@anton-gustafsson/snapshot-core 0.0.7 → 0.4.1

package/dist/cached-snapshot-storage.d.ts

@@ -0,0 +1,79 @@
+import type { EncodeOptions } from './encode';
+import type { SnapshotService } from './snapshot-service';
+import type { SnapshotKey, SnapshotStorage } from './snapshot-storage';
+/**
+ * The half of a server-backed storage only the consumer can write: the HTTP
+ * calls themselves. Everything around them — the local cache, the
+ * stale-while-revalidate order, the "a 404 must not evict my capture" rule —
+ * is `CachedSnapshotStorage`'s job.
+ */
+export interface RemoteSnapshotStorage {
+    /**
+     * Resolve `null` for "nothing stored yet" — **including a 404**, which is the
+     * normal answer for an entity nobody has captured. Reject only for real
+     * failures (network down, 500, 403), which are reported through `onError`
+     * and leave the local copy standing.
+     */
+    load(id: string, key: SnapshotKey): Promise<Blob | null>;
+    save(blob: Blob, id: string, key: SnapshotKey): Promise<void>;
+    remove?(id: string, key: SnapshotKey): Promise<void>;
+}
+export interface CachedSnapshotStorageOptions {
+    remote: RemoteSnapshotStorage;
+    /** Defaults to a fresh `IndexedDbSnapshotStorage`. */
+    local?: SnapshotStorage;
+    /** Re-encode applied to the *uploaded* copy only; the local cache keeps the full capture. */
+    uploadEncode?: EncodeOptions;
+    /** Skip the upload (and report a `SnapshotTooLargeError`) above this size. Mirrors a server-side cap. */
+    maxBytes?: number;
+    /**
+     * Called for every swallowed failure instead of `console.warn`, so a consumer
+     * can filter the routine ones (a 403 for a read-only user) from the real ones.
+     */
+    onError?(err: unknown, key: SnapshotKey, op: 'load' | 'save' | 'remove'): void;
+}
+/**
+ * A local cache in front of a remote store — the shape every server-backed
+ * consumer ends up needing.
+ *
+ * Load is stale-while-revalidate: the local hit paints immediately and the
+ * remote read happens in the background, `publish()`ing through the attached
+ * service if it turns up something new. Save writes locally first and fires the
+ * upload without awaiting it, so a slow PUT can never delay a navigation.
+ *
+ * Freshness is delegated to the HTTP cache (`ETag` + `Cache-Control: no-cache`)
+ * rather than any version bookkeeping here.
+ */
+export declare class CachedSnapshotStorage implements SnapshotStorage {
+    private readonly remote;
+    private readonly local;
+    private readonly options;
+    private service?;
+    /**
+     * Byte size of the copy currently cached per key. A revalidation that comes
+     * back the same size is treated as unchanged, so a warm list doesn't rewrite
+     * IndexedDB and swap every <img> src on every visit.
+     */
+    private cachedSizes;
+    /** In-flight revalidations, so N rows of the same key don't fan out N reads. */
+    private revalidating;
+    /** Keys `remove()` has deleted, so a revalidation already in flight can't resurrect them when it resolves after. */
+    private removedKeys;
+    /** Only defined when the wrapped local storage has one — keeps `SnapshotService.prune()`'s capability check honest. */
+    readonly keys?: () => Promise<SnapshotKey[]>;
+    constructor(options: CachedSnapshotStorageOptions);
+    attach(service: SnapshotService): void;
+    /** Local write is awaited (the caller needs a displayable URL); the upload is not. */
+    save(blob: Blob, key: SnapshotKey): Promise<string>;
+    load(key: SnapshotKey): Promise<string | null>;
+    loadMany(keys: SnapshotKey[]): Promise<Map<string, string | null>>;
+    remove(key: SnapshotKey): Promise<void>;
+    /** Best-effort: reads the cached blob back through its own URL to learn its size, without any storage needing a new method. */
+    private primeCachedSize;
+    private upload;
+    /** Awaited path: resolve the remote copy, seed the cache, hand back the URL. */
+    private fetchRemote;
+    /** Background path: only touches anything when the remote copy actually differs. */
+    private revalidate;
+    private report;
+}

package/dist/cached-snapshot-storage.js

@@ -0,0 +1,176 @@
+import { encodeSnapshot } from './encode';
+import { SnapshotTooLargeError } from './errors';
+import { IndexedDbSnapshotStorage } from './snapshot-storage';
+/**
+ * A local cache in front of a remote store — the shape every server-backed
+ * consumer ends up needing.
+ *
+ * Load is stale-while-revalidate: the local hit paints immediately and the
+ * remote read happens in the background, `publish()`ing through the attached
+ * service if it turns up something new. Save writes locally first and fires the
+ * upload without awaiting it, so a slow PUT can never delay a navigation.
+ *
+ * Freshness is delegated to the HTTP cache (`ETag` + `Cache-Control: no-cache`)
+ * rather than any version bookkeeping here.
+ */
+export class CachedSnapshotStorage {
+    constructor(options) {
+        /**
+         * Byte size of the copy currently cached per key. A revalidation that comes
+         * back the same size is treated as unchanged, so a warm list doesn't rewrite
+         * IndexedDB and swap every <img> src on every visit.
+         */
+        this.cachedSizes = new Map();
+        /** In-flight revalidations, so N rows of the same key don't fan out N reads. */
+        this.revalidating = new Set();
+        /** Keys `remove()` has deleted, so a revalidation already in flight can't resurrect them when it resolves after. */
+        this.removedKeys = new Set();
+        this.options = options;
+        this.remote = options.remote;
+        this.local = options.local ?? new IndexedDbSnapshotStorage();
+        if (this.local.keys) {
+            const local = this.local;
+            this.keys = () => local.keys();
+        }
+    }
+    attach(service) {
+        this.service = service;
+        this.local.attach?.(service);
+    }
+    /** Local write is awaited (the caller needs a displayable URL); the upload is not. */
+    async save(blob, key) {
+        const url = await this.local.save(blob, key);
+        this.cachedSizes.set(key.key, blob.size);
+        this.removedKeys.delete(key.key);
+        void this.upload(blob, key);
+        return url;
+    }
+    async load(key) {
+        const cached = await this.local.load(key);
+        if (cached) {
+            // A fresh instance (e.g. after a page reload) has an empty cachedSizes
+            // even though the local copy is already on disk — without this, the
+            // first revalidate() below has nothing to compare against and always
+            // treats an unchanged remote copy as "changed".
+            if (!this.cachedSizes.has(key.key))
+                await this.primeCachedSize(key, cached);
+            void this.revalidate(key, true);
+            return cached;
+        }
+        // Cold miss: nothing to paint yet, so the remote read is worth awaiting —
+        // and its URL is returned directly rather than announced via publish().
+        return this.fetchRemote(key);
+    }
+    async loadMany(keys) {
+        const cached = this.local.loadMany
+            ? await this.local.loadMany(keys)
+            : new Map(await Promise.all(keys.map(async (key) => [key.key, await this.local.load(key)])));
+        const misses = keys.filter((key) => !cached.get(key.key));
+        const fetched = await Promise.all(misses.map((key) => this.fetchRemote(key)));
+        misses.forEach((key, i) => cached.set(key.key, fetched[i]));
+        // Everything that came from the cache still gets revalidated, exactly as a
+        // single load() would — primed first, for the same reason as load() above.
+        const hits = keys.filter((key) => !misses.includes(key));
+        await Promise.all(hits.map(async (key) => {
+            const url = cached.get(key.key);
+            if (url && !this.cachedSizes.has(key.key))
+                await this.primeCachedSize(key, url);
+        }));
+        for (const key of hits)
+            void this.revalidate(key, true);
+        return cached;
+    }
+    async remove(key) {
+        this.removedKeys.add(key.key);
+        this.cachedSizes.delete(key.key);
+        await this.local.remove(key);
+        if (!this.remote.remove)
+            return;
+        try {
+            await this.remote.remove(key.id, key);
+        }
+        catch (err) {
+            this.report(err, key, 'remove');
+            throw err;
+        }
+    }
+    /** Best-effort: reads the cached blob back through its own URL to learn its size, without any storage needing a new method. */
+    async primeCachedSize(key, url) {
+        if (typeof fetch !== 'function')
+            return;
+        try {
+            const blob = await fetch(url).then((r) => r.blob());
+            this.cachedSizes.set(key.key, blob.size);
+        }
+        catch {
+            // A miss here just costs one extra revalidate() write, same as before this fix.
+        }
+    }
+    async upload(blob, key) {
+        try {
+            const payload = this.options.uploadEncode ? await encodeSnapshot(blob, this.options.uploadEncode) : blob;
+            const { maxBytes } = this.options;
+            if (maxBytes !== undefined && payload.size > maxBytes) {
+                this.report(new SnapshotTooLargeError(payload.size, maxBytes), key, 'save');
+                return;
+            }
+            await this.remote.save(payload, key.id, key);
+        }
+        catch (err) {
+            this.report(err, key, 'save');
+        }
+    }
+    /** Awaited path: resolve the remote copy, seed the cache, hand back the URL. */
+    async fetchRemote(key) {
+        try {
+            const blob = await this.remote.load(key.id, key);
+            // null / empty is "nobody has captured this yet", not a failure.
+            if (!blob || blob.size === 0)
+                return null;
+            const url = await this.local.save(blob, key);
+            this.cachedSizes.set(key.key, blob.size);
+            this.removedKeys.delete(key.key);
+            return url;
+        }
+        catch (err) {
+            this.report(err, key, 'load');
+            return null;
+        }
+    }
+    /** Background path: only touches anything when the remote copy actually differs. */
+    async revalidate(key, publish) {
+        if (this.revalidating.has(key.key))
+            return;
+        this.revalidating.add(key.key);
+        try {
+            const blob = await this.remote.load(key.id, key);
+            // The load-bearing rule: a remote miss must NEVER evict a local capture.
+            // Offline, 404, and "not synced yet" all land here.
+            if (!blob || blob.size === 0)
+                return;
+            // remove() ran while this read was in flight — don't resurrect what the
+            // caller just deleted.
+            if (this.removedKeys.has(key.key))
+                return;
+            if (this.cachedSizes.get(key.key) === blob.size)
+                return;
+            const url = await this.local.save(blob, key);
+            this.cachedSizes.set(key.key, blob.size);
+            if (publish)
+                this.service?.publish(key.id, url, { variant: key.variant });
+        }
+        catch (err) {
+            // A rejected read leaves the local copy in place — offline still works.
+            this.report(err, key, 'load');
+        }
+        finally {
+            this.revalidating.delete(key.key);
+        }
+    }
+    report(err, key, op) {
+        if (this.options.onError)
+            this.options.onError(err, key, op);
+        else
+            console.warn(`CachedSnapshotStorage: ${op} failed for "${key.key}"`, err);
+    }
+}

package/dist/encode.d.ts

@@ -0,0 +1,19 @@
+export type SnapshotImageType = `image/${'png' | 'webp' | 'jpeg'}`;
+export interface EncodeOptions {
+    /** Output format. Defaults to `image/webp`, falling back to `image/png` where WebP encoding isn't available. */
+    type?: SnapshotImageType;
+    /** Lossy quality, 0-1. Ignored for `image/png`. Default 0.8. */
+    quality?: number;
+    /** Longest edge in px — downscales to fit, never upscales. */
+    maxEdge?: number;
+}
+/**
+ * Re-encodes (and optionally downscales) a snapshot blob off the layout path,
+ * via `createImageBitmap` + `OffscreenCanvas` — so a full-resolution PNG from
+ * html2canvas becomes a small WebP suitable for a thumbnail or an upload.
+ *
+ * Deliberately never throws: a browser missing either API, a decode failure, or
+ * an encoder that doesn't know the requested type all resolve with the *input*
+ * blob. A thumbnail that's bigger than intended beats no thumbnail at all.
+ */
+export declare function encodeSnapshot(blob: Blob, opts?: EncodeOptions): Promise<Blob>;

package/dist/encode.js

@@ -0,0 +1,56 @@
+const DEFAULT_TYPE = 'image/webp';
+const DEFAULT_QUALITY = 0.8;
+function targetSize(width, height, maxEdge) {
+    if (!maxEdge || maxEdge <= 0)
+        return { width, height };
+    const longest = Math.max(width, height);
+    if (longest <= maxEdge)
+        return { width, height };
+    const ratio = maxEdge / longest;
+    return { width: Math.max(1, Math.round(width * ratio)), height: Math.max(1, Math.round(height * ratio)) };
+}
+/**
+ * Re-encodes (and optionally downscales) a snapshot blob off the layout path,
+ * via `createImageBitmap` + `OffscreenCanvas` — so a full-resolution PNG from
+ * html2canvas becomes a small WebP suitable for a thumbnail or an upload.
+ *
+ * Deliberately never throws: a browser missing either API, a decode failure, or
+ * an encoder that doesn't know the requested type all resolve with the *input*
+ * blob. A thumbnail that's bigger than intended beats no thumbnail at all.
+ */
+export async function encodeSnapshot(blob, opts = {}) {
+    const type = opts.type ?? DEFAULT_TYPE;
+    const quality = opts.quality ?? DEFAULT_QUALITY;
+    if (typeof createImageBitmap !== 'function' || typeof OffscreenCanvas !== 'function')
+        return blob;
+    let bitmap;
+    try {
+        bitmap = await createImageBitmap(blob);
+        const { width, height } = targetSize(bitmap.width, bitmap.height, opts.maxEdge);
+        // Nothing to do: same format already, no downscale needed, and either quality
+        // doesn't apply (png) or the caller didn't ask for a specific one — we can't
+        // tell what quality the existing blob was actually encoded at, so a caller
+        // who *did* specify one always gets a fresh encode at that quality.
+        const sameDimsAndType = width === bitmap.width && height === bitmap.height && blob.type === type;
+        if (sameDimsAndType && (type === 'image/png' || opts.quality === undefined))
+            return blob;
+        const canvas = new OffscreenCanvas(width, height);
+        const ctx = canvas.getContext('2d');
+        if (!ctx)
+            return blob;
+        ctx.drawImage(bitmap, 0, 0, width, height);
+        let encoded = await canvas.convertToBlob({ type, quality });
+        // Chrome/Safari silently fall back to image/png for a type they can't
+        // encode, so trust the *result's* type rather than a feature probe.
+        if (encoded.type !== type && type !== 'image/png') {
+            encoded = await canvas.convertToBlob({ type: 'image/png' });
+        }
+        return encoded;
+    }
+    catch {
+        return blob;
+    }
+    finally {
+        bitmap?.close();
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Typed errors, so a caller can branch on *why* a capture failed instead of
+ * string-matching a prose message. Every rejection thrown by the library
+ * extends `SnapshotError`.
+ */
+export declare class SnapshotError extends Error {
+    constructor(message: string);
+}
+/** The element passed to `capture()` was removed from the document before the render started. */
+export declare class SnapshotDetachedElementError extends SnapshotError {
+    readonly id: string;
+    constructor(id: string);
+}
+/** html2canvas rejected while rendering the element (e.g. "Unable to find element in cloned iframe"). */
+export declare class SnapshotRenderError extends SnapshotError {
+    readonly id: string;
+    readonly cause: unknown;
+    constructor(id: string, cause: unknown);
+}
+/** `canvas.toBlob()` resolved null — tainted (cross-origin) content, or a zero-size element. */
+export declare class SnapshotTaintedCanvasError extends SnapshotError {
+    readonly id: string;
+    constructor(id: string);
+}
+/** A blob exceeded a configured `maxBytes` cap (see `CachedSnapshotStorage`). */
+export declare class SnapshotTooLargeError extends SnapshotError {
+    readonly size: number;
+    readonly maxBytes: number;
+    constructor(size: number, maxBytes: number);
+}

package/dist/errors.js

@@ -0,0 +1,44 @@
+/**
+ * Typed errors, so a caller can branch on *why* a capture failed instead of
+ * string-matching a prose message. Every rejection thrown by the library
+ * extends `SnapshotError`.
+ */
+export class SnapshotError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** The element passed to `capture()` was removed from the document before the render started. */
+export class SnapshotDetachedElementError extends SnapshotError {
+    constructor(id) {
+        super(`SnapshotService: the element for "${id}" is not connected to the document — ` +
+            'it was removed (e.g. the view was destroyed) before the capture could run.');
+        this.id = id;
+    }
+}
+/** html2canvas rejected while rendering the element (e.g. "Unable to find element in cloned iframe"). */
+export class SnapshotRenderError extends SnapshotError {
+    constructor(id, cause) {
+        super(`SnapshotService: html2canvas failed while capturing "${id}": ` +
+            (cause instanceof Error ? cause.message : String(cause)));
+        this.id = id;
+        this.cause = cause;
+    }
+}
+/** `canvas.toBlob()` resolved null — tainted (cross-origin) content, or a zero-size element. */
+export class SnapshotTaintedCanvasError extends SnapshotError {
+    constructor(id) {
+        super(`SnapshotService: canvas.toBlob() returned null while capturing "${id}" — the element likely ` +
+            'contains tainted (cross-origin, no CORS headers) content, or has zero size.');
+        this.id = id;
+    }
+}
+/** A blob exceeded a configured `maxBytes` cap (see `CachedSnapshotStorage`). */
+export class SnapshotTooLargeError extends SnapshotError {
+    constructor(size, maxBytes) {
+        super(`Snapshot is ${size} bytes, above the configured maxBytes of ${maxBytes} — not uploaded.`);
+        this.size = size;
+        this.maxBytes = maxBytes;
+    }
+}

package/dist/index.d.ts

@@ -1,3 +1,6 @@
 export * from './snapshot-nav-list';
 export * from './snapshot-service';
 export * from './snapshot-storage';
+export * from './cached-snapshot-storage';
+export * from './encode';
+export * from './errors';

package/dist/index.js

@@ -1,3 +1,6 @@
 export * from './snapshot-nav-list';
 export * from './snapshot-service';
 export * from './snapshot-storage';
+export * from './cached-snapshot-storage';
+export * from './encode';
+export * from './errors';

package/dist/snapshot-nav-list.d.ts

@@ -1,14 +1,21 @@
 import { LitElement } from 'lit';
 import type { SnapshotService } from './snapshot-service';
-export interface NavItem {
+export interface NavItem<T = unknown> {
+    /** The snapshot id — a plain domain id. Anything else the consumer needs belongs in `data`. */
     id: string;
     label: string;
     /** A plain-text glyph (e.g. an emoji), or markup — a string starting with `<` renders as raw HTML/SVG instead of text, so a consumer can pass its own icon (e.g. `<svg>...</svg>`). Only the placeholder frame shown before a card's first capture. */
     icon?: string;
-    route?: string;
     description?: string;
+    /** Arbitrary consumer payload — echoed back verbatim on `nav-select` / `nav-edit`, so no lookup-by-id is needed in the handler. */
+    data?: T;
+    /** Per-item override of the component-level `editable` — for per-row rights. */
+    editable?: boolean;
+    /** @deprecated Put the route in `data` and read it off the emitted item. Kept for one release. */
+    route?: string;
 }
-export type SnapshotNavListVariant = 'list' | 'icon-only' | 'card';
+/** `'icon-only'` is the old name for `'tile'`; it still works and normalises to `'tile'`. */
+export type SnapshotNavListVariant = 'list' | 'tile' | 'card' | 'icon-only';
 /** `overlay` floats the edit button over the thumbnail (top-right, reveals on hover); `meta` pins it to the right edge of the title's line (description below), always visible. */
 export type SnapshotNavListEditButtonPosition = 'overlay' | 'meta';
 /**
@@ -20,8 +27,17 @@ export type SnapshotNavListEditButtonPosition = 'overlay' | 'meta';
 export declare class SnapshotNavList extends LitElement {
     static styles: import("lit").CSSResult;
     items: NavItem[];
+    /** `card` by default — a framed preview with title/description underneath. `tile` is the compact contact-sheet grid, `list` a sidebar row. */
     variant: SnapshotNavListVariant;
-    /** icon-only tile overlay: tint behind the title so it stays legible over any image. Transparent by default — opt into a scrim explicitly. */
+    /**
+     * Second dimension on every id — typically the active theme, so a light and a
+     * dark capture of the same view are stored (and read) separately. Passed
+     * straight through to `SnapshotService.get()` as `variant`.
+     */
+    variantKey?: string;
+    /** Lets the host itself scroll (see `--snapshot-nav-list-max-height`) instead of growing unbounded. */
+    scrollable: boolean;
+    /** tile overlay: tint behind the title so it stays legible over any image. Transparent by default — opt into a scrim explicitly. */
     overlayTint: 'dark' | 'light' | 'none';
     /** caption background tint strength, 0-1 */
     textOverlayOpacity: number;
@@ -29,11 +45,11 @@ export declare class SnapshotNavList extends LitElement {
     imageOverlayOpacity: number;
     /** backdrop blur behind the title, in px */
     overlayBlur: number;
-    /** icon-only only: 'bottom' is the caption strip (default), 'center' centers a larger title. */
+    /** tile only: 'bottom' is the caption strip (default), 'center' centers a larger title. */
     labelPosition: 'bottom' | 'center';
     /** Defaults to the shared singleton — set your own instance (e.g. a namespaced or custom-storage SnapshotService) per <snapshot-nav-list> if needed. */
     snapshotService: SnapshotService;
-    /** Shows an edit button per card. Off by default — clicking it fires `nav-edit` instead of `nav-select`; the host decides what "edit" means (e.g. open its own dialog component). */
+    /** Shows an edit button per card. Off by default — clicking it fires `nav-edit` instead of `nav-select`; the host decides what "edit" means (e.g. open its own dialog component). Overridable per row via `NavItem.editable`. */
     editable: boolean;
     /** Where the edit button sits: `overlay` (default) floats it over the thumbnail; `meta` pins it to the right edge of the title row, with the description below. Ignored by the icon-only variant, whose caption is itself an overlay. */
     editButtonPosition: SnapshotNavListEditButtonPosition;
@@ -41,26 +57,47 @@ export declare class SnapshotNavList extends LitElement {
     editIcon: string;
     private thumbs;
     private loadingIds;
-    /** In-flight dedup guard, separate from `loadingIds` (which is only for spinner display) so a repeat `loadThumb` call for an id already being fetched is a no-op. */
+    /**
+     * In-flight dedup guard, separate from `loadingIds` (which is only for
+     * spinner display) so a repeat `loadThumb` call for an id already being
+     * fetched is a no-op. Keyed by `${variant}\0${id}` — not just `id` — so a
+     * `variantKey` switch mid-flight doesn't have the new variant's fetch
+     * silently dropped because the *previous* variant's id is still marked
+     * in-flight.
+     */
     private fetchingIds;
     private unsubscribe?;
+    private fetchKey;
     private subscribeToService;
     connectedCallback(): void;
     disconnectedCallback(): void;
     willUpdate(changed: Map<string, unknown>): void;
     updated(changed: Map<string, unknown>): void;
-    private loadThumb;
+    /**
+     * One batched read for the whole list — `getMany()` collapses to a single
+     * query/round-trip on a storage that implements `loadMany`, instead of one
+     * per row. `fetchingIds` still guards per id, so an `items` reassignment
+     * mid-flight doesn't re-request what's already coming.
+     */
+    private loadThumbs;
     /** image scrim: blur + its own (usually 0) tint strength — independent of the caption's. */
     private get imageOverlayStyle();
     /** caption background: tint (to pop the text) + the same blur. */
     private get metaStyle();
     private select;
     private edit;
+    private isEditable;
     private renderEditButton;
     render(): import("lit-html").TemplateResult<1>;
 }
+/** Detail type of both `nav-select` and `nav-edit` — the clicked item itself. */
+export type SnapshotNavEvent<T = unknown> = CustomEvent<NavItem<T>>;
 declare global {
     interface HTMLElementTagNameMap {
         'snapshot-nav-list': SnapshotNavList;
     }
+    interface HTMLElementEventMap {
+        'nav-select': SnapshotNavEvent;
+        'nav-edit': SnapshotNavEvent;
+    }
 }