types

AGENTS.md

@@ -25,14 +25,17 @@ reichard.io/poiesis/
 ├── internal/
 │   ├── runtime/              # Runtime management, transpilation, execution
 │   │   ├── runtime.go
-│   │   └── runtime_test.go
+│   │   ├── runtime_test.go
+│   │   └── options.go
 │   ├── functions/            # Function registration framework
-│   │   ├── collector.go
 │   │   ├── registry.go
 │   │   ├── types.go
-│   │   ├── typescript.go
 │   │   ├── typescript_test.go
 │   │   └── functions_test.go
+│   ├── tsconvert/            # Go-to-TypeScript type conversion utilities
+│   │   ├── convert.go
+│   │   ├── types.go
+│   │   └── convert_test.go
 │   └── stdlib/               # Standard library implementations
 │       ├── fetch.go
 │       └── fetch_test.go
@@ -40,8 +43,9 @@ reichard.io/poiesis/
 
 ## Key Packages
 
-- `reichard.io/poiesis/internal/runtime` - Runtime management, TypeScript transpilation, JavaScript execution
-- `reichard.io/poiesis/internal/functions` - Generic function registration framework (sync/async wrappers, automatic JS/Go conversion via JSON, type definition generation)
+- `reichard.io/poiesis/internal/runtime` - Runtime management, TypeScript transpilation, JavaScript execution, per-runtime type management
+- `reichard.io/poiesis/internal/functions` - Generic function registration framework (sync/async wrappers, automatic JS/Go conversion via JSON)
+- `reichard.io/poiesis/internal/tsconvert` - Go-to-TypeScript type conversion utilities and type declaration generation
 - `reichard.io/poiesis/internal/stdlib` - Standard library implementations (fetch)
 
 ## Function System
@@ -49,6 +53,7 @@ reichard.io/poiesis/
 ### Registration
 
 Two types of functions:
+
 - **Sync**: `RegisterFunction[T, R](name, fn)` - executes synchronously, returns value
 - **Async**: `RegisterAsyncFunction[T, R](name, fn)` - runs in goroutine, returns Promise
 
@@ -108,3 +113,26 @@ functions.RegisterAsyncFunction[FetchArgs, *FetchResult]("fetch", Fetch)
 - Use `os` package instead of deprecated `io/ioutil`
 - Error logging uses `_, _ = fmt.Fprintf(stderr, ...)` pattern
 - Package structure follows standard Go project layout with internal packages
+
+### Comment Style
+
+Code blocks (even within functions) should be separated with title-cased comments describing what the block does:
+
+```go
+// Create Runtime
+r := &Runtime{opts: qjs.Option{Context: ctx}}
+
+// Create QuickJS Context
+rt, err := qjs.New(r.opts)
+
+// Populate Globals
+if err := r.populateGlobals(); err != nil {
+    return nil, err
+}
+```
+
+For more complex blocks, use a hyphen to add elaboration:
+
+```go
+// Does Thing - We do this here because we need to do xyz...
+```