@vectojs/core 1.32.7 → 1.34.0

package/dist/tree/scene/DriverTicker.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The batched property-driver tick: which entities have drivers in flight, and
+ * advancing them for one frame.
+ *
+ * Extraction 6 of the `Scene.ts` decomposition
+ * (`forge/decisions/file-decomposition-2026-08.md` §2), shipped at **heavily
+ * reduced scope** — see `DEC-0025` for the per-member measurement. The decided
+ * `RenderScheduler` scope named nine members and 989 lines; `loop` and `render`
+ * are not movable at all, so what ships is the two separable sub-clusters this
+ * file and {@link DirtyTracker} own.
+ *
+ * ## What this owns
+ *
+ * The candidate registry (`_activeDriverEntities`), the six reused scratch
+ * arrays, and the batch pass itself. The registry is the reason the pass is
+ * O(active drivers) rather than O(tree size), so registration and ticking are one
+ * domain: every write to the set exists to serve the walk that reads it.
+ *
+ * ## What is held, and what is passed in
+ *
+ * {@link WasmBackendFacade} is held: it is assigned once in `Scene`'s constructor
+ * and the anim backend is reached only through its public surface (`anim`,
+ * `animReason`, `animBatchedLastFrame`), exactly as `HitTester` reaches the hit
+ * backend.
+ *
+ * `dt`, the per-kind `gate` and `currentFrame` are per-call arguments
+ * (`DEC-0019` rule 5):
+ *
+ * - `currentFrame` is written by `render` and belongs to the frame loop, which
+ *   did not move.
+ * - `gate` is `Scene.animGate`, a **public mutable field** that tests and
+ *   benchmarks assign directly (`scene.animGate = { … }` at 8 sites, plus the
+ *   `animDriverGateCount` alias setter). Holding it would both go stale and force
+ *   the public field to become an accessor pair, which this sequence exists to
+ *   avoid.
+ *
+ * ## What deliberately did not move
+ *
+ * `_tickBatchedDrivers`'s caller. `render` (575 lines) calls twelve `Scene`
+ * methods spanning six domains, and `loop` calls `render`, `syncA11y` and
+ * `enforceA11yDomOrder`. Both would need a `Scene` back-edge, which `DEC-0019`
+ * rule 1 forbids and which `DEC-0020` and `DEC-0021` already refused in the
+ * bound-callback form.
+ */
+import { Entity } from '../Entity';
+import type { WasmBackendFacade } from './WasmBackendFacade';
+/** Per-kind driver gates, in active batchable drivers. See `Scene.animGate`. */
+export interface AnimDriverGate {
+    spring: number;
+    tween: number;
+    mixed: number;
+}
+export declare class DriverTicker {
+    private readonly backends;
+    private readonly activeEntities;
+    private springEntities;
+    private springProps;
+    private springDrivers;
+    private tweenEntities;
+    private tweenProps;
+    private tweenDrivers;
+    constructor(backends: WasmBackendFacade);
+    /** The candidate set, for the delegating accessor `Scene` keeps for its tests. */
+    get active(): Set<Entity>;
+    /** Register a single entity whose driver has just started. */
+    register(entity: Entity): void;
+    /**
+     * Drop `entity` and its whole subtree from the batched-driver candidate set.
+     * Called by `Scene.remove`/`Scene.hideOverlay` on detach: without this a
+     * removed-but-still-animating entity stays pinned in the Set (a leak) and its
+     * drivers keep ticking every frame even though it is off-tree. If it is later
+     * re-added, {@link registerSubtree} re-registers any node that still has live
+     * drivers, so the motion resumes.
+     */
+    unregisterSubtree(entity: Entity): void;
+    /**
+     * Re-register every node in `entity`'s subtree that still has live property
+     * drivers. Called by `Scene.add`/`Scene.showOverlay` so re-attaching a subtree
+     * that was removed mid-animation resumes its batched drivers (they were
+     * dropped from the candidate set on removal, but the driver state still lives
+     * on each entity).
+     */
+    registerSubtree(entity: Entity): void;
+    /**
+     * Advance every registered entity's active drivers for this frame, batching
+     * whichever are batchable (`SpringDriver`; `TweenDriver` with a named
+     * easing) through one WASM call each when the driver-count gate is open, and
+     * ticking the rest (a `TweenDriver` using a custom `EasingFn`) directly in
+     * JS regardless of the gate. A "claimed" entity must have ALL its drivers
+     * advanced here so it can be safely stamped `_driversTickedFrame` — leaving
+     * one unclaimed would silently stall it, since `tickDrivers()` skips the
+     * whole entity once stamped.
+     *
+     * Must run before ANY entity's `update()`/`tickDrivers()` this frame (see
+     * the call site in `Scene.render`) — the same ordering constraint G1 Stage 4
+     * discovered: a value this pass writes must be final before anything reads
+     * it, including the JS-mode interleaved walk and the WASM-mode transform
+     * pre-pass.
+     */
+    tick(dt: number, gate: AnimDriverGate, currentFrame: number): void;
+}

package/dist/tree/scene/HitTester.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Pointer hit-testing: which entity is under a point, by two paths that must
+ * agree.
+ *
+ * Extraction 4 of the `Scene.ts` decomposition
+ * (`forge/decisions/file-decomposition-2026-08.md` §2). `Scene.findEntityAt`
+ * keeps its name and signature and delegates here.
+ *
+ * ## The two paths, and why both exist
+ *
+ * The **JS depth-first walk** ({@link findHitRecursively}) is the permanent
+ * fallback and the definition of correct: children in reverse draw order,
+ * topmost hit wins, clipped by every `clipChildren` ancestor.
+ *
+ * The **WASM broad phase** ({@link findEntityAt}'s accelerated arm) asks a
+ * spatial grid for one cell's candidates. It is flat, so it has no recursion
+ * clip-stack, which is why {@link isHitEligible} re-applies the same
+ * visibility/clip/pointer gating the walk gets structurally. Keeping those two
+ * in lockstep is the whole correctness argument for having a second path — if
+ * they can disagree, the accelerator is a bug generator rather than an
+ * optimisation.
+ *
+ * ## What this owns
+ *
+ * The hit-grid *contents* — the slot→entity table, the boundless list, and the
+ * reused fused-gather buffer. The cache *key* (`hitGridFrame`, `hitGridOk`) stays
+ * on {@link WasmBackendFacade}, because installing a backend has to invalidate
+ * it and that is the facade's business.
+ *
+ * ## What it deliberately does not own
+ *
+ * `clientToScene` and `setupEvents` sit under hit-test banners but are not hit
+ * testing:
+ *
+ * - `clientToScene` maps browser viewport coordinates to logical ones from
+ *   `canvas`, `width` and `height` — all `ContextAndResize` state (extraction 5).
+ * - `setupEvents` wires the window resize listener, the embedded-canvas
+ *   `ResizeObserver`, the DPR watch, and the pointer listeners that write
+ *   `mouseX`/`mouseY`. Almost all of it is resize and canvas lifecycle.
+ *
+ * That is a fifth instance of `DEC-0016`'s finding that the domain banners
+ * expose wrong cuts — the same shape as `syncOverlayGeometry` in extraction 2.
+ *
+ * ## What is passed in, and why
+ *
+ * `root` and `overlayRoot` are held: `Scene` assigns both once in its constructor
+ * and never reassigns them. The facade is held because the hit backend is reached
+ * only through its public surface (`hit`, `hitReason`, `hitGridFrame`,
+ * `hitGridOk`, `ensureAabbs()`, `slotEntity`, `hitFusedGather`, `transform`).
+ *
+ * The frame counter and the viewport size are **per-call arguments** (`DEC-0019`
+ * rule 5): `currentFrame` belongs to the render scheduler (extraction 6) and
+ * `width`/`height` are mutated by `resize` (extraction 5), so neither can be
+ * captured at construction without going stale.
+ */
+import type { Bounds, Entity } from '../Entity';
+import type { WasmBackendFacade } from './WasmBackendFacade';
+export declare class HitTester {
+    private readonly root;
+    private readonly overlayRoot;
+    private readonly backends;
+    /** Slot index → entity, as built by the most recent grid build. */
+    private slotEntity;
+    /** Entities with no `getBounds()`, which the grid cannot index. */
+    private boundless;
+    /** Reused buffer for the fused gather, so a pointer query allocates nothing. */
+    private gatherBuffer;
+    constructor(root: Entity, overlayRoot: Entity, backends: WasmBackendFacade);
+    /**
+     * Finds the topmost interactive entity at the given coordinates.
+     *
+     * @param frame - `Scene.currentFrame`, the grid cache key's frame stamp.
+     * @param width - Scene logical width, for the grid's extent.
+     * @param height - Scene logical height, for the grid's extent.
+     */
+    findEntityAt(x: number, y: number, frame: number, width: number, height: number): Entity | null;
+    /**
+     * 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.
+     */
+    ensureHitGrid(frame: number, width: number, height: number): boolean;
+    /**
+     * `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;
+    findHitRecursively(node: Entity, x: number, y: number, clip?: Bounds | null): Entity | null;
+    /** 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;
+}

package/dist/tree/scene/PhaseTimer.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Per-phase frame timing: which phase owned the frame, and how the samples add
+ * up.
+ *
+ * A **shared leaf** of the `Scene.ts` decomposition rather than one of the six
+ * domain collaborators. It is extracted ahead of extraction 3 because the
+ * content-projection calibration pass records two of its own phases
+ * (`calibScan`, `calibProbeBuild`) and cannot move while the only way to reach
+ * the accumulator is `Scene._recordPhase`. Handing a collaborator
+ * `scene._recordPhase.bind(scene)` would put a `Scene` reference inside a
+ * closure, which is the violation of `DEC-0019` rule 1 that `DEC-0020` refused
+ * for `syncA11y`. A shared object that nobody's `Scene` is reachable through has
+ * neither problem: `Scene` owns one of these, and each collaborator that records
+ * a phase holds the same instance.
+ *
+ * Nine methods across four domains read the enable flag today — the render walk,
+ * the frame loop, the a11y sync, the content projection and its grid pass, the
+ * calibration scheduler — so this would have had to become shared state at
+ * whichever extraction reached it first regardless.
+ *
+ * ## Why totals rather than a log
+ *
+ * The question is always "which phase owns the frame". A per-frame log of
+ * thousands of samples answers that less directly and costs 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.
+ *
+ * ## The disabled path must cost nothing
+ *
+ * These probes sit on the frame path, so {@link enabled} is a plain boolean field
+ * and every call site is expected to test it before doing any timing work —
+ * including the `performance.now()` calls themselves.
+ */
+/**
+ * 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;
+}
+export declare class PhaseTimer {
+    /**
+     * Whether per-phase timing is being recorded.
+     *
+     * A field rather than an accessor: it is tested on the frame path once per
+     * probe, and the disabled cost has to be a single boolean read.
+     */
+    enabled: boolean;
+    /** Whether browser User Timing instrumentation is enabled. */
+    userTiming: boolean;
+    private readonly totals;
+    /** Start or stop recording. Disabling also drops what was collected. */
+    setEnabled(enabled: boolean): void;
+    /** Accumulate one phase sample. */
+    record(phase: RenderPhase, ms: number): void;
+    /**
+     * 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 entries(): RenderPhaseEntry[];
+    /** Drop recorded timings, keeping recording enabled. */
+    clear(): void;
+}

package/dist/tree/scene/WasmBackendFacade.d.ts

@@ -0,0 +1,271 @@
+/**
+ * The four invisible WASM accelerators, and the per-frame report that describes
+ * what each of them actually did.
+ *
+ * Extraction 1 of the `Scene.ts` decomposition
+ * (`forge/decisions/file-decomposition-2026-08.md` §2). `Scene` keeps every
+ * public method and getter it had — `setTransformBackend`, `enableWasmHitTest`,
+ * `accelerators`, and the rest — and each one now delegates here. The public API
+ * is byte-identical; only where the state lives changed.
+ *
+ * ## What this owns, and what it deliberately does not
+ *
+ * It owns the four backend handles, the shared runtime, the resident transform
+ * store, and every field the accelerator report reads.
+ *
+ * It does NOT own three things that sit inside `Scene.ts`'s WASM comment region
+ * but belong to other domains — the domain banners were added first precisely to
+ * make that visible before any code moved (carryctx `DEC-0016`):
+ *
+ * - `_ensureHitGrid` / `_findEntityAtWasm` are the hit-test broad phase
+ *   (`HitTester`, extraction 4). They *read* this facade.
+ * - `_tickBatchedDrivers` is the scheduler's batched driver tick
+ *   (`RenderScheduler`, extraction 6). It reads the anim backend from here.
+ * - `_computeEntitiesFor` walks the tree for `ComputeParticleEntity` instances
+ *   and is consumed by the render walk. Only its cache key — the structure
+ *   version — is store state, so the version lives here and the walk stays on
+ *   `Scene`.
+ *
+ * ## Why the reporting fields live here rather than with their writers
+ *
+ * `transformReason` is written by the render walk, `animReason` by the driver
+ * tick, `hitReason` by the hit-grid build, `particleReason` by the particle
+ * pass — four domains, four different extractions. They are collected here
+ * anyway because {@link report} is the single reader that has to make them
+ * consistent, and splitting them across four collaborators would leave that one
+ * getter reaching into all four. Each writer sets its own field through a public
+ * property on this object; none of them touches `Scene`'s privates.
+ *
+ * ## The one fact this cannot know
+ *
+ * `particle.available` is true when a WASM particle backend is installed **or**
+ * WebGPU is live, and WebGPU device state belongs to `ContextAndResize`
+ * (extraction 5). So {@link report} takes it as an argument rather than
+ * reaching for it. That is the whole of this facade's dependency on the rest of
+ * `Scene`.
+ */
+import type { Entity } from '../Entity';
+import { type WasmTransformBackend } from '../../wasm/backend';
+import { type CoreModuleSource, type CoreWasmRuntime } from '../../wasm/runtime';
+import type { HitTestBackend } from '../../wasm/hit-backend';
+import type { AnimBackend } from '../../wasm/anim-backend';
+import type { ParticleBackend } from '../../wasm/particle-backend';
+/**
+ * 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.
+ *
+ * Declared here rather than in `Scene.ts` because this is the class that owns
+ * every field of this type. `Scene.ts` re-exports all three accelerator types,
+ * so `@vectojs/core`'s barrel keeps publishing them unchanged — `AcceleratorReason`
+ * in particular is consumed by `@vectojs/devtools`.
+ */
+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 declare class WasmBackendFacade {
+    /**
+     * The main tree's root.
+     *
+     * Held by value rather than as a `Scene` reference: it is assigned exactly
+     * once in `Scene`'s constructor and never reassigned, and taking it directly
+     * is what keeps this class from holding a back-edge to its facade. Only the
+     * main tree is ever composed through the store — overlays render on the JS
+     * path, so the overlay root is not needed here.
+     */
+    private readonly root;
+    constructor(root: Entity);
+    private _transform;
+    private _mode;
+    private _treeStore;
+    private _slotEntity;
+    private _inputs;
+    private _world;
+    private _structureVersion;
+    private _storeStructureVersion;
+    /**
+     * Consecutive `uploadRuns` rejections. Reset by any success and by
+     * {@link setTransform}; at {@link WASM_UPLOAD_REJECT_LIMIT} the backend mode
+     * flips to `'js'` permanently.
+     */
+    private _uploadRejections;
+    /** Latch for the permanent-fallback warning, which fires from a per-frame path. */
+    private hasWarnedUploadFallback;
+    /**
+     * 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.
+     */
+    private _aabbsFresh;
+    /** The installed transform backend, or `null` on the JS path. */
+    get transform(): WasmTransformBackend | null;
+    /** Which backend composes world matrices for the main render walk. */
+    get mode(): 'js' | 'wasm';
+    /**
+     * Whether the render walk should source world matrices from the store this
+     * frame: a backend is installed AND the mode has not fallen back to JS.
+     */
+    get transformActive(): boolean;
+    /** Store slot -> entity, for the render walk and the fused hit gather. */
+    get slotEntity(): Entity[];
+    /** Bumped by every topology change; the store layout's cache key. */
+    get structureVersion(): number;
+    /** Which structure version the resident store layout was built for. */
+    get storeStructureVersion(): number;
+    /** Consecutive `uploadRuns` rejections; see {@link WASM_UPLOAD_REJECT_LIMIT}. */
+    get uploadRejections(): number;
+    /** Invalidate the resident WASM store layout; the next wasm-mode frame
+     *  rebuilds it. Called by `Entity.add`/`remove` (topology changes only). */
+    markStructureChanged(): void;
+    /**
+     * Install (or clear) a WASM transform backend. Passing a backend switches the
+     * main render walk onto it; passing `null` reverts to the JS path.
+     */
+    setTransform(backend: WasmTransformBackend | null): void;
+    /**
+     * 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 _runtime;
+    /** The shared WASM runtime, if one has been loaded. */
+    get runtime(): CoreWasmRuntime | null;
+    /**
+     * 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
+     * keep working; only subsequent `enableWasm*` calls re-load).
+     */
+    setRuntime(runtime: CoreWasmRuntime | null): void;
+    /**
+     * 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.
+     */
+    ensureRuntime(source: CoreModuleSource): Promise<CoreWasmRuntime | null>;
+    private _hit;
+    private _anim;
+    private _particle;
+    /** The installed hit-test backend, or `null` for the JS depth-first walk. */
+    get hit(): HitTestBackend | null;
+    /** Install (or clear) a WASM hit-test backend. */
+    setHit(backend: HitTestBackend | null): void;
+    /** The installed batched-animation backend, or `null` for the JS tick. */
+    get anim(): AnimBackend | null;
+    /** Install (or clear) a WASM batched-animation backend. */
+    setAnim(backend: AnimBackend | null): void;
+    /** The installed particle backend, or `null` for the JS `updateCPU` path. */
+    get particle(): ParticleBackend | null;
+    /** Install (or clear) a WASM particle backend. */
+    setParticle(backend: ParticleBackend | null): void;
+    /**
+     * Why the transform accelerator did or did not run on the most recent frame.
+     * Written by the render walk and {@link syncStore}.
+     */
+    transformReason: AcceleratorReason;
+    /** Why the batched-driver accelerator did or did not run. */
+    animReason: AcceleratorReason;
+    /**
+     * 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; the grid build moves it to `'not-applicable'` once
+     * one is installed but nothing has queried yet.
+     */
+    hitReason: AcceleratorReason;
+    /** Why the particle accelerator did or did not run. */
+    particleReason: AcceleratorReason;
+    /** Which particle implementation actually simulated the most recent frame. */
+    particlePath: string;
+    /**
+     * 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.
+     */
+    hitFusedGather: boolean;
+    /** Whether the WASM batch path actually ran on the most recent frame. */
+    animBatchedLastFrame: boolean;
+    /** Frame the hit grid was last built for; `-1` forces a rebuild. */
+    hitGridFrame: number;
+    /** Whether that build succeeded (did not overflow its item budget). */
+    hitGridOk: boolean;
+    /**
+     * Per-frame status of every invisible accelerator: whether each is installed,
+     * whether it actually ran on the most recent frame, and why.
+     *
+     * `webgpuActive` is passed in because WebGPU device state belongs to
+     * `ContextAndResize`, not here — see the class comment.
+     */
+    report(webgpuActive: boolean): AcceleratorReport;
+    /**
+     * 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.
+     */
+    syncStore(): ReturnType<WasmTransformBackend['worldView']> | null;
+    /**
+     * 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.
+     */
+    ensureAabbs(): boolean;
+}

package/dist/tree/scene/a11y-dom.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Stateless helpers for the a11y projection's DOM mirrors.
+ *
+ * First module of the `Scene.ts` decomposition
+ * (`forge/decisions/file-decomposition-2026-08.md` §2, `TODO.md`'s P3 refactor
+ * entry). The decision record calls for extracting the stateless top-level
+ * functions before any stateful manager, and these are both: pure functions of
+ * their arguments, no `Scene` reference, no back-edge to `Scene.ts`. That keeps
+ * the import graph a one-way edge (`Scene.ts → scene/a11y-dom.ts`) and avoids
+ * the temporal-dead-zone hazard the Markdown split hit, where a module
+ * importing a class back from its facade to `extends` it threw during module
+ * initialization.
+ *
+ * Neither symbol is re-exported from `Scene.ts`. Both were module-private
+ * there, and `packages/core/src/index.ts` is `export * from './tree/Scene'`, so
+ * re-exporting would silently widen the public API — the opposite of this
+ * refactor's byte-identical-surface requirement.
+ *
+ * When `A11yProjectionManager` (extraction 2) lands, it is the natural owner of
+ * both. Until then `Scene` imports them directly.
+ */
+import type { AffineTransform } from '../Entity';
+/**
+ * Whether the element takes focus without an explicit `tabindex`.
+ *
+ * The projection adds `tabindex="0"` only to mirrors that need it: a mirror
+ * carrying an interactive ARIA role but rendered as a non-focusable tag is
+ * unreachable by keyboard, while adding `tabindex` to an element that is
+ * already focusable is redundant and reorders nothing.
+ */
+export declare function isNativelyFocusable(element: HTMLElement): boolean;
+/**
+ * A nested mirror's box, expressed relative to its projected parent.
+ *
+ * Reused across calls rather than returned fresh: the geometry write runs for
+ * every projected node on every synced frame, and a virtualized table can
+ * nest several hundred cells, so a per-node literal here would allocate in the
+ * frame loop. The single caller consumes the fields immediately.
+ */
+export interface RebasedBox {
+    left: number;
+    top: number;
+    matrix: string;
+}
+/**
+ * Re-express a child's **world** transform as a box positioned inside its
+ * projected parent's box.
+ *
+ * Mirrors are `position: absolute`, so their `left`/`top` resolve against the
+ * nearest positioned ancestor. While the projection is flat that ancestor is
+ * always `a11yRoot` and world coordinates are correct as-written. The moment a
+ * mirror is nested inside another mirror, its containing block becomes the
+ * parent — writing world coordinates then *double-offsets* every descendant,
+ * and the parent's `matrix()` compounds on top. Measured in real Chrome and
+ * Firefox: a row at world (110, 80) under a grid at (100, 50) landed at
+ * (210, 130), and a cell at (120, 90) landed at (330, 220).
+ *
+ * The correction is not a plain subtraction. `left`/`top` are applied *before*
+ * the ancestor's `transform`, so the offset has to be expressed in the parent's
+ * pre-transform space: divide the world delta by the parent's linear part
+ * rather than subtracting its translation. The linear part is likewise relative
+ * — `inv(P) · C`, which collapses to the identity when the child adds no
+ * rotation or scale of its own.
+ *
+ * Both engines reproduce the flat layout exactly under this transform,
+ * including a parent rotated 30° and scaled 1.5×. That agreement depends on
+ * `transformOrigin: '0 0'` (set on every mirror at creation); with the default
+ * `50% 50%` each nested box rotates about its own centre and the results
+ * diverge by tens of pixels.
+ *
+ * A singular parent matrix (zero width or height, or a collapsed scale) has no
+ * inverse. Rather than emit `NaN` — which reads as `left: 0` and silently
+ * relocates the element to the parent's origin, where the reading-order sort
+ * would then treat it as the top-left-most element on screen — the child is
+ * pinned to the parent's origin with an identity matrix. A zero-area parent is
+ * already invisible, and `projectionBoxVisible` hides it on the same frame.
+ */
+export declare function rebaseChildBox(parent: AffineTransform, parentOriginX: number, parentOriginY: number, child: AffineTransform, childOriginX: number, childOriginY: number): RebasedBox;