web-doc 0.7.0 → 0.9.0

package/dist/edit/pptx/handler.js

@@ -13,6 +13,12 @@ export function createOoxmlEditHandler() {
             throw new ViewerError("lifecycle-error", "No package is open for editing");
         return state;
     };
+    const docx = () => {
+        const current = engine();
+        if (!(current instanceof DocxEditEngine))
+            throw new ViewerError("edit-unsupported", "The open document is not a Word document", { details: { format: "pptx", reason: "no-reads" } });
+        return current;
+    };
     const pptx = () => {
         const current = engine();
         if (!(current instanceof PptxEditEngine))
@@ -41,8 +47,8 @@ export function createOoxmlEditHandler() {
                 return result;
             }
             case "edit-validate": {
-                const { operations } = payload;
-                return engine().validate(operations, signal);
+                const { operations, mode } = payload;
+                return engine().validate(operations, signal, mode);
             }
             case "edit-apply": {
                 const { batch } = payload;
@@ -80,6 +86,8 @@ export function createOoxmlEditHandler() {
                 return pptx().slides(signal);
             case "edit-pptx-layouts":
                 return pptx().layouts(signal);
+            case "edit-docx-revisions":
+                return docx().revisions(payload.id, signal);
             case "edit-dispose":
                 await state?.dispose();
                 state = undefined;

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

@@ -1,3 +1,4 @@
+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, ReadItem, ReadOptions, ReadResult, SavedDocument, TextTarget } from "../types.js";
 import type { PptxDeleteElementOperation, PptxDeleteSlideOperation, PptxDuplicateSlideOperation, PptxEditSession, PptxElement, PptxFields, PptxInsertImageOperation, PptxInsertSlideOperation, PptxInsertTableOperation, PptxInsertTextBoxOperation, PptxLayoutInfo, PptxMoveElementOperation, PptxMoveSlideOperation, PptxOperation, PptxReplaceTextOperation, PptxResizeElementOperation, PptxSaveOptions, PptxSetShapeStyleOperation, PptxSetTableCellOperation, PptxSetTextStyleOperation, PptxSlideInfo } from "./types.js";
@@ -25,6 +26,15 @@ export declare class PptxSession implements PptxEditSession {
     getElement(id: string, options?: ReadOptions): Promise<ReadItem<PptxElement>>;
     elementsAt(pageIndex: number, point: PagePoint, options?: ReadOptions): Promise<ReadResult<PptxElement>>;
     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>;
     getSlides(options?: ReadOptions): Promise<ReadResult<PptxSlideInfo>>;
     getLayouts(options?: ReadOptions): Promise<ReadResult<PptxLayoutInfo>>;
     replaceText(fields: PptxFields<PptxReplaceTextOperation>, options?: ApplyOptions): Promise<EditReceipt>;

package/dist/edit/pptx/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";
 /**
  * The PPTX session: the core session narrowed to PPTX operations and
  * elements, plus the slide and layout reads. Each typed method is `apply()`
@@ -7,6 +10,7 @@ import { ViewerError } from "../../errors.js";
 export class PptxSession {
     format = "pptx";
     #core;
+    #tools;
     constructor(core) {
         this.#core = core;
     }
@@ -55,6 +59,33 @@ export class PptxSession {
     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();
+    }
+    restoreCheckpoint(id, options) {
+        return this.#core.restoreCheckpoint(id, options);
+    }
+    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);
+    }
     getSlides(options) {
         return this.#core.readItems(options, (engine, signal) => pptxReads(engine).slides(signal));
     }

package/dist/edit/session.d.ts

@@ -1,4 +1,5 @@
 import type { ResourceLimits, ViewerEventMap } from "../contracts.js";
+import type { DescribeOptions, DocumentDescription, EditCheckpoint, OutlineOptions, OutlineResult, TargetCandidate, TargetQuery, ToolCall, ToolCallOptions, ToolResult, ToolSet } from "./ai/types.js";
 import type { EditEngine, EditSessionCore } from "./engine.js";
 import type { AssetOptions, ApplyOptions, EditableFormat, EditElement, EditFindOptions, EditOperation, EditReceipt, EditState, ElementQuery, HistoryOptions, ReadItem, ReadOptions, ReadResult, OperationSchemaSet, PagePoint, SavedDocument, SaveOptions, TextTarget } from "./types.js";
 /** What the viewer provides to a session: a place to show bytes, and events. */
@@ -38,6 +39,7 @@ export declare class EditSessionController implements EditSessionCore {
     readonly sessionId: string;
     constructor(engine: EditEngine, host: EditSessionHost, original: Uint8Array, originalPageCount: number);
     get state(): EditState;
+    get limits(): ResourceLimits;
     applyJson(operations: readonly EditOperation[], options?: ApplyOptions): Promise<EditReceipt>;
     apply(operations: readonly EditOperation[], options?: ApplyOptions): Promise<EditReceipt>;
     undo(options?: HistoryOptions): Promise<EditReceipt>;
@@ -50,6 +52,15 @@ export declare class EditSessionController implements EditSessionCore {
     getElement(id: string, options?: ReadOptions): Promise<ReadItem<EditElement>>;
     elementsAt(pageIndex: number, point: PagePoint, options?: ReadOptions): Promise<ReadResult<EditElement>>;
     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>;
     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>>;
     /**

package/dist/edit/session.js

@@ -1,7 +1,10 @@
 import { linkedAbortController } from "../abort.js";
 import { abortError, 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 { assetIdOf, AssetStore, binaryFields, isAssetReference, } from "./assets.js";
-import { EditHistory } from "./history.js";
+import { batchOf, EditHistory, modeOf } from "./history.js";
 import { assertBatchSize, checkOperations, freezeOperations, invalidOperationError, parseReference, } from "./operations.js";
 /**
  * The format-independent editing session: validation, history, revisions,
@@ -17,15 +20,20 @@ export class EditSessionController {
     #original;
     #originalPageCount;
     #ending = new AbortController();
-    sessionId = newSessionId();
+    sessionId = randomId();
     /** Bytes of the last committed state; what the viewer shows and what a broken session saves. */
     #committedBytes;
     /** Materialized bytes of some committed states, by state id, so restores replay less. */
     #checkpoints = new Map();
     #checkpointBytes = 0;
+    /** Named checkpoints by id, in creation order. */
+    #named = new Map();
+    /** State ids named checkpoints pin, with how many name each; never evicted. */
+    #pinned = new Map();
     /** Binary payloads of this session's batches, by content id. */
     #assets = new AssetStore();
     #state;
+    #tools;
     #queue = Promise.resolve();
     #revision = 0;
     #savedStateId = 0;
@@ -46,6 +54,9 @@ export class EditSessionController {
     get state() {
         return this.#state;
     }
+    get limits() {
+        return this.#host.limits;
+    }
     applyJson(operations, options = {}) {
         return this.apply(operations, options);
     }
@@ -58,6 +69,9 @@ export class EditSessionController {
         return this.#enqueue(options.signal, async (signal) => {
             this.#assertRevision(options);
             assertBatchSize(batch, this.#host.limits.maxEditOperations);
+            const modeIssues = checkChangeMode(this.format, options);
+            if (modeIssues.length > 0)
+                throw invalidOperationError(modeIssues);
             const shapeIssues = checkOperations(batch, this.schemas);
             if (shapeIssues.length > 0)
                 throw invalidOperationError(shapeIssues);
@@ -65,7 +79,8 @@ export class EditSessionController {
             if (referenceIssues.length > 0)
                 throw invalidOperationError(referenceIssues);
             const interned = await this.#intern(batch, signal);
-            const engineIssues = await this.#engine.validate(interned, signal);
+            const mode = modeOf(options);
+            const engineIssues = await this.#engine.validate(interned, signal, mode);
             throwIfAborted(signal);
             if (engineIssues.length > 0)
                 throw invalidOperationError(engineIssues);
@@ -74,6 +89,7 @@ export class EditSessionController {
             const engineBatch = {
                 stateId: this.#history.nextStateId,
                 operations: interned,
+                ...mode,
             };
             if (options.dryRun) {
                 const change = await this.#transaction(signal, "apply", async () => {
@@ -99,6 +115,7 @@ export class EditSessionController {
             });
             this.#history.push({
                 operations: interned,
+                ...mode,
                 ...(options.label === undefined ? {} : { label: options.label }),
                 createdIds: change.createdIds,
                 removedIds: change.removedIds,
@@ -230,6 +247,88 @@ export class EditSessionController {
         const { signal: own, ...engineOptions } = options;
         return this.#enqueue(own, async (signal) => this.#items(await this.#engine.findText(query, engineOptions, signal)));
     }
+    getOutline(options) {
+        return readOutline(this, this.#host.limits, options);
+    }
+    describe(options) {
+        return readDescription(this, this.#host.limits, options);
+    }
+    resolveTargets(query, options) {
+        return resolveTargets(this, query, options);
+    }
+    createCheckpoint(label) {
+        return this.#enqueue(undefined, async () => {
+            const limit = this.#host.limits.maxEditCheckpoints;
+            if (this.#named.size >= limit)
+                throw new ViewerError("resource-limit", "Too many edit checkpoints; drop one first", { details: { limit } });
+            const stateId = this.#history.stateId;
+            const checkpoint = Object.freeze({
+                id: randomId(),
+                ...(label === undefined ? {} : { label }),
+                revision: this.#revision,
+                createdAt: new Date().toISOString(),
+            });
+            const entries = this.#history.entriesAt(this.#history.position);
+            this.#named.set(checkpoint.id, {
+                checkpoint,
+                stateId,
+                pageCount: this.#history.pageCount,
+                entries,
+                batches: batchesFromOriginal(entries),
+            });
+            this.#pin(stateId, this.#committedBytes);
+            return checkpoint;
+        });
+    }
+    listCheckpoints() {
+        return Object.freeze([...this.#named.values()].map((named) => named.checkpoint));
+    }
+    restoreCheckpoint(id, options = {}) {
+        return this.#enqueue(options.signal, async (signal) => {
+            this.#assertRevision(options);
+            const named = this.#named.get(id);
+            if (!named)
+                throw new ViewerError("invalid-operation", `Unknown edit checkpoint ${id}`, { details: { checkpointId: id } });
+            if (named.stateId === this.#history.stateId)
+                return this.#noop();
+            const before = this.#history.pageCount;
+            const changedPages = allPages(Math.max(before, named.pageCount));
+            const shown = await this.#transaction(signal, "apply", async () => {
+                await this.#engine.restore(this.#targetFor(named.entries), signal);
+                return this.#show(signal, changedPages);
+            });
+            const diff = entryDiff(this.#history.entriesAt(this.#history.position), named.entries);
+            this.#history.push({
+                operations: [],
+                createdIds: diff.created,
+                removedIds: diff.removed,
+                changedPages: shown.changedPages,
+                pageCountBefore: before,
+                pageCountAfter: shown.pageCount,
+                base: { stateId: named.stateId, batches: named.batches },
+            }, named.stateId);
+            this.#commit("restore", shown.changedPages, shown);
+            return this.#receipt(false, 0, diff.created, {
+                removedIds: diff.removed,
+                changedPages: shown.changedPages,
+                pageCount: shown.pageCount,
+                warnings: [],
+            });
+        });
+    }
+    dropCheckpoint(id) {
+        const named = this.#named.get(id);
+        if (!named)
+            return;
+        this.#named.delete(id);
+        this.#unpin(named.stateId);
+    }
+    get tools() {
+        return (this.#tools ??= buildToolSet(this.format, this.schemas));
+    }
+    callTool(call, options) {
+        return runTool(this, this.tools, call, options);
+    }
     readItem(options, task) {
         return this.#enqueue(options?.signal, async (signal) => Object.freeze({
             sessionId: this.sessionId,
@@ -412,7 +511,7 @@ export class EditSessionController {
     }
     #commit(reason, changedPages, shown) {
         this.#committedBytes = shown.bytes;
-        if (reason === "apply")
+        if (reason === "apply" || reason === "restore")
             this.#keepCheckpoint(shown.bytes);
         else if (reason === "reset")
             this.#dropCheckpoints();
@@ -500,49 +599,107 @@ export class EditSessionController {
     #keepCheckpoint(bytes) {
         const stride = Math.max(1, Math.floor(this.#host.limits.maxEditHistory / 4));
         const stateId = this.#history.stateId;
-        // Entries dropped by a new change after an undo can never be restored.
-        const reachable = new Set(this.#history.stateIds);
+        // Entries dropped by a new change after an undo can never be restored;
+        // a pinned state stays whatever the history does.
+        const reachable = this.#reachable();
         for (const [id, kept] of this.#checkpoints)
-            if (!reachable.has(id))
+            if (!reachable.has(id) && !this.#pinned.has(id))
                 this.#forgetCheckpoint(id, kept);
-        if (stateId % stride !== 0)
+        if (stateId === 0 ||
+            this.#checkpoints.has(stateId) ||
+            stateId % stride !== 0)
             return;
+        this.#retain(stateId, bytes);
+    }
+    /** Stores a state's bytes when the budget, less the pinned states, can hold them. */
+    #retain(stateId, bytes) {
         const budget = this.#host.limits.maxEditCheckpointBytes;
         if (bytes.byteLength > budget)
             return;
-        const oldestFirst = [...this.#checkpoints.keys()].sort((a, b) => a - b);
+        const evictable = [...this.#checkpoints.keys()]
+            .filter((id) => !this.#pinned.has(id))
+            .sort((a, b) => a - b);
         while (this.#checkpointBytes + bytes.byteLength > budget &&
-            oldestFirst.length > 0) {
-            const id = oldestFirst.shift();
+            evictable.length > 0) {
+            const id = evictable.shift();
             this.#forgetCheckpoint(id, this.#checkpoints.get(id));
         }
+        if (this.#checkpointBytes + bytes.byteLength > budget)
+            return;
         this.#checkpoints.set(stateId, bytes);
         this.#checkpointBytes += bytes.byteLength;
     }
+    /**
+     * Pins a state for a named checkpoint: its bytes are kept while any
+     * checkpoint names it, or rebuilt by replay when the budget cannot hold
+     * them. The original (state 0) needs no bytes.
+     */
+    #pin(stateId, bytes) {
+        if (stateId === 0)
+            return;
+        this.#pinned.set(stateId, (this.#pinned.get(stateId) ?? 0) + 1);
+        if (!this.#checkpoints.has(stateId))
+            this.#retain(stateId, bytes);
+    }
+    #unpin(stateId) {
+        const count = this.#pinned.get(stateId);
+        if (!count)
+            return;
+        if (count > 1) {
+            this.#pinned.set(stateId, count - 1);
+            return;
+        }
+        this.#pinned.delete(stateId);
+        const kept = this.#checkpoints.get(stateId);
+        if (kept && !this.#reachable().has(stateId))
+            this.#forgetCheckpoint(stateId, kept);
+    }
+    /** State ids a replay may start from: every entry's, and the base of every restore. */
+    #reachable() {
+        const reachable = new Set();
+        for (const entry of this.#history.allEntries) {
+            reachable.add(entry.stateId);
+            if (entry.base)
+                reachable.add(entry.base.stateId);
+        }
+        return reachable;
+    }
     #forgetCheckpoint(id, bytes) {
         this.#checkpoints.delete(id);
         this.#checkpointBytes -= bytes.byteLength;
     }
+    /** After a reset nothing in the history is reachable; pinned states stay. */
     #dropCheckpoints() {
-        this.#checkpoints.clear();
-        this.#checkpointBytes = 0;
+        for (const [id, kept] of this.#checkpoints)
+            if (!this.#pinned.has(id))
+                this.#forgetCheckpoint(id, kept);
     }
     /**
      * The cheapest way to rebuild the state at `position`: the newest
-     * checkpoint at or before it, plus the batches after that checkpoint.
+     * retained bytes at or before it, plus the batches after them.
      */
     #restoreTarget(position = this.#history.position) {
-        const entries = this.#history.entriesAt(position);
-        let last = entries.length - 1;
-        while (last >= 0 && !this.#checkpoints.has(entries[last].stateId))
-            last -= 1;
-        const batches = entries.slice(last + 1).map((entry) => ({
-            stateId: entry.stateId,
-            operations: entry.operations,
-        }));
-        return last >= 0
-            ? { base: this.#checkpoints.get(entries[last].stateId), batches }
-            : { batches };
+        return this.#targetFor(this.#history.entriesAt(position));
+    }
+    /**
+     * Walks `entries` from the end: the first with retained bytes is the base;
+     * a restore entry without them starts from the original plus the batches
+     * that built its checkpoint.
+     */
+    #targetFor(entries) {
+        for (let index = entries.length - 1; index >= 0; index -= 1) {
+            const entry = entries[index];
+            const after = () => batchesOf(entries.slice(index + 1));
+            const retained = this.#checkpoints.get(entry.stateId);
+            if (retained)
+                return { base: retained, batches: after() };
+            // A restore entry carries its checkpoint's state id, so its bytes
+            // were just looked up; without them the checkpoint's batches rebuild
+            // it from the original.
+            if (entry.base)
+                return { batches: [...entry.base.batches, ...after()] };
+        }
+        return { batches: batchesOf(entries) };
     }
     #stateToken(stateId) {
         return `${this.sessionId}:${stateId}`;
@@ -667,6 +824,43 @@ function checkBatchReferences(operations) {
     });
     return issues;
 }
+/**
+ * Tracked changes exist in DOCX only and always name their author (decision
+ * 8 of the ai-edit module): the batch is refused before any engine work.
+ */
+function checkChangeMode(format, options) {
+    const issues = [];
+    // A timestamp is written into the file where a format records one, so
+    // it must be a date-time the file can hold whatever the mode.
+    if (options.timestamp !== undefined &&
+        (!DATE_TIME.test(options.timestamp) ||
+            Number.isNaN(Date.parse(options.timestamp))))
+        issues.push({
+            operationIndex: -1,
+            path: "/timestamp",
+            code: "invalid-value",
+            message: "The timestamp must be an ISO 8601 date-time",
+        });
+    if (options.changeMode !== "tracked")
+        return issues;
+    if (format !== "docx")
+        issues.push({
+            operationIndex: -1,
+            path: "",
+            code: "unsupported-change-mode",
+            message: `${format.toUpperCase()} has no tracked changes; apply directly and review with checkpoints`,
+        });
+    else if (!options.author || options.author.trim().length === 0)
+        issues.push({
+            operationIndex: -1,
+            path: "/author",
+            code: "required",
+            message: "Tracked changes name their author; pass ApplyOptions.author",
+        });
+    return issues;
+}
+/** ISO 8601 as `xsd:dateTime` takes it. */
+const DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})?$/;
 /** The renderer owns the page count; an engine that disagrees is reported, not trusted. */
 function pageCountWarning(change, shown) {
     if (change.pageCount === undefined || change.pageCount === shown.pageCount)
@@ -679,8 +873,56 @@ function pageCountWarning(change, shown) {
         },
     ];
 }
-/** 128 random bits as URL-safe base64; unique across sessions and reloads. */
-function newSessionId() {
+/** The engine batches of entries that carry operations; restore entries carry none. */
+function batchesOf(entries) {
+    return entries.filter((entry) => entry.operations.length > 0).map(batchOf);
+}
+/** The batches from the original to the state after `entries`, through the last restore. */
+function batchesFromOriginal(entries) {
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const base = entries[index].base;
+        if (base)
+            return [...base.batches, ...batchesOf(entries.slice(index + 1))];
+    }
+    return batchesOf(entries);
+}
+/**
+ * The ids a move from the state after `current` to the state after `target`
+ * removes and creates: the entries past the common prefix are undone in
+ * reverse, then the target's are redone, each id netted out.
+ */
+function entryDiff(current, target) {
+    let common = 0;
+    while (common < current.length &&
+        common < target.length &&
+        current[common].stateId === target[common].stateId)
+        common += 1;
+    const created = new Set();
+    const removed = new Set();
+    const create = (id) => {
+        if (removed.has(id))
+            removed.delete(id);
+        else
+            created.add(id);
+    };
+    const remove = (id) => {
+        if (created.has(id))
+            created.delete(id);
+        else
+            removed.add(id);
+    };
+    for (const entry of current.slice(common).reverse()) {
+        entry.createdIds.forEach(remove);
+        entry.removedIds.forEach(create);
+    }
+    for (const entry of target.slice(common)) {
+        entry.removedIds.forEach(remove);
+        entry.createdIds.forEach(create);
+    }
+    return { created: [...created], removed: [...removed] };
+}
+/** 128 random bits as 22 URL-safe base64 characters; unique across sessions and reloads. */
+function randomId() {
     const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
     let binary = "";
     for (const byte of bytes)

package/dist/edit/types.d.ts

@@ -1,4 +1,5 @@
 import type { ViewerWarning } from "../contracts.js";
+import type { EditSessionReads } from "./ai/types.js";
 /** Formats an edit session can be started for. */
 export type EditableFormat = "pdf" | "pptx" | "docx";
 export interface EditOptions {
@@ -163,16 +164,27 @@ export interface EditState {
     readonly canRedo: boolean;
     readonly pageCount: number;
 }
+/** How a batch is written: in place, or as tracked changes (DOCX) for a person to accept or reject. */
+export type ChangeMode = "direct" | "tracked";
 export interface ApplyOptions {
     /** Rejects the call with `edit-conflict` unless `state.revision` equals this value. */
     readonly expectedRevision?: number;
+    /**
+     * Default `direct`. `tracked` writes Word revisions (`w:ins`, `w:del`,
+     * `w:rPrChange`, `w:pPrChange`) with `author` and `timestamp`; refused
+     * with `unsupported-change-mode` by formats and operations without a
+     * tracked form, and with `required` at `/author` without an author.
+     */
+    readonly changeMode?: ChangeMode;
+    /** The `w:author` of tracked changes; required with `changeMode: "tracked"`. */
+    readonly author?: string;
     /** Rejects with `edit-conflict` unless it equals `sessionId`; for callers that outlive a session. */
     readonly expectedSessionId?: string;
     /** Validates and simulates the batch without changing anything. */
     readonly dryRun?: boolean;
     /** Free text stored with the history entry, for host UIs and audit logs. */
     readonly label?: string;
-    /** Reserved: ISO 8601 time a format records with the change; never generated by web-doc. */
+    /** ISO 8601 time a format records with the change (the `w:date` of a tracked change); never generated by web-doc. */
     readonly timestamp?: string;
     readonly signal?: AbortSignal;
 }
@@ -228,7 +240,7 @@ export interface OperationIssue {
     readonly code: string;
     readonly message: string;
 }
-export interface EditSessionBase<TOperation extends EditOperation, TElement extends EditElement> {
+export interface EditSessionBase<TOperation extends EditOperation, TElement extends EditElement> extends EditSessionReads {
     readonly format: EditableFormat;
     /** Unique per session; stamped on state, receipts, read results and events. */
     readonly sessionId: string;
@@ -258,7 +270,9 @@ export interface EditStateChange extends EditState {
     readonly active: boolean;
     readonly format?: EditableFormat;
 }
-export type DocumentChangeReason = "apply" | "undo" | "redo" | "reset";
+export type DocumentChangeReason = "apply" | "undo" | "redo" | "reset"
+/** `restoreCheckpoint()`: the content of a named checkpoint, as one history entry. */
+ | "restore";
 export interface DocumentChange {
     readonly sessionId: string;
     readonly revision: number;

package/dist/edit/worker-engine.d.ts

@@ -1,6 +1,6 @@
 import type { WorkerRpcClient } from "../worker-client.js";
 import type { EditWorkerOperation } from "../worker-protocol.js";
-import type { EditEngine, EditEngineContext, EngineBatch, EngineChange, MaterializedDocument, MaterializeOptions, RestoreTarget } from "./engine.js";
+import type { EditEngine, EditEngineContext, BatchMode, EngineBatch, EngineChange, MaterializedDocument, MaterializeOptions, RestoreTarget } from "./engine.js";
 import type { EditElement, EditFindOptions, EditOperation, ElementQuery, OperationIssue, OperationSchemaSet, PagePoint, TextTarget } from "./types.js";
 export declare abstract class WorkerEngineClient implements EditEngine {
     #private;
@@ -8,7 +8,7 @@ export declare abstract class WorkerEngineClient implements EditEngine {
     protected readonly rpc: WorkerRpcClient;
     protected readonly context: EditEngineContext;
     constructor(rpc: WorkerRpcClient, context: EditEngineContext);
-    validate(operations: readonly EditOperation[], signal: AbortSignal): Promise<readonly OperationIssue[]>;
+    validate(operations: readonly EditOperation[], signal: AbortSignal, mode?: BatchMode): Promise<readonly OperationIssue[]>;
     /** Plain operation arrays, as the unit tests pass them, become the next batch. */
     apply(input: EngineBatch | readonly EditOperation[], signal: AbortSignal): Promise<EngineChange>;
     /** A bare signal, as the unit tests pass it, asks for the shown form. */

package/dist/edit/worker-engine.js

@@ -12,8 +12,8 @@ export class WorkerEngineClient {
         this.rpc = rpc;
         this.context = context;
     }
-    validate(operations, signal) {
-        return this.request("edit-validate", { operations }, signal);
+    validate(operations, signal, mode = {}) {
+        return this.request("edit-validate", { operations, mode }, signal);
     }
     /** Plain operation arrays, as the unit tests pass them, become the next batch. */
     apply(input, signal) {

package/dist/fonts/THIRD_PARTY_NOTICES.md

@@ -6,8 +6,11 @@ The WOFF2 files in this directory are modified/subset builds of Noto Sans and No
 - Noto Sans CJK sources: `notofonts/noto-cjk` commit `f8d157532fbfaeda587e826d4cd5b21a49186f7c`.
 - License: SIL Open Font License 1.1; see `OFL-1.1.txt`.
 - Modified font family used by the viewer: `Zrimo Noto`.
-- `noto-sans-latin-cyrillic.ttf` is the same Latin/Cyrillic subset saved as an
-  uncompressed TrueType file; the PDF editor embeds it into documents whose
-  text the standard fonts cannot encode.
+- `noto-sans-latin-cyrillic.ttf` is the same Latin/Cyrillic subset plus Noto
+  Sans's General Punctuation, Superscripts and Subscripts, Currency Symbols,
+  Letterlike Symbols and Number Forms (ranges in `manifest.json`; the Arrows
+  and Mathematical Operators ranges are requested too, but Noto Sans has no
+  glyphs there), saved as an uncompressed TrueType file; the PDF editor embeds it into
+  documents whose text the standard fonts cannot encode.
 
 No proprietary Microsoft font is included.

package/dist/fonts/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "family": "Zrimo Noto",
-  "generated": "2026-07-16",
-  "tooling": "fonttools pyftsubset with all layout features, then woff2_compress; the .ttf is the Latin/Cyrillic subset saved uncompressed with fonttools for embedding into PDFs",
+  "generated": "2026-10-02",
+  "tooling": "fonttools pyftsubset with all layout features, then woff2_compress; the .ttf is the Latin/Cyrillic subset saved uncompressed with fonttools for embedding into PDFs, from hinted/ttf/NotoSans/NotoSans-Regular.ttf with U+0000,U+000D,U+0020-007E,U+00A0-024F,U+0300-036F,U+0400-052F,U+1E00-1EFF plus General Punctuation, Superscripts and Subscripts, Currency Symbols, Letterlike Symbols, Number Forms, Arrows, Mathematical Operators, U+25CC and U+FFFD (U+2000-206F,U+2070-209F,U+20A0-20CF,U+2100-214F,U+2150-218F,U+2190-21FF,U+2200-22FF,U+25CC,U+FFFD) so text typed with dashes, quotes, currency signs and the numero sign can be embedded; Noto Sans has no glyphs in the Arrows and Mathematical Operators ranges, so those two add none",
   "license": "OFL-1.1",
   "sources": {
     "noto-fonts": "https://github.com/notofonts/noto-fonts/tree/ffebf8c1ee449e544955a7e813c54f9b73848eac",
@@ -81,8 +81,8 @@
     },
     {
       "file": "noto-sans-latin-cyrillic.ttf",
-      "bytes": 218796,
-      "sha256": "6a23e5413988b4b523ceb4aa81a1de85dad21336868997f52eb6d42159345262"
+      "bytes": 260552,
+      "sha256": "94094981da300fdb704d64cb91354360d37bf69b26f8584da7d44fdc2e0bdc84"
     }
   ]
 }