@pixerate/editor 0.145.0 → 0.146.0

package/dist/persistence/index.js

@@ -1,3 +1,12 @@
+import {
+  EDITOR_DOCUMENT_FORMAT,
+  EditorDocumentLoadError,
+  defineEditorDocument,
+  isEditorDocumentFile,
+  parseEditorDocument,
+  serializeEditorDocument,
+  toEditorDocumentFile
+} from "../chunk-HRLT5BYO.js";
 import {
   createLoadReport,
   hasLoadProblems,
@@ -651,10 +660,288 @@ 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: key ?? doc.kind,
+    getSnapshot: () => toEditorDocumentFile(doc),
+    deserialize: (text) => parseEditorDocument(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 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 = options.namespace ?? "pixerate.documents";
+  const now = 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 {
+        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 : parseEditorDocument(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(toEditorDocumentFile(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 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: 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 = options.noun ?? kind.replace(/_/g, " ");
+  const maxChars = 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 = JSON.stringify(document)?.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: 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: 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, name ?? options.name?.() ?? `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: options.id ?? `${kind}-document`,
+    ...options.namespace !== void 0 ? { namespace: options.namespace } : {},
+    title: 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) : []]
+  };
+}
 export {
+  EDITOR_DOCUMENT_FORMAT,
+  EditorDocumentLoadError,
   InjectedStorageError,
   StorageUnavailableError,
   createAutosaveController,
+  createDocumentToolProvider,
+  createEditorAutosave,
+  createEditorDocumentStore,
   createIndexedDbAdapter,
   createLoadReport,
   createLocalStorageAdapter,
@@ -662,15 +949,21 @@ export {
   createOpfsAdapter,
   createRecoveryPolicy,
   createRevisionTracker,
+  defineEditorDocument,
   exponentialBackoff,
   formatRecoveryMessage,
   hasLoadProblems,
+  isEditorDocumentFile,
   isIndexedDbAvailable,
   isLocalStorageAvailable,
   isOpfsAvailable,
   loadDocument,
   loadSections,
   migrateDocument,
+  parseEditorDocument,
   recoveryMetaKey,
+  serializeEditorDocument,
+  slugifyDocumentName,
+  toEditorDocumentFile,
   withStorageFailures
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.145.0",
+  "version": "0.146.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",

package/skills/pixerate-agent-tools/SKILL.md

@@ -61,6 +61,27 @@ editor's, or (in discovery mode) only `list_toolsets`, `search_tools`, `enable_t
 6. **Undo your own mistakes** with the domain's `undo_*` tool or the `history.undo` command, not
    by hand-reverting with more edits.
 
+## Saving, loading and undo
+
+Every editor can share the same document tools, named after its kind (`diagram`, `chart`,
+`spreadsheet`...). The editor's skill lists the ones it has.
+
+- `get_<kind>_document` returns the whole document as plain JSON
+  (`{ kind, formatVersion, revision, document }`). Use it to keep a copy before a risky change
+  or to hand the document on, not to read it: the editor's own read tools are smaller and more
+  precise. It refuses very large documents and says so.
+- `load_<kind>_document` puts such a copy back. The document is checked first and nothing
+  changes when it does not fit. It is one undo step when the result says `undoable: true`.
+- `undo_<kind>` / `redo_<kind>` step through the editor's history. They fail with
+  "Nothing to undo." / "Nothing to redo." when there is nothing to step over.
+- With host storage: `save_<kind>_document` (by `name`; the same name replaces that copy),
+  `list_saved_<kind>_documents`, then `open_saved_<kind>_document` with a `key` from either.
+  Save when the user asks. Opening replaces the current document, so ask first when it has
+  changes the user has not saved.
+
+A read-only document keeps its read tools; its write tools fail with the reason. `revision`
+goes up on every change, so comparing two results tells you whether the document changed.
+
 ## Playback
 
 The host may act your calls out on screen (agent playback): your cursor glides to what a call

package/skills/pixerate-diagram/SKILL.md

@@ -111,6 +111,19 @@ text-only families.
 | `undo_diagram` | Undo the last diagram edit; returns its label. |
 | `redo_diagram` | Redo the last undone diagram edit. |
 
+### Save and open
+
+The host may add the shared document tools (see `pixerate-agent-tools`). A diagram document is
+`{ source }`: the Mermaid text with its `%% @pixerate` layout comment.
+
+| Tool | Use |
+| --- | --- |
+| `get_diagram_document` | Take a copy of the whole diagram as `{ kind, formatVersion, revision, document }` before a risky rewrite, or to hand it to another session. To read the diagram, use `get_diagram`. |
+| `load_diagram_document` | Put back a copy from `get_diagram_document` (its `document`, or the whole result). Checked first; one undo step (`undo_diagram` brings the previous diagram back). For new Mermaid text use `load_diagram_mermaid`. |
+| `save_diagram_document` | Save the diagram under a `name` in the host's storage (same name replaces that copy). Returns the `key`. Only listed when the host has storage. Save when the user asks, not after every edit. |
+| `list_saved_diagram_documents` | List saved diagrams (`key`, `name`, `savedAt`), newest first. |
+| `open_saved_diagram_document` | Replace the diagram with a saved one by `key` from the list. One undo step. Ask before opening over unsaved work the user has not saved. |
+
 ## Pitfalls
 
 - Ids are Mermaid ids, not labels. Always take them from `get_diagram` or from what a write