jz 0.6.0 → 0.7.0

package/README.md

@@ -4,7 +4,6 @@
 
 **jz** (_javascript zero_) is **minimal functional JS** that compiles to performant WASM.
 
-
 ```js
 import jz from 'jz'
 
@@ -12,19 +11,23 @@ const { exports: { dist } } = jz`export let dist = (x, y) => (x*x + y*y) ** 0.5`
 dist(3, 4) // 5
 ```
 
-**[repl](https://dy.github.io/jz/repl/)** · **[examples](https://dy.github.io/jz/examples/)** · **[bench](https://dy.github.io/jz/bench/)**
+**[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/)**
 
 
 ## Why?
 
-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 portable WASM ([known divergences](#faq)).
+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                   |
+|------------------------------|---------------------------|
+| 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 |
 
-| 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         |
+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
@@ -32,7 +35,7 @@ jz distills **"the good parts"** ([Crockford](https://www.youtube.com/watch?v=_D
 `npm install jz`
 
 ```js
-import jz, { compile } from 'jz'
+import jz, { compile, compileModule, instantiate } from 'jz'
 
 // Compile + instantiate
 const { exports: { add } } = jz('export let add = (a, b) => a + b')
@@ -41,6 +44,10 @@ add(2, 3)  // 5
 // Compile only — raw WASM binary
 const wasm = compile('export let f = (x) => x * 2')
 
+// 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)
@@ -56,14 +63,20 @@ Options are passed as `jz(source, opts)` or `compile(source, opts)`. Common ones
 |---|---|
 | `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. |
+| `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` size-only, `true`/`2` default (all stable passes), `3` trades size for speed. String aliases: `'size'`, `'balanced'` (= default), `'speed'`. Object form overrides individual passes. |
+| `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. |
-| `profile` | Mutable sink for compile-stage timings; set `profile.names = true` for a WASM `name` section. |
+| `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
@@ -74,7 +87,7 @@ Options are passed as `jz(source, opts)` or `compile(source, opts)`. Common ones
 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 size, -O2 balanced, -O3 speed
+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
@@ -84,7 +97,7 @@ jz -e "1 + 2"              # eval → 3
 <summary><code>jz --help</code></summary>
 
 ```
-jz v0.5.1 - min JS → WASM compiler
+jz - min JS → WASM compiler
 
 Usage:
   jz <file.js>              Compile JS to WASM (full JS subset; .jz = strict)
@@ -98,8 +111,10 @@ Examples:
   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                # aggressive optimization
+  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
@@ -107,11 +122,22 @@ Examples:
 
 Options:
   --output, -o <file>       Output file (.wat, .wasm, or - for stdout)
-  -O<n>, --optimize <n>     Optimization level: 0 off, 1 size-only, 2 default,
-                            3 aggressive. Aliases: -Os/size, -Ob/balanced, -Of/speed.
+  -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
@@ -345,7 +371,7 @@ No runtime, no GC — a module is your code plus a small bump allocator. The geo
 
 - **`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 `profile.names`).
+- **`host: 'wasi'`** — no JS-host import shims (the debug `name` section is already off unless you set `names: true`).
 
 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)).
 
@@ -363,7 +389,7 @@ Ordinary JS is already fast — jz infers the right machine type for your number
 - **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.
 
-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` or `'size'`/`'balanced'`/`'speed'` (or a per-pass object): `'balanced'` (= `2`) is the default; `'speed'` trades size for inlined constants and larger buffers; `'size'` drops unrolling and SIMD.
+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).
 
 </details>
 
@@ -371,9 +397,9 @@ Codegen also adapts to the target: `host: 'js'` lowers `console`/timers to tiny
 <summary><strong>How do I inspect or debug the output?</strong></summary>
 
 - **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.
+- **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: `profile.names = true`) emits a wasm `name` section so DevTools profilers and disassemblers show real function names; the `profile` option collects per-stage compile timings.
+- **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.
 
 </details>
@@ -462,49 +488,40 @@ The full native pipeline (jz → `wasm-opt -O3` → `wasm2c` → `clang -O3 -flt
 
 
 
-
-
 ## Performance
 
-Geomean speed across the [bench corpus →](bench/README.md).
-
-<img src="bench/bench.svg?v=2" alt="jz vs alternatives — geomean speed across the bench corpus" width="720">
+<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">
 
-<sub>Local snapshot (M4 Max, darwin/arm64). Bun/Zig/Rust/Go/NumPy rows are hand-run reference points.</sub>
 
+See [bench →](https://dy.github.io/jz/bench/)
 
 ## Examples
 
 <table>
 <tr>
-<td width="33%"><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>
-<td width="33%"><a href="https://dy.github.io/jz/examples/lenia/"><img src="examples/thumbs/lenia.webp" width="100%" alt="Lenia"></a><br><b>lenia</b> — continuous cellular automaton; smooth-kernel "digital life".</td>
-<td width="33%"><a href="https://dy.github.io/jz/examples/diffusion/"><img src="examples/thumbs/diffusion.webp" width="100%" alt="Diffusion"></a><br><b>diffusion</b> — Gray-Scott; organic coral / labyrinths.</td>
+<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/interference/"><img src="examples/thumbs/interference.webp" width="100%" alt="Wave interference"></a><br><b>interference</b> — two-source wave field, recomputed every frame.</td>
-<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/chladni/"><img src="examples/thumbs/chladni.webp" width="100%" alt="Chladni plate"></a><br><b>chladni</b> — Camerata-style plate; frequency sweeps the nodal figure.</td>
-</tr>
-<tr>
-<td><a href="https://dy.github.io/jz/examples/mandelbrot/"><img src="examples/thumbs/mandelbrot.webp" width="100%" alt="Mandelbrot set"></a><br><b>mandelbrot</b> — escape-time fractal with smooth coloring.</td>
-<td><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, millions of iters → luminous curves.</td>
 <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/rfft/"><img src="examples/thumbs/rfft.webp" width="100%" alt="Live spectrogram"></a><br><b>rfft</b> — live log/mel spectrogram from a jz real FFT.</td>
-<td><a href="https://dy.github.io/jz/examples/zzfx/"><img src="examples/thumbs/zzfx.webp" width="100%" alt="ZzFX sound synth"></a><br><b>zzfx</b> — the unmodified <a href="https://github.com/KilledByAPixel/ZzFX">ZzFX</a> sfx synth, compiled as-is.</td>
-<td><a href="https://dy.github.io/jz/examples/jukebox/"><img src="examples/thumbs/jukebox.webp" width="100%" alt="Floatbeat jukebox"></a><br><b>jukebox</b> — looping procedural-jazz arpeggio floatbeat; tap to play/pause.</td>
+<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>
 
-[**Browse the gallery →**](https://dy.github.io/jz/examples/)
+See [all examples →](https://dy.github.io/jz/examples/)
 
 
 
 ## Alternatives
 
-From small, fast JS subset to full JS spec, bundled engine:
+Small & fast JS subset → full JS spec & bundled engine:
 
 * [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*.
@@ -521,4 +538,10 @@ From small, fast JS subset to full JS spec, bundled engine:
 * [**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`.
 
 
+## Contributing
+
+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>

package/bench/README.md

@@ -10,7 +10,6 @@ bench/<case>/<case>.rs      optional Rust baseline
 bench/<case>/<case>.go      optional Go baseline
 bench/<case>/<case>.zig     optional Zig baseline
 bench/<case>/<case>.as.ts   optional AssemblyScript baseline
-bench/<case>/<case>.py      optional scalar CPython baseline
 bench/<case>/<case>.npy.py  optional NumPy baseline
 bench/<case>/<case>.wat     optional hand-written WAT baseline
 ```
@@ -30,8 +29,8 @@ drift as `DIFF`.
 npm run bench
 node bench/bench.mjs --targets=nat,rust,go,numpy,v8,jz
 node bench/bench.mjs --targets=jz --cases=biquad,mat4,poly,bitwise
-node bench/bench.mjs --targets=v8,deno,bun,spidermonkey,hermes,graaljs,qjs
-node bench/bench.mjs --cases=biquad,mat4,tokenizer,json,sort,crc32
+node bench/bench.mjs --targets=v8,deno,bun,spidermonkey,graaljs
+node bench/bench.mjs --cases=biquad,fft,synth,bytebeat,blur
 node bench/bench.mjs biquad
 node bench/bench.mjs mat4 --targets=nat,v8,jz
 ```
@@ -51,10 +50,21 @@ node bench/bench.mjs mat4 --targets=nat,v8,jz
 | [`json`](json/json.js) | runtime `JSON.parse` of one module-local source plus heterogeneous object/array walk with a stable inferred JSON shape |
 | [`sort`](sort/sort.js) | in-place heapsort over a typed array; exposes call-heavy nested loops and typed-array index propagation |
 | [`crc32`](crc32/crc32.js) | table-driven CRC-32 over a mutable byte buffer; exposes integer narrowing and typed-array parameter propagation |
+| [`dotprod`](dotprod/dotprod.js) | multiply-accumulate reduction; jz reassociates to 4 SIMD accumulators, beating strict-fp serial native |
+| [`bytebeat`](bytebeat/bytebeat.js) | classic integer "bytebeat" one-line-song synthesis to 8-bit PCM; pure i32, bit-exact everywhere |
+| [`fft`](fft/fft.js) | radix-2 Cooley–Tukey FFT over a transcendental-free twiddle table; the canonical numeric/audio kernel |
+| [`synth`](synth/synth.js) | minisynth audio pipeline — polynomial oscillator + ADSR + biquad per sample; loop-carried f64 |
+| [`blur`](blur/blur.js) | separable box blur on an RGBA8 image; integer stencil with edge clamp, the canonical image pipeline |
 | [`watr`](watr/watr.js) | watr's WAT-to-wasm compiler on a small WAT corpus; compares jz-compiled compiler code with raw V8 |
 | [`jessie`](jessie/jessie.js) | the subscript/jessie JS parser over a realistic source corpus; branch-, allocation- and recursion-heavy front-end work |
 | [`jz`](jz/jz.js) | the jz compiler itself (scripts/self.js pipeline) compiling three small programs at L2 — the self-host row runs jz.wasm compiling JavaScript; output bytes are checksummed so the parity gate doubles as a determinism proof |
 
+The `watr`, `jessie`, and `jz` rows are self-referential — jz (or its deps)
+compiling code. They stay runnable (`--cases=watr,jessie,jz`) and gated in
+`test/bench.js`, but are hidden from the bench page and the headline geomean SVG:
+they answer a different question (compiler throughput on itself) from the
+cross-language kernel comparison the page is about.
+
 Native rows for `json` are fixed-source references, not semantic equivalents
 of JavaScript `JSON.parse`: C/Rust/Zig hand-parse the known schema from a
 compile-time string, and Zig may constant-fold the whole parse+walk under
@@ -64,9 +74,16 @@ compile-time folded, while the compiler can still specialize the stable literal
 shape. External unknown-shape JSON still uses the generic runtime parser.
 
 Native-language rows are intentionally per case. NumPy rows are used only
-where a vectorized array implementation is a meaningful Python convention;
-scalar CPython is kept to the tokenizer row to avoid turning the suite into
-a Python loop-overhead benchmark.
+where a vectorized array implementation is a meaningful Python convention.
+
+Pure interpreters (CPython, QuickJS, Hermes, Javy's embedded-QuickJS) are not
+benchmarked: this suite measures compiled-code quality, and an interpreter row
+inflates jz's lead for free without answering a question a user actually has.
+The headline field is wasm-vs-wasm, apples-to-apples: jz against the other
+languages compiled to the same target — WebAssembly run in V8 — i.e. Rust, Go,
+and C (`wasm32-wasi`), AssemblyScript, and Porffor, plus the JS JITs it replaces
+(V8/Bun/Deno/SpiderMonkey/GraalJS). Native C/Rust/Zig/Go and NumPy's vectorized
+C are kept only as a speed-of-light reference, never presented as the wasm peer.
 
 ### Parity classes
 
@@ -84,30 +101,30 @@ correctly-rounded; cascade is the same algorithm.
 | --- | --- |
 | `nat` | clang `-O3` native C baseline, when a matching C workload exists |
 | `natgcc` | gcc `-O3`, when real gcc is installed |
-| `rust` | Rust `rustc -C opt-level=3 -C target-cpu=native`, when a matching `.rs` exists |
-| `go` | Go native compiler, when a matching `.go` exists |
-| `zig` | Zig `build-exe -O ReleaseFast`, when a matching `.zig` exists |
-| `python` | scalar CPython, when a matching `.py` exists |
+| `rust` | Rust `rustc -C opt-level=3 -C target-cpu=native` — native baseline; the headline rival is `rust-wasm` |
+| `go` | Go native compiler — native baseline; the headline rival is `go-wasm` |
+| `zig` | Zig `build-exe -O ReleaseFast` — native baseline |
 | `numpy` | vectorized NumPy, when a matching `.npy.py` exists |
 | `v8` | raw JavaScript on Node/V8 |
 | `deno` | raw JavaScript on Deno/V8 |
 | `bun` | raw JavaScript on Bun/JavaScriptCore |
 | `spidermonkey` | raw JavaScript on SpiderMonkey shell (`spidermonkey`, `sm`, `js128`, `js115`, `js102`, or `js`) |
-| `hermes` | raw JavaScript on Hermes |
 | `shermes` | Static Hermes — JS AOT-compiled to a native binary (`shermes -O`), when installed |
 | `graaljs` | raw JavaScript on GraalJS |
 | `jz` | jz output with host imports for timing/logging (measures wasm size without WASI console/perf bloat) |
 | `as` | AssemblyScript `asc -O3 --runtime stub`, when a matching `.as.ts` exists |
+| `rust-wasm` | Rust → `wasm32-wasip1` (`rustc --target wasm32-wasip1 -C opt-level=3`), run in node's V8 — the apples-to-apples Rust rival |
+| `go-wasm` | Go → `wasm32-wasip1` (`GOOS=wasip1 GOARCH=wasm go build`), run in node's V8 |
+| `c-wasm` | C → `wasm32-wasi` (`zig cc -target wasm32-wasi -O3`, no emcc/wasi-sdk needed), run in node's V8 |
 | `jz-wasmtime` | jz output on wasmtime |
 | `jz-w2c` | jz wasm translated by wabt `wasm2c`, then clang `-O3` |
 | `wat` | hand-written WAT baseline when a case provides `run-wat.mjs` |
-| `qjs` | QuickJS when installed |
 | `porf` | Porffor (`porf run`) when installed |
 | `jawsm` | jawsm when installed |
 
 The `size` column reports the artifact size each target measures: the
 compiled native binary for `nat`/`rust`/`go`/`zig`, the produced
-`.wasm` for `jz`/`as`/hand-WAT/jawsm/`jz-w2c` (the C-translated
+`.wasm` for `jz`/`as`/`rust-wasm`/`go-wasm`/`c-wasm`/hand-WAT/jawsm/`jz-w2c` (the C-translated
 executable), or the source file for raw-JS interpreters where there is no
 compile step. For source files with imports, raw-JS size is only the entry file;
 jz size is the bundled wasm artifact.
@@ -130,11 +147,10 @@ This keeps the target measuring the best current jz artifact for that workload.
 BUN_BIN=/path/to/bun \
 DENO_BIN=/path/to/deno \
 SPIDERMONKEY_BIN=/path/to/js \
-HERMES_BIN=/path/to/hermes \
 SHERMES_BIN=/path/to/shermes \
 GRAALJS_BIN=/path/to/graaljs \
 PORF_BIN=/path/to/porf \
-node bench/bench.mjs --targets=bun,deno,spidermonkey,hermes,shermes,graaljs,porf
+node bench/bench.mjs --targets=bun,deno,spidermonkey,shermes,graaljs,porf
 ```
 
 ## Reading the numbers (darwin/arm64, M-class)
@@ -148,13 +164,13 @@ available from earlier runs.
 
 | target | median | ×v8 | size | parity |
 | --- | ---: | ---: | ---: | --- |
-| **jz → V8 wasm** | **6.50 ms** | **1.90×** | **3.4 kB** | **ok** |
-| AssemblyScript (asc -O3 --runtime stub) | 9.03 ms | 1.38× | 1.9 kB | ok |
-| V8 (node) raw JS | 12.35 ms | 1.00× | 3.2 kB | ok |
-| native C (clang -O3) | 5.32 ms | 2.32× | 32.7 kB | ok |
+| **jz → V8 wasm** | **4.64 ms** | **1.94×** | **3.4 kB** | **ok** |
+| AssemblyScript (asc -O3 --runtime stub) | 6.51 ms | 1.38× | 1.9 kB | ok |
+| V8 (node) raw JS | 8.98 ms | 1.00× | 3.2 kB | ok |
+| native C (clang -O3) | 3.86 ms | 2.32× | 32.7 kB | ok |
 | hand-WAT → V8 wasm | 6.49 ms | 1.90× | 767 B | ok |
 
-jz beats V8 raw JS by 1.9× and AS by 1.4×. The typed-array scalarization,
+jz beats V8 raw JS by 2.1× and AS by 1.4×. The typed-array scalarization,
 offset-fusion, and base-hoisting pipeline delivers dense-f64 loop codegen
 that matches the hand-WAT floor.
 
@@ -162,13 +178,13 @@ that matches the hand-WAT floor.
 
 | target | median | ×v8 | size | parity |
 | --- | ---: | ---: | ---: | --- |
-| **jz → V8 wasm** | **2.74 ms** | **4.37×** | **3.3 kB** | **ok** |
-| AssemblyScript (asc -O3 --runtime stub) | 9.32 ms | 1.28× | 1.6 kB | ok |
-| V8 (node) raw JS | 11.96 ms | 1.00× | 1.2 kB | ok |
-| native C (clang -O3) | 2.76 ms | 4.33× | 32.8 kB | ok |
+| **jz → V8 wasm** | **1.49 ms** | **5.75×** | **3.1 kB** | **ok** |
+| AssemblyScript (asc -O3 --runtime stub) | 6.71 ms | 1.28× | 1.6 kB | ok |
+| V8 (node) raw JS | 8.57 ms | 1.00× | 1.2 kB | ok |
+| native C (clang -O3) | 1.97 ms | 4.35× | 32.8 kB | ok |
 | hand-WAT → V8 wasm | 8.12 ms | 1.47× | 414 B | ok |
 
-jz is 4.4× faster than V8 raw JS and 3.4× faster than AS. The scalarized
+jz is 5.9× faster than V8 raw JS and 4.6× faster than AS. The scalarized
 SIMD hot path (unrolled 4×4 multiply) is the win; V8's JIT doesn't vectorize
 this from JS source.
 
@@ -176,11 +192,11 @@ this from JS source.
 
 | target | median | ×v8 | size | parity |
 | --- | ---: | ---: | ---: | --- |
-| **jz → V8 wasm** | **0.37 ms** | **6.22×** | **1.2 kB** | **ok** |
-| AssemblyScript (asc -O3 --runtime stub) | 1.15 ms | 2.02× | 1.3 kB | ok |
-| V8 (node) raw JS | 2.32 ms | 1.00× | 1014 B | ok |
+| **jz → V8 wasm** | **0.13 ms** | **12.67×** | **1.4 kB** | **ok** |
+| AssemblyScript (asc -O3 --runtime stub) | 0.81 ms | 2.07× | 1.3 kB | ok |
+| V8 (node) raw JS | 1.67 ms | 1.00× | 1014 B | ok |
 
-jz is 6.2× faster than V8 raw JS and 3.1× faster than AS. The bimorphic
+jz is 12.9× faster than V8 raw JS and 5.9× faster than AS. The bimorphic
 `sum` (called with both `Float64Array` and `Int32Array`) stays on typed
 paths without falling back to generic dispatch.
 
@@ -188,13 +204,13 @@ paths without falling back to generic dispatch.
 
 | target | median | ×v8 | size | parity |
 | --- | ---: | ---: | ---: | --- |
-| **jz → V8 wasm** | **1.40 ms** | **3.81×** | **1.2 kB** | **ok** |
-| V8 (node) raw JS | 5.32 ms | 1.00× | 1005 B | ok |
-| AssemblyScript (asc -O3 --runtime stub) | 12.13 ms | 0.44× | 1.5 kB | ok |
-| native C (clang -O3) | 1.31 ms | 4.06× | 32.9 kB | ok |
-| hand-WAT → V8 wasm | 4.88 ms | 1.09× | 355 B | ok |
+| **jz → V8 wasm** | **1.01 ms** | **3.84×** | **1.2 kB** | **ok** |
+| V8 (node) raw JS | 3.87 ms | 1.00× | 1005 B | ok |
+| AssemblyScript (asc -O3 --runtime stub) | 9.15 ms | 0.42× | 1.5 kB | ok |
+| native C (clang -O3) | 0.95 ms | 4.08× | 32.9 kB | ok |
+| hand-WAT → V8 wasm | 3.59 ms | 1.11× | 355 B | ok |
 
-jz is 3.8× faster than V8 raw JS and 8.7× faster than AS. The i32 hot path
+jz is 4.0× faster than V8 raw JS and 8.8× faster than AS. The i32 hot path
 (`Math.imul`, `|0`, `>>>0`) now lowers to raw `i32` ops without NaN-box
 overhead on every operation.
 
@@ -202,24 +218,22 @@ overhead on every operation.
 
 | target | median | ×v8 | size | parity |
 | --- | ---: | ---: | ---: | --- |
-| AssemblyScript (asc -O3 --runtime stub) | 0.08 ms | 2.63× | 1.6 kB | ok |
-| **jz → V8 wasm** | **0.10 ms** | **2.03×** | **1.7 kB** | **ok** |
-| V8 (node) raw JS | 0.21 ms | 1.00× | 2.0 kB | ok |
+| **jz → V8 wasm** | **0.06 ms** | **2.26×** | **2.2 kB** | **ok** |
+| AssemblyScript (asc -O3 --runtime stub) | 0.06 ms | 2.15× | 1.6 kB | ok |
+| V8 (node) raw JS | 0.13 ms | 1.00× | 2.0 kB | ok |
 
-jz is 2.0× faster than V8 raw JS. AS wins here by 1.3× because its
-`String#charCodeAt` is a direct memory load without NaN-box decode, while
-jz still boxes the string pointer. The gap is narrow (0.02 ms) and both
-are well ahead of V8.
+jz is 2.4× faster than V8 raw JS and now edges out AS by ~1.2× on this
+`charCodeAt`-heavy scan. Both are well ahead of V8.
 
 ### callback — `Array.map` closure + i32 fold
 
 | target | median | ×v8 | size | parity |
 | --- | ---: | ---: | ---: | --- |
-| **jz → V8 wasm** | **0.03 ms** | **27.56×** | **1.4 kB** | **ok** |
-| AssemblyScript (asc -O3 --runtime stub) | 1.49 ms | 0.59× | 1.9 kB | ok |
-| V8 (node) raw JS | 0.88 ms | 1.00× | 828 B | ok |
+| **jz → V8 wasm** | **0.26 ms** | **2.37×** | **1.4 kB** | **ok** |
+| V8 (node) raw JS | 0.62 ms | 1.00× | 1.3 kB | ok |
+| AssemblyScript (asc -O3 --runtime stub) | 0.80 ms | 0.78× | 1.9 kB | ok |
 
-jz is 27.6× faster than V8 raw JS and 49.7× faster than AS. Closure +
+jz is 2.3× faster than V8 raw JS and 2.9× faster than AS. Closure +
 `Array.map` lowers to a preallocated typed loop with no per-iteration alloc.
 V8's JIT does not inline the closure across the `map` boundary.
 
@@ -227,11 +241,11 @@ V8's JIT does not inline the closure across the `map` boundary.
 
 | target | median | ×v8 | size | parity |
 | --- | ---: | ---: | ---: | --- |
-| **jz → V8 wasm** | **1.62 ms** | **1.12×** | **1.8 kB** | **ok** |
-| V8 (node) raw JS | 1.82 ms | 1.00× | 1.1 kB | ok |
-| AssemblyScript (asc -O3 --runtime stub) | 1.91 ms | 0.95× | 2.2 kB | ok |
+| **jz → V8 wasm** | **0.69 ms** | **1.93×** | **1.8 kB** | **ok** |
+| V8 (node) raw JS | 1.33 ms | 1.00× | 1.1 kB | ok |
+| AssemblyScript (asc -O3 --runtime stub) | 1.40 ms | 0.95× | 2.1 kB | ok |
 
-jz is 1.1× faster than V8 raw JS and 1.2× faster than AS. Schema-slot
+jz is 1.9× faster than V8 raw JS and 2.0× faster than AS. Schema-slot
 reads are direct field offsets; the gap is small because the workload is
 memory-bound.
 
@@ -239,9 +253,9 @@ memory-bound.
 
 | target | median | ×v8 | size | parity |
 | --- | ---: | ---: | ---: | --- |
-| AssemblyScript (asc -O3 --runtime stub) | 12.42 ms | 1.11× | 1.3 kB | ok |
-| **jz → V8 wasm** | **12.55 ms** | **1.10×** | **1.0 kB** | **ok** |
-| V8 (node) raw JS | 13.80 ms | 1.00× | 1.8 kB | ok |
+| AssemblyScript (asc -O3 --runtime stub) | 8.90 ms | 1.11× | 1.3 kB | ok |
+| **jz → V8 wasm** | **8.45 ms** | **1.17×** | **1.4 kB** | **ok** |
+| V8 (node) raw JS | 9.90 ms | 1.00× | 1.8 kB | ok |
 
 jz is 1.1× faster than V8 raw JS and ties AS. The dense f64 hot loop with
 conditional break compacts to 1.0 kB — the smallest wasm in the suite.
@@ -250,40 +264,65 @@ conditional break compacts to 1.0 kB — the smallest wasm in the suite.
 
 | target | median | ×v8 | size | parity |
 | --- | ---: | ---: | ---: | --- |
-| **jz → V8 wasm** | **0.23 ms** | **1.65×** | **7.7 kB** | **ok** |
-| V8 (node) raw JS | 0.38 ms | 1.00× | 1.2 kB | ok |
+| **jz → V8 wasm** | **0.21 ms** | **1.28×** | **9.9 kB** | **ok** |
+| V8 (node) raw JS | 0.27 ms | 1.00× | 1.2 kB | ok |
 
-jz is 1.7× faster than V8 raw JS. The runtime parser is specialized to the
+jz is 1.3× faster than V8 raw JS. The runtime parser is specialized to the
 inferred JSON shape; AS is skipped because it cannot parse JSON at runtime.
 
 ### sort — in-place heapsort over typed array
 
 | target | median | ×v8 | size | parity |
 | --- | ---: | ---: | ---: | --- |
-| **jz → V8 wasm** | **5.96 ms** | **1.87×** | **1.6 kB** | **ok** |
-| AssemblyScript (asc -O3 --runtime stub) | 10.22 ms | 1.09× | 1.9 kB | ok |
-| V8 (node) raw JS | 11.13 ms | 1.00× | 1.6 kB | ok |
+| **jz → V8 wasm** | **4.65 ms** | **1.67×** | **1.8 kB** | **ok** |
+| AssemblyScript (asc -O3 --runtime stub) | 7.96 ms | 0.98× | 1.9 kB | ok |
+| V8 (node) raw JS | 7.79 ms | 1.00× | 1.6 kB | ok |
 
-jz is 1.9× faster than V8 raw JS and 1.7× faster than AS. Call-heavy
+jz is 1.6× faster than V8 raw JS and 1.4× faster than AS. Call-heavy
 nested loops with typed-array index propagation stay on the i32 path.
 
 ### crc32 — table-driven CRC-32 over byte buffer
 
 | target | median | ×v8 | size | parity |
 | --- | ---: | ---: | ---: | --- |
-| **jz → V8 wasm** | **12.12 ms** | **1.11×** | **1.2 kB** | **ok** |
-| AssemblyScript (asc -O3 --runtime stub) | 12.19 ms | 1.10× | 1.4 kB | ok |
-| V8 (node) raw JS | 13.43 ms | 1.00× | 1.8 kB | ok |
+| **jz → V8 wasm** | **8.74 ms** | **1.11×** | **1.5 kB** | **ok** |
+| AssemblyScript (asc -O3 --runtime stub) | 8.76 ms | 1.11× | 1.4 kB | ok |
+| V8 (node) raw JS | 9.71 ms | 1.00× | 1.8 kB | ok |
 
-jz is 1.1× faster than V8 raw JS and ties AS. Integer narrowing and
+jz is 1.2× faster than V8 raw JS and ties AS. Integer narrowing and
 typed-array parameter propagation keep the LUT lookup on raw i32.
 
+### Audio + image showcase (cross-language, bit-exact)
+
+Four standard kernels added to make the audio story concrete. All are written so
+the output is **bit-identical** across every engine and native target — integer
+math (bytebeat, blur) or transcendental-free f64 (fft, synth: in-source Taylor
+polynomials, not `Math.sin`, which differs per libm). Go's arm64 auto-FMA gives
+the documented `fma` parity class on the f64 cases.
+
+| case | jz | vs V8 | vs AS | vs fastest native | jz wasm |
+| --- | ---: | ---: | ---: | --- | ---: |
+| **synth** — osc + ADSR + biquad | **2.32 ms** | **1.33×** | **1.07×** | **beats all** (Rust 0.89×) | 2.0 kB |
+| **fft** — radix-2 Cooley–Tukey | **1.14 ms** | **1.27×** | **1.13×** | **ties** (Rust 1.07×) | 2.3 kB |
+| **blur** — RGBA box blur | **0.90 ms** | **9.4×** | **5.8×** | trails (native SIMDs the stencil, 1.5×) | 3.4 kB |
+| **bytebeat** — integer one-liner | **0.67 ms** | **3.7×** | **5.4×** | trails (native vectorizes, 1.3×) | 1.5 kB |
+
+The headline: jz beats the JS field (V8, AssemblyScript) on **every** audio/image
+case, **ties native on FFT**, and is the **fastest of all targets on the synth
+pipeline** — its per-sample loop is loop-carried (oscillator phase + biquad
+feedback), so native can't auto-vectorize it either, and jz's tight scalar f64
+codegen with no NaN-box overhead wins outright. The two stateless integer kernels
+(bytebeat, blur) are where `clang`/`zig`/`rustc` auto-vectorize an
+embarrassingly-parallel loop jz emits as scalar — native is the floor there, but
+jz still beats the JS field by 3.7–9.4× there. (Numbers: darwin/arm64, Apple M4 Max; the live snapshot
+is [results.json](results.json).)
+
 ### watr — WAT-to-wasm compiler on small corpus
 
 | target | median | ×v8 | size | parity |
 | --- | ---: | ---: | ---: | --- |
-| V8 (node) raw JS | 1.45 ms | 1.00× | 2.6 kB | ok |
-| **jz → V8 wasm** | **1.56 ms** | **1.07×** | **144.4 kB** | **ok** |
+| V8 (node) raw JS | 1.38 ms | 1.00× | 2.6 kB | ok |
+| **jz → V8 wasm** | **1.17 ms** | **1.17×** | **238.4 kB** | **ok** |
 
 jz is 1.07× slower than V8 raw JS on this large compiler bundle. The size
 (144 kB) is the full jz-compiled watr parser + encoder + optimizer; V8's JIT
@@ -295,25 +334,36 @@ Aggregate geomean (jz / target):
 
 | target | speed | size |
 | --- | ---: | ---: |
-| V8 (node) | **0.41×** | — |
-| AssemblyScript | **0.40×** | **0.85×** |
-| Porffor | **0.32×** | **0.04×** |
-| wasm-opt slack | — | **0.91×** |
+| V8 (node) | **0.40×** | — |
+| AssemblyScript | **0.36×** | **1.16×** |
+
+jz wins or ties V8 on every kernel case; the only V8 losses are the
+self-hosting rows `watr` (1.07×) and `jessie` (1.28×). AS is beaten on
+speed across the shared cases. On size jz is ~1.1× AS (geomean 1.16×,
+median 1.10×) — jz wins on speed, AS on bytes.
 
-jz wins or ties V8 on every case except `watr` (1.07×). AS is beaten on
-all cases except `tokenizer` (AS 0.08 ms vs jz 0.10 ms). The size geomean
-is 0.85× AS — jz output is smaller on average despite beating AS on speed.
+Against the systems languages compiled to the same target — **WebAssembly, run in
+V8** — jz is **2.4× faster than C, 2.6× than Rust, and 4.9× than Go** (geomean),
+and **competitive with native C** itself (1.07×, the lone non-wasm reference).
+That apples-to-apples wasm field is the headline chart above.
 
 Case-by-case summary:
 
 * **biquad, mat4, poly, bitwise, callback: large wins.** jz beats V8 by
-  1.9–27.6× and AS by 1.4–49.7×. Typed-array scalarization, i32 narrowing,
+  2.0–12.9× and AS by 1.4–9.1×. Typed-array scalarization, i32 narrowing,
   and closure lowering are the drivers.
 * **tokenizer, aos, mandelbrot, sort, crc32: modest wins.** jz beats V8 by
-  1.1–2.0× and ties or beats AS. These are memory-bound or branch-heavy
+  1.1–2.4× and ties or beats AS. These are memory-bound or branch-heavy
   workloads where codegen quality matters less than data layout.
-* **json: solid win.** jz beats V8 by 1.7× on runtime JSON parsing; AS
+* **json: solid win.** jz beats V8 by 1.3× on runtime JSON parsing; AS
   cannot run this case.
+* **alpha: the native floor.** jz beats V8 2.0× and every wasm rival (Rust/C/Go
+  → wasm), but trails the native-C reference ~14× (374 µs vs 26 µs) — alpha's hot
+  path is an unsigned i32 multiply. jz already lifts it to 128-bit SIMD (an i16x8
+  widening byte-map); native C pulls ahead on width alone — 256-bit AVX2 with a
+  fused byte multiply-add, run as native code with no per-load bounds checks. The
+  residual is the wasm-v128-vs-AVX2 ceiling, not a missing pass. A known gap we
+  publish rather than hide.
 * **watr: near parity.** jz is 1.07× slower than V8 on a 144 kB compiler
-  bundle. This is the only case where V8's profile-guided JIT tiers beat
-  jz's AOT wasm.
+  bundle. It is one of two self-host rows (with jessie) where V8's
+  profile-guided JIT tiers beat jz's AOT wasm.