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

package/dist/client/BridgeBootstrap.js

@@ -3,8 +3,8 @@ import { redirect, isRedirect } from '@sveltejs/kit';
 import { get } from 'svelte/store';
 import { createRouteGuard } from '../auth/route-guard.js';
 import { getBridgeAuth, bridgeReadyStore, markReady, waitForBridge as _waitForBridge, } from '../core/bridge-instance.js';
+import { installBridgeAuthFetch } from '../core/bridge-runtime.js';
 import { useBridge } from '@nebulr-group/bridge-auth-core';
-import { featureFlags } from '../shared/feature-flag.js';
 import { logger } from '../shared/logger.js';
 import { bridgeConfig, getConfig } from './stores/config.store.js';
 export async function bridgeBootstrap(url, config, routeConfig = { rules: [], defaultAccess: 'protected' }, kitFetch) {
@@ -21,6 +21,11 @@ export async function bridgeBootstrap(url, config, routeConfig = { rules: [], de
     }
     // 1. Initialize configuration (synchronously) — this also calls initBridge()
     bridgeConfig.initConfig(finalConfig, routeConfig);
+    // 1b. Patch globalThis.fetch early so GraphQL/HTTP calls made in this load()
+    //     function (before any component mounts) already carry the Bearer token.
+    //     installBridgeAuthFetch() is idempotent — startBridgeRuntime() (onMount)
+    //     is a no-op when it finds the patch already in place.
+    installBridgeAuthFetch();
     // 1a. Unified callback handler — detects what is calling back and routes accordingly
     try {
         const resolvedCallbackUrl = getConfig().callbackUrl;
@@ -62,22 +67,15 @@ export async function bridgeBootstrap(url, config, routeConfig = { rules: [], de
                 }
             }
             else if (stripeSuccess && sessionId) {
-                // Stripe payment success — verify with bridge-api (server calls Stripe directly),
-                // then refresh tokens so the new JWT has shouldSelectPlan: false before redirect.
+                // Stripe payment success — auth-core's confirmStripeCheckout() verifies the session
+                // with bridge-api (server calls Stripe directly) and refreshes tokens so the new JWT
+                // has shouldSelectPlan: false before we redirect. It throws on a non-OK response or
+                // network error → we fall through to the payment-error redirect. (TBP-369: the HTTP +
+                // token-refresh logic now lives in auth-core so every plugin port can reuse it.)
                 logger.debug('[bridgeBootstrap] Stripe success callback — confirming with bridge-api');
                 const bridge = getBridgeAuth();
-                const ctx = bridge.getApiContext();
                 try {
-                    const res = await (kitFetch ?? fetch)(`${ctx.apiBaseUrl}/v1/account/stripe/confirm-checkout`, {
-                        method: 'POST',
-                        headers: { 'Content-Type': 'application/json' },
-                        body: JSON.stringify({ sessionId, appId: ctx.appId }),
-                    });
-                    if (!res.ok) {
-                        logger.warn('[bridgeBootstrap] confirm-checkout failed', res.status);
-                        redirect(303, getConfig().billing?.paymentErrorRoute ?? '/payment-error');
-                    }
-                    await bridge.refreshTokens();
+                    await bridge.confirmStripeCheckout(sessionId, kitFetch);
                     redirect(303, redirectTo);
                 }
                 catch (err) {
@@ -112,22 +110,19 @@ export async function bridgeBootstrap(url, config, routeConfig = { rules: [], de
     catch {
         // Non-fatal — stale tokens will be caught by route guard
     }
-    // 2b. Paywall redirect — fires before any page renders. Reads shouldSelectPlan
-    //     and paymentsAutoRedirect from getSubscriptionStatus(). Only redirects when:
+    // 2b. Paywall redirect — fires before any page renders. The framework-agnostic
+    //     decision (authenticated + shouldSelectPlan + not opted out via
+    //     paymentsAutoRedirect) now lives in auth-core's shouldRedirectToPaywall()
+    //     (TBP-369). We only own the route/config guards here:
     //     - billing.paywallRoute is configured
     //     - the current path is not already the paywall route (no redirect loop)
-    //     - the tenant is authenticated but has not selected a plan
-    //     - the app has not opted out via paymentsAutoRedirect: false
     try {
         const paywallRoute = getConfig().billing?.paywallRoute;
         if (paywallRoute && url.pathname !== paywallRoute) {
             const bridge = getBridgeAuth();
-            if (bridge.isAuthenticated()) {
-                const status = await bridge.getSubscriptionStatus();
-                if (status?.shouldSelectPlan === true && status?.paymentsAutoRedirect !== false) {
-                    logger.debug('[bridgeBootstrap] paywall redirect', paywallRoute);
-                    redirect(303, paywallRoute);
-                }
+            if (await bridge.shouldRedirectToPaywall()) {
+                logger.debug('[bridgeBootstrap] paywall redirect', paywallRoute);
+                redirect(303, paywallRoute);
             }
         }
     }
@@ -152,11 +147,17 @@ export async function bridgeBootstrap(url, config, routeConfig = { rules: [], de
     catch {
         // Non-fatal — gate fails open; the notice hydrates lazily on first render.
     }
-    // 3. Fire flag fetch without awaiting so GQL queries can start in parallel.
-    //    The flagsReady promise is passed to the guard and returned to callers
-    //    so routes that need flags can still await before rendering.
-    //    Swallow errors — feature flag failures should never crash the bootstrap.
-    const flagsReady = featureFlags.refresh().catch((err) => {
+    // 3. Warm the route-guard's flag cache without awaiting so GQL queries can
+    //    start in parallel. `loadFeatureFlags()` populates the same auth-core
+    //    FeatureFlagService the route guard evaluates `featureFlag` rules
+    //    against; the flagsReady promise is passed to the guard and returned to
+    //    callers so routes that gate on flags can await before rendering.
+    //    (Component/programmatic flag reads use FF 2.0 `useFlag` / <FeatureFlag>.)
+    //    Errors are logged, never thrown — flag failures must not crash bootstrap.
+    const flagsReady = getBridgeAuth()
+        .loadFeatureFlags()
+        .then(() => { })
+        .catch((err) => {
         logger.warn('[bridgeBootstrap] Feature flags failed to load:', err);
     });
     // 4. Handle route guarding and redirects

package/dist/client/BridgeBootstrap.svelte

@@ -1,8 +1,15 @@
 <script lang="ts">
   import { beforeNavigate, goto } from '$app/navigation';
+  import { page } from '$app/stores';
   import { onMount, onDestroy } from 'svelte';
   import { createRouteGuard } from '../auth/route-guard.js';
-  import { getBridgeAuth } from '../core/bridge-instance.js';
+  import {
+    getBridgeAuth,
+    isAuthenticated,
+    subscriptionStore,
+    loadSubscription,
+    ensureAppConfig,
+  } from '../core/bridge-instance.js';
   import { bridge as bridgeSurface } from '../core/bridge.js';
   import { setBridgeContext } from '../core/use-bridge.js';
   import { getConfig } from './stores/config.store.js';
@@ -11,7 +18,6 @@
     stopBridgeRuntime,
     type StartBridgeRuntimeOptions,
   } from '../core/bridge-runtime.js';
-  import { loadSubscription, ensureAppConfig } from '../core/bridge-instance.js';
 
   // Props: optional `runtime` overrides for advanced/debug use (websocketFactory,
   // reconnect overrides, etc.); `onBootstrapComplete` callback fires after the
@@ -30,6 +36,42 @@
 
   const guard = createRouteGuard();
 
+  // Reactive paywall enforcement.
+  //
+  // The one-shot redirect in bridgeBootstrap() (load) only fires on the very
+  // first load — it short-circuits on every later navigation (bridgeReadyStore),
+  // so it misses the post-login case where auth + subscription state resolve a
+  // beat AFTER load() ran. This guard owns correctness: it actively loads the
+  // subscription once known-authenticated, then redirects reactively whenever
+  // `shouldSelectPlan` resolves true. Same data source as <BridgePaywall>, so the
+  // overlay and the redirect agree. The load() redirect remains a no-flash
+  // fast-path for direct loads/refreshes only.
+  $effect(() => {
+    const paywallRoute = getConfig().billing?.paywallRoute;
+    if (!paywallRoute || !$isAuthenticated) return;
+
+    const { status, loading, error } = $subscriptionStore;
+
+    // Status unknown → trigger a single load. Guarding on `!error` avoids a
+    // tight refetch loop on persistent failure (fail-pending, not fail-open);
+    // a workspace switch resets the store and re-attempts.
+    if (!status && !loading && !error) {
+      loadSubscription().catch(() => { /* surfaced via store.error */ });
+      return;
+    }
+
+    // Status known → enforce. `$page.url.pathname` makes this re-run on
+    // navigation too, so manual nav to a protected page while plan-less is
+    // also caught. Path guard prevents a redirect loop on the paywall itself.
+    if (
+      status?.shouldSelectPlan === true &&
+      status?.paymentsAutoRedirect !== false &&
+      $page.url.pathname !== paywallRoute
+    ) {
+      goto(paywallRoute);
+    }
+  });
+
   async function handleRoute(pathname: string, cancel?: () => void) {
     const decision = await guard.getNavigationDecision(pathname);
     if (decision.type === 'login') {

package/dist/client/components/sdk-auth/ForgotPassword.svelte

@@ -10,6 +10,11 @@
     onComplete?: () => void;
     onError?: (error: Error) => void;
     loginHref?: string;
+    /**
+     * Override the built-in heading ("Set new password" / "Reset your password").
+     * Pass `null`/`''` to render no heading and use your own page title.
+     */
+    heading?: string | null;
   }
 
   let {
@@ -17,6 +22,7 @@
     onComplete,
     onError,
     loginHref = '/login',
+    heading = undefined,
     class: className,
     style,
     ...rest
@@ -33,6 +39,14 @@
 
   const isSetMode = $derived(!!token);
 
+  // In a success state ("Password set" / the email-sent alert) the form heading
+  // is redundant, so suppress it. Otherwise use the override (if provided) or
+  // the built-in, state-appropriate heading.
+  const builtInHeading = $derived(isSetMode ? 'Set new password' : 'Reset your password');
+  const wrapperHeading = $derived(
+    passwordReset || emailSent ? null : heading !== undefined ? heading : builtInHeading,
+  );
+
   async function handleSendLink() {
     if (loading) return;
     error = null;
@@ -77,7 +91,7 @@
 </script>
 
 <AuthFormWrapper
-  heading={isSetMode ? 'Set new password' : 'Reset your password'}
+  heading={wrapperHeading}
   class={className}
   {style}
   {...rest}

package/dist/client/components/sdk-auth/ForgotPassword.svelte.d.ts

@@ -4,6 +4,11 @@ interface Props extends HTMLAttributes<HTMLDivElement> {
     onComplete?: () => void;
     onError?: (error: Error) => void;
     loginHref?: string;
+    /**
+     * Override the built-in heading ("Set new password" / "Reset your password").
+     * Pass `null`/`''` to render no heading and use your own page title.
+     */
+    heading?: string | null;
 }
 declare const ForgotPassword: import("svelte").Component<Props, {}, "">;
 type ForgotPassword = ReturnType<typeof ForgotPassword>;

package/dist/client/components/sdk-auth/LoginForm.svelte

@@ -219,7 +219,7 @@
 
 <!-- Inline forgot password -->
 {:else if step === 'forgot-password'}
-  <AuthFormWrapper heading="Reset your password">
+  <AuthFormWrapper heading={fpEmailSent ? null : 'Reset your password'}>
     {#if error}
       <Alert variant="error">{error}</Alert>
     {/if}
@@ -257,7 +257,7 @@
 
 <!-- Inline magic link -->
 {:else if step === 'magic-link'}
-  <AuthFormWrapper heading="Sign in with email link">
+  <AuthFormWrapper heading={mlSent ? null : 'Sign in with email link'}>
     {#if error}
       <Alert variant="error">{error}</Alert>
     {/if}

package/dist/client/components/sdk-auth/MagicLink.svelte

@@ -9,12 +9,15 @@
     onSent?: () => void;
     onError?: (error: Error) => void;
     loginHref?: string;
+    /** Heading text. Pass `null`/`''` to render no heading and use your own page title. */
+    heading?: string | null;
   }
 
   let {
     onSent,
     onError,
     loginHref = '/login',
+    heading = 'Sign in with email link',
     class: className,
     style,
     ...rest
@@ -51,7 +54,7 @@
   }
 </script>
 
-<AuthFormWrapper heading="Sign in with email link" class={className} {style} {...rest}>
+<AuthFormWrapper heading={sent ? null : heading} class={className} {style} {...rest}>
   {#if error}
     <Alert variant="error">{error}</Alert>
   {/if}

package/dist/client/components/sdk-auth/MagicLink.svelte.d.ts

@@ -3,6 +3,8 @@ interface Props extends HTMLAttributes<HTMLDivElement> {
     onSent?: () => void;
     onError?: (error: Error) => void;
     loginHref?: string;
+    /** Heading text. Pass `null`/`''` to render no heading and use your own page title. */
+    heading?: string | null;
 }
 declare const MagicLink: import("svelte").Component<Props, {}, "">;
 type MagicLink = ReturnType<typeof MagicLink>;

package/dist/client/components/sdk-auth/PasskeyLogin.svelte

@@ -40,7 +40,7 @@
 
       let authResponse: any;
       if (typeof window !== 'undefined' && (window as any).__simpleWebAuthn?.startAuthentication) {
-        authResponse = await (window as any).__simpleWebAuthn.startAuthentication(options, autofill);
+        authResponse = await (window as any).__simpleWebAuthn.startAuthentication({ optionsJSON: options, useBrowserAutofill: autofill });
       } else {
         // @ts-ignore — @simplewebauthn/browser is an optional peer dependency
         const mod = await import('@simplewebauthn/browser');

package/dist/client/components/sdk-auth/PasskeySetup.svelte

@@ -54,7 +54,7 @@
 
       let regResponse: any;
       if (typeof window !== 'undefined' && (window as any).__simpleWebAuthn?.startRegistration) {
-        regResponse = await (window as any).__simpleWebAuthn.startRegistration(options);
+        regResponse = await (window as any).__simpleWebAuthn.startRegistration({ optionsJSON: options });
       } else {
         // @ts-ignore — @simplewebauthn/browser is an optional peer dependency
         const mod = await import('@simplewebauthn/browser');

package/dist/client/components/sdk-auth/SignupForm.svelte

@@ -13,7 +13,14 @@
     showLoginLink?: boolean;
     /** Override login page URL. Default: derived from BridgeConfig loginRoute. */
     loginHref?: string | undefined;
-    heading?: string;
+    /** Heading text. Pass `null`/`''` to render no heading and use your own page title. */
+    heading?: string | null;
+    /** TBP-36 — preselected plan applied at tenant creation (from ?signupPlan= links). */
+    plan?: string | null;
+    /** TBP-36 — currency of the preselected plan's price offer. */
+    currency?: string | null;
+    /** TBP-36 — recurrence interval of the preselected plan's price offer. */
+    recurrenceInterval?: string | null;
     footer?: Snippet;
   }
 
@@ -23,6 +30,9 @@
     showLoginLink = true,
     loginHref = undefined,
     heading = 'Create your account',
+    plan = null,
+    currency = null,
+    recurrenceInterval = null,
     footer,
     class: className,
     style,
@@ -43,7 +53,11 @@
     error = null;
     loading = true;
     try {
-      await getBridgeAuth().signup(email, firstName, lastName);
+      await getBridgeAuth().signup(email, firstName, lastName, plan ? {
+        plan,
+        currency: currency ?? undefined,
+        recurrenceInterval: recurrenceInterval ?? undefined,
+      } : undefined);
       success = true;
       onSignup?.();
     } catch (err: any) {
@@ -55,7 +69,9 @@
   }
 </script>
 
-<AuthFormWrapper {heading} class={className} {style} {...rest}>
+<!-- In the success state, the "Check your email" heading below is the title,
+     so suppress the form heading to avoid two stacked headings. -->
+<AuthFormWrapper heading={success ? null : heading} class={className} {style} {...rest}>
   {#if success}
     <h2 class="bridge-success-heading">Check your email</h2>
     <p class="bridge-step-desc">We sent a verification link to <strong>{email}</strong>. Check your inbox to activate your account.</p>

package/dist/client/components/sdk-auth/SignupForm.svelte.d.ts

@@ -6,7 +6,14 @@ interface Props extends HTMLAttributes<HTMLDivElement> {
     showLoginLink?: boolean;
     /** Override login page URL. Default: derived from BridgeConfig loginRoute. */
     loginHref?: string | undefined;
-    heading?: string;
+    /** Heading text. Pass `null`/`''` to render no heading and use your own page title. */
+    heading?: string | null;
+    /** TBP-36 — preselected plan applied at tenant creation (from ?signupPlan= links). */
+    plan?: string | null;
+    /** TBP-36 — currency of the preselected plan's price offer. */
+    currency?: string | null;
+    /** TBP-36 — recurrence interval of the preselected plan's price offer. */
+    recurrenceInterval?: string | null;
     footer?: Snippet;
 }
 declare const SignupForm: import("svelte").Component<Props, {}, "">;

package/dist/client/components/sdk-auth/shared/AuthFormWrapper.svelte

@@ -3,7 +3,8 @@
   import type { HTMLAttributes } from 'svelte/elements';
 
   interface Props extends HTMLAttributes<HTMLDivElement> {
-    heading?: string;
+    /** Heading text. Pass `null` or `''` to render no heading. */
+    heading?: string | null;
     headingSnippet?: Snippet;
     children?: Snippet;
   }

package/dist/client/components/sdk-auth/shared/AuthFormWrapper.svelte.d.ts

@@ -1,7 +1,8 @@
 import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 interface Props extends HTMLAttributes<HTMLDivElement> {
-    heading?: string;
+    /** Heading text. Pass `null` or `''` to render no heading. */
+    heading?: string | null;
     headingSnippet?: Snippet;
     children?: Snippet;
 }

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 { getConfig } from '../../stores/config.store.js';
 
   type Chassis = 'bar' | 'rail' | 'card';
 
@@ -40,6 +41,9 @@
     class?: string;
     /** Override the default CTA click handler (links to billing surface). */
     onActionClick?: (state: BillingNoticeState) => void;
+    /** CTA destination for this instance. Overrides `billing.manageRoute`
+     *  config; `onActionClick` takes precedence over both. */
+    actionHref?: string;
   }
 
   let {
@@ -47,14 +51,15 @@
     mode = 'soft',
     class: className = '',
     onActionClick,
+    actionHref,
   }: Props = $props();
 
   let snapshot = $state<BillingSubscriptionSnapshot>(useBridge().subscription.snapshot());
   let unsubscribe: (() => void) | undefined;
 
-  // Admin/member variant — read from existing auth context. The exact field
-  // name varies by SDK; we look up `billing` privilege on the current user.
-  // Defaults to non-admin if unavailable.
+  // Admin/member variant. v1 policy: workspace owner only, via
+  // canManageBilling() (immutable OWNER role key). Defaults to non-admin if
+  // unavailable.
   let isBillingAdmin = $state(false);
 
   onMount(() => {
@@ -65,15 +70,7 @@
     const auth = getBridgeAuth();
     const ctx = auth.getApiContext();
     if (ctx.accessToken) {
-      // Best-effort role read. Existing auth-core role probing varies by app;
-      // defensive cast so the component never crashes on missing fields.
-      const tokenManager = (auth as unknown as { tokenManager?: { getTokens?: () => { accessToken?: string } } }).tokenManager;
-      void tokenManager; // intentionally unused — placeholder until role API is finalized
-      // For US-5 default: assume admin if a JWT is present. Subsequent
-      // stories will read the exact privilege claim. Keeping permissive so
-      // the CTA shows by default; member variant lands when the role check
-      // is wired through.
-      isBillingAdmin = true;
+      isBillingAdmin = auth.canManageBilling();
     }
 
     if (!ctx.accessToken) {
@@ -202,11 +199,16 @@
       onActionClick(noticeState);
       return;
     }
-    // Default: open the existing billing surface. The exact destination
-    // depends on app configuration — for now, navigate to /billing on the
-    // current origin. Apps can override via `onActionClick`.
+    // Default: open the app's billing surface. Destination priority:
+    // `actionHref` prop → `billing.manageRoute` config → '/billing'.
     if (typeof window !== 'undefined') {
-      window.location.href = '/billing';
+      let manageRoute: string | undefined;
+      try {
+        manageRoute = getConfig().billing?.manageRoute;
+      } catch {
+        // Config not initialized — fall through to the default.
+      }
+      window.location.href = actionHref ?? manageRoute ?? '/billing';
     }
   }
 </script>

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

@@ -13,6 +13,9 @@ interface Props {
     class?: string;
     /** Override the default CTA click handler (links to billing surface). */
     onActionClick?: (state: BillingNoticeState) => void;
+    /** CTA destination for this instance. Overrides `billing.manageRoute`
+     *  config; `onActionClick` takes precedence over both. */
+    actionHref?: string;
 }
 declare const BridgeBillingNotice: import("svelte").Component<Props, {}, "">;
 type BridgeBillingNotice = ReturnType<typeof BridgeBillingNotice>;

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

@@ -27,6 +27,7 @@
     type QuotaSnapshot,
   } from '@nebulr-group/bridge-auth-core';
   import { getBridgeAuth } from '../../../core/bridge-instance.js';
+  import { getConfig } from '../../stores/config.store.js';
 
   type Chassis = 'rail';
   type Severity = 'warn' | 'critical';
@@ -43,6 +44,9 @@
     class?: string;
     /** Override the default Upgrade CTA click handler. */
     onActionClick?: (snap: QuotaSnapshot) => void;
+    /** CTA destination for this instance. Overrides `billing.manageRoute`
+     *  config; `onActionClick` takes precedence over both. */
+    actionHref?: string;
     /**
      * Optional display label override. Defaults to the snapshot's `.label`
      * (raw metric key for US-11; the framework wrapper will eventually
@@ -56,6 +60,7 @@
     chassis = 'rail',
     class: className = '',
     onActionClick,
+    actionHref,
     label,
   }: Props = $props();
 
@@ -64,9 +69,8 @@
   let snapshot = $state<QuotaSnapshot | undefined>(useBridge().quota(metric));
   let unsubscribe: (() => void) | undefined;
 
-  // Role variant mirrors BridgeBillingNotice: any authenticated user is
-  // treated as a billing admin for US-11 until the role/privilege API is
-  // finalized. Member variant lands when the role probe is wired through.
+  // Role variant mirrors BridgeBillingNotice: CTA only for the workspace
+  // owner (v1 canManageBilling() policy). Member variant renders otherwise.
   let isBillingAdmin = $state(false);
 
   onMount(() => {
@@ -78,11 +82,7 @@
     snapshot = useBridge().quota(metric);
 
     try {
-      const auth = getBridgeAuth();
-      const ctx = auth.getApiContext();
-      if (ctx.accessToken) {
-        isBillingAdmin = true;
-      }
+      isBillingAdmin = getBridgeAuth().canManageBilling();
     } catch {
       // No BridgeAuth instance — render the member variant.
     }
@@ -96,12 +96,28 @@
   });
 
   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.used > snapshot.limit : false,
+    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)),
   );
-  const visible = $derived(snapshot !== undefined && warningLevel !== null);
+  // Metered never blocks, so it never renders as 'critical' — it's informational.
   const severity = $derived<Severity>(
-    warningLevel === 'critical' || overCap ? 'critical' : 'warn',
+    isMetered
+      ? 'warn'
+      : warningLevel === 'critical' || overCap
+        ? 'critical'
+        : 'warn',
   );
   const displayLabel = $derived(label ?? snapshot?.label ?? metric);
   const percent = $derived(
@@ -109,13 +125,58 @@
       ? Math.min(100, Math.round((snapshot.used / snapshot.limit) * 100))
       : 0,
   );
+  // 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: '' };
-    const over = snap.used > snap.limit;
+
+    // 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
@@ -162,8 +223,16 @@
       onActionClick(snapshot);
       return;
     }
+    // Destination priority: `actionHref` prop → `billing.manageRoute` config
+    // → '/billing'.
     if (typeof window !== 'undefined') {
-      window.location.href = '/billing';
+      let manageRoute: string | undefined;
+      try {
+        manageRoute = getConfig().billing?.manageRoute;
+      } catch {
+        // Config not initialized — fall through to the default.
+      }
+      window.location.href = actionHref ?? manageRoute ?? '/billing';
     }
   }
 </script>
@@ -178,9 +247,11 @@
     <div class="bqb-content">
       <strong class="bqb-title">{copy.title}</strong>
       <span class="bqb-body">{copy.body}</span>
-      <div class="bqb-meter" aria-hidden="true">
-        <div class="bqb-meter-fill" style={`width: ${Math.min(100, percent)}%`}></div>
-      </div>
+      {#if showMeter}
+        <div class="bqb-meter" aria-hidden="true">
+          <div class="bqb-meter-fill" style={`width: ${Math.min(100, percent)}%`}></div>
+        </div>
+      {/if}
     </div>
     {#if copy.cta && isBillingAdmin}
       <button type="button" class="bqb-cta" onclick={handleAction}>{copy.cta}</button>