@vectojs/core 1.30.0 → 1.31.0

package/dist/index.mjs

@@ -18,7 +18,7 @@ import {
   SVGEntity,
   VectoJSEvent,
   contentLineInHint
-} from "./chunk-2WXZCPYQ.mjs";
+} from "./chunk-RWN3ITBD.mjs";
 
 // src/tree/Scene.ts
 import { SpringDriver, TweenDriver } from "@vectojs/animation";
@@ -1379,6 +1379,7 @@ var SCENE_OPTION_KEYS = [
   "autoThrottle",
   "contentProjection",
   "contentProjectionMargin",
+  "contentSemanticMargin",
   "debugA11y",
   "disableWindowResize",
   "maxDPR",
@@ -1956,6 +1957,15 @@ var Scene = class _Scene {
   a11yElements = /* @__PURE__ */ new Map();
   /** DOM nodes mirroring static text content, keyed by entity id. */
   contentElements = /* @__PURE__ */ new Map();
+  /**
+   * What the last completed content-projection sync was built from, per entity.
+   *
+   * Compared at the top of {@link syncContentProjection} to skip a block whose
+   * content AND geometry are both unchanged, before the O(glyphs) projection
+   * build. Only populated for entities that opt in via
+   * {@link Entity.getContentEpoch}. (carryctx CTX-0199)
+   */
+  contentSyncState = /* @__PURE__ */ new Map();
   /** Pending cold font-calibration frame per projected grid entity. */
   contentGridCalibrationFrames = /* @__PURE__ */ new Map();
   /** Detached, untransformed font probes used by the cold calibration pass. */
@@ -1989,9 +1999,14 @@ var Scene = class _Scene {
   contentMetricScaleEpoch = -1;
   contentMetricScaleX = 1;
   contentProjectionEnabled = true;
-  // Virtualization margin (px) for content projection; `undefined` → one
-  // viewport height, resolved at sync time. `Infinity` = materialize everything.
+  // Virtualization margin (px) for the content-projection CARRIER band;
+  // `undefined` → one viewport height, resolved at sync time. `Infinity` is
+  // unsupported here: it unwindows every carrier, which is O(total glyphs).
   contentProjectionMargin = void 0;
+  // Virtualization margin (px) for the SEMANTIC tier — whether a block has
+  // any projected DOM. `undefined` → falls back to contentProjectionMargin, so
+  // the default keeps one gate. `Infinity` = every block keeps resident text.
+  contentSemanticMargin = void 0;
   /**
    * True while a text-selection drag that started on a projection's blank
    * region (no text node under the press) is being driven manually — the
@@ -3027,6 +3042,7 @@ var Scene = class _Scene {
     this.a11ySyncInterval = options.a11ySyncInterval ?? 0;
     this.contentProjectionEnabled = options.contentProjection ?? true;
     this.contentProjectionMargin = options.contentProjectionMargin;
+    this.contentSemanticMargin = options.contentSemanticMargin;
     this.readingDirection = options.readingDirection ?? "ltr";
     this.renderMode = options.renderMode ?? "always";
     this._devActive = _Scene._devModeDetected();
@@ -3449,6 +3465,7 @@ var Scene = class _Scene {
       this.clearContentGridState(node.id, contentEl);
       contentEl.remove();
       this.contentElements.delete(node.id);
+      this.contentSyncState.delete(node.id);
       this.a11yNeedsReorder = true;
     }
     const el = this.a11yElements.get(node.id);
@@ -3593,6 +3610,7 @@ var Scene = class _Scene {
     this.a11yElements.clear();
     for (const el of this.contentElements.values()) el.remove();
     this.contentElements.clear();
+    this.contentSyncState.clear();
     if (typeof cancelAnimationFrame === "function") {
       for (const frame of this.contentGridCalibrationFrames.values()) {
         cancelAnimationFrame(frame);
@@ -4555,14 +4573,27 @@ var Scene = class _Scene {
         this.contentElements.delete(node.id);
         this.a11yNeedsReorder = true;
       }
+      this.contentSyncState.delete(node.id);
     };
     const worldTf = node.getWorldTransform();
-    const margin = this.contentProjectionMargin ?? this.height;
-    if (Number.isFinite(margin) && !this.projectionBoxVisible(node, worldTf, margin)) {
+    const interactionMargin = this.contentProjectionMargin ?? this.height;
+    const semanticMargin = this.contentSemanticMargin ?? interactionMargin;
+    if (Number.isFinite(semanticMargin) && !this.projectionBoxVisible(node, worldTf, semanticMargin)) {
       releaseProjectionEl();
       return;
     }
-    const lineBand = Number.isFinite(margin) ? this.projectionVisibleLocalYBand(node, worldTf, margin) : null;
+    const inInteractionBand = !Number.isFinite(interactionMargin) || this.projectionBoxVisible(node, worldTf, interactionMargin);
+    const tier = inInteractionBand ? "fine" : "coarse";
+    const lineBand = tier === "coarse" ? null : Number.isFinite(interactionMargin) ? this.projectionVisibleLocalYBand(node, worldTf, interactionMargin) : null;
+    const visible = this.projectionBoxVisible(node, worldTf, 0);
+    const epoch = node.getContentEpoch();
+    const prior = this.contentSyncState.get(node.id);
+    if (epoch !== null && el && prior !== void 0) {
+      const { a: a2, b: b2, c: c2, d: d2, e: e2, f: f2 } = worldTf;
+      if (prior.epoch === epoch && prior.fontEpoch === this.contentFontEpoch && prior.a === a2 && prior.b === b2 && prior.c === c2 && prior.d === d2 && prior.e === e2 && prior.f === f2 && prior.tier === tier && prior.hasBand === (lineBand !== null) && (lineBand === null || prior.bandMin === lineBand.minY && prior.bandMax === lineBand.maxY) && prior.visible === visible && prior.width === node.width && prior.height === node.height && prior.interactive === node.interactive) {
+        return;
+      }
+    }
     const projection = node.getContentProjection(
       lineBand ? { minY: lineBand.minY, maxY: lineBand.maxY } : void 0
     );
@@ -4595,14 +4626,15 @@ var Scene = class _Scene {
       this.a11yNeedsReorder = true;
     }
     const lines = projection.lines;
-    if (!projection.grid && el.dataset.vectoContentGrid !== void 0) {
+    const useCarriers = tier === "fine";
+    if ((!projection.grid || !useCarriers) && el.dataset.vectoContentGrid !== void 0) {
       this.clearContentGridState(node.id, el);
     }
-    if (projection.grid) {
+    if (projection.grid && useCarriers) {
       const gridSyncStart = this._phaseTiming ? performance.now() : 0;
       this.syncContentGridProjection(node, el, projection, projection.grid, lineBand);
       if (this._phaseTiming) this._recordPhase("gridSync", performance.now() - gridSyncStart);
-    } else if (lines && lines.length > 0) {
+    } else if (useCarriers && lines && lines.length > 0) {
       const lineWindow = projectionLineWindow(lines, lineBand, projection.lineHeight ?? 16);
       const signature = JSON.stringify({
         lines,
@@ -4665,11 +4697,13 @@ var Scene = class _Scene {
         }
       }
     } else {
-      if (el.textContent !== projection.text) {
+      const demoted = tier === "coarse" && el.children.length > 0;
+      if (el.textContent !== projection.text || demoted) {
         this.releaseContentSelectionForRebuild(el);
         el.textContent = projection.text;
       }
       delete el.dataset.vectoProjectionLines;
+      if (tier === "coarse") delete el.dataset.vectoProjectionWindow;
     }
     const font = projection.font ?? "";
     if (el.style.font !== font) el.style.font = font;
@@ -4702,9 +4736,29 @@ var Scene = class _Scene {
     if (node.width > 0) el.style.width = `${node.width}px`;
     if (node.height > 0) el.style.height = `${node.height}px`;
     el.style.transform = `matrix(${a}, ${b}, ${c}, ${d}, 0, 0)`;
-    const visible = this.projectionBoxVisible(node, worldTf, 0);
     const display = visible ? "" : "none";
     if (el.style.display !== display) el.style.display = display;
+    if (epoch !== null) {
+      const { a: a2, b: b2, c: c2, d: d2, e: e2, f: f2 } = worldTf;
+      const next = prior ?? {};
+      next.epoch = epoch;
+      next.fontEpoch = this.contentFontEpoch;
+      next.a = a2;
+      next.b = b2;
+      next.c = c2;
+      next.d = d2;
+      next.e = e2;
+      next.f = f2;
+      next.tier = tier;
+      next.hasBand = lineBand !== null;
+      next.bandMin = lineBand?.minY ?? 0;
+      next.bandMax = lineBand?.maxY ?? 0;
+      next.visible = visible;
+      next.width = node.width;
+      next.height = node.height;
+      next.interactive = node.interactive;
+      if (prior === void 0) this.contentSyncState.set(node.id, next);
+    }
   }
   /**
    * Materialize a prepared grid in logical source order while positioning each
@@ -6107,6 +6161,8 @@ var TextEntity = class extends Entity {
   hoveredFillStyle = "#ffffff";
   lineWidth = 1;
   isHovered = false;
+  /** Bumped by {@link applyLayout}; read by `Scene` to skip an unchanged sync. */
+  contentEpoch = 0;
   constructor(text, atlas, maxWidth, fontSize = 24) {
     super();
     this.text = text;
@@ -6127,6 +6183,9 @@ var TextEntity = class extends Entity {
     if (!this.text) return null;
     return { text: this.text, font: `${this.fontSize}px sans-serif` };
   }
+  getContentEpoch() {
+    return this.contentEpoch;
+  }
   /**
    * Replace the text content. Runs the **cold** measurement pass (re-segment +
    * re-measure) since the glyphs changed, then re-lays out.
@@ -6173,6 +6232,7 @@ var TextEntity = class extends Entity {
   }
   /** Hot pass: place the cached {@link PreparedText} and refresh the a11y box. */
   applyLayout() {
+    this.contentEpoch++;
     const result = this.layout.layoutPrepared(this.prepared);
     this.nodes = result.nodes;
     this.width = result.totalWidth;

package/dist/text/MSDFTextEntity.d.ts

@@ -34,6 +34,8 @@ export declare class MSDFTextEntity extends Entity {
     private layoutText;
     private text;
     private lastRenderedSeqId;
+    /** Bumped by {@link queueLayout}; read by `Scene` to skip an unchanged sync. */
+    private contentEpoch;
     private atlasDecodeTarget;
     private atlasDecodeHandler;
     private rgbColorCache;
@@ -91,6 +93,7 @@ export declare class MSDFTextEntity extends Entity {
      * readers, crawlers, and translation see the same string the canvas draws.
      */
     getContentProjection(): ContentProjection | null;
+    getContentEpoch(): number;
     isPointInside(globalX: number, globalY: number): boolean;
     render(renderer: any): void;
     destroy(): void;

package/dist/text.js

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

package/dist/text.mjs

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

package/dist/tree/Entity.d.ts

@@ -1000,6 +1000,32 @@ export declare abstract class Entity {
      * @returns The projection descriptor, or `null` to project nothing.
      */
     getContentProjection(hint?: ContentProjectionHint): ContentProjection | 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(): number | 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

@@ -201,6 +201,34 @@ export interface SceneOptions {
      * height (`undefined` → resolved to `Scene.height` at sync time).
      */
     contentProjectionMargin?: number;
+    /**
+     * Virtualization margin (px) for the *semantic* tier of content projection —
+     * whether a block has **any** projected DOM at all, as opposed to
+     * {@link SceneOptions.contentProjectionMargin}, which decides whether that
+     * block's per-line **carriers** are windowed.
+     *
+     * Splitting the two makes a coarse resident tier expressible: with
+     * `contentSemanticMargin: Infinity` and a finite `contentProjectionMargin`,
+     * every block in the document keeps an element holding its full text — so
+     * find-in-page and screen-reader read-ahead see the whole document — while
+     * only blocks near the viewport pay for per-line carriers. One scalar could
+     * not express that, because a finite value freed off-band blocks entirely and
+     * `Infinity` also unwindowed every carrier, which is O(total document glyphs).
+     *
+     * `Infinity` is safe **here** and remains unsupported for
+     * `contentProjectionMargin`: the cost that made it unsupported comes from an
+     * unwindowed carrier band, not from resident text.
+     *
+     * Note the one-time cost. A resident tier materializes one element per block
+     * on the first sync — measured ~13µs per node created, so ~20ms at 1000 blocks
+     * and ~146ms at 10000 — as one synchronous block. Steady state is cheap
+     * (unchanged blocks skip via {@link Entity.getContentEpoch}), so this is a
+     * document-open stall, not a per-frame cost.
+     *
+     * Default: whatever `contentProjectionMargin` resolves to, so omitting this
+     * leaves behaviour unchanged.
+     */
+    contentSemanticMargin?: number;
     /**
      * Reading direction used to order the accessibility/automation shadow tree so
      * keyboard **tab order** and screen-reader traversal follow the *visual*
@@ -240,7 +268,7 @@ export interface SceneOptions {
  * against. A new option must be added here too — the test suite asserts the two
  * stay in sync.
  */
-export declare const SCENE_OPTION_KEYS: readonly ['a11ySyncInterval', 'autoThrottle', 'contentProjection', 'contentProjectionMargin', 'debugA11y', 'disableWindowResize', 'maxDPR', 'maxFPS', 'particleBackend', 'pointBackend', 'readingDirection', 'renderer', 'renderMode', 'respectReducedMotion', 'userTiming'];
+export declare const SCENE_OPTION_KEYS: readonly ['a11ySyncInterval', 'autoThrottle', 'contentProjection', 'contentProjectionMargin', 'contentSemanticMargin', 'debugA11y', 'disableWindowResize', 'maxDPR', 'maxFPS', 'particleBackend', 'pointBackend', 'readingDirection', 'renderer', 'renderMode', 'respectReducedMotion', 'userTiming'];
 /** Frame-rate the loop is capped to when the OS requests reduced motion. */
 export declare const REDUCED_MOTION_FPS = 30;
 /**
@@ -488,6 +516,15 @@ export declare class Scene {
     private a11yElements;
     /** DOM nodes mirroring static text content, keyed by entity id. */
     private contentElements;
+    /**
+     * What the last completed content-projection sync was built from, per entity.
+     *
+     * Compared at the top of {@link syncContentProjection} to skip a block whose
+     * content AND geometry are both unchanged, before the O(glyphs) projection
+     * build. Only populated for entities that opt in via
+     * {@link Entity.getContentEpoch}. (carryctx CTX-0199)
+     */
+    private contentSyncState;
     /** Pending cold font-calibration frame per projected grid entity. */
     private contentGridCalibrationFrames;
     /** Detached, untransformed font probes used by the cold calibration pass. */
@@ -522,6 +559,7 @@ export declare class Scene {
     private contentMetricScaleX;
     private contentProjectionEnabled;
     private contentProjectionMargin;
+    private contentSemanticMargin;
     /**
      * True while a text-selection drag that started on a projection's blank
      * region (no text node under the press) is being driven manually — the

package/package.json

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