@vectojs/core 1.22.0 → 1.24.0

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/ComputeParticleEntity.d.ts

@@ -143,8 +143,12 @@ export declare class ComputeParticleEntity 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: ParticleBackend, dt: number, mouseX: number, mouseY: number, width: number, height: number): void;
+    stepWithBackend(backend: ParticleBackend, dt: number, mouseX: number, mouseY: number, width: number, height: number): boolean;
     destroy(): void;
     /**
      * Frees all GPU resources allocated for WebGPU simulation.

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
@@ -208,6 +213,60 @@ export interface SceneOptions {
 }
 /** Frame-rate the loop is capped to when the OS requests reduced motion. */
 export declare const REDUCED_MOTION_FPS = 30;
+/**
+ * Why an accelerator did or did not run on the most recent frame.
+ *
+ * `'active'` is the only value that means the accelerator ran. Everything else
+ * is a distinct decline, kept separate because they call for different actions:
+ * `'not-installed'` means enable it, `'below-gate'` means the workload is too
+ * small to be worth it (working as designed), and `'rejected'` means the kernel
+ * refused its arguments — a fault worth reporting, not a tuning outcome.
+ */
+export type AcceleratorReason = 
+/** Ran on this frame. */
+'active'
+/** No backend installed; the JS path is the permanent fallback. */
+ | 'not-installed'
+/** Installed, but the per-frame gate chose JS (workload below threshold). */
+ | 'below-gate'
+/** Installed and gated in, but the kernel rejected the call and wrote nothing. */
+ | 'rejected'
+/** Not applicable to this pass (e.g. a non-main renderer, or nothing to do). */
+ | 'not-applicable';
+/**
+ * One accelerator's per-frame status, read from {@link Scene.accelerators}.
+ *
+ * The pair exists because `available` and `activeThisFrame` genuinely differ:
+ * before this shape, `transformBackend`/`animBackend` reported only that a
+ * backend was *installed*, which invites concluding an accelerator is doing work
+ * when its gate never opens. Read `activeThisFrame` for what actually happened
+ * and `reason` for why.
+ */
+export interface AcceleratorStatus {
+    /** A backend is installed and could run, gate permitting. */
+    available: boolean;
+    /** It ran on the most recent frame. */
+    activeThisFrame: boolean;
+    /** Why it did or did not run. */
+    reason: AcceleratorReason;
+    /** Which implementation actually did the work on the most recent frame. */
+    path: string;
+}
+/**
+ * Per-frame status of every invisible accelerator, read from
+ * {@link Scene.accelerators}. Each is independent: a scene can compose
+ * transforms in WASM while ticking drivers in JS.
+ */
+export interface AcceleratorReport {
+    /** World-matrix composition (`compose_simd`). */
+    transform: AcceleratorStatus;
+    /** Batched property drivers (`spring_step`/`tween_step`). */
+    animation: AcceleratorStatus;
+    /** Hit-test broad phase (`hit_build`/`hit_query`) and its gather source. */
+    hitTest: AcceleratorStatus;
+    /** Particle simulation — WebGPU compute, the WASM CPU kernel, or JS. */
+    particle: AcceleratorStatus;
+}
 /**
  * Live render-loop telemetry, read from {@link Scene.frameStats}. See that
  * getter for how each field is measured.
@@ -287,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.
@@ -304,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.
      *
@@ -467,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;
@@ -574,6 +645,41 @@ export declare class Scene {
     private _wasmAabbsFresh;
     /** Did the last hit-grid build use the fused (WASM-store) gather? */
     get hitGatherPath(): 'fused' | 'js';
+    /**
+     * Why the transform accelerator did or did not run on the most recent frame.
+     * Written by the render walk and `_syncWasmStore`.
+     */
+    private _transformReason;
+    /** Why the batched-driver accelerator did or did not run. */
+    private _animReason;
+    /**
+     * 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.
+     */
+    private _hitReason;
+    /** Why the particle accelerator did or did not run. */
+    private _particleReason;
+    /** Which particle implementation actually simulated the most recent frame. */
+    private _particlePath;
+    /**
+     * 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(): AcceleratorReport;
     /** Which backend answers `findEntityAt` for the main tree. */
     get hitTestBackend(): 'js' | 'wasm';
     /** Install (or clear) a WASM hit-test backend directly. Prefer
@@ -1169,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. */
@@ -1192,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/dist/wasm/anim-backend.d.ts

@@ -56,10 +56,27 @@ export declare class AnimBackend {
      * writing first and sizing after would write into a stale buffer.
      */
     ensure(springCount: number, tweenCount: number): void;
-    /** Advance `count` springs (from index 0) by `dtMs` milliseconds, in place. */
-    stepSprings(dtMs: number, count: number): void;
-    /** Advance `count` tweens (from index 0) by `dtMs` milliseconds, writing `val`. */
-    stepTweens(dtMs: number, count: number): void;
+    /**
+     * 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: number, count: number): boolean;
+    /**
+     * 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: number, count: number): boolean;
+    /**
+     * Status of the most recent kernel call — `WASM_STATUS.OK` unless the kernel
+     * declined it. Mirrors {@link TransformBackend.lastStatus}.
+     */
+    lastStatus: number;
     private refreshViews;
 }
 /**

package/dist/wasm/backend.d.ts

@@ -84,8 +84,11 @@ export declare class WasmTransformBackend {
      */
     runKernel(kernel?: Kernel): number;
     /** 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: TransformStore): void;
+     *  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: TransformStore): boolean;
     /**
      * Status of the most recent kernel or run-table call. `WASM_STATUS.OK` unless
      * the crate rejected its arguments, in which case that call was a no-op.
@@ -125,8 +128,10 @@ export declare class WasmTransformBackend {
     computeAabbs(store: TransformStore): void;
     /** 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: number): void;
+     *  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: number): boolean;
     /** Resident wasm local-bounds input views (`bx,by,bw,bh`) for the AABB pass. */
     boundsView(): {
         bx: Float64Array;

package/dist/wasm/particle-backend.d.ts

@@ -71,8 +71,19 @@ export declare class ParticleBackend {
      * 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: number, p: ParticleStepParams): boolean;
+    step(count: number, p: ParticleStepParams): boolean | null;
+    /**
+     * Status of the most recent {@link step} — `WASM_STATUS.OK` unless the kernel
+     * declined it. Mirrors {@link TransformBackend.lastStatus}.
+     */
+    lastStatus: number;
     /** Transpose the AoS stride-8 buffer into the SoA views (position/velocity/
      *  life every frame; origin upload-once when `withOrigin`). */
     gather(data: Float32Array, count: number, withOrigin: boolean): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectojs/core",
-  "version": "1.22.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",