@xnetjs/runtime 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,1020 @@
+import * as Y from 'yjs';
+import { ContentId, DID, PolicyEvaluator, AuthCheckInput, AuthDecision } from '@xnetjs/core';
+import { NodeStore, NodeStorageAdapter, NodeContentCipher, StoreAuthAPI, SchemaLookup, LensRegistry, PropertyBuilder, DefinedSchema, NodeState, TransactionOperation, NodeChange, NodePayload } from '@xnetjs/data';
+import { SyncLifecycleState, SyncReplicationConfig, ChangeSigner } from '@xnetjs/sync';
+export { SyncLifecyclePhase, SyncLifecycleState } from '@xnetjs/sync';
+import { Awareness } from 'y-protocols/awareness';
+import { DataBridge, MainThreadBridgeOptions, SyncStatus as SyncStatus$1, QueryOptions, BridgeTransactionResult, AcquiredDoc } from '@xnetjs/data-bridge';
+import { Identity } from '@xnetjs/identity';
+import { Platform, PluginRegistry } from '@xnetjs/plugins';
+import { UndoManager } from '@xnetjs/history';
+
+/**
+ * Connection Manager - Multiplexed WebSocket connection for all tracked Nodes
+ *
+ * Instead of one WebSocket per Node (current WebSocketSyncProvider approach),
+ * the Connection Manager maintains a single WebSocket subscribed to multiple
+ * rooms. This reduces connection count from O(N) to O(1).
+ *
+ * The signaling protocol supports multi-room subscriptions:
+ *   { type: "subscribe", topics: ["xnet-doc-abc", "xnet-doc-def"] }
+ */
+type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+interface ConnectionManagerConfig {
+    /** Signaling/hub WebSocket URL */
+    url: string;
+    /** Base reconnect delay in ms (default: 2000); grows exponentially per attempt. */
+    reconnectDelay?: number;
+    /**
+     * Cap on the exponentially-backed-off reconnect delay (default: 30000).
+     * Backoff is `min(reconnectDelay * 2^(attempt-1), maxReconnectDelay)`.
+     */
+    maxReconnectDelay?: number;
+    /** Max reconnect attempts (default: Infinity) */
+    maxReconnects?: number;
+    /**
+     * Backoff after a policy-violation close (WebSocket code 1008, e.g. the hub's
+     * "Rate limit exceeded"): a longer, jittered delay so we don't tight-loop or
+     * stampede the hub that just asked us to stop (default: 15000). Jitter adds
+     * up to 50% on top (exploration 0206).
+     */
+    rateLimitBackoffMs?: number;
+    /**
+     * Max time to wait for the WebSocket handshake to open before treating the
+     * attempt as failed and backing off (default: 10000). A browser WebSocket has
+     * no built-in connect timeout, so a stalled handshake can otherwise hang for
+     * tens of seconds (exploration 0188). Set to 0 to disable.
+     */
+    connectTimeout?: number;
+    /**
+     * Timeout for the FIRST handshake attempt (default: min(connectTimeout,
+     * 6000)). A healthy hub handshake completes in well under a second, so the
+     * first attempt fails fast and retries instead of pinning the "connecting"
+     * indicator for the full connectTimeout on a stalled cold dial; subsequent
+     * attempts use the full connectTimeout since the network is evidently slow
+     * (exploration 0204). Set to 0 to disable bounding the first attempt.
+     */
+    initialConnectTimeout?: number;
+    /** UCAN token for hub auth */
+    ucanToken?: string;
+    /** Async UCAN token provider (preferred for rotation) */
+    getUCANToken?: () => Promise<string>;
+}
+type RoomHandler = (data: Record<string, unknown>) => void;
+type StatusHandler = (status: ConnectionStatus) => void;
+interface RoomJoinResult {
+    /** Unsubscribe function */
+    unsubscribe: () => void;
+    /** Promise that resolves when server confirms subscription */
+    ready: Promise<void>;
+}
+interface ConnectionManager {
+    /** Current connection status */
+    readonly status: ConnectionStatus;
+    /** Connect to the signaling server */
+    connect(): void;
+    /** Disconnect and cleanup */
+    disconnect(): void;
+    /** Subscribe to a room (returns unsubscribe function) */
+    joinRoom(room: string, handler: RoomHandler): () => void;
+    /** Subscribe to a room with confirmation (returns cleanup and ready promise) */
+    joinRoomAsync(room: string, handler: RoomHandler): RoomJoinResult;
+    /** Leave a room */
+    leaveRoom(room: string): void;
+    /** Publish a message to a room */
+    publish(room: string, data: object): void;
+    /** Send a raw message on the WebSocket */
+    sendRaw(message: object): void;
+    /** Listen for non-room messages */
+    onMessage(handler: (message: Record<string, unknown>) => void): () => void;
+    /** Listen for status changes */
+    onStatus(handler: StatusHandler): () => void;
+    /** Number of active room subscriptions */
+    readonly roomCount: number;
+}
+interface MultiHubConnectionManagerConfig {
+    /** Hub connections to orchestrate as one logical transport. */
+    hubs: readonly ConnectionManagerConfig[];
+}
+declare function createConnectionManager(config: ConnectionManagerConfig): ConnectionManager;
+declare function createMultiHubConnectionManager(config: MultiHubConnectionManagerConfig): ConnectionManager;
+
+/**
+ * Blob Sync Provider - Handles blob synchronization between peers.
+ *
+ * Integrates with the Background Sync Manager's ConnectionManager to send
+ * blob have/want/data messages over the same multiplexed WebSocket connection
+ * used for Y.Doc sync. Uses a dedicated room for blob sync messages.
+ *
+ * Protocol:
+ *   blob-have: Announce available CIDs to peers
+ *   blob-want: Request missing blobs by CID
+ *   blob-data: Transfer blob bytes (base64 encoded)
+ *   blob-not-found: Signal unavailability
+ */
+
+/** Minimal blob store interface for sync (satisfied by BlobStore from @xnetjs/storage) */
+interface BlobStoreForSync {
+    get(cid: ContentId): Promise<Uint8Array | null>;
+    put(data: Uint8Array): Promise<ContentId>;
+    has(cid: ContentId): Promise<boolean>;
+}
+
+/**
+ * Sync Manager - Top-level orchestrator for Background Sync
+ *
+ * Wires together Node Pool, Registry, and Connection Manager into a cohesive
+ * sync service. Handles the Yjs sync protocol (state vectors, diffs, incremental
+ * updates) for each tracked Node.
+ *
+ * Components acquire Y.Docs via the SyncManager (through useNode). When released,
+ * docs stay alive in the pool and continue syncing in the background.
+ */
+
+type SyncStatus = ConnectionStatus;
+
+interface SyncManagerConfig {
+    /** NodeStore for meta bridge */
+    nodeStore: NodeStore;
+    /** Storage adapter for pool persistence (Y.Doc content) */
+    storage: NodeStorageAdapter;
+    /** Signaling/hub WebSocket URL */
+    signalingUrl: string;
+    /** Additional signaling/hub WebSocket URLs for multi-hub fan-out */
+    signalingUrls?: string[];
+    /** Max Y.Docs in memory (default: 50) */
+    poolSize?: number;
+    /** TTL for tracked Nodes in ms (default: 7 days) */
+    trackTTL?: number;
+    /** Author DID for awareness */
+    authorDID?: string;
+    /** Signing key for signed Yjs replication */
+    signingKey?: Uint8Array;
+    /** Replication compatibility policy */
+    replication?: SyncReplicationConfig;
+    /** Blob store for P2P blob sync (optional — if omitted, blob sync is disabled) */
+    blobStore?: BlobStoreForSync;
+    /** Optional UCAN token for hub auth */
+    ucanToken?: string;
+    /** Optional UCAN token provider for hub auth */
+    getUCANToken?: () => Promise<string>;
+    /** Optional pool update callback */
+    onDocUpdate?: (nodeId: string, doc: Y.Doc) => void;
+    /** Optional pool eviction callback */
+    onDocEvict?: (nodeId: string, doc: Y.Doc) => void;
+    /** Optional room for node-change relay (enables NodeStore sync via hub) */
+    nodeSyncRoom?: string;
+}
+type SyncReconciliationOptions = {
+    /** Optional node subset. Defaults to all joined rooms. */
+    nodeIds?: string[];
+    /** Diagnostic reason included in reports and debug traces. */
+    reason?: 'manual' | 'reconnect' | 'partition-repair';
+};
+type SyncReconciliationReport = {
+    reason: NonNullable<SyncReconciliationOptions['reason']>;
+    replayedOfflineChanges: number;
+    repairedNodeIds: string[];
+    skippedNodeIds: string[];
+    at: number;
+};
+interface SyncManager {
+    /** Start the sync manager (connect, load registry, sync tracked Nodes) */
+    start(): Promise<void>;
+    /** Stop (disconnect, flush, save registry) */
+    stop(): Promise<void>;
+    /** Track a Node for background sync */
+    track(nodeId: string, schemaId: string): void;
+    /** Stop tracking a Node */
+    untrack(nodeId: string): void;
+    /** Acquire a Y.Doc (used by useNode) */
+    acquire(nodeId: string): Promise<Y.Doc>;
+    /** Release a Y.Doc (component unmounted) */
+    release(nodeId: string): void;
+    /** Get awareness for a Node (for cursor presence) */
+    getAwareness(nodeId: string): Awareness | null;
+    /** Listen for awareness snapshots from the hub */
+    onAwarenessSnapshot(nodeId: string, handler: (users: AwarenessSnapshotUser[]) => void): () => void;
+    /** Request blobs from peers by CID (no-op if blob sync is disabled) */
+    requestBlobs(cids: string[]): Promise<void>;
+    /** Announce blob CIDs to peers (no-op if blob sync is disabled) */
+    announceBlobs(cids: string[]): void;
+    /** Explicitly drain queued updates and re-request state for tracked rooms. */
+    reconcile(options?: SyncReconciliationOptions): Promise<SyncReconciliationReport>;
+    /**
+     * Wipe this client's node-change data on the hub ("reset my data") and reset
+     * the local sync cursor. Returns how many changes the hub removed (0 if there
+     * is no node-sync room or we're offline). Pair with a local wipe + reload.
+     */
+    clearHubData(): Promise<number>;
+    /** Connection status */
+    readonly status: SyncStatus;
+    /** Canonical background-sync lifecycle */
+    readonly lifecycle: SyncLifecycleState;
+    /** Pool stats */
+    readonly poolSize: number;
+    /** Tracked count */
+    readonly trackedCount: number;
+    /** Offline queue size */
+    readonly queueSize: number;
+    /** Pending blob requests */
+    readonly pendingBlobCount: number;
+    /** Last rejected replication payload, if any */
+    readonly lastVerificationFailure: {
+        nodeId: string;
+        sender: string | null;
+        reason: string;
+        at: number;
+    } | null;
+    /** Last reconciliation/repair report, if any. */
+    readonly lastReconciliationReport: SyncReconciliationReport | null;
+    /** Listen for events */
+    on(event: 'status', handler: (status: SyncStatus) => void): () => void;
+    on(event: 'lifecycle', handler: (state: SyncLifecycleState) => void): () => void;
+    on(event: 'verification-failure', handler: (failure: {
+        nodeId: string;
+        sender: string | null;
+        reason: string;
+        at: number;
+    }) => void): () => void;
+    on(event: 'reconciliation', handler: (report: SyncReconciliationReport) => void): () => void;
+    /** Underlying ConnectionManager (if available) */
+    readonly connection?: ConnectionManager;
+}
+type AwarenessSnapshotUser = {
+    did: string;
+    state: {
+        user?: {
+            name?: string;
+            color?: string;
+            avatar?: string;
+            did?: string;
+        };
+        cursor?: {
+            anchor: number;
+            head: number;
+        };
+        selection?: unknown;
+        online?: boolean;
+        [key: string]: unknown;
+    };
+    lastSeen: number;
+    isStale: boolean;
+};
+declare function createSyncManager(config: SyncManagerConfig): SyncManager;
+
+/** Telemetry reporter accepted by the runtime (duck-typed, no hard dep). */
+interface XNetClientTelemetry {
+    reportPerformance(metricName: string, durationMs: number, codeNamespace?: string): void;
+    reportUsage(metricName: string, value: number): void;
+    reportCrash(error: Error, context?: {
+        codeNamespace?: string;
+    }): void;
+    reportSecurityEvent(eventName: string, severity: 'low' | 'medium' | 'high' | 'critical'): void;
+}
+/** Background-sync configuration. Omit (or pass `false`) for a local-only client. */
+interface XNetClientSyncOptions {
+    /** Primary signaling/hub WebSocket URL (default: ws://localhost:4444). */
+    signalingUrl?: string;
+    /** Additional signaling/hub URLs for multi-hub fan-out. */
+    signalingUrls?: string[];
+    /** Replication compatibility policy. */
+    replication?: SyncReplicationConfig;
+    /** Blob store for P2P blob sync (images, files). */
+    blobStore?: BlobStoreForSync;
+    /** Room for node-change relay (enables NodeStore sync via hub). */
+    nodeSyncRoom?: string;
+    /** Static UCAN token for hub auth. */
+    ucanToken?: string;
+    /** UCAN token provider for hub auth. */
+    getUCANToken?: () => Promise<string>;
+    /** Max Y.Docs held in memory (default: 50). */
+    poolSize?: number;
+    /** TTL for tracked Nodes in ms (default: 7 days). */
+    trackTTL?: number;
+    /** Pool update callback (e.g. for auto-backup). */
+    onDocUpdate?: (nodeId: string, doc: Y.Doc) => void;
+    /** Pool eviction callback. */
+    onDocEvict?: (nodeId: string, doc: Y.Doc) => void;
+    /** Start the sync manager immediately (default: true). */
+    autoStart?: boolean;
+}
+/** Plugin-system configuration. Omit for no plugin registry (lean default). */
+interface XNetClientPluginOptions {
+    /** Plugin compatibility platform (default: 'web'). */
+    platform?: Platform;
+    /** Load previously installed plugins from the store on init (default: true). */
+    autoLoad?: boolean;
+}
+/** App-wide undo configuration. Omit for no undo manager (lean default). */
+interface XNetClientUndoOptions {
+    /** Only undo the local author's own changes (default: true). */
+    localOnly?: boolean;
+    /** Max undo stack size (default: 200). */
+    maxStackSize?: number;
+}
+/** Options for {@link createXNetClient}. */
+interface CreateXNetClientOptions {
+    /** Node storage adapter (default: in-memory). */
+    nodeStorage?: NodeStorageAdapter;
+    /** Author's DID for signing changes. */
+    authorDID: DID;
+    /** Ed25519 signing key. */
+    signingKey: Uint8Array;
+    /** Optional full identity (exposed as `client.identity`). */
+    identity?: Identity;
+    /** Optional async change signer (e.g. WebCrypto/worker-backed). */
+    changeSigner?: ChangeSigner;
+    /** Authorization evaluator for read/write gating. */
+    authEvaluator?: PolicyEvaluator;
+    /** Transparent node-content cipher (encrypt/decrypt snapshots). */
+    nodeContentCipher?: NodeContentCipher;
+    /** High-level authorization API attached as `store.auth`. */
+    auth?: StoreAuthAPI;
+    /** Schema lookup for temp-id resolution in relation properties. */
+    schemaLookup?: SchemaLookup;
+    /** Property lookup for unknown-property preservation. */
+    propertyLookup?: (schemaId: string) => Set<string> | undefined;
+    /** Lens registry for automatic schema migrations on read. */
+    lensRegistry?: LensRegistry;
+    /** Telemetry reporter. */
+    telemetry?: XNetClientTelemetry;
+    /**
+     * Custom DataBridge (e.g. a WorkerBridge or IPC bridge), already
+     * initialized. When omitted, a main-thread bridge is created internally.
+     */
+    dataBridge?: DataBridge;
+    /** Options for the internally created main-thread bridge. */
+    bridgeOptions?: MainThreadBridgeOptions;
+    /** Background sync — omit or pass `false` for a local-only client. */
+    sync?: XNetClientSyncOptions | false;
+    /** Plugin system — omit or pass `false` to disable. */
+    plugins?: XNetClientPluginOptions | false;
+    /** App-wide undo — omit or pass `false` to disable. */
+    undo?: XNetClientUndoOptions | false;
+}
+type XNetClientRuntimePhase = 'ready' | 'destroyed';
+type XNetClientBridgeMode = 'main-thread' | 'custom';
+interface XNetClientRuntimeStatus {
+    phase: XNetClientRuntimePhase;
+    /** Whether the bridge was created internally ('main-thread') or supplied ('custom'). */
+    bridgeMode: XNetClientBridgeMode;
+    /** Whether background sync is active. */
+    syncEnabled: boolean;
+}
+/**
+ * A fully constructed, framework-agnostic xNet client. Owns its store, bridge,
+ * and (optionally) sync/plugins/undo, and exposes the read/write/auth/doc
+ * surface the React hooks expose.
+ */
+interface XNetClient {
+    readonly store: NodeStore;
+    readonly bridge: DataBridge;
+    readonly syncManager: SyncManager | null;
+    readonly plugins: PluginRegistry | null;
+    readonly undo: UndoManager | null;
+    readonly identity?: Identity;
+    readonly authorDID: DID;
+    /** Current bridge/sync connection status. */
+    readonly status: SyncStatus$1;
+    readonly runtimeStatus: XNetClientRuntimeStatus;
+    /** Live query — returns a `{ getSnapshot, subscribe }` subscription. */
+    query: DataBridge['query'];
+    /** One-shot read — resolves once with the first non-null snapshot. */
+    fetch<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, options?: QueryOptions<P>): Promise<NodeState[]>;
+    /** Read a single node by id. */
+    get(nodeId: string): Promise<NodeState | null>;
+    mutate: {
+        create: DataBridge['create'];
+        update: DataBridge['update'];
+        delete: DataBridge['delete'];
+        restore: DataBridge['restore'];
+        bulkWrite: DataBridge['bulkWrite'];
+        transaction(operations: TransactionOperation[]): Promise<BridgeTransactionResult>;
+    };
+    /** High-level grant/role API (null when no `auth` was configured). */
+    auth: StoreAuthAPI | null;
+    /** Evaluate an authorization decision (permissive when no evaluator is set). */
+    can(input: AuthCheckInput): Promise<AuthDecision>;
+    node: {
+        acquire(nodeId: string): Promise<AcquiredDoc>;
+        release(nodeId: string): void;
+    };
+    /** Sign a message with the client's signing key. */
+    sign(message: Uint8Array): Uint8Array;
+    /** Verify a signature (defaults to the client's own public key). */
+    verify(message: Uint8Array, signature: Uint8Array, publicKey?: Uint8Array): boolean;
+    on(event: 'status', handler: (status: SyncStatus$1) => void): () => void;
+    /** Tear down sync, plugins, undo, the (internally created) bridge, and storage. Idempotent. */
+    destroy(): Promise<void>;
+}
+/**
+ * Construct an xNet runtime. Returns a ready-to-use {@link XNetClient}.
+ *
+ * @example
+ * const client = await createXNetClient({
+ *   nodeStorage: new MemoryNodeStorageAdapter(),
+ *   authorDID: identity.did,
+ *   signingKey: privateKey
+ * })
+ * const tasks = await client.fetch(TaskSchema, { where: { status: 'todo' } })
+ * await client.mutate.create(TaskSchema, { title: 'Ship it' })
+ * await client.destroy()
+ */
+declare function createXNetClient(options: CreateXNetClientOptions): Promise<XNetClient>;
+
+/**
+ * liveQuery — a tiny framework-agnostic reactive wrapper over a client query.
+ *
+ * The whole point of the runtime is that `client.query(...)` returns a
+ * `{ getSnapshot, subscribe }` subscription — the universal external-store
+ * contract. `liveQuery` adapts that into the **Svelte store contract**
+ * (`subscribe(run) => unsubscribe`, where `run` is invoked immediately with the
+ * current value and again on every change), which is also trivially consumable
+ * from Vue (`shallowRef` + `watchSyncEffect`), Solid, Angular, or plain JS.
+ *
+ * It is intentionally dependency-free: there is no Svelte/Vue import here, so it
+ * works in any environment, yet a Svelte component can use it directly with
+ * `$liveQuery(...)` auto-subscription.
+ */
+
+/** The current value of a live query: `null` while loading, then the rows. */
+type LiveQueryValue = NodeState[] | null;
+/** A reactive handle over a live query (Svelte-store compatible). */
+interface LiveQuery {
+    /**
+     * Svelte store contract. `run` is called synchronously with the current value
+     * and again on every change. Returns an unsubscribe function.
+     */
+    subscribe(run: (value: LiveQueryValue) => void): () => void;
+    /** Read the current value synchronously. */
+    get(): LiveQueryValue;
+    /** Release the underlying query subscription and drop all subscribers. */
+    destroy(): void;
+}
+/**
+ * Create a reactive, Svelte-store-compatible live query.
+ *
+ * @example Svelte
+ * ```svelte
+ * <script>
+ *   import { liveQuery } from '@xnetjs/runtime'
+ *   const tasks = liveQuery(client, TaskSchema, { where: { status: 'todo' } })
+ * </script>
+ * {#each $tasks ?? [] as task}
+ *   <li>{task.properties.title}</li>
+ * {/each}
+ * ```
+ *
+ * @example Vanilla
+ * ```ts
+ * const tasks = liveQuery(client, TaskSchema)
+ * const stop = tasks.subscribe((rows) => render(rows))
+ * // …later
+ * stop()
+ * ```
+ */
+declare function liveQuery<P extends Record<string, PropertyBuilder>>(client: XNetClient, schema: DefinedSchema<P>, options?: QueryOptions<P>): LiveQuery;
+
+/**
+ * WebSocketSyncProvider - Syncs Y.Doc via WebSocket relay
+ *
+ * Unlike y-webrtc (which uses WebRTC DataChannels for P2P), this provider
+ * relays all Yjs updates through the signaling server. This works in all
+ * environments (same-machine, different networks, behind NATs) at the cost
+ * of server-relayed traffic.
+ *
+ * Protocol (extends the y-webrtc signaling protocol):
+ * - Uses the same subscribe/publish mechanism as y-webrtc signaling
+ * - Sync messages are published as JSON with base64-encoded binary data
+ * - Message types: 'sync-step1', 'sync-step2', 'sync-update', 'awareness'
+ *
+ * Sync flow:
+ * 1. On connect: subscribe to room, broadcast sync-step1 (state vector)
+ * 2. On receiving sync-step1: respond with sync-step2 (diff for their vector)
+ * 3. On local update: broadcast sync-update to room
+ * 4. On receiving sync-update: apply to local doc
+ *
+ * Awareness flow:
+ * 1. On connect: broadcast local awareness state
+ * 2. On awareness change: broadcast updated state
+ * 3. On receiving awareness: apply to local awareness instance
+ * 4. On disconnect: peers remove the disconnected client's state
+ */
+
+interface WebSocketSyncProviderOptions {
+    /** WebSocket URL of the signaling/relay server */
+    url: string;
+    /** Room name (peers in the same room sync together) */
+    room: string;
+    /** Author DID for signed replication */
+    authorDID?: string;
+    /** Signing key for signed replication */
+    signingKey?: Uint8Array;
+    /** Replication compatibility policy */
+    replication?: SyncReplicationConfig;
+    /** Reconnect delay in ms (default: 2000) */
+    reconnectDelay?: number;
+    /** Maximum reconnect attempts (default: Infinity) */
+    maxReconnectAttempts?: number;
+}
+type SyncEventType = 'status' | 'synced' | 'peers' | 'awareness-snapshot';
+type SyncEventHandler = (event: unknown) => void;
+declare class WebSocketSyncProvider {
+    readonly doc: Y.Doc;
+    readonly room: string;
+    readonly url: string;
+    readonly awareness: Awareness;
+    private ws;
+    private reconnectDelay;
+    private maxReconnectAttempts;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private destroyed;
+    private connected;
+    private synced;
+    private peerId;
+    private remotePeerIds;
+    private eventHandlers;
+    private readonly options;
+    private readonly replicationPolicy;
+    constructor(doc: Y.Doc, options: WebSocketSyncProviderOptions);
+    get isConnected(): boolean;
+    get isSynced(): boolean;
+    /** Helper to get XML fragment length for debug logging */
+    private _getFragmentLength;
+    on(event: SyncEventType, handler: SyncEventHandler): void;
+    off(event: SyncEventType, handler: SyncEventHandler): void;
+    private emit;
+    destroy(): void;
+    private _connect;
+    private _scheduleReconnect;
+    private _send;
+    private _publish;
+    private _createOutgoingPayload;
+    private _extractIncomingUpdate;
+    /** Handle incoming sync messages from other peers */
+    private _handleSyncMessage;
+    /** Broadcast local doc updates to peers */
+    private _onDocUpdate;
+    /** Broadcast local awareness changes to peers */
+    private _onAwarenessUpdate;
+}
+
+/**
+ * Meta Bridge - Unidirectional sync from NodeStore → Y.Doc meta map
+ *
+ * SECURITY: This bridge is intentionally ONE-WAY. The Y.Doc meta map is a
+ * read-only cache for the editor UI. Property changes MUST go through the
+ * signed NodeChange pipeline (via mutate()), never through Yjs.
+ *
+ * Before (VULNERABLE):
+ *   NodeStore ↔ MetaBridge ↔ Y.Doc meta
+ *   (Malicious Yjs updates could poison NodeStore!)
+ *
+ * After (SECURE):
+ *   NodeStore → MetaBridge → Y.Doc meta (write)
+ *   Y.Doc meta → Editor UI (read-only display)
+ *   Editor UI → mutate() → NodeStore (signed writes)
+ *
+ * See: docs/plans/plan03_4_1YjsSecurity/04-metabridge-isolation.md
+ */
+
+/** Transaction origin for MetaBridge writes (for debugging/monitoring) */
+declare const METABRIDGE_ORIGIN = "metabridge";
+declare const METABRIDGE_SEED_ORIGIN = "metabridge-seed";
+interface MetaBridge {
+    /**
+     * Start observing NodeStore changes for a Node and syncing to Y.Doc meta.
+     * Direction: NodeStore → Y.Doc meta map (ONE-WAY)
+     *
+     * @returns Unsubscribe function
+     */
+    observe(nodeId: string, doc: Y.Doc): () => void;
+    /**
+     * Seed the Y.Doc meta map with current NodeStore state.
+     * Called on document open to populate editor UI.
+     */
+    seed(nodeId: string, doc: Y.Doc): Promise<void>;
+    /**
+     * @deprecated Use seed() instead. applyNow() was the bidirectional API.
+     * This is kept for backward compatibility but now just calls seed().
+     */
+    applyNow(nodeId: string, doc: Y.Doc): Promise<void>;
+}
+/**
+ * Create a unidirectional MetaBridge.
+ *
+ * @param store - NodeStore to observe
+ * @param options - Configuration options
+ */
+declare function createMetaBridge(store: NodeStore, options?: {
+    /** Log warnings for non-MetaBridge meta map changes (default: true) */
+    warnOnExternalMetaChanges?: boolean;
+}): MetaBridge;
+
+/**
+ * Node Pool - LRU cache of Y.Doc instances with acquire/release semantics
+ *
+ * Components acquire a Y.Doc when they need it and release it when they unmount.
+ * Released Y.Docs stay in the pool (warm state) and continue receiving sync
+ * updates via the Connection Manager.
+ *
+ * States:
+ * - Active: refCount > 0, never evicted
+ * - Warm: refCount = 0, evictable (LRU)
+ * - Cold: evicted, serialized to storage (load on demand)
+ */
+
+type PoolEntryState = 'active' | 'warm' | 'cold';
+interface NodePoolConfig {
+    /** Storage adapter for persisting Y.Doc state */
+    storage: NodeStorageAdapter;
+    /** Meta bridge for syncing properties to NodeStore */
+    metaBridge: MetaBridge;
+    /** Max warm entries before LRU eviction (default: 50) */
+    maxWarm?: number;
+    /** Debounce delay for persisting dirty docs (default: 2000ms) */
+    persistDelay?: number;
+    /** Optional callback when a doc is updated */
+    onDocUpdate?: (nodeId: string, doc: Y.Doc) => void;
+    /** Optional callback before a doc is evicted */
+    onDocEvict?: (nodeId: string, doc: Y.Doc) => void;
+}
+interface NodePool {
+    /** Acquire a Y.Doc for a Node (load from storage or create new) */
+    acquire(nodeId: string): Promise<Y.Doc>;
+    /** Release a Y.Doc (component unmounted, doc stays warm) */
+    release(nodeId: string): void;
+    /** Check if a Node is in the pool */
+    has(nodeId: string): boolean;
+    /** Get pool entry state */
+    getState(nodeId: string): PoolEntryState | null;
+    /** Number of entries currently in memory */
+    readonly size: number;
+    /** Force-persist all dirty docs */
+    flushAll(): Promise<void>;
+    /** Destroy pool, persist all docs, cleanup */
+    destroy(): Promise<void>;
+}
+declare function createNodePool(config: NodePoolConfig): NodePool;
+
+/**
+ * NodeStoreSyncProvider - Sync NodeChange events via hub ConnectionManager.
+ *
+ * Anti-flood design (exploration 0206):
+ *  - A persisted per-room cursor (lastSyncedLamport) is loaded on connect, so
+ *    a reload no longer replays the entire change log (getChangesSince(0)).
+ *  - Request-sync-first: on connect we ask the hub for its high-water mark
+ *    before pushing, so when the hub is already ahead we push nothing.
+ *  - A throttled send queue caps outbound node-change messages per second so a
+ *    genuine backlog can't trip the hub's per-connection rate limiter (1008).
+ */
+
+type SerializedNodeChange = {
+    id: string;
+    type: string;
+    hash: string;
+    room: string;
+    nodeId: string;
+    schemaId?: string;
+    lamportTime: number;
+    lamportAuthor: string;
+    authorDid: string;
+    wallTime: number;
+    parentHash: string | null;
+    payload: NodePayload;
+    signatureB64: string;
+    protocolVersion?: number;
+    batchId?: string;
+    batchIndex?: number;
+    batchSize?: number;
+};
+type NodeSyncResponse = {
+    type: 'node-sync-response';
+    room: string;
+    changes: SerializedNodeChange[];
+    highWaterMark: number;
+};
+/**
+ * Listener for unknown change type events.
+ */
+type UnknownChangeTypeListener = (change: NodeChange, peerId: string) => void;
+declare class NodeStoreSyncProvider {
+    private store;
+    private room;
+    /** Confirmed, persisted high-water mark (advanced from the hub's response). */
+    private lastSyncedLamport;
+    /** Optimistic in-memory cursor: lamport of the last change actually sent. */
+    private pushedThrough;
+    private cursorLoaded;
+    private connection;
+    private roomCleanup;
+    private statusCleanup;
+    private messageCleanup;
+    private storeCleanup;
+    private unknownChangeTypeListeners;
+    private sendQueue;
+    private queuedHashes;
+    private sendTimer;
+    private sentInWindow;
+    private syncResponseResolver;
+    private structuralRejections;
+    private outboundHalted;
+    private clearResolver;
+    private firstRemoteApplyMarked;
+    constructor(store: NodeStore, room: string);
+    /**
+     * Mark the first remote apply once. Platform-agnostic and defensive: a
+     * missing `performance` global, or a throw, is a no-op — instrumentation
+     * must never break sync.
+     */
+    private markFirstRemoteApply;
+    /**
+     * Subscribe to unknown change type events.
+     * These are changes received from peers with types this version doesn't know how to process.
+     * The changes are still stored in the change log for forward compatibility.
+     *
+     * @param listener - Callback invoked when an unknown change type is received
+     * @returns Unsubscribe function
+     */
+    onUnknownChangeType(listener: UnknownChangeTypeListener): () => void;
+    private emitUnknownChangeType;
+    attach(connection: ConnectionManager): void;
+    detach(): void;
+    /**
+     * On connect: load the persisted cursor, ask the hub for its high-water mark
+     * FIRST, then push only the changes the hub is actually missing. Combined
+     * with the persisted cursor, a normal reload of an in-sync workspace pushes
+     * nothing (exploration 0206).
+     */
+    private onConnected;
+    private onDisconnected;
+    private ensureCursorLoaded;
+    private waitForSyncResponse;
+    private resolveSyncResponse;
+    /**
+     * Ask the hub to wipe every stored change for this room ("reset my data"),
+     * then reset the local sync cursor so a later sync re-pulls from scratch.
+     * Resolves with the number of changes the hub removed (0 on timeout or when
+     * offline). Pairs with a local wipe + reload for a full reset.
+     */
+    clearRoom(): Promise<number>;
+    private resolveClear;
+    private handleRoomMessage;
+    private handleDirectMessage;
+    /**
+     * Trip the circuit breaker after enough consecutive structural rejections.
+     *
+     * Structural rejections (bad hash/signature/shape) are not transient: the
+     * same change re-sent is rejected again, and — when it's a protocol/build
+     * skew — so is every other local change. Rather than re-flood the hub forever
+     * (the symptom that motivated this), we stop pushing, drop the queue, and log
+     * ONE actionable error. A reconnect clears the breaker (the hub may have been
+     * upgraded) via {@link onConnected}, and any forward progress resets the
+     * counter so sparse one-off rejections never accumulate to a false trip.
+     */
+    private recordStructuralRejection;
+    private requestSync;
+    private handleRemoteChange;
+    private handleSyncResponse;
+    /** Enqueue every local change since the last confirmed send, then drain. */
+    private syncLocalChanges;
+    /** Queue a change for throttled broadcast (deduped by hash). */
+    private enqueueChange;
+    private scheduleDrain;
+    private drain;
+    private publishChange;
+    private clearSendQueue;
+    private serializeChange;
+    private deserializeChange;
+}
+
+/**
+ * Registry - Persistent tracked-Node set that survives app restarts
+ *
+ * The Registry maintains the set of Nodes the BSM should keep synced.
+ * Nodes are added automatically when opened and expire after a configurable TTL.
+ * Pinned Nodes never expire.
+ */
+interface TrackedNode {
+    nodeId: string;
+    schemaId: string;
+    /** When the user last opened this Node */
+    lastOpened: number;
+    /** When sync last completed for this Node */
+    lastSynced: number;
+    /** Whether explicitly pinned (never expires) */
+    pinned: boolean;
+}
+interface RegistryStorage {
+    get(key: string): Promise<TrackedNode[] | null>;
+    set(key: string, entries: TrackedNode[]): Promise<void>;
+}
+interface RegistryConfig {
+    /** Storage adapter for persistence */
+    storage: RegistryStorage;
+    /** TTL for tracked Nodes in ms (default: 7 days) */
+    trackTTL?: number;
+    /** Storage key for the tracked set */
+    storageKey?: string;
+}
+interface Registry {
+    /** Add a Node to the tracked set */
+    track(nodeId: string, schemaId: string): void;
+    /** Remove a Node from the tracked set */
+    untrack(nodeId: string): void;
+    /** Pin a Node (never expires) */
+    pin(nodeId: string): void;
+    /** Unpin a Node (subject to TTL expiry) */
+    unpin(nodeId: string): void;
+    /** Mark a Node as recently opened (refreshes TTL) */
+    touch(nodeId: string): void;
+    /** Mark a Node as synced */
+    markSynced(nodeId: string): void;
+    /** Get all tracked Nodes (excluding expired) */
+    getTracked(): TrackedNode[];
+    /** Check if a Node is tracked */
+    isTracked(nodeId: string): boolean;
+    /** Load from storage */
+    load(): Promise<void>;
+    /** Persist to storage */
+    save(): Promise<void>;
+    /** Remove expired entries */
+    prune(): number;
+}
+declare function createRegistry(config: RegistryConfig): Registry;
+
+/**
+ * Offline Queue - Persistent queue for Y.Doc updates made while disconnected
+ *
+ * When the network is unavailable, local Y.Doc updates are queued in persistent
+ * storage. On reconnect, the queue is drained (replayed in order). This ensures
+ * no local changes are lost, even across app restarts.
+ */
+
+interface QueueEntry {
+    /** Node ID this update belongs to */
+    nodeId: string;
+    /** Serialized Y.Doc update (base64 encoded) */
+    update: string;
+    /** Original Yjs client ID when the update was queued */
+    clientId?: number;
+    /** Timestamp when queued */
+    queuedAt: number;
+}
+interface OfflineQueueConfig {
+    /** Storage adapter for persistence */
+    storage: NodeStorageAdapter;
+    /** Storage key for the queue (default: '_xnet_offline_queue') */
+    storageKey?: string;
+    /** Max queue size before dropping oldest entries (default: 1000) */
+    maxSize?: number;
+}
+interface OfflineQueue {
+    /** Enqueue an update for later broadcast */
+    enqueue(nodeId: string, update: Uint8Array, clientId?: number): Promise<void>;
+    /** Drain the queue, calling handler for each entry. Returns count drained. */
+    drain(handler: (entry: QueueEntry) => Promise<void>): Promise<number>;
+    /** Number of entries in the queue */
+    readonly size: number;
+    /** Load queue from storage */
+    load(): Promise<void>;
+    /** Persist queue to storage */
+    save(): Promise<void>;
+    /** Clear all entries */
+    clear(): Promise<void>;
+}
+declare function createOfflineQueue(config: OfflineQueueConfig): OfflineQueue;
+
+/**
+ * @xnetjs/react/sync - Initial sync manager for new device onboarding
+ *
+ * Orchestrates the full state sync when a new device connects to the hub
+ * with an existing identity. Tracks progress and provides callbacks.
+ */
+type SyncPhase = 'connecting' | 'syncing' | 'complete' | 'error';
+type SyncProgress = {
+    /** Current phase of the sync process */
+    phase: SyncPhase;
+    /** Total rooms discovered on the hub */
+    roomsTotal: number;
+    /** Rooms that have been fully synced */
+    roomsSynced: number;
+    /** Total bytes received from hub */
+    bytesReceived: number;
+    /** Error if phase === 'error' */
+    error?: Error;
+};
+type InitialSyncMessage = {
+    type: 'initial-sync' | 'node-changes' | 'initial-sync-complete';
+    room?: string;
+    update?: Uint8Array;
+    changes?: unknown[];
+    roomCount?: number;
+};
+type ProgressListener = (progress: SyncProgress) => void;
+/**
+ * Manages the initial sync process for a new device.
+ *
+ * Usage:
+ * ```ts
+ * const manager = createInitialSyncManager()
+ * const unsub = manager.onProgress((p) => updateUI(p))
+ *
+ * // Feed messages from the hub WebSocket:
+ * manager.handleMessage({ type: 'initial-sync', room: 'r1', update: ... })
+ * manager.handleMessage({ type: 'initial-sync-complete', roomCount: 5 })
+ *
+ * unsub()
+ * ```
+ */
+type InitialSyncManager = {
+    /** Subscribe to progress updates */
+    onProgress(listener: ProgressListener): () => void;
+    /** Handle an incoming sync message from the hub */
+    handleMessage(msg: InitialSyncMessage): void;
+    /** Get current progress snapshot */
+    getProgress(): SyncProgress;
+    /** Mark sync as started (connecting phase) */
+    start(): void;
+    /** Mark sync as errored */
+    setError(error: Error): void;
+    /** Reset to initial state */
+    reset(): void;
+};
+declare function createInitialSyncManager(): InitialSyncManager;
+
+/**
+ * The umbrella XNet Protocol Version.
+ *
+ * Five subsystems version independently (the change record, the Yjs sync
+ * envelope, awareness, schemas, the crypto level). To avoid a five-way
+ * negotiation, peers advertise a single named bundle — exactly as Matrix
+ * bundles breaking changes into "room versions". A breaking change to any
+ * normative layer mints a new umbrella version; the handshake advertises a
+ * set, so old and new peers can coexist.
+ *
+ * This is the machine-readable counterpart of the normative specification in
+ * `docs/specs/protocol/`. See `00-overview.md` §5.
+ */
+/** Schema profile version (xnet://authority/Name@version default). */
+declare const XNET_SCHEMA_VERSION = "1.0.0";
+/** Signed Yjs envelope wire version (SignedYjsEnvelopeV2). */
+declare const XNET_SYNC_ENVELOPE_VERSION = 2;
+/** y-protocols awareness profile version. */
+declare const XNET_AWARENESS_VERSION = 1;
+/** The L1 data-model version (Node shape + canonicalization contract). */
+declare const XNET_DATA_MODEL_VERSION = 1;
+/** UCAN capability-token profile pinned by this umbrella version. */
+declare const XNET_UCAN_PROFILE = "1.0";
+/**
+ * The per-subsystem versions bundled by one umbrella version. Implementations
+ * negotiate the umbrella `id`; this record documents what it expands to.
+ */
+interface XNetProtocolBundle {
+    /** Umbrella identifier advertised in the handshake, e.g. `"xnet/1.0"`. */
+    id: string;
+    /** L1 data-model version. */
+    dataModel: number;
+    /** Change-record protocol version (`CURRENT_PROTOCOL_VERSION`). */
+    change: number;
+    /** Signed Yjs envelope wire version. */
+    syncEnvelope: number;
+    /** Awareness profile version. */
+    awareness: number;
+    /** Default schema profile version. */
+    schema: string;
+    /**
+     * Default crypto signature level: 0 = Ed25519/X25519, 1 = hybrid (+ML-DSA),
+     * 2 = post-quantum. Level 0 is the only one required for baseline conformance.
+     */
+    cryptoLevel: number;
+    /** UCAN capability-token profile. */
+    ucan: string;
+}
+/**
+ * The current umbrella version this implementation speaks. The canonical
+ * version token is {@link XNET_PROTOCOL_VERSION.id} (`"xnet/1.0"`).
+ */
+declare const XNET_PROTOCOL_VERSION: XNetProtocolBundle;
+/**
+ * Every umbrella version this implementation can interoperate with, newest
+ * first. Older entries are added here (not removed) as the protocol evolves,
+ * so the handshake can advertise the full supported set.
+ */
+declare const XNET_SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
+/**
+ * Two peers are compatible when their advertised umbrella-version sets
+ * intersect. Returns the newest shared version id, or `null` when there is no
+ * overlap (the caller should then refuse with a typed version-mismatch rather
+ * than partially syncing — see `docs/specs/protocol/03-replication.md` §7).
+ */
+declare function negotiateProtocolVersion(ours: readonly string[], theirs: readonly string[]): string | null;
+/**
+ * Convenience: whether this implementation can interoperate with a peer that
+ * advertises `theirs`.
+ */
+declare function isProtocolCompatible(theirs: readonly string[]): boolean;
+
+export { type BlobStoreForSync, type ConnectionManager, type ConnectionManagerConfig, type ConnectionStatus, type CreateXNetClientOptions, type InitialSyncManager, type InitialSyncMessage, type LiveQuery, type LiveQueryValue, METABRIDGE_ORIGIN, METABRIDGE_SEED_ORIGIN, type MetaBridge, type MultiHubConnectionManagerConfig, type NodePool, type NodePoolConfig, NodeStoreSyncProvider, type NodeSyncResponse, type OfflineQueue, type OfflineQueueConfig, type PoolEntryState, type ProgressListener, type QueueEntry, type Registry, type RegistryConfig, type RegistryStorage, type SerializedNodeChange, type SyncManager, type SyncManagerConfig, type SyncPhase, type SyncProgress, type SyncReconciliationOptions, type SyncReconciliationReport, type SyncStatus, type TrackedNode, WebSocketSyncProvider, type WebSocketSyncProviderOptions, XNET_AWARENESS_VERSION, XNET_DATA_MODEL_VERSION, XNET_PROTOCOL_VERSION, XNET_SCHEMA_VERSION, XNET_SUPPORTED_PROTOCOL_VERSIONS, XNET_SYNC_ENVELOPE_VERSION, XNET_UCAN_PROFILE, type XNetClient, type XNetClientBridgeMode, type XNetClientPluginOptions, type XNetClientRuntimePhase, type XNetClientRuntimeStatus, type XNetClientSyncOptions, type XNetClientTelemetry, type XNetClientUndoOptions, type XNetProtocolBundle, createConnectionManager, createInitialSyncManager, createMetaBridge, createMultiHubConnectionManager, createNodePool, createOfflineQueue, createRegistry, createSyncManager, createXNetClient, isProtocolCompatible, liveQuery, negotiateProtocolVersion };