@palbase/web 1.0.1 → 1.1.1

package/dist/react/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/react/index.tsx"],"sourcesContent":["'use client';\n\n// `palbe/react` — thin React hooks over the observable `pb.*` facades. Each\n// value hook is a `useSyncExternalStore` (the React 18+ concurrent-safe\n// primitive) binding: `subscribe` is the facade's Unsubscribe-returning\n// listener, `getSnapshot` is the matching getter. NO new SDK behaviour lives\n// here — the hooks re-render exactly when (and only when) their slice of state\n// changes, mirroring the iOS `@Observable` granularity.\n//\n// `react` is an OPTIONAL peer dependency: importing `palbe` (the core entry)\n// never pulls React; only `palbe/react` does.\n//\n// Client-only: the module starts with `'use client'` (Next.js App Router). SSR\n// initial values come from the `getServerSnapshot` arms (null user, empty flag\n// set) so a server render never touches the runtime singleton.\n\nimport { useCallback, useEffect, useRef, useState, useSyncExternalStore } from 'react';\nimport type { AuthUser, Unsubscribe } from '../auth-facade.js';\nimport type { FlagsView, FlagValue } from '../flags-facade.js';\nimport { onConfigured } from '../internal.js';\nimport { pb } from '../pb.js';\nimport type { RealtimeConnectionState, RealtimePayload } from '../realtime/facade.js';\n\n/** The session slice `useSession` exposes. */\nexport interface SessionState {\n  signedIn: boolean;\n  user: AuthUser | null;\n}\n\n/** Frozen empty flag view — the stable server/unconfigured fallback for\n * `useFlags` (a fresh `{}` each call would loop `useSyncExternalStore`). */\nconst EMPTY_FLAGS: FlagsView = Object.freeze({});\n\n/** The signed-out session snapshot — a single frozen instance so the\n * unconfigured/server snapshot is referentially stable across calls. */\nconst SIGNED_OUT: SessionState = Object.freeze({ signedIn: false, user: null });\n\n/**\n * Wraps a facade-listener factory so hooks that mount BEFORE `__configure`\n * runs self-heal when configuration arrives (or changes on re-configure /\n * watch-mode regen).\n *\n * Behaviour:\n *  - If already configured at subscribe time, attaches the facade listener\n *    immediately AND registers an `onConfigured` watcher for future re-configures.\n *  - If NOT yet configured at subscribe time, only registers `onConfigured`;\n *    the facade listener is attached when configuration arrives.\n *  - On every configure event: detaches the old facade listener (if any),\n *    attaches a fresh one against the new runtime, then calls `onStoreChange`\n *    so React re-reads the snapshot from the new runtime.\n *  - The returned unsubscribe tears down both the onConfigured registration\n *    and the current facade listener.\n *\n * @param getFacadeListener - factory called when a runtime is available;\n *   must return an Unsubscribe; called with `onStoreChange` as its argument.\n */\nfunction subscribeWithConfig(\n  getFacadeListener: (onStoreChange: () => void) => Unsubscribe,\n): (onStoreChange: () => void) => Unsubscribe {\n  return (onStoreChange: () => void): Unsubscribe => {\n    let currentFacadeUnsub: Unsubscribe | null = null;\n\n    function attachFacade(): void {\n      currentFacadeUnsub?.();\n      try {\n        currentFacadeUnsub = getFacadeListener(onStoreChange);\n      } catch {\n        // notConfigured — will be retried when onConfigured fires\n        currentFacadeUnsub = null;\n      }\n    }\n\n    // Register for future (re-)configure events.\n    const offConfigured = onConfigured(() => {\n      attachFacade();\n      // Notify React to re-read the snapshot from the new runtime.\n      onStoreChange();\n    });\n\n    // If already configured right now, attach immediately too.\n    attachFacade();\n\n    return () => {\n      offConfigured();\n      currentFacadeUnsub?.();\n      currentFacadeUnsub = null;\n    };\n  };\n}\n\n/**\n * Current authenticated user, or `null` when signed out. Re-renders on BOTH\n * auth-state transitions (sign-in adopts a user, sign-out clears it) and\n * user-profile changes (e.g. an email-verified flip via `refreshUser`).\n *\n * `getSnapshot` is guarded: before the generated `palbe.gen.ts` runs\n * `__configure`, `pb.auth` throws `notConfigured` — a tree rendered that early\n * gets `null`, never a render crash. Once `__configure` runs the hook\n * self-heals: it re-subscribes to the new runtime's auth facade and notifies\n * React to re-read the snapshot.\n */\nexport function useUser(): AuthUser | null {\n  return useSyncExternalStore(subscribeUserWithConfig, getUserSnapshot, getNullUser);\n}\n\nconst subscribeUserWithConfig = subscribeWithConfig((onStoreChange) => {\n  // Two sources, one composite unsubscribe:\n  //   onAuthStateChange → sign-in (new user) and sign-out (null)\n  //   onUserChange      → in-place profile edits (email-verified, …)\n  // Both fire immediately on subscribe (iOS parity), which simply re-reads the\n  // already-current snapshot — harmless.\n  const offState = pb.auth.onAuthStateChange(onStoreChange);\n  const offUser = pb.auth.onUserChange(onStoreChange);\n  return () => {\n    offState();\n    offUser();\n  };\n});\n\nfunction getUserSnapshot(): AuthUser | null {\n  try {\n    return pb.auth.currentUser;\n  } catch {\n    return null;\n  }\n}\n\nfunction getNullUser(): AuthUser | null {\n  return null;\n}\n\n/**\n * Session slice: `{ signedIn, user }`. Re-renders on auth-state transitions.\n *\n * `getSnapshot` MUST be referentially stable when nothing changed — returning a\n * fresh object every call would put `useSyncExternalStore` into an infinite\n * render loop. A per-component ref caches the last value and returns the SAME\n * object until `signedIn` or `user` actually changes.\n *\n * Self-heals when `__configure` runs after mount (same as `useUser`).\n */\nexport function useSession(): SessionState {\n  const lastRef = useRef<SessionState>(SIGNED_OUT);\n  const getSnapshot = useCallback((): SessionState => {\n    const next = readSession();\n    const prev = lastRef.current;\n    if (prev.signedIn === next.signedIn && prev.user === next.user) {\n      return prev; // unchanged — keep the stable reference\n    }\n    lastRef.current = next;\n    return next;\n  }, []);\n  return useSyncExternalStore(subscribeSessionWithConfig, getSnapshot, getSignedOut);\n}\n\nconst subscribeSessionWithConfig = subscribeWithConfig((onStoreChange) =>\n  pb.auth.onAuthStateChange(onStoreChange),\n);\n\nfunction readSession(): SessionState {\n  try {\n    const user = pb.auth.currentUser;\n    const signedIn = pb.auth.isSignedIn;\n    if (!signedIn && user === null) return SIGNED_OUT;\n    return { signedIn, user };\n  } catch {\n    return SIGNED_OUT;\n  }\n}\n\nfunction getSignedOut(): SessionState {\n  return SIGNED_OUT;\n}\n\n/**\n * Subscribe to ONE flag. Re-renders only when THIS key's value changes\n * (`pb.flags.subscribeKey` is the per-key source — structural compare for\n * objects), returning `fallback` until the key has a value.\n *\n * The value is read at the dynamic flag boundary where the concrete type `T`\n * is caller-asserted (the cached value is whatever the server sent); the\n * contained `as T` is the documented escape hatch — flags are untyped on the\n * wire, and the caller owns the `fallback`'s type.\n *\n * NOTE: passing an inline-object `fallback` for an absent key defeats snapshot\n * caching (a new object reference each render re-enters the last-value ref).\n * Memoize the fallback (e.g. a module-level const or `useMemo`) if it matters.\n *\n * Self-heals when `__configure` runs after mount (same as `useUser`).\n */\nexport function useFlag<T extends FlagValue>(key: string, fallback: T): T {\n  // Subscribe identity must change when `key` changes so useSyncExternalStore\n  // re-subscribes to the new key. subscribeWithConfig wraps the per-key\n  // factory so the hook also self-heals on (re-)configure.\n  // biome-ignore lint/correctness/useExhaustiveDependencies: `key` is a runtime param, not an outer-scope value — dependency IS required\n  const subscribe = useCallback(\n    subscribeWithConfig((onStoreChange) => pb.flags.subscribeKey(key, onStoreChange)),\n    [key],\n  );\n\n  // Cache the last value so getSnapshot is referentially stable (objects come\n  // back as the frozen pooled reference — stable identity until a real change).\n  const lastRef = useRef<T>(fallback);\n  const getSnapshot = useCallback((): T => {\n    let next: T;\n    try {\n      const value = pb.flags.get(key);\n      next = value === undefined ? fallback : (value as T);\n    } catch {\n      next = fallback;\n    }\n    if (!Object.is(next, lastRef.current)) {\n      lastRef.current = next;\n    }\n    return lastRef.current;\n  }, [key, fallback]);\n\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n\n/**\n * Subscribe to the whole flag set. Re-renders on any change. `pb.flags.all()`\n * returns a frozen, identity-stable view (a NEW frozen object only when the set\n * actually changes), so it is `useSyncExternalStore`-safe as-is.\n *\n * Self-heals when `__configure` runs after mount (same as `useUser`).\n */\nexport function useFlags(): FlagsView {\n  return useSyncExternalStore(subscribeFlagsWithConfig, getFlagsSnapshot, getEmptyFlags);\n}\n\nconst subscribeFlagsWithConfig = subscribeWithConfig((onStoreChange) =>\n  pb.flags.onChange(onStoreChange),\n);\n\nfunction getFlagsSnapshot(): FlagsView {\n  try {\n    return pb.flags.all();\n  } catch {\n    return EMPTY_FLAGS;\n  }\n}\n\nfunction getEmptyFlags(): FlagsView {\n  return EMPTY_FLAGS;\n}\n\n/** The reported channel status: the shared-socket connection state, plus\n * `'unavailable'` when `pb.realtime.channel()` is not usable in this\n * environment (no WebSocket / SSR). */\nexport type ChannelStatus = RealtimeConnectionState | 'unavailable';\n\n/**\n * Subscribe a `handler` to one realtime `event` on `channel(name)` for the\n * lifetime of the component. Returns the live connection `{ status }`.\n *\n * The handler is held in a ref and refreshed every render, so passing a fresh\n * closure each render (the common case — callers needn't `useCallback`) does\n * NOT tear down and re-create the subscription. The subscription itself is\n * keyed on `[name, event]`: only a name/event change re-subscribes.\n *\n * StrictMode-safe: the facade refcounts joins, so React's mount→cleanup→\n * remount (double-invoke in dev) nets to exactly one live subscription via the\n * effect's `cancel()` cleanup — NO once-guard (a once-guard would leave the\n * subscription dead after the first cleanup; that was the P4 live-smoke bug).\n *\n * SSR / no-WebSocket: `pb.realtime.channel()` throws; the effect catches it and\n * reports `status: 'unavailable'` instead of crashing. (Effects don't run on\n * the server, so the initial server status is the idle default.)\n */\nexport function useChannel(\n  name: string,\n  event: string,\n  handler: (payload: RealtimePayload) => void,\n): { status: ChannelStatus } {\n  const handlerRef = useRef(handler);\n  // Refresh the handler every render WITHOUT re-subscribing — the effect below\n  // calls `handlerRef.current`, so the latest closure always runs.\n  useEffect(() => {\n    handlerRef.current = handler;\n  });\n\n  const [status, setStatus] = useState<ChannelStatus>('idle');\n\n  // A configure-epoch counter: bumped by onConfigured so the channel effect\n  // re-runs when a runtime arrives (handles the pre-config mount case and\n  // watch-mode runtime swaps). Does not re-subscribe on every render.\n  const [configEpoch, setConfigEpoch] = useState(0);\n  useEffect(() => {\n    return onConfigured(() => setConfigEpoch((n) => n + 1));\n  }, []);\n\n  // biome-ignore lint/correctness/useExhaustiveDependencies: `configEpoch` is intentionally a re-run trigger for configure-arrive / watch-mode\n  useEffect(() => {\n    let channel: ReturnType<typeof pb.realtime.channel>;\n    try {\n      channel = pb.realtime.channel(name);\n    } catch {\n      // notConfigured or no-WebSocket / server environment — degrade gracefully.\n      setStatus('unavailable');\n      return;\n    }\n    const sub = channel.on(event, (payload) => handlerRef.current(payload));\n    // Seed from the current connection state, then track transitions.\n    setStatus(pb.realtime.status.state);\n    const offStatus = pb.realtime.status.onChange((snapshot) => setStatus(snapshot.state));\n    return () => {\n      offStatus();\n      sub.cancel();\n    };\n  }, [name, event, configEpoch]);\n\n  return { status };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/react/index.tsx"],"sourcesContent":["'use client';\n\n// `palbe/react` — thin React hooks over the observable `pb.*` facades. Each\n// value hook is a `useSyncExternalStore` (the React 18+ concurrent-safe\n// primitive) binding: `subscribe` is the facade's Unsubscribe-returning\n// listener, `getSnapshot` is the matching getter. NO new SDK behaviour lives\n// here — the hooks re-render exactly when (and only when) their slice of state\n// changes, mirroring the iOS `@Observable` granularity.\n//\n// `react` is an OPTIONAL peer dependency: importing `palbe` (the core entry)\n// never pulls React; only `palbe/react` does.\n//\n// Client-only: the module starts with `'use client'` (Next.js App Router). SSR\n// initial values come from the `getServerSnapshot` arms (null user, empty flag\n// set) so a server render never touches the runtime singleton.\n\nimport { useCallback, useEffect, useRef, useState, useSyncExternalStore } from 'react';\nimport type { AuthUser, Unsubscribe } from '../auth-facade.js';\nimport type { FlagsView, FlagValue } from '../flags-facade.js';\nimport { onConfigured } from '../internal.js';\nimport type { Chat } from '../messaging/chat.js';\nimport type { ChatMember, ChatMessage } from '../messaging/types.js';\nimport { pb } from '../pb.js';\nimport type { RealtimeConnectionState, RealtimePayload } from '../realtime/facade.js';\n\n/** The session slice `useSession` exposes. */\nexport interface SessionState {\n  signedIn: boolean;\n  user: AuthUser | null;\n}\n\n/** Frozen empty flag view — the stable server/unconfigured fallback for\n * `useFlags` (a fresh `{}` each call would loop `useSyncExternalStore`). */\nconst EMPTY_FLAGS: FlagsView = Object.freeze({});\n\n/** The signed-out session snapshot — a single frozen instance so the\n * unconfigured/server snapshot is referentially stable across calls. */\nconst SIGNED_OUT: SessionState = Object.freeze({ signedIn: false, user: null });\n\n/**\n * Wraps a facade-listener factory so hooks that mount BEFORE `__configure`\n * runs self-heal when configuration arrives (or changes on re-configure /\n * watch-mode regen).\n *\n * Behaviour:\n *  - If already configured at subscribe time, attaches the facade listener\n *    immediately AND registers an `onConfigured` watcher for future re-configures.\n *  - If NOT yet configured at subscribe time, only registers `onConfigured`;\n *    the facade listener is attached when configuration arrives.\n *  - On every configure event: detaches the old facade listener (if any),\n *    attaches a fresh one against the new runtime, then calls `onStoreChange`\n *    so React re-reads the snapshot from the new runtime.\n *  - The returned unsubscribe tears down both the onConfigured registration\n *    and the current facade listener.\n *\n * @param getFacadeListener - factory called when a runtime is available;\n *   must return an Unsubscribe; called with `onStoreChange` as its argument.\n */\nfunction subscribeWithConfig(\n  getFacadeListener: (onStoreChange: () => void) => Unsubscribe,\n): (onStoreChange: () => void) => Unsubscribe {\n  return (onStoreChange: () => void): Unsubscribe => {\n    let currentFacadeUnsub: Unsubscribe | null = null;\n\n    function attachFacade(): void {\n      currentFacadeUnsub?.();\n      try {\n        currentFacadeUnsub = getFacadeListener(onStoreChange);\n      } catch {\n        // notConfigured — will be retried when onConfigured fires\n        currentFacadeUnsub = null;\n      }\n    }\n\n    // Register for future (re-)configure events.\n    const offConfigured = onConfigured(() => {\n      attachFacade();\n      // Notify React to re-read the snapshot from the new runtime.\n      onStoreChange();\n    });\n\n    // If already configured right now, attach immediately too.\n    attachFacade();\n\n    return () => {\n      offConfigured();\n      currentFacadeUnsub?.();\n      currentFacadeUnsub = null;\n    };\n  };\n}\n\n/**\n * Current authenticated user, or `null` when signed out. Re-renders on BOTH\n * auth-state transitions (sign-in adopts a user, sign-out clears it) and\n * user-profile changes (e.g. an email-verified flip via `refreshUser`).\n *\n * `getSnapshot` is guarded: before the generated `palbe.gen.ts` runs\n * `__configure`, `pb.auth` throws `notConfigured` — a tree rendered that early\n * gets `null`, never a render crash. Once `__configure` runs the hook\n * self-heals: it re-subscribes to the new runtime's auth facade and notifies\n * React to re-read the snapshot.\n */\nexport function useUser(): AuthUser | null {\n  return useSyncExternalStore(subscribeUserWithConfig, getUserSnapshot, getNullUser);\n}\n\nconst subscribeUserWithConfig = subscribeWithConfig((onStoreChange) => {\n  // Two sources, one composite unsubscribe:\n  //   onAuthStateChange → sign-in (new user) and sign-out (null)\n  //   onUserChange      → in-place profile edits (email-verified, …)\n  // Both fire immediately on subscribe (iOS parity), which simply re-reads the\n  // already-current snapshot — harmless.\n  const offState = pb.auth.onAuthStateChange(onStoreChange);\n  const offUser = pb.auth.onUserChange(onStoreChange);\n  return () => {\n    offState();\n    offUser();\n  };\n});\n\nfunction getUserSnapshot(): AuthUser | null {\n  try {\n    return pb.auth.currentUser;\n  } catch {\n    return null;\n  }\n}\n\nfunction getNullUser(): AuthUser | null {\n  return null;\n}\n\n/**\n * Session slice: `{ signedIn, user }`. Re-renders on auth-state transitions.\n *\n * `getSnapshot` MUST be referentially stable when nothing changed — returning a\n * fresh object every call would put `useSyncExternalStore` into an infinite\n * render loop. A per-component ref caches the last value and returns the SAME\n * object until `signedIn` or `user` actually changes.\n *\n * Self-heals when `__configure` runs after mount (same as `useUser`).\n */\nexport function useSession(): SessionState {\n  const lastRef = useRef<SessionState>(SIGNED_OUT);\n  const getSnapshot = useCallback((): SessionState => {\n    const next = readSession();\n    const prev = lastRef.current;\n    if (prev.signedIn === next.signedIn && prev.user === next.user) {\n      return prev; // unchanged — keep the stable reference\n    }\n    lastRef.current = next;\n    return next;\n  }, []);\n  return useSyncExternalStore(subscribeSessionWithConfig, getSnapshot, getSignedOut);\n}\n\nconst subscribeSessionWithConfig = subscribeWithConfig((onStoreChange) =>\n  pb.auth.onAuthStateChange(onStoreChange),\n);\n\nfunction readSession(): SessionState {\n  try {\n    const user = pb.auth.currentUser;\n    const signedIn = pb.auth.isSignedIn;\n    if (!signedIn && user === null) return SIGNED_OUT;\n    return { signedIn, user };\n  } catch {\n    return SIGNED_OUT;\n  }\n}\n\nfunction getSignedOut(): SessionState {\n  return SIGNED_OUT;\n}\n\n/**\n * Subscribe to ONE flag. Re-renders only when THIS key's value changes\n * (`pb.flags.subscribeKey` is the per-key source — structural compare for\n * objects), returning `fallback` until the key has a value.\n *\n * The value is read at the dynamic flag boundary where the concrete type `T`\n * is caller-asserted (the cached value is whatever the server sent); the\n * contained `as T` is the documented escape hatch — flags are untyped on the\n * wire, and the caller owns the `fallback`'s type.\n *\n * NOTE: passing an inline-object `fallback` for an absent key defeats snapshot\n * caching (a new object reference each render re-enters the last-value ref).\n * Memoize the fallback (e.g. a module-level const or `useMemo`) if it matters.\n *\n * Self-heals when `__configure` runs after mount (same as `useUser`).\n */\nexport function useFlag<T extends FlagValue>(key: string, fallback: T): T {\n  // Subscribe identity must change when `key` changes so useSyncExternalStore\n  // re-subscribes to the new key. subscribeWithConfig wraps the per-key\n  // factory so the hook also self-heals on (re-)configure.\n  // biome-ignore lint/correctness/useExhaustiveDependencies: `key` is a runtime param, not an outer-scope value — dependency IS required\n  const subscribe = useCallback(\n    subscribeWithConfig((onStoreChange) => pb.flags.subscribeKey(key, onStoreChange)),\n    [key],\n  );\n\n  // Cache the last value so getSnapshot is referentially stable (objects come\n  // back as the frozen pooled reference — stable identity until a real change).\n  const lastRef = useRef<T>(fallback);\n  const getSnapshot = useCallback((): T => {\n    let next: T;\n    try {\n      const value = pb.flags.get(key);\n      next = value === undefined ? fallback : (value as T);\n    } catch {\n      next = fallback;\n    }\n    if (!Object.is(next, lastRef.current)) {\n      lastRef.current = next;\n    }\n    return lastRef.current;\n  }, [key, fallback]);\n\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n\n/**\n * Subscribe to the whole flag set. Re-renders on any change. `pb.flags.all()`\n * returns a frozen, identity-stable view (a NEW frozen object only when the set\n * actually changes), so it is `useSyncExternalStore`-safe as-is.\n *\n * Self-heals when `__configure` runs after mount (same as `useUser`).\n */\nexport function useFlags(): FlagsView {\n  return useSyncExternalStore(subscribeFlagsWithConfig, getFlagsSnapshot, getEmptyFlags);\n}\n\nconst subscribeFlagsWithConfig = subscribeWithConfig((onStoreChange) =>\n  pb.flags.onChange(onStoreChange),\n);\n\nfunction getFlagsSnapshot(): FlagsView {\n  try {\n    return pb.flags.all();\n  } catch {\n    return EMPTY_FLAGS;\n  }\n}\n\nfunction getEmptyFlags(): FlagsView {\n  return EMPTY_FLAGS;\n}\n\n/** The reported channel status: the shared-socket connection state, plus\n * `'unavailable'` when `pb.realtime.channel()` is not usable in this\n * environment (no WebSocket / SSR). */\nexport type ChannelStatus = RealtimeConnectionState | 'unavailable';\n\n/**\n * Subscribe a `handler` to one realtime `event` on `channel(name)` for the\n * lifetime of the component. Returns the live connection `{ status }`.\n *\n * The handler is held in a ref and refreshed every render, so passing a fresh\n * closure each render (the common case — callers needn't `useCallback`) does\n * NOT tear down and re-create the subscription. The subscription itself is\n * keyed on `[name, event]`: only a name/event change re-subscribes.\n *\n * StrictMode-safe: the facade refcounts joins, so React's mount→cleanup→\n * remount (double-invoke in dev) nets to exactly one live subscription via the\n * effect's `cancel()` cleanup — NO once-guard (a once-guard would leave the\n * subscription dead after the first cleanup; that was the P4 live-smoke bug).\n *\n * SSR / no-WebSocket: `pb.realtime.channel()` throws; the effect catches it and\n * reports `status: 'unavailable'` instead of crashing. (Effects don't run on\n * the server, so the initial server status is the idle default.)\n */\nexport function useChannel(\n  name: string,\n  event: string,\n  handler: (payload: RealtimePayload) => void,\n): { status: ChannelStatus } {\n  const handlerRef = useRef(handler);\n  // Refresh the handler every render WITHOUT re-subscribing — the effect below\n  // calls `handlerRef.current`, so the latest closure always runs.\n  useEffect(() => {\n    handlerRef.current = handler;\n  });\n\n  const [status, setStatus] = useState<ChannelStatus>('idle');\n\n  // A configure-epoch counter: bumped by onConfigured so the channel effect\n  // re-runs when a runtime arrives (handles the pre-config mount case and\n  // watch-mode runtime swaps). Does not re-subscribe on every render.\n  const [configEpoch, setConfigEpoch] = useState(0);\n  useEffect(() => {\n    return onConfigured(() => setConfigEpoch((n) => n + 1));\n  }, []);\n\n  // biome-ignore lint/correctness/useExhaustiveDependencies: `configEpoch` is intentionally a re-run trigger for configure-arrive / watch-mode\n  useEffect(() => {\n    let channel: ReturnType<typeof pb.realtime.channel>;\n    try {\n      channel = pb.realtime.channel(name);\n    } catch {\n      // notConfigured or no-WebSocket / server environment — degrade gracefully.\n      setStatus('unavailable');\n      return;\n    }\n    const sub = channel.on(event, (payload) => handlerRef.current(payload));\n    // Seed from the current connection state, then track transitions.\n    setStatus(pb.realtime.status.state);\n    const offStatus = pb.realtime.status.onChange((snapshot) => setStatus(snapshot.state));\n    return () => {\n      offStatus();\n      sub.cancel();\n    };\n  }, [name, event, configEpoch]);\n\n  return { status };\n}\n\n// ─── Messaging hooks (Web-MLS Phase 2) ───────────────────────────────────────\n\nconst EMPTY_CHATS: readonly Chat[] = Object.freeze([]);\nconst EMPTY_MESSAGES: readonly ChatMessage[] = Object.freeze([]);\nconst EMPTY_MEMBERS: readonly ChatMember[] = Object.freeze([]);\nconst EMPTY_TYPING: readonly ChatMember[] = Object.freeze([]);\n\n/**\n * The observable chat list (DMs + groups, active only). Re-renders when a chat\n * is added (you start one / a peer DMs you and the Welcome drains), removed, or\n * the list hydrates from the durable catalog on launch.\n *\n * Self-heals when `__configure` runs after mount (same as `useUser`).\n */\nexport function useChats(): readonly Chat[] {\n  const lastRef = useRef<readonly Chat[]>(EMPTY_CHATS);\n  const getSnapshot = useCallback((): readonly Chat[] => {\n    try {\n      const next = pb.messaging.chats;\n      // Identity-stable: only swap the cached array when the set changed.\n      if (next.length !== lastRef.current.length || next.some((c, i) => c !== lastRef.current[i])) {\n        lastRef.current = next.slice();\n      }\n      return lastRef.current;\n    } catch {\n      return EMPTY_CHATS;\n    }\n  }, []);\n  return useSyncExternalStore(subscribeChatsWithConfig, getSnapshot, getEmptyChats);\n}\n\nconst subscribeChatsWithConfig = subscribeWithConfig((onStoreChange) =>\n  pb.messaging.onChatsChange(onStoreChange),\n);\n\nfunction getEmptyChats(): readonly Chat[] {\n  return EMPTY_CHATS;\n}\n\n/**\n * Bind to one `Chat`'s changes. Re-renders whenever the chat's observable state\n * changes (a new message, members refresh, typing, materialize draft→active).\n * Returns the SAME `chat` instance for ergonomic access to `chat.messages`,\n * `chat.send(...)`, etc.\n */\nexport function useChat(chat: Chat): Chat {\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => chat.onChange(onStoreChange),\n    [chat],\n  );\n  // The chat instance is pointer-stable; a per-render counter forces re-render\n  // on each onChange. Snapshot returns the instance itself (stable identity).\n  const getSnapshot = useCallback(() => chat, [chat]);\n  // Tick on every change so consumers reading chat.messages re-render.\n  const [, force] = useState(0);\n  useEffect(() => chat.onChange(() => force((n) => n + 1)), [chat]);\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n\n/**\n * The ordered message transcript for a chat (newest last). Re-renders on a new\n * message / history page / own-send echo. A cached snapshot keeps the array\n * reference stable until the list actually changes.\n */\nexport function useMessages(chat: Chat): readonly ChatMessage[] {\n  const lastRef = useRef<readonly ChatMessage[]>(EMPTY_MESSAGES);\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => chat.onChange(onStoreChange),\n    [chat],\n  );\n  const getSnapshot = useCallback((): readonly ChatMessage[] => {\n    const next = chat.messages;\n    if (next.length !== lastRef.current.length || next.some((m, i) => m !== lastRef.current[i])) {\n      lastRef.current = next.slice();\n    }\n    return lastRef.current;\n  }, [chat]);\n  return useSyncExternalStore(subscribe, getSnapshot, () => EMPTY_MESSAGES);\n}\n\n/** The members of a chat (users). Re-renders when the roster changes. */\nexport function useChatMembers(chat: Chat): readonly ChatMember[] {\n  const lastRef = useRef<readonly ChatMember[]>(EMPTY_MEMBERS);\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => chat.onChange(onStoreChange),\n    [chat],\n  );\n  const getSnapshot = useCallback((): readonly ChatMember[] => {\n    const next = chat.members;\n    if (next.length !== lastRef.current.length || next.some((m, i) => m !== lastRef.current[i])) {\n      lastRef.current = next.slice();\n    }\n    return lastRef.current;\n  }, [chat]);\n  return useSyncExternalStore(subscribe, getSnapshot, () => EMPTY_MEMBERS);\n}\n\n/** The users currently typing in a chat. Re-renders on typing start/stop. */\nexport function useTyping(chat: Chat): readonly ChatMember[] {\n  const lastRef = useRef<readonly ChatMember[]>(EMPTY_TYPING);\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => chat.onChange(onStoreChange),\n    [chat],\n  );\n  const getSnapshot = useCallback((): readonly ChatMember[] => {\n    const next = chat.typing;\n    if (next.length !== lastRef.current.length || next.some((m, i) => m !== lastRef.current[i])) {\n      lastRef.current = next.slice();\n    }\n    return lastRef.current;\n  }, [chat]);\n  return useSyncExternalStore(subscribe, getSnapshot, () => EMPTY_TYPING);\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palbase/web",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Palbe — the Palbase client SDK for web. One entry point: pb.",
   "license": "MIT",
   "private": false,
@@ -105,12 +105,15 @@
     "typescript": "^5.8.0",
     "vitest": "^3.1.0",
     "@palbase/auth": "^0.7.3",
-    "@palbase/flags": "^1.0.0",
-    "@palbase/core": "^2.0.0"
+    "@palbase/core": "^2.0.0",
+    "@palbase/flags": "^1.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "livekit-client": "^2.19.2"
+  },
   "scripts": {
     "prebuild": "node scripts/sync-version.mjs",
     "build": "tsup",