@spooky-sync/client-solid 0.0.1-canary.162 → 0.0.1-canary.163

package/skills/sp00ky-solid/references/file-hooks.md

@@ -64,11 +64,18 @@ Reactively download a file from a bucket. Re-fetches when the path changes.
 ### Signatures
 
 ```typescript
+interface UseDownloadFileOptions {
+  cache?: boolean;                    // default true — false disables every layer
+  persist?: boolean;                  // default true — keep bytes in OPFS
+  pin?: boolean;                      // exempt from pressure eviction
+  revalidate?: 'never' | 'head';      // default 'never' (paths are immutable)
+}
+
 // Context-based
 useDownloadFile<S>(
   bucketName: BucketNames<S>,
   path: Accessor<string | null | undefined>,
-  options?: { cache?: boolean },
+  options?: UseDownloadFileOptions,
 ): UseDownloadFileResult;
 
 // Explicit db
@@ -76,7 +83,7 @@ useDownloadFile<S>(
   db: SyncedDb<S>,
   bucketName: BucketNames<S>,
   path: Accessor<string | null | undefined>,
-  options?: { cache?: boolean },
+  options?: UseDownloadFileOptions,
 ): UseDownloadFileResult;
 ```
 
@@ -87,13 +94,35 @@ interface UseDownloadFileResult {
   url: Accessor<string | null>;     // Object URL for the file
   isLoading: Accessor<boolean>;
   error: Accessor<Error | null>;
-  refetch: () => void;              // Force re-download (evicts cache)
+  refetch: () => void;              // Force re-download, bypassing every layer
 }
 ```
 
 ### Caching
 
-By default, downloads are cached by `bucket:path` key with reference counting. Object URLs are revoked when no component references them. Set `cache: false` to disable.
+Three layers, checked in order:
+
+1. **Object URLs**, refcounted per `bucket:path` and shared between components. Revoked once the last holder releases and the entry ages out of a 32-entry hot window.
+2. **OPFS**, under `sp00ky-blobs/<bucketId>/<bucket>/<path>`. Survives reload, works offline, and is namespaced per signed-in user.
+3. **The bucket**, over the sync WebSocket.
+
+Nothing expires on a timer — an image whose row is still cached locally has to stay viewable offline. Bytes are dropped only when the app invalidates the path (`bucket.put`/`bucket.delete` do this automatically), when boot reconcile finds no file behind a row, or when the cache exceeds its byte budget, in which case the least-recently-used unpinned entries that nothing is rendering go first.
+
+Configure with `blobCache: { enabled, maxBytes, clearOnSignOut }` on the client. The budget defaults to `min(512 MB, quota × 0.25)`. Inspect live numbers in the DevTools Storage tab under "Bucket file cache".
+
+`persist: false` keeps the in-tab sharing but writes nothing durable. `cache: false` gives each hook instance a private URL fetched fresh and revoked on unmount.
+
+A bucket path is treated as immutable, which is how paths are normally written (`crypto.randomUUID() + ext`). If your app overwrites a path in place from another device, pass `revalidate: 'head'` — it spends a remote `head()` to compare sizes before trusting the cached copy, and keeps the cached copy when that call fails so going offline never blanks an image.
+
+### Pinning and prefetching
+
+```tsx
+const bucket = db.bucket('avatars');
+await bucket.prefetch(paths);   // warm the cache for offline use
+bucket.pin('logo.png');         // never evicted under pressure
+bucket.unpin('logo.png');
+await bucket.evict('old.png');  // drop locally, leave the remote file alone
+```
 
 ### Example
 

package/src/lib/use-download-file.ts

@@ -1,10 +1,31 @@
 import { createSignal, createEffect, onCleanup, type Accessor } from 'solid-js';
 import type { SchemaStructure, BucketNames } from '@spooky-sync/query-builder';
+import type { BlobUrlLease } from '@spooky-sync/core';
 import type { SyncedDb } from '../index';
 import { useDb } from './context';
 
 export interface UseDownloadFileOptions {
+  /**
+   * Master switch, default `true`. `false` gives every hook instance its own
+   * private object URL fetched fresh from the bucket and revoked on unmount —
+   * no sharing, no persistence, no reuse.
+   */
   cache?: boolean;
+  /**
+   * Keep the bytes in OPFS so they survive a reload and are available offline.
+   * Default `true`. Turn off for one-shot or sensitive files; the in-tab object
+   * URL is still shared between components rendering the same path.
+   */
+  persist?: boolean;
+  /** Exempt this file from pressure eviction. Pinned bytes never expire. */
+  pin?: boolean;
+  /**
+   * `'never'` (default) treats a bucket path as immutable, which is how paths
+   * are written (`crypto.randomUUID() + ext`). `'head'` spends a remote `head()`
+   * to compare sizes before trusting the cached copy — for paths the app
+   * overwrites in place.
+   */
+  revalidate?: 'never' | 'head';
 }
 
 export interface UseDownloadFileResult {
@@ -14,28 +35,6 @@ export interface UseDownloadFileResult {
   refetch: () => void;
 }
 
-interface CacheEntry {
-  url: string;
-  refCount: number;
-}
-
-const downloadCache = new Map<string, CacheEntry>();
-const inflightRequests = new Map<string, Promise<string | null>>();
-
-function cacheKey(bucket: string, path: string): string {
-  return `${bucket}:${path}`;
-}
-
-function releaseEntry(key: string): void {
-  const entry = downloadCache.get(key);
-  if (!entry) return;
-  entry.refCount--;
-  if (entry.refCount <= 0) {
-    URL.revokeObjectURL(entry.url);
-    downloadCache.delete(key);
-  }
-}
-
 export function useDownloadFile<S extends SchemaStructure>(
   bucketName: BucketNames<S>,
   path: Accessor<string | null | undefined>,
@@ -76,68 +75,19 @@ export function useDownloadFile<S extends SchemaStructure>(
   const [isLoading, setIsLoading] = createSignal(false);
   const [error, setError] = createSignal<Error | null>(null);
 
-  let currentKey: string | null = null;
+  // Exactly one of these is held at a time: a refcounted lease on the shared
+  // cache entry, or a private URL this instance minted and must revoke itself.
+  let lease: BlobUrlLease | null = null;
   let privateUrl: string | null = null;
+
   const [refetchSignal, setRefetchSignal] = createSignal(0);
-  const refetchTrigger = () => setRefetchSignal((n) => n + 1);
-
-  async function doDownload(key: string, filePath: string): Promise<string | null> {
-    if (useCache) {
-      // Check cache
-      const cached = downloadCache.get(key);
-      if (cached) {
-        cached.refCount++;
-        currentKey = key;
-        return cached.url;
-      }
-
-      // Check inflight
-      const inflight = inflightRequests.get(key);
-      if (inflight) {
-        const result = await inflight;
-        if (result) {
-          const entry = downloadCache.get(key);
-          if (entry) {
-            entry.refCount++;
-            currentKey = key;
-          }
-        }
-        return result;
-      }
-
-      // Start new download
-      const promise = (async () => {
-        const content = await db.bucket(bucketName).get(filePath);
-        if (!content) return null;
-        const objectUrl = URL.createObjectURL(new Blob([content as BlobPart]));
-        downloadCache.set(key, { url: objectUrl, refCount: 1 });
-        return objectUrl;
-      })();
-
-      inflightRequests.set(key, promise);
-      try {
-        const result = await promise;
-        currentKey = key;
-        return result;
-      } finally {
-        inflightRequests.delete(key);
-      }
-    } else {
-      // No caching — private URL per instance
-      const content = await db.bucket(bucketName).get(filePath);
-      if (!content) return null;
-      const objectUrl = URL.createObjectURL(new Blob([content as BlobPart]));
-      privateUrl = objectUrl;
-      return objectUrl;
-    }
-  }
+  /** Consumed by the next effect run, so `refetch()` bypasses every layer once. */
+  let reloadOnce = false;
 
-  function releaseCurrentEntry() {
-    if (useCache && currentKey) {
-      releaseEntry(currentKey);
-      currentKey = null;
-    }
-    if (!useCache && privateUrl) {
+  function releaseCurrent() {
+    lease?.release();
+    lease = null;
+    if (privateUrl) {
       URL.revokeObjectURL(privateUrl);
       privateUrl = null;
     }
@@ -148,8 +98,7 @@ export function useDownloadFile<S extends SchemaStructure>(
     // Subscribe to refetch signal so effect re-runs
     refetchSignal();
 
-    // Release previous entry
-    releaseCurrentEntry();
+    releaseCurrent();
 
     if (!filePath) {
       setUrl(null);
@@ -158,26 +107,41 @@ export function useDownloadFile<S extends SchemaStructure>(
       return;
     }
 
-    const key = cacheKey(bucketName as string, filePath);
-
-    // Synchronous cache hit
-    if (useCache) {
-      const cached = downloadCache.get(key);
-      if (cached) {
-        cached.refCount++;
-        currentKey = key;
-        setUrl(cached.url);
-        setIsLoading(false);
-        setError(null);
-        return;
-      }
-    }
+    const reload = reloadOnce;
+    reloadOnce = false;
 
     let cancelled = false;
     setIsLoading(true);
     setError(null);
 
-    doDownload(key, filePath).then(
+    const bucket = db.bucket(bucketName);
+    const resolve = useCache
+      ? bucket
+          .url(filePath, {
+            persist: options.persist !== false,
+            pin: options.pin,
+            revalidate: options.revalidate,
+            reload,
+          })
+          .then((acquired) => {
+            if (!acquired) return null;
+            if (cancelled) {
+              // Unmounted or the path changed mid-flight — hand the reference
+              // straight back, or the entry never drops to zero and its object
+              // URL leaks for the life of the tab.
+              acquired.release();
+              return null;
+            }
+            lease = acquired;
+            return acquired.url;
+          })
+      : bucket.read(filePath, { persist: false, reload: true }).then((blob) => {
+          if (!blob || cancelled) return null;
+          privateUrl = URL.createObjectURL(blob);
+          return privateUrl;
+        });
+
+    resolve.then(
       (result) => {
         if (!cancelled) {
           setUrl(result);
@@ -199,20 +163,12 @@ export function useDownloadFile<S extends SchemaStructure>(
   });
 
   onCleanup(() => {
-    releaseCurrentEntry();
+    releaseCurrent();
   });
 
   const refetch = () => {
-    // Evict current entry from cache before re-triggering
-    if (useCache && currentKey) {
-      const entry = downloadCache.get(currentKey);
-      if (entry) {
-        URL.revokeObjectURL(entry.url);
-        downloadCache.delete(currentKey);
-      }
-      currentKey = null;
-    }
-    refetchTrigger();
+    reloadOnce = true;
+    setRefetchSignal((n) => n + 1);
   };
 
   return { url, isLoading, error, refetch };