web-doc 0.7.0 → 0.9.0

package/dist/edit/docx/types.d.ts

@@ -1,4 +1,4 @@
-import type { ApplyOptions, BinaryData, EditColor, EditElement, EditReceipt, EditSessionBase, SavedDocument, SaveOptions, TextRange } from "../types.js";
+import type { ApplyOptions, BinaryData, EditColor, EditElement, EditReceipt, EditSessionBase, ReadOptions, ReadResult, SavedDocument, SaveOptions, TextRange } from "../types.js";
 export type DocxElementKind = "paragraph" | "table" | "image" | "other";
 export type DocxTextAlign = "left" | "center" | "right" | "justify";
 /** Word's sixteen highlight colours (`w:highlight/@w:val`). */
@@ -54,6 +54,14 @@ export interface DocxElement extends EditElement {
     readonly textStyle?: DocxTextStyle;
     /** Present for a paragraph. */
     readonly paragraphStyle?: DocxParagraphStyle;
+    /**
+     * Present for a paragraph in a table cell: the cell's row and its place in
+     * the row, both from 0. Paragraphs move only among those of the same cell.
+     */
+    readonly cell?: {
+        readonly row: number;
+        readonly column: number;
+    };
     /** Present for a table: cell text by row. */
     readonly table?: {
         readonly rows: readonly (readonly string[])[];
@@ -165,11 +173,26 @@ export interface DocxInsertImageOperation {
 export type DocxOperation = DocxReplaceTextOperation | DocxSetTextStyleOperation | DocxSetParagraphStyleOperation | DocxInsertParagraphOperation | DocxDeleteElementOperation | DocxMoveElementOperation | DocxInsertTableOperation | DocxSetTableCellOperation | DocxInsertImageOperation;
 /** DOCX saves have no fields of their own. */
 export type DocxSaveOptions = SaveOptions;
+/** One revision of a paragraph, as `getRevisions()` lists them in document order. */
+export interface DocxRevision {
+    readonly kind: "ins" | "del" | "moveFrom" | "moveTo" | "rPrChange" | "pPrChange";
+    /** The `w:id`; -1 when the file leaves it out. */
+    readonly id: number;
+    readonly author?: string;
+    /** ISO 8601, as the file writes it. */
+    readonly date?: string;
+    /** Runs of the paragraph, its paragraph mark, or the paragraph's properties. */
+    readonly scope: "runs" | "mark" | "paragraph";
+    /** The inserted, deleted or restyled text; "\n" for a paragraph mark; absent for a property change. */
+    readonly text?: string;
+}
 /** An operation's fields without its `op`, as the typed methods take them. */
 export type DocxFields<T extends DocxOperation> = T extends unknown ? Omit<T, "op"> : never;
 export interface DocxEditSession extends EditSessionBase<DocxOperation, DocxElement> {
     readonly format: "docx";
     save(options?: DocxSaveOptions): Promise<SavedDocument>;
+    /** The tracked changes a paragraph holds, in document order; empty for other elements. */
+    getRevisions(elementId: string, options?: ReadOptions): Promise<ReadResult<DocxRevision>>;
     /** Replaces the whole text of a paragraph, or the part a range covers. */
     replaceText(fields: DocxFields<DocxReplaceTextOperation>, options?: ApplyOptions): Promise<EditReceipt>;
     /** Changes run properties; unspecified ones keep their bytes. */

package/dist/edit/docx/write.d.ts

@@ -3,6 +3,10 @@ import { type XmlElement, type XmlPart } from "../ooxml/xml.js";
 import type { EditColor } from "../types.js";
 import { type DocxStyles } from "./style.js";
 import type { DocxParagraphStyleChange, DocxTextStyleChange } from "./types.js";
+/** Children of `w:rPr` in schema order (CT_RPr). */
+export declare const RPR_ORDER: string[];
+/** Children of `w:pPr` in schema order (CT_PPr). */
+export declare const PPR_ORDER: string[];
 /** Why a text cannot be written, or undefined when it can. */
 export declare function textProblem(text: string): string | undefined;
 /** Why a value cannot be written as an attribute: text problems plus the breaks text may hold. */
@@ -23,15 +27,25 @@ export declare function runXml(rPr: string, content: string): string;
  * where the schema puts them. Returns "" for no properties at all.
  */
 export declare function mergedProperties(part: XmlPart, source: XmlElement | undefined, tag: "w:rPr" | "w:pPr", order: readonly string[], set: ReadonlyMap<string, string | null>): string;
-/** `w:rPr` bytes with a text style change applied. */
-export declare function changedRunProperties(part: XmlPart, rPr: XmlElement | undefined, change: DocxTextStyleChange, styles: DocxStyles): string;
+/**
+ * `w:rPr` bytes with a text style change applied. With `revision` (the
+ * attributes of a tracked change) the previous properties are kept in a
+ * `w:rPrChange`, so Word shows the change as a suggestion.
+ */
+export declare function changedRunProperties(part: XmlPart, rPr: XmlElement | undefined, change: DocxTextStyleChange, styles: DocxStyles, revision?: string): string;
 /** `w:color` for a colour: RGB, automatic, or a theme name with the theme's value. */
 export declare function colorXml(color: EditColor, styles: DocxStyles): string;
-/** `w:pPr` bytes with alignment and spacing changed, other children kept. */
-export declare function changedParagraphProperties(part: XmlPart, pPr: XmlElement | undefined, change: DocxParagraphStyleChange): string;
+/** The children of a properties element as bytes, the named ones left out. */
+export declare function innerPropertiesXml(part: XmlPart, properties: XmlElement | undefined, without: readonly string[]): string;
+/**
+ * `w:pPr` bytes with alignment and spacing changed, other children kept.
+ * With `revision` the previous paragraph properties are kept in a
+ * `w:pPrChange`.
+ */
+export declare function changedParagraphProperties(part: XmlPart, pPr: XmlElement | undefined, change: DocxParagraphStyleChange, revision?: string): string;
 export declare function alignValue(align: NonNullable<DocxParagraphStyleChange["align"]>): string;
 /** `w:pPr` bytes with the paragraph mark's `w:rPr` changed (created when absent). */
-export declare function paragraphMarkProperties(part: XmlPart, pPr: XmlElement | undefined, change: DocxTextStyleChange, styles: DocxStyles): string;
+export declare function paragraphMarkProperties(part: XmlPart, pPr: XmlElement | undefined, change: DocxTextStyleChange, styles: DocxStyles, revision?: string): string;
 /** `w:pPr` bytes without the section properties, for a paragraph copied next to one that ends a section. */
 export declare function paragraphPropertiesWithoutSection(part: XmlPart, pPr: XmlElement | undefined): string;
 /**

package/dist/edit/docx/write.js

@@ -11,7 +11,7 @@ import { LINE_BREAK, PAGE_BREAK, TAB } from "./text.js";
  */
 const MC_NS = "http://schemas.openxmlformats.org/markup-compatibility/2006";
 /** Children of `w:rPr` in schema order (CT_RPr). */
-const RPR_ORDER = [
+export const RPR_ORDER = [
     "rStyle",
     "rFonts",
     "b",
@@ -54,7 +54,7 @@ const RPR_ORDER = [
     "rPrChange",
 ];
 /** Children of `w:pPr` in schema order (CT_PPr). */
-const PPR_ORDER = [
+export const PPR_ORDER = [
     "pStyle",
     "keepNext",
     "keepLines",
@@ -215,9 +215,15 @@ export function mergedProperties(part, source, tag, order, set) {
 function toggleXml(local, on) {
     return on ? `<w:${local}/>` : `<w:${local} w:val="0"/>`;
 }
-/** `w:rPr` bytes with a text style change applied. */
-export function changedRunProperties(part, rPr, change, styles) {
+/**
+ * `w:rPr` bytes with a text style change applied. With `revision` (the
+ * attributes of a tracked change) the previous properties are kept in a
+ * `w:rPrChange`, so Word shows the change as a suggestion.
+ */
+export function changedRunProperties(part, rPr, change, styles, revision) {
     const set = new Map();
+    if (revision !== undefined)
+        set.set("rPrChange", `<w:rPrChange${revision}>${wrapped("w:rPr", innerPropertiesXml(part, rPr, ["rPrChange"]))}</w:rPrChange>`);
     if (change.bold !== undefined) {
         set.set("b", toggleXml("b", change.bold));
         set.set("bCs", toggleXml("bCs", change.bold));
@@ -261,9 +267,26 @@ function fontsXml(part, rPr, family) {
     const rest = kept.map((a) => ` ${a.name}="${a.rawValue}"`).join("");
     return `<w:rFonts w:ascii="${face}" w:hAnsi="${face}"${rest}/>`;
 }
-/** `w:pPr` bytes with alignment and spacing changed, other children kept. */
-export function changedParagraphProperties(part, pPr, change) {
+/** `inner` inside `tag`, self-closing when empty. */
+function wrapped(tag, inner) {
+    return inner.length === 0 ? `<${tag}/>` : `<${tag}>${inner}</${tag}>`;
+}
+/** The children of a properties element as bytes, the named ones left out. */
+export function innerPropertiesXml(part, properties, without) {
+    return (properties?.children ?? [])
+        .filter((child) => !without.includes(child.local))
+        .map((child) => sliceOf(part, child))
+        .join("");
+}
+/**
+ * `w:pPr` bytes with alignment and spacing changed, other children kept.
+ * With `revision` the previous paragraph properties are kept in a
+ * `w:pPrChange`.
+ */
+export function changedParagraphProperties(part, pPr, change, revision) {
     const set = new Map();
+    if (revision !== undefined)
+        set.set("pPrChange", `<w:pPrChange${revision}>${wrapped("w:pPr", innerPropertiesXml(part, pPr, ["rPr", "sectPr", "pPrChange"]))}</w:pPrChange>`);
     if (change.align !== undefined)
         set.set("jc", `<w:jc w:val="${alignValue(change.align)}"/>`);
     if (change.spacing !== undefined) {
@@ -304,9 +327,9 @@ export function alignValue(align) {
     }
 }
 /** `w:pPr` bytes with the paragraph mark's `w:rPr` changed (created when absent). */
-export function paragraphMarkProperties(part, pPr, change, styles) {
+export function paragraphMarkProperties(part, pPr, change, styles, revision) {
     const rPr = pPr?.children.find((child) => child.local === "rPr" && child.namespace === W_NS);
-    const changed = changedRunProperties(part, rPr, change, styles);
+    const changed = changedRunProperties(part, rPr, change, styles, revision);
     return mergedProperties(part, pPr, "w:pPr", PPR_ORDER, new Map([["rPr", changed || null]]));
 }
 /** `w:pPr` bytes without the section properties, for a paragraph copied next to one that ends a section. */

package/dist/edit/engine.d.ts

@@ -1,6 +1,6 @@
 import type { DocumentFormat, RegisteredFont, ResourceLimits, TextRun, ViewerWarning } from "../contracts.js";
 import type { EditSession } from "./sessions.js";
-import type { EditableFormat, EditElement, EditFindOptions, EditOperation, EditSessionBase, ElementQuery, OperationIssue, OperationSchemaSet, PagePoint, ReadItem, ReadOptions, ReadResult, TextTarget } from "./types.js";
+import type { ChangeMode, EditableFormat, EditElement, EditFindOptions, EditOperation, EditSessionBase, ElementQuery, OperationIssue, OperationSchemaSet, PagePoint, ReadItem, ReadOptions, ReadResult, TextTarget } from "./types.js";
 export interface EditEngineContext {
     readonly format: EditableFormat;
     readonly fileName?: string;
@@ -16,6 +16,8 @@ export interface EditEngineContext {
  * earlier calls and carry the same envelope as the core's own reads.
  */
 export interface EditSessionCore extends EditSessionBase<EditOperation, EditElement> {
+    /** The host's limits, for reads a typed session builds over the core. */
+    readonly limits: ResourceLimits;
     readItem<T>(options: ReadOptions | undefined, task: (engine: EditEngine, signal: AbortSignal) => Promise<T | undefined>): Promise<ReadItem<T>>;
     readItems<T>(options: ReadOptions | undefined, task: (engine: EditEngine, signal: AbortSignal) => Promise<readonly T[]>): Promise<ReadResult<T>>;
 }
@@ -44,8 +46,17 @@ export interface MaterializedDocument {
     /** For example `privacy-not-guaranteed` when a PDF full save could not be compacted. */
     readonly warnings: readonly ViewerWarning[];
 }
+/** How a batch is written; travels with the batch to the engine and into the history, so a replay writes it the same way. */
+export interface BatchMode {
+    /** Default `direct`; `tracked` writes revisions where the format has them. */
+    readonly changeMode?: ChangeMode;
+    /** The author of tracked changes. */
+    readonly author?: string;
+    /** ISO 8601, the date of tracked changes. */
+    readonly timestamp?: string;
+}
 /** A batch with the identity the core assigned to the state after it. */
-export interface EngineBatch {
+export interface EngineBatch extends BatchMode {
     /** Unique within the session and never reused; engines derive created ids from it. */
     readonly stateId: number;
     readonly operations: readonly EditOperation[];
@@ -82,7 +93,7 @@ export interface EngineChange {
 export interface EditEngine {
     readonly schemas: OperationSchemaSet;
     /** Validates against the current state; an empty result means the batch can be applied. */
-    validate(operations: readonly EditOperation[], signal: AbortSignal): Promise<readonly OperationIssue[]>;
+    validate(operations: readonly EditOperation[], signal: AbortSignal, mode?: BatchMode): Promise<readonly OperationIssue[]>;
     /**
      * Applies an already validated batch to the working copy. Same-batch
      * references (`"$<n>"` targets) are resolved here; one that resolves to an

package/dist/edit/history.d.ts

@@ -1,6 +1,6 @@
-import type { EngineBatch } from "./engine.js";
+import type { BatchMode, EngineBatch } from "./engine.js";
 import type { EditOperation } from "./types.js";
-export interface HistoryEntry {
+export interface HistoryEntry extends BatchMode {
     readonly operations: readonly EditOperation[];
     readonly label?: string;
     /** Ids the batch created; an undo removes them again. */
@@ -15,6 +15,19 @@ export interface HistoryEntry {
     readonly pageCountAfter: number;
     /** Identifies the content after this batch; equal ids mean equal content. */
     readonly stateId: number;
+    /**
+     * A restore to a named checkpoint: the content after this entry is the
+     * checkpoint's, so a replay starts from its retained bytes or from the
+     * original plus `batches`, never from the entries before.
+     */
+    readonly base?: HistoryBase;
+}
+/** Where a restore entry's content comes from. */
+export interface HistoryBase {
+    /** The checkpoint's state id; its bytes may be retained under it. */
+    readonly stateId: number;
+    /** The batches that build the checkpoint's state from the original. */
+    readonly batches: readonly EngineBatch[];
 }
 /**
  * Linear undo history over an immutable original. Entries beyond the limit are
@@ -35,6 +48,8 @@ export declare class EditHistory {
     get pageCount(): number;
     /** State ids of every entry still in the history, folded and redo tail included. */
     get stateIds(): readonly number[];
+    /** Every entry still in the history: folded ones, then the undoable ones and the redo tail. */
+    get allEntries(): readonly HistoryEntry[];
     /** The entry `undo()` would revert, if any. */
     get undoEntry(): HistoryEntry | undefined;
     /** The entry `redo()` would re-apply, if any. */
@@ -46,8 +61,17 @@ export declare class EditHistory {
     /** Entries applied when `position` undoable entries are applied, folded ones first. */
     entriesAt(position: number): readonly HistoryEntry[];
     get position(): number;
-    push(entry: Omit<HistoryEntry, "stateId">): HistoryEntry;
+    /**
+     * Appends an entry with a fresh state id, or with `stateId` when the entry
+     * reproduces a known state (a restore to a checkpoint): the same id means
+     * the same content, so `dirty` stays exact.
+     */
+    push(entry: Omit<HistoryEntry, "stateId">, stateId?: number): HistoryEntry;
     undo(): void;
     redo(): void;
     clear(): void;
 }
+/** The engine batch an entry replays as: its operations and how they were written. */
+export declare function batchOf(entry: HistoryEntry): EngineBatch;
+/** The write mode fields of a batch or an entry, only those set. */
+export declare function modeOf(mode: BatchMode): BatchMode;

package/dist/edit/history.js

@@ -42,7 +42,11 @@ export class EditHistory {
     }
     /** State ids of every entry still in the history, folded and redo tail included. */
     get stateIds() {
-        return [...this.#folded, ...this.#entries].map((entry) => entry.stateId);
+        return this.allEntries.map((entry) => entry.stateId);
+    }
+    /** Every entry still in the history: folded ones, then the undoable ones and the redo tail. */
+    get allEntries() {
+        return [...this.#folded, ...this.#entries];
     }
     /** The entry `undo()` would revert, if any. */
     get undoEntry() {
@@ -58,10 +62,7 @@ export class EditHistory {
     }
     /** Batches applied to the original when `position` undoable entries are applied. */
     batchesAt(position) {
-        return this.entriesAt(position).map((entry) => ({
-            stateId: entry.stateId,
-            operations: entry.operations,
-        }));
+        return this.entriesAt(position).map(batchOf);
     }
     /** Entries applied when `position` undoable entries are applied, folded ones first. */
     entriesAt(position) {
@@ -70,10 +71,15 @@ export class EditHistory {
     get position() {
         return this.#position;
     }
-    push(entry) {
+    /**
+     * Appends an entry with a fresh state id, or with `stateId` when the entry
+     * reproduces a known state (a restore to a checkpoint): the same id means
+     * the same content, so `dirty` stays exact.
+     */
+    push(entry, stateId) {
         const stored = Object.freeze({
             ...entry,
-            stateId: this.#nextStateId++,
+            stateId: stateId ?? this.#nextStateId++,
         });
         // A new change after an undo drops the redo tail.
         this.#entries.length = this.#position;
@@ -99,3 +105,19 @@ export class EditHistory {
         this.#position = 0;
     }
 }
+/** The engine batch an entry replays as: its operations and how they were written. */
+export function batchOf(entry) {
+    return {
+        stateId: entry.stateId,
+        operations: entry.operations,
+        ...modeOf(entry),
+    };
+}
+/** The write mode fields of a batch or an entry, only those set. */
+export function modeOf(mode) {
+    return {
+        ...(mode.changeMode === undefined ? {} : { changeMode: mode.changeMode }),
+        ...(mode.author === undefined ? {} : { author: mode.author }),
+        ...(mode.timestamp === undefined ? {} : { timestamp: mode.timestamp }),
+    };
+}

package/dist/edit/pdf/engine/document.js

@@ -535,8 +535,11 @@ export class PdfEditDocument {
             },
             // Ids name the state the batch leads to, the operation and the item,
             // so replaying the history reproduces them and an undone id is never
-            // handed out again.
-            newId: (pageIndex, suffix = "") => `${this.#pages[pageIndex].key}:n${stateId}.${operationIndex}.${created++}${suffix}`,
+            // handed out again. A file saved by an earlier session carries the ids
+            // that session numbered from 1 as well, so one already on the page
+            // gets the first free `~n` instead (ACTION-886); the saved objects are
+            // part of the base, so a replay meets them and picks the same id.
+            newId: (pageIndex, suffix = "") => `${this.#unusedId(pageIndex, `${this.#pages[pageIndex].key}:n${stateId}.${operationIndex}.${created++}`)}${suffix}`,
             withPage: (pageIndex, use) => this.#writePage(pageIndex, use),
             appendObjects: (pageIndex, records) => {
                 const page = this.#pages[pageIndex];
@@ -686,10 +689,52 @@ export class PdfEditDocument {
             }
         }
         record.objects = objects.map((object, index) => object.mark && stale.has(object.id)
-            ? { id: `${record.key}:o${index}`, type: object.type }
+            ? {
+                id: `${record.key}:o${index}`,
+                type: object.type,
+                staleMarkId: object.id,
+            }
             : object);
         return record.objects;
     }
+    /**
+     * `id`, or its first free `~n` when an object saved by an earlier session
+     * has it already. Only ids a session numbered (`<key>:n…`) can collide, so
+     * only those are gathered; the objects are read without the page's text.
+     */
+    #unusedId(pageIndex, id) {
+        const record = this.#pages[pageIndex];
+        const objects = record.objects ?? this.#loadObjects(pageIndex);
+        const numbered = `${record.key}:n`;
+        const taken = new Set();
+        for (const object of objects) {
+            if (object.id.startsWith(numbered))
+                taken.add(object.id);
+            if (object.staleMarkId?.startsWith(numbered))
+                taken.add(object.staleMarkId);
+        }
+        if (!taken.has(id))
+            return id;
+        let suffix = 1;
+        while (taken.has(`${id}~${suffix}`))
+            suffix += 1;
+        return `${id}~${suffix}`;
+    }
+    /** A page's objects, loading the page alone when they are not known yet. */
+    #loadObjects(pageIndex) {
+        const { lib } = this.#pdfium;
+        const page = lib.FPDF_LoadPage(this.#document.handle, pageIndex);
+        if (!page)
+            throw new ViewerError("render-failed", "PDFium could not load the page", {
+                details: { pageIndex },
+            });
+        try {
+            return this.#objectsOf(pageIndex, page);
+        }
+        finally {
+            lib.FPDF_ClosePage(page);
+        }
+    }
     /** Marks from other sessions keep their id only if it cannot collide with ours. */
     #ownMark(mark, pageKey) {
         return mark.id.startsWith(`${pageKey}:`)

package/dist/edit/pdf/engine/elements.d.ts

@@ -21,6 +21,12 @@ export interface ObjectRecord {
     readonly id: string;
     readonly type: number;
     readonly mark?: MarkParams;
+    /**
+     * The id a mark the file still carries names, on an object listed as plain
+     * because the mark failed its check: a new id must not take it, or saving
+     * would join the new object to this one.
+     */
+    readonly staleMarkId?: string;
 }
 /**
  * Reads the objects of a loaded page in drawing order and turns them into

package/dist/edit/pdf/engine/fonts.js

@@ -110,7 +110,13 @@ export class FontLibrary {
             return undefined;
         if (this.#fallback && this.#covers(this.#fallback, request.text))
             return undefined;
-        const bad = firstNonWinAnsi(request.text) ?? firstUncovered(request.text, this);
+        // Name the character that actually stops the text: the first one the
+        // fallback lacks when it was tried, else the first the standard fonts
+        // cannot encode. Naming the first Cyrillic letter for a dash the
+        // fallback lacked sent people after the wrong character (ACTION-879).
+        const bad = this.#fallback
+            ? this.#firstMissing(this.#fallback, request.text)
+            : firstNonWinAnsi(request.text);
         return {
             path: "/text",
             code: "font-unavailable",
@@ -175,6 +181,10 @@ export class FontLibrary {
         return candidates.sort((a, b) => score(b.font) - score(a.font))[0];
     }
     #covers(bytes, text) {
+        return this.#firstMissing(bytes, text) === undefined;
+    }
+    /** The first character of `text` the font has no glyph for; layout handles line breaks and spaces. */
+    #firstMissing(bytes, text) {
         let coverage = this.#coverage.get(bytes);
         if (!coverage) {
             coverage = parseCmap(bytes);
@@ -185,9 +195,9 @@ export class FontLibrary {
             if (code === 0x0a || code === 0x20)
                 continue;
             if (!coverage.has(code))
-                return false;
+                return character;
         }
-        return true;
+        return undefined;
     }
     #load(pdfium, document, bytes) {
         let handles = this.#handles.get(document);
@@ -242,13 +252,6 @@ function isBold(font) {
 function isItalic(font) {
     return font.style !== "normal";
 }
-function firstUncovered(text, library) {
-    void library;
-    for (const character of text)
-        if (character !== "\n" && character !== " ")
-            return character;
-    return undefined;
-}
 /** The code points a TrueType font maps to glyphs, from its cmap table. */
 /**
  * Whether glyphs of a TrueType font have outline data: a subset font can keep

package/dist/edit/pdf/engine/pages.js

@@ -74,11 +74,19 @@ export const rotatePage = {
     validate(operation, context, issue) {
         if (operation.pageIndex >= context.pageCount)
             issue("/pageIndex", "unknown-target", `No page ${operation.pageIndex}`);
+        // A field given as undefined counts as absent, as it does everywhere else.
+        if ((operation.rotation === undefined) === (operation.by === undefined))
+            issue("", "one-of", "Give exactly one of `rotation` and `by`");
     },
     apply(operation, context) {
         const { lib } = context.pdfium;
         context.withPage(operation.pageIndex, (page) => {
-            lib.FPDFPage_SetRotation(page, operation.rotation / 90);
+            // A turn reads the angle the page has now, so it composes with what
+            // the file was saved with and with turns earlier in the history.
+            const quarters = operation.by !== undefined
+                ? (lib.FPDFPage_GetRotation(page) + operation.by / 90) % 4
+                : operation.rotation / 90;
+            lib.FPDFPage_SetRotation(page, quarters);
         });
         context.invalidatePage(operation.pageIndex);
         return {

package/dist/edit/pdf/range-map.d.ts

@@ -2,10 +2,12 @@ import type { EditOperation, EditReceipt, TextRange } from "../types.js";
 export interface MutationRecord {
     /** The revision the call produced. */
     readonly revision: number;
-    readonly kind: "apply" | "undo" | "redo" | "reset";
+    readonly kind: "apply" | "undo" | "redo" | "reset" | "restore";
     /**
      * The operations the call applied (apply, redo) or took back (undo, reset);
-     * for a reset every batch of the session, in order.
+     * for a reset every batch of the session, in order. A checkpoint restore
+     * carries none: its receipt's ids say what went and what came back, and
+     * offsets inside surviving elements are left as they were.
      */
     readonly operations: readonly EditOperation[];
     readonly receipt: EditReceipt;

package/dist/edit/pdf/schemas.js

@@ -170,10 +170,13 @@ export const pdfOperationSchemas = Object.freeze({
             from: { type: "integer", minimum: 0 },
             to: { type: "integer", minimum: 0 },
         }, ["from", "to"]),
+        // Exactly one of `rotation` (absolute) and `by` (a turn from the current
+        // angle); the handler reports a batch that gives both or neither.
         rotatePage: operation("rotatePage", {
             pageIndex: { type: "integer", minimum: 0 },
             rotation: { enum: [0, 90, 180, 270] },
-        }, ["pageIndex", "rotation"]),
+            by: { enum: [90, 180, 270] },
+        }, ["pageIndex"]),
         insertShape: operation("insertShape", {
             pageIndex: { type: "integer", minimum: 0 },
             shape: { enum: ["rectangle", "ellipse", "line"] },

package/dist/edit/pdf/session.d.ts

@@ -1,4 +1,5 @@
 import type { TextSelection } from "../../contracts.js";
+import type { DescribeOptions, DocumentDescription, EditCheckpoint, OutlineOptions, OutlineResult, TargetCandidate, TargetQuery, ToolCall, ToolCallOptions, ToolResult, ToolSet } from "../ai/types.js";
 import type { EditSessionCore } from "../engine.js";
 import type { ApplyOptions, AssetOptions, EditFindOptions, EditOperation, EditReceipt, EditState, ElementQuery, HistoryOptions, OperationSchemaSet, PagePoint, PageRect, ReadItem, ReadOptions, ReadResult, SavedDocument, TextPosition, TextRange, TextTarget } from "../types.js";
 import type { DeleteElementOperation, DeletePageOperation, Fields, InsertImageOperation, InsertPageOperation, InsertShapeOperation, InsertTableOperation, InsertTextBoxOperation, MoveElementOperation, MovePageOperation, PdfEditSession, PdfElement, PdfOperation, PdfSaveOptions, ReplaceTextOperation, ResizeElementOperation, RotatePageOperation, SetShapeStyleOperation, SetTableCellOperation, PageBitmap, PageLayout, RenderOptions, SetTextStyleOperation, TextLayout } from "./types.js";
@@ -28,6 +29,15 @@ export declare class PdfSession implements PdfEditSession {
     getElement(id: string, options?: ReadOptions): Promise<ReadItem<PdfElement>>;
     elementsAt(pageIndex: number, point: PagePoint, options?: ReadOptions): Promise<ReadResult<PdfElement>>;
     findText(query: string, options?: EditFindOptions): Promise<ReadResult<TextTarget>>;
+    getOutline(options?: OutlineOptions): Promise<OutlineResult>;
+    describe(options?: DescribeOptions): Promise<ReadItem<DocumentDescription>>;
+    resolveTargets(query: TargetQuery, options?: ReadOptions): Promise<ReadResult<TargetCandidate>>;
+    createCheckpoint(label?: string): Promise<EditCheckpoint>;
+    listCheckpoints(): readonly EditCheckpoint[];
+    restoreCheckpoint(id: string, options?: HistoryOptions): Promise<EditReceipt>;
+    dropCheckpoint(id: string): void;
+    get tools(): ToolSet;
+    callTool(call: ToolCall, options?: ToolCallOptions): Promise<ToolResult>;
     getTextLayout(elementId: string, options?: ReadOptions): Promise<ReadItem<TextLayout>>;
     positionAt(pageIndex: number, point: PagePoint, options?: ReadOptions): Promise<ReadItem<TextPosition>>;
     rangeRects(range: TextRange, options?: ReadOptions): Promise<ReadResult<PageRect>>;

package/dist/edit/pdf/session.js

@@ -1,4 +1,7 @@
 import { ViewerError } from "../../errors.js";
+import { readDescription, readOutline } from "../ai/outline.js";
+import { resolveTargets } from "../ai/targets.js";
+import { buildToolSet, callTool as runTool } from "../ai/tools.js";
 import { reportError } from "../session.js";
 import { rectContains } from "./engine/geometry.js";
 import { mapRangeThrough } from "./range-map.js";
@@ -11,6 +14,7 @@ import { resolveSelection } from "./selection.js";
 export class PdfSession {
     format = "pdf";
     #core;
+    #tools;
     /** Committed calls, oldest first, for `mapRange`; bounded by `LOG_LIMIT`. */
     #log = [];
     /** Batches applied and not undone, and those undone and not redone. */
@@ -81,6 +85,12 @@ export class PdfSession {
                 this.#applied = [];
                 this.#undone = [];
                 break;
+            case "restore":
+                // The checkpoint's content replaces whatever the stacks describe;
+                // the undo of a restore is the core's to replay, not the log's.
+                this.#applied = [];
+                this.#undone = [];
+                break;
         }
         this.#log.push({
             revision: receipt.revision,
@@ -156,6 +166,35 @@ export class PdfSession {
     findText(query, options) {
         return this.#core.findText(query, options);
     }
+    getOutline(options) {
+        return readOutline(this, this.#core.limits, options);
+    }
+    describe(options) {
+        return readDescription(this, this.#core.limits, options);
+    }
+    resolveTargets(query, options) {
+        return resolveTargets(this, query, options);
+    }
+    createCheckpoint(label) {
+        return this.#core.createCheckpoint(label);
+    }
+    listCheckpoints() {
+        return this.#core.listCheckpoints();
+    }
+    async restoreCheckpoint(id, options) {
+        const receipt = await this.#core.restoreCheckpoint(id, options);
+        this.#record("restore", [], receipt);
+        return receipt;
+    }
+    dropCheckpoint(id) {
+        this.#core.dropCheckpoint(id);
+    }
+    get tools() {
+        return (this.#tools ??= buildToolSet(this.format, this.schemas));
+    }
+    callTool(call, options) {
+        return runTool(this, this.tools, call, options);
+    }
     getTextLayout(elementId, options) {
         return this.#core.readItem(options, (engine, signal) => pdfReads(engine).textLayout(elementId, signal));
     }

package/dist/edit/pdf/types.d.ts

@@ -192,12 +192,24 @@ export interface SetShapeStyleOperation {
     /** A new fill, `null` to remove it, or absent to keep it. */
     readonly fill?: PdfFill | null;
 }
-export interface RotatePageOperation {
+/**
+ * Sets a page's rotation, or turns it from where it stands: a host offering
+ * "rotate" does not need to know the angle a file was saved with, and a
+ * replay of the history turns from the same angle again.
+ */
+export type RotatePageOperation = {
     readonly op: "rotatePage";
     readonly pageIndex: number;
     /** Absolute clockwise rotation in degrees. */
     readonly rotation: 0 | 90 | 180 | 270;
-}
+    readonly by?: never;
+} | {
+    readonly op: "rotatePage";
+    readonly pageIndex: number;
+    /** Clockwise turn in degrees from the page's current rotation. */
+    readonly by: 90 | 180 | 270;
+    readonly rotation?: never;
+};
 /** The PDF operation union; operations are added as they ship. */
 export type PdfOperation = InsertTextBoxOperation | ReplaceTextOperation | SetTextStyleOperation | ResizeElementOperation | MoveElementOperation | DeleteElementOperation | InsertPageOperation | DeletePageOperation | MovePageOperation | RotatePageOperation | InsertShapeOperation | SetShapeStyleOperation | InsertImageOperation | InsertTableOperation | SetTableCellOperation;
 export interface PdfSaveOptions extends SaveOptions {
@@ -321,7 +333,7 @@ export interface PdfEditSession extends EditSessionBase<PdfOperation, PdfElement
     deletePage(fields: Fields<DeletePageOperation>, options?: ApplyOptions): Promise<EditReceipt>;
     /** Reorders pages. */
     movePage(fields: Fields<MovePageOperation>, options?: ApplyOptions): Promise<EditReceipt>;
-    /** Sets a page's rotation. */
+    /** Sets a page's rotation, or turns it from the one it has. */
     rotatePage(fields: Fields<RotatePageOperation>, options?: ApplyOptions): Promise<EditReceipt>;
     /** Draws a rectangle, ellipse or line as a path object. */
     insertShape(fields: Fields<InsertShapeOperation>, options?: ApplyOptions): Promise<EditReceipt>;