revise 3.0.1 → 3.1.0

package/document.d.ts

@@ -39,14 +39,27 @@ export interface ChangeEntry {
     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". */
+/** Narrows tracked changes by where they are. Filters combine: a change
+ * must pass every one given. */
+export interface ChangeFilter {
+    /** A heading and everything under it, subsections included: its number
+     * ("8", "8.", "8.1", including Word's automatic numbering) or its title
+     * ("Allocation of risk", or part of it). */
     section?: string;
+    /** Everything outside that section. */
     exceptSection?: string;
+    /** Block ids, and inclusive `{ from, to }` ranges in document order. Ids
+     * of list items, table cells, and blocks inside them work. */
+    blocks?: Array<string | {
+        from: string;
+        to: string;
+    }>;
+}
+/** Which tracked changes to settle: exactly one of `ids`, `all`, or
+ * filters (`section`, `exceptSection`, `blocks`). */
+export interface ChangeSelection extends ChangeFilter {
+    ids?: string[];
+    all?: boolean;
 }
 export interface SettleResult {
     resolved: string[];
@@ -55,17 +68,47 @@ export interface SettleResult {
     /** Pending changes that could not be settled. */
     unresolved: string[];
 }
+/** How pending tracked changes read: "tracked" shows them (deleted and
+ * inserted text, marked), "accepted" as if every one were accepted (what
+ * the editing tools see), "original" as if every one were rejected. */
+export type ReadView = "tracked" | "accepted" | "original";
+export interface GrepMatch {
+    text: string;
+    /** Inside text a pending change inserted or deleted; null for text no
+     * change touches. */
+    change: "inserted" | "deleted" | null;
+    changeId: string | null;
+}
 export interface GrepHit {
     id: string;
     blockIndex: number;
     count: number;
+    /** The block's text in the view. Tracked marks changes inline:
+     * "Fees are [-$100-]{+$120+} per hour." */
     text: string;
+    matches: GrepMatch[];
+}
+/** Where a block is: the body, a page header or footer, or a note. */
+export type TextRegion = "body" | "header" | "footer" | "footnote" | "endnote";
+export interface ReplaceAllOptions {
+    /** Only in these blocks (ids from `read`, `grep`, `search`). */
+    blocks?: string[];
+    /** @deprecated The older name for `blocks`. */
+    ids?: string[];
+    /** Match regardless of case: "Provider" also finds "PROVIDER". */
+    ignoreCase?: boolean;
+    /** Match characters exactly. By default curly and straight quotes,
+     * non-breaking and ordinary spaces, and non-breaking and ordinary
+     * hyphens match each other, the way Word's Find treats quotes. */
+    exact?: boolean;
 }
 export interface ReplaceTextResult {
     /** Occurrences replaced. */
     replaced: number;
     /** Ids of the blocks that contained the text. */
     blocks: string[];
+    /** Occurrences replaced in each part of the document. */
+    regions: Partial<Record<TextRegion, number>>;
     /** Tracked changes the replacement created (none in editing mode). */
     changeIds: string[];
     /** Blocks that contained the text but could not be edited. */
@@ -74,6 +117,13 @@ export interface ReplaceTextResult {
         code: string;
         message: string;
     }>;
+    /** Text that would match with looser options but wasn't replaced: other
+     * capitalization (`ignoreCase`) or other quotes and spaces (`exact`). */
+    nearMisses: Array<{
+        text: string;
+        count: number;
+        reason: "case" | "characters";
+    }>;
 }
 export interface TextDiff {
     /** Paragraph-level diff with word detail: `~ a [-old-]{+new+} b`. */
@@ -108,6 +158,10 @@ export interface ExportOptions {
      * Only .docx can hold tracked changes: PDF, Markdown, HTML, and text
      * always show them accepted. */
     mode?: "review" | "final";
+    /** The same choice in read's words, and one more: "tracked" is
+     * "review", "accepted" is "final", and "original" writes the document as
+     * it was before every pending change. Give `mode` or `view`, not both. */
+    view?: ReadView;
     title?: string;
 }
 export interface ExportResult {
@@ -115,6 +169,8 @@ export interface ExportResult {
     format: ExportFormat;
     /** The mode the output actually has: only .docx can be "review". */
     mode: "review" | "final";
+    /** The view the output shows: "tracked" only for a .docx. */
+    view: ReadView;
     /** Tracked changes still pending in the output. */
     pendingTrackedChanges: number;
     /** For .docx, what the export actually did: "graft" carried untouched
@@ -243,21 +299,37 @@ export declare class ReviseDocument {
      * items, table-cell paragraphs), with their ids. */
     grep(pattern: string | RegExp, options?: {
         ignoreCase?: boolean;
+        view?: ReadView;
     }): GrepHit[];
+    /**
+     * HTML the read tools returned (`read_blocks_from_index`,
+     * `read_specific_blocks`), in a view. The tools read the accepted view;
+     * "tracked" marks pending changes as `<ins>`/`<del>` with
+     * `data-change-id` and `data-author`, and shows whole blocks a change
+     * deletes where they were; "original" shows the text before every change.
+     * Block ids are unchanged. The editing tools read `<ins>` as its text and
+     * ignore `<del>`, so tracked HTML pasted back edits the accepted text.
+     */
+    viewHtml(html: string, view: ReadView): Promise<string>;
     /** 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>;
+    /**
+     * Replace every occurrence everywhere: the body, tables, lists, page
+     * headers and footers, and footnotes and endnotes. Tracked changes in
+     * suggesting mode. Curly and straight quotes and non-breaking spaces match
+     * each other unless `exact`, and the replacement keeps the document's
+     * characters (see matchDocumentCharacters). Replacing text with itself
+     * changes nothing and is not a failure.
+     */
+    replaceAll(find: string, replace: string, options?: ReplaceAllOptions): Promise<ReplaceTextResult>;
+    /** @deprecated The 3.0 name of `replaceAll`. */
+    replaceText(find: string, replace: string, options?: ReplaceAllOptions): Promise<ReplaceTextResult>;
+    /** The document as it was before every pending change, exported from
+     * a copy: this document keeps its changes. */
+    private exportOriginal;
     /** Pending tracked changes with where they are and what they do. */
-    changes(filter?: {
-        section?: string;
-        exceptSection?: string;
-    }): Promise<ChangeEntry[]>;
+    changes(filter?: ChangeFilter): Promise<ChangeEntry[]>;
     private filteredChanges;
     /** The tracked changes a selection would settle, without settling them. */
     preview(selection: ChangeSelection): Promise<ChangeEntry[]>;
@@ -315,6 +387,14 @@ export declare function compare(originalSource: DocumentSource, revisedSource: D
 /** Convert a document to another format in one step. */
 export declare function convert(source: DocumentSource, format: ExportFormat, options?: {
     mode?: "review" | "final";
+    view?: ReadView;
 }): Promise<Uint8Array>;
-/** Section filter: "8", "8.", "Allocation of risk", or "8. Allocation". */
-export declare function inSection(entry: ChangeEntry, query: string): boolean;
+/** Whether a heading is the one a section query names: "8", "8.", "8.1",
+ * "Allocation of risk", or "8. Allocation". */
+export declare function headingMatches(title: string, query: string): boolean;
+/** A --blocks query: block ids and `first..last` ranges ("…" and "..."
+ * work too), e.g. "a1,b2..c3". */
+export declare function parseBlockQuery(query: string): Array<string | {
+    from: string;
+    to: string;
+}>;

package/index.d.ts

@@ -2,14 +2,14 @@
  * `revise`: read, edit, review, render, and convert documents from Node.
  *
  *   const doc = await ReviseDocument.open("contract.docx", { author: "Legal bot" });
- *   await doc.replaceText("Provider", "Northstar");      // tracked changes
+ *   await doc.replaceAll("Provider", "Northstar");      // tracked changes
  *   await doc.reject({ section: "8" });
  *   const { bytes } = await doc.export({ format: "docx" });
  *   fs.writeFileSync("contract-out.docx", bytes);
  *
  * The `revise` CLI is built on exactly this API.
  */
-export { ReviseDocument, compare, convert, formatForPath, seedYDoc, type ChangeEntry, type ChangeSelection, type CompareResult, type DocumentMode, type DocumentSource, type DocumentSummary, type ExportFormat, type ExportOptions, type ExportResult, type GrepHit, type OpenOptions, type ReplaceTextResult, type SettleResult, type TextDiff, } from "./document.js";
+export { ReviseDocument, compare, convert, formatForPath, seedYDoc, type ChangeEntry, type ChangeFilter, type ChangeSelection, type CompareResult, type DocumentMode, type DocumentSource, type DocumentSummary, type ExportFormat, type ExportOptions, type ExportResult, type GrepHit, type GrepMatch, type ReadView, type OpenOptions, type ReplaceAllOptions, type ReplaceTextResult, type TextRegion, type SettleResult, type TextDiff, } from "./document.js";
 export { agentTools, formatToolResult, type AgentProvider, type AgentTools, type AgentToolsOptions, type AnthropicToolUse, type OpenAIResponsesFunctionCall, type OpenAIToolCall, } from "./agent.js";
 export { catPart, listParts, patchPackage, type PatchRequest, type PatchResult, } from "./package.js";
 export type { ImageFetchPolicy, ReviseJsonObject, ReviseToolName, ReviseToolResult, ServerDocumentSession, } from "@reviseio/engine";

package/index.js

@@ -7,7 +7,7 @@ import {
   formatForPath,
   formatToolResult,
   seedYDoc
-} from "./chunks/chunk-ZLQVPMBN.js";
+} from "./chunks/chunk-SCNG3PKR.js";
 import {
   catPart,
   listParts,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "revise",
-  "version": "3.0.1",
-  "reviseBuild": "7ef88f310",
+  "version": "3.1.0",
+  "reviseBuild": "7cded52c5",
   "description": "Read, edit, and redline Word documents from the command line or TypeScript, with tracked changes, comments, and tools for AI agents.",
   "keywords": [
     "docx",
@@ -55,7 +55,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@reviseio/engine": "3.0.1",
+    "@reviseio/engine": "3.1.0",
     "jszip": "^3.10.1",
     "yjs": "^13.6.27"
   },