jz 0.4.0 → 0.5.0

package/{src/host.js → interop.js}

@@ -1,22 +1,118 @@
 /**
- * Interop runtime — JS ↔ WASM value marshaling.
+ * jz/interop — host-side boundary codec.
  *
- * NaN-boxing encoder/decoder, bump allocation, schema transport, host-object
- * handling. This is the *package* runtime that runs after compilation — it is
- * kept separate from the *compiler core* (index.js jz.compile) so the minimal
- * "pure scalar" story remains clean.
+ * Importable as `jz/interop` without pulling the compiler, parser, or watr —
+ * use this to run prebuilt jz wasm from a host that doesn't need to compile.
+ * Sole external dependency: `./wasi.js`.
+ *
+ * Marshals NaN-boxed `f64` values across the boundary: bump-allocated heap
+ * blobs (strings, arrays, typed arrays, objects), schema transport for
+ * fixed-shape objects, host-object externrefs.
  *
  * Exports:
  *   UNDEF_NAN, NULL_NAN, coerce          — null/undefined sentinels
+ *   i64ToF64, f64ToI64                    — bit-cast across the i64 boundary
  *   ptr / offset / type / aux             — NaN-boxed pointer codec
- *   memory(src)                           — enhance a WebAssembly.Memory
- *   wrap(memSrc, inst?)                   — adapt WASM exports to JS calling convention
- *   instantiate(compile, code, opts?)     — compile + instantiate + wrap
+ *   memory(src)                           — enhance a WebAssembly.Memory with read/write/String/Array/…
+ *   wrap(memSrc, inst?)                   — adapt raw wasm exports to JS calling convention
+ *   instantiate(wasm, opts?)              — instantiate prebuilt wasm bytes + wrap
+ *
+ * One boundary codec per binary: a jz wasm picks its host shape at compile
+ * time (`opts.host`). There is no runtime "driver sniff" — the host loading
+ * the binary knows which variant it asked for.
  *
- * @module runtime
+ * @module jz/interop
  */
 
-import { wasi } from '../wasi.js'
+import { wasi } from './wasi.js'
+
+// ── WASI linking ────────────────────────────────────────────────────────────
+
+const linkWasi = (mod, opts) => {
+  const needsWasi = WebAssembly.Module.imports(mod).some(i => i.module === 'wasi_snapshot_preview1')
+  return { needsWasi, wasiImports: needsWasi ? wasi(opts) : null }
+}
+
+const envFuncNames = (mod) =>
+  new Set(WebAssembly.Module.imports(mod)
+    .filter(i => i.module === 'env' && i.kind === 'function').map(i => i.name))
+
+// ── Allocator wiring ────────────────────────────────────────────────────────
+// Heap pointer: the exported `$__heap` global when the module has one (non-shared
+// memory), else memory[1020] (shared memory — globals are per-instance, so
+// threads must share a pointer cell in linear memory). 8-byte aligned bump on
+// the JS side; wasm `_alloc` takes over if exported.
+
+const HEAP_PTR_ADDR = 1020
+const HEAP_START = 1024
+
+const makeJsAllocator = (mem, heapGlobal) => {
+  const dv = () => new DataView(mem.buffer)
+  const getPtr = heapGlobal ? () => heapGlobal.value : () => dv().getInt32(HEAP_PTR_ADDR, true)
+  const setPtr = heapGlobal ? v => { heapGlobal.value = v } : v => dv().setInt32(HEAP_PTR_ADDR, v, true)
+  // Rewind target: the global's post-static-init value, else the fixed start.
+  const base = heapGlobal ? heapGlobal.value : HEAP_START
+  const alloc = (bytes) => {
+    const aligned = (getPtr() + 7) & ~7
+    const next = aligned + bytes
+    if (next > mem.buffer.byteLength)
+      mem.grow(Math.ceil((next - mem.buffer.byteLength) / 65536))
+    setPtr(next)
+    return aligned
+  }
+  const reset = () => setPtr(base)
+  // The global is initialized by wasm at module load; only the memory cell needs
+  // a JS-side nudge in case it underflows the heap start.
+  const initHeapPtr = () => {
+    if (heapGlobal) return
+    const d = dv()
+    if (d.getInt32(HEAP_PTR_ADDR, true) < HEAP_START) d.setInt32(HEAP_PTR_ADDR, HEAP_START, true)
+  }
+  return { alloc, reset, initHeapPtr }
+}
+
+// ── Custom-section reading ──────────────────────────────────────────────────
+
+const customSection = (mod, name) => {
+  const secs = WebAssembly.Module.customSections(mod, name)
+  return secs.length ? new Uint8Array(secs[0]) : null
+}
+
+const sectionReader = (bytes) => {
+  const td = new TextDecoder()
+  let i = 0
+  return {
+    pos: () => i,
+    seek: (p) => { i = p },
+    eof: () => i >= bytes.length,
+    u8: () => bytes[i++],
+    varint: () => {
+      let r = 0, s = 0
+      // eslint-disable-next-line no-constant-condition
+      while (true) {
+        const x = bytes[i++]
+        r |= (x & 0x7F) << s
+        if (!(x & 0x80)) return r
+        s += 7
+      }
+    },
+    str: (n) => { const s = td.decode(bytes.subarray(i, i + n)); i += n; return s },
+    bytes: (n) => { const r = bytes.subarray(i, i + n); i += n; return r },
+  }
+}
+
+const attachTimers = (inst) => {
+  if (!inst.exports.__timer_tick) return
+  const tick = inst.exports.__timer_tick
+  let hadTimers = false
+  const id = setInterval(() => {
+    const remaining = tick()
+    if (remaining > 0) hadTimers = true
+    if (hadTimers && remaining <= 0) clearInterval(id)
+  }, 1)
+}
+
+// ── NaN-box codec ───────────────────────────────────────────────────────────
 
 // NaN-boxing encode/decode — shared 8-byte scratch buffer
 const _buf = new ArrayBuffer(8), _u32 = new Uint32Array(_buf), _f64 = new Float64Array(_buf)
@@ -37,6 +133,11 @@ export const f64ToI64 = _bi64.f64ToI64
 // Distinct from 0, JS NaN (payload=0), and all pointers.
 _u32[1] = 0x7FF80001; _u32[0] = 0; export const NULL_NAN = _f64[0]
 _u32[1] = 0x7FF80002; _u32[0] = 0; export const UNDEF_NAN = _f64[0]
+// Boxed-boolean atoms (type=0, offset=0): aux=4 → false, aux=5 → true. The
+// low aux bit is the truth value; only exported scalars cross as these — the
+// inner 0/1 number carrier never escapes the wasm boundary.
+_u32[1] = 0x7FF80004; _u32[0] = 0; export const FALSE_NAN = _f64[0]
+_u32[1] = 0x7FF80005; _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
@@ -48,6 +149,8 @@ const decode = v => {
   if (_u32[0] !== 0) return v
   if (_u32[1] === 0x7FF80001) return null
   if (_u32[1] === 0x7FF80002) return undefined
+  if (_u32[1] === 0x7FF80004) return false
+  if (_u32[1] === 0x7FF80005) return true
   return v
 }
 
@@ -111,58 +214,44 @@ export const memory = (src) => {
 
   const dv = () => new DataView(mem.buffer)
 
-  // JS-side bump allocator (heap ptr at byte 1020, same convention as WASM)
-  const jsAlloc = (bytes) => {
-    let d = dv(), p = d.getInt32(1020, true)
-    const aligned = (p + 7) & ~7  // 8-byte align
-    const next = aligned + bytes
-    if (next > mem.buffer.byteLength) {
-      mem.grow(Math.ceil((next - mem.buffer.byteLength) / 65536))
-      d = dv()  // buffer was detached by grow
-    }
-    d.setInt32(1020, next, true)
-    return aligned
-  }
-
-  // Use WASM allocator if available, else JS-side bump
+  // Allocator scaffold: bumps the exported `$__heap` global (or memory[1020] for
+  // shared memory). Wasm `_alloc` takes over when exported; `_clear`/jsReset rewinds.
+  const { alloc: jsAlloc, reset: jsReset, initHeapPtr } = makeJsAllocator(mem, wasmExports?.__heap)
   let alloc = wasmExports?._alloc || jsAlloc
-  // JS-side reset: rewind the bump pointer at byte 1020. Only used when no WASM
-  // _clear is present (otherwise the WASM global / shared slot is authoritative).
-  const jsReset = () => dv().setInt32(1020, 1024, true)
-
-  // Initialize heap pointer if not yet set
-  const initDv = dv()
-  if (initDv.getInt32(1020, true) < 1024) initDv.setInt32(1020, 1024, true)
+  initHeapPtr()
 
-  // Write header (len + cap), return data offset
+  // Write 16-byte header matching WASM `__alloc_hdr`:
+  // [propsPtr@+0(i64=0), len@+8, cap@+12], return data offset (raw+16).
+  // Read paths (ARRAY at off-8/-4, BUFFER at off-8) and the propsPtr slot at
+  // off-16 then work uniformly on JS- and WASM-allocated values.
   const hdr = (len, cap, bytes) => {
-    const raw = alloc(8 + bytes)
+    const raw = alloc(16 + bytes)
     const m = dv()
-    m.setInt32(raw, len, true)
-    m.setInt32(raw + 4, cap, true)
-    return raw + 8
+    m.setBigInt64(raw, 0n, true)
+    m.setInt32(raw + 8, len, true)
+    m.setInt32(raw + 12, cap, true)
+    return raw + 16
   }
 
-  // Read schemas from module custom section, merge into memory.schemas
+  // Read schemas from module custom section, merge into memory.schemas. Schema
+  // entries are { type, payload } where type=0 means null (computed/missing
+  // key), type=1 means nested [null, name] (synthetic shape), else a UTF-8
+  // length-prefixed property name. Section format is varint-prefixed list.
   let schemas = mem.schemas || []
-  if (mod) {
-    const secs = WebAssembly.Module.customSections(mod, 'jz:schema')
-    if (secs.length) {
-      const b = new Uint8Array(secs[0]), td = new TextDecoder()
-      let i = 0
-      const varint = () => { let r = 0, s = 0; while (1) { const x = b[i++]; r |= (x & 0x7F) << s; if (!(x & 0x80)) return r; s += 7 } }
-      const dec = () => {
-        const t = b[i++]
-        if (t === 0) return null
-        if (t === 1) return [null, dec()]
-        const n = varint(), s = td.decode(b.subarray(i, i + n)); i += n; return s
-      }
-      const nS = varint(), newSchemas = []
-      for (let j = 0; j < nS; j++) { const k = varint(), props = []; for (let p = 0; p < k; p++) props.push(dec()); newSchemas.push(props) }
-      for (const s of newSchemas) {
-        const key = s.join(',')
-        if (!schemas.some(existing => existing.join(',') === key)) schemas.push(s)
-      }
+  const schemaBytes = mod && customSection(mod, 'jz:schema')
+  if (schemaBytes) {
+    const r = sectionReader(schemaBytes)
+    const dec = () => {
+      const t = r.u8()
+      if (t === 0) return null
+      if (t === 1) return [null, dec()]
+      return r.str(r.varint())
+    }
+    const nS = r.varint(), newSchemas = []
+    for (let j = 0; j < nS; j++) { const k = r.varint(), props = []; for (let p = 0; p < k; p++) props.push(dec()); newSchemas.push(props) }
+    for (const s of newSchemas) {
+      const key = s.join(',')
+      if (!schemas.some(existing => existing.join(',') === key)) schemas.push(s)
     }
   }
 
@@ -277,6 +366,8 @@ export const memory = (src) => {
     if (t === 0 && off === 0) {
       if (a === 1) return null
       if (a === 2) return undefined
+      if (a === 4) return false
+      if (a === 5) return true
     }
     if (t === 11 && this._extMap) return this._extMap[off]
     if (t === 1) {  // ARRAY
@@ -414,10 +505,11 @@ export const wrap = (memSrc, inst) => {
   const restFuncs = new Map()
   const mod = inst ? memSrc : memSrc.module || memSrc
   const realInst = inst || memSrc.instance || memSrc
-  const restSecs = WebAssembly.Module.customSections(mod, 'jz:rest')
-  if (restSecs.length) {
+  const td = new TextDecoder()
+  const restBytes = customSection(mod, 'jz:rest')
+  if (restBytes) {
     try {
-      for (const entry of JSON.parse(new TextDecoder().decode(restSecs[0])))
+      for (const entry of JSON.parse(td.decode(restBytes)))
         restFuncs.set(typeof entry === 'string' ? entry : entry.name, typeof entry === 'string' ? 0 : entry.fixed)
     } catch (e) { /* ignore */ }
   }
@@ -427,11 +519,29 @@ export const wrap = (memSrc, inst) => {
   // reinterprets f64↔BigInt only at those positions (see
   // synthesizeBoundaryWrappers).
   const i64Exp = new Map(), EMPTY_SET = new Set()
-  const i64Secs = WebAssembly.Module.customSections(mod, 'jz:i64exp')
-  if (i64Secs.length) {
-    try { for (const e of JSON.parse(new TextDecoder().decode(i64Secs[0]))) i64Exp.set(e.name, { p: new Set(e.p), r: e.r }) }
+  const i64Bytes = customSection(mod, 'jz:i64exp')
+  if (i64Bytes) {
+    try { for (const e of JSON.parse(td.decode(i64Bytes))) i64Exp.set(e.name, { p: new Set(e.p), r: e.r }) }
     catch { /* ignore */ }
   }
+  // externref-param exports: positions where the wasm side takes an externref
+  // (e.g. jsstring boundary opt-in). JS values at these positions pass through
+  // unchanged — no `mem.wrapVal` (would NaN-box into f64, defeating the point).
+  // `def` (optional) maps idx → default-string for jsstring params whose
+  // default substitution happens JS-side (the wasm side never sees null).
+  const extExp = new Map()
+  const extBytes = customSection(mod, 'jz:extparam')
+  if (extBytes) {
+    try {
+      for (const e of JSON.parse(td.decode(extBytes))) {
+        const idx = new Set(e.p)
+        // Hang the defaults off the Set as a property so call-sites that only
+        // check membership stay unchanged; the slow path reads `extInfo.def`.
+        if (e.d) idx.def = new Map(Object.entries(e.d).map(([k, v]) => [Number(k), v]))
+        extExp.set(e.name, idx)
+      }
+    } catch { /* ignore */ }
+  }
 
   const mem = memory(memSrc)
   const lastErrBits = realInst.exports.__jz_last_err_bits
@@ -453,17 +563,36 @@ export const wrap = (memSrc, inst) => {
   // indices; r = result is i64. Numeric (f64) positions pass through unchanged.
   const adaptArgs = (a, p) => p.size === 0 ? a : a.map((x, i) => p.has(i) ? f64ToI64(x) : x)
   const adaptRet = (ret, r) => r ? i64ToF64(ret) : ret
+  // Externref positions skip mem.wrapVal — the raw JS value (string, object,
+  // …) flows through as externref. mem.wrapVal would NaN-box it.
+  const wrapArg = (ext, i, x) => ext?.has(i) ? x : mem.wrapVal(x)
 
   // Arity-specialized wrapper: rest-spread + .map() + .apply() costs ~85ns/call
   // on hot loops (mandelbrot benchmark: 51ms wrapped vs 35ms direct over 200K
   // calls). Generating positional `function(a0, a1, ...)` via Function lets V8
   // fully inline the WASM call. Falls back to the spread-form wrapper if the
   // Function constructor is unavailable (CSP) or arity is unusually large.
-  const makeFastWrapper = (fn, len, p, r, decode_, wrap_) => {
+  // `ext` is a Set of externref param positions — those slots skip wrap/coerce
+  // and pass the JS value directly (jsstring carrier: JS string → externref).
+  // `ext.def` (optional Map idx→string) carries jsstring-literal defaults that
+  // are substituted JS-side when the caller passes `undefined`.
+  const makeFastWrapper = (fn, len, p, r, decode_, wrap_, ext) => {
     const params = [], wrapped = []
+    const defs = ext?.def
+    const defArgs = [], defNames = []
     for (let i = 0; i < len; i++) {
       const a = `a${i}`
       params.push(a)
+      if (ext?.has(i)) {
+        if (defs?.has(i)) {
+          const dn = `def${i}`
+          defNames.push(dn); defArgs.push(defs.get(i))
+          wrapped.push(`(${a} === undefined ? ${dn} : ${a})`)
+        } else {
+          wrapped.push(a)
+        }
+        continue
+      }
       const w = wrap_ ? `wrap_(${a})` : `coerce(${a})`
       wrapped.push(p.has(i) ? `f64ToI64(${w})` : w)
     }
@@ -472,8 +601,8 @@ export const wrap = (memSrc, inst) => {
     const body = `return function(${params.join(',')}) {\n` +
       `  try { return decode_(${retExpr}) } catch (e) { decodeThrown(e) }\n` +
       `}`
-    return new Function('fn', 'wrap_', 'coerce', 'decode_', 'f64ToI64', 'i64ToF64', 'decodeThrown', body)(
-      fn, wrap_, coerce, decode_, f64ToI64, i64ToF64, decodeThrown)
+    return new Function('fn', 'wrap_', 'coerce', 'decode_', 'f64ToI64', 'i64ToF64', 'decodeThrown', ...defNames, body)(
+      fn, wrap_, coerce, decode_, f64ToI64, i64ToF64, decodeThrown, ...defArgs)
   }
 
   // Pure scalar module (no memory): pass f64 values directly, no marshaling
@@ -482,15 +611,19 @@ export const wrap = (memSrc, inst) => {
       if (typeof fn !== 'function') { exports[name] = fn; continue }
       const sig = i64Exp.get(name)
       const p = sig?.p || EMPTY_SET, r = sig?.r || 0
+      const ext = extExp.get(name)
       const len = fn.length
       try {
-        exports[name] = makeFastWrapper(fn, len, p, r, decode, null)
+        exports[name] = makeFastWrapper(fn, len, p, r, decode, null, ext)
         continue
       } catch { /* CSP fallback */ }
       exports[name] = (...args) => {
         while (args.length < len) args.push(undefined)
         try {
-          const wasmArgs = adaptArgs(args.map(coerce), p)
+          const wasmArgs = adaptArgs(args.map((x, i) => {
+            if (!ext?.has(i)) return coerce(x)
+            return x === undefined && ext.def?.has(i) ? ext.def.get(i) : x
+          }), p)
           return decode(adaptRet(fn(...wasmArgs), r))
         } catch (e) { decodeThrown(e) }
       }
@@ -504,8 +637,12 @@ export const wrap = (memSrc, inst) => {
       const fixed = restFuncs.get(name)
       const sig = i64Exp.get(name)
       const p = sig?.p || EMPTY_SET, r = sig?.r || 0
+      const ext = extExp.get(name)
       exports[name] = (...args) => {
-        const a = args.slice(0, fixed).map(x => mem.wrapVal(x))
+        const a = args.slice(0, fixed).map((x, i) => {
+          if (!ext?.has(i)) return mem.wrapVal(x)
+          return x === undefined && ext.def?.has(i) ? ext.def.get(i) : x
+        })
         while (a.length < fixed) a.push(UNDEF_NAN)
         a.push(mem.Array(args.slice(fixed)))
         try {
@@ -518,15 +655,19 @@ export const wrap = (memSrc, inst) => {
     } else if (typeof fn === 'function') {
       const sig = i64Exp.get(name)
       const p = sig?.p || EMPTY_SET, r = sig?.r || 0
+      const ext = extExp.get(name)
       const len = fn.length
       try {
-        exports[name] = makeFastWrapper(fn, len, p, r, memRead, memWrapVal)
+        exports[name] = makeFastWrapper(fn, len, p, r, memRead, memWrapVal, ext)
         continue
       } catch { /* CSP fallback */ }
       exports[name] = (...args) => {
         while (args.length < len) args.push(undefined)
         try {
-          const boxed = args.map(x => mem.wrapVal(x))
+          const boxed = args.map((x, i) => {
+            if (!ext?.has(i)) return mem.wrapVal(x)
+            return x === undefined && ext.def?.has(i) ? ext.def.get(i) : x
+          })
           const ret = fn.apply(null, adaptArgs(boxed, p))
           return mem.read(adaptRet(ret, r))
         } catch (error) {
@@ -573,8 +714,7 @@ const prepareInterop = (opts) => {
 // imports them (host: 'js' mode lowering in module/console.js). Caller-provided
 // opts.imports.env entries take precedence.
 const installDefaultEnvImports = (mod, imports, state) => {
-  const envFns = new Set(WebAssembly.Module.imports(mod)
-    .filter(i => i.module === 'env' && i.kind === 'function').map(i => i.name))
+  const envFns = envFuncNames(mod)
   if (!envFns.size) return
   if (!imports.env) imports.env = {}
   if (envFns.has('print') && !imports.env.print) {
@@ -647,11 +787,61 @@ const installDefaultEnvImports = (mod, imports, state) => {
   }
 }
 
+// JS-side polyfills for `wasm:js-string` builtins. Used when the engine does
+// NOT honor `new WebAssembly.Module(buf, { builtins: ['js-string'] })` — older
+// V8, Hermes, JSC pre-18.4, etc. With native builtins the engine inlines
+// these calls to direct string accesses; with the polyfill each call is a
+// wasm→JS hop (still correct, just no boundary win).
+const JSS_POLYFILL = {
+  length:     (s) => s.length,
+  charCodeAt: (s, i) => s.charCodeAt(i),
+}
+
+// Probe once: does this engine honor the `{ builtins: ['js-string'] }` option
+// on WebAssembly.Module? Compiles a tiny module that imports a wasm:js-string
+// fn; if instantiation succeeds with no imports object, native is available.
+let jssNativeProbed = false
+let jssNativeSupported = false
+const jssProbeNative = () => {
+  if (jssNativeProbed) return jssNativeSupported
+  jssNativeProbed = true
+  try {
+    // Minimal module: (module (import "wasm:js-string" "length" (func (param externref) (result i32))))
+    const bytes = new Uint8Array([
+      0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00,        // header
+      0x01, 0x06, 0x01, 0x60, 0x01, 0x6f, 0x01, 0x7f,        // type: (externref)→i32
+      0x02, 0x18, 0x01,                                       // import section
+      0x0f, ...new TextEncoder().encode('wasm:js-string'),    // mod name
+      0x06, ...new TextEncoder().encode('length'),            // name
+      0x00, 0x00,                                             // kind=func, type=0
+    ])
+    const mod = new WebAssembly.Module(bytes, { builtins: ['js-string'] })
+    new WebAssembly.Instance(mod, {})
+    jssNativeSupported = true
+  } catch {
+    jssNativeSupported = false
+  }
+  return jssNativeSupported
+}
+
 const buildImports = (mod, opts, state) => {
-  const needsWasi = WebAssembly.Module.imports(mod).some(i => i.module === 'wasi_snapshot_preview1')
-  const imports = needsWasi ? wasi(opts) : {}
+  const { needsWasi, wasiImports } = linkWasi(mod, opts)
+  const imports = wasiImports || {}
   if (opts._interp) imports.env = { ...imports.env, ...opts._interp }
 
+  // `wasm:js-string` polyfills — only attach when native builtins aren't honored
+  // by this engine. With `{ builtins: ['js-string'] }` the import slots are
+  // already filled by the engine; supplying a JS function would error or just
+  // be ignored. Without native support, polyfill the names this module imports.
+  if (!jssProbeNative()) {
+    for (const imp of WebAssembly.Module.imports(mod)) {
+      if (imp.module === 'wasm:js-string' && JSS_POLYFILL[imp.name]) {
+        if (!imports['wasm:js-string']) imports['wasm:js-string'] = {}
+        imports['wasm:js-string'][imp.name] = JSS_POLYFILL[imp.name]
+      }
+    }
+  }
+
   // Host imports: decode NaN-boxed args for JS and wrap JS returns back into jz
   // values. Args/return ride i64 across the boundary (Step 2c) so V8 cannot
   // canonicalize the NaN payload — convert BigInt↔f64 via reinterpret bits.
@@ -705,16 +895,8 @@ const finishInstantiation = (mod, inst, imports, needsWasi, opts, state) => {
   // Trampoline used by env.setTimeout/clearTimeout to fire scheduled closures.
   state.invoke = inst.exports.__invoke_closure || null
 
-  // Drive WASM timer queue via JS scheduling (non-blocking)
-  if (inst.exports.__timer_tick) {
-    const tick = inst.exports.__timer_tick
-    let hadTimers = false
-    const id = setInterval(() => {
-      const remaining = tick()
-      if (remaining > 0) hadTimers = true
-      if (hadTimers && remaining <= 0) clearInterval(id)
-    }, 1)
-  }
+  // Drive WASM timer queue via JS scheduling (non-blocking, no-op if absent).
+  attachTimers(inst)
 
   // For shared memory, resolve memory from import; for own memory, from export.
   const rawMemory = opts.memory instanceof WebAssembly.Memory ? opts.memory : inst.exports.memory
@@ -726,14 +908,35 @@ const finishInstantiation = (mod, inst, imports, needsWasi, opts, state) => {
 }
 
 /**
- * Compile, instantiate, and wrap exports (with WASI + rest-param support).
- * `compile` is the jz.compile function (injected to avoid importing the compiler core).
+ * Instantiate prebuilt jz wasm and wrap exports (WASI imports, rest-params,
+ * host-object externrefs, default env.print/now wiring, optional shared memory).
+ *
+ * Compile-and-instantiate is the caller's job — pass already-compiled bytes:
+ *   import { instantiate } from 'jz/interop'
+ *   const { exports, memory } = instantiate(wasmBytes)
+ *
+ * @param {Uint8Array|ArrayBuffer|WebAssembly.Module} wasm  prebuilt wasm
+ * @param {object} [opts]  host options: imports, memory, _interp, host-shape flags
+ * @returns {{ exports, memory, instance, module }}
  */
-export const instantiate = (compile, code, opts = {}) => {
+export const instantiate = (wasm, opts = {}) => {
   const state = prepareInterop(opts)
-  const wasm = compile(code, opts)
   opts.extMap = state.extMap
-  const mod = new WebAssembly.Module(wasm)
+  // 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 { imports, needsWasi } = buildImports(mod, opts, state)
   const hasImports = Object.keys(imports).some(k => k !== '_setMemory')
   const inst = new WebAssembly.Instance(mod, hasImports ? imports : undefined)