@beyondwork/docx-react-component 1.0.81 → 1.0.83

package/package.json

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

package/src/api/public-types.ts

@@ -5614,7 +5614,8 @@ export interface WordReviewEditorProps {
    * Optional host-callback extension bag for workspace command chrome.
    * The default `<WordReviewEditor />` path now mounts
    * `TwWorkspaceChromeHost` with product-backed commands for formatting,
-   * paragraph/list actions, comments, and table insertion/structure.
+   * paragraph/list/style/font/color actions, search/navigation host
+   * delegation, comments, and table insertion/structure.
    * Supplying this bag overrides or extends those defaults for host-owned
    * actions such as custom table properties, hyperlink handling, or
    * object metadata. Actions without a wired callback are hidden from

package/src/api/v3/_runtime-handle.ts

@@ -43,6 +43,7 @@ export type RuntimeApiHandle = Pick<
   DocumentRuntime,
   // Session + export (runtime.document family)
   | "getSessionState"
+  | "setDocumentMode"
   | "exportDocx"
   | "getCompatibilityReport"
   | "getWarnings"
@@ -54,6 +55,7 @@ export type RuntimeApiHandle = Pick<
   | "findAllText"
   // Review (runtime.review family)
   | "getReviewWorkSnapshot"
+  | "getSuggestionsSnapshot"
   | "acceptChange"
   | "rejectChange"
   | "resolveComment"
@@ -136,6 +138,7 @@ export type RuntimeApiHandle = Pick<
  */
 export const RUNTIME_API_HANDLE_SHAPE_CHECK: Record<keyof RuntimeApiHandle, true> = {
   getSessionState: true,
+  setDocumentMode: true,
   exportDocx: true,
   getCompatibilityReport: true,
   getWarnings: true,
@@ -143,6 +146,7 @@ export const RUNTIME_API_HANDLE_SHAPE_CHECK: Record<keyof RuntimeApiHandle, true
   getCanonicalDocument: true,
   findAllText: true,
   getReviewWorkSnapshot: true,
+  getSuggestionsSnapshot: true,
   acceptChange: true,
   rejectChange: true,
   resolveComment: true,

package/src/api/v3/runtime/document.ts

@@ -1,14 +1,16 @@
 /**
  * @endStateApi v3 — `runtime.document` family.
  *
- * See docs/reference/public-api.md § runtime.document. Three functions:
+ * See docs/reference/public-api.md § runtime.document.
  * `load` (partial — runtime pre-load is the caller's responsibility; v3
- * exposes a re-mount semantic later), `export` (live; delegates to
- * `runtime.exportDocx`), `validate` (partial; read live, write mock).
+ * exposes a re-mount semantic later), `getMode` / `setMode` (live;
+ * delegates to the runtime view-state posture), `export` (live; delegates
+ * to `runtime.exportDocx`), `validate` (partial; read live, write mock).
  */
 
 import type { RuntimeApiHandle } from "../_runtime-handle.ts";
 import type {
+  DocumentMode,
   EditorError,
   ExportDocxOptions,
   ExportResult,
@@ -88,6 +90,42 @@ export const loadMetadata: ApiV3FnMetadata = {
     "§Runtime API § runtime.document.load. Graduation (2026-04-22, post-eb7d14fa): `live` via direct delegation to `loadDocxSessionAsync` (src/session/import/loader.ts). Returns a PersistedEditorSnapshot the caller can pass to DocxSession.reopenFromSnapshot or persist for later rehydrate. Note per arch §R8 Option B: v3 does NOT construct the receiving DocumentRuntime — that's the caller's job via createDocumentRuntime(initialSessionState).",
 };
 
+/* ================================================================== */
+/*  mode                                                              */
+/* ================================================================== */
+
+export const getModeMetadata: ApiV3FnMetadata = {
+  name: "runtime.document.getMode",
+  status: "live",
+  sourceLayer: "runtime-core",
+  liveEvidence: {
+    runnerTest: "test/api/v3/create-accepts-handle.test.ts",
+    commit: "refactor-03-tracked-changes-v1-api-adapter",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "document", auditCategory: "document-mode" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference:
+    "§Runtime API § runtime.document.getMode. Live adapter over the runtime render snapshot's DocumentMode; suggesting remains the tracked-change authoring posture.",
+};
+
+export const setModeMetadata: ApiV3FnMetadata = {
+  name: "runtime.document.setMode",
+  status: "live",
+  sourceLayer: "runtime-core",
+  liveEvidence: {
+    runnerTest: "test/api/v3/create-accepts-handle.test.ts",
+    commit: "refactor-03-tracked-changes-v1-api-adapter",
+  },
+  uxIntent: { uiVisible: true, expectsUxResponse: "surface-refresh", expectedDelta: "document mode changes" },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "document", auditCategory: "document-mode" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference:
+    "§Runtime API § runtime.document.setMode. Live adapter over runtime.setDocumentMode(); mode 'suggesting' is the v3 entry to tracked-change authoring.",
+};
+
 /* ================================================================== */
 /*  export                                                            */
 /* ================================================================== */
@@ -196,6 +234,26 @@ export function createDocumentFamily(runtime: RuntimeApiHandle) {
       return result;
     },
 
+    getMode(): DocumentMode {
+      // @endStateApi — live. Reads the runtime view-state posture that
+      // render snapshots already expose.
+      return runtime.getRenderSnapshot().documentMode;
+    },
+
+    setMode(mode: DocumentMode): void {
+      // @endStateApi — live. Delegates to the runtime's document-mode
+      // setter; `suggesting` is the tracked-change authoring posture.
+      runtime.setDocumentMode(mode);
+      emitUxResponse(runtime, {
+        apiFn: setModeMetadata.name,
+        intent: setModeMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: setModeMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "surface-refresh", payload: { mode } },
+      });
+    },
+
     async export(options?: ExportDocxOptions): Promise<ExportResult> {
       // @endStateApi — live. Delegates to the shipped runtime export path.
       const result = await runtime.exportDocx(options);

package/src/api/v3/runtime/review.ts

@@ -1,14 +1,15 @@
 /**
  * @endStateApi v3 — `runtime.review` family.
  *
- * getComments (live) / getChanges (live) / acceptChange (live) /
- * resolveComment (live).
+ * getComments (live) / getChanges (live) / getSuggestions (live) /
+ * acceptChange (live) / rejectChange (live) / resolveComment (live).
  */
 
 import type { RuntimeApiHandle } from "../_runtime-handle.ts";
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
 import type {
   CommentSidebarThreadSnapshot,
+  SuggestionsSnapshot,
   TrackedChangeEntrySnapshot,
 } from "../../public-types.ts";
 import { emitUxResponse } from "../_ux-response.ts";
@@ -51,6 +52,22 @@ export const getChangesMetadata: ApiV3FnMetadata = {
   rwdReference: "§Runtime API § runtime.review.getChanges",
 };
 
+export const getSuggestionsMetadata: ApiV3FnMetadata = {
+  name: "runtime.review.getSuggestions",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/create-accepts-handle.test.ts",
+    commit: "refactor-03-tracked-changes-v1-api-adapter",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "document", auditCategory: "review-read" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.review.getSuggestions. Live adapter over runtime.getSuggestionsSnapshot(); semantic suggestion readback is grouped by the runtime, not by v3.",
+};
+
 export const acceptChangeMetadata: ApiV3FnMetadata = {
   name: "runtime.review.acceptChange",
   status: "live",
@@ -70,6 +87,23 @@ export const acceptChangeMetadata: ApiV3FnMetadata = {
   rwdReference: "§Runtime API § runtime.review.acceptChange",
 };
 
+export const rejectChangeMetadata: ApiV3FnMetadata = {
+  name: "runtime.review.rejectChange",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/create-accepts-handle.test.ts",
+    commit: "refactor-03-tracked-changes-v1-api-adapter",
+  },
+  uxIntent: { uiVisible: true, expectsUxResponse: "inline-change", expectedDelta: "change mark disappears and text restores" },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "scope", auditCategory: "change-reject" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§Runtime API § runtime.review.rejectChange. Live adapter over runtime.rejectChange; mirrors acceptChange for individual tracked-change review.",
+};
+
 export const resolveCommentMetadata: ApiV3FnMetadata = {
   name: "runtime.review.resolveComment",
   status: "live",
@@ -100,6 +134,12 @@ export function createReviewFamily(runtime: RuntimeApiHandle) {
       return runtime.getRenderSnapshot().trackedChanges.revisions;
     },
 
+    getSuggestions(): SuggestionsSnapshot {
+      // @endStateApi — live. Delegates to the runtime's semantic
+      // suggestion grouping rather than regrouping raw revisions here.
+      return runtime.getSuggestionsSnapshot();
+    },
+
     acceptChange(changeId: string): void {
       // @endStateApi — live. Delegates.
       runtime.acceptChange(changeId);
@@ -113,6 +153,19 @@ export function createReviewFamily(runtime: RuntimeApiHandle) {
       });
     },
 
+    rejectChange(changeId: string): void {
+      // @endStateApi — live. Delegates.
+      runtime.rejectChange(changeId);
+      emitUxResponse(runtime, {
+        apiFn: rejectChangeMetadata.name,
+        intent: rejectChangeMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: rejectChangeMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "inline-change", payload: { changeId } },
+      });
+    },
+
     resolveComment(commentId: string): void {
       // @endStateApi — live.
       runtime.resolveComment(commentId);

package/src/io/normalize/normalize-text.ts

@@ -671,7 +671,10 @@ function normalizeDrawingFrameNode(
     const filename = packagePartName.slice(packagePartName.lastIndexOf("/") + 1) || "image.bin";
     state.media.items[node.content.mediaId] = {
       mediaId: node.content.mediaId,
-      contentType: existingMediaItem?.contentType ?? "application/octet-stream",
+      contentType:
+        node.content.contentType ??
+        existingMediaItem?.contentType ??
+        "application/octet-stream",
       filename,
       packagePartName,
       relationshipId: node.content.blipRef,

package/src/io/ooxml/parse-drawing.ts

@@ -188,8 +188,12 @@ function resolveContent(
           const partPath = normalizePartPath(
             resolveRelationshipTarget(opts.sourcePartPath ?? "/word/document.xml", rel),
           );
+          const mediaPart = opts.mediaParts?.get(partPath);
           pic.packagePartName = partPath;
           pic.mediaId = `media:${partPath.slice(1)}`;
+          if (mediaPart?.contentType) {
+            pic.contentType = mediaPart.contentType;
+          }
         }
         // F4.1 — preserve outer drawing XML for lossless round-trip serialization
         pic.rawXml = rawXml;

package/src/model/canonical-document.ts

@@ -1922,6 +1922,8 @@ export interface PictureContent {
   mediaId?: string;
   /** Absolute package path for media catalog lookup. */
   packagePartName?: string;
+  /** MIME resolved from the OPC media part, when known. */
+  contentType?: string;
   srcRect?: { top: number; bottom: number; left: number; right: number };
   stretch?: boolean;
   /**

package/src/ui/WordReviewEditor.tsx

@@ -2414,9 +2414,10 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
     function addReviewComment(): string | null {
       try {
         const { commentId } = activeRuntime.addComment({
-          anchor: snapshot.selection.activeRange,
+          anchor: resolveCommentCommandAnchor(snapshot),
           body: "",
           authorId: currentUser.userId,
+          snapToSafeBoundary: true,
         });
         activeRuntime.openComment(commentId);
         setActiveRailTab("comments");
@@ -3341,13 +3342,40 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         onToggleItalic: commands.onToggleItalic,
         onToggleUnderline: commands.onToggleUnderline,
         onToggleStrikethrough: commands.onToggleStrikethrough,
+        onSetParagraphStyle: (styleId) => {
+          const resolvedStyleId = resolveProductParagraphStyleId(styleCatalog, styleId);
+          if (!resolvedStyleId) {
+            activeRuntime.emitBlockedCommand("setParagraphStyle", [{
+              code: "unsupported_surface",
+              message: `${styleId} is not available in this document's style catalog.`,
+            }]);
+            return;
+          }
+          commands.onSetParagraphStyle?.(resolvedStyleId);
+        },
+        onSetFontFamily: commands.onSetFontFamily,
+        onSetFontSize: commands.onSetFontSize,
+        onSetTextColor: commands.onSetTextColor,
+        onSetHighlightColor: commands.onSetHighlightColor,
         onToggleBulletedList: commands.onToggleBulletedList,
         onToggleNumberedList: commands.onToggleNumberedList,
         onOutdent: commands.onOutdent,
         onIndent: commands.onIndent,
         onSetAlignment: (alignment) => commands.onSetAlignment?.(alignment),
+        onInsertPageBreak: commands.onInsertPageBreak,
+        onInsertSectionBreak: (type) => commands.onInsertSectionBreak?.(type),
         onInsertTable: commands.onInsertTable,
         onAddComment: commands.onAddComment,
+        onFindRequested: onFindRequested
+          ? () => onFindRequested({ selectionText: "", selectionRange: snapshot.selection })
+          : undefined,
+        onReplaceRequested: onReplaceRequested
+          ? () => onReplaceRequested({ selectionText: "", selectionRange: snapshot.selection })
+          : undefined,
+        onPrintRequested,
+        onGoToRequested: onGoToRequested
+          ? () => onGoToRequested({ selectionText: "", selectionRange: snapshot.selection })
+          : undefined,
         onInsertRowAbove: commands.onAddRowBefore,
         onInsertRowBelow: commands.onAddRowAfter,
         onInsertColumnBefore: commands.onAddColumnBefore,
@@ -3362,7 +3390,17 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       return editorActionHost
         ? { ...defaultHost, ...editorActionHost }
         : defaultHost;
-    }, [activeRuntime, commands, editorActionHost]);
+    }, [
+      activeRuntime,
+      commands,
+      editorActionHost,
+      onFindRequested,
+      onGoToRequested,
+      onPrintRequested,
+      onReplaceRequested,
+      snapshot.selection,
+      styleCatalog,
+    ]);
 
     const harnessShowUnsupportedPreviews = readHarnessDebugPortsFlag(__harnessDebugPorts, "unsupportedObjectPreviews");
     const effectiveShowUnsupportedPreviews = computeEffectiveShowUnsupportedPreviews({
@@ -4155,6 +4193,176 @@ function summarizeSelectionPreview(snapshot: RuntimeRenderSnapshot): string | nu
   return preview.length > 48 ? `${preview.slice(0, 45)}...` : preview;
 }
 
+function resolveCommentCommandAnchor(
+  snapshot: RuntimeRenderSnapshot,
+): PublicSelectionSnapshot["activeRange"] {
+  const selection = snapshot.selection;
+  if (!selection.isCollapsed && selection.activeRange.kind === "range") {
+    return selection.activeRange;
+  }
+
+  const collapsedRange = resolveCollapsedCommentRange(snapshot.surface, selection);
+  return collapsedRange
+    ? {
+        kind: "range",
+        from: collapsedRange.from,
+        to: collapsedRange.to,
+        assoc: { start: -1, end: 1 },
+      }
+    : selection.activeRange;
+}
+
+function resolveCollapsedCommentRange(
+  surface: RuntimeRenderSnapshot["surface"],
+  selection: RuntimeRenderSnapshot["selection"],
+): { from: number; to: number } | null {
+  if (!surface) {
+    return null;
+  }
+
+  const position = selection.activeRange.kind === "node"
+    ? selection.activeRange.at
+    : selection.head;
+  const paragraph =
+    findParagraphRangeAtPosition(surface.blocks, position) ??
+    findFirstNonEmptyParagraphRange(surface.blocks);
+  return paragraph
+    ? resolveWordRangeInsideParagraph(surface.plainText, paragraph, position)
+    : null;
+}
+
+function findParagraphRangeAtPosition(
+  blocks: readonly SurfaceBlockSnapshot[],
+  position: number,
+): { from: number; to: number } | null {
+  for (const block of blocks) {
+    if (
+      block.kind === "paragraph" &&
+      block.to > block.from &&
+      position >= block.from &&
+      position <= block.to
+    ) {
+      return { from: block.from, to: block.to };
+    }
+    const nested = findParagraphRangeInNestedBlocks(block, position);
+    if (nested) {
+      return nested;
+    }
+  }
+  return null;
+}
+
+function findFirstNonEmptyParagraphRange(
+  blocks: readonly SurfaceBlockSnapshot[],
+): { from: number; to: number } | null {
+  for (const block of blocks) {
+    if (block.kind === "paragraph" && block.to > block.from) {
+      return { from: block.from, to: block.to };
+    }
+    const nested = findFirstNonEmptyParagraphInNestedBlocks(block);
+    if (nested) {
+      return nested;
+    }
+  }
+  return null;
+}
+
+function findParagraphRangeInNestedBlocks(
+  block: SurfaceBlockSnapshot,
+  position: number,
+): { from: number; to: number } | null {
+  if (block.kind === "sdt_block") {
+    return findParagraphRangeAtPosition(block.children, position);
+  }
+  if (block.kind === "table") {
+    for (const row of block.rows) {
+      for (const cell of row.cells) {
+        const nested = findParagraphRangeAtPosition(cell.content, position);
+        if (nested) {
+          return nested;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+function findFirstNonEmptyParagraphInNestedBlocks(
+  block: SurfaceBlockSnapshot,
+): { from: number; to: number } | null {
+  if (block.kind === "sdt_block") {
+    return findFirstNonEmptyParagraphRange(block.children);
+  }
+  if (block.kind === "table") {
+    for (const row of block.rows) {
+      for (const cell of row.cells) {
+        const nested = findFirstNonEmptyParagraphRange(cell.content);
+        if (nested) {
+          return nested;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+function resolveWordRangeInsideParagraph(
+  plainText: string,
+  paragraph: { from: number; to: number },
+  position: number,
+): { from: number; to: number } {
+  const paragraphFrom = paragraph.from;
+  const paragraphTo = paragraph.to;
+  const fallback = { from: paragraphFrom, to: paragraphTo };
+  if (paragraphTo <= paragraphFrom) {
+    return fallback;
+  }
+
+  let cursor = Math.max(paragraphFrom, Math.min(position, paragraphTo - 1));
+  if (isCommentWordBoundary(plainText.charAt(cursor))) {
+    const next = findNearestCommentTextOffset(plainText, cursor, paragraphFrom, paragraphTo);
+    if (next === null) {
+      return fallback;
+    }
+    cursor = next;
+  }
+
+  let from = cursor;
+  while (from > paragraphFrom && !isCommentWordBoundary(plainText.charAt(from - 1))) {
+    from -= 1;
+  }
+
+  let to = cursor + 1;
+  while (to < paragraphTo && !isCommentWordBoundary(plainText.charAt(to))) {
+    to += 1;
+  }
+
+  return to > from ? { from, to } : fallback;
+}
+
+function findNearestCommentTextOffset(
+  plainText: string,
+  cursor: number,
+  from: number,
+  to: number,
+): number | null {
+  for (let distance = 1; distance < to - from; distance += 1) {
+    const right = cursor + distance;
+    if (right < to && !isCommentWordBoundary(plainText.charAt(right))) {
+      return right;
+    }
+    const left = cursor - distance;
+    if (left >= from && !isCommentWordBoundary(plainText.charAt(left))) {
+      return left;
+    }
+  }
+  return null;
+}
+
+function isCommentWordBoundary(value: string): boolean {
+  return value.length === 0 || /\s/.test(value);
+}
+
 function selectionToolbarAnchorsEqual(
   left: SelectionToolbarAnchor | null,
   right: SelectionToolbarAnchor | null,
@@ -4574,6 +4782,39 @@ function createSelectionToolbarStyleBadge(
   return { label: styleEntry.displayName };
 }
 
+function resolveProductParagraphStyleId(
+  styleCatalog: StyleCatalogSnapshot,
+  requestedStyleId: string,
+): string | null {
+  switch (requestedStyleId) {
+    case "Heading1":
+      return resolveHeadingShortcutStyleId(styleCatalog, 1);
+    case "Heading2":
+      return resolveHeadingShortcutStyleId(styleCatalog, 2);
+    case "Heading3":
+      return resolveHeadingShortcutStyleId(styleCatalog, 3);
+    case "Normal": {
+      const defaultStyle = styleCatalog.paragraphs.find((entry) => entry.isDefault);
+      if (defaultStyle) return defaultStyle.styleId;
+      break;
+    }
+    default:
+      break;
+  }
+
+  const requestedToken = normalizeProductStyleToken(requestedStyleId);
+  const match = styleCatalog.paragraphs.find(
+    (entry) =>
+      normalizeProductStyleToken(entry.styleId) === requestedToken ||
+      normalizeProductStyleToken(entry.displayName) === requestedToken,
+  );
+  return match?.styleId ?? null;
+}
+
+function normalizeProductStyleToken(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
 function createSelectionToolbarListBadge(
   viewState: ReturnType<WordReviewEditorRuntime["getViewState"]>,
 ): SelectionToolbarModel["badges"][number] | null {