revise 1.0.0 → 2.0.0

package/index.d.ts

@@ -0,0 +1,929 @@
+import * as React from "react";
+// The canonical tool contract, shared verbatim with the backend entry: the
+// browser surface returns the same envelopes and throws the same error.
+import type {
+  ReviseSuggestionDecision,
+  ReviseToolInput,
+  ReviseToolName,
+  ReviseToolResponse,
+  ReviseToolResult,
+} from "./serverToolContract.js";
+export type * from "./serverToolContract.js";
+
+export declare class ReviseToolError<Name extends string = string> extends Error {
+  readonly failure: import("./serverToolContract.js").ReviseToolFailure<Name>;
+  readonly callId: string;
+  readonly tool: Name;
+  readonly code: string;
+  constructor(failure: import("./serverToolContract.js").ReviseToolFailure<Name>);
+}
+
+/** The version of this package, at runtime. Include it when you escalate. */
+export declare const REVISE_SDK_VERSION: string;
+
+/** The commit this bundle was built from. Empty in a development build. */
+export declare const REVISE_SDK_BUILD: string;
+
+export interface ReviseDocument {
+  type: "doc";
+  children: unknown[];
+  [key: string]: unknown;
+}
+
+export interface EditorUserIdentity {
+  id?: string;
+  name?: string;
+  email?: string;
+  image?: string;
+  /** Caret and presence color. Any CSS color. Without one, a stable color
+   * is derived from the id. */
+  color?: string;
+}
+
+export interface ReviseAgentMessage {
+  role: string;
+  content: string;
+  timestamp?: number;
+  toolName?: string;
+  incomplete?: boolean;
+  [key: string]: unknown;
+}
+
+export interface ReviseAgentTurnRequest {
+  prompt: string;
+  currentDocument: ReviseDocument;
+  currentTurn: number;
+  config: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface ReviseAgentStreamEvent {
+  type: "text" | "tool_call" | "tool_result" | "tool_start" | "usage" | "error" | "done" | "request_mode" | "web_search" | "reasoning" | "history_repair";
+  data: any;
+}
+
+export type ReviseAgentTurnStream = (
+  request: ReviseAgentTurnRequest,
+) => AsyncGenerator<ReviseAgentStreamEvent, void, unknown>;
+
+export interface ReviseAgentConfig {
+  /** Display name for comments and tracked changes. Defaults to Revise Agent. */
+  name?: string;
+  baseUrl?: string;
+  token?: string;
+  conversationId?: string;
+  provider?: string;
+  model?: string;
+  turnStream?: ReviseAgentTurnStream;
+  disableMetrics?: boolean;
+}
+
+export interface ReviseAgentEvent {
+  state: "idle" | "streaming" | "complete" | "error";
+  activeTool: string | null;
+  status: string | null;
+  error?: string;
+  messages: ReviseAgentMessage[];
+}
+
+export interface ReviseAgentRunOptions {
+  /** Narrows host authority for this run; cannot raise it. */
+  executionPolicy?: {
+    documentAccess: "read" | "comment" | "edit";
+    interaction: "interactive" | "best_effort";
+    allowedTools?: readonly string[] | null;
+  };
+  developerPrePrompt?: string;
+  allowedToolNames?: string[];
+  providerOverride?: string;
+  modelOverride?: string;
+  forceFirstTurnNoTools?: boolean;
+  attachments?: unknown[];
+  directMode?: boolean;
+}
+
+export interface ReviseAgentRunResult extends ReviseAgentEvent {
+  actionCount: number;
+}
+
+export interface ReviseEditorToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+export interface ReviseEditorToolExecutionOptions {
+  /** Target an open document. Omit to use the active document. */
+  documentId?: string;
+  /** Apply mutation tools directly instead of leaving tracked suggestions. */
+  directMode?: boolean;
+}
+
+/** Tool arguments, with input optional only when its schema has no required
+ * fields — the browser twin of the server contract's argument tuple. */
+export type ReviseEditorToolArguments<Name extends ReviseToolName> =
+  Record<string, never> extends ReviseToolInput<Name>
+    ? [input?: ReviseToolInput<Name>, options?: ReviseEditorToolExecutionOptions]
+    : [input: ReviseToolInput<Name>, options?: ReviseEditorToolExecutionOptions];
+
+export interface ReviseEditorTool extends ReviseEditorToolDefinition {
+  execute(
+    input?: Record<string, unknown>,
+    options?: ReviseEditorToolExecutionOptions,
+  ): Promise<ReviseToolResult<string>>;
+}
+
+/** The document tool surface. Speaks the same contract as
+ * the backend entry: the same discriminated result envelope, the
+ * same typed inputs, the same execute/executeDynamic/call split. */
+export interface ReviseEditorTools {
+  /** Execute a known tool; expected failures come back as { ok: false }. */
+  execute<Name extends ReviseToolName>(
+    name: Name,
+    ...args: ReviseEditorToolArguments<Name>
+  ): Promise<ReviseToolResult<Name>>;
+  /** Execute an untrusted model-provided name and JSON input; also the door
+   * to browser-only tools (get_selection, view_image, revise_run_agent) and
+   * model-facing document_id routing. */
+  executeDynamic(
+    name: string,
+    input?: Record<string, unknown>,
+    options?: ReviseEditorToolExecutionOptions,
+  ): Promise<ReviseToolResult<string>>;
+  /** Returns only the successful response and throws ReviseToolError when
+   * the tool rejects the call. */
+  call<Name extends ReviseToolName>(
+    name: Name,
+    ...args: ReviseEditorToolArguments<Name>
+  ): Promise<ReviseToolResponse<Name>>;
+  getDefinitions(): ReviseEditorToolDefinition[];
+  exportDocx(): Promise<Blob>;
+  /** Settle every open suggestion, collaborators' included. Prefer ID-based
+   * review.acceptSuggestions() with IDs from mutation results. */
+  acceptAllSuggestions(): ReviseSuggestionDecision;
+  rejectAllSuggestions(): ReviseSuggestionDecision;
+}
+
+export interface ReviseAgentSubagent {
+  run(task: string, options?: ReviseAgentRunOptions): Promise<ReviseAgentRunResult>;
+  steer(message: string): boolean;
+  cancel(): void;
+  subscribe(listener: (event: ReviseAgentEvent) => void): () => void;
+}
+
+export function createEmptyDocx(title?: string): Promise<Blob>;
+/**
+ * Where Revise's static assets load from: PDF export and math fonts, the
+ * KaTeX stylesheet, the pdf.js worker, and (revise/editor/full) Tree-sitter
+ * grammars. Defaults to https://revise.io. To self-host, mirror revise.io's
+ * fonts/, katex.min.css, pdfjs/, and tree-sitter/ at your own origin and pass
+ * it here; null restores the default.
+ */
+export declare function setAssetBaseUrl(url: string | null): void;
+
+export type ReviseCommentAgentStatus =
+  | "running"
+  | "complete"
+  | "error"
+  | "interrupted"
+  | "canceled";
+
+export interface ReviseCommentAgentState {
+  threadId: string;
+  status: ReviseCommentAgentStatus;
+  statusText?: string;
+  error?: string;
+  relatedSuggestionIds?: string[];
+  updatedAt: number;
+  [key: string]: unknown;
+}
+
+export interface ReviseCommentAgentRunResult {
+  threadId: string;
+  status: ReviseCommentAgentStatus;
+  reply?: string;
+  relatedSuggestionIds: string[];
+  error?: string;
+}
+
+export interface ReviseCommentAgent {
+  run(threadId: string, prompt?: string): Promise<ReviseCommentAgentRunResult>;
+  steer(threadId: string, message: string): boolean;
+  cancel(threadId: string): void;
+  getState(threadId: string): ReviseCommentAgentState | undefined;
+  subscribe(
+    listener: (states: ReadonlyMap<string, ReviseCommentAgentState>) => void,
+  ): () => void;
+}
+
+export type InlineFormattingCommand =
+  | "bold"
+  | "italic"
+  | "underline"
+  | "strikethrough"
+  | "doubleStrikethrough"
+  | "smallCaps"
+  | "allCaps"
+  | "code"
+  | "latex"
+  | "superscript"
+  | "subscript";
+
+export type ReviseToolbarMode = "native" | "none";
+export type ReviseZoom = number | "fit-width";
+
+export interface ReviseFontDefinition {
+  family: string;
+  label?: string;
+  cssFamily?: string;
+  fontWeight?: number | string;
+}
+
+export interface ReviseZoomState {
+  zoom: ReviseZoom;
+  scale: number;
+}
+
+export interface ReviseEditorZoomController {
+  getState(): ReviseZoomState;
+  setZoom(zoom: ReviseZoom): void;
+  fitWidth(): void;
+  subscribe(listener: (state: ReviseZoomState) => void): () => void;
+}
+
+export interface ReviseSelectionPosition {
+  kind: "text";
+  blockId: string;
+  offset: number;
+}
+
+export interface ReviseTextTargetSegment {
+  blockId: string;
+  range: { start: number; end: number };
+}
+
+export interface ReviseTextTarget {
+  kind: "text";
+  segments: ReviseTextTargetSegment[];
+}
+
+export interface ReviseSelectionTarget {
+  kind: "selection";
+  start: ReviseSelectionPosition;
+  end: ReviseSelectionPosition;
+}
+
+export interface ReviseSelectionSnapshot {
+  documentId: string | null;
+  anchor: ReviseSelectionPosition | null;
+  focus: ReviseSelectionPosition | null;
+  start: ReviseSelectionPosition | null;
+  end: ReviseSelectionPosition | null;
+  target: ReviseTextTarget | null;
+  selectionTarget: ReviseSelectionTarget | null;
+  activeMarks: string[];
+  activeCommentIds: string[];
+  activeChangeIds: string[];
+  quotedText: string;
+  text: string;
+  collapsed: boolean;
+  empty: boolean;
+}
+
+export type ReviseSelectionCapture = ReviseSelectionSnapshot & {
+  documentId: string;
+  target: ReviseTextTarget;
+  selectionTarget: ReviseSelectionTarget;
+};
+
+export type ReviseSelectionRestoreResult =
+  | { success: true }
+  | {
+      success: false;
+      reason: "not-ready" | "read-only" | "missing-target" | "stale";
+    };
+
+export interface ReviseEditorSelection {
+  getSnapshot(): ReviseSelectionSnapshot;
+  subscribe(listener: (event: { snapshot: ReviseSelectionSnapshot }) => void): () => void;
+  observe(listener: (snapshot: ReviseSelectionSnapshot) => void): () => void;
+  capture(): ReviseSelectionCapture | null;
+  restore(capture: ReviseSelectionCapture): ReviseSelectionRestoreResult;
+  clear(): void;
+}
+
+export interface ReviseToolbarState {
+  ready: boolean;
+  readOnly: boolean;
+  documentMode: ReviseDocumentMode;
+  activeTab: "edit" | "layout" | "insert" | "tools" | "review";
+  hasSelection: boolean;
+  canUndo: boolean;
+  canRedo: boolean;
+  formatting: Record<string, unknown> & {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    color?: string;
+    backgroundColor?: string;
+    fontFamily?: string;
+  };
+  heading?: 1 | 2 | 3 | 4 | 5 | 6;
+  alignment?: "left" | "center" | "right" | "justify";
+  lineSpacing?: number;
+  fontSizePt?: number;
+  blockType: { type: string; variant?: string } | null;
+  review: {
+    open: boolean;
+    targetCount: number;
+    currentTargetSuggestionCount: number;
+    allOpenSuggestionCount: number;
+    showRemovals: boolean;
+    viewMode: "all-markup" | "final" | "original";
+  };
+}
+
+export interface ReviseDocumentStatistics {
+  wordCount: number;
+  characterCount: number;
+}
+
+/**
+ * DOCX-mode fidelity: what relationship the next export has to the original
+ * .docx file.
+ *
+ *   "exact"     — byte-identical to the imported file
+ *   "grafted"   — original bytes plus this document's edits; untouched
+ *                 content exports byte-for-byte
+ *   "converted" — no usable original; export regenerates everything
+ */
+export type ReviseSourceFidelity = "exact" | "grafted" | "converted";
+
+export interface ReviseSourceFidelityReport {
+  fidelity: ReviseSourceFidelity;
+  /** Body blocks an export would regenerate (empty for "exact"). */
+  regeneratedBlockIds: string[];
+  /** Part domains an export would regenerate (notes, chrome, comments…). */
+  changedDomains: string[];
+  /** Why "converted", when it is. */
+  convertedReason?:
+    | "no-capture"
+    | "no-carrier"
+    | "carrier-hash-mismatch"
+    | "unpaired-capture";
+}
+
+export interface ReviseEditorToolbar {
+  getState(): ReviseToolbarState;
+  subscribe(listener: (state: ReviseToolbarState) => void): () => void;
+  /** Switches the ribbon row. "tools" is Revise-app chrome and is ignored in
+   * the SDK — use `getStatistics()` for word and character counts. */
+  setActiveTab(tab: ReviseToolbarState["activeTab"]): void;
+  openFind(): void;
+  undo(): boolean;
+  redo(): boolean;
+  copy(): Promise<void>;
+  copyAs(format: "plaintext" | "markdown" | "html"): Promise<void>;
+  cut(): boolean;
+  paste(): Promise<boolean>;
+  pasteTextOnly(): Promise<boolean>;
+  pasteFormattingOnly(): Promise<boolean>;
+  toggleInline(command: InlineFormattingCommand): boolean;
+  toggleBold(): boolean;
+  toggleItalic(): boolean;
+  toggleUnderline(): boolean;
+  toggleStrikethrough(): boolean;
+  toggleDoubleStrikethrough(): boolean;
+  toggleSmallCaps(): boolean;
+  toggleAllCaps(): boolean;
+  toggleCode(): boolean;
+  toggleLatex(): boolean;
+  toggleSuperscript(): boolean;
+  toggleSubscript(): boolean;
+  clearFormatting(): boolean;
+  setFontFamily(fontFamily?: string): boolean;
+  setFontSize(fontSizePt?: number): boolean;
+  setLetterSpacing(spacing?: number): boolean;
+  setTextColor(color?: string): boolean;
+  setHighlightColor(color?: string): boolean;
+  setHeading(level?: 1 | 2 | 3 | 4 | 5 | 6): boolean;
+  setAlignment(alignment?: "left" | "center" | "right" | "justify"): boolean;
+  setLineSpacing(spacing?: number): boolean;
+  toggleList(variant: "ordered" | "unordered" | "todo"): boolean;
+  createLink(): boolean;
+  increaseIndent(): boolean;
+  decreaseIndent(): boolean;
+  insertTable(rows: number, columns: number): boolean;
+  insertImage(file: File): Promise<boolean>;
+  insertContainer(): boolean;
+  insertCodeBlock(language?: string): boolean;
+  insertMathBlock(content?: string): boolean;
+  insertDiagram(content?: string): boolean;
+  insertFootnote(kind?: "footnote" | "endnote"): boolean;
+  insertPageNumber(): boolean;
+  insertPageBreak(): boolean;
+  insertSectionBreak(): boolean;
+  openReview(): void;
+  closeReview(): void;
+  reviewPrevious(): boolean;
+  reviewNext(): boolean;
+  acceptCurrent(): boolean;
+  rejectCurrent(): boolean;
+  acceptAll(): boolean;
+  rejectAll(): boolean;
+  setShowRemovals(show: boolean): void;
+  setSuggestionViewMode(mode: "all-markup" | "final" | "original"): void;
+}
+
+export interface ReviseCommentMention {
+  id: string;
+  type: "user" | "agent";
+  label: string;
+  start: number;
+  end: number;
+  email?: string;
+}
+
+export interface ReviseCommentRecord {
+  id: string;
+  author: string;
+  initials?: string;
+  authorId?: string;
+  authorImageUrl?: string;
+  createdAt: string;
+  bodyMd: string;
+  mentions?: ReviseCommentMention[];
+  parentId?: string;
+  relatedSuggestionIds?: string[];
+  resolved?: boolean;
+}
+
+export interface ReviseCommentAnchor {
+  blockId: string;
+  start: number;
+  end: number;
+}
+
+export interface ReviseCommentThread {
+  root: ReviseCommentRecord;
+  replies: ReviseCommentRecord[];
+  anchor: ReviseCommentAnchor | null;
+  relatedSuggestionIds: string[];
+}
+
+export interface ReviseReviewState {
+  open: boolean;
+  commentsOpen: boolean;
+  targetCount: number;
+  currentTargetSuggestionCount: number;
+  allOpenSuggestionCount: number;
+  openSuggestionIds: string[];
+  currentSuggestionIds: string[];
+  visibleAgentSuggestionIds: string[];
+  activeCommentId: string | null;
+  showRemovals: boolean;
+  viewMode: "all-markup" | "final" | "original";
+  commentThreads: ReviseCommentThread[];
+}
+
+export interface ReviseEditorReview {
+  getState(): ReviseReviewState;
+  subscribe(listener: (state: ReviseReviewState) => void): () => void;
+  open(): void;
+  close(): void;
+  previous(): boolean;
+  next(): boolean;
+  nextAgentSuggestion(): boolean;
+  acceptCurrent(): boolean;
+  rejectCurrent(): boolean;
+  acceptAll(): boolean;
+  rejectAll(): boolean;
+  previewCurrent(mode: "accept" | "reject" | null): boolean;
+  previewAll(mode: "accept" | "reject" | null): boolean;
+  getOpenSuggestionIds(): string[];
+  /** Every pending change with its kind, author, timestamp, location, and
+   * text. A pull, not part of the subscribed state. */
+  listChanges(): ReviseTrackedChange[];
+  getChange(suggestionId: string): ReviseTrackedChange | null;
+  navigateToSuggestion(suggestionId: string): boolean;
+  navigateWithinSuggestions(suggestionIds: string[], direction: "previous" | "next"): boolean;
+  previewSuggestions(suggestionIds: string[], mode: "accept" | "reject" | null): void;
+  /** Per-ID outcome, same shape as the server surface: stale IDs land in
+   * missing; a role that may not resolve reports all unresolved. */
+  acceptSuggestions(suggestionIds: string[]): ReviseSuggestionDecision;
+  rejectSuggestions(suggestionIds: string[]): ReviseSuggestionDecision;
+  setShowRemovals(show: boolean): void;
+  setSuggestionViewMode(mode: "all-markup" | "final" | "original"): void;
+  openComments(): void;
+  closeComments(): void;
+  selectComment(commentId: string | null): boolean;
+  addCommentAtSelection(bodyMd: string, mentions?: ReviseCommentMention[]): string | null;
+  addCommentToRanges(ranges: ReviseCommentAnchor[], bodyMd: string, mentions?: ReviseCommentMention[]): string | null;
+  addCommentToBlock(blockId: string, bodyMd: string, mentions?: ReviseCommentMention[]): string | null;
+  addCommentForSuggestion(suggestionId: string, bodyMd: string, mentions?: ReviseCommentMention[]): string | null;
+  replyToComment(commentId: string, bodyMd: string, mentions?: ReviseCommentMention[]): string | null;
+  setCommentResolved(commentId: string, resolved: boolean): boolean;
+  deleteComment(commentId: string): boolean;
+  getRelatedSuggestionIds(commentId: string): string[];
+  acceptCommentSuggestions(commentId: string): ReviseSuggestionDecision;
+  rejectCommentSuggestions(commentId: string): ReviseSuggestionDecision;
+}
+
+/** Chrome the SDK no longer renders buttons for; the host drives it. */
+export interface ReviseViewState {
+  ready: boolean;
+  title: string;
+  documentMode: ReviseDocumentMode;
+  readOnly: boolean;
+  commentsOpen: boolean;
+  /** Comment threads in the document, open panel or not. */
+  commentCount: number;
+  reviewOpen: boolean;
+  /** Suggestions and comment threads Review would step through. */
+  reviewTargetCount: number;
+}
+
+export interface ReviseEditorView {
+  getState(): ReviseViewState;
+  subscribe(listener: (state: ReviseViewState) => void): () => void;
+  setTitle(title: string): void;
+  setDocumentMode(mode: ReviseDocumentMode): void;
+  setCommentsOpen(open: boolean): void;
+  setReviewOpen(open: boolean): void;
+}
+
+export interface ReviseDocumentHandle {
+  readonly id: string;
+  readonly title: string;
+  tools: ReviseEditorTools;
+  toolbar: ReviseEditorToolbar;
+  review: ReviseEditorReview;
+  /** Title and the comments/review/document-mode chrome the host now owns. */
+  view: ReviseEditorView;
+  zoom: ReviseEditorZoomController;
+  selection: ReviseEditorSelection;
+  agent: ReviseAgentSubagent;
+  comments: ReviseCommentAgent;
+  /** Presence and sync state for a shared document. */
+  collaboration: ReviseCollaborationController;
+  /** What this participant is permitted to do. */
+  getRole(): ReviseDocumentRole;
+  getDocument(): ReviseDocument;
+  /** DOCX-mode fidelity of the next export relative to the original file.
+   * Computed on demand from content signatures; cheap enough for UI
+   * badges, not for per-keystroke calls. */
+  getSourceFidelity(): ReviseSourceFidelityReport;
+  /** Live word and character counts (text statistics, no layout pass). */
+  getStatistics(): ReviseDocumentStatistics;
+  getDocumentMode(): ReviseDocumentMode;
+  setDocumentMode(mode: ReviseDocumentMode): void;
+  getToolDefinitions(): ReviseEditorTool[];
+  focus(): void;
+  openReview(): void;
+  closeReview(): void;
+  openComments(): void;
+  closeComments(): void;
+}
+
+export type ReviseDocumentMode = "editing" | "suggesting" | "viewing";
+
+export type ReviseDocumentSource = File | Blob | ArrayBuffer;
+
+/** Input formats the SDK parses. DOCX is the only one carrying comments,
+ * tracked changes, sections, and headers. */
+export type ReviseDocumentFormat = "docx" | "markdown" | "txt" | "html";
+
+/**
+ * Yjs types, left deliberately loose.
+ *
+ * Naming them structurally made the package dependency-free but broke the
+ * thing hosts actually write: a `connect` callback annotated with the real
+ * `Y.Doc` is not assignable to a minimal stand-in, because callback
+ * parameters are contravariant. Declaring them permissively keeps your own
+ * code fully typed — annotate the callback with yjs's types, as you would
+ * anyway — without this package importing yjs for every consumer, including
+ * those who never collaborate.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ReviseYDoc = any;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ReviseAwareness = any;
+
+/** Any Yjs provider: Hocuspocus exposes `document`, y-websocket and y-webrtc
+ * expose `doc`, and some wrappers expose `getYDoc()`. */
+export interface ReviseCollaborationProvider {
+  document?: ReviseYDoc;
+  doc?: ReviseYDoc;
+  getYDoc?: () => ReviseYDoc;
+  awareness?: ReviseAwareness | null;
+}
+
+/** Attach a transport to a document the SDK built. Return the provider so the
+ * editor can recognize its transactions as remote. */
+export type ReviseCollaborationConnect = (
+  ydoc: ReviseYDoc,
+  awareness: ReviseAwareness,
+) => ReviseCollaborationProvider | { destroy?: () => void } | void;
+
+export interface ReviseCollaborationConfig {
+  /**
+   * The recommended form: the editor builds the document and awareness with
+   * the settings it requires, and this connects them.
+   *
+   * The editor reserves eight top-level keys in the document — content,
+   * chrome, notes, comments, annotations, metadata, sdt-wrappers, paragraphs
+   * — so a document built elsewhere may already use those names or hold
+   * another schema. Let the editor build its own.
+   */
+  connect?: ReviseCollaborationConnect;
+  /** A provider that already owns its document. The document is validated
+   * before use. */
+  provider?: ReviseCollaborationProvider;
+  /** A document you own. Validated before use; prefer `connect`. */
+  ydoc?: ReviseYDoc;
+  /** Awareness, for remote carets and presence. Pass null to opt out. */
+  awareness?: ReviseAwareness | null;
+  /** The transaction origin your transport applies remote updates with.
+   * Required when passing `ydoc` without a `provider`. */
+  remoteOrigin?: unknown;
+  /** Whether the transport has finished its initial sync. The document stays
+   * closed until this is true. */
+  synced?: boolean;
+  /** "if-empty" (default) writes the source file into an empty room;
+   * "never" always joins. */
+  seed?: "if-empty" | "never";
+}
+
+export interface RevisePeer {
+  clientId: number;
+  isLocal: boolean;
+  id?: string;
+  name?: string;
+  email?: string;
+  image?: string;
+  color: string;
+}
+
+export interface ReviseCollaborationState {
+  enabled: boolean;
+  synced: boolean;
+  peers: RevisePeer[];
+}
+
+export interface ReviseCollaborationController {
+  getState(): ReviseCollaborationState;
+  subscribe(listener: (state: ReviseCollaborationState) => void): () => void;
+}
+
+/** What a participant may do. A boundary, not a starting point: unlike
+ * `documentMode` it cannot be escaped from inside the editor. */
+export type ReviseDocumentRole = "editor" | "suggester" | "viewer";
+
+export interface ReviseRolePolicy {
+  readonly modes: readonly ReviseDocumentMode[];
+  readonly canEdit: boolean;
+  readonly canEditDirectly: boolean;
+  readonly canResolveSuggestions: boolean;
+  readonly canComment: boolean;
+}
+
+export declare function rolePolicy(role: ReviseDocumentRole): ReviseRolePolicy;
+
+/** Thrown by `agent.run()` and UI controllers when a role forbids an
+ * action. Tool calls report role denials as structured
+ * `{ ok: false, error: { code: "role_not_permitted" } }` results instead. */
+export declare class ReviseRoleError extends Error {
+  readonly role: ReviseDocumentRole;
+  readonly action: string;
+}
+
+/** A pending tracked change, with the metadata a review panel needs. */
+export interface ReviseTrackedChange {
+  id: string;
+  /** Word's three revision kinds, plus "move" for a linked move pair. A
+   * replacement appears as both a delete and an insert, as it does in Word.
+   * A linked move is ONE change: `deletedText` is the text at the source,
+   * `insertedText` the text at the destination, and resolving it settles
+   * both locations atomically. */
+  kind: "insert" | "delete" | "format" | "move";
+  /** A person, "Revise Agent", an external agent, or "Anonymous". */
+  author: string;
+  authorType: "human" | "ai";
+  agentModel?: string;
+  /** Epoch milliseconds. */
+  createdAt?: number;
+  description?: string;
+  /** Blocks this change touches, in document order. */
+  blockIds: string[];
+  /** For kind "move": blocks the text moved out of, in document order. */
+  moveSourceBlockIds?: string[];
+  /** For kind "move": blocks the text moved into, in document order. */
+  moveDestinationBlockIds?: string[];
+  insertedText?: string;
+  deletedText?: string;
+  commentThreadId?: string;
+}
+
+export interface ReviseDocumentInput {
+  /** Stable host-owned ID used by APIs, agent tools, and callbacks. */
+  id: string;
+  /** The source document: DOCX, Markdown, plain text, or HTML. Optional when
+   * joining an established collaborative document. */
+  docx?: ReviseDocumentSource;
+  /** Share this document over a Yjs transport you own. */
+  collaboration?: ReviseCollaborationConfig;
+  /** Overrides the editor-wide role for this document. */
+  role?: ReviseDocumentRole;
+  /** Declare the format explicitly. Inferred from filename, then MIME type,
+   * defaulting to DOCX. */
+  format?: ReviseDocumentFormat;
+  title?: string;
+  documentMode?: ReviseDocumentMode;
+  readOnly?: boolean;
+  zoom?: ReviseZoom;
+  defaultCommentsOpen?: boolean;
+  /** Per-document agent settings override the editor-wide defaults. */
+  agent?: ReviseAgentConfig;
+}
+
+export interface ReviseOpenDocument {
+  id: string;
+  title: string;
+  status: "opening" | "ready" | "error";
+  active: boolean;
+  error?: string;
+}
+
+export interface ReviseDocumentCollectionState {
+  activeDocumentId: string | null;
+  documents: ReviseOpenDocument[];
+}
+
+export interface ReviseOpenDocumentOptions {
+  /** Newly opened documents become active by default. */
+  activate?: boolean;
+}
+
+export interface ReviseEditorDocuments {
+  open(
+    document: ReviseDocumentInput,
+    options?: ReviseOpenDocumentOptions,
+  ): Promise<ReviseDocumentHandle>;
+  close(documentId: string): boolean;
+  activate(documentId: string): boolean;
+  get(documentId?: string): ReviseDocumentHandle | null;
+  require(documentId?: string): ReviseDocumentHandle;
+  getActiveId(): string | null;
+  list(): ReviseOpenDocument[];
+  getState(): ReviseDocumentCollectionState;
+  subscribe(
+    listener: (state: ReviseDocumentCollectionState) => void,
+  ): () => void;
+}
+
+export type ReviseDocumentScoped<T> = T & {
+  /** Bind this controller to one open document instead of the active one. */
+  forDocument(documentId: string): T;
+};
+
+export interface ReviseMultiDocumentTools extends ReviseEditorTools {
+  forDocument(documentId: string): ReviseEditorTools;
+  exportDocx(documentId?: string): Promise<Blob>;
+  acceptAllSuggestions(documentId?: string): ReviseSuggestionDecision;
+  rejectAllSuggestions(documentId?: string): ReviseSuggestionDecision;
+}
+
+export interface ReviseEditorHandle {
+  documents: ReviseEditorDocuments;
+  /** Resolve an explicit document, or the active document when omitted. */
+  document(documentId?: string): ReviseDocumentHandle;
+  tools: ReviseMultiDocumentTools;
+  toolbar: ReviseDocumentScoped<ReviseEditorToolbar>;
+  review: ReviseDocumentScoped<ReviseEditorReview>;
+  /** Title and the comments/review/document-mode chrome the host now owns. */
+  view: ReviseDocumentScoped<ReviseEditorView>;
+  zoom: ReviseDocumentScoped<ReviseEditorZoomController>;
+  selection: ReviseDocumentScoped<ReviseEditorSelection>;
+  agent: ReviseDocumentScoped<ReviseAgentSubagent>;
+  comments: ReviseDocumentScoped<ReviseCommentAgent>;
+  /** Presence and sync state for shared documents. */
+  collaboration: ReviseDocumentScoped<ReviseCollaborationController>;
+  /** What this participant may do with a document. */
+  getRole(documentId?: string): ReviseDocumentRole;
+  /**
+   * Resolves once a document is open and its controllers are usable.
+   *
+   * `onReady` hands you the editor before any document exists; everything
+   * that acts on a document throws until one does. Subscriptions are the
+   * exception and can be placed immediately.
+   */
+  whenReady(documentId?: string): Promise<ReviseDocumentHandle>;
+  getDocument(documentId?: string): ReviseDocument;
+  /** Live word and character counts for a document (active by default). */
+  getStatistics(documentId?: string): ReviseDocumentStatistics;
+  getDocumentMode(documentId?: string): ReviseDocumentMode;
+  setDocumentMode(mode: ReviseDocumentMode, documentId?: string): void;
+  getToolDefinitions(documentId?: string): ReviseEditorTool[];
+  focus(documentId?: string): void;
+  openReview(documentId?: string): void;
+  closeReview(documentId?: string): void;
+  openComments(documentId?: string): void;
+  closeComments(documentId?: string): void;
+}
+
+/** Behavior settings for tracked changes. */
+export interface ReviseTrackedChangesSettings {
+  /** Start review with deleted text shown inline (strikethrough). Reviewers
+   * used to Word usually want this on. Default false. */
+  showRemovalsInReview?: boolean;
+  /** "revise" (default): per-kind colors with a soft background tint.
+   * "word": classic redlines — all revisions in red, insertions underlined,
+   * deletions struck through, no background tint. */
+  markupStyle?: "revise" | "word";
+}
+
+export interface ReviseEditorSettings {
+  trackedChanges?: ReviseTrackedChangesSettings;
+}
+
+export interface ReviseEditorProps {
+  findShortcut?: "editor" | "browser";
+  /** Behavior settings. */
+  settings?: ReviseEditorSettings;
+  /** Receive the editor's internal instrumentation events (tool
+   * invocations, exports, review interactions, …) for the host's own
+   * analytics. These events never leave the page except through this
+   * callback. Event names and property shapes may change between versions. */
+  onAnalyticsEvent?: (
+    event: string,
+    properties?: Record<string, unknown>,
+  ) => void;
+  /** Once per page load, the SDK sends Revise one anonymous ping carrying
+   * its version; the browser adds your site's origin. Development hosts
+   * (localhost and similar) are only counted, never named. No cookies, user
+   * data, or document content. Set false to turn it off. Defaults to true. */
+  telemetry?: boolean;
+  initialDocuments?: readonly ReviseDocumentInput[];
+  /** Controlled active document ID. */
+  activeDocumentId?: string | null;
+  /** Initial active ID for uncontrolled use. Defaults to the first document. */
+  defaultActiveDocumentId?: string | null;
+  currentUser?: EditorUserIdentity | null;
+  agent?: ReviseAgentConfig;
+  theme?: "light" | "dark";
+  /** What this participant may do, across every open document. Overridden per
+   * document by `ReviseDocumentInput.role`. */
+  role?: ReviseDocumentRole;
+  defaultDocumentMode?: ReviseDocumentMode;
+  defaultZoom?: ReviseZoom;
+  defaultCommentsOpen?: boolean;
+  showDocumentModeToggle?: boolean;
+  /**
+   * Render the built-in tab strip (one tab per open document). Off by default:
+   * hosts with their own file switcher drive `documents` instead.
+   */
+  showTabs?: boolean;
+  /**
+   * Render the built-in title bar above the ribbon. Hosts that build their own
+   * chrome turn this off and drive `view` (title, mode, review) themselves.
+   */
+  showTitleBar?: boolean;
+  /** Adds a "+" button to the tab strip. Without it, no button is rendered. */
+  onNewTab?: () => void;
+  /**
+   * Take keyboard focus when a document becomes active. Defaults to true; set
+   * false when the editor sits inside a larger page and should wait for a click.
+   */
+  autoFocus?: boolean;
+  /** Opt in to the Rust/WASM hot paths (word diff, agent text matching,
+   * document stats). Off by default; the TypeScript implementations remain the
+   * fallback, so this only ever changes speed, never behavior. Available only
+   * from the explicit `revise/editor/full` entry point. */
+  wasmHotPaths?: boolean;
+  /** The area behind the page — not the page itself. Any CSS background. */
+  canvasBackground?: string;
+  /** The paper color. Any CSS color. */
+  pageBackground?: string;
+  /** The 1px outline around each page. Any CSS color. */
+  pageBorderColor?: string;
+  toolbarMode?: ReviseToolbarMode;
+  fonts?: readonly ReviseFontDefinition[];
+  className?: string;
+  style?: React.CSSProperties;
+  onReady?: (editor: ReviseEditorHandle) => void;
+  onDocumentReady?: (document: ReviseDocumentHandle) => void;
+  onDocumentsChange?: (state: ReviseDocumentCollectionState) => void;
+  onActiveDocumentChange?: (documentId: string | null) => void;
+  onChange?: (documentId: string, document: ReviseDocument) => void;
+  onDocumentTitleChange?: (documentId: string, title: string) => void;
+  onDocumentModeChange?: (documentId: string, mode: ReviseDocumentMode) => void;
+  onZoomChange?: (documentId: string, zoom: ReviseZoom) => void;
+  onAgentEvent?: (documentId: string, event: ReviseAgentEvent) => void;
+  onError?: (error: Error, documentId?: string) => void;
+}
+
+export const ReviseEditor: React.ForwardRefExoticComponent<
+  ReviseEditorProps & React.RefAttributes<ReviseEditorHandle>
+>;
+export default ReviseEditor;