jz 0.5.1 → 0.7.0

package/README.md

@@ -1,39 +1,33 @@
 <img src="jz.svg" alt="jz logo" width="120"/>
 
+![stability](https://img.shields.io/badge/stability-experimental-black) [![npm](https://img.shields.io/npm/v/jz?color=black)](http://npmjs.org/package/jz) [![test](https://github.com/dy/jz/actions/workflows/test.yml/badge.svg)](https://github.com/dy/jz/actions/workflows/test.yml) [![bench](https://github.com/dy/jz/actions/workflows/bench.yml/badge.svg)](https://github.com/dy/jz/actions/workflows/bench.yml)
 
-
-## ![stability](https://img.shields.io/badge/stability-experimental-black) [![npm](https://img.shields.io/npm/v/jz?color=black)](http://npmjs.org/jz) [![test](https://github.com/dy/jz/actions/workflows/test.yml/badge.svg)](https://github.com/dy/jz/actions/workflows/test.yml) [![test262](https://github.com/dy/jz/actions/workflows/test262.yml/badge.svg)](https://github.com/dy/jz/actions/workflows/test262.yml) [![bench](https://github.com/dy/jz/actions/workflows/bench.yml/badge.svg)](https://github.com/dy/jz/actions/workflows/bench.yml)
-
-
-**JZ** (_javascript zero_) is a **minimal modern functional JS subset** that compiles to WASM.<br>
+**jz** (_javascript zero_) is **minimal functional JS** that compiles to performant WASM.
 
 ```js
 import jz from 'jz'
 
-// Distance between two points
 const { exports: { dist } } = jz`export let dist = (x, y) => (x*x + y*y) ** 0.5`
 dist(3, 4) // 5
 ```
 
-## Why?
+**[repl](https://dy.github.io/jz/repl/)** · **[floatbeat](https://dy.github.io/jz/floatbeat/)** · **[examples](https://dy.github.io/jz/examples/)** · **[bench](https://dy.github.io/jz/bench/)**
+
 
-**Write plain JS, compile to WASM** — fast, portable and long-lasting.<br>
-JZ distills modern JS to its functional core — the "good parts" ([Crockford](https://www.youtube.com/watch?v=_DKkVvOt6dk)) — without the legacy semantics, feature bloat, and perf quirks.
+## Why?
 
-* **Static AOT** – no runtime, no GC, no dynamic constructs.
-* **Valid jz = valid js** — test in browser, compile to wasm.
-* **Minimal** — output is close to hand-written WAT; CI gates it to stay at least as small and fast as AssemblyScript and Porffor on the bench corpus ([CONTRIBUTING](CONTRIBUTING.md#performance--size-invariant)).
-<!-- * **Realtime** — compiles faster than `eval`, useful for live-coding and REPL. -->
+JZ distills **"the good parts"** ([Crockford](https://www.youtube.com/watch?v=_DKkVvOt6dk)) and **compiles JS ahead-of-time to WASM**: no runtime, no GC, no legacy, no spec creep, near-native perf with unlocked SIMD. **Valid JZ is valid JS** – run and test as JS, compile to WASM.
 
-| Good for                    | Not for                    |
-|-----------------------------|----------------------------|
-| Numeric / math compute      | UI / frontend              |
-| DSP / audio / bytebeats     | Backend / APIs             |
-| Parsing / transforms        | Async / I/O-heavy logic    |
-| WASM utilities              | JavaScript runtime         |
+| Good for                     | Not for                   |
+|------------------------------|---------------------------|
+| DSP, audio, synthesis        | UI, DOM, the frontend     |
+| Image, video, pixels         | Servers, APIs, I/O        |
+| Simulation, physics, games   | Async, promises, events   |
+| Parsers, codecs, compression | Dynamic, polymorphic, OOP |
+| Scientific, numeric, ML      | Security crypto, big-ints |
+| Hashing, checksums, RNG      | Glue, plumbing, orchestration |
 
-<!-- Inspired by [porffor](https://github.com/CanadaHonk/porffor) and [piezo](https://github.com/dy/piezo). -->
-<!-- Used internally by: web-audio-api, color-space, audiojs -->
+Output `.wasm` is portable — run it in any host (browser, Node, Deno, edge, plugins), or take it native via [wasm2c](https://github.com/WebAssembly/wabt) (wasm → C → binary).
 
 
 ## Usage
@@ -41,18 +35,20 @@ JZ distills modern JS to its functional core — the "good parts" ([Crockford](h
 `npm install jz`
 
 ```js
-import jz, { compile } from 'jz'
+import jz, { compile, compileModule, instantiate } from 'jz'
 
-// Compile, instantiate
+// Compile + instantiate
 const { exports: { add } } = jz('export let add = (a, b) => a + b')
 add(2, 3)  // 5
 
-// Compile only — returns raw WASM binary (no JS adaptation)
+// Compile only — raw WASM binary
 const wasm = compile('export let f = (x) => x * 2')
-const mod = new WebAssembly.Module(wasm)
-const inst = new WebAssembly.Instance(mod)
 
-// Async WASM startup — jz source compilation is still synchronous
+// Compile once → instantiate many (pays the AOT + validate cost once)
+const mod = compileModule('export let f = (x) => x * 2')
+instantiate(mod).exports.f(21)  // 42 — repeat cheaply, no recompile
+
+// Async startup
 const asyncMod = await WebAssembly.compile(wasm)
 const asyncInst = await WebAssembly.instantiate(asyncMod)
 asyncInst.exports.f(21) // 42
@@ -65,17 +61,22 @@ Options are passed as `jz(source, opts)` or `compile(source, opts)`. Common ones
 
 | Option | Use |
 |---|---|
-| `jzify: true` | Accept broader JS patterns such as `var`, `function`, `switch`, `arguments`, `==`, `undefined`, and `class` (see *Not supported* below for the class subset) by lowering them to the JZ subset. The CLI auto-enables this for `.js` files. |
-| `modules: { specifier: source }` | Bundle static ES imports into one WASM module. CLI import resolution does this from files automatically. |
-| `imports: { mod: host }` | Wire host namespaces/functions used by `import { fn } from "mod"`; functions may be plain JS functions or `{ fn, returns }` specs. |
-| `memory` | Pass `memory: N` to create owned memory with `N` initial pages, or pass `memory: jz.memory()` / `WebAssembly.Memory` to share memory across modules. |
-| `host: 'js' \| 'wasi'` | Select runtime-service lowering. Default `js` uses small `env.*` imports auto-wired by `jz()`; `wasi` emits WASI Preview 1 imports for wasmtime/wasmer/deno. |
-| `optimize` | `false`/`0` disables optimization, `1` keeps cheap size passes, `true`/`2` is the default (every stable jz pass + full watr), `3` adds larger array/hash initial caps and inlines `f64.const` over mutable globals (trades size for speed). String aliases `'size'` (unroll/vectorize off, tight scalar caps — smallest wasm), `'balanced'` (= default), `'speed'` (full unroll + SIMD). Object form overrides individual passes/knobs (and accepts `level:` as a number or alias base). |
-| `strict: true` | Reject dynamic fallbacks such as unknown receiver method calls, `obj[k]`, and `for-in` instead of emitting JS-host dynamic dispatch. |
-| `alloc: false` | Omit raw allocator exports like `_alloc`/`_clear` when compiling standalone WASM that never marshals heap values across the host boundary. |
-| `wat: true` | `compile()` returns WAT text instead of a WASM binary. |
-| `profile` | Pass a mutable sink to collect compile-stage timings; set `profile.names = true` to also emit a WASM `name` section for profiler/debugger symbolication. |
-
+| `modules: { specifier: source }` | Static ES imports to bundle. CLI import resolution does this from files automatically. |
+| `imports: { mod: host }` | Host imports `import { fn } from "mod"`. |
+| `memory` | Pass `memory: N` for owned memory with `N` initial pages, or `memory: jz.memory()` / `WebAssembly.Memory` to share across modules. `maxMemory: N` caps growth; `importMemory: true` imports `env.memory` instead of exporting own. |
+| `host: 'js' \| 'wasi'` | Runtime-service lowering. Default `js`; `wasi` for standalone runtimes. |
+| `optimize` | `false`/`0` off, `1` minimal, `true`/`2` default (all stable passes), `3`/`'speed'` trades size for speed, `'size'` for smallest wasm. (Object form for per-pass overrides is internal/unstable.) |
+| `define` | Compile-time constants injected as top-level bindings, e.g. `{ DEBUG: false, PORT: 8080 }` (numbers, booleans, strings, null, or literal arrays/objects). |
+| `strict: true` | Enforce the pure canonical subset: skip jzify lowering (so `var`/`function`/`class`/`==`/… are rejected, not accepted) **and** reject dynamic fallbacks (`obj[k]`, `for-in`, unknown receiver methods). Off by default — broader JS is lowered automatically. |
+| `alloc: false` | Omit allocator exports (`_alloc`/`_clear`) for standalone modules that never marshal heap values. |
+| `noSimd: true` | Disable auto-vectorization (no jz-emitted `v128`) for engines without the SIMD proposal. Explicit `f32x4`/`i32x4` intrinsics still compile. |
+| `whyNotSimd: true` | Diagnostic (CLI `--why-not-simd`): emit a `simd-why-not` warning per loop the auto-vectorizer declined, naming the first blocking op — finds loops one op away from SIMD. Noisy; off by default. Surfaced via the `warnings` sink. |
+| `experimentalStencil: true` | Opt-in (CLI `--experimental-stencil`): vectorize neighbour-load stencils — `b[i] = f(a[i-1], a[i], a[i+1])` and 2-D 5-point sweeps — to f64x2. Bit-exact vs scalar (a lane-parallel map reorders nothing within a lane). Unstable / off by default until proven across the corpus. |
+| `experimentalOuterStrip: true` | Opt-in (CLI `--experimental-outer-strip`): strip-mine a pixel loop whose per-pixel value is an inner reduction (e.g. metaballs' field sum over blobs) into f64x2 — two adjacent pixels per step. Bit-exact vs scalar (each lane accumulates in scalar order). Unstable / off by default. |
+| `randomSeed` | `Math.random` seeding — default draws from host entropy (non-reproducible); a number fixes it for a reproducible sequence, `true` forces entropy explicitly. |
+| `wat: true` | `compile()` returns WAT text instead of WASM binary. |
+| `names: true` | Emit a WASM `name` section (function symbols) for profilers/debuggers. |
+| `profile` | Mutable sink for compile-stage timings (`entries`/`totals` per phase). |
 </details>
 
 ## CLI
@@ -83,81 +84,123 @@ Options are passed as `jz(source, opts)` or `compile(source, opts)`. Common ones
 `npm install -g jz`
 
 ```sh
-# Compile
 jz program.js              # → program.wasm
 jz program.js --wat        # → program.wat
 jz program.js -o out.wasm  # custom output (- for stdout)
+jz program.js -O3          # optimization: -O0 off, -O1 minimal, -O2 default, -O3 speed (-Os for size)
+jz program.js --host wasi  # standalone WASI output
+jz --strict program.js     # pure canonical subset (also implied by .jz extension)
+jz -e "1 + 2"              # eval → 3
+```
 
-# Optimization level: -O0 off, -O1 size, -O2 balanced, -O3 speed
-jz program.js -O3
-
-# Runtime-service lowering: js (default) or wasi
-jz program.js --host wasi
-
-# Evaluate
-jz -e "1 + 2" # 3
+<details>
+<summary><code>jz --help</code></summary>
 
-# Show help
-jz --help
 ```
+jz - min JS → WASM compiler
+
+Usage:
+  jz <file.js>              Compile JS to WASM (full JS subset; .jz = strict)
+  jz --strict <file.js>     Strict mode — pure canonical subset, no lowering
+  jz --jzify <file.js>      Transform JS → jz source (auto-derives output file)
+  jz -e <expression>        Evaluate expression
+  jz --help                 Show this help
+
+Examples:
+  jz program.js                    # → program.wasm
+  jz program.js --wat              # → program.wat
+  jz program.js -o out.wasm        # custom output name
+  jz program.js -o -               # write to stdout
+  jz program.js -O3                # optimize for speed
+  jz program.js -Os                # optimize for size
+  jz program.js -D DEBUG=false     # inject a compile-time constant
+  jz program.js --memory 64        # 64 initial pages (4 MB)
+  jz program.js --host wasi        # emit WASI Preview 1 imports
+  jz --strict program.js           # strict mode
+  jz --jzify lib.js                # → lib.jz
+  jz -e "1 + 2"
+
+Options:
+  --output, -o <file>       Output file (.wat, .wasm, or - for stdout)
+  -O<n>, --optimize <n>     Optimization level: 0 off, 1 minimal, 2 default (all
+                            stable passes), 3 speed. -Os optimizes for size.
+  --define, -D <K=V>        Inject a compile-time constant (VALUE parsed as JSON,
+                            else string). Repeatable.
+  --host <js|wasi>          Runtime-service lowering (default js)
+  --memory <pages>          Initial memory size in 64 KiB pages
+  --max-memory <pages>      Cap memory growth at this many pages (default unbounded)
+  --import-memory           Import env.memory instead of exporting own memory
+  --no-alloc                Omit _alloc/_clear allocator exports (standalone wasm)
+  --no-simd                 Disable auto-vectorization (no v128) for non-SIMD engines
+  --why-not-simd            Report, per loop, why the auto-vectorizer declined it
+  --experimental-stencil    Vectorize neighbour-load stencils (a[i±1]); opt-in
+  --experimental-outer-strip  Strip-mine pixel loops over an inner reduction to f64x2; opt-in
+  --no-tail-call            Use ordinary call frames instead of return_call
+  --names                   Emit wasm name section for profilers/debuggers
+  --stats                   Print compile-phase timings to stderr
+  --strict                  Pure canonical subset: reject full-JS syntax + dynamic fallbacks
+  --jzify                   Transform JS to jz source (no compilation)
+  --eval, -e                Evaluate expression or file
+  --wat                     Output WAT text instead of binary
+  --resolve                 Resolve bare specifiers via Node.js module resolution
+  --imports <file>          JSON file with host import specs (e.g. {"env":{"fn":{"params":2}}})
+  --version, -v             Show version number
+```
+</details>
 
 
 ## Language
 
-JZ is a strict functional JS subset. Built-in `jzify` transform extends support to legacy patterns.
+jz is a **strict modern JS subset**. Built-in jzify transform extends support to legacy patterns.
 
 ```
 ┌────────────────────────────────────────────────────────────────────────┐
-│ JZify                                                                  │
-│   var  function  arguments  switch  new Foo()                          │
-|   class  new  this  extends  super  static  #private                   │
-│   ==  !=  instanceof  undefined                                        |
-│                                                                        │
 │ ┌────────────────────────────────────────────────────────────────────┐ │
-│ │ JZ                                                                 │ │
+│ │ jz strict                                                          │ │
 │ │   let/const  =>  ...xs  destructuring  import/export               │ │
 │ │   if/else  for/while/do-while/of/in  break/continue                │ │
 │ │   try/catch/finally  throw                                         │ │
 │ │   operators  strings  booleans  numbers  arrays  objects  `${}`    │ │
 │ │   Math  Number  String  Array  Object  JSON  RegExp  Symbol  null  │ │
 │ │   ArrayBuffer  DataView  TypedArray  Map  Set                      │ │
+│ │   parseInt  parseFloat  encodeURIComponent  Error  BigInt          │ │
 │ │   console  setTimeout/setInterval  Date  performance               │ │
 │ └────────────────────────────────────────────────────────────────────┘ │
+│ jz default (jzify)                                                     │
+│   var  function  arguments  switch  new Foo()                          │
+│   class  new  this  extends  super  static  #private                   │
+│   ==  !=  instanceof  undefined  WeakMap  WeakSet                      │
+│                                                                        │
 └────────────────────────────────────────────────────────────────────────┘
 Not supported
   async/await  Promise  function*  yield
-  delete  labels  eval  Function  with
-  Proxy  Reflect  WeakMap  WeakSet
+  delete  getters/setters  eval  Function  with
+  Proxy  Reflect
   import()  DOM  fetch  Intl  Node APIs
 ```
 
-`jzify` covers most class syntax — fields, methods, `new`, `this`, `extends`, `super.method()`, `#private`, constant computed member names. Getters/setters, bare `super.x` reads, and dynamic computed names are rejected with a clear message.
 
 ## FAQ
 
 <details>
-<summary><strong>Where does jz differ from JavaScript?</strong></summary>
-
-<br>
-
-`Valid jz = valid JS` means jz source always parses and runs as JS — but jz compiles to *static* WASM, so a handful of behaviors diverge from V8. These are deliberate trades, not unfinished corners: each one is what keeps the output close to hand-written WAT. `--wat` shows exactly what was emitted. (For what's out of scope entirely — `eval`, `async`, `Proxy`, … — see the *Not supported* box above; for moving values across the boundary, see [Interop](#interop).)
-
-- **A boolean can surface as `1`/`0` at the host boundary.** `typeof`, `String`, `JSON.stringify`, and a directly-returned comparison all hand back a real boolean — but a boolean produced by value-preserving `&&`/`||`, or read bare from an untyped container, crosses as the numeric carrier `1`/`0`.
-- **Objects are fixed-layout schemas** — key set and order fixed at the literal; `delete` is rejected; `memory.Object({…})` must match the source key order.
-- **Errors are untagged** — `throw` carries a value, not a typed `Error`; `e instanceof TypeError` does not discriminate.
-- **`Set`/`Map` iterate slot order**, not insertion order.
-- **Memory is not reclaimed automatically** — see *How does memory work?* below.
-
-For full TC39 conformance use [porffor](https://github.com/CanadaHonk/porffor); jz trades completeness for low-level numeric performance by design.
-
+<summary><strong>What are the differences with JS?</strong></summary>
+
+- **Numbers are f64**; integer-proven values (loop counters, array idx, `| 0`) are `i32` and **wrap at ±2³¹**.
+- **Strings are UTF-8 bytes** — `.length`, `charCodeAt`, indexing, `slice`, `indexOf`, regex count bytes (`"中".length` is `3`); `toUpperCase`/`toLowerCase`/`trim` are ASCII-only. UTF-8 skips UTF-16's 2× and a multi-KB Unicode case table.
+- **Objects are fixed-shape structs** — literal keys sit in fixed slots; computed writes (`o[k] = v`) fall back to a per-object hash and enumerate normally, but a dot-key added after the literal (`o.b = 2`) stays readable without enumerating (`Object.keys`/`for…in`). Prefer `Map` for heavy dynamic keys.
+- **Typed arrays are fixed-size** — `arr.length = n` won't compile, and out-of-bounds reads give `0`.
+- **No GC** — call `memory.reset()` between batches; `WeakMap`/`WeakSet` wired to `Map`/`Set`.
+- **`String(number)` keeps ~9 significant digits** (`String(Math.PI)` → `"3.14159265"`), so it may not round-trip; `NaN`/`Infinity`/integers are exact. Exact shortest-form needs a multi-KB Ryū/Grisu formatter.
+- **Errors are just their message** — a caught error is the value you threw (no `.message`, not `instanceof Error`), and `null.x` yields `undefined` instead of throwing. It keeps `throw` and member reads free of object machinery and per-access checks.
+- **`Date` getters return UTC** (`getHours` ≡ `getUTCHours`) – the IANA timezone database is hundreds of KB.
+- **`Math.random` is seedable** — default draws host entropy; pass `randomSeed: n` for a reproducible stream.
 </details>
 
-<details>
-<summary><strong>Can I use npm packages or existing JS libraries?</strong></summary>
 
-<br>
+<details>
+<summary><strong>Can I use existing npm packages or JS libraries?</strong></summary>
 
-Only code that fits the jz subset. There's no runtime, so packages touching the DOM, `async`/`Promise`, the network, or Node APIs won't compile — but pure numeric/algorithmic source does.
+Only the ones that fit the jz subset. There's no runtime, so packages touching the DOM, `async`/`Promise`, the network, or Node APIs won't compile — but pure numeric/algorithmic source does.
 
 - **Relative imports** (`./dep.js`) bundle at compile time.
 - **Bare specifiers** (`import { x } from "pkg"`) resolve through Node module resolution only with the `--resolve` CLI flag, or by passing the source yourself via `{ modules }`. The package's source still has to be valid jz.
@@ -167,384 +210,338 @@ jz is for compiling *your* numeric/DSP/parser code, not for running the npm ecos
 </details>
 
 <details>
-<summary><strong>Can I use import/export to split code?</strong></summary>
+<summary><strong>Can I use import/export?</strong></summary>
 
-<br>
-
-Yes. Standard `import`/`export` syntax is bundled at compile time into a single WASM — no runtime module resolution.
+Standard `import`/`export` syntax is bundled at compile time into a single WASM — no runtime module resolution.
 
 ```js
 const { exports } = jz(
-  'import { add } from "./math.jz"; export let f = (a, b) => add(a, b)',
-  { modules: { './math.jz': 'export let add = (a, b) => a + b' } }
+  'import { add } from "./math.js"; export let f = (a, b) => add(a, b)',
+  { modules: { './math.js': 'export let add = (a, b) => a + b' } }
 )
 ```
 
-Transitive imports work (main → math → utils → …); circular imports error at compile time. The **CLI** resolves filesystem imports automatically (`jz main.jz -o main.wasm` reads `./math.jz` etc.). In the **browser**, fetch sources yourself and pass them via `{ modules }` — the compiler stays synchronous and pure, no I/O.
+Transitive imports work (main → math → utils → …); circular imports error at compile time. The **CLI** resolves filesystem imports automatically. In the **browser**, fetch sources yourself and pass them via `{ modules }` — the compiler stays synchronous and pure, no I/O.
 
 </details>
 
 <details>
-<summary><strong>How does memory work? How do I reset it?</strong></summary>
+<summary><strong>Can I call into the host (functions, objects)?</strong></summary>
 
-<br>
+`import … from 'host'` with the `{ imports }` option **wires a runtime binding** — a JS function, constant, or whole namespace. Numbers pass directly; strings, arrays, and objects cross via `memory.*`.
 
-jz uses a **bump allocator**: every heap value (string, array, object, typed array) bumps a single pointer forward — no free list, no GC. The heap starts at byte 1024 and grows the WASM memory automatically when full.
+```js
+// Custom function
+jz('import { log } from "host"; export let f = (x) => { log(x); return x }',
+   { imports: { host: { log: console.log } } })
 
-So **memory is never reclaimed implicitly** — a long-running program that allocates per call grows without bound. Reset the heap pointer between independent batches:
+// Whole namespace — sin, cos, PI, … all auto-wired (functions as imports, numeric constants folded)
+jz('import { sin, PI } from "math"; export let f = () => sin(PI / 2)',
+   { imports: { math: Math } })
 
-```js
-for (let i = 0; i < 1000; i++) {
-  const sum = exports.process(100)   // allocates an array each call
-  memory.reset()                     // drop everything; heap ptr → 1024
-}
+// globalThis works too
+jz('import { parseInt } from "window"; export let f = () => parseInt("42")',
+   { imports: { window: globalThis } })
 ```
 
-After `memory.reset()` all previously returned pointers are invalid — read what you need first, then reset. For finer control, `memory.alloc(bytes)` returns a raw offset on the same pointer. Pure scalar modules (no heap values) compile without the allocator at all. The low-level export/encoding contract is in [Interop](#interop).
-
 </details>
 
 <details>
-<summary><strong>How do I see and control inferred types?</strong></summary>
+<summary><strong>Can I interpolate values (template literals)?</strong></summary>
 
-<br>
+`jz` is a tagged template — interpolated values are baked into the source at compile time. Numbers and booleans inline directly; strings, arrays, and objects compile as jz literals:
 
-Inference is mechanical and visible — not the hidden, fragile, coercive thing the "explicit > implicit" reflex assumes. It reads the same signals a human reader does: literals, operators (`x | 0` → i32), member access (`s.length` → string), `typeof` guards, and assignment flow. The chosen types appear in `--wat`; ambiguous cases fall back to NaN-boxed **f64** — a safe default, never a wrong type.
+```js
+jz`export let f = () => ${'hello'}.length`               // 5
+jz`export let f = () => ${[10, 20, 30]}[1]`              // 20
+jz`export let f = () => ${{name: 'jz', count: 3}}.count` // 3
+
+const scale = (x) => x * 10
+jz`export let f = (n) => ${scale}(n) + 1`                // f(2) → 21, host-called
+```
 
-So there's nothing to annotate. Type annotations bundle two jobs into one syntax: hinting storage to the compiler (`let x: number` — which only duplicates what `x | 0` already tells inference) and documenting contracts at boundaries (a *docs* concern, not a *language* one). jz keeps the split clean — inference handles storage, and **valid jz = valid JS** means no parallel type system to learn. To pin a type, write code that implies it: `x | 0` keeps `x` an i32; an `s = ''` default declares a string param. (JSDoc `@type` is planned as an advisory hint, not yet enforced.) Annotations never make code faster; they only sharpen what inference already sees.
+Interpolated functions become host calls. Non-serializable values (host objects, class instances) fall back to post-instantiation getters automatically.
 
 </details>
 
 <details>
-<summary><strong>Is it production-ready?</strong></summary>
-
-<br>
+<summary><strong>How to pass numbers, strings, arrays, objects JS ↔ WASM?</strong></summary>
 
-It's **experimental** (`0.4.0`) — the compiler API and option names may still change. What's stable is the *output*: jz emits deterministic WASM, gated on every push by test262, a differential fuzzer (`test/differential.js` runs jz-compiled wasm against the same source as plain JS), and the size/speed bench.
+**Numbers cross natively** as `f64`/`i32`. **Heap values** — strings, arrays, objects, typed arrays — cross as NaN-boxed `f64` pointers into linear memory, allocated through the module's `_alloc`/`_clear` exports. That pointer-plus-allocator convention *is* the whole ABI (a few hundred bytes, documented in [`layout.js`](layout.js) with a worked example in [`test/abi.js`](test/abi.js)). The one shortcut: arrays of ≤ 8 elements come back as plain JS arrays via WASM multi-value.
 
-The robust way to depend on jz today: compile to `.wasm` at build time, commit the binary, and load it through the dependency-free [`jz/interop`](#interop) bridge — your app then rides on the WASM, not on the compiler's evolving API.
+The `memory` codec — returned by `jz()` and by `jz/interop`'s `instantiate()` — handles both directions: it marshals arguments in, decodes pointer returns out, and turns a wasm `throw` into a real `Error`:
 
-</details>
+```js
+const { exports, memory } = jz`
+  export let greet = (s) => s.length
+  export let dist = (p) => (p.x * p.x + p.y * p.y) ** 0.5
+  export let rgb = (c) => [c, c * 0.5, c * 0.2]
+  export let process = (buf) => buf.map(x => x * 2)
+`
 
-<details>
-<summary><strong>Why jz over Porffor or AssemblyScript?</strong></summary>
+// Pass in
+exports.greet(memory.String('hello'))        // 5
+exports.dist(memory.Object({ x: 3, y: 4 }))  // 5
 
-<br>
+// Get back
+exports.rgb(100)                              // [100, 50, 20] — auto-decoded JS array
+memory.read(exports.process(memory.Float64Array([1, 2, 3])))  // Float64Array [2, 4, 6]
+```
 
-Pick jz for plain JS that fits the subset and tiny, native-fast numeric/DSP WASM. For full TC39, a typed TypeScript dialect, or running standard JS unchanged, see the [Alternatives](#alternatives) decision table (porffor / AssemblyScript / jawsm).
+`memory.String` / `.Array` / `.Float64Array`/etc / `.Object` allocate on the heap and return a pointer; `memory.read(ptr)` decodes one back. `memory.Object()` is fixed-layout — its keys must match a compiled schema's key set (order is free, fields place by name).
 
 </details>
 
 <details>
-<summary><strong>Can I compile jz to C?</strong></summary>
+<summary><strong>Do I need jz at runtime?</strong></summary>
 
-<br>
-
-Yes, via [wasm2c](https://github.com/WebAssembly/wabt/blob/main/wasm2c) or [w2c2](https://github.com/turbolent/w2c2):
+The compiler runs at build time. At runtime you ship the `.wasm` and, at most, a small bridge — never the compiler, the parser, or a language runtime.
 
-```sh
-jz program.js -o program.wasm
-wasm-opt -O3 program.wasm -o program.opt.wasm   # trims redundant locals/loads first
-wasm2c program.opt.wasm -o program.c
-cc -O3 program.c -o program
-```
+- **Pure-number modules — nothing but the `.wasm`.** Instantiate with raw `WebAssembly`, zero jz dependency: `(await WebAssembly.instantiate(wasmBytes)).instance.exports.dist(3, 4)`. Compile with `{ alloc: false }` to drop the `_alloc`/`_clear` exports too.
+- **Heap values (strings, arrays, objects) — the `.wasm` plus `jz/interop`.** `import { instantiate } from 'jz/interop'` adds a ~6 KB-gzipped bridge (no compiler, no parser) that builds the same `Module`+`Instance` you'd build by hand and wires the allocator and the `memory` codec from the previous question (plus WASI / `wasm:js-string` imports if the module uses them).
+- **No JavaScript host at all** — compile with `host: 'wasi'`; see the next question.
 
-The full native pipeline (jz → `wasm-opt -O3` → `wasm2c` → `clang -O3 -flto` + PGO) lands within a few percent of hand-tuned C — beating V8 on 19 of 21 bench cases on an M4 Max. Details and the regression gate live in [`scripts/native/README.md`](scripts/native/README.md).
+For contrast, Rust (`wasm-bindgen`), Go (TinyGo), and C/Zig (Emscripten/WASI-libc) emit per-build generated glue and usually bundle a language runtime. jz keeps the ABI fixed and the optional bridge ~6 KB gzipped.
 
 </details>
 
 <details>
-<summary><strong>Can I add my own operators or stdlib methods?</strong></summary>
+<summary><strong>Can I run the `.wasm` without a JavaScript host (WASI)?</strong></summary>
 
-<br>
+There's two possible `host` targets:
 
-Yes — jz's emitter table (`ctx.core.emit`) maps AST operators to WASM IR generators, and the whole stdlib is just modules registering on it. Adding one is the same move the built-ins make:
+- **`js`** (default) — runs inside a JavaScript host (browser, Node, Deno, Bun). `jz()` and `jz/interop` wire the needed `env.*` services automatically (overridable via `opts.imports.env`), and you get full value marshaling across the boundary.
+- **`wasi`** — runs on a standalone WASM engine with no JavaScript (wasmtime, wasmer, deno run). jz emits WASI Preview 1, so the module needs no host shims — but there's no host-side marshaler, so heap values must be passed by hand.
 
-```js
-import { emitter } from './src/emit.js'
-import { typed } from './src/ir.js'
+Either way the `.wasm` carries at most one import namespace (none, `env`, or `wasi_snapshot_preview1`). The difference is only in how a few runtime services are serviced:
 
-// my.double(x) → x * 2
-emitter['my.double'] = (x) => ['f64.mul', ['f64.const', 2], typed(x, 'f64')]
-```
-
-Handler names follow the AST path: `Math.sin` → `math.sin`, `arr.push` → `.push`, typed variants like `.f64:push`. Any file in [`module/`](module/) is a worked template — each receives `ctx` and registers emitters, stdlib, globals, or helpers. See [CONTRIBUTING.md](CONTRIBUTING.md) for the pipeline.
+| What your code does | `js` (default) | `wasi` |
+|---|---|---|
+| `console.log()` | `env.print` — host stringifies | WASI `fd_write` |
+| `Date.now()` / `performance.now()` | `env.now` → f64 | WASI `clock_time_get` |
+| `setTimeout` / `setInterval` | `env.setTimeout` — host schedules | WASM timer queue + `__timer_tick` |
+| dynamic `obj.method()` | `env.__ext_call` (JS resolves) | error at compile time |
 
 </details>
 
+<details>
+<summary><strong>How does memory work?</strong></summary>
 
-## Benchmark
-
-| | jz | [Node](https://nodejs.org/) | [Porffor](https://github.com/CanadaHonk/porffor) | [AS](https://github.com/AssemblyScript/assemblyscript) | WAT | C | [Go](https://go.dev/) | [Zig](https://ziglang.org/) | [Rust](https://www.rust-lang.org/) | [NumPy](https://numpy.org/) |
-|---|---|---|---|---|---|---|---|---|---|---|
-| [biquad](bench/biquad/biquad.js) | 6.50ms<br>3.4kB | 12.35ms<br>3.2kB | fails | 9.03ms<br>1.9kB | 6.49ms<br>767 B | 5.30ms | 8.96ms<br>fma | 5.04ms | 5.27ms | 3.09s |
-| [mat4](bench/mat4/mat4.js) | 2.74ms<br>3.3kB | 11.96ms<br>1.2kB | 88.68ms<br>2.4kB<br>diff | 9.32ms<br>1.6kB | 8.12ms<br>414 B | 2.76ms | 12.51ms | 2.74ms | 1.78ms | 389.44ms |
-| [poly](bench/poly/poly.js) | 0.37ms<br>1.2kB | 2.32ms<br>1014 B | fails | 1.15ms<br>1.3kB | 0.81ms<br>359 B | 0.52ms | 0.80ms | 0.80ms | 0.57ms | 0.61ms |
-| [bitwise](bench/bitwise/bitwise.js) | 1.40ms<br>1.2kB | 5.32ms<br>1005 B | fails | 12.13ms<br>1.5kB | 4.88ms<br>355 B | 1.30ms | 5.23ms | 4.16ms | 1.30ms | 14.77ms |
-| [tokenizer](bench/tokenizer/tokenizer.js) | 0.10ms<br>1.7kB | 0.21ms<br>2.0kB | 0.41ms<br>3.2kB | 0.08ms<br>1.6kB | 0.10ms<br>344 B | 0.13ms | 0.08ms | 0.14ms | 0.12ms | 5.13ms |
-| [callback](bench/callback/callback.js) | 0.03ms<br>1.4kB | 0.88ms<br>828 B | fails | 1.49ms<br>1.9kB | 0.25ms<br>267 B | 0.10ms | 0.20ms | 0.01ms | 0.09ms | 1.81ms |
-| [aos](bench/aos/aos.js) | 1.62ms<br>1.8kB | 1.82ms<br>1.1kB | fails | 1.91ms<br>2.2kB | 1.07ms<br>481 B | 1.20ms | 0.90ms | 0.90ms | 1.20ms | 2.55ms |
-| [mandelbrot](bench/mandelbrot/mandelbrot.js) | 12.55ms<br>1.0kB | 13.80ms<br>1.8kB | 13.47ms<br>3.0kB | 12.42ms<br>1.3kB | — | 12.26ms | 12.46ms | 12.31ms | 12.23ms | — |
-| [json](bench/json/json.js) | 0.23ms<br>7.7kB | 0.38ms<br>1.2kB | fails | — | — | 0.21ms | 1.17ms | 0.69ms | 0.68ms | 1.20ms |
-| [sort](bench/sort/sort.js) | 5.96ms<br>1.6kB | 11.13ms<br>1.6kB | fails | 10.22ms<br>1.9kB | — | 8.85ms | 10.36ms | 8.84ms | 9.37ms | 5.05ms |
-| [crc32](bench/crc32/crc32.js) | 12.12ms<br>1.2kB | 13.43ms<br>1.8kB | 80.76ms<br>3.1kB | 12.19ms<br>1.4kB | — | 10.69ms | 9.30ms | 9.45ms | 9.38ms | 0.24ms |
-| [watr](bench/watr/watr.js) | 1.56ms<br>144.4kB | 1.45ms<br>2.6kB | fails | — | — | — | — | — | — | — |
-
+jz uses a **bump allocator**: every heap value (string, array, object, typed array) bumps a single pointer forward — no free list, no GC. The heap starts at byte 1024 — the first 1 KB holds static data (string/array literals laid out from offset 0, plus the bump pointer itself at byte 1020 when memory is shared across threads). It grows the WASM memory automatically when full, and if the literals overflow that 1 KB the heap simply starts past them.
+Memory is never reclaimed implicitly — a long-running program that allocates per call grows without bound. Reset between independent batches:
 
-_Per-case median speed / wasm size from `node bench/bench.mjs` on Apple Silicon (arm64); the **geomean** row is the gated cross-case jz/target ratio from `test/bench.js`._
+```js
+for (let i = 0; i < 1000; i++) {
+  const sum = exports.process(100)   // allocates an array each call
+  memory.reset()                     // drop everything; heap ptr → 1024
+}
+```
 
-Geomean size: jz **0.86× AS**. jz wasm runs at `clang -O3` speed — native-C parity at geomean 0.96× — and `test/bench.js` gates every figure so a regression fails CI.
+After `memory.reset()` all previously returned pointers are invalid — read what you need first, then reset. For finer control, `memory.alloc(bytes)` returns a raw offset on the same pointer. Pure scalar modules (no heap values) compile without the allocator at all.
 
+</details>
 
 <details>
-<summary><strong>Optimizations</strong></summary>
-
-<br>
-High-impact summary behind the benchmark table, not an exhaustive list.
+<summary><strong>Can modules share memory?</strong></summary>
 
-| Optimization | Effect |
-|---|---|
-| Escape scalar replacement | Removes short-lived object/array literals before allocation. |
-| Stack rest-param scalarization | Fixed-arity internal calls avoid heap rest arrays. |
-| Scoped arena rewind | Safely rewinds allocations in functions proven not to return or persist heap values. |
-| Host-service import lowering | `host: 'js'` lowers console, clocks, and timers to small `env.*` imports instead of pulling WASI/string formatting into normal JS-host builds. |
-| Static and shaped runtime JSON specialization | Constant `JSON.parse` sources fold to fresh slot trees; stable `let` JSON sources use a generated runtime parser for the inferred shape. |
-| Typed-array specialization and address fusion | Monomorphic/bimorphic typed-array paths skip generic index dispatch and fuse repeated address bases/offsets in hot loops. |
-| Integer/value-type narrowing | Keeps bitwise, `Math.imul`, `charCodeAt`, loop counters, and internal narrowed returns on raw i32/f64 paths instead of generic boxed-value helpers. |
-| SIMD lane-local vectorization | Beats V8 on bitwise and keeps scalar feedback loops such as biquad untouched. |
-| Small constant loop unroll | Required for biquad and mat4 speed; size cost is pinned. |
-| OBJECT-only ternary type propagation | Keeps bimorphic object reads on typed dynamic dispatch without broad type-risk. |
-| Benchmark checksum helper inlining | Avoids pulling generic ToNumber/string conversion into typed-array checksum binaries; mandelbrot drops from ~5.0kB to ~1.2kB. |
-
-`npm run test:bench` pins every claimed V8 win, AssemblyScript win/tie, and wasm size budget. Mandelbrot is pinned as a V8 win and AssemblyScript tie, not an AS win. Unclaimed rows stay visible as todo gaps without weakening the asserted wins.
+`jz.memory()` creates a shared memory that modules compile into. Schemas accumulate, so objects created in one module are readable by another:
 
-#### Making array loops vectorize
+```js
+const memory = jz.memory()
+const a = jz('export let make = () => { let o = {x: 10, y: 20}; return o }', { memory })
+const b = jz('export let read = (o) => o.x + o.y', { memory })
 
-The lane-local vectorizer (on at default `optimize: 2`) lifts inner loops of shape `for (let i=0;i<N;i++) arr[i] = f(arr[i], …)` to SIMD-128 when the body is lane-pure (the k-th output depends only on the k-th inputs).
+b.exports.read(a.exports.make())  // 30 — same memory, merged schemas
+memory.read(a.exports.make())     // {x: 10, y: 20}
+```
 
-**Lifts:** in-place maps (`a[i] = a[i] * 2`), cross-array maps (`b[i] = a[i] * k + c`), **structure-of-arrays** (`zs[i] = xs[i]*a + ys[i]*b`, up to 4 base pointers), and reductions (`s += a[i]`, `h ^= a[i]`, `|`, `&`).
+Pass an existing `WebAssembly.Memory` to wrap it: `jz.memory(new WebAssembly.Memory({ initial: 4 }))`.
 
-**Doesn't lift:** **array-of-structures** (interleaved `a[i*3]`, `a[i*3+1]` — stride exceeds lane width; split into one typed array per field), loop-carried scalars (`s ^= s << 13`), stencils (`a[i] = a[i] + a[i-1]`), unbounded loops, mixed lane types in one body.
+Each compiled module exposes two call surfaces:
 
-Check with `--wat`: a successful lift adds a `$__simd_loop<N>` block ahead of the scalar tail. No block means the recognizer bailed — usually a loop-carried local or a non-`(base + i<<K)` address.
+- **`.exports`** — the JS-wrapped surface: it marshals JS arguments into the heap and decodes pointer return values back to JS values (and turns a wasm `throw` into an `Error`). Use it by default — it's also how you hand a value from one module to another, as in the example above (the value is re-marshaled through the shared memory).
+- **`.instance.exports`** — the raw `WebAssembly.Instance` exports: numbers pass through untouched, and a pointer return comes back as a raw NaN-boxed handle. Decode it on the host with `memory.read(ptr)`. Don't pass a raw pointer back *in* as an argument, though — the JS↔wasm `f64` boundary canonicalizes its NaN payload and the pointer is lost; let `.exports` marshal across instead.
 
 </details>
 
+<details>
+<summary><strong>How big is the output?</strong></summary>
 
-## Interop
-
-How values cross the JS↔WASM boundary, and how to ship and run the compiled `.wasm`. The mental model is simple: numbers pass straight through, and anything heap-allocated — strings, arrays, objects — crosses as a pointer the `memory` helper reads and writes for you. Under the hood that pointer is a **NaN-boxed `f64`** into a bump-allocated heap, one boundary codec per binary, fixed at compile time.
+No runtime, no GC — a module is your code plus a small bump allocator. The geomean across the bench corpus is on par with AssemblyScript and smaller than Porffor; most modules are single-digit kB — the [ZzFX synth](examples/zzfx) is ~10 kB, [mandelbrot](examples/mandelbrot) ~7 kB. Shrink it further:
 
-### Passing data in and out
+- **`optimize: 'size'`** — keeps every size pass, drops loop unrolling and SIMD.
+- **`alloc: false`** — omit the allocator for pure-numeric modules that never marshal heap values.
+- **`host: 'wasi'`** — no JS-host import shims (the debug `name` section is already off unless you set `names: true`).
 
-Arrays of ≤ 8 elements come back as plain JS arrays (WASM multi-value); everything else stays heap-resident behind a pointer.
+Hand-written WAT is still ~3–8× smaller on tight kernels — jz carries generic allocator and stdlib helpers a specialist omits; closing that gap is ongoing. Size budgets are gated in CI alongside speed ([full table](bench/README.md)).
 
-```js
-const { exports, memory } = jz`
-  export let greet = (s) => s.length
-  export let dist = (p) => (p.x * p.x + p.y * p.y) ** 0.5
-  export let rgb = (c) => [c, c * 0.5, c * 0.2]
-  export let process = (buf) => buf.map(x => x * 2)
-`
+</details>
 
-// JS → WASM (write)
-memory.String('hello')          // → string pointer
-memory.Array([1, 2, 3])         // → array pointer
-memory.Float64Array([1, 2])     // → typed array pointer (all TypedArray ctors available)
-memory.Object({ x: 3, y: 4 })   // → object pointer (see warning)
 
-// Call with pointers
-exports.greet(memory.String('hello'))        // 5
-exports.dist(memory.Object({ x: 3, y: 4 }))  // 5
-exports.rgb(100)                              // [100, 50, 20] — direct JS array return
-memory.read(exports.process(memory.Float64Array([1, 2, 3])))  // Float64Array [2, 4, 6]
-```
+<details>
+<summary><strong>Which optimizations are applied?</strong></summary>
 
-> [!WARNING] jz objects are fixed-layout schemas (like C structs), not dynamic key bags.
-> `memory.Object({ x: 3, y: 4 })` must use the same key order as the jz source `{ x, y }` — reversed keys produce wrong values. Strings/arrays inside objects are auto-wrapped to pointers.
+Ordinary JS is already fast — jz infers the right machine type for your numbers, so you write plain JS. What it does, all on at the default `optimize: 2` (each line is also the habit that triggers it):
 
-### Template interpolation
+- **Type narrowing** — parameters/results pinned to `i32`/`f64`/bool/typed-array elements from their call sites, off the boxed path. A `Float64Array`/`Int32Array` is direct memory access; a plain `[]` works too, with a little more overhead.
+- **Escape analysis & arena rewind** — fixed-shape arrays/objects/typed-arrays become WASM locals; scratch a function doesn't return is freed on exit (no manual cleanup).
+- **Loops** — invariant hoisting, CSE, typed-array address reuse, induction-variable strength reduction, small fixed-count unrolling (mat4, biquad).
+- **SIMD-128** — independent iterations (`a[i] = a[i]*2 + b[i]`) run several lanes at once: lane-pure maps, reductions (sum/product/min·max), conditional maps (`bitselect`), byte scans (`memchr` via `i8x16`). Loops that look back (`a[i-1]`) or carry a running total stay sequential.
+- **Smaller encoding** — tree-shaking, copy-propagation + dead-store elimination, local/string-pool reordering for 1-byte indices, pointer-call specialization, constant pooling; JS strings you only read aren't copied.
 
-Interpolated values are baked into the source at compile time — no post-instantiation allocation, no getter overhead. Numbers and booleans inline directly; strings, arrays, and objects compile as jz literals:
+Codegen also adapts to the target: `host: 'js'` lowers `console`/timers to tiny `env.*` imports, a constant `JSON.parse` folds to a literal, JS strings stay zero-copy. Levels `0`–`3` (default `2`), or the named presets `'speed'` (= `3`, trades size for inlined constants and larger buffers) and `'size'` (drops unrolling and SIMD for the smallest wasm).
 
-```js
-jz`export let f = () => ${'hello'}.length`               // 5
-jz`export let f = () => ${[10, 20, 30]}[1]`              // 20
-jz`export let f = () => ${{name: 'jz', count: 3}}.count` // 3
-```
+</details>
 
-Functions are imported as host calls. Non-serializable values (host objects, class instances) fall back to post-instantiation getters automatically.
+<details>
+<summary><strong>How do I inspect or debug the output?</strong></summary>
 
-### Calling host functions
+- **Semantics** — valid jz is valid JS: run the same source under Node and diff results (mind the [documented divergences](#faq)); `console.log` works inside compiled modules too.
+- **Codegen** — `jz program.js --wat` (API: `compile(src, { wat: true })`) shows the emitted WAT: grep `v128` to confirm a loop vectorized, `__dyn_get`/`__ext_call` to spot dynamic fallbacks inference couldn't narrow. `--why-not-simd` (API: `whyNotSimd: true`) goes further — for each loop the auto-vectorizer declined it reports the first blocking op (e.g. `i32.rem_s: no lane-pure SIMD mapping`), so you don't have to grep the WAT to find what's one op away.
+- **Dynamic fallbacks** — compile with `strict: true` to turn every fallback (`obj[k]`, `for-in`, unknown receiver method) into a compile error pointing at the site.
+- **Profiling** — `--names` (API: `names: true`) emits a wasm `name` section so DevTools profilers and disassemblers show real function names; `--stats` (API: the `profile` sink) collects per-stage compile timings.
+- **Slow kernel checklist** — a stray float literal pins a counter to f64; a plain `[]` where a typed array would do; a loop-carried dependency (`a[i-1]`, running sum) blocks SIMD. The signals in *Why no type annotations?* below are the levers.
 
-Any host namespace — functions, constants, custom objects — wires in via the `imports` option. jz extracts names via `Object.getOwnPropertyNames`, so non-enumerable built-ins (`Math.sin`, `Date.now`) work automatically:
+</details>
 
-```js
-// Custom function
-jz('import { log } from "host"; export let f = (x) => { log(x); return x }',
-   { imports: { host: { log: console.log } } })
+<details>
+<summary><strong>How does jz work?</strong></summary>
 
-// Whole namespace — sin, cos, PI, … all auto-wired
-jz('import { sin, PI } from "math"; export let f = () => sin(PI / 2)',
-   { imports: { math: Math } })
+A source string flows through six stages into wasm bytes — no IR leaves the process, the whole thing is one pass per `compile()`:
 
-// globalThis works too
-jz('import { parseInt } from "window"; export let f = () => parseInt("42")',
-   { imports: { window: globalThis } })
+```
+ your .js
+   │ parse      jessie parser (subscript) → AST
+   │ jzify      lower legacy JS to the canonical subset (var/function/class/==/…)
+   │ prepare    resolve & bundle imports, normalize the AST
+   │ compile    type inference (i32 vs f64) + emit WAT IR; module/ handlers lower operators
+   │ optimize   WAT-level passes — CSE, DCE, const-fold, inline, peephole
+   │ encode     watr: WAT → WASM binary
+   ▼
+ .wasm
 ```
 
-### Host features & runtime services
+Each stage lives in its own place: parsing in [`subscript`](https://github.com/dy/subscript)'s jessie grammar, [`jzify/`](jzify/) for the legacy-JS lowering, [`src/prepare/`](src/prepare/) for module bundling, [`src/compile/`](src/compile/) for inference + codegen (with built-ins in [`module/`](module/) and heap layout in [`src/abi/`](src/abi/)), [`src/optimize/`](src/optimize/) + [`src/wat/`](src/wat/) for the WAT passes, and [`watr`](https://github.com/dy/watr) for the final encode. Shared compile state is one `ctx` object ([`src/ctx.js`](src/ctx.js)).
 
-Two host modes select how runtime services lower. `host: 'js'` (default) imports small `env.*` services that `jz()` auto-wires; `host: 'wasi'` emits WASI Preview 1 for wasmtime/wasmer/deno.
+</details>
 
-| JS API | `host: 'js'` (default) | `host: 'wasi'` |
-|---|---|---|
-| `console.log()` | `env.print(val, fd, sep)` — host stringifies | WASI `fd_write` (fd=1), space-separated, newline |
-| `console.warn`/`error` | same, fd=2 | WASI `fd_write` (fd=2) |
-| `Date.now()` | `env.now(0) → f64` (epoch ms) | `clock_time_get` (realtime) |
-| `performance.now()` | `env.now(1) → f64` (monotonic ms) | `clock_time_get` (monotonic) |
-| `setTimeout`/`setInterval` | `env.setTimeout(cb, delay, repeat)` — host schedules; fires via `__invoke_closure` | WASM timer queue + `__timer_tick` |
-| dynamic `obj.method()` | `env.__ext_call` (JS resolves) | error at compile time |
 
-The compiled `.wasm` carries at most one import namespace — none, `env`, or `wasi_snapshot_preview1` — matching the mode above. `host: 'gc'` is reserved for a planned wasm-gc backend and errors today; pair `host: 'wasi'` with `strict: true` to also fail dynamic `obj[k]`/unknown-receiver calls at compile time.
+<details>
+<summary><strong>Why no type annotations?</strong></summary>
 
-### Sharing memory across modules
-
-`jz.memory()` creates a shared memory that modules compile into. Schemas accumulate, so objects created in one module are readable by another:
+Because `let x: i32` isn't valid JS — annotations would break the promise that valid jz runs and tests as plain JS. So jz reads the types from signals you already write:
 
 ```js
-const memory = jz.memory()
-const a = jz('export let make = () => { let o = {x: 10, y: 20}; return o }', { memory })
-const b = jz('export let read = (o) => o.x + o.y', { memory })
-
-b.exports.read(a.exports.make())  // 30 — same memory, merged schemas
-memory.read(a.exports.make())     // {x: 10, y: 20} — JS reads it too
+export let bits = (a, b) => a | b   // i32 — a bitwise op pins both operands
+export let half = (n) => n * 0.5    // f64 — 0.5 isn't an integer
 ```
 
-`jz.memory()` returns a real `WebAssembly.Memory` patched with `.read()`/`.String()`/`.Array()`/`.Object()`/`.write()`. Pass an existing one to wrap it: `jz.memory(new WebAssembly.Memory({ initial: 4 }))`. Modules sharing a memory share one bump allocator. Use `.instance.exports` for raw pointers, `.exports` for the JS-wrapped surface.
+Literals (`0` vs `0.5`), operators (`|` `<<` `&` ⇒ i32), and how a value is used pin it to `i32`, `f64`, string, object, or typed array. Anything still ambiguous stays **dynamic** — always correct, just type-checked at runtime (a little slower).
 
-### Shipping & running the `.wasm`
+</details>
 
-Compile once, then run the binary anywhere.
 
-**JS host, no compiler.** `jz/interop` is a dependency-free bridge (only `wasi.js`) that knows the value encoding, so bundlers tree-shake the compiler, parser, and watr out entirely:
+<details>
+<summary><strong>Is jz production-ready?</strong></summary>
 
-```js
-import { instantiate } from 'jz/interop'
-import wasmBytes from './program.wasm'   // bundler-specific; or fetch(...)
+It's **experimental** (pre-1.0) — the supported subset and the wasm ABI may still change, so pin a version and re-test on upgrade. What's solid: every push runs the full test suite, the test262 conformance subset, the benchmark gate, and the self-host build in CI, so regressions surface immediately.
 
-const { exports, memory } = instantiate(wasmBytes)
-exports.greet(memory.String('hello'))    // marshal works exactly as at compile time
-```
+</details>
 
-`instantiate(wasm, opts?)` accepts `Uint8Array`, `ArrayBuffer`, or a prebuilt `WebAssembly.Module` and returns the same `{ exports, memory, instance, module }` shape as the `jz(src)` tag — same `memory.String/Array/Object/...` constructors, same `memory.read(ptr)` decoder.
 
-**Native runtimes.** Compile with `host: 'wasi'` and run on any WASM runtime:
+<details>
+<summary><strong>Can I compile in the browser or a Worker?</strong></summary>
 
-```sh
-jz program.js --host wasi -o program.wasm
-wasmtime program.wasm     # also `wasmer run` / `deno run`
-```
+Yes. The compiler is pure and synchronous (no I/O — you hand it the sources), so it runs anywhere JavaScript does — main thread, a Web Worker, or a build step — and compiling a kernel takes single-digit-to-tens of milliseconds, fast enough to do on the fly. The `.wasm` it produces is just a module: instantiate it in any WebAssembly host — browser main thread, Web/Service Worker, Node/Deno/Bun, or a standalone engine.
+
+</details>
 
-Pure numeric modules have no imports and instantiate with standard `WebAssembly.Module`/`Instance` — the right shape for JS hosts such as EdgeJS. Compile at startup or build time and reuse the module; don't compile jz source per request.
 
-**Memory ABI (non-JS hosts).** The allocator is exposed as two exports:
+<details>
+<summary><strong>Can jz compile itself?</strong></summary>
 
-```
-(func $_alloc (param $bytes i32) (result i32))   ;; returns heap offset
-(func $_clear)                                    ;; rewinds heap pointer to 1024
-```
+Yes — fully. jz compiles its own **entire** source to `dist/jz.wasm`: the whole pipeline (parse → jzify → prepare → compile → encode) runs inside WASM, taking a source string and returning wasm bytes with no host help. In other words, `dist/jz.wasm` is jz compiled by jz.
 
-`memory.alloc()`/`memory.reset()` are JS aliases for these. Headers vary by type: strings store `[len:i32]` + utf8 bytes (offset = `_alloc(4+n) + 4`); arrays / typed arrays / objects store `[len:i32, cap:i32]` + payload (offset = `_alloc(8+bytes) + 8`). The boundary pointer is the f64 NaN-box `0x7FF8 << 48 | type << 47 | aux << 32 | offset` — see [`src/host.js`](src/host.js) for type codes and the canonical encoders. Strip both exports with `compile(code, { alloc: false })` if you only call functions and never marshal heap values across the boundary.
+`npm run test:self` is the CI gate — it builds `dist/jz.wasm`, then round-trips real programs through the in-wasm compiler and runs their output, proving the wasm-hosted compiler produces working modules.
 
-<details>
-<summary><strong>Zero-copy strings</strong></summary>
+</details>
 
-<br>
 
-Strings have two boundary carriers; the compiler picks per export-param:
+<details>
+<summary><strong>Can I compile jz to C?</strong></summary>
 
-| carrier | when | what crosses | per-call cost |
-|---|---|---|---|
-| **f64 / SSO** (default) | every param unless the narrower can prove it is used purely as a string | a NaN-boxed `f64` → UTF-8 bytes in linear memory; ≤4 ASCII chars inline in the NaN payload (SSO) | one `_alloc` + memcpy |
-| **externref / `wasm:js-string`** | param uses only `.length`/bounded `.charCodeAt(i)`, isn't reassigned/captured/escaped, *and* has either a `.charCodeAt` use, call-site STRING evidence, or a `s = ''` default | the JS string itself, by reference | **zero** — lowers to [`wasm:js-string`](https://github.com/WebAssembly/js-string-builtins/blob/main/proposals/js-string-builtins/Overview.md) builtins the engine inlines |
+Yes, via [wasm2c](https://github.com/WebAssembly/wabt/blob/main/wasm2c) or [w2c2](https://github.com/turbolent/w2c2):
 
-```js
-const { exports } = jz`
-  // Opt-in fires: .charCodeAt in a bounded loop discriminates string.
-  export let sum = (s) => { let n = 0; for (let i = 0; i < s.length; i++) n += s.charCodeAt(i); return n }
-  // Opt-in fires: 's = ""' default declares string intent.
-  export let len = (s = '') => s.length
-  // Opt-in declines: '+' isn't a builtin; param escapes into the f64 op.
-  export let label = (s) => s + ' (ok)'
-`
-exports.sum('hello')   // 532 — JS string passed by reference
-exports.len()          // 0   — default substituted JS-side
-exports.label('test')  // 'test (ok)' — memory-backed string, as before
+```sh
+jz program.js -o program.wasm
+wasm-opt -O3 program.wasm -o program.opt.wasm
+wasm2c program.opt.wasm -o program.c
+cc -O3 program.c -o program
 ```
 
-**Why `.length`-only doesn't flip.** `.length` also reads arrays and typed arrays, so keeping it on f64 preserves that tolerant polymorphism — flipping would trap on non-strings. **Why bounded loops matter.** `wasm:js-string.charCodeAt` **traps** out of range where JS returns `NaN`, so the narrower proves `i < s.length` before flipping.
+The full native pipeline (jz → `wasm-opt -O3` → `wasm2c` → `clang -O3 -flto` + PGO) lowers to standalone native code that beats V8 on the watr example corpus (19/21 wins, 2 ties, M4 Max). Details and the regression gate live in [`scripts/native/README.md`](scripts/native/README.md).
 
-Native `wasm:js-string` lands in V8 17+ (Chrome 134+, Node 25+ via the `{ builtins: ['js-string'] }` Module option), Safari 18.4+, Firefox behind a flag. `jz/interop` probes the engine and either passes the option for native inlining or attaches a JS polyfill — either way the boundary string-copy is saved. Opt out with `optimize: { jsstring: false }`. Bench: `node bench/jsstring/bench-jsstring.mjs`.
+[Static Hermes](https://github.com/facebook/hermes) reaches native the same way from the other end — full JS through C/LLVM, with sound type annotations for speed; jz keeps the source plain JS and gets its types by inference.
 
 </details>
 
-<details>
-<summary><strong>Custom sections</strong></summary>
 
-<br>
 
-jz embeds four small WebAssembly custom sections so the JS interop layer can wire boundary ABIs without re-parsing the source. They're inert for non-JS hosts (wasmtime/wasmer ignore unknown customs); `interop.js` reads them once at instantiate-time. You don't need to touch them — they're documented so external tools (linkers, custom loaders, devtools) can read them safely.
 
-| Section | Purpose |
-|---|---|
-| `jz:schema` | Object schemas for exported records — JS rehydrates plain objects from boundary writes without per-call shape inference. |
-| `jz:rest` | Per-export rest-parameter info (`{ name, fixed }`) — tells JS how many fixed args precede the rest array so the wrapper packs the tail correctly (covers aliased re-exports). |
-| `jz:i64exp` | Per-export i64-ABI map — marks slots where pointers cross as i64 (dodging V8's NaN canonicalization) instead of f64. |
-| `jz:extparam` | Per-export externref-param positions — args that skip NaN-boxing (the jsstring carrier writes here), with `d` carrying `= ''` defaults. |
+## Performance
 
-Names are stable; binary layouts are not — re-derive from the latest `interop.js` if you parse them yourself.
+<img src="bench/bench.svg?v=5" alt="jz vs alternatives — geometric-mean speed across the bench corpus, every rival compiled to WebAssembly and run in V8 (apples-to-apples); native C is the lone reference, jz = 1.00× baseline" width="720">
 
-</details>
 
+See [bench →](https://dy.github.io/jz/bench/)
 
 ## Examples
 
-Runnable browser demos in [`examples/`](examples/) — each compiles a `.js` kernel to WASM and shares a typed array with a canvas (the memory-sharing pattern from [Interop](#interop)):
+<table>
+<tr>
+<td width="33%"><a href="https://dy.github.io/jz/examples/chladni/"><img src="examples/thumbs/chladni.webp" width="100%" alt="Chladni plate"></a><br><b>chladni</b> — frequency sweeps the nodal figure.</td>
+<td width="33%"><a href="https://dy.github.io/jz/examples/julia/"><img src="examples/thumbs/julia.webp" width="100%" alt="Julia set"></a><br><b>julia</b> — escape-time Julia set; drag the constant to morph it.</td>
+<td width="33%"><a href="https://dy.github.io/jz/examples/attractors/"><img src="examples/thumbs/attractors.webp" width="100%" alt="Strange attractor"></a><br><b>attractors</b> — de Jong map, luminous curves.</td>
+</tr>
+<tr>
+<td><a href="https://dy.github.io/jz/examples/raymarcher/"><img src="examples/thumbs/raymarcher.webp" width="100%" alt="SDF raymarcher"></a><br><b>raymarcher</b> — an SDF sphere field; Shadertoy on the CPU.</td>
+<td><a href="https://dy.github.io/jz/examples/nbody/"><img src="examples/thumbs/nbody.webp" width="100%" alt="N-body gravity"></a><br><b>nbody</b> — three-body gravity; fading trails trace the orbits.</td>
+<td><a href="https://dy.github.io/jz/examples/game-of-life/"><img src="examples/thumbs/game-of-life.webp" width="100%" alt="Game of Life"></a><br><b>game-of-life</b> — Conway's Life straight into shared pixel memory.</td>
+</tr>
+<tr>
+<td><a href="https://dy.github.io/jz/examples/plasma/"><img src="examples/thumbs/plasma.webp" width="100%" alt="Plasma"></a><br><b>plasma</b> — FBM domain-warp; the classic flowing shader plasma.</td>
+<td><a href="https://dy.github.io/jz/examples/cloth/"><img src="examples/thumbs/cloth.webp" width="100%" alt="Cloth simulation"></a><br><b>cloth</b> — Verlet mass-spring sheet; drag it, watch it settle.</td>
+<td><a href="https://dy.github.io/jz/examples/erosion/"><img src="examples/thumbs/erosion.webp" width="100%" alt="Terrain erosion"></a><br><b>erosion</b> — hydraulic droplets carve a fractal terrain.</td>
+</tr>
+</table>
 
-* [game-of-life](examples/game-of-life/) — Conway's Life writing the cell grid straight into shared pixel memory.
-* [interference](examples/interference/) — two-source wave interference field rendered per frame.
-* [mandelbrot](examples/mandelbrot/) — escape-time fractal with a precomputed color table.
+See [all examples →](https://dy.github.io/jz/examples/)
 
-Each folder has a `build.mjs` and an `index.html` — build, then open the page.
 
 
 ## Alternatives
 
-* [porffor](https://github.com/CanadaHonk/porffor) — ahead-of-time JS→WASM compiler targeting full TC39 semantics. Implements the spec progressively (test262). Where jz restricts the language for performance, porffor aims for completeness.
-* [assemblyscript](https://github.com/AssemblyScript/assemblyscript) — TypeScript-subset compiling to WASM — small, performant output, but requires type annotations.
-* [jawsm](https://github.com/drogus/jawsm) — JS→WASM compiler in Rust. Compiles standard JS with a runtime that provides GC and closures in WASM.
+Small & fast JS subset → full JS spec & bundled engine:
 
-<details>
-<summary><strong>Which one to choose?</strong></summary>
+* [AssemblyScript](https://github.com/AssemblyScript/assemblyscript) — TS-like dialect → WASM; small, fast output, but needs type annotations (not JS).
+* [awasm-compiler](https://github.com/paulmillr/awasm-compiler) — reproducible WASM assembled through a typed *builder API*.
+* [Porffor](https://github.com/CanadaHonk/porffor) — AOT JS→WASM (and C) targeting the full spec, grown against test262.
+* [Static Hermes](https://github.com/facebook/hermes) — Meta's AOT JS → native via C/LLVM (no WASM target); full speed needs sound type annotations, untyped JS stays dynamic.
+* [jawsm](https://github.com/drogus/jawsm) — JS→WASM in Rust on WasmGC; no interpreter, but leans on the engine's GC.
+* [Javy](https://github.com/bytecodealliance/javy) — embeds QuickJS; runs almost any JS, but ships a full interpreter (large, interpreter-speed).
+* [ComponentizeJS / jco](https://github.com/bytecodealliance/ComponentizeJS) — WASM Component via embedded SpiderMonkey; standards-complete, but bundles a JS engine.
 
-<br>
 
-| Pick | When |
-|---|---|
-| **jz** | You write plain JS, want tiny WASM and native-class numeric/DSP speed, and your code fits the subset. |
-| **porffor** | You need full TC39 / spec completeness. |
-| **AssemblyScript** | You're comfortable writing a typed TypeScript dialect for explicit low-level control. |
-| **jawsm** | You need to run standard JS *unchanged*, with GC and closures provided by a bundled WASM runtime. |
+## Built with
 
-The axis is completeness vs. cost: jz restricts the language to emit a runtime-free, native-speed binary; the others spend size/runtime to cover more of JS.
+* [**subscript**](https://github.com/dy/subscript) — JS parser. Minimal, extensible, builds the exact AST jz needs. Jessie subset keeps the grammar small and deterministic.
+* [**watr**](https://www.npmjs.com/package/watr) — WAT to WASM compiler. Binary encoding, validation, and peephole optimization. jz emits WAT text, watr turns it into valid `.wasm`.
 
-</details>
 
-## Build with
+## Contributing
 
-* [subscript](https://github.com/dy/subscript) — JS parser. Minimal, extensible, builds the exact AST jz needs without a full ES parser. Jessie subset keeps the grammar small and deterministic.
-* [watr](https://www.npmjs.com/package/watr) — WAT to WASM compiler. Handles binary encoding, validation, and peephole optimization. jz emits WAT text, watr turns it into a valid `.wasm` binary.
+Setup, code layout, and the bench/perf invariants are in [CONTRIBUTING.md](docs/CONTRIBUTING.md);
+the architecture & design rationale (NaN-boxing, type inference, native pipeline) in [DESIGN.md](docs/DESIGN.md).
 
 
 <p align=center>MIT • <a href="https://github.com/krishnized/license/">ॐ</a></p>