aegis-swap-widget 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.6.0
+
+### Minor Changes
+
+- d401c4d: Add optional partner context UI, host-owned action requirements, and one-shot launch intents that open a matching Engine Buy or Borrow market and prefill a concrete resource amount without submitting a transaction.
+
+  Adds the `partnerContext`, `partnerLaunchIntent`, `onPartnerLaunchIntentApplied`, `onPartnerAction`, and `onPartnerRequirementAction` props to `AegisEngineWidget`. The partner-neutral `PartnerActionRequirement` keeps host action semantics separate from the explicit Buy/Borrow launch event. The change also forwards `pools`/`poolIds` to the Buy surface and publishes the normalized contract from a new `aegis-swap-widget/partner-context` export. Omitting `partnerContext` keeps current behavior and performs no extra requests.
+
+  The `embedded` presentation is silent for aggregate partner facts and renders only a compact host-owned action requirement inside Buy or Borrow transaction content. The `showroom` presentation retains partner identity, environment, balances, activities, details, and navigation for integration evaluation.
+
+  API-backed partner amounts can additionally retain a validated raw base-unit integer and decimal scale. Partner blocks and action targets can carry observation and validity provenance; incomplete raw-amount or action-provenance pairs fail closed while the original display-only host shape remains compatible. Expired host requirements cannot produce a launch intent.
+
+### Patch Changes
+
+- d401c4d: Make collapsed Engine disclosures findable with the browser's page search. TX details, the Borrow/Lend details panel, the lifecycle card body and both position-row details now hide with `hidden="until-found"` instead of `visibility`, so Cmd/Ctrl+F, `#fragment` navigation and `#:~:text=` links reach their text and expand the panel that holds it.
+
+  Closed panels still leave the tab order — `content-visibility` skips its subtree the same way the previous `visibility` flip did — and the collapse animation is unchanged: searchability is re-armed only after the transition finishes. The attribute is applied only where the browser supports it (feature-detected via `beforematch`); elsewhere the previous `visibility` behavior is untouched. Panels also assert their own `display`, so a host stylesheet with an unguarded `[hidden] { display: none }` reset cannot flatten the accordion track.
+
 ## 0.5.1
 
 ### Patch Changes

package/README.md

@@ -58,6 +58,123 @@ export function Engine({ account, provider }) {
 }
 ```
 
+## Partner context and host action requirements
+
+`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.
+
+An `actionRequirement` is the host's authoritative statement of what a selected
+partner action needs. The widget can display the shortfall and let the user
+explicitly open Buy or Borrow. The choice creates an editable prefill; it never
+submits a transaction or changes Aegis market data:
+
+```tsx
+import { AegisEngineWidget } from 'aegis-swap-widget'
+import type { PartnerContext } from 'aegis-swap-widget/partner-context'
+
+const partnerContext = {
+  partner: { id: 'wolf-game', name: 'Wolf Game' },
+  actionRequirement: {
+    id: 'upgrade-barn-water',
+    label: 'Upgrade Barn',
+    resource: {
+      chainId: 1,
+      address: '0x828B22c9ea1c20B551EeFC6198174C4bb7a8CBF6',
+      symbol: 'WATER',
+    },
+    requiredAmount: '1000',
+    availableAmount: '660',
+    shortfallAmount: '340',
+    resourceUse: 'consumed',
+  },
+} satisfies PartnerContext
+
+export function GameMarket() {
+  return (
+    <AegisEngineWidget
+      partnerContext={partnerContext}
+      partnerContextVariant="embedded"
+      onPartnerRequirementAction={(requirement, surface) => {
+        console.log(surface, requirement.id)
+      }}
+      onPartnerLaunchIntentApplied={(intent) => {
+        console.log('Editable amount applied', intent.amount)
+      }}
+    />
+  )
+}
+```
+
+`requiredAmount`, `availableAmount`, and `shortfallAmount` are canonical token-unit
+decimal strings, not grouped text or raw base units. When `availableAmount` is
+present, the shortfall must equal `max(required - available, 0)`. `resourceUse`
+is host-owned disclosure: `'consumed'`, `'returned'`, or `'unknown'`. It does not
+make Borrow a recommendation.
+
+API-backed display amounts may also include `rawAmount` and `decimals`. Supply
+both or neither. `rawAmount` is a canonical nonnegative base-unit integer; it
+remains display-only and never becomes a transaction amount. Environment,
+production, inventory, and activity blocks can carry a `PartnerObservation`
+with `observedAt` and optional `validUntil`. An action target can carry the same
+validity provenance plus a host-owned `reason`. Partial or malformed amount and
+action-provenance blocks fail closed at the widget boundary. The launch helper
+also rejects a requirement once its optional `expiresAt` deadline is reached.
+
+If the host owns the action button outside the widget, keep using a separate
+one-shot `partnerLaunchIntent`. The exported helper maps a validated requirement
+to that event without duplicating its resource or amount:
+
+```tsx
+import { partnerLaunchIntentForRequirement } from 'aegis-swap-widget/partner-context'
+
+const launchIntent = partnerLaunchIntentForRequirement(
+  partnerContext.actionRequirement,
+  'borrow',
+  crypto.randomUUID()
+)
+```
+
+The equivalent launch intent is:
+
+```ts
+{
+  requestId: 'new-id-for-this-click',
+  source: 'action-requirement',
+  requirementId: 'upgrade-barn-water',
+  surface: 'borrow',
+  resource: {
+    chainId: 1,
+    address: '0x828B22c9ea1c20B551EeFC6198174C4bb7a8CBF6',
+    symbol: 'WATER',
+  },
+  amount: '340',
+}
+```
+
+Pass that value through `partnerLaunchIntent` and clear it after
+`onPartnerLaunchIntentApplied`. Use a new `requestId` for each external click.
+Borrow fills the debt token's “I need” field. Buy uses the matching direct pool
+and fills an exact-output Receive amount. The widget never submits automatically
+and fails closed when the chain, market, token identity, or precision does not
+match.
+
+Use `partnerContextVariant="embedded"` inside an existing product shell. It is
+silent unless the host supplies an `actionRequirement`; then the widget places
+one compact purpose row beside the active Buy or Borrow transaction content.
+Partner identity, weather, aggregate balances, activities, secondary details,
+and navigation remain available only in the default `showroom` variant. If the
+host already owns resource selection, pass its exact Engine `marketId`. This
+controlled form hides the widget market picker and prevents partner actions from
+selecting another market. Use `defaultMarketId` when the widget should own
+selection.
+
+Wolf Game's current aggregate API provides Community 12 balances, weather, and
+harvesting data. 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.
+
 The Engine discovery surface defaults to Amplifi's public production REST API.
 The production source implements
 `GET /v1/engine/markets?chainId=`,
@@ -122,9 +239,11 @@ Product semantics are deliberately conservative:
   impermanent-loss exposure.
 - The widget does not claim borrowing is cheaper than buying without a
   partner-provided returnability/consumption model and duration.
-- Positions are indexed snapshots (open + display). Last-locked LTV is not
-  presented as current health. Repay, redeem, close, and withdraw flows are
-  deferred and not exposed in the widget.
+- Positions start from indexed discovery snapshots. Last-locked LTV is not
+  presented as current health. The management dialog rehydrates live RPC state
+  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.
 - Lender balances are indexed Engine share units, not token amounts; the widget
   does not invent a token/USD value without a current share price.
 
@@ -766,6 +885,7 @@ No other props changed. See the [CHANGELOG](./CHANGELOG.md) for the full entry.
 - `networkSelectorColorMode`: `'accent'` (default) keeps host-brand selector chrome; `'chain'` uses the built-in DFF chain palette for supported chains.
 - `pools`: direct pool configs to render and swap against. This is the canonical config path.
 - `defaultPoolId`: initial pool id when `pools` is provided.
+- `poolId`: controlled active pool id. Pair with `onPoolChange` when the host owns pool selection; updates change the form in place.
 - `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`.
@@ -779,7 +899,10 @@ 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'`).
+- `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.
 - `subtitle`: optional header eyebrow. Defaults to empty. Pass a string to show it.
 - `ariaLabel`: optional accessible label for the widget region. Defaults to `Swap` for Swap and `Lend, borrow, and buy` for Engine.
 - `theme`: `dark`, `light`, or `auto` (follows `prefers-color-scheme`). Defaults to `dark`.