aegis-swap-widget 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## 0.9.0
+
+### Minor Changes
+
+- c76ba41: Add Engine Long/Short trading.
+
+  Core sizes a directional position against one block-pinned Engine state and v4
+  route, then opens it in a single atomic router call. The swap settles inside the
+  transaction, so the wallet signs only the authorizations it must.
+
+  The widget gains an opt-in `'trade'` surface and a dedicated one-view
+  `AegisLeverageWidget`. Leverage limits come from the quote, alongside the
+  trader-facing risk facts for the position. Authorization reports its request
+  count per chain, and a review step is mandatory before submission but stays
+  customizable. Permissions are granted in sequence, each with its own checkpoint;
+  after a partial failure the revoke guidance for what was already granted stays
+  on screen. A successful open links through to Positions.
+
+  Position identity survives a reload: the strategy is reconstructed from indexed
+  opening actions, with optional bounded persistence of the reviewed target
+  scenario.
+
+- 1e7a963: Keep the Leverage Positions surface trader-first and evidence-backed.
+
+  Only positions with strict indexed Long/Short evidence appear in the Leverage
+  widget. Ordinary borrow vaults remain in the portfolio presentation and are no
+  longer relabelled as trades while classification loads or fails. Stored opening
+  intents enrich matching indexed strategies but never classify a vault alone.
+
+  The collapsed trade row removes the borrow-rate runway, LTV bar, and
+  credit-product language. It shows direction, pair, opening-plan leverage, and a
+  signed underlying price move only while a fresh on-chain pool mark is available.
+  It does not call that move PnL or return. The detail keeps the reviewed
+  entry→target plan, and live debt/equity use the Engine liquidity-debt valuation
+  instead of deriving dollars or leverage from the protocol LTV ratio.
+  When NFT/LP collateral is attached and cannot be valued from the live idle
+  balances, the widget omits total equity rather than presenting a partial value.
+
+  "Last activity" now appears only when something actually happened after the
+  open. On an untouched lot it restated the opening date the collapsed row already
+  carries — one fact wearing two formats.
+
+### Patch Changes
+
+- 1e7a963: Unify the failure taxonomy and remove dead-end error states.
+
+  Core now owns one error classifier: `classifyError` returns curated copy plus a
+  failure `kind` and `retryable` flag, `UserFacingError` accepts both, and
+  `errorMessage` stays as a message-only compat wrapper. Wallet-cancelled sends
+  and not-ready Engine markets keep their curated copy instead of collapsing to a
+  generic fallback, and a not-ready market is marked non-retryable so retry CTAs
+  suppress.
+
+  The widget re-exports the core classifier (removing its diverged fork), catches
+  core's `TransactionReceiptTimeoutError` (hash included, explorer-link
+  messaging) instead of viem's unreachable timeout, retries failed Engine market
+  discovery via a Try again button and on refocus, turns a failed allowance check
+  into an enabled Try again CTA, labels fallback-served Engine data as
+  "last known" with a retry, derives inline errors from one precedence object
+  (submit failures outrank background quote failures), and keeps raw backend
+  error text out of the inline alert (widget log only).
+
+- 1e7a963: Hug Engine onboarding sheets to their content and end leverage opens on a trading success screen with See position and Open another.
+- Updated dependencies [1e7a963]
+- Updated dependencies [c76ba41]
+- Updated dependencies [1e7a963]
+  - @aegis-engine/core@0.5.0
+
+## 0.8.0
+
+### Minor Changes
+
+- 127be2b: Add trusted Aegis Engine v1.0.3 deployment support for Robinhood Chain, upgrade the Engine SDK to 0.33.0, and bundle Robinhood Chain network artwork in the widget. Redeem quotes now return execution fields only for an SDK-verified frame, and an execution-gated redeem that the Engine assessed above the post-redeem utilization cap reports `utilization-blocked`.
+
+### Patch Changes
+
+- Updated dependencies [127be2b]
+  - @aegis-engine/core@0.4.0
+
 ## 0.7.0
 
 ### Minor Changes

package/DESIGN.md

@@ -45,7 +45,8 @@ carry across both themes. `theme="auto"` follows `prefers-color-scheme`.
 
 ## Motion
 
-All motion is CSS and respects `prefers-reduced-motion` automatically.
+Motion uses CSS and the browser Web Animations API. No third-party animation
+runtime ships with the widget, and `prefers-reduced-motion` is respected.
 
 | Token | Default | Role |
 | --- | --- | --- |

package/README.md

@@ -4,7 +4,9 @@ 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.
+Choose `<AegisSwapWidget />` for a swap-only embed or
+`<AegisEngineWidget />` for Buy, Borrow, Lend, and Positions. Quoting, token
+approval, Permit2 signing, and transaction submission stay inside the widget.
 
 In the direct-pool widget, typing in the Sell field creates an exact-input swap
 and typing in the Buy field creates an exact-output swap. Active quotes refresh
@@ -52,14 +54,105 @@ export function Engine({ account, provider }) {
       defaultSurface="buy"
       showTokenPriceHistory
       showEngineMarketHistory
-      surfaces={['buy', 'borrow', 'lend', 'positions']}
+      surfaces={['buy', 'trade', 'borrow', 'lend', 'positions']}
     />
   )
 }
 ```
 
+## Trade surface
+
+`'trade'` is opt-in. The default tab set is `['buy', 'borrow', 'lend',
+'positions']`, so the tab appears only when a host lists `'trade'` in
+`surfaces`.
+
+The surface opens a directional position in one atomic Engine router call:
+create a fresh vault, deposit the user's token, borrow, swap through the same
+Uniswap v4 pool, redeposit the output, and lock the vault. The quote pins the
+Engine state and v4 route to one block, applies the selected slippage floor, and
+re-quotes after wallet authorization before submission.
+
+The user chooses Long or Short, a deposit, and leverage inside the live range
+returned by the quote. The widget shows opening LTV against the borrow limit,
+gross return at the configured target, entry-to-target price, opening price
+impact, and interest over the configured horizon. Engine positions do not have
+a single liquidation price; interest accrual increases LTV over time.
+
+For a separate Long/Short experience that starts without
+Buy/Borrow/Lend/Positions tabs, mount `AegisLeverageWidget`:
+
+```tsx
+import { AegisLeverageWidget } from 'aegis-swap-widget'
+import 'aegis-swap-widget/styles.css'
+
+export function LongShort({ account, provider }) {
+  return (
+    <AegisLeverageWidget
+      account={account}
+      provider={provider}
+      chains={engineChains}
+      engineDataSource={{ kind: 'rest', baseUrl: '/api/engine' }}
+      tradeLeverageOptions={[1.25, 1.5, 2, 3]}
+      defaultTradeLeverage={1.5}
+      onboarding={{ mode: 'guided' }}
+    />
+  )
+}
+```
+
+This is the frontend integration interface; the host does not call the Engine
+SDK directly. The host still supplies wallet connectivity, chain/router
+configuration, and an Engine data source or same-origin proxy. Trade offers
+only markets that support borrowing and have the required trusted execution
+addresses.
+
+After a deposit is entered, the leverage slider reads the feasible minimum and
+maximum from the live Engine quote. The range recalculates for the amount,
+direction, market, horizon, price scenario, liquidity, and slippage. Presets
+are shortcuts, not protocol limits. If a live bound moves past the selected
+target, the widget shows an explicit error and does not silently clamp it.
+
+After confirmation, Positions reconstructs Long/Short direction and executed
+entry price from the indexed opening transaction returned by
+`GET /v1/engine/positions/activity`. A normal Borrow swap has a final
+wallet-side withdrawal and is not labeled as a trade. The Leverage Positions
+tab shows only vaults whose activity proves the Long/Short recipe; ordinary
+borrow vaults remain in the unified portfolio. The reviewed average
+leverage and target are off-chain scenario inputs, so the widget stores only
+those fields after the receipt confirms. Omit `tradePositionStorage` for
+origin-local `localStorage`, pass `null` to keep only indexed facts, or provide
+an authenticated async adapter for cross-device continuity. Stored metadata is
+joined by chain, account, pool, and opening transaction hash; it cannot
+override indexed direction or entry price. A no-swap opening has no indexed
+direction signal and remains a generic position.
+
+The success sheet retains the reviewed risk snapshot and transaction link.
+`AegisLeverageWidget` then reveals a Positions entry; indexed data can take a
+moment to appear.
+
+`guided` is the default onboarding mode. It keeps optional education available
+through **How it works** without opening it automatically. Set
+`onboarding={{ showBeforeConnect: true }}` to open it once for a browser that
+has not dismissed it. Both `guided` and `contextual` use a required review
+sheet. The sheet freezes the displayed position, reads
+the connected account's current vault and token permissions, and lists only
+the missing wallet actions before the final open transaction. A zero-first
+ERC-20 reset is shown as a separate wallet prompt. The submit path re-reads the
+permissions and obtains a fresh executable quote; the review is not execution
+evidence. If that fresh quote weakens a displayed swap floor or risk fact, the
+widget stops before the router transaction and requires review of the updated
+strategy.
+
+Use `onboarding={{ mode: 'contextual' }}` to omit the introductory education
+while retaining the required review. Hosts can override presentation copy and
+persistence through `onboarding`, but contract scope, token amount, expiry,
+spender, target, and revocation copy remain SDK-owned.
+
 ## Partner context and host action requirements
 
+Wolf Game partners can use the canonical
+[live Wolf preview](https://swap.widget.aegis.markets/wolf).
+
 `partnerContext` adds optional, display-only facts from a game or partner. The
 host must normalize this data on its server. Do not pass API keys, private
 vendor responses, or wallet-specific context through shared URLs.
@@ -81,13 +174,13 @@ const partnerContext = {
     resource: {
       chainId: 1,
       address: '0x828B22c9ea1c20B551EeFC6198174C4bb7a8CBF6',
-      symbol: 'WATER',
+      symbol: 'WATER'
     },
     requiredAmount: '1000',
     availableAmount: '660',
     shortfallAmount: '340',
-    resourceUse: 'consumed',
-  },
+    resourceUse: 'consumed'
+  }
 } satisfies PartnerContext
 
 export function GameMarket() {
@@ -197,8 +290,8 @@ widget should own selection. The nested Buy surface remains independently
 controlled through `buySwapConfig`; one-shot partner Buy intents already
 resolve their matching direct pool.
 
-Wolf Game's current aggregate API provides Community 12 balances, weather, and
-harvesting data. It does not provide wallet-specific inventory, claimable
+Wolf Game's aggregate API provides game-wide balances plus weather and
+harvesting data for a selected community. It does not provide wallet-specific inventory, claimable
 resources, energy timing, or a concrete action requirement. A Wolf host must
 therefore create `actionRequirement` only from real game state. Do not derive it
 from aggregate weather or inventory alone.
@@ -272,6 +365,12 @@ Product semantics are deliberately conservative:
   before it quotes and submits add-collateral, repay, idle-withdraw, loan-close,
   and lend-redeem actions. A close that needs an idle-token rebalance asks the
   user to repay first, then re-quote the close.
+- Positions identify Tap Long/Short openings from the activity ledger's exact
+  create/deposit/debt/internal-swap/lock order. Target price and average
+  leverage remain clearly labeled opening-plan metadata, not current protocol
+  state or an on-chain order. Leverage rows omit borrow-rate runway forecasts
+  and show the underlying move from entry only while a fresh same-pool mark is
+  available; the move is not presented as PnL or return.
 - Lender balances are indexed Engine share units, not token amounts; the widget
   does not invent a token/USD value without a current share price.
 
@@ -356,10 +455,11 @@ normalizes addresses and validates shape, but it cannot prove that a host's
 override points at the intended Aegis or Uniswap deployment. Source those values
 from your own audited config or backend, not from user input.
 
-`onSubmitted`, `onSuccess`, `onError`, `onQuote`, `onStatusChange`, and
-`onPoolChange` are the supported host signals. The in-widget "Latest tx" drawer
-is a session-local UI receipt for the most recent confirmed swap; it is not a
-transaction history API. If a host needs durable history, record
+`onSubmitted`, `onSuccess`, `onError`, `onQuote`, `onStatusChange`,
+`onPoolChange`, `onAuthorizationPlan`, `onAuthorizationStepChange`, and
+`onOnboardingEvent` are the supported host signals. The in-widget "Latest tx"
+drawer is a session-local UI receipt for the most recent confirmed swap; it is
+not a transaction history API. If a host needs durable history, record
 `onSubmitted`/`onSuccess` on the host side.
 
 ## Appearance
@@ -367,11 +467,7 @@ transaction history API. If a host needs durable history, record
 Hosts can choose the widget surface and brand accent at instantiation time:
 
 ```tsx
-<AegisSwapWidget
-  theme="dark"
-  accentColor="#7c5cff"
-  baseColor="#16121f"
-/>
+<AegisSwapWidget 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).
@@ -443,7 +539,7 @@ The general Ethereum preset is exported for hosts that want the standard list:
 import { AegisAggregatedSwapWidget } from 'aegis-swap-widget'
 import {
   AGGREGATED_SWAP_DEFAULT_TOKEN_LIST,
-  AGGREGATED_SWAP_WOLFGAME_TOKEN_LIST,
+  AGGREGATED_SWAP_WOLFGAME_TOKEN_LIST
 } from '@aegis-engine/core'
 
 export function WolfGameSwap() {
@@ -520,7 +616,7 @@ import { AegisSwapWidget } from 'aegis-swap-widget'
 import {
   AEGIS_DYNAMIC_FEE_FLAG,
   AEGIS_SWAP_HOOK,
-  type AegisSwapPoolConfig,
+  type AegisSwapPoolConfig
 } from '@aegis-engine/core'
 
 const pools: AegisSwapPoolConfig[] = [
@@ -532,14 +628,14 @@ const pools: AegisSwapPoolConfig[] = [
       currency1: '0xYourTokenAddress',
       fee: AEGIS_DYNAMIC_FEE_FLAG,
       tickSpacing: 60,
-      hooks: AEGIS_SWAP_HOOK,
+      hooks: AEGIS_SWAP_HOOK
     },
     counterToken: {
       chainId: 1,
       address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
       name: 'USD Coin',
       symbol: 'USDC',
-      decimals: 6,
+      decimals: 6
     },
     token: {
       chainId: 1,
@@ -547,9 +643,9 @@ const pools: AegisSwapPoolConfig[] = [
       name: 'Example Token',
       symbol: 'EXAMPLE',
       decimals: 18,
-      iconUrl: 'https://example.com/token.svg',
-    },
-  },
+      iconUrl: 'https://example.com/token.svg'
+    }
+  }
 ]
 
 export function Swap() {
@@ -566,13 +662,13 @@ The default chain is Ethereum mainnet. You can override mainnet RPCs or provide
 ```tsx
 import { mainnet } from 'viem/chains'
 
-<AegisSwapWidget
+;<AegisSwapWidget
   chainId={1}
   chains={{
     1: {
       chain: mainnet,
-      rpcUrls: ['https://your-mainnet-rpc.example'],
-    },
+      rpcUrls: ['https://your-mainnet-rpc.example']
+    }
   }}
   pools={pools}
 />
@@ -588,15 +684,15 @@ import { base } from 'viem/chains'
 import { AegisSwapWidget } from 'aegis-swap-widget'
 import { UNISWAP_V4_CONTRACTS_BY_CHAIN } from '@aegis-engine/core'
 
-<AegisSwapWidget
+;<AegisSwapWidget
   chainId={8453}
   chains={{
     8453: {
       chain: base,
       router: '0xYourAegisRouter',
       rpcUrls: ['https://your-base-rpc.example'],
-      v4Contracts: UNISWAP_V4_CONTRACTS_BY_CHAIN[8453],
-    },
+      v4Contracts: UNISWAP_V4_CONTRACTS_BY_CHAIN[8453]
+    }
   }}
   pools={pools}
 />
@@ -614,10 +710,7 @@ The widget fetches token icons by address using the metadata IDs from the Aegis
 `evm_${chainId}_${tokenAddressLowercase}`.
 
 ```tsx
-<AegisSwapWidget
-  metadataEndpoint="/graphql/meta"
-  pools={pools}
-/>
+<AegisSwapWidget metadataEndpoint="/graphql/meta" pools={pools} />
 ```
 
 Use `metadataEndpoint={null}` to disable backend icon hydration. It does not
@@ -657,7 +750,7 @@ host connect modal creates the provider during the button click:
     const connection = await openWallet()
     return {
       provider: connection.provider,
-      account: connection.account,
+      account: connection.account
     }
   }}
 />
@@ -837,12 +930,12 @@ same viewport — a plain function, no hooks or context:
 ```tsx
 import { aegisToast } from 'aegis-swap-widget'
 
-aegisToast('Copied')                            // info
+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
+const id = aegisToast.loading('Uploading…') // sticky until updated
+aegisToast.success('Uploaded', { id }) // reusing an id morphs in place
 
 aegisToast.promise(save(), {
   loading: 'Saving…',
@@ -862,8 +955,9 @@ package keep two independent toast stores (and two viewports).
 
 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.
+when a switch retargets them. Motion uses CSS plus the browser Web Animations
+API for the bottom-sheet entrance; no third-party animation runtime ships with
+the widget. Every animation respects `prefers-reduced-motion` automatically.
 
 Hosts tune or disable the switch motion through CSS tokens on the `style` prop:
 
@@ -881,13 +975,13 @@ Hosts tune or disable the switch motion through CSS tokens on the `style` prop:
 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` |
+| 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.
 
@@ -927,8 +1021,22 @@ No other props changed. See the [CHANGELOG](./CHANGELOG.md) for the full entry.
 - `style`: optional root style object, useful for host layout constraints or CSS variables.
 - `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.
-- `onSurfaceChange`: Engine callback fired when the active unified tab changes (`'buy'`, `'borrow'`, `'lend'`, or `'positions'`).
+- `onSurfaceChange`: Engine callback fired when the active unified tab changes (`'buy'`, `'trade'`, `'borrow'`, `'lend'`, or `'positions'`).
 - `marketResource`: controlled Lend/Borrow market locator (`chainId`, token `address`, and `symbol`). On the active chain, the widget resolves one eligible Engine market, hides its picker, and fails closed on missing or ambiguous matches. It does not lock token direction. Use `marketId` only as an optional disambiguator for the same resource.
+- `surfaces`: Engine tabs to expose. Defaults to `['buy', 'borrow', 'lend', 'positions']`. Add `'trade'` to opt into the Long/Short surface (see Trade surface).
+- `tradeDirections`: directions offered on the Trade surface. Defaults to `['long', 'short']`.
+- `defaultTradeDirection`: initial Trade direction. Defaults to the first `tradeDirections` entry.
+- `tradeDirectionSelector`: Long/Short selector visibility — `'auto'` (default) hides it when `tradeDirections` resolves to a single entry, `'always'`, or `'never'`.
+- `tradeLeverageOptions`: shortcuts shown below the quote-driven leverage slider. Defaults to `[2]`, with a separate live `Max` shortcut; preset values must be above `1` and no greater than `5`. The live Engine quote, not this list, sets the actual minimum and maximum.
+- `defaultTradeLeverage`: initial Trade leverage. Defaults to `1.5` and does not need to match a shortcut.
+- `tradeHorizonDays`: horizon used to size the directional position and estimate interest. Defaults to `30`.
+- `tradePriceMovePercent`: target-price move used to measure average leverage and gross target return. Defaults to `20`.
+- `tradePositionStorage`: optional async `load`/`save` adapter for confirmed Long/Short opening intent. Omit for origin-local browser persistence, pass `null` to disable off-chain persistence, or provide a host service for cross-device continuity. Host operations receive an optional `{ signal }`, use `timeoutMs` (default `10000`), and must treat `(chainId, account, txHash)` as an idempotent upsert key. Return newest-first records; the widget validates and reads at most 64. Timed-out operations fail softly and are not retried. Indexed actions always own direction and entry price.
+- `onboarding`: Long/Short education and review options. `mode` is `'guided'` (default) or `'contextual'`; required transaction review cannot be disabled. `motion: 'reduce'` forces the no-travel variant; `storage`, `storageKey`, and safe presentation `copy` overrides support host customization. `howItWorks: false` hides the education link and sheet. `showBeforeConnect: true` opens education once on first view; it stays closed by default. `permissionsWalkthrough: 'auto'` opens setup when a positive deposit still needs wallet access.
+- `permissionRailColor`: optional Engine permission-step rail color. It defaults to `accentColor` and derives readable rail ink automatically.
+- `onAuthorizationPlan`: called after the widget reads the connected account's live Long/Short authorization plan.
+- `onAuthorizationStepChange`: called with `requesting` and `confirmed` progress for each required vault, token, Permit2, and final-open action.
+- `onOnboardingEvent`: product lifecycle callback for education, review, authorization start, and confirmed-position events.
 - `buySwapConfig`: optional host overrides for the nested Engine Buy surface only. Use it to constrain Buy to a chain, pool set, or controlled `poolId` without changing Engine market discovery or the Lend/Borrow/Positions surfaces.
 - `showBuySettings`: show the Engine Buy surface's slippage-settings control. Defaults to `false`.
 - `showAmountSlider`: amount-slider visibility on the Engine lend/borrow amount boxes: `'auto'` (default) shows sliders on the borrow surface only, sized against the wallet's borrowing limit; `'always'` adds the lend deposit slider; `'never'` hides every amount slider.
@@ -939,7 +1047,9 @@ No other props changed. See the [CHANGELOG](./CHANGELOG.md) for the full entry.
 - `accentTextColor`: optional CTA text color for contrast with the chosen accent.
 - `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`.
+- `showApprovalMode`: whether to show the approval-amount control. On Swap it appears in the details drawer; on Engine Long/Short it appears on the Permit spending-limit row. Defaults to `true`.
+- `approvalMode`: controlled Engine approval mode (`'exact'` or `'max'`). Omit it to initialize internal state from `defaultApprovalMode`.
+- `onApprovalModeChange`: fired when the Engine approval mode changes. A controlled host must update `approvalMode` in response.
 - `showExecutionDetails`: whether to render the collapsible drawer for trade details and, after a confirmed swap, the session-local Latest tx receipt. Defaults to `true`.
 - `defaultExecutionDetailsOpen`: whether that settings drawer starts expanded. Defaults to `false`.
 - `executionDetailsOpen`: controlled open state for the Trade details drawer. Omit this for the widget's internal open/closed state.