@vectojs/core 1.22.0 → 1.24.0

package/dist/index.mjs

@@ -8,7 +8,7 @@ import {
   isSafeUrl,
   parseColorToRGBA,
   sanitizeUrl
-} from "./chunk-UPULSLKA.mjs";
+} from "./chunk-ME4LB2HB.mjs";
 import {
   Entity,
   MSDFTextEntity,
@@ -307,12 +307,16 @@ var ComputeParticleEntity = class extends Entity {
    * 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.
+   *
+   * Returns `false` if the kernel declined the call and {@link updateCPU} ran
+   * instead, so the Scene can report which path actually simulated this frame
+   * rather than assuming an installed backend did the work.
    */
   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, {
+    const pending = backend.step(count, {
       dt,
       mouseX,
       mouseY,
@@ -324,8 +328,14 @@ var ComputeParticleEntity = class extends Entity {
       maxVelocity: this.maxVelocity,
       explosion: this.pendingExplosion
     });
+    if (pending === null) {
+      this.updateCPU(dt, mouseX, mouseY, width, height);
+      return false;
+    }
+    this._wasmPending = pending;
     backend.scatter(this.particleData, count);
     this.pendingExplosion = null;
+    return true;
   }
   destroy() {
     this.destroyGPUResources();
@@ -469,148 +479,6 @@ function buildTreeStore(root) {
   return { store, indexOf };
 }
 
-// src/wasm/hit-store.ts
-function gatherHitAABBs(root, currentFrame) {
-  const slotEntity = [];
-  const boundless = [];
-  const minxs = [];
-  const minys = [];
-  const maxxs = [];
-  const maxys = [];
-  const scratch = { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 };
-  const visit = (node) => {
-    const index = slotEntity.length;
-    slotEntity.push(node);
-    const bounds = node.getBounds();
-    if (bounds === null) {
-      boundless.push({ entity: node, index });
-      minxs.push(0);
-      minys.push(0);
-      maxxs.push(0);
-      maxys.push(0);
-    } else {
-      if (!node._readWorldCache(currentFrame, scratch)) {
-        const t = node.getWorldTransform();
-        scratch.a = t.a;
-        scratch.b = t.b;
-        scratch.c = t.c;
-        scratch.d = t.d;
-        scratch.e = t.e;
-        scratch.f = t.f;
-      }
-      const { a, b, c, d, e, f } = scratch;
-      let minX = Infinity;
-      let minY = Infinity;
-      let maxX = -Infinity;
-      let maxY = -Infinity;
-      for (let i = 0; i < 4; i++) {
-        const lx = i & 1 ? bounds.x + bounds.width : bounds.x;
-        const ly = i & 2 ? bounds.y + bounds.height : bounds.y;
-        const wx = a * lx + c * ly + e;
-        const wy = b * lx + d * ly + f;
-        if (wx < minX) minX = wx;
-        if (wx > maxX) maxX = wx;
-        if (wy < minY) minY = wy;
-        if (wy > maxY) maxY = wy;
-      }
-      minxs.push(minX);
-      minys.push(minY);
-      maxxs.push(maxX);
-      maxys.push(maxY);
-    }
-    const kids = node.children;
-    for (let i = 0; i < kids.length; i++) visit(kids[i]);
-  };
-  visit(root);
-  return {
-    count: slotEntity.length,
-    slotEntity,
-    boundless,
-    minx: Float64Array.from(minxs),
-    miny: Float64Array.from(minys),
-    maxx: Float64Array.from(maxxs),
-    maxy: Float64Array.from(maxys)
-  };
-}
-
-// src/wasm/hit-store-fused.ts
-function gatherHitAABBsFromStore(root, aabbs, storeSlotEntity, out) {
-  const slotEntity = out.slotEntity;
-  const boundless = out.boundless;
-  slotEntity.length = 0;
-  boundless.length = 0;
-  let count = 0;
-  let capacity = out.minx.length;
-  let minx = out.minx;
-  let miny = out.miny;
-  let maxx = out.maxx;
-  let maxy = out.maxy;
-  const grow = (needed) => {
-    if (needed <= capacity) return;
-    let next = capacity || 256;
-    while (next < needed) next *= 2;
-    const nminx = new Float64Array(next);
-    const nminy = new Float64Array(next);
-    const nmaxx = new Float64Array(next);
-    const nmaxy = new Float64Array(next);
-    nminx.set(minx);
-    nminy.set(miny);
-    nmaxx.set(maxx);
-    nmaxy.set(maxy);
-    minx = nminx;
-    miny = nminy;
-    maxx = nmaxx;
-    maxy = nmaxy;
-    capacity = next;
-  };
-  let bailed = false;
-  const visit = (node) => {
-    if (bailed) return;
-    const index = count;
-    slotEntity.push(node);
-    count++;
-    grow(count);
-    if (node.getBounds() === null) {
-      boundless.push({ entity: node, index });
-      minx[index] = 0;
-      miny[index] = 0;
-      maxx[index] = 0;
-      maxy[index] = 0;
-    } else {
-      const slot = node._storeSlot;
-      if (slot < 0 || slot >= aabbs.aminx.length || storeSlotEntity[slot] !== node) {
-        bailed = true;
-        return;
-      }
-      minx[index] = aabbs.aminx[slot];
-      miny[index] = aabbs.aminy[slot];
-      maxx[index] = aabbs.amaxx[slot];
-      maxy[index] = aabbs.amaxy[slot];
-    }
-    const children = node.children;
-    for (let i = 0; i < children.length; i++) visit(children[i]);
-  };
-  visit(root);
-  if (bailed) return null;
-  out.count = count;
-  out.minx = minx;
-  out.miny = miny;
-  out.maxx = maxx;
-  out.maxy = maxy;
-  return out;
-}
-function createHitGatherBuffer() {
-  return {
-    count: 0,
-    slotEntity: [],
-    boundless: [],
-    minx: new Float64Array(256),
-    miny: new Float64Array(256),
-    maxx: new Float64Array(256),
-    maxy: new Float64Array(256)
-  };
-}
-
 // src/wasm/backend.ts
 var WASM_STATUS = {
   OK: 0,
@@ -703,7 +571,10 @@ var WasmTransformBackend = class {
     return status;
   }
   /** Upload only the run table + count (topology), leaving per-entity inputs to
-   *  the resident views. Call when the tree structure changes, not per frame. */
+   *  the resident views. Call when the tree structure changes, not per frame.
+   *  Returns `false` if the crate rejected the run count, in which case the
+   *  PREVIOUS topology is still published and any kernel run against it would
+   *  compose the wrong tree — the caller must not proceed. */
   uploadRuns(store) {
     this.ensure(store.count, store.runCount);
     const rc = store.runCount;
@@ -711,6 +582,7 @@ var WasmTransformBackend = class {
     this.vrs.set(store.runStart.subarray(0, rc));
     this.vrl.set(store.runLen.subarray(0, rc));
     this.lastStatus = this.ex.set_run_count(rc);
+    return this.lastStatus === WASM_STATUS.OK;
   }
   /**
    * Status of the most recent kernel or run-table call. `WASM_STATUS.OK` unless
@@ -759,7 +631,8 @@ var WasmTransformBackend = class {
     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);
+    this.lastStatus = this.ex.compute_aabbs(n);
+    if (this.lastStatus !== WASM_STATUS.OK) return;
     store.aminx.set(this.vaminx.subarray(0, n));
     store.aminy.set(this.vaminy.subarray(0, n));
     store.amaxx.set(this.vamaxx.subarray(0, n));
@@ -767,9 +640,12 @@ var WasmTransformBackend = class {
   }
   /** 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. */
+   *  composed). No upload/readback — the per-frame resident path. Returns
+   *  `false` if the kernel rejected `count` (beyond capacity, or uninitialized),
+   *  in which case {@link aabbView} still holds the previous frame's bounds. */
   runAabbs(count) {
-    this.ex.compute_aabbs(count);
+    this.lastStatus = this.ex.compute_aabbs(count);
+    return this.lastStatus === WASM_STATUS.OK;
   }
   /** Resident wasm local-bounds input views (`bx,by,bw,bh`) for the AABB pass. */
   boundsView() {
@@ -843,6 +719,148 @@ var WasmTransformBackend = class {
   }
 };
 
+// src/wasm/hit-store.ts
+function gatherHitAABBs(root, currentFrame) {
+  const slotEntity = [];
+  const boundless = [];
+  const minxs = [];
+  const minys = [];
+  const maxxs = [];
+  const maxys = [];
+  const scratch = { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 };
+  const visit = (node) => {
+    const index = slotEntity.length;
+    slotEntity.push(node);
+    const bounds = node.getBounds();
+    if (bounds === null) {
+      boundless.push({ entity: node, index });
+      minxs.push(0);
+      minys.push(0);
+      maxxs.push(0);
+      maxys.push(0);
+    } else {
+      if (!node._readWorldCache(currentFrame, scratch)) {
+        const t = node.getWorldTransform();
+        scratch.a = t.a;
+        scratch.b = t.b;
+        scratch.c = t.c;
+        scratch.d = t.d;
+        scratch.e = t.e;
+        scratch.f = t.f;
+      }
+      const { a, b, c, d, e, f } = scratch;
+      let minX = Infinity;
+      let minY = Infinity;
+      let maxX = -Infinity;
+      let maxY = -Infinity;
+      for (let i = 0; i < 4; i++) {
+        const lx = i & 1 ? bounds.x + bounds.width : bounds.x;
+        const ly = i & 2 ? bounds.y + bounds.height : bounds.y;
+        const wx = a * lx + c * ly + e;
+        const wy = b * lx + d * ly + f;
+        if (wx < minX) minX = wx;
+        if (wx > maxX) maxX = wx;
+        if (wy < minY) minY = wy;
+        if (wy > maxY) maxY = wy;
+      }
+      minxs.push(minX);
+      minys.push(minY);
+      maxxs.push(maxX);
+      maxys.push(maxY);
+    }
+    const kids = node.children;
+    for (let i = 0; i < kids.length; i++) visit(kids[i]);
+  };
+  visit(root);
+  return {
+    count: slotEntity.length,
+    slotEntity,
+    boundless,
+    minx: Float64Array.from(minxs),
+    miny: Float64Array.from(minys),
+    maxx: Float64Array.from(maxxs),
+    maxy: Float64Array.from(maxys)
+  };
+}
+
+// src/wasm/hit-store-fused.ts
+function gatherHitAABBsFromStore(root, aabbs, storeSlotEntity, out) {
+  const slotEntity = out.slotEntity;
+  const boundless = out.boundless;
+  slotEntity.length = 0;
+  boundless.length = 0;
+  let count = 0;
+  let capacity = out.minx.length;
+  let minx = out.minx;
+  let miny = out.miny;
+  let maxx = out.maxx;
+  let maxy = out.maxy;
+  const grow = (needed) => {
+    if (needed <= capacity) return;
+    let next = capacity || 256;
+    while (next < needed) next *= 2;
+    const nminx = new Float64Array(next);
+    const nminy = new Float64Array(next);
+    const nmaxx = new Float64Array(next);
+    const nmaxy = new Float64Array(next);
+    nminx.set(minx);
+    nminy.set(miny);
+    nmaxx.set(maxx);
+    nmaxy.set(maxy);
+    minx = nminx;
+    miny = nminy;
+    maxx = nmaxx;
+    maxy = nmaxy;
+    capacity = next;
+  };
+  let bailed = false;
+  const visit = (node) => {
+    if (bailed) return;
+    const index = count;
+    slotEntity.push(node);
+    count++;
+    grow(count);
+    if (node.getBounds() === null) {
+      boundless.push({ entity: node, index });
+      minx[index] = 0;
+      miny[index] = 0;
+      maxx[index] = 0;
+      maxy[index] = 0;
+    } else {
+      const slot = node._storeSlot;
+      if (slot < 0 || slot >= aabbs.aminx.length || storeSlotEntity[slot] !== node) {
+        bailed = true;
+        return;
+      }
+      minx[index] = aabbs.aminx[slot];
+      miny[index] = aabbs.aminy[slot];
+      maxx[index] = aabbs.amaxx[slot];
+      maxy[index] = aabbs.amaxy[slot];
+    }
+    const children = node.children;
+    for (let i = 0; i < children.length; i++) visit(children[i]);
+  };
+  visit(root);
+  if (bailed) return null;
+  out.count = count;
+  out.minx = minx;
+  out.miny = miny;
+  out.maxx = maxx;
+  out.maxy = maxy;
+  return out;
+}
+function createHitGatherBuffer() {
+  return {
+    count: 0,
+    slotEntity: [],
+    boundless: [],
+    minx: new Float64Array(256),
+    miny: new Float64Array(256),
+    maxx: new Float64Array(256),
+    maxy: new Float64Array(256)
+  };
+}
+
 // src/wasm/anim-backend.ts
 var PAD3 = 8;
 var AnimBackend = class {
@@ -877,14 +895,33 @@ var AnimBackend = class {
     this.ex.anim_init(this.springCap, this.tweenCap);
     this.refreshViews();
   }
-  /** Advance `count` springs (from index 0) by `dtMs` milliseconds, in place. */
+  /**
+   * Advance `count` springs (from index 0) by `dtMs` milliseconds, in place.
+   * Returns `true` when the kernel ran. `false` means it rejected the call
+   * (count beyond the capacity {@link ensure} allocated, or no `anim_init` yet)
+   * and wrote nothing, so the caller must tick those drivers in JS instead of
+   * scattering back a pack the kernel never touched. See {@link lastStatus}.
+   */
   stepSprings(dtMs, count) {
-    this.ex.spring_step(dtMs / 1e3, count);
+    this.lastStatus = this.ex.spring_step(dtMs / 1e3, count);
+    return this.lastStatus === WASM_STATUS.OK;
   }
-  /** Advance `count` tweens (from index 0) by `dtMs` milliseconds, writing `val`. */
+  /**
+   * Advance `count` tweens (from index 0) by `dtMs` milliseconds, writing `val`.
+   * Returns `true` when the kernel ran; `false` means it rejected the call and
+   * wrote nothing (see {@link stepSprings}). `elapsed` is kernel-side state, so
+   * a rejected tween pack must not be read back — it is unadvanced, not
+   * partially advanced.
+   */
   stepTweens(dtMs, count) {
-    this.ex.tween_step(dtMs, count);
+    this.lastStatus = this.ex.tween_step(dtMs, count);
+    return this.lastStatus === WASM_STATUS.OK;
   }
+  /**
+   * Status of the most recent kernel call — `WASM_STATUS.OK` unless the kernel
+   * declined it. Mirrors {@link TransformBackend.lastStatus}.
+   */
+  lastStatus = WASM_STATUS.OK;
   refreshViews() {
     const buf = this.ex.memory.buffer;
     const sCap = this.springCap;
@@ -1035,6 +1072,12 @@ var ParticleBackend = class {
    * 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.
+   *
+   * Returns `null` when the kernel REJECTED the call — `count` beyond the
+   * capacity {@link ensure} allocated, or no `particle_init` yet. Nothing was
+   * written, so the caller must NOT {@link scatter} (that would write the
+   * gathered pre-step values back and freeze the simulation) and should fall
+   * back to the JS `updateCPU` path for this frame. See {@link lastStatus}.
    */
   step(count, p) {
     const e = p.explosion;
@@ -1054,8 +1097,18 @@ var ParticleBackend = class {
       e ? e.force : 0,
       count
     );
+    if (flag < 0) {
+      this.lastStatus = -flag;
+      return null;
+    }
+    this.lastStatus = WASM_STATUS.OK;
     return flag !== 0;
   }
+  /**
+   * Status of the most recent {@link step} — `WASM_STATUS.OK` unless the kernel
+   * declined it. Mirrors {@link TransformBackend.lastStatus}.
+   */
+  lastStatus = WASM_STATUS.OK;
   /** Transpose the AoS stride-8 buffer into the SoA views (position/velocity/
    *  life every frame; origin upload-once when `withOrigin`). */
   gather(data, count, withOrigin) {
@@ -1189,6 +1242,79 @@ async function loadCoreWasmRuntime(source) {
   return createCoreWasmRuntime(module);
 }
 
+// src/performance/UserTiming.ts
+var VECTO_USER_TIMING = {
+  scene: {
+    transform: "vecto:scene:transform",
+    drawWalk: "vecto:scene:draw-walk",
+    entityPaint: "vecto:scene:entity-paint",
+    flush: "vecto:scene:flush",
+    a11ySync: "vecto:scene:a11y-sync"
+  },
+  markdown: {
+    parse: "vecto:markdown:parse"
+  }
+};
+var nextSpanId = 0;
+function beginVectoUserTiming(name) {
+  const candidate = globalThis.performance;
+  if (typeof candidate?.mark !== "function" || typeof candidate.measure !== "function") {
+    return null;
+  }
+  const id = nextSpanId++;
+  const startMark = `${name}:start:${id}`;
+  const endMark = `${name}:end:${id}`;
+  try {
+    candidate.mark(startMark);
+    return {
+      name,
+      startMark,
+      endMark,
+      performance: candidate
+    };
+  } catch {
+    return null;
+  }
+}
+function endVectoUserTiming(span) {
+  if (!span) return;
+  const timing = span.performance;
+  try {
+    timing.mark(span.endMark);
+    timing.measure(span.name, span.startMark, span.endMark);
+  } catch {
+  } finally {
+    try {
+      timing.clearMarks?.(span.startMark);
+      timing.clearMarks?.(span.endMark);
+    } catch {
+    }
+  }
+}
+function measureVectoUserTiming(name, durationMs) {
+  const candidate = globalThis.performance;
+  if (typeof candidate?.now !== "function" || typeof candidate.mark !== "function" || typeof candidate.measure !== "function") {
+    return;
+  }
+  const id = nextSpanId++;
+  const startMark = `${name}:start:${id}`;
+  const endMark = `${name}:end:${id}`;
+  const endTime = candidate.now();
+  const startTime = Math.max(0, endTime - Math.max(0, durationMs));
+  try {
+    candidate.mark(startMark, { startTime });
+    candidate.mark(endMark, { startTime: endTime });
+    candidate.measure(name, startMark, endMark);
+  } catch {
+  } finally {
+    try {
+      candidate.clearMarks?.(startMark);
+      candidate.clearMarks?.(endMark);
+    } catch {
+    }
+  }
+}
+
 // src/tree/Scene.ts
 import { clearCssLineBoxMetrics, cssLineBoxBaseline } from "@vectojs/text";
 var RANGE_VALUE_ROLES = /* @__PURE__ */ new Set(["slider", "spinbutton", "progressbar", "scrollbar", "meter"]);
@@ -1203,9 +1329,47 @@ var INTERACTIVE_A11Y_ROLES = /* @__PURE__ */ new Set([
   "slider",
   "combobox"
 ]);
+var A11Y_REQUIRED_OWNED = /* @__PURE__ */ new Map([
+  ["grid", /* @__PURE__ */ new Set(["row", "rowgroup"])],
+  ["table", /* @__PURE__ */ new Set(["row", "rowgroup"])],
+  ["treegrid", /* @__PURE__ */ new Set(["row", "rowgroup"])],
+  ["rowgroup", /* @__PURE__ */ new Set(["row"])],
+  ["row", /* @__PURE__ */ new Set(["cell", "columnheader", "gridcell", "rowheader"])],
+  ["tablist", /* @__PURE__ */ new Set(["tab"])],
+  ["tree", /* @__PURE__ */ new Set(["treeitem", "group"])],
+  ["group", /* @__PURE__ */ new Set(["treeitem", "menuitem", "menuitemcheckbox", "menuitemradio", "option"])],
+  ["menu", /* @__PURE__ */ new Set(["menuitem", "menuitemcheckbox", "menuitemradio", "group", "separator"])],
+  ["menubar", /* @__PURE__ */ new Set(["menuitem", "menuitemcheckbox", "menuitemradio", "group", "separator"])],
+  ["listbox", /* @__PURE__ */ new Set(["option", "group"])],
+  ["list", /* @__PURE__ */ new Set(["listitem"])]
+]);
 function isNativelyFocusable(element) {
   return element instanceof HTMLButtonElement || element instanceof HTMLInputElement || element instanceof HTMLSelectElement || element instanceof HTMLTextAreaElement || element instanceof HTMLAnchorElement && element.hasAttribute("href");
 }
+var REBASED_BOX = { left: 0, top: 0, matrix: "" };
+function rebaseChildBox(parent, parentOriginX, parentOriginY, child, childOriginX, childOriginY) {
+  const det = parent.a * parent.d - parent.b * parent.c;
+  if (!Number.isFinite(det) || Math.abs(det) < 1e-12) {
+    REBASED_BOX.left = 0;
+    REBASED_BOX.top = 0;
+    REBASED_BOX.matrix = "matrix(1, 0, 0, 1, 0, 0)";
+    return REBASED_BOX;
+  }
+  const ia = parent.d / det;
+  const ib = -parent.b / det;
+  const ic = -parent.c / det;
+  const id = parent.a / det;
+  const dx = childOriginX - parentOriginX;
+  const dy = childOriginY - parentOriginY;
+  REBASED_BOX.left = ia * dx + ic * dy;
+  REBASED_BOX.top = ib * dx + id * dy;
+  const a = ia * child.a + ic * child.b;
+  const b = ib * child.a + id * child.b;
+  const c = ia * child.c + ic * child.d;
+  const d = ib * child.c + id * child.d;
+  REBASED_BOX.matrix = `matrix(${a}, ${b}, ${c}, ${d}, 0, 0)`;
+  return REBASED_BOX;
+}
 var REDUCED_MOTION_FPS = 30;
 function parseInlinePx(value) {
   if (!value || !value.endsWith("px")) return null;
@@ -1540,6 +1704,7 @@ var Scene = class _Scene {
   /** Cap on distinct recorded dirty reasons (see `recordDirtyReason`). */
   static MAX_DIRTY_REASONS = 200;
   _phaseTiming = false;
+  _userTiming = false;
   _phaseTotals = /* @__PURE__ */ new Map();
   /**
    * Start or stop per-phase render timing.
@@ -1562,6 +1727,19 @@ var Scene = class _Scene {
   get phaseTiming() {
     return this._phaseTiming;
   }
+  /**
+   * Enable or disable browser User Timing phase instrumentation.
+   *
+   * Off by default. The disabled frame path performs only boolean checks and
+   * emits no Performance Timeline entries.
+   */
+  setUserTiming(enabled) {
+    this._userTiming = enabled;
+  }
+  /** Whether browser User Timing phase instrumentation is enabled. */
+  get userTiming() {
+    return this._userTiming;
+  }
   /**
    * Accumulate one phase sample.
    *
@@ -1767,6 +1945,8 @@ var Scene = class _Scene {
   fullViewportElements = [];
   normalElements = [];
   activeIds = /* @__PURE__ */ new Set();
+  /** Per-parent insertion cursor, reused by `enforceA11yDomOrder`. */
+  a11yOrderCursors = /* @__PURE__ */ new Map();
   activePortalsThisFrame = /* @__PURE__ */ new Set();
   activePortalsPrevFrame = /* @__PURE__ */ new Set();
   portalEntities = /* @__PURE__ */ new Map();
@@ -1866,10 +2046,13 @@ var Scene = class _Scene {
     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
+  // Served by the same instance as every other accelerator (see
+  // `_wasmRuntime`): the crate keeps transform/anim/hit/particle in distinct
+  // statics, so one instance runs them all without aliasing. It indexes the
+  // main tree's world AABBs into a dense viewport grid for findEntityAt. Note
+  // that sharing one linear memory means an allocation here can grow it and
+  // detach views built over the old buffer, so each backend re-checks buffer
+  // identity (`revalidateViews`) before use. 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
@@ -1942,6 +2125,70 @@ var Scene = class _Scene {
   get hitGatherPath() {
     return this._hitFusedGather ? "fused" : "js";
   }
+  /**
+   * Why the transform accelerator did or did not run on the most recent frame.
+   * Written by the render walk and `_syncWasmStore`.
+   */
+  _transformReason = "not-installed";
+  /** Why the batched-driver accelerator did or did not run. */
+  _animReason = "not-installed";
+  /**
+   * Why the hit-test accelerator did or did not serve the last pointer query.
+   * The grid is built lazily on demand, not every frame, so this describes the
+   * most recent BUILD. Starts at `'not-installed'` because that is the truth
+   * before a backend exists; `_ensureHitGrid` moves it to `'not-applicable'`
+   * once one is installed but nothing has queried yet.
+   */
+  _hitReason = "not-installed";
+  /** Why the particle accelerator did or did not run. */
+  _particleReason = "not-applicable";
+  /** Which particle implementation actually simulated the most recent frame. */
+  _particlePath = "none";
+  /**
+   * Per-frame status of every invisible accelerator: whether each is installed,
+   * whether it actually ran on the most recent frame, and why.
+   *
+   * This exists because the older per-accelerator getters
+   * ({@link transformBackend}, {@link animBackend}, {@link hitTestBackend},
+   * {@link particleBackend}) report only that a backend is INSTALLED. Reading
+   * `'wasm'` from one of those and concluding the accelerator is doing work is
+   * wrong whenever a gate never opens, a kernel rejects its arguments, or a
+   * faster backend takes the pass instead. Read {@link AcceleratorStatus.reason}
+   * for which of those happened.
+   *
+   * Reflects the most recent main-renderer frame; a secondary renderer (SVG
+   * export, offscreen snapshot) does not overwrite it.
+   */
+  get accelerators() {
+    return {
+      transform: {
+        available: this._wasm !== null && this._transformBackend === "wasm",
+        activeThisFrame: this._transformReason === "active",
+        reason: this._transformReason,
+        path: this._transformReason === "active" ? "wasm" : "js"
+      },
+      animation: {
+        available: this._animWasm !== null,
+        activeThisFrame: this._animBatchedLastFrame,
+        reason: this._animReason,
+        path: this._animBatchedLastFrame ? "wasm" : "js"
+      },
+      hitTest: {
+        available: this._hitWasm !== null,
+        // The grid is built lazily on a pointer query, not every frame, so this
+        // describes the last BUILD rather than the last frame.
+        activeThisFrame: this._hitReason === "active",
+        reason: this._hitReason,
+        path: this._hitReason !== "active" ? "js" : this._hitFusedGather ? "wasm-fused" : "wasm"
+      },
+      particle: {
+        available: this._particleWasm !== null || this.webgpuActive,
+        activeThisFrame: this._particleReason === "active",
+        reason: this._particleReason,
+        path: this._particlePath
+      }
+    };
+  }
   /** Which backend answers `findEntityAt` for the main tree. */
   get hitTestBackend() {
     return this._hitWasm ? "wasm" : "js";
@@ -1951,6 +2198,7 @@ var Scene = class _Scene {
   setHitTestBackend(backend) {
     this._hitWasm = backend;
     this._hitGridFrame = -1;
+    this._hitReason = backend ? "not-applicable" : "not-installed";
   }
   /**
    * Asynchronously instantiate the WASM hit-test core and, on success, hot-swap
@@ -1977,7 +2225,10 @@ var Scene = class _Scene {
    */
   _ensureHitGrid() {
     const backend = this._hitWasm;
-    if (!backend) return false;
+    if (!backend) {
+      this._hitReason = "not-installed";
+      return false;
+    }
     if (this._hitGridFrame === this.currentFrame) return this._hitGridOk;
     let gathered = null;
     if (this._wasm && this._ensureWasmAabbs()) {
@@ -2006,6 +2257,7 @@ var Scene = class _Scene {
     this._hitBoundless = gathered.boundless;
     this._hitGridFrame = this.currentFrame;
     this._hitGridOk = ok;
+    this._hitReason = ok ? "active" : "rejected";
     return ok;
   }
   /**
@@ -2271,7 +2523,10 @@ var Scene = class _Scene {
    * pre-pass.
    */
   _tickBatchedDrivers(dt) {
-    if (this._activeDriverEntities.size === 0) return;
+    if (this._activeDriverEntities.size === 0) {
+      this._animReason = "not-applicable";
+      return;
+    }
     let springBatchable = 0;
     let tweenBatchable = 0;
     for (const entity of this._activeDriverEntities) {
@@ -2288,10 +2543,17 @@ var Scene = class _Scene {
     const batchable = springBatchable + tweenBatchable;
     const backend = this._animWasm;
     this._animBatchedLastFrame = false;
-    if (!backend) return;
+    if (!backend) {
+      this._animReason = "not-installed";
+      return;
+    }
     const gate = springBatchable > 0 && tweenBatchable > 0 ? this.animGate.mixed : tweenBatchable > 0 ? this.animGate.tween : this.animGate.spring;
-    if (batchable < gate) return;
+    if (batchable < gate) {
+      this._animReason = "below-gate";
+      return;
+    }
     this._animBatchedLastFrame = true;
+    this._animReason = "active";
     const sE = this._springEntities;
     const sP = this._springProps;
     const sD = this._springDrivers;
@@ -2338,8 +2600,13 @@ var Scene = class _Scene {
         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 (backend.stepSprings(dt, springCount)) {
+        for (let i = 0; i < springCount; i++) sD[i].syncExternal(sv.val[i], sv.vel[i]);
+      } else {
+        for (let i = 0; i < springCount; i++) sD[i].tick(dt);
+        this._animReason = "rejected";
+        this._animBatchedLastFrame = false;
+      }
     }
     if (tweenCount > 0) {
       const tv = backend.tweenView();
@@ -2352,8 +2619,13 @@ var Scene = class _Scene {
         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]);
+      if (backend.stepTweens(dt, tweenCount)) {
+        for (let i = 0; i < tweenCount; i++) tD[i].syncExternal(tv.val[i], tv.elapsed[i]);
+      } else {
+        for (let i = 0; i < tweenCount; i++) tD[i].tick(dt);
+        this._animReason = "rejected";
+        this._animBatchedLastFrame = false;
+      }
     }
     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]);
@@ -2375,7 +2647,10 @@ var Scene = class _Scene {
         slotEntity2[slot] = entity;
         entity._storeSlot = slot;
       }
-      backend.uploadRuns(built.store);
+      if (!backend.uploadRuns(built.store)) {
+        this._transformReason = "rejected";
+        return null;
+      }
       this._treeStore = built.store;
       this._slotEntity = slotEntity2;
       this._wasmInputs = backend.inputView();
@@ -2400,8 +2675,12 @@ var Scene = class _Scene {
       inp.sin[slot] = trig.sin;
       inp.opacity[slot] = e.opacity;
     }
-    backend.runKernel("simd");
+    if (backend.runKernel("simd") !== WASM_STATUS.OK) {
+      this._transformReason = "rejected";
+      return null;
+    }
     this._wasmAabbsFresh = false;
+    this._transformReason = "active";
     return this._wasmWorld;
   }
   /**
@@ -2431,7 +2710,7 @@ var Scene = class _Scene {
       bounds.bw[slot] = b ? b.width : 0;
       bounds.bh[slot] = b ? b.height : 0;
     }
-    backend.runAabbs(slotEntity.length);
+    if (!backend.runAabbs(slotEntity.length)) return false;
     this._wasmAabbsFresh = true;
     return true;
   }
@@ -2582,6 +2861,7 @@ var Scene = class _Scene {
     this.maxFPS = options.maxFPS ?? (isTest ? 0 : 60);
     this.respectReducedMotion = options.respectReducedMotion ?? true;
     this.autoThrottle = options.autoThrottle ?? true;
+    this._userTiming = options.userTiming ?? false;
     this.particleBackend = options.particleBackend ?? "auto";
     this.a11ySyncInterval = options.a11ySyncInterval ?? 0;
     this.contentProjectionEnabled = options.contentProjection ?? true;
@@ -2626,6 +2906,7 @@ var Scene = class _Scene {
     });
     if (typeof document !== "undefined") {
       this.a11yRoot = document.createElement("div");
+      this.a11yRoot.setAttribute("data-vecto-a11y-root", "");
       this.a11yRoot.style.position = "absolute";
       this.a11yRoot.style.top = "0";
       this.a11yRoot.style.left = "0";
@@ -3478,7 +3759,7 @@ var Scene = class _Scene {
   shouldProjectA11y(node) {
     return node.interactive && (node.width > 0 || node.a11yFullViewport);
   }
-  syncA11y(node) {
+  syncA11y(node, container = null) {
     if (!this.a11yRoot) return;
     if (node.isDOMPortal) {
       return;
@@ -3488,6 +3769,7 @@ var Scene = class _Scene {
       return;
     }
     const nodeStart = this._phaseTiming ? performance.now() : 0;
+    let childContainer = container;
     if (this.shouldProjectA11y(node)) {
       let el = this.a11yElements.get(node.id);
       const attrs = node.getA11yAttributes();
@@ -3500,9 +3782,9 @@ var Scene = class _Scene {
             this.caretBlinkTimer = null;
           }
         }
-        if (el.parentNode === this.a11yRoot) {
+        if (el.parentNode) {
           this.preserveFocusOnRemoval(el);
-          this.a11yRoot.removeChild(el);
+          el.remove();
         }
         this.a11yElements.delete(node.id);
         el = void 0;
@@ -3810,6 +4092,7 @@ var Scene = class _Scene {
         if (el.style.boxSizing !== "border-box") el.style.boxSizing = "border-box";
         if (el instanceof HTMLTextAreaElement) el.style.resize = "none";
       }
+      const nestedIn = container && attrs.role && container.owned.has(attrs.role) ? container : null;
       if (node.a11yFullViewport) {
         el.style.left = "0px";
         el.style.top = "0px";
@@ -3820,11 +4103,36 @@ var Scene = class _Scene {
       } else {
         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`;
+        const originX = e + node.a11yOffsetX;
+        const originY = f + node.a11yOffsetY;
+        const parentEl = nestedIn && nestedIn.el !== el && nestedIn.el.isConnected ? nestedIn.el : this.a11yRoot;
+        if (el.parentNode !== parentEl) {
+          parentEl.appendChild(el);
+          this.a11yNeedsReorder = true;
+        }
+        if (parentEl === this.a11yRoot) {
+          el.style.left = `${originX}px`;
+          el.style.top = `${originY}px`;
+          el.style.transform = `matrix(${a}, ${b}, ${c}, ${d}, 0, 0)`;
+        } else {
+          const box = rebaseChildBox(
+            nestedIn.transform,
+            nestedIn.originX,
+            nestedIn.originY,
+            worldTf,
+            originX,
+            originY
+          );
+          el.style.left = `${box.left}px`;
+          el.style.top = `${box.top}px`;
+          el.style.transform = box.matrix;
+        }
         el.style.width = `${node.width}px`;
         el.style.height = `${node.height}px`;
-        el.style.transform = `matrix(${a}, ${b}, ${c}, ${d}, 0, 0)`;
+        const owned = attrs.role ? A11Y_REQUIRED_OWNED.get(attrs.role) : void 0;
+        if (owned) {
+          childContainer = { el, owned, transform: worldTf, originX, originY };
+        }
         const visible = this.projectionBoxVisible(node, worldTf, 0);
         const display = visible ? "" : "none";
         if (el.style.display !== display) el.style.display = display;
@@ -3838,9 +4146,9 @@ var Scene = class _Scene {
     } else {
       this.syncContentProjection(node);
     }
-    for (const child of node.children) this.syncA11y(child);
+    for (const child of node.children) this.syncA11y(child, childContainer);
     if (node === this.root) {
-      for (const overlay of this.overlayRoot.children) this.syncA11y(overlay);
+      for (const overlay of this.overlayRoot.children) this.syncA11y(overlay, null);
     }
   }
   /**
@@ -4398,9 +4706,9 @@ var Scene = class _Scene {
             this.caretBlinkTimer = null;
           }
         }
-        if (el.parentNode === this.a11yRoot) {
+        if (el.parentNode) {
           this.preserveFocusOnRemoval(el);
-          this.a11yRoot.removeChild(el);
+          el.remove();
         }
         this.a11yElements.delete(id);
       }
@@ -4413,23 +4721,39 @@ var Scene = class _Scene {
     const fullLen = this.fullViewportElements.length;
     const normalLen = this.normalElements.length;
     const totalLen = fullLen + normalLen;
+    this.a11yOrderCursors.clear();
     for (let i = 0; i < totalLen; i++) {
       const expected = i < fullLen ? this.fullViewportElements[i] : this.normalElements[i - fullLen];
-      const current = this.a11yRoot.childNodes[i];
+      const parent = expected.parentNode;
+      if (!parent) continue;
+      const at = this.a11yOrderCursors.get(parent) ?? 0;
+      this.a11yOrderCursors.set(parent, at + 1);
+      const current = parent.childNodes[at];
       if (current !== expected) {
-        this.a11yRoot.insertBefore(expected, current || null);
+        parent.insertBefore(expected, current || null);
       }
     }
     this.a11yNeedsReorder = false;
   }
   /**
    * Reorder `normalElements` (in place) into visual reading order using the
-   * world positions `syncA11y` already wrote to each element's inline style
+   * 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.
+   *
+   * Those inline values are world coordinates for a top-level mirror but
+   * PARENT-RELATIVE for a nested one, so this list mixes coordinate spaces.
+   * That is sound because the result is only ever applied per DOM parent
+   * ({@link enforceA11yDomOrder} advances a cursor per parent), and all of one
+   * parent's children share one space: a `grid`'s rows are all grid-relative, a
+   * `row`'s cells all row-relative. Comparisons ACROSS spaces do happen while
+   * banding, but they only affect the relative order of elements in different
+   * parents, which no `insertBefore` ever acts on. Normalizing everything back
+   * to world coordinates here would cost a transform per element per frame to
+   * change nothing observable.
    */
   sortNormalElementsVisually() {
     const els = this.normalElements;
@@ -4665,9 +4989,11 @@ var Scene = class _Scene {
     if ((hasInteractive || this.a11yElements.size > 0 || wantsContentSync) && (shouldSyncInterval || this.a11yPendingSyncAfterAnimation)) {
       this.lastA11ySync = time;
       if (hasInteractive || wantsContentSync) {
+        const userTiming = this._userTiming ? beginVectoUserTiming(VECTO_USER_TIMING.scene.a11ySync) : null;
         const t0 = this._phaseTiming ? performance.now() : 0;
         this.syncA11y(this.root);
         if (this._phaseTiming) this._recordPhase("a11ySync", performance.now() - t0);
+        if (userTiming) endVectoUserTiming(userTiming);
       }
       const t1 = this._phaseTiming ? performance.now() : 0;
       this.enforceA11yDomOrder();
@@ -4681,6 +5007,26 @@ var Scene = class _Scene {
   /**
    * Render the entire scene graph onto the specified renderer.
    *
+   * Main-frame causal order is a correctness contract:
+   *
+   * 1. Browser/input callbacks finish before the scheduled frame begins.
+   * 2. Batched property drivers and particle simulation advance.
+   * 3. Entity `update()` hooks run.
+   * 4. Transform inputs are gathered and world matrices are composed.
+   * 5. Updated world bounds are tested for culling.
+   * 6. Visible entities paint in scene-graph order.
+   * 7. Canvas/GPU batches flush and retained renderers present.
+   * 8. The rAF loop synchronizes content and accessibility projections after
+   *    this method returns.
+   *
+   * The causal order is fixed; physical walks may stay fused. The JavaScript
+   * transform path interleaves update → compose → cull → paint per node in
+   * pre-order. The WASM path updates the whole tree first, then gathers and
+   * composes it in one store pass before the same cull/paint walk. Both must
+   * expose an update's transform mutation in that same rendered frame.
+   * Secondary renderers are read-only snapshots: they skip simulation and
+   * updates, then compose/cull/paint/flush the current state.
+   *
    * @param renderer - The renderer instance to draw to.
    * @param dt - Delta time in milliseconds (default 0).
    * @param time - Current absolute time in milliseconds (default 0).
@@ -4705,6 +5051,10 @@ var Scene = class _Scene {
     const computeEntities = this._computeEntitiesFor(this._structureVersion);
     if (computeEntities.length > 0) {
       const isMainRenderPath = renderer === this.renderer;
+      if (isMainRenderPath) {
+        this._particleReason = this._particleWasm ? "active" : "not-installed";
+        this._particlePath = this._particleWasm ? "wasm" : "js";
+      }
       if (isMainRenderPath && !this.device && !this.webgpuDisabled && !this.initializingWebGPU && !this.deviceLost) {
         this.initializingWebGPU = true;
         this.initWebGPUContext(computeEntities).then((newDevice) => {
@@ -4780,6 +5130,8 @@ var Scene = class _Scene {
           }
           this.device.queue.submit([commandEncoder.finish()]);
           if (this.gpuContext) this.gpuHasContent = true;
+          this._particleReason = "active";
+          this._particlePath = "webgpu";
         } catch (e) {
           console.error("WebGPU frame execution failed. Falling back.", e);
           this.deviceLost = true;
@@ -4801,13 +5153,25 @@ var Scene = class _Scene {
             }
           }
           if (this._particleWasm) {
-            entity.stepWithBackend(this._particleWasm, dt / 1e3, mx, my, this.width, this.height);
+            if (!entity.stepWithBackend(
+              this._particleWasm,
+              dt / 1e3,
+              mx,
+              my,
+              this.width,
+              this.height
+            )) {
+              this._particleReason = "rejected";
+              this._particlePath = "js";
+            }
           } else {
             entity.updateCPU(dt / 1e3, mx, my, this.width, this.height);
           }
         }
       }
     } else if (isMainRenderer) {
+      this._particleReason = "not-applicable";
+      this._particlePath = "none";
       this.clearGPUCanvasIfStale();
     }
     renderer.clear();
@@ -4836,6 +5200,9 @@ var Scene = class _Scene {
       }
     };
     const wasmMain = isMainRenderer && this._wasm !== null && this._transformBackend === "wasm";
+    if (isMainRenderer) {
+      this._transformReason = wasmMain ? "active" : "not-installed";
+    }
     if (wasmMain) {
       const updateWalk = (node) => {
         runUpdate(node);
@@ -4845,10 +5212,13 @@ var Scene = class _Scene {
       updateWalk(this.root);
       for (const overlay of this.overlayRoot.children) updateWalk(overlay);
     }
+    const transformTiming = this._userTiming ? beginVectoUserTiming(VECTO_USER_TIMING.scene.transform) : null;
     const wasmT0 = this._phaseTiming ? performance.now() : 0;
     const wasmWorld = wasmMain ? this._syncWasmStore() : null;
     if (this._phaseTiming) this._recordPhase("transform", performance.now() - wasmT0);
+    if (transformTiming) endVectoUserTiming(transformTiming);
     const wasmSlotEntity = this._slotEntity;
+    let userEntityPaintMs = 0;
     const renderNode = (node, pa, pb, pc, pd, pe, pf, parentOpacity) => {
       if (isMainRenderer && !wasmMain) {
         runUpdate(node);
@@ -4977,10 +5347,15 @@ var Scene = class _Scene {
             );
           }
         } else {
-          if (this._phaseTiming) {
+          if (this._userTiming || this._phaseTiming) {
             const t0 = performance.now();
-            node.render(renderer);
-            this._recordPhase("entityPaint", performance.now() - t0);
+            try {
+              node.render(renderer);
+            } finally {
+              const elapsed = performance.now() - t0;
+              if (this._userTiming) userEntityPaintMs += elapsed;
+              if (this._phaseTiming) this._recordPhase("entityPaint", elapsed);
+            }
           } else {
             node.render(renderer);
           }
@@ -4995,17 +5370,23 @@ var Scene = class _Scene {
       renderer.flush();
       renderer.restore();
     };
+    const drawTiming = this._userTiming ? beginVectoUserTiming(VECTO_USER_TIMING.scene.drawWalk) : null;
     const drawT0 = this._phaseTiming ? performance.now() : 0;
     renderNode(this.root, 1, 0, 0, 1, 0, 0, 1);
     for (const overlay of this.overlayRoot.children) {
       renderNode(overlay, 1, 0, 0, 1, 0, 0, 1);
     }
     if (this._phaseTiming) this._recordPhase("drawWalk", performance.now() - drawT0);
+    if (drawTiming) endVectoUserTiming(drawTiming);
+    if (this._userTiming) {
+      measureVectoUserTiming(VECTO_USER_TIMING.scene.entityPaint, userEntityPaintMs);
+    }
     if (isMainRenderer) {
       this.frameHadAnimation = walkHadAnimation;
       this.frameHadInteractive = walkHadInteractive;
       this.reconcilePortals();
     }
+    const flushTiming = this._userTiming ? beginVectoUserTiming(VECTO_USER_TIMING.scene.flush) : null;
     const flushT0 = this._phaseTiming ? performance.now() : 0;
     renderer.flush();
     if (isMainRenderer) {
@@ -5013,6 +5394,7 @@ var Scene = class _Scene {
     }
     renderer.present?.();
     if (this._phaseTiming) this._recordPhase("flush", performance.now() - flushT0);
+    if (flushTiming) endVectoUserTiming(flushTiming);
     if (this._devActive) {
       this._devFrameCount++;
       this._devRunChecks();
@@ -6112,11 +6494,15 @@ export {
   SplineEntity,
   TextEntity,
   TextRasterCache,
+  VECTO_USER_TIMING,
   VectoJSEvent,
   WebGPUParticleSystemManager,
+  beginVectoUserTiming,
   createWebGLPointRenderer,
+  endVectoUserTiming,
   isSafeUrl,
   loadSpline,
+  measureVectoUserTiming,
   parseColorToRGBA,
   polySegmentToBezier,
   sanitizeUrl