@beyondwork/docx-react-component 1.0.35 → 1.0.37

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

@@ -0,0 +1,257 @@
+/**
+ * Layout invalidation — determines what must be recomputed after a mutation.
+ *
+ * Instead of recomputing the entire document on every change, this module
+ * classifies invalidation reasons and determines the minimal dirty range.
+ * The classification is conservative-correct: when any doubt exists (section
+ * boundary inside the dirty range, style change, numbering change, etc.) we
+ * fall back to a full rebuild.  The `scope` field declares which path the
+ * engine should follow.
+ */
+
+import type { LayoutInvalidationReason } from "./paginated-layout-engine.ts";
+import type { RuntimePageGraph, RuntimePageNode } from "./page-graph.ts";
+import type { ResolvedDocumentSection } from "../document-layout.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Scope of the invalidation:
+ *   - "full"       — rebuild the entire page graph
+ *   - "bounded"    — retain unaffected pages, rebuild only the dirty tail
+ *   - "field-only" — no layout rebuild; field display values refresh
+ */
+export type InvalidationScope = "full" | "bounded" | "field-only";
+
+export interface InvalidationResult {
+  /** Scope declaring which path the engine should follow. */
+  scope: InvalidationScope;
+  /**
+   * Whether a full recompute is needed.  Kept for backward compatibility;
+   * equivalent to `scope === "full"`.
+   */
+  requiresFullRecompute: boolean;
+  /** If partial invalidation is possible, the dirty section range. */
+  dirtySectionRange?: { from: number; to: number } | null;
+  /**
+   * If partial invalidation is possible, the dirty page range.
+   * Uses `firstPageIndex` / `lastPageIndex` rather than `from` / `to` to
+   * avoid confusion with offset-based ranges elsewhere in the engine.
+   */
+  dirtyPageRange?: { firstPageIndex: number; lastPageIndex: number } | null;
+  /** Field families that need refresh after this layout change. */
+  dirtyFieldFamilies: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Invalidation analysis
+// ---------------------------------------------------------------------------
+
+/**
+ * Analyze an invalidation reason against the current page graph to
+ * determine the minimal recomputation scope.
+ */
+export function analyzeInvalidation(
+  reason: LayoutInvalidationReason,
+  graph: RuntimePageGraph | null,
+): InvalidationResult {
+  // No existing graph — classify by kind alone; for "field-refresh" we do
+  // not force a layout rebuild even without a graph because only display
+  // values change.
+  if (!graph) {
+    if (reason.kind === "field-refresh") {
+      return {
+        scope: "field-only",
+        requiresFullRecompute: false,
+        dirtyFieldFamilies: reason.family ? [reason.family] : [],
+      };
+    }
+    return {
+      scope: "full",
+      requiresFullRecompute: true,
+      dirtyFieldFamilies: [],
+    };
+  }
+
+  switch (reason.kind) {
+    case "full":
+    case "styles-change":
+    case "theme-change":
+      // These affect the entire document
+      return {
+        scope: "full",
+        requiresFullRecompute: true,
+        dirtyFieldFamilies: ["PAGE", "NUMPAGES", "SECTIONPAGES"],
+      };
+
+    case "content-edit":
+      return analyzeContentEdit(reason, graph);
+
+    case "section-change":
+      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.
+      return {
+        scope: "full",
+        requiresFullRecompute: true,
+        dirtyFieldFamilies: [],
+      };
+
+    case "field-refresh":
+      // Field refresh doesn't change layout, just field display values
+      return {
+        scope: "field-only",
+        requiresFullRecompute: false,
+        dirtyFieldFamilies: reason.family ? [reason.family] : [],
+      };
+  }
+}
+
+/**
+ * After layout recomputation, determine which page-sensitive field families
+ * need to be refreshed based on what changed.
+ */
+export function computeFieldDirtiness(
+  oldGraph: RuntimePageGraph | null,
+  newGraph: RuntimePageGraph,
+): string[] {
+  if (!oldGraph) {
+    return ["PAGE", "NUMPAGES", "SECTIONPAGES"];
+  }
+
+  const dirtyFamilies: string[] = [];
+
+  // Page count changed => NUMPAGES is dirty
+  if (oldGraph.contentPageCount !== newGraph.contentPageCount) {
+    dirtyFamilies.push("NUMPAGES");
+  }
+
+  // Page boundaries changed => PAGE fields may show different values
+  const oldOffsets = oldGraph.pages.map((p) => p.endOffset).join(",");
+  const newOffsets = newGraph.pages.map((p) => p.endOffset).join(",");
+  if (oldOffsets !== newOffsets) {
+    dirtyFamilies.push("PAGE");
+  }
+
+  // Section structure changed
+  if (oldGraph.sections.length !== newGraph.sections.length) {
+    dirtyFamilies.push("SECTIONPAGES");
+  } else {
+    for (let i = 0; i < oldGraph.sections.length; i++) {
+      const oldSection = oldGraph.sections[i]!;
+      const newSection = newGraph.sections[i]!;
+      if (
+        oldSection.start !== newSection.start ||
+        oldSection.end !== newSection.end
+      ) {
+        dirtyFamilies.push("SECTIONPAGES");
+        break;
+      }
+    }
+  }
+
+  return dirtyFamilies;
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+function analyzeContentEdit(
+  reason: Extract<LayoutInvalidationReason, { kind: "content-edit" }>,
+  graph: RuntimePageGraph,
+): InvalidationResult {
+  // Find the first page whose endOffset > reason.from.  That's the first
+  // page whose content could have been affected by the edit.
+  // (We scan linearly; page counts are small in practice.)
+  let firstDirty = -1;
+  for (let i = 0; i < graph.pages.length; i += 1) {
+    const page = graph.pages[i]!;
+    if (page.isBlankFiller) continue;
+    if (page.endOffset > reason.from) {
+      firstDirty = i;
+      break;
+    }
+  }
+
+  if (firstDirty < 0) {
+    // Edit is past all pages — need a full recompute to re-paginate the tail.
+    return {
+      scope: "full",
+      requiresFullRecompute: true,
+      dirtyPageRange: null,
+      dirtySectionRange: null,
+      dirtyFieldFamilies: ["PAGE", "NUMPAGES"],
+    };
+  }
+
+  // Find the last page whose startOffset <= reason.to.  That's the last
+  // page whose content could have been affected by the edit.  If the edit
+  // crosses page boundaries, every page from firstDirty to lastDirty is
+  // potentially dirty.
+  let lastDirty = firstDirty;
+  for (let i = graph.pages.length - 1; i >= 0; i -= 1) {
+    const page = graph.pages[i]!;
+    if (page.isBlankFiller) continue;
+    if (page.startOffset <= reason.to) {
+      lastDirty = i;
+      break;
+    }
+  }
+  if (lastDirty < firstDirty) {
+    lastDirty = firstDirty;
+  }
+
+  // Safety: if the dirty range straddles a section boundary, fall back to
+  // full recompute.  Section-break handling (nextPage/evenPage/oddPage blank
+  // fillers, continuous merges) is easier to prove correct when the whole
+  // document re-paginates.
+  const firstSection = graph.pages[firstDirty]!.sectionIndex;
+  const lastSection = graph.pages[lastDirty]!.sectionIndex;
+  if (firstSection !== lastSection) {
+    return {
+      scope: "full",
+      requiresFullRecompute: true,
+      dirtyPageRange: null,
+      dirtySectionRange: null,
+      dirtyFieldFamilies: ["PAGE", "NUMPAGES", "SECTIONPAGES"],
+    };
+  }
+
+  // Bounded: we can retain pages [0..firstDirty-1] from the prior graph and
+  // rebuild [firstDirty..end].  Rebuilding to the end (not just lastDirty)
+  // is required because paragraph reflow past the edit can shift subsequent
+  // pages.  The engine's splice helper uses this range.
+  return {
+    scope: "bounded",
+    requiresFullRecompute: false,
+    dirtyPageRange: {
+      firstPageIndex: firstDirty,
+      lastPageIndex: graph.pages.length - 1,
+    },
+    dirtySectionRange: null,
+    dirtyFieldFamilies: [],
+  };
+}
+
+function analyzeSectionChange(
+  reason: Extract<LayoutInvalidationReason, { kind: "section-change" }>,
+  graph: RuntimePageGraph,
+): InvalidationResult {
+  // Section property changes affect from that section onward; conservative
+  // fallback is a full recompute.
+  return {
+    scope: "full",
+    requiresFullRecompute: true,
+    dirtySectionRange: {
+      from: reason.sectionIndex,
+      to: graph.sections.length - 1,
+    },
+    dirtyFieldFamilies: ["PAGE", "NUMPAGES", "SECTIONPAGES"],
+  };
+}

package/src/runtime/layout/layout-measurement-provider.ts

@@ -0,0 +1,175 @@
+/**
+ * LayoutMeasurementProvider — the abstraction the engine uses to measure
+ * text runs, inline objects, and table blocks.
+ *
+ * Per the architecture spec (runtime-owned-paginated-layout-engine.md §3),
+ * the engine must never call the DOM directly and never pretend browser flow
+ * is the source of truth.  Instead it asks a provider that has two backends:
+ *
+ *   - `empirical` (SSR-safe, default) — character-width tables
+ *   - `canvas`    (browser only)       — Canvas2D measureText
+ *
+ * Selection is automatic: when the runtime detects a browser environment and
+ * the host opts in, the canvas backend is used; otherwise empirical stays the
+ * fallback.  This keeps the gRPC/word-review-api path deterministic.
+ */
+
+import type { SurfaceBlockSnapshot } from "../../api/public-types";
+import type { ResolvedParagraphFormatting } from "./resolved-formatting-state.ts";
+import type { ResolvedRunFormatting } from "./resolved-formatting-document.ts";
+
+// ---------------------------------------------------------------------------
+// Provider contract
+// ---------------------------------------------------------------------------
+
+export type MeasurementFidelity =
+  | "empirical"
+  | "canvas"
+  | "canvas-with-font-loading";
+
+export interface MeasureLineFragmentsInput {
+  /** Paragraph block to measure. */
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>;
+  /** Paragraph-level resolved formatting (spacing, indent, font size). */
+  formatting: ResolvedParagraphFormatting;
+  /** Per-run resolved formatting for each text segment, keyed by runId. */
+  runs: ReadonlyMap<string, ResolvedRunFormatting>;
+  /** Available column width in twips. */
+  columnWidth: number;
+}
+
+export interface MeasuredLineFragments {
+  /** Number of line boxes produced for this paragraph. */
+  lineCount: number;
+  /** Total inline width of the longest line (twips). Used for widow logic. */
+  maxLineWidth: number;
+  /** Estimated line heights per line (twips). Length === lineCount. */
+  lineHeights: number[];
+}
+
+export interface MeasureInlineObjectInput {
+  /** Width of the embedded object in twips. */
+  widthTwips: number;
+  /** Height of the embedded object in twips. */
+  heightTwips: number;
+  /** Whether the object is floating or inline. */
+  display: "inline" | "floating";
+}
+
+export interface MeasuredInlineObject {
+  widthTwips: number;
+  heightTwips: number;
+  /** How many text lines this object displaces. */
+  displacedLineCount: number;
+}
+
+export interface MeasureTableBlockInput {
+  block: Extract<SurfaceBlockSnapshot, { kind: "table" }>;
+  columnWidth: number;
+}
+
+export interface MeasuredTableBlock {
+  totalHeightTwips: number;
+  /** Per-row measured heights (twips). */
+  rowHeights: number[];
+}
+
+export interface LayoutMeasurementProvider {
+  readonly fidelity: MeasurementFidelity;
+  /**
+   * Resolve when the provider is ready to produce accurate measurements.
+   * Empirical resolves immediately.  Canvas resolves once fonts are available.
+   */
+  whenReady(): Promise<void>;
+
+  measureLineFragments(input: MeasureLineFragmentsInput): MeasuredLineFragments;
+  measureInlineObject(input: MeasureInlineObjectInput): MeasuredInlineObject;
+  measureTableBlock(input: MeasureTableBlockInput): MeasuredTableBlock;
+
+  /** Clear internal caches. Call after font registration changes. */
+  invalidateCache(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Provider selection
+// ---------------------------------------------------------------------------
+
+export type MeasurementBackendPreference = "auto" | "empirical" | "canvas";
+
+export interface CreateMeasurementProviderOptions {
+  preference?: MeasurementBackendPreference;
+  /**
+   * When the canvas backend is selected and the host passes a font loader,
+   * the provider will await `loader.whenReady()` before its own `whenReady`
+   * resolves.
+   */
+  fontLoader?: { whenReady(): Promise<void>; isSupported(): boolean };
+}
+
+/**
+ * Create the default measurement provider for a runtime.
+ *
+ * The factory lives here so that callers only ever import this module and the
+ * backend modules are lazy-loaded (canvas backend is not pulled into SSR
+ * bundles).
+ */
+export async function createMeasurementProvider(
+  options: CreateMeasurementProviderOptions = {},
+): Promise<LayoutMeasurementProvider> {
+  const preference = options.preference ?? "auto";
+  const canvasSupported = canUseCanvas();
+
+  if (preference === "canvas" && !canvasSupported) {
+    // Host requested canvas but we cannot satisfy it; fall back to empirical.
+    return createEmpiricalProvider();
+  }
+
+  if (preference === "empirical" || !canvasSupported) {
+    return createEmpiricalProvider();
+  }
+
+  // auto or canvas with canvas support
+  return createCanvasProvider(options.fontLoader);
+}
+
+/**
+ * Synchronous variant that always returns the empirical backend.
+ *
+ * Used in contexts where the runtime cannot `await` provider construction
+ * (e.g., inside an existing sync factory). The runtime can later swap to the
+ * canvas backend once it resolves via `createMeasurementProvider`.
+ */
+export function createEmpiricalMeasurementProvider(): LayoutMeasurementProvider {
+  return createEmpiricalProvider();
+}
+
+function canUseCanvas(): boolean {
+  if (typeof document === "undefined") return false;
+  try {
+    const canvas = document.createElement("canvas");
+    return typeof canvas.getContext === "function";
+  } catch {
+    return false;
+  }
+}
+
+// The backend implementations live in peer modules.  We keep the empirical
+// backend statically imported so it is available in every runtime (SSR, Node,
+// tests).  The canvas backend uses dynamic import so SSR bundles do not pull
+// it in.
+import { createEmpiricalBackend } from "./measurement-backend-empirical.ts";
+
+function createEmpiricalProvider(): LayoutMeasurementProvider {
+  return createEmpiricalBackend();
+}
+
+async function createCanvasProvider(
+  fontLoader?: CreateMeasurementProviderOptions["fontLoader"],
+): Promise<LayoutMeasurementProvider> {
+  try {
+    const mod = await import("./measurement-backend-canvas.ts");
+    return mod.createCanvasBackend(fontLoader);
+  } catch {
+    return createEmpiricalProvider();
+  }
+}