@pixerate/editor 0.272.0 → 0.273.0

package/dist/chunk-JV7DKLMX.js

@@ -0,0 +1,1073 @@
+import {
+  EditorDocumentLoadError,
+  collectEditorAssetGarbage,
+  collectRetiredEditorAssets,
+  parseEditorDocument,
+  preloadEditorAssets,
+  toEditorDocumentFile,
+  tryCollectEditorAssetGarbage,
+  withEditorAssets
+} from "./chunk-XBQX76CT.js";
+
+// src/persistence/recoveryPolicy.ts
+function exponentialBackoff(failures, base = 1e3, max = 3e4) {
+  const exp = Math.min(Math.max(failures - 1, 0), 16);
+  return Math.min(base * 2 ** exp, max);
+}
+function createRecoveryPolicy(options = {}) {
+  const interval = options.interval ?? 5e3;
+  const retryDelay = options.retryDelay ?? (() => interval);
+  const minWake = interval * 0.01;
+  let lastRevision = null;
+  let lastTime = null;
+  let gap = interval;
+  let ownsDirtyMeta = false;
+  let cleaning = false;
+  let snapshots = 0;
+  let snapshotsAtClean = 0;
+  let failures = 0;
+  const fail = (now) => {
+    failures++;
+    lastRevision = null;
+    lastTime = now;
+    gap = retryDelay(failures);
+  };
+  return {
+    tick(now, revision, savedRevision, tickOptions) {
+      const force = tickOptions?.force === true;
+      const since = force || lastTime === null ? Infinity : now - lastTime;
+      if (revision !== savedRevision) {
+        if (lastRevision === revision) return { type: "nothing" };
+        if (since >= gap) {
+          lastRevision = revision;
+          lastTime = now;
+          ownsDirtyMeta = true;
+          snapshots++;
+          return { type: "writeSnapshot", revision };
+        }
+        return { type: "wakeAfter", delay: Math.max(gap - since, minWake) };
+      }
+      if (ownsDirtyMeta && !cleaning) {
+        if (lastRevision !== null || since >= gap) {
+          cleaning = true;
+          snapshotsAtClean = snapshots;
+          return { type: "writeClean" };
+        }
+        return { type: "wakeAfter", delay: Math.max(gap - since, minWake) };
+      }
+      return { type: "nothing" };
+    },
+    written(revision, ok, now) {
+      if (ok) {
+        if (lastRevision === revision) {
+          failures = 0;
+          gap = interval;
+        }
+      } else if (lastRevision === revision) {
+        fail(now);
+      }
+    },
+    cleaned(ok, now) {
+      cleaning = false;
+      if (ok) {
+        ownsDirtyMeta = snapshots !== snapshotsAtClean;
+        failures = 0;
+        gap = interval;
+      } else {
+        fail(now);
+      }
+    },
+    get ownsSnapshot() {
+      return ownsDirtyMeta;
+    },
+    get failures() {
+      return failures;
+    }
+  };
+}
+
+// src/persistence/storage.ts
+var StorageUnavailableError = class extends Error {
+  constructor(kind) {
+    super(`${kind} storage is not available in this environment`);
+    this.name = "StorageUnavailableError";
+  }
+};
+var InjectedStorageError = class extends Error {
+  constructor(operation, key) {
+    super(`injected ${operation} failure for "${key}"`);
+    this.name = "InjectedStorageError";
+  }
+};
+function checkFailure(failure, operation, key) {
+  if (!failure) return;
+  const result = failure(operation, key);
+  if (result instanceof Error) throw result;
+  if (result) throw new InjectedStorageError(operation, key);
+}
+function withStorageFailures(inner, failure) {
+  return {
+    kind: inner.kind,
+    get available() {
+      return inner.available;
+    },
+    async get(key) {
+      checkFailure(failure, "get", key);
+      return inner.get(key);
+    },
+    async set(key, value) {
+      checkFailure(failure, "set", key);
+      return inner.set(key, value);
+    },
+    async remove(key) {
+      checkFailure(failure, "remove", key);
+      return inner.remove(key);
+    },
+    ...inner.keys ? {
+      async keys(prefix = "") {
+        checkFailure(failure, "keys", prefix);
+        return inner.keys(prefix);
+      }
+    } : {}
+  };
+}
+function guarded(kind, isAvailable, failure, impl) {
+  const check = (operation, key) => {
+    if (!isAvailable()) throw new StorageUnavailableError(kind);
+    checkFailure(failure, operation, key);
+  };
+  return {
+    kind,
+    get available() {
+      return isAvailable();
+    },
+    async get(key) {
+      check("get", key);
+      return impl.get(key);
+    },
+    async set(key, value) {
+      check("set", key);
+      return impl.set(key, value);
+    },
+    async remove(key) {
+      check("remove", key);
+      return impl.remove(key);
+    },
+    ...impl.keys ? {
+      async keys(prefix = "") {
+        check("keys", prefix);
+        return impl.keys(prefix);
+      }
+    } : {}
+  };
+}
+function createMemoryStorage(options = {}) {
+  const entries = new Map(Object.entries(options.initial ?? {}));
+  const adapter = guarded("memory", () => true, options.failure, {
+    async get(key) {
+      return entries.has(key) ? entries.get(key) : null;
+    },
+    async set(key, value) {
+      entries.set(key, value);
+    },
+    async remove(key) {
+      entries.delete(key);
+    },
+    async keys(prefix) {
+      return [...entries.keys()].filter((key) => key.startsWith(prefix));
+    }
+  });
+  return Object.assign(adapter, { entries });
+}
+function detectLocalStorage() {
+  try {
+    const storage = globalThis.localStorage;
+    return storage && typeof storage.getItem === "function" ? storage : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function isLocalStorageAvailable() {
+  return detectLocalStorage() !== void 0;
+}
+function createLocalStorageAdapter(prefix = "", options = {}) {
+  const storage = options.storage ?? detectLocalStorage();
+  return guarded("localStorage", () => storage !== void 0, options.failure, {
+    async get(key) {
+      return storage.getItem(prefix + key);
+    },
+    async set(key, value) {
+      storage.setItem(prefix + key, value);
+    },
+    async remove(key) {
+      storage.removeItem(prefix + key);
+    },
+    // Listing needs `length` and `key()` (real Web Storage has both).
+    ...!storage || typeof storage.key === "function" && typeof storage.length === "number" ? {
+      async keys(start) {
+        const out = [];
+        for (let i = 0; i < storage.length; i++) {
+          const key = storage.key(i);
+          if (key !== null && key.startsWith(prefix + start)) out.push(key.slice(prefix.length));
+        }
+        return out;
+      }
+    } : {}
+  });
+}
+function detectIndexedDb() {
+  try {
+    const factory = globalThis.indexedDB;
+    return factory && typeof factory.open === "function" ? factory : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function isIndexedDbAvailable() {
+  return detectIndexedDb() !== void 0;
+}
+var requestToPromise = (request) => new Promise((resolve, reject) => {
+  request.onsuccess = () => resolve(request.result);
+  request.onerror = () => reject(request.error ?? new Error("IndexedDB request failed"));
+});
+function createIndexedDbAdapter(name = "pixerate-editor", options = {}) {
+  const factory = options.indexedDB ?? detectIndexedDb();
+  const storeName = options.store ?? "kv";
+  let dbPromise = null;
+  const open = () => {
+    dbPromise ??= new Promise((resolve, reject) => {
+      const request = factory.open(name, 1);
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(storeName)) db.createObjectStore(storeName);
+      };
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => {
+        dbPromise = null;
+        reject(request.error ?? new Error("IndexedDB open failed"));
+      };
+    });
+    return dbPromise;
+  };
+  const write = async (fn) => {
+    const db = await open();
+    await new Promise((resolve, reject) => {
+      const tx = db.transaction(storeName, "readwrite");
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error ?? new Error("IndexedDB transaction failed"));
+      tx.onabort = () => reject(tx.error ?? new Error("IndexedDB transaction aborted"));
+      fn(tx.objectStore(storeName));
+    });
+  };
+  return guarded("indexedDB", () => factory !== void 0, options.failure, {
+    async get(key) {
+      const db = await open();
+      const tx = db.transaction(storeName, "readonly");
+      const value = await requestToPromise(tx.objectStore(storeName).get(key));
+      return typeof value === "string" ? value : null;
+    },
+    set: (key, value) => write((store) => store.put(value, key)),
+    remove: (key) => write((store) => store.delete(key)),
+    async keys(prefix) {
+      const db = await open();
+      const tx = db.transaction(storeName, "readonly");
+      const all = await requestToPromise(tx.objectStore(storeName).getAllKeys());
+      return all.filter((key) => typeof key === "string" && key.startsWith(prefix));
+    }
+  });
+}
+function detectOpfsRoot() {
+  try {
+    const storage = globalThis.navigator?.storage;
+    if (storage && typeof storage.getDirectory === "function") {
+      return () => storage.getDirectory();
+    }
+  } catch {
+  }
+  return void 0;
+}
+function isOpfsAvailable() {
+  return detectOpfsRoot() !== void 0;
+}
+var isNotFound = (error) => !!error && typeof error === "object" && error.name === "NotFoundError";
+function createOpfsAdapter(dir = "pixerate-editor", options = {}) {
+  const getRoot = options.root ?? detectOpfsRoot();
+  let dirPromise = null;
+  const directory = () => {
+    dirPromise ??= getRoot().then((root) => root.getDirectoryHandle(dir, { create: true }));
+    dirPromise.catch(() => {
+      dirPromise = null;
+    });
+    return dirPromise;
+  };
+  const fileName = (key) => encodeURIComponent(key) || "_";
+  const readFile = async (d, name) => {
+    try {
+      const handle = await d.getFileHandle(name);
+      return await (await handle.getFile()).text();
+    } catch (error) {
+      if (isNotFound(error)) return null;
+      throw error;
+    }
+  };
+  const writeFile = async (d, name, value) => {
+    const handle = await d.getFileHandle(name, { create: true });
+    if (typeof handle.createWritable !== "function") {
+      throw new StorageUnavailableError("opfs (createWritable)");
+    }
+    const writable = await handle.createWritable();
+    await writable.write(value);
+    await writable.close();
+    return handle;
+  };
+  const removeFile = async (d, name) => {
+    try {
+      await d.removeEntry(name);
+    } catch (error) {
+      if (!isNotFound(error)) throw error;
+    }
+  };
+  return guarded("opfs", () => getRoot !== void 0, options.failure, {
+    async get(key) {
+      const d = await directory();
+      const base = fileName(key);
+      const pointer = await readFile(d, `${base}.ptr`);
+      if (pointer === "a" || pointer === "b") return readFile(d, `${base}.${pointer}`);
+      return readFile(d, base);
+    },
+    async set(key, value) {
+      const d = await directory();
+      const base = fileName(key);
+      const pointer = await readFile(d, `${base}.ptr`);
+      if (!options.disableRename && pointer === null) {
+        const tmp = await writeFile(d, `${base}.tmp`, value);
+        if (typeof tmp.move === "function") {
+          await tmp.move(base);
+          return;
+        }
+        await removeFile(d, `${base}.tmp`);
+      }
+      const next = pointer === "a" ? "b" : "a";
+      await writeFile(d, `${base}.${next}`, value);
+      await writeFile(d, `${base}.ptr`, next);
+    },
+    async remove(key) {
+      const d = await directory();
+      const base = fileName(key);
+      for (const name of [`${base}.ptr`, base, `${base}.a`, `${base}.b`, `${base}.tmp`]) {
+        await removeFile(d, name);
+      }
+    },
+    async keys(prefix) {
+      const d = await directory();
+      if (typeof d.keys !== "function") throw new StorageUnavailableError("opfs (directory listing)");
+      const names = /* @__PURE__ */ new Set();
+      for await (const name of d.keys()) names.add(name);
+      const keys = /* @__PURE__ */ new Set();
+      for (const name of names) {
+        if (name.endsWith(".tmp")) continue;
+        if (name.endsWith(".ptr")) keys.add(name.slice(0, -4));
+        else if (/\.[ab]$/.test(name) && names.has(`${name.slice(0, -2)}.ptr`)) continue;
+        else keys.add(name);
+      }
+      const out = [];
+      for (const name of keys) {
+        let key;
+        try {
+          key = decodeURIComponent(name);
+        } catch {
+          continue;
+        }
+        if (key.startsWith(prefix)) out.push(key);
+      }
+      return out;
+    }
+  });
+}
+
+// src/persistence/autosave.ts
+var recoveryMetaKey = (key) => `${key}:meta`;
+function formatRecoveryMessage(meta, formatTime = (time) => new Date(time).toLocaleString()) {
+  return typeof meta.time === "number" && Number.isFinite(meta.time) ? `Restore unsaved changes from ${formatTime(meta.time)}?` : "Restore unsaved changes?";
+}
+function createAutosaveController(options) {
+  const {
+    storage,
+    key,
+    getSnapshot,
+    revision,
+    savedRevision,
+    interval = 5e3,
+    debounceMs = 1e3,
+    retryBaseMs = 1e3,
+    retryMaxMs = 3e4
+  } = options;
+  const serialize = options.serialize ?? ((value) => JSON.stringify(value));
+  const deserialize = options.deserialize ?? ((text) => JSON.parse(text));
+  const now = options.now ?? (() => Date.now());
+  const wallClock = options.wallClock ?? (() => Date.now());
+  const setTimer = options.setTimeout ?? ((fn, ms) => globalThis.setTimeout(fn, ms));
+  const clearTimer = options.clearTimeout ?? ((handle) => globalThis.clearTimeout(handle));
+  const metaKey = recoveryMetaKey(key);
+  const policy = createRecoveryPolicy({
+    interval,
+    retryDelay: (failures) => exponentialBackoff(failures, retryBaseMs, retryMaxMs)
+  });
+  let hydrated = options.ready === true;
+  let destroyed = false;
+  let timer = null;
+  let timerDue = Infinity;
+  let inflight = null;
+  let observedRevision = revision();
+  let lastChangeAt = null;
+  let pendingSince = null;
+  let forceNext = false;
+  let info = {
+    status: "idle",
+    error: null,
+    failures: 0,
+    nextAttemptAt: null,
+    lastSavedAt: null,
+    ready: hydrated
+  };
+  const listeners = /* @__PURE__ */ new Set();
+  const setInfo = (patch) => {
+    const next = { ...info, ...patch, failures: policy.failures, ready: hydrated };
+    if (next.status === info.status && next.error === info.error && next.failures === info.failures && next.nextAttemptAt === info.nextAttemptAt && next.lastSavedAt === info.lastSavedAt && next.ready === info.ready) {
+      return;
+    }
+    info = next;
+    options.onStatus?.(info);
+    listeners.forEach((listener) => {
+      try {
+        listener(info);
+      } catch (error) {
+        console.error("[autosave] Error in status listener:", error);
+      }
+    });
+  };
+  const cancelTimer = () => {
+    if (timer !== null) clearTimer(timer);
+    timer = null;
+    timerDue = Infinity;
+  };
+  const schedule = (delay) => {
+    if (destroyed) return;
+    const due = now() + Math.max(0, delay);
+    if (timer !== null && timerDue <= due) return;
+    cancelTimer();
+    timerDue = due;
+    timer = setTimer(() => {
+      timer = null;
+      timerDue = Infinity;
+      tick();
+    }, Math.max(0, delay));
+  };
+  const observe = (t) => {
+    const rev = revision();
+    if (rev !== observedRevision) {
+      observedRevision = rev;
+      lastChangeAt = t;
+      pendingSince ??= t;
+    }
+    return rev;
+  };
+  const docName = () => typeof options.name === "function" ? options.name() : options.name;
+  const run = (action, rev) => {
+    if (action.type === "writeSnapshot") {
+      setInfo({ status: "saving", nextAttemptAt: null });
+      inflight = (async () => {
+        let ok = false;
+        let error = null;
+        try {
+          const text = serialize(getSnapshot());
+          await storage.set(key, text);
+          const meta = {
+            dirty: true,
+            revision: action.revision,
+            time: wallClock(),
+            name: docName()
+          };
+          await storage.set(metaKey, JSON.stringify(meta));
+          ok = true;
+        } catch (e) {
+          error = e;
+        }
+        const t = now();
+        policy.written(action.revision, ok, t);
+        inflight = null;
+        if (ok) {
+          if (observedRevision === action.revision) pendingSince = null;
+          setInfo({ status: "saved", error: null, lastSavedAt: t });
+        } else {
+          setInfo({ status: "error", error });
+        }
+        tick();
+      })();
+    } else if (action.type === "writeClean") {
+      setInfo({ status: "saving", nextAttemptAt: null });
+      inflight = (async () => {
+        let ok = false;
+        let error = null;
+        try {
+          await storage.set(metaKey, JSON.stringify({ dirty: false }));
+          ok = true;
+        } catch (e) {
+          error = e;
+        }
+        policy.cleaned(ok, now());
+        inflight = null;
+        if (ok) {
+          if (!policy.ownsSnapshot) await storage.remove(key).catch(() => void 0);
+          setInfo({ status: "saved", error: null });
+        } else {
+          setInfo({ status: "error", error });
+        }
+        tick();
+      })();
+    } else if (action.type === "wakeAfter") {
+      schedule(action.delay);
+      setInfo(
+        info.status === "error" ? { nextAttemptAt: now() + action.delay } : { status: rev !== savedRevision() ? "dirty" : info.status, nextAttemptAt: now() + action.delay }
+      );
+    } else if (rev === savedRevision() && info.status === "dirty") {
+      setInfo({ status: policy.ownsSnapshot ? "dirty" : "idle", nextAttemptAt: null });
+    } else if (rev !== savedRevision() && info.status !== "saved" && info.status !== "error") {
+      setInfo({ status: "dirty" });
+    }
+  };
+  function tick() {
+    if (destroyed || inflight) return;
+    const t = now();
+    const rev = observe(t);
+    const saved = savedRevision();
+    if (!hydrated) {
+      if (rev !== saved) setInfo({ status: "dirty" });
+      return;
+    }
+    const force = forceNext;
+    forceNext = false;
+    if (rev !== saved && !force && info.status !== "error") {
+      const changed = lastChangeAt ?? t;
+      const due = Math.min(changed + debounceMs, (pendingSince ?? changed) + interval);
+      if (t < due) {
+        setInfo({ status: "dirty", nextAttemptAt: due });
+        schedule(due - t);
+        return;
+      }
+    }
+    run(policy.tick(t, rev, saved, { force }), rev);
+  }
+  const whenIdle = async () => {
+    while (inflight) await inflight;
+  };
+  return {
+    getStatus: () => info,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    notify() {
+      if (destroyed) return;
+      const t = now();
+      const before = observedRevision;
+      const rev = observe(t);
+      const dirty = rev !== savedRevision();
+      if (dirty && rev !== before && info.status !== "error" && !inflight) {
+        setInfo({ status: "dirty" });
+      }
+      if (!hydrated) return;
+      const changed = lastChangeAt ?? t;
+      const due = Math.min(changed + debounceMs, (pendingSince ?? changed) + interval);
+      schedule(dirty ? due - t : 0);
+    },
+    ready() {
+      if (hydrated || destroyed) return;
+      hydrated = true;
+      setInfo({});
+      schedule(0);
+    },
+    get isReady() {
+      return hydrated;
+    },
+    async flushNow() {
+      if (destroyed || !hydrated) return;
+      await whenIdle();
+      cancelTimer();
+      forceNext = true;
+      tick();
+      await whenIdle();
+    },
+    async markClean() {
+      if (destroyed) return;
+      await whenIdle();
+      cancelTimer();
+      tick();
+      await whenIdle();
+    },
+    async checkRecovery() {
+      if (policy.ownsSnapshot) return null;
+      let meta;
+      try {
+        const metaText = await storage.get(metaKey);
+        if (!metaText) return null;
+        meta = JSON.parse(metaText);
+      } catch {
+        return null;
+      }
+      if (!meta || meta.dirty !== true) return null;
+      const text = await storage.get(key).catch(() => null);
+      if (text === null) return null;
+      try {
+        return { snapshot: deserialize(text), text, meta };
+      } catch (error) {
+        return { snapshot: void 0, text, meta, error };
+      }
+    },
+    async discardRecovery() {
+      if (policy.ownsSnapshot) return false;
+      await whenIdle();
+      await storage.remove(metaKey);
+      await storage.remove(key);
+      return true;
+    },
+    tick,
+    whenIdle,
+    destroy() {
+      destroyed = true;
+      cancelTimer();
+      listeners.clear();
+    }
+  };
+}
+
+// src/persistence/revisions.ts
+function createRevisionTracker(options = {}) {
+  let revision = 0;
+  let saved = 0;
+  const listeners = /* @__PURE__ */ new Set();
+  const emit = () => listeners.forEach((listener) => {
+    try {
+      listener();
+    } catch (error) {
+      console.error("[autosave] Error in revision listener:", error);
+    }
+  });
+  const syncSaved = () => {
+    if (options.dirty && !options.dirty.dirty) saved = revision;
+  };
+  const unsubscribers = [];
+  if (options.history) {
+    unsubscribers.push(
+      options.history.subscribe(() => {
+        revision++;
+        emit();
+      })
+    );
+  }
+  if (options.dirty) {
+    let first = true;
+    unsubscribers.push(
+      options.dirty.subscribe((dirty) => {
+        if (first) {
+          first = false;
+          if (dirty && revision === saved) revision++;
+          return;
+        }
+        if (dirty && revision === saved) revision++;
+        if (!dirty) saved = revision;
+        emit();
+      })
+    );
+  }
+  return {
+    revision: () => revision,
+    savedRevision: () => {
+      syncSaved();
+      return saved;
+    },
+    bump() {
+      revision++;
+      emit();
+    },
+    markSaved() {
+      saved = revision;
+      emit();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    destroy() {
+      unsubscribers.forEach((fn) => fn());
+      unsubscribers.length = 0;
+      listeners.clear();
+    }
+  };
+}
+
+// src/persistence/editorAutosave.ts
+function createEditorAutosave(doc, options) {
+  const { dirty, key, collectAssetGarbage, ...rest } = options;
+  const collect = () => collectRetiredEditorAssets(rest.storage, doc, collectAssetGarbage);
+  const revisions = createRevisionTracker({ history: doc, dirty });
+  const controller = createAutosaveController({
+    ...rest,
+    // Image and paint documents hold asset references: their bytes are saved and read with them.
+    storage: doc.assets ? withEditorAssets(rest.storage, doc.assets) : rest.storage,
+    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();
+      await collect();
+    },
+    async markClean() {
+      revisions.markSaved();
+      await controller.markClean();
+      await collect();
+    },
+    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}`;
+  const gc = options.collectAssetGarbage ?? true;
+  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()
+      };
+      const text = JSON.stringify(toEditorDocumentFile(doc, trimmed));
+      await (doc.assets ? withEditorAssets(storage, doc.assets) : storage).set(fileKey(entry.key), text);
+      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.`}`
+        );
+      }
+      if (doc.assets) {
+        const missing = await preloadEditorAssets(storage, doc.assets, file);
+        if (missing.length) throw new EditorDocumentLoadError(`The saved document "${key}" refers to ${missing.length} asset${missing.length === 1 ? "" : "s"} that storage no longer has, so it cannot be opened.`);
+      }
+      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));
+      if (gc) await tryCollectEditorAssetGarbage(storage, gc === true ? {} : gc);
+      return true;
+    }),
+    ...storage.keys ? { collectAssetGarbage: (gcOptions) => run(() => collectEditorAssetGarbage(storage, gcOptions)) } : {}
+  };
+}
+
+// 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) };
+      }
+    }
+  ];
+  const LIST_LIMIT = 100;
+  const assetTools = (s) => [
+    {
+      name: `find_unreferenced_${kind}_assets`,
+      title: `Find unreferenced ${noun} assets`,
+      description: `Finds the stored image data (layer pixels, masks and other assets of every image and paint document in the host's storage) that no saved document or autosave snapshot refers to any more, without deleting anything. The open ${noun}'s own assets always count as used. Returns { assets, referenced, kept, unreferenced, unreferencedChars, refs, more }: unreferenced is how many could be deleted, unreferencedChars the characters of data they hold, refs up to ${LIST_LIMIT} of their references for delete_unreferenced_${kind}_assets, and more how many were left out of refs.`,
+      inputSchema: object({}),
+      annotations: { title: `Find unreferenced ${noun} assets`, ...READ },
+      handler: async () => {
+        const report = await s.collectAssetGarbage({ dryRun: true, keep: [doc.getDocument()] });
+        return {
+          assets: report.assets,
+          referenced: report.referenced,
+          kept: report.kept,
+          unreferenced: report.unreferenced.length,
+          unreferencedChars: report.unreferencedChars,
+          refs: report.unreferenced.slice(0, LIST_LIMIT),
+          more: Math.max(0, report.unreferenced.length - LIST_LIMIT)
+        };
+      }
+    },
+    {
+      name: `delete_unreferenced_${kind}_assets`,
+      title: `Delete unreferenced ${noun} assets`,
+      description: `Deletes stored image data that no saved document or autosave snapshot refers to, to free browser storage. Saved documents and the open ${noun} are never affected, and a write in progress is waited for. Call find_unreferenced_${kind}_assets first to see what would go, and do it when the user asks to free space or clean up storage. It cannot be undone, but nothing refers to the deleted data. Returns { removed, freedChars, kept, remaining }: how many assets were deleted, the characters of data freed, how many unreferenced ones were kept because a write was using them, and how many assets are left.`,
+      inputSchema: object({
+        refs: {
+          type: "array",
+          items: { type: "string", pattern: "^pixerate-asset:" },
+          minItems: 1,
+          uniqueItems: true,
+          description: `Delete only these references from find_unreferenced_${kind}_assets (refs). Default: every unreferenced asset. If any is no longer unreferenced, nothing is deleted and the error names it.`
+        }
+      }),
+      annotations: { title: `Delete unreferenced ${noun} assets`, ...OVERWRITE },
+      handler: async ({ refs }) => {
+        writable();
+        const report = await s.collectAssetGarbage({ keep: [doc.getDocument()], ...refs ? { only: refs } : {} });
+        return {
+          removed: report.removed.length,
+          freedChars: report.freedChars,
+          kept: report.kept,
+          remaining: report.assets - report.removed.length
+        };
+      }
+    }
+  ];
+  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) : [],
+      ...store?.collectAssetGarbage && doc.assets ? assetTools(store) : []
+    ]
+  };
+}
+
+export {
+  exponentialBackoff,
+  createRecoveryPolicy,
+  StorageUnavailableError,
+  InjectedStorageError,
+  withStorageFailures,
+  createMemoryStorage,
+  isLocalStorageAvailable,
+  createLocalStorageAdapter,
+  isIndexedDbAvailable,
+  createIndexedDbAdapter,
+  isOpfsAvailable,
+  createOpfsAdapter,
+  recoveryMetaKey,
+  formatRecoveryMessage,
+  createAutosaveController,
+  createRevisionTracker,
+  createEditorAutosave,
+  slugifyDocumentName,
+  createEditorDocumentStore,
+  createDocumentToolProvider
+};