aegis-swap-widget 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 0.5.0
+
+### Minor Changes
+
+- 3c4e2ba: Engine widget: add `detailsPlacement` ('up' | 'down', default 'up'). Details now
+  open as an overlay sheet rising from the bottom of the widget instead of
+  expanding inline; the widget's height no longer changes.
+- 3c4e2ba: Add host-selected history windows and mode-aware Engine metric series to the decorative sparklines, including >18h gap breaks in the shared SVG path.
+- 3c4e2ba: Add complete Engine position management and lifecycle surfaces.
+
+  - Core now exposes guarded repay, withdraw, close, and lend-withdraw flows,
+    live vault state and LTV reads, wallet-scoped position activity, fee
+    estimation, authorization checks, and transaction progress helpers.
+  - The React widget now shows existing borrow and lend positions above their
+    forms, adds live-risk and activity details, provides position management
+    sheets, and keeps review, pending, replacement, confirmation, and failure
+    states in one transaction lifecycle.
+
+- 3c4e2ba: Add REST-backed Aegis Engine markets and indexed positions (open + display; repay/redeem/close/withdraw remain deferred), protocol-correct one-token lend and collateralized borrow, rounded LP-debt carry estimates, session-safe caching, and duplicate-submit protection.
+
+  Bundle the Engine protocol implementation into public Core output so widget
+  consumers do not need private-registry credentials.
+
+  Also remove the unused `showPoolLink` widget prop (playground shared links that still carry it continue to parse; the key is ignored). Use host CSS or trade-details content if a pool explorer chip is still required.
+
+- 3c4e2ba: Highlight fresh, authoritative Engine fee surges in the market hero with the
+  observed trading-fee multiplier, while suppressing manual-override,
+  contract-inconsistent, and stale fee observations.
+- 2202655: Guard submission re-entry and keep reduced-motion/embed behavior honest.
+
+  - Double-clicking the swap CTA can no longer launch two parallel swap flows
+    with duplicate wallet prompts (both widgets).
+  - The "Connect wallet" click only connects; it no longer falls through into
+    the swap flow when an amount was already typed.
+  - Token/chain selection is inert while a swap is in flight, a pending native
+    Max fill is invalidated by typing/selection/submit, and an out-of-range
+    `defaultSlippagePercent` falls back to 1% instead of bricking the CTA.
+  - Reduced-motion polish: network dropdown and rail fade instead of snapping,
+    the chain-select flash cleans up its state, and long token symbols truncate
+    instead of crushing the amount input. Network menu state classes became
+    data attributes so host CSS can't collide; viem peer floor is `^2.23.1`.
+
+- 2202655: Add USD-aware swap fields, balance-loading states, a settings menu, and token-picker polish.
+
+  - Show amount and wallet USD values when pricing is available, while hiding invalid amount estimates.
+  - Keep backend market loading states honest and avoid contradictory no-pool CTAs during discovery.
+  - Move slippage and approval controls into the header settings menu and add single-action token-dialog network switching.
+
+### Patch Changes
+
+- Updated dependencies [3c4e2ba]
+- Updated dependencies [3c4e2ba]
+- Updated dependencies [2202655]
+- Updated dependencies [2202655]
+  - @aegis-engine/core@0.3.0
+
 ## 0.4.0
 
 ### Minor Changes

package/DESIGN.md

@@ -18,15 +18,26 @@ text), and no neutral is pure black or white. Derived accent tints
 `color-mix(in srgb, …)`, so a host can override `--aegis-swap-accent` with **any**
 CSS color (hex, `rgb()`, `oklch()`, …) and the whole accent system recomputes.
 
+The `baseColor` prop regenerates this entire neutral ramp at runtime from one
+surface color (`deriveBasePalette`, also exported): every step adopts the base
+hue with capped chroma, lightness follows the same hand-tuned envelope
+relative to the new bg, and the text steps are re-solved until primary text
+holds APCA Lc ≥ 90 / WCAG ≥ 7:1 on the panels and muted/subtle hold ≥ 4.5:1 on
+every surface — so the guarantees above survive arbitrary host input. Values
+are emitted as inline `oklch()` variables for the resolved theme; explicit
+`--aegis-swap-*` overrides in `style` win over derived ones.
+
 | Token | Role |
 | --- | --- |
 | `--aegis-swap-accent` | CTA, selected pool, focus ring, links. Host's primary knob. |
 | `--aegis-swap-accent-text` | Text on the accent CTA. Auto-derived from `accentColor`; override with `accentTextColor`. |
+| `--aegis-swap-accent-ink` | Accent used *as text on a panel* (quick-fill chips, selected pills, status links, market rate). Resolves to `--aegis-swap-accent-readable` — emitted from `accentColor` only when the raw accent falls under 4.5:1 on the panels — and falls back to the accent itself. |
 | `--aegis-swap-success` | Terminal success fill (rail, toast). |
 | `--aegis-swap-danger` | Error fill and inline error text. |
 | `--aegis-swap-bg` / `--aegis-swap-panel` / `--aegis-swap-panel-raised` / `--aegis-swap-panel-soft` | Surface ramp, darkest → most raised. |
 | `--aegis-swap-text` / `--aegis-swap-muted` / `--aegis-swap-subtle` | Text ramp, primary → tertiary. |
 | `--aegis-swap-border` / `--aegis-swap-border-strong` | Hairline and emphasized borders. |
+| `--aegis-swap-bg-hi` / `--aegis-swap-bg-mid` / `--aegis-swap-bg-lo` | Card-gradient stops ("lit from the top" spread of the bg family). |
 | `--aegis-swap-font-family` | Font family; the widget does **not** inherit the host font by default. |
 
 `theme="light"` swaps the surface/text/border/danger ramp; `accent`/`success`

package/README.md

@@ -1,6 +1,8 @@
-# Aegis Swap Widget
+# Amplifi Swap and Aegis Engine Widget
 
-Seamlessly embed Aegis Swap directly in your React application. Import the component, import the CSS, and configure networks, wallet handoff, and host styling through props.
+Embed Amplifi Swap or Aegis Engine directly in a React application. Import the
+component and CSS, then configure networks, REST data, wallet handoff, and host
+styling through props.
 
 The host app normally only renders `<AegisSwapWidget />`. Quoting, token approval, Permit2 signing, and swap submission are handled inside the widget.
 
@@ -21,7 +23,9 @@ npm install aegis-swap-widget
 
 Peer dependencies (provided by the host app): `react >=18 <20`, `react-dom >=18 <20`,
 and `viem ^2`. The package is ESM-only. Its only runtime dependencies are
-`@aegis-engine/core` (the swap engine) and `lucide-react` (icons).
+`@aegis-engine/core` and its protocol dependencies.
+The published packages are self-contained: host applications do not need a
+GitHub Packages token for the Engine SDK.
 
 ## Basic Usage
 
@@ -34,10 +38,101 @@ export function Swap() {
 }
 ```
 
-Without a `pools` prop, the widget loads Aegis config, token metadata, and market
-discovery from the production backend REST API. Pass `backendBaseUrl={null}` to
-use the bundled static WATER, WOOD, GRASS, and STONE mainnet pool configs, or
-pass `pools` when a host wants to pin its own audited pool set.
+## Engine usage
+
+```tsx
+import { AegisEngineWidget } from 'aegis-swap-widget'
+import 'aegis-swap-widget/styles.css'
+
+export function Engine({ account, provider }) {
+  return (
+    <AegisEngineWidget
+      account={account}
+      provider={provider}
+      defaultSurface="buy"
+      showTokenPriceHistory
+      showEngineMarketHistory
+      surfaces={['buy', 'borrow', 'lend', 'positions']}
+    />
+  )
+}
+```
+
+The Engine discovery surface defaults to Amplifi's public production REST API.
+The production source implements
+`GET /v1/engine/markets?chainId=`,
+`GET /v1/engine/positions/v2?chainId=&account=`, and
+`GET /v1/engine/positions/activity?chainId=&account=`, and
+`GET /v1/engine/markets/{marketId}/history?window=30d`. Position reads prefer
+v2 so borrow vaults and indexed lender shares are returned together, then fall
+back to the frozen v1 positions route only when v2 returns `404`. The UI labels
+that fallback as borrow-vault-only coverage. For REST sources, the Borrow tail
+also recovers the selected vault's latest indexed transaction from the activity
+ledger; missing activity stays display-only and never blocks quoting. When a
+host supplies a custom REST `engineDataSource`, an omitted `backendBaseUrl`
+inherits the same base URL for
+the nested Buy surface and token-price history. That origin must also expose
+`/v1/config`, `/v1/markets`, `/v1/tokens`, and the token-history route.
+
+`showTokenPriceHistory` is a separate, display-only opt-in. It reads the active
+token's price window (`tokenPriceHistoryWindow`, default `30d`) from
+`GET /v1/tokens/{chainId}/{address}/price-history` through `backendBaseUrl` and
+renders only when at least two usable points and a current market/token USD
+price are available. Missing, warming, or malformed history fails soft. The
+latest history bucket is never treated as the executable current price.
+The active token is the direct-pool target, aggregated-swap output, Engine lend
+deposit, or Engine borrow output for the current surface.
+
+`showEngineMarketHistory` is another display-only opt-in and defaults to
+`false`. In Lend or Borrow, the Details view renders the selected market's
+12-hour observations from the Engine history endpoint. The series follows
+`defaultEngineMarketHistoryMetric` (default `'rate'`): lend APY / borrow APR,
+shared utilization, or mode-aware liquidity (`suppliedUsd` vs
+`availableToBorrowUsd`). The fetch window is
+`defaultEngineMarketHistoryWindow` (default `'30d'`). The widget exposes
+loading, `warming_up`, `no_data`, incomplete, and unavailable states without
+blocking quotes or transactions. Current market details also preserve the
+backend's rate, fee, surge, and freshness fields; `surgeActive` is authoritative
+and is not inferred from `inCapEvent`.
+
+`detailsPlacement` controls where the Lend/Borrow breakdown opens. `'up'`
+(default) keeps the Details summary row in place and raises the breakdown as a
+full-width sheet inside the widget's own bounds — the row stays live and
+pressing it again (or Escape, or tapping the scrim) brings the sheet back down,
+and the widget's height never changes. `'down'` expands the breakdown inline
+below the CTA, growing the widget.
+
+A lend or borrow renders one transaction lifecycle card in the form's outcome
+slot: Review (feasible quote) → Pending (in flight) → Confirmed (mined). The
+same before → after metric rows persist across all three states — projected
+values are labeled, the network fee starts as a pre-submit estimate (approvals
+excluded) and flips to the mined fee, and the explorer action is promoted into
+the card header on confirm. `defaultTransactionDetailsOpen` (default `true`)
+sets whether the card's metric breakdown starts expanded; the Details row keeps
+its single trigger for the quote breakdown sheet.
+
+Product semantics are deliberately conservative:
+
+- A borrow requires an upfront collateral deposit.
+- Carry uses the exact rounded LP-shaped debt from the live SDK quote, not only
+  the token value received.
+- Repayment requires both pool tokens; remaining collateral is withdrawn
+  separately.
+- A one-token lend becomes a two-sided full-range LP with price and
+  impermanent-loss exposure.
+- The widget does not claim borrowing is cheaper than buying without a
+  partner-provided returnability/consumption model and duration.
+- Positions are indexed snapshots (open + display). Last-locked LTV is not
+  presented as current health. Repay, redeem, close, and withdraw flows are
+  deferred and not exposed in the widget.
+- Lender balances are indexed Engine share units, not token amounts; the widget
+  does not invent a token/USD value without a current share price.
+
+The Engine widget loads market discovery from the production REST API unless a
+host supplies `engineDataSource`. Static or offline Engine integrations use
+`engineDataSource={{ kind: 'static', markets: [...] }}`. Setting
+`backendBaseUrl={null}` disables token-price history and backend reads for the
+nested Buy surface; it does not change Engine market discovery.
 
 The backend-enabled network list comes from `GET /v1/config` (`chains[]`). By
 default the widget exposes every backend chain it can configure. Projects that
@@ -103,9 +198,10 @@ exposed as production widget props, so an embedded widget cannot accidentally
 run in a fake mode.
 
 Hosts should customize through `backendBaseUrl`, `pools`, `chains`, `rpcUrls`,
-`metadataEndpoint`, wallet/provider callbacks, status surfaces, `accentColor`,
-`accentTextColor`, `className`, `style`, `title`, and `subtitle`. The widget is
-meant to blend into a host app without forking its internals.
+`metadataEndpoint`, `showTokenPriceHistory`, `showEngineMarketHistory`,
+wallet/provider callbacks, status surfaces, `accentColor`, `accentTextColor`,
+`className`, `style`, `title`, and `subtitle`. The widget is meant to blend into
+a host app without forking its internals.
 
 Treat contract addresses as trusted integration config. Pool and chain config
 can provide `router`, `permit2`, `quoter`, `poolKey`, and `poolId`; the widget
@@ -125,15 +221,19 @@ Hosts can choose the widget surface and brand accent at instantiation time:
 
 ```tsx
 <AegisSwapWidget
-  theme="light"
-  accentColor="#006adc"
-  accentTextColor="#ffffff"
+  theme="dark"
+  accentColor="#7c5cff"
+  baseColor="#16121f"
 />
 ```
 
 `theme` supports `dark`, `light`, or `auto` (which follows the host's `prefers-color-scheme`). `accentColor` accepts any CSS color value and is used for the CTA, selected pools, focus states, links, and swap controls. The widget auto-derives a readable CTA text color from `accentColor` — for hex, `rgb()`, and `hsl()` values everywhere, and for any CSS color (named, `oklch()`, …) in the browser. `accentTextColor` overrides that and is the deterministic choice when you want an exact CTA text color (or are rendering a named/`oklch()` accent during SSR).
 
-The default accent is neutral green. Pass `accentColor`, `accentTextColor`, `title`, `subtitle`, `className`, or `style` when the widget should blend into another product UI.
+`accentColor` is applied verbatim, so wide-gamut values (`color(display-p3 …)`, high-chroma `oklch()`) render in P3 where the display supports it — only the auto-derived text/ink variants are computed in sRGB, which is safe because they solve contrast, not vibrancy.
+
+`baseColor` re-themes the whole neutral family — background, panels, borders, text, and the card gradient — from one surface color. The ramp is derived in OKLCH against the widget's hand-tuned lightness envelope: every step adopts the base hue, chroma is capped so a saturated input yields a tinted surface rather than a neon one, lightness is clamped into the active theme's band, and the text steps are solved until they pass their contrast targets (primary text ≥ APCA Lc 90 / WCAG 7:1 on the panels; secondary text ≥ 4.5:1 everywhere) — arbitrary input cannot produce unreadable text. The same color-format rules as `accentColor` apply (named/`oklch()` inputs resolve in the browser only). Individual `--aegis-swap-*` variables passed through `style` still override any derived value, and `deriveBasePalette(baseColor, 'dark' | 'light')` is exported for hosts that want the computed variables themselves (e.g. to inline them during SSR).
+
+The default accent is neutral green on a green-tinted dark surface. Pass `accentColor`, `baseColor`, `accentTextColor`, `title`, `subtitle`, `className`, or `style` when the widget should blend into another product UI.
 
 The default palette is authored in OKLCH (tinted neutrals, a calmer accent). The
 full set of host-overridable CSS variables — color, motion, rail, and toast
@@ -373,7 +473,9 @@ The widget fetches token icons by address using the metadata IDs from the Aegis
 />
 ```
 
-Use `metadataEndpoint={null}` to disable backend icon hydration. Tokens can also provide `iconUrl` directly.
+Use `metadataEndpoint={null}` to disable backend icon hydration. It does not
+disable token-price history, which uses `backendBaseUrl`. Tokens can also
+provide `iconUrl` directly.
 
 ## With Existing Wallet UI
 
@@ -431,7 +533,7 @@ Use `className` for host CSS selectors and `style` for one-off layout overrides
 />
 ```
 
-`accentColor`, `accentTextColor`, `title`, and `subtitle` are the intended props for making the widget fit a host surface without forking the component.
+`accentColor`, `baseColor`, `accentTextColor`, `title`, and `subtitle` are the intended props for making the widget fit a host surface without forking the component.
 
 ## Transaction Status
 
@@ -566,9 +668,10 @@ import 'aegis-swap-widget/styles.css'
 ```
 
 `AegisSwapToaster` props: `position` (`top`/`bottom` × `left`/`center`/`right`,
-default `'bottom-right'`), `theme`/`accentColor`/`accentTextColor` (the toaster
-portals to `document.body`, so widget-root accent variables do not reach it —
-pass these props or set `--aegis-swap-accent` and friends on `:root`),
+default `'bottom-right'`), `theme`/`accentColor`/`accentTextColor`/`baseColor`
+(the toaster portals to `document.body`, so widget-root accent and ramp
+variables do not reach it — pass these props or set `--aegis-swap-accent` and
+friends on `:root`),
 `duration` (auto-dismiss for info/success, default 5000ms), `visibleToasts`
 (default 3), `closeButton` (default `false` — swipe and auto-dismiss always
 work), `expand` (always-expanded list instead of the hover-expanded stack),
@@ -667,16 +770,22 @@ No other props changed. See the [CHANGELOG](./CHANGELOG.md) for the full entry.
 - `defaultDirection`: `buy` (counter token into the pool token) or `sell` (pool token into the counter token). Defaults to `buy`.
 - `defaultSlippagePercent`: number (canonical) or numeric string, in percent. Defaults to `1`.
 - `rpcUrls`: RPC fallback list for the active chain, or a `{ [chainId]: string[] }` map for multichain hosts.
-- `metadataEndpoint`: optional metadata GraphQL endpoint for `GlobalToken.iconURL` token icons. Set to `null` to disable.
+- `backendBaseUrl`: REST origin for Swap discovery and token-price history, and for the Engine widget's nested Buy surface. Defaults to the Aegis production backend. Engine market and position discovery is controlled separately by `engineDataSource`.
+- `backendRequestTimeoutMs`: timeout for backend REST reads. Defaults to 30000 ms.
+- `metadataEndpoint`: optional metadata GraphQL endpoint for `GlobalToken.iconURL` token icons only. Set to `null` to disable icon hydration.
+- `showTokenPriceHistory`: display a compact, fail-soft USD history for the active token through `backendBaseUrl`. Defaults to `false`.
+- `tokenPriceHistoryWindow`: `'7d' | '30d' | '90d' | '180d'` fetch/display window when token history is on. Defaults to `'30d'`. There is no in-widget window selector.
 - `className`: optional class for host layout and styling hooks.
 - `style`: optional root style object, useful for host layout constraints or CSS variables.
-- `title`: optional widget heading. Empty by default (compact topbar, no header row).
+- `title`: optional widget heading. Swap and Engine default to empty for compact embedded chrome.
+- `showNetworkSelector`: Engine header-network visibility: `'never'` (default), `'auto'`, or `'always'`. Cross-chain markets and tokens remain available in the full selectors when the header rail is hidden.
+- `showBuySettings`: show the Engine Buy surface's slippage-settings control. Defaults to `false`.
 - `subtitle`: optional header eyebrow. Defaults to empty. Pass a string to show it.
-- `ariaLabel`: optional accessible label for the widget region.
+- `ariaLabel`: optional accessible label for the widget region. Defaults to `Swap` for Swap and `Lend, borrow, and buy` for Engine.
 - `theme`: `dark`, `light`, or `auto` (follows `prefers-color-scheme`). Defaults to `dark`.
 - `accentColor`: CSS accent color for the CTA, selected pools, focus states, links, and swap controls. When set without `accentTextColor`, the widget derives a readable CTA text color automatically (see Appearance for supported color formats).
 - `accentTextColor`: optional CTA text color for contrast with the chosen accent.
-- `showPoolLink`: whether to render the direct-pool link when the active chain provides `poolExplorerUrl`.
+- `baseColor`: CSS base surface color; derives the full neutral ramp (background, panels, borders, text, card gradient) in OKLCH for the active theme with contrast enforced (see Appearance).
 - `defaultApprovalMode`: `exact` approves only the current quote spend by default; `max` opts into the old unlimited ERC-20 to Permit2 approval behavior.
 - `showApprovalMode`: whether the details drawer exposes the Exact/Max approval toggle. Defaults to `true`.
 - `showExecutionDetails`: whether to render the collapsible drawer for trade details and, after a confirmed swap, the session-local Latest tx receipt. Defaults to `true`.