@beyondwork/docx-react-component 1.0.28 → 1.0.29

package/src/api/public-types.ts

@@ -1,1421 +0,0 @@
-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;
-  isActive: boolean;
-  resolvedAt?: string;
-  resolvedBy?: string;
-}
-
-export interface TrackedChangeEntrySnapshot {
-  revisionId: string;
-  kind: "insertion" | "deletion" | "formatting" | "move" | "property-change";
-  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 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 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;
-      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 type SurfaceBlockSnapshot =
-  | {
-      blockId: string;
-      kind: "paragraph";
-      from: number;
-      to: number;
-      styleId?: string;
-      numbering?: {
-        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 };
-      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;
-      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 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"];
-}
-
-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"];
-}
-
-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";
-}
-
-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"
-    | "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;
-  disabledReason?: string;
-  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 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 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: "host_annotation_overlay_changed";
-      documentId: string;
-      snapshot: HostAnnotationSnapshot;
-    }
-  | {
-      type: "change_authored";
-      documentId: string;
-      changeId: string;
-      kind: "insertion" | "deletion";
-    }
-  | {
-      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;
-  getComments(): CommentSidebarSnapshot;
-  getTrackedChanges(): TrackedChangesSnapshot;
-  isDirty(): boolean;
-  getFormattingState(): FormattingStateSnapshot;
-  getStyleCatalog(): StyleCatalogSnapshot;
-  replaceText(text: string, target?: EditorAnchorProjection): 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;
-  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;
-  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;
-  setHostAnnotationOverlay(overlay: HostAnnotationOverlay): void;
-  clearHostAnnotationOverlay(): void;
-  getHostAnnotationSnapshot(): HostAnnotationSnapshot;
-  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";
-  suggestionsEnabled?: boolean;
-  markupDisplay?: "clean" | "simple" | "all";
-  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;
-  pageChrome: boolean;
-  statusBar: boolean;
-  reviewRail: boolean;
-}