@syncular/react 0.15.29 → 0.15.30

package/README.md

@@ -154,11 +154,13 @@ 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, resource }` record, reuses it for
-same-schema HMR, and awaits old-resource disposal before creating a schema-bump
-replacement. Request `hot.invalidate()` only when its `schemaChanged` result is
-true and `disposalError` is absent; the official example and full explanation
-are in the [Vite guide](https://syncular.dev/guide-vite/). The helper may close
+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
 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.

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { normalizeClient } from './client.js';
 export { inferTables } from './infer-tables.js';
 export { type SyncBoundaryActions, type SyncBoundaryState, SyncContext, SyncProvider, type SyncProviderProps, SyncStoreContext, } from './provider.js';
 export { createSyncClientResource, isSyncClientResource, type SyncClientResource, type SyncClientResourceSnapshot, } from './resource.js';
+export { SYNCULAR_REACT_RUNTIME_VERSION } from './runtime-version.js';
 export { useReactiveStore, useSyncClient } from './use-client.js';
 export { type UseCommitOutcomesResult, useCommitOutcomes, } from './use-commit-outcomes.js';
 export { type UseConflictsResult, useConflicts } from './use-conflicts.js';

package/dist/index.js

@@ -5,6 +5,7 @@ export { normalizeClient } from './client.js';
 export { inferTables } from './infer-tables.js';
 export { SyncContext, SyncProvider, SyncStoreContext, } from './provider.js';
 export { createSyncClientResource, isSyncClientResource, } from './resource.js';
+export { SYNCULAR_REACT_RUNTIME_VERSION } from './runtime-version.js';
 export { useReactiveStore, useSyncClient } from './use-client.js';
 export { useCommitOutcomes, } from './use-commit-outcomes.js';
 export { useConflicts } from './use-conflicts.js';

package/dist/runtime-version.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Materialized from the repository release version by scripts/version.ts.
+ * 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.30";

package/dist/runtime-version.js

@@ -0,0 +1,6 @@
+/**
+ * Materialized from the repository release version by scripts/version.ts.
+ * 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.30';

package/dist/vite-config.d.ts

@@ -0,0 +1,6 @@
+/**
+ * First-party Syncular browser packages are already ESM. Keeping them out of
+ * Vite's dependency optimizer prevents a live worker from referring to a
+ * retired hashed optimizer chunk after a package upgrade.
+ */
+export declare const SYNCULAR_VITE_OPTIMIZE_DEPS_EXCLUDE: readonly ["@syncular/client", "@syncular/client/worker", "@syncular/core", "@syncular/crypto", "@syncular/react"];

package/dist/vite-config.js

@@ -0,0 +1,12 @@
+/**
+ * First-party Syncular browser packages are already ESM. Keeping them out of
+ * Vite's dependency optimizer prevents a live worker from referring to a
+ * retired hashed optimizer chunk after a package upgrade.
+ */
+export const SYNCULAR_VITE_OPTIMIZE_DEPS_EXCLUDE = [
+    '@syncular/client',
+    '@syncular/client/worker',
+    '@syncular/core',
+    '@syncular/crypto',
+    '@syncular/react',
+];

package/dist/vite-hmr.d.ts

@@ -3,20 +3,29 @@ import { type SyncClientResource } from './resource.js';
 /** The exact value retained in `import.meta.hot.data.syncularClientResource`. */
 export interface RetainedSyncularResource {
     readonly schemaVersion: number;
+    readonly runtimeVersion: string;
     readonly resource: SyncClientResource;
 }
 export interface ViteSyncClientResourceResult {
     readonly resource: SyncClientResource;
-    /** True only when an older captured schema identity was replaced. */
+    /**
+     * Compatibility signal used by existing integrations to invalidate HMR.
+     * True when either the schema or Syncular runtime identity changed.
+     */
     readonly schemaChanged: boolean;
+    /** True only when a retained owner came from another Syncular release. */
+    readonly runtimeChanged: boolean;
+    /** True whenever an incompatible retained owner was replaced. */
+    readonly ownerChanged: boolean;
     /** A failed close is exposed by `resource` as a startup error. */
     readonly disposalError?: Error;
 }
 type HotData = Record<string, unknown>;
 /**
- * Reuse a Vite-owned client only while its captured generated schema matches.
- * On a bump, the prior resource is fully disposed before the replacement
- * resource (and therefore its worker) is constructed.
+ * 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 declare function retainViteSyncClientResource(hotData: HotData | undefined, schemaVersion: number, factory: () => SyncClientLike | Promise<SyncClientLike>): Promise<ViteSyncClientResourceResult>;
+export declare function retainViteSyncClientResource(hotData: HotData | undefined, schemaVersion: number, factory: () => SyncClientLike | Promise<SyncClientLike>, runtimeVersion?: string): Promise<ViteSyncClientResourceResult>;
 export {};

package/dist/vite-hmr.js

@@ -1,4 +1,5 @@
 import { createSyncClientResource } from './resource.js';
+import { SYNCULAR_REACT_RUNTIME_VERSION } from './runtime-version.js';
 function errorOf(value) {
     return value instanceof Error ? value : new Error(String(value));
 }
@@ -23,22 +24,39 @@ function retainedFrom(hotData) {
     }
     return {
         schemaVersion: candidate.schemaVersion,
+        ...(typeof candidate.runtimeVersion === 'string'
+            ? { runtimeVersion: candidate.runtimeVersion }
+            : {}),
         resource: candidate.resource,
     };
 }
 /**
- * Reuse a Vite-owned client only while its captured generated schema matches.
- * On a bump, the prior resource is fully disposed before the replacement
- * resource (and therefore its worker) is constructed.
+ * 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) {
+export async function retainViteSyncClientResource(hotData, schemaVersion, factory, runtimeVersion = SYNCULAR_REACT_RUNTIME_VERSION) {
     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');
+    }
     const retained = retainedFrom(hotData);
-    if (retained?.schemaVersion === schemaVersion) {
-        return { resource: retained.resource, schemaChanged: false };
+    if (retained?.schemaVersion === schemaVersion &&
+        retained.runtimeVersion === runtimeVersion) {
+        return {
+            resource: retained.resource,
+            schemaChanged: false,
+            runtimeChanged: false,
+            ownerChanged: false,
+        };
     }
+    const ownerChanged = retained !== undefined;
+    const runtimeChanged = retained !== undefined && retained.runtimeVersion !== runtimeVersion;
     let disposalError;
     if (retained !== undefined) {
         try {
@@ -52,12 +70,20 @@ export async function retainViteSyncClientResource(hotData, schemaVersion, facto
     // whose ordinary provider startup boundary reports the close failure.
     const resource = createSyncClientResource(disposalError === undefined ? factory : () => Promise.reject(disposalError));
     if (hotData !== undefined) {
-        const record = { schemaVersion, resource };
+        const record = {
+            schemaVersion,
+            runtimeVersion,
+            resource,
+        };
         hotData.syncularClientResource = record;
     }
     return {
         resource,
-        schemaChanged: retained !== undefined,
+        // Existing apps already invalidate on this property. Preserve that
+        // recovery behavior for a same-schema package upgrade.
+        schemaChanged: ownerChanged,
+        runtimeChanged,
+        ownerChanged,
         ...(disposalError !== undefined ? { disposalError } : {}),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/react",
-  "version": "0.15.29",
+  "version": "0.15.30",
   "description": "React hooks for Syncular offline-first sync",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -33,6 +33,13 @@
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
+    },
+    "./vite": {
+      "bun": "./src/vite-config.ts",
+      "import": {
+        "types": "./dist/vite-config.d.ts",
+        "default": "./dist/vite-config.js"
+      }
     }
   },
   "files": [
@@ -48,15 +55,15 @@
     "test": "bun test --preload ./test/setup.ts"
   },
   "dependencies": {
-    "@syncular/client": "0.15.29"
+    "@syncular/client": "0.15.30"
   },
   "peerDependencies": {
     "react": ">=18.0.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.0.0",
-    "@syncular/core": "0.15.29",
-    "@syncular/server": "0.15.29",
+    "@syncular/core": "0.15.30",
+    "@syncular/server": "0.15.30",
     "@testing-library/react": "^16.1.0",
     "@types/react": "^18.3.0",
     "react": "^18.3.1",

package/src/index.ts

@@ -30,6 +30,7 @@ export {
   type SyncClientResource,
   type SyncClientResourceSnapshot,
 } from './resource';
+export { SYNCULAR_REACT_RUNTIME_VERSION } from './runtime-version';
 export { useReactiveStore, useSyncClient } from './use-client';
 export {
   type UseCommitOutcomesResult,

package/src/runtime-version.ts

@@ -0,0 +1,6 @@
+/**
+ * Materialized from the repository release version by scripts/version.ts.
+ * 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.30';

package/src/vite-config.ts

@@ -0,0 +1,12 @@
+/**
+ * First-party Syncular browser packages are already ESM. Keeping them out of
+ * Vite's dependency optimizer prevents a live worker from referring to a
+ * retired hashed optimizer chunk after a package upgrade.
+ */
+export const SYNCULAR_VITE_OPTIMIZE_DEPS_EXCLUDE = [
+  '@syncular/client',
+  '@syncular/client/worker',
+  '@syncular/core',
+  '@syncular/crypto',
+  '@syncular/react',
+] as const;

package/src/vite-hmr.ts

@@ -1,16 +1,25 @@
 import type { SyncClientLike } from './client';
 import { createSyncClientResource, type SyncClientResource } from './resource';
+import { SYNCULAR_REACT_RUNTIME_VERSION } from './runtime-version';
 
 /** The exact value retained in `import.meta.hot.data.syncularClientResource`. */
 export interface RetainedSyncularResource {
   readonly schemaVersion: number;
+  readonly runtimeVersion: string;
   readonly resource: SyncClientResource;
 }
 
 export interface ViteSyncClientResourceResult {
   readonly resource: SyncClientResource;
-  /** True only when an older captured schema identity was replaced. */
+  /**
+   * Compatibility signal used by existing integrations to invalidate HMR.
+   * True when either the schema or Syncular runtime identity changed.
+   */
   readonly schemaChanged: boolean;
+  /** True only when a retained owner came from another Syncular release. */
+  readonly runtimeChanged: boolean;
+  /** True whenever an incompatible retained owner was replaced. */
+  readonly ownerChanged: boolean;
   /** A failed close is exposed by `resource` as a startup error. */
   readonly disposalError?: Error;
 }
@@ -29,10 +38,12 @@ function isResource(value: unknown): value is SyncClientResource {
   );
 }
 
-function retainedFrom(
-  hotData: HotData | undefined,
-):
-  | { readonly schemaVersion?: number; readonly resource: SyncClientResource }
+function retainedFrom(hotData: HotData | undefined):
+  | {
+      readonly schemaVersion?: number;
+      readonly runtimeVersion?: string;
+      readonly resource: SyncClientResource;
+    }
   | undefined {
   const value = hotData?.syncularClientResource;
   if (isResource(value)) {
@@ -42,6 +53,7 @@ function retainedFrom(
   if (typeof value !== 'object' || value === null) return undefined;
   const candidate = value as {
     readonly schemaVersion?: unknown;
+    readonly runtimeVersion?: unknown;
     readonly resource?: unknown;
   };
   if (
@@ -53,29 +65,53 @@ function retainedFrom(
   }
   return {
     schemaVersion: candidate.schemaVersion,
+    ...(typeof candidate.runtimeVersion === 'string'
+      ? { runtimeVersion: candidate.runtimeVersion }
+      : {}),
     resource: candidate.resource,
   };
 }
 
 /**
- * Reuse a Vite-owned client only while its captured generated schema matches.
- * On a bump, the prior resource is fully disposed before the replacement
- * resource (and therefore its worker) is constructed.
+ * 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: HotData | undefined,
   schemaVersion: number,
   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');
+  }
 
   const retained = retainedFrom(hotData);
-  if (retained?.schemaVersion === schemaVersion) {
-    return { resource: retained.resource, schemaChanged: false };
+  if (
+    retained?.schemaVersion === schemaVersion &&
+    retained.runtimeVersion === runtimeVersion
+  ) {
+    return {
+      resource: retained.resource,
+      schemaChanged: false,
+      runtimeChanged: false,
+      ownerChanged: false,
+    };
   }
 
+  const ownerChanged = retained !== undefined;
+  const runtimeChanged =
+    retained !== undefined && retained.runtimeVersion !== runtimeVersion;
+
   let disposalError: Error | undefined;
   if (retained !== undefined) {
     try {
@@ -91,12 +127,20 @@ export async function retainViteSyncClientResource(
     disposalError === undefined ? factory : () => Promise.reject(disposalError),
   );
   if (hotData !== undefined) {
-    const record: RetainedSyncularResource = { schemaVersion, resource };
+    const record: RetainedSyncularResource = {
+      schemaVersion,
+      runtimeVersion,
+      resource,
+    };
     hotData.syncularClientResource = record;
   }
   return {
     resource,
-    schemaChanged: retained !== undefined,
+    // Existing apps already invalidate on this property. Preserve that
+    // recovery behavior for a same-schema package upgrade.
+    schemaChanged: ownerChanged,
+    runtimeChanged,
+    ownerChanged,
     ...(disposalError !== undefined ? { disposalError } : {}),
   };
 }