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

package/AGENTS.md

@@ -45,7 +45,7 @@ Provider props are identical to client-solid: `config`, `fallback`, `preload` (a
   - `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.
+- **`useSyncActivity(options?)`** — `{ fetchingQueries, pendingMutations, isDownloading, isUploading }`. One subscription on the engine's aggregate fetch count plus the outbox depth; both are debounced ON by their delay (`downloadDelayMs` 200, `uploadDelayMs` 150) and off at once, and `isUploading()` additionally needs `pendingMutations() > uploadThreshold` (0, so any unacknowledged write counts). Drive a logo/traffic indicator off it; pair with `useSyncStatus().connection()` / `.isOffline()` to switch the same mark to a reconnecting or offline state and show the unsaved count.
 - **`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

@@ -116,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`, `useSyncActivity` (new: `isDownloading()` after 200 ms of fetching, `isUploading()` above one queued write, for a traffic indicator), `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()` after 150 ms of a queued write, for a traffic indicator), `useFeatureFlag`, `useAppRelease`, `useCrdtField`, `useFileUpload`, `useDownloadFile`, `createPreload`.
 
 ## Migrating from client-solid
 

package/README.md

@@ -8,7 +8,7 @@ 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.
+- 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()` (writes queued for longer than 150 ms), 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

@@ -324,8 +324,9 @@ const useQuery = createQuery;
 /**
 * Reactive, fire-and-forget prewarm. Resolves the query (calling it if it's a
 * function so it tracks reactive deps), dedupes on the query's stable identity
-* hash, and warms it into the local cache via `db.preload`. No subscription and
-* no cleanup: preload registers nothing that needs tearing down.
+* hash, and registers it via `db.preload`: a live query nobody subscribes to,
+* evicted a ttl after it was registered unless a view mounts it first. Nothing
+* to clean up here.
 *
 * Typical use: inside a list row, preload the detail query the user is likely
 * to open next, so navigation paints from cache instead of the network.
@@ -353,10 +354,7 @@ function createPreload(dbOrQuery, queryOrOptions, maybeOptions) {
 		return query;
 	}, (query) => {
 		if (!query) return;
-		db.getSp00ky().preload(query, {
-			refresh: options?.refresh,
-			staleTime: options?.staleTime
-		});
+		db.getSp00ky().preload(query, { signal: options?.signal });
 	});
 }
 
@@ -393,10 +391,10 @@ function useSyncStatus() {
 * 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
+* not one per query; `pendingMutations` is the outbox depth. Both
+* `isDownloading` and `isUploading` are debounced ON by their delay (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) {
@@ -404,38 +402,47 @@ function useSyncActivity(dbOrOptions, maybeOptions) {
 	const options = (explicitDb ? maybeOptions : dbOrOptions) ?? {};
 	const db = explicitDb ?? useDb();
 	const downloadDelayMs = options.downloadDelayMs ?? 200;
-	const uploadThreshold = options.uploadThreshold ?? 1;
+	const uploadThreshold = options.uploadThreshold ?? 0;
+	const uploadDelayMs = options.uploadDelayMs ?? 150;
 	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 });
+	return {
+		fetchingQueries,
+		pendingMutations,
+		isDownloading: delayedOn(() => fetchingQueries() > 0, downloadDelayMs),
+		isUploading: delayedOn(() => pendingMutations() > uploadThreshold, uploadDelayMs)
+	};
+}
+/**
+* `busy` held for `delayMs`, dropped the instant it clears. Both directions of
+* traffic use it, so a burst too short to see never flickers the indicator and
+* neither one can latch on after the work is done.
+*/
+function delayedOn(busy, delayMs) {
+	const [on, setOn] = (0, solid_js.createSignal)(false, { ownedWrite: true });
 	let timer;
-	(0, solid_js.createEffect)(() => fetchingQueries() > 0, (busy) => {
+	(0, solid_js.createEffect)(busy, (isBusy) => {
 		if (timer !== void 0) {
 			clearTimeout(timer);
 			timer = void 0;
 		}
-		if (!busy) {
-			setIsDownloading(false);
+		if (!isBusy) {
+			setOn(false);
 			return;
 		}
-		if (downloadDelayMs <= 0) {
-			setIsDownloading(true);
+		if (delayMs <= 0) {
+			setOn(true);
 			return;
 		}
 		timer = setTimeout(() => {
 			timer = void 0;
-			setIsDownloading(true);
-		}, downloadDelayMs);
+			setOn(true);
+		}, delayMs);
 	});
 	(0, solid_js.onCleanup)(() => {
 		if (timer !== void 0) clearTimeout(timer);
 	});
-	return {
-		fetchingQueries,
-		pendingMutations,
-		isDownloading,
-		isUploading: () => pendingMutations() > uploadThreshold
-	};
+	return on;
 }
 
 //#endregion