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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khadim Fall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/QUICK_START.md

@@ -0,0 +1,126 @@
+# @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()` | No result yet and no error. |
+| `isFetching()` | Sync engine is pulling records for this query. |
+| `isSettled()` | Delivered AND idle — windowed lists may trust a short result as the true end of the list. |
+
+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`, `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 `createProjection` fed by an async generator over the engine's live subscription: keyed reconcile by `id`, row identity preserved, coarse `<For>` readers notified — no manual reconcile/version-signal plumbing.
+- `createQuery` exposes both worlds: non-suspending accessors (`data`, `isLoading`, `isFetching`, `isSettled`, `error`) and a suspending `ready()` for `<Loading>` boundaries. Born committed (`seedLoadingValue`), so local-first cache paints never suspend.
+- Status hooks (`useSyncStatus`, `useStorageStatus`, `usePendingMutations`, feature flags, app release) are async-iterable-backed memos with `loadingValue`.
+- 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
+```