@pixerate/editor 0.144.0 → 0.146.0

package/dist/persistence/documentTools.d.ts

@@ -0,0 +1,35 @@
+import type { AgentToolProvider } from "../tools/registry.js";
+import type { EditorDocumentStore } from "./documentStore.js";
+import type { EditorDocument } from "./editorDocument.js";
+export interface DocumentToolProviderOptions {
+    /** Provider id (default `<kind>-document`). */
+    id?: string;
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the id, `''` for bare names. */
+    namespace?: string;
+    /** Toolset title (default "<Noun> document"). */
+    title?: string;
+    /** The skill that documents the editor's tools, e.g. `pixerate-diagram`. */
+    skill?: string;
+    /** What the document is called in descriptions (default the kind with spaces, e.g. "video project"). */
+    noun?: string;
+    /**
+     * Add `undo_<kind>` / `redo_<kind>` (default `true`). Pass `false` for editors
+     * whose own provider already has them.
+     */
+    history?: boolean;
+    /** Saved documents: adds `save_<kind>_document`, `list_saved_<kind>_documents` and `open_saved_<kind>_document`. */
+    store?: EditorDocumentStore;
+    /** Name `save_<kind>_document` uses when none is given (default "Untitled <noun>"). */
+    name?: () => string | undefined;
+    /** `get_<kind>_document` refuses documents whose JSON is longer than this (default 200000 characters). */
+    maxChars?: number;
+}
+/**
+ * The same document tools for every editor, named after `doc.kind`:
+ * `get_<kind>_document`, `load_<kind>_document`, `undo_<kind>`, `redo_<kind>`
+ * and, with a `store`, `save_<kind>_document`, `list_saved_<kind>_documents`
+ * and `open_saved_<kind>_document`. Loads are checked before anything changes
+ * and are one undo step where the editor supports it. A read-only document
+ * keeps its read tools; its write tools refuse with the reason.
+ */
+export declare function createDocumentToolProvider(doc: EditorDocument, options?: DocumentToolProviderOptions): AgentToolProvider;

package/dist/persistence/editorAutosave.d.cts

@@ -0,0 +1,33 @@
+import { type AutosaveController, type AutosaveControllerOptions, type AutosaveRecovery } from "./autosave.cjs";
+import { type EditorDocument, type EditorDocumentFile } from "./editorDocument.cjs";
+import type { LoadReport } from "./migrate.cjs";
+import { type DirtyFlagSource, type RevisionTracker } from "./revisions.cjs";
+export interface EditorAutosaveOptions extends Omit<AutosaveControllerOptions<EditorDocumentFile>, "getSnapshot" | "serialize" | "deserialize" | "revision" | "savedRevision" | "key"> {
+    /** Snapshot key (default the document's `kind`). */
+    key?: string;
+    /**
+     * Saved-vs-current flag (e.g. `bindDirtyToHistory`), so undoing back to the
+     * saved state needs no snapshot. Without it, every change counts until `markClean()`.
+     */
+    dirty?: DirtyFlagSource;
+}
+export interface EditorAutosave {
+    readonly controller: AutosaveController<EditorDocumentFile>;
+    readonly revisions: RevisionTracker;
+    /** An earlier session's unsaved snapshot of this document, or `null`. */
+    checkRecovery(): Promise<AutosaveRecovery<EditorDocumentFile> | null>;
+    /** Loads a recovered snapshot into the document and starts autosaving. */
+    restore(recovery: AutosaveRecovery<EditorDocumentFile>): LoadReport;
+    /** Deletes the earlier session's snapshot and starts autosaving. */
+    discard(): Promise<void>;
+    /** Call after an explicit save. */
+    markClean(): Promise<void>;
+    destroy(): void;
+}
+/**
+ * Crash-recovery autosave for any editor: snapshots `doc` as an
+ * `EditorDocumentFile` after each change. Like `createAutosaveController`,
+ * nothing is written until the recovery check is settled: call
+ * `controller.ready()` when nothing was found, or `restore` / `discard`.
+ */
+export declare function createEditorAutosave(doc: EditorDocument, options: EditorAutosaveOptions): EditorAutosave;

package/dist/persistence/editorAutosave.d.ts

@@ -0,0 +1,33 @@
+import { type AutosaveController, type AutosaveControllerOptions, type AutosaveRecovery } from "./autosave.js";
+import { type EditorDocument, type EditorDocumentFile } from "./editorDocument.js";
+import type { LoadReport } from "./migrate.js";
+import { type DirtyFlagSource, type RevisionTracker } from "./revisions.js";
+export interface EditorAutosaveOptions extends Omit<AutosaveControllerOptions<EditorDocumentFile>, "getSnapshot" | "serialize" | "deserialize" | "revision" | "savedRevision" | "key"> {
+    /** Snapshot key (default the document's `kind`). */
+    key?: string;
+    /**
+     * Saved-vs-current flag (e.g. `bindDirtyToHistory`), so undoing back to the
+     * saved state needs no snapshot. Without it, every change counts until `markClean()`.
+     */
+    dirty?: DirtyFlagSource;
+}
+export interface EditorAutosave {
+    readonly controller: AutosaveController<EditorDocumentFile>;
+    readonly revisions: RevisionTracker;
+    /** An earlier session's unsaved snapshot of this document, or `null`. */
+    checkRecovery(): Promise<AutosaveRecovery<EditorDocumentFile> | null>;
+    /** Loads a recovered snapshot into the document and starts autosaving. */
+    restore(recovery: AutosaveRecovery<EditorDocumentFile>): LoadReport;
+    /** Deletes the earlier session's snapshot and starts autosaving. */
+    discard(): Promise<void>;
+    /** Call after an explicit save. */
+    markClean(): Promise<void>;
+    destroy(): void;
+}
+/**
+ * Crash-recovery autosave for any editor: snapshots `doc` as an
+ * `EditorDocumentFile` after each change. Like `createAutosaveController`,
+ * nothing is written until the recovery check is settled: call
+ * `controller.ready()` when nothing was found, or `restore` / `discard`.
+ */
+export declare function createEditorAutosave(doc: EditorDocument, options: EditorAutosaveOptions): EditorAutosave;

package/dist/persistence/editorDocument.d.cts

@@ -0,0 +1,118 @@
+import { type LoadReport } from "./migrate.cjs";
+/**
+ * Undo / redo of an editor. Satisfies `HistoryCommandTarget`, so
+ * `createHistoryCommands(doc.history)` works for every editor.
+ */
+export interface EditorDocumentHistory {
+    /** Returns `false` when there was nothing to undo. */
+    undo(): boolean;
+    /** Returns `false` when there was nothing to redo. */
+    redo(): boolean;
+    getState(): {
+        canUndo: boolean;
+        canRedo: boolean;
+        undoName?: string;
+        redoName?: string;
+    };
+}
+export interface LoadEditorDocumentOptions {
+    /**
+     * `"reset"` (default) opens the document fresh and clears the undo stack.
+     * `"record"` makes the load one undo step (agent loads); editors whose
+     * `recordsLoads` is `false` reset instead.
+     */
+    history?: "reset" | "record";
+}
+/**
+ * The save / load / undo contract every editor exposes (e.g.
+ * `createDiagramEditorDocument(controller)`). Autosave
+ * (`createEditorAutosave`), the agent tools (`createDocumentToolProvider`) and
+ * the React / Svelte wrappers take it, so they work the same for every editor.
+ */
+export interface EditorDocument<T = unknown> {
+    /** Editor domain, e.g. `"diagram"`; names the tools and storage keys (`[a-z][a-z0-9_]*`). */
+    readonly kind: string;
+    /** The format version `getDocument()` writes; older files are migrated on load. */
+    readonly formatVersion: number;
+    /** Whether `loadDocument(…, { history: "record" })` is one undo step. */
+    readonly recordsLoads: boolean;
+    /** Plain JSON snapshot of the whole document; `loadDocument(getDocument())` changes nothing. */
+    getDocument(): T;
+    /**
+     * Replaces the document with a raw document or an `EditorDocumentFile`.
+     * Validates and migrates first: throws `EditorDocumentLoadError` and changes
+     * nothing when the input does not fit.
+     */
+    loadDocument(input: unknown, options?: LoadEditorDocumentOptions): LoadReport;
+    /** Bumped on every document change, including undo, redo and load (not on selection). */
+    revision(): number;
+    /** Called after every document change. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    readonly history: EditorDocumentHistory;
+    /** Why the document cannot be changed (a sentence, e.g. "The diagram is read-only."), or `false`. */
+    readOnly(): string | false;
+    /** Stops listening to the editor; `subscribe` or `revision` reconnects (React StrictMode remounts). */
+    destroy(): void;
+}
+/** Thrown by `loadDocument` / `parseEditorDocument` when the input does not fit; nothing changed. */
+export declare class EditorDocumentLoadError extends Error {
+    /** The `LoadReport` when the input was a file that could not be migrated. */
+    readonly report?: LoadReport;
+    constructor(message: string, report?: LoadReport);
+}
+/** Marker of a saved editor document file (`EditorDocumentFile.format`). */
+export declare const EDITOR_DOCUMENT_FORMAT = "pixerate.editor-document";
+/** A document as it is saved: names its editor and format version. */
+export interface EditorDocumentFile<T = unknown> {
+    format: typeof EDITOR_DOCUMENT_FORMAT;
+    kind: string;
+    formatVersion: number;
+    /** Display name, when it has one. */
+    name?: string;
+    document: T;
+}
+export declare function isEditorDocumentFile(value: unknown): value is EditorDocumentFile;
+/** The current document wrapped as a file (what autosave and the save tools store). */
+export declare function toEditorDocumentFile<T>(doc: EditorDocument<T>, name?: string): EditorDocumentFile<T>;
+/** JSON text of the current document as a file. */
+export declare function serializeEditorDocument(doc: EditorDocument, options?: {
+    name?: string;
+    space?: number;
+}): string;
+/**
+ * Parses a file written by `serializeEditorDocument`. With `kind`, a file of
+ * another editor is refused. Throws `EditorDocumentLoadError` with a message
+ * that says what is wrong.
+ */
+export declare function parseEditorDocument<T = unknown>(text: string, options?: {
+    kind?: string;
+}): EditorDocumentFile<T>;
+/** What an editor supplies to `defineEditorDocument`. */
+export interface EditorDocumentSpec<T> {
+    kind: string;
+    /** Default 1. */
+    formatVersion?: number;
+    /** Default `true`: `load` honours `history: "record"`. */
+    recordsLoads?: boolean;
+    get(): T;
+    /**
+     * Replaces the document. Throw (with a message saying what is wrong) before
+     * changing anything when `document` does not fit.
+     */
+    load(document: unknown, options: {
+        history: "reset" | "record";
+    }): void;
+    /** Calls `listener` after each document change (not selection or view changes). */
+    subscribe(listener: () => void): () => void;
+    history: EditorDocumentHistory;
+    /** Why the document cannot be changed, or `false` (default: never read-only). */
+    readOnly?: () => string | false;
+    /** `migrations[v]` turns a version `v` document into version `v + 1`. */
+    migrations?: Record<number, (document: unknown) => unknown>;
+}
+/**
+ * Builds an `EditorDocument` from an editor's own methods: counts revisions,
+ * unwraps and migrates files, and turns load failures into
+ * `EditorDocumentLoadError`.
+ */
+export declare function defineEditorDocument<T>(spec: EditorDocumentSpec<T>): EditorDocument<T>;

package/dist/persistence/editorDocument.d.ts

@@ -0,0 +1,118 @@
+import { type LoadReport } from "./migrate.js";
+/**
+ * Undo / redo of an editor. Satisfies `HistoryCommandTarget`, so
+ * `createHistoryCommands(doc.history)` works for every editor.
+ */
+export interface EditorDocumentHistory {
+    /** Returns `false` when there was nothing to undo. */
+    undo(): boolean;
+    /** Returns `false` when there was nothing to redo. */
+    redo(): boolean;
+    getState(): {
+        canUndo: boolean;
+        canRedo: boolean;
+        undoName?: string;
+        redoName?: string;
+    };
+}
+export interface LoadEditorDocumentOptions {
+    /**
+     * `"reset"` (default) opens the document fresh and clears the undo stack.
+     * `"record"` makes the load one undo step (agent loads); editors whose
+     * `recordsLoads` is `false` reset instead.
+     */
+    history?: "reset" | "record";
+}
+/**
+ * The save / load / undo contract every editor exposes (e.g.
+ * `createDiagramEditorDocument(controller)`). Autosave
+ * (`createEditorAutosave`), the agent tools (`createDocumentToolProvider`) and
+ * the React / Svelte wrappers take it, so they work the same for every editor.
+ */
+export interface EditorDocument<T = unknown> {
+    /** Editor domain, e.g. `"diagram"`; names the tools and storage keys (`[a-z][a-z0-9_]*`). */
+    readonly kind: string;
+    /** The format version `getDocument()` writes; older files are migrated on load. */
+    readonly formatVersion: number;
+    /** Whether `loadDocument(…, { history: "record" })` is one undo step. */
+    readonly recordsLoads: boolean;
+    /** Plain JSON snapshot of the whole document; `loadDocument(getDocument())` changes nothing. */
+    getDocument(): T;
+    /**
+     * Replaces the document with a raw document or an `EditorDocumentFile`.
+     * Validates and migrates first: throws `EditorDocumentLoadError` and changes
+     * nothing when the input does not fit.
+     */
+    loadDocument(input: unknown, options?: LoadEditorDocumentOptions): LoadReport;
+    /** Bumped on every document change, including undo, redo and load (not on selection). */
+    revision(): number;
+    /** Called after every document change. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    readonly history: EditorDocumentHistory;
+    /** Why the document cannot be changed (a sentence, e.g. "The diagram is read-only."), or `false`. */
+    readOnly(): string | false;
+    /** Stops listening to the editor; `subscribe` or `revision` reconnects (React StrictMode remounts). */
+    destroy(): void;
+}
+/** Thrown by `loadDocument` / `parseEditorDocument` when the input does not fit; nothing changed. */
+export declare class EditorDocumentLoadError extends Error {
+    /** The `LoadReport` when the input was a file that could not be migrated. */
+    readonly report?: LoadReport;
+    constructor(message: string, report?: LoadReport);
+}
+/** Marker of a saved editor document file (`EditorDocumentFile.format`). */
+export declare const EDITOR_DOCUMENT_FORMAT = "pixerate.editor-document";
+/** A document as it is saved: names its editor and format version. */
+export interface EditorDocumentFile<T = unknown> {
+    format: typeof EDITOR_DOCUMENT_FORMAT;
+    kind: string;
+    formatVersion: number;
+    /** Display name, when it has one. */
+    name?: string;
+    document: T;
+}
+export declare function isEditorDocumentFile(value: unknown): value is EditorDocumentFile;
+/** The current document wrapped as a file (what autosave and the save tools store). */
+export declare function toEditorDocumentFile<T>(doc: EditorDocument<T>, name?: string): EditorDocumentFile<T>;
+/** JSON text of the current document as a file. */
+export declare function serializeEditorDocument(doc: EditorDocument, options?: {
+    name?: string;
+    space?: number;
+}): string;
+/**
+ * Parses a file written by `serializeEditorDocument`. With `kind`, a file of
+ * another editor is refused. Throws `EditorDocumentLoadError` with a message
+ * that says what is wrong.
+ */
+export declare function parseEditorDocument<T = unknown>(text: string, options?: {
+    kind?: string;
+}): EditorDocumentFile<T>;
+/** What an editor supplies to `defineEditorDocument`. */
+export interface EditorDocumentSpec<T> {
+    kind: string;
+    /** Default 1. */
+    formatVersion?: number;
+    /** Default `true`: `load` honours `history: "record"`. */
+    recordsLoads?: boolean;
+    get(): T;
+    /**
+     * Replaces the document. Throw (with a message saying what is wrong) before
+     * changing anything when `document` does not fit.
+     */
+    load(document: unknown, options: {
+        history: "reset" | "record";
+    }): void;
+    /** Calls `listener` after each document change (not selection or view changes). */
+    subscribe(listener: () => void): () => void;
+    history: EditorDocumentHistory;
+    /** Why the document cannot be changed, or `false` (default: never read-only). */
+    readOnly?: () => string | false;
+    /** `migrations[v]` turns a version `v` document into version `v + 1`. */
+    migrations?: Record<number, (document: unknown) => unknown>;
+}
+/**
+ * Builds an `EditorDocument` from an editor's own methods: counts revisions,
+ * unwraps and migrates files, and turns load failures into
+ * `EditorDocumentLoadError`.
+ */
+export declare function defineEditorDocument<T>(spec: EditorDocumentSpec<T>): EditorDocument<T>;

package/dist/persistence/index.cjs

@@ -4,6 +4,15 @@
 
 
 
+
+
+var _chunkKC7HB5GFcjs = require('../chunk-KC7HB5GF.cjs');
+
+
+
+
+
+
 var _chunkL5OWG2NAcjs = require('../chunk-L5OWG2NA.cjs');
 require('../chunk-2BSBFBOA.cjs');
 
@@ -652,6 +661,290 @@ function createRevisionTracker(options = {}) {
   };
 }
 
+// src/persistence/editorAutosave.ts
+function createEditorAutosave(doc, options) {
+  const { dirty, key, ...rest } = options;
+  const revisions = createRevisionTracker({ history: doc, dirty });
+  const controller = createAutosaveController({
+    ...rest,
+    key: _nullishCoalesce(key, () => ( doc.kind)),
+    getSnapshot: () => _chunkKC7HB5GFcjs.toEditorDocumentFile.call(void 0, doc),
+    deserialize: (text) => _chunkKC7HB5GFcjs.parseEditorDocument.call(void 0, text, { kind: doc.kind }),
+    revision: revisions.revision,
+    savedRevision: revisions.savedRevision
+  });
+  const unsubscribe = revisions.subscribe(() => controller.notify());
+  return {
+    controller,
+    revisions,
+    checkRecovery: () => controller.checkRecovery(),
+    restore(recovery) {
+      if (!recovery.snapshot) throw _nullishCoalesce(recovery.error, () => ( new Error("The recovered snapshot could not be read.")));
+      const report = doc.loadDocument(recovery.snapshot, { history: "reset" });
+      controller.ready();
+      return report;
+    },
+    async discard() {
+      await controller.discardRecovery();
+      controller.ready();
+    },
+    async markClean() {
+      revisions.markSaved();
+      await controller.markClean();
+    },
+    destroy() {
+      unsubscribe();
+      revisions.destroy();
+      controller.destroy();
+    }
+  };
+}
+
+// src/persistence/documentStore.ts
+function slugifyDocumentName(name) {
+  const slug = name.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
+  return slug || "untitled";
+}
+function createEditorDocumentStore(options) {
+  const { storage } = options;
+  const ns = _nullishCoalesce(options.namespace, () => ( "pixerate.documents"));
+  const now = _nullishCoalesce(options.now, () => ( Date.now));
+  const indexKey = `${ns}:index`;
+  const fileKey = (key) => `${ns}:file:${key}`;
+  let index = null;
+  let queue = Promise.resolve();
+  const run = (task) => {
+    const result = queue.then(task, task);
+    queue = result.catch(() => void 0);
+    return result;
+  };
+  const loadIndex = async () => {
+    if (index) return index;
+    const raw = await storage.get(indexKey);
+    let items = [];
+    if (raw) {
+      try {
+        const data = JSON.parse(raw);
+        if (data && Array.isArray(data.items)) {
+          items = data.items.filter((item) => item && typeof item.key === "string" && typeof item.kind === "string");
+        }
+      } catch (e6) {
+        items = [];
+      }
+    }
+    index = items;
+    return index;
+  };
+  const saveIndex = async (items) => {
+    await storage.set(indexKey, JSON.stringify({ version: 1, items }));
+    index = items;
+  };
+  const newestFirst = (a, b) => a.savedAt < b.savedAt ? 1 : a.savedAt > b.savedAt ? -1 : 0;
+  const readFile = async (key) => {
+    const raw = await storage.get(fileKey(key));
+    return raw === null ? null : _chunkKC7HB5GFcjs.parseEditorDocument.call(void 0, raw);
+  };
+  return {
+    save: (doc, name) => run(async () => {
+      const trimmed = name.trim() || "Untitled";
+      const entry = {
+        key: `${doc.kind}/${slugifyDocumentName(trimmed)}`,
+        kind: doc.kind,
+        name: trimmed,
+        formatVersion: doc.formatVersion,
+        savedAt: new Date(now()).toISOString()
+      };
+      await storage.set(fileKey(entry.key), JSON.stringify(_chunkKC7HB5GFcjs.toEditorDocumentFile.call(void 0, doc, trimmed)));
+      await saveIndex([...(await loadIndex()).filter((item) => item.key !== entry.key), entry]);
+      return entry;
+    }),
+    list: (kind) => run(async () => (await loadIndex()).filter((item) => !kind || item.kind === kind).sort(newestFirst)),
+    read: (key) => run(() => readFile(key)),
+    open: (doc, key, openOptions = {}) => run(async () => {
+      const entry = (await loadIndex()).find((item) => item.key === key);
+      const file = entry ? await readFile(key) : null;
+      if (!entry || !file) {
+        const keys = (await loadIndex()).filter((item) => item.kind === doc.kind).sort(newestFirst).map((item) => item.key);
+        throw new (0, _chunkKC7HB5GFcjs.EditorDocumentLoadError)(
+          `There is no saved document "${key}". ${keys.length ? `Saved ${doc.kind} documents: ${keys.join(", ")}.` : `No ${doc.kind} documents are saved yet.`}`
+        );
+      }
+      const report = doc.loadDocument(file, { history: _nullishCoalesce(openOptions.history, () => ( "reset")) });
+      return { ...entry, report };
+    }),
+    remove: (key) => run(async () => {
+      const items = await loadIndex();
+      if (!items.some((item) => item.key === key)) return false;
+      await saveIndex(items.filter((item) => item.key !== key));
+      await storage.remove(fileKey(key));
+      return true;
+    })
+  };
+}
+
+// src/persistence/documentTools.ts
+var READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+var WRITE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+var REPLACE = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false };
+var OVERWRITE = { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false };
+var object = (properties, required = []) => ({
+  type: "object",
+  properties,
+  ...required.length ? { required } : {},
+  additionalProperties: false
+});
+var reportOut = (report) => ({
+  ...report.migratedFrom !== null ? { migratedFrom: report.migratedFrom } : {},
+  ...report.problems.length ? { problems: report.problems } : {},
+  ...report.unknownKeys.length ? { unknownKeys: report.unknownKeys } : {}
+});
+function createDocumentToolProvider(doc, options = {}) {
+  const { kind } = doc;
+  const noun = _nullishCoalesce(options.noun, () => ( kind.replace(/_/g, " ")));
+  const maxChars = _nullishCoalesce(options.maxChars, () => ( 2e5));
+  const store = options.store;
+  const writable = () => {
+    const reason = doc.readOnly();
+    if (reason) throw new Error(`${reason} Read tools still work; write tools are refused.`);
+  };
+  const historyOut = () => {
+    const h = doc.history.getState();
+    return {
+      revision: doc.revision(),
+      canUndo: h.canUndo,
+      canRedo: h.canRedo,
+      ...h.undoName ? { undoName: h.undoName } : {},
+      ...h.redoName ? { redoName: h.redoName } : {}
+    };
+  };
+  const loaded = (report) => ({
+    revision: doc.revision(),
+    undoable: doc.recordsLoads,
+    ...reportOut(report)
+  });
+  const get = {
+    name: `get_${kind}_document`,
+    title: `Get the ${noun} document`,
+    description: `Returns the whole ${noun} as plain JSON: { kind, formatVersion, revision, document }. Use it to keep a copy, compare versions or pass the document to load_${kind}_document later. For reading or editing parts of the ${noun}, prefer the editor's own read tools: this result can be large.`,
+    inputSchema: object({}),
+    annotations: { title: `Get the ${noun} document`, ...READ },
+    handler: () => {
+      const document = doc.getDocument();
+      const size = _nullishCoalesce(_optionalChain([JSON, 'access', _6 => _6.stringify, 'call', _7 => _7(document), 'optionalAccess', _8 => _8.length]), () => ( 0));
+      if (size > maxChars) {
+        throw new Error(`The ${noun} document is ${size} characters of JSON, over the ${maxChars} limit for this tool. Use the editor's read tools to look at parts of it.`);
+      }
+      return { kind, formatVersion: doc.formatVersion, revision: doc.revision(), document };
+    }
+  };
+  const load = {
+    name: `load_${kind}_document`,
+    title: `Load a ${noun} document`,
+    description: `Replaces the whole ${noun} with a document from get_${kind}_document (its "document" value, or the whole result as a saved file). The document is checked first: when it does not fit, nothing changes and the error says why. Returns { revision, undoable, migratedFrom?, problems?, unknownKeys? }; undoable: true means undo_${kind} brings the previous ${noun} back.`,
+    inputSchema: object(
+      {
+        document: {
+          type: "object",
+          description: `The ${noun} document: the "document" value from get_${kind}_document, or a saved file ({ format, kind, formatVersion, document }).`
+        }
+      },
+      ["document"]
+    ),
+    annotations: { title: `Load a ${noun} document`, ...REPLACE },
+    handler: ({ document }) => {
+      writable();
+      return loaded(doc.loadDocument(document, { history: "record" }));
+    }
+  };
+  const undo = {
+    name: `undo_${kind}`,
+    title: `Undo a ${noun} edit`,
+    description: `Undoes the last ${noun} edit (one tool call or one user gesture). Returns { undone, revision, canUndo, canRedo, undoName?, redoName? }; undone is the name of the step that was undone.`,
+    inputSchema: object({}),
+    annotations: { title: `Undo a ${noun} edit`, ...WRITE },
+    handler: () => {
+      writable();
+      const name = doc.history.getState().undoName;
+      if (!doc.history.getState().canUndo || !doc.history.undo()) throw new Error("Nothing to undo.");
+      return { undone: _nullishCoalesce(name, () => ( true)), ...historyOut() };
+    }
+  };
+  const redo = {
+    name: `redo_${kind}`,
+    title: `Redo a ${noun} edit`,
+    description: `Redoes the last undone ${noun} edit. Returns { redone, revision, canUndo, canRedo, undoName?, redoName? }; redone is the name of the step that was redone.`,
+    inputSchema: object({}),
+    annotations: { title: `Redo a ${noun} edit`, ...WRITE },
+    handler: () => {
+      writable();
+      const name = doc.history.getState().redoName;
+      if (!doc.history.getState().canRedo || !doc.history.redo()) throw new Error("Nothing to redo.");
+      return { redone: _nullishCoalesce(name, () => ( true)), ...historyOut() };
+    }
+  };
+  const storeTools = (s) => [
+    {
+      name: `save_${kind}_document`,
+      title: `Save the ${noun}`,
+      description: `Saves the current ${noun} under a name in the host's document storage. Saving the same name again replaces that saved copy. Returns { key, name, savedAt, revision }; pass key to open_saved_${kind}_document to load it again.`,
+      inputSchema: object({
+        name: {
+          type: "string",
+          minLength: 1,
+          maxLength: 200,
+          description: `Name to save under (default: the ${noun}'s current name, or "Untitled ${noun}").`
+        }
+      }),
+      annotations: { title: `Save the ${noun}`, ...OVERWRITE },
+      handler: async ({ name }) => {
+        const entry = await s.save(doc, _nullishCoalesce(_nullishCoalesce(name, () => ( _optionalChain([options, 'access', _9 => _9.name, 'optionalCall', _10 => _10()]))), () => ( `Untitled ${noun}`)));
+        return { key: entry.key, name: entry.name, savedAt: entry.savedAt, revision: doc.revision() };
+      }
+    },
+    {
+      name: `list_saved_${kind}_documents`,
+      title: `List saved ${noun} documents`,
+      description: `Lists the ${noun} documents in the host's document storage, newest first. Returns { documents: [{ key, name, savedAt, formatVersion }] }.`,
+      inputSchema: object({}),
+      annotations: { title: `List saved ${noun} documents`, ...READ },
+      handler: async () => ({
+        documents: (await s.list(kind)).map(({ key, name, savedAt, formatVersion }) => ({ key, name, savedAt, formatVersion }))
+      })
+    },
+    {
+      name: `open_saved_${kind}_document`,
+      title: `Open a saved ${noun}`,
+      description: `Replaces the current ${noun} with a saved one. Unsaved changes stay reachable through undo_${kind} when undoable is true. Returns { key, name, revision, undoable, migratedFrom?, problems?, unknownKeys? }.`,
+      inputSchema: object({ key: { type: "string", minLength: 1, description: `A key from list_saved_${kind}_documents or save_${kind}_document.` } }, ["key"]),
+      annotations: { title: `Open a saved ${noun}`, ...REPLACE },
+      handler: async ({ key }) => {
+        writable();
+        const entry = await s.open(doc, key, { history: "record" });
+        return { key: entry.key, name: entry.name, ...loaded(entry.report) };
+      }
+    }
+  ];
+  return {
+    id: _nullishCoalesce(options.id, () => ( `${kind}-document`)),
+    ...options.namespace !== void 0 ? { namespace: options.namespace } : {},
+    title: _nullishCoalesce(options.title, () => ( `${noun.charAt(0).toUpperCase()}${noun.slice(1)} document`)),
+    description: `Get, load${options.history === false ? "" : ", undo, redo"}${store ? ", save and open" : ""} the whole ${noun}.`,
+    ...options.skill ? { skill: options.skill } : {},
+    tools: [get, load, ...options.history === false ? [] : [undo, redo], ...store ? storeTools(store) : []]
+  };
+}
+
+
+
+
+
+
+
+
+
+
+
+
 
 
 
@@ -673,4 +966,4 @@ function createRevisionTracker(options = {}) {
 
 
 
-exports.InjectedStorageError = InjectedStorageError; exports.StorageUnavailableError = StorageUnavailableError; exports.createAutosaveController = createAutosaveController; exports.createIndexedDbAdapter = createIndexedDbAdapter; exports.createLoadReport = _chunkL5OWG2NAcjs.createLoadReport; exports.createLocalStorageAdapter = createLocalStorageAdapter; exports.createMemoryStorage = createMemoryStorage; exports.createOpfsAdapter = createOpfsAdapter; exports.createRecoveryPolicy = createRecoveryPolicy; exports.createRevisionTracker = createRevisionTracker; exports.exponentialBackoff = exponentialBackoff; exports.formatRecoveryMessage = formatRecoveryMessage; exports.hasLoadProblems = _chunkL5OWG2NAcjs.hasLoadProblems; exports.isIndexedDbAvailable = isIndexedDbAvailable; exports.isLocalStorageAvailable = isLocalStorageAvailable; exports.isOpfsAvailable = isOpfsAvailable; exports.loadDocument = _chunkL5OWG2NAcjs.loadDocument; exports.loadSections = _chunkL5OWG2NAcjs.loadSections; exports.migrateDocument = _chunkL5OWG2NAcjs.migrateDocument; exports.recoveryMetaKey = recoveryMetaKey; exports.withStorageFailures = withStorageFailures;
+exports.EDITOR_DOCUMENT_FORMAT = _chunkKC7HB5GFcjs.EDITOR_DOCUMENT_FORMAT; exports.EditorDocumentLoadError = _chunkKC7HB5GFcjs.EditorDocumentLoadError; exports.InjectedStorageError = InjectedStorageError; exports.StorageUnavailableError = StorageUnavailableError; exports.createAutosaveController = createAutosaveController; exports.createDocumentToolProvider = createDocumentToolProvider; exports.createEditorAutosave = createEditorAutosave; exports.createEditorDocumentStore = createEditorDocumentStore; exports.createIndexedDbAdapter = createIndexedDbAdapter; exports.createLoadReport = _chunkL5OWG2NAcjs.createLoadReport; exports.createLocalStorageAdapter = createLocalStorageAdapter; exports.createMemoryStorage = createMemoryStorage; exports.createOpfsAdapter = createOpfsAdapter; exports.createRecoveryPolicy = createRecoveryPolicy; exports.createRevisionTracker = createRevisionTracker; exports.defineEditorDocument = _chunkKC7HB5GFcjs.defineEditorDocument; exports.exponentialBackoff = exponentialBackoff; exports.formatRecoveryMessage = formatRecoveryMessage; exports.hasLoadProblems = _chunkL5OWG2NAcjs.hasLoadProblems; exports.isEditorDocumentFile = _chunkKC7HB5GFcjs.isEditorDocumentFile; exports.isIndexedDbAvailable = isIndexedDbAvailable; exports.isLocalStorageAvailable = isLocalStorageAvailable; exports.isOpfsAvailable = isOpfsAvailable; exports.loadDocument = _chunkL5OWG2NAcjs.loadDocument; exports.loadSections = _chunkL5OWG2NAcjs.loadSections; exports.migrateDocument = _chunkL5OWG2NAcjs.migrateDocument; exports.parseEditorDocument = _chunkKC7HB5GFcjs.parseEditorDocument; exports.recoveryMetaKey = recoveryMetaKey; exports.serializeEditorDocument = _chunkKC7HB5GFcjs.serializeEditorDocument; exports.slugifyDocumentName = slugifyDocumentName; exports.toEditorDocumentFile = _chunkKC7HB5GFcjs.toEditorDocumentFile; exports.withStorageFailures = withStorageFailures;

package/dist/persistence/index.d.cts

@@ -3,3 +3,7 @@ export * from "./storage.cjs";
 export * from "./autosave.cjs";
 export * from "./migrate.cjs";
 export * from "./revisions.cjs";
+export * from "./editorDocument.cjs";
+export * from "./editorAutosave.cjs";
+export * from "./documentStore.cjs";
+export * from "./documentTools.cjs";

package/dist/persistence/index.d.ts

@@ -3,3 +3,7 @@ export * from "./storage.js";
 export * from "./autosave.js";
 export * from "./migrate.js";
 export * from "./revisions.js";
+export * from "./editorDocument.js";
+export * from "./editorAutosave.js";
+export * from "./documentStore.js";
+export * from "./documentTools.js";