@beyondwork/docx-react-component 1.0.29 → 1.0.31

package/src/api/public-types.ts

@@ -0,0 +1,1952 @@
+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 =
+  | {
+      kind: "docx";
+      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;
+  email?: string;
+  avatarUrl?: string;
+}
+
+export type EditorAnchorProjection =
+  | {
+      kind: "range";
+      from: number;
+      to: number;
+      assoc: {
+        start: -1 | 1;
+        end: -1 | 1;
+      };
+    }
+  | {
+      kind: "node";
+      at: number;
+      assoc: -1 | 1;
+    }
+  | {
+      kind: "detached";
+      lastKnownRange: {
+        from: number;
+        to: number;
+      };
+      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 {
+  storyLength: number;
+  commentCount: number;
+  revisionCount: number;
+  opaqueFragmentCount: number;
+}
+
+export interface CommentSidebarSnapshot {
+  activeCommentId?: string;
+  openCommentIds: string[];
+  resolvedCommentIds: string[];
+  detachedCommentIds: string[];
+  totalCount: number;
+  threads: CommentSidebarThreadSnapshot[];
+}
+
+export interface CommentSidebarThreadEntrySnapshot {
+  entryId: string;
+  authorId: string;
+  body: string;
+  createdAt: string;
+}
+
+export interface CommentSidebarThreadSnapshot {
+  commentId: string;
+  status: "open" | "resolved" | "detached";
+  anchor: EditorAnchorProjection;
+  excerpt: string;
+  entryCount: number;
+  entries: CommentSidebarThreadEntrySnapshot[];
+  createdAt: string;
+  createdBy: string;
+  warningCount: number;
+  anchorLabel: string;
+  detachedReason?: "incomplete-markers" | "multi-paragraph" | "opaque-region" | "revision-overlap";
+  actionabilityNote?: string;
+  isActive: boolean;
+  resolvedAt?: string;
+  resolvedBy?: string;
+}
+
+export interface TrackedChangeEntrySnapshot {
+  revisionId: string;
+  kind: "insertion" | "deletion" | "formatting" | "move" | "property-change";
+  source?: "runtime" | "import";
+  suggestionId?: string;
+  semanticKind?:
+    | "insertion"
+    | "deletion"
+    | "replacement"
+    | "formatting-change"
+    | "paragraph-property-change"
+    | "structural-change"
+    | "object-change";
+  linkedRevisionIds?: string[];
+  predecessorSuggestionId?: string;
+  label: string;
+  status: "active" | "accepted" | "rejected" | "detached";
+  actionability: "actionable" | "preserve-only";
+  storyTarget?: EditorStoryTarget;
+  importedRevisionForm?:
+    | "run-insertion"
+    | "run-deletion"
+    | "paragraph-insertion"
+    | "paragraph-deletion";
+  anchor: EditorAnchorProjection;
+  anchorLabel: string;
+  createdAt: string;
+  authorId: string;
+  warningCount: number;
+  canAccept: boolean;
+  canReject: boolean;
+  preserveOnlyReason?: string;
+  excerpt?: string;
+  detail?: string;
+}
+
+export interface TrackedChangesSnapshot {
+  pendingChangeIds: string[];
+  acceptedChangeIds: string[];
+  rejectedChangeIds: string[];
+  detachedChangeIds: string[];
+  actionableChangeIds: string[];
+  preserveOnlyChangeIds: string[];
+  totalCount: number;
+  revisions: TrackedChangeEntrySnapshot[];
+}
+
+export interface SuggestionEntrySnapshot {
+  suggestionId: string;
+  kind:
+    | "insertion"
+    | "deletion"
+    | "replacement"
+    | "formatting-change"
+    | "paragraph-property-change"
+    | "structural-change"
+    | "object-change";
+  source: "runtime" | "import";
+  status: "active" | "accepted" | "rejected" | "detached";
+  actionability: "actionable" | "preserve-only";
+  storyTarget: EditorStoryTarget;
+  anchor: EditorAnchorProjection;
+  anchorLabel: string;
+  createdAt: string;
+  authorId: string;
+  changeIds: string[];
+  editable: boolean;
+  canAccept: boolean;
+  canReject: boolean;
+  isReplacement: boolean;
+  preserveOnlyReason?: string;
+  excerpt?: string;
+  detail?: string;
+}
+
+export interface SuggestionsSnapshot {
+  totalCount: number;
+  actionableSuggestionIds: string[];
+  preserveOnlySuggestionIds: string[];
+  activeSuggestionIds: string[];
+  acceptedSuggestionIds: string[];
+  rejectedSuggestionIds: string[];
+  detachedSuggestionIds: string[];
+  suggestions: SuggestionEntrySnapshot[];
+}
+
+export type FormattingAlignment = "left" | "center" | "right" | "justify";
+
+export interface FormattingBreadcrumbItem {
+  kind: "table" | "table_row" | "table_cell" | "paragraph" | "sdt_block" | "opaque_block";
+  label: string;
+  from: number;
+  to: number;
+}
+
+export interface FormattingStateSnapshot {
+  bold: boolean;
+  italic: boolean;
+  underline: boolean;
+  strikethrough: boolean;
+  superscript: boolean;
+  subscript: boolean;
+  fontFamily?: string;
+  fontSize?: number;
+  textColor?: string;
+  highlightColor?: string | null;
+  alignment?: FormattingAlignment;
+  paragraphStyleId?: string;
+  breadcrumb: FormattingBreadcrumbItem[];
+}
+
+export interface SearchOptions {
+  matchCase?: boolean;
+  wholeWord?: boolean;
+  limit?: number;
+}
+
+export interface SearchResultSnapshot {
+  resultId: string;
+  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 type DocumentLocationSource =
+  | { kind: "selection" }
+  | { kind: "search"; resultId?: string; query?: string }
+  | { kind: "workflow"; markupId?: string; candidateId?: string }
+  | { kind: "navigation" };
+
+export interface DocumentLocationSnapshot {
+  locationId: string;
+  anchor: EditorAnchorProjection;
+  storyTarget?: EditorStoryTarget;
+  sectionIndex?: number;
+  pageIndex?: number;
+  headingId?: string;
+  headingPath?: string[];
+  bookmarkName?: string;
+  source: DocumentLocationSource;
+}
+
+export type RestorePointCheckpointType = "selection" | "search-result" | "workflow-item" | "manual";
+
+export interface RestorePointSnapshot {
+  restorePointId: string;
+  location: DocumentLocationSnapshot;
+  revisionToken: string;
+  createdAt: string;
+  checkpointType: RestorePointCheckpointType;
+}
+
+export interface RestoreResult {
+  status: "restored" | "remapped" | "detached" | "blocked";
+  selection?: SelectionSnapshot;
+  location?: DocumentLocationSnapshot;
+  reasons?: string[];
+}
+
+export interface DocumentOutlineHeadingSnapshot extends DocumentHeadingSnapshot {
+  parentHeadingIds: string[];
+}
+
+export interface DocumentOutlineSnapshot {
+  activeHeadingId?: string;
+  headings: DocumentOutlineHeadingSnapshot[];
+}
+
+export interface TocEntrySnapshot {
+  tocEntryId: string;
+  level: number;
+  text: string;
+  pageIndex?: number;
+  anchor?: EditorAnchorProjection;
+  bookmarkName?: string;
+  headingId?: string;
+}
+
+export interface TocSnapshot {
+  status: "current" | "stale" | "missing";
+  sourceFieldIndex?: number;
+  instruction?: string;
+  entries: TocEntrySnapshot[];
+}
+
+export interface DocumentSectionSnapshot {
+  sectionId: string;
+  sectionIndex: number;
+  pageRange: { start: number; end: number };
+  headingPath: string[];
+  primaryHeadingId?: string;
+  primaryHeadingText?: string;
+  layout?: PageLayoutSnapshot;
+  anchor: EditorAnchorProjection;
+  storyTargets: EditorStoryTarget[];
+}
+
+export type SnapshotRefreshInvalidateTarget =
+  | "selection"
+  | "render"
+  | "navigation"
+  | "fields"
+  | "comments"
+  | "trackedChanges"
+  | "workflowScope"
+  | "workflowMarkup"
+  | "reviewWork"
+  | "contextAnalytics"
+  | "chunks"
+  | "outline"
+  | "toc"
+  | "sections"
+  | "locations"
+  | "textStream";
+
+export type SnapshotRefreshStaleTarget =
+  | "search_results"
+  | "anchors"
+  | "selection_only"
+  | "none";
+
+export type SnapshotRefreshChangeKind =
+  | "selection"
+  | "content"
+  | "review"
+  | "workflow"
+  | "structure"
+  | "checkpoint";
+
+export interface SnapshotRefreshHints {
+  invalidate: SnapshotRefreshInvalidateTarget[];
+  staleTargets: SnapshotRefreshStaleTarget[];
+  changeKinds: SnapshotRefreshChangeKind[];
+  checkpointType?: "session" | "snapshot" | "export";
+}
+
+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 {
+  rows: number;
+  columns: number;
+}
+
+export interface InsertImageOptions {
+  data: Uint8Array;
+  mimeType: string;
+  width?: number;
+  height?: number;
+  altText?: string;
+}
+
+export type SurfaceTextMark =
+  | "bold"
+  | "italic"
+  | "underline"
+  | "strikethrough"
+  | "doubleStrikethrough"
+  | "superscript"
+  | "subscript"
+  | "vanish"
+  | "emboss"
+  | "imprint"
+  | "shadow"
+  | "smallCaps"
+  | "allCaps";
+
+export type SurfaceInlineSegment =
+  | {
+      segmentId: string;
+      kind: "text";
+      from: number;
+      to: number;
+      text: string;
+      marks?: SurfaceTextMark[];
+      markAttrs?: {
+        backgroundColor?: string;
+        charSpacing?: number;
+        kerning?: number;
+        textFill?: string;
+        fontFamily?: string;
+        fontSize?: number;
+        textColor?: string;
+      };
+      hyperlinkHref?: string;
+    }
+  | {
+      segmentId: string;
+      kind: "tab" | "hard_break";
+      from: number;
+      to: number;
+      hyperlinkHref?: string;
+    }
+  | {
+      segmentId: string;
+      kind: "image";
+      from: number;
+      to: number;
+      mediaId: string;
+      altText?: string;
+      state: "editable" | "missing";
+      display?: "inline" | "floating";
+      detail?: string;
+    }
+  | {
+      segmentId: string;
+      kind: "opaque_inline";
+      from: number;
+      to: number;
+      fragmentId: string;
+      warningId: string;
+      label: string;
+      detail: string;
+      featureKey?: string;
+      blockedReasonCode?: "workflow_preserve_only" | "workflow_blocked_import";
+      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 {
+  gridSpan: number;
+  verticalMerge: "restart" | "continue" | null;
+  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[];
+  gridBefore?: number;
+  gridAfter?: number;
+  height?: number;
+  heightRule?: "auto" | "atLeast" | "exact";
+  isHeader?: boolean;
+}
+
+export interface ResolvedNumberingGeometrySnapshot {
+  markerJustification?: "left" | "center" | "right" | "both" | "distribute";
+  spacing?: { before?: number; after?: number; line?: number; lineRule?: string };
+  indentation?: { left?: number; right?: number; firstLine?: number; hanging?: number };
+  tabStops?: Array<{ pos: number; val?: string; leader?: string }>;
+  markerLane?: { start: number; width: number; textStart: number };
+  textColumn?: { start: number; right?: number; firstLine?: number; hanging?: number };
+}
+
+export interface ResolvedNumberingSnapshot {
+  level: number;
+  format: string;
+  text?: string;
+  startAt: number;
+  paragraphStyleId?: string;
+  isLegalNumbering?: boolean;
+  suffix?: "tab" | "space" | "nothing";
+  geometry: ResolvedNumberingGeometrySnapshot;
+}
+
+export type SurfaceBlockSnapshot =
+  | {
+      blockId: string;
+      kind: "paragraph";
+      from: number;
+      to: number;
+      styleId?: string;
+      numbering?: {
+        numberingInstanceId: string;
+        level: number;
+      };
+      numberingPrefix?: string;
+      numberingSuffix?: "tab" | "space" | "nothing";
+      resolvedNumbering?: ResolvedNumberingSnapshot;
+      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 };
+      tabStops?: Array<{ pos: number; val?: string; leader?: string }>;
+      keepNext?: boolean;
+      keepLines?: boolean;
+      pageBreakBefore?: boolean;
+      outlineLevel?: number;
+      bidi?: boolean;
+      suppressLineNumbers?: boolean;
+      segments: SurfaceInlineSegment[];
+    }
+  | {
+      blockId: string;
+      kind: "table";
+      from: number;
+      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[];
+    }
+  | {
+      blockId: string;
+      kind: "sdt_block";
+      from: number;
+      to: number;
+      sdtType?: string;
+      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[];
+    }
+  | {
+      blockId: string;
+      kind: "opaque_block";
+      from: number;
+      to: number;
+      fragmentId: string;
+      warningId: string;
+      label: string;
+      detail: string;
+      featureKey?: string;
+      blockedReasonCode?: "workflow_preserve_only" | "workflow_blocked_import";
+      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 =
+  | "unsupported_ooxml_preserved"
+  | "unsupported_ooxml_locked"
+  | "import_normalized"
+  | "export_roundtrip_risk"
+  | "comment_anchor_detached"
+  | "revision_anchor_detached"
+  | "large_document_degraded"
+  | "font_substitution"
+  | "image_missing";
+
+export interface EditorWarning {
+  warningId: string;
+  code: EditorWarningCode;
+  severity: "info" | "warning";
+  message: string;
+  source:
+    | "import"
+    | "runtime"
+    | "review"
+    | "preservation"
+    | "validation"
+    | "export";
+  affectedAnchor?: EditorAnchorProjection;
+  featureEntryId?: string;
+  details?: Record<string, unknown>;
+}
+
+export type EditorErrorCode =
+  | "import_failed"
+  | "export_failed"
+  | "package_corrupt"
+  | "validation_failed"
+  | "datastore_failed"
+  | "internal_invariant";
+
+export interface EditorError {
+  errorId: string;
+  code: EditorErrorCode;
+  message: string;
+  isFatal: boolean;
+  source: "import" | "runtime" | "validation" | "datastore" | "host" | "export";
+  details?: Record<string, unknown>;
+}
+
+export type CompatibilityFeatureClass =
+  | "supported-roundtrip"
+  | "preserve-only"
+  | "unsupported-fatal";
+
+export interface CompatibilityFeatureEntry {
+  featureEntryId: string;
+  featureKey: string;
+  featureClass: CompatibilityFeatureClass;
+  message: string;
+  affectedAnchor?: EditorAnchorProjection;
+  details?: Record<string, unknown>;
+}
+
+export interface CompatibilityReport {
+  reportVersion: "compatibility-report/1";
+  generatedAt: string;
+  blockExport: boolean;
+  featureEntries: CompatibilityFeatureEntry[];
+  warnings: EditorWarning[];
+  errors: EditorError[];
+}
+
+export interface CompatibilityPanelSnapshot {
+  blockExport: boolean;
+  blockExportReasons: string[];
+  warningCount: number;
+  errorCount: number;
+  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 TableOperationCapabilitySnapshot {
+  enabled: boolean;
+  reason?: string;
+}
+
+export interface TableStructureContextSnapshot {
+  tableBlockIndex: number;
+  currentStyleId?: string | null;
+  selectionKind: "text" | "cell";
+  rowCount: number;
+  columnCount: number;
+  selectedCellCount: number;
+  isSimpleTable: boolean;
+  currentCell: {
+    rowIndex: number;
+    columnIndex: number;
+    isHeader: boolean;
+  };
+  operations: {
+    setTableStyle: TableOperationCapabilitySnapshot;
+    setCellBackground: TableOperationCapabilitySnapshot;
+    addRowBefore: TableOperationCapabilitySnapshot;
+    addRowAfter: TableOperationCapabilitySnapshot;
+    deleteRow: TableOperationCapabilitySnapshot;
+    addColumnBefore: TableOperationCapabilitySnapshot;
+    addColumnAfter: TableOperationCapabilitySnapshot;
+    deleteColumn: TableOperationCapabilitySnapshot;
+    mergeCells: TableOperationCapabilitySnapshot;
+    splitCell: TableOperationCapabilitySnapshot;
+    deleteTable: TableOperationCapabilitySnapshot;
+  };
+}
+
+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;
+  readOnly: boolean;
+}
+
+export interface RuntimeRenderSnapshot {
+  documentId: string;
+  sessionId: string;
+  sourceLabel?: string;
+  revisionToken: string;
+  isReady: boolean;
+  isDirty: boolean;
+  readOnly: boolean;
+  documentMode: DocumentMode;
+  selection: SelectionSnapshot;
+  activeStory: EditorStoryTarget;
+  pageLayout?: PageLayoutSnapshot;
+  documentStats: DocumentStats;
+  comments: CommentSidebarSnapshot;
+  trackedChanges: TrackedChangesSnapshot;
+  compatibility: CompatibilityPanelSnapshot;
+  warnings: EditorWarning[];
+  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"];
+  workflowMetadata?: WorkflowMetadataSnapshot;
+}
+
+export interface PersistedEditorSnapshot {
+  snapshotVersion: RuntimePersistedEditorSnapshot["snapshotVersion"];
+  schemaVersion: RuntimePersistedEditorSnapshot["schemaVersion"];
+  documentId: string;
+  docId: string;
+  createdAt: string;
+  updatedAt: string;
+  savedAt: string;
+  editorBuild: string;
+  canonicalDocument: RuntimePersistedEditorSnapshot["canonicalDocument"];
+  compatibility: CompatibilityReport;
+  warningLog: EditorWarning[];
+  protectionSnapshot?: ProtectionSnapshot;
+  sourcePackage?: RuntimePersistedEditorSnapshot["sourcePackage"];
+  workflowMetadata?: WorkflowMetadataSnapshot;
+}
+
+export interface AddCommentParams {
+  anchor?: EditorAnchorProjection;
+  body?: string;
+  authorId?: string;
+}
+
+export interface ExportDocxOptions {
+  fileName?: string;
+  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";
+  metadataRefs?: string[];
+}
+
+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 type WorkflowMetadataPersistence =
+  | "runtime-only"
+  | "session"
+  | "document-metadata";
+
+export interface WorkflowMetadataDefinition {
+  metadataId: string;
+  kind: string;
+  label: string;
+  color?: string;
+  icon?: string;
+  dataSchema?: Record<string, unknown>;
+  persistence: WorkflowMetadataPersistence;
+}
+
+export interface WorkflowMetadataEntry {
+  entryId: string;
+  metadataId: string;
+  anchor: EditorAnchorProjection;
+  storyTarget?: EditorStoryTarget;
+  value?: Record<string, unknown>;
+  scopeId?: string;
+  workItemId?: string;
+}
+
+export interface WorkflowMetadataSnapshot {
+  definitions: WorkflowMetadataDefinition[];
+  entries: WorkflowMetadataEntry[];
+}
+
+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"
+    | "suggesting_unsupported";
+  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 type EffectiveSelectionMode = WorkflowScopeMode | "blocked";
+
+export interface InteractionGuardSnapshot {
+  effectiveMode: EffectiveSelectionMode;
+  matchedScopeId?: string;
+  matchedScopeMode?: WorkflowScopeMode;
+  targetAccess?: "direct-edit" | "suggest" | "comment-only" | "view-only" | "blocked";
+  commandCapabilities?: Array<{
+    family: "text" | "formatting" | "structure";
+    supported: boolean;
+    blockedReasons: WorkflowBlockedCommandReason[];
+  }>;
+  disabledReason?: string;
+  blockedReasons: WorkflowBlockedCommandReason[];
+}
+
+export type WorkflowMarkupKind =
+  | "highlight"
+  | "metadata"
+  | "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 WorkflowMetadataMarkup extends WorkflowMarkupBase {
+  kind: "metadata";
+  entryId: string;
+  metadataId: string;
+  color?: string;
+  icon?: string;
+  persistence: WorkflowMetadataPersistence;
+  value?: Record<string, unknown>;
+  scopeId?: string;
+  workItemId?: 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
+  | WorkflowMetadataMarkup
+  | WorkflowCommentMarkup
+  | WorkflowRevisionMarkup
+  | WorkflowFieldMarkup
+  | WorkflowProtectedRangeMarkup
+  | WorkflowOpaqueFragmentMarkup;
+
+export interface WorkflowMarkupSnapshot {
+  totalCount: number;
+  items: WorkflowMarkupItem[];
+  highlights: WorkflowHighlightMarkup[];
+  metadata: WorkflowMetadataMarkup[];
+  comments: WorkflowCommentMarkup[];
+  revisions: WorkflowRevisionMarkup[];
+  fields: WorkflowFieldMarkup[];
+  protectedRanges: WorkflowProtectedRangeMarkup[];
+  opaqueFragments: WorkflowOpaqueFragmentMarkup[];
+}
+
+export type HostAnnotationKind =
+  | "note"
+  | "scope_hint"
+  | "readonly_marker"
+  | "suggestion"
+  | "warning";
+
+export interface HostAnnotationItem {
+  annotationId: string;
+  kind: HostAnnotationKind;
+  label: string;
+  anchor: EditorAnchorProjection;
+  storyTarget?: EditorStoryTarget;
+  detail?: string;
+  scopeMode?: WorkflowScopeMode;
+  severity?: "low" | "medium" | "high";
+  workItemId?: string;
+  provenance: "host";
+}
+
+export interface HostAnnotationOverlay {
+  overlayVersion: "host-annotation-overlay/1";
+  annotations: HostAnnotationItem[];
+}
+
+export interface HostAnnotationSnapshot {
+  totalCount: number;
+  annotations: HostAnnotationItem[];
+}
+
+export type ReviewQueueItemKind = "comment" | "change" | "section_mark";
+
+export interface ReviewQueueItem {
+  itemId: string;
+  kind: ReviewQueueItemKind;
+  label: string;
+  storyTarget?: EditorStoryTarget;
+  anchor: EditorAnchorProjection;
+  sectionIndex?: number;
+  pageIndex?: number;
+  status: "open" | "resolved";
+  actionable: boolean;
+}
+
+export interface ReviewQueueSnapshot {
+  totalCount: number;
+  openCount: number;
+  activeIndex: number;
+  items: ReviewQueueItem[];
+}
+
+export interface DocumentTextToken {
+  tokenId: string;
+  storyTarget?: EditorStoryTarget;
+  blockId: string;
+  blockKind: SurfaceBlockSnapshot["kind"];
+  segmentId?: string;
+  kind: SurfaceInlineSegment["kind"] | "paragraph_boundary" | "table_boundary";
+  from: number;
+  to: number;
+  text?: string;
+  marks?: SurfaceTextMark[];
+  pageIndex?: number;
+  sectionIndex?: number;
+}
+
+export interface StoryTextStreamSnapshot {
+  target: EditorStoryTarget;
+  label: string;
+  storySize: number;
+  tokens: DocumentTextToken[];
+}
+
+export type DocumentChunkKind = "retrieval" | "action" | "workflow";
+
+export interface DocumentChunkSnapshot {
+  chunkId: string;
+  kind: DocumentChunkKind;
+  label: string;
+  text: string;
+  storyTarget?: EditorStoryTarget;
+  anchor: EditorAnchorProjection;
+  sectionIndex?: number;
+  pageRange?: { start: number; end: number };
+  headingPath: string[];
+  blockRefs: Array<{ blockId: string; kind: string }>;
+  source:
+    | { type: "surface" }
+    | { type: "search"; query: string }
+    | { type: "workflow"; candidateId?: string; markupId?: string };
+  cautionFlags: Array<
+    | "contains_table"
+    | "contains_protected_range"
+    | "contains_preserve_only"
+    | "contains_detached_anchor"
+  >;
+}
+
+export interface ReviewWorkItemSnapshot {
+  workId: string;
+  kind: "comment" | "revision" | "protected_range" | "opaque_fragment";
+  label: string;
+  excerpt: string;
+  anchor: EditorAnchorProjection;
+  storyTarget?: EditorStoryTarget;
+  sectionIndex?: number;
+  pageIndex?: number;
+}
+
+export interface ReviewWorkSnapshot {
+  openCommentCount: number;
+  actionableRevisionCount: number;
+  items: ReviewWorkItemSnapshot[];
+}
+
+export type RuntimeContextAnalyticsScopeKind =
+  | "selection"
+  | "workflow_scope"
+  | "work_item"
+  | "document";
+
+export interface RuntimeContextAnalyticsQuery {
+  scopeKind?: RuntimeContextAnalyticsScopeKind;
+  scopeId?: string;
+  workItemId?: string;
+}
+
+export interface RuntimeContextAnalyticsBadge {
+  key: string;
+  label: string;
+  value?: string | number;
+  tone?: "neutral" | "accent" | "warning" | "danger" | "success";
+  priority?: 1 | 2 | 3;
+}
+
+export interface RuntimeContextAnalyticsActionHint {
+  key: string;
+  label: string;
+  kind: "next_step" | "blocker" | "warning" | "approval";
+}
+
+export interface RuntimeContextAnalyticsCounts {
+  tasksRemaining?: number;
+  unresolvedComments?: number;
+  pendingRevisions?: number;
+  pendingSuggestions?: number;
+  blockedCommands?: number;
+  approvalsRemaining?: number;
+  overdueItems?: number;
+  warnings?: number;
+  errors?: number;
+  openWorkItems?: number;
+  exportBlockers?: number;
+}
+
+export interface RuntimeContextAnalyticsState {
+  effectiveMode?: EffectiveSelectionMode;
+  isBlocked?: boolean;
+  disabledReason?: string;
+  completionState?: "not_started" | "in_progress" | "ready" | "done";
+  exportReadiness?: "ready" | "warning" | "blocked";
+  lastTouchedAt?: string;
+}
+
+export type RuntimeContextAnalyticsUnavailableField =
+  | "tasksRemaining"
+  | "approvalsRemaining"
+  | "overdueItems"
+  | "tags"
+  | "assignee"
+  | "dueDate"
+  | "lastTouchedAt";
+
+export interface RuntimeContextAnalyticsProvenance {
+  kind: "runtime-derived";
+  derivedFrom: Array<
+    | "render"
+    | "workflowScope"
+    | "interactionGuard"
+    | "workflowMarkup"
+    | "reviewWork"
+    | "warnings"
+    | "compatibility"
+  >;
+  unavailable: RuntimeContextAnalyticsUnavailableField[];
+}
+
+export interface RuntimeContextAnalyticsSnapshot {
+  scopeKind: RuntimeContextAnalyticsScopeKind;
+  scopeId?: string;
+  workItemId?: string | null;
+  badges: RuntimeContextAnalyticsBadge[];
+  nextActions: RuntimeContextAnalyticsActionHint[];
+  counts: RuntimeContextAnalyticsCounts;
+  state: RuntimeContextAnalyticsState;
+  provenance: RuntimeContextAnalyticsProvenance;
+}
+
+export interface WorkflowCandidateRangeOptions {
+  kinds?: WorkflowMarkupKind[];
+  includeDetached?: boolean;
+  source?: WorkflowCandidateRange["source"];
+}
+
+export type AutosaveState =
+  | { status: "idle" }
+  | { status: "saving" }
+  | { status: "saved"; savedAt: string }
+  | { status: "error"; error: EditorError };
+
+export interface AutosaveConfig {
+  enabled?: boolean;
+  debounceMs?: number;
+}
+
+export type WordReviewEditorEvent =
+  | {
+      type: "ready";
+      documentId: string;
+      sessionId: string;
+      source: "docx" | "session" | "snapshot";
+      stats: DocumentStats;
+      compatibility: CompatibilityReport;
+      comments: CommentSidebarSnapshot;
+      trackedChanges: TrackedChangesSnapshot;
+    }
+  | {
+      type: "dirty_changed";
+      documentId: string;
+      isDirty: boolean;
+    }
+  | {
+      type: "selection_changed";
+      documentId: string;
+      selection: SelectionSnapshot;
+    }
+  | {
+      type: "comment_added";
+      documentId: string;
+      commentId: string;
+      anchor: EditorAnchorProjection;
+    }
+  | {
+      type: "comment_resolved";
+      documentId: string;
+      commentId: string;
+    }
+  | {
+      type: "change_accepted";
+      documentId: string;
+      changeId: string;
+    }
+  | {
+      type: "change_rejected";
+      documentId: string;
+      changeId: string;
+    }
+  | {
+      type: "story_changed";
+      documentId: string;
+      activeStory: EditorStoryTarget;
+    }
+  | {
+      type: "warning_added";
+      documentId: string;
+      warning: EditorWarning;
+    }
+  | {
+      type: "warning_cleared";
+      documentId: string;
+      warningId: string;
+      code: EditorWarningCode;
+    }
+  | {
+      type: "error";
+      documentId: string;
+      error: EditorError;
+    }
+  | {
+      type: "autosave_state";
+      documentId: string;
+      state: AutosaveState;
+    }
+  | {
+      type: "snapshot_saved";
+      documentId: string;
+      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: "workflow_metadata_changed";
+      documentId: string;
+      snapshot: WorkflowMetadataSnapshot;
+    }
+  | {
+      type: "host_annotation_overlay_changed";
+      documentId: string;
+      snapshot: HostAnnotationSnapshot;
+    }
+  | {
+      type: "context_analytics_changed";
+      documentId: string;
+      snapshot: RuntimeContextAnalyticsSnapshot | null;
+    }
+  | {
+      type: "change_authored";
+      documentId: string;
+      changeId: string;
+      kind: "insertion" | "deletion";
+    }
+  | {
+      type: "suggestion_authored";
+      documentId: string;
+      suggestionId: string;
+      changeIds: string[];
+      suggestionKind: SuggestionEntrySnapshot["kind"];
+      storyTarget: EditorStoryTarget;
+      anchor: EditorAnchorProjection;
+      isReplacement: boolean;
+    }
+  | {
+      type: "suggestion_updated";
+      documentId: string;
+      suggestionId: string;
+      changeIds: string[];
+      suggestionKind: SuggestionEntrySnapshot["kind"];
+      status: SuggestionEntrySnapshot["status"];
+      storyTarget: EditorStoryTarget;
+      anchor: EditorAnchorProjection;
+    }
+  | {
+      type: "command_blocked";
+      documentId: string;
+      command: string;
+      reasons: WorkflowBlockedCommandReason[];
+    };
+
+export interface LoadResult {
+  source?: ExternalDocumentSource;
+}
+
+export interface SaveSnapshotParams {
+  documentId: string;
+  snapshot: PersistedEditorSnapshot;
+  isAutosave: boolean;
+}
+
+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;
+}
+
+export interface SaveExportResult {
+  savedAt: string;
+}
+
+export interface EditorTelemetryEvent {
+  type: string;
+  documentId: string;
+  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: LoadRequest): Promise<LoadResult>;
+  saveSnapshot(params: SaveSnapshotParams): Promise<SaveSnapshotResult>;
+  saveExport?(params: SaveExportParams): Promise<SaveExportResult>;
+  logEvent?(event: EditorTelemetryEvent): void;
+}
+
+export interface WordReviewEditorRef {
+  focus(): void;
+  blur(): void;
+  undo(): void;
+  redo(): void;
+  addComment(params: AddCommentParams): string;
+  openComment(commentId: string): void;
+  resolveComment(commentId: string): void;
+  reopenComment(commentId: string): void;
+  addCommentReply(commentId: string, body: string): void;
+  editCommentBody(commentId: string, body: string): void;
+  deleteComment(commentId: string): void;
+  acceptChange(changeId: string): void;
+  rejectChange(changeId: string): void;
+  acceptAllChanges(): void;
+  rejectAllChanges(): void;
+  exportDocx(options?: ExportDocxOptions): Promise<ExportResult>;
+  getSessionState(): EditorSessionState;
+  getSnapshot(): PersistedEditorSnapshot;
+  getRenderSnapshot(): RuntimeRenderSnapshot;
+  getCompatibilityReport(): CompatibilityReport;
+  getWarnings(): EditorWarning[];
+  getCommentSidebarSnapshot(): CommentSidebarSnapshot;
+  getTrackedChangesSnapshot(): TrackedChangesSnapshot;
+  getSuggestionsSnapshot(): SuggestionsSnapshot;
+  getComments(): CommentSidebarSnapshot;
+  getTrackedChanges(): TrackedChangesSnapshot;
+  isDirty(): boolean;
+  getFormattingState(): FormattingStateSnapshot;
+  getStyleCatalog(): StyleCatalogSnapshot;
+  replaceText(text: string, target?: EditorAnchorProjection): void;
+  toggleBulletedList(): void;
+  toggleNumberedList(): void;
+  toggleBold(): void;
+  toggleItalic(): void;
+  toggleUnderline(): void;
+  toggleStrikethrough(): void;
+  toggleSuperscript(): void;
+  toggleSubscript(): void;
+  setFontFamily(fontFamily: string | null): void;
+  setFontSize(size: number | null): void;
+  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;
+  restartNumbering(): void;
+  continueNumbering(): void;
+  insertPageBreak(): void;
+  insertTable(options: InsertTableOptions): void;
+  insertImage(options: InsertImageOptions): void;
+  addRowBefore(): void;
+  addRowAfter(): void;
+  addColumnBefore(): void;
+  addColumnAfter(): void;
+  deleteRow(): void;
+  deleteColumn(): void;
+  deleteTable(): void;
+  mergeCells(): void;
+  splitCell(): void;
+  setCellBackground(color: string): void;
+  search(query: string, options?: SearchOptions): SearchResultSnapshot[];
+  clearSearch(): void;
+  setSelection(selection: SelectionSnapshot | null): void;
+  scrollToRevision(revisionId: string): void;
+  scrollToComment(commentId: string): void;
+  openStory(target: EditorStoryTarget): void;
+  closeStory(): void;
+  getPageLayoutSnapshot(): PageLayoutSnapshot | null;
+  getDocumentNavigationSnapshot(): DocumentNavigationSnapshot;
+  getCurrentLocation(): DocumentLocationSnapshot | null;
+  getLocationForSelection(selection: SelectionSnapshot): DocumentLocationSnapshot | null;
+  getLocationForAnchor(
+    anchor: EditorAnchorProjection,
+    storyTarget?: EditorStoryTarget,
+  ): DocumentLocationSnapshot | null;
+  captureRestorePoint(
+    input?: SelectionSnapshot | EditorAnchorProjection,
+  ): RestorePointSnapshot | null;
+  restoreToPoint(
+    point: RestorePointSnapshot,
+    options?: { behavior?: "exact" | "semantic"; scroll?: boolean },
+  ): RestoreResult;
+  getOutlineSnapshot(): DocumentOutlineSnapshot;
+  getTocSnapshot(): TocSnapshot | null;
+  getSections(): DocumentSectionSnapshot[];
+  getSectionSnapshot(input: {
+    sectionIndex?: number;
+    headingId?: string;
+    bookmarkName?: string;
+  }): DocumentSectionSnapshot | null;
+  describeEventImpact(event: WordReviewEditorEvent): SnapshotRefreshHints;
+  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;
+  setWorkflowMetadataDefinitions(definitions: WorkflowMetadataDefinition[]): void;
+  clearWorkflowMetadataDefinitions(): void;
+  setWorkflowMetadataEntries(entries: WorkflowMetadataEntry[]): void;
+  clearWorkflowMetadataEntries(): void;
+  getWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot;
+  setHostAnnotationOverlay(overlay: HostAnnotationOverlay): void;
+  clearHostAnnotationOverlay(): void;
+  getHostAnnotationSnapshot(): HostAnnotationSnapshot;
+  getReviewQueueSnapshot(): ReviewQueueSnapshot;
+  goToNextReviewItem(): ReviewQueueItem | null;
+  goToPreviousReviewItem(): ReviewQueueItem | null;
+  markSectionForReview(input?: { sectionIndex?: number; label?: string }): string | null;
+  clearSectionReviewMark(annotationId: string): void;
+  getWorkflowCandidateRanges(options?: WorkflowCandidateRangeOptions): WorkflowCandidateRange[];
+  replaceWorkflowMarkupText(markupId: string, text: string): void;
+  getRuntimeContextAnalytics(
+    query?: RuntimeContextAnalyticsQuery,
+  ): RuntimeContextAnalyticsSnapshot | null;
+}
+
+export type WordReviewEditorChromePreset =
+  | "selection"
+  | "simple"
+  | "advanced"
+  | "review";
+
+export interface WordReviewEditorChromeOptions {
+  showReviewQueueBar: boolean;
+  showSectionTagAction: boolean;
+  showReviewRail: boolean;
+}
+
+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";
+  suggestionsEnabled?: boolean;
+  chromePreset?: WordReviewEditorChromePreset;
+  chromeOptions?: Partial<WordReviewEditorChromeOptions>;
+  markupDisplay?: "clean" | "simple" | "all";
+  showUnsupportedObjectPreviews?: boolean;
+  showReviewPanel?: boolean;
+  chromeVisibility?: Partial<WordReviewEditorChromeVisibility>;
+  hostAdapter?: EditorHostAdapter;
+  datastore?: EditorDatastoreAdapter;
+  autosave?: AutosaveConfig;
+  onEvent?: (event: WordReviewEditorEvent) => void;
+  onWarning?: (warning: EditorWarning) => void;
+  onError?: (error: EditorError) => void;
+}
+
+export interface WordReviewEditorChromeVisibility {
+  toolbar: boolean;
+  alerts: boolean;
+  selectionOverlay: boolean;
+  contextToolbars: boolean;
+  contextAnalytics: boolean;
+  pageChrome: boolean;
+  statusBar: boolean;
+  reviewRail: boolean;
+}