@vectojs/core 1.30.0 → 1.32.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,8 @@ var SCENE_OPTION_KEYS = [
   "autoThrottle",
   "contentProjection",
   "contentProjectionMargin",
+  "contentSemanticBudget",
+  "contentSemanticMargin",
   "debugA11y",
   "disableWindowResize",
   "maxDPR",
@@ -1431,6 +1433,7 @@ function parseInlinePx(value) {
   const n = parseFloat(value);
   return Number.isFinite(n) && n > 0 ? n : null;
 }
+var DEFAULT_CONTENT_SEMANTIC_BUDGET = 256;
 function projectionGridLineWindow(grid, projectionLines, band) {
   const count = grid.lines.length;
   const all = { start: 0, end: count, gated: false };
@@ -1956,6 +1959,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 +2001,49 @@ 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;
+  // How many coarse-tier blocks may be MATERIALIZED per sync, spreading the
+  // resident tier's document-open cost across frames. `Infinity` = one
+  // synchronous pass.
+  contentSemanticBudget = DEFAULT_CONTENT_SEMANTIC_BUDGET;
+  // Remaining materializations in the CURRENT sync. Reset at the start of each
+  // a11y walk; decremented per coarse block that creates its element.
+  contentSemanticBudgetLeft = 0;
+  // Set when a sync deferred at least one block, so the scene knows to keep
+  // drawing frames until the resident tier is complete. Without it a static
+  // scene in `onDemand` mode would stop rendering with the document half
+  // materialized and never finish.
+  contentSemanticDeferred = false;
+  /**
+   * Per-sync memo of "does the document hold a selection at all".
+   *
+   * Reading ANY property of a `Selection` (`anchorNode`, `rangeCount`, `type`,
+   * `isCollapsed`) forces a synchronous layout, because Blink validates the
+   * selection against current box geometry before answering. Measured in real
+   * Chrome against a 1000-carrier subtree with layout dirtied between reads:
+   * `anchorNode` 0.5ms, `rangeCount` 0.4ms, `type` 0.5ms, `isCollapsed` 0.5ms —
+   * all indistinguishable from `offsetHeight` (0.5ms), against a 0ms floor for
+   * mutating without reading. So there is no cheap property to probe with; the
+   * only way to avoid the layout is to not touch the object at all.
+   *
+   * Materializing a block rebuilds its carriers, which asks whether the rebuild
+   * would destroy a selection. Once per block, that read cost a forced layout
+   * over the whole (and growing) projection subtree, which is what made
+   * per-block cost rise with resident count: profiled at 1973 forced layouts
+   * totalling 633ms of an 847ms 1000-block drain (75%).
+   *
+   * A selection is a single document-wide object and a sync walk cannot yield to
+   * the user, so its presence cannot change mid-walk. Resolving it once per walk
+   * turns O(blocks) forced layouts into O(1). `null` = not yet resolved.
+   */
+  contentSelectionPresentThisSync = null;
   /**
    * 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 +3079,8 @@ var Scene = class _Scene {
     this.a11ySyncInterval = options.a11ySyncInterval ?? 0;
     this.contentProjectionEnabled = options.contentProjection ?? true;
     this.contentProjectionMargin = options.contentProjectionMargin;
+    this.contentSemanticMargin = options.contentSemanticMargin;
+    this.contentSemanticBudget = options.contentSemanticBudget ?? DEFAULT_CONTENT_SEMANTIC_BUDGET;
     this.readingDirection = options.readingDirection ?? "ltr";
     this.renderMode = options.renderMode ?? "always";
     this._devActive = _Scene._devModeDetected();
@@ -3308,12 +3362,31 @@ var Scene = class _Scene {
     }
     return null;
   }
+  /**
+   * Does the document hold a selection right now, memoized for this sync walk?
+   *
+   * Pays one forced layout per walk instead of one per rebuilt element — see
+   * {@link Scene.contentSelectionPresentThisSync} for the measurements. When the
+   * answer is `false` no element can own a selection, so every per-element
+   * ownership test can be skipped without touching the object.
+   */
+  contentSelectionPresent() {
+    if (this.contentSelectionPresentThisSync !== null) {
+      return this.contentSelectionPresentThisSync;
+    }
+    const selection = typeof window !== "undefined" && typeof window.getSelection === "function" ? window.getSelection() : null;
+    const present = !!selection && (!!selection.anchorNode || !!selection.focusNode);
+    this.contentSelectionPresentThisSync = present;
+    return present;
+  }
   releaseContentSelectionForRebuild(el) {
+    if (!this.contentSelectionAnchor && !this.contentSelectionPresent()) return;
     const selection = typeof window !== "undefined" && typeof window.getSelection === "function" ? window.getSelection() : null;
     const ownsSelection = this.contentSelectionAnchor && el.contains(this.contentSelectionAnchor.node) || (selection?.anchorNode ? el.contains(selection.anchorNode) : false) || (selection?.focusNode ? el.contains(selection.focusNode) : false);
     if (!ownsSelection) return;
     this.endContentSelectionDrag();
     selection?.removeAllRanges();
+    this.contentSelectionPresentThisSync = null;
   }
   /**
    * Rebuild a content-projection element's DOM (`rebuild`) while preserving a
@@ -3331,6 +3404,10 @@ var Scene = class _Scene {
    * restore against).
    */
   preserveContentSelectionAcrossRebuild(el, rebuild) {
+    if (!this.contentSelectionAnchor && !this.contentSelectionPresent()) {
+      rebuild();
+      return;
+    }
     const selection = typeof window !== "undefined" && typeof window.getSelection === "function" ? window.getSelection() : null;
     const owns = !!selection && !this.blankRegionSelectionDrag && ((selection.anchorNode ? el.contains(selection.anchorNode) : false) || (selection.focusNode ? el.contains(selection.focusNode) : false));
     if (!owns || !selection.anchorNode || !selection.focusNode) {
@@ -3449,6 +3526,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 +3671,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);
@@ -4024,6 +4103,11 @@ var Scene = class _Scene {
   }
   syncA11y(node, container = null) {
     if (!this.a11yRoot) return;
+    if (node === this.root) {
+      this.contentSemanticBudgetLeft = this.contentSemanticBudget;
+      this.contentSemanticDeferred = false;
+      this.contentSelectionPresentThisSync = null;
+    }
     if (node.isDOMPortal) {
       return;
     }
@@ -4442,7 +4526,9 @@ var Scene = class _Scene {
    * transparent DOM node positioned over the drawn glyphs. Runs on the a11y
    * sync cadence; all writes are dirty-checked. Off-viewport projections are
    * hidden (`display: none`) so text-heavy scenes only materialize what is
-   * visible to the browser's text machinery anyway.
+   * visible to the browser's text machinery anyway — except in the coarse
+   * (resident) tier, which stays displayed because hiding it would make its text
+   * unfindable and remove it from the accessibility tree, defeating the tier.
    */
   /**
    * Whether `node`'s world-space box, expanded by `margin` px on every side,
@@ -4451,8 +4537,15 @@ var Scene = class _Scene {
    * at `margin = contentProjectionMargin`) and for the exact `display:none`
    * visibility test (`margin = 0`). Boundless nodes (width/height 0) opt out of
    * culling and always count as visible, matching the legacy behavior.
+   *
+   * `viewportOnly` skips the `clipChildren` ancestor walk, answering the narrower
+   * question "does this box overlap the viewport at all". The coarse content tier
+   * needs the two apart: text that is merely off-viewport is clipped by
+   * `a11yRoot`'s own `overflow: hidden` and can safely stay displayed, while text
+   * rejected by an ancestor clip box that itself overlaps the viewport would sit
+   * transparently on top of whatever is really drawn there.
    */
-  projectionBoxVisible(node, tf, margin) {
+  projectionBoxVisible(node, tf, margin, viewportOnly = false) {
     if (!(node.width > 0 && node.height > 0)) return true;
     const { a, b, c, d, e, f } = tf;
     const worldCorners = [];
@@ -4474,6 +4567,7 @@ var Scene = class _Scene {
     if (!(maxX >= -margin && minX <= this.width + margin && maxY >= -margin && minY <= this.height + margin)) {
       return false;
     }
+    if (viewportOnly) return true;
     for (let ancestor = node.parent; ancestor; ancestor = ancestor.parent) {
       if (!ancestor.clipChildren || ancestor.width <= 0 || ancestor.height <= 0) continue;
       let localMinX = Infinity;
@@ -4555,14 +4649,31 @@ 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;
+      }
+    }
+    if (tier === "coarse" && !el && this.contentSemanticBudgetLeft <= 0) {
+      this.contentSemanticDeferred = true;
+      return;
+    }
     const projection = node.getContentProjection(
       lineBand ? { minY: lineBand.minY, maxY: lineBand.maxY } : void 0
     );
@@ -4571,6 +4682,7 @@ var Scene = class _Scene {
       return;
     }
     if (!el) {
+      if (tier === "coarse") this.contentSemanticBudgetLeft--;
       el = document.createElement("div");
       el.setAttribute("data-vecto-content", node.id);
       const s = el.style;
@@ -4595,14 +4707,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 +4778,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 +4817,30 @@ 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";
+    const residentTier = semanticMargin > interactionMargin;
+    const display = visible || residentTier && !this.projectionBoxVisible(node, worldTf, 0, true) ? "" : "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
@@ -5325,7 +5461,7 @@ var Scene = class _Scene {
     if (!this.isRunning) return;
     if (!this._canvasOnScreen) return;
     let cap = this.effectiveMaxFPS();
-    const isIdle = !this.dirty && !this.frameHadAnimation;
+    const isIdle = !this.dirty && !this.frameHadAnimation && !this.contentSemanticDeferred;
     if (isIdle && this.autoThrottle && this.renderMode === "always" && this.maxFPS > 0) {
       cap = Math.min(cap, 2);
     }
@@ -6107,6 +6243,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 +6265,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 +6314,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;
@@ -6850,6 +6992,7 @@ export {
   CanvasRenderer,
   Circle,
   ComputeParticleEntity,
+  DEFAULT_CONTENT_SEMANTIC_BUDGET,
   DOMPortalEntity,
   Entity,
   GlyphRasterAtlas,

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,64 @@ 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 unbudgeted at 21.3ms for 1000 blocks and 139.5ms
+     * for 10000 on Chrome — 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. That stall is what
+     * {@link SceneOptions.contentSemanticBudget} spreads across frames.
+     *
+     * Default: whatever `contentProjectionMargin` resolves to, so omitting this
+     * leaves behaviour unchanged.
+     */
+    contentSemanticMargin?: number;
+    /**
+     * How many resident (coarse-tier) blocks may be materialized in **one** sync,
+     * bounding the document-open stall a wide {@link
+     * SceneOptions.contentSemanticMargin} otherwise pays all at once.
+     *
+     * The cost of a resident tier is per node **created**, not per node held: 10000
+     * resident blocks cost ~3.0 ms/sync at steady state, while creating them costs
+     * ~0.03 ms each plus a per-pass floor that grows with how many are already
+     * resident. So the front-load is a *scheduling* problem, and this is the
+     * schedule — remaining blocks materialize on subsequent syncs, a few per frame,
+     * until the document is fully resident.
+     *
+     * What it does **not** change is the end state: the same blocks end up with the
+     * same DOM, only later. Nothing is dropped, so the reachability the semantic
+     * tier exists for is preserved; a block still waiting is simply not yet in the
+     * DOM, exactly as a block beyond the margin is not.
+     *
+     * Applies **only** to the coarse tier. A block inside the interaction margin is
+     * on screen and materializes immediately regardless of this budget — deferring
+     * visible text would make it briefly unselectable, which is a user-visible
+     * regression rather than a cost saving.
+     *
+     * `Infinity` disables the budget and restores one synchronous pass. Default:
+     * {@link DEFAULT_CONTENT_SEMANTIC_BUDGET}. Because the coarse tier exists only
+     * when `contentSemanticMargin` is wider than `contentProjectionMargin`, a scene
+     * that does not opt into a resident tier has no coarse blocks and is therefore
+     * unaffected by any value here.
+     */
+    contentSemanticBudget?: number;
     /**
      * Reading direction used to order the accessibility/automation shadow tree so
      * keyboard **tab order** and screen-reader traversal follow the *visual*
@@ -240,7 +298,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', 'contentSemanticBudget', '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;
 /**
@@ -331,6 +389,45 @@ export interface A11yTreeNode {
     valuemax?: string;
     children: A11yTreeNode[];
 }
+/**
+ * Default {@link SceneOptions.contentSemanticBudget}: resident blocks
+ * materialized per sync.
+ *
+ * Sized against the two costs a pass actually pays, both measured in real headed
+ * Chrome on a 240Hz panel. Per created block is cheap and flat (~0.03ms). What
+ * dominates is style+layout of the projection subtree, which scales with how many
+ * blocks are already RESIDENT and is paid once per pass: traced at 10000 blocks,
+ * `UpdateLayoutTree` 391.7ms + `Layout` 305.8ms over 40 passes (~17ms each), with
+ * per-pass cost roughly doubling from the first pass to the last while the number
+ * created stayed constant.
+ *
+ * So total drain cost is approximately `passes × f(resident)`, and a SMALLER
+ * budget multiplies the term that does not shrink. Measured to completion, 3
+ * repeats, medians:
+ *
+ * ```text
+ *  1000 blocks   budget  32 →   67.1ms total,  4.3ms worst pass
+ *                budget  64 →   54.0ms total,  5.1ms worst pass
+ *                budget 256 →   27.7ms total,  7.7ms worst pass
+ *                Infinity   →   24.1ms total, 23.6ms worst pass
+ * 10000 blocks   budget  32 → 3773.2ms total, 42.6ms worst pass
+ *                budget  64 → 1896.2ms total, 41.6ms worst pass
+ *                budget 256 →  648.1ms total, 35.2ms worst pass
+ *                Infinity   →  319.4ms total, 307.3ms worst pass
+ * ```
+ *
+ * 256 is where the two goals stop trading against each other. Below it there is no
+ * frame-bound improvement at 10000 blocks — every budget lands at 35-43ms, because
+ * the worst pass is the LAST one laying out the complete subtree — while total time
+ * rises 6x. At 1000 blocks it still holds 7.7ms, inside a 60Hz frame, for less than
+ * half the total time of 64.
+ *
+ * This replaces an earlier default of 64, which was sized against a per-block cost
+ * of ~0.4ms. That figure was inflated by a forced layout per materialized block
+ * (see `contentSelectionPresentThisSync`); with that removed, 64 spends 6x the
+ * total time for no frame-bound gain.
+ */
+export declare const DEFAULT_CONTENT_SEMANTIC_BUDGET = 256;
 /**
  * Top-level orchestrator that owns the entity tree, drive the render loop,
  * and maintains the accessibility/automation shadow layer.
@@ -488,6 +585,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 +628,33 @@ export declare class Scene {
     private contentMetricScaleX;
     private contentProjectionEnabled;
     private contentProjectionMargin;
+    private contentSemanticMargin;
+    private contentSemanticBudget;
+    private contentSemanticBudgetLeft;
+    private contentSemanticDeferred;
+    /**
+     * Per-sync memo of "does the document hold a selection at all".
+     *
+     * Reading ANY property of a `Selection` (`anchorNode`, `rangeCount`, `type`,
+     * `isCollapsed`) forces a synchronous layout, because Blink validates the
+     * selection against current box geometry before answering. Measured in real
+     * Chrome against a 1000-carrier subtree with layout dirtied between reads:
+     * `anchorNode` 0.5ms, `rangeCount` 0.4ms, `type` 0.5ms, `isCollapsed` 0.5ms —
+     * all indistinguishable from `offsetHeight` (0.5ms), against a 0ms floor for
+     * mutating without reading. So there is no cheap property to probe with; the
+     * only way to avoid the layout is to not touch the object at all.
+     *
+     * Materializing a block rebuilds its carriers, which asks whether the rebuild
+     * would destroy a selection. Once per block, that read cost a forced layout
+     * over the whole (and growing) projection subtree, which is what made
+     * per-block cost rise with resident count: profiled at 1973 forced layouts
+     * totalling 633ms of an 847ms 1000-block drain (75%).
+     *
+     * A selection is a single document-wide object and a sync walk cannot yield to
+     * the user, so its presence cannot change mid-walk. Resolving it once per walk
+     * turns O(blocks) forced layouts into O(1). `null` = not yet resolved.
+     */
+    private contentSelectionPresentThisSync;
     /**
      * 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
@@ -1063,6 +1196,15 @@ export declare class Scene {
      * to the live DOM selection.
      */
     private contentGridSelectionLine;
+    /**
+     * Does the document hold a selection right now, memoized for this sync walk?
+     *
+     * Pays one forced layout per walk instead of one per rebuilt element — see
+     * {@link Scene.contentSelectionPresentThisSync} for the measurements. When the
+     * answer is `false` no element can own a selection, so every per-element
+     * ownership test can be skipped without touching the object.
+     */
+    private contentSelectionPresent;
     private releaseContentSelectionForRebuild;
     /**
      * Rebuild a content-projection element's DOM (`rebuild`) while preserving a
@@ -1390,7 +1532,9 @@ export declare class Scene {
      * transparent DOM node positioned over the drawn glyphs. Runs on the a11y
      * sync cadence; all writes are dirty-checked. Off-viewport projections are
      * hidden (`display: none`) so text-heavy scenes only materialize what is
-     * visible to the browser's text machinery anyway.
+     * visible to the browser's text machinery anyway — except in the coarse
+     * (resident) tier, which stays displayed because hiding it would make its text
+     * unfindable and remove it from the accessibility tree, defeating the tier.
      */
     /**
      * Whether `node`'s world-space box, expanded by `margin` px on every side,
@@ -1399,6 +1543,13 @@ export declare class Scene {
      * at `margin = contentProjectionMargin`) and for the exact `display:none`
      * visibility test (`margin = 0`). Boundless nodes (width/height 0) opt out of
      * culling and always count as visible, matching the legacy behavior.
+     *
+     * `viewportOnly` skips the `clipChildren` ancestor walk, answering the narrower
+     * question "does this box overlap the viewport at all". The coarse content tier
+     * needs the two apart: text that is merely off-viewport is clipped by
+     * `a11yRoot`'s own `overflow: hidden` and can safely stay displayed, while text
+     * rejected by an ancestor clip box that itself overlaps the viewport would sit
+     * transparently on top of whatever is really drawn there.
      */
     private projectionBoxVisible;
     /**

package/package.json

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