feat: Multi-module React provider and ConnectionManager.rebuild()

[Ludv1gL]

Summary

The React layer ships a first-class single-module story — one
<SpacetimeDBProvider> per app, useSpacetimeDB() reads the closest
one — but no supported pattern for apps that need to connect to more
than one module concurrently (game + chat, core + telemetry, org +
multiplayer, etc.). Stacking nested <SpacetimeDBProvider>s breaks
because useTable(tables.X) can only reach the nearest provider, and
the internal ConnectionManager that would otherwise let applications
build their own adapter layer is not re-exported.

This PR adds a keyed multi-module provider, re-exports
ConnectionManager, and adds a rebuild(key, builder) method that
closes a real gap in the pool API. Existing single-<SpacetimeDBProvider>
apps are unchanged — the new hook forms take an optional leading key
argument; zero-arg calls hit the original context path exactly as before.

Changes

• crates/bindings-typescript/src/sdk/connection_manager.ts:
  New rebuild(key, builder) method that tears down the existing
  connection and installs a fresh one under the same refcount + listener
  set. Extracted shared #install / #teardown helpers so retain,
  release, and rebuild go through a single code path. rebuild
  cancels a pending release if one is scheduled, returns null when the
  key has no retain, and removes the old connection's callbacks before
  swapping so stale events never leak into the pool state.
• crates/bindings-typescript/src/sdk/index.ts: Re-export
  ConnectionManager and alias the internal state type as
  ManagedConnectionState so application code can inter-op.
• crates/bindings-typescript/src/react/SpacetimeDBMultiProvider.ts
  (new, 160 LOC): <SpacetimeDBMultiProvider connections={{ key: builder, ... }}>
  retains one pool entry per label on mount, subscribes to every entry's
  state via useSyncExternalStore, and exposes a Map<label, ConnectionState>
  to the subtree. Absorbs inline-object-prop churn with a content-based
  signature over (label, uri, moduleName) — two renders whose tuples
  match reuse the same entries-array identity, avoiding spurious
  retain/release cycles. Per-label fallback state so consumers comparing
  connectionId across labels don't see a single shared
  ConnectionId.random() before the pool resolves.
• crates/bindings-typescript/src/react/useSpacetimeDB.ts:
  useSpacetimeDB(key?) now reads both the single-provider and
  multi-provider contexts unconditionally (Rules of Hooks), then
  dispatches on key. Zero-arg form is exactly the pre-PR behavior.
  Thrown errors for useSpacetimeDB('missing') include the list of
  registered keys.
• crates/bindings-typescript/src/react/useTable.ts /
  useReducer.ts: Keyed overloads —
  useTable(key, tables.user) / useReducer(key, def) — that dispatch
  through useSpacetimeDB(key). Internal logic extracted into
  useTableInternal / useReducerInternal so the overloads are a thin
  dispatch wrapper.
• crates/bindings-typescript/src/react/useSpacetimeDBStatus.ts
  (new): useSpacetimeDBStatus() returns the live
  Map<label, ConnectionState> from the nearest SpacetimeDBMultiProvider.
  Useful for per-module connection-health UI.
• crates/bindings-typescript/src/react/index.ts: Exports for
  SpacetimeDBMultiProvider, SpacetimeDBMultiContext,
  useSpacetimeDBStatus, and the supporting types.
• crates/bindings-typescript/tests/connection_manager.test.ts:
  Eight new rebuild() cases covering teardown, refcount preservation,
  pending-release cancellation, stale-callback removal, listener
  re-wiring, and fresh-connection event routing. Updated the test file's
  mirror implementation to match the new #install / #teardown
  factoring.
• crates/bindings-typescript/tests/multi_provider.test.tsx (new):
  Nine React-layer tests (Testing Library + happy-dom) covering render,
  keyed-dispatch correctness, missing-key and missing-provider errors,
  useSpacetimeDBStatus aggregation, reactivity to onConnect,
  StrictMode mount→unmount→remount survival, and absorption of inline
  connections={{...}} prop churn.
• crates/bindings-typescript/vitest.config.ts: Include
  tests/**/*.test.tsx in the glob and typecheck set.
• crates/bindings-typescript/package.json + pnpm-lock.yaml:
  Dev-deps for the React tests — @testing-library/react, happy-dom,
  react, react-dom, @types/react, @types/react-dom.

Safety

• Backward compatibility: Zero-arg useSpacetimeDB(),
  useTable(query), useReducer(def), and existing
  <SpacetimeDBProvider> usage are untouched. The overload signatures
  collapse into a single implementation that runs the same useContext
  calls whether or not a key was passed, so hook order stays stable
  across call forms.
• Rules of Hooks: useSpacetimeDB calls both
  useContext(SpacetimeDBContext) and useContext(SpacetimeDBMultiContext)
  unconditionally on every render, then branches on the argument. All
  keyed hooks delegate through useSpacetimeDB(key) with no ternary at
  the call site, so ESLint react-hooks/rules-of-hooks passes without
  exemptions.
• StrictMode safety: SpacetimeDBMultiProvider uses the existing
  pool semantics — retain on mount, release on cleanup — and the
  pool's setTimeout(0) deferred teardown absorbs React 18's
  double-mount. Covered by
  multi_provider.test.tsx:'StrictMode mount → unmount → remount keeps the connection alive'.
• Pool sharing: Two SpacetimeDBMultiProviders registering the same
  (uri, moduleName) under different labels share a single WebSocket
  — the pool key is derived from builder identity, not from the React
  label — so unmounting one provider releases its retain without tearing
  the socket while sibling providers are still alive.
• rebuild() semantics: Synchronously removes the old connection's
  onConnect / onDisconnect / onConnectError callbacks before
  calling disconnect(), then installs the new connection. Listeners
  registered via subscribe() are unaffected, so
  useSyncExternalStore consumers see the new state on the next
  notification rather than a brief empty gap.
• No module-level mutable state: The per-label fallback map lives in
  a per-provider useRef, so multiple providers don't share a random
  ConnectionId fallback.

Example

import {
  SpacetimeDBMultiProvider,
  useSpacetimeDB,
  useTable,
  useSpacetimeDBStatus,
} from 'spacetimedb/react';

function App() {
  const connections = useMemo(() => ({
    game: GameDbConnection.builder().withUri(GAME_URI).withDatabaseName('game'),
    chat: ChatDbConnection.builder().withUri(GAME_URI).withDatabaseName('chat'),
  }), []);

  return (
    <SpacetimeDBMultiProvider connections={connections}>
      <PlayerList />
      <ChatPanel />
      <ConnectionStatusBar />
    </SpacetimeDBMultiProvider>
  );
}

function PlayerList() {
  const [players] = useTable('game', gameTables.player);
  return <ul>{players.map(p => <li key={p.id}>{p.name}</li>)}</ul>;
}

function ChatPanel() {
  const [messages] = useTable('chat', chatTables.message);
  return <ul>{messages.map(m => <li key={m.id}>{m.text}</li>)}</ul>;
}

function ConnectionStatusBar() {
  const status = useSpacetimeDBStatus();
  return (
    <div>
      {Array.from(status.entries()).map(([label, state]) => (
        <span key={label}>{label}: {state.isActive ? 'ok' : 'connecting'}</span>
      ))}
    </div>
  );
}

Test plan

• pnpm --filter spacetimedb test — 195/195 pass, including 8 new
  rebuild() cases and 9 new React-layer cases covering the keyed
  dispatch, error surfaces, StrictMode, and inline-prop churn
• pnpm --filter spacetimedb lint — clean (ESLint + Prettier)
• pnpm --filter spacetimedb build — clean (tsup all variants +
  tsc types build)
• Verified <SpacetimeDBProvider> + useSpacetimeDB() +
  useTable(query) unchanged — the single-module db_connection.test.ts
  suite and all 19 pre-existing test files still pass
• Manual React DevTools check: zero-arg useSpacetimeDB() in a
  subtree wrapped by both providers reads the single-provider context,
  not the multi-provider map

🤖 Generated with Claude Code

[Ludv1gL]

Added a follow-up commit (c9eee82) that makes <SpacetimeDBMultiProvider>s compose by merging when nested. Motivating use case: apps with a mix of long-lived and short-lived modules (e.g. org-scoped connections that outlive a single project, plus project-scoped connections that swap on project change).

Behavior:

• Outer labels remain visible from an inner subtree (useSpacetimeDB('label') resolves through the parent provider even when called inside a child <SpacetimeDBMultiProvider>).
• Inner entries shadow outer entries only on label collision.
• Unmounting the inner provider only releases the inner's pool retains; outer retains are untouched — no reliance on the release-then-retain deferred-cleanup trick for the persistent half of the tree.

Covered by four new tests:

• nested provider: outer labels remain visible from inner subtree
• nested provider: inner provider shadows outer label on collision
• nested provider: inner unmount only releases inner entries
• subset swap: changing one label releases that entry, keeps siblings alive

Total: 199 tests pass. Lint + build clean.