@nebulr-group/bridge-svelte 0.7.0 → 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/client/components/sdk-auth/LoginForm.svelte

@@ -239,6 +239,35 @@
 {:else if currentAuthState === 'tenant-selection'}
   <TenantSelector onError={onError} {messages} />
 
+<!--
+  Settling: the session is real and the host app has not navigated yet.
+
+  This branch is `!== 'unauthenticated'` rather than an explicit list of
+  `authenticated | credentials-validated` on purpose. Those two used to fall
+  through to the credentials form below, so somebody who had just typed their
+  password correctly was shown the password form again — which reads as a
+  refusal, and the reasonable response is to type it again (TBP-635). The window
+  opens when the token exchange resolves and closes only when the consumer's
+  router lands, because LoginForm fires `onLogin` and deliberately does not
+  navigate. Measured at 600ms against a local stack; longer anywhere real.
+
+  Listing the two states would fix the two we know about and leave the next
+  `AuthState` member falling into the same hole. Inverting the test means the
+  credentials form renders ONLY for `unauthenticated`, and anything else lands
+  on a spinner — wrong-but-harmless instead of wrong-and-alarming.
+
+  `login.submitting` is reused rather than given its own key: it already says
+  "Signing in…" in all twelve locales, and a second key rendering the same words
+  would be a translation burden that buys nothing.
+-->
+{:else if currentAuthState !== 'unauthenticated'}
+  <AuthFormWrapper heading={null} class={className} {style} {...rest}>
+    <div class="bridge-auth-settling" data-bridge-auth-settling>
+      <Spinner size={24} />
+      <span>{t('login.submitting')}</span>
+    </div>
+  </AuthFormWrapper>
+
 <!-- Inline forgot password -->
 {:else if step === 'forgot-password'}
   <AuthFormWrapper heading={fpEmailSent ? null : t('forgot.headingRequest')}>

package/dist/client/components/sdk-auth/login-settling.test.d.ts

@@ -0,0 +1,27 @@
+/**
+ * TBP-635 — LoginForm must never draw the credentials form to somebody who has
+ * already authenticated.
+ *
+ * The top-level branch named `mfa-required`, `mfa-setup-required` and
+ * `tenant-selection`, and let everything else fall through to the password
+ * form. `authenticated` and `credentials-validated` are also "everything else",
+ * so between the token exchange resolving and the host app's router landing —
+ * LoginForm fires `onLogin` and deliberately does not navigate — the component
+ * showed a password field to a user who had just typed their password
+ * correctly. That reads as a refusal. Measured at 600ms against a local stack.
+ *
+ * ## What this file can and cannot prove
+ *
+ * The ticket's suggested test is a MutationObserver recording every DOM batch
+ * during a real login, because a sampling loop can miss the race. This
+ * workspace has no DOM (see auth-form-description.test.ts for why), so that
+ * exact test is not available here and belongs in the Playwright e2e suite.
+ *
+ * What IS available is stronger in the dimension that actually caused the bug.
+ * The defect was not a timing subtlety — it was an unhandled branch. So this
+ * enumerates EVERY member of `AuthState`, read out of auth-core's shipped
+ * type declaration rather than hardcoded, and asserts that exactly one of them
+ * renders a password field. A seventh state added to auth-core tomorrow is
+ * covered the moment it exists, which is the half a race-detector would miss.
+ */
+export {};

package/dist/client/components/sdk-auth/login-settling.test.js

@@ -0,0 +1,219 @@
+/**
+ * TBP-635 — LoginForm must never draw the credentials form to somebody who has
+ * already authenticated.
+ *
+ * The top-level branch named `mfa-required`, `mfa-setup-required` and
+ * `tenant-selection`, and let everything else fall through to the password
+ * form. `authenticated` and `credentials-validated` are also "everything else",
+ * so between the token exchange resolving and the host app's router landing —
+ * LoginForm fires `onLogin` and deliberately does not navigate — the component
+ * showed a password field to a user who had just typed their password
+ * correctly. That reads as a refusal. Measured at 600ms against a local stack.
+ *
+ * ## What this file can and cannot prove
+ *
+ * The ticket's suggested test is a MutationObserver recording every DOM batch
+ * during a real login, because a sampling loop can miss the race. This
+ * workspace has no DOM (see auth-form-description.test.ts for why), so that
+ * exact test is not available here and belongs in the Playwright e2e suite.
+ *
+ * What IS available is stronger in the dimension that actually caused the bug.
+ * The defect was not a timing subtlety — it was an unhandled branch. So this
+ * enumerates EVERY member of `AuthState`, read out of auth-core's shipped
+ * type declaration rather than hardcoded, and asserts that exactly one of them
+ * renders a password field. A seventh state added to auth-core tomorrow is
+ * covered the moment it exists, which is the half a race-detector would miss.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { createServer } from 'vite';
+import { svelte } from '@sveltejs/vite-plugin-svelte';
+import { render } from 'svelte/server';
+import {} from 'svelte';
+import { en, sv } from '@nebulr-group/bridge-auth-core';
+import fs from 'node:fs';
+import path from 'node:path';
+const ROOT = process.cwd();
+const COMPONENT_DIR = 'src/lib/client/components/sdk-auth';
+const SEED_PREFIX = '__seeded-settling-';
+/**
+ * Every `AuthState`, parsed out of the auth-core declaration the package
+ * actually ships.
+ *
+ * Deliberately not a literal list: a hardcoded one would still say six when
+ * auth-core says seven, and the bug being fixed is precisely a state nobody
+ * remembered to handle. Parsing throws rather than returning a short list, so a
+ * refactor that moves the type fails this suite loudly instead of quietly
+ * testing fewer states.
+ */
+function authStates() {
+    // Resolved from the filesystem rather than the module system: the package
+    // exports no `./package.json` subpath, and vitest's module runner supports
+    // neither `require.resolve` nor `import.meta.resolve` here. Both candidate
+    // paths are tried because bun may hoist the dep to the workspace root.
+    const candidates = [
+        path.join(ROOT, 'node_modules/@nebulr-group/bridge-auth-core/dist/types.d.ts'),
+        path.join(ROOT, '../node_modules/@nebulr-group/bridge-auth-core/dist/types.d.ts'),
+    ];
+    const dts = candidates.find((c) => fs.existsSync(c));
+    if (!dts) {
+        throw new Error(`auth-core types.d.ts not found. Looked in:\n  ${candidates.join('\n  ')}`);
+    }
+    const source = fs.readFileSync(dts, 'utf8');
+    const match = source.match(/export type AuthState\s*=([^;]+);/);
+    if (!match) {
+        throw new Error('Could not find `export type AuthState` in auth-core types.d.ts.');
+    }
+    const states = [...match[1].matchAll(/'([^']+)'/g)].map((m) => m[1]);
+    if (states.length < 2) {
+        throw new Error(`Parsed only ${states.length} AuthState members — parser is wrong.`);
+    }
+    return states;
+}
+const STATES = authStates();
+let server;
+const seededPaths = [];
+beforeAll(async () => {
+    for (const f of fs.readdirSync(path.join(ROOT, COMPONENT_DIR))) {
+        if (f.startsWith(SEED_PREFIX))
+            fs.unlinkSync(path.join(ROOT, COMPONENT_DIR, f));
+    }
+    server = await createServer({
+        configFile: false,
+        root: ROOT,
+        logLevel: 'error',
+        server: { middlewareMode: true, hmr: false },
+        plugins: [svelte({ compilerOptions: { dev: false } })],
+    });
+}, 120_000);
+afterAll(async () => {
+    await server?.close();
+    for (const p of seededPaths) {
+        if (fs.existsSync(p))
+            fs.unlinkSync(p);
+    }
+});
+/**
+ * Render LoginForm with `currentAuthState` pinned.
+ *
+ * The seed replaces the one `$derived($authState)` line, so the template — every
+ * branch, the wrapper call, the catalogue lookups — is the real shipped source.
+ * Driving the store itself would need the network and the real state machine,
+ * and would test auth-core's transitions rather than this component's branching,
+ * which is where the defect was.
+ */
+async function renderAtState(state, props = {}) {
+    const file = 'LoginForm.svelte';
+    const from = 'let currentAuthState = $derived($authState);';
+    let source = fs.readFileSync(path.join(ROOT, COMPONENT_DIR, file), 'utf8');
+    if (!source.includes(from)) {
+        throw new Error(`State seed target not found in ${file}:\n  ${from}\n` +
+            'The component was refactored. Update the seed so the test keeps driving ' +
+            'the auth-state branch — do not delete the assertion.');
+    }
+    source = source.replace(from, `let currentAuthState = $state('${state}');`);
+    const name = `${SEED_PREFIX}${process.pid}-${seededPaths.length}-${file}`;
+    const full = path.join(ROOT, COMPONENT_DIR, name);
+    fs.writeFileSync(full, source);
+    seededPaths.push(full);
+    const mod = await server.ssrLoadModule(`/${COMPONENT_DIR}/${name}`);
+    const Component = mod.default;
+    return render(Component, { props }).body;
+}
+async function setLocale(locale) {
+    const mod = await server.ssrLoadModule('/src/lib/client/stores/config.store.ts');
+    mod.bridgeConfig.initConfig({ appId: 'tbp-635-test', locale });
+}
+/** A password field is the thing that must never appear post-auth. */
+function hasPasswordField(html) {
+    return /<input[^>]+type="password"/.test(html);
+}
+function text(html) {
+    return html
+        .replace(/<!--[\s\S]*?-->/g, '')
+        .replace(/<[^>]*>/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+// ---------------------------------------------------------------------------
+// 1. The fixture itself
+// ---------------------------------------------------------------------------
+describe('AuthState coverage (TBP-635)', () => {
+    it('reads the real state list out of the shipped auth-core types', () => {
+        // If this drifts, every assertion below silently covers less.
+        expect(STATES).toContain('unauthenticated');
+        expect(STATES).toContain('authenticated');
+        expect(STATES).toContain('credentials-validated');
+        expect(STATES.length).toBeGreaterThanOrEqual(6);
+    });
+});
+// ---------------------------------------------------------------------------
+// 2. The invariant
+// ---------------------------------------------------------------------------
+describe('LoginForm never shows the credentials form post-auth (TBP-635)', () => {
+    it('renders a password field for `unauthenticated` and for nothing else', async () => {
+        await setLocale(undefined);
+        const withPassword = [];
+        for (const state of STATES) {
+            if (hasPasswordField(await renderAtState(state)))
+                withPassword.push(state);
+        }
+        // Both directions. Asserting only "authenticated has no password field"
+        // would pass for a component that rendered nothing at all, ever.
+        expect(withPassword).toEqual(['unauthenticated']);
+    });
+    for (const state of ['authenticated', 'credentials-validated']) {
+        it(`shows the settling card at "${state}"`, async () => {
+            await setLocale(undefined);
+            const html = await renderAtState(state);
+            expect(html).toContain('data-bridge-auth-settling');
+            expect(hasPasswordField(html)).toBe(false);
+            // Not a blank card: an empty box during a pause is its own bad message.
+            expect(text(html)).toContain(en['login.submitting']);
+        });
+    }
+    it('translates the waiting copy', async () => {
+        await setLocale('sv');
+        const html = await renderAtState('authenticated');
+        expect(text(html)).toContain(sv['login.submitting']);
+        expect(text(html)).not.toContain(en['login.submitting']);
+    });
+    it('suppresses the heading while settling, so no stale "Log in" survives', async () => {
+        await setLocale(undefined);
+        const html = await renderAtState('authenticated', { heading: 'Log in to NorthWhistle' });
+        expect(html).not.toContain('Log in to NorthWhistle');
+        expect(html).toContain('data-bridge-auth-settling');
+    });
+    it('still hands the three delegated states to their own components', async () => {
+        // The fix must not have swallowed the branches that already worked — an
+        // over-eager `!== unauthenticated` placed above them would do exactly that.
+        await setLocale(undefined);
+        expect(await renderAtState('tenant-selection')).toContain('bridge-tenant-list');
+        expect(await renderAtState('mfa-required')).toContain(en['mfa.challengeHeading']);
+        expect(await renderAtState('mfa-setup-required')).toContain(en['mfaSetup.heading']);
+    });
+    it('leaves the unauthenticated step machine alone', async () => {
+        await setLocale(undefined);
+        const html = await renderAtState('unauthenticated');
+        expect(hasPasswordField(html)).toBe(true);
+        expect(html).toContain(en['login.submit']);
+        expect(html).not.toContain('data-bridge-auth-settling');
+    });
+});
+// ---------------------------------------------------------------------------
+// 3. onLogin is untouched
+// ---------------------------------------------------------------------------
+describe('onLogin lifecycle is unchanged (TBP-635)', () => {
+    it('still fires from an effect keyed on `authenticated`', () => {
+        // Effects do not run in a server render, so this is asserted on the source.
+        // It is here because the tempting wrong fix for this bug is to move
+        // `onLogin` earlier so the consumer navigates sooner — which would fire it
+        // before the session is real.
+        const source = fs.readFileSync(path.join(ROOT, COMPONENT_DIR, 'LoginForm.svelte'), 'utf8');
+        const effect = source.match(/\$effect\(\(\) => \{[\s\S]*?\}\);/);
+        expect(effect, 'LoginForm no longer has an $effect').not.toBeNull();
+        expect(effect[0]).toContain("currentAuthState === 'authenticated'");
+        expect(effect[0]).toContain('onLogin?.()');
+        // Exactly one call site, so it cannot fire twice.
+        expect(source.match(/onLogin\?\.\(\)/g)).toHaveLength(1);
+    });
+});

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.