@cloudsignal/collaborate 0.1.0

package/dist/index.js

@@ -0,0 +1,1153 @@
+import { createContext, useState, useRef, useEffect, useMemo, useCallback, useContext } from 'react';
+import CloudSignalClient from '@cloudsignal/mqtt-client';
+import { jsx, jsxs } from 'react/jsx-runtime';
+
+/**
+ * @cloudsignal/collaborate v0.1.0
+ * Real-time collaboration primitives for React
+ * https://cloudsignal.io
+ * MIT License
+ */
+
+var SpaceContext = createContext(null);
+
+// src/utils/colors.ts
+var CURSOR_COLORS = [
+  "#3B82F6",
+  // Blue
+  "#EF4444",
+  // Red
+  "#22C55E",
+  // Green
+  "#A855F7",
+  // Purple
+  "#F97316",
+  // Orange
+  "#EC4899",
+  // Pink
+  "#14B8A6",
+  // Teal
+  "#EAB308",
+  // Yellow
+  "#6366F1",
+  // Indigo
+  "#F43F5E"
+  // Rose
+];
+function getColorForUser(userId) {
+  let hash = 0;
+  for (let i = 0; i < userId.length; i++) {
+    hash = (hash << 5) - hash + userId.charCodeAt(i) | 0;
+  }
+  return CURSOR_COLORS[Math.abs(hash) % CURSOR_COLORS.length];
+}
+function getInitials(name) {
+  return name.split(/\s+/).map((w) => w[0]).filter(Boolean).slice(0, 2).join("").toUpperCase();
+}
+
+// src/constants.ts
+var TOPIC_PREFIX = "$spaces";
+var TOPICS = {
+  PRESENCE: "presence",
+  CURSORS: "cursors",
+  LOCKS: "locks",
+  TYPING: "typing",
+  REACTIONS: "reactions",
+  BROADCAST: "broadcast",
+  STATE: "state"
+};
+var DEFAULTS = {
+  /** Presence heartbeat interval (ms) */
+  PRESENCE_HEARTBEAT_MS: 1e4,
+  /** Time before a user is considered offline (ms) */
+  PRESENCE_TIMEOUT_MS: 3e4,
+  /** Cursor publish throttle (ms) — ~33Hz */
+  CURSOR_THROTTLE_MS: 30,
+  /** Time before a cursor fades out (ms) */
+  CURSOR_STALE_MS: 3e3,
+  /** Typing indicator auto-reset (ms) */
+  TYPING_TIMEOUT_MS: 3e3,
+  /** Minimum interval between typing publishes (ms) */
+  TYPING_THROTTLE_MS: 2e3,
+  /** Time before a typing user is cleaned from the list (ms) */
+  TYPING_STALE_MS: 4e3,
+  /** How long a reaction stays visible (ms) */
+  REACTION_DURATION_MS: 3e3,
+  /** Max visible reactions at once */
+  REACTION_MAX_VISIBLE: 20,
+  /** Stats sync interval (ms) — for cursor count etc. */
+  STATS_TICK_MS: 1e3,
+  /** Opacity fade-out sync interval (ms) */
+  FADE_TICK_MS: 200
+};
+function spaceTopic(spaceId, segment) {
+  return `${TOPIC_PREFIX}/${spaceId}/${segment}`;
+}
+function spaceWildcard(spaceId) {
+  return `${TOPIC_PREFIX}/${spaceId}/#`;
+}
+function Space({
+  id,
+  connection,
+  userName,
+  userColor,
+  userAvatar,
+  userData,
+  debug = false,
+  presenceHeartbeatMs = DEFAULTS.PRESENCE_HEARTBEAT_MS,
+  presenceTimeoutMs = DEFAULTS.PRESENCE_TIMEOUT_MS,
+  onConnectionChange,
+  children
+}) {
+  const [isConnected, setIsConnected] = useState(false);
+  const [isConnecting, setIsConnecting] = useState(false);
+  const [error, setError] = useState(null);
+  const clientRef = useRef(null);
+  const connectingRef = useRef(false);
+  const mountedRef = useRef(true);
+  const handlersRef = useRef(/* @__PURE__ */ new Map());
+  const messageHandlerRef = useRef(null);
+  const onConnectionChangeRef = useRef(onConnectionChange);
+  useEffect(() => {
+    onConnectionChangeRef.current = onConnectionChange;
+  }, [onConnectionChange]);
+  const resolvedColor = userColor || getColorForUser(userName);
+  const self = useMemo(() => ({
+    userId: connection.username || userName,
+    name: userName,
+    color: resolvedColor,
+    avatar: userAvatar,
+    data: userData,
+    joinedAt: Date.now(),
+    lastSeen: Date.now()
+  }), [connection.username, userName, resolvedColor, userAvatar, userData]);
+  const selfRef = useRef(self);
+  useEffect(() => {
+    selfRef.current = self;
+  }, [self]);
+  const log = useCallback((...args) => {
+    if (debug) console.log("[CloudSignal:Space]", ...args);
+  }, [debug]);
+  const addTopicHandler = useCallback((segment, handler) => {
+    if (!handlersRef.current.has(segment)) {
+      handlersRef.current.set(segment, /* @__PURE__ */ new Set());
+    }
+    handlersRef.current.get(segment).add(handler);
+    return () => {
+      handlersRef.current.get(segment)?.delete(handler);
+    };
+  }, []);
+  const routeMessage = useCallback((topic, messageStr) => {
+    const prefix = `${TOPIC_PREFIX}/${id}/`;
+    if (!topic.startsWith(prefix)) return;
+    const subtopic = topic.slice(prefix.length);
+    const segment = subtopic.split("/")[0];
+    let payload;
+    try {
+      payload = JSON.parse(messageStr);
+    } catch {
+      payload = messageStr;
+    }
+    log("\u2190", segment, subtopic);
+    const handlers = handlersRef.current.get(segment);
+    if (handlers) {
+      for (const handler of handlers) {
+        handler(subtopic, payload);
+      }
+    }
+  }, [id, log]);
+  const publish = useCallback((subtopic, payload, options) => {
+    if (!clientRef.current) {
+      log("Cannot publish: not connected");
+      return;
+    }
+    const topic = spaceTopic(id, subtopic);
+    const message = typeof payload === "string" ? payload : JSON.stringify(payload);
+    clientRef.current.transmit(topic, message, options);
+    log("\u2192", subtopic);
+  }, [id, log]);
+  useEffect(() => {
+    if (!isConnected) return;
+    const sendHeartbeat = () => {
+      publish(TOPICS.PRESENCE, {
+        userId: selfRef.current.userId,
+        name: selfRef.current.name,
+        color: selfRef.current.color,
+        avatar: selfRef.current.avatar,
+        data: selfRef.current.data,
+        ts: Date.now()
+      });
+    };
+    sendHeartbeat();
+    const interval = setInterval(sendHeartbeat, presenceHeartbeatMs);
+    return () => clearInterval(interval);
+  }, [isConnected, publish, presenceHeartbeatMs]);
+  useEffect(() => {
+    if (!isConnected) return;
+    const handleUnload = () => {
+      publish(TOPICS.PRESENCE, {
+        userId: selfRef.current.userId,
+        type: "leave",
+        ts: Date.now()
+      });
+    };
+    window.addEventListener("beforeunload", handleUnload);
+    return () => window.removeEventListener("beforeunload", handleUnload);
+  }, [isConnected, publish]);
+  useEffect(() => {
+    mountedRef.current = true;
+    const doConnect = async () => {
+      if (connectingRef.current || clientRef.current) return;
+      connectingRef.current = true;
+      setIsConnecting(true);
+      setError(null);
+      try {
+        const clientOptions = {
+          debug,
+          preset: "desktop"
+        };
+        if (connection.tokenServiceUrl) {
+          clientOptions.tokenServiceUrl = connection.tokenServiceUrl;
+        }
+        const client = new CloudSignalClient(clientOptions);
+        client.onConnectionStatusChange = (connected) => {
+          log("Connection:", connected);
+          if (mountedRef.current) {
+            setIsConnected(connected);
+            onConnectionChangeRef.current?.(connected);
+          }
+        };
+        client.onReconnecting = (attempt) => {
+          log("Reconnecting, attempt:", attempt);
+        };
+        client.onAuthError = (err) => {
+          log("Auth error:", err.message);
+          if (mountedRef.current) {
+            setError(err);
+            setIsConnected(false);
+          }
+          clientRef.current = null;
+        };
+        const handler = (topic, message) => routeMessage(topic, message);
+        messageHandlerRef.current = handler;
+        client.onMessage(handler);
+        const willPayload = JSON.stringify({
+          userId: selfRef.current.userId,
+          type: "leave",
+          ts: Date.now()
+        });
+        if (connection.secretKey || connection.externalToken) {
+          await client.connectWithToken({
+            host: connection.host,
+            organizationId: connection.organizationId,
+            secretKey: connection.secretKey,
+            externalToken: connection.externalToken,
+            willTopic: spaceTopic(id, TOPICS.PRESENCE),
+            willMessage: willPayload,
+            willQos: 0
+          });
+        } else {
+          await client.connect({
+            host: connection.host,
+            username: connection.username,
+            password: connection.password,
+            willTopic: spaceTopic(id, TOPICS.PRESENCE),
+            willMessage: willPayload,
+            willQos: 0
+          });
+        }
+        if (!mountedRef.current) {
+          client.destroy();
+          return;
+        }
+        clientRef.current = client;
+        await client.subscribe(spaceWildcard(id), 0);
+        log("Subscribed to", spaceWildcard(id));
+      } catch (err) {
+        log("Connection failed:", err);
+        if (mountedRef.current) {
+          setError(err instanceof Error ? err : new Error(String(err)));
+        }
+      } finally {
+        connectingRef.current = false;
+        if (mountedRef.current) setIsConnecting(false);
+      }
+    };
+    doConnect();
+    return () => {
+      mountedRef.current = false;
+      if (clientRef.current) {
+        try {
+          const leaveTopic = spaceTopic(id, TOPICS.PRESENCE);
+          const leavePayload = JSON.stringify({
+            userId: selfRef.current.userId,
+            type: "leave",
+            ts: Date.now()
+          });
+          clientRef.current.transmit(leaveTopic, leavePayload, { qos: 0 });
+        } catch {
+        }
+        clientRef.current.destroy();
+        clientRef.current = null;
+      }
+    };
+  }, [id, connection.host, connection.username, connection.password, connection.secretKey, connection.externalToken, connection.organizationId]);
+  const contextValue = useMemo(() => ({
+    spaceId: id,
+    self,
+    isConnected,
+    isConnecting,
+    error,
+    presenceTimeoutMs,
+    publish,
+    addTopicHandler
+  }), [id, self, isConnected, isConnecting, error, presenceTimeoutMs, publish, addTopicHandler]);
+  return /* @__PURE__ */ jsx(SpaceContext.Provider, { value: contextValue, children });
+}
+function useSpace() {
+  const ctx = useContext(SpaceContext);
+  if (!ctx) {
+    throw new Error(
+      'useSpace() must be used within a <Space> provider. Wrap your component tree with <Space id="..." connection={...}>'
+    );
+  }
+  return ctx;
+}
+function usePresence() {
+  const { self, addTopicHandler, presenceTimeoutMs } = useSpace();
+  const [members, setMembers] = useState([self]);
+  const membersMapRef = useRef(/* @__PURE__ */ new Map());
+  const joinCallbacksRef = useRef(/* @__PURE__ */ new Set());
+  const leaveCallbacksRef = useRef(/* @__PURE__ */ new Set());
+  useEffect(() => {
+    membersMapRef.current.set(self.userId, self);
+    setMembers([self]);
+  }, [self]);
+  useEffect(() => {
+    const unsubscribe = addTopicHandler(TOPICS.PRESENCE, (_subtopic, payload) => {
+      if (typeof payload !== "object" || payload === null) return;
+      const data = payload;
+      const userId = data.userId;
+      if (!userId) return;
+      if (data.type === "leave") {
+        const user2 = membersMapRef.current.get(userId);
+        if (user2) {
+          membersMapRef.current.delete(userId);
+          setMembers(Array.from(membersMapRef.current.values()));
+          for (const cb of leaveCallbacksRef.current) cb(user2);
+        }
+        return;
+      }
+      const isNew = !membersMapRef.current.has(userId);
+      const user = {
+        userId,
+        name: data.name || userId,
+        color: data.color || "#3B82F6",
+        avatar: data.avatar,
+        data: data.data,
+        joinedAt: isNew ? Date.now() : membersMapRef.current.get(userId)?.joinedAt ?? Date.now(),
+        lastSeen: Date.now()
+      };
+      membersMapRef.current.set(userId, user);
+      setMembers(Array.from(membersMapRef.current.values()));
+      if (isNew) {
+        for (const cb of joinCallbacksRef.current) cb(user);
+      }
+    });
+    return unsubscribe;
+  }, [addTopicHandler]);
+  useEffect(() => {
+    const interval = setInterval(() => {
+      const now = Date.now();
+      let changed = false;
+      for (const [userId, user] of membersMapRef.current) {
+        if (userId === self.userId) continue;
+        if (now - user.lastSeen > presenceTimeoutMs) {
+          membersMapRef.current.delete(userId);
+          changed = true;
+          for (const cb of leaveCallbacksRef.current) cb(user);
+        }
+      }
+      if (changed) {
+        setMembers(Array.from(membersMapRef.current.values()));
+      }
+    }, 5e3);
+    return () => clearInterval(interval);
+  }, [self.userId, presenceTimeoutMs]);
+  const onJoin = useCallback((callback) => {
+    joinCallbacksRef.current.add(callback);
+    return () => {
+      joinCallbacksRef.current.delete(callback);
+    };
+  }, []);
+  const onLeave = useCallback((callback) => {
+    leaveCallbacksRef.current.add(callback);
+    return () => {
+      leaveCallbacksRef.current.delete(callback);
+    };
+  }, []);
+  return {
+    members,
+    count: members.length,
+    self,
+    onJoin,
+    onLeave
+  };
+}
+function useCursors(options = {}) {
+  const {
+    throttleMs = DEFAULTS.CURSOR_THROTTLE_MS,
+    staleMs = DEFAULTS.CURSOR_STALE_MS
+  } = options;
+  const { self, publish, addTopicHandler } = useSpace();
+  const cursorsRef = useRef(/* @__PURE__ */ new Map());
+  const onUpdateRef = useRef(null);
+  const lastPublishRef = useRef(0);
+  const throttleMsRef = useRef(throttleMs);
+  const [cursors, setCursors] = useState([]);
+  useEffect(() => {
+    throttleMsRef.current = throttleMs;
+  }, [throttleMs]);
+  useEffect(() => {
+    const unsubscribe = addTopicHandler(TOPICS.CURSORS, (_subtopic, payload) => {
+      if (typeof payload !== "object" || payload === null) return;
+      const data = payload;
+      const userId = data.userId;
+      if (!userId || userId === self.userId) return;
+      const now = Date.now();
+      cursorsRef.current.set(userId, {
+        userId,
+        name: data.name || userId,
+        x: data.x || 0,
+        y: data.y || 0,
+        color: data.color || "#3B82F6",
+        ts: data.ts || now,
+        lastSeen: now
+      });
+      onUpdateRef.current?.();
+    });
+    return unsubscribe;
+  }, [addTopicHandler, self.userId]);
+  const publishCursor = useCallback((x, y) => {
+    const now = Date.now();
+    if (now - lastPublishRef.current < throttleMsRef.current) return;
+    lastPublishRef.current = now;
+    publish(TOPICS.CURSORS, {
+      userId: self.userId,
+      name: self.name,
+      x,
+      y,
+      color: self.color,
+      ts: now
+    }, { qos: 0 });
+  }, [publish, self.userId, self.name, self.color]);
+  useEffect(() => {
+    const interval = setInterval(() => {
+      const now = Date.now();
+      let changed = false;
+      for (const [id, cursor] of cursorsRef.current) {
+        if (now - cursor.lastSeen > staleMs) {
+          cursorsRef.current.delete(id);
+          changed = true;
+        }
+      }
+      if (changed) {
+        onUpdateRef.current?.();
+      }
+      setCursors(Array.from(cursorsRef.current.values()));
+    }, DEFAULTS.STATS_TICK_MS);
+    return () => clearInterval(interval);
+  }, [staleMs]);
+  return {
+    cursorsRef,
+    onUpdateRef,
+    cursors,
+    publishCursor
+  };
+}
+function useLock(componentId) {
+  const { self, publish, addTopicHandler } = useSpace();
+  const [lockedBy, setLockedBy] = useState(null);
+  const lockedByRef = useRef(null);
+  const isLockedByMeRef = useRef(false);
+  const publishRef = useRef(publish);
+  const selfUserIdRef = useRef(self.userId);
+  useEffect(() => {
+    publishRef.current = publish;
+  }, [publish]);
+  useEffect(() => {
+    selfUserIdRef.current = self.userId;
+  }, [self.userId]);
+  const isLocked = lockedBy !== null;
+  const isLockedByMe = lockedBy?.userId === self.userId;
+  useEffect(() => {
+    const unsubscribe = addTopicHandler(TOPICS.LOCKS, (_subtopic, payload) => {
+      if (typeof payload !== "object" || payload === null) return;
+      const data = payload;
+      if (data.componentId !== componentId) return;
+      const action = data.action;
+      if (action === "lock") {
+        const user = {
+          userId: data.userId,
+          name: data.name || data.userId,
+          color: data.color || "#3B82F6",
+          joinedAt: Date.now(),
+          lastSeen: Date.now()
+        };
+        lockedByRef.current = user;
+        isLockedByMeRef.current = user.userId === self.userId;
+        setLockedBy(user);
+      } else if (action === "unlock") {
+        lockedByRef.current = null;
+        isLockedByMeRef.current = false;
+        setLockedBy(null);
+      }
+    });
+    return unsubscribe;
+  }, [addTopicHandler, componentId, self.userId]);
+  const lock = useCallback(() => {
+    if (lockedByRef.current && lockedByRef.current.userId !== self.userId) return;
+    publish(TOPICS.LOCKS, {
+      userId: self.userId,
+      name: self.name,
+      color: self.color,
+      componentId,
+      action: "lock",
+      ts: Date.now()
+    }, { qos: 1 });
+  }, [publish, self, componentId]);
+  const unlock = useCallback(() => {
+    if (!isLockedByMeRef.current) return;
+    publish(TOPICS.LOCKS, {
+      userId: self.userId,
+      componentId,
+      action: "unlock",
+      ts: Date.now()
+    }, { qos: 1 });
+  }, [publish, self.userId, componentId]);
+  useEffect(() => {
+    return () => {
+      if (isLockedByMeRef.current) {
+        publishRef.current(TOPICS.LOCKS, {
+          userId: selfUserIdRef.current,
+          componentId,
+          action: "unlock",
+          ts: Date.now()
+        }, { qos: 1 });
+      }
+    };
+  }, [componentId]);
+  return { isLocked, lockedBy, isLockedByMe, lock, unlock };
+}
+function useTypingIndicator(inputId) {
+  const { self, publish, addTopicHandler } = useSpace();
+  const [typingUsers, setTypingUsers] = useState([]);
+  const [isTyping, setIsTyping] = useState(false);
+  const typingMapRef = useRef(/* @__PURE__ */ new Map());
+  const lastPublishRef = useRef(0);
+  const stopTimerRef = useRef(null);
+  useEffect(() => {
+    const unsubscribe = addTopicHandler(TOPICS.TYPING, (_subtopic, payload) => {
+      if (typeof payload !== "object" || payload === null) return;
+      const data = payload;
+      const userId = data.userId;
+      if (!userId || userId === self.userId) return;
+      if (inputId && data.inputId !== inputId) return;
+      const isCurrentlyTyping = data.isTyping;
+      if (isCurrentlyTyping) {
+        typingMapRef.current.set(userId, {
+          userId,
+          name: data.name || userId,
+          color: data.color || "#3B82F6",
+          joinedAt: Date.now(),
+          lastSeen: Date.now()
+        });
+      } else {
+        typingMapRef.current.delete(userId);
+      }
+      setTypingUsers(Array.from(typingMapRef.current.values()));
+    });
+    return unsubscribe;
+  }, [addTopicHandler, self.userId, inputId]);
+  useEffect(() => {
+    const interval = setInterval(() => {
+      const now = Date.now();
+      let changed = false;
+      for (const [userId, user] of typingMapRef.current) {
+        if (now - user.lastSeen > DEFAULTS.TYPING_STALE_MS) {
+          typingMapRef.current.delete(userId);
+          changed = true;
+        }
+      }
+      if (changed) {
+        setTypingUsers(Array.from(typingMapRef.current.values()));
+      }
+    }, 2e3);
+    return () => clearInterval(interval);
+  }, []);
+  const publishTyping = useCallback((typing) => {
+    publish(TOPICS.TYPING, {
+      userId: self.userId,
+      name: self.name,
+      color: self.color,
+      inputId,
+      isTyping: typing,
+      ts: Date.now()
+    }, { qos: 0 });
+  }, [publish, self, inputId]);
+  const startTyping = useCallback(() => {
+    const now = Date.now();
+    if (now - lastPublishRef.current >= DEFAULTS.TYPING_THROTTLE_MS) {
+      lastPublishRef.current = now;
+      publishTyping(true);
+    }
+    setIsTyping(true);
+    if (stopTimerRef.current) clearTimeout(stopTimerRef.current);
+    stopTimerRef.current = setTimeout(() => {
+      publishTyping(false);
+      setIsTyping(false);
+    }, DEFAULTS.TYPING_TIMEOUT_MS);
+  }, [publishTyping]);
+  const stopTyping = useCallback(() => {
+    if (stopTimerRef.current) {
+      clearTimeout(stopTimerRef.current);
+      stopTimerRef.current = null;
+    }
+    publishTyping(false);
+    setIsTyping(false);
+  }, [publishTyping]);
+  const publishTypingRef = useRef(publishTyping);
+  useEffect(() => {
+    publishTypingRef.current = publishTyping;
+  }, [publishTyping]);
+  useEffect(() => {
+    return () => {
+      if (stopTimerRef.current) {
+        clearTimeout(stopTimerRef.current);
+        publishTypingRef.current(false);
+      }
+    };
+  }, []);
+  return { typingUsers, startTyping, stopTyping, isTyping };
+}
+
+// src/utils/uid.ts
+function shortId() {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID().slice(0, 8);
+  }
+  return Math.random().toString(36).slice(2, 10);
+}
+
+// src/hooks/useReactions.ts
+function useReactions(options = {}) {
+  const {
+    maxVisible = DEFAULTS.REACTION_MAX_VISIBLE,
+    durationMs = DEFAULTS.REACTION_DURATION_MS
+  } = options;
+  const { self, publish, addTopicHandler } = useSpace();
+  const [reactions, setReactions] = useState([]);
+  const timersRef = useRef(/* @__PURE__ */ new Map());
+  const addReaction = useCallback((reaction) => {
+    const positioned = reaction.x != null ? reaction : { ...reaction, x: Math.random() * 80 + 10 };
+    setReactions((prev) => {
+      const next = [...prev, positioned];
+      return next.length > maxVisible ? next.slice(-maxVisible) : next;
+    });
+    const timer = setTimeout(() => {
+      setReactions((prev) => prev.filter((r) => r.id !== reaction.id));
+      timersRef.current.delete(reaction.id);
+    }, durationMs);
+    timersRef.current.set(reaction.id, timer);
+  }, [maxVisible, durationMs]);
+  useEffect(() => {
+    const unsubscribe = addTopicHandler(TOPICS.REACTIONS, (_subtopic, payload) => {
+      if (typeof payload !== "object" || payload === null) return;
+      const data = payload;
+      if (!data.emoji) return;
+      if (data.userId === self.userId) return;
+      addReaction({
+        id: data.id || shortId(),
+        userId: data.userId || "",
+        name: data.name || "",
+        emoji: data.emoji,
+        color: data.color || "#3B82F6",
+        ts: data.ts || Date.now()
+      });
+    });
+    return unsubscribe;
+  }, [addTopicHandler, addReaction, self.userId]);
+  const sendReaction = useCallback((emoji) => {
+    const reaction = {
+      id: shortId(),
+      userId: self.userId,
+      name: self.name,
+      emoji,
+      color: self.color,
+      ts: Date.now()
+    };
+    publish(TOPICS.REACTIONS, reaction, { qos: 0 });
+    addReaction(reaction);
+  }, [publish, self, addReaction]);
+  useEffect(() => {
+    return () => {
+      for (const timer of timersRef.current.values()) {
+        clearTimeout(timer);
+      }
+    };
+  }, []);
+  return { reactions, sendReaction };
+}
+function useBroadcast(event) {
+  const { publish, addTopicHandler } = useSpace();
+  const [lastMessage, setLastMessage] = useState(null);
+  const callbacksRef = useRef(/* @__PURE__ */ new Set());
+  useEffect(() => {
+    const unsubscribe = addTopicHandler(TOPICS.BROADCAST, (subtopic, payload) => {
+      const eventName = subtopic.includes("/") ? subtopic.split("/").slice(1).join("/") : void 0;
+      if (event && eventName !== event) return;
+      const data = payload;
+      setLastMessage(data);
+      for (const cb of callbacksRef.current) {
+        cb(data);
+      }
+    });
+    return unsubscribe;
+  }, [addTopicHandler, event]);
+  const broadcast = useCallback((data) => {
+    const subtopic = event ? `${TOPICS.BROADCAST}/${event}` : TOPICS.BROADCAST;
+    publish(subtopic, data, { qos: 0 });
+  }, [publish, event]);
+  const onMessage = useCallback((callback) => {
+    callbacksRef.current.add(callback);
+    return () => {
+      callbacksRef.current.delete(callback);
+    };
+  }, []);
+  return { broadcast, lastMessage, onMessage };
+}
+
+// src/utils/lww.ts
+function lwwMerge(current, incoming) {
+  return incoming.ts > current.ts ? incoming : current;
+}
+
+// src/hooks/useSharedState.ts
+function useSharedState(key, initialValue) {
+  const { self, publish, addTopicHandler } = useSpace();
+  const [value, setValue] = useState(initialValue);
+  const entryRef = useRef({
+    value: initialValue,
+    ts: 0,
+    userId: self.userId
+  });
+  useEffect(() => {
+    `${TOPICS.STATE}/${key}`;
+    const unsubscribe = addTopicHandler(TOPICS.STATE, (incomingSubtopic, payload) => {
+      const incomingKey = incomingSubtopic.includes("/") ? incomingSubtopic.split("/").slice(1).join("/") : void 0;
+      if (incomingKey !== key) return;
+      if (typeof payload !== "object" || payload === null) return;
+      const data = payload;
+      const incoming = {
+        value: data.value,
+        ts: data.ts || 0,
+        userId: data.userId || ""
+      };
+      const merged = lwwMerge(entryRef.current, incoming);
+      if (merged !== entryRef.current) {
+        entryRef.current = merged;
+        setValue(merged.value);
+      }
+    });
+    return unsubscribe;
+  }, [addTopicHandler, key]);
+  const update = useCallback((newValue) => {
+    const ts = Date.now();
+    const entry = { value: newValue, ts, userId: self.userId };
+    entryRef.current = entry;
+    setValue(newValue);
+    publish(`${TOPICS.STATE}/${key}`, {
+      value: newValue,
+      ts,
+      userId: self.userId
+    }, { qos: 1, retain: true });
+  }, [publish, key, self.userId]);
+  return [value, update];
+}
+function AvatarStack({ max = 5, size = 32, className = "" }) {
+  const { members } = usePresence();
+  const visible = members.slice(0, max);
+  const overflow = members.length - max;
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className,
+      style: { display: "flex", alignItems: "center" },
+      children: /* @__PURE__ */ jsxs("div", { style: { display: "flex", flexDirection: "row-reverse" }, children: [
+        overflow > 0 && /* @__PURE__ */ jsxs(
+          "div",
+          {
+            style: {
+              width: size,
+              height: size,
+              borderRadius: "50%",
+              backgroundColor: "#6B7280",
+              color: "white",
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              fontSize: size * 0.35,
+              fontWeight: 600,
+              border: "2px solid white",
+              marginLeft: -size * 0.25,
+              position: "relative",
+              zIndex: 0
+            },
+            children: [
+              "+",
+              overflow
+            ]
+          }
+        ),
+        visible.map((user, i) => /* @__PURE__ */ jsx(
+          "div",
+          {
+            title: user.name,
+            style: {
+              width: size,
+              height: size,
+              borderRadius: "50%",
+              backgroundColor: user.color,
+              color: "white",
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              fontSize: size * 0.35,
+              fontWeight: 600,
+              border: "2px solid white",
+              marginLeft: i === visible.length - 1 ? 0 : -size * 0.25,
+              position: "relative",
+              zIndex: visible.length - i,
+              overflow: "hidden"
+            },
+            children: user.avatar ? /* @__PURE__ */ jsx(
+              "img",
+              {
+                src: user.avatar,
+                alt: user.name,
+                style: { width: "100%", height: "100%", objectFit: "cover" }
+              }
+            ) : getInitials(user.name)
+          },
+          user.userId
+        ))
+      ] })
+    }
+  );
+}
+function CursorOverlay({
+  throttleMs,
+  staleMs = DEFAULTS.CURSOR_STALE_MS,
+  className = "",
+  children
+}) {
+  const { cursorsRef, onUpdateRef, publishCursor } = useCursors({ throttleMs, staleMs });
+  const containerRef = useRef(null);
+  const wrapperRef = useRef(null);
+  const nodesRef = useRef(/* @__PURE__ */ new Map());
+  const syncDOM = useCallback(() => {
+    const container = containerRef.current;
+    const wrapper = wrapperRef.current;
+    if (!container || !wrapper) return;
+    const w = container.clientWidth;
+    const h = container.clientHeight;
+    const now = Date.now();
+    const cursors = cursorsRef.current;
+    for (const [id, node] of nodesRef.current) {
+      if (!cursors.has(id)) {
+        node.remove();
+        nodesRef.current.delete(id);
+      }
+    }
+    for (const [id, cursor] of cursors) {
+      const age = now - cursor.lastSeen;
+      const opacity = age > 1e3 ? Math.max(0, 1 - (age - 1e3) / (staleMs - 1e3)) : 1;
+      let node = nodesRef.current.get(id);
+      if (!node) {
+        node = createCursorNode(cursor);
+        wrapper.appendChild(node);
+        nodesRef.current.set(id, node);
+      }
+      node.style.transform = `translate(${cursor.x * w}px, ${cursor.y * h}px)`;
+      node.style.opacity = String(opacity);
+    }
+  }, [cursorsRef, staleMs]);
+  useEffect(() => {
+    onUpdateRef.current = syncDOM;
+    return () => {
+      onUpdateRef.current = null;
+    };
+  }, [onUpdateRef, syncDOM]);
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    const observer = new ResizeObserver(() => syncDOM());
+    observer.observe(container);
+    return () => observer.disconnect();
+  }, [syncDOM]);
+  useEffect(() => {
+    const interval = setInterval(syncDOM, DEFAULTS.FADE_TICK_MS);
+    return () => clearInterval(interval);
+  }, [syncDOM]);
+  const handleMouseMove = useCallback((e) => {
+    const container = containerRef.current;
+    if (!container) return;
+    const rect = container.getBoundingClientRect();
+    const x = (e.clientX - rect.left) / rect.width;
+    const y = (e.clientY - rect.top) / rect.height;
+    publishCursor(x, y);
+  }, [publishCursor]);
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ref: containerRef,
+      className,
+      style: { position: "relative", overflow: "hidden" },
+      onMouseMove: handleMouseMove,
+      children: [
+        children,
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            ref: wrapperRef,
+            style: {
+              position: "absolute",
+              inset: 0,
+              pointerEvents: "none",
+              zIndex: 50
+            }
+          }
+        )
+      ]
+    }
+  );
+}
+function createCursorNode(cursor) {
+  const node = document.createElement("div");
+  node.style.position = "absolute";
+  node.style.left = "0";
+  node.style.top = "0";
+  node.style.pointerEvents = "none";
+  node.style.transition = "transform 30ms linear";
+  node.innerHTML = `
+    <svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg" style="transform: translate(-2px, -2px)">
+      <path d="M3 3L10.07 19.97L12.58 12.58L19.97 10.07L3 3Z" fill="${cursor.color}" stroke="white" stroke-width="1.5" stroke-linejoin="round"/>
+    </svg>
+    <div style="margin-left: 16px; margin-top: 4px; white-space: nowrap; border-radius: 4px; padding: 2px 6px; font-size: 12px; font-weight: 500; color: white; background-color: ${cursor.color}; box-shadow: 0 1px 2px rgba(0,0,0,0.1);">${escapeHtml(cursor.name)}</div>
+  `;
+  return node;
+}
+function escapeHtml(str) {
+  const div = document.createElement("div");
+  div.textContent = str;
+  return div.innerHTML;
+}
+function TypingIndicator({ inputId, className = "" }) {
+  const { typingUsers } = useTypingIndicator(inputId);
+  if (typingUsers.length === 0) {
+    return /* @__PURE__ */ jsx("div", { className, style: { minHeight: "1.25rem" } });
+  }
+  let text;
+  if (typingUsers.length === 1) {
+    text = `${typingUsers[0].name} is typing...`;
+  } else if (typingUsers.length === 2) {
+    text = `${typingUsers[0].name} and ${typingUsers[1].name} are typing...`;
+  } else {
+    text = `${typingUsers.length} people are typing...`;
+  }
+  return /* @__PURE__ */ jsx("div", { className, style: { minHeight: "1.25rem" }, children: /* @__PURE__ */ jsxs("span", { style: { display: "inline-flex", alignItems: "center", gap: "4px" }, children: [
+    /* @__PURE__ */ jsx(TypingDots, {}),
+    text
+  ] }) });
+}
+function TypingDots() {
+  return /* @__PURE__ */ jsxs("span", { style: { display: "inline-flex", gap: "2px", alignItems: "center" }, children: [
+    [0, 1, 2].map((i) => /* @__PURE__ */ jsx(
+      "span",
+      {
+        style: {
+          width: 4,
+          height: 4,
+          borderRadius: "50%",
+          backgroundColor: "currentColor",
+          opacity: 0.6,
+          animation: `cs-typing-dot 1.4s infinite`,
+          animationDelay: `${i * 0.2}s`
+        }
+      },
+      i
+    )),
+    /* @__PURE__ */ jsx("style", { children: `
+        @keyframes cs-typing-dot {
+          0%, 80%, 100% { opacity: 0.3; transform: scale(0.8); }
+          40% { opacity: 1; transform: scale(1); }
+        }
+      ` })
+  ] });
+}
+function LockIndicator({ componentId, className = "", children }) {
+  const { isLocked, lockedBy, isLockedByMe } = useLock(componentId);
+  const borderColor = isLocked ? isLockedByMe ? lockedBy?.color || "#3B82F6" : lockedBy?.color || "#EF4444" : "transparent";
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className,
+      style: {
+        position: "relative",
+        borderRadius: "6px",
+        border: `2px solid ${borderColor}`,
+        transition: "border-color 200ms ease"
+      },
+      children: [
+        children,
+        isLocked && !isLockedByMe && lockedBy && /* @__PURE__ */ jsx(
+          "div",
+          {
+            style: {
+              position: "absolute",
+              top: -10,
+              right: 8,
+              padding: "1px 6px",
+              borderRadius: "4px",
+              fontSize: "11px",
+              fontWeight: 500,
+              color: "white",
+              backgroundColor: lockedBy.color,
+              whiteSpace: "nowrap",
+              zIndex: 10
+            },
+            children: lockedBy.name
+          }
+        )
+      ]
+    }
+  );
+}
+var DEFAULT_EMOJIS = ["\u{1F44D}", "\u2764\uFE0F", "\u{1F602}", "\u{1F389}", "\u{1F525}", "\u{1F440}", "\u{1F680}", "\u{1F4AF}"];
+function ReactionBar({ emojis = DEFAULT_EMOJIS, className = "" }) {
+  const { reactions, sendReaction } = useReactions();
+  return /* @__PURE__ */ jsxs("div", { className, style: { position: "relative" }, children: [
+    /* @__PURE__ */ jsx(
+      "div",
+      {
+        style: {
+          position: "absolute",
+          bottom: "100%",
+          left: 0,
+          right: 0,
+          height: 120,
+          pointerEvents: "none",
+          overflow: "hidden"
+        },
+        children: reactions.map((reaction) => /* @__PURE__ */ jsx(
+          "span",
+          {
+            style: {
+              position: "absolute",
+              bottom: 0,
+              left: `${reaction.x ?? 50}%`,
+              fontSize: "24px",
+              animation: "cs-reaction-float 3s ease-out forwards",
+              pointerEvents: "none"
+            },
+            children: reaction.emoji
+          },
+          reaction.id
+        ))
+      }
+    ),
+    /* @__PURE__ */ jsx("div", { style: { display: "flex", gap: "4px", flexWrap: "wrap" }, children: emojis.map((emoji) => /* @__PURE__ */ jsx(
+      "button",
+      {
+        onClick: () => sendReaction(emoji),
+        style: {
+          padding: "4px 8px",
+          fontSize: "18px",
+          border: "1px solid #E5E7EB",
+          borderRadius: "8px",
+          backgroundColor: "white",
+          cursor: "pointer",
+          transition: "transform 100ms ease, background-color 100ms ease"
+        },
+        onMouseEnter: (e) => {
+          e.currentTarget.style.transform = "scale(1.15)";
+          e.currentTarget.style.backgroundColor = "#F3F4F6";
+        },
+        onMouseLeave: (e) => {
+          e.currentTarget.style.transform = "scale(1)";
+          e.currentTarget.style.backgroundColor = "white";
+        },
+        children: emoji
+      },
+      emoji
+    )) }),
+    /* @__PURE__ */ jsx("style", { children: `
+        @keyframes cs-reaction-float {
+          0% { opacity: 1; transform: translateY(0) scale(1); }
+          100% { opacity: 0; transform: translateY(-100px) scale(1.5); }
+        }
+      ` })
+  ] });
+}
+function PresenceBorder({
+  componentId,
+  borderWidth = 2,
+  className = "",
+  children
+}) {
+  const { isLocked, lockedBy, isLockedByMe, lock, unlock } = useLock(componentId);
+  const borderColor = isLocked ? lockedBy?.color || "#3B82F6" : "transparent";
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className,
+      style: {
+        position: "relative",
+        borderRadius: "6px",
+        border: `${borderWidth}px solid ${borderColor}`,
+        transition: "border-color 200ms ease"
+      },
+      onFocusCapture: () => lock(),
+      onBlurCapture: () => unlock(),
+      children: [
+        children,
+        isLocked && lockedBy && /* @__PURE__ */ jsx(
+          "div",
+          {
+            style: {
+              position: "absolute",
+              top: -(borderWidth + 8),
+              left: 8,
+              padding: "0px 6px",
+              borderRadius: "4px 4px 0 0",
+              fontSize: "11px",
+              fontWeight: 500,
+              color: "white",
+              backgroundColor: lockedBy.color,
+              whiteSpace: "nowrap",
+              lineHeight: "16px"
+            },
+            children: isLockedByMe ? "You" : lockedBy.name
+          }
+        )
+      ]
+    }
+  );
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+
+export { AvatarStack, Space as CloudSignalSpace, CursorOverlay, DEFAULTS, LockIndicator, PresenceBorder, ReactionBar, Space, TOPICS, TOPIC_PREFIX, TypingIndicator, VERSION, getColorForUser, getInitials, spaceTopic, spaceWildcard, useBroadcast, useCursors, useLock, usePresence, useReactions, useSharedState, useSpace, useTypingIndicator };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map