@pylonsync/react 0.3.41 → 0.3.43

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.41",
+  "version": "0.3.43",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -12,8 +12,8 @@
     "check": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@pylonsync/sdk": "0.3.41",
-    "@pylonsync/sync": "0.3.41"
+    "@pylonsync/sdk": "0.3.43",
+    "@pylonsync/sync": "0.3.43"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/index.ts

@@ -61,6 +61,9 @@ export type {
 export { useSession } from "./useSession";
 export type { UseSessionReturn, ResolvedSession } from "./useSession";
 
+export { useSyncStatus } from "./useSyncStatus";
+export type { SyncConnectionStatus } from "./useSyncStatus";
+
 // One-liner API
 export { db, init } from "./db";
 

package/src/useSyncStatus.ts

@@ -0,0 +1,49 @@
+"use client";
+
+import {
+	type SyncConnectionStatus,
+	type SyncEngine,
+} from "@pylonsync/sync";
+import { useSyncExternalStore } from "react";
+import { db } from "./db";
+
+export type { SyncConnectionStatus };
+
+/**
+ * Subscribe to the sync engine's connection status. Re-renders whenever
+ * the WebSocket transitions ("connecting" → "connected" → "reconnecting"
+ * → "offline"), so apps can render a small indicator without polling
+ * or wiring their own event listeners.
+ *
+ * Common use case: surface a "reconnecting…" banner during the cold
+ * start after a Fly autostop or a flaky network. Live queries keep
+ * returning the last-known data during reconnect, so without this hook
+ * users see stale data with no signal that anything is wrong.
+ *
+ * ```tsx
+ * function ConnectionBanner() {
+ *   const status = useSyncStatus();
+ *   if (status === "connected") return null;
+ *   return (
+ *     <div className="banner">
+ *       {status === "reconnecting" ? "Reconnecting…" : "Offline"}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * Pass an explicit `engine` if your app uses a non-default sync
+ * instance; otherwise omit and the hook reads the singleton wired up
+ * by `init()`.
+ */
+export function useSyncStatus(engine?: SyncEngine): SyncConnectionStatus {
+	const sync = engine ?? db.sync;
+	return useSyncExternalStore(
+		(cb) => sync.store.subscribe(cb),
+		() => sync.connectionStatus(),
+		// SSR snapshot — engine is offline until start() runs in the
+		// browser, so claiming "connecting" here would mislead consumers
+		// rendered server-side.
+		() => "offline" as SyncConnectionStatus,
+	);
+}