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

@vectojs/core 1.28.1 → 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 (16) hide show

package/dist/{chunk-MVFPN4Y5.mjs → chunk-2WXZCPYQ.mjs} +47 -1
package/dist/{chunk-Z3HFY75R.js → chunk-7PI7LVWW.js} +124 -78
package/dist/{chunk-TI5EMJGL.mjs → chunk-IFSFHYF7.mjs} +44 -1
package/dist/{chunk-K2UGEIT6.js → chunk-M73XB4ZK.js} +98 -55
package/dist/index.js +432 -223
package/dist/index.mjs +225 -16
package/dist/renderer/CanvasRenderer.d.ts +23 -0
package/dist/renderer/GlyphRasterAtlas.d.ts +12 -0
package/dist/renderer/IRenderer.d.ts +17 -0
package/dist/renderer.js +2 -2
package/dist/renderer.mjs +1 -1
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

@@ -11,13 +11,14 @@ import {
   parseColorToRGBA,
   sanitizeUrl,
   setRendererDevMode
-} from "./chunk-TI5EMJGL.mjs";
+} from "./chunk-IFSFHYF7.mjs";
 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/renderer/CanvasRenderer.d.ts CHANGED Viewed

@@ -20,6 +20,12 @@ export declare class CanvasRenderer implements IRenderer {
      * change at runtime (e.g. a window dragged between displays).
      */
     maxDPR?: number;
+    /**
+     * The ratio the context is actually scaled by, i.e. the last value the
+     * constructor or {@link resize} applied. Backs {@link pixelRatio}; see there
+     * for why this is recorded rather than recomputed on read.
+     */
+    private appliedDPR;
     /**
      * Max circles per batched `fill()`. A single Canvas 2D `fill()` over a path is
      * superlinear in sub-path count, so an unbounded batch is *slower* than many
@@ -77,6 +83,23 @@ export declare class CanvasRenderer implements IRenderer {
     getContext(): CanvasRenderingContext2D;
     /** Real `devicePixelRatio`, clamped to {@link maxDPR} when set. */
     private effectiveDPR;
+    /**
+     * @inheritdoc
+     *
+     * The ratio the context is **currently scaled by**, recorded by the constructor
+     * and {@link resize} — deliberately not a live `effectiveDPR()` call.
+     *
+     * The distinction is load-bearing rather than pedantic. `devicePixelRatio`
+     * changes the instant a zoom lands, but the backing store is only reallocated
+     * when something calls {@link resize} (in a `Scene`, the `(resolution: Ndppx)`
+     * media query). A live getter therefore reports the *future* ratio during that
+     * window, and a caller rasterizing pixels from it produces a texture that the
+     * still-old context scale resamples — the same defect this property exists to
+     * let callers avoid, merely inverted. Reporting the applied ratio means a
+     * cache keyed on it is always consistent with the pixels it is blitted into,
+     * and it simply re-keys on the next `resize`.
+     */
+    get pixelRatio(): number;
     /**
      * Resize the backing canvas buffer and re-apply DPR scaling.
      *

package/dist/renderer/GlyphRasterAtlas.d.ts CHANGED Viewed

@@ -143,6 +143,18 @@ export declare class GlyphRasterAtlas {
     private _misses;
     private _resets;
     constructor(options?: GlyphRasterAtlasOptions);
+    /**
+     * The device-pixel-ratio these slots were rasterized at.
+     *
+     * Immutable by design. Slot `sx`/`sy`/`sw`/`sh` are device pixels at *this*
+     * ratio while `w`/`h` are CSS pixels, so changing it would invalidate every
+     * resident slot — an atlas is therefore keyed by DPR and replaced on a change,
+     * not mutated (see `Markdown`'s code atlas pool). Exposed so a caller can
+     * compare it against {@link IRenderer.pixelRatio} and assert the blit is
+     * 1:1 rather than resampled: `blitScale = renderer.pixelRatio / atlas.dpr`,
+     * which must be 1 for the pixels to land crisp.
+     */
+    get pixelRatio(): number;
     /** Live instrumentation snapshot. */
     get stats(): GlyphRasterAtlasStats;
     /**

package/dist/renderer/IRenderer.d.ts CHANGED Viewed

@@ -67,6 +67,23 @@ export interface IRenderer {
      * backend in the build where it matters is not much of a debug tool.
      */
     readonly kind?: 'canvas2d' | 'svg' | 'three' | string;
+    /**
+     * Device pixels per CSS pixel of this renderer's backing store, i.e. the scale
+     * already applied to the drawing context.
+     *
+     * Read this rather than `window.devicePixelRatio` when rasterizing pixels that
+     * will be blitted into the renderer: the two differ whenever a backend clamps
+     * (`CanvasRenderer.maxDPR`, `SceneOptions.maxDPR`), and rasterizing at the
+     * window's ratio while the context is scaled to a clamped one blits a texture
+     * the destination then resamples. A cache keyed on this value also stays
+     * correct across a zoom or a monitor move, which a value captured once at
+     * module scope cannot — that is the defect this exists to make fixable
+     * (`GlyphRasterAtlas` consumers; see `Markdown`'s code atlas pool).
+     *
+     * Optional and a *live* read, not a snapshot: a backend that has no backing
+     * store of its own omits it, and a caller treats the absence as `1`.
+     */
+    readonly pixelRatio?: number;
     /**
      * Enable or disable draw counting. Optional; a backend that cannot count omits
      * it and a reader treats the absence as "not available".

package/dist/renderer.js CHANGED Viewed

@@ -10,7 +10,7 @@
-var _chunkK2UGEIT6js = require('./chunk-K2UGEIT6.js');
+var _chunkM73XB4ZKjs = require('./chunk-M73XB4ZK.js');
@@ -22,4 +22,4 @@ var _chunkK2UGEIT6js = require('./chunk-K2UGEIT6.js');
-exports.CanvasRenderer = _chunkK2UGEIT6js.CanvasRenderer; exports.GlyphRasterAtlas = _chunkK2UGEIT6js.GlyphRasterAtlas; exports.SVGRenderer = _chunkK2UGEIT6js.SVGRenderer; exports.TextRasterCache = _chunkK2UGEIT6js.TextRasterCache; exports.WebGPUParticleSystemManager = _chunkK2UGEIT6js.WebGPUParticleSystemManager; exports.createWebGLPointRenderer = _chunkK2UGEIT6js.createWebGLPointRenderer; exports.installRendererDevTraps = _chunkK2UGEIT6js.installRendererDevTraps; exports.isRendererDevMode = _chunkK2UGEIT6js.isRendererDevMode; exports.parseColorToRGBA = _chunkK2UGEIT6js.parseColorToRGBA; exports.setRendererDevMode = _chunkK2UGEIT6js.setRendererDevMode;
+exports.CanvasRenderer = _chunkM73XB4ZKjs.CanvasRenderer; exports.GlyphRasterAtlas = _chunkM73XB4ZKjs.GlyphRasterAtlas; exports.SVGRenderer = _chunkM73XB4ZKjs.SVGRenderer; exports.TextRasterCache = _chunkM73XB4ZKjs.TextRasterCache; exports.WebGPUParticleSystemManager = _chunkM73XB4ZKjs.WebGPUParticleSystemManager; exports.createWebGLPointRenderer = _chunkM73XB4ZKjs.createWebGLPointRenderer; exports.installRendererDevTraps = _chunkM73XB4ZKjs.installRendererDevTraps; exports.isRendererDevMode = _chunkM73XB4ZKjs.isRendererDevMode; exports.parseColorToRGBA = _chunkM73XB4ZKjs.parseColorToRGBA; exports.setRendererDevMode = _chunkM73XB4ZKjs.setRendererDevMode;

package/dist/renderer.mjs CHANGED Viewed

@@ -9,7 +9,7 @@ import {
   isRendererDevMode,
   parseColorToRGBA,
   setRendererDevMode
-} from "./chunk-TI5EMJGL.mjs";
+} from "./chunk-IFSFHYF7.mjs";
 export {
   CanvasRenderer,
   GlyphRasterAtlas,

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