@beyondwork/docx-react-component 1.0.80 → 1.0.82

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.80",
+  "version": "1.0.82",
   "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

@@ -5611,17 +5611,16 @@ export interface WordReviewEditorProps {
     import("../ui/headless/chrome-registry").SelectionToolRegistryEntry
   >;
   /**
-   * Phase C.γ host-callback bag. When supplied, the workspace mounts
-   * `TwWorkspaceChromeHost` which in turn mounts the right-click
-   * context menu (`TwContextMenuPortal`) and the Ctrl/Cmd+K command
-   * palette (`TwCommandPaletteMount`), dispatching through the shared
-   * `editorActionRegistry`. Actions without a wired callback are
-   * hidden from every surface — progressive disclosure per
-   * `designsystem.md §2.1 principle 4`.
-   *
-   * Omit to preserve pre-Phase-C behavior (no right-click menu, no
-   * palette). Required for the default editor to expose the
-   * Phase C.γ surfaces shipped in `5fce913a`.
+   * Optional host-callback extension bag for workspace command chrome.
+   * The default `<WordReviewEditor />` path now mounts
+   * `TwWorkspaceChromeHost` with product-backed commands for formatting,
+   * 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
+   * every surface — progressive disclosure per `designsystem.md §2.1
+   * principle 4`.
    */
   editorActionHost?: import("../ui-tailwind/chrome/editor-action-registry").EditorActionHostCallbacks;
   /**
@@ -5637,8 +5636,8 @@ export interface WordReviewEditorProps {
   /**
    * Suppress the global Ctrl/Cmd+K palette listener — e.g. when a
    * higher-priority modal captures keyboard focus. Defaults to
-   * `false` (palette listener is active when `editorActionHost` is
-   * supplied).
+   * `false` (the default product command palette listener is active
+   * unless this prop suppresses it).
    */
   commandPaletteDisabled?: boolean;
   /**

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/api/v3/ui/chrome-composition.ts

@@ -131,6 +131,7 @@ export interface ChromeCompositionInput {
     | "simple"
     | "all";
   readonly activeRailTab?: EditorRailTab | null;
+  readonly railOpen?: boolean;
   readonly pinnedRailTabs?: ReadonlySet<EditorRailTab>;
   readonly density?: ChromeDensity;
   readonly containerWidth?: number;
@@ -255,13 +256,18 @@ function resolveVisibleRailTabs(
   railOpen: boolean,
   diagnosticsSignal: DiagnosticsSignal,
   pinned: ReadonlySet<EditorRailTab>,
+  mode: EditorChromeMode,
 ): ReadonlySet<EditorRailTab> {
   const visible = new Set<EditorRailTab>();
   if (railOpen) {
     visible.add("comments");
     visible.add("changes");
     visible.add("workflow");
-    if (diagnosticsSignal.severity !== "none" || diagnosticsSignal.count > 0) {
+    if (
+      diagnosticsSignal.severity !== "none" ||
+      diagnosticsSignal.count > 0 ||
+      mode === "more"
+    ) {
       visible.add("health");
     }
   }
@@ -294,11 +300,13 @@ export function resolveChromeComposition(
   const density: ChromeDensity = input.density ?? "standard";
   const pinnedRailTabs: ReadonlySet<EditorRailTab> =
     input.pinnedRailTabs ?? new Set<EditorRailTab>();
-  const railOpen = options.showReviewRail && visibility.reviewRail;
+  const railOpen =
+    input.railOpen ?? (options.showReviewRail && visibility.reviewRail);
   const visibleTabs = resolveVisibleRailTabs(
     railOpen,
     diagnosticsSignal,
     pinnedRailTabs,
+    mode,
   );
 
   // Default active tab: honor caller; otherwise land on the mode-appropriate tab.

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

@@ -186,6 +186,7 @@ import { EditorShellView } from "./editor-shell-view.tsx";
 import { TwDebugPresentation } from "../ui-tailwind/debug/index.ts";
 import { shellPasteFragmentParser as SHELL_PASTE_FRAGMENT_PARSER } from "../shell/paste-adapter.ts";
 import { EditorSurfaceController } from "./editor-surface-controller.tsx";
+import type { EditorActionHostCallbacks } from "../ui-tailwind/chrome/editor-action-registry";
 import type { TwWorkspaceChromeHostController } from "../ui-tailwind/chrome/tw-workspace-chrome-host";
 import {
   resolveChromePreset,
@@ -3306,6 +3307,100 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       },
     });
 
+    const productEditorActionHost = useMemo<EditorActionHostCallbacks>(() => {
+      const runClipboardCommand = (command: "copy" | "cut") => {
+        try {
+          globalThis.document?.execCommand?.(command);
+        } catch {
+          // Browser-native clipboard commands are best-effort fallbacks.
+        }
+      };
+
+      const defaultHost: EditorActionHostCallbacks = {
+        onUndo: commands.onUndo,
+        onRedo: commands.onRedo,
+        onCut: () => runClipboardCommand("cut"),
+        onCopy: () => runClipboardCommand("copy"),
+        onPaste: () => {
+          const readText = globalThis.navigator?.clipboard?.readText;
+          if (typeof readText !== "function") return;
+          void readText.call(globalThis.navigator.clipboard)
+            .then((text: string) => {
+              if (!text) return;
+              dispatchTextCommand(
+                activeRuntime,
+                { type: "insert-text", text },
+                DISPATCH_CONTEXT,
+              );
+            })
+            .catch(() => {
+              // Clipboard permission failures should not break the menu.
+            });
+        },
+        onToggleBold: commands.onToggleBold,
+        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,
+        onInsertColumnAfter: commands.onAddColumnAfter,
+        onDeleteRow: commands.onDeleteRow,
+        onDeleteColumn: commands.onDeleteColumn,
+        onDeleteTable: commands.onDeleteTable,
+        onMergeCells: commands.onMergeCells,
+        onSplitCell: commands.onSplitCell,
+      };
+
+      return editorActionHost
+        ? { ...defaultHost, ...editorActionHost }
+        : defaultHost;
+    }, [
+      activeRuntime,
+      commands,
+      editorActionHost,
+      onFindRequested,
+      onGoToRequested,
+      onPrintRequested,
+      onReplaceRequested,
+      snapshot.selection,
+      styleCatalog,
+    ]);
+
     const harnessShowUnsupportedPreviews = readHarnessDebugPortsFlag(__harnessDebugPorts, "unsupportedObjectPreviews");
     const effectiveShowUnsupportedPreviews = computeEffectiveShowUnsupportedPreviews({
       harnessShowUnsupportedPreviews,
@@ -3342,7 +3437,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         activeWorkflowScopeIds={workflowScopeSnapshot?.activeWorkItem?.scopeIds ?? []}
         workflowMetadata={workflowMarkupSnapshot?.metadata}
         onSelectionToolbarAnchorChange={handleSelectionToolbarAnchorChange}
-        {...(editorActionHost ? { onContextMenuRequested: handleContextMenuRequested } : {})}
+        onContextMenuRequested={handleContextMenuRequested}
         {...editorCallbacks}
         dispatchRuntimeCommand={(command) =>
           activeRuntime.applyActiveStoryTextCommand(command as never)
@@ -3420,8 +3515,9 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         interactionGuardSnapshot={interactionGuardSnapshot}
         chromePreset={effectiveChromePreset}
         chromeOptions={chromeOptions}
-        {...(editorActionHost ? { editorActionHost } : {})}
-        {...(editorActionHost ? { chromeControllerRef: teedChromeControllerRef } : {})}
+        density={density}
+        editorActionHost={productEditorActionHost}
+        chromeControllerRef={teedChromeControllerRef}
         {...(commandPaletteDisabled !== undefined
           ? { commandPaletteDisabled }
           : {})}
@@ -4515,6 +4611,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 {

package/src/ui/editor-shell-view.tsx

@@ -83,6 +83,7 @@ export interface EditorShellViewProps {
   interactionGuardSnapshot?: InteractionGuardSnapshot;
   chromePreset?: WordReviewEditorChromePreset;
   chromeOptions?: Partial<WordReviewEditorChromeOptions>;
+  density?: "compact" | "standard" | "comfortable";
   editorActionHost?: import("../ui-tailwind/chrome/editor-action-registry.ts").EditorActionHostCallbacks;
   chromeControllerRef?: React.Ref<
     import("../ui-tailwind/chrome/tw-workspace-chrome-host.tsx").TwWorkspaceChromeHostController