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

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.
@@ -87,9 +89,21 @@ export function wrapFetchWithBridgeAuth(baseFetch, apiBaseUrl) {
                 .extensions?.response?.code === 'TOKEN_VERSION_STALE');
         if (!isStale)
             return response;
-        // 3. Refresh — same call as the WebSocket user.state_changed path.
-        //    Dedup gate in BridgeAuth coalesces concurrent calls into one HTTP request.
-        await getBridgeAuth().refreshTokens().catch(() => { });
+        // 3. Refresh with a token minted AFTER this answer. The server just said
+        //    our tokenVersion is behind, so a refresh that was already in flight
+        //    (the per-connect reconcile, the WebSocket user.state_changed path)
+        //    may have been minted before the bump and come back just as stale —
+        //    retrying with it fails the same way and the caller sees "access
+        //    token has been invalidated; refresh required". `fresh` waits for
+        //    such a refresh and mints again (or joins one that started after
+        //    this call), so the retry carries the current version.
+        //    Stage, 2026-09-28: a new user's first CreateApp failed twice this way
+        //    (retry sent tv 0 while the server was at tv 1). TBP-747.
+        //    An auth-core older than 0.8.0-beta.2 (the peer range allows 0.7.x)
+        //    ignores the option and joins the in-flight refresh, as before.
+        const auth = getBridgeAuth();
+        const refresh = auth.refreshTokens;
+        await refresh.call(auth, { fresh: true }).catch(() => { });
         const freshToken = getBridgeAuth().getTokens()?.accessToken;
         const freshHeaders = new Headers(init?.headers);
         if (freshToken)
@@ -119,10 +133,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.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/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.5",
+  "version": "0.9.0-beta.7",
   "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",
@@ -58,7 +58,7 @@
     "svelte": "^5.0.0",
     "@sveltejs/kit": "^2.0.0",
     "@stripe/stripe-js": ">=4.0.0",
-    "@nebulr-group/bridge-auth-core": ">=0.7.1 <1.0.0 || >=0.8.0-beta.0 <1.0.0"
+    "@nebulr-group/bridge-auth-core": ">=0.8.0-beta.4 <1.0.0"
   },
   "peerDependenciesMeta": {
     "@stripe/stripe-js": {
@@ -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.2"
+    "@nebulr-group/bridge-auth-core": "0.8.0-beta.4"
   },
   "keywords": [
     "svelte",