jz 0.1.1 → 0.2.1

package/README.md

@@ -1,8 +1,8 @@
-<img src="logo.svg" alt="jz logo" width="120"/>
+<img src="jz.svg" alt="jz logo" width="120"/>
 
 
 
-## ![stability](https://img.shields.io/badge/stability-experimental-black) [![test](https://github.com/dy/jz/actions/workflows/test.yml/badge.svg)](https://github.com/dy/jz/actions/workflows/test.yml)
+## ![stability](https://img.shields.io/badge/stability-experimental-black) [![npm](https://img.shields.io/npm/v/jz?color=gray)](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)
 
 
 **JZ** (_javascript zero_) is **minimal modern functional JS subset**, compiling to WASM.<br/>
@@ -17,18 +17,14 @@ dist(3, 4) // 5
 
 ## Why?
 
-**Write plain JS, compile to WASM** – fast, portable and long-lasting. JZ distills the modern functional core – the "good parts" [Crockford](https://www.youtube.com/watch?v=_DKkVvOt6dk) – from legacy semantics, specs evolution and perf quirks.
+**Write plain JS, compile to WASM** – fast, portable and long-lasting.<br>
+JZ distills the modern functional core – the "good parts" ([Crockford](https://www.youtube.com/watch?v=_DKkVvOt6dk)) – from legacy semantics, features overhead and perf quirks.
 
-* **Static** – no runtime, no GC, no dynamic constructs.
+* **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.
 <!-- * **Realtime** — compiles faster than `eval`, useful for live-coding and REPL. -->
 
-**Used by**: [web-audio-api](https://github.com/audiojs/web-audio-api), [color-space](https://github.com/colorjs/color-space), [audiojs](https://github.com/colorjs/audiojs). Inspired by [porffor](https://github.com/CanadaHonk/porffor) and [piezo](https://github.com/dy/piezo).
-<!-- * [audio-filter](https://github.com/audiojs/audio-filter)
-* [digital-filter](https://github.com/audiojs/digital-filter)
-* [time-stretch](https://github.com/audiojs/time-stretch) -->
-
 | Good for                    | Not for                    |
 |-----------------------------|----------------------------|
 | Numeric / math compute      | UI / frontend              |
@@ -36,6 +32,9 @@ dist(3, 4) // 5
 | Parsing / transforms        | Async / I/O-heavy logic    |
 | WASM utilities              | JavaScript runtime         |
 
+<!-- Inspired by [porffor](https://github.com/CanadaHonk/porffor) and [piezo](https://github.com/dy/piezo). -->
+<!-- Used internally by: web-audio-api, color-space, audiojs -->
+
 
 ## Usage
 
@@ -50,8 +49,33 @@ add(2, 3)  // 5
 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
+const asyncMod = await WebAssembly.compile(wasm)
+const asyncInst = await WebAssembly.instantiate(asyncMod)
+asyncInst.exports.f(21) // 42
 ```
 
+<details>
+<summary><strong>Options</strong></summary><br>
+
+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`, `==`, and `undefined` by lowering them to the JZ subset. |
+| `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, `3` enables aggressive experimental passes, object form overrides individual passes. |
+| `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. `profileNames` remains as a legacy alias. |
+
+</details>
+
 ## CLI
 
 `npm install -g jz`
@@ -102,56 +126,39 @@ flowchart TB
 │                                                                        │
 │ ┌────────────────────────────────────────────────────────────────────┐ │
 │ │ JZ                                                                 │ │
-│ │   let/const  =>  ...xs  destructuring  import/export  `${}`        │ │
+│ │   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  null     │ │
-│ │   Math  Number  String  Array  Object  JSON  RegExp  Symbol        │ │
+│ │   operators  strings  booleans  numbers  arrays  objects  `${}`    │ │
+│ │   Math  Number  String  Array  Object  JSON  RegExp  Symbol  null  │ │
 │ │   ArrayBuffer  DataView  TypedArray  Map  Set                      │ │
 │ │   console  setTimeout/setInterval  Date  performance               │ │
 │ └────────────────────────────────────────────────────────────────────┘ │
 └────────────────────────────────────────────────────────────────────────┘
-
 Not supported
   async/await  Promise  function*  yield
   this  class  super  extends  delete  labels
   eval  Function  with  Proxy  Reflect  WeakMap  WeakSet
   dynamic import  DOM  fetch  Intl  Node APIs
 ```
+## FAQ
 
+<details>
+<summary><strong>How to pass data between JS and WASM?</strong></summary>
 
-## Benchmark
-
-| | **jz** | [Node](https://nodejs.org/) | [AS](https://github.com/AssemblyScript/assemblyscript) | WAT | C | [Go](https://go.dev/) | [Rust](https://www.rust-lang.org/) |
-|---|---|---|---|---|---|---|---|
-| [**biquad**](bench/biquad/biquad.js) | **6.44 ms**<br>**3.4 kB** | 12.30 ms<br>3.2 kB | 9.04 ms<br>1.9 kB | 6.48 ms<br>767 B | 5.43 ms<br>32.7 kB | 9.03 ms<br>1.60 MB<br>fma | 5.33 ms<br>380.7 kB |
-| [**tokenizer**](bench/tokenizer/tokenizer.js) | **0.10 ms**<br>**1.6 kB** | 0.18 ms<br>1.4 kB | 0.08 ms<br>1.5 kB | — | 0.13 ms<br>32.9 kB | 0.07 ms<br>1.60 MB | 0.12 ms<br>380.7 kB |
-| [**mat4**](bench/mat4/mat4.js) | **4.00 ms**<br>**1.7 kB** | 11.64 ms<br>1.1 kB | 9.18 ms<br>1.5 kB | 7.99 ms<br>353 B | 2.62 ms<br>32.8 kB | 11.93 ms<br>1.60 MB | 0.80 ms<br>380.7 kB |
-| [**aos**](bench/aos/aos.js) | **1.50 ms**<br>**2.3 kB** | 1.81 ms<br>1.1 kB | 1.91 ms<br>2.2 kB | — | 1.22 ms<br>32.9 kB | 0.90 ms<br>1.60 MB | 1.20 ms<br>380.7 kB |
-| [**bitwise**](bench/bitwise/bitwise.js) | **4.93 ms**<br>**1.2 kB** | 5.31 ms<br>1005 B | 12.36 ms<br>1.5 kB | 4.96 ms<br>355 B | 1.31 ms<br>32.9 kB | 5.24 ms<br>1.60 MB | 1.30 ms<br>380.7 kB |
-| [**poly**](bench/poly/poly.js) | **1.13 ms**<br>**1.3 kB** | 2.31 ms<br>1014 B | 1.14 ms<br>1.3 kB | — | 0.52 ms<br>32.9 kB | 0.80 ms<br>1.60 MB | 0.52 ms<br>380.7 kB |
-| [**callback**](bench/callback/callback.js) | **0.01 ms**<br>**1.5 kB** | 1.03 ms<br>828 B | 1.48 ms<br>1.9 kB | — | 0.09 ms<br>32.9 kB | 0.20 ms<br>1.60 MB | 0.08 ms<br>380.7 kB |
-| [**json**](bench/json/json.js) | **0.20 ms**<br>**2.8 kB** | 0.38 ms<br>923 B | — | — | 0.02 ms<br>32.8 kB | 1.06 ms<br>1.97 MB | 0.03 ms<br>380.7 kB |
-| [**watr**](bench/watr/watr.js) | **1.82 ms**<br>**137.1 kB** | 1.50 ms<br>2.6 kB | — | — | — | — | — |
-
-_Numbers from `node bench/bench.mjs` on Apple Silicon, May 2026. `jz` uses host imports for benchmark timing/logging (measures wasm without WASI console/perf bloat). Raw-JS size is the entry file; jz size is the bundled wasm artifact. `fma` is the documented Go arm64 fused-multiply-add checksum class. See [benchmark](./bench/)._
-
-
-
-
-## FAQ
+<br>
 
-### How to pass data between JS and WASM?
 
-Numbers pass directly as f64. Strings, arrays, objects, and typed arrays are heap values — `inst.memory` provides read/write across the boundary:
+Numbers pass directly as f64, arrays of ≤ 8 elements return as plain JS arrays (multi-value). Strings, arrays, objects, and typed arrays are heap values — `inst.memory` provides read/write across the boundary:
 
 ```js
-const { exports, memory } = jz(\`
+const { exports, memory } = jz`
   export let greet = (s) => s.length
   export let sum = (a) => a.reduce((s, x) => s + x, 0)
   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)
-\`)
+`
 
 // JS → WASM (write)
 memory.String('hello')               // → string pointer
@@ -159,8 +166,9 @@ memory.Array([1, 2, 3])              // → array pointer
 memory.Float64Array([1.0, 2.0])      // → typed array pointer
 memory.Int32Array([10, 20, 30])      // all typed array constructors available
 
-// Objects: keys and order must match the jz source declaration.
+// ⚠ Objects: keys and order must match the jz source declaration.
 // jz objects are fixed-layout schemas (like C structs), not dynamic key bags.
+// If the jz source declares `{ x, y }`, you must pass `{ x, y }` in that order.
 memory.Object({ x: 3, y: 4 })       // → object pointer
 
 // Strings/arrays inside objects are auto-wrapped to pointers:
@@ -171,14 +179,17 @@ exports.greet(memory.String('hello'))          // 5
 exports.sum(memory.Array([1, 2, 3]))           // 6
 exports.dist(memory.Object({ x: 3, y: 4 }))   // 5
 
-// WASM → JS (read)
+// direct JS array return
+exports.rgb(100)      // [100, 50, 20]
+
+// read pointer value
 memory.read(exports.process(memory.Float64Array([1, 2, 3])))  // Float64Array [2, 4, 6]
 ```
 
 Template interpolation handles most of this automatically — strings, arrays, numbers, and numeric objects are marshaled for you:
 
 ```js
-jz\`export let f = () => ${'hello'}.length + ${[1,2,3]}[0] + ${{x: 5, y: 10}}.x\`
+jz`export let f = () => ${'hello'}.length + ${[1,2,3]}[0] + ${{x: 5, y: 10}}.x`
 ```
 
 <!--
@@ -209,7 +220,12 @@ All values are IEEE 754 f64 (at WASM boundary). Integers up to 2^53 are exact. H
 **NaN preservation**: IEEE 754 defines 2^52 − 1 distinct NaN bit patterns. WASM preserves NaN payload bits through arithmetic (spec requires `nondeterministic_nan`), and JS engines canonicalize only on certain operations (`Math.fround`, structured clone). jz uses quiet NaNs (`0x7FF8` prefix) which survive all standard paths. The 51 payload bits encode type (4), aux metadata (15), and heap offset (32) — enough for 4GB addressable memory and 12 type codes.
 -->
 
-### How does template interpolation work?
+</details>
+
+<details>
+<summary><strong>How does template interpolation work?</strong></summary>
+
+<br>
 
 Numbers and booleans inline directly into source. Strings, arrays, and objects are serialized as jz source literals and compiled at compile time — no post-instantiation allocation, no getter overhead:
 
@@ -224,66 +240,84 @@ jz`export let f = () => ${{label: 'origin', x: 0, y: 0}}.label.length`  // 6
 
 Functions are imported as host calls. Non-serializable values (host objects, class instances) fall back to post-instantiation getters automatically.
 
-### Does it support imports?
+</details>
+
+<details>
+<summary><strong>Does it support ES module imports?</strong></summary>
 
-Yes — standard ES `import` syntax, bundled at compile-time into one WASM.
+<br>
+
+Yes — standard ES `import` syntax is bundled at compile-time into a single WASM.
 
 ```js
-// modules: jz source bundled at compile time
 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' } }
 )
-
-// imports: JS functions wired at instantiation
-const { exports } = jz(
-  'import { log } from "host"; export let f = (x) => { log(x); return x }',
-  { imports: { host: { log: console.log } } }
-)
 ```
 
 Transitive imports work (main → math → utils → …). Circular imports error at compile time. Output is always one WASM binary — no runtime resolution.
 
-You can also pass whole host environment objects — `Math`, `Date`, `window`, `console`, or any custom namespace object. jz extracts the functions it needs via `Object.getOwnPropertyNames`, so non-enumerable built-ins (like `Math.sin`) work automatically:
+**CLI** resolves filesystem imports automatically.
+
+```sh
+jz main.jz -o main.wasm    # reads ./math.jz, ./utils.jz automatically
+```
+
+**Browser**: fetch sources yourself, pass via `{ modules }`. The compiler stays synchronous and pure — no I/O.
 
 ```js
-// Pass the entire Math namespace — sin, cos, sqrt, PI, etc. auto-wired
+// Transitive bundling — all merged into one WASM
+const { exports } = jz(mainSrc, { modules: {
+  './math.jz': 'import { sq } from "./utils.jz"; export let dist = (x, y) => (sq(x) + sq(y)) ** 0.5',
+  // Fetch sources yourself, pass them in
+  './utils.jz': await fetch('./util.jz').then(r => r.text())
+} })
+```
+
+</details>
+
+<details>
+<summary><strong>How do I pass values from the host to jz?</strong></summary>
+
+<br>
+
+Any host namespace — functions, constants, custom objects — wires in via the `imports` option. jz extracts what's needed via `Object.getOwnPropertyNames`, so non-enumerable built-ins (`Math.sin`, `Date.now`) work automatically:
+
+```js
+// Custom function
+const { exports } = jz(
+  'import { log } from "host"; export let f = (x) => { log(x); return x }',
+  { imports: { host: { log: console.log } } }
+)
+
+// Whole namespace — sin, cos, sqrt, PI, etc. all auto-wired
 const { exports } = jz(
   'import { sin, PI } from "math"; export let f = () => sin(PI / 2)',
   { imports: { math: Math } }
 )
 
-// Pass Date static methods
+// Date static methods
 const { exports } = jz(
   'import { now } from "date"; export let f = () => now()',
   { imports: { date: Date } }
 )
 
-// Pass window / globalThis
+// window / globalThis
 const { exports } = jz(
   'import { parseInt } from "window"; export let f = () => parseInt("42")',
   { imports: { window: globalThis } }
 )
 ```
 
-**CLI** resolves filesystem imports automatically.
-
-```sh
-jz main.jz -o main.wasm    # reads ./math.jz, ./utils.jz automatically
-```
+For per-call data (numbers, strings, arrays, objects, typed arrays), see *How to pass data between JS and WASM?* above — pointers via `memory.String`/`memory.Array`/`memory.Object` or template interpolation.
 
-**Browser**: fetch sources yourself, pass via `{ modules }`. The compiler stays synchronous and pure — no I/O.
+</details>
 
-```js
-// Transitive bundling — all merged into one WASM
-const { exports } = jz(mainSrc, { modules: {
-  './math.jz': 'import { sq } from "./utils.jz"; export let dist = (x, y) => (sq(x) + sq(y)) ** 0.5',
-  // Fetch sources yourself, pass them in
-  './utils.jz': await fetch('./util.jz').then(r => r.text())
-} })
-```
+<details>
+<summary><strong>Can two modules share data?</strong></summary>
 
-### Can two modules share data?
+<br>
 
 Yes — `jz.memory()` creates a shared memory that modules compile into. Schemas accumulate automatically, so objects created in one module are readable by another:
 
@@ -306,10 +340,54 @@ memory.Array([1, 2, 3])     // → NaN-boxed pointer
 
 `jz.memory()` returns an actual `WebAssembly.Memory` (monkey-patched with `.read()`, `.String()`, `.Array()`, `.Object()`, `.write()`, etc). You can also pass an existing memory: `jz.memory(new WebAssembly.Memory({ initial: 4 }))` patches and returns the same object. Passing raw `WebAssembly.Memory` to `{ memory }` auto-wraps it.
 
-All modules sharing a memory use a single bump allocator (heap pointer at byte 1020). Use `.instance.exports` for raw pointers, `.exports` for the JS-wrapped surface.
+Modules sharing a memory share a single bump allocator — see *How does memory work?* below. Use `.instance.exports` for raw pointers, `.exports` for the JS-wrapped surface.
+
+
+</details>
+
+<details>
+<summary><strong>How does memory work? How do I reset it?</strong></summary>
+
+<br>
+
+jz uses a **bump allocator**: every heap value (string, array, object, typed array) bumps a single pointer forward. No free list, no GC, no per-object header overhead beyond `[len][cap]`. Bytes 0–1023 are reserved (data segment + heap-pointer slot at byte 1020); the heap starts at byte 1024 and grows the WASM memory automatically when full.
+
+This means **memory is never reclaimed implicitly** — long-running programs that allocate per call will grow without bound. The fix is to reset the heap pointer between independent batches:
+
+```js
+const { exports, memory } = jz`
+  export let process = (n) => {
+    let xs = []
+    for (let i = 0; i < n; i++) xs.push(i * 2)
+    return xs.reduce((s, x) => s + x, 0)
+  }
+`
+
+for (let i = 0; i < 1000; i++) {
+  const sum = exports.process(100)   // allocates an array each call
+  memory.reset()                     // drop everything; heap ptr → 1024
+}
+```
+
+After `memory.reset()` all previously returned pointers are invalid — read what you need first, then reset.
+
+For finer control, allocate manually: `memory.alloc(bytes)` returns a raw offset using the same bump pointer. Pure scalar modules (no strings/arrays/objects) are compiled without the allocator at all — no `_alloc`, no `_clear`, no memory section.
+
+**Non-JS hosts** (wasmtime, wasmer, deno, EdgeJS, embedded WASM) get the same allocator via two exports:
+
+```
+(func $_alloc (param $bytes i32) (result i32))   ;; returns heap offset
+(func $_clear)                                    ;; rewinds heap pointer to 1024
+```
+
+`memory.reset()` and `memory.alloc()` are JS-side 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 pointer crossing the WASM boundary 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. Call `_clear()` between batches to reclaim. Strip both with `compile(code, { alloc: false })` if you only call functions and never marshal heap values across the boundary.
+
+</details>
 
+<details>
+<summary><strong>How do I run compiled WASM outside the browser?</strong></summary>
 
-### How do I run compiled WASM outside the browser?
+<br>
 
 ```sh
 jz program.js -o program.wasm
@@ -321,33 +399,78 @@ deno run program.wasm
 ```
 
 Pure numeric modules have no imports and instantiate with standard
-`WebAssembly.Module` / `WebAssembly.Instance`, which is the right shape for JS
-hosts such as EdgeJS. Compile once at startup or build time, then reuse the
-module; do not compile JZ source per request.
+`WebAssembly.Module` / `WebAssembly.Instance`, which is the right shape for JS hosts such as EdgeJS. Compile once at startup or build time, then reuse the module; do not compile JZ source per request.
+
+Two host modes select how runtime services lower:
+
+```js
+jz.compile(code)                      // host: 'js' (default) — env.* imports
+jz.compile(code, { host: 'wasi' })    // wasi_snapshot_preview1.* imports
+```
+
+`host: 'js'` (default) — `console.log`/`Date.now`/`performance.now` import from `env.*` and the JS host (`jz()` runtime) wires them automatically. Host-side stringification means jz drops `__ftoa`/`__write_*`/`__to_str` from the binary.
 
-`console.log` compiles to WASI `fd_write` by default — works natively on
-wasmtime/wasmer/deno without polyfills. In JS hosts, `jz()` auto-applies the
-small `jz/wasi` polyfill; pass `{ write(fd, text) { ... } }` to capture or route
-stdout/stderr without depending on `process.stdout`.
+`host: 'wasi'` — `console.log` compiles to WASI `fd_write`, clocks to
+`clock_time_get`. Output runs natively on wasmtime/wasmer/deno. In JS hosts, the small `jz/wasi` polyfill is auto-applied; pass `{ write(fd, text) {…} }` to capture stdout/stderr. `host: 'wasi'` errors at compile time if a program would emit `env.__ext_*` (dynamic dispatch into the JS host) — annotate the receiver or stay on `host: 'js'`.
 
+</details>
 
-### What host features are supported?
+<details>
+<summary><strong>What host features are supported?</strong></summary>
 
-The compiled `.wasm` uses one import namespace:
+<br>
+
+| JS API | `host: 'js'` (default) | `host: 'wasi'` |
+|---|---|---|
+| `console.log()` | `env.print(val: i64, fd: i32, sep: i32)` — host stringifies | WASI `fd_write` (fd=1), space-separated, newline appended |
+| `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`/`clearTimeout` | `env.setTimeout(cb, delay, repeat) -> f64` / `env.clearTimeout(id) -> f64` — host schedules; fires via exported `__invoke_closure` | WASM timer queue + `__timer_tick` (or blocking `__timer_loop` on wasmtime) |
+| `setInterval`/`clearInterval` | same `env.setTimeout` (repeat=1) / `env.clearTimeout` | WASM timer queue + `__timer_tick` |
+| dynamic `obj.method()` | `env.__ext_call` (JS resolves) | error at compile time |
+
+The compiled `.wasm` uses at most one import namespace:
 
 - none — pure scalar/compute modules. Instantiate directly with standard WebAssembly APIs.
-- `wasi_snapshot_preview1` — standard WASI Preview 1 calls. Run natively on wasmtime, wasmer, deno; for browsers/Node/EdgeJS-like hosts, jz ships a tiny polyfill (`jz/wasi`) auto-applied by the `jz()` runtime.
+- `env` — JS-host services (default). Auto-wired by the `jz()` runtime.
+- `wasi_snapshot_preview1` — standard WASI Preview 1. Run natively on wasmtime/wasmer/deno.
+
+</details>
+
+<details>
+<summary><strong>How do I add custom operators / extend the stdlib?</strong></summary>
 
-| JS API | Maps to | Notes |
-|--------|---------|-------|
-| `console.log()` | WASI `fd_write` (fd=1) | Multiple args space-separated, newline appended |
-| `console.warn()`, `console.error()` | WASI `fd_write` (fd=2) | Writes to stderr |
-| `Date.now()` | WASI `clock_time_get` (realtime) | Returns ms since epoch |
-| `performance.now()` | WASI `clock_time_get` (monotonic) | Returns ms, high-resolution |
-| `setTimeout`, `clearTimeout` | WASM timer queue + `__timer_tick` | JS runtime drives tick via `setInterval`; wasmtime uses blocking `__timer_loop` |
-| `setInterval`, `clearInterval` | WASM timer queue + `__timer_tick` | Same — native WASM implementation, no host imports |
+<br>
 
-### Can I compile jz to C?
+jz's emitter table (`ctx.core.emit`) maps AST operators → WASM IR generators. Module files in `module/` register handlers on it. To add your own:
+
+```js
+import { emitter } from './src/emit.js'
+import { typed } from './src/ir.js'
+
+// Register a custom operator: my.double(x) → x * 2
+emitter['my.double'] = (x) => {
+  return ['f64.mul', ['f64.const', 2], typed(x, 'f64')]
+}
+```
+
+The naming convention follows the AST path: `Math.sin` → `math.sin`, `arr.push` → `.push`, typed variants like `.f64:push`. See any file in `module/` for the full pattern — each exports a function that receives `ctx` and registers emitters, stdlib, globals, or helpers.
+
+Inside a runtime module, import directly from the layer you need:
+
+```js
+import { emit } from '../src/emit.js'
+import { asF64, temp } from '../src/ir.js'
+import { valTypeOf, VAL } from '../src/analyze.js'
+```
+
+</details>
+
+<details>
+<summary><strong>Can I compile jz to C?</strong></summary>
+
+<br>
 
 Yes, via [wasm2c](https://github.com/WebAssembly/wabt/blob/main/wasm2c) or [w2c2](https://github.com/turbolent/w2c2):
 
@@ -356,6 +479,49 @@ jz program.js -o program.wasm
 wasm2c program.wasm -o program.c
 cc program.c -o program
 ```
+</details>
+
+
+## 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) | 4.63ms<br>4.0kB | 8.68ms<br>3.2kB | fails | 6.59ms<br>1.9kB | 6.45ms<br>767 B | 5.30ms | 8.91ms<br>fma | 5.06ms | 5.28ms | 3.12s |
+| [tokenizer](bench/tokenizer/tokenizer.js) | 0.07ms<br>1.8kB | 0.12ms<br>1.4kB | 0.34ms<br>2.6kB | 0.05ms<br>1.5kB | 0.08ms<br>344 B | 0.14ms | 0.07ms | 0.12ms | 0.12ms | 5.15ms |
+| [mat4](bench/mat4/mat4.js) | 2.12ms<br>3.7kB | 11.80ms<br>1.2kB | 88.54ms<br>2.4kB<br>diff | 9.21ms<br>1.6kB | 8.06ms<br>414 B | 2.73ms | 11.93ms | 2.73ms | 1.77ms | 387.60ms |
+| [aos](bench/aos/aos.js) | 1.11ms<br>2.3kB | 1.26ms<br>1.1kB | fails | 1.33ms<br>2.2kB | 1.07ms<br>481 B | 1.20ms | 0.91ms | 0.91ms | 1.20ms | 2.57ms |
+| [mandelbrot](bench/mandelbrot/mandelbrot.js) | 8.02ms<br>1.2kB | 9.06ms<br>1.8kB | 9.71ms<br>3.0kB | 8.00ms<br>1.3kB | — | 8.31ms | 8.80ms | 7.83ms | 8.52ms | — |
+| [bitwise](bench/bitwise/bitwise.js) | 0.98ms<br>1.3kB | 3.76ms<br>1005 B | fails | 8.79ms<br>1.5kB | 4.86ms<br>355 B | 1.30ms | 5.20ms | 4.15ms | 1.30ms | 14.72ms |
+| [poly](bench/poly/poly.js) | 0.27ms<br>1.4kB | 1.62ms<br>1014 B | fails | 0.73ms<br>1.3kB | 0.81ms<br>359 B | 0.57ms | 0.79ms | 0.89ms | 0.63ms | 0.60ms |
+| [callback](bench/callback/callback.js) | 0.03ms<br>1.6kB | 0.69ms<br>828 B | fails | 1.04ms<br>1.9kB | 0.24ms<br>267 B | 0.08ms | 0.23ms | 0.01ms | 0.12ms | 1.78ms |
+| [json](bench/json/json.js) | 0.24ms<br>11.0kB | 0.37ms<br>1.2kB | fails | — | — | 0.03ms | 1.05ms | <0.01ms | 0.03ms | 1.21ms |
+| [watr](bench/watr/watr.js) | 1.04ms<br>169.8kB | 1.05ms<br>2.6kB | fails | — | — | — | — | — | — | — |
+
+_Numbers from `node bench/bench.mjs` on Apple Silicon. Porffor cells were refreshed with `porf` 0.61.13; `fails` means the latest Porffor compiler/runtime did not complete that benchmark._
+
+<details>
+<summary><strong>Optimizations</strong></summary>
+
+<br>
+High-impact summary behind the benchmark table, not an exhaustive list.
+
+| 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-pin` 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.
+
+</details>
 
 
 ## Alternatives

package/cli.js

@@ -6,7 +6,9 @@
 
 import { readFileSync, writeFileSync, existsSync } from 'fs'
 import { dirname, resolve, join } from 'path'
-import { parse } from 'subscript/jessie'
+import { pathToFileURL } from 'url'
+import { execFileSync } from 'child_process'
+import { parse } from 'subscript/feature/jessie'
 import jz, { compile } from './index.js'
 import jzifyFn, { codegen } from './src/jzify.js'
 
@@ -36,6 +38,7 @@ Options:
   --jzify                   Transform JS to jz (no compilation)
   --eval, -e                Evaluate expression or file
   --wat                     Output WAT text instead of binary
+  --resolve                 Resolve bare specifiers via Node.js module resolution
   `)
 }
 
@@ -96,12 +99,13 @@ async function handleJzify(args) {
 }
 
 async function handleCompile(args) {
-  let inputFile = null, outputFile = null, wat = false, strict = false
+  let inputFile = null, outputFile = null, wat = false, strict = false, resolveNode = false
 
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--output' || args[i] === '-o') outputFile = args[++i]
     else if (args[i] === '--wat') wat = true
     else if (args[i] === '--strict') strict = true
+    else if (args[i] === '--resolve') resolveNode = true
     else if (!inputFile) inputFile = args[i]
   }
 
@@ -126,21 +130,43 @@ async function handleCompile(args) {
     } catch {}
   }
 
+  // Recursively resolve relative imports from entry file and all discovered modules
   const importRe = /import\s+.*?\s+from\s+['"]([^'"]+)['"]/g
-  let m; while ((m = importRe.exec(code)) !== null) {
-    const spec = m[1]
-    if (!modules[spec] && (spec.startsWith('./') || spec.startsWith('../'))) {
-      const full = resolve(dir, spec)
-      try { modules[spec] = readFileSync(full, 'utf8') }
-      catch { try { modules[spec] = readFileSync(full + '.js', 'utf8') } catch {} }
+  const resolveBareModule = (specifier, fromDir) => execFileSync(
+    process.execPath,
+    ['--input-type=module', '-e', 'process.stdout.write(import.meta.resolve(process.argv[1]))', specifier],
+    { cwd: fromDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+  ).trim()
+  const resolveModule = (specifier, fromDir) => {
+    if (modules[specifier]) return
+    // Relative imports: resolve from filesystem
+    if (specifier.startsWith('./') || specifier.startsWith('../')) {
+      const full = resolve(fromDir, specifier)
+      let src
+      try { src = readFileSync(full, 'utf8') }
+      catch { try { src = readFileSync(full + '.js', 'utf8') } catch { return } }
+      modules[specifier] = src
+      let m; importRe.lastIndex = 0
+      while ((m = importRe.exec(src)) !== null) resolveModule(m[1], dirname(full))
+      return
+    }
+    // Bare specifiers: opt-in Node.js resolution
+    if (resolveNode) {
+      try {
+        const resolved = resolveBareModule(specifier, fromDir)
+        if (resolved.startsWith('file:')) modules[specifier] = readFileSync(new URL(resolved), 'utf8')
+      } catch {}
     }
   }
+  let m; importRe.lastIndex = 0
+  while ((m = importRe.exec(code)) !== null) resolveModule(m[1], dir)
 
   // .jz = strict (no auto-transform), .js = auto-jzify
   // --strict forces strict for any extension
   const opts = {
     wat,
     jzify: !strict && !inputFile.endsWith('.jz'),
+    importMetaUrl: pathToFileURL(resolve(inputFile)).href,
     ...(Object.keys(modules).length && { modules }),
   }