@vectojs/core 1.31.0 → 1.32.1

package/dist/index.mjs

@@ -1379,6 +1379,7 @@ var SCENE_OPTION_KEYS = [
   "autoThrottle",
   "contentProjection",
   "contentProjectionMargin",
+  "contentSemanticBudget",
   "contentSemanticMargin",
   "debugA11y",
   "disableWindowResize",
@@ -1432,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 };
@@ -2007,6 +2009,41 @@ var Scene = class _Scene {
   // 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
@@ -2074,6 +2111,16 @@ var Scene = class _Scene {
    * see {@link sortNormalElementsVisually}.
    */
   a11yOrderContainers = /* @__PURE__ */ new Set();
+  /**
+   * Nearest `clipChildren` ancestor per ordered element — its *region* — reused
+   * per pass. Written by `enforceA11yDomOrder`'s collect walk, which already has
+   * the entity in hand, so a region costs one comparison per node rather than an
+   * ancestor walk per element.
+   *
+   * Absent means the element sits under no clipping ancestor and belongs to the
+   * implicit root region. See {@link sortNormalElementsVisually}.
+   */
+  a11yOrderRegions = /* @__PURE__ */ new Map();
   activePortalsThisFrame = /* @__PURE__ */ new Set();
   activePortalsPrevFrame = /* @__PURE__ */ new Set();
   portalEntities = /* @__PURE__ */ new Map();
@@ -3043,6 +3090,7 @@ var Scene = class _Scene {
     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();
@@ -3324,12 +3372,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
@@ -3347,6 +3414,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) {
@@ -4042,6 +4113,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;
     }
@@ -4460,7 +4536,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,
@@ -4469,8 +4547,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 = [];
@@ -4492,6 +4577,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;
@@ -4594,6 +4680,10 @@ var Scene = class _Scene {
         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
     );
@@ -4602,6 +4692,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;
@@ -4736,7 +4827,8 @@ 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 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;
@@ -5087,12 +5179,14 @@ var Scene = class _Scene {
     this.fullViewportElements.length = 0;
     this.normalElements.length = 0;
     this.activeIds.clear();
-    const collect = (node) => {
+    this.a11yOrderRegions.clear();
+    const collect = (node, region) => {
       if (node.isDOMPortal) return;
       const contentEl = this.contentElements.get(node.id);
       if (contentEl) {
         if (node.a11yFullViewport) this.fullViewportElements.push(contentEl);
         else this.normalElements.push(contentEl);
+        if (region) this.a11yOrderRegions.set(contentEl, region);
       }
       if (this.shouldProjectA11y(node)) {
         const el = this.a11yElements.get(node.id);
@@ -5100,14 +5194,16 @@ var Scene = class _Scene {
           this.activeIds.add(node.id);
           if (node.a11yFullViewport) this.fullViewportElements.push(el);
           else this.normalElements.push(el);
+          if (region) this.a11yOrderRegions.set(el, region);
         }
       }
-      for (const child of node.children) collect(child);
+      const childRegion = node.clipChildren && node.width > 0 && node.height > 0 ? node : region;
+      for (const child of node.children) collect(child, childRegion);
       if (node === this.root) {
-        for (const overlay of this.overlayRoot.children) collect(overlay);
+        for (const overlay of this.overlayRoot.children) collect(overlay, null);
       }
     };
-    collect(this.root);
+    collect(this.root, null);
     let elementsPruned = false;
     for (const [id, el] of this.a11yElements.entries()) {
       if (!this.activeIds.has(id)) {
@@ -5169,6 +5265,18 @@ var Scene = class _Scene {
    * parents, which no `insertBefore` ever acts on. Normalizing everything back
    * to world coordinates here would cost a transform per element per frame to
    * change nothing observable.
+   *
+   * Banding runs **per region** — per nearest `clipChildren` ancestor, recorded
+   * by {@link enforceA11yDomOrder}'s collect walk — rather than once over the
+   * whole scene. Purely visual banding is right for a screen reader but wrong
+   * for selection: a DOM `Selection` covers everything between anchor and focus
+   * in DOM order, so under one global banding a vertical drag through a
+   * transcript also swallowed a sidebar whose headings happened to fall in the
+   * same rows. Regions are laid out side by side, so ordering region-major keeps
+   * each one a contiguous DOM run and a drag stays inside it, while reading
+   * order *within* a region is unchanged. Regions are emitted in the order their
+   * clipper is first reached by the depth-first walk, so a screen reader still
+   * meets them in the author's declared order.
    */
   sortNormalElementsVisually() {
     const els = this.normalElements;
@@ -5196,30 +5304,40 @@ var Scene = class _Scene {
       }
       return { top, left };
     };
-    const order = els.map((el, i) => {
+    const decorated = els.map((el, i) => {
       const { top, left } = absolute(el);
       return { el, i, top, left, container: containers.has(el) };
     });
-    order.sort((p, q) => p.top - q.top || p.i - q.i);
+    const regions = this.a11yOrderRegions;
+    const buckets = /* @__PURE__ */ new Map();
+    for (const d of decorated) {
+      const key = regions.get(d.el) ?? null;
+      const bucket = buckets.get(key);
+      if (bucket) bucket.push(d);
+      else buckets.set(key, [d]);
+    }
     const bandBottom = (r) => r.top + (r.container ? 4 : heightOf(r.el));
     const sorted = [];
-    let rowStart = 0;
-    let rowBottom = order.length ? bandBottom(order[0]) : 0;
-    const flushRow = (end) => {
-      const row = order.slice(rowStart, end);
-      row.sort((p, q) => (rtl ? q.left - p.left : p.left - q.left) || p.i - q.i);
-      for (const r of row) sorted.push(r.el);
-    };
-    for (let k = 1; k < order.length; k++) {
-      if (order[k].top < rowBottom) {
-        rowBottom = Math.max(rowBottom, bandBottom(order[k]));
-      } else {
-        flushRow(k);
-        rowStart = k;
-        rowBottom = bandBottom(order[k]);
+    for (const order of buckets.values()) {
+      order.sort((p, q) => p.top - q.top || p.i - q.i);
+      let rowStart = 0;
+      let rowBottom = order.length ? bandBottom(order[0]) : 0;
+      const flushRow = (end) => {
+        const row = order.slice(rowStart, end);
+        row.sort((p, q) => (rtl ? q.left - p.left : p.left - q.left) || p.i - q.i);
+        for (const r of row) sorted.push(r.el);
+      };
+      for (let k = 1; k < order.length; k++) {
+        if (order[k].top < rowBottom) {
+          rowBottom = Math.max(rowBottom, bandBottom(order[k]));
+        } else {
+          flushRow(k);
+          rowStart = k;
+          rowBottom = bandBottom(order[k]);
+        }
       }
+      flushRow(order.length);
     }
-    flushRow(order.length);
     for (let i = 0; i < sorted.length; i++) els[i] = sorted[i];
   }
   /** Keep DOM/WebGL overlay layers aligned with the canvas's CSS box. */
@@ -5379,7 +5497,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);
     }
@@ -6910,6 +7028,7 @@ export {
   CanvasRenderer,
   Circle,
   ComputeParticleEntity,
+  DEFAULT_CONTENT_SEMANTIC_BUDGET,
   DOMPortalEntity,
   Entity,
   GlyphRasterAtlas,

package/dist/tree/Scene.d.ts

@@ -220,15 +220,45 @@ export interface SceneOptions {
      * 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
+     * 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.
+     * 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*
@@ -268,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', 'contentSemanticMargin', '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;
 /**
@@ -359,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.
@@ -560,6 +629,32 @@ export declare class Scene {
     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
@@ -624,6 +719,16 @@ export declare class Scene {
      * see {@link sortNormalElementsVisually}.
      */
     private a11yOrderContainers;
+    /**
+     * Nearest `clipChildren` ancestor per ordered element — its *region* — reused
+     * per pass. Written by `enforceA11yDomOrder`'s collect walk, which already has
+     * the entity in hand, so a region costs one comparison per node rather than an
+     * ancestor walk per element.
+     *
+     * Absent means the element sits under no clipping ancestor and belongs to the
+     * implicit root region. See {@link sortNormalElementsVisually}.
+     */
+    private a11yOrderRegions;
     private activePortalsThisFrame;
     private activePortalsPrevFrame;
     private portalEntities;
@@ -1101,6 +1206,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
@@ -1428,7 +1542,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,
@@ -1437,6 +1553,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;
     /**
@@ -1496,6 +1619,18 @@ export declare class Scene {
      * parents, which no `insertBefore` ever acts on. Normalizing everything back
      * to world coordinates here would cost a transform per element per frame to
      * change nothing observable.
+     *
+     * Banding runs **per region** — per nearest `clipChildren` ancestor, recorded
+     * by {@link enforceA11yDomOrder}'s collect walk — rather than once over the
+     * whole scene. Purely visual banding is right for a screen reader but wrong
+     * for selection: a DOM `Selection` covers everything between anchor and focus
+     * in DOM order, so under one global banding a vertical drag through a
+     * transcript also swallowed a sidebar whose headings happened to fall in the
+     * same rows. Regions are laid out side by side, so ordering region-major keeps
+     * each one a contiguous DOM run and a drag stays inside it, while reading
+     * order *within* a region is unchanged. Regions are emitted in the order their
+     * clipper is first reached by the depth-first walk, so a screen reader still
+     * meets them in the author's declared order.
      */
     private sortNormalElementsVisually;
     /** Keep DOM/WebGL overlay layers aligned with the canvas's CSS box. */

package/package.json

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