@vectojs/core 1.29.0 → 1.31.0

package/dist/{chunk-Z3HFY75R.js → chunk-TRT2TRCW.js}

@@ -14,6 +14,10 @@ var ANIMATABLE_PROPS = /* @__PURE__ */ new Set([
   "rotation",
   "opacity"
 ]);
+function contentLineInHint(hint, y, height) {
+  if (_optionalChain([hint, 'optionalAccess', _ => _.minY]) === void 0 || hint.maxY === void 0) return true;
+  return y + height >= hint.minY && y <= hint.maxY;
+}
 var VectoJSEvent = (_class = class {
   /** The event name. */
   
@@ -47,7 +51,7 @@ var VectoJSEvent = (_class = class {
   }
   /** Forward to the native event's `preventDefault` (e.g. stop page scroll). */
   preventDefault() {
-    _optionalChain([this, 'access', _ => _.nativeEvent, 'optionalAccess', _2 => _2.preventDefault, 'optionalCall', _3 => _3()]);
+    _optionalChain([this, 'access', _2 => _2.nativeEvent, 'optionalAccess', _3 => _3.preventDefault, 'optionalCall', _4 => _4()]);
   }
   /** Whether {@link stopPropagation} has been called. */
   get propagationStopped() {
@@ -59,72 +63,72 @@ var VectoJSEvent = (_class = class {
   }
   /** Whether the native event's default action was prevented. */
   get defaultPrevented() {
-    return !!_optionalChain([this, 'access', _4 => _4.nativeEvent, 'optionalAccess', _5 => _5.defaultPrevented]);
+    return !!_optionalChain([this, 'access', _5 => _5.nativeEvent, 'optionalAccess', _6 => _6.defaultPrevented]);
   }
   /** Native horizontal wheel delta, if this wraps a `WheelEvent`. */
   get deltaX() {
-    return _optionalChain([this, 'access', _6 => _6.nativeEvent, 'optionalAccess', _7 => _7.deltaX]);
+    return _optionalChain([this, 'access', _7 => _7.nativeEvent, 'optionalAccess', _8 => _8.deltaX]);
   }
   /** Native vertical wheel delta, if this wraps a `WheelEvent`. */
   get deltaY() {
-    return _optionalChain([this, 'access', _8 => _8.nativeEvent, 'optionalAccess', _9 => _9.deltaY]);
+    return _optionalChain([this, 'access', _9 => _9.nativeEvent, 'optionalAccess', _10 => _10.deltaY]);
   }
   /** Native pointer X, if this wraps a pointer/mouse event. */
   get clientX() {
-    return _optionalChain([this, 'access', _10 => _10.nativeEvent, 'optionalAccess', _11 => _11.clientX]);
+    return _optionalChain([this, 'access', _11 => _11.nativeEvent, 'optionalAccess', _12 => _12.clientX]);
   }
   /** Native pointer Y, if this wraps a pointer/mouse event. */
   get clientY() {
-    return _optionalChain([this, 'access', _12 => _12.nativeEvent, 'optionalAccess', _13 => _13.clientY]);
+    return _optionalChain([this, 'access', _13 => _13.nativeEvent, 'optionalAccess', _14 => _14.clientY]);
   }
   get resolvedScenePoint() {
     if (this.explicitScenePoint) return this.explicitScenePoint;
     const native = this.nativeEvent;
-    if (_optionalChain([native, 'optionalAccess', _14 => _14.vectoSceneX]) !== void 0 && native.vectoSceneY !== void 0) {
+    if (_optionalChain([native, 'optionalAccess', _15 => _15.vectoSceneX]) !== void 0 && native.vectoSceneY !== void 0) {
       return { x: native.vectoSceneX, y: native.vectoSceneY };
     }
-    if (_optionalChain([native, 'optionalAccess', _15 => _15.clientX]) === void 0 || native.clientY === void 0) return void 0;
+    if (_optionalChain([native, 'optionalAccess', _16 => _16.clientX]) === void 0 || native.clientY === void 0) return void 0;
     const scene = this.target.scene;
-    return _nullishCoalesce(_optionalChain([scene, 'optionalAccess', _16 => _16.clientToScene, 'optionalCall', _17 => _17(native.clientX, native.clientY)]), () => ( {
+    return _nullishCoalesce(_optionalChain([scene, 'optionalAccess', _17 => _17.clientToScene, 'optionalCall', _18 => _18(native.clientX, native.clientY)]), () => ( {
       x: native.clientX,
       y: native.clientY
     }));
   }
   /** Pointer X in the Scene's logical coordinate space. */
   get sceneX() {
-    return _optionalChain([this, 'access', _18 => _18.resolvedScenePoint, 'optionalAccess', _19 => _19.x]);
+    return _optionalChain([this, 'access', _19 => _19.resolvedScenePoint, 'optionalAccess', _20 => _20.x]);
   }
   /** Pointer Y in the Scene's logical coordinate space. */
   get sceneY() {
-    return _optionalChain([this, 'access', _20 => _20.resolvedScenePoint, 'optionalAccess', _21 => _21.y]);
+    return _optionalChain([this, 'access', _21 => _21.resolvedScenePoint, 'optionalAccess', _22 => _22.y]);
   }
   /** Pointer X local to the entity whose listener is currently running. */
   get localX() {
     const point = this.resolvedScenePoint;
     if (!point) return void 0;
-    return _optionalChain([this, 'access', _22 => _22.currentTarget, 'access', _23 => _23.worldToLocal, 'call', _24 => _24(point.x, point.y), 'optionalAccess', _25 => _25.x]);
+    return _optionalChain([this, 'access', _23 => _23.currentTarget, 'access', _24 => _24.worldToLocal, 'call', _25 => _25(point.x, point.y), 'optionalAccess', _26 => _26.x]);
   }
   /** Pointer Y local to the entity whose listener is currently running. */
   get localY() {
     const point = this.resolvedScenePoint;
     if (!point) return void 0;
-    return _optionalChain([this, 'access', _26 => _26.currentTarget, 'access', _27 => _27.worldToLocal, 'call', _28 => _28(point.x, point.y), 'optionalAccess', _29 => _29.y]);
+    return _optionalChain([this, 'access', _27 => _27.currentTarget, 'access', _28 => _28.worldToLocal, 'call', _29 => _29(point.x, point.y), 'optionalAccess', _30 => _30.y]);
   }
   get shiftKey() {
-    return !!_optionalChain([this, 'access', _30 => _30.nativeEvent, 'optionalAccess', _31 => _31.shiftKey]);
+    return !!_optionalChain([this, 'access', _31 => _31.nativeEvent, 'optionalAccess', _32 => _32.shiftKey]);
   }
   get ctrlKey() {
-    return !!_optionalChain([this, 'access', _32 => _32.nativeEvent, 'optionalAccess', _33 => _33.ctrlKey]);
+    return !!_optionalChain([this, 'access', _33 => _33.nativeEvent, 'optionalAccess', _34 => _34.ctrlKey]);
   }
   get altKey() {
-    return !!_optionalChain([this, 'access', _34 => _34.nativeEvent, 'optionalAccess', _35 => _35.altKey]);
+    return !!_optionalChain([this, 'access', _35 => _35.nativeEvent, 'optionalAccess', _36 => _36.altKey]);
   }
   get metaKey() {
-    return !!_optionalChain([this, 'access', _36 => _36.nativeEvent, 'optionalAccess', _37 => _37.metaKey]);
+    return !!_optionalChain([this, 'access', _37 => _37.nativeEvent, 'optionalAccess', _38 => _38.metaKey]);
   }
   /** Native key, if this wraps a keyboard event. */
   get key() {
-    return _optionalChain([this, 'access', _38 => _38.nativeEvent, 'optionalAccess', _39 => _39.key]);
+    return _optionalChain([this, 'access', _39 => _39.nativeEvent, 'optionalAccess', _40 => _40.key]);
   }
 }, _class);
 var Entity = (_class2 = class {
@@ -253,6 +257,42 @@ var Entity = (_class2 = class {
    * nodes, so on-top components stay clickable.
    */
   __init33() {this.a11yFullViewport = false}
+  /**
+   * When this entity's a11y shadow node is materialized.
+   *
+   * `'eager'` (the default) keeps today's behaviour: a shadow node exists for as
+   * long as the entity is `interactive` with a box. That is right for a button or
+   * a link, and wrong for thousands of ephemeral, individually-meaningless
+   * entities — particles, danmaku, graph nodes — where it produces one DOM node
+   * per entity every frame.
+   *
+   * Measured on 5,000 moving interactive entities (`benchmarks/lazy-a11y/`):
+   * eager costs **72.2 ms/frame on Chrome and 114.3 ms on Firefox**, missing even
+   * 60 Hz, against **1.55/1.63 ms** for the same scene with one node projected —
+   * within noise of the 1.26/1.65 ms floor of projecting nothing at all.
+   *
+   * `'onDemand'` projects a node only while {@link Scene} considers the entity
+   * *engaged*: it is focused, it is the current pointer target, or it has been
+   * explicitly requested via {@link Scene.requestA11yProjection}. Crucially the
+   * trigger is not hover alone — a keyboard or assistive-technology user
+   * generates no hover, so a hover-only gate would remove exactly those users'
+   * access. Engagement therefore includes focus and an explicit request, and the
+   * entity stays hit-testable on canvas throughout, so a click still reaches it
+   * and promotes it.
+   *
+   * `'never'` suppresses the node entirely. Prefer `interactive = false` unless
+   * the entity genuinely needs pointer events without any semantic presence;
+   * this exists so a purely decorative interactive surface can opt out without
+   * losing canvas hit-testing.
+   *
+   * **This does not replace an aggregate description.** A thousand `'onDemand'`
+   * danmaku are individually reachable but say nothing collectively. The proven
+   * pattern is one aggregate live region (`role: 'status'`, `a11yFullViewport`)
+   * plus a small pool of persistent hotspots for the current selection — see
+   * `vectojs-native/danmaku`. Use `'onDemand'` to stop paying per entity, not as
+   * the whole accessibility story.
+   */
+  __init34() {this.a11yProjection = "eager"}
   /**
    * Hide this entity AND its whole subtree from the accessibility/automation
    * projection, regardless of each node's own `interactive` flag.
@@ -270,21 +310,21 @@ var Entity = (_class2 = class {
    * `=== 0` test never fires; a threshold would instead silently un-project a
    * faint-but-live control.
    */
-  __init34() {this.a11yHidden = false}
+  __init35() {this.a11yHidden = 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.
    */
-  __init35() {this.clipChildren = false}
+  __init36() {this.clipChildren = false}
   // Lazily allocated (see _drivers above). Most entities never register a
   // listener or an imperative animate() tween.
-  __init36() {this.listeners = null}
+  __init37() {this.listeners = null}
   /** Capture-phase listeners (fired root→target before bubble). */
-  __init37() {this.captureListeners = null}
-  __init38() {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);
+  __init38() {this.captureListeners = null}
+  __init39() {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);
     this.id = id || `entity_${Math.random().toString(36).substring(2, 9)}`;
   }
   /**
@@ -318,7 +358,7 @@ var Entity = (_class2 = class {
     const s = this.scene;
     if (s) {
       s.a11yNeedsReorder = true;
-      _optionalChain([s, 'access', _40 => _40.markStructureChanged, 'optionalCall', _41 => _41()]);
+      _optionalChain([s, 'access', _41 => _41.markStructureChanged, 'optionalCall', _42 => _42()]);
       s.markDirty({ entity: this.id, reason: "child-added" });
       child._notifyMounted();
     }
@@ -348,7 +388,7 @@ var Entity = (_class2 = class {
       if (s) {
         s.detachA11y(child);
         s.a11yNeedsReorder = true;
-        _optionalChain([s, 'access', _42 => _42.markStructureChanged, 'optionalCall', _43 => _43()]);
+        _optionalChain([s, 'access', _43 => _43.markStructureChanged, 'optionalCall', _44 => _44()]);
         s.markDirty({ entity: this.id, reason: "child-removed" });
       }
     }
@@ -403,7 +443,7 @@ var Entity = (_class2 = class {
       startTime: -1,
       startProps: {}
     });
-    _optionalChain([this, 'access', _44 => _44.scene, 'optionalAccess', _45 => _45.markDirty, 'call', _46 => _46({ entity: this.id, reason: "animation-start" })]);
+    _optionalChain([this, 'access', _45 => _45.scene, 'optionalAccess', _46 => _46.markDirty, 'call', _47 => _47({ entity: this.id, reason: "animation-start" })]);
     return this;
   }
   /** Write a driver-computed value to a backing field without re-triggering the setter. */
@@ -450,26 +490,26 @@ var Entity = (_class2 = class {
    * that need to seed a starting state (e.g. the presence helper's enter `from`).
    */
   setImmediate(prop, v) {
-    const existing = _optionalChain([this, 'access', _47 => _47._drivers, 'optionalAccess', _48 => _48.get, 'call', _49 => _49(prop)]);
+    const existing = _optionalChain([this, 'access', _48 => _48._drivers, 'optionalAccess', _49 => _49.get, 'call', _50 => _50(prop)]);
     if (existing) this._settleDriver(existing);
-    _optionalChain([this, 'access', _50 => _50._drivers, 'optionalAccess', _51 => _51.delete, 'call', _52 => _52(prop)]);
+    _optionalChain([this, 'access', _51 => _51._drivers, 'optionalAccess', _52 => _52.delete, 'call', _53 => _53(prop)]);
     this._applyAnimated(prop, v);
   }
   _settleDriver(driver) {
     const active = driver;
     const onDone = active.onDone;
     active.onDone = void 0;
-    _optionalChain([onDone, 'optionalCall', _53 => _53()]);
+    _optionalChain([onDone, 'optionalCall', _54 => _54()]);
   }
   _spawnDriver(prop, to, cfg) {
-    if (prop !== "opacity" && _optionalChain([this, 'access', _54 => _54.scene, 'optionalAccess', _55 => _55.prefersReducedMotion])) {
-      const existing2 = _optionalChain([this, 'access', _56 => _56._drivers, 'optionalAccess', _57 => _57.get, 'call', _58 => _58(prop)]);
+    if (prop !== "opacity" && _optionalChain([this, 'access', _55 => _55.scene, 'optionalAccess', _56 => _56.prefersReducedMotion])) {
+      const existing2 = _optionalChain([this, 'access', _57 => _57._drivers, 'optionalAccess', _58 => _58.get, 'call', _59 => _59(prop)]);
       if (existing2) this._settleDriver(existing2);
-      _optionalChain([this, 'access', _59 => _59._drivers, 'optionalAccess', _60 => _60.delete, 'call', _61 => _61(prop)]);
+      _optionalChain([this, 'access', _60 => _60._drivers, 'optionalAccess', _61 => _61.delete, 'call', _62 => _62(prop)]);
       this._applyAnimated(prop, to);
       return;
     }
-    const existing = _optionalChain([this, 'access', _62 => _62._drivers, 'optionalAccess', _63 => _63.get, 'call', _64 => _64(prop)]);
+    const existing = _optionalChain([this, 'access', _63 => _63._drivers, 'optionalAccess', _64 => _64.get, 'call', _65 => _65(prop)]);
     if (existing) {
       this._settleDriver(existing);
       existing.retarget(to);
@@ -478,12 +518,12 @@ var Entity = (_class2 = class {
     const from = this._currentOf(prop);
     const driver = _animation.isTweenConfig.call(void 0, cfg) ? new (0, _animation.TweenDriver)(from, to, cfg) : new (0, _animation.SpringDriver)(from, to, cfg === "spring" ? {} : cfg);
     (this._drivers ??= /* @__PURE__ */ new Map()).set(prop, driver);
-    _optionalChain([this, 'access', _65 => _65.scene, 'optionalAccess', _66 => _66.markDirty, 'call', _67 => _67({ entity: this.id, reason: "driver-added" })]);
-    _optionalChain([this, 'access', _68 => _68.scene, 'optionalAccess', _69 => _69._registerActiveDriverEntity, 'call', _70 => _70(this)]);
+    _optionalChain([this, 'access', _66 => _66.scene, 'optionalAccess', _67 => _67.markDirty, 'call', _68 => _68({ entity: this.id, reason: "driver-added" })]);
+    _optionalChain([this, 'access', _69 => _69.scene, 'optionalAccess', _70 => _70._registerActiveDriverEntity, 'call', _71 => _71(this)]);
   }
   /** Assignment path when a declarative transition is configured for `prop`. */
   _animateProp(prop, to) {
-    const cfg = _optionalChain([this, 'access', _71 => _71._transitions, 'optionalAccess', _72 => _72.get, 'call', _73 => _73(prop)]);
+    const cfg = _optionalChain([this, 'access', _72 => _72._transitions, 'optionalAccess', _73 => _73.get, 'call', _74 => _74(prop)]);
     if (!cfg) {
       this._applyAnimated(prop, to);
       return;
@@ -512,7 +552,7 @@ var Entity = (_class2 = class {
       entries.map(
         (e) => new Promise((resolve) => {
           this._spawnDriver(e[0], e[1], cfg);
-          const d = _optionalChain([this, 'access', _74 => _74._drivers, 'optionalAccess', _75 => _75.get, 'call', _76 => _76(e[0])]);
+          const d = _optionalChain([this, 'access', _75 => _75._drivers, 'optionalAccess', _76 => _76.get, 'call', _77 => _77(e[0])]);
           if (!d)
             resolve();
           else d.onDone = resolve;
@@ -534,7 +574,7 @@ var Entity = (_class2 = class {
         this._applyAnimated(prop, driver.value);
       }
     }
-    _optionalChain([this, 'access', _77 => _77.scene, 'optionalAccess', _78 => _78.markDirty, 'call', _79 => _79({ entity: this.id, reason: "driver-tick" })]);
+    _optionalChain([this, 'access', _78 => _78.scene, 'optionalAccess', _79 => _79.markDirty, 'call', _80 => _80({ entity: this.id, reason: "driver-tick" })]);
   }
   /**
    * Internal: this entity's active-driver map (read-only view), or `null` if
@@ -559,7 +599,7 @@ var Entity = (_class2 = class {
     if (driver.isDone()) {
       this._applyAnimated(prop, driver.target);
       this._settleDriver(driver);
-      _optionalChain([this, 'access', _80 => _80._drivers, 'optionalAccess', _81 => _81.delete, 'call', _82 => _82(prop)]);
+      _optionalChain([this, 'access', _81 => _81._drivers, 'optionalAccess', _82 => _82.delete, 'call', _83 => _83(prop)]);
     } else {
       this._applyAnimated(prop, driver.value);
     }
@@ -620,7 +660,7 @@ var Entity = (_class2 = class {
    * @example entity.on('click', (e) => console.log('clicked', e));
    */
   on(event, callback, options) {
-    const map = _optionalChain([options, 'optionalAccess', _83 => _83.capture]) ? this.captureListeners ??= /* @__PURE__ */ new Map() : this.listeners ??= /* @__PURE__ */ new Map();
+    const map = _optionalChain([options, 'optionalAccess', _84 => _84.capture]) ? this.captureListeners ??= /* @__PURE__ */ new Map() : this.listeners ??= /* @__PURE__ */ new Map();
     if (!map.has(event)) {
       map.set(event, []);
     }
@@ -636,7 +676,7 @@ var Entity = (_class2 = class {
    * @returns `this` for method chaining.
    */
   off(event, callback, options) {
-    const handlers = _optionalChain([(_optionalChain([options, 'optionalAccess', _84 => _84.capture]) ? this.captureListeners : this.listeners), 'optionalAccess', _85 => _85.get, 'call', _86 => _86(event)]);
+    const handlers = _optionalChain([(_optionalChain([options, 'optionalAccess', _85 => _85.capture]) ? this.captureListeners : this.listeners), 'optionalAccess', _86 => _86.get, 'call', _87 => _87(event)]);
     if (handlers) {
       const idx = handlers.indexOf(callback);
       if (idx !== -1) handlers.splice(idx, 1);
@@ -673,8 +713,8 @@ var Entity = (_class2 = class {
       }
       this._drivers.clear();
     }
-    _optionalChain([this, 'access', _87 => _87.listeners, 'optionalAccess', _88 => _88.clear, 'call', _89 => _89()]);
-    _optionalChain([this, 'access', _90 => _90.captureListeners, 'optionalAccess', _91 => _91.clear, 'call', _92 => _92()]);
+    _optionalChain([this, 'access', _88 => _88.listeners, 'optionalAccess', _89 => _89.clear, 'call', _90 => _90()]);
+    _optionalChain([this, 'access', _91 => _91.captureListeners, 'optionalAccess', _92 => _92.clear, 'call', _93 => _93()]);
     if (this.parent) {
       this.parent.remove(this);
     }
@@ -689,7 +729,7 @@ var Entity = (_class2 = class {
    * @param payload - Arbitrary data forwarded to each listener.
    */
   emit(event, payload) {
-    const handlers = _optionalChain([this, 'access', _93 => _93.listeners, 'optionalAccess', _94 => _94.get, 'call', _95 => _95(event)]);
+    const handlers = _optionalChain([this, 'access', _94 => _94.listeners, 'optionalAccess', _95 => _95.get, 'call', _96 => _96(event)]);
     if (handlers) {
       handlers.forEach((h) => h(payload));
     }
@@ -703,19 +743,19 @@ var Entity = (_class2 = class {
    * with `requestAnimationFrame(() => document.getElementById(id)?.focus())`.
    */
   focus() {
-    const el = _optionalChain([this, 'access', _96 => _96.scene, 'optionalAccess', _97 => _97.getA11yElement, 'call', _98 => _98(this.id)]);
+    const el = _optionalChain([this, 'access', _97 => _97.scene, 'optionalAccess', _98 => _98.getA11yElement, 'call', _99 => _99(this.id)]);
     if (el) {
       el.focus();
       return;
     }
     requestAnimationFrame(() => {
-      const retry = _optionalChain([this, 'access', _99 => _99.scene, 'optionalAccess', _100 => _100.getA11yElement, 'call', _101 => _101(this.id)]);
+      const retry = _optionalChain([this, 'access', _100 => _100.scene, 'optionalAccess', _101 => _101.getA11yElement, 'call', _102 => _102(this.id)]);
       if (retry) retry.focus();
     });
   }
   /** Run one node's listeners for the event, honoring stopImmediatePropagation. */
   fireListeners(node, map, event) {
-    const handlers = _optionalChain([map, 'optionalAccess', _102 => _102.get, 'call', _103 => _103(event.type)]);
+    const handlers = _optionalChain([map, 'optionalAccess', _103 => _103.get, 'call', _104 => _104(event.type)]);
     if (!handlers) return;
     event.currentTarget = node;
     for (const h of handlers.slice()) {
@@ -1047,9 +1087,42 @@ var Entity = (_class2 = class {
    * `selectable` is set — natively selectable. Returns `null` by default.
    * Read on the a11y sync cadence, so text changes propagate automatically.
    *
+   * @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
+   *   {@link ContentProjectionHint}.
    * @returns The projection descriptor, or `null` to project nothing.
    */
-  getContentProjection() {
+  getContentProjection(hint) {
+    void hint;
+    return null;
+  }
+  /**
+   * A cheap, monotonically-increasing stamp of this entity's projected content.
+   *
+   * Purely an optimization, and opt-in: returning `null` (the default) means
+   * "I cannot cheaply tell whether my content changed", and the {@link Scene}
+   * then rebuilds the projection every synced frame exactly as before. An
+   * implementation must bump the value whenever anything
+   * {@link getContentProjection} would report changes — text, fonts, line
+   * geometry, `selectable`, grid revision.
+   *
+   * When two consecutive syncs report the same epoch AND the entity's geometry
+   * is unchanged, `Scene` skips the block *before* calling
+   * {@link getContentProjection}. That matters because the projection call is
+   * O(glyphs-in-block) and the DOM diff around it costs about the same again:
+   * measured on a 1500-resident-block document, a sync in which the projected
+   * text was byte-identical before and after still cost 17.875 ms, and skipping
+   * unchanged blocks took that to 0.475 ms (carryctx CTX-0199, vectojs#343).
+   *
+   * Correctness is entirely on the implementer: a stale epoch means stale DOM,
+   * so bump it in the same place the content is invalidated rather than trying
+   * to enumerate mutation sites afterwards. Any monotonic counter works; the
+   * value is only ever compared for equality with the previous sync's.
+   *
+   * @returns The current content epoch, or `null` to disable skipping.
+   */
+  getContentEpoch() {
     return null;
   }
   /**
@@ -1069,7 +1142,7 @@ var Entity = (_class2 = class {
    * @returns `true` if at least one animation or property driver remains.
    */
   hasPendingAnimations() {
-    return (_nullishCoalesce(_optionalChain([this, 'access', _104 => _104.animations, 'optionalAccess', _105 => _105.length]), () => ( 0))) > 0 || (_nullishCoalesce(_optionalChain([this, 'access', _106 => _106._drivers, 'optionalAccess', _107 => _107.size]), () => ( 0))) > 0;
+    return (_nullishCoalesce(_optionalChain([this, 'access', _105 => _105.animations, 'optionalAccess', _106 => _106.length]), () => ( 0))) > 0 || (_nullishCoalesce(_optionalChain([this, 'access', _107 => _107._drivers, 'optionalAccess', _108 => _108.size]), () => ( 0))) > 0;
   }
 }, _class2);
 
@@ -1091,20 +1164,22 @@ 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.
-  __init39() {this.hyphenator = null}
-  __init40() {this.layoutText = ""}
-  __init41() {this.text = ""}
-  __init42() {this.lastRenderedSeqId = 0}
+  __init40() {this.hyphenator = null}
+  __init41() {this.layoutText = ""}
+  __init42() {this.text = ""}
+  __init43() {this.lastRenderedSeqId = 0}
+  /** Bumped by {@link queueLayout}; read by `Scene` to skip an unchanged sync. */
+  __init44() {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.
-  __init43() {this.atlasDecodeTarget = null}
-  __init44() {this.atlasDecodeHandler = null}
-  __init45() {this.rgbColorCache = /* @__PURE__ */ new Map()}
-  __init46() {this.fontStringCache = []}
-  __init47() {this.layoutResult = null}
+  __init45() {this.atlasDecodeTarget = null}
+  __init46() {this.atlasDecodeHandler = null}
+  __init47() {this.rgbColorCache = /* @__PURE__ */ new Map()}
+  __init48() {this.fontStringCache = []}
+  __init49() {this.layoutResult = null}
   constructor(text, options) {
-    super();_class3.prototype.__init39.call(this);_class3.prototype.__init40.call(this);_class3.prototype.__init41.call(this);_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);;
+    super();_class3.prototype.__init40.call(this);_class3.prototype.__init41.call(this);_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);;
     this.font = options.font;
     this.texture = options.texture;
     this.fallbackFont = _nullishCoalesce(options.fallbackFont, () => ( "sans-serif"));
@@ -1149,7 +1224,7 @@ var MSDFTextEntity = (_class3 = class extends Entity {
     const target = this.texture;
     this.atlasDecodeHandler = () => {
       this.detachAtlasDecodeListener();
-      _optionalChain([this, 'access', _108 => _108.scene, 'optionalAccess', _109 => _109.markDirty, 'call', _110 => _110()]);
+      _optionalChain([this, 'access', _109 => _109.scene, 'optionalAccess', _110 => _110.markDirty, 'call', _111 => _111()]);
     };
     target.addEventListener("load", this.atlasDecodeHandler);
     target.addEventListener("error", this.atlasDecodeHandler);
@@ -1214,6 +1289,7 @@ var MSDFTextEntity = (_class3 = class extends Entity {
     });
   }
   queueLayout() {
+    this.contentEpoch++;
     _layout.LayoutWorkerManager.getInstance().queueLayout(this.id, this.layoutText, {
       fontId: this.font.id,
       fontSize: this.fontSize,
@@ -1227,7 +1303,7 @@ var MSDFTextEntity = (_class3 = class extends Entity {
         if (res.seqId < this.lastRenderedSeqId) return;
         this.lastRenderedSeqId = res.seqId;
         this.layoutResult = res;
-        _optionalChain([this, 'access', _111 => _111.scene, 'optionalAccess', _112 => _112.markDirty, 'call', _113 => _113()]);
+        _optionalChain([this, 'access', _112 => _112.scene, 'optionalAccess', _113 => _113.markDirty, 'call', _114 => _114()]);
       }
     });
   }
@@ -1243,6 +1319,9 @@ var MSDFTextEntity = (_class3 = class extends Entity {
       lineHeight: this.lineHeight
     };
   }
+  getContentEpoch() {
+    return this.contentEpoch;
+  }
   isPointInside(globalX, globalY) {
     if (!this.layoutResult) return false;
     const local = this.worldToLocal(globalX, globalY);
@@ -1376,23 +1455,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)'`.
    */
-  __init48() {this.fallbackStroke = "rgba(248,113,113,0.9)"}
+  __init50() {this.fallbackStroke = "rgba(248,113,113,0.9)"}
   /** Fill behind the fallback marker. Default `'rgba(248,113,113,0.12)'`. */
-  __init49() {this.fallbackFill = "rgba(248,113,113,0.12)"}
-  __init50() {this.svgSource = ""}
-  __init51() {this.imageBitmap = null}
-  __init52() {this.imageElement = null}
-  __init53() {this.blobURL = null}
-  __init54() {this.currentImg = null}
-  __init55() {this.lodTimeout = null}
-  __init56() {this.rasterFailed = false}
-  __init57() {this.cachedDoc = null}
-  __init58() {this.baseWidth = 100}
-  __init59() {this.baseHeight = 100}
-  __init60() {this.lastRasterizedScale = 1}
-  __init61() {this.targetScale = 1}
+  __init51() {this.fallbackFill = "rgba(248,113,113,0.12)"}
+  __init52() {this.svgSource = ""}
+  __init53() {this.imageBitmap = null}
+  __init54() {this.imageElement = null}
+  __init55() {this.blobURL = null}
+  __init56() {this.currentImg = null}
+  __init57() {this.lodTimeout = null}
+  __init58() {this.rasterFailed = false}
+  __init59() {this.cachedDoc = null}
+  __init60() {this.baseWidth = 100}
+  __init61() {this.baseHeight = 100}
+  __init62() {this.lastRasterizedScale = 1}
+  __init63() {this.targetScale = 1}
   constructor(svgSource, id) {
-    super(id);_class4.prototype.__init48.call(this);_class4.prototype.__init49.call(this);_class4.prototype.__init50.call(this);_class4.prototype.__init51.call(this);_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);;
+    super(id);_class4.prototype.__init50.call(this);_class4.prototype.__init51.call(this);_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);;
     this.setSVGSource(svgSource);
   }
   setSVGSource(svgSource) {
@@ -1640,4 +1719,5 @@ var SVGEntity = (_class4 = class extends Entity {
 
 
 
-exports.VectoJSEvent = VectoJSEvent; exports.Entity = Entity; exports.MSDFTextEntity = MSDFTextEntity; exports.SVGEntity = SVGEntity;
+
+exports.contentLineInHint = contentLineInHint; exports.VectoJSEvent = VectoJSEvent; exports.Entity = Entity; exports.MSDFTextEntity = MSDFTextEntity; exports.SVGEntity = SVGEntity;

package/dist/components/TextEntity.d.ts

@@ -12,12 +12,15 @@ export declare class TextEntity extends Entity {
     hoveredFillStyle: string | any;
     lineWidth: number;
     private isHovered;
+    /** Bumped by {@link applyLayout}; read by `Scene` to skip an unchanged sync. */
+    private contentEpoch;
     constructor(text: string, atlas: any, maxWidth: number, fontSize?: number);
     /**
      * Mirror the rendered text into the DOM content layer: find-in-page, screen
      * readers, crawlers, and translation see the same string the canvas draws.
      */
     getContentProjection(): ContentProjection | null;
+    getContentEpoch(): number;
     /**
      * Replace the text content. Runs the **cold** measurement pass (re-segment +
      * re-measure) since the glyphs changed, then re-lays out.