aegis-swap-widget 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,7 +5,124 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.3.0] - 2026-06-08
+
+### Removed (breaking)
+- `targets` prop — use `poolIds` (identical `string[]` shape).
+- `markets` prop — use `pools`; `Object.values(markets)` migrates an existing map.
+- `defaultDirection` values `'intoTarget'` / `'outOfTarget'` — use `'buy'` / `'sell'`.
+
+### Changed (breaking)
+- Renamed `showApprovalModeControl` → `showApprovalMode`, pairing it with
+  `defaultApprovalMode`.
+
+### Migration
+- `targets={ids}` → `poolIds={ids}`
+- `markets={map}` → `pools={Object.values(map)}`
+- `defaultDirection="intoTarget"` → `defaultDirection="buy"`
+- `defaultDirection="outOfTarget"` → `defaultDirection="sell"`
+- `showApprovalModeControl={x}` → `showApprovalMode={x}`
+
+### Internal
+- Refactored the widget into a `useSwapController` hook (state, derivation, and
+  hook orchestration) over a thin presentational component, decomposed the swap
+  money path into pure `src/swap/` modules (`authorizePermit`,
+  `executeSwapTransaction`), and unified the host-callback emitters behind a
+  single `useChangeEmitter` primitive. No public behavior change.
+
+### Added
+- Toast notifications as an alternative transaction-status surface: new
+  `statusSurface` prop (`'rail'` default, `'toast'`, `'both'`, `'none'`) plus
+  `toastPosition`. One toast per swap attempt morphs loading → success/error in
+  place with the received amount and a View transaction action; wallet
+  rejections auto-dismiss after 4s, other errors after 8s. The root
+  `data-progress-state` attribute stays on for every surface.
+- `AegisSwapToaster` export: the toast viewport as a standalone component.
+  Mounting it anywhere takes over rendering from widget-provided toasters —
+  exactly one viewport per page — and owns `position`, `theme`/`accentColor`,
+  `duration`, `visibleToasts`, `closeButton`, `expand`, and `offset`. Toasts
+  stack with depth, expand on hover/focus, swipe-to-dismiss with momentum
+  (interruptible CSS transitions throughout), dismiss on Escape when focused,
+  pause their timers while hovered, mid-swipe, and in hidden tabs, and reduce
+  to fades under `prefers-reduced-motion`. Lifecycle morphs replay quiet icon
+  and text entrances in place, and terminal states tint the card border
+  (success whisper, error alarm) the way the progress rail recolors. The
+  viewport is hardened for arbitrary host pages: host `li`/text styling
+  cannot leak in, toasts hide in print, and the light theme keeps icon
+  contrast AA without overriding an explicit host accent.
+- `aegisToast` export: toast function for host apps sharing the same viewport —
+  `aegisToast()` / `.info` / `.success` / `.error` / `.loading` / `.dismiss` /
+  `.promise`, with upsert-by-id morphing. New public types
+  `AegisSwapToasterProps`, `AegisSwapStatusSurface`, `AegisToastAction`,
+  `AegisToastOptions`, `AegisToastPosition`, `AegisToastType`, and
+  `AegisToastPromiseMessage`/`AegisToastPromiseMessages`.
+- `onPoolChange` prop: fires with the active pool id whenever it changes —
+  user tab selection or a `poolIds` update that forces a fallback. Silent on
+  mount, so hosts only hear genuine transitions.
+- `resolveTokenIconUrl` export (plus the `TokenMetadataByAddress` type): the
+  widget's own icon-source order — config `iconUrl`, metadata service, ichi
+  naming guess — so hosts rendering their own token marks resolve identically.
+- `onStatusChange` prop: fires a lifecycle snapshot (`status`, `progress`, `txHash`,
+  `error`, `label`, rail geometry, and `walletPrompts`) on every transition, mirroring
+  the top progress rail — including errors and wallet rejections, which never appear
+  as a `status`. `walletPrompts.total/completed/active` exposes the SDK-owned provider
+  prompt plan for ERC20 approval, Permit2 authorization, and swap submission.
+- `AegisSwapProgressRail` export: the widget's animated top rail as a standalone
+  component hosts can mount on their own containers, themed via `--aegis-swap-accent`,
+  `--aegis-swap-danger`, and `--aegis-swap-success` (the rail CSS now carries literal
+  dark-theme fallbacks for use outside the widget root).
+- Host-tunable top rail tokens: `--aegis-rail-height`, `--aegis-rail-hold`, and
+  `--aegis-rail-fade` via the widget `style` prop. The success auto-reset reads the
+  computed hold/fade values so host-tuned terminal animations and status cleanup stay
+  synchronized.
+- The top rail now separates completion from activity: `completePct` tracks completed
+  wallet-provider prompts, while pending/mining shimmer always sweeps the full top
+  border instead of starting from the completed fill.
+- `networkOptions` prop plus `AegisSwapNetworkOption`/`AegisSwapNetworkIcon` types:
+  a display-only network menu list for previewing upcoming chains — non-selected
+  options render disabled by default with optional `status` text; a list without
+  the active chain gets it prepended; switching is not wired yet.
+- Public types `AegisSwapStatusSnapshot`, `AegisSwapWalletPromptProgress`,
+  `SubmitStatus`, `TransactionProgressState`, and the `isUserRejectedError` helper.
+
+### Changed
+- The branded header (`title`/`subtitle`) is now text-only: the Aegis logomark no longer
+  renders next to host-provided titles. Aegis attribution lives solely in the
+  "Powered by Aegis" footer.
+- The trade-details toggle no longer compensates ancestor scroll position when
+  expanding or collapsing; the panel expands in place.
+- Hover styles apply only on hover-capable devices (`@media (hover: hover)`), so taps
+  on touch screens no longer leave stuck hover states (raised tabs, rotated flip arrows).
+- The direction-flip arrows now spin when the direction actually flips (driven by a
+  `data-direction` attribute) instead of pre-playing the rotation on hover.
+- A busy CTA reads as working, not blocked: while approving/signing/submitting the
+  submit button keeps near-full opacity, shows a `progress` cursor, and runs a soft
+  sheen (`data-busy` attribute, motion-gated).
+- Status feedback eases in instead of popping: error/success lines and the explorer
+  link get a staggered fade-rise, and the success line opens with a self-drawing
+  check ("Swap complete · received ~…", previously an em dash).
+- Network-menu rows cascade in as the menu opens (30ms steps, reduced-motion safe),
+  and the menu's overlay shadow is re-tuned for the light theme.
+- Switching feels like one control: the pool tabs and the Exact/Max approval
+  segments glide a single active pill between options instead of cross-fading
+  two buttons, and the Sell/Buy token pills cross-fade when a switch retargets
+  them. New `--aegis-switch-dur`/`--aegis-spring` tokens (overridable via the
+  `style` prop) drive it; reduced-motion safe.
+- Concentric corner radii on nested chrome: pool tab rail, network menu, approval
+  segments, and the trade-details toggle now derive outer radius = inner + padding.
+- The trade-details panel sheds visual weight: approval segments and route actions
+  drop from 40px to 26px (keeping control-height touch targets via invisible
+  extensions), the route chip loses its divider hairlines and dead drop shadow, the
+  active pill is fill-only, and the setting rows tighten to 38px with unified 12px
+  labels.
+
+### Fixed
+- Keyboard focus no longer reshapes controls: the global `:focus-visible` rule forced
+  a 6px border-radius onto every focused element, visibly squaring the circular flip
+  button; the ring now follows each element's own radius.
+- The slippage input no longer triggers iOS Safari's focus auto-zoom (16px input font
+  on coarse pointers).
+- The network trigger's touch target is extended to ~44px without growing the chip.
 
 ## [0.2.0] - 2026-06-05
 
@@ -75,7 +192,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial embeddable direct-pool Aegis swap widget for WATER, WOOD, GRASS, and STONE.
 - Generic pool widget API; ERC-20 → Permit2 approval and Permit2 batch signing.
 
-[Unreleased]: https://github.com/amplifi-liquidity/aegis-widget/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/amplifi-liquidity/aegis-widget/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/amplifi-liquidity/aegis-widget/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/amplifi-liquidity/aegis-widget/compare/v0.1.3...v0.2.0
 [0.1.3]: https://github.com/amplifi-liquidity/aegis-widget/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/amplifi-liquidity/aegis-widget/compare/v0.1.0...v0.1.2

package/DESIGN.md

@@ -0,0 +1,77 @@
+# Design tokens
+
+The widget themes through CSS custom properties on the `.aegis-swap-widget` root
+(and the toast viewport). This file is the reference for the **public** tokens —
+the ones a host may override and depend on. Set them inline via the `style` prop,
+in a stylesheet on an ancestor, or per-toaster via `AegisSwapToaster`.
+
+Renaming or removing anything in the tables below is a breaking (major) change.
+Tokens prefixed `--aegis-_*` are internal and may change without notice.
+
+## Color
+
+The default palette is authored in **OKLCH**: neutrals are tinted toward the
+brand hue (~165) so the surface reads as one family, each step's lightness is
+matched to keep text contrast (subtle/muted stay ≥ 4.5:1 on the panel for 12px
+text), and no neutral is pure black or white. Derived accent tints
+(`--aegis-swap-accent-soft/-line/-glow/-ring`) are computed with
+`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.
+
+| 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-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-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`
+carry across both themes. `theme="auto"` follows `prefers-color-scheme`.
+
+## Motion
+
+All motion is CSS and respects `prefers-reduced-motion` automatically.
+
+| Token | Default | Role |
+| --- | --- | --- |
+| `--aegis-switch-dur` | `260ms` | Segmented-pill glide and Sell/Buy token swap. `0ms` disables. |
+| `--aegis-spring` | `cubic-bezier(0.22, 1, 0.36, 1)` | Easing for interactive state changes. |
+| `--aegis-ease` | `cubic-bezier(0.2, 0, 0, 1)` | Easing for entrances and transitions. |
+
+The pool-tab/approval-segment open is intentionally slower than the close
+(enter-slow, exit-fast); that asymmetry is by design, not a value to "correct".
+
+## Progress rail
+
+| Token | Default | Role |
+| --- | --- | --- |
+| `--aegis-rail-height` | `3px` | Rail thickness. |
+| `--aegis-rail-hold` | `3000ms` | How long the terminal state holds before fading. |
+| `--aegis-rail-fade` | `420ms` | Terminal fade-out duration. |
+
+`--aegis-rail-hold` / `--aegis-rail-fade` must be CSS time strings (`ms`/`s`):
+the widget reads the computed values at runtime to keep the success auto-reset in
+sync with the host-tuned animation. These also apply to the standalone
+`AegisSwapProgressRail`.
+
+## Toasts
+
+The toast viewport portals to `document.body`, so widget-root variables do **not**
+reach it — set these on `:root` or pass `AegisSwapToaster` props.
+
+| Token | Role |
+| --- | --- |
+| `--aegis-swap-toast-z` | Stacking context for the viewport. |
+| `--aegis-swap-toast-width` | Toast card width. |
+| `--aegis-swap-toast-offset-x` / `--aegis-swap-toast-offset-y` | Viewport inset from the chosen corner. |
+
+## Internal tokens
+
+`--aegis-r-sm/-md/-lg` (radii), `--aegis-seg-*` (segment chrome),
+`--aegis-swap-shell`, and any `--aegis-_*` primitive are internal implementation
+details. They are not part of the supported theming surface and may change
+between minor versions.

package/README.md

@@ -19,6 +19,9 @@ bundled config sets one; today only Ethereum mainnet is bundled.
 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 and ships no runtime dependencies of its own.
+
 ## Basic Usage
 
 ```tsx
@@ -39,6 +42,32 @@ Token icons are hydrated from the same metadata table used by the Aegis website:
 `GlobalToken.iconURL` from the Aegis metadata GraphQL API. The default endpoint is
 `https://aegis.markets/graphql/meta`.
 
+## Headless Core
+
+Use the root import for the React widget and CSS. Use the `/core` entry when a
+host, backend-backed client, or future query layer needs the swap primitives
+without importing the widget UI:
+
+```ts
+import {
+  AEGIS_SWAP_MARKETS,
+  createSwapPublicClient,
+  fetchDirectSwapQuote,
+} from 'aegis-swap-widget/core'
+```
+
+The core entry exports chain and pool config helpers, quote fetching, calldata
+encoding, Permit2 helpers, wallet/provider utilities, metadata fetchers, and the
+pure transaction-progress helpers. It does not import the React widget or the
+package stylesheet.
+
+To render token icons with the widget's exact resolution order (config
+`iconUrl` → metadata endpoint → ICHI guess), use `resolveTokenIconUrl`:
+
+```ts
+import { resolveTokenIconUrl, fetchGlobalTokenMetadata } from 'aegis-swap-widget/core'
+```
+
 ## Appearance
 
 Hosts can choose the widget surface and brand accent at instantiation time:
@@ -55,6 +84,10 @@ Hosts can choose the widget surface and brand accent at instantiation time:
 
 The default accent is neutral green. Pass `accentColor`, `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
+tokens — is documented in [DESIGN.md](./DESIGN.md).
+
 ## Configure Pools
 
 Pass the direct pools you want to expose. This is the recommended integration path because it is not tied to any specific asset list.
@@ -272,6 +305,214 @@ 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.
 
+## Transaction Status
+
+The widget paints swap progress on a rail along its own top edge — an accent
+sweep while pending/mining, solid green on success, solid red on errors
+(including wallet rejections), then a short hold and fade. The rail is the
+default of two built-in status surfaces; `statusSurface` switches to toast
+notifications, shows `'both'`, or `'none'` (see Toasts below). Hosts can tune
+the rail through the widget's `style` prop:
+
+```tsx
+<AegisSwapWidget
+  style={{
+    '--aegis-rail-height': '4px',
+    '--aegis-rail-hold': '1800ms',
+    '--aegis-rail-fade': '260ms'
+  }}
+/>
+```
+
+Use CSS time strings (`ms` or `s`) for `--aegis-rail-hold` and
+`--aegis-rail-fade`; the widget reads the computed tokens at runtime so the
+success auto-reset stays in sync with the host-tuned animation. Hosts can
+mirror that state outside the widget three ways:
+
+`onStatusChange` fires a snapshot on every lifecycle transition. `walletPrompts`
+is the SDK-owned provider-prompt plan: ERC20 approval, Permit2 authorization,
+and swap submission are counted from the current allowance/authorization reads.
+Use that for step copy or external rails instead of guessing from status names:
+
+```tsx
+<AegisSwapWidget
+  onStatusChange={({ status, progress, walletPrompts, txHash, error }) => {
+    // status:   'idle' | 'approving' | 'signing' | 'submitting' | 'success'
+    // progress: 'pending' | 'mining' | 'success' | 'error' | null (rail hidden)
+    // walletPrompts: { total, completed, active } // active is 1-based or null
+    // error:    user-facing message, e.g. "Request rejected."
+  }}
+/>
+```
+
+The rail separates step completion from activity: `completePct` fills the calm
+completed portion (for example 33.3% after one of three wallet prompts), while
+the pending/mining shimmer is always a full-width top-border sweep.
+
+Errors never appear in `status` (the submit machine resets to `'idle'`); read
+them from `progress === 'error'` plus `error`. For classifying the raw `Error`
+from `onError`, `isUserRejectedError` is exported.
+
+Success clears itself after confirming (by default a 3s hold plus the 420ms
+rail fade-out), the widget resets and emits a final
+`{ status: 'idle', progress: null }` snapshot. Errors persist until the
+user interacts with the widget again — the in-widget rail fades out visually,
+but the last snapshot and `data-progress-state` keep reporting `'error'`,
+matching the widget's own inline error message.
+
+`AegisSwapProgressRail` renders the animated rail standalone — mount it inside
+any `position: relative` container and feed it the snapshot's `progress`:
+
+```tsx
+import { useState } from 'react'
+import {
+  AegisSwapProgressRail,
+  AegisSwapWidget,
+  type AegisSwapStatusSnapshot
+} from 'aegis-swap-widget'
+import 'aegis-swap-widget/styles.css'
+
+export function CheckoutHeader() {
+  const [status, setStatus] = useState<AegisSwapStatusSnapshot | null>(null)
+
+  return (
+    <>
+      <AegisSwapWidget onStatusChange={setStatus} />
+
+      <header style={{ position: 'relative' }}>
+        <AegisSwapProgressRail
+          state={status?.progress ?? null}
+          label={status?.label ?? undefined}
+          completePct={status?.completePct ?? undefined}
+          activeWidthPct={status?.activeWidthPct ?? undefined}
+        />
+        My checkout
+      </header>
+    </>
+  )
+}
+```
+
+Driven from `progress` alone, the standalone rail uses simplified geometry — a
+full-width sweep while in flight, solid fill when terminal. Feed the snapshot's
+`completePct` and `activeWidthPct` to mirror the in-widget prompt-aware fill.
+Theme it by setting `--aegis-swap-accent` (plus
+`--aegis-swap-danger` and `--aegis-swap-success` for the terminal fills) on an
+ancestor. `--aegis-rail-height`, `--aegis-rail-hold`, and
+`--aegis-rail-fade` apply to the standalone rail as CSS too; only the in-widget
+auto-reset timer reads those motion tokens. The built-in color fallbacks are
+the dark-theme values, so light hosts should set them.
+
+For CSS-only hooks, the widget root mirrors the rail as
+`data-progress-state="pending | mining | success | error"`, so a host
+stylesheet can react without JavaScript. The attribute stays on for every
+`statusSurface`, including `'toast'` and `'none'`.
+
+## Toasts
+
+`statusSurface="toast"` replaces the rail with toast notifications; `'both'`
+shows rail and toasts, `'none'` neither. With `'toast'` or `'both'` the widget
+provides its own toast viewport — no extra setup:
+
+```tsx
+<AegisSwapWidget statusSurface="toast" toastPosition="bottom-right" />
+```
+
+One toast per swap attempt morphs through the lifecycle: a loading card
+follows the same wallet-prompt copy as the rail, then settles into success
+(received amount plus a View transaction link) or error in place. Wallet
+rejections auto-dismiss after 4s and other errors after 8s — the widget's
+inline error message and `data-progress-state` persist regardless. A retry
+withdraws the previous attempt's toast and starts a fresh one.
+
+Mounting `<AegisSwapToaster />` anywhere in the app takes over rendering from
+every widget-provided toaster — exactly one toast viewport exists per page —
+which is how hosts control placement and toast options:
+
+```tsx
+import { AegisSwapToaster, AegisSwapWidget } from 'aegis-swap-widget'
+import 'aegis-swap-widget/styles.css'
+
+<AegisSwapWidget statusSurface="toast" />
+<AegisSwapToaster position="top-right" theme="light" accentColor="#006adc" closeButton />
+```
+
+`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`),
+`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),
+`offset` (viewport inset, default 24px / 16px on small screens), `className`,
+and `style` (e.g. `'--aegis-swap-toast-z'`, `'--aegis-swap-toast-width'`).
+
+The toast system is the widget's own implementation, not a dependency: toasts
+stack with depth, hovering (or focusing) the stack expands it into a list,
+swiping toward the nearest viewport edge dismisses (momentum-based — a quick
+flick is enough), auto-dismiss timers pause while hovered, while swiping, and
+in hidden tabs, and `prefers-reduced-motion` reduces all motion to fades.
+
+`aegisToast` is exported so host apps can fire their own toasts through the
+same viewport — a plain function, no hooks or context:
+
+```tsx
+import { aegisToast } from 'aegis-swap-widget'
+
+aegisToast('Copied')                            // info
+aegisToast.success('Saved', { description: 'Order #1204' })
+aegisToast.error('Could not save', { duration: 8000 })
+
+const id = aegisToast.loading('Uploading…')     // sticky until updated
+aegisToast.success('Uploaded', { id })          // reusing an id morphs in place
+
+aegisToast.promise(save(), {
+  loading: 'Saving…',
+  success: (result) => `Saved ${result.name}`,
+  error: (reason) => (reason instanceof Error ? reason.message : 'Save failed')
+})
+```
+
+Every creator returns the toast id. Actions render as a new-tab link
+(`{ label, href }`) or a button (`{ label, onClick }`); acting on a toast
+dismisses it. `duration: Infinity` keeps a toast until dismissed;
+`dismissible: false` hides the close affordance and blocks swiping. One caveat
+shared with every module-store toast library: two bundled copies of the
+package keep two independent toast stores (and two viewports).
+
+## Motion
+
+Switching pools or the approval mode glides a single active pill between the
+options (iOS-segmented-control style), and the Sell/Buy token pills cross-fade
+when a switch retargets them. It is all CSS — no animation library — and every
+animation respects `prefers-reduced-motion` automatically.
+
+Hosts tune or disable the switch motion through CSS tokens on the `style` prop:
+
+```tsx
+<AegisSwapWidget
+  style={{
+    '--aegis-switch-dur': '180ms', // pill glide + token swap; '0ms' disables
+    '--aegis-spring': 'cubic-bezier(0.2, 0, 0, 1)' // switch easing
+  }}
+/>
+```
+
+## Migrating to 0.3.0
+
+0.3.0 removes the props that were deprecated in 0.2.x. The replacements are
+drop-in:
+
+| Removed | Use instead |
+| --- | --- |
+| `targets={[...]}` | `poolIds={[...]}` (same `string[]`) |
+| `markets={map}` | `pools={Object.values(map)}` |
+| `defaultDirection="intoTarget"` | `defaultDirection="buy"` |
+| `defaultDirection="outOfTarget"` | `defaultDirection="sell"` |
+| `showApprovalModeControl` | `showApprovalMode` |
+
+No other props changed. See the [CHANGELOG](./CHANGELOG.md) for the full entry.
+
 ## Props
 
 - `provider`: optional EIP-1193 provider. Defaults to auto-detected `window.ethereum`.
@@ -282,13 +523,15 @@ Use `className` for host CSS selectors and `style` for one-off layout overrides
 - `onSuccess`: `({ hash, explorerUrl, swap? })` fired when the receipt confirms.
 - `onError`: `(error)` fired on approval/swap failures (after the widget shows its own message).
 - `onQuote`: `(quote)` fired on every quote refresh.
+- `onStatusChange`: `(snapshot)` fired on every lifecycle transition with what the top progress rail shows (see Transaction Status).
+- `onPoolChange`: `(poolId)` fired when the active pool changes — user selection or a `poolIds` update that forces a fallback. Silent on mount.
 - `chainId`: active chain id. Defaults to Ethereum mainnet.
 - `chains`: optional chain config overrides or additional chain configs, including per-chain `v4Contracts`.
+- `networkOptions`: optional display-only entries for the network menu (`{ id, name, icon?, selected?, disabled?, status? }`). The active entry is resolved by explicit `selected: true`, else by `id` matching the active chain id, else by `name`; a list without the active chain gets it prepended so the trigger never misreports the chain in use. Non-selected options render disabled by default with optional `status` text (e.g. "Coming soon"); `icon` is `'ethereum' | 'base'`. Clicking the enabled option only closes the menu (disabled options ignore clicks) — switching is not wired yet.
 - `pools`: direct pool configs to render and swap against. This is the canonical config path.
 - `defaultPoolId`: initial pool id when `pools` is provided.
 - `poolIds`: optional pool id order/subset. Use this when the host wants to hide pools or control ordering.
-- `defaultDirection`: `buy` (counter token into the pool token) or `sell`. The legacy `intoTarget`/`outOfTarget` values still work but are deprecated.
-- `markets`: **deprecated** advanced override; pass `pools` (or `Object.values(markets)`) instead.
+- `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.
@@ -302,9 +545,11 @@ Use `className` for host CSS selectors and `style` for one-off layout overrides
 - `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`.
 - `defaultApprovalMode`: `exact` approves only the current quote spend by default; `max` opts into the old unlimited ERC-20 to Permit2 approval behavior.
-- `showApprovalModeControl`: whether the details drawer exposes the Exact/Max approval toggle. Defaults to `true`.
+- `showApprovalMode`: whether the details drawer exposes the Exact/Max approval toggle. Defaults to `true`.
 - `showExecutionDetails`: whether to render the collapsible settings drawer for slippage, approval mode, and route. Defaults to `true`.
 - `defaultExecutionDetailsOpen`: whether that settings drawer starts expanded. Defaults to `false`.
+- `statusSurface`: where transaction status is surfaced — `'rail'` (default), `'toast'`, `'both'`, or `'none'`. The root `data-progress-state` attribute stays on regardless (see Toasts).
+- `toastPosition`: viewport corner for the widget-provided toaster. Defaults to `'bottom-right'`; ignored once a host mounts `<AegisSwapToaster />`.
 
 The widget intentionally does not inherit the host font; set the
 `--aegis-swap-font-family` CSS variable (via `style` or a stylesheet) to match
@@ -365,7 +610,7 @@ git switch main && git pull
 npm ci
 npm run typecheck && npm run test && npm run build
 # Move CHANGELOG [Unreleased] entries under the new version heading.
-npm version patch            # e.g. 0.1.2 -> 0.1.3; commits and tags vX.Y.Z
+npm version minor            # e.g. 0.2.1 -> 0.3.0 for a breaking 0.x release; commits and tags vX.Y.Z
 git push origin main --follow-tags
 npm publish --access public  # prepublishOnly gate + prepack build run automatically
 npm view aegis-swap-widget version