@spooky-sync/client-solid2 0.0.1-alpha.1

package/src/lib/merge-rows.ts

@@ -0,0 +1,72 @@
+import { snapshot } from 'solid-js';
+
+/**
+ * Keyed in-place merge of a fresh row list into a store draft array.
+ *
+ * Why not `reconcile(rows, 'id')`: in Solid 2 rc.1 a reconcile REPLACES the row
+ * objects, so a component that captured `data()[0]` sees a different object
+ * after the next emission, and anything keyed on row identity (`<For>` without
+ * an explicit key, a memo comparing rows) re-creates its subtree on every live
+ * update. Mutating the draft in place keeps the identity AND keeps updates
+ * fine-grained: only the fields that actually changed are written, so a row
+ * whose data is unchanged notifies nobody.
+ *
+ * Rows are matched by `key` (default `id`); unmatched incoming rows are
+ * inserted as-is and trailing rows are dropped, so add / remove / reorder all
+ * reach coarse readers.
+ */
+/**
+ * Field-level equality for the merge. `===` is not enough: the decoder hands
+ * out a fresh RecordId / Date instance for every record-link and datetime
+ * column on every emission, so by identity every one of those fields "changed"
+ * on every update - and a store write on an unchanged `id` re-ran everything a
+ * page keyed on that row (a thread's anchor, its composer, its whole subtree).
+ * Compare those wrappers by value; everything else stays identity (nested
+ * objects and arrays are reconciled by their own writes).
+ */
+export function sameValue(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a == null || b == null) return false;
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+  // RecordId (and the SDK's other value wrappers: Duration, Decimal, Uuid…)
+  // all carry a stable `toString`; two of the same class that print alike ARE
+  // the same value. Plain objects are excluded: their `toString` is
+  // "[object Object]" and would make every object equal to every other.
+  if (typeof a === 'object' && typeof b === 'object') {
+    const ctor = (a as any).constructor;
+    if (ctor && ctor === (b as any).constructor && ctor !== Object && ctor !== Array) {
+      return String(a) === String(b);
+    }
+  }
+  return false;
+}
+
+export function mergeRows(draft: any[], next: any[], key = 'id'): void {
+  const byKey = new Map<any, any>();
+  for (const row of draft) {
+    const k = row?.[key];
+    if (k !== undefined) byKey.set(String(k), row);
+  }
+
+  for (let i = 0; i < next.length; i++) {
+    const incoming = next[i];
+    const k = incoming?.[key];
+    const reuse = k !== undefined ? byKey.get(String(k)) : undefined;
+
+    if (reuse) {
+      for (const field of Object.keys(incoming)) {
+        if (!sameValue(reuse[field], incoming[field])) reuse[field] = incoming[field];
+      }
+      // `snapshot` first: iterating the proxy's own keys while deleting from it
+      // is not safe, and the raw object is what carries the stale fields.
+      for (const field of Object.keys(snapshot(reuse))) {
+        if (!(field in incoming)) delete reuse[field];
+      }
+      if (draft[i] !== reuse) draft[i] = reuse;
+    } else if (draft[i] !== incoming) {
+      draft[i] = incoming;
+    }
+  }
+
+  if (draft.length > next.length) draft.splice(next.length);
+}

package/src/lib/models.ts

@@ -0,0 +1,8 @@
+import type { RecordId } from 'surrealdb';
+
+// Re-export types from query-builder for backward compatibility
+export type { GenericModel, GenericSchema } from '@spooky-sync/query-builder';
+
+// Model and ModelPayload types for the client
+export type Model<T> = T;
+export type ModelPayload<T> = T & { id: RecordId };

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

@@ -0,0 +1,89 @@
+import type { Accessor } from 'solid-js';
+import { onCleanup } from 'solid-js';
+import { useDb } from './context';
+import { fromSubscription } from './from-subscription';
+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 });
+  onCleanup(() => handle.close());
+
+  const snapshot = fromSubscription<AppReleaseSnapshot>(
+    (cb) => handle.subscribe(cb),
+    handle.snapshot()
+  );
+
+  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,82 @@
+import { createSignal, createEffect, 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>;
+  }
+
+  // Written from the lookup continuation, outside any tracking scope.
+  const [hash, setHash] = createSignal<string | null>(null, { ownedWrite: true });
+  const [isLoading, setIsLoading] = createSignal(false, { ownedWrite: true });
+
+  // Compute tracks the path; apply runs the lookup and returns the cancel
+  // cleanup, which runs before the next apply and on unmount.
+  createEffect(
+    () => path(),
+    (filePath) => {
+      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);
+        });
+      return () => {
+        cancelled = true;
+      };
+    }
+  );
+
+  return { hash, isLoading };
+}

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

@@ -0,0 +1,108 @@
+import { createSignal, createEffect, 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);
+
+  // Written from the decode continuation (and from the url effect's apply
+  // phase), outside any tracking scope.
+  const [ready, setReady] = createSignal(false, { ownedWrite: true });
+  // A new url (path change, refetch) means a new undecoded bitmap.
+  createEffect(
+    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,57 @@
+import { createEffect, createSignal, type Accessor } from 'solid-js';
+import { useDb } 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 = useDb();
+  const [crdtField, setCrdtField] = createSignal<CrdtField | null>(null, { ownedWrite: true });
+
+  // Two-arg Solid 2 effect: the compute tracks `recordId`, the apply owns the
+  // open/close lifecycle and returns the cleanup — which runs both when the id
+  // changes (before the next apply) and on unmount. That replaces the Solid 1
+  // version's manual currentId/initialized bookkeeping.
+  createEffect(
+    () => recordId(),
+    (id) => {
+      if (!id) {
+        setCrdtField(null);
+        return;
+      }
+      const sp00ky = db.getSp00ky();
+      let superseded = false;
+      const text = fallbackText?.();
+      sp00ky
+        .openCrdtField(table, id, field, text)
+        .then((cf) => {
+          if (!superseded) {
+            setCrdtField(cf);
+          } else {
+            sp00ky.closeCrdtField(table, id, field);
+          }
+        })
+        .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);
+        });
+      return () => {
+        superseded = true;
+        if (crdtField()) {
+          sp00ky.closeCrdtField(table, id, field);
+          setCrdtField(null);
+        }
+      };
+    }
+  );
+
+  return crdtField;
+}

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

@@ -0,0 +1,181 @@
+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 {
+  url: Accessor<string | null>;
+  isLoading: Accessor<boolean>;
+  error: Accessor<Error | null>;
+  refetch: () => void;
+}
+
+export function useDownloadFile<S extends SchemaStructure>(
+  bucketName: BucketNames<S>,
+  path: Accessor<string | null | undefined>,
+  options?: UseDownloadFileOptions
+): UseDownloadFileResult;
+export function useDownloadFile<S extends SchemaStructure>(
+  db: SyncedDb<S>,
+  bucketName: BucketNames<S>,
+  path: Accessor<string | null | undefined>,
+  options?: UseDownloadFileOptions
+): UseDownloadFileResult;
+export function useDownloadFile<S extends SchemaStructure>(
+  dbOrBucketName: SyncedDb<S> | BucketNames<S>,
+  bucketNameOrPath?: BucketNames<S> | Accessor<string | null | undefined>,
+  pathOrOptions?: Accessor<string | null | undefined> | UseDownloadFileOptions,
+  maybeOptions?: UseDownloadFileOptions
+): UseDownloadFileResult {
+  let db: SyncedDb<S>;
+  let bucketName: BucketNames<S>;
+  let path: Accessor<string | null | undefined>;
+  let options: UseDownloadFileOptions;
+
+  if (typeof dbOrBucketName === 'string') {
+    db = useDb<S>();
+    bucketName = dbOrBucketName as BucketNames<S>;
+    path = bucketNameOrPath as Accessor<string | null | undefined>;
+    options = (pathOrOptions as UseDownloadFileOptions) ?? {};
+  } else {
+    db = dbOrBucketName as SyncedDb<S>;
+    bucketName = bucketNameOrPath as BucketNames<S>;
+    path = pathOrOptions as Accessor<string | null | undefined>;
+    options = maybeOptions ?? {};
+  }
+
+  const useCache = options.cache !== false;
+
+  // Written from fetch continuations — outside any tracking scope.
+  const [url, setUrl] = createSignal<string | null>(null, { ownedWrite: true });
+  const [isLoading, setIsLoading] = createSignal(false, { ownedWrite: true });
+  const [error, setError] = createSignal<Error | null>(null, { ownedWrite: true });
+
+  // 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);
+  /** Consumed by the next effect run, so `refetch()` bypasses every layer once. */
+  let reloadOnce = false;
+
+  function releaseCurrent() {
+    lease?.release();
+    lease = null;
+    if (privateUrl) {
+      URL.revokeObjectURL(privateUrl);
+      privateUrl = null;
+    }
+  }
+
+  // Two-arg Solid 2 effect: compute tracks path + refetch tick; apply runs the
+  // fetch and returns the cancel/release cleanup, which runs before the next
+  // apply and on unmount.
+  createEffect(
+    () => {
+      refetchSignal();
+      return path();
+    },
+    (filePath) => {
+      releaseCurrent();
+
+      if (!filePath) {
+        setUrl(null);
+        setIsLoading(false);
+        setError(null);
+        return;
+      }
+
+      const reload = reloadOnce;
+      reloadOnce = false;
+
+      let cancelled = false;
+      setIsLoading(true);
+      setError(null);
+
+      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) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+            setIsLoading(false);
+          }
+        }
+      );
+
+      return () => {
+        cancelled = true;
+      };
+    }
+  );
+
+  onCleanup(() => {
+    releaseCurrent();
+  });
+
+  const refetch = () => {
+    reloadOnce = true;
+    setRefetchSignal((n) => n + 1);
+  };
+
+  return { url, isLoading, error, refetch };
+}

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

@@ -0,0 +1,43 @@
+import type { Accessor } from 'solid-js';
+import { onCleanup } from 'solid-js';
+import { useDb } from './context';
+import { fromSubscription } from './from-subscription';
+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 `createQuery`, 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);
+  onCleanup(() => handle.close());
+
+  const state = fromSubscription<{ variant: string | undefined; payload: unknown }>(
+    (cb) =>
+      handle.subscribe((s) => cb({ variant: s.variant ?? options?.fallback, payload: s.payload })),
+    { variant: handle.variant(), payload: handle.payload() }
+  );
+
+  return {
+    variant: () => state().variant,
+    payload: () => state().payload,
+    enabled: () => {
+      const v = state().variant;
+      return v !== undefined && v !== 'off';
+    },
+  };
+}