@spooky-sync/client-solid 0.0.1-canary.32 → 0.0.1-canary.321

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,68 @@
+import { createEffect, createSignal, onCleanup, useContext, type Accessor } from 'solid-js';
+import { Sp00kyContext } from './context';
+import type { CrdtField } from '@spooky-sync/core';
+
+export function useCrdtField(
+  table: string,
+  recordId: () => string | undefined,
+  field: string,
+  fallbackText?: () => string | undefined,
+): 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);
+  let currentId: string | undefined;
+  let initialized = false;
+
+  createEffect(() => {
+    const id = recordId();
+
+    // Skip if the ID hasn't changed (but allow the first non-undefined value through)
+    if (initialized && id === currentId) return;
+
+    // Close previous field
+    if (currentId && crdtField()) {
+      db.getSp00ky().closeCrdtField(table, currentId, field);
+      setCrdtField(null);
+    }
+
+    currentId = id;
+    initialized = true;
+
+    if (!id) return;
+
+    const sp00ky = db.getSp00ky();
+    const text = fallbackText?.();
+    sp00ky
+      .openCrdtField(table, id, field, text)
+      .then((cf) => {
+        if (currentId === id) {
+          setCrdtField(cf);
+        }
+      })
+      .catch((err) => {
+        // Silent rejections here leave the consumer's `Show when={field()}`
+        // permanently stuck on its fallback (typically a static `<p>` with
+        // no editing UI), with no error trail. Surface the failure so the
+        // root cause (missing `@crdt` annotation, schema codegen drift,
+        // local DB query failure, etc.) is visible in the console instead
+        // of silently breaking collaborative fields.
+        console.error(
+          `[useCrdtField] Failed to open CRDT field ${table}.${field} on ${id}:`,
+          err,
+        );
+      });
+  });
+
+  onCleanup(() => {
+    if (currentId && crdtField()) {
+      db.getSp00ky().closeCrdtField(table, currentId, field);
+      setCrdtField(null);
+    }
+  });
+
+  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 };

package/src/lib/use-feature-flag.ts

@@ -0,0 +1,50 @@
+import { createSignal, onCleanup, type Accessor } from 'solid-js';
+import { useDb } from './context';
+import type { FeatureFlagOptions } from '@spooky-sync/core';
+
+export interface UseFeatureFlag {
+  variant: Accessor<string | undefined>;
+  payload: Accessor<unknown | undefined>;
+  enabled: Accessor<boolean>;
+}
+
+/**
+ * Subscribe to a feature flag for the currently authenticated user.
+ *
+ * Returns three Solid accessors that update reactively whenever the
+ * server-materialized assignment in `_00_user_feature` changes. Backed by
+ * the same SSP + sync pipeline that powers `useQuery`, so toggling a flag
+ * via `spky flag enable <key>` propagates to the UI without a refresh.
+ *
+ * `enabled()` is `true` when the resolved variant exists and is not 'off'.
+ * For multi-variant flags, prefer `variant()` directly.
+ */
+export function useFeatureFlag(
+  key: string,
+  options?: FeatureFlagOptions,
+): UseFeatureFlag {
+  const db = useDb();
+  const handle = db.getSp00ky().feature(key, options);
+
+  const [variant, setVariant] = createSignal<string | undefined>(handle.variant());
+  const [payload, setPayload] = createSignal<unknown | undefined>(handle.payload());
+
+  const unsub = handle.subscribe((s) => {
+    setVariant(s.variant ?? options?.fallback);
+    setPayload(s.payload);
+  });
+
+  onCleanup(() => {
+    unsub();
+    handle.close();
+  });
+
+  return {
+    variant,
+    payload,
+    enabled: () => {
+      const v = variant();
+      return v !== undefined && v !== 'off';
+    },
+  };
+}

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

@@ -1,6 +1,7 @@
 import { createSignal, onCleanup } from 'solid-js';
 import type { SchemaStructure, BucketNames } from '@spooky-sync/query-builder';
 import { fileToUint8Array } from '@spooky-sync/core';
+import type { BucketPutOptions, BucketPutResult } from '@spooky-sync/core';
 import type { SyncedDb } from '../index';
 import { useDb } from './context';
 
@@ -8,7 +9,7 @@ export interface FileUploadResult {
   isUploading: () => boolean;
   error: () => Error | null;
   clearError: () => void;
-  upload: (path: string, file: File | Blob) => Promise<void>;
+  upload: (path: string, file: File | Blob, options?: BucketPutOptions) => Promise<BucketPutResult | void>;
   download: (path: string) => Promise<string | null>;
   remove: (path: string) => Promise<void>;
   exists: (path: string) => Promise<boolean>;
@@ -33,6 +34,7 @@ export function useFileUpload<S extends SchemaStructure>(
     bucketName = dbOrBucketName as BucketNames<S>;
   } else {
     db = dbOrBucketName as SyncedDb<S>;
+    // oxlint-disable-next-line no-non-null-assertion
     bucketName = maybeBucketName!;
   }
 
@@ -52,7 +54,7 @@ export function useFileUpload<S extends SchemaStructure>(
     const config = db.getBucketConfig(bucketName as string);
     if (!config) return;
 
-    if (config.maxSize != null && file.size > config.maxSize) {
+    if (config.maxSize !== null && config.maxSize !== undefined && file.size > config.maxSize) {
       const maxMB = (config.maxSize / (1024 * 1024)).toFixed(1);
       throw new Error(`File exceeds maximum size of ${maxMB} MB.`);
     }
@@ -70,7 +72,11 @@ export function useFileUpload<S extends SchemaStructure>(
     }
   };
 
-  const upload = async (path: string, file: File | Blob): Promise<void> => {
+  const upload = async (
+    path: string,
+    file: File | Blob,
+    options?: BucketPutOptions
+  ): Promise<BucketPutResult | void> => {
     setError(null);
     try {
       validate(file);
@@ -82,7 +88,7 @@ export function useFileUpload<S extends SchemaStructure>(
     setIsUploading(true);
     try {
       const bytes = await fileToUint8Array(file);
-      await db.bucket(bucketName).put(path, bytes);
+      return await db.bucket(bucketName).put(path, bytes, options);
     } catch (e) {
       setError(e instanceof Error ? e : new Error(String(e)));
     } finally {