@beyondwork/docx-react-component 1.0.41 → 1.0.42

package/src/runtime/document-runtime.ts

@@ -319,6 +319,7 @@ export interface DocumentRuntime {
   getSuggestionsSnapshot(): SuggestionsSnapshot;
   setWorkflowOverlay(overlay: WorkflowOverlay): void;
   clearWorkflowOverlay(): void;
+  getWorkflowOverlay(): WorkflowOverlay | null;
   getWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null;
   getInteractionGuardSnapshot(): InteractionGuardSnapshot;
   getWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot;
@@ -1662,11 +1663,34 @@ export function createDocumentRuntime(
         applyHistory("redo");
         return;
       }
+
+      if (isRuntimeStateOverlayCommand(command)) {
+        applyRuntimeStateOverlayCommand(command);
+        const context = {
+          timestamp: normalizeCommandTimestamp(command.origin?.timestamp) ?? clock(),
+          documentMode: getEffectiveDocumentMode(commandSelection),
+          defaultAuthorId: defaultAuthorId ?? undefined,
+        } as const;
+        const noopTransaction: EditorTransaction = {
+          nextState: state,
+          mapping: createEmptyMapping(),
+          effects: { warningsAdded: [], warningsCleared: [] },
+          historyBoundary: "skip",
+          markDirty: false,
+        };
+        options.onCommandApplied?.(command, noopTransaction, context, {
+          preSelection: state.selection,
+          activeStory,
+        });
+        return;
+      }
+
       try {
         const context = {
           timestamp: normalizeCommandTimestamp(command.origin?.timestamp) ?? clock(),
           documentMode: getEffectiveDocumentMode(commandSelection),
           defaultAuthorId: defaultAuthorId ?? undefined,
+          renderSnapshot: cachedRenderSnapshot,
         } as const;
         const preSelection = commandSelection;
         const preActiveStory = activeStory;
@@ -1685,6 +1709,10 @@ export function createDocumentRuntime(
         if (command.type === "history.undo" || command.type === "history.redo") {
           return;
         }
+        if (isRuntimeStateOverlayCommand(command)) {
+          applyRuntimeStateOverlayCommand(command);
+          return;
+        }
         if (meta?.activeStory && !storyTargetsEqual(meta.activeStory, activeStory)) {
           activeStory = meta.activeStory;
           storySelections.set(
@@ -1695,7 +1723,17 @@ export function createDocumentRuntime(
         const replayState = meta?.preSelection
           ? { ...state, selection: meta.preSelection }
           : state;
-        const transaction = executeEditorCommand(replayState, command, context);
+        const replaySnapshot = meta?.preSelection
+          ? {
+              ...cachedRenderSnapshot,
+              selection: toPublicSelectionSnapshot(meta.preSelection, activeStory),
+            }
+          : cachedRenderSnapshot;
+        const replayContext = {
+          ...context,
+          renderSnapshot: replaySnapshot,
+        };
+        const transaction = executeEditorCommand(replayState, command, replayContext);
         commitRemote(transaction);
       } catch (error) {
         emitError(toRuntimeError(error));
@@ -2156,6 +2194,9 @@ export function createDocumentRuntime(
         state.selection.head,
         activeStory,
         options,
+        // P5 — TOC entries print Word's display number (honors page-
+        // number restarts), not the raw 0-based pageIndex+1.
+        (pageIndex: number) => layoutFacet.getDisplayPageNumber(pageIndex),
       );
       if (refreshed.changed) {
         this.dispatch({
@@ -2224,47 +2265,20 @@ export function createDocumentRuntime(
       return result;
     },
     setWorkflowOverlay(overlay) {
-      workflowOverlay = structuredClone(overlay);
-      cachedRenderSnapshot = refreshRenderSnapshot();
-      const snapshot = deriveWorkflowScopeSnapshot()!;
-      emit({
-        type: "workflow_overlay_changed",
-        documentId: state.documentId,
-        snapshot,
+      this.dispatch({
+        type: "workflow.set-overlay",
+        overlay,
+        origin: createOrigin("api", clock()),
       });
-      if (workflowOverlay.activeWorkItemId !== undefined) {
-        emit({
-          type: "workflow_active_work_item_changed",
-          documentId: state.documentId,
-          activeWorkItemId: workflowOverlay.activeWorkItemId ?? null,
-        });
-      }
-      for (const listener of listeners) {
-        listener();
-      }
     },
     clearWorkflowOverlay() {
-      workflowOverlay = null;
-      cachedRenderSnapshot = refreshRenderSnapshot();
-      emit({
-        type: "workflow_active_work_item_changed",
-        documentId: state.documentId,
-        activeWorkItemId: null,
-      });
-      emit({
-        type: "workflow_overlay_changed",
-        documentId: state.documentId,
-        snapshot: {
-          overlayPresent: false,
-          activeWorkItemId: null,
-          scopes: [],
-          candidates: [],
-          blockedReasons: [],
-        },
+      this.dispatch({
+        type: "workflow.clear-overlay",
+        origin: createOrigin("api", clock()),
       });
-      for (const listener of listeners) {
-        listener();
-      }
+    },
+    getWorkflowOverlay() {
+      return workflowOverlay;
     },
     getWorkflowScopeSnapshot() {
       return getCachedWorkflowScopeSnapshot();
@@ -2276,77 +2290,46 @@ export function createDocumentRuntime(
       return getCachedWorkflowMarkupSnapshot();
     },
     setWorkflowMetadataDefinitions(definitions) {
-      workflowMetadataDefinitions = structuredClone(definitions);
-      const snapshot = deriveWorkflowMetadataSnapshot();
-      emit({
-        type: "workflow_metadata_changed",
-        documentId: state.documentId,
-        snapshot,
+      this.dispatch({
+        type: "workflow.set-metadata-definitions",
+        definitions,
+        origin: createOrigin("api", clock()),
       });
-      for (const listener of listeners) {
-        listener();
-      }
     },
     clearWorkflowMetadataDefinitions() {
-      workflowMetadataDefinitions = [];
-      const snapshot = deriveWorkflowMetadataSnapshot();
-      emit({
-        type: "workflow_metadata_changed",
-        documentId: state.documentId,
-        snapshot,
+      this.dispatch({
+        type: "workflow.clear-metadata-definitions",
+        origin: createOrigin("api", clock()),
       });
-      for (const listener of listeners) {
-        listener();
-      }
     },
     setWorkflowMetadataEntries(entries) {
-      workflowMetadataEntries = structuredClone(entries);
-      const snapshot = deriveWorkflowMetadataSnapshot();
-      emit({
-        type: "workflow_metadata_changed",
-        documentId: state.documentId,
-        snapshot,
+      this.dispatch({
+        type: "workflow.set-metadata-entries",
+        entries,
+        origin: createOrigin("api", clock()),
       });
-      for (const listener of listeners) {
-        listener();
-      }
     },
     clearWorkflowMetadataEntries() {
-      workflowMetadataEntries = [];
-      const snapshot = deriveWorkflowMetadataSnapshot();
-      emit({
-        type: "workflow_metadata_changed",
-        documentId: state.documentId,
-        snapshot,
+      this.dispatch({
+        type: "workflow.clear-metadata-entries",
+        origin: createOrigin("api", clock()),
       });
-      for (const listener of listeners) {
-        listener();
-      }
     },
     getWorkflowMetadataSnapshot() {
       return deriveWorkflowMetadataSnapshot();
     },
     setHostAnnotationOverlay(overlay) {
-      hostAnnotationOverlay = structuredClone(overlay);
-      emit({
-        type: "host_annotation_overlay_changed",
-        documentId: state.documentId,
-        snapshot: deriveHostAnnotationSnapshot(),
+      this.dispatch({
+        type: "host-annotation.set-overlay",
+        overlay,
+        origin: createOrigin("api", clock()),
       });
-      for (const listener of listeners) {
-        listener();
-      }
     },
     clearHostAnnotationOverlay() {
-      hostAnnotationOverlay = null;
-      emit({
-        type: "host_annotation_overlay_changed",
-        documentId: state.documentId,
-        snapshot: deriveHostAnnotationSnapshot(),
+      this.dispatch({
+        type: "host-annotation.clear-overlay",
+        origin: createOrigin("api", clock()),
       });
-      for (const listener of listeners) {
-        listener();
-      }
     },
     getHostAnnotationSnapshot() {
       return deriveHostAnnotationSnapshot();
@@ -2480,9 +2463,14 @@ export function createDocumentRuntime(
     // Font-loader refresh on subParts identity change — this is the
     // lightweight proxy for "a change that could affect which fonts the
     // canvas backend measures against".  Typing edits don't rebuild
-    // subParts; style + font + numbering imports do.
+    // subParts; style + font + numbering imports do.  Hardening: also
+    // invalidate the measurement provider's glyph cache AND the engine's
+    // cached graph so the next pagination run re-measures with the
+    // newly-registered FontFaces (pre-hardening the canvas backend kept
+    // returning pre-refresh widths from its cache).
     if (previous.document.subParts !== state.document.subParts) {
       fontLoader.refresh(collectFontLoaderInput(state.document));
+      layoutEngine.invalidateMeasurementCache();
     }
 
     cachedRenderSnapshot = refreshRenderSnapshot();
@@ -2715,6 +2703,7 @@ export function createDocumentRuntime(
       timestamp,
       documentMode: getEffectiveDocumentMode(selection),
       defaultAuthorId: defaultAuthorId ?? undefined,
+      renderSnapshot: cachedRenderSnapshot,
     } as const;
     const baseState = selection === state.selection
       ? state
@@ -2953,6 +2942,109 @@ export function createDocumentRuntime(
     }
   }
 
+  function applyRuntimeStateOverlayCommand(
+    command: RuntimeStateOverlayCommand,
+  ): void {
+    switch (command.type) {
+      case "workflow.set-overlay": {
+        workflowOverlay = structuredClone(command.overlay);
+        cachedRenderSnapshot = refreshRenderSnapshot();
+        const snapshot = deriveWorkflowScopeSnapshot()!;
+        emit({
+          type: "workflow_overlay_changed",
+          documentId: state.documentId,
+          snapshot,
+        });
+        if (workflowOverlay.activeWorkItemId !== undefined) {
+          emit({
+            type: "workflow_active_work_item_changed",
+            documentId: state.documentId,
+            activeWorkItemId: workflowOverlay.activeWorkItemId ?? null,
+          });
+        }
+        break;
+      }
+      case "workflow.clear-overlay": {
+        workflowOverlay = null;
+        cachedRenderSnapshot = refreshRenderSnapshot();
+        emit({
+          type: "workflow_active_work_item_changed",
+          documentId: state.documentId,
+          activeWorkItemId: null,
+        });
+        emit({
+          type: "workflow_overlay_changed",
+          documentId: state.documentId,
+          snapshot: {
+            overlayPresent: false,
+            activeWorkItemId: null,
+            scopes: [],
+            candidates: [],
+            blockedReasons: [],
+          },
+        });
+        break;
+      }
+      case "workflow.set-metadata-definitions": {
+        workflowMetadataDefinitions = structuredClone(command.definitions);
+        emit({
+          type: "workflow_metadata_changed",
+          documentId: state.documentId,
+          snapshot: deriveWorkflowMetadataSnapshot(),
+        });
+        break;
+      }
+      case "workflow.clear-metadata-definitions": {
+        workflowMetadataDefinitions = [];
+        emit({
+          type: "workflow_metadata_changed",
+          documentId: state.documentId,
+          snapshot: deriveWorkflowMetadataSnapshot(),
+        });
+        break;
+      }
+      case "workflow.set-metadata-entries": {
+        workflowMetadataEntries = structuredClone(command.entries);
+        emit({
+          type: "workflow_metadata_changed",
+          documentId: state.documentId,
+          snapshot: deriveWorkflowMetadataSnapshot(),
+        });
+        break;
+      }
+      case "workflow.clear-metadata-entries": {
+        workflowMetadataEntries = [];
+        emit({
+          type: "workflow_metadata_changed",
+          documentId: state.documentId,
+          snapshot: deriveWorkflowMetadataSnapshot(),
+        });
+        break;
+      }
+      case "host-annotation.set-overlay": {
+        hostAnnotationOverlay = structuredClone(command.overlay);
+        emit({
+          type: "host_annotation_overlay_changed",
+          documentId: state.documentId,
+          snapshot: deriveHostAnnotationSnapshot(),
+        });
+        break;
+      }
+      case "host-annotation.clear-overlay": {
+        hostAnnotationOverlay = null;
+        emit({
+          type: "host_annotation_overlay_changed",
+          documentId: state.documentId,
+          snapshot: deriveHostAnnotationSnapshot(),
+        });
+        break;
+      }
+    }
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+
   function emitInternal(event: DocumentRuntimeEvent): void {
     options.onEvent?.(event);
     for (const listener of eventListeners) {
@@ -3111,6 +3203,39 @@ function normalizeCommandTimestamp(value: unknown): string | undefined {
   return undefined;
 }
 
+type RuntimeStateOverlayCommand = Extract<
+  EditorCommand,
+  {
+    type:
+      | "workflow.set-overlay"
+      | "workflow.clear-overlay"
+      | "workflow.set-metadata-definitions"
+      | "workflow.clear-metadata-definitions"
+      | "workflow.set-metadata-entries"
+      | "workflow.clear-metadata-entries"
+      | "host-annotation.set-overlay"
+      | "host-annotation.clear-overlay";
+  }
+>;
+
+function isRuntimeStateOverlayCommand(
+  command: EditorCommand,
+): command is RuntimeStateOverlayCommand {
+  switch (command.type) {
+    case "workflow.set-overlay":
+    case "workflow.clear-overlay":
+    case "workflow.set-metadata-definitions":
+    case "workflow.clear-metadata-definitions":
+    case "workflow.set-metadata-entries":
+    case "workflow.clear-metadata-entries":
+    case "host-annotation.set-overlay":
+    case "host-annotation.clear-overlay":
+      return true;
+    default:
+      return false;
+  }
+}
+
 function finalizeState(
   state: EditorState,
   markDirty: boolean,
@@ -3684,6 +3809,14 @@ const NON_MUTATION_COMMANDS = new Set([
   "warning.add",
   "warning.clear",
   "comment.open",
+  "workflow.set-overlay",
+  "workflow.clear-overlay",
+  "workflow.set-metadata-definitions",
+  "workflow.clear-metadata-definitions",
+  "workflow.set-metadata-entries",
+  "workflow.clear-metadata-entries",
+  "host-annotation.set-overlay",
+  "host-annotation.clear-overlay",
 ]);
 
 /** Mutation commands that are not yet supported in suggesting mode. */
@@ -4008,6 +4141,7 @@ function refreshDocumentTableOfContents(
   selectionHead: number,
   activeStory: EditorStoryTarget,
   options?: TocRefreshOptions,
+  resolveDisplayPageNumber?: (pageIndex: number) => number | null,
 ): {
   document: CanonicalDocumentEnvelope;
   result: TocRefreshResult;
@@ -4038,7 +4172,7 @@ function refreshDocumentTableOfContents(
     }
     const nextField: FieldNode = {
       ...field,
-      children: buildTocInlineNodes(entries),
+      children: buildTocInlineNodes(entries, resolveDisplayPageNumber),
       refreshStatus: "current",
     };
     if (flattenInlineDisplayText(nextField.children) !== flattenInlineDisplayText(field.children)) {
@@ -4221,14 +4355,26 @@ function buildInlineNodesFromDisplayText(text: string): InlineNode[] {
   return children;
 }
 
+/**
+ * P5 — TOC entry rendering with display-number resolution.  When
+ * `resolveDisplayPageNumber` is supplied, TOC entries print the number
+ * Word would print on the page (honors `w:pgNumType/@w:start` restarts
+ * for front-matter roman numerals → body arabic restart).  Without the
+ * resolver, falls back to the raw `pageIndex + 1` (pre-P5 behavior).
+ */
 function buildTocInlineNodes(
   entries: ReadonlyArray<{ level: number; text: string; pageIndex: number }>,
+  resolveDisplayPageNumber?: (pageIndex: number) => number | null,
 ): InlineNode[] {
   const children: InlineNode[] = [];
   entries.forEach((entry, index) => {
     children.push({ type: "text", text: entry.text });
     children.push({ type: "tab" });
-    children.push({ type: "text", text: String(entry.pageIndex + 1) });
+    const displayed = resolveDisplayPageNumber?.(entry.pageIndex);
+    children.push({
+      type: "text",
+      text: String(displayed ?? entry.pageIndex + 1),
+    });
     if (index < entries.length - 1) {
       children.push({ type: "hard_break" });
     }
@@ -4236,6 +4382,14 @@ function buildTocInlineNodes(
   return children;
 }
 
+/** Test-only export of `buildTocInlineNodes` (P5 unit tests). */
+export function __buildTocInlineNodes(
+  entries: ReadonlyArray<{ level: number; text: string; pageIndex: number }>,
+  resolveDisplayPageNumber?: (pageIndex: number) => number | null,
+): InlineNode[] {
+  return buildTocInlineNodes(entries, resolveDisplayPageNumber);
+}
+
 function collectFieldsFromSubParts(
   subParts: SubPartsCatalog | undefined,
   entries: FieldEntrySnapshot[],
@@ -4575,8 +4729,38 @@ function remapProtectionSnapshot(
  * let the loader register system fonts it finds via
  * `document.fonts.check(...)`.
  */
+// P14.d — memoize the font-family walk by `(content, styles)` reference
+// identity.  Both shapes change identity only on a real edit / import /
+// style mutation; per-keystroke edits keep the same references because
+// `finalizeState` shallow-spreads `state.document`.  WeakMap two-level
+// cache so the entries free with the documents that own them.
+const fontLoaderInputCache = new WeakMap<
+  object,
+  WeakMap<object, { families: readonly string[] }>
+>();
+
 function collectFontLoaderInput(
   document: CanonicalDocumentEnvelope,
+): { families: readonly string[] } {
+  const contentKey = document.content as unknown as object;
+  const stylesKey = (document.styles ?? FONT_LOADER_EMPTY_STYLES_KEY) as unknown as object;
+  let stylesCache = fontLoaderInputCache.get(contentKey);
+  if (stylesCache) {
+    const cached = stylesCache.get(stylesKey);
+    if (cached) return cached;
+  } else {
+    stylesCache = new WeakMap();
+    fontLoaderInputCache.set(contentKey, stylesCache);
+  }
+  const result = collectFontLoaderInputUncached(document);
+  stylesCache.set(stylesKey, result);
+  return result;
+}
+
+const FONT_LOADER_EMPTY_STYLES_KEY = Object.freeze({});
+
+function collectFontLoaderInputUncached(
+  document: CanonicalDocumentEnvelope,
 ): { families: readonly string[] } {
   try {
     const families = new Set<string>();
@@ -4604,6 +4788,9 @@ function collectFontLoaderInput(
   }
 }
 
+/** Test-only export of the uncached walk so memoization tests can spy on it. */
+export const __collectFontLoaderInputUncached = collectFontLoaderInputUncached;
+
 /**
  * Asynchronously upgrade the engine's measurement backend to canvas once
  * the platform supports it and fonts have resolved.  Errors are swallowed

package/src/runtime/external-send-runtime.ts

@@ -0,0 +1,117 @@
+import {
+  sendToExternal,
+  type SendToExternalBlock,
+  type SendToExternalResult,
+} from "../io/export/external-send.ts";
+import type {
+  ExternalCustodyResolver,
+} from "../api/external-custody-types.ts";
+import type { CollabSessionBridge } from "./collab-session-bridge.ts";
+import { resignPayload } from "./resign-payload.ts";
+import type { PayloadSigner } from "../io/ooxml/payload-signature.ts";
+import type { TamperGate } from "./tamper-gate.ts";
+
+/**
+ * Runtime-level composition of the P7 pure pipeline with:
+ *   - the P8c `CollabSessionBridge` (snapshots of negotiation /
+ *     presentation / participants)
+ *   - the P8e `TamperGate` (blocks when `metadataIntegrity === "tampered"`)
+ *   - the P8a `resignPayload()` hook (every write re-signs)
+ *
+ * Callers supply the raw workflow-payload XML alongside the collab
+ * state. On success the result carries:
+ *   - the custody receipt (to be emitted inside bw:extensions)
+ *   - the kept snapshots (to replace the pre-send facet state)
+ *   - the re-signed payload XML (to persist in the shipped docx)
+ *
+ * This helper does NOT rewrite `word/document.xml` / `word/comments.xml`
+ * or the three companion parts; the caller owns the zip rewrite using
+ * `result.stripped.commentIds`. This keeps the runtime layer isolated
+ * from OPC packaging.
+ */
+export interface RuntimeSendToExternalArgs {
+  bridge: CollabSessionBridge;
+  tamperGate: TamperGate;
+  signer: PayloadSigner;
+
+  /** The raw `<bw:workflowPayload …>…</bw:workflowPayload>` XML. */
+  payloadXml: string;
+
+  role: "author" | "reviewer" | "observer";
+
+  originDocumentId: string;
+  originPayloadId: string;
+  /** sha256:{hex} of canonicalized word/document.xml at send time. */
+  originContentHash: string;
+
+  resolver: ExternalCustodyResolver;
+  recipient: string;
+  sentBy: string;
+  archiveRef: string;
+
+  /** Optional deterministic overrides for tests. */
+  custodyId?: string;
+  now?: string;
+}
+
+export type RuntimeSendToExternalResult =
+  | { ok: false; reason: "collab_role_restricted" }
+  | { ok: false; reason: "metadata_tampered" }
+  | {
+      ok: true;
+      custody: SendToExternalResult["custody"];
+      kept: SendToExternalResult["kept"];
+      stripped: SendToExternalResult["stripped"];
+      /** Re-signed `<bw:workflowPayload …>…</bw:workflowPayload>` ready to persist. */
+      payloadXml: string;
+    };
+
+export async function runtimeSendToExternal(
+  args: RuntimeSendToExternalArgs,
+): Promise<RuntimeSendToExternalResult> {
+  const guard = args.tamperGate.guard();
+  if (!guard.ok) {
+    return { ok: false, reason: guard.reason };
+  }
+
+  const presentation = args.bridge.getCommentPresentationSnapshot();
+  const negotiation = args.bridge.getCommentNegotiationSnapshot();
+  const participants = args.bridge.getParticipantRoster();
+
+  const pipelineArgs = {
+    presentation,
+    negotiation,
+    participants,
+    role: args.role,
+    metadataIntegrity:
+      args.tamperGate.state === "unsigned" ? "verified" : args.tamperGate.state,
+    originDocumentId: args.originDocumentId,
+    originPayloadId: args.originPayloadId,
+    originContentHash: args.originContentHash,
+    resolver: args.resolver,
+    recipient: args.recipient,
+    sentBy: args.sentBy,
+    archiveRef: args.archiveRef,
+    ...(args.custodyId !== undefined ? { custodyId: args.custodyId } : {}),
+    ...(args.now !== undefined ? { now: args.now } : {}),
+  } as const;
+
+  const pipeline: SendToExternalBlock = await sendToExternal(pipelineArgs);
+  if (!pipeline.ok) {
+    return { ok: false, reason: pipeline.reason };
+  }
+
+  const { payloadXml } = await resignPayload({
+    payloadXml: args.payloadXml,
+    signer: args.signer,
+    ...(args.now !== undefined ? { now: args.now } : {}),
+  });
+
+  return {
+    ok: true,
+    custody: pipeline.result.custody,
+    kept: pipeline.result.kept,
+    stripped: pipeline.result.stripped,
+    payloadXml,
+  };
+}