@vectojs/core 1.23.0 → 1.25.0

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.25.0",
   "publishConfig": {
     "access": "public"
   },
@@ -61,19 +61,20 @@
   "scripts": {
     "build": "(cd ../math && bun run build) && (cd ../text && bun run build) && (cd ../layout && bun run build) && (cd ../animation && bun run build) && tsup && tsc -p tsconfig.build.json",
     "test": "vitest run",
-    "test:e2e": "bun e2e/hidpi.e2e.ts && bun e2e/text-projection.e2e.ts"
+    "test:e2e": "bun e2e/hidpi.e2e.ts && bun e2e/text-projection.e2e.ts && bun e2e/svg-fallback.e2e.ts && bun e2e/msdf-atlas-decode.e2e.ts && bun e2e/layout-worker-fallback.e2e.ts"
   },
   "dependencies": {
     "@vectojs/animation": "^0.1.1",
-    "@vectojs/layout": "^0.4.0",
+    "@vectojs/layout": "^0.5.0",
     "@vectojs/math": "^0.1.1",
-    "@vectojs/text": "^0.2.0"
+    "@vectojs/text": "^0.3.0"
   },
   "devDependencies": {
+    "@guidepup/virtual-screen-reader": "0.32.1",
     "@vitest/coverage-v8": "^4.1.10",
     "esbuild": "^0.28.1",
-    "jsdom": "^29.1.1",
-    "puppeteer-core": "^25.3.0",
+    "jsdom": "^30.0.1",
+    "puppeteer-core": "^25.4.0",
     "tsup": "^8.3.5",
     "vitest": "^4.1.10"
   }