@beyondwork/docx-react-component 1.0.37 → 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,
@@ -124,11 +125,16 @@ import {
   findPageForOffset,
 } from "./document-navigation.ts";
 import {
+  createDocxFontLoader,
   createLayoutEngine,
   createLayoutFacet,
+  createMeasurementProvider,
+  type DocxFontLoader,
   type LayoutEngineInstance,
+  type LayoutMeasurementProvider,
   type WordReviewEditorLayoutFacet,
 } from "./layout/index.ts";
+import { createRenderKernel, type RenderKernel } from "./render/index.ts";
 import {
   createDocumentOutlineSnapshot,
   createDocumentSectionSnapshots,
@@ -174,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";
@@ -224,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;
@@ -250,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;
   /**
@@ -314,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;
@@ -333,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;
 }
@@ -405,7 +455,20 @@ export function createDocumentRuntime(
   // The engine caches graph + resolved-formatting + fragment mapper keyed on
   // (content, styles, subParts).  It is the single internal source of truth
   // for page composition, story resolution, and layout invalidation.
+  //
+  // R0 measurement wiring: the engine starts with the sync empirical backend
+  // so the runtime is available immediately, then we kick off
+  // `createMeasurementProvider({ preference: "auto", fontLoader })` which
+  // upgrades to the canvas backend once fonts resolve.  `swapMeasurementProvider`
+  // emits `measurement_backend_ready` so chrome consumers can re-read metrics.
   const layoutEngine: LayoutEngineInstance = createLayoutEngine();
+  const fontLoader: DocxFontLoader = createDocxFontLoader(
+    collectFontLoaderInput(state.document),
+  );
+  void upgradeMeasurementProvider(layoutEngine, fontLoader);
+  // `renderKernelRef` is a forward reference so the facet can reach the
+  // kernel after it is created below (kernel creation needs the facet).
+  let renderKernelRef: RenderKernel | null = null;
   const layoutFacet: WordReviewEditorLayoutFacet = createLayoutFacet({
     engine: layoutEngine,
     getQueryInput: () => ({
@@ -416,6 +479,27 @@ export function createDocumentRuntime(
         zoomLevel: viewState.zoomLevel,
       },
     }),
+    renderKernel: () => renderKernelRef,
+    getWorkflowRailInput: () => {
+      if (!workflowOverlay) return null;
+      const activeWorkItemId = workflowOverlay.activeWorkItemId ?? null;
+      const activeWorkItem =
+        activeWorkItemId !== null
+          ? workflowOverlay.workItems?.find(
+              (item) => item.workItemId === activeWorkItemId,
+            )
+          : undefined;
+      return {
+        scopes: workflowOverlay.scopes,
+        candidates: workflowOverlay.candidates,
+        activeWorkItemScopeIds: activeWorkItem?.scopeIds ?? [],
+        activeStory,
+      };
+    },
+  });
+  renderKernelRef = createRenderKernel({
+    facet: layoutFacet,
+    getActiveStory: () => activeStory,
   });
   let cachedSurface:
     | {
@@ -1572,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));
       }
@@ -1851,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);
     },
@@ -2307,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);
@@ -2336,6 +2470,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.
+    if (previous.document.subParts !== state.document.subParts) {
+      fontLoader.refresh(collectFontLoaderInput(state.document));
+    }
+
     cachedRenderSnapshot = refreshRenderSnapshot();
     notify(previous, state, transaction);
   }
@@ -2515,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" &&
@@ -2531,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,
@@ -2550,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 {
@@ -2561,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),
@@ -2574,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,
@@ -2635,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,
     );
 
@@ -2653,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,
@@ -2941,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,
@@ -4390,3 +4553,70 @@ function remapProtectionSnapshot(
     preservedRangeCount: nextRanges.filter((range) => !range.enforced).length,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Measurement provider wiring (R0)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the initial input the `DocxFontLoader` needs: a list of font
+ * families the document actively uses, plus any embedded font payloads the
+ * import pipeline may have extracted.
+ *
+ * Walks the document content tree once per call.  Embedded font extraction
+ * is not yet wired into the canonical model; we pass an empty map today and
+ * let the loader register system fonts it finds via
+ * `document.fonts.check(...)`.
+ */
+function collectFontLoaderInput(
+  document: CanonicalDocumentEnvelope,
+): { families: readonly string[] } {
+  try {
+    const families = new Set<string>();
+    const visit = (node: unknown): void => {
+      if (!node || typeof node !== "object") return;
+      const record = node as Record<string, unknown>;
+      const rpr = record["runProperties"] as
+        | Record<string, unknown>
+        | undefined;
+      if (rpr && typeof rpr["fontFamily"] === "string") {
+        families.add(rpr["fontFamily"] as string);
+      }
+      for (const value of Object.values(record)) {
+        if (Array.isArray(value)) value.forEach(visit);
+        else if (value && typeof value === "object") visit(value);
+      }
+    };
+    visit(document.content);
+    if (document.styles) {
+      visit(document.styles);
+    }
+    return { families: Array.from(families) };
+  } catch {
+    return { families: [] };
+  }
+}
+
+/**
+ * Asynchronously upgrade the engine's measurement backend to canvas once
+ * the platform supports it and fonts have resolved.  Errors are swallowed
+ * so a failure in the upgrade path can never break the empirical baseline.
+ */
+async function upgradeMeasurementProvider(
+  engine: LayoutEngineInstance,
+  fontLoader: DocxFontLoader,
+): Promise<void> {
+  try {
+    const provider: LayoutMeasurementProvider = await createMeasurementProvider({
+      preference: "auto",
+      fontLoader,
+    });
+    // If the host is running in SSR or a jsdom test shell, the factory will
+    // fall back to the empirical backend.  In that case swapping is a no-op
+    // but still emits `measurement_backend_ready` with `empirical` which is
+    // informational; chrome consumers use the event to refresh metrics.
+    engine.swapMeasurementProvider(provider);
+  } catch {
+    // fall through — the empirical backend remains in place
+  }
+}

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

@@ -0,0 +1,96 @@
+/**
+ * Locale-aware default page format.
+ *
+ * Word historically defaults to US Letter for `en-US` hosts and A4 everywhere
+ * else.  This module is the single place that decides which format a
+ * newly-created document uses when no section carries an explicit `w:pgSz`.
+ *
+ * It never overrides an existing section's page size on import — importers
+ * always preserve what the source document specified.  The default is
+ * consulted in two places:
+ *
+ *   1. `serialize-main-document.ts` when the canonical model carries a
+ *      section with no `pageSize` (e.g. programmatic document construction).
+ *   2. `DocumentRuntime` when rendering a brand-new blank document.
+ */
+
+import {
+  getPageFormatById,
+  type PageFormatDefinition,
+} from "./page-format-catalog.ts";
+
+// ---------------------------------------------------------------------------
+// Locale resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Which BCP-47 language tags should fall back to Letter.
+ *
+ * Anything else defaults to A4.  This intentionally uses a small whitelist
+ * rather than a `startsWith("en")` check — `en-GB`, `en-AU`, `en-IN` all
+ * expect ISO paper sizes, not US Letter.
+ */
+const LETTER_LOCALES = new Set<string>([
+  "en-us",
+  "en-ca",
+  "fr-ca",
+  "es-mx",
+  "es-cl",
+  "fil-ph",
+]);
+
+export interface ResolveDefaultPageFormatOptions {
+  /** Explicit BCP-47 locale (e.g. "en-US", "de-DE"). */
+  locale?: string;
+}
+
+/**
+ * Return the default `PageFormatDefinition` for a given locale.
+ *
+ * When `locale` is omitted the function consults `Intl.DateTimeFormat` to
+ * infer the current locale.  When `Intl` is unavailable (unusual in modern
+ * runtimes) it falls back to A4 as the safer international default.
+ */
+export function resolveDefaultPageFormat(
+  options: ResolveDefaultPageFormatOptions = {},
+): PageFormatDefinition {
+  const raw = options.locale ?? tryResolveHostLocale();
+  if (!raw) {
+    return getPageFormatById("a4");
+  }
+  const normalized = raw.toLowerCase();
+  if (LETTER_LOCALES.has(normalized)) {
+    return getPageFormatById("letter");
+  }
+  // Match just the language-region prefix (e.g. "en-us-1234" → "en-us")
+  const region = normalized.split("-").slice(0, 2).join("-");
+  if (LETTER_LOCALES.has(region)) {
+    return getPageFormatById("letter");
+  }
+  return getPageFormatById("a4");
+}
+
+function tryResolveHostLocale(): string | undefined {
+  try {
+    if (typeof Intl === "undefined" || typeof Intl.DateTimeFormat !== "function") {
+      return undefined;
+    }
+    return new Intl.DateTimeFormat().resolvedOptions().locale;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Return the default `w:pgSz` payload (width/height in twips) for a given
+ * locale.  Convenience wrapper used by the export pipeline.
+ */
+export function resolveDefaultPageSizeTwips(
+  options: ResolveDefaultPageFormatOptions = {},
+): { widthTwips: number; heightTwips: number } {
+  const format = resolveDefaultPageFormat(options);
+  return {
+    widthTwips: format.portraitWidthTwips,
+    heightTwips: format.portraitHeightTwips,
+  };
+}

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)
 // ---------------------------------------------------------------------------
@@ -184,5 +186,50 @@ export {
   type PublicFieldDirtinessReport,
   type LayoutFacetEvent,
   type LayoutFacetInvalidationReason,
+  type RenderZoomSummary,
   type CreateLayoutFacetInput,
+  type PageFormatDefinition,
+  type ActivePageFormat,
+  type MarginPresetDefinition,
+  type ActiveMarginPreset,
 } from "./public-facet.ts";
+
+// ---------------------------------------------------------------------------
+// Page-format catalog + margin preset catalog + locale defaults (R0.5)
+// ---------------------------------------------------------------------------
+
+export {
+  PAGE_FORMAT_CATALOG,
+  matchPageFormat,
+  getPageFormatById,
+  type PageFormatId,
+  type PageFormatRegion,
+  type PageFormatLocaleDefault,
+  type PageFormatDisplay,
+  type MatchPageFormatInput,
+} from "./page-format-catalog.ts";
+
+export {
+  MARGIN_PRESET_CATALOG,
+  matchMarginPreset,
+  getMarginPresetById,
+  type MarginPresetId,
+  type MatchMarginPresetInput,
+} from "./margin-preset-catalog.ts";
+
+export {
+  resolveDefaultPageFormat,
+  resolveDefaultPageSizeTwips,
+  type ResolveDefaultPageFormatOptions,
+} from "./default-page-format.ts";
+
+// ---------------------------------------------------------------------------
+// Workflow rail segments (R3a)
+// ---------------------------------------------------------------------------
+
+export {
+  collectScopeRailSegments,
+  type CollectScopeRailSegmentsInput,
+  type ScopeRailPosture,
+  type ScopeRailSegment,
+} from "../workflow-rail-segments.ts";

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

@@ -12,6 +12,8 @@ import type {
   PublicMeasurementFidelity,
   WordReviewEditorLayoutFacet,
 } from "./public-facet.ts";
+import { MARGIN_PRESET_CATALOG } from "./margin-preset-catalog.ts";
+import { PAGE_FORMAT_CATALOG } from "./page-format-catalog.ts";
 
 export function createInertLayoutFacet(): WordReviewEditorLayoutFacet {
   const emptyReport: PublicFieldDirtinessReport = {
@@ -32,12 +34,26 @@ export function createInertLayoutFacet(): WordReviewEditorLayoutFacet {
     getActiveStoriesOnPage: () => null,
     getDisplayPageNumber: () => null,
     getLineBoxes: () => [],
+    getLineBoxesForRegion: () => [],
     getFragmentsForPage: () => [],
+    getPageFormatCatalog: () => PAGE_FORMAT_CATALOG,
+    getActivePageFormat: () => null,
+    getMarginPresetCatalog: () => MARGIN_PRESET_CATALOG,
+    getActiveMarginPreset: () => null,
+    getRenderFrame: () => null,
+    getRenderZoom: () => null,
+    hitTest: () => null,
+    getAnchorRects: () => [],
+    getScopeRailSegments: () => [],
+    getAllScopeRailSegments: () => [],
     getResolvedFormatting: () => null,
     getResolvedRunFormatting: () => null,
     getMeasurement: () => null,
     getMeasurementFidelity: () => fidelity,
     whenMeasurementReady: () => Promise.resolve(),
+    getFirstPageIndexForBlock: () => null,
+    swapMeasurementProvider: () => undefined,
+    getTableRenderPlan: () => null,
     getDirtyFieldFamilies: () => [],
     getFieldDirtinessReport: () => emptyReport,
     subscribe: (_listener: (event: LayoutFacetEvent) => void) => () => undefined,