@spooky-sync/client-solid2 0.0.1-canary.200

package/src/lib/conflate.ts

@@ -0,0 +1,74 @@
+/**
+ * Latest-wins async iterable over a subscribe-callback source.
+ *
+ * Bridges spooky's push-callback subscriptions into the AsyncIterable shape
+ * Solid 2 computations consume natively. Each spooky emission is a full result
+ * set, so intermediate values are droppable: only the newest unconsumed value
+ * is buffered, and a pending pull resolves with it immediately.
+ *
+ * Teardown contract (probed in rc-semantics.test.ts): Solid 2 does NOT
+ * terminate a superseded/disposed computation's async generator — no
+ * `return()`, no `finally`. Consumers MUST call `it.return()` themselves from
+ * an `onCleanup` registered synchronously in the compute scope. `return()`
+ * unsubscribes (awaiting the unsubscribe if the subscribe returned a promise,
+ * as `sp00ky.subscribe` does) and resolves any parked pull as done.
+ */
+export function conflate<T>(
+  subscribe: (cb: (v: T) => void) => (() => void) | Promise<() => void>
+): AsyncIterable<T> {
+  return {
+    [Symbol.asyncIterator](): AsyncIterator<T> {
+      let buffered: { v: T } | undefined;
+      let resolveNext: ((r: IteratorResult<T>) => void) | undefined;
+      let done = false;
+
+      const unsubMaybe = subscribe((v) => {
+        if (done) return;
+        if (resolveNext) {
+          const r = resolveNext;
+          resolveNext = undefined;
+          r({ value: v, done: false });
+        } else {
+          buffered = { v };
+        }
+      });
+
+      const finish = () => {
+        if (done) return;
+        done = true;
+        buffered = undefined;
+        // Unsubscribe may still be in flight (async registration); chain it.
+        Promise.resolve(unsubMaybe)
+          .then((unsub) => unsub())
+          .catch(() => {
+            // Registration failed — there is nothing to unsubscribe.
+          });
+        if (resolveNext) {
+          const r = resolveNext;
+          resolveNext = undefined;
+          r({ value: undefined as never, done: true });
+        }
+      };
+
+      return {
+        next(): Promise<IteratorResult<T>> {
+          if (done) return Promise.resolve({ value: undefined as never, done: true });
+          if (buffered) {
+            const v = buffered.v;
+            buffered = undefined;
+            return Promise.resolve({ value: v, done: false });
+          }
+          return new Promise<IteratorResult<T>>((r) => (resolveNext = r));
+        },
+        return(): Promise<IteratorResult<T>> {
+          finish();
+          return Promise.resolve({ value: undefined as never, done: true });
+        },
+        throw(e: unknown): Promise<IteratorResult<T>> {
+          finish();
+          return Promise.reject(e);
+        },
+      };
+    },
+  };
+}

package/src/lib/context.ts

@@ -0,0 +1,28 @@
+import { createContext, useContext, type Accessor } from 'solid-js';
+import type { SchemaStructure } from '@spooky-sync/query-builder';
+import type { SyncedDb } from '../index';
+import { fromSubscription } from './from-subscription';
+
+// Solid 2: the context object doubles as its provider component —
+// <Sp00kyContext value={db}>{children}</Sp00kyContext>.
+export const Sp00kyContext = createContext<SyncedDb<any>>();
+
+export function useDb<S extends SchemaStructure>(): SyncedDb<S> {
+  try {
+    return useContext(Sp00kyContext) as SyncedDb<S>;
+  } catch {
+    // Solid 2 throws ContextNotFoundError; rethrow with actionable guidance.
+    throw new Error(
+      'useDb must be used within a <Sp00kyProvider>. Wrap your app in <Sp00kyProvider config={...}>.'
+    );
+  }
+}
+
+/**
+ * Count of locally-committed mutations not yet acknowledged by the server.
+ * Drive an "unsaved changes" indicator off this.
+ */
+export function usePendingMutations(): Accessor<number> {
+  const db = useDb();
+  return fromSubscription((cb) => db.subscribeToPendingMutations(cb), db.pendingMutationCount);
+}

package/src/lib/create-preload.ts

@@ -0,0 +1,115 @@
+import type {
+  ColumnSchema,
+  FinalQuery,
+  SchemaStructure,
+  TableNames,
+} from '@spooky-sync/query-builder';
+import { createEffect } from 'solid-js';
+import { SyncedDb } from '..';
+import type {
+  Sp00kyQueryResultPromise,
+  PreloadOptions as CorePreloadOptions,
+} from '@spooky-sync/core';
+import { useDb } 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 warms it into the local cache via `db.preload`. No subscription and
+ * no cleanup: preload registers nothing that needs tearing down.
+ *
+ * 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 {
+    db = useDb<S>();
+    finalQuery = dbOrQuery;
+    options = queryOrOptions as PreloadOptions | undefined;
+  }
+
+  let prevHash: number | undefined;
+
+  // Two-arg Solid 2 effect: compute resolves the query (tracking its reactive
+  // deps) and dedupes on the identity hash; the untracked apply fires the
+  // preload. Returning `undefined` from compute skips nothing — apply guards.
+  createEffect(
+    () => {
+      if (!(options?.enabled?.() ?? true)) return undefined;
+      const query = typeof finalQuery === 'function' ? finalQuery() : finalQuery;
+      if (!query) return undefined;
+      // 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 undefined;
+      prevHash = query.hash;
+      return query;
+    },
+    (query) => {
+      if (!query) return;
+      void db
+        .getSp00ky()
+        .preload(query, { refresh: options?.refresh, staleTime: options?.staleTime });
+    }
+  );
+}

package/src/lib/create-query.ts

@@ -0,0 +1,285 @@
+import type {
+  ColumnSchema,
+  FinalQuery,
+  SchemaStructure,
+  TableNames,
+  QueryResult,
+} from '@spooky-sync/query-builder';
+import {
+  createMemo,
+  createProjection,
+  createSignal,
+  onCleanup,
+  type Accessor,
+} from 'solid-js';
+import { SyncedDb } from '..';
+import type { Sp00kyQueryResultPromise } from '@spooky-sync/core';
+import { useDb } from './context';
+import { conflate } from './conflate';
+
+type QueryArg<
+  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);
+
+export type QueryOptions = {
+  enabled?: () => boolean;
+  /**
+   * Tear down the query (remote `_00_query` view + local WASM view) when this
+   * hook is disposed and no other subscriber remains, instead of keeping it
+   * resident for cheap re-subscription. Use for viewport-windowed lists that
+   * mount/unmount a query per scroll window and want off-screen windows
+   * cancelled. Trade-off: scrolling back to a torn-down window re-registers it.
+   */
+  deregisterOnCleanup?: boolean;
+};
+
+export type CreateQueryResult<TData> = {
+  /**
+   * Reactive result. Never suspends and never throws: born as an empty
+   * committed value (`[]` / `null`) and reconciled in place (keyed by `id`) on
+   * every live emission — unchanged rows keep identity, and coarse readers
+   * (`<For>`) are notified on add/remove/reorder.
+   */
+  data: Accessor<TData>;
+  /**
+   * Suspending read of the same result for `<Loading>` users: throws Solid's
+   * not-ready protocol until the query has delivered its first real result
+   * (or errored, in which case it returns the empty value and `error()` is
+   * set). Read this inside a `<Loading>` boundary.
+   */
+  ready: Accessor<TData>;
+  error: Accessor<Error | undefined>;
+  isLoading: Accessor<boolean>;
+  isFetching: Accessor<boolean>;
+  /**
+   * True once the query has delivered a result AND no fetch cycle is in
+   * flight (registration + initial sync included). While settled, results are
+   * authoritative: a windowed query returning fewer rows than its LIMIT
+   * really is the end of the list. Resets when the query identity changes.
+   */
+  isSettled: Accessor<boolean>;
+};
+
+// Overload: context-based (no explicit db)
+export function createQuery<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends { columns: Record<string, ColumnSchema> },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+  TData = QueryResult<S, TableName, RelatedFields, IsOne> | null,
+>(
+  finalQuery: QueryArg<S, TableName, T, RelatedFields, IsOne>,
+  options?: QueryOptions
+): CreateQueryResult<TData>;
+
+// Overload: explicit db
+export function createQuery<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends { columns: Record<string, ColumnSchema> },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+  TData = QueryResult<S, TableName, RelatedFields, IsOne> | null,
+>(
+  db: SyncedDb<S>,
+  finalQuery: QueryArg<S, TableName, T, RelatedFields, IsOne>,
+  options?: QueryOptions
+): CreateQueryResult<TData>;
+
+// Implementation
+export function createQuery<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends {
+    columns: Record<string, ColumnSchema>;
+  },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+  TData = QueryResult<S, TableName, RelatedFields, IsOne> | null,
+>(
+  dbOrQuery: SyncedDb<S> | QueryArg<S, TableName, T, RelatedFields, IsOne>,
+  queryOrOptions?: QueryArg<S, TableName, T, RelatedFields, IsOne> | QueryOptions,
+  maybeOptions?: QueryOptions
+): CreateQueryResult<TData> {
+  let db: SyncedDb<S>;
+  let finalQuery: QueryArg<S, TableName, T, RelatedFields, IsOne>;
+  let options: QueryOptions | undefined;
+
+  if (dbOrQuery instanceof SyncedDb) {
+    db = dbOrQuery;
+    finalQuery = queryOrOptions as QueryArg<S, TableName, T, RelatedFields, IsOne>;
+    options = maybeOptions;
+  } else {
+    db = useDb<S>();
+    finalQuery = dbOrQuery;
+    options = queryOrOptions as QueryOptions | undefined;
+  }
+
+  const sp00ky = db.getSp00ky();
+
+  // Status channel. Written from subscription callbacks and generator
+  // continuations, which run outside any tracking scope — `ownedWrite` opts
+  // these signals out of Solid 2's owned-scope write guard.
+  const [error, setError] = createSignal<Error | undefined>(undefined, { ownedWrite: true });
+  const [isFetched, setIsFetched] = createSignal(false, { ownedWrite: true });
+  const [isFetching, setIsFetching] = createSignal(false, { ownedWrite: true });
+
+  // The hash of the currently-installed subscription, for opt-in deregister on
+  // dispose (see `deregisterOnCleanup`).
+  let activeHash: string | undefined;
+
+  // Results live in a projection: each yielded emission is reconciled in place
+  // keyed by `id` (unchanged rows keep identity; coarse readers are notified
+  // on add/remove/reorder — probed in rc-semantics.test.ts, replacing the
+  // Solid 1 reconcile + version-signal hack). `seedLoadingValue` births the
+  // store committed, so `data()` reads never suspend.
+  //
+  // The compute's tracked reads (enabled, query thunk) all happen before the
+  // first await — Solid 2 only creates dependency edges for pre-await reads. A
+  // dep change restarts the generator; the superseded one is ABANDONED by
+  // Solid (no return()/finally — probed), so the onCleanup registered
+  // synchronously below is what tears down its subscriptions. This also
+  // replaces the Solid 1 hook's runId/prevQueryString supersede machinery:
+  // Solid dedupes re-runs whose tracked reads are unchanged, and identical
+  // query identity means an identical hash means the same compute inputs.
+  const store = createProjection(
+    async function* (): AsyncGenerator<{ value: TData }> {
+      const enabled = options?.enabled?.() ?? true;
+      const query = typeof finalQuery === 'function' ? finalQuery() : finalQuery;
+
+      if (!enabled || !query) {
+        setIsFetched(false);
+        setError(undefined);
+        return;
+      }
+
+      // A new identity starts clean: a previous identity's failure must not
+      // keep this one out of its loading state.
+      setIsFetched(false);
+      setError(undefined);
+
+      const iterators: AsyncIterator<any>[] = [];
+      const cleanups: (() => void)[] = [];
+      onCleanup(() => {
+        for (const it of iterators) void it.return?.();
+        for (const c of cleanups) c();
+      });
+
+      try {
+        /**
+         * Registration can fail — the canonical case is the SSP answering 503
+         * NOT_READY while it bootstraps. Surface it as `error()` instead of
+         * throwing into the graph: the sync scheduler retries the
+         * registration underneath, so a transient failure still recovers, and
+         * a spinner driven by `isLoading()` resolves via `error()`.
+         */
+        const { hash } = await query.run();
+        activeHash = hash;
+
+        // Mirror the query's fetch status so the UI can show a "loading more"
+        // state while the sync engine pulls missing records in the background.
+        cleanups.push(
+          sp00ky.subscribeQueryStatus(hash, (status) => setIsFetching(status === 'fetching'), {
+            immediate: true,
+          })
+        );
+
+        const it = conflate<Record<string, any>[]>((cb) =>
+          sp00ky.subscribe(hash, cb, { immediate: true })
+        )[Symbol.asyncIterator]();
+        iterators.push(it);
+
+        let isFirstCall = true;
+        while (true) {
+          const r = await it.next();
+          if (r.done) break;
+          const e = r.value;
+          const queryData = (query.isOne ? (e[0] ?? null) : e) as TData;
+          // The first (immediate) callback with no data likely means the local
+          // DB hasn't synced yet — don't mark as fetched so UI shows loading.
+          const hasData = query.isOne
+            ? queryData !== null && queryData !== undefined
+            : e.length > 0;
+          if (!isFirstCall || hasData) setIsFetched(true);
+          isFirstCall = false;
+
+          // Time the store commit (yield → resume) and report it as the
+          // "frontend" phase for DevTools/MCP. Approximate: Solid reconciles
+          // the yielded value before resuming the generator.
+          const t0 = performance.now();
+          yield { value: queryData };
+          sp00ky.reportFrontendTiming(hash, performance.now() - t0);
+        }
+      } catch (err) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+      }
+    },
+    // Wrapped in an object so `one()` queries (row object or null) and list
+    // queries share one store shape; `key` reconciles `value`'s contents.
+    { value: null as TData },
+    { key: 'id', seedLoadingValue: true }
+  );
+
+  // Fallback empty value served before the first emission of a list query.
+  const emptyList = [] as unknown as TData;
+
+  const data: Accessor<TData> = () => {
+    const v = store.value;
+    if (v === null || v === undefined) {
+      const query = typeof finalQuery === 'function' ? finalQuery() : finalQuery;
+      if (query && !query.isOne) return emptyList;
+    }
+    return v as TData;
+  };
+
+  // Suspending read: pends until the first real result (or error) via an async
+  // memo that resolves when isFetched/error flips. Reading it inside <Loading>
+  // integrates with Solid 2's boundary protocol; `data` stays non-throwing.
+  const readyGate = createMemo(async (): Promise<true> => {
+    if (isFetched() || error()) return true;
+    // Tracked reads above registered the deps; park until one flips.
+    await new Promise<void>(() => {});
+    return true;
+  });
+  const ready: Accessor<TData> = () => {
+    readyGate();
+    return data();
+  };
+
+  // Tear down the live subscription when the hook's owner is disposed. The
+  // projection's own onCleanup (inside the compute) already unsubscribes; this
+  // hook-scope cleanup only handles the opt-in query deregistration.
+  onCleanup(() => {
+    // Opt-in: cancel the query once this hook (its last subscriber) is gone.
+    // The compute's cleanup removed this hook's callback, so deregisterQuery's
+    // refcount guard sees the true remaining-subscriber count.
+    if (options?.deregisterOnCleanup && activeHash) {
+      sp00ky.deregisterQuery(activeHash);
+    }
+  });
+
+  const isLoading = () => !isFetched() && error() === undefined;
+  const isSettled = () => isFetched() && !isFetching();
+
+  return {
+    data,
+    ready,
+    error,
+    isLoading,
+    isFetching,
+    isSettled,
+  };
+}
+
+/** @deprecated Renamed `createQuery` in the Solid 2 binding. */
+export const useQuery = createQuery;

package/src/lib/create-submission.ts

@@ -0,0 +1,57 @@
+import { createSignal, type Accessor } from 'solid-js';
+
+export interface Submission<Args extends unknown[], R> {
+  /** Run the wrapped async fn. Concurrent submits share the pending flag. */
+  submit: (...args: Args) => Promise<R | undefined>;
+  /** True while at least one submit is in flight. */
+  pending: Accessor<boolean>;
+  /** Error from the most recent settled submit, cleared on the next submit. */
+  error: Accessor<Error | undefined>;
+  /** Result of the most recent successful submit. */
+  result: Accessor<R | undefined>;
+  clearError: () => void;
+}
+
+/**
+ * Thin submission-state wrapper for mutations — button spinner/disable state
+ * around `db.create/update/delete/run` calls.
+ *
+ * Deliberately NOT built on Solid 2's `action()`/`createOptimisticStore`: the
+ * spooky engine is already optimistic local-first (writes commit to the local
+ * DB and re-render through live queries before sync; `run()` is an outbox
+ * CREATE), so a transaction/revert layer on top buys nothing and `action()`'s
+ * await-vs-yield transaction escape is a real footgun. Errors here mean the
+ * LOCAL commit failed — sync/push failures surface through `useSyncStatus`
+ * and `usePendingMutations` instead.
+ */
+export function createSubmission<Args extends unknown[], R>(
+  fn: (...args: Args) => Promise<R>
+): Submission<Args, R> {
+  // Written from promise continuations — outside any tracking scope.
+  const [inFlight, setInFlight] = createSignal(0, { ownedWrite: true });
+  const [error, setError] = createSignal<Error | undefined>(undefined, { ownedWrite: true });
+  const [result, setResult] = createSignal<R | undefined>(undefined, { ownedWrite: true });
+
+  const submit = async (...args: Args): Promise<R | undefined> => {
+    setError(undefined);
+    setInFlight((n) => n + 1);
+    try {
+      const r = await fn(...args);
+      setResult(() => r);
+      return r;
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error(String(e)));
+      return undefined;
+    } finally {
+      setInFlight((n) => n - 1);
+    }
+  };
+
+  return {
+    submit,
+    pending: () => inFlight() > 0,
+    error,
+    result,
+    clearError: () => setError(undefined),
+  };
+}

package/src/lib/from-subscription.ts

@@ -0,0 +1,32 @@
+import { createMemo, onCleanup, type Accessor } from 'solid-js';
+import { conflate } from './conflate';
+
+/**
+ * Reactive view over a spooky subscribe-callback API.
+ *
+ * The memo's async generator pulls from a conflated (latest-wins) iterator;
+ * `initial` is committed as the memo's `loadingValue`, so the accessor is
+ * readable synchronously from birth and never suspends. Spooky's subscribe
+ * APIs fire immediately with the current value, so the real value lands within
+ * a tick of the first read.
+ *
+ * Teardown is manual by contract (see conflate.ts): onCleanup terminates the
+ * iterator, which unsubscribes.
+ */
+export function fromSubscription<T>(
+  subscribe: (cb: (v: T) => void) => (() => void) | Promise<() => void>,
+  initial: T
+): Accessor<T> {
+  return createMemo(
+    async function* (): AsyncGenerator<T> {
+      const it = conflate(subscribe)[Symbol.asyncIterator]();
+      onCleanup(() => void it.return?.());
+      while (true) {
+        const r = await it.next();
+        if (r.done) break;
+        yield r.value;
+      }
+    },
+    { loadingValue: initial }
+  );
+}

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()),
+  };
+}