aegis-swap-widget 0.10.3 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,197 @@
 # Changelog
 
+## 0.12.0
+
+### Minor Changes
+
+- ed4f81a: Add a bounded account portfolio and paged activity contract, a reusable multi-chain portfolio view, and explicit receipt/indexer/portfolio acknowledgement. Preserve unknown valuations and per-chain coverage, resolve management through live position identity, and retain known transaction hashes across reloads without resubmission.
+- fc5419f: Ship agent-readable widget config and versioned, correlated event schemas, a focused integration skill, a Swap event projector, a semantic event validator, and package resource exports.
+- 7157400: Trade Long/Short now refers to the market's displayed asset across all markets. On USDC-ETH, Long means Long ETH; on BNB-QQQB, Long means Long QQQB. Displayed prices, leverage, existing positions and outcome estimates use that same orientation, including interest tooltips.
+
+  Host `tradeDirections`, `defaultTradeDirection` and the `direction` in onboarding event payloads use asset direction. Hosts that previously constrained token0 direction must invert their values on quote-first markets to preserve the same exposure. Core quotes, indexed actions and stored position records keep their protocol direction; hosts must not rewrite those records. See the Trade direction migration section in the widget README.
+
+- 2c39b4b: Add a direct two-token lending quote and guarded execution flow, a headless React hook, and an opt-in linked-pair lending surface with exact token limits and persistent receipt recovery.
+- 603c625: Add trusted BSC Aegis Engine v1.0.3 and direct-swap support to Core and Widget. This registers the BSC router and V4 contracts, enables production REST discovery, includes the BNB/BNCB, BNB/QQQB, and NVDAB/USDC pool catalogue, and handles native BNB without ERC-20 or Permit2 approval prompts.
+- df98b19: Add a selective account reader and headless hook for completed tap trade token PnL from a retained accounting snapshot. Validate identity, cash-flow arithmetic and expiry; keep unsupported histories and total economic PnL explicitly unavailable. The hook reads once per snapshot, cancels replaced requests and honors Retry-After on manual refresh.
+- 86da1ff: Add selective Core account and React hooks entry points, validated position-history and closed-position catalog reads, and shared transaction metadata recovery. Qualify installed public tarballs on the configured CI runtime and React 18/19. Validate the consumed live backend contract before enabling its features in an environment. History retains missing values, actual observation intervals and incomplete accounting coverage.
+- 8d07a0b: Add the account-only position accounting reader and matching widget hook. Preserve raw event details, proven ownership, immutable snapshot cursors and explicit unavailable financial capabilities. Pin the consumed backend contract to the accounting endpoint source.
+- 1c32ae1: Add lazy historical position discovery and recorded values to account and trading views, including closed positions and optional previously owned vaults. Preserve missing valuation and ownership coverage, reject expired or changed pagination, and expose history wire validators for host proxies.
+- e53591d: Add a React-free Engine trade execution session with explicit wallet request,
+  submission, confirmation, failure, cancellation, receipt reconciliation, and
+  typed recovery states.
+
+  Use that lifecycle in the leverage widget so wallet rejection cannot appear as
+  chain confirmation, submitted hashes cannot be retried blindly, refreshed
+  quotes return to review, and completed permission evidence survives later
+  prompts.
+
+  Freeze the submitted Swap hash, chain, account, and asset identity in status
+  events so controlled host props cannot rewrite explorer links or settlement
+  copy while a transaction is pending.
+
+  Reject caller-provided V4 quoters that differ from the trusted Engine registry
+  before using their output in an executable minimum amount.
+
+  Pin Lend and Trade internal-swap quotes to the same block as their Engine
+  frame. Require a host price-impact limit, fail closed with typed reasons when
+  impact is unavailable or above that limit, and re-check the frame hash before
+  returning executable calldata. The Widget defaults this policy to 500 basis
+  points and exposes a host override.
+
+  Trade-open quotes now include a required `intent` echo. Update hand-built quote
+  fixtures to include owner, side, collateral, strategy, slippage, and impact cap.
+
+  Expose same-block DynamicFeeManager evidence as post-swap surge telemetry,
+  including manual-override changes, without presenting its adaptive tick
+  threshold as a Router price limit.
+
+  Keep the exposure asset in Long and Short actions, disclose the internal swap,
+  require acknowledgement for severe price impact, and lead with one compact
+  leverage-limit signal. The progress rail and success confirmation remain
+  CSS-only and honor reduced-motion preferences.
+
+  Floor compact minimum-receive copy instead of rounding it upward, while keeping
+  the exact executable amount accessible. Re-open review only when refreshed
+  market utilization changes at the precision shown to the user.
+
+- 8234bad: Add trusted Ink Aegis Engine v1.0.3 support, upgrade the Engine SDK to 0.35.0, and expose Ink markets, positions, and history through the existing REST data source.
+- e53591d: Install the approval authority the caller asked for, and stop bundling a Permit2
+  signature the chain will reject.
+
+  `approvePermit2ToRouter` read `amount` for truthiness, so an explicit `0n` — the
+  natural revoke, and the value `approveErc20ToPermit2` already takes for the
+  USDT-style reset — installed MAX_UINT160 with a far-future expiration instead.
+  `0n` now means zero, omitting `amount` still means maximum, and an amount wider
+  than uint160 is clamped.
+
+  The ERC-20 → Permit2, aggregator-router, and Permit2 → router gates each
+  short-circuited on amount alone, so "No limit" silently reused any allowance
+  that happened to cover the trade and nothing unlimited was ever installed. All
+  three are mode-aware now: `max` requires a standing grant that still reads as
+  effectively unlimited, `exact` is unchanged.
+
+  `authorizePermit` previously turned every non-rejection signing failure into an
+  on-chain approval. It now uses that fallback only for explicit unsupported
+  typed-data method codes. Disconnects, timeouts, internal RPC errors, and unknown
+  wallet failures abort without opening a broader approval prompt.
+
+  Permit2 branches on the owner's code, not the signature's shape, so a returned
+  but unacceptable signature — an ERC-6492 wrapper, or an ordinary 65-byte
+  signature from an EIP-7702-delegated EOA whose delegate has no ERC-1271 — would
+  revert the bundled swap. The signature is now checked the way Permit2 will check
+  it, and an unacceptable result fails closed before any transaction is sent.
+
+  The widget's approval prediction is mode-aware too. Once submission starts, the
+  executor's fresh prompt plan replaces that prediction, including a zero-reset,
+  and mined approvals remain credited if a later wallet prompt is rejected.
+
+  Zero-reset is now a token capability, not an inference from any finite standing
+  allowance. Hosts can set `requiresApprovalReset` on a token, and Ethereum USDT
+  keeps its well-known address rule. Ordinary ERC-20 allowance upgrades use one
+  approval transaction.
+
+  Submission now freezes quote state synchronously, including background requests
+  that were already in flight. Engine close also returns to review when a fresh
+  block-pinned quote introduces a router/operator authorization gate or widens a
+  token approval. Permit2 signature progress is complete only after its owner
+  verification path accepts the signature.
+
+  Leverage-open quotes now expose exact market utilization before and after the
+  final integer-rounded debt. Both values use the same block-pinned Core frame;
+  the widget shows them inside the compact Execution disclosure and never mixes
+  them with the REST market snapshot.
+
+- 5d200cb: Improve Tap account equity and scoped estimated P&L, exact position navigation, permission progress and cancellation recovery, and unavailable chart states. Align asset direction, leverage and outcome currencies while preserving exact spending limits as the default.
+- 6c6d894: Add a `layout` prop (`'vertical' | 'horizontal'`, default `'vertical'`) to the Engine and Leverage widgets, exported as `AegisEngineLayout`. `horizontal` re-flows Tap trading (the Trade surface with `showTradeChart`) into a trading-terminal view: a market bar across the top, the price chart in a wide left column, and a fixed-width order ticket on the right, with Positions beside the session activity rail. The grid engages once the widget is at least 640px wide and falls back to the vertical stack below that; Buy, Lend, Borrow, and Positions stay vertical. The root reflects the prop as `data-layout`, and the new `engine-layout.css` module sets `--aegis-trade-chart-height` on the chart region for the wide plot. Every widget still opens vertical unless a host opts in.
+- 37b614d: Add a Thena presentation preset for BSC Tap integrations.
+
+### Patch Changes
+
+- 7c3a598: Add bounded pool-candle, token-reference-line and qualified rate-history readers. Preserve source provenance, explicit gaps, APR semantics and display-only reference limitations without automatic fallback or wallet RPC reads.
+
+  Share bounded market-history requests with short caching and server-aware cooldowns, validate chart token units, and expose candle segments that preserve explicit gaps. Back off failed Widget pool-mark reads independently while keeping stale-price expiry and healthy-market polling.
+
+- 2ab8cb1: Unify the trade chart across time windows and render recorded swap candles with visible dojis. Keep live pool observations distinct from swap OHLC, show empty-period and delayed-indexing states, and preserve gaps.
+- c1f58b5: Value debt and equity from block-pinned SDK repayment legs instead of a balanced USD-price approximation. Missing or inconsistent pool reads withhold the USD estimate while retaining live ownership and risk state.
+- c415d24: Name the partial-liquidation and full-repayment thresholds consistently in visible and accessible risk descriptions. Label the legacy time estimate with its full-repayment threshold and constant-rate assumptions.
+- 6c6d894: Compact Tap trading into a chart, position or trade ticket, and portfolio workspace. Keep position navigation, entry-price navigation, spending-limit changes and explicit revocation in the existing workflows. Use consistent inset focus rings, responsive controls and reduced-motion disclosures.
+
+  Show current and estimated debt ratios while adding margin or reducing leverage. Repayment uses a display-only SDK projection; unavailable evidence stays unavailable. Keep deposit and leverage editable during trade review, block confirmation while a replacement quote is pending, and animate market utilization without overshoot. Preserve separate partial-reduction and full-repayment thresholds.
+
+- 6c6d894: Tap trading draws one price chart for Live, 1H, 6H, 1D and target selection. Indexed 5-minute closes hold flat across verified coverage up to `coverage.completedThrough`, unobserved spans (not-yet-indexed buckets, declared gaps, live pauses) are dashed and labelled, and the live pool-state session is the tail of the same line. The plot's right edge follows the wall clock: Live scrolls continuously with a heartbeat on the last price, range switches morph the same line, and the current price stays visible while a target is chosen. The chart sizes itself from its box, so the horizontal layout's taller cell gets more gridlines and ticks without stretching text. The canvas `liveline` renderer is no longer used.
+- 98f5187: Keep the indexed debt-action token ratio separate from executed entry price. The position card requires explicit receipt-reconciled entry evidence before displaying entry, price movement, or entry-based plans.
+- e53591d: Fix two approval-path failures found by an audit of the approval work, and
+  correct the permissions sheet's surface label.
+
+  `approveErc20ToPermit2` and `approveErc20Spender` simulated `approve` against
+  viem's `erc20Abi`, which declares a `bool` return. Ethereum USDT returns no
+  data, so `decodeFunctionResult` threw `AbiDecodingZeroDataError` and the
+  approval failed before the wallet was ever asked — the token that
+  `requiresApprovalReset` exists for could not be approved at all, in either the
+  reset or the grant. Both writers now simulate against an approve ABI that
+  declares no outputs, which accepts the return-less and bool-returning shapes
+  alike. Nothing is lost: the returned value was already discarded, and the
+  post-write allowance read is what confirms the grant.
+
+  The aggregated-swap settlement floor is the stronger of the fresh and reviewed
+  minimums, but the calldata was still requested at the raw slippage tolerance
+  against the fresh route. KyberSwap embeds that tolerance in the bytes it
+  returns, so once the reviewed floor was the stronger of the two, the build could
+  not satisfy the floor it was then checked against and
+  `assertKyberCalldataMatchesQuote` rejected a build we had asked for. Any
+  in-tolerance price dip after review therefore failed the swap outright instead
+  of settling at the reviewed minimum. The build is now requested at the tightest
+  tolerance that still clears the settlement floor; the result never exceeds the
+  requested tolerance, so the wallet is only ever offered a stricter minimum than
+  the user set.
+
+  The permissions sheet's final footer hardcoded "Ready to open" on every surface,
+  so Lend and Borrow ended on trade wording while the surface-aware label was
+  computed and unreachable. Lend now reads "Ready to deposit" and Borrow "Ready to
+  borrow".
+
+  The permission rail's target and spender rows, and each row's Details
+  disclosure, reach assistive technology and touch: full addresses are no longer
+  tooltip-only, and each disclosure is named for its own permission. The
+  price-impact consent checkbox is named by the acknowledgement rather than by the
+  entire warning paragraph.
+
+- Updated dependencies [ed4f81a]
+- Updated dependencies [2c39b4b]
+- Updated dependencies [603c625]
+- Updated dependencies [df98b19]
+- Updated dependencies [86da1ff]
+- Updated dependencies [8d07a0b]
+- Updated dependencies [7c3a598]
+- Updated dependencies [c1f58b5]
+- Updated dependencies [ec0018b]
+- Updated dependencies [1c32ae1]
+- Updated dependencies [e53591d]
+- Updated dependencies [8234bad]
+- Updated dependencies [e53591d]
+- Updated dependencies [55c2173]
+- Updated dependencies [98f5187]
+- Updated dependencies [e53591d]
+  - @aegis-engine/core@0.8.0
+
+## 0.11.0
+
+### Minor Changes
+
+- Refresh the widget layout, styling, amount transitions, permission review, and transaction progress across Swap, Borrow, Lend, and Leverage. Keep the chart visible during Leverage execution and show transaction links after confirmation.
+
+  Add editable spending limits, wallet-aware borrow limits, receipt-based swap amounts, and consistent confirmed transaction progress to support the updated widget experience.
+
+  Improve the landing site and playground with funded multi-chain demo portfolios, simulated transaction lifecycles, clearer wallet prompts, installation snippets, event inspection, sharing, reset controls, and walkthroughs. Tap Trading remains marked as coming soon.
+
+### Patch Changes
+
+- 1727b9d: Expose settled borrow collateral sizing outcomes and align the Widget's advice,
+  button, retry, and existing-vault withdrawal review with them.
+- Updated dependencies [1727b9d]
+- Updated dependencies
+  - @aegis-engine/core@0.7.0
+
 ## 0.10.3
 
 ### Patch Changes

package/DESIGN.md

@@ -50,7 +50,7 @@ runtime ships with the widget, and `prefers-reduced-motion` is respected.
 
 | Token | Default | Role |
 | --- | --- | --- |
-| `--aegis-switch-dur` | `260ms` | Segmented-pill glide and Sell/Buy token swap. `0ms` disables. |
+| `--aegis-switch-dur` | `260ms` | Segmented-pill glide plus Sell/Buy, Add/Reduce, and Add/Withdraw switches. `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. |
 

package/README.md

@@ -1,5 +1,12 @@
 # Amplifi Swap and Aegis Engine Widget
 
+Opt in to paired lending with
+`balancedLending={{ nativeGasReserve: yourReserveInWei }}` on
+`AegisEngineWidget`, or embed `AegisEngineBalancedLend` directly.
+`useEngineBalancedLend` exposes the same flow for custom layouts. See
+[the integration guide](../../docs/balanced-lending.md) for the SDK release
+dependency, wallet interface, scoped recovery and native-reserve semantics.
+
 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.
@@ -29,6 +36,12 @@ and `viem ^2`. The package is ESM-only. Its only runtime dependencies are
 The published packages are self-contained: host applications do not need a
 GitHub Packages token for the Engine SDK.
 
+The ESM build targets JavaScript syntax supported by Chrome/Edge 92+, Firefox 90+,
+and Safari 15.4+, matching the widget's existing native `Array.prototype.at()` usage.
+Build targets do not add runtime polyfills: hosts must also provide the APIs used
+by their enabled flows, including `structuredClone()` in Engine core, and transpile
+the package if they support older browsers.
+
 ## Basic Usage
 
 ```tsx
@@ -52,6 +65,7 @@ export function Engine({ account, provider }) {
       account={account}
       provider={provider}
       defaultSurface="buy"
+      maxEngineSwapPriceImpactBps={500}
       showTokenPriceHistory
       showEngineMarketHistory
       surfaces={['buy', 'trade', 'borrow', 'lend', 'positions']}
@@ -164,8 +178,37 @@ 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.
+impact, block-pinned market utilization before and after opening, the exact
+internal-swap minimum behind its compact floor, and interest over the configured
+horizon. Engine positions do not have a single liquidation price; interest
+accrual increases LTV over time.
+
+### Trade direction migration
+
+Long/Short now refers to the displayed asset on every market. When exactly one
+token is stable, the other token is the asset. Otherwise, when exactly one token
+is native or the chain's trusted wrapped native token, the other token is the
+asset. Remaining pairs use token0 as the asset.
+
+For USDC-ETH, Long means Long ETH and Short means Short ETH. For BNB-QQQB, they
+mean Long QQQB and Short QQQB. Prices are displayed in quote tokens per asset;
+leverage and price scenarios follow the same asset exposure. Existing protocol
+limits still apply: a flipped market's Long minimum may be 2×, depending on its
+live quote. The widget does not create a new borrowing range.
+
+`tradeDirections`, `defaultTradeDirection` and the `direction` field on
+`onOnboardingEvent` events (`review-opened`, `review-closed`,
+`authorization-started`, `position-opened`) all use this asset direction. Hosts
+that previously restricted token0 exposure must invert `long` and `short` for
+quote-first pairs to preserve their former intent; a host offering both
+directions can keep both values. Update direction-specific copy and analytics
+to name the asset, rather than assuming token0.
+
+Core SDK requests and quotes, indexed activity, and stored position records
+retain their protocol token-order direction. The widget converts those values
+for display and maps asset intent back when quoting. Do not invert Core callback
+values or rewrite stored position records. Exact spending limits remain the
+default, and wallet authorization and transaction order are unchanged.
 
 For a separate Long/Short experience that starts without
 Buy/Borrow/Lend/Positions tabs, mount `AegisLeverageWidget`:
@@ -181,6 +224,7 @@ export function LongShort({ account, provider }) {
       provider={provider}
       chains={engineChains}
       engineDataSource={{ kind: 'rest', baseUrl: '/api/engine' }}
+      maxEngineSwapPriceImpactBps={500}
       tradeLeverageOptions={[1.25, 1.5, 2, 3]}
       defaultTradeLeverage={1.5}
       onboarding={{ mode: 'guided' }}
@@ -189,6 +233,26 @@ export function LongShort({ account, provider }) {
 }
 ```
 
+### Layout
+
+Every widget ships as a single vertical column (`layout="vertical"`, the
+default). Tap trading — the Trade surface with `showTradeChart` — can also
+run as a horizontal trading terminal:
+
+```tsx
+<AegisLeverageWidget {...props} showTradeChart layout="horizontal" />
+```
+
+`horizontal` re-flows the same blocks the way perps terminals do: a market bar
+across the top (pair picker, liquidity, financing rate), the price chart in a
+wide left column, and a fixed-width order ticket on the right (Long/Short,
+deposit, leverage, estimate, execution details, CTA). Positions sit below the chart and ticket, without a separate top navigation tab. The grid engages once
+the widget itself is at least 640px wide and falls back to the vertical stack
+below that, so a narrow embed never scrolls horizontally. The widget caps
+itself at 1280px; give it a wide container. Buy, Lend, Borrow, and Positions
+stay vertical on the Engine widget. The root carries `data-layout` for host
+styling either way.
+
 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
@@ -272,6 +336,7 @@ export function GameMarket({
   return (
     <AegisEngineWidget
       partnerContext={partnerContext}
+      maxEngineSwapPriceImpactBps={500}
       partnerContextVariant="embedded"
       onPartnerRequirementAction={(requirement, surface) => {
         console.log(surface, requirement.id)
@@ -350,6 +415,7 @@ const wolfResources = {
 <AegisEngineWidget
   chainId={1}
   enabledChainIds={[1]}
+  maxEngineSwapPriceImpactBps={500}
   marketResource={wolfResources[selectedResource]}
 />
 ```
@@ -462,6 +528,12 @@ host supplies `engineDataSource`. Static or offline Engine integrations use
 `backendBaseUrl={null}` disables token-price history and backend reads for the
 nested Buy surface; it does not change Engine market discovery.
 
+For a static source, the widget's best-effort latest vault-activity tail can
+query the public Engine subgraph directly from the browser. The request carries
+the chain and vault identifier. Use a REST source or a host-owned proxy when
+client-side indexer access is not acceptable; fully offline fixtures should
+supply `vaultActivity` with their static position data.
+
 The backend-enabled network list comes from `GET /v1/config` (`chains[]`). By
 default the widget exposes every backend chain it can configure. Projects that
 only support a subset should pass `enabledChainIds`; the first entry becomes
@@ -516,9 +588,9 @@ Token icons are hydrated from the same metadata table used by the Aegis website:
 
 `aegis-swap-widget` is the production widget SDK. It uses real providers, RPCs,
 pool config, approvals, Permit2 authorization, swap submission, and callbacks.
-Pull requests publish the package demo to the Cloudflare Pages branch URL
-reported by Wrangler, for example
-`https://pr-<number>.aegis-widget-preview.pages.dev`.
+The Cloudflare Pages package demo deploys only from trusted `main` code while
+the repository uses a Global API Key. Pull requests run the full CI gate but do
+not receive Cloudflare credentials.
 
 Demo wallets, fake transaction flows, scenario controls, and mock host shells
 belong in the playground app (`apps/playground` in this monorepo). They are not
@@ -538,12 +610,31 @@ 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`,
-`onPoolChange`, `onAuthorizationPlan`, `onAuthorizationStepChange`, and
-`onOnboardingEvent` are the supported host signals. The in-widget "Latest tx"
+`onPoolChange`, `onAuthorizationPlan`, `onAuthorizationStepChange`,
+`onTradeExecutionChange`, 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.
 
+`onTradeExecutionChange` emits the complete Long/Short execution session. Use
+its stable `sessionId`, monotonic `sequence`, `occurredAt`, `chainId`, and
+`quoteRevision` to correlate wallet rejection, submission, quote review, and
+recovery before a transaction hash exists. The raw callback also contains the
+Core quote, plan, and bigint values; do not serialize it directly. Project the
+JSON-safe fields through the versioned event schema, then run the exported
+`validateAegisWidgetEventSemantics` helper from
+`aegis-swap-widget/agent/validate-events` for matching-step and matching-hash
+invariants.
+
+`onStatusChange` remains the small Swap rail payload. To store the same
+versioned event envelope, call `projectAegisSwapStatusEvent` from
+`aegis-swap-widget/agent/events`. The host creates `sessionId` before the first
+wallet request, increments `sequence` for every status event and
+`quoteRevision` whenever `onQuote` replaces the executable quote, stamps
+`occurredAt`, and retains the reviewed `chainId` until the attempt reaches a
+terminal outcome. The projector copies only schema fields; validate its result
+with the v1 schema and semantic validator before persistence.
+
 ## Appearance
 
 Hosts can choose the widget surface and brand accent at instantiation time:
@@ -884,14 +975,19 @@ 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:
+A USDT-style token that reverts a non-zero → non-zero `approve` adds one more
+prompt: the widget resets the standing allowance to zero first. Both approvals
+report `status: 'approving'`, but they are counted and completed separately.
+Use `walletPrompts` for step copy or external rails instead of guessing from
+status names:
 
 ```tsx
 <AegisSwapWidget
-  onStatusChange={({ status, progress, walletPrompts, txHash, error }) => {
+  onStatusChange={({ status, progress, walletPrompts, txHash, transaction, 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
+    // transaction: submission-time chain/account/token identity after broadcast
     // error:    user-facing message, e.g. "Request rejected."
   }}
 />
@@ -901,6 +997,11 @@ 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.
 
+Once a transaction is broadcast, `transaction` freezes its `hash`, `chainId`,
+`account`, input/output token identity, and explorer URL. Use this context for
+pending, timeout, failure, and success UI: controlled host props may already
+describe a different chain or market while the submitted transaction settles.
+
 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`, import `isUserRejectedError` from `@aegis-engine/core`.
@@ -1035,18 +1136,19 @@ 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. 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.
+Switching pools, approval mode, Add/Reduce, or Add/Withdraw 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. 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:
 
 ```tsx
 <AegisSwapWidget
   style={{
-    '--aegis-switch-dur': '180ms', // pill glide + token swap; '0ms' disables
+    '--aegis-switch-dur': '180ms', // segmented/action glide + token swap; '0ms' disables
     '--aegis-spring': 'cubic-bezier(0.2, 0, 0, 1)' // switch easing
   }}
 />
@@ -1093,6 +1195,7 @@ No other props changed. See the [CHANGELOG](./CHANGELOG.md) for the full entry.
 - `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` (pool token into the counter token). Defaults to `buy`.
 - `defaultSlippagePercent`: number (canonical) or numeric string, in percent. Defaults to `1`.
+- `maxEngineSwapPriceImpactBps`: maximum block-pinned price impact for Engine internal swaps, in basis points. Lend and Trade fail closed above it or when impact cannot be assessed. Defaults to `500` (5%); valid range is `0` through `10000`. This is an SDK/Widget gate, not a Router-level pool-price invariant.
 - `rpcUrls`: RPC fallback list for the active chain, or a `{ [chainId]: string[] }` map for multichain hosts.
 - `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.
@@ -1106,9 +1209,18 @@ No other props changed. See the [CHANGELOG](./CHANGELOG.md) for the full entry.
 - `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.
+- `tradeDirections`: asset directions offered on the Trade surface. Defaults to `['long', 'short']`; see [Trade direction migration](#trade-direction-migration).
+- `defaultTradeDirection`: initial asset 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'`.
+- `showTradeChart`: display-only pool history and live observations on the Trade surface (Tap trading). Defaults to `false`.
+- `requireTradeLtvAcknowledgement`: defaults to `false`. Set `true` to require explicit acknowledgement when a trade quote is near the borrowing limit. This does not change contract limits, quote validation, or price-impact checks.
+- `tradeDetails`: `'compact'` (Tap default) or `'expanded'`. Compact reviews show the deposit and leverage without execution diagnostics.
+- `showTradePositions`: show positions beneath the Tap chart and ticket. Defaults to `true`.
+- `tradeSuccessDurationMs`: return from successful Tap execution to the chart after this delay. Defaults to `0`, keeping the receipt open until explicitly dismissed.
+
+Tap uses a single workspace without top section tabs. The chart starts as a line; its Candles control uses the same OHLC history and stays disabled when no candles are available. Verified entry lines are restored from the opening-execution API, scoped to the account, network, vault, pool and token pair. Unavailable execution evidence is never replaced by the reviewed quote. Entry is the opening swap price, not wallet cost basis or net P&L.
+
+- `layout`: `'vertical'` (default) or `'horizontal'`. Horizontal turns Tap trading (Trade surface with `showTradeChart`) into a terminal view — market bar on top, chart left, order ticket right — once the widget is at least 640px wide; narrower embeds fall back to the vertical stack. Other surfaces stay vertical. Reflected on the root as `data-layout` (see Layout under Trade surface).
 - `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`.
@@ -1118,6 +1230,7 @@ No other props changed. See the [CHANGELOG](./CHANGELOG.md) for the full entry.
 - `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.
+- `onTradeExecutionChange`: called for every Long/Short execution-session transition, including wallet request, submitted hash, confirmation, typed failure, quote review, and recovery. Its session metadata is stable and JSON-safe; the full quote and plan remain in-process values.
 - `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`.
@@ -1198,7 +1311,62 @@ Local `pnpm pack:check` still runs each package's `prepack` build sequentially.
 
 ```bash
 pnpm changeset               # in your PR: pick aegis-swap-widget + bump, write the entry
-# Merge the PR; the Release workflow opens a "Version Packages" PR on main.
+# After merge and successful release gates, Changesets opens the version PR.
 # Merging that PR publishes to npm via OIDC trusted publishing.
 npm view aegis-swap-widget version
 ```
+
+## Account portfolio
+
+Custom React account pages can selectively import account/activity/status hooks,
+`useEnginePositionHistory`, `useEngineHistoryPositions`, and
+`useEngineTransactionHistory` from `aegis-swap-widget/hooks`. This entry imports
+no stock components or CSS. The transaction hook uses Core's shared metadata,
+replacement and bounded receipt-recovery rules. History hooks return one page
+with explicit coverage; passing `null` disables the read. See
+`docs/package-data-contracts.md` in the repository for examples and the qualified
+React 18/19, Node and TypeScript matrix.
+
+Enable `accountPortfolio={{ chainIds: [1, 8453], layout: 'compact' }}` on `AegisEngineWidget` to use the shared account view on Positions. The selected chains must also be enabled by the host. This requires the new portfolio, paged-activity and transaction-status backend APIs; an unavailable service is shown explicitly. Omit the option to keep the existing embedded Positions presentation.
+
+For a separate account page, use `AegisEnginePortfolio` with a REST `source`, `account`, and `chainIds`. It supports compact/full layout, controlled network filtering, theme/style, labels, position actions, and header/summary/position/footer slots. Hosts can also consume `useEngineAccountPortfolio`, `useEngineAccountActivity`, and `useEngineAccountTransactionStatus` directly. These share Core's identity, amount, coverage and read contracts.
+
+Both the embedded REST Positions panel and `AegisEnginePortfolio` include a lazy **Engine position history** section. On the account component, `showHistory={false}` hides it. Hosts must proxy `GET /v1/engine/positions/history/catalog` (including `ownerScope`, `limit`, and `cursor`) and `GET /v1/engine/positions/history` (including `kind`, `poolId`, optional `vaultId`, `window`, and `before`). These are private, uncached reads. The playground forwards both routes under `/api/engine`.
+
+History defaults to current or last-owned vaults and includes closed positions. **Include previously owned vaults** requests `ownerScope=ever-owned`; unsupported indexing produces an explicit unavailable state, with no silent fallback. Borrow records cover the vault lifetime across owners, not wallet profit. Recorded values retain missing USD marks, assumed-price evidence, gaps, and page coverage. Catalog pagination rejects a changed deployment/frame or expired cursor; changing wallet, source, or network clears the prior selection.
+
+The view separates gross assets, debt, net equity and supplied value, retains known subtotals for incomplete pricing, and shows each network's frame separately. Performance stays unavailable without complete entry/cash-flow evidence. A management callback is disabled while a snapshot is stale, expired or still catching up to an acknowledged transaction. The stock widget additionally checks live position ownership and existing action guards.
+
+Activity joins local and indexed records by chain and transaction hash and combines split-page events. Lending amounts say spent/received; vault deltas say vault balance change. An indexed event does not imply a checked receipt. A confirmed transaction is reflected in the portfolio only after backend acknowledgement and a sufficiently recent displayed frame.
+
+Engine transaction hashes and safe display metadata persist in localStorage by wallet and network by default. `transactionStorage` accepts host storage with synchronous `getItem`/`setItem`, or `null` for memory-only history. Storage is best effort and local to the host origin/device. Known pending transactions survive remount and block new actions until the existing receipt reconciler resolves them. Checking status never signs, broadcasts, or reconstructs the original transaction; after confirmation the widget refreshes live positions. Signature/permit payloads and executable drafts are not saved. Future reorgs remain possible after receipt confirmation.
+
+History synchronizes sibling embeds and merges storage events from other tabs. Superseded hashes remain attached to their replacement, including out-of-order observations. A price-only speed-up can confirm the original action; a replacement that changed execution stays cancelled even after a timeout and reload. Engine ERC-20, Permit2, vault and share authorizations use a separate stage: their confirmation does not announce a portfolio update or fire a final-action success callback. Direct swap hosts can consume `onTransactionObservation` with its frozen account and chain. Pending-history persistence requires working host storage; storage errors are shown explicitly.
+
+### Headless completed-trade PnL
+
+`useEnginePositionPnl(input)` accepts the Core `AegisEnginePositionPnlInput`, or
+`null` to disable the read. Pass the same account, chain, pool, vault and retained
+accounting `snapshotId`. It returns `{ data, pending, error, refresh }`, reads once
+when that scope changes and never starts a polling loop. `refresh()` is explicit
+and honors the API's Retry-After cooldown. Changed selections hide old results;
+replaced requests are cancelled, and expired PnL is cleared.
+
+Render `data.status === 'token-pnl'` as separate token gains/losses. Render an
+unavailable reason separately from zero. Execution gas is only part of transaction
+cost, and the result does not supply historical USD or total economic PnL. This
+hook is an optional host integration and does not enable the live chart.
+
+
+### Thena presentation preset
+
+Import `THENA_TAP_PRESET` from `aegis-swap-widget/presets/thena` and spread it on
+`AegisLeverageWidget` for BSC, horizontal Tap layout and Thena's dark orchid theme.
+Supply a controlled `marketId` to connect a host-owned market rail. Import
+`aegis-swap-widget/styles.css` once in the host.
+
+This preset contains presentation defaults only. The host owns its market scope,
+wallet provider, account, data source and access policy. It does not enable a
+network in the production API or provide share-multiplier conversion. The
+playground's `/thena` route demonstrates the composition with a live injected
+wallet. Approvals, signatures and trades require the user's wallet confirmation.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,25 @@
+# Third-party notices
+
+The shared value display includes `torph` 0.1.2 under the MIT License:
+
+MIT License
+
+Copyright (c) 2025 Lochie Axon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.