@stll/folio-agents/dist/bridges/editor-ref.d.ts

Framework-neutral LLM tool layer over folio's ai-edits engine: function-calling tools so an agent can read and mutate .docx documents through @stll/folio-core.

import { FolioAgentBridge } from "../bridge.js";
import { FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditOperation, FolioAIEditSnapshot, FolioDocumentNavigationTarget, FolioDocumentOperationBatch, FolioDocumentOperationResult, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult } from "@stll/folio-core/server";
import { FolioCommentAnchor, FolioReviewChange as FolioReviewChange$1 } from "@stll/folio-core/ai-edits";
import { Comment } from "@stll/folio-core/types/content";
//#region src/bridges/editor-ref.d.ts
type FolioAgentEditorApplyDocumentOperationsOptions = {
  snapshot: FolioAIEditSnapshot;
  batch: FolioDocumentOperationBatch;
  mode?: FolioAIEditApplyMode;
  author?: string;
};
/**
 * Minimal structural slice of `DocxEditorRef` (`packages/react`) this bridge
 * drives — declared locally per AGENTS.md's react-free-core rule (agents
 * stays framework-neutral; it may not import a React-package type), covering
 * ONLY the members actually called below.
 *
 * The read-surface members (`getTrackedChanges`, `getCommentAnchors`,
 * `getSelectionText`, `getPageText`, `getTargetPage`, `showInDocument`) are
 * OPTIONAL here even though the current `DocxEditorRef` always implements
 * them: a ref built against an older `@stll/folio-react` (before these methods
 * existed) still structurally satisfies this type, and `createEditorRefBridge`
 * below falls back to the pre-existing degraded behavior for each one it does
 * not find.
 */
type FolioAgentEditorRefLike = {
  /** `DocxEditorRef.createAIEditSnapshot`. `null` before the editor view mounts. */
  createAIEditSnapshot(): FolioAIEditSnapshot | null;
  /** `DocxEditorRef.applyAIEditOperations`. */
  applyAIEditOperations(options: {
    snapshot: FolioAIEditSnapshot;
    operations: FolioAIEditOperation[];
    mode?: FolioAIEditApplyMode;
    author?: string;
  }): FolioAIEditApplyResult;
  /** `DocxEditorRef.applyDocumentOperations`, when available on newer refs. */
  applyDocumentOperations?(options: FolioAgentEditorApplyDocumentOperationsOptions): FolioDocumentOperationResult;
  /** `DocxEditorRef.undoDocumentOperations`, when available on newer refs. */
  undoDocumentOperations?(undoHandle: FolioDocumentOperationUndoHandle): FolioDocumentOperationUndoResult;
  /** `DocxEditorRef.scrollToBlock`. */
  scrollToBlock(blockId: string, snapshot?: FolioAIEditSnapshot): boolean;
  /** `DocxEditorRef.getTotalPages`. */
  getTotalPages(): number;
  /**
   * `DocxEditorRef.getTrackedChanges`. When present, `getChanges()` maps its
   * output to {@link FolioAgentChange} (same mapping as the reviewer
   * bridge's); when absent, `getChanges()` returns `[]`.
   */
  getTrackedChanges?(): FolioReviewChange$1[];
  /**
   * `DocxEditorRef.getCommentAnchors`. When present, `getComments()` merges
   * each anchor's `blockId` / `quote` into the matching host-state comment
   * by `commentId`; when absent, those fields stay `null` / `""`.
   */
  getCommentAnchors?(): FolioCommentAnchor[];
  /**
   * `DocxEditorRef.getSelectionText`. The bridge exposes `getSelectionText`
   * only when this is present, so `read_selection` reports an
   * unsupported-capability error on a ref that lacks it.
   */
  getSelectionText?(): string;
  /**
   * `DocxEditorRef.getPageText`. The bridge exposes `getPageText` only when
   * this is present, so `read_page` reports an unsupported-capability error
   * on a ref that lacks it. See {@link createEditorRefBridge} for how a
   * `null` return (page in range, layout not yet computed) is handled.
   */
  getPageText?(page: number): string | null;
  /** `DocxEditorRef.getTargetPage`, when available on newer refs. */
  getTargetPage?(target: FolioDocumentNavigationTarget, snapshot?: FolioAIEditSnapshot): number | null;
  /** `DocxEditorRef.showInDocument`, when available on newer refs. */
  showInDocument?(target: FolioDocumentNavigationTarget, snapshot?: FolioAIEditSnapshot): boolean;
};
/** Options for {@link createEditorRefBridge}. */
type CreateEditorRefBridgeOptions = {
  ref: FolioAgentEditorRefLike;
  /** Author attributed to tracked changes, comments, and replies this bridge creates. */
  author: string;
  /** Read the host app's current comment state (e.g. the `DocxEditor` `comments` prop). */
  getComments(): Comment[];
  /** Replace the host app's comment state (e.g. the setter backing that same prop). */
  setComments(comments: Comment[]): void;
  /** `"tracked-changes"` (default) produces ins/del redlines; `"direct"` edits in place. */
  mode?: FolioAIEditApplyMode;
};
/**
 * Build a {@link FolioAgentBridge} over a live `DocxEditor` ref plus the host
 * app's comment state.
 *
 * Comments live in app-controlled React state (the `DocxEditor` `comments`
 * prop), not on the ref, so this factory takes `getComments`/`setComments` to
 * read and write that state directly — the same pair the host already passes
 * to `DocxEditor`.
 *
 * KNOWN LIMITATIONS (only apply to a `ref` that predates the read-surface
 * additions below; the current `DocxEditorRef` implements all six):
 * - `getChanges()` returns `[]` when `ref.getTrackedChanges` is absent, since
 *   there is then no ref-level way to enumerate tracked changes from
 *   ProseMirror mark attributes.
 * - Comment entries fall back to `blockId: null` / `quote: ""` when
 *   `ref.getCommentAnchors` is absent, since there is then no ref-level way
 *   to resolve a comment's anchor against the live ProseMirror document.
 * - `read_page` / `read_selection` report an unsupported-capability error
 *   when `ref.getPageText` / `ref.getSelectionText` are absent: this bridge
 *   omits the corresponding `getPageText` / `getSelectionText` member
 *   entirely rather than implementing it as a no-op, which is what tells
 *   `executeFolioToolCall` to report the tool as unsupported instead of
 *   throwing.
 * - Page-scoped search and `show_in_document` report an unsupported-capability
 *   error when `ref.getTargetPage` / `ref.showInDocument` are absent.
 */
declare const createEditorRefBridge: (options: CreateEditorRefBridgeOptions) => FolioAgentBridge;
//#endregion
export { CreateEditorRefBridgeOptions, FolioAgentEditorApplyDocumentOperationsOptions, FolioAgentEditorRefLike, createEditorRefBridge };