jz 0.1.0 → 0.2.0

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,16 +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, features overhead 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. -->
 
-Inspired by [porffor](https://github.com/CanadaHonk/porffor) and [piezo](https://github.com/dy/piezo).
-<!-- Used internally by: web-audio-api, color-space, audiojs -->
-
 | Good for                    | Not for                    |
 |-----------------------------|----------------------------|
 | Numeric / math compute      | UI / frontend              |
@@ -34,6 +32,9 @@ Inspired by [porffor](https://github.com/CanadaHonk/porffor) and [piezo](https:/
 | 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
 
@@ -48,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. `memoryPages` remains as a legacy alias for the page count. |
+| `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`
@@ -78,7 +104,7 @@ flowchart TB
     subgraph JS[JS — not supported]
         subgraph JZify[JZ + jzify]
             subgraph JZ[JZ strict]
-                j1["let/const, arrows, default/rest params, flow, break/continue, try/catch, a[]/a()/a.b, operators, strings, booleans, numbers, std, memory, host"]:::plain
+                j1["let/const, arrows, default/rest params, flow, break/continue, try/catch/finally, a[]/a()/a.b, operators, strings, booleans, numbers, std, memory, host"]:::plain
             end
             z1["var, function, arguments, switch, new Foo(), ==, !=, instanceof"]:::plain
         end
@@ -94,12 +120,12 @@ flowchart TB
 
 ```
 ┌────────────────────────────────────────────────────────────────────────┐
-│ JZify                                                    test262: 68%  │
+│ JZify                                                                  │
 │   var  function  arguments  switch  new Foo()                          │
 │   ==  !=  instanceof  undefined                                        │
 │                                                                        │
 │ ┌────────────────────────────────────────────────────────────────────┐ │
-│ │ JZ                                                   test262: 54%  │ │
+│ │ JZ                                                                 │ │
 │ │   let/const  =>  ...xs  destructuring  import/export               │ │
 │ │   if/else  for/while/do-while/of/in  break/continue                │ │
 │ │   try/catch/finally  throw                                         │ │
@@ -109,29 +135,30 @@ flowchart TB
 │ │   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>
 
+<br>
 
-## FAQ
-
-### 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
@@ -152,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`
 ```
 
 <!--
@@ -190,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:
 
@@ -205,7 +240,12 @@ 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 ES module imports?
+</details>
+
+<details>
+<summary><strong>Does it support ES module imports?</strong></summary>
+
+<br>
 
 Yes — standard ES `import` syntax is bundled at compile-time into a single WASM.
 
@@ -235,40 +275,49 @@ const { exports } = jz(mainSrc, { modules: {
 } })
 ```
 
-### Can I call JS/host functions from jz?
+</details>
 
-Yes — JS functions are wired at instantiation via the `imports` option:
+<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 } } }
 )
-```
-
-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:
 
-```js
-// Pass the entire Math namespace — sin, cos, sqrt, PI, etc. auto-wired
+// 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 } }
 )
 ```
 
-### Can two modules share data?
+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.
+
+</details>
+
+<details>
+<summary><strong>Can two modules share data?</strong></summary>
+
+<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:
 
@@ -291,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>
 
-### How do I run compiled WASM outside the browser?
+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>
+
+<br>
 
 ```sh
 jz program.js -o program.wasm
@@ -305,40 +398,79 @@ wasmer run program.wasm
 deno run program.wasm
 ```
 
-`console.log` compiles to WASI `fd_write` — works natively on wasmtime/wasmer/deno without polyfills.
+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.
 
+Two host modes select how runtime services lower:
 
-### What host features are supported?
+```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.
+
+`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>
+
+<details>
+<summary><strong>What host features are supported?</strong></summary>
+
+<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 one import namespace:
+The compiled `.wasm` uses at most one import namespace:
 
-- `wasi_snapshot_preview1` — standard WASI Preview 1 calls. Run natively on wasmtime, wasmer, deno; for browsers/Node, jz ships a tiny polyfill (`jz/wasi`) auto-applied by the `jz()` runtime.
+- none — pure scalar/compute modules. Instantiate directly with standard WebAssembly APIs.
+- `env` — JS-host services (default). Auto-wired by the `jz()` runtime.
+- `wasi_snapshot_preview1` — standard WASI Preview 1. Run natively on wasmtime/wasmer/deno.
 
-| 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 |
+</details>
 
-### How do I add custom operators / extend the stdlib?
+<details>
+<summary><strong>How do I add custom operators / extend the stdlib?</strong></summary>
+
+<br>
 
 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 'jz/src/compile.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], 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 registers emitters and stdlib on `ctx`.
+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>
 
-### Can I compile jz to C?
+<br>
 
 Yes, via [wasm2c](https://github.com/WebAssembly/wabt/blob/main/wasm2c) or [w2c2](https://github.com/turbolent/w2c2):
 
@@ -347,23 +479,50 @@ jz program.js -o program.wasm
 wasm2c program.wasm -o program.c
 cc program.c -o program
 ```
+</details>
 
 
 ## Benchmark
 
-| | **jz** | [Node](https://nodejs.org/) | [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/) | [Porffor](https://github.com/CanadaHonk/porffor) |
+| | 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.44ms**<br>**3.4kB** | 12.30ms<br>3.2kB | 9.04ms<br>1.9kB | 6.48ms<br>767 B | 5.43ms | 9.03ms<br>fma | 5.09ms | 5.33ms | 3.15s | — |
-| [**tokenizer**](bench/tokenizer/tokenizer.js) | **0.10ms**<br>**1.6kB** | 0.18ms<br>1.4kB | 0.08ms<br>1.5kB | — | 0.13ms | 0.07ms | 0.12ms | 0.12ms | 5.21ms | 0.46ms<br>2.6kB |
-| [**mat4**](bench/mat4/mat4.js) | **4.00ms**<br>**1.7kB** | 11.64ms<br>1.1kB | 9.18ms<br>1.5kB | 7.99ms<br>353 B | 2.62ms | 11.93ms | 2.60ms | 0.80ms | 323.69ms | 87.65ms<br>2.3kB |
-| [**aos**](bench/aos/aos.js) | **1.50ms**<br>**2.3kB** | 1.81ms<br>1.1kB | 1.91ms<br>2.2kB | — | 1.22ms | 0.90ms | 0.99ms | 1.20ms | 2.23ms | — |
-| [**bitwise**](bench/bitwise/bitwise.js) | **4.93ms**<br>**1.2kB** | 5.31ms<br>1005 B | 12.36ms<br>1.5kB | 4.96ms<br>355 B | 1.31ms | 5.24ms | 4.26ms | 1.30ms | 14.89ms | — |
-| [**poly**](bench/poly/poly.js) | **1.13ms**<br>**1.3kB** | 2.31ms<br>1014 B | 1.14ms<br>1.3kB | — | 0.52ms | 0.80ms | — | 0.52ms | 0.60ms | — |
-| [**callback**](bench/callback/callback.js) | **0.01ms**<br>**1.5kB** | 1.03ms<br>828 B | 1.48ms<br>1.9kB | — | 0.09ms | 0.20ms | 0.01ms | 0.08ms | 1.84ms | — |
-| [**json**](bench/json/json.js) | **0.20ms**<br>**2.8kB** | 0.38ms<br>923 B | — | — | 0.02ms | 1.06ms | — | 0.03ms | 1.19ms | — |
-| [**watr**](bench/watr/watr.js) | **1.82ms**<br>**137.1kB** | 1.50ms<br>85.3kB | — | — | — | — | — | — | — | — |
-
-_Numbers from `node bench/bench.mjs` on Apple Silicon._
+| [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 |
+| [json-dynamic](bench/json-dynamic/json-dynamic.js) | 0.24ms<br>11.3kB | 0.39ms<br>1.2kB | — | — | — | — | — | — | — | — |
+| [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 }),
   }