aegis-swap-widget 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # 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

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

@@ -54,12 +54,100 @@ 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
@@ -86,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() {
@@ -277,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.
 
@@ -361,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
@@ -372,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).
@@ -448,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() {
@@ -525,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[] = [
@@ -537,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,
@@ -552,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() {
@@ -571,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}
 />
@@ -593,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}
 />
@@ -619,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
@@ -662,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
     }
   }}
 />
@@ -842,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…',
@@ -867,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:
 
@@ -886,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.
 
@@ -932,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.
@@ -944,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.