@beyondwork/docx-react-component 1.0.38 → 1.0.40

package/src/runtime/layout/layout-engine-instance.ts

@@ -45,6 +45,8 @@ import {
 import {
   buildPageStack,
   buildPageStackFrom,
+  buildPageStackFromWithSplits,
+  buildPageStackWithSplits,
   type LayoutInvalidationReason,
 } from "./paginated-layout-engine.ts";
 import {
@@ -195,6 +197,14 @@ function recordFullRebuildReason(reasonKind: string): void {
 export interface CreateLayoutEngineOptions {
   /** Optional measurement provider. Defaults to empirical. */
   measurementProvider?: LayoutMeasurementProvider;
+  /**
+   * When true and a browser-like `document` global is available, the engine
+   * dynamically imports the Canvas2D measurement backend and swaps to it at
+   * init time, emitting `measurement_backend_ready`.  SSR stays on the
+   * empirical backend.  Callers that want to stay on empirical (for
+   * determinism or tests) pass `false`.  Default: true.
+   */
+  autoUpgradeToCanvasBackend?: boolean;
 }
 
 export function createLayoutEngine(
@@ -202,6 +212,7 @@ export function createLayoutEngine(
 ): LayoutEngineInstance {
   let measurementProvider: LayoutMeasurementProvider =
     options.measurementProvider ?? createEmpiricalMeasurementProvider();
+  const autoUpgradeToCanvas = options.autoUpgradeToCanvasBackend !== false;
   const dirtyFieldFamilies = new Set<string>();
   const listeners = new Set<(event: LayoutEngineEvent) => void>();
   let cachedKey: CacheKey | null = null;
@@ -244,11 +255,18 @@ export function createLayoutEngine(
       MAIN_STORY_TARGET,
     );
     const sections = buildResolvedSections(document);
-    const pages = buildPageStack(document, sections, mainSurface, measurementProvider);
+    const pageStack = buildPageStackWithSplits(
+      document,
+      sections,
+      mainSurface,
+      measurementProvider,
+    );
+    const pages = pageStack.pages;
     const stories = resolvePageStories(pages);
     const fragmentsByPageIndex = projectSurfaceBlocksToPageFragments(
       mainSurface,
       pages,
+      pageStack.splits,
     );
     const graph = buildPageGraph({
       pages,
@@ -320,7 +338,7 @@ export function createLayoutEngine(
     const sections = buildResolvedSections(document);
 
     const dirtyPage = priorGraph.pages[firstDirty]!;
-    const freshSnapshots = buildPageStackFrom(
+    const freshResult = buildPageStackFromWithSplits(
       document,
       sections,
       mainSurface,
@@ -330,6 +348,7 @@ export function createLayoutEngine(
       },
       measurementProvider,
     );
+    const freshSnapshots = freshResult.pages;
 
     // Convert fresh DocumentPageSnapshots into RuntimePageNodes via the
     // standard buildPageGraph pipeline — this keeps region, story, and
@@ -341,10 +360,18 @@ export function createLayoutEngine(
       return null;
     }
     const freshStories = resolvePageStories(freshSnapshots);
+    // Project fragments for the fresh tail pages, threading paragraph
+    // line-range splits produced by intra-paragraph pagination.
+    const freshFragmentsByPageIndex = projectSurfaceBlocksToPageFragments(
+      mainSurface,
+      freshSnapshots,
+      freshResult.splits,
+    );
     const freshGraph = buildPageGraph({
       pages: freshSnapshots,
       sections,
       stories: freshStories,
+      fragmentsByPageIndex: freshFragmentsByPageIndex,
     });
     const freshNodes = freshGraph.pages;
 
@@ -444,6 +471,46 @@ export function createLayoutEngine(
     return cachedFormatting!;
   }
 
+  // -----------------------------------------------------------------------
+  // Auto-upgrade to the Canvas2D measurement backend in browsers.  Dynamic
+  // import keeps SSR bundles lean.  We only attempt the upgrade when the
+  // caller didn't provide their own provider and `document` is available.
+  // -----------------------------------------------------------------------
+  if (
+    autoUpgradeToCanvas &&
+    options.measurementProvider === undefined &&
+    typeof document !== "undefined" &&
+    typeof HTMLCanvasElement !== "undefined"
+  ) {
+    // Swallow errors silently — staying on empirical is correct behavior
+    // when the upgrade fails.  Perf probe increments the fallback counter
+    // through the emitted event (listeners observe fidelity).
+    const readCachedRevision = (): number => cachedGraph?.revision ?? 0;
+    void (async () => {
+      try {
+        const mod = await import("./measurement-backend-canvas.ts");
+        const canvasProvider = mod.createCanvasBackend();
+        measurementProvider = canvasProvider;
+        // Invalidate the cached graph/formatting/mapper so the next read
+        // recomputes with canvas-measured font metrics.  Without this,
+        // the first render after the async import still uses empirical
+        // numbers and the chrome shifts by a few pixels on the next
+        // real invalidation.
+        cachedKey = null;
+        cachedGraph = null;
+        cachedFormatting = null;
+        cachedMapper = null;
+        emit({
+          kind: "measurement_backend_ready",
+          revision: readCachedRevision(),
+          fidelity: canvasProvider.fidelity,
+        });
+      } catch {
+        // Stay on empirical. No-op.
+      }
+    })();
+  }
+
   return {
     get measurementFidelity() {
       return measurementProvider.fidelity;

package/src/runtime/layout/layout-invalidation.ts

@@ -93,12 +93,21 @@ export function analyzeInvalidation(
       return analyzeSectionChange(reason, graph);
 
     case "numbering-change":
-      // Numbering changes can affect indentation and spacing globally,
-      // but could be bounded to sections using that numbering instance.
-      // For now, full recompute.
+      if (!reason.numberingInstanceId) {
+        return {
+          scope: "full",
+          requiresFullRecompute: true,
+          dirtyFieldFamilies: [],
+        };
+      }
       return {
-        scope: "full",
-        requiresFullRecompute: true,
+        scope: "bounded",
+        requiresFullRecompute: false,
+        dirtyPageRange: {
+          firstPageIndex: 0,
+          lastPageIndex: Math.max(0, graph.pages.length - 1),
+        },
+        dirtySectionRange: null,
         dirtyFieldFamilies: [],
       };
 

package/src/runtime/layout/page-graph.ts

@@ -102,6 +102,42 @@ export interface RuntimeBlockFragment {
   to: number;
   /** Height consumed on this page (twips). */
   heightTwips: number;
+  /**
+   * Fragment classification.
+   * - `"whole"` (default): the fragment represents the entire block; no slicing.
+   * - `"paragraph-slice"`: one of several fragments produced by intra-paragraph
+   *   line-box splitting. `paragraphLineRange` identifies which lines this
+   *   slice renders.
+   * - `"table-slice"`: one of several fragments produced by row-boundary table
+   *   splitting (emitted by the table-fidelity workstream).
+   *   `tableRowRange` identifies which canonical rows this slice renders.
+   * Consumers that predate multi-fragment blocks may treat an absent `kind`
+   * as `"whole"`.
+   */
+  kind?: "whole" | "paragraph-slice" | "table-slice";
+  /**
+   * For `kind === "paragraph-slice"`, the inclusive-exclusive line-box index
+   * range rendered by this slice plus the total line count for the source
+   * paragraph. `from`/`to` still span the full paragraph offset range on
+   * every slice — only the visible lines differ.
+   */
+  paragraphLineRange?: {
+    from: number;
+    to: number;
+    totalLines: number;
+  };
+  /**
+   * For `kind === "table-slice"`, the inclusive-exclusive row-index range
+   * rendered by this slice. Repeated header rows (when the table has
+   * `isHeader` rows and `continuation` pages) are implied by the owning
+   * table's canonical row list — consumers prepend header rows for slices
+   * whose `from > 0`.
+   */
+  tableRowRange?: {
+    from: number;
+    to: number;
+    totalRows: number;
+  };
 }
 
 export interface RuntimeLineBox {

package/src/runtime/layout/paginate-paragraph-lines.ts

@@ -0,0 +1,128 @@
+/**
+ * Line-box splitter for paragraph pagination.
+ *
+ * Given a paragraph that doesn't fit on the current page, decide how many of
+ * its lines belong on the current page and how many continue on the next.
+ * Honors the four pagination attributes that govern this in OOXML /
+ * ECMA-376 §17.3.1.33:
+ *
+ *   - `keepLines`         — if true, never split the paragraph.
+ *   - `widowControl`      — if true (Word default), keep ≥ WIDOW_MIN lines on
+ *                           each side of any split. Applies independently at
+ *                           the top (orphan) and bottom (widow) of a split.
+ *   - `keepNext`          — orthogonal to splitting itself; the engine's
+ *                           outer loop uses it to bundle the paragraph with
+ *                           the next. We only honour it here to avoid an
+ *                           awkward split on a paragraph that is about to be
+ *                           kept with the next (no gain from splitting).
+ *   - `pageBreakBefore`   — handled upstream via an unconditional page break;
+ *                           if set, callers do not consult this splitter.
+ *
+ * Pure function. No DOM, no side effects. Unit-testable in isolation.
+ */
+
+export const DEFAULT_WIDOW_MIN_LINES = 2;
+
+export interface LineSplitInput {
+  /** Total number of line boxes in the paragraph, ≥ 1. */
+  totalLines: number;
+  /**
+   * How many lines can still fit on the current page given the remaining
+   * vertical space and the paragraph's resolved line height. Callers compute
+   * this by dividing the remaining column height by the per-line height.
+   * Must be ≥ 0. Zero is legal and short-circuits to "no split" (the whole
+   * paragraph moves to the next page).
+   */
+  availableLines: number;
+  /** OOXML `w:keepLines`. */
+  keepLines: boolean;
+  /** OOXML `w:widowControl` (true in Word's default).  */
+  widowControl: boolean;
+  /** OOXML `w:keepNext`. */
+  keepNext: boolean;
+  /**
+   * Whether this paragraph is the last block on the page-in-flight.  If true,
+   * splitting buys nothing (there's no subsequent content we're squeezing in
+   * below) and we leave the whole paragraph on the current page.
+   */
+  isLastBlockOnPage: boolean;
+  /**
+   * Minimum lines required on each side of a widow/orphan-controlled split.
+   * Defaults to {@link DEFAULT_WIDOW_MIN_LINES}. Exposed for fixtures that
+   * exercise narrow paragraphs.
+   */
+  widowMinLines?: number;
+}
+
+export interface LineSplitResult {
+  linesOnCurrent: number;
+  linesOnNext: number;
+}
+
+/**
+ * Decide how to split a paragraph across a page boundary.
+ *
+ * Returns:
+ *   - `null` when no split should happen. The caller's existing "move the
+ *     whole paragraph to the next page" behavior applies.
+ *   - A `{ linesOnCurrent, linesOnNext }` split with `linesOnCurrent +
+ *     linesOnNext === totalLines` and both values ≥ 1. The caller must
+ *     render `linesOnCurrent` lines in the remaining space on the current
+ *     page and `linesOnNext` lines at the top of the next page.
+ */
+export function paginateParagraphLines(
+  input: LineSplitInput,
+): LineSplitResult | null {
+  const totalLines = Math.max(1, Math.floor(input.totalLines));
+  const availableLines = Math.max(0, Math.floor(input.availableLines));
+  const widowMin = Math.max(1, input.widowMinLines ?? DEFAULT_WIDOW_MIN_LINES);
+
+  // keepLines wins unconditionally.
+  if (input.keepLines) return null;
+
+  // If the paragraph fits wholesale on the current page, no split.
+  if (totalLines <= availableLines) return null;
+
+  // If there's nothing worth keeping on the current page (zero lines fit, or
+  // only a single line under widow control would fit), fall through to the
+  // caller's "move whole paragraph" path.
+  const effectiveOrphanMin = input.widowControl ? widowMin : 1;
+  if (availableLines < effectiveOrphanMin) return null;
+
+  // Don't split trivially-short paragraphs whose final lines could fit a
+  // page move (keeping them intact preserves Word's visual intent).
+  if (totalLines < effectiveOrphanMin * 2) return null;
+
+  // If this paragraph is the last thing on this page anyway, splitting has
+  // no downstream benefit — the next page is empty.
+  if (input.isLastBlockOnPage) return null;
+
+  // keepNext paragraphs are meant to travel with the next block. Splitting
+  // them would move half-and-half across the break, which usually contradicts
+  // author intent. Leave the paragraph intact; the outer loop will handle
+  // the keep-with-next pairing on the next page.
+  if (input.keepNext) return null;
+
+  // Candidate split: fill the current page, put the rest on the next.
+  let linesOnCurrent = availableLines;
+  let linesOnNext = totalLines - linesOnCurrent;
+
+  // Widow control: the tail on the next page needs ≥ widowMin lines too.
+  if (input.widowControl && linesOnNext < widowMin) {
+    // Pull enough lines back to the next page to meet the widow minimum.
+    const deficit = widowMin - linesOnNext;
+    linesOnCurrent -= deficit;
+    linesOnNext += deficit;
+
+    // If pulling back violates the orphan minimum, abandon the split —
+    // the whole paragraph goes on the next page.
+    if (linesOnCurrent < widowMin) return null;
+  }
+
+  // Sanity clamp (the arithmetic above should guarantee these but be
+  // defensive against bad input).
+  if (linesOnCurrent < 1 || linesOnNext < 1) return null;
+  if (linesOnCurrent + linesOnNext !== totalLines) return null;
+
+  return { linesOnCurrent, linesOnNext };
+}