web-doc 0.7.0 → 0.9.0

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

@@ -0,0 +1,175 @@
+import type { ChangeMode, EditableFormat, EditReceipt, HistoryOptions, JsonSchema, OperationIssue, ReadItem, ReadOptions, ReadResult, TextRange } from "../types.js";
+export interface OutlineOptions extends ReadOptions {
+    /** Inclusive 0-based page range; a node outside it is left out unless a descendant is inside. */
+    readonly pageRange?: readonly [number, number];
+    /** Element kinds to keep; a container of a kept node stays as its parent. */
+    readonly kinds?: readonly string[];
+    /** Characters of text kept per node; the rest is cut and `truncated` says so. Default 160. */
+    readonly maxTextChars?: number;
+}
+/** One element as a prompt sees it: no geometry, no styles, nested where the format nests. */
+export interface OutlineNode {
+    /** The element id, as every operation takes it. */
+    readonly id: string;
+    /** The reading-order path: "3", "3.2" (a cell paragraph under its table). */
+    readonly ordinal: string;
+    /** The format's element kind. */
+    readonly kind: string;
+    /** −1 while the page is not laid out (a DOCX page the viewer has not cached). */
+    readonly pageIndex: number;
+    /** The first `maxTextChars` characters of the element's text. */
+    readonly text?: string;
+    /** Length of the whole text, in UTF-16 code units. */
+    readonly textLength: number;
+    /** True when `text` is shorter than the element's text. */
+    readonly truncated: boolean;
+    /** What a person calls it: "Title 1", "Heading 2", "Table (3×4)". */
+    readonly label?: string;
+    /** Why the element only accepts insertions next to it, when it does. */
+    readonly readOnlyReason?: string;
+    /** Listed and editable, but not drawn (a hidden PowerPoint shape). */
+    readonly hidden?: boolean;
+    /** Names of the operations that accept the element as their target. */
+    readonly operations: readonly string[];
+    /** A table's cell paragraphs, a group's members, a paragraph's inline pictures. */
+    readonly children?: readonly OutlineNode[];
+}
+/** `getOutline()`'s read: the nodes, how many there are and whether the limit cut them. */
+export interface OutlineResult extends ReadResult<OutlineNode> {
+    /** Nodes in the result, nested ones included. */
+    readonly nodeCount: number;
+    /** True when `maxOutlineNodes` cut the outline. */
+    readonly truncated: boolean;
+}
+export interface DescribeOptions extends OutlineOptions {
+    /** Characters the description may take; the tail is cut and `truncated` says so. Default 50 000. */
+    readonly maxChars?: number;
+}
+/** The outline rendered as plain text for a prompt. */
+export interface DocumentDescription {
+    readonly format: EditableFormat;
+    readonly pageCount: number;
+    /** Elements the description covers, nested ones included. */
+    readonly elementCount: number;
+    /**
+     * A header line, then one line per node in the documented grammar:
+     * `[sld2:7] slide 2 shape "Title 1": Quarterly review`.
+     */
+    readonly text: string;
+    /** True when `maxChars` or `maxOutlineNodes` cut the description. */
+    readonly truncated: boolean;
+}
+/** What a model names: a quoted text, a citation with its page, a kind, a place. */
+export interface TargetQuery {
+    /** Text to find; whitespace-insensitive, case-insensitive, tolerant to small differences. */
+    readonly text?: string;
+    /** A citation as the viewer's `search()` gets them: the passage and the 1-based page it is expected on. */
+    readonly citation?: {
+        readonly text: string;
+        readonly pageNumber?: number;
+    };
+    readonly pageIndex?: number;
+    readonly kinds?: readonly string[];
+    /** Restrict to an element and its descendants (a table, a group). */
+    readonly within?: string;
+    /** Default 5. */
+    readonly maxResults?: number;
+}
+/** One way to read a query, with how it was found and how far to trust it. */
+export interface TargetCandidate {
+    readonly elementId: string;
+    /** The matched part, for ranged operations; absent when the match is the element's whole text. */
+    readonly range?: TextRange;
+    readonly pageIndex: number;
+    /** 1 for an exact match, down to 0.5 for the loosest accepted one. */
+    readonly score: number;
+    /** The pass that matched: the engine's exact search, folded text, fuzzy alignment, or a kind lookup. */
+    readonly reason: "exact" | "normalized" | "fuzzy" | "kind-only";
+    /** The matched text with a little context, on one line. */
+    readonly snippet: string;
+}
+/** A state the host named, to come back to; session state, gone with the session. */
+export interface EditCheckpoint {
+    /** 22 URL-safe characters, unique in the session. */
+    readonly id: string;
+    readonly label?: string;
+    /** The revision it names. */
+    readonly revision: number;
+    /** ISO 8601. */
+    readonly createdAt: string;
+}
+/** One tool as a model provider takes it: a name, a description and a JSON Schema (draft 2020-12). */
+export interface ToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchema;
+}
+/** The tools of a session; the same names on every format, the operations of its own. */
+export interface ToolSet {
+    /** Raised when a tool's shape changes incompatibly. */
+    readonly version: number;
+    readonly format: EditableFormat;
+    readonly definitions: readonly ToolDefinition[];
+}
+/** A model's call: the tool's name and its JSON arguments, validated against the tool's schema. */
+export interface ToolCall {
+    readonly name: string;
+    readonly arguments: unknown;
+}
+/** What a tool call produced, for the model and the chat. */
+export interface ToolResult {
+    readonly ok: boolean;
+    /** JSON for the model: a description, an outline, candidates, a receipt, or the issues of a refused call. */
+    readonly content: unknown;
+    /** One or two sentences for the model and the chat: "Replaced the title of slide 2." */
+    readonly text: string;
+    /** Why a call was refused, in the shape `apply()` reports. */
+    readonly issues?: readonly OperationIssue[];
+}
+export interface ToolCallOptions {
+    /** Checked before any tool that changes the document, like `ApplyOptions.expectedRevision`. */
+    readonly expectedRevision?: number;
+    /** How `document_apply` writes: in place, or as tracked changes where the format has them. */
+    readonly changeMode?: ChangeMode;
+    /** The author of tracked changes; required with `changeMode: "tracked"`. */
+    readonly author?: string;
+    readonly signal?: AbortSignal;
+}
+/** The AI-facing reads, the checkpoints and the tools every edit session has. */
+export interface EditSessionReads {
+    /** The body elements in reading order, shaped for a prompt. */
+    getOutline(options?: OutlineOptions): Promise<OutlineResult>;
+    /** The outline as plain text, one line per element, within a character budget. */
+    describe(options?: DescribeOptions): Promise<ReadItem<DocumentDescription>>;
+    /**
+     * Elements and ranges a query names, best first: an exact match, else a
+     * match with whitespace, case, quotes and compatibility forms folded,
+     * else the viewer's fuzzy citation match, else (without text) the
+     * elements of the asked kinds in reading order.
+     */
+    resolveTargets(query: TargetQuery, options?: ReadOptions): Promise<ReadResult<TargetCandidate>>;
+    /**
+     * Pins the current state under a new id. Rejects with `resource-limit`
+     * past `maxEditCheckpoints`.
+     */
+    createCheckpoint(label?: string): Promise<EditCheckpoint>;
+    /** Every checkpoint alive, in creation order. */
+    listCheckpoints(): readonly EditCheckpoint[];
+    /**
+     * Back to the checkpoint's content as one history entry: undoable, a new
+     * revision, `documentchange` with reason `restore`. Rejects with
+     * `invalid-operation` for an unknown id.
+     */
+    restoreCheckpoint(id: string, options?: HistoryOptions): Promise<EditReceipt>;
+    /** Forgets a checkpoint; unknown ids are ignored. */
+    dropCheckpoint(id: string): void;
+    /** The tool definitions of this session, for a model provider's tool list. */
+    readonly tools: ToolSet;
+    /**
+     * Runs one tool call. A model's mistake (an unknown tool, bad arguments, a
+     * refused batch, a stale revision) comes back as `ok: false` with issues
+     * and a text to act on; only the session's own errors (`lifecycle-error`,
+     * `aborted`) throw.
+     */
+    callTool(call: ToolCall, options?: ToolCallOptions): Promise<ToolResult>;
+}

package/dist/edit/ai/types.js

@@ -0,0 +1 @@
+export {};

package/dist/edit/docx/elements.js

@@ -81,10 +81,28 @@ function paragraphElement(model, record, base) {
         id: record.elementId,
         kind: "paragraph",
         text: record.text.text,
-        ...(record.table ? { parentId: record.table.elementId } : {}),
+        ...(record.table
+            ? { parentId: record.table.elementId, ...cellOf(record.table, record) }
+            : {}),
         textStyle: resolveTextStyle(model.styles, record.pPr, first?.rPr),
         paragraphStyle: resolveParagraphStyle(model.styles, record.pPr),
         ...(record.readOnlyReason ? { readOnlyReason: record.readOnlyReason } : {}),
         operations: operationsOf("paragraph", record.readOnlyReason !== undefined),
     };
 }
+/** Where each paragraph of a table sits, read once per table. */
+const CELLS = new WeakMap();
+/** The cell of a table that holds a paragraph, when the table lists it. */
+function cellOf(table, record) {
+    let cells = CELLS.get(table);
+    if (!cells) {
+        cells = new Map();
+        for (const [row, cellsOfRow] of table.rows.entries())
+            for (const [column, cell] of cellsOfRow.entries())
+                for (const paragraph of cell.paragraphs)
+                    cells.set(paragraph, { row, column });
+        CELLS.set(table, cells);
+    }
+    const cell = cells.get(record);
+    return cell ? { cell } : {};
+}

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

@@ -1,10 +1,14 @@
 import type { ResourceLimits } from "../../contracts.js";
-import type { EditEngine, EngineBatch, EngineChange, MaterializedDocument, MaterializeOptions, RestoreTarget } from "../engine.js";
+import type { BatchMode, EditEngine, EngineBatch, EngineChange, MaterializedDocument, MaterializeOptions, RestoreTarget } from "../engine.js";
 import { OoxmlPackage } from "../ooxml/package.js";
 import type { EditFindOptions, EditOperation, ElementQuery, OperationIssue, PagePoint, TextTarget } from "../types.js";
 import { DocxModel, type AnyRecord } from "./model.js";
-import type { DocxElement } from "./types.js";
-export declare class DocxEditEngine implements EditEngine {
+import type { DocxElement, DocxRevision } from "./types.js";
+/** Reads the DOCX session adds on top of the core, served by the engine and the worker client alike. */
+export interface DocxEngineReads {
+    revisions(id: string, signal: AbortSignal): Promise<readonly DocxRevision[]>;
+}
+export declare class DocxEditEngine implements EditEngine, DocxEngineReads {
     #private;
     readonly schemas: import("../types.js").OperationSchemaSet;
     private constructor();
@@ -16,9 +20,11 @@ export declare class DocxEditEngine implements EditEngine {
     get pageCount(): number;
     /** The block index at the current revision. */
     model(signal?: AbortSignal): Promise<DocxModel>;
-    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>;
+    /** The revisions of a paragraph; none for another element or an unknown id. */
+    revisions(id: string, signal: AbortSignal): Promise<readonly DocxRevision[]>;
     materialize(purposeOrSignal?: "show" | "save" | AbortSignal, options?: MaterializeOptions, signal?: AbortSignal): Promise<Uint8Array>;
     /**
      * `save` is the package as the session changed it: ids written only on

package/dist/edit/docx/engine.js

@@ -7,9 +7,10 @@ import { NO_PAGE, toElement } from "./elements.js";
 import { docxHandlers } from "./handlers.js";
 import { freshParagraphId, paragraphsOf } from "./ids.js";
 import { DocxModel } from "./model.js";
-import { issueCollector } from "./operations.js";
+import { issueCollector, } from "./operations.js";
 import { docxOperationSchemas } from "./schemas.js";
-import { namespacePatches } from "./write.js";
+import { revisionsOf } from "./tracked.js";
+import { attributeProblem, namespacePatches } from "./write.js";
 /*
  * The DOCX edit engine: the package layer under a block index of the body
  * story. It runs inside the OOXML edit worker in the browser and directly
@@ -39,6 +40,57 @@ function unauthoredIdsOf(bytes) {
     const text = new TextDecoder().decode(bytes);
     return [...text.matchAll(/<p id="([0-9A-F]{8})"\/>/g)].map((m) => m[1]);
 }
+/** The tracked-change record of a batch, when it writes revisions. */
+function trackedOf(mode) {
+    if (mode.changeMode !== "tracked")
+        return undefined;
+    return {
+        author: mode.author ?? "",
+        ...(mode.timestamp === undefined ? {} : { date: mode.timestamp }),
+    };
+}
+/** ISO 8601 as `xsd:dateTime` takes it; what `w:date` carries. */
+const DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})?$/;
+/**
+ * What a tracked batch must carry before any revision is written: an author
+ * the file can hold (the core requires one too; the engine used on its own
+ * does the same) and a date the file can hold.
+ */
+function trackedModeIssues(tracked) {
+    if (!tracked)
+        return [];
+    const issues = [];
+    const author = attributeProblem(tracked.author);
+    if (tracked.author.trim().length === 0)
+        issues.push({
+            operationIndex: -1,
+            path: "/author",
+            code: "required",
+            message: "Tracked changes name their author; pass ApplyOptions.author",
+        });
+    else if (author)
+        issues.push({
+            operationIndex: -1,
+            path: "/author",
+            code: "invalid-value",
+            message: `The author holds ${author}`,
+        });
+    if (tracked.date !== undefined) {
+        const date = attributeProblem(tracked.date);
+        if (date ||
+            !DATE_TIME.test(tracked.date) ||
+            Number.isNaN(Date.parse(tracked.date)))
+            issues.push({
+                operationIndex: -1,
+                path: "/timestamp",
+                code: "invalid-value",
+                message: date
+                    ? `The timestamp holds ${date}`
+                    : "The timestamp must be an ISO 8601 date-time",
+            });
+    }
+    return issues;
+}
 export class DocxEditEngine {
     schemas = docxOperationSchemas;
     #original;
@@ -96,9 +148,13 @@ export class DocxEditEngine {
         });
         return pending;
     }
-    async validate(operations, signal) {
+    async validate(operations, signal, mode = {}) {
         const issues = [];
-        const base = await this.#context(0, signal);
+        const tracked = trackedOf(mode);
+        const modeIssues = trackedModeIssues(tracked);
+        if (modeIssues.length > 0)
+            return modeIssues;
+        const base = await this.#context(0, signal, 0, new Set(), tracked);
         for (const [index, operation] of operations.entries()) {
             const context = { ...base, operationIndex: index };
             const handler = docxHandlers.get(operation.op);
@@ -142,6 +198,10 @@ export class DocxEditEngine {
             ? { stateId: this.#nextStateId(), operations: input }
             : input;
         this.#stateId = Math.max(this.#stateId, batch.stateId);
+        const tracked = trackedOf(batch);
+        const modeIssues = trackedModeIssues(tracked);
+        if (modeIssues.length > 0)
+            throw invalidOperationError(modeIssues);
         const snapshot = this.#pkg.snapshot();
         const unauthored = this.#unauthored ? [...this.#unauthored] : undefined;
         const createdIds = [];
@@ -158,7 +218,7 @@ export class DocxEditEngine {
                 const handler = docxHandlers.get(operation.op);
                 if (!handler)
                     throw new ViewerError("invalid-operation", `Unknown operation ${operation.op}`);
-                const context = await this.#context(batch.stateId, signal, index, issued);
+                const context = await this.#context(batch.stateId, signal, index, issued, tracked);
                 const issues = [];
                 await handler.validate(operation, context, issueCollector(index, issues));
                 if (issues.length > 0)
@@ -209,10 +269,11 @@ export class DocxEditEngine {
         this.#stateId += 1;
         return this.#stateId;
     }
-    async #context(stateId, signal, operationIndex = 0, issued = new Set()) {
+    async #context(stateId, signal, operationIndex = 0, issued = new Set(), tracked) {
         const model = await this.model(signal);
         const taken = new Set([...model.takenIds, ...issued]);
         let count = 0;
+        let revisions = 0;
         return {
             pkg: this.#pkg,
             model,
@@ -227,8 +288,21 @@ export class DocxEditEngine {
                 taken.add(id);
                 return id;
             },
+            ...(tracked ? { tracked } : {}),
+            nextRevisionId: () => {
+                revisions += 1;
+                return model.maxRevisionId + revisions;
+            },
         };
     }
+    /** The revisions of a paragraph; none for another element or an unknown id. */
+    async revisions(id, signal) {
+        const model = await this.model(signal);
+        const record = model.byId.get(id);
+        if (!record || record.kind !== "paragraph")
+            return [];
+        return revisionsOf(model.document, record.node);
+    }
     async materialize(purposeOrSignal = "show", options = {}, signal = new AbortController().signal) {
         return (await this.materializeDocument(purposeOrSignal, options, signal))
             .bytes;

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

@@ -73,6 +73,8 @@ export declare class DocxModel {
     /** Every paragraph id the document uses, in any story part. */
     readonly takenIds: ReadonlySet<string>;
     readonly styles: DocxStyles;
+    /** The largest `w:id` of the main part, over revisions and range markup alike; 0 without any. */
+    get maxRevisionId(): number;
     private constructor();
     /**
      * Builds the index. `unauthored` carries the ids of the paragraphs that

package/dist/edit/docx/model.js

@@ -15,6 +15,17 @@ export class DocxModel {
     unauthoredIds;
     takenIds;
     styles;
+    #maxRevisionId;
+    /** The largest `w:id` of the main part, over revisions and range markup alike; 0 without any. */
+    get maxRevisionId() {
+        if (this.#maxRevisionId === undefined) {
+            let max = 0;
+            for (const match of this.document.text.matchAll(/ w:id="(\d{1,9})"/g))
+                max = Math.max(max, Number(match[1]));
+            this.#maxRevisionId = max;
+        }
+        return this.#maxRevisionId;
+    }
     constructor(revision, mainPart, document, body, 
     /** The body's own `w:sectPr`, when present. */
     bodySectPr, 

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

@@ -15,6 +15,16 @@ export interface DocxOperationContext {
     readonly operationIndex: number;
     /** A paragraph id no paragraph of the document or of this batch uses. */
     freshParagraphId(): string;
+    /** Set when the batch writes tracked changes: who, and when. */
+    readonly tracked?: TrackedChange;
+    /** A `w:id` no revision of the document or of this batch uses. */
+    nextRevisionId(): number;
+}
+/** What every revision of a tracked batch records. */
+export interface TrackedChange {
+    readonly author: string;
+    /** ISO 8601; left out of the file when the batch has no timestamp. */
+    readonly date?: string;
 }
 export interface DocxOperationResult {
     readonly createdIds: readonly string[];

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

@@ -1,13 +1,16 @@
 import type { EditEngineContext } from "../engine.js";
 import { type OoxmlEditProviderOptions } from "../ooxml/worker.js";
 import { WorkerEngineClient } from "../worker-engine.js";
+import type { DocxEngineReads } from "./engine.js";
+import type { DocxRevision } from "./types.js";
 export type DocxEditProviderOptions = OoxmlEditProviderOptions;
 /**
  * Starts the OOXML edit worker for `original` as a DOCX engine. Loaded
  * lazily by the Office adapter's provider on the first `edit()`.
  */
 export declare function loadDocxEditEngine(original: Uint8Array, context: EditEngineContext, options?: DocxEditProviderOptions): Promise<DocxEditEngineClient>;
-export declare class DocxEditEngineClient extends WorkerEngineClient {
+export declare class DocxEditEngineClient extends WorkerEngineClient implements DocxEngineReads {
     readonly schemas: import("../types.js").OperationSchemaSet;
+    revisions(id: string, signal: AbortSignal): Promise<readonly DocxRevision[]>;
     start(original: Uint8Array): Promise<void>;
 }

package/dist/edit/docx/provider.js

@@ -21,6 +21,9 @@ export async function loadDocxEditEngine(original, context, options = {}) {
 }
 export class DocxEditEngineClient extends WorkerEngineClient {
     schemas = docxOperationSchemas;
+    revisions(id, signal) {
+        return this.request("edit-docx-revisions", { id }, signal);
+    }
     async start(original) {
         const data = original.slice().buffer;
         const open = {

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

@@ -1,6 +1,7 @@
+import type { DescribeOptions, DocumentDescription, EditCheckpoint, OutlineOptions, OutlineResult, TargetCandidate, TargetQuery, ToolCall, ToolCallOptions, ToolResult, ToolSet } from "../ai/types.js";
 import type { EditSessionAccess, EditSessionCore } from "../engine.js";
 import type { ApplyOptions, AssetOptions, EditFindOptions, EditOperation, EditReceipt, EditState, ElementQuery, HistoryOptions, OperationSchemaSet, PagePoint, PageRect, ReadItem, ReadOptions, ReadResult, SavedDocument, TextTarget } from "../types.js";
-import type { DocxDeleteElementOperation, DocxEditSession, DocxElement, DocxFields, DocxInsertImageOperation, DocxInsertParagraphOperation, DocxInsertTableOperation, DocxMoveElementOperation, DocxOperation, DocxReplaceTextOperation, DocxSaveOptions, DocxSetParagraphStyleOperation, DocxSetTableCellOperation, DocxSetTextStyleOperation } from "./types.js";
+import type { DocxDeleteElementOperation, DocxEditSession, DocxElement, DocxFields, DocxInsertImageOperation, DocxInsertParagraphOperation, DocxInsertTableOperation, DocxMoveElementOperation, DocxOperation, DocxReplaceTextOperation, DocxRevision, DocxSaveOptions, DocxSetParagraphStyleOperation, DocxSetTableCellOperation, DocxSetTextStyleOperation } from "./types.js";
 /** Per paragraph id (eight hex digits), the union of its runs per page. */
 type Placement = ReadonlyMap<string, ReadonlyMap<number, PageRect>>;
 export declare class DocxSession implements DocxEditSession {
@@ -22,6 +23,16 @@ export declare class DocxSession implements DocxEditSession {
     getElement(id: string, options?: ReadOptions): Promise<ReadItem<DocxElement>>;
     elementsAt(pageIndex: number, point: PagePoint, options?: ReadOptions): Promise<ReadResult<DocxElement>>;
     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>;
+    getRevisions(elementId: string, options?: ReadOptions): Promise<ReadResult<DocxRevision>>;
     replaceText(fields: DocxFields<DocxReplaceTextOperation>, options?: ApplyOptions): Promise<EditReceipt>;
     setTextStyle(fields: DocxFields<DocxSetTextStyleOperation>, options?: ApplyOptions): Promise<EditReceipt>;
     setParagraphStyle(fields: DocxFields<DocxSetParagraphStyleOperation>, options?: ApplyOptions): Promise<EditReceipt>;

package/dist/edit/docx/session.js

@@ -1,6 +1,11 @@
+import { readDescription, readOutline } from "../ai/outline.js";
+import { resolveTargets } from "../ai/targets.js";
+import { buildToolSet, callTool as runTool } from "../ai/tools.js";
+import { ViewerError } from "../../errors.js";
 export class DocxSession {
     format = "docx";
     #core;
+    #tools;
     #access;
     constructor(core, access) {
         this.#core = core;
@@ -99,6 +104,36 @@ export class DocxSession {
             : placed;
         return Object.freeze({ ...found, items });
     }
+    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);
+    }
+    getRevisions(elementId, options) {
+        return this.#core.readItems(options, (engine, signal) => docxReads(engine).revisions(elementId, signal));
+    }
     replaceText(fields, options) {
         return this.apply([{ op: "replaceText", ...fields }], options);
     }
@@ -424,3 +459,9 @@ function matchesQuery(element, query) {
         return false;
     return !query.intersects || rectsIntersect(fragment.bounds, query.intersects);
 }
+function docxReads(engine) {
+    const candidate = engine;
+    if (typeof candidate.revisions !== "function")
+        throw new ViewerError("edit-unsupported", "The engine does not provide the DOCX reads", { details: { format: "docx", reason: "no-reads" } });
+    return candidate;
+}

package/dist/edit/docx/structure-ops.js

@@ -4,6 +4,7 @@ import { patches } from "../ooxml/patch.js";
 import { relativeTarget } from "../ooxml/transaction.js";
 import { OFFICE_RELATIONSHIPS, W_NS } from "./ids.js";
 import { firstTextItem } from "./text.js";
+import { deletedParagraphXml, insertedRunXml, markedParagraphProperties, trackedRangeProblem, unsupportedTracked, } from "./tracked.js";
 import { attributeProblem, changedRunProperties, colorProblem, namespacePatches, normalizeText, paragraphPropertiesWithoutSection, paragraphXml, runContentXml, runXml, sliceOf, textProblem, } from "./write.js";
 /*
  * Structure: paragraphs inserted next to other elements, paragraphs,
@@ -168,15 +169,17 @@ export const insertParagraphHandler = {
         const rPr = operation.style
             ? changedRunProperties(part, sourceRPr, operation.style, context.model.styles)
             : sliceOf(part, sourceRPr);
-        const pPr = record.kind === "paragraph"
-            ? paragraphPropertiesWithoutSection(part, record.pPr)
-            : "";
+        const sourcePPr = record.kind === "paragraph" ? record.pPr : undefined;
+        const pPr = paragraphPropertiesWithoutSection(part, sourcePPr);
         const segments = normalizeText(operation.text).split("\n");
         const createdIds = [];
         const xml = segments.map((segment) => {
             const id = context.freshParagraphId();
             createdIds.push(`p:${id}`);
-            return paragraphXml(undefined, id, pPr, runXml(rPr, runContentXml(segment)));
+            // Tracked: the paragraph mark and the run are both insertions.
+            return context.tracked
+                ? paragraphXml(undefined, id, markedParagraphProperties(context, sourcePPr, "ins"), insertedRunXml(context, rPr, segment))
+                : paragraphXml(undefined, id, pPr, runXml(rPr, runContentXml(segment)));
         });
         // Inserts at one position land in call order, so the paragraphs
         // keep their order on either side of the reference.
@@ -236,7 +239,15 @@ export const deleteElementHandler = {
                 : `No element ${operation.target}`);
             return;
         }
+        if (context.tracked && record.kind !== "paragraph") {
+            unsupportedTracked(issue, "/target", "Deleting a table or a picture");
+            return;
+        }
         if (record.kind === "paragraph") {
+            if (context.tracked &&
+                !record.readOnlyReason &&
+                trackedRangeProblem(record, 0, record.text.text.length, issue, "/target"))
+                return;
             if (record.sectPr)
                 issue("/target", "section-break", "A paragraph that ends a section cannot be deleted");
             else if (record.readOnlyReason)
@@ -253,6 +264,22 @@ export const deleteElementHandler = {
             return deleteInline(context, found);
         const record = found;
         const node = blockNode(record);
+        if (context.tracked && record.kind === "paragraph") {
+            // The paragraph stays, marked deleted; its inline objects leave
+            // the model with their runs, Word drops the rest on accept.
+            const nested = paragraphIdsUnder(model, node).filter((id) => id !== record.id);
+            return commit(context, [
+                patches.replaceElement(part, node, deletedParagraphXml(context, record)),
+            ], {
+                createdIds: [],
+                removedIds: record.inlines.map((inline) => inline.elementId),
+                ...(nested.length > 0 ? { removedParagraphIds: nested } : {}),
+                ...(model.unauthoredSet.has(record.id)
+                    ? { stamped: [record.id] }
+                    : {}),
+                reflowFrom: record.id,
+            });
+        }
         const items = [patches.removeElement(part, node)];
         const createdIds = [];
         if (model.blocks.includes(record)) {
@@ -310,6 +337,10 @@ function stripNode(part, node) {
 }
 export const moveElementHandler = {
     async validate(operation, context, issue) {
+        if (context.tracked) {
+            unsupportedTracked(issue, "", "Moving an element");
+            return;
+        }
         const record = context.model.byId.get(operation.target);
         if (!record || (record.kind !== "paragraph" && record.kind !== "table")) {
             issue("/target", record ? "invalid-target" : "unknown-target", record
@@ -449,6 +480,10 @@ function drawingNamespacePatches(part) {
 }
 export const insertImageHandler = {
     async validate(operation, context, issue) {
+        if (context.tracked) {
+            unsupportedTracked(issue, "", "Inserting a picture");
+            return;
+        }
         placement(operation, context, issue);
         try {
             const bytes = resolveBinary(operation.data, context.assets);