@korajs/core 1.0.0-beta.1 → 1.0.0-beta.11

package/dist/bindings/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/bindings/index.ts","../../src/bindings/create-mutation-controller.ts"],"sourcesContent":["export type {\n\tAuthSyncBinding,\n\tKoraAppLike,\n\tKoraBindingSyncBridge,\n\tKoraBindingSyncStatus,\n\tKoraContextValue,\n\tUseMutationOptions,\n\tUseMutationResultBase,\n\tUseQueryOptions,\n} from './types'\nexport {\n\tcreateMutationController,\n\ttype CreateMutationControllerOptions,\n\ttype MutationController,\n\ttype MutationControllerState,\n} from './create-mutation-controller'\n","import type { UseMutationOptions } from './types'\n\nexport interface MutationControllerState {\n\tisLoading: boolean\n\terror: Error | null\n}\n\nexport interface MutationController<TData, TArgs extends unknown[], TContext = void> {\n\tgetSnapshot(): MutationControllerState\n\tsubscribe(listener: () => void): () => void\n\tmutate(...args: TArgs): void\n\tmutateAsync(...args: TArgs): Promise<TData>\n\treset(): void\n\tdestroy(): void\n}\n\nexport interface CreateMutationControllerOptions<TData, TArgs extends unknown[], TContext = void> {\n\tmutationFn: (...args: TArgs) => Promise<TData>\n\toptions?: UseMutationOptions<TData, TArgs, TContext>\n\t/** Reads latest options on each mutation (for framework hooks with ref-backed options). */\n\tresolveOptions?: () => UseMutationOptions<TData, TArgs, TContext> | undefined\n\tonStateChange?: (state: MutationControllerState) => void\n}\n\n/**\n * Framework-agnostic mutation runner with optimistic lifecycle hooks.\n */\nexport function createMutationController<TData, TArgs extends unknown[], TContext = void>(\n\toptions: CreateMutationControllerOptions<TData, TArgs, TContext>,\n): MutationController<TData, TArgs, TContext> {\n\tlet snapshot: MutationControllerState = { isLoading: false, error: null }\n\tconst listeners = new Set<() => void>()\n\tlet disposed = false\n\tlet inFlight = 0\n\n\tconst notify = (): void => {\n\t\tfor (const listener of listeners) {\n\t\t\tlistener()\n\t\t}\n\t\toptions.onStateChange?.(snapshot)\n\t}\n\n\tconst setSnapshot = (next: MutationControllerState): void => {\n\t\tsnapshot = next\n\t\tnotify()\n\t}\n\n\tconst getSnapshot = (): MutationControllerState => snapshot\n\n\tconst subscribe = (listener: () => void): (() => void) => {\n\t\tlisteners.add(listener)\n\t\treturn () => {\n\t\t\tlisteners.delete(listener)\n\t\t}\n\t}\n\n\tconst reset = (): void => {\n\t\tif (disposed) return\n\t\tsetSnapshot({ isLoading: false, error: null })\n\t}\n\n\tconst mutateAsync = async (...args: TArgs): Promise<TData> => {\n\t\tif (disposed) {\n\t\t\tthrow new Error('Mutation controller is destroyed')\n\t\t}\n\n\t\tconst opts = options.resolveOptions?.() ?? options.options\n\t\tlet context: TContext | undefined\n\n\t\tinFlight++\n\t\tsetSnapshot({ isLoading: true, error: null })\n\n\t\ttry {\n\t\t\tif (opts?.onMutate) {\n\t\t\t\tcontext = await opts.onMutate(...args)\n\t\t\t}\n\n\t\t\tconst result = await options.mutationFn(...args)\n\t\t\tinFlight = Math.max(0, inFlight - 1)\n\t\t\tsetSnapshot({ isLoading: inFlight > 0, error: null })\n\t\t\topts?.onSuccess?.(result, ...args)\n\t\t\topts?.onSettled?.(result, null, ...args)\n\t\t\treturn result\n\t\t} catch (err) {\n\t\t\tconst error = err instanceof Error ? err : new Error(String(err))\n\n\t\t\tif (context !== undefined && opts?.onRollback) {\n\t\t\t\tawait opts.onRollback(context, ...args)\n\t\t\t}\n\n\t\t\tinFlight = Math.max(0, inFlight - 1)\n\t\t\tsetSnapshot({ isLoading: inFlight > 0, error })\n\t\t\topts?.onError?.(error, ...args)\n\t\t\topts?.onSettled?.(undefined, error, ...args)\n\t\t\tthrow error\n\t\t}\n\t}\n\n\tconst mutate = (...args: TArgs): void => {\n\t\tvoid mutateAsync(...args).catch(() => {})\n\t}\n\n\tconst destroy = (): void => {\n\t\tdisposed = true\n\t\tlisteners.clear()\n\t}\n\n\treturn {\n\t\tgetSnapshot,\n\t\tsubscribe,\n\t\tmutate,\n\t\tmutateAsync,\n\t\treset,\n\t\tdestroy,\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;AC2BO,SAAS,yBACf,SAC6C;AAC7C,MAAI,WAAoC,EAAE,WAAW,OAAO,OAAO,KAAK;AACxE,QAAM,YAAY,oBAAI,IAAgB;AACtC,MAAI,WAAW;AACf,MAAI,WAAW;AAEf,QAAM,SAAS,MAAY;AAC1B,eAAW,YAAY,WAAW;AACjC,eAAS;AAAA,IACV;AACA,YAAQ,gBAAgB,QAAQ;AAAA,EACjC;AAEA,QAAM,cAAc,CAAC,SAAwC;AAC5D,eAAW;AACX,WAAO;AAAA,EACR;AAEA,QAAM,cAAc,MAA+B;AAEnD,QAAM,YAAY,CAAC,aAAuC;AACzD,cAAU,IAAI,QAAQ;AACtB,WAAO,MAAM;AACZ,gBAAU,OAAO,QAAQ;AAAA,IAC1B;AAAA,EACD;AAEA,QAAM,QAAQ,MAAY;AACzB,QAAI,SAAU;AACd,gBAAY,EAAE,WAAW,OAAO,OAAO,KAAK,CAAC;AAAA,EAC9C;AAEA,QAAM,cAAc,UAAU,SAAgC;AAC7D,QAAI,UAAU;AACb,YAAM,IAAI,MAAM,kCAAkC;AAAA,IACnD;AAEA,UAAM,OAAO,QAAQ,iBAAiB,KAAK,QAAQ;AACnD,QAAI;AAEJ;AACA,gBAAY,EAAE,WAAW,MAAM,OAAO,KAAK,CAAC;AAE5C,QAAI;AACH,UAAI,MAAM,UAAU;AACnB,kBAAU,MAAM,KAAK,SAAS,GAAG,IAAI;AAAA,MACtC;AAEA,YAAM,SAAS,MAAM,QAAQ,WAAW,GAAG,IAAI;AAC/C,iBAAW,KAAK,IAAI,GAAG,WAAW,CAAC;AACnC,kBAAY,EAAE,WAAW,WAAW,GAAG,OAAO,KAAK,CAAC;AACpD,YAAM,YAAY,QAAQ,GAAG,IAAI;AACjC,YAAM,YAAY,QAAQ,MAAM,GAAG,IAAI;AACvC,aAAO;AAAA,IACR,SAAS,KAAK;AACb,YAAM,QAAQ,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC;AAEhE,UAAI,YAAY,UAAa,MAAM,YAAY;AAC9C,cAAM,KAAK,WAAW,SAAS,GAAG,IAAI;AAAA,MACvC;AAEA,iBAAW,KAAK,IAAI,GAAG,WAAW,CAAC;AACnC,kBAAY,EAAE,WAAW,WAAW,GAAG,MAAM,CAAC;AAC9C,YAAM,UAAU,OAAO,GAAG,IAAI;AAC9B,YAAM,YAAY,QAAW,OAAO,GAAG,IAAI;AAC3C,YAAM;AAAA,IACP;AAAA,EACD;AAEA,QAAM,SAAS,IAAI,SAAsB;AACxC,SAAK,YAAY,GAAG,IAAI,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AAAA,EACzC;AAEA,QAAM,UAAU,MAAY;AAC3B,eAAW;AACX,cAAU,MAAM;AAAA,EACjB;AAEA,SAAO;AAAA,IACN;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACD;AACD;","names":[]}
+{"version":3,"sources":["../../src/bindings/index.ts","../../src/bindings/create-mutation-controller.ts"],"sourcesContent":["export type {\n\tAuthSyncBinding,\n\tAuthSyncState,\n\tKoraAppLike,\n\tKoraBindingSyncBridge,\n\tKoraBindingSyncStatus,\n\tKoraContextValue,\n\tUseMutationOptions,\n\tUseMutationResultBase,\n\tUseQueryOptions,\n} from './types'\nexport {\n\tcreateMutationController,\n\ttype CreateMutationControllerOptions,\n\ttype MutationController,\n\ttype MutationControllerState,\n} from './create-mutation-controller'\n","import type { UseMutationOptions } from './types'\n\nexport interface MutationControllerState {\n\tisLoading: boolean\n\terror: Error | null\n}\n\nexport interface MutationController<TData, TArgs extends unknown[], TContext = void> {\n\tgetSnapshot(): MutationControllerState\n\tsubscribe(listener: () => void): () => void\n\tmutate(...args: TArgs): void\n\tmutateAsync(...args: TArgs): Promise<TData>\n\treset(): void\n\tdestroy(): void\n}\n\nexport interface CreateMutationControllerOptions<TData, TArgs extends unknown[], TContext = void> {\n\tmutationFn: (...args: TArgs) => Promise<TData>\n\toptions?: UseMutationOptions<TData, TArgs, TContext>\n\t/** Reads latest options on each mutation (for framework hooks with ref-backed options). */\n\tresolveOptions?: () => UseMutationOptions<TData, TArgs, TContext> | undefined\n\tonStateChange?: (state: MutationControllerState) => void\n}\n\n/**\n * Framework-agnostic mutation runner with optimistic lifecycle hooks.\n */\nexport function createMutationController<TData, TArgs extends unknown[], TContext = void>(\n\toptions: CreateMutationControllerOptions<TData, TArgs, TContext>,\n): MutationController<TData, TArgs, TContext> {\n\tlet snapshot: MutationControllerState = { isLoading: false, error: null }\n\tconst listeners = new Set<() => void>()\n\tlet disposed = false\n\tlet inFlight = 0\n\n\tconst notify = (): void => {\n\t\tfor (const listener of listeners) {\n\t\t\tlistener()\n\t\t}\n\t\toptions.onStateChange?.(snapshot)\n\t}\n\n\tconst setSnapshot = (next: MutationControllerState): void => {\n\t\tsnapshot = next\n\t\tnotify()\n\t}\n\n\tconst getSnapshot = (): MutationControllerState => snapshot\n\n\tconst subscribe = (listener: () => void): (() => void) => {\n\t\tlisteners.add(listener)\n\t\treturn () => {\n\t\t\tlisteners.delete(listener)\n\t\t}\n\t}\n\n\tconst reset = (): void => {\n\t\tif (disposed) return\n\t\tsetSnapshot({ isLoading: false, error: null })\n\t}\n\n\tconst mutateAsync = async (...args: TArgs): Promise<TData> => {\n\t\tif (disposed) {\n\t\t\tthrow new Error('Mutation controller is destroyed')\n\t\t}\n\n\t\tconst opts = options.resolveOptions?.() ?? options.options\n\t\tlet context: TContext | undefined\n\n\t\tinFlight++\n\t\tsetSnapshot({ isLoading: true, error: null })\n\n\t\ttry {\n\t\t\tif (opts?.onMutate) {\n\t\t\t\tcontext = await opts.onMutate(...args)\n\t\t\t}\n\n\t\t\tconst result = await options.mutationFn(...args)\n\t\t\tinFlight = Math.max(0, inFlight - 1)\n\t\t\tsetSnapshot({ isLoading: inFlight > 0, error: null })\n\t\t\topts?.onSuccess?.(result, ...args)\n\t\t\topts?.onSettled?.(result, null, ...args)\n\t\t\treturn result\n\t\t} catch (err) {\n\t\t\tconst error = err instanceof Error ? err : new Error(String(err))\n\n\t\t\tif (context !== undefined && opts?.onRollback) {\n\t\t\t\tawait opts.onRollback(context, ...args)\n\t\t\t}\n\n\t\t\tinFlight = Math.max(0, inFlight - 1)\n\t\t\tsetSnapshot({ isLoading: inFlight > 0, error })\n\t\t\topts?.onError?.(error, ...args)\n\t\t\topts?.onSettled?.(undefined, error, ...args)\n\t\t\tthrow error\n\t\t}\n\t}\n\n\tconst mutate = (...args: TArgs): void => {\n\t\tvoid mutateAsync(...args).catch(() => {})\n\t}\n\n\tconst destroy = (): void => {\n\t\tdisposed = true\n\t\tlisteners.clear()\n\t}\n\n\treturn {\n\t\tgetSnapshot,\n\t\tsubscribe,\n\t\tmutate,\n\t\tmutateAsync,\n\t\treset,\n\t\tdestroy,\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;AC2BO,SAAS,yBACf,SAC6C;AAC7C,MAAI,WAAoC,EAAE,WAAW,OAAO,OAAO,KAAK;AACxE,QAAM,YAAY,oBAAI,IAAgB;AACtC,MAAI,WAAW;AACf,MAAI,WAAW;AAEf,QAAM,SAAS,MAAY;AAC1B,eAAW,YAAY,WAAW;AACjC,eAAS;AAAA,IACV;AACA,YAAQ,gBAAgB,QAAQ;AAAA,EACjC;AAEA,QAAM,cAAc,CAAC,SAAwC;AAC5D,eAAW;AACX,WAAO;AAAA,EACR;AAEA,QAAM,cAAc,MAA+B;AAEnD,QAAM,YAAY,CAAC,aAAuC;AACzD,cAAU,IAAI,QAAQ;AACtB,WAAO,MAAM;AACZ,gBAAU,OAAO,QAAQ;AAAA,IAC1B;AAAA,EACD;AAEA,QAAM,QAAQ,MAAY;AACzB,QAAI,SAAU;AACd,gBAAY,EAAE,WAAW,OAAO,OAAO,KAAK,CAAC;AAAA,EAC9C;AAEA,QAAM,cAAc,UAAU,SAAgC;AAC7D,QAAI,UAAU;AACb,YAAM,IAAI,MAAM,kCAAkC;AAAA,IACnD;AAEA,UAAM,OAAO,QAAQ,iBAAiB,KAAK,QAAQ;AACnD,QAAI;AAEJ;AACA,gBAAY,EAAE,WAAW,MAAM,OAAO,KAAK,CAAC;AAE5C,QAAI;AACH,UAAI,MAAM,UAAU;AACnB,kBAAU,MAAM,KAAK,SAAS,GAAG,IAAI;AAAA,MACtC;AAEA,YAAM,SAAS,MAAM,QAAQ,WAAW,GAAG,IAAI;AAC/C,iBAAW,KAAK,IAAI,GAAG,WAAW,CAAC;AACnC,kBAAY,EAAE,WAAW,WAAW,GAAG,OAAO,KAAK,CAAC;AACpD,YAAM,YAAY,QAAQ,GAAG,IAAI;AACjC,YAAM,YAAY,QAAQ,MAAM,GAAG,IAAI;AACvC,aAAO;AAAA,IACR,SAAS,KAAK;AACb,YAAM,QAAQ,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC;AAEhE,UAAI,YAAY,UAAa,MAAM,YAAY;AAC9C,cAAM,KAAK,WAAW,SAAS,GAAG,IAAI;AAAA,MACvC;AAEA,iBAAW,KAAK,IAAI,GAAG,WAAW,CAAC;AACnC,kBAAY,EAAE,WAAW,WAAW,GAAG,MAAM,CAAC;AAC9C,YAAM,UAAU,OAAO,GAAG,IAAI;AAC9B,YAAM,YAAY,QAAW,OAAO,GAAG,IAAI;AAC3C,YAAM;AAAA,IACP;AAAA,EACD;AAEA,QAAM,SAAS,IAAI,SAAsB;AACxC,SAAK,YAAY,GAAG,IAAI,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AAAA,EACzC;AAEA,QAAM,UAAU,MAAY;AAC3B,eAAW;AACX,cAAU,MAAM;AAAA,EACjB;AAEA,SAAO;AAAA,IACN;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACD;AACD;","names":[]}

package/dist/bindings/index.d.cts

@@ -1,9 +1,10 @@
-import { p as KoraEventEmitter } from '../events-CqDkr1LN.cjs';
-import { S as ScopeMap } from '../build-scope-map-DtTr9C7A.cjs';
+import { p as KoraEventEmitter } from '../events-BPbYUbrE.cjs';
+import { S as ScopeMap } from '../build-scope-map--0H8l6Tw.cjs';
 
 /** Sync status shape consumed by framework binding hooks (matches {@link SyncStatusInfo} in `@korajs/sync`). */
 interface KoraBindingSyncStatus {
-    status: 'connected' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-error';
+    status: 'connected' | 'reconnecting' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-error' | 'auth-required';
+    reconnecting: boolean;
     pendingOperations: number;
     lastSyncedAt: number | null;
     lastSuccessfulPush: number | null;
@@ -65,6 +66,8 @@ interface AuthSyncBinding {
     auth: () => Promise<{
         token: string;
     }>;
+    /** Resolve whether sync may currently open a transport. Tokens are never used as readiness signals. */
+    resolveSyncState?: () => Promise<AuthSyncState>;
     /** Builds a scope map from the current token and schema. */
     resolveScopeMap?: () => Promise<ScopeMap | undefined>;
     /**
@@ -72,9 +75,25 @@ interface AuthSyncBinding {
      * Separate from the user id (`sub`).
      */
     resolveNodeId?: () => Promise<string | undefined>;
+    /** Returns the authenticated user id used for local store namespacing. */
+    resolveUserId?: () => Promise<string | undefined>;
     /** Notifies when auth state changes so sync can refresh scope or reconnect. */
     subscribe?: (listener: () => void) => () => void;
 }
+/** Authentication state consumed by the sync and auth-isolated store lifecycles. */
+type AuthSyncState = {
+    state: 'loading';
+} | {
+    state: 'signed-out';
+    mayConnectAnonymously: false;
+} | {
+    state: 'anonymous';
+    mayConnectAnonymously: true;
+} | {
+    state: 'authenticated';
+    userId: string;
+    token: string;
+};
 
 interface MutationControllerState {
     isLoading: boolean;
@@ -100,4 +119,4 @@ interface CreateMutationControllerOptions<TData, TArgs extends unknown[], TConte
  */
 declare function createMutationController<TData, TArgs extends unknown[], TContext = void>(options: CreateMutationControllerOptions<TData, TArgs, TContext>): MutationController<TData, TArgs, TContext>;
 
-export { type AuthSyncBinding, type CreateMutationControllerOptions, type KoraAppLike, type KoraBindingSyncBridge, type KoraBindingSyncStatus, type KoraContextValue, type MutationController, type MutationControllerState, type UseMutationOptions, type UseMutationResultBase, type UseQueryOptions, createMutationController };
+export { type AuthSyncBinding, type AuthSyncState, type CreateMutationControllerOptions, type KoraAppLike, type KoraBindingSyncBridge, type KoraBindingSyncStatus, type KoraContextValue, type MutationController, type MutationControllerState, type UseMutationOptions, type UseMutationResultBase, type UseQueryOptions, createMutationController };

package/dist/bindings/index.d.ts

@@ -1,9 +1,10 @@
-import { p as KoraEventEmitter } from '../events-CqDkr1LN.js';
-import { S as ScopeMap } from '../build-scope-map-DvOHbYjn.js';
+import { p as KoraEventEmitter } from '../events-BPbYUbrE.js';
+import { S as ScopeMap } from '../build-scope-map-B3R_emUU.js';
 
 /** Sync status shape consumed by framework binding hooks (matches {@link SyncStatusInfo} in `@korajs/sync`). */
 interface KoraBindingSyncStatus {
-    status: 'connected' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-error';
+    status: 'connected' | 'reconnecting' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-error' | 'auth-required';
+    reconnecting: boolean;
     pendingOperations: number;
     lastSyncedAt: number | null;
     lastSuccessfulPush: number | null;
@@ -65,6 +66,8 @@ interface AuthSyncBinding {
     auth: () => Promise<{
         token: string;
     }>;
+    /** Resolve whether sync may currently open a transport. Tokens are never used as readiness signals. */
+    resolveSyncState?: () => Promise<AuthSyncState>;
     /** Builds a scope map from the current token and schema. */
     resolveScopeMap?: () => Promise<ScopeMap | undefined>;
     /**
@@ -72,9 +75,25 @@ interface AuthSyncBinding {
      * Separate from the user id (`sub`).
      */
     resolveNodeId?: () => Promise<string | undefined>;
+    /** Returns the authenticated user id used for local store namespacing. */
+    resolveUserId?: () => Promise<string | undefined>;
     /** Notifies when auth state changes so sync can refresh scope or reconnect. */
     subscribe?: (listener: () => void) => () => void;
 }
+/** Authentication state consumed by the sync and auth-isolated store lifecycles. */
+type AuthSyncState = {
+    state: 'loading';
+} | {
+    state: 'signed-out';
+    mayConnectAnonymously: false;
+} | {
+    state: 'anonymous';
+    mayConnectAnonymously: true;
+} | {
+    state: 'authenticated';
+    userId: string;
+    token: string;
+};
 
 interface MutationControllerState {
     isLoading: boolean;
@@ -100,4 +119,4 @@ interface CreateMutationControllerOptions<TData, TArgs extends unknown[], TConte
  */
 declare function createMutationController<TData, TArgs extends unknown[], TContext = void>(options: CreateMutationControllerOptions<TData, TArgs, TContext>): MutationController<TData, TArgs, TContext>;
 
-export { type AuthSyncBinding, type CreateMutationControllerOptions, type KoraAppLike, type KoraBindingSyncBridge, type KoraBindingSyncStatus, type KoraContextValue, type MutationController, type MutationControllerState, type UseMutationOptions, type UseMutationResultBase, type UseQueryOptions, createMutationController };
+export { type AuthSyncBinding, type AuthSyncState, type CreateMutationControllerOptions, type KoraAppLike, type KoraBindingSyncBridge, type KoraBindingSyncStatus, type KoraContextValue, type MutationController, type MutationControllerState, type UseMutationOptions, type UseMutationResultBase, type UseQueryOptions, createMutationController };

package/dist/{build-scope-map-DtTr9C7A.d.cts → build-scope-map--0H8l6Tw.d.cts}

@@ -1,4 +1,4 @@
-import { S as SchemaDefinition } from './events-CqDkr1LN.cjs';
+import { S as SchemaDefinition } from './events-BPbYUbrE.cjs';
 
 /**
  * Per-collection scope map: `{ collectionName: { field: value, ... } }`

package/dist/{build-scope-map-DvOHbYjn.d.ts → build-scope-map-B3R_emUU.d.ts}

@@ -1,4 +1,4 @@
-import { S as SchemaDefinition } from './events-CqDkr1LN.js';
+import { S as SchemaDefinition } from './events-BPbYUbrE.js';
 
 /**
  * Per-collection scope map: `{ collectionName: { field: value, ... } }`

package/dist/{events-CqDkr1LN.d.cts → events-BPbYUbrE.d.cts}

@@ -486,7 +486,7 @@ interface BlobRef {
  */
 interface SyncDiagnosticsSnapshot {
     /** Current developer-facing sync status */
-    status: 'connected' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-error';
+    status: 'connected' | 'reconnecting' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-error' | 'auth-required';
     /** Timestamp when the current connection was established, or null if disconnected */
     connectedAt: number | null;
     /** Timestamp when the last disconnection occurred, or null if never disconnected */
@@ -738,6 +738,16 @@ interface SequenceConfig {
     startAt?: number;
 }
 
+interface SyncApplyFailureEvent {
+    operationId: string;
+    collection: string;
+    recordId: string;
+    code: string;
+    message: string;
+    retriable: boolean;
+    firstSeenAt: number;
+    retryCount: number;
+}
 /**
  * Trace of a merge decision. Records all inputs and outputs for debugging and DevTools.
  */
@@ -795,6 +805,21 @@ type KoraEvent = {
 } | {
     type: 'sync:auth-failed';
     reason: string;
+} | {
+    type: 'sync:suspended';
+    reason: 'auth-loading' | 'auth-required' | 'auth-rejected' | 'device-revoked' | string;
+} | {
+    type: 'sync:apply-blocked';
+    failure: SyncApplyFailureEvent;
+} | {
+    type: 'sync:apply-retrying';
+    failure: SyncApplyFailureEvent;
+} | {
+    type: 'sync:apply-recovered';
+    failure: SyncApplyFailureEvent;
+} | {
+    type: 'sync:apply-abandoned';
+    failure: SyncApplyFailureEvent;
 } | {
     type: 'sync:clock-skew';
     /** serverTime - localTime in ms. Negative = this device's clock is fast. */
@@ -826,6 +851,33 @@ type KoraEvent = {
     code: string;
     message: string;
     retriable: boolean;
+} | {
+    /**
+     * The server rejected one of THIS client's outbound operations before it
+     * became authoritative. The op has been diverted out of the pending sync
+     * queue into the durable rejected store (kept, not retried); the app can
+     * surface the reason and decide whether to roll back the optimistic local
+     * write or let the user edit and resubmit.
+     */
+    type: 'sync:operation-rejected';
+    operationId: string;
+    collection: string;
+    recordId: string;
+    code: string;
+    message: string;
+    retriable: boolean;
+} | {
+    type: 'sync:delivery-gap';
+    expectedBase: number;
+    receivedBase: number;
+    currentWatermark: number;
+    messageId: string;
+    repeatCount: number;
+} | {
+    type: 'sync:delivery-stalled';
+    sessionId: string;
+    watermark: number;
+    repeatCount: number;
 } | {
     type: 'query:subscribed';
     queryId: string;
@@ -880,6 +932,46 @@ type KoraEvent = {
     type: 'store:quota-exceeded';
     dbName: string;
     message: string;
+} | {
+    /**
+     * OPFS persistence was unavailable, so the store fell back to a
+     * NON-PERSISTENT in-memory database. Anything written this session is lost
+     * on reload. This is emitted instead of failing silently so the condition
+     * is observable rather than a data-loss trap.
+     */
+    type: 'store:opfs-unavailable';
+    dbName: string;
+    /**
+     * Why OPFS could not be used. `lock-conflict` means another runtime on this
+     * origin already holds the OPFS pool for this database; `timeout` means the
+     * VFS install did not complete in time (common in headless CI); `unsupported`
+     * means the runtime has no usable OPFS.
+     */
+    reason: 'lock-conflict' | 'timeout' | 'unsupported';
+    message: string;
+} | {
+    /**
+     * A preferred storage backend could not provide durable storage, so Kora
+     * promoted the app to another durable backend before user code observed the
+     * store. This is informational: data still survives reloads.
+     */
+    type: 'store:storage-fallback';
+    dbName: string;
+    from: 'opfs' | 'sqlite-wasm';
+    to: 'indexeddb';
+    reason: 'lock-conflict' | 'timeout' | 'unsupported';
+    message: string;
+} | {
+    /**
+     * Another runtime on this origin was already using this database name, so
+     * this runtime attached to it as a follower and now SHARES that one
+     * database. That is intended for multiple tabs of the SAME app; it is a bug
+     * if these are logically separate apps, which should each use a distinct
+     * store name (`store: { name: '...' }`) to stay isolated.
+     */
+    type: 'store:db-name-collision';
+    dbName: string;
+    message: string;
 } | {
     type: 'replay:completed';
     targetOperationId: string;

package/dist/{events-CqDkr1LN.d.ts → events-BPbYUbrE.d.ts}

@@ -486,7 +486,7 @@ interface BlobRef {
  */
 interface SyncDiagnosticsSnapshot {
     /** Current developer-facing sync status */
-    status: 'connected' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-error';
+    status: 'connected' | 'reconnecting' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-error' | 'auth-required';
     /** Timestamp when the current connection was established, or null if disconnected */
     connectedAt: number | null;
     /** Timestamp when the last disconnection occurred, or null if never disconnected */
@@ -738,6 +738,16 @@ interface SequenceConfig {
     startAt?: number;
 }
 
+interface SyncApplyFailureEvent {
+    operationId: string;
+    collection: string;
+    recordId: string;
+    code: string;
+    message: string;
+    retriable: boolean;
+    firstSeenAt: number;
+    retryCount: number;
+}
 /**
  * Trace of a merge decision. Records all inputs and outputs for debugging and DevTools.
  */
@@ -795,6 +805,21 @@ type KoraEvent = {
 } | {
     type: 'sync:auth-failed';
     reason: string;
+} | {
+    type: 'sync:suspended';
+    reason: 'auth-loading' | 'auth-required' | 'auth-rejected' | 'device-revoked' | string;
+} | {
+    type: 'sync:apply-blocked';
+    failure: SyncApplyFailureEvent;
+} | {
+    type: 'sync:apply-retrying';
+    failure: SyncApplyFailureEvent;
+} | {
+    type: 'sync:apply-recovered';
+    failure: SyncApplyFailureEvent;
+} | {
+    type: 'sync:apply-abandoned';
+    failure: SyncApplyFailureEvent;
 } | {
     type: 'sync:clock-skew';
     /** serverTime - localTime in ms. Negative = this device's clock is fast. */
@@ -826,6 +851,33 @@ type KoraEvent = {
     code: string;
     message: string;
     retriable: boolean;
+} | {
+    /**
+     * The server rejected one of THIS client's outbound operations before it
+     * became authoritative. The op has been diverted out of the pending sync
+     * queue into the durable rejected store (kept, not retried); the app can
+     * surface the reason and decide whether to roll back the optimistic local
+     * write or let the user edit and resubmit.
+     */
+    type: 'sync:operation-rejected';
+    operationId: string;
+    collection: string;
+    recordId: string;
+    code: string;
+    message: string;
+    retriable: boolean;
+} | {
+    type: 'sync:delivery-gap';
+    expectedBase: number;
+    receivedBase: number;
+    currentWatermark: number;
+    messageId: string;
+    repeatCount: number;
+} | {
+    type: 'sync:delivery-stalled';
+    sessionId: string;
+    watermark: number;
+    repeatCount: number;
 } | {
     type: 'query:subscribed';
     queryId: string;
@@ -880,6 +932,46 @@ type KoraEvent = {
     type: 'store:quota-exceeded';
     dbName: string;
     message: string;
+} | {
+    /**
+     * OPFS persistence was unavailable, so the store fell back to a
+     * NON-PERSISTENT in-memory database. Anything written this session is lost
+     * on reload. This is emitted instead of failing silently so the condition
+     * is observable rather than a data-loss trap.
+     */
+    type: 'store:opfs-unavailable';
+    dbName: string;
+    /**
+     * Why OPFS could not be used. `lock-conflict` means another runtime on this
+     * origin already holds the OPFS pool for this database; `timeout` means the
+     * VFS install did not complete in time (common in headless CI); `unsupported`
+     * means the runtime has no usable OPFS.
+     */
+    reason: 'lock-conflict' | 'timeout' | 'unsupported';
+    message: string;
+} | {
+    /**
+     * A preferred storage backend could not provide durable storage, so Kora
+     * promoted the app to another durable backend before user code observed the
+     * store. This is informational: data still survives reloads.
+     */
+    type: 'store:storage-fallback';
+    dbName: string;
+    from: 'opfs' | 'sqlite-wasm';
+    to: 'indexeddb';
+    reason: 'lock-conflict' | 'timeout' | 'unsupported';
+    message: string;
+} | {
+    /**
+     * Another runtime on this origin was already using this database name, so
+     * this runtime attached to it as a follower and now SHARES that one
+     * database. That is intended for multiple tabs of the SAME app; it is a bug
+     * if these are logically separate apps, which should each use a distinct
+     * store name (`store: { name: '...' }`) to stay isolated.
+     */
+    type: 'store:db-name-collision';
+    dbName: string;
+    message: string;
 } | {
     type: 'replay:completed';
     targetOperationId: string;