@spooky-sync/client-solid 0.0.1-canary.17 → 0.0.1-canary.170

package/src/lib/use-query.ts

@@ -1,4 +1,4 @@
-import {
+import type {
   ColumnSchema,
   FinalQuery,
   SchemaStructure,
@@ -6,9 +6,10 @@ import {
   QueryResult,
 } from '@spooky-sync/query-builder';
 import { createEffect, createSignal, onCleanup, useContext } from 'solid-js';
+import { createStore, reconcile } from 'solid-js/store';
 import { SyncedDb } from '..';
-import { SpookyQueryResultPromise } from '@spooky-sync/core';
-import { SpookyContext } from './context';
+import type { Sp00kyQueryResultPromise } from '@spooky-sync/core';
+import { Sp00kyContext } from './context';
 
 type QueryArg<
   S extends SchemaStructure,
@@ -17,13 +18,23 @@ type QueryArg<
   RelatedFields extends Record<string, any>,
   IsOne extends boolean,
 > =
-  | FinalQuery<S, TableName, T, RelatedFields, IsOne, SpookyQueryResultPromise>
+  | FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise>
   | (() =>
-      | FinalQuery<S, TableName, T, RelatedFields, IsOne, SpookyQueryResultPromise>
+      | FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise>
       | null
       | undefined);
 
-type QueryOptions = { enabled?: () => boolean };
+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;
+};
 
 // Overload: context-based (no explicit db)
 export function useQuery<
@@ -36,7 +47,13 @@ export function useQuery<
 >(
   finalQuery: QueryArg<S, TableName, T, RelatedFields, IsOne>,
   options?: QueryOptions,
-): { data: () => TData | undefined; error: () => Error | undefined; isLoading: () => boolean };
+): {
+  data: () => TData | undefined;
+  error: () => Error | undefined;
+  isLoading: () => boolean;
+  isFetching: () => boolean;
+  isSettled: () => boolean;
+};
 
 // Overload: explicit db (backward-compatible)
 export function useQuery<
@@ -50,7 +67,13 @@ export function useQuery<
   db: SyncedDb<S>,
   finalQuery: QueryArg<S, TableName, T, RelatedFields, IsOne>,
   options?: QueryOptions,
-): { data: () => TData | undefined; error: () => Error | undefined; isLoading: () => boolean };
+): {
+  data: () => TData | undefined;
+  error: () => Error | undefined;
+  isLoading: () => boolean;
+  isFetching: () => boolean;
+  isSettled: () => boolean;
+};
 
 // Implementation
 export function useQuery<
@@ -82,11 +105,11 @@ export function useQuery<
     options = maybeOptions;
   } else {
     // Context-based overload: useQuery(query, options?)
-    const contextDb = useContext(SpookyContext);
+    const contextDb = useContext(Sp00kyContext);
     if (!contextDb) {
       throw new Error(
-        'useQuery: No db argument provided and no SpookyContext found. ' +
-        'Either pass a SyncedDb instance or wrap your app in <SpookyProvider>.'
+        'useQuery: No db argument provided and no Sp00kyContext found. ' +
+        'Either pass a SyncedDb instance or wrap your app in <Sp00kyProvider>.'
       );
     }
     db = contextDb as SyncedDb<S>;
@@ -94,29 +117,76 @@ export function useQuery<
     options = queryOrOptions as QueryOptions | undefined;
   }
 
-  const [data, setData] = createSignal<TData | undefined>(undefined);
   const [error, setError] = createSignal<Error | undefined>(undefined);
   const [isFetched, setIsFetched] = createSignal(false);
-  const [unsubscribe, setUnsubscribe] = createSignal<(() => void) | undefined>(undefined);
+  const [isFetching, setIsFetching] = createSignal(false);
+  // Results live in a store (not a signal) so consecutive live-query emissions
+  // are merged with `reconcile`: unchanged rows keep their object identity and
+  // changed rows are mutated in place. That keeps Solid's reference-keyed `<For>`
+  // rows — and any `useQuery` subscriptions mounted inside them — alive across
+  // updates, instead of tearing every row down and re-registering its queries.
+  const [state, setState] = createStore<{ value: TData | undefined }>({ value: undefined });
+  // `reconcile` (below) merges each emission into `state.value` IN PLACE, keeping
+  // the array reference stable. That's ideal for granular per-row reactivity, but
+  // it means a *coarse* reader of `data()` — `<For each={data()}>`, or an effect
+  // that copies the whole array elsewhere (e.g. GameList's windowed store) — is
+  // NOT re-run when rows are added/removed/reordered within a same-length result
+  // (the classic case: deleting a row in a windowed list shifts the next one in,
+  // so length stays 50 and the array ref never changes). Bump a version on every
+  // emission and read it in `data()` so every consumer re-runs on any change while
+  // reconcile still preserves row identity underneath.
+  const [version, setVersion] = createSignal(0);
+  const data = () => {
+    version();
+    return state.value;
+  };
+
   let prevQueryString: string | undefined;
+  // Monotonic token for each subscription generation. Bumped whenever the query
+  // identity changes or the hook is disposed, so a slow async `initQuery`
+  // continuation can detect it was superseded and avoid installing a stale (and
+  // leaked) subscription.
+  let runId = 0;
+  let activeUnsub: (() => void) | undefined;
+  // The hash of the currently-installed subscription, for opt-in deregister on
+  // dispose (see `deregisterOnCleanup`).
+  let activeHash: string | undefined;
+
+  const teardownActive = () => {
+    activeUnsub?.();
+    activeUnsub = undefined;
+  };
 
-  const spooky = db.getSpooky();
+  const sp00ky = db.getSp00ky();
 
   const initQuery = async (
-    query: FinalQuery<S, TableName, T, RelatedFields, IsOne, SpookyQueryResultPromise>
+    query: FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise>,
+    myRun: number
   ) => {
     const { hash } = await query.run();
+    // A newer query identity (or disposal) won the race while we awaited run().
+    if (myRun !== runId) return;
+    activeHash = hash;
     setError(undefined);
 
     let isFirstCall = true;
-    const unsub = await spooky.subscribe(
+    const unsub = await sp00ky.subscribe(
       hash,
       (e) => {
-        const data = (query.isOne ? e[0] : e) as TData;
-        setData(() => data);
+        const queryData = (query.isOne ? e[0] : e) as TData;
+        // Merge into the store by record id: unchanged rows keep their identity,
+        // changed rows update in place. Replaces wholesale for `one()`/null.
+        // Time the reconcile → report as the "frontend" phase for DevTools/MCP.
+        const reconcileStart = performance.now();
+        setState('value', reconcile(queryData as any, { key: 'id' }));
+        // Notify coarse `data()` readers (see the `version` note above): reconcile
+        // keeps the array ref stable, so this is what re-runs `<For>`/copy-effects
+        // on add/remove/reorder.
+        setVersion((v) => v + 1);
+        sp00ky.reportFrontendTiming(hash, performance.now() - reconcileStart);
         // 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 state
-        const hasData = query.isOne ? data != null : (e as any[]).length > 0;
+        const hasData = query.isOne ? queryData !== null && queryData !== undefined : (e as any[]).length > 0;
         if (!isFirstCall || hasData) {
           setIsFetched(true);
         }
@@ -125,7 +195,25 @@ export function useQuery<
       { immediate: true }
     );
 
-    setUnsubscribe(() => unsub);
+    // 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.
+    const unsubStatus = sp00ky.subscribeQueryStatus(
+      hash,
+      (status) => setIsFetching(status === 'fetching'),
+      { immediate: true }
+    );
+
+    const teardown = () => {
+      unsub();
+      unsubStatus();
+    };
+
+    // Superseded while awaiting subscribe()? Don't leak — tear down immediately.
+    if (myRun !== runId) {
+      teardown();
+      return;
+    }
+    activeUnsub = teardown;
   };
 
   createEffect(() => {
@@ -143,30 +231,57 @@ export function useQuery<
       return;
     }
 
-    // Prevent re-running if query hasn't changed
-    const queryString = JSON.stringify(query);
+    // Dedup on the query's stable identity hash (cyrb53 of surql + vars), not a
+    // full `JSON.stringify` of the FinalQuery (which walks the whole schema +
+    // inner query on every reactive tick and isn't guaranteed stable). When the
+    // identity is unchanged we keep the existing subscription alive.
+    const queryString = String(query.hash);
     if (queryString === prevQueryString) {
       return;
     }
     prevQueryString = queryString;
 
-    // Reset fetched state when query changes
+    // New query identity → supersede the previous subscription and start fresh.
+    const myRun = ++runId;
+    teardownActive();
     setIsFetched(false);
-    initQuery(query);
+    initQuery(query, myRun);
+  });
 
-    // Cleanup
-    onCleanup(() => {
-      unsubscribe()?.();
-    });
+  // Tear down the live subscription when the hook's owner is disposed. Registered
+  // on the hook (component) scope rather than inside the effect, so an effect
+  // re-run that early-returns (unchanged query) doesn't clean up the still-valid
+  // subscription. Bumping runId also invalidates any in-flight initQuery.
+  onCleanup(() => {
+    runId++;
+    teardownActive();
+    // Opt-in: cancel the query once this hook (its last subscriber) is gone.
+    // teardownActive() above already 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 = () => {
     return !isFetched() && error() === undefined;
   };
 
+  // True once the query has delivered a result AND no fetch cycle is in flight
+  // (registration + initial sync included — the core holds `fetching` across
+  // the whole registration and flushes debounced results before flipping back
+  // to idle). While settled, the results are authoritative: a windowed query
+  // returning fewer rows than its LIMIT really is the end of the list, so
+  // virtualized lists may size themselves to it without the scrollbar jumping
+  // when a still-syncing window transiently reports short. Resets to false
+  // whenever the query identity changes.
+  const isSettled = () => isFetched() && !isFetching();
+
   return {
     data,
     error,
     isLoading,
+    isFetching,
+    isSettled,
   };
 }

package/src/lib/use-storage-status.ts

@@ -0,0 +1,44 @@
+import { createSignal, onCleanup, type Accessor } from 'solid-js';
+import { useDb } from './context';
+import type { StorageHealth, StorageHealthStatus } from '@spooky-sync/core';
+
+export interface UseStorageStatus {
+  /** Full durability snapshot; updates reactively. */
+  health: Accessor<StorageHealth>;
+  /** `'unknown'` | `'persistent'` | `'memory'`. */
+  status: Accessor<StorageHealthStatus>;
+  /** `true` when the local store survives a reload. */
+  isPersistent: Accessor<boolean>;
+  /**
+   * `true` only when durable storage was requested and could NOT be opened, so
+   * the dataset is sitting in RAM and local writes die on reload. Drive a
+   * warning off this, not off `status`: a store configured as in-memory reports
+   * `'memory'` too, and that is a choice rather than a problem.
+   */
+  isMemoryFallback: Accessor<boolean>;
+}
+
+/**
+ * Observe how durable the LOCAL cache is, for a "no local storage" warning.
+ *
+ * Under `localEngine: 'sqlite'` with `store: 'indexeddb'` the durable store is
+ * the OPFS SAHPool VFS, and only ONE client per bucket can hold it open: a
+ * second tab of the same app cannot get it and runs in memory instead (the
+ * engine retries first, so a closing tab's lock is usually waited out). Must be
+ * used within a `<Sp00kyProvider>`.
+ */
+export function useStorageStatus(): UseStorageStatus {
+  const db = useDb();
+  // subscribeToStorageHealth fires synchronously with the current snapshot, so
+  // the signal is correct from the first read; the initial value avoids a flash.
+  const [health, setHealth] = createSignal<StorageHealth>(db.storageHealth);
+  const unsub = db.subscribeToStorageHealth(setHealth);
+  onCleanup(unsub);
+
+  return {
+    health,
+    status: () => health().status,
+    isPersistent: () => health().status === 'persistent',
+    isMemoryFallback: () => health().fallback,
+  };
+}

package/src/lib/use-sync-status.ts

@@ -0,0 +1,64 @@
+import { createSignal, onCleanup, type Accessor } from 'solid-js';
+import { useDb } from './context';
+import type { ConnectionState, SyncHealth, SyncHealthStatus } from '@spooky-sync/core';
+
+export interface UseSyncStatus {
+  /** Full health snapshot; updates reactively on every transition. */
+  health: Accessor<SyncHealth>;
+  /** `'healthy'` | `'degraded'`. */
+  status: Accessor<SyncHealthStatus>;
+  isHealthy: Accessor<boolean>;
+  /** `true` once sync has failed for a sustained run — drive a banner off this. */
+  isDegraded: Accessor<boolean>;
+  /** `true` once at least one sync round has succeeded this session. */
+  everConnected: Accessor<boolean>;
+  /**
+   * `true` only for a real lost connection: degraded AFTER a first successful
+   * sync. Stays `false` during the initial "connecting" phase (degraded but
+   * never reached the server yet), so an indicator can show nothing until the
+   * app has actually connected once.
+   */
+  isOffline: Accessor<boolean>;
+  /**
+   * Transport state of the remote WebSocket. Flips the instant the socket
+   * drops, unlike `status`, which only degrades after a sustained run of failed
+   * sync rounds — so this is what to drive a "reconnecting…" affordance off.
+   */
+  connection: Accessor<ConnectionState>;
+  /**
+   * `true` while the connection is being re-established. Usually still
+   * `isHealthy()`: a short reconnect is invisible to sync, and writes made
+   * during it are queued locally and pushed once the socket is back.
+   */
+  isReconnecting: Accessor<boolean>;
+}
+
+/**
+ * Observe sync health for a "can't reach the server" banner / indicator.
+ *
+ * Backed by `db.subscribeToSyncHealth`. Individual sync failures (a transient
+ * remote 500 on query registration, a dropped socket) are absorbed by the
+ * retry and never flip this; `isDegraded()` only goes true once failures
+ * persist for the configured number of consecutive rounds (sp00ky core config
+ * `syncHealth.degradeAfterConsecutiveFailures`, default 3), and flips back on
+ * the next successful round. Must be used within a `<Sp00kyProvider>`.
+ */
+export function useSyncStatus(): UseSyncStatus {
+  const db = useDb();
+  // subscribeToSyncHealth fires synchronously with the current status, so the
+  // signal is correct from first read; the initial value just avoids a flash.
+  const [health, setHealth] = createSignal<SyncHealth>(db.syncHealth);
+  const unsub = db.subscribeToSyncHealth(setHealth);
+  onCleanup(unsub);
+
+  return {
+    health,
+    status: () => health().status,
+    isHealthy: () => health().status === 'healthy',
+    isDegraded: () => health().status === 'degraded',
+    everConnected: () => health().everConnected,
+    isOffline: () => health().status === 'degraded' && health().everConnected,
+    connection: () => health().connection,
+    isReconnecting: () => health().connection === 'reconnecting',
+  };
+}

package/src/types/index.ts

@@ -1,7 +1,6 @@
-import type { Surreal } from 'surrealdb';
 import type { SyncedDb } from '../index';
-import { GenericSchema } from '../lib/models';
-import type { SpookyConfig } from '@spooky-sync/core';
+import type { GenericSchema } from '../lib/models';
+import type { Sp00kyConfig } from '@spooky-sync/core';
 import type { SchemaStructure, TableNames, GetTable, TableModel } from '@spooky-sync/query-builder';
 
 /**
@@ -44,7 +43,7 @@ export type InferRelationshipsFromConst<S extends SchemaStructure, Schema extend
 // Prettify helper expands types for better intellisense
 type Prettify<T> = { [K in keyof T]: T[K] } & {};
 
-export type SyncedDbConfig<S extends SchemaStructure> = Prettify<SpookyConfig<S>>;
+export type SyncedDbConfig<S extends SchemaStructure> = Prettify<Sp00kyConfig<S>>;
 
 // export interface LocalDbConfig {
 //   name: string;

package/skills/spooky-solid/SKILL.md

@@ -1,217 +0,0 @@
----
-name: spooky-solid
-description: >-
-  SolidJS integration for the Spooky reactive local-first SurrealDB framework.
-  Use when setting up SpookyProvider, using useQuery for reactive data, building
-  queries with QueryBuilder in SolidJS components, handling mutations, auth,
-  file uploads/downloads, or working with Spooky types like Model and RecordId.
-metadata:
-  author: spooky-sync
-  version: "0.0.1"
----
-
-# Spooky SolidJS Client
-
-`@spooky-sync/client-solid` provides SolidJS bindings for the Spooky framework. It wraps `@spooky-sync/core` with a context provider, reactive `useQuery` hook, and file operation hooks.
-
-## Setup
-
-```tsx
-import { SpookyProvider } from '@spooky-sync/client-solid';
-import { schema } from './generated/schema';
-import schemaSurql from './generated/schema.surql?raw';
-
-function App() {
-  return (
-    <SpookyProvider
-      config={{
-        database: {
-          endpoint: 'ws://localhost:8000',
-          namespace: 'my_ns',
-          database: 'my_db',
-          store: 'indexeddb',
-        },
-        schema,
-        schemaSurql,
-        logLevel: 'info',
-      }}
-      fallback={<div>Loading database...</div>}
-      onReady={(db) => console.log('DB ready')}
-      onError={(err) => console.error('DB failed', err)}
-    >
-      <MyApp />
-    </SpookyProvider>
-  );
-}
-```
-
-### SpookyProvider Props
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `config` | `SyncedDbConfig<S>` | Same as `SpookyConfig` from core |
-| `fallback` | `JSX.Element` | Shown while the database is initializing |
-| `onReady` | `(db: SyncedDb<S>) => void` | Called when initialization succeeds |
-| `onError` | `(error: Error) => void` | Called if initialization fails |
-| `children` | `JSX.Element` | App content, rendered after init |
-
-## useQuery
-
-The primary hook for reactive data fetching. Queries automatically re-subscribe when inputs change.
-
-### Context-based usage (recommended)
-
-```tsx
-import { useQuery } from '@spooky-sync/client-solid';
-import { QueryBuilder } from '@spooky-sync/query-builder';
-import { schema } from './generated/schema';
-
-function PostList() {
-  const db = useDb();
-
-  // Static query
-  const posts = useQuery(
-    db.query('post').orderBy('createdAt', 'desc').limit(20).build()
-  );
-
-  return (
-    <Show when={!posts.isLoading()} fallback={<div>Loading...</div>}>
-      <For each={posts.data()}>
-        {(post) => <div>{post.title}</div>}
-      </For>
-    </Show>
-  );
-}
-```
-
-### Reactive queries (function form)
-
-Wrap the query in a function to make it reactive to signal changes:
-
-```tsx
-function UserPosts(props: { userId: string }) {
-  const db = useDb();
-
-  // Query re-runs when props.userId changes
-  const posts = useQuery(
-    () => db.query('post')
-      .where({ author: props.userId })
-      .related('author')
-      .build()
-  );
-
-  return <For each={posts.data()}>{(post) => <div>{post.title}</div>}</For>;
-}
-```
-
-### Conditional queries
-
-Use the `enabled` option to conditionally run queries:
-
-```tsx
-const [userId, setUserId] = createSignal<string | null>(null);
-
-const user = useQuery(
-  () => userId()
-    ? db.query('user').where({ id: userId()! }).one().build()
-    : undefined,
-  { enabled: () => userId() !== null }
-);
-```
-
-### Return value
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `data` | `() => T \| undefined` | Reactive accessor for query results |
-| `error` | `() => Error \| undefined` | Reactive accessor for errors |
-| `isLoading` | `() => boolean` | `true` until first data arrives |
-
-### Explicit db overload
-
-You can also pass the `SyncedDb` instance directly (legacy):
-
-```tsx
-const posts = useQuery(db, db.query('post').build());
-```
-
-## useDb
-
-Access the `SyncedDb` instance from context:
-
-```tsx
-import { useDb } from '@spooky-sync/client-solid';
-
-function MyComponent() {
-  const db = useDb();
-  // db.query(), db.create(), db.update(), db.delete(), db.auth, etc.
-}
-```
-
-## Mutations
-
-Use the `SyncedDb` instance (from `useDb()`) for mutations:
-
-```tsx
-const db = useDb();
-
-// Create
-await db.create('post:abc', { title: 'Hello', body: 'World', author: 'user:alice' });
-
-// Update
-await db.update('post', 'post:abc', { title: 'Updated' });
-
-// Update with debounce
-await db.update('post', 'post:abc', { body: newText }, {
-  debounced: { key: 'recordId_x_fields', delay: 300 },
-});
-
-// Delete
-await db.delete('post', 'post:abc');
-```
-
-## Authentication
-
-```tsx
-const db = useDb();
-
-await db.auth.signUp('user_access', { email, password, name });
-await db.auth.signIn('user_access', { email, password });
-await db.auth.signOut();
-
-// Subscribe to auth state
-const unsub = db.auth.subscribe((userId) => { ... });
-```
-
-## File Upload & Download
-
-See [references/file-hooks.md](references/file-hooks.md) for details.
-
-```tsx
-import { useFileUpload, useDownloadFile } from '@spooky-sync/client-solid';
-
-// Upload
-const { upload, isUploading, error } = useFileUpload('avatars');
-await upload('alice/photo.png', file);
-
-// Download (reactive)
-const { url, isLoading } = useDownloadFile('avatars', () => user()?.avatarPath);
-```
-
-## Backend Runs
-
-```tsx
-const db = useDb();
-await db.run('email', '/send', { to: 'alice@example.com', subject: 'Hi', body: 'Hello' });
-```
-
-## Key Re-exports
-
-The package re-exports commonly needed types:
-
-```typescript
-import { RecordId, Uuid } from '@spooky-sync/client-solid';
-import type {
-  Model, GenericModel, QueryResult, TableModel, TableNames, GetTable,
-} from '@spooky-sync/client-solid';
-```

package/src/lib/SpookyProvider.ts

@@ -1,55 +0,0 @@
-import { createSignal, onMount, createComponent, createMemo, JSX, mergeProps } from 'solid-js';
-import type { SchemaStructure } from '@spooky/query-builder';
-import type { SyncedDbConfig } from '../types';
-import { SyncedDb } from '../index';
-import { SpookyContext } from './context';
-
-export interface SpookyProviderProps<S extends SchemaStructure> {
-  config: SyncedDbConfig<S>;
-  fallback?: JSX.Element;
-  onError?: (error: Error) => void;
-  onReady?: (db: SyncedDb<S>) => void;
-  children: JSX.Element;
-}
-
-export function SpookyProvider<S extends SchemaStructure>(
-  props: SpookyProviderProps<S>
-): JSX.Element {
-  const merged = mergeProps(
-    {
-      fallback: undefined as JSX.Element | undefined,
-    },
-    props
-  );
-
-  const [db, setDb] = createSignal<SyncedDb<S> | undefined>(undefined);
-
-  onMount(async () => {
-    try {
-      const instance = new SyncedDb<S>(merged.config);
-      await instance.init();
-      setDb(() => instance);
-      merged.onReady?.(instance);
-    } catch (e) {
-      const error = e instanceof Error ? e : new Error(String(e));
-      if (merged.onError) {
-        merged.onError(error);
-      } else {
-        console.error('SpookyProvider: Failed to initialize database', error);
-      }
-    }
-  });
-
-  const content = createMemo(() => {
-    const instance = db();
-    if (!instance) return merged.fallback;
-    return createComponent(SpookyContext.Provider, {
-      value: instance,
-      get children() {
-        return merged.children;
-      },
-    });
-  });
-
-  return content as unknown as JSX.Element;
-}