@vectojs/core 1.29.0 → 1.31.0

package/dist/{chunk-MVFPN4Y5.mjs → chunk-RWN3ITBD.mjs}

@@ -12,6 +12,10 @@ var ANIMATABLE_PROPS = /* @__PURE__ */ new Set([
   "rotation",
   "opacity"
 ]);
+function contentLineInHint(hint, y, height) {
+  if (hint?.minY === void 0 || hint.maxY === void 0) return true;
+  return y + height >= hint.minY && y <= hint.maxY;
+}
 var VectoJSEvent = class {
   /** The event name. */
   type;
@@ -251,6 +255,42 @@ var Entity = class {
    * nodes, so on-top components stay clickable.
    */
   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.
+   */
+  a11yProjection = "eager";
   /**
    * Hide this entity AND its whole subtree from the accessibility/automation
    * projection, regardless of each node's own `interactive` flag.
@@ -1045,9 +1085,42 @@ var Entity = 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;
   }
   /**
@@ -1093,6 +1166,8 @@ var MSDFTextEntity = class extends Entity {
   layoutText = "";
   text = "";
   lastRenderedSeqId = 0;
+  /** Bumped by {@link queueLayout}; read by `Scene` to skip an unchanged sync. */
+  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.
@@ -1212,6 +1287,7 @@ var MSDFTextEntity = class extends Entity {
     });
   }
   queueLayout() {
+    this.contentEpoch++;
     LayoutWorkerManager.getInstance().queueLayout(this.id, this.layoutText, {
       fontId: this.font.id,
       fontSize: this.fontSize,
@@ -1241,6 +1317,9 @@ var MSDFTextEntity = class extends Entity {
       lineHeight: this.lineHeight
     };
   }
+  getContentEpoch() {
+    return this.contentEpoch;
+  }
   isPointInside(globalX, globalY) {
     if (!this.layoutResult) return false;
     const local = this.worldToLocal(globalX, globalY);
@@ -1634,6 +1713,7 @@ var SVGEntity = class extends Entity {
 };
 
 export {
+  contentLineInHint,
   VectoJSEvent,
   Entity,
   MSDFTextEntity,