@omg-dev/sdk 0.4.24

package/src/index.ts

@@ -0,0 +1,1042 @@
+// @omg-dev/sdk — client-side React hooks with realtime updates
+
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from "react"
+import { fetchEventSource, type EventSourceMessage } from "@microsoft/fetch-event-source"
+import { getAuthContext, notifyAuthRequired, subscribeAuthChange } from "./auth/bridge"
+
+// Re-export the auth surface from root so agents have a single import:
+// `import { VibesAuthGuard, useUser } from "@omg-dev/sdk"`. The publish
+// workflow's jq filter rewrites exports to only `"."` (drops subpaths),
+// so `@omg-dev/sdk/auth` won't resolve in production deploy builds even
+// though it works locally during dev. Re-export here = one import surface
+// that always resolves.
+export * from "./auth/index"
+// Storage surface — useUpload() + <VibesUpload />. Re-exported here for
+// the same publish-workflow reason as auth (only "." subpath survives).
+export * from "./storage/index"
+// Feedback surface — <VibesFeedback /> gesture widget + trace capture.
+// Re-exported here for the same publish-workflow reason (only "." survives).
+export * from "./feedback/index"
+// Brand surface — <OmgBadge /> platform attribution badge.
+export * from "./brand/index"
+// Notifications surface — durable in-app inbox + Web Push registration.
+export * from "./notifications/index"
+// Sandbox router surface — server-side helpers for creating child sandboxes
+// through the in-VM agent, which stamps parent authority.
+export * from "./sandbox"
+
+// Builds Headers with Authorization: Bearer <token> when a token is present
+// in the auth bridge. Apps that don't wrap with <VibesAuthProvider> see no
+// token; requests go through unauthenticated and the server returns 401 for
+// scoped collections, 200 for global ones.
+function authHeaders(extra?: HeadersInit): Headers {
+  const h = new Headers(extra)
+  const { token } = getAuthContext()
+  if (token) h.set("Authorization", `Bearer ${token}`)
+  return h
+}
+
+/**
+ * Thrown when a request comes back with the server's auth-required signal
+ * (HTTP 401). Callers that don't catch it still won't get garbage data — the
+ * old paths swallowed 401 bodies and returned them as if they were rows.
+ */
+export class VibesAuthRequiredError extends Error {
+  constructor(message = "Authentication required") {
+    super(message)
+    this.name = "VibesAuthRequiredError"
+  }
+}
+
+// Wraps fetch with the auth bridge headers and turns the server's auth-required
+// signal (401) into a notifyAuthRequired() broadcast + a typed throw. Every REST
+// path in this module goes through here so the auto-prompt fires consistently.
+async function apiFetch(input: string, init?: RequestInit): Promise<Response> {
+  const res = await fetch(input, { ...init, headers: authHeaders(init?.headers) })
+  if (res.status === 401) {
+    // Only pop the login dialog once auth has settled — a 401 during the
+    // startup token race is transient (the bearer just isn't attached yet).
+    if (getAuthContext().authReady) notifyAuthRequired()
+    let message = "Authentication required"
+    try {
+      const body = await res.clone().json()
+      if (body && typeof body.error === "string") message = body.error
+    } catch {
+      // non-JSON body; keep the default message
+    }
+    throw new VibesAuthRequiredError(message)
+  }
+  return res
+}
+
+// ── useQuery / useCollection ─────────────────────────────────────────────────
+//
+// useQuery is the WS-first default: it subscribes to a collection (optionally
+// scoped by a `where` predicate evaluated server-side) over /__vibes_sub and
+// receives a snapshot + live row deltas. `api` is optional — pass it to enable
+// create/update/remove and the legacy SSE+REST fallback for pre-WS backends.
+// useCollection is a thin, deprecated wrapper kept for back-compat.
+
+export interface UseCollectionOptions {
+  /** API endpoint, e.g. "/api/entries" */
+  api: string
+  /** Collection name for filtering WS events, e.g. "entries" */
+  collection: string
+}
+
+export type QueryConnectionStatus =
+  | "loading"
+  | "live"
+  | "reconnecting"
+  | "stale"
+  | "auth_required"
+  | "unavailable"
+  | "error"
+
+export interface UseCollectionReturn<T> {
+  data: T[]
+  loading: boolean
+  error: string | null
+  status: QueryConnectionStatus
+  create: (item: Partial<T>) => Promise<T>
+  update: (id: string, patch: Partial<T>) => Promise<T>
+  remove: (id: string) => Promise<void>
+  refresh: () => void
+}
+
+export interface UseQueryOptions {
+  /** Collection name to subscribe to, e.g. "entries". */
+  collection: string
+  /** Optional predicate; scopes rows server-side (and client-side on the legacy fallback). */
+  where?: SubscribePredicate
+  /** Optional REST endpoint (e.g. "/api/entries"). Enables create/update/remove + the legacy fallback. */
+  api?: string
+}
+
+export type UseQueryReturn<T> = UseCollectionReturn<T>
+
+export function useQuery<T extends { id: string }>(
+  opts: UseQueryOptions
+): UseQueryReturn<T> {
+  const optsRef = useRef(opts)
+  optsRef.current = opts
+
+  const url = defaultSubscribeUrl()
+  const collectionKey = opts.collection
+  const whereKey = canonicalPredicateString(opts.where)
+  const store = useMemo(
+    () => getCollectionQueryStore<T>(url, opts.collection, opts.where),
+    [url, collectionKey, whereKey],
+  )
+  const snapshot = useSyncExternalStore(
+    (listener) => store.subscribe(listener),
+    () => store.getSnapshot(),
+    () => store.getSnapshot(),
+  )
+
+  useEffect(() => {
+    const api = optsRef.current.api
+    if (snapshot.status === "unavailable" && api) store.ensureLegacyFallback(api)
+  }, [snapshot.status, store])
+
+  const refresh = useCallback(() => {
+    const api = optsRef.current.api
+    if (!api) return
+    void store.refreshFromApi(api)
+  }, [store])
+
+  const create = useCallback(async (item: Partial<T>): Promise<T> => {
+    const api = optsRef.current.api
+    if (!api) throw new Error("useQuery: `api` is required to call create()")
+    const res = await apiFetch(api, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(item),
+    })
+    return res.json()
+  }, [])
+
+  const update = useCallback(async (id: string, patch: Partial<T>): Promise<T> => {
+    const api = optsRef.current.api
+    if (!api) throw new Error("useQuery: `api` is required to call update()")
+    const res = await apiFetch(`${api}/${id}`, {
+      method: "PATCH",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(patch),
+    })
+    return res.json()
+  }, [])
+
+  const remove = useCallback(async (id: string): Promise<void> => {
+    const api = optsRef.current.api
+    if (!api) throw new Error("useQuery: `api` is required to call remove()")
+    await apiFetch(`${api}/${id}`, { method: "DELETE" })
+  }, [])
+
+  return {
+    data: snapshot.data,
+    loading: snapshot.loading,
+    error: snapshot.error,
+    status: snapshot.status,
+    create,
+    update,
+    remove,
+    refresh,
+  }
+}
+
+/**
+ * @deprecated Use {@link useQuery} instead — it's the WS-first default and adds
+ * server-side `where` predicate scoping. This wrapper forwards to `useQuery`
+ * (full collection, no predicate) and remains only for back-compat.
+ */
+export function useCollection<T extends { id: string }>(
+  opts: UseCollectionOptions
+): UseCollectionReturn<T> {
+  return useQuery<T>({ collection: opts.collection, api: opts.api })
+}
+
+/**
+ * Best-effort client-side evaluation of a SubscribePredicate, used only by the
+ * legacy SSE+REST fallback to scope the REST result the way the WS snapshot
+ * would. The WS path is authoritative; this mirrors the common cases (SQL
+ * three-valued-logic edge cases around NULL are not reproduced exactly).
+ */
+function matchesPredicate(row: Record<string, unknown>, p: SubscribePredicate): boolean {
+  switch (p.op) {
+    case "and": return p.clauses.every(c => matchesPredicate(row, c))
+    case "or": return p.clauses.some(c => matchesPredicate(row, c))
+    case "not": return !matchesPredicate(row, p.clause)
+    case "eq": return row[p.column] === p.value
+    case "ne": return row[p.column] !== p.value
+    case "gt": return (row[p.column] as number | string) > p.value
+    case "gte": return (row[p.column] as number | string) >= p.value
+    case "lt": return (row[p.column] as number | string) < p.value
+    case "lte": return (row[p.column] as number | string) <= p.value
+    case "in": return p.values.includes(row[p.column] as string | number | boolean | null)
+    case "like": {
+      const v = row[p.column]
+      if (typeof v !== "string") return false
+      const re = new RegExp(
+        "^" + p.pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/%/g, ".*").replace(/_/g, ".") + "$",
+        "i",
+      )
+      return re.test(v)
+    }
+    case "isNull": return row[p.column] == null
+    case "isNotNull": return row[p.column] != null
+    default: return true
+  }
+}
+
+/**
+ * Legacy SSE + REST refetch loop. Used only as fallback when the WS
+ * subscription path (subscribeCollection) gives up — typically on an old
+ * deploy that doesn't serve /__vibes_sub. Same shape as the pre-Phase-1
+ * useCollection internals so behavior on older backends is unchanged.
+ *
+ * Returns an AbortController whose abort() tears the SSE stream down.
+ */
+function startLegacySseRefetch(
+  // Only the collection name is read here (to match invalidation events); the
+  // refresh() closure owns the REST fetch. Accept the loosened shape so both
+  // useQuery (api optional) and the deprecated useCollection can pass their ref.
+  optsRef: { current: { collection: string } },
+  refresh: () => void,
+  setError: (m: string) => void,
+): AbortController {
+  const evtUrl = `${typeof window !== "undefined" ? window.location.origin : ""}/__vibes_events`
+  const RECONNECT_BASE_MS = 1000
+  const RECONNECT_CAP_MS = 60_000
+  const RECONNECT_GIVE_UP = 6
+  const REFRESH_THROTTLE_MS = 2000
+
+  const ctl = new AbortController()
+  let consecutiveErrors = 0
+  let lastRefresh = 0
+
+  function throttledRefresh() {
+    const now = Date.now()
+    if (now - lastRefresh < REFRESH_THROTTLE_MS) return
+    lastRefresh = now
+    refresh()
+  }
+
+  class FatalError extends Error {}
+  let isFirstOpen = true
+
+  // Kick the initial REST fetch so `data` populates before SSE delivers
+  // its first invalidate.
+  refresh()
+
+  void fetchEventSource(evtUrl, {
+    signal: ctl.signal,
+    async onopen(res) {
+      if (res.ok && res.headers.get("content-type")?.includes("text/event-stream")) {
+        consecutiveErrors = 0
+        if (!isFirstOpen) throttledRefresh()
+        isFirstOpen = false
+        return
+      }
+      if (res.status === 401 || res.status === 403 || res.status === 400) {
+        if (res.status === 401 && getAuthContext().authReady) notifyAuthRequired()
+        throw new FatalError(`fatal ${res.status}`)
+      }
+      throw new Error(`unexpected ${res.status}`)
+    },
+    onmessage(ev: EventSourceMessage) {
+      if (!ev.data) return
+      try {
+        const event = JSON.parse(ev.data) as { type?: string; collection?: string }
+        if (event.type === "invalidate" && event.collection === optsRef.current.collection) {
+          throttledRefresh()
+        }
+      } catch { /* ignore malformed messages */ }
+    },
+    onclose() {
+      throw new Error("connection closed")
+    },
+    onerror(err) {
+      if (err instanceof FatalError) throw err
+      consecutiveErrors++
+      if (consecutiveErrors >= RECONNECT_GIVE_UP) {
+        setError("realtime stream unavailable — falling back to manual refresh")
+        throw new FatalError("give up after consecutive errors")
+      }
+      return Math.min(
+        RECONNECT_CAP_MS,
+        RECONNECT_BASE_MS * Math.pow(2, consecutiveErrors - 1),
+      )
+    },
+  }).catch(() => { /* fatal errors throw from onerror */ })
+
+  return ctl
+}
+
+// ── subscribeCollection ──────────────────────────────────────────────────────
+//
+// Low-level per-query reactive subscription over WebSocket (Phase 1 of the
+// delta-push migration). Where useCollection above polls REST after each SSE
+// invalidate, this subscribes to a specific collection on a dedicated WS
+// channel and receives a full snapshot on subscribe and on every write.
+//
+// Phase 1 scope: full-collection snapshots. Phase 2 adds predicate filters in
+// the subscribe payload; Phase 3 swaps snapshots for row-level deltas.
+//
+// This API is intentionally NOT wired into useCollection yet. Existing
+// callers stay on the SSE+REST path until we've measured that the WS path
+// is at least as fast, then useCollection swaps internals while keeping the
+// hook signature.
+
+// Mirrors the server-side Predicate AST. Defined here so SDK callers don't
+// need to import from @omg-dev/server (and so the wire format stays a
+// well-defined seam). When the SDK eventually grows a query-builder DSL,
+// it'll target this shape.
+export type SubscribePredicate =
+  | { op: "and"; clauses: SubscribePredicate[] }
+  | { op: "or"; clauses: SubscribePredicate[] }
+  | { op: "not"; clause: SubscribePredicate }
+  | { op: "eq" | "ne"; column: string; value: string | number | boolean | null }
+  | { op: "gt" | "gte" | "lt" | "lte"; column: string; value: string | number }
+  | { op: "in"; column: string; values: (string | number | boolean | null)[] }
+  | { op: "like"; column: string; pattern: string }
+  | { op: "isNull" | "isNotNull"; column: string }
+
+export interface SubscribeCollectionOptions<T> {
+  /** Collection name, e.g. "posts". */
+  collection: string
+  /** Optional JSON predicate AST to narrow the snapshot server-side. */
+  where?: SubscribePredicate
+  /** Called with the full row set on initial subscribe and after each change. */
+  onSnapshot: (rows: T[]) => void
+  /** Called with an error code + message; subscription remains open. */
+  onError?: (code: string, message: string) => void
+  /** Override the WS URL (default: ws[s]://<location.host>/__vibes_sub). */
+  url?: string
+}
+
+interface InternalSubscribeCollectionOptions<T> extends SubscribeCollectionOptions<T> {
+  resumeFromSeq?: number | null
+  onSeq?: (seq: number) => void
+  onStatus?: (status: QueryConnectionStatus) => void
+}
+
+export interface SubscribeHandle {
+  /** Closes the underlying WebSocket and stops reconnect attempts. */
+  unsubscribe(): void
+}
+
+interface ServerFrame {
+  type: "snapshot" | "delta" | "resumed" | "error"
+  subId?: string
+  collection?: string
+  seq?: number
+  rows?: unknown[]
+  op?: "insert" | "update" | "delete"
+  row?: Record<string, unknown>
+  id?: string
+  fromSeq?: number
+  toSeq?: number
+  replayed?: number
+  code?: string
+  message?: string
+}
+
+function defaultSubscribeUrl(): string {
+  if (typeof window === "undefined") return ""
+  const proto = window.location.protocol === "https:" ? "wss:" : "ws:"
+  return `${proto}//${window.location.host}/__vibes_sub`
+}
+
+interface LogicalSub<T extends { id: string } = { id: string }> {
+  subId: string
+  collection: string
+  where?: SubscribePredicate
+  state: Map<string, T>
+  lastSeq: number | null
+  onSnapshot: (rows: T[]) => void
+  onError?: (code: string, message: string) => void
+  onSeq?: (seq: number) => void
+  onStatus?: (status: QueryConnectionStatus) => void
+}
+
+function makeSubId(): string {
+  return typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+    ? crypto.randomUUID()
+    : `s${Date.now()}-${Math.random().toString(36).slice(2)}`
+}
+
+function protocolsForAuth(token: string | null): string[] | undefined {
+  return token ? [`vibes-bearer.${token}`] : undefined
+}
+
+const RECONNECT_BASE_MS = 1000
+const RECONNECT_CAP_MS = 60_000
+const RECONNECT_GIVE_UP = 6
+
+type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }
+
+function canonicalJson(value: unknown): string {
+  return JSON.stringify(canonicalizeValue(value))
+}
+
+function canonicalizeValue(value: unknown): JsonValue {
+  if (value === null) return null
+  if (Array.isArray(value)) return value.map(canonicalizeValue)
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value
+  if (typeof value !== "object") return null
+  const out: { [key: string]: JsonValue } = {}
+  for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+    out[key] = canonicalizeValue((value as Record<string, unknown>)[key])
+  }
+  return out
+}
+
+function normalizePredicate(predicate: SubscribePredicate | undefined): SubscribePredicate | undefined {
+  if (!predicate) return undefined
+  switch (predicate.op) {
+    case "and":
+    case "or": {
+      const clauses = predicate.clauses
+        .map((clause) => normalizePredicate(clause)!)
+        .sort((a, b) => canonicalJson(a).localeCompare(canonicalJson(b)))
+      return { op: predicate.op, clauses }
+    }
+    case "not":
+      return { op: "not", clause: normalizePredicate(predicate.clause)! }
+    case "in":
+      return {
+        ...predicate,
+        values: [...predicate.values].sort((a, b) => canonicalJson(a).localeCompare(canonicalJson(b))),
+      }
+    default:
+      return { ...predicate }
+  }
+}
+
+function canonicalPredicateString(predicate: SubscribePredicate | undefined): string {
+  return canonicalJson(normalizePredicate(predicate) ?? null)
+}
+
+function rowOrderValue(row: { id: string } & Record<string, unknown>): string | number | null {
+  const createdAt = row.createdAt ?? row.created_at
+  if (typeof createdAt === "string" || typeof createdAt === "number") return createdAt
+  const updatedAt = row.updatedAt ?? row.updated_at
+  if (typeof updatedAt === "string" || typeof updatedAt === "number") return updatedAt
+  return null
+}
+
+function compareRows(a: { id: string } & Record<string, unknown>, b: { id: string } & Record<string, unknown>): number {
+  const av = rowOrderValue(a)
+  const bv = rowOrderValue(b)
+  if (av !== null && bv !== null && av !== bv) return av > bv ? -1 : 1
+  if (av !== null && bv === null) return -1
+  if (av === null && bv !== null) return 1
+  return b.id.localeCompare(a.id)
+}
+
+function orderedRows<T extends { id: string }>(rows: Iterable<T>): T[] {
+  return Array.from(rows).sort((a, b) => compareRows(a as T & Record<string, unknown>, b as T & Record<string, unknown>))
+}
+
+class SharedCollectionSocket {
+  private ws: WebSocket | null = null
+  private connecting = false
+  private closedByManager = false
+  private consecutiveErrors = 0
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  private flushQueued = false
+  private readonly subs = new Map<string, LogicalSub>()
+  private readonly pendingSubIds = new Set<string>()
+
+  constructor(
+    private readonly url: string,
+    private readonly token: string | null,
+  ) {}
+
+  add<T extends { id: string }>(sub: LogicalSub<T>): void {
+    this.subs.set(sub.subId, sub as LogicalSub)
+    this.pendingSubIds.add(sub.subId)
+    if (this.isOpen()) this.queueFlush()
+    else this.connect()
+  }
+
+  remove(subId: string): void {
+    const existed = this.subs.delete(subId)
+    this.pendingSubIds.delete(subId)
+    if (existed && this.isOpen()) this.sendFrame({ op: "unsub", subId })
+    if (this.subs.size === 0) this.shutdown()
+  }
+
+  isIdle(): boolean {
+    return this.subs.size === 0
+  }
+
+  shutdown(): void {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer)
+      this.reconnectTimer = null
+    }
+    this.pendingSubIds.clear()
+    this.closedByManager = true
+    try { this.ws?.close() } catch { /* idempotent */ }
+    this.ws = null
+    this.connecting = false
+    this.consecutiveErrors = 0
+  }
+
+  private connect(): void {
+    if (this.connecting || this.isOpen() || this.subs.size === 0) return
+    this.connecting = true
+    this.closedByManager = false
+    const protocols = protocolsForAuth(this.token)
+
+    try {
+      this.ws = protocols ? new WebSocket(this.url, protocols) : new WebSocket(this.url)
+    } catch (err) {
+      this.connecting = false
+      this.broadcastError("ws_construct_failed", (err as Error).message)
+      this.scheduleReconnect()
+      return
+    }
+
+    this.ws.addEventListener("open", () => {
+      this.connecting = false
+      this.consecutiveErrors = 0
+      this.broadcastStatus("live")
+      for (const subId of this.subs.keys()) this.pendingSubIds.add(subId)
+      this.queueFlush()
+    })
+
+    this.ws.addEventListener("message", (ev: MessageEvent<string>) => {
+      this.handleMessage(ev.data)
+    })
+
+    this.ws.addEventListener("close", () => {
+      this.ws = null
+      this.connecting = false
+      if (this.closedByManager || this.subs.size === 0) return
+      this.broadcastStatus("reconnecting")
+      this.scheduleReconnect()
+    })
+
+    this.ws.addEventListener("error", () => {
+      // The close event will follow; reconnect is scheduled there.
+    })
+  }
+
+  private queueFlush(): void {
+    if (this.flushQueued) return
+    this.flushQueued = true
+    queueMicrotask(() => {
+      this.flushQueued = false
+      this.flushPendingSubs()
+    })
+  }
+
+  private flushPendingSubs(): void {
+    if (!this.isOpen()) return
+    const ids = Array.from(this.pendingSubIds)
+    this.pendingSubIds.clear()
+
+    for (const subId of ids) {
+      const sub = this.subs.get(subId)
+      if (!sub) continue
+      const frame: Record<string, unknown> = {
+        op: "sub",
+        subId,
+        collection: sub.collection,
+      }
+      if (sub.where !== undefined) frame.where = sub.where
+      if (sub.lastSeq !== null) frame.resumeFromSeq = sub.lastSeq
+      this.sendFrame(frame)
+    }
+  }
+
+  private handleMessage(data: string): void {
+    let frame: ServerFrame
+    try {
+      frame = JSON.parse(data) as ServerFrame
+    } catch {
+      this.broadcastError("bad_frame", "non-JSON frame from server")
+      return
+    }
+
+    if (!frame.subId) {
+      if (frame.type === "error") this.broadcastError(frame.code ?? "unknown", frame.message ?? "")
+      return
+    }
+
+    const sub = this.subs.get(frame.subId)
+    if (!sub) return
+
+    if (frame.type === "snapshot") {
+      sub.state.clear()
+      for (const row of (frame.rows ?? []) as Array<{ id: string }>) {
+        if (row && typeof row.id === "string") sub.state.set(row.id, row)
+      }
+      if (typeof frame.seq === "number") sub.lastSeq = frame.seq
+      if (typeof frame.seq === "number") sub.onSeq?.(frame.seq)
+      this.publish(sub)
+      return
+    }
+
+    if (frame.type === "delta") {
+      if (frame.op === "insert" || frame.op === "update") {
+        const row = frame.row as { id: string } | undefined
+        if (!row || typeof row.id !== "string") {
+          sub.onError?.("bad_delta", "delta missing row.id")
+          return
+        }
+        sub.state.set(row.id, row)
+        if (typeof frame.seq === "number") sub.lastSeq = frame.seq
+        if (typeof frame.seq === "number") sub.onSeq?.(frame.seq)
+        this.publish(sub)
+        return
+      }
+      if (frame.op === "delete") {
+        if (typeof frame.id !== "string") {
+          sub.onError?.("bad_delta", "delete delta missing id")
+          return
+        }
+        sub.state.delete(frame.id)
+        if (typeof frame.seq === "number") sub.lastSeq = frame.seq
+        if (typeof frame.seq === "number") sub.onSeq?.(frame.seq)
+        this.publish(sub)
+        return
+      }
+      sub.onError?.("bad_delta", `unknown delta op: ${String(frame.op)}`)
+      return
+    }
+
+    if (frame.type === "resumed") {
+      if (typeof frame.toSeq === "number") sub.lastSeq = frame.toSeq
+      if (typeof frame.toSeq === "number") sub.onSeq?.(frame.toSeq)
+      return
+    }
+
+    if (frame.type === "error") {
+      sub.onError?.(frame.code ?? "unknown", frame.message ?? "")
+    }
+  }
+
+  private publish(sub: LogicalSub): void {
+    try { sub.onSnapshot(orderedRows(sub.state.values())) } catch { /* user cb */ }
+  }
+
+  private scheduleReconnect(): void {
+    if (this.subs.size === 0 || this.reconnectTimer) return
+    this.consecutiveErrors++
+    if (this.consecutiveErrors >= RECONNECT_GIVE_UP) {
+      this.broadcastError("give_up", `gave up after ${this.consecutiveErrors} reconnect attempts`)
+      return
+    }
+    const delay = Math.min(
+      RECONNECT_CAP_MS,
+      RECONNECT_BASE_MS * Math.pow(2, this.consecutiveErrors - 1),
+    )
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null
+      this.connect()
+    }, delay)
+  }
+
+  private broadcastError(code: string, message: string): void {
+    for (const sub of this.subs.values()) sub.onError?.(code, message)
+  }
+
+  private broadcastStatus(status: QueryConnectionStatus): void {
+    for (const sub of this.subs.values()) sub.onStatus?.(status)
+  }
+
+  private sendFrame(frame: unknown): void {
+    try {
+      this.ws?.send(JSON.stringify(frame))
+    } catch (err) {
+      this.broadcastError("ws_send_failed", (err as Error).message)
+    }
+  }
+
+  private isOpen(): boolean {
+    return this.ws?.readyState === 1
+  }
+}
+
+const sharedCollectionSockets = new Map<string, SharedCollectionSocket>()
+
+function sharedSocketKey(url: string, token: string | null): string {
+  return `${url}\n${token ?? ""}`
+}
+
+function getSharedCollectionSocket(url: string, token: string | null): SharedCollectionSocket {
+  const key = sharedSocketKey(url, token)
+  let socket = sharedCollectionSockets.get(key)
+  if (!socket) {
+    socket = new SharedCollectionSocket(url, token)
+    sharedCollectionSockets.set(key, socket)
+  }
+  return socket
+}
+
+function openSocketSubscription<T = Record<string, unknown>>(
+  opts: InternalSubscribeCollectionOptions<T>,
+): SubscribeHandle {
+  const url = opts.url ?? defaultSubscribeUrl()
+  const token = getAuthContext().token
+  const key = sharedSocketKey(url, token)
+  const socket = getSharedCollectionSocket(url, token)
+  const sub: LogicalSub<T & { id: string }> = {
+    subId: makeSubId(),
+    collection: opts.collection,
+    where: opts.where,
+    state: new Map<string, T & { id: string }>(),
+    lastSeq: opts.resumeFromSeq ?? null,
+    onSnapshot: opts.onSnapshot as (rows: Array<T & { id: string }>) => void,
+    onError: opts.onError,
+    onSeq: opts.onSeq,
+    onStatus: opts.onStatus,
+  }
+
+  socket.add(sub)
+
+  return {
+    unsubscribe() {
+      socket.remove(sub.subId)
+      if (socket.isIdle()) sharedCollectionSockets.delete(key)
+    },
+  }
+}
+
+interface QuerySnapshot<T> {
+  data: T[]
+  loading: boolean
+  error: string | null
+  status: QueryConnectionStatus
+}
+
+type QueryStoreListener = () => void
+
+interface RowSubscriber<T> {
+  onSnapshot: (rows: T[]) => void
+  onError?: (code: string, message: string) => void
+}
+
+function makeInitialQuerySnapshot<T>(): QuerySnapshot<T> {
+  return { data: [], loading: true, error: null, status: "loading" }
+}
+
+class CollectionQueryStore<T extends { id: string }> {
+  private readonly listeners = new Set<QueryStoreListener>()
+  private readonly rowSubscribers = new Set<RowSubscriber<T>>()
+  private socketHandle: SubscribeHandle | null = null
+  private fallbackHandle: AbortController | null = null
+  private authUnsub: (() => void) | null = null
+  private authToken: string | null = getAuthContext().token
+  private authReady = getAuthContext().authReady
+  private lastSeq: number | null = null
+  private pendingAuthRequired: string | null = null
+  private notifyQueued = false
+  private rowsDirty = false
+  private snapshot: QuerySnapshot<T> = makeInitialQuerySnapshot()
+
+  constructor(
+    readonly key: string,
+    private readonly url: string,
+    private readonly collection: string,
+    private readonly where: SubscribePredicate | undefined,
+    private readonly onIdle: (key: string) => void,
+  ) {}
+
+  subscribe(listener: QueryStoreListener): () => void {
+    this.listeners.add(listener)
+    this.start()
+    return () => {
+      this.listeners.delete(listener)
+      this.stopIfIdle()
+    }
+  }
+
+  subscribeRows(subscriber: RowSubscriber<T>): () => void {
+    this.rowSubscribers.add(subscriber)
+    this.start()
+    if (!this.snapshot.loading) {
+      queueMicrotask(() => {
+        if (this.rowSubscribers.has(subscriber)) subscriber.onSnapshot(this.snapshot.data)
+      })
+    }
+    return () => {
+      this.rowSubscribers.delete(subscriber)
+      this.stopIfIdle()
+    }
+  }
+
+  destroy(): void {
+    this.stop()
+    this.listeners.clear()
+    this.rowSubscribers.clear()
+    this.lastSeq = null
+    this.notifyQueued = false
+    this.rowsDirty = false
+    this.snapshot = makeInitialQuerySnapshot()
+  }
+
+  getSnapshot(): QuerySnapshot<T> {
+    return this.snapshot
+  }
+
+  ensureLegacyFallback(api: string): void {
+    if (this.fallbackHandle) return
+    this.fallbackHandle = startLegacySseRefetch(
+      { current: { collection: this.collection } },
+      () => this.refreshFromApi(api, "stale"),
+      (message) => this.setError("unavailable", message),
+    )
+  }
+
+  async refreshFromApi(api: string, status: QueryConnectionStatus = this.socketHandle ? "live" : "stale"): Promise<void> {
+    try {
+      const res = await apiFetch(api)
+      const body = await res.json()
+      let rows = Array.isArray(body) ? body as T[] : []
+      if (this.where) rows = rows.filter(row => matchesPredicate(row as Record<string, unknown>, this.where!))
+      this.setRows(orderedRows(rows), status)
+    } catch (err) {
+      this.setError("error", err instanceof Error ? err.message : String(err))
+    }
+  }
+
+  private start(): void {
+    if (!this.authUnsub) {
+      this.authUnsub = subscribeAuthChange((snap) => this.handleAuthChange(snap.token, snap.authReady))
+    }
+    if (!this.socketHandle) this.openSocket()
+  }
+
+  private stopIfIdle(): void {
+    if (this.listeners.size > 0 || this.rowSubscribers.size > 0) return
+    this.stop()
+    this.onIdle(this.key)
+  }
+
+  private stop(): void {
+    this.socketHandle?.unsubscribe()
+    this.socketHandle = null
+    this.fallbackHandle?.abort()
+    this.fallbackHandle = null
+    this.authUnsub?.()
+    this.authUnsub = null
+    this.pendingAuthRequired = null
+  }
+
+  private openSocket(): void {
+    this.authToken = getAuthContext().token
+    this.authReady = getAuthContext().authReady
+    this.socketHandle = openSocketSubscription<T>({
+      url: this.url,
+      collection: this.collection,
+      where: this.where,
+      resumeFromSeq: this.lastSeq,
+      onSeq: (seq) => { this.lastSeq = seq },
+      onStatus: (status) => {
+        if (status === "reconnecting") this.setStatus("reconnecting", null)
+      },
+      onSnapshot: (rows) => this.setRows(rows, "live"),
+      onError: (code, message) => this.handleSocketError(code, message),
+    })
+  }
+
+  private handleAuthChange(token: string | null, authReady: boolean): void {
+    const tokenChanged = token !== this.authToken
+    const readyChanged = authReady !== this.authReady
+    this.authToken = token
+    this.authReady = authReady
+
+    if (tokenChanged) {
+      this.socketHandle?.unsubscribe()
+      this.socketHandle = null
+      this.fallbackHandle?.abort()
+      this.fallbackHandle = null
+      this.lastSeq = null
+      this.pendingAuthRequired = null
+      this.setRows([], "loading", true)
+      this.openSocket()
+      return
+    }
+
+    if (readyChanged && authReady && this.pendingAuthRequired) {
+      const message = this.pendingAuthRequired
+      this.pendingAuthRequired = null
+      notifyAuthRequired()
+      this.setStatus("auth_required", `auth_required: ${message}`, true)
+    }
+  }
+
+  private handleSocketError(code: string, message: string): void {
+    this.broadcastRowError(code, message)
+    if (code === "auth_required") {
+      if (!getAuthContext().authReady) {
+        this.pendingAuthRequired = message
+        this.setStatus("loading", null)
+        return
+      }
+      notifyAuthRequired()
+      this.setStatus("auth_required", `${code}: ${message}`, true)
+      return
+    }
+    if (code === "give_up") {
+      this.setStatus("unavailable", "realtime stream unavailable", true)
+      return
+    }
+    this.setStatus("error", `${code}: ${message}`, true)
+  }
+
+  private setRows(rows: T[], status: QueryConnectionStatus, forceLoading = false): void {
+    this.snapshot = {
+      data: rows,
+      loading: forceLoading || status === "loading",
+      error: null,
+      status,
+    }
+    this.rowsDirty = true
+    this.queueNotify()
+  }
+
+  private setStatus(status: QueryConnectionStatus, error: string | null, doneLoading = false): void {
+    this.snapshot = {
+      ...this.snapshot,
+      loading: status === "loading" ? true : doneLoading ? false : this.snapshot.loading,
+      error,
+      status,
+    }
+    this.queueNotify()
+  }
+
+  private setError(status: QueryConnectionStatus, error: string): void {
+    this.snapshot = {
+      ...this.snapshot,
+      loading: false,
+      error,
+      status,
+    }
+    this.queueNotify()
+  }
+
+  private queueNotify(): void {
+    if (this.notifyQueued) return
+    this.notifyQueued = true
+    queueMicrotask(() => {
+      this.notifyQueued = false
+      const rowsDirty = this.rowsDirty
+      this.rowsDirty = false
+      for (const listener of this.listeners) listener()
+      if (rowsDirty) {
+        for (const subscriber of this.rowSubscribers) {
+          try { subscriber.onSnapshot(this.snapshot.data) } catch { /* user cb */ }
+        }
+      }
+    })
+  }
+
+  private broadcastRowError(code: string, message: string): void {
+    for (const subscriber of this.rowSubscribers) subscriber.onError?.(code, message)
+  }
+}
+
+const collectionQueryStores = new Map<string, CollectionQueryStore<{ id: string }>>()
+
+function collectionQueryKey(url: string, collection: string, where: SubscribePredicate | undefined): string {
+  return `${url}\n${collection}\n${canonicalPredicateString(where)}`
+}
+
+function getCollectionQueryStore<T extends { id: string }>(
+  url: string,
+  collection: string,
+  where: SubscribePredicate | undefined,
+): CollectionQueryStore<T> {
+  const normalizedWhere = normalizePredicate(where)
+  const key = collectionQueryKey(url, collection, normalizedWhere)
+  let store = collectionQueryStores.get(key) as CollectionQueryStore<T> | undefined
+  if (!store) {
+    store = new CollectionQueryStore<T>(
+      key,
+      url,
+      collection,
+      normalizedWhere,
+      (idleKey) => collectionQueryStores.delete(idleKey),
+    )
+    collectionQueryStores.set(key, store as CollectionQueryStore<{ id: string }>)
+  }
+  return store
+}
+
+export function subscribeCollection<T = Record<string, unknown>>(
+  opts: SubscribeCollectionOptions<T>,
+): SubscribeHandle {
+  const store = getCollectionQueryStore<T & { id: string }>(
+    opts.url ?? defaultSubscribeUrl(),
+    opts.collection,
+    opts.where,
+  )
+  const unsubscribe = store.subscribeRows({
+    onSnapshot: opts.onSnapshot as (rows: Array<T & { id: string }>) => void,
+    onError: opts.onError,
+  })
+  return { unsubscribe }
+}
+
+export function _resetSharedCollectionSocketsForTests(): void {
+  for (const store of collectionQueryStores.values()) {
+    store.destroy()
+  }
+  collectionQueryStores.clear()
+  for (const socket of sharedCollectionSockets.values()) socket.shutdown()
+  sharedCollectionSockets.clear()
+}
+
+export function _canonicalPredicateForTests(predicate: SubscribePredicate | undefined): string {
+  return canonicalPredicateString(predicate)
+}
+
+// ── Re-exports for convenience ───────────────────────────────────────────────
+
+export type { UseCollectionOptions as CollectionOptions }