jz 0.6.0 → 0.7.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

@@ -44,17 +44,20 @@ import { parse } from './src/parse.js'
 import watrCompile from "watr/compile";
 import watrPrint from "watr/print";
 import watOptimize from "./src/wat/optimize.js";
+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 } 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
@@ -421,6 +499,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 +508,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 +534,33 @@ 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). Disabling the vectorizeLaneLocal pass suppresses every
+  // jz-emitted v128 (lane maps, reductions incl. reduceUnroll, byte scans);
+  // 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
+
+  // 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')
 
@@ -477,6 +589,14 @@ 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: true }
+    else if (typeof watrOpts === 'object' && watrOpts.inline === undefined) watrOpts.inline = true
+  }
   const optimized = cfg.watr ? time('watOptimize', () => watOptimize(module, watrOpts)) : module
   // Stable-pointee module globals: resolve the __ptr_offset once per function.
   // Never-forwarding kinds — every PTR tag outside __ptr_offset's forwarding
@@ -502,12 +622,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 +669,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 +701,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 +752,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 }

package/interop.js

@@ -132,10 +132,24 @@ _u32[1] = ATOM_HI[ATOM.TRUE]; _u32[0] = 0; export const TRUE_NAN = _f64[0]
 // Coerce JS null/undefined → NaN-boxed sentinels for WASM boundary
 export const coerce = v => v === null ? NULL_NAN : v === undefined ? UNDEF_NAN : v
 
-// Decode f64 return value: null/undefined sentinels → JS values, numbers pass through
+// Memory-free decode of an f64 boundary value: numbers pass through, the reserved
+// atoms become null/undefined/false/true, and an SSO string unpacks its ≤4 inline
+// ASCII bytes straight from the NaN payload. These are exactly the value forms a
+// *memoryless* module can carry across the boundary — a heap string/array/object
+// would need linear memory to exist, so it can't reach here. Heap-carrying modules
+// route through `mem.read` instead (which also handles these, via memory).
 const decode = v => {
-  if (v === v) return v  // fast path: non-NaN
+  if (v === v) return v  // fast path: non-NaN number
   _f64[0] = v
+  // STRING (type 4) + SSO bit: content is the low 32 bits, length the low aux bits.
+  if (decodePtrType(_u32[1]) === 4) {
+    const a = decodePtrAux(_u32[1])
+    if (a & LAYOUT.SSO_BIT) {
+      const len = a & 0x7, off = _u32[0]; let s = ''
+      for (let i = 0; i < len; i++) s += String.fromCharCode((off >>> (i * 8)) & 0xFF)
+      return s
+    }
+  }
   if (_u32[0] !== 0) return v
   if (_u32[1] === ATOM_HI[ATOM.NULL]) return null
   if (_u32[1] === ATOM_HI[ATOM.UNDEF]) return undefined
@@ -144,6 +158,14 @@ const decode = v => {
   return v
 }
 
+// Decode a boundary value that arrives as i64 bits (BigInt carrier) into a JS
+// value. Heap-carrying modules go through `mem.read`; a memoryless module's value
+// is a number/atom/SSO string, decodable from the bits alone.
+const readArgBits = (state, big) => {
+  const f = i64ToF64(big)
+  return state.mem ? state.mem.read(f) : decode(f)
+}
+
 export const ptr = (type, aux, offset) => {
   _u32[1] = encodePtrHi(type, aux)
   _u32[0] = offset >>> 0; return _f64[0]
@@ -196,7 +218,11 @@ export const memory = (src) => {
     // Instance result: { module, instance, exports, extMap }
     const raw = src?.instance?.exports || src?.exports || src
     mem = src?.exports?.memory || raw.memory
-    if (!mem) return null  // pure scalar module — no memory
+    // Memoryless module (SSO strings / atoms / numbers only — no linear memory):
+    // hand back a minimal reader instead of null so callers can still decode its
+    // boundary values from bits. `read`/`wrapVal` cover the value forms that exist
+    // without memory; `scalar` flags the fast path that skips heap marshaling.
+    if (!mem) return { read: decode, wrapVal: coerce, scalar: true }
     wasmExports = { ...raw, memory: mem }
     extMap = src.extMap || null
     mod = src.module || null
@@ -249,8 +275,7 @@ export const memory = (src) => {
   if (_enhanced.has(mem)) {
     mem.schemas = schemas
     if (wasmExports?._alloc) { alloc = wasmExports._alloc; mem.alloc = alloc }
-    if (wasmExports?._clear) mem.reset = wasmExports._clear
-    else if (!mem.reset) mem.reset = jsReset
+    mem.reset = jsReset   // post-init rewind — see the note at the first-enhance path
     if (extMap) mem._extMap = extMap
     return mem
   }
@@ -471,7 +496,14 @@ export const memory = (src) => {
   }
 
   mem.alloc = alloc
-  mem.reset = wasmExports?._clear || jsReset
+  // Rewind to the JS-captured post-init heap mark, NOT the wasm `_clear` (which
+  // rewinds to the static-data end and would clobber module-global heap values —
+  // a top-level `let o = {…}` — on the first alloc after reset). `jsReset`'s base
+  // is `$__heap` read after instantiation (start ran), i.e. exactly the high-water
+  // mark above all module-init allocations. Both share `$__heap`, so a wasm `_alloc`
+  // and this reset stay consistent. (Shared memory has no `$__heap` global → base
+  // is the fixed start, preserving prior behavior.)
+  mem.reset = jsReset
 
   // TypedArray constructors: memory.Float64Array(data), etc.
   // Bulk-copy path: when input is a TypedArray whose element type matches
@@ -536,7 +568,9 @@ export const wrap = (memSrc, inst) => {
     const bits = lastErrBits.value
     _u32[0] = Number(bits & 0xffffffffn)
     _u32[1] = Number((bits >> 32n) & 0xffffffffn)
-    const value = mem ? mem.read(_f64[0]) : _f64[0]
+    // Memoryless module: the thrown value is a number/atom/SSO string — decode it
+    // from bits. (A heap Error/string can only exist when the module has memory.)
+    const value = mem ? mem.read(_f64[0]) : decode(_f64[0])
     if (value instanceof Error) throw value
     const wrapped = new Error(typeof value === 'string' ? value : String(value))
     wrapped.cause = error
@@ -554,7 +588,7 @@ export const wrap = (memSrc, inst) => {
     ext?.has(i) ? (x === undefined && ext.def?.has(i) ? ext.def.get(i) : x) : box(x)
 
   // Pure scalar module (no memory): pass f64 values directly, no marshaling
-  if (!mem) {
+  if (!mem || mem.scalar) {
     for (const [name, fn] of Object.entries(realInst.exports)) {
       if (typeof fn !== 'function') { exports[name] = fn; continue }
       const ext = extExp.get(name)
@@ -649,7 +683,7 @@ const installDefaultEnvImports = (mod, imports, state) => {
     // across the wasm→JS boundary (see module/console.js header). Reinterpret
     // the BigInt's bits as f64 here so mem.read sees the original NaN-box.
     const write = (valBig, fd, sep) => {
-      const v = state.mem.read(i64ToF64(valBig))
+      const v = readArgBits(state, valBig)
       buf[fd] += String(v)
       if (sep === 32) buf[fd] += ' '
       else if (sep === 10) flush(fd)
@@ -679,13 +713,13 @@ const installDefaultEnvImports = (mod, imports, state) => {
   }
   if (envFns.has('parseFloat') && !imports.env.parseFloat) {
     imports.env.parseFloat = (valBig) => {
-      const s = state.mem.read(i64ToF64(valBig))
+      const s = readArgBits(state, valBig)
       return parseFloat(s)
     }
   }
   if (envFns.has('parseInt') && !imports.env.parseInt) {
     imports.env.parseInt = (valBig, radix) => {
-      const s = state.mem.read(i64ToF64(valBig))
+      const s = readArgBits(state, valBig)
       return parseInt(s, radix || undefined)
     }
   }
@@ -834,7 +868,11 @@ const finishInstantiation = (mod, inst, imports, needsWasi, opts, state) => {
   const enhanced = memory(memSrc)
   state.mem = enhanced
   state.flushPrint?.()
-  return { exports: wrap(memSrc), memory: enhanced, instance: inst, module: mod }
+  // A memoryless module keeps a minimal reader internally (state.mem, for decoding
+  // its SSO/atom boundary values), but the result's `.memory` stays null — the
+  // module genuinely exposes no linear memory. `jz.memory(result)` still hands back
+  // a usable reader on demand.
+  return { exports: wrap(memSrc), memory: enhanced?.scalar ? null : enhanced, instance: inst, module: mod }
 }
 
 /**
@@ -849,23 +887,29 @@ const finishInstantiation = (mod, inst, imports, needsWasi, opts, state) => {
  * @param {object} [opts]  host options: imports, memory, _interp, host-shape flags
  * @returns {{ exports, memory, instance, module }}
  */
+/**
+ * Compile wasm bytes to a `WebAssembly.Module`, preferring native
+ * `wasm:js-string` builtins when the engine honors the option (V8 17+/Safari
+ * 18.4+; older engines throw or ignore it — try-fallback handles both). A
+ * `WebAssembly.Module` passed in is returned as-is. Factor it out so callers
+ * can compile once and instantiate many times without re-validating the bytes
+ * (`instantiate(toModule(wasm))` skips the per-call compile on hot loops).
+ *
+ * @param {Uint8Array|ArrayBuffer|WebAssembly.Module} wasm
+ * @returns {WebAssembly.Module}
+ */
+export const toModule = (wasm) => {
+  if (wasm instanceof WebAssembly.Module) return wasm
+  if (jssProbeNative()) {
+    try { return new WebAssembly.Module(wasm, { builtins: ['js-string'] }) }
+    catch { return new WebAssembly.Module(wasm) }
+  }
+  return new WebAssembly.Module(wasm)
+}
+
 export const instantiate = (wasm, opts = {}) => {
   const state = prepareInterop(opts)
-  // Prefer native `wasm:js-string` builtins when the engine honors the option.
-  // The option is silently accepted by V8 17+/Safari 18.4+; older engines that
-  // don't recognize it either throw or ignore it — try-fallback handles both.
-  let mod
-  if (wasm instanceof WebAssembly.Module) {
-    mod = wasm
-  } else if (jssProbeNative()) {
-    try {
-      mod = new WebAssembly.Module(wasm, { builtins: ['js-string'] })
-    } catch {
-      mod = new WebAssembly.Module(wasm)
-    }
-  } else {
-    mod = new WebAssembly.Module(wasm)
-  }
+  const mod = toModule(wasm)
   const { imports, needsWasi } = buildImports(mod, opts, state)
   const hasImports = Object.keys(imports).some(k => k !== '_setMemory')
   const inst = new WebAssembly.Instance(mod, hasImports ? imports : undefined)