@nebulr-group/bridge-svelte 0.9.0-beta.7 → 0.9.0

package/dist/client/BridgeBootstrap.js

@@ -6,6 +6,7 @@ import { createRouteGuard } from '../auth/route-guard.js';
 import { dropFlagCache, guardCacheGeneration } from '../auth/guard-cache.js';
 import { getBridgeAuth, bridgeReadyStore, markReady, waitForBridge as _waitForBridge, } from '../core/bridge-instance.js';
 import { installBridgeAuthFetch } from '../core/bridge-runtime.js';
+import { refreshBilling, tokenStaleHandlerOf } from '../core/billing-store.js';
 import { useBridge, sanitizeReturnTo, stashReturnTo, takeReturnTo, withReturnTo, } from '@nebulr-group/bridge-auth-core';
 import { logger } from '../shared/logger.js';
 import { bridgeConfig, getConfig, getRouteGuardConfig } from './stores/config.store.js';
@@ -226,6 +227,8 @@ function ensureInitialised() {
                     apiBaseUrl: ctx.apiBaseUrl,
                     accessToken: ctx.accessToken,
                     appId: ctx.appId,
+                    // TBP-762 — renew an out-of-date sign-in and retry instead of failing.
+                    onTokenStale: tokenStaleHandlerOf(bridge),
                 });
             }
         }
@@ -340,6 +343,16 @@ async function handleCallbackRoute(url, kitFetch) {
                 const bridge = getBridgeAuth();
                 try {
                     await bridge.confirmStripeCheckout(sessionId, kitFetch);
+                    // TBP-762 — the checkout changed the plan: re-read the billing stores
+                    // before the landing page renders, so its "Current plan" is the new
+                    // one on first render. In the browser only — a server-side read
+                    // would fill a store no page sees. Never throws.
+                    if (typeof window !== 'undefined') {
+                        try {
+                            await refreshBilling();
+                        }
+                        catch { /* the landing page re-reads */ }
+                    }
                     redirect(303, redirectTo);
                 }
                 catch (err) {

package/dist/client/BridgeBootstrap.svelte

@@ -24,6 +24,7 @@
     type StartBridgeRuntimeOptions,
   } from '../core/bridge-runtime.js';
   import RealtimeDevBadge from './components/developer/RealtimeDevBadge.svelte';
+  import { startBillingRefresh } from '../core/billing-store.js';
   import BridgeUpgradeDialog from './components/subscription/BridgeUpgradeDialog.svelte';
   import { dismissQuotaRefusal, quotaRefusal } from '../core/quota-refusal.js';
   import { dismissFeatureUpgrade, featureUpgrade, openFeatureUpgrade } from '../core/feature-upgrade.js';
@@ -219,6 +220,7 @@
   let _recheckTimer: ReturnType<typeof setTimeout> | undefined;
   let _stopFlagWatch: (() => void) | undefined;
   let _stopAuthzWatch: (() => void) | undefined;
+  let _stopBillingRefresh: (() => void) | undefined;
 
   function scheduleRouteRecheck() {
     if (_recheckTimer) clearTimeout(_recheckTimer);
@@ -255,6 +257,11 @@
     // protected page and a revoked entitlement ejects the user.
     _stopAuthzWatch = onBridgeAuthorizationChange(() => scheduleRouteRecheck());
 
+    // TBP-762 — the billing store's refresh rule: re-read the plan list,
+    // current plan and billing state on a renewed sign-in and on tab focus
+    // after 30 s (live billing events are wired in the runtime).
+    _stopBillingRefresh = startBillingRefresh();
+
     // Fetch app config outside load() so we use the correct fetch context.
     // LoginForm also calls ensureAppConfig() — both share the same in-flight promise.
     void ensureAppConfig();
@@ -287,6 +294,8 @@
   });
 
   onDestroy(() => {
+    _stopBillingRefresh?.();
+    _stopBillingRefresh = undefined;
     if (_recheckTimer) {
       clearTimeout(_recheckTimer);
       _recheckTimer = undefined;

package/dist/client/billing-role.d.ts

@@ -4,6 +4,7 @@ export declare function isBillingAdmin(): boolean;
 export declare const CONTACT_WORKSPACE_OWNER = "Contact your workspace owner.";
 /**
  * The member-facing sentence for a quota, by how close it is to the cap.
- * `over` is also what a refused request (the upgrade dialog) says.
+ * `over` is also what a refused request (the upgrade dialog) says. `reached`
+ * (TBP-697): exactly at a hard limit — 2 of 2 is not "approaching".
  */
-export declare function quotaMemberBody(label: string, state: 'over' | 'critical' | 'approaching'): string;
+export declare function quotaMemberBody(label: string, state: 'over' | 'reached' | 'critical' | 'approaching'): string;

package/dist/client/billing-role.js

@@ -22,12 +22,15 @@ export function isBillingAdmin() {
 export const CONTACT_WORKSPACE_OWNER = 'Contact your workspace owner.';
 /**
  * The member-facing sentence for a quota, by how close it is to the cap.
- * `over` is also what a refused request (the upgrade dialog) says.
+ * `over` is also what a refused request (the upgrade dialog) says. `reached`
+ * (TBP-697): exactly at a hard limit — 2 of 2 is not "approaching".
  */
 export function quotaMemberBody(label, state) {
     switch (state) {
         case 'over':
             return `Your workspace is over its ${label} cap. ${CONTACT_WORKSPACE_OWNER}`;
+        case 'reached':
+            return `Your workspace has reached its ${label} limit. ${CONTACT_WORKSPACE_OWNER}`;
         case 'critical':
             return `Your workspace is approaching its ${label} cap. ${CONTACT_WORKSPACE_OWNER}`;
         case 'approaching':

package/dist/client/components/subscription/BridgeBillingNotice.svelte

@@ -24,6 +24,7 @@
     type BillingSubscriptionSnapshot,
   } from '@nebulr-group/bridge-auth-core';
   import { getBridgeAuth } from '../../../core/bridge-instance.js';
+  import { ensureBillingState } from '../../../core/billing-store.js';
   import { billingRoutes } from '../../billing-routes.js';
 
   type Chassis = 'bar' | 'rail' | 'card';
@@ -77,13 +78,9 @@
       useBridge().subscription.setError('Not authenticated');
       return;
     }
-    if (!snapshot.state) {
-      useBridge().subscription.mount({
-        apiBaseUrl: ctx.apiBaseUrl,
-        accessToken: ctx.accessToken,
-        appId: ctx.appId,
-      });
-    }
+    // TBP-762 — through the billing store: renews an out-of-date sign-in,
+    // retries once, and re-reads on the store's refresh rule.
+    void ensureBillingState();
   });
 
   onDestroy(() => unsubscribe?.());

package/dist/client/components/subscription/BridgeBillingRoutes.svelte

@@ -27,12 +27,14 @@
        pages keep working.
     4. Headless: `PlanSelector`, `BridgeSubscriptionStatus`, `BillingPortalButton`
        and `subscriptionStore` are the pieces these pages are built from.
+
+  A Free pick (like a paid checkout) lands on /subscription/success (TBP-762).
 -->
 <script lang="ts">
   import type { Snippet } from 'svelte';
   import { untrack } from 'svelte';
   import { page } from '$app/stores';
-  import { loadSubscription, subscriptionStore } from '../../../core/bridge-instance.js';
+  import { ensureSubscription, loadSubscription } from '../../../core/bridge-instance.js';
   import { BRIDGE_AUTH_ROUTE_PARAM, bridgeAuthBase } from '../../auth-routes.js';
   import { parseBridgeBillingRoute, type BridgeBillingPage } from '../../billing-routes.js';
   import PlanSelector from './PlanSelector.svelte';
@@ -64,19 +66,17 @@
     error: "We couldn't confirm your payment",
   };
 
-  // Every page reads the subscription. The success page always re-reads it: the
-  // checkout just changed it, and whatever the store holds predates that. Keyed
-  // on the page, because moving between these pages reuses this component.
+  // Every page reads the subscription through the billing store (TBP-762): a
+  // read younger than 30 s is reused, anything older is re-read. The success
+  // page always re-reads everything — the checkout just changed it, and
+  // whatever the store holds predates that. Keyed on the page, because moving
+  // between these pages reuses this component. (The success page's badge is
+  // `fresh`: it re-reads the billing state itself.)
   $effect(() => {
     const current = route?.page;
     if (!current) return;
     untrack(() => {
-      const { status, loading } = $subscriptionStore;
-      if (current === 'success' || (!status && !loading)) {
-        loadSubscription().catch(() => {
-          /* surfaced via subscriptionStore.error */
-        });
-      }
+      void (current === 'success' ? loadSubscription() : ensureSubscription());
     });
   });
 </script>
@@ -102,7 +102,7 @@
     <p class="bridge-billing-text">Your plan is active.</p>
     <div class="bridge-billing-current">
       <span class="bridge-billing-label">Current plan</span>
-      <BridgeSubscriptionStatus />
+      <BridgeSubscriptionStatus fresh />
     </div>
     <a class="bridge-btn-primary bridge-billing-action" href={redirectTo}>Continue</a>
   {:else if p === 'error'}

package/dist/client/components/subscription/BridgePaywall.svelte

@@ -2,7 +2,7 @@
   import type { Snippet } from 'svelte';
   import { onMount } from 'svelte';
   import type { Plan, PriceOfferSdk } from '@nebulr-group/bridge-auth-core';
-  import { subscriptionStore, loadSubscription } from '../../../core/bridge-instance.js';
+  import { subscriptionStore, ensureSubscription } from '../../../core/bridge-instance.js';
   import PlanSelector from './PlanSelector.svelte';
 
   interface Props {
@@ -29,9 +29,8 @@
   const loading = $derived($subscriptionStore.loading);
 
   onMount(() => {
-    if (!$subscriptionStore.status && !$subscriptionStore.loading) {
-      loadSubscription();
-    }
+    // TBP-762 — the billing store: reuses a read younger than 30 s.
+    void ensureSubscription();
   });
 
   // Show paywall only once the subscription status is known and the tenant

package/dist/client/components/subscription/BridgePaywallPage.svelte

@@ -21,7 +21,7 @@
   import { onMount } from 'svelte';
   import { page } from '$app/stores';
   import type { Plan, PriceOfferSdk } from '@nebulr-group/bridge-auth-core';
-  import { loadSubscription, subscriptionStore } from '../../../core/bridge-instance.js';
+  import { ensureSubscription } from '../../../core/bridge-instance.js';
   import { logger } from '../../../shared/logger.js';
   import { billingRoutes } from '../../billing-routes.js';
   import PlanSelector from './PlanSelector.svelte';
@@ -56,11 +56,8 @@
   const cancel = $derived(cancelRedirect ?? $page.url.pathname);
 
   onMount(() => {
-    if (!$subscriptionStore.status && !$subscriptionStore.loading) {
-      loadSubscription().catch(() => {
-        /* surfaced via subscriptionStore.error */
-      });
-    }
+    // TBP-762 — the billing store: reuses a read younger than 30 s.
+    void ensureSubscription();
     const here = $page.url.pathname;
     if (isDevBuild() && routes.paywallRoute !== here) {
       logger.warn(

package/dist/client/components/subscription/BridgeQuotaBanner.svelte

@@ -9,9 +9,10 @@
     - the metric has no quota configured on the plan (server returns null), OR
     - usage is below 80% of the limit (warningLevel === null).
 
-  Three visible states:
+  Four visible states (hard quotas):
     - approaching  (80-94% used)        → severity 'warn'
     - critical     (95-99% used)        → severity 'critical'
+    - reached      (used == limit)      → severity 'critical', "limit reached" (TBP-697)
     - over-cap     (used > limit)       → severity 'critical', different copy
 
   Two role variants (admin / member): admins get an Upgrade CTA; members get
@@ -26,7 +27,8 @@
     useBridge,
     type QuotaSnapshot,
   } from '@nebulr-group/bridge-auth-core';
-  import { isBillingAdmin as canManageBilling, quotaMemberBody } from '../../billing-role.js';
+  import { isBillingAdmin as canManageBilling } from '../../billing-role.js';
+  import { quotaBannerCopy, quotaBannerState } from '../../quota-banner-copy.js';
   import { billingRoutes } from '../../billing-routes.js';
 
   type Chassis = 'rail';
@@ -92,29 +94,14 @@
     snapshot = useBridge().quota(metric);
   });
 
-  const warningLevel = $derived(snapshot?.warningLevel ?? null);
-  // TBP-275 — `metered` quotas bill overage instead of blocking. Prefer the
-  // server-authoritative `overcap` flag (handles limit === 0 pure-per-unit)
-  // over a UI-derived `used > limit`.
-  const isMetered = $derived(snapshot?.policy === 'metered');
-  const overCap = $derived(
-    snapshot
-      ? (snapshot.overcap ?? snapshot.used > snapshot.limit)
-      : false,
-  );
-  // Hard caps show only at the warning thresholds. Metered quotas also show
-  // once billing has engaged (overCap), even with no warningLevel — that's the
-  // live "you're now being billed for overage" state.
-  const visible = $derived(
-    snapshot !== undefined && (warningLevel !== null || (isMetered && overCap)),
-  );
+  // TBP-697 — the state and the copy live in quota-banner-copy.ts: at
+  // `used >= limit` on a hard quota the banner says the limit is REACHED (2 of
+  // 2 is not "approaching"), whatever warning level the server sent.
+  const bannerState = $derived(quotaBannerState(snapshot));
+  const visible = $derived(bannerState !== 'hidden');
   // Metered never blocks, so it never renders as 'critical' — it's informational.
   const severity = $derived<Severity>(
-    isMetered
-      ? 'warn'
-      : warningLevel === 'critical' || overCap
-        ? 'critical'
-        : 'warn',
+    bannerState === 'critical' || bannerState === 'reached' || bannerState === 'over' ? 'critical' : 'warn',
   );
   const displayLabel = $derived(label ?? snapshot?.label ?? metric);
   const percent = $derived(
@@ -125,94 +112,7 @@
   // Meter bar is meaningless for pure per-unit metered (limit 0) — hide it there.
   const showMeter = $derived(!!snapshot && snapshot.limit > 0);
 
-  /** Format an estimated cost like "$1.00" / "1.00 SEK". */
-  function formatCost(amount: number | undefined, currency: string | undefined): string {
-    if (amount === undefined) return '';
-    const cur = (currency ?? '').toUpperCase();
-    try {
-      return new Intl.NumberFormat(undefined, {
-        style: 'currency',
-        currency: cur || 'USD',
-      }).format(amount);
-    } catch {
-      // Unknown currency code → fall back to "<amount> <CUR>".
-      return `${amount.toFixed(2)}${cur ? ` ${cur}` : ''}`;
-    }
-  }
-
-  function getCopy(
-    snap: QuotaSnapshot | undefined,
-    admin: boolean,
-  ): { title: string; body: string; cta?: string } {
-    if (!snap) return { title: '', body: '' };
-
-    // TBP-275 — metered: live usage + projected cost, never a blocking message.
-    if (snap.policy === 'metered') {
-      const overUnits = snap.limit > 0 ? Math.max(0, snap.used - snap.limit) : snap.used;
-      const cost = formatCost(snap.overageEstimate, snap.currency);
-      const costSuffix = cost ? ` · ~${cost} estimated this period` : '';
-      if (snap.limit > 0) {
-        // included allotment + overage
-        if (overUnits > 0) {
-          return {
-            title: `${displayLabel} overage`,
-            body: `${overUnits.toLocaleString()} over your ${snap.limit.toLocaleString()} included${costSuffix}.`,
-          };
-        }
-        // approaching the included allotment (warningLevel drove visibility)
-        const unit = formatCost(snap.unitAmount, snap.currency);
-        return {
-          title: `${displayLabel} approaching included limit`,
-          body: `You've used ${snap.used.toLocaleString()} of ${snap.limit.toLocaleString()} included${unit ? ` — extra usage is billed at ${unit}/unit` : ''}.`,
-        };
-      }
-      // pure per-unit (limit 0) — billed from unit 1
-      return {
-        title: `${displayLabel} usage`,
-        body: `${snap.used.toLocaleString()} ${displayLabel}${costSuffix}.`,
-      };
-    }
-
-    const over = snap.overcap ?? snap.used > snap.limit;
-    const remaining = Math.max(0, snap.remaining);
-    if (over) {
-      return admin
-        ? {
-            title: `${displayLabel} over cap`,
-            body: `You've used ${snap.used.toLocaleString()} of ${snap.limit.toLocaleString()}. Upgrade your plan to add headroom.`,
-            cta: 'Upgrade',
-          }
-        : {
-            title: `${displayLabel} over cap`,
-            body: quotaMemberBody(displayLabel, 'over'),
-          };
-    }
-    if (warningLevel === 'critical') {
-      return admin
-        ? {
-            title: `${displayLabel} near cap`,
-            body: `You've used ${snap.used.toLocaleString()} of ${snap.limit.toLocaleString()} (${remaining.toLocaleString()} left). Upgrade to avoid hitting the cap.`,
-            cta: 'Upgrade',
-          }
-        : {
-            title: `${displayLabel} near cap`,
-            body: quotaMemberBody(displayLabel, 'critical'),
-          };
-    }
-    // approaching
-    return admin
-      ? {
-          title: `${displayLabel} approaching cap`,
-          body: `You've used ${snap.used.toLocaleString()} of ${snap.limit.toLocaleString()} (${remaining.toLocaleString()} left).`,
-          cta: 'Upgrade',
-        }
-      : {
-          title: `${displayLabel} approaching cap`,
-          body: quotaMemberBody(displayLabel, 'approaching'),
-        };
-  }
-
-  const copy = $derived(getCopy(snapshot, isBillingAdmin));
+  const copy = $derived(quotaBannerCopy(snapshot, isBillingAdmin, displayLabel));
 
   function handleAction() {
     if (!snapshot) return;

package/dist/client/components/subscription/BridgeSubscriptionStatus.svelte

@@ -7,7 +7,16 @@
   `BridgeFlags`. Do NOT confuse with the older `<PlanSelector />` which
   consumes the Stripe-direct path via `subscriptionStore`.
 
-  No live push in v1 — that's US-3. Fetches once on mount.
+  TBP-762 — reads through the plugin's billing store (core/billing-store.ts):
+  it re-reads on a plan change, a renewed sign-in and tab focus, so the badge
+  follows the plan without a reload. A read that meets an out-of-date sign-in
+  renews it and retries; a failed read is retried once, and "Loading…" stays up
+  meanwhile. "Subscription unavailable" only after that; with `debug: true` the
+  reason is shown next to it.
+
+  `fresh` (the checkout success page): show "Loading…" until a read started
+  after this badge mounted has answered, so the plan it shows is the one the
+  checkout just bought, never the one the store held before.
 -->
 <script lang="ts">
   import { onDestroy, onMount } from 'svelte';
@@ -15,46 +24,53 @@
     useBridge,
     type BillingSubscriptionSnapshot,
   } from '@nebulr-group/bridge-auth-core';
-  import { getBridgeAuth } from '../../../core/bridge-instance.js';
+  import { ensureBillingState, refreshBillingState } from '../../../core/billing-store.js';
+  import { isLoggerDebug } from '../../../shared/logger.js';
+  import { subscriptionBadgeView } from './subscription-badge.js';
 
   interface Props {
     /** Optional class applied to the root span. */
     class?: string;
+    /** Wait for a read made after mount before showing a plan. */
+    fresh?: boolean;
   }
 
-  let { class: className = '' }: Props = $props();
+  let { class: className = '', fresh = false }: Props = $props();
 
   let snapshot = $state<BillingSubscriptionSnapshot>(useBridge().subscription.snapshot());
+  // "Loading…" until this badge's own read has answered when it has nothing to
+  // show yet (never a "No subscription" flash), or always on `fresh`.
+  // svelte-ignore state_referenced_locally
+  let awaiting = $state(fresh || snapshot.state === null);
   let unsubscribe: (() => void) | undefined;
+  const debug = isLoggerDebug();
 
   onMount(() => {
     unsubscribe = useBridge().subscription.subscribe((snap) => {
       snapshot = snap;
     });
-
-    const ctx = getBridgeAuth().getApiContext();
-    if (!ctx.accessToken) {
-      useBridge().subscription.setError('Not authenticated');
-      return;
-    }
-    useBridge().subscription.mount({
-      apiBaseUrl: ctx.apiBaseUrl,
-      accessToken: ctx.accessToken,
-      appId: ctx.appId,
+    const read = fresh ? refreshBillingState() : ensureBillingState();
+    void read.finally(() => {
+      awaiting = false;
     });
   });
 
   onDestroy(() => unsubscribe?.());
+
+  const view = $derived(subscriptionBadgeView(snapshot, awaiting, debug));
 </script>
 
-<span class={`bridge-subscription-status ${className}`}>
-  {#if snapshot.loading}
+<span class={`bridge-subscription-status ${className}`} data-state={view.kind}>
+  {#if view.kind === 'loading'}
     <span class="bss-loading">Loading…</span>
-  {:else if snapshot.error}
+  {:else if view.kind === 'error'}
     <span class="bss-error">Subscription unavailable</span>
-  {:else if snapshot.state}
-    <span class="bss-plan">{snapshot.state.plan.name}</span>
-    <span class={`bss-badge bss-badge-${snapshot.state.status}`}>{snapshot.state.status}</span>
+    {#if view.reason}
+      <span class="bss-error-reason" data-bridge-error-reason>({view.reason})</span>
+    {/if}
+  {:else if view.kind === 'plan'}
+    <span class="bss-plan">{view.name}</span>
+    <span class={`bss-badge bss-badge-${view.status}`}>{view.status}</span>
   {:else}
     <span class="bss-empty">No subscription</span>
   {/if}
@@ -110,7 +126,8 @@
     font-style: italic;
   }
 
-  .bss-error {
+  .bss-error,
+  .bss-error-reason {
     color: var(--bridge-alert-error-fg, #991b1b);
   }
 </style>

package/dist/client/components/subscription/BridgeSubscriptionStatus.svelte.d.ts

@@ -1,6 +1,8 @@
 interface Props {
     /** Optional class applied to the root span. */
     class?: string;
+    /** Wait for a read made after mount before showing a plan. */
+    fresh?: boolean;
 }
 declare const BridgeSubscriptionStatus: import("svelte").Component<Props, {}, "">;
 type BridgeSubscriptionStatus = ReturnType<typeof BridgeSubscriptionStatus>;

package/dist/client/components/subscription/Entitled.svelte

@@ -13,12 +13,15 @@
   optional `loading` snippet — so a cold start never flashes the upgrade prompt
   at a paying workspace, nor the paid feature at a free one.
 
-  The markup form of `$entitlements.can('analytics')`. Decoration only: the
-  backend's @RequireEntitlement is what refuses the request.
+  The markup form of `$entitlements.can('analytics')`. It reads the plan
+  directly, which is the exception: the standard gate is `<FeatureFlag key>`
+  with a flag ruled `bridge:billing.entitlement.<key> eq true`. In development
+  it logs a one-time note saying so (TBP-705).
 -->
 <script lang="ts">
   import type { Snippet } from 'svelte';
   import { entitlements } from '../../../core/entitlements.js';
+  import { noteDirectPlanCheck } from '../../../core/direct-plan-check-note.js';
 
   interface Props {
     /** The entitlement key, e.g. `'analytics'`. */
@@ -32,6 +35,12 @@
   }
 
   let { to, children, fallback, loading }: Props = $props();
+
+  // Runs before the first render, so this note — not the store's `can()` one —
+  // is the one a page using <Entitled> sees. Once per page load, so the first
+  // `to` is the one it names.
+  const note = () => noteDirectPlanCheck('entitled', to);
+  note();
 </script>
 
 {#if !$entitlements.ready}

package/dist/client/components/subscription/PlanSelector.svelte

@@ -2,8 +2,11 @@
   import type { Snippet } from 'svelte';
   import type { HTMLAttributes } from 'svelte/elements';
   import { onMount } from 'svelte';
+  import { goto } from '$app/navigation';
   import type { Plan, PriceOfferSdk } from '@nebulr-group/bridge-auth-core';
-  import { getBridgeAuth, loadSubscription, subscriptionStore } from '../../../core/bridge-instance.js';
+  import { ensureSubscription, getBridgeAuth, loadSubscription, subscriptionStore } from '../../../core/bridge-instance.js';
+  import { refreshBilling } from '../../../core/billing-store.js';
+  import { pickPlan } from './plan-pick.js';
   import { getConfig } from '../../stores/config.store.js';
   import Alert from '../sdk-auth/shared/Alert.svelte';
   import Spinner from '../sdk-auth/shared/Spinner.svelte';
@@ -157,12 +160,23 @@
   );
 
   onMount(() => {
-    // Only load if not already loaded
-    if (!$subscriptionStore.status && !$subscriptionStore.loading) {
-      loadSubscription();
-    }
+    // TBP-762 — read unless the billing store holds a read younger than 30 s;
+    // the store re-reads on plan changes, renewed sign-ins and tab focus.
+    void ensureSubscription();
   });
 
+  // TBP-762 — an empty plan list is not proof the app has none (the store has
+  // already asked twice): offer a retry instead of "No plans available".
+  let retrying = $state(false);
+  async function retryPlans(): Promise<void> {
+    retrying = true;
+    try {
+      await loadSubscription();
+    } finally {
+      retrying = false;
+    }
+  }
+
   // ── Plan-change confirmation (TBP-33) ─────────────────────────────────
   // Switching an existing subscriber's plan is instant (no Stripe checkout
   // page), so it needs an explicit confirm step. Free selection and the
@@ -197,7 +211,7 @@
     confirmError = null;
     try {
       await getBridgeAuth().changePlan(plan.key, price);
-      await loadSubscription();
+      await refreshBilling();
       confirmTarget = null;
       showSuccess(`You're now on ${plan.name} (${formatPrice(price)}).`);
       onSelect?.({ plan, price });
@@ -213,37 +227,30 @@
     picking = true;
     pickError = null;
     try {
-      if (price.amount === 0 && !plan.hasCost) {
-        // Free plan — select directly. TBP-275: guard on `!plan.hasCost` so a
-        // $0-base plan that carries METERED pricing is NOT treated as free —
-        // it falls through to checkout/changePlan below, capturing a payment
-        // method so per-unit overage can be billed (US-C). Without this guard a
-        // metered $0-base plan would hit selectFreePlan, which the backend now
-        // rejects ("has a cost — use the checkout endpoint instead").
-        await getBridgeAuth().selectFreePlan(plan.key);
-        await loadSubscription();
-        onSelect?.({ plan, price });
-      } else if (status?.paymentsEnabled) {
-        // Already has payment method — instant switch, so require an explicit
+      const outcome = await pickPlan(
+        plan,
+        price,
+        {
+          paymentsEnabled: !!status?.paymentsEnabled,
+          successRedirect,
+          cancelRedirect,
+          callbackBase: getConfig().callbackUrl ?? `${window.location.origin}/auth/oauth-callback`,
+          onSelect,
+        },
+        {
+          auth: getBridgeAuth(),
+          refresh: refreshBilling,
+          navigate: (url) => goto(url),
+          leave: (url) => {
+            window.location.href = url;
+          },
+        },
+      );
+      if (outcome === 'confirm') {
+        // Already has a payment method — instant switch, so require an explicit
         // confirmation (TBP-33). The actual changePlan runs in confirmPlanChange.
         confirmTarget = { plan, price };
         confirmError = null;
-      } else {
-        // Needs checkout — redirect to Stripe (or direct plan set when Stripe not configured)
-        const base = getConfig().callbackUrl ?? `${window.location.origin}/auth/oauth-callback`;
-        // Use {CHECKOUT_SESSION_ID} placeholder — Stripe substitutes it in-place,
-        // avoiding the double-? bug that occurs when Stripe appends ?session_id= to a URL that already has query params.
-        const successUrl = `${base}?stripe_success=1&session_id={CHECKOUT_SESSION_ID}&redirect=${encodeURIComponent(successRedirect)}`;
-        const cancelUrl  = `${base}?stripe_cancel=1&redirect=${encodeURIComponent(cancelRedirect)}`;
-        const session = await getBridgeAuth().startCheckout(plan.key, price, { successUrl, cancelUrl });
-        if (session.sessionId === null) {
-          // Stripe not configured — plan was set directly on the backend
-          await loadSubscription();
-          onSelect?.({ plan, price });
-        } else {
-          if (!session.checkoutUrl) throw new Error('Checkout session URL missing');
-          window.location.href = session.checkoutUrl;
-        }
       }
     } catch (err) {
       pickError = err instanceof Error ? err.message : 'Something went wrong';
@@ -305,7 +312,12 @@
       {#if emptyState}
         {@render emptyState()}
       {:else}
-        <p class="bridge-plan-empty">No plans available.</p>
+        <div class="bridge-plan-empty" data-bridge-plan-empty>
+          <p>The plans could not be loaded.</p>
+          <button type="button" class="bridge-btn-primary" onclick={retryPlans} disabled={retrying}>
+            {retrying ? 'Loading…' : 'Try again'}
+          </button>
+        </div>
       {/if}
     {:else if plans}
       {#if showIntervalTabs}