aegis-swap-widget 0.1.2 → 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,16 +1,17 @@
 # Aegis Swap Widget
 
-Embeddable React swap widget for Aegis direct pools. 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.
 
-On Ethereum mainnet, widget swaps apply a fixed 50 bps output-token fee to
-`0x8ea2C7de60ef1Cd4dcE64ea2DDDe2f99F0127eFC`. The widget does not apply this
-fee on other chains yet.
+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
 
@@ -25,12 +26,7 @@ import { AegisSwapWidget } from 'aegis-swap-widget'
 import 'aegis-swap-widget/styles.css'
 
 export function Swap() {
-  return (
-    <AegisSwapWidget
-      theme="dark"
-      accentColor="#31d48a"
-    />
-  )
+  return <AegisSwapWidget />
 }
 ```
 
@@ -55,7 +51,9 @@ 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.
 
 ## Configure Pools
 
@@ -86,24 +84,27 @@ export function Swap() {
 }
 ```
 
-Use `defaultPoolId` to choose which pool opens first. Use `targets` when a host wants a different pool order or subset:
+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"
-  targets={['GRASS_USDC', 'WATER_USDC']}
+  poolIds={['GRASS_USDC', 'WATER_USDC']}
 />
 ```
 
 ## Fees
 
-The widget applies a fixed output-token fee only on Ethereum mainnet:
+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.
+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:
 
@@ -255,24 +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, including per-chain `v4Contracts`.
-- `pools`: direct pool configs to render and swap against.
+- `pools`: direct pool configs to render and swap against. This is the canonical config path.
 - `defaultPoolId`: initial pool id when `pools` is provided.
-- `targets`: optional pool id order/subset.
-- `defaultDirection`: `intoTarget` for USDC to target, or `outOfTarget` for target to USDC.
-- `markets`: advanced override for normalized pool/router/quoter config.
-- `rpcUrls`: optional RPC fallback list for the active chain.
+- `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`.
-- `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
 
@@ -287,9 +343,30 @@ 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;