@vectojs/core 1.19.0 → 1.21.0

package/dist/tree/Scene.d.ts

@@ -17,6 +17,61 @@ import { type CoreWasmRuntime } from '../wasm/runtime';
 import { type HitModuleSource, type HitTestBackend } from '../wasm/hit-backend';
 import { type AnimModuleSource, type AnimBackend } from '../wasm/anim-backend';
 import { type ParticleModuleSource, type ParticleBackend } from '../wasm/particle-backend';
+/**
+ * A timed phase of a frame.
+ *
+ * `render` is the ENCLOSING phase — it contains `transform`, `drawWalk` and
+ * `flush` — so it is reported without a share to avoid double-counting.
+ * `a11ySync` and `a11yOrder` run after `render` in the frame loop, so they are
+ * siblings of it, not children.
+ */
+export type RenderPhase = 'render' | 'transform' | 'drawWalk' | 'flush' | 'a11ySync'
+/**
+ * Time inside {@link Scene.syncContentGridProjection} materializing DOM
+ * carriers, nested inside `a11ySync`.
+ *
+ * Split out because `a11ySync` for a streaming code block measured 1661-1875 ms
+ * against a 210-671 ms render, and attributing that to grid materialization was
+ * an assumption. Nothing should be optimised here on the strength of the parent
+ * phase alone.
+ */
+ | 'gridMaterialize'
+/**
+ * Whole of {@link Scene.syncContentProjection}, nested inside `a11ySync`.
+ *
+ * Measured at 99.8-99.9% of `a11ySync` for a streaming code block, so per-node
+ * a11y attribute and geometry work is not where that phase's cost lives.
+ */
+ | 'contentProjection'
+/** Per-node a11y attribute/geometry work, excluding content projection and descendants. */
+ | 'a11yNodes'
+/** Whole of `syncContentGridProjection`, of which `gridMaterialize` is one part. */
+ | 'gridSync'
+/**
+ * Synchronous part of `scheduleContentGridCalibration` — building the probe DOM.
+ *
+ * The measurement itself is deferred to a rAF, but the probe is constructed
+ * here. Measured at 77-80% of `gridSync` on Chrome (3.7-4.5 ms per frame, i.e.
+ * the entire 240Hz budget) against about 1 ms on Firefox, making it the largest
+ * remaining cost of projecting a streaming code block once carrier reuse landed.
+ */
+ | 'gridCalibrateSchedule'
+/** The `querySelectorAll` + per-cell scan inside calibration scheduling. */
+ | 'calibScan'
+/** Probe DOM construction and insertion inside calibration scheduling. */
+ | 'calibProbeBuild' | 'a11yOrder'
+/** Sum of every entity's own render(), nested inside drawWalk. */
+ | 'entityPaint';
+export interface RenderPhaseEntry {
+    phase: RenderPhase;
+    totalMs: number;
+    calls: number;
+    avgMs: number;
+    /** Worst single sample — a spiky phase is a different problem from a slow one. */
+    maxMs: number;
+    /** Percent of the measured total, or `null` for the enclosing `render` phase. */
+    share: number | null;
+}
 /**
  * Who marked the scene dirty, and why.
  *
@@ -230,6 +285,43 @@ export declare class Scene {
     renderMode: 'always' | 'onDemand';
     /** Cap on distinct recorded dirty reasons (see `recordDirtyReason`). */
     private static readonly MAX_DIRTY_REASONS;
+    private _phaseTiming;
+    private _phaseTotals;
+    /**
+     * Start or stop per-phase render timing.
+     *
+     * Off by default, and the probes compile to a single boolean test when off:
+     * these sit on the frame path, so the disabled cost has to be nothing. Enable,
+     * run the scene, then read {@link renderPhases}.
+     *
+     * Exists because a frame total cannot tell you where the time went. The
+     * markdown streaming benchmark put render at 85-99% of an append's cost, and
+     * there was no way to decompose that number further — which is exactly the
+     * position that led to two wrong optimisation guesses earlier
+     * (`CodeBlock` reuse, hit-grid fusion), both of which measured as no change.
+     */
+    setPhaseTiming(enabled: boolean): void;
+    /** Whether per-phase render timing is being recorded. */
+    get phaseTiming(): boolean;
+    /**
+     * Accumulate one phase sample.
+     *
+     * Totals rather than a per-frame log: the question is always "which phase owns
+     * the frame", and a log of thousands of samples answers it less directly while
+     * costing far more memory. `maxMs` is kept because a phase that is cheap on
+     * average but spikes is a different problem from one that is uniformly slow.
+     */
+    private _recordPhase;
+    /**
+     * Recorded phase timings, most expensive first, with each phase's share of the
+     * measured total.
+     *
+     * `share` is the number that matters: a phase at 4% cannot be worth optimising
+     * however inefficient it looks in isolation.
+     */
+    get renderPhases(): RenderPhaseEntry[];
+    /** Drop recorded phase timings, keeping timing enabled. */
+    clearRenderPhases(): void;
     private _dirtyTracking;
     private _dirtyReasons;
     private dirty;
@@ -300,6 +392,29 @@ export declare class Scene {
     private contentGridCalibrationFrames;
     /** Detached, untransformed font probes used by the cold calibration pass. */
     private contentGridCalibrationProbes;
+    /**
+     * Monotonic stamp identifying the conditions grid cells were calibrated under.
+     *
+     * Calibration measures the difference between the advance the canvas grid assigns
+     * a cluster and the width the browser lays it out at, then writes a per-cell
+     * `scaleX`. That result stays valid until the font or the page scale changes, and
+     * it lives on the cell element — so a cell carrying this stamp needs no further
+     * work.
+     *
+     * The scan that feeds calibration was O(cells) on every revision bump: for a
+     * streaming code block it re-derived a measurement key for every cell in the
+     * block each frame in order to produce only ~20 distinct keys, costing about
+     * 2.5 ms/frame after the `style.font` fix and still over half of `a11ySync`. Since
+     * carrier reuse (#244) leaves untouched lines — and therefore their calibrated
+     * transforms — in place, cells stamped with the current generation can simply be
+     * skipped, making the scan O(new cells) instead.
+     *
+     * A plain incrementing integer rather than the descriptive calibration key,
+     * because it goes into an attribute selector and must not need escaping.
+     */
+    private contentGridCalibrationGeneration;
+    /** The `(fontEpoch, pageScale)` pair the current generation corresponds to. */
+    private contentGridCalibrationStamp;
     /** Invalidates grid font calibration after browser font availability changes. */
     private contentFontEpoch;
     /** Cached Canvas-to-client scale for the current font/viewport epoch. */
@@ -742,6 +857,15 @@ export declare class Scene {
      */
     private setupGLContextRecovery;
     private endContentSelectionDrag;
+    /**
+     * Index of the carrier line currently holding a selection inside `el`, or
+     * `null`.
+     *
+     * Lets a partial re-materialization decide whether the user's selection is even
+     * affected. Checks the tracked anchor first (it survives a drag) and falls back
+     * to the live DOM selection.
+     */
+    private contentGridSelectionLine;
     private releaseContentSelectionForRebuild;
     /**
      * Rebuild a content-projection element's DOM (`rebuild`) while preserving a
@@ -778,7 +902,26 @@ export declare class Scene {
      * @example scene.add(new CircleEntity());
      */
     add(entity: Entity): this;
+    /**
+     * Reset per-grid calibration and bookkeeping before a (re)materialization.
+     *
+     * @param entityId - Owning entity, keyed into the calibration maps.
+     * @param el - The projection element.
+     * @param releaseSelection - Whether to drop a selection this element owns.
+     *   Pass `false` when carrier lines are being reused: the selection's DOM nodes
+     *   survive the pass, so tearing it down would wipe a user's selection on every
+     *   streamed chunk — the exact bug `preserveContentSelectionAcrossRebuild`
+     *   exists to prevent on the non-grid path.
+     */
     private clearContentGridState;
+    /**
+     * Drop any projected elements under `node` without touching the entity tree.
+     *
+     * Used when the walk reaches an invisible subtree: the entities stay put (a
+     * later `show()` re-projects them), but nothing under here may remain
+     * focusable or announced while hidden.
+     */
+    private pruneA11ySubtree;
     private removeA11yRecursively;
     /**
      * If `el` is about to be removed from the DOM while it holds browser focus,
@@ -867,6 +1010,26 @@ export declare class Scene {
     get rootEntity(): Entity;
     /** The overlay layer root (see {@link showOverlay}), read-only for tooling. */
     get overlayRootEntity(): Entity;
+    /**
+     * Advance and render exactly one frame, synchronously.
+     *
+     * This renders UNCONDITIONALLY: it consults neither {@link renderMode} nor
+     * {@link dirty}, and it does not apply the `always`-mode idle auto-throttle.
+     * That is deliberate — a deterministic driver (video export, a test, a
+     * fixed-step benchmark) asks for a frame because it wants that frame, not a
+     * scheduler opinion about whether it is needed.
+     *
+     * The consequence is a measurement footgun worth stating explicitly: a
+     * benchmark that drives frames through `step()` CANNOT observe frame skipping,
+     * so `always` and `onDemand` produce byte-identical draw counts through this
+     * path. An investigation into whether `onDemand` skips redundant repaints once
+     * concluded "it does not" on exactly that basis; on the real rAF loop the same
+     * workload rendered ~1.0 frames per content change. To measure anything about
+     * scheduling, use {@link start} and let `requestAnimationFrame` drive.
+     *
+     * @param dt Seconds to advance. Not clamped by `MAX_FRAME_DT` — the caller
+     *   chooses the step, since determinism is the point.
+     */
     step(dt: number): void;
     /**
      * Mark the scene as needing a redraw on the next frame.
@@ -875,6 +1038,22 @@ export declare class Scene {
      * entity state outside of {@link Entity.animate} so the change is rendered.
      */
     markDirty(source?: DirtySource): void;
+    /**
+     * Increments whenever the tree's shape changes: add, remove or reparent.
+     *
+     * Already maintained for the resident WASM transform store (see
+     * {@link markStructureChanged}, called from `Entity.add`/`remove`), and exposed
+     * here because a cache of the tree's shape — a DevTools tree model, a serialized
+     * snapshot — is valid exactly as long as this value is unchanged. Comparing it is
+     * O(1) against re-walking the tree, which is what it replaces: DevTools rebuilt
+     * both trees on a fixed 500 ms interval, a constant cost proportional to entity
+     * count, purely because it had no way to ask whether the shape had changed.
+     *
+     * Property changes do NOT bump it. Moving or restyling an entity leaves the
+     * shape intact, so a consumer that also cares about values must read those
+     * directly rather than rebuilding a tree.
+     */
+    get structureVersion(): number;
     /**
      * Record who marked the scene dirty and why.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectojs/core",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "publishConfig": {
     "access": "public"
   },