zerodrift 1.0.3 → 1.1.0

package/README.md

@@ -157,15 +157,17 @@ Both authoring paths compile to the same registry, so schema entities and decora
 
 ## React quick start
 
-Wrap your app in `<SyncProvider>` once. Import your model file as a side effect so decorators run before bootstrap.
+Wrap your app in `<SyncProvider>` once. For the decorator path, import your model file as a side effect so decorators run before bootstrap; for the schema-first path, pass `schema={schema}` and the provider registers entities before fetching.
 
 ```tsx
 import { SyncProvider } from "zerodrift/react";
-import "./models";
+import { schema } from "./schema";   // schema-first
+// import "./models";                  // or: decorator path — side-effect import
 
 export default function Providers({ children }) {
   return (
     <SyncProvider
+      schema={schema}
       config={{
         workspaceId: "workspace-123",
         transport: {
@@ -194,6 +196,16 @@ export default function Providers({ children }) {
 }
 ```
 
+In schema-first children, pull the typed store with `useStore<typeof schema>()` (add `typeof extensions` as the second generic if you also passed extensions):
+
+```tsx
+import { useStore } from "zerodrift/react";
+import { schema } from "./schema";
+
+const store = useStore<typeof schema>();
+const { data: issue } = useRecord(store.issue, issueId);
+```
+
 Common reads and writes. The read hooks take a **handle** — a model class
 (decorator path) or a `store.<entity>` namespace (schema path) — and infer
 the record type from it. Every result has the same shape:
@@ -227,7 +239,7 @@ const { data: teams } = useRecords(store.team);
 const { data: teamIssues } = useRecordsByIndex(store.issue, "teamId", teamId);
 ```
 
-See [agent-docs/08-react-integration.md](agent-docs/08-react-integration.md) for hook return shapes, context-driven id generation, Storybook seeding, and testing patterns.
+See [agent-docs/08-react-integration.md](agent-docs/08-react-integration.md) for hook return shapes, context-driven id generation, Storybook seeding, and testing patterns. For the full `transport` field list (`bootstrapSyncGroups`, `modelStreams`, `sseClientFactory`, `syncTransform`, …) see [TransportConfig reference](agent-docs/07-realtime-sync.md#transportconfig-reference).
 
 ## Headless usage
 

package/dist/core/BaseModel.d.ts

@@ -13,8 +13,8 @@
  *   - BackRef for @BackReference properties
  * These are stored on __collections and __backRefs, read by the decorator getters.
  */
-import { type PropertyChange, type IObjectPool, type IStoreManager } from "./types";
-import { LazyCollectionBase, BackRef } from "./LazyCollection";
+import { type PropertyChange, type IObjectPool, type IStoreManager } from "./types.js";
+import { LazyCollectionBase, BackRef } from "./LazyCollection.js";
 import { type IObservableValue } from "mobx";
 export declare class BaseModel {
     id: string;

package/dist/core/BaseModel.js

@@ -13,10 +13,10 @@
  *   - BackRef for @BackReference properties
  * These are stored on __collections and __backRefs, read by the decorator getters.
  */
-import { ModelRegistry } from "./ModelRegistry";
-import { PropertyType, DEFAULT_TRANSIENT_INDEX_DEPTH, } from "./types";
-import { RefCollection, BackRef } from "./LazyCollection";
-import { OwnedRefs } from "./LazyOwnedCollection";
+import { ModelRegistry } from "./ModelRegistry.js";
+import { PropertyType, DEFAULT_TRANSIENT_INDEX_DEPTH, } from "./types.js";
+import { RefCollection, BackRef } from "./LazyCollection.js";
+import { OwnedRefs } from "./LazyOwnedCollection.js";
 import { action, computed, observable, reaction, runInAction, } from "mobx";
 // The four PropertyTypes that have MobX boxes and direct setters — the "flat scalar" fields.
 // Used by makeModelObservable (to create boxes) and assign() (to filter writable keys).

package/dist/core/BaseSSEConnection.d.ts

@@ -1,4 +1,4 @@
-import { type EngineErrorContext } from "./types";
+import { type EngineErrorContext } from "./types.js";
 export interface SSEClient {
     onmessage: ((event: {
         data: string;
@@ -8,19 +8,25 @@ export interface SSEClient {
 }
 export type SSEClientFactory = (url: string) => SSEClient;
 export type SSEErrorReporter = (err: Error, context: EngineErrorContext) => void;
+/** Either a fixed URL or a thunk re-evaluated on every (re)connect. */
+export type SSEEndpoint = string | (() => string);
 export declare const createBrowserSSEFactory: (init?: EventSourceInit) => SSEClientFactory;
 export declare abstract class BaseSSEConnection {
-    protected url: string;
+    protected url: SSEEndpoint;
     private sseClientFactory;
     private reportError?;
     private eventSource;
     private reconnectTimer;
     private stopped;
-    constructor(url: string, sseClientFactory?: SSEClientFactory, reportError?: SSEErrorReporter | undefined);
+    constructor(url: SSEEndpoint, sseClientFactory?: SSEClientFactory, reportError?: SSEErrorReporter | undefined);
     connect(): void;
     disconnect(): void;
     reconnect(): void;
     get isConnected(): boolean;
+    /** Resolve the endpoint to a concrete string. Subclasses building dynamic
+     * URLs (e.g. appending query params) must read through this instead of
+     * `this.url` directly so a thunk endpoint is re-evaluated on every connect. */
+    protected resolveUrl(): string;
     protected buildUrl(): string;
     protected abstract onMessage(data: string): void;
     protected onReconnect(): void;

package/dist/core/BaseSSEConnection.js

@@ -1,4 +1,4 @@
-import { toError } from "./types";
+import { toError } from "./types.js";
 export const createBrowserSSEFactory = (init) => (url) => new EventSource(url, init);
 export class BaseSSEConnection {
     constructor(url, sseClientFactory = createBrowserSSEFactory(), reportError) {
@@ -36,8 +36,14 @@ export class BaseSSEConnection {
     get isConnected() {
         return this.eventSource != null;
     }
+    /** Resolve the endpoint to a concrete string. Subclasses building dynamic
+     * URLs (e.g. appending query params) must read through this instead of
+     * `this.url` directly so a thunk endpoint is re-evaluated on every connect. */
+    resolveUrl() {
+        return typeof this.url === "function" ? this.url() : this.url;
+    }
     buildUrl() {
-        return this.url;
+        return this.resolveUrl();
     }
     onReconnect() { }
     onOpen() { }
@@ -51,7 +57,21 @@ export class BaseSSEConnection {
             this.eventSource = null;
             this.onClose();
         }
-        const url = this.buildUrl();
+        // buildUrl() can throw when the endpoint is a thunk (e.g. cursor read
+        // crashes). Catch + schedule a reconnect so a transient failure doesn't
+        // permanently kill the stream.
+        let url;
+        try {
+            url = this.buildUrl();
+        }
+        catch (err) {
+            this.reportError?.(toError(err), {
+                kind: "sseConstruction",
+                url: "<endpoint-thunk-threw>",
+            });
+            this.scheduleReconnect();
+            return;
+        }
         try {
             this.eventSource = this.sseClientFactory(url);
             this.eventSource.onmessage = (e) => {

package/dist/core/CompoundIndexFetcher.d.ts

@@ -14,8 +14,8 @@
  * Adopters without server JOIN support leave the flag unset; the engine
  * fans out per-parent (existing behavior).
  */
-import type { IndexBatchFetcher, IndexQuery } from "./BatchModelLoader";
-import { type ObjectPool } from "./ObjectPool";
+import type { IndexBatchFetcher, IndexQuery } from "./BatchModelLoader.js";
+import { type ObjectPool } from "./ObjectPool.js";
 /** Switch to a compound fetch only when at least this many pending
  * requests share a single parent FK value. Below this, the per-parent
  * fan-out wins because the compound response would over-fetch. */

package/dist/core/CompoundIndexFetcher.js

@@ -14,9 +14,9 @@
  * Adopters without server JOIN support leave the flag unset; the engine
  * fans out per-parent (existing behavior).
  */
-import { ModelRegistry } from "./ModelRegistry";
-import { readFk } from "./ObjectPool";
-import { PropertyType } from "./types";
+import { ModelRegistry } from "./ModelRegistry.js";
+import { readFk } from "./ObjectPool.js";
+import { PropertyType } from "./types.js";
 /** Switch to a compound fetch only when at least this many pending
  * requests share a single parent FK value. Below this, the per-parent
  * fan-out wins because the compound response would over-fetch. */

package/dist/core/Database.d.ts

@@ -201,7 +201,8 @@ export interface StorageAdapter {
     close(): Promise<void>;
     /**
      * Close the connection AND permanently delete all persisted data.
-     * Use for explicit logout / factory-reset flows — NOT for routine teardown.
+     * Called by StoreManager.destroy() for explicit logout / factory-reset
+     * flows — NOT for routine teardown.
      */
     destroy(): Promise<void>;
     get isConnected(): boolean;

package/dist/core/Database.js

@@ -15,7 +15,7 @@
  *   - Partial: DB exists with valid data, just need delta since lastSyncId
  *   - Local: DB exists, no server contact needed (offline start)
  */
-import { ModelRegistry } from "./ModelRegistry";
+import { ModelRegistry } from "./ModelRegistry.js";
 export var BootstrapType;
 (function (BootstrapType) {
     BootstrapType["Full"] = "full";

package/dist/core/LazyCollection.d.ts

@@ -28,8 +28,8 @@
  *   // or via hook:
  *   const { data, isLoading } = useRelation(team?.issues);
  */
-import type { BaseModel } from "./BaseModel";
-import type { CoveringPath } from "./types";
+import type { BaseModel } from "./BaseModel.js";
+import type { CoveringPath } from "./types.js";
 export declare enum CollectionState {
     /** Never accessed — hydrate() computed the index values but no load yet. */
     Idle = "idle",

package/dist/core/LazyCollection.js

@@ -29,7 +29,7 @@
  *   const { data, isLoading } = useRelation(team?.issues);
  */
 import { observable, runInAction, makeObservable } from "mobx";
-import { readFk } from "./ObjectPool";
+import { readFk } from "./ObjectPool.js";
 /** Walk a `CoveringPath` from `parent` through the pool, returning the
  * leaf FK value or null if any link is missing. Depth-1 paths are a single
  * `readFk(parent, hops[0].fk)`. Deeper paths use intermediate

package/dist/core/LazyOwnedCollection.d.ts

@@ -15,8 +15,8 @@
  *   @OwnedCollection("Issue", { idsField: "issueIds" })
  *   public issues: OwnedRefs<Issue>;
  */
-import type { BaseModel } from "./BaseModel";
-import { LazyCollectionBase } from "./LazyCollection";
+import type { BaseModel } from "./BaseModel.js";
+import { LazyCollectionBase } from "./LazyCollection.js";
 export declare class OwnedRefs<T extends BaseModel = BaseModel> extends LazyCollectionBase<T> {
     /** Live getter — reads the current IDs array from the parent model each call. */
     private idsGetter;

package/dist/core/LazyOwnedCollection.js

@@ -16,7 +16,7 @@
  *   public issues: OwnedRefs<Issue>;
  */
 import { runInAction } from "mobx";
-import { LazyCollectionBase, CollectionState } from "./LazyCollection";
+import { LazyCollectionBase, CollectionState } from "./LazyCollection.js";
 export class OwnedRefs extends LazyCollectionBase {
     constructor(referencedModelName, idsGetter) {
         super(referencedModelName);

package/dist/core/MemoryAdapter.d.ts

@@ -8,7 +8,7 @@
  * storage in a server environment, implement StorageAdapter with your own
  * SQLite / Redis / file-system backend.
  */
-import { BootstrapType, type DatabaseMeta, type PartialIndexEntry, type StorageAdapter, type SyncActionHeader } from "./Database";
+import { BootstrapType, type DatabaseMeta, type PartialIndexEntry, type StorageAdapter, type SyncActionHeader } from "./Database.js";
 export declare class MemoryAdapter implements StorageAdapter {
     private meta;
     private models;

package/dist/core/MemoryAdapter.js

@@ -8,7 +8,7 @@
  * storage in a server environment, implement StorageAdapter with your own
  * SQLite / Redis / file-system backend.
  */
-import { BootstrapType, LoadedModelsTracker, diffModelVersions, currentModelVersions, } from "./Database";
+import { BootstrapType, LoadedModelsTracker, diffModelVersions, currentModelVersions, } from "./Database.js";
 export class MemoryAdapter {
     constructor() {
         this.meta = null;

package/dist/core/ModelRegistry.d.ts

@@ -8,7 +8,7 @@
  * Also computes a schemaHash — a fingerprint of all models and their properties.
  * If the hash changes between sessions, the local IndexedDB needs a migration.
  */
-import { type ModelMeta, type PropertyMeta, type CoveringPath } from "./types";
+import { type ModelMeta, type PropertyMeta, type CoveringPath } from "./types.js";
 declare class ModelRegistryImpl {
     private models;
     private cachedHash;

package/dist/core/ModelRegistry.js

@@ -8,8 +8,8 @@
  * Also computes a schemaHash — a fingerprint of all models and their properties.
  * If the hash changes between sessions, the local IndexedDB needs a migration.
  */
-import { hashString } from "./hash";
-import { LoadStrategy, PropertyType, } from "./types";
+import { hashString } from "./hash.js";
+import { LoadStrategy, PropertyType, } from "./types.js";
 class ModelRegistryImpl {
     constructor() {
         this.models = new Map();

package/dist/core/ModelStream.d.ts

@@ -3,9 +3,9 @@
  * Writes to IDB and upserts into the ObjectPool — no sync state management.
  * Ephemeral models skip IDB and are only held in the pool.
  */
-import type { StorageAdapter } from "./Database";
-import { ObjectPool } from "./ObjectPool";
-import { BaseSSEConnection, type SSEClientFactory, type SSEErrorReporter } from "./BaseSSEConnection";
+import type { StorageAdapter } from "./Database.js";
+import { ObjectPool } from "./ObjectPool.js";
+import { BaseSSEConnection, type SSEClientFactory, type SSEEndpoint, type SSEErrorReporter } from "./BaseSSEConnection.js";
 export interface ModelUpdate {
     modelName: string;
     modelId: string;
@@ -23,7 +23,7 @@ export declare class ModelStream extends BaseSSEConnection {
     private transform?;
     private updateQueue;
     private processing;
-    constructor(url: string, database: StorageAdapter, pool: ObjectPool, onStatusChange?: ((connected: boolean) => void) | undefined, sseClientFactory?: SSEClientFactory, transform?: ModelStreamMessageTransform | undefined, reportError?: SSEErrorReporter);
+    constructor(url: SSEEndpoint, database: StorageAdapter, pool: ObjectPool, onStatusChange?: ((connected: boolean) => void) | undefined, sseClientFactory?: SSEClientFactory, transform?: ModelStreamMessageTransform | undefined, reportError?: SSEErrorReporter);
     disconnect(): void;
     protected onOpen(): void;
     protected onClose(): void;

package/dist/core/ModelStream.js

@@ -3,9 +3,9 @@
  * Writes to IDB and upserts into the ObjectPool — no sync state management.
  * Ephemeral models skip IDB and are only held in the pool.
  */
-import { ModelRegistry } from "./ModelRegistry";
-import { BaseSSEConnection, } from "./BaseSSEConnection";
-import { LoadStrategy } from "./types";
+import { ModelRegistry } from "./ModelRegistry.js";
+import { BaseSSEConnection, } from "./BaseSSEConnection.js";
+import { LoadStrategy } from "./types.js";
 export class ModelStream extends BaseSSEConnection {
     constructor(url, database, pool, onStatusChange, sseClientFactory, transform, reportError) {
         super(url, sseClientFactory, reportError);

package/dist/core/ObjectPool.d.ts

@@ -11,8 +11,8 @@
  *   adds, updates, or removes an instance of that type, all subscribers
  *   are notified and their components re-render.
  */
-import type { BaseModel } from "./BaseModel";
-import { type ModelMeta } from "./types";
+import type { BaseModel } from "./BaseModel.js";
+import { type ModelMeta } from "./types.js";
 type Listener = () => void;
 /**
  * Read a dynamic property off a model instance. The single bridge between

package/dist/core/ObjectPool.js

@@ -12,8 +12,8 @@
  *   are notified and their components re-render.
  */
 import { createAtom, runInAction } from "mobx";
-import { ModelRegistry } from "./ModelRegistry";
-import { PropertyType } from "./types";
+import { ModelRegistry } from "./ModelRegistry.js";
+import { PropertyType } from "./types.js";
 /**
  * Read a dynamic property off a model instance. The single bridge between
  * the typed `BaseModel` shape and the index-string access we need for

package/dist/core/Store.d.ts

@@ -6,10 +6,10 @@
  *   - PartialStore for partial models (on demand)
  *   - EphemeralStore for ephemeral models (pool-only, never persisted)
  */
-import type { BaseModel } from "./BaseModel";
-import type { StorageAdapter } from "./Database";
-import { ObjectPool } from "./ObjectPool";
-import { type ModelMeta } from "./types";
+import type { BaseModel } from "./BaseModel.js";
+import type { StorageAdapter } from "./Database.js";
+import { ObjectPool } from "./ObjectPool.js";
+import { type ModelMeta } from "./types.js";
 export declare abstract class ModelStore {
     protected meta: ModelMeta;
     protected database: StorageAdapter;

package/dist/core/Store.js

@@ -6,7 +6,7 @@
  *   - PartialStore for partial models (on demand)
  *   - EphemeralStore for ephemeral models (pool-only, never persisted)
  */
-import { LoadStrategy } from "./types";
+import { LoadStrategy } from "./types.js";
 export class ModelStore {
     constructor(meta, database, pool) {
         this.meta = meta;

package/dist/core/StoreManager.d.ts

@@ -18,14 +18,14 @@
  *   storeManager.getOrLoadCollection("Issue", "teamId", teamId)
  *   storeManager.getOrLoadById("DocumentContent", docId)
  */
-import { ObjectPool } from "./ObjectPool";
-import { BootstrapType, type StorageAdapter, type DatabaseMeta, type PartialIndexEntry } from "./Database";
-import { TransactionQueue, type TransactionSender, type UndoableActionHandlers } from "./TransactionQueue";
-import { type DeltaPacket, type SSEClientFactory, type SyncMessageTransform } from "./SyncConnection";
-import { type ModelStreamMessageTransform } from "./ModelStream";
-import { type IndexBatchFetcher } from "./BatchModelLoader";
-import { BaseModel } from "./BaseModel";
-import { BootstrapPhase, type ModelMeta, type PropertyMeta, type PropertyChange, type FieldTransform, type EngineErrorContext, type EngineErrorHandler, type CommitRouteHandler, type OnModelTouchedHandler } from "./types";
+import { ObjectPool } from "./ObjectPool.js";
+import { BootstrapType, type StorageAdapter, type DatabaseMeta, type PartialIndexEntry } from "./Database.js";
+import { TransactionQueue, type TransactionSender, type UndoableActionHandlers } from "./TransactionQueue.js";
+import { type DeltaPacket, type SSEClientFactory, type SSEEndpoint, type SyncMessageTransform } from "./SyncConnection.js";
+import { type ModelStreamMessageTransform } from "./ModelStream.js";
+import { type IndexBatchFetcher } from "./BatchModelLoader.js";
+import { BaseModel } from "./BaseModel.js";
+import { BootstrapPhase, type ModelMeta, type PropertyMeta, type PropertyChange, type FieldTransform, type EngineErrorContext, type EngineErrorHandler, type CommitRouteHandler, type OnModelTouchedHandler } from "./types.js";
 /**
  * Thrown when a delete/archive is blocked by an onDelete: "restrict" relationship.
  *
@@ -68,7 +68,7 @@ export interface BootstrapFetcherOptions extends FetcherContext {
 }
 export type BootstrapFetcher = (type: BootstrapType.Full | BootstrapType.Partial, options?: BootstrapFetcherOptions) => Promise<BootstrapResponse>;
 export interface ModelStreamConfig {
-    url: string;
+    url: SSEEndpoint;
     onStatusChange?: (connected: boolean) => void;
     /**
      * Use when the backend sends a different envelope than the engine's
@@ -107,7 +107,10 @@ export type OnDemandConfig = {
 export interface TransportConfig {
     bootstrapFetcher: BootstrapFetcher;
     transactionSender?: TransactionSender;
-    syncUrl?: string;
+    /** SSE endpoint for live deltas — a static string, or a thunk evaluated
+     * on every (re)connect (so callers can fold in cursors from localStorage,
+     * auth tokens in the path, etc., without rebuilding the engine). */
+    syncUrl?: SSEEndpoint;
     /**
      * Optional async hook that returns the user's sync-group memberships
      * before any bootstrap fetch runs. The returned groups are append-only
@@ -624,8 +627,8 @@ export declare class StoreManager<TContext = unknown> {
      * draft target's `assign()` doesn't re-trigger a user-facing "first edit".
      * BaseModel guards on `hasModelTouchedHandler` before calling. */
     fireModelTouched(model: BaseModel, modelName: string): void;
-    undo(): Promise<import("./TransactionQueue").UndoResult | null>;
-    redo(): Promise<import("./TransactionQueue").UndoResult | null>;
+    undo(): Promise<import("./TransactionQueue.js").UndoResult | null>;
+    redo(): Promise<import("./TransactionQueue.js").UndoResult | null>;
     /**
      * Run a remote side-effect that returns a `changeLogId`, and record it on
      * the undo stack so the next `undo()` invokes the consumer's
@@ -829,7 +832,15 @@ export declare class StoreManager<TContext = unknown> {
      * cleared here because the schema-mismatch path keeps coverage entries;
      * the `fullyLoadedModels` mirror stays consistent with that. */
     private resetPoolState;
+    /** Routine cleanup (e.g. React unmount): stop sync, clear the object pool,
+     * and `close()` the persistence layer — persisted data is preserved so the
+     * next load can do a fast partial/local bootstrap. Not a logout. */
     teardown(): Promise<void>;
+    /** Logout / account switch: stop sync, clear the object pool, and `destroy()`
+     * the persistence layer — permanently wiping its data, whether persistence is
+     * IndexedDB or in-memory. Unlike {@link teardown}, nothing survives. */
+    destroy(): Promise<void>;
+    private shutdown;
     /** Debounced reconnect for SSE when `loadedModels` mutates. A burst of
      * transitions in the same tick (or across awaited writes in the same
      * async chain) coalesces into a single reconnect. setTimeout — not

package/dist/core/StoreManager.js

@@ -18,18 +18,18 @@
  *   storeManager.getOrLoadCollection("Issue", "teamId", teamId)
  *   storeManager.getOrLoadById("DocumentContent", docId)
  */
-import { ModelRegistry } from "./ModelRegistry";
-import { DEFAULT_TRANSIENT_INDEX_DEPTH } from "./types";
-import { ObjectPool, prop, readFk } from "./ObjectPool";
-import { Database, BootstrapType, } from "./Database";
-import { FullStore, PartialStore, EphemeralStore, } from "./Store";
-import { TransactionQueue, } from "./TransactionQueue";
-import { SyncConnection, encodeCsvList, createBrowserSSEFactory, } from "./SyncConnection";
-import { ModelStream } from "./ModelStream";
-import { BatchModelLoader } from "./BatchModelLoader";
-import { COMPOUND_FETCH_THRESHOLD, wrapCompoundFetcher, } from "./CompoundIndexFetcher";
-import { BaseModel } from "./BaseModel";
-import { BootstrapPhase, LoadStrategy, PropertyType, toError, } from "./types";
+import { ModelRegistry } from "./ModelRegistry.js";
+import { DEFAULT_TRANSIENT_INDEX_DEPTH } from "./types.js";
+import { ObjectPool, prop, readFk } from "./ObjectPool.js";
+import { Database, BootstrapType, } from "./Database.js";
+import { FullStore, PartialStore, EphemeralStore, } from "./Store.js";
+import { TransactionQueue, } from "./TransactionQueue.js";
+import { SyncConnection, encodeCsvList, createBrowserSSEFactory, } from "./SyncConnection.js";
+import { ModelStream } from "./ModelStream.js";
+import { BatchModelLoader } from "./BatchModelLoader.js";
+import { COMPOUND_FETCH_THRESHOLD, wrapCompoundFetcher, } from "./CompoundIndexFetcher.js";
+import { BaseModel } from "./BaseModel.js";
+import { BootstrapPhase, LoadStrategy, PropertyType, toError, } from "./types.js";
 /**
  * Thrown when a delete/archive is blocked by an onDelete: "restrict" relationship.
  *
@@ -1980,7 +1980,19 @@ export class StoreManager {
         this.inflightFullLoads.clear();
         this.seededSyncGroups = [];
     }
+    /** Routine cleanup (e.g. React unmount): stop sync, clear the object pool,
+     * and `close()` the persistence layer — persisted data is preserved so the
+     * next load can do a fast partial/local bootstrap. Not a logout. */
     async teardown() {
+        await this.shutdown(false);
+    }
+    /** Logout / account switch: stop sync, clear the object pool, and `destroy()`
+     * the persistence layer — permanently wiping its data, whether persistence is
+     * IndexedDB or in-memory. Unlike {@link teardown}, nothing survives. */
+    async destroy() {
+        await this.shutdown(true);
+    }
+    async shutdown(destroyData) {
         this.stopped = true;
         BaseModel.storeManager = null;
         this.loadedModelsUnsub?.();
@@ -1998,7 +2010,7 @@ export class StoreManager {
         this.transactionQueue.destroy();
         this.indexBatchLoader?.dispose();
         this.indexBatchLoader = null;
-        await this.database.close();
+        await (destroyData ? this.database.destroy() : this.database.close());
         this.objectPool.clear();
         this.stores.clear();
         this.partialIndexCoverage.clear();

package/dist/core/SyncConnection.d.ts

@@ -21,11 +21,11 @@
  *   `BaseModel.hydrate` dispatches FK changes for in-pool models. SyncConnection
  *   only has to mutate the pool; parent collections track changes themselves.
  */
-import type { StorageAdapter } from "./Database";
-import { ObjectPool } from "./ObjectPool";
-import { TransactionQueue } from "./TransactionQueue";
-import { BaseSSEConnection, type SSEClientFactory, type SSEErrorReporter } from "./BaseSSEConnection";
-export { type SSEClient, type SSEClientFactory, type SSEErrorReporter, createBrowserSSEFactory, } from "./BaseSSEConnection";
+import type { StorageAdapter } from "./Database.js";
+import { ObjectPool } from "./ObjectPool.js";
+import { TransactionQueue } from "./TransactionQueue.js";
+import { BaseSSEConnection, type SSEClientFactory, type SSEEndpoint, type SSEErrorReporter } from "./BaseSSEConnection.js";
+export { type SSEClient, type SSEClientFactory, type SSEEndpoint, type SSEErrorReporter, createBrowserSSEFactory, } from "./BaseSSEConnection.js";
 /**
  * Encode each element then comma-join — the right shape for a list-of-
  * strings inside a URL query parameter or a stable cache key. Commas
@@ -92,7 +92,7 @@ export declare class SyncConnection extends BaseSSEConnection {
      * gate, which doesn't see `getOrLoadAll`'s sentinel coverage. */
     private isModelFullyLoaded?;
     private recordInflightDelete?;
-    constructor(url: string, database: StorageAdapter, pool: ObjectPool, queue: TransactionQueue, opts?: SyncConnectionOptions);
+    constructor(url: SSEEndpoint, database: StorageAdapter, pool: ObjectPool, queue: TransactionQueue, opts?: SyncConnectionOptions);
     protected buildUrl(): string;
     protected onMessage(data: string): void;
     protected onReconnect(): void;

package/dist/core/SyncConnection.js

@@ -21,11 +21,11 @@
  *   `BaseModel.hydrate` dispatches FK changes for in-pool models. SyncConnection
  *   only has to mutate the pool; parent collections track changes themselves.
  */
-import { ModelRegistry } from "./ModelRegistry";
-import { LoadStrategy, PropertyType } from "./types";
-import { BaseSSEConnection, } from "./BaseSSEConnection";
+import { ModelRegistry } from "./ModelRegistry.js";
+import { LoadStrategy, PropertyType } from "./types.js";
+import { BaseSSEConnection, } from "./BaseSSEConnection.js";
 // Re-export so existing imports from "@zerodrift/SyncConnection" keep working.
-export { createBrowserSSEFactory, } from "./BaseSSEConnection";
+export { createBrowserSSEFactory, } from "./BaseSSEConnection.js";
 /** How many syncIds back to retain in the SyncAction store before pruning.
  * Covers short offline gaps where a persisted pending tx asks "was my
  * target deleted while I was away?" on next reconnect. */
@@ -67,11 +67,8 @@ export class SyncConnection extends BaseSSEConnection {
         const meta = this.database.currentMeta;
         const lastSyncId = meta?.lastSyncId ?? 0;
         const syncGroups = encodeCsvList(meta?.subscribedSyncGroups ?? []);
-        // Tell the server which models we're subscribed to (catchup + live
-        // stream; absent → no filter). Union of always-subscribed (Eager +
-        // Ephemeral, see ModelRegistry) with adapter-tracked loadedModels.
-        // Sort for a stable URL — equivalent sets must produce identical URLs
-        // so the engine doesn't churn reconnects when iteration order shifts.
+        // Sort the union — equivalent sets must produce identical URLs so the
+        // engine doesn't churn reconnects when iteration order shifts.
         const subscribed = [
             ...new Set([
                 ...ModelRegistry.alwaysSubscribedModelNames(),
@@ -79,7 +76,11 @@ export class SyncConnection extends BaseSSEConnection {
             ]),
         ].sort();
         const onlyModels = subscribed.length > 0 ? `&onlyModels=${encodeCsvList(subscribed)}` : "";
-        return `${this.url}?lastSyncId=${lastSyncId}&syncGroups=${syncGroups}${onlyModels}`;
+        const base = this.resolveUrl();
+        // Thunk endpoints often already carry query params (tenant, cursor, …);
+        // pick `&` when the base is already in query-string mode.
+        const sep = base.includes("?") ? "&" : "?";
+        return `${base}${sep}lastSyncId=${lastSyncId}&syncGroups=${syncGroups}${onlyModels}`;
     }
     onMessage(data) {
         const raw = JSON.parse(data);

package/dist/core/Transaction.d.ts

@@ -7,8 +7,8 @@
  * Rebasing (UpdateTransaction): when a delta packet conflicts with our local
  * change, the server value becomes our new baseline and our value is re-applied.
  */
-import type { BaseModel } from "./BaseModel";
-import { TransactionState, type PropertyChange } from "./types";
+import type { BaseModel } from "./BaseModel.js";
+import { TransactionState, type PropertyChange } from "./types.js";
 export declare abstract class BaseTransaction {
     readonly id: `${string}-${string}-${string}-${string}-${string}`;
     readonly modelId: string;

package/dist/core/Transaction.js

@@ -7,7 +7,7 @@
  * Rebasing (UpdateTransaction): when a delta packet conflicts with our local
  * change, the server value becomes our new baseline and our value is re-applied.
  */
-import { TransactionState } from "./types";
+import { TransactionState } from "./types.js";
 export class BaseTransaction {
     constructor(modelId, modelName) {
         this.id = crypto.randomUUID();

package/dist/core/TransactionQueue.d.ts

@@ -12,12 +12,12 @@
  *
  * The undo stack stores "entries" — either a single tx or a batch of txs.
  */
-import type { StorageAdapter } from "./Database";
-import { ObjectPool } from "./ObjectPool";
-import { type EngineErrorContext } from "./types";
-import { BaseTransaction, UpdateTransaction, type UndoableAction } from "./Transaction";
-import { type PropertyChange } from "./types";
-import type { BaseModel } from "./BaseModel";
+import type { StorageAdapter } from "./Database.js";
+import { ObjectPool } from "./ObjectPool.js";
+import { type EngineErrorContext } from "./types.js";
+import { BaseTransaction, UpdateTransaction, type UndoableAction } from "./Transaction.js";
+import { type PropertyChange } from "./types.js";
+import type { BaseModel } from "./BaseModel.js";
 export interface BatchResponse {
     success: boolean;
     lastSyncId: number;