@revealui/sync 0.0.0-canary-20260409021642

package/LICENSE

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

package/README.md

@@ -0,0 +1,201 @@
+# @revealui/sync
+
+ElectricSQL sync utilities for RevealUI — real-time data synchronization with local-first architecture.
+
+## Features
+
+- **ElectricSQL Integration**: Real-time sync via shape subscriptions
+- **React Hooks**: Subscribe to synced data in React components
+- **Mutations**: Create, update, and delete records via authenticated REST endpoints
+- **Type-safe**: Full TypeScript support with database types
+- **React Provider**: Easy setup with `ElectricProvider`
+- **Yjs Collaboration**: CRDT-based real-time collaborative editing
+
+## Installation
+
+```bash
+pnpm add @revealui/sync
+```
+
+## Usage
+
+### Setup Provider
+
+Wrap your app with `ElectricProvider`:
+
+```typescript
+import { ElectricProvider } from '@revealui/sync/provider'
+
+export default function App() {
+  return (
+    <ElectricProvider proxyBaseUrl="https://cms.revealui.com">
+      <YourComponents />
+    </ElectricProvider>
+  )
+}
+```
+
+### Read Synced Data
+
+Hooks subscribe to ElectricSQL shapes via authenticated proxy routes. Data updates in real-time as the database changes.
+
+```typescript
+import { useAgentContexts } from '@revealui/sync'
+
+function MyComponent() {
+  const { contexts, isLoading } = useAgentContexts()
+
+  if (isLoading) return <div>Loading...</div>
+
+  return (
+    <ul>
+      {contexts.map(context => (
+        <li key={context.id}>{JSON.stringify(context.context)}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+### Mutations
+
+Each hook returns `create`, `update`, and `remove` functions. Mutations go through authenticated REST endpoints at `/api/sync/*`. ElectricSQL picks up the database changes and pushes updates to all subscribers automatically.
+
+```typescript
+import { useAgentContexts } from '@revealui/sync'
+
+function CreateContext() {
+  const { contexts, create, update, remove } = useAgentContexts()
+
+  const handleCreate = async () => {
+    const result = await create({
+      agent_id: 'assistant',
+      context: { theme: 'dark', language: 'en' },
+      priority: 0.8,
+    })
+    if (!result.success) console.error(result.error)
+  }
+
+  const handleUpdate = async (id: string) => {
+    await update(id, { context: { theme: 'light' } })
+  }
+
+  const handleDelete = async (id: string) => {
+    await remove(id)
+  }
+
+  return <button onClick={handleCreate}>Create</button>
+}
+```
+
+## Available Hooks
+
+### `useAgentContexts()`
+
+Subscribe to agent contexts (task context, working memory).
+
+```typescript
+const {
+  contexts,    // AgentContextRecord[]
+  isLoading,   // boolean
+  error,       // Error | null
+  create,      // (data: CreateAgentContextInput) => Promise<MutationResult>
+  update,      // (id: string, data: UpdateAgentContextInput) => Promise<MutationResult>
+  remove,      // (id: string) => Promise<MutationResult>
+} = useAgentContexts()
+```
+
+### `useAgentMemory(agentId)`
+
+Subscribe to agent memory (episodic, semantic, working) filtered by agent ID.
+
+```typescript
+const {
+  memories,    // AgentMemoryRecord[]
+  isLoading,   // boolean
+  error,       // Error | null
+  create,      // (data: CreateAgentMemoryInput) => Promise<MutationResult>
+  update,      // (id: string, data: UpdateAgentMemoryInput) => Promise<MutationResult>
+  remove,      // (id: string) => Promise<MutationResult>
+} = useAgentMemory('assistant')
+```
+
+### `useConversations(userId)`
+
+Subscribe to conversation history. Server-side proxy enforces row-level filtering by session — the `userId` parameter is for API compatibility but filtering is handled server-side.
+
+```typescript
+const {
+  conversations,  // ConversationRecord[]
+  isLoading,      // boolean
+  error,          // Error | null
+  create,         // (data: CreateConversationInput) => Promise<MutationResult>
+  update,         // (id: string, data: UpdateConversationInput) => Promise<MutationResult>
+  remove,         // (id: string) => Promise<MutationResult>
+} = useConversations(userId)
+```
+
+## How It Works
+
+1. **Reads**: ElectricSQL shape subscriptions via authenticated CMS proxy (`/api/shapes/*`)
+2. **Writes**: REST mutations via CMS API (`/api/sync/*`) → Postgres → ElectricSQL replication
+3. **Real-time**: Database changes propagate to all shape subscribers automatically
+4. **Auth**: All endpoints require a valid session cookie
+
+## Collaboration (Yjs)
+
+The collab layer provides CRDT-based collaborative editing:
+
+```typescript
+import { useCollaboration } from '@revealui/sync'
+
+function Editor() {
+  const { doc, synced, connectedUsers } = useCollaboration({
+    documentId: 'doc-uuid',
+    serverUrl: 'ws://localhost:4000',
+  })
+  // ...
+}
+```
+
+Server-side agents can use `AgentCollabClient` from `@revealui/sync/collab/server`.
+
+## Environment Variables
+
+```env
+# ElectricSQL service URL (used by CMS proxy)
+ELECTRIC_SERVICE_URL=http://localhost:5133
+
+# Optional: Electric auth secret
+ELECTRIC_SECRET=your-secret
+
+# Client-side (stored in provider context)
+NEXT_PUBLIC_ELECTRIC_SERVICE_URL=http://localhost:5133
+```
+
+## Development
+
+```bash
+pnpm --filter @revealui/sync build      # Build
+pnpm --filter @revealui/sync dev        # Watch mode
+pnpm --filter @revealui/sync test       # Run tests
+pnpm --filter @revealui/sync typecheck  # Type check
+```
+
+## When to Use This
+
+- You need real-time data sync between your database and React UI via ElectricSQL
+- You want CRDT-based collaborative editing (Yjs) for multi-user document workflows
+- You need React hooks that subscribe to live database changes with automatic mutation support
+- **Not** for batch data loading or static pages — use server components with `@revealui/db` directly
+- **Not** for offline-first mobile apps — ElectricSQL targets web clients with persistent connections
+
+## JOSHUA Alignment
+
+- **Adaptive**: Shape subscriptions dynamically sync only the data your component needs — scales from one user to many
+- **Sovereign**: Sync runs through your own CMS proxy and PostgreSQL — no third-party real-time service required
+- **Hermetic**: All mutations go through authenticated REST endpoints; ElectricSQL replication is read-only on the client
+
+## License
+
+MIT

package/dist/collab/agent-client-factory.d.ts

@@ -0,0 +1,16 @@
+import { AgentCollabClient } from './agent-client.js';
+export interface CreateAgentClientOptions {
+    serverUrl: string;
+    documentId: string;
+    name?: string;
+    model?: string;
+    color?: string;
+    authToken?: string;
+    autoReconnect?: boolean;
+    defaultTextName?: string;
+}
+export declare function createAgentClient(options: CreateAgentClientOptions): AgentCollabClient;
+export declare function createAndConnectAgentClient(options: CreateAgentClientOptions & {
+    syncTimeoutMs?: number;
+}): Promise<AgentCollabClient>;
+//# sourceMappingURL=agent-client-factory.d.ts.map

package/dist/collab/agent-client-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-client-factory.d.ts","sourceRoot":"","sources":["../../src/collab/agent-client-factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAsB,MAAM,mBAAmB,CAAC;AAI1E,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CAgBtF;AAED,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,wBAAwB,GAAG;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7D,OAAO,CAAC,iBAAiB,CAAC,CAK5B"}

package/dist/collab/agent-client-factory.js

@@ -0,0 +1,24 @@
+import { AgentCollabClient } from './agent-client.js';
+const DEFAULT_AGENT_COLOR = '#8B5CF6';
+export function createAgentClient(options) {
+    const identity = {
+        type: 'agent',
+        name: options.name ?? 'AI Agent',
+        model: options.model ?? 'unknown',
+        color: options.color ?? DEFAULT_AGENT_COLOR,
+    };
+    return new AgentCollabClient({
+        serverUrl: options.serverUrl,
+        documentId: options.documentId,
+        identity,
+        authToken: options.authToken,
+        autoReconnect: options.autoReconnect,
+        defaultTextName: options.defaultTextName,
+    });
+}
+export async function createAndConnectAgentClient(options) {
+    const client = createAgentClient(options);
+    client.connect();
+    await client.waitForSync(options.syncTimeoutMs ?? 5000);
+    return client;
+}

package/dist/collab/agent-client.d.ts

@@ -0,0 +1,56 @@
+import { Observable } from 'lib0/observable';
+import * as awarenessProtocol from 'y-protocols/awareness';
+import * as Y from 'yjs';
+export interface AgentIdentity {
+    type: 'agent';
+    name: string;
+    model: string;
+    color: string;
+}
+export interface AgentCollabClientOptions {
+    serverUrl: string;
+    documentId: string;
+    identity: AgentIdentity;
+    authToken?: string;
+    autoReconnect?: boolean;
+    defaultTextName?: string;
+}
+export declare class AgentCollabClient extends Observable<string> {
+    readonly doc: Y.Doc;
+    readonly awareness: awarenessProtocol.Awareness;
+    private readonly serverUrl;
+    private readonly documentId;
+    private readonly identity;
+    private readonly authToken?;
+    private readonly autoReconnect;
+    private readonly defaultTextName;
+    private ws;
+    private synced;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private updateHandler;
+    private awarenessUpdateHandler;
+    private destroyed;
+    private pendingSyncAbort;
+    constructor(options: AgentCollabClientOptions);
+    connect(): void;
+    disconnect(): void;
+    getDocument(): Y.Doc;
+    getText(name?: string): Y.Text;
+    getTextContent(name?: string): string;
+    insertText(index: number, content: string, name?: string): void;
+    deleteText(index: number, length: number, name?: string): void;
+    replaceAll(content: string, name?: string): void;
+    onUpdate(callback: (update: Uint8Array) => void): () => void;
+    getConnectedUsers(): Map<number, Record<string, unknown>>;
+    waitForSync(timeoutMs?: number): Promise<void>;
+    destroy(): void;
+    private buildWebSocketUrl;
+    private handleOpen;
+    private handleMessage;
+    private handleClose;
+    private handleError;
+    private scheduleReconnect;
+    private cancelReconnect;
+}
+//# sourceMappingURL=agent-client.d.ts.map

package/dist/collab/agent-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-client.d.ts","sourceRoot":"","sources":["../../src/collab/agent-client.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,KAAK,iBAAiB,MAAM,uBAAuB,CAAC;AAE3D,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAOzB,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,aAAa,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,iBAAkB,SAAQ,UAAU,CAAC,MAAM,CAAC;IACvD,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC,SAAS,CAAC;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IACxC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IAEzC,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,aAAa,CAAgE;IACrF,OAAO,CAAC,sBAAsB,CAGpB;IACV,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,gBAAgB,CAA6B;gBAEzC,OAAO,EAAE,wBAAwB;IA0B7C,OAAO,IAAI,IAAI;IAcf,UAAU,IAAI,IAAI;IAkBlB,WAAW,IAAI,CAAC,CAAC,GAAG;IAIpB,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI;IAI9B,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM;IAIrC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAI/D,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAI9D,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAQhD,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI;IAU5D,iBAAiB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAUzD,WAAW,CAAC,SAAS,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA+B5C,OAAO,IAAI,IAAI;IAUf,OAAO,CAAC,iBAAiB;IAazB,OAAO,CAAC,UAAU;IAoClB,OAAO,CAAC,aAAa;IAoCrB,OAAO,CAAC,WAAW;IAenB,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,iBAAiB;IAezB,OAAO,CAAC,eAAe;CAOxB"}

package/dist/collab/agent-client.js

@@ -0,0 +1,262 @@
+import * as decoding from 'lib0/decoding';
+import * as encoding from 'lib0/encoding';
+import { Observable } from 'lib0/observable';
+import WebSocket from 'ws';
+import * as awarenessProtocol from 'y-protocols/awareness';
+import * as syncProtocol from 'y-protocols/sync';
+import * as Y from 'yjs';
+import { MESSAGE_AWARENESS, MESSAGE_SYNC } from './protocol-constants.js';
+const MAX_RECONNECT_ATTEMPTS = 5;
+const BASE_RECONNECT_DELAY = 1000;
+const RECONNECT_MULTIPLIER = 2;
+export class AgentCollabClient extends Observable {
+    doc;
+    awareness;
+    serverUrl;
+    documentId;
+    identity;
+    authToken;
+    autoReconnect;
+    defaultTextName;
+    ws = null;
+    synced = false;
+    reconnectAttempts = 0;
+    reconnectTimer = null;
+    updateHandler = null;
+    awarenessUpdateHandler;
+    destroyed = false;
+    pendingSyncAbort = null;
+    constructor(options) {
+        super();
+        this.serverUrl = options.serverUrl;
+        this.documentId = options.documentId;
+        this.identity = options.identity;
+        this.authToken = options.authToken;
+        this.autoReconnect = options.autoReconnect ?? true;
+        this.defaultTextName = options.defaultTextName ?? 'content';
+        this.doc = new Y.Doc();
+        this.awareness = new awarenessProtocol.Awareness(this.doc);
+        this.awarenessUpdateHandler = ({ added, updated, removed }, origin) => {
+            if (origin === 'remote')
+                return;
+            const changedClients = added.concat(updated, removed);
+            const update = awarenessProtocol.encodeAwarenessUpdate(this.awareness, changedClients);
+            const encoder = encoding.createEncoder();
+            encoding.writeVarUint(encoder, MESSAGE_AWARENESS);
+            encoding.writeVarUint8Array(encoder, update);
+            if (this.ws?.readyState === WebSocket.OPEN) {
+                this.ws.send(encoding.toUint8Array(encoder));
+            }
+        };
+        this.awareness.on('update', this.awarenessUpdateHandler);
+    }
+    connect() {
+        if (this.ws || this.destroyed)
+            return;
+        const url = this.buildWebSocketUrl();
+        this.ws = new WebSocket(url);
+        this.emit('status', [{ status: 'connecting' }]);
+        this.ws.on('open', () => this.handleOpen());
+        this.ws.on('message', (data) => this.handleMessage(data));
+        this.ws.on('close', () => this.handleClose());
+        this.ws.on('error', (err) => this.handleError(err));
+    }
+    disconnect() {
+        this.cancelReconnect();
+        if (this.updateHandler) {
+            this.doc.off('update', this.updateHandler);
+            this.updateHandler = null;
+        }
+        awarenessProtocol.removeAwarenessStates(this.awareness, [this.doc.clientID], 'local');
+        if (this.ws) {
+            this.ws.removeAllListeners();
+            this.ws.close();
+            this.ws = null;
+        }
+        this.synced = false;
+        this.emit('status', [{ status: 'disconnected' }]);
+    }
+    getDocument() {
+        return this.doc;
+    }
+    getText(name) {
+        return this.doc.getText(name ?? this.defaultTextName);
+    }
+    getTextContent(name) {
+        return this.getText(name).toString();
+    }
+    insertText(index, content, name) {
+        this.getText(name).insert(index, content);
+    }
+    deleteText(index, length, name) {
+        this.getText(name).delete(index, length);
+    }
+    replaceAll(content, name) {
+        const text = this.getText(name);
+        this.doc.transact(() => {
+            text.delete(0, text.length);
+            text.insert(0, content);
+        });
+    }
+    onUpdate(callback) {
+        const handler = (update, origin) => {
+            if (origin !== this) {
+                callback(update);
+            }
+        };
+        this.doc.on('update', handler);
+        return () => this.doc.off('update', handler);
+    }
+    getConnectedUsers() {
+        const users = new Map();
+        for (const [clientId, state] of this.awareness.getStates()) {
+            if (state && typeof state === 'object') {
+                users.set(clientId, state);
+            }
+        }
+        return users;
+    }
+    waitForSync(timeoutMs = 5000) {
+        if (this.synced)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                clearTimeout(timeout);
+                this.off('sync', handler);
+                if (this.pendingSyncAbort === abort)
+                    this.pendingSyncAbort = null;
+            };
+            const timeout = setTimeout(() => {
+                cleanup();
+                reject(new Error(`Sync timeout after ${timeoutMs}ms`));
+            }, timeoutMs);
+            const handler = (isSynced) => {
+                if (isSynced) {
+                    cleanup();
+                    resolve();
+                }
+            };
+            const abort = () => {
+                cleanup();
+                reject(new Error('Client destroyed while waiting for sync'));
+            };
+            this.pendingSyncAbort = abort;
+            this.on('sync', handler);
+        });
+    }
+    destroy() {
+        this.destroyed = true;
+        this.pendingSyncAbort?.();
+        this.awareness.off('update', this.awarenessUpdateHandler);
+        this.disconnect();
+        this.awareness.destroy();
+        this.doc.destroy();
+        super.destroy();
+    }
+    buildWebSocketUrl() {
+        const params = new URLSearchParams({
+            name: this.identity.name,
+            color: this.identity.color,
+            type: 'agent',
+            agentModel: this.identity.model,
+        });
+        if (this.authToken) {
+            params.set('token', this.authToken);
+        }
+        return `${this.serverUrl}/ws/collab/${this.documentId}?${params.toString()}`;
+    }
+    handleOpen() {
+        this.reconnectAttempts = 0;
+        this.emit('status', [{ status: 'connected' }]);
+        const encoder = encoding.createEncoder();
+        encoding.writeVarUint(encoder, MESSAGE_SYNC);
+        syncProtocol.writeSyncStep1(encoder, this.doc);
+        this.ws?.send(encoding.toUint8Array(encoder));
+        this.awareness.setLocalState({
+            name: this.identity.name,
+            color: this.identity.color,
+            type: 'agent',
+            agentModel: this.identity.model,
+        });
+        const awarenessUpdate = awarenessProtocol.encodeAwarenessUpdate(this.awareness, [
+            this.doc.clientID,
+        ]);
+        const awarenessEncoder = encoding.createEncoder();
+        encoding.writeVarUint(awarenessEncoder, MESSAGE_AWARENESS);
+        encoding.writeVarUint8Array(awarenessEncoder, awarenessUpdate);
+        this.ws?.send(encoding.toUint8Array(awarenessEncoder));
+        this.updateHandler = (update, origin) => {
+            if (origin === this)
+                return;
+            const updateEncoder = encoding.createEncoder();
+            encoding.writeVarUint(updateEncoder, MESSAGE_SYNC);
+            syncProtocol.writeUpdate(updateEncoder, update);
+            if (this.ws?.readyState === WebSocket.OPEN) {
+                this.ws.send(encoding.toUint8Array(updateEncoder));
+            }
+        };
+        this.doc.on('update', this.updateHandler);
+    }
+    handleMessage(data) {
+        const uint8 = data instanceof ArrayBuffer
+            ? new Uint8Array(data)
+            : Array.isArray(data)
+                ? new Uint8Array(Buffer.concat(data))
+                : new Uint8Array(data);
+        const decoder = decoding.createDecoder(uint8);
+        const messageType = decoding.readVarUint(decoder);
+        if (messageType === MESSAGE_SYNC) {
+            const responseEncoder = encoding.createEncoder();
+            encoding.writeVarUint(responseEncoder, MESSAGE_SYNC);
+            const syncMessageType = syncProtocol.readSyncMessage(decoder, responseEncoder, this.doc, this);
+            if (encoding.length(responseEncoder) > 1) {
+                this.ws?.send(encoding.toUint8Array(responseEncoder));
+            }
+            if (syncMessageType === 1 && !this.synced) {
+                this.synced = true;
+            }
+            this.emit('sync', [true]);
+        }
+        else if (messageType === MESSAGE_AWARENESS) {
+            const update = decoding.readVarUint8Array(decoder);
+            awarenessProtocol.applyAwarenessUpdate(this.awareness, update, 'remote');
+            this.emit('awareness', [this.getConnectedUsers()]);
+        }
+    }
+    handleClose() {
+        if (this.updateHandler) {
+            this.doc.off('update', this.updateHandler);
+            this.updateHandler = null;
+        }
+        this.ws = null;
+        this.synced = false;
+        this.emit('sync', [false]);
+        this.emit('status', [{ status: 'disconnected' }]);
+        if (this.autoReconnect && !this.destroyed) {
+            this.scheduleReconnect();
+        }
+    }
+    handleError(err) {
+        this.emit('error', [err]);
+        this.ws?.close();
+    }
+    scheduleReconnect() {
+        if (this.reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
+            this.emit('status', [{ status: 'failed' }]);
+            return;
+        }
+        const delay = BASE_RECONNECT_DELAY * RECONNECT_MULTIPLIER ** this.reconnectAttempts;
+        this.reconnectAttempts++;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, delay);
+    }
+    cancelReconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.reconnectAttempts = 0;
+    }
+}

package/dist/collab/index.d.ts

@@ -0,0 +1,8 @@
+export { MESSAGE_AWARENESS, MESSAGE_SYNC } from './protocol-constants.js';
+export type { CollabDocumentState } from './use-collab-document.js';
+export { useCollabDocument } from './use-collab-document.js';
+export type { CollaborationIdentity, UseCollaborationOptions, UseCollaborationResult, } from './use-collaboration.js';
+export { useCollaboration } from './use-collaboration.js';
+export type { UserPresence } from './yjs-websocket-provider.js';
+export { CollabProvider } from './yjs-websocket-provider.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/collab/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/collab/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC1E,YAAY,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EACV,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/collab/index.js

@@ -0,0 +1,4 @@
+export { MESSAGE_AWARENESS, MESSAGE_SYNC } from './protocol-constants.js';
+export { useCollabDocument } from './use-collab-document.js';
+export { useCollaboration } from './use-collaboration.js';
+export { CollabProvider } from './yjs-websocket-provider.js';

package/dist/collab/protocol-constants.d.ts

@@ -0,0 +1,5 @@
+/** Yjs sync protocol message type */
+export declare const MESSAGE_SYNC = 0;
+/** Yjs awareness protocol message type */
+export declare const MESSAGE_AWARENESS = 1;
+//# sourceMappingURL=protocol-constants.d.ts.map

package/dist/collab/protocol-constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-constants.d.ts","sourceRoot":"","sources":["../../src/collab/protocol-constants.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,eAAO,MAAM,YAAY,IAAI,CAAC;AAE9B,0CAA0C;AAC1C,eAAO,MAAM,iBAAiB,IAAI,CAAC"}

package/dist/collab/protocol-constants.js

@@ -0,0 +1,4 @@
+/** Yjs sync protocol message type */
+export const MESSAGE_SYNC = 0;
+/** Yjs awareness protocol message type */
+export const MESSAGE_AWARENESS = 1;

package/dist/collab/server-index.d.ts

@@ -0,0 +1,6 @@
+export type { AgentCollabClientOptions, AgentIdentity } from './agent-client.js';
+export { AgentCollabClient } from './agent-client.js';
+export type { CreateAgentClientOptions } from './agent-client-factory.js';
+export { createAgentClient, createAndConnectAgentClient } from './agent-client-factory.js';
+export { MESSAGE_AWARENESS, MESSAGE_SYNC } from './protocol-constants.js';
+//# sourceMappingURL=server-index.d.ts.map

package/dist/collab/server-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-index.d.ts","sourceRoot":"","sources":["../../src/collab/server-index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,EAAE,iBAAiB,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AAC3F,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/collab/server-index.js

@@ -0,0 +1,3 @@
+export { AgentCollabClient } from './agent-client.js';
+export { createAgentClient, createAndConnectAgentClient } from './agent-client-factory.js';
+export { MESSAGE_AWARENESS, MESSAGE_SYNC } from './protocol-constants.js';

package/dist/collab/use-collab-document.d.ts

@@ -0,0 +1,8 @@
+export interface CollabDocumentState {
+    initialState: Uint8Array | null;
+    connectedClients: number;
+    isLoading: boolean;
+    error: Error | null;
+}
+export declare function useCollabDocument(documentId: string): CollabDocumentState;
+//# sourceMappingURL=use-collab-document.d.ts.map

package/dist/collab/use-collab-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-collab-document.d.ts","sourceRoot":"","sources":["../../src/collab/use-collab-document.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,UAAU,GAAG,IAAI,CAAC;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAKD,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,mBAAmB,CAiDzE"}