@spooky-sync/client-solid2 0.0.1-canary.237 → 0.0.1-canary.238

package/AGENTS.md

@@ -39,7 +39,10 @@ Provider props are identical to client-solid: `config`, `fallback`, `preload` (a
   - `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()` / `isFetching()` / `isSettled()` — `isSettled()` means delivered AND idle; gate windowed-list end detection on it.
+  - `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`).
 - **`createPreload`**, **`usePendingMutations`**, **`useSyncStatus`**, **`useStorageStatus`**, **`useFeatureFlag`**, **`useAppRelease`**, **`useCrdtField`**, **`useFileUpload`**, **`useDownloadFile`** — same shapes as client-solid.

package/QUICK_START.md

@@ -81,9 +81,12 @@ import { Loading } from 'solid-js';
 | `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. |
+| `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. |
-| `isSettled()` | Delivered AND idle — windowed lists may trust a short result as the true end of the list. |
+| `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.
 

package/README.md

@@ -7,7 +7,7 @@ Counterpart of `@spooky-sync/client-solid` (Solid 1.x); the two coexist until So
 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`, `isSettled`, `error`) and a suspending `ready()` for `<Loading>` boundaries. Born committed, so local-first cache paints never suspend.
+- `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`, `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.
 

package/dist/index.cjs

@@ -197,7 +197,8 @@ function createQuery(dbOrQuery, queryOrOptions, maybeOptions) {
 	}
 	const sp00ky = db.getSp00ky();
 	const [error, setError] = (0, solid_js.createSignal)(void 0, { ownedWrite: true });
-	const [isFetched, setIsFetched] = (0, solid_js.createSignal)(false, { ownedWrite: true });
+	const [isAuthoritative, setIsAuthoritative] = (0, solid_js.createSignal)(false, { ownedWrite: true });
+	const [hasPainted, setHasPainted] = (0, solid_js.createSignal)(false, { ownedWrite: true });
 	const [isFetching, setIsFetching] = (0, solid_js.createSignal)(false, { ownedWrite: true });
 	let activeHash;
 	const [store, setStore] = (0, solid_js.createStore)({ value: null });
@@ -215,7 +216,8 @@ function createQuery(dbOrQuery, queryOrOptions, maybeOptions) {
 		};
 	}, ({ enabled, query }) => {
 		const myRun = ++runId;
-		setIsFetched(false);
+		setIsAuthoritative(false);
+		setHasPainted(false);
 		setError(void 0);
 		if (!enabled || !query) return;
 		const cleanups = [];
@@ -244,16 +246,19 @@ function createQuery(dbOrQuery, queryOrOptions, maybeOptions) {
 			if (disposed || myRun !== runId) return;
 			activeHash = hash;
 			addCleanup(sp00ky.subscribeQueryStatus(hash, (status) => setIsFetching(status === "fetching"), { immediate: true }));
-			let isFirstCall = true;
+			addCleanup(sp00ky.subscribeQueryAuthority(hash, (known) => {
+				if (disposed || myRun !== runId) return;
+				setIsAuthoritative(known);
+				if (known) wakeReady();
+				else setHasPainted(false);
+			}, { immediate: true }));
 			addCleanup(sp00ky.subscribe(hash, (rows) => {
 				if (disposed || myRun !== runId) return;
 				const queryData = query.isOne ? rows[0] ?? null : rows;
-				const hasData = query.isOne ? queryData !== null && queryData !== void 0 : rows.length > 0;
-				if (!isFirstCall || hasData) {
-					setIsFetched(true);
+				if (query.isOne ? queryData !== null && queryData !== void 0 : rows.length > 0) {
+					setHasPainted(true);
 					wakeReady();
 				}
-				isFirstCall = false;
 				const t0 = performance.now();
 				setStore((s) => {
 					if (query.isOne || queryData === null || !Array.isArray(s.value)) s.value = queryData;
@@ -281,7 +286,7 @@ function createQuery(dbOrQuery, queryOrOptions, maybeOptions) {
 		return v;
 	};
 	const readyGate = (0, solid_js.createMemo)(async () => {
-		if (isFetched() || error()) return true;
+		if (isAuthoritative() || hasPainted() || error()) return true;
 		await new Promise((resolve) => readyWaiters.push(resolve));
 		return true;
 	}, { lazy: true });
@@ -292,14 +297,22 @@ function createQuery(dbOrQuery, queryOrOptions, maybeOptions) {
 	(0, solid_js.onCleanup)(() => {
 		if (options?.deregisterOnCleanup && activeHash) sp00ky.deregisterQuery(activeHash);
 	});
-	const isLoading = () => !isFetched() && error() === void 0;
-	const isSettled = () => isFetched() && !isFetching();
+	const hasData = () => {
+		const v = store.value;
+		return Array.isArray(v) ? v.length > 0 : v !== null && v !== void 0;
+	};
+	const isLoading = () => !isAuthoritative() && !hasPainted() && error() === void 0;
+	const isEmpty = () => isAuthoritative() && !hasData();
+	const isSettled = () => isAuthoritative() && !isFetching();
 	return {
 		data,
 		ready,
 		error,
 		isLoading,
 		isFetching,
+		isAuthoritative,
+		hasData,
+		isEmpty,
 		isSettled
 	};
 }