@pylonsync/react 0.3.36 → 0.3.42

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.36",
+  "version": "0.3.42",
   "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.36",
-    "@pylonsync/sync": "0.3.36"
+    "@pylonsync/sdk": "0.3.42",
+    "@pylonsync/sync": "0.3.42"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/db.ts

@@ -42,9 +42,16 @@ let _started = false;
  * import { init } from "@pylonsync/react";
  * init({ baseUrl: "http://localhost:4321" });
  * ```
+ *
+ * Omitting `baseUrl` in a browser context falls back to
+ * `window.location.origin` — the right answer for same-origin
+ * deployments (Next.js + Vercel rewrites, embedded SPA). Passing an
+ * explicit `baseUrl` always wins. We deliberately do NOT default to
+ * `http://localhost:4321` in browsers — that footgun caused production
+ * dashboards to fire requests at the engineer's dev port.
  */
 export function init(config?: Partial<SyncEngineConfig> & { baseUrl?: string }) {
-  _sync = createSyncEngine(config?.baseUrl ?? "http://localhost:4321", config);
+  _sync = createSyncEngine(config?.baseUrl, config);
   _started = false;
   // Keep the React-side helpers in sync — a single init() should fully
   // namespace this app's storage without a separate configureClient call.
@@ -56,7 +63,13 @@ export function init(config?: Partial<SyncEngineConfig> & { baseUrl?: string })
 
 function getSync(): SyncEngine {
   if (!_sync) {
-    _sync = createSyncEngine("http://localhost:4321");
+    // Lazy fallback for callers that never invoked init(). Same
+    // resolution rules as init: browser → window.location.origin,
+    // SSR → localhost:4321 (the pylon dev default). The browser case
+    // is critical: without it a useQuery hook that fires before the
+    // app's SyncProvider effect lands would leak `localhost:4321`
+    // requests in production.
+    _sync = createSyncEngine();
   }
   if (!_started) {
     _started = true;

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,
+	);
+}