@convex-localfirst/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fanzzzd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @convex-localfirst/core
+
+The local-first engine for [Convex](https://convex.dev): a canonical-centric store
+where the live view is derived (`canonical + replay(pending)`), so server changes never
+clobber pending local ops. Includes the sync protocol, deterministic op ordering, an
+IndexedDB adapter with migrations, Web Locks multi-tab leadership, and opt-in convergent
+merges (set / counter / timestamp-LWW).
+
+Most apps use [`@convex-localfirst/react`](https://www.npmjs.com/package/@convex-localfirst/react)
+or [`@convex-localfirst/server`](https://www.npmjs.com/package/@convex-localfirst/server)
+rather than this package directly.
+
+```bash
+npm install @convex-localfirst/core
+```
+
+MIT

package/dist/collection.d.ts

@@ -0,0 +1,101 @@
+import type { RelationEntry, RelationSpec } from "./relations.js";
+import type { RowValue } from "./types.js";
+/**
+ * A compiled local-first query plan: a pure where/order/limit refinement over the
+ * rows a table already holds locally (its authorized, server-pulled scope), plus
+ * optional in-memory relations attached from other local tables. It NEVER reaches
+ * unsynced data — local query is refinement, not authorization. The server still
+ * decides what syncs into the scope (Invariant I7), so a client predicate/relation
+ * can only narrow/join what is already permitted, never widen it.
+ *
+ * `Row` is the base table row; `Rel` is the shape attached by .related() — the
+ * result rows are `Row & Rel`.
+ */
+export type LocalQueryPlan<Row extends Record<string, unknown> = Record<string, unknown>, Rel = unknown> = {
+    readonly __localFirstQuery: true;
+    /**
+     * Phantom: carries the `.related()` result shape `Rel` so `useLiveQuery` can
+     * infer `Row & Rel` structurally. `Rel` appears in no other member (run() only
+     * returns the base `Row[]`), so without this the parameter would be unbindable
+     * and silently fall back to `unknown`. Never set at runtime.
+     */
+    readonly __rel?: Rel;
+    readonly table: string;
+    /** Scope field values (e.g. { workspaceId }); the engine builds the pull scope. */
+    readonly scopeValues?: Record<string, unknown>;
+    /** Relations to attach in memory (resolved by the engine across local tables). */
+    readonly relations: readonly RelationEntry[];
+    /** Apply where/order/limit to the base table's live rows. Pure. Relations are
+     *  attached afterwards by the engine (they need other tables' rows). */
+    run(rows: readonly RowValue[]): Row[];
+};
+/**
+ * The result shape contributed by a named map of relation specs: each key maps
+ * to `Target[]` for many/manyToMany, or `Target | undefined` for one. Lets
+ * `.withRelations({...})` attach a reusable relation map in one typed call.
+ */
+export type RelationsResult<Specs extends Record<string, RelationSpec>> = {
+    [K in keyof Specs]: Specs[K] extends RelationSpec<infer Target, infer Many> ? Many extends true ? Target[] : Target | undefined : never;
+};
+type Ops<Row> = {
+    readonly scopeValues?: Record<string, unknown>;
+    readonly predicates: ReadonlyArray<(row: Row) => boolean>;
+    readonly orderKey?: keyof Row;
+    readonly orderDir: "asc" | "desc";
+    readonly limitN?: number;
+    readonly relations: readonly RelationEntry[];
+};
+/**
+ * Chainable, fully-typed client query builder — Zero/TanStack-style ergonomics,
+ * Convex-idiomatic. `where` takes a plain typed JS predicate (we refine locally,
+ * so no serializable filter DSL is needed); `.related()` attaches related local
+ * tables with full type inference. Pass the result to `useLiveQuery`, or run it
+ * directly via `engine.runLocalQuery`.
+ */
+export declare class LocalQuery<Row extends Record<string, unknown> = RowValue, Rel = unknown> implements LocalQueryPlan<Row, Rel> {
+    readonly table: string;
+    private readonly ops;
+    readonly __localFirstQuery: true;
+    /** Phantom carrier for `Rel` (see LocalQueryPlan.__rel) — `declare` ⇒ no runtime field. */
+    readonly __rel: Rel;
+    constructor(table: string, ops?: Ops<Row>);
+    /** Narrow to a workspace/project scope (typed to the row's scope fields). */
+    scope(values: Partial<Row>): LocalQuery<Row, Rel>;
+    /** Keep rows matching a typed predicate. Chains as AND. */
+    where(predicate: (row: Row) => boolean): LocalQuery<Row, Rel>;
+    /** Sort by a field; defaults to ascending. */
+    order<K extends keyof Row>(field: K, direction?: "asc" | "desc"): LocalQuery<Row, Rel>;
+    /** Cap the number of rows returned. */
+    limit(n: number): LocalQuery<Row, Rel>;
+    /**
+     * Attach a related local table under `name`. `one(...)` yields a single row (or
+     * undefined); `many(...)`/`manyToMany(...)` yield an array. Fully typed: the
+     * result rows become `Row & { [name]: Target | Target[] }`.
+     */
+    related<Name extends string, Target extends Record<string, unknown>, Many extends boolean>(name: Name, spec: RelationSpec<Target, Many>): LocalQuery<Row, Rel & {
+        [K in Name]: Many extends true ? Target[] : Target | undefined;
+    }>;
+    /**
+     * Attach a whole map of named relations at once — the lazy path for the common
+     * case where relations belong to the model, not the query. Define the map once
+     * (next to your row type) and reuse it everywhere:
+     *
+     *   const issueRelations = {
+     *     project: one<Doc<"projects">>("projects", "projectId"),
+     *     comments: many<Doc<"comments">>("comments", "issueId"),
+     *     labels: manyToMany<Doc<"labels">>("labels", "issue_labels", "issueId", "labelId")
+     *   };
+     *   collection<Issue>("issues").scope({ workspaceId }).withRelations(issueRelations)
+     *
+     * Fully typed: result rows become `Row & { project: ...; comments: ...[]; ... }`.
+     * Equivalent to chaining `.related(name, spec)` for each entry.
+     */
+    withRelations<Specs extends Record<string, RelationSpec>>(specs: Specs): LocalQuery<Row, Rel & RelationsResult<Specs>>;
+    get scopeValues(): Record<string, unknown> | undefined;
+    get relations(): readonly RelationEntry[];
+    run(rows: readonly RowValue[]): Row[];
+    private with;
+}
+/** Start a typed local-first query over a table: `collection<Doc<"issues">>("issues")`. */
+export declare function collection<Row extends Record<string, unknown> = RowValue>(table: string): LocalQuery<Row>;
+export {};

package/dist/collection.js

@@ -0,0 +1,100 @@
+import { compareValues } from "./ordering.js";
+/**
+ * Chainable, fully-typed client query builder — Zero/TanStack-style ergonomics,
+ * Convex-idiomatic. `where` takes a plain typed JS predicate (we refine locally,
+ * so no serializable filter DSL is needed); `.related()` attaches related local
+ * tables with full type inference. Pass the result to `useLiveQuery`, or run it
+ * directly via `engine.runLocalQuery`.
+ */
+export class LocalQuery {
+    table;
+    ops;
+    __localFirstQuery = true;
+    constructor(table, ops = { predicates: [], orderDir: "asc", relations: [] }) {
+        this.table = table;
+        this.ops = ops;
+    }
+    /** Narrow to a workspace/project scope (typed to the row's scope fields). */
+    scope(values) {
+        return this.with({ scopeValues: values });
+    }
+    /** Keep rows matching a typed predicate. Chains as AND. */
+    where(predicate) {
+        return this.with({ predicates: [...this.ops.predicates, predicate] });
+    }
+    /** Sort by a field; defaults to ascending. */
+    order(field, direction = "asc") {
+        return this.with({ orderKey: field, orderDir: direction });
+    }
+    /** Cap the number of rows returned. */
+    limit(n) {
+        return this.with({ limitN: n });
+    }
+    /**
+     * Attach a related local table under `name`. `one(...)` yields a single row (or
+     * undefined); `many(...)`/`manyToMany(...)` yield an array. Fully typed: the
+     * result rows become `Row & { [name]: Target | Target[] }`.
+     */
+    related(name, spec) {
+        return new LocalQuery(this.table, {
+            ...this.ops,
+            relations: [...this.ops.relations, { name, spec }]
+        });
+    }
+    /**
+     * Attach a whole map of named relations at once — the lazy path for the common
+     * case where relations belong to the model, not the query. Define the map once
+     * (next to your row type) and reuse it everywhere:
+     *
+     *   const issueRelations = {
+     *     project: one<Doc<"projects">>("projects", "projectId"),
+     *     comments: many<Doc<"comments">>("comments", "issueId"),
+     *     labels: manyToMany<Doc<"labels">>("labels", "issue_labels", "issueId", "labelId")
+     *   };
+     *   collection<Issue>("issues").scope({ workspaceId }).withRelations(issueRelations)
+     *
+     * Fully typed: result rows become `Row & { project: ...; comments: ...[]; ... }`.
+     * Equivalent to chaining `.related(name, spec)` for each entry.
+     */
+    withRelations(specs) {
+        const entries = Object.keys(specs).map((name) => ({ name, spec: specs[name] }));
+        return new LocalQuery(this.table, {
+            ...this.ops,
+            relations: [...this.ops.relations, ...entries]
+        });
+    }
+    get scopeValues() {
+        return this.ops.scopeValues;
+    }
+    get relations() {
+        return this.ops.relations;
+    }
+    run(rows) {
+        const scopeValues = this.ops.scopeValues;
+        let out = rows.filter((row) => {
+            if (scopeValues) {
+                for (const key in scopeValues) {
+                    if (row[key] !== scopeValues[key])
+                        return false;
+                }
+            }
+            return this.ops.predicates.every((predicate) => predicate(row));
+        });
+        if (this.ops.orderKey !== undefined) {
+            const key = this.ops.orderKey;
+            const direction = this.ops.orderDir === "desc" ? -1 : 1;
+            out = [...out].sort((a, b) => compareValues(a[key], b[key]) * direction);
+        }
+        if (this.ops.limitN !== undefined) {
+            out = out.slice(0, Math.max(0, this.ops.limitN));
+        }
+        return out;
+    }
+    with(patch) {
+        return new LocalQuery(this.table, { ...this.ops, ...patch });
+    }
+}
+/** Start a typed local-first query over a table: `collection<Doc<"issues">>("issues")`. */
+export function collection(table) {
+    return new LocalQuery(table);
+}

package/dist/declarative.d.ts

@@ -0,0 +1,56 @@
+import type { LocalMutationDefinition, LocalQueryDefinition } from "./manifest.js";
+import type { JsonValue, RowValue } from "./types.js";
+/**
+ * Declarative descriptors emitted by codegen. They make the client manifest pure
+ * data + generic interpreters (below), so no per-function code is generated and
+ * the manifest is browser-safe (no Convex server imports).
+ */
+export type FieldSource = {
+    readonly from: "arg";
+    readonly arg: string;
+} | {
+    readonly from: "auth";
+} | {
+    readonly from: "now";
+} | {
+    readonly from: "const";
+    readonly value: JsonValue;
+};
+/**
+ * How a query derives its pull scope. byUser is omitted (the engine derives it
+ * from the authed user); workspace/project scopes name the query arg that holds
+ * the scope value (e.g. the workspaceId arg).
+ */
+export type DeclarativeScope = {
+    readonly kind: "byWorkspace" | "byProject";
+    readonly valueArg: string;
+};
+export type DeclarativeQuery = {
+    readonly name: string;
+    readonly table: string;
+    readonly filters: readonly string[];
+    readonly orderBy?: string;
+    readonly order?: "asc" | "desc";
+    readonly initial?: unknown;
+    readonly scope?: DeclarativeScope;
+};
+export type DeclarativeInsert = {
+    readonly name: string;
+    readonly table: string;
+    readonly fields: Record<string, FieldSource>;
+};
+export type DeclarativePatch = {
+    readonly name: string;
+    readonly table: string;
+    readonly idArg: string;
+    readonly fields: Record<string, FieldSource>;
+};
+export type DeclarativeRemove = {
+    readonly name: string;
+    readonly table: string;
+    readonly idArg: string;
+};
+export declare function declarativeQuery(descriptor: DeclarativeQuery): LocalQueryDefinition<Record<string, unknown>, RowValue[]>;
+export declare function declarativeInsert(descriptor: DeclarativeInsert): LocalMutationDefinition<Record<string, unknown>>;
+export declare function declarativePatch(descriptor: DeclarativePatch): LocalMutationDefinition<Record<string, unknown>>;
+export declare function declarativeRemove(descriptor: DeclarativeRemove): LocalMutationDefinition<Record<string, unknown>>;

package/dist/declarative.js

@@ -0,0 +1,86 @@
+import { compareValues } from "./ordering.js";
+function resolveField(source, args, ctx) {
+    switch (source.from) {
+        case "arg":
+            return args[source.arg];
+        case "auth":
+            return ctx.userId;
+        case "now":
+            return ctx.now;
+        case "const":
+            return source.value;
+    }
+}
+export function declarativeQuery(descriptor) {
+    const definition = {
+        kind: "query",
+        name: descriptor.name,
+        table: descriptor.table,
+        initial: descriptor.initial ?? [],
+        run(rows, args) {
+            let out = rows.filter((row) => descriptor.filters.every((field) => row[field] === args[field]));
+            if (descriptor.orderBy) {
+                const key = descriptor.orderBy;
+                const direction = descriptor.order === "desc" ? -1 : 1;
+                out = [...out].sort((a, b) => compareValues(a[key], b[key]) * direction);
+            }
+            return out;
+        }
+    };
+    // Workspace/project queries carry their pull scope so the engine pulls (and the
+    // server enforces membership on) the right scope. byUser is derived by the engine.
+    if (descriptor.scope) {
+        const sc = descriptor.scope;
+        return {
+            ...definition,
+            scope: (args) => ({ kind: sc.kind, key: `${sc.kind}:${String(args[sc.valueArg])}`, table: descriptor.table })
+        };
+    }
+    return definition;
+}
+export function declarativeInsert(descriptor) {
+    return {
+        kind: "mutation",
+        name: descriptor.name,
+        table: descriptor.table,
+        plan(args, ctx) {
+            const value = {};
+            for (const [field, source] of Object.entries(descriptor.fields)) {
+                value[field] = resolveField(source, args, ctx);
+            }
+            return { kind: "insert", table: descriptor.table, id: ctx.localId(descriptor.table), value };
+        }
+    };
+}
+export function declarativePatch(descriptor) {
+    return {
+        kind: "mutation",
+        name: descriptor.name,
+        table: descriptor.table,
+        plan(args, ctx) {
+            const patch = {};
+            for (const [field, source] of Object.entries(descriptor.fields)) {
+                const resolved = resolveField(source, args, ctx);
+                // A partial patch must not clobber fields the caller didn't set: skip an arg
+                // that resolved to `undefined` (an absent optional arg). This is what lets ONE
+                // `update` mutation with all-optional fields act as a generic partial patch
+                // (the seam Plane's `patchIssue(Partial<TIssue>)` needs). `null` is a real
+                // value (Plane uses it for "cleared") and still passes through.
+                if (resolved !== undefined) {
+                    patch[field] = resolved;
+                }
+            }
+            return { kind: "patch", table: descriptor.table, id: String(args[descriptor.idArg]), patch };
+        }
+    };
+}
+export function declarativeRemove(descriptor) {
+    return {
+        kind: "mutation",
+        name: descriptor.name,
+        table: descriptor.table,
+        plan(args) {
+            return { kind: "delete", table: descriptor.table, id: String(args[descriptor.idArg]) };
+        }
+    };
+}

package/dist/engine.d.ts

@@ -0,0 +1,237 @@
+import type { LocalQueryPlan } from "./collection.js";
+import { type IdFactory } from "./id.js";
+import type { FunctionNameResolver } from "./functionName.js";
+import type { LocalFirstManifest } from "./manifest.js";
+import { type LocalFirstMutationCall } from "./mutationCall.js";
+import type { LocalStore } from "./storage.js";
+import type { SyncTransport } from "./transport.js";
+import type { RowValue, SyncScope, SyncStatus } from "./types.js";
+export type LocalFirstEngineOptions = {
+    readonly manifest: LocalFirstManifest;
+    readonly store: LocalStore;
+    readonly clientId: string;
+    readonly userId?: string | null;
+    readonly transport?: SyncTransport;
+    readonly nameOf?: FunctionNameResolver;
+    readonly idFactory?: IdFactory;
+    readonly clock?: () => number;
+    /** Network retry policy for background sync. */
+    readonly retry?: {
+        readonly retries: number;
+        readonly baseDelayMs: number;
+    };
+    /** Injectable delay (tests pass a no-op to avoid real waits). */
+    readonly sleep?: (ms: number) => Promise<void>;
+    /**
+     * Hard cap (ms) on a single push/pull, so an unreachable server (online but not
+     * responding) can't hang sync — or an awaited read — forever. On timeout the call fails
+     * fast (ops stay pending). 0 disables. Default 15000. Complements the navigator.onLine
+     * guard, which handles a hard OS-offline.
+     */
+    readonly syncTimeoutMs?: number;
+};
+export declare class LocalFirstEngine {
+    readonly manifest: LocalFirstManifest;
+    private readonly store;
+    readonly clientId: string;
+    private readonly userId;
+    private readonly transport;
+    private readonly nameOf;
+    private readonly idFactory;
+    private readonly clock;
+    private readonly retry;
+    private readonly syncTimeoutMs;
+    private readonly sleep;
+    private status;
+    private readonly opStatuses;
+    private readonly statusListeners;
+    private readonly scopeWatchers;
+    private disposeConnectivity;
+    private syncEnabled;
+    private tsHighWater;
+    constructor(options: LocalFirstEngineOptions);
+    /** Wall-clock timestamp that never goes backward within this engine, so a backward
+     *  clock step cannot reorder two local edits (I4). */
+    private monotonicNow;
+    /** Seed the high-water from durable ops so monotonic order holds across reloads.
+     *  ponytail: an op created before this async seed resolves could predate it — needs a
+     *  backward clock step AND reload AND a same-row edit in that window; acceptable. */
+    private seedTimestampHighWater;
+    /** Merge a status patch and notify subscribers so useSyncStatus re-renders. */
+    private setStatus;
+    /**
+     * Resolve a function reference to its stable name. The React adapter keys effects on
+     * this string, not the reference object, because Convex's `api` proxy returns a fresh
+     * object per access — keying on identity would re-run the effect every render (a sync loop).
+     */
+    functionName(reference: unknown): string | null;
+    /**
+     * Run a transport call and reflect connectivity in status.online (threw → offline,
+     * returned → online). ponytail: heuristic — a server-side error also reads as offline;
+     * the navigator online/offline events give finer detection.
+     */
+    private tracked;
+    hasLocalQuery(reference: unknown): boolean;
+    hasLocalMutation(reference: unknown): boolean;
+    query<TArgs, TResult>(reference: unknown, args: TArgs): Promise<TResult | undefined>;
+    /**
+     * Keep only rows in the active scope (owner==userId for byUser, field==value for
+     * byWorkspace/byProject). The client caches every scope the user can see, so a query
+     * with an incomplete filter could otherwise observe another scope's rows; enforcing it
+     * here mirrors the server's I7. `custom` scopes have no client-known field → server-only.
+     */
+    private filterToScope;
+    /** True when `table` is workspace/project-scoped but `args` carry no scope value. */
+    private scopedQueryMissingScope;
+    /**
+     * @internal All visible (non-deleted) rows for a table, from the derived view
+     * (I1). UNSCOPED plumbing for useLiveQuery's subscription — the hook only ever
+     * returns these through `applyLocalQuery` (the scoped guard). Not an app API.
+     */
+    tableRows(table: string): Promise<readonly RowValue[]>;
+    /** Every table a plan reads: its base table plus any relation targets/join tables. */
+    tablesForPlan(plan: LocalQueryPlan): string[];
+    /**
+     * Apply a query plan to already-fetched rows (keyed by table), enforcing the
+     * scoped fail-closed guard and attaching relations in memory. Synchronous so the
+     * React hook (useLiveQuery) can call it at render and cannot bypass the guard by
+     * running plan.run directly.
+     */
+    applyLocalQuery<Row extends Record<string, unknown>, Rel>(plan: LocalQueryPlan<Row, Rel>, rowsByTable: Record<string, readonly RowValue[]>): Array<Row & Rel>;
+    runLocalQuery<Row extends Record<string, unknown>, Rel>(plan: LocalQueryPlan<Row, Rel>): Promise<Array<Row & Rel>>;
+    /**
+     * One-call imperative read for the service-layer path: background-refresh the plan's
+     * scope (offline-safe, never throws), then return the merged local rows (canonical +
+     * pending). Prefer over hand-orchestrating refreshPlan + runLocalQuery. For reactive UI
+     * use useLiveQuery instead.
+     */
+    read<Row extends Record<string, unknown>, Rel>(plan: LocalQueryPlan<Row, Rel>): Promise<Array<Row & Rel>>;
+    /**
+     * Read a single live row by id (== row[idField] == _id), or undefined. Local-only, no
+     * server pull — for the "I just wrote id X, read it back" case (the write already flushes
+     * via its own .server push). Includes pending optimistic state. For a possibly-cold row
+     * (e.g. a deep link), use a scoped query so refreshPlan can pull it first.
+     */
+    getRow<Row extends Record<string, unknown>>(table: string, id: string): Promise<Row | undefined>;
+    /**
+     * Pull scope for a query plan: the explicit workspace/project value when the
+     * table is scoped that way, else the authed user. Key format mirrors the
+     * declarative path so pull cursors and server membership checks line up.
+     */
+    scopeForPlan(plan: LocalQueryPlan): SyncScope | null;
+    /** Background sync for a mounted plan (push pending + pull its scope). Never throws. */
+    refreshPlan(plan: LocalQueryPlan): Promise<void>;
+    /** True when the transport offers a reactive change feed (server push). When
+     *  false, callers fall back to polling for real-time. */
+    get reactive(): boolean;
+    /**
+     * Reactive sync for a mounted plan: subscribe to the transport's change feed for
+     * this plan's scope and drain (pull) on every server-side change — true server
+     * push, no polling. Returns an unsubscribe, or `null` when the transport is not
+     * reactive (the caller should fall back to polling) or the plan has no scope.
+     */
+    watchPlan(plan: LocalQueryPlan): (() => void) | null;
+    /**
+     * Reactive sync for a declarative (server-defined) query — the `useQuery` path. Like
+     * `watchPlan` but resolves the scope from the query DEFINITION. Returns an unsubscribe,
+     * or `null` when not reactive / no scope. This is what makes our `useQuery` reactive
+     * like `convex/react`'s.
+     */
+    watchQuery<TArgs>(reference: unknown, args: TArgs): (() => void) | null;
+    /**
+     * Refcounted entry point: many hooks watching the SAME scope share ONE watch + drain
+     * loop (started on the first watcher, torn down on the last). Returns an idempotent unwatch.
+     */
+    private watchScope;
+    /**
+     * Drive one scope's subscription. The doorbell carries no data, so each fire triggers a
+     * real `pullScopes` drain, then re-subscribes at the advanced cursor: a fixed-cursor
+     * watch grows until it saturates the page limit and goes deaf, so re-pinning keeps the
+     * window small. Only resubscribing when the cursor moved avoids an empty-fire loop.
+     */
+    private startScopeWatch;
+    /** Subscribe to local DATA changes (rows). Used by useQuery. */
+    subscribe(listener: () => void): () => void;
+    /** Subscribe to SYNC STATUS changes (online/syncing/pending). Used by useSyncStatus. */
+    subscribeStatus(listener: () => void): () => void;
+    mutate<TArgs, TResult = unknown>(reference: unknown, args: TArgs): LocalFirstMutationCall<TResult>;
+    syncOnce(scopes?: readonly SyncScope[]): Promise<void>;
+    getStatus(): SyncStatus;
+    /** Reflect externally-known connectivity (e.g. the browser's online/offline events). */
+    setOnline(online: boolean): void;
+    /**
+     * Self-wire browser connectivity so offline-first works with zero consumer setup: going
+     * offline makes sync a no-op (so reads/writes don't hang on a buffering socket), and
+     * reconnect flushes the outbox. Returns a remover; a noop outside a browser. Safe to
+     * double-wire with the React provider (setOnline is idempotent; flushPending dedupes).
+     */
+    private wireConnectivity;
+    /** Remove engine-owned browser listeners. Optional: a singleton engine that lives
+     *  for the page lifetime need not call this; provided for tests / teardown. */
+    dispose(): void;
+    /**
+     * A HARD offline signal only (navigator.onLine === false), where a push/pull would just
+     * hang on a buffering client. Deliberately NOT gated on the softer status.online, which a
+     * transient server error can flip false — that would wedge sync off while genuinely online.
+     */
+    private isLikelyOffline;
+    /**
+     * Multi-tab leadership gate (wired by the React provider). Only the leader runs the
+     * background batch push; a follower keeps pulling but doesn't re-push the shared outbox.
+     * On regaining leadership we flush immediately so an inherited backlog isn't stranded.
+     */
+    setSyncEnabled(enabled: boolean): void;
+    /**
+     * Explicit, UN-gated push of the outbox (reconnect flush, leadership handoff, or a
+     * cross-tab wake). Distinct from the background push so an offline-created op in a
+     * follower tab is not stranded waiting for the leader's next trigger. Never throws.
+     */
+    flushPending(): void;
+    /**
+     * Cross-tab "db changed" poke: IndexedDB has no cross-tab change event, so when the
+     * leader pulls into the shared DB, follower tabs are told to re-derive. Safe to over-call
+     * (applyServerChanges is version-folded, so a re-read only surfaces equal-or-newer rows).
+     */
+    pokeLocalChange(): void;
+    /**
+     * Background sync triggered by a mounted query: push pending ops and pull this
+     * query's scope (if the definition declares one). Never throws — failures are
+     * recorded in status.lastError for the UI.
+     */
+    refreshQuery<TArgs>(reference: unknown, args: TArgs): Promise<void>;
+    private scopeForTable;
+    private getQueryDefinition;
+    private getMutationDefinition;
+    private safeName;
+    /**
+     * For a patch on a table with declared `setFields`/`counterFields`, rewrite each touched
+     * field into a DELTA vs the row's current value, so concurrent edits merge (see setMerge.ts)
+     * instead of clobbering: arrays → set deltas, numbers → counter deltas. Runs before the op
+     * is persisted/pushed. No-op for non-patches, undeclared fields, or wrong-typed/already-delta values.
+     */
+    private applyFieldDeltas;
+    private commitLocal;
+    private markStatus;
+    private pushSingleOperation;
+    private pushPendingOperations;
+    private pullScopes;
+    private blockForSchemaMismatch;
+    /**
+     * Bound a transport call so an unreachable server can't hang sync forever. Races fn()
+     * against a timer (cleared on settle, unref'd so it can't keep a process alive).
+     * syncTimeoutMs <= 0 disables.
+     */
+    private withTimeout;
+    /** Retry a network call with exponential backoff. */
+    private withRetry;
+    private operationStatus;
+    private refreshPendingCount;
+}
+/**
+ * Headless engine factory — build an engine outside React for imperative consumers (a
+ * service layer, a MobX/Zustand store, a worker). The same instance can be passed to the
+ * React `ConvexProvider` (its `localFirst.engine` option) to share one engine/outbox/cache.
+ * Reads: `query`/`runLocalQuery` (scope-enforced); writes: `mutate`; `subscribe` fires on
+ * every local data change.
+ */
+export declare function createLocalFirstEngine(options: LocalFirstEngineOptions): LocalFirstEngine;