@convex-localfirst/core 0.1.0

package/dist/functionName.d.ts

@@ -0,0 +1,3 @@
+import type { FunctionName } from "./types.js";
+export type FunctionNameResolver = (reference: unknown) => FunctionName;
+export declare function defaultFunctionName(reference: unknown): FunctionName;

package/dist/functionName.js

@@ -0,0 +1,15 @@
+export function defaultFunctionName(reference) {
+    if (typeof reference === "string") {
+        return reference;
+    }
+    if (reference && typeof reference === "object") {
+        const record = reference;
+        const candidates = [record._name, record.name, record.functionName, record.path];
+        for (const candidate of candidates) {
+            if (typeof candidate === "string" && candidate.length > 0) {
+                return candidate;
+            }
+        }
+    }
+    throw new Error("Unable to resolve Convex function name. Inject the official getFunctionName resolver in the React adapter.");
+}

package/dist/id.d.ts

@@ -0,0 +1,5 @@
+import type { TableName } from "./types.js";
+export type IdFactory = (table: TableName) => string;
+export declare function createDefaultIdFactory(prefix?: string): IdFactory;
+export declare function createClientId(): string;
+export declare function createOpId(clientId: string): string;

package/dist/id.js

@@ -0,0 +1,22 @@
+export function createDefaultIdFactory(prefix = "lf") {
+    let counter = 0;
+    return (table) => {
+        counter += 1;
+        const random = Math.random().toString(36).slice(2, 10);
+        return `${prefix}_${table}_${Date.now().toString(36)}_${counter.toString(36)}_${random}`;
+    };
+}
+export function createClientId() {
+    const random = Math.random().toString(36).slice(2, 14);
+    return `client_${Date.now().toString(36)}_${random}`;
+}
+let opCounter = 0;
+export function createOpId(clientId) {
+    // Zero-padded monotonic counter so lexicographic opId order matches creation
+    // order — this is the deterministic tiebreak when two ops share a createdAt
+    // (Invariant I4). Time component keeps ids sortable across process restarts.
+    opCounter += 1;
+    const seq = opCounter.toString(36).padStart(8, "0");
+    const random = Math.random().toString(36).slice(2, 10);
+    return `op_${clientId}_${Date.now().toString(36)}_${seq}_${random}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { createLocalFirstEngine } from "./engine.js";
+export type { LocalFirstEngine, LocalFirstEngineOptions } from "./engine.js";
+export * from "./collection.js";
+export * from "./relations.js";
+export { createClientId, type IdFactory } from "./id.js";
+export { IndexedDbStore, type IndexedDbStoreOptions } from "./indexedDbStore.js";
+export * from "./manifest.js";
+export * from "./memoryStore.js";
+export type { LocalFirstMutationCall } from "./mutationCall.js";
+export type { FunctionNameResolver } from "./functionName.js";
+export * from "./status.js";
+export * from "./storage.js";
+export * from "./transport.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,27 @@
+// Public API surface (GOAL §6). Rebase/replay, the derived view, and other
+// implementation internals are intentionally NOT re-exported here — they live in
+// "./internal.js" ("@convex-localfirst/core/internal") for the React adapter only.
+// Keeping them out keeps the public type surface free of internal vocabulary (I13)
+// so internals can be rewritten without a semver break. publicApi.test.ts guards this.
+//
+// The engine is exposed as a HEADLESS factory only (createLocalFirstEngine) + its
+// instance TYPE — the class constructor stays internal, so the construction path is
+// one blessed function, but imperative/vanilla consumers (a service layer, a MobX
+// store, a worker) can build and drive an engine without React. This is what lets a
+// real app adopt the library without rewriting its components into hooks.
+export { createLocalFirstEngine } from "./engine.js";
+export * from "./collection.js";
+export * from "./relations.js";
+// id: only createClientId is a wiring helper (GOAL §6). createOpId/createDefaultIdFactory
+// are engine internals → "./internal.js".
+export { createClientId } from "./id.js";
+// indexedDbStore: IndexedDbStore is the wiring helper (GOAL §6). openLocalFirstDb +
+// the schema-version constant are internals → "./internal.js".
+export { IndexedDbStore } from "./indexedDbStore.js";
+export * from "./manifest.js";
+export * from "./memoryStore.js";
+// ordering (compareOperations) is an engine internal → "./internal.js".
+export * from "./status.js";
+export * from "./storage.js";
+export * from "./transport.js";
+export * from "./types.js";

package/dist/indexedDbStore.d.ts

@@ -0,0 +1,53 @@
+import type { LocalStore, StoreListener, StoreUnsubscribe } from "./storage.js";
+import type { Cursor, LocalId, LocalOperation, OperationStatus, RowValue, ScopeKey, ServerChange, TableName } from "./types.js";
+export type IndexedDbStoreOptions = {
+    readonly databaseName: string;
+    /** Per-user/per-tenant suffix; switching it isolates data (Invariant I9). */
+    readonly namespace: string;
+    /** Called when an upgrade is blocked by another open connection. */
+    readonly onBlocked?: () => void;
+};
+export declare const INDEXED_DB_SCHEMA_VERSION = 3;
+export declare function openLocalFirstDb(name: string, version: number, options?: {
+    onBlocked?: () => void;
+}): Promise<IDBDatabase>;
+/**
+ * IndexedDB-backed canonical store. Same model as MemoryLocalStore (the live
+ * view is derived via deriveView), persisted durably so pending operations and
+ * canonical rows survive reloads (Invariant I3).
+ */
+export declare class IndexedDbStore implements LocalStore {
+    readonly options: IndexedDbStoreOptions;
+    private readonly listeners;
+    private readonly dbName;
+    private dbPromise;
+    /** Serializes canonical-mutating writes within this tab so a logout clear can't
+     *  interleave with an in-flight apply and resurrect rows. Cross-tab safety comes from
+     *  each apply being one atomic readwrite tx, not this lock. ponytail: promise-chain;
+     *  errors swallowed so one failed write can't wedge the queue. */
+    private writeChain;
+    private epoch;
+    private sessionEnded;
+    constructor(options: IndexedDbStoreOptions);
+    private db;
+    /** Internal accessor for tests that need raw transactional access. */
+    _database(): Promise<IDBDatabase>;
+    getCanonicalRows(table: TableName): Promise<readonly RowValue[]>;
+    getRows(table: TableName): Promise<readonly RowValue[]>;
+    getRow(table: TableName, id: LocalId): Promise<RowValue | null>;
+    applyServerChange(change: ServerChange): Promise<void>;
+    applyServerChanges(changes: readonly ServerChange[]): Promise<void>;
+    private applyServerChangesAtomic;
+    enqueueOperation(operation: LocalOperation): Promise<void>;
+    getPendingOperations(): Promise<readonly LocalOperation[]>;
+    getAllOperations(): Promise<readonly LocalOperation[]>;
+    getOperation(opId: string): Promise<LocalOperation | null>;
+    updateOperationStatus(opId: string, status: OperationStatus, error?: string): Promise<void>;
+    dropOperation(opId: string): Promise<void>;
+    getCursor(scopeKey: ScopeKey): Promise<Cursor>;
+    setCursor(scopeKey: ScopeKey, cursor: string): Promise<void>;
+    clear(): Promise<void>;
+    private clearAtomic;
+    subscribe(listener: StoreListener): StoreUnsubscribe;
+    notify(): void;
+}

package/dist/indexedDbStore.js

@@ -0,0 +1,328 @@
+import { compareOperations } from "./ordering.js";
+import { deriveView, nextCanonicalRow } from "./view.js";
+export const INDEXED_DB_SCHEMA_VERSION = 3;
+const CANONICAL = "canonical";
+const OPERATIONS = "operations";
+const CURSORS = "cursors";
+const META = "meta";
+const BY_TABLE = "by_table";
+const EPOCH_KEY = "epoch";
+const OWED_STATUSES = new Set(["pending", "pushing"]);
+function request(req) {
+    return new Promise((resolve, reject) => {
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error);
+    });
+}
+function transactionDone(tx) {
+    return new Promise((resolve, reject) => {
+        tx.oncomplete = () => resolve();
+        tx.onerror = () => reject(tx.error);
+        tx.onabort = () => reject(tx.error ?? new Error("Transaction aborted"));
+    });
+}
+/** Schema migrations. Each block runs when upgrading past that version. */
+function upgrade(db, oldVersion, tx) {
+    if (oldVersion < 1) {
+        db.createObjectStore(CANONICAL, { keyPath: ["_table", "_id"] });
+        db.createObjectStore(OPERATIONS, { keyPath: "opId" });
+        db.createObjectStore(CURSORS, { keyPath: "scopeKey" });
+    }
+    if (oldVersion < 2) {
+        const canonical = tx.objectStore(CANONICAL);
+        if (!canonical.indexNames.contains(BY_TABLE)) {
+            canonical.createIndex(BY_TABLE, "_table", { unique: false });
+        }
+    }
+    if (oldVersion < 3) {
+        // Durable logout epoch (I9). NOT wiped by clear(); clear() bumps it so a
+        // concurrent apply in another tab sees the advance and aborts (no resurrection).
+        // Guarded like the by_table index: opening AT an intermediate version runs every
+        // `oldVersion < N` block, so a later open must not recreate an existing store.
+        if (!db.objectStoreNames.contains(META)) {
+            db.createObjectStore(META, { keyPath: "key" });
+        }
+    }
+}
+export function openLocalFirstDb(name, version, options = {}) {
+    return new Promise((resolve, reject) => {
+        const open = indexedDB.open(name, version);
+        open.onupgradeneeded = (event) => {
+            upgrade(open.result, event.oldVersion, open.transaction);
+        };
+        open.onblocked = () => options.onBlocked?.();
+        open.onsuccess = () => resolve(open.result);
+        open.onerror = () => reject(open.error);
+    });
+}
+/**
+ * IndexedDB-backed canonical store. Same model as MemoryLocalStore (the live
+ * view is derived via deriveView), persisted durably so pending operations and
+ * canonical rows survive reloads (Invariant I3).
+ */
+export class IndexedDbStore {
+    options;
+    listeners = new Set();
+    dbName;
+    dbPromise = null;
+    /** Serializes canonical-mutating writes within this tab so a logout clear can't
+     *  interleave with an in-flight apply and resurrect rows. Cross-tab safety comes from
+     *  each apply being one atomic readwrite tx, not this lock. ponytail: promise-chain;
+     *  errors swallowed so one failed write can't wedge the queue. */
+    writeChain = Promise.resolve();
+    // Logout epoch this instance opened under. clear() bumps the durable epoch; an apply
+    // whose captured epoch no longer matches means a clear happened → the session is over.
+    epoch = 0;
+    // Set once a clear/foreign-clear is seen: further applies become no-ops (else they'd
+    // resurrect cleared data). Per-instance, not a permanent lock — a new login opens a
+    // fresh store (the provider keys it on userId).
+    sessionEnded = false;
+    constructor(options) {
+        this.options = options;
+        this.dbName = `${options.databaseName}:${options.namespace}`;
+    }
+    db() {
+        if (!this.dbPromise) {
+            this.dbPromise = openLocalFirstDb(this.dbName, INDEXED_DB_SCHEMA_VERSION, {
+                onBlocked: this.options.onBlocked
+            }).then(async (db) => {
+                // If another tab needs to upgrade, get out of the way and reopen lazily.
+                db.onversionchange = () => {
+                    db.close();
+                    this.dbPromise = null;
+                };
+                // Seed the epoch this instance opened under, so a later clear() (here or in
+                // another tab) is detectable as an advance against this captured value.
+                try {
+                    const row = (await request(db.transaction(META, "readonly").objectStore(META).get(EPOCH_KEY)));
+                    this.epoch = row?.value ?? 0;
+                }
+                catch {
+                    this.epoch = 0;
+                }
+                return db;
+            });
+        }
+        return this.dbPromise;
+    }
+    /** Internal accessor for tests that need raw transactional access. */
+    async _database() {
+        return this.db();
+    }
+    async getCanonicalRows(table) {
+        const db = await this.db();
+        const tx = db.transaction(CANONICAL, "readonly");
+        const index = tx.objectStore(CANONICAL).index(BY_TABLE);
+        return (await request(index.getAll(table)));
+    }
+    async getRows(table) {
+        const db = await this.db();
+        const tx = db.transaction([CANONICAL, OPERATIONS], "readonly");
+        const canonical = (await request(tx.objectStore(CANONICAL).index(BY_TABLE).getAll(table)));
+        const operations = (await request(tx.objectStore(OPERATIONS).getAll()));
+        return deriveView(table, canonical, operations);
+    }
+    async getRow(table, id) {
+        const rows = await this.getRows(table);
+        return rows.find((row) => row._id === id) ?? null;
+    }
+    async applyServerChange(change) {
+        await this.applyServerChanges([change]);
+    }
+    async applyServerChanges(changes) {
+        if (changes.length === 0 || this.sessionEnded) {
+            return;
+        }
+        // Queue behind any in-flight canonical write IN THIS TAB (so clear() cannot
+        // interleave). Cross-tab safety is the atomic tx inside applyServerChangesAtomic.
+        const run = this.writeChain.then(() => this.applyServerChangesAtomic(changes));
+        this.writeChain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async applyServerChangesAtomic(changes) {
+        const db = await this.db();
+        // NUL separator: table names and localIds cannot contain it, so distinct
+        // (table, id) pairs never collide in the grouping map below.
+        const keyOf = (table, id) => `${table}\u0000${id}`;
+        // Group changes per row, preserving arrival order. A batch may carry several
+        // changes to the same row (e.g. insert then patch) that must fold in order.
+        const perRow = new Map();
+        const opIds = new Set();
+        for (const c of changes) {
+            const k = keyOf(c.table, c.id);
+            let entry = perRow.get(k);
+            if (!entry) {
+                entry = { table: c.table, id: c.id, changes: [] };
+                perRow.set(k, entry);
+            }
+            entry.changes.push(c);
+            if (c.opId)
+                opIds.add(c.opId);
+        }
+        // ONE readwrite tx: the per-row get -> version-compare -> put happens atomically
+        // via request callbacks. NEVER await between requests, which would let the tx
+        // auto-commit early. Because IndexedDB serializes overlapping readwrite
+        // transactions to the same store (INCLUDING across tabs/connections), a
+        // concurrent apply's get observes our committed put, so an older version cannot
+        // overwrite a newer one and the canonical row never regresses (I5). A delete
+        // folds to a `_deleted: true` tombstone row (deriveView hides it), so we only put.
+        // META is in the SAME tx as the canonical writes: read the durable epoch FIRST and
+        // only apply if it still matches the epoch we opened under. IndexedDB serializes
+        // overlapping readwrite txns to the same stores across tabs/connections, so a
+        // clear() that committed first (bumping the epoch) is observed here and we abort —
+        // an apply can never resurrect rows a concurrent logout just cleared (I9).
+        const tx = db.transaction([CANONICAL, OPERATIONS, META], "readwrite");
+        let applied = false;
+        const epochReq = tx.objectStore(META).get(EPOCH_KEY);
+        epochReq.onsuccess = () => {
+            const epoch = epochReq.result?.value ?? 0;
+            if (epoch !== this.epoch) {
+                // A clear() advanced the epoch since we opened: applying now would resurrect
+                // just-cleared (sensitive) rows. Abort — issue NO writes — and end this session.
+                this.epoch = epoch;
+                this.sessionEnded = true;
+                return;
+            }
+            applied = true;
+            const canonical = tx.objectStore(CANONICAL);
+            const ops = tx.objectStore(OPERATIONS);
+            for (const entry of perRow.values()) {
+                const getReq = canonical.get([entry.table, entry.id]);
+                getReq.onsuccess = () => {
+                    let row = getReq.result ?? null;
+                    for (const change of entry.changes) {
+                        const next = nextCanonicalRow(row, change);
+                        if (next !== "stale") {
+                            row = next;
+                        }
+                    }
+                    if (row) {
+                        canonical.put(row);
+                    }
+                };
+            }
+            for (const opId of opIds) {
+                ops.delete(opId);
+            }
+        };
+        await transactionDone(tx);
+        if (applied) {
+            this.notify();
+        }
+    }
+    async enqueueOperation(operation) {
+        const db = await this.db();
+        const tx = db.transaction(OPERATIONS, "readwrite");
+        const store = tx.objectStore(OPERATIONS);
+        const existing = await request(store.get(operation.opId));
+        if (!existing) {
+            store.put(operation);
+        }
+        await transactionDone(tx);
+        if (!existing) {
+            this.notify();
+        }
+    }
+    async getPendingOperations() {
+        const all = await this.getAllOperations();
+        return all.filter((operation) => OWED_STATUSES.has(operation.status));
+    }
+    async getAllOperations() {
+        const db = await this.db();
+        const tx = db.transaction(OPERATIONS, "readonly");
+        const all = (await request(tx.objectStore(OPERATIONS).getAll()));
+        return all.sort(compareOperations);
+    }
+    async getOperation(opId) {
+        const db = await this.db();
+        const tx = db.transaction(OPERATIONS, "readonly");
+        return (await request(tx.objectStore(OPERATIONS).get(opId))) ?? null;
+    }
+    async updateOperationStatus(opId, status, error) {
+        const db = await this.db();
+        const tx = db.transaction(OPERATIONS, "readwrite");
+        const store = tx.objectStore(OPERATIONS);
+        const current = (await request(store.get(opId)));
+        if (current) {
+            store.put({ ...current, status, error });
+        }
+        await transactionDone(tx);
+        if (current) {
+            this.notify();
+        }
+    }
+    async dropOperation(opId) {
+        const db = await this.db();
+        const tx = db.transaction(OPERATIONS, "readwrite");
+        const store = tx.objectStore(OPERATIONS);
+        const current = (await request(store.get(opId)));
+        if (current) {
+            store.delete(opId);
+        }
+        await transactionDone(tx);
+        if (current) {
+            this.notify();
+        }
+    }
+    async getCursor(scopeKey) {
+        const db = await this.db();
+        const tx = db.transaction(CURSORS, "readonly");
+        const row = (await request(tx.objectStore(CURSORS).get(scopeKey)));
+        return row?.cursor ?? null;
+    }
+    async setCursor(scopeKey, cursor) {
+        const db = await this.db();
+        const tx = db.transaction(CURSORS, "readwrite");
+        const store = tx.objectStore(CURSORS);
+        // Monotonic (I5): read-compare-write in ONE readwrite tx. IndexedDB serializes
+        // readwrite txns on the same store, so this is atomic across concurrent pulls;
+        // the put is issued inside the get's onsuccess so the tx can't auto-commit
+        // between them. A write that would move the cursor backward is dropped.
+        const getReq = store.get(scopeKey);
+        getReq.onsuccess = () => {
+            const existing = getReq.result;
+            if (!existing || cursor > existing.cursor) {
+                store.put({ scopeKey, cursor });
+            }
+        };
+        await transactionDone(tx);
+    }
+    async clear() {
+        // Serialize through writeChain so a logout clear cannot land BETWEEN an
+        // in-flight apply's read and write and resurrect the just-cleared rows.
+        const run = this.writeChain.then(() => this.clearAtomic());
+        this.writeChain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async clearAtomic() {
+        const db = await this.db();
+        const tx = db.transaction([CANONICAL, OPERATIONS, CURSORS, META], "readwrite");
+        tx.objectStore(CANONICAL).clear();
+        tx.objectStore(OPERATIONS).clear();
+        tx.objectStore(CURSORS).clear();
+        // Bump (NOT clear) the durable epoch in the SAME tx so a concurrent apply — in this
+        // tab or another, which reads META in its own serialized tx — sees the advance and
+        // aborts instead of resurrecting the just-cleared rows.
+        const meta = tx.objectStore(META);
+        const getReq = meta.get(EPOCH_KEY);
+        getReq.onsuccess = () => {
+            const next = (getReq.result?.value ?? 0) + 1;
+            meta.put({ key: EPOCH_KEY, value: next });
+            this.epoch = next;
+        };
+        await transactionDone(tx);
+        this.sessionEnded = true;
+        this.notify();
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    notify() {
+        for (const listener of Array.from(this.listeners)) {
+            listener();
+        }
+    }
+}

package/dist/internal.d.ts

@@ -0,0 +1,12 @@
+export * from "./engine.js";
+export * from "./rebase.js";
+export * from "./view.js";
+export * from "./declarative.js";
+export * from "./leadership.js";
+export * from "./multiTab.js";
+export * from "./ordering.js";
+export * from "./setMerge.js";
+export { createOpId, createDefaultIdFactory } from "./id.js";
+export { openLocalFirstDb, INDEXED_DB_SCHEMA_VERSION } from "./indexedDbStore.js";
+export { createLocalFirstMutationCall, createFallbackMutationCall } from "./mutationCall.js";
+export { defaultFunctionName } from "./functionName.js";

package/dist/internal.js

@@ -0,0 +1,22 @@
+// Internal API surface — NOT part of the public package (GOAL §6 / I13).
+//
+// The engine, rebase/replay, the derived view, the manifest interpreters
+// (declarative*, consumed only by codegen output), multi-tab leadership, and
+// low-level call/name helpers are implementation details: app authors must never
+// import them, so they are kept OUT of the package's public entry
+// ("@convex-localfirst/core"). The React adapter and generated code — the only
+// legitimate internal consumers — import them from "@convex-localfirst/core/internal".
+// A type-surface guard test (publicApi.test.ts) asserts none of these leak into the
+// public index.
+export * from "./engine.js";
+export * from "./rebase.js";
+export * from "./view.js";
+export * from "./declarative.js";
+export * from "./leadership.js";
+export * from "./multiTab.js";
+export * from "./ordering.js";
+export * from "./setMerge.js";
+export { createOpId, createDefaultIdFactory } from "./id.js";
+export { openLocalFirstDb, INDEXED_DB_SCHEMA_VERSION } from "./indexedDbStore.js";
+export { createLocalFirstMutationCall, createFallbackMutationCall } from "./mutationCall.js";
+export { defaultFunctionName } from "./functionName.js";

package/dist/leadership.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Multi-tab sync leadership. Only the leader tab runs background push/pull so a
+ * mutation is not pushed N times from N open tabs. Uses the Web Locks API — the robust
+ * browser primitive whose lock auto-releases when a tab crashes or closes, so failover
+ * needs no heartbeat or hand-rolled election.
+ *
+ * The React provider only engages multi-tab when Web Locks is present, and every browser
+ * that ships IndexedDB (which this library requires for persistence) also ships Web Locks.
+ * Without Web Locks a tab simply leads itself and syncs; concurrent tabs would then each
+ * push, but the server ledger dedupes by opId, so the result is correct (just less
+ * efficient). That keeps this the single, crash-safe coordination path — no second
+ * election protocol to keep correct.
+ */
+export type LeadershipOptions = {
+    /** Lock name; tabs sharing it elect a single leader (whoever holds the exclusive lock). */
+    readonly name: string;
+    /** Stable id for this tab (the engine's clientId). */
+    readonly id: string;
+    readonly onChange?: (isLeader: boolean) => void;
+    /**
+     * Injectable Web Locks manager. `undefined` → use navigator.locks if present;
+     * `null` → no Web Locks, so this tab leads itself (used by tests / non-browser).
+     */
+    readonly locks?: LockManagerLike | null;
+};
+/** The slice of the Web Locks API we use (navigator.locks). */
+export type LockManagerLike = {
+    request(name: string, options: {
+        mode?: "exclusive" | "shared";
+        signal?: AbortSignal;
+    }, callback: () => Promise<unknown>): Promise<unknown>;
+};
+export declare class TabLeadership {
+    private readonly options;
+    private leader;
+    private stopped;
+    private abort;
+    private releaseLock;
+    constructor(options: LeadershipOptions);
+    isLeader(): boolean;
+    /** Begin acquisition. Resolves once the request is issued (Web Locks) or immediately
+     *  (no Web Locks → this tab self-leads). Leadership changes thereafter via onChange. */
+    start(): Promise<void>;
+    stop(): void;
+    private resolveLocks;
+    private startWithLocks;
+    private setLeader;
+}

package/dist/leadership.js

@@ -0,0 +1,69 @@
+export class TabLeadership {
+    options;
+    leader = false;
+    stopped = false;
+    abort = null;
+    releaseLock = null;
+    constructor(options) {
+        this.options = options;
+    }
+    isLeader() {
+        return this.leader;
+    }
+    /** Begin acquisition. Resolves once the request is issued (Web Locks) or immediately
+     *  (no Web Locks → this tab self-leads). Leadership changes thereafter via onChange. */
+    start() {
+        const locks = this.resolveLocks();
+        if (locks) {
+            return this.startWithLocks(locks);
+        }
+        // No Web Locks: this class can't coordinate across tabs (the React provider only engages
+        // multi-tab when Web Locks is present). A direct caller without locks gets sole-tab
+        // behavior — lead immediately so its engine runs sync rather than staying gated.
+        this.setLeader(true);
+        return Promise.resolve();
+    }
+    stop() {
+        this.stopped = true;
+        // Releasing the held promise frees the lock so a waiting tab leads; aborting cancels a
+        // pending (follower) request. The browser also auto-releases if this tab crashes.
+        this.releaseLock?.();
+        this.releaseLock = null;
+        this.abort?.abort();
+        this.setLeader(false);
+    }
+    resolveLocks() {
+        if (this.options.locks !== undefined) {
+            return this.options.locks;
+        }
+        const nav = globalThis.navigator;
+        return nav?.locks ?? null;
+    }
+    startWithLocks(locks) {
+        this.abort = new AbortController();
+        // Holding an exclusive lock named `name` == being the leader. The callback runs only
+        // once the lock is granted; until then this tab is a follower. The browser frees the
+        // lock if this tab dies, so a dead leader fails over automatically.
+        void locks
+            .request(this.options.name, { mode: "exclusive", signal: this.abort.signal }, () => {
+            if (this.stopped) {
+                return Promise.resolve();
+            }
+            this.setLeader(true);
+            return new Promise((release) => {
+                this.releaseLock = release;
+            });
+        })
+            .catch(() => {
+            // AbortError (stopped before acquiring) or a lock failure: stay a follower.
+        });
+        // "Settled" = request issued; leadership arrives via onChange when the lock is held.
+        return Promise.resolve();
+    }
+    setLeader(value) {
+        if (this.leader !== value) {
+            this.leader = value;
+            this.options.onChange?.(value);
+        }
+    }
+}