@spooky-sync/client-solid 0.0.1-canary.33 → 0.0.1-canary.330

package/AGENTS.md

@@ -0,0 +1,70 @@
+# `@spooky-sync/client-solid` — agent guide
+
+## What this package is
+
+The SolidJS binding for sp00ky. Exposes a `Sp00kyProvider` that initializes a `Sp00kyClient` and a set of reactive hooks (`useDb`, `useQuery`, `useCrdtField`, `useFileUpload`, `useDownloadFile`). All hooks expect to be called inside a `<Sp00kyProvider>` boundary.
+
+## Setup pattern
+
+```ts
+// db.ts
+import type { SyncedDbConfig } from '@spooky-sync/client-solid';
+import { schema, SURQL_SCHEMA } from './schema.gen'; // generated by `spky generate`
+
+export const dbConfig: SyncedDbConfig<typeof schema> = {
+  schema,
+  schemaSurql: SURQL_SCHEMA,
+  database: {
+    namespace: 'main',
+    database: 'app',
+    endpoint: 'ws://localhost:8666/rpc',
+    store: 'memory',           // or 'indexeddb' for persistence
+    persistenceClient: 'localstorage',
+  },
+};
+```
+
+```tsx
+// App.tsx
+<Sp00kyProvider config={dbConfig}>{/* app */}</Sp00kyProvider>
+```
+
+## Key hooks
+
+- **`useDb<typeof schema>()`** — returns the `SyncedDb<S>` instance. Methods:
+  - `db.create(id, payload)` — `id` is a full record ID like `'thread:abc'`.
+  - `db.update(table, id, payload, options?)` — `options.debounced` coalesces updates; with `flushOnHide` (default `true`) a pending patch survives a reload or closed tab.
+  - `db.delete(table, idOrSelector)`.
+  - `db.query(table)` — returns a `QueryBuilder`. Chain `.related()`, `.orderBy()`, `.limit()`, etc., end with `.build()`.
+  - `db.preload(query, options?)` — registers the query without subscribing. Resolved before on this device: returns instantly. Never resolved: awaits the server's membership and every record. Signed out without `enableAnonymousLiveQueries`: returns instantly (no membership is ever sent to that session). `options.signal` aborts a cold wait; `refresh`/`staleTime` are ignored. Evicted a ttl after registration unless a view mounts the same query.
+  - `db.run(backend, route, payload)` — call a backend RPC route.
+  - `db.bucket(name)` — get a `BucketHandle` for file storage.
+  - `db.remoteQuery(sql, vars?)` — one-shot remote read through the client's queued, connect-gated path (skips cache).
+  - `db.useRemote(fn)` — escape hatch to the raw `Surreal` client (skips cache AND the connect gate).
+  - `db.authenticate(token)`, `db.signOut()`, `db.auth`.
+  - `db.pendingMutationCount`, `db.subscribeToPendingMutations(cb)`.
+- **`useQuery(() => db.query(...).build())`** — reactive query. Returns `{ data, status, error, ... }` accessors. The factory function is tracked, so passing reactive params (signals) re-runs the query.
+- **`createPreload(() => db.query(...).build(), options?)`** — reactive, fire-and-forget prewarm (same overloads/`enabled` as `useQuery`, plus `signal`). Registers a query the user is likely to open next (e.g. a list row's detail). For blocking first-load, use the `Sp00kyProvider` `preload` prop instead.
+- **`useCrdtField(table, () => recordId, field)`**: opens a `@crdt` field and returns an accessor that is `null` until it is open, then a `CrdtField`. Bind the editor to `field()?.getDoc()` (a `LoroDoc`: `loro-prosemirror` plugins for `@crdt prosemirror`, `doc.getText(field)` for `@crdt text`); edits sync themselves, so there is no `db.update` for them. Reopens when the id changes, closes on cleanup. To give a not-yet-created record content, use `db.getSp00ky().createCrdtDraft(table, field)`, then after `db.create` call `openCrdtField(table, id, field, draft)` and `await closeCrdtField(...)`. Only the record id is an accessor.
+- **`useImpersonation()`**: `{ impersonation, isImpersonating, stop }` for admin impersonation started from the DevTools (`impersonation.enabled` in sp00ky.yml). The client already renders its own warning bar with a Stop button; use the hook only for extras, such as hiding destructive actions while impersonating, or pass `{ rendersBanner: true }` when the app draws its own banner under `impersonationBanner: { mode: 'custom' }`. See `/docs/client/impersonation`.
+- **`useFileUpload()`** / **`useDownloadFile()`** — bucket helpers; the upload result includes the storage path you write into a record column. `useDownloadFile` reads through the durable OPFS blob cache (options `{ cache, persist, pin, revalidate }`), so images survive a reload and paint offline; `refetch()` bypasses every layer.
+
+## Re-exports for convenience
+
+- `RecordId`, `Uuid` from `surrealdb`.
+- Query-builder types: `TableModel`, `TableNames`, `GetTable`, `QueryResult`, etc. (see `@spooky-sync/query-builder/AGENTS.md`).
+- `Model<S, T>`, `GenericModel`, `ModelPayload` — typed row shapes.
+
+## Common gotchas
+
+- **`useDb()` requires `<typeof schema>`.** Without the generic, all calls fall back to `unknown` and you lose type safety.
+- **A `@crdt` column is the server-written plain text of its document.** Read it with `useQuery` for previews, search and filters (it trails live edits until the server folds, a few seconds); edit it only through `useCrdtField`. Set it only in the `db.create` that makes the record (its initial text, so lists show it before the first fold); a later `db.update` keeps the old value.
+- **Generate IDs explicitly.** `const id = new Uuid().toString()`, then `db.create(\`thread:\${id}\`, ...)`. SurrealDB's auto-id only fires on direct DB writes, not through the sync queue.
+- **`useQuery` factories must call `.build()` (or `.all()`, `.first()`, etc.).** A bare `db.query('thread')` is a builder, not a query — `useQuery` will throw or return forever-loading.
+- **Provider is mandatory.** Calling any hook outside `<Sp00kyProvider>` throws.
+
+## Pointers
+
+- Sync engine: `node_modules/@spooky-sync/core/AGENTS.md`
+- Query builder DSL: `node_modules/@spooky-sync/query-builder/AGENTS.md`
+- Schema authoring + codegen: `node_modules/@spooky-sync/cli/AGENTS.md`

package/README.md

@@ -11,6 +11,7 @@ A SurrealDB client for Solid.js with automatic cache synchronization and live qu
 - **Type-Safe**: Full TypeScript support with generated schema types
 - **Reactive**: Seamless integration with Solid.js reactivity
 - **Offline Support**: Local cache works even when remote is temporarily unavailable
+- **Preload / Prewarm**: Warm data into the local cache ahead of time so screens open instantly — awaitable to gate first load, reactive to prefetch what's next
 
 ## Quick Start
 
@@ -215,6 +216,25 @@ const liveQuery = await db.query.thread
   .orderBy('created_at', 'desc'); // ✅ Field names autocompleted
 ```
 
+### Preload / Prewarm
+
+Warm a query's results into the local cache before they're needed, so a later `useQuery` paints
+instantly instead of waiting on the network. Preload is a one-shot snapshot — it does not register
+a live view; the data freshens on use when the real `useQuery` mounts.
+
+```typescript
+// Awaitable + cache-aware: blocks on the FIRST load (nothing cached), returns
+// instantly on later loads (already cached). Great for gating the UI on config.
+await db.preload(db.query('config').build());
+
+// Opt into a one-time background refresh when the cache is stale:
+await db.preload(db.query('config').build(), { refresh: 'stale', staleTime: '1d' });
+```
+
+Block first-load UI on essential data via the `Sp00kyProvider` `preload` prop, or reactively
+prefetch what the user is likely to open next with `createPreload(() => …build())`. Full details
+in the [SKILL guide](./skills/sp00ky-solid/SKILL.md#preload).
+
 ## Documentation
 
 - **[Quick Start Guide](./QUICK_START.md)**: Get up and running quickly