From 61eb442df56af93dd5ad3a19bd72098658fee223 Mon Sep 17 00:00:00 2001
From: Pierre Brisorgueil <pierrebrisorgueil@me.com>
Date: Thu, 18 Jun 2026 15:32:47 +0200
Subject: [PATCH 1/2] feat(billing): surface capacity equivalences on the nav
 compute gauge

Wire the (previously orphaned) BillingEquivalencesChipsComponent into the nav
compute-gauge tooltip. When serverConfig.billing.equivalences is set, derive a
human-readable remaining-capacity estimate per entry:
count = floor(totalRemaining / unitCost), totalRemaining = max(0, (meterQuota +
extrasRemaining) - meterUsed). Only consumption-scaled kinds (easy/hard) with a
finite positive unitCost render; the unit-cost framing handles per-period and
one-shot grants with no special branch. Config-driven, no-op when absent.

Also adds a mount fade/scale-in and a low-remaining (>= 80%) pulse to the ring
to make the gauge more noticeable; both respect prefers-reduced-motion.

Tests (15 new) cover the derivation, filtering, one-shot grant, exhaustion and
ring motion. Documents the equivalences contract in the module README.

Closes #4349
---
 src/modules/billing/README.md                 |  36 +++
 .../billing.navComputeGauge.component.vue     | 127 +++++++++-
 ...ng.navComputeGauge.component.unit.tests.js | 219 ++++++++++++++++++
 3 files changed, 372 insertions(+), 10 deletions(-)

diff --git a/src/modules/billing/README.md b/src/modules/billing/README.md
index 984f560e7..6cb3cccf7 100644
--- a/src/modules/billing/README.md
+++ b/src/modules/billing/README.md
@@ -49,3 +49,39 @@ Auto-colored progress bar (green/orange/red). Shows "Unlimited" for uncapped pla
 ```vue
 <BillingPlanBadgeComponent :plan="currentPlan" />
 ```
+
+### `<BillingNavComputeGaugeComponent>`
+
+Sidenav compute-usage indicator (meter mode). A color-coded ring + `X% used`
+label; the hover tooltip shows `used / total compute · resets <day>`. The ring
+fades/scales in on mount and pulses near exhaustion (≥ 80%) — both motions
+respect `prefers-reduced-motion`.
+
+When the server config defines `billing.equivalences`, the tooltip also surfaces
+a human-readable remaining-capacity estimate via `<BillingEquivalencesChipsComponent>`.
+
+### `<BillingEquivalencesChipsComponent>` + the `equivalences` contract
+
+Renders capacity chips (`{ kind, count, label }`) color-coded by kind
+(`easy` → green, `hard` → amber, `feature` → brand).
+
+The nav gauge derives those chips from `serverConfig.billing.equivalences` — an
+**opaque passthrough** from the backend auth config that **downstream projects
+define** (the devkit ships only a neutral demo default):
+
+```js
+// serverConfig.billing.equivalences  (null / absent / [] → gauge shows raw units only)
+[
+  { kind: 'easy', unitCost: 200,  label: 'easy operations' },
+  { kind: 'hard', unitCost: 2000, label: 'heavy operations' },
+]
+```
+
+- `unitCost` = compute units consumed per ONE operation of that kind (finite, `> 0`).
+- The gauge renders `count = floor(totalRemaining / unitCost)` per entry, where
+  `totalRemaining = max(0, (meterQuota + extrasRemaining) − meterUsed)`.
+- Only the consumption-scaled kinds `easy` / `hard` are surfaced; entries with a
+  non-positive/non-finite `unitCost`, a non-string `label`, or any other kind are
+  dropped. The unit-cost framing means **per-period and one-shot grants need no
+  special handling** — for a one-shot grant, `totalRemaining` is simply the
+  remaining grant.
diff --git a/src/modules/billing/components/billing.navComputeGauge.component.vue b/src/modules/billing/components/billing.navComputeGauge.component.vue
index edbf2b295..04af9e179 100644
--- a/src/modules/billing/components/billing.navComputeGauge.component.vue
+++ b/src/modules/billing/components/billing.navComputeGauge.component.vue
@@ -5,11 +5,15 @@
   nav items (icon in #prepend, title), only the icon is a colored circle
   reflecting consumption level.
 
-  Hover tooltip exposes the precise figures: "X / Y compute · resets <day>".
+  Hover tooltip exposes the precise figures: "X / Y compute · resets <day>",
+  plus optional capacity chips ("~N easy / ~M heavy ops") when the server config
+  defines billing.equivalences (rendered via BillingEquivalencesChipsComponent).
   Admin users see a permanent ∞ rainbow state (no quota applies).
 
   Click → navigates to /users/billing.
   Auto-fetches on mount + on window.focus.
+  The ring fades/scales in on mount and pulses when usage nears exhaustion
+  (>= 80%); both motions respect prefers-reduced-motion.
 
   Gate: hidden when not logged in or meterMode false.
 -->
@@ -27,15 +31,16 @@
         <template #prepend>
           <!-- Admin: rainbow circular indicator (full ring) -->
           <div v-if="isAdmin" class="nav-gauge-admin-ring me-8" aria-hidden="true" />
-          <!-- Standard: color-coded progress ring -->
-          <v-progress-circular
-            v-else
-            :model-value="pctUsed"
-            :color="iconColor"
-            size="24"
-            width="6"
-            class="me-8"
-          />
+          <!-- Standard: color-coded progress ring (mount fade/scale-in; pulses near exhaustion) -->
+          <div v-else class="nav-gauge-ring-enter me-8">
+            <v-progress-circular
+              :model-value="pctUsed"
+              :color="iconColor"
+              :class="{ 'nav-gauge-ring-alert': isLow }"
+              size="24"
+              width="6"
+            />
+          </div>
         </template>
         <!-- Admin: ∞ rainbow label -->
         <v-list-item-title v-if="isAdmin">
@@ -48,6 +53,11 @@
     <template v-else>
       <div>{{ usedDisplay }} / {{ totalDisplay }} compute</div>
       <div v-if="resetLabel">{{ resetLabel }}</div>
+      <BillingEquivalencesChipsComponent
+        v-if="equivalenceChips.length"
+        :equivalences="equivalenceChips"
+        class="mt-2"
+      />
     </template>
   </v-tooltip>
 </template>
@@ -55,10 +65,13 @@
 <script>
 import { useBillingStore } from '../stores/billing.store.js';
 import { useAuthStore } from '../../auth/stores/auth.store.js';
+import BillingEquivalencesChipsComponent from './billing.equivalencesChips.component.vue';
 
 export default {
   name: 'BillingNavComputeGaugeComponent',
 
+  components: { BillingEquivalencesChipsComponent },
+
   setup() {
     const billingStore = useBillingStore();
     const authStore = useAuthStore();
@@ -133,6 +146,61 @@ export default {
       return 'success';
     },
 
+    /**
+     * @desc True when usage has reached the warning/error band (>= 80%).
+     * Drives the low-remaining pulse on the ring.
+     * @returns {boolean}
+     */
+    isLow() {
+      return this.iconColor === 'warning' || this.iconColor === 'error';
+    },
+
+    /**
+     * @desc Remaining compute the gauge can still spend: total quota (included +
+     * extras) minus consumed, floored at 0. Consistent with the used/total figures
+     * shown in the tooltip; drives the equivalence-chip estimates.
+     * @returns {number}
+     */
+    totalRemaining() {
+      return Math.max(0, this.totalQuota - this.meterUsed);
+    },
+
+    /**
+     * @desc Per-operation capacity equivalences from server config (downstream-defined,
+     * opaque passthrough via serverConfig.billing.equivalences). Returns [] when unset.
+     * @returns {Array<{kind: string, unitCost: number, label: string}>}
+     */
+    equivalencesConfig() {
+      const eq = this.authStore.serverConfig?.billing?.equivalences;
+      return Array.isArray(eq) ? eq : [];
+    },
+
+    /**
+     * @desc Human-readable remaining-capacity chips derived from the equivalence unit
+     * costs: count = floor(totalRemaining / unitCost). Only consumption-scaled kinds
+     * (easy/hard) with a finite positive unitCost render — this guards against
+     * division-by-zero / Infinity and drops the non-consumption 'feature' kind.
+     * Works identically for per-period and one-shot grants (no special branch): when
+     * the quota is a one-shot total, totalRemaining is simply the remaining grant.
+     * @returns {Array<{kind: string, count: number, label: string}>}
+     */
+    equivalenceChips() {
+      return this.equivalencesConfig
+        .filter(
+          (e) =>
+            e &&
+            (e.kind === 'easy' || e.kind === 'hard') &&
+            typeof e.label === 'string' &&
+            Number.isFinite(e.unitCost) &&
+            e.unitCost > 0,
+        )
+        .map((e) => ({
+          kind: e.kind,
+          count: Math.floor(this.totalRemaining / e.unitCost),
+          label: e.label,
+        }));
+    },
+
     usedDisplay() {
       return this.meterUsed.toLocaleString();
     },
@@ -225,4 +293,43 @@ export default {
   opacity: 0.6;
   flex-shrink: 0;
 }
+
+/* ── Nav gauge ring motion (#4349) ──────────────────────────────────────────
+   Mount fade/scale-in to draw the eye, plus a low-remaining pulse near
+   exhaustion. Both are gated on prefers-reduced-motion: no-preference, so
+   reduced-motion users always get a static ring. */
+.nav-gauge-ring-enter {
+  display: inline-flex;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .nav-gauge-ring-enter {
+    animation: nav-gauge-in 420ms ease-out both;
+  }
+
+  .nav-gauge-ring-alert {
+    animation: nav-gauge-pulse 1.8s ease-in-out infinite;
+  }
+}
+
+@keyframes nav-gauge-in {
+  from {
+    opacity: 0;
+    transform: scale(0.6);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+@keyframes nav-gauge-pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.55;
+  }
+}
 </style>
diff --git a/src/modules/billing/tests/billing.navComputeGauge.component.unit.tests.js b/src/modules/billing/tests/billing.navComputeGauge.component.unit.tests.js
index f185bf39b..0d26ba7f5 100644
--- a/src/modules/billing/tests/billing.navComputeGauge.component.unit.tests.js
+++ b/src/modules/billing/tests/billing.navComputeGauge.component.unit.tests.js
@@ -477,4 +477,223 @@ describe('BillingNavComputeGaugeComponent', () => {
       expect(listItem.attributes('aria-label')).toMatch(/unlimited.*admin/i);
     });
   });
+
+  // ── #4349 — equivalence capacity chips ───────────────────────────────────
+
+  describe('equivalence chips (#4349)', () => {
+    const setupWithEquivalences = (
+      equivalences,
+      meter = { meterUsed: 0, meterQuota: 10000, extrasRemaining: 0, weekResetAt: null },
+    ) => {
+      const authStore = useAuthStore();
+      const billingStore = useBillingStore();
+      authStore.cookieExpire = Date.now() + 86400000;
+      authStore.serverConfig = { billing: { meterMode: true, equivalences } };
+      billingStore.usageMeter = meter;
+    };
+
+    it('registers BillingEquivalencesChipsComponent', () => {
+      setupWithEquivalences([{ kind: 'easy', unitCost: 200, label: 'easy ops' }]);
+      wrapper = mountComponent();
+      expect(wrapper.vm.$options.components.BillingEquivalencesChipsComponent).toBeTruthy();
+    });
+
+    it('derives chips with count = floor(totalRemaining / unitCost)', () => {
+      // totalRemaining = (10000 + 0) - 0 = 10000
+      setupWithEquivalences([
+        { kind: 'easy', unitCost: 200, label: 'easy ops' },
+        { kind: 'hard', unitCost: 2000, label: 'hard ops' },
+      ]);
+      wrapper = mountComponent();
+      expect(wrapper.vm.equivalenceChips).toEqual([
+        { kind: 'easy', count: 50, label: 'easy ops' },
+        { kind: 'hard', count: 5, label: 'hard ops' },
+      ]);
+    });
+
+    it('floors fractional results (no rounding up)', () => {
+      // totalRemaining = 9500 → 9500 / 200 = 47.5 → 47
+      setupWithEquivalences(
+        [{ kind: 'easy', unitCost: 200, label: 'easy ops' }],
+        { meterUsed: 500, meterQuota: 10000, extrasRemaining: 0, weekResetAt: null },
+      );
+      wrapper = mountComponent();
+      expect(wrapper.vm.equivalenceChips).toEqual([{ kind: 'easy', count: 47, label: 'easy ops' }]);
+    });
+
+    it('returns no chips when equivalences config is absent', () => {
+      const authStore = useAuthStore();
+      const billingStore = useBillingStore();
+      authStore.cookieExpire = Date.now() + 86400000;
+      authStore.serverConfig = { billing: { meterMode: true } };
+      billingStore.usageMeter = { meterUsed: 0, meterQuota: 10000, extrasRemaining: 0, weekResetAt: null };
+      wrapper = mountComponent();
+      expect(wrapper.vm.equivalenceChips).toEqual([]);
+    });
+
+    it('returns no chips when equivalences is null', () => {
+      setupWithEquivalences(null);
+      wrapper = mountComponent();
+      expect(wrapper.vm.equivalenceChips).toEqual([]);
+    });
+
+    it('returns no chips when equivalences is an empty array', () => {
+      setupWithEquivalences([]);
+      wrapper = mountComponent();
+      expect(wrapper.vm.equivalenceChips).toEqual([]);
+    });
+
+    it('drops entries with non-positive / non-finite unitCost (no div-by-zero or Infinity)', () => {
+      setupWithEquivalences([
+        { kind: 'easy', unitCost: 0, label: 'zero' },
+        { kind: 'easy', unitCost: -5, label: 'neg' },
+        { kind: 'hard', unitCost: Number.NaN, label: 'nan' },
+        { kind: 'hard', unitCost: Number.POSITIVE_INFINITY, label: 'inf' },
+        { kind: 'easy', unitCost: 200, label: 'valid' },
+      ]);
+      wrapper = mountComponent();
+      expect(wrapper.vm.equivalenceChips).toEqual([{ kind: 'easy', count: 50, label: 'valid' }]);
+    });
+
+    it('drops unknown kinds and the non-consumption feature kind', () => {
+      setupWithEquivalences([
+        { kind: 'feature', unitCost: 1, label: 'integrations' },
+        { kind: 'weird', unitCost: 10, label: 'weird' },
+        { kind: 'hard', unitCost: 2000, label: 'hard ops' },
+      ]);
+      wrapper = mountComponent();
+      expect(wrapper.vm.equivalenceChips).toEqual([{ kind: 'hard', count: 5, label: 'hard ops' }]);
+    });
+
+    it('drops entries whose label is not a string', () => {
+      setupWithEquivalences([
+        { kind: 'easy', unitCost: 200, label: 42 },
+        { kind: 'easy', unitCost: 200, label: 'ok' },
+      ]);
+      wrapper = mountComponent();
+      expect(wrapper.vm.equivalenceChips).toEqual([{ kind: 'easy', count: 50, label: 'ok' }]);
+    });
+
+    it('handles a one-shot grant (quota=0 + extras) from the remaining grant, no per-period branch', () => {
+      // free/one-shot plan: meterQuota 0, grant lives in extrasRemaining.
+      // totalRemaining = max(0, (0 + 500) - 100) = 400 → floor(400 / 200) = 2
+      setupWithEquivalences(
+        [{ kind: 'easy', unitCost: 200, label: 'easy ops' }],
+        { meterUsed: 100, meterQuota: 0, extrasRemaining: 500, weekResetAt: null },
+      );
+      wrapper = mountComponent();
+      expect(wrapper.vm.equivalenceChips).toEqual([{ kind: 'easy', count: 2, label: 'easy ops' }]);
+    });
+
+    it('renders a truthful 0 when remaining compute is exhausted', () => {
+      // totalRemaining = max(0, 500 - 1000) = 0 → count 0
+      setupWithEquivalences(
+        [{ kind: 'easy', unitCost: 200, label: 'easy ops' }],
+        { meterUsed: 1000, meterQuota: 500, extrasRemaining: 0, weekResetAt: null },
+      );
+      wrapper = mountComponent();
+      expect(wrapper.vm.equivalenceChips).toEqual([{ kind: 'easy', count: 0, label: 'easy ops' }]);
+    });
+  });
+
+  // ── #4349 — tooltip render (real chips component, open tooltip) ───────────
+
+  describe('equivalence chips render in the open tooltip (#4349)', () => {
+    beforeEach(() => {
+      if (!window.visualViewport) {
+        Object.defineProperty(window, 'visualViewport', {
+          configurable: true,
+          value: { width: 1024, height: 768, offsetTop: 0, offsetLeft: 0, addEventListener: () => {}, removeEventListener: () => {} },
+        });
+      }
+    });
+
+    afterEach(() => {
+      if (window.visualViewport) {
+        Object.defineProperty(window, 'visualViewport', { configurable: true, value: undefined });
+      }
+    });
+
+    it('renders the real chip text (count + label) inside the open tooltip', async () => {
+      const authStore = useAuthStore();
+      const billingStore = useBillingStore();
+      authStore.cookieExpire = Date.now() + 86400000;
+      authStore.serverConfig = {
+        billing: {
+          meterMode: true,
+          equivalences: [
+            { kind: 'easy', unitCost: 200, label: 'easy operations' },
+            { kind: 'hard', unitCost: 2000, label: 'heavy operations' },
+          ],
+        },
+      };
+      // Stub the mount-time fetch (the global axios mock resolves { data: null },
+      // which would async-null usageMeter across the awaits below).
+      billingStore.fetchUsageMeter = vi.fn().mockResolvedValue(undefined);
+      // totalRemaining = 10000 → 50 easy / 5 heavy
+      billingStore.usageMeter = { meterUsed: 0, meterQuota: 10000, extrasRemaining: 0, weekResetAt: null };
+
+      wrapper = mountComponent();
+      wrapper.vm.onTouchActivate(); // open the tooltip
+      await wrapper.vm.$nextTick();
+      await wrapper.vm.$nextTick();
+
+      // Tooltip content is teleported to body — assert the real chips rendered there.
+      const body = document.body.textContent || '';
+      expect(body).toContain('50 easy operations');
+      expect(body).toContain('5 heavy operations');
+    });
+  });
+
+  // ── #4349 — ring visibility motion (Slice 2) ─────────────────────────────
+
+  describe('ring motion (#4349)', () => {
+    const setupRing = (meter) => {
+      const authStore = useAuthStore();
+      const billingStore = useBillingStore();
+      authStore.cookieExpire = Date.now() + 86400000;
+      authStore.serverConfig = { billing: { meterMode: true } };
+      billingStore.usageMeter = meter;
+    };
+
+    it('isLow is false below 80%', () => {
+      setupRing({ meterUsed: 50, meterQuota: 100, extrasRemaining: 0, weekResetAt: null });
+      wrapper = mountComponent();
+      expect(wrapper.vm.isLow).toBe(false);
+    });
+
+    it('isLow is true at or above 80%', () => {
+      setupRing({ meterUsed: 80, meterQuota: 100, extrasRemaining: 0, weekResetAt: null });
+      wrapper = mountComponent();
+      expect(wrapper.vm.isLow).toBe(true);
+    });
+
+    it('wraps the ring in .nav-gauge-ring-enter (mount animation) for non-admin', () => {
+      setupRing({ meterUsed: 10, meterQuota: 100, extrasRemaining: 0, weekResetAt: null });
+      wrapper = mountComponent();
+      expect(wrapper.find('.nav-gauge-ring-enter').exists()).toBe(true);
+    });
+
+    it('applies .nav-gauge-ring-alert on the ring when usage is low', () => {
+      setupRing({ meterUsed: 90, meterQuota: 100, extrasRemaining: 0, weekResetAt: null });
+      wrapper = mountComponent();
+      expect(wrapper.find('.nav-gauge-ring-alert').exists()).toBe(true);
+    });
+
+    it('does not apply .nav-gauge-ring-alert when usage is healthy', () => {
+      setupRing({ meterUsed: 10, meterQuota: 100, extrasRemaining: 0, weekResetAt: null });
+      wrapper = mountComponent();
+      expect(wrapper.find('.nav-gauge-ring-alert').exists()).toBe(false);
+    });
+
+    it('uses the admin ring (no .nav-gauge-ring-enter wrapper) for admin users', () => {
+      const authStore = useAuthStore();
+      authStore.cookieExpire = Date.now() + 86400000;
+      authStore.serverConfig = { billing: { meterMode: true } };
+      authStore.user = { roles: ['admin'] };
+      wrapper = mountComponent();
+      expect(wrapper.find('.nav-gauge-ring-enter').exists()).toBe(false);
+      expect(wrapper.find('.nav-gauge-admin-ring').exists()).toBe(true);
+    });
+  });
 });

From 3f71ad316e3c48022a6a615663e88d7f21061093 Mon Sep 17 00:00:00 2001
From: Pierre Brisorgueil <pierrebrisorgueil@me.com>
Date: Thu, 18 Jun 2026 16:46:46 +0200
Subject: [PATCH 2/2] fix(billing): address review on the nav-gauge
 equivalences

- Header comment now quotes the exact rendered chip text (integer counts, no '~').
- Open-tooltip test captures + restores the original visualViewport descriptor
  instead of clobbering/deleting it, so it never disturbs a real/global one and
  Vuetify overlay teardown stays safe.
---
 .../billing.navComputeGauge.component.vue           |  2 +-
 .../billing.navComputeGauge.component.unit.tests.js | 13 ++++++++++++-
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/src/modules/billing/components/billing.navComputeGauge.component.vue b/src/modules/billing/components/billing.navComputeGauge.component.vue
index 04af9e179..c05d08f1d 100644
--- a/src/modules/billing/components/billing.navComputeGauge.component.vue
+++ b/src/modules/billing/components/billing.navComputeGauge.component.vue
@@ -6,7 +6,7 @@
   reflecting consumption level.
 
   Hover tooltip exposes the precise figures: "X / Y compute · resets <day>",
-  plus optional capacity chips ("~N easy / ~M heavy ops") when the server config
+  plus optional capacity chips ("N easy / M heavy ops") when the server config
   defines billing.equivalences (rendered via BillingEquivalencesChipsComponent).
   Admin users see a permanent ∞ rainbow state (no quota applies).
 
diff --git a/src/modules/billing/tests/billing.navComputeGauge.component.unit.tests.js b/src/modules/billing/tests/billing.navComputeGauge.component.unit.tests.js
index 0d26ba7f5..17dd7f376 100644
--- a/src/modules/billing/tests/billing.navComputeGauge.component.unit.tests.js
+++ b/src/modules/billing/tests/billing.navComputeGauge.component.unit.tests.js
@@ -599,7 +599,13 @@ describe('BillingNavComputeGaugeComponent', () => {
   // ── #4349 — tooltip render (real chips component, open tooltip) ───────────
 
   describe('equivalence chips render in the open tooltip (#4349)', () => {
+    let originalViewport;
+
     beforeEach(() => {
+      // jsdom lacks visualViewport (Vuetify VOverlay reads it when the tooltip opens).
+      // Capture any pre-existing descriptor and stub only when absent, so cleanup
+      // restores exactly what was there (never clobbers a real/global visualViewport).
+      originalViewport = Object.getOwnPropertyDescriptor(window, 'visualViewport');
       if (!window.visualViewport) {
         Object.defineProperty(window, 'visualViewport', {
           configurable: true,
@@ -609,7 +615,12 @@ describe('BillingNavComputeGaugeComponent', () => {
     });
 
     afterEach(() => {
-      if (window.visualViewport) {
+      // Restore the original descriptor when one existed; otherwise leave a defined
+      // `undefined` value (not a deleted property) so Vuetify overlay teardown's
+      // optional-chained reads stay safe.
+      if (originalViewport) {
+        Object.defineProperty(window, 'visualViewport', originalViewport);
+      } else {
         Object.defineProperty(window, 'visualViewport', { configurable: true, value: undefined });
       }
     });