@beyondwork/docx-react-component 1.0.18 → 1.0.20

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 =
   | {
@@ -6,12 +15,25 @@ export type ExternalDocumentSource =
       bytes: Uint8Array | ArrayBuffer;
       sourceLabel?: string;
     }
+  | {
+      kind: "session";
+      sessionState: EditorSessionState;
+      sourceLabel?: string;
+    }
   | {
       kind: "snapshot";
       snapshot: PersistedEditorSnapshot;
       sourceLabel?: string;
     };
 
+export type LoadSourcePolicy = "prefer-saved-state" | "prefer-source-package";
+
+export interface LoadRequest {
+  documentId: string;
+  loadRevision?: string;
+  loadSourcePolicy?: LoadSourcePolicy;
+}
+
 export interface EditorUser {
   userId: string;
   displayName: string;
@@ -43,11 +65,129 @@ export type EditorAnchorProjection =
       reason: "deleted" | "invalidatedByStructureChange" | "importAmbiguity";
     };
 
+export type EditorStoryTarget =
+  | { kind: "main" }
+  | {
+      kind: "header";
+      relationshipId: string;
+      variant: "default" | "first" | "even";
+      sectionIndex?: number;
+    }
+  | {
+      kind: "footer";
+      relationshipId: string;
+      variant: "default" | "first" | "even";
+      sectionIndex?: number;
+    }
+  | { kind: "footnote"; noteId: string }
+  | { kind: "endnote"; noteId: string };
+
 export interface SelectionSnapshot {
   anchor: number;
   head: number;
   isCollapsed: boolean;
   activeRange: EditorAnchorProjection;
+  storyTarget?: EditorStoryTarget;
+}
+
+export interface PageLayoutSnapshot {
+  sectionIndex: number;
+  sectionType?: "continuous" | "nextPage" | "evenPage" | "oddPage" | "nextColumn";
+  pageWidth: number;
+  pageHeight: number;
+  marginTop: number;
+  marginBottom: number;
+  marginLeft: number;
+  marginRight: number;
+  headerMargin: number;
+  footerMargin: number;
+  gutter: number;
+  orientation: "portrait" | "landscape";
+  columns: number;
+  differentFirstPage: boolean;
+  differentOddEvenPages: boolean;
+  pageNumbering?: {
+    format?: string;
+    start?: number;
+    chapterStyle?: string;
+    chapterSeparator?: string;
+  };
+  lineNumbering?: {
+    countBy?: number;
+    start?: number;
+    distance?: number;
+    restart?: "newPage" | "newSection" | "continuous";
+  };
+  pageBorders?: {
+    top?: { value?: string; size?: number; space?: number; color?: string };
+    left?: { value?: string; size?: number; space?: number; color?: string };
+    bottom?: { value?: string; size?: number; space?: number; color?: string };
+    right?: { value?: string; size?: number; space?: number; color?: string };
+    offsetFrom?: "page" | "text";
+    display?: "allPages" | "firstPage" | "notFirstPage";
+    zOrder?: "front" | "back";
+  };
+  documentGrid?: {
+    type?: "default" | "lines" | "linesAndChars" | "snapToChars";
+    linePitch?: number;
+    charSpace?: number;
+  };
+  columnDefinitions: Array<{ width: number; space?: number }>;
+  equalWidthColumns: boolean;
+  columnSeparator: boolean;
+  headerVariants: Array<{ variant: "default" | "first" | "even"; relationshipId: string }>;
+  footerVariants: Array<{ variant: "default" | "first" | "even"; relationshipId: string }>;
+}
+
+export type WorkspaceMode = "canvas" | "page";
+
+export type ZoomLevel = "pageWidth" | "onePage" | number;
+
+export type SectionBreakType =
+  | "nextPage"
+  | "continuous"
+  | "evenPage"
+  | "oddPage"
+  | "nextColumn";
+
+export interface SectionLayoutPatch {
+  pageSize?: Partial<{
+    width: number;
+    height: number;
+    orientation: "portrait" | "landscape";
+  }>;
+  pageMargins?: Partial<{
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+    header: number;
+    footer: number;
+    gutter: number;
+  }>;
+  columns?: Partial<{
+    count: number;
+    space: number;
+    equalWidth: boolean;
+    columns: Array<{ width: number; space?: number }>;
+    separator: boolean;
+  }>;
+  titlePage?: boolean;
+  sectionType?: SectionBreakType;
+}
+
+export interface SectionPageNumberingPatch {
+  format?: string | null;
+  start?: number | null;
+  chapterStyle?: string | null;
+  chapterSeparator?: string | null;
+}
+
+export interface HeaderFooterLinkPatch {
+  kind: "header" | "footer";
+  variant: "default" | "first" | "even";
+  linkToPrevious: boolean;
+  relationshipId?: string | null;
 }
 
 export interface DocumentStats {
@@ -144,6 +284,7 @@ export interface FormattingStateSnapshot {
   textColor?: string;
   highlightColor?: string | null;
   alignment?: FormattingAlignment;
+  paragraphStyleId?: string;
   breadcrumb: FormattingBreadcrumbItem[];
 }
 
@@ -158,6 +299,143 @@ export interface SearchResultSnapshot {
   anchor: EditorAnchorProjection;
   excerpt: string;
   isActive: boolean;
+  storyTarget?: EditorStoryTarget;
+  sectionIndex?: number;
+  pageIndex?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Document Navigation Model (Wave 37)
+// ---------------------------------------------------------------------------
+
+/**
+ * Runtime-owned snapshot of the document's page stack, heading outline, and
+ * navigation context.  Derived from canonical document state and section
+ * properties — never from DOM scroll position or CSS layout.
+ */
+export interface DocumentNavigationSnapshot {
+  /** Total estimated page count across all sections. */
+  pageCount: number;
+  /** Ordered page descriptors, one per logical page. */
+  pages: DocumentPageSnapshot[];
+  /** Ordered heading outline extracted from paragraph styles. */
+  headings: DocumentHeadingSnapshot[];
+  /** Index of the page containing the current selection head. */
+  activePageIndex: number;
+  /** Section index containing the current selection head. */
+  activeSectionIndex: number;
+}
+
+/** Runtime-derived descriptor for a single logical page. */
+export interface DocumentPageSnapshot {
+  /** Zero-based page index within the whole document. */
+  pageIndex: number;
+  /** Section that owns this page (zero-based). */
+  sectionIndex: number;
+  /** Zero-based page index within its owning section. */
+  pageInSection: number;
+  /** Estimated character offset where the page begins in the main story. */
+  startOffset: number;
+  /** Estimated character offset where the page ends in the main story. */
+  endOffset: number;
+  /** Page layout properties inherited from the section. */
+  layout: PageLayoutSnapshot;
+}
+
+/** A heading entry in the document outline. */
+export interface DocumentHeadingSnapshot {
+  /** Stable identifier for the heading (derived from block position). */
+  headingId: string;
+  /** Outline level (1 = Heading 1, 2 = Heading 2, etc.). */
+  level: number;
+  /** Plain-text content of the heading paragraph. */
+  text: string;
+  /** Character offset of the heading in the main story. */
+  offset: number;
+  /** Zero-based page index where the heading lives. */
+  pageIndex: number;
+  /** Section index where the heading lives. */
+  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;
+  kind: "paragraph" | "character" | "table";
+  isDefault: boolean;
+  basedOn?: string;
+  nextStyle?: string;
+}
+
+export interface StyleCatalogSnapshot {
+  paragraphs: StyleCatalogEntrySnapshot[];
+  characters: StyleCatalogEntrySnapshot[];
+  tables: StyleCatalogEntrySnapshot[];
+  fromPackage: boolean;
 }
 
 export interface InsertTableOptions {
@@ -234,7 +512,28 @@ export type SurfaceInlineSegment =
       warningId: string;
       label: string;
       detail: string;
+      presentation?: "inline-chip" | "quiet-marker";
       state: "locked-preserve-only";
+    }
+  | {
+      segmentId: string;
+      kind: "note_ref";
+      from: number;
+      to: number;
+      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 {
@@ -243,11 +542,19 @@ export interface SurfaceTableCellSnapshot {
   colspan: number;
   rowspan: number;
   backgroundColor?: string | null;
+  verticalAlign?: "top" | "center" | "bottom" | null;
+  borderTop?: string | null;
+  borderRight?: string | null;
+  borderBottom?: string | null;
+  borderLeft?: string | null;
   content: SurfaceBlockSnapshot[];
 }
 
 export interface SurfaceTableRowSnapshot {
   cells: SurfaceTableCellSnapshot[];
+  height?: number;
+  heightRule?: "auto" | "atLeast" | "exact";
+  isHeader?: boolean;
 }
 
 export type SurfaceBlockSnapshot =
@@ -261,8 +568,11 @@ export type SurfaceBlockSnapshot =
         numberingInstanceId: string;
         level: number;
       };
+      numberingPrefix?: string;
+      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 };
@@ -272,6 +582,7 @@ export type SurfaceBlockSnapshot =
       pageBreakBefore?: boolean;
       outlineLevel?: number;
       bidi?: boolean;
+      suppressLineNumbers?: boolean;
       segments: SurfaceInlineSegment[];
     }
   | {
@@ -281,6 +592,15 @@ export type SurfaceBlockSnapshot =
       to: number;
       styleId?: string;
       gridColumns: number[];
+      alignment?: "left" | "center" | "right";
+      tblLook?: {
+        firstRow?: boolean;
+        lastRow?: boolean;
+        firstColumn?: boolean;
+        lastColumn?: boolean;
+        noHBand?: boolean;
+        noVBand?: boolean;
+      };
       rows: SurfaceTableRowSnapshot[];
     }
   | {
@@ -292,6 +612,11 @@ export type SurfaceBlockSnapshot =
       alias?: string;
       tag?: string;
       lock?: string;
+      checkboxChecked?: boolean;
+      dateValue?: string;
+      dropdownItems?: Array<{ displayText?: string; value: string }>;
+      comboBoxItems?: Array<{ displayText?: string; value: string }>;
+      showingPlcHdr?: boolean;
       children: SurfaceBlockSnapshot[];
     }
   | {
@@ -306,11 +631,19 @@ export type SurfaceBlockSnapshot =
       state: "locked-preserve-only";
     };
 
+export interface SecondaryStorySurface {
+  target: EditorStoryTarget;
+  label: string;
+  storySize: number;
+  blocks: SurfaceBlockSnapshot[];
+}
+
 export interface EditorSurfaceSnapshot {
   storySize: number;
   plainText: string;
   blocks: SurfaceBlockSnapshot[];
   lockedFragmentIds: string[];
+  secondaryStories: SecondaryStorySurface[];
 }
 
 export type EditorWarningCode =
@@ -354,7 +687,7 @@ export interface EditorError {
   code: EditorErrorCode;
   message: string;
   isFatal: boolean;
-  source: "import" | "runtime" | "validation" | "datastore" | "export";
+  source: "import" | "runtime" | "validation" | "datastore" | "host" | "export";
   details?: Record<string, unknown>;
 }
 
@@ -389,6 +722,108 @@ export interface CompatibilityPanelSnapshot {
   featureEntries: CompatibilityFeatureEntry[];
 }
 
+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 {
+  numberingInstanceId: string;
+  level: number;
+  isOrdered: boolean;
+  markerText?: string;
+}
+
+export interface ActiveNoteContext {
+  noteKind: "footnote" | "endnote";
+  noteId: string;
+  referencePosition: number;
+}
+
+export interface PageRegionHitTest {
+  region: "body" | "header" | "footer" | "margin" | "gutter";
+  sectionIndex: number;
+  columnIndex: number;
+}
+
+export interface LayoutMeasurement {
+  pageRegions: PageRegionHitTest[];
+  caretAffinity: CaretAffinity;
+  tabStops: Array<{ pos: number; val?: string; leader?: string }>;
+  listMarkerLane?: { indent: number; markerWidth: number };
+  objectFrame?: { kind: "image" | "textbox" | "shape"; anchorPos: number; display: "inline" | "floating" };
+}
+
+export interface EditorViewStateSnapshot {
+  viewMode: ViewMode;
+  documentMode: DocumentMode;
+  workspaceMode: WorkspaceMode;
+  zoomLevel: ZoomLevel;
+  activeStory: EditorStoryTarget;
+  selection: SelectionSnapshot;
+  caretAffinity: CaretAffinity;
+  activeListContext: ActiveListContext | null;
+  activeNoteContext: ActiveNoteContext | null;
+  activePageRegion: PageRegionHitTest | null;
+  activeObjectFrame: LayoutMeasurement["objectFrame"] | null;
+  measurement: LayoutMeasurement;
+  isFocused: boolean;
+}
+
 export interface CommandStateSnapshot {
   canUndo: boolean;
   canRedo: boolean;
@@ -403,7 +838,10 @@ export interface RuntimeRenderSnapshot {
   isReady: boolean;
   isDirty: boolean;
   readOnly: boolean;
+  documentMode: DocumentMode;
   selection: SelectionSnapshot;
+  activeStory: EditorStoryTarget;
+  pageLayout?: PageLayoutSnapshot;
   documentStats: DocumentStats;
   comments: CommentSidebarSnapshot;
   trackedChanges: TrackedChangesSnapshot;
@@ -412,6 +850,22 @@ export interface RuntimeRenderSnapshot {
   fatalError?: EditorError;
   commandState: CommandStateSnapshot;
   surface?: EditorSurfaceSnapshot;
+  protectionSnapshot: ProtectionSnapshot;
+}
+
+export interface EditorSessionState {
+  sessionVersion: "editor-session-state/1";
+  schemaVersion: RuntimePersistedEditorSnapshot["schemaVersion"];
+  documentId: string;
+  docId: string;
+  createdAt: string;
+  updatedAt: string;
+  editorBuild: string;
+  canonicalDocument: RuntimePersistedEditorSnapshot["canonicalDocument"];
+  compatibility: CompatibilityReport;
+  warningLog: EditorWarning[];
+  protectionSnapshot?: ProtectionSnapshot;
+  sourcePackage?: RuntimePersistedEditorSnapshot["sourcePackage"];
 }
 
 export interface PersistedEditorSnapshot {
@@ -426,6 +880,7 @@ export interface PersistedEditorSnapshot {
   canonicalDocument: RuntimePersistedEditorSnapshot["canonicalDocument"];
   compatibility: CompatibilityReport;
   warningLog: EditorWarning[];
+  protectionSnapshot?: ProtectionSnapshot;
   sourcePackage?: RuntimePersistedEditorSnapshot["sourcePackage"];
 }
 
@@ -440,10 +895,179 @@ export interface ExportDocxOptions {
   reason?: string;
 }
 
+export interface ExportDelivery {
+  mode: "downloaded" | "persisted-by-host" | "exported-bytes-only";
+  savedAt?: string;
+}
+
 export interface ExportResult {
   bytes: Uint8Array;
   mimeType: string;
   fileName: string;
+  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 =
@@ -462,7 +1086,7 @@ export type WordReviewEditorEvent =
       type: "ready";
       documentId: string;
       sessionId: string;
-      source: "docx" | "snapshot" | "datastore" | "canonical";
+      source: "docx" | "session" | "snapshot";
       stats: DocumentStats;
       compatibility: CompatibilityReport;
       comments: CommentSidebarSnapshot;
@@ -499,6 +1123,11 @@ export type WordReviewEditorEvent =
       documentId: string;
       changeId: string;
     }
+  | {
+      type: "story_changed";
+      documentId: string;
+      activeStory: EditorStoryTarget;
+    }
   | {
       type: "warning_added";
       documentId: string;
@@ -526,10 +1155,33 @@ export type WordReviewEditorEvent =
       snapshot: PersistedEditorSnapshot;
       isAutosave: boolean;
     }
+  | {
+      type: "session_saved";
+      documentId: string;
+      sessionState: EditorSessionState;
+      savedAt: string;
+      isAutosave: boolean;
+    }
   | {
       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 {
@@ -546,6 +1198,16 @@ export interface SaveSnapshotResult {
   savedAt: string;
 }
 
+export interface SaveSessionParams {
+  documentId: string;
+  sessionState: EditorSessionState;
+  isAutosave: boolean;
+}
+
+export interface SaveSessionResult {
+  savedAt: string;
+}
+
 export interface SaveExportParams {
   documentId: string;
   result: ExportResult;
@@ -561,10 +1223,17 @@ export interface EditorTelemetryEvent {
   detail?: Record<string, unknown>;
 }
 
+export interface EditorHostAdapter {
+  load?(params: LoadRequest): Promise<LoadResult>;
+  saveSession?(params: SaveSessionParams): Promise<SaveSessionResult>;
+  saveExport?(params: SaveExportParams): Promise<SaveExportResult>;
+  logEvent?(event: EditorTelemetryEvent): void;
+}
+
 export interface EditorDatastoreAdapter {
-  load(params: { documentId: string }): Promise<LoadResult>;
+  load(params: LoadRequest): Promise<LoadResult>;
   saveSnapshot(params: SaveSnapshotParams): Promise<SaveSnapshotResult>;
-  saveExport(params: SaveExportParams): Promise<SaveExportResult>;
+  saveExport?(params: SaveExportParams): Promise<SaveExportResult>;
   logEvent?(event: EditorTelemetryEvent): void;
 }
 
@@ -585,6 +1254,7 @@ export interface WordReviewEditorRef {
   acceptAllChanges(): void;
   rejectAllChanges(): void;
   exportDocx(options?: ExportDocxOptions): Promise<ExportResult>;
+  getSessionState(): EditorSessionState;
   getSnapshot(): PersistedEditorSnapshot;
   getRenderSnapshot(): RuntimeRenderSnapshot;
   getCompatibilityReport(): CompatibilityReport;
@@ -595,6 +1265,7 @@ export interface WordReviewEditorRef {
   getTrackedChanges(): TrackedChangesSnapshot;
   isDirty(): boolean;
   getFormattingState(): FormattingStateSnapshot;
+  getStyleCatalog(): StyleCatalogSnapshot;
   replaceText(text: string, target?: EditorAnchorProjection): void;
   toggleBold(): void;
   toggleItalic(): void;
@@ -607,6 +1278,8 @@ export interface WordReviewEditorRef {
   setTextColor(color: string | null): void;
   setHighlightColor(color: string | null): void;
   setAlignment(alignment: FormattingAlignment): void;
+  setParagraphStyle(styleId: string | null): void;
+  setTableStyle(styleId: string | null): void;
   indent(): void;
   outdent(): void;
   insertPageBreak(): void;
@@ -627,20 +1300,53 @@ export interface WordReviewEditorRef {
   setSelection(selection: SelectionSnapshot | null): void;
   scrollToRevision(revisionId: string): void;
   scrollToComment(commentId: string): void;
+  openStory(target: EditorStoryTarget): void;
+  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;
+  deleteSectionBreak(sectionIndex: number): void;
+  updateSectionLayout(sectionIndex: number, patch: SectionLayoutPatch): void;
+  setSectionPageNumbering(
+    sectionIndex: number,
+    patch: SectionPageNumberingPatch | null,
+  ): void;
+  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 {
   documentId: string;
   currentUser: EditorUser;
   initialDocx?: Uint8Array | ArrayBuffer;
+  initialSessionState?: EditorSessionState;
   initialSnapshot?: PersistedEditorSnapshot;
   initialSourceLabel?: string;
   externalDocumentRevision?: string;
   externalDocSource?: ExternalDocumentSource;
+  loadRevision?: string;
+  loadSourcePolicy?: LoadSourcePolicy;
   readOnly?: boolean;
   reviewMode?: "editing" | "review";
   markupDisplay?: "clean" | "simple" | "all";
   showReviewPanel?: boolean;
+  hostAdapter?: EditorHostAdapter;
   datastore?: EditorDatastoreAdapter;
   autosave?: AutosaveConfig;
   onEvent?: (event: WordReviewEditorEvent) => void;