@backbay/glia 0.2.0-alpha.1

package/dist/hooks/usePlaySession.d.ts

@@ -0,0 +1,50 @@
+/**
+ * usePlaySession - Hook for managing play sessions with external environments
+ *
+ * Handles session lifecycle, LiveKit connections, and JSON-RPC calls to adapters.
+ */
+import type { PlaySessionData, PlaySessionStatus, JsonRpcResponse } from '../protocol/types.js';
+export interface UsePlaySessionOptions {
+    /** Adapter ID (e.g., 'openrct2', 'bbdoom') */
+    adapter: string;
+    /** Auto-connect on mount */
+    autoConnect?: boolean;
+    /** Connection timeout in ms */
+    timeout?: number;
+    /** Called when session is established */
+    onConnect?: (session: PlaySessionData) => void;
+    /** Called when session ends */
+    onDisconnect?: () => void;
+    /** Called on RPC result */
+    onRpcResult?: (response: JsonRpcResponse) => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+}
+export interface UsePlaySessionReturn {
+    /** Current session or null */
+    session: PlaySessionData | null;
+    /** Session status */
+    status: PlaySessionStatus;
+    /** LiveKit video track (for rendering) */
+    videoTrack: MediaStreamTrack | null;
+    /** LiveKit audio track */
+    audioTrack: MediaStreamTrack | null;
+    /** Make a JSON-RPC call */
+    call: <T = unknown>(method: string, params?: Record<string, unknown>) => Promise<JsonRpcResponse<T>>;
+    /** Shorthand for observe.* methods */
+    observe: <T = unknown>(key: string) => Promise<T>;
+    /** Shorthand for act.* methods */
+    act: <T = unknown>(action: string, params?: Record<string, unknown>) => Promise<T>;
+    /** Connect to the session */
+    connect: (options?: {
+        timeout?: number;
+    }) => Promise<void>;
+    /** Disconnect from the session */
+    disconnect: () => Promise<void>;
+    /** Whether currently connected */
+    isConnected: boolean;
+    /** Error message if any */
+    error: string | null;
+}
+export declare function usePlaySession({ adapter, autoConnect, timeout, onConnect, onDisconnect, onRpcResult, onError, }: UsePlaySessionOptions): UsePlaySessionReturn;
+//# sourceMappingURL=usePlaySession.d.ts.map

package/dist/hooks/usePlaySession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePlaySession.d.ts","sourceRoot":"","sources":["../../src/hooks/usePlaySession.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAOhG,MAAM,WAAW,qBAAqB;IACpC,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAEhB,4BAA4B;IAC5B,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,yCAAyC;IACzC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAC;IAE/C,+BAA+B;IAC/B,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAE1B,2BAA2B;IAC3B,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,IAAI,CAAC;IAElD,sBAAsB;IACtB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,oBAAoB;IACnC,8BAA8B;IAC9B,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IAEhC,qBAAqB;IACrB,MAAM,EAAE,iBAAiB,CAAC;IAE1B,0CAA0C;IAC1C,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAEpC,0BAA0B;IAC1B,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAEpC,2BAA2B;IAC3B,IAAI,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IAErG,sCAAsC;IACtC,OAAO,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAElD,kCAAkC;IAClC,GAAG,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAEnF,6BAA6B;IAC7B,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3D,kCAAkC;IAClC,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhC,kCAAkC;IAClC,WAAW,EAAE,OAAO,CAAC;IAErB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAMD,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,WAAmB,EACnB,OAAe,EACf,SAAS,EACT,YAAY,EACZ,WAAW,EACX,OAAO,GACR,EAAE,qBAAqB,GAAG,oBAAoB,CAgP9C"}

package/dist/hooks/usePlaySession.js

@@ -0,0 +1,208 @@
+/**
+ * usePlaySession - Hook for managing play sessions with external environments
+ *
+ * Handles session lifecycle, LiveKit connections, and JSON-RPC calls to adapters.
+ */
+import { useState, useCallback, useRef, useEffect } from 'react';
+import { useBBContext } from '../components/BBProvider.js';
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+export function usePlaySession({ adapter, autoConnect = false, timeout = 30000, onConnect, onDisconnect, onRpcResult, onError, }) {
+    const { config } = useBBContext();
+    // State
+    const [session, setSession] = useState(null);
+    const [status, setStatus] = useState('disconnected');
+    const [videoTrack, setVideoTrack] = useState(null);
+    const [audioTrack, setAudioTrack] = useState(null);
+    const [error, setError] = useState(null);
+    // Refs
+    const wsRef = useRef(null);
+    const rpcIdRef = useRef(0);
+    const pendingCallsRef = useRef(new Map());
+    // Connect to session
+    const connect = useCallback(async (options) => {
+        if (status === 'connecting' || status === 'connected')
+            return;
+        setStatus('connecting');
+        setError(null);
+        const connectTimeout = options?.timeout ?? timeout;
+        try {
+            // Create session via API
+            const response = await fetch(`${config.apiBaseUrl}/play-sessions`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...config.headers,
+                },
+                body: JSON.stringify({ adapter }),
+            });
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+            const sessionData = await response.json();
+            const newSession = {
+                id: sessionData.id,
+                adapter,
+                capabilityToken: sessionData.capabilityToken,
+                createdAt: Date.now(),
+                expiresAt: sessionData.expiresAt,
+                livekitUrl: sessionData.livekitUrl,
+                livekitToken: sessionData.livekitToken,
+            };
+            setSession(newSession);
+            // Connect WebSocket for RPC
+            const wsUrl = sessionData.wsUrl ?? `${config.apiBaseUrl.replace('http', 'ws')}/play-sessions/${newSession.id}/ws`;
+            const ws = new WebSocket(wsUrl);
+            wsRef.current = ws;
+            // Set up WebSocket handlers
+            await new Promise((resolve, reject) => {
+                const timeoutId = setTimeout(() => {
+                    ws.close();
+                    reject(new Error('Connection timeout'));
+                }, connectTimeout);
+                ws.onopen = () => {
+                    clearTimeout(timeoutId);
+                    resolve();
+                };
+                ws.onerror = () => {
+                    clearTimeout(timeoutId);
+                    reject(new Error('WebSocket connection failed'));
+                };
+            });
+            ws.onmessage = (event) => {
+                try {
+                    const message = JSON.parse(event.data);
+                    // Handle RPC response
+                    if ('id' in message && pendingCallsRef.current.has(message.id)) {
+                        const pending = pendingCallsRef.current.get(message.id);
+                        pendingCallsRef.current.delete(message.id);
+                        pending.resolve(message);
+                        onRpcResult?.(message);
+                    }
+                }
+                catch {
+                    // Ignore parse errors
+                }
+            };
+            ws.onclose = () => {
+                setStatus('disconnected');
+                setSession(null);
+                wsRef.current = null;
+                onDisconnect?.();
+            };
+            ws.onerror = () => {
+                setError('WebSocket error');
+                onError?.(new Error('WebSocket error'));
+            };
+            // Connect to LiveKit if available
+            if (newSession.livekitUrl && newSession.livekitToken) {
+                // Note: LiveKit connection would typically use @livekit/client-sdk
+                // For now, we just store the connection info for the consumer to use
+            }
+            setStatus('connected');
+            onConnect?.(newSession);
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : 'Connection failed';
+            setStatus('error');
+            setError(errorMessage);
+            onError?.(err instanceof Error ? err : new Error(errorMessage));
+        }
+    }, [adapter, config, status, timeout, onConnect, onDisconnect, onRpcResult, onError]);
+    // Disconnect
+    const disconnect = useCallback(async () => {
+        if (wsRef.current) {
+            wsRef.current.close();
+            wsRef.current = null;
+        }
+        // Optionally notify server
+        if (session) {
+            try {
+                await fetch(`${config.apiBaseUrl}/play-sessions/${session.id}`, {
+                    method: 'DELETE',
+                    headers: config.headers,
+                });
+            }
+            catch {
+                // Ignore errors on disconnect
+            }
+        }
+        setSession(null);
+        setStatus('disconnected');
+        setVideoTrack(null);
+        setAudioTrack(null);
+        onDisconnect?.();
+    }, [session, config, onDisconnect]);
+    // Make RPC call
+    const call = useCallback((method, params) => {
+        return new Promise((resolve, reject) => {
+            if (!wsRef.current || wsRef.current.readyState !== WebSocket.OPEN) {
+                reject(new Error('Not connected'));
+                return;
+            }
+            const id = ++rpcIdRef.current;
+            const request = {
+                jsonrpc: '2.0',
+                id,
+                method,
+                params: params ?? {},
+            };
+            pendingCallsRef.current.set(id, {
+                resolve: resolve,
+                reject,
+            });
+            wsRef.current.send(JSON.stringify(request));
+            // Timeout for RPC call
+            setTimeout(() => {
+                if (pendingCallsRef.current.has(id)) {
+                    pendingCallsRef.current.delete(id);
+                    reject(new Error('RPC call timeout'));
+                }
+            }, 30000);
+        });
+    }, []);
+    // Observe shorthand
+    const observe = useCallback(async (key) => {
+        const response = await call(`observe.${key}`);
+        if (response.error) {
+            throw new Error(response.error.message);
+        }
+        return response.result;
+    }, [call]);
+    // Act shorthand
+    const act = useCallback(async (action, params) => {
+        const response = await call(`act.${action}`, params);
+        if (response.error) {
+            throw new Error(response.error.message);
+        }
+        return response.result;
+    }, [call]);
+    // Auto-connect on mount
+    useEffect(() => {
+        if (autoConnect) {
+            connect();
+        }
+    }, [autoConnect]); // eslint-disable-line react-hooks/exhaustive-deps
+    // Cleanup on unmount
+    useEffect(() => {
+        return () => {
+            if (wsRef.current) {
+                wsRef.current.close();
+            }
+        };
+    }, []);
+    return {
+        session,
+        status,
+        videoTrack,
+        audioTrack,
+        call,
+        observe,
+        act,
+        connect,
+        disconnect,
+        isConnected: status === 'connected',
+        error,
+    };
+}

package/dist/hooks/useRunStream.d.ts

@@ -0,0 +1,39 @@
+/**
+ * useRunStream - Hook for streaming run events
+ *
+ * Implements dual EventSource + polling pattern for resilient real-time updates.
+ */
+import type { RunEvent, RunStatus, AgentRun } from '../protocol/types.js';
+export interface UseRunStreamOptions {
+    /** Polling interval in ms (default: 4000) */
+    pollInterval?: number;
+    /** Whether to use polling as primary (if EventSource unavailable) */
+    preferPolling?: boolean;
+    /** Called on each event */
+    onEvent?: (event: RunEvent) => void;
+    /** Called when run completes */
+    onComplete?: (run: AgentRun) => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+}
+export interface UseRunStreamReturn {
+    /** All received events */
+    events: RunEvent[];
+    /** Most recent event */
+    latestEvent: RunEvent | null;
+    /** Derived run status */
+    status: RunStatus;
+    /** Whether EventSource is connected */
+    isConnected: boolean;
+    /** Current run data (if available) */
+    run: AgentRun | null;
+    /** Manually disconnect */
+    disconnect: () => void;
+    /** Manually reconnect */
+    reconnect: () => void;
+}
+export declare function useRunStream(runId: string | null, options?: UseRunStreamOptions): UseRunStreamReturn;
+export declare function subscribeToRunEvents(apiBaseUrl: string, runId: string, callback: (event: RunEvent) => void, options?: {
+    headers?: Record<string, string>;
+}): () => void;
+//# sourceMappingURL=useRunStream.d.ts.map

package/dist/hooks/useRunStream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRunStream.d.ts","sourceRoot":"","sources":["../../src/hooks/useRunStream.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAO1E,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,qEAAqE;IACrE,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB,2BAA2B;IAC3B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;IAEpC,gCAAgC;IAChC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,CAAC;IAErC,sBAAsB;IACtB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IACjC,0BAA0B;IAC1B,MAAM,EAAE,QAAQ,EAAE,CAAC;IAEnB,wBAAwB;IACxB,WAAW,EAAE,QAAQ,GAAG,IAAI,CAAC;IAE7B,yBAAyB;IACzB,MAAM,EAAE,SAAS,CAAC;IAElB,uCAAuC;IACvC,WAAW,EAAE,OAAO,CAAC;IAErB,sCAAsC;IACtC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAErB,0BAA0B;IAC1B,UAAU,EAAE,MAAM,IAAI,CAAC;IAEvB,yBAAyB;IACzB,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAMD,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CA0NpB;AAMD,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,EACnC,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAO,GACjD,MAAM,IAAI,CA+BZ"}

package/dist/hooks/useRunStream.js

@@ -0,0 +1,230 @@
+/**
+ * useRunStream - Hook for streaming run events
+ *
+ * Implements dual EventSource + polling pattern for resilient real-time updates.
+ */
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { useBBContext } from '../components/BBProvider.js';
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+export function useRunStream(runId, options = {}) {
+    const { pollInterval = 4000, preferPolling = false, onEvent, onComplete, onError } = options;
+    const { config } = useBBContext();
+    const [events, setEvents] = useState([]);
+    const [latestEvent, setLatestEvent] = useState(null);
+    const [status, setStatus] = useState('idle');
+    const [isConnected, setIsConnected] = useState(false);
+    const [run, setRun] = useState(null);
+    const eventSourceRef = useRef(null);
+    const pollingIntervalRef = useRef(null);
+    const isActiveRef = useRef(true);
+    // Handle incoming event
+    const handleEvent = useCallback((event) => {
+        if (!isActiveRef.current)
+            return;
+        setEvents((prev) => [...prev, event]);
+        setLatestEvent(event);
+        onEvent?.(event);
+        // Update status from event
+        if (event.data?.status) {
+            setStatus(event.data.status);
+        }
+        // Handle completion events
+        if (event.type === 'completed' || event.type === 'failed' || event.type === 'cancelled') {
+            const finalStatus = event.type === 'completed'
+                ? 'completed'
+                : event.type === 'failed'
+                    ? 'failed'
+                    : 'cancelled';
+            setStatus(finalStatus);
+            if (event.data?.run) {
+                setRun(event.data.run);
+                if (event.type === 'completed') {
+                    onComplete?.(event.data.run);
+                }
+            }
+        }
+    }, [onEvent, onComplete]);
+    // Setup EventSource
+    const setupEventSource = useCallback(() => {
+        if (!runId || preferPolling)
+            return;
+        const url = `${config.apiBaseUrl}/runs/${runId}/events`;
+        const eventSource = new EventSource(url);
+        eventSource.onopen = () => {
+            setIsConnected(true);
+            handleEvent({
+                type: 'connected',
+                runId,
+                timestamp: Date.now(),
+            });
+        };
+        eventSource.onmessage = (e) => {
+            try {
+                const data = JSON.parse(e.data);
+                handleEvent({
+                    type: data.type ?? 'status',
+                    runId,
+                    timestamp: Date.now(),
+                    data,
+                });
+            }
+            catch (err) {
+                console.error('Failed to parse event:', err);
+            }
+        };
+        eventSource.onerror = () => {
+            setIsConnected(false);
+            // EventSource will auto-reconnect, but we'll start polling as fallback
+            startPolling();
+        };
+        eventSourceRef.current = eventSource;
+    }, [runId, config.apiBaseUrl, preferPolling, handleEvent]);
+    // Setup polling
+    const startPolling = useCallback(() => {
+        if (!runId || pollingIntervalRef.current)
+            return;
+        const poll = async () => {
+            if (!isActiveRef.current || !runId)
+                return;
+            try {
+                const response = await fetch(`${config.apiBaseUrl}/runs/${runId}`, {
+                    headers: config.headers,
+                });
+                if (!response.ok) {
+                    throw new Error(`HTTP ${response.status}`);
+                }
+                const data = await response.json();
+                handleEvent({
+                    type: 'status',
+                    runId,
+                    timestamp: Date.now(),
+                    data: {
+                        status: data.status,
+                        output: data.output,
+                        run: data,
+                    },
+                });
+                // Stop polling if run is complete
+                if (data.status === 'completed' || data.status === 'failed' || data.status === 'cancelled') {
+                    stopPolling();
+                    handleEvent({
+                        type: data.status,
+                        runId,
+                        timestamp: Date.now(),
+                        data: { run: data },
+                    });
+                }
+            }
+            catch (err) {
+                if (err instanceof Error) {
+                    onError?.(err);
+                }
+            }
+        };
+        // Initial poll
+        poll();
+        // Setup interval
+        pollingIntervalRef.current = setInterval(poll, pollInterval);
+    }, [runId, config, pollInterval, handleEvent, onError]);
+    const stopPolling = useCallback(() => {
+        if (pollingIntervalRef.current) {
+            clearInterval(pollingIntervalRef.current);
+            pollingIntervalRef.current = null;
+        }
+    }, []);
+    // Disconnect everything
+    const disconnect = useCallback(() => {
+        isActiveRef.current = false;
+        if (eventSourceRef.current) {
+            eventSourceRef.current.close();
+            eventSourceRef.current = null;
+        }
+        stopPolling();
+        setIsConnected(false);
+    }, [stopPolling]);
+    // Reconnect
+    const reconnect = useCallback(() => {
+        disconnect();
+        isActiveRef.current = true;
+        // Reset state
+        setEvents([]);
+        setLatestEvent(null);
+        setStatus('idle');
+        // Restart
+        if (preferPolling) {
+            startPolling();
+        }
+        else {
+            setupEventSource();
+        }
+    }, [disconnect, preferPolling, startPolling, setupEventSource]);
+    // Effect: Setup on mount / runId change
+    useEffect(() => {
+        if (!runId) {
+            disconnect();
+            return;
+        }
+        isActiveRef.current = true;
+        setEvents([]);
+        setLatestEvent(null);
+        setStatus('running');
+        if (preferPolling) {
+            startPolling();
+        }
+        else {
+            setupEventSource();
+            // Also start polling as fallback with longer interval
+            setTimeout(() => {
+                if (isActiveRef.current && !isConnected) {
+                    startPolling();
+                }
+            }, 2000);
+        }
+        return () => {
+            disconnect();
+        };
+    }, [runId]); // eslint-disable-line react-hooks/exhaustive-deps
+    return {
+        events,
+        latestEvent,
+        status,
+        isConnected,
+        run,
+        disconnect,
+        reconnect,
+    };
+}
+// =============================================================================
+// Utility: Subscribe to run events (non-hook version)
+// =============================================================================
+export function subscribeToRunEvents(apiBaseUrl, runId, callback, options = {}) {
+    const url = `${apiBaseUrl}/runs/${runId}/events`;
+    const eventSource = new EventSource(url);
+    eventSource.onopen = () => {
+        callback({
+            type: 'connected',
+            runId,
+            timestamp: Date.now(),
+        });
+    };
+    eventSource.onmessage = (e) => {
+        try {
+            const data = JSON.parse(e.data);
+            callback({
+                type: data.type ?? 'status',
+                runId,
+                timestamp: Date.now(),
+                data,
+            });
+        }
+        catch (err) {
+            console.error('Failed to parse event:', err);
+        }
+    };
+    eventSource.onerror = () => {
+        // EventSource handles reconnection automatically
+    };
+    return () => eventSource.close();
+}

package/dist/hooks/useSync.d.ts

@@ -0,0 +1,50 @@
+/**
+ * useSync - Offline-first sync hook with conflict resolution
+ *
+ * Implements the hybrid local+API sync pattern from Backbay.
+ */
+import type { SyncStatus, SyncConflict, ConflictResolution } from '../protocol/types.js';
+export interface UseSyncOptions<T> {
+    /** Unique key for localStorage */
+    key: string;
+    /** API endpoint for sync */
+    endpoint: string;
+    /** Debounce time in ms (default: 2000) */
+    debounce?: number;
+    /** Initial data */
+    initialData?: T;
+    /** Custom fetch function */
+    fetcher?: (endpoint: string) => Promise<T>;
+    /** Custom save function */
+    saver?: (endpoint: string, data: T) => Promise<T>;
+    /** Called when conflict is detected */
+    onConflict?: (conflict: SyncConflict<T>) => void;
+    /** Called on sync error */
+    onError?: (error: Error) => void;
+    /** Called on successful sync */
+    onSync?: (data: T) => void;
+}
+export interface UseSyncReturn<T> {
+    /** Current data */
+    data: T | null;
+    /** Update data locally (triggers debounced sync) */
+    setData: (data: T | ((prev: T | null) => T)) => void;
+    /** Current sync status */
+    status: SyncStatus;
+    /** Number of pending changes */
+    pendingChanges: number;
+    /** Timestamp of last successful sync */
+    lastSyncedAt: number | null;
+    /** Current conflict if status === 'conflict' */
+    conflict: SyncConflict<T> | null;
+    /** Resolve a conflict */
+    resolveConflict: (resolution: ConflictResolution) => Promise<void>;
+    /** Force immediate save (bypass debounce) */
+    forceSave: () => Promise<void>;
+    /** Refresh from server */
+    refresh: () => Promise<void>;
+    /** Whether initial load is complete */
+    isLoaded: boolean;
+}
+export declare function useSync<T>({ key, endpoint, debounce, initialData, fetcher, saver, onConflict, onError, onSync, }: UseSyncOptions<T>): UseSyncReturn<T>;
+//# sourceMappingURL=useSync.d.ts.map

package/dist/hooks/useSync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSync.d.ts","sourceRoot":"","sources":["../../src/hooks/useSync.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAMzF,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IAEZ,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IAEjB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,mBAAmB;IACnB,WAAW,CAAC,EAAE,CAAC,CAAC;IAEhB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAE3C,2BAA2B;IAC3B,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAElD,uCAAuC;IACvC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAEjD,2BAA2B;IAC3B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAEjC,gCAAgC;IAChC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,mBAAmB;IACnB,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IAEf,oDAAoD;IACpD,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC;IAErD,0BAA0B;IAC1B,MAAM,EAAE,UAAU,CAAC;IAEnB,gCAAgC;IAChC,cAAc,EAAE,MAAM,CAAC;IAEvB,wCAAwC;IACxC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B,gDAAgD;IAChD,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAEjC,yBAAyB;IACzB,eAAe,EAAE,CAAC,UAAU,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE,6CAA6C;IAC7C,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/B,0BAA0B;IAC1B,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7B,uCAAuC;IACvC,QAAQ,EAAE,OAAO,CAAC;CACnB;AAqGD,wBAAgB,OAAO,CAAC,CAAC,EAAE,EACzB,GAAG,EACH,QAAQ,EACR,QAAe,EACf,WAAW,EACX,OAAO,EACP,KAAK,EACL,UAAU,EACV,OAAO,EACP,MAAM,GACP,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAmStC"}