jz 0.5.1 → 0.6.0

package/jzify/switch.js

@@ -0,0 +1,106 @@
+/**
+ * switch → if/else + fall-through lowering.
+ * @module jzify/switch
+ */
+
+/** Flatten a switch clause body to a single node, dropping ASI position markers.
+ * Unlike a plain statement list this keeps any `break` intact — transformSwitch
+ * needs the breaks to gate fall-through; it rewrites them to a sticky flag. */
+export function normalizeCaseBody(body) {
+  if (!Array.isArray(body) || body[0] !== ';') return body
+  const stmts = body.slice(1).filter(s => s != null && typeof s !== 'number')
+  return stmts.length === 0 ? null : stmts.length === 1 ? stmts[0] : [';', ...stmts]
+}
+
+const SWITCH_BREAK_BOUNDARIES = new Set(['for', 'for-in', 'for-of', 'while', 'do', 'switch', '=>', 'function', 'class'])
+
+function hasOwnSwitchBreak(node) {
+  if (!Array.isArray(node)) return false
+  if (node[0] === 'break') return true
+  if (SWITCH_BREAK_BOUNDARIES.has(node[0])) return false
+  for (let i = 1; i < node.length; i++) if (hasOwnSwitchBreak(node[i])) return true
+  return false
+}
+
+function rewriteSwitchBreaks(node, flag) {
+  if (!Array.isArray(node)) return node
+  const op = node[0]
+  if (op === 'break') return ['=', flag, [null, true]]
+  if (SWITCH_BREAK_BOUNDARIES.has(op)) return node
+
+  if (op === ';') {
+    const out = []
+    const stmts = node.slice(1)
+    for (let i = 0; i < stmts.length; i++) {
+      const stmt = stmts[i]
+      out.push(rewriteSwitchBreaks(stmt, flag))
+      if (hasOwnSwitchBreak(stmt) && i < stmts.length - 1) {
+        const tail = rewriteSwitchBreaks([';', ...stmts.slice(i + 1)], flag)
+        out.push(['if', ['!', flag], tail])
+        break
+      }
+    }
+    return out.length === 0 ? null : out.length === 1 ? out[0] : [';', ...out]
+  }
+
+  return node.map((part, i) => i === 0 ? part : rewriteSwitchBreaks(part, flag))
+}
+
+/** Transform a switch into structured control flow with faithful fall-through.
+ *
+ * A pure if/else-if chain (the former lowering) can't express fall-through,
+ * stacked labels, or a `default` clause that isn't last \u2014 it ran only the first
+ * matching body. The correct model is two-phase, evaluated once with no goto:
+ *
+ *   1. ENTRY \u2014 compare the discriminant against each `case` label in source
+ *      order; the first `===` match fixes the entry index. No case matches \u2192
+ *      entry = the `default` clause's source index (or past-end if none).
+ *   2. RUN \u2014 walk clauses in source order; `entry <= i` runs clause i, so every
+ *      clause from the entry onward executes (fall-through). A `break` flips the
+ *      sticky `brk` flag (via rewriteSwitchBreaks) and gates the rest.
+ *
+ * The discriminant is bound to a temp only when re-reading it isn't free/safe; a
+ * bare identifier is compared directly \u2014 a synthetic temp would shed its STRING
+ * val-type and mis-fold string `case`s to `false` under strict-=== folding. */
+export function createSwitchLowering(transform, names) {
+  return function transformSwitch(discriminant, cases) {
+  const disc = transform(discriminant)
+  const simple = typeof disc === 'string' || (Array.isArray(disc) && disc[0] == null)
+  const tmp = simple ? disc : names.switchDisc()
+  const start = names.switchStart()
+  const needsBreakFlag = cases.some(c => hasOwnSwitchBreak(c[0] === 'case' ? c[2] : c[1]))
+  const brk = needsBreakFlag ? names.switchBreak() : null
+
+  const n = cases.length
+  let defaultIdx = -1
+  const bodies = cases.map((c, i) => {
+    if (c[0] === 'default') { defaultIdx = i; return transform(c[1]) }
+    return transform(c[2])
+  })
+
+  const stmts = []
+  if (!simple) stmts.push(['let', ['=', tmp, disc]])
+
+  // Phase 1 \u2014 entry index. Init to default's position (or n = "no clause runs"),
+  // then let the first matching label override it via an if/else-if chain.
+  stmts.push(['let', ['=', start, [null, defaultIdx >= 0 ? defaultIdx : n]]])
+  let chain = null
+  for (let i = n - 1; i >= 0; i--) {
+    if (cases[i][0] !== 'case') continue
+    const hit = ['=', start, [null, i]]
+    const cond = ['===', tmp, transform(cases[i][1])]
+    chain = chain != null ? ['if', cond, hit, chain] : ['if', cond, hit]
+  }
+  if (chain) stmts.push(chain)
+  if (brk) stmts.push(['let', ['=', brk, [null, false]]])
+
+  // Phase 2 \u2014 run clauses from the entry index, falling through until a break.
+  for (let i = 0; i < n; i++) {
+    if (bodies[i] == null) continue
+    const body = brk ? rewriteSwitchBreaks(bodies[i], brk) : bodies[i]
+    const reached = ['<=', start, [null, i]]
+    stmts.push(['if', brk ? ['&&', ['!', brk], reached] : reached, body])
+  }
+  return [';', ...stmts]
+  }
+}

package/jzify/transform.js

@@ -0,0 +1,349 @@
+/**
+ * AST transform handlers — function/class/control-flow lowering after hoisting.
+ * @module jzify/transform
+ */
+
+import { warn } from '../src/ctx.js'
+import { JZ_BLOCK_OPS, LABEL_BODY_OPS, STMT_ONLY_OPS, paramList } from '../src/ast.js'
+import { isDestructurePat } from './hoist-vars.js'
+
+const ERROR_INSTANCEOF = new Set(['Error', 'TypeError', 'SyntaxError', 'RangeError', 'ReferenceError', 'URIError', 'EvalError'])
+
+const TYPED_ARRAYS = new Set(['Float64Array','Float32Array','Int32Array','Uint32Array',
+  'Int16Array','Uint16Array','Int8Array','Uint8Array',
+  'ArrayBuffer','BigInt64Array','BigUint64Array','DataView'])
+
+const isProto = n => Array.isArray(n) && n[0] === '.' && Array.isArray(n[1]) && n[1][0] === '.' && n[1][2] === 'prototype'
+
+function staticInstanceofFold(val, ctor) {
+  if (typeof ctor !== 'string' || !Array.isArray(val)) return null
+  if (val[0] === '()' && val.length === 2) return staticInstanceofFold(val[1], ctor)
+  if (val[0] === '[]' && val.length <= 2) return ctor === 'Array' || ctor === 'Object'
+  if (val[0] === '{}') return ctor === 'Object'
+  if (val[0] === '//') return ctor === 'RegExp' || ctor === 'Object'
+  if (val[0] === 'new') {
+    const inner = val[1]
+    const cname = typeof inner === 'string' ? inner
+      : (Array.isArray(inner) && inner[0] === '()' && typeof inner[1] === 'string') ? inner[1]
+      : null
+    if (cname) return cname === ctor || (cname !== 'Object' && ctor === 'Object')
+  }
+  if (val[0] == null && val.length === 2) {
+    const v = val[1]
+    if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean' || v == null) return false
+  }
+  return null
+}
+
+function dedupeRedecls(stmts) {
+  const declName = d => typeof d === 'string' ? d
+    : Array.isArray(d) && d[0] === '=' && typeof d[1] === 'string' ? d[1] : null
+  const seen = new Set(), out = []
+  for (const s of stmts) {
+    if (!Array.isArray(s) || (s[0] !== 'let' && s[0] !== 'const' && s[0] !== 'var')) { out.push(s); continue }
+    const keep = [s[0]], reassign = []
+    for (let i = 1; i < s.length; i++) {
+      const d = s[i], n = declName(d)
+      if (n == null) { keep.push(d); continue }
+      if (seen.has(n)) { if (Array.isArray(d) && d[0] === '=') reassign.push(['=', d[1], d[2]]) }
+      else { seen.add(n); keep.push(d) }
+    }
+    if (keep.length > 1) out.push(keep)
+    for (const r of reassign) out.push(r)
+  }
+  return out
+}
+
+function functionBodyBlock(body) {
+  if (Array.isArray(body) && body[0] === '{}') return body
+  if (Array.isArray(body) && body[0] === ';') return ['{}', body]
+  return ['{}', [';', body]]
+}
+
+const arrowParams = params => Array.isArray(params) && params[0] === '()' ? params : ['()', params]
+
+/**
+ * @param {object} opts
+ * @param {ReturnType<import('./names.js').createNames>} opts.names
+ * @param {Function} opts.lowerArguments
+ * @param {Function} opts.transformPattern
+ * @param {Function} opts.normalizeCaseBody
+ * @param {Function} opts.transformSwitch
+ * @param {() => Function} opts.lowerClass
+ * @param {() => Function} opts.lowerObjectLiteralThis
+ * @param {() => Function} opts.lowerArrayConstructor
+ */
+export function createTransform(opts) {
+  const { names, lowerArguments, transformPattern, normalizeCaseBody, transformSwitch } = opts
+  const lowerClass = (...a) => opts.lowerClass()(...a)
+  const lowerObjectLiteralThis = (...a) => opts.lowerObjectLiteralThis()(...a)
+  const lowerArrayConstructor = (...a) => opts.lowerArrayConstructor()(...a)
+
+  const methodOverrideHasOwn = (a, b) => {
+    const proto = isProto(a) ? a : isProto(b) ? b : null
+    if (!proto) return null
+    const other = proto === a ? b : a
+    if (!Array.isArray(other) || other[0] !== '.' || other[2] !== proto[2]) return null
+    return ['()', ['.', transform(other[1]), 'hasOwnProperty'], [null, proto[2]]]
+  }
+
+  function wrapArrowBody(body) {
+    const t = transformScope(body)
+    if (!Array.isArray(t)) return ['{}', [';', t]]
+    if (t[0] === ';') return ['{}', t]
+    if (t[0] !== '{}') return ['{}', [';', t]]
+    if (t.length === 2 && !(Array.isArray(t[1]) && t[1][0] === ';')) return ['{}', [';', t[1]]]
+    return t
+  }
+
+  function hoistFnDecl(name, params, body) {
+    const [p2, b2] = lowerArguments(params, functionBodyBlock(body))
+    const decl = ['const', ['=', name, ['=>', p2, wrapArrowBody(b2)]]]
+    decl._hoisted = true
+    return decl
+  }
+
+  function transformScope(node) {
+    if (!Array.isArray(node)) return transform(node)
+
+    const [op, ...args] = node
+
+    if (op === 'function' && args[0]) return hoistFnDecl(...args)
+    if (op === 'class' && args[0]) return ['let', ['=', args[0], lowerClass(...args)]]
+
+    if (op === ';') {
+      const hoisted = [], rest = []
+      for (let i = 0; i < args.length; i++) {
+        const stmt = args[i]
+        if (Array.isArray(stmt) && stmt[0] === 'function' && stmt[1]) {
+          hoisted.push(hoistFnDecl(stmt[1], stmt[2], stmt[3]))
+          continue
+        }
+        if (Array.isArray(stmt) && stmt[0] === 'class' && stmt[1]) {
+          rest.push(['let', ['=', stmt[1], lowerClass(stmt[1], stmt[2], stmt[3])]])
+          continue
+        }
+        const t = transform(stmt)
+        if (t == null) continue
+        if (Array.isArray(t) && t[0] === 'const' && t._hoisted) {
+          hoisted.push(t)
+        } else if (Array.isArray(t) && t[0] === ';') {
+          for (const s of t.slice(1)) {
+            if (s != null) {
+              if (Array.isArray(s) && s[0] === 'const' && s._hoisted) hoisted.push(s)
+              else rest.push(s)
+            }
+          }
+        } else {
+          rest.push(t)
+        }
+      }
+      // ES hoists every import binding above any function body. jzify mirrors
+      // that by floating imports ahead of hoisted function decls. A combo import
+      // `import d, { n } from 'm'` parses as `[',', ['import',…], ['from',…]]`, so
+      // match the comma-wrapped form too — otherwise its bindings land after the
+      // hoisted functions that reference them ("X is not in scope").
+      const isImportStmt = s => Array.isArray(s) &&
+        (s[0] === 'import' || (s[0] === ',' && Array.isArray(s[1]) && s[1][0] === 'import'))
+      const imports = rest.filter(isImportStmt)
+      const nonImports = rest.filter(s => !isImportStmt(s))
+      const all = dedupeRedecls([...imports, ...hoisted, ...nonImports])
+      return all.length === 0 ? null : all.length === 1 ? all[0] : [';', ...all]
+    }
+
+    return transform(node)
+  }
+
+  const handlers = {
+    '()'(callee, ...rest) {
+      if (callee === 'Array') {
+        const lit = lowerArrayConstructor(rest[0])
+        if (lit) return lit
+      }
+      if (Array.isArray(callee) && callee[0] === '()' && Array.isArray(callee[1]) && callee[1][0] === 'function' && callee[1][1]) {
+        const [, name, params, body] = callee[1]
+        const [p2, b2] = lowerArguments(params, functionBodyBlock(body))
+        // `(function name(){…})(args)` — the named binding must be lowered as a
+        // self-contained EXPRESSION (it can sit in concise-arrow-body / argument
+        // position), so wrap the `let name = arrow; name(args)` in a block IIFE
+        // rather than emitting a bare `;`-sequence. A statement-sequence in
+        // expression position never reaches the `'=>'` handler's block-wrap (that
+        // runs before this transform), and emit miscompiles a `let`-closure decl in
+        // a concise `;`-body. Mirrors the bare-`function name` lowering below.
+        return ['()', ['=>', null, ['{}', [';',
+          ['let', ['=', name, ['=>', arrowParams(p2), wrapArrowBody(b2)]]],
+          ['return', ['()', name, ...rest.map(transform)]],
+        ]]], null]
+      }
+    },
+
+    'function'(name, params, body) {
+      const [p2, b2] = lowerArguments(params, functionBodyBlock(body))
+      const arrow = ['=>', p2, wrapArrowBody(b2)]
+      if (name) {
+        return ['()', ['()', ['=>', null, ['{}', [';',
+          ['let', name],
+          ['=', name, arrow],
+          ['return', name]
+        ]]]], null]
+      }
+      return arrow
+    },
+
+    '=>'(params, body) {
+      let b = body
+      if (Array.isArray(b) && b[0] === '{}' && b.length === 2) {
+        const inner = b[1]
+        if (inner != null && !(Array.isArray(inner) && inner[0] === ';')) {
+          b = ['{}', [';', inner]]
+        }
+      } else if (Array.isArray(b) && STMT_ONLY_OPS.has(b[0])) {
+        // Subscript's expression grammar lets statement-only ops (`if`, `for`,
+        // `return`, `;`, …) appear in concise-body position — method shorthand
+        // `m(){ stmt }` parses to `['=>', p, stmt]` with no `{}` wrap (the body
+        // braces are structural, not a group operator). A concise body must
+        // yield a value, so these void ops would otherwise be coerced into the
+        // f64 return slot ("not enough arguments on the stack for f64.convert_i32_s").
+        // Re-wrap as a block — statement bodies belong in block form.
+        b = b[0] === ';' ? ['{}', b] : ['{}', [';', b]]
+      }
+      const [p2, b2] = lowerArguments(params, b)
+      return ['=>', p2, transform(b2)]
+    },
+
+    'class'(name, heritage, body) { return lowerClass(name, heritage, body) },
+
+    'var'(...args) {
+      return ['let', ...args.map(transform)]
+    },
+
+    ':'(label, body) {
+      if (typeof label === 'string' && Array.isArray(body) && LABEL_BODY_OPS.has(body[0]))
+        return ['label', label, transform(body)]
+    },
+
+    '='(lhs, rhs) {
+      if (isDestructurePat(lhs)) return ['=', transformPattern(lhs), transform(rhs)]
+    },
+
+    'switch'(disc, ...cases) {
+      const clean = cases.map(c => {
+        if (c[0] === 'case') return ['case', c[1], normalizeCaseBody(c[2])]
+        if (c[0] === 'default') return ['default', normalizeCaseBody(c[1])]
+        return c
+      })
+      return transformSwitch(disc, clean)
+    },
+
+    '=='(a, b) { const own = methodOverrideHasOwn(a, b); if (own) return ['!', own]; return isProto(a) || isProto(b) ? 1 : ['==', transform(a), transform(b)] },
+    '!='(a, b) { const own = methodOverrideHasOwn(a, b); if (own) return own; return isProto(a) || isProto(b) ? 0 : ['!=', transform(a), transform(b)] },
+    '==='(a, b) { const own = methodOverrideHasOwn(a, b); if (own) return ['!', own]; if (isProto(a) || isProto(b)) return 1 },
+    '!=='(a, b) { const own = methodOverrideHasOwn(a, b); if (own) return own; if (isProto(a) || isProto(b)) return 0 },
+
+    'new'(ctor, ...cargs) {
+      if (Array.isArray(ctor) && ctor[0] === '()' && ctor[1] === 'Array') {
+        const lit = lowerArrayConstructor(ctor[2])
+        if (lit) return lit
+      }
+      const name = typeof ctor === 'string' ? ctor : (Array.isArray(ctor) && ctor[0] === '()' ? ctor[1] : null)
+      // Preserve `new` for native constructors the compiler resolves under its own
+      // `new` handler (prepare/index.js): typed arrays/Array/RegExp need the `new`
+      // form, and `new URL(rel, import.meta.url)` lowers to a static href string there.
+      // User classes (lowered to factory arrows by jzify) become plain calls below.
+      if (typeof name === 'string' && (TYPED_ARRAYS.has(name) || name === 'Array' || name === 'RegExp' || name === 'URL')) return ['new', transform(ctor), ...cargs.map(transform)]
+      if (Array.isArray(ctor) && ctor[0] === '()') return transform(ctor)
+      return ['()', transform(ctor), ...(cargs.length ? cargs.map(transform) : [null])]
+    },
+
+    'instanceof'(val, ctor) {
+      const t = transform(val)
+      const name = typeof ctor === 'string' ? ctor : (Array.isArray(ctor) && ctor[0] === '()' ? ctor[1] : null)
+      const fold = staticInstanceofFold(val, name)
+      if (fold != null) return [null, fold]
+      if (typeof name === 'string' && ERROR_INSTANCEOF.has(name)) {
+        warn('untagged-instanceof',
+          `\`instanceof ${name}\` does not discriminate thrown values in jz — errors are untagged; inspect the message or value instead`,
+          {}, Array.isArray(val) ? val.loc : null)
+      }
+      if (name === 'Array') return ['()', ['.', 'Array', 'isArray'], t]
+      if (name === 'Map') return ['()', '__is_map', t]
+      if (name === 'Set') return ['()', '__is_set', t]
+      if (typeof name === 'string' && TYPED_ARRAYS.has(name) && name !== 'ArrayBuffer' && name !== 'DataView')
+        return ['()', '__is_typed', t]
+      return ['===', ['typeof', t], [null, 'object']]
+    },
+
+    'do'(body, cond) {
+      const flag = names.doFlag()
+      return [';',
+        ['let', ['=', flag, [null, true]]],
+        ['while', ['||', flag, transform(cond)], ['{}', [';', ['=', flag, [null, false]], transform(body)]]]]
+    },
+
+    // The classic for-head `[';', init, cond, step]` is a fixed 3-slot structure,
+    // NOT a statement sequence. Transform each slot individually and keep null slots
+    // in place. Without this handler, `for` falls to the generic recurse, the head
+    // hits the `;` handler (transformScope), and an empty `init` (null) is dropped as
+    // an empty statement — shifting cond→init/step→cond and miscompiling the loop
+    // (`for (; i < n; i++)` ran zero/garbage iterations). for-of/for-in heads aren't
+    // `;`-lists, so they pass through transform unchanged.
+    'for'(head, body) {
+      if (Array.isArray(head) && head[0] === ';')
+        return ['for', [';', ...head.slice(1).map(s => s == null ? s : transform(s))], transform(body)]
+      return ['for', transform(head), transform(body)]
+    },
+
+    // A bare statement sequence is a block scope too. `parse` only wraps
+    // function/arrow bodies in `{}`; loop/conditional bodies arrive as a raw
+    // `;`. Route them through transformScope so `function` declarations nested
+    // in a loop/if body get hoisted (→ block-top `const f = arrow`) instead of
+    // falling to the discard-IIFE path, which would scope the name inside the
+    // IIFE and leave later `f()` references dangling.
+    ';'(...args) { return transformScope([';', ...args]) },
+
+    '{}'(...args) {
+      const loweredObject = lowerObjectLiteralThis(args)
+      if (loweredObject) return loweredObject
+
+      return ['{}', ...args.map((a, i) => {
+        const t = transformScope(a) ?? a
+        if (i !== 0 || a == null) return t
+        const blockIn = Array.isArray(a) && JZ_BLOCK_OPS.has(a[0])
+        if (!blockIn || t == null) return t
+        return Array.isArray(t) && t[0] === ';' ? t : [';', t]
+      })]
+    },
+
+    'export'(inner) {
+      if (Array.isArray(inner) && inner[0] === 'function' && inner[1]) {
+        return ['export', hoistFnDecl(inner[1], inner[2], inner[3])]
+      }
+      if (Array.isArray(inner) && inner[0] === 'class' && inner[1]) {
+        return ['export', ['let', ['=', inner[1], lowerClass(inner[1], inner[2], inner[3])]]]
+      }
+      if (Array.isArray(inner) && inner[0] === 'default' && Array.isArray(inner[1]) && inner[1][0] === 'function' && inner[1][1]) {
+        // Route a named default-export function through the named-export path: a bare
+        // `const NAME` lifted in a bundled module loses its recursive self-reference
+        // (the default-alias resolver renames the func but not in-body call sites),
+        // so the function is dropped. Exporting NAME as a named binding makes prepare
+        // mangle it and resolve self-calls correctly; alias `default` to it.
+        const decl = hoistFnDecl(inner[1][1], inner[1][2], inner[1][3])
+        return [';', ['export', decl], ['export', ['{}', ['as', inner[1][1], 'default']]]]
+      }
+      if (Array.isArray(inner) && inner[0] === 'default' && Array.isArray(inner[1]) && inner[1][0] === 'class' && inner[1][1]) {
+        return [';', ['let', ['=', inner[1][1], lowerClass(inner[1][1], inner[1][2], inner[1][3])]], ['export', ['default', inner[1][1]]]]
+      }
+      return ['export', transform(inner)]
+    },
+  }
+
+  function transform(node) {
+    if (node == null || typeof node !== 'object' || !Array.isArray(node)) return node
+    const [op, ...args] = node
+    if (op == null) return node
+    const h = handlers[op]
+    return (h && h(...args)) ?? [op, ...args.map(transform)]
+  }
+
+  return { transform, transformScope }
+}

package/layout.js

@@ -0,0 +1,179 @@
+/**
+ * Shared runtime layout: heap, NaN-box carrier, pointer tags.
+ *
+ * Compiler-free — safe for `jz/interop` and tests without pulling the compiler.
+ *
+ * @module layout
+ */
+
+/** Bump-allocator cells in linear memory / globals. */
+export const HEAP = { PTR_ADDR: 1020, START: 1024 }
+
+/** NaN-box bit layout (i64 carrier). */
+export const LAYOUT = {
+  TAG_SHIFT: 47,
+  TAG_MASK: 0xF,
+  AUX_SHIFT: 32,
+  AUX_MASK: 0x7FFF,
+  OFFSET_MASK: 0xFFFFFFFF,
+  NAN_PREFIX: 0x7FF8,
+  NAN_PREFIX_BITS: 0x7FF8000000000000n,
+  SSO_BIT: 0x4000,
+  SLICE_BIT: 0x2000,
+  SLICE_LEN_MASK: 0x1FFF,
+}
+
+/** 4-bit tagged-pointer type codes. */
+export const PTR = {
+  ATOM: 0,
+  ARRAY: 1,
+  BUFFER: 2,
+  TYPED: 3,
+  STRING: 4,
+  OBJECT: 6,
+  HASH: 7,
+  SET: 8,
+  MAP: 9,
+  CLOSURE: 10,
+  EXTERNAL: 11,
+}
+
+/** Reserved atom aux ids (PTR.ATOM). */
+export const ATOM = { NULL: 1, UNDEF: 2, FALSE: 4, TRUE: 5 }
+
+// =============================================================================
+// PTR.TYPED element-type aux codec — which typed-array flavor lives in the aux
+// field of a PTR.TYPED box. Pure (no compiler state) → lives with the NaN-box
+// layout it encodes, shared by the compiler (type/analyze/narrow/infer) and the
+// `module/typedarray` stdlib.
+// =============================================================================
+
+/** Base element-type codes for PTR.TYPED aux (0–7). BigInt ctors share 7 + TYPED_ELEM_BIGINT_FLAG. */
+export const TYPED_ELEM_CODE = {
+  Int8Array: 0, Uint8Array: 1, Int16Array: 2, Uint16Array: 3,
+  Int32Array: 4, Uint32Array: 5, Float32Array: 6, Float64Array: 7,
+  BigInt64Array: 7, BigUint64Array: 7,
+}
+export const TYPED_ELEM_VIEW_FLAG = 8
+export const TYPED_ELEM_BIGINT_FLAG = 16
+
+export const TYPED_ELEM_NAMES = ['Int8Array', 'Uint8Array', 'Int16Array', 'Uint16Array',
+  'Int32Array', 'Uint32Array', 'Float32Array', 'Float64Array']
+
+/** Encode element-type name (+ optional view/bigint flags) to PTR.TYPED aux bits. */
+export function encodeTypedElemAux(name, isView = false) {
+  const et = TYPED_ELEM_CODE[name]
+  if (et == null) return null
+  return et | (isView ? TYPED_ELEM_VIEW_FLAG : 0) |
+    (name === 'BigInt64Array' || name === 'BigUint64Array' ? TYPED_ELEM_BIGINT_FLAG : 0)
+}
+
+/** Encode a `typedElemCtor` string ('new.Int32Array' | 'new.Int32Array.view') to the 4-bit
+ *  aux value used in PTR.TYPED NaN-boxing. Returns null for unknown ctors (ArrayBuffer/DataView). */
+export function typedElemAux(ctor) {
+  if (!ctor || !ctor.startsWith('new.')) return null
+  const isView = ctor.endsWith('.view')
+  const name = isView ? ctor.slice(4, -5) : ctor.slice(4)
+  return encodeTypedElemAux(name, isView)
+}
+
+/** Reverse of typedElemAux: pick a canonical ctor string for a 4-bit elem aux. Used
+ *  to round-trip TYPED-narrowed call results through ctx.types.typedElem so the
+ *  unboxed local's rep picks up the same aux. aux=7 is shared with BigInt typed
+ *  arrays — Float64Array is canonical (read-side compares aux only). */
+export function ctorFromElemAux(aux) {
+  if (aux == null) return null
+  const isView = (aux & 8) !== 0
+  const name = (aux & 16) !== 0 ? 'BigInt64Array' : TYPED_ELEM_NAMES[aux & 7]
+  if (!name) return null
+  return isView ? `new.${name}.view` : `new.${name}`
+}
+
+/** Host-side high u32 word for NaN-boxed f64 pointer encoding (interop). */
+export const encodePtrHi = (type, aux) =>
+  (0x7FF80000 | ((type & 0xF) << 15) | (aux & 0x7FFF)) >>> 0
+
+export const decodePtrType = hi => (hi >>> 15) & 0xF
+export const decodePtrAux = hi => hi & 0x7FFF
+
+/** i64 NaN-prefix OR-mask for WAT `(i64.const …)` templates. */
+export const nanPrefixHex = () =>
+  '0x' + LAYOUT.NAN_PREFIX_BITS.toString(16).toUpperCase().padStart(16, '0')
+
+/** Atom sentinel as i64 hex (compiler WAT templates). */
+export const atomNanHex = atomId =>
+  '0x' + (LAYOUT.NAN_PREFIX_BITS | (BigInt(atomId) << BigInt(LAYOUT.AUX_SHIFT))).toString(16).toUpperCase().padStart(16, '0')
+
+/** STRING aux bit 0 on a PLAIN-HEAP string (SSO and SLICE clear): this is a
+ *  CANONICAL interned string — the static-pool copy (or an intern-table hit
+ *  resolving to it). Two canonicals are bit-equal iff content-equal, so
+ *  __str_eq answers unequal canonicals without touching bytes, and interned
+ *  statics carry a cached FNV hash at offset-8 ([hash u32][len u32][bytes])
+ *  that __str_hash loads instead of re-hashing. Inert elsewhere: slice-length
+ *  bits are only read under SLICE_BIT, SSO length under SSO_BIT, and plain-
+ *  heap consumers read the len header at -4 regardless of aux. */
+export const STR_INTERN_BIT = 0x1
+
+/** Pre-shifted STRING SSO aux bit as i64 hex. */
+export const ssoBitI64Hex = () =>
+  '0x' + (BigInt(LAYOUT.SSO_BIT) << BigInt(LAYOUT.AUX_SHIFT)).toString(16).toUpperCase().padStart(16, '0')
+
+/** Pre-shifted STRING slice/view aux bit as i64 hex. */
+export const sliceBitI64Hex = () =>
+  '0x' + (BigInt(LAYOUT.SLICE_BIT) << BigInt(LAYOUT.AUX_SHIFT)).toString(16).toUpperCase().padStart(16, '0')
+
+/** Full i64 NaN-box hex for `(i64.const …)` — ptr type + aux, offset OR'd separately. */
+export const ptrNanHex = (ptrType, aux = 0) =>
+  '0x' + ptrBoxPrefixBigInt(ptrType, aux).toString(16).toUpperCase().padStart(16, '0')
+
+/** Compile-time i64 prefix for mkPtrIR (before offset OR). */
+export const ptrBoxPrefixBigInt = (ptrType, aux = 0) =>
+  (0x7FF8n << 48n)
+  | ((BigInt(ptrType) & 0xFn) << 47n)
+  | ((BigInt(aux) & 0x7FFFn) << 32n)
+
+/** Host-side atom sentinel high-u32 values (interop f64 decode). */
+export const ATOM_HI = {
+  [ATOM.NULL]: encodePtrHi(PTR.ATOM, ATOM.NULL),
+  [ATOM.UNDEF]: encodePtrHi(PTR.ATOM, ATOM.UNDEF),
+  [ATOM.FALSE]: encodePtrHi(PTR.ATOM, ATOM.FALSE),
+  [ATOM.TRUE]: encodePtrHi(PTR.ATOM, ATOM.TRUE),
+}
+
+/** OOB / canonical quiet-NaN f64 literal for WAT and IR (`nan:0x7FF8…`). */
+export const oobNanLiteral = () => `nan:${nanPrefixHex()}`
+export const oobNanIR = () => ['f64.const', oobNanLiteral()]
+
+/** Heap forwarding-pointer follow (WAT fragment).
+ *  ARRAY/HASH/SET/MAP relocate on growth, leaving the old cell as a forwarding
+ *  header: cap=-1 sentinel at off-4, relocated offset at off-8. `off` is the
+ *  i32 local (token incl. `$`) holding the current offset — mutated in place.
+ *  `lowGuard` adds the `off < 8` bailout; omit it when the caller already
+ *  proved off≥8.
+ *
+ *  Shape: a loop-free in-bounds + sentinel CHECK with a cold call into
+ *  $__ptr_offset_fwd (the actual chase loop, module/core.js) only when the
+ *  first hop is a real forward. Keeping every inline copy loop-free is what
+ *  lets the engine inline the hot heap helpers (__ptr_offset, __len,
+ *  __arr_idx_known, __typed_idx…) — a body containing a loop is excluded from
+ *  V8's wasm inliner, and these helpers sit on ~25% of self-host compile time.
+ *  Callers must list '__ptr_offset_fwd' in their deps()/wat() dependency set. */
+export const followForwardingWat = (off = '$off', { lowGuard = true } = {}) =>
+  `(if (i32.and
+        ${lowGuard ? `(i32.ge_u (local.get ${off}) (i32.const 8))` : '(i32.const 1)'}
+        (i32.le_u (local.get ${off}) (i32.shl (memory.size) (i32.const 16))))
+    (then (if (i32.eq (i32.load (i32.sub (local.get ${off}) (i32.const 4))) (i32.const -1))
+      (then (local.set ${off} (call $__ptr_offset_fwd (local.get ${off})))))))`
+
+/** The cold forwarding-chase loop behind followForwardingWat — the only body
+ *  allowed to loop. Re-checks the sentinel each hop (first re-check is
+ *  redundant with the caller's guard; the cold path doesn't care). */
+export const ptrOffsetFwdWat = () =>
+  `(func $__ptr_offset_fwd (param $off i32) (result i32)
+    (block $done (loop $follow
+      (br_if $done (i32.lt_u (local.get $off) (i32.const 8)))
+      (br_if $done (i32.gt_u (local.get $off) (i32.shl (memory.size) (i32.const 16))))
+      (br_if $done (i32.ne (i32.load (i32.sub (local.get $off) (i32.const 4))) (i32.const -1)))
+      (local.set $off (i32.load (i32.sub (local.get $off) (i32.const 8))))
+      (br $follow)))
+    (local.get $off))`