[Unclebaffa]

Closes #1034

---

Pull Request: feat: build circuit breaker status indicator on buy form for price impact warnings (#1034)

Target Branch: dev
Closes: #1034

---

Summary

This PR implements a real-time price impact indicator and circuit breaker protection system across the key purchasing interfaces (TradeDialog modal and BuySellKeyFlow tab). When traders enter an order amount on a bonding curve, the UI dynamically assesses price impact against the key's configured circuit breaker threshold to protect buyers from predatory front-running and sudden volatility.

Key Capabilities & Architectural Additions

• Real-Time Price Impact Evaluation:

  • Evaluates marginal price impact $\left(\frac{\text{quotePrice} - \text{spotPrice}}{\text{spotPrice}} \times 100\right)$ reactively upon amount changes within $< 300\text{ ms}$.
  • Modularized mathematical utilities in src/utils/circuitBreaker.utils.ts via evaluateCircuitBreakerStatus and resolveCircuitBreakerThreshold.
  • Flexible threshold configuration: parses circuitBreakerThresholdPercent, falls back to circuitBreakerThresholdBps / 100, or defaults to 15.0%. Proximity warning triggers at $80%$ of threshold (DEFAULT_CIRCUIT_BREAKER_PROXIMITY_RATIO = 0.8).

• Three-Tier Visual State Indicator (CircuitBreakerStatusIndicator):

  State	Condition	Visual Representation	Buy Action
  Normal	$\text{Impact} < 80%$ threshold	Emerald badge with percentage & info tooltip	Enabled
  Approaching	$80% \le \text{Impact} < 100%$ threshold	Amber alert banner warning of high price impact near circuit limit	Enabled
  Breached	$\text{Impact} \ge 100%$ threshold	Critical red alert banner with explicit reduction instructions	Disabled ("Circuit Breaker Tripped")

• Hard Protection (Non-Bypassable):

  • Unlike configurable user slippage tolerances, circuit breaker limits represent hard safety boundaries.
  • When breached, the buy button is disabled, styled with disabled:cursor-not-allowed, changes text to "Circuit Breaker Tripped", and prevents submission even if triggered programmatically.

• Accessible Tooltip & Responsive Design:

  • Includes an accessible tooltip (aria-label="Circuit breaker protection info", role, keyboard focusable via Tab/Escape) detailing the automated circuit breaker mechanism.
  • Placed directly beneath the amount input on buy forms; hidden on sell forms where slippage/impact mechanics differ.

• Data Models & Page Propagation:

  • Extended Course and KeyConfig in src/services/course.service.ts to support optional circuitBreakerThresholdPercent and circuitBreakerThresholdBps.
  • Wired key configurations in CreatorDetailPage.tsx into TradeDialog.

---

Changed Files

File	Type	Description
src/utils/circuitBreaker.utils.ts	Created	Threshold resolution, proximity evaluation, status typing, and tooltip constants.
src/utils/__tests__/circuitBreaker.utils.test.ts	Created	13 unit tests for threshold precedence, boundary conditions, and proximity math.
src/components/common/CircuitBreakerStatusIndicator.tsx	Created	Reusable presentation component for impact badges, tooltips, and warning/breach banners.
src/components/common/__tests__/CircuitBreakerStatusIndicator.test.tsx	Created	7 component tests verifying badge styles, alert levels, tooltips, and zero-state handling.
src/components/common/TradeDialog.tsx	Modified	Placed indicator below amount input, disabled confirm button, updated button text, and blocked submit.
src/components/common/__tests__/TradeDialog.circuitBreaker.test.tsx	Created	6 integration tests verifying reactive updates ($< 300\text{ ms}$), approaching banners, button blocking, and exclusion from sell mode.
src/components/common/BuySellKeyFlow.tsx	Modified	Embedded indicator in buy tab, disabled review button with "Circuit Breaker Tripped", and blocked submit.
src/components/common/__tests__/BuySellKeyFlow.circuitBreaker.test.tsx	Created	5 integration tests testing threshold breach and approaching states on the key swap flow.
src/pages/CreatorDetailPage.tsx	Modified	Forwarded circuitBreakerThresholdPercent and circuitBreakerThresholdBps to TradeDialog.
src/services/course.service.ts	Modified	Added threshold properties to Course and KeyConfig.
src/test/setup.ts	Modified	Added Node 22 localStorage mock fallback for jsdom test runner environments.

---

Testing

• pnpm lint (0 errors, 0 warnings)
• pnpm build (clean production bundle generated via tsc -b && vite build)
• pnpm vitest run circuitBreaker TradeDialog.circuitBreaker BuySellKeyFlow.circuitBreaker (31 tests passed across 4 test suites)
• pnpm vitest run TradeDialog.a11y.test.tsx TradeDialog.test.tsx (17 tests passed)

---

Checklist

• Scope is limited to the stated change
• Updated docs if behavior or setup changed
• Added screenshots for UI changes when relevant (or test-covered UI DOM assertions)

[drips-wave]

@Unclebaffa Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits