@beyondwork/docx-react-component 1.0.34 → 1.0.36

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.34",
+  "version": "1.0.36",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
-  "packageManager": "pnpm@10.30.3",
   "type": "module",
   "sideEffects": [
     "**/*.css"
@@ -89,31 +88,6 @@
     "./ui-tailwind/theme/editor-theme.css": "./src/ui-tailwind/theme/editor-theme.css"
   },
   "types": "./src/index.ts",
-  "scripts": {
-    "build": "tsup",
-    "test": "bash scripts/run-workspace-tests.sh",
-    "test:repo": "node scripts/run-repo-tests.mjs core",
-    "test:repo:all": "node scripts/run-repo-tests.mjs all",
-    "test:repo:optional": "node scripts/run-repo-tests.mjs optional",
-    "test:repo:browser-ui": "node scripts/run-repo-tests.mjs browser-ui",
-    "test:wcag-audit": "node scripts/run-repo-tests.mjs wcag-audit",
-    "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
-    "lint": "pnpm run lint:no-authored-js && pnpm run lint:docs-contracts && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
-    "lint:docs-contracts": "bash scripts/check-reference-load-contract.sh",
-    "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",
-    "lint:tsgo": "tsgo --noEmit -p tsconfig.build.json",
-    "lint:tsgo:harness": "pnpm --filter @docx-react-component/react-word-editor-harness lint:tsgo",
-    "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
-    "wave:doctor": "bash scripts/context7-export-env.sh run pnpm exec wave doctor --json",
-    "wave:dry-run": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main --dry-run --no-dashboard",
-    "wave:launch": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main",
-    "wave:launch:managed": "bash scripts/wave-launch.sh",
-    "wave:status": "bash scripts/wave-status.sh",
-    "wave:watch": "bash scripts/wave-watch.sh --follow",
-    "wave:dashboard:current": "bash scripts/wave-dashboard-attach.sh current",
-    "wave:dashboard:global": "bash scripts/wave-dashboard-attach.sh global",
-    "harness:dev": "pnpm --filter @docx-react-component/react-word-editor-harness dev"
-  },
   "keywords": [
     "docx",
     "word",
@@ -162,9 +136,15 @@
     "y-protocols": "^1.0.0"
   },
   "peerDependenciesMeta": {
-    "yjs": { "optional": true },
-    "y-prosemirror": { "optional": true },
-    "y-protocols": { "optional": true }
+    "yjs": {
+      "optional": true
+    },
+    "y-prosemirror": {
+      "optional": true
+    },
+    "y-protocols": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@chllming/wave-orchestration": "^0.9.15",
@@ -187,14 +167,29 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.30"
   },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild",
-      "sharp"
-    ],
-    "overrides": {
-      "react": "19.2.4",
-      "react-dom": "19.2.4"
-    }
+  "scripts": {
+    "build": "tsup",
+    "test": "bash scripts/run-workspace-tests.sh",
+    "test:repo": "node scripts/run-repo-tests.mjs core",
+    "test:repo:all": "node scripts/run-repo-tests.mjs all",
+    "test:repo:optional": "node scripts/run-repo-tests.mjs optional",
+    "test:repo:browser-ui": "node scripts/run-repo-tests.mjs browser-ui",
+    "test:wcag-audit": "node scripts/run-repo-tests.mjs wcag-audit",
+    "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
+    "lint": "pnpm run lint:no-authored-js && pnpm run lint:docs-contracts && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
+    "lint:docs-contracts": "bash scripts/check-reference-load-contract.sh",
+    "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",
+    "lint:tsgo": "tsgo --noEmit -p tsconfig.build.json",
+    "lint:tsgo:harness": "pnpm --filter @docx-react-component/react-word-editor-harness lint:tsgo",
+    "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
+    "wave:doctor": "bash scripts/context7-export-env.sh run pnpm exec wave doctor --json",
+    "wave:dry-run": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main --dry-run --no-dashboard",
+    "wave:launch": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main",
+    "wave:launch:managed": "bash scripts/wave-launch.sh",
+    "wave:status": "bash scripts/wave-status.sh",
+    "wave:watch": "bash scripts/wave-watch.sh --follow",
+    "wave:dashboard:current": "bash scripts/wave-dashboard-attach.sh current",
+    "wave:dashboard:global": "bash scripts/wave-dashboard-attach.sh global",
+    "harness:dev": "pnpm --filter @docx-react-component/react-word-editor-harness dev"
   }
-}
+}

package/src/api/public-types.ts

@@ -920,7 +920,7 @@ export type ViewMode = "editing" | "review" | "view";
  * Distinct from `ViewMode` (editor posture) and `WorkspaceMode` (shell layout).
  * `DocumentMode` reflects document-level editing authority, not presentation.
  */
-export type DocumentMode = "editing" | "suggesting" | "viewing";
+export type DocumentMode = "editing" | "suggesting" | "viewing" | "commenting";
 
 /**
  * A single permission range parsed from `w:permStart` / `w:permEnd` in the
@@ -1145,6 +1145,7 @@ export interface WorkflowCandidateRange {
 
 export interface WorkflowScope {
   scopeId: string;
+  version?: number;
   mode: WorkflowScopeMode;
   anchor: EditorAnchorProjection;
   storyTarget?: EditorStoryTarget;
@@ -1152,6 +1153,13 @@ export interface WorkflowScope {
   label?: string;
   domain?: "legal" | "commercial" | "finance" | "other";
   metadataRefs?: string[];
+  metadata?: WorkflowScopeMetadataField[];
+}
+
+export interface WorkflowScopeMetadataField {
+  key: string;
+  valueType?: "string" | "number" | "boolean" | "json";
+  value?: string | number | boolean | Record<string, unknown>;
 }
 
 export interface WorkflowWorkItem {

package/src/api/session-state.ts

@@ -2,6 +2,10 @@ import type {
   EditorSessionState,
   PersistedEditorSnapshot,
 } from "./public-types.ts";
+import {
+  assertPersistedEditorSnapshot,
+  validatePersistedEditorSnapshot,
+} from "../model/snapshot.ts";
 
 export const EDITOR_SESSION_STATE_VERSION = "editor-session-state/1" as const;
 
@@ -62,3 +66,23 @@ export function persistedSnapshotFromEditorSessionState(
     workflowMetadata: sessionState.workflowMetadata,
   });
 }
+
+export function validateEditorSessionState(
+  sessionState: EditorSessionState,
+): ReturnType<typeof validatePersistedEditorSnapshot> {
+  return validatePersistedEditorSnapshot(
+    persistedSnapshotFromEditorSessionState(sessionState, {
+      savedAt: sessionState.updatedAt,
+    }),
+  );
+}
+
+export function assertEditorSessionState(
+  sessionState: EditorSessionState,
+): void {
+  assertPersistedEditorSnapshot(
+    persistedSnapshotFromEditorSessionState(sessionState, {
+      savedAt: sessionState.updatedAt,
+    }),
+  );
+}

package/src/core/commands/index.ts

@@ -195,7 +195,7 @@ export interface EditorTransaction {
 
 export interface CommandExecutionContext {
   timestamp: string;
-  documentMode?: "editing" | "suggesting" | "viewing";
+  documentMode?: "editing" | "suggesting" | "viewing" | "commenting";
   defaultAuthorId?: string;
 }
 
@@ -1365,6 +1365,59 @@ function applySuggestingInsert(
       result.mapping,
     );
 
+    // Extend an existing adjacent insertion revision if the cursor is right at its end.
+    // After remapping, a prior insertion revision's `to` stays at `insertedFrom` (assoc.end = -1),
+    // so consecutive keystrokes coalesce into one revision instead of one per character.
+    const existingInsertion = findAdjacentInsertionRevision(
+      reviewState.document.review.revisions,
+      insertedFrom,
+      authorId,
+    );
+
+    if (existingInsertion && existingInsertion.anchor.kind === "range") {
+      const updatedRevision: CanonicalRevisionRecord = {
+        ...existingInsertion,
+        anchor: {
+          kind: "range",
+          range: { from: existingInsertion.anchor.range.from, to: insertedTo },
+          assoc: { start: 1, end: -1 },
+        },
+      };
+
+      const finalDocument: CanonicalDocumentEnvelope = {
+        ...reviewState.document,
+        review: {
+          ...reviewState.document.review,
+          revisions: {
+            ...reviewState.document.review.revisions,
+            [updatedRevision.changeId]: updatedRevision,
+          },
+        },
+      };
+
+      return createTransaction(
+        {
+          ...state,
+          document: finalDocument,
+          selection: result.selection,
+          warnings: reviewState.warnings,
+          runtime: {
+            ...state.runtime,
+            activeCommentId: reviewState.activeCommentId,
+          },
+        },
+        {
+          historyBoundary: "push",
+          markDirty: true,
+          mapping: result.mapping,
+          effects: {
+            ...reviewState.effects,
+            revisionAuthored: { changeId: updatedRevision.changeId, kind: "insertion" },
+          },
+        },
+      );
+    }
+
     // Create the revision with pre-mapping positions — it refers to content
     // that was just inserted, so its anchors are already correct in the new document
     const revision = createAuthoredRevision(
@@ -1850,6 +1903,26 @@ function applySuggestingParagraphSplit(
   );
 }
 
+function findAdjacentInsertionRevision(
+  revisions: Record<string, CanonicalRevisionRecord>,
+  cursorPos: number,
+  authorId: string,
+): CanonicalRevisionRecord | undefined {
+  for (const revision of Object.values(revisions)) {
+    if (
+      revision.kind === "insertion" &&
+      revision.status === "open" &&
+      revision.metadata?.source === "runtime" &&
+      revision.anchor.kind === "range" &&
+      revision.anchor.range.to === cursorPos &&
+      revision.authorId === authorId
+    ) {
+      return revision;
+    }
+  }
+  return undefined;
+}
+
 function findOverlappingAuthoredDeletion(
   revisions: Record<string, CanonicalRevisionRecord>,
   from: number,

package/src/index.ts

@@ -1,8 +1,10 @@
 export { WordReviewEditor } from "./ui/WordReviewEditor.tsx";
 export {
   createEditorSessionState,
+  assertEditorSessionState,
   editorSessionStateFromPersistedSnapshot,
   persistedSnapshotFromEditorSessionState,
+  validateEditorSessionState,
   EDITOR_SESSION_STATE_VERSION,
 } from "./api/session-state.ts";
 export type {

package/src/io/docx-session.ts

@@ -9,6 +9,11 @@ import type {
   PersistedEditorSnapshot,
   ProtectionRange,
   ProtectionSnapshot,
+  WorkflowMetadataSnapshot,
+  WorkflowOverlay,
+  WorkflowScope,
+  WorkflowScopeMetadataField,
+  WorkflowWorkItem,
 } from "../api/public-types.ts";
 import { editorSessionStateFromPersistedSnapshot } from "../api/session-state.ts";
 import type {
@@ -655,6 +660,12 @@ export function loadDocxEditorSession(
         : undefined;
 
     const timestamp = new Date().toISOString();
+    const translatedWorkflowState = translateClmCommentsToWorkflow({
+      comments: normalizedComments.threads,
+      workflowOverlay: embeddedWorkflowOverlay,
+      workflowMetadata: embeddedWorkflowMetadata,
+      timestamp,
+    });
     const document = createImportedCanonicalDocument({
       documentId: options.documentId,
       timestamp,
@@ -703,7 +714,7 @@ export function loadDocxEditorSession(
         errors: [],
       },
       review: {
-        comments: toRuntimeCommentRecords(normalizedComments.threads),
+        comments: toRuntimeCommentRecords(translatedWorkflowState.comments),
         revisions: toRuntimeRevisionRecords([
           ...normalizedRevisions.revisions,
           ...importedStoryRevisions,
@@ -722,8 +733,8 @@ export function loadDocxEditorSession(
       compatibility: toPublicCompatibilityReport(compatibility),
       protectionSnapshot: importedProtectionSnapshot,
       sourcePackage: createPersistedSourcePackage(sourceBytes, options.sourceLabel),
-      workflowOverlay: embeddedWorkflowOverlay,
-      workflowMetadata: embeddedWorkflowMetadata,
+      workflowOverlay: translatedWorkflowState.workflowOverlay,
+      workflowMetadata: translatedWorkflowState.workflowMetadata,
     });
     const snapshotIssues = validatePersistedEditorSnapshot(snapshot);
     if (snapshotIssues.length > 0) {
@@ -1940,6 +1951,252 @@ function normalizeImportedCommentThreads(
   };
 }
 
+function translateClmCommentsToWorkflow(input: {
+  comments: readonly CommentThread[];
+  workflowOverlay?: WorkflowOverlay;
+  workflowMetadata?: WorkflowMetadataSnapshot;
+  timestamp: string;
+}): {
+  comments: CommentThread[];
+  workflowOverlay?: WorkflowOverlay;
+  workflowMetadata?: WorkflowMetadataSnapshot;
+} {
+  const nextComments = input.comments.map((thread) => structuredClone(thread));
+  let nextOverlay = input.workflowOverlay ? structuredClone(input.workflowOverlay) : undefined;
+  let overlayChanged = false;
+
+  for (const [index, thread] of nextComments.entries()) {
+    const directive = parseClmCommentDirective(thread);
+    if (!directive || thread.anchor.kind !== "range") {
+      continue;
+    }
+
+    if (!nextOverlay) {
+      nextOverlay = {
+        overlayVersion: "workflow-overlay/1",
+        scopes: [],
+      };
+    }
+
+    const existingScope = findExistingClmScope(nextOverlay.scopes, directive);
+    if (!existingScope) {
+      const version = getNextClmScopeVersion(nextOverlay.scopes, thread.anchor);
+      const scopeId = `clm-scope-${thread.commentId}-v${version}`;
+      const workItem = directive.tag === "TASK"
+        ? createClmWorkflowWorkItem(thread, directive.description, scopeId)
+        : undefined;
+      const scope = createClmWorkflowScope(thread, directive, version, scopeId, workItem?.workItemId);
+
+      nextOverlay.scopes = [...nextOverlay.scopes, scope];
+      if (workItem) {
+        nextOverlay.workItems = [...(nextOverlay.workItems ?? []), workItem];
+        if (!nextOverlay.activeWorkItemId) {
+          nextOverlay.activeWorkItemId = workItem.workItemId;
+        }
+      }
+      overlayChanged = true;
+    }
+
+    nextComments[index] = resolveImportedCommentThreadOnTranslation(thread, input.timestamp);
+  }
+
+  return {
+    comments: nextComments,
+    workflowOverlay: overlayChanged || input.workflowOverlay ? nextOverlay : undefined,
+    workflowMetadata: input.workflowMetadata,
+  };
+}
+
+function parseClmCommentDirective(
+  thread: CommentThread,
+): { tag: "TASK" | "READ" | "COMMENT" | "EDIT"; description: string; sourceCommentId: string; sourceCommentDurableId?: string; sourceCommentParaId?: string; mode: WorkflowScope["mode"] } | undefined {
+  if (thread.metadata?.rootParaId === undefined && thread.entries[0]?.metadata?.parentParaId) {
+    return undefined;
+  }
+  const firstMeaningfulLine = thread.entries
+    .flatMap((entry) => entry.body.split(/\r?\n/u))
+    .map((line) => line.trim())
+    .find((line) => line.length > 0);
+  if (!firstMeaningfulLine) {
+    return undefined;
+  }
+  const match = /^CLM:([A-Z]+):(.*)$/u.exec(firstMeaningfulLine);
+  if (!match) {
+    return undefined;
+  }
+  const tag = match[1] as "TASK" | "READ" | "COMMENT" | "EDIT";
+  const description = (match[2] ?? "").trim();
+  const mode = getClmWorkflowScopeMode(tag);
+  if (!mode || description.length === 0) {
+    return undefined;
+  }
+  return {
+    tag,
+    description,
+    sourceCommentId: thread.metadata?.rootOoxmlCommentId ?? thread.commentId,
+    sourceCommentDurableId: thread.entries[0]?.metadata?.durableId,
+    sourceCommentParaId: thread.metadata?.rootParaId ?? thread.entries[0]?.metadata?.paraId,
+    mode,
+  };
+}
+
+function getClmWorkflowScopeMode(tag: string): WorkflowScope["mode"] | undefined {
+  switch (tag) {
+    case "TASK":
+      return "suggest";
+    case "READ":
+      return "view";
+    case "COMMENT":
+      return "comment";
+    case "EDIT":
+      return "edit";
+    default:
+      return undefined;
+  }
+}
+
+function createClmWorkflowWorkItem(
+  thread: CommentThread,
+  description: string,
+  scopeId: string,
+): WorkflowWorkItem {
+  return {
+    workItemId: `clm-task-${thread.commentId}`,
+    title: description,
+    description,
+    status: "pending",
+    scopeIds: [scopeId],
+  };
+}
+
+function createClmWorkflowScope(
+  thread: CommentThread,
+  directive: NonNullable<ReturnType<typeof parseClmCommentDirective>>,
+  version: number,
+  scopeId: string,
+  workItemId?: string,
+): WorkflowScope {
+  if (workItemId) {
+    return {
+      scopeId,
+      version,
+      mode: directive.mode,
+      anchor: toPublicAnchorProjection(thread.anchor),
+      storyTarget: { kind: "main" },
+      workItemId,
+      label: directive.description,
+      metadata: createClmScopeMetadata(directive),
+    };
+  }
+  return {
+    scopeId,
+    version,
+    mode: directive.mode,
+    anchor: toPublicAnchorProjection(thread.anchor),
+    storyTarget: { kind: "main" },
+    label: directive.description,
+    metadata: createClmScopeMetadata(directive),
+  };
+}
+
+function createClmScopeMetadata(
+  directive: NonNullable<ReturnType<typeof parseClmCommentDirective>>,
+): WorkflowScopeMetadataField[] {
+  return [
+    {
+      key: "workblock.clm.tag",
+      valueType: "string",
+      value: directive.tag,
+    },
+    {
+      key: "workblock.clm.description",
+      valueType: "string",
+      value: directive.description,
+    },
+    {
+      key: "workblock.sourceCommentId",
+      valueType: "string",
+      value: directive.sourceCommentId,
+    },
+    ...(directive.sourceCommentDurableId
+      ? [{
+          key: "workblock.sourceCommentDurableId",
+          valueType: "string" as const,
+          value: directive.sourceCommentDurableId,
+        }]
+      : []),
+    ...(directive.sourceCommentParaId
+      ? [{
+          key: "workblock.sourceCommentParaId",
+          valueType: "string" as const,
+          value: directive.sourceCommentParaId,
+        }]
+      : []),
+  ];
+}
+
+function findExistingClmScope(
+  scopes: readonly WorkflowScope[],
+  directive: NonNullable<ReturnType<typeof parseClmCommentDirective>>,
+): WorkflowScope | undefined {
+  return scopes.find((scope) => {
+    const sourceCommentId = getWorkflowScopeMetadataValue(scope.metadata, "workblock.sourceCommentId");
+    const sourceCommentDurableId = getWorkflowScopeMetadataValue(
+      scope.metadata,
+      "workblock.sourceCommentDurableId",
+    );
+    return (
+      sourceCommentId === directive.sourceCommentId ||
+      (directive.sourceCommentDurableId !== undefined &&
+        sourceCommentDurableId === directive.sourceCommentDurableId)
+    );
+  });
+}
+
+function getWorkflowScopeMetadataValue(
+  metadata: WorkflowScope["metadata"] | undefined,
+  key: string,
+): string | undefined {
+  const field = metadata?.find((entry) => entry.key === key);
+  return typeof field?.value === "string" ? field.value : undefined;
+}
+
+function getNextClmScopeVersion(
+  scopes: readonly WorkflowScope[],
+  anchor: Extract<CommentThread["anchor"], { kind: "range" }>,
+): number {
+  const anchorRange = {
+    from: anchor.range.from,
+    to: anchor.range.to,
+  };
+  const overlappingVersions = scopes.flatMap((scope) => {
+    if (scope.anchor.kind !== "range") {
+      return [];
+    }
+    return rangesIntersect(scope.anchor, anchorRange) && typeof scope.version === "number"
+      ? [scope.version]
+      : [];
+  });
+  return overlappingVersions.length > 0 ? Math.max(...overlappingVersions) + 1 : 1;
+}
+
+function resolveImportedCommentThreadOnTranslation(
+  thread: CommentThread,
+  timestamp: string,
+): CommentThread {
+  if (thread.status === "resolved") {
+    return thread;
+  }
+  return {
+    ...thread,
+    status: thread.status === "detached" ? "detached" : "resolved",
+    resolution: thread.resolution ?? {
+      resolvedAt: timestamp,
+      resolvedBy: thread.entries[thread.entries.length - 1]?.authorId ?? thread.createdBy,
+    },
+  };
+}
+
 function resolveDefinitionRootCommentId(
   definition: ImportedCommentDefinition,
   definitions: readonly ImportedCommentDefinition[],

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

@@ -371,19 +371,46 @@ function buildWorkblockExtensionXml(workflowOverlay: WorkflowOverlay | undefined
 }
 
 function buildWorkflowScopeXml(scope: WorkflowScope): string {
+  const scopeMetadataXml = buildWorkflowScopeMetadataXml(scope.metadata);
   return [
     `<bw:scope`,
     ` id="${escapeXml(scope.scopeId)}"`,
+    typeof scope.version === "number" ? ` version="${String(scope.version)}"` : "",
     ` mode="${escapeXml(scope.mode)}"`,
     scope.workItemId ? ` workItemRef="${escapeXml(scope.workItemId)}"` : "",
     scope.label ? ` label="${escapeXml(scope.label)}"` : "",
     scope.domain ? ` domain="${escapeXml(scope.domain)}"` : "",
     `>`,
     indentLines(buildWorkflowAnchorXml(scope.anchor, scope.storyTarget), 2),
+    scopeMetadataXml ? indentLines(scopeMetadataXml, 2) : "",
     `</bw:scope>`,
   ].join("");
 }
 
+function buildWorkflowScopeMetadataXml(scopeMetadata: WorkflowScope["metadata"]): string {
+  if (!scopeMetadata || scopeMetadata.length === 0) {
+    return "";
+  }
+  return [
+    `<bw:scopeMetadata>`,
+    indentLines(
+      scopeMetadata
+        .map((field) => {
+          const serialized = serializeWorkflowScopeMetadataValue(field.valueType, field.value);
+          return [
+            `<bw:field`,
+            ` key="${escapeXml(field.key)}"`,
+            serialized.valueType ? ` type="${escapeXml(serialized.valueType)}"` : "",
+            `>${escapeXml(serialized.text)}</bw:field>`,
+          ].join("");
+        })
+        .join("\n"),
+      2,
+    ),
+    `</bw:scopeMetadata>`,
+  ].join("\n");
+}
+
 function buildWorkflowAnchorXml(
   anchor: EditorAnchorProjection,
   storyTarget: WorkflowScope["storyTarget"],
@@ -563,15 +590,110 @@ function parseWorkflowScope(attributesSource: string, body: string): WorkflowSco
     : createDefaultRangeAnchor(0, 0);
   return {
     scopeId: attributes.id,
+    version: attributes.version !== undefined ? Number(attributes.version) : undefined,
     mode: attributes.mode as WorkflowScope["mode"],
     anchor,
     storyTarget: anchorMatch ? parseOverlayStoryTarget(parseAttributes(anchorMatch[1] ?? "")) : { kind: "main" },
     workItemId: attributes.workItemRef,
     label: attributes.label,
     domain: attributes.domain as WorkflowScope["domain"],
+    metadata: parseWorkflowScopeMetadata(body),
+  };
+}
+
+function parseWorkflowScopeMetadata(body: string): WorkflowScope["metadata"] | undefined {
+  const metadataMatch = body.match(/<bw:scopeMetadata\b[^>]*>([\s\S]*?)<\/bw:scopeMetadata>/u);
+  if (!metadataMatch) {
+    return undefined;
+  }
+  const fields = [...(metadataMatch[1] ?? "").matchAll(/<bw:field\b([^>]*)>([\s\S]*?)<\/bw:field>/gu)]
+    .map((match) => parseWorkflowScopeMetadataField(match[1] ?? "", match[2] ?? ""))
+    .filter((field): field is NonNullable<WorkflowScope["metadata"]>[number] => field !== null);
+  return fields.length > 0 ? fields : undefined;
+}
+
+function parseWorkflowScopeMetadataField(
+  attributesSource: string,
+  body: string,
+): NonNullable<WorkflowScope["metadata"]>[number] | null {
+  const attributes = parseAttributes(attributesSource);
+  if (!attributes.key) {
+    return null;
+  }
+  const valueType = attributes.type as NonNullable<WorkflowScope["metadata"]>[number]["valueType"] | undefined;
+  return {
+    key: attributes.key,
+    ...(valueType ? { valueType } : {}),
+    value: parseWorkflowScopeMetadataValue(valueType, body),
+  };
+}
+
+function serializeWorkflowScopeMetadataValue(
+  valueType: NonNullable<WorkflowScope["metadata"]>[number]["valueType"],
+  value: NonNullable<WorkflowScope["metadata"]>[number]["value"],
+): { valueType?: "string" | "number" | "boolean" | "json"; text: string } {
+  const resolvedValueType =
+    valueType ??
+    (typeof value === "number"
+      ? "number"
+      : typeof value === "boolean"
+        ? "boolean"
+        : typeof value === "string"
+          ? "string"
+          : value && typeof value === "object"
+            ? "json"
+            : undefined);
+
+  if (resolvedValueType === "json") {
+    return {
+      valueType: "json",
+      text: JSON.stringify(value ?? {}),
+    };
+  }
+  if (resolvedValueType === "number") {
+    return {
+      valueType: "number",
+      text: typeof value === "number" ? String(value) : "0",
+    };
+  }
+  if (resolvedValueType === "boolean") {
+    return {
+      valueType: "boolean",
+      text: String(value === true),
+    };
+  }
+  return {
+    valueType: resolvedValueType,
+    text: typeof value === "string" ? value : value === undefined ? "" : String(value),
   };
 }
 
+function parseWorkflowScopeMetadataValue(
+  valueType: NonNullable<WorkflowScope["metadata"]>[number]["valueType"],
+  payloadText: string,
+): NonNullable<WorkflowScope["metadata"]>[number]["value"] {
+  const decodedText = decodeXmlEntities(payloadText);
+  if (valueType === "json") {
+    try {
+      const parsed = JSON.parse(decodedText) as unknown;
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed as Record<string, unknown>;
+      }
+      return { value: parsed };
+    } catch {
+      return { value: decodedText };
+    }
+  }
+  if (valueType === "number") {
+    const numericValue = Number(decodedText);
+    return Number.isFinite(numericValue) ? numericValue : 0;
+  }
+  if (valueType === "boolean") {
+    return decodedText === "true" || decodedText === "1";
+  }
+  return decodedText;
+}
+
 function parseWorkflowWorkItem(attributesSource: string, body: string): WorkflowWorkItem | null {
   const attributes = parseAttributes(attributesSource);
   if (!attributes.id || !attributes.title) {

package/src/model/snapshot.ts

@@ -124,12 +124,20 @@ export interface PersistedWorkflowMetadataSnapshot {
 
 export interface PersistedWorkflowScope {
   scopeId: string;
+  version?: number;
   mode: "edit" | "suggest" | "comment" | "view";
   anchor: Record<string, unknown>;
   storyTarget?: Record<string, unknown>;
   workItemId?: string;
   label?: string;
   domain?: "legal" | "commercial" | "finance" | "other";
+  metadata?: PersistedWorkflowScopeMetadataField[];
+}
+
+export interface PersistedWorkflowScopeMetadataField {
+  key: string;
+  valueType?: "string" | "number" | "boolean" | "json";
+  value?: string | number | boolean | Record<string, unknown>;
 }
 
 export interface PersistedWorkflowWorkItem {
@@ -726,12 +734,62 @@ function validateWorkflowScope(
     issues.push({ path: `${path}.mode`, message: "mode must be edit, suggest, comment, or view." });
   }
   asPlainObject(record.anchor, `${path}.anchor`, issues);
+  if (record.version !== undefined && !Number.isInteger(record.version)) {
+    issues.push({ path: `${path}.version`, message: "version must be an integer." });
+  }
   if (record.workItemId !== undefined) {
     expectString(record.workItemId, `${path}.workItemId`, issues);
   }
   if (record.label !== undefined) {
     expectString(record.label, `${path}.label`, issues);
   }
+  if (record.metadata !== undefined) {
+    if (!Array.isArray(record.metadata)) {
+      issues.push({ path: `${path}.metadata`, message: "metadata must be an array." });
+    } else {
+      record.metadata.forEach((field, index) =>
+        validateWorkflowScopeMetadataField(field, `${path}.metadata[${index}]`, issues),
+      );
+    }
+  }
+}
+
+function validateWorkflowScopeMetadataField(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+  expectString(record.key, `${path}.key`, issues);
+  if (
+    record.valueType !== undefined &&
+    record.valueType !== "string" &&
+    record.valueType !== "number" &&
+    record.valueType !== "boolean" &&
+    record.valueType !== "json"
+  ) {
+    issues.push({
+      path: `${path}.valueType`,
+      message: "valueType must be string, number, boolean, or json.",
+    });
+  }
+  if (
+    record.value !== undefined &&
+    typeof record.value !== "string" &&
+    typeof record.value !== "number" &&
+    typeof record.value !== "boolean"
+  ) {
+    const nestedRecord = asPlainObject(record.value, `${path}.value`, issues);
+    if (!nestedRecord) {
+      issues.push({
+        path: `${path}.value`,
+        message: "value must be a string, number, boolean, or plain object.",
+      });
+    }
+  }
 }
 
 function validateWorkflowWorkItem(

package/src/runtime/document-runtime.ts

@@ -738,7 +738,7 @@ export function createDocumentRuntime(
       });
     }
 
-    if (viewState.documentMode === "viewing") {
+    if (viewState.documentMode === "viewing" || viewState.documentMode === "commenting") {
       reasons.push({
         code: "document_viewing_mode",
         message: "Document is in viewing mode.",
@@ -822,8 +822,8 @@ export function createDocumentRuntime(
   function getEffectiveDocumentMode(
     selection: EditorState["selection"],
   ): DocumentMode {
-    if (viewState.documentMode === "viewing") {
-      return "viewing";
+    if (viewState.documentMode === "viewing" || viewState.documentMode === "commenting") {
+      return viewState.documentMode;
     }
     const matchingScope = getMatchingWorkflowScope(selection);
     if (matchingScope?.mode === "suggest") {
@@ -1529,13 +1529,13 @@ export function createDocumentRuntime(
       }
 
       if (command.type === "history.undo") {
-        if (viewState.documentMode === "viewing") return;
+        if (viewState.documentMode === "viewing" || viewState.documentMode === "commenting") return;
         applyHistory("undo");
         return;
       }
 
       if (command.type === "history.redo") {
-        if (viewState.documentMode === "viewing") return;
+        if (viewState.documentMode === "viewing" || viewState.documentMode === "commenting") return;
         applyHistory("redo");
         return;
       }
@@ -3949,10 +3949,11 @@ function resolveSupportedFieldDisplay(
   if (!field.fieldFamily || !isSupportedFieldFamily(field.fieldFamily)) {
     return undefined;
   }
+  if (field.fieldFamily === "TOC") {
+    return undefined;
+  }
   if (!field.fieldTarget) {
-    return field.fieldFamily === "TOC"
-      ? undefined
-      : { displayText: "", refreshStatus: "unresolvable" };
+    return { displayText: "", refreshStatus: "unresolvable" };
   }
   if (field.fieldFamily === "REF") {
     const result = resolveRefFieldText(document, bookmarkMap, field.fieldTarget);

package/src/runtime/session-capabilities.ts

@@ -23,7 +23,7 @@ export interface SessionCapabilities {
 
   // ── Document mode ──
   /** Runtime document mode — editing authority, distinct from view/workspace mode. */
-  documentMode: "editing" | "suggesting" | "viewing";
+  documentMode: "editing" | "suggesting" | "viewing" | "commenting";
 
   // ── Command capabilities ──
   canUndo: boolean;
@@ -101,12 +101,15 @@ export function deriveCapabilities(
       ? "read-only-diagnostics"
       : reviewMode;
 
-  // Command capabilities — document mode "viewing" disables editing
-  const canEdit = isReady && !isReadOnly && !hasFatalError && documentMode !== "viewing";
+  // Command capabilities — "viewing" and "commenting" modes both disable editing;
+  // "commenting" additionally keeps comment creation enabled.
+  const canEdit = isReady && !isReadOnly && !hasFatalError
+    && documentMode !== "viewing" && documentMode !== "commenting";
   const canUndo = snapshot.commandState.canUndo && canEdit;
   const canRedo = snapshot.commandState.canRedo && canEdit;
+  const canComment = isReady && !hasFatalError && documentMode !== "viewing";
   const canAddComment =
-    canEdit &&
+    canComment &&
     activeStory.kind === "main" &&
     !snapshot.selection.isCollapsed &&
     Boolean(snapshot.surface) &&

package/src/runtime/surface-projection.ts

@@ -1427,6 +1427,14 @@ function describePreservedInlinePreview(
     };
   }
 
+  if (/\b(?:w:)?br\b[^>]*\b(?:w:)?type="page"/u.test(payloadReference)) {
+    return {
+      label: "Page break",
+      detail: "Word page-break marker preserved for export safety.",
+      presentation: "quiet-marker",
+    };
+  }
+
   if (/\b(?:w:)?permStart\b/u.test(payloadReference)) {
     const editorGroup = /\bw:edGrp="([^"]+)"/u.exec(payloadReference)?.[1];
     return {

package/src/ui-tailwind/editor-surface/pm-decorations.ts

@@ -309,11 +309,11 @@ export function buildDecorations(
       // This is the critical behavior: "hide tracked changes" must show
       // the document as if accepted, not show deleted text as kept text.
       if (markupDisplay === "clean" && rev.kind === "deletion") {
-        const pmFrom = positionMap.runtimeToPm(rev.from);
-        const pmTo = positionMap.runtimeToPm(rev.to);
-        if (pmFrom < pmTo) {
+        const cleanPmFrom = positionMap.runtimeToPm(rev.from);
+        const cleanPmTo = positionMap.runtimeToPm(rev.to);
+        if (cleanPmFrom < cleanPmTo) {
           decorations.push(
-            Decoration.inline(pmFrom, pmTo, {
+            Decoration.inline(cleanPmFrom, cleanPmTo, {
               class: "hidden",
               "data-revision-id": rev.revisionId,
             }),
@@ -322,13 +322,11 @@ export function buildDecorations(
         continue;
       }
 
-      // Skip visual styling when tracked changes display is off
-      if (!showTrackedChanges) continue;
-
       const pmFrom = positionMap.runtimeToPm(rev.from);
       const pmTo = positionMap.runtimeToPm(rev.to);
       if (pmFrom >= pmTo) continue;
 
+      // Suggestions styling is always shown regardless of showTrackedChanges toggle.
       if (suggestionsEnabled) {
         if (rev.kind === "insertion") {
           decorations.push(
@@ -366,6 +364,9 @@ export function buildDecorations(
         continue;
       }
 
+      // Skip normal markup styling when tracked changes display is off
+      if (!showTrackedChanges) continue;
+
       const cls = getRevisionHighlightClass(
         revisionModel,
         rev.from,

package/src/ui-tailwind/editor-surface/surface-build-keys.ts

@@ -37,6 +37,7 @@ export function createSurfaceDocumentBuildKey(input: {
 export function createSurfaceDecorationKey(input: {
   markupDisplay: string;
   showTrackedChanges: boolean;
+  suggestionsEnabled?: boolean;
   canEdit: boolean;
   activeCommentId?: string;
   activeRevisionId?: string;
@@ -51,6 +52,7 @@ export function createSurfaceDecorationKey(input: {
   return JSON.stringify({
     markupDisplay: input.markupDisplay,
     showTrackedChanges: input.showTrackedChanges,
+    suggestionsEnabled: input.suggestionsEnabled ?? false,
     canEdit: input.canEdit,
     activeCommentId: input.activeCommentId ?? null,
     activeRevisionId: input.activeRevisionId ?? null,

package/src/ui-tailwind/editor-surface/tw-prosemirror-surface.tsx

@@ -223,6 +223,7 @@ export const TwProseMirrorSurface = forwardRef<
       createSurfaceDecorationKey({
         markupDisplay,
         showTrackedChanges,
+        suggestionsEnabled,
         canEdit,
         activeCommentId: snapshot.comments.activeCommentId,
         activeRevisionId: props.activeRevisionId,
@@ -246,6 +247,7 @@ export const TwProseMirrorSurface = forwardRef<
       props.activeWorkflowScopeIds,
       props.workflowScopes,
       showTrackedChanges,
+      suggestionsEnabled,
       snapshot.comments.activeCommentId,
     ],
   );