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

package/AGENTS.md

@@ -0,0 +1,81 @@
+# `@spooky-sync/client-solid2` — agent guide
+
+## What this package is
+
+The **Solid 2.0** binding for sp00ky. Counterpart of `@spooky-sync/client-solid` (Solid 1.x); the two coexist until Solid 2.0 is stable and an app uses exactly one. Peers: `solid-js@^2.0.0-rc.0` + `@solidjs/signals@^2.0.0-rc.0` (coordinated RC, pin matching versions); apps also need `@solidjs/web` and `jsxImportSource: "@solidjs/web"`.
+
+Solid-2 native internals: query results live in a `createProjection` fed by an async generator over the engine's live subscription (keyed reconcile by `id`, row identity preserved, `<For>` notified on add/remove/reorder — no version-signal hack). Status hooks are async-iterable-backed memos with a `loadingValue`. Teardown is `onCleanup`-driven, because Solid 2 abandons superseded async generators without terminating them.
+
+## Setup pattern
+
+```ts
+// db.ts
+import type { SyncedDbConfig } from '@spooky-sync/client-solid2';
+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: 'indexeddb',
+  },
+};
+```
+
+```tsx
+// App.tsx
+<Sp00kyProvider config={dbConfig} fallback={<Splash />}>{/* app */}</Sp00kyProvider>
+```
+
+Provider props are identical to client-solid: `config`, `fallback`, `preload` (awaited gate before children render), `onReady`, `onError`. A mounted client is deliberately not closed on unmount.
+
+## Key API
+
+- **`useDb<typeof schema>()`** — the `SyncedDb<S>` instance. Same surface as client-solid: `create`, `update`, `delete`, `query`, `preload`, `run`, `bucket`, `remoteQuery`, `useRemote`, `auth`/`signOut`, `pendingMutationCount`, `subscribeToPendingMutations`, `syncHealth`/`storageHealth` + their subscribe methods.
+- **`createQuery(query, options?)`** (or `createQuery(db, query, options?)`) — reactive query. `useQuery` is a deprecated alias. Pass a thunk when the query depends on signals; read the signals inside it.
+  - `data()` — non-suspending. `[]` / `null` before the first result, keyed-reconciled live rows after.
+  - `ready()` — suspending read for `<Loading fallback={...}>` (Solid 2's renamed `<Suspense>`).
+  - `error()` — registration/sync failure (e.g. SSP 503 NOT_READY). Never thrown into the render tree; the sync scheduler retries underneath.
+  - `isLoading()` — cold first load only (nothing painted for this identity, server not heard, no error). A cached paint ends it; an authoritative empty answer ends it. Never true again for the same identity.
+  - `isFetching()` — a fetch cycle is in flight (registration, a sync round).
+  - `isAuthoritative()` — server membership is known for this identity (latched until it changes). `hasData()` — `data()` holds something. `isEmpty()` — authoritative AND no data: the server said "no rows"; render empty states on this, not on `!hasData()`.
+  - `isSettled()` — authoritative AND idle; gate windowed-list end detection on it. Not monotonic; latch it (a `createMemo(prev => prev || q.isSettled())`) for a verdict that must stick.
+  - Options: `enabled?: () => boolean`, `deregisterOnCleanup?: boolean`.
+- **`createSubmission(fn)`** — button pending/error state around a mutation: `submit()`, `pending()`, `error()`, `result()`, `clearError()`. There is deliberately no `action()` / `createOptimisticStore` layer (see `src/lib/create-submission.ts`).
+- **`useSyncActivity(options?)`** — `{ fetchingQueries, pendingMutations, isDownloading, isUploading }`. One subscription on the engine's aggregate fetch count plus the outbox depth; `isDownloading()` is debounced ON by `downloadDelayMs` (200) and off at once, `isUploading()` is `pendingMutations() > uploadThreshold` (1). Drive a logo/traffic indicator off it; pair with `useSyncStatus().isOffline()` to show the unsaved count while disconnected.
+- **`createPreload`**, **`usePendingMutations`**, **`useSyncStatus`**, **`useStorageStatus`**, **`useFeatureFlag`**, **`useAppRelease`**, **`useCrdtField`**, **`useFileUpload`**, **`useDownloadFile`** — same shapes as client-solid.
+- **`conflate`**, **`fromSubscription`** — the async-iterable helpers the hooks are built on; useful for wrapping other engine subscriptions.
+
+## Mutations
+
+The engine is optimistic local-first end to end (local commit → live queries re-emit → outbox sync; `db.run()` writes an outbox job row with `status: 'pending'`). So mutations are plain awaited calls, no optimistic-update layer on top:
+
+```ts
+await db.create('post:' + crypto.randomUUID(), { title: 'Hi' });
+await db.update('post', 'post:xyz', { title: 'Edited' });
+await db.delete('post', row.id);
+await db.run('backend', 'sendMail', { to });
+```
+
+Track a backend job by querying its outbox row: `createQuery(() => db.query('job_outbox').where({ id: jobId() }).one().build())`.
+
+## Common gotchas
+
+- **Rows are store proxies.** Solid 2 stores wrap class instances too and serve their methods **bound**, so a `RecordId` read out of a row reports `constructor.name === 'bound RecordId'`. `db.delete('post', row.id)` handles that; for surrealdb APIs that check `instanceof`, unwrap first with `snapshot(row)` from `solid-js`.
+- **`<Loading>`, not `<Suspense>`.** Only `ready()` suspends; `data()` never does, which is what keeps local-first cache paints instant.
+- **`data()` is never `undefined`.** It is born `[]` / `null` (`seedLoadingValue`), unlike client-solid. Branch on `isLoading()`, not on nullish data.
+- **Coordinated RC.** `solid-js`, `@solidjs/web`, `@solidjs/signals` must be on matching `2.0.0-rc.x` versions. After any Solid bump, run `src/lib/__tests__/rc-semantics.test.ts` — it probes the RC contracts this package depends on.
+- **Vitest resolves the SSR build.** Under Node, `solid-js`'s `node` export condition gives you the SSR build where user effects never run. Set `resolve.conditions: ['browser', 'development']` (see this package's `vitest.config.ts`).
+- **`createQuery` factories must call `.build()`** (or `.all()`, `.one()`, …). A bare `db.query('post')` is a builder, not a query.
+- **Provider is mandatory.** Any hook outside `<Sp00kyProvider>` throws.
+
+## Pointers
+
+- Usage walkthrough + migration table: `QUICK_START.md` (same content as the docs' [Solid 2 guide](https://mono424.github.io/sp00ky/docs/guide/solid2))
+- Skill for coding agents: `skills/sp00ky-solid2/SKILL.md`
+- Solid 1.x binding: `node_modules/@spooky-sync/client-solid/AGENTS.md`
+- Sync engine: `node_modules/@spooky-sync/core/AGENTS.md`
+- Query builder DSL: `node_modules/@spooky-sync/query-builder/AGENTS.md`

package/QUICK_START.md

@@ -0,0 +1,129 @@
+# @spooky-sync/client-solid2 — Quick Start
+
+Solid **2.0** native bindings for the Sp00ky reactive local-first SurrealDB framework. This is the Solid 2 counterpart of `@spooky-sync/client-solid` (which stays on Solid 1.x); the two packages coexist until Solid 2.0 is stable and apps migrate.
+
+## Install
+
+```bash
+pnpm add @spooky-sync/client-solid2 solid-js@2.0.0-rc.0 @solidjs/web@2.0.0-rc.0 @solidjs/signals@2.0.0-rc.0
+```
+
+> **Coordinated RC**: `solid-js`, `@solidjs/web`, and `@solidjs/signals` must be on matching `2.0.0-rc.x` versions. Pin exact versions; this package's semantics probes (`rc-semantics.test.ts`) catch drift on bumps. `jsxImportSource` is `@solidjs/web` in Solid 2.
+
+## Provider
+
+```tsx
+import { Sp00kyProvider } from '@spooky-sync/client-solid2';
+import { schema } from './generated/schema';
+import schemaSurql from './generated/schema.surql?raw';
+
+function App() {
+  return (
+    <Sp00kyProvider
+      config={{
+        database: { endpoint: 'ws://localhost:8000', namespace: 'my_ns', database: 'my_db', store: 'indexeddb' },
+        schema,
+        schemaSurql,
+      }}
+      fallback={<div>Loading database…</div>}
+      preload={async (db) => { await db.preload(db.query('config').build()); }}
+    >
+      <MyApp />
+    </Sp00kyProvider>
+  );
+}
+```
+
+Same props as client-solid's provider (`config`, `fallback`, `preload`, `onReady`, `onError`). A live mounted client is deliberately not closed on unmount (see source comment).
+
+## createQuery
+
+`createQuery` replaces `useQuery` (which remains as a deprecated alias). Same overloads: `(query, options?)` with context, or `(db, query, options?)`.
+
+```tsx
+import { createQuery, useDb } from '@spooky-sync/client-solid2';
+
+function PostList() {
+  const db = useDb();
+  const posts = createQuery(db.query('post').orderBy('createdAt', 'desc').limit(20).build());
+
+  // Accessor style — data() never suspends, born as [] and live thereafter:
+  return (
+    <Show when={!posts.isLoading()} fallback={<div>Loading…</div>}>
+      <For each={posts.data()}>{(post) => <PostRow post={post} />}</For>
+    </Show>
+  );
+}
+```
+
+Reactive inputs: pass a thunk, read your signals inside it.
+
+```tsx
+const post = createQuery(() => (postId() ? db.query('post').where({ id: postId() }).one().build() : null));
+```
+
+### Suspension style (`<Loading>`)
+
+`q.ready()` reads the same data but participates in Solid 2's boundary protocol: it pends until the first real result.
+
+```tsx
+import { Loading } from 'solid-js';
+
+<Loading fallback={<Skeleton />}>
+  <For each={posts.ready()}>{(post) => <PostRow post={post} />}</For>
+</Loading>
+```
+
+### Result surface
+
+| Accessor | Meaning |
+|---|---|
+| `data()` | Rows (or row/`null` for `.one()`). Never suspends, never throws. Keyed-reconciled in place: unchanged rows keep identity, `<For>` is notified on add/remove/reorder. |
+| `ready()` | Same data, suspends into the nearest `<Loading>` until first result or error. |
+| `error()` | Registration/sync error (e.g. SSP 503 during bootstrap). Never thrown into the render tree; the sync scheduler retries underneath. |
+| `isLoading()` | Cold first load only: nothing painted for this identity yet, server not heard, no error. A cached paint ends it; so does the server answering with zero rows. |
+| `isFetching()` | Sync engine is pulling records for this query. |
+| `isAuthoritative()` | Server membership is known for this identity (registration/poll landed, or a previous session's membership was read on boot). Latched until the identity changes. |
+| `hasData()` | `data()` holds rows (or the `.one()` row). |
+| `isEmpty()` | Authoritative AND no data — the server said "no rows". Render empty states on this. |
+| `isSettled()` | Authoritative AND idle — windowed lists may trust a short result as the true end of the list. Re-enters on later sync rounds; latch it for a sticky verdict. |
+
+Options: `{ enabled?: () => boolean, deregisterOnCleanup?: boolean }` — both as in client-solid.
+
+### Gotcha: rows are store proxies
+
+Solid 2 stores wrap class instances too, and serve methods bound. A `RecordId` read out of a row works for display and for `db.delete('table', row.id)`, but if you pass whole row objects back into surrealdb APIs that check `instanceof`, unwrap first with `snapshot(row)` (exported by `solid-js`).
+
+## Mutations
+
+Engine writes are already optimistic local-first (local commit → live queries re-emit → outbox sync; `db.run()` is itself an outbox job row with `status: 'pending'`). Plain calls:
+
+```ts
+await db.create('post:xyz', { title: 'Hi' });
+await db.update('post', 'post:xyz', { title: 'Edited' });
+await db.delete('post', row.id);
+await db.run('backend', 'sendMail', { to });
+```
+
+For button pending/error state, wrap with `createSubmission`:
+
+```tsx
+const save = createSubmission((title: string) => db.create(`post:${crypto.randomUUID()}`, { title }));
+<button disabled={save.pending()} onClick={() => save.submit(title())}>Save</button>
+```
+
+Track a backend job's progress by querying its outbox row: `createQuery(() => db.query('job_outbox').where({ id: jobId() }).one().build())`.
+
+## Status hooks
+
+Same shapes as client-solid, rebuilt on async-iterable-backed memos: `useSyncStatus`, `useStorageStatus`, `usePendingMutations`, `useSyncActivity` (new: `isDownloading()` after 200 ms of fetching, `isUploading()` above one queued write, for a traffic indicator), `useFeatureFlag`, `useAppRelease`, `useCrdtField`, `useFileUpload`, `useDownloadFile`, `createPreload`.
+
+## Migrating from client-solid
+
+| client-solid (Solid 1) | client-solid2 (Solid 2) |
+|---|---|
+| `useQuery(q)` | `createQuery(q)` (alias `useQuery` kept) |
+| `data()` may be `undefined` pre-fetch | `data()` is `[]` / `null` pre-fetch |
+| No suspension | `ready()` + `<Loading>` |
+| `useDb()` throws custom error | same API (Solid 2 context throws on missing provider) |
+| everything else | unchanged call signatures |

package/README.md

@@ -0,0 +1,19 @@
+# @spooky-sync/client-solid2
+
+Solid **2.0** native bindings for the Sp00ky reactive local-first SurrealDB framework.
+
+Counterpart of `@spooky-sync/client-solid` (Solid 1.x); the two coexist until Solid 2.0 is stable. Peer deps: `solid-js@^2.0.0-rc.0` + `@solidjs/signals@^2.0.0-rc.0` (coordinated RC — pin matching versions, apps also need `@solidjs/web`).
+
+What "native" means here:
+
+- Query results are a plain store written from the engine's live subscription and merged keyed by `id`: row identity preserved, coarse `<For>` readers notified, only changed fields written. Not an async-generator projection - see `create-query.ts` for why a never-returning generator breaks navigation transitions.
+- `createQuery` exposes both worlds: non-suspending accessors (`data`, `isLoading`, `isFetching`, `isAuthoritative`, `hasData`, `isEmpty`, `isSettled`, `error`) and a suspending `ready()` for `<Loading>` boundaries. Born committed, so local-first cache paints never suspend. `isLoading()` is true only on a cold first load (nothing cached, server not heard yet); `isEmpty()` is the server saying "no rows".
+- Status hooks (`useSyncStatus`, `useSyncActivity`, `useStorageStatus`, `usePendingMutations`, feature flags, app release) are async-iterable-backed memos with `loadingValue`. `useSyncActivity` is the traffic indicator pair: `isDownloading()` (queries fetching for longer than 200 ms) and `isUploading()` (more than one write queued), plus the raw `fetchingQueries()` / `pendingMutations()` counts.
+- Mutations stay plain async calls — the engine is already optimistic local-first end to end (local commit → live re-emit → outbox sync). `createSubmission` adds button pending/error state.
+
+See `QUICK_START.md` for usage and the migration table from client-solid, and `src/lib/__tests__/rc-semantics.test.ts` for the probed Solid 2 rc contracts this package depends on (run them after every Solid version bump).
+
+```bash
+pnpm --filter @spooky-sync/client-solid2 test
+pnpm --filter @spooky-sync/client-solid2 build
+```