@palbase/web 1.0.0 → 1.1.0

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.0",
+  "version": "1.1.0",
   "description": "Palbe — the Palbase client SDK for web. One entry point: pb.",
   "license": "MIT",
   "private": false,
@@ -82,11 +82,6 @@
   "files": [
     "dist"
   ],
-  "dependencies": {
-    "@palbase/core": "^2.0.0",
-    "@palbase/auth": "^0.7.3",
-    "@palbase/flags": "^1.0.0"
-  },
   "peerDependencies": {
     "next": ">=15",
     "react": ">=18"
@@ -108,11 +103,17 @@
     "react-dom": "^19.0.0",
     "tsup": "^8.4.0",
     "typescript": "^5.8.0",
-    "vitest": "^3.1.0"
+    "vitest": "^3.1.0",
+    "@palbase/auth": "^0.7.3",
+    "@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",

package/dist/analytics-facade-DkOwkEpi.d.ts

@@ -1,454 +0,0 @@
-import { HttpClient, TokenManager, Session } from '@palbase/core';
-import { AuthClient } from '@palbase/auth';
-import { S as SessionStorageAdapter } from './storage-BPaeSG8K.js';
-import { FlagValue } from '@palbase/flags';
-
-interface PalbeOAuthConfig {
-    google?: {
-        enabled?: boolean;
-        clientId?: string;
-    };
-    apple?: {
-        enabled?: boolean;
-    };
-}
-/** Baked into palbe.gen.ts by `palbase web link` — the generated web config. */
-interface PalbeConfig {
-    url: string;
-    apiKey: string;
-    /** Informational — url+apiKey are already branch-specific (endpointRef embeds the branch slug); gen bakes all three consistently. */
-    branch?: string;
-    oauth?: PalbeOAuthConfig;
-    /** Refresh-token persistence. Default: endpoint-scoped localStorage in browsers, memory elsewhere. */
-    storage?: SessionStorageAdapter;
-    /** Extra headers on every request. */
-    headers?: Record<string, string>;
-}
-
-/** Frozen view of all cached flag values (what `all()` returns / `changes()` yields). */
-type FlagsView = Readonly<Record<string, FlagValue>>;
-/**
- * `pb.flags` — iOS-parity facade over `FlagsPool` (cache + delta polling +
- * auth binding) and `FlagsClient` (stateless transport).
- *
- * Start semantics: the facade is constructed lazily (first `pb.flags` touch).
- * - Browser: the pool starts right here in the constructor — cold snapshot +
- *   30s delta polling + visibility pause. "First use starts the machinery"
- *   without per-method start checks.
- * - Server (no `document`): NEVER auto-starts. `ready()`/`refresh()` are
- *   one-shot snapshot fetches with zero timers and zero storage access, so a
- *   pbServer request that reads flags pays exactly one HTTP call.
- *
- * localStorage persistence is scoped per endpoint ref (`palbe.flags.<ref>`),
- * mirroring the session-storage key convention.
- */
-declare class PalbeFlags {
-    private readonly transport;
-    private readonly pool;
-    constructor(rt: PalbeRuntime);
-    /** Resolves once the first snapshot (or persisted hydrate) is available. Auto-starts the pool. */
-    ready(): Promise<void>;
-    /** Force an immediate re-snapshot. */
-    refresh(): Promise<void>;
-    /** Frozen snapshot of all cached values (identity-stable until a change). */
-    all(): FlagsView;
-    /** Raw cached value for `key`, or `undefined` when not in the cache. */
-    get(key: string): FlagValue | undefined;
-    /** `true` only when the cached value is strictly `true`; `fallback` when the key is absent. */
-    isEnabled(key: string, fallback?: boolean): boolean;
-    /** Alias of {@link isEnabled} (iOS parity). */
-    bool(key: string, fallback?: boolean): boolean;
-    /** Cached value when it is a string, else `fallback`. */
-    getString(key: string, fallback: string): string;
-    /** Cached value when it is an integer number, else `fallback`. */
-    getInt(key: string, fallback: number): number;
-    /** Cached value when it is a number (integers included), else `fallback`. */
-    getDouble(key: string, fallback: number): number;
-    /**
-     * Resolve the multivariate variant for `key` — the variant name, or `null`
-     * when the flag has no variant (or the read fails).
-     *
-     * Wire failures (network errors, 404, etc.) resolve to `null`.
-     * Invalid flag names throw `BackendError('validation', { code: 'invalid_flag_name' })`.
-     *
-     * DEVIATION from iOS sync-cache parity: the platform does not propagate
-     * variant metadata into the user-flags snapshot/delta cache, so this is an
-     * ASYNC transport read (`GET /v1/flags/{key}/variant`), not a cache lookup.
-     */
-    getVariant(key: string): Promise<string | null>;
-    /** Subscribe to any change in the cached flag set. */
-    onChange(callback: () => void): Unsubscribe;
-    /**
-     * Observe ONE key: fires only when that key's value actually changes
-     * (per {@link sameFlagValue} — structural compare for objects), with the
-     * new value (`undefined` = deleted). P5 React-hook substrate.
-     */
-    subscribeKey(key: string, callback: (value: FlagValue | undefined) => void): Unsubscribe;
-    /**
-     * Async iteration over flag changes: yields the new {@link all} view on
-     * every pool change notification. The listener is detached when the
-     * consumer `break`s/`return`s/`throw`s — including while a `next()` is
-     * still pending (it resolves `{ done: true }` instead of hanging, which a
-     * plain async-generator `finally` would not guarantee).
-     */
-    changes(): AsyncIterableIterator<FlagsView>;
-    /** Stop polling and detach all listeners (auth + visibility + subscribers). */
-    destroy(): void;
-}
-
-/**
- * The connection state of the shared realtime WebSocket (iOS enum parity), plus
- * `'error'` — surfaced when a channel could not be recovered after a
- * token-expiry close exhausted its rejoin attempts (the socket itself may still
- * be up; the app should stop expecting events on the dead channel).
- */
-type RealtimeConnectionState = 'idle' | 'connected' | 'reconnecting' | 'error';
-
-/** An inbound broadcast payload (the inner `payload` of the Phoenix envelope). */
-type RealtimePayload = Record<string, unknown>;
-type RealtimeHandler = (payload: RealtimePayload) => void;
-/** A cancellable realtime subscription. `cancel()` removes the handler and,
- * when it was the channel's last, leaves the channel on the shared socket.
- * Cancelling twice is a no-op. */
-interface RealtimeSubscription {
-    cancel(): void;
-}
-interface RealtimeStatusSnapshot {
-    state: RealtimeConnectionState;
-    lastEventAt: Date | null;
-}
-/**
- * The observable connection status (`pb.realtime.status`) — the plain-JS
- * analogue of the iOS `@Observable RealtimeStatusStore`. `state` drives a
- * live "connected" badge; `lastEventAt` proves a push actually arrived.
- * `onChange` fires on state transitions and on every recorded event.
- */
-interface RealtimeStatus {
-    readonly state: RealtimeConnectionState;
-    readonly lastEventAt: Date | null;
-    onChange(callback: (status: RealtimeStatusSnapshot) => void): Unsubscribe;
-}
-/**
- * A subscription handle for one realtime channel (returned by
- * `pb.realtime.channel(name)` — the SAME instance per name). A channel is
- * joined on the shared socket when its first handler is added (or on the
- * first `send`) and left when its last handler cancels.
- */
-declare class RealtimeChannel {
-    /** The app-defined channel name (bare sub-topic, no "realtime:" prefix). */
-    readonly name: string;
-    private readonly owner;
-    /** @internal — obtain channels via `pb.realtime.channel(name)`. */
-    constructor(name: string, owner: PalbeRealtime);
-    /**
-     * Subscribe `handler` to `event` on this channel. Fire-and-forget: the
-     * join rides the shared socket asynchronously. Hold the returned
-     * subscription and `cancel()` it to stop.
-     */
-    on(event: string, handler: RealtimeHandler): RealtimeSubscription;
-    /**
-     * Broadcast `payload` to the channel's other subscribers (web addition —
-     * iOS is receive-only). Joins the channel if it isn't already; queued
-     * until the join is live on the socket.
-     */
-    send(event: string, payload?: RealtimePayload): void;
-}
-declare class PalbeRealtime {
-    private readonly rt;
-    private socket;
-    private readonly channels;
-    private readonly statusStore;
-    private readonly handlers;
-    private readonly topicRefcount;
-    constructor(rt: PalbeRuntime);
-    /**
-     * Get the handle for an app-defined channel (e.g. "room:42"). The same
-     * name returns the SAME instance. Throws a guided error on server-side
-     * hosts (SSR/RSC/Node) — realtime is client-only.
-     */
-    channel(name: string): RealtimeChannel;
-    /**
-     * Tear down the shared socket and clear all channel state. Called by
-     * `__configure` and `__reset` when the runtime is replaced, so old sockets
-     * are not left open and heartbeat timers do not leak.
-     */
-    destroy(): void;
-    /** The observable connection status. Safe to read anywhere (reports `idle` until a socket exists). */
-    get status(): RealtimeStatus;
-    /** @internal */
-    subscribe(topic: string, event: string, handler: RealtimeHandler): RealtimeSubscription;
-    /** @internal */
-    send(topic: string, event: string, payload: RealtimePayload): void;
-    /** Lazily build + start the shared socket on first subscription/send. */
-    private ensureSocket;
-    private route;
-    /**
-     * A channel died for good (token-expiry rejoin exhausted N attempts). Drop its
-     * handlers + refcount so the app stops expecting events on it, and flip the
-     * status observable to `'error'` (the React `useChannel` hook reports this).
-     * A later `.on()` for the same topic re-joins from scratch (refcount 1).
-     */
-    private handleChannelError;
-}
-
-interface PalbeRuntime {
-    config: PalbeConfig;
-    http: HttpClient;
-    tokenManager: TokenManager;
-    authClient: AuthClient;
-    auth: PalbeAuth;
-    flags: PalbeFlags;
-    realtime: PalbeRealtime;
-    analytics: PalbeAnalytics;
-    storage: SessionStorageAdapter;
-    /**
-     * Destroy the realtime facade if it was already constructed (no-op otherwise).
-     * Called by `__configure` / `__reset` when the runtime is replaced so the old
-     * socket is closed and heartbeat timers do not leak.
-     */
-    destroyRealtime(): void;
-}
-declare function buildRuntime(config: PalbeConfig): PalbeRuntime;
-
-type MagicLinkResult = ({
-    status: 'signedIn';
-} & AuthSuccess) | {
-    status: 'mfaRequired';
-    mfaToken: string;
-    factors: string[];
-};
-type OAuthExchangeResult = ({
-    status: 'signedIn';
-} & AuthSuccess) | {
-    status: 'mfaRequired';
-    mfaToken: string;
-    factors: string[];
-};
-interface AuthUser {
-    id: string;
-    /** null for phone-only users (the server omits email). */
-    email: string | null;
-    emailVerified: boolean;
-    createdAt: string;
-}
-interface AuthSuccess {
-    user: AuthUser;
-    session: Session;
-}
-type AuthState = {
-    status: 'signedIn';
-    user: AuthUser;
-} | {
-    status: 'signedOut';
-};
-type AuthChangeEvent = {
-    type: 'signedIn';
-    user: AuthUser;
-} | {
-    type: 'signedOut';
-    reason: 'userInitiated' | 'sessionExpired';
-} | {
-    type: 'tokenRefreshed';
-};
-type Unsubscribe = () => void;
-declare class PalbeAuth {
-    private readonly rt;
-    private cachedUser;
-    private signingOut;
-    private signingIn;
-    private signedInState;
-    private readonly stateListeners;
-    private readonly eventListeners;
-    private readonly userListeners;
-    constructor(rt: PalbeRuntime);
-    get currentUser(): AuthUser | null;
-    get isSignedIn(): boolean;
-    signUp(params: {
-        email: string;
-        password: string;
-    }): Promise<AuthSuccess>;
-    signIn(params: {
-        email: string;
-        password: string;
-    }): Promise<AuthSuccess>;
-    signOut(): Promise<void>;
-    getUser(): Promise<AuthUser>;
-    refreshUser(): Promise<AuthUser>;
-    /**
-     * Subscribe to signed-in/signed-out state. Fires immediately with the
-     * current snapshot (iOS parity). NOTE: a restored session (page reload) has
-     * no cached user yet, so the immediate snapshot reports signedOut even when
-     * `isSignedIn` is true — call `refreshUser()` on boot to populate the user
-     * and rely on `isSignedIn` for the session truth.
-     */
-    onAuthStateChange(callback: (state: AuthState) => void): Unsubscribe;
-    onAuthEvent(callback: (event: AuthChangeEvent) => void): Unsubscribe;
-    /** Subscribe to user-profile changes. Replays the cached user on subscribe (iOS parity). */
-    onUserChange(callback: (user: AuthUser) => void): Unsubscribe;
-    private snapshotState;
-    /**
-     * Listener exception isolation: a throwing consumer callback must never
-     * break delivery to other listeners nor propagate into the emit caller
-     * (tokenManager.clearSession callers, pb.call paths, signOut, ...).
-     */
-    private safeInvoke;
-    private emitState;
-    private emitEvent;
-    /** Cache the user + announce sign-in. Session was already set by AuthClient. */
-    private adopt;
-    /** Adopt a raw palauth AuthResult wire shape: wire tokens, cache user, announce. */
-    private adoptWire;
-    /** Run a sign-in flow under the signingIn flag to suppress spurious tokenRefreshed. */
-    private withSigningIn;
-    /**
-     * Defensively decode a 200 union body (AuthResult | mfa-required) and
-     * complete the flow. The wire contract promises one of the two shapes, but
-     * a literal-`null` (or otherwise malformed) JSON body must surface as
-     * BackendError('decode') — never a raw TypeError from probing a non-object.
-     * The mfa branch validates its fields: `mfa_token` is required; the factor
-     * list (named `factors` by magic-link verify, `mfa_factors` by the OAuth
-     * callback — extraction-verified against palauth) tolerates a missing or
-     * malformed value as []. The signedIn branch validates the FULL AuthResult
-     * shape (asWireAuthResult) — an incomplete body falls through to decode,
-     * never half-adopts.
-     */
-    private completeAuthUnion;
-    private decodeError;
-    signInWithOTP(params: {
-        phone: string;
-    }): Promise<void>;
-    verifyOTP(params: {
-        phone: string;
-        token: string;
-    }): Promise<AuthSuccess>;
-    resetPassword(email: string): Promise<void>;
-    confirmPasswordReset(params: {
-        token: string;
-        newPassword: string;
-    }): Promise<void>;
-    updatePassword(params: {
-        currentPassword: string;
-        newPassword: string;
-    }): Promise<void>;
-    verifyEmail(params: {
-        token: string;
-    } | {
-        code: string;
-        email: string;
-    }): Promise<void>;
-    resendVerification(email: string): Promise<void>;
-    signInWithMagicLink(email: string): Promise<void>;
-    verifyMagicLink(token: string): Promise<MagicLinkResult>;
-    signInWithCredential(params: {
-        provider: string;
-        credential: string;
-    }): Promise<AuthSuccess>;
-    signInWithOAuth(params: {
-        provider: string;
-        redirectTo?: string;
-        /** Set false to skip the browser redirect (popup/manual flows). Default true. */
-        redirect?: boolean;
-    }): Promise<{
-        url: string;
-    }>;
-    /**
-     * Complete the OAuth redirect flow: trade the provider's `code` + `state`
-     * (from the app's redirect_uri query) for a session. PKCE verifier + state
-     * live server-side in palauth — the client only relays the two values.
-     */
-    exchangeCodeForSession(params: {
-        provider: string;
-        code: string;
-        state: string;
-    }): Promise<OAuthExchangeResult>;
-    /** Config-as-code gate for the zero-arg provider sugar. */
-    private requireProvider;
-    signInWithGoogle(opts?: {
-        redirectTo?: string;
-        redirect?: boolean;
-    }): Promise<{
-        url: string;
-    }>;
-    signInWithApple(opts?: {
-        redirectTo?: string;
-        redirect?: boolean;
-    }): Promise<{
-        url: string;
-    }>;
-}
-
-/** Free-form event property bag (JSON object on the wire). */
-type AnalyticsProperties = Record<string, unknown>;
-/**
- * Runtime-scoped analytics identity — constructed EAGERLY in `buildRuntime`
- * (cheap: listener wiring only, no I/O) because the X-Distinct-Id header
- * interceptor must stamp every request from the first one, even when
- * `pb.analytics` is never touched (iOS: the resolver is wired at
- * PalBackend init). The facade wraps this state lazily.
- *
- * Auth events: while no facade exists, the state maintains identity only
- * (user id for the header, anon rotation on user-initiated sign-out). Once
- * the facade attaches, it takes over wholesale and adds the ingest
- * side-effects (flush + identify / flush + reset).
- */
-declare class AnalyticsState {
-    identifiedUserId: string | null;
-    /** Set by PalbeAnalytics on construction — delegates auth events to it. */
-    facadeAuthHandler: ((event: AuthChangeEvent) => void) | null;
-    private anonId;
-    private readonly store;
-    private readonly idKey;
-    private readonly optOutKey;
-    constructor(rt: PalbeRuntime);
-    /** User id when identified, else the stable anon id. NEVER empty —
-     * this is what `identify()` links, so stamping it on every request lets
-     * the trace pipeline stitch pre-login activity to the user. */
-    distinctId(): string;
-    anonymousId(): string;
-    rotateAnonymousId(): string;
-    isOptedOut(): boolean;
-    setOptOut(on: boolean): void;
-}
-declare class PalbeAnalytics {
-    private readonly rt;
-    private readonly state;
-    private readonly buffer;
-    private flushTimer;
-    /** Browser → buffer + size/timer flush. Server (no document) → immediate
-     * per-call POST, zero timers (nothing leaks into RSC/route handlers). */
-    private readonly browser;
-    constructor(rt: PalbeRuntime, state: AnalyticsState);
-    /** Record an event. Invalid names are dropped (one warn per process). */
-    capture(event: string, properties?: AnalyticsProperties): void;
-    /** Record a screen view — server-canonical `$screen` + `screen_name`.
-     * Validates non-empty only (the live wire at /v1/analytics/screen requires
-     * non-empty screen_name; the event-name regex does NOT apply here). */
-    screen(name: string, properties?: AnalyticsProperties): void;
-    /** Link the current anon id to `userId` and adopt it as the distinct id.
-     * Immediate POST (not buffered). Re-identifying a DIFFERENT user
-     * auto-resets first (iOS K10) so one anon id never links two users. */
-    identify(userId: string, traits?: AnalyticsProperties): void;
-    /** Merge distinct id `from` into `to` (identity stitching). Immediate POST. */
-    alias(from: string, to: string): void;
-    /** Drop the buffer, clear the identified user and rotate the anon id
-     * (sign-out hygiene). Callers wanting pending events delivered flush first
-     * — the auth binding does. */
-    reset(): void;
-    /** Persisted GDPR opt-out. Opting out drops anything pending so nothing
-     * already-buffered leaks after the user said stop. */
-    setOptOut(on: boolean): void;
-    /** Drain the buffer to /v1/analytics/batch (≤100 per request, sequential).
-     * Resolves when delivery finished; NEVER rejects — failed slices are
-     * dropped with one warn per flush. 207 partial-reject is also warned once
-     * (fire-and-forget: no retry for already-delivered batches). */
-    flush(): Promise<void>;
-    private ingest;
-    /** iOS PalBackend auth-binding parity: signedIn → flush + identify;
-     * userInitiated signedOut → flush + reset; sessionExpired → flush only. */
-    private handleAuthEvent;
-    private startTimer;
-    private cancelTimer;
-    private post;
-}
-
-export { type AnalyticsProperties as A, type FlagsView as F, type MagicLinkResult as M, type OAuthExchangeResult as O, PalbeAnalytics as P, RealtimeChannel as R, type Unsubscribe as U, type AuthChangeEvent as a, type AuthState as b, type AuthSuccess as c, type AuthUser as d, PalbeAuth as e, type PalbeConfig as f, PalbeFlags as g, type PalbeOAuthConfig as h, PalbeRealtime as i, type RealtimeConnectionState as j, type RealtimeHandler as k, type RealtimePayload as l, type RealtimeStatus as m, type RealtimeStatusSnapshot as n, type RealtimeSubscription as o, type PalbeRuntime as p, buildRuntime as q };