revise 2.2.0 → 3.0.0

package/LICENSE

@@ -1,41 +1,24 @@
-# Revise SDK License
-
-Version 1.0
-
-Copyright © 2026 Migraine, Inc. (“Revise”). All rights reserved.
-
-By using the Revise SDK and accompanying documentation (“SDK”), you agree to these terms.
-
-## Free use
-
-Revise grants you a nonexclusive, worldwide, royalty-free license to copy, run, and integrate the SDK for:
-
-- **Evaluation:** Development, testing, and prototyping, including for planned commercial applications, without prior permission or a time limit. Evaluation excludes production use.
-- **Personal noncommercial apps:** Production apps run by an individual that do not generate revenue and are not intended to monetize, promote a paid offering, or support the operations of any organization.
-- **Education:** Production use by accredited nonprofit or public schools, colleges, and universities for teaching, learning, research, and their own internal operations.
-
-## Commercial use and source access
-
-Production use by businesses, nonprofit organizations, and government entities, whether internal or customer-facing, and all other production use outside the free permissions above, requires a separate written commercial license **before deployment**, including paid, subscription, ad-supported, and commercially intended apps that are temporarily free or not yet earning revenue. Obtain a license before converting a free permitted use to commercial use.
-
-Unpublished source code is not included. Source code access requires a separate commercial agreement expressly granting it.
-
-Please contact [sdk@revise.io](mailto:sdk@revise.io) for a commercial agreement.
-
-## Distribution and restrictions
-
-You may bundle, minify, host, and distribute the compiled SDK within permitted apps, including to browsers. Preserve copyright and license notices. Recipients may run the embedded SDK within those apps. Standalone SDK resale, sublicensing, or redistribution—including reusable SDK wrappers—is prohibited without written permission.
-
-Except to the extent applicable law expressly permits despite this restriction, you may not decompile, disassemble, reverse engineer, or modify the SDK, or attempt to derive its source code, algorithms, or internal structure. Configuring the SDK through its documented options is not modification. Revise retains ownership and all ungranted rights, and this license grants no rights to Revise names or logos except to identify the SDK; you retain your apps and documents. Third-party components retain their separate licenses.
-
-The SDK sends an anonymous usage ping as described in its documentation; you may disable it.
-
-## Termination
-
-A material breach terminates your rights and requires you to stop using and distributing the SDK. Rights are reinstated if a first breach is fully cured within 30 days of written notice.
-
-## Warranty and liability
-
-TO THE EXTENT PERMITTED BY LAW, THE SDK IS PROVIDED “AS IS,” WITHOUT WARRANTIES, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT, AND WITHOUT ANY SUPPORT OBLIGATION. REVISE AND ITS LICENSORS ARE NOT LIABLE FOR LOST PROFITS, LOST DATA, OR INDIRECT, INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES. THEIR TOTAL LIABILITY UNDER THIS LICENSE WILL NOT EXCEED US $100.
-
-Ownership, restrictions, and warranty/liability provisions survive termination. A separate written agreement controls conflicting terms. Invalid provisions do not invalidate the remainder. Each version of the SDK is licensed under the license included with it. This license is governed by the laws of the State of Delaware, USA, excluding its conflict-of-laws rules.
+MIT License
+
+Copyright (c) 2026 Migraine, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This package depends on @reviseio/engine, which is distributed separately
+under its own license (free for any use, including commercial).

package/README.md

@@ -1,42 +1,119 @@
 # revise
 
-A document editor library for React apps, with full DOCX support and tools for AI agents.
+The swiss army knife for documents. Read, edit, and redline Word documents
+from the command line or from TypeScript. Edits land as tracked changes, with
+comments, review, and undo, and untouched content is written back to the
+.docx byte for byte. Built for AI agents and the programs that run them.
+
+**Using a coding agent?** Paste this into it:
+
+```text
+Read https://revise.io/skills/cli.md and follow it.
+```
+
+## Install
+
+```bash
+npm i -g revise        # or: npx revise <command>
+```
+
+Node 20 or newer. No account, API key, or telemetry, and documents never
+leave your machine. Two things fetch over the network: PDF export downloads
+its fonts from revise.io, and an image you insert by URL is downloaded.
+
+## The CLI
+
+Every command names its file. Edits save the file in place.
 
 ```bash
-npm i revise
+revise outline contract.docx                     # headings with block ranges
+revise read contract.docx 0                       # blocks as HTML, with ids
+revise replace-text contract.docx "Provider" "Northstar"   # tracked change
+revise changes contract.docx                      # what's pending
+revise reject contract.docx --section 8           # review by section
+revise export contract.docx contract.pdf          # .docx .pdf .md .html .txt
+revise compare v1.docx v2.docx --out redline.docx # redline two versions
+revise undo contract.docx
+```
+
+`revise tools` lists the editing tools (insert, replace, move, tables,
+comments, footnotes, styles, headers and footers…) and `revise call` runs
+one with JSON input. `--author "Legal bot"` signs tracked changes, `--out
+copy.docx` saves an edit as a new file, and `-` reads or writes a pipe
+(`cat notes.md | revise convert - notes.docx`). `--json` on any command prints
+one versioned object ([contract](https://revise.io/developer/docs/revise/json)).
+`revise examples` shows more.
+
+## Agent skills
+
+The skill teaches a coding agent the CLI: reading by block id, tracked edits,
+review, creating documents, and the `xml` escape hatch.
+
+| Agent                             | Install                                                                                           |
+| --------------------------------- | ------------------------------------------------------------------------------------------------- |
+| Claude Code                       | `claude plugin marketplace add reviseio/skills`, then `claude plugin install revise@revise`       |
+| Codex, ChatGPT desktop            | `codex plugin marketplace add reviseio/skills`, then `codex plugin add revise@revise`             |
+| Cursor, Copilot, Windsurf, Cline… | `npx skills add reviseio/skills --skill revise`                                                   |
+| Anything else                     | `revise skill install` (into `.agents/skills` or `.claude/skills`), or `revise skill` to print it |
+
+Building a browser editor instead? The `revise-editor` skill covers
+[`@reviseio/editor`](https://www.npmjs.com/package/@reviseio/editor):
+`npx skills add reviseio/skills --skill revise-editor`.
+
+## The library
+
+```ts
+import { ReviseDocument } from "revise";
+
+const doc = await ReviseDocument.open("contract.docx", { author: "Legal bot" });
+await doc.replaceText("Provider", "Northstar"); // tracked changes
+await doc.reject({ section: "8" });
+const { bytes, fidelity } = await doc.export({ format: "docx" });
+doc.dispose();
+```
+
+Run the editing tools with typed input, or hand them to a model:
+
+```ts
+import Anthropic from "@anthropic-ai/sdk";
+import { ReviseDocument, agentTools } from "revise";
+
+const doc = await ReviseDocument.open("brief.docx");
+const { tools, handle } = agentTools(doc, { provider: "anthropic" });
+const client = new Anthropic();
+// Pass `tools` to client.messages.create(); answer each tool_use block in
+// the response with `await handle(block)`, which returns its tool_result.
 ```
 
-![The Revise editor embedded in a host application](https://developer.revise.io/images/revise-sdk-editor.png)
+### Collaboration servers
 
-## Getting started
+Seed a sync server's room from a file, and edit or export the live room:
 
-Get started with the [quickstart guide](https://developer.revise.io/editor-sdk/quickstart).
+```ts
+import { ReviseDocument, seedYDoc } from "revise";
 
-```tsx
-import ReviseEditor from "revise/editor";
-import "revise/style.css";
+// e.g. Hocuspocus onLoadDocument: safe on every connection
+await seedYDoc(room, "contract.docx");
 
-export function DocumentPane({ file }: { file: File }) {
-  return (
-    <ReviseEditor
-      initialDocuments={[{ id: "contract-1", title: "Contract", source: file }]}
-      onChange={(documentId, document) => {
-        console.log(documentId, "now has", document.children.length, "blocks");
-      }}
-    />
-  );
-}
+const doc = await ReviseDocument.fromYDoc(room, { author: "Review bot" });
+await doc.tools.call("replace", {
+  /* ... */
+});
+const { bytes } = await doc.export({ format: "docx" });
 ```
 
-The editor sends Revise one anonymous ping per page load, with its version and
-no user data or document content. Pass `telemetry={false}` to turn it off.
+The browser editor for the same documents is
+[`@reviseio/editor`](https://www.npmjs.com/package/@reviseio/editor).
+
+## Docs
 
-Refer to the [SDK Docs](https://developer.revise.io/editor-sdk) for the full editor API, including agentic tool calling.
+- [revise.io/developer/docs](https://revise.io/developer/docs)
+- [Build with AI](https://revise.io/developer/docs/build-with-ai): skills,
+  plugins, and Markdown versions of every page
+- [Changelog](https://revise.io/developer/docs/revise/changelog)
 
 ## License
 
-Revise is closed-source software, free for evaluation, personal projects, and
-education. Production use by businesses, nonprofits, and government requires a
-commercial license: see [LICENSE](./LICENSE) and
-[developer.revise.io/editor-sdk/license](https://developer.revise.io/editor-sdk/license),
-or email [sdk@revise.io](mailto:sdk@revise.io).
+MIT. `revise` runs on [`@reviseio/engine`](https://www.npmjs.com/package/@reviseio/engine),
+Revise's document engine, which is installed with it and is free for any use,
+including commercial, under its own license.

package/agent.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Revise's editing tools for your own agent loop, in the shape each model
+ * API expects: hand `tools` to the model, pass each tool call it makes to
+ * `handle`, and send back what `handle` returns.
+ *
+ *   const agent = agentTools(doc, { provider: "anthropic" });
+ *   const reply = await anthropic.messages.create({ model, tools: agent.tools, messages });
+ *   const results = await Promise.all(
+ *     reply.content.filter((b) => b.type === "tool_use").map(agent.handle),
+ *   );
+ *   messages.push({ role: "assistant", content: reply.content }, { role: "user", content: results });
+ *
+ * OpenAI Responses: pass `agent.tools` as `tools`, append every output item
+ * the model returned (reasoning and function_call items included) to your
+ * input, then the `function_call_output` items `handle` returns, and call
+ * again until the model stops calling tools.
+ *
+ * No model SDK is a dependency: plain objects in, plain objects out. Every
+ * call runs on the document's one tool session, so reads, searches, and
+ * edits share context across turns, and calls run one at a time (parallel
+ * tool calls are safe; they queue). The session remembers what the model
+ * has read: when your host compacts or drops the transcript, call
+ * `reset()` so it stops assuming the model still has that text. Tool
+ * descriptions mention "turns": here a turn is one model response.
+ */
+import type { ReviseToolResult } from "@reviseio/engine";
+import type { ReviseDocument } from "./document.js";
+export type AgentProvider = "anthropic" | "openai" | "openai-responses";
+export interface AgentToolsOptions {
+    provider: AgentProvider;
+    /** Cap on one tool result's text, in characters (default 100,000). Longer
+     * results are cut with a note telling the model how to page. */
+    maxResultChars?: number;
+    /** Only these tools (by name). */
+    include?: string[];
+    /** Every tool except these. */
+    exclude?: string[];
+}
+/** Anthropic Messages API: a `tool_use` content block. */
+export interface AnthropicToolUse {
+    type?: "tool_use";
+    id: string;
+    name: string;
+    input: unknown;
+}
+/** OpenAI Chat Completions: an entry of `message.tool_calls`. */
+export interface OpenAIToolCall {
+    id: string;
+    type?: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/** OpenAI Responses API: a `function_call` output item. */
+export interface OpenAIResponsesFunctionCall {
+    type?: "function_call";
+    call_id: string;
+    name: string;
+    arguments: string;
+}
+interface ProviderShapes {
+    anthropic: {
+        tool: {
+            name: string;
+            description: string;
+            input_schema: {
+                type: "object";
+                [key: string]: unknown;
+            };
+        };
+        call: AnthropicToolUse;
+        result: {
+            type: "tool_result";
+            tool_use_id: string;
+            content: string;
+            is_error?: boolean;
+        };
+    };
+    openai: {
+        tool: {
+            type: "function";
+            function: {
+                name: string;
+                description: string;
+                parameters: {
+                    [key: string]: unknown;
+                };
+            };
+        };
+        call: OpenAIToolCall;
+        result: {
+            role: "tool";
+            tool_call_id: string;
+            content: string;
+        };
+    };
+    "openai-responses": {
+        tool: {
+            type: "function";
+            name: string;
+            description: string;
+            parameters: {
+                [key: string]: unknown;
+            };
+            /** Revise's schemas use optional fields, which strict mode rejects. */
+            strict: false;
+        };
+        call: OpenAIResponsesFunctionCall;
+        result: {
+            type: "function_call_output";
+            call_id: string;
+            output: string;
+        };
+    };
+}
+export interface AgentTools<P extends AgentProvider> {
+    /** Tool definitions in the provider's format. */
+    tools: Array<ProviderShapes[P]["tool"]>;
+    /** Run one tool call; returns the provider's tool-result message. Never
+     * throws for a bad call: the model gets the error to correct itself. */
+    handle: (call: ProviderShapes[P]["call"]) => Promise<ProviderShapes[P]["result"]>;
+    /** Did the last handled calls change the document? Compare to decide
+     * whether to save. */
+    version: () => Uint8Array;
+    /** Forget what the model has read (after compacting its transcript). */
+    reset: () => Promise<void>;
+}
+/** A tool result as the text a model reads: the message, any tracked
+ * change ids, the document HTML it loaded, and its structured data (counts,
+ * paging, what changed), within a size budget. */
+export declare function formatToolResult(result: ReviseToolResult<string>, maxChars?: number): {
+    text: string;
+    isError: boolean;
+};
+export declare function agentTools<P extends AgentProvider>(doc: ReviseDocument, options: AgentToolsOptions & {
+    provider: P;
+}): AgentTools<P>;
+export {};

package/chunks/chunk-U5X47PZ6.js

@@ -0,0 +1,135 @@
+// revise: MIT License. https://revise.io/developer/docs
+import {
+  ReviseError
+} from "./chunk-U6YKQBKL.js";
+
+// src/embed-sdk/lib/package.ts
+import { engineModules } from "@reviseio/engine";
+import JSZip from "jszip";
+import { installDomShims } from "@reviseio/engine";
+async function listParts(bytes) {
+  const zip = await JSZip.loadAsync(bytes);
+  const parts = [];
+  for (const [path, entry] of Object.entries(zip.files)) {
+    if (entry.dir) continue;
+    parts.push({ path, bytes: (await entry.async("uint8array")).length });
+  }
+  return parts.sort((a, b) => a.path.localeCompare(b.path));
+}
+async function readPart(zip, part) {
+  const file = zip.file(part);
+  if (!file) {
+    throw new ReviseError(`No part "${part}" in this document.`, "no_such_part");
+  }
+  return file.async("string");
+}
+var UNITS = [
+  "w:rPr",
+  "w:pPr",
+  "w:p",
+  "w:tr",
+  "w:style",
+  "w:abstractNum",
+  "w:num",
+  "w:lvl",
+  "w:sectPr",
+  "w:tbl"
+];
+var CAT_MATCH_LIMIT = 20;
+async function catPart(bytes, part, match, limit = CAT_MATCH_LIMIT) {
+  const xml = await readPart(await JSZip.loadAsync(bytes), part);
+  if (!match) return [xml];
+  const found = /* @__PURE__ */ new Set();
+  let at = xml.indexOf(match);
+  while (at >= 0 && found.size < limit) {
+    let best;
+    for (const tag of UNITS) {
+      const start = Math.max(
+        xml.lastIndexOf(`<${tag} `, at),
+        xml.lastIndexOf(`<${tag}>`, at)
+      );
+      if (start < 0) continue;
+      const close = xml.indexOf(`</${tag}>`, start);
+      if (close < 0 || close < at) continue;
+      const unit = xml.slice(start, close + tag.length + 3);
+      if (!best || unit.length < best.length) best = unit;
+    }
+    found.add(
+      best ?? xml.slice(Math.max(0, at - 200), at + match.length + 200)
+    );
+    at = xml.indexOf(match, at + match.length);
+  }
+  return [...found];
+}
+var MODEL_READ_PARTS = /^word\/(document|styles|numbering|footnotes|endnotes|comments|header\d*|footer\d*)\.xml$/;
+async function assertWellFormed(part, xml) {
+  await installDomShims();
+  const parsed = new DOMParser().parseFromString(xml, "application/xml");
+  const error = parsed.getElementsByTagName("parsererror")[0];
+  if (error) {
+    throw new ReviseError(
+      `The patched ${part} is not well-formed XML: ${error.textContent?.trim().split("\n")[0] ?? "parse error"}. Nothing was changed.`,
+      "malformed_xml"
+    );
+  }
+}
+async function patchPackage(pkg, request, readFile) {
+  const zip = await JSZip.loadAsync(pkg);
+  const before = await readPart(zip, request.part);
+  let after;
+  let replacements = 0;
+  if (request.file !== void 0) {
+    after = readFile(request.file);
+    replacements = 1;
+  } else {
+    if (!request.find) {
+      throw new ReviseError(
+        "Give --find and --replace, or --file to replace the whole part.",
+        "usage"
+      );
+    }
+    const occurrences = before.split(request.find).length - 1;
+    if (occurrences === 0) {
+      throw new ReviseError(
+        `"${request.find}" does not occur in ${request.part}.`,
+        "find_not_found"
+      );
+    }
+    if (occurrences > 1 && !request.all) {
+      throw new ReviseError(
+        `"${request.find}" occurs ${occurrences} times in ${request.part}; add context to match once, or pass --all.`,
+        "find_ambiguous"
+      );
+    }
+    after = before.split(request.find).join(request.replace ?? "");
+    replacements = request.all ? occurrences : 1;
+  }
+  await assertWellFormed(request.part, after);
+  if (request.part === "word/document.xml") {
+    const { scanElementChildren } = await engineModules.xmlScan();
+    const shape = (xml) => scanElementChildren(xml, "w:body").children.map((child) => child.tag).join(",");
+    if (shape(before) !== shape(after)) {
+      throw new ReviseError(
+        "This patch adds, removes, or reorders body elements, which a direct patch cannot do. Use the editing tools for body structure. Nothing was changed.",
+        "body_shape_changed"
+      );
+    }
+  }
+  zip.file(request.part, after);
+  const bytes = await zip.generateAsync({
+    type: "uint8array",
+    compression: "DEFLATE"
+  });
+  return {
+    bytes,
+    replacements,
+    modelRead: MODEL_READ_PARTS.test(request.part)
+  };
+}
+
+export {
+  listParts,
+  CAT_MATCH_LIMIT,
+  catPart,
+  patchPackage
+};

package/chunks/chunk-U6YKQBKL.js

@@ -0,0 +1,15 @@
+// revise: MIT License. https://revise.io/developer/docs
+
+// src/embed-sdk/lib/errors.ts
+var ReviseError = class extends Error {
+  constructor(message, code = "error", options = {}) {
+    super(message);
+    this.code = code;
+    this.name = "ReviseError";
+    if (options.cause !== void 0) this.cause = options.cause;
+  }
+};
+
+export {
+  ReviseError
+};