@voltro/local-first 0.29.0

package/dist/index.d.ts

@@ -0,0 +1,603 @@
+/**
+ * `true` when the queue is ready to hand its head to the transport: online,
+ * nothing already in flight, and something waiting. A `drain-start` dispatched
+ * when this is `false` is a no-op, so callers can dispatch it optimistically.
+ */
+export declare const canDrain: (state: SyncQueueState) => boolean;
+
+export declare interface ConflictPolicy {
+    /** Resolve a single named field. Fields with no declared policy fall back to LWW. */
+    readonly resolveField: (field: string, local: FieldValue, remote: FieldValue) => unknown;
+    /**
+     * Resolve two versions of a whole record, field by field. The result covers
+     * the union of both sides' keys; a key present on only one side is taken as-is.
+     */
+    readonly resolveRecord: (local: VersionedRecord, remote: VersionedRecord) => Record<string, unknown>;
+}
+
+/**
+ * Declare per-field conflict policy for a table's non-CRDT fields.
+ *
+ * ```ts
+ * const policy = conflictPolicy({
+ *   title: 'lastWriteWins',
+ *   permissions: customResolver,
+ * })
+ * policy.resolveRecord(localRow, remoteRow) // → merged plain values
+ * ```
+ *
+ * Fields not named here resolve with {@link lastWriteWins}, so a policy never
+ * has to enumerate every column to be safe.
+ */
+export declare const conflictPolicy: (policies: Record<string, FieldPolicy>) => ConflictPolicy;
+
+/** Resolves two competing versions of one field to a single winning value. */
+export declare type ConflictResolver<T = unknown> = (local: FieldValue<T>, remote: FieldValue<T>) => T;
+
+export declare type ConnectionAction = 
+/** Browser/OS reports the network interface is up. */
+    {
+    readonly type: 'network-up';
+}
+/** Browser/OS reports the network is down. */
+| {
+    readonly type: 'network-down';
+}
+/** A reachability confirmation (a real round-trip) succeeded. */
+| {
+    readonly type: 'confirmed';
+}
+/** A reachability confirmation failed; stay reconnecting, count the try. */
+| {
+    readonly type: 'confirm-failed';
+};
+
+export declare type ConnectionPhase = 'online' | 'offline' | 'reconnecting';
+
+export declare const connectionReducer: (state: ConnectionState, action: ConnectionAction) => ConnectionState;
+
+export declare interface ConnectionState {
+    readonly phase: ConnectionPhase;
+    /** Confirmation attempts made since the network last came back. 0 when online/offline. */
+    readonly attempt: number;
+}
+
+/**
+ * A CRDT implementation. One per library. The default is {@link yjsBackend}.
+ *
+ * `merge` and `decodeText` are STATELESS with respect to any live handle: they
+ * operate purely on encoded bytes, which is what lets the sync layer and tests
+ * converge two states without holding a document open.
+ */
+export declare interface CrdtBackend {
+    /** Identifies the library, e.g. `"yjs"`. Surfaced for diagnostics/telemetry. */
+    readonly name: string;
+    /** Create a fresh text buffer, optionally seeded with `initial`. */
+    createText: (initial?: string) => CrdtTextHandle;
+    /**
+     * Merge two encoded states into one converged encoded state.
+     *
+     * The core primitive. MUST be:
+     *  - commutative up to convergence: `decodeText(merge(a,b)) === decodeText(merge(b,a))`
+     *  - idempotent: `decodeText(merge(m,a)) === decodeText(m)` when `m` already contains `a`
+     *  - an identity over the empty state: `merge(empty, a)` decodes to `a`'s text
+     */
+    merge: (a: CrdtState, b: CrdtState) => CrdtState;
+    /** The plain-string view of an encoded state. */
+    decodeText: (state: CrdtState) => string;
+    /** The encoded state of an empty document — the merge identity element. */
+    emptyState: () => CrdtState;
+}
+
+/** Identifies one CRDT-managed cell: a `crdtText()` COLUMN of one ROW of one TABLE. */
+export declare interface CrdtDocKey {
+    readonly table: string;
+    readonly id: string;
+    readonly column: string;
+}
+
+/**
+ * An encoded CRDT state or delta, as opaque bytes. Produced by
+ * {@link CrdtBackend.encodeState} / {@link CrdtTextHandle.encodeState},
+ * consumed by {@link CrdtBackend.merge} and {@link CrdtBackend.decodeText}.
+ *
+ * It is opaque ON PURPOSE: the shape is the backend's business. Yjs emits a
+ * v1 update blob; Loro would emit its own. Consumers only ever move these
+ * bytes around and hand them back.
+ */
+export declare type CrdtState = Uint8Array;
+
+/**
+ * A CRDT-managed text field. A thin, fluent wrapper over a live
+ * {@link CrdtTextHandle}: mutations return `this` so edits chain, and the
+ * string view + encoded state are always one call away.
+ *
+ * ```ts
+ * const body = crdtText('hello')
+ * body.insert(5, ' world')
+ * body.toString()      // "hello world"
+ * const state = body.encode()          // bytes to sync
+ * ```
+ */
+export declare interface CrdtText {
+    /** The backing library's name (e.g. `"yjs"`). */
+    readonly backend: string;
+    /** Current text as a plain string. */
+    toString: () => string;
+    /** Insert `text` at `index` (UTF-16 code units). Chainable. */
+    insert: (index: number, text: string) => CrdtText;
+    /** Delete `length` code units at `index`. Chainable. */
+    delete: (index: number, length: number) => CrdtText;
+    /** Fold an incoming encoded state into this field; concurrent edits converge. Chainable. */
+    merge: (state: CrdtState) => CrdtText;
+    /** This field's full state, encoded for transport. */
+    encode: () => CrdtState;
+}
+
+/**
+ * Create a CRDT text field, optionally seeded with `initial`.
+ *
+ * @param backend defaults to {@link defaultCrdtBackend} (Yjs). Passing one is
+ *   how tests and a later Loro swap avoid touching every call site.
+ */
+export declare const crdtText: (initial?: string, backend?: CrdtBackend) => CrdtText;
+
+/**
+ * A live, mutable CRDT text buffer. Edits are local until you
+ * {@link CrdtTextHandle.encodeState | encode} them for transport/merge.
+ */
+export declare interface CrdtTextHandle {
+    /** The current text as a plain string — the view a UI renders. */
+    toString: () => string;
+    /** Insert `text` at UTF-16 code-unit `index`. */
+    insert: (index: number, text: string) => void;
+    /** Delete `length` code units starting at `index`. */
+    delete: (index: number, length: number) => void;
+    /** This buffer's full state, encoded for transport or merge. */
+    encodeState: () => CrdtState;
+    /**
+     * Fold another buffer's encoded state into this one. Concurrent edits
+     * converge — this is the CRDT property, applied in place.
+     */
+    applyState: (state: CrdtState) => void;
+}
+
+/** A local edit to sync: the encoded CRDT update for one cell. `update` is a
+ *  full-state-or-delta blob (a Yjs update is both), folded server-side. */
+export declare interface CrdtWritePayload extends CrdtDocKey {
+    readonly update: CrdtState;
+}
+
+/**
+ * Create a durable {@link PersistenceAdapter} over IndexedDB.
+ *
+ * @param options.factory the IndexedDB implementation. Defaults to the ambient
+ *   `globalThis.indexedDB`. Tests pass a fake; a worker/host can pass its own.
+ * @param options.databaseName the IDB database name. Default `"voltro-local-first"`.
+ *   Distinct apps on one origin should pass distinct names.
+ */
+export declare const createIndexedDbPersistence: (options?: {
+    readonly factory?: IndexedDbFactory;
+    readonly databaseName?: string;
+}) => Promise<PersistenceAdapter>;
+
+/**
+ * An in-memory {@link PersistenceAdapter} backed by Maps. Real, not a stub: it
+ * fully satisfies the contract, and copies bytes on the way in and out so a
+ * caller mutating a `Uint8Array` after saving cannot corrupt what was stored
+ * (a durable backing serialises, so this keeps the in-memory impl honest to the
+ * same isolation). Loses everything when the process ends — that is the ONLY
+ * thing the WASM/Turso seam adds over it.
+ */
+export declare const createInMemoryPersistence: () => PersistenceAdapter;
+
+/** Create a fresh shared bus. Pass it to two `createInMemoryPresenceChannel`
+ *  calls to model two peers over one broker. */
+export declare const createInMemoryPresenceBus: () => InMemoryPresenceBus;
+
+/**
+ * An in-memory {@link PresenceChannel} over a shared {@link InMemoryPresenceBus}.
+ * Real, not a stub: it fans a publish out to every OTHER handler on the room
+ * synchronously — the same delivery a broker gives, minus the network.
+ *
+ * A handler NEVER receives its own channel's publish (a broker's own-origin
+ * skip): otherwise a peer would see itself as an "other". Isolation is per
+ * channel instance, so one peer = one channel.
+ */
+export declare const createInMemoryPresenceChannel: (bus?: InMemoryPresenceBus) => PresenceChannel;
+
+/**
+ * Create a presence room over a {@link PresenceChannel}. Publishes an initial
+ * "join" immediately, so a peer already listening sees this one at once; on
+ * hearing from a peer it has not seen, it re-announces itself (announce-back) so
+ * mutual discovery holds without any central registry.
+ */
+export declare const createPresenceRoom: <TPresence>(options: PresenceRoomOptions<TPresence>) => PresenceRoom<TPresence>;
+
+/**
+ * Create a sync client over a {@link SyncTransport}.
+ *
+ * ```ts
+ * const client = createSyncClient({
+ *   transport: {
+ *     kind: 'sync-transport',
+ *     push: (w) => runMutation('documents.setBody', w.payload),   // useMutation
+ *     onRemoteState: (h) => subscribeRow('documents', (row) =>    // useSubscription
+ *       h({ table: 'documents', id: row.id, column: 'body', state: row.body })),
+ *   },
+ *   adapter: await someDurablePersistence(),   // optional
+ * })
+ * client.enqueue({ table: 'documents', id: 'd1', column: 'body', update })
+ * ```
+ */
+export declare const createSyncClient: (options: SyncClientOptions) => SyncClient;
+
+/** The plain-string view of an encoded CRDT state. */
+export declare const decodeCrdtText: (state: CrdtState, backend?: CrdtBackend) => string;
+
+/** The backend used when a call site does not pass one. Swap point for Loro. */
+export declare const defaultCrdtBackend: CrdtBackend;
+
+/**
+ * Derive the user-visible status. Offline wins (nothing can sync); otherwise
+ * `syncing` while writes are outstanding OR we are still confirming the server,
+ * else `synced`.
+ */
+export declare const deriveSyncStatus: (phase: ConnectionPhase, outstanding: number) => SyncStatus;
+
+/** The encoded empty state — the identity element for {@link mergeCrdtStates}. */
+export declare const emptyCrdtState: (backend?: CrdtBackend) => CrdtState;
+
+/** Either the built-in name or a custom resolver. */
+export declare type FieldPolicy<T = unknown> = 'lastWriteWins' | ConflictResolver<T>;
+
+/** A value tagged with when and by whom it was written — the input to a resolver. */
+export declare interface FieldValue<T = unknown> {
+    readonly value: T;
+    /** Wall-clock of the write (ms epoch). The primary ordering key. */
+    readonly updatedAt: number;
+    /** Stable writer identity (device/user id). Used ONLY to break exact ties, deterministically. */
+    readonly writer?: string;
+}
+
+declare interface IDBDatabaseLike {
+    transaction: (store: string, mode: 'readonly' | 'readwrite') => IDBTransactionLike;
+    objectStoreNames: {
+        contains: (name: string) => boolean;
+    };
+    createObjectStore: (name: string) => IDBObjectStoreLike;
+}
+
+declare interface IDBObjectStoreLike {
+    get: (key: string) => IDBRequestLike<unknown>;
+    put: (value: unknown, key: string) => IDBRequestLike<unknown>;
+    delete: (key: string) => IDBRequestLike<unknown>;
+}
+
+declare interface IDBOpenRequestLike extends IDBRequestLike<IDBDatabaseLike> {
+    onupgradeneeded: ((this: unknown, ev: unknown) => void) | null;
+}
+
+declare interface IDBRequestLike<T> {
+    result: T;
+    error: unknown;
+    onsuccess: ((this: unknown, ev: unknown) => void) | null;
+    onerror: ((this: unknown, ev: unknown) => void) | null;
+}
+
+declare interface IDBTransactionLike {
+    objectStore: (name: string) => IDBObjectStoreLike;
+}
+
+/**
+ * DONE — Durable persistence.
+ *   `createIndexedDbPersistence` (./persistence/indexedDb) is a durable
+ *   `PersistenceAdapter` over IndexedDB — no WASM, no added dependency, tested
+ *   against a fake IDB backend that survives a reopen. `createInMemoryPersistence`
+ *   remains the ephemeral default. REMAINING (optional): a wa-sqlite / Turso
+ *   adapter for cross-tab SQL, a sibling file behind the SAME interface + the
+ *   plan's LRU eviction. Nothing above the adapter changes when it lands.
+ *
+ * DONE — Bi-directional sync wire.
+ *   `createSyncClient` (./sync/syncClient) maps the pure sync-queue reducer onto
+ *   a `SyncTransport`: a local edit → optimistic merge + queued write; reconnect
+ *   → drain to `push`; incoming merged state → local CRDT merge; convergence.
+ *   Tested against an in-memory dispatcher that mirrors the server's
+ *   authoritative merge. REMAINING (runtime binding, NOT this package): supply
+ *   the two transport functions from a running app — `push` from the client's
+ *   mutation caller (`useMutation` / `resolveByTag` writing the `crdtText()`
+ *   column), `onRemoteState` from the reactive subscription that streams the row.
+ *
+ * DONE — Presence / awareness.
+ *   `createPresenceRoom` (./presence/room) + the `usePresence` hook implement
+ *   ephemeral awareness over a `PresenceChannel` — join/leave, announce-back
+ *   discovery, cursor propagation, TTL expiry. Tested over the in-memory channel
+ *   (`createInMemoryPresenceChannel`), which is the SAME dumb string-payload
+ *   shape as the framework's `BroadcastProvider`. REMAINING (runtime binding):
+ *   a `PresenceChannel` that forwards onto the app's provisioned broker
+ *   (in-memory locally; Redis / NATS at scale — both already shipped in
+ *   `@voltro/plugin-broadcast`). That is a network hop, not new logic.
+ *
+ * DONE — localFirst mixin + discovery.
+ *   `localFirst()` (`@voltro/database`) marks a table; the runtime SchemaRegistry
+ *   reflects it as `hasLocalFirst(table)` (alongside `crdtColumns(table)`) — the
+ *   discovery surface, with NO codegen change (a marker mixin rides `.with()`
+ *   like any column type). `crdtText()` was already a real column type with an
+ *   authoritative server merge on the write path.
+ */
+export declare const IMPLEMENTED_SINCE_SEAMS: readonly ["durable-persistence-indexeddb", "sync-transport-syncclient", "presence-room", "localFirst-mixin-discovery"];
+
+export declare type ImplementedSeam = (typeof IMPLEMENTED_SINCE_SEAMS)[number];
+
+export declare interface IndexedDbFactory {
+    open: (name: string, version?: number) => IDBOpenRequestLike;
+}
+
+export declare const initialConnection: (phase?: ConnectionPhase) => ConnectionState;
+
+/** A fresh, empty queue. `online` defaults to `true`. */
+export declare const initialSyncQueue: <T = unknown>(online?: boolean) => SyncQueueState<T>;
+
+/** A shared in-process fan-out bus. Two channels built over the SAME bus see
+ *  each other's publishes — the presence analogue of `memoryProvider`'s named
+ *  bus, which is what lets a test model two independent peers on one broker. */
+export declare interface InMemoryPresenceBus {
+    readonly rooms: Map<string, Set<(payload: string) => void>>;
+}
+
+/**
+ * Last-write-wins: newer `updatedAt` wins; exact ties break on the (stable,
+ * symmetric) tiebreak key so both peers converge on the same value.
+ */
+export declare const lastWriteWins: ConflictResolver;
+
+/**
+ * Rehydrate a {@link PersistedSyncQueue} from an adapter. Any writes the adapter
+ * has (from a prior session) come back as `pending`, oldest first, so a client
+ * that went offline, queued writes, and closed picks them up on next launch.
+ *
+ * @param online seeds the connection belief (default `true`). A client that
+ *   knows it starts offline passes `false` so `canDrain` stays shut until an
+ *   `online` action arrives.
+ */
+export declare const loadPersistedSyncQueue: <T = unknown>(adapter: PersistenceAdapter, online?: boolean) => Promise<PersistedSyncQueue<T>>;
+
+/**
+ * The heart of the package: converge two encoded CRDT states into one.
+ *
+ * Deterministic and order-independent up to the resulting text
+ * (`decodeCrdtText(mergeCrdtStates(a, b))` equals the same for `(b, a)`),
+ * idempotent (re-merging a state already contained is a no-op on the text), and
+ * treats {@link CrdtBackend.emptyState} as identity.
+ */
+export declare const mergeCrdtStates: (a: CrdtState, b: CrdtState, backend?: CrdtBackend) => CrdtState;
+
+/** Total outstanding writes (pending + the one in flight). 0 means fully synced. */
+export declare const outstandingCount: (state: SyncQueueState) => number;
+
+/** A sync queue whose every transition is persisted through an adapter. */
+export declare interface PersistedSyncQueue<T = unknown> {
+    /** The current in-memory queue state. */
+    getState: () => SyncQueueState<T>;
+    /**
+     * Apply an action with the pure reducer, persist the new outstanding set, and
+     * resolve with the new state. Persistence happens before the promise resolves,
+     * so an `await`ed dispatch guarantees the write survived.
+     */
+    dispatch: (action: SyncQueueAction<T>) => Promise<SyncQueueState<T>>;
+}
+
+/**
+ * Durable local storage for a local-first client. Every method is async because
+ * the real backings (WASM SQLite, Turso, IndexedDB) are — the in-memory impl
+ * resolves immediately but keeps the same shape so tests exercise the real
+ * contract, not a synchronous shortcut.
+ */
+export declare interface PersistenceAdapter {
+    /** Identifies the backing, e.g. `"in-memory"` / `"wa-sqlite"`. Diagnostics. */
+    readonly kind: string;
+    /** The stored CRDT state for a record, or `undefined` if none is persisted. */
+    loadCrdtState: (table: string, id: string) => Promise<CrdtState | undefined>;
+    /** Persist a record's CRDT state, replacing any prior value. */
+    saveCrdtState: (table: string, id: string, state: CrdtState) => Promise<void>;
+    /** The persisted offline write queue (oldest first). Empty when none saved. */
+    loadQueue: () => Promise<readonly QueuedWrite[]>;
+    /** Persist the entire offline write queue, replacing the prior snapshot. */
+    saveQueue: (writes: readonly QueuedWrite[]) => Promise<void>;
+    /** Mark a record as never-evict (the plan's "pinned" records). */
+    pin: (table: string, id: string) => Promise<void>;
+    /** Whether a record is pinned. */
+    isPinned: (table: string, id: string) => Promise<boolean>;
+}
+
+/**
+ * A dumb ephemeral pub/sub channel. Publish a string payload to a room;
+ * subscribe to a room and get every payload (from other peers) back.
+ *
+ * Mirrors `BroadcastProvider` so a runtime adapter can forward straight onto the
+ * app's broker. `publish` is fire-and-forget (presence loss is tolerable — the
+ * next heartbeat corrects it); `subscribe` returns its unsubscribe.
+ */
+export declare interface PresenceChannel {
+    readonly kind: 'presence-channel';
+    readonly publish: (room: string, payload: string) => void;
+    readonly subscribe: (room: string, handler: (payload: string) => void) => () => void;
+}
+
+/** One other peer's last-known presence. */
+export declare interface PresencePeer<TPresence> {
+    readonly peerId: string;
+    readonly presence: TPresence;
+    /** Clock value of the last message seen from this peer (for TTL expiry). */
+    readonly lastSeen: number;
+}
+
+export declare interface PresenceRoom<TPresence> {
+    /** This peer's current presence. */
+    readonly self: () => TPresence;
+    /** Every OTHER live peer, newest-message-first is NOT guaranteed — order is
+     *  insertion. Expired peers are excluded once `sweep()` has run. */
+    readonly others: () => readonly PresencePeer<TPresence>[];
+    /** Replace this peer's presence and publish it. */
+    readonly update: (presence: TPresence) => void;
+    /** Re-publish current presence (drives keep-alive; call on an interval). */
+    readonly heartbeat: () => void;
+    /** Drop peers whose last message is older than `ttlMs`. Call on an interval. */
+    readonly sweep: () => void;
+    /** Subscribe to any change (a peer joined/updated/left, or self changed). */
+    readonly onChange: (listener: () => void) => () => void;
+    /** Announce departure and stop listening. Idempotent. */
+    readonly leave: () => void;
+}
+
+export declare interface PresenceRoomOptions<TPresence> {
+    readonly channel: PresenceChannel;
+    readonly roomId: string;
+    /** Unique id for THIS peer/connection. Two tabs of one user are two peers. */
+    readonly peerId: string;
+    readonly initial: TPresence;
+    /** A peer with no message in this many ms is considered gone. Default 30_000. */
+    readonly ttlMs?: number;
+    /** Injectable clock. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+
+/** A single queued write. `payload` is opaque to the queue — the wire seam owns its shape. */
+export declare interface QueuedWrite<T = unknown> {
+    readonly id: string;
+    readonly payload: T;
+    /** When the write was first enqueued (ms epoch). Set by the caller for determinism. */
+    readonly enqueuedAt: number;
+    /** How many times delivery has been attempted and failed. 0 until the first `fail`. */
+    readonly attempts: number;
+}
+
+/** Merged authoritative state for one cell, delivered back from the server. */
+export declare interface RemoteCrdtState extends CrdtDocKey {
+    readonly state: CrdtState;
+}
+
+/**
+ * The genuinely REMAINING runtime seams — provisioned infra + the thin app-level
+ * binding to it, not un-built framework code:
+ *   - a `SyncTransport` bound to a specific running app's mutation/subscription
+ *   - a `PresenceChannel` bound to a provisioned Redis/NATS broker at scale
+ *   - (optional) a wa-sqlite/Turso durable adapter for cross-tab SQL
+ */
+export declare const RUNTIME_SEAMS: readonly ["sync-transport-app-binding", "presence-broker-binding", "wasm-sqlite-durable-adapter"];
+
+export declare type RuntimeSeam = (typeof RUNTIME_SEAMS)[number];
+
+export declare interface SyncClient {
+    /** Apply a local edit: merge it into local state immediately (optimistic),
+     *  persist, queue it, and start draining if online. */
+    readonly enqueue: (payload: CrdtWritePayload) => void;
+    /** Report reachability. Going online kicks the drain loop. */
+    readonly setOnline: (online: boolean) => void;
+    /** Current queue state (pending + in-flight). */
+    readonly queueState: () => SyncQueueState<CrdtWritePayload>;
+    /** Outstanding writes; 0 means fully synced. */
+    readonly outstanding: () => number;
+    /** The current merged local state for a cell, or undefined if none. */
+    readonly getState: (key: CrdtDocKey) => CrdtState | undefined;
+    /** The plain-text view of a cell's merged state (empty string if none). */
+    readonly getText: (key: CrdtDocKey) => string;
+    /** Subscribe to any local change (a local edit, an acked write, or incoming
+     *  remote state). Returns an unsubscribe. */
+    readonly subscribe: (listener: () => void) => () => void;
+    /** Drain the queue to quiescence and resolve — the test/await seam. Resolves
+     *  when nothing more can be drained (synced, offline, or all writes gave up). */
+    readonly flush: () => Promise<void>;
+    /** Tear down the transport subscription. */
+    readonly close: () => void;
+}
+
+export declare interface SyncClientOptions {
+    readonly transport: SyncTransport;
+    /** Durable local storage. When present, local CRDT state + the queue survive
+     *  a reload. Omit for an ephemeral (in-memory) client. */
+    readonly adapter?: PersistenceAdapter;
+    /** CRDT backend for the local optimistic merge. Defaults to Yjs. */
+    readonly backend?: CrdtBackend;
+    /** Seed the connection belief (default `true`). `false` holds the queue shut
+     *  until `setOnline(true)`. */
+    readonly online?: boolean;
+    /** Injectable clock for deterministic `enqueuedAt`. Defaults to `Date.now`. */
+    readonly now?: () => number;
+    /** Stop re-driving a write after this many failed attempts (it stays queued,
+     *  head-of-line, for the next `setOnline`/`enqueue` to retry). Default 5. */
+    readonly maxAttempts?: number;
+}
+
+export declare type SyncQueueAction<T = unknown> = 
+/** Queue a new write at the tail. */
+    {
+    readonly type: 'enqueue';
+    readonly write: QueuedWrite<T>;
+}
+/** Network/reachability came back. */
+| {
+    readonly type: 'online';
+}
+/** Network/reachability went away. An in-flight write returns to the front. */
+| {
+    readonly type: 'offline';
+}
+/** Move the head into `inFlight` so the transport can deliver it. */
+| {
+    readonly type: 'drain-start';
+}
+/** The in-flight write (matched by id) was delivered. */
+| {
+    readonly type: 'ack';
+    readonly id: string;
+}
+/** The in-flight write (matched by id) failed; it returns to the front, attempts+1. */
+| {
+    readonly type: 'fail';
+    readonly id: string;
+    readonly error: string;
+};
+
+export declare const syncQueueReducer: <T>(state: SyncQueueState<T>, action: SyncQueueAction<T>) => SyncQueueState<T>;
+
+export declare interface SyncQueueState<T = unknown> {
+    /** Whether the queue believes it can reach the server. Drives draining. */
+    readonly online: boolean;
+    /** Writes waiting to be sent, oldest first. */
+    readonly pending: readonly QueuedWrite<T>[];
+    /** The write currently being delivered, if any. Only one at a time (in-order delivery). */
+    readonly inFlight: QueuedWrite<T> | undefined;
+    /** Last delivery error message, if the most recent attempt failed. */
+    readonly lastError: string | undefined;
+}
+
+/** What an offline indicator shows: a join of network phase and queue depth. */
+export declare type SyncStatus = 'offline' | 'syncing' | 'synced';
+
+/**
+ * The transport the {@link SyncClient} rides. Two functions the framework binds
+ * to its EXISTING wire:
+ *
+ *  - `push` — deliver a queued CRDT write to the server. Bound to a mutation
+ *    that writes the `crdtText()` column (the runtime's MutationStore folds it
+ *    with `mergeCrdtColumnsIntoPatch`). Rejects to trigger the queue's retry.
+ *  - `onRemoteState` — receive merged state pushed from the server. Bound to
+ *    the reactive subscription that already streams the row. Returns an
+ *    unsubscribe.
+ *
+ * In tests it is an in-memory dispatcher that merges + broadcasts, exercising
+ * the exact convergence contract without a network.
+ */
+export declare interface SyncTransport {
+    readonly kind: 'sync-transport';
+    readonly push: (write: QueuedWrite<CrdtWritePayload>) => Promise<void>;
+    readonly onRemoteState: (handler: (remote: RemoteCrdtState) => void) => () => void;
+}
+
+/** A record's fields, each carrying its version metadata. */
+export declare type VersionedRecord = Record<string, FieldValue>;
+
+export declare const yjsBackend: CrdtBackend;
+
+export { }