@deeeed/metamask-harness 0.34.1 → 0.34.3

package/library/recipes/core/perps/snapshot.recipe.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
+  "title": "MetaMask core Perps snapshots",
+  "description": "Reads global market and account snapshots through the public PerpsController API used by wallet clients. Configure CORE_PERPS_TERMINAL_GLOBAL_SNAPSHOT_URL to exercise a Terminal schema-v2 endpoint.",
+  "workflow": {
+    "entry": "status",
+    "nodes": {
+      "status": {
+        "action": "app.status",
+        "next": "read_snapshot",
+        "intent": "Resolve the Core checkout and report headless compatibility"
+      },
+      "read_snapshot": {
+        "action": "metamask.perps.read_snapshot",
+        "scope": "all",
+        "next": "done",
+        "intent": "Read coherent market and account snapshots through public controller methods"
+      },
+      "done": {
+        "action": "end",
+        "status": "pass"
+      }
+    }
+  }
+}

package/library/recipes/extension/performance/navigation-memory.recipe.json

@@ -0,0 +1,175 @@
+{
+  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
+  "title": "Extension navigation retained-memory audit",
+  "description": "Measures post-GC retained nodes and listeners across eight representative Extension screens, verifies detached DOM does not grow, and separates navigation-attributable listener growth from an equal-duration idle control.",
+  "proofTargets": [
+    {
+      "id": "screen-slopes",
+      "claim": "Eight representative Extension screens remain within separate post-GC retained-node and listener growth bounds during navigation churn."
+    },
+    {
+      "id": "detached-dom",
+      "claim": "Detached DOM retained after forced garbage collection does not grow beyond the declared bound."
+    },
+    {
+      "id": "idle-control",
+      "claim": "Navigation-attributable listener growth remains within its declared bound after subtracting an equal-duration idle control."
+    }
+  ],
+  "workflow": {
+    "entry": "require-cdp",
+    "nodes": {
+      "require-cdp": {
+        "action": "cdp.target",
+        "required": true,
+        "require_reachable": true,
+        "intent": "Confirm the live Extension CDP target is reachable before measuring retained memory.",
+        "next": "ensure-unlocked"
+      },
+      "ensure-unlocked": {
+        "action": "metamask.wallet.ensure_unlocked",
+        "intent": "Ensure the representative screens are reachable from an unlocked wallet.",
+        "next": "market-detail"
+      },
+      "market-detail": {
+        "action": "metamask.performance.measure_navigation_memory",
+        "screen_hash": "#/perps/market/ETH",
+        "screen_test_id": "perps-market-detail-page",
+        "return_hash": "#/",
+        "cycles": 8,
+        "timeout_ms": 400000,
+        "max_nodes_per_cycle": 2,
+        "max_listeners_per_cycle": 4,
+        "intent": "Measure the post-GC navigation slope for Perps market detail.",
+        "proves": ["screen-slopes"],
+        "next": "order-entry"
+      },
+      "order-entry": {
+        "action": "metamask.performance.measure_navigation_memory",
+        "screen_hash": "#/perps/trade/ETH?direction=long&mode=new",
+        "screen_test_id": "perps-order-entry-page",
+        "return_hash": "#/",
+        "cycles": 6,
+        "timeout_ms": 400000,
+        "max_nodes_per_cycle": 2,
+        "max_listeners_per_cycle": 4,
+        "intent": "Measure the post-GC navigation slope for Perps order entry.",
+        "proves": ["screen-slopes"],
+        "next": "perps-home"
+      },
+      "perps-home": {
+        "action": "metamask.performance.measure_navigation_memory",
+        "screen_hash": "#/perps-home",
+        "screen_test_id": "perps-home-page",
+        "return_hash": "#/",
+        "cycles": 6,
+        "timeout_ms": 400000,
+        "max_nodes_per_cycle": 2,
+        "max_listeners_per_cycle": 4,
+        "intent": "Measure the post-GC navigation slope for Perps home.",
+        "proves": ["screen-slopes"],
+        "next": "market-list"
+      },
+      "market-list": {
+        "action": "metamask.performance.measure_navigation_memory",
+        "screen_hash": "#/perps/market-list",
+        "screen_test_id": "market-list-view",
+        "return_hash": "#/",
+        "cycles": 6,
+        "timeout_ms": 400000,
+        "max_nodes_per_cycle": 2,
+        "max_listeners_per_cycle": 4,
+        "intent": "Measure the post-GC navigation slope for the Perps market list.",
+        "proves": ["screen-slopes"],
+        "next": "perps-activity"
+      },
+      "perps-activity": {
+        "action": "metamask.performance.measure_navigation_memory",
+        "screen_hash": "#/perps/activity",
+        "screen_test_id": "perps-activity-page",
+        "return_hash": "#/",
+        "cycles": 6,
+        "timeout_ms": 400000,
+        "max_nodes_per_cycle": 2,
+        "max_listeners_per_cycle": 4,
+        "intent": "Measure the post-GC navigation slope for Perps activity.",
+        "proves": ["screen-slopes"],
+        "next": "asset-details"
+      },
+      "asset-details": {
+        "action": "metamask.performance.measure_navigation_memory",
+        "screen_hash": "#/asset/0x1/",
+        "screen_test_id": "asset-price-chart",
+        "return_hash": "#/",
+        "cycles": 6,
+        "timeout_ms": 400000,
+        "max_nodes_per_cycle": 2,
+        "max_listeners_per_cycle": 4,
+        "intent": "Measure the post-GC navigation slope for asset details.",
+        "proves": ["screen-slopes"],
+        "next": "swaps-bridge"
+      },
+      "swaps-bridge": {
+        "action": "metamask.performance.measure_navigation_memory",
+        "screen_hash": "#/cross-chain/swaps/prepare-bridge-page",
+        "screen_test_id": "bridge-source-button",
+        "return_hash": "#/",
+        "cycles": 6,
+        "timeout_ms": 400000,
+        "max_nodes_per_cycle": 2,
+        "max_listeners_per_cycle": 4,
+        "intent": "Measure the post-GC navigation slope for Swaps and Bridge.",
+        "proves": ["screen-slopes"],
+        "next": "settings-control"
+      },
+      "settings-control": {
+        "action": "metamask.performance.measure_navigation_memory",
+        "screen_hash": "#/settings",
+        "screen_test_id": "settings-tab-bar-grouped",
+        "return_hash": "#/",
+        "cycles": 6,
+        "timeout_ms": 400000,
+        "max_nodes_per_cycle": 2,
+        "max_listeners_per_cycle": 4,
+        "intent": "Measure a non-Perps control screen with the same retained-memory gate.",
+        "proves": ["screen-slopes"],
+        "next": "detached-market-detail"
+      },
+      "detached-market-detail": {
+        "action": "metamask.performance.measure_detached_dom",
+        "screen_hash": "#/perps/market/ETH",
+        "screen_test_id": "perps-market-detail-page",
+        "return_hash": "#/",
+        "cycles": 5,
+        "timeout_ms": 400000,
+        "max_detached_growth": 50,
+        "intent": "Compare retained detached DOM before and after market-detail navigation churn.",
+        "proves": ["detached-dom"],
+        "next": "idle-control-market-detail"
+      },
+      "idle-control-market-detail": {
+        "action": "metamask.performance.compare_idle_navigation_memory",
+        "screen_hash": "#/perps/market/ETH",
+        "screen_test_id": "perps-market-detail-page",
+        "return_hash": "#/",
+        "rounds": 8,
+        "round_duration_ms": 10000,
+        "timeout_ms": 400000,
+        "max_attributable_listeners_per_cycle": 2,
+        "intent": "Subtract equal-duration idle growth from the market-detail navigation slope.",
+        "proves": ["idle-control"],
+        "next": "return-home"
+      },
+      "return-home": {
+        "action": "ui.navigate",
+        "page": "home",
+        "intent": "Leave the Extension on a known screen after the audit.",
+        "next": "done"
+      },
+      "done": {
+        "action": "end",
+        "status": "pass"
+      }
+    }
+  }
+}

package/library/recipes/mobile/perps/performance.homepage.cold-position-sample.recipe.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
+  "title": "Homepage Perps cold no-cache position sample",
+  "description": "Clears only persisted Perps performance caches, reproduces a process-cold Homepage position, and measures production-like Perps timing from the first usable Wallet Home frame with the device performance clock. Metro, splash, bridge readiness, unlock, and recipe orchestration are excluded from the Perps metric.",
+  "paramsSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "account": {
+        "type": "string",
+        "description": "Existing fixture account that owns the position."
+      },
+      "market": {
+        "type": "string",
+        "default": "BTC",
+        "description": "Exact visible position market symbol."
+      },
+      "sample_id": {
+        "type": "string",
+        "default": "sample",
+        "description": "Artifact-local sample identifier."
+      },
+      "snapshot_port": {
+        "type": "number",
+        "default": 3000,
+        "description": "Host port for the explicitly configured local Terminal global snapshot endpoint."
+      }
+    },
+    "required": ["account"]
+  },
+  "workflow": {
+    "entry": "ensure-wallet",
+    "nodes": {
+      "ensure-wallet": {
+        "action": "metamask.wallet.ensure_unlocked",
+        "target_timeout_ms": 90000,
+        "unlock_timeout_ms": 180000,
+        "intent": "Reuse the existing unlocked fixture wallet without replacing it",
+        "next": "select-account"
+      },
+      "select-account": {
+        "action": "metamask.wallet.select_account",
+        "name": "{{params.account}}",
+        "cdp_timeout_ms": 30000,
+        "intent": "Pin the device-owned fixture account before the measured cold restart",
+        "next": "assert-position"
+      },
+      "assert-position": {
+        "action": "metamask.perps.assert_positions",
+        "market": "{{params.market}}",
+        "state": "open",
+        "timeout_ms": 30000,
+        "intent": "Prove the real position exists before process termination",
+        "next": "open-wallet-home"
+      },
+      "open-wallet-home": {
+        "action": "ui.navigate",
+        "page": "home",
+        "timeout_ms": 30000,
+        "intent": "Persist Wallet Home as the route restored by the cold launch",
+        "next": "clear-perps-caches"
+      },
+      "clear-perps-caches": {
+        "action": "metamask.perps.clear_performance_caches",
+        "intent": "Remove only persisted Perps market and user snapshots before the measured cold launch",
+        "next": "prepare-local-snapshot-endpoint"
+      },
+      "prepare-local-snapshot-endpoint": {
+        "action": "metamask.perps.prepare_local_snapshot_endpoint",
+        "port": "{{params.snapshot_port}}",
+        "intent": "Make the configured local Terminal v2 endpoint reachable on physical Android without an external command node",
+        "next": "cold-restart"
+      },
+      "cold-restart": {
+        "action": "app.lifecycle",
+        "command": "restart",
+        "settle_ms": 0,
+        "runtime_ready_timeout_ms": 90000,
+        "timeout_ms": 120000,
+        "intent": "Create a process-cold app state without rebuilding or resetting wallet state; this node is setup and is not part of the Perps metric",
+        "next": "measure-visible-perps"
+      },
+      "measure-visible-perps": {
+        "action": "metamask.perps.measure_homepage_visible",
+        "target_timeout_ms": 90000,
+        "unlock_timeout_ms": 180000,
+        "scroll_test_id": "wallet-screen",
+        "from_test_id": "wallet-screen",
+        "offset": 600,
+        "poll_interval_ms": 1000,
+        "visible_event_stage": "first_visible_recorded",
+        "visible_event_grace_ms": 1500,
+        "animated": true,
+        "target_test_id": "homepage-section-title-perps",
+        "required_present_test_id": "perps-position-row-{{params.market}}",
+        "timeout_ms": 30000,
+        "intent": "Confirm the restored wallet is usable and immediately measure the direct-CDP transition to visible Perps position content without returning control to the recipe runner",
+        "next": "wait-position"
+      },
+      "wait-position": {
+        "action": "ui.wait_for",
+        "test_id": "perps-position-row-{{params.market}}",
+        "expected": "present",
+        "timeout_ms": 60000,
+        "intent": "Prove the real market position row remains rendered after the measured Perps transition",
+        "next": "capture-position"
+      },
+      "capture-position": {
+        "action": "ui.screenshot",
+        "path": "screenshots/cold-position-{{params.sample_id}}.png",
+        "intent": "Preserve native proof that meaningful Perps content is visibly rendered after the fixed viewport demand",
+        "next": "done"
+      },
+      "done": {
+        "action": "end",
+        "status": "pass"
+      }
+    }
+  }
+}

package/library/recipes/mobile/perps/performance.homepage.ios-background-reconnect.recipe.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
   "title": "iOS Homepage Perps long-background reconnect proof",
-  "description": "Keeps the existing no-order simulator fixture, backgrounds longer than the connection grace period, then validates resident-to-fresh trending content at the visible Homepage endpoint.",
+  "description": "Keeps the existing simulator wallet and position, backgrounds longer than the connection grace period, then validates resident-to-fresh position content at the visible Homepage endpoint.",
   "workflow": {
     "entry": "ensure-wallet",
     "nodes": {
@@ -19,7 +19,7 @@
       },
       "wait-perps-before": {
         "action": "ui.wait_for",
-        "test_id": "homepage-section-title-perps",
+        "test_id": "homepage-perps-positions",
         "expected": "present",
         "intent": "Require the Perps section before backgrounding",
         "timeout_ms": 30000,
@@ -27,7 +27,7 @@
       },
       "show-perps-before": {
         "action": "ui.scroll",
-        "test_id": "homepage-section-title-perps",
+        "test_id": "homepage-perps-positions",
         "scroll_into_view": true,
         "animated": true,
         "settle": true,
@@ -53,12 +53,13 @@
         "command": "foreground",
         "settle_ms": 10000,
         "runtime_ready_timeout_ms": 60000,
+        "require_process_continuity": true,
         "intent": "Restore the same process and require a reconnect",
         "next": "wait-perps-after"
       },
       "wait-perps-after": {
         "action": "ui.wait_for",
-        "test_id": "homepage-section-title-perps",
+        "test_id": "homepage-perps-positions",
         "expected": "present",
         "intent": "Confirm the Perps section remains available after reconnect",
         "timeout_ms": 30000,
@@ -66,7 +67,7 @@
       },
       "show-perps-after": {
         "action": "ui.scroll",
-        "test_id": "homepage-section-title-perps",
+        "test_id": "homepage-perps-positions",
         "scroll_into_view": true,
         "animated": true,
         "settle": true,
@@ -97,7 +98,7 @@
         ],
         "required_lifecycles": ["background_reconnect"],
         "required_sources": ["resident_state", "fresh_socket"],
-        "required_fresh_content_variants": ["trending"],
+        "required_fresh_content_variants": ["positions"],
         "intent": "Require the long-background visible reconnect cohort",
         "next": "done"
       },

package/library/recipes/mobile/perps/performance.homepage.ios-cold-no-cache.recipe.json

@@ -43,15 +43,15 @@
       },
       "wait-perps-section": {
         "action": "ui.wait_for",
-        "test_id": "homepage-section-title-perps",
+        "test_id": "homepage-perps-positions",
         "expected": "present",
-        "intent": "Require the Perps section after cold launch",
+        "intent": "Require the selected account's Perps position after cold launch",
         "timeout_ms": 30000,
         "next": "show-perps-section"
       },
       "show-perps-section": {
         "action": "ui.scroll",
-        "test_id": "homepage-section-title-perps",
+        "test_id": "homepage-perps-positions",
         "scroll_into_view": true,
         "animated": true,
         "settle": true,
@@ -82,8 +82,8 @@
         ],
         "required_lifecycles": ["cold_no_cache"],
         "required_sources": ["fresh_socket"],
-        "required_fresh_content_variants": ["trending"],
-        "intent": "Require cold-no-cache lifecycle and fresh visible trending content",
+        "required_fresh_content_variants": ["positions"],
+        "intent": "Require cold-no-cache lifecycle and the fresh visible position",
         "next": "done"
       },
       "done": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.34.1",
+  "version": "0.34.3",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"

package/scripts/site-contrast.mjs

@@ -351,11 +351,33 @@ async function checkBehavior(browserEndpoint, port, pages) {
         return window.__siteCopied;
       })()
     `);
-    const expected = 'mm-harness run <recipe> --artifacts-dir ./first-recipe-artifacts';
-    if (!copied?.includes(expected)) {
-      throw new Error(`copy prompt omitted "${expected}"`);
+    // Both halves of the onboarding have to survive a copy: set up the harness
+    // and the skills, then drive real work through one.
+    const expected = ['npm i -g @deeeed/metamask-harness@latest', 'yarn skills', '/mms-recipe-cook'];
+    const missing = expected.filter((line) => !copied?.includes(line));
+    if (missing.length) {
+      throw new Error(`copy prompt omitted ${missing.map((m) => `"${m}"`).join(', ')}`);
     }
 
+    // The landing page is the lobby: one prompt, one way onward, nothing else.
+    const lobby = await page.evaluate(String.raw`
+      (() => ({
+        nav: document.querySelectorAll('.nav a').length,
+        steps: document.querySelectorAll('.step[data-step]').length,
+        depth: document.querySelector('a[href="how-it-works.html"]') !== null,
+        anchor: document.getElementById('prompt') !== null,
+      }))()
+    `);
+    if (lobby.nav || lobby.steps || !lobby.depth || !lobby.anchor) {
+      throw new Error(
+        `landing page is not a lobby: ${lobby.nav} nav links, ${lobby.steps} steps, ` +
+          `depth link ${lobby.depth}, prompt anchor ${lobby.anchor}`,
+      );
+    }
+  });
+
+  // The walkthrough and its saved progress live one click deeper.
+  await withPage(browserEndpoint, `${base}how-it-works.html`, async (page) => {
     const progress = await page.evaluate(String.raw`
       (() => {
         const box = document.querySelector('.step-check');
@@ -426,6 +448,20 @@ async function checkBehavior(browserEndpoint, port, pages) {
       if (broken.length) {
         throw new Error(`${relative} has broken internal links: ${broken.join(', ')}`);
       }
+      // Every page past the lobby owes the reader one click back to the prompt.
+      if (relative !== 'index.html') {
+        const back = await page.evaluate(String.raw`
+          (() => {
+            const link = document.querySelector('.nav a.nav-cta');
+            if (!link) return null;
+            const url = new URL(link.getAttribute('href'), location.href);
+            return url.pathname + url.hash;
+          })()
+        `);
+        if (back !== '/index.html#prompt') {
+          throw new Error(`${relative} has no nav link back to the setup prompt (found ${back})`);
+        }
+      }
       for (const width of [834, 390]) {
         await page.send('Emulation.setDeviceMetricsOverride', {
           width,

package/site/architecture.html

@@ -14,11 +14,12 @@
   <div class="wrap topbar-inner">
     <a class="brand" href="index.html">
       <span class="brand-mark" aria-hidden="true"></span>
-      <span class="brand-name">mm-harness</span>
+      <span class="brand-name">recipes</span>
     </a>
     <nav class="nav" aria-label="Main">
-      <a href="index.html">Start Here</a>
-      <a href="recipes.html">Recipes</a>
+      <a class="nav-cta" href="index.html#prompt">Quick start</a>
+      <a href="how-it-works.html">How it works</a>
+      <a href="recipes.html">Recipe anatomy</a>
       <a href="perps.html">Perps</a>
       <a href="cheatsheet.html">Cheatsheet</a>
       <a href="architecture.html" aria-current="page">Architecture</a>
@@ -30,11 +31,12 @@
 
 <main>
 <section class="wrap hero" style="padding-bottom:1rem">
-  <span class="eyebrow">The stack</span>
+  <span class="eyebrow">The stack behind a recipe</span>
   <h1>How the pieces fit together</h1>
   <p class="lede">
-    Four moving parts, two of which people routinely confuse. What each layer is, where it lives, which
-    workflow you are in, and the mistakes that cost newcomers their first afternoon.
+    The recipe is the unit of trust; the rest of the stack runs it. Four moving parts, two of which
+    people routinely confuse. What each layer is, where it lives, which workflow you are in, and the
+    mistakes that cost newcomers their first afternoon.
   </p>
 </section>
 
@@ -45,8 +47,9 @@
       <span class="k">A recipe proves a task with actions.</span> Recipes are JSON graphs of typed
       actions; <code>mm-harness</code> executes them against a real app and produces an evidence bundle
       a reviewer can trust. <strong>Skills</strong> teach an agent a workflow — author a recipe, review
-      a PR, validate a release. <strong>Recipe libraries</strong> hold each team's recipes and domain
-      actions. Compose in that order, against the product repo under test.
+      a PR, validate a release — and are the layer you work through; they call the harness, which runs
+      the recipe. <strong>Recipe libraries</strong> hold each team's recipes and domain actions.
+      Compose in that order, against the product repo under test.
     </p>
   </div>
 </section>
@@ -67,9 +70,12 @@
         release — turning "figure it out" into a procedure with gates you can steer.
       </p>
       <p>
-        Skills live in the internal <code>Consensys/skills</code> repo, installed per checkout with that
-        repo's tooling. <strong>You do not need skills to run a recipe</strong>, only to have an agent
-        follow a proven workflow instead of improvising one.
+        Skills come from the public <code>MetaMask/skills</code> repo plus the internal
+        <code>Consensys/skills</code> overlay, which needs access to that org; private skills override
+        public ones on a name collision. Clone each, point <code>METAMASK_SKILLS_DIR</code> and
+        <code>CONSENSYS_SKILLS_DIR</code> at them, then install per checkout with
+        <code>yarn skills</code>. <strong>You do not need skills to run a recipe</strong>, only to have
+        an agent follow a proven workflow instead of improvising one.
         <a href="tutorials/v3.html">V3 walks the install.</a>
       </p>
     </div>
@@ -129,8 +135,8 @@
       </p>
       <p style="margin-bottom:0">
         They differ, and the harness says so rather than pretending otherwise: Core is headless with
-        nothing to launch and no UI actions; Mobile carries video capture; Extension is screenshots
-        only.
+        nothing to launch and no UI actions; Extension and iOS can record full-run video; Android
+        replay video is not implemented yet, so use screenshot evidence there.
       </p>
     </div>
   </div>
@@ -466,7 +472,7 @@
 
   <hr class="sep">
   <div class="btn-row">
-    <a class="btn btn-primary" href="index.html#steps">Do the walkthrough →</a>
+    <a class="btn btn-primary" href="how-it-works.html#steps">Do the walkthrough →</a>
     <a class="btn btn-ghost" href="reviewers.html">Read an evidence bundle</a>
   </div>
 </section>
@@ -474,8 +480,8 @@
 
 <footer class="footer">
   <div class="wrap">
-    <p>Internal getting-started guide for the MetaMask agentic coding workflow. Not official MetaMask product documentation.</p>
-    <p>Verified against mm-harness 0.33+.</p>
+    <p>Internal getting-started guide for proving MetaMask changes with recipes. Not official MetaMask product documentation.</p>
+    <p>Sample output moves between releases; trust your terminal over this page.</p>
   </div>
 </footer>
 

package/site/assets/progress.mjs

@@ -3,7 +3,7 @@
  * buttons, platform filters, and the layer diagram. No dependencies, no
  * network, no tracking. Progress lives in localStorage under
  * `mmh.progress.<page>`, where <page> comes from body[data-progress-page].
- * Pages that share a namespace share their state (Start Here and the V1
+ * Pages that share a namespace share their state (the How it works walkthrough and the V1
  * tutorial are deliberately the same checklist).
  */
 (function () {