@spooky-sync/client-solid 0.0.1-canary.33 → 0.0.1-canary.331

package/src/lib/create-preload.ts

@@ -0,0 +1,112 @@
+import type {
+  ColumnSchema,
+  FinalQuery,
+  SchemaStructure,
+  TableNames,
+} from '@spooky-sync/query-builder';
+import { createEffect, useContext } from 'solid-js';
+import { SyncedDb } from '..';
+import type { Sp00kyQueryResultPromise, PreloadOptions as CorePreloadOptions } from '@spooky-sync/core';
+import { Sp00kyContext } from './context';
+
+type PreloadArg<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends { columns: Record<string, ColumnSchema> },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+> =
+  | FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise>
+  | (() =>
+      | FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise>
+      | null
+      | undefined);
+
+type PreloadOptions = CorePreloadOptions & {
+  /** Only preload while this returns true (defaults to always). */
+  enabled?: () => boolean;
+};
+
+// Overload: context-based (no explicit db)
+export function createPreload<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends { columns: Record<string, ColumnSchema> },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+>(
+  finalQuery: PreloadArg<S, TableName, T, RelatedFields, IsOne>,
+  options?: PreloadOptions,
+): void;
+
+// Overload: explicit db
+export function createPreload<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends { columns: Record<string, ColumnSchema> },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+>(
+  db: SyncedDb<S>,
+  finalQuery: PreloadArg<S, TableName, T, RelatedFields, IsOne>,
+  options?: PreloadOptions,
+): void;
+
+/**
+ * Reactive, fire-and-forget prewarm. Resolves the query (calling it if it's a
+ * function so it tracks reactive deps), dedupes on the query's stable identity
+ * hash, and registers it via `db.preload`: a live query nobody subscribes to,
+ * evicted a ttl after it was registered unless a view mounts it first. Nothing
+ * to clean up here.
+ *
+ * Typical use: inside a list row, preload the detail query the user is likely
+ * to open next, so navigation paints from cache instead of the network.
+ */
+export function createPreload<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends { columns: Record<string, ColumnSchema> },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+>(
+  dbOrQuery: SyncedDb<S> | PreloadArg<S, TableName, T, RelatedFields, IsOne>,
+  queryOrOptions?: PreloadArg<S, TableName, T, RelatedFields, IsOne> | PreloadOptions,
+  maybeOptions?: PreloadOptions,
+): void {
+  let db: SyncedDb<S>;
+  let finalQuery: PreloadArg<S, TableName, T, RelatedFields, IsOne>;
+  let options: PreloadOptions | undefined;
+
+  if (dbOrQuery instanceof SyncedDb) {
+    db = dbOrQuery;
+    finalQuery = queryOrOptions as PreloadArg<S, TableName, T, RelatedFields, IsOne>;
+    options = maybeOptions;
+  } else {
+    const contextDb = useContext(Sp00kyContext);
+    if (!contextDb) {
+      throw new Error(
+        'createPreload: No db argument provided and no Sp00kyContext found. ' +
+          'Either pass a SyncedDb instance or wrap your app in <Sp00kyProvider>.',
+      );
+    }
+    db = contextDb as SyncedDb<S>;
+    finalQuery = dbOrQuery;
+    options = queryOrOptions as PreloadOptions | undefined;
+  }
+
+  let prevHash: number | undefined;
+
+  createEffect(() => {
+    if (!(options?.enabled?.() ?? true)) return;
+
+    const query = typeof finalQuery === 'function' ? finalQuery() : finalQuery;
+    if (!query) return;
+
+    // Dedupe on the query's stable identity hash so a reactive re-run with an
+    // unchanged query doesn't refetch (the core also dedupes per session).
+    if (query.hash === prevHash) return;
+    prevHash = query.hash;
+
+    void db.getSp00ky().preload(query, { signal: options?.signal });
+  });
+}

package/src/lib/models.ts

@@ -1,4 +1,4 @@
-import { RecordId } from 'surrealdb';
+import type { RecordId } from 'surrealdb';
 
 // Re-export types from query-builder for backward compatibility
 export type { GenericModel, GenericSchema } from '@spooky/query-builder';

package/src/lib/use-app-release.ts

@@ -0,0 +1,89 @@
+import { createSignal, onCleanup, type Accessor } from 'solid-js';
+import { useDb } from './context';
+import { semverGt, type AppReleaseOptions, type AppReleaseSnapshot } from '@spooky-sync/core';
+
+export interface UseAppReleaseOptions extends AppReleaseOptions {
+  /** App name from sp00ky.yml, e.g. `web`. */
+  app: string;
+  /**
+   * The running build's version (X.Y.Z), typically baked in at build time
+   * (e.g. a vite `define` from package.json). `updateAvailable()` is true when
+   * the announced release is semver-newer than this.
+   */
+  currentVersion: string;
+}
+
+export interface UseAppRelease {
+  /** Latest announced version for the app, or undefined when no row exists. */
+  latestVersion: Accessor<string | undefined>;
+  /** Announced version is semver-newer than the running build. */
+  updateAvailable: Accessor<boolean>;
+  /** The newer release asks clients to update/reload without prompting. */
+  mandatory: Accessor<boolean>;
+  /** The newer release asks reloads to clear service-worker caches first. */
+  cacheBust: Accessor<boolean>;
+  /**
+   * Reload onto the announced release. Plain `location.reload()` normally;
+   * when the release is flagged cache-bust, CacheStorage is cleared, the
+   * service-worker registration is nudged to update, and navigation carries a
+   * `?cb=` token to punch through intermediary caches. The service worker is
+   * deliberately NOT unregistered: navigating while still controlled by a
+   * just-unregistered worker strands subresource fetches on the dead worker
+   * and the page hangs until a manual reload.
+   */
+  reload: () => Promise<void>;
+}
+
+async function reloadForSnapshot(snapshot: AppReleaseSnapshot): Promise<void> {
+  if (typeof window === 'undefined') return;
+  if (snapshot.cacheBust) {
+    try {
+      if (window.caches) {
+        const keys = await window.caches.keys();
+        await Promise.all(keys.map((k) => window.caches.delete(k)));
+      }
+      if (navigator.serviceWorker) {
+        const regs = await navigator.serviceWorker.getRegistrations();
+        for (const r of regs) r.update().catch(() => {});
+      }
+      window.location.href = window.location.pathname + '?cb=' + Date.now();
+      return;
+    } catch {
+      /* fall through to a plain reload */
+    }
+  }
+  window.location.reload();
+}
+
+/**
+ * Observe the app's announced release (`_00_app_release:<app>`, written by
+ * `spky deploy` / `spky release`) and compare it against the running build.
+ *
+ * Typical use: mount a small "new version available — Reload" notification
+ * gated on `updateAvailable()`, auto-invoking `reload()` when `mandatory()`
+ * (guard the auto path against reload loops with a per-version marker, since
+ * a client can reload while the deploy is still rolling out and land on the
+ * old bundle again).
+ */
+export function useAppRelease(options: UseAppReleaseOptions): UseAppRelease {
+  const db = useDb();
+  const handle = db.getSp00ky().appRelease(options.app, { ttl: options.ttl });
+
+  const [snapshot, setSnapshot] = createSignal<AppReleaseSnapshot>(handle.snapshot());
+  const unsub = handle.subscribe(setSnapshot);
+
+  onCleanup(() => {
+    unsub();
+    handle.close();
+  });
+
+  const updateAvailable = () => semverGt(snapshot().version, options.currentVersion);
+
+  return {
+    latestVersion: () => snapshot().version,
+    updateAvailable,
+    mandatory: () => updateAvailable() && snapshot().mandatory,
+    cacheBust: () => snapshot().cacheBust,
+    reload: () => reloadForSnapshot(snapshot()),
+  };
+}

package/src/lib/use-blurhash.ts

@@ -0,0 +1,77 @@
+import { createSignal, createEffect, onCleanup, type Accessor } from 'solid-js';
+import type { SchemaStructure, BucketNames } from '@spooky-sync/query-builder';
+import type { SyncedDb } from '../index';
+import { useDb } from './context';
+
+export interface UseBlurhashResult {
+  /** The stored blurhash for the path, or null while loading / when none exists. */
+  hash: Accessor<string | null>;
+  isLoading: Accessor<boolean>;
+}
+
+/**
+ * The blurhash sidecar for a bucket image (written automatically by
+ * `bucket.put`, see `Sp00kyConfig.blurhash`). Resolves from OPFS instantly on
+ * warm clients; a miss is remembered per tab. Use this directly when the hash
+ * belongs to a different rendition than the displayed image; otherwise
+ * `useBucketImage` / `BucketImage` bundle it with the download.
+ */
+export function useBlurhash<S extends SchemaStructure>(
+  bucketName: BucketNames<S>,
+  path: Accessor<string | null | undefined>
+): UseBlurhashResult;
+export function useBlurhash<S extends SchemaStructure>(
+  db: SyncedDb<S>,
+  bucketName: BucketNames<S>,
+  path: Accessor<string | null | undefined>
+): UseBlurhashResult;
+export function useBlurhash<S extends SchemaStructure>(
+  dbOrBucketName: SyncedDb<S> | BucketNames<S>,
+  bucketNameOrPath?: BucketNames<S> | Accessor<string | null | undefined>,
+  maybePath?: Accessor<string | null | undefined>
+): UseBlurhashResult {
+  let db: SyncedDb<S>;
+  let bucketName: BucketNames<S>;
+  let path: Accessor<string | null | undefined>;
+
+  if (typeof dbOrBucketName === 'string') {
+    db = useDb<S>();
+    bucketName = dbOrBucketName as BucketNames<S>;
+    path = bucketNameOrPath as Accessor<string | null | undefined>;
+  } else {
+    db = dbOrBucketName as SyncedDb<S>;
+    bucketName = bucketNameOrPath as BucketNames<S>;
+    path = maybePath as Accessor<string | null | undefined>;
+  }
+
+  const [hash, setHash] = createSignal<string | null>(null);
+  const [isLoading, setIsLoading] = createSignal(false);
+
+  createEffect(() => {
+    const filePath = path();
+    if (!filePath) {
+      setHash(null);
+      setIsLoading(false);
+      return;
+    }
+    let cancelled = false;
+    setIsLoading(true);
+    db.bucket(bucketName)
+      .blurhash(filePath)
+      .then((result) => {
+        if (cancelled) return;
+        setHash(result);
+        setIsLoading(false);
+      })
+      .catch(() => {
+        if (cancelled) return;
+        setHash(null);
+        setIsLoading(false);
+      });
+    onCleanup(() => {
+      cancelled = true;
+    });
+  });
+
+  return { hash, isLoading };
+}

package/src/lib/use-bucket-image.ts

@@ -0,0 +1,100 @@
+import { createSignal, createEffect, on, type Accessor } from 'solid-js';
+import type { SchemaStructure, BucketNames } from '@spooky-sync/query-builder';
+import type { SyncedDb } from '../index';
+import { useDb } from './context';
+import {
+  useDownloadFile,
+  type UseDownloadFileOptions,
+  type UseDownloadFileResult,
+} from './use-download-file';
+import { useBlurhash } from './use-blurhash';
+
+export interface UseBucketImageOptions extends UseDownloadFileOptions {
+  /**
+   * Also resolve the image's blurhash sidecar (see `Sp00kyConfig.blurhash`).
+   * Default `true`; the read is registered before the image bytes so the tiny
+   * sidecar tends to land first on the serialized remote chain.
+   */
+  blurhash?: boolean;
+}
+
+export interface UseBucketImageResult extends UseDownloadFileResult {
+  /** Blurhash for the same path, or null (off, missing, still loading). */
+  blurhash: Accessor<string | null>;
+  /** True once the current `url()` has been decoded and is safe to paint. */
+  ready: Accessor<boolean>;
+  /**
+   * Ref callback for the `<img>` rendering `url()`: flips `ready` when the
+   * bitmap is decoded (resolves on failure too, so a broken blob degrades to
+   * paint-on-load instead of hiding the image forever). Re-arms itself when
+   * the url changes.
+   */
+  gate: (img: HTMLImageElement) => void;
+}
+
+/**
+ * Everything needed to render a bucket image without a pop-in: the refcounted
+ * object URL, the blurhash placeholder, and a decode gate so the real bitmap
+ * is only revealed once it can paint in full. `BucketImage` wraps this into a
+ * drop-in component; use the hook for custom markup.
+ */
+export function useBucketImage<S extends SchemaStructure>(
+  bucketName: BucketNames<S>,
+  path: Accessor<string | null | undefined>,
+  options?: UseBucketImageOptions
+): UseBucketImageResult;
+export function useBucketImage<S extends SchemaStructure>(
+  db: SyncedDb<S>,
+  bucketName: BucketNames<S>,
+  path: Accessor<string | null | undefined>,
+  options?: UseBucketImageOptions
+): UseBucketImageResult;
+export function useBucketImage<S extends SchemaStructure>(
+  dbOrBucketName: SyncedDb<S> | BucketNames<S>,
+  bucketNameOrPath?: BucketNames<S> | Accessor<string | null | undefined>,
+  pathOrOptions?: Accessor<string | null | undefined> | UseBucketImageOptions,
+  maybeOptions?: UseBucketImageOptions
+): UseBucketImageResult {
+  let db: SyncedDb<S>;
+  let bucketName: BucketNames<S>;
+  let path: Accessor<string | null | undefined>;
+  let options: UseBucketImageOptions;
+
+  if (typeof dbOrBucketName === 'string') {
+    db = useDb<S>();
+    bucketName = dbOrBucketName as BucketNames<S>;
+    path = bucketNameOrPath as Accessor<string | null | undefined>;
+    options = (pathOrOptions as UseBucketImageOptions) ?? {};
+  } else {
+    db = dbOrBucketName as SyncedDb<S>;
+    bucketName = bucketNameOrPath as BucketNames<S>;
+    path = pathOrOptions as Accessor<string | null | undefined>;
+    options = maybeOptions ?? {};
+  }
+
+  // Registered BEFORE the download so the sidecar read enters the serialized
+  // remote queue first: the placeholder should never wait behind the bytes it
+  // is standing in for.
+  const wantHash = options.blurhash !== false;
+  const { hash } = useBlurhash(db, bucketName, () => (wantHash ? path() : null));
+
+  const file = useDownloadFile(db, bucketName, path, options);
+
+  const [ready, setReady] = createSignal(false);
+  // A new url (path change, refetch) means a new undecoded bitmap.
+  createEffect(on(file.url, () => setReady(false), { defer: true }));
+
+  const gate = (img: HTMLImageElement) => {
+    const done = () => setReady(true);
+    if (typeof img.decode === 'function') {
+      img.decode().then(done, done);
+    } else if (img.complete) {
+      done();
+    } else {
+      img.onload = done;
+      img.onerror = done;
+    }
+  };
+
+  return { ...file, blurhash: hash, ready, gate };
+}

package/src/lib/use-crdt-field.ts

@@ -0,0 +1,65 @@
+import { createEffect, createMemo, createSignal, on, onCleanup, useContext, type Accessor } from 'solid-js';
+import { Sp00kyContext } from './context';
+import type { CrdtField } from '@spooky-sync/core';
+
+/**
+ * Open a `@crdt` field of the record `recordId()` names, for an editor to bind
+ * to (`field()?.getDoc()`). Re-opens when the id changes; closes on cleanup.
+ *
+ * The accessor stays `null` until the field is loaded (`CrdtField.isLoaded`):
+ * this device had the document, or the server answered. Until then the
+ * document may be empty only because nothing has arrived yet, so show the
+ * column's text instead of binding an editor to it.
+ */
+export function useCrdtField(
+  table: string,
+  recordId: () => string | undefined,
+  field: string,
+): Accessor<CrdtField | null> {
+  const db = useContext(Sp00kyContext);
+  if (!db) {
+    throw new Error('useCrdtField must be used within a <Sp00kyProvider>');
+  }
+
+  const [crdtField, setCrdtField] = createSignal<CrdtField | null>(null);
+  // Only a different id reopens: `recordId` may re-run on every live update.
+  const id = createMemo(recordId);
+
+  createEffect(
+    on(id, (current) => {
+      if (!current) return;
+      const sp00ky = db.getSp00ky();
+      let active = true;
+      let opened = false;
+      let offLoaded = () => {};
+      sp00ky
+        .openCrdtField(table, current, field)
+        .then((cf) => {
+          opened = true;
+          if (!active) {
+            void sp00ky.closeCrdtField(table, current, field);
+            return;
+          }
+          offLoaded = cf.onLoaded(() => {
+            if (active) setCrdtField(cf);
+          });
+        })
+        .catch((err) => {
+          // A silent rejection leaves the consumer's `Show when={field()}` on
+          // its fallback for good, with no trail. Surface the cause (missing
+          // `@crdt` annotation, schema codegen drift, local DB failure, ...).
+          console.error(`[useCrdtField] Failed to open CRDT field ${table}.${field} on ${current}:`, err);
+        });
+      // Runs before the next id opens, and on unmount. Closing a field whose
+      // open is still in flight is left to the `then` above.
+      onCleanup(() => {
+        active = false;
+        offLoaded();
+        setCrdtField(null);
+        if (opened) void sp00ky.closeCrdtField(table, current, field);
+      });
+    }),
+  );
+
+  return crdtField;
+}

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,69 +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;
-  let refetchTrigger: () => void;
+
   const [refetchSignal, setRefetchSignal] = createSignal(0);
-  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;
     }
@@ -149,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);
@@ -159,31 +107,47 @@ 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);
           setIsLoading(false);
         }
+        return undefined;
       },
       (err) => {
         if (!cancelled) {
@@ -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 };