@vectojs/core 1.15.0 → 1.16.1

package/dist/index.mjs

@@ -7,13 +7,16 @@ import {
   isSafeUrl,
   parseColorToRGBA,
   sanitizeUrl
-} from "./chunk-L5BCKFQE.mjs";
+} from "./chunk-JFU56BX4.mjs";
 import {
   Entity,
   MSDFTextEntity,
   SVGEntity,
   VectoJSEvent
-} from "./chunk-64UFEHOJ.mjs";
+} from "./chunk-AQTO7OSU.mjs";
+
+// src/tree/Scene.ts
+import { SpringDriver, TweenDriver } from "@vectojs/animation";
 
 // src/tree/ComputeParticleEntity.ts
 var PARTICLE_STRIDE_FLOATS = 8;
@@ -48,6 +51,10 @@ var ComputeParticleEntity = class extends Entity {
   computeBindGroup = null;
   /** WebGPU bind group for the render pass (usually same as compute). */
   renderBindGroup = null;
+  /** When the last simulation step ran through the WASM backend, its fused
+   *  pending-animation flag; `null` when the last step used the JS `updateCPU`
+   *  path (so `hasPendingAnimations` falls back to its own scan). */
+  _wasmPending = null;
   constructor(options = {}) {
     super();
     this.maxParticles = options.maxParticles ?? 1e4;
@@ -177,6 +184,9 @@ var ComputeParticleEntity = class extends Entity {
    * always return `true` and defeat the idle throttle entirely.
    */
   hasPendingAnimations() {
+    if (this._wasmPending !== null) {
+      return this._wasmPending || this.pendingExplosion !== null;
+    }
     const EPS_VELOCITY = 0.5;
     const EPS_DISTANCE = 0.5;
     for (let i = 0; i < this.maxParticles; i++) {
@@ -202,6 +212,7 @@ var ComputeParticleEntity = class extends Entity {
    * @param height - Boundary height.
    */
   updateCPU(dt, mouseX, mouseY, width, height) {
+    this._wasmPending = null;
     const safeDt = isNaN(dt) ? 0.016 : Math.max(0, Math.min(dt, 0.1));
     const explosion = this.pendingExplosion;
     const safeWidth = Math.max(1, width);
@@ -284,6 +295,37 @@ var ComputeParticleEntity = class extends Entity {
     }
     this.pendingExplosion = null;
   }
+  /**
+   * Advance the simulation one step through the WASM particle kernel: transpose
+   * this entity's AoS buffer into the backend's SoA views, run `particle_step`,
+   * and scatter position/velocity/life back. Produces an f32 result (matching
+   * the WGSL shader) that differs from {@link updateCPU}'s f64 by <1 ULP/step —
+   * the accepted CPU-vs-GPU-class divergence. Caches the kernel's fused
+   * pending-animation flag so {@link hasPendingAnimations} needs no second scan.
+   *
+   * The backend holds one resident SoA store, so a Scene with multiple particle
+   * entities reuses it sequentially — origin is therefore re-gathered each call
+   * (not upload-once), a couple of extra f32 reads per particle.
+   */
+  stepWithBackend(backend, dt, mouseX, mouseY, width, height) {
+    const count = this.maxParticles;
+    backend.ensure(count);
+    backend.gather(this.particleData, count, true);
+    this._wasmPending = backend.step(count, {
+      dt,
+      mouseX,
+      mouseY,
+      width,
+      height,
+      springK: this.springK,
+      damping: this.damping,
+      bounceDamping: this.bounceDamping,
+      maxVelocity: this.maxVelocity,
+      explosion: this.pendingExplosion
+    });
+    backend.scatter(this.particleData, count);
+    this.pendingExplosion = null;
+  }
   destroy() {
     this.destroyGPUResources();
     super.destroy();
@@ -309,6 +351,749 @@ var ComputeParticleEntity = class extends Entity {
   }
 };
 
+// src/wasm/soa.ts
+var PAD = 8;
+function buildStore(nodes) {
+  const count = nodes.length;
+  const capacity = count + PAD;
+  const childrenOf = Array.from({ length: count }, () => []);
+  let rootInput = -1;
+  for (let k = 0; k < count; k++) {
+    const p = nodes[k].parent;
+    if (p === -1) {
+      if (rootInput !== -1) throw new Error("buildStore: more than one root (parent === -1)");
+      rootInput = k;
+    } else {
+      if (p < 0 || p >= count)
+        throw new Error(`buildStore: node ${k} has out-of-range parent ${p}`);
+      childrenOf[p].push(k);
+    }
+  }
+  if (rootInput === -1) throw new Error("buildStore: no root (need exactly one parent === -1)");
+  const store = {
+    count,
+    capacity,
+    x: new Float64Array(capacity),
+    y: new Float64Array(capacity),
+    sx: new Float64Array(capacity),
+    sy: new Float64Array(capacity),
+    cos: new Float64Array(capacity),
+    sin: new Float64Array(capacity),
+    opacity: new Float64Array(capacity),
+    wa: new Float64Array(capacity),
+    wb: new Float64Array(capacity),
+    wc: new Float64Array(capacity),
+    wd: new Float64Array(capacity),
+    we: new Float64Array(capacity),
+    wf: new Float64Array(capacity),
+    wo: new Float64Array(capacity),
+    bx: new Float64Array(capacity),
+    by: new Float64Array(capacity),
+    bw: new Float64Array(capacity),
+    bh: new Float64Array(capacity),
+    aminx: new Float64Array(capacity),
+    aminy: new Float64Array(capacity),
+    amaxx: new Float64Array(capacity),
+    amaxy: new Float64Array(capacity),
+    runParent: new Int32Array(count),
+    runStart: new Int32Array(count),
+    runLen: new Int32Array(count),
+    runCount: 0,
+    storeIndexOf: new Int32Array(count).fill(-1)
+  };
+  store.storeIndexOf[rootInput] = 0;
+  writeInput(store, 0, nodes[rootInput]);
+  let next = 1;
+  const queue = [rootInput];
+  let head = 0;
+  while (head < queue.length) {
+    const parentInput = queue[head++];
+    const kids = childrenOf[parentInput];
+    if (kids.length === 0) continue;
+    const runStart = next;
+    for (const kid of kids) {
+      store.storeIndexOf[kid] = next;
+      writeInput(store, next, nodes[kid]);
+      next++;
+    }
+    const r = store.runCount++;
+    store.runParent[r] = store.storeIndexOf[parentInput];
+    store.runStart[r] = runStart;
+    store.runLen[r] = kids.length;
+    for (const kid of kids) queue.push(kid);
+  }
+  return store;
+}
+function writeInput(s, i, n) {
+  s.x[i] = n.x;
+  s.y[i] = n.y;
+  s.sx[i] = n.scaleX;
+  s.sy[i] = n.scaleY;
+  s.cos[i] = Math.cos(n.rotation);
+  s.sin[i] = Math.sin(n.rotation);
+  s.opacity[i] = n.opacity;
+  s.bx[i] = n.bx ?? 0;
+  s.by[i] = n.by ?? 0;
+  s.bw[i] = n.bw ?? 0;
+  s.bh[i] = n.bh ?? 0;
+}
+
+// src/wasm/scene-store.ts
+function buildTreeStore(root) {
+  const entities = [];
+  const inputIndex = /* @__PURE__ */ new Map();
+  const collect = (e) => {
+    inputIndex.set(e, entities.length);
+    entities.push(e);
+    const kids = e.children;
+    for (let i = 0; i < kids.length; i++) collect(kids[i]);
+  };
+  collect(root);
+  const nodes = entities.map((e) => {
+    const parent = e.parent;
+    const p = parent !== null && inputIndex.has(parent) ? inputIndex.get(parent) : -1;
+    return {
+      parent: e === root ? -1 : p,
+      x: e.x,
+      y: e.y,
+      scaleX: e.scaleX,
+      scaleY: e.scaleY,
+      rotation: e.rotation,
+      opacity: e.opacity
+    };
+  });
+  const store = buildStore(nodes);
+  const indexOf = /* @__PURE__ */ new Map();
+  for (const [e, ii] of inputIndex) indexOf.set(e, store.storeIndexOf[ii]);
+  return { store, indexOf };
+}
+
+// src/wasm/backend.ts
+var PAD2 = 8;
+var WasmTransformBackend = class {
+  available = true;
+  ex;
+  cap = 0;
+  runCap = 0;
+  // Views over wasm linear memory, valid until the next init().
+  vx;
+  vy;
+  vsx;
+  vsy;
+  vcos;
+  vsin;
+  vop;
+  vwa;
+  vwb;
+  vwc;
+  vwd;
+  vwe;
+  vwf;
+  vwo;
+  vbx;
+  vby;
+  vbw;
+  vbh;
+  vaminx;
+  vaminy;
+  vamaxx;
+  vamaxy;
+  vrp;
+  vrs;
+  vrl;
+  constructor(instance) {
+    this.ex = instance.exports;
+  }
+  /** Compose world matrices for `store` in WASM, writing back into its
+   *  `wa..wo` arrays. Result is bit-identical to `composeJS(store)`. */
+  compose(store, kernel = "simd") {
+    this.ensure(store.count, store.runCount);
+    const n = store.count;
+    this.vx.set(store.x.subarray(0, n));
+    this.vy.set(store.y.subarray(0, n));
+    this.vsx.set(store.sx.subarray(0, n));
+    this.vsy.set(store.sy.subarray(0, n));
+    this.vcos.set(store.cos.subarray(0, n));
+    this.vsin.set(store.sin.subarray(0, n));
+    this.vop.set(store.opacity.subarray(0, n));
+    const rc = store.runCount;
+    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();
+    store.wa.set(this.vwa.subarray(0, n));
+    store.wb.set(this.vwb.subarray(0, n));
+    store.wc.set(this.vwc.subarray(0, n));
+    store.wd.set(this.vwd.subarray(0, n));
+    store.we.set(this.vwe.subarray(0, n));
+    store.wf.set(this.vwf.subarray(0, n));
+    store.wo.set(this.vwo.subarray(0, n));
+  }
+  /**
+   * Run the kernel only, over data already resident in WASM memory — no upload,
+   * no readback. This is the per-frame cost the *designed* integration pays:
+   * entity accessors write `x/y/rotation` straight into the wasm input views
+   * (via {@link inputView}) and the renderer reads world matrices straight from
+   * the wasm output views (via {@link worldView}), so the batch copies in
+   * {@link compose} do not happen every frame. `compose` must have run at least
+   * once at the current capacity to size the store and set the run count; call
+   * {@link uploadRuns} after a topology change.
+   */
+  runKernel(kernel = "simd") {
+    if (kernel === "scalar") this.ex.compose_scalar();
+    else this.ex.compose_simd();
+  }
+  /** Upload only the run table + count (topology), leaving per-entity inputs to
+   *  the resident views. Call when the tree structure changes, not per frame. */
+  uploadRuns(store) {
+    this.ensure(store.count, store.runCount);
+    const rc = store.runCount;
+    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);
+  }
+  /** 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() {
+    return {
+      x: this.vx,
+      y: this.vy,
+      sx: this.vsx,
+      sy: this.vsy,
+      cos: this.vcos,
+      sin: this.vsin,
+      opacity: this.vop
+    };
+  }
+  /** The resident wasm world-matrix output views (`wa..wo`). Reading here is
+   *  what makes readback unnecessary. */
+  worldView() {
+    return {
+      wa: this.vwa,
+      wb: this.vwb,
+      wc: this.vwc,
+      wd: this.vwd,
+      we: this.vwe,
+      wf: this.vwf,
+      wo: this.vwo
+    };
+  }
+  /**
+   * Compute world-space AABBs for `store` in WASM (G1+), writing back into its
+   * `aminx/aminy/amaxx/amaxy` arrays. Uploads the local bounds, runs the AABB
+   * pass, reads results back. Result is bit-identical to `computeAabbsJS(store)`.
+   * `compose` (or `runKernel`) must have populated the world matrices first —
+   * this pass reads them. For the resident (no-copy) integration, write bounds
+   * via {@link boundsView} and read via {@link aabbView} + call
+   * {@link runAabbs} instead.
+   */
+  computeAabbs(store) {
+    this.ensure(store.count, store.runCount);
+    const n = store.count;
+    this.vbx.set(store.bx.subarray(0, n));
+    this.vby.set(store.by.subarray(0, n));
+    this.vbw.set(store.bw.subarray(0, n));
+    this.vbh.set(store.bh.subarray(0, n));
+    this.ex.compute_aabbs(n);
+    store.aminx.set(this.vaminx.subarray(0, n));
+    store.aminy.set(this.vaminy.subarray(0, n));
+    store.amaxx.set(this.vamaxx.subarray(0, n));
+    store.amaxy.set(this.vamaxy.subarray(0, n));
+  }
+  /** Run the AABB pass only, over `count` entities already resident in wasm
+   *  memory (bounds written via {@link boundsView}, world matrices already
+   *  composed). No upload/readback — the per-frame resident path. */
+  runAabbs(count) {
+    this.ex.compute_aabbs(count);
+  }
+  /** Resident wasm local-bounds input views (`bx,by,bw,bh`) for the AABB pass. */
+  boundsView() {
+    return { bx: this.vbx, by: this.vby, bw: this.vbw, bh: this.vbh };
+  }
+  /** Resident wasm world-AABB output views (`aminx,aminy,amaxx,amaxy`). */
+  aabbView() {
+    return {
+      aminx: this.vaminx,
+      aminy: this.vaminy,
+      amaxx: this.vamaxx,
+      amaxy: this.vamaxy
+    };
+  }
+  ensure(count, runCount) {
+    if (count + PAD2 <= this.cap && runCount <= this.runCap) return;
+    this.cap = count + PAD2;
+    this.runCap = Math.max(runCount, count, 1);
+    this.ex.init(count, this.runCap);
+    this.refreshViews();
+  }
+  /** Rebuild typed-array views after an init() (which may have grown, and thus
+   *  detached, the memory buffer). */
+  refreshViews() {
+    const buf = this.ex.memory.buffer;
+    const cap = this.cap;
+    const rc = this.runCap;
+    const f64 = (ptr) => new Float64Array(buf, ptr, cap);
+    const i32 = (ptr) => new Int32Array(buf, ptr, rc);
+    this.vx = f64(this.ex.p_x());
+    this.vy = f64(this.ex.p_y());
+    this.vsx = f64(this.ex.p_sx());
+    this.vsy = f64(this.ex.p_sy());
+    this.vcos = f64(this.ex.p_cos());
+    this.vsin = f64(this.ex.p_sin());
+    this.vop = f64(this.ex.p_opacity());
+    this.vwa = f64(this.ex.p_wa());
+    this.vwb = f64(this.ex.p_wb());
+    this.vwc = f64(this.ex.p_wc());
+    this.vwd = f64(this.ex.p_wd());
+    this.vwe = f64(this.ex.p_we());
+    this.vwf = f64(this.ex.p_wf());
+    this.vwo = f64(this.ex.p_wo());
+    this.vbx = f64(this.ex.p_bx());
+    this.vby = f64(this.ex.p_by());
+    this.vbw = f64(this.ex.p_bw());
+    this.vbh = f64(this.ex.p_bh());
+    this.vaminx = f64(this.ex.p_aminx());
+    this.vaminy = f64(this.ex.p_aminy());
+    this.vamaxx = f64(this.ex.p_amaxx());
+    this.vamaxy = f64(this.ex.p_amaxy());
+    this.vrp = i32(this.ex.p_run_parent());
+    this.vrs = i32(this.ex.p_run_start());
+    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;
+  }
+}
+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;
+  }
+}
+
+// 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-backend.ts
+var PAD3 = 8;
+var CELLS_PER_ENTITY_HINT = 4;
+var HitTestBackend = class {
+  ex;
+  entityCap = 0;
+  cellCap = 0;
+  itemCap = 0;
+  vminx;
+  vminy;
+  vmaxx;
+  vmaxy;
+  vCellStart;
+  vCellCount;
+  vItems;
+  /** Grid geometry from the last {@link ensure} call. */
+  gridW = 0;
+  gridH = 0;
+  cellSize = 64;
+  constructor(instance) {
+    this.ex = instance.exports;
+  }
+  /** The resident AABB input views (`minx/miny/maxx/maxy`), valid until the
+   *  next capacity growth. Writing here is what {@link build} reads from. */
+  inputView() {
+    return { minx: this.vminx, miny: this.vminy, maxx: this.vmaxx, maxy: this.vmaxy };
+  }
+  /**
+   * Size (and grow, if needed) capacity for `count` entities over
+   * `[0,vw] x [0,vh]` at `cellSize`, and record the grid geometry
+   * {@link candidatesAt} needs. Call this BEFORE writing AABBs into
+   * {@link inputView} — a capacity growth detaches the previous views, so
+   * writing first and sizing after would write into a stale buffer.
+   */
+  ensure(count, vw, vh, cellSize) {
+    const gw = Math.max(1, Math.ceil(vw / cellSize));
+    const gh = Math.max(1, Math.ceil(vh / cellSize));
+    this.growIfNeeded(count, gw * gh, count * CELLS_PER_ENTITY_HINT);
+    this.gridW = gw;
+    this.gridH = gh;
+    this.cellSize = cellSize;
+  }
+  /**
+   * Run the kernel's bucketing over whatever is currently resident in
+   * {@link inputView} (write the AABBs there, and call {@link ensure} first).
+   * Returns `false` if the build overflowed its item budget — the caller must
+   * not trust {@link candidatesAt} results for this build and should fall back
+   * to the JS walk instead (never return a wrong hit).
+   */
+  runBuild(count, vw, vh, cellSize) {
+    this.ex.hit_build(count, vw, vh, cellSize);
+    return this.ex.hit_overflow() === 0;
+  }
+  /**
+   * Entity indices whose AABB overlaps the cell containing `(px, py)`, in
+   * ascending index order (scan from the end for topmost/highest-index
+   * first), or `null` if the point falls outside the built grid. This is a
+   * coarse candidate LIST, not a hit result — the caller must still confirm
+   * each candidate's AABB contains the point and re-check its precise
+   * `isPointInside`.
+   */
+  candidatesAt(px, py) {
+    if (px < 0 || py < 0) return null;
+    const cx = Math.floor(px / this.cellSize);
+    const cy = Math.floor(py / this.cellSize);
+    if (cx < 0 || cy < 0 || cx >= this.gridW || cy >= this.gridH) return null;
+    const c = cy * this.gridW + cx;
+    if (c >= this.cellCap) return null;
+    const start = this.vCellStart[c];
+    const count = this.vCellCount[c];
+    return this.vItems.subarray(start, start + count);
+  }
+  growIfNeeded(count, cellCount, itemCount) {
+    if (count + PAD3 <= this.entityCap && cellCount <= this.cellCap && itemCount <= this.itemCap) {
+      return;
+    }
+    this.entityCap = count + PAD3;
+    this.cellCap = Math.max(cellCount, 1);
+    this.itemCap = Math.max(itemCount, count, 1);
+    this.ex.hit_init(count, this.cellCap, this.itemCap);
+    this.refreshViews();
+  }
+  /** Rebuild typed-array views after a growing `hit_init` (which detaches the
+   *  memory buffer). */
+  refreshViews() {
+    const buf = this.ex.memory.buffer;
+    const eCap = this.entityCap;
+    const cCap = this.cellCap;
+    const iCap = this.itemCap;
+    this.vminx = new Float64Array(buf, this.ex.p_h_minx(), eCap);
+    this.vminy = new Float64Array(buf, this.ex.p_h_miny(), eCap);
+    this.vmaxx = new Float64Array(buf, this.ex.p_h_maxx(), eCap);
+    this.vmaxy = new Float64Array(buf, this.ex.p_h_maxy(), eCap);
+    this.vCellStart = new Int32Array(buf, this.ex.p_h_cell_start(), cCap);
+    this.vCellCount = new Int32Array(buf, this.ex.p_h_cell_count(), cCap);
+    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;
+var ParticleBackend = class {
+  ex;
+  cap = 0;
+  view;
+  constructor(instance) {
+    this.ex = instance.exports;
+  }
+  /** The resident SoA views, valid until the next capacity growth. */
+  particleView() {
+    return this.view;
+  }
+  /**
+   * Size (and grow, if needed) capacity for `count` particles. Call BEFORE
+   * writing into {@link particleView} — a growth detaches the previous views.
+   */
+  ensure(count) {
+    if (count + PAD5 <= this.cap) return;
+    this.cap = count + PAD5;
+    this.ex.particle_init(this.cap);
+    this.refreshViews();
+  }
+  /**
+   * Advance `count` particles one step in place. Returns `true` when at least
+   * one live particle is still moving or off-origin beyond epsilon (the fused
+   * `hasPendingAnimations` flag), so the caller need not re-scan the buffer.
+   */
+  step(count, p) {
+    const e = p.explosion;
+    const flag = this.ex.particle_step(
+      p.dt,
+      p.mouseX,
+      p.mouseY,
+      p.width,
+      p.height,
+      p.springK,
+      p.damping,
+      p.bounceDamping,
+      p.maxVelocity,
+      e ? 1 : 0,
+      e ? e.x : 0,
+      e ? e.y : 0,
+      e ? e.force : 0,
+      count
+    );
+    return flag !== 0;
+  }
+  /** Transpose the AoS stride-8 buffer into the SoA views (position/velocity/
+   *  life every frame; origin upload-once when `withOrigin`). */
+  gather(data, count, withOrigin) {
+    const v = this.view;
+    for (let i = 0; i < count; i++) {
+      const o = i * PARTICLE_STRIDE_FLOATS;
+      v.px[i] = data[o + PARTICLE_OFFSET_POSITION_X];
+      v.py[i] = data[o + PARTICLE_OFFSET_POSITION_Y];
+      v.vx[i] = data[o + PARTICLE_OFFSET_VELOCITY_X];
+      v.vy[i] = data[o + PARTICLE_OFFSET_VELOCITY_Y];
+      v.life[i] = data[o + PARTICLE_OFFSET_LIFE];
+      if (withOrigin) {
+        v.ox[i] = data[o + PARTICLE_OFFSET_ORIGIN_X];
+        v.oy[i] = data[o + PARTICLE_OFFSET_ORIGIN_Y];
+      }
+    }
+  }
+  /** Scatter the mutated position/velocity/life back into the AoS buffer. */
+  scatter(data, count) {
+    const v = this.view;
+    for (let i = 0; i < count; i++) {
+      const o = i * PARTICLE_STRIDE_FLOATS;
+      data[o + PARTICLE_OFFSET_POSITION_X] = v.px[i];
+      data[o + PARTICLE_OFFSET_POSITION_Y] = v.py[i];
+      data[o + PARTICLE_OFFSET_VELOCITY_X] = v.vx[i];
+      data[o + PARTICLE_OFFSET_VELOCITY_Y] = v.vy[i];
+      data[o + PARTICLE_OFFSET_LIFE] = v.life[i];
+    }
+  }
+  refreshViews() {
+    const buf = this.ex.memory.buffer;
+    const c = this.cap;
+    this.view = {
+      px: new Float32Array(buf, this.ex.pp_px(), c),
+      py: new Float32Array(buf, this.ex.pp_py(), c),
+      vx: new Float32Array(buf, this.ex.pp_vx(), c),
+      vy: new Float32Array(buf, this.ex.pp_vy(), c),
+      ox: new Float32Array(buf, this.ex.pp_ox(), c),
+      oy: new Float32Array(buf, this.ex.pp_oy(), c),
+      life: new Float32Array(buf, this.ex.pp_life(), c)
+    };
+  }
+};
+async function instantiateAsync4(bytes) {
+  try {
+    const { instance } = await WebAssembly.instantiate(bytes, {});
+    return new ParticleBackend(instance);
+  } catch {
+    return null;
+  }
+}
+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();
+      try {
+        const { instance: instance2 } = await WebAssembly.instantiateStreaming(resp, {});
+        return new ParticleBackend(instance2);
+      } catch {
+        const { instance: instance2 } = await WebAssembly.instantiate(await buffered.arrayBuffer(), {});
+        return new ParticleBackend(instance2);
+      }
+    }
+    const { instance } = await WebAssembly.instantiate(await resp.arrayBuffer(), {});
+    return new ParticleBackend(instance);
+  } catch {
+    return null;
+  }
+}
+
 // src/tree/Scene.ts
 import { clearCssLineBoxMetrics, cssLineBoxBaseline } from "@vectojs/text";
 var INTERACTIVE_A11Y_ROLES = /* @__PURE__ */ new Set([
@@ -625,6 +1410,10 @@ function extendSelection(selection, anchor, focus) {
 var Scene = class _Scene {
   static webglCreator = null;
   static webgpuManagerClass = null;
+  /** Upper bound (ms) on a single frame's `dt`. Caps the giant elapsed gap a
+   *  backgrounded/refocused tab produces so physics advances at most one slow
+   *  frame instead of the whole idle duration (~100ms ≈ 6 frames at 60fps). */
+  static MAX_FRAME_DT = 100;
   static registerWebGLPointRendererCreator(creator) {
     _Scene.webglCreator = creator;
   }
@@ -635,6 +1424,13 @@ var Scene = class _Scene {
   overlayRoot;
   renderer;
   isRunning = false;
+  /** Whether the canvas is at least partially in the viewport. When it scrolls
+   *  fully off-screen the rAF loop pauses (stops rescheduling) instead of
+   *  burning frames on a scene nobody can see; an IntersectionObserver resumes
+   *  it on re-entry. Defaults true (and stays true where IntersectionObserver
+   *  is unavailable, e.g. SSR/jsdom, so behavior is unchanged there). */
+  _canvasOnScreen = true;
+  _canvasObserver = null;
   lastTime = 0;
   canvas;
   /**
@@ -669,12 +1465,45 @@ var Scene = class _Scene {
   maxFPS = 60;
   /** Whether the OS prefers-reduced-motion setting auto-caps the loop. */
   respectReducedMotion = true;
+  /**
+   * Reading direction for accessibility tab/traversal order (`'ltr'` default,
+   * `'rtl'`). Controls the inline sort within a visual row in
+   * {@link enforceA11yDomOrder}. Set at runtime to re-flow tab order on the
+   * next sync (also trips a reorder).
+   */
+  get readingDirection() {
+    return this._readingDirection;
+  }
+  set readingDirection(dir) {
+    if (dir !== this._readingDirection) {
+      this._readingDirection = dir;
+      this.a11yNeedsReorder = true;
+    }
+  }
+  _readingDirection = "ltr";
   /** Cached media-query list; `.matches` is read live each frame. */
   reducedMotionQuery = null;
+  /** Cached `(forced-colors: active)` query (Windows High Contrast etc.). A
+   *  canvas gets NO automatic forced-colors treatment from the browser (it's
+   *  opaque pixels), so components must read {@link forcedColors} and repaint
+   *  with system colors themselves; a change listener repaints idle scenes. */
+  forcedColorsQuery = null;
+  forcedColorsChangeHandler = null;
   /** True when the OS asks for reduced motion and we respect it. Read by the animation drivers. */
   get prefersReducedMotion() {
     return this.respectReducedMotion && !!this.reducedMotionQuery?.matches;
   }
+  /**
+   * True when the OS is in a forced-colors mode (Windows High Contrast, and the
+   * `forced-colors: active` media feature generally). Canvas pixels are exempt
+   * from the browser's forced-colors remapping, so accessible components should
+   * read this and draw with CSS system colors (`CanvasText`, `Canvas`,
+   * `Highlight`, …) instead of their themed palette. Re-rendered automatically
+   * when the setting toggles.
+   */
+  get forcedColors() {
+    return !!this.forcedColorsQuery?.matches;
+  }
   /**
    * Throttle interval (ms) for the a11y/automation shadow sync. `0` = every
    * frame. See {@link SceneOptions.a11ySyncInterval}.
@@ -719,7 +1548,32 @@ var Scene = class _Scene {
   frameHadAnimation = true;
   frameHadInteractive = true;
   resizeHandler;
+  /** Active `(resolution: Ndppx)` media query watching for a runtime DPR change
+   *  (window moved between monitors, browser zoom) so the canvas backing store
+   *  can be re-scaled — otherwise it stays rasterized at the old DPR and blurs.
+   *  A resolution media query only fires when leaving its exact value, so the
+   *  handler re-arms a fresh query for the new DPR each time. */
+  dprMediaQuery = null;
+  /** For embedded (`disableWindowResize`) scenes: observes the canvas element so
+   *  a CSS/layout-driven size change re-runs `resize()`. A window `resize`
+   *  listener never fires for these (the window isn't what changed), so without
+   *  this an embedded canvas stayed at its initial size forever. */
+  canvasResizeObserver = null;
+  dprChangeHandler = null;
   focusedA11yElement = null;
+  /** Last geometry `syncOverlayGeometry` wrote, so an unchanged frame can skip the
+   *  style writes entirely. Reset to `null` to force the next sync (a new overlay
+   *  layer was created and has never been positioned). */
+  _overlayGeometry = null;
+  /** Shadow elements the pointer is currently inside. Lets a removal that happens
+   *  mid-hover synthesize the `pointerleave` the browser never sends for a
+   *  detached element, so the entity doesn't keep its hover state. */
+  hoveredA11yElements = /* @__PURE__ */ new WeakSet();
+  /** Persistent tabindex=-1 element in a11yRoot. When the focused a11y mirror is
+   *  pruned (virtualization/streaming/removal) while it holds focus, we move
+   *  focus here instead of letting the browser drop it to <body> — keeping the
+   *  screen-reader virtual cursor inside the scene's a11y region. */
+  focusSentinel = null;
   caretBlinkTimer = null;
   a11yNeedsReorder = true;
   portalRoot = null;
@@ -730,6 +1584,510 @@ var Scene = class _Scene {
   activePortalsPrevFrame = /* @__PURE__ */ new Set();
   portalEntities = /* @__PURE__ */ new Map();
   renderOrderCounter = 0;
+  /**
+   * Monotonic render-frame counter, bumped once per authoritative `render()`
+   * pass. Entities stamp their per-frame world-matrix cache with this value and
+   * {@link Entity.getWorldTransform} trusts that cache only while it still
+   * matches, so a query outside the frame that produced it transparently falls
+   * back to the ancestor walk. Public for the same reason `Entity._getTrig`/
+   * `_setWorldCache` are: it is a cross-class render-internal contract.
+   */
+  currentFrame = 0;
+  // ── WASM transform backend (invisible accelerator) ──────────────────────────
+  // When `_transformBackend === 'wasm'`, the main render walk sources each
+  // entity's world matrix from an SoA store composed by `_wasm` (see
+  // `renderNode`), instead of composing it in JS. The JS path is the permanent
+  // fallback and the default: a null backend, a non-main renderer, or any entity
+  // absent from the store all fall back to the JS composition, so WASM can only
+  // ever change *how fast* a world matrix is produced, never *what* it is.
+  _wasm = null;
+  _transformBackend = "js";
+  // Resident store state (Stage 3). The store layout — slot assignment + sibling
+  // runs — depends only on tree TOPOLOGY, so it is rebuilt only when the
+  // structure changes (add/remove/reparent bump `_structureVersion`). Between
+  // rebuilds the per-frame cost is: gather each entity's transform into the
+  // resident wasm input view + run the kernel — no reallocation, no readback.
+  _treeStore = null;
+  _slotEntity = [];
+  // store slot -> entity (also validates slots)
+  _wasmInputs = null;
+  _wasmWorld = null;
+  _structureVersion = 0;
+  _storeStructureVersion = -1;
+  // Cached list of ComputeParticleEntity instances in the tree, keyed by the
+  // structure version it was gathered at. Rebuilt only on a topology change.
+  _computeEntities = [];
+  _computeEntitiesVersion = -1;
+  /** Invalidate the resident WASM store layout; the next wasm-mode frame rebuilds
+   *  it. Called by `Entity.add`/`remove` (topology changes only). */
+  markStructureChanged() {
+    this._structureVersion++;
+  }
+  /** The tree's ComputeParticleEntity instances, cached per structure version so
+   *  a compute-free scene doesn't re-walk the whole tree every frame. */
+  _computeEntitiesFor(version) {
+    if (this._computeEntitiesVersion === version) return this._computeEntities;
+    const list = [];
+    const collect = (node) => {
+      if (node instanceof ComputeParticleEntity) list.push(node);
+      for (const child of node.children) collect(child);
+    };
+    collect(this.root);
+    for (const overlay of this.overlayRoot.children) collect(overlay);
+    this._computeEntities = list;
+    this._computeEntitiesVersion = version;
+    return list;
+  }
+  /** Which backend composes world matrices for the main render walk. */
+  get transformBackend() {
+    return this._transformBackend;
+  }
+  /**
+   * Install (or clear) a WASM transform backend. Passing a backend switches the
+   * main render walk onto it; passing `null` reverts to the JS path. Synchronous
+   * and safe to call between frames — the next `render()` picks it up. Prefer
+   * {@link enableWasmTransforms} for the normal async hot-swap.
+   */
+  setTransformBackend(backend) {
+    this._wasm = backend;
+    this._transformBackend = backend ? "wasm" : "js";
+  }
+  /**
+   * Asynchronously instantiate the WASM transform core and, on success, hot-swap
+   * the render walk onto it. Accepts whatever is convenient at the call site:
+   *
+   * ```ts
+   * // The common case — a bundler-emitted, co-located asset URL:
+   * await scene.enableWasmTransforms(new URL('./vectojs_core.wasm', import.meta.url));
+   * // …or a path string, a Response, or raw bytes you already have:
+   * await scene.enableWasmTransforms('/assets/vectojs_core.wasm');
+   * await scene.enableWasmTransforms(await fetch(url));
+   * await scene.enableWasmTransforms(myUint8Array);
+   * ```
+   *
+   * A URL/Response streams (compiles while it downloads, with a buffered
+   * fallback for a wrong MIME type); raw bytes instantiate directly. The Scene
+   * keeps rendering on the JS path until this resolves, and stays on JS if
+   * instantiation fails (CSP `wasm-unsafe-eval`, unsupported SIMD, corrupt or
+   * missing bytes, a 404) — failure is the default state, not an error path.
+   * 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);
+    return true;
+  }
+  // ── WASM hit-test backend (invisible accelerator, G3) ───────────────────────
+  // A separate WASM module instance from the transform backend (each crate
+  // export lives in independent linear memory per instance, so there is no
+  // shared-state hazard in running both) that indexes the main tree's world
+  // AABBs into a dense viewport grid for findEntityAt. The JS depth-first walk
+  // (findHitRecursively) is the permanent fallback: a null backend, a build
+  // that overflows its item budget, or the overlay tree (never indexed — small
+  // and rare, not worth accelerating) all fall through to it, so WASM can only
+  // 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).
+  _hitWasm = null;
+  // Cache key: which frame + structure version the grid was last (successfully,
+  // non-overflowing) built for. findEntityAt is called ad-hoc (pointer
+  // hover/click), not every frame, so the grid is refreshed lazily on demand
+  // rather than proactively every render() — unlike the transform store, which
+  // every frame's draw depends on.
+  _hitGridFrame = -1;
+  _hitGridOk = false;
+  _hitSlotEntity = [];
+  _hitBoundless = [];
+  /** Which backend answers `findEntityAt` for the main tree. */
+  get hitTestBackend() {
+    return this._hitWasm ? "wasm" : "js";
+  }
+  /** Install (or clear) a WASM hit-test backend directly. Prefer
+   *  {@link enableWasmHitTest} for the normal async hot-swap. */
+  setHitTestBackend(backend) {
+    this._hitWasm = backend;
+    this._hitGridFrame = -1;
+  }
+  /**
+   * Asynchronously instantiate the WASM hit-test core and, on success, hot-swap
+   * `findEntityAt` onto it. Accepts the same source shapes as
+   * {@link enableWasmTransforms} (URL, path string, Response, or raw bytes).
+   * Stays on the JS walk if instantiation fails — failure is the default
+   * 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);
+    return true;
+  }
+  /**
+   * Refresh the hit-test grid for the CURRENT tree state if it is stale (a
+   * structural or transform change may have happened since the last build —
+   * there is no cheap "nothing moved" shortcut for a spatial index the way
+   * there is for the transform store's topology-only run table, since ANY
+   * entity moving invalidates its AABB, not just add/remove/reparent; the
+   * measured build cost is cheap enough to redo per call). Returns `false`
+   * (grid untrustworthy — caller must use the JS walk) when there is no
+   * backend or the build overflowed its item budget.
+   */
+  _ensureHitGrid() {
+    const backend = this._hitWasm;
+    if (!backend) return false;
+    if (this._hitGridFrame === this.currentFrame) return this._hitGridOk;
+    const 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));
+    view.miny.set(gathered.miny.subarray(0, gathered.count));
+    view.maxx.set(gathered.maxx.subarray(0, gathered.count));
+    view.maxy.set(gathered.maxy.subarray(0, gathered.count));
+    const ok = backend.runBuild(gathered.count, this.width, this.height, 64);
+    this._hitSlotEntity = gathered.slotEntity;
+    this._hitBoundless = gathered.boundless;
+    this._hitGridFrame = this.currentFrame;
+    this._hitGridOk = ok;
+    return ok;
+  }
+  /**
+   * `findEntityAt`'s WASM-accelerated path for the main tree. Scans only the
+   * queried cell's candidates (confirming each against its own AABB and precise
+   * `isPointInside`) merged against the (typically empty or tiny) list of
+   * entities with no `getBounds()`, taking whichever confirmed match has the
+   * higher pre-order index — see hit-store.ts for why that is exactly
+   * equivalent to findHitRecursively's topmost-hit priority. Always
+   * conclusive: returns the correct entity or `null`, never "inconclusive".
+   */
+  _findEntityAtWasm(x, y) {
+    const backend = this._hitWasm;
+    const { minx, miny, maxx, maxy } = backend.inputView();
+    let bestIndex = -1;
+    let bestEntity = null;
+    const cell = backend.candidatesAt(x, y);
+    if (cell) {
+      for (let k = cell.length - 1; k >= 0; k--) {
+        const idx = cell[k];
+        if (x < minx[idx] || x > maxx[idx] || y < miny[idx] || y > maxy[idx]) continue;
+        const entity = this._hitSlotEntity[idx];
+        if (entity?.isPointInside(x, y) && this.isHitEligible(entity, x, y)) {
+          bestIndex = idx;
+          bestEntity = entity;
+          break;
+        }
+      }
+    }
+    for (const { entity, index } of this._hitBoundless) {
+      if (index > bestIndex && entity.isPointInside(x, y) && this.isHitEligible(entity, x, y)) {
+        bestIndex = index;
+        bestEntity = entity;
+      }
+    }
+    return bestEntity;
+  }
+  // ── WASM batched-animation backend (invisible accelerator, G2) ──────────────
+  // Advances every currently-active SpringDriver/TweenDriver in one WASM call
+  // each (spring_step/tween_step) instead of Entity.tickDrivers()'s per-driver
+  // JS loop. The JS tick loop is the permanent fallback: a null backend, a
+  // driver count below `animDriverGateCount`, or a TweenDriver using a custom
+  // EasingFn (which cannot cross into WASM) all fall through to it — WASM can
+  // only ever change *how* a driver is advanced, never *what* value it lands
+  // on.
+  _animWasm = null;
+  // Entities with at least one active driver, added by Entity._spawnDriver.
+  // Self-pruning: _tickBatchedDrivers drops an entry the first time it visits
+  // an entity whose drivers have since all completed or been removed. This is
+  // what lets the batch pass find its candidates in O(active drivers), not
+  // O(tree size) — the exact mistake G3's first integrated benchmark made.
+  _activeDriverEntities = /* @__PURE__ */ new Set();
+  // Reused across frames instead of allocating a fresh array + N {entity,prop,
+  // driver} objects every call — the integrated benchmark
+  // (benchmarks/anim-wasm-scene) found that allocation churn was the
+  // dominant integrated cost, not the wasm kernel itself. Parallel arrays,
+  // truncated to the live count after each use so a stale tail slot never
+  // pins a no-longer-active entity/driver in memory.
+  _springEntities = [];
+  _springProps = [];
+  _springDrivers = [];
+  _tweenEntities = [];
+  _tweenProps = [];
+  _tweenDrivers = [];
+  /**
+   * Minimum number of batchable (spring, or named-easing tween) active drivers
+   * before a frame engages the WASM batch path at all; below it, every driver
+   * ticks on the normal JS per-entity path, unmodified.
+   *
+   * Re-measured on the INTEGRATED path (benchmarks/anim-wasm-scene, real
+   * Chrome 150 / Firefox 153, 2026-07-24 — correctness verified 0 mismatches
+   * across all three kinds before any of these numbers were trusted): the
+   * isolated kernel spike's "<100 drivers, wins everywhere" verdict did NOT
+   * survive integration, and neither did the first integrated pass's single
+   * gate-count verdict once broken out by driver kind. On Chrome, spring and
+   * mixed drivers are a real ~1.4–2.3× win from n=128 up through the tested
+   * ceiling of 16384, but pure-tween drivers are a LOSS at n=128 (0.71×,
+   * i.e. ~40% slower than the JS path) and only turn net-positive around
+   * n≈256 (1.52×). A single scalar gate can't be tight for spring/mixed
+   * without occasionally opening early on a tween-heavy scene and making it
+   * slower — 256 is chosen to keep the gate net-positive across all three
+   * kinds rather than optimal for any one of them; a kind-aware gate (see
+   * `_tickBatchedDrivers`'s per-kind arrays, which already separate spring
+   * from tween) would recover the 128–255 spring/mixed win without the
+   * tween regression, but that's a larger change than this measurement pass
+   * covers. On Firefox it is a net loss at every driver count measured, up
+   * to 16384 — not an allocation artifact (confirmed after removing all
+   * per-frame allocation from the gather/scatter path); SpiderMonkey's
+   * wasm-boundary/property-dispatch cost for this shape of call appears to
+   * structurally exceed the saving, at least at the scales tested here.
+   *
+   * 256 is set as a Chrome-oriented default so an app that opts in (this
+   * path is never engaged without an explicit {@link enableWasmAnimBatching}
+   * call) sees the gate open only where it reliably helps on Chromium,
+   * regardless of whether the scene's active drivers are spring, tween, or
+   * a mix of both. Unlike G1 (safe to default on everywhere) and G3 (opt-in,
+   * but a reliable win once its own gate condition holds), G2 has no
+   * threshold that is safe on every engine — raise or lower this per your
+   * own target browser mix and driver-kind distribution, or leave WASM
+   * animation batching disabled entirely on a Firefox-heavy audience.
+   */
+  animDriverGateCount = 256;
+  /** 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'`. */
+  get animBackend() {
+    return this._animWasm ? "wasm" : "js";
+  }
+  /** Install (or clear) a WASM batched-animation backend directly. Prefer
+   *  {@link enableWasmAnimBatching} for the normal async hot-swap. */
+  setAnimBackend(backend) {
+    this._animWasm = backend;
+  }
+  /**
+   * Asynchronously instantiate the WASM batched-animation core and, on
+   * success, make it available to the per-frame gate (see
+   * {@link animDriverGateCount}). Accepts the same source shapes as
+   * {@link enableWasmTransforms}. Stays on the JS tick loop if instantiation
+   * fails — failure is the default state, not an error path. Resolves `true`
+   * 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);
+    return true;
+  }
+  // ── WASM particle CPU-sim backend (invisible accelerator, G4) ───────────────
+  // Advances a ComputeParticleEntity's whole buffer in one `particle_step` call
+  // (spring/mouse/explosion/integrate/bounce/life), replacing the per-particle
+  // JS `updateCPU` loop on the GPU-less fallback path. Measured ~2.1-2.5x on
+  // Chrome and ~1.4-2.0x on Firefox including the per-frame AoS<->SoA transpose
+  // (benchmarks/particle-wasm). f32 (matches the WGSL shader), bit-identical to
+  // a JS f32 reference oracle; updateCPU (f64) stays the permanent fallback when
+  // no backend is installed or a scene runs on WebGPU.
+  _particleWasm = null;
+  /** Which backend runs the CPU particle simulation. Reflects only whether a
+   *  backend is installed (the WebGPU compute path, when active, is used first
+   *  regardless). */
+  get particleSimBackend() {
+    return this._particleWasm ? "wasm" : "js";
+  }
+  /** Install (or clear) a WASM particle backend directly. Prefer
+   *  {@link enableWasmParticles} for the normal async hot-swap. */
+  setParticleBackend(backend) {
+    this._particleWasm = backend;
+  }
+  /**
+   * Asynchronously instantiate the WASM particle core and, on success, use it
+   * for the CPU particle fallback. Accepts the same source shapes as
+   * {@link enableWasmTransforms}. Stays on the JS `updateCPU` path if
+   * instantiation fails — failure is the default state, not an error path.
+   * 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);
+    return true;
+  }
+  /** Internal: called by `Entity._spawnDriver` when a new property driver
+   *  starts. See {@link _activeDriverEntities}. */
+  _registerActiveDriverEntity(entity) {
+    this._activeDriverEntities.add(entity);
+  }
+  /**
+   * Drop `entity` and its whole subtree from the batched-driver candidate set.
+   * Called by {@link remove}/{@link hideOverlay} on detach: without this a
+   * removed-but-still-animating entity stays pinned in the Set (a leak) and its
+   * drivers keep ticking every frame even though it is off-tree. If it is later
+   * re-added, {@link registerActiveDriverSubtree} re-registers any node that
+   * still has live drivers, so the motion resumes.
+   */
+  unregisterActiveDriverSubtree(entity) {
+    if (this._activeDriverEntities.size === 0) return;
+    const stack = [entity];
+    while (stack.length > 0) {
+      const node = stack.pop();
+      this._activeDriverEntities.delete(node);
+      for (const child of node.children) stack.push(child);
+    }
+  }
+  /**
+   * Re-register every node in `entity`'s subtree that still has live property
+   * drivers. Called by {@link add}/{@link showOverlay} so re-attaching a subtree
+   * that was removed mid-animation resumes its batched drivers (they were
+   * dropped from the candidate set on removal, but the driver state still lives
+   * on each entity).
+   */
+  registerActiveDriverSubtree(entity) {
+    const stack = [entity];
+    while (stack.length > 0) {
+      const node = stack.pop();
+      const entries = node._driverEntries();
+      if (entries && entries.size > 0) this._activeDriverEntities.add(node);
+      for (const child of node.children) stack.push(child);
+    }
+  }
+  /**
+   * Advance every registered entity's active drivers for this frame, batching
+   * whichever are batchable (`SpringDriver`; `TweenDriver` with a named
+   * easing) through one WASM call each when the driver-count gate is open, and
+   * ticking the rest (a `TweenDriver` using a custom `EasingFn`) directly in
+   * JS regardless of the gate. A "claimed" entity must have ALL its drivers
+   * advanced here so it can be safely stamped `_driversTickedFrame` — leaving
+   * one unclaimed would silently stall it, since `tickDrivers()` skips the
+   * whole entity once stamped.
+   *
+   * Must run before ANY entity's `update()`/`tickDrivers()` this frame (see
+   * the call site in {@link render}) — the same ordering constraint G1 Stage 4
+   * discovered: a value this pass writes must be final before anything reads
+   * it, including the JS-mode interleaved walk and the WASM-mode transform
+   * pre-pass.
+   */
+  _tickBatchedDrivers(dt) {
+    if (this._activeDriverEntities.size === 0) return;
+    let batchable = 0;
+    for (const entity of this._activeDriverEntities) {
+      const entries = entity._driverEntries();
+      if (!entries || entries.size === 0) {
+        this._activeDriverEntities.delete(entity);
+        continue;
+      }
+      for (const driver of entries.values()) {
+        if (driver instanceof SpringDriver) batchable++;
+        else if (driver instanceof TweenDriver && driver.wasmEasingId !== null) batchable++;
+      }
+    }
+    const backend = this._animWasm;
+    if (!backend || batchable < this.animDriverGateCount) return;
+    const sE = this._springEntities;
+    const sP = this._springProps;
+    const sD = this._springDrivers;
+    const tE = this._tweenEntities;
+    const tP = this._tweenProps;
+    const tD = this._tweenDrivers;
+    let springCount = 0;
+    let tweenCount = 0;
+    for (const entity of this._activeDriverEntities) {
+      const entries = entity._driverEntries();
+      for (const [prop, driver] of entries) {
+        if (driver instanceof SpringDriver) {
+          sE[springCount] = entity;
+          sP[springCount] = prop;
+          sD[springCount] = driver;
+          springCount++;
+        } else if (driver instanceof TweenDriver && driver.wasmEasingId !== null) {
+          tE[tweenCount] = entity;
+          tP[tweenCount] = prop;
+          tD[tweenCount] = driver;
+          tweenCount++;
+        } else {
+          driver.tick(dt);
+          entity._applyDriverTick(prop, driver);
+        }
+      }
+      entity._driversTickedFrame = this.currentFrame;
+    }
+    sE.length = springCount;
+    sP.length = springCount;
+    sD.length = springCount;
+    tE.length = tweenCount;
+    tP.length = tweenCount;
+    tD.length = tweenCount;
+    backend.ensure(springCount, tweenCount);
+    if (springCount > 0) {
+      const sv = backend.springView();
+      for (let i = 0; i < springCount; i++) {
+        const phys = sD[i].physics;
+        sv.val[i] = phys.value;
+        sv.target[i] = phys.target;
+        sv.vel[i] = phys.velocity;
+        sv.stiff[i] = phys.stiffness;
+        sv.damp[i] = phys.damping;
+        sv.mass[i] = phys.mass;
+      }
+      backend.stepSprings(dt, springCount);
+      for (let i = 0; i < springCount; i++) sD[i].syncExternal(sv.val[i], sv.vel[i]);
+    }
+    if (tweenCount > 0) {
+      const tv = backend.tweenView();
+      for (let i = 0; i < tweenCount; i++) {
+        const d = tD[i];
+        tv.from[i] = d.fromValue;
+        tv.to[i] = d.target;
+        tv.elapsed[i] = d.elapsedMs;
+        tv.dur[i] = d.durationMs;
+        tv.delay[i] = d.delayMs;
+        tv.ease[i] = d.wasmEasingId;
+      }
+      backend.stepTweens(dt, tweenCount);
+      for (let i = 0; i < tweenCount; i++) tD[i].syncExternal(tv.val[i], tv.elapsed[i]);
+    }
+    for (let i = 0; i < springCount; i++) sE[i]._applyDriverTick(sP[i], sD[i]);
+    for (let i = 0; i < tweenCount; i++) tE[i]._applyDriverTick(tP[i], tD[i]);
+  }
+  /**
+   * Compose the whole main tree's world matrices through the resident WASM store
+   * and return the world-matrix views for the render walk to read. Rebuilds the
+   * store layout (slots + runs) only when the tree structure changed since the
+   * last rebuild; otherwise it just gathers current transforms into the resident
+   * input view and runs the kernel. Returns `null` if there is no backend.
+   */
+  _syncWasmStore() {
+    const backend = this._wasm;
+    if (!backend) return null;
+    if (this._treeStore === null || this._storeStructureVersion !== this._structureVersion) {
+      const built = buildTreeStore(this.root);
+      const slotEntity2 = Array.from({ length: built.store.count });
+      for (const [entity, slot] of built.indexOf) {
+        slotEntity2[slot] = entity;
+        entity._storeSlot = slot;
+      }
+      backend.uploadRuns(built.store);
+      this._treeStore = built.store;
+      this._slotEntity = slotEntity2;
+      this._wasmInputs = backend.inputView();
+      this._wasmWorld = backend.worldView();
+      this._storeStructureVersion = this._structureVersion;
+    }
+    const inp = this._wasmInputs;
+    const slotEntity = this._slotEntity;
+    for (let slot = 1; slot < slotEntity.length; slot++) {
+      const e = slotEntity[slot];
+      inp.x[slot] = e.x;
+      inp.y[slot] = e.y;
+      inp.sx[slot] = e.scaleX;
+      inp.sy[slot] = e.scaleY;
+      const trig = e._getTrig();
+      inp.cos[slot] = trig.cos;
+      inp.sin[slot] = trig.sin;
+      inp.opacity[slot] = e.opacity;
+    }
+    backend.runKernel("simd");
+    return this._wasmWorld;
+  }
   /**
    * Authoritative paint order for semantic nodes discovered during the main
    * render. A node may not have a DOM projection until the following a11y
@@ -740,6 +2098,8 @@ var Scene = class _Scene {
   // Optional WebGL point-cloud layer (see SceneOptions.pointBackend).
   pointRenderer = null;
   glCanvas = null;
+  glContextLostHandler = null;
+  glContextRestoredHandler = null;
   debugA11y;
   width;
   height;
@@ -769,6 +2129,9 @@ var Scene = class _Scene {
   mouseY = -9999;
   pointerMoveListener = null;
   pointerLeaveListener = null;
+  /** Element the pointer listeners are bound to (parent container if present,
+   *  else the canvas). Stored so `destroy()` detaches from the same element. */
+  pointerEventTarget = null;
   hasWarnedZeroSize = false;
   fontLoadHandler = null;
   // ── Dev-mode warning infrastructure ──────────────────────────────
@@ -855,8 +2218,14 @@ var Scene = class _Scene {
     this.a11ySyncInterval = options.a11ySyncInterval ?? 0;
     this.contentProjectionEnabled = options.contentProjection ?? true;
     this.contentProjectionMargin = options.contentProjectionMargin;
+    this.readingDirection = options.readingDirection ?? "ltr";
     this._devActive = _Scene._devModeDetected();
     this.reducedMotionQuery = typeof window !== "undefined" && typeof window.matchMedia === "function" ? window.matchMedia("(prefers-reduced-motion: reduce)") : null;
+    if (typeof window !== "undefined" && typeof window.matchMedia === "function") {
+      this.forcedColorsQuery = window.matchMedia("(forced-colors: active)");
+      this.forcedColorsChangeHandler = () => this.markDirty();
+      this.forcedColorsQuery.addEventListener?.("change", this.forcedColorsChangeHandler);
+    }
     this.root = new class RootEntity extends Entity {
       isPointInside() {
         return false;
@@ -883,6 +2252,10 @@ var Scene = class _Scene {
         this.maxDPR
       );
     }
+    this.renderer.onContextRestored?.(() => {
+      this.markDirty();
+      if (this.renderer.isContextLost?.() !== true) this.render(this.renderer);
+    });
     if (typeof document !== "undefined") {
       this.a11yRoot = document.createElement("div");
       this.a11yRoot.style.position = "absolute";
@@ -894,6 +2267,15 @@ var Scene = class _Scene {
       this.a11yRoot.style.overflow = "hidden";
       this.a11yRoot.style.zIndex = "10";
       this.a11yRoot.style.userSelect = "text";
+      this.focusSentinel = document.createElement("div");
+      this.focusSentinel.setAttribute("data-vecto-focus-sentinel", "");
+      this.focusSentinel.tabIndex = -1;
+      this.focusSentinel.style.position = "absolute";
+      this.focusSentinel.style.width = "0";
+      this.focusSentinel.style.height = "0";
+      this.focusSentinel.style.outline = "none";
+      this.focusSentinel.style.overflow = "hidden";
+      this.a11yRoot.appendChild(this.focusSentinel);
       this.a11yRoot.addEventListener("mousedown", (e) => {
         if (e.button !== 0) return;
         const target = e.target;
@@ -1010,6 +2392,8 @@ var Scene = class _Scene {
         pr.resize(this.width, this.height);
         this.glCanvas = gl;
         this.pointRenderer = pr;
+        this._overlayGeometry = null;
+        this.setupGLContextRecovery(gl);
       } else {
         gl.remove();
       }
@@ -1028,6 +2412,61 @@ var Scene = class _Scene {
     }
     this.setupEvents();
   }
+  /**
+   * Arm a `(resolution: Ndppx)` media query for the current devicePixelRatio and
+   * re-apply the canvas scale when it changes. Such a query only fires when the
+   * DPR leaves its exact value, so on each change the old query is detached and
+   * a fresh one is armed for the new DPR. Re-runs `resize(width, height)` (which
+   * re-scales the backing store via the renderer) so text/vectors stay crisp
+   * after a monitor move or zoom. No-op without `matchMedia`.
+   */
+  watchDevicePixelRatio() {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
+    if (this.dprMediaQuery && this.dprChangeHandler) {
+      this.dprMediaQuery.removeEventListener?.("change", this.dprChangeHandler);
+    }
+    const dpr = window.devicePixelRatio || 1;
+    const query = window.matchMedia(`(resolution: ${dpr}dppx)`);
+    const handler = () => {
+      this.resize(this.width, this.height);
+      this.watchDevicePixelRatio();
+    };
+    query.addEventListener?.("change", handler);
+    this.dprMediaQuery = query;
+    this.dprChangeHandler = handler;
+  }
+  /**
+   * Recover the WebGL point layer from a GPU context loss (driver TDR reset,
+   * tab backgrounded on mobile, GPU switch). Two things are required:
+   *
+   *  1. The `webglcontextlost` handler MUST call `preventDefault()`, or the
+   *     browser never fires `webglcontextrestored` and the layer is blank
+   *     forever. While lost, the old renderer's GL calls are silently ignored,
+   *     so we drop it and the render loop simply skips the point layer.
+   *  2. On `webglcontextrestored`, all GL objects (programs, buffers, textures)
+   *     are gone, so we rebuild the renderer from scratch via `Scene.webglCreator`
+   *     on the same canvas, restore DPR/size, and repaint.
+   */
+  setupGLContextRecovery(gl) {
+    if (typeof gl.addEventListener !== "function") return;
+    this.glContextLostHandler = (e) => {
+      e.preventDefault();
+      this.pointRenderer?.destroy();
+      this.pointRenderer = null;
+    };
+    this.glContextRestoredHandler = () => {
+      if (this.destroyed || !this.glCanvas) return;
+      const pr = _Scene.webglCreator ? _Scene.webglCreator(this.glCanvas) : null;
+      if (pr) {
+        pr.maxDPR = this.maxDPR;
+        pr.resize(this.width, this.height);
+        this.pointRenderer = pr;
+        this.markDirty();
+      }
+    };
+    gl.addEventListener("webglcontextlost", this.glContextLostHandler);
+    gl.addEventListener("webglcontextrestored", this.glContextRestoredHandler);
+  }
   endContentSelectionDrag() {
     this.blankRegionSelectionDrag = false;
     this.contentSelectionAnchor = null;
@@ -1040,6 +2479,53 @@ var Scene = class _Scene {
     this.endContentSelectionDrag();
     selection?.removeAllRanges();
   }
+  /**
+   * Rebuild a content-projection element's DOM (`rebuild`) while preserving a
+   * text selection the user made inside it. A streaming message replaces its
+   * projection children on every appended chunk; without this, a selection in
+   * the UNCHANGED prefix is wiped on each frame ("can't select text in a
+   * message still receiving tokens"). We snapshot the selection's anchor/focus
+   * as linear character offsets within `el` before the rebuild and re-resolve
+   * them against the new DOM after, clamped to the new text length.
+   *
+   * Only fires when `el` owns the current selection and there is no active drag
+   * (mid-drag the browser is authoritative). The virtualization case — where
+   * `el` itself is removed from the DOM — is out of scope here (the node is
+   * genuinely freed; the browser clears the selection and there is nothing to
+   * restore against).
+   */
+  preserveContentSelectionAcrossRebuild(el, rebuild) {
+    const selection = typeof window !== "undefined" && typeof window.getSelection === "function" ? window.getSelection() : null;
+    const owns = !!selection && !this.blankRegionSelectionDrag && ((selection.anchorNode ? el.contains(selection.anchorNode) : false) || (selection.focusNode ? el.contains(selection.focusNode) : false));
+    if (!owns || !selection.anchorNode || !selection.focusNode) {
+      this.releaseContentSelectionForRebuild(el);
+      rebuild();
+      return;
+    }
+    const anchorNode = selection.anchorNode;
+    const focusNode = selection.focusNode;
+    const anchorOffset = anchorNode instanceof Text ? projectionAbsoluteOffset(el, {
+      node: anchorNode,
+      offset: selection.anchorOffset
+    }) : null;
+    const focusOffset = focusNode instanceof Text ? projectionAbsoluteOffset(el, {
+      node: focusNode,
+      offset: selection.focusOffset
+    }) : null;
+    this.endContentSelectionDrag();
+    selection.removeAllRanges();
+    rebuild();
+    if (anchorOffset === null || focusOffset === null) return;
+    const textLen = (el.textContent ?? "").length;
+    if (anchorOffset > textLen || focusOffset > textLen) return;
+    const anchor = projectionCaretAt(el, anchorOffset, "forward");
+    const focus = projectionCaretAt(el, focusOffset, "backward");
+    if (!anchor || !focus) return;
+    try {
+      selection.setBaseAndExtent(anchor.node, anchor.offset, focus.node, focus.offset);
+    } catch {
+    }
+  }
   /**
    * Expose the underlying {@link IRenderer} for advanced direct-draw operations.
    *
@@ -1068,6 +2554,7 @@ var Scene = class _Scene {
    */
   add(entity) {
     this.root.add(entity);
+    this.registerActiveDriverSubtree(entity);
     return this;
   }
   clearContentGridState(entityId, el) {
@@ -1090,6 +2577,7 @@ var Scene = class _Scene {
   }
   removeA11yRecursively(node) {
     if (node.isDOMPortal) {
+      node.releaseDOMBindings();
       node.domElement.remove();
       this.portalEntities.delete(node.id);
       this.activePortalsThisFrame.delete(node.id);
@@ -1111,6 +2599,11 @@ var Scene = class _Scene {
           this.caretBlinkTimer = null;
         }
       }
+      if (this.hoveredA11yElements.has(el)) {
+        this.hoveredA11yElements.delete(el);
+        node.dispatchEvent(new VectoJSEvent("pointerleave", node, void 0, false));
+      }
+      this.preserveFocusOnRemoval(el);
       el.remove();
       this.a11yElements.delete(node.id);
       this.a11yNeedsReorder = true;
@@ -1119,6 +2612,18 @@ var Scene = class _Scene {
       this.removeA11yRecursively(child);
     }
   }
+  /**
+   * If `el` is about to be removed from the DOM while it holds browser focus,
+   * move focus to the a11y focus sentinel first. Removing the active element
+   * otherwise drops focus to `<body>`, which pulls a screen reader out of the
+   * scene's a11y region and back to the top of the page — the classic
+   * "lost my place on scroll/stream" bug for virtualized/recycled controls.
+   */
+  preserveFocusOnRemoval(el) {
+    if (!this.focusSentinel || typeof document === "undefined") return;
+    if (document.activeElement !== el) return;
+    this.focusSentinel.focus({ preventScroll: true });
+  }
   /**
    * Remove a top-level entity from the scene graph and clean up its
    * accessibility shadow elements recursively.
@@ -1129,6 +2634,7 @@ var Scene = class _Scene {
   remove(entity) {
     this.root.remove(entity);
     this.removeA11yRecursively(entity);
+    this.unregisterActiveDriverSubtree(entity);
     return this;
   }
   /**
@@ -1148,6 +2654,7 @@ var Scene = class _Scene {
    */
   showOverlay(overlay) {
     this.overlayRoot.add(overlay);
+    this.registerActiveDriverSubtree(overlay);
     this.markDirty();
   }
   /**
@@ -1156,10 +2663,10 @@ var Scene = class _Scene {
   hideOverlay(overlay) {
     this.overlayRoot.remove(overlay);
     this.removeA11yRecursively(overlay);
+    this.unregisterActiveDriverSubtree(overlay);
     this.markDirty();
   }
   destroyEntitySubtree(entity) {
-    while (entity.children.length > 0) this.destroyEntitySubtree(entity.children.at(-1));
     entity.destroy();
   }
   /**
@@ -1179,20 +2686,36 @@ var Scene = class _Scene {
     if (typeof window !== "undefined" && !this.disableWindowResize) {
       window.removeEventListener("resize", this.resizeHandler);
     }
+    if (this.canvasResizeObserver) {
+      this.canvasResizeObserver.disconnect();
+      this.canvasResizeObserver = null;
+    }
+    if (this.dprMediaQuery && this.dprChangeHandler) {
+      this.dprMediaQuery.removeEventListener?.("change", this.dprChangeHandler);
+      this.dprMediaQuery = null;
+      this.dprChangeHandler = null;
+    }
+    if (this.forcedColorsQuery && this.forcedColorsChangeHandler) {
+      this.forcedColorsQuery.removeEventListener?.("change", this.forcedColorsChangeHandler);
+      this.forcedColorsQuery = null;
+      this.forcedColorsChangeHandler = null;
+    }
     if (typeof window !== "undefined" && this.contentSelectionEndListener) {
       window.removeEventListener("mouseup", this.contentSelectionEndListener);
       window.removeEventListener("blur", this.contentSelectionEndListener);
       this.contentSelectionEndListener = null;
     }
-    if (typeof window !== "undefined" && this.canvas && typeof this.canvas.removeEventListener === "function") {
+    if (typeof window !== "undefined" && this.pointerEventTarget && typeof this.pointerEventTarget.removeEventListener === "function") {
       if (this.pointerMoveListener) {
-        this.canvas.removeEventListener("pointermove", this.pointerMoveListener);
+        this.pointerEventTarget.removeEventListener("pointermove", this.pointerMoveListener);
       }
       if (this.pointerLeaveListener) {
-        this.canvas.removeEventListener("pointerleave", this.pointerLeaveListener);
+        this.pointerEventTarget.removeEventListener("pointerleave", this.pointerLeaveListener);
       }
+      this.pointerEventTarget = null;
     }
     this.a11yRoot?.remove();
+    this.focusSentinel = null;
     this.portalRoot?.remove();
     this.a11yElements.clear();
     for (const el of this.contentElements.values()) el.remove();
@@ -1206,6 +2729,16 @@ var Scene = class _Scene {
     for (const probe of this.contentGridCalibrationProbes.values()) probe.remove();
     this.contentGridCalibrationProbes.clear();
     this.endContentSelectionDrag();
+    if (this.glCanvas) {
+      if (this.glContextLostHandler) {
+        this.glCanvas.removeEventListener("webglcontextlost", this.glContextLostHandler);
+      }
+      if (this.glContextRestoredHandler) {
+        this.glCanvas.removeEventListener("webglcontextrestored", this.glContextRestoredHandler);
+      }
+    }
+    this.glContextLostHandler = null;
+    this.glContextRestoredHandler = null;
     this.pointRenderer?.destroy();
     this.renderer.dispose?.();
     this.glCanvas?.remove();
@@ -1228,7 +2761,20 @@ var Scene = class _Scene {
   setupEvents() {
     if (typeof window !== "undefined" && !this.disableWindowResize) {
       window.addEventListener("resize", this.resizeHandler);
+    } else if (this.disableWindowResize && typeof ResizeObserver !== "undefined" && this.canvas && typeof this.canvas.getBoundingClientRect === "function") {
+      this.canvasResizeObserver = new ResizeObserver((entries) => {
+        const entry = entries[0];
+        if (!entry) return;
+        const box = entry.contentRect;
+        const w = Math.round(box.width);
+        const h = Math.round(box.height);
+        if (w > 0 && h > 0 && (w !== this.width || h !== this.height)) {
+          this.resize(w, h);
+        }
+      });
+      this.canvasResizeObserver.observe(this.canvas);
     }
+    this.watchDevicePixelRatio();
     if (typeof window !== "undefined" && this.canvas && typeof this.canvas.addEventListener === "function") {
       this.pointerMoveListener = (e) => {
         const point = this.clientToScene(e.clientX, e.clientY);
@@ -1239,8 +2785,9 @@ var Scene = class _Scene {
         this.mouseX = -9999;
         this.mouseY = -9999;
       };
-      this.canvas.addEventListener("pointermove", this.pointerMoveListener);
-      this.canvas.addEventListener("pointerleave", this.pointerLeaveListener);
+      this.pointerEventTarget = this.canvas.parentElement ?? this.canvas;
+      this.pointerEventTarget.addEventListener("pointermove", this.pointerMoveListener);
+      this.pointerEventTarget.addEventListener("pointerleave", this.pointerLeaveListener);
     }
   }
   /**
@@ -1258,6 +2805,7 @@ var Scene = class _Scene {
     }
     this.isRunning = true;
     this.lastTime = typeof performance !== "undefined" ? performance.now() : 0;
+    this.watchCanvasVisibility();
     this.scheduleFrame();
     const isTextFocused = this.focusedA11yElement instanceof HTMLInputElement || this.focusedA11yElement instanceof HTMLTextAreaElement;
     if (isTextFocused && this.renderMode === "onDemand" && !this.caretBlinkTimer) {
@@ -1272,6 +2820,29 @@ var Scene = class _Scene {
       requestAnimationFrame((t) => this.loop(t));
     }
   }
+  /**
+   * Observe whether the canvas is on-screen so the rAF loop can pause when it
+   * scrolls fully out of view (a dashboard tab, a chart below the fold) and
+   * resume when it returns — instead of running the full update/render every
+   * frame for a scene nobody can see. No-op (stays "on screen") where
+   * `IntersectionObserver` is unavailable, so SSR/jsdom behavior is unchanged.
+   */
+  watchCanvasVisibility() {
+    if (this._canvasObserver || typeof IntersectionObserver === "undefined") return;
+    if (!this.canvas || typeof this.canvas.getBoundingClientRect !== "function") return;
+    this._canvasObserver = new IntersectionObserver((entries) => {
+      const entry = entries[entries.length - 1];
+      if (!entry) return;
+      const nowOnScreen = entry.isIntersecting;
+      const wasOffScreen = !this._canvasOnScreen;
+      this._canvasOnScreen = nowOnScreen;
+      if (nowOnScreen && wasOffScreen && this.isRunning) {
+        this.lastTime = typeof performance !== "undefined" ? performance.now() : 0;
+        this.scheduleFrame();
+      }
+    });
+    this._canvasObserver.observe(this.canvas);
+  }
   /**
    * Halt the render loop after the current frame completes.
    *
@@ -1283,6 +2854,11 @@ var Scene = class _Scene {
       clearInterval(this.caretBlinkTimer);
       this.caretBlinkTimer = null;
     }
+    if (this._canvasObserver) {
+      this._canvasObserver.disconnect();
+      this._canvasObserver = null;
+    }
+    this._canvasOnScreen = true;
   }
   /**
    * Manually advance the scene clock by `dt` milliseconds and render synchronously.
@@ -1373,6 +2949,7 @@ var Scene = class _Scene {
           }
         }
         if (el.parentNode === this.a11yRoot) {
+          this.preserveFocusOnRemoval(el);
           this.a11yRoot.removeChild(el);
         }
         this.a11yElements.delete(node.id);
@@ -1407,10 +2984,12 @@ var Scene = class _Scene {
         });
         el.addEventListener("mouseenter", (e) => {
           if (this.debugA11y) el.style.backgroundColor = "rgba(56, 189, 248, 0.2)";
+          this.hoveredA11yElements.add(el);
           node.dispatchEvent(new VectoJSEvent("hover", node, e, false));
         });
         el.addEventListener("mouseleave", (e) => {
           if (this.debugA11y) el.style.backgroundColor = "rgba(56, 189, 248, 0.05)";
+          this.hoveredA11yElements.delete(el);
           node.dispatchEvent(new VectoJSEvent("pointerleave", node, e, false));
         });
         const capEl = el;
@@ -1474,12 +3053,18 @@ var Scene = class _Scene {
           el.addEventListener("click", forward);
           el.addEventListener("select", forward);
           el.addEventListener("compositionstart", () => {
-            composition = { start: input.selectionStart ?? input.value.length, length: 0 };
+            composition = {
+              start: input.selectionStart ?? input.value.length,
+              length: 0
+            };
             forward();
           });
           el.addEventListener("compositionupdate", (e) => {
             const data = e.data ?? "";
-            composition = { start: composition?.start ?? 0, length: data.length };
+            composition = {
+              start: composition?.start ?? 0,
+              length: data.length
+            };
             forward();
           });
           el.addEventListener("compositionend", () => {
@@ -1593,6 +3178,31 @@ var Scene = class _Scene {
       this.syncOptionalAttribute(el, "aria-activedescendant", attrs.activedescendant);
       this.syncOptionalAttribute(el, "aria-valuemin", attrs.valuemin);
       this.syncOptionalAttribute(el, "aria-valuemax", attrs.valuemax);
+      this.syncOptionalAttribute(el, "aria-live", attrs.live);
+      this.syncOptionalAttribute(
+        el,
+        "aria-atomic",
+        attrs.atomic === void 0 ? void 0 : String(attrs.atomic)
+      );
+      this.syncOptionalAttribute(el, "aria-relevant", attrs.relevant);
+      this.syncOptionalAttribute(el, "aria-modal", attrs.ariaModal);
+      this.syncOptionalAttribute(el, "aria-labelledby", attrs.labelledby);
+      this.syncOptionalAttribute(el, "aria-describedby", attrs.describedby);
+      this.syncOptionalAttribute(
+        el,
+        "aria-required",
+        attrs.required === void 0 ? void 0 : String(attrs.required)
+      );
+      this.syncOptionalAttribute(
+        el,
+        "aria-invalid",
+        attrs.invalid === void 0 ? void 0 : String(attrs.invalid)
+      );
+      this.syncOptionalAttribute(
+        el,
+        "aria-level",
+        attrs.level === void 0 ? void 0 : String(attrs.level)
+      );
       if (attrs.value !== void 0) {
         if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
           if (el.value !== attrs.value) {
@@ -1624,13 +3234,18 @@ var Scene = class _Scene {
         el.style.width = `${this.width}px`;
         el.style.height = `${this.height}px`;
         el.style.transform = "";
+        if (el.style.display === "none") el.style.display = "";
       } else {
-        const { a, b, c, d, e, f } = node.getWorldTransform();
+        const worldTf = node.getWorldTransform();
+        const { a, b, c, d, e, f } = worldTf;
         el.style.left = `${e + node.a11yOffsetX}px`;
         el.style.top = `${f + node.a11yOffsetY}px`;
         el.style.width = `${node.width}px`;
         el.style.height = `${node.height}px`;
         el.style.transform = `matrix(${a}, ${b}, ${c}, ${d}, 0, 0)`;
+        const visible = this.projectionBoxVisible(node, worldTf, 0);
+        const display = visible ? "" : "none";
+        if (el.style.display !== display) el.style.display = display;
       }
     }
     this.syncContentProjection(node);
@@ -1698,26 +3313,24 @@ var Scene = class _Scene {
   }
   syncContentProjection(node) {
     if (!this.contentProjectionEnabled || !this.a11yRoot) return;
-    const projection = node.getContentProjection();
     let el = this.contentElements.get(node.id);
-    if (!projection || !projection.text) {
+    const releaseProjectionEl = () => {
       if (el) {
         this.clearContentGridState(node.id, el);
         el.remove();
         this.contentElements.delete(node.id);
         this.a11yNeedsReorder = true;
       }
-      return;
-    }
+    };
     const worldTf = node.getWorldTransform();
     const margin = this.contentProjectionMargin ?? this.height;
     if (Number.isFinite(margin) && !this.projectionBoxVisible(node, worldTf, margin)) {
-      if (el) {
-        this.clearContentGridState(node.id, el);
-        el.remove();
-        this.contentElements.delete(node.id);
-        this.a11yNeedsReorder = true;
-      }
+      releaseProjectionEl();
+      return;
+    }
+    const projection = node.getContentProjection();
+    if (!projection || !projection.text) {
+      releaseProjectionEl();
       return;
     }
     if (!el) {
@@ -1757,35 +3370,48 @@ var Scene = class _Scene {
         fallbackLineHeight: projection.lineHeight ?? 16
       });
       if (el.dataset.vectoProjectionLines !== signature) {
-        this.releaseContentSelectionForRebuild(el);
-        el.replaceChildren();
-        for (let index = 0; index < lines.length; index++) {
-          const line = lines[index];
-          const lineElement = document.createElement("span");
-          const lineFont = line.font ?? projection.font ?? "";
-          const lineHeight2 = line.lineHeight ?? projection.lineHeight ?? 16;
-          lineElement.style.position = "absolute";
-          lineElement.dir = "auto";
-          lineElement.style.left = `${line.x}px`;
-          lineElement.style.top = `${line.y + line.baseline - cssLineBoxBaseline(lineFont, lineHeight2)}px`;
-          lineElement.style.whiteSpace = "pre";
-          if (lineFont) lineElement.style.font = lineFont;
-          lineElement.style.lineHeight = `${lineHeight2}px`;
-          const separator = line.separatorAfter ?? (index < lines.length - 1 ? "\n" : "");
-          if (line.runs && line.runs.length > 0) {
-            for (let runIndex = 0; runIndex < line.runs.length; runIndex++) {
-              const run = line.runs[runIndex];
-              const runElement = document.createElement("span");
-              runElement.textContent = run.text + (runIndex === line.runs.length - 1 ? separator : "");
-              if (run.font) runElement.style.font = run.font;
-              runElement.style.lineHeight = `${lineHeight2}px`;
-              lineElement.appendChild(runElement);
+        this.preserveContentSelectionAcrossRebuild(el, () => {
+          el.replaceChildren();
+          for (let index = 0; index < lines.length; index++) {
+            const line = lines[index];
+            const lineElement = document.createElement("span");
+            const lineFont = line.font ?? projection.font ?? "";
+            const lineHeight2 = line.lineHeight ?? projection.lineHeight ?? 16;
+            const hasPositionedRuns = !!line.runs && line.runs.some((run) => run.x !== void 0);
+            lineElement.style.position = "absolute";
+            lineElement.dir = hasPositionedRuns ? "ltr" : "auto";
+            lineElement.style.left = `${line.x}px`;
+            lineElement.style.top = `${line.y + line.baseline - cssLineBoxBaseline(lineFont, lineHeight2)}px`;
+            lineElement.style.whiteSpace = "pre";
+            if (lineFont) lineElement.style.font = lineFont;
+            lineElement.style.lineHeight = `${lineHeight2}px`;
+            const separator = line.separatorAfter ?? (index < lines.length - 1 ? "\n" : "");
+            if (line.runs && line.runs.length > 0) {
+              const positioned = line.runs.some((run) => run.x !== void 0);
+              for (let runIndex = 0; runIndex < line.runs.length; runIndex++) {
+                const run = line.runs[runIndex];
+                const runElement = document.createElement("span");
+                runElement.textContent = run.text + (runIndex === line.runs.length - 1 ? separator : "");
+                if (run.font) runElement.style.font = run.font;
+                runElement.style.lineHeight = `${lineHeight2}px`;
+                if (positioned && run.x !== void 0) {
+                  runElement.style.position = "absolute";
+                  runElement.style.left = `${run.x - line.x}px`;
+                  runElement.style.top = "0";
+                  if (run.width !== void 0) runElement.style.width = `${run.width}px`;
+                  runElement.style.whiteSpace = "pre";
+                  runElement.style.verticalAlign = "top";
+                  runElement.style.unicodeBidi = "isolate";
+                  runElement.dir = "ltr";
+                }
+                lineElement.appendChild(runElement);
+              }
+            } else {
+              lineElement.textContent = line.text + separator;
             }
-          } else {
-            lineElement.textContent = line.text + separator;
+            el.appendChild(lineElement);
           }
-          el.appendChild(lineElement);
-        }
+        });
         el.dataset.vectoProjectionLines = signature;
       }
     } else {
@@ -2008,7 +3634,12 @@ var Scene = class _Scene {
       const source = document.createTextNode(sourceText);
       carrier.appendChild(source);
       probe.appendChild(carrier);
-      const measurement = { targets: [target], targetWidth, sourceLength, source };
+      const measurement = {
+        targets: [target],
+        targetWidth,
+        sourceLength,
+        source
+      };
       measurements.push(measurement);
       measurementsByKey.set(measurementKey, measurement);
     }
@@ -2107,6 +3738,7 @@ var Scene = class _Scene {
           }
         }
         if (el.parentNode === this.a11yRoot) {
+          this.preserveFocusOnRemoval(el);
           this.a11yRoot.removeChild(el);
         }
         this.a11yElements.delete(id);
@@ -2116,6 +3748,7 @@ var Scene = class _Scene {
       this.a11yNeedsReorder = true;
     }
     if (!this.a11yNeedsReorder) return;
+    this.sortNormalElementsVisually();
     const fullLen = this.fullViewportElements.length;
     const normalLen = this.normalElements.length;
     const totalLen = fullLen + normalLen;
@@ -2128,6 +3761,49 @@ var Scene = class _Scene {
     }
     this.a11yNeedsReorder = false;
   }
+  /**
+   * Reorder `normalElements` (in place) into visual reading order using the
+   * world positions `syncA11y` already wrote to each element's inline style
+   * (`top`/`left`/`height`). Elements are grouped into rows top-to-bottom (an
+   * element belongs to the current row while its top is above the row's
+   * running bottom edge), then sorted within a row by `left` — ascending for
+   * `'ltr'`, descending for `'rtl'`. The sort is stable, so entities at the
+   * same position keep their scene-graph (collection) order as a tiebreak.
+   */
+  sortNormalElementsVisually() {
+    const els = this.normalElements;
+    if (els.length < 2) return;
+    const rtl = this._readingDirection === "rtl";
+    const topOf = (el) => Number.parseFloat(el.style.top) || 0;
+    const leftOf = (el) => Number.parseFloat(el.style.left) || 0;
+    const heightOf = (el) => Math.max(Number.parseFloat(el.style.height) || 0, 4);
+    const order = els.map((el, i) => ({
+      el,
+      i,
+      top: topOf(el),
+      left: leftOf(el)
+    }));
+    order.sort((p, q) => p.top - q.top || p.i - q.i);
+    const sorted = [];
+    let rowStart = 0;
+    let rowBottom = order.length ? order[0].top + heightOf(order[0].el) : 0;
+    const flushRow = (end) => {
+      const row = order.slice(rowStart, end);
+      row.sort((p, q) => (rtl ? q.left - p.left : p.left - q.left) || p.i - q.i);
+      for (const r of row) sorted.push(r.el);
+    };
+    for (let k = 1; k < order.length; k++) {
+      if (order[k].top < rowBottom) {
+        rowBottom = Math.max(rowBottom, order[k].top + heightOf(order[k].el));
+      } else {
+        flushRow(k);
+        rowStart = k;
+        rowBottom = order[k].top + heightOf(order[k].el);
+      }
+    }
+    flushRow(order.length);
+    for (let i = 0; i < sorted.length; i++) els[i] = sorted[i];
+  }
   /** Keep DOM/WebGL overlay layers aligned with the canvas's CSS box. */
   syncOverlayGeometry() {
     const parent = this.canvas.parentElement;
@@ -2140,6 +3816,18 @@ var Scene = class _Scene {
     const top = (canvasRect?.top ?? 0) - (parentRect?.top ?? 0) - (parent.clientTop || 0) + parent.scrollTop;
     const scaleX = this.width > 0 ? cssWidth / this.width : 1;
     const scaleY = this.height > 0 ? cssHeight / this.height : 1;
+    const prev = this._overlayGeometry;
+    if (prev !== null && prev.left === left && prev.top === top && prev.cssWidth === cssWidth && prev.cssHeight === cssHeight && prev.width === this.width && prev.height === this.height) {
+      return;
+    }
+    this._overlayGeometry = {
+      left,
+      top,
+      cssWidth,
+      cssHeight,
+      width: this.width,
+      height: this.height
+    };
     for (const root of [this.a11yRoot, this.portalRoot]) {
       if (!root) continue;
       root.style.left = `${left}px`;
@@ -2207,6 +3895,7 @@ var Scene = class _Scene {
     if (portal.domElement.parentElement !== this.portalRoot) {
       this.portalRoot.appendChild(portal.domElement);
     }
+    portal.attachDOMBindings();
     if (!portal.domElement.hasAttribute("data-vecto-id")) {
       portal.domElement.setAttribute("data-vecto-id", portal.id);
     }
@@ -2247,6 +3936,7 @@ var Scene = class _Scene {
         const portal = this.portalEntities.get(oldId);
         if (portal) {
           if (portal.domElement.parentElement === this.portalRoot && (!portal.scene || portal.scene === this)) {
+            portal.releaseDOMBindings();
             portal.domElement.remove();
           }
           this.portalEntities.delete(oldId);
@@ -2269,6 +3959,7 @@ var Scene = class _Scene {
   }
   loop(time) {
     if (!this.isRunning) return;
+    if (!this._canvasOnScreen) return;
     let cap = this.effectiveMaxFPS();
     const isIdle = !this.dirty && !this.frameHadAnimation;
     if (isIdle && this.autoThrottle && this.renderMode === "always" && this.maxFPS > 0) {
@@ -2284,6 +3975,7 @@ var Scene = class _Scene {
       const nominal = 1e3 / cap;
       if (Math.abs(dt - nominal) < nominal * 0.3) dt = nominal;
     }
+    if (dt > _Scene.MAX_FRAME_DT) dt = _Scene.MAX_FRAME_DT;
     this.lastTime = time;
     if (this.renderMode === "onDemand" && isIdle) {
       this._skippedFrames++;
@@ -2327,6 +4019,7 @@ var Scene = class _Scene {
    * @param time - Current absolute time in milliseconds (default 0).
    */
   render(renderer, dt = 0, time = 0) {
+    if (renderer.isContextLost?.()) return;
     const isMainRenderer = renderer === this.renderer;
     if (isMainRenderer && this.a11yRoot && this.canvas.parentElement) {
       const parentStyle = this.canvas.parentElement.style;
@@ -2336,23 +4029,13 @@ var Scene = class _Scene {
       this.syncOverlayGeometry();
     }
     if (isMainRenderer) {
+      this.currentFrame++;
       this.renderOrderCounter = 0;
       this.a11yRenderOrders.clear();
       this.activePortalsThisFrame.clear();
+      this._tickBatchedDrivers(dt);
     }
-    const computeEntities = [];
-    const collectComputeEntities = (node) => {
-      if (node instanceof ComputeParticleEntity) {
-        computeEntities.push(node);
-      }
-      for (const child of node.children) {
-        collectComputeEntities(child);
-      }
-    };
-    collectComputeEntities(this.root);
-    for (const overlay of this.overlayRoot.children) {
-      collectComputeEntities(overlay);
-    }
+    const computeEntities = this._computeEntitiesFor(this._structureVersion);
     if (computeEntities.length > 0) {
       const isMainRenderPath = renderer === this.renderer;
       if (isMainRenderPath && !this.device && !this.webgpuDisabled && !this.initializingWebGPU && !this.deviceLost) {
@@ -2450,7 +4133,11 @@ var Scene = class _Scene {
               my = -9999;
             }
           }
-          entity.updateCPU(dt / 1e3, mx, my, this.width, this.height);
+          if (this._particleWasm) {
+            entity.stepWithBackend(this._particleWasm, dt / 1e3, mx, my, this.width, this.height);
+          } else {
+            entity.updateCPU(dt / 1e3, mx, my, this.width, this.height);
+          }
         }
       }
     } else if (isMainRenderer) {
@@ -2464,31 +4151,69 @@ var Scene = class _Scene {
     const vh = this.height;
     let walkHadAnimation = false;
     let walkHadInteractive = false;
-    const renderNode = (node, pa, pb, pc, pd, pe, pf, parentOpacity) => {
-      if (isMainRenderer) {
+    const runUpdate = (node) => {
+      const overridesUpdate = node.update !== Entity.prototype.update;
+      let pending = node.hasPendingAnimations();
+      if (pending || overridesUpdate) {
         node.update(dt, time);
-        if (!walkHadAnimation && node.hasPendingAnimations()) walkHadAnimation = true;
-        if (!walkHadInteractive && node.interactive) walkHadInteractive = true;
-        if (this._devActive && this._devFrameCount % 120 === 0) {
-          if (node.update !== Entity.prototype.update && node.hasPendingAnimations === Entity.prototype.hasPendingAnimations) {
-            this._devWarn(
-              `Entity "${node.id}" overrides update() but not hasPendingAnimations(). Custom motion in update() without overriding hasPendingAnimations() causes the idle throttle to drop the animation to ~2fps. Override hasPendingAnimations() to return true while motion is in flight.`
-            );
-          }
+        pending = node.hasPendingAnimations();
+      }
+      if (pending) walkHadAnimation = true;
+      if (!walkHadInteractive && node.interactive) walkHadInteractive = true;
+      if (this._devActive && this._devFrameCount % 120 === 0) {
+        if (overridesUpdate && node.hasPendingAnimations === Entity.prototype.hasPendingAnimations) {
+          this._devWarn(
+            `Entity "${node.id}" overrides update() but not hasPendingAnimations(). Custom motion in update() without overriding hasPendingAnimations() causes the idle throttle to drop the animation to ~2fps. Override hasPendingAnimations() to return true while motion is in flight.`
+          );
         }
       }
-      const cos = Math.cos(node.rotation);
-      const sin = Math.sin(node.rotation);
-      const te = pa * node.x + pc * node.y + pe;
-      const tf = pb * node.x + pd * node.y + pf;
-      const sxCos = node.scaleX * cos;
-      const sxSin = node.scaleX * sin;
-      const syCos = node.scaleY * cos;
-      const sySin = node.scaleY * sin;
-      const a = pa * sxCos + pc * sySin;
-      const b = pb * sxCos + pd * sySin;
-      const c = pa * -sxSin + pc * syCos;
-      const d = pb * -sxSin + pd * syCos;
+    };
+    const wasmMain = isMainRenderer && this._wasm !== null && this._transformBackend === "wasm";
+    if (wasmMain) {
+      const updateWalk = (node) => {
+        runUpdate(node);
+        const kids = node.children;
+        for (let i = 0; i < kids.length; i++) updateWalk(kids[i]);
+      };
+      updateWalk(this.root);
+      for (const overlay of this.overlayRoot.children) updateWalk(overlay);
+    }
+    const wasmWorld = wasmMain ? this._syncWasmStore() : null;
+    const wasmSlotEntity = this._slotEntity;
+    const renderNode = (node, pa, pb, pc, pd, pe, pf, parentOpacity) => {
+      if (isMainRenderer && !wasmMain) {
+        runUpdate(node);
+      }
+      let a;
+      let b;
+      let c;
+      let d;
+      let te;
+      let tf;
+      const slot = node._storeSlot;
+      if (wasmWorld !== null && slot >= 0 && wasmSlotEntity[slot] === node) {
+        a = wasmWorld.wa[slot];
+        b = wasmWorld.wb[slot];
+        c = wasmWorld.wc[slot];
+        d = wasmWorld.wd[slot];
+        te = wasmWorld.we[slot];
+        tf = wasmWorld.wf[slot];
+      } else {
+        const trig = node._getTrig();
+        const cos = trig.cos;
+        const sin = trig.sin;
+        te = pa * node.x + pc * node.y + pe;
+        tf = pb * node.x + pd * node.y + pf;
+        const sxCos = node.scaleX * cos;
+        const sxSin = node.scaleX * sin;
+        const syCos = node.scaleY * cos;
+        const sySin = node.scaleY * sin;
+        a = pa * sxCos + pc * sySin;
+        b = pb * sxCos + pd * sySin;
+        c = pa * -sxSin + pc * syCos;
+        d = pb * -sxSin + pd * syCos;
+      }
+      if (isMainRenderer) node._setWorldCache(a, b, c, d, te, tf, this.currentFrame);
       const worldScaleX = Math.hypot(a, b);
       const worldScaleY = Math.hypot(c, d);
       const worldOpacity = parentOpacity * node.opacity;
@@ -2637,12 +4362,25 @@ var Scene = class _Scene {
       this.pointRenderer.maxDPR = this.maxDPR;
       this.pointRenderer.resize(width, height);
     }
-    if (this.gpuCanvas) {
-      this.gpuCanvas.width = width;
-      this.gpuCanvas.height = height;
-    }
+    if (this.gpuCanvas) this.sizeGpuCanvas(this.gpuCanvas, width, height);
     this.markDirty();
   }
+  /** Effective device pixel ratio, matching CanvasRenderer: real DPR clamped to
+   *  `maxDPR` when set. */
+  effectiveDPR() {
+    const real = typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1;
+    return this.maxDPR !== void 0 ? Math.min(real, this.maxDPR) : real;
+  }
+  /** Size the WebGPU particle canvas: backing store at logical × DPR, CSS box at
+   *  the logical size. Sizing the backing store in logical px (the old
+   *  behavior) left it rasterized at 1× and CSS-stretched — blurry on HiDPI. */
+  sizeGpuCanvas(gpuCanvas, width, height) {
+    const dpr = this.effectiveDPR();
+    gpuCanvas.width = Math.max(1, Math.round(width * dpr));
+    gpuCanvas.height = Math.max(1, Math.round(height * dpr));
+    gpuCanvas.style.width = `${width}px`;
+    gpuCanvas.style.height = `${height}px`;
+  }
   /**
    * Gets the accessibility DOM element projected for the given entity ID.
    */
@@ -2665,6 +4403,9 @@ var Scene = class _Scene {
   findEntityAt(x, y) {
     const overlayHit = this.findHitRecursively(this.overlayRoot, x, y);
     if (overlayHit) return overlayHit;
+    if (this._hitWasm && this._ensureHitGrid()) {
+      return this._findEntityAtWasm(x, y);
+    }
     return this.findHitRecursively(this.root, x, y);
   }
   /** Submit one transparent clear pass when particle content lingers on the GPU canvas. */
@@ -2699,8 +4440,7 @@ var Scene = class _Scene {
     const device = await adapter.requestDevice();
     if (typeof document !== "undefined" && !this.gpuCanvas) {
       const gpuCanvas = document.createElement("canvas");
-      gpuCanvas.width = this.width;
-      gpuCanvas.height = this.height;
+      this.sizeGpuCanvas(gpuCanvas, this.width, this.height);
       gpuCanvas.style.position = "absolute";
       gpuCanvas.style.top = "0";
       gpuCanvas.style.left = "0";
@@ -2710,6 +4450,7 @@ var Scene = class _Scene {
         this.canvas.parentElement.appendChild(gpuCanvas);
       }
       this.gpuCanvas = gpuCanvas;
+      this._overlayGeometry = null;
       this.gpuContext = gpuCanvas.getContext("webgpu");
     }
     if (this.gpuContext) {
@@ -2806,17 +4547,68 @@ var Scene = class _Scene {
       }
     }
   }
-  findHitRecursively(node, x, y) {
+  findHitRecursively(node, x, y, clip = null) {
+    if (node.opacity <= 0) return null;
+    let childClip = clip;
+    if (node.clipChildren) {
+      const box = node.getWorldBounds();
+      childClip = clip ? intersectBounds(clip, box) : box;
+    }
     for (let i = node.children.length - 1; i >= 0; i--) {
-      const hit = this.findHitRecursively(node.children[i], x, y);
+      const hit = this.findHitRecursively(node.children[i], x, y, childClip);
       if (hit) return hit;
     }
-    if (node.isPointInside && node.isPointInside(x, y)) {
+    if (node.isPointInside && node.isPointInside(x, y) && (!clip || pointInBounds(clip, x, y)) && !this.isPointerTransparent(node)) {
       return node;
     }
     return null;
   }
+  /** Whether `node` opts out of being a pointer hit target: a disabled control
+   *  or an explicit `pointerEvents: 'none'` in its a11y attributes. Its children
+   *  are still walked (a transparent container can hold hittable descendants). */
+  isPointerTransparent(node) {
+    const attrs = node.getA11yAttributes();
+    return attrs.disabled === true || attrs.pointerEvents === "none";
+  }
+  /**
+   * Whether a confirmed geometric hit on `node` at world `(x, y)` is a REAL hit,
+   * applying the same visibility/input gating as {@link findHitRecursively} but
+   * from a flat candidate (the WASM grid has no recursion clip-stack): the node
+   * and all ancestors are visible (`opacity > 0`), the point lies inside every
+   * `clipChildren` ancestor's world box, and the node isn't pointer-transparent
+   * (disabled / `pointerEvents: 'none'`). Keeps the WASM and JS hit paths in
+   * lockstep so they return the same entity.
+   */
+  isHitEligible(node, x, y) {
+    if (this.isPointerTransparent(node)) return false;
+    if (node.opacity <= 0) return false;
+    for (let ancestor = node.parent; ancestor; ancestor = ancestor.parent) {
+      if (ancestor.opacity <= 0) return false;
+      if (ancestor.clipChildren && ancestor.width > 0 && ancestor.height > 0) {
+        const local = ancestor.worldToLocal(x, y);
+        if (!local || local.x < 0 || local.y < 0 || local.x > ancestor.width || local.y > ancestor.height) {
+          return false;
+        }
+      }
+    }
+    return true;
+  }
 };
+function intersectBounds(a, b) {
+  const x = Math.max(a.x, b.x);
+  const y = Math.max(a.y, b.y);
+  const right = Math.min(a.x + a.width, b.x + b.width);
+  const bottom = Math.min(a.y + a.height, b.y + b.height);
+  return {
+    x,
+    y,
+    width: Math.max(0, right - x),
+    height: Math.max(0, bottom - y)
+  };
+}
+function pointInBounds(b, x, y) {
+  return x >= b.x && x <= b.x + b.width && y >= b.y && y <= b.y + b.height;
+}
 
 // src/components/TextEntity.ts
 import {
@@ -3456,6 +5248,7 @@ var DOMPortalEntity = class extends Entity {
   isDOMPortal = true;
   domListeners = [];
   resizeObserver = null;
+  domBound = false;
   cachedWidth = 100;
   cachedHeight = 100;
   lastWidth = "";
@@ -3474,50 +5267,84 @@ var DOMPortalEntity = class extends Entity {
       this.domElement.style.pointerEvents = "auto";
       this.cachedWidth = parseFloat(domElement.style.width) || domElement.offsetWidth || 100;
       this.cachedHeight = parseFloat(domElement.style.height) || domElement.offsetHeight || 100;
-      if (typeof ResizeObserver !== "undefined") {
-        this.resizeObserver = new ResizeObserver((entries) => {
-          for (const entry of entries) {
-            this.cachedWidth = entry.contentRect.width || entry.target.offsetWidth;
-            this.cachedHeight = entry.contentRect.height || entry.target.offsetHeight;
-          }
-        });
-        this.resizeObserver.observe(this.domElement);
-      }
-      const events = [
-        "click",
-        "pointerdown",
-        "pointerup",
-        "pointercancel",
-        "pointermove",
-        "wheel"
-      ];
-      for (const type of events) {
-        const handler = (e) => {
-          this.dispatchEvent(new VectoJSEvent(type, this, e));
-        };
-        this.domElement.addEventListener(type, handler);
-        this.domListeners.push({ type, handler, capture: false });
-      }
-      const hoverEvents = [
-        { native: "mouseenter", vecto: "hover" },
-        { native: "mouseleave", vecto: "pointerleave" }
-      ];
-      for (const { native, vecto } of hoverEvents) {
-        const handler = (e) => {
-          this.dispatchEvent(new VectoJSEvent(vecto, this, e, false));
-        };
-        this.domElement.addEventListener(native, handler);
-        this.domListeners.push({ type: native, handler, capture: false });
-      }
-      const focusEvents = ["focus", "blur"];
-      for (const type of focusEvents) {
-        const handler = (e) => {
-          this.dispatchEvent(new VectoJSEvent(type, this, e, true));
-        };
-        this.domElement.addEventListener(type, handler, true);
-        this.domListeners.push({ type, handler, capture: true });
+      this.attachDOMBindings();
+    }
+  }
+  /**
+   * Attach the ResizeObserver + DOM event listeners that bridge native DOM
+   * events into the Vecto event system. Idempotent: safe to call every frame
+   * from the projection path (`Scene.syncPortalGeometry`), which is what lets a
+   * portal survive a `scene.remove()` -> re-add cycle — {@link releaseDOMBindings}
+   * tears these down on removal and the next projection re-attaches them.
+   */
+  attachDOMBindings() {
+    if (this.domBound || typeof window === "undefined") return;
+    this.domBound = true;
+    if (typeof ResizeObserver !== "undefined") {
+      this.resizeObserver = new ResizeObserver((entries) => {
+        for (const entry of entries) {
+          this.cachedWidth = entry.contentRect.width || entry.target.offsetWidth;
+          this.cachedHeight = entry.contentRect.height || entry.target.offsetHeight;
+        }
+      });
+      this.resizeObserver.observe(this.domElement);
+    }
+    const events = [
+      "click",
+      "pointerdown",
+      "pointerup",
+      "pointercancel",
+      "pointermove",
+      "wheel"
+    ];
+    for (const type of events) {
+      const handler = (e) => {
+        this.dispatchEvent(new VectoJSEvent(type, this, e));
+      };
+      this.domElement.addEventListener(type, handler);
+      this.domListeners.push({ type, handler, capture: false });
+    }
+    const hoverEvents = [
+      { native: "mouseenter", vecto: "hover" },
+      { native: "mouseleave", vecto: "pointerleave" }
+    ];
+    for (const { native, vecto } of hoverEvents) {
+      const handler = (e) => {
+        this.dispatchEvent(new VectoJSEvent(vecto, this, e, false));
+      };
+      this.domElement.addEventListener(native, handler);
+      this.domListeners.push({ type: native, handler, capture: false });
+    }
+    const focusEvents = ["focus", "blur"];
+    for (const type of focusEvents) {
+      const handler = (e) => {
+        this.dispatchEvent(new VectoJSEvent(type, this, e, true));
+      };
+      this.domElement.addEventListener(type, handler, true);
+      this.domListeners.push({ type, handler, capture: true });
+    }
+  }
+  /**
+   * Disconnect the ResizeObserver and remove the DOM event listeners, without
+   * touching the scene graph or the element's DOM parentage. Called on the
+   * `scene.remove()` path so a detached portal doesn't leak an observer that
+   * keeps its element alive and firing; the element itself is removed from the
+   * document by the scene's portal pruning. Re-attached lazily on the next
+   * projection frame via {@link attachDOMBindings}.
+   */
+  releaseDOMBindings() {
+    if (!this.domBound) return;
+    this.domBound = false;
+    if (this.resizeObserver) {
+      this.resizeObserver.disconnect();
+      this.resizeObserver = null;
+    }
+    if (this.domElement) {
+      for (const { type, handler, capture } of this.domListeners) {
+        this.domElement.removeEventListener(type, handler, capture);
       }
     }
+    this.domListeners = [];
   }
   isPointInside(globalX, globalY) {
     const w = this.width > 0 ? this.width : this.cachedWidth;
@@ -3533,18 +5360,9 @@ var DOMPortalEntity = class extends Entity {
   render() {
   }
   destroy() {
-    if (typeof window !== "undefined") {
-      if (this.resizeObserver) {
-        this.resizeObserver.disconnect();
-        this.resizeObserver = null;
-      }
-      if (this.domElement) {
-        for (const { type, handler, capture } of this.domListeners) {
-          this.domElement.removeEventListener(type, handler, capture);
-        }
-        this.domListeners = [];
-        this.domElement.remove();
-      }
+    this.releaseDOMBindings();
+    if (typeof window !== "undefined" && this.domElement) {
+      this.domElement.remove();
     }
     super.destroy();
   }