@deeeed/metamask-harness 0.36.0 → 0.37.0

package/docs/RELEASE-QA-CAPABILITY-MAP.md

@@ -0,0 +1,150 @@
+# Release QA capability map
+
+This document maps the Extension release checklists to durable recipe
+capabilities. The baseline is `mm-harness` 0.36.0. It is a capability map, not
+a claim that the listed release cases currently pass.
+
+Source baseline: QA repository commit
+[`77591c5`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/tree/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension).
+The relevant sources are the Perps
+[`checklist`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/perps-rc/perps-rc-regression.md)
+and
+[`runbook`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/perps-rc/runbook.md),
+Assets
+[`checklist`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/assets-rc/assets-rc-regression.md)
+and
+[`runbook`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/assets-rc/runbook.md),
+Swap and Bridge
+[`checklist`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/swap-bridge-rc/swap-bridge-rc-regression.md)
+and
+[`runbook`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/swap-bridge-rc/runbook.md),
+and Networks
+[`checklist`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/networks-regression-rc/networks-regression-rc.md)
+and
+[`runbook`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/networks-regression-rc/runbook.md).
+
+Ratings:
+
+- **AVAILABLE**: a typed capability supplies the required setup, operation, or
+  machine-checkable observation.
+- **PARTIAL**: generic UI operations or a narrower domain action can perform
+  part of the case, but deterministic setup or a domain assertion is absent.
+- **MISSING**: no durable recipe capability covers the case family.
+- **TARGET**: being implemented in the current change; not present in 0.36.0.
+
+## Cross-cutting capabilities
+
+| Requirement | 0.36.0 capability | Status |
+| --- | --- | --- |
+| Discover the typed surface | `mm-harness actions --adapter extension --json` exposes the schemas in the [Extension action manifest](../library/manifests/extension.action-manifest.json), so a plan can reject unsupported domain operations before launch. | **AVAILABLE** |
+| Validate and launch the downloaded official RC artifact | Network discovery and download remain in the release-validation workflow, following the QA [`download-build.sh`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/assets-rc/scripts/download-build.sh) contract. | **TARGET**: verify a local Extension ZIP or Android APK against its trusted digest and declared product identity, then run it without using a checkout build. Extension adds safe extraction, cached tree integrity, and isolated launch. Android adds explicit-device install and launch; release recipes use native accessibility without a development bridge, Metro, or HUD. Downloaded iOS artifacts remain unsupported. |
+| Start from an imported wallet or clean onboarding | [`metamask.wallet.import`](../library/actions/extension/wallet/import.mjs), [`metamask.wallet.reset`](../library/actions/extension/wallet/reset.mjs), and the shared [`import`](../library/recipes/wallet/import.recipe.json) and [`reset-import`](../library/recipes/wallet/reset-import.recipe.json) recipes can use visible UI and parameterized credential sources. | **AVAILABLE** |
+| Drive and observe UI | The [Extension action manifest](../library/manifests/extension.action-manifest.json) exposes typed navigation, press, input, key, scroll, wait, screenshot, surface capture, locators, and CDP target selection. | **AVAILABLE** for mechanics; domain meaning remains **PARTIAL**. |
+| Record evidence and a terminal verdict | Recipe traces, action results, screenshots, and artifact indexing exist. There is no release-plan completion gate equivalent to the QA [`validate-run-report.sh`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/assets-rc/scripts/validate-run-report.sh), including canonical case-ID coverage and explicit remaining cases. | **PARTIAL** |
+| Parameterized environment control | Wallet import choices and Extension analytics consent are typed. Domain fixtures, service doubles, geo eligibility, network catalogs, and remote stream scenarios are not general release-plan inputs. | **MISSING** |
+
+## Perps: 64 Critical cases
+
+The existing Perps surface can prepare, read, assert, and close selected
+positions and open orders, and place a basic order. See the
+[`Extension manifest`](../library/manifests/extension.action-manifest.json) and
+[`smoke recipe`](../library/recipes/extension/perps/smoke.recipe.json). It does
+not reproduce the checklist's seeded account snapshot: balance, long and short
+positions, limit orders, take-profit/stop-loss state, activity, watchlist, and
+controlled provider responses and streams.
+
+| Case family | Required start state | Required operations and assertions | 0.36.0 coverage |
+| --- | --- | --- | --- |
+| Feature, navigation, session (4) | Feature/eligibility combinations and accounts with different Perps state | Toggle gates, lock/unlock, switch accounts, navigate back; assert gating, account isolation, and route recovery | **PARTIAL**: wallet/account and generic navigation exist; deterministic gates and Perps session assertions are missing. |
+| Perps home (8) | Seeded balance, positions, orders, watchlist, and history | Open cards and balance actions, mutate watchlist; assert all seeded summaries and recent activity | **PARTIAL**: position/order reads and assertions exist; account, market, watchlist, and activity observations are missing. |
+| Market list (4) | Controlled catalog, categories, and price updates | Search, filter, sort, open a market; assert catalog and live values | **PARTIAL**: UI mechanics only; no market catalog or price assertion. |
+| Market details (6) | Selected market data, candles, position, and market-specific order | Navigate and change chart range; assert header, stats, chart states, action mode, and selected-market orders | **PARTIAL**: route and selected order/position state only; market and chart observations are missing. |
+| Order entry (12) | Known balance, constraints, price, leverage limits, and order outcomes | Edit side, amount, percent, leverage, limit price, TP/SL; submit market/limit orders; assert validation, preview, fill, resting order, and duplicate protection | **PARTIAL**: basic placement and open-order convergence exist; rich entry controls, limit/TP-SL inputs, validation, and outcome fields are missing. |
+| Position management (11) | Seeded isolated position, margin, TP/SL, and resting order | Add/reduce exposure, add margin, edit TP/SL, cancel order; assert size, margin, liquidation price, TP/SL, and removal | **PARTIAL**: close positions/orders exists; modify, margin, TP/SL, and rich field assertions are missing. |
+| Deposit (3) | Funded wallet and known Perps balance | Enter amount/Max and confirm; assert validation, pending/success, and resulting balances/activity | **MISSING** |
+| Withdraw (4) | Known withdrawable balance | Enter amount/percent/Max and confirm; assert validation, destination, balance, and activity | **MISSING** |
+| Activity and history (6) | Seeded trades, orders, funding, deposits, and withdrawals | Filter and open details; assert type-specific rows and agreement with home | **MISSING** |
+| Streaming and resilience (4) | Controllable initial responses, updates, reconnects, and order events | Refresh, disconnect/reconnect, close/reopen; assert price, position, order, activity, and loading-state reconciliation | **MISSING** |
+| Geo/compliance (1) | Ineligible trade state | Attempt a trade; assert blocking UI and no submitted order | **MISSING** |
+| Responsive presentation (1) | Popup-width Perps views with populated content | Traverse core views and capture surfaces; assert no clipping or overlap | **PARTIAL**: screenshots and generic UI assertions exist; no reusable Perps presentation assertion. |
+
+The aggregate Extension Perps snapshot is a **TARGET**. It exposes account,
+market, position, open-order, activity, and watchlist observations in one typed,
+read-only result when the Extension background test hook is present. An
+untouched production artifact does not expose that hook, so official-artifact
+Perps assertions still require a product-supported observation boundary. The
+snapshot also does not create the required start state.
+
+## Assets: 22 Critical cases
+
+| Case family | Required start state | Required operations and assertions | 0.36.0 coverage |
+| --- | --- | --- | --- |
+| Token list, prices, details, sorting (4) | Imported account with known live holdings across networks | Open and sort token list/details; assert holdings, fiat, change, chart, and market data | **PARTIAL**: wallet import and UI mechanics only; no asset reads or assertions. |
+| Token import, hide, persistence, custom network (5) | Known ERC-20 contracts and custom network configuration | Search/import/hide/re-add/restart/remove network; assert visibility and persistence | **MISSING**: no token-list/import or custom-network domain actions. |
+| Real-time and aggregate balances (2) | Known multi-chain balances and an externally triggered update | Observe stream and aggregate; assert prompt update and total | **MISSING** |
+| EVM send and activity (3) | Two owned accounts with native/token funds and gas | Send token, native Max, and custom-gas transaction; assert confirmation, balances, gas behavior, and activity | **MISSING** |
+| NFTs (3) | Owned indexed NFT plus owned and unowned contracts | Detect/import/filter/open media; assert ownership rejection, metadata, image, and network filter | **MISSING** |
+| DeFi positions (2) | Account with known live protocol positions | Open list/details; assert protocol, supplied/borrowed assets, and USD totals | **MISSING** |
+| Solana assets and send (2) | Imported Solana account with SOL and SPL balances | Inspect assets and send SPL; assert fiat, confirmation, balances, and activity | **MISSING** |
+| Bitcoin balance (1) | Imported Bitcoin account with known balance | Open asset details; assert balance, fiat, and chart | **MISSING** |
+
+## Swap and Bridge: 39 cases (25 Critical, 14 Non-Critical)
+
+These cases intentionally form a sequential, live-funds journey. A successful
+step changes the next step's network and balances, so generic navigation alone
+cannot establish or prove the required state transitions.
+
+| Case family | Required start state | Required operations and assertions | 0.36.0 coverage |
+| --- | --- | --- | --- |
+| Random ERC-20 round trip on Ethereum (2 Critical) | Funded imported account and live token/quote services | Select eligible random token, swap amount then Max; assert quote, confirmation, balance deltas, and activity | **MISSING** |
+| WETH round trip (2 Critical) | Funded Ethereum account | Swap ETH to WETH and Max back; assert quotes, wrapping result, balance deltas, and activity | **MISSING** |
+| Gasless round trip (2 Critical) | Smart Transactions enabled and funded ETH/USDC balances | Execute full-balance gasless swaps; assert route, no stranded input, balances, and activity | **MISSING** |
+| Ethereum to native Solana (2 Critical) | Funded Ethereum source and derived Solana destination | Bridge Max and await completion; assert destination asset is native SOL, balances, and activity | **MISSING** |
+| Half/Max swaps across destination networks (12 Critical, 8 Non-Critical) | Balance delivered by the preceding bridge on each network | Pick supported random token, swap about half and Max back; assert quote/route, confirmation, balance deltas, and activity | **MISSING** |
+| Sequential onward bridges (5 Critical, 4 Non-Critical) | Source balance produced by the preceding swap | Bridge Max to the specified next network and await completion; assert source/destination assets, balances, and activity | **MISSING** |
+| Quote-only networks (2 Non-Critical) | Selected network and funded source asset | Request but do not submit a quote; assert supported routes, fees, and destination | **MISSING** |
+
+## Networks: 10 cases (7 Critical, 3 not marked Critical)
+
+| Case family | Required start state | Required operations and assertions | 0.36.0 coverage |
+| --- | --- | --- | --- |
+| Custom-network asset rendering (4) | HyperEVM, INK, and XDC configurations plus known token contracts/balances | Add/select networks and tokens; assert decimals, render stability, logos, and token rows | **MISSING** |
+| Fiat and price APIs (2) | Custom networks with supported native assets and conversion responses | Refresh/select network; assert conversion rates and fiat values | **MISSING** |
+| Send Max and activity (2) | Funded HyperEVM/INK accounts and recipient | Send native Max; assert review amount, gas handling, completion, balance, and activity | **MISSING** |
+| Bridge label, tracking, details (2) | Funded Monad account and a completed bridge route | Submit/open bridge activity; assert label, status tracking, route, fees, and details | **MISSING** |
+
+## Prioritized delivery order
+
+1. **Downloaded official artifact validation and launch — current target.**
+   Accept a local ZIP, trusted digest, and requested version from the
+   release-validation workflow; validate the manifest and extracted tree,
+   reuse a validated cache, and launch without modifying the source checkout
+   or original artifact. Prove onboarding, visible wallet import, normal popup
+   operation, and side-panel operation.
+2. **Aggregate Extension Perps snapshot — current target.** Add a typed,
+   read-only result for account, markets, positions, open orders, activity, and
+   watchlist, with selectors suitable for machine assertions. It is usable in
+   source-built runtimes that expose the background test hook; an untouched
+   production artifact must fail explicitly until it has a supported read-only
+   observation boundary.
+3. **Deterministic Perps start state.** Add setup-time, trace-visible provider
+   doubles and seeded balance, positions, limit orders, TP/SL, activity, and
+   watchlist. Keep setup outside the proof window and never mutate product
+   state to manufacture an assertion.
+4. **Complete Perps operations and assertions.** Add parameterized feature and
+   eligibility control, watchlist, rich order entry, position changes, margin,
+   TP/SL, deposits, withdrawals, activity filters, and stream recovery. Extend
+   shared Mobile/Extension vocabulary where both clients support the behavior.
+5. **Release-plan completion gate.** Validate canonical case IDs, verdict
+   counts, required evidence, and explicit remaining cases before reporting a
+   terminal result.
+6. **Assets and Networks domain surfaces.** Add shared network selection and
+   custom-network state first, then typed assets, balances, token import,
+   transaction/activity, NFT, DeFi, and non-EVM observations.
+7. **Swap and Bridge domain surface.** Add quote, route, submit, status,
+   balance-delta, and activity actions with explicit live-funds safeguards and
+   resumable sequential state.
+
+Completing the two current targets does **not** provide full Perps parity. The
+64-case plan still depends on deterministic domain state, controlled provider
+behavior, richer mutations and assertions, and a canonical completion gate.

package/library/actions/extension/perps/perps.mjs

@@ -1,5 +1,6 @@
 import { pathToFileURL } from 'node:url';
 import { dataTestId, marketSymbol, normalizeMarketSymbol, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import { readSnapshot } from './read_snapshot.mjs';
 import { readPerpsRuntimeStateExpression } from './state.mjs';
 
 function sleep(ms) {
@@ -832,6 +833,7 @@ export async function teardownState(input) {
 }
 
 const DIRECT_ACTIONS = new Map([
+  ['metamask.perps.read_snapshot', readSnapshot],
   ['metamask.perps.read_positions', readPositions],
   ['metamask.perps.read_orders', readOrders],
   ['metamask.perps.close_positions', closePositions],

package/library/actions/extension/perps/read_snapshot.mjs

@@ -0,0 +1,470 @@
+import { pathToFileURL } from 'node:url';
+
+import { normalizeMarketSymbol, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+
+const ALL_SECTIONS = ['account', 'markets', 'positions', 'orders', 'history', 'watchlist'];
+const DEFAULT_HISTORY_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
+const MAX_HISTORY_WINDOW_MS = 365 * 24 * 60 * 60 * 1000;
+
+function boundedInteger(value, fallback, minimum, maximum, name) {
+  const resolved = value == null ? fallback : Number(value);
+  if (!Number.isInteger(resolved) || resolved < minimum || resolved > maximum) {
+    throw new Error(`metamask.perps.read_snapshot ${name} must be an integer from ${minimum} to ${maximum}.`);
+  }
+  return resolved;
+}
+
+function requestedMarkets(node) {
+  if (node.market != null && node.markets != null) {
+    throw new Error('metamask.perps.read_snapshot accepts market or markets, not both.');
+  }
+  const values = node.markets ?? (node.market == null ? [] : [node.market]);
+  if (!Array.isArray(values)) {
+    throw new Error('metamask.perps.read_snapshot markets must be an array of market symbols.');
+  }
+  const markets = Array.from(new Set(
+    values.map((value) => typeof value === 'string' ? normalizeMarketSymbol(value) : '').filter(Boolean),
+  ));
+  if (markets.length > 100) {
+    throw new Error('metamask.perps.read_snapshot accepts at most 100 market symbols.');
+  }
+  return markets;
+}
+
+export function resolveSnapshotOptions(input, now = Date.now()) {
+  const node = input.node ?? {};
+  const include = node.include ?? ALL_SECTIONS;
+  if (!Array.isArray(include) || include.length === 0) {
+    throw new Error('metamask.perps.read_snapshot include must be a non-empty array.');
+  }
+  const sections = Array.from(new Set(include.map((section) => String(section).toLowerCase())));
+  const unsupported = sections.filter((section) => !ALL_SECTIONS.includes(section));
+  if (unsupported.length > 0) {
+    throw new Error(`metamask.perps.read_snapshot received unsupported sections: ${unsupported.join(', ')}.`);
+  }
+
+  const history = node.history && typeof node.history === 'object' && !Array.isArray(node.history)
+    ? node.history
+    : {};
+  const endTime = boundedInteger(
+    history.end_time_ms,
+    now,
+    0,
+    Number.MAX_SAFE_INTEGER,
+    'history.end_time_ms',
+  );
+  const startTime = boundedInteger(
+    history.start_time_ms,
+    Math.max(0, endTime - DEFAULT_HISTORY_WINDOW_MS),
+    0,
+    Number.MAX_SAFE_INTEGER,
+    'history.start_time_ms',
+  );
+  if (startTime > endTime) {
+    throw new Error('metamask.perps.read_snapshot history.start_time_ms must not exceed history.end_time_ms.');
+  }
+  if (endTime - startTime > MAX_HISTORY_WINDOW_MS) {
+    throw new Error('metamask.perps.read_snapshot history range must not exceed 365 days.');
+  }
+
+  return {
+    include: sections,
+    markets: requestedMarkets(node),
+    timeoutMs: boundedInteger(node.timeout_ms, 20000, 1000, 60000, 'timeout_ms'),
+    maxItems: boundedInteger(node.max_items_per_section, 100, 1, 500, 'max_items_per_section'),
+    history: {
+      startTime,
+      endTime,
+      accountId: history.account_id == null || history.account_id === ''
+        ? undefined
+        : String(history.account_id),
+      limit: boundedInteger(history.limit, 100, 1, 500, 'history.limit'),
+    },
+  };
+}
+
+export function snapshotRequestExpression(options) {
+  const methods = {
+    account: ['perpsGetAccountState', []],
+    markets: ['perpsGetMarketDataWithPrices', []],
+    positions: ['perpsGetPositions', []],
+    orders: ['perpsGetOpenOrders', []],
+    history: ['perpsGetUserHistory', null],
+    watchlist: ['perpsGetWatchlistMarkets', []],
+  };
+  return `(async () => {
+    const request = globalThis.stateHooks?.submitRequestToBackground;
+    if (typeof request !== 'function') {
+      throw new Error('stateHooks.submitRequestToBackground is unavailable; cannot read live Perps snapshot.');
+    }
+    const timeoutMs = ${JSON.stringify(options.timeoutMs)};
+    const historyParams = {
+      startTime: ${JSON.stringify(options.history.startTime)},
+      endTime: ${JSON.stringify(options.history.endTime)},
+      accountId: ${options.history.accountId === undefined ? 'undefined' : JSON.stringify(options.history.accountId)},
+    };
+    const methods = ${JSON.stringify(methods)};
+    const markets = ${JSON.stringify(options.markets)};
+    const maxItems = ${JSON.stringify(options.maxItems)};
+    const historyLimit = ${JSON.stringify(Math.min(options.history.limit, options.maxItems))};
+    function field(record, names) {
+      for (const name of names) {
+        const value = record?.[name];
+        if (value === null || ['string', 'number', 'boolean'].includes(typeof value)) return value;
+      }
+      return null;
+    }
+    function marketFor(item) {
+      const value = field(item, ['symbol', 'coin', 'market', 'asset']);
+      return typeof value === 'string' ? value.replace(/-PERP$/iu, '').toUpperCase() : '';
+    }
+    function sideFor(item) {
+      const side = String(field(item, ['side', 'direction']) ?? '').toLowerCase();
+      if (['buy', 'b', 'long'].includes(side)) return 'long';
+      if (['sell', 'a', 's', 'short'].includes(side)) return 'short';
+      return side || null;
+    }
+    function leverageFor(item) {
+      const leverage = item?.leverage;
+      if (leverage === null || ['string', 'number'].includes(typeof leverage)) return leverage;
+      if (!leverage || typeof leverage !== 'object' || Array.isArray(leverage)) return null;
+      return { type: field(leverage, ['type']), value: field(leverage, ['value']) };
+    }
+    function normalize(section, item) {
+      if (section === 'markets') return {
+        market: marketFor(item) || null,
+        name: field(item, ['name']),
+        price: field(item, ['price', 'currentPrice']),
+        markPrice: field(item, ['markPrice', 'markPx']),
+        oraclePrice: field(item, ['oraclePrice', 'oraclePx']),
+        change24hPercent: field(item, ['change24hPercent', 'priceChange24h']),
+        volume24h: field(item, ['volume24h', 'dayNtlVlm']),
+        openInterest: field(item, ['openInterest']),
+        fundingRate: field(item, ['fundingRate', 'funding']),
+        maxLeverage: field(item, ['maxLeverage']),
+      };
+      if (section === 'positions') return {
+        market: marketFor(item) || null,
+        side: sideFor(item),
+        size: field(item, ['size', 'szi']),
+        entryPrice: field(item, ['entryPrice', 'entryPx']),
+        positionValue: field(item, ['positionValue']),
+        leverage: leverageFor(item),
+        liquidationPrice: field(item, ['liquidationPrice', 'liquidationPx']),
+        marginUsed: field(item, ['marginUsed']),
+        unrealizedPnl: field(item, ['unrealizedPnl']),
+        returnOnEquity: field(item, ['returnOnEquity']),
+        takeProfitPrice: field(item, ['takeProfitPrice']),
+        stopLossPrice: field(item, ['stopLossPrice']),
+      };
+      if (section === 'orders') return {
+        orderId: field(item, ['orderId', 'id', 'oid']),
+        market: marketFor(item) || null,
+        side: sideFor(item),
+        size: field(item, ['size', 'sz', 'szi']),
+        price: field(item, ['price', 'limitPx', 'px']),
+        type: field(item, ['orderType', 'type']),
+        status: field(item, ['status']),
+        timestamp: field(item, ['timestamp', 'time']),
+        reduceOnly: field(item, ['reduceOnly']),
+        isTrigger: field(item, ['isTrigger']),
+        triggerPrice: field(item, ['triggerPrice', 'triggerPx']),
+        triggerOrderType: field(item, ['triggerOrderType']),
+        takeProfitPrice: field(item, ['takeProfitPrice']),
+        stopLossPrice: field(item, ['stopLossPrice']),
+      };
+      return {
+        type: field(item, ['type', 'activityType']),
+        status: field(item, ['status']),
+        asset: field(item, ['asset', 'token', 'currency']),
+        market: marketFor(item) || null,
+        amount: field(item, ['amount', 'value']),
+        fee: field(item, ['fee']),
+        timestamp: field(item, ['timestamp', 'time']),
+        transactionHash: field(item, ['transactionHash', 'txHash', 'hash']),
+      };
+    }
+    function transport(section, value) {
+      if (section === 'account') {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) return { value };
+        const allowed = ${JSON.stringify([
+          'accountValue', 'totalBalance', 'balance', 'spendableBalance',
+          'withdrawableBalance', 'availableBalance', 'availableToTradeBalance',
+          'marginUsed', 'maintenanceMargin', 'unrealizedPnl', 'returnOnEquity',
+        ])};
+        return { value: Object.fromEntries(allowed.map((name) => [name, field(value, [name])]).filter(([, item]) => item !== null)) };
+      }
+      if (!Array.isArray(value)) return { value };
+      if (section === 'watchlist') {
+        const items = value.map((item) => typeof item === 'string' ? item : marketFor(item)).filter(Boolean);
+        const selected = markets.length === 0 ? items : items.filter((item) => markets.includes(String(item).replace(/-PERP$/iu, '').toUpperCase()));
+        const bounded = selected.slice(0, maxItems).map((item) => String(item).replace(/-PERP$/iu, '').toUpperCase());
+        return { value: bounded, totalCount: value.length, matchingCount: selected.length, truncated: bounded.length < selected.length, transportBound: true };
+      }
+      const selected = markets.length === 0 ? value : value.filter((item) => markets.includes(marketFor(item)));
+      const limit = section === 'history' ? historyLimit : maxItems;
+      const bounded = selected.slice(0, limit).map((item) => normalize(section, item));
+      return { value: bounded, totalCount: value.length, matchingCount: selected.length, truncated: bounded.length < selected.length, transportBound: true };
+    }
+    async function read(section) {
+      const [method, configuredArgs] = methods[section];
+      const args = section === 'history' ? [historyParams] : configuredArgs;
+      let timeoutId;
+      try {
+        const value = await Promise.race([
+          request(method, args),
+          new Promise((_, reject) => {
+            timeoutId = setTimeout(
+              () => reject(new Error(method + ' timed out after ' + timeoutMs + 'ms')),
+              timeoutMs,
+            );
+          }),
+        ]);
+        return [section, { ok: true, method, ...transport(section, value) }];
+      } catch (error) {
+        return [section, {
+          ok: false,
+          method,
+          error: error instanceof Error ? error.message : String(error),
+        }];
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    }
+    return Object.fromEntries(await Promise.all(${JSON.stringify(options.include)}.map(read)));
+  })()`;
+}
+
+function field(record, names) {
+  for (const name of names) {
+    const value = record?.[name];
+    if (value === null || ['string', 'number', 'boolean'].includes(typeof value)) return value;
+  }
+  return null;
+}
+
+function normalizedSide(item) {
+  const side = String(field(item, ['side', 'direction']) ?? '').toLowerCase();
+  if (side === 'buy' || side === 'b' || side === 'long') return 'long';
+  if (side === 'sell' || side === 'a' || side === 's' || side === 'short') return 'short';
+  return side || null;
+}
+
+function normalizedLeverage(item) {
+  const leverage = item?.leverage;
+  if (leverage === null || ['string', 'number'].includes(typeof leverage)) return leverage;
+  if (!leverage || typeof leverage !== 'object' || Array.isArray(leverage)) return null;
+  return {
+    type: field(leverage, ['type']),
+    value: field(leverage, ['value']),
+  };
+}
+
+function marketForItem(item) {
+  const value = field(item, ['symbol', 'coin', 'market', 'asset']);
+  return typeof value === 'string' && value.length > 0 ? normalizeMarketSymbol(value) : '';
+}
+
+function normalizeAccount(account) {
+  const allowed = [
+    'accountValue',
+    'totalBalance',
+    'balance',
+    'spendableBalance',
+    'withdrawableBalance',
+    'availableBalance',
+    'availableToTradeBalance',
+    'marginUsed',
+    'maintenanceMargin',
+    'unrealizedPnl',
+    'returnOnEquity',
+  ];
+  return Object.fromEntries(
+    allowed
+      .map((name) => [name, field(account, [name])])
+      .filter(([, value]) => value !== null),
+  );
+}
+
+function normalizeMarket(item) {
+  return {
+    market: marketForItem(item) || null,
+    name: field(item, ['name']),
+    price: field(item, ['price', 'currentPrice']),
+    markPrice: field(item, ['markPrice', 'markPx']),
+    oraclePrice: field(item, ['oraclePrice', 'oraclePx']),
+    change24hPercent: field(item, ['change24hPercent', 'priceChange24h']),
+    volume24h: field(item, ['volume24h', 'dayNtlVlm']),
+    openInterest: field(item, ['openInterest']),
+    fundingRate: field(item, ['fundingRate', 'funding']),
+    maxLeverage: field(item, ['maxLeverage']),
+  };
+}
+
+function normalizePosition(item) {
+  return {
+    market: marketForItem(item) || null,
+    side: normalizedSide(item),
+    size: field(item, ['size', 'szi']),
+    entryPrice: field(item, ['entryPrice', 'entryPx']),
+    positionValue: field(item, ['positionValue']),
+    leverage: normalizedLeverage(item),
+    liquidationPrice: field(item, ['liquidationPrice', 'liquidationPx']),
+    marginUsed: field(item, ['marginUsed']),
+    unrealizedPnl: field(item, ['unrealizedPnl']),
+    returnOnEquity: field(item, ['returnOnEquity']),
+    takeProfitPrice: field(item, ['takeProfitPrice']),
+    stopLossPrice: field(item, ['stopLossPrice']),
+  };
+}
+
+function normalizeOrder(item) {
+  return {
+    orderId: field(item, ['orderId', 'id', 'oid']),
+    market: marketForItem(item) || null,
+    side: normalizedSide(item),
+    size: field(item, ['size', 'sz', 'szi']),
+    price: field(item, ['price', 'limitPx', 'px']),
+    type: field(item, ['orderType', 'type']),
+    status: field(item, ['status']),
+    timestamp: field(item, ['timestamp', 'time']),
+    reduceOnly: field(item, ['reduceOnly']),
+    isTrigger: field(item, ['isTrigger']),
+    triggerPrice: field(item, ['triggerPrice', 'triggerPx']),
+    triggerOrderType: field(item, ['triggerOrderType']),
+    takeProfitPrice: field(item, ['takeProfitPrice']),
+    stopLossPrice: field(item, ['stopLossPrice']),
+  };
+}
+
+function normalizeHistoryItem(item) {
+  return {
+    type: field(item, ['type', 'activityType']),
+    status: field(item, ['status']),
+    asset: field(item, ['asset', 'token', 'currency']),
+    market: marketForItem(item) || null,
+    amount: field(item, ['amount', 'value']),
+    fee: field(item, ['fee']),
+    timestamp: field(item, ['timestamp', 'time']),
+    transactionHash: field(item, ['transactionHash', 'txHash', 'hash']),
+  };
+}
+
+function selectAndBound(items, options, normalize, limit = options.maxItems, result = {}) {
+  const selected = result.transportBound === true || options.markets.length === 0
+    ? items
+    : items.filter((item) => options.markets.includes(marketForItem(item)));
+  const bounded = selected.slice(0, Math.min(limit, options.maxItems));
+  return {
+    totalCount: result.transportBound === true ? result.totalCount : items.length,
+    matchingCount: result.transportBound === true ? result.matchingCount : selected.length,
+    returnedCount: bounded.length,
+    truncated: result.transportBound === true ? result.truncated === true : bounded.length < selected.length,
+    items: bounded.map(normalize),
+  };
+}
+
+function requireObjectSection(section, result) {
+  if (!result?.ok) {
+    throw new Error(`Requested Perps snapshot section ${section} is unavailable: ${result?.error ?? 'unknown error'}.`);
+  }
+  if (!result.value || typeof result.value !== 'object' || Array.isArray(result.value)) {
+    throw new Error(`Requested Perps snapshot section ${section} is unavailable: ${result.method} returned a non-object result.`);
+  }
+  return result.value;
+}
+
+function requireArraySection(section, result) {
+  if (!result?.ok) {
+    throw new Error(`Requested Perps snapshot section ${section} is unavailable: ${result?.error ?? 'unknown error'}.`);
+  }
+  if (!Array.isArray(result.value)) {
+    throw new Error(`Requested Perps snapshot section ${section} is unavailable: ${result.method} returned a non-array result.`);
+  }
+  return result.value;
+}
+
+export function normalizeSnapshotResult(raw, options) {
+  const sections = {};
+  for (const section of options.include) {
+    const result = raw?.[section];
+    if (section === 'account') {
+      sections.account = {
+        source: result?.method ?? 'perpsGetAccountState',
+        state: normalizeAccount(requireObjectSection(section, result)),
+      };
+      continue;
+    }
+    if (section === 'watchlist') {
+      const values = requireArraySection(section, result);
+      const items = values
+        .map((item) => typeof item === 'string' ? item : marketForItem(item))
+        .filter((item) => typeof item === 'string' && item.length > 0);
+      const selected = result.transportBound === true || options.markets.length === 0
+        ? items
+        : items.filter((item) => options.markets.includes(normalizeMarketSymbol(item)));
+      const bounded = selected
+        .slice(0, options.maxItems)
+        .map((item) => typeof item === 'string' && item.length > 0 ? normalizeMarketSymbol(item) : '')
+        .filter(Boolean);
+      sections.watchlist = {
+        source: result.method,
+        totalCount: result.transportBound === true ? result.totalCount : values.length,
+        matchingCount: result.transportBound === true ? result.matchingCount : selected.length,
+        returnedCount: bounded.length,
+        truncated: result.transportBound === true ? result.truncated === true : bounded.length < selected.length,
+        markets: bounded,
+      };
+      continue;
+    }
+    const values = requireArraySection(section, result);
+    const normalizer = {
+      markets: normalizeMarket,
+      positions: normalizePosition,
+      orders: normalizeOrder,
+      history: normalizeHistoryItem,
+    }[section];
+    sections[section] = {
+      source: result.method,
+      ...selectAndBound(
+        values,
+        options,
+        normalizer,
+        section === 'history' ? options.history.limit : options.maxItems,
+        result,
+      ),
+    };
+  }
+  return sections;
+}
+
+export async function readSnapshot(input) {
+  const options = resolveSnapshotOptions(input);
+  return withExtensionPage(input, async (page) => {
+    const raw = await page.evaluate(snapshotRequestExpression(options));
+    return {
+      action: input.action,
+      source: 'extension-stateHooks-background',
+      include: options.include,
+      markets: options.markets,
+      historyQuery: options.include.includes('history')
+        ? {
+            startTime: options.history.startTime,
+            endTime: options.history.endTime,
+            accountScoped: options.history.accountId !== undefined,
+          }
+        : null,
+      sections: normalizeSnapshotResult(raw, options),
+      redacted: true,
+      proofPath: 'background-perps-snapshot',
+    };
+  });
+}
+
+function isDirectRun() {
+  return process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+}
+
+if (isDirectRun()) {
+  runAdapter(readSnapshot);
+}

package/library/actions/extension/platform/cdp.mjs

@@ -67,9 +67,12 @@ export function extensionTarget(targets, extensionId = null) {
     if (extensionId && extensionIdFromTarget(target) !== extensionId) return false;
     return Boolean(target.webSocketDebuggerUrl);
   });
-  return candidates.find((target) => String(target.url).includes('/home.html')) ??
-    candidates.find((target) => String(target.url).includes('/sidepanel.html')) ??
-    null;
+  const home = candidates.find((target) => String(target.url).includes('/home.html'));
+  const sidepanel = candidates.find((target) => String(target.url).includes('/sidepanel.html'));
+  if (home && String(home.url).includes('/onboarding/completion') && sidepanel) {
+    return sidepanel;
+  }
+  return home ?? sidepanel ?? null;
 }