@syncular/client 0.15.29 → 0.15.31

package/README.md

@@ -144,11 +144,12 @@ deterministic tuple for diagnostics and host integration. Replica IDs are
 stable code-like values (`A-Z`, `a-z`, `0-9`, dot, underscore, dash).
 
 During Vite development, retain the React client resource only while its
-captured generated schema version matches. The
-[schema-aware Vite guide](https://syncular.dev/guide-vite/) uses
+captured generated schema version and published Syncular runtime identity both
+match. The
+[schema-and-runtime-aware Vite guide](https://syncular.dev/guide-vite/) uses
 `retainViteSyncClientResource` to close the old worker before constructing a
-schema-bump replacement; hot-reloading query code alone does not migrate the
-worker-owned database.
+schema-bump or package-upgrade replacement; hot-reloading query code alone does
+not migrate the worker-owned database.
 
 Set `multiTab: false` to opt out. A losing tab then becomes an
 `isLeader === false` handle whose calls reject with `client.not_leader`. This
@@ -360,6 +361,11 @@ in-memory one**; the local database and pending outbox may be perfectly healthy.
 Missing or obsolete OPFS APIs instead use the non-retryable
 `client.storage_unavailable` code.
 
+A worker graph that still names a retired Vite optimizer chunk instead uses
+the non-retryable `client.worker_restart_required` code. Restart the dev server
+and reload the page; do not clear OPFS. The original bundler message and chunk
+URL are deliberately not copied into the public error.
+
 When using `@syncular/react`, `createSyncClientResource()` exposes `retry()` and
 passes the same action as the second argument to `SyncProvider.renderError`.
 Applications may use a small bounded backoff for errors whose `retryable` flag

package/dist/client.js

@@ -1745,7 +1745,8 @@ export class SyncClient {
         return (code === 'transport.failed' ||
             code === 'transport.unavailable' ||
             code === 'sync.transport_failed' ||
-            code === 'client.worker_failed');
+            code === 'client.worker_failed' ||
+            code === 'client.worker_restart_required');
     }
     #diagnosticCode(code) {
         return code.length <= 96 && /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/.test(code)

package/dist/worker-host.d.ts

@@ -27,6 +27,7 @@ import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, QueryRead
 import type { SqlRow, SqlValue } from './database.js';
 import { ClientDiagnosticsEmitter, type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot } from './diagnostics.js';
 import type { EncryptionKeyringConfig } from './encryption.js';
+import { ClientSyncError } from './errors.js';
 import { ChangeEmitter, type ClientChangeListener, InvalidationEmitter, type InvalidationListener, type LocalRevision, type SyncStatusSnapshot } from './invalidation.js';
 import { type LeaderLease, type LeaderLock } from './leader-lock.js';
 import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge.js';
@@ -38,6 +39,8 @@ import type { ClientSchema } from './schema.js';
 import type { SubscriptionRecord } from './state.js';
 import type { WindowBase } from './window.js';
 import { type SyncWorkerEvent, type WorkerDatabaseInit, type WorkerEndpoints, type WorkerErrorShape, type WorkerSecurityActivation } from './worker-protocol.js';
+/** Classify startup without echoing a chunk URL or bundler text to UI/logs. */
+export declare function workerStartupError(message: unknown): ClientSyncError;
 export type HandleRole = 'leader' | 'follower';
 export type BrowserReplicaMode = {
     readonly mode: 'shared';

package/dist/worker-host.js

@@ -4,7 +4,15 @@ import { ClientSyncError } from './errors.js';
 import { ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
 import { singleOwnerLock, webLocksLeaderLock, } from './leader-lock.js';
 import { broadcastChannelFactory, FollowerLink, LeaderBridge, multiTabChannelName, newTabId, } from './multi-tab.js';
-import { NOT_LEADER_CODE, WORKER_FAILED_CODE, } from './worker-protocol.js';
+import { NOT_LEADER_CODE, WORKER_FAILED_CODE, WORKER_RESTART_REQUIRED_CODE, } from './worker-protocol.js';
+const WORKER_BUNDLE_LOAD_FAILURE = /(?:failed to fetch dynamically imported module|error loading dynamically imported module|importing a module script failed|failed to load module script)/iu;
+/** Classify startup without echoing a chunk URL or bundler text to UI/logs. */
+export function workerStartupError(message) {
+    if (typeof message === 'string' && WORKER_BUNDLE_LOAD_FAILURE.test(message)) {
+        return new ClientSyncError(WORKER_RESTART_REQUIRED_CODE, 'the sync worker bundle changed; fully reload this application');
+    }
+    return new ClientSyncError(WORKER_FAILED_CODE, 'the sync worker failed');
+}
 /** Derive the complete ownership tuple for an independently owned replica. */
 export function isolatedReplicaNames(options) {
     if (!/^[A-Za-z0-9._-]+$/.test(options.replicaId)) {
@@ -403,7 +411,7 @@ async function startWorkerCore(options) {
             }
         };
         const onError = (event) => {
-            const error = new ClientSyncError(WORKER_FAILED_CODE, `the sync worker failed: ${event.message ?? 'unknown error'}`);
+            const error = workerStartupError(event.message);
             reject(error);
             for (const entry of pending.values())
                 entry.reject(error);

package/dist/worker-protocol.d.ts

@@ -34,6 +34,8 @@ import type { WindowBase } from './window.js';
 export declare const NOT_LEADER_CODE = "client.not_leader";
 /** The worker (or its RPC channel) failed outside protocol semantics. */
 export declare const WORKER_FAILED_CODE = "client.worker_failed";
+/** A page/worker bundle identity changed and a full host reload is required. */
+export declare const WORKER_RESTART_REQUIRED_CODE = "client.worker_restart_required";
 export type WorkerDatabaseInit = {
     /** THE persistent mode: opfs-sahpool, named database. */
     readonly mode: 'persistent';

package/dist/worker-protocol.js

@@ -5,3 +5,5 @@
 export const NOT_LEADER_CODE = 'client.not_leader';
 /** The worker (or its RPC channel) failed outside protocol semantics. */
 export const WORKER_FAILED_CODE = 'client.worker_failed';
+/** A page/worker bundle identity changed and a full host reload is required. */
+export const WORKER_RESTART_REQUIRED_CODE = 'client.worker_restart_required';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.15.29",
+  "version": "0.15.31",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -81,7 +81,7 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.15.29"
+    "@syncular/core": "0.15.31"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.15.29",
+    "@syncular/server": "0.15.31",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.11.1"
   }

package/src/client.ts

@@ -2524,7 +2524,8 @@ export class SyncClient {
       code === 'transport.failed' ||
       code === 'transport.unavailable' ||
       code === 'sync.transport_failed' ||
-      code === 'client.worker_failed'
+      code === 'client.worker_failed' ||
+      code === 'client.worker_restart_required'
     );
   }
 

package/src/worker-host.ts

@@ -92,6 +92,7 @@ import {
   NOT_LEADER_CODE,
   type SyncWorkerEvent,
   WORKER_FAILED_CODE,
+  WORKER_RESTART_REQUIRED_CODE,
   type WorkerApi,
   type WorkerDatabaseInit,
   type WorkerEndpoints,
@@ -103,6 +104,20 @@ import {
   type WorkerToMainMessage,
 } from './worker-protocol';
 
+const WORKER_BUNDLE_LOAD_FAILURE =
+  /(?:failed to fetch dynamically imported module|error loading dynamically imported module|importing a module script failed|failed to load module script)/iu;
+
+/** Classify startup without echoing a chunk URL or bundler text to UI/logs. */
+export function workerStartupError(message: unknown): ClientSyncError {
+  if (typeof message === 'string' && WORKER_BUNDLE_LOAD_FAILURE.test(message)) {
+    return new ClientSyncError(
+      WORKER_RESTART_REQUIRED_CODE,
+      'the sync worker bundle changed; fully reload this application',
+    );
+  }
+  return new ClientSyncError(WORKER_FAILED_CODE, 'the sync worker failed');
+}
+
 export type HandleRole = 'leader' | 'follower';
 
 export type BrowserReplicaMode =
@@ -717,10 +732,7 @@ async function startWorkerCore(options: {
       }
     };
     const onError = (event: ErrorEvent) => {
-      const error = new ClientSyncError(
-        WORKER_FAILED_CODE,
-        `the sync worker failed: ${event.message ?? 'unknown error'}`,
-      );
+      const error = workerStartupError(event.message);
       reject(error);
       for (const entry of pending.values()) entry.reject(error);
       pending.clear();

package/src/worker-protocol.ts

@@ -67,6 +67,8 @@ import type { WindowBase } from './window';
 export const NOT_LEADER_CODE = 'client.not_leader';
 /** The worker (or its RPC channel) failed outside protocol semantics. */
 export const WORKER_FAILED_CODE = 'client.worker_failed';
+/** A page/worker bundle identity changed and a full host reload is required. */
+export const WORKER_RESTART_REQUIRED_CODE = 'client.worker_restart_required';
 
 // ---------------------------------------------------------------------------
 // Init configuration (structured-clone safe)