@pantheon-systems/puck-css 0.4.0

package/dist/collaboration/useBranchPresence.js

@@ -0,0 +1,94 @@
+/**
+ * useBranchPresence Hook
+ *
+ * Provides branch-level presence aggregation with polling.
+ */
+import { useState, useCallback, useEffect, useRef } from 'react';
+import { usePresenceContext } from '../core/PresenceContext.js';
+/**
+ * Hook for consuming branch-level presence data.
+ *
+ * @param options - Configuration options
+ * @returns Branch presence state and operations
+ *
+ * @example
+ * ```tsx
+ * function BranchCollaborators() {
+ *   const { presence, activeDocuments, totalActors } = useBranchPresence();
+ *
+ *   return (
+ *     <div>
+ *       <span>{totalActors} collaborators on this branch</span>
+ *       {activeDocuments.map(doc => (
+ *         <DocumentBadge key={doc.documentId} path={doc.documentPath} />
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useBranchPresence(options = {}) {
+    const { pollingInterval = 10000 } = options;
+    const { client, siteId, branchId } = usePresenceContext();
+    const [presence, setPresence] = useState(null);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(null);
+    // Track mounted state to avoid state updates after unmount
+    const mountedRef = useRef(true);
+    // Ref for fetchPresence to avoid restarting polling interval
+    const fetchPresenceRef = useRef(async () => { });
+    // Fetch presence data
+    const fetchPresence = useCallback(async () => {
+        try {
+            const branchPresence = await client.presence.getBranchPresence(siteId, branchId);
+            if (!mountedRef.current)
+                return;
+            setPresence(branchPresence);
+            setError(null);
+        }
+        catch (err) {
+            if (!mountedRef.current)
+                return;
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            if (mountedRef.current) {
+                setIsLoading(false);
+            }
+        }
+    }, [client, siteId, branchId]);
+    // Keep ref in sync with callback
+    useEffect(() => {
+        fetchPresenceRef.current = fetchPresence;
+    }, [fetchPresence]);
+    // Manual refresh function
+    const refresh = useCallback(async () => {
+        await fetchPresence();
+    }, [fetchPresence]);
+    // Initial fetch and polling
+    useEffect(() => {
+        mountedRef.current = true;
+        // Initial fetch
+        void fetchPresenceRef.current();
+        // Set up polling - use ref to avoid restarting interval when callback changes
+        const intervalId = setInterval(() => {
+            void fetchPresenceRef.current();
+        }, pollingInterval);
+        return () => {
+            mountedRef.current = false;
+            clearInterval(intervalId);
+        };
+    }, [pollingInterval]);
+    // Derived values
+    const activeDocuments = presence?.documentSummary ?? [];
+    const totalActors = presence?.summary.totalActors ?? 0;
+    return {
+        presence,
+        activeDocuments,
+        totalActors,
+        isLoading,
+        error,
+        refresh,
+    };
+}
+//# sourceMappingURL=useBranchPresence.js.map

package/dist/collaboration/useBranchPresence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBranchPresence.js","sourceRoot":"","sources":["../../src/collaboration/useBranchPresence.ts"],"names":[],"mappings":"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"}

package/dist/collaboration/useFocusRegionReporting.d.ts

@@ -0,0 +1,69 @@
+/**
+ * useFocusRegionReporting Hook
+ *
+ * Manages debounced reporting of focus regions to the backend.
+ * Used to inform the server which components a human has selected in the editor,
+ * enabling proactive collision detection before actual edits occur.
+ */
+/**
+ * Options for the useFocusRegionReporting hook.
+ */
+export interface UseFocusRegionReportingOptions {
+    /** Whether focus reporting is enabled (default: true) */
+    enabled?: boolean;
+    /** Debounce delay in ms before sending to server (default: 300) */
+    debounceMs?: number;
+    /** Heartbeat interval in ms to keep focus alive (default: 15000) */
+    heartbeatMs?: number;
+    /**
+     * Optional function to send focus regions via WebSocket.
+     * When provided and returns true, HTTP fallback is skipped.
+     * When returns false or not provided, falls back to HTTP.
+     * @param regions - Focus regions to send
+     * @returns true if sent successfully via WebSocket, false otherwise
+     */
+    sendViaWebSocket?: (regions: string[]) => boolean;
+}
+/**
+ * Return value for the useFocusRegionReporting hook.
+ */
+export interface UseFocusRegionReportingReturn {
+    /** Current focus regions (local state) */
+    focusRegions: string[];
+    /** Set the focus regions - triggers debounced report to server */
+    setFocusRegions: (regions: string[]) => void;
+    /** Clear all focus regions */
+    clearFocus: () => void;
+    /** Whether a report is currently in flight */
+    isReporting: boolean;
+}
+/**
+ * Hook for reporting focus regions to the backend.
+ *
+ * Manages debounced updates, heartbeat keep-alive, and cleanup on unmount.
+ * Focus regions tell the server which components the user has selected,
+ * allowing agents to avoid editing those regions proactively.
+ *
+ * @param options - Configuration options
+ * @returns Focus state and operations
+ *
+ * @example
+ * ```tsx
+ * function SelectionReporter() {
+ *   const { setFocusRegions, clearFocus } = useFocusRegionReporting();
+ *
+ *   // When Puck selection changes
+ *   useEffect(() => {
+ *     if (selectedItem) {
+ *       setFocusRegions([`/content/${selectedItem.index}`]);
+ *     } else {
+ *       clearFocus();
+ *     }
+ *   }, [selectedItem, setFocusRegions, clearFocus]);
+ *
+ *   return null;
+ * }
+ * ```
+ */
+export declare function useFocusRegionReporting(options?: UseFocusRegionReportingOptions): UseFocusRegionReportingReturn;
+//# sourceMappingURL=useFocusRegionReporting.d.ts.map

package/dist/collaboration/useFocusRegionReporting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFocusRegionReporting.d.ts","sourceRoot":"","sources":["../../src/collaboration/useFocusRegionReporting.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,yDAAyD;IACzD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC;CACnD;AAED;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,0CAA0C;IAC1C,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,kEAAkE;IAClE,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC7C,8BAA8B;IAC9B,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,8CAA8C;IAC9C,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,8BAAmC,GAC3C,6BAA6B,CAiM/B"}

package/dist/collaboration/useFocusRegionReporting.js

@@ -0,0 +1,199 @@
+/**
+ * useFocusRegionReporting Hook
+ *
+ * Manages debounced reporting of focus regions to the backend.
+ * Used to inform the server which components a human has selected in the editor,
+ * enabling proactive collision detection before actual edits occur.
+ */
+import { useState, useCallback, useEffect, useRef } from 'react';
+import { usePresenceContext } from '../core/PresenceContext.js';
+/**
+ * Hook for reporting focus regions to the backend.
+ *
+ * Manages debounced updates, heartbeat keep-alive, and cleanup on unmount.
+ * Focus regions tell the server which components the user has selected,
+ * allowing agents to avoid editing those regions proactively.
+ *
+ * @param options - Configuration options
+ * @returns Focus state and operations
+ *
+ * @example
+ * ```tsx
+ * function SelectionReporter() {
+ *   const { setFocusRegions, clearFocus } = useFocusRegionReporting();
+ *
+ *   // When Puck selection changes
+ *   useEffect(() => {
+ *     if (selectedItem) {
+ *       setFocusRegions([`/content/${selectedItem.index}`]);
+ *     } else {
+ *       clearFocus();
+ *     }
+ *   }, [selectedItem, setFocusRegions, clearFocus]);
+ *
+ *   return null;
+ * }
+ * ```
+ */
+export function useFocusRegionReporting(options = {}) {
+    const { enabled = true, debounceMs = 300, heartbeatMs = 15000, sendViaWebSocket } = options;
+    const { client, siteId, branchId, documentPath, userId } = usePresenceContext();
+    // Ref for sendViaWebSocket to avoid callback recreation
+    const sendViaWebSocketRef = useRef(sendViaWebSocket);
+    useEffect(() => {
+        sendViaWebSocketRef.current = sendViaWebSocket;
+    }, [sendViaWebSocket]);
+    // Local state
+    const [focusRegions, setFocusRegionsState] = useState([]);
+    const [isReporting, setIsReporting] = useState(false);
+    // Refs for managing timers and cleanup
+    const debounceTimerRef = useRef(null);
+    const heartbeatTimerRef = useRef(null);
+    const mountedRef = useRef(true);
+    const lastReportedRef = useRef(null);
+    const focusRegionsRef = useRef([]);
+    // Keep ref in sync with state
+    useEffect(() => {
+        focusRegionsRef.current = focusRegions;
+    }, [focusRegions]);
+    // Ref for reportFocusRegions to avoid restarting heartbeat interval
+    const reportFocusRegionsRef = useRef(async () => { });
+    /**
+     * Send focus regions to the server.
+     * Tries WebSocket first if available, falls back to HTTP.
+     */
+    const reportFocusRegions = useCallback(async (regions) => {
+        // Deduplicate - don't report if regions haven't changed
+        const serialized = JSON.stringify(regions);
+        if (serialized === lastReportedRef.current) {
+            return;
+        }
+        // Skip if disabled, unmounted, or no document path
+        if (!enabled || !mountedRef.current || !documentPath) {
+            return;
+        }
+        // Try WebSocket first if available, fall back to HTTP
+        if (sendViaWebSocketRef.current?.(regions)) {
+            lastReportedRef.current = serialized;
+            return;
+        }
+        // Fall back to HTTP
+        try {
+            setIsReporting(true);
+            await client.presence.updateFocusRegions(siteId, branchId, documentPath, userId, regions);
+            lastReportedRef.current = serialized;
+        }
+        catch {
+            // Silently handle errors - focus reporting is not critical
+            // Log for debugging if needed
+        }
+        finally {
+            if (mountedRef.current) {
+                setIsReporting(false);
+            }
+        }
+    }, [client, siteId, branchId, documentPath, userId, enabled]);
+    // Keep ref in sync with callback
+    useEffect(() => {
+        reportFocusRegionsRef.current = reportFocusRegions;
+    }, [reportFocusRegions]);
+    /**
+     * Set focus regions with debouncing.
+     */
+    const setFocusRegions = useCallback((regions) => {
+        // Update local state immediately
+        setFocusRegionsState(regions);
+        if (!enabled) {
+            return;
+        }
+        // Cancel any pending debounced call
+        if (debounceTimerRef.current) {
+            clearTimeout(debounceTimerRef.current);
+        }
+        // Schedule debounced report
+        debounceTimerRef.current = setTimeout(() => {
+            void reportFocusRegions(regions);
+        }, debounceMs);
+    }, [enabled, debounceMs, reportFocusRegions]);
+    /**
+     * Clear focus regions.
+     */
+    const clearFocus = useCallback(() => {
+        setFocusRegionsState([]);
+        if (!enabled) {
+            return;
+        }
+        // Cancel any pending debounced call
+        if (debounceTimerRef.current) {
+            clearTimeout(debounceTimerRef.current);
+        }
+        // Schedule debounced report
+        debounceTimerRef.current = setTimeout(() => {
+            void reportFocusRegions([]);
+        }, debounceMs);
+    }, [enabled, debounceMs, reportFocusRegions]);
+    // Heartbeat to keep focus alive
+    useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+        heartbeatTimerRef.current = setInterval(() => {
+            // Only send heartbeat if we have focus regions
+            if (focusRegionsRef.current.length > 0) {
+                // Reset lastReported to force the heartbeat through
+                const serialized = JSON.stringify(focusRegionsRef.current);
+                if (lastReportedRef.current === serialized) {
+                    // Same regions - force through by clearing last reported temporarily
+                    lastReportedRef.current = null;
+                }
+                void reportFocusRegionsRef.current(focusRegionsRef.current);
+            }
+        }, heartbeatMs);
+        return () => {
+            if (heartbeatTimerRef.current) {
+                clearInterval(heartbeatTimerRef.current);
+                heartbeatTimerRef.current = null;
+            }
+        };
+    }, [enabled, heartbeatMs]);
+    // Cleanup on unmount
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+            // Cancel pending debounced call
+            if (debounceTimerRef.current) {
+                clearTimeout(debounceTimerRef.current);
+                debounceTimerRef.current = null;
+            }
+            // Cancel heartbeat
+            if (heartbeatTimerRef.current) {
+                clearInterval(heartbeatTimerRef.current);
+                heartbeatTimerRef.current = null;
+            }
+            // Send final clear (fire-and-forget)
+            // Only if we have a document path to clear
+            if (enabled && documentPath) {
+                // Reset lastReported to ensure the clear goes through
+                lastReportedRef.current = null;
+                // Try WebSocket first if available
+                if (sendViaWebSocketRef.current?.([])) {
+                    return;
+                }
+                // Fall back to HTTP
+                void client.presence
+                    .updateFocusRegions(siteId, branchId, documentPath, userId, [])
+                    .catch(() => {
+                    // Ignore errors on unmount
+                });
+            }
+        };
+    }, [client, siteId, branchId, documentPath, userId, enabled]);
+    return {
+        focusRegions,
+        setFocusRegions,
+        clearFocus,
+        isReporting,
+    };
+}
+//# sourceMappingURL=useFocusRegionReporting.js.map

package/dist/collaboration/useFocusRegionReporting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFocusRegionReporting.js","sourceRoot":"","sources":["../../src/collaboration/useFocusRegionReporting.ts"],"names":[],"mappings":"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"}

package/dist/collaboration/usePresence.d.ts

@@ -0,0 +1,62 @@
+/**
+ * usePresence Hook
+ *
+ * Provides document-level presence information with polling.
+ */
+import type { ActorPresence } from '@pantheon-systems/css-client';
+/**
+ * Options for the usePresence hook.
+ */
+export interface UsePresenceOptions {
+    /** Polling interval in ms (default: 10000) */
+    pollingInterval?: number;
+    /** Include self in presence list (default: false) */
+    includeSelf?: boolean;
+}
+/**
+ * Return value for the usePresence hook.
+ */
+export interface UsePresenceReturn {
+    /** All actors present in the document */
+    actors: ActorPresence[];
+    /** Actors currently editing */
+    editingActors: ActorPresence[];
+    /** Human actors only */
+    humans: ActorPresence[];
+    /** Agent actors only */
+    agents: ActorPresence[];
+    /** Whether any human is actively editing */
+    hasActiveHumans: boolean;
+    /** Whether any agent is actively editing */
+    hasActiveAgents: boolean;
+    /** Loading state */
+    isLoading: boolean;
+    /** Error state */
+    error: Error | null;
+    /** Force refresh presence data */
+    refresh: () => Promise<void>;
+}
+/**
+ * Hook for consuming document-level presence data.
+ *
+ * @param options - Configuration options
+ * @returns Presence state and operations
+ *
+ * @example
+ * ```tsx
+ * function CollaboratorList() {
+ *   const { actors, hasActiveAgents } = usePresence();
+ *
+ *   return (
+ *     <div>
+ *       {hasActiveAgents && <span>Agents are working...</span>}
+ *       {actors.map(actor => (
+ *         <Avatar key={actor.id} name={actor.name} />
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function usePresence(options?: UsePresenceOptions): UsePresenceReturn;
+//# sourceMappingURL=usePresence.d.ts.map

package/dist/collaboration/usePresence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePresence.d.ts","sourceRoot":"","sources":["../../src/collaboration/usePresence.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAGlE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,+BAA+B;IAC/B,aAAa,EAAE,aAAa,EAAE,CAAC;IAC/B,wBAAwB;IACxB,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,wBAAwB;IACxB,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,4CAA4C;IAC5C,eAAe,EAAE,OAAO,CAAC;IACzB,4CAA4C;IAC5C,eAAe,EAAE,OAAO,CAAC;IACzB,oBAAoB;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,kBAAkB;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,kCAAkC;IAClC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,iBAAiB,CAyF/E"}

package/dist/collaboration/usePresence.js

@@ -0,0 +1,105 @@
+/**
+ * usePresence Hook
+ *
+ * Provides document-level presence information with polling.
+ */
+import { useState, useCallback, useEffect, useRef } from 'react';
+import { usePresenceContext } from '../core/PresenceContext.js';
+/**
+ * Hook for consuming document-level presence data.
+ *
+ * @param options - Configuration options
+ * @returns Presence state and operations
+ *
+ * @example
+ * ```tsx
+ * function CollaboratorList() {
+ *   const { actors, hasActiveAgents } = usePresence();
+ *
+ *   return (
+ *     <div>
+ *       {hasActiveAgents && <span>Agents are working...</span>}
+ *       {actors.map(actor => (
+ *         <Avatar key={actor.id} name={actor.name} />
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function usePresence(options = {}) {
+    const { pollingInterval = 10000, includeSelf = false } = options;
+    const { client, siteId, branchId, userId } = usePresenceContext();
+    const [actors, setActors] = useState([]);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(null);
+    // Track mounted state to avoid state updates after unmount
+    const mountedRef = useRef(true);
+    // Ref for fetchPresence to avoid restarting polling interval
+    const fetchPresenceRef = useRef(async () => { });
+    // Fetch presence data
+    const fetchPresence = useCallback(async () => {
+        try {
+            const branchPresence = await client.presence.getBranchPresence(siteId, branchId);
+            if (!mountedRef.current)
+                return;
+            // Filter actors - optionally exclude self
+            let filteredActors = branchPresence.actors;
+            if (!includeSelf) {
+                filteredActors = filteredActors.filter((actor) => actor.actorId !== userId);
+            }
+            setActors(filteredActors);
+            setError(null);
+        }
+        catch (err) {
+            if (!mountedRef.current)
+                return;
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            if (mountedRef.current) {
+                setIsLoading(false);
+            }
+        }
+    }, [client, siteId, branchId, userId, includeSelf]);
+    // Keep ref in sync with callback
+    useEffect(() => {
+        fetchPresenceRef.current = fetchPresence;
+    }, [fetchPresence]);
+    // Manual refresh function
+    const refresh = useCallback(async () => {
+        await fetchPresence();
+    }, [fetchPresence]);
+    // Initial fetch and polling
+    useEffect(() => {
+        mountedRef.current = true;
+        // Initial fetch
+        void fetchPresenceRef.current();
+        // Set up polling - use ref to avoid restarting interval when callback changes
+        const intervalId = setInterval(() => {
+            void fetchPresenceRef.current();
+        }, pollingInterval);
+        return () => {
+            mountedRef.current = false;
+            clearInterval(intervalId);
+        };
+    }, [pollingInterval]);
+    // Derived values
+    const editingActors = actors.filter((actor) => actor.state === 'editing');
+    const humans = actors.filter((actor) => actor.role === 'human');
+    const agents = actors.filter((actor) => actor.role === 'agent');
+    const hasActiveHumans = humans.some((actor) => actor.state === 'active' || actor.state === 'editing');
+    const hasActiveAgents = agents.some((actor) => actor.state === 'active' || actor.state === 'editing');
+    return {
+        actors,
+        editingActors,
+        humans,
+        agents,
+        hasActiveHumans,
+        hasActiveAgents,
+        isLoading,
+        error,
+        refresh,
+    };
+}
+//# sourceMappingURL=usePresence.js.map

package/dist/collaboration/usePresence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePresence.js","sourceRoot":"","sources":["../../src/collaboration/usePresence.ts"],"names":[],"mappings":"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"}

package/dist/collaboration/useSitePresence.d.ts

@@ -0,0 +1,54 @@
+/**
+ * useSitePresence Hook
+ *
+ * Provides site-level presence aggregation with polling.
+ */
+import type { SitePresence, BranchPresenceSummary } from '@pantheon-systems/css-client';
+/**
+ * Options for the useSitePresence hook.
+ */
+export interface UseSitePresenceOptions {
+    /** Polling interval in ms (default: 10000) */
+    pollingInterval?: number;
+}
+/**
+ * Return value for the useSitePresence hook.
+ */
+export interface UseSitePresenceReturn {
+    /** Site presence summary */
+    presence: SitePresence | null;
+    /** Branches with active collaborators */
+    activeBranches: BranchPresenceSummary[];
+    /** Total collaborators across site */
+    totalActors: number;
+    /** Loading state */
+    isLoading: boolean;
+    /** Error state */
+    error: Error | null;
+    /** Refresh presence data */
+    refresh: () => Promise<void>;
+}
+/**
+ * Hook for consuming site-level presence data.
+ *
+ * @param options - Configuration options
+ * @returns Site presence state and operations
+ *
+ * @example
+ * ```tsx
+ * function SiteCollaborators() {
+ *   const { presence, activeBranches, totalActors } = useSitePresence();
+ *
+ *   return (
+ *     <div>
+ *       <span>{totalActors} collaborators on this site</span>
+ *       {activeBranches.map(branch => (
+ *         <BranchBadge key={branch.branchId} name={branch.branchName} />
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useSitePresence(options?: UseSitePresenceOptions): UseSitePresenceReturn;
+//# sourceMappingURL=useSitePresence.d.ts.map

package/dist/collaboration/useSitePresence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSitePresence.d.ts","sourceRoot":"","sources":["../../src/collaboration/useSitePresence.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAGxF;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,8CAA8C;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,4BAA4B;IAC5B,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B,yCAAyC;IACzC,cAAc,EAAE,qBAAqB,EAAE,CAAC;IACxC,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,oBAAoB;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,kBAAkB;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,4BAA4B;IAC5B,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CAyEvB"}