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

package/AGENTS.md

@@ -39,9 +39,13 @@ 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`).
+- **`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.
 

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.
 
@@ -113,7 +116,7 @@ Track a backend job's progress by querying its outbox row: `createQuery(() => db
 
 ## Status hooks
 
-Same shapes as client-solid, rebuilt on async-iterable-backed memos: `useSyncStatus`, `useStorageStatus`, `usePendingMutations`, `useFeatureFlag`, `useAppRelease`, `useCrdtField`, `useFileUpload`, `useDownloadFile`, `createPreload`.
+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
 

package/README.md

@@ -7,8 +7,8 @@ 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.
-- Status hooks (`useSyncStatus`, `useStorageStatus`, `usePendingMutations`, feature flags, app release) are async-iterable-backed memos with `loadingValue`.
+- `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).

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
 	};
 }
@@ -374,6 +387,57 @@ function useSyncStatus() {
 	};
 }
 
+//#endregion
+//#region src/lib/use-sync-activity.ts
+/**
+* The two directions of sync traffic, for an indicator in the app chrome.
+*
+* `fetchingQueries` is one subscription on the engine's aggregate fetch count,
+* not one per query; `pendingMutations` is the outbox depth. `isDownloading`
+* is the fetch count debounced ON by `downloadDelayMs` (and off at once), so a
+* local-first page that answers from cache and confirms with the server in a
+* few milliseconds never flickers. Must be used within a `<Sp00kyProvider>`, or
+* pass the `SyncedDb` explicitly.
+*/
+function useSyncActivity(dbOrOptions, maybeOptions) {
+	const explicitDb = dbOrOptions && typeof dbOrOptions.subscribeToFetchActivity === "function" ? dbOrOptions : void 0;
+	const options = (explicitDb ? maybeOptions : dbOrOptions) ?? {};
+	const db = explicitDb ?? useDb();
+	const downloadDelayMs = options.downloadDelayMs ?? 200;
+	const uploadThreshold = options.uploadThreshold ?? 1;
+	const fetchingQueries = fromSubscription((cb) => db.subscribeToFetchActivity(cb), db.fetchingQueryCount);
+	const pendingMutations = fromSubscription((cb) => db.subscribeToPendingMutations(cb), db.pendingMutationCount);
+	const [isDownloading, setIsDownloading] = (0, solid_js.createSignal)(false, { ownedWrite: true });
+	let timer;
+	(0, solid_js.createEffect)(() => fetchingQueries() > 0, (busy) => {
+		if (timer !== void 0) {
+			clearTimeout(timer);
+			timer = void 0;
+		}
+		if (!busy) {
+			setIsDownloading(false);
+			return;
+		}
+		if (downloadDelayMs <= 0) {
+			setIsDownloading(true);
+			return;
+		}
+		timer = setTimeout(() => {
+			timer = void 0;
+			setIsDownloading(true);
+		}, downloadDelayMs);
+	});
+	(0, solid_js.onCleanup)(() => {
+		if (timer !== void 0) clearTimeout(timer);
+	});
+	return {
+		fetchingQueries,
+		pendingMutations,
+		isDownloading,
+		isUploading: () => pendingMutations() > uploadThreshold
+	};
+}
+
 //#endregion
 //#region src/lib/use-storage-status.ts
 /**
@@ -1150,6 +1214,19 @@ var SyncedDb = class {
 		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
 		return this.sp00ky.subscribeToPendingMutations(cb);
 	}
+	/** Queries mid-fetch right now. See {@link useSyncActivity}. */
+	get fetchingQueryCount() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.fetchingQueryCount;
+	}
+	/**
+	* Observe how many queries are fetching from the server. Fires immediately
+	* and on every change. Prefer the `useSyncActivity` hook in components.
+	*/
+	subscribeToFetchActivity(cb) {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.subscribeToFetchActivity(cb);
+	}
 	/** Current sync-health snapshot. See {@link useSyncStatus}. */
 	get syncHealth() {
 		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
@@ -1210,5 +1287,6 @@ exports.useFileUpload = useFileUpload;
 exports.usePendingMutations = usePendingMutations;
 exports.useQuery = useQuery;
 exports.useStorageStatus = useStorageStatus;
+exports.useSyncActivity = useSyncActivity;
 exports.useSyncStatus = useSyncStatus;
 //# sourceMappingURL=index.cjs.map