@vectojs/core 1.19.0 → 1.21.0

package/dist/index.mjs

@@ -1,5 +1,6 @@
 import {
   CanvasRenderer,
+  GlyphRasterAtlas,
   SVGRenderer,
   TextRasterCache,
   WebGPUParticleSystemManager,
@@ -7,13 +8,13 @@ import {
   isSafeUrl,
   parseColorToRGBA,
   sanitizeUrl
-} from "./chunk-QS3CUV7H.mjs";
+} from "./chunk-RTENOAYT.mjs";
 import {
   Entity,
   MSDFTextEntity,
   SVGEntity,
   VectoJSEvent
-} from "./chunk-XWBVBXFZ.mjs";
+} from "./chunk-FRMLD4PP.mjs";
 
 // src/tree/Scene.ts
 import { SpringDriver, TweenDriver } from "@vectojs/animation";
@@ -1538,6 +1539,70 @@ var Scene = class _Scene {
   renderMode = "always";
   /** Cap on distinct recorded dirty reasons (see `recordDirtyReason`). */
   static MAX_DIRTY_REASONS = 200;
+  _phaseTiming = false;
+  _phaseTotals = /* @__PURE__ */ new Map();
+  /**
+   * Start or stop per-phase render timing.
+   *
+   * Off by default, and the probes compile to a single boolean test when off:
+   * these sit on the frame path, so the disabled cost has to be nothing. Enable,
+   * run the scene, then read {@link renderPhases}.
+   *
+   * Exists because a frame total cannot tell you where the time went. The
+   * markdown streaming benchmark put render at 85-99% of an append's cost, and
+   * there was no way to decompose that number further — which is exactly the
+   * position that led to two wrong optimisation guesses earlier
+   * (`CodeBlock` reuse, hit-grid fusion), both of which measured as no change.
+   */
+  setPhaseTiming(enabled) {
+    this._phaseTiming = enabled;
+    if (!enabled) this.clearRenderPhases();
+  }
+  /** Whether per-phase render timing is being recorded. */
+  get phaseTiming() {
+    return this._phaseTiming;
+  }
+  /**
+   * Accumulate one phase sample.
+   *
+   * Totals rather than a per-frame log: the question is always "which phase owns
+   * the frame", and a log of thousands of samples answers it less directly while
+   * costing far more memory. `maxMs` is kept because a phase that is cheap on
+   * average but spikes is a different problem from one that is uniformly slow.
+   */
+  _recordPhase(phase, ms) {
+    const existing = this._phaseTotals.get(phase);
+    if (existing) {
+      existing.totalMs += ms;
+      existing.calls++;
+      if (ms > existing.maxMs) existing.maxMs = ms;
+      return;
+    }
+    this._phaseTotals.set(phase, { totalMs: ms, calls: 1, maxMs: ms });
+  }
+  /**
+   * Recorded phase timings, most expensive first, with each phase's share of the
+   * measured total.
+   *
+   * `share` is the number that matters: a phase at 4% cannot be worth optimising
+   * however inefficient it looks in isolation.
+   */
+  get renderPhases() {
+    const entries = [...this._phaseTotals.entries()];
+    const denominator = entries.filter(([phase]) => phase !== "render").reduce((sum, [, v]) => sum + v.totalMs, 0);
+    return entries.map(([phase, v]) => ({
+      phase,
+      totalMs: +v.totalMs.toFixed(3),
+      calls: v.calls,
+      avgMs: +(v.totalMs / Math.max(1, v.calls)).toFixed(4),
+      maxMs: +v.maxMs.toFixed(3),
+      share: phase === "render" ? null : +(100 * v.totalMs / Math.max(1e-9, denominator)).toFixed(1)
+    })).sort((a, b) => b.totalMs - a.totalMs);
+  }
+  /** Drop recorded phase timings, keeping timing enabled. */
+  clearRenderPhases() {
+    this._phaseTotals.clear();
+  }
   _dirtyTracking = false;
   _dirtyReasons = /* @__PURE__ */ new Map();
   dirty = true;
@@ -1623,6 +1688,29 @@ var Scene = class _Scene {
   contentGridCalibrationFrames = /* @__PURE__ */ new Map();
   /** Detached, untransformed font probes used by the cold calibration pass. */
   contentGridCalibrationProbes = /* @__PURE__ */ new Map();
+  /**
+   * Monotonic stamp identifying the conditions grid cells were calibrated under.
+   *
+   * Calibration measures the difference between the advance the canvas grid assigns
+   * a cluster and the width the browser lays it out at, then writes a per-cell
+   * `scaleX`. That result stays valid until the font or the page scale changes, and
+   * it lives on the cell element — so a cell carrying this stamp needs no further
+   * work.
+   *
+   * The scan that feeds calibration was O(cells) on every revision bump: for a
+   * streaming code block it re-derived a measurement key for every cell in the
+   * block each frame in order to produce only ~20 distinct keys, costing about
+   * 2.5 ms/frame after the `style.font` fix and still over half of `a11ySync`. Since
+   * carrier reuse (#244) leaves untouched lines — and therefore their calibrated
+   * transforms — in place, cells stamped with the current generation can simply be
+   * skipped, making the scan O(new cells) instead.
+   *
+   * A plain incrementing integer rather than the descriptive calibration key,
+   * because it goes into an attribute selector and must not need escaping.
+   */
+  contentGridCalibrationGeneration = 0;
+  /** The `(fontEpoch, pageScale)` pair the current generation corresponds to. */
+  contentGridCalibrationStamp = "";
   /** Invalidates grid font calibration after browser font availability changes. */
   contentFontEpoch = 0;
   /** Cached Canvas-to-client scale for the current font/viewport epoch. */
@@ -2731,6 +2819,29 @@ var Scene = class _Scene {
     this.contentSelectionAnchor = null;
     if (this.a11yRoot) this.a11yRoot.style.pointerEvents = "none";
   }
+  /**
+   * Index of the carrier line currently holding a selection inside `el`, or
+   * `null`.
+   *
+   * Lets a partial re-materialization decide whether the user's selection is even
+   * affected. Checks the tracked anchor first (it survives a drag) and falls back
+   * to the live DOM selection.
+   */
+  contentGridSelectionLine(el) {
+    const candidates = [this.contentSelectionAnchor?.node];
+    if (typeof window !== "undefined" && typeof window.getSelection === "function") {
+      const selection = window.getSelection();
+      candidates.push(selection?.anchorNode, selection?.focusNode);
+    }
+    for (const candidate of candidates) {
+      if (!candidate || !el.contains(candidate)) continue;
+      let cursor = candidate;
+      while (cursor && cursor.parentNode !== el) cursor = cursor.parentNode;
+      const lineIndex = cursor?.dataset?.vectoGridLine;
+      if (lineIndex !== void 0) return Number(lineIndex);
+    }
+    return null;
+  }
   releaseContentSelectionForRebuild(el) {
     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);
@@ -2816,7 +2927,18 @@ var Scene = class _Scene {
     this.registerActiveDriverSubtree(entity);
     return this;
   }
-  clearContentGridState(entityId, el) {
+  /**
+   * Reset per-grid calibration and bookkeeping before a (re)materialization.
+   *
+   * @param entityId - Owning entity, keyed into the calibration maps.
+   * @param el - The projection element.
+   * @param releaseSelection - Whether to drop a selection this element owns.
+   *   Pass `false` when carrier lines are being reused: the selection's DOM nodes
+   *   survive the pass, so tearing it down would wipe a user's selection on every
+   *   streamed chunk — the exact bug `preserveContentSelectionAcrossRebuild`
+   *   exists to prevent on the non-grid path.
+   */
+  clearContentGridState(entityId, el, releaseSelection = true) {
     const calibrationFrame = this.contentGridCalibrationFrames.get(entityId);
     if (calibrationFrame !== void 0 && typeof cancelAnimationFrame === "function") {
       cancelAnimationFrame(calibrationFrame);
@@ -2832,7 +2954,21 @@ var Scene = class _Scene {
     delete el.dataset.vectoGridMaterializeMs;
     delete el.dataset.vectoGridCalibrationSamples;
     delete el.dataset.vectoGridCalibrationMs;
-    this.releaseContentSelectionForRebuild(el);
+    if (releaseSelection) this.releaseContentSelectionForRebuild(el);
+  }
+  /**
+   * Drop any projected elements under `node` without touching the entity tree.
+   *
+   * Used when the walk reaches an invisible subtree: the entities stay put (a
+   * later `show()` re-projects them), but nothing under here may remain
+   * focusable or announced while hidden.
+   */
+  pruneA11ySubtree(node) {
+    if (this.a11yElements.has(node.id) || this.contentElements.has(node.id)) {
+      this.removeA11yRecursively(node);
+      return;
+    }
+    for (const child of node.children) this.pruneA11ySubtree(child);
   }
   removeA11yRecursively(node) {
     if (node.isDOMPortal) {
@@ -3148,10 +3284,32 @@ var Scene = class _Scene {
   get overlayRootEntity() {
     return this.overlayRoot;
   }
+  /**
+   * Advance and render exactly one frame, synchronously.
+   *
+   * This renders UNCONDITIONALLY: it consults neither {@link renderMode} nor
+   * {@link dirty}, and it does not apply the `always`-mode idle auto-throttle.
+   * That is deliberate — a deterministic driver (video export, a test, a
+   * fixed-step benchmark) asks for a frame because it wants that frame, not a
+   * scheduler opinion about whether it is needed.
+   *
+   * The consequence is a measurement footgun worth stating explicitly: a
+   * benchmark that drives frames through `step()` CANNOT observe frame skipping,
+   * so `always` and `onDemand` produce byte-identical draw counts through this
+   * path. An investigation into whether `onDemand` skips redundant repaints once
+   * concluded "it does not" on exactly that basis; on the real rAF loop the same
+   * workload rendered ~1.0 frames per content change. To measure anything about
+   * scheduling, use {@link start} and let `requestAnimationFrame` drive.
+   *
+   * @param dt Seconds to advance. Not clamped by `MAX_FRAME_DT` — the caller
+   *   chooses the step, since determinism is the point.
+   */
   step(dt) {
     const time = this.lastTime + dt;
     this.lastTime = time;
+    const t0 = this._phaseTiming ? performance.now() : 0;
     this.render(this.renderer, dt, time);
+    if (this._phaseTiming) this._recordPhase("render", performance.now() - t0);
     this.dirty = false;
   }
   /**
@@ -3164,6 +3322,24 @@ var Scene = class _Scene {
     this.dirty = true;
     if (this._dirtyTracking && source) this.recordDirtyReason(source);
   }
+  /**
+   * Increments whenever the tree's shape changes: add, remove or reparent.
+   *
+   * Already maintained for the resident WASM transform store (see
+   * {@link markStructureChanged}, called from `Entity.add`/`remove`), and exposed
+   * here because a cache of the tree's shape — a DevTools tree model, a serialized
+   * snapshot — is valid exactly as long as this value is unchanged. Comparing it is
+   * O(1) against re-walking the tree, which is what it replaces: DevTools rebuilt
+   * both trees on a fixed 500 ms interval, a constant cost proportional to entity
+   * count, purely because it had no way to ask whether the shape had changed.
+   *
+   * Property changes do NOT bump it. Moving or restyling an entity leaves the
+   * shape intact, so a consumer that also cares about values must read those
+   * directly rather than rebuilding a tree.
+   */
+  get structureVersion() {
+    return this._structureVersion;
+  }
   /**
    * Record who marked the scene dirty and why.
    *
@@ -3286,6 +3462,11 @@ var Scene = class _Scene {
     if (node.isDOMPortal) {
       return;
     }
+    if (node.a11yHidden) {
+      this.pruneA11ySubtree(node);
+      return;
+    }
+    const nodeStart = this._phaseTiming ? performance.now() : 0;
     if (this.shouldProjectA11y(node)) {
       let el = this.a11yElements.get(node.id);
       const attrs = node.getA11yAttributes();
@@ -3628,7 +3809,14 @@ var Scene = class _Scene {
         if (el.style.display !== display) el.style.display = display;
       }
     }
-    this.syncContentProjection(node);
+    if (this._phaseTiming) {
+      const projectionStart = performance.now();
+      this.syncContentProjection(node);
+      this._recordPhase("contentProjection", performance.now() - projectionStart);
+      this._recordPhase("a11yNodes", projectionStart - nodeStart);
+    } else {
+      this.syncContentProjection(node);
+    }
     for (const child of node.children) this.syncA11y(child);
     if (node === this.root) {
       for (const overlay of this.overlayRoot.children) this.syncA11y(overlay);
@@ -3742,7 +3930,9 @@ var Scene = class _Scene {
       this.clearContentGridState(node.id, el);
     }
     if (projection.grid) {
+      const gridSyncStart = this._phaseTiming ? performance.now() : 0;
       this.syncContentGridProjection(node, el, projection, projection.grid);
+      if (this._phaseTiming) this._recordPhase("gridSync", performance.now() - gridSyncStart);
     } else if (lines && lines.length > 0) {
       const signature = JSON.stringify({
         lines,
@@ -3848,16 +4038,33 @@ var Scene = class _Scene {
     const signature = `${grid.revision}`;
     if (el.dataset.vectoContentGrid !== signature) {
       const materializeStart = typeof performance !== "undefined" ? performance.now() : 0;
-      this.clearContentGridState(node.id, el);
-      el.replaceChildren();
+      this.clearContentGridState(node.id, el, false);
       const projectionLines = projection.lines ?? [];
+      const selectionLine = this.contentGridSelectionLine(el);
+      let rebuiltSelectionLine = false;
+      const existingLines = el.children;
       for (let lineIndex = 0; lineIndex < grid.lines.length; lineIndex++) {
         const gridLine = grid.lines[lineIndex];
         const projectedLine = projectionLines[lineIndex];
         const lineHeight = projectedLine?.lineHeight ?? grid.lineHeight;
         const baseline = projectedLine?.baseline ?? grid.baseline;
         const lineFont = projectedLine?.font ?? grid.font;
+        const lineSignature = contentGridLineSignature(
+          grid,
+          gridLine,
+          projectedLine,
+          lineHeight,
+          baseline,
+          lineFont,
+          lineIndex === 0
+        );
+        const reusable = existingLines[lineIndex];
+        if (reusable !== void 0 && reusable.dataset.vectoGridLineSig === lineSignature && reusable.dataset.vectoGridLine === `${lineIndex}`) {
+          continue;
+        }
+        if (selectionLine !== null && selectionLine === lineIndex) rebuiltSelectionLine = true;
         const lineElement = document.createElement("span");
+        lineElement.dataset.vectoGridLineSig = lineSignature;
         lineElement.dir = "ltr";
         lineElement.dataset.vectoGridLine = `${lineIndex}`;
         lineElement.style.position = "absolute";
@@ -3899,6 +4106,8 @@ var Scene = class _Scene {
             cellElement.style.font = lineFont;
             cellElement.style.lineHeight = `${lineHeight}px`;
             cellElement.style.transformOrigin = "0 50%";
+            cellElement.dataset.vectoGridFont = lineFont;
+            cellElement.dataset.vectoGridLineHeight = `${lineHeight}px`;
             lineElement.appendChild(cellElement);
             logicalX += cell.advance;
           }
@@ -3922,13 +4131,24 @@ var Scene = class _Scene {
             lineElement.appendChild(marker);
           }
         }
-        el.appendChild(lineElement);
+        const occupant = el.children[lineIndex];
+        if (occupant) el.replaceChild(lineElement, occupant);
+        else el.appendChild(lineElement);
       }
+      while (el.children.length > grid.lines.length) {
+        if (selectionLine !== null && selectionLine >= grid.lines.length) {
+          rebuiltSelectionLine = true;
+        }
+        el.lastElementChild?.remove();
+      }
+      if (rebuiltSelectionLine) this.releaseContentSelectionForRebuild(el);
       el.dataset.vectoProjectionLines = signature;
       el.dataset.vectoContentGrid = signature;
       el.dataset.vectoGridCarriers = `${el.querySelectorAll("[data-vecto-grid-cell]").length}`;
       if (typeof performance !== "undefined") {
-        el.dataset.vectoGridMaterializeMs = `${performance.now() - materializeStart}`;
+        const materializeMs = performance.now() - materializeStart;
+        el.dataset.vectoGridMaterializeMs = `${materializeMs}`;
+        if (this._phaseTiming) this._recordPhase("gridMaterialize", materializeMs);
       }
       delete el.dataset.vectoGridCalibration;
       delete el.dataset.vectoGridReady;
@@ -3936,7 +4156,11 @@ var Scene = class _Scene {
     const pageScaleX = this.getContentMetricScaleX();
     const calibrationKey = `${signature}:${this.contentFontEpoch}:${pageScaleX.toFixed(4)}`;
     if (el.dataset.vectoGridCalibration !== calibrationKey) {
+      const calibStart = this._phaseTiming ? performance.now() : 0;
       this.scheduleContentGridCalibration(node.id, el, calibrationKey, pageScaleX);
+      if (this._phaseTiming) {
+        this._recordPhase("gridCalibrateSchedule", performance.now() - calibStart);
+      }
     }
   }
   getContentMetricScaleX() {
@@ -3954,6 +4178,27 @@ var Scene = class _Scene {
   scheduleContentGridCalibration(entityId, el, calibrationKey, pageScaleX) {
     if (typeof requestAnimationFrame !== "function") return;
     if (el.dataset.vectoGridCalibrationPending === calibrationKey) return;
+    const stamp = `${this.contentFontEpoch}:${pageScaleX.toFixed(4)}`;
+    if (this.contentGridCalibrationStamp !== stamp) {
+      this.contentGridCalibrationStamp = stamp;
+      this.contentGridCalibrationGeneration++;
+    }
+    const generation = `${this.contentGridCalibrationGeneration}`;
+    const pendingCells = el.querySelectorAll(
+      `[data-vecto-grid-cell]:not([data-vecto-grid-calib="${generation}"])`
+    );
+    if (pendingCells.length === 0) {
+      el.dataset.vectoGridCalibrationSamples = "0";
+      delete el.dataset.vectoGridCalibrationPending;
+      const readyFrame = requestAnimationFrame(() => {
+        this.contentGridCalibrationFrames.delete(entityId);
+        if (!el.isConnected) return;
+        el.dataset.vectoGridCalibration = calibrationKey;
+        el.dataset.vectoGridReady = "true";
+      });
+      this.contentGridCalibrationFrames.set(entityId, readyFrame);
+      return;
+    }
     const previous = this.contentGridCalibrationFrames.get(entityId);
     if (previous !== void 0 && typeof cancelAnimationFrame === "function") {
       cancelAnimationFrame(previous);
@@ -3984,18 +4229,22 @@ var Scene = class _Scene {
     probe.append(probeOrigin, probeX);
     const measurements = [];
     const measurementsByKey = /* @__PURE__ */ new Map();
-    for (const target of el.querySelectorAll("[data-vecto-grid-cell]")) {
+    const scanStart = this._phaseTiming ? performance.now() : 0;
+    for (const target of pendingCells) {
       const sourceLength = Number(target.dataset.vectoGridSourceLength ?? 0);
       const targetWidth = Number(target.dataset.vectoGridAdvance ?? 0);
-      if (sourceLength <= 0 || targetWidth <= 0) continue;
+      if (sourceLength <= 0 || targetWidth <= 0) {
+        target.dataset.vectoGridCalib = generation;
+        continue;
+      }
       const sourceText = target.textContent?.slice(0, sourceLength) ?? "";
-      if (!sourceText) continue;
-      const measurementKey = JSON.stringify([
-        target.style.font,
-        target.style.lineHeight,
-        targetWidth,
-        sourceText
-      ]);
+      if (!sourceText) {
+        target.dataset.vectoGridCalib = generation;
+        continue;
+      }
+      const cellFont = target.dataset.vectoGridFont ?? "";
+      const cellLineHeight = target.dataset.vectoGridLineHeight ?? "";
+      const measurementKey = JSON.stringify([cellFont, cellLineHeight, targetWidth, sourceText]);
       const shared = measurementsByKey.get(measurementKey);
       if (shared) {
         shared.targets.push(target);
@@ -4007,8 +4256,8 @@ var Scene = class _Scene {
       carrier.style.left = "0";
       carrier.style.top = "0";
       carrier.style.whiteSpace = "pre";
-      carrier.style.font = target.style.font;
-      carrier.style.lineHeight = target.style.lineHeight;
+      carrier.style.font = cellFont;
+      carrier.style.lineHeight = cellLineHeight;
       carrier.style.fontVariantLigatures = "none";
       carrier.style.fontKerning = "none";
       const source = document.createTextNode(sourceText);
@@ -4023,7 +4272,17 @@ var Scene = class _Scene {
       measurements.push(measurement);
       measurementsByKey.set(measurementKey, measurement);
     }
+    if (this._phaseTiming) this._recordPhase("calibScan", performance.now() - scanStart);
+    if (measurements.length === 0) {
+      el.dataset.vectoGridCalibration = calibrationKey;
+      el.dataset.vectoGridReady = "true";
+      el.dataset.vectoGridCalibrationSamples = "0";
+      delete el.dataset.vectoGridCalibrationPending;
+      return;
+    }
+    const appendStart = this._phaseTiming ? performance.now() : 0;
     (this.a11yRoot ?? document.body ?? document.documentElement).appendChild(probe);
+    if (this._phaseTiming) this._recordPhase("calibProbeBuild", performance.now() - appendStart);
     el.dataset.vectoGridCalibrationSamples = `${measurements.length}`;
     this.contentGridCalibrationProbes.set(entityId, probe);
     el.dataset.vectoGridCalibrationPending = calibrationKey;
@@ -4067,6 +4326,7 @@ var Scene = class _Scene {
         }
         for (const { element, scale } of updates) {
           element.style.transform = Math.abs(scale - 1) <= 1e-3 ? "" : `scaleX(${scale})`;
+          element.dataset.vectoGridCalib = generation;
         }
         el.dataset.vectoGridCalibration = calibrationKey;
         el.dataset.vectoGridReady = "true";
@@ -4372,7 +4632,9 @@ var Scene = class _Scene {
     }
     this._lastRenderTick = time;
     this._lastDt = dt;
+    const phaseClock = this._phaseTiming ? performance.now() : 0;
     this.render(this.renderer, dt, time);
+    if (this._phaseTiming) this._recordPhase("render", performance.now() - phaseClock);
     this._lastFrameMs = (typeof performance !== "undefined" ? performance.now() : time) - now;
     this._renderedFrames++;
     const hasActiveAnimation = this.frameHadAnimation;
@@ -4382,9 +4644,13 @@ var Scene = class _Scene {
     if ((hasInteractive || this.a11yElements.size > 0 || wantsContentSync) && (shouldSyncInterval || this.a11yPendingSyncAfterAnimation)) {
       this.lastA11ySync = time;
       if (hasInteractive || wantsContentSync) {
+        const t0 = this._phaseTiming ? performance.now() : 0;
         this.syncA11y(this.root);
+        if (this._phaseTiming) this._recordPhase("a11ySync", performance.now() - t0);
       }
+      const t1 = this._phaseTiming ? performance.now() : 0;
       this.enforceA11yDomOrder();
+      if (this._phaseTiming) this._recordPhase("a11yOrder", performance.now() - t1);
       this.a11yPendingSyncAfterAnimation = hasActiveAnimation;
     } else if (hasActiveAnimation) {
       this.a11yPendingSyncAfterAnimation = true;
@@ -4558,7 +4824,9 @@ var Scene = class _Scene {
       updateWalk(this.root);
       for (const overlay of this.overlayRoot.children) updateWalk(overlay);
     }
+    const wasmT0 = this._phaseTiming ? performance.now() : 0;
     const wasmWorld = wasmMain ? this._syncWasmStore() : null;
+    if (this._phaseTiming) this._recordPhase("transform", performance.now() - wasmT0);
     const wasmSlotEntity = this._slotEntity;
     const renderNode = (node, pa, pb, pc, pd, pe, pf, parentOpacity) => {
       if (isMainRenderer && !wasmMain) {
@@ -4688,7 +4956,13 @@ var Scene = class _Scene {
             );
           }
         } else {
-          node.render(renderer);
+          if (this._phaseTiming) {
+            const t0 = performance.now();
+            node.render(renderer);
+            this._recordPhase("entityPaint", performance.now() - t0);
+          } else {
+            node.render(renderer);
+          }
         }
       }
       if (node.clipChildren) {
@@ -4700,20 +4974,24 @@ var Scene = class _Scene {
       renderer.flush();
       renderer.restore();
     };
+    const drawT0 = this._phaseTiming ? performance.now() : 0;
     renderNode(this.root, 1, 0, 0, 1, 0, 0, 1);
     for (const overlay of this.overlayRoot.children) {
       renderNode(overlay, 1, 0, 0, 1, 0, 0, 1);
     }
+    if (this._phaseTiming) this._recordPhase("drawWalk", performance.now() - drawT0);
     if (isMainRenderer) {
       this.frameHadAnimation = walkHadAnimation;
       this.frameHadInteractive = walkHadInteractive;
       this.reconcilePortals();
     }
+    const flushT0 = this._phaseTiming ? performance.now() : 0;
     renderer.flush();
     if (isMainRenderer) {
       this.pointRenderer?.flush();
     }
     renderer.present?.();
+    if (this._phaseTiming) this._recordPhase("flush", performance.now() - flushT0);
     if (this._devActive) {
       this._devFrameCount++;
       this._devRunChecks();
@@ -4989,6 +5267,41 @@ function intersectBounds(a, b) {
 function pointInBounds(b, x, y) {
   return x >= b.x && x <= b.x + b.width && y >= b.y && y <= b.y + b.height;
 }
+function contentGridLineSignature(grid, line, projected, lineHeight, baseline, font, isFirstLine) {
+  const parts = [
+    // Line box: position, size, and the font that resolves its baseline.
+    `${projected?.x ?? 0}`,
+    `${projected?.y ?? ""}`,
+    `${lineHeight}`,
+    `${baseline}`,
+    font,
+    `${line.width}`,
+    // The trailing hard break belongs to this line and lands in the DOM text.
+    grid.source.slice(line.sourceEnd, line.nextSourceStart),
+    // The basis markers are appended only to line 0, so a line moving to or from
+    // index 0 changes its DOM even when nothing else does.
+    isFirstLine ? "1" : "0"
+  ];
+  if (line.cells.length === 0) {
+    parts.push("empty");
+  } else {
+    for (const cell of line.cells) {
+      parts.push(
+        `${cell.sourceStart}`,
+        `${cell.sourceEnd}`,
+        `${cell.x}`,
+        `${cell.advance}`,
+        `${cell.level}`,
+        cell.sourceCaretOffsets.join("."),
+        // Source text, not `cell.glyph`: the carrier holds the original characters
+        // (the shaped glyph is the canvas's business), so a change in shaping alone
+        // must not invalidate a carrier, and a change in source must.
+        grid.source.slice(cell.sourceStart, cell.sourceEnd)
+      );
+    }
+  }
+  return parts.join("
");
+}
 
 // src/components/TextEntity.ts
 import {
@@ -5757,6 +6070,7 @@ export {
   ComputeParticleEntity,
   DOMPortalEntity,
   Entity,
+  GlyphRasterAtlas,
   GridTextEntity,
   Group,
   MSDFTextEntity,

package/dist/renderer/CanvasRenderer.d.ts

@@ -111,6 +111,8 @@ export declare class CanvasRenderer implements IRenderer {
     /** @inheritdoc */
     drawImage(source: CanvasImageSource, dx: number, dy: number, dw: number, dh: number): void;
     /** @inheritdoc */
+    drawImageRect(source: CanvasImageSource, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number): void;
+    /** @inheritdoc */
     fillCircle(cx: number, cy: number, radius: number, color: string, alpha?: number): void;
     /** @inheritdoc */
     flush(): void;