web-doc 0.6.2 → 0.7.0

package/dist/edit/session.d.ts

@@ -0,0 +1,66 @@
+import type { ResourceLimits, ViewerEventMap } from "../contracts.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. */
+export interface EditSessionHost {
+    readonly format: EditableFormat;
+    readonly limits: ResourceLimits;
+    /** Opens `bytes` next to the current document; may fail or be aborted. */
+    prepareDocument(bytes: Uint8Array, signal: AbortSignal): Promise<PreparedDocument>;
+    /**
+     * Shows a prepared document: synchronous, cannot fail, and returns the page
+     * count the renderer reports. `changedPages` lets the viewer repaint only
+     * what changed.
+     */
+    commitDocument(prepared: PreparedDocument, changedPages: readonly number[]): number;
+    /** Releases a preparation that will not be shown. */
+    discardDocument(prepared: PreparedDocument): void;
+    /**
+     * Flow formats: the first page whose text runs carry `paragraphId`, when
+     * the host has laid it out; the core repaints from it to the end.
+     */
+    pageOf?(paragraphId: string): number | undefined;
+    emit<K extends "editstatechange" | "documentchange">(type: K, event: ViewerEventMap[K]): void;
+}
+/** What `prepareDocument` hands back; hosts attach their own handle to it. */
+export interface PreparedDocument {
+    readonly pageCount: number;
+}
+/**
+ * The format-independent editing session: validation, history, revisions,
+ * saving and the viewer refresh. Format modules wrap it to add typed methods.
+ * Calls run one at a time in call order.
+ */
+export declare class EditSessionController implements EditSessionCore {
+    #private;
+    readonly format: EditableFormat;
+    readonly schemas: OperationSchemaSet;
+    readonly sessionId: string;
+    constructor(engine: EditEngine, host: EditSessionHost, original: Uint8Array, originalPageCount: number);
+    get state(): EditState;
+    applyJson(operations: readonly EditOperation[], options?: ApplyOptions): Promise<EditReceipt>;
+    apply(operations: readonly EditOperation[], options?: ApplyOptions): Promise<EditReceipt>;
+    undo(options?: HistoryOptions): Promise<EditReceipt>;
+    redo(options?: HistoryOptions): Promise<EditReceipt>;
+    reset(options?: HistoryOptions): Promise<EditReceipt>;
+    save(options?: SaveOptions): Promise<SavedDocument>;
+    /** Records that the host persisted the state a `save()` token names. */
+    markSaved(stateToken: string): void;
+    getElements(query?: ElementQuery, options?: ReadOptions): Promise<ReadResult<EditElement>>;
+    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>>;
+    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>>;
+    /**
+     * Ends the session: pending calls reject with `aborted`, later calls with
+     * `lifecycle-error`, the engine is disposed and `active: false` is emitted.
+     */
+    end(): Promise<void>;
+    get ended(): boolean;
+    /** False once the session ended or a failed recovery left it inconsistent. */
+    get usable(): boolean;
+    addAsset(data: Uint8Array, options?: AssetOptions): Promise<string>;
+}
+/** Surfaces a listener's exception without failing the call that emitted the event. */
+export declare function reportError(error: unknown): void;