create-syncular-app 0.15.36 → 0.15.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-syncular-app",
-  "version": "0.15.36",
+  "version": "0.15.38",
   "description": "Scaffold a new Syncular app: `create-syncular-app`",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -49,6 +49,6 @@
     "!dist/**/*.test.d.ts"
   ],
   "devDependencies": {
-    "@syncular/typegen": "0.15.36"
+    "@syncular/typegen": "0.15.38"
   }
 }

package/template/tauri/src/frontend/engine.ts

@@ -18,6 +18,12 @@
  * the web build never ships the Tauri bridge, and the Tauri webview never
  * loads sqlite-wasm.
  */
+
+import {
+  browserConnectivitySignal,
+  documentLifecycleSignal,
+  installRealtimeSupervisor,
+} from '@syncular/client';
 import type { SyncClientLike } from '@syncular/react';
 import { schema } from '../syncular.generated';
 
@@ -26,7 +32,9 @@ import { schema } from '../syncular.generated';
  * lifecycle both concrete clients share, still fully host-agnostic.
  */
 export interface Engine extends SyncClientLike {
+  syncUntilIdle(maxRounds?: number): unknown | Promise<unknown>;
   connectRealtime(): Promise<void>;
+  disconnectRealtime(): void | Promise<void>;
   close(): Promise<void>;
 }
 
@@ -34,22 +42,29 @@ export interface Engine extends SyncClientLike {
 const isTauri = () => '__TAURI_INTERNALS__' in window;
 
 export async function createEngine(): Promise<Engine> {
+  const supervise = <Client extends Engine>(client: Client): Client =>
+    installRealtimeSupervisor(client, {
+      connectivity: browserConnectivitySignal(),
+      lifecycle: documentLifecycleSignal(),
+    });
   if (isTauri()) {
     // Desktop: the native Rust core in the Tauri process.
     const { createTauriSyncClient } = await import('@syncular/tauri');
-    return createTauriSyncClient({ schema });
+    return supervise(await createTauriSyncClient({ schema }));
   }
   // Web: the whole core in a worker, persisted on OPFS.
   const { createSyncClientHandle } = await import('@syncular/client');
   const WS = location.protocol === 'https:' ? 'wss' : 'ws';
-  return createSyncClientHandle({
-    worker: () => new Worker('/worker.js', { type: 'module' }),
-    schema,
-    database: { mode: 'persistent', name: 'app' },
-    endpoints: {
-      syncUrl: '/sync',
-      segmentsUrl: '/segments',
-      realtimeUrl: `${WS}://${location.host}/realtime?clientId={clientId}`,
-    },
-  });
+  return supervise(
+    await createSyncClientHandle({
+      worker: () => new Worker('/worker.js', { type: 'module' }),
+      schema,
+      database: { mode: 'persistent', name: 'app' },
+      endpoints: {
+        syncUrl: '/sync',
+        segmentsUrl: '/segments',
+        realtimeUrl: `${WS}://${location.host}/realtime?clientId={clientId}`,
+      },
+    }),
+  );
 }

package/template/tauri/src/frontend/main.tsx

@@ -142,13 +142,9 @@ function TodoApp() {
 }
 
 const engineResource = createSyncClientResource(async () => {
-  const engine = await createEngine();
-  try {
-    await engine.connectRealtime();
-  } catch {
-    // offline / no socket — the host loop keeps syncing over HTTP
-  }
-  return engine;
+  // createEngine installs the supported reconnect/catch-up supervisor. React
+  // renders from local SQLite immediately; connectivity never gates startup.
+  return createEngine();
 });
 
 function Root() {

package/template/tauri/src-tauri/Cargo.toml

@@ -21,7 +21,7 @@ tauri = { version = "2", features = [] }
 # The syncular plugin from crates.io. `native-transport` gives the core its
 # real HTTP + WebSocket transport (ureq + tungstenite) inside the host
 # process — the webview never talks to the sync server directly.
-tauri-plugin-syncular = { version = "0.15.36", features = ["native-transport"] }
+tauri-plugin-syncular = { version = "0.15.38", features = ["native-transport"] }
 
 [features]
 default = []

package/template/web/src/frontend/main.ts

@@ -13,9 +13,14 @@
  * to watch them converge over the realtime socket.
  */
 import {
+  browserConnectivitySignal,
   ClientSyncError,
   createSyncClientHandle,
+  documentLifecycleSignal,
+  installRealtimeSupervisor,
+  realtimeSupervisorSnapshot,
   type SqlRow,
+  subscribeRealtimeSupervisor,
 } from '@syncular/client';
 import { schema, todoListSubscription } from '../syncular.generated';
 
@@ -63,15 +68,25 @@ async function main(): Promise<void> {
     scopes: todoListSubscription.scopes({ listId: LIST_ID }),
   });
 
-  // Connect-then-sync (§8.7 reference boot order): the first sync round rides
-  // the socket and registers this connection's subscriptions at round end.
-  try {
-    await handle.connectRealtime();
-  } catch {
-    // HTTP sync still works without the socket.
-  }
-  await handle.syncUntilIdle();
-  setStatus('in sync');
+  // The supported host policy owns connect + catch-up, retries transient
+  // startup/socket loss, and suspends while this page is offline or hidden.
+  // Rendering remains local-first: no network promise blocks app startup.
+  installRealtimeSupervisor(handle, {
+    connectivity: browserConnectivitySignal(),
+    lifecycle: documentLifecycleSignal(),
+  });
+  const renderRealtimeStatus = () => {
+    const phase = realtimeSupervisorSnapshot(handle).phase;
+    setStatus(
+      phase === 'connected'
+        ? 'in sync'
+        : phase === 'offline'
+          ? 'offline — edits queue in the outbox'
+          : phase,
+    );
+  };
+  subscribeRealtimeSupervisor(handle, renderRealtimeStatus);
+  renderRealtimeStatus();
   await refresh();
 
   let offline = false;
@@ -82,14 +97,9 @@ async function main(): Promise<void> {
     if (offline) {
       setStatus('offline — edits queue in the outbox');
     } else {
-      setStatus('back online — draining outbox…');
-      try {
-        await handle.connectRealtime();
-      } catch {
-        // socket optional
-      }
-      await handle.syncUntilIdle();
-      setStatus('in sync');
+      // The online diagnostic wakes the supervisor. Its successful reconnect
+      // always performs syncUntilIdle before publishing `connected`.
+      setStatus('back online — reconnecting…');
     }
     await refresh();
   });