@spooky-sync/client-solid 0.0.0-canary.1 → 0.0.1-alpha.2

package/src/lib/BucketImage.ts

@@ -0,0 +1,141 @@
+import { createSignal, createEffect, onMount, onCleanup, children } from 'solid-js';
+import type { JSX } from 'solid-js';
+import type { BucketNames, SchemaStructure } from '@spooky-sync/query-builder';
+import { useBucketImage, type UseBucketImageOptions } from './use-bucket-image';
+import { Blurhash } from './Blurhash';
+
+export interface BucketImageProps {
+  /** Bucket name from the schema. */
+  bucket: string;
+  /** Path within the bucket. Nullish renders only the fallback layers. */
+  path: string | null | undefined;
+  alt?: string;
+  /** Classes for the container element (sizing/positioning). */
+  class?: string;
+  /** Classes for the inner `<img>` (the layout styles are inline). */
+  imgClass?: string;
+  /** `object-fit` for the image. Defaults to `cover`. */
+  fit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
+  /**
+   * Bottom placeholder layer (your own plate/skeleton), shown until the image
+   * settles. The blurhash layer paints on top of it once the sidecar resolves.
+   */
+  fallback?: JSX.Element;
+  /** Crossfade duration in ms. Defaults to 300. */
+  transition?: number;
+  /** Crossfade easing. Defaults to an ease-out-expo curve. */
+  easing?: string;
+  /** Resolve the blurhash sidecar. Defaults to true. */
+  blurhash?: boolean;
+  /** Download tuning, forwarded to the underlying `useDownloadFile`. */
+  options?: UseBucketImageOptions;
+}
+
+const LAYER_STYLE = 'position:absolute;inset:0;width:100%;height:100%;';
+
+/**
+ * A bucket image that never pops in: it layers (bottom to top) your `fallback`
+ * plate, the automatically stored blurhash, and the real image, which stays
+ * transparent until the bitmap is DECODED and then crossfades over the
+ * placeholders. Placeholder layers unmount once the fade settles. Respects
+ * prefers-reduced-motion (instant swap). The container is made
+ * `position: relative` unless your `class` positions it already.
+ *
+ * ```tsx
+ * <BucketImage bucket="covers" path={row.cover_key} class="absolute inset-0"
+ *              fallback={<MyPlate />} alt="" />
+ * ```
+ */
+export function BucketImage(props: BucketImageProps): JSX.Element {
+  if (typeof document === 'undefined') return null;
+
+  const image = useBucketImage(
+    props.bucket as BucketNames<SchemaStructure>,
+    () => props.path,
+    { ...props.options, blurhash: props.blurhash !== false }
+  );
+
+  const reducedMotion =
+    typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+  const root = document.createElement('div');
+  createEffect(() => {
+    root.className = props.class ?? '';
+  });
+  // Layers are absolutely positioned; give them an anchor without stomping on
+  // a caller class that already positions the container (inline would win).
+  onMount(() => {
+    if (getComputedStyle(root).position === 'static') root.style.position = 'relative';
+  });
+
+  const placeholder = document.createElement('div');
+  placeholder.style.cssText = LAYER_STYLE;
+  // Solid hands JSX props over as lazy thunks; `children` resolves them (and
+  // nested arrays/functions) to real nodes and keeps them alive reactively.
+  const fallbackHolder = document.createElement('div');
+  fallbackHolder.style.cssText = LAYER_STYLE;
+  placeholder.append(fallbackHolder);
+  const resolvedFallback = children(() => props.fallback);
+  createEffect(() => {
+    const nodes = resolvedFallback.toArray().filter((node) => node instanceof Node) as Node[];
+    fallbackHolder.replaceChildren(...nodes);
+  });
+  const hashCanvas = Blurhash({
+    get hash() {
+      return image.blurhash();
+    },
+    style: LAYER_STYLE,
+  });
+  if (hashCanvas instanceof Node) placeholder.append(hashCanvas);
+
+  const img = document.createElement('img');
+  img.decoding = 'async';
+  img.style.cssText = `${LAYER_STYLE}opacity:0;`;
+  createEffect(() => {
+    img.className = props.imgClass ?? '';
+  });
+  createEffect(() => {
+    img.style.objectFit = props.fit ?? 'cover';
+  });
+  createEffect(() => {
+    img.alt = props.alt ?? '';
+  });
+  createEffect(() => {
+    img.style.transition = reducedMotion
+      ? 'none'
+      : `opacity ${props.transition ?? 300}ms ${props.easing ?? 'cubic-bezier(0.16, 1, 0.3, 1)'}`;
+  });
+  createEffect(() => {
+    const url = image.url();
+    if (!url) {
+      img.removeAttribute('src');
+      return;
+    }
+    img.src = url;
+    image.gate(img);
+  });
+  createEffect(() => {
+    img.style.opacity = image.ready() ? '1' : '0';
+  });
+
+  // Placeholders leave the DOM once the fade is over (a shelf of covers should
+  // not composite three layers each forever) and come back when the path
+  // changes mid-life (`ready` re-arms via the hook).
+  const [settled, setSettled] = createSignal(false);
+  createEffect(() => {
+    if (!image.ready()) {
+      setSettled(false);
+      return;
+    }
+    const wait = (reducedMotion ? 0 : (props.transition ?? 300)) + 120;
+    const timer = setTimeout(() => setSettled(true), wait);
+    onCleanup(() => clearTimeout(timer));
+  });
+  createEffect(() => {
+    if (settled()) placeholder.remove();
+    else if (!placeholder.isConnected) root.insertBefore(placeholder, img);
+  });
+
+  root.append(placeholder, img);
+  return root;
+}

package/src/lib/Sp00kyProvider.ts

@@ -0,0 +1,104 @@
+import type { JSX } from 'solid-js';
+import {
+  createSignal,
+  onMount,
+  onCleanup,
+  createComponent,
+  createMemo,
+  mergeProps,
+} from 'solid-js';
+import type { SchemaStructure } from '@spooky/query-builder';
+import type { SyncedDbConfig } from '../types';
+import { SyncedDb } from '../index';
+import { Sp00kyContext } from './context';
+
+export interface Sp00kyProviderProps<S extends SchemaStructure> {
+  config: SyncedDbConfig<S>;
+  fallback?: JSX.Element;
+  onError?: (error: Error) => void;
+  onReady?: (db: SyncedDb<S>) => void;
+  /**
+   * Prewarm data into the local cache before revealing the UI. Runs after
+   * `init()`; the `fallback` stays visible until it resolves. Use awaitable
+   * `db.preload(...)` calls here to gate first-load on essential data (e.g.
+   * config). On warm loads preload returns instantly, so there's no perceptible
+   * gate after the first run. Best-effort: a rejection is caught and the UI is
+   * revealed anyway.
+   */
+  preload?: (db: SyncedDb<S>) => Promise<void>;
+  children: JSX.Element;
+}
+
+export function Sp00kyProvider<S extends SchemaStructure>(
+  props: Sp00kyProviderProps<S>
+): JSX.Element {
+  const merged = mergeProps(
+    {
+      fallback: undefined as JSX.Element | undefined,
+    },
+    props
+  );
+
+  const [db, setDb] = createSignal<SyncedDb<S> | undefined>(undefined);
+
+  // `onMount` is async, so a dispose can land mid-init. Only that narrow race is
+  // handled here: an instance whose init finished AFTER the provider was already
+  // gone is closed, because nothing will ever reference it.
+  //
+  // A live, mounted client is deliberately NOT closed on cleanup. Doing that
+  // nulls `SyncedDb.sp00ky`, so every later `create`/`update`/`delete` throws
+  // "SyncedDb not initialized" while reads keep rendering from state that is
+  // already subscribed — i.e. mutations die silently and the app looks fine. In
+  // a host app the provider wraps the whole tree and only unmounts with the
+  // page, where the browser reclaims the worker anyway, so the leak this was
+  // meant to fix is worth far less than that risk.
+  let disposed = false;
+
+  onCleanup(() => {
+    disposed = true;
+  });
+
+  onMount(async () => {
+    try {
+      const instance = new SyncedDb<S>(merged.config);
+      await instance.init();
+      if (disposed) {
+        await instance.close();
+        return;
+      }
+      // Gate first-load UI on prewarmed data. Best-effort: never let a preload
+      // failure keep the app stuck on the fallback.
+      if (merged.preload) {
+        try {
+          await merged.preload(instance);
+        } catch (e) {
+          // oxlint-disable-next-line no-console
+          console.error('Sp00kyProvider: preload failed; revealing UI anyway', e);
+        }
+      }
+      setDb(() => instance);
+      merged.onReady?.(instance);
+    } catch (e) {
+      const error = e instanceof Error ? e : new Error(String(e));
+      if (merged.onError) {
+        merged.onError(error);
+      } else {
+        // oxlint-disable-next-line no-console
+        console.error('Sp00kyProvider: Failed to initialize database', error);
+      }
+    }
+  });
+
+  const content = createMemo(() => {
+    const instance = db();
+    if (!instance) return merged.fallback;
+    return createComponent(Sp00kyContext.Provider, {
+      value: instance,
+      get children() {
+        return merged.children;
+      },
+    });
+  });
+
+  return content as unknown as JSX.Element;
+}

package/src/lib/context.ts

@@ -2,12 +2,12 @@ import { createContext, useContext } from 'solid-js';
 import type { SchemaStructure } from '@spooky/query-builder';
 import type { SyncedDb } from '../index';
 
-export const SpookyContext = createContext<SyncedDb<any> | undefined>();
+export const Sp00kyContext = createContext<SyncedDb<any> | undefined>();
 
 export function useDb<S extends SchemaStructure>(): SyncedDb<S> {
-  const db = useContext(SpookyContext);
+  const db = useContext(Sp00kyContext);
   if (!db) {
-    throw new Error('useDb must be used within a <SpookyProvider>. Wrap your app in <SpookyProvider config={...}>.');
+    throw new Error('useDb must be used within a <Sp00kyProvider>. Wrap your app in <Sp00kyProvider config={...}>.');
   }
   return db as SyncedDb<S>;
 }

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 };
+}