aegis-swap-widget 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-06-05
+
+### Added
+- Premium embeddable swap surface with collapsible trade details, route chip, token icons,
+  Ethereum light/dark assets, and host-controlled execution details.
+- Exact-vs-max approval mode support, defaulting to exact approvals with Permit2 fallback.
+- Wallet, quote, allowance, balance, token icon, and submit hooks split out of the widget
+  entrypoint for a smaller public surface and easier testing.
+- Address, color, error, transaction progress, and widget view-state helpers with tests
+  organized under `tests/`.
+
+### Changed
+- The public widget entrypoint now delegates to focused widget modules instead of carrying
+  the entire implementation in `src/index.tsx`.
+- Quote and router encoding paths are hardened around calldata construction, stale quote
+  handling, and direct-pool route metadata.
+- Pool, wallet, metadata, and config inputs are normalized more defensively for host apps.
+- The default approval mode is `exact`; hosts can still opt into `max`.
+
+### Deprecated
+- `targets` remains available as a backwards-compatible alias for `poolIds` and will be
+  removed in `0.3.0`.
+
+## [0.1.3] - 2026-06-05
+
+### Added
+- Per-chain internal fee: `fee` field on `AegisSwapChainConfig`, so the output-token
+  fee applies to any bundled chain that sets one (mainnet keeps its 50 bps fee).
+- Package metadata (`license`, `repository`, `homepage`, `bugs`, `keywords`) and a
+  `LICENSE` file (MIT).
+- Test suite (Vitest) covering the quote/encoding money-path, formatting, and config
+  factories, plus a GitHub Actions CI workflow (typecheck + test + build).
+- `prepack` build hook and a `prepublishOnly` typecheck + test gate so published
+  tarballs always contain a fresh build.
+
+### Changed
+- `resolveWidgetFee` now reads the per-chain `fee` from the resolved chain config
+  instead of hardcoding Ethereum mainnet. Default mainnet behavior is unchanged.
+- Swap submission re-quotes immediately before building calldata so the on-chain
+  `amountOutMinimum`/`amountInMaximum` reflect the current price, not a stale quote.
+- After switching the wallet network, submission waits for the switch to settle and
+  continues the swap automatically instead of forcing a second click.
+- `viem` moved from `dependencies` to `peerDependencies` (it was already externalized
+  from the bundle).
+
+### Removed
+- `dist/` build artifacts are no longer committed to git (rebuilt on pack/publish).
+
+## [0.1.2] - 2026-06-04
+
+> Note: the published 0.1.2 tarball was cut before commit `31f01fa`
+> ("Round displayed token amounts"); that change first reaches consumers in the
+> next published version.
+
+### Added
+- Adjustable internal widget swap fee, fixed to Ethereum mainnet (50 bps).
+- Exact-output swaps and a 5-second quote refresh.
+- Per-chain Uniswap v4 contract config (`UNISWAP_V4_CONTRACTS_BY_CHAIN`).
+
+### Changed
+- Display token amounts are rounded (local only; not in the published 0.1.2 tarball).
+
+## [0.1.0] - 2026-06-04
+
+### Added
+- Initial embeddable direct-pool Aegis swap widget for WATER, WOOD, GRASS, and STONE.
+- Generic pool widget API; ERC-20 → Permit2 approval and Permit2 batch signing.
+
+[Unreleased]: https://github.com/amplifi-liquidity/aegis-widget/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/amplifi-liquidity/aegis-widget/compare/v0.1.3...v0.2.0
+[0.1.3]: https://github.com/amplifi-liquidity/aegis-widget/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/amplifi-liquidity/aegis-widget/compare/v0.1.0...v0.1.2
+[0.1.0]: https://github.com/amplifi-liquidity/aegis-widget/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aegis Swap Widget contributors
+
+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.

package/README.md

@@ -1,8 +1,17 @@
 # Aegis Swap Widget
 
-Embeddable React swap widget for WATER, WOOD, GRASS, and STONE. It does not import the private Aegis Engine SDK and does not use Uniswap widget packages.
+Embeddable React swap widget for Aegis direct pools. Import the component, import the CSS, and configure pools, wallet handoff, and host styling through props.
 
-The widget quotes the configured Uniswap v4 pool, handles ERC20 approval to Permit2, signs a Permit2 batch for the Aegis router, and submits the direct pool swap.
+The host app normally only renders `<AegisSwapWidget />`. Quoting, token approval, Permit2 signing, and swap submission are handled inside the widget.
+
+Typing in the Sell field creates an exact-input swap. Typing in the Buy field
+creates an exact-output swap. Active quotes refresh every five seconds while the
+amount is valid.
+
+Widget swaps apply an internal output-token fee per configured chain. The bundled
+Ethereum mainnet config carries a fixed 50 bps fee to
+`0x8ea2C7de60ef1Cd4dcE64ea2DDDe2f99F0127eFC`. A chain carries a fee only when its
+bundled config sets one; today only Ethereum mainnet is bundled.
 
 ## Install
 
@@ -17,16 +26,12 @@ import { AegisSwapWidget } from 'aegis-swap-widget'
 import 'aegis-swap-widget/styles.css'
 
 export function Swap() {
-  return (
-    <AegisSwapWidget
-      defaultTarget="GRASS"
-      theme="dark"
-      accentColor="#31d48a"
-    />
-  )
+  return <AegisSwapWidget />
 }
 ```
 
+Without a `pools` prop, the widget uses the bundled Aegis WATER, WOOD, GRASS, and STONE pool configs. For production integrations, pass the pools the host app wants to expose.
+
 By default the component uses `window.ethereum` when available, so injected wallets
 like MetaMask and Rabby work without any wallet props.
 
@@ -46,36 +51,106 @@ Hosts can choose the widget surface and brand accent at instantiation time:
 />
 ```
 
-`theme` supports `dark` and `light`. `accentColor` accepts any CSS color value and is used for the CTA, selected pools, focus states, links, and swap controls. `accentTextColor` is optional and only needed when the accent color needs a different CTA text color for contrast.
+`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).
+
+The default accent is neutral green. Pass `accentColor`, `accentTextColor`, `title`, `subtitle`, `className`, or `style` when the widget should blend into another product UI.
 
-## Instantiate From Pool Keys
+## Configure Pools
 
-Pass the direct pools you want to expose. When `poolKeys` is provided, the widget only renders those token buttons unless you also pass `targets`.
+Pass the direct pools you want to expose. This is the recommended integration path because it is not tied to any specific asset list.
+
+For the first WATER, WOOD, GRASS, and STONE implementors, use the bundled mainnet pool configs:
+
+```tsx
+import { AegisSwapWidget, AEGIS_SWAP_MARKETS } from 'aegis-swap-widget'
+import 'aegis-swap-widget/styles.css'
+
+const pools = [
+  AEGIS_SWAP_MARKETS.WATER_USDC,
+  AEGIS_SWAP_MARKETS.WOOD_USDC,
+  AEGIS_SWAP_MARKETS.GRASS_USDC,
+  AEGIS_SWAP_MARKETS.STONE_USDC,
+]
+
+export function Swap() {
+  return (
+    <AegisSwapWidget
+      pools={pools}
+      defaultPoolId="WATER_USDC"
+      theme="dark"
+      accentColor="#31d48a"
+    />
+  )
+}
+```
+
+Use `defaultPoolId` to choose which pool opens first. Use `poolIds` when a host wants a different pool order or subset:
+
+```tsx
+<AegisSwapWidget
+  pools={pools}
+  defaultPoolId="GRASS_USDC"
+  poolIds={['GRASS_USDC', 'WATER_USDC']}
+/>
+```
+
+## Fees
+
+The widget applies an internal output-token fee per chain. Each bundled chain config
+carries its own fee. Today only Ethereum mainnet is bundled:
+
+- Fee: `50` bps
+- Recipient: `0x8ea2C7de60ef1Cd4dcE64ea2DDDe2f99F0127eFC`
+
+This fee is internal to the widget and is not configured by host sites — host `chains`
+overrides cannot set or change it. Chains added later carry a fee only when their
+bundled config provides one.
+
+For custom assets, provide full pool and token metadata:
 
 ```tsx
 import {
   AegisSwapWidget,
-  AEGIS_SWAP_MARKETS,
-  type AegisSwapPoolKeys,
+  AEGIS_DYNAMIC_FEE_FLAG,
+  AEGIS_SWAP_HOOK,
+  type AegisSwapPoolConfig,
 } from 'aegis-swap-widget'
 
-const poolKeys: AegisSwapPoolKeys = {
-  GRASS: {
-    poolKey: AEGIS_SWAP_MARKETS.GRASS.poolKey,
-    label: 'USDC / GRASS',
-  },
-  WATER: {
-    poolKey: AEGIS_SWAP_MARKETS.WATER.poolKey,
-    label: 'USDC / WATER',
+const pools: AegisSwapPoolConfig[] = [
+  {
+    id: 'usdc-example',
+    label: 'USDC / EXAMPLE',
+    poolKey: {
+      currency0: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+      currency1: '0xYourTokenAddress',
+      fee: AEGIS_DYNAMIC_FEE_FLAG,
+      tickSpacing: 60,
+      hooks: AEGIS_SWAP_HOOK,
+    },
+    counterToken: {
+      chainId: 1,
+      address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+      name: 'USD Coin',
+      symbol: 'USDC',
+      decimals: 6,
+    },
+    token: {
+      chainId: 1,
+      address: '0xYourTokenAddress',
+      name: 'Example Token',
+      symbol: 'EXAMPLE',
+      decimals: 18,
+      iconUrl: 'https://example.com/token.svg',
+    },
   },
-}
+]
 
 export function Swap() {
-  return <AegisSwapWidget poolKeys={poolKeys} defaultTarget="GRASS" />
+  return <AegisSwapWidget pools={pools} defaultPoolId="usdc-example" />
 }
 ```
 
-For the built-in WATER, WOOD, GRASS, and STONE symbols, the widget fills in token metadata, router, Permit2, Quoter, and pool id automatically. You can override any of those fields inside each pool-key config.
+Each pool can override `router`, `permit2`, `quoter`, and `poolId`. If omitted, those values come from the active chain config.
 
 ## Chains
 
@@ -92,11 +167,38 @@ import { mainnet } from 'viem/chains'
       rpcUrls: ['https://your-mainnet-rpc.example'],
     },
   }}
-  poolKeys={poolKeys}
+  pools={pools}
+/>
+```
+
+Uniswap v4 deployments are configured per chain. The package exports
+`UNISWAP_V4_CONTRACTS_BY_CHAIN` for the supported mainnet deployments listed in
+the official Uniswap v4 deployment docs: Ethereum, Optimism, Unichain, Polygon,
+Base, and Arbitrum.
+
+```tsx
+import { base } from 'viem/chains'
+import { UNISWAP_V4_CONTRACTS_BY_CHAIN } from 'aegis-swap-widget'
+
+<AegisSwapWidget
+  chainId={8453}
+  chains={{
+    8453: {
+      chain: base,
+      router: '0xYourAegisRouter',
+      rpcUrls: ['https://your-base-rpc.example'],
+      v4Contracts: UNISWAP_V4_CONTRACTS_BY_CHAIN[8453],
+    },
+  }}
+  pools={pools}
 />
 ```
 
-For a new chain, provide a viem `chain`, router, Permit2, Quoter, and RPC URLs. Pool-key entries can set `chainId`, `token`, and `counterToken` when the token addresses differ by chain.
+For a new chain that is not bundled, provide a viem `chain`, Aegis router, RPC
+URLs, and `v4Contracts` with at least `permit2` and `quoter`. Include
+`poolManager`, `positionManager`, `stateView`, and `universalRouter` when the
+host app needs those addresses too. Pool entries can set `chainId`, `token`, and
+`counterToken` when token addresses differ by chain.
 
 ## Token Icons
 
@@ -106,11 +208,11 @@ The widget fetches token icons by address using the metadata IDs from the Aegis
 ```tsx
 <AegisSwapWidget
   metadataEndpoint="/graphql/meta"
-  poolKeys={poolKeys}
+  pools={pools}
 />
 ```
 
-Use `metadataEndpoint={null}` to disable backend icon hydration. Tokens can also provide `iconUrl` directly when passed through a custom `market` or pool-key token override.
+Use `metadataEndpoint={null}` to disable backend icon hydration. Tokens can also provide `iconUrl` directly.
 
 ## With Existing Wallet UI
 
@@ -121,7 +223,7 @@ If a site already has wallet state, pass its EIP-1193 provider and account:
   provider={provider}
   account={account}
   onConnectWallet={openWallet}
-  defaultTarget="STONE"
+  defaultPoolId="STONE_USDC"
   onSubmitted={(hash) => console.log(hash)}
 />
 ```
@@ -154,25 +256,79 @@ host connect modal creates the provider during the button click:
 If none of these props are supplied, the widget still checks `window.ethereum`
 automatically when it renders and again when the user clicks connect/swap.
 
+## UI Integration
+
+Use `className` for host CSS selectors and `style` for one-off layout overrides or CSS variables:
+
+```tsx
+<AegisSwapWidget
+  className="partner-swap"
+  style={{ maxWidth: 520 }}
+  title="Swap"
+  subtitle="Aegis direct pools"
+  ariaLabel="Partner swap"
+/>
+```
+
+`accentColor`, `accentTextColor`, `title`, and `subtitle` are the intended props for making the widget fit a host surface without forking the component.
+
 ## Props
 
 - `provider`: optional EIP-1193 provider. Defaults to auto-detected `window.ethereum`.
 - `account`: optional connected account from the host wallet UI.
 - `getProvider`: optional provider resolver for wallet libraries with async providers.
 - `onConnectWallet`: optional callback for opening the host wallet modal. It may return `{ provider, account }`.
+- `onSubmitted`: `(hash, swap?)` fired when the swap transaction is sent. `swap` carries mode, token symbols, amounts, and fee for analytics.
+- `onSuccess`: `({ hash, explorerUrl, swap? })` fired when the receipt confirms.
+- `onError`: `(error)` fired on approval/swap failures (after the widget shows its own message).
+- `onQuote`: `(quote)` fired on every quote refresh.
 - `chainId`: active chain id. Defaults to Ethereum mainnet.
-- `chains`: optional chain config overrides or additional chain configs.
-- `poolKeys`: optional direct pool keys to render and swap against.
-- `targets`: optional token button order/subset.
-- `defaultTarget`: `WATER`, `WOOD`, `GRASS`, or `STONE`.
-- `defaultDirection`: `intoTarget` for USDC to target, or `outOfTarget` for target to USDC.
-- `markets`: optional override for pool/router/quoter config.
-- `rpcUrls`: optional RPC fallback list for the active chain.
+- `chains`: optional chain config overrides or additional chain configs, including per-chain `v4Contracts`.
+- `pools`: direct pool configs to render and swap against. This is the canonical config path.
+- `defaultPoolId`: initial pool id when `pools` is provided.
+- `poolIds`: optional pool id order/subset. Use this when the host wants to hide pools or control ordering.
+- `defaultDirection`: `buy` (counter token into the pool token) or `sell`. The legacy `intoTarget`/`outOfTarget` values still work but are deprecated.
+- `markets`: **deprecated** advanced override; pass `pools` (or `Object.values(markets)`) instead.
+- `defaultSlippagePercent`: number (canonical) or numeric string, in percent. Defaults to `1`.
+- `rpcUrls`: RPC fallback list for the active chain, or a `{ [chainId]: string[] }` map for multichain hosts.
 - `metadataEndpoint`: optional metadata GraphQL endpoint for `GlobalToken.iconURL` token icons. Set to `null` to disable.
-- `theme`: `dark` or `light`. Defaults to `dark`.
-- `themeMode`: legacy alias for `theme`.
-- `accentColor`: CSS accent color for the CTA, selected pools, focus states, links, and swap controls.
+- `className`: optional class for host layout and styling hooks.
+- `style`: optional root style object, useful for host layout constraints or CSS variables.
+- `title`: optional widget heading. Empty by default (compact topbar, no header row).
+- `subtitle`: optional header eyebrow. Defaults to empty. Pass a string to show it.
+- `ariaLabel`: optional accessible label for the widget region.
+- `theme`: `dark`, `light`, or `auto` (follows `prefers-color-scheme`). Defaults to `dark`.
+- `accentColor`: CSS accent color for the CTA, selected pools, focus states, links, and swap controls. When set without `accentTextColor`, the widget derives a readable CTA text color automatically (see Appearance for supported color formats).
 - `accentTextColor`: optional CTA text color for contrast with the chosen accent.
+- `showPoolLink`: whether to render the direct-pool link when the active chain provides `poolExplorerUrl`.
+- `defaultApprovalMode`: `exact` approves only the current quote spend by default; `max` opts into the old unlimited ERC-20 to Permit2 approval behavior.
+- `showApprovalModeControl`: whether the details drawer exposes the Exact/Max approval toggle. Defaults to `true`.
+- `showExecutionDetails`: whether to render the collapsible settings drawer for slippage, approval mode, and route. Defaults to `true`.
+- `defaultExecutionDetailsOpen`: whether that settings drawer starts expanded. Defaults to `false`.
+
+The widget intentionally does not inherit the host font; set the
+`--aegis-swap-font-family` CSS variable (via `style` or a stylesheet) to match
+the host typography.
+
+### With wagmi
+
+The widget consumes the host's wallet instead of bundling its own connect UI.
+From a wagmi app, derive the EIP-1193 provider from the active connector:
+
+```tsx
+import { useAccount } from 'wagmi'
+
+function Swap() {
+  const { address, connector } = useAccount()
+  return (
+    <AegisSwapWidget
+      account={address}
+      getProvider={async () => (await connector?.getProvider()) ?? null}
+      onConnectWallet={openConnectModal}
+    />
+  )
+}
+```
 
 ## Default Markets
 
@@ -183,11 +339,34 @@ The package ships mainnet direct-pool configs for:
 - `USDC / GRASS`
 - `USDC / STONE`
 
-These use the Aegis mainnet router `0x00581261a1200956ea05d1810fF28ffd66D8E254`, Permit2, and the public Uniswap v4 Quoter.
+These use the Aegis mainnet router `0x00581261a1200956ea05d1810fF28ffd66D8E254`
+and the Ethereum entry in `UNISWAP_V4_CONTRACTS_BY_CHAIN` for Permit2 and the
+public Uniswap v4 Quoter.
+
+## License
+
+MIT.
 
 ## Local Demo
 
 ```bash
-npm install
+npm ci
 npm run dev
 ```
+
+## Releasing
+
+Maintainer release flow (publishes to npm). `dist/` is not committed — the `prepack`
+hook rebuilds it on every `npm pack`/`npm publish`, and `prepublishOnly` runs the
+typecheck + test gate.
+
+```bash
+git switch main && git pull
+npm ci
+npm run typecheck && npm run test && npm run build
+# Move CHANGELOG [Unreleased] entries under the new version heading.
+npm version patch            # e.g. 0.1.2 -> 0.1.3; commits and tags vX.Y.Z
+git push origin main --follow-tags
+npm publish --access public  # prepublishOnly gate + prepack build run automatically
+npm view aegis-swap-widget version
+```

package/dist/abis.d.ts

@@ -72,6 +72,24 @@ export declare const AEGIS_ROUTER_ABI: readonly [{
     readonly outputs: readonly [];
 }];
 export declare const PERMIT2_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "approve";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint160";
+    }, {
+        readonly name: "expiration";
+        readonly type: "uint48";
+    }];
+    readonly outputs: readonly [];
+}, {
     readonly type: "function";
     readonly name: "allowance";
     readonly stateMutability: "view";
@@ -185,4 +203,3 @@ export declare const UNISWAP_V4_QUOTER_ABI: readonly [{
         readonly type: "uint256";
     }];
 }];
-//# sourceMappingURL=abis.d.ts.map

package/dist/address.d.ts

@@ -0,0 +1,5 @@
+import type { Address, Hex } from 'viem';
+export declare function addressKey(address: Address | null | undefined): string;
+export declare function sameAddress(a: Address, b: Address): boolean;
+export declare function sameOptionalAddress(a: Address | null, b: Address | null): boolean;
+export declare function samePoolId(a: Hex, b: Hex): boolean;