@pixerate/editor 0.163.0 → 0.165.0

package/dist/paint-editor/index.js

@@ -7,7 +7,7 @@ import {
   resolveExternalAssets,
   serializeLayers,
   serializeLayersExternal
-} from "../chunk-3VLOOO3G.js";
+} from "../chunk-BDIM6NVW.js";
 import "../chunk-3CI7FRMK.js";
 import {
   EffectRendererPool
@@ -54,7 +54,7 @@ import {
   realPresenceClock,
   tweenPresenceCursor
 } from "../chunk-O2ANJFUF.js";
-import "../chunk-SET6KJOP.js";
+import "../chunk-LPIKXPBM.js";
 import {
   BRUSH_ID,
   BRUSH_ROTATIONS,
@@ -227,17 +227,18 @@ import "../chunk-VDGBHYC7.js";
 import {
   createEditorAssetRegistry,
   defineEditorDocument
-} from "../chunk-NHLYK3AX.js";
+} from "../chunk-XBQX76CT.js";
 import "../chunk-HF5QZS7Z.js";
-import "../chunk-BQWGN5WH.js";
+import "../chunk-M2TPMYJE.js";
 import "../chunk-2WPNAGHI.js";
 import {
   HARMONY_KINDS,
   colorHarmony,
   hueToWheel,
   wheelToHue
-} from "../chunk-QYZGBVNC.js";
-import "../chunk-4VU4CP7R.js";
+} from "../chunk-7272D3K2.js";
+import "../chunk-YBAPT7NL.js";
+import "../chunk-MHLU6GRJ.js";
 import "../chunk-6ONMQ6WF.js";
 
 // src/paint-editor/document.ts

package/dist/parameters/index.cjs

@@ -1,6 +1,6 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class;
 
-var _chunkM4MIZPQIcjs = require('../chunk-M4MIZPQI.cjs');
+var _chunkSJ2CPTQCcjs = require('../chunk-SJ2CPTQC.cjs');
 require('../chunk-2BSBFBOA.cjs');
 
 
@@ -1327,7 +1327,7 @@ function mapRange(value, from, to, options) {
 // src/parameters/editorDocument.ts
 var isRecord = (value) => !!value && typeof value === "object" && !Array.isArray(value);
 function createParametersEditorDocument(controller) {
-  return _chunkM4MIZPQIcjs.defineEditorDocument.call(void 0, {
+  return _chunkSJ2CPTQCcjs.defineEditorDocument.call(void 0, {
     kind: "parameters",
     get: () => controller.toJSON(),
     load: (document, { history }) => {

package/dist/parameters/index.js

@@ -1,6 +1,6 @@
 import {
   defineEditorDocument
-} from "../chunk-NHLYK3AX.js";
+} from "../chunk-XBQX76CT.js";
 import "../chunk-HF5QZS7Z.js";
 import {
   HistoryManager

package/dist/persistence/assetWrites.d.cts

@@ -0,0 +1,22 @@
+/**
+ * Coordination between asset writes and asset garbage collection (internal: not exported from
+ * the package). Collection must never delete an asset that a write in flight is about to point a
+ * document at, so:
+ *
+ * - every write that persists assets leases their references until its document is written, and
+ *   a running collection skips leased references and references leased while it runs;
+ * - where the Web Locks API exists, writes hold a shared lock and collection an exclusive one,
+ *   which extends the same guarantee to other tabs on the same origin.
+ */
+/** Marks `refs` as about to be referenced by a document write; call the result when it is written. */
+export declare function leaseAssetRefs(refs: Iterable<string>): () => void;
+/**
+ * Starts recording references that are, or become, leased. `touched` holds every reference
+ * leased now or at any time until `stop()`.
+ */
+export declare function watchAssetLeases(): {
+    touched: Set<string>;
+    stop(): void;
+};
+/** Runs `task` under the cross-tab asset lock for `prefix` when the Web Locks API exists. */
+export declare function withAssetLock<T>(prefix: string, mode: "shared" | "exclusive", task: () => Promise<T>): Promise<T>;

package/dist/persistence/assetWrites.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Coordination between asset writes and asset garbage collection (internal: not exported from
+ * the package). Collection must never delete an asset that a write in flight is about to point a
+ * document at, so:
+ *
+ * - every write that persists assets leases their references until its document is written, and
+ *   a running collection skips leased references and references leased while it runs;
+ * - where the Web Locks API exists, writes hold a shared lock and collection an exclusive one,
+ *   which extends the same guarantee to other tabs on the same origin.
+ */
+/** Marks `refs` as about to be referenced by a document write; call the result when it is written. */
+export declare function leaseAssetRefs(refs: Iterable<string>): () => void;
+/**
+ * Starts recording references that are, or become, leased. `touched` holds every reference
+ * leased now or at any time until `stop()`.
+ */
+export declare function watchAssetLeases(): {
+    touched: Set<string>;
+    stop(): void;
+};
+/** Runs `task` under the cross-tab asset lock for `prefix` when the Web Locks API exists. */
+export declare function withAssetLock<T>(prefix: string, mode: "shared" | "exclusive", task: () => Promise<T>): Promise<T>;

package/dist/persistence/assets.d.cts

@@ -17,6 +17,11 @@ export interface EditorAssetRegistry {
     /** Puts data read back from storage under its reference. */
     set(ref: string, data: string): void;
     readonly size: number;
+    /**
+     * Every reference the registry holds. Optional for custom registries, but
+     * `collectEditorAssetGarbage({ keep })` needs it to protect a registry's assets.
+     */
+    refs?(): string[];
 }
 /** Whether a string is inline binary data worth keeping out of the document. */
 export declare function isInlineAsset(value: string): boolean;
@@ -49,3 +54,69 @@ export declare function preloadEditorAssets(storage: StorageAdapter, registry: E
  * document store uses for an editor whose document has `assets`.
  */
 export declare function withEditorAssets(storage: StorageAdapter, registry: EditorAssetRegistry, options?: EditorAssetStorageOptions): StorageAdapter;
+export interface EditorAssetGarbageOptions extends EditorAssetStorageOptions {
+    /**
+     * More assets to keep although no stored value refers to them: asset registries (e.g. an open
+     * editor's `doc.assets`), editor documents with `assets`, asset references, or documents /
+     * JSON text whose references to keep.
+     */
+    keep?: ReadonlyArray<unknown>;
+    /** Report what would be deleted without deleting anything (default `false`). */
+    dryRun?: boolean;
+    /**
+     * Delete only these references (e.g. from a dry run). Every one must still be unreferenced,
+     * or nothing is deleted and the call throws naming them.
+     */
+    only?: ReadonlyArray<string>;
+}
+export interface EditorAssetGarbageReport {
+    /** Assets found in storage. */
+    assets: number;
+    /** Stored values read for references (documents, the index, autosave snapshots, anything else). */
+    scannedKeys: number;
+    /** Assets a stored value refers to. */
+    referenced: number;
+    /** Unreferenced assets kept because of `keep` or a write in flight. */
+    kept: number;
+    /** References of the assets nothing refers to (limited by `only`); deleted unless `dryRun`. */
+    unreferenced: string[];
+    /** Characters of data the unreferenced assets hold. */
+    unreferencedChars: number;
+    /** References deleted (empty on a dry run). */
+    removed: string[];
+    /** Characters of data deleted. */
+    freedChars: number;
+    dryRun: boolean;
+}
+/**
+ * Deletes the stored assets that nothing refers to. Every other value in `storage` (named
+ * documents, the document index, autosave snapshots, anything else) is read and its
+ * `pixerate-asset:` references are kept, so pass the whole storage the editors write to (a
+ * `withEditorAssets` wrapper works too, but reads assets into its registry). Assets in `keep`,
+ * and assets a write in flight in this realm is about to refer to, are never deleted; where the
+ * Web Locks API exists, writes in other tabs are waited for too. Needs `storage.keys` (every
+ * built-in adapter has it) and throws without it.
+ *
+ * Run it after removing documents, after an autosave snapshot was retired (`markClean`), or on
+ * demand. Deleting an asset that an open editor's registry still holds is safe: the collection
+ * invalidates every session's "already written" cache, so its next save writes the asset again.
+ */
+export declare function collectEditorAssetGarbage(storage: StorageAdapter, options?: EditorAssetGarbageOptions): Promise<EditorAssetGarbageReport>;
+/**
+ * `collectEditorAssetGarbage` for automatic, best-effort runs: resolves `null` instead of
+ * throwing when the storage cannot list keys or the collection fails.
+ */
+export declare function tryCollectEditorAssetGarbage(storage: StorageAdapter, options?: EditorAssetGarbageOptions): Promise<EditorAssetGarbageReport | null>;
+/**
+ * The collection an editor autosave runs after retiring a snapshot (`markClean`, `discard`):
+ * best effort, keeping the assets `doc` uses now, and only for documents with `assets`.
+ * `setting` is the autosave's `collectAssetGarbage` option (default on). Pass the unwrapped storage.
+ *
+ * Not the whole registry: a recovery check reads the old snapshot's assets into it, so keeping
+ * it would keep exactly what `discard` throws away. Assets only the registry (e.g. undo) still
+ * holds are written again by the next save.
+ */
+export declare function collectRetiredEditorAssets(storage: StorageAdapter, doc: {
+    assets?: EditorAssetRegistry;
+    getDocument(): unknown;
+}, setting?: boolean | Omit<EditorAssetGarbageOptions, "dryRun" | "only">): Promise<EditorAssetGarbageReport | null>;

package/dist/persistence/assets.d.ts

@@ -17,6 +17,11 @@ export interface EditorAssetRegistry {
     /** Puts data read back from storage under its reference. */
     set(ref: string, data: string): void;
     readonly size: number;
+    /**
+     * Every reference the registry holds. Optional for custom registries, but
+     * `collectEditorAssetGarbage({ keep })` needs it to protect a registry's assets.
+     */
+    refs?(): string[];
 }
 /** Whether a string is inline binary data worth keeping out of the document. */
 export declare function isInlineAsset(value: string): boolean;
@@ -49,3 +54,69 @@ export declare function preloadEditorAssets(storage: StorageAdapter, registry: E
  * document store uses for an editor whose document has `assets`.
  */
 export declare function withEditorAssets(storage: StorageAdapter, registry: EditorAssetRegistry, options?: EditorAssetStorageOptions): StorageAdapter;
+export interface EditorAssetGarbageOptions extends EditorAssetStorageOptions {
+    /**
+     * More assets to keep although no stored value refers to them: asset registries (e.g. an open
+     * editor's `doc.assets`), editor documents with `assets`, asset references, or documents /
+     * JSON text whose references to keep.
+     */
+    keep?: ReadonlyArray<unknown>;
+    /** Report what would be deleted without deleting anything (default `false`). */
+    dryRun?: boolean;
+    /**
+     * Delete only these references (e.g. from a dry run). Every one must still be unreferenced,
+     * or nothing is deleted and the call throws naming them.
+     */
+    only?: ReadonlyArray<string>;
+}
+export interface EditorAssetGarbageReport {
+    /** Assets found in storage. */
+    assets: number;
+    /** Stored values read for references (documents, the index, autosave snapshots, anything else). */
+    scannedKeys: number;
+    /** Assets a stored value refers to. */
+    referenced: number;
+    /** Unreferenced assets kept because of `keep` or a write in flight. */
+    kept: number;
+    /** References of the assets nothing refers to (limited by `only`); deleted unless `dryRun`. */
+    unreferenced: string[];
+    /** Characters of data the unreferenced assets hold. */
+    unreferencedChars: number;
+    /** References deleted (empty on a dry run). */
+    removed: string[];
+    /** Characters of data deleted. */
+    freedChars: number;
+    dryRun: boolean;
+}
+/**
+ * Deletes the stored assets that nothing refers to. Every other value in `storage` (named
+ * documents, the document index, autosave snapshots, anything else) is read and its
+ * `pixerate-asset:` references are kept, so pass the whole storage the editors write to (a
+ * `withEditorAssets` wrapper works too, but reads assets into its registry). Assets in `keep`,
+ * and assets a write in flight in this realm is about to refer to, are never deleted; where the
+ * Web Locks API exists, writes in other tabs are waited for too. Needs `storage.keys` (every
+ * built-in adapter has it) and throws without it.
+ *
+ * Run it after removing documents, after an autosave snapshot was retired (`markClean`), or on
+ * demand. Deleting an asset that an open editor's registry still holds is safe: the collection
+ * invalidates every session's "already written" cache, so its next save writes the asset again.
+ */
+export declare function collectEditorAssetGarbage(storage: StorageAdapter, options?: EditorAssetGarbageOptions): Promise<EditorAssetGarbageReport>;
+/**
+ * `collectEditorAssetGarbage` for automatic, best-effort runs: resolves `null` instead of
+ * throwing when the storage cannot list keys or the collection fails.
+ */
+export declare function tryCollectEditorAssetGarbage(storage: StorageAdapter, options?: EditorAssetGarbageOptions): Promise<EditorAssetGarbageReport | null>;
+/**
+ * The collection an editor autosave runs after retiring a snapshot (`markClean`, `discard`):
+ * best effort, keeping the assets `doc` uses now, and only for documents with `assets`.
+ * `setting` is the autosave's `collectAssetGarbage` option (default on). Pass the unwrapped storage.
+ *
+ * Not the whole registry: a recovery check reads the old snapshot's assets into it, so keeping
+ * it would keep exactly what `discard` throws away. Assets only the registry (e.g. undo) still
+ * holds are written again by the next save.
+ */
+export declare function collectRetiredEditorAssets(storage: StorageAdapter, doc: {
+    assets?: EditorAssetRegistry;
+    getDocument(): unknown;
+}, setting?: boolean | Omit<EditorAssetGarbageOptions, "dryRun" | "only">): Promise<EditorAssetGarbageReport | null>;

package/dist/persistence/documentStore.d.cts

@@ -1,4 +1,5 @@
 import { type EditorDocument, type EditorDocumentFile } from "./editorDocument.cjs";
+import { type EditorAssetGarbageOptions, type EditorAssetGarbageReport } from "./assets.cjs";
 import type { LoadReport } from "./migrate.cjs";
 import type { StorageAdapter } from "./storage.cjs";
 /** One saved document as the index lists it (no document read needed). */
@@ -17,6 +18,12 @@ export interface EditorDocumentStoreOptions {
     namespace?: string;
     /** Wall clock for `savedAt` (default `Date.now`). */
     now?: () => number;
+    /**
+     * After `remove`, delete the stored assets nothing refers to any more
+     * (`collectEditorAssetGarbage`, best effort; default `true`). Needs `storage.keys`; pass
+     * options (e.g. `keep` with open editors' registries) or `false` to turn it off.
+     */
+    collectAssetGarbage?: boolean | Omit<EditorAssetGarbageOptions, "dryRun" | "only">;
 }
 export interface EditorDocumentStore {
     /**
@@ -37,8 +44,17 @@ export interface EditorDocumentStore {
     }): Promise<SavedEditorDocument & {
         report: LoadReport;
     }>;
-    /** Deletes a saved document; `false` when there was none. */
+    /**
+     * Deletes a saved document; `false` when there was none. Then deletes the assets nothing
+     * refers to any more, unless `collectAssetGarbage: false`.
+     */
     remove(key: string): Promise<boolean>;
+    /**
+     * Deletes (or with `dryRun`, finds) the stored assets nothing refers to, queued after the
+     * store's other operations (see `collectEditorAssetGarbage`). Only present when the storage
+     * can list its keys.
+     */
+    collectAssetGarbage?(options?: EditorAssetGarbageOptions): Promise<EditorAssetGarbageReport>;
 }
 /** `"Release flow v2"` → `"release-flow-v2"` (the key part of a saved name). */
 export declare function slugifyDocumentName(name: string): string;

package/dist/persistence/documentStore.d.ts

@@ -1,4 +1,5 @@
 import { type EditorDocument, type EditorDocumentFile } from "./editorDocument.js";
+import { type EditorAssetGarbageOptions, type EditorAssetGarbageReport } from "./assets.js";
 import type { LoadReport } from "./migrate.js";
 import type { StorageAdapter } from "./storage.js";
 /** One saved document as the index lists it (no document read needed). */
@@ -17,6 +18,12 @@ export interface EditorDocumentStoreOptions {
     namespace?: string;
     /** Wall clock for `savedAt` (default `Date.now`). */
     now?: () => number;
+    /**
+     * After `remove`, delete the stored assets nothing refers to any more
+     * (`collectEditorAssetGarbage`, best effort; default `true`). Needs `storage.keys`; pass
+     * options (e.g. `keep` with open editors' registries) or `false` to turn it off.
+     */
+    collectAssetGarbage?: boolean | Omit<EditorAssetGarbageOptions, "dryRun" | "only">;
 }
 export interface EditorDocumentStore {
     /**
@@ -37,8 +44,17 @@ export interface EditorDocumentStore {
     }): Promise<SavedEditorDocument & {
         report: LoadReport;
     }>;
-    /** Deletes a saved document; `false` when there was none. */
+    /**
+     * Deletes a saved document; `false` when there was none. Then deletes the assets nothing
+     * refers to any more, unless `collectAssetGarbage: false`.
+     */
     remove(key: string): Promise<boolean>;
+    /**
+     * Deletes (or with `dryRun`, finds) the stored assets nothing refers to, queued after the
+     * store's other operations (see `collectEditorAssetGarbage`). Only present when the storage
+     * can list its keys.
+     */
+    collectAssetGarbage?(options?: EditorAssetGarbageOptions): Promise<EditorAssetGarbageReport>;
 }
 /** `"Release flow v2"` → `"release-flow-v2"` (the key part of a saved name). */
 export declare function slugifyDocumentName(name: string): string;

package/dist/persistence/documentTools.d.cts

@@ -17,7 +17,11 @@ export interface DocumentToolProviderOptions {
      * whose own provider already has them.
      */
     history?: boolean;
-    /** Saved documents: adds `save_<kind>_document`, `list_saved_<kind>_documents` and `open_saved_<kind>_document`. */
+    /**
+     * Saved documents: adds `save_<kind>_document`, `list_saved_<kind>_documents` and `open_saved_<kind>_document`.
+     * For documents with `assets` (image, paint) on a storage that lists keys, also
+     * `find_unreferenced_<kind>_assets` and `delete_unreferenced_<kind>_assets`.
+     */
     store?: EditorDocumentStore;
     /** Name `save_<kind>_document` uses when none is given (default "Untitled <noun>"). */
     name?: () => string | undefined;

package/dist/persistence/documentTools.d.ts

@@ -17,7 +17,11 @@ export interface DocumentToolProviderOptions {
      * whose own provider already has them.
      */
     history?: boolean;
-    /** Saved documents: adds `save_<kind>_document`, `list_saved_<kind>_documents` and `open_saved_<kind>_document`. */
+    /**
+     * Saved documents: adds `save_<kind>_document`, `list_saved_<kind>_documents` and `open_saved_<kind>_document`.
+     * For documents with `assets` (image, paint) on a storage that lists keys, also
+     * `find_unreferenced_<kind>_assets` and `delete_unreferenced_<kind>_assets`.
+     */
     store?: EditorDocumentStore;
     /** Name `save_<kind>_document` uses when none is given (default "Untitled <noun>"). */
     name?: () => string | undefined;

package/dist/persistence/editorAutosave.d.cts

@@ -1,5 +1,6 @@
 import { type AutosaveController, type AutosaveControllerOptions, type AutosaveRecovery } from "./autosave.cjs";
 import { type EditorDocument, type EditorDocumentFile } from "./editorDocument.cjs";
+import { type EditorAssetGarbageOptions } from "./assets.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"> {
@@ -10,6 +11,12 @@ export interface EditorAutosaveOptions extends Omit<AutosaveControllerOptions<Ed
      * saved state needs no snapshot. Without it, every change counts until `markClean()`.
      */
     dirty?: DirtyFlagSource;
+    /**
+     * For documents with `assets`: after `markClean` or `discard` retire a snapshot, delete the
+     * stored assets nothing refers to any more (`collectEditorAssetGarbage`, best effort, keeping
+     * the assets the document uses now; default `true`). Needs `storage.keys`; `false` turns it off.
+     */
+    collectAssetGarbage?: boolean | Omit<EditorAssetGarbageOptions, "dryRun" | "only">;
 }
 export interface EditorAutosave {
     readonly controller: AutosaveController<EditorDocumentFile>;

package/dist/persistence/editorAutosave.d.ts

@@ -1,5 +1,6 @@
 import { type AutosaveController, type AutosaveControllerOptions, type AutosaveRecovery } from "./autosave.js";
 import { type EditorDocument, type EditorDocumentFile } from "./editorDocument.js";
+import { type EditorAssetGarbageOptions } from "./assets.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"> {
@@ -10,6 +11,12 @@ export interface EditorAutosaveOptions extends Omit<AutosaveControllerOptions<Ed
      * saved state needs no snapshot. Without it, every change counts until `markClean()`.
      */
     dirty?: DirtyFlagSource;
+    /**
+     * For documents with `assets`: after `markClean` or `discard` retire a snapshot, delete the
+     * stored assets nothing refers to any more (`collectEditorAssetGarbage`, best effort, keeping
+     * the assets the document uses now; default `true`). Needs `storage.keys`; `false` turns it off.
+     */
+    collectAssetGarbage?: boolean | Omit<EditorAssetGarbageOptions, "dryRun" | "only">;
 }
 export interface EditorAutosave {
     readonly controller: AutosaveController<EditorDocumentFile>;