@vectojs/core 1.20.0 → 1.22.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-UPULSLKA.mjs";
 import {
   Entity,
   MSDFTextEntity,
   SVGEntity,
   VectoJSEvent
-} from "./chunk-TJCXB2F6.mjs";
+} from "./chunk-FRMLD4PP.mjs";
 
 // src/tree/Scene.ts
 import { SpringDriver, TweenDriver } from "@vectojs/animation";
@@ -1687,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. */
@@ -2438,6 +2462,27 @@ var Scene = class _Scene {
   get webgpuDisabled() {
     return this._webgpuDisabled || this.particleBackend === "cpu";
   }
+  /**
+   * Draw accounting for the WebGL point layer, or null when that layer is not in
+   * use.
+   *
+   * Null and all-zero mean different things: null is "this backend is not
+   * running", zero is "it ran and drew nothing". A readout that conflates them
+   * sends someone looking for a performance problem in a backend that was never
+   * active.
+   */
+  get webglDrawStats() {
+    return this.pointRenderer?.stats?.() ?? null;
+  }
+  /**
+   * Whether a WebGPU device is currently live for particle compute.
+   *
+   * The WebGPU path only activates when a `ComputeParticleEntity` is present, so
+   * most scenes never touch it.
+   */
+  get webgpuActive() {
+    return this.device !== null && !this.deviceLost;
+  }
   set webgpuDisabled(value) {
     this._webgpuDisabled = value;
   }
@@ -2795,6 +2840,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);
@@ -2880,7 +2948,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);
@@ -2896,7 +2975,7 @@ 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.
@@ -3226,6 +3305,26 @@ 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;
@@ -3244,6 +3343,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.
    *
@@ -3370,6 +3487,7 @@ var Scene = class _Scene {
       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();
@@ -3712,7 +3830,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);
@@ -3826,7 +3951,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,
@@ -3932,16 +4059,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";
@@ -3983,6 +4127,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;
           }
@@ -4006,13 +4152,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;
@@ -4020,7 +4177,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() {
@@ -4038,6 +4199,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);
@@ -4068,18 +4250,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);
@@ -4091,8 +4277,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);
@@ -4107,7 +4293,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;
@@ -4151,6 +4347,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";
@@ -5091,6 +5288,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 {
@@ -5859,6 +6091,7 @@ export {
   ComputeParticleEntity,
   DOMPortalEntity,
   Entity,
+  GlyphRasterAtlas,
   GridTextEntity,
   Group,
   MSDFTextEntity,

package/dist/renderer/CanvasRenderer.d.ts

@@ -1,4 +1,4 @@
-import { IRenderer } from './IRenderer';
+import { type DrawCounters, IRenderer } from './IRenderer';
 export declare class CanvasRenderer implements IRenderer {
     private ctx;
     private width;
@@ -33,6 +33,17 @@ export declare class CanvasRenderer implements IRenderer {
     private batchCount;
     private _cachedFont;
     private _cachedFill;
+    /** Backend discriminator; see {@link IRenderer.kind}. */
+    readonly kind = "canvas2d";
+    /**
+     * Draw counters, allocated only once counting is enabled.
+     *
+     * Null when off, so the guard on every op is a single null test and an inactive
+     * renderer carries no counter object at all.
+     */
+    private counters;
+    /** Accumulated primitive area, kept separately so the ratio is derived on read. */
+    private drawnArea;
     /**
      * @param canvas - The target canvas. Its backing store is resized to the
      *   logical size × devicePixelRatio.
@@ -79,6 +90,12 @@ export declare class CanvasRenderer implements IRenderer {
      *  restored). The owner skips its render pass while this is true. */
     isContextLost(): boolean;
     /** @inheritdoc */
+    /** @inheritdoc */
+    setDrawCounters(enabled: boolean): void;
+    /** @inheritdoc */
+    getDrawCounters(): DrawCounters | null;
+    /** @inheritdoc */
+    clearDrawCounters(): void;
     clear(): void;
     /** @inheritdoc */
     save(): void;
@@ -111,6 +128,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;

package/dist/renderer/GlyphRasterAtlas.d.ts

@@ -0,0 +1,186 @@
+/**
+ * A texture atlas of rasterized glyphs, for grids that draw the *same small set
+ * of glyphs* thousands of times per frame.
+ *
+ * Named `GlyphRasterAtlas` rather than `GlyphAtlas` because `@vectojs/layout`
+ * already exports a `GlyphAtlas` interface — a map of grapheme to *vector* path
+ * metrics — and the core barrel re-exports that package, so the shorter name is a
+ * hard collision. The distinction is also worth keeping: that one holds path data
+ * for measuring, this one holds pixels for blitting.
+ *
+ * ## Why this exists alongside {@link TextRasterCache}
+ *
+ * Both replace per-cell `fillText` with a bitmap blit. The difference is where
+ * the pixels live, and measurement says that difference decides whether the idea
+ * works at all.
+ *
+ * `TextRasterCache` allocates **one canvas per cached run**. A warm cache for a
+ * syntax-highlighted code grid holds a few hundred of them (glyphs x theme
+ * colours), so a frame blits from a few hundred distinct source textures and the
+ * GPU re-binds on nearly every call. Measured on real hardware, that per-source
+ * cost is invisible at 2k cells and dominant at 40k: Chrome went 1.82x at 2k to
+ * **0.87x at 40k** — slower than the `fillText` it replaced. Its per-call cost
+ * grows with cell count (1.22 -> 2.89 us) rather than staying flat.
+ *
+ * This atlas keeps every glyph in **one** canvas and selects with a source rect,
+ * so the source texture never changes. Same call count, same pixels, same
+ * geometry — and per-call cost is flat as the grid grows (Chrome 1.10 -> 1.11
+ * us), giving **1.90-2.27x over `fillText` on both engines at every size**.
+ * Full data: `vectojs-docs/forge/baselines/raster-cache-findings.md`.
+ *
+ * The win comes from *reuse*, so this is for bounded glyph sets: a monospace code
+ * grid, a terminal, a data grid, a numeric HUD. Prose is the wrong customer —
+ * every run is distinct, so an atlas is pure overhead (use `RichText`'s coalesced
+ * runs there instead).
+ *
+ * ## Requires a source-rect blit
+ *
+ * Selecting one slot needs {@link IRenderer.drawImageRect}, which is optional:
+ * `CanvasRenderer` implements it, `SVGRenderer` deliberately does not (an SVG
+ * blit embeds its source as a data URL, so a per-cell sub-rect would inline the
+ * whole atlas thousands of times — and vector text is the correct output for a
+ * vector export anyway). Callers must keep their `fillText` path for renderers
+ * that lack it:
+ *
+ * ```ts
+ * const slot = atlas.get(font, color, glyph);
+ * if (slot && r.drawImageRect) {
+ *   r.drawImageRect(atlas.source, slot.sx, slot.sy, slot.sw, slot.sh,
+ *                   x - slot.offsetX, baselineY - slot.offsetY, slot.w, slot.h);
+ * } else {
+ *   r.fillText(glyph, x, baselineY, font, color);
+ * }
+ * ```
+ */
+/** Where one glyph lives in the atlas, and how to blit it at a baseline. */
+export interface GlyphSlot {
+    /** Source X in atlas *device* pixels. */
+    sx: number;
+    /** Source Y in atlas *device* pixels. */
+    sy: number;
+    /** Source width in atlas *device* pixels. */
+    sw: number;
+    /** Source height in atlas *device* pixels. */
+    sh: number;
+    /** Destination width in CSS pixels. */
+    w: number;
+    /** Destination height in CSS pixels. */
+    h: number;
+    /** Left inset (CSS px) of the glyph origin inside the slot. */
+    offsetX: number;
+    /** Distance (CSS px) from the slot top down to the text baseline. */
+    offsetY: number;
+    /** The cluster these pixels represent. */
+    glyph: string;
+    /** The CSS font shorthand these pixels were rasterized with. */
+    font: string;
+    /** Advance width (CSS px) of the cluster, i.e. `measureText().width`. */
+    advance: number;
+    /**
+     * Ink extent left of the glyph origin (CSS px), from `actualBoundingBoxLeft`.
+     *
+     * Carried on the slot so a blit can be mapped back to the same geometry a
+     * `fillText` would have produced. Without it, instrumentation that traces draw
+     * calls to verify grid positioning (`e2e/text-projection.e2e.ts`) can see only
+     * a destination rect and cannot recover where the glyph origin sat inside it.
+     */
+    left: number;
+    /** Ink extent right of the glyph origin (CSS px), from `actualBoundingBoxRight`. */
+    right: number;
+}
+/** Instrumentation counters, e.g. to surface a HUD hit rate. */
+export interface GlyphRasterAtlasStats {
+    /** Requests served from an existing slot. */
+    hits: number;
+    /** Requests that had to rasterize. */
+    misses: number;
+    /** Glyphs currently resident. */
+    size: number;
+    /**
+     * Times the atlas filled up and was reset.
+     *
+     * Steady-state thrash means the glyph set is unbounded for the configured
+     * size, and the atlas is doing net harm — every reset re-rasterizes everything.
+     * A caller that watches this can fall back to `fillText` permanently.
+     */
+    resets: number;
+}
+/** Options for {@link GlyphRasterAtlas}. */
+export interface GlyphRasterAtlasOptions {
+    /**
+     * Device-pixel-ratio to rasterize at. Slots record device pixels while `w`/`h`
+     * stay in CSS pixels, so the blit is DPR-correct without caller arithmetic.
+     * Default `1`.
+     */
+    dpr?: number;
+    /**
+     * Max atlas edge in device pixels, capped at 8192 — comfortably inside the
+     * lowest common `maxTextureSize` while leaving room for thousands of glyphs.
+     * Exceeding a browser's real limit yields a silently blank canvas, so this is
+     * clamped rather than trusted. Default `2048`.
+     */
+    maxSize?: number;
+}
+/**
+ * A glyph atlas. Create one per renderer/scene — instances share no state, so
+ * multiple scenes or an SSR pass never collide.
+ */
+export declare class GlyphRasterAtlas {
+    private readonly slots;
+    private readonly dpr;
+    private readonly maxSize;
+    private canvas;
+    private ctx;
+    /**
+     * Shelf packing: glyphs land left-to-right on a row, then a new row starts.
+     * A monospace grid produces near-uniform widths, so shelves waste very little
+     * and cost one comparison per insert — a real 2D packer would buy nothing here.
+     */
+    private penX;
+    private penY;
+    private rowHeight;
+    private _hits;
+    private _misses;
+    private _resets;
+    constructor(options?: GlyphRasterAtlasOptions);
+    /** Live instrumentation snapshot. */
+    get stats(): GlyphRasterAtlasStats;
+    /**
+     * The atlas canvas, to pass as the blit source.
+     *
+     * `null` until the first successful {@link get}, and in any non-DOM context.
+     */
+    get source(): HTMLCanvasElement | null;
+    private ensureCanvas;
+    /**
+     * Look up a glyph, rasterizing it into the atlas on first request.
+     *
+     * @param font - Full CSS `font` shorthand, used for measuring and painting.
+     * @param color - CSS color baked into the pixels.
+     * @param glyph - A single grapheme cluster. Long strings are rejected
+     *   (`null`): they defeat the atlas's fixed-slot packing and belong in
+     *   `fillText` or {@link TextRasterCache}.
+     * @returns The slot, or `null` when the caller must fall back to `fillText`
+     *   (headless, unrasterizable, or too large to pack).
+     */
+    get(font: string, color: string, glyph: string): GlyphSlot | null;
+    /**
+     * Find the slot occupying a source position, or `null`.
+     *
+     * The inverse of {@link get}: it maps a blit back to the glyph it drew. Exists
+     * for instrumentation — a test or devtool that traces `drawImage` calls sees
+     * only a source rect, and needs this to recover which cluster was painted and
+     * with what metrics. Linear over resident slots, so it is a diagnostic, not a
+     * per-frame call.
+     */
+    slotAt(sx: number, sy: number): GlyphSlot | null;
+    /**
+     * Drop every glyph and reuse the canvas.
+     *
+     * Call after a font or theme change: slots are keyed by `(font, color, glyph)`
+     * so stale entries are never *returned* wrongly, but they do occupy space.
+     */
+    reset(): void;
+    /** Release the backing canvas and all slots. */
+    destroy(): void;
+}