@vectojs/core 1.23.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,
@@ -1242,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"]);
@@ -1256,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;
@@ -1593,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.
@@ -1615,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.
    *
@@ -1820,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();
@@ -2734,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;
@@ -2778,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";
@@ -3630,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;
@@ -3640,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();
@@ -3652,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;
@@ -3962,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";
@@ -3972,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;
@@ -3990,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);
     }
   }
   /**
@@ -4550,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);
       }
@@ -4565,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;
@@ -4817,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();
@@ -4833,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).
@@ -5018,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);
@@ -5150,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);
           }
@@ -5168,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) {
@@ -5186,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();
@@ -6285,11 +6494,15 @@ export {
   SplineEntity,
   TextEntity,
   TextRasterCache,
+  VECTO_USER_TIMING,
   VectoJSEvent,
   WebGPUParticleSystemManager,
+  beginVectoUserTiming,
   createWebGLPointRenderer,
+  endVectoUserTiming,
   isSafeUrl,
   loadSpline,
+  measureVectoUserTiming,
   parseColorToRGBA,
   polySegmentToBezier,
   sanitizeUrl

package/dist/performance/UserTiming.d.ts

@@ -0,0 +1,44 @@
+/** Stable User Timing measure names emitted by VectoJS instrumentation. */
+export declare const VECTO_USER_TIMING: {
+    readonly scene: {
+        readonly transform: 'vecto:scene:transform';
+        readonly drawWalk: 'vecto:scene:draw-walk';
+        readonly entityPaint: 'vecto:scene:entity-paint';
+        readonly flush: 'vecto:scene:flush';
+        readonly a11ySync: 'vecto:scene:a11y-sync';
+    };
+    readonly markdown: {
+        readonly parse: 'vecto:markdown:parse';
+    };
+};
+interface TimingPerformance {
+    now(): number;
+    mark(name: string, options?: {
+        startTime?: number;
+    }): unknown;
+    measure(name: string, startMark: string, endMark: string): unknown;
+    clearMarks?(name?: string): void;
+}
+/** Opaque handle for one enabled User Timing interval. */
+export interface VectoUserTimingSpan {
+    readonly name: string;
+    readonly startMark: string;
+    readonly endMark: string;
+    readonly performance: TimingPerformance;
+}
+/**
+ * Begin a User Timing interval when the host implements marks and measures.
+ * Returns `null` instead of making optional profiling a runtime requirement.
+ */
+export declare function beginVectoUserTiming(name: string): VectoUserTimingSpan | null;
+/** Finish a span and release its uniquely named marks. */
+export declare function endVectoUserTiming(span: VectoUserTimingSpan | null): void;
+/**
+ * Emit one measure for a duration accumulated from disjoint calls.
+ *
+ * The marks are anchored at the current time with the measured duration ending
+ * there. This keeps one entry per frame while still reporting the sum of every
+ * entity's paint call instead of instrumenting every entity individually.
+ */
+export declare function measureVectoUserTiming(name: string, durationMs: number): void;
+export {};

package/dist/renderer.js

@@ -7,7 +7,7 @@
 
 
 
-var _chunkLHONR3GOjs = require('./chunk-LHONR3GO.js');
+var _chunkKEBYJVD6js = require('./chunk-KEBYJVD6.js');
 
 
 
@@ -16,4 +16,4 @@ var _chunkLHONR3GOjs = require('./chunk-LHONR3GO.js');
 
 
 
-exports.CanvasRenderer = _chunkLHONR3GOjs.CanvasRenderer; exports.GlyphRasterAtlas = _chunkLHONR3GOjs.GlyphRasterAtlas; exports.SVGRenderer = _chunkLHONR3GOjs.SVGRenderer; exports.TextRasterCache = _chunkLHONR3GOjs.TextRasterCache; exports.WebGPUParticleSystemManager = _chunkLHONR3GOjs.WebGPUParticleSystemManager; exports.createWebGLPointRenderer = _chunkLHONR3GOjs.createWebGLPointRenderer; exports.parseColorToRGBA = _chunkLHONR3GOjs.parseColorToRGBA;
+exports.CanvasRenderer = _chunkKEBYJVD6js.CanvasRenderer; exports.GlyphRasterAtlas = _chunkKEBYJVD6js.GlyphRasterAtlas; exports.SVGRenderer = _chunkKEBYJVD6js.SVGRenderer; exports.TextRasterCache = _chunkKEBYJVD6js.TextRasterCache; exports.WebGPUParticleSystemManager = _chunkKEBYJVD6js.WebGPUParticleSystemManager; exports.createWebGLPointRenderer = _chunkKEBYJVD6js.createWebGLPointRenderer; exports.parseColorToRGBA = _chunkKEBYJVD6js.parseColorToRGBA;

package/dist/renderer.mjs

@@ -6,7 +6,7 @@ import {
   WebGPUParticleSystemManager,
   createWebGLPointRenderer,
   parseColorToRGBA
-} from "./chunk-UPULSLKA.mjs";
+} from "./chunk-ME4LB2HB.mjs";
 export {
   CanvasRenderer,
   GlyphRasterAtlas,

package/dist/tree/Scene.d.ts

@@ -176,6 +176,11 @@ export interface SceneOptions {
      * and not marked dirty) to save power/CPU. Default is `true`.
      */
     autoThrottle?: boolean;
+    /**
+     * Emit User Timing marks and measures for render phases. Default `false`.
+     * Intended for short profiler captures; enable only while collecting one.
+     */
+    userTiming?: boolean;
     /**
      * Mirror static text from entities implementing
      * {@link Entity.getContentProjection} as transparent, position-synced DOM
@@ -341,6 +346,7 @@ export declare class Scene {
     /** Cap on distinct recorded dirty reasons (see `recordDirtyReason`). */
     private static readonly MAX_DIRTY_REASONS;
     private _phaseTiming;
+    private _userTiming;
     private _phaseTotals;
     /**
      * Start or stop per-phase render timing.
@@ -358,6 +364,15 @@ export declare class Scene {
     setPhaseTiming(enabled: boolean): void;
     /** Whether per-phase render timing is being recorded. */
     get phaseTiming(): boolean;
+    /**
+     * 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: boolean): void;
+    /** Whether browser User Timing phase instrumentation is enabled. */
+    get userTiming(): boolean;
     /**
      * Accumulate one phase sample.
      *
@@ -521,6 +536,8 @@ export declare class Scene {
     private fullViewportElements;
     private normalElements;
     private activeIds;
+    /** Per-parent insertion cursor, reused by `enforceA11yDomOrder`. */
+    private a11yOrderCursors;
     private activePortalsThisFrame;
     private activePortalsPrevFrame;
     private portalEntities;
@@ -1258,12 +1275,23 @@ export declare class Scene {
     private enforceA11yDomOrder;
     /**
      * 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.
      */
     private sortNormalElementsVisually;
     /** Keep DOM/WebGL overlay layers aligned with the canvas's CSS box. */
@@ -1281,6 +1309,26 @@ export declare 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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectojs/core",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "publishConfig": {
     "access": "public"
   },
@@ -70,6 +70,7 @@
     "@vectojs/text": "^0.2.0"
   },
   "devDependencies": {
+    "@guidepup/virtual-screen-reader": "0.32.1",
     "@vitest/coverage-v8": "^4.1.10",
     "esbuild": "^0.28.1",
     "jsdom": "^29.1.1",