@beyondwork/docx-react-component 1.0.38 → 1.0.39

package/src/runtime/document-runtime.ts

@@ -82,6 +82,7 @@ import {
   persistedSnapshotFromEditorSessionState,
 } from "../api/session-state.ts";
 import {
+  type CommandExecutionContext,
   executeEditorCommand,
   selectionChanged,
   type CommandOrigin,
@@ -179,6 +180,8 @@ import {
   setCaretAffinity as applyCaretAffinity,
   setActivePageRegion as applyActivePageRegion,
   setActiveObjectFrame as applyActiveObjectFrame,
+  setEditorRole as applyEditorRole,
+  setChromePin as applyChromePins,
   createEditorViewStateSnapshot,
   type ViewState,
 } from "./view-state.ts";
@@ -229,6 +232,24 @@ export interface DocumentRuntime {
   replaceText(text: string, target?: EditorAnchorProjection): void;
   applyActiveStoryTextCommand(command: ActiveStoryTextCommand): TextCommandAck;
   dispatch(command: EditorCommand): void;
+  /**
+   * Apply a command received from a remote collaborator. The command
+   * executes through `executeEditorCommand` exactly like a local dispatch,
+   * but:
+   *   - `onCommandApplied` is NOT fired (no echo back to the network)
+   *   - the local undo/redo history is NOT mutated (remote edits are
+   *     not undoable by the local user)
+   *   - local workflow/blocked-command checks are bypassed (the remote
+   *     already performed them)
+   *
+   * Used by runtime-level collaboration sync to replay `CommandEvent`s
+   * from the shared event log.
+   */
+  applyRemoteCommand(
+    command: EditorCommand,
+    context: CommandExecutionContext,
+    meta?: Partial<CommandAppliedMeta>,
+  ): void;
   emitBlockedCommand(command: string, reasons: WorkflowBlockedCommandReason[]): void;
   undo(): void;
   redo(): void;
@@ -255,6 +276,8 @@ export interface DocumentRuntime {
   getProtectionSnapshot(): ProtectionSnapshot;
   setWorkspaceMode(mode: WorkspaceMode): void;
   setZoom(level: ZoomLevel): void;
+  setEditorRole(role: import("./view-state.ts").ViewState["editorRole"]): void;
+  setChromePin(surface: import("../api/public-types.ts").ChromePinSurface, pin: import("../api/public-types.ts").PinState | null): void;
   getPageLayoutSnapshot(): PageLayoutSnapshot | null;
   getDocumentNavigationSnapshot(): DocumentNavigationSnapshot;
   /**
@@ -319,6 +342,11 @@ export interface DocumentRuntime {
   ): RuntimeContextAnalyticsSnapshot | null;
 }
 
+export interface CommandAppliedMeta {
+  preSelection: import("../core/state/editor-state.ts").SelectionSnapshot;
+  activeStory: EditorStoryTarget;
+}
+
 export interface CreateDocumentRuntimeOptions {
   documentId: string;
   initialSessionState?: EditorSessionState;
@@ -338,6 +366,23 @@ export interface CreateDocumentRuntimeOptions {
   onEvent?: (event: DocumentRuntimeEvent) => void;
   onWarning?: (warning: EditorWarning) => void;
   onError?: (error: EditorError) => void;
+  /**
+   * Fired AFTER a command has been applied locally via `dispatch()` or
+   * `applyActiveStoryTextCommand()`. Used by collaboration sync to
+   * broadcast the command to remote clients. NOT fired for remote commands
+   * applied via `applyRemoteCommand()` — this prevents echo loops.
+   *
+   * Not fired for:
+   * - `history.undo` / `history.redo` (applied via `applyHistory()` which
+   *   does not pass through `commit()`'s new hook call site)
+   * - Remote replays applied via `applyRemoteCommand()`
+   */
+  onCommandApplied?: (
+    command: EditorCommand,
+    transaction: EditorTransaction,
+    context: CommandExecutionContext,
+    meta: CommandAppliedMeta,
+  ) => void;
   initialViewState?: Partial<ViewState>;
   protectionSnapshot?: ProtectionSnapshot;
 }
@@ -1611,12 +1656,40 @@ export function createDocumentRuntime(
         return;
       }
       try {
-        const transaction = executeEditorCommand(state, command, {
-          timestamp: command.origin?.timestamp ?? clock(),
+        const context = {
+          timestamp: normalizeCommandTimestamp(command.origin?.timestamp) ?? clock(),
           documentMode: getEffectiveDocumentMode(commandSelection),
           defaultAuthorId: defaultAuthorId ?? undefined,
-        });
+        } as const;
+        const preSelection = commandSelection;
+        const preActiveStory = activeStory;
+        const transaction = executeEditorCommand(state, command, context);
         commit(transaction);
+        options.onCommandApplied?.(command, transaction, context, {
+          preSelection,
+          activeStory: preActiveStory,
+        });
+      } catch (error) {
+        emitError(toRuntimeError(error));
+      }
+    },
+    applyRemoteCommand(command, context, meta) {
+      try {
+        if (command.type === "history.undo" || command.type === "history.redo") {
+          return;
+        }
+        if (meta?.activeStory && !storyTargetsEqual(meta.activeStory, activeStory)) {
+          activeStory = meta.activeStory;
+          storySelections.set(
+            storyTargetKey(activeStory),
+            meta.preSelection ?? state.selection,
+          );
+        }
+        const replayState = meta?.preSelection
+          ? { ...state, selection: meta.preSelection }
+          : state;
+        const transaction = executeEditorCommand(replayState, command, context);
+        commitRemote(transaction);
       } catch (error) {
         emitError(toRuntimeError(error));
       }
@@ -1890,6 +1963,20 @@ export function createDocumentRuntime(
         listener();
       }
     },
+    setEditorRole(role) {
+      viewState = applyEditorRole(viewState, role);
+      cachedRenderSnapshot = refreshRenderSnapshot();
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    setChromePin(surface, pin) {
+      viewState = applyChromePins(viewState, surface, pin);
+      cachedRenderSnapshot = refreshRenderSnapshot();
+      for (const listener of listeners) {
+        listener();
+      }
+    },
     getPageLayoutSnapshot() {
       return getCachedPageLayoutSnapshot(state, activeStory);
     },
@@ -2346,13 +2433,21 @@ export function createDocumentRuntime(
   }
 
   function commit(transaction: EditorTransaction): void {
-    const previous = state;
-
     if (transaction.historyBoundary === "push") {
       history.past.push(state);
       history.future = [];
     }
 
+    applyTransactionToState(transaction);
+  }
+
+  function commitRemote(transaction: EditorTransaction): void {
+    applyTransactionToState(transaction);
+  }
+
+  function applyTransactionToState(transaction: EditorTransaction): void {
+    const previous = state;
+
     protectionSnapshot = remapProtectionSnapshot(protectionSnapshot, transaction.mapping);
     state = finalizeState(transaction.nextState, transaction.markDirty, clock());
     storySelections.set(storyTargetKey(activeStory), state.selection);
@@ -2562,13 +2657,13 @@ export function createDocumentRuntime(
 
   function applyTextCommandInActiveStory(
     command: ActiveStoryTextCommand,
-    options: {
+    textOptions: {
       selection?: EditorState["selection"];
       blockedCommandName?: string;
     } = {},
   ): TextCommandAck {
     const opId = (command.origin as { opId?: string } | undefined)?.opId;
-    const selection = options.selection ?? state.selection;
+    const selection = textOptions.selection ?? state.selection;
     if (
       activeStory.kind !== "main" &&
       getEffectiveDocumentMode(selection) === "suggesting" &&
@@ -2578,7 +2673,7 @@ export function createDocumentRuntime(
       emit({
         type: "command_blocked",
         documentId: state.documentId,
-        command: options.blockedCommandName ?? command.type,
+        command: textOptions.blockedCommandName ?? command.type,
         reasons: [{
           code: "suggesting_unsupported",
           message,
@@ -2597,7 +2692,7 @@ export function createDocumentRuntime(
       emit({
         type: "command_blocked",
         documentId: state.documentId,
-        command: options.blockedCommandName ?? command.type,
+        command: textOptions.blockedCommandName ?? command.type,
         reasons: blockedReasons,
       });
       return {
@@ -2608,7 +2703,7 @@ export function createDocumentRuntime(
       };
     }
 
-    const timestamp = command.origin?.timestamp ?? clock();
+    const timestamp = normalizeCommandTimestamp(command.origin?.timestamp) ?? clock();
     const context = {
       timestamp,
       documentMode: getEffectiveDocumentMode(selection),
@@ -2621,9 +2716,15 @@ export function createDocumentRuntime(
           selection,
         };
 
+    const preSelection = selection;
+    const preActiveStory = activeStory;
     if (activeStory.kind === "main") {
       const mainTransaction = executeEditorCommand(baseState, command, context);
       commit(mainTransaction);
+      options.onCommandApplied?.(command, mainTransaction, context, {
+        preSelection,
+        activeStory: preActiveStory,
+      });
       return classifyAck({
         command,
         opId,
@@ -2682,16 +2783,17 @@ export function createDocumentRuntime(
         activeStory,
       ),
     };
+    const broadcastCommand: EditorCommand = {
+      type: "document.replace",
+      document: nextDocumentWithReview,
+      selection: localTransaction.nextState.selection,
+      mapping: createEmptyMapping(),
+      protectionSelection: selection,
+      origin: command.origin,
+    };
     const fullTransaction = executeEditorCommand(
       baseState,
-      {
-        type: "document.replace",
-        document: nextDocumentWithReview,
-        selection: localTransaction.nextState.selection,
-        mapping: createEmptyMapping(),
-        protectionSelection: selection,
-        origin: command.origin,
-      },
+      broadcastCommand,
       context,
     );
 
@@ -2700,6 +2802,10 @@ export function createDocumentRuntime(
       effects: mergeTransactionEffects(fullTransaction.effects, localTransaction.effects),
     };
     commit(mergedTransaction);
+    options.onCommandApplied?.(broadcastCommand, mergedTransaction, context, {
+      preSelection,
+      activeStory: preActiveStory,
+    });
     return classifyAck({
       command,
       opId,
@@ -2988,6 +3094,16 @@ function createEntityId(
   return nextId;
 }
 
+function normalizeCommandTimestamp(value: unknown): string | undefined {
+  if (typeof value === "string" && value.length > 0) {
+    return value;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return new Date(value).toISOString();
+  }
+  return undefined;
+}
+
 function finalizeState(
   state: EditorState,
   markDirty: boolean,

package/src/runtime/layout/index.ts

@@ -158,6 +158,8 @@ export {
   type EmbeddedFontBytes,
 } from "./docx-font-loader.ts";
 
+export { createCanvasBackend } from "./measurement-backend-canvas.ts";
+
 // ---------------------------------------------------------------------------
 // Public facet (Phase 7)
 // ---------------------------------------------------------------------------

package/src/runtime/layout/inert-layout-facet.ts

@@ -51,6 +51,8 @@ export function createInertLayoutFacet(): WordReviewEditorLayoutFacet {
     getMeasurement: () => null,
     getMeasurementFidelity: () => fidelity,
     whenMeasurementReady: () => Promise.resolve(),
+    getFirstPageIndexForBlock: () => null,
+    swapMeasurementProvider: () => undefined,
     getTableRenderPlan: () => null,
     getDirtyFieldFamilies: () => [],
     getFieldDirtinessReport: () => emptyReport,

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 };
+}