@beyondwork/docx-react-component 1.0.38 → 1.0.40

package/src/runtime/collab/runtime-collab-sync.ts

@@ -0,0 +1,273 @@
+import * as Y from "yjs";
+
+import type {
+  CommandExecutionContext,
+  EditorCommand,
+  EditorTransaction,
+} from "../../core/commands/index.ts";
+import type {
+  CommandAppliedMeta,
+  DocumentRuntime,
+  Unsubscribe,
+} from "../document-runtime.ts";
+import {
+  createCommandEvent,
+  isBroadcastCommand,
+  isLocalOnlyCommand,
+  type CommandEvent,
+} from "./event-types.ts";
+
+export type RuntimeCommandAppliedListener = (
+  command: EditorCommand,
+  transaction: EditorTransaction,
+  context: CommandExecutionContext,
+  meta: CommandAppliedMeta,
+) => void;
+
+export interface RuntimeCommandAppliedBridge {
+  onCommandApplied: RuntimeCommandAppliedListener;
+  subscribe(listener: RuntimeCommandAppliedListener): Unsubscribe;
+}
+
+export interface RuntimeCollabSyncOptions {
+  ydoc: Y.Doc;
+  runtime: DocumentRuntime;
+  authorId: string;
+  commandAppliedBridge: RuntimeCommandAppliedBridge;
+}
+
+export interface RuntimeCollabSyncHandle {
+  destroy(): void;
+}
+
+export function createRuntimeCommandAppliedBridge(): RuntimeCommandAppliedBridge {
+  const listeners = new Set<RuntimeCommandAppliedListener>();
+
+  return {
+    onCommandApplied(command, transaction, context, meta) {
+      for (const listener of [...listeners]) {
+        listener(command, transaction, context, meta);
+      }
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}
+
+export function createRuntimeCollabSync(
+  options: RuntimeCollabSyncOptions,
+): RuntimeCollabSyncHandle {
+  const { ydoc, runtime, authorId, commandAppliedBridge } = options;
+  const yEvents = ydoc.getArray<CommandEvent>("commandEvents");
+  const appliedEventIds = new Set<string>();
+
+  const unsubscribeCommandApplied = commandAppliedBridge.subscribe((command, _transaction, context, meta) => {
+    if (isLocalOnlyCommand(command)) {
+      return;
+    }
+    if (!isBroadcastCommand(command)) {
+      return;
+    }
+
+    const event = createCommandEvent({
+      command,
+      originClientId: ydoc.clientID,
+      authorId,
+      timestamp: context.timestamp,
+      context: {
+        documentMode: context.documentMode,
+        defaultAuthorId: context.defaultAuthorId,
+        preSelection: meta.preSelection,
+        activeStory: meta.activeStory,
+      },
+    });
+
+    appliedEventIds.add(event.eventId);
+    yEvents.push([event]);
+  });
+
+  yEvents.observe(onYEventsChange);
+
+  for (const value of yEvents.toArray()) {
+    applyStartupEvent(value);
+  }
+
+  return {
+    destroy() {
+      unsubscribeCommandApplied();
+      yEvents.unobserve(onYEventsChange);
+    },
+  };
+
+  function onYEventsChange(event: Y.YArrayEvent<CommandEvent>): void {
+    for (const delta of event.changes.delta) {
+      if (!Array.isArray(delta.insert)) {
+        continue;
+      }
+
+      for (const value of delta.insert) {
+        applyObservedEvent(value);
+      }
+    }
+  }
+
+  function applyStartupEvent(value: unknown): void {
+    const event = asCommandEvent(value);
+    if (!event) {
+      return;
+    }
+    if (appliedEventIds.has(event.eventId)) {
+      return;
+    }
+    if (!isReplayableEvent(event)) {
+      appliedEventIds.add(event.eventId);
+      return;
+    }
+
+    appliedEventIds.add(event.eventId);
+    applyEventToRuntime(event);
+  }
+
+  function applyObservedEvent(value: unknown): void {
+    const event = asCommandEvent(value);
+    if (!event) {
+      return;
+    }
+    if (appliedEventIds.has(event.eventId)) {
+      return;
+    }
+    if (!isReplayableEvent(event)) {
+      appliedEventIds.add(event.eventId);
+      return;
+    }
+
+    appliedEventIds.add(event.eventId);
+    if (event.originClientId === ydoc.clientID) {
+      return;
+    }
+    applyEventToRuntime(event);
+  }
+
+  function isReplayableEvent(event: CommandEvent): boolean {
+    if (isLocalOnlyCommand(event.command)) {
+      return false;
+    }
+    if (!isBroadcastCommand(event.command)) {
+      return false;
+    }
+    return true;
+  }
+
+  function applyEventToRuntime(event: CommandEvent): void {
+    runtime.applyRemoteCommand(
+      event.command,
+      {
+        timestamp: event.timestamp,
+        documentMode: event.context.documentMode,
+        defaultAuthorId: event.context.defaultAuthorId ?? event.authorId,
+      },
+      {
+        preSelection: event.context.preSelection,
+        activeStory: event.context.activeStory,
+      },
+    );
+  }
+}
+
+function asCommandEvent(value: unknown): CommandEvent | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  if (typeof value.eventId !== "string") {
+    return null;
+  }
+  if (typeof value.originClientId !== "number" || !Number.isFinite(value.originClientId)) {
+    return null;
+  }
+  if (typeof value.authorId !== "string") {
+    return null;
+  }
+  const timestamp = normalizeTimestamp(value.timestamp);
+  if (timestamp === null) {
+    return null;
+  }
+
+  const command = asEditorCommand(value.command);
+  const context = asCommandEventContext(value.context);
+  if (!command || !context) {
+    return null;
+  }
+
+  return {
+    eventId: value.eventId,
+    originClientId: value.originClientId,
+    authorId: value.authorId,
+    timestamp,
+    command,
+    context,
+  };
+}
+
+function normalizeTimestamp(value: unknown): string | null {
+  if (typeof value === "string" && value.length > 0) {
+    return value;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return new Date(value).toISOString();
+  }
+  return null;
+}
+
+function asEditorCommand(value: unknown): EditorCommand | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  if (typeof value.type !== "string") {
+    return null;
+  }
+  return value as EditorCommand;
+}
+
+function asCommandEventContext(value: unknown): CommandEvent["context"] | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+
+  return {
+    documentMode: isCommandDocumentMode(value.documentMode) ? value.documentMode : undefined,
+    defaultAuthorId: typeof value.defaultAuthorId === "string" ? value.defaultAuthorId : undefined,
+    preSelection: asSelectionSnapshot(value.preSelection),
+    activeStory: asStoryTarget(value.activeStory),
+  };
+}
+
+function asSelectionSnapshot(value: unknown): CommandEvent["context"]["preSelection"] {
+  if (!isRecord(value)) return undefined;
+  if (typeof value.anchor !== "number" || typeof value.head !== "number") return undefined;
+  if (typeof value.isCollapsed !== "boolean") return undefined;
+  if (!isRecord(value.activeRange)) return undefined;
+  return value as unknown as CommandEvent["context"]["preSelection"];
+}
+
+function asStoryTarget(value: unknown): CommandEvent["context"]["activeStory"] {
+  if (!isRecord(value)) return undefined;
+  if (typeof value.kind !== "string") return undefined;
+  return value as unknown as CommandEvent["context"]["activeStory"];
+}
+
+function isCommandDocumentMode(
+  value: unknown,
+): value is NonNullable<CommandEvent["context"]["documentMode"]> {
+  return value === "editing"
+    || value === "suggesting"
+    || value === "viewing"
+    || value === "commenting";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

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;
 }
@@ -451,6 +496,13 @@ export function createDocumentRuntime(
         activeStory,
       };
     },
+    // R2 / scope-card-overlay P1 — surface metadata markup so
+    // `facet.getAllScopeCardModels()` can attach `IssueMetadataValue`
+    // to its scope without the chrome overlay having to re-fetch a
+    // separate snapshot.  Reads through the same cached snapshot the
+    // runtime already builds for comment/revision/search consumers.
+    getWorkflowMarkupMetadata: () =>
+      getCachedWorkflowMarkupSnapshot().metadata,
   });
   renderKernelRef = createRenderKernel({
     facet: layoutFacet,
@@ -1611,12 +1663,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 +1970,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 +2440,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 +2664,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 +2680,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 +2699,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 +2710,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 +2723,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 +2790,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 +2809,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 +3101,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/docx-font-loader.ts

@@ -45,12 +45,35 @@ export interface DocxFontLoader {
   refresh(input: FontLoaderInput): void;
 }
 
+interface MinimalFontFace {
+  load(): Promise<MinimalFontFace>;
+}
+
+interface MinimalFontFaceDescriptors {
+  weight?: string;
+  style?: string;
+}
+
+interface MinimalFontFaceConstructor {
+  new (
+    family: string,
+    source: ArrayBuffer | ArrayBufferView | string,
+    descriptors?: MinimalFontFaceDescriptors,
+  ): MinimalFontFace;
+}
+
+interface MinimalFontFaceSet {
+  add(face: MinimalFontFace): void;
+  check(font: string): boolean;
+  ready: Promise<MinimalFontFaceSet>;
+}
+
 export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
+  const globalDocument = (globalThis as { document?: { fonts?: MinimalFontFaceSet } }).document;
   const supported =
-    typeof document !== "undefined" &&
+    globalDocument !== undefined &&
     typeof (globalThis as { FontFace?: unknown }).FontFace !== "undefined" &&
-    // Guard against jsdom which exposes FontFace but not document.fonts
-    Boolean((document as Document & { fonts?: FontFaceSet }).fonts);
+    Boolean(globalDocument.fonts);
 
   let current: FontLoaderInput = initial;
   let readyPromise: Promise<void>;
@@ -58,7 +81,7 @@ export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
 
   function run(input: FontLoaderInput): Promise<void> {
     if (!supported) return Promise.resolve();
-    const fontSet = (document as Document & { fonts?: FontFaceSet }).fonts;
+    const fontSet = globalDocument?.fonts;
     if (!fontSet) return Promise.resolve();
 
     const pending: Array<Promise<unknown>> = [];
@@ -70,10 +93,8 @@ export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
 
         for (const [descriptor, data] of variantsOf(variants)) {
           try {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const FontFaceCtor = (globalThis as any).FontFace as {
-              new (family: string, source: BufferSource, descriptors?: FontFaceDescriptors): FontFace;
-            };
+            const FontFaceCtor = (globalThis as { FontFace?: MinimalFontFaceConstructor }).FontFace;
+            if (!FontFaceCtor) continue;
             const face = new FontFaceCtor(family, data, descriptor);
             pending.push(
               face.load().then((loaded) => {
@@ -88,8 +109,6 @@ export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
       }
     }
 
-    // Mark declared families as registered if the browser already resolves
-    // them (e.g. system fonts like Calibri, Arial).
     for (const family of input.families) {
       try {
         const probe = `12px "${family.replace(/"/g, "'")}", serif`;
@@ -127,7 +146,7 @@ export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
 
 function* variantsOf(
   variants: EmbeddedFontBytes,
-): IterableIterator<[FontFaceDescriptors, ArrayBuffer]> {
+): IterableIterator<[MinimalFontFaceDescriptors, ArrayBuffer]> {
   if (variants.regular) {
     yield [{ weight: "400", style: "normal" }, variants.regular];
   }

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

@@ -46,11 +46,14 @@ export function createInertLayoutFacet(): WordReviewEditorLayoutFacet {
     getAnchorRects: () => [],
     getScopeRailSegments: () => [],
     getAllScopeRailSegments: () => [],
+    getAllScopeCardModels: () => [],
     getResolvedFormatting: () => null,
     getResolvedRunFormatting: () => null,
     getMeasurement: () => null,
     getMeasurementFidelity: () => fidelity,
     whenMeasurementReady: () => Promise.resolve(),
+    getFirstPageIndexForBlock: () => null,
+    swapMeasurementProvider: () => undefined,
     getTableRenderPlan: () => null,
     getDirtyFieldFamilies: () => [],
     getFieldDirtinessReport: () => emptyReport,