@farmslot/adapter-web 0.17.7 → 0.19.0

package/CHANGELOG.md

@@ -6,6 +6,14 @@ All notable changes to `@farmslot/adapter-web` are tracked here.
 
 - Active-development baseline; add user-facing changes here before release or package publication.
 
+## 0.19.0 - 2026-11-06
+
+- Web-dapp wallet accounts: a mnemonic entry yields every account its `count` names (`names[]`, else dev1, dev2, ...), and `--account` selects one by name or address. A host can add named derivations of a fixture secret at a higher HD index through `RECIPE_WALLET_DERIVED_ACCOUNTS`; a declared address that does not match is refused. `browser.json` records the account's fixture secret name and index.
+
+## 0.18.0 - 2026-11-05
+
+- Run ordinary websites in an owned extension-free browser with shared CDP actions, screenshots and whole-run recording. Existing extension launches retain their lifecycle.
+
 ## 0.17.7 - 2026-11-04
 
 - Check host-resolver blocking in an owned blank document so strict application CSP needs no harness-only source. Keep application HTTP and WebSocket blocking checks unchanged.

package/README.md

@@ -108,6 +108,12 @@ const binding = createWalletRequestBinding({
 });
 ```
 
+## Plain websites
+
+`@farmslot/adapter-web/plain-web` exports `createPlainWebAdapter({ manifestPath, url, serverLabel })`. The project supplies its action catalog and a URL function using its selected ports. The runtime owns an isolated browser and reuses shared CDP actions, screenshots and whole-run recording. The project owns its application server.
+
+Browser stop is scoped to the selected checkout's profile and retains the application server. This path needs no extension, signer or wallet policy and makes no assumptions about the application framework or page selectors.
+
 ## Web-dapp adapter
 
 `@farmslot/adapter-web/web-dapp` (ESM) is the lifecycle of a web app under test whose dev server the slot owns. `createWebDappAdapter({ id, signerModule, cli, hooks })` returns an `@farmslot/adapter-sdk` `ProjectRuntime`: launch, stop, runtime status, doctor checks, logs and the wallet request-log findings. It runs one slot browser per slot, and a wallet host attached to it over CDP that records the wallet requests (and, with `signer=injected`, answers them with the strict wallet from `dapp`).

package/dist/launch-browser.d.cts

@@ -3,9 +3,9 @@ export type LaunchBrowserOptions = {
     chromeBin: string;
     profile: string;
     /**
-     * Unpacked extension to load.
+     * Unpacked extension to load; omitted for a plain web page.
      */
-    extensionDir: string;
+    extensionDir?: string | undefined;
     /**
      * Holds browser-resolution.json and the runtime identity.
      */
@@ -72,7 +72,7 @@ export type LaunchBrowserOptions = {
  * @property {number} cdpPort
  * @property {string} chromeBin
  * @property {string} profile
- * @property {string} extensionDir Unpacked extension to load.
+ * @property {string} [extensionDir] Unpacked extension to load; omitted for a plain web page.
  * @property {string} runtimeDir Holds browser-resolution.json and the runtime identity.
  * @property {string} chromeLog
  * @property {string} chromePid

package/dist/plain-web.d.mts

@@ -0,0 +1,17 @@
+/** Runtime files and the browser profile always belong to the selected checkout. */
+export function plainWebRuntimeDir(target: any): string;
+/**
+ * Use existing browser ownership, CDP actions and whole-run recording for a plain website.
+ * @param {PlainWebAdapterConfig} config
+ * @returns {import('@farmslot/adapter-sdk').ProjectRuntime}
+ */
+export function createPlainWebAdapter(config: PlainWebAdapterConfig): import("@farmslot/adapter-sdk").ProjectRuntime;
+/** Releases only the selected checkout's owned profile. The application server is retained. */
+export function stopPlainWebBrowser(target: any): {
+    stopped: boolean;
+};
+export type PlainWebAdapterConfig = {
+    manifestPath: string;
+    url: (target: string) => string;
+    serverLabel?: string;
+};

package/dist/web-dapp/index.d.mts

@@ -125,5 +125,5 @@ export { recipeHarnessPath, recipeRuntimeDir, recipeRuntimePath, shellQuote, wal
 export { assertPolicyDigest, fencePolicy, POLICY_DIGEST_ENV, PolicyFenceError } from "./lib/policy-fence.mjs";
 export { cdpListenerPids, ownedBrowserPids, OWNER_FLAG, OWNER_KINDS, ownerMarker, ownsProcess, pidAlive, portFree, stopConsoleCollector, stopWebDappBrowser, terminate } from "./lib/processes.mjs";
 export { assertLaunchNetwork, DEV_SERVER_PID_FILE, devServerTestnetDiagnostic, pythonFor, webDappReadiness } from "./lib/readiness.mjs";
-export { accountName, appOrigin, appPort, canonicalPath, cdpPort, DEFAULT_ACCOUNT, fixtureAccount, fixtureEntry, fixturePath, loadWalletFixture, readBrowserState, readJsonFile, resolveAccountAddress, resolveSigner, SIGNER_MODES, viemAccountFromEntry, webDappRuntimeDir, webDappRuntimePath, writePrivateJson } from "./lib/runtime.mjs";
+export { accountName, appOrigin, appPort, canonicalPath, cdpPort, DEFAULT_ACCOUNT, DERIVED_ACCOUNTS_ENV, fixtureAccount, fixtureEntry, fixturePath, loadWalletFixture, readBrowserState, readJsonFile, resolveAccountAddress, resolveSigner, SIGNER_MODES, viemAccountFromEntry, walletAccount, walletAccounts, webDappRuntimeDir, webDappRuntimePath, writePrivateJson } from "./lib/runtime.mjs";
 export { macosSessionLocked, parseSessionLocked, SESSION_LOCKED_MESSAGE, SESSION_LOCKED_USER_ACTION } from "./lib/session-lock.mjs";

package/dist/web-dapp/lib/runtime.d.mts

@@ -15,7 +15,28 @@ export function loadWalletFixture(projectRoot: any, env?: NodeJS.ProcessEnv): Pr
     fixture: any;
 }>;
 export function fixtureEntry(fixture: any, name: any): any;
-export function viemAccountFromEntry(entry: any, projectRoot: any): any;
+export function viemAccountFromEntry(entry: any, projectRoot: any, addressIndex?: number): any;
+export function derivedAccounts(env?: NodeJS.ProcessEnv): any[];
+/**
+ * Every account the fixture offers: each mnemonic entry expanded to its count,
+ * each private key, then the host's named derivations (DERIVED_ACCOUNTS_ENV)
+ * of the secrets this fixture holds. `account` is the viem account holding the
+ * key: sign with it, never log or persist it.
+ */
+export function walletAccounts(fixture: any, projectRoot: any, env?: NodeJS.ProcessEnv): {
+    name: any;
+    address: any;
+    secret: any;
+    index: any;
+    account: any;
+}[];
+export function walletAccount(fixture: any, selector: any, projectRoot: any, env?: NodeJS.ProcessEnv): {
+    name: any;
+    address: any;
+    secret: any;
+    index: any;
+    account: any;
+};
 export function fixtureAccount(projectRoot: any, name: any, env?: NodeJS.ProcessEnv): Promise<any>;
 export function resolveAccountAddress(input: any, env?: NodeJS.ProcessEnv): Promise<{
     name: any;
@@ -23,6 +44,7 @@ export function resolveAccountAddress(input: any, env?: NodeJS.ProcessEnv): Prom
 }>;
 export const SIGNER_MODES: readonly string[];
 export const DEFAULT_ACCOUNT: "dev1";
+export const DERIVED_ACCOUNTS_ENV: "RECIPE_WALLET_DERIVED_ACCOUNTS";
 import { POLICY_ENV } from './policy.mjs';
 import { webDappAdapterId } from './policy.mjs';
 import { webDappPolicy } from './policy.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farmslot/adapter-web",
-  "version": "0.17.7",
+  "version": "0.19.0",
   "description": "Web platform adapter for Farmslot recipes: resolve and launch an isolated Chromium, own its CDP port, load unpacked extensions, and keep macOS focus.",
   "type": "commonjs",
   "exports": {
@@ -68,6 +68,10 @@
     "./web-dapp": {
       "types": "./dist/web-dapp/index.d.mts",
       "default": "./src/web-dapp/index.mjs"
+    },
+    "./plain-web": {
+      "types": "./dist/plain-web.d.mts",
+      "default": "./src/plain-web.mjs"
     }
   },
   "scripts": {

package/src/launch-browser.cjs

@@ -67,7 +67,7 @@ const BROWSER_RESOLVER_CLI = require.resolve('./browser-resolver.cjs');
  * @property {number} cdpPort
  * @property {string} chromeBin
  * @property {string} profile
- * @property {string} extensionDir Unpacked extension to load.
+ * @property {string} [extensionDir] Unpacked extension to load; omitted for a plain web page.
  * @property {string} runtimeDir Holds browser-resolution.json and the runtime identity.
  * @property {string} chromeLog
  * @property {string} chromePid
@@ -114,7 +114,6 @@ function normalizeOptions(options) {
   const flags = {
     chromeBin: 'chrome-bin',
     profile: 'profile',
-    extensionDir: 'extension-dir',
     runtimeDir: 'runtime-dir',
     chromeLog: 'chrome-log',
     chromePid: 'chrome-pid',
@@ -122,6 +121,10 @@ function normalizeOptions(options) {
   for (const [key, flag] of Object.entries(flags)) {
     if (!opts[key]) throw new Error(`Missing --${flag}`);
   }
+  if (!opts.extensionDir && !opts.stopOnly) {
+    if (!opts.startUrl || !/^https?:$/u.test(new URL(opts.startUrl).protocol))
+      throw new Error('Plain web launch requires an explicit HTTP(S) --start-url');
+  }
   opts.log = opts.log ?? ((line) => process.stderr.write(`${line}\n`));
   opts.progress = opts.progress ?? (() => {});
   return opts;
@@ -135,7 +138,7 @@ function runLaunch(opts, acquireLock) {
   if (!opts.stopOnly) {
     if (!fs.existsSync(opts.chromeBin))
       throw new Error(`Chrome binary not found: ${opts.chromeBin}`);
-    if (!fs.existsSync(path.join(extensionDir, 'manifest.json'))) {
+    if (extensionDir && !fs.existsSync(path.join(extensionDir, 'manifest.json'))) {
       throw new Error(
         `Extension dist manifest not found: ${path.join(extensionDir, 'manifest.json')}`,
       );
@@ -189,7 +192,7 @@ function runLaunch(opts, acquireLock) {
   // run's Chrome would hold the lock and the write fails.
   if (opts.stopOnly) return { stopped: true };
   try {
-    removeExtensionWorkerRegistrations(profile);
+    if (extensionDir) removeExtensionWorkerRegistrations(profile);
   } catch (error) {
     const detail = error instanceof Error ? error.message : String(error);
     throw new Error(
@@ -221,7 +224,7 @@ function runLaunch(opts, acquireLock) {
   const initialUrl =
     opts.startUrl || extensionPageUrl(extensionDir, opts.homePage) || 'chrome://extensions/';
   const browser = launchBrowserResolution(opts.browserResolution, opts.chromeBin);
-  const loadsOverCdp = browser.extensionLoading === CDP_LOAD_UNPACKED;
+  const loadsOverCdp = Boolean(extensionDir) && browser.extensionLoading === CDP_LOAD_UNPACKED;
   let cdpLoad = null;
   let owner = null;
   const runtimeNonce = createRuntimeIdentityNonce();
@@ -238,10 +241,14 @@ function runLaunch(opts, acquireLock) {
     ...isolatedProfileArgs(),
     '--disable-default-apps',
     '--disable-popup-blocking',
-    '--disable-extensions-file-access-check',
-    '--disable-extensions-content-verification',
-    '--disable-features=ExtensionContentVerification,DisableLoadExtensionCommandLineSwitch',
-    ...extensionLaunchArgs(extensionDir, browser.extensionLoading),
+    ...(extensionDir
+      ? [
+          '--disable-extensions-file-access-check',
+          '--disable-extensions-content-verification',
+          '--disable-features=ExtensionContentVerification,DisableLoadExtensionCommandLineSwitch',
+          ...extensionLaunchArgs(extensionDir, browser.extensionLoading),
+        ]
+      : []),
   ]);
   // Initial tab: the caller's URL when provided, else the extension home. The
   // extension home avoids leaving disposable chrome://newtab/ or extensions
@@ -333,7 +340,7 @@ function runLaunch(opts, acquireLock) {
         cdpLoad = loadExtensionOverCdp(opts, browserPid, initialUrl, clearLaunchMarkers);
       else if (application) openBackgroundWindow(opts, browserPid, initialUrl, clearLaunchMarkers);
       owner = cdpLoad?.owner ?? ownerIdentity(cdpPort, profile, browserPid, log);
-      for (const problem of pruneExtraHomeTabs(cdpPort, extensionDir, opts)) {
+      for (const problem of extensionDir ? pruneExtraHomeTabs(cdpPort, extensionDir, opts) : []) {
         log(`[launch] home-tab pruning: ${problem}`);
       }
     } finally {
@@ -658,7 +665,8 @@ function processIsOwnedBrowser(pid, profile, extensionDir, extensionOwnerRoot) {
   const command = processCommand(pid);
   if (!command) return false;
   if (command.includes(`--user-data-dir=${profile}`)) return true;
-  const ownerRoot = extensionOwnerRoot ? extensionOwnerRoot(path.resolve(extensionDir)) : null;
+  const ownerRoot =
+    extensionDir && extensionOwnerRoot ? extensionOwnerRoot(path.resolve(extensionDir)) : null;
   return Boolean(ownerRoot && command.includes(`--load-extension=${ownerRoot}`));
 }
 

package/src/plain-web.mjs

@@ -0,0 +1,219 @@
+// A regular website in a slot-owned browser. The project owns its application server.
+import fs from 'node:fs';
+import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+import { CdpWebPage, listCdpTargets } from '@farmslot/recipe-runner/runtime/cdp';
+
+import { assertSameOwner, cdpOwner } from './browser-cdp.cjs';
+import { resolveBrowser } from './browser-resolver.cjs';
+import { removeRuntimeIdentity } from './chrome-args.cjs';
+import { launchBrowser } from './launch-browser.cjs';
+import { stopProfileProcessesSync } from './validation-process-ownership.cjs';
+
+/** @typedef {{
+ * manifestPath: string,
+ * url: (target: string) => string,
+ * serverLabel?: string
+ * }} PlainWebAdapterConfig
+ */
+
+function port(env = process.env) {
+  const value = Number(env.RECIPE_CDP_PORT ?? env.CDP_PORT);
+  if (!Number.isInteger(value) || value < 1 || value > 65535)
+    throw new Error('The plain web runtime requires the assigned --cdp-port.');
+  return value;
+}
+
+/** Runtime files and the browser profile always belong to the selected checkout. */
+export function plainWebRuntimeDir(target) {
+  return path.join(fs.realpathSync(target), '.agent', 'web');
+}
+
+function browserOptions(target, env = process.env) {
+  const runtimeDir = plainWebRuntimeDir(target);
+  return {
+    cdpPort: port(env),
+    runtimeDir,
+    profile: path.join(runtimeDir, 'profile'),
+    chromeLog: path.join(runtimeDir, 'browser.log'),
+    chromePid: path.join(runtimeDir, 'browser.pid'),
+  };
+}
+
+function owned(target, env = process.env) {
+  const options = browserOptions(target, env);
+  return cdpOwner(options.cdpPort, options.profile);
+}
+
+/**
+ * Use existing browser ownership, CDP actions and whole-run recording for a plain website.
+ * @param {PlainWebAdapterConfig} config
+ * @returns {import('@farmslot/adapter-sdk').ProjectRuntime}
+ */
+export function createPlainWebAdapter(config) {
+  const hint = 'Prepare the selected slot, then launch its plain web browser.';
+  async function page(target, env = process.env) {
+    const owner = owned(target, env);
+    const file = path.join(plainWebRuntimeDir(target), 'page.json');
+    const state = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const selected = (await listCdpTargets('127.0.0.1', port(env))).find(
+      (entry) => entry.id === state.pageId && entry.type === 'page',
+    );
+    assertSameOwner(owner);
+    if (!selected) throw new Error(`The owned application page is unavailable. ${hint}`);
+    return selected;
+  }
+  /** @type {import('@farmslot/adapter-sdk').ProjectRuntime} */
+  const runtime = {
+    id: 'web',
+    sdkVersion: 1,
+    headless: false,
+    targets: ['web', 'cli'],
+    resolveSlotPorts() {},
+    async runtimeStatus(target) {
+      try {
+        await page(target);
+        const response = await fetch(config.url(target), { signal: AbortSignal.timeout(5000) });
+        await response.body?.cancel();
+        if (!response.ok) throw new Error(`Application returned HTTP ${response.status}.`);
+        return {
+          decision: 'ready',
+          reasons: [],
+          devServer: { label: config.serverLabel ?? 'website', status: 'up' },
+        };
+      } catch (error) {
+        return {
+          decision: 'blocked',
+          reasons: [error instanceof Error ? error.message : String(error)],
+          nextAction: hint,
+        };
+      }
+    },
+    devServer: {
+      label: 'browser',
+      describe: () => 'The owned website browser; the application server belongs to the project',
+      stop(target) {
+        stopPlainWebBrowser(target);
+        return {
+          kind: 'stopped',
+          status: 0,
+          summary: 'Website browser stopped; application server retained.',
+        };
+      },
+    },
+    logSources: (target) => [
+      { label: 'Browser', path: path.join(plainWebRuntimeDir(target), 'browser.log') },
+    ],
+    appLogSource: () => null,
+    hints: { launch: hint, relaunch: hint, runtimeProbeRecovery: () => hint },
+    harness: {
+      kind: 'built-in',
+      verify(target) {
+        return {
+          inProcess: async () => async (_args, io) => {
+            const status = await runtime.runtimeStatus(target);
+            if (status.decision !== 'ready') {
+              io.err(status.reasons.join('; '));
+              return 1;
+            }
+            io.out('ready');
+            return 0;
+          },
+        };
+      },
+    },
+    runtimeContext: { forbiddenFields: [] },
+    readiness: { captureProviders: ['cdp'], readyIndicator: () => 'ready' },
+    recording: {
+      async target(context) {
+        const owner = owned(context.projectRoot, context.env);
+        await page(context.projectRoot, context.env);
+        assertSameOwner(owner);
+        return { kind: 'pid', pid: owner.pid };
+      },
+    },
+    async launch({ target, jsonOutput }) {
+      const url = config.url(target);
+      const parsed = new URL(url);
+      if (!['http:', 'https:'].includes(parsed.protocol))
+        throw new Error('Expected an HTTP(S) application URL.');
+      const options = browserOptions(target);
+      const resolution = await resolveBrowser({
+        env: {
+          ...process.env,
+          RECIPE_HARNESS_BROWSER: process.env.RECIPE_HARNESS_BROWSER ?? 'chrome',
+        },
+        cft: () => ({
+          error:
+            'Select installed Chrome or set RECIPE_HARNESS_CHROME_BIN to an installed Chromium executable.',
+        }),
+        cachePath: path.join(options.runtimeDir, 'browser-probe.json'),
+        launchMethod: process.platform === 'darwin' ? 'launch-services' : 'spawn',
+        display: 'headful',
+      });
+      launchBrowser({ ...options, chromeBin: resolution.bin, startUrl: url });
+      try {
+        const owner = owned(target);
+        const deadline = Date.now() + 15_000;
+        let candidates = [];
+        do {
+          candidates = (await listCdpTargets('127.0.0.1', port())).filter(
+            (entry) => entry.type === 'page' && entry.url.startsWith(`${parsed.origin}/`),
+          );
+          if (candidates.length) break;
+          await delay(100);
+        } while (Date.now() < deadline);
+        if (candidates.length !== 1)
+          throw new Error('Expected one application page in the owned browser.');
+        assertSameOwner(owner);
+        fs.writeFileSync(
+          path.join(options.runtimeDir, 'page.json'),
+          JSON.stringify({ pageId: candidates[0].id }),
+          { mode: 0o600 },
+        );
+        const status = await runtime.runtimeStatus(target);
+        if (status.decision !== 'ready') throw new Error(status.reasons.join('; '));
+      } catch (error) {
+        stopPlainWebBrowser(target);
+        throw error;
+      }
+      if (jsonOutput)
+        console.log(
+          JSON.stringify({
+            schemaVersion: 1,
+            command: 'launch',
+            status: 'pass',
+            adapter: 'web',
+            target,
+            url,
+            cdpPort: options.cdpPort,
+          }),
+        );
+      return 0;
+    },
+    actions: {
+      manifestPath: () => config.manifestPath,
+      semantic: [],
+      cdpTarget: { transport: 'cdp', probePath: '/json/version' },
+      ui: ({ createCdpWebUiTransport }) => ({
+        base: createCdpWebUiTransport({
+          getPage: async ({ context }) =>
+            CdpWebPage.connectToTarget(await page(context.projectRoot, context.env)),
+        }),
+      }),
+    },
+  };
+  return runtime;
+}
+
+/** Releases only the selected checkout's owned profile. The application server is retained. */
+export function stopPlainWebBrowser(target) {
+  const runtimeDir = plainWebRuntimeDir(target);
+  // Stop also works without active port options, including a repeated closeout.
+  stopProfileProcessesSync(path.join(runtimeDir, 'profile'));
+  removeRuntimeIdentity(runtimeDir);
+  fs.rmSync(path.join(runtimeDir, 'browser.pid'), { force: true });
+  fs.rmSync(path.join(runtimeDir, 'page.json'), { force: true });
+  return { stopped: true };
+}

package/src/web-dapp/index.mjs

@@ -90,6 +90,7 @@ export {
   canonicalPath,
   cdpPort,
   DEFAULT_ACCOUNT,
+  DERIVED_ACCOUNTS_ENV,
   fixtureAccount,
   fixtureEntry,
   fixturePath,
@@ -100,6 +101,8 @@ export {
   resolveSigner,
   SIGNER_MODES,
   viemAccountFromEntry,
+  walletAccount,
+  walletAccounts,
   webDappRuntimeDir,
   webDappRuntimePath,
   writePrivateJson,

package/src/web-dapp/launch.mjs

@@ -11,11 +11,12 @@
 //   wallet requests.
 //
 // Inputs (flags): --target <checkout> --cdp-port <port> --app-port <port>
-//   [--signer extension|injected] [--signer-module <path>] [--account <fixture name>]
+//   [--signer extension|injected] [--signer-module <path>] [--account <name|address>]
 //   [--fresh-profile] [--headless | --headful] [--slow-mo <ms>] [--start-chain <id>]
 //   [--json] [--network mainnet --mainnet-confirmation REAL_FUNDS] (testnet
 //   otherwise, enforced in the browser from the venue policy)
 //   env: TERMINAL_CHROME_BIN, RECIPE_WEB_DAPP_SIGNER_MODULE, RECIPE_WALLET_FIXTURE,
+//   RECIPE_WALLET_DERIVED_ACCOUNTS,
 //   TERMINAL_HEADLESS, TERMINAL_SLOW_MO, TERMINAL_WINDOW, TERMINAL_SCREEN
 //   (plus whatever the signer module reads)
 //   The browser is headful by default, in a window placed per slot (see
@@ -68,10 +69,9 @@ import {
 } from './lib/processes.mjs';
 import { assertLaunchNetwork, devServerTestnetDiagnostic } from './lib/readiness.mjs';
 import {
-  fixtureEntry,
   loadWalletFixture,
   resolveSigner,
-  viemAccountFromEntry,
+  walletAccount,
   webDappPolicy,
   webDappRuntimeDir,
 } from './lib/runtime.mjs';
@@ -86,7 +86,7 @@ const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const macosFocus = createRequire(import.meta.url)('../macos-focus.cjs');
 
 function usage() {
-  return 'Usage: launch.mjs --target <checkout> --cdp-port <port> --app-port <port> [--signer extension|injected] [--signer-module <path>] [--account <name>] [--fresh-profile] [--headless | --headful] [--slow-mo <ms>] [--network testnet|mainnet --mainnet-confirmation REAL_FUNDS] [--start-chain <id>] [--json]';
+  return 'Usage: launch.mjs --target <checkout> --cdp-port <port> --app-port <port> [--signer extension|injected] [--signer-module <path>] [--account <name|address>] [--fresh-profile] [--headless | --headful] [--slow-mo <ms>] [--network testnet|mainnet --mainnet-confirmation REAL_FUNDS] [--start-chain <id>] [--json]';
 }
 
 export function parseLaunchArgs(argv, env = process.env) {
@@ -490,7 +490,14 @@ export async function launchWebDappBrowser(
   }
 
   const { fixture } = await loadWalletFixture(target, env);
-  const accountAddress = viemAccountFromEntry(fixtureEntry(fixture, args.account), target).address;
+  // --account is an account name or address; the browser runs under its name.
+  const selected = walletAccount(fixture, args.account, target, env);
+  const account = {
+    name: selected.name,
+    address: selected.address,
+    secret: selected.secret,
+    index: selected.index,
+  };
 
   const previous = readStateFile(stateFile);
   const reusable =
@@ -499,7 +506,8 @@ export async function launchWebDappBrowser(
     previous.signer === signer &&
     previous.cdpPort === cdpPort &&
     previous.appOrigin === appOrigin &&
-    previous.account?.name === args.account &&
+    previous.account?.name === account.name &&
+    previous.account?.address?.toLowerCase() === account.address.toLowerCase() &&
     previous.browser?.headless === headless &&
     (previous.network ?? 'testnet') === network &&
     previous.networkEnforcement?.fingerprint === enforcementFingerprint &&
@@ -507,7 +515,7 @@ export async function launchWebDappBrowser(
     ownsProcess('wallet-host', previous.hostPid, runtime);
   if (reusable) {
     await browserWebSocketUrl(cdpPort, 5000);
-    log(`reusing browser pid ${previous.browserPid} (${signer}, ${args.account})`);
+    log(`reusing browser pid ${previous.browserPid} (${signer}, ${account.name})`);
     const state = { ...previous, slowMoMs };
     if (previous.slowMoMs !== slowMoMs)
       writePrivateFile(stateFile, `${JSON.stringify(state, null, 2)}\n`);
@@ -518,7 +526,7 @@ export async function launchWebDappBrowser(
   const browser = await resolveBrowser(env);
   const profile = path.join(
     runtime,
-    `profile-${signer}-${args.account.replace(/[^A-Za-z0-9_-]/gu, '_')}`,
+    `profile-${signer}-${account.name.replace(/[^A-Za-z0-9_-]/gu, '_')}`,
   );
   if (args['fresh-profile'] && existsSync(profile)) {
     const retired = `${profile}.retired-${Date.now()}`;
@@ -571,7 +579,7 @@ export async function launchWebDappBrowser(
         target,
         runtime,
         profile,
-        account: args.account,
+        account: account.name,
         fixture,
         env,
         freshProfile,
@@ -683,7 +691,7 @@ export async function launchWebDappBrowser(
       '--target',
       target,
       '--account',
-      args.account,
+      account.name,
       '--start-chain',
       String(args['start-chain'] ?? policy.startChain),
       '--network',
@@ -758,7 +766,7 @@ export async function launchWebDappBrowser(
       appListeners: cdpListenerPids(appPort),
       cdpPort,
       appOrigin,
-      account: { name: args.account, address: accountAddress },
+      account,
       browserPid,
       hostPid,
       browser: {

package/src/web-dapp/lib/readiness.mjs

@@ -11,10 +11,9 @@ import path from 'node:path';
 import { ownsProcess, pidAlive, portFree } from './processes.mjs';
 import {
   canonicalPath,
-  fixtureEntry,
   loadWalletFixture,
   readBrowserState,
-  viemAccountFromEntry,
+  walletAccount,
   webDappPolicy,
   webDappRuntimeDir,
 } from './runtime.mjs';
@@ -359,7 +358,7 @@ export async function webDappReadiness({
 
   try {
     const { file, fixture } = await loadWalletFixture(target, env);
-    const address = viemAccountFromEntry(fixtureEntry(fixture, account), target).address;
+    const { address } = walletAccount(fixture, account, target, env);
     checks.push(
       check('wallet-fixture', true, `${path.basename(file)}: account ${account} -> ${address}`),
     );

package/src/web-dapp/lib/runtime.mjs

@@ -151,22 +151,26 @@ export function fixtureEntry(fixture, name) {
       .join(', ');
     throw new Error(`wallet fixture has no account named "${name}". Available: ${names}.`);
   }
+  return checkedEntry(entry);
+}
+
+function checkedEntry(entry) {
   if (entry.type !== 'mnemonic' && entry.type !== 'privateKey') {
     throw new Error(
-      `wallet fixture account "${name}" must be mnemonic or privateKey, got "${entry.type}".`,
+      `wallet fixture account "${entry.name}" must be mnemonic or privateKey, got "${entry.type}".`,
     );
   }
   if (typeof entry.value !== 'string' || !entry.value.trim()) {
-    throw new Error(`wallet fixture account "${name}" has no value.`);
+    throw new Error(`wallet fixture account "${entry.name}" has no value.`);
   }
   return entry;
 }
 
-// Mnemonics use BIP-44 index 0, the MetaMask default and the derivation the
-// Extension fixture flow imports.
-export function viemAccountFromEntry(entry, projectRoot) {
+// Mnemonics use BIP-44 m/44'/60'/0'/0/<addressIndex>, the MetaMask derivation
+// the Extension fixture flow imports; index 0 is the wallet's first account.
+export function viemAccountFromEntry(entry, projectRoot, addressIndex = 0) {
   const { mnemonicToAccount, privateKeyToAccount } = loadViemAccounts(projectRoot);
-  if (entry.type === 'mnemonic') return mnemonicToAccount(entry.value.trim(), { addressIndex: 0 });
+  if (entry.type === 'mnemonic') return mnemonicToAccount(entry.value.trim(), { addressIndex });
   const raw = entry.value.trim();
   const key = raw.startsWith('0x') ? raw : `0x${raw}`;
   if (!/^0x[0-9a-fA-F]{64}$/u.test(key)) {
@@ -175,9 +179,123 @@ export function viemAccountFromEntry(entry, projectRoot) {
   return privateKeyToAccount(key);
 }
 
+// Named HD derivations of the fixture's mnemonic entries that the host adds,
+// e.g. a team's shared test account at a higher index: JSON
+// [{ "name", "secret": <mnemonic entry name>, "index", "address"? }]. Names and
+// indexes only; the key stays in the fixture.
+export const DERIVED_ACCOUNTS_ENV = 'RECIPE_WALLET_DERIVED_ACCOUNTS';
+
+export function derivedAccounts(env = process.env) {
+  const raw = env[DERIVED_ACCOUNTS_ENV];
+  if (!raw) return [];
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${DERIVED_ACCOUNTS_ENV} is not JSON: ${error.message}`);
+  }
+  const valid = (item) =>
+    item &&
+    typeof item.name === 'string' &&
+    item.name.trim() &&
+    typeof item.secret === 'string' &&
+    item.secret.trim() &&
+    Number.isInteger(item.index) &&
+    item.index >= 0 &&
+    (item.address === undefined || /^0x[0-9a-fA-F]{40}$/u.test(item.address));
+  if (!Array.isArray(value) || !value.every(valid)) {
+    throw new Error(
+      `${DERIVED_ACCOUNTS_ENV} must be an array of { name, secret, index, address? } (index a non-negative integer).`,
+    );
+  }
+  return value;
+}
+
+function mnemonicCount(entry) {
+  const count = Number(entry.count ?? entry.numberOfAccounts ?? 1);
+  if (!Number.isInteger(count) || count < 1 || count > 100) {
+    throw new Error(
+      `wallet fixture account "${entry.name}" count must be an integer from 1 through 100.`,
+    );
+  }
+  return count;
+}
+
+// names[index] when the entry gives one; a single account keeps the entry's
+// name; otherwise dev1 with count 3 is dev1, dev2, dev3 (a name without a
+// trailing number gets one appended).
+function derivedName(entry, index, count) {
+  const explicit = Array.isArray(entry.names) ? entry.names[index] : undefined;
+  if (typeof explicit === 'string' && explicit.trim()) return explicit.trim();
+  if (count === 1) return entry.name;
+  const match = /^(.*?)(\d+)$/u.exec(entry.name);
+  return match ? `${match[1]}${Number(match[2]) + index}` : `${entry.name}${index + 1}`;
+}
+
+/**
+ * Every account the fixture offers: each mnemonic entry expanded to its count,
+ * each private key, then the host's named derivations (DERIVED_ACCOUNTS_ENV)
+ * of the secrets this fixture holds. `account` is the viem account holding the
+ * key: sign with it, never log or persist it.
+ */
+export function walletAccounts(fixture, projectRoot, env = process.env) {
+  const accounts = [];
+  for (const entry of fixture.accounts) {
+    if (entry?.type !== 'mnemonic' && entry?.type !== 'privateKey') continue;
+    checkedEntry(entry);
+    const count = entry.type === 'mnemonic' ? mnemonicCount(entry) : 1;
+    for (let index = 0; index < count; index += 1) {
+      const account = viemAccountFromEntry(entry, projectRoot, index);
+      accounts.push({
+        name: derivedName(entry, index, count),
+        address: account.address,
+        secret: entry.name,
+        index,
+        account,
+      });
+    }
+  }
+  for (const item of derivedAccounts(env)) {
+    const entry = fixture.accounts.find(
+      (candidate) => candidate?.type === 'mnemonic' && candidate.name === item.secret,
+    );
+    if (!entry) continue;
+    const account = viemAccountFromEntry(checkedEntry(entry), projectRoot, item.index);
+    if (item.address && item.address.toLowerCase() !== account.address.toLowerCase()) {
+      throw new Error(
+        `wallet account "${item.name}" derives to ${account.address} from "${item.secret}" index ${item.index}, not the declared ${item.address}.`,
+      );
+    }
+    accounts.push({
+      name: item.name,
+      address: account.address,
+      secret: item.secret,
+      index: item.index,
+      account,
+    });
+  }
+  return accounts;
+}
+
+// The fixture account a selector names: an account name, else an address.
+export function walletAccount(fixture, selector, projectRoot, env = process.env) {
+  const accounts = walletAccounts(fixture, projectRoot, env);
+  const wanted = String(selector ?? '').trim();
+  const found =
+    accounts.find((account) => account.name === wanted) ??
+    (/^0x[0-9a-fA-F]{40}$/u.test(wanted)
+      ? accounts.find((account) => account.address.toLowerCase() === wanted.toLowerCase())
+      : undefined);
+  if (!found) {
+    const names = accounts.map((account) => account.name).join(', ');
+    throw new Error(`wallet fixture has no account named "${wanted}". Available: ${names}.`);
+  }
+  return found;
+}
+
 export async function fixtureAccount(projectRoot, name, env = process.env) {
   const { fixture } = await loadWalletFixture(projectRoot, env);
-  return viemAccountFromEntry(fixtureEntry(fixture, name), projectRoot);
+  return walletAccount(fixture, name, projectRoot, env).account;
 }
 
 // Address-only view of the account a node targets: an explicit address wins