@ingcreators/annot-core 0.1.0

package/dist/storage/errors.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Stable discriminator for cross-backend storage error handling.
+ * Mirrors the `StorageError` subclass hierarchy below; callers
+ * that prefer a `switch` over `instanceof` can use `e.code`.
+ */
+export type StorageErrorCode = "conflict" | "not-found" | "permission" | "quota";
+/**
+ * Base for all `StorageProvider`-thrown errors that callers may
+ * want to discriminate. Generic IO / network / parse errors keep
+ * throwing plain `Error` and are NOT captured by `instanceof
+ * StorageError`.
+ *
+ * Subclasses set `name` / `code` / `path` themselves. Construct via
+ * the subclasses (`StorageConflictError`, `StorageNotFoundError`,
+ * `StoragePermissionError`, `StorageQuotaError`) — callers and
+ * backends never instantiate `StorageError` directly.
+ */
+export declare class StorageError extends Error {
+    /** Discriminator. Set by each subclass to its matching code. */
+    readonly code: StorageErrorCode;
+    /** Path the failed operation was attempted on (image or folder). */
+    readonly path: string;
+    constructor(code: StorageErrorCode, path: string, message: string);
+}
+/**
+ * Destination path collides with an existing image or folder, and
+ * the operation does NOT auto-uniquify. Thrown by `createFolder`
+ * (duplicate name), `renameImage` / `renameFolder` / `moveFolder`
+ * (caller-picked name collides). `saveImage` and `moveImage`
+ * auto-uniquify and never throw this.
+ */
+export declare class StorageConflictError extends StorageError {
+    constructor(path: string, message?: string);
+}
+/**
+ * Source path for a `rename*` / `move*` no longer exists. Read
+ * methods (`getImage`, `getFolder`, `listImages`, `listFolders`,
+ * `getBreadcrumb`) and idempotent mutations (`updateImage`,
+ * `deleteImage`, `deleteFolder`) return `undefined` / `[]` /
+ * silently instead of throwing this.
+ */
+export declare class StorageNotFoundError extends StorageError {
+    constructor(path: string, message?: string);
+}
+/**
+ * Backend rejected the operation for auth / ACL reasons — expired
+ * GitHub token, revoked Drive scope, FSA permission lapse, etc.
+ * Any mutating `StorageProvider` method may throw this.
+ */
+export declare class StoragePermissionError extends StorageError {
+    constructor(path: string, message?: string);
+}
+/**
+ * Backend reports out-of-space or out-of-quota. Any mutating
+ * `StorageProvider` method may throw this.
+ */
+export declare class StorageQuotaError extends StorageError {
+    constructor(path: string, message?: string);
+}

package/dist/storage/index.d.ts

@@ -0,0 +1,6 @@
+export * from './errors.js';
+export * from './metadata-cache.js';
+export * from './path.js';
+export * from './thumbnail.js';
+export * from './thumbnail-cache.js';
+export * from './types.js';

package/dist/storage/metadata-cache.d.ts

@@ -0,0 +1,231 @@
+import { DocumentRecord, ImageRecord, StorageProvider } from './types.js';
+/**
+ * What kind of leaf entity a `ListingEntry` represents. `folder`
+ * means "this child path is a subfolder of the listing's
+ * `folderPath`"; consumers walk it for the folder tree, not for
+ * `getImage` / `getDocument` lookups.
+ */
+export type ListingEntryKind = "image" | "document" | "folder";
+/**
+ * One entry in a folder's listing. `path` is the full path (not the
+ * leaf name); `version` is the opaque per-backend version string the
+ * cache uses to detect external mutation (`mtime` for Device/Desktop,
+ * blob SHA for GitHub, `modifiedTime` for Drive).
+ */
+export interface ListingEntry {
+    path: string;
+    version: string;
+    kind: ListingEntryKind;
+}
+/**
+ * Path → cached record + listing + per-namespace metadata store with
+ * version-gated hits. Lifecycle is shared across every opt-in
+ * `StorageProvider`; the providers themselves talk to this directly
+ * (unlike thumbnails, where a manager sits between the provider and
+ * the cache — metadata is intrinsic to `listImages` rather than a
+ * side-channel).
+ *
+ * Methods are organized by concern:
+ *
+ *   - **Records**: per-path `ImageRecord` / `DocumentRecord` caches,
+ *     version-gated so a stale entry is invisible to readers.
+ *   - **Listing**: per-folder `ListingEntry[]` cache, used by
+ *     `listImages` / `listDocuments` / `listFolders` so the store
+ *     can return "what we know" before deciding whether to revalidate
+ *     against the backend.
+ *   - **Namespace meta**: per-namespace single-value KV store. Used
+ *     for GitHub `branchHead` SHA tracking and Drive
+ *     `changesPageToken` integration.
+ *   - **Backend ID**: per-namespace bidirectional path ↔
+ *     backend-internal-id map. Used by ID-based backends (Drive)
+ *     where the change-tracking API speaks fileIds, not paths.
+ *   - **Bulk operations**: cross-namespace migrations (rename,
+ *     move-folder prefix rewrite) consolidated in one place rather
+ *     than reimplemented per backend.
+ *   - **Invalidation**: precise (`invalidatePath`) and broad
+ *     (`invalidatePrefix`) eviction, used on `resync()` /
+ *     `forceRefresh()` paths.
+ */
+export interface MetadataCache {
+    /**
+     * Returns the cached image record IFF its stored version matches
+     * `version`. Version mismatch returns `undefined` without
+     * disturbing the stored row — in a multi-tab world a peer may
+     * have written a NEWER version we don't yet know about, and
+     * silently evicting it here would discard valid data. Stale
+     * entries age out via LRU or are overwritten by the next `put`.
+     * `lastAccessedAt` is updated on hit so LRU eviction respects
+     * recent reads.
+     */
+    getImage(ns: string, path: string, version: string): Promise<ImageRecord | undefined>;
+    /**
+     * Write-or-overwrite at `(ns, path)`. The `version` field becomes
+     * the new gate for future `getImage` calls. Implementations
+     * should handle quota exhaustion internally (one self-eviction
+     * sweep + retry, `clearAll` as last resort) and only throw
+     * `MetadataCacheQuotaError` when even that fails.
+     */
+    putImage(ns: string, path: string, version: string, rec: ImageRecord): Promise<void>;
+    /** Document equivalent of {@link getImage}. */
+    getDocument(ns: string, path: string, version: string): Promise<DocumentRecord | undefined>;
+    /** Document equivalent of {@link putImage}. */
+    putDocument(ns: string, path: string, version: string, rec: DocumentRecord): Promise<void>;
+    /**
+     * Returns the cached listing for `folderPath` under `ns`, or
+     * `undefined` if no listing has been recorded. Listings are
+     * **not** version-gated at this layer — callers compare individual
+     * entry versions to decide whether to revalidate per-entry.
+     */
+    getListing(ns: string, folderPath: string): Promise<ListingEntry[] | undefined>;
+    /**
+     * Replace the cached listing at `(ns, folderPath)` with `entries`.
+     * Used on cold-fetch or invalidate-all paths. Incremental updates
+     * (single add / version bump / remove) should prefer the
+     * targeted helpers below.
+     */
+    putListing(ns: string, folderPath: string, entries: ListingEntry[]): Promise<void>;
+    /**
+     * Add `entry` to the listing for `(ns, folderPath)`, or replace
+     * the existing entry with the same `path`. No-op if no listing
+     * has been recorded for the folder.
+     */
+    upsertListingEntry(ns: string, folderPath: string, entry: ListingEntry): Promise<void>;
+    /**
+     * Remove the entry matching `path` from the listing for
+     * `(ns, folderPath)`. No-op if no listing or no matching entry.
+     */
+    removeListingEntry(ns: string, folderPath: string, path: string): Promise<void>;
+    /**
+     * Read a single per-namespace value. Returns `undefined` when not
+     * set. Used today for:
+     *
+     *   - GitHubStore's `branchHead` (current commit SHA of the
+     *     tracked branch). On `init()` the store compares the live
+     *     HEAD against this value; on match it skips the recursive
+     *     tree fetch entirely.
+     *   - GoogleDriveStore's `changesPageToken` (Drive Changes API
+     *     resume token). On `init()` / `resync()` the store reads
+     *     this token, applies changes since, advances the token.
+     *
+     * Treated as opaque strings by the cache.
+     */
+    getNamespaceMeta(ns: string, key: string): Promise<string | undefined>;
+    /** Write-or-overwrite a per-namespace value. */
+    putNamespaceMeta(ns: string, key: string, value: string): Promise<void>;
+    /** Remove a per-namespace value. */
+    deleteNamespaceMeta(ns: string, key: string): Promise<void>;
+    /**
+     * Record the path ↔ backend-internal-id mapping. Used by ID-based
+     * backends (Drive's fileId, future S3 / API-keyed stores) where
+     * the change-tracking API speaks IDs, not paths. The cache
+     * maintains both directions so `getBackendIdByPath` and
+     * `getPathByBackendId` are constant-time.
+     */
+    setBackendId(ns: string, path: string, backendId: string): Promise<void>;
+    /** Forward lookup: path → backend ID. */
+    getBackendIdByPath(ns: string, path: string): Promise<string | undefined>;
+    /** Reverse lookup: backend ID → path. */
+    getPathByBackendId(ns: string, backendId: string): Promise<string | undefined>;
+    /**
+     * Move every cached artefact (record + listing entry + backend
+     * ID) from `oldPath` to `newPath` within the namespace.
+     * Generalizes the per-store rename/move handling that
+     * `GitHubBlobCache.migrateEntry` did for GitHubStore alone.
+     * Listing entries are updated in BOTH the source and destination
+     * folder's listings (remove from old, upsert into new).
+     */
+    migrateEntry(ns: string, oldPath: string, newPath: string): Promise<void>;
+    /**
+     * Bulk-rewrite every cached artefact whose path starts with
+     * `oldPrefix` to start with `newPrefix` instead. Generalizes
+     * `GitHubBlobCache.rewriteEntriesForPrefix`. Used by folder
+     * rename / folder move operations.
+     */
+    rewriteEntriesForPrefix(ns: string, oldPrefix: string, newPrefix: string): Promise<void>;
+    /** Targeted eviction: drop the record at `(ns, path)`. */
+    invalidatePath(ns: string, path: string): Promise<void>;
+    /**
+     * Drop every cached artefact whose key starts with `prefix`.
+     * Used by:
+     *   - `StorageProvider.forceRefresh()` to invalidate a whole
+     *     instance's namespace.
+     *   - GitHubStore's branch-HEAD-mismatch handling (v1: drop the
+     *     whole namespace, re-fetch from scratch).
+     *   - Plugin uninstall — the host fires
+     *     `invalidatePrefix("plugin:<pluginId>:")`.
+     */
+    invalidatePrefix(prefix: string): Promise<void>;
+}
+/**
+ * Base error type implementations may throw out of mutating methods
+ * when their underlying transport fails irrecoverably. Stores that
+ * catch this should fall back to in-memory-only operation —
+ * functionality stays correct for the current session, just not
+ * across reload.
+ */
+export declare class MetadataCacheError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Specific `MetadataCacheError` for quota-exhaustion paths.
+ * Implementations that distinguish quota from other I/O errors
+ * should throw this so the host can render quota-specific UI
+ * ("free up space") rather than the generic fallback.
+ */
+export declare class MetadataCacheQuotaError extends MetadataCacheError {
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Capability interface — opt into the shared metadata cache by
+ * implementing both methods. Stores that don't implement this
+ * continue managing their own metadata internally
+ * (BrowserStore / IDBStore — already IDB-native and don't benefit
+ * from a second cache layer).
+ *
+ * The host wires the cache in at construction time via
+ * `attachMetadataCache(cache)`; the store reads its own namespace
+ * via `metadataNamespace()` so consumers (test helpers, `forceRefresh`
+ * implementations) can derive prefix-invalidation keys.
+ */
+export interface StorageWithMetadataCache {
+    /**
+     * Return the per-instance namespace prefix used to scope this
+     * store's cache entries. Examples:
+     *
+     *   - DeviceStore:        `"device:my-screenshots"` (root folder name)
+     *   - DesktopStore:       `"desktop:default-library"`
+     *   - GitHubStore:        `"github:owner/repo:main"` (owner / repo / branch)
+     *   - GoogleDriveStore:   `"googledrive:<rootFolderId>"`
+     *   - Plugin-registered:  `"plugin:<pluginId>:..."` — the rest of
+     *     the suffix is the plugin's choice; the `plugin:<pluginId>:`
+     *     prefix is enforced by the host at registration time.
+     *
+     * Stable across resync. Implementations MUST NOT bake mutable
+     * state into the namespace (e.g. don't append a "session ID" or
+     * "build hash") — invalidation relies on prefix stability across
+     * sessions.
+     */
+    metadataNamespace(): string;
+    /**
+     * Receive the `MetadataCache` instance from the host at
+     * construction time. After this call, the store may issue cache
+     * operations from any of its public methods.
+     *
+     * Called exactly once per store instance, before any
+     * `StorageProvider` method. Stores that need to perform initial
+     * cache reads (e.g. seeding their in-memory shortcuts from
+     * `getNamespaceMeta`) should do so in `init()`, not here.
+     */
+    attachMetadataCache(cache: MetadataCache): void;
+}
+/**
+ * Capability predicate — narrow a `StorageProvider` to
+ * `StorageProvider & StorageWithMetadataCache` before invoking
+ * the optional methods. Mirrors the `supports*` helpers next to
+ * the other `StorageWith*` interfaces in `./types.ts`.
+ */
+export declare function supportsMetadataCache(store: StorageProvider): store is StorageProvider & StorageWithMetadataCache;

package/dist/storage/path.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Path utilities for filesystem-style storage identifiers.
+ *
+ * Paths are POSIX-style, separated by "/". Never leading or trailing "/".
+ * Root path is "" (empty string). Reserved segments "." and ".." are invalid.
+ */
+/** Empty string represents the root folder. */
+export declare const ROOT_PATH = "";
+/**
+ * Validate a single path segment (folder or filename).
+ * Throws if the name is empty, is "." / "..", or contains reserved characters.
+ */
+export declare function validateName(name: string): void;
+/**
+ * Join a parent path with a single name.
+ * Throws if `name` contains "/".
+ */
+export declare function joinPath(parent: string, name: string): string;
+/** Return the parent folder's path. Root path's parent is "" (root). */
+export declare function getParentPath(path: string): string;
+/** Return the last segment (folder name or filename) from a path. */
+export declare function getFilename(path: string): string;
+/** Split a path into its segments. Returns [] for the root path. */
+export declare function splitPath(path: string): string[];
+/**
+ * Return all ancestor paths from root down to (but not including) `path`.
+ * Example: `ancestorPaths("A/B/C") = ["A", "A/B"]`.
+ */
+export declare function ancestorPaths(path: string): string[];
+/**
+ * Return `true` if `path` is equal to `ancestor` or is nested inside it.
+ * Example: `isDescendantOrSame("A/B/C", "A") === true`.
+ */
+export declare function isDescendantOrSame(path: string, ancestor: string): boolean;
+/**
+ * Split a filename into base + extension. Extension includes the leading ".".
+ * Example: `splitExt("image.tar.gz") = ["image.tar", ".gz"]`.
+ * Files without extension return `[name, ""]`.
+ */
+export declare function splitExt(filename: string): [string, string];
+/**
+ * Return a unique filename within its folder by appending " (2)", " (3)", ...
+ * before the extension. If `desired` is already free, returns it unchanged.
+ */
+export declare function uniquifyFilename(desired: string, exists: (candidate: string) => boolean): string;
+/** Async variant of `uniquifyFilename` for stores that need async existence checks. */
+export declare function uniquifyFilenameAsync(desired: string, exists: (candidate: string) => Promise<boolean>): Promise<string>;
+/** Rewrite a child path when its ancestor folder is renamed/moved. */
+export declare function rewritePathPrefix(path: string, oldPrefix: string, newPrefix: string): string;

package/dist/storage/thumbnail-cache.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Persistent thumbnail cache contract — Tier A, DOM-free.
+ *
+ * Owns a key-versioned key/value store of pre-rendered gallery
+ * thumbnails (`dataUrl` + natural dimensions). Implementations
+ * decide where the bytes live: the first-party
+ * `IndexedDBThumbnailCache` in `@ingcreators/annot-web/storage/
+ * idb-thumbnail-cache` is the canonical browser-side option;
+ * tests / Node hosts can swap in an in-memory mock with the
+ * same surface.
+ *
+ * The unified-thumbnail-cache plan
+ * ([`docs/plans/_done/unified-thumbnail-cache.md`](../../../../docs/plans/_done/unified-thumbnail-cache.md))
+ * lifts the per-store `#ensureThumbnail` lifecycle into a single
+ * host-side `ThumbnailManager` that talks to one `ThumbnailCache`
+ * instance shared across every backend; this file is the Tier A
+ * piece that contract.
+ *
+ * Keys carry a host-reserved namespace prefix matching the
+ * `StorageMode` strings used elsewhere in the app (`browser:` /
+ * `device:` / `github:` / `googledrive:`); plugin-registered
+ * providers must use the `plugin:<pluginId>:` prefix the host
+ * enforces at registration time. See the plan doc for the full
+ * convention.
+ */
+/**
+ * One cached thumbnail. JPEG-encoded `dataUrl` (already base64
+ * via the standard `image-thumbnail.ts` helper) plus the source
+ * image's natural dimensions — needed by the gallery card's
+ * `WxH • date` line so it doesn't have to wait on a separate
+ * decode round-trip after a cache hit.
+ */
+export interface CachedThumbnail {
+    dataUrl: string;
+    width: number;
+    height: number;
+}
+/** One bulk-`get` request — the key plus the version the caller
+ *  considers fresh. Mismatches are evicted, not returned. */
+export interface ThumbnailCacheGetRequest {
+    key: string;
+    expectedVersion: string;
+}
+/**
+ * Key/value store of `CachedThumbnail` entries with version-gated
+ * cache hits. Lifecycle owned by the host-side `ThumbnailManager`;
+ * `StorageProvider` implementations don't talk to this directly,
+ * they expose `thumbnailKey` / `thumbnailVersion` /
+ * `fetchThumbnailSource` and let the manager drive the cache.
+ */
+export interface ThumbnailCache {
+    /**
+     * Returns the cached entry IFF its stored version matches
+     * `expectedVersion`. Stale entries (version mismatch) are
+     * evicted as a side effect of `get` — the next caller sees a
+     * cold miss. `lastAccessedAt` is updated on hit so LRU
+     * eviction respects recent reads.
+     */
+    get(key: string, expectedVersion: string): Promise<CachedThumbnail | undefined>;
+    /**
+     * Bulk get — single transaction instead of one per record.
+     * Used by `ThumbnailManager.attach` against a `listImages`
+     * result so cold listings of a populated gallery don't fan
+     * out into N IDB round-trips.
+     *
+     * The returned `Map` keys are the request keys (so callers
+     * can correlate). Misses are simply absent.
+     */
+    getMany(requests: ThumbnailCacheGetRequest[]): Promise<Map<string, CachedThumbnail>>;
+    /**
+     * Write or overwrite at `key`. Updates the entry's
+     * `lastAccessedAt`. Implementations should handle quota
+     * exhaustion internally (one self-eviction sweep + retry,
+     * `clearAll` as last resort) and only throw
+     * `ThumbnailCacheQuotaError` when even that fails.
+     */
+    set(key: string, version: string, value: CachedThumbnail): Promise<void>;
+    /** Evict by exact key. */
+    delete(key: string): Promise<void>;
+    /**
+     * Drop every entry whose key starts with `prefix`. Used by:
+     *   - `StorageProvider.resync()` to invalidate a whole instance's
+     *     namespace without enumerating individual keys.
+     *   - Plugin uninstall — the host fires
+     *     `deletePrefix("plugin:<pluginId>:")`.
+     */
+    deletePrefix(prefix: string): Promise<void>;
+    /** Quota-recovery hatch. Drops everything. */
+    clearAll(): Promise<void>;
+}
+/**
+ * Base error type implementations may throw out of `set` once
+ * eviction + retry both fail. `ThumbnailManager` swallows this
+ * and falls back to in-memory only — the gallery still gets the
+ * thumbnail for the current session, just not across reload.
+ */
+export declare class ThumbnailCacheError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Specific `ThumbnailCacheError` for quota-exhaustion paths.
+ *  Implementations that distinguish quota from other I/O errors
+ *  should throw this so callers can apply quota-specific UI
+ *  ("free up space") rather than the generic fallback. */
+export declare class ThumbnailCacheQuotaError extends ThumbnailCacheError {
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}

package/dist/storage/thumbnail.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared thumbnail rendering helper.
+ *
+ * The gallery card is a fixed 16:9 tile. Scaling a short/wide source image
+ * up to fill that tile (as `object-fit: cover` would do) makes the image
+ * blurry. Instead, every storage provider's `generateThumbnail()` draws
+ * onto a fixed-aspect (16:9) canvas with the following rules:
+ *
+ *   - Never upscale. If the source is smaller than the canvas, it stays
+ *     at natural size and the gaps are filled with the `bgColor`.
+ *   - For source wider than 16:9 (or exactly 16:9): fit width,
+ *     letterbox vertically when shorter than the canvas height.
+ *   - For source taller than 16:9 (portrait screenshots, scrollshots):
+ *     fit width, take only the top portion so the canvas shows the
+ *     "head" of the page — matching typical screenshot gallery UX.
+ *
+ * Works with both `HTMLCanvasElement` (main-thread web) and
+ * `OffscreenCanvas` (service worker / fs-store). Caller passes in the
+ * source's natural width/height so we don't assume an `HTMLImageElement`.
+ */
+export interface ThumbCanvasLike {
+    width: number;
+    height: number;
+}
+export type ThumbImageSource = HTMLImageElement | CanvasImageSource;
+/**
+ * Configure `canvas` size, clear the background, and draw `source` onto it
+ * following the rules above. The canvas ends up exactly `targetW × targetH`
+ * where targetW = maxWidth and targetH = round(targetW * 9/16).
+ */
+export declare function drawToThumbCanvas(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, canvas: ThumbCanvasLike, source: ThumbImageSource, srcW: number, srcH: number, maxWidth?: number, bgColor?: string): void;