jz 0.6.0 → 0.8.0

package/index.d.ts

@@ -0,0 +1,126 @@
+// Type declarations for jz — minimal functional JS subset compiling to WASM.
+// The public surface is small: `jz` (compile + instantiate), `compile` (raw bytes),
+// `compileModule` (compile once), `instantiate` (run a module), and `jz.memory`.
+// See README for semantics and the JS↔WASM value ABI.
+
+/** Optimization level / preset. `2` is the default (all stable passes). */
+export type OptimizeLevel = boolean | 0 | 1 | 2 | 3 | 'speed' | 'size'
+
+/** Runtime-service lowering target. */
+export type Host = 'js' | 'wasi'
+
+/** Value injectable as a compile-time `define` constant. */
+export type DefineValue = number | boolean | string | null | DefineValue[] | { [k: string]: DefineValue }
+
+export interface CompileOptions {
+  /** Static ES imports to bundle: `{ './dep.js': 'export let x = 1' }`. */
+  modules?: Record<string, string>
+  /** Host imports wired at runtime: `{ math: Math, host: { log: console.log } }`. */
+  imports?: Record<string, unknown>
+  /** `N` initial pages of owned memory, or a shared `jz.memory()` / `WebAssembly.Memory`. */
+  memory?: number | WebAssembly.Memory | JzMemory
+  /** Cap memory growth at this many 64 KiB pages (default: unbounded). */
+  maxMemory?: number
+  /** Import `env.memory` instead of exporting own memory. */
+  importMemory?: boolean
+  /** Runtime-service lowering. Default `'js'`. */
+  host?: Host
+  /** Optimization level or named preset. Default `2`. */
+  optimize?: OptimizeLevel
+  /** Compile-time constants injected as top-level bindings. */
+  define?: Record<string, DefineValue>
+  /** Enforce the pure canonical subset: skip jzify lowering and reject dynamic fallbacks. */
+  strict?: boolean
+  /** Omit `_alloc`/`_clear` allocator exports for standalone scalar modules. */
+  alloc?: boolean
+  /** Disable auto-vectorization (no jz-emitted `v128`). Explicit intrinsics still compile. */
+  noSimd?: boolean
+  /** Use ordinary call frames instead of `return_call` tail calls. */
+  tailCall?: boolean
+  /** `Math.random` seeding: a number fixes the stream; `true` forces host entropy. */
+  randomSeed?: number | boolean
+  /** Emit a WASM `name` section (function symbols) for profilers/debuggers. */
+  names?: boolean
+  /** `compile()` returns WAT text instead of a WASM binary. */
+  wat?: boolean
+  /** Resolve bare specifiers via Node.js module resolution (CLI/build use). */
+  resolve?: boolean
+  /** Mutable sink that collects per-stage compile timings. */
+  profile?: { entries?: unknown[]; totals?: Record<string, number> } & Record<string, unknown>
+}
+
+/**
+ * An enhanced `WebAssembly.Memory` that marshals JS values across the WASM boundary.
+ * Allocators (`String`/`Array`/`Object`/typed-array ctors) return NaN-boxed `f64`
+ * pointers; `read` decodes one back. The heap never frees implicitly — call `reset`
+ * between independent batches (all previously returned pointers become invalid).
+ */
+export interface JzMemory extends WebAssembly.Memory {
+  /** Allocate a UTF-8 string; returns a pointer. */
+  String(str: string): number
+  /** Allocate an array (numbers, strings, nested arrays/objects); returns a pointer. */
+  Array(data: ArrayLike<unknown>): number
+  /** Allocate a fixed-layout object (keys must match a compiled schema); returns a pointer. */
+  Object(obj: Record<string, unknown>): number
+  Float64Array(data: ArrayLike<number>): number
+  Float32Array(data: ArrayLike<number>): number
+  Int32Array(data: ArrayLike<number>): number
+  Uint32Array(data: ArrayLike<number>): number
+  Int16Array(data: ArrayLike<number>): number
+  Uint16Array(data: ArrayLike<number>): number
+  Int8Array(data: ArrayLike<number>): number
+  Uint8Array(data: ArrayLike<number>): number
+  /** Decode one pointer (or a multi-value tuple of pointers) back to a JS value. */
+  read(ptr: number | number[]): unknown
+  /** Reserve `bytes` of raw heap; returns the offset. */
+  alloc(bytes: number): number
+  /** Rewind the bump pointer — drops every allocation since the last reset. */
+  reset(): void
+}
+
+/** A compiled-and-instantiated jz module. */
+export interface JzInstance {
+  /** JS-wrapped exports: marshals arguments in, decodes pointer returns, throws real `Error`s. */
+  exports: Record<string, (...args: any[]) => any> & Record<string, any>
+  /** The value codec, or `null` for a pure-scalar module with no heap. */
+  memory: JzMemory | null
+  /** The raw `WebAssembly.Instance` (numbers pass through; pointers come back NaN-boxed). */
+  instance: WebAssembly.Instance
+  /** The underlying `WebAssembly.Module`. */
+  module: WebAssembly.Module
+}
+
+/** Create a shared memory that modules compile into (schemas accumulate across modules). */
+export interface MemoryFactory {
+  (src?: WebAssembly.Memory): JzMemory
+}
+
+/** The default export: compile + instantiate, as a call or a tagged template. */
+export interface Jz {
+  /** Compile and instantiate a source string. */
+  (code: string, opts?: CompileOptions): JzInstance
+  /** Tagged-template form: interpolations are baked into the source at compile time. */
+  (strings: TemplateStringsArray, ...values: unknown[]): JzInstance
+  /** Compile only — raw WASM binary (or WAT text with `{ wat: true }`). */
+  compile: typeof compile
+  /** Shared-memory factory: `jz.memory()` or `jz.memory(existing)`. */
+  memory: MemoryFactory
+}
+
+declare const jz: Jz
+export default jz
+export { jz }
+
+/** Compile to a raw WASM binary. */
+export function compile(code: string, opts?: CompileOptions & { wat?: false }): Uint8Array
+/** Compile to WAT text. */
+export function compile(code: string, opts: CompileOptions & { wat: true }): string
+
+/** Compile once to a `WebAssembly.Module` (pays AOT + validate cost once); instantiate many. */
+export function compileModule(code: string, opts?: CompileOptions): WebAssembly.Module
+
+/** Instantiate a compiled module or raw WASM bytes, wiring the allocator and value codec. */
+export function instantiate(
+  module: WebAssembly.Module | Uint8Array | ArrayBuffer,
+  opts?: CompileOptions,
+): JzInstance

package/index.js

@@ -43,18 +43,21 @@
 import { parse } from './src/parse.js'
 import watrCompile from "watr/compile";
 import watrPrint from "watr/print";
-import watOptimize from "./src/wat/optimize.js";
+import watOptimize from "watr/optimize";
+import { appendLateStdlib } from './src/wat/assemble.js'
 import { ctx, reset, err, initWarnings, assertCtxInvariants } from './src/ctx.js'
 import prepare, { GLOBALS } from './src/prepare/index.js'
+import { liftIIFEs } from './src/prepare/lift-iife.js'
 import compile from './src/compile/index.js'
 import { resetProgramFactsCache } from './src/compile/program-facts.js'
 import { emit, emitter, emitVoid as flat, emitBlockBody as body, emitBoolStr as bool, emitIndex as idx, buildArrayWithSpreads as spread } from './src/compile/emit.js'
-import { optimizeFunc, collectVolatileGlobals, collectReachableGlobalWrites, hoistGlobalPtrOffset, stablePtrGlobalNames, resolveOptimize } from './src/optimize/index.js'
+import { optimizeFunc, foldStrDispatchF64, collectVolatileGlobals, collectReachableGlobalWrites, hoistGlobalPtrOffset, stablePtrGlobalNames, resolveOptimize, SIMD_PINNED } from './src/optimize/index.js'
+import { findBodyStart } from './src/ir.js'
 import { VAL } from './src/reps.js'
 import jzify from './jzify/index.js'
 import { T } from './src/ast.js'
 import {
-  memory as enhanceMemory, instantiate as instantiateRuntime,
+  memory as enhanceMemory, instantiate as instantiateRuntime, toModule,
 } from './interop.js'
 
 // A host import that's a JS function may hand back any value, including a host
@@ -68,11 +71,47 @@ const importsMayReturnExternal = (imports) =>
 // directly — keeps the self-host kernel free of host-only built-ins.
 const resolveUrl = (spec, base) => new URL(spec, base).href
 
+// Serialize a JS value to a jz source literal (numbers/booleans/strings/null/
+// undefined + literal arrays/objects). Returns null for anything not expressible
+// as a compile-time literal (functions, host objects, circular). Shared by the
+// `jz\`…${val}\`` template tag (hoists complex args) and opts.define.
+const serialize = (v) => {
+  if (v === undefined) return 'undefined'
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v)
+  if (v === null) return 'null'
+  if (typeof v === 'string') return JSON.stringify(v)
+  if (Array.isArray(v)) {
+    const elems = v.map(serialize)
+    return elems.every(e => e !== null) ? `[${elems.join(', ')}]` : null
+  }
+  if (typeof v === 'object') {
+    const props = Object.keys(v).map(k => {
+      const s = serialize(v[k])
+      return s !== null ? `${k}: ${s}` : null
+    })
+    return props.every(p => p !== null) ? `{${props.join(', ')}}` : null
+  }
+  return null
+}
+
+// opts.define → a one-line `let K = V; …` prelude prepended to source. Kept on a
+// single line (no trailing newline) so user line numbers past line 1 stay exact —
+// same convention the template tag uses for hoisted literals.
+const defineBindings = (define) => {
+  const parts = []
+  for (const [k, v] of Object.entries(define)) {
+    const s = serialize(v)
+    if (s === null) err(`opts.define['${k}'] is not a compile-time constant — use a number, boolean, string, null, or a literal array/object`)
+    parts.push(`let ${k} = ${s}`)
+  }
+  return parts.length ? parts.join('; ') + '; ' : ''
+}
+
 const nowMs = () => globalThis.performance?.now ? globalThis.performance.now() : Date.now()
 
 const compileProfiler = (profile) => {
   if (profile == null) return null
-  if (typeof profile !== 'object') throw new TypeError('opts.profile must be an object sink; use { profile: { names: true } } to emit a wasm name section')
+  if (typeof profile !== 'object') throw new TypeError('opts.profile must be an object sink (populated with compile-phase entries/totals); for a wasm name section use opts.names')
   profile.entries ||= []
   profile.totals ||= {}
   return {
@@ -168,12 +207,20 @@ jz.memory = enhanceMemory
  *   (so full-JS syntax like var/function/class is rejected, not lowered) and reject
  *   dynamic features (obj[k], for-in, unknown receiver method calls) at compile time.
  *   Avoids pulling dynamic-dispatch stdlib into output; large size win for static programs.
- * @param {WebAssembly.Memory|number} [opts.memory] - Shared memory import, or
- *   initial page count. Prefer `memory: N` for owned memory.
+ * @param {WebAssembly.Memory|number} [opts.memory] - Owned memory's initial page
+ *   count (`memory: N`, 64 KiB/page), or a `WebAssembly.Memory` to share across modules.
+ * @param {number} [opts.maxMemory] - Maximum memory pages — emits a ceiling on the
+ *   memory type so growth traps past it (sandbox cap). Must be ≥ the initial size.
+ *   Default: unbounded.
+ * @param {boolean} [opts.importMemory] - Import `env.memory` instead of exporting an
+ *   owned memory. For embedding into a host that provides the memory.
  * @param {boolean} [opts.alloc=true] - Export raw allocator helpers
  *   (`_alloc`, `_clear`) for JS memory wrapping. Set false for standalone host-run
  *   modules that only call exported wasm functions.
- * @param {boolean|number|object} [opts.optimize] - Optimization level/config.
+ * @param {Object<string,*>} [opts.define] - Compile-time constants injected as
+ *   top-level bindings before parse, e.g. `{ DEBUG: false, PORT: 8080 }`. Values may
+ *   be numbers, booleans, strings, null, or literal arrays/objects.
+ * @param {boolean|number|string|object} [opts.optimize] - Optimization level/config.
  *   - `false` / `0`: nothing. Fastest compile, largest output (live coding).
  *   - `1`: encoding-compactness only (treeshake + sortLocalsByUse + fusedRewrite-inline).
  *   - `true` / `2` (default): every stable jz pass + full watr (inlineOnce +
@@ -181,16 +228,32 @@ jz.memory = enhanceMemory
  *   - `3` / `'speed'`: level 2 + larger array/hash initial caps (`arrayMinCap`,
  *     `hashSmallInitCap`) + `hoistConstantPool` off (inline `f64.const` over
  *     mutable globals); trades size for speed.
- *   - `{ level?: 0|1|2|3, watr?: bool, hoistAddrBase?: bool, ... }`: per-pass
- *     overrides on top of the chosen level. See PASS_NAMES in src/optimize.js.
+ *   - `'size'`: full passes with unrolling/SIMD off and tight scalar caps — smallest wasm.
+ *   - `{ level?, <pass>?: bool, ... }`: per-pass overrides on top of a base level.
+ *     INTERNAL/unstable — pass names track compiler internals (PASS_NAMES in
+ *     src/optimize/index.js) and change between versions; prefer the level/string forms.
+ * @param {boolean} [opts.noSimd] - Disable auto-vectorization (no jz-emitted v128) for
+ *   engines without the SIMD proposal. Explicit f32x4/i32x4 intrinsics still compile.
+ * @param {boolean} [opts.whyNotSimd] - Diagnostic: emit a `simd-why-not` warning (via
+ *   opts.warnings) for each canonical loop the auto-vectorizer declined, naming the
+ *   first blocking op. Finds loops one op away from SIMD. Noisy — off by default.
+ * @param {boolean} [opts.experimentalStencil] - Opt-in: vectorize neighbour-load
+ *   stencils (`b[i]=f(a[i-1],a[i],a[i+1])`, 2-D 5-point) to f64x2. Bit-exact vs scalar.
+ *   Unstable — off by default until proven across the corpus.
+ * @param {boolean} [opts.experimentalOuterStrip] - Opt-in: strip-mine a pixel loop whose
+ *   per-pixel value is an inner reduction (metaballs-shape) into f64x2 lanes (2 pixels at
+ *   once). Bit-exact vs scalar. Unstable — off by default.
+ * @param {boolean} [opts.experimentalToneMap] - Mixed-lane log-tonemap vectorizer: a flat
+ *   `i32 dens[i] → f64 Math.log → i32 pack → px[i]` loop lifts to a 2-wide f64x2 island
+ *   (fern/bifurcation/attractors). Bit-exact vs scalar; default-on at speed, pass `false` to disable.
  * @param {object} [opts.warnings] - Optional mutable warning sink populated with
  *   `entries: [{ code, message, fn?, line?, column? }]`. Heap-growth advisories
  *   fire when a module uses the bump allocator and an export or loop retains
  *   allocations without a host-side memory.reset().
  * @param {object} [opts.profile] - Optional mutable profile sink populated with
  *   `entries` and `totals` for parse / jzify / prepare / compile / plan / watr phases.
- *   Set `profile.names = true` to also emit a standard wasm `name` custom section
- *   for profiler/debugger symbolication.
+ * @param {boolean} [opts.names] - Emit a standard wasm `name` custom section (function
+ *   symbols) for profiler/debugger symbolication. (Legacy: `profile.names = true`.)
  * @param {Object<string,string>} [opts.modules] - Map of module specifier → source
  *   for compile-time `import`/`export` bundling: jz resolves the module graph
  *   in-process from this map instead of reading from disk.
@@ -305,10 +368,16 @@ const detectOptimizeConfig = (ast, code) => {
 
   const cfg = {}
   // Machine-generated or large code: watr's WAT-level CSE/DCE/inline fights
-  // jz's already-optimized IR and inflates output. Disable it automatically.
+  // jz's already-optimized IR and inflates output. Disable it automatically —
+  // EXCEPT when the module uses SIMD intrinsics. A v128 helper call (e.g.
+  // f64x2.sin → $math.sin2) leaves v128 params/results across the call boundary;
+  // watr's inliner folds the helper into the loop and coalesces those vectors,
+  // and without it the v128 spills to memory every iteration (~2× slower on the
+  // trig-bound attractors kernel). Explicit SIMD is a perf opt-in — keep watr on.
+  const usesSimd = !!ctx.module?.modules?.simd
   const isLarge = s.sourceChars > 4000 || s.funcCount > 40 || s.maxFuncBodySize > 300
   const isMachineLike = s.callSites > 300 && s.stringLiteralCount < 10
-  if (isLarge || isMachineLike) { cfg.watr = false; cfg.splitCharScan = false }
+  if ((isLarge || isMachineLike) && !usesSimd) { cfg.watr = false; cfg.splitCharScan = false }
   // Typed-array heavy: tighten scalarization thresholds when we see large
   // fixed-size arrays; keep defaults for small/dynamic ones.
   if (s.typedArrayCount > 0 && s.maxTypedArrayLen > 0) {
@@ -362,6 +431,15 @@ const setupCtx = (code, opts) => {
   initWarnings(opts.warnings)
   if (typeof opts.memory === 'number') ctx.memory.pages = opts.memory
   else if (opts.memory) ctx.memory.shared = true
+  if (opts.importMemory) ctx.memory.shared = true   // import env.memory instead of exporting own
+  if (opts.maxMemory != null) {
+    if (!Number.isInteger(opts.maxMemory) || opts.maxMemory < 1)
+      err(`opts.maxMemory must be a positive integer page count (each page is 64 KiB); got ${opts.maxMemory}`)
+    const initialPages = ctx.memory.pages || 1
+    if (opts.maxMemory < initialPages)
+      err(`opts.maxMemory (${opts.maxMemory}) is below the initial memory size (${initialPages} pages)`)
+    ctx.memory.max = opts.maxMemory
+  }
   if (opts.modules) ctx.module.importSources = opts.modules
   if (opts.imports) {
     ctx.module.hostImports = opts.imports
@@ -384,6 +462,8 @@ const setupCtx = (code, opts) => {
   }
   if (opts.alloc === false) ctx.transform.alloc = false
   if (opts.inspect) ctx.transform.inspect = true
+  if (opts.helperCounters) ctx.transform.helperCounters = true
+  if (opts.helperCallsites) ctx.transform.helperCallsites = opts.helperCallsites
   if (opts.importMetaUrl) ctx.transform.importMetaUrl = String(opts.importMetaUrl)
   if (opts.randomSeed !== undefined) {
     if (opts.randomSeed !== true && !Number.isFinite(opts.randomSeed))
@@ -421,6 +501,7 @@ const rejectReservedPrefix = (node) => {
 }
 
 const jzCompileInner = (code, opts = {}) => {
+  if (opts.define) code = defineBindings(opts.define) + code
   const profiler = compileProfiler(opts.profile)
   const time = (name, fn) => profiler ? profiler.time(name, fn) : fn()
 
@@ -429,6 +510,12 @@ const jzCompileInner = (code, opts = {}) => {
 
   let parsed = time('parse', () => parse(code))
   if (typeof code === 'string' && code.includes(T)) rejectReservedPrefix(parsed)
+  // Lambda-lift immediately-invoked arrow literals to typed direct calls — lets SIMD
+  // flow through the f64-only closure ABI and drops the closure for every IIFE. Runs
+  // BEFORE jzify so it only sees USER arrow IIFEs, not jzify's synthetic wrapper IIFEs
+  // (named/recursive function expressions, method shorthand), which keep the closure
+  // path. A no-op when there are none.
+  parsed = time('liftIIFE', () => liftIIFEs(parsed))
   if (!opts.strict) parsed = time('jzify', () => jzify(parsed))
   const ast = time('prepare', () => prepare(parsed))
   assertCtxInvariants('post-prepare')
@@ -449,6 +536,39 @@ const jzCompileInner = (code, opts = {}) => {
     }
   }
 
+  // opts.noSimd: force auto-vectorization off regardless of opt level — a
+  // portability escape hatch for engines without the SIMD proposal (parallels
+  // opts.noTailCall). Must suppress EVERY jz-emitted v128, which is two passes:
+  // vectorizeLaneLocal (lane maps, reductions incl. reduceUnroll, byte scans) AND
+  // the SLP store-pair packer (within-iteration f64x2). Both off, so `noSimd` is a
+  // true scalar baseline — the oracle SIMD-vs-scalar correctness tests compare
+  // against (missing one let an SLP miscompile pass as "SIMD == scalar"). Explicit
+  // f32x4/i32x4 intrinsics in source are the user's own opt-in and stay. Applied
+  // after auto-config so it wins over any re-resolved preset.
+  if (opts.noSimd) {
+    ctx.transform.optimize.vectorizeLaneLocal = false
+    ctx.transform.optimize.experimentalSlp = false
+  }
+
+  // opts.whyNotSimd (CLI --why-not-simd): emit a `simd-why-not` warning per
+  // canonical loop that the auto-vectorizer declined, naming the blocking op —
+  // a diagnostic to find loops that are "one op away" from SIMD. Rides the
+  // resolved optimize cfg to the vectorizer; off by default (the report is noisy).
+  if (opts.whyNotSimd && ctx.transform.optimize) ctx.transform.optimize.whyNotSimd = true
+
+  // opts.experimentalStencil: the neighbour-load stencil vectorizer (a[i±1] / 2-D 5-point).
+  // Now default-on at optimize:'speed' (proven bit-exact corpus-wide); the opt is two-way so an
+  // explicit `false` can still disable it (e.g. to A/B against the scalar path).
+  if (opts.experimentalStencil !== undefined && ctx.transform.optimize) ctx.transform.optimize.experimentalStencil = !!opts.experimentalStencil
+
+  // opts.experimentalOuterStrip: the outer-loop strip-mine vectorizer (2 adjacent pixels in f64x2
+  // lanes over an inner reduction). Default-on at speed; two-way like experimentalStencil.
+  if (opts.experimentalOuterStrip !== undefined && ctx.transform.optimize) ctx.transform.optimize.experimentalOuterStrip = !!opts.experimentalOuterStrip
+
+  // opts.experimentalToneMap: the mixed-lane log-tonemap vectorizer (i32 dens[i] → f64 log →
+  // i32 pack → px[i], 2-wide f64x2 island). Default-on at speed; two-way like the others.
+  if (opts.experimentalToneMap !== undefined && ctx.transform.optimize) ctx.transform.optimize.experimentalToneMap = !!opts.experimentalToneMap
+
   const module = time('compile', () => compile(ast, profiler))
   assertCtxInvariants('post-compile')
 
@@ -470,6 +590,10 @@ const jzCompileInner = (code, opts = {}) => {
   const cfg = ctx.transform.optimize
   let watrOpts = typeof cfg.watr === 'object' ? { ...cfg.watr } : true
   if (cfg.vectorizeLaneLocal) {
+    // Off at the speed tier: watr's loopify collapses the while-idiom to
+    // `loop { if C { …; br } }` (an UNfused back-jump — no win) AND would mangle the
+    // lane-vectorizer's loop shape. jz's own `rotateLoops` (optimize/index.js, post
+    // phase) does the rotation instead, emitting the FUSED `br_if $loop C` back-edge.
     if (watrOpts === true) watrOpts = { loopify: false }
     else if (typeof watrOpts === 'object' && watrOpts.loopify === undefined) watrOpts.loopify = false
   }
@@ -477,7 +601,34 @@ const jzCompileInner = (code, opts = {}) => {
     if (watrOpts === true) watrOpts = { devirt: true }
     else if (typeof watrOpts === 'object' && watrOpts.devirt === undefined) watrOpts.devirt = true
   }
+  // Multi-caller small-function inlining (size-for-speed): on at the 'speed'/level-3
+  // tier only, like devirt above. Removes call overhead from hot inner loops at the
+  // cost of duplicating tiny bodies; level 2 (and the size budgets measured there)
+  // stay untouched.
+  if (cfg.inlineFns) {
+    if (watrOpts === true) watrOpts = { inline: 'simd' }
+    else if (typeof watrOpts === 'object' && watrOpts.inline === undefined) watrOpts.inline = 'simd'
+  }
+  // guardRefine folds jz's NaN-box tag reads — default-off in watr (general WAT
+  // never matches it), so jz always enables it explicitly.
+  if (watrOpts === true) watrOpts = { guardRefine: true }
+  else if (typeof watrOpts === 'object' && watrOpts.guardRefine === undefined) watrOpts.guardRefine = true
+  // Pin jz's scalar transcendentals (the PPC_CALL2 keys the auto-vectorizer rewrites to f64x2
+  // mirrors) so watr's inline passes don't dissolve the call nodes the lift needs. The protection
+  // policy lives here in jz — watr just honours the `pin` list (no jz names hardcoded in watr).
+  if (cfg.watr) {
+    if (watrOpts === true) watrOpts = {}
+    watrOpts.pin = watrOpts.pin ? [...watrOpts.pin, ...SIMD_PINNED] : SIMD_PINNED
+  }
+  // Capture the per-func alias facts (param-distinctness) the emit phase stamped as JS
+  // expandos — watOptimize round-trips the module through watr's printer/parser, which
+  // rebuilds plain arrays and DROPS every non-index property. Without re-attaching, the
+  // 'post' leaf passes (splitLoopPrivateScratch, hoistInvariantLoop) lose the proven
+  // alias model and fall back to weaker/heuristic invariance — the exact reason raytrace's
+  // read-only sphere loads couldn't be SOUNDLY proven loop-invariant after watr ran.
+  const aliasFacts = cfg.watr ? new Map(module.filter(n => Array.isArray(n) && n[0] === 'func' && n.distinctParams).map(n => [n[1], n.distinctParams])) : null
   const optimized = cfg.watr ? time('watOptimize', () => watOptimize(module, watrOpts)) : module
+  if (aliasFacts?.size) for (const n of optimized) if (Array.isArray(n) && n[0] === 'func' && aliasFacts.has(n[1])) n.distinctParams = aliasFacts.get(n[1])
   // Stable-pointee module globals: resolve the __ptr_offset once per function.
   // Never-forwarding kinds — every PTR tag outside __ptr_offset's forwarding
   // set {ARRAY, HASH, SET, MAP} — give the same offset for the same bits, so
@@ -502,12 +653,45 @@ const jzCompileInner = (code, opts = {}) => {
   if (cfg.watr) {
     // Build global name→type map from ctx.scope.globalTypes for promoteGlobals
     const globalTypesMap = ctx.scope.globalTypes ? new Map([...ctx.scope.globalTypes].map(([k, v]) => [`$${k}`, v])) : null
+    // Build pure-function map for Phase 2 user-function inline in tryPerPixelColor.
+    // A function is "pure for SIMD inline" if its body contains no side effects:
+    // no global.set, no memory stores, no calls outside $math.*.
+    // foldStrDispatchF64 is run first (idempotent) so the purity check sees the
+    // folded body — dead __is_str_key dispatch would otherwise look impure.
+    if (cfg.vectorizeLaneLocal === true) {
+      const allFuncs = optimized.filter(node => Array.isArray(node) && node[0] === 'func')
+      const pureFuncMap = new Map()
+      const hasSideEffect = (node) => {
+        if (!Array.isArray(node)) return false
+        const op = node[0]
+        if (op === 'global.set') return true
+        if (typeof op === 'string' && (op.endsWith('.store') || op.startsWith('memory.'))) return true
+        if (op === 'call' && typeof node[1] === 'string' && !node[1].startsWith('$math.')) return true
+        if (op === 'call_indirect' || op === 'call_ref') return true
+        return node.some((c, i) => i > 0 && hasSideEffect(c))
+      }
+      for (const fn of allFuncs) {
+        const name = fn[1]
+        if (typeof name !== 'string' || name.startsWith('$math.') || name.startsWith('$__')) continue
+        // Fold dead str-dispatch blocks so purity check sees the clean form.
+        foldStrDispatchF64(fn)
+        const bodyStart = findBodyStart(fn)
+        if (bodyStart < 0) continue
+        let pure = true
+        for (let i = bodyStart; i < fn.length; i++) if (hasSideEffect(fn[i])) { pure = false; break }
+        if (pure) pureFuncMap.set(name, fn)
+      }
+      if (pureFuncMap.size) cfg._pureFuncMap = pureFuncMap
+    }
     time('watrReopt', () => {
       const funcs = optimized.filter(node => Array.isArray(node) && node[0] === 'func')
       const volatileGlobals = collectVolatileGlobals(funcs)
       const reach = collectReachableGlobalWrites(funcs)
       for (const node of funcs) optimizeFunc(node, cfg, globalTypesMap, volatileGlobals, 'post', reach)
     })
+    // The 'post' lane vectorizer can inject stdlib calls (e.g. the f64x2 trig mirror $math.cos2)
+    // absent from the already-pulled+treeshaken module — append any now-referenced helper body.
+    appendLateStdlib(optimized)
   }
   try {
     if (opts.wat) {
@@ -516,7 +700,9 @@ const jzCompileInner = (code, opts = {}) => {
     }
     const wasm = time('watrCompile', () => watrCompile(optimized))
     let bytes = wasm
-    if (opts.profile?.names) bytes = appendFunctionNames(bytes, optimized)
+    // opts.names emits a wasm `name` custom section (symbols for profilers/
+    // debuggers). opts.profile.names is the older spelling — still honored.
+    if (opts.names || opts.profile?.names) bytes = appendFunctionNames(bytes, optimized)
     return opts.inspect ? { wasm: bytes, inspect: ctx.inspect } : bytes
   } catch (e) {
     // watr surfaces dangling identifiers as "Unknown local|func|global|table|memory $X".
@@ -546,27 +732,6 @@ export default function jz(code, ...args) {
   if (Array.isArray(code)) {
     const interp = {}, data = {}, hoisted = []
 
-    // Serialize JS value to jz source literal. Returns null if not serializable.
-    const serialize = (v) => {
-      if (v === undefined) return 'undefined'  // else falls through → treated as a
-      // host object → memory.Object(undefined) → Object.keys(undefined) crash
-      if (typeof v === 'number' || typeof v === 'boolean') return String(v)
-      if (v === null) return 'null'
-      if (typeof v === 'string') return JSON.stringify(v)
-      if (Array.isArray(v)) {
-        const elems = v.map(serialize)
-        return elems.every(e => e !== null) ? `[${elems.join(', ')}]` : null
-      }
-      if (typeof v === 'object') {
-        const props = Object.keys(v).map(k => {
-          const s = serialize(v[k])
-          return s !== null ? `${k}: ${s}` : null
-        })
-        return props.every(p => p !== null) ? `{${props.join(', ')}}` : null
-      }
-      return null
-    }
-
     let src = code[0]
     for (let i = 0; i < args.length; i++) {
       const v = args[i]
@@ -618,3 +783,25 @@ export default function jz(code, ...args) {
 export { jz }
 const jzCompile = jz.compile
 export { jzCompile as compile }
+
+/**
+ * Compile source to a cached `WebAssembly.Module` (compile + validate once).
+ * Pair with `instantiate(module, opts)` to spin up many instances without
+ * re-validating the bytes each time — the AOT compile is paid once, so repeated
+ * instantiation is cheap. Returns a `WebAssembly.Module`, built with the native
+ * `wasm:js-string` builtins fast path where the engine supports it.
+ *
+ *   import { compileModule, instantiate } from 'jz'
+ *   const mod = compileModule('export let f = x => x * 2')
+ *   const { exports } = instantiate(mod)   // repeat cheaply, no recompile
+ *
+ * @param {string} code
+ * @param {object} [opts] - same options as `compile()`
+ * @returns {WebAssembly.Module}
+ */
+export const compileModule = (code, opts = {}) => {
+  const out = jzCompile(code, opts)
+  return toModule(out && typeof out === 'object' && 'wasm' in out ? out.wasm : out)
+}
+
+export { instantiateRuntime as instantiate }