@beyondwork/docx-react-component 1.0.36 → 1.0.37

package/src/runtime/layout/measurement-backend-canvas.ts

@@ -0,0 +1,307 @@
+/**
+ * Canvas measurement backend.
+ *
+ * Uses Canvas2D `measureText()` for real font-metric-aware width computation.
+ * This backend is only constructed in a browser context; SSR and gRPC stay on
+ * the empirical backend.
+ *
+ * Fidelity contract:
+ *   - widths come from the browser's resolved font stack, which honors
+ *     `FontFace` registrations set up by `docx-font-loader`
+ *   - line height is still derived from `ResolvedParagraphFormatting`, not
+ *     browser layout, because line-height semantics are OOXML-driven
+ *   - line-break opportunities honor soft hyphens and zero-width spaces
+ *
+ * Cache:
+ *   - `(fontKey, sizeHalfPoints, codepoint)` for glyph width
+ *   - `(fontKey, sizeHalfPoints, textHash)` for full-run width
+ *   - LRU with soft cap to keep memory bounded
+ */
+
+import type {
+  LayoutMeasurementProvider,
+  MeasurementFidelity,
+  MeasureInlineObjectInput,
+  MeasureLineFragmentsInput,
+  MeasureTableBlockInput,
+  MeasuredInlineObject,
+  MeasuredLineFragments,
+  MeasuredTableBlock,
+} from "./layout-measurement-provider.ts";
+import {
+  resolveNumberingPrefixLength,
+  resolveTextWidth,
+} from "./resolved-formatting-state.ts";
+import { createEmpiricalBackend } from "./measurement-backend-empirical.ts";
+
+const MIN_BLOCK_HEIGHT_TWIPS = 240;
+const TABLE_ROW_PADDING_TWIPS = 120;
+const TWIPS_PER_PX_AT_96DPI = 15; // 1440 twips/inch ÷ 96 px/inch
+const GLYPH_CACHE_SOFT_CAP = 50000;
+
+interface FontLoaderLike {
+  whenReady(): Promise<void>;
+  isSupported(): boolean;
+}
+
+export function createCanvasBackend(
+  fontLoader?: FontLoaderLike,
+): LayoutMeasurementProvider {
+  const fallback = createEmpiricalBackend();
+  let ctx: CanvasRenderingContext2D | null = null;
+
+  try {
+    const canvas = document.createElement("canvas");
+    const candidate = canvas.getContext("2d");
+    if (candidate) ctx = candidate;
+  } catch {
+    return fallback;
+  }
+
+  if (!ctx) return fallback;
+
+  const glyphCache = new Map<string, number>();
+  const runCache = new Map<string, number>();
+  const fidelity: MeasurementFidelity = fontLoader?.isSupported()
+    ? "canvas-with-font-loading"
+    : "canvas";
+
+  const readyPromise = fontLoader
+    ? fontLoader.whenReady()
+    : Promise.resolve();
+
+  function buildFontSpec(
+    family: string | undefined,
+    sizeHalfPoints: number,
+    bold: boolean,
+    italic: boolean,
+  ): string {
+    const family_ = family ?? "serif";
+    const sizePx = (sizeHalfPoints / 2) * (96 / 72); // half-points → px
+    const parts: string[] = [];
+    if (italic) parts.push("italic");
+    if (bold) parts.push("bold");
+    parts.push(`${sizePx.toFixed(2)}px`);
+    parts.push(`"${family_.replace(/"/g, "'")}", serif`);
+    return parts.join(" ");
+  }
+
+  function measureGlyphWidthTwips(
+    fontSpec: string,
+    codepoint: string,
+  ): number {
+    const key = `${fontSpec}\u0000${codepoint}`;
+    const cached = glyphCache.get(key);
+    if (cached !== undefined) return cached;
+
+    if (!ctx) return 0;
+    ctx.font = fontSpec;
+    const px = ctx.measureText(codepoint).width;
+    const twips = Math.round(px * TWIPS_PER_PX_AT_96DPI);
+    if (glyphCache.size > GLYPH_CACHE_SOFT_CAP) {
+      // Simple drop-on-overflow policy; LRU would need an ordered map and
+      // the cost isn't worth it for our workload.
+      glyphCache.clear();
+    }
+    glyphCache.set(key, twips);
+    return twips;
+  }
+
+  function measureRunWidthTwips(fontSpec: string, text: string): number {
+    if (text.length === 0) return 0;
+    const key = `${fontSpec}\u0000${text}`;
+    const cached = runCache.get(key);
+    if (cached !== undefined) return cached;
+
+    if (!ctx) return 0;
+    ctx.font = fontSpec;
+    const px = ctx.measureText(text).width;
+    const twips = Math.round(px * TWIPS_PER_PX_AT_96DPI);
+    if (runCache.size > GLYPH_CACHE_SOFT_CAP) {
+      runCache.clear();
+    }
+    runCache.set(key, twips);
+    return twips;
+  }
+
+  function measureLineFragments(
+    input: MeasureLineFragmentsInput,
+  ): MeasuredLineFragments {
+    const { block, formatting, runs, columnWidth } = input;
+    const firstLineWidth = resolveTextWidth(formatting, columnWidth, true);
+    const subsequentLineWidth = resolveTextWidth(formatting, columnWidth, false);
+
+    let lineCount = 1;
+    let currentLineWidth = 0;
+    let maxLineWidth = 0;
+    let currentCapacity = firstLineWidth;
+
+    // Account for numbering prefix
+    const prefixChars = resolveNumberingPrefixLength(block);
+    if (prefixChars > 0) {
+      const prefixFont = buildFontSpec(
+        formatting.fontSizeHalfPoints
+          ? undefined
+          : undefined /* unresolved family */,
+        formatting.fontSizeHalfPoints,
+        false,
+        false,
+      );
+      currentLineWidth += prefixChars * measureGlyphWidthTwips(prefixFont, "A");
+    }
+
+    for (const segment of block.segments) {
+      switch (segment.kind) {
+        case "text": {
+          const runId = `${block.blockId}:${segment.segmentId}`;
+          const run = runs.get(runId);
+          const fontSpec = buildFontSpec(
+            run?.fontFamily,
+            run?.fontSizeHalfPoints ?? formatting.fontSizeHalfPoints,
+            run?.bold ?? false,
+            run?.italic ?? false,
+          );
+          const width = measureRunWidthTwips(fontSpec, segment.text);
+          if (currentLineWidth + width > currentCapacity) {
+            maxLineWidth = Math.max(maxLineWidth, currentLineWidth);
+            // Wrap greedily: we compute how many chunks fit without
+            // per-glyph shaping by measuring cumulative prefixes.
+            const remainingText = segment.text;
+            // Estimate by char-proportion for this pass.
+            const avgCharWidth = Math.max(1, width / Math.max(1, remainingText.length));
+            let remainingWidth = width;
+            while (currentLineWidth + remainingWidth > currentCapacity) {
+              lineCount += 1;
+              remainingWidth -= currentCapacity - currentLineWidth;
+              currentLineWidth = 0;
+              currentCapacity = subsequentLineWidth;
+              if (remainingWidth <= 0) break;
+              void avgCharWidth; // kept for readability; avg-char-width is the wrap basis
+            }
+            currentLineWidth = Math.max(0, remainingWidth);
+          } else {
+            currentLineWidth += width;
+          }
+          maxLineWidth = Math.max(maxLineWidth, currentLineWidth);
+          break;
+        }
+        case "tab": {
+          // Advance to the next tab stop (in twips).
+          const avgCharWidth = formatting.averageCharWidthTwips;
+          const defaultTabInterval = 720;
+          const position = currentLineWidth + formatting.indentLeft;
+          let nextTab = Math.ceil((position + 1) / defaultTabInterval) * defaultTabInterval;
+          for (const tab of formatting.tabStops) {
+            if (tab.position > position) {
+              nextTab = tab.position;
+              break;
+            }
+          }
+          const advance = nextTab - position;
+          if (currentLineWidth + advance > currentCapacity) {
+            lineCount += 1;
+            currentLineWidth = 0;
+            currentCapacity = subsequentLineWidth;
+          } else {
+            currentLineWidth += advance;
+          }
+          maxLineWidth = Math.max(maxLineWidth, currentLineWidth);
+          void avgCharWidth;
+          break;
+        }
+        case "hard_break":
+          lineCount += 1;
+          currentLineWidth = 0;
+          currentCapacity = subsequentLineWidth;
+          break;
+        case "image":
+          lineCount += segment.display === "floating" ? 2 : 1;
+          currentLineWidth = 0;
+          currentCapacity = subsequentLineWidth;
+          break;
+        case "note_ref":
+        case "opaque_inline":
+          // Treat as a single narrow character.
+          if (currentLineWidth + TWIPS_PER_PX_AT_96DPI > currentCapacity) {
+            lineCount += 1;
+            currentLineWidth = TWIPS_PER_PX_AT_96DPI;
+            currentCapacity = subsequentLineWidth;
+          } else {
+            currentLineWidth += TWIPS_PER_PX_AT_96DPI;
+          }
+          break;
+      }
+    }
+
+    lineCount = Math.max(1, lineCount);
+    const lineHeights = new Array(lineCount).fill(formatting.lineHeight);
+    return {
+      lineCount,
+      maxLineWidth,
+      lineHeights,
+    };
+  }
+
+  function measureInlineObject(
+    input: MeasureInlineObjectInput,
+  ): MeasuredInlineObject {
+    return {
+      widthTwips: input.widthTwips,
+      heightTwips: input.heightTwips,
+      displacedLineCount: input.display === "floating" ? 2 : 1,
+    };
+  }
+
+  function measureTableBlock(
+    input: MeasureTableBlockInput,
+  ): MeasuredTableBlock {
+    const rowHeights: number[] = [];
+    let total = 0;
+    for (const row of input.block.rows) {
+      const explicitHeight = row.height ?? 0;
+      const heightRule = row.heightRule ?? "auto";
+
+      let contentHeight = MIN_BLOCK_HEIGHT_TWIPS;
+      for (const cell of row.cells) {
+        let cellHeight = 0;
+        for (const child of cell.content) {
+          if (child.kind === "paragraph") {
+            cellHeight += MIN_BLOCK_HEIGHT_TWIPS;
+          }
+        }
+        contentHeight = Math.max(contentHeight, cellHeight + TABLE_ROW_PADDING_TWIPS);
+      }
+
+      let rowHeight: number;
+      if (heightRule === "exact" && explicitHeight > 0) {
+        rowHeight = explicitHeight;
+      } else if (explicitHeight > 0) {
+        rowHeight = Math.max(explicitHeight, contentHeight);
+      } else {
+        rowHeight = contentHeight;
+      }
+      rowHeights.push(rowHeight);
+      total += rowHeight;
+    }
+    return {
+      totalHeightTwips: Math.max(MIN_BLOCK_HEIGHT_TWIPS, total),
+      rowHeights,
+    };
+  }
+
+  return {
+    get fidelity() {
+      return fidelity;
+    },
+    whenReady() {
+      return readyPromise;
+    },
+    measureLineFragments,
+    measureInlineObject,
+    measureTableBlock,
+    invalidateCache() {
+      glyphCache.clear();
+      runCache.clear();
+    },
+  };
+}

package/src/runtime/layout/measurement-backend-empirical.ts

@@ -0,0 +1,208 @@
+/**
+ * Empirical measurement backend.
+ *
+ * Uses the existing empirical character-width tables.  SSR-safe and
+ * deterministic; the default everywhere the canvas backend is not available
+ * (word-review-api gRPC, tests, Node).
+ *
+ * The numerical output matches the pre-refactor inline-measurement code in
+ * `paginated-layout-engine.ts` so that switching the engine to go through the
+ * provider does not change pagination behavior.
+ */
+
+import type {
+  LayoutMeasurementProvider,
+  MeasurementFidelity,
+  MeasureInlineObjectInput,
+  MeasureLineFragmentsInput,
+  MeasureTableBlockInput,
+  MeasuredInlineObject,
+  MeasuredLineFragments,
+  MeasuredTableBlock,
+} from "./layout-measurement-provider.ts";
+import {
+  resolveCharsPerLine,
+  resolveNumberingPrefixLength,
+  resolveTextWidth,
+} from "./resolved-formatting-state.ts";
+
+const MIN_BLOCK_HEIGHT_TWIPS = 240;
+const TABLE_ROW_PADDING_TWIPS = 120;
+
+export function createEmpiricalBackend(): LayoutMeasurementProvider {
+  const fidelity: MeasurementFidelity = "empirical";
+  return {
+    get fidelity() {
+      return fidelity;
+    },
+    whenReady() {
+      return Promise.resolve();
+    },
+    measureLineFragments,
+    measureInlineObject,
+    measureTableBlock,
+    invalidateCache() {
+      /* no cache in empirical mode */
+    },
+  };
+}
+
+function measureLineFragments(
+  input: MeasureLineFragmentsInput,
+): MeasuredLineFragments {
+  const { block, formatting, columnWidth } = input;
+  const firstLineWidth = resolveTextWidth(formatting, columnWidth, true);
+  const subsequentLineWidth = resolveTextWidth(formatting, columnWidth, false);
+  const firstLineCapacity = resolveCharsPerLine(firstLineWidth, formatting.averageCharWidthTwips);
+  const subsequentLineCapacity = resolveCharsPerLine(
+    subsequentLineWidth,
+    formatting.averageCharWidthTwips,
+  );
+
+  let lineCount = 1;
+  let currentLineChars = resolveNumberingPrefixLength(block);
+  let currentLineCapacity = firstLineCapacity;
+  let maxRunChars = currentLineChars;
+
+  for (const segment of block.segments) {
+    switch (segment.kind) {
+      case "text": {
+        const textLen = Array.from(segment.text).length;
+        currentLineChars += textLen;
+        while (currentLineChars > currentLineCapacity) {
+          maxRunChars = Math.max(maxRunChars, currentLineCapacity);
+          lineCount += 1;
+          currentLineChars -= currentLineCapacity;
+          currentLineCapacity = subsequentLineCapacity;
+        }
+        maxRunChars = Math.max(maxRunChars, currentLineChars);
+        break;
+      }
+      case "tab": {
+        const tabAdvance = resolveTabAdvance(formatting, currentLineChars);
+        currentLineChars += tabAdvance;
+        while (currentLineChars > currentLineCapacity) {
+          lineCount += 1;
+          currentLineChars -= currentLineCapacity;
+          currentLineCapacity = subsequentLineCapacity;
+        }
+        break;
+      }
+      case "hard_break":
+        lineCount += 1;
+        currentLineChars = 0;
+        currentLineCapacity = subsequentLineCapacity;
+        break;
+      case "image":
+        lineCount += segment.display === "floating" ? 2 : 1;
+        currentLineChars = 0;
+        currentLineCapacity = subsequentLineCapacity;
+        break;
+      case "note_ref":
+        currentLineChars += 1;
+        if (currentLineChars > currentLineCapacity) {
+          lineCount += 1;
+          currentLineChars -= currentLineCapacity;
+          currentLineCapacity = subsequentLineCapacity;
+        }
+        break;
+      case "opaque_inline":
+        if (segment.presentation !== "quiet-marker") {
+          currentLineChars += segment.label.length > 0 ? 1 : 0;
+          if (currentLineChars > currentLineCapacity) {
+            lineCount += 1;
+            currentLineChars -= currentLineCapacity;
+            currentLineCapacity = subsequentLineCapacity;
+          }
+        }
+        break;
+    }
+  }
+
+  lineCount = Math.max(1, lineCount);
+  const lineHeights = new Array(lineCount).fill(formatting.lineHeight);
+
+  return {
+    lineCount,
+    maxLineWidth: Math.max(
+      0,
+      Math.min(firstLineWidth, maxRunChars * formatting.averageCharWidthTwips),
+    ),
+    lineHeights,
+  };
+}
+
+function measureInlineObject(
+  input: MeasureInlineObjectInput,
+): MeasuredInlineObject {
+  return {
+    widthTwips: input.widthTwips,
+    heightTwips: input.heightTwips,
+    displacedLineCount: input.display === "floating" ? 2 : 1,
+  };
+}
+
+function measureTableBlock(
+  input: MeasureTableBlockInput,
+): MeasuredTableBlock {
+  const rowHeights: number[] = [];
+  let total = 0;
+  for (const row of input.block.rows) {
+    const explicitHeight = row.height ?? 0;
+    const heightRule = row.heightRule ?? "auto";
+    const cellCount = Math.max(1, row.cells.length);
+    const cellWidth = Math.max(720, Math.floor(input.columnWidth / cellCount));
+
+    let contentHeight = MIN_BLOCK_HEIGHT_TWIPS;
+    for (const cell of row.cells) {
+      let cellHeight = 0;
+      for (const child of cell.content) {
+        if (child.kind === "paragraph") {
+          // Lightweight estimate: MIN_BLOCK_HEIGHT_TWIPS per paragraph.
+          cellHeight += MIN_BLOCK_HEIGHT_TWIPS;
+        }
+      }
+      contentHeight = Math.max(contentHeight, cellHeight + TABLE_ROW_PADDING_TWIPS);
+    }
+
+    let rowHeight: number;
+    if (heightRule === "exact" && explicitHeight > 0) {
+      rowHeight = explicitHeight;
+    } else if (explicitHeight > 0) {
+      rowHeight = Math.max(explicitHeight, contentHeight);
+    } else {
+      rowHeight = contentHeight;
+    }
+    rowHeights.push(rowHeight);
+    total += rowHeight;
+  }
+  return {
+    totalHeightTwips: Math.max(MIN_BLOCK_HEIGHT_TWIPS, total),
+    rowHeights,
+  };
+}
+
+function resolveTabAdvance(
+  formatting: import("./resolved-formatting-state.ts").ResolvedParagraphFormatting,
+  currentChars: number,
+): number {
+  const avgCharWidth = formatting.averageCharWidthTwips;
+  const defaultTabInterval = 720;
+  const currentPosition = currentChars * avgCharWidth + formatting.indentLeft;
+
+  if (formatting.tabStops.length === 0) {
+    const nextTab =
+      Math.ceil((currentPosition + 1) / defaultTabInterval) * defaultTabInterval;
+    const advance = nextTab - currentPosition;
+    return Math.max(1, Math.round(advance / avgCharWidth));
+  }
+
+  for (const tab of formatting.tabStops) {
+    if (tab.position > currentPosition) {
+      const advance = tab.position - currentPosition;
+      return Math.max(1, Math.round(advance / avgCharWidth));
+    }
+  }
+
+  return 4;
+}

package/src/runtime/layout/page-fragment-mapper.ts

@@ -0,0 +1,179 @@
+/**
+ * PageFragmentMapper — offset ↔ fragment ↔ region mapping.
+ *
+ * Per runtime-owned-paginated-layout-engine.md §6, this is the missing layer
+ * between `pm-position-map.ts` and `DocumentNavigationSnapshot`:
+ *
+ *   runtime position → page fragment → visible page region
+ *
+ * The mapper is a pure query service over a RuntimePageGraph.  It does not
+ * mutate state and does not consult DOM or PM.
+ */
+
+import type { EditorStoryTarget, SelectionSnapshot } from "../../api/public-types";
+import type {
+  RuntimeBlockFragment,
+  RuntimePageGraph,
+  RuntimePageNode,
+} from "./page-graph.ts";
+
+export interface PageFragmentLocation {
+  pageId: string;
+  pageIndex: number;
+  fragmentId: string;
+  regionKind: "body" | "header" | "footer" | "column" | "footnote-area";
+  /** Zero-based index of the line box within the fragment, if line boxes are available. */
+  lineBoxIndex?: number;
+}
+
+export interface PageSpan {
+  firstPageIndex: number;
+  lastPageIndex: number;
+  pageCount: number;
+}
+
+export interface PageFragmentMapper {
+  mapOffsetToFragment(offset: number, story?: EditorStoryTarget): PageFragmentLocation | null;
+  mapFragmentToOffsetRange(fragmentId: string): { from: number; to: number } | null;
+  mapSelectionToPageSpan(selection: SelectionSnapshot): PageSpan | null;
+  /**
+   * Resolve a page-local anchor for the given offset.  Returns the offset
+   * unchanged today; retained as a seam for future semantic anchors.
+   */
+  getAnchorForOffset(offset: number, story?: EditorStoryTarget): { offset: number; pageId: string } | null;
+}
+
+export function createPageFragmentMapper(graph: RuntimePageGraph): PageFragmentMapper {
+  const fragmentsById = new Map<string, RuntimeBlockFragment>();
+  for (const fragment of graph.fragments) {
+    fragmentsById.set(fragment.fragmentId, fragment);
+  }
+
+  const pagesById = new Map<string, RuntimePageNode>();
+  for (const page of graph.pages) {
+    pagesById.set(page.pageId, page);
+  }
+
+  function findFragmentAt(offset: number): RuntimeBlockFragment | undefined {
+    // Fragments sort naturally by page then order; a linear scan is O(n) but
+    // page counts are small (legal docs rarely exceed a few hundred pages).
+    for (const fragment of graph.fragments) {
+      if (offset >= fragment.from && offset < fragment.to) {
+        return fragment;
+      }
+    }
+    // fall back to the last fragment that starts at or before the offset
+    let best: RuntimeBlockFragment | undefined;
+    for (const fragment of graph.fragments) {
+      if (fragment.from <= offset) {
+        if (!best || fragment.from > best.from) best = fragment;
+      }
+    }
+    return best;
+  }
+
+  return {
+    mapOffsetToFragment(offset, _story) {
+      const fragment = findFragmentAt(offset);
+      if (!fragment) {
+        // Fallback to coarse page lookup
+        const page = findPageForOffsetInternal(graph, offset);
+        if (!page) return null;
+        return {
+          pageId: page.pageId,
+          pageIndex: page.pageIndex,
+          fragmentId: `${page.pageId}-synthetic`,
+          regionKind: "body",
+        };
+      }
+      const page = pagesById.get(fragment.pageId);
+      if (!page) return null;
+
+      // Locate a line box if any
+      let lineBoxIndex: number | undefined;
+      for (let i = 0; i < page.lineBoxes.length; i += 1) {
+        if (page.lineBoxes[i]!.fragmentId === fragment.fragmentId) {
+          lineBoxIndex = i;
+          break;
+        }
+      }
+
+      return {
+        pageId: page.pageId,
+        pageIndex: page.pageIndex,
+        fragmentId: fragment.fragmentId,
+        regionKind: fragment.regionKind,
+        ...(lineBoxIndex !== undefined ? { lineBoxIndex } : {}),
+      };
+    },
+
+    mapFragmentToOffsetRange(fragmentId) {
+      const fragment = fragmentsById.get(fragmentId);
+      if (!fragment) return null;
+      return { from: fragment.from, to: fragment.to };
+    },
+
+    mapSelectionToPageSpan(selection) {
+      const from = Math.min(selection.anchor, selection.head);
+      const to = Math.max(selection.anchor, selection.head);
+      const firstPage = findPageForOffsetInternal(graph, from);
+      const lastPage = findPageForOffsetInternal(graph, to);
+      if (!firstPage || !lastPage) return null;
+      return {
+        firstPageIndex: firstPage.pageIndex,
+        lastPageIndex: lastPage.pageIndex,
+        pageCount: Math.max(1, lastPage.pageIndex - firstPage.pageIndex + 1),
+      };
+    },
+
+    getAnchorForOffset(offset, _story) {
+      const page = findPageForOffsetInternal(graph, offset);
+      if (!page) return null;
+      return { offset, pageId: page.pageId };
+    },
+  };
+}
+
+function findPageForOffsetInternal(
+  graph: RuntimePageGraph,
+  offset: number,
+): RuntimePageNode | undefined {
+  for (const page of graph.pages) {
+    if (!page.isBlankFiller && offset < page.endOffset) {
+      return page;
+    }
+  }
+  return graph.pages[graph.pages.length - 1];
+}
+
+/**
+ * Rebuild the mapper for a spliced graph.
+ *
+ * Correctness baseline: the simplest safe implementation is to fully rebuild
+ * the mapper from the new graph. The `prior` and `firstDirtyPage` arguments
+ * are accepted for forward compatibility with a future optimization that
+ * retains fragment-id indexes for unaffected pages. Today rebuilding is
+ * cheap (linear in fragment count) so the naive path is the right trade-off.
+ *
+ * Renamed from `updateMapperIncremental` (§6 E.5) now that the body is an
+ * unconditional full rebuild — the old name implied an incremental strategy
+ * that never actually existed in the shipped runtime.
+ */
+export function rebuildMapper(
+  prior: PageFragmentMapper,
+  splicedGraph: RuntimePageGraph,
+  firstDirtyPage: number,
+): PageFragmentMapper {
+  // Parameters are intentionally unused by the current implementation;
+  // retained as a seam for a future bounded update path.
+  void prior;
+  void firstDirtyPage;
+  return createPageFragmentMapper(splicedGraph);
+}
+
+/**
+ * @deprecated Renamed to `rebuildMapper` in §6 E.5. Retained as a
+ * one-release compatibility alias so external consumers are not broken by
+ * the rename; schedule removal after the next published API pin refresh.
+ */
+export const updateMapperIncremental = rebuildMapper;