@deeeed/metamask-harness 0.19.1 → 0.20.0

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

@@ -575,10 +575,15 @@ export class ExtensionPage extends CdpWebPage {
     this.port = port;
   }
 
-  async navigateHash(hash) {
+  async navigateHash(hash, timeoutMs = 10000) {
     const normalizedHash = String(hash || '').startsWith('#') ? hash : `#${hash || '/'}`;
-    const href = `${this.origin}/home.html${normalizedHash}`;
-    return this.navigate(href);
+    const navigation = await this.evaluate(`(() => {
+      const before = location.href;
+      location.hash = ${JSON.stringify(normalizedHash)};
+      return { before, href: location.href };
+    })()`);
+    await this.waitForDocumentReady({ expectedUrl: navigation.href, timeoutMs });
+    return { ...navigation, sameDocument: true };
   }
 
   async readPositions() {

package/library/actions/extension/ui/navigate.mjs

@@ -1,31 +1,249 @@
-import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import { pathToFileURL } from 'node:url';
 
-const PAGE_HASHES = {
-  home: '#/',
-  perps: '#/perps-home',
-};
+import {
+  dataTestId,
+  normalizeMarketSymbol,
+  runAdapter,
+  withExtensionPage,
+} from '../platform/cdp.mjs';
+
+const BACK_CONTROLS = [
+  'perps-order-entry-back-button',
+  'perps-market-detail-back-button',
+  'perps-activity-back-button',
+  'perps-withdraw-back-button',
+  'back-button',
+].map(dataTestId);
 
 function text(value) {
   return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
 
-function pageHash(node) {
+function pageIntent(node) {
   const page = text(node?.page);
   if (!page) return undefined;
-  if (PAGE_HASHES[page]) return { page, hash: PAGE_HASHES[page] };
+  if (page === 'home' || page === 'perps') return { page };
   if (page === 'perps-market') {
     const market = text(node.market) ?? text(node.symbol);
     if (!market) throw new Error('extension ui.navigate page=perps-market requires market or symbol.');
-    return { page, hash: `#/perps/market/${encodeURIComponent(market)}` };
+    return { page, market };
   }
-  throw new Error('extension ui.navigate supported page aliases: home, perps, perps-market.');
+  throw new Error('extension ui.navigate supported page intents: home, perps, perps-market.');
+}
+
+async function hasVisibleSelector(page, selector) {
+  return page.evaluate(`(() => {
+    const element = document.querySelector(${JSON.stringify(selector)});
+    if (!element) return false;
+    const style = getComputedStyle(element);
+    const rect = element.getBoundingClientRect();
+    return style.display !== 'none' && style.visibility !== 'hidden' && rect.width > 0 && rect.height > 0;
+  })()`);
+}
+
+async function pauseForUi(page) {
+  await page.evaluate('new Promise((resolve) => setTimeout(resolve, 200))');
 }
 
-runAdapter((input) => withExtensionPage(input, async (page) => {
-  const alias = pageHash(input.node);
-  if (alias) {
-    const navigation = await page.navigateHash(alias.hash);
-    return { action: input.action, ...alias, navigation, proofPath: 'ui-navigation' };
+async function waitForFirstVisible(page, selectors, deadline) {
+  while (Date.now() < deadline) {
+    for (const selector of selectors) {
+      if (await hasVisibleSelector(page, selector)) return selector;
+    }
+    await pauseForUi(page);
+  }
+  return undefined;
+}
+
+async function currentHref(page) {
+  return page.evaluate('location.href');
+}
+
+async function activateSemanticControl(page, selector) {
+  return {
+    activation: 'trusted-pointer',
+    interaction: await page.click(selector),
+  };
+}
+
+export async function openHome(page, timeoutMs) {
+  const home = dataTestId('bottom-nav-home');
+  const selectedHome = `${home}[aria-current="page"]`;
+  const deadline = Date.now() + timeoutMs;
+  const steps = [];
+  let pendingActivation;
+
+  while (Date.now() < deadline) {
+    if (await hasVisibleSelector(page, selectedHome)) {
+      return { method: 'visible-ui', href: await currentHref(page), steps };
+    }
+    const href = await currentHref(page);
+    if (pendingActivation && pendingActivation.href !== href) {
+      pendingActivation = undefined;
+      await pauseForUi(page);
+      continue;
+    }
+    if (await hasVisibleSelector(page, home)) {
+      if (pendingActivation?.selector !== home) pendingActivation = undefined;
+      if (!pendingActivation) {
+        await activateSemanticControl(page, home);
+        steps.push(home);
+        pendingActivation = { selector: home, href };
+      }
+      await pauseForUi(page);
+      continue;
+    }
+    let backControl;
+    for (const selector of BACK_CONTROLS) {
+      if (await hasVisibleSelector(page, selector)) {
+        backControl = selector;
+        break;
+      }
+    }
+    if (backControl) {
+      if (pendingActivation?.selector !== backControl) pendingActivation = undefined;
+      if (!pendingActivation || pendingActivation.selector !== backControl) {
+        await activateSemanticControl(page, backControl);
+        steps.push(backControl);
+        pendingActivation = { selector: backControl, href };
+      }
+    }
+    await pauseForUi(page);
+  }
+
+  throw new Error(
+    `extension ui.navigate page=home could not resolve Home through visible controls; observed href ${JSON.stringify(await currentHref(page))}.`,
+  );
+}
+
+export async function openPerpsHome(page, timeoutMs) {
+  const bottomNav = dataTestId('bottom-nav-perps');
+  const legacyTab = dataTestId('account-overview__perps-tab');
+  const perpsHome = dataTestId('perps-home-page');
+  const steps = [];
+  const deadline = Date.now() + timeoutMs;
+  let pendingActivation;
+  let perpsActivation;
+
+  while (Date.now() < deadline) {
+    if (await hasVisibleSelector(page, perpsHome)) {
+      return {
+        ...(perpsActivation ? { navigation: perpsActivation, selector: bottomNav } : {}),
+        method: 'visible-ui',
+        href: await currentHref(page),
+        steps,
+      };
+    }
+    if (await hasVisibleSelector(page, bottomNav)) {
+      if (!perpsActivation) {
+        perpsActivation = await activateSemanticControl(page, bottomNav);
+        steps.push(bottomNav);
+      }
+      await pauseForUi(page);
+      continue;
+    }
+    if (await hasVisibleSelector(page, legacyTab)) {
+      const navigation = await activateSemanticControl(page, legacyTab);
+      await page.waitForSelector(dataTestId('perps-view'), {
+        timeoutMs: Math.max(1, deadline - Date.now()),
+      });
+      return {
+        navigation,
+        method: 'visible-ui',
+        href: await currentHref(page),
+        selector: legacyTab,
+        steps,
+      };
+    }
+
+    let backControl;
+    for (const selector of BACK_CONTROLS) {
+      if (await hasVisibleSelector(page, selector)) {
+        backControl = selector;
+        break;
+      }
+    }
+    if (backControl) {
+      const href = await currentHref(page);
+      if (pendingActivation && pendingActivation.href !== href) {
+        pendingActivation = undefined;
+      }
+      if (!pendingActivation || pendingActivation.selector !== backControl) {
+        await activateSemanticControl(page, backControl);
+        steps.push(backControl);
+        pendingActivation = { selector: backControl, href };
+      }
+    }
+    await pauseForUi(page);
+  }
+
+  const state = await page.evaluate(`({
+    href: location.href,
+    title: document.title,
+    visibleTestIds: [...document.querySelectorAll('[data-testid]')]
+      .filter((element) => {
+        const style = getComputedStyle(element);
+        const rect = element.getBoundingClientRect();
+        return style.display !== 'none' && style.visibility !== 'hidden' && rect.width > 0 && rect.height > 0;
+      })
+      .map((element) => element.getAttribute('data-testid'))
+      .filter(Boolean)
+      .slice(0, 30),
+  })`);
+  throw new Error(
+    `extension ui.navigate page=perps could not resolve the Perps home through visible UI; observed ${JSON.stringify(state)}. Capture the current UI with mm-harness call ui.screenshot, then use a verified visible control or raw hash/path.`,
+  );
+}
+
+export async function openPerpsMarket(page, market, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  const home = await openPerpsHome(page, Math.max(1, deadline - Date.now()));
+  const normalizedMarket = normalizeMarketSymbol(market.trim());
+  const selectors = [
+    dataTestId(`perps-watchlist-${normalizedMarket}`),
+    dataTestId(`explore-markets-${normalizedMarket.replaceAll(':', '-')}`),
+  ];
+  const marketControl = await waitForFirstVisible(page, selectors, deadline);
+  if (!marketControl) {
+    const visibleMarketControls = await page.evaluate(`[
+      ...document.querySelectorAll('[data-testid^="perps-watchlist-"], [data-testid^="explore-markets-"]')
+    ].filter((element) => {
+      const style = getComputedStyle(element);
+      const rect = element.getBoundingClientRect();
+      return style.display !== 'none' && style.visibility !== 'hidden' && rect.width > 0 && rect.height > 0;
+    }).map((element) => element.getAttribute('data-testid')).filter(Boolean)`);
+    throw new Error(
+      `extension ui.navigate page=perps-market could not find ${JSON.stringify(normalizedMarket)} in the current visible market controls ${JSON.stringify(visibleMarketControls)}.`,
+    );
+  }
+  const navigation = await activateSemanticControl(page, marketControl);
+  await page.waitForSelector(dataTestId('perps-market-detail-page'), {
+    timeoutMs: Math.max(1, deadline - Date.now()),
+  });
+  return {
+    navigation,
+    method: 'visible-ui',
+    href: await currentHref(page),
+    selector: marketControl,
+    steps: [...home.steps, marketControl],
+  };
+}
+
+export async function navigateExtensionUi(input) {
+  return withExtensionPage(input, async (page) => {
+  const intent = pageIntent(input.node);
+  if (intent) {
+    const timeoutMs = Number(input.node?.timeout_ms ?? 20000);
+    if (intent.page === 'home') {
+      const result = await openHome(page, timeoutMs);
+      return { action: input.action, ...intent, ...result, proofPath: 'ui-navigation' };
+    }
+    if (intent.page === 'perps') {
+      const result = await openPerpsHome(page, timeoutMs);
+      return { action: input.action, ...intent, ...result, proofPath: 'ui-navigation' };
+    }
+    const result = await openPerpsMarket(page, intent.market, timeoutMs);
+    return { action: input.action, ...intent, ...result, proofPath: 'ui-navigation' };
   }
 
   const url = input.node?.url;
@@ -40,5 +258,10 @@ runAdapter((input) => withExtensionPage(input, async (page) => {
     return { action: input.action, hash, navigation, proofPath: 'ui-navigation' };
   }
 
-  throw new Error('extension ui.navigate requires page, raw extension url, hash, or path.');
-}));
+    throw new Error('extension ui.navigate requires page, raw extension url, hash, or path.');
+  });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runAdapter(navigateExtensionUi);
+}

package/library/actions/mobile/ui/navigate.mjs

@@ -18,7 +18,7 @@ function pageRoute(node) {
     if (!market) throw new Error('mobile ui.navigate page=perps-market requires market or symbol.');
     return { page, route: 'PerpsMarketDetails', params: { market: { symbol: market } } };
   }
-  throw new Error('mobile ui.navigate supported page aliases: home, perps, perps-market.');
+  throw new Error('mobile ui.navigate supported page intents: home, perps, perps-market.');
 }
 
 runAdapter(async (input) => {

package/library/manifests/core.action-manifest.json

@@ -838,7 +838,7 @@
               "long",
               "short"
             ],
-            "description": "Order direction (default: long)."
+            "description": "Required order direction."
           },
           "order_type": {
             "type": "string",
@@ -857,11 +857,17 @@
             "description": "Resting limit price as a percent offset from live mid for limit orders (e.g. -30 = 30%% below mid for a non-filling BUY; default -30 buy / +30 sell). Alias: offsetPct."
           },
           "amount": {
-            "type": "string",
+            "type": [
+              "string",
+              "number"
+            ],
             "description": "USD notional alias."
           },
           "notional": {
-            "type": "string",
+            "type": [
+              "string",
+              "number"
+            ],
             "description": "USD notional alias."
           },
           "leverage": {
@@ -1233,7 +1239,7 @@
               "long",
               "short"
             ],
-            "description": "Order/position direction (default: long when placing)."
+            "description": "Required when state=open/present; otherwise filters selected positions."
           },
           "state": {
             "type": "string",
@@ -1247,11 +1253,17 @@
             "description": "Desired selected position state to converge to."
           },
           "amount": {
-            "type": "string",
+            "type": [
+              "string",
+              "number"
+            ],
             "description": "USD notional alias (used when placing to reach state open)."
           },
           "notional": {
-            "type": "string",
+            "type": [
+              "string",
+              "number"
+            ],
             "description": "USD notional alias."
           },
           "leverage": {
@@ -1279,6 +1291,17 @@
             "market": "BTC",
             "intent": "Converge Perps positions to the requested state via the headless controller"
           }
+        },
+        {
+          "description": "Ensure one ETH long position exists",
+          "node": {
+            "action": "metamask.perps.ensure_positions",
+            "market": "ETH",
+            "side": "long",
+            "state": "open",
+            "notional": "10",
+            "intent": "Converge ETH positions to one explicit testnet precondition"
+          }
         }
       ],
       "proof_effect": "E2E validation must record this action in trace.json; live-proof actions include liveAdapter/proofPath or controller output.",
@@ -1610,11 +1633,29 @@
               "long",
               "short"
             ],
-            "description": "Optional position/order side filter."
+            "description": "Required when state=open/present; otherwise filters selected orders."
           },
           "timeout_ms": {
             "type": "number"
           },
+          "amount": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "Explicit USD notional used only when creating a missing open order. Alias: notional."
+          },
+          "notional": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "Alias for amount."
+          },
+          "leverage": {
+            "type": "number",
+            "description": "Leverage used only when creating a missing open order."
+          },
           "state": {
             "type": "string",
             "enum": [
@@ -1641,6 +1682,18 @@
             "mode": "all",
             "intent": "Converge Perps orders to the requested state"
           }
+        },
+        {
+          "description": "Ensure one resting ETH short order exists",
+          "node": {
+            "action": "metamask.perps.ensure_orders",
+            "market": "ETH",
+            "side": "short",
+            "state": "open",
+            "notional": "10",
+            "leverage": 2,
+            "intent": "Converge ETH open orders to one explicit testnet precondition"
+          }
         }
       ],
       "proof_effect": "E2E validation must record this action in trace.json; live-proof actions include liveAdapter/proofPath or target runtime output.",

package/library/manifests/extension.action-manifest.json

@@ -220,7 +220,7 @@
       ]
     },
     "ui.navigate": {
-      "description": "Navigate with either raw extension url/hash/path or a small stable page alias. Discover supported aliases here before hardcoding routes.",
+      "description": "Navigate by semantic page intent when available; the adapter uses the current visible UI or a verified route. Raw url/hash/path values must be verified against the current app first.",
       "schema": {
         "type": "object",
         "properties": {
@@ -257,14 +257,16 @@
             "type": "object"
           },
           "timeout_ms": {
-            "type": "number"
+            "type": "number",
+            "default": 20000,
+            "description": "Maximum time to discover and verify the requested page intent."
           }
         },
         "additionalProperties": false
       },
       "examples": [
         {
-          "description": "Open Perps through the stable alias",
+          "description": "Ask the adapter to discover and open the current Perps entry point",
           "node": {
             "action": "ui.navigate",
             "page": "perps",
@@ -272,7 +274,7 @@
           }
         },
         {
-          "description": "Open a Perps market through the stable alias",
+          "description": "Open a Perps market through the current verified adapter path",
           "node": {
             "action": "ui.navigate",
             "page": "perps-market",
@@ -281,7 +283,7 @@
           }
         },
         {
-          "description": "Fallback to a raw extension hash when no alias exists",
+          "description": "Use a raw extension hash only after verifying it in the current app",
           "node": {
             "action": "ui.navigate",
             "hash": "#/perps-home",
@@ -1606,17 +1608,23 @@
               "long",
               "short"
             ],
-            "description": "Optional position/order side filter."
+            "description": "Required order direction."
           },
           "timeout_ms": {
             "type": "number"
           },
           "amount": {
-            "type": "string",
+            "type": [
+              "string",
+              "number"
+            ],
             "description": "USD amount/notional alias."
           },
           "notional": {
-            "type": "string",
+            "type": [
+              "string",
+              "number"
+            ],
             "description": "USD notional alias."
           },
           "size": {
@@ -1967,11 +1975,25 @@
               "long",
               "short"
             ],
-            "description": "Optional position/order side filter."
+            "description": "Required when state=open/present; otherwise filters selected positions."
           },
           "timeout_ms": {
             "type": "number"
           },
+          "amount": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "Explicit USD notional used only when creating a missing open position. Alias: notional."
+          },
+          "notional": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "Alias for amount."
+          },
           "state": {
             "type": "string",
             "enum": [
@@ -2007,6 +2029,17 @@
             "mode": "all",
             "intent": "Converge Perps positions to the requested state"
           }
+        },
+        {
+          "description": "Ensure one ETH long position exists",
+          "node": {
+            "action": "metamask.perps.ensure_positions",
+            "market": "ETH",
+            "side": "long",
+            "state": "open",
+            "notional": "10",
+            "intent": "Converge ETH positions to one explicit testnet precondition"
+          }
         }
       ],
       "proof_effect": "E2E validation must record this action in trace.json; live-proof actions include liveAdapter/proofPath or target runtime output.",
@@ -2097,15 +2130,24 @@
               "long",
               "short"
             ],
-            "description": "Optional position/order side filter."
+            "description": "Required when state=open/present; otherwise filters selected orders."
           },
           "timeout_ms": {
             "type": "number"
           },
+          "amount": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "Explicit USD notional used only when creating a missing open order. Alias: notional."
+          },
           "notional": {
-            "type": "number",
-            "default": 10,
-            "description": "Small testnet USD notional used only when creating a missing open order."
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "Alias for amount."
           },
           "leverage": {
             "type": "number",