@pylonsync/sync 0.3.292 → 0.3.293

package/dist/index.d.ts

@@ -0,0 +1,949 @@
+import { LocalStore } from "./local-store";
+import { MutationQueue } from "./mutation-queue";
+import { type RoomError, type RoomMember, type RoomSubscriber } from "./room-subscriptions";
+import { SessionResolver } from "./session-resolver";
+export { RoomSubscriptions, type RoomError, type RoomErrorCode, type RoomMember, type RoomMessage, type RoomMessageSubscriber, type RoomSubscriber, } from "./room-subscriptions";
+export { IndexedDBPersistence, persistChange } from "./persistence";
+export { buildRequest, pylonFetch, pylonFetchRaw, PylonHttpError, resolveBaseUrl, } from "./transport";
+export type { PylonRequestInit, TransportConfig } from "./transport";
+export { LocalStore } from "./local-store";
+export { MutationQueue, type MutationQueuePersistence, type PendingMutation, } from "./mutation-queue";
+export { generateId } from "./ids";
+export type { ChangeEvent, ClientChange, PullResponse, PushOpResult, PushResponse, ReactiveMessage, ReactiveSpec, ResolvedSession, Row, SyncConnectionStatus, SyncCursor, TransportType, } from "./types";
+export { defaultStorage, createWriteThroughStorage, type Storage, } from "./storage";
+import type { ReactiveMessage, ResolvedSession, Row, SyncConnectionStatus, SyncCursor, TransportType } from "./types";
+export interface SyncEngineConfig {
+    baseUrl: string;
+    /** Transport type. Default: "websocket". Falls back to polling if connection fails. */
+    transport?: TransportType;
+    /** WebSocket URL. Default: derived from baseUrl (ws://). */
+    wsUrl?: string;
+    /** Poll interval in ms (only used when transport is "poll"). Default 1000. */
+    pollInterval?: number;
+    /** Reconnect delay in ms. Default 1000. */
+    reconnectDelay?: number;
+    /** Auth token for requests. */
+    token?: string;
+    /** Enable IndexedDB persistence. Data survives page refresh. Default: true in browser. */
+    persist?: boolean;
+    /** App name for IndexedDB database naming. Default: "default". */
+    appName?: string;
+    /**
+     * Sync key-value adapter for hot-path state (auth token, client_id).
+     * Default: localStorage on the web, in-memory no-op elsewhere. Non-browser
+     * hosts (RN, Tauri, Workers) inject an adapter to persist these values.
+     */
+    storage?: import("./storage").Storage;
+    /**
+     * Debounce window (ms) between `reconcile()` calls. Reconcile triggers
+     * fire on connect, WS reconnect, and visibility-change; the debounce
+     * prevents the back-to-back triggers from re-fetching every entity
+     * twice within seconds. Default 2000ms.
+     */
+    reconcileMinIntervalMs?: number;
+    /**
+     * Opt out of the automatic visibility-change reconcile. The reconcile
+     * pass runs on connect/reconnect regardless; this only disables the
+     * tab-refocus trigger. Default: enabled (reconcile fires when the tab
+     * becomes visible).
+     */
+    reconcileOnVisibility?: boolean;
+    /**
+     * Client → server keepalive interval (ms). The Pylon dev server's
+     * dedicated :port+1 WS listener uses a dual-thread design where the
+     * writer thread wakes on every broadcast — pings are pure liveness,
+     * 25_000 (25s) is the right default. The HTTP-multiplexed
+     * `/api/sync/ws` fallback path uses a single-thread design where
+     * the reader's mutex unlocks only between reads; on THAT path,
+     * broadcast latency is bounded by this interval, so set it lower
+     * (e.g. 200) to trade traffic for delivery latency. Most production
+     * deployments should leave this at the default and configure their
+     * edge proxy to forward to the dual-thread listener instead.
+     */
+    pingIntervalMs?: number;
+    /**
+     * Multi-tab coordination via BroadcastChannel. When multiple tabs of
+     * the same origin run the engine, one is elected leader and owns
+     * the WebSocket, pull/push/reconcile, and IndexedDB writes;
+     * follower tabs mirror state via cross-tab broadcasts. Default
+     * `true` in browsers. Set `false` to force every tab to behave as
+     * its own leader (the pre-multi-tab semantics).
+     */
+    multiTab?: boolean;
+}
+/**
+ * Generate a stable client_id. Prefers a persisted id from `storage`
+ * (so a reload keeps the same identifier) and falls back to a fresh UUID.
+ */
+/**
+ * Generate a Pylon-shaped row id (40-char lowercase hex).
+ *
+ * Mirrors the runtime's `generate_id` shape: 32 hex of milliseconds
+ * since epoch (extended to nanos so it lex-sorts alongside server-
+ * generated ids) + 8 hex of a per-tab counter. Lex-sortable, monotonic
+ * within a tab, statistically unique across tabs (the timestamp
+ * disambiguates almost every cross-tab collision; the counter handles
+ * the rest within a single tick).
+ *
+ * Used by `useMutation({ optimistic })` to mint client-side ids that
+ * the runtime will accept verbatim — so the optimistic ghost and the
+ * canonical row share the same `row_id` and the WS broadcast is an
+ * idempotent merge instead of a delete-then-replace flash.
+ *
+ * Apps can call this directly when they need a stable id earlier than
+ * the mutation (e.g. to reference the row from another optimistic
+ * insert in the same gesture).
+ */
+export declare class SyncEngine {
+    private config;
+    private cursor;
+    private running;
+    /** Real-time transport — owns its own socket / timers / backoff.
+     *  The engine just calls start/stop/send and consumes inbound events
+     *  via the TransportHost callbacks (set up below in `transportHost`).
+     *  Constructed in start() because followers don't open a transport
+     *  at all and SSR-only consumers never reach start(). */
+    private transport;
+    private _connectionStatus;
+    private persistence;
+    /**
+     * Flips true once `start()` has either:
+     *   - drained IndexedDB into the in-memory store (data path), OR
+     *   - decided the engine has no persistence layer (test / SSR / explicit opt-out).
+     *
+     * `useQuery`'s `loading` flag consumes this so apps don't render a
+     * "Loading…" flash on every page refresh when the disk replica
+     * already has the data. Without it, even returning visits show the
+     * spinner for the 50–200ms gap between component mount and IndexedDB
+     * `loadAllEntities()` resolving — visually identical to a true
+     * cold-start fetch.
+     */
+    private _hydrated;
+    isHydrated(): boolean;
+    /**
+     * True once the engine has a *server-confirmed* initial view: the first
+     * pull (snapshot) settled, OR the IndexedDB cache already held rows, OR a
+     * fallback deadline elapsed so we never pin forever. This is what
+     * `useQuery`'s `loading` waits on — NOT `isHydrated()`. The distinction
+     * matters: `isHydrated()` flips true the instant the local cache loads,
+     * which on a cold/empty cache (first visit, or right after an org switch
+     * wipes the replica) is immediate and EMPTY — so a `loading` gated on it
+     * drops to false while the projects/rows are still en route from the
+     * server, and the UI flashes its empty state for the ~seconds until the
+     * pull lands. Gating on this signal keeps `loading` true through that
+     * window so callers can show a skeleton instead.
+     */
+    private _initialSyncSettled;
+    isInitialSyncSettled(): boolean;
+    private _initialSyncFallback;
+    /** Flip `_initialSyncSettled` true (idempotent) + notify so `useQuery`
+     *  re-reads and drops its loading state. */
+    private markInitialSyncSettled;
+    /** Safety net so `loading` never pins: settle after a deadline even if no
+     *  pull lands (offline, or a multi-tab follower of an empty entity that
+     *  never receives a broadcast). The real pull settles it far sooner in the
+     *  normal case. Re-armable — a replica wipe (org switch / token flip) resets
+     *  the signal and re-arms this. */
+    private armInitialSyncFallback;
+    /**
+     * True when the engine drained at least one row OR a saved cursor
+     * out of IndexedDB during `start()`. Distinguishes a returning user
+     * (cached replica may contain rows the server has since deleted) from
+     * a true first-time user (cache empty, pull-from-0 IS canonical
+     * truth).
+     *
+     * Used by the WS `onConnected` fast-path: `lastPullStartedFromZero`
+     * only fires the reconcile-skip when this flag is ALSO false. A
+     * returning user whose IDB cursor somehow rolled back to 0 (rare:
+     * partial wipe, corrupt write) must still get the reconcile pass —
+     * otherwise rows deleted on the server while the tab was closed
+     * survive forever.
+     *
+     * Read-only after start() observes the IDB load.
+     */
+    private _hadCachedReplica;
+    /**
+     * Sticky flag: a persisted row/cursor write degraded (IDB quota /
+     * abort), so the on-disk replica is known to be behind the in-memory
+     * cursor. Once set, `enqueueApply` STOPS advancing the persisted
+     * cursor — persisting a cursor ahead of the durable rows would make
+     * the next cold start skip them forever (cursor-ahead-of-replica). The
+     * in-memory replica stays authoritative for the live session; on
+     * restart the lagging on-disk cursor simply re-pulls the gap. Resets to
+     * false only on `resetReplicaInner` (full wipe + resync, disk is clean
+     * again). A storage-pressured tab thus degrades to "re-pull on restart"
+     * — like a memory-only client — instead of silently losing rows.
+     */
+    private persistDegraded;
+    readonly store: LocalStore;
+    readonly mutations: MutationQueue;
+    /**
+     * Stable per-client identifier. Minted on first construction, not
+     * necessarily persisted (depends on what the host provides).
+     * Included on every PushRequest so the server can correlate retries and
+     * track per-client diagnostics. Not auth — do not trust this to identify
+     * a user.
+     */
+    readonly clientId: string;
+    /** Presence state for this client. */
+    private presenceData;
+    /**
+     * Token observed on the last pull. When the token changes (anonymous →
+     * signed in, or user A → user B), the set of rows the server will expose
+     * changes — so the cursor from the previous identity is meaningless.
+     * Compared on every pull; a mismatch triggers an automatic resync.
+     *
+     * Owns the resolved session, the last-seen token, the last-seen
+     * tenant, and the null→X / X→Y / token-flip verdicts that used to
+     * be inlined across pull / refresh / reconcile. The engine acts on
+     * the verdicts (reset, pull, notify); the resolver decides nothing
+     * on its own. See session-resolver.ts.
+     *
+     * Exposed (read-only) so tests and plugins can inspect or simulate
+     * identity transitions without re-implementing the comparison.
+     */
+    readonly session: SessionResolver;
+    /**
+     * Multi-tab orchestrator — owns the cross-tab protocol: broker
+     * lifecycle, election, inbound message dispatch, outbound broadcasts.
+     * Engine receives inbound events via hooks (see `multiTabHooks()`).
+     *
+     * Constructed lazily in `start()` because SSR-only consumers that
+     * never reach start() shouldn't pay for the broker. */
+    private orchestrator;
+    /** Mirror of `orchestrator.isLeader()` kept on the engine for the
+     *  many `if (this.isMultiTabLeader)` gates throughout the codebase.
+     *  Updated via the orchestrator's onInitialLeader / onLatePromote /
+     *  onDemote hooks. Defaults to false so a tab joining an existing
+     *  election stays a passive follower until the orchestrator
+     *  explicitly promotes us — a `true` default would let a late
+     *  joiner whose orchestrator never fires onPromote (because it was
+     *  never leader) silently run as a leader. */
+    private isMultiTabLeader;
+    /**
+     * Serialized apply queue. Every change-event apply — from WS onmessage,
+     * pull(), or session-changed catchup — chains onto this promise so
+     * applies execute in arrival order. Without this, two WS messages or
+     * two concurrent pull()s race: seq 3's persistence can land before
+     * seq 2's, leaving the row at the older value AND the cursor briefly
+     * regressing if writes complete out of order. The queue also gates
+     * the cursor advance so `last_seq` only moves forward.
+     */
+    private applyQueue;
+    /**
+     * Live-event hold buffer, active ONLY while a from-zero snapshot pull is in
+     * flight. A snapshot is full state as-of `snapshot_seq` S; its rows arrive
+     * tagged `seq = S`. If a live WS frame (or a tab broadcast) at `seq = S+k`
+     * applies FIRST — during the snapshot's (possibly multi-page) HTTP fetch — it
+     * advances the cursor past S, and then EVERY snapshot row (seq ≤ S) is
+     * dropped by the monotonic filter in enqueueApply, leaving a near-empty
+     * replica with the cursor persisted ahead (no 410, no heal until a reconcile
+     * happens to fire). The store has no per-row seq guard, so we can't just
+     * apply the snapshot unconditionally — an older snapshot row would clobber a
+     * newer live update. So we instead ORDER them: hold live/broadcast applies
+     * here while snapshotting, then replay them (seq-filtered) AFTER the snapshot
+     * lands. null = not snapshotting → normal apply.
+     */
+    private snapshotHold;
+    /**
+     * Serialized channel for outbound network ops (pull, push, reconcile,
+     * refresh, resetReplica). Replaces the per-op `inFlightX` mutexes +
+     * the fire-and-forget `void refreshResolvedSession()` calls that used
+     * to race against in-flight pulls and reconciles. Apply stays
+     * separate (see `applyQueue` above) so WS events don't block on a
+     * pull's HTTP round-trip.
+     */
+    private opQueue;
+    /**
+     * Serialized chain for session-transition application. Multiple
+     * concurrent triggers (`refreshResolvedSession` from app code +
+     * a `session-changed` envelope landing over WS + a multi-tab
+     * `session` broadcast) all enqueue here. Without it, two
+     * inspect-then-commit pairs interleave on the microtask queue
+     * and the older session can commit AFTER the newer, leaving the
+     * engine pinned to a stale tenant.
+     */
+    private sessionChain;
+    /**
+     * Registered consumers for binary WebSocket frames. SyncEngine itself
+     * doesn't decode binary — it just owns the WS connection and routes
+     * frames to whoever signed up via [`onBinaryFrame`]. The first
+     * consumer is `@pylonsync/loro` for CRDT snapshots / updates;
+     * future binary use cases (file streaming, etc.) register the same
+     * way so this layer stays use-case-agnostic.
+     *
+     * Set rather than Array so a hot-reload re-registration of the same
+     * handler doesn't double-invoke. Caller-provided handler identity
+     * is the dedup key.
+     */
+    private binaryHandlers;
+    /**
+     * Server-side ephemeral subscriptions (CRDT row subs, reactive query
+     * subs, future kinds). Owns the WS replay bookkeeping — each kind
+     * registers the message that re-creates its server-side state, and
+     * `ws.onopen` replays the bundle on reconnect. Kind-specific concerns
+     * (CRDT refcount, reactive handler routing) stay below as their own
+     * maps. See server-subscriptions.ts.
+     */
+    private serverSubs;
+    /** Coordinator for every "this tab wants live updates" subscription —
+     *  CRDT row subs + reactive query subs, leader bookkeeping + follower
+     *  forwarding. The engine delegates `subscribeCrdt` / `unsubscribeCrdt`
+     *  / `subscribeReactive` / `unsubscribeReactive` to it, and routes
+     *  inbound multi-tab `sub-register` / `sub-unregister` / `reactive-msg`
+     *  envelopes through it. Constructed lazily in start() because
+     *  serverSubs isn't built until then. */
+    private subscriptions;
+    /** Room presence subscriptions. Replaces the per-component
+     *  setInterval(GET /api/rooms/<room>, 5s) polling loop the `useRoom`
+     *  hook used to run for every channel. New server protocol
+     *  (v0.3.214+): the client sends `room-subscribe` / `room-unsubscribe`
+     *  over the existing WS, and the server pushes `room-snapshot` /
+     *  `room-update` whenever membership changes.
+     *
+     *  This engine field is leader-only (followers forward register /
+     *  unregister calls over the multi-tab channel — the leader's
+     *  registry is the single source of truth on the wire). Constructed
+     *  lazily in start() so SSR-only callers don't pay for it. */
+    private rooms;
+    /** Per-room set of follower tabIds that have forwarded a
+     *  `room-sub-register`. Leader-only. Mirrors `crdtForwarders` in the
+     *  SubscriptionCoordinator — the WS room sub stays alive until both
+     *  the local refcount AND this set are empty. A separate map on the
+     *  engine (instead of inside RoomSubscriptions) because the registry
+     *  is leader-local and forwarder bookkeeping is multi-tab specific. */
+    private roomForwarders;
+    /**
+     * Listeners notified when the server signals a per-subscriber row
+     * revocation (`row-revoked` envelope). Used by `@pylonsync/loro`
+     * to evict the LoroDoc registry entry for a row whose policy was
+     * revoked mid-session. Plain Set so identity is the dedup key.
+     */
+    private rowEvictionListeners;
+    /**
+     * Register a binary-frame handler. Returns an unsubscribe fn that
+     * pulls the handler back out — call on hook unmount / module
+     * teardown so handlers don't leak.
+     *
+     * Multiple handlers can register concurrently; each gets called for
+     * every binary frame the WS receives. Handlers should be cheap and
+     * non-throwing — exceptions are caught and logged but the message
+     * is otherwise dropped for that handler.
+     */
+    onBinaryFrame(handler: (bytes: Uint8Array) => void): () => void;
+    /** Read the cached resolved session. Null user = anonymous. */
+    resolvedSession(): ResolvedSession;
+    /**
+     * Coarse connection state (see `SyncConnectionStatus`). Updated as
+     * the WS opens/closes and reconnect attempts run; subscribers re-
+     * render via the same store notify channel as live queries, so
+     * `useSyncStatus` is just a thin reader.
+     */
+    connectionStatus(): SyncConnectionStatus;
+    /**
+     * Mutate connection status + notify subscribers. Idempotent — same-
+     * status calls are a no-op so the WS onopen → connected transition
+     * doesn't spam re-renders during a stable connection.
+     */
+    private setConnectionStatus;
+    /** Sync key-value adapter for hot-path state (token, client_id). */
+    readonly storage: import("./storage").Storage;
+    constructor(config: SyncEngineConfig);
+    /**
+     * Hydrate the local store with server-rendered data.
+     * Call this before start() to avoid a redundant initial pull.
+     * Typically used for SSR: server fetches data + cursor, passes to client.
+     */
+    hydrate(data: HydrationData): void;
+    /** Start the sync engine. Loads persisted data, pulls updates, then connects for real-time. */
+    start(): Promise<void>;
+    /**
+     * Multi-tab election. Brings up the orchestrator and runs the
+     * initial election. Sets `isMultiTabLeader` via the orchestrator's
+     * hooks (onInitialLeader / onLatePromote / onDemote).
+     *
+     * On platforms without BroadcastChannel (Node, jsdom, very old
+     * Safari) the orchestrator declares self leader and returns
+     * immediately.
+     */
+    private initMultiTab;
+    /** Hooks the orchestrator calls back into for inbound multi-tab
+     *  events that need engine state. Cases that only touch
+     *  subscriptions are dispatched directly by the orchestrator. */
+    private multiTabHooks;
+    /** Leader-side hold tokens for room subs forwarded by followers. The
+     *  leader subscribes via its own registry with a no-op callback so
+     *  the registry's first-add gate ships `room-subscribe` exactly
+     *  once; the release tokens here let us undo that hold when the
+     *  last follower stops caring. */
+    private leaderForwarderHolds;
+    /** Seed serverSubs with every subscription this tab currently wants.
+     *  Called from both the initial-leader path (subscribes that
+     *  happened before start() took the follower branch and broadcast
+     *  to a not-yet-running broker, so the registers were lost) and the
+     *  late-promotion path (the previous leader owned the subs and we
+     *  need to claim them). */
+    private seedServerSubsFromLocalInterest;
+    /** Late promotion: the previous leader dropped while we were
+     *  running as a follower. Take over network ops now AND drain any
+     *  pending mutations through push() — a mutation we'd forwarded to
+     *  the previous leader may have died with it before the server
+     *  acked, and we need to ship it ourselves. op_id makes the
+     *  server-side retry idempotent: a previously-applied op returns
+     *  `replayed` and we just mark it applied locally. */
+    private onMultiTabPromoted;
+    /** Demotion: another tab took over as leader. Tear down our
+     *  transport (WS socket, ping timer, reconnect timer, poll timer —
+     *  whichever applies) and stop driving network ops; the new leader
+     *  will broadcast applied changes that our followers-mirror path
+     *  picks up. */
+    private onMultiTabDemoted;
+    /** Broadcast a payload to other tabs in this origin. Delegates to
+     *  the orchestrator; no-op when the orchestrator isn't running
+     *  (SSR-only consumers that never reach `start()`). */
+    private broadcastToTabs;
+    private visibilityHandler;
+    private attachVisibilityListener;
+    /**
+     * Serialize a batch of change applies behind any in-flight applies, and
+     * advance the cursor monotonically when the batch lands. Both the WS
+     * onmessage path and pull() funnel through here so seq 3's persistence
+     * can't race ahead of seq 2's. The returned promise resolves after
+     * THIS batch is applied (not after later batches), so a caller awaiting
+     * pull() still completes deterministically.
+     *
+     * Per-event monotonic filter: re-applies of an already-seen seq are
+     * skipped before touching the store. Without that, a retransmit
+     * (WS + pull window overlap) would have us run applyChange twice
+     * against the local store.
+     */
+    private enqueueApply;
+    /**
+     * Reconcile path. Routes through the same applyQueue as WS/pull so
+     * a reconcile batch can't interleave with a fresher change event
+     * mid-apply — but reconcile carries no real seqs, so the seq filter
+     * and cursor advance from `enqueueApply` are deliberately absent.
+     * Pending mutations are protected upstream (in applyEntityReconcile)
+     * before the batch is ever built.
+     */
+    private enqueueReconcile;
+    /** Stop the sync engine. */
+    stop(): void;
+    /**
+     * Drop local cursor + store + notify. Safe to call from any state.
+     * Used by:
+     *  - the 410 RESYNC_REQUIRED handler (server says our cursor is stale)
+     *  - the identity-change detector in pull() (new auth = new visible set)
+     *  - callers that need to force a clean re-pull (tests, sign-out flows)
+     *
+     * Does NOT issue the subsequent pull — callers decide when to re-pull.
+     * That keeps the lifecycle explicit: a caller can reset, swap config,
+     * then pull.
+     *
+     * Clears IndexedDB too. Without that, locals that should have been
+     * deleted server-side (e.g. another client deleted rows while this tab
+     * was closed, then this tab's cursor 410'd) survived on disk and got
+     * rehydrated on the next page load — phantom rows that no purge of
+     * in-memory state could fix.
+     */
+    resetReplica(opts?: {
+        wipeMutations?: boolean;
+    }): Promise<void>;
+    /**
+     * Drop the local replica and pull fresh. `wipeMutations` decides the
+     * fate of the durable offline write queue:
+     * - `false` (default, 410 RESYNC, SAME user): KEEP pending writes —
+     *   they survive the snapshot refresh and re-push under the same
+     *   session.
+     * - `true` (token/tenant flip, DIFFERENT identity): DROP them — the
+     *   queued writes belong to the outgoing identity and must never be
+     *   replayed as the incoming one (cross-identity write leak).
+     */
+    private resetReplicaInner;
+    /**
+     * localStorage key for the auth token, namespaced by appName. Matches
+     * the key the React package's `configureClient` writes to so the sync
+     * engine and the hooks agree on where the token lives.
+     */
+    private tokenStorageKey;
+    /** Current auth token from config or the storage adapter. Null when neither has one. */
+    private currentToken;
+    /**
+     * Call a Pylon Action / Mutation by name.
+     *
+     * Wraps `POST /api/fn/<name>` with the engine's bearer/cookie auth
+     * AND observes the `X-Pylon-Change-Seq` response header. If the
+     * server reports the action generated change events that the local
+     * replica hasn't seen yet, the engine immediately fires a one-shot
+     * pull — closing the latency window between the HTTP response
+     * landing here and the WS broadcast of the same events arriving.
+     *
+     * App code that uses this method no longer needs the
+     * "after-mutation refetch()" workaround pattern (see pylon-cloud's
+     * domains/page.tsx, pre-2026-05-17, which called refetch() four
+     * times for exactly this reason).
+     *
+     * Throws (`Error & {status, code?}`) on non-2xx with the server's
+     * error envelope. Returns the parsed JSON response.
+     */
+    fn<T = unknown>(name: string, args?: unknown): Promise<T>;
+    /** Shared by `fn()` and any future entity-mutation wrappers. POSTs
+     *  through the central transport, observes `X-Pylon-Change-Seq`,
+     *  and triggers a one-shot pull when the server says it produced
+     *  events past our local cursor. The pull short-circuits cheaply
+     *  (`{changes:[]}`) if WS broadcast already caught us up — so the
+     *  worst case is one extra in-flight pull per mutation, never a
+     *  stale render. */
+    private requestWithChangeSync;
+    /** Pull changes from the server. Coalesces concurrent callers via
+     *  the op queue and serializes against push / reconcile / reset, so
+     *  the cursor can't be read mid-reset and the change-log delta can't
+     *  interleave with a sweeping reconcile. The 410 RESYNC retry path
+     *  recurses into `pullInner` directly to avoid self-deadlock on the
+     *  queue. */
+    pull(): Promise<void>;
+    private pullInner;
+    /** Consecutive 410 RESYNC_REQUIRED responses since the last successful
+     *  pull. Used by the circuit breaker in pull() to bound the retry
+     *  storm against a misconfigured server. Resets to 0 on any pull
+     *  that doesn't throw a 410. */
+    private consecutive_410s;
+    /** Consecutive TRANSIENT push failures (offline / 5xx / 429 / 401)
+     *  since the last server response. Drives the exponential backoff on
+     *  the retry of a transient-failed push so an offline tab doesn't
+     *  hot-loop. Reset to 0 the moment the server returns any response. */
+    private pushFailureCount;
+    /** Set by pullInner whenever the just-completed pull started with
+     *  `cursor.last_seq === 0` (cold load OR post-reset). The WS
+     *  onConnected hook reads this to skip the reconcile() that would
+     *  otherwise fire immediately after the bootstrap pull — the
+     *  snapshot path of pull already returned every row visible under
+     *  current policy, so per-entity reconcile fetches right after are
+     *  pure waste (~300ms on the critical path). One-shot: the flag is
+     *  cleared on read so a subsequent reconnect-after-disconnect still
+     *  runs reconcile normally. */
+    private lastPullStartedFromZero;
+    /** Timestamp of the last `reconcile()` invocation. Used to debounce —
+     *  reconcile runs on connect, WS reconnect, AND visibility-change, so
+     *  a quick tab-flick after a normal reconnect shouldn't refetch every
+     *  entity twice within seconds. Configurable via `reconcileMinIntervalMs`. */
+    private lastReconcileAt;
+    /** Entities the app has subscribed to via `useQuery` / `useQueryOne`,
+     *  even ones the local replica has zero rows for. The reconcile
+     *  safety net defaults to `store.entityNames()` — entities with at
+     *  least one local row — so a server row in a NEVER-cached entity (a
+     *  row created on another surface, or a freshly-added entity) stayed
+     *  invisible until a full snapshot / cache clear: `useQuery` reads
+     *  the local store and a delta `pull()` can't recover a row created
+     *  before the cursor. Tracking observed entities lets the no-arg
+     *  reconcile sweep them too. See `observeEntity`. */
+    private observedEntities;
+    /** Per-entity count of CONSECUTIVE 403s seen during reconcile, reset on
+     *  any successful fetch. A single 403 can be transient (a bearer caught
+     *  mid-refresh, a momentary policy blip) and must NOT wipe the local cache;
+     *  we only drop an entity's rows after two in a row. See `reconcile`. */
+    private reconcile403Streak;
+    /**
+     * Reconcile the local replica against server truth.
+     *
+     * For each entity that has at least one local row, fetch the
+     * authoritative row set from `/api/entities/<entity>` (already
+     * policy-filtered) and apply the diff:
+     *
+     * - Local rows whose id is missing from the server set → removed.
+     * - Server rows whose JSON differs from local → overwritten.
+     * - Server rows the local replica doesn't have → inserted.
+     *
+     * This is the safety net the WS / pull path can't provide on its own:
+     *
+     *   - Deletes made by other surfaces (Mac SDK, server-side actions,
+     *     admin tools) while this client was offline can fall off the
+     *     in-memory ChangeLog before this client reconnects. The pull
+     *     then returns an empty diff and the local phantom rows persist
+     *     forever. Reconcile catches them.
+     *
+     *   - Mutations broadcast on a sibling Fly machine (multi-instance
+     *     deploys, autoscaled apps) never reach this WS. Reconcile is
+     *     the only mechanism that observes them.
+     *
+     *   - Events broadcast in the brief window between a pull completing
+     *     and the WS opening get dropped because the WS has no replay-
+     *     on-connect; reconcile makes those eventually-consistent.
+     *
+     * Debounced via `lastReconcileAt` so a flurry of triggers
+     * (reconnect + visibility-change firing back-to-back) coalesces to
+     * one network round per entity.
+     *
+     * Pass an explicit entity list to scope the reconcile (callers like
+     * `db.useQueryOne` that know what they care about). When called with
+     * no arg, every entity with local rows OR observed via `useQuery`
+     * (see `observeEntity`) is checked.
+     */
+    /**
+     * Register interest in an entity — called by `useQuery` /
+     * `useQueryOne` on mount. Two effects:
+     *
+     *   1. Adds the entity to the reconcile sweep so the safety net
+     *      covers it even with zero local rows (see `observedEntities`).
+     *   2. The FIRST time an entity is observed while the replica is
+     *      hydrated and that entity is locally empty, fires a one-shot
+     *      scoped reconcile so a server row this client never cached
+     *      appears on page-open — instead of waiting for the next
+     *      reconnect / visibility-change trigger. Bounded: at most once
+     *      per entity per engine (the `observedEntities` guard).
+     *
+     * Genuinely-empty entities just pay one cheap policy-filtered fetch;
+     * entities where the client missed an insert get the row back.
+     */
+    observeEntity(entity: string): void;
+    reconcile(entities?: string[]): Promise<void>;
+    private reconcileInner;
+    /** Fetch every row for an entity. Uses cursor pagination so big tables
+     *  don't blow past server-side limits; loops until `has_more` is false
+     *  or a safety cap is hit. */
+    private fetchEntityRows;
+    private applyEntityReconcile;
+    private dropEntity;
+    /**
+     * Fetch `/api/auth/me` and feed the result into the SessionResolver,
+     * acting on the verdict it returns (reset replica + pull on a real
+     * tenant flip, notify subscribers if any field changed). Callers:
+     *   - `start()` — initial load
+     *   - the token-flip branch in `pull()`
+     *   - `notifySessionChanged()` — app code invokes this after it mutates
+     *     server session state (login, logout, `/api/auth/select-org`) so the
+     *     cached session + React subscribers update immediately instead of
+     *     waiting for the next pull/reconnect cycle.
+     *
+     * On tenant flip this also resets the replica — same logic as the
+     * token-flip path, for the same reason (visible set changed).
+     */
+    refreshResolvedSession(): Promise<void>;
+    /**
+     * Pure HTTP fetch of /api/auth/me → ResolvedSession. Unlike
+     * `refreshResolvedSession`, this does NOT gate on `isMultiTabLeader`
+     * — bootstrap callers in `start()` fire this in PARALLEL with the
+     * multi-tab election to overlap two independent latency windows
+     * (election ~250ms || auth/me ~60ms). At that point no other tabs'
+     * messages have been observed yet, so there's no broadcast-policy
+     * violation; the caller is responsible for discarding the result
+     * if it lost the election.
+     *
+     * Returns null on HTTP error / network failure / parse error — the
+     * caller's next pull cycle (or the WS `session-changed` envelope)
+     * will retry. Errors must not abort bootstrap.
+     */
+    private fetchSessionBootstrap;
+    /**
+     * Apply a freshly-observed session through the resolver and act on
+     * the verdict. Serialized via `sessionChain` so concurrent triggers
+     * (refreshResolvedSession from app code + multi-tab `session`
+     * broadcast + WS `session-changed` envelope) run in arrival order
+     * and the latest tenant wins — without this, two interleaved
+     * inspect-then-commit pairs could commit an older session AFTER
+     * the newer one.
+     */
+    private applySessionTransition;
+    private rawFetch;
+    /**
+     * Public alias for `refreshResolvedSession`. Almost never needed by
+     * app code today — the server pushes a `session-changed` envelope
+     * over WS whenever the session is mutated (select-org, clear-org,
+     * session revoke, even from other tabs / admin tools / server
+     * actions), and the engine's WS handler refreshes automatically.
+     *
+     * Kept as an escape hatch for the rare case where you mutated the
+     * session via a path that doesn't go through the framework's auth
+     * surface (e.g. directly writing to the SessionStore from a Rust
+     * plugin that bypassed `notify_session_changed`).
+     *
+     * The `selectOrg` / `clearOrg` / `signOut` helpers below remain as
+     * convenience wrappers that combine the HTTP call with an immediate
+     * local refresh — useful when the same tab needs the new state
+     * before the WS round-trip lands.
+     */
+    notifySessionChanged(): Promise<void>;
+    /**
+     * Drop a row from the local replica because the server signaled
+     * that the current subscriber's read policy was revoked for it.
+     *
+     * `tombstoneSeq` is the server's high-water seq at the time of
+     * revocation (from the envelope). Stale in-flight WS frames with
+     * `seq <= tombstoneSeq` are filtered locally; legitimate
+     * re-grant + re-insert at higher seqs still land. Also fires a
+     * catch-up pull on revocation so any frame with `seq >
+     * tombstoneSeq` that arrives before the next legitimate event
+     * gets reconciled against server truth.
+     *
+     * Uses `LocalStore.revokeRow` (not `reconcileRemove`) so the
+     * tombstone is recorded even for CRDT-only consumers whose row
+     * was never materialized into `tables`.
+     *
+     * Also notifies row-eviction listeners so external row-bound
+     * resources (LoroDoc registries, etc.) can unmount.
+     */
+    private handleRowRevocation;
+    /**
+     * Register a listener invoked when the server signals a per-
+     * subscriber row revocation. Used by `@pylonsync/loro` to evict
+     * the LoroDoc registry entry for the row so collaborative doc
+     * handles unmount cleanly. Returns an unsubscribe function.
+     */
+    addRowEvictionListener(listener: (entity: string, rowId: string) => void): () => void;
+    /**
+     * Switch the caller's active tenant (organization) and refresh the
+     * resolved session in one shot. Membership is verified server-side
+     * (POST /api/auth/select-org throws 403 if the user isn't a member
+     * of the target org), and the engine's local replica resets so
+     * `db.useQuery` stops returning the previous tenant's rows.
+     *
+     * Throws on any non-2xx response. The error carries the
+     * server-issued JSON error body when available, so callers can
+     * branch on `err.code === "NOT_A_MEMBER"` etc.
+     */
+    selectOrg(orgId: string): Promise<void>;
+    /**
+     * Drop the caller's active tenant — back to the "no active org"
+     * state typical of a login-lobby route. Refreshes the resolved
+     * session so React subscribers re-render with `tenantId: null`.
+     */
+    clearOrg(): Promise<void>;
+    /**
+     * Revoke the current session server-side (DELETE /api/auth/session)
+     * and refresh — leaves the caller anonymous. Local sync stops on
+     * the next pull cycle; replica content stays in IndexedDB so a
+     * subsequent sign-in as the same user is instant.
+     */
+    signOut(): Promise<void>;
+    /** Shared transport for the auth helpers above. Same bearer/cookie
+     *  policy as `request()` — keeps the auth flows on the same
+     *  authentication footing as data sync. */
+    private authMutate;
+    /** Push pending mutations to the server. Coalesces concurrent callers
+     *  via the op queue's keyed dedupe — a slow push can't be restarted
+     *  by the poll timer or a user mutation, which would resend the same
+     *  batch (the mutation `op_id` keeps that safe at the protocol level,
+     *  but shipping the same batch twice is still wasted bandwidth). Also
+     *  serializes against pull / reconcile / resetReplica so a push can't
+     *  observe a half-reset cursor or a mid-reconcile replica. */
+    push(): Promise<void>;
+    private pushInner;
+    /**
+     * Mark a pending mutation as failed AND undo its optimistic ghost
+     * in the local replica. Without the rollback step, a server-
+     * rejected insert leaves a ghost row that survives indefinitely
+     * (reconcile skips rows with pending/failed mutations to avoid
+     * sweeping the user's in-flight edit). The exact failure mode is
+     * "send a message, the server says no, refresh — the ghost is
+     * still there until you find the failed-state UI."
+     *
+     * Updates can't be rolled back without a pre-update snapshot
+     * (not captured today); the user-visible ghost-update sticks
+     * until the next reconcile observes the canonical row. Deletes
+     * leave a tombstone that should also be cleared, but the current
+     * `LocalStore` API doesn't expose the un-tombstone path — flagged
+     * for follow-up. Inserts are the dominant case (chat send is an
+     * insert; collaborative-edit is an update with a separate CRDT
+     * channel) so insert-only rollback is the right shape to ship now.
+     */
+    private failPushedMutation;
+    /** Insert a row with optimistic local update.
+     *
+     *  Invariant: the optimistic ghost and the canonical server row
+     *  share a single id. The client mints a Pylon-shaped id, threads
+     *  it through the data payload, and the server honors it on the
+     *  canonical insert. Test:
+     *  `insert_optimistic_ghost_and_server_row_share_id`. */
+    insert(entity: string, data: Row): Promise<string>;
+    /** Update a row with optimistic local update. */
+    update(entity: string, id: string, data: Partial<Row>): Promise<void>;
+    /** Delete a row with optimistic local update. */
+    delete(entity: string, id: string): Promise<void>;
+    /** Load a page of data from an entity with cursor-based pagination. */
+    loadPage(entity: string, options?: {
+        limit?: number;
+        offset?: number;
+        order?: Record<string, "asc" | "desc">;
+    }): Promise<{
+        data: Row[];
+        total: number;
+        hasMore: boolean;
+    }>;
+    /**
+     * Create an infinite query that appends pages.
+     * Returns an object with loadMore() and the current accumulated data.
+     */
+    createInfiniteQuery(entity: string, options?: {
+        pageSize?: number;
+        order?: Record<string, "asc" | "desc">;
+    }): {
+        /** Load the next page. */
+        loadMore: () => Promise<void>;
+        /** Get current accumulated rows. */
+        readonly data: Row[];
+        /** Whether more pages are available. */
+        readonly hasMore: boolean;
+        /** Whether currently loading. */
+        readonly loading: boolean;
+        /** Subscribe to changes. */
+        subscribe: (fn: () => void) => () => boolean;
+        /** Reset and start over. */
+        reset: () => void;
+    };
+    /** Get the current cursor position. */
+    getCursor(): SyncCursor;
+    /** Whether the real-time transport is currently open. True for an
+     *  open WebSocket / EventSource and for a running poll loop; false
+     *  for a follower tab (no transport) or before start() / after stop(). */
+    get connected(): boolean;
+    /** Set this client's presence data and broadcast it. */
+    setPresence(data: Record<string, unknown>): void;
+    /** Send a topic message to all connected clients. */
+    publishTopic(topic: string, data: unknown): void;
+    /**
+     * Subscribe this client to binary CRDT updates for one row. Refcounted
+     * so two `useLoroDoc` consumers on the same `(entity, rowId)` don't
+     * unsubscribe each other on unmount — only the last `unsubscribeCrdt`
+     * call ships the unsubscribe message to the server.
+     *
+     * The first subscriber for a row sends the `crdt-subscribe` over WS,
+     * which prompts the server to ship the current snapshot back as a
+     * binary frame so the new tab converges to the latest state.
+     *
+     * Idempotent at the WS level: re-calling for the same row with no
+     * intervening unsubscribe just bumps the refcount.
+     */
+    subscribeCrdt(entity: string, rowId: string): void;
+    /**
+     * Decrement the refcount for a row. When it hits zero we ship a
+     * `crdt-unsubscribe` to the server and forget the row, so a future
+     * reconnect won't try to resubscribe.
+     *
+     * Calling `unsubscribeCrdt` more times than `subscribeCrdt` is a
+     * no-op rather than an error — keeps React's StrictMode double-
+     * invocation in dev from over-decrementing past zero.
+     */
+    unsubscribeCrdt(entity: string, rowId: string): void;
+    /**
+     * Register a reactive query subscription. The caller-minted `sub_id`
+     * is used by the React hook to dispatch result/error pushes to the
+     * right component. Returns nothing — push handling is async via the
+     * registered handler.
+     *
+     * Idempotent: re-calling with the same `sub_id` replaces the prior
+     * handler + spec. Useful when args change and the hook re-registers.
+     *
+     * The actual subscribe message goes over the WS — works only when
+     * the socket is open. When called before the WS opens (initial
+     * mount during start()), the spec is still recorded and gets sent
+     * on `ws.onopen`'s re-registration sweep.
+     */
+    subscribeReactive(sub_id: string, fn_name: string, args: unknown, handler: (msg: ReactiveMessage) => void): void;
+    /** Tear down a reactive subscription. Sends the unsubscribe to the
+     *  server and clears local state. No-op for unknown sub_ids — React
+     *  StrictMode double-unmount won't error. */
+    unsubscribeReactive(sub_id: string): void;
+    /** Send a JSON message via the active transport. No-op when no
+     *  transport exists (follower tab) or the transport doesn't support
+     *  uplink (SSE, polling). Subscribe / presence / topic / ping frames
+     *  all route here. */
+    private sendWs;
+    /**
+     * Subscribe to a room's membership over WebSocket. The callback fires
+     * whenever the room's `members` list OR `error` state changes — read
+     * the current snapshot via `getRoomMembers(roomId)` and the latest
+     * error via `getRoomError(roomId)` inside the callback.
+     *
+     * Refcounted: multiple subscribers for the same `roomId` share one
+     * `room-subscribe` on the wire. Returns an unsubscribe function;
+     * the last unsubscribe ships `room-unsubscribe`.
+     *
+     * Follower tabs forward the register / unregister over the multi-tab
+     * channel so the leader's WS carries one subscribe per room across
+     * the whole origin. Inbound snapshot / update / error envelopes land
+     * on the leader's WS and the leader fans them out cross-tab so each
+     * follower's local registry routes to its own subscribers.
+     *
+     * Idempotent w.r.t. wire frames: a re-subscribe with no intervening
+     * full unsubscribe doesn't re-send `room-subscribe`. ServerSubscriptions-
+     * style replay on reconnect is built in — the registry resends
+     * `room-subscribe` for every active room on WS reopen.
+     */
+    subscribeRoom(roomId: string, callback: RoomSubscriber): () => void;
+    /**
+     * Subscribe to BROADCAST MESSAGES relayed through a room (the
+     * payloads sent via `POST /api/rooms/broadcast` / `useRoom`'s
+     * `broadcast()`). Same refcounted wire-subscription and leader /
+     * follower routing as `subscribeRoom` — the two channels share one
+     * `room-subscribe` per room per origin.
+     *
+     * The callback receives `{ topic, payload, from }` where `from` is
+     * the server-stamped sender user id (own broadcasts echo back —
+     * filter on `from` if unwanted). Returns an unsubscribe function.
+     */
+    subscribeRoomMessages(roomId: string, callback: (message: import("./room-subscriptions").RoomMessage) => void): () => void;
+    /** Force-unsubscribe every local subscriber of a room and ship a
+     *  `room-unsubscribe`. Used by the `useRoom` hook's manual `leave()`
+     *  action so a deliberate exit propagates to the server immediately. */
+    unsubscribeRoom(roomId: string): void;
+    /** Read the current cached members snapshot for `roomId`. Returns
+     *  `null` when no snapshot has landed yet (distinct from `[]` for
+     *  an empty room). */
+    getRoomMembers(roomId: string): RoomMember[] | null;
+    /** Read the latest error for `roomId` (e.g. NOT_IN_ROOM). null when
+     *  none. */
+    getRoomError(roomId: string): RoomError | null;
+    /** Active transport kind. Used by the `useRoom` hook to decide
+     *  between WS push and HTTP polling fallback — only the WS transport
+     *  supports the room-subscribe push protocol; SSE and polling fall
+     *  back to the legacy 5s GET /api/rooms/<room>. */
+    getActiveTransportType(): TransportType;
+    /** True when the active transport is a WebSocket AND the socket is
+     *  currently open. The `useRoom` hook gates its WS-push path on this
+     *  — when false, fall back to polling. */
+    isWebSocketConnected(): boolean;
+    /** Resolved transport kind, with the websocket default applied. */
+    private transportKind;
+    /** Build the host surface the transport calls back into. One object
+     *  shared across transport lifetime — the engine fields it reads (
+     *  config, transport state, callbacks) are stable references. */
+    private transportHost;
+    /** Dispatch a typed JSON envelope inbound from the transport. The
+     *  transport already filtered out ChangeEvents (those go through
+     *  onChangeEvent → enqueueApply). Anything else lands here. */
+    private dispatchInboundMessage;
+    /** Route a binary frame to local consumers AND, when at least one
+     *  follower tab forwarded a CRDT sub, mirror over the multi-tab
+     *  channel so followers see Loro updates too. */
+    private dispatchBinaryFrame;
+    private request;
+}
+/** Data shape for hydrating the client from server-rendered content. */
+export interface HydrationData {
+    /** Map of entity name -> rows fetched on the server. */
+    entities: Record<string, Record<string, unknown>[]>;
+    /** The sync cursor at the time of server fetch. */
+    cursor?: SyncCursor;
+}
+/**
+ * Server-side helper: fetch entities from the pylon API and return
+ * hydration data that can be passed to the client's SyncEngine.hydrate().
+ *
+ * Use this in Next.js server components, getServerSideProps, or route handlers.
+ */
+export declare function getServerData(baseUrl: string, entities: string[], options?: {
+    token?: string;
+}): Promise<HydrationData>;
+/**
+ * Create a sync engine connected to the pylon backend.
+ *
+ * Default `baseUrl` resolution order:
+ *  1. Explicit `baseUrl` argument — wins always.
+ *  2. `window.location.origin` when running in a browser — same-origin
+ *     deployments (Next.js + Vercel rewrites, embedded SPA, etc.) want
+ *     this and forgetting to pass it should NOT silently leak
+ *     `localhost:4321` requests in production.
+ *  3. `http://localhost:4321` — the `pylon dev` default for SSR /
+ *     non-browser callers (Node scripts, tests).
+ */
+export declare function createSyncEngine(baseUrl?: string, options?: Partial<SyncEngineConfig>): SyncEngine;