@ai-matrx/office 0.4.0 → 0.5.2

package/dist/docs.d.cts

@@ -0,0 +1,582 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+import { ServiceResult } from '@ai-matrx/records/core';
+import { IDocumentData } from '@univerjs/core';
+import { WorkingCopyHandle, CommitReason } from '@ai-matrx/kit/working-copy';
+import { AwarenessState } from '@ai-matrx/data/realtime/collab';
+
+/**
+ * The host ports of the Docs model and io.
+ *
+ * The package owns the document service, the open-document model and the converters, but two things
+ * belong to the app that mounts them: the database client (a package owns no client) and the server
+ * request that converts a .docx to .odt / .rtf (the app owns the server URL, auth and error capture).
+ * The host states them once at start-up with `configureDocsHost`. State sits on a `globalThis` slot
+ * so a dual-bundled copy of the package still sees one host. An unconfigured port THROWS naming
+ * itself (nothing fails silently).
+ */
+
+/** A Supabase client over any schema: the package cannot import the app's generated database types. */
+type DocsSupabase = SupabaseClient<any, any, any>;
+interface DocsHostPorts {
+    /** The app's database client (signed in as the person). */
+    getSupabase(): DocsSupabase;
+    /** An authenticated request to the Matrx server returning the raw `Response` (the open-format converter). */
+    requestRaw(path: string, init: {
+        method: "POST";
+        body: FormData;
+    }): Promise<Response>;
+}
+declare function configureDocsHost(ports: DocsHostPorts): void;
+declare function getDocsHost(): DocsHostPorts;
+
+type DocumentSource = "created" | "imported_docx" | "imported_md" | "imported_txt" | "linked_gdoc";
+/** `platform.shown_to`. */
+type ShownTo = "only_me" | "my_team" | "everyone" | "everyone_on_ai_matrx";
+/** `platform.visibility`. */
+type Visibility = "personal" | "internal" | "link" | "public";
+/** Origin of a snapshot. Free text in the database; this union is advisory. */
+type WorkbookSnapshotOrigin = "autosave" | "manual" | "imported" | "restored" | "named";
+/** Same advisory union as workbooks: a string column in the database. */
+type DocumentSnapshotOrigin = WorkbookSnapshotOrigin;
+/** A row of `workbench.udt_documents`. */
+interface DocumentRow {
+    created_at: string;
+    created_by: string;
+    custom_fields: unknown;
+    deleted_at: string | null;
+    description: string | null;
+    document_name: string;
+    id: string;
+    is_public: boolean;
+    metadata: unknown;
+    organization_id: string | null;
+    original_file_id: string | null;
+    project_id: string | null;
+    published_to_web: boolean;
+    published_to_web_at: string | null;
+    published_to_web_by: string | null;
+    shown_to: ShownTo | null;
+    source: DocumentSource;
+    task_id: string | null;
+    updated_at: string;
+    updated_by: string | null;
+    user_id: string;
+    version: number;
+    visibility: Visibility;
+}
+/** A row of `workbench.udt_document_snapshots`. */
+interface DocumentSnapshot {
+    created_at: string;
+    created_by: string | null;
+    custom_fields: unknown;
+    document_id: string;
+    id: string;
+    label: string | null;
+    metadata: unknown;
+    origin: string;
+    snapshot: unknown;
+}
+
+type CreateDocumentArgs = {
+    name: string;
+    description?: string | null;
+    /** Origin label for the document itself, mirrors `udt_documents.source`. */
+    source?: "created" | "imported_docx" | "imported_md" | "imported_txt" | "linked_gdoc";
+    organizationId: string;
+    projectId?: string | null;
+    taskId?: string | null;
+    isPublic?: boolean;
+    /**
+     * cld_files.id of the source upload (DOCX / MD / TXT blob). Set on the
+     * import flow so the lossless original is recoverable; FK is ON DELETE SET
+     * NULL, so deleting the file just nulls the link — the document survives.
+     */
+    originalFileId?: string | null;
+};
+declare function createDocument(args: CreateDocumentArgs): Promise<ServiceResult<DocumentRow>>;
+declare function listAccessibleDocuments(): Promise<ServiceResult<DocumentRow[]>>;
+declare function getDocument(documentId: string): Promise<ServiceResult<DocumentRow>>;
+declare function renameDocument(documentId: string, name: string): Promise<ServiceResult<DocumentRow>>;
+/**
+ * Move the document into a project (or out of one with `null`). Sibling of
+ * `renameDocument`: the one named setter for `project_id`.
+ */
+declare function moveDocument(documentId: string, projectId: string | null): Promise<ServiceResult<DocumentRow>>;
+/**
+ * Rewrite the document's description. Sibling of `renameDocument` — the two
+ * human-authored fields on `udt_documents` each get a named setter so callers
+ * never hand-roll a `.from("udt_documents").update(...)`. Pass `null` (or an
+ * empty string) to clear it.
+ *
+ * Added when the documents surface became agent-writable: the
+ * `document_description` write target on `/documents/[id]` is its caller, the
+ * same way `updateWorkbookDescription` serves `workbook_description`. Keeping
+ * the pair symmetric is this file's standing contract with `workbook-service`
+ * (see the module header).
+ */
+declare function updateDocumentDescription(documentId: string, description: string | null): Promise<ServiceResult<DocumentRow>>;
+/**
+ * Soft delete — the document is tombstoned, not destroyed, and its snapshots stay
+ * with it. Every read path filters `deleted_at is null`. Pair with
+ * restoreDocument for undo. (aidream migration 0458.)
+ */
+declare function restoreDocument(documentId: string): Promise<ServiceResult<true>>;
+/**
+ * Archive (delete means archive: never a hard delete) — only for rolling back a document this very flow just created and
+ * failed to populate. Never use for a user-initiated delete: that is
+ * deleteDocument, which tombstones and stays recoverable.
+ */
+declare function discardFailedDocument(documentId: string): Promise<ServiceResult<true>>;
+declare function deleteDocument(documentId: string): Promise<ServiceResult<true>>;
+/**
+ * Latest-snapshot fetch — what an opened document hydrates from. Returns
+ * `data: null` (success path) when the document has no snapshots yet (newly
+ * created, never saved). Distinguish "no snapshot" from "load error" by
+ * checking `result.data === null`.
+ */
+declare function getLatestDocumentSnapshot(documentId: string): Promise<ServiceResult<DocumentSnapshot | null>>;
+type SaveDocumentSnapshotArgs = {
+    documentId: string;
+    snapshot: unknown;
+    label?: string | null;
+    origin?: DocumentSnapshotOrigin;
+};
+declare function saveDocumentSnapshot(args: SaveDocumentSnapshotArgs): Promise<ServiceResult<DocumentSnapshot>>;
+/**
+ * An independent copy of a document: its own row, with the latest snapshot copied over, so editing the copy never
+ * touches the original. The copy lives in the original's organization and project. Used by a board-template use.
+ */
+declare function copyDocument(documentId: string, name?: string): Promise<ServiceResult<DocumentRow>>;
+/** Trash view: the caller's own archived documents (RLS decides what is readable). */
+declare function listTrashedDocuments(): Promise<ServiceResult<DocumentRow[]>>;
+declare function listDocumentSnapshots(documentId: string, limit?: number): Promise<ServiceResult<DocumentSnapshot[]>>;
+
+type MutationParams = Record<string, unknown> | unknown[] | null;
+type CollabMutationInfo = {
+    id: string;
+    type: number;
+    params: MutationParams;
+    /** Who made it (the person's uid), so a peer can tell its own other tab's edit from a stranger's. */
+    uid?: string;
+};
+type ExecuteOptions = {
+    /** Per-Univer convention: when true, the command runs locally only and is
+     *  NOT broadcast to other plugins. We set this on inbound-apply so the
+     *  subsequent onMutationExecutedForCollab does NOT re-fire on our peer. */
+    onlyLocal?: boolean;
+    fromCollab?: boolean;
+};
+type CommandServiceLike = {
+    onMutationExecutedForCollab(listener: (info: CollabMutationInfo, options?: ExecuteOptions) => void): {
+        dispose: () => void;
+    };
+    syncExecuteCommand(id: string, params: MutationParams, options?: ExecuteOptions): unknown;
+};
+
+/**
+ * THE DOCUMENT MODEL — the engine of one cloud document per tab.
+ *
+ * Before this, the document lived only inside each `DocumentEditor`'s Univer
+ * instance. A remount (a board tile waking, a tile removed and undone, a route
+ * change and back) rebuilt the editor from the SERVER copy, so whatever the
+ * last save had not carried yet was gone; two mounts of one document were two
+ * editors, each saving full snapshots of its own copy (last write wins), each
+ * with its own realtime channel and its own collab room.
+ *
+ * The document is a record on THE one working-copy primitive
+ * (`@ai-matrx/kit/working-copy`, kind `udt_document`,
+ * `./documentModels.ts`): its save status, dirty and view count are Redux state
+ * (`workingCopies["udt_document:<id>"]`), its one coalesced save is the kind's.
+ * What Redux cannot hold — Univer's body — is this engine, registered on the
+ * record's session under the same key:
+ *
+ *  - BODY. Every local mutation in one view is replayed into every other view
+ *    of the document (the same mutation stream collab sends between machines),
+ *    so two views show one document. A new view boots from the engine's latest
+ *    state — a live view's snapshot, or the snapshot the last view left behind
+ *    — never the stale server copy while the record's session is alive.
+ *  - SIDE EFFECTS, ONCE. The snapshot realtime channel, the collab room, and
+ *    the pagehide / visibility / beforeunload flush are opened once per
+ *    document and closed once.
+ *  - THE EDITOR ITSELF, KEPT. Univer keeps its undo / redo history inside the
+ *    editor instance, so rebuilding the editor on a remount threw the history
+ *    away. When the last view leaves, its editor (a Univer instance with its
+ *    own DOM host) is parked here — off the page, alive — and the next view of
+ *    the document RE-ATTACHES that same instance to its own container instead
+ *    of booting a new one (`parkEditor` / `takeParkedEditor`). Undo and redo
+ *    therefore work across hide / show, a remount and a removed tile undone,
+ *    for as long as the record's session is warm; `close()` disposes it.
+ */
+
+/** Debounce from the last edit to the save. */
+declare const DOCUMENT_SAVE_DELAY_MS = 2500;
+type DocumentSnapshotData = Partial<IDocumentData>;
+/** What a view lends the model while it is mounted. */
+interface DocumentViewPort {
+    /** Univer's command service for this view's instance. */
+    commandService: CommandServiceLike;
+    /** The live document of this view (`doc.save()`), or null if it has none. */
+    snapshot: () => DocumentSnapshotData | null;
+    /** Replace the whole document in this view (a collaborator's snapshot). */
+    remount: (snapshot: DocumentSnapshotData) => void;
+    /** Whether this view may change the document (read at edit time). */
+    editable: () => boolean;
+    /**
+     * The Univer unit id of this view's mounted document. Every seat mounts its own unit, so a
+     * mutation carries the SENDER's id and must be re-addressed to this view's unit before it is
+     * applied. Falls back to the id of `snapshot()` when a view does not state it.
+     */
+    unitId?: () => string | null;
+}
+/** Everything the engine reaches outside itself — injected so it is testable. */
+interface DocumentModelDeps {
+    /** The newest stored snapshot (its row id + body), or null for a document never saved. */
+    loadLatest: (documentId: string) => Promise<{
+        id: string;
+        snapshot: DocumentSnapshotData;
+    } | null>;
+    save: (input: {
+        documentId: string;
+        snapshot: DocumentSnapshotData;
+        origin: "autosave" | "manual";
+    }) => Promise<{
+        id: string;
+        createdBy: string | null;
+    }>;
+    onSaved?: (documentId: string, origin: "autosave" | "manual") => void;
+    /** Window-level listeners (pagehide, visibilitychange, beforeunload). */
+    listenToPage?: (handlers: {
+        flush: () => void;
+        hasUnsaved: () => boolean;
+    }) => () => void;
+    /** A mutation could not be applied to a view: the app says so (a notice); the model re-syncs from the saved version. */
+    onApplyFailed?: (documentId: string, mutationId: string, error: unknown) => void;
+}
+/** A collab room (WorkbookCollabSession) bound to the model's command stream. */
+interface DocumentCollabHandle {
+    stop: () => void;
+    isHost: () => boolean;
+    /** This tab replaced the whole document and saved it as `snapshotId`: peers reload it. */
+    announceReplaced: (snapshotId: string) => void;
+}
+/** Who else is in the document's room (shared by every view of it). */
+interface DocumentAwareness {
+    states: Map<number, AwarenessState>;
+    selfUid: string;
+}
+/**
+ * An editor instance kept alive between views of the document: its DOM host
+ * (re-parented into the next view's container) and the instance behind it,
+ * whose undo history survives because the instance does. Opaque to the model
+ * apart from what it calls.
+ */
+interface ParkedDocumentEditor<T = unknown> {
+    /** The element the editor renders into; the next view appends it to its container. */
+    element: HTMLElement;
+    instance: T;
+    /** Replace the whole document (a collaborator's snapshot arrived while parked). */
+    remount: (snapshot: DocumentSnapshotData) => void;
+    /** Throw the instance away (the record's session closed). */
+    dispose: () => void;
+}
+type DocumentCollabFactory = (commandService: CommandServiceLike, onAwareness: (awareness: DocumentAwareness) => void, 
+/** A peer replaced the whole document (history restore, Google update). */
+onReplaced: () => void) => Promise<DocumentCollabHandle | null>;
+declare class DocumentModel {
+    readonly documentId: string;
+    private readonly deps;
+    private readonly handle;
+    private readonly views;
+    private lastEditedView;
+    /** The document as the last view left it, or as last loaded / saved. */
+    private stored;
+    private loading;
+    private relaying;
+    /** Snapshot rows this tab already holds (loaded or written) — never re-applied. */
+    private readonly knownSnapshots;
+    private readonly collabListeners;
+    private collab;
+    private collabStarting;
+    private awareness;
+    private readonly awarenessListeners;
+    private realtimeClose;
+    private pageClose;
+    /** The last view's editor, alive and off the page until a view takes it back. */
+    private parked;
+    constructor(handle: WorkingCopyHandle, deps: DocumentModelDeps);
+    /** The newest state of the body this tab holds, without a network read. */
+    latest(): DocumentSnapshotData | null;
+    /**
+     * What a NEW view should boot from: the model's latest state, or (only when
+     * this tab holds none) the newest server snapshot. Null = an empty document.
+     * Re-read `latest()` synchronously right before mounting — another view may
+     * have typed while the server read was in flight.
+     */
+    openingSnapshot(createEmpty: () => DocumentSnapshotData): Promise<DocumentSnapshotData>;
+    /** A view's Univer instance is ready: it shares the document from now on. */
+    attachView(port: DocumentViewPort): () => void;
+    /**
+     * The last view of the document is leaving: keep its editor (and Univer's
+     * undo history inside it) for the next view. Call AFTER the view's
+     * `attachView` detach. Refused — the caller disposes its editor — while
+     * another view is still attached (it carries the document) or one is
+     * already kept.
+     */
+    parkEditor(editor: ParkedDocumentEditor): boolean;
+    /** The kept editor, handed to the view that mounts next (null when none is kept). */
+    takeParkedEditor(): ParkedDocumentEditor | null;
+    private onViewMutation;
+    /** The unit id a view's document has (what a replayed mutation must be addressed to). */
+    private unitIdOf;
+    /** Replay one mutation into every view except `exceptViewId`, addressed to each view's own unit. */
+    private relay;
+    /** A view could not follow an edit: say so, then show the saved version (unless this tab has unsaved edits of its own). */
+    private applyFailed;
+    private markDirty;
+    private saving;
+    /**
+     * The content of the version the server holds (loaded or last written). A
+     * save of the same content is no save: attaching, detaching, waking or a
+     * flush of an unchanged document never writes a snapshot row.
+     */
+    private savedFingerprint;
+    /**
+     * Write the body as it is now. Returns false when this tab is a collab peer
+     * that does not write (the elected host writes the canonical snapshot; a
+     * peer's edits reach it through the room). An explicit Save always writes.
+     */
+    write(reason: CommitReason): Promise<boolean>;
+    private hasUnsaved;
+    hasViews(): boolean;
+    /** Opened once per document by the first view that asks; idempotent. */
+    connectRealtime(open: (onSnapshot: (snapshotId: string) => void) => () => void): void;
+    /**
+     * A snapshot was committed (here or elsewhere): show a foreign one in every
+     * view. Over unsaved edits it is a CONFLICT — the working copy holds it and
+     * no save runs (one would overwrite the collaborator's snapshot) until the
+     * person chooses; `overUnsaved` is "Take theirs" (`./documentModels.ts`).
+     */
+    onRemoteSnapshot(snapshotId: string, { overUnsaved }?: {
+        overUnsaved?: boolean;
+    }): Promise<void>;
+    /**
+     * THE content swap (see @ai-matrx/office/univer openEditorContent): a SAVED snapshot
+     * replaces the document in every view and the kept editor. It is the saved
+     * version from now on, so the pending save compares equal and writes
+     * nothing (it would put the old content back over the new). In a collab
+     * room the peers reload it and the shared log is emptied.
+     */
+    replaceContent(row: {
+        id: string;
+        snapshot: DocumentSnapshotData;
+    }): void;
+    /** A peer replaced the document: show the newest save (once). */
+    private onPeerReplaced;
+    private show;
+    /**
+     * The model's command stream as ONE command service — what the collab room
+     * binds to. Local edits from any view go out once; a peer's edit is applied
+     * to every view.
+     */
+    private readonly virtualCommandService;
+    /** Join the document's collab room once (the first view that asks). */
+    startCollab(factory: DocumentCollabFactory): Promise<void>;
+    isCollabHost(): boolean;
+    getAwareness(): DocumentAwareness | null;
+    subscribeAwareness(listener: () => void): () => void;
+    /** A view arrived on a document with none. */
+    wake(): void;
+    /**
+     * The last view left: leave the collab room (presence must not outlive the
+     * person). The snapshot channel stays open while the session is kept alive,
+     * so a collaborator's save still reaches the body a returning view boots from.
+     */
+    rest(): void;
+    private closed;
+    close(): void;
+}
+
+/**
+ * Pure validation for the `matrx-user/documents` write targets.
+ *
+ * Deliberately OUTSIDE the React updater. `applySurfaceWrite`
+ * (`features/surfaces/runtime/surface-writeback.ts`) turns a THROW from a
+ * handler into the error envelope the agent reads back. Validating inside a
+ * `setState` updater would instead throw during React's render/commit — after
+ * the seam has already reported success — so the agent would be told its bad
+ * value landed. Validate here, synchronously, before touching any state.
+ *
+ * `DOCUMENT_NAME_MAX_LENGTH` is the single source of truth for the limit: it is
+ * enforced here, interpolated into the manifest target description, AND set as
+ * the `maxLength` of the header rename field on `/documents/[id]` — so the
+ * contract the agent reads, the rule the handler enforces, and the limit the
+ * human's own control applies cannot drift apart. The last of those matters
+ * for a non-obvious reason: the blur commit swallows service failures, so
+ * before the field was bounded a pasted 300-character title came back as a
+ * `varchar(255)` 400 and reverted with nothing on screen to explain it.
+ */
+/**
+ * `workbench.udt_documents.document_name` is `varchar(255) NOT NULL` — a
+ * longer value is rejected by Postgres, not merely by taste. Verified against
+ * `information_schema.columns` on 2026-08-11.
+ */
+declare const DOCUMENT_NAME_MAX_LENGTH = 255;
+/**
+ * `workbench.udt_documents.description` is unbounded `text`, so this is a
+ * product bound rather than a database one: it matches the 2000 the sibling
+ * `workbook_description` target enforces, keeping the two mirrored services
+ * mirrored in behaviour too. The library renders this as a two-line blurb —
+ * anything near the cap is already past what a reader sees.
+ */
+declare const DOCUMENT_DESCRIPTION_MAX_LENGTH = 2000;
+/**
+ * Validate an agent-supplied document title and return the exact string to
+ * persist. Throws (never coerces) so the agent hears about its own mistake.
+ *
+ * The `typeof` guard is load-bearing: the inline-tool layer PARSES a
+ * JSON-looking argument before the handler ever sees it, so a caller that
+ * sends `{"document_name":"..."}` or `"\"Quoted\""` arrives here as an object,
+ * not text. The message names the fix explicitly, because an agent that only
+ * hears "invalid" tends to retry by double-encoding — which lands escaped
+ * quotes and `\n` in the user's title box.
+ */
+declare function validateDocumentName(value: unknown): string;
+/**
+ * Validate an agent-supplied document description and return the value to
+ * persist — `null` for a deliberate clear, so the caller never has to decide
+ * whether "" means "empty string" or "no description".
+ *
+ * Unlike the title this MAY span lines (it is a blurb, not a header), but it
+ * carries the same not-JSON guard for the same reason: the inline-tool layer
+ * parses a JSON-looking argument before the handler sees it.
+ */
+declare function validateDocumentDescription(value: unknown): string | null;
+
+/**
+ * Normalize a Univer document snapshot in place. Currently fixes string-valued
+ * `paragraphStyle.namedStyleType` (the confirmed `<ParagraphMenu>` crash). New
+ * classes of string-vs-enum corruption should be added here, not patched at the
+ * call site.
+ *
+ * @param snapshot  The snapshot about to be passed to `createUniverDoc`.
+ * @param docId     Document id, for the loud warning only.
+ * @returns the same snapshot reference (mutated).
+ */
+declare function sanitizeUniverDocSnapshot(snapshot: Partial<IDocumentData>, docId?: string): Partial<IDocumentData>;
+
+/**
+ * The zoom that fits a document page inside a narrow editor (a phone), so the
+ * page reflows into view instead of scrolling sideways. Never above 100%, and
+ * never so small the text is unreadable. Pure — guarded by fit-zoom-ratio.test.ts.
+ */
+declare const MIN_FIT_ZOOM = 0.45;
+declare function fitZoomRatio(containerWidth: number, pageWidth: number, gutter?: number): number;
+
+declare function documentSourceLabel(source: DocumentSource): string;
+
+/** Insert, Emoji and Special characters: searchable sets, a name per entry. */
+interface Glyph {
+    char: string;
+    name: string;
+}
+declare const EMOJI_GROUPS: Array<{
+    id: string;
+    label: string;
+    items: Glyph[];
+}>;
+declare const SPECIAL_GROUPS: Array<{
+    id: string;
+    label: string;
+    items: Glyph[];
+}>;
+declare function searchSymbols(groups: typeof EMOJI_GROUPS, query: string): Glyph[];
+
+/**
+ * The BODY TEXT of a Univer document, as agents read and write it (PURE).
+ *
+ * `matrx-user/documents` declares the body as a value (`document_body_text`)
+ * and a write target (`document_body`). Univer owns the document model, so
+ * both go through a small port the editor hands up (`DocumentEditor`
+ * `onBodyPort`): the read is the body's data stream as plain text, and a write
+ * is ONE changed span, applied through Univer's own facade (`deleteRange` /
+ * `insertText`, which run `InsertTextCommand` on the command service). That
+ * keeps every agent edit on the one editing path a keystroke takes: undo,
+ * autosave snapshots, History and collab all see it, and formatting outside
+ * the changed span is left exactly as it was.
+ *
+ * Univer's data stream encodes a paragraph end as `\r`, a section break as
+ * `\n`, and custom blocks / tables with control characters below U+0020. The
+ * plain text maps a paragraph end to `\n` and leaves the other control tokens
+ * out; `offsets` maps each text position back to its data-stream index so a
+ * change found in the text lands at the right place in the stream.
+ */
+/** The shape of a surface write handler (structurally the chat runtime's `SurfaceWriteHandlerEntry`; the package imports no chat). */
+interface DocumentBodyWriteHandler {
+    validate: (value: unknown) => void;
+    apply: (value: unknown) => {
+        summary: string;
+        data?: unknown;
+    };
+}
+/**
+ * A product bound, not a database one (snapshots are jsonb): a body an agent
+ * sends larger than this is almost certainly a mistake (a whole file pasted
+ * twice), and past it the approval card stops being readable.
+ */
+declare const DOCUMENT_BODY_MAX_LENGTH = 200000;
+/** What the editor lends the surface. Each call resolves the live document. */
+interface DocumentBodyPort {
+    /** The main body's Univer data stream (ends with `\r\n`). */
+    getDataStream: () => string;
+    /** The live document snapshot (body with its text runs), for reading the formatting back out. */
+    getSnapshot?: () => unknown;
+    /** Delete `[start, end)` of the data stream; false when Univer refused. */
+    deleteRange: (start: number, end: number) => boolean;
+    /** Insert plain text (a `\n` starts a new paragraph) at a stream index. */
+    insertText: (at: number, text: string) => boolean;
+    /** Run a Univer command in the open editor (File menu: find and replace, comments). */
+    runCommand?: (commandId: string) => Promise<void>;
+    /** File → Page setup: open the page setup dialog in the open editor. */
+    openPageSetup?: () => void;
+    /** File → Language (and the other Docs tool dialogs): open one in the open editor. */
+    openTool?: (id: "language") => void;
+}
+interface BodyText {
+    text: string;
+    /** `offsets[i]` = the stream index of text position `i`; length is text.length + 1. */
+    offsets: number[];
+}
+/** The body's plain text and where each character sits in the stream. */
+declare function bodyTextOf(dataStream: string): BodyText;
+interface BodyEdit {
+    /** Stream range to remove (may be empty). */
+    start: number;
+    end: number;
+    /** Plain text to insert at `start` (may be empty). */
+    insert: string;
+}
+/**
+ * The ONE span that turns the current body into `next`: the longest common
+ * prefix and suffix stay untouched (with their formatting), only the middle
+ * changes. Null when nothing differs.
+ */
+declare function planBodyEdit(current: BodyText, next: string): BodyEdit | null;
+/** Apply `next` as the whole body text through the port. */
+declare function writeBodyText(port: DocumentBodyPort, next: string): {
+    changed: boolean;
+    removed: number;
+    inserted: number;
+};
+/** Shape check for an agent-sent body; throws a sentence the agent can act on. */
+declare function validateDocumentBody(value: unknown): string;
+/**
+ * The `document_body` write handler. `getPort` answers the live editor's port
+ * (null until Univer has mounted the document); `assertWritable` throws when
+ * the record is not loaded or the person may only view it.
+ */
+declare function documentBodyWriteHandler(deps: {
+    getPort: () => DocumentBodyPort | null;
+    assertWritable: (whatItBlocks: string) => void;
+}): DocumentBodyWriteHandler;
+
+export { type BodyEdit, type BodyText, type CreateDocumentArgs, DOCUMENT_BODY_MAX_LENGTH, DOCUMENT_DESCRIPTION_MAX_LENGTH, DOCUMENT_NAME_MAX_LENGTH, DOCUMENT_SAVE_DELAY_MS, type DocsHostPorts, type DocsSupabase, type DocumentAwareness, type DocumentBodyPort, type DocumentBodyWriteHandler, type DocumentCollabFactory, type DocumentCollabHandle, DocumentModel, type DocumentModelDeps, type DocumentSnapshotData, type DocumentViewPort, EMOJI_GROUPS, type Glyph, MIN_FIT_ZOOM, type ParkedDocumentEditor, SPECIAL_GROUPS, type SaveDocumentSnapshotArgs, bodyTextOf, configureDocsHost, copyDocument, createDocument, deleteDocument, discardFailedDocument, documentBodyWriteHandler, documentSourceLabel, fitZoomRatio, getDocsHost, getDocument, getLatestDocumentSnapshot, listAccessibleDocuments, listDocumentSnapshots, listTrashedDocuments, moveDocument, planBodyEdit, renameDocument, restoreDocument, sanitizeUniverDocSnapshot, saveDocumentSnapshot, searchSymbols, updateDocumentDescription, validateDocumentBody, validateDocumentDescription, validateDocumentName, writeBodyText };