jz 0.0.0 → 0.1.1

package/src/optimize.js

@@ -0,0 +1,1352 @@
+/**
+ * WASM IR post-emission optimizations.
+ *
+ * # Stage contract
+ *   IN:  WAT-as-array IR (function body or module-level).
+ *   OUT: equivalent WAT-as-array IR (same semantics, smaller encoding).
+ *   INVARIANTS: pure IR→IR rewrite. No ctx reads/writes. No new top-level declarations except
+ *        the ones explicitly surfaced via `addGlobal` (hoistConstantPool only).
+ *
+ * Each pass is orthogonal. Apply order matters: structural hoists (hoistPtrType) introduce
+ * new locals before the fused walk, which mixes peephole rebox folds, ptr-helper inlining,
+ * and memarg-offset folding in one bottom-up traversal.
+ *
+ * Passes:
+ *   hoistPtrType      — repeated `(call $__ptr_type X)` on same X → single local.tee + local.get reuse
+ *   fusedRewrite      — peephole rebox folds + inline ptr/is_* helpers + memarg-offset fold (one walk)
+ *   sortLocalsByUse   — reorder local decls so hot ones get 1-byte LEB128 indices
+ *   specializeMkptr   — `(call $__mkptr (i32.const T) (i32.const A) X)` → per-combo specialized helper (~4 B/site)
+ *   specializePtrBase — `(call $F (i32.add (global.get $G) (i32.const N)))` → `$F_rel_$G (i32.const N)`
+ *   sortStrPoolByFreq — reorder string pool so hottest strings get small offsets (smaller LEB128)
+ *   hoistConstantPool — frequently-repeated f64.const values → mutable globals (~7 B/reuse)
+ *   treeshake         — drop func decls unreachable from exports / start / elem / ref.func roots
+ *
+ * Per-function passes run over sec.funcs + sec.stdlib + sec.start.
+ * Whole-module passes see the full function list + globals map.
+ *
+ * @module optimize
+ */
+
+const MEMOP = /^[fi](32|64)\.(load|store)(\d+(_[su])?)?$/
+const NAN_PREFIX_BITS = 0x7FF8n
+
+/**
+ * Optimization passes, partitioned by phase. The `level` presets pick which
+ * passes are on by default; the user can override individual passes via an
+ * object form (`{ level: 1, hoistAddrBase: true }`).
+ *
+ * Levels:
+ *   0 — nothing. Fastest compile, largest output. Useful for live coding.
+ *   1 — encoding-compactness only (treeshake + sortLocalsByUse + fusedRewrite-inline).
+ *       Cheap, no IR rewrites that perturb V8's tier-up shape.
+ *   2 — default. All current passes (watr CSE/DCE/inline + every jz pass).
+ *   3 — reserved for future aggressive passes (constant-arg propagation,
+ *       inlining, unrolling). Currently == level 2.
+ */
+export const PASS_NAMES = [
+  'watr',                     // third-party WAT-level CSE/DCE/inlining (heaviest)
+  'hoistPtrType',
+  'hoistInvariantPtrOffset',
+  'fusedRewrite',             // peephole + ptr-helper inline + memarg fold
+  'hoistAddrBase',
+  'hoistInvariantCellLoads',
+  'sortLocalsByUse',
+  'specializeMkptr',
+  'specializePtrBase',
+  'sortStrPoolByFreq',
+  'hoistConstantPool',
+  'smallConstForUnroll',
+  'treeshake',
+]
+
+const ALL_ON = Object.freeze(Object.fromEntries(PASS_NAMES.map(n => [n, true])))
+const ALL_OFF = Object.freeze(Object.fromEntries(PASS_NAMES.map(n => [n, false])))
+const LEVEL_PRESETS = Object.freeze({
+  0: ALL_OFF,
+  1: Object.freeze({ ...ALL_OFF, treeshake: true, sortLocalsByUse: true, fusedRewrite: true }),
+  2: ALL_ON,
+  3: ALL_ON,
+})
+
+/**
+ * Normalize the user's `opts.optimize` value into a flat config object.
+ *
+ *   resolveOptimize(undefined | true)         → all on (level 2)
+ *   resolveOptimize(false | 0)                → all off
+ *   resolveOptimize(1 | 2 | 3)                → preset for that level
+ *   resolveOptimize({ level: 1, watr: true }) → level 1 base, with watr forced on
+ *   resolveOptimize({ hoistAddrBase: false }) → level 2 base, hoistAddrBase off
+ */
+export function resolveOptimize(opt) {
+  if (opt === false || opt === 0) return { ...ALL_OFF }
+  if (opt === true || opt == null) return { ...ALL_ON }
+  if (typeof opt === 'number') return { ...(LEVEL_PRESETS[opt] || ALL_ON) }
+  if (typeof opt === 'object') {
+    const baseLevel = typeof opt.level === 'number' ? opt.level : 2
+    const base = LEVEL_PRESETS[baseLevel] || ALL_ON
+    const out = { ...base }
+    for (const n of PASS_NAMES) if (n in opt) out[n] = !!opt[n]
+    return out
+  }
+  return { ...ALL_ON }
+}
+
+/**
+ * CSE repeated `(call $__ptr_type X)` on same X across stable regions.
+ *
+ * A stable region for var X is a maximal CFG segment where X is not written.
+ * Within each region, the first `__ptr_type X` becomes `(local.tee $__ptN ...)`,
+ * subsequent ones become `(local.get $__ptN)`. One hoist local per X is shared
+ * across regions (each region's tee re-initializes it).
+ *
+ * Region boundaries:
+ *   - `local.set` / `local.tee` of X → close region, alive[X] = false
+ *   - `if` arms processed independently from the if-entry alive state; on merge,
+ *     a var is alive after the `if` only if alive in BOTH arms with the same region
+ *     (so the same tee was reachable on every path).
+ *   - `loop` body walks with empty alive (next iteration may re-enter after a write)
+ *   - `block` is sequential (br jumps out, never in)
+ *
+ * Threshold: a region is committed only when it has ≥2 sites. Singleton regions
+ * (one tee with no follow-up gets) are pure cost and skipped.
+ *
+ * Safety: __ptr_type extracts type tag bits, which never change for a given
+ * NaN-boxed f64. Caching is safe inside any region where X isn't rewritten.
+ * (Contrast __ptr_offset, which has a forwarding loop for ARRAY — caching its
+ * result is unsafe across realloc, so it isn't hoisted here.)
+ */
+export function hoistPtrType(fn) {
+  if (!Array.isArray(fn) || fn[0] !== 'func') return
+  const bodyStart = findBodyStart(fn)
+  if (bodyStart < 0) return
+
+  // Per X: array of regions; each region is array of {parent, idx, role: 'tee'|'get'}.
+  const regions = new Map()
+  // Currently-open region per X (X → region array). Presence ⇔ alive.
+  const open = new Map()
+
+  const ensureRegions = (x) => {
+    let arr = regions.get(x)
+    if (!arr) { arr = []; regions.set(x, arr) }
+    return arr
+  }
+
+  const walk = (node, parent, pi) => {
+    if (!Array.isArray(node)) return
+    const op = node[0]
+
+    if (op === 'call' && node[1] === '$__ptr_type' && node.length === 3) {
+      const arg = node[2]
+      if (Array.isArray(arg) && arg[0] === 'local.get' && typeof arg[1] === 'string') {
+        const x = arg[1]
+        let region = open.get(x)
+        if (!region) {
+          region = []
+          ensureRegions(x).push(region)
+          open.set(x, region)
+          region.push({ parent, idx: pi, role: 'tee' })
+        } else {
+          region.push({ parent, idx: pi, role: 'get' })
+        }
+        return  // don't recurse — local.get inside is a read, not interesting
+      }
+      // Non-trivial arg: walk children normally
+      for (let i = 2; i < node.length; i++) walk(node[i], node, i)
+      return
+    }
+
+    if ((op === 'local.set' || op === 'local.tee') && typeof node[1] === 'string') {
+      const x = node[1]
+      // Walk value first — it may contain __ptr_type X, which sees pre-write X.
+      for (let i = 2; i < node.length; i++) walk(node[i], node, i)
+      // Then close any open region for X.
+      open.delete(x)
+      return
+    }
+
+    if (op === 'if') {
+      // Skip optional `(result T)` siblings to find cond / then / else.
+      let i = 1
+      while (i < node.length && Array.isArray(node[i]) && node[i][0] === 'result') i++
+      if (i < node.length) walk(node[i], node, i)  // cond
+      i++
+      let thenArm = null, elseArm = null
+      for (; i < node.length; i++) {
+        const c = node[i]
+        if (Array.isArray(c)) {
+          if (c[0] === 'then') thenArm = c
+          else if (c[0] === 'else') elseArm = c
+        }
+      }
+      const beforeArms = new Map(open)
+      let afterThen = beforeArms
+      if (thenArm) {
+        for (let j = 1; j < thenArm.length; j++) walk(thenArm[j], thenArm, j)
+        afterThen = new Map(open)
+      }
+      open.clear()
+      for (const [k, v] of beforeArms) open.set(k, v)
+      let afterElse = beforeArms
+      if (elseArm) {
+        for (let j = 1; j < elseArm.length; j++) walk(elseArm[j], elseArm, j)
+        afterElse = new Map(open)
+      }
+      // Merge: alive after if iff alive on BOTH paths with same region ref
+      // (so the same tee was reachable regardless of which arm executed).
+      open.clear()
+      for (const [k, vT] of afterThen) {
+        if (afterElse.get(k) === vT) open.set(k, vT)
+      }
+      return
+    }
+
+    if (op === 'loop') {
+      // Conservative: any tee installed in iter N may not have run in iter N+1
+      // before reaching the same site (back-edge to loop header). Clear before+after.
+      open.clear()
+      for (let i = 1; i < node.length; i++) walk(node[i], node, i)
+      open.clear()
+      return
+    }
+
+    // block / func-body / generic: walk children sequentially.
+    for (let i = 0; i < node.length; i++) walk(node[i], node, i)
+  }
+
+  for (let i = bodyStart; i < fn.length; i++) walk(fn[i], fn, i)
+
+  if (regions.size === 0) return
+
+  // Commit: for each X with ≥1 usable region, allocate one shared local and rewrite.
+  // Per-region threshold ≥2 (a singleton would be pure cost).
+  let hoistId = 0
+  const locals = []
+  for (const [, regs] of regions) {
+    let usable = false
+    for (const r of regs) if (r.length >= 2) { usable = true; break }
+    if (!usable) continue
+    const tLocal = `$__pt${hoistId++}`
+    locals.push(['local', tLocal, 'i32'])
+    for (const r of regs) {
+      if (r.length < 2) continue
+      for (let i = 0; i < r.length; i++) {
+        const { parent, idx, role } = r[i]
+        if (role === 'tee') parent[idx] = ['local.tee', tLocal, parent[idx]]
+        else parent[idx] = ['local.get', tLocal]
+      }
+    }
+  }
+  if (locals.length) fn.splice(bodyStart, 0, ...locals)
+}
+
+/**
+ * CSE repeated `(i32.add (local.get $A) (i32.shl (local.get $B) (i32.const K)))`
+ * — the shape jz emits for `arr[idx + k]` typed-array reads after foldMemargOffsets
+ * absorbs the constant K into `offset=`. The remaining base expression is
+ * recomputed once per `arr[…]` read; biquad's inner cascade has 9 such reads
+ * sharing 2 base shapes per iteration. V8's CSE usually catches this, but emitting
+ * the share explicitly avoids relying on tier-up and helps wasm2c / wasm-opt too.
+ *
+ * Same region-tracking discipline as hoistPtrType: open region per key, closed
+ * by re-assignment to either A or B; loop entry/exit clears all open regions.
+ *
+ * Must run AFTER fusedRewrite — relies on shl-distribution + assoc-lift +
+ * foldMemargOffsets having normalized the base shape.
+ */
+export function hoistAddrBase(fn) {
+  if (!Array.isArray(fn) || fn[0] !== 'func') return
+  const bodyStart = findBodyStart(fn)
+  if (bodyStart < 0) return
+
+  // Per key (`$A|$B|K`): array of regions; region: array of {parent, idx, role}.
+  const regions = new Map()
+  // Open regions keyed by string key; also indexed by local name → set of keys
+  // depending on it (so `local.set X` can close any region whose key references X).
+  const open = new Map()
+  const localToKeys = new Map()
+
+  const ensureRegions = (k) => {
+    let arr = regions.get(k)
+    if (!arr) { arr = []; regions.set(k, arr) }
+    return arr
+  }
+  const addLocalDep = (name, key) => {
+    let s = localToKeys.get(name)
+    if (!s) { s = new Set(); localToKeys.set(name, s) }
+    s.add(key)
+  }
+  const closeKey = (key) => {
+    const r = open.get(key)
+    if (!r) return
+    open.delete(key)
+    // Don't bother removing from localToKeys; stale entries are filtered on close.
+  }
+  const closeForLocal = (name) => {
+    const s = localToKeys.get(name)
+    if (!s) return
+    for (const k of s) if (open.has(k)) closeKey(k)
+    localToKeys.delete(name)
+  }
+
+  // Returns { A, B, K } if node matches the pattern, else null.
+  const matchPattern = (node) => {
+    if (!Array.isArray(node) || node[0] !== 'i32.add' || node.length !== 3) return null
+    const a = node[1], b = node[2]
+    // Two orderings: (add (get A) (shl (get B) (const K))) or (add (shl …) (get A))
+    let baseGet, shlNode
+    if (Array.isArray(a) && a[0] === 'local.get' && typeof a[1] === 'string' &&
+        Array.isArray(b) && b[0] === 'i32.shl' && b.length === 3) {
+      baseGet = a; shlNode = b
+    } else if (Array.isArray(b) && b[0] === 'local.get' && typeof b[1] === 'string' &&
+               Array.isArray(a) && a[0] === 'i32.shl' && a.length === 3) {
+      baseGet = b; shlNode = a
+    } else return null
+    const idx = shlNode[1], shamt = shlNode[2]
+    if (!Array.isArray(idx) || idx[0] !== 'local.get' || typeof idx[1] !== 'string') return null
+    if (!Array.isArray(shamt) || shamt[0] !== 'i32.const' || typeof shamt[1] !== 'number') return null
+    return { A: baseGet[1], B: idx[1], K: shamt[1] }
+  }
+
+  const walk = (node, parent, pi) => {
+    if (!Array.isArray(node)) return
+    const op = node[0]
+
+    const m = matchPattern(node)
+    if (m) {
+      const key = `${m.A}|${m.B}|${m.K}`
+      let region = open.get(key)
+      if (!region) {
+        region = []
+        ensureRegions(key).push(region)
+        open.set(key, region)
+        addLocalDep(m.A, key)
+        addLocalDep(m.B, key)
+        region.push({ parent, idx: pi, role: 'tee' })
+      } else {
+        region.push({ parent, idx: pi, role: 'get' })
+      }
+      return  // children are local.gets — they're reads, not interesting
+    }
+
+    if ((op === 'local.set' || op === 'local.tee') && typeof node[1] === 'string') {
+      const x = node[1]
+      // Walk value first — it may match patterns referencing pre-write X.
+      for (let i = 2; i < node.length; i++) walk(node[i], node, i)
+      closeForLocal(x)
+      return
+    }
+
+    if (op === 'if') {
+      let i = 1
+      while (i < node.length && Array.isArray(node[i]) && node[i][0] === 'result') i++
+      if (i < node.length) walk(node[i], node, i)
+      i++
+      let thenArm = null, elseArm = null
+      for (; i < node.length; i++) {
+        const c = node[i]
+        if (Array.isArray(c)) {
+          if (c[0] === 'then') thenArm = c
+          else if (c[0] === 'else') elseArm = c
+        }
+      }
+      const beforeArms = new Map(open)
+      let afterThen = beforeArms
+      if (thenArm) {
+        for (let j = 1; j < thenArm.length; j++) walk(thenArm[j], thenArm, j)
+        afterThen = new Map(open)
+      }
+      open.clear()
+      for (const [k, v] of beforeArms) open.set(k, v)
+      let afterElse = beforeArms
+      if (elseArm) {
+        for (let j = 1; j < elseArm.length; j++) walk(elseArm[j], elseArm, j)
+        afterElse = new Map(open)
+      }
+      open.clear()
+      for (const [k, vT] of afterThen) {
+        if (afterElse.get(k) === vT) open.set(k, vT)
+      }
+      return
+    }
+
+    if (op === 'loop') {
+      open.clear()
+      for (let i = 1; i < node.length; i++) walk(node[i], node, i)
+      open.clear()
+      return
+    }
+
+    for (let i = 0; i < node.length; i++) walk(node[i], node, i)
+  }
+
+  for (let i = bodyStart; i < fn.length; i++) walk(fn[i], fn, i)
+
+  if (regions.size === 0) return
+
+  let hoistId = 0
+  const locals = []
+  // Find next free $__abN id by scanning existing locals.
+  while (fn.some(n => Array.isArray(n) && n[0] === 'local' && n[1] === `$__ab${hoistId}`)) hoistId++
+  for (const [, regs] of regions) {
+    let usable = false
+    for (const r of regs) if (r.length >= 2) { usable = true; break }
+    if (!usable) continue
+    const tLocal = `$__ab${hoistId++}`
+    locals.push(['local', tLocal, 'i32'])
+    for (const r of regs) {
+      if (r.length < 2) continue
+      for (let i = 0; i < r.length; i++) {
+        const { parent, idx, role } = r[i]
+        if (role === 'tee') parent[idx] = ['local.tee', tLocal, parent[idx]]
+        else parent[idx] = ['local.get', tLocal]
+      }
+    }
+  }
+  if (locals.length) fn.splice(bodyStart, 0, ...locals)
+}
+
+/**
+ * Hoist `(call $__ptr_offset (local.get $X))` to a function-entry snapshot
+ * when X is an f64-NaN-boxed parameter that's never reassigned and only ever
+ * passed to known-pure helpers. Aos-style hot loops read `rows[i]` once per
+ * iteration; without this, V8 keeps re-extracting the offset each time.
+ *
+ * Safety: __ptr_offset on an Array follows the realloc-forwarding chain. Once
+ * a function commits to "this param won't realloc inside me", caching is
+ * sound for the duration. The whitelist below is the read-only set
+ * (no mutation possible); any other callee touching X invalidates hoisting.
+ */
+const SAFE_OFFSET_CALLS = new Set(['$__ptr_offset', '$__ptr_type', '$__ptr_aux', '$__len'])
+
+export function hoistInvariantPtrOffset(fn) {
+  if (!Array.isArray(fn) || fn[0] !== 'func') return
+  const bodyStart = findBodyStart(fn)
+  if (bodyStart < 0) return
+
+  const params = new Set()
+  for (let i = 2; i < fn.length; i++) {
+    const c = fn[i]
+    if (!Array.isArray(c)) continue
+    if (c[0] !== 'param') continue
+    if (typeof c[1] === 'string' && c[2] === 'f64') params.add(c[1])
+  }
+  if (!params.size) return
+
+  const sites = new Map()
+  const unsafe = new Set()
+
+  const walk = (node, parent, pi) => {
+    if (!Array.isArray(node)) return
+    const op = node[0]
+
+    if (op === 'local.set' || op === 'local.tee') {
+      if (typeof node[1] === 'string' && params.has(node[1])) unsafe.add(node[1])
+      for (let i = 2; i < node.length; i++) walk(node[i], node, i)
+      return
+    }
+
+    if (op === 'call') {
+      const callee = node[1]
+      if (callee === '$__ptr_offset' && node.length === 3) {
+        const a = node[2]
+        if (Array.isArray(a) && a[0] === 'local.get' && typeof a[1] === 'string' && params.has(a[1])) {
+          let arr = sites.get(a[1])
+          if (!arr) { arr = []; sites.set(a[1], arr) }
+          arr.push({ parent, idx: pi })
+          return
+        }
+      }
+      const isSafe = SAFE_OFFSET_CALLS.has(callee)
+      for (let i = 2; i < node.length; i++) {
+        const arg = node[i]
+        if (Array.isArray(arg) && arg[0] === 'local.get' && typeof arg[1] === 'string' && params.has(arg[1])) {
+          if (!isSafe) unsafe.add(arg[1])
+          continue
+        }
+        walk(arg, node, i)
+      }
+      return
+    }
+
+    if (op === 'call_indirect' || op === 'call_ref') {
+      for (let i = 1; i < node.length; i++) {
+        const arg = node[i]
+        if (Array.isArray(arg) && arg[0] === 'local.get' && typeof arg[1] === 'string' && params.has(arg[1])) {
+          unsafe.add(arg[1])
+          continue
+        }
+        walk(arg, node, i)
+      }
+      return
+    }
+
+    for (let i = 0; i < node.length; i++) walk(node[i], node, i)
+  }
+
+  for (let i = bodyStart; i < fn.length; i++) walk(fn[i], fn, i)
+
+  if (sites.size === 0) return
+
+  let hoistId = 0
+  while (fn.some(n => Array.isArray(n) && n[0] === 'local' && n[1] === `$__po${hoistId}`)) hoistId++
+
+  const newLocals = []
+  const snaps = []
+  for (const [X, arr] of sites) {
+    if (unsafe.has(X)) continue
+    if (arr.length < 2) continue
+    const tLocal = `$__po${hoistId++}`
+    newLocals.push(['local', tLocal, 'i32'])
+    snaps.push(['local.set', tLocal, ['call', '$__ptr_offset', ['local.get', X]]])
+    for (const { parent, idx } of arr) {
+      parent[idx] = ['local.get', tLocal]
+    }
+  }
+
+  if (newLocals.length) fn.splice(bodyStart, 0, ...newLocals, ...snaps)
+}
+
+/**
+ * Hoist loop-invariant boxed-cell reads out of loops.
+ *
+ * Boxed-capture cells (`$cell_X`, allocated by the closure-capture pass) are
+ * private to the enclosing function — no other code path can write to that
+ * memory. So if a loop body contains `(f64.load (local.get $cell_X))` reads
+ * and *no* `(f64.store (local.get $cell_X) …)` writes, the load is loop-
+ * invariant and can be hoisted to a snapshot local set just before the loop.
+ *
+ * Necessary because V8's wasm tier doesn't perform LICM across f64.load:
+ * memory may alias with f64.stores in the loop body, and even though we
+ * know the cell can't alias with array stores, the engine has to assume it
+ * can. Hand-hoisting unblocks register-keeping of the captured value.
+ *
+ * Inside-out per-loop processing — inner loops handled first, so reads
+ * already replaced by snap-locals don't appear as cell reads at outer levels.
+ */
+export function hoistInvariantCellLoads(fn) {
+  if (!Array.isArray(fn) || fn[0] !== 'func') return
+  const bodyStart = findBodyStart(fn)
+  if (bodyStart < 0) return
+
+  let snapId = 0
+  while (fn.some(n => Array.isArray(n) && n[0] === 'local' && n[1] === `$__sc${snapId}`)) snapId++
+  const newLocals = []
+
+  // Build refcount of array nodes: how many positions in `fn` reference each
+  // array. Earlier passes (fusedRewrite, hoistAddrBase) introduce shared
+  // subtrees; mutating `parent[idx]` for a shared parent would also affect
+  // references outside the current loop. Sites whose immediate parent has
+  // refcount > 1 are skipped.
+  const refcount = new Map()
+  const countRefs = (node) => {
+    if (!Array.isArray(node)) return
+    const n = (refcount.get(node) || 0) + 1
+    refcount.set(node, n)
+    if (n > 1) return  // already counted children below
+    for (let i = 0; i < node.length; i++) countRefs(node[i])
+  }
+  countRefs(fn)
+
+  // Process one loop node: find cell_X reads, check no writes, hoist.
+  // Returns { snapDecls } — list of (local.set $snap (f64.load (local.get $cell_X))) IR
+  // to emit before the loop in its parent.
+  const processLoop = (loopNode) => {
+    // Recurse first — inner loops handled bottom-up. Each inner-loop processor
+    // returns a list of pre-loop snap decls; we splice them just before the inner
+    // loop within this loop's body.
+    for (let i = 1; i < loopNode.length; i++) {
+      const child = loopNode[i]
+      if (!Array.isArray(child)) continue
+      processNode(child, loopNode, i)
+    }
+
+    // Scan this loop's body for cell reads & writes (excluding nested loop bodies,
+    // since their reads were already hoisted at their level).
+    const reads = new Map()  // cellName → array of {parent, idx}
+    const writes = new Set()
+    let hasCall = false
+    const scanWrites = (node) => {
+      if (!Array.isArray(node)) return
+      const op = node[0]
+      if (op === 'call' || op === 'call_ref' || op === 'call_indirect') {
+        hasCall = true
+      }
+      // DESCEND into nested loops here — we need to know if any nested-loop
+      // body writes to cell_X (which would invalidate hoisting THIS loop's reads).
+      if (op === 'f64.store' && node.length >= 3) {
+        const addr = node[1]
+        if (Array.isArray(addr) && addr[0] === 'local.get' && typeof addr[1] === 'string'
+            && addr[1].startsWith('$cell_')) {
+          writes.add(addr[1])
+        }
+        // Continue scan into value expr
+        for (let i = 2; i < node.length; i++) scanWrites(node[i])
+        return
+      }
+      if (op === 'f64.load' && node.length === 2) {
+        const addr = node[1]
+        if (Array.isArray(addr) && addr[0] === 'local.get' && typeof addr[1] === 'string'
+            && addr[1].startsWith('$cell_')) {
+          // Defer; we'll handle in a parent-tracking second pass.
+        }
+      }
+      for (let i = 1; i < node.length; i++) scanWrites(node[i])
+    }
+    for (let i = 1; i < loopNode.length; i++) scanWrites(loopNode[i])
+    // Sound bailout: a call inside the loop could mutate a captured cell
+    // via a closure we can't see. Without escape analysis we can't prove
+    // non-aliasing, so we skip hoisting from any loop containing calls.
+    if (hasCall) return []
+
+    // Parent-tracking pass to collect read sites.
+    const collect = (node, parent, idx) => {
+      if (!Array.isArray(node)) return
+      const op = node[0]
+      if (op === 'loop') return
+      if (op === 'f64.load' && node.length === 2) {
+        const addr = node[1]
+        if (Array.isArray(addr) && addr[0] === 'local.get' && typeof addr[1] === 'string'
+            && addr[1].startsWith('$cell_')) {
+          const cell = addr[1]
+          // Skip if the f64.load node or its immediate parent is shared
+          // (refcount>1): mutating parent[idx] would propagate the rewrite to
+          // references outside this loop.
+          if (!writes.has(cell)
+              && (refcount.get(node) || 0) <= 1
+              && (refcount.get(parent) || 0) <= 1) {
+            let arr = reads.get(cell)
+            if (!arr) { arr = []; reads.set(cell, arr) }
+            arr.push({ parent, idx })
+          }
+          return
+        }
+      }
+      for (let i = 0; i < node.length; i++) collect(node[i], node, i)
+    }
+    for (let i = 1; i < loopNode.length; i++) collect(loopNode[i], loopNode, i)
+
+    // For each cell with reads but no writes (and confirmed no calls above),
+    // hoist a snap. Single-read hoist is fine semantically: the cell address
+    // doesn't change once allocated, and snap is loaded unconditionally before
+    // the loop, then the body uses the snap local.
+    const snaps = []
+    for (const [cell, sites] of reads) {
+      if (sites.length < 1) continue
+      const snapName = `$__sc${snapId++}`
+      newLocals.push(['local', snapName, 'f64'])
+      snaps.push(['local.set', snapName, ['f64.load', ['local.get', cell]]])
+      for (const { parent, idx } of sites) {
+        parent[idx] = ['local.get', snapName]
+      }
+    }
+    return snaps
+  }
+
+  // Recursive node walker that splices snap decls before nested loops.
+  const processNode = (node, parent, idx) => {
+    if (!Array.isArray(node)) return
+    const op = node[0]
+    if (op === 'loop') {
+      const snaps = processLoop(node)
+      if (snaps.length) {
+        // Splice snaps just before this loop in its parent. The parent could be
+        // a `block` or a top-level func body or any other container.
+        parent.splice(idx, 0, ...snaps)
+      }
+      return
+    }
+    for (let i = 0; i < node.length; i++) processNode(node[i], node, i)
+  }
+
+  for (let i = bodyStart; i < fn.length; i++) {
+    processNode(fn[i], fn, i)
+  }
+
+  if (newLocals.length) fn.splice(bodyStart, 0, ...newLocals)
+}
+
+/**
+ * Find the index of the first body-content child in a func node.
+ * Skips `$name`, (export …), (import …), (type …), (param …), (result …), (local …).
+ */
+function findBodyStart(fn) {
+  for (let i = 2; i < fn.length; i++) {
+    const c = fn[i]
+    if (!Array.isArray(c)) continue
+    if (c[0] === 'export' || c[0] === 'import' || c[0] === 'type' || c[0] === 'param' || c[0] === 'result' || c[0] === 'local') continue
+    return i
+  }
+  return fn.length
+}
+
+/**
+ * Hoist frequently-repeated f64 constants into mutable globals.
+ * f64.const is 9 bytes; global.get with idx<128 is 2 bytes — saves 7 B per reuse.
+ * Pool entries sorted by usage descending, so hottest get lowest indices (1-byte LEB128).
+ * Break-even: N ≥ 2 uses (pool cost: 11 B global decl + 2N bytes vs 9N original).
+ *
+ * Mutates `funcs` in place; writes new global decls via `addGlobal(name, watString)`.
+ */
+export function hoistConstantPool(funcs, addGlobal) {
+  const MIN_USES = 2
+  // Single walk: count occurrences AND record each f64.const site for direct rewrite.
+  // Avoids a second full-AST traversal in the rewrite phase.
+  const counts = new Map()
+  const sites = []  // { parent, idx, key }
+  const walk = (node) => {
+    if (!Array.isArray(node)) return
+    for (let i = 0; i < node.length; i++) {
+      const c = node[i]
+      if (Array.isArray(c) && c[0] === 'f64.const' && (typeof c[1] === 'number' || typeof c[1] === 'string')) {
+        const k = typeof c[1] === 'number' ? `n:${c[1]}` : `s:${c[1]}`
+        counts.set(k, (counts.get(k) || 0) + 1)
+        sites.push({ parent: node, idx: i, key: k })
+      }
+      walk(c)
+    }
+  }
+  for (let i = 0; i < funcs.length; i++) walk(funcs[i])
+
+  const hoist = new Map()
+  const sorted = [...counts].filter(([, n]) => n >= MIN_USES).sort((a, b) => b[1] - a[1])
+  let gId = 0
+  for (const [k] of sorted) {
+    const name = `__fc${gId++}`
+    const lit = k.slice(2)
+    addGlobal(name, `(global $${name} (mut f64) (f64.const ${lit}))`)
+    hoist.set(k, name)
+  }
+  if (!hoist.size) return
+
+  // Rewrite recorded sites directly. Idempotent: if parent[idx] is no longer the
+  // f64.const we recorded (shared subtrees), skip.
+  for (let i = 0; i < sites.length; i++) {
+    const { parent, idx, key } = sites[i]
+    const g = hoist.get(key)
+    if (!g) continue
+    const c = parent[idx]
+    if (!Array.isArray(c) || c[0] !== 'f64.const') continue
+    parent[idx] = ['global.get', `$${g}`]
+  }
+}
+
+/**
+ * Specialize `(call $F arg1 arg2 …)` call sites by literal-arg signature.
+ *
+ * For each call target with a stable (param-types, result-type) signature,
+ * scan all call sites and group by "literal-arg signature" (which args are
+ * `i32.const N` literals vs runtime-dynamic). For groups with ≥ MIN_USES, emit
+ * a specialized trampoline `$F_L1_L2_…` that bakes literals into the call:
+ *
+ *   (func $F_L1_L2 (param $a2 T2) (result R)
+ *     (call $F (i32.const L1) (local.get $a2)))
+ *
+ * Call sites are rewritten `(call $F (i32.const L1) a2)` → `(call $F_L1_L2 a2)`.
+ * Savings per site: ~2 B per dropped literal arg.
+ *
+ * For `$__mkptr`, every combo has type+aux literal so we special-case the body:
+ * fold the prefix into `(i64.const TEMPLATE)` instead of a trampoline call —
+ * avoids a runtime indirection for the hottest path.
+ *
+ * @param funcs    — flat list of func IR nodes (sec.funcs + sec.stdlib + sec.start)
+ * @param addFunc  — callback `(watString) => void` to register new helpers
+ * @param parseWat — `wat → IR` parser (injected to avoid circular imports)
+ */
+export function specializeMkptr(funcs, addFunc, parseWat) {
+  // Per-target specification: param-types, result-type. Threshold tuned so helper cost amortizes.
+  // Any target not listed here is left untouched. Order matters only for readability.
+  const SPECS = {
+    '$__mkptr':     { params: ['i32', 'i32', 'i32'], result: 'f64', inline: true },
+    '$__alloc_hdr': { params: ['i32', 'i32', 'i32'], result: 'i32' },
+    '$__typed_idx': { params: ['f64', 'i32'],        result: 'f64' },
+    '$__str_idx':   { params: ['f64', 'i32'],        result: 'f64' },
+  }
+  const MIN_USES = 5
+
+  // Build literal-arg signature key for a call node. Returns null if no args are literal.
+  // Key format: 'T:V' per literal arg, 'D' per dynamic; indexed by position.
+  const sigKey = (call, nParams) => {
+    const key = []
+    let anyLit = false
+    for (let i = 0; i < nParams; i++) {
+      const a = call[2 + i]
+      if (Array.isArray(a) && a[0] === 'i32.const' && typeof a[1] === 'number') { key.push('L:' + a[1]); anyLit = true }
+      else key.push('D')
+    }
+    return anyLit ? key.join('|') : null
+  }
+
+  // Pass 1: count per (target, sig) AND record candidate site locations for direct
+  // rewrite in pass 3. Pre-order push means nested candidates appear later in `sites`,
+  // so reverse iteration in pass 3 yields leaf-first rewrite order (inner before outer).
+  const counts = new Map()  // 'target##sig' → count
+  const sites = []  // { parent, idx, fullKey, parts }
+  const walk = (node, parent, idx) => {
+    if (!Array.isArray(node)) return
+    if (parent && node[0] === 'call' && typeof node[1] === 'string' && SPECS[node[1]]) {
+      const spec = SPECS[node[1]]
+      if (node.length === 2 + spec.params.length) {
+        const k = sigKey(node, spec.params.length)
+        if (k) {
+          const fullKey = node[1] + '##' + k
+          counts.set(fullKey, (counts.get(fullKey) || 0) + 1)
+          sites.push({ parent, idx, fullKey, parts: k.split('|') })
+        }
+      }
+    }
+    for (let i = 0; i < node.length; i++) walk(node[i], node, i)
+  }
+  for (let i = 0; i < funcs.length; i++) walk(funcs[i], null, 0)
+
+  // Pass 2: for each eligible (target, sig), emit helper.
+  const specialized = new Set()
+  for (const [k, n] of counts) if (n >= MIN_USES) specialized.add(k)
+  if (!specialized.size) return
+
+  const variantName = (target, sigParts) => target.slice(1) + '_' + sigParts
+    .map(p => p === 'D' ? 'd' : p.slice(2)).join('_')
+
+  for (const fullKey of specialized) {
+    const [target, sig] = fullKey.split('##')
+    const parts = sig.split('|')
+    const spec = SPECS[target]
+    const name = variantName(target, parts)
+
+    // $__mkptr inline fast path: bake (type, aux) literals into i64.const template.
+    if (target === '$__mkptr' && spec.inline && parts[0].startsWith('L:') && parts[1].startsWith('L:')) {
+      const type = +parts[0].slice(2), aux = +parts[1].slice(2)
+      const tmpl = (NAN_PREFIX_BITS << 48n)
+        | ((BigInt(type) & 0xFn) << 47n)
+        | ((BigInt(aux) & 0x7FFFn) << 32n)
+      // Third arg (offset) may also be literal — emit (f64.const nan:…) then.
+      if (parts[2].startsWith('L:')) {
+        // Fully literal: all sites can be f64.const — no helper needed, handled in rewrite below.
+        continue
+      }
+      addFunc(`(func $${name} (param $o i32) (result f64)
+        (f64.reinterpret_i64 (i64.or (i64.const 0x${tmpl.toString(16).toUpperCase()}) (i64.extend_i32_u (local.get $o)))))`)
+      continue
+    }
+
+    // Generic trampoline: (func $F_LITS (param …dyn) (result R) (call $F lits+dyn))
+    const dynArgs = []
+    const callArgs = []
+    for (let i = 0; i < parts.length; i++) {
+      if (parts[i].startsWith('L:')) {
+        callArgs.push(`(i32.const ${parts[i].slice(2)})`)
+      } else {
+        dynArgs.push(`(param $a${i} ${spec.params[i]})`)
+        callArgs.push(`(local.get $a${i})`)
+      }
+    }
+    addFunc(`(func $${name} ${dynArgs.join(' ')} (result ${spec.result}) (call ${target} ${callArgs.join(' ')}))`)
+  }
+
+  // Pass 3: rewrite recorded sites in reverse (leaf-first since pass 1 was pre-order).
+  // Iterating the captured site list avoids a second full-AST walk.
+  // Idempotency guard: shared subtrees in the IR cause the same (parent, idx) to be
+  // recorded as multiple sites. The first visit rewrites; subsequent visits see the
+  // rewritten call (target no longer in SPECS) and skip — same behavior as the
+  // recursive rewrite this replaces.
+  for (let i = sites.length - 1; i >= 0; i--) {
+    const { parent, idx, fullKey, parts } = sites[i]
+    if (!specialized.has(fullKey)) continue
+    const c = parent[idx]
+    const target = c[1]
+    const spec = SPECS[target]
+    if (!spec || c.length !== 2 + spec.params.length) continue
+
+    // $__mkptr fully literal (rare — mkPtrIR usually folds these ahead of us, but defensive):
+    if (target === '$__mkptr' && parts[0].startsWith('L:') && parts[1].startsWith('L:') && parts[2].startsWith('L:')) {
+      const type = +parts[0].slice(2), aux = +parts[1].slice(2), off = +parts[2].slice(2)
+      const bits = (NAN_PREFIX_BITS << 48n)
+        | ((BigInt(type) & 0xFn) << 47n)
+        | ((BigInt(aux) & 0x7FFFn) << 32n)
+        | (BigInt(off >>> 0) & 0xFFFFFFFFn)
+      const n = ['f64.const', 'nan:0x' + bits.toString(16).toUpperCase().padStart(16, '0')]
+      n.type = 'f64'
+      parent[idx] = n
+      continue
+    }
+
+    const name = variantName(target, parts)
+    const dynArgs = []
+    for (let j = 0; j < parts.length; j++) if (parts[j] === 'D') dynArgs.push(c[2 + j])
+    const newCall = ['call', '$' + name, ...dynArgs]
+    newCall.type = spec.result
+    parent[idx] = newCall
+  }
+}
+
+/**
+ * Specialize `(call $F (i32.add (global.get $G) (i32.const N)))` → `(call $F_rel_$G (i32.const N))`.
+ * Helper bakes `(global.get $G) + i32.add` into its body so call sites drop those 3 B.
+ * Targets any single-arg call whose arg is `add(global_base, const)` — in practice: $__mkptr_X_Y_d
+ * specializations against $__strBase (watr self-host: ~2193 sites × 3 B ≈ 6.5 KB).
+ *
+ * @param funcs    — flat list of func IR nodes
+ * @param addFunc  — callback `(watString) => void` to register new helpers
+ * @param parseWat — `wat → IR` parser (injected)
+ */
+export function specializePtrBase(funcs, addFunc, parseWat) {
+  const MIN_USES = 20
+
+  // Pass 1: count (targetFunc, baseGlobal) pairs AND record candidate sites for direct
+  // rewrite in pass 3 (avoids a second full-AST walk).
+  const counts = new Map()  // 'F##G' → count
+  const sites = []  // { parent, idx, key }
+  const walk = (node, parent, idx) => {
+    if (!Array.isArray(node)) return
+    if (parent && node[0] === 'call' && typeof node[1] === 'string' && node.length === 3) {
+      const arg = node[2]
+      if (Array.isArray(arg) && arg[0] === 'i32.add' && arg.length === 3 &&
+          Array.isArray(arg[1]) && arg[1][0] === 'global.get' && typeof arg[1][1] === 'string' &&
+          Array.isArray(arg[2]) && arg[2][0] === 'i32.const') {
+        const k = node[1] + '##' + arg[1][1]
+        counts.set(k, (counts.get(k) || 0) + 1)
+        sites.push({ parent, idx, key: k })
+      }
+    }
+    for (let i = 0; i < node.length; i++) walk(node[i], node, i)
+  }
+  for (let i = 0; i < funcs.length; i++) walk(funcs[i], null, 0)
+
+  const specialized = new Set()
+  for (const [k, n] of counts) if (n >= MIN_USES) specialized.add(k)
+  if (!specialized.size) return
+
+  // Find a target func's result-type by locating its decl among `funcs`.
+  const funcByName = new Map()
+  for (let i = 0; i < funcs.length; i++) {
+    const fn = funcs[i]
+    if (Array.isArray(fn) && fn[0] === 'func' && typeof fn[1] === 'string') funcByName.set(fn[1], fn)
+  }
+  const resultOf = (name) => {
+    const fn = funcByName.get(name)
+    if (!fn) return 'f64'  // defensive; mkptr specializations all return f64
+    for (let i = 2; i < fn.length; i++) {
+      const c = fn[i]
+      if (Array.isArray(c) && c[0] === 'result') return c[1]
+      if (Array.isArray(c) && c[0] !== 'param') break
+    }
+    return 'f64'
+  }
+
+  const sanit = (g) => g.replace(/^\$/, '').replace(/[^a-zA-Z0-9_]/g, '_')
+  const variantFor = (F, G) => `${F}_rel_${sanit(G)}`
+
+  // Pass 2: emit helpers.
+  for (const fullKey of specialized) {
+    const [F, G] = fullKey.split('##')
+    const rt = resultOf(F)
+    const name = variantFor(F, G)
+    addFunc(`(func ${name} (param $o i32) (result ${rt}) (call ${F} (i32.add (global.get ${G}) (local.get $o))))`)
+  }
+
+  // Pass 3: rewrite recorded sites in reverse (leaf-first since pass 1 was pre-order).
+  // Idempotency guard: shared IR subtrees can record the same (parent, idx) twice.
+  // The first visit rewrites to a 2-arg call; subsequent visits see a shape that
+  // doesn't match the original `call F (i32.add (global.get) (i32.const))` pattern.
+  for (let i = sites.length - 1; i >= 0; i--) {
+    const { parent, idx, key } = sites[i]
+    if (!specialized.has(key)) continue
+    const c = parent[idx]
+    if (!Array.isArray(c) || c[0] !== 'call' || c.length !== 3) continue
+    const arg = c[2]
+    if (!Array.isArray(arg) || arg[0] !== 'i32.add' || arg.length !== 3) continue
+    if (!Array.isArray(arg[1]) || arg[1][0] !== 'global.get') continue
+    if (!Array.isArray(arg[2]) || arg[2][0] !== 'i32.const') continue
+    const F = c[1]
+    const G = arg[1][1]
+    const konst = arg[2]
+    const newCall = ['call', variantFor(F, G), konst]
+    newCall.type = resultOf(F)
+    parent[idx] = newCall
+  }
+}
+
+/**
+ * Reorder strings in `strPool` so most-referenced strings get low byte offsets.
+ * Each string ref is encoded as `(i32.const off)` with ULEB128: 1 B for off<128, 2 B for off<16384, 3 B for off<2M.
+ * Frequent strings migrating from 3-B to 2-B (or 2-B to 1-B) LEB128 saves ~541 B on watr self-host.
+ *
+ * Pool layout: `[4-byte-len][data-bytes][4-byte-len][data-bytes]...`. Offsets in refs point PAST the len prefix.
+ *
+ * @param funcs        — flat list of func IR nodes (scanned for refs)
+ * @param strPoolRef   — `{ pool: string }` holder; pool is rewritten in place
+ * @param strDedupMap  — optional `Map<string, offset>` to update (kept consistent for later queries)
+ */
+export function sortStrPoolByFreq(funcs, strPoolRef, strDedupMap) {
+  if (!strPoolRef.pool) return
+  // Match both specialized and unspecialized strBase refs.
+  const isSpecRef = (n) =>
+    Array.isArray(n) && n[0] === 'call' && typeof n[1] === 'string' && n[1].includes('_rel___strBase') &&
+    n.length === 3 && Array.isArray(n[2]) && n[2][0] === 'i32.const'
+  const isUnspecRef = (n) =>
+    Array.isArray(n) && n[0] === 'call' && typeof n[1] === 'string' && n[1].startsWith('$__mkptr_') &&
+    n.length === 3 && Array.isArray(n[2]) && n[2][0] === 'i32.add' && n[2].length === 3 &&
+    Array.isArray(n[2][1]) && n[2][1][0] === 'global.get' && n[2][1][1] === '$__strBase' &&
+    Array.isArray(n[2][2]) && n[2][2][0] === 'i32.const'
+  const getOff = (n) => isSpecRef(n) ? (n[2][1] | 0) : isUnspecRef(n) ? (n[2][2][1] | 0) : null
+  const setOff = (n, v) => { if (isSpecRef(n)) n[2][1] = v; else if (isUnspecRef(n)) n[2][2][1] = v }
+
+  // Single walk: count freq AND record each ref site for direct rewrite.
+  const freq = new Map()
+  const sites = []  // { node, oldOff } — node is the ref node, mutate offset in place
+  const walk = (n) => {
+    if (!Array.isArray(n)) return
+    const o = getOff(n)
+    if (o !== null) { freq.set(o, (freq.get(o) || 0) + 1); sites.push({ node: n, oldOff: o }) }
+    for (let i = 0; i < n.length; i++) walk(n[i])
+  }
+  for (let i = 0; i < funcs.length; i++) walk(funcs[i])
+  if (!freq.size) return
+
+  // Parse pool structure into entries.
+  const pool = strPoolRef.pool
+  const entries = []
+  let i = 0
+  while (i < pool.length) {
+    const len = pool.charCodeAt(i) | (pool.charCodeAt(i+1) << 8) | (pool.charCodeAt(i+2) << 16) | (pool.charCodeAt(i+3) << 24)
+    const oldOff = i + 4
+    entries.push({ oldOff, len, str: pool.substring(oldOff, oldOff + len) })
+    i = oldOff + len
+  }
+
+  // Sort by freq descending; tie-break by length ascending (pack short hot strings into low-offset range).
+  entries.sort((a, b) => (freq.get(b.oldOff) || 0) - (freq.get(a.oldOff) || 0) || a.len - b.len)
+
+  // Rebuild pool; map old → new offsets.
+  const remap = new Map()
+  let newPool = ''
+  for (const e of entries) {
+    newPool += String.fromCharCode(e.len & 0xFF, (e.len >> 8) & 0xFF, (e.len >> 16) & 0xFF, (e.len >> 24) & 0xFF)
+    remap.set(e.oldOff, newPool.length)
+    newPool += e.str
+  }
+  strPoolRef.pool = newPool
+  if (strDedupMap)
+    for (const [str, oldOff] of strDedupMap) {
+      const newOff = remap.get(oldOff)
+      if (newOff !== undefined) strDedupMap.set(str, newOff)
+    }
+
+  // Rewrite recorded ref sites directly (no second AST walk).
+  for (let i = 0; i < sites.length; i++) {
+    const { node, oldOff } = sites[i]
+    const newO = remap.get(oldOff)
+    if (newO !== undefined) setOff(node, newO)
+  }
+}
+
+/**
+ * Run all per-function IR optimizations on a single function node.
+ * hoistPtrType runs first — it introduces new locals (`$__ptN`) that the fused
+ * walk should see in their final form. fusedRewrite then collapses rebox/unbox
+ * round-trips, inlines tiny ptr/is_* helpers, and folds (i32.add base const)
+ * into memarg offset= form, all in a single bottom-up traversal — and
+ * piggybacks local-ref counting so sortLocalsByUse skips its own walk.
+ *
+ * @param fn  func IR node
+ * @param cfg optional resolved config from resolveOptimize() — when omitted, all on.
+ */
+export function optimizeFunc(fn, cfg) {
+  if (cfg && cfg.hoistPtrType === false &&
+      cfg.hoistInvariantPtrOffset === false &&
+      cfg.fusedRewrite === false &&
+      cfg.hoistAddrBase === false &&
+      cfg.hoistInvariantCellLoads === false &&
+      cfg.sortLocalsByUse === false) return
+  if (!cfg || cfg.hoistPtrType !== false) hoistPtrType(fn)
+  if (!cfg || cfg.hoistInvariantPtrOffset !== false) hoistInvariantPtrOffset(fn)
+  const counts = new Map()
+  if (!cfg || cfg.fusedRewrite !== false) fusedRewrite(fn, counts)
+  if (!cfg || cfg.hoistAddrBase !== false) hoistAddrBase(fn)
+  if (!cfg || cfg.hoistInvariantCellLoads !== false) hoistInvariantCellLoads(fn)
+  if (!cfg || cfg.sortLocalsByUse !== false) sortLocalsByUse(fn, cfg && cfg.fusedRewrite !== false ? counts : null)
+}
+
+// Fused bottom-up walk applying three orthogonal pattern sets at each node:
+//   inlinePtrType  — call $__ptr_type / __ptr_aux / __is_nullish / __is_null / __is_truthy
+//                    (skipped inside $__ptr_*/__is_* helper bodies themselves)
+//   peephole       — rebox/unbox round-trips: i64.reinterpret_f64 / f64.reinterpret_i64 /
+//                    i32.wrap_i64 over (i64.extend_i32_u/_s X) or (i64.or HIGH_ONLY extend X)
+//   foldMemarg     — (load/store (i32.add base (i32.const N)) …) → (load/store offset=N base …)
+// They discriminate on node[0] and don't overlap, so one visit suffices for all three.
+function fusedRewrite(fn, counts) {
+  if (!Array.isArray(fn) || fn[0] !== 'func') {
+    if (Array.isArray(fn)) {
+      for (let i = 0; i < fn.length; i++) {
+        const c = fn[i]
+        if (Array.isArray(c)) fn[i] = walkRewrite(c, true, counts)
+      }
+    }
+    return
+  }
+  // Skip __ptr_*/is_* bodies for inline pattern (they ARE the helpers).
+  const name = typeof fn[1] === 'string' ? fn[1] : null
+  const skipInline = !!(name && (name.startsWith('$__ptr_') || name === '$__is_nullish' || name === '$__is_truthy' || name === '$__is_null'))
+  const bodyStart = findBodyStart(fn)
+  for (let i = bodyStart; i < fn.length; i++) {
+    const c = fn[i]
+    if (Array.isArray(c)) fn[i] = walkRewrite(c, !skipInline, counts)
+  }
+}
+
+function walkRewrite(node, doInline, counts) {
+  if (!Array.isArray(node)) return node
+  for (let i = 0; i < node.length; i++) {
+    const c = node[i]
+    if (Array.isArray(c)) node[i] = walkRewrite(c, doInline, counts)
+  }
+  const op = node[0]
+  // Piggyback local-ref counting for sortLocalsByUse. `counts` may be undefined
+  // when fusedRewrite is called outside optimizeFunc (whole-module pass).
+  if (counts && (op === 'local.get' || op === 'local.set' || op === 'local.tee') && typeof node[1] === 'string')
+    counts.set(node[1], (counts.get(node[1]) || 0) + 1)
+
+  // Inline-ptr-helpers: $__ptr_type / $__ptr_aux / $__is_nullish / $__is_null / $__is_truthy
+  if (doInline && op === 'call' && node.length === 3 && typeof node[1] === 'string') {
+    const fname = node[1]
+    if (fname === '$__ptr_type') return ['i32.and',
+      ['i32.wrap_i64', ['i64.shr_u', ['i64.reinterpret_f64', node[2]], ['i64.const', 47]]],
+      ['i32.const', 0xF]]
+    if (fname === '$__ptr_aux') return ['i32.and',
+      ['i32.wrap_i64', ['i64.shr_u', ['i64.reinterpret_f64', node[2]], ['i64.const', 32]]],
+      ['i32.const', 0x7FFF]]
+    if (fname === '$__is_null') return ['i64.eq', ['i64.reinterpret_f64', node[2]], ['i64.const', '0x7FF8000100000000']]
+    if (fname === '$__is_nullish' && Array.isArray(node[2]) && node[2][0] === 'local.get') return ['i32.or',
+      ['i64.eq', ['i64.reinterpret_f64', node[2]], ['i64.const', '0x7FF8000100000000']],
+      ['i64.eq', ['i64.reinterpret_f64', node[2]], ['i64.const', '0x7FF8000000000001']]]
+    if (fname === '$__is_truthy' && Array.isArray(node[2]) && node[2][0] === 'local.get') {
+      const lget = node[2]
+      const bits = ['i64.reinterpret_f64', lget]
+      return ['if', ['result', 'i32'],
+        ['f64.eq', lget, lget],
+        ['then', ['f64.ne', lget, ['f64.const', 0]]],
+        ['else', ['i32.and',
+          ['i32.and',
+            ['i64.ne', bits, ['i64.const', '0x7FF8000000000000']],
+            ['i64.ne', bits, ['i64.const', '0x7FF8000100000000']]],
+          ['i32.and',
+            ['i64.ne', bits, ['i64.const', '0x7FF8000000000001']],
+            ['i64.ne', bits, ['i64.const', '0x7FFA800000000000']]]]]]
+    }
+  }
+
+  // Peephole: rebox/unbox round-trips
+  if (op === 'i64.reinterpret_f64' && node.length === 2) {
+    const a = node[1]
+    if (Array.isArray(a) && a[0] === 'f64.reinterpret_i64' && a.length === 2) return a[1]
+  }
+  if (op === 'f64.reinterpret_i64' && node.length === 2) {
+    const a = node[1]
+    if (Array.isArray(a) && a[0] === 'i64.reinterpret_f64' && a.length === 2) return a[1]
+  }
+  if (op === 'i32.wrap_i64' && node.length === 2) {
+    const a = node[1]
+    if (Array.isArray(a) && (a[0] === 'i64.extend_i32_u' || a[0] === 'i64.extend_i32_s') && a.length === 2)
+      return a[1]
+    // (i32.wrap_i64 (i64.reinterpret_f64 (f64.load ADDR ?offset))) → (i32.load ADDR ?offset).
+    // Wasm is little-endian; the low 32 bits of the f64 at ADDR are exactly
+    // i32.load(ADDR). Saves two ops on every NaN-box pointer extraction from
+    // an array slot or struct field.
+    if (Array.isArray(a) && a[0] === 'i64.reinterpret_f64' && a.length === 2) {
+      const inner = a[1]
+      if (Array.isArray(inner) && inner[0] === 'f64.load') {
+        const out = ['i32.load']
+        for (let i = 1; i < inner.length; i++) out.push(inner[i])
+        return out
+      }
+    }
+    if (Array.isArray(a) && a[0] === 'i64.or' && a.length === 3) {
+      const l = a[1], r = a[2]
+      const isHighOnly = (n) => {
+        if (!Array.isArray(n) || n[0] !== 'i64.const') return false
+        const v = n[1]
+        let bi
+        if (typeof v === 'number') bi = BigInt(v)
+        else if (typeof v === 'string') {
+          try { bi = v.startsWith('-') ? -BigInt(v.slice(1)) : BigInt(v) } catch { return false }
+        } else return false
+        return (bi & 0xFFFFFFFFn) === 0n
+      }
+      const isExtend = (n) => Array.isArray(n) && (n[0] === 'i64.extend_i32_u' || n[0] === 'i64.extend_i32_s') && n.length === 2
+      if (isHighOnly(l) && isExtend(r)) return r[1]
+      if (isHighOnly(r) && isExtend(l)) return l[1]
+    }
+  }
+
+  // shl-distribute-over-add: (i32.shl (i32.add x (i32.const K)) (i32.const S))
+  // → (i32.add (i32.shl x S) (i32.const K<<S)). Overflow-safe — both forms wrap
+  // mod 2^32 identically. Unlocks memarg offset= folding for biquad-style
+  // `arr[c+K0..KN]` reads where idx is precomputed but K is a small literal.
+  if (op === 'i32.shl' && node.length === 3) {
+    const a = node[1], b = node[2]
+    // shl-shl-merge: (i32.shl (i32.shl x K1) K2) → (i32.shl x (K1+K2))
+    // when K1+K2 < 32. Biquad: `sb = s<<2` then `__ab1 = state + (sb<<3)` ⇒
+    // `s<<5` directly.
+    if (Array.isArray(a) && a[0] === 'i32.shl' && a.length === 3 &&
+        Array.isArray(b) && b[0] === 'i32.const' && typeof b[1] === 'number' &&
+        Array.isArray(a[2]) && a[2][0] === 'i32.const' && typeof a[2][1] === 'number') {
+      const sum = a[2][1] + b[1]
+      if (sum >= 0 && sum < 32) return ['i32.shl', a[1], ['i32.const', sum]]
+    }
+    if (Array.isArray(a) && a[0] === 'i32.add' && a.length === 3 &&
+        Array.isArray(b) && b[0] === 'i32.const' && typeof b[1] === 'number' && b[1] >= 0 && b[1] < 32) {
+      const ka = a[1], kb = a[2]
+      let inner, k
+      if (Array.isArray(kb) && kb[0] === 'i32.const' && typeof kb[1] === 'number') { inner = ka; k = kb[1] }
+      else if (Array.isArray(ka) && ka[0] === 'i32.const' && typeof ka[1] === 'number') { inner = kb; k = ka[1] }
+      if (inner != null) {
+        const shifted = (k * (1 << b[1])) | 0
+        return ['i32.add', ['i32.shl', inner, b], ['i32.const', shifted]]
+      }
+    }
+  }
+
+  // assoc-lift-const-add: (i32.add A (i32.add B (i32.const K))) → (i32.add (i32.add A B) (i32.const K))
+  // and mirror for left side. Lifts constant to top level so foldMemargOffsets
+  // recognizes the canonical (i32.add base const) shape.
+  if (op === 'i32.add' && node.length === 3) {
+    const a = node[1], b = node[2]
+    if (Array.isArray(b) && b[0] === 'i32.add' && b.length === 3) {
+      const bb1 = b[1], bb2 = b[2]
+      if (Array.isArray(bb2) && bb2[0] === 'i32.const') return ['i32.add', ['i32.add', a, bb1], bb2]
+      if (Array.isArray(bb1) && bb1[0] === 'i32.const') return ['i32.add', ['i32.add', a, bb2], bb1]
+    }
+    if (Array.isArray(a) && a[0] === 'i32.add' && a.length === 3) {
+      const aa1 = a[1], aa2 = a[2]
+      if (Array.isArray(aa2) && aa2[0] === 'i32.const') return ['i32.add', ['i32.add', aa1, b], aa2]
+      if (Array.isArray(aa1) && aa1[0] === 'i32.const') return ['i32.add', ['i32.add', aa2, b], aa1]
+    }
+  }
+
+  // foldMemargOffsets: (load/store (i32.add base const) ...) → (load/store offset=N base ...)
+  if (typeof op === 'string' && MEMOP.test(op)) {
+    const m1 = node[1]
+    if (!(typeof m1 === 'string' && (m1.startsWith('offset=') || m1.startsWith('align=')))) {
+      const addr = m1
+      if (Array.isArray(addr) && addr[0] === 'i32.add' && addr.length === 3) {
+        const a = addr[1], b = addr[2]
+        let base, offset
+        if (Array.isArray(b) && b[0] === 'i32.const' && typeof b[1] === 'number' && b[1] >= 0 && b[1] < 0x100000000) { base = a; offset = b[1] }
+        else if (Array.isArray(a) && a[0] === 'i32.const' && typeof a[1] === 'number' && a[1] >= 0 && a[1] < 0x100000000) { base = b; offset = a[1] }
+        if (base != null) {
+          node[1] = `offset=${offset}`
+          node.splice(2, 0, base)
+        }
+      }
+    }
+  }
+  return node
+}
+
+/**
+ * Dead-code elimination: remove func decls not reachable from any entry point.
+ * Roots: `(start $X)`, `(export "n" (func $X))`, `(elem … $X …)`, `(ref.func $X)`.
+ * Iteratively adds funcs called from reachable ones. Mutates arrays in place.
+ * Typical win: watr's optimize.js has orphan top-level consts (e.g. `hoist` = 26 KB).
+ *
+ * @param funcSections — array of { arr, isStartContainer? }. Each `arr` holds func IR nodes
+ *                       (may be interleaved with other nodes like `(start $X)` for sec.start).
+ * @param allModuleNodes — flat iterable of all module-level nodes for root discovery
+ *                          (exports, elem, start directive are elsewhere than funcSections).
+ * @param opts — optional `{ removeDead: bool }`. When `removeDead` is false, the
+ *               reachability walk still runs (so `callCount` is populated for the
+ *               funcidx sort downstream) but unreachable funcs are kept. Default true.
+ */
+export function treeshake(funcSections, allModuleNodes, opts) {
+  const removeDead = !opts || opts.removeDead !== false
+  const funcByName = new Map()
+  const allFuncs = []
+  for (const { arr } of funcSections)
+    for (const n of arr)
+      if (Array.isArray(n) && n[0] === 'func') {
+        allFuncs.push(n)
+        if (typeof n[1] === 'string') funcByName.set(n[1], n)
+      }
+
+  const reachable = new Set()
+  const stack = []
+  const addRoot = (name) => { if (funcByName.has(name) && !reachable.has(name)) { reachable.add(name); stack.push(name) } }
+
+  // Named funcs with inline `(export "name")` are module-export roots.
+  for (const [name, fn] of funcByName)
+    for (let i = 2; i < fn.length; i++)
+      if (Array.isArray(fn[i]) && fn[i][0] === 'export') { addRoot(name); break }
+
+  const findRoots = (node) => {
+    if (!Array.isArray(node)) return
+    if (node[0] === 'start' && typeof node[1] === 'string') addRoot(node[1])
+    else if (node[0] === 'export' && Array.isArray(node[2]) && node[2][0] === 'func') addRoot(node[2][1])
+    else if (node[0] === 'elem') for (const c of node) if (typeof c === 'string' && c.startsWith('$')) addRoot(c)
+    for (const c of node) findRoots(c)
+  }
+  for (const n of allModuleNodes) findRoots(n)
+
+  // Side-output: per-callee call counts over all reachable + anonymous funcs.
+  // Caller uses this to sort funcs by hotness for low-LEB128-funcidx packing.
+  // Counting here is free — we already visit every node in these funcs.
+  const callCount = new Map()
+  const CALL_OPS = new Set(['call', 'return_call', 'ref.func'])
+  const visitCalls = (node) => {
+    if (!Array.isArray(node)) return
+    if (CALL_OPS.has(node[0]) && typeof node[1] === 'string') {
+      addRoot(node[1])
+      if (node[0] === 'call' || node[0] === 'return_call')
+        callCount.set(node[1], (callCount.get(node[1]) || 0) + 1)
+    }
+    for (const c of node) visitCalls(c)
+  }
+  // Anonymous funcs can't be pruned (no name) — walk them to seed roots.
+  for (const fn of allFuncs) if (typeof fn[1] !== 'string') visitCalls(fn)
+  while (stack.length) visitCalls(funcByName.get(stack.pop()))
+
+  let removed = 0
+  if (removeDead) {
+    for (const { arr } of funcSections) {
+      for (let i = arr.length - 1; i >= 0; i--) {
+        const n = arr[i]
+        if (Array.isArray(n) && n[0] === 'func' && typeof n[1] === 'string' && !reachable.has(n[1])) {
+          arr.splice(i, 1); removed++
+        }
+      }
+    }
+  }
+  return { removed, callCount }
+}
+
+/**
+ * Reorder non-param local decls by reference count (hot locals first).
+ * WASM `local.get/set/tee` encode local idx as ULEB128 — 1 B for idx < 128, else 2 B.
+ * Only the decl order changes; refs by name are unchanged and re-resolved by watr.
+ * Params are fixed (their slot defines the call ABI) — only `(local …)` nodes move.
+ */
+export function sortLocalsByUse(fn, precomputedCounts) {
+  if (!Array.isArray(fn) || fn[0] !== 'func') return
+  const localIdxs = []
+  let totalDecls = 0
+  for (let i = 2; i < fn.length; i++) {
+    const c = fn[i]
+    if (!Array.isArray(c)) continue
+    if (c[0] === 'param' || c[0] === 'result') { totalDecls++; continue }
+    if (c[0] === 'local') { localIdxs.push(i); totalDecls++; continue }
+    break
+  }
+  if (localIdxs.length < 2 || totalDecls <= 128) return
+  let counts = precomputedCounts
+  if (!counts) {
+    counts = new Map()
+    const visit = (n) => {
+      if (!Array.isArray(n)) return
+      if ((n[0] === 'local.get' || n[0] === 'local.set' || n[0] === 'local.tee') && typeof n[1] === 'string')
+        counts.set(n[1], (counts.get(n[1]) || 0) + 1)
+      for (const c of n) visit(c)
+    }
+    for (let i = totalDecls + 2; i < fn.length; i++) visit(fn[i])
+  }
+  const locals = localIdxs.map(i => fn[i])
+  locals.sort((a, b) => (counts.get(b[1]) || 0) - (counts.get(a[1]) || 0))
+  localIdxs.forEach((i, k) => { fn[i] = locals[k] })
+}