@vectojs/core 1.39.1 → 1.40.0

package/dist/text.js

@@ -2,11 +2,11 @@
 
 
 
-var _chunkPOPXUPKRjs = require('./chunk-POPXUPKR.js');
+var _chunkHC5EZOZJjs = require('./chunk-HC5EZOZJ.js');
 
 // src/text/index.ts
 var _text = require('@vectojs/text'); _createStarExport(_text);
 
 
 
-exports.MSDFTextEntity = _chunkPOPXUPKRjs.MSDFTextEntity; exports.SVGEntity = _chunkPOPXUPKRjs.SVGEntity;
+exports.MSDFTextEntity = _chunkHC5EZOZJjs.MSDFTextEntity; exports.SVGEntity = _chunkHC5EZOZJjs.SVGEntity;

package/dist/text.mjs

@@ -1,7 +1,7 @@
 import {
   MSDFTextEntity,
   SVGEntity
-} from "./chunk-7PYD5UDX.mjs";
+} from "./chunk-CIRZ3S2Z.mjs";
 
 // src/text/index.ts
 export * from "@vectojs/text";

package/dist/tree/Entity.d.ts

@@ -502,6 +502,20 @@ export interface ListenerOptions {
     /** Register the listener for the capture phase (root→target) instead of bubble. */
     capture?: boolean;
 }
+/**
+ * Origin transport of a dispatched {@link VectoJSEvent} (input-dispatch-contract
+ * v2 §4 rule 1: source attribution; gesture stickiness and single delivery are
+ * judged against this field).
+ *
+ * `'mirror'` is the a11y-shadow transport that ships today; `'canvas'` and
+ * `'at'` are reserved for the canvas-first dispatcher and AT-synthesized
+ * reflection. `'dom'` is owned by `@vectojs/dom` (RFC2): the live projected
+ * element counts as a materialized target at its point, so its bridge tags
+ * every event it forwards. The open tail leaves room for future backends
+ * without touching this type. `undefined` means "unattributed" (legacy call
+ * sites and synthetic dispatches predate the contract).
+ */
+export type VectoEventSource = 'mirror' | 'canvas' | 'at' | (string & {});
 /**
  * A propagating event dispatched through the entity tree by
  * {@link Entity.dispatchEvent} (DOM-like capture + bubble).
@@ -523,10 +537,15 @@ export declare class VectoJSEvent<N = unknown> {
     readonly nativeEvent: N | undefined;
     /** Whether the event bubbles past its target (capture always runs). */
     readonly bubbles: boolean;
+    /**
+     * Which transport delivered this event ({@link VectoEventSource}).
+     * `undefined` for unattributed legacy/synthetic dispatches.
+     */
+    readonly source: VectoEventSource | undefined;
     private readonly explicitScenePoint;
     private stopped;
     private stoppedImmediate;
-    constructor(type: VectoEvent, target: Entity, nativeEvent?: N, bubbles?: boolean, scenePoint?: Point);
+    constructor(type: VectoEvent, target: Entity, nativeEvent?: N, bubbles?: boolean, scenePoint?: Point, source?: VectoEventSource);
     /** Stop the event from reaching the next node in the propagation path. */
     stopPropagation(): void;
     /** Stop propagation AND skip any remaining listeners on the current node. */
@@ -712,6 +731,41 @@ export declare abstract class Entity {
      * faint-but-live control.
      */
     a11yHidden: boolean;
+    /**
+     * Opt-in to the DOM visual projection (RFC2, implemented by `@vectojs/dom`).
+     * Plain data only — core never materializes an element from this; a
+     * registered `ProjectionBackend` does.
+     *
+     * Name mapping: this field IS the RFC4 §2 `projection` policy
+     * (`ProjectionPolicy`: `'canvas' | 'dom' | 'auto'` in
+     * `tree/scene/ProjectionPolicy.ts`) — predates the RFC, so the field keeps
+     * its name and the RFC spelling lives on the value type.
+     *
+     * - `'canvas'` (default): today's rendering. Zero behavior change.
+     * - `'dom'`: the node materializes as a live `HTMLElement` positioned by its
+     *   world matrix. The live element replaces the transparent a11y mirror
+     *   (same single-delivery reasoning as `DOMPortalEntity`), so opting in
+     *   requires a DOM backend and a DOM environment for the AT representation.
+     * - `'auto'`: negotiated per node per frame by `Scene.resolveProjectionFor`
+     *   (RFC4 §3: explicit beats automatic, fallbacks reported with reasons,
+     *   hysteresis against flip-flop, no-DOM short-circuits to canvas).
+     */
+    domPolicy: 'canvas' | 'dom' | 'auto';
+    /**
+     * Backend-side creation hint for a `'dom'`-policy node (tag/content mapping
+     * key, e.g. `'text' | 'button' | 'input' | 'container' | 'transform'`). Plain
+     * string so custom nodes need no DOM types in core; `@vectojs/dom` owns the
+     * registry. `''` means a plain positioned `div` with no content sync.
+     */
+    domKind: string;
+    /**
+     * Internal cache owned by the DOM backend: true while the node has a live
+     * projected element. The render walk reads it to skip canvas paint for
+     * DOM-resident nodes (so a mounted node is never double-drawn) and falls
+     * through to canvas while false (SSR / no backend registered). Do not set
+     * by hand — the backend sets it on mount and clears it on unmount.
+     */
+    domResident: boolean;
     /**
      * Clip this node's children to its local box (`[0,0]–[width,height]`) while
      * rendering. Combined with translating a content child, this is how
@@ -1123,6 +1177,10 @@ export declare abstract class Entity {
      * `selectable` is set — natively selectable. Returns `null` by default.
      * Read on the a11y sync cadence, so text changes propagate automatically.
      *
+     * This is the descriptor half of the `ContentProjection` row of
+     * `ProjectionBackend` (`tree/scene/ProjectionBackend.ts`): the entity
+     * describes *what* to project, the scene owns *how* it is materialized.
+     *
      * @param hint - Optional advice about which part of the entity is worth
      *   describing. Purely an optimization: ignoring it is always correct, which
      *   is why it is a parameter rather than a required contract change. See

package/dist/tree/Scene.d.ts

@@ -13,6 +13,7 @@ export interface IWebGPUParticleSystemManager {
 import { Entity } from './Entity';
 import { IRenderer } from '../renderer/IRenderer';
 import type { WebGLDrawStats } from '../renderer/WebGLPointRenderer';
+import type { ProjectionBackend, ProjectionBackendKind } from './scene/ProjectionBackend';
 import { type WasmModuleSource, type WasmTransformBackend } from '../wasm/backend';
 import type { CoreWasmRuntime } from '../wasm/runtime';
 import { type HitModuleSource, type HitTestBackend } from '../wasm/hit-backend';
@@ -20,9 +21,12 @@ import { type AnimModuleSource, type AnimBackend } from '../wasm/anim-backend';
 import { type ParticleModuleSource, type ParticleBackend } from '../wasm/particle-backend';
 import { type OverlayGeometry } from './scene/CanvasGeometry';
 import { type DirtyReasonEntry, type DirtySource } from './scene/DirtyTracker';
+import type { DomHitCandidate, HitResult } from './scene/HitResult';
 import { type RenderPhase, type RenderPhaseEntry } from './scene/PhaseTimer';
 import { type AcceleratorReason, type AcceleratorReport, type AcceleratorStatus } from './scene/WasmBackendFacade';
 import { type SceneKeyEvent, type SceneShortcutSpec } from './scene/keyboard';
+import { type SemanticProjectionPolicy } from './scene/SemanticProjectionPolicy';
+import { type ProjectionCapabilityRow, type ProjectionResolution, type SceneProjectionCapabilities } from './scene/ProjectionPolicy';
 export type { RenderPhase, RenderPhaseEntry };
 export { normalizeChord } from './scene/keyboard';
 export type { SceneKeyEvent, SceneShortcutSpec } from './scene/keyboard';
@@ -96,6 +100,28 @@ export interface SceneOptions {
      * Also settable later via {@link Scene.a11ySyncInterval}.
      */
     a11ySyncInterval?: number;
+    /**
+     * Per-node semantic projection policy (RFC3 §5, CTX-0599). Consulted by the
+     * single per-node decision point (`shouldProjectA11y`); the framework-known
+     * default projects everything the legacy predicate projects, so omitting
+     * this changes nothing. Also settable later via
+     * {@link Scene.semanticProjectionPolicy}.
+     */
+    semanticProjectionPolicy?: SemanticProjectionPolicy;
+    /**
+     * Consecutive syncs an `'auto'`-policy node must keep voting for the other
+     * backend before its sticky resolution flips (RFC4 §3 rule 3). Defaults to
+     * {@link PROJECTION_AUTO_HYSTERESIS_FRAMES}. Also settable later via
+     * {@link Scene.projectionHysteresisFrames}.
+     */
+    projectionHysteresisFrames?: number;
+    /**
+     * Maximum `'auto'`-resolved DOM residents per scene per frame (RFC4 §4
+     * particle-row backstop). Explicit `'dom'` requests bypass it. Defaults to
+     * {@link PROJECTION_AUTO_DOM_BUDGET}. Also settable later via
+     * {@link Scene.projectionAutoDomBudget}.
+     */
+    projectionAutoDomBudget?: number;
     /**
      * Custom renderer implementation (e.g., ThreeRenderer from @vectojs/three).
      * If provided, this renderer will be used for drawing rather than the default CanvasRenderer.
@@ -261,7 +287,7 @@ export interface SceneOptions {
  * against. A new option must be added here too — the test suite asserts the two
  * stay in sync.
  */
-export declare const SCENE_OPTION_KEYS: readonly ['a11ySyncInterval', 'autoThrottle', 'contentProjection', 'contentProjectionMargin', 'contentSemanticBudget', 'contentSemanticMargin', 'debugA11y', 'disableWindowResize', 'idleFPS', 'maxDPR', 'maxFPS', 'particleBackend', 'pointBackend', 'readingDirection', 'renderer', 'renderMode', 'respectReducedMotion', 'userTiming'];
+export declare const SCENE_OPTION_KEYS: readonly ['a11ySyncInterval', 'autoThrottle', 'contentProjection', 'contentProjectionMargin', 'contentSemanticBudget', 'contentSemanticMargin', 'debugA11y', 'disableWindowResize', 'idleFPS', 'maxDPR', 'maxFPS', 'particleBackend', 'pointBackend', 'readingDirection', 'renderer', 'renderMode', 'respectReducedMotion', 'semanticProjectionPolicy', 'userTiming'];
 /** Frame-rate the loop is capped to when the OS requests reduced motion. */
 export declare const REDUCED_MOTION_FPS = 30;
 export type { AcceleratorReason, AcceleratorStatus, AcceleratorReport };
@@ -507,6 +533,26 @@ export declare class Scene {
      * frame. See {@link SceneOptions.a11ySyncInterval}.
      */
     a11ySyncInterval: number;
+    /**
+     * Per-node semantic projection policy (RFC3 §5, CTX-0599). Consulted once
+     * per node by {@link shouldProjectA11y}; the default projects everything
+     * the legacy predicate projects, so reassigning nothing changes nothing.
+     * See {@link SceneOptions.semanticProjectionPolicy}.
+     */
+    semanticProjectionPolicy: SemanticProjectionPolicy;
+    /**
+     * Consecutive syncs an `'auto'`-policy node must keep voting for the other
+     * backend before its sticky resolution flips (RFC4 §3 rule 3, CTX-0601).
+     * Documented tunable — see {@link PROJECTION_AUTO_HYSTERESIS_FRAMES}.
+     */
+    projectionHysteresisFrames: number;
+    /**
+     * Maximum `'auto'`-resolved DOM residents per scene per frame (RFC4 §4
+     * particle-row backstop: bulk-count nodes stay canvas). Explicit `'dom'`
+     * requests bypass it. Documented tunable — see
+     * {@link PROJECTION_AUTO_DOM_BUDGET}.
+     */
+    projectionAutoDomBudget: number;
     /** Timestamp of the last a11y sync, for throttling. */
     private lastA11ySync;
     /** True if we skipped an a11y sync during animation and need to sync when at rest. */
@@ -700,6 +746,30 @@ export declare class Scene {
     private activePortalsThisFrame;
     private activePortalsPrevFrame;
     private portalEntities;
+    /**
+     * Generic projection backends (RFC1 §5 vocabulary, `tree/scene/ProjectionBackend.ts`).
+     * Render-independent: the interface exchanges only node identity, world
+     * matrix, and lifecycle calls, so registering a DOM backend adds no
+     * `HTMLElement` surface to core. `@vectojs/dom` owns the only implementation.
+     */
+    private projectionBackends;
+    /** Per-frame seen-sets driving {@link pruneProjectionBackends} (portal-precedent). */
+    private domSeenPrevFrame;
+    private domSeenThisFrame;
+    private domSeenNodes;
+    /**
+     * Negotiation state (RFC4 §3, CTX-0601): last resolution per node (the
+     * per-scene queryable surface behind {@link getProjectionResolutions}),
+     * hysteresis votes, per-kind capability overrides, and explicit gesture
+     * pins. Plain data only — no `HTMLElement` surface in core.
+     */
+    private projectionResolutions;
+    private projectionHysteresis;
+    private projectionCapabilityOverrides;
+    private projectionGesturePins;
+    /** Frame id the `'auto'` DOM budget count belongs to (bulk backstop). */
+    private projectionBudgetFrame;
+    private projectionDomAutoCount;
     private renderOrderCounter;
     /**
      * Monotonic render-frame counter, bumped once per authoritative `render()`
@@ -1188,6 +1258,24 @@ export declare class Scene {
      * (`DEC-0019` rule 5).
      */
     findEntityAt(x: number, y: number): Entity | null;
+    /**
+     * The merged hit list for a scene-space point: the canvas spatial test
+     * plus caller-observed DOM-native candidates (mirror / portal /
+     * `dom-visual` extension point for CTX-0598) as ONE ordered candidate
+     * list (`HitResult`, overlay order authoritative).
+     *
+     * Query API alongside {@link findEntityAt} — no dispatch change:
+     * `findEntityAt` keeps its single topmost answer byte-for-byte, keyboard
+     * and AT flows are untouched. For browser pointer coordinates use
+     * {@link findHitsAtClient}, which maps through {@link clientToScene} first.
+     */
+    findHitsAt(x: number, y: number, domCandidates?: DomHitCandidate[]): HitResult[];
+    /**
+     * {@link findHitsAt} for browser viewport coordinates: maps through
+     * {@link clientToScene} so coordinates enter in scene space (RFC5 §2
+     * rule 3) and backend attribution follows.
+     */
+    findHitsAtClient(clientX: number, clientY: number, domCandidates?: DomHitCandidate[]): HitResult[];
     /** Convert browser viewport coordinates into this Scene's logical coordinates. */
     clientToScene(clientX: number, clientY: number): {
         x: number;
@@ -1481,6 +1569,23 @@ export declare class Scene {
      * predicate, which is only tractable while it has one home.
      */
     private shouldProjectA11y;
+    /**
+     * Policy half of {@link shouldProjectA11y} (RFC3 §5, CTX-0599).
+     *
+     * The legacy gates above (interactive, box, `a11yProjection` engagement)
+     * are unchanged; this only maps a {@link SemanticProjectionPolicy} decision
+     * onto project/suppress. Out of the box the default policy returns
+     * `'project'`, so behaviour is identical to having no policy.
+     *
+     * `'defer-to-browser'` always falls back to projection today: no deferral
+     * backend exists (`supportsHTMLInCanvas()` is `false`), so deferring would
+     * silently drop semantics — the exact failure RFC §3 rules out. When a
+     * backend lands, only allow-listed plain display text
+     * ({@link isDeferrableSemanticNode}; never controls) may actually defer. A
+     * throwing policy likewise falls back to projection: a policy must never be
+     * able to drop semantics by accident.
+     */
+    private resolveSemanticProjection;
     /**
      * Whether an `a11yProjection: 'onDemand'` entity is currently engaged enough to
      * deserve a shadow node.
@@ -1610,6 +1715,89 @@ export declare class Scene {
     getA11yTree(): A11yTreeNode[];
     private renderPortalDOM;
     private reconcilePortals;
+    /**
+     * Register a generic projection backend (RFC1 §5, RFC2 P1 CTX-0598).
+     * Registration is idempotent per backend instance. Core drives
+     * mount/update/unmount from the render walk; the backend owns all
+     * medium-specific state.
+     */
+    addProjectionBackend(backend: ProjectionBackend): this;
+    /**
+     * Remove a previously registered projection backend by instance or
+     * {@link ProjectionBackendKind | kind}. Removing does not unmount resident
+     * nodes — unmount the backend first if teardown order matters.
+     */
+    removeProjectionBackend(backend: ProjectionBackend | ProjectionBackendKind): this;
+    /**
+     * Scene-level projection capabilities (RFC4 §3 rule 2, CTX-0601).
+     *
+     * Plain-data feature detection in the shape of the proposed
+     * `scene.inputCapabilities` (input-dispatch-contract-v2 §4): apps and
+     * devtools query where a node _would_ materialize and why, without touching
+     * any backend. Additive only — no existing surface moves.
+     */
+    get projectionCapabilities(): SceneProjectionCapabilities;
+    /**
+     * Register (or replace) the Capability Matrix row for one `domKind`
+     * (RFC4 §4, CTX-0601). Custom kinds start at the unknown-kind default
+     * (`unsupported-kind` → canvas); registering a row is how a custom backend
+     * kind opts into `'auto'` resolution and how tests drive oscillating costs.
+     */
+    registerProjectionCapability(domKind: string, row: ProjectionCapabilityRow): this;
+    /** Matrix row for a node's `domKind` (override wins, unknown → canvas). */
+    getProjectionCapability(node: Entity): ProjectionCapabilityRow;
+    /**
+     * Pin a node's backend for the duration of an active gesture (RFC4 §5 +
+     * input-dispatch-contract-v2 §4 gesture stickiness: no mid-gesture handoff).
+     * The a11y-mirror pointerdown/up/cancel listeners maintain this; DOM-side
+     * gestures are consulted through
+     * {@link ProjectionBackend.hasActiveGesture | backend.hasActiveGesture}.
+     * Refcounted so multi-pointer gestures on one node unpin exactly once.
+     */
+    pinProjectionForGesture(node: Entity): void;
+    /** Release one gesture pin taken by {@link pinProjectionForGesture}. */
+    unpinProjectionForGesture(node: Entity): void;
+    /** Whether `node` currently owns an active gesture on a core mirror. */
+    isProjectionPinned(node: Entity): boolean;
+    /**
+     * Last negotiation for one node, if it was ever resolved on this scene.
+     * Accepts the node or its id; returns the stored record (not a copy — treat
+     * as read-only).
+     */
+    getProjectionResolution(node: Entity | string): ProjectionResolution | undefined;
+    /** Every node's last negotiation, in first-resolution order. */
+    getProjectionResolutions(): readonly ProjectionResolution[];
+    /**
+     * Resolve one node's `domPolicy` to its effective backend (RFC4 §3, CTX-0601).
+     *
+     * Memoized per main frame (`currentFrame`, bumped once per authoritative
+     * render): the render walk and the later a11y sync must agree within a
+     * frame, or a node could lose its mirror the same frame it gains an element.
+     * `'auto'` applies, in order: no-DOM short-circuit → pure negotiation →
+     * gesture/focus hard bars (a pinned node keeps its current backend, never
+     * flips mid-gesture, focus is preserved-or-moved never dropped to `body` per
+     * input-dispatch-contract-v2 §4) → hysteresis stickiness → bulk budget.
+     * Every outcome is recorded on the per-scene queryable surface
+     * ({@link getProjectionResolutions}) with its reason — fallbacks are
+     * reported, not silent (§3 rule 2).
+     */
+    resolveProjectionFor(node: Entity): 'canvas' | 'dom';
+    /**
+     * Whether `node`'s a11y mirror currently owns browser focus (RFC4 §5 focus
+     * rule, input-dispatch-contract-v2 §4: focus stays DOM-based; flipping
+     * `projection` must preserve or deliberately move focus, never drop it to
+     * `body`). A focused node keeps its backend until blur — the actual move, if
+     * any, goes through the existing sentinels (`preserveFocusOnRemoval`, the
+     * DOM backend's own fallback), never a bare removal.
+     */
+    private ownsProjectionFocus;
+    /**
+     * RFC2 P1 (CTX-0598): unmount DOM-projection residents the walk did not see
+     * this frame (viewport-culled, removed without `remove()`, policy-flipped).
+     * Mirrors {@link reconcilePortals} above; unmount is idempotent per the
+     * `ProjectionBackend` contract so notifying every backend is safe.
+     */
+    private pruneProjectionBackends;
     /**
      * The frame-rate cap actually in effect: the explicit {@link maxFPS}, further
      * lowered to {@link REDUCED_MOTION_FPS} when the OS requests reduced motion
@@ -1620,6 +1808,12 @@ export declare class Scene {
     /**
      * Render the entire scene graph onto the specified renderer.
      *
+     * This is the `CanvasProjection` row of {@link ProjectionBackend}:
+     * the per-frame materialization of scene semantics into pixels through the
+     * backend-agnostic `IRenderer` contract. (The `A11yProjection` /
+     * `ContentProjection` rows run on the same cadence via {@link Scene.syncA11y}
+     * below; the `DOMProjection` row does not exist yet — RFC2/CTX-0598.)
+     *
      * Main-frame causal order is a correctness contract:
      *
      * 1. Browser/input callbacks finish before the scheduled frame begins.

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

@@ -0,0 +1,50 @@
+import type { Entity, Point } from '../Entity';
+/**
+ * Which medium painted the hit node (RFC5 §2, CTX-0600).
+ *
+ * - `'canvas'` — the canvas spatial test (`Scene.findEntityAt`).
+ * - `'mirror'` — an `a11yRoot` mirror element under the cursor.
+ * - `'portal'` — a `portalRoot` element (`DOMPortalEntity` bridge precedent,
+ *   `tree/DOMPortalEntity.ts:64-99`).
+ * - `'dom-visual'` — extension point for CTX-0598's DOM backend: accepted and
+ *   attributed through the same predicate path today, without depending on
+ *   that package existing yet.
+ */
+export type HitBackend = 'canvas' | 'dom-visual' | 'mirror' | 'portal';
+/**
+ * One candidate in the merged hit list (RFC5 §2).
+ *
+ * Coordinates enter in scene space and attribution follows (RFC5 §2 rule 3):
+ * `worldPoint` is the queried scene-space point, `localPoint` is that point
+ * in the node's local space (`Entity.worldToLocal`, `null` when the
+ * accumulated transform is singular).
+ *
+ * `priority` is compositor-layer order, then paint order (RFC5 §2 rule 2 and
+ * §3): the overlay subtree sorts above the main tree, and within one subtree
+ * DOM-native backends sort above canvas. Computed as
+ * `(inOverlaySubtree ? 2 : 0) + (backend === 'canvas' ? 0 : 1)`, so
+ * overlay-DOM (3) > overlay-canvas (2) > main-DOM (1) > main-canvas (0).
+ * Sort descending; ties keep insertion order (stable sort).
+ */
+export interface HitResult {
+    node: Entity;
+    backend: HitBackend;
+    localPoint: Point | null;
+    worldPoint: Point;
+    priority: number;
+}
+/**
+ * A caller-observed DOM-native hit offered to the merge
+ * (`HitTester.findHitsAt`). The browser's own hit test over the
+ * `pointer-events: auto` element is the geometric authority, so the merge
+ * gates the owning node with the same visibility/input predicate as the
+ * canvas paths (`disabled` / `pointerEvents: 'none'` exclusion, opacity,
+ * `clipChildren`) but does not re-check scene-space `isPointInside`.
+ *
+ * `'canvas'` is excluded: canvas candidates come from the spatial test, never
+ * from the caller.
+ */
+export interface DomHitCandidate {
+    node: Entity;
+    backend: Exclude<HitBackend, 'canvas'>;
+}

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

@@ -56,6 +56,7 @@
  * captured at construction without going stale.
  */
 import type { Bounds, Entity } from '../Entity';
+import type { DomHitCandidate, HitResult } from './HitResult';
 import type { WasmBackendFacade } from './WasmBackendFacade';
 export declare class HitTester {
     private readonly root;
@@ -76,6 +77,35 @@ export declare class HitTester {
      * @param height - Scene logical height, for the grid's extent.
      */
     findEntityAt(x: number, y: number, frame: number, width: number, height: number): Entity | null;
+    /**
+     * The merged hit list (RFC5 §2, CTX-0600): the canvas spatial test plus
+     * caller-observed DOM-native candidates (mirror / portal / `dom-visual`
+     * extension point for CTX-0598) as ONE ordered candidate list.
+     *
+     * Query API only — no dispatch change: `findEntityAt` keeps its single
+     * topmost answer byte-for-byte. Coordinates enter in scene space (callers
+     * map client coordinates first, e.g. `Scene.findHitsAtClient`); backend
+     * attribution follows. DOM candidates pass through the same
+     * `disabled` / `pointerEvents: 'none'` predicate as the canvas paths
+     * (RFC5 §2 rule 4); the browser's hit test is their geometric authority,
+     * so scene-space `isPointInside` is not re-checked.
+     *
+     * Overlay order is authoritative (RFC5 §2 rule 2): overlay-subtree
+     * candidates sort above main-tree candidates, DOM-native backends above
+     * canvas within one subtree. Sorted descending by `priority`; ties keep
+     * insertion order (canvas overlay, canvas main, then DOM in caller order).
+     */
+    findHitsAt(x: number, y: number, frame: number, width: number, height: number, domCandidates?: DomHitCandidate[]): HitResult[];
+    /**
+     * Attribute one candidate: scene-space point plus node-local point, with
+     * the compositor-layer priority (overlay subtree above main tree,
+     * DOM-native backends above canvas within one subtree).
+     */
+    private toHitResult;
+    /** Whether `node` lives under the overlay root (drawn above the main tree). */
+    private isInOverlaySubtree;
+    /** Main-tree arm of {@link findEntityAt}, shared with {@link findHitsAt}. */
+    private findMainTreeHit;
     /**
      * 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 —

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

@@ -0,0 +1,64 @@
+import type { AffineTransform, Entity } from '../Entity';
+/**
+ * Stable backend id for telemetry and capability negotiation (cf. RFC4).
+ *
+ * The three literals name the projections that exist today; the open-ended
+ * tail leaves room for RFC2+ backends without touching this type. `'content'`
+ * extends the RFC1 sketch's `canvas | dom | a11y` union: the sketch's table
+ * already lists `ContentProjection` as a first-class row, so the kind union
+ * names it too.
+ */
+export type ProjectionBackendKind = 'canvas' | 'dom' | 'a11y' | 'content' | (string & {});
+/**
+ * A materialization of scene nodes in one medium: canvas pixels, an
+ * `HTMLElement` subtree, an accessibility node, or a future backend's own
+ * representation.
+ *
+ * This is vocabulary, not machinery (RFC1 §5, CTX-0597): it names the
+ * mount/update/unmount shape the existing projections already follow so
+ * RFC2 (DOM projection), RFC3 (semantic/a11y projection), and RFC4
+ * (projection policy) can each name which row they implement or consume.
+ * Nothing implements this interface yet — the rows below map each proposed
+ * backend onto the code that performs its role today, with the invariant
+ * from RFC1 §2: two projections of the same node must agree on geometry
+ * (world matrix), visibility, and lifecycle state, while each keeps its own
+ * medium-specific representation.
+ *
+ * | Backend (proposed name) | Exists today as | Mount site |
+ * | ----------------------- | --------------- | ---------- |
+ * | `CanvasProjection` (`'canvas'`) | the main render pass via `IRenderer` | `Scene.render(renderer)` (`tree/Scene.ts`) → per-entity `Entity.render` (`tree/Entity.ts`) |
+ * | `A11yProjection` (`'a11y'`) | `A11yProjectionManager` + `a11yRoot` mirrors | mirror creation in the `Scene.syncA11y` walk (`tree/Scene.ts`); ordering in `A11yProjectionManager` |
+ * | `ContentProjection` (`'content'`) | `ContentProjectionManager` + `Entity.getContentProjection` | `Scene.syncContentProjection`, driven on the a11y sync cadence (`tree/Scene.ts`) |
+ * | `DOMProjection` (`'dom'`) | **does not exist** — RFC2's work item (CTX-0598) | — (`DOMPortalEntity` is the pilot consumer, not the backend) |
+ *
+ * Open points deliberately left to RFC2/RFC4 (RFC1 §5): whether `update`
+ * receives the full matrix or a decomposed transform, how z-order/layering
+ * composes canvas pixels under/over DOM elements, and event forwarding
+ * ownership (constrained by `forge/input-dispatch-contract-v2-design.md` §4).
+ */
+export interface ProjectionBackend {
+    /** Stable backend id for telemetry and capability negotiation (cf. RFC4). */
+    readonly kind: ProjectionBackendKind;
+    /** Create backend state for a newly materialized node. Idempotent. */
+    mount(node: Entity): void;
+    /**
+     * Reconcile backend state after a layout/transform/visibility change.
+     *
+     * Takes the node's {@link Entity.getWorldTransform | world transform} as
+     * {@link AffineTransform} rather than the sketch's `Float64Array`: that is
+     * what the scene computes today, and it converts losslessly to the
+     * `matrix3d()` a DOM backend wants. The matrix-vs-decomposed question stays
+     * open for RFC2/RFC4 per RFC1 §5.
+     */
+    update(node: Entity, worldMatrix: AffineTransform): void;
+    /** Tear down backend state on removal or policy change. Idempotent. */
+    unmount(node: Entity): void;
+    /**
+     * Whether `node` currently owns an active gesture on this backend (RFC4 §5,
+     * CTX-0601). Consulted by the scene's capability negotiation alongside its
+     * own mirror pins: a pinned node keeps its backend until gesture end —
+     * input-dispatch-contract-v2 §4 gesture stickiness, no mid-gesture handoff.
+     * Optional so test fakes stay three methods; absent means "no gestures".
+     */
+    hasActiveGesture?(node: Entity): boolean;
+}