@nebulr-group/bridge-svelte 0.9.0-beta.4 → 0.9.0-beta.6

package/dist/auth/route-guard.d.ts

@@ -1,11 +1,19 @@
 import type { NavigationDecision } from '@nebulr-group/bridge-auth-core';
 export type { FlagRequirement, NavigationDecision, RouteGuard, RouteGuardConfig, RouteRule } from '@nebulr-group/bridge-auth-core';
+/** TBP-756 — a route restriction and, for a feature flag, why. */
+export interface Restriction {
+    to: string;
+    reason?: 'plan' | 'permission' | 'off' | 'rule' | 'rollout';
+    flag?: string;
+    feature?: string;
+}
 export declare function createRouteGuard(flagsReady?: Promise<void>): {
     checkRouteRestrictions(pathname: string): Promise<string | null>;
     getNavigationDecision(pathname: string, attempted?: string): Promise<NavigationDecision>;
     isPublicRoute(pathname: string): boolean;
     isProtectedRoute(pathname: string): boolean;
     shouldRedirectToLogin(pathname: string): boolean;
+    checkRouteRestriction(pathname: string): Promise<import("@nebulr-group/bridge-auth-core").RouteRestriction | null>;
     getLoginRedirect(): string;
     resolveReturnTo(attempted: string | null | undefined): string | null;
 };

package/dist/auth/route-guard.js

@@ -35,14 +35,24 @@ export function createRouteGuard(flagsReady) {
         for (let attempt = 1;; attempt++) {
             await settleAuthorizationChange(deadline);
             const generation = guardCacheGeneration();
-            const redirectTo = await guard.checkRouteRestrictions(pathname);
+            const restriction = await readRestriction(pathname);
             if (generation === guardCacheGeneration())
-                return redirectTo;
+                return restriction;
             dropFlagCache();
             if (attempt >= MAX_FRESH_READS)
-                return redirectTo;
+                return restriction;
         }
     }
+    // TBP-756 — the restriction with its reason, from an auth-core that reports
+    // one; an older auth-core gives the bare redirect target.
+    async function readRestriction(pathname) {
+        const withReason = guard
+            .checkRouteRestriction;
+        if (typeof withReason === 'function')
+            return withReason.call(guard, pathname);
+        const to = await guard.checkRouteRestrictions(pathname);
+        return to ? { to } : null;
+    }
     function loginDecision(pathname, attempted) {
         // TBP-629 — the attempted target (path + query) rides along on every
         // login decision, including the fail-closed ones below.
@@ -107,7 +117,7 @@ export function createRouteGuard(flagsReady) {
         async checkRouteRestrictions(pathname) {
             const deadline = Date.now() + AUTHORIZATION_CHANGE_WAIT_MS;
             await flagsReady;
-            return checkRestrictionsFresh(pathname, deadline);
+            return (await checkRestrictionsFresh(pathname, deadline))?.to ?? null;
         },
         async getNavigationDecision(pathname, attempted) {
             // TBP-654 — one bound for the whole decision, however many reads it takes.
@@ -124,9 +134,11 @@ export function createRouteGuard(flagsReady) {
                     return loginDecision(pathname, attempted);
                 }
                 await flagsReady;
-                const redirectTo = await checkRestrictionsFresh(pathname, deadline);
-                if (redirectTo) {
-                    return { type: 'redirect', to: redirectTo };
+                const restriction = await checkRestrictionsFresh(pathname, deadline);
+                if (restriction) {
+                    // TBP-756 — `reason: 'plan'` rides along so the adapter opens the
+                    // upgrade dialog; everything else is the plain redirect it was.
+                    return { type: 'redirect', ...restriction };
                 }
                 return { type: 'allow' };
             }

package/dist/client/BridgeBootstrap.js

@@ -1,5 +1,6 @@
 // src/lib/bridge/bootstrap.ts
 import { error, redirect, isRedirect } from '@sveltejs/kit';
+import { openFeatureUpgrade } from '../core/feature-upgrade.js';
 import { get } from 'svelte/store';
 import { createRouteGuard } from '../auth/route-guard.js';
 import { dropFlagCache, guardCacheGeneration } from '../auth/guard-cache.js';
@@ -431,7 +432,25 @@ async function enforceRouteGuard(url, flagsReady) {
         stashReturnTo(decision.returnTo);
         redirect(303, bridge.createLoginUrl());
     }
-    if (decision.type === 'redirect' && url.pathname !== decision.to) {
-        redirect(303, decision.to);
+    if (decision.type === 'redirect') {
+        upgradeForPlanDecision(url, decision);
+        if (url.pathname !== decision.to)
+            redirect(303, decision.to);
     }
 }
+/**
+ * TBP-756 — a route whose feature flag is off because of the plan opens the
+ * upgrade dialog (the owner case "reaching a gated page"). On a client-side
+ * navigation the visitor stays on the page they came from (the browser still
+ * shows it while the target loads); on a first load there is no such page, so
+ * they go to the rule's `redirectTo` first and the dialog opens there.
+ * Server-side there is no dialog to open: the plain redirect stands.
+ */
+function upgradeForPlanDecision(url, decision) {
+    if (decision.reason !== 'plan' || typeof window === 'undefined')
+        return;
+    openFeatureUpgrade({ flag: decision.flag, feature: decision.feature });
+    const here = window.location;
+    if (here.pathname !== url.pathname)
+        redirect(303, `${here.pathname}${here.search}`);
+}

package/dist/client/BridgeBootstrap.svelte

@@ -26,6 +26,7 @@
   import RealtimeDevBadge from './components/developer/RealtimeDevBadge.svelte';
   import BridgeUpgradeDialog from './components/subscription/BridgeUpgradeDialog.svelte';
   import { dismissQuotaRefusal, quotaRefusal } from '../core/quota-refusal.js';
+  import { dismissFeatureUpgrade, featureUpgrade, openFeatureUpgrade } from '../core/feature-upgrade.js';
   import { resolveUpgradeDialog, upgradeHrefFor } from './upgrade-dialog.js';
   import { isBillingAdmin } from './billing-role.js';
 
@@ -54,9 +55,26 @@
   })();
   const upgradeDialog = resolveUpgradeDialog(billingConfig);
   const UpgradeDialog = upgradeDialog === 'default' ? BridgeUpgradeDialog : upgradeDialog;
-  const upgradeHref = $derived(upgradeHrefFor($quotaRefusal, billingConfig));
+  // TBP-756 — the same dialog in its feature variant: a plan-gated route, a
+  // <FeatureFlag> upgrade click, or a backend's 402 FEATURE_NOT_IN_PLAN. A plan
+  // limit refusal wins when both are pending.
+  const upgradeHref = $derived(upgradeHrefFor($quotaRefusal ?? $featureUpgrade, billingConfig));
   // Re-read for every refusal: the same owner rule as <BridgeQuotaBanner>.
-  const canUpgrade = $derived($quotaRefusal ? isBillingAdmin() : false);
+  const canUpgrade = $derived($quotaRefusal || $featureUpgrade ? isBillingAdmin() : false);
+  const upgradeFeature = $derived(
+    $quotaRefusal ? null : ($featureUpgrade ? ($featureUpgrade.feature ?? $featureUpgrade.flag ?? '') : null),
+  );
+  // TBP-755/756 — the feature variant names the plans that include the
+  // feature, from the plan list. Load it once when that variant opens.
+  $effect(() => {
+    if (!$featureUpgrade || !$isAuthenticated) return;
+    const { plans, loading, error } = $subscriptionStore;
+    if (!plans && !loading && !error) loadSubscription().catch(() => { /* the dialog still opens, without plan names */ });
+  });
+  function closeUpgradeDialog(): void {
+    dismissQuotaRefusal();
+    dismissFeatureUpgrade();
+  }
 
   // Props: optional `runtime` overrides for advanced/debug use (websocketFactory,
   // reconnect overrides, etc.); `onBootstrapComplete` callback fires after the
@@ -170,6 +188,18 @@
       }
       return;
     }
+    // TBP-756 — a plan-gated route opens the upgrade dialog instead of
+    // silently bouncing. A navigation is handled by the route's load
+    // (bridgeBootstrap), which keeps the visitor where they were; here only the
+    // re-check of the page they are already on is left: it takes them to the
+    // rule's redirectTo (client-side, so the dialog survives) and opens it.
+    if (decision.type === 'redirect' && (decision as { reason?: string }).reason === 'plan') {
+      if (cancel) return;
+      const { flag, feature } = decision as { flag?: string; feature?: string };
+      openFeatureUpgrade({ flag, feature });
+      if (window.location.pathname !== decision.to) await goto(decision.to);
+      return;
+    }
     if (decision.type === 'redirect' && window.location.pathname !== decision.to) {
       if (cancel) cancel();
       window.location.href = decision.to;
@@ -283,7 +313,7 @@
 <RealtimeDevBadge enabled={devBadgeEnabled} />
 
 {#if UpgradeDialog}
-  <UpgradeDialog refusal={$quotaRefusal} {upgradeHref} {canUpgrade} onclose={dismissQuotaRefusal} />
+  <UpgradeDialog refusal={$quotaRefusal} {upgradeHref} {canUpgrade} onclose={closeUpgradeDialog} feature={upgradeFeature} plans={$subscriptionStore.plans} />
 {/if}
 
 {#if runtimeAttached && $bridgeReadyStore}

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

@@ -11,22 +11,36 @@
   and receives the same props.
 
   Decoration only: the backend already refused the write. This explains why.
+
+  TBP-756 — with no refusal and a `feature` set, it opens in its feature
+  variant ("This feature isn't on your plan", naming the plans that include
+  it). BridgeBootstrap sets `feature` only after the person did something
+  gated; a page that merely renders a hidden feature never opens it.
 -->
 <script lang="ts">
   import type { BridgeUpgradeDialogProps } from '../../../shared/types/config.js';
   import { quotaMemberBody } from '../../billing-role.js';
+  import { plansIncludingFeature } from '../../upgrade-dialog.js';
 
-  let { refusal, upgradeHref, canUpgrade, onclose }: BridgeUpgradeDialogProps = $props();
+  let { refusal, upgradeHref, canUpgrade, onclose, feature = null, plans = null }: BridgeUpgradeDialogProps = $props();
 
   let dialogEl: HTMLDialogElement | undefined = $state();
 
+  // TBP-756 — the feature variant: no plan-limit refusal, but a feature the
+  // plan does not include (a plan-gated route, a <FeatureFlag> upgrade click,
+  // a backend's 402 FEATURE_NOT_IN_PLAN).
+  const featureVariant = $derived(!refusal && feature != null);
+  const isOpen = $derived(!!refusal || featureVariant);
+
   $effect(() => {
     if (!dialogEl) return;
-    if (refusal && !dialogEl.open) dialogEl.showModal();
-    else if (!refusal && dialogEl.open) dialogEl.close();
+    if (isOpen && !dialogEl.open) dialogEl.showModal();
+    else if (!isOpen && dialogEl.open) dialogEl.close();
   });
 
   const hasNumbers = $derived(refusal?.used != null && refusal?.limit != null);
+  // TBP-755 — the plans that include the missing feature, from the plan list.
+  const includedIn = $derived(plansIncludingFeature(plans, feature));
 </script>
 
 <dialog
@@ -34,12 +48,40 @@
   class="bridge-team-dialog bridge-upgrade-dialog"
   data-bridge-upgrade-dialog
   data-metric={refusal?.metric}
+  data-variant={featureVariant ? 'feature' : refusal ? 'limit' : undefined}
+  data-feature={featureVariant ? feature : undefined}
   aria-labelledby="bridge-upgrade-dialog-title"
   onclose={() => {
-    if (refusal) onclose();
+    if (isOpen) onclose();
   }}
 >
-  {#if refusal}
+  {#if featureVariant}
+    <div class="bridge-team-dialog-content">
+      <h3 id="bridge-upgrade-dialog-title" class="bridge-team-dialog-title">This feature isn't on your plan</h3>
+      <p class="bridge-team-dialog-message" data-bridge-upgrade-dialog-message data-variant={canUpgrade ? 'admin' : 'member'}>
+        {#if canUpgrade}
+          Upgrade the plan to use it.
+        {:else}
+          Ask the workspace owner to upgrade the plan to use it.
+        {/if}
+      </p>
+      {#if includedIn.length > 0}
+        <p class="bridge-team-dialog-message" data-bridge-upgrade-dialog-included-in>
+          Included in: {includedIn.join(', ')}
+        </p>
+      {/if}
+      <div class="bridge-team-dialog-actions">
+        {#if canUpgrade}
+          <button type="button" class="bridge-btn bridge-btn-secondary" onclick={() => onclose()}>Not now</button>
+          <a class="bridge-btn bridge-btn-primary" href={upgradeHref} data-bridge-upgrade-dialog-cta onclick={() => onclose()}>
+            Upgrade plan
+          </a>
+        {:else}
+          <button type="button" class="bridge-btn bridge-btn-primary" onclick={() => onclose()}>OK</button>
+        {/if}
+      </div>
+    </div>
+  {:else if refusal}
     <div class="bridge-team-dialog-content">
       <h3 id="bridge-upgrade-dialog-title" class="bridge-team-dialog-title">You've reached your plan's limit</h3>
       <p class="bridge-team-dialog-message" data-bridge-upgrade-dialog-message data-variant={canUpgrade ? 'admin' : 'member'}>
@@ -54,6 +96,11 @@
         {/if}
         {#if canUpgrade}Upgrade the plan to keep going.{/if}
       </p>
+      {#if includedIn.length > 0}
+        <p class="bridge-team-dialog-message" data-bridge-upgrade-dialog-included-in>
+          Included in: {includedIn.join(', ')}
+        </p>
+      {/if}
       <div class="bridge-team-dialog-actions">
         {#if canUpgrade}
           <button type="button" class="bridge-btn bridge-btn-secondary" onclick={() => onclose()}>Not now</button>

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

@@ -126,6 +126,12 @@
     [...(plans ?? [])].sort((a, b) => minAmount(a) - minAmount(b)),
   );
 
+  // TBP-755 — the features the plan includes; the same list the upgrade dialog
+  // reads. Structural: an older auth-core `Plan` type has no `features`.
+  function planFeatures(plan: Plan): ReadonlyArray<{ key: string; name: string }> {
+    return (plan as Plan & { features?: ReadonlyArray<{ key: string; name: string }> }).features ?? [];
+  }
+
   function minAmount(plan: Plan): number {
     const amounts = (plan.prices ?? []).map((p) => p.amount);
     return amounts.length > 0 ? Math.min(...amounts) : Number.POSITIVE_INFINITY;
@@ -351,6 +357,14 @@
                 <p class="bridge-plan-description">{plan.description}</p>
               {/if}
 
+              {#if planFeatures(plan).length > 0}
+                <ul class="bridge-plan-features" data-bridge-plan-features aria-label={`Included in ${plan.name}`}>
+                  {#each planFeatures(plan) as feature (feature.key)}
+                    <li class="bridge-plan-feature" data-feature={feature.key}>{feature.name}</li>
+                  {/each}
+                </ul>
+              {/if}
+
               <div class="bridge-plan-prices">
                 {#each visiblePrices as price (price.recurrenceInterval + price.currency)}
                   <button

package/dist/client/upgrade-dialog.d.ts

@@ -1,6 +1,6 @@
 import type { Component } from 'svelte';
 import type { BridgeQuotaRefusal } from '../core/quota-refusal.js';
-import type { BridgeConfig, BridgeUpgradeDialogProps } from '../shared/types/config.js';
+import type { BridgeConfig, BridgeUpgradeDialogProps, PlanWithFeatures } from '../shared/types/config.js';
 /**
  * The dialog to mount for a `billing` config: the built-in one (`default`), the
  * app's own component, or none (`false`). Anything that is not `false` and not
@@ -14,3 +14,10 @@ export declare function resolveUpgradeDialog(billing: BridgeConfig['billing'] |
  * (default `/subscription`).
  */
 export declare function upgradeHrefFor(refusal: Pick<BridgeQuotaRefusal, 'fix'> | null, billing: BridgeConfig['billing'] | undefined): string;
+/**
+ * TBP-755 — the names of the plans that include `feature`, cheapest first (the
+ * plan picker's order). Empty when there is no feature, no plan list, or no
+ * plan lists it. The upgrade dialog and the pricing table read the same list:
+ * each plan's `features`.
+ */
+export declare function plansIncludingFeature(plans: ReadonlyArray<PlanWithFeatures> | null | undefined, feature: string | null | undefined): string[];

package/dist/client/upgrade-dialog.js

@@ -24,3 +24,21 @@ export function resolveUpgradeDialog(billing) {
 export function upgradeHrefFor(refusal, billing) {
     return refusal?.fix ?? resolveBillingRoutes(billing).manageRoute;
 }
+/**
+ * TBP-755 — the names of the plans that include `feature`, cheapest first (the
+ * plan picker's order). Empty when there is no feature, no plan list, or no
+ * plan lists it. The upgrade dialog and the pricing table read the same list:
+ * each plan's `features`.
+ */
+export function plansIncludingFeature(plans, feature) {
+    if (!feature || !plans)
+        return [];
+    const cheapest = (p) => {
+        const amounts = (p.prices ?? []).map((price) => price.amount);
+        return amounts.length > 0 ? Math.min(...amounts) : Number.POSITIVE_INFINITY;
+    };
+    return plans
+        .filter((p) => (p.features ?? []).some((f) => f.key === feature))
+        .sort((a, b) => cheapest(a) - cheapest(b))
+        .map((p) => p.name);
+}

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

@@ -36,5 +36,10 @@ export declare function wrapFetchWithBridgeAuth(baseFetch: typeof fetch, apiBase
  * `@RequireQuota` sends at the plan's cap) opens the upgrade dialog that
  * `<BridgeBootstrap>` mounts, whatever origin your backend is on. The response
  * is still returned to you unchanged.
+ *
+ * TBP-697 — in development, if your backend says it counted a metric (the
+ * `X-Bridge-Usage-Counted` header bridge-nestjs sends outside production) and
+ * this page also reports that metric with `bridge.usage`, the console warns
+ * once: count once, where the action happens.
  */
 export declare function bridgeFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;

package/dist/core/bridge-fetch.js

@@ -1,6 +1,7 @@
 import { getBridgeAuth } from './bridge-instance.js';
 import { observeQuotaRefusal, watchesQuotaOrigin } from './quota-refusal.js';
 import { getConfig } from '../client/stores/config.store.js';
+import { noteBackendResponse } from './double-count-warning.js';
 function requestUrl(input) {
     return typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
 }
@@ -64,6 +65,7 @@ export function wrapFetchWithBridgeAuth(baseFetch, apiBaseUrl) {
         if (!url.startsWith(apiBaseUrl)) {
             const passthrough = await baseFetch(input, init);
             observeIfWatched(passthrough, url, apiBaseUrl);
+            noteBackendResponse(passthrough); // TBP-697 — dev-only double-count check
             return passthrough;
         }
         // 1. Inject current access token.
@@ -119,10 +121,16 @@ export function wrapFetchWithBridgeAuth(baseFetch, apiBaseUrl) {
  * `@RequireQuota` sends at the plan's cap) opens the upgrade dialog that
  * `<BridgeBootstrap>` mounts, whatever origin your backend is on. The response
  * is still returned to you unchanged.
+ *
+ * TBP-697 — in development, if your backend says it counted a metric (the
+ * `X-Bridge-Usage-Counted` header bridge-nestjs sends outside production) and
+ * this page also reports that metric with `bridge.usage`, the console warns
+ * once: count once, where the action happens.
  */
 export async function bridgeFetch(input, init) {
     const response = await fetchWithToken(input, init);
     void observeQuotaRefusal(response, absoluteUrl(requestUrl(input)));
+    noteBackendResponse(response);
     return response;
 }
 async function fetchWithToken(input, init) {

package/dist/core/bridge-runtime.js

@@ -176,8 +176,8 @@ export function startBridgeRuntime(options = {}) {
         // 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.
+        // the reconcile after the reconnect (TBP-700) mints once more and stops
+        // there — a token that changes nothing does not replace the socket.
         refreshAuthToken: options.realtime?.refreshAuthToken ??
             (async () => {
                 if (!_currentAuthToken)
@@ -191,11 +191,10 @@ export function startBridgeRuntime(options = {}) {
                 }
             }),
     });
-    let _connectedOnce = false;
-    // Set just before we call _realtime.reauthorize() so the resulting
-    // reconnect's setOnOpen handler knows the token is already fresh and skips
-    // its proactive refresh — see the loop note in setOnOpen below.
-    let _reauthInFlight = false;
+    // TBP-700 — bookkeeping for reconcileUserState() below.
+    let _reconciling = 0;
+    let _reconcileSawChange = false;
+    let _reconcileSwapsInARow = 0;
     // TBP-660 — catch up after ANY reconnect, including the one our own
     // reauthorize() causes. AppSync Events has no replay, so a push published
     // while the socket is being replaced is gone for good — and a plan change
@@ -240,11 +239,12 @@ export function startBridgeRuntime(options = {}) {
                 return;
             const data = (await res.json());
             // Stopped, or the session changed while this was in flight: the answer
-            // describes a session we no longer have. A token change reauthorizes,
-            // and that reconnect catches up again with the right token.
-            if (_realtime !== rt || _currentAuthToken !== token)
+            // describes a session we no longer have. A new token for the SAME user,
+            // workspace and app is not a new session — the reconcile below rotates
+            // the token on every open, concurrently with this read (TBP-700).
+            if (_realtime !== rt || !sameSession(token, _currentAuthToken))
                 return;
-            const { planChanged, entitlementsChanged } = applyCatchUpSnapshot(data);
+            const { planChanged, entitlementsChanged, initial } = applyCatchUpSnapshot(data);
             if (entitlementsChanged && data?.tenant?.entitlements) {
                 // Keep auth-core's copy (what flag targeting reads) in step too.
                 try {
@@ -254,6 +254,14 @@ export function startBridgeRuntime(options = {}) {
             }
             // TBP-654 — a recovered change must reach the route guard exactly like
             // the push it replaces would have. Nothing changed → nothing to redo.
+            //
+            // TBP-700 — and filling empty stores for the first time recovers no
+            // change: nothing was decided against a plan this page never knew. It
+            // used to count as a plan change, which refreshed the token and swapped
+            // the socket right after every first connect — the window a role change
+            // was lost in on stage. The access token is reconciled below instead.
+            if (initial)
+                return;
             if (planChanged)
                 authorizationChanged('subscription.plan_changed');
             else if (entitlementsChanged)
@@ -335,7 +343,7 @@ export function startBridgeRuntime(options = {}) {
                 const data = (await res.json());
                 // Stopped, or the session changed while this was in flight: the
                 // answer describes a workspace we no longer have.
-                if (_realtime !== rt || _currentAuthToken !== token)
+                if (_realtime !== rt || !sameSession(token, _currentAuthToken))
                     return;
                 if (quotas.getAll().get(metric) !== before)
                     return; // a push won the race
@@ -348,6 +356,57 @@ export function startBridgeRuntime(options = {}) {
             }
         }));
     };
+    // TBP-700 — the same repair for the user's own state: role, privileges,
+    // anything that bumps the server's tokenVersion and publishes
+    // `user.state_changed`. That push is lost exactly like the others when it
+    // is published while the socket is being replaced, and before this nothing
+    // recovered it: the session snapshot's `user` is read from the token being
+    // presented, and a reconnect our own reauthorize() caused skipped the token
+    // refresh (the TBP-644 loop guard). On stage a role change landed in that
+    // window in 4 of 4 runs once the first connect started swapping its socket
+    // (TBP-686), and the user kept the old role until a reload.
+    //
+    // The server's current tokenVersion and claims are only available by
+    // minting: the refresh endpoint reads them from the database, uncached. So
+    // every connect and reconnect ends with ONE refresh, and the token that
+    // comes back is compared with the one we had:
+    //   - same authority (only iat/exp/jti moved): nothing was missed, and the
+    //     socket that was just subscribed stays — no swap, so no loop;
+    //   - anything else (tv, role, plan…): that IS the missed change. It is
+    //     handled like the push would have been — the route guard re-checks and
+    //     the socket is re-authorized with the new token — and the reconnect
+    //     reconciles again, which then finds nothing new.
+    //
+    // `fresh: true` (auth-core, TBP-700) keeps this from joining a
+    // refresh that started before the channels were live, whose token could
+    // predate the very change we are looking for. An older auth-core ignores
+    // the option and joins it — best effort, as before.
+    const reconcileUserState = async () => {
+        if (_realtime !== rt || !_currentAuthToken)
+            return; // signed out: no user state
+        let auth;
+        try {
+            auth = getBridgeAuth();
+        }
+        catch {
+            return; // BridgeAuth not constructed — nothing to refresh with.
+        }
+        _reconciling += 1;
+        _reconcileSawChange = false;
+        try {
+            const refresh = auth.refreshTokens;
+            await refresh.call(auth, { fresh: true });
+        }
+        catch {
+            // Best-effort: the TOKEN_VERSION_STALE retry in bridgeAuthFetch and the
+            // next reconnect are the fallbacks.
+        }
+        finally {
+            _reconciling -= 1;
+            if (!_reconcileSawChange)
+                _reconcileSwapsInARow = 0;
+        }
+    };
     const requestCatchUp = () => {
         if (!_currentAuthToken)
             return; // signed out: no tenant or user scope to fetch
@@ -356,9 +415,9 @@ export function startBridgeRuntime(options = {}) {
             return;
         }
         _catchUpInFlight = true;
-        // Both repairs ride the one in-flight/queued gate, so an open storm still
-        // costs one round of requests, and neither can starve the other.
-        void Promise.all([catchUpSessionSnapshot(), catchUpQuotaSnapshots()]).catch(() => {
+        // Every repair rides the one in-flight/queued gate, so an open storm still
+        // costs one round of requests, and none can starve the others.
+        void Promise.all([catchUpSessionSnapshot(), catchUpQuotaSnapshots(), reconcileUserState()]).catch(() => {
             // Both halves are already best-effort internally; this is the backstop
             // that keeps a repair failure from surfacing as an unhandled rejection
             // in the consuming app. `.finally` below still drains the queue.
@@ -370,41 +429,29 @@ export function startBridgeRuntime(options = {}) {
             }
         });
     };
+    // TBP-700 — when to catch up. Everything above only works if it reads the
+    // server AFTER every channel is live: anything published before that is
+    // already in the database and the read sees it, anything after arrives on
+    // the socket. `open` fires on the FIRST accepted subscription, with the user
+    // channel possibly still pending, so an auth-core that can say "all
+    // subscribed" is asked; an older one falls back to `open`.
+    //
+    // One trigger for the initial connect, a genuine reconnect and the one our
+    // own reauthorize() causes alike: losing pushes is a property of the socket
+    // swap, whoever caused it (TBP-660), and the first connect is where the
+    // snapshot push always loses its race (TBP-686). `requestCatchUp` returns
+    // early when signed out and coalesces concurrent calls.
+    const realtimeWithSubscribed = _realtime;
+    const catchUpOnSubscribed = typeof realtimeWithSubscribed.setOnSubscribed === 'function';
+    if (catchUpOnSubscribed)
+        realtimeWithSubscribed.setOnSubscribed(() => requestCatchUp());
     _realtime.setOnOpen(() => {
         _setRealtimeStatus('open');
-        // On reconnect (not initial connect), proactively refresh tokens.
-        // If the WS was down when tokenVersion was bumped on the server, the
-        // client missed the user.state_changed broadcast. Refreshing here
-        // syncs tokens before the first post-reconnect request can fail with
-        // TOKEN_VERSION_STALE.
-        //
-        // EXCEPT when this reconnect was caused by our OWN reauthorize() below
-        // (a token-only refresh). In that case the token is already current, so
-        // refreshing again would mint yet another JWT, which the tokenStore
-        // subscription would see as a change and reauthorize() again → reconnect
-        // → setOnOpen → refresh → … an unbounded loop that hammers /auth/token
-        // (observed ~32 cycles/sec, jamming the page's main thread and stalling
-        // every downstream wait). Only genuine, externally-triggered reconnects
-        // (network blips, server restarts) should trigger the catch-up refresh.
-        const causedByReauthorize = _reauthInFlight;
-        _reauthInFlight = false;
-        if (_connectedOnce && !causedByReauthorize) {
-            getBridgeAuth().refreshTokens().catch(() => { });
-        }
-        // TBP-660 — the TOKEN refresh above is skipped for a self-induced
-        // reconnect; the STATE catch-up is not. Losing pushes is a property of
-        // the socket swap, whoever caused it, and the catch-up cannot loop.
-        //
-        // TBP-686 — and it runs on the FIRST connect too. It used to be gated on
-        // `_connectedOnce`, which read as "only repair a reconnect" — but the
-        // first connect is exactly where the snapshot goes missing: the server
-        // publishes it fire-and-forget during authorize, before the subscription
-        // is live, so it loses the race and there is nothing to replay. The result
-        // was a signed-in page with a null workspace id, name and branding for the
-        // whole session. `requestCatchUp` already returns early when signed out
-        // and coalesces concurrent calls, so this costs one request per session.
-        requestCatchUp();
-        _connectedOnce = true;
+        // No token refresh here any more (TBP-700): the reconcile in
+        // requestCatchUp mints on EVERY open, the self-induced ones included, and
+        // cannot loop — see reconcileUserState.
+        if (!catchUpOnSubscribed)
+            requestCatchUp();
         for (const fn of _onOpenSubs) {
             try {
                 fn();
@@ -437,10 +484,6 @@ export function startBridgeRuntime(options = {}) {
     // 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);
@@ -560,10 +603,7 @@ export function startBridgeRuntime(options = {}) {
     // (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.
@@ -572,7 +612,30 @@ export function startBridgeRuntime(options = {}) {
     _unsubscribeAuth = tokenStore.subscribe((tokens) => {
         const prevAuthToken = _currentAuthToken;
         _currentAuthToken = tokens?.accessToken ?? undefined;
-        const tokenChanged = _tokenSubscriptionLive && prevAuthToken !== _currentAuthToken;
+        let tokenChanged = _tokenSubscriptionLive && prevAuthToken !== _currentAuthToken;
+        let reauthorize = tokenChanged;
+        // TBP-700 — the token minted by the post-(re)connect reconcile.
+        if (tokenChanged && _reconciling > 0) {
+            if (_realtime.getState?.() === 'open' && sameAuthorization(prevAuthToken, _currentAuthToken)) {
+                // Only its timing moved: nothing was missed, every verdict taken with
+                // the old token stands, and the socket that was just subscribed has
+                // exactly this authority. Replacing it would open the very window
+                // this repair exists for — and loop.
+                tokenChanged = false;
+                reauthorize = false;
+            }
+            else {
+                // The server moved on while we were not listening: the lost
+                // `user.state_changed`, recovered. Re-authorize like the push would
+                // have — bounded, so a claim that differs on every mint cannot turn
+                // this into a reconnect loop.
+                _reconcileSawChange = true;
+                if (_reconcileSwapsInARow >= MAX_RECONCILE_SWAPS)
+                    reauthorize = false;
+                else
+                    _reconcileSwapsInARow += 1;
+            }
+        }
         // TBP-654 + TBP-653 — a new token (sign-in, refresh after a plan change,
         // sign-out) invalidates every verdict taken with the old one, and the
         // current route is re-evaluated: a signed-out session on a protected page
@@ -616,7 +679,7 @@ export function startBridgeRuntime(options = {}) {
         // 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)
+        if (reauthorize)
             reauthorizeForTokenChange();
     });
     _tokenSubscriptionLive = true;
@@ -739,6 +802,48 @@ export function __resetBridgeRuntime() {
     _realtime = undefined;
 }
 // ── helpers ─────────────────────────────────────────────────────────────────
+/**
+ * TBP-700 — how many reconcile-driven socket replacements may follow one
+ * another before the reconcile stops replacing the socket (it still adopts the
+ * token). A genuine missed change costs one; a second is a change published
+ * during that swap. More than a few in a row means a claim differs on every
+ * mint, and replacing the socket forever would be the TBP-644 loop again.
+ */
+const MAX_RECONCILE_SWAPS = 3;
+/** Claims that differ on every mint without meaning anything changed. */
+const PER_MINT_CLAIMS = new Set(['iat', 'exp', 'nbf', 'jti', 'auth_time']);
+/** Same user, workspace and app — the scope a catch-up read belongs to. */
+function sameSession(a, b) {
+    if (!a || !b)
+        return false;
+    if (a === b)
+        return true;
+    const ca = decodeJwtPayload(a);
+    const cb = decodeJwtPayload(b);
+    if (!ca || !cb)
+        return false;
+    return ca.sub === cb.sub && ca.tid === cb.tid && ca.aid === cb.aid;
+}
+/**
+ * TBP-700 — two tokens carry the same authority: every claim is equal except
+ * the per-mint ones. Unreadable tokens are never the same.
+ */
+function sameAuthorization(a, b) {
+    if (!a || !b)
+        return false;
+    const ca = decodeJwtPayload(a);
+    const cb = decodeJwtPayload(b);
+    if (!ca || !cb)
+        return false;
+    const keys = new Set([...Object.keys(ca), ...Object.keys(cb)]);
+    for (const k of keys) {
+        if (PER_MINT_CLAIMS.has(k))
+            continue;
+        if (JSON.stringify(ca[k]) !== JSON.stringify(cb[k]))
+            return false;
+    }
+    return true;
+}
 /** Decode a JWT payload without signature verification (client context only). */
 function decodeJwtPayload(token) {
     try {

package/dist/core/bridge.d.ts

@@ -56,12 +56,13 @@ export interface BridgeTenantSurface {
 /**
  * TBP-697 — usage reporting from the browser.
  *
- * **Self-reported: this is a trusted-client path.** Anything running in the
- * user's browser can call it with any value, so a frontend-only app cannot
- * *enforce* a quota with it — only a backend can refuse a write. Use it when the
- * app has no backend that sees the action: a local-first or mobile app whose
- * data lives on the device. When you do have a backend, report there instead
- * (bridge-nestjs `@RequireQuota`, `usage.report` on the server SDK).
+ * Count once, where the action happens. When the action stays in the browser
+ * (a local-first or mobile app, data on the device) count it here — a
+ * first-class setup that trusts the browser: Bridge shows and bills what the
+ * page reports, and only a backend can refuse a write. When the click calls
+ * your server, the backend handler counts it (bridge-nestjs `@RequireQuota`)
+ * and the page reports nothing. In development the console warns once when a
+ * metric is counted on both sides.
  *
  * Which call: *if deleting it frees room, it's a gauge and your app counts it
  * (`set`); if it happened, it's a counter and Bridge counts it (`report`).*

package/dist/core/bridge.js

@@ -18,6 +18,7 @@
 import { derived, get } from 'svelte/store';
 import { appBrandingStore, tenantEntitlementsStore, tenantIdStore, tenantNameStore, tenantSubscriptionStore, userSnapshotStore, } from './snapshot-stores.js';
 import { LazySlice } from './lazy-slice.js';
+import { noteBrowserCount } from './double-count-warning.js';
 import { DevAttributeProvider } from '@nebulr-group/bridge-auth-core';
 import { getBridgeAuth, tokenStore, subscriptionStore, loadSubscription } from './bridge-instance.js';
 import { bridgeEvents } from './events.js';
@@ -140,9 +141,11 @@ const _subscriptionSurface = {
 // BridgeAuth instance does not exist until bootstrap, and SSR imports this module.
 const _usage = {
     report(metric, value, idempotencyKey) {
+        noteBrowserCount(metric); // TBP-697 — dev warning when the backend counts it too
         getBridgeAuth().usage.report(metric, value, idempotencyKey);
     },
     async set(metric, value) {
+        noteBrowserCount(metric);
         const usage = getBridgeAuth().usage;
         // Peer range still admits auth-core 0.7.x, which has no gauges. Say so
         // instead of "set is not a function".

package/dist/core/double-count-warning.d.ts

@@ -0,0 +1,8 @@
+/** The response header bridge-nestjs sets, outside production, on a counting endpoint. */
+export declare const USAGE_COUNTED_HEADER = "x-bridge-usage-counted";
+/** `bridge.usage.report` / `set` was called for `metric` from this page. */
+export declare function noteBrowserCount(metric: string): void;
+/** A response from the app's own backend — records the metrics it says it counted. */
+export declare function noteBackendResponse(response: Response | null | undefined): void;
+/** Test hook: forget everything seen so far. */
+export declare function __resetDoubleCountWarning(): void;

package/dist/core/double-count-warning.js

@@ -0,0 +1,74 @@
+// TBP-697 — in development, warn when the browser and the backend both count
+// the same metric.
+//
+// The rule: count once, where the action happens. When the click calls your
+// server, the backend handler counts (bridge-nestjs `@RequireQuota` /
+// `@SyncQuota`) and the page only shows the number. When there is no backend
+// that sees the action, the browser counts (`bridge.usage.report` / `set`).
+// Doing both counts every action twice, and nothing else would ever say so.
+//
+// How it is noticed: outside production, bridge-nestjs marks a response from a
+// counting endpoint with `X-Bridge-Usage-Counted: <metric>[, <metric>]`. This
+// module remembers the metrics the backend said it counts and the metrics this
+// page reported through `bridge.usage`, and warns once per metric that appears
+// in both. A development build only: in production nothing is recorded and
+// nothing is printed (and the backend does not send the header there anyway).
+//
+// Scope is the page session, which is one signed-in workspace — both sides
+// count for the workspace of the user's token.
+/** The response header bridge-nestjs sets, outside production, on a counting endpoint. */
+export const USAGE_COUNTED_HEADER = 'x-bridge-usage-counted';
+const countedByBackend = new Set();
+const countedByBrowser = new Set();
+const warned = new Set();
+function isDevBuild() {
+    try {
+        return import.meta.env.DEV === true;
+    }
+    catch {
+        return false;
+    }
+}
+function warnIfBoth(metric) {
+    if (warned.has(metric) || !countedByBackend.has(metric) || !countedByBrowser.has(metric))
+        return;
+    warned.add(metric);
+    console.warn(`[bridge] '${metric}' is counted twice: your backend counts it (bridge-nestjs @RequireQuota / @SyncQuota) ` +
+        `and this page also reports it with bridge.usage. Count once, where the action happens: ` +
+        `when the click calls your server, keep the backend count and remove the bridge.usage call. ` +
+        `(Development only — this warning is not shown in production.)`);
+}
+/** `bridge.usage.report` / `set` was called for `metric` from this page. */
+export function noteBrowserCount(metric) {
+    if (!isDevBuild() || typeof metric !== 'string' || metric === '')
+        return;
+    countedByBrowser.add(metric);
+    warnIfBoth(metric);
+}
+/** A response from the app's own backend — records the metrics it says it counted. */
+export function noteBackendResponse(response) {
+    if (!isDevBuild())
+        return;
+    let value;
+    try {
+        value = response?.headers?.get(USAGE_COUNTED_HEADER);
+    }
+    catch {
+        return;
+    }
+    if (!value)
+        return;
+    for (const raw of value.split(',')) {
+        const metric = raw.trim();
+        if (!metric)
+            continue;
+        countedByBackend.add(metric);
+        warnIfBoth(metric);
+    }
+}
+/** Test hook: forget everything seen so far. */
+export function __resetDoubleCountWarning() {
+    countedByBackend.clear();
+    countedByBrowser.clear();
+    warned.clear();
+}

package/dist/core/feature-upgrade.d.ts

@@ -0,0 +1,49 @@
+/**
+ * TBP-756 — "this feature is not on your plan", as an event the upgrade dialog
+ * listens to.
+ *
+ * Owner decision (2026-09-28): nothing opens by itself. The upgrade dialog's
+ * feature variant opens only when the person does something gated:
+ *   - reaches a route whose feature flag is off because of the plan (the route
+ *     guard), on first load after redirecting to the rule's `redirectTo`;
+ *   - clicks the upgrade prompt a `<FeatureFlag>` shows (its `fallback`
+ *     snippet's `openUpgrade`, or the opt-in `upgrade` prompt);
+ *   - makes a request the backend refuses with `402 FEATURE_NOT_IN_PLAN`
+ *     (bridge-nestjs's flag guards), like the `402 QUOTA_EXCEEDED` dialog.
+ * A hidden feature with no fallback opens nothing.
+ */
+import { type Readable } from 'svelte/store';
+/** Why a feature is off, as Bridge reports it. */
+export type BridgeFeatureOffReason = 'plan' | 'permission' | 'off' | 'rule' | 'rollout';
+/** A request to show the upgrade dialog for a feature the plan does not include. */
+export interface BridgeFeatureUpgrade {
+    /** The feature flag that is off. */
+    flag: string | null;
+    /**
+     * The plan feature the flag's rule asks for (`bridge:billing.entitlement.<feature>`),
+     * when it names one. The dialog lists the plans that include it.
+     */
+    feature: string | null;
+    /** Where to upgrade, from a backend refusal's `fix` (a same-app path), else null. */
+    fix: string | null;
+}
+/** The feature upgrade the dialog is showing, or `null`. */
+export declare const featureUpgrade: Readable<BridgeFeatureUpgrade | null>;
+/**
+ * Open the upgrade dialog for a feature the plan does not include. Call it from
+ * a click; a page render must never call it (owner rule: nothing opens by itself).
+ */
+export declare function openFeatureUpgrade(request?: {
+    flag?: string | null;
+    feature?: string | null;
+    fix?: string | null;
+}): void;
+/** Close the feature variant of the upgrade dialog. */
+export declare function dismissFeatureUpgrade(): void;
+/**
+ * The upgrade request in a `402 FEATURE_NOT_IN_PLAN` body (bridge-nestjs), or
+ * null when the body is something else.
+ */
+export declare function parseFeatureRefusal(body: unknown): BridgeFeatureUpgrade | null;
+/** Test-only: forget the current request. */
+export declare function __resetFeatureUpgradeForTests(): void;

package/dist/core/feature-upgrade.js

@@ -0,0 +1,63 @@
+/**
+ * TBP-756 — "this feature is not on your plan", as an event the upgrade dialog
+ * listens to.
+ *
+ * Owner decision (2026-09-28): nothing opens by itself. The upgrade dialog's
+ * feature variant opens only when the person does something gated:
+ *   - reaches a route whose feature flag is off because of the plan (the route
+ *     guard), on first load after redirecting to the rule's `redirectTo`;
+ *   - clicks the upgrade prompt a `<FeatureFlag>` shows (its `fallback`
+ *     snippet's `openUpgrade`, or the opt-in `upgrade` prompt);
+ *   - makes a request the backend refuses with `402 FEATURE_NOT_IN_PLAN`
+ *     (bridge-nestjs's flag guards), like the `402 QUOTA_EXCEEDED` dialog.
+ * A hidden feature with no fallback opens nothing.
+ */
+import { readable } from 'svelte/store';
+import { safeFixPath } from './quota-refusal.js';
+let _current = null;
+let _setCurrent = null;
+/** The feature upgrade the dialog is showing, or `null`. */
+export const featureUpgrade = readable(null, (set) => {
+    _setCurrent = set;
+    set(_current);
+    return () => {
+        _setCurrent = null;
+    };
+});
+/**
+ * Open the upgrade dialog for a feature the plan does not include. Call it from
+ * a click; a page render must never call it (owner rule: nothing opens by itself).
+ */
+export function openFeatureUpgrade(request = {}) {
+    _current = {
+        flag: request.flag ?? null,
+        feature: request.feature ?? null,
+        fix: safeFixPath(request.fix),
+    };
+    _setCurrent?.(_current);
+}
+/** Close the feature variant of the upgrade dialog. */
+export function dismissFeatureUpgrade() {
+    _current = null;
+    _setCurrent?.(null);
+}
+/**
+ * The upgrade request in a `402 FEATURE_NOT_IN_PLAN` body (bridge-nestjs), or
+ * null when the body is something else.
+ */
+export function parseFeatureRefusal(body) {
+    if (typeof body !== 'object' || body === null)
+        return null;
+    const b = body;
+    if (b.code !== 'FEATURE_NOT_IN_PLAN')
+        return null;
+    return {
+        flag: typeof b.flag === 'string' && b.flag ? b.flag : null,
+        feature: typeof b.feature === 'string' && b.feature ? b.feature : null,
+        fix: safeFixPath(b.fix),
+    };
+}
+/** Test-only: forget the current request. */
+export function __resetFeatureUpgradeForTests() {
+    dismissFeatureUpgrade();
+}

package/dist/core/quota-refusal.js

@@ -22,6 +22,7 @@
  * The dialog is decoration. The refusal is the backend's; this only explains it.
  */
 import { readable } from 'svelte/store';
+import { openFeatureUpgrade, parseFeatureRefusal } from './feature-upgrade.js';
 /**
  * A same-app path, or null. A backend's `fix` becomes a link the user clicks,
  * so an absolute URL, a protocol-relative `//host` or a `javascript:` value is
@@ -129,8 +130,15 @@ export function observeQuotaRefusal(response, url = '') {
         .json()
         .then((body) => {
         const refusal = parseQuotaRefusal(body, url || response.url);
-        if (refusal)
+        if (refusal) {
             reportQuotaRefusal(refusal);
+            return;
+        }
+        // TBP-756 — a flag-gated endpoint refused because the plan does not
+        // include the feature: the same dialog, in its feature variant.
+        const feature = parseFeatureRefusal(body);
+        if (feature)
+            openFeatureUpgrade(feature);
     })
         .catch(() => {
         /* not JSON — not a quota refusal */

package/dist/core/snapshot-stores.d.ts

@@ -104,6 +104,13 @@ export declare function applyEntitlementsChanged(msg: {
 export declare function applyCatchUpSnapshot(data: SessionSnapshotData): {
     planChanged: boolean;
     entitlementsChanged: boolean;
+    /**
+     * TBP-700 — the tenant stores were empty: this filled them for the first
+     * time rather than changing anything the page had already seen. The
+     * `*Changed` flags still say whether the values moved, so a caller can seed
+     * other copies; a first fill is not a recovered change.
+     */
+    initial: boolean;
 };
 /** Test-only: reset every snapshot store to `null`. Vitest hook. */
 export declare function __resetSnapshotStores(): void;

package/dist/core/snapshot-stores.js

@@ -104,6 +104,7 @@ export function applyCatchUpSnapshot(data) {
     const subAfter = get(_tenantSubscription);
     const entAfter = get(_tenantEntitlements);
     return {
+        initial: subBefore === null && entBefore === null,
         planChanged: (subBefore?.plan?.slug ?? null) !== (subAfter?.plan?.slug ?? null) ||
             (subBefore?.status ?? null) !== (subAfter?.status ?? null),
         entitlementsChanged: !sameFlags(entBefore, entAfter),

package/dist/flags/FeatureFlag.svelte

@@ -6,27 +6,56 @@
     - `fallback` — rendered when the flag is off or no rule matched
 
   Both snippets receive the Bridge-decided value so you can use it directly.
+  TBP-756 — `fallback` also receives why the feature is off, and a way to open
+  the upgrade dialog:
+    - `reason`: 'plan' (an upgrade alone would turn it on), 'permission' (this
+      person's role or privileges), 'off', 'rule', 'rollout', or undefined when
+      Bridge has not said (the flag is not loaded yet)
+    - `feature`: with 'plan', the plan feature the rule asks for
+    - `openUpgrade()`: opens the upgrade dialog for this feature. Call it from a
+      click; rendering a fallback never opens anything by itself.
+
+  `upgrade` (opt-in): with no `fallback`, a feature that is off because of the
+  plan renders a small "Upgrade to use this" prompt in its place; clicking it
+  opens the upgrade dialog. Off for any other reason: nothing, as before.
 
   Usage:
     <FeatureFlag key="new-dashboard" defaultValue={false}>
       {#snippet children()}<NewDashboard />{/snippet}
     </FeatureFlag>
 
-    <FeatureFlag key="ui-theme" defaultValue="light-mode">
-      {#snippet children(value)}<App theme={value} />{/snippet}
-      {#snippet fallback(value)}<App theme={value} />{/snippet}
+    <FeatureFlag key="reports" defaultValue={false}>
+      {#snippet children()}<Reports />{/snippet}
+      {#snippet fallback(_value, { reason, openUpgrade })}
+        {#if reason === 'plan'}<button onclick={openUpgrade}>Upgrade for reports</button>{/if}
+      {/snippet}
+    </FeatureFlag>
+
+    <FeatureFlag key="reports" defaultValue={false} upgrade>
+      {#snippet children()}<Reports />{/snippet}
     </FeatureFlag>
 -->
+<script lang="ts" module>
+  /** TBP-756 — what a `<FeatureFlag>` fallback learns about why the feature is off. */
+  export interface FeatureFlagOffInfo {
+    reason: 'plan' | 'permission' | 'off' | 'rule' | 'rollout' | undefined;
+    feature: string | undefined;
+    openUpgrade: () => void;
+  }
+</script>
+
 <script lang="ts" generics="T = boolean">
   import type { Snippet } from 'svelte';
   import type { EvalContext } from '@nebulr-group/bridge-auth-core';
   import { evaluateFlag } from './registry.js';
   import { _flagVersionsRune } from './flag.svelte.js';
+  import { openFeatureUpgrade } from '../core/feature-upgrade.js';
 
   let {
     key,
     defaultValue,
     context,
+    upgrade = false,
     children,
     fallback,
   }: {
@@ -38,8 +67,13 @@
      * attributes win on key collision over Bridge-managed providers.
      */
     context?: Partial<EvalContext>;
+    /**
+     * TBP-756 — opt in to an inline "Upgrade to use this" prompt when the
+     * feature is off because of the plan and there is no `fallback`.
+     */
+    upgrade?: boolean;
     children?: Snippet<[T]>;
-    fallback?: Snippet<[T]>;
+    fallback?: Snippet<[T, FeatureFlagOffInfo]>;
   } = $props();
 
   const result = $derived.by(() => {
@@ -48,10 +82,29 @@
     _flagVersionsRune().get(key);
     return evaluateFlag<T>(key, defaultValue, context);
   });
+
+  // An auth-core without TBP-756 returns no reason; the info is then empty.
+  const off = $derived.by((): FeatureFlagOffInfo => {
+    const r = result as { reason?: FeatureFlagOffInfo['reason']; feature?: string };
+    return {
+      reason: r.reason,
+      feature: r.feature,
+      openUpgrade: () => openFeatureUpgrade({ flag: key, feature: r.feature ?? null }),
+    };
+  });
 </script>
 
 {#if result.passed}
   {#if children}{@render children(result.value)}{/if}
 {:else if fallback}
-  {@render fallback(result.value)}
+  {@render fallback(result.value, off)}
+{:else if upgrade && off.reason === 'plan'}
+  <button
+    type="button"
+    class="bridge-btn bridge-btn-secondary bridge-feature-upgrade"
+    data-bridge-feature-upgrade={key}
+    onclick={off.openUpgrade}
+  >
+    Upgrade to use this
+  </button>
 {/if}

package/dist/flags/FeatureFlag.svelte.d.ts

@@ -1,3 +1,9 @@
+/** TBP-756 — what a `<FeatureFlag>` fallback learns about why the feature is off. */
+export interface FeatureFlagOffInfo {
+    reason: 'plan' | 'permission' | 'off' | 'rule' | 'rollout' | undefined;
+    feature: string | undefined;
+    openUpgrade: () => void;
+}
 import type { Snippet } from 'svelte';
 import type { EvalContext } from '@nebulr-group/bridge-auth-core';
 declare function $$render<T = boolean>(): {
@@ -10,8 +16,13 @@ declare function $$render<T = boolean>(): {
          * attributes win on key collision over Bridge-managed providers.
          */
         context?: Partial<EvalContext>;
+        /**
+         * TBP-756 — opt in to an inline "Upgrade to use this" prompt when the
+         * feature is off because of the plan and there is no `fallback`.
+         */
+        upgrade?: boolean;
         children?: Snippet<[T]>;
-        fallback?: Snippet<[T]>;
+        fallback?: Snippet<[T, FeatureFlagOffInfo]>;
     };
     exports: {};
     bindings: "";

package/dist/flags/index.d.ts

@@ -2,6 +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 type { FeatureFlagOffInfo } from './FeatureFlag.svelte';
+export { openFeatureUpgrade } from '../core/feature-upgrade.js';
 export { realtimeStatus, realtimeStatusDetail } from './realtime-status.js';
 export { onBridgeRealtimeStatus } from '../core/bridge-runtime.js';
 export type { ConnectionState, RealtimeStatus } from '@nebulr-group/bridge-auth-core';

package/dist/flags/index.js

@@ -12,6 +12,8 @@ export { evaluateFlag, setBridgeFlagsInstance, getBridgeFlagsInstance, notifyFla
 export { useFlag, flagStore, _flagVersionsRune } from './flag.svelte.js';
 // Component
 export { default as FeatureFlag } from './FeatureFlag.svelte';
+// TBP-756 — open the upgrade dialog for a feature the plan does not include.
+export { openFeatureUpgrade } from '../core/feature-upgrade.js';
 // Reactive realtime connection status (subscribe in components to show
 // offline indicators, retry banners, etc.).
 export { realtimeStatus, realtimeStatusDetail } from './realtime-status.js';

package/dist/index.d.ts

@@ -63,6 +63,8 @@ export { default as QuotaGate } from './client/components/subscription/QuotaGate
 export { default as Entitled } from './client/components/subscription/Entitled.svelte';
 export { default as BridgeUpgradeDialog } from './client/components/subscription/BridgeUpgradeDialog.svelte';
 export { onBridgeQuotaExceeded, parseQuotaRefusal } from './core/quota-refusal.js';
+export { openFeatureUpgrade, dismissFeatureUpgrade, featureUpgrade, parseFeatureRefusal, } from './core/feature-upgrade.js';
+export type { BridgeFeatureUpgrade, BridgeFeatureOffReason } from './core/feature-upgrade.js';
 export type { BridgeQuotaRefusal } from './core/quota-refusal.js';
 export * from './auth/route-guard.js';
 export * from './shared/profile.js';

package/dist/index.js

@@ -102,6 +102,9 @@ export { default as QuotaGate } from './client/components/subscription/QuotaGate
 export { default as Entitled } from './client/components/subscription/Entitled.svelte';
 export { default as BridgeUpgradeDialog } from './client/components/subscription/BridgeUpgradeDialog.svelte';
 export { onBridgeQuotaExceeded, parseQuotaRefusal } from './core/quota-refusal.js';
+// TBP-756 — the upgrade dialog's feature variant: a plan-gated route, a
+// <FeatureFlag> upgrade click, or a backend's 402 FEATURE_NOT_IN_PLAN.
+export { openFeatureUpgrade, dismissFeatureUpgrade, featureUpgrade, parseFeatureRefusal, } from './core/feature-upgrade.js';
 // Auth route guards
 export * from './auth/route-guard.js';
 // Types

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

@@ -72,4 +72,28 @@ export interface BridgeUpgradeDialogProps {
     canUpgrade: boolean;
     /** Close the dialog. */
     onclose: () => void;
+    /** TBP-755/756 — the plan feature the user is missing, by key (or the
+     *  feature flag's key when its rule names no plan feature). With no
+     *  `refusal`, a non-null `feature` opens the dialog in its feature variant;
+     *  when `plans` lists plans that include it, the dialog names them.
+     *  BridgeBootstrap sets it only after the person did something gated: a
+     *  plan-gated route, a `<FeatureFlag>` upgrade click, or a backend's
+     *  `402 FEATURE_NOT_IN_PLAN`. */
+    feature?: string | null;
+    /** TBP-755 — the app's plans (the plan picker's feed), each with the
+     *  features it includes. Used only to name the plans that include `feature`. */
+    plans?: ReadonlyArray<PlanWithFeatures> | null;
+}
+/** TBP-755 — a plan as the plan list returns it, with the features it
+ *  includes. Structural so it holds whichever auth-core release is installed. */
+export interface PlanWithFeatures {
+    key: string;
+    name: string;
+    prices?: ReadonlyArray<{
+        amount: number;
+    }>;
+    features?: ReadonlyArray<{
+        key: string;
+        name: string;
+    }>;
 }

package/dist/styles.css

@@ -1177,6 +1177,16 @@
   font-size: 0.875rem;
 }
 
+/* TBP-755 — the features a plan includes. */
+.bridge-plan-features {
+  margin: 0;
+  padding-left: 1.125rem;
+  font-size: 0.875rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
 .bridge-plan-prices {
   display: flex;
   flex-direction: column;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulr-group/bridge-svelte",
-  "version": "0.9.0-beta.4",
+  "version": "0.9.0-beta.6",
   "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",
@@ -79,7 +79,7 @@
     "typescript": "^6.0.0",
     "vite": "^6.2.6",
     "vitest": "^4.1.4",
-    "@nebulr-group/bridge-auth-core": "0.8.0-beta.0"
+    "@nebulr-group/bridge-auth-core": "0.8.0-beta.3"
   },
   "keywords": [
     "svelte",