korajs 0.5.0 → 0.6.0

package/dist/index.js

@@ -6,19 +6,57 @@ import {
 } from "./chunk-WALHLVVF.js";
 
 // src/create-app.ts
-import { buildScopeMap } from "@korajs/core";
 import { SimpleEventEmitter } from "@korajs/core/internal";
-import { Instrumenter } from "@korajs/devtools";
 import { MergeEngine } from "@korajs/merge";
+import { QueryStoreCache } from "@korajs/store";
+
+// src/collection-accessor.ts
+import { AppNotReadyError } from "@korajs/core";
+function createCollectionAccessor(collectionName, getStore) {
+  const notReady = (action) => new AppNotReadyError(
+    `Cannot ${action} on collection "${collectionName}" before app.ready. Await app.ready or use <KoraProvider app={app}>.`
+  );
+  return {
+    async insert(data) {
+      const currentStore = getStore();
+      if (!currentStore) {
+        throw notReady("insert into");
+      }
+      return currentStore.collection(collectionName).insert(data);
+    },
+    async findById(id) {
+      const currentStore = getStore();
+      if (!currentStore) return null;
+      return currentStore.collection(collectionName).findById(id);
+    },
+    async update(id, data) {
+      const currentStore = getStore();
+      if (!currentStore) {
+        throw notReady("update");
+      }
+      return currentStore.collection(collectionName).update(id, data);
+    },
+    async delete(id) {
+      const currentStore = getStore();
+      if (!currentStore) {
+        throw notReady("delete from");
+      }
+      return currentStore.collection(collectionName).delete(id);
+    },
+    where(conditions) {
+      const currentStore = getStore();
+      if (!currentStore) {
+        throw notReady("query");
+      }
+      return currentStore.collection(collectionName).where(conditions);
+    }
+  };
+}
+
+// src/initialize-app.ts
+import { buildScopeMap } from "@korajs/core";
 import { Store } from "@korajs/store";
-import {
-  ConnectionMonitor,
-  HttpLongPollingTransport,
-  ReconnectionManager,
-  SyncEncryptor,
-  SyncEngine,
-  WebSocketTransport
-} from "@korajs/sync";
+import { SyncEncryptor, SyncEngine } from "@korajs/sync";
 
 // src/adapter-resolver.ts
 function importOptionalPeer(specifier) {
@@ -68,17 +106,6 @@ async function createAdapter(type, dbName, workerUrl, emitter, workerResponseTim
   }
 }
 
-// src/app-not-ready-error.ts
-import { KoraError } from "@korajs/core";
-var AppNotReadyError = class extends KoraError {
-  constructor(detail) {
-    super(detail, "APP_NOT_READY", {
-      fix: "Await app.ready, or wrap your UI in <KoraProvider app={app}> before calling useQuery()."
-    });
-    this.name = "AppNotReadyError";
-  }
-};
-
 // src/audit-bridge.ts
 import { persistedAuditTraceFromEvent } from "@korajs/store";
 var AUDIT_EVENT_TYPES = ["merge:completed", "merge:conflict", "constraint:violated"];
@@ -103,9 +130,19 @@ function wireAuditPersistence(store, emitter) {
   };
 }
 
+// src/create-sync-transport.ts
+import { HttpLongPollingTransport, WebSocketTransport } from "@korajs/sync";
+function createSyncTransport(sync) {
+  if (sync.transport === "http") {
+    return new HttpLongPollingTransport();
+  }
+  return new WebSocketTransport();
+}
+
 // src/sync-query-bridge.ts
 function queryDescriptorToSyncSubset(descriptor) {
   const where = {};
+  const skippedFields = [];
   for (const [field, value] of Object.entries(descriptor.where)) {
     if (value === null || value === void 0) {
       where[field] = value;
@@ -113,7 +150,14 @@ function queryDescriptorToSyncSubset(descriptor) {
     }
     if (typeof value !== "object" || Array.isArray(value)) {
       where[field] = value;
+      continue;
     }
+    skippedFields.push(field);
+  }
+  if (skippedFields.length > 0 && typeof console !== "undefined") {
+    console.warn(
+      `[Kora] Sync query subset omitted non-equality filters on ${descriptor.collection}: ${skippedFields.join(", ")}. Only plain equality WHERE clauses are registered for incremental sync.`
+    );
   }
   if (Object.keys(where).length === 0) {
     return null;
@@ -139,297 +183,148 @@ function createSyncQuerySubscriptionHook(getSyncEngine) {
   };
 }
 
-// src/sync-status-bridge.ts
-var OFFLINE_STATUS = Object.freeze({
-  status: "offline",
-  pendingOperations: 0,
-  lastSyncedAt: null,
-  lastSuccessfulPush: null,
-  lastSuccessfulPull: null,
-  conflicts: 0
-});
-var SYNC_STATUS_EVENT_TYPES = [
-  "sync:connected",
-  "sync:disconnected",
-  "sync:schema-mismatch",
-  "sync:auth-failed",
-  "sync:sent",
-  "sync:received",
-  "sync:acknowledged",
-  "sync:apply-failed",
-  "sync:diagnostics",
-  "sync:initial-sync-progress"
-];
-function createSyncStatusBridge(emitter, getSyncEngine) {
-  let currentStatus = OFFLINE_STATUS;
-  const listeners = /* @__PURE__ */ new Set();
-  const refresh = () => {
-    const engine = getSyncEngine();
-    const next = engine ? engine.getStatus() : OFFLINE_STATUS;
-    const prevSerialized = JSON.stringify(currentStatus);
-    const nextSerialized = JSON.stringify(next);
-    if (prevSerialized === nextSerialized) {
-      return;
+// src/initialize-app.ts
+async function initializeApp(config, emitter, mergeEngine) {
+  const adapterType = config.store?.adapter ?? detectAdapterType();
+  const dbName = config.store?.name ?? "kora-db";
+  const adapter = await createAdapter(
+    adapterType,
+    dbName,
+    config.store?.workerUrl,
+    emitter,
+    config.store?.workerResponseTimeoutMs,
+    config.store?.sharedWorkerUrl
+  );
+  const authBinding = config.sync?.authClient ?? null;
+  const authNodeId = authBinding?.resolveNodeId ? await authBinding.resolveNodeId() : void 0;
+  let syncEngine = null;
+  const store = new Store({
+    schema: config.schema,
+    adapter,
+    emitter,
+    dbName,
+    nodeId: authNodeId,
+    isolation: authNodeId ? "shared" : config.store?.isolation,
+    ...config.sync ? { onQuerySubscribed: createSyncQuerySubscriptionHook(() => syncEngine) } : {}
+  });
+  await store.open();
+  let recordConflict;
+  const applyPipeline = new ApplyPipeline({
+    store,
+    mergeEngine,
+    emitter,
+    onMergeConflict: () => recordConflict?.()
+  });
+  store.setLocalMutationHandler(applyPipeline);
+  const unsubscribeAudit = wireAuditPersistence(store, emitter);
+  let unsubscribeSync = null;
+  if (config.sync) {
+    const transport = createSyncTransport(config.sync);
+    const mergeAwareStore = new MergeAwareSyncStore(store, mergeEngine, emitter, {
+      onMergeConflict: () => recordConflict?.()
+    });
+    let scopeMap = config.sync.scope ? buildScopeMap(config.schema, config.sync.scope) : void 0;
+    if (authBinding?.resolveScopeMap) {
+      scopeMap = await authBinding.resolveScopeMap() ?? scopeMap;
     }
-    currentStatus = next;
-    for (const listener of listeners) {
-      listener(currentStatus);
+    const syncAuth = authBinding?.auth ?? config.sync.auth;
+    const encryptor = config.sync.encryption?.enabled === true ? await SyncEncryptor.create(config.sync.encryption) : void 0;
+    syncEngine = new SyncEngine({
+      transport,
+      store: mergeAwareStore,
+      config: {
+        url: config.sync.url,
+        transport: config.sync.transport,
+        auth: syncAuth,
+        batchSize: config.sync.batchSize,
+        schemaVersion: config.sync.schemaVersion ?? config.schema.version,
+        scopeMap,
+        encryption: config.sync.encryption,
+        strictHandshake: config.sync.strictHandshake,
+        operationTransforms: config.sync.operationTransforms
+      },
+      emitter,
+      queueStorage: new StoreQueueStorage(adapter),
+      syncState: new StoreSyncStatePersistence(store, scopeMap),
+      encryptor
+    });
+    recordConflict = () => syncEngine?.recordConflict();
+    unsubscribeSync = emitter.on("operation:created", (event) => {
+      if (syncEngine) {
+        syncEngine.pushOperation(event.operation);
+      }
+    });
+  }
+  return {
+    store,
+    syncEngine,
+    unsubscribeSync,
+    unsubscribeAudit,
+    authBinding
+  };
+}
+
+// src/sequences-accessor.ts
+function createSequencesAccessor(ready, getStore) {
+  const requireStore = async () => {
+    await ready;
+    const store = getStore();
+    if (!store) {
+      throw new Error("Store not initialized. Await app.ready before using sequences.");
     }
+    return store;
   };
-  const unsubs = [];
-  for (const type of SYNC_STATUS_EVENT_TYPES) {
-    unsubs.push(emitter.on(type, refresh));
-  }
-  const bridge = {
-    get status() {
-      return currentStatus;
+  return {
+    async next(name, config) {
+      const store = await requireStore();
+      return store.getSequenceManager().next(name, config);
     },
-    subscribe(listener) {
-      listeners.add(listener);
-      listener(currentStatus);
-      return () => {
-        listeners.delete(listener);
-      };
+    async current(name, config) {
+      const store = await requireStore();
+      return store.getSequenceManager().current(name, config);
     },
-    refresh,
-    destroy() {
-      for (const unsub of unsubs) {
-        unsub();
-      }
-      unsubs.length = 0;
-      listeners.clear();
+    async reset(name, config) {
+      const store = await requireStore();
+      return store.getSequenceManager().reset(name, config);
     }
   };
-  refresh();
-  return bridge;
 }
 
-// src/validate-config.ts
-import { KoraError as KoraError2, SchemaValidationError } from "@korajs/core";
-function validateCreateAppConfig(config) {
-  if (!config.schema) {
-    throw new SchemaValidationError("createApp requires a schema.", {
-      fix: "Pass schema: defineSchema({ version: 1, collections: { ... } })"
-    });
-  }
-  if (config.schema.version < 1) {
-    throw new SchemaValidationError("Schema version must be at least 1.", {
-      version: config.schema.version
-    });
-  }
-  const collectionNames = Object.keys(config.schema.collections);
-  if (collectionNames.length === 0) {
-    throw new SchemaValidationError("Schema must define at least one collection.", {
-      fix: "Add entries under collections in defineSchema()."
-    });
-  }
-  if (config.sync) {
-    validateSyncUrl(config.sync.url, config.sync.transport ?? "websocket");
-  }
-  const adapter = config.store?.adapter ?? detectAdapterType();
-  const isBrowser = typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined";
-  if (isBrowser && (adapter === "sqlite-wasm" || adapter === "indexeddb") && !config.store?.workerUrl) {
-    throw new KoraError2(
-      "Browser storage requires store.workerUrl pointing to the SQLite WASM worker script.",
-      "MISSING_WORKER_URL",
-      {
-        adapter,
-        fix: 'Add store: { workerUrl: "/sqlite-wasm-worker.js" } (see create-kora-app templates).'
-      }
-    );
+// src/setup-devtools.ts
+import { Instrumenter } from "@korajs/devtools";
+function setupDevtools(config, emitter) {
+  if (!config.devtools) {
+    return { instrumenter: null, destroyOverlay: null };
   }
-}
-function validateSyncUrl(url, transport) {
-  if (!url || url.trim().length === 0) {
-    throw new KoraError2("sync.url is required when sync is configured.", "INVALID_SYNC_URL", {
-      fix: 'Pass sync: { url: "wss://your-server/kora" }.'
+  const instrumenter = new Instrumenter(emitter, {
+    bridgeEnabled: typeof globalThis !== "undefined" && "window" in globalThis
+  });
+  let destroyOverlay = null;
+  if (typeof globalThis !== "undefined" && "window" in globalThis) {
+    void import("@korajs/devtools/overlay").then(({ mountKoraDevtoolsOverlay }) => {
+      destroyOverlay = mountKoraDevtoolsOverlay(instrumenter);
+    }).catch(() => {
     });
   }
-  try {
-    const parsed = new URL(url);
-    if (transport === "http") {
-      if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-        throw new Error("bad protocol");
-      }
-    } else if (parsed.protocol !== "ws:" && parsed.protocol !== "wss:") {
-      throw new Error("bad protocol");
-    }
-  } catch {
-    throw new KoraError2(
-      `Invalid sync URL "${url}" for transport "${transport}".`,
-      "INVALID_SYNC_URL",
-      {
-        url,
-        transport,
-        fix: transport === "http" ? "Use an absolute http:// or https:// URL." : "Use an absolute ws:// or wss:// URL."
-      }
-    );
-  }
+  return { instrumenter, destroyOverlay: () => destroyOverlay?.() };
 }
 
-// src/create-app.ts
-function createApp(config) {
-  validateCreateAppConfig(config);
-  const emitter = new SimpleEventEmitter();
-  const mergeEngine = new MergeEngine();
-  if (config.onSyncEvent) {
-    const handler = config.onSyncEvent;
-    const syncTypes = [
-      "sync:connected",
-      "sync:disconnected",
-      "sync:schema-mismatch",
-      "sync:auth-failed",
-      "sync:sent",
-      "sync:received",
-      "sync:acknowledged",
-      "sync:apply-failed",
-      "sync:diagnostics",
-      "sync:bandwidth",
-      "sync:initial-sync-progress"
-    ];
-    for (const type of syncTypes) {
-      emitter.on(type, (event) => {
-        handler(event);
-      });
-    }
-  }
-  let store = null;
-  let syncEngine = null;
-  let unsubscribeSync = null;
-  let unsubscribeAudit = null;
-  let reconnectionManager = null;
-  let connectionMonitor = null;
-  let instrumenter = null;
-  let intentionalDisconnect = false;
-  let qualityInterval = null;
-  let syncStatusBridge = null;
-  let destroyDevtoolsOverlay = null;
-  if (config.devtools) {
-    instrumenter = new Instrumenter(emitter, {
-      bridgeEnabled: typeof globalThis !== "undefined" && "window" in globalThis
-    });
-    if (typeof globalThis !== "undefined" && "window" in globalThis) {
-      void import("@korajs/devtools/overlay").then(({ mountKoraDevtoolsOverlay }) => {
-        if (instrumenter) {
-          destroyDevtoolsOverlay = mountKoraDevtoolsOverlay(instrumenter);
-        }
-      }).catch(() => {
-      });
-    }
+// src/sync-control.ts
+import { OFFLINE_SYNC_STATUS } from "@korajs/sync";
+function createSyncControl(options) {
+  const { config, ready, state } = options;
+  if (!config.sync) {
+    return null;
   }
-  const ready = initializeAsync(config, emitter, mergeEngine).then((result) => {
-    store = result.store;
-    syncEngine = result.syncEngine;
-    unsubscribeSync = result.unsubscribeSync;
-    unsubscribeAudit = result.unsubscribeAudit;
-    const authBinding = result.authBinding;
-    if (config.sync) {
-      syncStatusBridge = createSyncStatusBridge(emitter, () => syncEngine);
-      syncStatusBridge.refresh();
-    }
-    if (config.sync && syncEngine && authBinding?.subscribe) {
-      authBinding.subscribe(() => {
-        const engine = syncEngine;
-        if (!engine) {
-          return;
-        }
-        void (async () => {
-          const headers = await authBinding.auth();
-          if (!headers.token) {
-            await engine.stop();
-            return;
-          }
-          if (authBinding.resolveScopeMap) {
-            const nextScope = await authBinding.resolveScopeMap();
-            engine.updateScope(nextScope);
-          }
-          const status = engine.getStatus().status;
-          if (status !== "offline") {
-            await engine.stop();
-          }
-          await engine.start();
-        })();
-      });
-    }
-    if (config.sync && syncEngine) {
-      connectionMonitor = new ConnectionMonitor();
-      reconnectionManager = new ReconnectionManager({
-        initialDelay: config.sync.reconnectInterval,
-        maxDelay: config.sync.maxReconnectInterval
-      });
-      emitter.on("sync:sent", () => connectionMonitor?.recordActivity());
-      emitter.on("sync:received", () => connectionMonitor?.recordActivity());
-      emitter.on("sync:acknowledged", () => connectionMonitor?.recordActivity());
-      emitter.on("sync:connected", () => {
-        if (qualityInterval !== null) clearInterval(qualityInterval);
-        qualityInterval = setInterval(() => {
-          if (connectionMonitor) {
-            emitter.emit({ type: "connection:quality", quality: connectionMonitor.getQuality() });
-          }
-        }, 5e3);
-      });
-      emitter.on("sync:disconnected", () => {
-        connectionMonitor?.reset();
-        if (qualityInterval !== null) {
-          clearInterval(qualityInterval);
-          qualityInterval = null;
-        }
-      });
-      const browserGlobal = globalThis;
-      if (typeof browserGlobal.addEventListener === "function") {
-        const engine = syncEngine;
-        browserGlobal.addEventListener("online", () => {
-          if (intentionalDisconnect || config.sync?.autoReconnect === false) return;
-          reconnectionManager?.wake();
-          reconnectionManager?.reset();
-          void engine.retryNow();
-        });
-      }
-      emitter.on("sync:schema-mismatch", () => {
-        reconnectionManager?.stop();
-        intentionalDisconnect = true;
-      });
-      if (config.sync.autoReconnect !== false) {
-        const engine = syncEngine;
-        emitter.on("sync:disconnected", () => {
-          if (intentionalDisconnect || engine.isSchemaBlocked()) return;
-          if (reconnectionManager?.isRunning()) return;
-          engine.setReconnecting(true);
-          reconnectionManager?.stop();
-          reconnectionManager?.start(async () => {
-            try {
-              await engine.start();
-              engine.setReconnecting(false);
-              return true;
-            } catch {
-              return false;
-            }
-          }).then(() => {
-            engine.setReconnecting(false);
-          });
-        });
-      }
-      if (config.sync.autoConnect === true && syncEngine) {
-        void syncEngine.start().catch(() => {
-        });
-      }
-    }
-  });
-  const offlineSyncStatus = () => ({
-    status: "offline",
-    pendingOperations: 0,
-    lastSyncedAt: null,
-    lastSuccessfulPush: null,
-    lastSuccessfulPull: null,
-    conflicts: 0
-  });
-  const syncControl = config.sync ? {
+  const offlineSyncStatus = () => OFFLINE_SYNC_STATUS;
+  const bridgeStatus = () => state.syncStatusBridge?.status ?? offlineSyncStatus();
+  return {
     get status() {
-      return syncStatusBridge?.status ?? offlineSyncStatus();
+      return bridgeStatus();
     },
     subscribeStatus(listener) {
-      if (syncStatusBridge) {
-        return syncStatusBridge.subscribe(listener);
+      if (state.syncStatusBridge) {
+        return state.syncStatusBridge.subscribe(listener);
       }
       listener(offlineSyncStatus());
       return () => {
@@ -437,41 +332,41 @@ function createApp(config) {
     },
     async connect() {
       await ready;
-      if (syncEngine) {
-        intentionalDisconnect = false;
-        reconnectionManager?.stop();
-        reconnectionManager?.reset();
-        await syncEngine.start();
-        syncStatusBridge?.refresh();
+      if (state.syncEngine) {
+        state.intentionalDisconnect = false;
+        state.reconnectionManager?.stop();
+        state.reconnectionManager?.reset();
+        await state.syncEngine.start();
+        state.syncStatusBridge?.refresh();
       }
     },
     async disconnect() {
       await ready;
-      if (syncEngine) {
-        intentionalDisconnect = true;
-        reconnectionManager?.stop();
-        await syncEngine.stop();
-        syncStatusBridge?.refresh();
+      if (state.syncEngine) {
+        state.intentionalDisconnect = true;
+        state.reconnectionManager?.stop();
+        await state.syncEngine.stop();
+        state.syncStatusBridge?.refresh();
       }
     },
     getStatus() {
-      if (syncEngine) {
-        return syncEngine.getStatus();
+      if (state.syncEngine) {
+        return state.syncEngine.getStatus();
       }
       return offlineSyncStatus();
     },
     async retryNow() {
       await ready;
-      if (syncEngine) {
-        await syncEngine.retryNow();
+      if (state.syncEngine) {
+        await state.syncEngine.retryNow();
       }
     },
     clearSchemaBlock() {
-      syncEngine?.clearSchemaBlock();
+      state.syncEngine?.clearSchemaBlock();
     },
     exportDiagnostics() {
-      if (syncEngine) {
-        return syncEngine.exportDiagnostics();
+      if (state.syncEngine) {
+        return state.syncEngine.exportDiagnostics();
       }
       return {
         state: "disconnected",
@@ -496,10 +391,201 @@ function createApp(config) {
         timestamp: Date.now()
       };
     }
-  } : null;
-  async function executeTransaction(fn, mutationName) {
-    await ready;
-    if (!store) {
+  };
+}
+
+// src/auth-sync-coordinator.ts
+var AuthSyncCoordinator = class {
+  constructor(getEngine, authBinding) {
+    this.getEngine = getEngine;
+    this.authBinding = authBinding;
+  }
+  getEngine;
+  authBinding;
+  inFlight = null;
+  pending = false;
+  disposed = false;
+  scheduleReconnect() {
+    if (this.disposed) {
+      return;
+    }
+    if (this.inFlight) {
+      this.pending = true;
+      return;
+    }
+    this.inFlight = this.run().finally(() => {
+      this.inFlight = null;
+      if (this.pending && !this.disposed) {
+        this.pending = false;
+        this.scheduleReconnect();
+      }
+    });
+  }
+  destroy() {
+    this.disposed = true;
+    this.pending = false;
+  }
+  async run() {
+    const engine = this.getEngine();
+    if (!engine) {
+      return;
+    }
+    const headers = await this.authBinding.auth();
+    if (!headers.token) {
+      await engine.stop();
+      return;
+    }
+    if (this.authBinding.resolveScopeMap) {
+      const nextScope = await this.authBinding.resolveScopeMap();
+      engine.updateScope(nextScope);
+    }
+    const status = engine.getStatus().status;
+    if (status !== "offline") {
+      await engine.stop();
+    }
+    await engine.start();
+  }
+};
+
+// src/sync-status-bridge.ts
+import { createSyncStatusController } from "@korajs/sync";
+function createSyncStatusBridge(emitter, getSyncEngine) {
+  const controller = createSyncStatusController({
+    getSyncEngine,
+    subscribeSyncStatus: null,
+    events: emitter
+  });
+  return {
+    get status() {
+      return controller.getSnapshot();
+    },
+    subscribe(listener) {
+      return controller.subscribe(() => {
+        listener(controller.getSnapshot());
+      });
+    },
+    refresh: () => controller.refresh(),
+    destroy: () => controller.destroy()
+  };
+}
+
+// src/sync-lifecycle.ts
+import {
+  ConnectionMonitor,
+  ReconnectionManager
+} from "@korajs/sync";
+function wireSyncLifecycleAfterReady(config, emitter, state, init) {
+  state.syncEngine = init.syncEngine;
+  if (!config.sync) {
+    return;
+  }
+  state.syncStatusBridge = createSyncStatusBridge(emitter, () => state.syncEngine);
+  state.syncStatusBridge.refresh();
+  if (state.syncEngine && init.authBinding?.subscribe) {
+    state.authSyncCoordinator = new AuthSyncCoordinator(() => state.syncEngine, init.authBinding);
+    init.authBinding.subscribe(() => {
+      state.authSyncCoordinator?.scheduleReconnect();
+    });
+  }
+  if (!state.syncEngine) {
+    return;
+  }
+  const syncEngine = state.syncEngine;
+  state.connectionMonitor = new ConnectionMonitor();
+  state.reconnectionManager = new ReconnectionManager({
+    initialDelay: config.sync.reconnectInterval,
+    maxDelay: config.sync.maxReconnectInterval
+  });
+  emitter.on("sync:sent", () => state.connectionMonitor?.recordActivity());
+  emitter.on("sync:received", () => state.connectionMonitor?.recordActivity());
+  emitter.on("sync:acknowledged", () => state.connectionMonitor?.recordActivity());
+  emitter.on("sync:connected", () => {
+    if (state.qualityInterval !== null) {
+      clearInterval(state.qualityInterval);
+    }
+    state.qualityInterval = setInterval(() => {
+      if (state.connectionMonitor) {
+        emitter.emit({
+          type: "connection:quality",
+          quality: state.connectionMonitor.getQuality()
+        });
+      }
+    }, 5e3);
+  });
+  emitter.on("sync:disconnected", () => {
+    state.connectionMonitor?.reset();
+    if (state.qualityInterval !== null) {
+      clearInterval(state.qualityInterval);
+      state.qualityInterval = null;
+    }
+  });
+  const browserGlobal = globalThis;
+  if (typeof browserGlobal.addEventListener === "function") {
+    const onOnline = () => {
+      if (state.intentionalDisconnect || config.sync?.autoReconnect === false) {
+        return;
+      }
+      state.reconnectionManager?.wake();
+      state.reconnectionManager?.reset();
+      void syncEngine.retryNow();
+    };
+    browserGlobal.addEventListener("online", onOnline);
+    state.removeOnlineListener = () => {
+      browserGlobal.removeEventListener?.("online", onOnline);
+    };
+  }
+  emitter.on("sync:schema-mismatch", () => {
+    state.reconnectionManager?.stop();
+    state.intentionalDisconnect = true;
+  });
+  if (config.sync.autoReconnect !== false) {
+    emitter.on("sync:disconnected", () => {
+      if (state.intentionalDisconnect || syncEngine.isSchemaBlocked()) {
+        return;
+      }
+      if (state.reconnectionManager?.isRunning()) {
+        return;
+      }
+      syncEngine.setReconnecting(true);
+      state.reconnectionManager?.stop();
+      state.reconnectionManager?.start(async () => {
+        try {
+          await syncEngine.start();
+          syncEngine.setReconnecting(false);
+          return true;
+        } catch {
+          return false;
+        }
+      }).then(() => {
+        syncEngine.setReconnecting(false);
+      });
+    });
+  }
+  if (config.sync.autoConnect === true) {
+    void syncEngine.start().catch(() => {
+    });
+  }
+}
+function teardownSyncLifecycle(state) {
+  if (state.qualityInterval !== null) {
+    clearInterval(state.qualityInterval);
+    state.qualityInterval = null;
+  }
+  state.reconnectionManager?.stop();
+  state.syncStatusBridge?.destroy();
+  state.syncStatusBridge = null;
+  state.authSyncCoordinator?.destroy();
+  state.authSyncCoordinator = null;
+  state.removeOnlineListener?.();
+  state.removeOnlineListener = null;
+}
+
+// src/transaction-executor.ts
+function createTransactionExecutor(config, ready, getStore) {
+  return async (fn, mutationName) => {
+    await ready;
+    const store = getStore();
+    if (!store) {
       throw new Error("Store not initialized. Await app.ready before using transactions.");
     }
     const collectionNames = Object.keys(config.schema.collections);
@@ -519,29 +605,130 @@ function createApp(config) {
       }
       await fn(proxy);
     });
+  };
+}
+
+// src/validate-config.ts
+import { KoraError, SchemaValidationError } from "@korajs/core";
+function validateCreateAppConfig(config) {
+  if (!config.schema) {
+    throw new SchemaValidationError("createApp requires a schema.", {
+      fix: "Pass schema: defineSchema({ version: 1, collections: { ... } })"
+    });
   }
-  const sequences = {
-    async next(name, config2) {
-      await ready;
-      if (!store) throw new Error("Store not initialized. Await app.ready before using sequences.");
-      return store.getSequenceManager().next(name, config2);
-    },
-    async current(name, config2) {
-      await ready;
-      if (!store) throw new Error("Store not initialized. Await app.ready before using sequences.");
-      return store.getSequenceManager().current(name, config2);
-    },
-    async reset(name, config2) {
-      await ready;
-      if (!store) throw new Error("Store not initialized. Await app.ready before using sequences.");
-      return store.getSequenceManager().reset(name, config2);
+  if (config.schema.version < 1) {
+    throw new SchemaValidationError("Schema version must be at least 1.", {
+      version: config.schema.version
+    });
+  }
+  const collectionNames = Object.keys(config.schema.collections);
+  if (collectionNames.length === 0) {
+    throw new SchemaValidationError("Schema must define at least one collection.", {
+      fix: "Add entries under collections in defineSchema()."
+    });
+  }
+  if (config.sync) {
+    validateSyncUrl(config.sync.url, config.sync.transport ?? "websocket");
+  }
+  const adapter = config.store?.adapter ?? detectAdapterType();
+  const isBrowser = typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined";
+  if (isBrowser && (adapter === "sqlite-wasm" || adapter === "indexeddb") && !config.store?.workerUrl) {
+    throw new KoraError(
+      "Browser storage requires store.workerUrl pointing to the SQLite WASM worker script.",
+      "MISSING_WORKER_URL",
+      {
+        adapter,
+        fix: 'Add store: { workerUrl: "/sqlite-wasm-worker.js" } (see create-kora-app templates).'
+      }
+    );
+  }
+}
+function validateSyncUrl(url, transport) {
+  if (!url || url.trim().length === 0) {
+    throw new KoraError("sync.url is required when sync is configured.", "INVALID_SYNC_URL", {
+      fix: 'Pass sync: { url: "wss://your-server/kora" }.'
+    });
+  }
+  try {
+    const parsed = new URL(url);
+    if (transport === "http") {
+      if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error("bad protocol");
+      }
+    } else if (parsed.protocol !== "ws:" && parsed.protocol !== "wss:") {
+      throw new Error("bad protocol");
     }
+  } catch {
+    throw new KoraError(
+      `Invalid sync URL "${url}" for transport "${transport}".`,
+      "INVALID_SYNC_URL",
+      {
+        url,
+        transport,
+        fix: transport === "http" ? "Use an absolute http:// or https:// URL." : "Use an absolute ws:// or wss:// URL."
+      }
+    );
+  }
+}
+
+// src/wire-sync-event-forwarding.ts
+var SYNC_EVENT_TYPES = [
+  "sync:connected",
+  "sync:disconnected",
+  "sync:schema-mismatch",
+  "sync:auth-failed",
+  "sync:sent",
+  "sync:received",
+  "sync:acknowledged",
+  "sync:apply-failed",
+  "sync:diagnostics",
+  "sync:bandwidth",
+  "sync:initial-sync-progress"
+];
+function wireSyncEventForwarding(emitter, handler) {
+  for (const type of SYNC_EVENT_TYPES) {
+    emitter.on(type, (event) => {
+      handler(event);
+    });
+  }
+}
+
+// src/create-app.ts
+function createApp(config) {
+  validateCreateAppConfig(config);
+  const emitter = new SimpleEventEmitter();
+  const mergeEngine = new MergeEngine();
+  if (config.onSyncEvent) {
+    wireSyncEventForwarding(emitter, config.onSyncEvent);
+  }
+  let store = null;
+  let unsubscribeSync = null;
+  let unsubscribeAudit = null;
+  const syncState = {
+    syncEngine: null,
+    syncStatusBridge: null,
+    authSyncCoordinator: null,
+    reconnectionManager: null,
+    connectionMonitor: null,
+    qualityInterval: null,
+    intentionalDisconnect: false,
+    removeOnlineListener: null
   };
+  const devtools = setupDevtools(config, emitter);
+  const queryStoreCache = new QueryStoreCache(config.store?.name ?? "kora-db");
+  const ready = initializeApp(config, emitter, mergeEngine).then((init) => {
+    store = init.store;
+    unsubscribeSync = init.unsubscribeSync;
+    unsubscribeAudit = init.unsubscribeAudit;
+    wireSyncLifecycleAfterReady(config, emitter, syncState, init);
+  });
+  const getStore = () => store;
+  const executeTransaction = createTransactionExecutor(config, ready, getStore);
   const app = {
     ready,
     events: emitter,
-    sync: syncControl,
-    sequences,
+    sync: createSyncControl({ config, ready, state: syncState }),
+    sequences: createSequencesAccessor(ready, getStore),
     getStore() {
       if (!store) {
         throw new Error("Store not initialized. Await app.ready before accessing the store.");
@@ -549,30 +736,23 @@ function createApp(config) {
       return store;
     },
     getSyncEngine() {
-      return syncEngine;
+      return syncState.syncEngine;
+    },
+    getQueryStoreCache() {
+      return queryStoreCache;
     },
-    async transaction(fn) {
+    transaction(fn) {
       return executeTransaction(fn);
     },
-    async mutation(name, fn) {
+    mutation(name, fn) {
       return executeTransaction(fn, name);
     },
     async close() {
       await ready;
-      intentionalDisconnect = true;
-      if (qualityInterval !== null) {
-        clearInterval(qualityInterval);
-        qualityInterval = null;
-      }
-      reconnectionManager?.stop();
-      if (destroyDevtoolsOverlay) {
-        destroyDevtoolsOverlay();
-        destroyDevtoolsOverlay = null;
-      }
-      if (instrumenter) {
-        instrumenter.destroy();
-        instrumenter = null;
-      }
+      syncState.intentionalDisconnect = true;
+      teardownSyncLifecycle(syncState);
+      devtools.destroyOverlay?.();
+      devtools.instrumenter?.destroy();
       if (unsubscribeSync) {
         unsubscribeSync();
         unsubscribeSync = null;
@@ -581,14 +761,11 @@ function createApp(config) {
         unsubscribeAudit();
         unsubscribeAudit = null;
       }
-      if (syncEngine) {
-        await syncEngine.stop();
-        syncEngine = null;
-      }
-      if (syncStatusBridge) {
-        syncStatusBridge.destroy();
-        syncStatusBridge = null;
+      if (syncState.syncEngine) {
+        await syncState.syncEngine.stop();
+        syncState.syncEngine = null;
       }
+      queryStoreCache.clear();
       if (store) {
         await store.close();
         store = null;
@@ -627,7 +804,7 @@ function createApp(config) {
   for (const collectionName of Object.keys(config.schema.collections)) {
     Object.defineProperty(app, collectionName, {
       get() {
-        return createCollectionAccessor(collectionName, () => store);
+        return createCollectionAccessor(collectionName, getStore);
       },
       enumerable: true,
       configurable: false
@@ -635,174 +812,6 @@ function createApp(config) {
   }
   return app;
 }
-async function initializeAsync(config, emitter, mergeEngine) {
-  const adapterType = config.store?.adapter ?? detectAdapterType();
-  const dbName = config.store?.name ?? "kora-db";
-  const adapter = await createAdapter(
-    adapterType,
-    dbName,
-    config.store?.workerUrl,
-    emitter,
-    config.store?.workerResponseTimeoutMs,
-    config.store?.sharedWorkerUrl
-  );
-  const authBinding = config.sync?.authClient;
-  const authNodeId = authBinding?.resolveNodeId ? await authBinding.resolveNodeId() : void 0;
-  let syncEngine = null;
-  const store = new Store({
-    schema: config.schema,
-    adapter,
-    emitter,
-    dbName,
-    nodeId: authNodeId,
-    isolation: authNodeId ? "shared" : config.store?.isolation,
-    ...config.sync ? { onQuerySubscribed: createSyncQuerySubscriptionHook(() => syncEngine) } : {}
-  });
-  await store.open();
-  let recordConflict;
-  const applyPipeline = new ApplyPipeline({
-    store,
-    mergeEngine,
-    emitter,
-    onMergeConflict: () => recordConflict?.()
-  });
-  store.setLocalMutationHandler(applyPipeline);
-  const unsubscribeAudit = wireAuditPersistence(store, emitter);
-  let unsubscribeSync = null;
-  if (config.sync) {
-    const transport = createSyncTransport(config.sync);
-    const mergeAwareStore = new MergeAwareSyncStore(store, mergeEngine, emitter, {
-      onMergeConflict: () => recordConflict?.()
-    });
-    let scopeMap = config.sync.scope ? buildScopeMap(config.schema, config.sync.scope) : void 0;
-    if (authBinding?.resolveScopeMap) {
-      scopeMap = await authBinding.resolveScopeMap() ?? scopeMap;
-    }
-    const syncAuth = authBinding?.auth ?? config.sync.auth;
-    const encryptor = config.sync.encryption?.enabled === true ? await SyncEncryptor.create(config.sync.encryption) : void 0;
-    syncEngine = new SyncEngine({
-      transport,
-      store: mergeAwareStore,
-      config: {
-        url: config.sync.url,
-        transport: config.sync.transport,
-        auth: syncAuth,
-        batchSize: config.sync.batchSize,
-        schemaVersion: config.sync.schemaVersion ?? config.schema.version,
-        scopeMap,
-        encryption: config.sync.encryption,
-        strictHandshake: config.sync.strictHandshake,
-        operationTransforms: config.sync.operationTransforms
-      },
-      emitter,
-      queueStorage: new StoreQueueStorage(adapter),
-      syncState: new StoreSyncStatePersistence(store, scopeMap),
-      encryptor
-    });
-    recordConflict = () => syncEngine?.recordConflict();
-    unsubscribeSync = emitter.on("operation:created", (event) => {
-      if (syncEngine) {
-        syncEngine.pushOperation(event.operation);
-      }
-    });
-  }
-  return {
-    store,
-    syncEngine,
-    unsubscribeSync,
-    unsubscribeAudit,
-    authBinding: config.sync?.authClient ?? null
-  };
-}
-function createSyncTransport(sync) {
-  if (sync.transport === "http") {
-    return new HttpLongPollingTransport();
-  }
-  return new WebSocketTransport();
-}
-function createCollectionAccessor(collectionName, getStore) {
-  return {
-    async insert(data) {
-      const currentStore = getStore();
-      if (!currentStore) {
-        throw new Error(`Cannot mutate collection "${collectionName}" before app.ready resolves.`);
-      }
-      return currentStore.collection(collectionName).insert(data);
-    },
-    async findById(id) {
-      const currentStore = getStore();
-      if (!currentStore) return null;
-      return currentStore.collection(collectionName).findById(id);
-    },
-    async update(id, data) {
-      const currentStore = getStore();
-      if (!currentStore) {
-        throw new Error(`Cannot mutate collection "${collectionName}" before app.ready resolves.`);
-      }
-      return currentStore.collection(collectionName).update(id, data);
-    },
-    async delete(id) {
-      const currentStore = getStore();
-      if (!currentStore) {
-        throw new Error(`Cannot mutate collection "${collectionName}" before app.ready resolves.`);
-      }
-      return currentStore.collection(collectionName).delete(id);
-    },
-    where(conditions) {
-      const currentStore = getStore();
-      if (!currentStore) {
-        return createPendingQueryBuilder(conditions);
-      }
-      return currentStore.collection(collectionName).where(conditions);
-    }
-  };
-}
-function createPendingQueryBuilder(initialWhere) {
-  const descriptor = {
-    collection: "__pending__",
-    where: { ...initialWhere },
-    orderBy: [],
-    limit: void 0,
-    offset: void 0
-  };
-  const builder = {
-    where(conditions) {
-      descriptor.where = { ...descriptor.where, ...conditions };
-      return this;
-    },
-    orderBy(field, direction = "asc") {
-      descriptor.orderBy.push({ field, direction });
-      return this;
-    },
-    limit(n) {
-      descriptor.limit = n;
-      return this;
-    },
-    offset(n) {
-      descriptor.offset = n;
-      return this;
-    },
-    async exec() {
-      throw new AppNotReadyError(
-        "Cannot execute a query before app.ready. Await app.ready or use <KoraProvider app={app}>."
-      );
-    },
-    async count() {
-      throw new AppNotReadyError(
-        "Cannot count query results before app.ready. Await app.ready or use <KoraProvider app={app}>."
-      );
-    },
-    subscribe(_callback) {
-      throw new AppNotReadyError(
-        "Cannot subscribe to a query before app.ready. Await app.ready or use <KoraProvider app={app}>."
-      );
-    },
-    getDescriptor() {
-      return { ...descriptor, where: { ...descriptor.where }, orderBy: [...descriptor.orderBy] };
-    }
-  };
-  return builder;
-}
 
 // src/index.ts
 import {
@@ -814,7 +823,7 @@ import { defineSchema, migrate, t } from "@korajs/core";
 import { HybridLogicalClock } from "@korajs/core";
 import { generateUUIDv7 } from "@korajs/core";
 import { createOperation } from "@korajs/core";
-import { KoraError as KoraError3 } from "@korajs/core";
+import { KoraError as KoraError2, AppNotReadyError as AppNotReadyError2 } from "@korajs/core";
 import { op } from "@korajs/core";
 import { SequenceManager, Store as Store2 } from "@korajs/store";
 import { TransactionContext } from "@korajs/store";
@@ -827,8 +836,9 @@ import {
 import { MergeEngine as MergeEngine2 } from "@korajs/merge";
 import { SyncEngine as SyncEngine2, WebSocketTransport as WebSocketTransport2 } from "@korajs/sync";
 export {
+  AppNotReadyError2 as AppNotReadyError,
   HybridLogicalClock,
-  KoraError3 as KoraError,
+  KoraError2 as KoraError,
   MergeEngine2 as MergeEngine,
   SequenceManager,
   Store2 as Store,