@vectojs/core 1.39.0 → 1.40.0

package/README.md

@@ -1,18 +1,12 @@
 # @vectojs/core
 
-> Scene, layout, interaction, text, rendering, and semantic projection for canvas-native interfaces.
-
-[![npm](https://img.shields.io/npm/v/@vectojs/core?color=22d3ee)](https://www.npmjs.com/package/@vectojs/core)
-[![CI](https://github.com/vectojs/vectojs/actions/workflows/ci.yml/badge.svg)](https://github.com/vectojs/vectojs/actions/workflows/ci.yml)
-[![MIT](https://img.shields.io/badge/license-MIT-6366f1.svg)](https://github.com/vectojs/vectojs/blob/main/LICENSE)
-
-`@vectojs/core` is the runtime beneath VectoJS. It owns the retained `Scene`/`Entity` tree, affine
-transforms, render scheduling, layout, text flow, spatial hit-testing, event propagation, renderer
-backends, and the accessibility/automation projection layer.
-
-[Core guide](https://vectojs.org/learn/core-scene/) ·
-[API reference](https://vectojs.org/reference/core-api/) ·
-[Main repository](https://github.com/vectojs/vectojs)
+`@vectojs/core` is the runtime at the root of the VectoJS dependency graph: a retained
+`Scene`/`Entity` scene graph (the Virtual Math Tree) that renders to a single canvas, with
+transforms, render scheduling, spatial hit-testing, DOM-like event propagation, layout and text
+engines, Canvas/SVG/WebGL/WebGPU renderer backends, and the accessibility/automation projection
+layer. It is also the composition point of the framework — it depends on and re-exports
+`@vectojs/layout`, `@vectojs/text`, `@vectojs/math`, and `@vectojs/animation`, so `@vectojs/ui`
+and every higher-level package build directly on it.
 
 ## Install
 
@@ -20,7 +14,7 @@ backends, and the accessibility/automation projection layer.
 bun add @vectojs/core
 ```
 
-## Minimal scene
+## Usage
 
 ```ts
 import { Entity, type IRenderer, Scene } from '@vectojs/core';
@@ -57,124 +51,38 @@ scene.add(new Dot().setPosition(80, 80));
 scene.start();
 ```
 
-## Runtime building blocks
-
-| Area        | Main APIs                                       | Purpose                                                                |
-| ----------- | ----------------------------------------------- | ---------------------------------------------------------------------- |
-| Scene graph | `Scene`, `Entity`                               | ownership, transforms, lifecycle, update/render traversal              |
-| Layout      | `LayoutEngine`, layout subpath                  | prepared text/rich-text layout, wrapping, exclusions, reusable buffers |
-| Interaction | entity events, `SpatialHashGrid`                | hit-testing and DOM-like capture/bubble dispatch                       |
-| Text        | `TextEntity`, `MSDFTextEntity`, `SplineEntity`  | Canvas text, GPU text, and mathematical curves                         |
-| Rendering   | `IRenderer`, `CanvasRenderer`, renderer subpath | backend-neutral drawing contract and concrete renderers                |
-| GPU paths   | WebGL point batching, WebGPU particles          | high-volume points/rects and compute-driven particles                  |
-| Semantics   | `A11yAttributes`, Scene projection              | role/name/state, native inputs, screen readers, Playwright/agents      |
-| Animation   | `animate`, springs, transitions, `Scene.step()` | real-time or deterministic fixed-step motion                           |
-
-## Scene lifecycle
-
-```ts
-const scene = new Scene(canvas, {
-  maxFPS: 60,
-  pointBackend: 'canvas', // or 'webgl'
-  particleBackend: 'cpu', // or 'webgpu' when supported
-});
-scene.renderMode = 'onDemand'; // redraw only when dirty
-
-scene.resize(width, height); // logical CSS pixels
-scene.markDirty();
-scene.start();
-scene.stop();
-scene.step(1000 / 60); // deterministic single step
-scene.destroy(); // release renderers, workers, observers, and semantic DOM
-```
-
-Always call `destroy()` when a framework component unmounts. A `Scene` owns browser observers,
-renderer resources, layout work, and projected DOM nodes.
-
-## Package entry points
-
-```ts
-import { Scene, Entity } from '@vectojs/core';
-import { LayoutEngine } from '@vectojs/core/layout';
-import type { IRenderer } from '@vectojs/core/renderer';
-import { TextEntity } from '@vectojs/core/text';
-```
-
-Both ESM and CommonJS outputs are published with TypeScript declarations.
-
-## Accessibility and automation
-
-Canvas pixels have no semantics. Interactive entities can implement `getA11yAttributes()`; the
-Scene projects transparent DOM nodes over their world-space bounds and forwards native input back
-into the VectoJS event system.
-
-This projection is intentionally thin. Applications still own accessible names, keyboard behavior,
-focus order, contrast, and correct control semantics. See the
-[accessibility guide](https://vectojs.org/learn/accessibility/).
-
-Non-control workspaces that own keyboard shortcuts can opt into focus order
-explicitly: return `{ role: 'region', label: 'Canvas workspace', tabIndex: 0 }`.
-The Scene refreshes the projected `tabindex` when attributes change. Keep native
-text inputs and editable content in charge of their own editing shortcuts.
-
-Interactive projected nodes capture the active pointer on `pointerdown` and route
-`pointermove`, `pointerup`, and `pointercancel` through normal VMT capture/bubble propagation.
-Treat `pointercancel` as rollback: discard transient gesture state and do not create durable
-history. Pointer capture is released safely on both completion paths.
-
-## Static content projection
-
-Canvas-rendered text can opt into browser-native find, translation, selection, and copy without
-turning the application into a DOM layout. Override `getContentProjection()` on the owning Entity;
-the Scene creates a transparent, position-synchronized mirror while the VMT remains authoritative:
-
-```ts
-class SelectableLabel extends Entity {
-  getContentProjection() {
-    return {
-      text: 'Selectable canvas text',
-      font: '18px Inter',
-      lineHeight: 24,
-      selectable: true,
-    };
-  }
-}
-```
-
-`selectable` controls whether the mirror receives pointer input. The Scene keeps projection order
-aligned with VMT order, removes descendant mirrors with their subtree, and hides mirrors fully
-outside the viewport or a `clipChildren` ancestor. Tooling can inspect the currently materialized
-node with `scene.getContentElement(entityId)`. Virtualized or non-materialized off-viewport text is
-not searchable until the application brings it into the active scene.
-
-Code-like renderers can compile their logical source once with `prepareContentGrid()` and return the
-same immutable plan as `ContentProjection.grid`. The plan retains UTF-16 source ranges, legal
-grapheme carets, CR/LF ownership, tab stops, wide CJK/emoji advances, Arabic shaping, and Unicode
-bidi positions. Scene projects those cells in logical source order, performs font calibration in a
-cold offscreen batch, and uses the plan's local geometry for pointer selection even when the entity
-is rotated, scaled, or the page is zoomed.
-
-Selection routing preserves forward/reverse drag direction, Shift extension, word and line
-selection, and exact clipboard source. Projection rebuild/removal/destroy paths release active
-selection and pending calibration ownership before replacing DOM carriers.
-
-## Performance model
-
-Useful levers include on-demand rendering, viewport culling, spatial hashing, prepared text layout,
-typed reusable buffers, batched WebGL points, and optional WebGPU particle compute. None makes every
-workload allocation-free or GPU-bound; profile the renderer and entity types used by your app.
-
-Run the repository benchmarks with `bun run benchmark`, `bun run compare:dom`, and
-`bun run compare`. Prepared-grid scaling can be measured independently with
-`bun run --cwd packages/core benchmark:grid`; benchmark timing is release evidence rather than a
-wall-clock CI gate.
-
-## Related packages
-
-- [`@vectojs/ui`](https://github.com/vectojs/vectojs/tree/main/packages/ui) — high-level accessible components
-- [`@vectojs/three`](https://github.com/vectojs/vectojs/tree/main/packages/three) — Three.js/WebXR projection and raycast routing
-- [`@vectojs/video-exporter`](https://github.com/vectojs/vectojs/tree/main/packages/video-exporter) — deterministic H.264 capture
-
-## License
-
-[MIT](https://github.com/vectojs/vectojs/blob/main/LICENSE) © 2026 Xuepoo
+## Highlights
+
+- Retained `Scene`/`Entity` tree with affine transforms, capture/bubble event dispatch,
+  viewport culling, and dirty-flag `renderMode: 'onDemand'` rendering; `scene.step(dt)` drives a
+  deterministic frame for tests and video export.
+- Backend-neutral `IRenderer` drawing contract with modular backends: `CanvasRenderer`,
+  `SVGRenderer`, batched WebGL points (`WebGLPointRenderer`), and WebGPU particle compute
+  (`WebGPUParticleSystemManager`) — registered on load via `Scene.register*`, selected through
+  `pointBackend` / `particleBackend` options.
+- Optional Rust WASM kernels (`crates/vectojs-core-rs`) hot-swapped per subsystem with
+  `scene.enableWasmTransforms / enableWasmHitTest / enableWasmAnimBatching / enableWasmParticles`;
+  fallible exports return `WASM_STATUS` codes (`OK`/`CAPACITY`/`UNINITIALIZED`/`BAD_RUN`/
+  `OVERFLOW`) so any rejected batch degrades to the JS path instead of rendering half-written state.
+- Semantic accessibility projection: entities implementing `getA11yAttributes()` get transparent,
+  position-synchronized DOM mirrors for screen readers, keyboard users, Playwright, and AI agents;
+  static text opts into browser-native selection/find/copy through `getContentProjection()` and
+  Core's prepared content grid (`prepareContentGrid()`).
+- Entity-based text renderers stay here because they extend `Entity`: `TextEntity`,
+  `GridTextEntity`, GPU-resolved `MSDFTextEntity` (off-thread layout via `LayoutWorkerManager`),
+  `SVGEntity`, and `DOMPortalEntity`.
+- The standalone engines are re-exported from this barrel and remain available as subpaths, so
+  existing imports keep working:
+  `@vectojs/core/layout`, `@vectojs/core/text`, `@vectojs/core/renderer`.
+- Lifecycle ownership is explicit: a `Scene` owns renderers, workers, observers, and projected DOM
+  nodes; `scene.destroy()` releases all of them.
+
+> Documents @vectojs/core@1.39.0.
+
+## Documentation
+
+- [Core Scene architecture](https://vectojs.org/learn/core-scene/)
+- [`@vectojs/core` API reference](https://vectojs.org/reference/core-api/)
+- [`Entity` reference](https://vectojs.org/reference/core-entity/)
+- [Renderers reference](https://vectojs.org/reference/core-renderer/)
+- [Accessibility & automation guide](https://vectojs.org/learn/accessibility/)

package/dist/{chunk-RUM2KEDI.mjs → chunk-AISSDI6U.mjs}

@@ -63,7 +63,8 @@ function emptyDrawCounters() {
 }
 var TWO_PI = Math.PI * 2;
 function getDevicePixelRatio() {
-  return typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1;
+  const raw = typeof window !== "undefined" ? window.devicePixelRatio : 1;
+  return Number.isFinite(raw) && raw > 0 ? raw : 1;
 }
 var CanvasRenderer = class _CanvasRenderer {
   ctx;
@@ -209,7 +210,9 @@ var CanvasRenderer = class _CanvasRenderer {
   /** Real `devicePixelRatio`, clamped to {@link maxDPR} when set. */
   effectiveDPR() {
     const real = getDevicePixelRatio();
-    return this.maxDPR !== void 0 ? Math.min(real, this.maxDPR) : real;
+    if (this.maxDPR === void 0) return real;
+    if (!Number.isFinite(this.maxDPR) || this.maxDPR <= 0) return real;
+    return Math.min(real, this.maxDPR);
   }
   /**
    * @inheritdoc
@@ -240,14 +243,18 @@ var CanvasRenderer = class _CanvasRenderer {
    */
   resize(width, height) {
     const dpr = this.effectiveDPR();
+    const safeWidth = Number.isFinite(width) && width >= 0 ? width : this.width;
+    const safeHeight = Number.isFinite(height) && height >= 0 ? height : this.height;
+    const backingW = Number.isFinite(safeWidth * dpr) ? Math.max(1, Math.round(safeWidth * dpr)) : 1;
+    const backingH = Number.isFinite(safeHeight * dpr) ? Math.max(1, Math.round(safeHeight * dpr)) : 1;
     this.appliedDPR = dpr;
-    this.width = width;
-    this.height = height;
-    this.ctx.canvas.width = width * dpr;
-    this.ctx.canvas.height = height * dpr;
+    this.width = safeWidth;
+    this.height = safeHeight;
+    this.ctx.canvas.width = backingW;
+    this.ctx.canvas.height = backingH;
     if (this.ctx.canvas.style) {
-      this.ctx.canvas.style.width = `${width}px`;
-      this.ctx.canvas.style.height = `${height}px`;
+      this.ctx.canvas.style.width = `${safeWidth}px`;
+      this.ctx.canvas.style.height = `${safeHeight}px`;
     }
     this.ctx.scale(dpr, dpr);
     this._cachedFont = "";

package/dist/{chunk-KRUDTGNR.js → chunk-BKXERWAD.js}

@@ -65,7 +65,8 @@ function emptyDrawCounters() {
 }
 var TWO_PI = Math.PI * 2;
 function getDevicePixelRatio() {
-  return typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1;
+  const raw = typeof window !== "undefined" ? window.devicePixelRatio : 1;
+  return Number.isFinite(raw) && raw > 0 ? raw : 1;
 }
 var CanvasRenderer = (_class = class _CanvasRenderer {
   
@@ -211,7 +212,9 @@ var CanvasRenderer = (_class = class _CanvasRenderer {
   /** Real `devicePixelRatio`, clamped to {@link maxDPR} when set. */
   effectiveDPR() {
     const real = getDevicePixelRatio();
-    return this.maxDPR !== void 0 ? Math.min(real, this.maxDPR) : real;
+    if (this.maxDPR === void 0) return real;
+    if (!Number.isFinite(this.maxDPR) || this.maxDPR <= 0) return real;
+    return Math.min(real, this.maxDPR);
   }
   /**
    * @inheritdoc
@@ -242,14 +245,18 @@ var CanvasRenderer = (_class = class _CanvasRenderer {
    */
   resize(width, height) {
     const dpr = this.effectiveDPR();
+    const safeWidth = Number.isFinite(width) && width >= 0 ? width : this.width;
+    const safeHeight = Number.isFinite(height) && height >= 0 ? height : this.height;
+    const backingW = Number.isFinite(safeWidth * dpr) ? Math.max(1, Math.round(safeWidth * dpr)) : 1;
+    const backingH = Number.isFinite(safeHeight * dpr) ? Math.max(1, Math.round(safeHeight * dpr)) : 1;
     this.appliedDPR = dpr;
-    this.width = width;
-    this.height = height;
-    this.ctx.canvas.width = width * dpr;
-    this.ctx.canvas.height = height * dpr;
+    this.width = safeWidth;
+    this.height = safeHeight;
+    this.ctx.canvas.width = backingW;
+    this.ctx.canvas.height = backingH;
     if (this.ctx.canvas.style) {
-      this.ctx.canvas.style.width = `${width}px`;
-      this.ctx.canvas.style.height = `${height}px`;
+      this.ctx.canvas.style.width = `${safeWidth}px`;
+      this.ctx.canvas.style.height = `${safeHeight}px`;
     }
     this.ctx.scale(dpr, dpr);
     this._cachedFont = "";

package/dist/{chunk-7PYD5UDX.mjs → chunk-CIRZ3S2Z.mjs}

@@ -27,16 +27,22 @@ var VectoJSEvent = class {
   nativeEvent;
   /** Whether the event bubbles past its target (capture always runs). */
   bubbles;
+  /**
+   * Which transport delivered this event ({@link VectoEventSource}).
+   * `undefined` for unattributed legacy/synthetic dispatches.
+   */
+  source;
   explicitScenePoint;
   stopped = false;
   stoppedImmediate = false;
-  constructor(type, target, nativeEvent, bubbles = true, scenePoint) {
+  constructor(type, target, nativeEvent, bubbles = true, scenePoint, source) {
     this.type = type;
     this.target = target;
     this.currentTarget = target;
     this.nativeEvent = nativeEvent;
     this.bubbles = bubbles;
     this.explicitScenePoint = scenePoint;
+    this.source = source;
   }
   /** Stop the event from reaching the next node in the propagation path. */
   stopPropagation() {
@@ -330,6 +336,41 @@ var Entity = class {
    * faint-but-live control.
    */
   a11yHidden = false;
+  /**
+   * 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";
+  /**
+   * 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 = "";
+  /**
+   * 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 = false;
   /**
    * Clip this node's children to its local box (`[0,0]–[width,height]`) while
    * rendering. Combined with translating a content child, this is how
@@ -631,8 +672,7 @@ var Entity = class {
         (e) => new Promise((resolve) => {
           this._spawnDriver(e[0], e[1], cfg);
           const d = this._drivers?.get(e[0]);
-          if (!d)
-            resolve();
+          if (!d) resolve();
           else d.onDone = resolve;
         })
       )
@@ -822,6 +862,7 @@ var Entity = class {
       el.focus();
       return;
     }
+    if (typeof requestAnimationFrame === "undefined") return;
     requestAnimationFrame(() => {
       const retry = this.scene?.getA11yElement(this.id);
       if (retry) retry.focus();
@@ -1188,6 +1229,10 @@ var Entity = class {
    * `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/{chunk-POPXUPKR.js → chunk-HC5EZOZJ.js}

@@ -29,16 +29,22 @@ var VectoJSEvent = (_class = class {
   
   /** Whether the event bubbles past its target (capture always runs). */
   
+  /**
+   * Which transport delivered this event ({@link VectoEventSource}).
+   * `undefined` for unattributed legacy/synthetic dispatches.
+   */
+  
   
   __init() {this.stopped = false}
   __init2() {this.stoppedImmediate = false}
-  constructor(type, target, nativeEvent, bubbles = true, scenePoint) {;_class.prototype.__init.call(this);_class.prototype.__init2.call(this);
+  constructor(type, target, nativeEvent, bubbles = true, scenePoint, source) {;_class.prototype.__init.call(this);_class.prototype.__init2.call(this);
     this.type = type;
     this.target = target;
     this.currentTarget = target;
     this.nativeEvent = nativeEvent;
     this.bubbles = bubbles;
     this.explicitScenePoint = scenePoint;
+    this.source = source;
   }
   /** Stop the event from reaching the next node in the propagation path. */
   stopPropagation() {
@@ -332,13 +338,48 @@ var Entity = (_class2 = class {
    * faint-but-live control.
    */
   __init36() {this.a11yHidden = false}
+  /**
+   * 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).
+   */
+  __init37() {this.domPolicy = "canvas"}
+  /**
+   * 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.
+   */
+  __init38() {this.domKind = ""}
+  /**
+   * 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.
+   */
+  __init39() {this.domResident = false}
   /**
    * Clip this node's children to its local box (`[0,0]–[width,height]`) while
    * rendering. Combined with translating a content child, this is how
    * scroll/overflow containers (e.g. `ScrollView`) keep their content inside a
    * fixed viewport. Off by default (children render unclipped). Canvas2D only.
    */
-  __init37() {this.clipChildren = false}
+  __init40() {this.clipChildren = false}
   /**
    * Group this subtree's projected text into its own accessibility **region**,
    * without clipping anything.
@@ -365,14 +406,14 @@ var Entity = (_class2 = class {
    *
    * Off by default. Regions nest: the nearest enclosing region wins.
    */
-  __init38() {this.a11yRegion = false}
+  __init41() {this.a11yRegion = false}
   // Lazily allocated (see _drivers above). Most entities never register a
   // listener or an imperative animate() tween.
-  __init39() {this.listeners = null}
+  __init42() {this.listeners = null}
   /** Capture-phase listeners (fired root→target before bubble). */
-  __init40() {this.captureListeners = null}
-  __init41() {this.animations = null}
-  constructor(id) {;_class2.prototype.__init3.call(this);_class2.prototype.__init4.call(this);_class2.prototype.__init5.call(this);_class2.prototype.__init6.call(this);_class2.prototype.__init7.call(this);_class2.prototype.__init8.call(this);_class2.prototype.__init9.call(this);_class2.prototype.__init10.call(this);_class2.prototype.__init11.call(this);_class2.prototype.__init12.call(this);_class2.prototype.__init13.call(this);_class2.prototype.__init14.call(this);_class2.prototype.__init15.call(this);_class2.prototype.__init16.call(this);_class2.prototype.__init17.call(this);_class2.prototype.__init18.call(this);_class2.prototype.__init19.call(this);_class2.prototype.__init20.call(this);_class2.prototype.__init21.call(this);_class2.prototype.__init22.call(this);_class2.prototype.__init23.call(this);_class2.prototype.__init24.call(this);_class2.prototype.__init25.call(this);_class2.prototype.__init26.call(this);_class2.prototype.__init27.call(this);_class2.prototype.__init28.call(this);_class2.prototype.__init29.call(this);_class2.prototype.__init30.call(this);_class2.prototype.__init31.call(this);_class2.prototype.__init32.call(this);_class2.prototype.__init33.call(this);_class2.prototype.__init34.call(this);_class2.prototype.__init35.call(this);_class2.prototype.__init36.call(this);_class2.prototype.__init37.call(this);_class2.prototype.__init38.call(this);_class2.prototype.__init39.call(this);_class2.prototype.__init40.call(this);_class2.prototype.__init41.call(this);
+  __init43() {this.captureListeners = null}
+  __init44() {this.animations = null}
+  constructor(id) {;_class2.prototype.__init3.call(this);_class2.prototype.__init4.call(this);_class2.prototype.__init5.call(this);_class2.prototype.__init6.call(this);_class2.prototype.__init7.call(this);_class2.prototype.__init8.call(this);_class2.prototype.__init9.call(this);_class2.prototype.__init10.call(this);_class2.prototype.__init11.call(this);_class2.prototype.__init12.call(this);_class2.prototype.__init13.call(this);_class2.prototype.__init14.call(this);_class2.prototype.__init15.call(this);_class2.prototype.__init16.call(this);_class2.prototype.__init17.call(this);_class2.prototype.__init18.call(this);_class2.prototype.__init19.call(this);_class2.prototype.__init20.call(this);_class2.prototype.__init21.call(this);_class2.prototype.__init22.call(this);_class2.prototype.__init23.call(this);_class2.prototype.__init24.call(this);_class2.prototype.__init25.call(this);_class2.prototype.__init26.call(this);_class2.prototype.__init27.call(this);_class2.prototype.__init28.call(this);_class2.prototype.__init29.call(this);_class2.prototype.__init30.call(this);_class2.prototype.__init31.call(this);_class2.prototype.__init32.call(this);_class2.prototype.__init33.call(this);_class2.prototype.__init34.call(this);_class2.prototype.__init35.call(this);_class2.prototype.__init36.call(this);_class2.prototype.__init37.call(this);_class2.prototype.__init38.call(this);_class2.prototype.__init39.call(this);_class2.prototype.__init40.call(this);_class2.prototype.__init41.call(this);_class2.prototype.__init42.call(this);_class2.prototype.__init43.call(this);_class2.prototype.__init44.call(this);
     this.id = id || `entity_${Math.random().toString(36).substring(2, 9)}`;
   }
   /**
@@ -633,8 +674,7 @@ var Entity = (_class2 = class {
         (e) => new Promise((resolve) => {
           this._spawnDriver(e[0], e[1], cfg);
           const d = _optionalChain([this, 'access', _84 => _84._drivers, 'optionalAccess', _85 => _85.get, 'call', _86 => _86(e[0])]);
-          if (!d)
-            resolve();
+          if (!d) resolve();
           else d.onDone = resolve;
         })
       )
@@ -824,6 +864,7 @@ var Entity = (_class2 = class {
       el.focus();
       return;
     }
+    if (typeof requestAnimationFrame === "undefined") return;
     requestAnimationFrame(() => {
       const retry = _optionalChain([this, 'access', _109 => _109.scene, 'optionalAccess', _110 => _110.getA11yElement, 'call', _111 => _111(this.id)]);
       if (retry) retry.focus();
@@ -1190,6 +1231,10 @@ var Entity = (_class2 = class {
    * `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
@@ -1267,27 +1312,27 @@ var MSDFTextEntity = (_class3 = class extends Entity {
   // joined by soft hyphens (U+00AD); the worker then treats those as break
   // opportunities. `text` keeps the original string for a11y/content
   // projection; `layoutText` is the soft-hyphen-annotated string sent to layout.
-  __init42() {this.hyphenator = null}
-  __init43() {this.layoutText = ""}
-  __init44() {this.text = ""}
-  __init45() {this.lastRenderedSeqId = 0}
+  __init45() {this.hyphenator = null}
+  __init46() {this.layoutText = ""}
+  __init47() {this.text = ""}
+  __init48() {this.lastRenderedSeqId = 0}
   /** Bumped by {@link queueLayout}; read by `Scene` to skip an unchanged sync. */
-  __init46() {this.contentEpoch = 0}
+  __init49() {this.contentEpoch = 0}
   // Atlas-decode subscription (see watchAtlasDecode). Held so `destroy()` can
   // release it: the handler closes over `this`, so leaving it attached to a
   // long-lived shared atlas image would retain the whole entity.
-  __init47() {this.atlasDecodeTarget = null}
-  __init48() {this.atlasDecodeHandler = null}
-  __init49() {this.fontStringCache = []}
-  __init50() {this.layoutResult = null}
+  __init50() {this.atlasDecodeTarget = null}
+  __init51() {this.atlasDecodeHandler = null}
+  __init52() {this.fontStringCache = []}
+  __init53() {this.layoutResult = null}
   /**
    * Visual rows rebuilt from {@link layoutResult} (see
    * {@link rebuildProjectionLines}). Empty until a layout reply lands and the
    * reply's shaped glyphs can be mapped back to the source text 1:1.
    */
-  __init51() {this.projectionLines = []}
+  __init54() {this.projectionLines = []}
   constructor(text, options) {
-    super();_class3.prototype.__init42.call(this);_class3.prototype.__init43.call(this);_class3.prototype.__init44.call(this);_class3.prototype.__init45.call(this);_class3.prototype.__init46.call(this);_class3.prototype.__init47.call(this);_class3.prototype.__init48.call(this);_class3.prototype.__init49.call(this);_class3.prototype.__init50.call(this);_class3.prototype.__init51.call(this);;
+    super();_class3.prototype.__init45.call(this);_class3.prototype.__init46.call(this);_class3.prototype.__init47.call(this);_class3.prototype.__init48.call(this);_class3.prototype.__init49.call(this);_class3.prototype.__init50.call(this);_class3.prototype.__init51.call(this);_class3.prototype.__init52.call(this);_class3.prototype.__init53.call(this);_class3.prototype.__init54.call(this);;
     this.font = options.font;
     this.texture = options.texture;
     this.fallbackFont = _nullishCoalesce(options.fallbackFont, () => ( "sans-serif"));
@@ -1671,23 +1716,23 @@ var SVGEntity = (_class4 = class extends Entity {
    * rasterized. Set to `'transparent'` to opt out and keep the box empty.
    * Default `'rgba(248,113,113,0.9)'`.
    */
-  __init52() {this.fallbackStroke = "rgba(248,113,113,0.9)"}
+  __init55() {this.fallbackStroke = "rgba(248,113,113,0.9)"}
   /** Fill behind the fallback marker. Default `'rgba(248,113,113,0.12)'`. */
-  __init53() {this.fallbackFill = "rgba(248,113,113,0.12)"}
-  __init54() {this.svgSource = ""}
-  __init55() {this.imageBitmap = null}
-  __init56() {this.imageElement = null}
-  __init57() {this.blobURL = null}
-  __init58() {this.currentImg = null}
-  __init59() {this.lodTimeout = null}
-  __init60() {this.rasterFailed = false}
-  __init61() {this.cachedDoc = null}
-  __init62() {this.baseWidth = 100}
-  __init63() {this.baseHeight = 100}
-  __init64() {this.lastRasterizedScale = 1}
-  __init65() {this.targetScale = 1}
+  __init56() {this.fallbackFill = "rgba(248,113,113,0.12)"}
+  __init57() {this.svgSource = ""}
+  __init58() {this.imageBitmap = null}
+  __init59() {this.imageElement = null}
+  __init60() {this.blobURL = null}
+  __init61() {this.currentImg = null}
+  __init62() {this.lodTimeout = null}
+  __init63() {this.rasterFailed = false}
+  __init64() {this.cachedDoc = null}
+  __init65() {this.baseWidth = 100}
+  __init66() {this.baseHeight = 100}
+  __init67() {this.lastRasterizedScale = 1}
+  __init68() {this.targetScale = 1}
   constructor(svgSource, id) {
-    super(id);_class4.prototype.__init52.call(this);_class4.prototype.__init53.call(this);_class4.prototype.__init54.call(this);_class4.prototype.__init55.call(this);_class4.prototype.__init56.call(this);_class4.prototype.__init57.call(this);_class4.prototype.__init58.call(this);_class4.prototype.__init59.call(this);_class4.prototype.__init60.call(this);_class4.prototype.__init61.call(this);_class4.prototype.__init62.call(this);_class4.prototype.__init63.call(this);_class4.prototype.__init64.call(this);_class4.prototype.__init65.call(this);;
+    super(id);_class4.prototype.__init55.call(this);_class4.prototype.__init56.call(this);_class4.prototype.__init57.call(this);_class4.prototype.__init58.call(this);_class4.prototype.__init59.call(this);_class4.prototype.__init60.call(this);_class4.prototype.__init61.call(this);_class4.prototype.__init62.call(this);_class4.prototype.__init63.call(this);_class4.prototype.__init64.call(this);_class4.prototype.__init65.call(this);_class4.prototype.__init66.call(this);_class4.prototype.__init67.call(this);_class4.prototype.__init68.call(this);;
     this.setSVGSource(svgSource);
   }
   setSVGSource(svgSource) {