@pixerate/editor 0.164.0 → 0.165.0

package/dist/persistence/index.cjs

@@ -20,7 +20,10 @@
 
 
 
-var _chunkM4MIZPQIcjs = require('../chunk-M4MIZPQI.cjs');
+
+
+
+var _chunkSJ2CPTQCcjs = require('../chunk-SJ2CPTQC.cjs');
 require('../chunk-2BSBFBOA.cjs');
 
 // src/persistence/recoveryPolicy.ts
@@ -136,7 +139,13 @@ function withStorageFailures(inner, failure) {
     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) {
@@ -160,7 +169,13 @@ function guarded(kind, isAvailable, failure, impl) {
     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 = {}) {
@@ -174,6 +189,9 @@ function createMemoryStorage(options = {}) {
     },
     async remove(key) {
       entries.delete(key);
+    },
+    async keys(prefix) {
+      return [...entries.keys()].filter((key) => key.startsWith(prefix));
     }
   });
   return Object.assign(adapter, { entries });
@@ -200,7 +218,18 @@ function createLocalStorageAdapter(prefix = "", options = {}) {
     },
     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() {
@@ -255,7 +284,13 @@ function createIndexedDbAdapter(name = "pixerate-editor", options = {}) {
       return typeof value === "string" ? value : null;
     },
     set: (key, value) => write((store) => store.put(value, key)),
-    remove: (key) => write((store) => store.delete(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() {
@@ -339,6 +374,30 @@ function createOpfsAdapter(dir = "pixerate-editor", options = {}) {
       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 (e5) {
+          continue;
+        }
+        if (key.startsWith(prefix)) out.push(key);
+      }
+      return out;
     }
   });
 }
@@ -572,7 +631,7 @@ function createAutosaveController(options) {
         const metaText = await storage.get(metaKey);
         if (!metaText) return null;
         meta = JSON.parse(metaText);
-      } catch (e5) {
+      } catch (e6) {
         return null;
       }
       if (!meta || meta.dirty !== true) return null;
@@ -670,15 +729,16 @@ function createRevisionTracker(options = {}) {
 
 // src/persistence/editorAutosave.ts
 function createEditorAutosave(doc, options) {
-  const { dirty, key, ...rest } = options;
+  const { dirty, key, collectAssetGarbage, ...rest } = options;
+  const collect = () => _chunkSJ2CPTQCcjs.collectRetiredEditorAssets.call(void 0, 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 ? _chunkM4MIZPQIcjs.withEditorAssets.call(void 0, rest.storage, doc.assets) : rest.storage,
+    storage: doc.assets ? _chunkSJ2CPTQCcjs.withEditorAssets.call(void 0, rest.storage, doc.assets) : rest.storage,
     key: _nullishCoalesce(key, () => ( doc.kind)),
-    getSnapshot: () => _chunkM4MIZPQIcjs.toEditorDocumentFile.call(void 0, doc),
-    deserialize: (text) => _chunkM4MIZPQIcjs.parseEditorDocument.call(void 0, text, { kind: doc.kind }),
+    getSnapshot: () => _chunkSJ2CPTQCcjs.toEditorDocumentFile.call(void 0, doc),
+    deserialize: (text) => _chunkSJ2CPTQCcjs.parseEditorDocument.call(void 0, text, { kind: doc.kind }),
     revision: revisions.revision,
     savedRevision: revisions.savedRevision
   });
@@ -696,10 +756,12 @@ function createEditorAutosave(doc, options) {
     async discard() {
       await controller.discardRecovery();
       controller.ready();
+      await collect();
     },
     async markClean() {
       revisions.markSaved();
       await controller.markClean();
+      await collect();
     },
     destroy() {
       unsubscribe();
@@ -720,6 +782,7 @@ function createEditorDocumentStore(options) {
   const now = _nullishCoalesce(options.now, () => ( Date.now));
   const indexKey = `${ns}:index`;
   const fileKey = (key) => `${ns}:file:${key}`;
+  const gc = _nullishCoalesce(options.collectAssetGarbage, () => ( true));
   let index = null;
   let queue = Promise.resolve();
   const run = (task) => {
@@ -737,7 +800,7 @@ function createEditorDocumentStore(options) {
         if (data && Array.isArray(data.items)) {
           items = data.items.filter((item) => item && typeof item.key === "string" && typeof item.kind === "string");
         }
-      } catch (e6) {
+      } catch (e7) {
         items = [];
       }
     }
@@ -751,7 +814,7 @@ function createEditorDocumentStore(options) {
   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 : _chunkM4MIZPQIcjs.parseEditorDocument.call(void 0, raw);
+    return raw === null ? null : _chunkSJ2CPTQCcjs.parseEditorDocument.call(void 0, raw);
   };
   return {
     save: (doc, name) => run(async () => {
@@ -763,9 +826,8 @@ function createEditorDocumentStore(options) {
         formatVersion: doc.formatVersion,
         savedAt: new Date(now()).toISOString()
       };
-      const text = JSON.stringify(_chunkM4MIZPQIcjs.toEditorDocumentFile.call(void 0, doc, trimmed));
-      if (doc.assets) await _chunkM4MIZPQIcjs.persistEditorAssets.call(void 0, storage, doc.assets, text);
-      await storage.set(fileKey(entry.key), text);
+      const text = JSON.stringify(_chunkSJ2CPTQCcjs.toEditorDocumentFile.call(void 0, doc, trimmed));
+      await (doc.assets ? _chunkSJ2CPTQCcjs.withEditorAssets.call(void 0, storage, doc.assets) : storage).set(fileKey(entry.key), text);
       await saveIndex([...(await loadIndex()).filter((item) => item.key !== entry.key), entry]);
       return entry;
     }),
@@ -776,13 +838,13 @@ function createEditorDocumentStore(options) {
       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, _chunkM4MIZPQIcjs.EditorDocumentLoadError)(
+        throw new (0, _chunkSJ2CPTQCcjs.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 _chunkM4MIZPQIcjs.preloadEditorAssets.call(void 0, storage, doc.assets, file);
-        if (missing.length) throw new (0, _chunkM4MIZPQIcjs.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 missing = await _chunkSJ2CPTQCcjs.preloadEditorAssets.call(void 0, storage, doc.assets, file);
+        if (missing.length) throw new (0, _chunkSJ2CPTQCcjs.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: _nullishCoalesce(openOptions.history, () => ( "reset")) });
       return { ...entry, report };
@@ -792,8 +854,10 @@ function createEditorDocumentStore(options) {
       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 _chunkSJ2CPTQCcjs.tryCollectEditorAssetGarbage.call(void 0, storage, gc === true ? {} : gc);
       return true;
-    })
+    }),
+    ...storage.keys ? { collectAssetGarbage: (gcOptions) => run(() => _chunkSJ2CPTQCcjs.collectEditorAssetGarbage.call(void 0, storage, gcOptions)) } : {}
   };
 }
 
@@ -939,13 +1003,66 @@ function createDocumentToolProvider(doc, options = {}) {
       }
     }
   ];
+  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: _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) : []]
+    tools: [
+      get,
+      load,
+      ...options.history === false ? [] : [undo, redo],
+      ...store ? storeTools(store) : [],
+      ..._optionalChain([store, 'optionalAccess', _11 => _11.collectAssetGarbage]) && doc.assets ? assetTools(store) : []
+    ]
   };
 }
 
@@ -990,4 +1107,7 @@ function createDocumentToolProvider(doc, options = {}) {
 
 
 
-exports.EDITOR_ASSET_PREFIX = _chunkM4MIZPQIcjs.EDITOR_ASSET_PREFIX; exports.EDITOR_DOCUMENT_FORMAT = _chunkM4MIZPQIcjs.EDITOR_DOCUMENT_FORMAT; exports.EditorDocumentLoadError = _chunkM4MIZPQIcjs.EditorDocumentLoadError; exports.InjectedStorageError = InjectedStorageError; exports.StorageUnavailableError = StorageUnavailableError; exports.collectAssetRefs = _chunkM4MIZPQIcjs.collectAssetRefs; exports.createAutosaveController = createAutosaveController; exports.createDocumentToolProvider = createDocumentToolProvider; exports.createEditorAssetRegistry = _chunkM4MIZPQIcjs.createEditorAssetRegistry; exports.createEditorAutosave = createEditorAutosave; exports.createEditorDocumentStore = createEditorDocumentStore; exports.createIndexedDbAdapter = createIndexedDbAdapter; exports.createLoadReport = _chunkM4MIZPQIcjs.createLoadReport; exports.createLocalStorageAdapter = createLocalStorageAdapter; exports.createMemoryStorage = createMemoryStorage; exports.createOpfsAdapter = createOpfsAdapter; exports.createRecoveryPolicy = createRecoveryPolicy; exports.createRevisionTracker = createRevisionTracker; exports.defineEditorDocument = _chunkM4MIZPQIcjs.defineEditorDocument; exports.exponentialBackoff = exponentialBackoff; exports.externalizeAssets = _chunkM4MIZPQIcjs.externalizeAssets; exports.formatRecoveryMessage = formatRecoveryMessage; exports.hasLoadProblems = _chunkM4MIZPQIcjs.hasLoadProblems; exports.internalizeAssets = _chunkM4MIZPQIcjs.internalizeAssets; exports.isEditorDocumentFile = _chunkM4MIZPQIcjs.isEditorDocumentFile; exports.isIndexedDbAvailable = isIndexedDbAvailable; exports.isInlineAsset = _chunkM4MIZPQIcjs.isInlineAsset; exports.isLocalStorageAvailable = isLocalStorageAvailable; exports.isOpfsAvailable = isOpfsAvailable; exports.loadDocument = _chunkM4MIZPQIcjs.loadDocument; exports.loadSections = _chunkM4MIZPQIcjs.loadSections; exports.migrateDocument = _chunkM4MIZPQIcjs.migrateDocument; exports.parseEditorDocument = _chunkM4MIZPQIcjs.parseEditorDocument; exports.persistEditorAssets = _chunkM4MIZPQIcjs.persistEditorAssets; exports.preloadEditorAssets = _chunkM4MIZPQIcjs.preloadEditorAssets; exports.recoveryMetaKey = recoveryMetaKey; exports.serializeEditorDocument = _chunkM4MIZPQIcjs.serializeEditorDocument; exports.slugifyDocumentName = slugifyDocumentName; exports.toEditorDocumentFile = _chunkM4MIZPQIcjs.toEditorDocumentFile; exports.withEditorAssets = _chunkM4MIZPQIcjs.withEditorAssets; exports.withStorageFailures = withStorageFailures;
+
+
+
+exports.EDITOR_ASSET_PREFIX = _chunkSJ2CPTQCcjs.EDITOR_ASSET_PREFIX; exports.EDITOR_DOCUMENT_FORMAT = _chunkSJ2CPTQCcjs.EDITOR_DOCUMENT_FORMAT; exports.EditorDocumentLoadError = _chunkSJ2CPTQCcjs.EditorDocumentLoadError; exports.InjectedStorageError = InjectedStorageError; exports.StorageUnavailableError = StorageUnavailableError; exports.collectAssetRefs = _chunkSJ2CPTQCcjs.collectAssetRefs; exports.collectEditorAssetGarbage = _chunkSJ2CPTQCcjs.collectEditorAssetGarbage; exports.collectRetiredEditorAssets = _chunkSJ2CPTQCcjs.collectRetiredEditorAssets; exports.createAutosaveController = createAutosaveController; exports.createDocumentToolProvider = createDocumentToolProvider; exports.createEditorAssetRegistry = _chunkSJ2CPTQCcjs.createEditorAssetRegistry; exports.createEditorAutosave = createEditorAutosave; exports.createEditorDocumentStore = createEditorDocumentStore; exports.createIndexedDbAdapter = createIndexedDbAdapter; exports.createLoadReport = _chunkSJ2CPTQCcjs.createLoadReport; exports.createLocalStorageAdapter = createLocalStorageAdapter; exports.createMemoryStorage = createMemoryStorage; exports.createOpfsAdapter = createOpfsAdapter; exports.createRecoveryPolicy = createRecoveryPolicy; exports.createRevisionTracker = createRevisionTracker; exports.defineEditorDocument = _chunkSJ2CPTQCcjs.defineEditorDocument; exports.exponentialBackoff = exponentialBackoff; exports.externalizeAssets = _chunkSJ2CPTQCcjs.externalizeAssets; exports.formatRecoveryMessage = formatRecoveryMessage; exports.hasLoadProblems = _chunkSJ2CPTQCcjs.hasLoadProblems; exports.internalizeAssets = _chunkSJ2CPTQCcjs.internalizeAssets; exports.isEditorDocumentFile = _chunkSJ2CPTQCcjs.isEditorDocumentFile; exports.isIndexedDbAvailable = isIndexedDbAvailable; exports.isInlineAsset = _chunkSJ2CPTQCcjs.isInlineAsset; exports.isLocalStorageAvailable = isLocalStorageAvailable; exports.isOpfsAvailable = isOpfsAvailable; exports.loadDocument = _chunkSJ2CPTQCcjs.loadDocument; exports.loadSections = _chunkSJ2CPTQCcjs.loadSections; exports.migrateDocument = _chunkSJ2CPTQCcjs.migrateDocument; exports.parseEditorDocument = _chunkSJ2CPTQCcjs.parseEditorDocument; exports.persistEditorAssets = _chunkSJ2CPTQCcjs.persistEditorAssets; exports.preloadEditorAssets = _chunkSJ2CPTQCcjs.preloadEditorAssets; exports.recoveryMetaKey = recoveryMetaKey; exports.serializeEditorDocument = _chunkSJ2CPTQCcjs.serializeEditorDocument; exports.slugifyDocumentName = slugifyDocumentName; exports.toEditorDocumentFile = _chunkSJ2CPTQCcjs.toEditorDocumentFile; exports.tryCollectEditorAssetGarbage = _chunkSJ2CPTQCcjs.tryCollectEditorAssetGarbage; exports.withEditorAssets = _chunkSJ2CPTQCcjs.withEditorAssets; exports.withStorageFailures = withStorageFailures;

package/dist/persistence/index.js

@@ -3,6 +3,8 @@ import {
   EDITOR_DOCUMENT_FORMAT,
   EditorDocumentLoadError,
   collectAssetRefs,
+  collectEditorAssetGarbage,
+  collectRetiredEditorAssets,
   createEditorAssetRegistry,
   createLoadReport,
   defineEditorDocument,
@@ -19,8 +21,9 @@ import {
   preloadEditorAssets,
   serializeEditorDocument,
   toEditorDocumentFile,
+  tryCollectEditorAssetGarbage,
   withEditorAssets
-} from "../chunk-NHLYK3AX.js";
+} from "../chunk-XBQX76CT.js";
 import "../chunk-HF5QZS7Z.js";
 
 // src/persistence/recoveryPolicy.ts
@@ -136,7 +139,13 @@ function withStorageFailures(inner, failure) {
     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) {
@@ -160,7 +169,13 @@ function guarded(kind, isAvailable, failure, impl) {
     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 = {}) {
@@ -174,6 +189,9 @@ function createMemoryStorage(options = {}) {
     },
     async remove(key) {
       entries.delete(key);
+    },
+    async keys(prefix) {
+      return [...entries.keys()].filter((key) => key.startsWith(prefix));
     }
   });
   return Object.assign(adapter, { entries });
@@ -200,7 +218,18 @@ function createLocalStorageAdapter(prefix = "", options = {}) {
     },
     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() {
@@ -255,7 +284,13 @@ function createIndexedDbAdapter(name = "pixerate-editor", options = {}) {
       return typeof value === "string" ? value : null;
     },
     set: (key, value) => write((store) => store.put(value, key)),
-    remove: (key) => write((store) => store.delete(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() {
@@ -339,6 +374,30 @@ function createOpfsAdapter(dir = "pixerate-editor", options = {}) {
       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;
     }
   });
 }
@@ -670,7 +729,8 @@ function createRevisionTracker(options = {}) {
 
 // src/persistence/editorAutosave.ts
 function createEditorAutosave(doc, options) {
-  const { dirty, key, ...rest } = options;
+  const { dirty, key, collectAssetGarbage, ...rest } = options;
+  const collect = () => collectRetiredEditorAssets(rest.storage, doc, collectAssetGarbage);
   const revisions = createRevisionTracker({ history: doc, dirty });
   const controller = createAutosaveController({
     ...rest,
@@ -696,10 +756,12 @@ function createEditorAutosave(doc, options) {
     async discard() {
       await controller.discardRecovery();
       controller.ready();
+      await collect();
     },
     async markClean() {
       revisions.markSaved();
       await controller.markClean();
+      await collect();
     },
     destroy() {
       unsubscribe();
@@ -720,6 +782,7 @@ function createEditorDocumentStore(options) {
   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) => {
@@ -764,8 +827,7 @@ function createEditorDocumentStore(options) {
         savedAt: new Date(now()).toISOString()
       };
       const text = JSON.stringify(toEditorDocumentFile(doc, trimmed));
-      if (doc.assets) await persistEditorAssets(storage, doc.assets, text);
-      await storage.set(fileKey(entry.key), text);
+      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;
     }),
@@ -792,8 +854,10 @@ function createEditorDocumentStore(options) {
       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)) } : {}
   };
 }
 
@@ -939,13 +1003,66 @@ function createDocumentToolProvider(doc, options = {}) {
       }
     }
   ];
+  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) : []]
+    tools: [
+      get,
+      load,
+      ...options.history === false ? [] : [undo, redo],
+      ...store ? storeTools(store) : [],
+      ...store?.collectAssetGarbage && doc.assets ? assetTools(store) : []
+    ]
   };
 }
 export {
@@ -955,6 +1072,8 @@ export {
   InjectedStorageError,
   StorageUnavailableError,
   collectAssetRefs,
+  collectEditorAssetGarbage,
+  collectRetiredEditorAssets,
   createAutosaveController,
   createDocumentToolProvider,
   createEditorAssetRegistry,
@@ -988,6 +1107,7 @@ export {
   serializeEditorDocument,
   slugifyDocumentName,
   toEditorDocumentFile,
+  tryCollectEditorAssetGarbage,
   withEditorAssets,
   withStorageFailures
 };

package/dist/persistence/storage.d.cts

@@ -5,7 +5,7 @@
  * construction, so SSR and old browsers are safe) and accepts an injectable
  * failure mode for tests.
  */
-export type StorageOperation = "get" | "set" | "remove";
+export type StorageOperation = "get" | "set" | "remove" | "keys";
 /**
  * Injected failure: return `true` (or an `Error`) to make that operation fail.
  * Example: `failure: (op) => op === "set"` simulates a full disk.
@@ -19,6 +19,12 @@ export interface StorageAdapter {
     get(key: string): Promise<string | null>;
     set(key: string, value: string): Promise<void>;
     remove(key: string): Promise<void>;
+    /**
+     * Every stored key that starts with `prefix` (default: every key), in no particular order.
+     * Optional: custom adapters may leave it out, but asset garbage collection
+     * (`collectEditorAssetGarbage`) needs it. All built-in adapters have it.
+     */
+    keys?(prefix?: string): Promise<string[]>;
 }
 export interface StorageAdapterOptions {
     failure?: StorageFailureMode;
@@ -44,6 +50,10 @@ export interface WebStorageLike {
     getItem(key: string): string | null;
     setItem(key: string, value: string): void;
     removeItem(key: string): void;
+    /** Number of stored items (with `key`, lets the adapter list its keys). */
+    readonly length?: number;
+    /** The key at `index` (with `length`, lets the adapter list its keys). */
+    key?(index: number): string | null;
 }
 export interface LocalStorageAdapterOptions extends StorageAdapterOptions {
     /** Storage to use (default `globalThis.localStorage`, e.g. pass `sessionStorage`). */
@@ -84,6 +94,8 @@ export interface OpfsDirectoryLike {
         create?: boolean;
     }): Promise<OpfsFileLike>;
     removeEntry(name: string): Promise<void>;
+    /** Entry names (real directory handles have it); lets the adapter list its keys. */
+    keys?(): AsyncIterable<string>;
 }
 export interface OpfsFileLike {
     getFile(): Promise<{

package/dist/persistence/storage.d.ts

@@ -5,7 +5,7 @@
  * construction, so SSR and old browsers are safe) and accepts an injectable
  * failure mode for tests.
  */
-export type StorageOperation = "get" | "set" | "remove";
+export type StorageOperation = "get" | "set" | "remove" | "keys";
 /**
  * Injected failure: return `true` (or an `Error`) to make that operation fail.
  * Example: `failure: (op) => op === "set"` simulates a full disk.
@@ -19,6 +19,12 @@ export interface StorageAdapter {
     get(key: string): Promise<string | null>;
     set(key: string, value: string): Promise<void>;
     remove(key: string): Promise<void>;
+    /**
+     * Every stored key that starts with `prefix` (default: every key), in no particular order.
+     * Optional: custom adapters may leave it out, but asset garbage collection
+     * (`collectEditorAssetGarbage`) needs it. All built-in adapters have it.
+     */
+    keys?(prefix?: string): Promise<string[]>;
 }
 export interface StorageAdapterOptions {
     failure?: StorageFailureMode;
@@ -44,6 +50,10 @@ export interface WebStorageLike {
     getItem(key: string): string | null;
     setItem(key: string, value: string): void;
     removeItem(key: string): void;
+    /** Number of stored items (with `key`, lets the adapter list its keys). */
+    readonly length?: number;
+    /** The key at `index` (with `length`, lets the adapter list its keys). */
+    key?(index: number): string | null;
 }
 export interface LocalStorageAdapterOptions extends StorageAdapterOptions {
     /** Storage to use (default `globalThis.localStorage`, e.g. pass `sessionStorage`). */
@@ -84,6 +94,8 @@ export interface OpfsDirectoryLike {
         create?: boolean;
     }): Promise<OpfsFileLike>;
     removeEntry(name: string): Promise<void>;
+    /** Entry names (real directory handles have it); lets the adapter list its keys. */
+    keys?(): AsyncIterable<string>;
 }
 export interface OpfsFileLike {
     getFile(): Promise<{