@vectojs/core 1.39.1 → 1.40.1

package/dist/index.mjs

@@ -18,7 +18,7 @@ import {
   SVGEntity,
   VectoJSEvent,
   contentLineInHint
-} from "./chunk-7PYD5UDX.mjs";
+} from "./chunk-CIRZ3S2Z.mjs";
 
 // src/tree/ComputeParticleEntity.ts
 var PARTICLE_STRIDE_FLOATS = 8;
@@ -1598,6 +1598,62 @@ var HitTester = class {
   findEntityAt(x, y, frame, width, height) {
     const overlayHit = this.findHitRecursively(this.overlayRoot, x, y);
     if (overlayHit) return overlayHit;
+    return this.findMainTreeHit(x, y, frame, width, height);
+  }
+  /**
+   * 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, y, frame, width, height, domCandidates = []) {
+    const results = [];
+    const overlayHit = this.findHitRecursively(this.overlayRoot, x, y);
+    if (overlayHit) results.push(this.toHitResult(overlayHit, "canvas", x, y));
+    const mainHit = this.findMainTreeHit(x, y, frame, width, height);
+    if (mainHit) results.push(this.toHitResult(mainHit, "canvas", x, y));
+    for (const candidate of domCandidates) {
+      if (!this.isHitEligible(candidate.node, x, y)) continue;
+      results.push(this.toHitResult(candidate.node, candidate.backend, x, y));
+    }
+    results.sort((a, b) => b.priority - a.priority);
+    return results;
+  }
+  /**
+   * 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).
+   */
+  toHitResult(node, backend, x, y) {
+    return {
+      node,
+      backend,
+      localPoint: node.worldToLocal(x, y),
+      worldPoint: { x, y },
+      priority: (this.isInOverlaySubtree(node) ? 2 : 0) + (backend === "canvas" ? 0 : 1)
+    };
+  }
+  /** Whether `node` lives under the overlay root (drawn above the main tree). */
+  isInOverlaySubtree(node) {
+    for (let current = node; current; current = current.parent) {
+      if (current === this.overlayRoot) return true;
+    }
+    return false;
+  }
+  /** Main-tree arm of {@link findEntityAt}, shared with {@link findHitsAt}. */
+  findMainTreeHit(x, y, frame, width, height) {
     if (this.backends.hit && this.ensureHitGrid(frame, width, height)) {
       return this.findEntityAtWasm(x, y);
     }
@@ -3501,6 +3557,207 @@ function normalizeChord(input) {
   return ordered.join("+");
 }
 
+// src/tree/scene/SemanticProjectionPolicy.ts
+var DEFAULT_SEMANTIC_PROJECTION_POLICY = {
+  choose: () => "project"
+};
+function getSemanticProjectionCapabilities() {
+  return {
+    htmlInCanvas: supportsHTMLInCanvas(),
+    canvasTextRecovery: false
+  };
+}
+var CONTROL_SEMANTIC_ROLES = /* @__PURE__ */ new Set([
+  "button",
+  "link",
+  "checkbox",
+  "radio",
+  "switch",
+  "slider",
+  "spinbutton",
+  "combobox",
+  "listbox",
+  "option",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "tab",
+  "textbox",
+  "searchbox",
+  "progressbar",
+  "scrollbar",
+  "meter"
+]);
+function isDeferrableSemanticNode(node) {
+  const attrs = node.getA11yAttributes();
+  if (attrs.tag !== void 0 && attrs.tag !== "div") return false;
+  if (attrs.role !== void 0 && CONTROL_SEMANTIC_ROLES.has(attrs.role)) return false;
+  if (typeof attrs.tabIndex === "number" && attrs.tabIndex >= 0) return false;
+  const projection = node.getContentProjection?.();
+  if (projection?.selectable) return false;
+  return true;
+}
+function describeHTMLInCanvasSupport() {
+  if (typeof document === "undefined") return { supported: false, reason: "no-dom" };
+  try {
+    const canvas = document.createElement("canvas");
+    const ctx = canvas.getContext("2d");
+    const native2D = typeof CanvasRenderingContext2D !== "undefined" && ctx instanceof CanvasRenderingContext2D;
+    if (native2D && typeof ctx["drawElementImage"] === "function") {
+      return { supported: true };
+    }
+  } catch {
+    return { supported: false, reason: "no-backend" };
+  }
+  return { supported: false, reason: "no-backend" };
+}
+function supportsHTMLInCanvas() {
+  return describeHTMLInCanvasSupport().supported;
+}
+
+// src/tree/scene/ProjectionPolicy.ts
+var DEFAULT_PROJECTION_CAPABILITIES = {
+  /** Static text (short): findability already covered by content projection. */
+  text: {
+    domSupported: true,
+    nativeValue: "medium",
+    domCost: "low",
+    canvasCost: "low",
+    autoDefault: "canvas"
+  },
+  /** Long/selectable text, Markdown blocks: selection, Ctrl+F, translation. */
+  prose: {
+    domSupported: true,
+    nativeValue: "high",
+    domCost: "medium",
+    canvasCost: "high",
+    autoDefault: "dom"
+  },
+  /** Code blocks: selectable source, but canvas carriers already serve selection — rests canvas until measured (RFC4 §6 hybrid mapping). */
+  code: {
+    domSupported: true,
+    nativeValue: "medium",
+    domCost: "medium",
+    canvasCost: "high",
+    autoDefault: "canvas"
+  },
+  /** Text input / editable: IME, caret, clipboard, BiDi come free in DOM. */
+  input: {
+    domSupported: true,
+    nativeValue: "high",
+    domCost: "low",
+    canvasCost: "prohibitive",
+    autoDefault: "dom"
+  },
+  /** Button / Link: cheap either way, native wins on focus + AT clicks. */
+  button: {
+    domSupported: true,
+    nativeValue: "medium",
+    domCost: "low",
+    canvasCost: "low",
+    autoDefault: "dom"
+  },
+  link: {
+    domSupported: true,
+    nativeValue: "medium",
+    domCost: "low",
+    canvasCost: "low",
+    autoDefault: "dom"
+  },
+  /** Select / Dropdown / Checkbox / Radio: popup, keyboard, form semantics. */
+  select: {
+    domSupported: true,
+    nativeValue: "high",
+    domCost: "low",
+    canvasCost: "high",
+    autoDefault: "dom"
+  },
+  /** Container / layout group: no direct representation, children negotiate. */
+  container: {
+    domSupported: true,
+    nativeValue: "none",
+    domCost: "n/a",
+    canvasCost: "low",
+    autoDefault: "canvas"
+  },
+  /** Transform / camera rig: owns space, not pixels — never materialized. */
+  transform: {
+    domSupported: true,
+    nativeValue: "none",
+    domCost: "n/a",
+    canvasCost: "n/a",
+    autoDefault: "canvas"
+  },
+  /** Image / video frame: blit is cheap, one element per item is not. */
+  image: {
+    domSupported: true,
+    nativeValue: "low",
+    domCost: "medium",
+    canvasCost: "low",
+    autoDefault: "canvas"
+  },
+  /** Particles / danmaku / chart glyphs: bulk stays canvas, unconditionally. */
+  particles: {
+    domSupported: true,
+    nativeValue: "none",
+    domCost: "prohibitive",
+    canvasCost: "low",
+    autoDefault: "canvas"
+  },
+  /** Graph nodes/edges (interactive, moderate count): canvas until measured. */
+  graph: {
+    domSupported: true,
+    nativeValue: "low",
+    domCost: "medium",
+    canvasCost: "medium",
+    autoDefault: "canvas"
+  },
+  /** Custom shader / GPU particles: no DOM representation exists. */
+  shader: {
+    domSupported: false,
+    nativeValue: "none",
+    domCost: "unsupported",
+    canvasCost: "low",
+    autoDefault: "canvas"
+  }
+};
+var UNKNOWN_PROJECTION_CAPABILITY = {
+  domSupported: false,
+  nativeValue: "none",
+  domCost: "unsupported",
+  canvasCost: "low",
+  autoDefault: "canvas"
+};
+var PROJECTION_AUTO_HYSTERESIS_FRAMES = 3;
+var PROJECTION_AUTO_DOM_BUDGET = 500;
+function resolveProjection(want, cap, ctx) {
+  if (want === "canvas") return { resolved: "canvas", reason: null };
+  if (!ctx.hasDOM || !ctx.domBackendMounted) {
+    return { resolved: "canvas", reason: "no-dom-backend" };
+  }
+  if (!cap.domSupported) return { resolved: "canvas", reason: "unsupported-kind" };
+  if (want === "dom") {
+    if (cap.domCost === "prohibitive") return { resolved: "canvas", reason: "prohibitive-cost" };
+    return { resolved: "dom", reason: null };
+  }
+  if (cap.nativeValue === "high" && cap.domCost !== "prohibitive") {
+    return { resolved: "dom", reason: null };
+  }
+  if (cap.canvasCost === "prohibitive" && cap.domSupported) {
+    return { resolved: "dom", reason: null };
+  }
+  if (cap.autoDefault === "dom") return { resolved: "dom", reason: null };
+  return { resolved: "canvas", reason: null };
+}
+function hysteresisVote(current, desired, consecutive, hysteresisFrames) {
+  if (current === void 0 || current === desired) {
+    return { resolved: desired, consecutive: 0, flipped: false };
+  }
+  const next = consecutive + 1;
+  if (next >= hysteresisFrames) return { resolved: desired, consecutive: 0, flipped: true };
+  return { resolved: current, consecutive: next, flipped: false };
+}
+
 // src/tree/Scene.ts
 var RANGE_VALUE_ROLES = /* @__PURE__ */ new Set(["slider", "spinbutton", "progressbar", "scrollbar", "meter"]);
 var INTERACTIVE_A11Y_ROLES = /* @__PURE__ */ new Set([
@@ -3524,7 +3781,8 @@ var KEYBOARD_OWNING_ROLES = /* @__PURE__ */ new Set([
 ]);
 function ownsKeyboard(el) {
   if (!el) return false;
-  if (el === document.body || el === document.documentElement) return false;
+  if (typeof document !== "undefined" && (el === document.body || el === document.documentElement))
+    return false;
   if (el.hasAttribute("data-vecto-a11y-root")) return false;
   const tag = el.tagName;
   if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return true;
@@ -3560,10 +3818,13 @@ var SCENE_OPTION_KEYS = [
   "maxFPS",
   "particleBackend",
   "pointBackend",
+  "projectionAutoDomBudget",
+  "projectionHysteresisFrames",
   "readingDirection",
   "renderer",
   "renderMode",
   "respectReducedMotion",
+  "semanticProjectionPolicy",
   "userTiming"
 ];
 var SCENE_FIELD_NOT_OPTION = {
@@ -4061,6 +4322,26 @@ var Scene = class _Scene {
    * frame. See {@link SceneOptions.a11ySyncInterval}.
    */
   a11ySyncInterval = 0;
+  /**
+   * 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 = DEFAULT_SEMANTIC_PROJECTION_POLICY;
+  /**
+   * 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 = PROJECTION_AUTO_HYSTERESIS_FRAMES;
+  /**
+   * 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 = PROJECTION_AUTO_DOM_BUDGET;
   /** Timestamp of the last a11y sync, for throttling. */
   lastA11ySync = -Infinity;
   /** True if we skipped an a11y sync during animation and need to sync when at rest. */
@@ -4291,6 +4572,30 @@ var Scene = class _Scene {
   activePortalsThisFrame = /* @__PURE__ */ new Set();
   activePortalsPrevFrame = /* @__PURE__ */ new Set();
   portalEntities = /* @__PURE__ */ new Map();
+  /**
+   * 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.
+   */
+  projectionBackends = [];
+  /** Per-frame seen-sets driving {@link pruneProjectionBackends} (portal-precedent). */
+  domSeenPrevFrame = /* @__PURE__ */ new Set();
+  domSeenThisFrame = /* @__PURE__ */ new Set();
+  domSeenNodes = /* @__PURE__ */ new Map();
+  /**
+   * 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.
+   */
+  projectionResolutions = /* @__PURE__ */ new Map();
+  projectionHysteresis = /* @__PURE__ */ new Map();
+  projectionCapabilityOverrides = /* @__PURE__ */ new Map();
+  projectionGesturePins = /* @__PURE__ */ new Map();
+  /** Frame id the `'auto'` DOM budget count belongs to (bulk backstop). */
+  projectionBudgetFrame = -1;
+  projectionDomAutoCount = 0;
   renderOrderCounter = 0;
   // --- domain: render-scheduler — authoritative frame counter ---
   /**
@@ -4954,6 +5259,9 @@ var Scene = class _Scene {
     this.phases.userTiming = options.userTiming ?? false;
     this.particleBackend = options.particleBackend ?? "auto";
     this.a11ySyncInterval = options.a11ySyncInterval ?? 0;
+    this.semanticProjectionPolicy = options.semanticProjectionPolicy ?? DEFAULT_SEMANTIC_PROJECTION_POLICY;
+    this.projectionHysteresisFrames = options.projectionHysteresisFrames ?? PROJECTION_AUTO_HYSTERESIS_FRAMES;
+    this.projectionAutoDomBudget = options.projectionAutoDomBudget ?? PROJECTION_AUTO_DOM_BUDGET;
     this.contentProjectionEnabled = options.contentProjection ?? true;
     this.contentProjectionMargin = options.contentProjectionMargin;
     this.contentSemanticMargin = options.contentSemanticMargin;
@@ -5305,6 +5613,37 @@ var Scene = class _Scene {
   findEntityAt(x, y) {
     return this._hitTester.findEntityAt(x, y, this.currentFrame, this.width, this.height);
   }
+  // --- domain: hit-test — merged HitResult query (RFC5 §2, CTX-0600) ---
+  /**
+   * 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, y, domCandidates = []) {
+    return this._hitTester.findHitsAt(
+      x,
+      y,
+      this.currentFrame,
+      this.width,
+      this.height,
+      domCandidates
+    );
+  }
+  /**
+   * {@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, clientY, domCandidates = []) {
+    const point = this.clientToScene(clientX, clientY);
+    return this.findHitsAt(point.x, point.y, domCandidates);
+  }
   // --- domain: hit-test — client-to-scene mapping ---
   /** Convert browser viewport coordinates into this Scene's logical coordinates. */
   clientToScene(clientX, clientY) {
@@ -5345,6 +5684,15 @@ var Scene = class _Scene {
       this.activePortalsThisFrame.delete(node.id);
       this.activePortalsPrevFrame.delete(node.id);
     }
+    if (node.domPolicy === "dom" || node.domResident) {
+      for (const backend of this.projectionBackends) backend.unmount(node);
+      this.domSeenThisFrame.delete(node.id);
+      this.domSeenPrevFrame.delete(node.id);
+      this.domSeenNodes.delete(node.id);
+    }
+    this.projectionResolutions.delete(node.id);
+    this.projectionHysteresis.delete(node.id);
+    this.projectionGesturePins.delete(node.id);
     const contentEl = this.contentElements.get(node.id);
     if (contentEl) {
       this._contentProjection.clearGridState(node.id, contentEl);
@@ -5456,6 +5804,15 @@ var Scene = class _Scene {
     while (this.overlayRoot.children.length > 0) {
       this.destroyEntitySubtree(this.overlayRoot.children.at(-1));
     }
+    for (const node of this.domSeenNodes.values()) {
+      for (const backend of this.projectionBackends) backend.unmount(node);
+    }
+    this.domSeenNodes.clear();
+    this.domSeenThisFrame.clear();
+    this.domSeenPrevFrame.clear();
+    this.projectionResolutions.clear();
+    this.projectionHysteresis.clear();
+    this.projectionGesturePins.clear();
     if (typeof window !== "undefined" && !this.disableWindowResize) {
       window.removeEventListener("resize", this.resizeHandler);
     }
@@ -5954,15 +6311,48 @@ var Scene = class _Scene {
   shouldProjectA11y(node) {
     if (!node.interactive) return false;
     if (!(node.width > 0 || node.a11yFullViewport)) return false;
+    if (this.resolveProjectionFor(node) === "dom") return false;
     switch (node.a11yProjection) {
       case "never":
         return false;
       case "onDemand":
-        return this.a11yEngaged(node);
+        return this.a11yEngaged(node) && this.resolveSemanticProjection(node);
       default:
-        return true;
+        return this.resolveSemanticProjection(node);
     }
   }
+  /**
+   * 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.
+   */
+  resolveSemanticProjection(node) {
+    const policy = this.semanticProjectionPolicy ?? DEFAULT_SEMANTIC_PROJECTION_POLICY;
+    let decision;
+    try {
+      decision = policy.choose(node, getSemanticProjectionCapabilities(), {
+        hasDOM: this.a11yRoot !== null
+      });
+    } catch {
+      decision = "project";
+    }
+    if (decision === "never") return false;
+    if (decision === "defer-to-browser" && isDeferrableSemanticNode(node) && supportsHTMLInCanvas()) {
+      return false;
+    }
+    return true;
+  }
   /**
    * Whether an `a11yProjection: 'onDemand'` entity is currently engaged enough to
    * deserve a shadow node.
@@ -6131,14 +6521,17 @@ var Scene = class _Scene {
           if (e.target === capEl && typeof capEl.setPointerCapture === "function") {
             capEl.setPointerCapture(e.pointerId);
           }
+          this.pinProjectionForGesture(node);
           node.dispatchEvent(new VectoJSEvent("pointerdown", node, e));
         });
         el.addEventListener("pointerup", (e) => {
           releasePointer(e);
+          this.unpinProjectionForGesture(node);
           node.dispatchEvent(new VectoJSEvent("pointerup", node, e));
         });
         el.addEventListener("pointercancel", (e) => {
           releasePointer(e);
+          this.unpinProjectionForGesture(node);
           node.dispatchEvent(new VectoJSEvent("pointercancel", node, e));
         });
         el.addEventListener(
@@ -7099,6 +7492,197 @@ var Scene = class _Scene {
     this.activePortalsPrevFrame = new Set(this.activePortalsThisFrame);
     this.activePortalsThisFrame.clear();
   }
+  /**
+   * 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) {
+    if (!this.projectionBackends.includes(backend)) this.projectionBackends.push(backend);
+    return 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) {
+    this.projectionBackends = this.projectionBackends.filter(
+      (b) => typeof backend === "string" ? b.kind !== backend : b !== backend
+    );
+    return 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() {
+    return {
+      hasDOM: typeof document !== "undefined",
+      domBackendMounted: this.projectionBackends.some((b) => b.kind === "dom"),
+      backends: this.projectionBackends.map((b) => b.kind),
+      autoHysteresisFrames: this.projectionHysteresisFrames,
+      autoDomBudget: this.projectionAutoDomBudget
+    };
+  }
+  /**
+   * 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, row) {
+    this.projectionCapabilityOverrides.set(domKind, row);
+    return this;
+  }
+  /** Matrix row for a node's `domKind` (override wins, unknown → canvas). */
+  getProjectionCapability(node) {
+    return this.projectionCapabilityOverrides.get(node.domKind) ?? DEFAULT_PROJECTION_CAPABILITIES[node.domKind] ?? UNKNOWN_PROJECTION_CAPABILITY;
+  }
+  /**
+   * 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) {
+    this.projectionGesturePins.set(node.id, (this.projectionGesturePins.get(node.id) ?? 0) + 1);
+  }
+  /** Release one gesture pin taken by {@link pinProjectionForGesture}. */
+  unpinProjectionForGesture(node) {
+    const count = (this.projectionGesturePins.get(node.id) ?? 0) - 1;
+    if (count <= 0) this.projectionGesturePins.delete(node.id);
+    else this.projectionGesturePins.set(node.id, count);
+  }
+  /** Whether `node` currently owns an active gesture on a core mirror. */
+  isProjectionPinned(node) {
+    return (this.projectionGesturePins.get(node.id) ?? 0) > 0;
+  }
+  /**
+   * 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) {
+    return this.projectionResolutions.get(typeof node === "string" ? node : node.id);
+  }
+  /** Every node's last negotiation, in first-resolution order. */
+  getProjectionResolutions() {
+    return [...this.projectionResolutions.values()];
+  }
+  /**
+   * 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) {
+    const want = node.domPolicy;
+    if (this.projectionBackends.length === 0 && want === "canvas") return "canvas";
+    const memo = this.projectionHysteresis.get(node.id);
+    if (memo && memo.lastFrame === this.currentFrame) return memo.resolved;
+    const hasDOM = typeof document !== "undefined";
+    const domBackendMounted = this.projectionBackends.some((b) => b.kind === "dom");
+    const outcome = resolveProjection(want, this.getProjectionCapability(node), {
+      hasDOM,
+      domBackendMounted
+    });
+    let resolved = outcome.resolved;
+    let reason = outcome.reason;
+    if (want === "auto" && memo !== void 0) {
+      if (resolved !== memo.resolved) {
+        const gesturePinned = this.isProjectionPinned(node) || this.projectionBackends.some((b) => b.hasActiveGesture?.(node) === true);
+        if (gesturePinned) {
+          resolved = memo.resolved;
+          reason = "active-gesture";
+        } else if (this.ownsProjectionFocus(node)) {
+          resolved = memo.resolved;
+          reason = "focus-pinned";
+        } else {
+          const vote = hysteresisVote(
+            memo.resolved,
+            resolved,
+            memo.consecutive,
+            this.projectionHysteresisFrames
+          );
+          resolved = vote.resolved;
+          memo.consecutive = vote.consecutive;
+          reason = vote.flipped ? reason : "hysteresis";
+        }
+      } else {
+        memo.consecutive = 0;
+      }
+    }
+    if (want === "auto" && resolved === "dom") {
+      if (this.projectionBudgetFrame !== this.currentFrame) {
+        this.projectionBudgetFrame = this.currentFrame;
+        this.projectionDomAutoCount = 0;
+      }
+      this.projectionDomAutoCount += 1;
+      if (this.projectionDomAutoCount > this.projectionAutoDomBudget) {
+        resolved = "canvas";
+        reason = "bulk-budget";
+      }
+    }
+    this.projectionHysteresis.set(node.id, {
+      resolved,
+      consecutive: memo?.consecutive ?? 0,
+      lastFrame: this.currentFrame
+    });
+    const prev = this.projectionResolutions.get(node.id);
+    if (!prev || prev.want !== want || prev.resolved !== resolved || prev.reason !== reason) {
+      this.projectionResolutions.set(node.id, { nodeId: node.id, want, resolved, reason });
+    }
+    return resolved;
+  }
+  /**
+   * 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.
+   */
+  ownsProjectionFocus(node) {
+    if (typeof document === "undefined") return false;
+    const mirror = this.a11yElements.get(node.id);
+    if (!mirror || mirror !== this.focusedA11yElement) return false;
+    return document.activeElement === mirror;
+  }
+  /**
+   * 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.
+   */
+  pruneProjectionBackends() {
+    for (const id of this.domSeenPrevFrame) {
+      if (!this.domSeenThisFrame.has(id)) {
+        const node = this.domSeenNodes.get(id);
+        if (node) {
+          for (const backend of this.projectionBackends) backend.unmount(node);
+          this.domSeenNodes.delete(id);
+        }
+      }
+    }
+    this.domSeenPrevFrame = new Set(this.domSeenThisFrame);
+    this.domSeenThisFrame.clear();
+  }
   // --- domain: render-scheduler — the loop and the render walk ---
   /**
    * The frame-rate cap actually in effect: the explicit {@link maxFPS}, further
@@ -7176,6 +7760,13 @@ var Scene = 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 lives in `@vectojs/dom` and is driven from
+   * the render walk further below.)
+   *
    * Main-frame causal order is a correctness contract:
    *
    * 1. Browser/input callbacks finish before the scheduled frame begins.
@@ -7468,6 +8059,16 @@ var Scene = class _Scene {
         visible = maxX >= 0 && minX <= vw && maxY >= 0 && minY <= vh;
       }
       if (!visible && node.children.length === 0) return;
+      if (isMainRenderer && this.projectionBackends.length > 0 && this.resolveProjectionFor(node) === "dom" && visible) {
+        for (const backend of this.projectionBackends) {
+          backend.update(node, { a, b, c, d, e: te, f: tf });
+        }
+        if (node.domResident) {
+          this.domSeenThisFrame.add(node.id);
+          this.domSeenNodes.set(node.id, node);
+          if (node.children.length === 0) return;
+        }
+      }
       if (node.children.length === 0 && node.scaleX === node.scaleY) {
         const bc = node.getBatchCircle();
         if (bc) {
@@ -7597,6 +8198,7 @@ var Scene = class _Scene {
       this.frameHadAnimation = walkHadAnimation;
       this.frameHadInteractive = walkHadInteractive;
       this.reconcilePortals();
+      this.pruneProjectionBackends();
     }
     const flushTiming = this.phases.userTiming ? beginVectoUserTiming(VECTO_USER_TIMING.scene.flush) : null;
     const flushT0 = this.phases.enabled ? performance.now() : 0;
@@ -8033,6 +8635,238 @@ var TextEntity = class extends Entity {
   }
 };
 
+// src/components/VirtualizedSetAggregate.ts
+var VirtualizedSetAggregate = class extends Entity {
+  _items;
+  _label;
+  _role;
+  _itemRole;
+  _rowHeight;
+  _visibleCapacity;
+  _onActivate;
+  /** First item index currently bound to the pool (the scroll window). */
+  _visibleStart = 0;
+  /** Item id owning the roving tab stop / keyboard focus. */
+  _activeId = null;
+  _selectedId = null;
+  /** One focusable hotspot per visible slot; re-bound, never rebuilt per item. */
+  _hotspots = [];
+  constructor(opts = {}) {
+    super();
+    this._items = opts.items ?? [];
+    this._label = opts.label ?? "Items";
+    this._role = opts.role ?? "list";
+    this._itemRole = opts.itemRole ?? "listitem";
+    this._rowHeight = opts.rowHeight ?? 28;
+    this._visibleCapacity = opts.visibleCapacity;
+    this._onActivate = opts.onActivate;
+    this.width = opts.width ?? 0;
+    this.height = opts.height ?? 0;
+    this.interactive = true;
+    this._syncHotspots();
+  }
+  /** Full item count — the number the container label states. */
+  get itemCount() {
+    return this._items.length;
+  }
+  /** Live pool size (bounded by the visible capacity, never by the item count). */
+  get poolSize() {
+    return this._hotspots.length;
+  }
+  /** First item index currently bound to the pool. */
+  get visibleStart() {
+    return this._visibleStart;
+  }
+  getA11yAttributes() {
+    return {
+      role: this._role,
+      label: `${this._label}, ${this._items.length} items`,
+      pointerEvents: "none"
+    };
+  }
+  render(_renderer) {
+  }
+  /** Axis-aligned hit-test against the container box (the `UIComponent` default). */
+  isPointInside(globalX, globalY) {
+    const local = this.worldToLocal(globalX, globalY);
+    if (!local) return false;
+    return local.x >= 0 && local.x <= this.width && local.y >= 0 && local.y <= this.height;
+  }
+  /** Replace the item set; the pool re-binds and the label count follows. */
+  setItems(items) {
+    this._items = items;
+    if (this._activeId !== null && !items.some((item) => item.id === this._activeId)) {
+      this._activeId = null;
+    }
+    if (this._selectedId !== null && !items.some((item) => item.id === this._selectedId)) {
+      this._selectedId = null;
+    }
+    this._visibleStart = Math.max(0, Math.min(this._visibleStart, Math.max(0, items.length - 1)));
+    this._syncHotspots();
+    this.scene?.markDirty();
+  }
+  /** Move the pool window to start at `start` (the scroll position). */
+  setVisibleStart(start) {
+    const clamped = Math.max(0, Math.min(start, Math.max(0, this._items.length - 1)));
+    if (clamped === this._visibleStart) return;
+    this._visibleStart = clamped;
+    this._syncHotspots();
+    this.scene?.markDirty();
+  }
+  /**
+   * Keep one hotspot per visible slot, positioned over it. The pool is sized
+   * to the viewport (capacity), each slot re-bound to whatever item currently
+   * occupies it — the `Tree._syncHotspots` shape, minus tree structure.
+   */
+  _syncHotspots() {
+    const capacity = this._visibleCapacity ?? Math.max(1, Math.ceil(this.height / this._rowHeight));
+    const need = Math.max(0, Math.min(capacity, this._items.length - this._visibleStart));
+    while (this._hotspots.length < need) {
+      const hotspot = new AggregateItemHotspot(this);
+      this._hotspots.push(hotspot);
+      this.add(hotspot);
+    }
+    while (this._hotspots.length > need) {
+      const hotspot = this._hotspots.pop();
+      this.scene?.detachA11y(hotspot);
+      this.remove(hotspot);
+    }
+    for (let slot = 0; slot < need; slot++) {
+      const index = this._visibleStart + slot;
+      const hotspot = this._hotspots[slot];
+      hotspot.bind(index, this._items[index]);
+      hotspot.x = 0;
+      hotspot.y = slot * this._rowHeight;
+      hotspot.width = this.width;
+      hotspot.height = this._rowHeight;
+    }
+  }
+  /** Whether `id` owns the roving tab stop: active, else selected, else first. */
+  isTabStop(id) {
+    const anchor = (this._activeId !== null && this._items.some((item) => item.id === this._activeId) ? this._activeId : null) ?? (this._selectedId !== null && this._items.some((item) => item.id === this._selectedId) ? this._selectedId : null) ?? this._items[0]?.id;
+    return id === anchor;
+  }
+  isSelected(id) {
+    return this._selectedId === id;
+  }
+  /** Item role the hotspots announce (kept on the parent: one source of truth). */
+  get itemRole() {
+    return this._itemRole;
+  }
+  /** Activate an item (pointer tap-through or Enter/Space): selects and notifies. */
+  activateItem(id, focusIt = false) {
+    const index = this._items.findIndex((item) => item.id === id);
+    if (index === -1) return;
+    this._activeId = id;
+    this._selectedId = id;
+    this._onActivate?.(this._items[index], index);
+    if (focusIt) this.focusItem(id);
+    this.scene?.markDirty();
+  }
+  /** Move keyboard focus to the hotspot currently bound to `id`, if any. */
+  focusItem(id) {
+    this._hotspots.find((hotspot) => hotspot.itemId === id)?.focus();
+  }
+  /**
+   * Aggregate keyboard model: Up/Down move the active item (scrolling the pool
+   * window so it stays bound), Home/End jump, Enter/Space activate. The active
+   * item is focused as it moves so focus is never stranded on a re-bound slot.
+   */
+  handleItemKey(e, id) {
+    const index = this._items.findIndex((item) => item.id === id);
+    if (index === -1) return;
+    let next = -1;
+    switch (e.key) {
+      case "ArrowDown":
+        next = Math.min(index + 1, this._items.length - 1);
+        break;
+      case "ArrowUp":
+        next = Math.max(index - 1, 0);
+        break;
+      case "Home":
+        next = 0;
+        break;
+      case "End":
+        next = this._items.length - 1;
+        break;
+      case "Enter":
+      case " ":
+        e.preventDefault();
+        this.activateItem(id, true);
+        return;
+      default:
+        return;
+    }
+    e.preventDefault();
+    this._activeId = this._items[next].id;
+    this._ensureVisible(next);
+    this.focusItem(this._activeId);
+    this.scene?.markDirty();
+  }
+  /** Scroll the pool window just enough to keep `index` bound. */
+  _ensureVisible(index) {
+    const capacity = this._visibleCapacity ?? Math.max(1, Math.ceil(this.height / this._rowHeight));
+    if (index < this._visibleStart) this.setVisibleStart(index);
+    else if (index >= this._visibleStart + capacity) {
+      this.setVisibleStart(index - capacity + 1);
+    } else {
+      this._syncHotspots();
+    }
+  }
+  update(_dt, _time) {
+    super.update(_dt, _time);
+    this._syncHotspots();
+  }
+};
+var AggregateItemHotspot = class extends Entity {
+  constructor(aggregate) {
+    super();
+    this.aggregate = aggregate;
+    this.interactive = true;
+    this.on("click", () => this.aggregate.activateItem(this.itemId, true));
+    this.on("keydown", (e) => this.aggregate.handleItemKey(e, this.itemId));
+  }
+  aggregate;
+  itemId = "";
+  _index = 0;
+  _label = "";
+  bind(index, item) {
+    this._index = index;
+    this.itemId = item.id;
+    this._label = item.label;
+  }
+  /** The aggregate positions and sizes one pooled hotspot per visible slot. */
+  getLayoutControlledProperties() {
+    return ["x", "y", "width", "height"];
+  }
+  getA11yAttributes() {
+    return {
+      role: this.aggregate.itemRole,
+      label: this._label,
+      // 1-based position within the FULL set, not the pool: without these a
+      // virtualized window announces the pool position as the set position.
+      posInSet: this._index + 1,
+      setSize: this.aggregate.itemCount,
+      selected: this.aggregate.isSelected(this.itemId),
+      // Roving tabindex: only the active item is a tab stop; arrows move within.
+      tabIndex: this.aggregate.isTabStop(this.itemId) ? 0 : -1,
+      // The owner keeps the pointer (canvas handling or an underlying
+      // selectable-text mirror); this hotspot exists for semantics + keyboard
+      // focus, so it opts out of hit-testing. Keyboard focus and
+      // AT-synthesized `click` still work under `pointer-events:none`.
+      pointerEvents: "none"
+    };
+  }
+  render() {
+  }
+  /** Axis-aligned hit-test against the hotspot slot (the `UIComponent` default). */
+  isPointInside(globalX, globalY) {
+    const local = this.worldToLocal(globalX, globalY);
+    if (!local) return false;
+    return local.x >= 0 && local.x <= this.width && local.y >= 0 && local.y <= this.height;
+  }
+};
+
 // src/components/GridTextEntity.ts
 var GridTextEntity = class extends Entity {
   fontSize;
@@ -8728,6 +9562,8 @@ export {
   Circle,
   ComputeParticleEntity,
   DEFAULT_CONTENT_SEMANTIC_BUDGET,
+  DEFAULT_PROJECTION_CAPABILITIES,
+  DEFAULT_SEMANTIC_PROJECTION_POLICY,
   DOMPortalEntity,
   Entity,
   GlyphRasterAtlas,
@@ -8744,6 +9580,8 @@ export {
   PARTICLE_OFFSET_VELOCITY_X,
   PARTICLE_OFFSET_VELOCITY_Y,
   PARTICLE_STRIDE_FLOATS,
+  PROJECTION_AUTO_DOM_BUDGET,
+  PROJECTION_AUTO_HYSTERESIS_FRAMES,
   REDUCED_MOTION_FPS,
   Rect,
   SCENE_OPTION_KEYS,
@@ -8753,14 +9591,20 @@ export {
   SplineEntity,
   TextEntity,
   TextRasterCache,
+  UNKNOWN_PROJECTION_CAPABILITY,
   VECTO_USER_TIMING,
   VectoJSEvent,
+  VirtualizedSetAggregate,
   WebGPUParticleSystemManager,
   beginVectoUserTiming,
   contentLineInHint,
   createWebGLPointRenderer,
+  describeHTMLInCanvasSupport,
   endVectoUserTiming,
+  getSemanticProjectionCapabilities,
+  hysteresisVote,
   installRendererDevTraps,
+  isDeferrableSemanticNode,
   isRendererDevMode,
   isSafeUrl,
   loadSpline,
@@ -8769,6 +9613,8 @@ export {
   ownsKeyboard,
   parseColorToRGBA,
   polySegmentToBezier,
+  resolveProjection,
   sanitizeUrl,
-  setRendererDevMode
+  setRendererDevMode,
+  supportsHTMLInCanvas
 };