@beyondwork/docx-react-component 1.0.37 → 1.0.39

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

@@ -36,6 +36,7 @@ import {
 } from "../document-layout.ts";
 import { findNoteReferencePosition } from "../view-state.ts";
 import { createEditorSurfaceSnapshot } from "../surface-projection.ts";
+import { buildHeadingOutline } from "../document-navigation.ts";
 import {
   analyzeInvalidation,
   computeFieldDirtiness,
@@ -44,6 +45,8 @@ import {
 import {
   buildPageStack,
   buildPageStackFrom,
+  buildPageStackFromWithSplits,
+  buildPageStackWithSplits,
   type LayoutInvalidationReason,
 } from "./paginated-layout-engine.ts";
 import {
@@ -53,6 +56,7 @@ import {
   type RuntimePageGraph,
   type RuntimePageNode,
 } from "./page-graph.ts";
+import { projectSurfaceBlocksToPageFragments } from "./project-block-fragments.ts";
 import {
   resolvePageStories,
   resolveTotalPageCount,
@@ -193,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(
@@ -200,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;
@@ -242,9 +255,25 @@ export function createLayoutEngine(
       MAIN_STORY_TARGET,
     );
     const sections = buildResolvedSections(document);
-    const pages = buildPageStack(document, sections, mainSurface);
+    const pageStack = buildPageStackWithSplits(
+      document,
+      sections,
+      mainSurface,
+      measurementProvider,
+    );
+    const pages = pageStack.pages;
     const stories = resolvePageStories(pages);
-    const graph = buildPageGraph({ pages, sections, stories });
+    const fragmentsByPageIndex = projectSurfaceBlocksToPageFragments(
+      mainSurface,
+      pages,
+      pageStack.splits,
+    );
+    const graph = buildPageGraph({
+      pages,
+      sections,
+      stories,
+      fragmentsByPageIndex,
+    });
 
     // Field dirtiness diff from previous graph
     const dirtyFamilies = computeFieldDirtiness(cachedGraph, graph);
@@ -309,10 +338,17 @@ export function createLayoutEngine(
     const sections = buildResolvedSections(document);
 
     const dirtyPage = priorGraph.pages[firstDirty]!;
-    const freshSnapshots = buildPageStackFrom(document, sections, mainSurface, {
-      startPageIndex: firstDirty,
-      startOffset: dirtyPage.startOffset,
-    });
+    const freshResult = buildPageStackFromWithSplits(
+      document,
+      sections,
+      mainSurface,
+      {
+        startPageIndex: firstDirty,
+        startOffset: dirtyPage.startOffset,
+      },
+      measurementProvider,
+    );
+    const freshSnapshots = freshResult.pages;
 
     // Convert fresh DocumentPageSnapshots into RuntimePageNodes via the
     // standard buildPageGraph pipeline — this keeps region, story, and
@@ -324,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;
 
@@ -427,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;
@@ -543,13 +627,19 @@ function buildNavigationFromGraph(
 ): DocumentNavigationSnapshot {
   const pages = deriveDocumentPageSnapshots(graph);
   const sections = graph.sections;
+  const mainSurface = createEditorSurfaceSnapshot(
+    document,
+    createSelectionSnapshot(0, 0),
+    MAIN_STORY_TARGET,
+  );
+  const headings = buildHeadingOutline(document, mainSurface, sections, pages);
 
   if (activeStory.kind === "main") {
     const activePageIndex = deriveActivePageIndex(graph, selectionHead);
     return {
       pageCount: pages.length,
       pages,
-      headings: buildHeadings(graph),
+      headings,
       activePageIndex,
       activeSectionIndex: deriveActiveSectionIndex(graph, selectionHead),
     };
@@ -564,24 +654,19 @@ function buildNavigationFromGraph(
     return {
       pageCount: pages.length,
       pages,
-      headings: buildHeadings(graph),
+      headings,
       activePageIndex: firstPage >= 0 ? firstPage : 0,
       activeSectionIndex: sectionIndex,
     };
   }
 
   if (activeStory.kind === "footnote" || activeStory.kind === "endnote") {
-    const mainSurface = createEditorSurfaceSnapshot(
-      document,
-      createSelectionSnapshot(0, 0),
-      MAIN_STORY_TARGET,
-    );
     const referencePosition = findNoteReferencePosition(mainSurface, activeStory);
     const activePageIndex = deriveActivePageIndex(graph, referencePosition);
     return {
       pageCount: pages.length,
       pages,
-      headings: buildHeadings(graph),
+      headings,
       activePageIndex,
       activeSectionIndex:
         graph.pages[activePageIndex]?.sectionIndex ??
@@ -592,20 +677,12 @@ function buildNavigationFromGraph(
   return {
     pageCount: pages.length,
     pages,
-    headings: buildHeadings(graph),
+    headings,
     activePageIndex: 0,
     activeSectionIndex: 0,
   };
 }
 
-function buildHeadings(graph: RuntimePageGraph) {
-  // Headings are derived elsewhere (createDocumentNavigationSnapshot pipes
-  // them from its own helper).  For engine-native reads we return an empty
-  // list; the existing navigation snapshot keeps its headings pipeline.
-  void graph;
-  return [];
-}
-
 // ---------------------------------------------------------------------------
 // Convenience: find the active page node directly
 // ---------------------------------------------------------------------------

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/margin-preset-catalog.ts

@@ -0,0 +1,178 @@
+/**
+ * Margin preset catalog — the five named Word margin presets (Normal,
+ * Narrow, Moderate, Wide, Mirrored) plus Custom.
+ *
+ * Values mirror Microsoft Word's defaults in twips so a "Narrow" preset
+ * round-trips to `w:top = 720 / w:bottom = 720 / w:left = 720 / w:right = 720`
+ * on export.
+ */
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export type MarginPresetId =
+  | "normal"
+  | "narrow"
+  | "moderate"
+  | "wide"
+  | "mirrored"
+  | "custom";
+
+export interface MarginPresetDefinition {
+  id: MarginPresetId;
+  label: string;
+  topTwips: number;
+  bottomTwips: number;
+  leftTwips: number;
+  rightTwips: number;
+  gutterTwips: number;
+  mirrored: boolean;
+}
+
+export interface ActiveMarginPreset {
+  sectionIndex: number;
+  preset: MarginPresetDefinition;
+  matchesCatalog: boolean;
+  customTwips?: {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+    gutter: number;
+    mirrored: boolean;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Catalog
+// ---------------------------------------------------------------------------
+
+export const MARGIN_PRESET_CATALOG: readonly MarginPresetDefinition[] = Object.freeze([
+  {
+    id: "normal",
+    label: "Normal",
+    topTwips: 1440,
+    bottomTwips: 1440,
+    leftTwips: 1440,
+    rightTwips: 1440,
+    gutterTwips: 0,
+    mirrored: false,
+  },
+  {
+    id: "narrow",
+    label: "Narrow",
+    topTwips: 720,
+    bottomTwips: 720,
+    leftTwips: 720,
+    rightTwips: 720,
+    gutterTwips: 0,
+    mirrored: false,
+  },
+  {
+    id: "moderate",
+    label: "Moderate",
+    topTwips: 1440,
+    bottomTwips: 1440,
+    leftTwips: 1080,
+    rightTwips: 1080,
+    gutterTwips: 0,
+    mirrored: false,
+  },
+  {
+    id: "wide",
+    label: "Wide",
+    topTwips: 1440,
+    bottomTwips: 1440,
+    leftTwips: 2880,
+    rightTwips: 2880,
+    gutterTwips: 0,
+    mirrored: false,
+  },
+  {
+    id: "mirrored",
+    label: "Mirrored",
+    topTwips: 1440,
+    bottomTwips: 1440,
+    leftTwips: 1800,
+    rightTwips: 1440,
+    gutterTwips: 0,
+    mirrored: true,
+  },
+  {
+    id: "custom",
+    label: "Custom",
+    topTwips: 0,
+    bottomTwips: 0,
+    leftTwips: 0,
+    rightTwips: 0,
+    gutterTwips: 0,
+    mirrored: false,
+  },
+]);
+
+const MATCH_TOLERANCE_TWIPS = 1;
+
+// ---------------------------------------------------------------------------
+// Matching
+// ---------------------------------------------------------------------------
+
+export interface MatchMarginPresetInput {
+  sectionIndex: number;
+  topTwips: number;
+  bottomTwips: number;
+  leftTwips: number;
+  rightTwips: number;
+  gutterTwips: number;
+  mirrored: boolean;
+}
+
+export function matchMarginPreset(
+  input: MatchMarginPresetInput,
+): ActiveMarginPreset {
+  const { sectionIndex, topTwips, bottomTwips, leftTwips, rightTwips, gutterTwips, mirrored } = input;
+
+  for (const preset of MARGIN_PRESET_CATALOG) {
+    if (preset.id === "custom") continue;
+    if (preset.mirrored !== mirrored) continue;
+
+    if (
+      near(preset.topTwips, topTwips) &&
+      near(preset.bottomTwips, bottomTwips) &&
+      near(preset.leftTwips, leftTwips) &&
+      near(preset.rightTwips, rightTwips) &&
+      near(preset.gutterTwips, gutterTwips)
+    ) {
+      return {
+        sectionIndex,
+        preset,
+        matchesCatalog: true,
+      };
+    }
+  }
+
+  const custom = MARGIN_PRESET_CATALOG.find((p) => p.id === "custom")!;
+  return {
+    sectionIndex,
+    preset: custom,
+    matchesCatalog: false,
+    customTwips: {
+      top: topTwips,
+      bottom: bottomTwips,
+      left: leftTwips,
+      right: rightTwips,
+      gutter: gutterTwips,
+      mirrored,
+    },
+  };
+}
+
+function near(a: number, b: number): boolean {
+  return Math.abs(a - b) <= MATCH_TOLERANCE_TWIPS;
+}
+
+export function getMarginPresetById(id: string): MarginPresetDefinition {
+  const found = MARGIN_PRESET_CATALOG.find((p) => p.id === id);
+  if (found) return found;
+  return MARGIN_PRESET_CATALOG.find((p) => p.id === "custom")!;
+}

package/src/runtime/layout/page-format-catalog.ts

@@ -0,0 +1,233 @@
+/**
+ * Page-format catalog — named page sizes that back the section page-size
+ * picker and the real-dimension page frame.
+ *
+ * The canonical storage of page geometry remains
+ * `SectionProperties.pageSize` in twips.  This catalog adds a layer of
+ * semantic naming on top so the UI can render "A4" or "US Letter" and
+ * the render kernel can pick a sensible default per locale.
+ *
+ * Unit reference (OOXML):
+ *   - 1 inch = 1440 twips
+ *   - 1 mm   = 56.6929 twips
+ *
+ * The catalog deliberately ships a single default match tolerance (1 twip)
+ * so legacy documents whose page sizes were round-tripped through third-
+ * party tools still identify as the named format they were authored at.
+ */
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export type PageFormatId =
+  | "letter"
+  | "legal"
+  | "tabloid"
+  | "executive"
+  | "a3"
+  | "a4"
+  | "a5"
+  | "b4-iso"
+  | "b5-iso"
+  | "custom";
+
+export type PageFormatRegion = "us" | "iso" | "jp" | "custom";
+
+export type PageFormatLocaleDefault = "en-us" | "en-gb" | "eu" | "jp";
+
+export interface PageFormatDisplay {
+  inches?: string;
+  millimeters?: string;
+}
+
+export interface PageFormatDefinition {
+  /** Stable identifier. */
+  id: PageFormatId;
+  /** Human-facing label used in pickers. */
+  label: string;
+  /** Locale or region hint. */
+  region: PageFormatRegion;
+  /** Width in twips at portrait orientation. */
+  portraitWidthTwips: number;
+  /** Height in twips at portrait orientation. */
+  portraitHeightTwips: number;
+  /** Default-for-locale hint so consumers can pick a sensible default. */
+  localeDefault?: PageFormatLocaleDefault;
+  /** Pre-computed inches/millimeters strings for the picker. */
+  display: PageFormatDisplay;
+}
+
+export interface ActivePageFormat {
+  sectionIndex: number;
+  format: PageFormatDefinition;
+  orientation: "portrait" | "landscape";
+  /** True when the section matches a catalog format within the match tolerance. */
+  matchesCatalog: boolean;
+  /** When matchesCatalog is false, the raw twips (custom format). */
+  customTwips?: { width: number; height: number };
+}
+
+// ---------------------------------------------------------------------------
+// Catalog
+// ---------------------------------------------------------------------------
+
+/**
+ * Pre-defined named page formats.  Ordering intentionally puts the most
+ * common sizes (Letter, A4) first because UI dropdowns render in list order.
+ */
+export const PAGE_FORMAT_CATALOG: readonly PageFormatDefinition[] = Object.freeze([
+  {
+    id: "letter",
+    label: "US Letter",
+    region: "us",
+    portraitWidthTwips: 12240,
+    portraitHeightTwips: 15840,
+    localeDefault: "en-us",
+    display: { inches: "8.5 × 11 in", millimeters: "215.9 × 279.4 mm" },
+  },
+  {
+    id: "a4",
+    label: "A4",
+    region: "iso",
+    portraitWidthTwips: 11906,
+    portraitHeightTwips: 16838,
+    localeDefault: "eu",
+    display: { inches: "8.27 × 11.69 in", millimeters: "210 × 297 mm" },
+  },
+  {
+    id: "legal",
+    label: "US Legal",
+    region: "us",
+    portraitWidthTwips: 12240,
+    portraitHeightTwips: 20160,
+    display: { inches: "8.5 × 14 in", millimeters: "215.9 × 355.6 mm" },
+  },
+  {
+    id: "tabloid",
+    label: "Tabloid / Ledger",
+    region: "us",
+    portraitWidthTwips: 15840,
+    portraitHeightTwips: 24480,
+    display: { inches: "11 × 17 in", millimeters: "279.4 × 431.8 mm" },
+  },
+  {
+    id: "executive",
+    label: "Executive",
+    region: "us",
+    portraitWidthTwips: 10440,
+    portraitHeightTwips: 15120,
+    display: { inches: "7.25 × 10.5 in", millimeters: "184.1 × 266.7 mm" },
+  },
+  {
+    id: "a3",
+    label: "A3",
+    region: "iso",
+    portraitWidthTwips: 16838,
+    portraitHeightTwips: 23811,
+    display: { inches: "11.69 × 16.54 in", millimeters: "297 × 420 mm" },
+  },
+  {
+    id: "a5",
+    label: "A5",
+    region: "iso",
+    portraitWidthTwips: 8391,
+    portraitHeightTwips: 11906,
+    display: { inches: "5.83 × 8.27 in", millimeters: "148 × 210 mm" },
+  },
+  {
+    id: "b4-iso",
+    label: "B4 (ISO)",
+    region: "iso",
+    portraitWidthTwips: 14173,
+    portraitHeightTwips: 20016,
+    display: { inches: "9.84 × 13.90 in", millimeters: "250 × 353 mm" },
+  },
+  {
+    id: "b5-iso",
+    label: "B5 (ISO)",
+    region: "iso",
+    portraitWidthTwips: 9977,
+    portraitHeightTwips: 14173,
+    display: { inches: "6.93 × 9.84 in", millimeters: "176 × 250 mm" },
+  },
+  {
+    id: "custom",
+    label: "Custom",
+    region: "custom",
+    portraitWidthTwips: 0,
+    portraitHeightTwips: 0,
+    display: {},
+  },
+]);
+
+/**
+ * Match tolerance in twips.  Historic round-trips through third-party tools
+ * sometimes drift by sub-twip amounts; a 1-twip window catches those while
+ * keeping intentionally custom sizes genuinely custom.
+ */
+const MATCH_TOLERANCE_TWIPS = 1;
+
+// ---------------------------------------------------------------------------
+// Matching
+// ---------------------------------------------------------------------------
+
+export interface MatchPageFormatInput {
+  sectionIndex: number;
+  widthTwips: number;
+  heightTwips: number;
+}
+
+/**
+ * Match a section's page dimensions against the catalog.
+ *
+ * The matcher tolerates either orientation — if the supplied (width, height)
+ * match a catalog entry rotated by 90°, the active format is reported as
+ * `landscape`.  Custom sizes fall through to the `custom` entry.
+ */
+export function matchPageFormat(input: MatchPageFormatInput): ActivePageFormat {
+  const { sectionIndex, widthTwips, heightTwips } = input;
+
+  for (const format of PAGE_FORMAT_CATALOG) {
+    if (format.id === "custom") continue;
+
+    const portraitMatch =
+      near(widthTwips, format.portraitWidthTwips) &&
+      near(heightTwips, format.portraitHeightTwips);
+    const landscapeMatch =
+      near(widthTwips, format.portraitHeightTwips) &&
+      near(heightTwips, format.portraitWidthTwips);
+
+    if (portraitMatch || landscapeMatch) {
+      return {
+        sectionIndex,
+        format,
+        orientation: portraitMatch ? "portrait" : "landscape",
+        matchesCatalog: true,
+      };
+    }
+  }
+
+  const custom = PAGE_FORMAT_CATALOG.find((f) => f.id === "custom")!;
+  return {
+    sectionIndex,
+    format: custom,
+    orientation: widthTwips > heightTwips ? "landscape" : "portrait",
+    matchesCatalog: false,
+    customTwips: { width: widthTwips, height: heightTwips },
+  };
+}
+
+function near(a: number, b: number): boolean {
+  return Math.abs(a - b) <= MATCH_TOLERANCE_TWIPS;
+}
+
+/**
+ * Look up a format by id.  Returns the `custom` entry for unknown ids so
+ * callers can chain `.format` reads without null-checking.
+ */
+export function getPageFormatById(id: string): PageFormatDefinition {
+  const found = PAGE_FORMAT_CATALOG.find((f) => f.id === id);
+  if (found) return found;
+  return PAGE_FORMAT_CATALOG.find((f) => f.id === "custom")!;
+}