@nebulr-group/bridge-svelte 0.3.2 → 0.4.0-beta.0

package/dist/client/tracking/pii-hashing.spec.js

@@ -1,5 +1,4 @@
-import { describe, it, expect, beforeAll } from 'vitest';
-import { webcrypto } from 'node:crypto';
+import { describe, it, expect } from 'vitest';
 import { sha256Email } from './pii-hashing.js';
 /**
  * Client-side PII hashing fixtures.
@@ -17,18 +16,9 @@ import { sha256Email } from './pii-hashing.js';
 const USER_AT_EXAMPLE_COM_HASH = 'b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514';
 // SHA-256 hex of "admin@gmail.com"
 const ADMIN_AT_GMAIL_COM_HASH = '7932b2e116b076a54f452848eaabd5857f61bd957fe8a218faf216f24c9885bb';
-/**
- * Vitest's `environment: 'node'` exposes Node's `webcrypto` at `globalThis.crypto`
- * from v19+, but the `digest()` API is the same as the browser `crypto.subtle`
- * that `sha256Email` expects. We defensively wire it up here so the test is
- * robust across Node versions.
- */
-beforeAll(() => {
-    if (!globalThis.crypto || typeof globalThis.crypto.subtle?.digest !== 'function') {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        globalThis.crypto = webcrypto;
-    }
-});
+// Vitest's `environment: 'node'` exposes the Web Crypto API at
+// `globalThis.crypto` (Node 19+), with the same `crypto.subtle.digest()` the
+// browser provides and `sha256Email` expects.
 describe('sha256Email (client)', () => {
     it('hashes a plain, already-normalized email to the known SHA-256 hex (matches server fixture)', async () => {
         await expect(sha256Email('user@example.com')).resolves.toBe(USER_AT_EXAMPLE_COM_HASH);

package/dist/core/bridge-instance.d.ts

@@ -45,7 +45,7 @@ export declare const flagsStore: Readable<Record<string, boolean>>;
 export declare const bridgeReadyStore: Readable<boolean>;
 /** App-level config (SSO providers, feature flags, etc.) — loaded anonymously on init */
 export declare const appConfigStore: Readable<AppConfig | null>;
-interface SubscriptionState {
+export interface SubscriptionState {
     status: SubscriptionStatus | null;
     plans: Plan[] | null;
     loading: boolean;
@@ -59,4 +59,3 @@ export declare const auth: BridgeAuth;
 export declare const _flagsWritable: Writable<Record<string, boolean>>;
 export declare const _profileWritable: Writable<Profile | null | undefined>;
 export declare const _errorWritable: Writable<string | null>;
-export {};

package/dist/core/bridge-instance.js

@@ -84,10 +84,6 @@ export function initBridge(config) {
     _instance.on('auth:error', (err) => {
         _error.set(err.message);
     });
-    // Load app config anonymously (drives SSO buttons, signup toggle, etc.).
-    // Cached in `_appConfigPromise` so LoginForm (and others) can await the
-    // result via `ensureAppConfig()` instead of racing the store update.
-    void ensureAppConfig();
     logger.debug('[bridge-instance] initialized');
     return _instance;
 }

package/dist/core/bridge-runtime.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Bridge core runtime — the realtime + reactive-identity wiring that every
+ * Bridge capability (auth, flags, billing, ...) rides on top of.
+ *
+ * Until TBP-Live-Channel-Unification this lived inside `/flags/bootstrap.ts`,
+ * which was misleading: the realtime client, the per-channel auth scoping,
+ * the session.snapshot fanout and the billing-family event dispatch are not
+ * flag-specific. Hoisting them here lets `<BridgeBootstrap />` mount the
+ * runtime once and any capability (flags, billing) attach onto the same
+ * RealtimeClient instance.
+ *
+ * What this module does on `startBridgeRuntime()`:
+ *
+ *   1. Constructs a single `RealtimeClient` using `appId` + `apiBaseUrl` from
+ *      `bridgeConfig.initConfig({...})` (auth's `getConfig()` is the single
+ *      source of truth — no separate API base URL config for flags).
+ *   2. Calls `useBridge().attachToRealtimeClient(realtime)` so the billing
+ *      stores (subscription, quotas, entitlements) react to live pushes.
+ *   3. Wires `setOnOpen` / `setOnClose` to mirror connection state into the
+ *      reactive `realtimeStatus` store.
+ *   4. Wires `setOnSnapshot` to call `applySessionSnapshot(...)` (drives every
+ *      `useBridge()` reactive store) and dispatch the snapshot event through
+ *      `bridgeEvents`.
+ *   5. Wires `setOnUserState` so a server-side claims-change signal forces a
+ *      `refreshTokens()` on BridgeAuth — the fresh JWT then flows back through
+ *      the tokenStore subscription below.
+ *   6. Subscribes to `tokenStore`: identity tracking for the realtime channel
+ *      (setAppId/setWorkspaceId/setUserId), explicit reauthorize on
+ *      token-only refresh, and re-configuration of the `useBridge().quotas`
+ *      HTTP options so quota hydrate requests carry the current access token.
+ *   7. Registers the canonical billing-family event handlers via
+ *      `useBridge().handle({...})` so `subscription.*` / `payment.*` /
+ *      `dunning.*` / `quota.updated` / `entitlements.changed` flow into
+ *      `bridgeEvents._dispatch()`.
+ *   8. Exposes chainable `onBridgeRealtimeOpen` / `onBridgeRealtimeClose` /
+ *      `onBridgeRealtimeSnapshot` subscriber sets so individual capability
+ *      bootstrappers (flag attach, etc.) can layer their own behavior without
+ *      clobbering the core handlers (`setOn*` on RealtimeClient is single-slot).
+ *
+ * `startBridgeRuntime()` is idempotent — repeated calls return the existing
+ * instance. Call `stopBridgeRuntime()` (e.g. on `<BridgeBootstrap />` destroy)
+ * to flush the realtime client and unsubscribe from the token store.
+ */
+import { RealtimeClient, type RealtimeClientConfig, type SessionSnapshotMessage } from '@nebulr-group/bridge-auth-core';
+/**
+ * Advanced runtime overrides. Product consumers never pass these; tests,
+ * Storybook harnesses, and the demo workspace use them to override the
+ * realtime transport (e.g. inject a debug-instrumented WebSocket) or watch
+ * `user.state_changed` signals for visualization.
+ */
+export interface StartBridgeRuntimeOptions {
+    /**
+     * Pass-through realtime overrides. `apiBaseUrl`, `apiKey`, `appId`, and
+     * `getAuthToken` are owned by the runtime and ignored here.
+     */
+    realtime?: Partial<Omit<RealtimeClientConfig, 'apiBaseUrl' | 'apiKey' | 'appId' | 'getAuthToken'>>;
+}
+/**
+ * Start the Bridge runtime. Idempotent — repeated calls are a no-op. Reads
+ * `appId` + `apiBaseUrl` from the auth config store (`bridgeConfig.initConfig`).
+ * Must be called AFTER `bridgeConfig.initConfig({...})` runs — typically from
+ * `<BridgeBootstrap />`'s onMount.
+ */
+export declare function startBridgeRuntime(options?: StartBridgeRuntimeOptions): void;
+/**
+ * Stop the runtime. Idempotent — safe to call without a prior start. Flushes
+ * the realtime client and unsubscribes from the token store. Subscriber sets
+ * are NOT cleared so re-start picks up existing capability extensions.
+ */
+export declare function stopBridgeRuntime(): Promise<void>;
+/**
+ * Get the shared RealtimeClient. Returns `undefined` if `startBridgeRuntime()`
+ * hasn't run yet. Used by capability bootstrappers (e.g. flag attach) to
+ * register their own bridge/cache against the same channel.
+ */
+export declare function getBridgeRealtime(): RealtimeClient | undefined;
+/**
+ * Get the current access token cached for the realtime client's
+ * `getAuthToken` closure. Capability bootstrappers may need it for their own
+ * auth-sensitive operations (e.g. flag hydrate). Returns `undefined` when
+ * the user is logged out.
+ */
+export declare function getCurrentAuthToken(): string | undefined;
+/** Subscribe to realtime `open` events. Returns an unsubscribe fn. */
+export declare function onBridgeRealtimeOpen(handler: () => void): () => void;
+/** Subscribe to realtime `close` events. Returns an unsubscribe fn. */
+export declare function onBridgeRealtimeClose(handler: () => void): () => void;
+/** Subscribe to `session.snapshot` messages. Returns an unsubscribe fn. */
+export declare function onBridgeRealtimeSnapshot(handler: (msg: SessionSnapshotMessage) => void): () => void;
+/**
+ * Subscribe to server-side `user.state_changed` signals (fired before the
+ * runtime triggers a token refresh). Useful for debug overlays + tests.
+ */
+export declare function onBridgeRealtimeUserState(handler: (event: {
+    reason: string;
+}) => void): () => void;
+/**
+ * Test-only — reset module-level state. Use between unit tests to avoid
+ * cross-test bleed in the realtime client + subscriber sets.
+ */
+export declare function __resetBridgeRuntime(): void;

package/dist/core/bridge-runtime.js

@@ -0,0 +1,290 @@
+/**
+ * Bridge core runtime — the realtime + reactive-identity wiring that every
+ * Bridge capability (auth, flags, billing, ...) rides on top of.
+ *
+ * Until TBP-Live-Channel-Unification this lived inside `/flags/bootstrap.ts`,
+ * which was misleading: the realtime client, the per-channel auth scoping,
+ * the session.snapshot fanout and the billing-family event dispatch are not
+ * flag-specific. Hoisting them here lets `<BridgeBootstrap />` mount the
+ * runtime once and any capability (flags, billing) attach onto the same
+ * RealtimeClient instance.
+ *
+ * What this module does on `startBridgeRuntime()`:
+ *
+ *   1. Constructs a single `RealtimeClient` using `appId` + `apiBaseUrl` from
+ *      `bridgeConfig.initConfig({...})` (auth's `getConfig()` is the single
+ *      source of truth — no separate API base URL config for flags).
+ *   2. Calls `useBridge().attachToRealtimeClient(realtime)` so the billing
+ *      stores (subscription, quotas, entitlements) react to live pushes.
+ *   3. Wires `setOnOpen` / `setOnClose` to mirror connection state into the
+ *      reactive `realtimeStatus` store.
+ *   4. Wires `setOnSnapshot` to call `applySessionSnapshot(...)` (drives every
+ *      `useBridge()` reactive store) and dispatch the snapshot event through
+ *      `bridgeEvents`.
+ *   5. Wires `setOnUserState` so a server-side claims-change signal forces a
+ *      `refreshTokens()` on BridgeAuth — the fresh JWT then flows back through
+ *      the tokenStore subscription below.
+ *   6. Subscribes to `tokenStore`: identity tracking for the realtime channel
+ *      (setAppId/setWorkspaceId/setUserId), explicit reauthorize on
+ *      token-only refresh, and re-configuration of the `useBridge().quotas`
+ *      HTTP options so quota hydrate requests carry the current access token.
+ *   7. Registers the canonical billing-family event handlers via
+ *      `useBridge().handle({...})` so `subscription.*` / `payment.*` /
+ *      `dunning.*` / `quota.updated` / `entitlements.changed` flow into
+ *      `bridgeEvents._dispatch()`.
+ *   8. Exposes chainable `onBridgeRealtimeOpen` / `onBridgeRealtimeClose` /
+ *      `onBridgeRealtimeSnapshot` subscriber sets so individual capability
+ *      bootstrappers (flag attach, etc.) can layer their own behavior without
+ *      clobbering the core handlers (`setOn*` on RealtimeClient is single-slot).
+ *
+ * `startBridgeRuntime()` is idempotent — repeated calls return the existing
+ * instance. Call `stopBridgeRuntime()` (e.g. on `<BridgeBootstrap />` destroy)
+ * to flush the realtime client and unsubscribe from the token store.
+ */
+import { RealtimeClient, useBridge, } from '@nebulr-group/bridge-auth-core';
+import { getConfig } from '../client/stores/config.store.js';
+import { getBridgeAuth, tokenStore } from './bridge-instance.js';
+import { applySessionSnapshot } from './snapshot-stores.js';
+import { bridgeEvents } from './events.js';
+import { _setRealtimeStatus } from './realtime-status.js';
+let _realtime;
+let _unsubscribeAuth;
+let _currentAuthToken;
+const _onOpenSubs = new Set();
+const _onCloseSubs = new Set();
+const _onSnapshotSubs = new Set();
+const _onUserStateSubs = new Set();
+/**
+ * Start the Bridge runtime. Idempotent — repeated calls are a no-op. Reads
+ * `appId` + `apiBaseUrl` from the auth config store (`bridgeConfig.initConfig`).
+ * Must be called AFTER `bridgeConfig.initConfig({...})` runs — typically from
+ * `<BridgeBootstrap />`'s onMount.
+ */
+export function startBridgeRuntime(options = {}) {
+    if (_realtime)
+        return;
+    const config = getConfig();
+    // `appId` may come from BridgeAuth's API context if available; falls back
+    // to the value from `getConfig()`. The auth context one is what gets bound
+    // to the per-app channel scope at boot, before any user JWT arrives.
+    let _bootstrapAppId = config.appId;
+    try {
+        _bootstrapAppId = getBridgeAuth().getApiContext().appId ?? config.appId;
+    }
+    catch {
+        // BridgeAuth singleton not constructed yet — fall through with config.appId.
+    }
+    _realtime = new RealtimeClient({
+        ...(options.realtime ?? {}),
+        apiBaseUrl: config.apiBaseUrl ?? 'https://api.thebridge.dev',
+        apiKey: config.appId,
+        appId: _bootstrapAppId,
+        getAuthToken: () => _currentAuthToken,
+    });
+    _realtime.setOnOpen(() => {
+        _setRealtimeStatus('open');
+        for (const fn of _onOpenSubs) {
+            try {
+                fn();
+            }
+            catch { /* subscriber errors swallowed */ }
+        }
+    });
+    _realtime.setOnClose(() => {
+        _setRealtimeStatus('closed');
+        for (const fn of _onCloseSubs) {
+            try {
+                fn();
+            }
+            catch { /* subscriber errors swallowed */ }
+        }
+    });
+    _realtime.setOnSnapshot((msg) => {
+        try {
+            applySessionSnapshot(msg.data);
+        }
+        catch { /* store updates shouldn't throw, defensive */ }
+        bridgeEvents._dispatch(msg);
+        for (const fn of _onSnapshotSubs) {
+            try {
+                fn(msg);
+            }
+            catch { /* subscriber errors swallowed */ }
+        }
+    });
+    // user.state_changed → JWT refresh. The fresh tokens flow back through the
+    // tokenStore subscription below and re-bind channel scopes / re-eval flags.
+    _realtime.setOnUserState(async (msg) => {
+        for (const fn of _onUserStateSubs) {
+            try {
+                fn({ reason: msg.reason });
+            }
+            catch { /* subscriber errors swallowed */ }
+        }
+        try {
+            await getBridgeAuth().refreshTokens();
+        }
+        catch { /* next scheduled refresh will pick it up */ }
+    });
+    // Billing 2.0 US-11 — bind the billing stores to this realtime client so
+    // subscription / quotas / entitlements react to live pushes.
+    useBridge().attachToRealtimeClient(_realtime);
+    // Phase 5 (TBP-331) + TBP-360 — billing-family events flow through the
+    // unified bridge events surface via `useBridge().handle({...})`.
+    useBridge().handle({
+        'subscription.plan_changed': (msg) => bridgeEvents._dispatch(msg),
+        'payment.failed': (msg) => bridgeEvents._dispatch(msg),
+        'payment.succeeded': (msg) => bridgeEvents._dispatch(msg),
+        'subscription.created': (msg) => bridgeEvents._dispatch(msg),
+        'subscription.updated': (msg) => bridgeEvents._dispatch(msg),
+        'subscription.canceled': (msg) => bridgeEvents._dispatch(msg),
+        'subscription.reactivated': (msg) => bridgeEvents._dispatch(msg),
+        'subscription.trial_started': (msg) => bridgeEvents._dispatch(msg),
+        'subscription.trial_ending_soon': (msg) => bridgeEvents._dispatch(msg),
+        'subscription.trial_converted': (msg) => bridgeEvents._dispatch(msg),
+        'subscription.trial_expired': (msg) => bridgeEvents._dispatch(msg),
+        'dunning.entered': (msg) => bridgeEvents._dispatch(msg),
+        'dunning.retry_scheduled': (msg) => bridgeEvents._dispatch(msg),
+        'dunning.recovered': (msg) => bridgeEvents._dispatch(msg),
+        'dunning.exhausted': (msg) => bridgeEvents._dispatch(msg),
+        'quota.updated': (msg) => bridgeEvents._dispatch(msg),
+        'entitlements.changed': (msg) => bridgeEvents._dispatch(msg),
+    });
+    // Token store subscription — owns realtime channel scoping + quotas HTTP
+    // options + reauthorize on token-only refresh. Capability-specific subs
+    // (e.g. flag eval context) are layered on top by their own bootstrappers.
+    const apiBaseUrl = config.apiBaseUrl ?? 'https://api.thebridge.dev';
+    _unsubscribeAuth = tokenStore.subscribe((tokens) => {
+        const prevAuthToken = _currentAuthToken;
+        _currentAuthToken = tokens?.accessToken;
+        // Quota store hydrate requests carry the current access token; configure
+        // here so post-login state is picked up. Best-effort: a missing
+        // BridgeAuth means SDK isn't fully initialized yet — skip.
+        try {
+            const auth = getBridgeAuth();
+            useBridge().quotas.configure({
+                apiBaseUrl,
+                appId: auth.getApiContext().appId,
+                accessToken: tokens?.accessToken ?? null,
+            });
+        }
+        catch {
+            // No BridgeAuth yet — quota hydration falls back to live pushes only.
+        }
+        if (!tokens?.accessToken) {
+            // Logout — drop user + workspace channel scopes. The app channel keeps
+            // its anonymous app-id auth.
+            _realtime.setUserId(undefined);
+            _realtime.setWorkspaceId(undefined);
+            return;
+        }
+        const claims = decodeJwtPayload(tokens.accessToken);
+        if (!claims)
+            return;
+        // Wire all three SDK channel scopes from the JWT. `aid` → app, `tid` →
+        // workspace, `sub` → user. Each setter is idempotent; only changes trigger
+        // a reconnect.
+        _realtime.setAppId(typeof claims.aid === 'string' ? claims.aid : undefined);
+        _realtime.setWorkspaceId(typeof claims.tid === 'string' ? claims.tid : undefined);
+        _realtime.setUserId(typeof claims.sub === 'string' ? claims.sub : undefined);
+        // Token-only refresh (same user, new JWT): setUserId is a no-op when
+        // userId hasn't changed, leaving the channel riding the OLD JWT until
+        // Centrifugo's connection-token TTL drops it. Force a reauthorize so the
+        // server re-validates against the new token immediately.
+        if (prevAuthToken && _currentAuthToken && prevAuthToken !== _currentAuthToken) {
+            void _realtime.reauthorize();
+        }
+    });
+    // Best-effort start. RealtimeClient gracefully no-ops if the workspace's
+    // `/realtime/config` returns `kind: 'noop'`.
+    void _realtime.start();
+}
+/**
+ * Stop the runtime. Idempotent — safe to call without a prior start. Flushes
+ * the realtime client and unsubscribes from the token store. Subscriber sets
+ * are NOT cleared so re-start picks up existing capability extensions.
+ */
+export async function stopBridgeRuntime() {
+    if (_unsubscribeAuth) {
+        _unsubscribeAuth();
+        _unsubscribeAuth = undefined;
+    }
+    if (_realtime) {
+        try {
+            await _realtime.stop();
+        }
+        catch { /* already stopped, ignore */ }
+        _realtime = undefined;
+    }
+    _currentAuthToken = undefined;
+}
+/**
+ * Get the shared RealtimeClient. Returns `undefined` if `startBridgeRuntime()`
+ * hasn't run yet. Used by capability bootstrappers (e.g. flag attach) to
+ * register their own bridge/cache against the same channel.
+ */
+export function getBridgeRealtime() {
+    return _realtime;
+}
+/**
+ * Get the current access token cached for the realtime client's
+ * `getAuthToken` closure. Capability bootstrappers may need it for their own
+ * auth-sensitive operations (e.g. flag hydrate). Returns `undefined` when
+ * the user is logged out.
+ */
+export function getCurrentAuthToken() {
+    return _currentAuthToken;
+}
+/** Subscribe to realtime `open` events. Returns an unsubscribe fn. */
+export function onBridgeRealtimeOpen(handler) {
+    _onOpenSubs.add(handler);
+    return () => _onOpenSubs.delete(handler);
+}
+/** Subscribe to realtime `close` events. Returns an unsubscribe fn. */
+export function onBridgeRealtimeClose(handler) {
+    _onCloseSubs.add(handler);
+    return () => _onCloseSubs.delete(handler);
+}
+/** Subscribe to `session.snapshot` messages. Returns an unsubscribe fn. */
+export function onBridgeRealtimeSnapshot(handler) {
+    _onSnapshotSubs.add(handler);
+    return () => _onSnapshotSubs.delete(handler);
+}
+/**
+ * Subscribe to server-side `user.state_changed` signals (fired before the
+ * runtime triggers a token refresh). Useful for debug overlays + tests.
+ */
+export function onBridgeRealtimeUserState(handler) {
+    _onUserStateSubs.add(handler);
+    return () => _onUserStateSubs.delete(handler);
+}
+/**
+ * Test-only — reset module-level state. Use between unit tests to avoid
+ * cross-test bleed in the realtime client + subscriber sets.
+ */
+export function __resetBridgeRuntime() {
+    _onOpenSubs.clear();
+    _onCloseSubs.clear();
+    _onSnapshotSubs.clear();
+    _onUserStateSubs.clear();
+    _currentAuthToken = undefined;
+    if (_unsubscribeAuth) {
+        _unsubscribeAuth();
+        _unsubscribeAuth = undefined;
+    }
+    _realtime = undefined;
+}
+// ── helpers ─────────────────────────────────────────────────────────────────
+/** Decode a JWT payload without signature verification (client context only). */
+function decodeJwtPayload(token) {
+    try {
+        const part = token.split('.')[1];
+        if (!part)
+            return null;
+        const json = atob(part.replace(/-/g, '+').replace(/_/g, '/'));
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/bridge-runtime.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/bridge-runtime.test.js

@@ -0,0 +1,203 @@
+// Unit tests for the hoisted Bridge core runtime.
+//
+// Covers the contract surface around `startBridgeRuntime` / subscriber sets /
+// `getBridgeRealtime`. Heavy stubbing — auth-core's RealtimeClient + useBridge
+// are mocked so we can drive open/close/snapshot/user-state events and assert
+// they fan out to subscribers + the realtimeStatus store + bridgeEvents.
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { writable, get } from 'svelte/store';
+let _tokenStore;
+// Captured event handlers so tests can fire them.
+let _onOpen;
+let _onClose;
+let _onSnapshot;
+let _onUserState;
+const _channelScopeCalls = [];
+const _reauthCalls = [];
+let _startCalls = 0;
+let _stopCalls = 0;
+let _capturedRealtimeConfig;
+// Reset the spy state between tests.
+function resetSpies() {
+    _onOpen = _onClose = _onSnapshot = _onUserState = undefined;
+    _channelScopeCalls.length = 0;
+    _reauthCalls.length = 0;
+    _startCalls = 0;
+    _stopCalls = 0;
+    _capturedRealtimeConfig = undefined;
+}
+// ── Mocks ──────────────────────────────────────────────────────────────────
+vi.mock('./bridge-instance.js', () => ({
+    get tokenStore() {
+        return _tokenStore;
+    },
+    getBridgeAuth: () => ({
+        getApiContext: () => ({ appId: 'app-1', accessToken: null }),
+        refreshTokens: async () => { },
+    }),
+}));
+vi.mock('../client/stores/config.store.js', () => ({
+    getConfig: () => ({ appId: 'app-1', apiBaseUrl: 'http://test' }),
+}));
+vi.mock('./snapshot-stores.js', () => ({
+    applySessionSnapshot: vi.fn(),
+}));
+vi.mock('./events.js', () => ({
+    bridgeEvents: { _dispatch: vi.fn() },
+}));
+vi.mock('@nebulr-group/bridge-auth-core', () => {
+    class FakeRealtimeClient {
+        constructor(config) {
+            _capturedRealtimeConfig = config;
+        }
+        setOnOpen(fn) { _onOpen = fn; }
+        setOnClose(fn) { _onClose = fn; }
+        setOnSnapshot(fn) { _onSnapshot = fn; }
+        setOnUserState(fn) { _onUserState = fn; }
+        setAppId(v) { _channelScopeCalls.push({ method: 'setAppId', value: v }); }
+        setWorkspaceId(v) { _channelScopeCalls.push({ method: 'setWorkspaceId', value: v }); }
+        setUserId(v) { _channelScopeCalls.push({ method: 'setUserId', value: v }); }
+        async reauthorize() { _reauthCalls.push(Date.now()); }
+        async start() { _startCalls++; }
+        async stop() { _stopCalls++; }
+    }
+    return {
+        RealtimeClient: FakeRealtimeClient,
+        useBridge: () => ({
+            quotas: { configure: vi.fn() },
+            attachToRealtimeClient: vi.fn(),
+            handle: vi.fn(() => () => { }),
+        }),
+    };
+});
+beforeEach(() => {
+    _tokenStore = writable(null);
+    resetSpies();
+});
+afterEach(async () => {
+    const { __resetBridgeRuntime, stopBridgeRuntime } = await import('./bridge-runtime.js');
+    await stopBridgeRuntime();
+    __resetBridgeRuntime();
+});
+// ── Imports under test ─────────────────────────────────────────────────────
+import { startBridgeRuntime, stopBridgeRuntime, getBridgeRealtime, onBridgeRealtimeOpen, onBridgeRealtimeClose, onBridgeRealtimeSnapshot, onBridgeRealtimeUserState, } from './bridge-runtime.js';
+import { realtimeStatus } from './realtime-status.js';
+// ── Helpers ────────────────────────────────────────────────────────────────
+function makeJwt(claims) {
+    const enc = (o) => btoa(JSON.stringify(o)).replace(/=+$/, '').replace(/\+/g, '-').replace(/\//g, '_');
+    return `${enc({ alg: 'HS256', typ: 'JWT' })}.${enc(claims)}.sig`;
+}
+// ── Tests ──────────────────────────────────────────────────────────────────
+describe('startBridgeRuntime', () => {
+    it('is idempotent — repeated calls do not construct a second realtime client', () => {
+        startBridgeRuntime();
+        const first = getBridgeRealtime();
+        startBridgeRuntime();
+        const second = getBridgeRealtime();
+        expect(first).toBe(second);
+        expect(_startCalls).toBe(1);
+    });
+    it('reads apiBaseUrl + appId from getConfig()', () => {
+        startBridgeRuntime();
+        expect(_capturedRealtimeConfig?.apiBaseUrl).toBe('http://test');
+        expect(_capturedRealtimeConfig?.apiKey).toBe('app-1');
+    });
+    it('mirrors connection state into realtimeStatus on open/close', () => {
+        startBridgeRuntime();
+        _onOpen?.();
+        expect(get(realtimeStatus)).toBe('open');
+        _onClose?.();
+        expect(get(realtimeStatus)).toBe('closed');
+    });
+});
+describe('chainable subscriber sets', () => {
+    it('fans out open events to every subscriber', () => {
+        const a = vi.fn();
+        const b = vi.fn();
+        onBridgeRealtimeOpen(a);
+        onBridgeRealtimeOpen(b);
+        startBridgeRuntime();
+        _onOpen?.();
+        expect(a).toHaveBeenCalledTimes(1);
+        expect(b).toHaveBeenCalledTimes(1);
+    });
+    it('unsubscribes cleanly', () => {
+        const a = vi.fn();
+        const unsub = onBridgeRealtimeOpen(a);
+        startBridgeRuntime();
+        unsub();
+        _onOpen?.();
+        expect(a).not.toHaveBeenCalled();
+    });
+    it('isolates subscriber errors — one throwing handler does not block others', () => {
+        const a = vi.fn(() => { throw new Error('boom'); });
+        const b = vi.fn();
+        onBridgeRealtimeOpen(a);
+        onBridgeRealtimeOpen(b);
+        startBridgeRuntime();
+        _onOpen?.();
+        expect(a).toHaveBeenCalled();
+        expect(b).toHaveBeenCalled();
+    });
+    it('dispatches session.snapshot to bridgeEvents + applySessionSnapshot + subscribers', async () => {
+        const { bridgeEvents } = await import('./events.js');
+        const { applySessionSnapshot } = await import('./snapshot-stores.js');
+        const sub = vi.fn();
+        onBridgeRealtimeSnapshot(sub);
+        startBridgeRuntime();
+        _onSnapshot?.({ kind: 'session.snapshot', data: { user: { id: 'u' } } });
+        expect(applySessionSnapshot).toHaveBeenCalledWith({ user: { id: 'u' } });
+        expect(bridgeEvents._dispatch).toHaveBeenCalled();
+        expect(sub).toHaveBeenCalled();
+    });
+    it('forwards user.state_changed events to onBridgeRealtimeUserState subscribers', async () => {
+        const sub = vi.fn();
+        onBridgeRealtimeUserState(sub);
+        startBridgeRuntime();
+        await _onUserState?.({ reason: 'role.changed' });
+        expect(sub).toHaveBeenCalledWith({ reason: 'role.changed' });
+    });
+});
+describe('token store subscription', () => {
+    it('binds channel scopes from JWT claims on login', () => {
+        startBridgeRuntime();
+        // `tokenStore.subscribe` fires immediately with the current value (null)
+        // — that emits a `setUserId(undefined)` first. Clear so we only see the
+        // login emission.
+        _channelScopeCalls.length = 0;
+        _tokenStore.set({ accessToken: makeJwt({ sub: 'user-1', tid: 'tenant-7', aid: 'app-1' }) });
+        const userCall = _channelScopeCalls.find((c) => c.method === 'setUserId');
+        const tenantCall = _channelScopeCalls.find((c) => c.method === 'setWorkspaceId');
+        expect(userCall?.value).toBe('user-1');
+        expect(tenantCall?.value).toBe('tenant-7');
+    });
+    it('clears user + workspace scopes on logout but keeps app scope', () => {
+        startBridgeRuntime();
+        _tokenStore.set({ accessToken: makeJwt({ sub: 'user-1', tid: 'tenant-7' }) });
+        _channelScopeCalls.length = 0;
+        _tokenStore.set(null);
+        expect(_channelScopeCalls).toEqual([
+            { method: 'setUserId', value: undefined },
+            { method: 'setWorkspaceId', value: undefined },
+        ]);
+    });
+    it('reauthorizes on token-only refresh (same user, new JWT)', () => {
+        startBridgeRuntime();
+        _tokenStore.set({ accessToken: makeJwt({ sub: 'user-1' }) });
+        _reauthCalls.length = 0;
+        _tokenStore.set({ accessToken: makeJwt({ sub: 'user-1', iat: 123 }) });
+        expect(_reauthCalls.length).toBe(1);
+    });
+});
+describe('stopBridgeRuntime', () => {
+    it('flushes the realtime client and clears the singleton', async () => {
+        startBridgeRuntime();
+        expect(getBridgeRealtime()).toBeDefined();
+        await stopBridgeRuntime();
+        expect(getBridgeRealtime()).toBeUndefined();
+        expect(_stopCalls).toBe(1);
+    });
+    it('is safe to call without a prior start', async () => {
+        await expect(stopBridgeRuntime()).resolves.not.toThrow();
+    });
+});