@spooky-sync/client-solid 0.0.1-canary.16 → 0.0.1-canary.160

package/AGENTS.md

@@ -0,0 +1,68 @@
+# `@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.
+  - `db.delete(table, idOrSelector)`.
+  - `db.query(table)` — returns a `QueryBuilder`. Chain `.related()`, `.orderBy()`, `.limit()`, etc., end with `.build()`.
+  - `db.preload(query, options?)` — cache-aware, awaitable prewarm. Cold (nothing cached in the bucket) fetches + persists and the promise awaits it (blocks); warm returns instantly. `options.refresh` (`'onUse'` default / `'background'` / `'stale'`) + `options.staleTime` control warm-refresh. One-shot snapshot, no live view — freshens on use.
+  - `db.run(backend, route, payload)` — call a backend RPC route.
+  - `db.bucket(name)` — get a `BucketHandle` for file storage.
+  - `db.useRemote(fn)` — escape hatch to the raw `Surreal` client (skips cache).
+  - `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 `refresh`/`staleTime`). Warms a query the user is likely to open next (e.g. a list row's detail) into the local cache. For blocking first-load, use the `Sp00kyProvider` `preload` prop instead.
+- **`useCrdtField(table, () => recordId, field, () => valueAccessor)`** — wires a CRDT text field to a Loro doc. Pair with `db.update(table, id, { [field]: newValue }, { debounced: true })` so rapid keystrokes don't flood the queue. *All four arguments take accessor functions where reactive — that's deliberate, for SolidJS tracking.*
+- **`useFileUpload()`** / **`useDownloadFile()`** — bucket helpers; the upload result includes the storage path you write into a record column.
+
+## 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.
+- **CRDT fields are not regular columns.** Don't read or write them via `useQuery` — read with `useCrdtField`, write via `db.update` with `{ debounced: true }`.
+- **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