revise 2.2.0 → 3.0.1

package/document.d.ts

@@ -0,0 +1,320 @@
+import * as Y from "yjs";
+import { ydocSourceFidelity, type ReviseServerExportFormat } from "@reviseio/engine";
+import type { ImageFetchPolicy, ReviseDocumentMeasurementData, ReviseToolDefinition, ReviseJsonObject, ReviseToolArguments, ReviseToolName, ReviseToolResult, ServerDocumentSession } from "@reviseio/engine";
+/** How faithfully the document exports back to its original Word file. */
+export type SourceFidelity = Awaited<ReturnType<typeof ydocSourceFidelity>>;
+import { type DocxExportOutcome } from "./docx.js";
+import type { RenderOptions, RenderResult } from "./render.js";
+export type DocumentMode = "suggesting" | "editing";
+export type ExportFormat = ReviseServerExportFormat | "pdf";
+/** Formats the library reads. */
+export declare const READABLE: RegExp;
+/** The export format a file name implies (`out.pdf` → "pdf"). */
+export declare function formatForPath(file: string): ExportFormat | undefined;
+/** A document to read: a path, or bytes with the file name they came from. */
+export type DocumentSource = string | {
+    bytes: Uint8Array;
+    filename: string;
+};
+export interface OpenOptions {
+    /** Who edits and comments: shown as the author of tracked changes. */
+    author?: string;
+    /** "suggesting" records edits as tracked changes (the default for Word
+     * files); "editing" applies them directly (the default for plain text). */
+    mode?: DocumentMode;
+    /** A stable id for this document (tool sessions, collaboration). */
+    documentId?: string;
+    /** How images inserted by URL are fetched. By default only public http(s)
+     * hosts are reachable; see ImageFetchPolicy. */
+    images?: ImageFetchPolicy;
+}
+export interface ChangeEntry {
+    id: string;
+    type: string;
+    author: string;
+    blockId?: string;
+    blockIndex?: number;
+    /** The heading of the section the change is in. */
+    section?: string;
+    deleted: string;
+    inserted: string;
+}
+/** Which tracked changes to settle: exactly one of `ids`, `all`, or a
+ * section filter (`section` and/or `exceptSection`). */
+export interface ChangeSelection {
+    ids?: string[];
+    all?: boolean;
+    /** "8", "8.", "Allocation of risk", or "8. Allocation". */
+    section?: string;
+    exceptSection?: string;
+}
+export interface SettleResult {
+    resolved: string[];
+    /** Requested ids that are not pending tracked changes. */
+    missing: string[];
+    /** Pending changes that could not be settled. */
+    unresolved: string[];
+}
+export interface GrepHit {
+    id: string;
+    blockIndex: number;
+    count: number;
+    text: string;
+}
+export interface ReplaceTextResult {
+    /** Occurrences replaced. */
+    replaced: number;
+    /** Ids of the blocks that contained the text. */
+    blocks: string[];
+    /** Tracked changes the replacement created (none in editing mode). */
+    changeIds: string[];
+    /** Blocks that contained the text but could not be edited. */
+    failures: Array<{
+        blockId: string;
+        code: string;
+        message: string;
+    }>;
+}
+export interface TextDiff {
+    /** Paragraph-level diff with word detail: `~ a [-old-]{+new+} b`. */
+    text: string;
+    changed: number;
+}
+export interface DocumentSummary {
+    text: string;
+    data: {
+        pages?: number;
+        words: number;
+        pageSize: string;
+        orientation: string;
+        pageInches: [number, number];
+        marginsInches: number[];
+        title?: string;
+        headings: Record<string, number>;
+        lists: number[];
+        tables: string[];
+        images: number;
+        headersFooters: Array<{
+            side: string;
+            slot: string;
+            text: string;
+        }>;
+        pendingTrackedChanges: number;
+    };
+}
+export interface ExportOptions {
+    format: ExportFormat;
+    /** "review" keeps tracked changes and comments; "final" accepts them.
+     * Only .docx can hold tracked changes: PDF, Markdown, HTML, and text
+     * always show them accepted. */
+    mode?: "review" | "final";
+    title?: string;
+}
+export interface ExportResult {
+    bytes: Uint8Array;
+    format: ExportFormat;
+    /** The mode the output actually has: only .docx can be "review". */
+    mode: "review" | "final";
+    /** Tracked changes still pending in the output. */
+    pendingTrackedChanges: number;
+    /** For .docx, what the export actually did: "graft" carried untouched
+     * content over byte for byte from the original file; "regenerated" wrote
+     * the whole file fresh (fallbackCode says why). */
+    fidelity: DocxExportOutcome | null;
+    warnings: string[];
+}
+/** Bytes of a document in a format, through graft export when the original
+ * Word package is available, with what the .docx export actually did. */
+export declare function exportYDoc(ydoc: Y.Doc, pkg: Uint8Array | null, { format, mode, title }: ExportOptions): Promise<{
+    bytes: Uint8Array;
+    outcome: DocxExportOutcome | null;
+}>;
+/**
+ * One open document: a live Revise document model plus the agent tool
+ * session that edits it. Nothing touches disk unless you export it.
+ */
+export declare class ReviseDocument {
+    private currentYDoc;
+    private currentSession;
+    private readonly settings;
+    private originalPackage;
+    /** False when the Y.Doc came from the caller (fromYDoc): it may be
+     * shared with an editor or a provider, so it is never replaced. */
+    private readonly ownsYDoc;
+    private disposed;
+    private queue;
+    private constructor();
+    /** Open a file (path) or bytes. Word files keep their original package,
+     * so untouched content exports byte for byte. */
+    static open(source: DocumentSource, options?: OpenOptions): Promise<ReviseDocument>;
+    /** Start a document from the HTML the tools read and write (headings,
+     * `data-style-id="Title"`, lists, tables), or from Markdown. */
+    static create(content?: {
+        html?: string;
+        markdown?: string;
+        title?: string;
+    }, options?: OpenOptions): Promise<ReviseDocument>;
+    /** Restore a document from `snapshot()` (or a bare Y.js update). Options
+     * override what the snapshot recorded. */
+    static restore(snapshot: Uint8Array, options?: OpenOptions): Promise<ReviseDocument>;
+    /** Wrap an existing Revise Y.Doc, e.g. one shared with an editor. The
+     * Y.Doc stays yours: `dispose()` leaves it intact, and `reload()` is not
+     * available (it would have to replace it). */
+    static fromYDoc(ydoc: Y.Doc, options?: OpenOptions & {
+        package?: Uint8Array | null;
+        title?: string;
+    }): Promise<ReviseDocument>;
+    private static build;
+    private static startSession;
+    private assertOpen;
+    /** Run `work` after every operation already queued on this document. */
+    private serial;
+    /** The live document model. Shared with `@reviseio/editor`. */
+    get ydoc(): Y.Doc;
+    /** The low-level tool session behind `tools`: an escape hatch for what
+     * the methods here don't cover. */
+    get session(): ServerDocumentSession;
+    get mode(): DocumentMode;
+    /** Switch between tracked changes ("suggesting") and direct edits. */
+    setMode(mode: DocumentMode): Promise<void>;
+    get author(): string | undefined;
+    get documentId(): string;
+    /** The original Word package that export grafts onto, if any. */
+    get package(): Uint8Array | null;
+    /** The complete document (versioned; includes the original Word package)
+     * to store or hand to `@reviseio/editor`, as of every operation queued
+     * before this call. Restore with `restore()`. */
+    snapshot(): Promise<Uint8Array>;
+    /** An opaque value that changes whenever the document does (including
+     * edits that only delete, which a state vector misses). */
+    version(): Uint8Array;
+    /**
+     * Re-read the document from new bytes (it changed elsewhere). Block ids
+     * carry over only where identity is provable (Word's paragraph ids, or
+     * identical content); `changedIds` lists kept ids whose content changed,
+     * so earlier reads of them are stale. Replaces the Y.Doc, so it is not
+     * available on a document made with `fromYDoc`.
+     */
+    reload(bytes: Uint8Array, filename: string): Promise<{
+        idsKept: number;
+        idsNew: number;
+        changedIds: string[];
+        removedIds: string[];
+    }>;
+    /** Start the tool session over: forget what the agent has read and
+     * searched (e.g. after the host compacts its transcript). */
+    resetToolContext(): Promise<void>;
+    /** Release the tool session. The document can't be used afterwards; a
+     * Y.Doc it created is destroyed, one passed to fromYDoc is left alone. */
+    dispose(): void;
+    readonly tools: {
+        /** Every editing tool's name, description, and JSON input schema. */
+        definitions: () => ReviseToolDefinition[];
+        /** Run a known tool with typed input. Expected failures come back as
+         * `{ ok: false, error }`; nothing throws for a bad edit. */
+        call: <Name extends ReviseToolName>(name: Name, ...args: ReviseToolArguments<Name>) => Promise<ReviseToolResult<Name>>;
+        /** Run a tool by name with untyped input (agent tool calls). Unknown
+         * tools and bad input come back as `{ ok: false, error }` too. */
+        run: (name: string, input?: ReviseJsonObject, options?: {
+            direct?: boolean;
+        }) => Promise<ReviseToolResult<string>>;
+    };
+    /** The document's title for exports: its saved title property (dc:title
+     * in a .docx, or set_title's), else the name it was opened under. */
+    private title;
+    /** set_title renames the document in the editor. In a file, the title is
+     * the document property (docProps/core.xml in a .docx, the PDF title), so
+     * it is saved there too; without this, the tool reported success and the
+     * saved file kept its old title. */
+    private afterTool;
+    /** Sections with their block ranges and word counts. */
+    outline(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<ReviseDocumentMeasurementData>;
+    /** Blocks, words, pending changes, and how faithfully it exports to Word. */
+    status(): Promise<{
+        blocks: number;
+        words: number;
+        pendingSuggestions: number;
+        fidelity: SourceFidelity | null;
+    }>;
+    /** Text-bearing blocks matching a pattern (paragraphs, headings, list
+     * items, table-cell paragraphs), with their ids. */
+    grep(pattern: string | RegExp, options?: {
+        ignoreCase?: boolean;
+    }): GrepHit[];
+    /** What the document holds, in one glance: page setup, header and footer
+     * text with live fields, title, headings, lists, tables, review state. */
+    summary(): Promise<DocumentSummary>;
+    /** Replace every exact occurrence, block by block (tracked changes in
+     * suggesting mode). `ids` limits it to those blocks. Replacing text with
+     * itself changes nothing and is not a failure. */
+    replaceText(find: string, replace: string, options?: {
+        ids?: string[];
+    }): Promise<ReplaceTextResult>;
+    /** Pending tracked changes with where they are and what they do. */
+    changes(filter?: {
+        section?: string;
+        exceptSection?: string;
+    }): Promise<ChangeEntry[]>;
+    private filteredChanges;
+    /** The tracked changes a selection would settle, without settling them. */
+    preview(selection: ChangeSelection): Promise<ChangeEntry[]>;
+    accept(selection: ChangeSelection): Promise<SettleResult>;
+    reject(selection: ChangeSelection): Promise<SettleResult>;
+    private selectedIds;
+    private settle;
+    /**
+     * What the pending tracked changes do to the text (before → after), or
+     * what changed since `baseline` (a snapshot).
+     */
+    diff(baseline?: Uint8Array): Promise<TextDiff>;
+    /** Write the document in a format. Reports what the output actually
+     * contains: its pending changes, and for .docx how much of the original
+     * file was carried over byte for byte. */
+    export(options: ExportOptions): Promise<ExportResult>;
+    /** Pages as images, laid out exactly as the editor lays them out. */
+    renderPages(options?: RenderOptions): Promise<RenderResult>;
+}
+export interface CompareResult {
+    /** The revised document with every difference as a tracked change. */
+    document: ReviseDocument;
+    stats: {
+        inlineChanges: number;
+        insertedBlocks: number;
+        deletedBlocks: number;
+        unmarkedBlocks: number;
+    };
+    untrackedRegions: string[];
+    /** Accepting every change in the exported redline (read back from the
+     * .docx) gives the revised text; rejecting every change gives the
+     * original. Text only: formatting and comments are not compared. */
+    verified: {
+        acceptAllGivesRevised: boolean;
+        rejectAllGivesOriginal: boolean;
+    };
+}
+/** A redline: `revised` with every difference from `original` tracked. */
+/**
+ * Seed a collaboration room (a Y.Doc your sync server owns) from a file, and
+ * say whether it wrote anything. A room that already holds a document is
+ * left alone, so call it on every connection:
+ *
+ *   onLoadDocument: async ({ document }) => {
+ *     await seedYDoc(document, "contract.docx");
+ *   }
+ *
+ * Two peers that both seeded an empty room before syncing are repaired to a
+ * single copy. A Word file is stored in the room too, so any session over
+ * it (`ReviseDocument.fromYDoc`, or the editor) exports untouched content
+ * byte for byte.
+ */
+export declare function seedYDoc(ydoc: Y.Doc, source: DocumentSource): Promise<boolean>;
+export declare function compare(originalSource: DocumentSource, revisedSource: DocumentSource, options?: OpenOptions): Promise<CompareResult>;
+/** Convert a document to another format in one step. */
+export declare function convert(source: DocumentSource, format: ExportFormat, options?: {
+    mode?: "review" | "final";
+}): Promise<Uint8Array>;
+/** Section filter: "8", "8.", "Allocation of risk", or "8. Allocation". */
+export declare function inSection(entry: ChangeEntry, query: string): boolean;

package/docx.d.ts

@@ -0,0 +1,73 @@
+import * as Y from "yjs";
+import type { DocRoot } from "@reviseio/engine";
+/** What a .docx export actually did. */
+export interface DocxExportOutcome {
+    /** "graft": untouched content copied byte for byte from the original;
+     * "regenerated": the whole file written fresh (no original, or graft
+     * refused it, see fallbackCode). */
+    method: "graft" | "regenerated";
+    exact: boolean;
+    regeneratedBlocks: number;
+    fallbackCode?: string;
+}
+/**
+ * The session as a .docx: the model's changes grafted onto the session's
+ * package. Without a package (a document not opened from .docx) it is the
+ * ordinary export. Paragraphs and rows the export writes fresh get a
+ * w14:paraId if they lack one (see stampParaIds); untouched ones never do.
+ * Reports what the converter actually did, not what it was asked to do.
+ */
+export declare function exportSessionDocx(ydoc: Y.Doc, pkg: Uint8Array | null, mode?: "review" | "final"): Promise<{
+    bytes: Uint8Array;
+    outcome: DocxExportOutcome;
+}>;
+/** The w14:paraId revise writes for a block it created: derived from the
+ * block id, so it is the same on every save and maps back on re-read.
+ * Word's rules: 8 hex digits, below 0x80000000. */
+export declare function derivedParaId(blockId: string, salt?: number): string;
+/**
+ * Give paragraphs and table rows a w14:paraId where they lack one, but only
+ * in blocks the export writes fresh (`regenerated`; null = every block):
+ * untouched content keeps its exact bytes. Returns a copy.
+ */
+/** What graft export copies from the original: whole parts, and changed
+ * rows whose own properties (their head) are unchanged. */
+interface GraftKept {
+    whole: Set<string>;
+    head: Set<string>;
+}
+export declare function stampParaIds(doc: DocRoot, regenerated: ReadonlySet<string> | null, 
+/** Parts the graft copies from the original: never stamped. */
+kept?: GraftKept): DocRoot;
+export interface IdMatchReport {
+    /** Ids carried over to the re-read document. */
+    kept: number;
+    /** New blocks (or ones with no provable identity): fresh ids. */
+    fresh: number;
+    /** Kept ids whose content changed: earlier reads of them are stale. */
+    changedIds: string[];
+    /** Old ids that no longer exist. */
+    removedIds: string[];
+}
+/** Carry ids from `previous` onto the re-imported `next` (mutated). */
+export declare function matchIds(previous: DocRoot, next: DocRoot): IdMatchReport;
+export interface SyncResult {
+    ydoc: Y.Doc;
+    pkg: Uint8Array;
+    idsKept: number;
+    idsNew: number;
+    /** Kept ids whose content changed: earlier reads of them are stale. */
+    changedIds: string[];
+    /** Ids that no longer exist. */
+    removedIds: string[];
+    changedBlocks: number;
+    changedStyles: string[];
+}
+/**
+ * Make `bytes` (any supported format) the session's model: parse them, carry
+ * block ids over where identity is provable (see matchIds), and
+ * keep a .docx as the graft package. Used after an xml patch and when the
+ * file changed outside revise.
+ */
+export declare function relearn(ydoc: Y.Doc, bytes: Uint8Array, filename: string): Promise<SyncResult>;
+export {};

package/errors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The one error type the library throws for expected failures (a missing
+ * file, an unsupported format, a malformed patch). `code` is stable and
+ * machine-readable; the CLI prints it as `error <code>: <message>`.
+ */
+export declare class ReviseError extends Error {
+    readonly code: string;
+    /** The underlying error, when this one wraps another (a filesystem or
+     * parser failure). */
+    readonly cause?: unknown;
+    constructor(message: string, code?: string, options?: {
+        cause?: unknown;
+    });
+}