@beyondwork/docx-react-component 1.0.45 → 1.0.47

package/README.md

@@ -708,7 +708,21 @@ Fired when a comment is resolved (via `resolveComment` or the sidebar).
 }
 ```
 
-There is no separate `comment_removed` event — deletions are silent. Query `getComments()` after a `dirty_changed` event if you need to detect deletions.
+For a general-purpose "something about comments changed" signal (covering deletions, reply appends, body edits, reopen, and every other mutation — including Yjs-driven mutations that route through the editor's imperative ref), subscribe to `comments_changed`.
+
+#### `comments_changed`
+
+Fired once per commit whenever the runtime's comment snapshot differs from the previous commit. Use this when you render comments in a sibling component and need to know when to re-fetch via `editorRef.current.getComments()`.
+
+```ts
+{
+  type: "comments_changed";
+  documentId: string;
+  changedCommentIds: string[]; // always non-empty
+}
+```
+
+Covers: `addComment`, `deleteComment`, `resolveComment`, `reopenComment`, `addCommentReply`, `editCommentBody`, and any remote-origin mutation that funnels through the same runtime APIs. Does NOT fire on selection/focus changes.
 
 #### `change_accepted`
 
@@ -944,6 +958,9 @@ function CommentButton({ editorRef }: { editorRef: React.RefObject<WordReviewEdi
       case "comment_resolved":
         console.log("comment resolved:", event.commentId);
         break;
+      case "comments_changed":
+        console.log("comments changed:", event.changedCommentIds);
+        break;
       case "change_accepted":
         console.log("change accepted:", event.changeId);
         break;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.45",
+  "version": "1.0.47",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "packageManager": "pnpm@10.30.3",
   "type": "module",

package/src/api/public-types.ts

@@ -2416,6 +2416,23 @@ export type WordReviewEditorEvent =
       documentId: string;
       commentId: string;
     }
+  | {
+      type: "comments_changed";
+      documentId: string;
+      /**
+       * Stable ids of the comment threads whose state differs between
+       * the previous and current runtime render snapshot. Includes
+       * additions, deletions, body edits, reply appends, and
+       * resolution-state transitions. Consumers can call
+       * `editorRef.current.getComments()` to obtain the full updated
+       * `CommentSidebarSnapshot`.
+       *
+       * The array is always non-empty when this event fires. When the
+       * snapshot's `comments` reference is unchanged between commits,
+       * no event fires.
+       */
+      changedCommentIds: string[];
+    }
   | {
       type: "change_accepted";
       documentId: string;

package/src/core/commands/index.ts

@@ -34,7 +34,10 @@ import {
   outdentParagraphAtSelection,
   splitParagraph,
 } from "./text-commands.ts";
-import type { RevisionRecord as CanonicalRevisionRecord } from "../../model/canonical-document.ts";
+import type {
+  BlockNode,
+  RevisionRecord as CanonicalRevisionRecord,
+} from "../../model/canonical-document.ts";
 import { remapCommentThreads } from "../../review/store/comment-remapping.ts";
 import { collectScopeTagTouches } from "../../review/store/scope-tag-diff.ts";
 import { applyRevisionRuntimeCommand } from "../../runtime/revision-runtime.ts";
@@ -86,6 +89,15 @@ import {
 import { insertPageBreak, insertTable } from "./text-commands.ts";
 import type { TableSelectionDescriptor } from "../../runtime/table-commands.ts";
 
+export type ContentChildrenPatch =
+  | { kind: "keep-all" }
+  | { kind: "replace-all"; children: BlockNode[] }
+  | {
+      kind: "index-map";
+      baseLength: number;
+      entries: ReadonlyArray<{ index: number; block: BlockNode }>;
+    };
+
 export interface CommandOrigin {
   source:
     | "keyboard"
@@ -112,6 +124,15 @@ export type EditorCommand =
       protectionSelection?: SelectionSnapshot;
       origin?: CommandOrigin;
     }
+  | {
+      type: "document.patch";
+      patch: Partial<CanonicalDocumentEnvelope>;
+      contentChildren?: ContentChildrenPatch;
+      mapping?: TransactionMapping;
+      selection?: SelectionSnapshot;
+      protectionSelection?: SelectionSnapshot;
+      origin?: CommandOrigin;
+    }
   | {
       type: "text.insert";
       text: string;
@@ -482,6 +503,53 @@ export function executeEditorCommand(
         },
       );
     }
+    case "document.patch": {
+      const mapping = command.mapping ?? createEmptyMapping();
+      const nextDocument = applyDocumentPatch(
+        state.document,
+        command.patch,
+        command.contentChildren,
+      );
+      const selection =
+        command.selection ?? remapSelection(state.selection, mapping);
+      const reviewState = remapReviewStateAfterContentChange(
+        state,
+        nextDocument,
+        mapping,
+      );
+
+      return createTransaction(
+        {
+          ...state,
+          document: reviewState.document,
+          selection,
+          warnings: reviewState.warnings,
+          runtime: {
+            ...state.runtime,
+            activeCommentId: reviewState.activeCommentId,
+          },
+          compatibility: {
+            ...state.compatibility,
+            generatedAt: context.timestamp,
+            warnings: reviewState.warnings,
+            featureEntries: state.compatibility.featureEntries.map((entry) =>
+              entry.affectedAnchor
+                ? {
+                    ...entry,
+                    affectedAnchor: mapAnchor(entry.affectedAnchor, mapping),
+                  }
+                : entry,
+            ),
+          },
+        },
+        {
+          historyBoundary: "push",
+          markDirty: true,
+          mapping,
+          effects: reviewState.effects,
+        },
+      );
+    }
     case "text.insert": {
       const suggestingResult = context.documentMode === "suggesting"
         ? applySuggestingInsert(state, command.text, context)
@@ -1141,6 +1209,57 @@ export function executeEditorCommand(
   }
 }
 
+export function applyDocumentPatch(
+  base: CanonicalDocumentEnvelope,
+  patch: Partial<CanonicalDocumentEnvelope>,
+  contentChildren?: ContentChildrenPatch,
+): CanonicalDocumentEnvelope {
+  const nextContent = resolvePatchedContent(base, patch, contentChildren);
+  const merged: CanonicalDocumentEnvelope = { ...base, ...patch };
+  if (nextContent) {
+    merged.content = nextContent;
+  }
+  return merged;
+}
+
+function resolvePatchedContent(
+  base: CanonicalDocumentEnvelope,
+  patch: Partial<CanonicalDocumentEnvelope>,
+  contentChildren: ContentChildrenPatch | undefined,
+): CanonicalDocumentEnvelope["content"] | null {
+  if (!contentChildren) {
+    return patch.content ?? null;
+  }
+  if (contentChildren.kind === "keep-all") {
+    return { ...base.content, children: base.content.children };
+  }
+  if (contentChildren.kind === "replace-all") {
+    return {
+      ...(patch.content ?? base.content),
+      children: contentChildren.children,
+    };
+  }
+  const baseChildren = base.content.children;
+  if (contentChildren.baseLength !== baseChildren.length) {
+    throw new Error(
+      `applyDocumentPatch: index-map baseLength ${contentChildren.baseLength} does not match current children length ${baseChildren.length}`,
+    );
+  }
+  const nextChildren: BlockNode[] = baseChildren.slice();
+  for (const entry of contentChildren.entries) {
+    if (entry.index < 0 || entry.index >= nextChildren.length) {
+      throw new Error(
+        `applyDocumentPatch: index-map entry index ${entry.index} out of range [0, ${nextChildren.length})`,
+      );
+    }
+    nextChildren[entry.index] = entry.block;
+  }
+  return {
+    ...(patch.content ?? base.content),
+    children: nextChildren,
+  };
+}
+
 function buildDocumentReplaceTransaction(
   state: EditorState,
   context: CommandExecutionContext,

package/src/io/docx-session.ts

@@ -59,14 +59,12 @@ import {
   getDocumentBackedWorkflowMetadata,
   parseWorkflowPayloadEnvelopeFromPackage,
   resolvePayloadPartPath,
+  resolveWorkflowPayloadPartPaths,
   WORKFLOW_PAYLOAD_CONTENT_TYPE,
   WORKFLOW_PAYLOAD_CUSTOM_PROPS_CONTENT_TYPE,
   WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH,
   WORKFLOW_PAYLOAD_CUSTOM_PROPS_RELATIONSHIP_TYPE,
   WORKFLOW_PAYLOAD_ITEM_PROPS_CONTENT_TYPE,
-  WORKFLOW_PAYLOAD_ITEM_PROPS_PART_PATH,
-  WORKFLOW_PAYLOAD_PART_PATH,
-  WORKFLOW_PAYLOAD_RELATIONSHIP_TYPE,
 } from "./ooxml/workflow-payload.ts";
 import {
   classifyCorruptPackageError,
@@ -1736,12 +1734,17 @@ function exportDocxEditorSession(
     }
   }
 
+  const workflowPayloadPartPaths = resolveWorkflowPayloadPartPaths(
+    state.sourcePackage,
+    sessionState.documentId,
+  );
+
   const exportSession = createExportSession(state.sourcePackage, [
     state.sourceDocumentPartPath,
     APP_PROPERTIES_PART_PATH,
     CORE_PROPERTIES_PART_PATH,
-    WORKFLOW_PAYLOAD_PART_PATH,
-    WORKFLOW_PAYLOAD_ITEM_PROPS_PART_PATH,
+    workflowPayloadPartPaths.payloadPartPath,
+    workflowPayloadPartPaths.itemPropsPartPath,
     WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH,
     numberingPartPath,
     commentsPartPath,
@@ -1974,7 +1977,14 @@ function exportDocxEditorSession(
   ensureHostMetadataParts(exportSession, state.sourcePackage, currentDocument);
   // Schema 1.2: pass through editorState payload collected by the runtime channel.
   const internalEditorState = (options as { _editorState?: import("./ooxml/workflow-payload.ts").EditorStatePayload } | undefined)?._editorState;
-  ensureWorkflowPayloadParts(exportSession, sessionState, currentDocument, state.sourcePackage, internalEditorState);
+  ensureWorkflowPayloadParts(
+    exportSession,
+    sessionState,
+    currentDocument,
+    state.sourcePackage,
+    internalEditorState,
+    workflowPayloadPartPaths,
+  );
 
   return {
     bytes: exportSession.serialize(),
@@ -3701,6 +3711,7 @@ function ensureWorkflowPayloadParts(
   document: CanonicalDocumentEnvelope,
   sourcePackage: OpcPackage,
   editorState?: import("./ooxml/workflow-payload.ts").EditorStatePayload,
+  precomputedPartPaths?: { payloadPartPath: string; itemPropsPartPath: string },
 ): void {
   const payloadParts = buildWorkflowPayloadParts({
     sourcePackage,
@@ -3716,19 +3727,37 @@ function ensureWorkflowPayloadParts(
     return;
   }
 
+  // Export ownership is resolved before session creation, so any precomputed
+  // paths must stay in lockstep with buildWorkflowPayloadParts for the same
+  // source package and documentId.
+  if (precomputedPartPaths) {
+    if (
+      precomputedPartPaths.payloadPartPath !== payloadParts.payloadPartPath ||
+      precomputedPartPaths.itemPropsPartPath !== payloadParts.itemPropsPartPath
+    ) {
+      throw new Error(
+        `ensureWorkflowPayloadParts: precomputed payload part paths `
+          + `(${precomputedPartPaths.payloadPartPath} / ${precomputedPartPaths.itemPropsPartPath}) `
+          + `do not match buildWorkflowPayloadParts output `
+          + `(${payloadParts.payloadPartPath} / ${payloadParts.itemPropsPartPath}). `
+          + `This is a bug in the export orchestration.`,
+      );
+    }
+  }
+
   const payloadPart = sourcePackage.parts.get(payloadParts.payloadPartPath);
   const itemPropsPart = sourcePackage.parts.get(payloadParts.itemPropsPartPath);
   const customPropsPart = sourcePackage.parts.get(WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH);
 
   exportSession.replaceOwnedPart({
-    path: payloadParts.payloadPartPath,
+    path: precomputedPartPaths?.payloadPartPath ?? payloadParts.payloadPartPath,
     bytes: new TextEncoder().encode(payloadParts.payloadPartXml),
     contentType: payloadPart?.contentType ?? WORKFLOW_PAYLOAD_CONTENT_TYPE,
     relationships: payloadParts.payloadRelationships,
     compression: payloadPart?.compression,
   });
   exportSession.replaceOwnedPart({
-    path: payloadParts.itemPropsPartPath,
+    path: precomputedPartPaths?.itemPropsPartPath ?? payloadParts.itemPropsPartPath,
     bytes: new TextEncoder().encode(payloadParts.itemPropsXml),
     contentType: itemPropsPart?.contentType ?? WORKFLOW_PAYLOAD_ITEM_PROPS_CONTENT_TYPE,
     compression: itemPropsPart?.compression,

package/src/io/ooxml/workflow-payload.ts

@@ -1158,6 +1158,33 @@ function resolveDescriptor(sourcePackage: OpcPackage, documentId: string): Embed
   };
 }
 
+/**
+ * Resolve the OPC part paths the workflow-payload serializer will write
+ * to on export, based on the source package's existing customXml slots.
+ *
+ * - If the source already contains a BW workflow payload, the existing
+ *   `/customXml/itemN.xml` path is reused (via `resolvePayloadPartPath`).
+ * - Otherwise, `findNextAvailableItemNumber(sourcePackage)` picks the
+ *   next free slot (e.g. `item5.xml` when `item1..4.xml` already exist
+ *   in the source).
+ *
+ * The returned paths MUST be passed to `createExportSession` as owned
+ * paths so `replaceOwnedPart(...)` does not throw when
+ * `ensureWorkflowPayloadParts` later writes to them. The custom-props
+ * part lives at the fixed path `WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH`
+ * and is not part of this resolver.
+ */
+export function resolveWorkflowPayloadPartPaths(
+  sourcePackage: OpcPackage,
+  documentId: string,
+): { payloadPartPath: string; itemPropsPartPath: string } {
+  const descriptor = resolveDescriptor(sourcePackage, documentId);
+  return {
+    payloadPartPath: descriptor.payloadPartPath,
+    itemPropsPartPath: descriptor.itemPropsPartPath,
+  };
+}
+
 export function resolvePayloadPartPath(sourcePackage: OpcPackage): string | null {
   const mirroredItemId = readCustomPropertyValue(
     sourcePackage,

package/src/runtime/collab/event-types.ts

@@ -18,11 +18,15 @@ import type { EditorStoryTarget } from "../../api/public-types.ts";
  * Events are meant to be small deltas (text insertions, comment adds,
  * change accepts, etc.). They are NOT full-document snapshots.
  *
- * `document.replace` is a special case: some formatting/table/list
- * operations currently produce `document.replace` commands that carry
- * a full `CanonicalDocumentEnvelope`. These events are bandwidth-heavy
- * but functionally correct. A follow-up will promote them to first-class
- * delta commands.
+ * `document.replace` carries a full `CanonicalDocumentEnvelope` and is
+ * therefore bandwidth-heavy. The collab sync bridge transparently
+ * converts broadcast `document.replace` commands to `document.patch`
+ * deltas by diffing against the pre-commit document snapshot, so the
+ * shared event log only ever contains the changed top-level keys (and,
+ * for `content.children`, only the changed block indices). Remote
+ * replicas apply `document.patch` by merging the delta onto their
+ * current canonical state — see `applyDocumentPatch` in
+ * `core/commands/index.ts`.
  */
 export interface CommandEvent {
   /** UUID — dedup key for defensive idempotency. */
@@ -74,6 +78,7 @@ export const BROADCAST_COMMAND_TYPES: ReadonlySet<EditorCommand["type"]> = new S
   "text.insert-hard-break",
   "paragraph.split",
   "document.replace",
+  "document.patch",
   "comment.add",
   "comment.resolve",
   "comment.reopen",

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

@@ -2,9 +2,12 @@ import * as Y from "yjs";
 
 import type {
   CommandExecutionContext,
+  ContentChildrenPatch,
   EditorCommand,
   EditorTransaction,
 } from "../../core/commands/index.ts";
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import type { BlockNode } from "../../model/canonical-document.ts";
 import type {
   CommandAppliedMeta,
   DocumentRuntime,
@@ -17,6 +20,122 @@ import {
   type CommandEvent,
 } from "./event-types.ts";
 
+const PATCHABLE_TOP_LEVEL_KEYS = [
+  "updatedAt",
+  "metadata",
+  "styles",
+  "numbering",
+  "media",
+  "content",
+  "review",
+  "preservation",
+  "diagnostics",
+  "subParts",
+  "fieldRegistry",
+] as const satisfies ReadonlyArray<keyof CanonicalDocumentEnvelope>;
+
+export function compressDocumentReplaceForBroadcast(
+  command: EditorCommand,
+  priorDocument: CanonicalDocumentEnvelope,
+): EditorCommand {
+  if (command.type !== "document.replace") {
+    return command;
+  }
+  const next = command.document;
+  if (next === priorDocument) {
+    return command;
+  }
+
+  const patch: Partial<CanonicalDocumentEnvelope> = {};
+  let anyTopLevelChange = false;
+  for (const key of PATCHABLE_TOP_LEVEL_KEYS) {
+    if (key === "content") continue;
+    if (next[key] !== priorDocument[key]) {
+      (patch as Record<string, unknown>)[key] = next[key];
+      anyTopLevelChange = true;
+    }
+  }
+
+  const contentChildrenPatch = diffContentChildren(
+    priorDocument.content.children,
+    next.content.children,
+  );
+  const contentMetaChanged =
+    next.content !== priorDocument.content &&
+    !contentReferenceEqualExceptChildren(priorDocument.content, next.content);
+  if (contentMetaChanged) {
+    const { children: _children, ...rest } = next.content;
+    patch.content = { ...rest, children: [] } as CanonicalDocumentEnvelope["content"];
+  }
+
+  const contentChanged =
+    contentChildrenPatch.kind !== "keep-all" || contentMetaChanged;
+  if (!contentChanged && !anyTopLevelChange) {
+    return {
+      type: "document.patch",
+      patch: {},
+      contentChildren: { kind: "keep-all" },
+      mapping: command.mapping,
+      selection: command.selection,
+      protectionSelection: command.protectionSelection,
+      origin: command.origin,
+    };
+  }
+
+  return {
+    type: "document.patch",
+    patch,
+    contentChildren: contentChildrenPatch,
+    mapping: command.mapping,
+    selection: command.selection,
+    protectionSelection: command.protectionSelection,
+    origin: command.origin,
+  };
+}
+
+function contentReferenceEqualExceptChildren(
+  a: CanonicalDocumentEnvelope["content"],
+  b: CanonicalDocumentEnvelope["content"],
+): boolean {
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    if (key === "children") continue;
+    if ((a as unknown as Record<string, unknown>)[key] !== (b as unknown as Record<string, unknown>)[key]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function diffContentChildren(
+  prior: readonly BlockNode[],
+  next: readonly BlockNode[],
+): ContentChildrenPatch {
+  if (prior === next) {
+    return { kind: "keep-all" };
+  }
+  if (prior.length === next.length) {
+    const entries: Array<{ index: number; block: BlockNode }> = [];
+    for (let i = 0; i < next.length; i += 1) {
+      const priorBlock = prior[i];
+      const nextBlock = next[i];
+      if (priorBlock === undefined || nextBlock === undefined) {
+        return { kind: "replace-all", children: next.slice() };
+      }
+      if (priorBlock !== nextBlock) {
+        entries.push({ index: i, block: nextBlock });
+      }
+    }
+    if (entries.length === 0) {
+      return { kind: "keep-all" };
+    }
+    return { kind: "index-map", baseLength: prior.length, entries };
+  }
+  return { kind: "replace-all", children: next.slice() };
+}
+
 export type RuntimeCommandAppliedListener = (
   command: EditorCommand,
   transaction: EditorTransaction,
@@ -73,8 +192,13 @@ export function createRuntimeCollabSync(
       return;
     }
 
-    const event = createCommandEvent({
+    const broadcastCommand = compressDocumentReplaceForBroadcast(
       command,
+      meta.priorDocument,
+    );
+
+    const event = createCommandEvent({
+      command: broadcastCommand,
       originClientId: ydoc.clientID,
       authorId,
       timestamp: context.timestamp,

package/src/runtime/document-runtime.ts

@@ -406,6 +406,7 @@ export interface DocumentRuntime {
 export interface CommandAppliedMeta {
   preSelection: import("../core/state/editor-state.ts").SelectionSnapshot;
   activeStory: EditorStoryTarget;
+  priorDocument: CanonicalDocumentEnvelope;
 }
 
 export interface CreateDocumentRuntimeOptions {
@@ -2111,6 +2112,7 @@ export function createDocumentRuntime(
         options.onCommandApplied?.(command, noopTransaction, context, {
           preSelection: state.selection,
           activeStory,
+          priorDocument: state.document,
         });
         return;
       }
@@ -2124,11 +2126,13 @@ export function createDocumentRuntime(
         } as const;
         const preSelection = commandSelection;
         const preActiveStory = activeStory;
+        const priorDocument = state.document;
         const transaction = executeEditorCommand(state, command, context);
         commit(transaction);
         options.onCommandApplied?.(command, transaction, context, {
           preSelection,
           activeStory: preActiveStory,
+          priorDocument,
         });
       } catch (error) {
         emitError(toRuntimeError(error));
@@ -3071,6 +3075,20 @@ export function createDocumentRuntime(
       });
     }
 
+    if (previous.document.review.comments !== next.document.review.comments) {
+      const changedCommentIds = diffCommentMapKeys(
+        previous.document.review.comments,
+        next.document.review.comments,
+      );
+      if (changedCommentIds.length > 0) {
+        emit({
+          type: "comments_changed",
+          documentId: next.documentId,
+          changedCommentIds,
+        });
+      }
+    }
+
     if (transaction.effects.changeAccepted) {
       emit({
         type: "change_accepted",
@@ -3269,12 +3287,14 @@ export function createDocumentRuntime(
 
     const preSelection = selection;
     const preActiveStory = activeStory;
+    const priorDocument = state.document;
     if (activeStory.kind === "main") {
       const mainTransaction = executeEditorCommand(baseState, command, context);
       commit(mainTransaction);
       options.onCommandApplied?.(command, mainTransaction, context, {
         preSelection,
         activeStory: preActiveStory,
+        priorDocument,
       });
       return classifyAck({
         command,
@@ -3356,6 +3376,7 @@ export function createDocumentRuntime(
     options.onCommandApplied?.(broadcastCommand, mergedTransaction, context, {
       preSelection,
       activeStory: preActiveStory,
+      priorDocument,
     });
     return classifyAck({
       command,
@@ -3988,6 +4009,27 @@ function createSelectionFromPublicAnchor(
   }
 }
 
+/**
+ * Collect the stable ids of comment threads whose entry differs
+ * (present in one side but not the other, OR present in both but
+ * referencing a different object — which indicates any mutation to
+ * the thread, since the runtime treats `review.comments` as
+ * immutable per commit). Used by the `comments_changed` event.
+ */
+function diffCommentMapKeys(
+  previous: CanonicalDocumentEnvelope["review"]["comments"],
+  next: CanonicalDocumentEnvelope["review"]["comments"],
+): string[] {
+  const changed = new Set<string>();
+  for (const id of Object.keys(previous)) {
+    if (previous[id] !== next[id]) changed.add(id);
+  }
+  for (const id of Object.keys(next)) {
+    if (previous[id] !== next[id]) changed.add(id);
+  }
+  return Array.from(changed);
+}
+
 function toPublicCompatibilityReport(
   report: InternalCompatibilityReport,
 ): CompatibilityReport {

package/src/runtime/event-refresh-hints.ts

@@ -43,6 +43,7 @@ export function describeEventImpact(
     case "suggestion_updated":
     case "comment_added":
     case "comment_resolved":
+    case "comments_changed":
       return {
         invalidate: [
           "render",

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 unknown as { document?: { fonts?: unknown } }).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 as MinimalFontFaceSet | undefined;
     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/layout-engine-version.ts

@@ -24,8 +24,26 @@
  *       internal cachedGraph + cachedKey without triggering fullRebuild.
  *       Does not change geometry — but the public interface changed, so
  *       persisted envelopes MUST re-derive their cacheKey under 3.
+ *   4 — PR #188 `fix(export)` bumped the version to satisfy the
+ *       `src/runtime/layout/**` gate, even though the font-loader
+ *       type-def restoration intended for that PR did not survive the
+ *       squash-merge. Runtime and cached geometry unchanged.
+ *   5 — PR #187 `joakim/commentevents` restores the local `Minimal*`
+ *       font-loader type defs under `src/runtime/layout/docx-font-loader.ts`
+ *       (re-application of previously-shipped PRs #162/#163 which a
+ *       subsequent merge reverted) so downstream consumers whose
+ *       TS `lib` does not expose `FontFaceSet.add` can type-check the
+ *       package, and adds the `comments_changed` event plumbing in
+ *       runtime domains outside `src/runtime/layout/**`. TypeScript-
+ *       surface-only from the layout engine's perspective: no cached
+ *       geometry or cache-key derivation changes. The bump exists
+ *       solely to satisfy the
+ *       `scripts/ci-check-layout-engine-version.mjs` gate because a
+ *       file under `src/runtime/layout/**` changed. Safe to treat
+ *       versions 3, 4, and 5 as cache-compatible if a migration ever
+ *       needs to collapse them.
  */
-export const LAYOUT_ENGINE_VERSION = 3 as const;
+export const LAYOUT_ENGINE_VERSION = 5 as const;
 
 /**
  * Serialization schema version for the LayCache payload (the cache envelope

package/src/runtime/text-ack-range.ts

@@ -3,9 +3,9 @@
  * as `adjustedRange`. The semantics: the union of all step post-edit ranges
  * (where each step covers `[step.from, step.from + step.insertSize]` in the
  * new document). When the transaction has no steps (e.g., a non-main-story
- * `document.replace` that uses `createEmptyMapping()`), fall back to the
- * normalized prior selection range so consumers still receive a meaningful
- * pointer.
+ * `document.replace` or `document.patch` that uses `createEmptyMapping()`),
+ * fall back to the normalized prior selection range so consumers still
+ * receive a meaningful pointer.
  *
  * Note: only `step.from` and `step.insertSize` are considered; `step.to`
  * (the pre-edit end of the replaced range) is intentionally ignored. A pure