@vectojs/core 1.32.6 → 1.33.0

package/dist/tree/Scene.d.ts

@@ -14,90 +14,16 @@ import { Entity } from './Entity';
 import { IRenderer } from '../renderer/IRenderer';
 import type { WebGLDrawStats } from '../renderer/WebGLPointRenderer';
 import { type WasmModuleSource, type WasmTransformBackend } from '../wasm/backend';
-import { type CoreWasmRuntime } from '../wasm/runtime';
+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.
- *
- * Every field is optional except `reason` so a call site can be as specific as it
- * cheaply can — an entity id costs nothing to pass, a property name is often
- * already in scope.
- */
-export interface DirtySource {
-    /** Entity id responsible, when one is. Omitted for scene-level invalidation. */
-    entity?: string;
-    /** Short, stable category — e.g. `'text-changed'`, `'animation'`, `'resize'`. */
-    reason: string;
-    /** Property that changed, when the reason alone is ambiguous. */
-    property?: string;
-}
-/** An aggregated dirty attribution. */
-export interface DirtyReasonEntry {
-    entity?: string;
-    reason: string;
-    property?: string;
-    /** How many times this exact attribution was recorded. */
-    count: number;
-    firstFrame: number;
-    lastFrame: number;
-}
+import { type OverlayGeometry } from './scene/CanvasGeometry';
+import { type DirtyReasonEntry, type DirtySource } from './scene/DirtyTracker';
+import { type RenderPhase, type RenderPhaseEntry } from './scene/PhaseTimer';
+import { type AcceleratorReason, type AcceleratorReport, type AcceleratorStatus } from './scene/WasmBackendFacade';
+export type { RenderPhase, RenderPhaseEntry };
+export type { DirtyReasonEntry, DirtySource };
 /**
  * Options for {@link Scene}.
  */
@@ -301,60 +227,7 @@ export interface SceneOptions {
 export declare const SCENE_OPTION_KEYS: readonly ['a11ySyncInterval', 'autoThrottle', 'contentProjection', 'contentProjectionMargin', 'contentSemanticBudget', 'contentSemanticMargin', 'debugA11y', 'disableWindowResize', 'maxDPR', 'maxFPS', 'particleBackend', 'pointBackend', 'readingDirection', 'renderer', 'renderMode', 'respectReducedMotion', 'userTiming'];
 /** 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;
-}
+export type { AcceleratorReason, AcceleratorStatus, AcceleratorReport };
 /**
  * Live render-loop telemetry, read from {@link Scene.frameStats}. See that
  * getter for how each field is measured.
@@ -470,11 +343,16 @@ export declare class Scene {
      *   event-driven UIs where idle frames should cost ~0.
      */
     renderMode: 'always' | 'onDemand';
-    /** Cap on distinct recorded dirty reasons (see `recordDirtyReason`). */
-    private static readonly MAX_DIRTY_REASONS;
-    private _phaseTiming;
-    private _userTiming;
-    private _phaseTotals;
+    /**
+     * Per-phase frame timing and the browser User Timing flag.
+     *
+     * Extracted ahead of extraction 3 because the content-grid calibration pass is
+     * instrumented (`calibScan`, `calibProbeBuild`) and could not move while its
+     * only remaining dependency was a `Scene` private. Nine methods across four
+     * domains write phases, so this is a shared leaf rather than any one domain's
+     * property — see `DEC-0021`.
+     */
+    private readonly phases;
     /**
      * Start or stop per-phase render timing.
      *
@@ -500,15 +378,6 @@ export declare class Scene {
     setUserTiming(enabled: boolean): void;
     /** Whether browser User Timing phase instrumentation is enabled. */
     get userTiming(): 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.
@@ -519,9 +388,24 @@ export declare class Scene {
     get renderPhases(): RenderPhaseEntry[];
     /** Drop recorded phase timings, keeping timing enabled. */
     clearRenderPhases(): void;
-    private _dirtyTracking;
-    private _dirtyReasons;
-    private dirty;
+    /**
+     * The dirty flag and its opt-in attribution (extraction 6, `DEC-0025`).
+     *
+     * A field initializer rather than a constructor assignment: it needs no
+     * injected input, so it follows {@link phases} and {@link a11yOrder} rather
+     * than the definite-assignment collaborators.
+     */
+    private readonly _dirty;
+    /**
+     * The redraw-pending flag, under its original name.
+     *
+     * `Scene.test.ts:2153` assigns `false` and `:2158` reads it, and the suite is
+     * unedited (`DEC-0019` rule 4). `private` is correct here rather than
+     * `protected` — unlike the extraction 1/3/4 accessors, this one still has
+     * in-class readers (`loop`, `step`, `frameStats`).
+     */
+    private get dirty();
+    private set dirty(value);
     /** Whether to throttle rendering to 2 FPS when the scene is static to save power. */
     autoThrottle: boolean;
     /** Wall-clock ms spent inside the last `render()` call. */
@@ -594,33 +478,6 @@ export declare class Scene {
      * {@link Entity.getContentEpoch}. (carryctx CTX-0199)
      */
     private contentSyncState;
-    /** Pending cold font-calibration frame per projected grid entity. */
-    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;
     /**
@@ -681,37 +538,6 @@ export declare class Scene {
     private contentSemanticBudget;
     private contentSemanticBudgetLeft;
     private contentSemanticDeferred;
-    /**
-     * Per-sync memo of "does the document hold a selection at all".
-     *
-     * Reading ANY property of a `Selection` (`anchorNode`, `rangeCount`, `type`,
-     * `isCollapsed`) forces a synchronous layout, because Blink validates the
-     * selection against current box geometry before answering. Measured in real
-     * Chrome against a 1000-carrier subtree with layout dirtied between reads:
-     * `anchorNode` 0.5ms, `rangeCount` 0.4ms, `type` 0.5ms, `isCollapsed` 0.5ms —
-     * all indistinguishable from `offsetHeight` (0.5ms), against a 0ms floor for
-     * mutating without reading. So there is no cheap property to probe with; the
-     * only way to avoid the layout is to not touch the object at all.
-     *
-     * Materializing a block rebuilds its carriers, which asks whether the rebuild
-     * would destroy a selection. Once per block, that read cost a forced layout
-     * over the whole (and growing) projection subtree, which is what made
-     * per-block cost rise with resident count: profiled at 1973 forced layouts
-     * totalling 633ms of an 847ms 1000-block drain (75%).
-     *
-     * A selection is a single document-wide object and a sync walk cannot yield to
-     * the user, so its presence cannot change mid-walk. Resolving it once per walk
-     * turns O(blocks) forced layouts into O(1). `null` = not yet resolved.
-     */
-    private contentSelectionPresentThisSync;
-    /**
-     * True while a text-selection drag that started on a projection's blank
-     * region (no text node under the press) is being driven manually — the
-     * browser has no native anchor for it, so mousemove extends the Selection
-     * from the position we resolved ourselves.
-     */
-    private blankRegionSelectionDrag;
-    private contentSelectionAnchor;
     private contentSelectionEndListener;
     private frameHadAnimation;
     private frameHadInteractive;
@@ -729,10 +555,25 @@ export declare class Scene {
     private canvasResizeObserver;
     private dprChangeHandler;
     private focusedA11yElement;
-    /** Last geometry `syncOverlayGeometry` wrote, so an unchanged frame can skip the
-     *  style writes entirely. Reset to `null` to force the next sync (a new overlay
-     *  layer was created and has never been positioned). */
-    private _overlayGeometry;
+    /**
+     * Canvas box geometry: the CSS↔logical mapping, overlay layer alignment, and
+     * the DPR math (extraction 5, `DEC-0024`).
+     *
+     * Definite-assignment because it holds `a11yRoot` and `portalRoot`, which the
+     * constructor only decides partway through — the same shape as
+     * {@link _contentProjection}.
+     */
+    private _geometry;
+    /**
+     * The overlay memo, for the unedited suite.
+     *
+     * `OverlayGeometrySkip.test.ts:75,143` assigns `null` to force the next sync,
+     * so the setter delegates to `invalidateOverlay()`. `protected` rather than
+     * `private` because it has no in-class reader and `noUnusedLocals` fails the
+     * build on a private with none (`DEC-0019` rule 4).
+     */
+    protected get _overlayGeometry(): OverlayGeometry | null;
+    protected set _overlayGeometry(value: OverlayGeometry | null);
     /** Shadow elements the pointer is currently inside. Lets a removal that happens
      *  mid-hover synthesize the `pointerleave` the browser never sends for a
      *  detached element, so the entity doesn't keep its hover state. */
@@ -751,33 +592,60 @@ export declare class Scene {
      *  screen-reader virtual cursor inside the scene's a11y region. */
     private focusSentinel;
     private caretBlinkTimer;
-    a11yNeedsReorder: boolean;
-    private portalRoot;
-    private fullViewportElements;
-    private normalElements;
-    private activeIds;
-    /** Per-parent insertion cursor, reused by `enforceA11yDomOrder`. */
-    private a11yOrderCursors;
-    /** Membership set for the elements being ordered, reused per reorder pass. */
-    private a11yOrderMembers;
     /**
-     * Elements that are an *ancestor* of another ordered element, reused per pass.
+     * The projected DOM's ordering engine — the reorder flag, the per-pass scratch
+     * collections, the visual reading-order sort and the cursor-based
+     * `insertBefore` pass (extraction 2, `DEC-0020`).
+     *
+     * `a11yNeedsReorder` and `enforceA11yDomOrder` keep their names on `Scene` and
+     * delegate here; the collect-and-prune walk stays behind because it needs
+     * {@link shouldProjectA11y} and the focus/caret state.
+     */
+    private readonly a11yOrder;
+    /**
+     * The content projection's selection preservation and grid calibration
+     * (extraction 3, `DEC-0022`).
+     *
+     * Definite-assignment because it needs `a11yRoot`, which the constructor
+     * creates partway through — the same shape as {@link _wasmBackend}. Every
+     * constructor use is inside a deferred event listener, so it is always
+     * assigned before anything can reach it.
+     */
+    private _contentProjection;
+    /** Grid carrier materialization (the projection walk's separable leaf). */
+    private _gridProjector;
+    /**
+     * Pending grid-calibration frames, keyed by entity id.
+     *
+     * Delegates to {@link ContentProjectionManager}. Kept on `Scene` under its
+     * original name because the text-projection e2e reads
+     * `scene.contentGridCalibrationFrames.size` to assert calibration is not left
+     * in flight after a rebuild. `protected` rather than `private`: there is no
+     * in-class reader, and `private` plus no reader fails `noUnusedLocals`
+     * (`DEC-0019` rule 4).
+     */
+    protected get contentGridCalibrationFrames(): ReadonlyMap<string, number>;
+    /**
+     * Index of the carrier line holding a selection inside `el`, or `null`.
      *
-     * A composite widget's container (a `grid` around its rows, a `tree` around its
-     * items) spans every descendant row, so it must not extend a visual row band —
-     * see {@link sortNormalElementsVisually}.
+     * Delegates to {@link ContentProjectionManager}. Kept under its original name
+     * because `ContentGridSelectionWindow.test.ts` calls it through a cast to
+     * assert the selection-window behaviour. `protected` per `DEC-0019` rule 4 —
+     * the in-class callers now go through the manager directly.
      */
-    private a11yOrderContainers;
+    protected contentGridSelectionLine(el: HTMLElement): number | null;
     /**
-     * Nearest `clipChildren` ancestor per ordered element — its *region* — reused
-     * per pass. Written by `enforceA11yDomOrder`'s collect walk, which already has
-     * the entity in hand, so a region costs one comparison per node rather than an
-     * ancestor walk per element.
+     * Whether the projected a11y DOM needs reordering on the next pass.
      *
-     * Absent means the element sits under no clipping ancestor and belongs to the
-     * implicit root region. See {@link sortNormalElementsVisually}.
+     * Delegates to {@link A11yProjectionManager}. Kept on `Scene` under its
+     * original name — and with a setter — because `Entity` assigns to
+     * `scene.a11yNeedsReorder` as a public cross-class contract (`Entity.ts` sets
+     * it when `interactive` flips and when a child is added or removed), and the
+     * unedited suite writes it directly too.
      */
-    private a11yOrderRegions;
+    get a11yNeedsReorder(): boolean;
+    set a11yNeedsReorder(value: boolean);
+    private portalRoot;
     private activePortalsThisFrame;
     private activePortalsPrevFrame;
     private portalEntities;
@@ -791,14 +659,58 @@ export declare class Scene {
      * `_setWorldCache` are: it is a cross-class render-internal contract.
      */
     currentFrame: number;
-    private _wasm;
-    private _transformBackend;
-    private _treeStore;
-    private _slotEntity;
-    private _wasmInputs;
-    private _wasmWorld;
-    private _structureVersion;
-    private _storeStructureVersion;
+    /**
+     * The four invisible WASM accelerators and the resident transform store.
+     *
+     * Extraction 1 of this file's decomposition. Every public member below keeps
+     * its name, signature and behaviour and delegates here, so the public API is
+     * byte-identical; only where the state lives changed.
+     *
+     * Constructed in the constructor rather than initialized here because it needs
+     * {@link root}, which is itself assigned there.
+     */
+    private _wasmBackend;
+    /**
+     * The transform backend object itself.
+     *
+     * Kept under its original name and delegating, rather than deleted:
+     * `test/wasm/scene-accelerators.test.ts` reaches for `scene._wasm` to
+     * monkey-patch a kernel into rejecting, and that unedited suite is this
+     * refactor's gate — rewriting it to match the new shape would be marking our
+     * own homework. Same reasoning for `_animWasm`, `_wasmUploadRejections`,
+     * `_storeStructureVersion` and `_structureVersion` below.
+     *
+     * `protected` rather than `private` since extraction 4: the hit-grid build was
+     * this getter's last in-class reader, and `private` plus no reader fails
+     * `noUnusedLocals` (`DEC-0019` rule 4).
+     * @internal
+     */
+    protected get _wasm(): WasmTransformBackend | null;
+    /** @internal Read by the WASM anim suites; see {@link _wasm}. */
+    private get _animWasm();
+    /**
+     * @internal
+     * `protected`, not `private`, and that is the one deliberate access change in
+     * this extraction. Both of these are read by a test and by nothing inside this
+     * class, so `private` makes them dead code and `noUnusedLocals` rejects the
+     * build. `protected` is the honest encoding of "exists to be read from
+     * outside, never from in here" — and it is invisible to API consumers, who
+     * cannot reach a protected member either. `Scene` has no subclasses in this
+     * repo and is not documented as subclassable.
+     *
+     * Read by the run-table fallback suite; see {@link _wasm}.
+     */
+    protected get _wasmUploadRejections(): number;
+    /** @internal Read by the resident-store suite; see {@link _wasmUploadRejections}. */
+    protected get _storeStructureVersion(): number;
+    /**
+     * Tree topology version, bumped by every add/remove/reparent.
+     *
+     * Lives on the facade because the resident store layout is keyed by it, but is
+     * read here by the compute-entity cache below and by `Scene.test.ts`.
+     * @internal
+     */
+    private get _structureVersion();
     private _computeEntities;
     private _computeEntitiesVersion;
     /** Invalidate the resident WASM store layout; the next wasm-mode frame rebuilds
@@ -837,25 +749,6 @@ export declare class Scene {
      * Resolves `true` if WASM is now active, `false` if the JS path remains.
      */
     enableWasmTransforms(source: WasmModuleSource): Promise<boolean>;
-    /**
-     * The one WASM instance this Scene's accelerators share.
-     *
-     * Each `enableWasm*` used to instantiate the binary itself, so enabling all
-     * four compiled the same module four times and held four linear memories. The
-     * Rust crate already keeps transform/anim/hit/particle in separate statics, so
-     * one instance serves all of them without aliasing. The compiled module is
-     * cached globally; the instance is per-Scene, which is the isolation that
-     * actually matters.
-     */
-    private _wasmRuntime;
-    /**
-     * Load (or reuse) this Scene's shared WASM runtime.
-     *
-     * Returns `null` on any failure — CSP `wasm-unsafe-eval`, a 404, corrupt bytes,
-     * unsupported SIMD — so every caller keeps its JS path. Failure is the default
-     * state here, not an error path.
-     */
-    private ensureWasmRuntime;
     /**
      * Install a pre-built runtime, so several Scenes can share one compile while
      * each keeps its own stores. Pass `null` to detach (backends already installed
@@ -864,46 +757,17 @@ export declare class Scene {
     setWasmRuntime(runtime: CoreWasmRuntime | null): void;
     /** The shared WASM runtime, if one has been loaded. */
     get wasmRuntime(): CoreWasmRuntime | null;
-    private _hitWasm;
-    private _hitGridFrame;
-    private _hitGridOk;
-    private _hitSlotEntity;
-    private _hitBoundless;
-    /** Reused buffer for the fused gather, so a pointer query allocates nothing. */
-    private _hitGatherBuffer;
     /**
-     * Whether the last grid build sourced its AABBs from the WASM transform store
-     * rather than recomputing them in JS. Diagnostic only — both paths must
-     * produce the same entity for a given point.
-     */
-    private _hitFusedGather;
-    /**
-     * Whether `compute_aabbs` has run against the current frame's world matrices.
-     * The AABB pass is only meaningful after a `compose_*`, so the fused gather
-     * must not read the views before then.
+     * The pointer hit-test: the WASM broad-phase grid, the permanent JS
+     * depth-first walk, and the eligibility gating that keeps the two in lockstep
+     * (extraction 4, `DEC-0023`).
+     *
+     * Definite-assignment because it needs {@link _wasmBackend}, which is built
+     * partway through the constructor.
      */
-    private _wasmAabbsFresh;
+    private _hitTester;
     /** 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.
@@ -918,6 +782,10 @@ export declare class Scene {
      *
      * Reflects the most recent main-renderer frame; a secondary renderer (SVG
      * export, offscreen snapshot) does not overwrite it.
+     *
+     * `webgpuActive` is handed to the facade rather than read by it: WebGPU device
+     * state belongs to the context/resize domain (extraction 5), and this getter
+     * is the only place the two domains have to agree.
      */
     get accelerators(): AcceleratorReport;
     /** Which backend answers `findEntityAt` for the main tree. */
@@ -934,34 +802,23 @@ export declare class Scene {
      */
     enableWasmHitTest(source: HitModuleSource): Promise<boolean>;
     /**
-     * Refresh the hit-test grid for the CURRENT tree state if it is stale (a
-     * structural or transform change may have happened since the last build —
-     * there is no cheap "nothing moved" shortcut for a spatial index the way
-     * there is for the transform store's topology-only run table, since ANY
-     * entity moving invalidates its AABB, not just add/remove/reparent; the
-     * measured build cost is cheap enough to redo per call). Returns `false`
-     * (grid untrustworthy — caller must use the JS walk) when there is no
-     * backend or the build overflowed its item budget.
-     */
-    private _ensureHitGrid;
-    /**
-     * `findEntityAt`'s WASM-accelerated path for the main tree. Scans only the
-     * queried cell's candidates (confirming each against its own AABB and precise
-     * `isPointInside`) merged against the (typically empty or tiny) list of
-     * entities with no `getBounds()`, taking whichever confirmed match has the
-     * higher pre-order index — see hit-store.ts for why that is exactly
-     * equivalent to findHitRecursively's topmost-hit priority. Always
-     * conclusive: returns the correct entity or `null`, never "inconclusive".
-     */
-    private _findEntityAtWasm;
-    private _animWasm;
-    private _activeDriverEntities;
-    private _springEntities;
-    private _springProps;
-    private _springDrivers;
-    private _tweenEntities;
-    private _tweenProps;
-    private _tweenDrivers;
+     * The batched driver tick and its candidate registry (extraction 6,
+     * `DEC-0025`).
+     *
+     * Definite-assignment because it holds {@link _wasmBackend}, which is built
+     * partway through the constructor — the same shape as {@link _hitTester}.
+     */
+    private _driverTicker;
+    /**
+     * The candidate set, for the unedited suite.
+     *
+     * `test/wasm/scene-anim-batch.test.ts` reads it through a cast at four sites to
+     * assert the registry self-prunes, unregisters a removed subtree, and
+     * re-registers a re-added one. `protected` rather than `private` because it has
+     * no in-class reader and `noUnusedLocals` fails the build on a private with
+     * none (`DEC-0019` rule 4).
+     */
+    protected get _activeDriverEntities(): Set<Entity>;
     /**
      * Minimum number of batchable (spring, or named-easing tween) active drivers
      * before a frame engages the WASM batch path at all; below it, every driver
@@ -1029,7 +886,6 @@ export declare class Scene {
      * Setting {@link animDriverGateCount} overwrites all three, so existing code
      * that tuned the single knob keeps working unchanged.
      */
-    private _animBatchedLastFrame;
     /**
      * Whether the WASM batch path actually ran on the most recent frame.
      *
@@ -1060,7 +916,6 @@ export declare class Scene {
      * if WASM is now available (not necessarily active every frame).
      */
     enableWasmAnimBatching(source: AnimModuleSource): Promise<boolean>;
-    private _particleWasm;
     /** Which backend runs the CPU particle simulation. Reflects only whether a
      *  backend is installed (the WebGPU compute path, when active, is used first
      *  regardless). */
@@ -1113,25 +968,6 @@ export declare class Scene {
      * pre-pass.
      */
     private _tickBatchedDrivers;
-    /**
-     * Compose the whole main tree's world matrices through the resident WASM store
-     * and return the world-matrix views for the render walk to read. Rebuilds the
-     * store layout (slots + runs) only when the tree structure changed since the
-     * last rebuild; otherwise it just gathers current transforms into the resident
-     * input view and runs the kernel. Returns `null` if there is no backend.
-     */
-    private _syncWasmStore;
-    /**
-     * Run the WASM world-AABB pass over the current frame's world matrices, so the
-     * fused hit gather can read AABBs straight out of the store.
-     *
-     * Local bounds are uploaded here rather than in the per-frame transform sync
-     * because `getBounds()` is a virtual call that allocates a rect on most
-     * entities — paying it every frame for a query that may never come would move
-     * cost onto the render path to save it on hover. Returns `false` if any entity
-     * cannot supply bounds through the store, so the caller uses the JS gather.
-     */
-    private _ensureWasmAabbs;
     /**
      * Authoritative paint order for semantic nodes discovered during the main
      * render. A node may not have a DOM projection until the following a11y
@@ -1188,6 +1024,16 @@ export declare class Scene {
      *  else the canvas). Stored so `destroy()` detaches from the same element. */
     private pointerEventTarget;
     private hasWarnedZeroSize;
+    /**
+     * Latch for {@link Scene.resize}'s invalid-dimension warning.
+     *
+     * Separate from `hasWarnedZeroSize`: that one fires for a tolerated zero-size
+     * scene at `start()`, this one for a rejected resize, and sharing the flag
+     * would let either suppress the other's first (and only) report. Latched
+     * because `resize()` is commonly driven from a `ResizeObserver`, which would
+     * otherwise warn on every frame of a drag.
+     */
+    private hasWarnedInvalidResize;
     private fontLoadHandler;
     private static _devMode;
     /**
@@ -1245,48 +1091,22 @@ export declare class Scene {
      *     on the same canvas, restore DPR/size, and repaint.
      */
     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;
-    /**
-     * Does the document hold a selection right now, memoized for this sync walk?
-     *
-     * Pays one forced layout per walk instead of one per rebuilt element — see
-     * {@link Scene.contentSelectionPresentThisSync} for the measurements. When the
-     * answer is `false` no element can own a selection, so every per-element
-     * ownership test can be skipped without touching the object.
-     */
-    private contentSelectionPresent;
-    private releaseContentSelectionForRebuild;
-    /**
-     * Rebuild a content-projection element's DOM (`rebuild`) while preserving a
-     * text selection the user made inside it. A streaming message replaces its
-     * projection children on every appended chunk; without this, a selection in
-     * the UNCHANGED prefix is wiped on each frame ("can't select text in a
-     * message still receiving tokens"). We snapshot the selection's anchor/focus
-     * as linear character offsets within `el` before the rebuild and re-resolve
-     * them against the new DOM after, clamped to the new text length.
-     *
-     * Only fires when `el` owns the current selection and there is no active drag
-     * (mid-drag the browser is authoritative). The virtualization case — where
-     * `el` itself is removed from the DOM — is out of scope here (the node is
-     * genuinely freed; the browser clears the selection and there is nothing to
-     * restore against).
-     */
-    private preserveContentSelectionAcrossRebuild;
     /**
      * Expose the underlying {@link IRenderer} for advanced direct-draw operations.
      *
      * @returns The active renderer instance.
      */
     getRenderer(): IRenderer;
+    /**
+     * Finds the topmost interactive entity at the given coordinates.
+     *
+     * Delegates to {@link HitTester}. The frame stamp and the logical size are
+     * passed in rather than reached for: `currentFrame` is the scheduler's
+     * (extraction 6) and `width`/`height` are mutated by `resize`
+     * (extraction 5), so neither can be captured at construction
+     * (`DEC-0019` rule 5).
+     */
+    findEntityAt(x: number, y: number): Entity | null;
     /** Convert browser viewport coordinates into this Scene's logical coordinates. */
     clientToScene(clientX: number, clientY: number): {
         x: number;
@@ -1300,18 +1120,6 @@ 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.
      *
@@ -1376,7 +1184,8 @@ export declare class Scene {
     /**
      * Begin the `requestAnimationFrame` render loop.
      *
-     * Idempotent — calling `start()` on an already-running scene is a no-op.
+     * Idempotent — calling `start()` on an already-running scene is a no-op, and so
+     * is calling it on a destroyed one.
      */
     start(): void;
     /** Schedule the next frame, or no-op where `requestAnimationFrame` is absent (SSR). */
@@ -1465,13 +1274,6 @@ export declare class Scene {
      * directly rather than rebuilding a tree.
      */
     get structureVersion(): number;
-    /**
-     * Record who marked the scene dirty and why.
-     *
-     * Kept separate from {@link markDirty} so the hot path is not a function call
-     * with a branch — V8 inlines the one-field version reliably.
-     */
-    private recordDirtyReason;
     /**
      * Start or stop recording dirty attributions.
      *
@@ -1649,49 +1451,15 @@ export declare class Scene {
      */
     private projectionVisibleLocalYBand;
     private syncContentProjection;
-    /**
-     * Materialize a prepared grid in logical source order while positioning each
-     * carrier from the shared canvas geometry. Browser font measurement happens
-     * later in one cold read/write batch, never inside projection synchronization.
-     */
-    private syncContentGridProjection;
     private getContentMetricScaleX;
-    private scheduleContentGridCalibration;
     private enforceA11yDomOrder;
     /**
-     * Reorder `normalElements` (in place) into visual reading order using the
-     * 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.
-     *
-     * Banding runs **per region** — per nearest `clipChildren` ancestor, recorded
-     * by {@link enforceA11yDomOrder}'s collect walk — rather than once over the
-     * whole scene. Purely visual banding is right for a screen reader but wrong
-     * for selection: a DOM `Selection` covers everything between anchor and focus
-     * in DOM order, so under one global banding a vertical drag through a
-     * transcript also swallowed a sidebar whose headings happened to fall in the
-     * same rows. Regions are laid out side by side, so ordering region-major keeps
-     * each one a contiguous DOM run and a drag stays inside it, while reading
-     * order *within* a region is unchanged. Regions are emitted in the order their
-     * clipper is first reached by the depth-first walk, so a screen reader still
-     * meets them in the author's declared order.
-     */
-    private sortNormalElementsVisually;
-    /** Keep DOM/WebGL overlay layers aligned with the canvas's CSS box. */
+     * Keep DOM/WebGL overlay layers aligned with the canvas's CSS box.
+     *
+     * The logical size and the lazily-created layers are threaded through rather
+     * than held: `resize` mutates `width`/`height`, and `gpuCanvas` does not exist
+     * until the WebGPU particle path first runs (`DEC-0019` rule 5).
+     */
     private syncOverlayGeometry;
     getA11yTree(): A11yTreeNode[];
     private renderPortalDOM;
@@ -1737,11 +1505,12 @@ export declare class Scene {
     toSVG(): string;
     /**
      * Manually resize the Scene's viewport.
+     *
+     * Rejects a negative or non-finite dimension, keeping the last known-good
+     * size. `0` is accepted: a zero-size scene is tolerated and warned about at
+     * {@link start} instead, and rejecting it here would contradict that.
      */
     resize(width: number, height: number): void;
-    /** Effective device pixel ratio, matching CanvasRenderer: real DPR clamped to
-     *  `maxDPR` when set. */
-    private effectiveDPR;
     /** Size the WebGPU particle canvas: backing store at logical × DPR, CSS box at
      *  the logical size. Sizing the backing store in logical px (the old
      *  behavior) left it rasterized at 1× and CSS-stretched — blurry on HiDPI. */
@@ -1756,29 +1525,10 @@ export declare class Scene {
      * Gets the root entity of the scene.
      */
     getRoot(): Entity;
-    /**
-     * Finds the topmost interactive entity at the given coordinates.
-     */
-    findEntityAt(x: number, y: number): Entity | null;
     /** Submit one transparent clear pass when particle content lingers on the GPU canvas. */
     private clearGPUCanvasIfStale;
     private initWebGPUContext;
     private setupDeviceLostHandler;
     private recreateWebGPUDeviceWithRetry;
     private renderCPUParticles;
-    private findHitRecursively;
-    /** Whether `node` opts out of being a pointer hit target: a disabled control
-     *  or an explicit `pointerEvents: 'none'` in its a11y attributes. Its children
-     *  are still walked (a transparent container can hold hittable descendants). */
-    private isPointerTransparent;
-    /**
-     * Whether a confirmed geometric hit on `node` at world `(x, y)` is a REAL hit,
-     * applying the same visibility/input gating as {@link findHitRecursively} but
-     * from a flat candidate (the WASM grid has no recursion clip-stack): the node
-     * and all ancestors are visible (`opacity > 0`), the point lies inside every
-     * `clipChildren` ancestor's world box, and the node isn't pointer-transparent
-     * (disabled / `pointerEvents: 'none'`). Keeps the WASM and JS hit paths in
-     * lockstep so they return the same entity.
-     */
-    private isHitEligible;
 }