@anton-gustafsson/snapshot-core 0.0.7 → 0.4.1

package/dist/snapshot-service.js

@@ -1,10 +1,13 @@
-import html2canvas from 'html2canvas';
+import { encodeSnapshot } from './encode';
+import { SnapshotDetachedElementError, SnapshotRenderError, SnapshotTaintedCanvasError } from './errors';
 import { IndexedDbSnapshotStorage } from './snapshot-storage';
 const CONTENT_PADDING = 16;
+const VARIANT_SEPARATOR = '@';
 // Tracks keyPrefixes already claimed by a live SnapshotService instance, so
 // two instances that both forget to set one (or pick the same one) get a
 // loud warning instead of silently colliding on the same broadcast channel
-// and storage keys.
+// and storage keys. Entries are dropped on close(), so a hot-reload that
+// re-instantiates a closed service doesn't warn.
 const activeKeyPrefixes = new Set();
 /** So a container much bigger than its content (e.g. a full-page canvas with one small widget) doesn't capture as mostly empty space — crop to the actual children's bounding box, padded, instead of the whole element. */
 function getContentBounds(el) {
@@ -45,46 +48,188 @@ function getContentBounds(el) {
 export class SnapshotService {
     constructor(config = {}) {
         this.listeners = new Set();
+        /** In-flight captures, keyed by storage key, so two callers racing on the same view do one render. */
+        this.capturing = new Map();
         this.storage = config.storage ?? new IndexedDbSnapshotStorage();
         this.scale = config.scale ?? 0.4;
         this.keyPrefix = config.keyPrefix ?? '';
+        this.encode = config.encode;
+        this.keyFor = config.keyFor;
         if (activeKeyPrefixes.has(this.keyPrefix)) {
             console.warn(`SnapshotService: another instance already uses keyPrefix "${this.keyPrefix}" — ` +
                 'their storage keys and cross-tab notifications will collide. Give each instance its own keyPrefix.');
         }
         activeKeyPrefixes.add(this.keyPrefix);
-        this.channel = new BroadcastChannel(`nav-snapshots:${this.keyPrefix}`);
-        this.channel.onmessage = (e) => {
-            const { id, url } = e.data;
-            this.listeners.forEach((l) => l(id, url));
-        };
+        if (typeof BroadcastChannel === 'function') {
+            this.channel = new BroadcastChannel(`nav-snapshots:${this.keyPrefix}`);
+            this.channel.onmessage = (e) => {
+                const { id, url, variant } = e.data;
+                this.listeners.forEach((l) => l(id, url, variant));
+            };
+        }
+        this.storage.attach?.(this);
+    }
+    /**
+     * The fully-qualified storage key for an id (+ variant) under this instance.
+     * `id`/`variant` are `encodeURIComponent`-escaped before joining, so a `@`
+     * (or any other character) inside either can never be mistaken for the
+     * separator itself — without escaping, `id: 'a@b'` and `id: 'a', variant: 'b'`
+     * would otherwise land on the exact same key.
+     */
+    keyOf(id, opts = {}) {
+        const base = opts.variant === undefined || opts.variant === ''
+            ? `${this.keyPrefix}${encodeURIComponent(id)}`
+            : `${this.keyPrefix}${encodeURIComponent(id)}${VARIANT_SEPARATOR}${encodeURIComponent(opts.variant)}`;
+        const key = { id, key: base };
+        if (opts.variant)
+            key.variant = opts.variant;
+        if (this.keyFor)
+            key.key = this.keyFor(key);
+        return key;
+    }
+    /**
+     * Inverse of `keyOf()` for the default key shape — splits a stored key back
+     * into `{ id, variant }`. Returns `null` for a key belonging to a different
+     * `keyPrefix`, or for any key when a custom `keyFor` is configured (a custom
+     * shape isn't reversible).
+     */
+    parseKey(key) {
+        if (this.keyFor)
+            return null;
+        if (!key.startsWith(this.keyPrefix))
+            return null;
+        const rest = key.slice(this.keyPrefix.length);
+        // Safe to split on the first raw '@': encodeURIComponent never emits one,
+        // so a '@' here can only be the separator this class itself inserted.
+        const at = rest.indexOf(VARIANT_SEPARATOR);
+        if (at < 0)
+            return { id: decodeURIComponent(rest), key };
+        return { id: decodeURIComponent(rest.slice(0, at)), variant: decodeURIComponent(rest.slice(at + 1)), key };
     }
-    /** Capture works on any element — a snapshot-nav-list item is one convention, not a requirement. */
-    async capture(el, id) {
+    /**
+     * Capture works on any element — a snapshot-nav-list item is one convention,
+     * not a requirement. Concurrent calls for the same id/variant share one
+     * render instead of racing two.
+     */
+    async capture(el, id, opts = {}) {
+        // Declared `async` on purpose: `keyOf()` can throw synchronously (a
+        // caller-supplied `keyFor` is free to), and without `async` that throw
+        // would escape as a synchronous exception instead of a rejected promise,
+        // bypassing a caller's chained `.catch()`.
+        const key = this.keyOf(id, opts);
+        const inFlight = this.capturing.get(key.key);
+        if (inFlight)
+            return inFlight;
+        const run = this.runCapture(el, key, opts).finally(() => this.capturing.delete(key.key));
+        this.capturing.set(key.key, run);
+        return run;
+    }
+    async runCapture(el, key, opts) {
+        // A detached element renders as an empty (or, under html2canvas, a failed)
+        // clone — reject with something the caller can recognise instead of
+        // storing a blank thumbnail over a good one.
+        if (!el.isConnected)
+            throw new SnapshotDetachedElementError(key.id);
         const crop = getContentBounds(el);
-        const canvas = await html2canvas(el, {
-            scale: this.scale,
-            logging: false,
-            useCORS: true,
-            x: crop.x,
-            y: crop.y,
-            width: crop.width,
-            height: crop.height,
-        });
-        const blob = await new Promise((resolve, reject) => canvas.toBlob((b) => b
-            ? resolve(b)
-            : reject(new Error('SnapshotService: canvas.toBlob() returned null — the captured element likely contains tainted (cross-origin, no CORS headers) content, or has zero size.')), 'image/png'));
-        const url = await this.storage.save(this.keyPrefix + id, blob);
-        this.notify(id, url);
+        // Imported on demand so `import '@anton-gustafsson/snapshot-core'` doesn't
+        // pull a DOM-only dependency into a Node/SSR/Jest process that only wants
+        // the types or a storage.
+        const { default: html2canvas } = await import('html2canvas');
+        let canvas;
+        try {
+            canvas = await html2canvas(el, {
+                scale: opts.scale ?? this.scale,
+                logging: false,
+                useCORS: true,
+                x: crop.x,
+                y: crop.y,
+                width: crop.width,
+                height: crop.height,
+            });
+        }
+        catch (err) {
+            // errors.ts documents every rejection from this library as a SnapshotError.
+            throw new SnapshotRenderError(key.id, err);
+        }
+        const raw = await new Promise((resolve, reject) => canvas.toBlob((b) => (b ? resolve(b) : reject(new SnapshotTaintedCanvasError(key.id))), 'image/png'));
+        const encode = opts.encode ?? this.encode;
+        const blob = encode ? await encodeSnapshot(raw, encode) : raw;
+        const url = await this.storage.save(blob, key);
+        this.notify(key.id, url, key.variant);
         return url;
     }
-    get(id) {
-        return this.storage.load(this.keyPrefix + id);
+    get(id, opts = {}) {
+        return this.storage.load(this.keyOf(id, opts));
+    }
+    /**
+     * Batch read, keyed by bare id. Uses the storage's `loadMany()` when it has
+     * one (a single query/round-trip for a whole list) and falls back to parallel
+     * `load()`s when it doesn't.
+     */
+    async getMany(ids, opts = {}) {
+        const keys = ids.map((id) => this.keyOf(id, opts));
+        const byId = new Map();
+        if (this.storage.loadMany) {
+            const byKey = await this.storage.loadMany(keys);
+            for (const key of keys)
+                byId.set(key.id, byKey.get(key.key) ?? null);
+            return byId;
+        }
+        // allSettled, not all: one item's rejection (e.g. a flaky read for one row
+        // of a ten-row list) shouldn't fail every other id's already-successful load.
+        const results = await Promise.allSettled(keys.map((key) => this.storage.load(key)));
+        keys.forEach((key, i) => {
+            const result = results[i];
+            byId.set(key.id, result.status === 'fulfilled' ? result.value : null);
+        });
+        return byId;
     }
     /** Deletes a stored snapshot and notifies subscribers (this tab and others) that `id` is gone. */
-    async remove(id) {
-        await this.storage.remove?.(this.keyPrefix + id);
-        this.notify(id, null);
+    async remove(id, opts = {}) {
+        const key = this.keyOf(id, opts);
+        await this.storage.remove(key);
+        this.notify(id, null, key.variant);
+    }
+    /**
+     * Deletes every stored snapshot (all variants) whose id isn't in `keepIds`,
+     * so thumbnails don't outlive the entities they belong to. Requires a storage
+     * that implements `keys()`; returns the number of snapshots removed.
+     */
+    async prune(keepIds) {
+        if (!this.storage.keys) {
+            console.warn('SnapshotService: prune() needs a storage that implements keys() — nothing was removed.');
+            return 0;
+        }
+        if (this.keyFor) {
+            console.warn('SnapshotService: prune() can\'t reverse a custom keyFor — parseKey() has no way to recover each ' +
+                'entry\'s id, so every stored key is skipped. Nothing was removed.');
+            return 0;
+        }
+        const keep = new Set(keepIds);
+        const stored = await this.storage.keys();
+        let removed = 0;
+        for (const entry of stored) {
+            const parsed = this.parseKey(entry.key);
+            // Not ours (different keyPrefix, or an unreversible custom shape) — leave it alone.
+            if (!parsed || keep.has(parsed.id))
+                continue;
+            await this.storage.remove(parsed);
+            this.notify(parsed.id, null, parsed.variant);
+            removed++;
+        }
+        return removed;
+    }
+    /**
+     * Warms the storage for a list of ids ahead of render (one `loadMany()` where
+     * the storage supports it) and publishes whatever it finds, so any mounted
+     * `<snapshot-nav-list>` paints from the first frame instead of spinning.
+     */
+    async prefetch(ids, opts = {}) {
+        const urls = await this.getMany(ids, opts);
+        for (const [id, url] of urls) {
+            if (url)
+                this.notify(id, url, opts.variant);
+        }
     }
     /**
      * Announces a URL for `id` to subscribers (this tab and others) without
@@ -93,8 +238,8 @@ export class SnapshotService {
      * local cache in front of a slower authoritative database — call this once
      * the slow read settles so any mounted <snapshot-nav-list> updates live.
      */
-    publish(id, url) {
-        this.notify(id, url);
+    publish(id, url, opts = {}) {
+        this.notify(id, url, opts.variant);
     }
     /**
      * Tells subscribers to drop their locally cached thumbnail for `id` and
@@ -103,26 +248,58 @@ export class SnapshotService {
      * it again. Useful when the underlying data changed out from under the
      * cache (or, for a demo, to replay a loading state on demand).
      */
-    invalidate(id) {
-        this.notify(id, null);
+    invalidate(id, opts = {}) {
+        this.notify(id, null, opts.variant);
     }
     subscribe(cb) {
         this.listeners.add(cb);
-        return () => this.listeners.delete(cb);
+        return () => {
+            this.listeners.delete(cb);
+        };
     }
     /** Releases the cross-tab BroadcastChannel. Call when this instance (a non-default, namespaced one) is no longer needed. */
     close() {
-        this.channel.close();
+        this.channel?.close();
         this.listeners.clear();
         activeKeyPrefixes.delete(this.keyPrefix);
     }
     // BroadcastChannel never delivers a message back to its own sender, so
     // same-tab listeners have to be notified directly alongside the cross-tab
     // post — kept as one method so `capture()` and `remove()` can't drift.
-    notify(id, url) {
-        this.channel.postMessage({ id, url });
-        this.listeners.forEach((l) => l(id, url));
+    notify(id, url, variant) {
+        this.channel?.postMessage({ id, url, variant });
+        this.listeners.forEach((l) => l(id, url, variant));
     }
 }
-/** Default singleton (IndexedDB-backed). Replace with your own SnapshotService({ storage }) if you need a real backend. */
-export const snapshotService = new SnapshotService();
+let defaultService;
+/**
+ * The shared IndexedDB-backed instance, created on first call — so importing
+ * this package never opens a BroadcastChannel or an IndexedDB connection an
+ * app that brings its own `SnapshotService` would never use.
+ */
+export function getDefaultSnapshotService() {
+    return (defaultService ??= new SnapshotService());
+}
+/**
+ * @deprecated Use `getDefaultSnapshotService()`. A lazy stand-in for the
+ * default instance: it forwards every access to the real service, constructing
+ * it on first touch rather than at import time.
+ */
+export const snapshotService = new Proxy({}, {
+    get(_target, prop) {
+        const service = getDefaultSnapshotService();
+        // No `receiver` on purpose — forwarding the proxy as `this` to an accessor
+        // would loop straight back through this handler.
+        const value = Reflect.get(service, prop);
+        return typeof value === 'function' ? value.bind(service) : value;
+    },
+    set(_target, prop, value) {
+        return Reflect.set(getDefaultSnapshotService(), prop, value);
+    },
+    has(_target, prop) {
+        return prop in getDefaultSnapshotService();
+    },
+    getPrototypeOf() {
+        return SnapshotService.prototype;
+    },
+});

package/dist/snapshot-storage.d.ts

@@ -1,7 +1,41 @@
+import type { SnapshotService } from './snapshot-service';
+/**
+ * Everything a storage needs to key a snapshot, handed over as one object so
+ * no storage ever has to re-derive (or strip) a prefix the service already
+ * knows.
+ */
+export interface SnapshotKey {
+    /** Bare id, exactly as the caller passed it to `capture()`/`get()`. */
+    id: string;
+    /** Variant, if the call carried one (e.g. a theme). */
+    variant?: string;
+    /** Fully-qualified storage key: `keyPrefix + id [+ '@' + variant]`. Stable, safe to use verbatim. */
+    key: string;
+}
 export interface SnapshotStorage {
-    save(id: string, blob: Blob): Promise<string>;
-    load(id: string): Promise<string | null>;
-    remove?(id: string): Promise<void>;
+    /** Persists `blob` and returns a URL/dataURL that can be displayed right away. */
+    save(blob: Blob, key: SnapshotKey): Promise<string>;
+    load(key: SnapshotKey): Promise<string | null>;
+    remove(key: SnapshotKey): Promise<void>;
+    /**
+     * Optional batch read. When present, a `<snapshot-nav-list>` uses it once per
+     * `items` change instead of one `load()` per row. Resolve a `Map` keyed by
+     * `SnapshotKey.key` (the fully-qualified key), with `null` for a miss.
+     */
+    loadMany?(keys: SnapshotKey[]): Promise<Map<string, string | null>>;
+    /**
+     * Every key this storage holds — enables `SnapshotService.prune()`. `id` and
+     * `variant` are best-effort: a storage that can't tell a `keyPrefix` from an
+     * id may leave them as the raw remainder, since `prune()` re-derives them
+     * from `key` itself.
+     */
+    keys?(): Promise<SnapshotKey[]>;
+    /**
+     * Called once from the `SnapshotService` constructor, so a storage that
+     * resolves fresher data asynchronously can `publish()` it without the
+     * consumer having to wire the two together by hand.
+     */
+    attach?(service: SnapshotService): void;
 }
 /**
  * Default storage: browser-local IndexedDB. Does NOT sync across devices.
@@ -9,14 +43,19 @@ export interface SnapshotStorage {
  * Blobs are stored natively (IndexedDB supports them directly) instead of
  * base64-encoding into a data URL — that would cost ~33% extra storage and
  * an encode/decode pass on every save/render. Displayable URLs are minted
- * via `URL.createObjectURL`, cached per id so a re-capture of the same id
+ * via `URL.createObjectURL`, cached per key so a re-capture of the same key
  * revokes its old URL instead of leaking one per capture.
  */
 export declare class IndexedDbSnapshotStorage implements SnapshotStorage {
     private objectUrls;
-    save(id: string, blob: Blob): Promise<string>;
-    load(id: string): Promise<string | null>;
-    remove(id: string): Promise<void>;
+    private service?;
+    attach(service: SnapshotService): void;
+    save(blob: Blob, key: SnapshotKey): Promise<string>;
+    load(key: SnapshotKey): Promise<string | null>;
+    remove(key: SnapshotKey): Promise<void>;
+    /** One IndexedDB transaction for the whole list instead of one per row. */
+    loadMany(requested: SnapshotKey[]): Promise<Map<string, string | null>>;
+    keys(): Promise<SnapshotKey[]>;
     private mintObjectUrl;
     private revoke;
 }

package/dist/snapshot-storage.js

@@ -1,43 +1,79 @@
-import { get, set, del } from 'idb-keyval';
+import { get, set, del, keys as idbKeys, getMany } from 'idb-keyval';
+const IDB_PREFIX = 'snapshot:';
 /**
  * Default storage: browser-local IndexedDB. Does NOT sync across devices.
  *
  * Blobs are stored natively (IndexedDB supports them directly) instead of
  * base64-encoding into a data URL — that would cost ~33% extra storage and
  * an encode/decode pass on every save/render. Displayable URLs are minted
- * via `URL.createObjectURL`, cached per id so a re-capture of the same id
+ * via `URL.createObjectURL`, cached per key so a re-capture of the same key
  * revokes its old URL instead of leaking one per capture.
  */
 export class IndexedDbSnapshotStorage {
     constructor() {
         this.objectUrls = new Map();
     }
-    async save(id, blob) {
-        await set(`snapshot:${id}`, blob);
-        return this.mintObjectUrl(id, blob);
+    attach(service) {
+        this.service = service;
     }
-    async load(id) {
-        const cached = this.objectUrls.get(id);
+    async save(blob, key) {
+        await set(IDB_PREFIX + key.key, blob);
+        return this.mintObjectUrl(key.key, blob);
+    }
+    async load(key) {
+        const cached = this.objectUrls.get(key.key);
         if (cached)
             return cached;
-        const blob = await get(`snapshot:${id}`);
-        return blob ? this.mintObjectUrl(id, blob) : null;
+        const blob = await get(IDB_PREFIX + key.key);
+        return blob ? this.mintObjectUrl(key.key, blob) : null;
+    }
+    async remove(key) {
+        this.revoke(key.key);
+        await del(IDB_PREFIX + key.key);
+    }
+    /** One IndexedDB transaction for the whole list instead of one per row. */
+    async loadMany(requested) {
+        const result = new Map();
+        const missing = [];
+        for (const key of requested) {
+            const cached = this.objectUrls.get(key.key);
+            if (cached)
+                result.set(key.key, cached);
+            else
+                missing.push(key);
+        }
+        if (missing.length > 0) {
+            const blobs = await getMany(missing.map((key) => IDB_PREFIX + key.key));
+            missing.forEach((key, i) => {
+                const blob = blobs[i];
+                result.set(key.key, blob ? this.mintObjectUrl(key.key, blob) : null);
+            });
+        }
+        return result;
     }
-    async remove(id) {
-        this.revoke(id);
-        await del(`snapshot:${id}`);
+    async keys() {
+        const stored = await idbKeys();
+        return stored
+            .filter((k) => typeof k === 'string' && k.startsWith(IDB_PREFIX))
+            .map((k) => {
+            const key = k.slice(IDB_PREFIX.length);
+            // Once attached, the service can split the key properly (it owns both
+            // the keyPrefix and the '@variant' convention); standalone, the raw
+            // remainder is the honest answer.
+            return this.service?.parseKey(key) ?? { id: key, key };
+        });
     }
-    mintObjectUrl(id, blob) {
-        this.revoke(id);
+    mintObjectUrl(key, blob) {
+        this.revoke(key);
         const url = URL.createObjectURL(blob);
-        this.objectUrls.set(id, url);
+        this.objectUrls.set(key, url);
         return url;
     }
-    revoke(id) {
-        const existing = this.objectUrls.get(id);
+    revoke(key) {
+        const existing = this.objectUrls.get(key);
         if (existing) {
             URL.revokeObjectURL(existing);
-            this.objectUrls.delete(id);
+            this.objectUrls.delete(key);
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anton-gustafsson/snapshot-core",
-  "version": "0.0.7",
+  "version": "0.4.1",
   "description": "A pluggable snapshot service that turns any DOM element into a stored, shareable image, plus an optional <snapshot-nav-list> web component to display them.",
   "license": "MIT",
   "repository": {
@@ -19,7 +19,9 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json"
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.test.json"
   },
   "dependencies": {
     "lit": "^3.2.0",
@@ -27,6 +29,8 @@
     "idb-keyval": "^6.2.1"
   },
   "devDependencies": {
-    "typescript": "^5.5.0"
+    "jsdom": "^28.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.0.8"
   }
 }