@nebulr-group/bridge-svelte 0.7.1 → 0.8.0-beta.0

package/dist/client/BridgeBootstrap.svelte

@@ -20,6 +20,18 @@
     stopBridgeRuntime,
     type StartBridgeRuntimeOptions,
   } from '../core/bridge-runtime.js';
+  import RealtimeDevBadge from './components/developer/RealtimeDevBadge.svelte';
+
+  // TBP-644 — the "Live updates off — why?" badge is mounted here so every app
+  // gets it without code changes. It renders in development builds only;
+  // `devBadge: false` in the config turns it off there too.
+  const devBadgeEnabled = (() => {
+    try {
+      return getConfig().devBadge !== false;
+    } catch {
+      return true;
+    }
+  })();
 
   // Props: optional `runtime` overrides for advanced/debug use (websocketFactory,
   // reconnect overrides, etc.); `onBootstrapComplete` callback fires after the
@@ -194,3 +206,5 @@
     await handleRoute(to.url.pathname, cancel, to.url.search);
   });
 </script>
+
+<RealtimeDevBadge enabled={devBadgeEnabled} />

package/dist/client/components/developer/RealtimeDevBadge.svelte

@@ -0,0 +1,216 @@
+<!--
+  TBP-644 — development-only "Live updates off — why?" corner badge.
+
+  <BridgeBootstrap /> mounts this automatically. It renders only in
+  development builds (`dev` from `$app/environment`, which SvelteKit resolves
+  to a constant `false` in production builds) and only while live updates are
+  actually off: refused (`unauthorized`), connected but deaf (`degraded`), or
+  retrying for longer than 30 s. Opt out with `devBadge: false` in
+  `bridgeConfig.initConfig({...})`.
+
+  Styling is self-contained — every element resets with `all: unset` — so it
+  neither depends on nor inherits from the host app's CSS.
+-->
+<script lang="ts">
+  import { dev } from '$app/environment';
+  import { realtimeStatusDetail } from '../../../core/realtime-status.js';
+  import {
+    REALTIME_BADGE_RETRYING_AFTER_MS,
+    createRetryClock,
+    realtimeBadgeView,
+  } from '../../../core/realtime-dev-badge.js';
+
+  let { enabled = true }: { enabled?: boolean } = $props();
+
+  const PANEL_ID = 'bridge-realtime-dev-badge-panel';
+  const retryClock = createRetryClock();
+
+  let now = $state(Date.now());
+  let expanded = $state(false);
+  let dismissedKey = $state<string | undefined>(undefined);
+  let toggleEl = $state<HTMLButtonElement | undefined>(undefined);
+
+  const status = $derived($realtimeStatusDetail);
+  // Start of the current retry run — stable across the closed/connecting
+  // flips inside one episode (see createRetryClock).
+  const retryingSince = $derived(retryClock(status, Date.now()));
+
+  // Tick `now` once the retrying threshold passes — nothing else re-renders.
+  $effect(() => {
+    if (retryingSince === undefined) return;
+    const remaining = retryingSince + REALTIME_BADGE_RETRYING_AFTER_MS - Date.now();
+    const timer = setTimeout(() => (now = Date.now()), Math.max(0, remaining) + 50);
+    return () => clearTimeout(timer);
+  });
+
+  const view = $derived(realtimeBadgeView(status, retryingSince, now));
+  const visible = $derived(!!view && view.key !== dismissedKey);
+
+  function dismiss() {
+    dismissedKey = view?.key;
+    expanded = false;
+  }
+
+  function onKeydown(event: KeyboardEvent) {
+    if (event.key === 'Escape' && expanded) {
+      expanded = false;
+      toggleEl?.focus();
+    }
+  }
+</script>
+
+{#if dev && enabled}
+  <div class="bridge-rt-root" data-testid="bridge-realtime-dev-badge-root">
+    <span class="bridge-rt-sr" role="status" aria-live="polite"
+      >{visible && view ? `Bridge live updates are off: ${view.reason}` : ''}</span
+    >
+    {#if visible && view}
+      <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+      <aside
+        class="bridge-rt-badge"
+        aria-label="Bridge live updates (development only)"
+        data-testid="bridge-realtime-dev-badge"
+        onkeydown={onKeydown}
+      >
+        <div class="bridge-rt-bar">
+          <button
+            bind:this={toggleEl}
+            type="button"
+            class="bridge-rt-toggle"
+            aria-expanded={expanded}
+            aria-controls={PANEL_ID}
+            onclick={() => (expanded = !expanded)}
+          >
+            <span class="bridge-rt-dot" aria-hidden="true">●</span> Live updates off — why?
+          </button>
+          <button
+            type="button"
+            class="bridge-rt-close"
+            aria-label="Dismiss the live updates notice"
+            onclick={dismiss}>×</button
+          >
+        </div>
+        {#if expanded}
+          <div id={PANEL_ID} class="bridge-rt-panel">
+            <div class="bridge-rt-row">
+              <span class="bridge-rt-label">Reason</span>
+              <code class="bridge-rt-code">{view.reason}</code>
+            </div>
+            <div class="bridge-rt-row">
+              <span class="bridge-rt-label">Whose side</span>
+              <span class="bridge-rt-value">{view.sideLabel}</span>
+            </div>
+            {#if view.ref}
+              <div class="bridge-rt-row">
+                <span class="bridge-rt-label">Ref</span>
+                <code class="bridge-rt-code">{view.ref}</code>
+              </div>
+            {/if}
+            {#if view.docsUrl}
+              <a class="bridge-rt-link" href={view.docsUrl} target="_blank" rel="noopener noreferrer"
+                >How to fix this ↗</a
+              >
+            {/if}
+            <span class="bridge-rt-note">Development builds only — never shown to your users.</span>
+          </div>
+        {/if}
+      </aside>
+    {/if}
+  </div>
+{/if}
+
+<style>
+  .bridge-rt-root,
+  .bridge-rt-root * {
+    all: unset;
+    box-sizing: border-box;
+  }
+  .bridge-rt-root {
+    position: fixed;
+    right: 16px;
+    bottom: 16px;
+    z-index: 2147483000;
+    display: block;
+    font-family: ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+    font-size: 12px;
+    line-height: 1.4;
+    color: #f5f5f5;
+  }
+  .bridge-rt-sr {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip: rect(0 0 0 0);
+    white-space: nowrap;
+  }
+  .bridge-rt-badge {
+    display: block;
+    max-width: min(360px, calc(100vw - 32px));
+    background: #1f2328;
+    border: 1px solid #3d444d;
+    border-radius: 8px;
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.25);
+  }
+  .bridge-rt-bar {
+    display: flex;
+    align-items: center;
+  }
+  .bridge-rt-toggle,
+  .bridge-rt-close {
+    cursor: pointer;
+    padding: 6px 10px;
+    border-radius: 8px;
+  }
+  .bridge-rt-toggle {
+    flex: 1;
+  }
+  .bridge-rt-close {
+    font-size: 14px;
+    line-height: 1;
+    color: #b0b8c1;
+  }
+  .bridge-rt-toggle:focus-visible,
+  .bridge-rt-close:focus-visible,
+  .bridge-rt-link:focus-visible {
+    outline: 2px solid #58a6ff;
+    outline-offset: 1px;
+  }
+  .bridge-rt-dot {
+    color: #f85149;
+  }
+  .bridge-rt-panel {
+    display: block;
+    padding: 4px 10px 10px;
+    border-top: 1px solid #3d444d;
+  }
+  .bridge-rt-row {
+    display: flex;
+    gap: 8px;
+    padding-top: 6px;
+  }
+  .bridge-rt-label {
+    flex: 0 0 72px;
+    color: #9198a1;
+  }
+  .bridge-rt-value {
+    flex: 1;
+  }
+  .bridge-rt-code {
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    overflow-wrap: anywhere;
+  }
+  .bridge-rt-link {
+    display: inline-block;
+    margin-top: 8px;
+    color: #58a6ff;
+    text-decoration: underline;
+    cursor: pointer;
+  }
+  .bridge-rt-note {
+    display: block;
+    margin-top: 8px;
+    color: #9198a1;
+    font-size: 11px;
+  }
+</style>

package/dist/client/components/developer/RealtimeDevBadge.svelte.d.ts

@@ -0,0 +1,6 @@
+type $$ComponentProps = {
+    enabled?: boolean;
+};
+declare const RealtimeDevBadge: import("svelte").Component<$$ComponentProps, {}, "">;
+type RealtimeDevBadge = ReturnType<typeof RealtimeDevBadge>;
+export default RealtimeDevBadge;

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

@@ -41,7 +41,7 @@
  * instance. Call `stopBridgeRuntime()` (e.g. on `<BridgeBootstrap />` destroy)
  * to flush the realtime client and unsubscribe from the token store.
  */
-import { RealtimeClient, type FlagChange, type RealtimeClientConfig, type SessionSnapshotMessage } from '@nebulr-group/bridge-auth-core';
+import { RealtimeClient, type FlagChange, type RealtimeClientConfig, type RealtimeStatus, 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
@@ -105,6 +105,14 @@ export declare function onBridgeRealtimeClose(handler: () => void): () => void;
 export declare function onBridgeFlagChange(handler: (change: FlagChange) => void): () => void;
 /** Subscribe to `session.snapshot` messages. Returns an unsubscribe fn. */
 export declare function onBridgeRealtimeSnapshot(handler: (msg: SessionSnapshotMessage) => void): () => void;
+/**
+ * Subscribe to realtime status changes (TBP-644): state, the machine-readable
+ * reason, whose side a fault is on (`app` / `config` / `bridge` / `network`),
+ * whether the client is still retrying, a docs link and a support ref.
+ * Fires on every change, not with the current value — read
+ * `realtimeStatusDetail` for that. Returns an unsubscribe fn.
+ */
+export declare function onBridgeRealtimeStatus(handler: (status: RealtimeStatus) => void): () => void;
 /**
  * Subscribe to server-side `user.state_changed` signals (fired before the
  * runtime triggers a token refresh). Useful for debug overlays + tests.

package/dist/core/bridge-runtime.js

@@ -47,7 +47,7 @@ import { getBridgeAuth, tokenStore } from './bridge-instance.js';
 import { wrapFetchWithBridgeAuth } from './bridge-fetch.js';
 import { applySessionSnapshot } from './snapshot-stores.js';
 import { bridgeEvents } from './events.js';
-import { _setRealtimeStatus } from './realtime-status.js';
+import { _setRealtimeStatus, _setRealtimeStatusDetail } from './realtime-status.js';
 let _realtime;
 let _unsubscribeAuth;
 let _currentAuthToken;
@@ -59,6 +59,8 @@ const _onSnapshotSubs = new Set();
 // invalidate its (separate) cache and re-evaluate the current route.
 const _onFlagChangeSubs = new Set();
 const _onUserStateSubs = new Set();
+// TBP-644 — full realtime status (state + reason + whose side + retrying).
+const _onStatusSubs = new Set();
 /**
  * Start the Bridge runtime. Idempotent — repeated calls are a no-op. Reads
  * `appId` + `apiBaseUrl` from the auth config store (`bridgeConfig.initConfig`).
@@ -105,6 +107,25 @@ export function startBridgeRuntime(options = {}) {
         apiKey: config.appId,
         appId: _bootstrapAppId,
         getAuthToken: () => _currentAuthToken,
+        // TBP-644 — a refused connection gets ONE session refresh per episode
+        // (auth-core enforces the once) and reconnects with the new token instead
+        // of parking. A signed-out session has nothing to refresh. Loop safety:
+        // the refreshed token lands in the tokenStore subscription below, whose
+        // reauthorize() is a no-op while that episode is still connecting, and
+        // the reconnect it produces is flagged self-induced so setOnOpen does not
+        // refresh a second time.
+        refreshAuthToken: options.realtime?.refreshAuthToken ??
+            (async () => {
+                if (!_currentAuthToken)
+                    return undefined;
+                try {
+                    const tokens = await getBridgeAuth().refreshTokens();
+                    return tokens?.accessToken ?? undefined;
+                }
+                catch {
+                    return undefined;
+                }
+            }),
     });
     let _connectedOnce = false;
     // Set just before we call _realtime.reauthorize() so the resulting
@@ -159,6 +180,23 @@ export function startBridgeRuntime(options = {}) {
     _realtime.setOnDegraded?.(() => {
         _setRealtimeStatus('degraded');
     });
+    // TBP-644 — the full status: why the connection is not working, whose side
+    // the fault is on, and whether it is still retrying. Guarded for the same
+    // reason as setOnDegraded (an older auth-core has no such hook; the
+    // open/close/degraded mirrors above keep `realtimeStatus` working there).
+    _realtime.setOnStatusChange?.((status) => {
+        _setRealtimeStatusDetail(status);
+        // A parked client never opens, so a reauthorize that ended in a refusal
+        // must not leave the self-induced flag set for the next genuine reconnect.
+        if (status.state === 'unauthorized')
+            _reauthInFlight = false;
+        for (const fn of _onStatusSubs) {
+            try {
+                fn(status);
+            }
+            catch { /* subscriber errors swallowed */ }
+        }
+    });
     // TBP-575 — a flag changed on the wire. Two caches need to hear about it and
     // only one of them was ever told:
     //   - BridgeFlags (FF 2.0)      — driven by realtime already, via attach()
@@ -232,9 +270,24 @@ export function startBridgeRuntime(options = {}) {
     // 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';
+    // TBP-644 — the realtime connection must be re-authorized whenever the
+    // token VALUE changes: rotation (A → B), but also first sign-in
+    // (none → A) and sign-out (A → none). Keying this on rotation only meant a
+    // session that signed in after page load kept the anonymous connection —
+    // or stayed parked after a refusal — until something else reconnected it.
+    // Flagged self-induced so setOnOpen skips its catch-up refresh (see the
+    // loop note there): the token we reconnect with is already current.
+    const reauthorizeForTokenChange = () => {
+        _reauthInFlight = true;
+        void _realtime.reauthorize();
+    };
+    // `subscribe` emits the current value synchronously, before `start()` below.
+    // That first emission is not a change: start() connects with it anyway.
+    let _tokenSubscriptionLive = false;
     _unsubscribeAuth = tokenStore.subscribe((tokens) => {
         const prevAuthToken = _currentAuthToken;
-        _currentAuthToken = tokens?.accessToken;
+        _currentAuthToken = tokens?.accessToken ?? undefined;
+        const tokenChanged = _tokenSubscriptionLive && prevAuthToken !== _currentAuthToken;
         // 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.
@@ -254,29 +307,28 @@ export function startBridgeRuntime(options = {}) {
             // its anonymous app-id auth.
             _realtime.setUserId(undefined);
             _realtime.setWorkspaceId(undefined);
+            // Reconnect as the signed-out session now, rather than riding the old
+            // user's socket until something else drops it.
+            if (tokenChanged)
+                reauthorizeForTokenChange();
             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) {
-            // Flag this as a self-induced reconnect so setOnOpen does NOT fire its
-            // proactive refresh (which would mint a new token → land back here →
-            // loop forever). The token we're reauthorizing with is already current.
-            _reauthInFlight = true;
-            void _realtime.reauthorize();
+        if (claims) {
+            // 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);
         }
+        // setUserId is a no-op when the user is unchanged (token-only refresh),
+        // and a setter-driven reconnect waits out a backoff and cannot lift a
+        // parked refusal — so reauthorize explicitly on every value change.
+        if (tokenChanged)
+            reauthorizeForTokenChange();
     });
+    _tokenSubscriptionLive = true;
     // Best-effort start. RealtimeClient gracefully no-ops if the workspace's
     // `/realtime/config` returns `kind: 'noop'`.
     void _realtime.start();
@@ -346,6 +398,17 @@ export function onBridgeRealtimeSnapshot(handler) {
     _onSnapshotSubs.add(handler);
     return () => _onSnapshotSubs.delete(handler);
 }
+/**
+ * Subscribe to realtime status changes (TBP-644): state, the machine-readable
+ * reason, whose side a fault is on (`app` / `config` / `bridge` / `network`),
+ * whether the client is still retrying, a docs link and a support ref.
+ * Fires on every change, not with the current value — read
+ * `realtimeStatusDetail` for that. Returns an unsubscribe fn.
+ */
+export function onBridgeRealtimeStatus(handler) {
+    _onStatusSubs.add(handler);
+    return () => _onStatusSubs.delete(handler);
+}
 /**
  * Subscribe to server-side `user.state_changed` signals (fired before the
  * runtime triggers a token refresh). Useful for debug overlays + tests.
@@ -364,6 +427,7 @@ export function __resetBridgeRuntime() {
     _onSnapshotSubs.clear();
     _onFlagChangeSubs.clear();
     _onUserStateSubs.clear();
+    _onStatusSubs.clear();
     _currentAuthToken = undefined;
     if (_unsubscribeAuth) {
         _unsubscribeAuth();

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

@@ -15,6 +15,10 @@ let _onDegraded;
 let _invalidateCalls = 0;
 let _onFlagChange;
 let _onUserState;
+let _onStatusChange;
+let _refreshCalls = 0;
+let _refreshImpl;
+let _refreshThrows = false;
 const _channelScopeCalls = [];
 const _reauthCalls = [];
 let _startCalls = 0;
@@ -31,6 +35,10 @@ function resetSpies() {
     _startCalls = 0;
     _stopCalls = 0;
     _capturedRealtimeConfig = undefined;
+    _onStatusChange = undefined;
+    _refreshCalls = 0;
+    _refreshImpl = undefined;
+    _refreshThrows = false;
 }
 // ── Mocks ──────────────────────────────────────────────────────────────────
 vi.mock('./bridge-instance.js', () => ({
@@ -39,7 +47,12 @@ vi.mock('./bridge-instance.js', () => ({
     },
     getBridgeAuth: () => ({
         getApiContext: () => ({ appId: 'app-1', accessToken: null }),
-        refreshTokens: async () => { },
+        refreshTokens: async () => {
+            _refreshCalls += 1;
+            if (_refreshThrows)
+                throw new Error('refresh failed');
+            return _refreshImpl ? _refreshImpl() : null;
+        },
         invalidateFeatureFlagCache: () => { _invalidateCalls += 1; },
     }),
 }));
@@ -63,6 +76,7 @@ vi.mock('@nebulr-group/bridge-auth-core', () => {
         setOnDegraded(fn) { _onDegraded = fn; }
         setOnFlagChange(fn) { _onFlagChange = fn; }
         setOnUserState(fn) { _onUserState = fn; }
+        setOnStatusChange(fn) { _onStatusChange = 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 }); }
@@ -89,8 +103,8 @@ afterEach(async () => {
     __resetBridgeRuntime();
 });
 // ── Imports under test ─────────────────────────────────────────────────────
-import { startBridgeRuntime, stopBridgeRuntime, getBridgeRealtime, onBridgeRealtimeOpen, onBridgeRealtimeClose, onBridgeRealtimeSnapshot, onBridgeRealtimeUserState, onBridgeFlagChange, } from './bridge-runtime.js';
-import { realtimeStatus } from './realtime-status.js';
+import { startBridgeRuntime, stopBridgeRuntime, getBridgeRealtime, onBridgeRealtimeOpen, onBridgeRealtimeClose, onBridgeRealtimeSnapshot, onBridgeRealtimeUserState, onBridgeFlagChange, onBridgeRealtimeStatus, } from './bridge-runtime.js';
+import { realtimeStatus, realtimeStatusDetail } from './realtime-status.js';
 // ── Helpers ────────────────────────────────────────────────────────────────
 function makeJwt(claims) {
     const enc = (o) => btoa(JSON.stringify(o)).replace(/=+$/, '').replace(/\+/g, '-').replace(/\//g, '_');
@@ -266,3 +280,166 @@ describe('degraded realtime is reported as degraded, not open (TBP-575)', () =>
         expect(get(realtimeStatus)).toBe('degraded');
     });
 });
+// ─────────────────────────────────────────────────────────────────────────────
+// TBP-644 — the runtime only reauthorized on token ROTATION (A → B). A session
+// that signed in after page load (none → A) kept the anonymous connection, and
+// a client parked after a refusal stayed parked, until something else happened
+// to reconnect it.
+// ─────────────────────────────────────────────────────────────────────────────
+const flush = async () => {
+    for (let i = 0; i < 10; i++)
+        await Promise.resolve();
+};
+describe('reauthorizes on every token value change (TBP-644)', () => {
+    it('reauthorizes on first sign-in (no token → token)', () => {
+        startBridgeRuntime();
+        expect(_reauthCalls.length).toBe(0);
+        _tokenStore.set({ accessToken: makeJwt({ sub: 'user-1' }) });
+        expect(_reauthCalls.length).toBe(1);
+    });
+    it('reauthorizes on sign-out (token → no token)', () => {
+        startBridgeRuntime();
+        _tokenStore.set({ accessToken: makeJwt({ sub: 'user-1' }) });
+        _reauthCalls.length = 0;
+        _tokenStore.set(null);
+        expect(_reauthCalls.length).toBe(1);
+    });
+    it('does not reauthorize for the value already present at start — start() connects with it', () => {
+        _tokenStore.set({ accessToken: makeJwt({ sub: 'user-1' }) });
+        startBridgeRuntime();
+        expect(_reauthCalls.length).toBe(0);
+        expect(_startCalls).toBe(1);
+    });
+    it('does not reauthorize when the same token is emitted again', () => {
+        startBridgeRuntime();
+        const token = makeJwt({ sub: 'user-1' });
+        _tokenStore.set({ accessToken: token });
+        _reauthCalls.length = 0;
+        _tokenStore.set({ accessToken: token });
+        expect(_reauthCalls.length).toBe(0);
+    });
+    it('does not treat null → null (signed out, re-emitted) as a change', () => {
+        startBridgeRuntime();
+        _tokenStore.set({ accessToken: null });
+        _tokenStore.set(null);
+        expect(_reauthCalls.length).toBe(0);
+    });
+});
+describe('the self-induced refresh loop guard still holds (TBP-644)', () => {
+    it('the reconnect caused by a sign-in reauthorize does not fire the on-open refresh', () => {
+        startBridgeRuntime();
+        _onOpen?.(); // initial, anonymous connect
+        _tokenStore.set({ accessToken: makeJwt({ sub: 'user-1' }) }); // → reauthorize
+        _onOpen?.(); // the reconnect that reauthorize caused
+        expect(_refreshCalls).toBe(0);
+    });
+    it('a genuine reconnect still refreshes (catch-up for a missed user.state_changed)', () => {
+        startBridgeRuntime();
+        _onOpen?.();
+        _onOpen?.();
+        expect(_refreshCalls).toBe(1);
+    });
+    it('refresh → new token → reauthorize → open stops there instead of refreshing again', async () => {
+        startBridgeRuntime();
+        _tokenStore.set({ accessToken: makeJwt({ sub: 'user-1', iat: 1 }) });
+        _onOpen?.();
+        _refreshImpl = () => {
+            const t = { accessToken: makeJwt({ sub: 'user-1', iat: 2 }) };
+            _tokenStore.set(t);
+            return t;
+        };
+        _onOpen?.(); // genuine reconnect → catch-up refresh → token change → reauthorize
+        await flush();
+        expect(_refreshCalls).toBe(1);
+        _onOpen?.(); // the reauthorize's reconnect
+        await flush();
+        expect(_refreshCalls).toBe(1);
+    });
+});
+describe('refreshAuthToken is wired into the realtime client (TBP-644)', () => {
+    const refreshHook = () => _capturedRealtimeConfig.refreshAuthToken;
+    it('resolves to the NEW access token from BridgeAuth.refreshTokens()', async () => {
+        startBridgeRuntime();
+        _tokenStore.set({ accessToken: makeJwt({ sub: 'user-1', iat: 1 }) });
+        const fresh = makeJwt({ sub: 'user-1', iat: 2 });
+        _refreshImpl = () => {
+            _tokenStore.set({ accessToken: fresh });
+            return { accessToken: fresh };
+        };
+        await expect(refreshHook()()).resolves.toBe(fresh);
+        expect(_refreshCalls).toBe(1);
+    });
+    it('a signed-out session has nothing to refresh — resolves undefined without calling refresh', async () => {
+        startBridgeRuntime();
+        await expect(refreshHook()()).resolves.toBeUndefined();
+        expect(_refreshCalls).toBe(0);
+    });
+    it('a failed refresh resolves undefined instead of throwing', async () => {
+        startBridgeRuntime();
+        _tokenStore.set({ accessToken: makeJwt({ sub: 'user-1' }) });
+        _refreshThrows = true;
+        await expect(refreshHook()()).resolves.toBeUndefined();
+    });
+    it('the reconnect after a refreshAuthToken-driven token change does not refresh a second time', async () => {
+        startBridgeRuntime();
+        _tokenStore.set({ accessToken: makeJwt({ sub: 'user-1', iat: 1 }) });
+        _onOpen?.();
+        _refreshImpl = () => {
+            const t = { accessToken: makeJwt({ sub: 'user-1', iat: 2 }) };
+            _tokenStore.set(t);
+            return t;
+        };
+        await refreshHook()(); // realtime asked for it after a refusal
+        _onOpen?.(); // reconnect with the refreshed token
+        await flush();
+        expect(_refreshCalls).toBe(1);
+    });
+    it('an app-supplied refreshAuthToken override wins', () => {
+        const own = async () => 'own-token';
+        startBridgeRuntime({ realtime: { refreshAuthToken: own } });
+        expect(_capturedRealtimeConfig.refreshAuthToken).toBe(own);
+    });
+});
+describe('full realtime status reaches the public API (TBP-644)', () => {
+    const unauthorized = {
+        state: 'unauthorized',
+        reason: 'expired',
+        side: 'app',
+        retrying: false,
+        docsUrl: 'https://thebridge.dev/docs/live-updates/troubleshooting/#expired',
+        ref: 'abcd1234',
+        since: 1,
+    };
+    it('propagates to realtimeStatusDetail, realtimeStatus and onBridgeRealtimeStatus', () => {
+        const seen = [];
+        onBridgeRealtimeStatus((s) => seen.push(s));
+        startBridgeRuntime();
+        _onStatusChange?.(unauthorized);
+        expect(get(realtimeStatusDetail)).toEqual(unauthorized);
+        expect(get(realtimeStatus)).toBe('unauthorized');
+        expect(seen).toEqual([unauthorized]);
+    });
+    it('a later open/close mirror does not clobber the detail of the same state', () => {
+        startBridgeRuntime();
+        const closing = { state: 'closed', reason: 'connection_lost', side: 'network', retrying: true, ref: 'r1', since: 2 };
+        _onStatusChange?.(closing);
+        _onClose?.();
+        expect(get(realtimeStatusDetail)).toEqual(closing);
+    });
+    it('a parked (unauthorized) client clears the self-induced flag so the next genuine reconnect refreshes', () => {
+        startBridgeRuntime();
+        _onOpen?.();
+        _tokenStore.set({ accessToken: makeJwt({ sub: 'user-1' }) }); // reauthorize → flag set
+        _onStatusChange?.(unauthorized); // …but it was refused and parked
+        _onOpen?.(); // a later, genuine reconnect
+        expect(_refreshCalls).toBe(1);
+    });
+    it('unsubscribes cleanly', () => {
+        const handler = vi.fn();
+        const off = onBridgeRealtimeStatus(handler);
+        startBridgeRuntime();
+        off();
+        _onStatusChange?.(unauthorized);
+        expect(handler).not.toHaveBeenCalled();
+    });
+});

package/dist/core/realtime-dev-badge.d.ts

@@ -0,0 +1,29 @@
+import type { RealtimeStatus } from '@nebulr-group/bridge-auth-core';
+/** A connection still retrying after this long is worth telling the developer about. */
+export declare const REALTIME_BADGE_RETRYING_AFTER_MS = 30000;
+export interface RealtimeBadgeView {
+    /** Machine-readable reason — also the docs anchor. */
+    reason: string;
+    /** Plain-language owner of the fault. */
+    sideLabel: string;
+    docsUrl?: string;
+    ref?: string;
+    /**
+     * Identity of this run of trouble. Dismissing hides the badge until the key
+     * changes, so a NEW problem shows again but the same one does not nag.
+     */
+    key: string;
+}
+/**
+ * Tracks when the current retrying run started. `RealtimeStatus.since` resets
+ * on every state flip (closed ↔ connecting), so it cannot measure how long a
+ * retry loop has lasted; the episode `ref` stays constant for the whole run.
+ */
+export declare function createRetryClock(): (status: RealtimeStatus, now: number) => number | undefined;
+/**
+ * What the badge should say, or null when live updates are fine. Shown while
+ * the client has given up (`unauthorized`), is connected but deaf
+ * (`degraded`), or has been retrying for longer than
+ * {@link REALTIME_BADGE_RETRYING_AFTER_MS}.
+ */
+export declare function realtimeBadgeView(status: RealtimeStatus, retryingSince: number | undefined, now: number): RealtimeBadgeView | null;

package/dist/core/realtime-dev-badge.js

@@ -0,0 +1,66 @@
+// TBP-644 — decision logic for the development-only "Live updates off — why?"
+// badge. Kept framework-free so it is unit-testable without rendering and so
+// the component stays a thin view over it.
+/** A connection still retrying after this long is worth telling the developer about. */
+export const REALTIME_BADGE_RETRYING_AFTER_MS = 30_000;
+/**
+ * Used when a status carries a reason but no docs link (e.g. `degraded`).
+ * Mirrors auth-core's REALTIME_DOCS_BASE_URL — not imported, so a consumer on
+ * an auth-core that predates it does not fail to build.
+ */
+const DOCS_BASE_URL = 'https://thebridge.dev/docs/live-updates/troubleshooting/';
+const SIDE_LABELS = {
+    app: "Your app — the session / token it hands to Bridge",
+    config: "Your Bridge settings — apiBaseUrl or appId don't match the session",
+    bridge: 'Bridge — nothing to change in your app',
+    network: 'The network — retrying automatically',
+};
+function sideLabel(status) {
+    if (status.side)
+        return SIDE_LABELS[status.side];
+    if (status.state === 'degraded')
+        return 'Channel access — connected, but Bridge accepted no channel';
+    return 'Unknown';
+}
+/**
+ * Tracks when the current retrying run started. `RealtimeStatus.since` resets
+ * on every state flip (closed ↔ connecting), so it cannot measure how long a
+ * retry loop has lasted; the episode `ref` stays constant for the whole run.
+ */
+export function createRetryClock() {
+    let ref;
+    let since;
+    return (status, now) => {
+        if (!status.retrying) {
+            ref = undefined;
+            since = undefined;
+            return undefined;
+        }
+        const key = status.ref ?? '';
+        if (since === undefined || key !== ref) {
+            ref = key;
+            since = now;
+        }
+        return since;
+    };
+}
+/**
+ * What the badge should say, or null when live updates are fine. Shown while
+ * the client has given up (`unauthorized`), is connected but deaf
+ * (`degraded`), or has been retrying for longer than
+ * {@link REALTIME_BADGE_RETRYING_AFTER_MS}.
+ */
+export function realtimeBadgeView(status, retryingSince, now) {
+    const stuck = status.state === 'unauthorized' || status.state === 'degraded';
+    const retryingTooLong = status.retrying && retryingSince !== undefined && now - retryingSince >= REALTIME_BADGE_RETRYING_AFTER_MS;
+    if (!stuck && !retryingTooLong)
+        return null;
+    const reason = status.reason ?? status.state;
+    return {
+        reason,
+        sideLabel: sideLabel(status),
+        docsUrl: status.docsUrl ?? (status.reason ? `${DOCS_BASE_URL}#${status.reason}` : undefined),
+        ref: status.ref,
+        key: `${stuck ? status.state : 'retrying'}|${reason}|${status.ref ?? ''}`,
+    };
+}

package/dist/core/realtime-dev-badge.test.d.ts

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

package/dist/core/realtime-dev-badge.test.js

@@ -0,0 +1,145 @@
+// TBP-644 — the development-only "Live updates off — why?" badge.
+//
+// Rendered with `svelte/server`: the vitest environment has no DOM, and what
+// matters most here — does it render at all, in which build, with which
+// config — is fully visible in the server-rendered HTML.
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { readable } from 'svelte/store';
+import { REALTIME_BADGE_RETRYING_AFTER_MS, createRetryClock, realtimeBadgeView, } from './realtime-dev-badge.js';
+const unauthorized = {
+    state: 'unauthorized',
+    reason: 'wrong_environment',
+    side: 'config',
+    retrying: false,
+    docsUrl: 'https://thebridge.dev/docs/live-updates/troubleshooting/#wrong_environment',
+    ref: '0badf00d',
+    since: 1,
+};
+const degraded = { state: 'degraded', reason: 'no_channel_accepted', retrying: false, since: 1 };
+const open = { state: 'open', retrying: false, since: 1 };
+const retrying = {
+    state: 'connecting',
+    reason: 'connection_lost',
+    side: 'network',
+    retrying: true,
+    ref: 'r1',
+    since: 1,
+};
+describe('realtimeBadgeView', () => {
+    it('shows for unauthorized, with reason, whose side, docs link and ref', () => {
+        const view = realtimeBadgeView(unauthorized, undefined, 0);
+        expect(view).toMatchObject({
+            reason: 'wrong_environment',
+            docsUrl: unauthorized.docsUrl,
+            ref: '0badf00d',
+        });
+        expect(view?.sideLabel).toMatch(/Bridge settings/);
+    });
+    it('shows for degraded and builds the docs link from the reason', () => {
+        expect(realtimeBadgeView(degraded, undefined, 0)).toMatchObject({
+            reason: 'no_channel_accepted',
+            docsUrl: 'https://thebridge.dev/docs/live-updates/troubleshooting/#no_channel_accepted',
+        });
+    });
+    it('stays hidden while open', () => {
+        expect(realtimeBadgeView(open, undefined, 0)).toBeNull();
+    });
+    it('stays hidden while retrying for less than 30 s, and shows after', () => {
+        expect(realtimeBadgeView(retrying, 0, REALTIME_BADGE_RETRYING_AFTER_MS - 1)).toBeNull();
+        expect(realtimeBadgeView(retrying, 0, REALTIME_BADGE_RETRYING_AFTER_MS)).toMatchObject({
+            reason: 'connection_lost',
+            sideLabel: expect.stringMatching(/network/i),
+        });
+    });
+    it('keys a retry run by its ref, not by the closed/connecting flips inside it', () => {
+        const a = realtimeBadgeView({ ...retrying, state: 'closed' }, 0, 60_000);
+        const b = realtimeBadgeView({ ...retrying, state: 'connecting' }, 0, 60_000);
+        expect(a?.key).toBe(b?.key);
+        expect(realtimeBadgeView({ ...retrying, ref: 'r2' }, 0, 60_000)?.key).not.toBe(a?.key);
+    });
+});
+describe('createRetryClock', () => {
+    it('measures a retry run from its first status, across state flips, and resets on recovery', () => {
+        const clock = createRetryClock();
+        expect(clock(retrying, 100)).toBe(100);
+        expect(clock({ ...retrying, state: 'closed' }, 5_000)).toBe(100);
+        expect(clock({ ...retrying, ref: 'r2' }, 9_000)).toBe(9_000); // a new episode
+        expect(clock(open, 10_000)).toBeUndefined();
+        expect(clock(retrying, 11_000)).toBe(11_000);
+    });
+});
+// ── Rendering ───────────────────────────────────────────────────────────────
+async function renderBadge(opts) {
+    vi.resetModules();
+    vi.doMock('$app/environment', () => ({ dev: opts.dev, browser: false, building: false, version: 'test' }));
+    const { _setRealtimeStatusDetail } = await import('./realtime-status.js');
+    if (opts.status)
+        _setRealtimeStatusDetail(opts.status);
+    const { default: Badge } = await import('../client/components/developer/RealtimeDevBadge.svelte');
+    const { render } = await import('svelte/server');
+    return render(Badge, { props: opts.enabled === undefined ? {} : { enabled: opts.enabled } }).body;
+}
+afterEach(() => {
+    vi.doUnmock('$app/environment');
+    vi.doUnmock('$app/navigation');
+    vi.doUnmock('$app/stores');
+    vi.doUnmock('../auth/route-guard.js');
+    vi.doUnmock('../client/stores/config.store.js');
+});
+describe('<RealtimeDevBadge>', () => {
+    it('renders in a development build while live updates are off', async () => {
+        const html = await renderBadge({ dev: true, status: unauthorized });
+        expect(html).toContain('Live updates off — why?');
+        expect(html).toContain('data-testid="bridge-realtime-dev-badge"');
+        // Accessible: a real button that says it controls a collapsed panel, and
+        // a polite live region that announces the reason.
+        expect(html).toMatch(/<button[^>]*type="button"[^>]*aria-expanded="false"/);
+        expect(html).toContain('aria-live="polite"');
+        expect(html).toContain('Bridge live updates are off: wrong_environment');
+    });
+    it('renders nothing in a production build', async () => {
+        const html = await renderBadge({ dev: false, status: unauthorized });
+        expect(html).not.toContain('bridge-realtime-dev-badge');
+        expect(html).not.toContain('Live updates off');
+    });
+    it('renders nothing when opted out', async () => {
+        const html = await renderBadge({ dev: true, status: unauthorized, enabled: false });
+        expect(html).not.toContain('bridge-realtime-dev-badge');
+    });
+    it('renders no badge while live updates are working', async () => {
+        const html = await renderBadge({ dev: true, status: open });
+        expect(html).not.toContain('Live updates off');
+    });
+});
+// ── Mounted automatically by <BridgeBootstrap /> ────────────────────────────
+async function renderBootstrap(opts) {
+    vi.resetModules();
+    vi.doMock('$app/environment', () => ({ dev: opts.dev, browser: false, building: false, version: 'test' }));
+    vi.doMock('$app/navigation', () => ({ beforeNavigate: () => { }, goto: async () => { } }));
+    vi.doMock('$app/stores', () => ({ page: readable({ url: new URL('http://localhost/') }) }));
+    // The route guard needs an initialised BridgeAuth; this test is about markup.
+    vi.doMock('../auth/route-guard.js', () => ({
+        createRouteGuard: () => ({ getNavigationDecision: async () => ({ type: 'allow' }) }),
+        routeRulesReferenceFlag: () => false,
+    }));
+    vi.doMock('../client/stores/config.store.js', () => ({
+        getConfig: () => ({ appId: 'app-1', apiBaseUrl: 'http://test', devBadge: opts.devBadge }),
+        getRouteGuardConfig: () => null,
+    }));
+    const { _setRealtimeStatusDetail } = await import('./realtime-status.js');
+    _setRealtimeStatusDetail(unauthorized);
+    const { default: BridgeBootstrap } = await import('../client/BridgeBootstrap.svelte');
+    const { render } = await import('svelte/server');
+    return render(BridgeBootstrap, { props: {} }).body;
+}
+describe('<BridgeBootstrap> mounts the badge', () => {
+    it('without any app code in a development build', async () => {
+        expect(await renderBootstrap({ dev: true })).toContain('Live updates off — why?');
+    });
+    it('and respects devBadge: false', async () => {
+        expect(await renderBootstrap({ dev: true, devBadge: false })).not.toContain('bridge-realtime-dev-badge');
+    });
+    it('and never in a production build', async () => {
+        expect(await renderBootstrap({ dev: false })).not.toContain('bridge-realtime-dev-badge');
+    });
+});

package/dist/core/realtime-status.d.ts

@@ -1,6 +1,20 @@
 import { type Readable } from 'svelte/store';
-import type { ConnectionState } from '@nebulr-group/bridge-auth-core';
+import type { ConnectionState, RealtimeStatus } from '@nebulr-group/bridge-auth-core';
 /** Reactive readable store of the current realtime connection state. */
 export declare const realtimeStatus: Readable<ConnectionState>;
-/** Internal — set the current status. Only called by `startBridgeRuntime`. */
+/**
+ * Reactive readable store of the full realtime status (TBP-644): `state`, and
+ * when live updates are not working, the machine-readable `reason`, whose
+ * `side` the fault is on (`app` / `config` / `bridge` / `network`), whether the
+ * client is still `retrying`, a `docsUrl` and a support `ref`.
+ *
+ * A sibling of `realtimeStatus` rather than a change to it: that store is a
+ * plain `ConnectionState` string that apps compare and render directly, so
+ * widening its type would break them. `realtimeStatus` always equals
+ * `realtimeStatusDetail.state`.
+ */
+export declare const realtimeStatusDetail: Readable<RealtimeStatus>;
+/** Internal — set the current state. Only called by `startBridgeRuntime`. */
 export declare function _setRealtimeStatus(state: ConnectionState): void;
+/** Internal — set the full status. Only called by `startBridgeRuntime`. */
+export declare function _setRealtimeStatusDetail(status: RealtimeStatus): void;

package/dist/core/realtime-status.js

@@ -7,9 +7,31 @@
 // offline indicators, retry banners, etc.
 import { writable } from 'svelte/store';
 const _store = writable('idle');
+const _detail = writable({ state: 'idle', retrying: false, since: Date.now() });
 /** Reactive readable store of the current realtime connection state. */
 export const realtimeStatus = _store;
-/** Internal — set the current status. Only called by `startBridgeRuntime`. */
+/**
+ * Reactive readable store of the full realtime status (TBP-644): `state`, and
+ * when live updates are not working, the machine-readable `reason`, whose
+ * `side` the fault is on (`app` / `config` / `bridge` / `network`), whether the
+ * client is still `retrying`, a `docsUrl` and a support `ref`.
+ *
+ * A sibling of `realtimeStatus` rather than a change to it: that store is a
+ * plain `ConnectionState` string that apps compare and render directly, so
+ * widening its type would break them. `realtimeStatus` always equals
+ * `realtimeStatusDetail.state`.
+ */
+export const realtimeStatusDetail = _detail;
+/** Internal — set the current state. Only called by `startBridgeRuntime`. */
 export function _setRealtimeStatus(state) {
     _store.set(state);
+    // Keep the detail store in step when running on an auth-core that has no
+    // status hook (only open/close/degraded). With the hook, the detail for
+    // this state has already landed and is left alone.
+    _detail.update((d) => (d.state === state ? d : { state, retrying: false, since: Date.now() }));
+}
+/** Internal — set the full status. Only called by `startBridgeRuntime`. */
+export function _setRealtimeStatusDetail(status) {
+    _detail.set(status);
+    _store.set(status.state);
 }

package/dist/flags/index.d.ts

@@ -2,7 +2,8 @@ export { createBridgeFlags, BrowserIdentityStorage, type CreateBridgeFlagsConfig
 export { evaluateFlag, setBridgeFlagsInstance, getBridgeFlagsInstance, notifyFlagChanged, notifyAllFlagsChanged, subscribeToFlagChanges, } from './registry.js';
 export { useFlag, flagStore, _flagVersionsRune, type FlagStore } from './flag.svelte.js';
 export { default as FeatureFlag } from './FeatureFlag.svelte';
-export { realtimeStatus } from './realtime-status.js';
-export type { ConnectionState } from '@nebulr-group/bridge-auth-core';
+export { realtimeStatus, realtimeStatusDetail } from './realtime-status.js';
+export { onBridgeRealtimeStatus } from '../core/bridge-runtime.js';
+export type { ConnectionState, RealtimeStatus } from '@nebulr-group/bridge-auth-core';
 export { BridgeFlags, MemoryIdentityStorage, attachIdentity, generateAnonymousId, BRIDGE_CONTEXT_HEADER, serializeContext, deserializeContext, serverInstanceId, } from '@nebulr-group/bridge-auth-core';
 export type { CachedFlag, FlagValueType, EvalTelemetry, DiscoveryTelemetry, BridgeFlagsHooks, DeclaredAttributeType, AttributeDeclaration, BridgeFlagsMode, EvalContext, IdentityStorage, AnonymousTrackingMode, BridgeIdentity, RealtimeMessage, } from '@nebulr-group/bridge-auth-core';

package/dist/flags/index.js

@@ -14,7 +14,9 @@ export { useFlag, flagStore, _flagVersionsRune } from './flag.svelte.js';
 export { default as FeatureFlag } from './FeatureFlag.svelte';
 // Reactive realtime connection status (subscribe in components to show
 // offline indicators, retry banners, etc.).
-export { realtimeStatus } from './realtime-status.js';
+export { realtimeStatus, realtimeStatusDetail } from './realtime-status.js';
+// TBP-644 — why live updates are off, whose side it is, and whether it retries.
+export { onBridgeRealtimeStatus } from '../core/bridge-runtime.js';
 // Auth-core re-exports — consumers can stay on the `/flags` path without
 // adding a direct dependency on `@nebulr-group/bridge-auth-core`.
 export { BridgeFlags, MemoryIdentityStorage, attachIdentity, generateAnonymousId, BRIDGE_CONTEXT_HEADER, serializeContext, deserializeContext, serverInstanceId, } from '@nebulr-group/bridge-auth-core';

package/dist/flags/realtime-status.d.ts

@@ -1 +1 @@
-export { realtimeStatus, _setRealtimeStatus } from '../core/realtime-status.js';
+export { realtimeStatus, realtimeStatusDetail, _setRealtimeStatus } from '../core/realtime-status.js';

package/dist/flags/realtime-status.js

@@ -1,4 +1,4 @@
 // Backward-compat re-export. The implementation moved to `core/realtime-status.ts`
 // because the realtime channel is a Bridge-level construct (flags + billing both
 // ride it). Imports from `@nebulr-group/bridge-svelte/flags` keep working.
-export { realtimeStatus, _setRealtimeStatus } from '../core/realtime-status.js';
+export { realtimeStatus, realtimeStatusDetail, _setRealtimeStatus } from '../core/realtime-status.js';

package/dist/index.d.ts

@@ -8,6 +8,10 @@ export type { BrandingSnapshot, SubscriptionSnapshot, UserSnapshot, SessionSnaps
 export type { BridgeEventHandlers, BridgeEventsDispatcher } from './core/events.js';
 export { default as BridgeBootstrap, default as BridgeProvider } from './client/BridgeBootstrap.svelte';
 export { default as ApiTokenManagement } from './client/components/developer/ApiTokenManagement.svelte';
+export { default as RealtimeDevBadge } from './client/components/developer/RealtimeDevBadge.svelte';
+export { realtimeStatus, realtimeStatusDetail } from './core/realtime-status.js';
+export { onBridgeRealtimeStatus } from './core/bridge-runtime.js';
+export type { RealtimeStatus } from '@nebulr-group/bridge-auth-core';
 export { default as FeatureFlag } from './flags/FeatureFlag.svelte';
 export { default as ProfileName } from './client/components/ProfileName.svelte';
 export { default as TeamManagementPanel } from './client/components/team/TeamManagementPanel.svelte';

package/dist/index.js

@@ -16,6 +16,14 @@ export { bridge } from './core/bridge.js';
 // Components (Svelte components must have `export default`)
 export { default as BridgeBootstrap, default as BridgeProvider } from './client/BridgeBootstrap.svelte';
 export { default as ApiTokenManagement } from './client/components/developer/ApiTokenManagement.svelte';
+// TBP-644 — dev-only live-updates badge. <BridgeBootstrap /> already mounts it;
+// exported for apps that render their own bootstrap.
+export { default as RealtimeDevBadge } from './client/components/developer/RealtimeDevBadge.svelte';
+// TBP-644 — realtime status. `realtimeStatus` is the plain state string;
+// `realtimeStatusDetail` adds the reason, whose side it is and whether it is
+// still retrying. `onBridgeRealtimeStatus` is the event-style subscription.
+export { realtimeStatus, realtimeStatusDetail } from './core/realtime-status.js';
+export { onBridgeRealtimeStatus } from './core/bridge-runtime.js';
 export { default as FeatureFlag } from './flags/FeatureFlag.svelte';
 export { default as ProfileName } from './client/components/ProfileName.svelte';
 export { default as TeamManagementPanel } from './client/components/team/TeamManagementPanel.svelte';

package/dist/shared/types/config.d.ts

@@ -12,6 +12,12 @@ export interface BridgeConfig extends BridgeAuthConfig {
     /** Per-key copy overrides applied on top of the resolved locale, for wording
      *  an app genuinely needs to differ. Highest precedence in the chain. */
     messages?: MessageOverrides;
+    /** Show the "Live updates off — why?" corner badge that <BridgeBootstrap />
+     *  mounts while realtime is refused, degraded or stuck retrying (TBP-644).
+     *  It only ever renders in development builds; set `false` to hide it there
+     *  too. Production builds never show it, whatever this says.
+     *  @default true */
+    devBadge?: boolean;
     /** Billing paywall configuration. When set, Bridge redirects unauthenticated
      *  or plan-less users to `paywallRoute` before the page renders. */
     billing?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulr-group/bridge-svelte",
-  "version": "0.7.1",
+  "version": "0.8.0-beta.0",
   "description": "Bridge Svelte library, This library helps you to add bridge authentication and feature flags, and payments to your svelte application.",
   "author": "Iman Pouya",
   "license": "MIT",
@@ -56,7 +56,7 @@
     "svelte": "^5.0.0",
     "@sveltejs/kit": "^2.0.0",
     "@stripe/stripe-js": ">=4.0.0",
-    "@nebulr-group/bridge-auth-core": ">=0.6.0 <1.0.0"
+    "@nebulr-group/bridge-auth-core": ">=0.7.0-beta.0 <1.0.0"
   },
   "peerDependenciesMeta": {
     "@stripe/stripe-js": {
@@ -77,7 +77,7 @@
     "typescript": "^6.0.0",
     "vite": "^6.2.6",
     "vitest": "^4.1.4",
-    "@nebulr-group/bridge-auth-core": "^0.6.0"
+    "@nebulr-group/bridge-auth-core": "0.7.0-beta.0"
   },
   "keywords": [
     "svelte",