web-doc 0.6.2 → 0.8.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/assets.d.ts

@@ -0,0 +1,23 @@
+import type { BinaryData, JsonSchema } from "./types.js";
+export declare function isAssetReference(value: unknown): value is string;
+/** The content-addressed id of `bytes`. */
+export declare function assetIdOf(bytes: Uint8Array): Promise<string>;
+/** Something that answers an asset reference with its bytes. */
+export interface AssetSource {
+    get(id: string): Uint8Array | undefined;
+}
+export declare class AssetStore implements AssetSource {
+    #private;
+    get(id: string): Uint8Array | undefined;
+    has(id: string): boolean;
+    set(id: string, bytes: Uint8Array): void;
+    /** Bytes held, for limits. */
+    get byteLength(): number;
+}
+/**
+ * Bytes of a `BinaryData` value that passed schema validation: inline bytes,
+ * a base64 string, or an asset reference the store knows.
+ */
+export declare function resolveBinary(data: BinaryData, assets: AssetSource): Uint8Array;
+/** Names of an operation's top-level properties its schema marks as binary. */
+export declare function binaryFields(schema: JsonSchema | undefined): string[];

package/dist/edit/assets.js

@@ -0,0 +1,75 @@
+import { ViewerError } from "../errors.js";
+/*
+ * Binary payloads of operations live in a content-addressed store for the
+ * session: an operation refers to them as `asset:<sha-256 hex>`, so the
+ * history, undo, redo, dry runs and recovery never copy image bytes again.
+ */
+const REFERENCE = /^asset:[0-9a-f]{64}$/;
+export function isAssetReference(value) {
+    return typeof value === "string" && REFERENCE.test(value);
+}
+/** The content-addressed id of `bytes`. */
+export async function assetIdOf(bytes) {
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes.slice().buffer);
+    let hex = "";
+    for (const byte of new Uint8Array(digest))
+        hex += byte.toString(16).padStart(2, "0");
+    return `asset:${hex}`;
+}
+export class AssetStore {
+    #bytes = new Map();
+    #total = 0;
+    get(id) {
+        return this.#bytes.get(id);
+    }
+    has(id) {
+        return this.#bytes.has(id);
+    }
+    set(id, bytes) {
+        if (this.#bytes.has(id))
+            return;
+        this.#bytes.set(id, bytes);
+        this.#total += bytes.byteLength;
+    }
+    /** Bytes held, for limits. */
+    get byteLength() {
+        return this.#total;
+    }
+}
+/**
+ * Bytes of a `BinaryData` value that passed schema validation: inline bytes,
+ * a base64 string, or an asset reference the store knows.
+ */
+export function resolveBinary(data, assets) {
+    if (data instanceof Uint8Array)
+        return data;
+    if (isAssetReference(data)) {
+        const bytes = assets.get(data);
+        if (!bytes)
+            throw new ViewerError("invalid-operation", `Unknown asset ${data}`, {
+                details: {
+                    issues: [
+                        {
+                            operationIndex: -1,
+                            path: "",
+                            code: "unknown-asset",
+                            message: `Unknown asset ${data}`,
+                        },
+                    ],
+                },
+            });
+        return bytes;
+    }
+    return Uint8Array.from(atob(data), (character) => character.charCodeAt(0));
+}
+/** Names of an operation's top-level properties its schema marks as binary. */
+export function binaryFields(schema) {
+    const properties = schema?.properties;
+    if (!properties || typeof properties !== "object")
+        return [];
+    return Object.entries(properties)
+        .filter(([, property]) => typeof property === "object" &&
+        property !== null &&
+        property["x-binary"] === true)
+        .map(([name]) => name);
+}

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

@@ -0,0 +1,6 @@
+import type { PageRect } from "../types.js";
+import { type AnyRecord, type DocxModel } from "./model.js";
+import type { DocxElement } from "./types.js";
+export declare const NO_PAGE = -1;
+export declare const EMPTY_RECT: PageRect;
+export declare function toElement(model: DocxModel, record: AnyRecord): DocxElement;

package/dist/edit/docx/elements.js

@@ -0,0 +1,90 @@
+import { tableRows, tableText, } from "./model.js";
+import { IMPLEMENTED_OPERATIONS } from "./schemas.js";
+import { resolveParagraphStyle, resolveTextStyle } from "./style.js";
+import { firstTextItem } from "./text.js";
+/*
+ * `DocxElement` values from the model's records, without geometry: the
+ * engine never lays out, so `pageIndex` is −1 and `bounds` empty until
+ * the session joins the renderer's runs on the main thread.
+ */
+export const NO_PAGE = -1;
+export const EMPTY_RECT = { x: 0, y: 0, width: 0, height: 0 };
+/** The operations each kind accepts once its handler ships. */
+const OPERATIONS = {
+    paragraph: [
+        "replaceText",
+        "setTextStyle",
+        "setParagraphStyle",
+        "insertParagraph",
+        "insertTable",
+        "insertImage",
+        "moveElement",
+        "deleteElement",
+    ],
+    table: [
+        "setTableCell",
+        "insertParagraph",
+        "insertTable",
+        "insertImage",
+        "moveElement",
+        "deleteElement",
+    ],
+    image: ["deleteElement"],
+    other: [],
+};
+/** A read-only paragraph only accepts siblings placed next to it. */
+const INSERTIONS = ["insertParagraph", "insertTable", "insertImage"];
+function operationsOf(kind, readOnly) {
+    return OPERATIONS[kind].filter((name) => IMPLEMENTED_OPERATIONS.includes(name) &&
+        (!readOnly || INSERTIONS.includes(name)));
+}
+export function toElement(model, record) {
+    const base = {
+        pageIndex: NO_PAGE,
+        bounds: EMPTY_RECT,
+        fragments: [],
+        story: { kind: "body" },
+    };
+    if (record.kind === "paragraph")
+        return paragraphElement(model, record, base);
+    if (record.kind === "table")
+        return {
+            ...base,
+            id: record.elementId,
+            kind: "table",
+            text: tableText(record),
+            table: { rows: tableRows(record) },
+            operations: operationsOf("table", false),
+        };
+    return {
+        ...base,
+        id: record.elementId,
+        kind: record.kind,
+        parentId: record.paragraph.elementId,
+        ...(record.kind === "image" && record.extent
+            ? {
+                imageSize: {
+                    width: record.extent.cx / EMU_PER_PX,
+                    height: record.extent.cy / EMU_PER_PX,
+                },
+            }
+            : {}),
+        operations: operationsOf(record.kind, false),
+    };
+}
+/** EMU per CSS pixel at 96 dpi. */
+const EMU_PER_PX = 9525;
+function paragraphElement(model, record, base) {
+    const first = firstTextItem(record.text);
+    return {
+        ...base,
+        id: record.elementId,
+        kind: "paragraph",
+        text: record.text.text,
+        ...(record.table ? { parentId: record.table.elementId } : {}),
+        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),
+    };
+}

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

@@ -0,0 +1,57 @@
+import type { ResourceLimits } from "../../contracts.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, 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();
+    /** Opens the package and reads the block index, so a broken document fails here. */
+    static open(bytes: Uint8Array, limits: ResourceLimits, signal?: AbortSignal): Promise<DocxEditEngine>;
+    /** The package behind the engine, for tests and the operations. */
+    get package(): OoxmlPackage;
+    /** The engine has no pages of its own; the renderer counts them. */
+    get pageCount(): number;
+    /** The block index at the current revision. */
+    model(signal?: AbortSignal): Promise<DocxModel>;
+    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
+     * the paragraphs the session rebuilt or created. `show` also stamps every
+     * other paragraph with the id the engine knows it by, in a copy, so the
+     * display pre-pass and the viewer's runs name the engine's paragraphs
+     * after edits that moved paragraphs around. Without changes both are
+     * the original bytes.
+     */
+    materializeDocument(purposeOrSignal?: "show" | "save" | AbortSignal, _options?: MaterializeOptions, signal?: AbortSignal): Promise<MaterializedDocument>;
+    restore(input: RestoreTarget | readonly (readonly EditOperation[])[], signal: AbortSignal): Promise<void>;
+    putAsset(id: string, data: Uint8Array, _signal: AbortSignal): Promise<void>;
+    /**
+     * Every element of the body story, in document order, without geometry.
+     * `pageIndex` and `intersects` are the session's to apply once the runs
+     * are joined; `kinds` filters here.
+     */
+    getElements(query: ElementQuery, signal: AbortSignal): Promise<readonly DocxElement[]>;
+    getElement(id: string, signal: AbortSignal): Promise<DocxElement | undefined>;
+    /** The record an element id names, at the current revision. */
+    locate(id: string, signal?: AbortSignal): Promise<AnyRecord | undefined>;
+    /** Hit-testing needs the renderer's geometry; the session answers it. */
+    elementsAt(_pageIndex: number, _point: PagePoint, _signal: AbortSignal): Promise<readonly DocxElement[]>;
+    /**
+     * Matches in paragraph text, in document order, without rectangles or
+     * pages: the session adds those from the renderer's runs.
+     */
+    findText(query: string, options: EditFindOptions, signal: AbortSignal): Promise<readonly TextTarget[]>;
+    dispose(): Promise<void>;
+}