@beyondwork/docx-react-component 1.0.52 → 1.0.54

package/src/runtime/prerender/prerender-document.ts

@@ -10,7 +10,11 @@ import {
 } from "../layout/layout-engine-version.ts";
 import { createLayoutEngine } from "../layout/layout-engine-instance.ts";
 import { createEditorSurfaceSnapshot } from "../surface-projection.ts";
-import type { CacheEnvelope } from "./cache-envelope.ts";
+import { buildCompatibilityReport } from "../../validation/compatibility-engine.ts";
+import {
+  CACHE_NORMALIZED_GENERATED_AT,
+  type CacheEnvelope,
+} from "./cache-envelope.ts";
 import {
   computeStructuralHash,
   deriveCacheKey,
@@ -167,6 +171,17 @@ export async function prerenderDocument(
     canonicalDocumentHash,
   });
 
+  // Phase 2 Finale C3: pre-compute `compatibilityReport` so the warm Plan B
+  // short-circuit in `loadDocxEditorSessionAsync` can skip the live
+  // `buildCompatibilityReport` call (~60–100 ms on extra-large). The report
+  // is a pure function of `canonicalDocument` + `generatedAt`; pinning
+  // `generatedAt` to `CACHE_NORMALIZED_GENERATED_AT` keeps the envelope
+  // byte-identical across two sequential prerenders on identical input.
+  const compatibilityReport = buildCompatibilityReport({
+    document: envelope,
+    generatedAt: CACHE_NORMALIZED_GENERATED_AT,
+  });
+
   const cacheBlob: CacheEnvelope = {
     schemaVersion: LAYCACHE_SCHEMA_VERSION,
     engineVersion: LAYOUT_ENGINE_VERSION,
@@ -176,6 +191,7 @@ export async function prerenderDocument(
     graph,
     surface,
     canonicalDocument: envelope,
+    compatibilityReport,
   };
 
   // Plan B B.5 — persistToCustomXml: inject the envelope into the docx's

package/src/runtime/render/render-frame-diff.ts

@@ -22,6 +22,7 @@ import type {
   RenderPage,
   RenderStoryRegion,
   DecorationIndex,
+  PageChromeReservations,
 } from "./render-frame-types.ts";
 
 // ---------------------------------------------------------------------------
@@ -46,6 +47,14 @@ export interface ChangedPageEntry {
      */
     changedBlockIds: readonly string[];
   }[];
+  /**
+   * R1: Set when the page's physical frame rect changed but no individual
+   * block regions changed. Consumers that iterate `regions` for targeted
+   * re-render targets must also honour this flag to avoid silently skipping
+   * pages whose geometry shifted without block-level changes (e.g. zoom
+   * change or page margin edit that shifts every page frame uniformly).
+   */
+  pageFrameChanged?: boolean;
 }
 
 export interface RenderFrameDiff {
@@ -110,10 +119,21 @@ export function diffRenderFrames(
       continue;
     }
     const regions = diffPage(prevPage, nextPage, prev.decorationIndex, next.decorationIndex);
-    if (regions.length === 0 && rectEquals(prevPage.frame, nextPage.frame)) {
+    // R1: track page-frame geometry changes independently of block regions.
+    const frameChanged = !rectEquals(prevPage.frame, nextPage.frame);
+    // R2: track chrome-reservation changes so chrome re-projection isn't skipped.
+    const reservationsChanged = !reservationsEqual(
+      prevPage.chromeReservations,
+      nextPage.chromeReservations,
+    );
+    if (regions.length === 0 && !frameChanged && !reservationsChanged) {
       unchangedPages.push(pageIndex);
     } else {
-      changedPages.push({ pageIndex, regions });
+      changedPages.push({
+        pageIndex,
+        regions,
+        ...(frameChanged ? { pageFrameChanged: true } : {}),
+      });
     }
   }
 
@@ -268,6 +288,22 @@ function decorationHashForBlock(
   return tokens.join("|");
 }
 
+// ---------------------------------------------------------------------------
+// Chrome reservations compare
+// ---------------------------------------------------------------------------
+
+// R2: Compare all five reservation fields so changes to rail/balloon lanes
+// or footnote area trigger changedPages, not unchangedPages.
+function reservationsEqual(a: PageChromeReservations, b: PageChromeReservations): boolean {
+  return (
+    a.railLaneTwips === b.railLaneTwips &&
+    a.balloonLaneTwips === b.balloonLaneTwips &&
+    a.footnoteAreaTwips === b.footnoteAreaTwips &&
+    a.pageFrameWidthPx === b.pageFrameWidthPx &&
+    a.pageFrameHeightPx === b.pageFrameHeightPx
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Geometry compare
 // ---------------------------------------------------------------------------

package/src/runtime/render/render-kernel.ts

@@ -23,12 +23,8 @@ import type {
   PublicRegionBlock,
   WordReviewEditorLayoutFacet,
 } from "../layout/public-facet.ts";
-import type {
-  CommentDecorationModel,
-} from "../../ui/headless/comment-decoration-model.ts";
-import type {
-  RevisionDecorationModel,
-} from "../../ui/headless/revision-decoration-model.ts";
+import type { CommentDecorationModel } from "../../ui/headless/comment-decoration-model.ts";
+import type { RevisionDecorationModel } from "../../ui/headless/revision-decoration-model.ts";
 import type { ScopeRailSegment } from "../workflow-rail-segments.ts";
 import {
   resolveDecorationIndex,
@@ -148,6 +144,24 @@ export function createRenderKernel(input: CreateRenderKernelInput): RenderKernel
   // is an optimizer for repeat reads at the same revision.
   let lastEmittedFrame: RenderFrame | null = null;
 
+  // P14.c — single-slot DecorationIndex cache. `resolveDecorationIndex`
+  // is O(n × m) in decorations × offsets; it is safe to reuse the prior
+  // result when the layout revision, active story, zoom, and every source
+  // reference are all unchanged from the previous build.  The frame-level
+  // `cache` already prevents rebuilds for repeat reads; this slot covers
+  // the post-invalidate rebuild where layout changed but decorations did not.
+  let diCacheKey: {
+    revision: number;
+    activeStoryKind: string;
+    zoomPxPerTwip: number;
+    workflowSegments: readonly ScopeRailSegment[] | undefined;
+    comments: CommentDecorationModel | null | undefined;
+    revisions: RevisionDecorationModel | null | undefined;
+    searchMatches: readonly SearchMatchRange[] | undefined;
+    lockedRanges: readonly LockedRangeInput[] | undefined;
+  } | null = null;
+  let diCacheValue: DecorationIndex | null = null;
+
   const listeners = new Set<(event: RenderKernelEvent) => void>();
   const unsubscribeFacet = facet.subscribe((event) => {
     // Any layout-changing event invalidates the cached frame.  We rely on
@@ -208,6 +222,14 @@ export function createRenderKernel(input: CreateRenderKernelInput): RenderKernel
       pendingDeltas,
       zoom.pxPerTwip,
     );
+    // Revision: keyed off the engine's current page graph so repeated reads
+    // at the same revision return the same cached frame.  We derive it
+    // from the first page since the engine stamps every page with the
+    // graph's revision indirectly via pageId; fall back to 0 if empty.
+    const revision = filteredPages[0]
+      ? Number(extractRevisionFromPageId(filteredPages[0].pageId))
+      : 0;
+
     const includeDecorations = options?.includeDecorations ?? true;
     const sources = input.getDecorationSources?.();
     const hasSources =
@@ -217,11 +239,45 @@ export function createRenderKernel(input: CreateRenderKernelInput): RenderKernel
         (sources.revisions?.revisions?.length ?? 0) > 0 ||
         (sources.searchMatches && sources.searchMatches.length > 0) ||
         (sources.lockedRanges && sources.lockedRanges.length > 0));
-    const decorationIndex: DecorationIndex = !includeDecorations
-      ? EMPTY_DECORATION_INDEX
-      : hasSources
-        ? resolveDecorationIndex({ anchorIndex: baseAnchorIndex, ...sources })
-        : buildDecorationIndex(renderPages);
+    // P14.c — DecorationIndex single-slot cache. Check reference equality
+    // on every source before calling the O(n × m) resolver.
+    const newDIKey = {
+      revision: Number.isFinite(revision) ? revision : 0,
+      activeStoryKind: activeStory.kind,
+      zoomPxPerTwip: zoom.pxPerTwip,
+      workflowSegments: sources?.workflowSegments,
+      comments: sources?.comments,
+      revisions: sources?.revisions,
+      searchMatches: sources?.searchMatches,
+      lockedRanges: sources?.lockedRanges,
+    };
+    const diCacheHit =
+      hasSources &&
+      diCacheKey !== null &&
+      diCacheValue !== null &&
+      diCacheKey.revision === newDIKey.revision &&
+      diCacheKey.activeStoryKind === newDIKey.activeStoryKind &&
+      diCacheKey.zoomPxPerTwip === newDIKey.zoomPxPerTwip &&
+      diCacheKey.workflowSegments === newDIKey.workflowSegments &&
+      diCacheKey.comments === newDIKey.comments &&
+      diCacheKey.revisions === newDIKey.revisions &&
+      diCacheKey.searchMatches === newDIKey.searchMatches &&
+      diCacheKey.lockedRanges === newDIKey.lockedRanges;
+
+    let decorationIndex: DecorationIndex;
+    if (!includeDecorations) {
+      decorationIndex = EMPTY_DECORATION_INDEX;
+    } else if (hasSources) {
+      if (diCacheHit) {
+        decorationIndex = diCacheValue!;
+      } else {
+        decorationIndex = resolveDecorationIndex({ anchorIndex: baseAnchorIndex, ...sources });
+        diCacheKey = newDIKey;
+        diCacheValue = decorationIndex;
+      }
+    } else {
+      decorationIndex = buildDecorationIndex(renderPages);
+    }
     const anchorIndex = buildAnchorIndex(
       renderPages,
       pendingDeltas,
@@ -229,14 +285,6 @@ export function createRenderKernel(input: CreateRenderKernelInput): RenderKernel
       decorationIndex,
     );
 
-    // Revision: keyed off the engine's current page graph so repeated reads
-    // at the same revision return the same cached frame.  We derive it
-    // from the first page since the engine stamps every page with the
-    // graph's revision indirectly via pageId; fall back to 0 if empty.
-    const revision = filteredPages[0]
-      ? Number(extractRevisionFromPageId(filteredPages[0].pageId))
-      : 0;
-
     const frame: RenderFrame = {
       revision: Number.isFinite(revision) ? revision : 0,
       measurementFidelity,

package/src/runtime/surface-projection.ts

@@ -419,6 +419,9 @@ function createTableBlock(
         ...(cellBorders.borderRight ? { borderRight: cellBorders.borderRight } : {}),
         ...(cellBorders.borderBottom ? { borderBottom: cellBorders.borderBottom } : {}),
         ...(cellBorders.borderLeft ? { borderLeft: cellBorders.borderLeft } : {}),
+        // R3.a Phase 2: per-cell text-flow direction copied from canonical
+        // TableCellNode. Node-view renders `tbRl` / `btLr` as CSS writing-mode.
+        ...(cell.textDirection ? { textDirection: cell.textDirection } : {}),
         ...(bandClasses ? { bandClasses } : {}),
         content: cellContent,
       });
@@ -437,6 +440,30 @@ function createTableBlock(
     });
   }
 
+  // R3.a Phase 2 — fold the resolver's table-level bundle onto the surface
+  // block when any field is populated. Borders carry the typed BorderSpec per
+  // side; the node-view converts the four outer sides to CSS shorthand at
+  // render time. insideH / insideV flow through for round-trip + future use,
+  // but their visual effect is realized via per-cell borders today.
+  const tr = resolvedTable.tableResolved;
+  const trHasContent =
+    tr.width !== undefined ||
+    tr.layoutMode !== undefined ||
+    tr.cellSpacing !== undefined ||
+    tr.borders !== undefined;
+  const tableResolvedAttr = trHasContent
+    ? {
+        ...(tr.width !== undefined ? { width: tr.width } : {}),
+        ...(tr.widthType !== undefined ? { widthType: tr.widthType } : {}),
+        ...(tr.layoutMode !== undefined ? { layoutMode: tr.layoutMode } : {}),
+        ...(tr.cellSpacing !== undefined ? { cellSpacing: tr.cellSpacing } : {}),
+        ...(tr.cellSpacingType !== undefined
+          ? { cellSpacingType: tr.cellSpacingType }
+          : {}),
+        ...(tr.borders ? { borders: tr.borders } : {}),
+      }
+    : undefined;
+
   return {
     block: {
       blockId: `table-${tableIndex}`,
@@ -447,6 +474,7 @@ function createTableBlock(
       gridColumns: table.gridColumns,
       ...(resolvedTable.table?.alignment ? { alignment: resolvedTable.table.alignment } : {}),
       tblLook: resolvedTable.effectiveTblLook,
+      ...(tableResolvedAttr ? { tableResolved: tableResolvedAttr } : {}),
       rows,
     },
     lockedFragmentIds,

package/src/runtime/table-schema.ts

@@ -42,6 +42,8 @@ type TableCellAttrs = {
   borderRight?: string | null;
   borderBottom?: string | null;
   borderLeft?: string | null;
+  /** R3.a Phase 2 — per-cell text-flow direction. */
+  textDirection?: "lrTb" | "tbRl" | "btLr" | null;
   bandClasses?: string | null;
 };
 
@@ -188,6 +190,13 @@ const tableCellSpecAttrs = {
   borderRight: { default: null },
   borderBottom: { default: null },
   borderLeft: { default: null },
+  /**
+   * R3.a Phase 2 — per-cell text-flow direction copied from
+   * `TableCellNode.textDirection` ("lrTb" | "tbRl" | "btLr"). Node-view maps
+   * `tbRl` → `writing-mode: vertical-rl`, `btLr` → `writing-mode: vertical-lr`,
+   * `lrTb` (or null) → unset.
+   */
+  textDirection: { default: null },
   /** R2b: space-joined band classes ("band-firstRow band-band1Horz") from the resolved style. */
   bandClasses: { default: null },
 } as const;
@@ -210,6 +219,24 @@ export const tableNodeSpec: NodeSpec = {
     tblLookNoVBand: { default: false },
     /** R2d: raw `w:tblLook/@w:val` hex preserved verbatim so vendor-extended bits survive round-trip. */
     tblLookVal: { default: null },
+    // R3.a Phase 2 — table-level resolved properties projected from
+    // ResolvedTableLevelProperties. Each is nullable so PM's null-vs-undefined
+    // preference is satisfied. Width is in twips (dxa) or fiftieths-of-percent
+    // (pct); spacing is twips (dxa). Borders are CSS shorthand strings (e.g.
+    // "1px solid #000000") for the four outer sides; insideH / insideV are
+    // realized through per-cell border attrs (CSS has no native
+    // table-inside-border property — see applyTableAttrs comment).
+    tableWidth: { default: null },
+    tableWidthType: { default: null },
+    tableLayoutMode: { default: null },
+    tableCellSpacing: { default: null },
+    tableCellSpacingType: { default: null },
+    tableBorderTop: { default: null },
+    tableBorderRight: { default: null },
+    tableBorderBottom: { default: null },
+    tableBorderLeft: { default: null },
+    tableBorderInsideH: { default: null },
+    tableBorderInsideV: { default: null },
   },
   parseDOM: [{ tag: "table" }],
   toDOM(node) {

package/src/runtime/table-style-resolver.ts

@@ -27,10 +27,31 @@ export interface ResolvedTableRowStyle {
   activeConditionalRegions: TableStyleConditionalRegion[];
 }
 
+/**
+ * R3.a Phase 2 — typed bundle of table-level resolved properties projected onto
+ * the surface snapshot so the PM schema + node-view can render them inline at
+ * commit time.
+ *
+ * Borders are kept as the typed `TableBorders` shape here (BorderSpec per side);
+ * the surface-projection step converts them to per-side CSS shorthand strings
+ * (e.g. "1px solid #000") to mirror the existing `resolveCellBorderStyles`
+ * pattern at `surface-projection.ts:506`.
+ */
+export interface ResolvedTableLevelProperties {
+  width?: number;
+  widthType?: TableWidth["type"];
+  layoutMode?: "fixed" | "autofit";
+  cellSpacing?: number;
+  cellSpacingType?: TableWidth["type"];
+  borders?: TableBorders;
+}
+
 export interface ResolvedTableStyleResolution {
   rawTblLook?: TableLook;
   effectiveTblLook: TableLook;
   table?: TableStyleFormatting["table"];
+  /** R3.a Phase 2 — table-level resolved properties (width / layout / spacing / borders). */
+  tableResolved: ResolvedTableLevelProperties;
   rows: Array<{
     style: ResolvedTableRowStyle;
     cells: ResolvedTableCellStyle[];
@@ -140,10 +161,40 @@ export function resolveTableStyleResolution(
     },
   );
 
+  // R3.a Phase 2 — collect the table-level resolved property bundle. Direct
+  // TableNode properties win over the resolved table-style formatting; both
+  // paths still populate the optional fields independently so a partial style
+  // (e.g. style provides borders, direct provides width) merges cleanly.
+  const resolvedTableLevel: ResolvedTableLevelProperties = {};
+  const styleTable = resolvedStyle.formatting?.table;
+  const directWidth = table.width;
+  const styleWidth = styleTable?.width;
+  if (directWidth) {
+    resolvedTableLevel.width = directWidth.value;
+    resolvedTableLevel.widthType = directWidth.type;
+  } else if (styleWidth) {
+    resolvedTableLevel.width = styleWidth.value;
+    resolvedTableLevel.widthType = styleWidth.type;
+  }
+  if (table.layoutMode) {
+    resolvedTableLevel.layoutMode = table.layoutMode;
+  }
+  if (table.cellSpacing) {
+    resolvedTableLevel.cellSpacing = table.cellSpacing.value;
+    resolvedTableLevel.cellSpacingType = table.cellSpacing.type;
+  }
+  // Borders: prefer direct TableNode.borders, fall back to merged style borders.
+  // Both shapes are TableBorders so we can hand the side-bag straight back.
+  const mergedBorders = mergeBorderMap<TableBorders>(styleTable?.borders, table.borders);
+  if (mergedBorders) {
+    resolvedTableLevel.borders = mergedBorders;
+  }
+
   return {
     ...(table.tblLook ? { rawTblLook: table.tblLook } : {}),
     effectiveTblLook,
     ...(tableFormatting ? { table: tableFormatting } : {}),
+    tableResolved: resolvedTableLevel,
     rows,
   };
 }

package/src/ui/WordReviewEditor.tsx

@@ -782,7 +782,9 @@ export function __createWordReviewEditorRefBridge(
     clearWorkflowOverlay: () => {
       runtime.clearWorkflowOverlay();
     },
-    getWorkflowOverlay: () => clonePublicValue(runtime.getWorkflowOverlay()),
+    getWorkflowOverlay: () => {
+      return clonePublicValue(runtime.getWorkflowOverlay());
+    },
     setSharedWorkflowState: (state) => {
       runtime.setSharedWorkflowState(state === null ? null : clonePublicValue(state));
     },
@@ -1834,8 +1836,9 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         clearWorkflowOverlay: () => {
           activeRuntime.clearWorkflowOverlay();
         },
-        getWorkflowOverlay: () =>
-          clonePublicValue(activeRuntime.getWorkflowOverlay()),
+        getWorkflowOverlay: () => {
+          return clonePublicValue(activeRuntime.getWorkflowOverlay());
+        },
         setSharedWorkflowState: (state) => {
           activeRuntime.setSharedWorkflowState(state === null ? null : clonePublicValue(state));
         },

package/src/ui/editor-runtime-boundary.ts

@@ -8,6 +8,7 @@ import type {
   EditorError,
   EditorHostAdapter,
   EditorSessionState,
+  EditorSurfaceSnapshot,
   EditorViewStateSnapshot,
   EditorWarning,
   ExportDocxOptions,
@@ -134,6 +135,8 @@ export interface EditorRuntimeBoundaryState {
   runtime: WordReviewEditorRuntime | null;
   loadError: EditorError | null;
   activeRuntime: WordReviewEditorRuntime;
+  /** C2c: partial surface snapshot from body-normalize stage; null once full runtime is ready. */
+  progressiveSurface: EditorSurfaceSnapshot | null;
   commandAppliedBridge: RuntimeCommandAppliedBridge;
   fallbackSnapshot: RuntimeRenderSnapshot;
   loadingSessionState: EditorSessionState;
@@ -302,6 +305,12 @@ export function useEditorRuntimeBoundary(
 
   const [runtime, setRuntime] = useState<WordReviewEditorRuntime | null>(null);
   const [loadError, setLoadError] = useState<EditorError | null>(null);
+  // C2c: progressive initial mount — transient surface snapshot from the
+  // body-normalize stage. Cleared when the full runtime commits (setRuntime).
+  const [progressiveSurface, setProgressiveSurface] =
+    useState<EditorSurfaceSnapshot | null>(null);
+  const progressiveSurfaceRef = useRef<EditorSurfaceSnapshot | null>(null);
+  progressiveSurfaceRef.current = progressiveSurface;
   const runtimeRef = useRef<WordReviewEditorRuntime | null>(null);
   const pendingReadySourceRef = useRef<"docx" | "session" | "snapshot" | null>(null);
   const autosaveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -445,7 +454,20 @@ export function useEditorRuntimeBoundary(
             bytes: source.initialDocx,
             editorBuild: "dev",
             scheduler,
-            ...(probeResult ? { laycacheEnvelope: probeResult.envelope } : {}),
+            ...(probeResult ? { laycacheEnvelope: probeResult.envelope } : {
+              // C2c: on the cold path (no cached envelope), emit the first
+              // viewport surface as soon as body-normalize completes so the
+              // UI can show the first page before the full session is ready.
+              // Wrapped in startTransition so React treats this as a
+              // low-priority update — the full setRuntime commit (urgent)
+              // will preempt it if it arrives before React flushes the
+              // transition.
+              onProgressiveSnapshot: (partial) => {
+                React.startTransition(() => {
+                  setProgressiveSurface(partial.surface);
+                });
+              },
+            }),
           });
           if (cancelled) {
             scheduler.dispose();
@@ -478,6 +500,10 @@ export function useEditorRuntimeBoundary(
         recordPerfSample("runtime.create");
         runtimeRef.current = nextRuntime;
         pendingReadySourceRef.current = source.source;
+        // C2c: clear the transient progressive surface — the full runtime
+        // snapshot supersedes it. No need for startTransition here since
+        // this is the higher-priority commit that preempts the transition.
+        setProgressiveSurface(null);
         setRuntime(nextRuntime);
       } catch (error) {
         if (cancelled) {
@@ -627,6 +653,9 @@ export function useEditorRuntimeBoundary(
         sessionState: loadingSessionState,
         viewState: loadingViewState,
         navigation: loadingNavigation,
+        // C2c: ref so the bridge can serve the progressive surface in
+        // getRenderSnapshot().surface without recreating on each update.
+        progressiveSurfaceRef,
       }),
     [fallbackSnapshot, loadingNavigation, loadingSessionState, loadingViewState],
   );
@@ -635,6 +664,7 @@ export function useEditorRuntimeBoundary(
     runtime,
     loadError,
     activeRuntime: runtime ?? loadingRuntimeBridge,
+    progressiveSurface,
     commandAppliedBridge,
     fallbackSnapshot,
     loadingSessionState,
@@ -876,6 +906,8 @@ function createLoadingRuntimeBridge(input: {
   sessionState: EditorSessionState;
   viewState: EditorViewStateSnapshot;
   navigation: DocumentNavigationSnapshot;
+  /** C2c: when present, getRenderSnapshot() injects the progressive surface. */
+  progressiveSurfaceRef?: React.RefObject<EditorSurfaceSnapshot | null>;
 }): WordReviewEditorRuntime {
   const inertLayoutFacet = createInertLayoutFacet();
   const emptyFieldSnapshot: FieldSnapshot = {
@@ -908,7 +940,11 @@ function createLoadingRuntimeBridge(input: {
     subscribe: () => () => undefined,
     subscribeToEvents: () => () => undefined,
     emitBlockedCommand: () => undefined,
-    getRenderSnapshot: () => input.snapshot,
+    getRenderSnapshot: () => {
+      const progressive = input.progressiveSurfaceRef?.current;
+      if (progressive == null) return input.snapshot;
+      return { ...input.snapshot, surface: progressive };
+    },
     getCanonicalDocument: () => input.sessionState.canonicalDocument,
     getSourcePackage: () => input.sessionState.sourcePackage,
     replaceText: () => undefined,
@@ -922,6 +958,7 @@ function createLoadingRuntimeBridge(input: {
     }),
     dispatch: () => undefined,
     applyRemoteCommand: () => undefined,
+    applyRemoteCommandBatch: () => undefined,
     undo: () => undefined,
     redo: () => undefined,
     focus: () => undefined,

package/src/ui/headless/comment-decoration-model.ts

@@ -77,7 +77,61 @@ export function getCommentRangeState(
   };
 }
 
-export type MarkupDisplay = "clean" | "simple" | "all";
+/**
+ * Markup display mode — controls how tracked changes and comments render.
+ *
+ * L6d.N2 widens the union to Word's 4-mode grammar (`"all-markup"`,
+ * `"simple-markup"`, `"no-markup"`, `"original"`) while keeping the
+ * legacy aliases `"clean" | "simple" | "all"` for backward compat with
+ * hosts that already pass the old values.  Callers that switch on this
+ * value should either:
+ *   - handle both sets of names (the decoration models do), or
+ *   - normalize via `normalizeMarkupDisplay()` before matching.
+ *
+ * New in 6d.N2:
+ *   - `"original"` — hide insertions entirely, render deletions as
+ *     plain body text.  Shows what the document looked like before the
+ *     current batch of tracked changes.
+ */
+export type MarkupDisplay =
+  | "all-markup"
+  | "simple-markup"
+  | "no-markup"
+  | "original"
+  // Legacy aliases — accepted on the public API; prefer the canonical names above.
+  | "clean"
+  | "simple"
+  | "all";
+
+/**
+ * Collapse legacy `MarkupDisplay` aliases to their canonical Word-grammar
+ * name:
+ *   - `"all"` → `"all-markup"`
+ *   - `"simple"` → `"simple-markup"`
+ *   - `"clean"` → `"no-markup"`
+ *   - `"original"` → `"original"` (identity)
+ *
+ * The two sets remain interchangeable inside the decoration models, but
+ * external surfaces (selector labels, telemetry, host events) should
+ * normalize first so Word's grammar is the single source of truth.
+ */
+export function normalizeMarkupDisplay(
+  value: MarkupDisplay,
+): "all-markup" | "simple-markup" | "no-markup" | "original" {
+  switch (value) {
+    case "all":
+    case "all-markup":
+      return "all-markup";
+    case "simple":
+    case "simple-markup":
+      return "simple-markup";
+    case "clean":
+    case "no-markup":
+      return "no-markup";
+    case "original":
+      return "original";
+  }
+}
 
 export function getCommentHighlightClass(
   model: CommentDecorationModel | undefined,
@@ -90,10 +144,11 @@ export function getCommentHighlightClass(
     return "";
   }
 
-  switch (markupDisplay) {
-    case "clean":
+  switch (normalizeMarkupDisplay(markupDisplay)) {
+    case "no-markup":
+    case "original":
       return state.hasActive ? "bg-comment-soft" : "";
-    case "simple":
+    case "simple-markup":
       if (state.hasActive) {
         return "underline decoration-comment decoration-2 underline-offset-4";
       }
@@ -101,7 +156,7 @@ export function getCommentHighlightClass(
         return "underline decoration-comment/60 decoration-1 underline-offset-4";
       }
       return "underline decoration-comment/40 decoration-1 underline-offset-4";
-    case "all":
+    case "all-markup":
       if (state.hasActive) {
         return "bg-comment-strong";
       }