@beyondwork/docx-react-component 1.0.19 → 1.0.21

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.19",
+  "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/api/public-types.ts

@@ -1,4 +1,13 @@
 import type { PersistedEditorSnapshot as RuntimePersistedEditorSnapshot } from "../core/state/editor-state.ts";
+import type {
+  FieldFamily as FieldFamilyType,
+  FieldRefreshStatus as FieldRefreshStatusType,
+  SupportedFieldFamily as SupportedFieldFamilyType,
+} from "../model/canonical-document.ts";
+
+export type FieldFamily = FieldFamilyType;
+export type FieldRefreshStatus = FieldRefreshStatusType;
+export type SupportedFieldFamily = SupportedFieldFamilyType;
 
 export type ExternalDocumentSource =
   | {
@@ -349,6 +358,70 @@ export interface DocumentHeadingSnapshot {
   sectionIndex: number;
 }
 
+/** A single field entry in the runtime field snapshot. */
+export interface FieldEntrySnapshot {
+  /** Stable index of the field in document order. */
+  index: number;
+  /** Classified field family. */
+  fieldFamily: FieldFamily;
+  /** Whether this family is in the supported refresh slice. */
+  supported: boolean;
+  /** Raw field instruction string. */
+  instruction: string;
+  /** Target bookmark for REF/PAGEREF/NOTEREF fields. */
+  fieldTarget?: string;
+  /** Current refresh status. */
+  refreshStatus: FieldRefreshStatus;
+  /** Resolved display text (from field children). */
+  displayText: string;
+}
+
+/** Runtime field snapshot — read-only view of all fields in the document. */
+export interface FieldSnapshot {
+  /** Total number of fields in the document. */
+  totalCount: number;
+  /** Number of fields in the supported refresh slice. */
+  supportedCount: number;
+  /** Number of fields that are preserve-only. */
+  preserveOnlyCount: number;
+  /** Ordered field entries. */
+  fields: FieldEntrySnapshot[];
+}
+
+/** Options for runtime-backed field refresh. */
+export interface UpdateFieldsOptions {
+  /** When true, only refresh fields in the supported slice. Default true. */
+  supportedOnly?: boolean;
+}
+
+/** Result of a runtime-backed field refresh operation. */
+export interface UpdateFieldsResult {
+  /** Total number of fields in the document. */
+  totalCount: number;
+  /** Number of fields that were refreshed. */
+  updatedCount: number;
+  /** Number of preserve-only fields left unchanged. */
+  preserveOnlyCount: number;
+}
+
+/** Options for runtime-backed TOC refresh. */
+export interface TocRefreshOptions {
+  /** Maximum heading outline level to include (1–9, default 3). */
+  maxLevel?: number;
+}
+
+/** Result of a TOC refresh operation. */
+export interface TocRefreshResult {
+  /** Number of TOC entries generated from heading structure. */
+  entryCount: number;
+  /** Heading entries that populated the TOC. */
+  entries: Array<{
+    level: number;
+    text: string;
+    pageIndex: number;
+  }>;
+}
+
 export interface StyleCatalogEntrySnapshot {
   styleId: string;
   displayName: string;
@@ -450,6 +523,17 @@ export type SurfaceInlineSegment =
       noteKind: "footnote" | "endnote";
       noteId: string;
       label: string;
+    }
+  | {
+      segmentId: string;
+      kind: "field_ref";
+      from: number;
+      to: number;
+      fieldFamily: SupportedFieldFamily;
+      fieldTarget?: string;
+      instruction: string;
+      refreshStatus: FieldRefreshStatus;
+      label: string;
     };
 
 export interface SurfaceTableCellSnapshot {
@@ -488,6 +572,7 @@ export type SurfaceBlockSnapshot =
       numberingSuffix?: "tab" | "space" | "nothing";
       alignment?: "left" | "center" | "right" | "both" | "distribute";
       spacing?: { before?: number; after?: number; line?: number; lineRule?: string };
+      contextualSpacing?: boolean;
       indentation?: { left?: number; right?: number; firstLine?: number; hanging?: number };
       borders?: { top?: unknown; left?: unknown; bottom?: unknown; right?: unknown; bar?: unknown; between?: unknown };
       shading?: { fill?: string; color?: string; val?: string };
@@ -639,6 +724,61 @@ export interface CompatibilityPanelSnapshot {
 
 export type ViewMode = "editing" | "review" | "view";
 
+/**
+ * Runtime document-mode — controls whether editing is unrestricted, restricted
+ * to suggestions, or fully read-only at the document level.
+ *
+ * Distinct from `ViewMode` (editor posture) and `WorkspaceMode` (shell layout).
+ * `DocumentMode` reflects document-level editing authority, not presentation.
+ */
+export type DocumentMode = "editing" | "suggesting" | "viewing";
+
+/**
+ * A single permission range parsed from `w:permStart` / `w:permEnd` in the
+ * source package.  Ranges carry stable ids, edit-rights metadata, and an
+ * enforcement reason that the UI can display.
+ */
+export interface ProtectionRange {
+  /** Stable range id from `w:id` on the originating `w:permStart`. */
+  rangeId: string;
+  /** Start offset of the editable range when the runtime can map it safely. */
+  start?: number;
+  /** End offset of the editable range when the runtime can map it safely. */
+  end?: number;
+  /** Editor group allowed to edit this range (`w:edGrp`), if specified. */
+  editorGroup?: string;
+  /** Specific editor identity (`w:ed`), if specified. */
+  editor?: string;
+  /** Whether this range is currently enforced by the runtime. */
+  enforced: boolean;
+  /** Human-readable reason for the enforcement state. */
+  enforcementReason: string;
+}
+
+/**
+ * Snapshot of the document's protection posture.  Descriptive and bounded —
+ * no public bypass around protected ranges, export blockers, or preserve-only
+ * regions.
+ */
+export interface ProtectionSnapshot {
+  /** Whether document-level protection is declared in the source package. */
+  hasDocumentProtection: boolean;
+  /**
+   * The declared protection edit type from `w:documentProtection` in
+   * `settings.xml` (e.g. `"readOnly"`, `"comments"`, `"trackedChanges"`,
+   * `"forms"`, `"none"`).  `undefined` when no protection element exists.
+   */
+  editType?: string;
+  /** Whether the declared protection is enforced (`w:enforcement="1"`). */
+  enforcementActive: boolean;
+  /** All parsed permission ranges from the source package. */
+  ranges: ProtectionRange[];
+  /** Count of permission ranges that are currently enforced. */
+  enforcedRangeCount: number;
+  /** Count of permission ranges preserved but not live-enforced. */
+  preservedRangeCount: number;
+}
+
 export type CaretAffinity = "forward" | "backward" | "none";
 
 export interface ActiveListContext {
@@ -670,6 +810,7 @@ export interface LayoutMeasurement {
 
 export interface EditorViewStateSnapshot {
   viewMode: ViewMode;
+  documentMode: DocumentMode;
   workspaceMode: WorkspaceMode;
   zoomLevel: ZoomLevel;
   activeStory: EditorStoryTarget;
@@ -697,6 +838,7 @@ export interface RuntimeRenderSnapshot {
   isReady: boolean;
   isDirty: boolean;
   readOnly: boolean;
+  documentMode: DocumentMode;
   selection: SelectionSnapshot;
   activeStory: EditorStoryTarget;
   pageLayout?: PageLayoutSnapshot;
@@ -708,6 +850,7 @@ export interface RuntimeRenderSnapshot {
   fatalError?: EditorError;
   commandState: CommandStateSnapshot;
   surface?: EditorSurfaceSnapshot;
+  protectionSnapshot: ProtectionSnapshot;
 }
 
 export interface EditorSessionState {
@@ -721,6 +864,7 @@ export interface EditorSessionState {
   canonicalDocument: RuntimePersistedEditorSnapshot["canonicalDocument"];
   compatibility: CompatibilityReport;
   warningLog: EditorWarning[];
+  protectionSnapshot?: ProtectionSnapshot;
   sourcePackage?: RuntimePersistedEditorSnapshot["sourcePackage"];
 }
 
@@ -736,6 +880,7 @@ export interface PersistedEditorSnapshot {
   canonicalDocument: RuntimePersistedEditorSnapshot["canonicalDocument"];
   compatibility: CompatibilityReport;
   warningLog: EditorWarning[];
+  protectionSnapshot?: ProtectionSnapshot;
   sourcePackage?: RuntimePersistedEditorSnapshot["sourcePackage"];
 }
 
@@ -762,6 +907,169 @@ export interface ExportResult {
   delivery: ExportDelivery;
 }
 
+export type WorkflowScopeMode = "edit" | "suggest" | "comment" | "view";
+
+export interface WorkflowCandidateRange {
+  candidateId: string;
+  storyTarget?: EditorStoryTarget;
+  anchor: EditorAnchorProjection;
+  label?: string;
+  source?: "search" | "playbook" | "host" | "ai";
+}
+
+export interface WorkflowScope {
+  scopeId: string;
+  mode: WorkflowScopeMode;
+  anchor: EditorAnchorProjection;
+  storyTarget?: EditorStoryTarget;
+  workItemId?: string;
+  label?: string;
+  domain?: "legal" | "commercial" | "finance" | "other";
+}
+
+export interface WorkflowWorkItem {
+  workItemId: string;
+  title: string;
+  description?: string;
+  domain?: "legal" | "commercial" | "finance" | "other";
+  status?: "pending" | "active" | "done" | "blocked";
+  scopeIds: string[];
+}
+
+export interface WorkflowOverlay {
+  overlayVersion: "workflow-overlay/1";
+  candidates?: WorkflowCandidateRange[];
+  scopes: WorkflowScope[];
+  workItems?: WorkflowWorkItem[];
+  activeWorkItemId?: string | null;
+}
+
+export interface WorkflowBlockedCommandReason {
+  code:
+    | "outside_workflow_scope"
+    | "workflow_comment_only"
+    | "workflow_view_only"
+    | "workflow_preserve_only"
+    | "workflow_blocked_import"
+    | "document_read_only"
+    | "document_viewing_mode"
+    | "protected_range"
+    | "unsupported_surface";
+  message: string;
+  scopeId?: string;
+  workItemId?: string;
+  anchor?: EditorAnchorProjection;
+  storyTarget?: EditorStoryTarget;
+}
+
+export interface WorkflowScopeSnapshot {
+  overlayPresent: boolean;
+  activeWorkItemId?: string | null;
+  activeWorkItem?: WorkflowWorkItem;
+  scopes: WorkflowScope[];
+  candidates: WorkflowCandidateRange[];
+  blockedReasons: WorkflowBlockedCommandReason[];
+}
+
+export interface InteractionGuardSnapshot {
+  blockedReasons: WorkflowBlockedCommandReason[];
+}
+
+export type WorkflowMarkupKind =
+  | "highlight"
+  | "comment"
+  | "revision"
+  | "field"
+  | "protected_range"
+  | "opaque_fragment";
+
+export interface WorkflowMarkupBase {
+  markupId: string;
+  kind: WorkflowMarkupKind;
+  anchor: EditorAnchorProjection;
+  storyTarget?: EditorStoryTarget;
+  label: string;
+  excerpt?: string;
+}
+
+export interface WorkflowHighlightMarkup extends WorkflowMarkupBase {
+  kind: "highlight";
+  color: string;
+  text: string;
+}
+
+export interface WorkflowCommentMarkup extends WorkflowMarkupBase {
+  kind: "comment";
+  commentId: string;
+  status: CommentSidebarThreadSnapshot["status"];
+  warningCount: number;
+  entryCount: number;
+  createdAt: string;
+  createdBy: string;
+}
+
+export interface WorkflowRevisionMarkup extends WorkflowMarkupBase {
+  kind: "revision";
+  revisionId: string;
+  revisionKind: TrackedChangeEntrySnapshot["kind"];
+  status: TrackedChangeEntrySnapshot["status"];
+  actionability: TrackedChangeEntrySnapshot["actionability"];
+  authorId: string;
+  createdAt: string;
+  preserveOnlyReason?: string;
+}
+
+export interface WorkflowFieldMarkup extends WorkflowMarkupBase {
+  kind: "field";
+  fieldIndex: number;
+  fieldFamily: FieldFamily;
+  fieldTarget?: string;
+  refreshStatus: FieldRefreshStatus;
+  displayText: string;
+}
+
+export interface WorkflowProtectedRangeMarkup extends WorkflowMarkupBase {
+  kind: "protected_range";
+  rangeId: string;
+  enforced: boolean;
+  enforcementReason: string;
+  editorGroup?: string;
+  editor?: string;
+}
+
+export interface WorkflowOpaqueFragmentMarkup extends WorkflowMarkupBase {
+  kind: "opaque_fragment";
+  fragmentId: string;
+  warningId: string;
+  detail: string;
+  blockedReasonCode: "workflow_preserve_only" | "workflow_blocked_import";
+}
+
+export type WorkflowMarkupItem =
+  | WorkflowHighlightMarkup
+  | WorkflowCommentMarkup
+  | WorkflowRevisionMarkup
+  | WorkflowFieldMarkup
+  | WorkflowProtectedRangeMarkup
+  | WorkflowOpaqueFragmentMarkup;
+
+export interface WorkflowMarkupSnapshot {
+  totalCount: number;
+  items: WorkflowMarkupItem[];
+  highlights: WorkflowHighlightMarkup[];
+  comments: WorkflowCommentMarkup[];
+  revisions: WorkflowRevisionMarkup[];
+  fields: WorkflowFieldMarkup[];
+  protectedRanges: WorkflowProtectedRangeMarkup[];
+  opaqueFragments: WorkflowOpaqueFragmentMarkup[];
+}
+
+export interface WorkflowCandidateRangeOptions {
+  kinds?: WorkflowMarkupKind[];
+  includeDetached?: boolean;
+  source?: WorkflowCandidateRange["source"];
+}
+
 export type AutosaveState =
   | { status: "idle" }
   | { status: "saving" }
@@ -858,6 +1166,22 @@ export type WordReviewEditorEvent =
       type: "export_completed";
       documentId: string;
       result: ExportResult;
+    }
+  | {
+      type: "workflow_overlay_changed";
+      documentId: string;
+      snapshot: WorkflowScopeSnapshot;
+    }
+  | {
+      type: "workflow_active_work_item_changed";
+      documentId: string;
+      activeWorkItemId: string | null;
+    }
+  | {
+      type: "command_blocked";
+      documentId: string;
+      command: string;
+      reasons: WorkflowBlockedCommandReason[];
     };
 
 export interface LoadResult {
@@ -980,7 +1304,12 @@ export interface WordReviewEditorRef {
   closeStory(): void;
   getPageLayoutSnapshot(): PageLayoutSnapshot | null;
   getDocumentNavigationSnapshot(): DocumentNavigationSnapshot;
+  getFieldSnapshot(): FieldSnapshot;
+  updateFields(options?: UpdateFieldsOptions): UpdateFieldsResult;
+  updateTableOfContents(options?: TocRefreshOptions): TocRefreshResult;
   getViewState(): EditorViewStateSnapshot;
+  setDocumentMode(mode: DocumentMode): void;
+  getProtectionSnapshot(): ProtectionSnapshot;
   setWorkspaceMode(mode: WorkspaceMode): void;
   setZoom(level: ZoomLevel): void;
   insertSectionBreak(type: SectionBreakType, options?: { afterSectionIndex?: number }): void;
@@ -993,6 +1322,13 @@ export interface WordReviewEditorRef {
   setHeaderFooterLink(sectionIndex: number, params: HeaderFooterLinkPatch): void;
   setImageLayout(mediaId: string, dimensions: { widthEmu: number; heightEmu: number }): void;
   setImageFrame(mediaId: string, offsets: { horizontalOffsetEmu?: number; verticalOffsetEmu?: number }): void;
+  setWorkflowOverlay(overlay: WorkflowOverlay): void;
+  clearWorkflowOverlay(): void;
+  getWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null;
+  getInteractionGuardSnapshot(): InteractionGuardSnapshot;
+  getWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot;
+  getWorkflowCandidateRanges(options?: WorkflowCandidateRangeOptions): WorkflowCandidateRange[];
+  replaceWorkflowMarkupText(markupId: string, text: string): void;
 }
 
 export interface WordReviewEditorProps {

package/src/api/session-state.ts

@@ -31,6 +31,7 @@ export function editorSessionStateFromPersistedSnapshot(
     canonicalDocument: snapshot.canonicalDocument,
     compatibility: snapshot.compatibility,
     warningLog: snapshot.warningLog,
+    protectionSnapshot: snapshot.protectionSnapshot,
     sourcePackage: snapshot.sourcePackage,
   });
 }
@@ -53,6 +54,7 @@ export function persistedSnapshotFromEditorSessionState(
     canonicalDocument: sessionState.canonicalDocument,
     compatibility: sessionState.compatibility,
     warningLog: sessionState.warningLog,
+    protectionSnapshot: sessionState.protectionSnapshot,
     sourcePackage: sessionState.sourcePackage,
   });
 }

package/src/core/commands/formatting-commands.ts

@@ -973,7 +973,7 @@ function setMarkValue(
 ): TextMark[] | undefined {
   const nextMarks = cloneMarks(marks).filter((candidate) => {
     if (markType === "backgroundColor") {
-      return candidate.type !== "backgroundColor";
+      return candidate.type !== "backgroundColor" && candidate.type !== "highlight";
     }
     return candidate.type !== markType;
   });

package/src/core/commands/index.ts

@@ -60,6 +60,7 @@ export type EditorCommand =
       document: CanonicalDocumentEnvelope;
       mapping?: TransactionMapping;
       selection?: SelectionSnapshot;
+      protectionSelection?: SelectionSnapshot;
       origin?: CommandOrigin;
     }
   | {
@@ -110,6 +111,7 @@ export type EditorCommand =
   | {
       type: "comment.add";
       comment: CommentThreadRecord;
+      selection?: SelectionSnapshot;
       origin?: CommandOrigin;
     }
   | {
@@ -615,7 +617,12 @@ export function remapSelection(
   }
 
   if (activeRange.kind === "node") {
-    return createSelectionSnapshot(activeRange.at, activeRange.at);
+    return {
+      anchor: activeRange.at,
+      head: activeRange.at,
+      isCollapsed: true,
+      activeRange,
+    };
   }
 
   return {
@@ -680,7 +687,12 @@ function normalizeSelection(selection: SelectionSnapshot): SelectionSnapshot {
   }
 
   if (activeRange.kind === "node") {
-    return createSelectionSnapshot(activeRange.at, activeRange.at);
+    return {
+      anchor: activeRange.at,
+      head: activeRange.at,
+      isCollapsed: true,
+      activeRange,
+    };
   }
 
   return {

package/src/core/search/search-text.ts

@@ -3,6 +3,7 @@ import type {
   SearchOptions as PublicSearchOptions,
   SecondaryStorySurface,
   SurfaceBlockSnapshot,
+  WorkflowCandidateRange,
 } from "../../api/public-types";
 
 export interface SearchTextOptions extends PublicSearchOptions {
@@ -156,6 +157,33 @@ export function searchSecondaryStories(
   return results;
 }
 
+/**
+ * Derive workflow candidate ranges from search results.
+ *
+ * Maps search hits into `WorkflowCandidateRange` values suitable for
+ * inclusion in a host-fed `WorkflowOverlay`. The runtime search results
+ * supply runtime-mapped `from`/`to` positions that align with the
+ * canonical document model.
+ */
+export function deriveCandidateRangesFromSearch(
+  results: readonly SurfaceSearchResult[],
+  storyTarget?: EditorStoryTarget,
+  source: WorkflowCandidateRange["source"] = "search",
+): WorkflowCandidateRange[] {
+  return results.map((result, index) => ({
+    candidateId: `search-candidate-${index}`,
+    storyTarget,
+    anchor: {
+      kind: "range" as const,
+      from: result.from,
+      to: result.to,
+      assoc: { start: 1 as const, end: -1 as const },
+    },
+    label: result.excerpt,
+    source,
+  }));
+}
+
 export function projectSurfaceText(
   blocks: readonly SurfaceBlockSnapshot[],
 ): ProjectedSurfaceText {

package/src/core/state/editor-state.ts

@@ -10,6 +10,7 @@ import {
   assertPersistedEditorSnapshot as assertModelPersistedEditorSnapshot,
   createPersistedEditorSnapshot as createModelPersistedEditorSnapshot,
   validatePersistedEditorSnapshot as validateModelPersistedEditorSnapshot,
+  type ProtectionSnapshotRecord as ModelProtectionSnapshotRecord,
   type PersistedEditorSnapshot as ModelPersistedEditorSnapshot,
 } from "../../model/snapshot.ts";
 import {
@@ -638,6 +639,7 @@ export function createPersistedEditorSnapshot(
     editorBuild: string;
     savedAt: string;
     compatibility?: CompatibilityReport;
+    protectionSnapshot?: ModelProtectionSnapshotRecord;
   },
 ): PersistedEditorSnapshot {
   const snapshot = createModelPersistedEditorSnapshot({
@@ -647,6 +649,7 @@ export function createPersistedEditorSnapshot(
     canonicalDocument: state.document,
     compatibility: (options.compatibility ?? state.compatibility) as never,
     warningLog: state.warnings as never,
+    protectionSnapshot: options.protectionSnapshot,
     sourcePackage: state.sourcePackage,
   });
   return snapshot as PersistedEditorSnapshot;

package/src/index.ts

@@ -6,6 +6,8 @@ export {
   EDITOR_SESSION_STATE_VERSION,
 } from "./api/session-state.ts";
 export type {
+  LoadRequest,
+  LoadSourcePolicy,
   EditorSessionState,
   EditorHostAdapter,
   WordReviewEditorProps,
@@ -72,4 +74,23 @@ export type {
   SurfaceTextMark,
   EditorSurfaceSnapshot,
   CommandStateSnapshot,
+  WorkflowScopeMode,
+  WorkflowCandidateRange,
+  WorkflowScope,
+  WorkflowWorkItem,
+  WorkflowOverlay,
+  WorkflowBlockedCommandReason,
+  WorkflowScopeSnapshot,
+  InteractionGuardSnapshot,
+  WorkflowMarkupKind,
+  WorkflowMarkupBase,
+  WorkflowHighlightMarkup,
+  WorkflowCommentMarkup,
+  WorkflowRevisionMarkup,
+  WorkflowFieldMarkup,
+  WorkflowProtectedRangeMarkup,
+  WorkflowOpaqueFragmentMarkup,
+  WorkflowMarkupItem,
+  WorkflowMarkupSnapshot,
+  WorkflowCandidateRangeOptions,
 } from "./api/public-types.ts";