@vectojs/core 1.16.2 → 1.17.0

package/dist/index.mjs

@@ -468,7 +468,158 @@ function buildTreeStore(root) {
   return { store, indexOf };
 }
 
+// src/wasm/hit-store.ts
+function gatherHitAABBs(root, currentFrame) {
+  const slotEntity = [];
+  const boundless = [];
+  const minxs = [];
+  const minys = [];
+  const maxxs = [];
+  const maxys = [];
+  const scratch = { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 };
+  const visit = (node) => {
+    const index = slotEntity.length;
+    slotEntity.push(node);
+    const bounds = node.getBounds();
+    if (bounds === null) {
+      boundless.push({ entity: node, index });
+      minxs.push(0);
+      minys.push(0);
+      maxxs.push(0);
+      maxys.push(0);
+    } else {
+      if (!node._readWorldCache(currentFrame, scratch)) {
+        const t = node.getWorldTransform();
+        scratch.a = t.a;
+        scratch.b = t.b;
+        scratch.c = t.c;
+        scratch.d = t.d;
+        scratch.e = t.e;
+        scratch.f = t.f;
+      }
+      const { a, b, c, d, e, f } = scratch;
+      let minX = Infinity;
+      let minY = Infinity;
+      let maxX = -Infinity;
+      let maxY = -Infinity;
+      for (let i = 0; i < 4; i++) {
+        const lx = i & 1 ? bounds.x + bounds.width : bounds.x;
+        const ly = i & 2 ? bounds.y + bounds.height : bounds.y;
+        const wx = a * lx + c * ly + e;
+        const wy = b * lx + d * ly + f;
+        if (wx < minX) minX = wx;
+        if (wx > maxX) maxX = wx;
+        if (wy < minY) minY = wy;
+        if (wy > maxY) maxY = wy;
+      }
+      minxs.push(minX);
+      minys.push(minY);
+      maxxs.push(maxX);
+      maxys.push(maxY);
+    }
+    const kids = node.children;
+    for (let i = 0; i < kids.length; i++) visit(kids[i]);
+  };
+  visit(root);
+  return {
+    count: slotEntity.length,
+    slotEntity,
+    boundless,
+    minx: Float64Array.from(minxs),
+    miny: Float64Array.from(minys),
+    maxx: Float64Array.from(maxxs),
+    maxy: Float64Array.from(maxys)
+  };
+}
+
+// src/wasm/hit-store-fused.ts
+function gatherHitAABBsFromStore(root, aabbs, storeSlotEntity, out) {
+  const slotEntity = out.slotEntity;
+  const boundless = out.boundless;
+  slotEntity.length = 0;
+  boundless.length = 0;
+  let count = 0;
+  let capacity = out.minx.length;
+  let minx = out.minx;
+  let miny = out.miny;
+  let maxx = out.maxx;
+  let maxy = out.maxy;
+  const grow = (needed) => {
+    if (needed <= capacity) return;
+    let next = capacity || 256;
+    while (next < needed) next *= 2;
+    const nminx = new Float64Array(next);
+    const nminy = new Float64Array(next);
+    const nmaxx = new Float64Array(next);
+    const nmaxy = new Float64Array(next);
+    nminx.set(minx);
+    nminy.set(miny);
+    nmaxx.set(maxx);
+    nmaxy.set(maxy);
+    minx = nminx;
+    miny = nminy;
+    maxx = nmaxx;
+    maxy = nmaxy;
+    capacity = next;
+  };
+  let bailed = false;
+  const visit = (node) => {
+    if (bailed) return;
+    const index = count;
+    slotEntity.push(node);
+    count++;
+    grow(count);
+    if (node.getBounds() === null) {
+      boundless.push({ entity: node, index });
+      minx[index] = 0;
+      miny[index] = 0;
+      maxx[index] = 0;
+      maxy[index] = 0;
+    } else {
+      const slot = node._storeSlot;
+      if (slot < 0 || slot >= aabbs.aminx.length || storeSlotEntity[slot] !== node) {
+        bailed = true;
+        return;
+      }
+      minx[index] = aabbs.aminx[slot];
+      miny[index] = aabbs.aminy[slot];
+      maxx[index] = aabbs.amaxx[slot];
+      maxy[index] = aabbs.amaxy[slot];
+    }
+    const children = node.children;
+    for (let i = 0; i < children.length; i++) visit(children[i]);
+  };
+  visit(root);
+  if (bailed) return null;
+  out.count = count;
+  out.minx = minx;
+  out.miny = miny;
+  out.maxx = maxx;
+  out.maxy = maxy;
+  return out;
+}
+function createHitGatherBuffer() {
+  return {
+    count: 0,
+    slotEntity: [],
+    boundless: [],
+    minx: new Float64Array(256),
+    miny: new Float64Array(256),
+    maxx: new Float64Array(256),
+    maxy: new Float64Array(256)
+  };
+}
+
 // src/wasm/backend.ts
+var WASM_STATUS = {
+  OK: 0,
+  /** A count exceeded what `init` allocated. */
+  CAPACITY: 1,
+  /** A kernel ran before `init`. */
+  UNINITIALIZED: 2,
+  /** A sibling run addressed a slot or parent outside the store. */
+  BAD_RUN: 3
+};
 var PAD2 = 8;
 var WasmTransformBackend = class {
   available = true;
@@ -520,9 +671,13 @@ var WasmTransformBackend = class {
     this.vrp.set(store.runParent.subarray(0, rc));
     this.vrs.set(store.runStart.subarray(0, rc));
     this.vrl.set(store.runLen.subarray(0, rc));
-    this.ex.set_run_count(rc);
-    if (kernel === "scalar") this.ex.compose_scalar();
-    else this.ex.compose_simd();
+    if (this.ex.set_run_count(rc) !== WASM_STATUS.OK) {
+      this.lastStatus = WASM_STATUS.CAPACITY;
+      return;
+    }
+    const status = kernel === "scalar" ? this.ex.compose_scalar() : this.ex.compose_simd();
+    this.lastStatus = status;
+    if (status !== WASM_STATUS.OK) return;
     store.wa.set(this.vwa.subarray(0, n));
     store.wb.set(this.vwb.subarray(0, n));
     store.wc.set(this.vwc.subarray(0, n));
@@ -542,8 +697,9 @@ var WasmTransformBackend = class {
    * {@link uploadRuns} after a topology change.
    */
   runKernel(kernel = "simd") {
-    if (kernel === "scalar") this.ex.compose_scalar();
-    else this.ex.compose_simd();
+    const status = kernel === "scalar" ? this.ex.compose_scalar() : this.ex.compose_simd();
+    this.lastStatus = status;
+    return status;
   }
   /** Upload only the run table + count (topology), leaving per-entity inputs to
    *  the resident views. Call when the tree structure changes, not per frame. */
@@ -553,8 +709,13 @@ var WasmTransformBackend = class {
     this.vrp.set(store.runParent.subarray(0, rc));
     this.vrs.set(store.runStart.subarray(0, rc));
     this.vrl.set(store.runLen.subarray(0, rc));
-    this.ex.set_run_count(rc);
+    this.lastStatus = this.ex.set_run_count(rc);
   }
+  /**
+   * Status of the most recent kernel or run-table call. `WASM_STATUS.OK` unless
+   * the crate rejected its arguments, in which case that call was a no-op.
+   */
+  lastStatus = WASM_STATUS.OK;
   /** The resident wasm input views (`x,y,sx,sy,cos,sin,opacity`), valid until
    *  the next capacity growth. Writing here is what makes uploads unnecessary. */
   inputView() {
@@ -622,6 +783,22 @@ var WasmTransformBackend = class {
       amaxy: this.vamaxy
     };
   }
+  /**
+   * Re-create the typed-array views if the memory buffer they were built over has
+   * been detached.
+   *
+   * Necessary because all backends of a Scene now share one instance, and
+   * therefore one linear memory: another backend's allocation (notably
+   * `hit_init`, which allocates its own grid arrays) can grow the memory and
+   * detach every view built over the old buffer. A detached `Float64Array` reads
+   * as length 0 and silently returns `undefined` for every index, so without this
+   * the transform store appears empty rather than failing loudly.
+   */
+  revalidateViews() {
+    if (this.cap === 0) return;
+    if (this.vwa.length === this.cap && this.vwa.buffer === this.ex.memory.buffer) return;
+    this.refreshViews();
+  }
   ensure(count, runCount) {
     if (count + PAD2 <= this.cap && runCount <= this.runCap) return;
     this.cap = count + PAD2;
@@ -664,100 +841,75 @@ var WasmTransformBackend = class {
     this.vrl = i32(this.ex.p_run_len());
   }
 };
-async function instantiateAsync(bytes) {
-  try {
-    const { instance } = await WebAssembly.instantiate(bytes, {});
-    return new WasmTransformBackend(instance);
-  } catch {
-    return null;
+
+// src/wasm/anim-backend.ts
+var PAD3 = 8;
+var AnimBackend = class {
+  ex;
+  springCap = 0;
+  tweenCap = 0;
+  sv;
+  tv;
+  constructor(instance) {
+    this.ex = instance.exports;
   }
-}
-async function instantiateStreaming(source) {
-  try {
-    const resp = typeof source === "string" || source instanceof URL ? await fetch(String(source)) : await source;
-    if (typeof WebAssembly.instantiateStreaming === "function") {
-      const buffered = resp.clone();
-      try {
-        const { instance: instance2 } = await WebAssembly.instantiateStreaming(resp, {});
-        return new WasmTransformBackend(instance2);
-      } catch {
-        const { instance: instance2 } = await WebAssembly.instantiate(await buffered.arrayBuffer(), {});
-        return new WasmTransformBackend(instance2);
-      }
-    }
-    const { instance } = await WebAssembly.instantiate(await resp.arrayBuffer(), {});
-    return new WasmTransformBackend(instance);
-  } catch {
-    return null;
+  /** The resident spring SoA input/output views, valid until the next capacity
+   *  growth. Write gathered driver state here before calling {@link stepSprings}. */
+  springView() {
+    return this.sv;
   }
-}
-
-// src/wasm/hit-store.ts
-function gatherHitAABBs(root, currentFrame) {
-  const slotEntity = [];
-  const boundless = [];
-  const minxs = [];
-  const minys = [];
-  const maxxs = [];
-  const maxys = [];
-  const scratch = { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 };
-  const visit = (node) => {
-    const index = slotEntity.length;
-    slotEntity.push(node);
-    const bounds = node.getBounds();
-    if (bounds === null) {
-      boundless.push({ entity: node, index });
-      minxs.push(0);
-      minys.push(0);
-      maxxs.push(0);
-      maxys.push(0);
-    } else {
-      if (!node._readWorldCache(currentFrame, scratch)) {
-        const t = node.getWorldTransform();
-        scratch.a = t.a;
-        scratch.b = t.b;
-        scratch.c = t.c;
-        scratch.d = t.d;
-        scratch.e = t.e;
-        scratch.f = t.f;
-      }
-      const { a, b, c, d, e, f } = scratch;
-      let minX = Infinity;
-      let minY = Infinity;
-      let maxX = -Infinity;
-      let maxY = -Infinity;
-      for (let i = 0; i < 4; i++) {
-        const lx = i & 1 ? bounds.x + bounds.width : bounds.x;
-        const ly = i & 2 ? bounds.y + bounds.height : bounds.y;
-        const wx = a * lx + c * ly + e;
-        const wy = b * lx + d * ly + f;
-        if (wx < minX) minX = wx;
-        if (wx > maxX) maxX = wx;
-        if (wy < minY) minY = wy;
-        if (wy > maxY) maxY = wy;
-      }
-      minxs.push(minX);
-      minys.push(minY);
-      maxxs.push(maxX);
-      maxys.push(maxY);
-    }
-    const kids = node.children;
-    for (let i = 0; i < kids.length; i++) visit(kids[i]);
-  };
-  visit(root);
-  return {
-    count: slotEntity.length,
-    slotEntity,
-    boundless,
-    minx: Float64Array.from(minxs),
-    miny: Float64Array.from(minys),
-    maxx: Float64Array.from(maxxs),
-    maxy: Float64Array.from(maxys)
-  };
-}
+  /** The resident tween SoA input/output views, valid until the next capacity
+   *  growth. Write gathered driver state here before calling {@link stepTweens}. */
+  tweenView() {
+    return this.tv;
+  }
+  /**
+   * Size (and grow, if needed) capacity for `springCount` springs and
+   * `tweenCount` tweens. Call this BEFORE writing into {@link springView}/
+   * {@link tweenView} — a capacity growth detaches the previous views, so
+   * writing first and sizing after would write into a stale buffer.
+   */
+  ensure(springCount, tweenCount) {
+    if (springCount + PAD3 <= this.springCap && tweenCount + PAD3 <= this.tweenCap) return;
+    this.springCap = springCount + PAD3;
+    this.tweenCap = tweenCount + PAD3;
+    this.ex.anim_init(this.springCap, this.tweenCap);
+    this.refreshViews();
+  }
+  /** Advance `count` springs (from index 0) by `dtMs` milliseconds, in place. */
+  stepSprings(dtMs, count) {
+    this.ex.spring_step(dtMs / 1e3, count);
+  }
+  /** Advance `count` tweens (from index 0) by `dtMs` milliseconds, writing `val`. */
+  stepTweens(dtMs, count) {
+    this.ex.tween_step(dtMs, count);
+  }
+  refreshViews() {
+    const buf = this.ex.memory.buffer;
+    const sCap = this.springCap;
+    const tCap = this.tweenCap;
+    this.sv = {
+      val: new Float64Array(buf, this.ex.p_s_val(), sCap),
+      target: new Float64Array(buf, this.ex.p_s_target(), sCap),
+      vel: new Float64Array(buf, this.ex.p_s_vel(), sCap),
+      stiff: new Float64Array(buf, this.ex.p_s_stiff(), sCap),
+      damp: new Float64Array(buf, this.ex.p_s_damp(), sCap),
+      mass: new Float64Array(buf, this.ex.p_s_mass(), sCap)
+    };
+    this.tv = {
+      from: new Float64Array(buf, this.ex.p_t_from(), tCap),
+      to: new Float64Array(buf, this.ex.p_t_to(), tCap),
+      elapsed: new Float64Array(buf, this.ex.p_t_elapsed(), tCap),
+      dur: new Float64Array(buf, this.ex.p_t_dur(), tCap),
+      delay: new Float64Array(buf, this.ex.p_t_delay(), tCap),
+      ease: new Float64Array(buf, this.ex.p_t_ease(), tCap),
+      val: new Float64Array(buf, this.ex.p_t_val(), tCap)
+    };
+  }
+};
 
 // src/wasm/hit-backend.ts
-var PAD3 = 8;
+var PAD4 = 8;
 var CELLS_PER_ENTITY_HINT = 4;
 var HitTestBackend = class {
   ex;
@@ -829,10 +981,10 @@ var HitTestBackend = class {
     return this.vItems.subarray(start, start + count);
   }
   growIfNeeded(count, cellCount, itemCount) {
-    if (count + PAD3 <= this.entityCap && cellCount <= this.cellCap && itemCount <= this.itemCap) {
+    if (count + PAD4 <= this.entityCap && cellCount <= this.cellCap && itemCount <= this.itemCap) {
       return;
     }
-    this.entityCap = count + PAD3;
+    this.entityCap = count + PAD4;
     this.cellCap = Math.max(cellCount, 1);
     this.itemCap = Math.max(itemCount, count, 1);
     this.ex.hit_init(count, this.cellCap, this.itemCap);
@@ -854,126 +1006,6 @@ var HitTestBackend = class {
     this.vItems = new Int32Array(buf, this.ex.p_h_items(), iCap);
   }
 };
-async function instantiateAsync2(bytes) {
-  try {
-    const { instance } = await WebAssembly.instantiate(bytes, {});
-    return new HitTestBackend(instance);
-  } catch {
-    return null;
-  }
-}
-async function instantiateStreaming2(source) {
-  try {
-    const resp = typeof source === "string" || source instanceof URL ? await fetch(String(source)) : await source;
-    if (typeof WebAssembly.instantiateStreaming === "function") {
-      const buffered = resp.clone();
-      try {
-        const { instance: instance2 } = await WebAssembly.instantiateStreaming(resp, {});
-        return new HitTestBackend(instance2);
-      } catch {
-        const { instance: instance2 } = await WebAssembly.instantiate(await buffered.arrayBuffer(), {});
-        return new HitTestBackend(instance2);
-      }
-    }
-    const { instance } = await WebAssembly.instantiate(await resp.arrayBuffer(), {});
-    return new HitTestBackend(instance);
-  } catch {
-    return null;
-  }
-}
-
-// src/wasm/anim-backend.ts
-var PAD4 = 8;
-var AnimBackend = class {
-  ex;
-  springCap = 0;
-  tweenCap = 0;
-  sv;
-  tv;
-  constructor(instance) {
-    this.ex = instance.exports;
-  }
-  /** The resident spring SoA input/output views, valid until the next capacity
-   *  growth. Write gathered driver state here before calling {@link stepSprings}. */
-  springView() {
-    return this.sv;
-  }
-  /** The resident tween SoA input/output views, valid until the next capacity
-   *  growth. Write gathered driver state here before calling {@link stepTweens}. */
-  tweenView() {
-    return this.tv;
-  }
-  /**
-   * Size (and grow, if needed) capacity for `springCount` springs and
-   * `tweenCount` tweens. Call this BEFORE writing into {@link springView}/
-   * {@link tweenView} — a capacity growth detaches the previous views, so
-   * writing first and sizing after would write into a stale buffer.
-   */
-  ensure(springCount, tweenCount) {
-    if (springCount + PAD4 <= this.springCap && tweenCount + PAD4 <= this.tweenCap) return;
-    this.springCap = springCount + PAD4;
-    this.tweenCap = tweenCount + PAD4;
-    this.ex.anim_init(this.springCap, this.tweenCap);
-    this.refreshViews();
-  }
-  /** Advance `count` springs (from index 0) by `dtMs` milliseconds, in place. */
-  stepSprings(dtMs, count) {
-    this.ex.spring_step(dtMs / 1e3, count);
-  }
-  /** Advance `count` tweens (from index 0) by `dtMs` milliseconds, writing `val`. */
-  stepTweens(dtMs, count) {
-    this.ex.tween_step(dtMs, count);
-  }
-  refreshViews() {
-    const buf = this.ex.memory.buffer;
-    const sCap = this.springCap;
-    const tCap = this.tweenCap;
-    this.sv = {
-      val: new Float64Array(buf, this.ex.p_s_val(), sCap),
-      target: new Float64Array(buf, this.ex.p_s_target(), sCap),
-      vel: new Float64Array(buf, this.ex.p_s_vel(), sCap),
-      stiff: new Float64Array(buf, this.ex.p_s_stiff(), sCap),
-      damp: new Float64Array(buf, this.ex.p_s_damp(), sCap),
-      mass: new Float64Array(buf, this.ex.p_s_mass(), sCap)
-    };
-    this.tv = {
-      from: new Float64Array(buf, this.ex.p_t_from(), tCap),
-      to: new Float64Array(buf, this.ex.p_t_to(), tCap),
-      elapsed: new Float64Array(buf, this.ex.p_t_elapsed(), tCap),
-      dur: new Float64Array(buf, this.ex.p_t_dur(), tCap),
-      delay: new Float64Array(buf, this.ex.p_t_delay(), tCap),
-      ease: new Float64Array(buf, this.ex.p_t_ease(), tCap),
-      val: new Float64Array(buf, this.ex.p_t_val(), tCap)
-    };
-  }
-};
-async function instantiateAsync3(bytes) {
-  try {
-    const { instance } = await WebAssembly.instantiate(bytes, {});
-    return new AnimBackend(instance);
-  } catch {
-    return null;
-  }
-}
-async function instantiateStreaming3(source) {
-  try {
-    const resp = typeof source === "string" || source instanceof URL ? await fetch(String(source)) : await source;
-    if (typeof WebAssembly.instantiateStreaming === "function") {
-      const buffered = resp.clone();
-      try {
-        const { instance: instance2 } = await WebAssembly.instantiateStreaming(resp, {});
-        return new AnimBackend(instance2);
-      } catch {
-        const { instance: instance2 } = await WebAssembly.instantiate(await buffered.arrayBuffer(), {});
-        return new AnimBackend(instance2);
-      }
-    }
-    const { instance } = await WebAssembly.instantiate(await resp.arrayBuffer(), {});
-    return new AnimBackend(instance);
-  } catch {
-    return null;
-  }
-}
 
 // src/wasm/particle-backend.ts
 var PAD5 = 8;
@@ -1066,33 +1098,95 @@ var ParticleBackend = class {
     };
   }
 };
-async function instantiateAsync4(bytes) {
-  try {
-    const { instance } = await WebAssembly.instantiate(bytes, {});
-    return new ParticleBackend(instance);
-  } catch {
-    return null;
+
+// src/wasm/runtime.ts
+var moduleCache = /* @__PURE__ */ new Map();
+function cacheKey(source) {
+  if (typeof source === "string") return source;
+  if (source instanceof URL) return source.href;
+  return null;
+}
+async function compile(source) {
+  if (source instanceof ArrayBuffer || ArrayBuffer.isView(source)) {
+    return new WebAssembly.Module(source);
+  }
+  const response = typeof source === "string" || source instanceof URL ? await fetch(String(source)) : await source;
+  if (typeof WebAssembly.compileStreaming === "function") {
+    const buffered = response.clone();
+    try {
+      return await WebAssembly.compileStreaming(response);
+    } catch {
+      return await WebAssembly.compile(await buffered.arrayBuffer());
+    }
   }
+  return await WebAssembly.compile(await response.arrayBuffer());
 }
-async function instantiateStreaming4(source) {
-  try {
-    const resp = typeof source === "string" || source instanceof URL ? await fetch(String(source)) : await source;
-    if (typeof WebAssembly.instantiateStreaming === "function") {
-      const buffered = resp.clone();
+async function loadCoreWasmModule(source) {
+  const key = cacheKey(source);
+  if (key !== null) {
+    const hit = moduleCache.get(key);
+    if (hit) {
       try {
-        const { instance: instance2 } = await WebAssembly.instantiateStreaming(resp, {});
-        return new ParticleBackend(instance2);
+        return await hit;
       } catch {
-        const { instance: instance2 } = await WebAssembly.instantiate(await buffered.arrayBuffer(), {});
-        return new ParticleBackend(instance2);
+        moduleCache.delete(key);
+        return null;
       }
     }
-    const { instance } = await WebAssembly.instantiate(await resp.arrayBuffer(), {});
-    return new ParticleBackend(instance);
+  }
+  const pending = compile(source);
+  if (key !== null) moduleCache.set(key, pending);
+  try {
+    return await pending;
   } catch {
+    if (key !== null) moduleCache.delete(key);
     return null;
   }
 }
+var CoreWasmRuntime = class {
+  instance;
+  transformBackend = null;
+  animBackend = null;
+  hitBackend = null;
+  particleBackendInstance = null;
+  constructor(instance) {
+    this.instance = instance;
+  }
+  /**
+   * Backends are constructed lazily and memoised: each one's constructor calls
+   * into the instance to size its store and build typed-array views, so building
+   * all four up front would pay for accelerators the Scene never enables.
+   */
+  transform() {
+    if (!this.transformBackend) this.transformBackend = new WasmTransformBackend(this.instance);
+    return this.transformBackend;
+  }
+  anim() {
+    if (!this.animBackend) this.animBackend = new AnimBackend(this.instance);
+    return this.animBackend;
+  }
+  hit() {
+    if (!this.hitBackend) this.hitBackend = new HitTestBackend(this.instance);
+    return this.hitBackend;
+  }
+  particle() {
+    if (!this.particleBackendInstance)
+      this.particleBackendInstance = new ParticleBackend(this.instance);
+    return this.particleBackendInstance;
+  }
+};
+function createCoreWasmRuntime(module) {
+  try {
+    return new CoreWasmRuntime(new WebAssembly.Instance(module, {}));
+  } catch {
+    return null;
+  }
+}
+async function loadCoreWasmRuntime(source) {
+  const module = await loadCoreWasmModule(source);
+  if (!module) return null;
+  return createCoreWasmRuntime(module);
+}
 
 // src/tree/Scene.ts
 import { clearCssLineBoxMetrics, cssLineBoxBaseline } from "@vectojs/text";
@@ -1673,10 +1767,9 @@ var Scene = class _Scene {
    * Resolves `true` if WASM is now active, `false` if the JS path remains.
    */
   async enableWasmTransforms(source) {
-    const isBytes = source instanceof ArrayBuffer || ArrayBuffer.isView(source);
-    const backend = isBytes ? await instantiateAsync(source) : await instantiateStreaming(source);
-    if (!backend) return false;
-    this.setTransformBackend(backend);
+    const runtime = await this.ensureWasmRuntime(source);
+    if (!runtime) return false;
+    this.setTransformBackend(runtime.transform());
     return true;
   }
   // ── WASM hit-test backend (invisible accelerator, G3) ───────────────────────
@@ -1690,6 +1783,44 @@ var Scene = class _Scene {
   // ever change *how fast* a hit is found, never *which* entity is returned —
   // every grid candidate is re-confirmed against its own precise
   // isPointInside before being trusted (see hit-store.ts / hit-backend.ts).
+  /**
+   * The one WASM instance this Scene's accelerators share.
+   *
+   * Each `enableWasm*` used to instantiate the binary itself, so enabling all
+   * four compiled the same module four times and held four linear memories. The
+   * Rust crate already keeps transform/anim/hit/particle in separate statics, so
+   * one instance serves all of them without aliasing. The compiled module is
+   * cached globally; the instance is per-Scene, which is the isolation that
+   * actually matters.
+   */
+  _wasmRuntime = null;
+  /**
+   * Load (or reuse) this Scene's shared WASM runtime.
+   *
+   * Returns `null` on any failure — CSP `wasm-unsafe-eval`, a 404, corrupt bytes,
+   * unsupported SIMD — so every caller keeps its JS path. Failure is the default
+   * state here, not an error path.
+   */
+  async ensureWasmRuntime(source) {
+    if (this._wasmRuntime) return this._wasmRuntime;
+    const runtime = await loadCoreWasmRuntime(source);
+    if (!runtime) return null;
+    if (this._wasmRuntime) return this._wasmRuntime;
+    this._wasmRuntime = runtime;
+    return runtime;
+  }
+  /**
+   * Install a pre-built runtime, so several Scenes can share one compile while
+   * each keeps its own stores. Pass `null` to detach (backends already installed
+   * keep working; only subsequent `enableWasm*` calls re-load).
+   */
+  setWasmRuntime(runtime) {
+    this._wasmRuntime = runtime;
+  }
+  /** The shared WASM runtime, if one has been loaded. */
+  get wasmRuntime() {
+    return this._wasmRuntime;
+  }
   _hitWasm = null;
   // Cache key: which frame + structure version the grid was last (successfully,
   // non-overflowing) built for. findEntityAt is called ad-hoc (pointer
@@ -1700,6 +1831,24 @@ var Scene = class _Scene {
   _hitGridOk = false;
   _hitSlotEntity = [];
   _hitBoundless = [];
+  /** Reused buffer for the fused gather, so a pointer query allocates nothing. */
+  _hitGatherBuffer = null;
+  /**
+   * Whether the last grid build sourced its AABBs from the WASM transform store
+   * rather than recomputing them in JS. Diagnostic only — both paths must
+   * produce the same entity for a given point.
+   */
+  _hitFusedGather = false;
+  /**
+   * Whether `compute_aabbs` has run against the current frame's world matrices.
+   * The AABB pass is only meaningful after a `compose_*`, so the fused gather
+   * must not read the views before then.
+   */
+  _wasmAabbsFresh = false;
+  /** Did the last hit-grid build use the fused (WASM-store) gather? */
+  get hitGatherPath() {
+    return this._hitFusedGather ? "fused" : "js";
+  }
   /** Which backend answers `findEntityAt` for the main tree. */
   get hitTestBackend() {
     return this._hitWasm ? "wasm" : "js";
@@ -1718,10 +1867,9 @@ var Scene = class _Scene {
    * state, not an error path. Resolves `true` if WASM is now active.
    */
   async enableWasmHitTest(source) {
-    const isBytes = source instanceof ArrayBuffer || ArrayBuffer.isView(source);
-    const backend = isBytes ? await instantiateAsync2(source) : await instantiateStreaming2(source);
-    if (!backend) return false;
-    this.setHitTestBackend(backend);
+    const runtime = await this.ensureWasmRuntime(source);
+    if (!runtime) return false;
+    this.setHitTestBackend(runtime.hit());
     return true;
   }
   /**
@@ -1738,7 +1886,22 @@ var Scene = class _Scene {
     const backend = this._hitWasm;
     if (!backend) return false;
     if (this._hitGridFrame === this.currentFrame) return this._hitGridOk;
-    const gathered = gatherHitAABBs(this.root, this.currentFrame);
+    let gathered = null;
+    if (this._wasm && this._ensureWasmAabbs()) {
+      this._hitGatherBuffer ??= createHitGatherBuffer();
+      this._wasm.revalidateViews();
+      gathered = gatherHitAABBsFromStore(
+        this.root,
+        this._wasm.aabbView(),
+        this._slotEntity,
+        this._hitGatherBuffer
+      );
+      if (gathered) this._hitFusedGather = true;
+    }
+    if (!gathered) {
+      this._hitFusedGather = false;
+      gathered = gatherHitAABBs(this.root, this.currentFrame);
+    }
     backend.ensure(gathered.count, this.width, this.height, 64);
     const view = backend.inputView();
     view.minx.set(gathered.minx.subarray(0, gathered.count));
@@ -1851,7 +2014,57 @@ var Scene = class _Scene {
    * own target browser mix and driver-kind distribution, or leave WASM
    * animation batching disabled entirely on a Firefox-heavy audience.
    */
-  animDriverGateCount = 256;
+  /**
+   * Back-compat alias for {@link animGate}. Reading it returns the tween gate
+   * (the conservative one the single knob used to represent); writing it sets all
+   * three, so code that tuned one number keeps behaving as before.
+   *
+   * Prefer {@link animGate} — a single threshold cannot be right for both kinds,
+   * which is why this exists as an alias rather than the primary control.
+   */
+  get animDriverGateCount() {
+    return this.animGate.tween;
+  }
+  set animDriverGateCount(n) {
+    this.animGate = { spring: n, tween: n, mixed: n };
+  }
+  /**
+   * Per-kind driver gates, in active batchable drivers.
+   *
+   * Measured on the integrated path (`benchmarks/anim-wasm-scene`, real Chrome
+   * 150 / Firefox 153): spring and mixed workloads are a ~1.4-2.3x win from 128
+   * drivers up through 16384, while pure tween is a **0.71x loss** at 128 and
+   * only turns net-positive near 256. One scalar threshold therefore had to be
+   * set for the worst kind, discarding the 128-255 spring win to avoid making a
+   * tween-heavy scene slower.
+   *
+   * Firefox is a net loss at every count measured up to 16384 — not an
+   * allocation artifact (confirmed after removing all per-frame allocation from
+   * gather/scatter); SpiderMonkey's wasm-boundary cost for this call shape
+   * appears to structurally exceed the saving at these scales. These defaults are
+   * Chrome-oriented; on a Firefox-heavy audience, leave
+   * {@link enableWasmAnimBatching} off entirely rather than tuning these.
+   *
+   * Setting {@link animDriverGateCount} overwrites all three, so existing code
+   * that tuned the single knob keeps working unchanged.
+   */
+  _animBatchedLastFrame = false;
+  /**
+   * Whether the WASM batch path actually ran on the most recent frame.
+   *
+   * Distinct from {@link animBackend}, which reports only that a backend is
+   * installed — a gate below the driver count means the frame still ticked in JS.
+   * Conflating the two makes it easy to believe an accelerator is active when it
+   * never opens.
+   */
+  get animBatchedLastFrame() {
+    return this._animBatchedLastFrame;
+  }
+  animGate = {
+    spring: 128,
+    tween: 256,
+    mixed: 128
+  };
   /** Which backend advances active property drivers on the current gate
    *  decision. Reflects only whether a backend is installed — the per-frame
    *  gate can still choose the JS path even when this reads `'wasm'`. */
@@ -1872,10 +2085,9 @@ var Scene = class _Scene {
    * if WASM is now available (not necessarily active every frame).
    */
   async enableWasmAnimBatching(source) {
-    const isBytes = source instanceof ArrayBuffer || ArrayBuffer.isView(source);
-    const backend = isBytes ? await instantiateAsync3(source) : await instantiateStreaming3(source);
-    if (!backend) return false;
-    this.setAnimBackend(backend);
+    const runtime = await this.ensureWasmRuntime(source);
+    if (!runtime) return false;
+    this.setAnimBackend(runtime.anim());
     return true;
   }
   // ── WASM particle CPU-sim backend (invisible accelerator, G4) ───────────────
@@ -1906,10 +2118,9 @@ var Scene = class _Scene {
    * Resolves `true` if WASM is now active.
    */
   async enableWasmParticles(source) {
-    const isBytes = source instanceof ArrayBuffer || ArrayBuffer.isView(source);
-    const backend = isBytes ? await instantiateAsync4(source) : await instantiateStreaming4(source);
-    if (!backend) return false;
-    this.setParticleBackend(backend);
+    const runtime = await this.ensureWasmRuntime(source);
+    if (!runtime) return false;
+    this.setParticleBackend(runtime.particle());
     return true;
   }
   /** Internal: called by `Entity._spawnDriver` when a new property driver
@@ -1968,7 +2179,8 @@ var Scene = class _Scene {
    */
   _tickBatchedDrivers(dt) {
     if (this._activeDriverEntities.size === 0) return;
-    let batchable = 0;
+    let springBatchable = 0;
+    let tweenBatchable = 0;
     for (const entity of this._activeDriverEntities) {
       const entries = entity._driverEntries();
       if (!entries || entries.size === 0) {
@@ -1976,12 +2188,17 @@ var Scene = class _Scene {
         continue;
       }
       for (const driver of entries.values()) {
-        if (driver instanceof SpringDriver) batchable++;
-        else if (driver instanceof TweenDriver && driver.wasmEasingId !== null) batchable++;
+        if (driver instanceof SpringDriver) springBatchable++;
+        else if (driver instanceof TweenDriver && driver.wasmEasingId !== null) tweenBatchable++;
       }
     }
+    const batchable = springBatchable + tweenBatchable;
     const backend = this._animWasm;
-    if (!backend || batchable < this.animDriverGateCount) return;
+    this._animBatchedLastFrame = false;
+    if (!backend) return;
+    const gate = springBatchable > 0 && tweenBatchable > 0 ? this.animGate.mixed : tweenBatchable > 0 ? this.animGate.tween : this.animGate.spring;
+    if (batchable < gate) return;
+    this._animBatchedLastFrame = true;
     const sE = this._springEntities;
     const sP = this._springProps;
     const sD = this._springDrivers;
@@ -2072,6 +2289,11 @@ var Scene = class _Scene {
       this._wasmWorld = backend.worldView();
       this._storeStructureVersion = this._structureVersion;
     }
+    backend.revalidateViews();
+    if (this._wasmInputs && this._wasmInputs.x.length === 0) {
+      this._wasmInputs = backend.inputView();
+      this._wasmWorld = backend.worldView();
+    }
     const inp = this._wasmInputs;
     const slotEntity = this._slotEntity;
     for (let slot = 1; slot < slotEntity.length; slot++) {
@@ -2086,8 +2308,40 @@ var Scene = class _Scene {
       inp.opacity[slot] = e.opacity;
     }
     backend.runKernel("simd");
+    this._wasmAabbsFresh = false;
     return this._wasmWorld;
   }
+  /**
+   * Run the WASM world-AABB pass over the current frame's world matrices, so the
+   * fused hit gather can read AABBs straight out of the store.
+   *
+   * Local bounds are uploaded here rather than in the per-frame transform sync
+   * because `getBounds()` is a virtual call that allocates a rect on most
+   * entities — paying it every frame for a query that may never come would move
+   * cost onto the render path to save it on hover. Returns `false` if any entity
+   * cannot supply bounds through the store, so the caller uses the JS gather.
+   */
+  _ensureWasmAabbs() {
+    const backend = this._wasm;
+    const store = this._treeStore;
+    if (!backend || !store) return false;
+    if (this._wasmAabbsFresh) return true;
+    backend.revalidateViews();
+    const bounds = backend.boundsView();
+    const slotEntity = this._slotEntity;
+    for (let slot = 0; slot < slotEntity.length; slot++) {
+      const e = slotEntity[slot];
+      if (!e) continue;
+      const b = e.getBounds();
+      bounds.bx[slot] = b ? b.x : 0;
+      bounds.by[slot] = b ? b.y : 0;
+      bounds.bw[slot] = b ? b.width : 0;
+      bounds.bh[slot] = b ? b.height : 0;
+    }
+    backend.runAabbs(slotEntity.length);
+    this._wasmAabbsFresh = true;
+    return true;
+  }
   /**
    * Authoritative paint order for semantic nodes discovered during the main
    * render. A node may not have a DOM projection until the following a11y
@@ -2161,17 +2415,17 @@ var Scene = class _Scene {
     this._devFrameCount++;
     if (this._devFrameCount % 120 !== 0) return;
     if (this.a11yElements) {
-      let interactiveCount = 0;
+      let projectableCount = 0;
       const walk = (node) => {
-        if (node.interactive && node.width > 0) interactiveCount++;
+        if (this.shouldProjectA11y(node)) projectableCount++;
         for (const c of node.children) walk(c);
       };
       walk(this.root);
       for (const c of this.overlayRoot.children) walk(c);
       const shadowCount = this.a11yElements.size;
-      if (shadowCount > interactiveCount + 2) {
+      if (shadowCount > projectableCount) {
         this._devWarn(
-          `a11yElements (${shadowCount}) exceeds interactive entities (${interactiveCount}). Call scene.detachA11y(entity) before removing interactive children from the tree, or their shadow nodes leak.`
+          `a11yElements (${shadowCount}) exceeds projectable entities (${projectableCount}). Call scene.detachA11y(entity) before removing interactive children from the tree, or their shadow nodes leak.`
         );
       }
     }
@@ -2642,7 +2896,19 @@ var Scene = class _Scene {
    * without removing it from the scene graph. Components that manage dynamic
    * interactive *child* entities (e.g. a {@link Entity}'s per-link hotspots) call
    * this before discarding those children so their shadow `<a>`/controls don't
-   * leak (the per-frame `syncA11y` only creates/updates, it never prunes).
+   * leak.
+   *
+   * `syncA11y` itself only creates and updates, never prunes — but it is always
+   * followed by `enforceA11yDomOrder`, whose prune pass removes any element
+   * whose entity is no longer reachable in the tree or no longer satisfies
+   * {@link shouldProjectA11y}. So an entity that is `remove()`d, or whose
+   * `interactive` flips to `false`, has its element torn down on the next synced
+   * frame without any explicit call.
+   *
+   * This method is for the case that pass cannot see: a child dropped from a
+   * component's own bookkeeping while still parented, or one discarded before
+   * the next sync runs. Calling it is always safe and is the right habit for
+   * pooled children.
    *
    * @param entity - The subtree whose shadow nodes should be removed.
    */
@@ -2931,12 +3197,34 @@ var Scene = class _Scene {
     }
     if (element.getAttribute(name) !== value) element.setAttribute(name, value);
   }
+  /**
+   * Whether `node` should have an a11y shadow element projected for it.
+   *
+   * The single authority for that decision. It was previously inlined verbatim
+   * at four call sites — `syncA11y` (create/update), `enforceA11yDomOrder`
+   * (which ids survive pruning), `getA11yTree` (the public snapshot) and
+   * `render` (z-index / reading-order assignment). Four copies of one predicate
+   * is a standing correctness hazard: if any of them drifts, elements either
+   * leak (created but never marked active, so pruned every frame and rebuilt) or
+   * go missing from the semantic tree while still present in the DOM.
+   *
+   * A box is required because a zero-size element is unfocusable and
+   * unhittable; `a11yFullViewport` is the deliberate exception, since those
+   * nodes are boundless interaction surfaces mounted behind everything else.
+   *
+   * Keep this the only place the rule is written. A planned per-entity
+   * `a11yProjection` mode ('eager' | 'onDemand' | 'never') extends exactly this
+   * predicate, which is only tractable while it has one home.
+   */
+  shouldProjectA11y(node) {
+    return node.interactive && (node.width > 0 || node.a11yFullViewport);
+  }
   syncA11y(node) {
     if (!this.a11yRoot) return;
     if (node.isDOMPortal) {
       return;
     }
-    if (node.interactive && (node.width > 0 || node.a11yFullViewport)) {
+    if (this.shouldProjectA11y(node)) {
       let el = this.a11yElements.get(node.id);
       const attrs = node.getA11yAttributes();
       const expectedTag = attrs.tag || "div";
@@ -3712,7 +4000,7 @@ var Scene = class _Scene {
         if (node.a11yFullViewport) this.fullViewportElements.push(contentEl);
         else this.normalElements.push(contentEl);
       }
-      if (node.interactive && (node.width > 0 || node.a11yFullViewport)) {
+      if (this.shouldProjectA11y(node)) {
         const el = this.a11yElements.get(node.id);
         if (el) {
           this.activeIds.add(node.id);
@@ -3851,7 +4139,7 @@ var Scene = class _Scene {
     const traverse = (node, parentNode) => {
       if (node.isDOMPortal) return;
       let currentA11yNode = null;
-      if (node.interactive && (node.width > 0 || node.a11yFullViewport)) {
+      if (this.shouldProjectA11y(node)) {
         const el = this.a11yElements.get(node.id);
         if (el) {
           const attrs = node.getA11yAttributes();
@@ -4221,7 +4509,7 @@ var Scene = class _Scene {
       const orthogonalTolerance = Math.max(1, worldScaleX * worldScaleY) * 1e-6;
       const isSimilarityTransform = Number.isFinite(worldScaleX) && Number.isFinite(worldScaleY) && Math.abs(worldScaleX - worldScaleY) <= scaleTolerance && Math.abs(a * c + b * d) <= orthogonalTolerance;
       const a11yEl = isMainRenderer ? this.a11yElements.get(node.id) : void 0;
-      const willProjectA11y = isMainRenderer && node.interactive && (node.width > 0 || node.a11yFullViewport);
+      const willProjectA11y = isMainRenderer && this.shouldProjectA11y(node);
       if (a11yEl || willProjectA11y) {
         const renderOrder = this.renderOrderCounter++;
         if (willProjectA11y) this.a11yRenderOrders.set(node.id, renderOrder);