@syncular/react 0.15.40 → 0.15.42

package/README.md

@@ -153,14 +153,18 @@ old resource before creating another one. Otherwise the old worker and the new
 worker can briefly compete for the same persistent OPFS directory. Never wipe
 or rename the database in response to a retryable startup error.
 
-For Vite, use `retainViteSyncClientResource(hot.data, schema.version,
-createClient)`. It retains a `{ schemaVersion, runtimeVersion, resource }`
-record, reuses it for same-schema HMR on the same published Syncular runtime,
-and awaits old-resource disposal before creating a schema-bump or
-package-upgrade replacement. Request `hot.invalidate()` only when its
-`ownerChanged` result is true and `disposalError` is absent; the official
-example, optimizer exclusion, and upgrade workflow are in the
-[Vite guide](https://syncular.dev/guide-vite/). The helper may close
+For Vite, use `createViteSyncClientResource(hot.data, schema.version,
+createClient)`. It synchronously returns a pending-or-retained resource, keeps
+a `{ schemaVersion, runtimeVersion, resource }` record, reuses it for
+same-schema HMR on the same published Syncular runtime, and sequences a
+schema-bump or package-upgrade factory behind old-resource disposal. Await its
+`handoff` promise before requesting `hot.invalidate()` when `ownerChanged` is
+true. A failed handoff is also exposed by the resource through the ordinary
+startup boundary and never opens a second owner. This recipe requires no
+top-level await; the official example, optimizer exclusion, and upgrade
+workflow are in the [Vite guide](https://syncular.dev/guide-vite/).
+`retainViteSyncClientResource` remains the async alternative for targets that
+deliberately support top-level await. Either helper may close
 the retained client before React runs cleanup for the old provider; Syncular
 absorbs that teardown-only window-release race while still surfacing failures
 from closing the resource itself.
@@ -260,6 +264,16 @@ not need a custom retention effect.
 
 The hooks are SSR-safe: no local query runs during server rendering.
 
+### Router scheduling
+
+Syncular hooks publish through `useSyncExternalStore`. If React Router owns
+clinical query state, keep the router as the only owner and use its explicit
+synchronous publication policy (`<RouterProvider useTransitions={false}>`) on
+versions where sustained external-store updates can starve a transition. Do
+not repair URL/render disagreement with `window.location`, `flushSync`, or a
+mirrored store. The maintained fixture and upgrade guidance live in the
+[React guide](https://syncular.dev/platform-react/#router-transition-scheduling).
+
 ### Privacy-safe support view
 
 Use application-owned, stable, PHI-free subscription ids to make missing

package/dist/index.d.ts

@@ -23,4 +23,4 @@ export { type NamedQueryDescriptor, useQuery, } from './use-query.js';
 export { type UseRawSqlOptions, type UseRawSqlResult, useRawSql, } from './use-raw-sql.js';
 export { type SyncStatus, useSyncStatus } from './use-sync-status.js';
 export { type UseRetainedWindowResult, type UseWindowResult, useRetainedWindow, useWindow, } from './use-window.js';
-export { type RetainedSyncularResource, retainViteSyncClientResource, type ViteSyncClientResourceResult, } from './vite-hmr.js';
+export { createViteSyncClientResource, type RetainedSyncularResource, retainViteSyncClientResource, type ViteSyncClientResourceBootstrap, type ViteSyncClientResourceResult, } from './vite-hmr.js';

package/dist/index.js

@@ -16,4 +16,4 @@ export { useQuery, } from './use-query.js';
 export { useRawSql, } from './use-raw-sql.js';
 export { useSyncStatus } from './use-sync-status.js';
 export { useRetainedWindow, useWindow, } from './use-window.js';
-export { retainViteSyncClientResource, } from './vite-hmr.js';
+export { createViteSyncClientResource, retainViteSyncClientResource, } from './vite-hmr.js';

package/dist/runtime-version.d.ts

@@ -3,4 +3,4 @@
  * Vite HMR uses it to replace a worker owner after a Syncular package upgrade
  * even when the application's generated schema version did not change.
  */
-export declare const SYNCULAR_REACT_RUNTIME_VERSION = "0.15.40";
+export declare const SYNCULAR_REACT_RUNTIME_VERSION = "0.15.42";

package/dist/runtime-version.js

@@ -3,4 +3,4 @@
  * Vite HMR uses it to replace a worker owner after a Syncular package upgrade
  * even when the application's generated schema version did not change.
  */
-export const SYNCULAR_REACT_RUNTIME_VERSION = '0.15.40';
+export const SYNCULAR_REACT_RUNTIME_VERSION = '0.15.42';

package/dist/vite-hmr.d.ts

@@ -20,7 +20,36 @@ export interface ViteSyncClientResourceResult {
     /** A failed close is exposed by `resource` as a startup error. */
     readonly disposalError?: Error;
 }
+/**
+ * Synchronous module-bootstrap result for Vite targets that do not support
+ * top-level await. The resource is immediately usable by `SyncProvider`; it
+ * remains pending until an obsolete owner has closed and the replacement
+ * factory is allowed to run.
+ */
+export interface ViteSyncClientResourceBootstrap {
+    readonly resource: SyncClientResource;
+    /**
+     * Resolves after an incompatible retained owner has closed. A rejection is
+     * also published by `resource` as its startup error, and prevents the
+     * replacement factory from running.
+     */
+    readonly handoff: Promise<void>;
+    /** Compatibility alias; true whenever the retained owner was replaced. */
+    readonly schemaChanged: boolean;
+    /** True only when a retained owner came from another Syncular release. */
+    readonly runtimeChanged: boolean;
+    /** True whenever an incompatible retained owner is being replaced. */
+    readonly ownerChanged: boolean;
+}
 type HotData = Record<string, unknown>;
+/**
+ * Create or reuse a Vite-retained resource without top-level await.
+ *
+ * On an owner change, the returned resource's factory is sequenced behind the
+ * prior resource's complete disposal. A failed close therefore becomes the
+ * ordinary resource startup error and never constructs a competing owner.
+ */
+export declare function createViteSyncClientResource(hotData: HotData | undefined, schemaVersion: number, factory: () => SyncClientLike | Promise<SyncClientLike>, runtimeVersion?: string): ViteSyncClientResourceBootstrap;
 /**
  * Reuse a Vite-owned client only while both its captured generated schema and
  * materialized Syncular runtime identity match. On either change, the prior

package/dist/vite-hmr.js

@@ -30,13 +30,7 @@ function retainedFrom(hotData) {
         resource: candidate.resource,
     };
 }
-/**
- * Reuse a Vite-owned client only while both its captured generated schema and
- * materialized Syncular runtime identity match. On either change, the prior
- * resource is fully disposed before the replacement resource (and therefore
- * its worker) is constructed.
- */
-export async function retainViteSyncClientResource(hotData, schemaVersion, factory, runtimeVersion = SYNCULAR_REACT_RUNTIME_VERSION) {
+function validateIdentity(schemaVersion, runtimeVersion) {
     if (!Number.isInteger(schemaVersion) || schemaVersion < 1) {
         throw new TypeError('schemaVersion must be a positive integer');
     }
@@ -45,6 +39,64 @@ export async function retainViteSyncClientResource(hotData, schemaVersion, facto
         runtimeVersion.length > 96) {
         throw new TypeError('runtimeVersion must be a bounded non-empty string');
     }
+}
+/**
+ * Create or reuse a Vite-retained resource without top-level await.
+ *
+ * On an owner change, the returned resource's factory is sequenced behind the
+ * prior resource's complete disposal. A failed close therefore becomes the
+ * ordinary resource startup error and never constructs a competing owner.
+ */
+export function createViteSyncClientResource(hotData, schemaVersion, factory, runtimeVersion = SYNCULAR_REACT_RUNTIME_VERSION) {
+    validateIdentity(schemaVersion, runtimeVersion);
+    const retained = retainedFrom(hotData);
+    if (retained?.schemaVersion === schemaVersion &&
+        retained.runtimeVersion === runtimeVersion) {
+        return {
+            resource: retained.resource,
+            handoff: Promise.resolve(),
+            schemaChanged: false,
+            runtimeChanged: false,
+            ownerChanged: false,
+        };
+    }
+    const ownerChanged = retained !== undefined;
+    const runtimeChanged = retained !== undefined && retained.runtimeVersion !== runtimeVersion;
+    const handoff = retained
+        ? Promise.resolve().then(() => retained.resource.dispose())
+        : Promise.resolve();
+    // The resource below observes the same rejection. Attaching a handler here
+    // also keeps an integration that ignores `handoff` free of an unhandled
+    // promise while the provider reports the typed startup failure.
+    void handoff.catch(() => undefined);
+    const resource = createSyncClientResource(async () => {
+        await handoff;
+        return factory();
+    });
+    if (hotData !== undefined) {
+        const record = {
+            schemaVersion,
+            runtimeVersion,
+            resource,
+        };
+        hotData.syncularClientResource = record;
+    }
+    return {
+        resource,
+        handoff,
+        schemaChanged: ownerChanged,
+        runtimeChanged,
+        ownerChanged,
+    };
+}
+/**
+ * Reuse a Vite-owned client only while both its captured generated schema and
+ * materialized Syncular runtime identity match. On either change, the prior
+ * resource is fully disposed before the replacement resource (and therefore
+ * its worker) is constructed.
+ */
+export async function retainViteSyncClientResource(hotData, schemaVersion, factory, runtimeVersion = SYNCULAR_REACT_RUNTIME_VERSION) {
+    validateIdentity(schemaVersion, runtimeVersion);
     const retained = retainedFrom(hotData);
     if (retained?.schemaVersion === schemaVersion &&
         retained.runtimeVersion === runtimeVersion) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/react",
-  "version": "0.15.40",
+  "version": "0.15.42",
   "description": "React hooks for Syncular offline-first sync",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -55,18 +55,20 @@
     "test": "bun test --preload ./test/setup.ts"
   },
   "dependencies": {
-    "@syncular/client": "0.15.40"
+    "@syncular/client": "0.15.42"
   },
   "peerDependencies": {
     "react": ">=18.0.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.0.0",
-    "@syncular/core": "0.15.40",
-    "@syncular/server": "0.15.40",
+    "@syncular/core": "0.15.42",
+    "@syncular/server": "0.15.42",
     "@testing-library/react": "^16.1.0",
     "@types/react": "^18.3.0",
     "react": "^18.3.1",
-    "react-dom": "^18.3.1"
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^7.18.1",
+    "vite": "^8.1.3"
   }
 }

package/src/index.ts

@@ -67,7 +67,9 @@ export {
   useWindow,
 } from './use-window';
 export {
+  createViteSyncClientResource,
   type RetainedSyncularResource,
   retainViteSyncClientResource,
+  type ViteSyncClientResourceBootstrap,
   type ViteSyncClientResourceResult,
 } from './vite-hmr';

package/src/runtime-version.ts

@@ -3,4 +3,4 @@
  * Vite HMR uses it to replace a worker owner after a Syncular package upgrade
  * even when the application's generated schema version did not change.
  */
-export const SYNCULAR_REACT_RUNTIME_VERSION = '0.15.40';
+export const SYNCULAR_REACT_RUNTIME_VERSION = '0.15.42';

package/src/vite-hmr.ts

@@ -24,6 +24,28 @@ export interface ViteSyncClientResourceResult {
   readonly disposalError?: Error;
 }
 
+/**
+ * Synchronous module-bootstrap result for Vite targets that do not support
+ * top-level await. The resource is immediately usable by `SyncProvider`; it
+ * remains pending until an obsolete owner has closed and the replacement
+ * factory is allowed to run.
+ */
+export interface ViteSyncClientResourceBootstrap {
+  readonly resource: SyncClientResource;
+  /**
+   * Resolves after an incompatible retained owner has closed. A rejection is
+   * also published by `resource` as its startup error, and prevents the
+   * replacement factory from running.
+   */
+  readonly handoff: Promise<void>;
+  /** Compatibility alias; true whenever the retained owner was replaced. */
+  readonly schemaChanged: boolean;
+  /** True only when a retained owner came from another Syncular release. */
+  readonly runtimeChanged: boolean;
+  /** True whenever an incompatible retained owner is being replaced. */
+  readonly ownerChanged: boolean;
+}
+
 type HotData = Record<string, unknown>;
 
 function errorOf(value: unknown): Error {
@@ -72,6 +94,81 @@ function retainedFrom(hotData: HotData | undefined):
   };
 }
 
+function validateIdentity(schemaVersion: number, runtimeVersion: string): void {
+  if (!Number.isInteger(schemaVersion) || schemaVersion < 1) {
+    throw new TypeError('schemaVersion must be a positive integer');
+  }
+  if (
+    typeof runtimeVersion !== 'string' ||
+    runtimeVersion.length === 0 ||
+    runtimeVersion.length > 96
+  ) {
+    throw new TypeError('runtimeVersion must be a bounded non-empty string');
+  }
+}
+
+/**
+ * Create or reuse a Vite-retained resource without top-level await.
+ *
+ * On an owner change, the returned resource's factory is sequenced behind the
+ * prior resource's complete disposal. A failed close therefore becomes the
+ * ordinary resource startup error and never constructs a competing owner.
+ */
+export function createViteSyncClientResource(
+  hotData: HotData | undefined,
+  schemaVersion: number,
+  factory: () => SyncClientLike | Promise<SyncClientLike>,
+  runtimeVersion = SYNCULAR_REACT_RUNTIME_VERSION,
+): ViteSyncClientResourceBootstrap {
+  validateIdentity(schemaVersion, runtimeVersion);
+
+  const retained = retainedFrom(hotData);
+  if (
+    retained?.schemaVersion === schemaVersion &&
+    retained.runtimeVersion === runtimeVersion
+  ) {
+    return {
+      resource: retained.resource,
+      handoff: Promise.resolve(),
+      schemaChanged: false,
+      runtimeChanged: false,
+      ownerChanged: false,
+    };
+  }
+
+  const ownerChanged = retained !== undefined;
+  const runtimeChanged =
+    retained !== undefined && retained.runtimeVersion !== runtimeVersion;
+  const handoff = retained
+    ? Promise.resolve().then(() => retained.resource.dispose())
+    : Promise.resolve();
+  // The resource below observes the same rejection. Attaching a handler here
+  // also keeps an integration that ignores `handoff` free of an unhandled
+  // promise while the provider reports the typed startup failure.
+  void handoff.catch(() => undefined);
+  const resource = createSyncClientResource(async () => {
+    await handoff;
+    return factory();
+  });
+
+  if (hotData !== undefined) {
+    const record: RetainedSyncularResource = {
+      schemaVersion,
+      runtimeVersion,
+      resource,
+    };
+    hotData.syncularClientResource = record;
+  }
+
+  return {
+    resource,
+    handoff,
+    schemaChanged: ownerChanged,
+    runtimeChanged,
+    ownerChanged,
+  };
+}
+
 /**
  * Reuse a Vite-owned client only while both its captured generated schema and
  * materialized Syncular runtime identity match. On either change, the prior
@@ -84,16 +181,7 @@ export async function retainViteSyncClientResource(
   factory: () => SyncClientLike | Promise<SyncClientLike>,
   runtimeVersion = SYNCULAR_REACT_RUNTIME_VERSION,
 ): Promise<ViteSyncClientResourceResult> {
-  if (!Number.isInteger(schemaVersion) || schemaVersion < 1) {
-    throw new TypeError('schemaVersion must be a positive integer');
-  }
-  if (
-    typeof runtimeVersion !== 'string' ||
-    runtimeVersion.length === 0 ||
-    runtimeVersion.length > 96
-  ) {
-    throw new TypeError('runtimeVersion must be a bounded non-empty string');
-  }
+  validateIdentity(schemaVersion, runtimeVersion);
 
   const retained = retainedFrom(hotData);
   if (