tjs-lang 0.6.44 → 0.7.3

package/docs/README.md

@@ -10,46 +10,47 @@ ASTs that run sandboxed with fuel (gas) limits.
 
 | Guide | Description |
 |-------|-------------|
-| [TJS Language Guide](../DOCS-TJS.md) | Complete TJS language reference |
-| [AJS Runtime Guide](../DOCS-AJS.md) | Agent language and VM documentation |
-| [TJS for TypeScript Developers](../TJS-FOR-TS.md) | Coming from TypeScript? Start here |
-| [TJS for JavaScript Developers](../TJS-FOR-JS.md) | Coming from JavaScript? Start here |
+| [TJS Language Guide](https://github.com/tonioloewald/tjs-lang/blob/main/DOCS-TJS.md) | Complete TJS language reference |
+| [AJS Runtime Guide](https://github.com/tonioloewald/tjs-lang/blob/main/DOCS-AJS.md) | Agent language and VM documentation |
+| [TJS for TypeScript Developers](https://github.com/tonioloewald/tjs-lang/blob/main/TJS-FOR-TS.md) | Coming from TypeScript? Start here |
+| [TJS for JavaScript Developers](https://github.com/tonioloewald/tjs-lang/blob/main/TJS-FOR-JS.md) | Coming from JavaScript? Start here |
 
 ## Architecture & Design
 
 | Document | Description |
 |----------|-------------|
-| [Technical Context](../CONTEXT.md) | Architecture deep dive, design decisions |
-| [Design Patterns](../guides/patterns.md) | Common patterns in TJS and AJS |
-| [Schema Validation](../guides/tosijs-schema.md) | Working with tosijs-schema |
+| [Technical Context](https://github.com/tonioloewald/tjs-lang/blob/main/CONTEXT.md) | Architecture deep dive, design decisions |
+| [WASM Quick Start](https://github.com/tonioloewald/tjs-lang/blob/main/docs/WASM-QUICKSTART.md) | Build WASM-accelerated libraries with zero toolchain setup |
+| [Design Patterns](https://github.com/tonioloewald/tjs-lang/blob/main/guides/patterns.md) | Common patterns in TJS and AJS |
+| [Schema Validation](https://github.com/tonioloewald/tjs-lang/blob/main/guides/tosijs-schema.md) | Working with tosijs-schema |
 
 ## Examples
 
 Interactive examples are available in the [TJS Playground](https://tjs-platform.web.app).
 
-Source code for all examples lives in [`guides/examples/`](../guides/examples/):
+Source code for all examples lives in [`guides/examples/`](https://github.com/tonioloewald/tjs-lang/tree/main/guides/examples):
 
-- **TJS examples** — [`guides/examples/tjs/`](../guides/examples/tjs/) (type annotations, classes, WASM, etc.)
-- **AJS examples** — [`guides/examples/ajs/`](../guides/examples/ajs/) (agents, LLM, APIs, etc.)
+- **TJS examples** — [`guides/examples/tjs/`](https://github.com/tonioloewald/tjs-lang/tree/main/guides/examples/tjs) (type annotations, classes, WASM, etc.)
+- **AJS examples** — [`guides/examples/ajs/`](https://github.com/tonioloewald/tjs-lang/tree/main/guides/examples/ajs) (agents, LLM, APIs, etc.)
 
 Key examples:
 
 | Example | Description |
 |---------|-------------|
-| [TJS Grammar Reference](../guides/examples/tjs/tjs-grammar-demo.md) | Comprehensive TJS feature demo |
-| [Hello TJS](../guides/examples/tjs/hello-tjs.md) | Getting started with TJS |
-| [Full-Stack Demo](../guides/examples/tjs/full-stack-demo-user-service.md) | User service with runtime validation |
-| [WASM Starfield](../guides/examples/tjs/wasm-starfield.md) | SIMD-accelerated particle system with mouse steering |
-| [WASM Vector Search](../guides/examples/tjs/wasm-vector-search.md) | SIMD cosine similarity benchmark vs JS scalar |
+| [TJS Grammar Reference](https://github.com/tonioloewald/tjs-lang/blob/main/guides/examples/tjs/tjs-grammar-demo.md) | Comprehensive TJS feature demo |
+| [Hello TJS](https://github.com/tonioloewald/tjs-lang/blob/main/guides/examples/tjs/hello-tjs.md) | Getting started with TJS |
+| [Full-Stack Demo](https://github.com/tonioloewald/tjs-lang/blob/main/guides/examples/tjs/full-stack-demo-user-service.md) | User service with runtime validation |
+| [WASM Starfield](https://github.com/tonioloewald/tjs-lang/blob/main/guides/examples/tjs/wasm-starfield.md) | SIMD-accelerated particle system with mouse steering |
+| [WASM Vector Search](https://github.com/tonioloewald/tjs-lang/blob/main/guides/examples/tjs/wasm-vector-search.md) | SIMD cosine similarity benchmark vs JS scalar |
 
 ## Additional Resources
 
 | Resource | Description |
 |----------|-------------|
-| [Roadmap](../PLAN.md) | Project roadmap and planned features |
-| [TODO](../TODO.md) | Current task list |
-| [Benchmarks](../guides/benchmarks.md) | Performance benchmarks |
-| [CLAUDE.md](../CLAUDE.md) | AI assistant instructions for this codebase |
+| [Roadmap](https://github.com/tonioloewald/tjs-lang/blob/main/PLAN.md) | Project roadmap and planned features |
+| [TODO](https://github.com/tonioloewald/tjs-lang/blob/main/TODO.md) | Current task list |
+| [Benchmarks](https://github.com/tonioloewald/tjs-lang/blob/main/guides/benchmarks.md) | Performance benchmarks |
+| [CLAUDE.md](https://github.com/tonioloewald/tjs-lang/blob/main/CLAUDE.md) | AI assistant instructions for this codebase |
 
 ## npm Package
 
@@ -61,4 +62,4 @@ npm install tjs-lang
 import { Agent, AgentVM, ajs, tjs } from 'tjs-lang'
 ```
 
-See the [main README](../README.md) for installation and quick start.
+See the [main README](https://github.com/tonioloewald/tjs-lang#readme) for installation and quick start.

package/docs/WASM-QUICKSTART.md

@@ -0,0 +1,283 @@
+# WASM Quick Start
+
+**Build WASM-accelerated libraries in TJS with zero toolchain setup.**
+
+No Emscripten. No Rust. No `.wasm` files. No webpack plugins. Write WASM inline,
+get compiled bytecode embedded in your JavaScript output. Ship one `.js` file.
+
+## Why TJS for WASM?
+
+The traditional WASM workflow:
+
+1. Install a C/Rust/Go toolchain
+2. Write code in a separate language
+3. Compile to `.wasm` (configure build system)
+4. Load the `.wasm` file at runtime (async, CORS, bundler config)
+5. Marshal data between JS and WASM heaps (manual, error-prone)
+6. Ship multiple files
+
+The TJS workflow:
+
+1. Write `wasm { }` inside your function
+2. Run `tjs emit myfile.tjs`
+3. Ship the output `.js`
+
+That's it. The compiler handles bytecode generation, base64 embedding, memory
+management, and typed array marshaling. Your output is a single self-contained
+JavaScript file.
+
+## Your First WASM Block
+
+```tjs
+function add(! a: 0, b: 0):! 0 {
+  return wasm {
+    a + b
+  } fallback {
+    return a + b
+  }
+}
+
+console.log(add(3, 4))  // 7 — computed in WASM
+```
+
+**What's happening:**
+
+- `wasm { }` — JS-like syntax compiled to WASM bytecode at transpile time
+- `fallback { }` — JS fallback if WASM isn't available (e.g., older runtimes)
+- `!` — unsafe marker, skips runtime type checking for speed
+- `:!` — assert-returns, the return type contract
+
+Run it:
+
+```bash
+bun src/cli/tjs.ts run myfile.tjs
+```
+
+Or emit standalone JS:
+
+```bash
+bun src/cli/tjs.ts emit myfile.tjs > myfile.js
+node myfile.js  # works anywhere — WASM is embedded as base64
+```
+
+## What the Compiler Produces
+
+For the `add` function above, `tjs emit` generates something like:
+
+```javascript
+/**
+ * WASM: __tjs_wasm_0
+ * (func $compute (param $a f64) (param $b f64) (result f64)
+ *   local.get 0
+ *   local.get 1
+ *   f64.add
+ * )
+ */
+;(async()=>{
+  // ... base64 decode, instantiate, register globalThis.__tjs_wasm_0
+})();
+
+function add(a, b) {
+  // calls __tjs_wasm_0(a, b) with fallback
+}
+```
+
+The WAT (WebAssembly Text) is included as a comment so you can inspect what was
+compiled. The binary is embedded as base64 — no external files.
+
+## Numeric Types
+
+WASM blocks infer types from TJS parameter annotations:
+
+| TJS annotation | WASM type | Example |
+|---------------|-----------|---------|
+| `0` | `i32` (integer) | `function f(x: 0)` |
+| `0.0` | `f64` (float) | `function f(x: 0.0)` |
+| `+0` | `i32` (non-negative) | `function f(x: +0)` |
+| `Float32Array` | `i32` (pointer) | `function f(arr: Float32Array, len: 0)` |
+
+Integers use `i32`, floats use `f64`. Typed arrays are passed as memory pointers
+(the compiler handles marshaling automatically).
+
+## SIMD: 4x Throughput
+
+Process 4 float32 values per instruction using `f32x4_*` intrinsics:
+
+```tjs
+function scale(! arr: Float32Array, len: 0, factor: 0.0) {
+  wasm {
+    let s = f32x4_splat(factor)
+    for (let i = 0; i < len; i += 4) {
+      let off = i * 4
+      let v = f32x4_load(arr, off)
+      f32x4_store(arr, off, f32x4_mul(v, s))
+    }
+  } fallback {
+    for (let i = 0; i < len; i++) arr[i] *= factor
+  }
+}
+
+const data = new Float32Array([1, 2, 3, 4, 5, 6, 7, 8])
+scale(data, 8, 10.0)
+console.log(Array.from(data))  // [10, 20, 30, 40, 50, 60, 70, 80]
+```
+
+### Available SIMD Intrinsics
+
+| Intrinsic | Operation |
+|-----------|-----------|
+| `f32x4_load(arr, byteOffset)` | Load 4 floats from memory |
+| `f32x4_store(arr, byteOffset, vec)` | Store 4 floats to memory |
+| `f32x4_splat(value)` | Fill all 4 lanes with one value |
+| `f32x4_add(a, b)` | Lane-wise addition |
+| `f32x4_sub(a, b)` | Lane-wise subtraction |
+| `f32x4_mul(a, b)` | Lane-wise multiplication |
+| `f32x4_div(a, b)` | Lane-wise division |
+| `f32x4_neg(v)` | Negate all lanes |
+| `f32x4_sqrt(v)` | Square root of all lanes |
+| `f32x4_extract_lane(vec, N)` | Get one float (lane 0-3) |
+| `f32x4_replace_lane(vec, N, val)` | Set one float in lane |
+
+These map directly to WASM SIMD opcodes — no auto-vectorization, no surprises.
+
+## Memory Management
+
+### Regular typed arrays: automatic copy
+
+Pass a normal `Float32Array` and TJS copies it into WASM memory before the call,
+copies results back after. Zero effort:
+
+```tjs
+function double(! arr: Float32Array, len: 0) {
+  wasm {
+    for (let i = 0; i < len; i += 4) {
+      let off = i * 4
+      let v = f32x4_load(arr, off)
+      f32x4_store(arr, off, f32x4_add(v, v))
+    }
+  } fallback {
+    for (let i = 0; i < len; i++) arr[i] *= 2
+  }
+}
+
+const data = new Float32Array([1, 2, 3, 4])
+double(data, 4)
+// data is [2, 4, 6, 8] — copy-out happened automatically
+```
+
+### `wasmBuffer()`: zero-copy shared memory
+
+For hot paths with large arrays, eliminate the copy overhead:
+
+```tjs
+const positions = wasmBuffer(Float32Array, 100000)
+
+// JS writes directly to WASM memory
+for (let i = 0; i < 100000; i++) positions[i] = Math.random()
+
+// WASM reads/writes the same memory — no copy
+function process(! arr: Float32Array, len: 0, delta: 0.0) {
+  wasm {
+    let vd = f32x4_splat(delta)
+    for (let i = 0; i < len; i += 4) {
+      let off = i * 4
+      f32x4_store(arr, off, f32x4_add(f32x4_load(arr, off), vd))
+    }
+  } fallback {
+    for (let i = 0; i < len; i++) arr[i] += delta
+  }
+}
+
+process(positions, 100000, 0.01)
+// JS sees mutations immediately — same backing memory
+```
+
+**How it works:** All WASM blocks in a file share one `WebAssembly.Memory` (64MB).
+`wasmBuffer` is a bump allocator that hands out views into this memory. When a
+typed array's `.buffer === wasmMemory.buffer`, the wrapper skips the copy and
+passes the byte offset directly.
+
+**Supported types:** `Float32Array`, `Float64Array`, `Int32Array`, `Uint8Array`
+
+**Trade-off:** `wasmBuffer` allocations are permanent (bump allocator, no free).
+Use them for long-lived buffers, not temporary scratch space.
+
+## Patterns
+
+### Dot product (horizontal SIMD reduction)
+
+```tjs
+function dot(! a: Float32Array, b: Float32Array, len: 0):! 0.0 {
+  return wasm {
+    let acc = f32x4_splat(0.0)
+    for (let i = 0; i < len; i += 4) {
+      let off = i * 4
+      acc = f32x4_add(acc, f32x4_mul(f32x4_load(a, off), f32x4_load(b, off)))
+    }
+    f32x4_extract_lane(acc, 0) + f32x4_extract_lane(acc, 1)
+      + f32x4_extract_lane(acc, 2) + f32x4_extract_lane(acc, 3)
+  } fallback {
+    let sum = 0
+    for (let i = 0; i < len; i++) sum += a[i] * b[i]
+    return sum
+  }
+}
+```
+
+### Normalize array to [0, 1]
+
+```tjs
+function normalize(! arr: Float32Array, len: 0) {
+  wasm {
+    let max = 0.0
+    for (let i = 0; i < len; i++) {
+      let off = i * 4
+      let v = f32x4_extract_lane(f32x4_load(arr, off), 0)
+      if (v > max) { max = v }
+    }
+    if (max > 0.0) {
+      let inv = f32x4_splat(1.0 / max)
+      for (let i = 0; i < len; i += 4) {
+        let off = i * 4
+        f32x4_store(arr, off, f32x4_mul(f32x4_load(arr, off), inv))
+      }
+    }
+  } fallback {
+    let max = 0
+    for (let i = 0; i < len; i++) if (arr[i] > max) max = arr[i]
+    if (max > 0) for (let i = 0; i < len; i++) arr[i] /= max
+  }
+}
+```
+
+## Tips
+
+- **Always provide a `fallback`** — it's your safety net and makes code testable
+  without WASM
+- **Use `!` (unsafe) on WASM functions** — type checking overhead defeats the
+  purpose of dropping to WASM
+- **Align to 4 elements** for SIMD — `f32x4` processes 4 floats at a time; pad
+  arrays to multiples of 4
+- **Use `wasmBuffer` for hot loops** — the copy overhead of regular arrays can
+  negate WASM's speed advantage for large data
+- **WASM blocks share memory per file** — all blocks in one `.tjs` file use the
+  same 64MB `WebAssembly.Memory`
+- **Check the WAT comments** — the compiler includes human-readable WAT in the
+  output so you can verify what was compiled
+
+## Limitations
+
+- No function calls inside WASM blocks (only intrinsics and arithmetic)
+- No imports/exports beyond the function itself
+- `wasmBuffer` allocations are permanent (bump allocator)
+- Array lengths must be multiples of 4 for SIMD operations
+- SIMD is f32 only (f32x4) — no i32x4, f64x2, etc. yet
+
+## Next Steps
+
+- **[WASM Basics](https://github.com/tonioloewald/tjs-lang/blob/main/guides/examples/tjs/wasm-basics.md)** — Runnable examples: integer math, floats, array processing
+- **[WASM SIMD](https://github.com/tonioloewald/tjs-lang/blob/main/guides/examples/tjs/wasm-simd.md)** — SIMD patterns: scale, dot product, benchmarking
+- **[WASM Memory](https://github.com/tonioloewald/tjs-lang/blob/main/guides/examples/tjs/wasm-memory.md)** — Data marshaling deep dive, `wasmBuffer()` patterns
+- **[WASM Starfield](https://github.com/tonioloewald/tjs-lang/blob/main/guides/examples/tjs/wasm-starfield.md)** — Full demo: 50K SIMD-accelerated particles
+- **[WASM Vector Search](https://github.com/tonioloewald/tjs-lang/blob/main/guides/examples/tjs/wasm-vector-search.md)** — Benchmark: SIMD cosine similarity vs JS scalar
+- **[TJS Language Guide — WASM section](https://github.com/tonioloewald/tjs-lang/blob/main/DOCS-TJS.md)** — Complete language reference

package/docs/diagrams/architecture-shift.svg

@@ -0,0 +1,117 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 680 400" font-family="system-ui, -apple-system, sans-serif">
+  <style>
+    /* TJS Brand Palette */
+    .bg { fill: #fafafa; stroke: #e4e4e4; }
+
+    .section-old { fill: white; stroke: #ff1c24; stroke-width: 1.5; }
+    .section-new { fill: white; stroke: #006736; stroke-width: 1.5; }
+    .section-old-header { fill: #fff3f3; }
+    .section-new-header { fill: #f0fff5; }
+
+    .section-label-old { fill: #ff1c24; font-size: 13px; font-weight: 700; }
+    .section-label-new { fill: #006736; font-size: 13px; font-weight: 700; }
+
+    .node { fill: #f5f5f5; stroke: #9e9e9e; stroke-width: 1.5; }
+    .node-edge { fill: #eef6ff; stroke: #3da8f4; stroke-width: 1.5; }
+    .node-text { fill: #444; font-size: 14px; font-weight: 500; }
+    .node-text-edge { fill: #1a6ab5; font-size: 14px; font-weight: 600; }
+
+    .arrow-fwd { stroke: #9e9e9e; stroke-width: 1.5; fill: none; }
+    .arrow-ret-bad { stroke: #ff1c24; stroke-width: 1.5; fill: none; }
+    .arrow-good { stroke: #006736; stroke-width: 1.5; fill: none; }
+
+    .lbl-fwd { fill: #888; font-size: 10px; }
+    .lbl-ret-bad { fill: #ff1c24; font-size: 10px; font-weight: 600; }
+    .lbl-good { fill: #006736; font-size: 10px; font-weight: 500; }
+    .lbl-ret-good { fill: #006736; font-size: 10px; font-weight: 600; }
+
+    .callout-bad { fill: #fff3f3; stroke: #ff1c24; stroke-dasharray: 4 3; }
+    .callout-good { fill: #f0fff5; stroke: #006736; stroke-dasharray: 4 3; }
+    .callout-text-bad { fill: #ff1c24; font-size: 11px; }
+    .callout-text-good { fill: #006736; font-size: 11px; }
+
+    .shadow { filter: drop-shadow(0 2px 3px rgba(0,0,0,0.1)); }
+
+    .ah { fill: #9e9e9e; }
+    .ah-bad { fill: #ff1c24; }
+    .ah-good { fill: #006736; }
+  </style>
+
+  <defs>
+    <marker id="a" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10z" class="ah"/>
+    </marker>
+    <marker id="ab" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10z" class="ah-bad"/>
+    </marker>
+    <marker id="ag" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10z" class="ah-good"/>
+    </marker>
+  </defs>
+
+  <rect width="680" height="400" rx="12" class="bg"/>
+
+  <!-- OLD WAY -->
+  <g class="shadow">
+    <rect x="20" y="16" width="640" height="170" rx="8" class="section-old"/>
+  </g>
+  <rect x="20" y="16" width="640" height="32" rx="8" class="section-old-header"/>
+  <rect x="20" y="36" width="640" height="12" class="section-old-header"/>
+  <text x="40" y="38" class="section-label-old">OLD WAY: Data-to-Code</text>
+
+  <rect x="50" y="70" width="120" height="50" rx="8" class="node"/>
+  <text x="110" y="100" text-anchor="middle" class="node-text">Client</text>
+
+  <rect x="280" y="70" width="120" height="50" rx="8" class="node"/>
+  <text x="340" y="100" text-anchor="middle" class="node-text">Server</text>
+
+  <rect x="510" y="70" width="120" height="50" rx="8" class="node"/>
+  <text x="570" y="100" text-anchor="middle" class="node-text">Database</text>
+
+  <line x1="170" y1="85" x2="275" y2="85" class="arrow-fwd" marker-end="url(#a)"/>
+  <text x="222" y="78" text-anchor="middle" class="lbl-fwd">request</text>
+
+  <line x1="400" y1="85" x2="505" y2="85" class="arrow-fwd" marker-end="url(#a)"/>
+  <text x="452" y="78" text-anchor="middle" class="lbl-fwd">fetch 100 rows</text>
+
+  <line x1="505" y1="105" x2="400" y2="105" class="arrow-ret-bad" marker-end="url(#ab)"/>
+  <text x="452" y="118" text-anchor="middle" class="lbl-ret-bad">100 rows</text>
+
+  <line x1="275" y1="105" x2="170" y2="105" class="arrow-ret-bad" marker-end="url(#ab)"/>
+  <text x="222" y="118" text-anchor="middle" class="lbl-ret-bad">5 rows</text>
+
+  <rect x="170" y="140" width="330" height="28" rx="14" class="callout-bad"/>
+  <text x="335" y="158" text-anchor="middle" class="callout-text-bad">High latency. High bandwidth. Validate at every layer.</text>
+
+  <!-- TJS WAY -->
+  <g class="shadow">
+    <rect x="20" y="210" width="640" height="174" rx="8" class="section-new"/>
+  </g>
+  <rect x="20" y="210" width="640" height="32" rx="8" class="section-new-header"/>
+  <rect x="20" y="230" width="640" height="12" class="section-new-header"/>
+  <text x="40" y="232" class="section-label-new">TJS WAY: Code-to-Data</text>
+
+  <rect x="50" y="264" width="120" height="50" rx="8" class="node"/>
+  <text x="110" y="294" text-anchor="middle" class="node-text">Client</text>
+
+  <rect x="280" y="264" width="120" height="50" rx="8" class="node-edge"/>
+  <text x="340" y="294" text-anchor="middle" class="node-text-edge">Edge</text>
+
+  <rect x="510" y="264" width="120" height="50" rx="8" class="node"/>
+  <text x="570" y="294" text-anchor="middle" class="node-text">Database</text>
+
+  <line x1="170" y1="279" x2="275" y2="279" class="arrow-good" marker-end="url(#ag)"/>
+  <text x="222" y="272" text-anchor="middle" class="lbl-good">send agent</text>
+
+  <line x1="400" y1="279" x2="505" y2="279" class="arrow-good" marker-end="url(#ag)"/>
+  <text x="452" y="272" text-anchor="middle" class="lbl-good">run at data</text>
+
+  <line x1="505" y1="299" x2="400" y2="299" class="arrow-good" marker-end="url(#ag)"/>
+  <text x="452" y="312" text-anchor="middle" class="lbl-ret-good">5 rows</text>
+
+  <line x1="275" y1="299" x2="170" y2="299" class="arrow-good" marker-end="url(#ag)"/>
+  <text x="222" y="312" text-anchor="middle" class="lbl-ret-good">5 rows</text>
+
+  <rect x="170" y="334" width="330" height="28" rx="14" class="callout-good"/>
+  <text x="335" y="352" text-anchor="middle" class="callout-text-good">Low latency. Zero waste. Validate once.</text>
+</svg>

package/docs/diagrams/compile-runtime.svg

@@ -0,0 +1,130 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 660 420" font-family="system-ui, -apple-system, sans-serif">
+  <style>
+    /* TJS Brand Palette */
+    .bg { fill: #fafafa; stroke: #e4e4e4; }
+
+    .section-compile { fill: white; stroke: #3da8f4; stroke-width: 1.5; }
+    .section-runtime { fill: white; stroke: #181340; stroke-width: 1.5; }
+    .section-label-compile { fill: #3da8f4; font-size: 12px; font-weight: 700; letter-spacing: 1px; }
+    .section-label-runtime { fill: #181340; font-size: 12px; font-weight: 700; letter-spacing: 1px; }
+
+    .box-code { fill: #f8f8f8; stroke: #9e9e9e; }
+    .box-action { fill: #eef6ff; stroke: #3da8f4; stroke-width: 1.5; }
+    .box-error { fill: #fff3f3; stroke: #ff1c24; stroke-width: 1.5; }
+    .box-pass { fill: #f0fff5; stroke: #006736; stroke-width: 1.5; }
+    .box-metadata { fill: #f8f8f8; stroke: #9e9e9e; }
+
+    .diamond { fill: #fffbe6; stroke: #fdbe52; stroke-width: 1.5; }
+
+    .arrow { stroke: #9e9e9e; stroke-width: 1.5; fill: none; }
+    .arrow-pass { stroke: #006736; stroke-width: 1.5; fill: none; }
+    .arrow-fail { stroke: #ff1c24; stroke-width: 1.5; fill: none; }
+
+    .label { font-size: 13px; font-weight: 500; }
+    .label-sm { font-size: 11px; }
+    .label-xs { font-size: 9px; }
+    .label-mono { font-size: 11px; font-family: monospace; }
+    .label-mono-sm { font-size: 12px; font-family: monospace; }
+
+    .text-action { fill: #1a6ab5; }
+    .text-dark { fill: #444; }
+    .text-muted { fill: #999; }
+    .text-pass { fill: #006736; font-size: 10px; font-weight: 600; }
+    .text-fail { fill: #ff1c24; font-size: 10px; font-weight: 600; }
+    .text-error { fill: #cc1118; }
+
+    .shadow { filter: drop-shadow(0 2px 3px rgba(0,0,0,0.1)); }
+
+    .arrowhead { fill: #9e9e9e; }
+    .arrowhead-pass { fill: #006736; }
+    .arrowhead-fail { fill: #ff1c24; }
+  </style>
+
+  <defs>
+    <marker id="arr" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10z" class="arrowhead"/>
+    </marker>
+    <marker id="arr-pass" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10z" class="arrowhead-pass"/>
+    </marker>
+    <marker id="arr-fail" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10z" class="arrowhead-fail"/>
+    </marker>
+  </defs>
+
+  <rect width="660" height="420" rx="12" class="bg"/>
+
+  <!-- COMPILE TIME -->
+  <g id="section-compile" class="section shadow">
+    <rect x="20" y="16" width="620" height="140" rx="8" class="section-compile"/>
+  </g>
+  <text x="40" y="42" class="section-label-compile">COMPILE TIME</text>
+
+  <!-- Source code: two-line box, h=44 -->
+  <g id="node-source" class="node flow-step">
+    <rect x="40" y="56" width="200" height="44" rx="6" class="box-code"/>
+    <text x="140" y="75" text-anchor="middle" class="label-mono text-dark">greet(name: 'World')</text>
+    <text x="140" y="90" text-anchor="middle" class="label-xs text-muted">source</text>
+  </g>
+
+  <line x1="245" y1="78" x2="290" y2="78" class="arrow connector" marker-end="url(#arr)"/>
+
+  <g id="node-parse" class="node flow-step">
+    <rect x="295" y="60" width="100" height="36" rx="6" class="box-action"/>
+    <text x="345" y="83" text-anchor="middle" class="label text-action">Parse</text>
+  </g>
+
+  <line x1="400" y1="78" x2="445" y2="78" class="arrow connector" marker-end="url(#arr)"/>
+
+  <!-- Extract type: two-line box, h=44 -->
+  <g id="node-extract" class="node flow-step">
+    <rect x="450" y="56" width="170" height="44" rx="6" class="box-action"/>
+    <text x="535" y="75" text-anchor="middle" class="label text-action">Extract type</text>
+    <text x="535" y="90" text-anchor="middle" class="label-xs text-action">name = string</text>
+  </g>
+
+  <!-- Arrow between sections -->
+  <line x1="330" y1="156" x2="330" y2="194" class="arrow connector" marker-end="url(#arr)"/>
+
+  <!-- RUNTIME — expanded to h=210 -->
+  <g id="section-runtime" class="section shadow">
+    <rect x="20" y="198" width="620" height="210" rx="8" class="section-runtime"/>
+  </g>
+  <text x="40" y="224" class="section-label-runtime">RUNTIME</text>
+
+  <g id="node-metadata" class="node">
+    <rect x="40" y="238" width="280" height="34" rx="6" class="box-metadata"/>
+    <text x="180" y="260" text-anchor="middle" class="label-mono text-dark">greet.__tjs = { params: { name: ... } }</text>
+  </g>
+
+  <g id="node-call" class="node">
+    <rect x="40" y="292" width="140" height="34" rx="6" class="box-error"/>
+    <text x="110" y="314" text-anchor="middle" class="label-mono-sm text-error">greet(123)</text>
+  </g>
+
+  <line x1="185" y1="309" x2="230" y2="309" class="arrow connector" marker-end="url(#arr)"/>
+
+  <!-- Diamond -->
+  <g id="gate-type-check" class="gate">
+    <polygon points="310,286 374,309 310,332 246,309" class="diamond"/>
+    <text x="310" y="313" text-anchor="middle" fill="#8b6914" font-size="12" class="label">Type Check</text>
+  </g>
+
+  <!-- Pass -->
+  <line x1="374" y1="309" x2="424" y2="309" class="arrow-pass connector" marker-end="url(#arr-pass)"/>
+  <text x="399" y="301" text-anchor="middle" class="text-pass">Pass</text>
+
+  <g id="node-execute" class="node outcome-pass">
+    <rect x="429" y="293" width="100" height="34" rx="6" class="box-pass"/>
+    <text x="479" y="314" text-anchor="middle" class="label" fill="#005028">Execute</text>
+  </g>
+
+  <!-- Fail -->
+  <line x1="310" y1="332" x2="310" y2="358" class="arrow-fail connector" marker-end="url(#arr-fail)"/>
+  <text x="330" y="350" class="text-fail">Fail</text>
+
+  <g id="node-error" class="node outcome-fail">
+    <rect x="225" y="362" width="170" height="34" rx="6" class="box-error"/>
+    <text x="310" y="383" text-anchor="middle" class="label-sm text-error">MonadicError (no throw)</text>
+  </g>
+</svg>

package/docs/diagrams/icon-riff-1.svg

@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Riff 1: "The Aware Runtime" — owl face as a live terminal/monitor
+     The screen shows -> (the TJS return type arrow), suggesting the owl
+     IS the runtime. Eyes are active. Blue sky palette from the animation. -->
+<svg viewBox="0 0 48 48" width="48" height="48" xmlns="http://www.w3.org/2000/svg">
+  <style>
+    .bg { fill: #3da8f4; }
+    .screen { fill: #ffffff; stroke: #000; stroke-width: 2; stroke-linejoin: round; stroke-linecap: round; }
+    .outline { fill: none; stroke: #000; stroke-width: 2; stroke-linejoin: round; stroke-linecap: round; }
+    .wing { fill: #9e9e9e; stroke: #000; stroke-width: 2; stroke-linejoin: round; stroke-linecap: round; }
+    .body { fill: #e4e4e4; stroke: #000; stroke-width: 2; stroke-linejoin: round; stroke-linecap: round; }
+    .feet { fill: none; stroke: #000; stroke-width: 2; stroke-linejoin: round; stroke-linecap: round; }
+    .eye { fill: #006736; stroke: #000; stroke-width: 1.5; stroke-linecap: round; }
+    .symbol { fill: none; stroke: #006736; stroke-width: 2; stroke-linecap: round; stroke-linejoin: round; }
+    .cloud { fill: rgba(255,255,255,0.85); }
+  </style>
+
+  <!-- Background: blue sky -->
+  <rect width="48" height="48" rx="8" class="bg"/>
+
+  <!-- Small cloud bottom-left (from platform icon) -->
+  <ellipse cx="8" cy="43" rx="7" ry="4" class="cloud"/>
+  <ellipse cx="15" cy="44" rx="5" ry="3" class="cloud"/>
+
+  <!-- Left wing -->
+  <path d="M7.5,16 C4.5,16,2,18.5,2,21.5 C2,24,4,26,6.5,26 L6.6,26 C7.4,26,8,26.6,8,27.4 C8,29.9,10.1,32,12.6,32 L16,32 C18.6,32,20.7,29.9,20.7,27.3 L20.7,21.4 C20.7,18.4,18.3,16,15.3,16 Z" class="wing"/>
+
+  <!-- Right wing -->
+  <path d="M40.5,16 C43.5,16,46,18.5,46,21.5 C46,24,44,26,41.5,26 L41.4,26 C40.6,26,40,26.6,40,27.4 C40,29.9,37.9,32,35.4,32 L32,32 C29.4,32,27.3,29.9,27.3,27.3 L27.3,21.4 C27.3,18.4,29.7,16,32.7,16 Z" class="wing"/>
+
+  <!-- Body -->
+  <path d="M17,29 L33,29 C33,34.5,28.5,39,23,39 C19.7,39,17,36.3,17,33 Z" class="body"/>
+
+  <!-- Feet -->
+  <path d="M20,43 L18,41 L16,43" class="feet"/>
+  <path d="M32,43 L30,41 L28,43" class="feet"/>
+
+  <!-- Rain lines (subtle, from animation) -->
+  <path d="M35,35 L32.2,35 L32.2,37.8" class="feet"/>
+  <path d="M31,39 L28.2,39 L28.2,41.8" class="feet"/>
+
+  <!-- Head/Screen -->
+  <rect x="6" y="6" width="30" height="23" rx="4" class="screen"/>
+
+  <!-- Divider line (nose) -->
+  <line x1="21" y1="11" x2="21" y2="23" class="outline"/>
+
+  <!-- Eyes: green rectangles (like code blocks / the runtime watching) -->
+  <rect x="10" y="13" width="7" height="6" rx="1.5" class="eye"/>
+  <rect x="25" y="13" width="7" height="6" rx="1.5" class="eye"/>
+
+  <!-- TJS arrow symbol on forehead area -->
+  <path d="M15,9 L19,9" class="symbol"/>
+  <path d="M17.5,7.5 L19,9 L17.5,10.5" class="symbol"/>
+</svg>