@beyondwork/docx-react-component 1.0.20 → 1.0.21

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.20",
+  "version": "1.0.21",
   "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"
@@ -73,6 +74,14 @@
       "types": "./src/core/commands/table-structure-commands.ts",
       "import": "./src/core/commands/table-structure-commands.ts"
     },
+    "./core/commands/style-commands": {
+      "types": "./src/core/commands/style-commands.ts",
+      "import": "./src/core/commands/style-commands.ts"
+    },
+    "./core/commands/section-layout-commands": {
+      "types": "./src/core/commands/section-layout-commands.ts",
+      "import": "./src/core/commands/section-layout-commands.ts"
+    },
     "./core/state/editor-state": {
       "types": "./src/core/state/editor-state.ts",
       "import": "./src/core/state/editor-state.ts"
@@ -80,6 +89,30 @@
     "./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: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",
@@ -142,28 +175,14 @@
     "tsup": "^8.3.0",
     "tsx": "^4.21.0"
   },
-  "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: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"
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "sharp"
+    ],
+    "overrides": {
+      "react": "19.2.4",
+      "react-dom": "19.2.4"
+    }
   }
-}
+}

package/src/io/docx-session.ts

@@ -726,7 +726,7 @@ function exportDocxEditorSession(
       state.initialCanonicalSignature;
   const canReuse = canReuseSourceBytesForCurrentDocument(state, currentDocument);
   const commentCount = Object.keys(currentDocument.review?.comments ?? {}).length;
-  console.error(`[DEBUG-EXPORT] docId=${sessionState.documentId} signatureMatch=${signatureMatch} canReuse=${canReuse} preservedDefs=${state.preservedCommentDefinitions.length} blockingDiags=${state.blockingCommentDiagnostics.length} comments=${commentCount}`);
+
   if (signatureMatch && canReuse) {
     return {
       bytes: new Uint8Array(state.sourceBytes),

package/src/runtime/document-runtime.ts

@@ -2442,12 +2442,12 @@ function collectFieldsFromSubParts(
     return index;
   }
   let nextIndex = index;
-  for (const header of subParts.headers) {
+  for (const header of subParts.headers ?? []) {
     for (const block of header.blocks) {
       nextIndex = collectFieldsFromBlock(block, entries, nextIndex);
     }
   }
-  for (const footer of subParts.footers) {
+  for (const footer of subParts.footers ?? []) {
     for (const block of footer.blocks) {
       nextIndex = collectFieldsFromBlock(block, entries, nextIndex);
     }

package/src/ui/WordReviewEditor.tsx

@@ -45,6 +45,7 @@ import type {
   UpdateFieldsResult,
   ViewMode as EditorViewMode,
   WorkflowBlockedCommandReason,
+  WorkflowMarkupSnapshot,
   WorkflowScopeSnapshot,
   WordReviewEditorEvent,
   WordReviewEditorProps,
@@ -151,6 +152,7 @@ import type {
   SelectionToolbarModel,
 } from "./headless/selection-toolbar-model";
 import { type EditorCommandBag, useCommandBag } from "./editor-command-bag.ts";
+import { deriveVisibleWorkflowBlockedRails } from "./workflow-surface-blocked-rails.ts";
 import {
   type WordReviewEditorRuntime,
   persistAndExport as persistAndExportFromBoundary,
@@ -645,6 +647,14 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       { blockedReasons: [] } satisfies InteractionGuardSnapshot,
       interactionGuardSnapshotsEqual,
     );
+    const workflowMarkupSnapshot = useMemo(
+      () => (runtime ? runtime.getWorkflowMarkupSnapshot() : null),
+      [runtime, snapshot.revisionToken],
+    );
+    const workflowBlockedRails = useMemo(
+      () => deriveVisibleWorkflowBlockedRails(snapshot.surface, workflowMarkupSnapshot),
+      [snapshot.surface, workflowMarkupSnapshot],
+    );
     const sessionState = useMemo(
       () => (runtime ? runtime.getSessionState() : loadingSessionState),
       [loadingSessionState, runtime, snapshot.revisionToken],
@@ -1611,6 +1621,8 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         mediaPreviews={mediaPreviews}
         isPageWorkspace={isPageWorkspace}
         workflowScopes={workflowScopeSnapshot?.scopes}
+        workflowCandidates={workflowScopeSnapshot?.candidates}
+        workflowBlockedReasons={workflowBlockedRails}
         onSelectionToolbarAnchorChange={handleSelectionToolbarAnchorChange}
         {...editorCallbacks}
         onCommentActivated={(commentId) => {
@@ -1904,6 +1916,13 @@ function applyRuntimeInsertSectionBreak(
   if (!canApplyRuntimeMutation(snapshot) || snapshot.activeStory.kind !== "main") {
     return;
   }
+  if (snapshot.documentMode === "suggesting") {
+    runtime.emitBlockedCommand("insertSectionBreak", [{
+      code: "unsupported_surface",
+      message: "Section break insertion is not supported in suggesting mode.",
+    }]);
+    return;
+  }
 
   const sessionState = runtime.getSessionState();
   const timestamp = new Date().toISOString();
@@ -2075,6 +2094,14 @@ function applyRuntimeSetHeaderFooterLink(
 }
 
 function applyRuntimeInsertPageBreak(runtime: WordReviewEditorRuntime): void {
+  const snapshot = runtime.getRenderSnapshot();
+  if (snapshot.documentMode === "suggesting") {
+    runtime.emitBlockedCommand("insertPageBreak", [{
+      code: "unsupported_surface",
+      message: "Page break insertion is not supported in suggesting mode.",
+    }]);
+    return;
+  }
   const context = getStoryMutationContext(runtime);
   if (!context) {
     return;
@@ -2092,6 +2119,14 @@ function applyRuntimeInsertTable(
   runtime: WordReviewEditorRuntime,
   options: InsertTableOptions,
 ): void {
+  const snapshot = runtime.getRenderSnapshot();
+  if (snapshot.documentMode === "suggesting") {
+    runtime.emitBlockedCommand("insertTable", [{
+      code: "unsupported_surface",
+      message: "Table insertion is not supported in suggesting mode.",
+    }]);
+    return;
+  }
   const context = getStoryMutationContext(runtime);
   if (!context) {
     return;
@@ -2110,6 +2145,14 @@ function applyRuntimeInsertImage(
   runtime: WordReviewEditorRuntime,
   options: InsertImageOptions,
 ): void {
+  const snapshot = runtime.getRenderSnapshot();
+  if (snapshot.documentMode === "suggesting") {
+    runtime.emitBlockedCommand("insertImage", [{
+      code: "unsupported_surface",
+      message: "Image insertion is not supported in suggesting mode.",
+    }]);
+    return;
+  }
   const context = getStoryMutationContext(runtime);
   if (!context) {
     return;
@@ -2148,6 +2191,13 @@ function applyRuntimeImageResize(
   if (!canApplyRuntimeMutation(snapshot)) {
     return;
   }
+  if (snapshot.documentMode === "suggesting") {
+    runtime.emitBlockedCommand("setImageLayout", [{
+      code: "unsupported_surface",
+      message: "Image resize is not supported in suggesting mode.",
+    }]);
+    return;
+  }
 
   try {
     const sessionState = runtime.getSessionState();
@@ -2172,6 +2222,14 @@ function applyRuntimeImageReposition(
   mediaId: string,
   offsets: { horizontalOffsetEmu?: number; verticalOffsetEmu?: number },
 ): void {
+  const snapshot = runtime.getRenderSnapshot();
+  if (snapshot.documentMode === "suggesting") {
+    runtime.emitBlockedCommand("setImageFrame", [{
+      code: "unsupported_surface",
+      message: "Image reposition is not supported in suggesting mode.",
+    }]);
+    return;
+  }
   const context = getStoryMutationContext(runtime);
   if (!context) {
     return;
@@ -2217,6 +2275,14 @@ function applyRuntimeTableStructureOperation(
     | { type: "split-cell" }
     | { type: "set-cell-background"; color: string },
 ): void {
+  const snapshot = runtime.getRenderSnapshot();
+  if (snapshot.documentMode === "suggesting") {
+    runtime.emitBlockedCommand(`table.${operation.type}`, [{
+      code: "unsupported_surface",
+      message: `Table operation "${operation.type}" is not supported in suggesting mode.`,
+    }]);
+    return;
+  }
   const context = getStoryMutationContext(runtime);
   if (!context) {
     return;

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

@@ -73,12 +73,17 @@ export interface CreateRuntimeArgs {
 interface RuntimeLifecycleHandlers {
   onWarning?: (warning: EditorWarning) => void;
   onError?: (error: EditorError) => void;
+  onEvent?: (event: WordReviewEditorEvent) => void;
 }
 
 export interface WordReviewEditorRuntime extends DocumentRuntime {
   getFatalError?(): EditorError | undefined;
   dispose?(): void;
   setDefaultAuthorId?(authorId?: string): void;
+  emitBlockedCommand(
+    command: string,
+    reasons: Extract<WordReviewEditorEvent, { type: "command_blocked" }>["reasons"],
+  ): void;
 }
 
 type PackageBackedDocxSession = ReturnType<typeof loadDocxEditorSession>;
@@ -357,6 +362,7 @@ export function useEditorRuntimeBoundary(
           {
             onWarning: onWarningRef.current,
             onError: onErrorRef.current,
+            onEvent: onEventRef.current,
           },
         );
         recordPerfSample("runtime.create");
@@ -538,7 +544,7 @@ function createRuntime(
     ? applySessionExportBarrier(initialSessionState, snapshotExportResolution.barrier)
     : initialSessionState;
 
-  return createDocumentRuntime({
+  const runtime: WordReviewEditorRuntime = Object.assign(createDocumentRuntime({
     documentId: args.documentId,
     initialSessionState: runtimeSessionState,
     sourceKind: args.source.source,
@@ -569,7 +575,26 @@ function createRuntime(
     onWarning: handlers.onWarning,
     onError: handlers.onError,
     defaultAuthorId: args.currentUserId,
+  }), {
+    emitBlockedCommand: (
+      command: string,
+      reasons: Extract<WordReviewEditorEvent, { type: "command_blocked" }>["reasons"],
+    ) => {
+      emitEditorEvent({
+        hostAdapter: args.hostAdapter,
+        datastore: args.datastore,
+        onEvent: handlers.onEvent,
+        event: {
+          type: "command_blocked",
+          documentId: args.documentId,
+          command,
+          reasons,
+        },
+      });
+    },
   });
+
+  return runtime;
 }
 
 function createLoadingSnapshot(
@@ -691,6 +716,7 @@ function createLoadingRuntimeBridge(input: {
   return {
     subscribe: () => () => undefined,
     subscribeToEvents: () => () => undefined,
+    emitBlockedCommand: () => undefined,
     getRenderSnapshot: () => input.snapshot,
     replaceText: () => undefined,
     dispatch: () => undefined,

package/src/ui/editor-surface-controller.tsx

@@ -5,6 +5,8 @@ import type {
   EditorUser,
   RuntimeRenderSnapshot,
   SelectionSnapshot,
+  WorkflowBlockedCommandReason,
+  WorkflowCandidateRange,
   WorkflowScope,
 } from "../api/public-types.ts";
 import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
@@ -41,6 +43,8 @@ export interface EditorSurfaceControllerProps {
   onCommentActivated?: (commentId: string) => void;
   onRevisionActivated?: (revisionId: string) => void;
   workflowScopes?: readonly WorkflowScope[];
+  workflowCandidates?: readonly WorkflowCandidateRange[];
+  workflowBlockedReasons?: readonly WorkflowBlockedCommandReason[];
 }
 
 export const EditorSurfaceController = forwardRef<

package/src/ui/workflow-surface-blocked-rails.ts

@@ -0,0 +1,94 @@
+import type {
+  EditorStoryTarget,
+  RuntimeRenderSnapshot,
+  SurfaceBlockSnapshot,
+  WorkflowBlockedCommandReason,
+  WorkflowMarkupSnapshot,
+} from "../api/public-types";
+
+export function deriveVisibleWorkflowBlockedRails(
+  surface: RuntimeRenderSnapshot["surface"] | undefined,
+  markupSnapshot: WorkflowMarkupSnapshot | null,
+): WorkflowBlockedCommandReason[] {
+  if (!surface || !markupSnapshot) {
+    return [];
+  }
+
+  const visibleFragments = collectVisibleOpaqueFragmentStoryKeys(surface);
+  return markupSnapshot.opaqueFragments
+    .filter((fragment) =>
+      visibleFragments.has(
+        createOpaqueFragmentStoryKey(fragment.fragmentId, fragment.storyTarget ?? { kind: "main" }),
+      ),
+    )
+    .map((fragment) => ({
+      code: fragment.blockedReasonCode,
+      message: fragment.detail,
+      anchor: fragment.anchor,
+      storyTarget: fragment.storyTarget,
+    }));
+}
+
+function collectVisibleOpaqueFragmentStoryKeys(
+  surface: NonNullable<RuntimeRenderSnapshot["surface"]>,
+): Set<string> {
+  const keys = new Set<string>();
+  collectVisibleOpaqueFragmentStoryKeysInBlocks(surface.blocks, { kind: "main" }, keys);
+  for (const story of surface.secondaryStories) {
+    collectVisibleOpaqueFragmentStoryKeysInBlocks(story.blocks, story.target, keys);
+  }
+  return keys;
+}
+
+function collectVisibleOpaqueFragmentStoryKeysInBlocks(
+  blocks: readonly SurfaceBlockSnapshot[],
+  storyTarget: EditorStoryTarget,
+  keys: Set<string>,
+): void {
+  for (const block of blocks) {
+    if (block.kind === "paragraph") {
+      for (const segment of block.segments) {
+        if (segment.kind === "opaque_inline") {
+          keys.add(createOpaqueFragmentStoryKey(segment.fragmentId, storyTarget));
+        }
+      }
+      continue;
+    }
+
+    if (block.kind === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          collectVisibleOpaqueFragmentStoryKeysInBlocks(cell.content, storyTarget, keys);
+        }
+      }
+      continue;
+    }
+
+    if (block.kind === "sdt_block") {
+      collectVisibleOpaqueFragmentStoryKeysInBlocks(block.children, storyTarget, keys);
+      continue;
+    }
+
+    keys.add(createOpaqueFragmentStoryKey(block.fragmentId, storyTarget));
+  }
+}
+
+function createOpaqueFragmentStoryKey(
+  fragmentId: string,
+  storyTarget: EditorStoryTarget,
+): string {
+  return `${fragmentId}:${serializeStoryTargetKey(storyTarget)}`;
+}
+
+function serializeStoryTargetKey(storyTarget: EditorStoryTarget): string {
+  switch (storyTarget.kind) {
+    case "main":
+      return "main";
+    case "header":
+    case "footer":
+      return `${storyTarget.kind}:${storyTarget.relationshipId}:${storyTarget.variant}:${storyTarget.sectionIndex ?? "none"}`;
+    case "footnote":
+    case "endnote":
+      return `${storyTarget.kind}:${storyTarget.noteId}`;
+  }
+}

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

@@ -4,11 +4,156 @@ import type { CommentDecorationModel } from "../../ui/headless/comment-decoratio
 import { getCommentHighlightClass, type MarkupDisplay } from "../../ui/headless/comment-decoration-model";
 import type { RevisionDecorationModel } from "../../ui/headless/revision-decoration-model";
 import { getRevisionHighlightClass } from "../../ui/headless/revision-decoration-model";
-import type { EditorStoryTarget, WorkflowScope } from "../../api/public-types";
+import type {
+  EditorAnchorProjection,
+  EditorStoryTarget,
+  WorkflowBlockedCommandReason,
+  WorkflowCandidateRange,
+  WorkflowScope,
+} from "../../api/public-types";
 import { MAIN_STORY_TARGET, storyTargetsEqual } from "../../core/selection/mapping.ts";
 import type { PositionMap } from "./pm-position-map";
 import type { Node as PMNode } from "prosemirror-model";
 
+type RailDecorationSpec = {
+  railKind: "scope" | "candidate" | "blocked";
+  className: string;
+  attrs: Record<string, string>;
+};
+
+function getWorkflowInlineClass(scope: WorkflowScope): string {
+  if (scope.mode === "edit") return "wre-workflow-inline wre-workflow-inline-edit";
+  if (scope.mode === "suggest") return "wre-workflow-inline wre-workflow-inline-suggest";
+  if (scope.mode === "comment") return "wre-workflow-inline wre-workflow-inline-comment";
+  return "wre-workflow-inline wre-workflow-inline-view";
+}
+
+function getWorkflowRailClass(scope: WorkflowScope): string {
+  if (scope.mode === "edit") return "wre-workflow-rail wre-workflow-rail-edit";
+  if (scope.mode === "suggest") return "wre-workflow-rail wre-workflow-rail-suggest";
+  if (scope.mode === "comment") return "wre-workflow-rail wre-workflow-rail-comment";
+  return "wre-workflow-rail wre-workflow-rail-view";
+}
+
+function getWorkflowCandidateInlineClass(): string {
+  return "wre-workflow-inline wre-workflow-inline-candidate";
+}
+
+function getWorkflowCandidateRailClass(): string {
+  return "wre-workflow-rail wre-workflow-rail-candidate";
+}
+
+function getWorkflowBlockedInlineClass(reason: WorkflowBlockedCommandReason): string {
+  if (reason.code === "workflow_blocked_import") {
+    return "wre-workflow-inline wre-workflow-inline-blocked-import";
+  }
+  return "wre-workflow-inline wre-workflow-inline-preserve-only";
+}
+
+function getWorkflowBlockedRailClass(reason: WorkflowBlockedCommandReason): string {
+  if (reason.code === "workflow_blocked_import") {
+    return "wre-workflow-rail wre-workflow-rail-blocked-import";
+  }
+  return "wre-workflow-rail wre-workflow-rail-preserve-only";
+}
+
+function hasBlockChildren(node: PMNode): boolean {
+  for (let index = 0; index < node.childCount; index += 1) {
+    if (node.child(index).isBlock) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function collectRailRanges(doc: PMNode, from: number, to: number): Array<{ from: number; to: number }> {
+  const effectiveTo = Math.max(to, from + 1);
+  const ranges = new Map<string, { from: number; to: number }>();
+  let fallbackFrom: number | null = null;
+  let fallbackTo: number | null = null;
+  let fallbackSize: number | null = null;
+
+  doc.descendants((node, pos) => {
+    if (!node.isBlock || node.type.name === "doc") {
+      return true;
+    }
+
+    const nodeFrom = pos;
+    const nodeTo = pos + node.nodeSize;
+    if (nodeTo <= from || nodeFrom >= effectiveTo) {
+      return true;
+    }
+
+    if (!hasBlockChildren(node)) {
+      ranges.set(`${nodeFrom}:${nodeTo}`, { from: nodeFrom, to: nodeTo });
+      return true;
+    }
+
+    if (nodeFrom <= from && nodeTo >= effectiveTo) {
+      const size = nodeTo - nodeFrom;
+      if (fallbackSize === null || size < fallbackSize) {
+        fallbackFrom = nodeFrom;
+        fallbackTo = nodeTo;
+        fallbackSize = size;
+      }
+    }
+
+    return true;
+  });
+
+  if (ranges.size > 0) {
+    return [...ranges.values()];
+  }
+
+  if (fallbackFrom !== null && fallbackTo !== null) {
+    return [{ from: fallbackFrom, to: fallbackTo }];
+  }
+
+  return [];
+}
+
+function buildAnchorPmRange(
+  anchor: EditorAnchorProjection,
+  positionMap: PositionMap,
+): { from: number; to: number; allowInline: boolean } | null {
+  if (anchor.kind === "detached") {
+    return null;
+  }
+
+  if (anchor.kind === "range") {
+    return {
+      from: positionMap.runtimeToPm(anchor.from),
+      to: positionMap.runtimeToPm(anchor.to),
+      allowInline: true,
+    };
+  }
+
+  const pmAt = positionMap.runtimeToPm(anchor.at);
+  return {
+    from: pmAt,
+    to: pmAt + 1,
+    allowInline: false,
+  };
+}
+
+function pushRailDecorations(
+  decorations: Decoration[],
+  doc: PMNode,
+  from: number,
+  to: number,
+  spec: RailDecorationSpec,
+): void {
+  for (const range of collectRailRanges(doc, from, to)) {
+    decorations.push(
+      Decoration.node(range.from, range.to, {
+        class: spec.className,
+        "data-workflow-rail": spec.railKind,
+        ...spec.attrs,
+      }),
+    );
+  }
+}
+
 /**
  * Build ProseMirror DecorationSet from runtime comment and revision models.
  *
@@ -25,6 +170,8 @@ export function buildDecorations(
   showTrackedChanges = true,
   workflowScopes?: readonly WorkflowScope[],
   activeStory: EditorStoryTarget = MAIN_STORY_TARGET,
+  workflowCandidates?: readonly WorkflowCandidateRange[],
+  workflowBlockedReasons?: readonly WorkflowBlockedCommandReason[],
 ): DecorationSet {
   const decorations: Decoration[] = [];
 
@@ -98,34 +245,89 @@ export function buildDecorations(
     }
   }
 
-  // Walk workflow scopes and create inline decorations for scope emphasis.
   if (workflowScopes) {
     for (const scope of workflowScopes) {
       const scopeStoryTarget = scope.storyTarget ?? MAIN_STORY_TARGET;
       if (!storyTargetsEqual(scopeStoryTarget, activeStory)) continue;
-      if (scope.anchor.kind === "detached") continue;
-      const from = scope.anchor.kind === "range" ? scope.anchor.from : scope.anchor.at;
-      const to = scope.anchor.kind === "range" ? scope.anchor.to : scope.anchor.at;
-      const pmFrom = positionMap.runtimeToPm(from);
-      const pmTo = positionMap.runtimeToPm(to);
-      if (pmFrom >= pmTo) continue;
-
-      const modeClass =
-        scope.mode === "edit"
-          ? "bg-blue-50/40 ring-1 ring-blue-200/50"
-          : scope.mode === "suggest"
-            ? "bg-amber-50/40 ring-1 ring-amber-200/50"
-            : scope.mode === "comment"
-              ? "bg-green-50/40 ring-1 ring-green-200/50"
-              : "bg-gray-50/40 ring-1 ring-gray-200/50";
-
-      decorations.push(
-        Decoration.inline(pmFrom, pmTo, {
-          class: modeClass,
+      const pmRange = buildAnchorPmRange(scope.anchor, positionMap);
+      if (!pmRange) continue;
+
+      if (pmRange.allowInline && pmRange.from < pmRange.to) {
+        decorations.push(
+          Decoration.inline(pmRange.from, pmRange.to, {
+            class: getWorkflowInlineClass(scope),
+            "data-workflow-scope-id": scope.scopeId,
+            "data-workflow-scope-mode": scope.mode,
+          }),
+        );
+      }
+
+      pushRailDecorations(decorations, doc, pmRange.from, pmRange.to, {
+        railKind: "scope",
+        className: getWorkflowRailClass(scope),
+        attrs: {
           "data-workflow-scope-id": scope.scopeId,
           "data-workflow-scope-mode": scope.mode,
-        }),
-      );
+        },
+      });
+    }
+  }
+
+  if (workflowCandidates) {
+    for (const candidate of workflowCandidates) {
+      const candidateStoryTarget = candidate.storyTarget ?? MAIN_STORY_TARGET;
+      if (!storyTargetsEqual(candidateStoryTarget, activeStory)) continue;
+      const pmRange = buildAnchorPmRange(candidate.anchor, positionMap);
+      if (!pmRange) continue;
+
+      if (pmRange.allowInline && pmRange.from < pmRange.to) {
+        decorations.push(
+          Decoration.inline(pmRange.from, pmRange.to, {
+            class: getWorkflowCandidateInlineClass(),
+            "data-workflow-candidate-id": candidate.candidateId,
+          }),
+        );
+      }
+
+      pushRailDecorations(decorations, doc, pmRange.from, pmRange.to, {
+        railKind: "candidate",
+        className: getWorkflowCandidateRailClass(),
+        attrs: {
+          "data-workflow-candidate-id": candidate.candidateId,
+        },
+      });
+    }
+  }
+
+  if (workflowBlockedReasons) {
+    for (const reason of workflowBlockedReasons) {
+      if (
+        reason.code !== "workflow_preserve_only" &&
+        reason.code !== "workflow_blocked_import"
+      ) {
+        continue;
+      }
+      const reasonStoryTarget = reason.storyTarget ?? MAIN_STORY_TARGET;
+      if (!storyTargetsEqual(reasonStoryTarget, activeStory) || !reason.anchor) continue;
+      const pmRange = buildAnchorPmRange(reason.anchor, positionMap);
+      if (!pmRange) continue;
+
+      if (pmRange.allowInline && pmRange.from < pmRange.to) {
+        decorations.push(
+          Decoration.inline(pmRange.from, pmRange.to, {
+            class: getWorkflowBlockedInlineClass(reason),
+            "data-workflow-blocked-code": reason.code,
+          }),
+        );
+      }
+
+      pushRailDecorations(decorations, doc, pmRange.from, pmRange.to, {
+        railKind: "blocked",
+        className: getWorkflowBlockedRailClass(reason),
+        attrs: {
+          "data-workflow-blocked-code": reason.code,
+        },
+      });
     }
   }
 

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

@@ -39,6 +39,8 @@ export function createSurfaceDecorationKey(input: {
   activeCommentId?: string;
   activeRevisionId?: string;
   workflowScopeSignature?: string;
+  workflowCandidateSignature?: string;
+  workflowBlockedSignature?: string;
 }): string {
   return JSON.stringify({
     markupDisplay: input.markupDisplay,
@@ -47,5 +49,7 @@ export function createSurfaceDecorationKey(input: {
     activeCommentId: input.activeCommentId ?? null,
     activeRevisionId: input.activeRevisionId ?? null,
     workflowScopeSignature: input.workflowScopeSignature ?? null,
+    workflowCandidateSignature: input.workflowCandidateSignature ?? null,
+    workflowBlockedSignature: input.workflowBlockedSignature ?? null,
   });
 }

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

@@ -16,6 +16,8 @@ import type {
   SearchOptions,
   SearchResultSnapshot,
   SelectionSnapshot,
+  WorkflowBlockedCommandReason,
+  WorkflowCandidateRange,
   WorkflowScope,
 } from "../../api/public-types";
 import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
@@ -90,6 +92,8 @@ export interface TwProseMirrorSurfaceProps {
   onSelectionToolbarAnchorChange?: (anchor: SelectionToolbarAnchor | null) => void;
   mediaPreviews?: Record<string, MediaPreviewDescriptor>;
   workflowScopes?: readonly WorkflowScope[];
+  workflowCandidates?: readonly WorkflowCandidateRange[];
+  workflowBlockedReasons?: readonly WorkflowBlockedCommandReason[];
 }
 
 export interface TwProseMirrorSurfaceRef {
@@ -201,11 +205,15 @@ export const TwProseMirrorSurface = forwardRef<
         activeCommentId: snapshot.comments.activeCommentId,
         activeRevisionId: props.activeRevisionId,
         workflowScopeSignature: JSON.stringify(props.workflowScopes ?? []),
+        workflowCandidateSignature: JSON.stringify(props.workflowCandidates ?? []),
+        workflowBlockedSignature: JSON.stringify(props.workflowBlockedReasons ?? []),
       }),
     [
       canEdit,
       markupDisplay,
       props.activeRevisionId,
+      props.workflowCandidates,
+      props.workflowBlockedReasons,
       props.workflowScopes,
       showTrackedChanges,
       snapshot.comments.activeCommentId,
@@ -249,6 +257,8 @@ export const TwProseMirrorSurface = forwardRef<
         showTrackedChanges,
         props.workflowScopes,
         snapshot.activeStory,
+        props.workflowCandidates,
+        props.workflowBlockedReasons,
       );
       view.setProps({
         editable: () => canEdit,
@@ -265,7 +275,11 @@ export const TwProseMirrorSurface = forwardRef<
       markupDisplay,
       revisionModel,
       showTrackedChanges,
+      props.workflowBlockedReasons,
+      props.workflowCandidates,
       props.workflowScopes,
+      props.workflowCandidates,
+      props.workflowBlockedReasons,
     ],
   );
 
@@ -293,6 +307,8 @@ export const TwProseMirrorSurface = forwardRef<
       showTrackedChanges,
       props.workflowScopes,
       snapshot.activeStory,
+      props.workflowCandidates,
+      props.workflowBlockedReasons,
     );
     recordPerfSample("pm.rebuild");
     incrementInvalidationCounter("pm.laneA.rebuilds");

package/src/ui-tailwind/theme/editor-theme.css

@@ -258,6 +258,132 @@
   outline: none;
 }
 
+.prosemirror-surface .ProseMirror .wre-workflow-inline {
+  border-radius: 0.25rem;
+  box-shadow: inset 0 0 0 1px transparent;
+}
+
+.prosemirror-surface .ProseMirror .wre-workflow-inline-edit {
+  background: color-mix(in srgb, var(--color-accent) 10%, transparent);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--color-accent) 18%, transparent);
+}
+
+.prosemirror-surface .ProseMirror .wre-workflow-inline-suggest {
+  background: color-mix(in srgb, var(--color-warning) 12%, transparent);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--color-warning) 20%, transparent);
+}
+
+.prosemirror-surface .ProseMirror .wre-workflow-inline-comment {
+  background: color-mix(in srgb, var(--color-insert) 10%, transparent);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--color-insert) 18%, transparent);
+}
+
+.prosemirror-surface .ProseMirror .wre-workflow-inline-view {
+  background: color-mix(in srgb, var(--color-secondary) 7%, transparent);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--color-secondary) 14%, transparent);
+}
+
+.prosemirror-surface .ProseMirror .wre-workflow-inline-candidate {
+  background: color-mix(in srgb, var(--color-warning) 6%, transparent);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--color-warning) 18%, transparent);
+  text-decoration: underline;
+  text-decoration-style: dashed;
+  text-decoration-color: color-mix(in srgb, var(--color-warning) 55%, transparent);
+  text-underline-offset: 0.18em;
+}
+
+.prosemirror-surface .ProseMirror .wre-workflow-inline-preserve-only {
+  background: color-mix(in srgb, var(--color-danger) 7%, transparent);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--color-danger) 18%, transparent);
+}
+
+.prosemirror-surface .ProseMirror .wre-workflow-inline-blocked-import {
+  background: color-mix(in srgb, var(--color-danger) 8%, transparent);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--color-danger) 24%, transparent);
+  text-decoration: underline;
+  text-decoration-style: wavy;
+  text-decoration-color: color-mix(in srgb, var(--color-danger) 70%, transparent);
+  text-underline-offset: 0.18em;
+}
+
+.prosemirror-surface .ProseMirror .wre-workflow-rail {
+  position: relative;
+  padding-left: 0.875rem;
+  border-radius: 0.25rem;
+}
+
+.prosemirror-surface .ProseMirror .wre-workflow-rail::before {
+  content: "";
+  position: absolute;
+  left: 0;
+  top: 0.2rem;
+  bottom: 0.2rem;
+  width: 0.3rem;
+  border-radius: 999px;
+  background: var(--wre-workflow-rail-color, var(--color-border-strong));
+}
+
+.prosemirror-surface .ProseMirror .wre-workflow-rail-edit {
+  --wre-workflow-rail-color: var(--color-accent);
+  background: color-mix(in srgb, var(--color-accent) 7%, transparent);
+}
+
+.prosemirror-surface .ProseMirror .wre-workflow-rail-suggest {
+  --wre-workflow-rail-color: var(--color-warning);
+  background: color-mix(in srgb, var(--color-warning) 8%, transparent);
+}
+
+.prosemirror-surface .ProseMirror .wre-workflow-rail-comment {
+  --wre-workflow-rail-color: var(--color-insert);
+  background: color-mix(in srgb, var(--color-insert) 7%, transparent);
+}
+
+.prosemirror-surface .ProseMirror .wre-workflow-rail-view {
+  --wre-workflow-rail-color: var(--color-secondary);
+  background: color-mix(in srgb, var(--color-secondary) 6%, transparent);
+}
+
+.prosemirror-surface .ProseMirror .wre-workflow-rail-candidate {
+  --wre-workflow-rail-color: var(--color-warning);
+  background: color-mix(in srgb, var(--color-warning) 4%, transparent);
+}
+
+.prosemirror-surface .ProseMirror .wre-workflow-rail-candidate::before {
+  background:
+    repeating-linear-gradient(
+      to bottom,
+      var(--wre-workflow-rail-color, var(--color-warning)) 0,
+      var(--wre-workflow-rail-color, var(--color-warning)) 6px,
+      transparent 6px,
+      transparent 10px
+    );
+}
+
+.prosemirror-surface .ProseMirror .wre-workflow-rail-preserve-only {
+  --wre-workflow-rail-color: var(--color-danger);
+  background: color-mix(in srgb, var(--color-danger) 5%, transparent);
+}
+
+.prosemirror-surface .ProseMirror .wre-workflow-rail-preserve-only::before {
+  opacity: 0.85;
+}
+
+.prosemirror-surface .ProseMirror .wre-workflow-rail-blocked-import {
+  --wre-workflow-rail-color: var(--color-danger);
+  background: color-mix(in srgb, var(--color-danger) 8%, transparent);
+}
+
+.prosemirror-surface .ProseMirror .wre-workflow-rail-blocked-import::before {
+  background:
+    repeating-linear-gradient(
+      to bottom,
+      var(--wre-workflow-rail-color, var(--color-danger)) 0,
+      var(--wre-workflow-rail-color, var(--color-danger)) 4px,
+      transparent 4px,
+      transparent 8px
+    );
+}
+
 .prosemirror-surface:focus-visible {
   outline: none;
 }