@vectojs/core 1.32.7 → 1.34.0

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

@@ -0,0 +1,147 @@
+/**
+ * The a11y projection's DOM **ordering** engine: what order the projected
+ * mirrors sit in, and what that reordering must not break.
+ *
+ * Extraction 2 of the `Scene.ts` decomposition
+ * (`forge/decisions/file-decomposition-2026-08.md` §2), reduced in scope by
+ * carryctx `DEC-0020`. `Scene` keeps `enforceA11yDomOrder` and
+ * `a11yNeedsReorder` under their original names; the ordering half of the former
+ * and the whole of the latter live here.
+ *
+ * ## What this owns
+ *
+ * The per-pass scratch collections (all reused rather than reallocated, which is
+ * why they are fields and not locals), the reorder flag, the visual reading-order
+ * sort, and the cursor-based `insertBefore` pass with its focus and `Selection`
+ * preservation.
+ *
+ * ## What it deliberately does not own
+ *
+ * `Scene.enforceA11yDomOrder` still runs the collect-and-prune walk. Collecting
+ * needs `shouldProjectA11y` — which reaches the pointer position (extraction 5)
+ * and the content-projection tier (extraction 3) — and pruning needs
+ * `focusedA11yElement`, `caretBlinkTimer` and `preserveFocusOnRemoval`. So
+ * `Scene` walks and prunes, feeding each element in through {@link collect}, and
+ * this class orders what it was given.
+ *
+ * Three members the original extraction plan assigned here stayed on `Scene`,
+ * measured rather than assumed (`DEC-0020`):
+ *
+ * - `syncA11y` is not an a11y method. It is the shared depth-first walk driver
+ *   for a11y **and** content projection: it calls `syncContentProjection` at its
+ *   own recursion point and initialises four per-sync fields whose readers live
+ *   in three other domains. It moves once extraction 3 has taken its co-driver
+ *   out, not before — taking it now would need a back-edge into `Scene`, which
+ *   `DEC-0019` rule 1 forbids.
+ * - `removeA11yRecursively` deletes content projections and releases DOM portals,
+ *   which are extraction 3 and the ninth portal domain respectively.
+ * - `syncOverlayGeometry` is overlay-**layer** geometry: every dependency except
+ *   `a11yRoot` (`canvas`, `glCanvas`, `gpuCanvas`, `width`, `height`) belongs to
+ *   extraction 5. It sits under an a11y banner, which is a fourth instance of
+ *   `DEC-0016`'s finding that the banners expose wrong cuts.
+ *
+ * ## Reading direction is passed in
+ *
+ * The inline sort is direction-sensitive and `_readingDirection` belongs to the
+ * text/layout side of `Scene`, so {@link reorder} takes it as an argument rather
+ * than reaching for it — `DEC-0019` rule 5, the same shape as
+ * `WasmBackendFacade.report(webgpuActive)`.
+ */
+import type { Entity } from '../Entity';
+export declare class A11yProjectionManager {
+    /**
+     * Set by anything that changes which elements exist or how they nest, and
+     * cleared by the reorder pass. Public so `Scene` can expose it under its
+     * original name: `Entity` assigns to `scene.a11yNeedsReorder` as a public
+     * cross-class contract, so the flag needs a setter and not only
+     * {@link markNeedsReorder}.
+     */
+    needsReorder: boolean;
+    /** Overlay mirrors, kept in insertion order — they cover everything, so the
+     *  author's declared order is the right one. */
+    private readonly fullViewportElements;
+    /** Everything else, sorted into visual reading order by {@link reorder}. */
+    private readonly normalElements;
+    /** Ids collected this pass, read by `Scene`'s prune pass through
+     *  {@link isActive}. */
+    private readonly activeIdSet;
+    /** Per-parent insertion cursor, reused by {@link reorder}. */
+    private readonly orderCursors;
+    /** Membership set for the elements being ordered, reused per reorder pass. */
+    private readonly orderMembers;
+    /**
+     * Elements that are an *ancestor* of another ordered element, reused per pass.
+     *
+     * 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}.
+     */
+    private readonly orderContainers;
+    /**
+     * Nearest region-establishing ancestor per ordered element — its *region*.
+     * Written by `Scene.enforceA11yDomOrder`'s collect walk through
+     * {@link collect}, which already has the entity in hand, so a region costs one
+     * comparison per node rather than an ancestor walk per element.
+     *
+     * An ancestor establishes a region by setting `a11yRegion` (grouping declared
+     * directly) or `clipChildren` (a clipper is usually the column boundary you
+     * want anyway). Absent means the element sits under neither and belongs to the
+     * implicit root region. See {@link sortNormalElementsVisually}.
+     */
+    private readonly orderRegions;
+    /** Mark the projected DOM as needing a reorder on the next pass. */
+    markNeedsReorder(): void;
+    /** Reset the per-pass collections. Zero-GC: length/clear, never reallocate. */
+    beginCollect(): void;
+    /**
+     * Add one projected element to this pass.
+     *
+     * `region` is the nearest ancestor that sets `a11yRegion` or `clipChildren`,
+     * or `null` for the implicit root region.
+     */
+    collect(el: HTMLElement, fullViewport: boolean, region: Entity | null): void;
+    /** Record that `id` still has a live a11y mirror this pass. */
+    markActive(id: string): void;
+    /** Whether `id` was collected this pass. Drives `Scene`'s prune pass. */
+    isActive(id: string): boolean;
+    /**
+     * Put the collected elements into visual reading order in the DOM.
+     *
+     * No-op unless {@link needsReorder} is set; clears it on the way out.
+     */
+    reorder(rtl: boolean): void;
+    /**
+     * 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 reorder} 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 ancestor setting `a11yRegion` or
+     * `clipChildren`, recorded by `Scene.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 establishing ancestor is first reached by the
+     * depth-first walk, so a screen reader still meets them in the author's
+     * declared order.
+     */
+    private sortNormalElementsVisually;
+}

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

@@ -0,0 +1,117 @@
+/**
+ * Canvas box geometry: the CSS↔logical mapping, the overlay layer alignment, and
+ * the device-pixel-ratio math.
+ *
+ * Extraction 5 of the `Scene.ts` decomposition
+ * (`forge/decisions/file-decomposition-2026-08.md` §2), shipped at **reduced
+ * scope** for the same measured reason extractions 2 and 3 were reduced
+ * (`DEC-0020`, `DEC-0022`): the decided `ContextAndResize` scope named nine
+ * members, and six of them cannot move without a `Scene` back-edge. See the
+ * decision record for the per-member measurement.
+ *
+ * ## What this owns
+ *
+ * Everything that is a pure function of the canvas's CSS box and the scene's
+ * logical size:
+ *
+ * - {@link clientToScene} — browser viewport coordinates to logical ones.
+ * - {@link syncOverlay} — keeps the a11y, portal, WebGL and WebGPU layers
+ *   aligned with the canvas box, including the `position` that layers share with
+ *   the canvas so a scroll needs no JS compensation, and the memo that makes an
+ *   unchanged frame write nothing.
+ * - {@link effectiveDPR} and {@link sizeGpuCanvas} — the DPR clamp and the
+ *   backing-store sizing that follows from it.
+ *
+ * ## What is held, and what is passed in
+ *
+ * `canvas`, `a11yRoot` and `portalRoot` are held: `Scene` assigns all three
+ * exactly once in its constructor and never reassigns them (`canvas` at
+ * `Scene.ts:2423`, `a11yRoot` at `:2526`/`:2683`, `portalRoot` at
+ * `:2670`/`:2684`).
+ *
+ * Everything else is a per-call argument (`DEC-0019` rule 5), because it is
+ * genuinely mutable and holding it would go stale silently:
+ *
+ * - `width`/`height` are **public** fields that `resize` mutates and that code
+ *   outside this package assigns directly (9 sites across the test suite,
+ *   benchmarks and comparisons write `scene.width = …`). They cannot become this
+ *   collaborator's state without changing the public API.
+ * - `maxDPR` is public and externally assignable (`Scene.test.ts:1013`).
+ * - `glCanvas` and `gpuCanvas` are created lazily — `gpuCanvas` only when the
+ *   WebGPU particle path first runs (`Scene.ts:6468`) — so the overlay sync is
+ *   told which layers exist at the moment it runs.
+ *
+ * ## What deliberately did not move
+ *
+ * `resize` stays on `Scene` and keeps its whole body. It mutates `width`,
+ * `height`, `contentFontEpoch` and `contentViewportEpoch`, drives `renderer` and
+ * `pointRenderer`, and calls `markDirty` — four domains, none of them this one.
+ * It calls in here for the GPU canvas sizing and that is the honest extent of it
+ * (`DEC-0019` rule 2 applied without inventing a back-edge).
+ *
+ * `setupEvents` and `watchDevicePixelRatio` both call `this.resize(…)`, so moving
+ * either needs a `Scene` reference; a bound `resize` injected at construction is
+ * still that reference captured in a closure, which `DEC-0020` refused for
+ * `syncA11y` and `DEC-0021` refused for `_recordPhase`.
+ *
+ * `watchCanvasVisibility` reads `isRunning`, writes `lastTime`, calls
+ * `scheduleFrame`, and owns `_canvasOnScreen`, whose readers are `loop` and
+ * `stop`. That is render-scheduler state, so it belongs to extraction 6.
+ *
+ * `initWebGPUContext` is one member of a device-lifecycle cluster (`device`,
+ * `deviceLost`, `manager`, `recoveryTimerId`, `gpuContext`,
+ * `setupDeviceLostHandler`, `recreateWebGPUDeviceWithRetry`,
+ * `clearGPUCanvasIfStale`) that `render` and `destroy` also drive.
+ *
+ * `getContentMetricScaleX` caches into `contentMetricScaleX` keyed by
+ * `contentFontEpoch` and is called only by `syncContentGridProjection`, so it is
+ * content-projection state and moves with the deferred projection walk.
+ */
+/** The overlay box last written by {@link CanvasGeometry.syncOverlay}. */
+export interface OverlayGeometry {
+    left: number;
+    top: number;
+    cssWidth: number;
+    cssHeight: number;
+    width: number;
+    height: number;
+    /**
+     * `position` written to the overlay layers, mirroring the canvas's own.
+     *
+     * Part of the memo because it is part of the written state: a canvas that
+     * becomes `fixed` after the first sync (a scroll-driven CSS class, a
+     * full-screen toggle) changes nothing else in here — same box, same logical
+     * size — so without this the memo would short-circuit and leave the overlay
+     * positioned the old way.
+     */
+    position: 'absolute' | 'fixed';
+}
+export declare class CanvasGeometry {
+    private readonly canvas;
+    private readonly a11yRoot;
+    private readonly portalRoot;
+    /** Last geometry {@link syncOverlay} wrote, so an unchanged frame can skip the
+     *  style writes entirely. Cleared by {@link invalidateOverlay} to force the next
+     *  sync (a new overlay layer was created and has never been positioned). */
+    private overlayGeometry;
+    constructor(canvas: HTMLCanvasElement, a11yRoot: HTMLDivElement | null, portalRoot: HTMLDivElement | null);
+    /** Convert browser viewport coordinates into the scene's logical coordinates. */
+    clientToScene(clientX: number, clientY: number, width: number, height: number): {
+        x: number;
+        y: number;
+    };
+    /** Effective device pixel ratio, matching CanvasRenderer: real DPR clamped to
+     *  `maxDPR` when set. */
+    effectiveDPR(maxDPR: number | undefined): number;
+    /** 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. */
+    sizeGpuCanvas(gpuCanvas: HTMLCanvasElement, width: number, height: number, maxDPR: number | undefined): void;
+    /** The memo, for the delegating accessor `Scene` keeps for its test readers. */
+    get overlay(): OverlayGeometry | null;
+    /** Force the next {@link syncOverlay} to write: a new overlay layer exists and
+     *  has never been positioned. */
+    invalidateOverlay(): void;
+    /** Keep DOM/WebGL overlay layers aligned with the canvas's CSS box. */
+    syncOverlay(width: number, height: number, glCanvas: HTMLCanvasElement | null, gpuCanvas: HTMLCanvasElement | null): void;
+}

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

@@ -0,0 +1,63 @@
+/**
+ * Grid carrier materialization: turning a prepared content grid into positioned
+ * DOM carriers, with per-line reuse so streaming stays affordable.
+ *
+ * The deferred **projection walk** extraction (`DEC-0028` measurement,
+ * `DEC-0019` pattern). The walk was deferred by `DEC-0020` and `DEC-0022` on the
+ * grounds that `syncA11y` and `syncContentProjection` are one shared depth-first
+ * walk and would have to move as a pair. Re-measured on `58c77ac` that premise
+ * held for the two walk drivers and **not** for this member: the grid path is a
+ * leaf of the walk, not part of it.
+ *
+ * ## Why this is separable when its callers are not
+ *
+ * `syncContentGridProjection` has exactly one call site, takes everything it
+ * needs as parameters already, and calls nothing else on `Scene` except the
+ * content-projection manager and the phase timer. Its own state is two memo
+ * fields nobody outside it reads. It writes no state any other domain reads, so
+ * there is no back-edge to invent and `DEC-0019` rule 1 is satisfied outright.
+ *
+ * ## What is held, and what is passed in
+ *
+ * Held: the {@link ContentProjectionManager} and the {@link PhaseTimer}. Both are
+ * `readonly` on `Scene`, constructed once, and already shared collaborators — the
+ * timer is the shared leaf `DEC-0021` extracted for exactly this reason.
+ *
+ * Per-call (`DEC-0019` rule 5): `pageScaleX` and `fontEpoch`. `Scene` keeps
+ * `getContentMetricScaleX`, which reads `canvas` and the **public mutable**
+ * `width`, and whose memo is keyed on `contentFontEpoch` that `resize` and a font
+ * load both bump. Holding either here would go stale silently. `entityId` is
+ * passed rather than the `Entity`, because the id is all this needs.
+ *
+ * ## What deliberately did not move
+ *
+ * `syncContentProjection` (the walk's content driver) and `syncA11y` (its a11y
+ * driver) stay together on the facade, still blocked on each other exactly as
+ * `DEC-0020` measured.
+ *
+ * `projectionBoxVisible` also stays, for a reason measurement found rather than
+ * predicted: `test/ContentProjectionSettledWalk.test.ts` replaces it on the
+ * `Scene` instance and asserts call counts (the settled-walk fast path is
+ * verified by counting box tests, 2 when settled against 802 unpruned). Moving
+ * it onto a collaborator would make those calls invisible to the patch and turn
+ * a behavioural regression test into one that cannot fail. The suite is unedited
+ * by contract, so the member stays where the test can see it.
+ */
+import type { ContentProjection } from '../Entity';
+import type { PreparedContentGrid } from '@vectojs/text';
+import type { ContentProjectionManager } from './ContentProjectionManager';
+import type { PhaseTimer } from './PhaseTimer';
+export declare class ContentGridProjector {
+    private readonly contentProjection;
+    private readonly phases;
+    constructor(contentProjection: ContentProjectionManager, phases: PhaseTimer);
+    /**
+     * 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.
+     */
+    syncGrid(entityId: string, el: HTMLElement, projection: ContentProjection, grid: PreparedContentGrid, lineBand: {
+        minY: number;
+        maxY: number;
+    } | null, pageScaleX: number, fontEpoch: number): void;
+}

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

@@ -0,0 +1,217 @@
+/**
+ * The content projection's **selection preservation** and **grid calibration** —
+ * the two halves of extraction 3 that are separable today.
+ *
+ * Extraction 3 of the `Scene.ts` decomposition
+ * (`forge/decisions/file-decomposition-2026-08.md` §2), reduced in scope by
+ * carryctx `DEC-0022` for the same measured reason `DEC-0020` reduced extraction
+ * 2: the projection *walk* is not separable yet.
+ *
+ * ## What this owns
+ *
+ * **Selection across rebuilds.** A streaming message replaces its projection
+ * children on every appended chunk, and a naive rebuild wipes a selection the
+ * user made in the unchanged prefix. This owns the tracked drag anchor, the
+ * blank-region drag flag, the per-walk "is anything selected at all" memo, and
+ * the snapshot/restore of selection endpoints as linear character offsets.
+ *
+ * **Grid calibration.** The cold read/write batch that measures a projected
+ * grid's real laid-out text and writes a per-cell `scaleX`, its generation
+ * stamping, its probe DOM, and the pending-frame/probe bookkeeping that lets a
+ * teardown cancel work in flight.
+ *
+ * ## What it deliberately does not own
+ *
+ * `syncContentProjection` (624 lines) and its helpers stay on `Scene`. It is the
+ * far side of the shared walk `DEC-0020` measured: `syncA11y` calls it at its own
+ * recursion point, and it reads the four per-sync fields `syncA11y` initialises
+ * (`_syncSerial`, `contentSemanticBudgetLeft`, `contentSemanticDeferred`,
+ * `contentSelectionPresentThisSync`). The two walk drivers move together, once
+ * they can be cut as a pair rather than threaded through each other — taking
+ * either alone needs a back-edge, which `DEC-0019` rule 1 forbids.
+ *
+ * `getContentMetricScaleX` also stays: it reads `canvas` and `width`, which
+ * `resize` mutates, so it is extraction 5's state. Its result is already a
+ * parameter of {@link scheduleGridCalibration}, so nothing here reaches for it.
+ *
+ * ## What is passed in, and why
+ *
+ * `a11yRoot` is injected because it is assigned once in `Scene`'s constructor and
+ * never reassigned, so it is safe to hold. {@link PhaseTimer} is injected because
+ * it is the shared leaf `DEC-0021` extracted for exactly this: the calibration
+ * pass records `calibScan` and `calibProbeBuild`, and reaching a `Scene` private
+ * to do it — or holding a bound `Scene` method — is the rule 1 violation this
+ * whole sequence is avoiding.
+ *
+ * The font epoch is a per-call argument rather than held state (`DEC-0019` rule
+ * 5): a font load and a resize both bump it, and both belong to other domains.
+ */
+import { PhaseTimer } from './PhaseTimer';
+import { type TextCaretPosition } from './content-caret';
+export declare class ContentProjectionManager {
+    /**
+     * `a11yRoot` doubles as the projection root: carriers are appended to it, and
+     * the calibration probe is parented under it so CSS zoom and font substitution
+     * match the live carriers. `null` in non-DOM (SSR/Node) environments.
+     */
+    private readonly a11yRoot;
+    private readonly phases;
+    /**
+     * True while a drag that started in a blank region of the projection is live.
+     * Mid-drag the browser is authoritative, so a rebuild must not try to preserve
+     * anything.
+     */
+    private blankRegionDrag;
+    /** Tracked drag anchor. Survives a drag, unlike the live DOM selection. */
+    private anchor;
+    /**
+     * Memo for {@link selectionPresent}, valid for one sync walk.
+     *
+     * Reading any `Selection` property forces a synchronous layout, so the answer
+     * is resolved once per walk rather than once per rebuilt element. `null` means
+     * "not yet asked this walk".
+     */
+    private presentThisSync;
+    /** Pending calibration rAF handle per projected grid entity. */
+    private readonly calibrationFrameHandles;
+    /** Detached, untransformed font probes used by the cold calibration pass. */
+    private readonly calibrationProbes;
+    /**
+     * Bumped when the conditions a measurement depends on change, which
+     * invalidates every existing per-cell `scaleX` at once without touching them.
+     */
+    private calibrationGeneration;
+    /** The conditions the current generation was measured under. */
+    private calibrationStamp;
+    constructor(a11yRoot: HTMLDivElement | null, phases: PhaseTimer);
+    /** Pending calibration frames, keyed by entity id. Read by the e2e lifecycle probe. */
+    get calibrationFrames(): ReadonlyMap<string, number>;
+    /**
+     * Start tracking a drag that began in a blank region of the projection.
+     *
+     * Called from the projection root's `mousedown` handler, which has already
+     * resolved the caret and collapsed or extended the live selection.
+     */
+    beginBlankRegionDrag(anchor: TextCaretPosition): void;
+    /** The tracked drag anchor, for extending a selection as the pointer moves. */
+    get selectionAnchor(): TextCaretPosition | null;
+    /**
+     * Whether a manually-driven blank-region drag is live.
+     *
+     * The projection root's `mousemove` handler gates on this: with no native
+     * anchor, the browser will not extend the selection itself.
+     */
+    get blankRegionDragActive(): boolean;
+    /**
+     * Drop the memo describing whether the document holds a selection.
+     *
+     * Called at the top of each a11y sync walk: the memo answers a question about
+     * the live document, and a value from an earlier frame would be wrong.
+     */
+    invalidateSelectionMemo(): void;
+    endDrag(): void;
+    /**
+     * 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.
+     */
+    gridSelectionLine(el: HTMLElement): number | null;
+    /**
+     * 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 presentThisSync} 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.
+     */
+    selectionPresent(): boolean;
+    releaseSelectionForRebuild(el: HTMLElement): void;
+    /**
+     * 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).
+     */
+    preserveSelectionAcrossRebuild(el: HTMLElement, rebuild: () => void): void;
+    /**
+     * A selection inside a projected grid, expressed as offsets into `grid.source`.
+     *
+     * Source offsets rather than the linear DOM offsets
+     * {@link preserveSelectionAcrossRebuild} uses, because the grid path windows its
+     * carriers: the DOM holds only the lines near the viewport, so linear offset 0
+     * means "the first line that happens to be materialized" and moves whenever the
+     * window does. A reflow changes both the line breaks and the window, so a linear
+     * offset would restore the selection onto different characters. Every carrier
+     * cell already records its own `sourceStart`/`sourceEnd`, which are stable
+     * against line breaking, windowing, and per-cell calibration.
+     */
+    private gridSelectionEndpointOffset;
+    /**
+     * Where in `grid.source` the live selection sits, or `null` when this element
+     * does not own one that can be expressed that way.
+     *
+     * Cheap-rejects exactly as {@link releaseSelectionForRebuild} does: the tracked
+     * anchor is a local field, and the memo costs one forced layout per sync walk
+     * rather than one per element.
+     */
+    snapshotGridSelection(el: HTMLElement): {
+        anchor: number;
+        focus: number;
+    } | null;
+    /** The carrier caret for a source offset, or `null` when it is not projected. */
+    private gridCaretAtSourceOffset;
+    /**
+     * Put a {@link snapshotGridSelection} result back after a re-materialization,
+     * releasing instead whenever the selected text is no longer projected.
+     *
+     * Restoring is what keeps a selection alive across a reflow or a browser zoom,
+     * where every carrier line is rebuilt (the line breaks moved) but the selected
+     * characters are still on screen. When the window scrolled past them instead,
+     * the offsets resolve to nothing and the selection is dropped — a `Range` left
+     * pointing into detached carriers reports stale geometry and copies the wrong
+     * text.
+     */
+    restoreGridSelection(el: HTMLElement, snapshot: {
+        anchor: number;
+        focus: number;
+    } | null): void;
+    /**
+     * 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 {@link preserveSelectionAcrossRebuild}
+     *   exists to prevent on the non-grid path.
+     */
+    clearGridState(entityId: string, el: HTMLElement, releaseSelection?: boolean): void;
+    /**
+     * Cancel every calibration in flight and drop every probe.
+     *
+     * For `Scene.destroy()`: an outstanding rAF would otherwise run against a
+     * destroyed scene, and a probe left in the document keeps a detached subtree
+     * alive.
+     */
+    dispose(): void;
+    /**
+     * Measure a projected grid's real laid-out text and write a per-cell `scaleX`.
+     *
+     * @param fontEpoch - `Scene`'s font epoch. Passed in rather than held: a font
+     *   load and a resize both bump it, and both belong to other domains.
+     */
+    scheduleGridCalibration(entityId: string, el: HTMLElement, calibrationKey: string, pageScaleX: number, fontEpoch: number): void;
+}

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

@@ -0,0 +1,107 @@
+/**
+ * The dirty flag and its attribution: whether the next frame must redraw, and
+ * who asked for it.
+ *
+ * Extraction 6 of the `Scene.ts` decomposition
+ * (`forge/decisions/file-decomposition-2026-08.md` §2), shipped at **heavily
+ * reduced scope** — see `DEC-0025`. The decided `RenderScheduler` scope named
+ * `loop` and `render` as its centre; neither is movable, so what ships is this
+ * cluster and {@link DriverTicker}.
+ *
+ * ## What this owns
+ *
+ * The flag itself, the opt-in attribution map, and its FIFO bound. The two are
+ * one domain rather than two: `markDirty` is the only writer of the flag and the
+ * only trigger of an attribution, so splitting them would put a branch on the hot
+ * path in one class and its data in another.
+ *
+ * ## The hot path
+ *
+ * {@link mark} is called from dozens of sites, several per frame. It stays a
+ * single field write plus one already-false branch when tracking is off, which is
+ * why {@link record} is a separate method: V8 inlines the one-field version
+ * reliably, and that split was deliberate before this extraction.
+ *
+ * ## What is passed in
+ *
+ * `currentFrame` is a per-call argument (`DEC-0019` rule 5). It is written by
+ * `Scene.render`, which did not move, so capturing it would go stale every frame.
+ *
+ * ## What deliberately did not move
+ *
+ * `Scene.markDirty` keeps its exact name and signature and delegates here. It is
+ * a cross-class contract — `Entity.ts` calls `scene.markDirty()`, and there are
+ * 129 call sites across the workspace packages — so it stays reachable on `Scene`
+ * (`DEC-0019` rule 2).
+ *
+ * `renderMode`, `maxFPS` and `autoThrottle` stay on `Scene` as public fields:
+ * they are consumed by `loop`, which did not move, and `renderMode` has three
+ * external readers in `@vectojs/devtools`. The frame telemetry counters stay with
+ * `loop` for the same reason — it is their only writer.
+ */
+/**
+ * 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;
+}
+export declare class DirtyTracker {
+    /** Cap on distinct recorded dirty reasons (see {@link record}). */
+    private static readonly MAX_DIRTY_REASONS;
+    private tracking;
+    private readonly reasons;
+    private isDirty;
+    /** Whether the next frame must redraw. */
+    get dirty(): boolean;
+    /**
+     * Mark the scene as needing a redraw on the next frame.
+     *
+     * Attribution is opt-in and costs nothing when off: this is called from dozens
+     * of sites, several of them per-frame, so the common path must stay a single
+     * field write.
+     */
+    mark(source: DirtySource | undefined, currentFrame: number): void;
+    /**
+     * Consume the flag.
+     *
+     * `Scene.loop` clears it BEFORE the update/render pass: any `markDirty()` call
+     * made inside an entity's `update()` must survive into the next frame
+     * (self-animating entities re-arm themselves this way). Clearing after render
+     * would silently wipe those marks and freeze the entity.
+     */
+    clear(): void;
+    /**
+     * Record who marked the scene dirty and why.
+     *
+     * Kept separate from {@link mark} so the hot path is not a function call with a
+     * branch — V8 inlines the one-field version reliably.
+     */
+    private record;
+    /** Start or stop recording dirty attributions. */
+    setTracking(enabled: boolean): void;
+    /** Whether dirty attribution is currently being recorded. */
+    get trackingEnabled(): boolean;
+    /** Recorded dirty attributions, most frequent first. */
+    get sortedReasons(): DirtyReasonEntry[];
+    /** Drop recorded attributions, keeping tracking enabled. */
+    clearReasons(): void;
+}