npm - @vectojs/core - Versions diffs - 1.29.0 → 1.30.0 - Mend

@vectojs/core 1.29.0 → 1.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/dist/{chunk-MVFPN4Y5.mjs → chunk-2WXZCPYQ.mjs} +47 -1
package/dist/{chunk-Z3HFY75R.js → chunk-7PI7LVWW.js} +124 -78
package/dist/index.js +424 -215
package/dist/index.mjs +224 -15
package/dist/text.js +2 -2
package/dist/text.mjs +1 -1
package/dist/tree/Entity.d.ts +78 -1
package/dist/tree/Scene.d.ts +88 -0
package/package.json +1 -1

package/dist/index.mjs CHANGED Viewed

@@ -16,8 +16,9 @@ import {
   Entity,
   MSDFTextEntity,
   SVGEntity,
-  VectoJSEvent
-} from "./chunk-MVFPN4Y5.mjs";
+  VectoJSEvent,
+  contentLineInHint
+} from "./chunk-2WXZCPYQ.mjs";
 // src/tree/Scene.ts
 import { SpringDriver, TweenDriver } from "@vectojs/animation";
@@ -1430,6 +1431,45 @@ function parseInlinePx(value) {
   const n = parseFloat(value);
   return Number.isFinite(n) && n > 0 ? n : null;
 }
+function projectionGridLineWindow(grid, projectionLines, band) {
+  const count = grid.lines.length;
+  const all = { start: 0, end: count, gated: false };
+  if (!band || count === 0) return all;
+  const lines = [];
+  for (let i = 0; i < count; i++) {
+    const projected = projectionLines?.[i];
+    lines.push({
+      y: projected?.y ?? i * grid.lineHeight,
+      lineHeight: projected?.lineHeight ?? grid.lineHeight
+    });
+  }
+  return projectionLineWindow(lines, band, grid.lineHeight);
+}
+function projectionLineWindow(lines, band, fallbackLineHeight) {
+  const all = {
+    start: 0,
+    end: lines.length,
+    gated: false
+  };
+  if (!band || lines.length === 0) return all;
+  let start = -1;
+  let end = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const h = line.lineHeight ?? fallbackLineHeight;
+    if (line.y + h >= band.minY && line.y <= band.maxY) {
+      if (start === -1) start = i;
+      end = i + 1;
+    } else if (start !== -1 && line.y > band.maxY) {
+      break;
+    }
+  }
+  if (start === -1) {
+    return { start: 0, end: Math.min(1, lines.length), gated: true };
+  }
+  if (start === 0 && end === lines.length) return all;
+  return { start, end, gated: true };
+}
 function collectTextNodes(root) {
   const out = [];
   const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
@@ -1988,6 +2028,14 @@ var Scene = class _Scene {
    *  mid-hover synthesize the `pointerleave` the browser never sends for a
    *  detached element, so the entity doesn't keep its hover state. */
   hoveredA11yElements = /* @__PURE__ */ new WeakSet();
+  /**
+   * Entity ids the application has pinned via {@link requestA11yProjection}.
+   *
+   * Ids rather than entities so a removed entity cannot be retained by this set;
+   * a stale id simply never matches. Cleared per-entity by
+   * {@link releaseA11yProjection}.
+   */
+  a11yProjectionRequests = /* @__PURE__ */ new Set();
   /** Persistent tabindex=-1 element in a11yRoot. When the focused a11y mirror is
    *  pruned (virtualization/streaming/removal) while it holds focus, we move
    *  focus here instead of letting the browser drop it to <body> — keeping the
@@ -2941,7 +2989,9 @@ var Scene = class _Scene {
         const el = this.contentElements?.get(node.id);
         if (el) {
           const projectedText = el.textContent || "";
-          if (projectedText !== "" && projectedText !== proj.text) {
+          const windowed = el.dataset.vectoProjectionWindow !== void 0;
+          const mismatched = windowed ? !proj.text.includes(projectedText) : projectedText !== proj.text;
+          if (projectedText !== "" && mismatched) {
             this._devWarn(
               `Content projection mismatch for entity "${node.id}": projection says "${proj.text.slice(0, 60)}" but DOM shows "${projectedText.slice(0, 60)}". Ensure getContentProjection() output matches what drawSelf renders.`
             );
@@ -3885,7 +3935,92 @@ var Scene = class _Scene {
    * predicate, which is only tractable while it has one home.
    */
   shouldProjectA11y(node) {
-    return node.interactive && (node.width > 0 || node.a11yFullViewport);
+    if (!node.interactive) return false;
+    if (!(node.width > 0 || node.a11yFullViewport)) return false;
+    switch (node.a11yProjection) {
+      case "never":
+        return false;
+      case "onDemand":
+        return this.a11yEngaged(node);
+      default:
+        return true;
+    }
+  }
+  /**
+   * Whether an `a11yProjection: 'onDemand'` entity is currently engaged enough to
+   * deserve a shadow node.
+   *
+   * Deliberately **not** hover alone. A keyboard or assistive-technology user
+   * generates no pointer events, so a hover-only trigger would withhold the
+   * semantic node from precisely the users it exists for. Three signals, any of
+   * which counts:
+   *
+   * - **Focus.** Covers keyboard traversal and AT-driven focus. Checked against
+   *   the live element so a node keeps its own focus rather than being pruned out
+   *   from under the user mid-interaction.
+   * - **Pointer target.** The entity under the pointer, so a mouse user gets the
+   *   same node a hover-gated design would have given them.
+   * - **Explicit request.** {@link Scene.requestA11yProjection}, for anything the
+   *   app knows is significant — the selected item, a search hit, a
+   *   just-announced element. This is the escape hatch that keeps the mode usable
+   *   when neither focus nor pointer applies.
+   *
+   * The entity stays hit-testable on canvas regardless, so a click always reaches
+   * it and promotes it on the next sync.
+   */
+  a11yEngaged(node) {
+    if (this.a11yProjectionRequests.has(node.id)) return true;
+    if (this.mouseX > -9e3 && !this.projectsSelectableText(node)) {
+      if (node.isPointInside(this.mouseX, this.mouseY)) return true;
+    }
+    const existing = this.a11yElements?.get(node.id);
+    if (existing && typeof document !== "undefined" && document.activeElement === existing) {
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Whether `node` mirrors selectable text of its own.
+   *
+   * Such an entity must not be promoted by the pointer: its interactive a11y node
+   * would sit above the text mirror and eat the mousedown that starts a native
+   * selection.
+   */
+  projectsSelectableText(node) {
+    const projection = node.getContentProjection?.();
+    return !!projection?.text && projection.selectable !== false;
+  }
+  /**
+   * Keep `entity`'s a11y shadow node projected while it has
+   * `a11yProjection: 'onDemand'`.
+   *
+   * For anything the application knows matters but the engine cannot infer — the
+   * selected danmaku, a search hit, a node just announced in a live region.
+   * Without this, `'onDemand'` would be reachable only by focus or pointer, and
+   * an app-driven selection change would leave the selected entity semantically
+   * invisible.
+   *
+   * Idempotent. Has no effect on an `'eager'` entity, which is always projected.
+   */
+  requestA11yProjection(entity) {
+    const id = typeof entity === "string" ? entity : entity.id;
+    if (this.a11yProjectionRequests.has(id)) return;
+    this.a11yProjectionRequests.add(id);
+    this.a11yNeedsReorder = true;
+    this.markDirty({ entity: id, reason: "a11y-reorder" });
+  }
+  /**
+   * Drop a projection request made by {@link requestA11yProjection}.
+   *
+   * The node is not removed immediately: it survives while it is focused or under
+   * the pointer, and is pruned on the next sync that finds it unengaged. Releasing
+   * a request the scene does not hold is a no-op.
+   */
+  releaseA11yProjection(entity) {
+    const id = typeof entity === "string" ? entity : entity.id;
+    if (!this.a11yProjectionRequests.delete(id)) return;
+    this.a11yNeedsReorder = true;
+    this.markDirty({ entity: id, reason: "a11y-reorder" });
   }
   syncA11y(node, container = null) {
     if (!this.a11yRoot) return;
@@ -4359,6 +4494,57 @@ var Scene = class _Scene {
     }
     return true;
   }
+  /**
+   * The band of an entity's own y coordinates that is worth projecting, or
+   * `null` to project everything.
+   *
+   * {@link projectionBoxVisible} answers "is this entity near the viewport",
+   * which frees whole blocks that scroll away. It cannot help a single entity
+   * *taller* than the viewport: that entity's box always intersects, so every
+   * one of its visual lines was materialized — a `<span>` per line and, on the
+   * grid path, a `<span>` per glyph cluster. That is where "14.8k elements for a
+   * 346KB Markdown doc" comes from, and it is O(document) rather than
+   * O(viewport) in both element count and per-frame walk cost.
+   *
+   * Measured on one entity scrolled to its middle, real headed browsers
+   * (`benchmarks/projection-per-line/`): at 4000 lines, materializing every line
+   * costs 6.28 ms/frame on Chrome and 6.51 ms on Firefox with 36,000 child
+   * elements, against 0.28/0.16 ms and 963 elements when only the visible band
+   * is emitted. The gated cost is *flat* across a 20x document-size range, so
+   * this converts an asymptote rather than shaving a constant.
+   *
+   * Returns local-y bounds in the entity's own coordinate space, already
+   * expanded by `margin` and intersected with every `clipChildren` ancestor, so
+   * a line inside a scrolled container is measured against the container rather
+   * than the window. `null` means "no useful bound" — a degenerate transform, a
+   * rotation/skew that makes a y-band meaningless, or a boundless entity — and
+   * the caller must then project every line, because emitting nothing would
+   * silently drop text from selection, find-in-page and screen readers.
+   */
+  projectionVisibleLocalYBand(node, tf, margin) {
+    const { b, d, f } = tf;
+    if (b !== 0 || d === 0 || !Number.isFinite(d) || !Number.isFinite(f)) return null;
+    const top = (-margin - f) / d;
+    const bottom = (this.height + margin - f) / d;
+    let minY = Math.min(top, bottom);
+    let maxY = Math.max(top, bottom);
+    for (let ancestor = node.parent; ancestor; ancestor = ancestor.parent) {
+      if (!ancestor.clipChildren || ancestor.width <= 0 || ancestor.height <= 0) continue;
+      const originWorldY = f;
+      const unitWorldY = d + f;
+      const originLocal = ancestor.worldToLocal(tf.e, originWorldY);
+      const unitLocal = ancestor.worldToLocal(tf.e + tf.c, unitWorldY);
+      if (!originLocal || !unitLocal) return null;
+      const slope = unitLocal.y - originLocal.y;
+      if (slope === 0 || !Number.isFinite(slope)) return null;
+      const a1 = (-margin - originLocal.y) / slope;
+      const a2 = (ancestor.height + margin - originLocal.y) / slope;
+      minY = Math.max(minY, Math.min(a1, a2));
+      maxY = Math.min(maxY, Math.max(a1, a2));
+    }
+    if (!Number.isFinite(minY) || !Number.isFinite(maxY) || maxY < minY) return null;
+    return { minY, maxY };
+  }
   syncContentProjection(node) {
     if (!this.contentProjectionEnabled || !this.a11yRoot) return;
     let el = this.contentElements.get(node.id);
@@ -4376,7 +4562,10 @@ var Scene = class _Scene {
       releaseProjectionEl();
       return;
     }
-    const projection = node.getContentProjection();
+    const lineBand = Number.isFinite(margin) ? this.projectionVisibleLocalYBand(node, worldTf, margin) : null;
+    const projection = node.getContentProjection(
+      lineBand ? { minY: lineBand.minY, maxY: lineBand.maxY } : void 0
+    );
     if (!projection || !projection.text) {
       releaseProjectionEl();
       return;
@@ -4411,18 +4600,24 @@ var Scene = class _Scene {
     }
     if (projection.grid) {
       const gridSyncStart = this._phaseTiming ? performance.now() : 0;
-      this.syncContentGridProjection(node, el, projection, projection.grid);
+      this.syncContentGridProjection(node, el, projection, projection.grid, lineBand);
       if (this._phaseTiming) this._recordPhase("gridSync", performance.now() - gridSyncStart);
     } else if (lines && lines.length > 0) {
+      const lineWindow = projectionLineWindow(lines, lineBand, projection.lineHeight ?? 16);
       const signature = JSON.stringify({
         lines,
         fallbackFont: projection.font ?? "",
-        fallbackLineHeight: projection.lineHeight ?? 16
+        fallbackLineHeight: projection.lineHeight ?? 16,
+        // Part of the signature, or scrolling would not rebuild the carriers and
+        // the window would stay frozen where it was first built. Quantized to
+        // whole line indices by construction, so a sub-pixel scroll inside one
+        // line does not churn the DOM.
+        window: lineWindow.gated ? `${lineWindow.start}-${lineWindow.end}` : "all"
       });
       if (el.dataset.vectoProjectionLines !== signature) {
         this.preserveContentSelectionAcrossRebuild(el, () => {
           el.replaceChildren();
-          for (let index = 0; index < lines.length; index++) {
+          for (let index = lineWindow.start; index < lineWindow.end; index++) {
             const line = lines[index];
             const lineElement = document.createElement("span");
             const lineFont = line.font ?? projection.font ?? "";
@@ -4463,6 +4658,11 @@ var Scene = class _Scene {
           }
         });
         el.dataset.vectoProjectionLines = signature;
+        if (lineWindow.gated) {
+          el.dataset.vectoProjectionWindow = `${lineWindow.start}-${lineWindow.end}/${lines.length}`;
+        } else {
+          delete el.dataset.vectoProjectionWindow;
+        }
       }
     } else {
       if (el.textContent !== projection.text) {
@@ -4511,11 +4711,12 @@ var Scene = class _Scene {
    * carrier from the shared canvas geometry. Browser font measurement happens
    * later in one cold read/write batch, never inside projection synchronization.
    */
-  syncContentGridProjection(node, el, projection, grid) {
+  syncContentGridProjection(node, el, projection, grid, lineBand) {
     if (grid.source !== projection.text) {
       throw new Error("ContentProjection.grid.source must equal ContentProjection.text");
     }
-    const signature = `${grid.revision}`;
+    const gridWindow = projectionGridLineWindow(grid, projection.lines, lineBand);
+    const signature = gridWindow.gated ? `${grid.revision}:${gridWindow.start}-${gridWindow.end}` : `${grid.revision}`;
     if (el.dataset.vectoContentGrid !== signature) {
       const materializeStart = typeof performance !== "undefined" ? performance.now() : 0;
       this.clearContentGridState(node.id, el, false);
@@ -4523,7 +4724,8 @@ var Scene = class _Scene {
       const selectionLine = this.contentGridSelectionLine(el);
       let rebuiltSelectionLine = false;
       const existingLines = el.children;
-      for (let lineIndex = 0; lineIndex < grid.lines.length; lineIndex++) {
+      for (let lineIndex = gridWindow.start; lineIndex < gridWindow.end; lineIndex++) {
+        const domIndex = lineIndex - gridWindow.start;
         const gridLine = grid.lines[lineIndex];
         const projectedLine = projectionLines[lineIndex];
         const lineHeight = projectedLine?.lineHeight ?? grid.lineHeight;
@@ -4538,7 +4740,7 @@ var Scene = class _Scene {
           lineFont,
           lineIndex === 0
         );
-        const reusable = existingLines[lineIndex];
+        const reusable = existingLines[domIndex];
         if (reusable !== void 0 && reusable.dataset.vectoGridLineSig === lineSignature && reusable.dataset.vectoGridLine === `${lineIndex}`) {
           continue;
         }
@@ -4611,12 +4813,13 @@ var Scene = class _Scene {
             lineElement.appendChild(marker);
           }
         }
-        const occupant = el.children[lineIndex];
+        const occupant = el.children[domIndex];
         if (occupant) el.replaceChild(lineElement, occupant);
         else el.appendChild(lineElement);
       }
-      while (el.children.length > grid.lines.length) {
-        if (selectionLine !== null && selectionLine >= grid.lines.length) {
+      const windowLength = gridWindow.end - gridWindow.start;
+      while (el.children.length > windowLength) {
+        if (selectionLine !== null && selectionLine >= gridWindow.end) {
           rebuiltSelectionLine = true;
         }
         el.lastElementChild?.remove();
@@ -4624,6 +4827,11 @@ var Scene = class _Scene {
       if (rebuiltSelectionLine) this.releaseContentSelectionForRebuild(el);
       el.dataset.vectoProjectionLines = signature;
       el.dataset.vectoContentGrid = signature;
+      if (gridWindow.gated) {
+        el.dataset.vectoProjectionWindow = `${gridWindow.start}-${gridWindow.end}/${grid.lines.length}`;
+      } else {
+        delete el.dataset.vectoProjectionWindow;
+      }
       el.dataset.vectoGridCarriers = `${el.querySelectorAll("[data-vecto-grid-cell]").length}`;
       if (typeof performance !== "undefined") {
         const materializeMs = performance.now() - materializeStart;
@@ -6670,6 +6878,7 @@ export {
   VectoJSEvent,
   WebGPUParticleSystemManager,
   beginVectoUserTiming,
+  contentLineInHint,
   createWebGLPointRenderer,
   endVectoUserTiming,
   installRendererDevTraps,

package/dist/text.js CHANGED Viewed

@@ -2,11 +2,11 @@
-var _chunkZ3HFY75Rjs = require('./chunk-Z3HFY75R.js');
+var _chunk7PI7LVWWjs = require('./chunk-7PI7LVWW.js');
 // src/text/index.ts
 var _text = require('@vectojs/text'); _createStarExport(_text);
-exports.MSDFTextEntity = _chunkZ3HFY75Rjs.MSDFTextEntity; exports.SVGEntity = _chunkZ3HFY75Rjs.SVGEntity;
+exports.MSDFTextEntity = _chunk7PI7LVWWjs.MSDFTextEntity; exports.SVGEntity = _chunk7PI7LVWWjs.SVGEntity;

package/dist/text.mjs CHANGED Viewed

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

package/dist/tree/Entity.d.ts CHANGED Viewed

@@ -103,6 +103,43 @@ export interface ContentProjectionLine {
     /** Styled text runs in visual order. */
     runs?: ContentProjectionRun[];
 }
+/**
+ * Advice from the {@link Scene} about which part of an entity is worth
+ * describing in {@link Entity.getContentProjection}.
+ *
+ * **Purely an optimization, and ignoring it is always correct.** The Scene
+ * windows the DOM itself, so an entity that returns its whole document still
+ * behaves correctly — it just pays to build lines that get discarded. An entity
+ * whose projection is O(glyphs) can use this to make that build O(visible)
+ * instead, which is the difference between per-frame cost that scales with the
+ * document and cost that scales with the viewport.
+ *
+ * Why a hint rather than a strict window: the entity owns the mapping from its
+ * own text to visual lines, and only it knows things like where a wrapped
+ * paragraph begins. Handing it a band and letting it round outward keeps that
+ * knowledge in one place. An entity may return more than asked — never less
+ * than it can, because text absent from the projection is invisible to
+ * find-in-page, copy and, for static text, the screen reader.
+ */
+export interface ContentProjectionHint {
+    /**
+     * Inclusive band of entity-local y worth projecting, already expanded by the
+     * scene's `contentProjectionMargin` and intersected with every clipping
+     * ancestor. Absent when no useful bound exists (a rotated or skewed
+     * transform, a boundless entity), in which case project everything.
+     */
+    minY?: number;
+    maxY?: number;
+}
+/**
+ * Whether a line at `y` of height `height` is worth projecting under `hint`.
+ *
+ * Shared so every consumer rounds the same way: a line is kept when its box
+ * overlaps the band at all, which retains a line straddling the edge whole
+ * rather than clipping it mid-glyph. Returns `true` when the hint carries no
+ * band, so the default is always "project it".
+ */
+export declare function contentLineInHint(hint: ContentProjectionHint | undefined, y: number, height: number): boolean;
 export interface ContentProjection {
     /** The logical source text exposed to find, selection, copy, and assistive technology. */
     text: string;
@@ -540,6 +577,42 @@ export declare abstract class Entity {
      * nodes, so on-top components stay clickable.
      */
     a11yFullViewport: boolean;
+    /**
+     * 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' | 'onDemand' | 'never';
     /**
      * Hide this entity AND its whole subtree from the accessibility/automation
      * projection, regardless of each node's own `interactive` flag.
@@ -920,9 +993,13 @@ export declare abstract class Entity {
      * `selectable` is set — natively selectable. Returns `null` by default.
      * Read on the a11y sync cadence, so text changes propagate automatically.
      *
+     * @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(): ContentProjection | null;
+    getContentProjection(hint?: ContentProjectionHint): ContentProjection | null;
     /**
      * Whether this entity still has a queued/running tween animation, or an
      * active {@link setTransition}/{@link animateTo}/{@link springTo} property

package/dist/tree/Scene.d.ts CHANGED Viewed

@@ -555,6 +555,14 @@ export declare class Scene {
      *  mid-hover synthesize the `pointerleave` the browser never sends for a
      *  detached element, so the entity doesn't keep its hover state. */
     private readonly hoveredA11yElements;
+    /**
+     * Entity ids the application has pinned via {@link requestA11yProjection}.
+     *
+     * Ids rather than entities so a removed entity cannot be retained by this set;
+     * a stale id simply never matches. Cleared per-entity by
+     * {@link releaseA11yProjection}.
+     */
+    private readonly a11yProjectionRequests;
     /** Persistent tabindex=-1 element in a11yRoot. When the focused a11y mirror is
      *  pruned (virtualization/streaming/removal) while it holds focus, we move
      *  focus here instead of letting the browser drop it to <body> — keeping the
@@ -1324,6 +1332,58 @@ export declare class Scene {
      * predicate, which is only tractable while it has one home.
      */
     private shouldProjectA11y;
+    /**
+     * Whether an `a11yProjection: 'onDemand'` entity is currently engaged enough to
+     * deserve a shadow node.
+     *
+     * Deliberately **not** hover alone. A keyboard or assistive-technology user
+     * generates no pointer events, so a hover-only trigger would withhold the
+     * semantic node from precisely the users it exists for. Three signals, any of
+     * which counts:
+     *
+     * - **Focus.** Covers keyboard traversal and AT-driven focus. Checked against
+     *   the live element so a node keeps its own focus rather than being pruned out
+     *   from under the user mid-interaction.
+     * - **Pointer target.** The entity under the pointer, so a mouse user gets the
+     *   same node a hover-gated design would have given them.
+     * - **Explicit request.** {@link Scene.requestA11yProjection}, for anything the
+     *   app knows is significant — the selected item, a search hit, a
+     *   just-announced element. This is the escape hatch that keeps the mode usable
+     *   when neither focus nor pointer applies.
+     *
+     * The entity stays hit-testable on canvas regardless, so a click always reaches
+     * it and promotes it on the next sync.
+     */
+    private a11yEngaged;
+    /**
+     * Whether `node` mirrors selectable text of its own.
+     *
+     * Such an entity must not be promoted by the pointer: its interactive a11y node
+     * would sit above the text mirror and eat the mousedown that starts a native
+     * selection.
+     */
+    private projectsSelectableText;
+    /**
+     * Keep `entity`'s a11y shadow node projected while it has
+     * `a11yProjection: 'onDemand'`.
+     *
+     * For anything the application knows matters but the engine cannot infer — the
+     * selected danmaku, a search hit, a node just announced in a live region.
+     * Without this, `'onDemand'` would be reachable only by focus or pointer, and
+     * an app-driven selection change would leave the selected entity semantically
+     * invisible.
+     *
+     * Idempotent. Has no effect on an `'eager'` entity, which is always projected.
+     */
+    requestA11yProjection(entity: Entity | string): void;
+    /**
+     * Drop a projection request made by {@link requestA11yProjection}.
+     *
+     * The node is not removed immediately: it survives while it is focused or under
+     * the pointer, and is pruned on the next sync that finds it unengaged. Releasing
+     * a request the scene does not hold is a no-op.
+     */
+    releaseA11yProjection(entity: Entity | string): void;
     private syncA11y;
     /**
      * Mirror one entity's static text ({@link Entity.getContentProjection}) as a
@@ -1341,6 +1401,34 @@ export declare class Scene {
      * culling and always count as visible, matching the legacy behavior.
      */
     private projectionBoxVisible;
+    /**
+     * The band of an entity's own y coordinates that is worth projecting, or
+     * `null` to project everything.
+     *
+     * {@link projectionBoxVisible} answers "is this entity near the viewport",
+     * which frees whole blocks that scroll away. It cannot help a single entity
+     * *taller* than the viewport: that entity's box always intersects, so every
+     * one of its visual lines was materialized — a `<span>` per line and, on the
+     * grid path, a `<span>` per glyph cluster. That is where "14.8k elements for a
+     * 346KB Markdown doc" comes from, and it is O(document) rather than
+     * O(viewport) in both element count and per-frame walk cost.
+     *
+     * Measured on one entity scrolled to its middle, real headed browsers
+     * (`benchmarks/projection-per-line/`): at 4000 lines, materializing every line
+     * costs 6.28 ms/frame on Chrome and 6.51 ms on Firefox with 36,000 child
+     * elements, against 0.28/0.16 ms and 963 elements when only the visible band
+     * is emitted. The gated cost is *flat* across a 20x document-size range, so
+     * this converts an asymptote rather than shaving a constant.
+     *
+     * Returns local-y bounds in the entity's own coordinate space, already
+     * expanded by `margin` and intersected with every `clipChildren` ancestor, so
+     * a line inside a scrolled container is measured against the container rather
+     * than the window. `null` means "no useful bound" — a degenerate transform, a
+     * rotation/skew that makes a y-band meaningless, or a boundless entity — and
+     * the caller must then project every line, because emitting nothing would
+     * silently drop text from selection, find-in-page and screen readers.
+     */
+    private projectionVisibleLocalYBand;
     private syncContentProjection;
     /**
      * Materialize a prepared grid in logical source order while positioning each

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@vectojs/core",
-  "version": "1.29.0",
+  "version": "1.30.0",
   "publishConfig": {
     "access": "public"
   },