@terrariumlabs/core 0.4.0 → 0.6.0

package/bin/terrarium.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // terrarium — the CLI.
 //
-//   terrarium build [--scenario terrarium.scenario.ts] [--out dist-terrarium]
+//   terrarium build [--scenario terrarium.scenario.ts] [--out dist-terrarium] [--devbar hidden|off]
 //       One injectable classic script (dist-terrarium/terrarium.js): chain Worker + wallet + dev bar. Inject it into
 //       any page (Playwright addInitScript, a <script> tag, a bookmarklet) — your dapp built without the Terrarium,
 //       a Storybook, someone else's dapp.
@@ -15,6 +15,12 @@
 //       account (balance, nonce, code) and storage slot, runs your script against the fork (every account, code blob
 //       and slot the EVM touches is recorded), rolls the script's changes back (unless --keep) and dumps. The fixture
 //       is what a scenario's `fork: { blockNumber, offline: true }, restore: fixture.dump` consumes.
+//
+//   terrarium import-anvil [name=0xaddress]... --rpc <url> [--broadcast run-latest.json] [--artifacts out/] [--out fixture.json] [--skip 0xaddress]...
+//       Everything a running Anvil holds (anvil_dumpState: every account's code, storage, nonce and balance) as a fixture
+//       for ctx.install(): deploy your protocol with its own tooling (forge script, hardhat deploy) against Anvil and
+//       boot the Terrarium from the result, byte for byte. --skip leaves accounts out (Anvil's funded test accounts,
+//       which the Terrarium funds itself, are skipped by default).
 import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -28,9 +34,12 @@ for (let i = 0; i < rest.length; i++) {
 }
 const define = { 'process.env.DEBUG': 'undefined', 'process.env.TERRARIUM_DEBUG': 'undefined' };
 const usage = `usage:
-  terrarium build [--scenario terrarium.scenario.ts] [--out dist-terrarium]
+  terrarium build [--scenario terrarium.scenario.ts] [--out dist-terrarium] [--devbar hidden|off]
   terrarium fetch-code <name=0xaddress>... --rpc <url> [--block N] [--chain ID] [--out fixture.json]
-  terrarium record [name=0xaddress]... --rpc <url> [--block N] [--chain ID] [--storage name:slot,slot] [--script warm.mjs] [--keep] [--out fixture.json]`;
+  terrarium record [name=0xaddress]... --rpc <url> [--block N] [--chain ID] [--storage name:slot,slot] [--script warm.mjs] [--keep] [--out fixture.json]
+  terrarium import-anvil [name=0xaddress]... --rpc <url> [--broadcast run-latest.json] [--artifacts out/] [--out fixture.json] [--skip 0xaddress]...
+      --broadcast: a Foundry broadcast (contract names + addresses), --artifacts: the out/ (or artifacts/) dir with their ABIs;
+      both land in the fixture as names/abis, so the dev bar's explorer shows the deployment decoded with no scenario code`;
 const fail = (msg) => { console.error(msg); process.exit(1); };
 const hex = (n) => '0x' + BigInt(n).toString(16);
 /** a raw JSON-RPC call to --rpc */
@@ -53,7 +62,7 @@ if (cmd === 'build') {
   const scenario = '/' + relative(root, resolve(root, args.scenario ?? 'terrarium.scenario.ts')).split(sep).join('/');
   const dir = resolve(root, '.terrarium'); mkdirSync(dir, { recursive: true });
   writeFileSync(join(dir, 'worker.ts'), `import scenario from '${scenario}';\nimport { runScenario } from '@terrariumlabs/core/worker';\nrunScenario(scenario);\n`);
-  writeFileSync(join(dir, 'inject-bundle.ts'), `import { startTerrarium } from '@terrariumlabs/core/inject';\ndeclare const __TERRARIUM_WORKER_SRC__: string;\nstartTerrarium(new Worker(URL.createObjectURL(new Blob([__TERRARIUM_WORKER_SRC__], { type: 'text/javascript' })), { type: 'module' }));\n`);
+  writeFileSync(join(dir, 'inject-bundle.ts'), `import { startTerrarium } from '@terrariumlabs/core/inject';\ndeclare const __TERRARIUM_WORKER_SRC__: string;\nstartTerrarium(new Worker(URL.createObjectURL(new Blob([__TERRARIUM_WORKER_SRC__], { type: 'text/javascript' })), { type: 'module' })${args.devbar === 'hidden' ? ", { devBar: 'hidden' }" : args.devbar === 'off' ? ', { devBar: false }' : ''});\n`);
   await build({ root, configFile: false, logLevel: 'warn', define, build: { outDir: out, emptyOutDir: true, target: 'es2022', minify: true, lib: { entry: '.terrarium/worker.ts', formats: ['es'], fileName: () => 'terrarium.worker.js' }, rollupOptions: { output: { codeSplitting: false } } } });
   const outDir = resolve(root, out);
   const workerSrc = readFileSync(join(outDir, 'terrarium.worker.js'), 'utf8');
@@ -74,6 +83,52 @@ if (cmd === 'build') {
   const out = args.out ?? 'fixture.json';
   writeFileSync(out, JSON.stringify(fixture, null, 2));
   console.log(`wrote ${out} (chain ${chainId}, block ${blockNumber})`);
+} else if (cmd === 'import-anvil') {
+  if (!args.rpc) fail(usage);
+  const { gunzipSync } = await import('node:zlib');
+  const { TEST_KEYS } = await import('../src/engine.js');
+  const { privateKeyToAccount } = await import('viem/accounts');
+  const chainId = await resolveChain();
+  const blockNumber = Number(await remote('eth_blockNumber'));
+  const raw = await remote('anvil_dumpState');
+  const bytes = Buffer.from(raw.slice(2), 'hex');
+  const dump = JSON.parse((bytes[0] === 0x1f && bytes[1] === 0x8b ? gunzipSync(bytes) : bytes).toString('utf8'));
+  // Anvil's ten test accounts are the Terrarium's own (funded at genesis): only their nonces matter, so a deployer's
+  // next transaction does not collide with what it already deployed
+  const testAccounts = new Set(TEST_KEYS.map((k) => privateKeyToAccount(k).address.toLowerCase()));
+  const skip = new Set([].concat(args.skip ?? []).map((a) => String(a).toLowerCase()));
+  const accounts = {}; let slots = 0, contracts = 0;
+  for (const [address, acct] of Object.entries(dump.accounts ?? {})) {
+    const a = address.toLowerCase(); if (skip.has(a) || !acct) continue;
+    const code = acct.code && acct.code !== '0x' ? acct.code : undefined;
+    const storage = acct.storage && Object.keys(acct.storage).length ? acct.storage : undefined;
+    if (testAccounts.has(a)) { if (Number(acct.nonce)) accounts[a] = { nonce: Number(acct.nonce) }; continue; }
+    accounts[a] = { nonce: Number(acct.nonce), balance: acct.balance, code, storage };
+    if (code) contracts++; slots += Object.keys(storage ?? {}).length;
+  }
+  // names: name=0xaddress positionals, and a Foundry broadcast (forge script --broadcast writes broadcast/<Script>/<chain>/run-latest.json)
+  const names = {};
+  for (const p of positional) { const [name, address] = p.split('='); if (name && address?.startsWith('0x')) names[address.toLowerCase()] = name; }
+  if (args.broadcast) {
+    const b = JSON.parse(readFileSync(resolve(process.cwd(), args.broadcast), 'utf8'));
+    for (const tx of b.transactions ?? []) {
+      if (tx.contractName && tx.contractAddress) names[tx.contractAddress.toLowerCase()] ??= tx.contractName;
+      for (const c of tx.additionalContracts ?? []) if (c.address) names[c.address.toLowerCase()] ??= c.contractName ?? (tx.contractName ? `${tx.contractName} (created)` : 'contract');
+    }
+  }
+  // ABIs: for each named contract, <name>.json somewhere under --artifacts (Foundry out/<File>.sol/<Name>.json, Hardhat artifacts/…)
+  const abis = {};
+  if (args.artifacts) {
+    const { readdirSync } = await import('node:fs');
+    const files = new Map();
+    const walk = (dir) => { for (const e of readdirSync(dir, { withFileTypes: true })) { const p = join(dir, e.name); if (e.isDirectory()) walk(p); else if (e.name.endsWith('.json') && !e.name.endsWith('.dbg.json')) files.set(e.name.slice(0, -5), p); } };
+    walk(resolve(process.cwd(), args.artifacts));
+    for (const [address, name] of Object.entries(names)) { const p = files.get(name); if (!p) continue; const abi = JSON.parse(readFileSync(p, 'utf8')).abi; if (Array.isArray(abi)) abis[address] = abi; }
+  }
+  const fixture = { source: `Anvil state imported with \`terrarium import-anvil\` via ${args.rpc}`, chainId, blockNumber, importedAt: new Date().toISOString(), accounts, ...(Object.keys(names).length ? { names } : {}), ...(Object.keys(abis).length ? { abis } : {}) };
+  const out = args.out ?? 'fixture.json';
+  writeFileSync(out, JSON.stringify(fixture));
+  console.log(`wrote ${out}: ${contracts} contracts, ${Object.keys(accounts).length} accounts, ${slots} storage slots (chain ${chainId}, block ${blockNumber})${Object.keys(names).length ? `, ${Object.keys(names).length} named, ${Object.keys(abis).length} with an ABI` : ''}`);
 } else if (cmd === 'record') {
   if (!args.rpc) fail(usage);
   const [{ createTerrarium }, viem] = await Promise.all([import('../src/engine.js'), import('viem')]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrariumlabs/core",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "A complete EVM chain inside the page, presented to your dapp as a wallet. revm in WebAssembly, real receipts, byte-identical to Anvil.",
   "type": "module",
   "license": "MIT",
@@ -44,6 +44,7 @@
     "./devbar": "./src/devbar.ts",
     "./bridge": "./src/bridge.ts",
     "./http": "./src/http.ts",
+    "./transport": "./src/transport.ts",
     "./vite": "./src/vite-plugin.js",
     "./fixtures/*": "./fixtures/*"
   },
@@ -60,7 +61,7 @@
     "@ethereumjs/util": "^10.1.3",
     "@ethereumjs/mpt": "^10.1.3",
     "@ethereumjs/rlp": "^10.0.0",
-    "@terrariumlabs/evm": "^0.4.0"
+    "@terrariumlabs/evm": "^0.6.0"
   },
   "peerDependencies": {
     "viem": "^2.0.0",

package/src/devbar.ts

@@ -1,39 +1,68 @@
 // devbar.ts — the dev overlay. Plain DOM, own styles, talks to the chain only through provider.request(), so it works
-// on top of any dapp (React or not) and never touches the dapp's code. Two parts: the bar (controls) and the transaction
-// explorer, a panel above it listing every transaction with its receipt, decoded call, events and revert reason
-// (`terrarium_transactions`: the scenario runtime decodes with the scenario's `abis` and names addresses with `labels`).
+// on top of any dapp (React or not) and never touches the dapp's code. Parts: the bar (grouped controls: scenario, chain,
+// wallet, the scenario's own buttons, explorer / reset / hide), the transaction explorer (a panel above it listing every
+// transaction with its receipt, decoded call, events and revert reason, fed by `terrarium_transactions`), the scenario
+// selector (`terrarium_scenarios` / `terrarium_selectScenario`) when the Worker runs a list, toasts for every action, and
+// two keyboard shortcuts (Alt+Shift+T: the bar, Alt+Shift+X: the explorer).
 type Provider = { request(a: { method: string; params?: unknown[] }): Promise<any> };
 
 const HIDDEN_KEY = 'terrarium:devbar-hidden';
 const CSS = `
-#terrarium-devbar { position: fixed; left: 0; right: 0; bottom: 0; z-index: 2147483000; display: flex; align-items: center; gap: 8px; flex-wrap: wrap; padding: 10px 24px; background: #14231b; color: #dfe9e3; font: 13px/1.4 ui-sans-serif, system-ui, -apple-system, 'Segoe UI', sans-serif; font-variant-numeric: tabular-nums; }
-#terrarium-devbar[hidden], #terrarium-explorer[hidden], #terrarium-devbar-show[hidden] { display: none; }
-#terrarium-devbar .tag { background: #e8c547; color: #14231b; font-weight: 700; padding: 2px 8px; border-radius: 6px; }
-#terrarium-devbar .muted { color: rgba(223, 233, 227, 0.7); }
-#terrarium-devbar .muted b { color: #fff; font-weight: 600; }
-#terrarium-devbar .spacer { flex: 1; }
-#terrarium-devbar button { background: rgba(255,255,255,0.08); border: 1px solid rgba(255,255,255,0.14); color: #fff; padding: 6px 10px; border-radius: 8px; font: inherit; cursor: pointer; }
-#terrarium-devbar button:hover { background: rgba(255,255,255,0.16); }
-#terrarium-devbar button.on { background: #1f6f5c; border-color: #1f6f5c; }
+#terrarium-devbar { position: fixed; left: 0; right: 0; bottom: 0; z-index: 2147483000; display: flex; align-items: center; gap: 6px 14px; flex-wrap: wrap; padding: 8px 16px; background: #14231b; color: #dfe9e3; font: 12.5px/1.4 ui-sans-serif, system-ui, -apple-system, 'Segoe UI', sans-serif; font-variant-numeric: tabular-nums; box-shadow: 0 -1px 0 rgba(255,255,255,0.08); }
+#terrarium-devbar[hidden], #terrarium-explorer[hidden], #terrarium-devbar-show[hidden], #terrarium-devbar-menu[hidden] { display: none; }
+#terrarium-devbar *:focus-visible, #terrarium-explorer *:focus-visible, #terrarium-devbar-show:focus-visible { outline: 2px solid #e8c547; outline-offset: 1px; }
+#terrarium-devbar .brand { display: flex; align-items: center; gap: 8px; }
+#terrarium-devbar .tag { background: #e8c547; color: #14231b; font-weight: 700; padding: 2px 8px; border-radius: 6px; letter-spacing: 0.01em; }
+#terrarium-devbar .name { color: #fff; font-weight: 600; }
+#terrarium-devbar select { background: rgba(255,255,255,0.08); border: 1px solid rgba(255,255,255,0.14); color: #fff; padding: 5px 8px; border-radius: 8px; font: inherit; font-weight: 600; cursor: pointer; max-width: 260px; }
+#terrarium-devbar .status { display: flex; align-items: center; gap: 10px; color: rgba(223,233,227,0.72); white-space: nowrap; }
+#terrarium-devbar .status b { color: #fff; font-weight: 600; }
+#terrarium-devbar .status .warn { color: #e8c547; }
+#terrarium-devbar .status .shift { color: #e8c547; font-weight: 600; }
+#terrarium-devbar .spacer { flex: 1; min-width: 8px; }
+#terrarium-devbar .group { display: flex; align-items: center; gap: 4px; padding-left: 10px; border-left: 1px solid rgba(255,255,255,0.12); position: relative; }
+#terrarium-devbar .group[hidden] { display: none; }
+#terrarium-devbar .glabel { font-size: 10px; text-transform: uppercase; letter-spacing: 0.08em; color: rgba(223,233,227,0.45); margin-right: 4px; user-select: none; }
+#terrarium-devbar .glabel:empty { display: none; }
+@media (max-width: 1280px) { #terrarium-devbar .glabel { display: none; } #terrarium-devbar { gap: 6px 10px; padding: 6px 12px; } }
+#terrarium-devbar button, #terrarium-devbar-menu button { background: rgba(255,255,255,0.07); border: 1px solid rgba(255,255,255,0.12); color: #fff; padding: 5px 9px; border-radius: 8px; font: inherit; cursor: pointer; white-space: nowrap; }
+#terrarium-devbar button:hover { background: rgba(255,255,255,0.15); }
+#terrarium-devbar button.on { background: #1f6f5c; border-color: #2b8a73; }
 #terrarium-devbar button.armed { background: #7a3b2a; border-color: #b3452c; }
 #terrarium-devbar button.danger { border-color: rgba(255,140,110,0.4); color: #ffb5a0; }
-#terrarium-devbar button.quiet { background: transparent; border-color: transparent; color: rgba(223,233,227,0.7); }
+#terrarium-devbar button.danger.armed { background: #b3452c; border-color: #ff8c6e; color: #fff; }
+#terrarium-devbar button.quiet { background: transparent; border-color: transparent; color: rgba(223,233,227,0.6); }
+#terrarium-devbar button.quiet:hover { color: #fff; background: rgba(255,255,255,0.08); }
+#terrarium-devbar button .badge { display: inline-block; margin-left: 6px; padding: 0 6px; border-radius: 999px; background: rgba(255,255,255,0.14); font-size: 11px; line-height: 16px; }
+#terrarium-devbar button .badge.bad { background: #b3452c; }
+#terrarium-devbar-menu { position: fixed; z-index: 2147483001; display: flex; flex-direction: column; gap: 2px; padding: 4px; background: #1b2e24; color: #dfe9e3; border: 1px solid rgba(255,255,255,0.14); border-radius: 10px; box-shadow: 0 6px 24px rgba(0,0,0,0.4); font: 12.5px/1.4 ui-sans-serif, system-ui, sans-serif; }
+#terrarium-devbar-menu button { text-align: left; background: transparent; border-color: transparent; }
+#terrarium-devbar-menu button:hover { background: rgba(255,255,255,0.1); }
 #terrarium-devbar-show { position: fixed; right: 12px; bottom: 12px; z-index: 2147483000; width: 36px; height: 36px; border-radius: 50%; border: 1px solid rgba(255,255,255,0.2); background: #14231b; color: #e8c547; font: 16px/1 ui-sans-serif, system-ui, sans-serif; cursor: pointer; box-shadow: 0 2px 8px rgba(0,0,0,0.35); }
+#terrarium-toast { position: fixed; right: 16px; z-index: 2147483001; display: flex; flex-direction: column; gap: 6px; align-items: flex-end; pointer-events: none; font: 12.5px/1.4 ui-sans-serif, system-ui, sans-serif; }
+#terrarium-toast div { background: #1b2e24; color: #dfe9e3; border: 1px solid rgba(255,255,255,0.14); border-left: 3px solid #e8c547; border-radius: 8px; padding: 6px 10px; box-shadow: 0 4px 16px rgba(0,0,0,0.35); opacity: 1; transition: opacity 0.3s; max-width: 420px; }
+#terrarium-toast div.bad { border-left-color: #ff8c6e; }
+#terrarium-toast div.fade { opacity: 0; }
 #terrarium-explorer { position: fixed; left: 0; right: 0; z-index: 2147483000; max-height: 60vh; overflow: auto; background: #0f1a14; color: #dfe9e3; border-top: 1px solid rgba(255,255,255,0.12); font: 12px/1.45 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-variant-numeric: tabular-nums; }
-#terrarium-explorer .head { display: flex; align-items: center; gap: 12px; padding: 8px 24px; font: 13px ui-sans-serif, system-ui, sans-serif; color: rgba(223,233,227,0.8); position: sticky; top: 0; background: #0f1a14; border-bottom: 1px solid rgba(255,255,255,0.08); }
+#terrarium-explorer.tall { max-height: 90vh; }
+#terrarium-explorer .head { display: flex; align-items: center; gap: 10px; padding: 8px 16px; font: 13px ui-sans-serif, system-ui, sans-serif; color: rgba(223,233,227,0.8); position: sticky; top: 0; background: #0f1a14; border-bottom: 1px solid rgba(255,255,255,0.08); }
 #terrarium-explorer .head b { color: #fff; }
+#terrarium-explorer .head select, #terrarium-explorer .head input, #terrarium-explorer .head button { background: rgba(255,255,255,0.08); border: 1px solid rgba(255,255,255,0.14); color: #fff; padding: 3px 8px; border-radius: 6px; font: inherit; }
+#terrarium-explorer .head input { width: 220px; } #terrarium-explorer .head input::placeholder { color: rgba(223,233,227,0.45); }
+#terrarium-explorer .head button { cursor: pointer; } #terrarium-explorer .head button:hover { background: rgba(255,255,255,0.15); }
 #terrarium-explorer table { width: 100%; border-collapse: collapse; }
 #terrarium-explorer th { text-align: left; font-weight: 600; color: rgba(223,233,227,0.6); padding: 6px 12px; border-bottom: 1px solid rgba(255,255,255,0.08); white-space: nowrap; }
-#terrarium-explorer th:first-child, #terrarium-explorer td:first-child { padding-left: 24px; }
+#terrarium-explorer th:first-child, #terrarium-explorer td:first-child { padding-left: 16px; }
 #terrarium-explorer td { padding: 6px 12px; border-bottom: 1px solid rgba(255,255,255,0.05); white-space: nowrap; vertical-align: top; }
 #terrarium-explorer tr.tx { cursor: pointer; }
 #terrarium-explorer tr.tx:hover td { background: rgba(255,255,255,0.04); }
 #terrarium-explorer tr.tx.open td { background: rgba(255,255,255,0.06); border-bottom-color: transparent; }
 #terrarium-explorer .ok { color: #7fd3a8; } #terrarium-explorer .bad { color: #ff9c80; } #terrarium-explorer .wait { color: #e8c547; }
 #terrarium-explorer .hash, #terrarium-explorer .addr { color: #9ecbff; }
+#terrarium-explorer .hash { cursor: copy; } #terrarium-explorer .hash:hover { text-decoration: underline dotted; }
 #terrarium-explorer .name { color: #e8c547; }
 #terrarium-explorer .dim { color: rgba(223,233,227,0.55); }
-#terrarium-explorer .detail td { padding: 10px 24px 14px 48px; white-space: normal; background: rgba(0,0,0,0.25); }
+#terrarium-explorer .detail td { padding: 10px 16px 14px 40px; white-space: normal; background: rgba(0,0,0,0.25); }
 #terrarium-explorer dl { display: grid; grid-template-columns: max-content 1fr; gap: 3px 16px; margin: 0; }
 #terrarium-explorer dt { color: rgba(223,233,227,0.6); } #terrarium-explorer dd { margin: 0; word-break: break-all; }
 #terrarium-explorer .events { margin: 10px 0 0; padding: 0; list-style: none; }
@@ -55,55 +84,102 @@ export const formatEth = (hex: string | null | undefined) => {
 const formatGwei = (hex: string | null | undefined) => { if (!hex) return '0'; const wei = BigInt(hex), whole = wei / 10n ** 9n, frac = (wei % 10n ** 9n).toString().padStart(9, '0').slice(0, 3).replace(/0+$/, ''); return frac ? `${whole}.${frac}` : whole.toString(); };
 const fmtArgs = (args: any): string => Array.isArray(args) ? args.map(fmtArgs).join(', ') : args && typeof args === 'object' ? Object.entries(args).map(([k, v]) => `${k}: ${fmtArgs(v)}`).join(', ') : String(args);
 const time = (hex: string | null) => (hex ? new Date(Number(BigInt(hex)) * 1000).toLocaleTimeString() : '');
+/** a duration in seconds as "+1h 30m" / "-2d" */
+const span = (s: number) => { const a = Math.abs(s), sign = s < 0 ? '-' : '+'; if (a < 3600) return `${sign}${Math.round(a / 60)}m`; if (a < 86400) { const h = Math.floor(a / 3600), m = Math.round((a % 3600) / 60); return `${sign}${h}h${m ? ` ${m}m` : ''}`; } const d = Math.floor(a / 86400), h = Math.round((a % 86400) / 3600); return `${sign}${d}d${h ? ` ${h}h` : ''}`; };
 
-export function mountDevBar(provider: Provider) {
+export interface DevBarOptions {
+  /** start collapsed to the leaf (default false). A Hide/Show click is remembered in localStorage and overrides this */
+  hidden?: boolean;
+}
+
+export function mountDevBar(provider: Provider, opts: DevBarOptions = {}) {
   if (document.getElementById('terrarium-devbar')) return;
   const rpc = (method: string, params: unknown[] = []) => provider.request({ method, params });
   const bar = document.createElement('footer');
-  bar.id = 'terrarium-devbar'; bar.dataset.testid = 'devbar';
+  bar.id = 'terrarium-devbar'; bar.dataset.testid = 'devbar'; bar.setAttribute('role', 'toolbar'); bar.setAttribute('aria-label', 'Terrarium dev bar');
   const style = document.createElement('style'); style.textContent = CSS;
   bar.append(style);
   const el = (html: string) => { const t = document.createElement('template'); t.innerHTML = html.trim(); return t.content.firstElementChild as HTMLElement; };
-  const btn = (label: string, testid: string, title: string, onClick: () => Promise<unknown> | void) => { const b = el(`<button data-testid="${testid}" title="${title}">${label}</button>`); b.onclick = () => Promise.resolve(onClick()).catch((e) => console.warn('[terrarium]', e)); return b; };
+  const btn = (label: string, testid: string, title: string, onClick: () => Promise<unknown> | void) => { const b = el(`<button data-testid="${testid}" title="${esc(title)}" aria-label="${esc(title)}">${label}</button>`); b.onclick = () => Promise.resolve(onClick()).catch((e) => { console.warn('[terrarium]', e); toast(e?.message ?? String(e), true); }); return b; };
+  const group = (label: string, testid: string, ...children: HTMLElement[]) => { const g = el(`<div class="group" data-testid="${testid}" role="group" aria-label="${esc(label || 'tools')}"><span class="glabel">${label}</span></div>`); g.append(...children); return g; };
+
+  // ---- toasts: every action says what it did --------------------------------------------------------------------------------
+  const toasts = el('<div id="terrarium-toast" data-testid="toast" aria-live="polite"></div>');
+  const toast = (msg: string, bad = false) => {
+    const t = el(`<div${bad ? ' class="bad"' : ''}>${esc(msg)}</div>`); toasts.append(t);
+    setTimeout(() => { t.classList.add('fade'); setTimeout(() => t.remove(), 350); }, bad ? 5000 : 2200);
+  };
+
+  // ---- brand + scenario selector + status ---------------------------------------------------------------------------
+  const brand = el(`<span class="brand"><span class="tag">Terrarium</span><span class="name" data-testid="scenario-name" hidden></span></span>`);
+  const scenarioSelect = el(`<select data-testid="scenario" aria-label="Scenario" title="Which scenario the chain runs: switching stores the choice and reloads the page; each scenario keeps its own chain" hidden></select>`) as HTMLSelectElement;
+  brand.append(scenarioSelect);
+  let scenariosKey = '';
+  scenarioSelect.onchange = () => { toast(`Switching to “${scenarioSelect.value}”…`); rpc('terrarium_selectScenario', [scenarioSelect.value]).catch((e) => { console.warn('[terrarium]', e); toast(e?.message ?? String(e), true); }); };
+  const status = el(`<span class="status"><span>block <b data-testid="block" data-f="block">…</b></span><span>chain <span data-f="chain">…</span></span><span data-testid="clock" data-f="clock" title="The chain's clock: the timestamp the next block gets. Yellow when it has been shifted away from wall time (deadlines and oracles see this clock, not yours)"></span><span data-f="engine"></span></span>`);
 
-  const info = el(`<span class="muted">simulated chain <span data-f="chain">…</span> · block <b data-testid="block" data-f="block">…</b> · <span data-f="engine">…</span> · state persists in IndexedDB</span>`);
-  let mining: 'auto' | 'interval' = 'auto', snap: string | null = null;
+  // ---- chain ------------------------------------------------------------------------------------------------------------
+  let mining: 'auto' | 'interval' = 'auto', snap: { id: string; block: number } | null = null, head = 0;
   const bMining = btn('Blocks: instant', 'mining', 'Auto: a block per transaction. Interval: a block every 3s, so you can watch pending states', async () => {
     mining = mining === 'auto' ? 'interval' : 'auto';
     await (mining === 'auto' ? rpc('evm_setAutomine', [true]) : rpc('evm_setIntervalMining', [3000]));
-    bMining.textContent = mining === 'auto' ? 'Blocks: instant' : 'Blocks: every 3s';
+    bMining.textContent = mining === 'auto' ? 'Blocks: instant' : 'Blocks: every 3s'; bMining.classList.toggle('on', mining === 'interval');
+    toast(mining === 'auto' ? 'A block per transaction again' : 'A block every 3 seconds: transactions stay pending in between');
   });
   const bSnap = btn('Snapshot', 'snapshot', 'Snapshot the chain; revert brings blocks, receipts, journal and the UI history back', async () => {
-    if (snap) { await rpc('evm_revert', [snap]); snap = null; bSnap.textContent = 'Snapshot'; }
-    else { snap = await rpc('evm_snapshot'); bSnap.textContent = 'Revert to snapshot'; }
+    if (snap) { await rpc('evm_revert', [snap.id]); toast(`Reverted to block ${snap.block}`); snap = null; bSnap.textContent = 'Snapshot'; bSnap.classList.remove('on'); }
+    else { const id = await rpc('evm_snapshot'); snap = { id, block: head }; bSnap.textContent = `Revert to block ${head}`; bSnap.classList.add('on'); toast(`Snapshot at block ${head}: the next click reverts to it`); }
   });
-  const bActors = btn('Actors off', 'actors', 'Scripted actors: other users, keepers, arbitrageurs trading on their own', () => rpc('terrarium_actors'));
-  const bReject = btn('Reject next tx', 'reject-next', 'The wallet rejects the next signature request (EIP-1193 error 4001), like a user hitting Cancel', () => rpc('terrarium_setWallet', [{ rejectNext: 1 }]));
-  const bLatency = btn('Wallet: instant', 'wallet-latency', 'Make the wallet take 2 seconds to answer, like a real one', async () => { const w = await rpc('terrarium_getWallet'); await rpc('terrarium_setWallet', [{ latencyMs: w.latencyMs ? 0 : 2000 }]); });
-  const bLag = btn('Receipts: instant', 'receipt-lag', 'Receipts appear 3 seconds after the block, like a node that has not caught up', async () => { const w = await rpc('terrarium_getWallet'); await rpc('terrarium_setWallet', [{ receiptLagMs: w.receiptLagMs ? 0 : 3000 }]); });
-  const bReset = btn('Reset pond', 'reset', 'Wipe the chain and redeploy everything', async () => { await rpc('terrarium_reset'); location.reload(); });
-  bReset.classList.add('danger');
+  const timeMenu = el('<div id="terrarium-devbar-menu" data-testid="time-menu" role="menu" aria-label="Move the chain clock" hidden></div>');   // on the body: a menu inside the bar was clipped by its layout
+  const shift = (seconds: number, label: string, testid: string) => btn(label, testid, `Move the chain clock forward ${label.slice(1)} and mine a block`, async () => { timeMenu.hidden = true; await rpc('evm_increaseTime', [seconds]); await rpc('evm_mine'); toast(`Chain clock moved ${label}; a block sealed at the new time`); });
+  timeMenu.append(shift(60, '+1 minute', 'plus-minute'), shift(3600, '+1 hour', 'plus-hour'), shift(86400, '+1 day', 'plus-day'), shift(7 * 86400, '+1 week', 'plus-week'));
+  const bTime = btn('Time ▾', 'time', 'Move the chain clock forward: deadlines expire, oracles go stale, interest accrues', () => {
+    timeMenu.hidden = !timeMenu.hidden;
+    if (!timeMenu.hidden) { const r = bTime.getBoundingClientRect(); timeMenu.style.left = `${r.left}px`; timeMenu.style.bottom = `${window.innerHeight - r.top + 6}px`; }
+  });
+  bTime.setAttribute('aria-haspopup', 'menu');
+  const gChain = group('chain', 'group-chain',
+    btn('Mine a block', 'mine', 'Mine one empty block', async () => { await rpc('evm_mine'); toast(`Mined block ${head + 1}`); }),
+    bTime, bMining, bSnap);
+  document.addEventListener('click', (e) => { if (!timeMenu.hidden && !bTime.contains(e.target as Node) && !timeMenu.contains(e.target as Node)) timeMenu.hidden = true; });
+
+  // ---- wallet -----------------------------------------------------------------------------------------------------------
+  const bReject = btn('Reject next tx', 'reject-next', 'The wallet rejects the next signature request (EIP-1193 error 4001), like a user hitting Cancel', async () => { await rpc('terrarium_setWallet', [{ rejectNext: 1 }]); toast('The wallet will reject the next signature request'); });
+  const bLatency = btn('Wallet: instant', 'wallet-latency', 'Make the wallet take 2 seconds to answer, like a real one', async () => { const w = await rpc('terrarium_getWallet'); await rpc('terrarium_setWallet', [{ latencyMs: w.latencyMs ? 0 : 2000 }]); toast(w.latencyMs ? 'The wallet answers instantly again' : 'The wallet now takes 2 seconds to answer'); });
+  const bLag = btn('Receipts: instant', 'receipt-lag', 'Receipts appear 3 seconds after the block, like a node that has not caught up', async () => { const w = await rpc('terrarium_getWallet'); await rpc('terrarium_setWallet', [{ receiptLagMs: w.receiptLagMs ? 0 : 3000 }]); toast(w.receiptLagMs ? 'Receipts are immediate again' : 'Receipts now arrive 3 seconds after the block'); });
+  const gWallet = group('wallet', 'group-wallet', bReject, bLatency, bLag);
+
+  // ---- the scenario's own knobs: actors + controls ------------------------------------------------------------------------
+  const bActors = btn('Actors off', 'actors', 'Scripted actors: other users, keepers, arbitrageurs trading on their own', async () => { const on = await rpc('terrarium_actors'); toast(on ? `${actorsLabel} on: other actors are trading now` : `${actorsLabel} off`); });
+  let actorsLabel = 'Actors';
+  const controls = el('<span class="controls" style="display:contents"></span>'); let controlsKey = '';
+  const gScenario = group('scenario', 'group-scenario', bActors, controls);
 
-  // ---- the transaction explorer -----------------------------------------------------------------------------------
-  const panel = el(`<section id="terrarium-explorer" data-testid="explorer" hidden></section>`);
+  // ---- the transaction explorer -----------------------------------------------------------------------------------------
+  const panel = el(`<section id="terrarium-explorer" data-testid="explorer" role="region" aria-label="Transactions" hidden></section>`);
   const open = new Set<string>();   // expanded rows, by hash, kept across refreshes
-  let lastRender = '';
-  const bTxs = btn('Transactions', 'txs', 'Every transaction on this chain, like a block explorer: receipt, decoded call, events, revert reason', async () => {
-    panel.hidden = !panel.hidden; bTxs.classList.toggle('on', !panel.hidden); lastRender = '';
-    if (!panel.hidden) await refreshTxs();
-  });
-  const place = () => { panel.style.bottom = `${bar.offsetHeight}px`; };
+  let lastRender = '', filter: 'all' | 'mine' | 'failed' = 'all', search = '', me: string | null = null;   // `me`: accounts[0] from terrarium_status
+  const bTxs = btn('Transactions', 'txs', 'Every transaction on this chain, like a block explorer: receipt, decoded call, events, revert reason (Alt+Shift+X)', () => togglePanel());
+  const togglePanel = async (show: boolean = !!panel.hidden) => { panel.hidden = !show; bTxs.classList.toggle('on', show); lastRender = ''; if (show) { await refreshTxs(); panel.querySelector<HTMLInputElement>('[data-testid=tx-search]')?.focus(); } place(); };
+  const place = () => { panel.style.bottom = `${bar.offsetHeight}px`; toasts.style.bottom = `${bar.offsetHeight + (panel.hidden ? 0 : panel.offsetHeight) + 12}px`; };   // toasts sit above whatever is open
   const statusCell = (s: string) => s === 'success' ? '<span class="ok" title="success">✓</span>' : s === 'pending' ? '<span class="wait" title="pending">⏳</span>' : `<span class="bad" title="${s}">✗</span>`;
   const who = (labels: Record<string, string>, a: string | null) => a ? `<span class="addr" title="${a}">${esc(labels[a.toLowerCase()] ?? short(a))}</span>` : '<span class="dim">contract creation</span>';
+  const matches = (t: any, L: Record<string, string>) => {
+    if (!search) return true;
+    const q = search.toLowerCase();
+    const hay = [t.hash, t.from, t.to, L[t.from?.toLowerCase()], L[t.to?.toLowerCase()], t.method?.name, t.method?.selector, t.revert?.name, t.status, ...(t.logs ?? []).flatMap((l: any) => [l.decoded?.name, L[l.address?.toLowerCase()], l.address])].filter(Boolean).join(' ').toLowerCase();
+    return hay.includes(q);
+  };
   const render = (data: { total: number; labels: Record<string, string>; transactions: any[] }) => {
-    const key = JSON.stringify([data.total, data.transactions.map((t) => [t.hash, t.status]), [...open]]);
+    const key = JSON.stringify([data.total, data.transactions.map((t) => [t.hash, t.status]), [...open], filter, search, me]);
     if (key === lastRender) return; lastRender = key;
     const L = data.labels ?? {};
-    const rows = data.transactions.map((t) => {
+    const shown = data.transactions.filter((t) => (filter === 'all' ? true : filter === 'failed' ? t.status !== 'success' && t.status !== 'pending' : !!me && t.from?.toLowerCase() === me.toLowerCase()) && matches(t, L));
+    const rows = shown.map((t) => {
       const method = t.method ? (t.method.name ? `<span class="name">${esc(t.method.name)}</span>` : `<span class="dim">${esc(t.method.selector)}</span>`) : '<span class="dim">transfer</span>';
       const isOpen = open.has(t.hash);
       const detail = !isOpen ? '' : `<tr class="detail" data-testid="tx-detail"><td colspan="10"><dl>
-        <dt>hash</dt><dd class="hash">${esc(t.hash)}</dd>
+        <dt>hash</dt><dd class="hash" data-copy="${t.hash}" title="click to copy">${esc(t.hash)}</dd>
         <dt>status</dt><dd>${esc(t.status)}${t.status === 'reverted' || t.status === 'dropped' ? ` <span class="bad">· ${t.revert ? esc(t.revert.name) + '(' + esc(fmtArgs(t.revert.args)) + ')' : esc(t.error ?? '')}</span>` : ''}</dd>
         <dt>block</dt><dd>${t.receipt ? `${num(t.receipt.blockNumber)} · ${esc(time(t.timestamp))} · index ${num(t.receipt.transactionIndex)}` : 'pending'}</dd>
         <dt>from</dt><dd>${who(L, t.from)} <span class="dim">${esc(t.from)}</span></dd>
@@ -118,63 +194,116 @@ export function mountDevBar(provider: Provider) {
       </td></tr>`;
       return `<tr class="tx${isOpen ? ' open' : ''}" data-testid="tx-row" data-hash="${t.hash}" data-status="${t.status}">
         <td>${statusCell(t.status)}</td><td>${t.receipt ? num(t.receipt.blockNumber) : '<span class="dim">pending</span>'}</td><td class="dim">${esc(time(t.timestamp))}</td>
-        <td class="hash" title="${t.hash}">${short(t.hash)}</td><td>${method}</td><td>${who(L, t.from)}</td><td>${who(L, t.to)}</td>
+        <td class="hash" data-copy="${t.hash}" title="${t.hash} (click to copy)">${short(t.hash)}</td><td>${method}</td><td>${who(L, t.from)}</td><td>${who(L, t.to)}</td>
         <td>${formatEth(t.value)} ETH</td><td class="dim">${t.receipt ? num(t.receipt.gasUsed) : ''}</td><td class="dim">${t.logs?.length ? `${t.logs.length} event${t.logs.length === 1 ? '' : 's'}` : ''}</td></tr>${detail}`;
     }).join('');
-    panel.innerHTML = `<div class="head"><b>Transactions</b> <span>${data.total} on this chain, newest first${data.total > data.transactions.length ? ` (showing ${data.transactions.length})` : ''}</span><span class="spacer" style="flex:1"></span><span class="dim">click a row for the receipt, the decoded call and the events</span></div>`
-      + (rows ? `<table><thead><tr><th></th><th>block</th><th>time</th><th>hash</th><th>method</th><th>from</th><th>to</th><th>value</th><th>gas used</th><th>events</th></tr></thead><tbody>${rows}</tbody></table>` : `<div class="empty">No transactions yet. Do something in the dapp and it appears here.</div>`);
+    const headEl = panel.querySelector('.head');
+    const headHtml = `<b>Transactions</b> <span data-testid="explorer-count">${data.total} on this chain${data.total > data.transactions.length ? ` (showing ${data.transactions.length})` : ''}${filter !== 'all' || search ? `, ${shown.length} shown` : ''}</span>
+      <input data-testid="tx-search" type="search" placeholder="filter: hash, address, name, method, event…" aria-label="Filter transactions" value="${esc(search)}">
+      <select data-testid="tx-filter" aria-label="Which transactions" title="Which transactions to list"><option value="all"${filter === 'all' ? ' selected' : ''}>all</option><option value="mine"${filter === 'mine' ? ' selected' : ''}>mine (account #0)</option><option value="failed"${filter === 'failed' ? ' selected' : ''}>failed</option></select>
+      <span class="spacer" style="flex:1"></span><span class="dim">click a row for the receipt, the decoded call and the events · Esc closes</span>
+      <button data-testid="explorer-size" title="Taller / shorter panel">${panel.classList.contains('tall') ? '⇩ shorter' : '⇧ taller'}</button>`;
+    const body = rows ? `<table><thead><tr><th></th><th>block</th><th>time</th><th>hash</th><th>method</th><th>from</th><th>to</th><th>value</th><th>gas used</th><th>events</th></tr></thead><tbody>${rows}</tbody></table>` : `<div class="empty">${data.total ? 'Nothing matches.' : 'No transactions yet. Do something in the dapp and it appears here.'}</div>`;
+    if (headEl && document.activeElement === headEl.querySelector('[data-testid=tx-search]')) {
+      // keep the focused search box: update its neighbours only
+      headEl.querySelector('[data-testid=explorer-count]')!.textContent = `${data.total} on this chain${filter !== 'all' || search ? `, ${shown.length} shown` : ''}`;
+      panel.querySelector('table, .empty')?.remove(); panel.insertAdjacentHTML('beforeend', body);
+    } else panel.innerHTML = `<div class="head">${headHtml}</div>${body}`;
     place();
   };
+  panel.addEventListener('change', (e) => { const sel = e.target as HTMLSelectElement; if (sel.dataset.testid === 'tx-filter') { filter = sel.value as typeof filter; lastRender = ''; refreshTxs(); } });
+  panel.addEventListener('input', (e) => { const inp = e.target as HTMLInputElement; if (inp.dataset.testid === 'tx-search') { search = inp.value.trim(); lastRender = ''; refreshTxs(); } });
   panel.addEventListener('click', (e) => {
-    const row = (e.target as HTMLElement).closest<HTMLElement>('tr.tx'); if (!row) return;
+    const target = e.target as HTMLElement;
+    const copy = target.closest<HTMLElement>('[data-copy]');
+    if (copy) { e.stopPropagation(); navigator.clipboard?.writeText(copy.dataset.copy!).then(() => toast(`Copied ${short(copy.dataset.copy!)}`), () => toast('Clipboard unavailable', true)); return; }
+    if (target.closest('[data-testid=explorer-size]')) { panel.classList.toggle('tall'); lastRender = ''; refreshTxs(); return; }
+    const row = target.closest<HTMLElement>('tr.tx'); if (!row) return;
     const h = row.dataset.hash!; open.has(h) ? open.delete(h) : open.add(h); lastRender = ''; refreshTxs();
   });
   const refreshTxs = async () => { const data = await rpc('terrarium_transactions', [{ limit: 200 }]).catch(() => null); if (data) render(data); };
 
-  // ---- hide / show --------------------------------------------------------------------------------------------------
-  const pill = el(`<button id="terrarium-devbar-show" data-testid="show" title="Show the Terrarium dev bar" hidden>🌱</button>`);
-  const remember = (hidden: boolean) => { try { hidden ? localStorage.setItem(HIDDEN_KEY, '1') : localStorage.removeItem(HIDDEN_KEY); } catch {} };
-  const setHidden = (hidden: boolean) => {
-    bar.hidden = hidden; pill.hidden = !hidden;
-    if (hidden) { panel.hidden = true; bTxs.classList.remove('on'); }
-    document.body.style.paddingBottom = hidden ? '' : '64px';
-    remember(hidden);
-  };
-  const bHide = btn('Hide', 'hide', 'Hide the dev bar (the chain keeps running); the leaf at the bottom right brings it back', () => setHidden(true));
+  // ---- reset (two clicks), hide / show ------------------------------------------------------------------------------------
+  let resetArmed: ReturnType<typeof setTimeout> | null = null;
+  const bReset = btn('Reset', 'reset', 'Wipe this scenario\'s chain and boot it again from scratch (click twice)', async () => {
+    if (!resetArmed) { bReset.textContent = 'Really reset?'; bReset.classList.add('armed'); toast('Click Reset again within 3 seconds to wipe this scenario\'s chain'); resetArmed = setTimeout(() => { resetArmed = null; bReset.textContent = 'Reset'; bReset.classList.remove('armed'); }, 3000); return; }
+    clearTimeout(resetArmed); resetArmed = null; bReset.textContent = 'Resetting…';
+    await rpc('terrarium_reset'); location.reload();
+  });
+  bReset.classList.add('danger');
+  const pill = el(`<button id="terrarium-devbar-show" data-testid="show" title="Show the Terrarium dev bar (Alt+Shift+T)" aria-label="Show the Terrarium dev bar" hidden>🌱</button>`);
+  const remember = (hidden: boolean) => { try { localStorage.setItem(HIDDEN_KEY, hidden ? '1' : '0'); } catch {} };
+  const apply = (hidden: boolean) => { bar.hidden = hidden; pill.hidden = !hidden; if (hidden) { panel.hidden = true; bTxs.classList.remove('on'); } document.body.style.paddingBottom = hidden ? '' : '56px'; toasts.style.bottom = hidden ? '60px' : `${(bar.offsetHeight || 48) + 12}px`; };
+  const setHidden = (hidden: boolean) => { apply(hidden); remember(hidden); };
+  const bHide = btn('Hide', 'hide', 'Hide the dev bar (the chain keeps running); the leaf at the bottom right or Alt+Shift+T brings it back', () => setHidden(true));
   bHide.classList.add('quiet');
   pill.onclick = () => setHidden(false);
+  const gTools = group('', 'group-tools', bTxs, bReset, bHide);
 
-  const controls = el('<span class="controls" style="display:contents"></span>'); let controlsKey = '';
-  bar.append(el('<span class="tag">Terrarium</span>'), info, el('<span class="spacer"></span>'), controls,
-    btn('Mine a block', 'mine', 'Mine one empty block', () => rpc('evm_mine')),
-    btn('+1 hour', 'plus-hour', 'Move the chain clock forward one hour', async () => { await rpc('evm_increaseTime', [3600]); await rpc('evm_mine'); }),
-    bMining, bSnap, bActors, bReject, bLatency, bLag, bTxs, bReset, bHide, panel);
-  document.body.append(bar, pill);
-  let startHidden = false; try { startHidden = localStorage.getItem(HIDDEN_KEY) === '1'; } catch {}
-  setHidden(startHidden);
+  bar.append(brand, status, el('<span class="spacer"></span>'), gChain, gWallet, gScenario, gTools, panel);
+  document.body.append(bar, pill, toasts, timeMenu);
+  let startHidden = !!opts.hidden; try { const v = localStorage.getItem(HIDDEN_KEY); if (v !== null) startHidden = v === '1'; } catch {}
+  apply(startHidden);   // without remembering: the default is not a choice
 
+  // ---- keyboard: Alt+Shift+T the bar, Alt+Shift+X the explorer, Esc closes the explorer / the time menu -----------------------------
+  const onKey = (e: KeyboardEvent) => {
+    if (!document.getElementById('terrarium-devbar')) { document.removeEventListener('keydown', onKey); return; }
+    if (e.altKey && e.shiftKey && (e.code === 'KeyT')) { e.preventDefault(); setHidden(!bar.hidden); }
+    else if (e.altKey && e.shiftKey && (e.code === 'KeyX')) { e.preventDefault(); if (bar.hidden) setHidden(false); togglePanel(); }
+    else if (e.key === 'Escape') { if (!panel.hidden) togglePanel(false); timeMenu.hidden = true; }
+  };
+  document.addEventListener('keydown', onKey);
+
+  // ---- polling: status every 500 ms, the explorer while open, the scenario list now and then -----------------------------------
+  const refreshScenarios = async () => {
+    const s = await rpc('terrarium_scenarios').catch(() => null); if (!s) return;
+    const k = JSON.stringify(s); if (k === scenariosKey) return; scenariosKey = k;
+    const many = s.scenarios.length > 1;
+    scenarioSelect.hidden = !many;
+    const name = brand.querySelector<HTMLElement>('[data-testid=scenario-name]')!;
+    name.hidden = many || !s.active || /^Scenario \d+$/.test(s.active); name.textContent = s.active ?? '';
+    if (many) {
+      scenarioSelect.replaceChildren(...s.scenarios.map((sc: any) => { const o = document.createElement('option'); o.value = sc.name; o.textContent = sc.name; if (sc.description) o.title = sc.description; o.selected = sc.name === s.active; return o; }));
+      const active = s.scenarios.find((sc: any) => sc.name === s.active); if (active?.description) scenarioSelect.title = `${active.description}\n\nSwitching stores the choice and reloads the page; each scenario keeps its own chain.`;
+    }
+  };
   const refresh = async () => {
-    if (!document.getElementById('terrarium-devbar')) return;   // unmounted: stop polling
     const s = await rpc('terrarium_status').catch(() => null); if (!s) return;
-    info.querySelector('[data-f=chain]')!.textContent = String(s.chainId);
-    info.querySelector('[data-f=block]')!.textContent = String(parseInt(s.block, 16));
-    info.querySelector('[data-f=engine]')!.textContent = 'revm/wasm' + (s.fork ? ` · fork @${s.fork.blockNumber}${s.fork.offline ? ' offline' : ''}${s.fork.misses ? ` · ${s.fork.misses} MISSES` : ''}` : '')
-      + (s.http?.routes ? ` · ${s.http.routes} HTTP route${s.http.routes === 1 ? '' : 's'}, ${s.http.hits} answered` : '')
-      + (s.restoredFromPersistence ? ` · ${s.localBlocks} local block${s.localBlocks === 1 ? '' : 's'} restored from a previous session (Reset to start clean)` : '');
+    me = s.accounts?.[0] ?? me; head = parseInt(s.block, 16); actorsLabel = s.actorsLabel ?? actorsLabel;
+    status.querySelector('[data-f=chain]')!.textContent = String(s.chainId);
+    status.querySelector('[data-f=block]')!.textContent = String(head);
+    if (s.now) {
+      const chainNow = Number(BigInt(s.now)), drift = chainNow - Math.floor(Date.now() / 1000);
+      const clock = status.querySelector<HTMLElement>('[data-f=clock]')!;
+      clock.innerHTML = Math.abs(drift) > 90 ? `clock ${esc(new Date(chainNow * 1000).toLocaleString())} <span class="shift">${esc(span(drift))}</span>` : `clock ${esc(new Date(chainNow * 1000).toLocaleTimeString())}`;
+    }
+    const notes: string[] = [];
+    if (s.fork) notes.push(`fork @${s.fork.blockNumber}${s.fork.offline ? ' offline' : ''}${s.fork.misses ? ` · <span class="warn">${s.fork.misses} MISSES</span>` : ''}`);
+    if (s.http?.routes) notes.push(`${s.http.routes} HTTP route${s.http.routes === 1 ? '' : 's'}, ${s.http.hits} answered`);
+    if (s.restoredFromPersistence) notes.push(`${s.localBlocks} block${s.localBlocks === 1 ? '' : 's'} restored`);
+    status.querySelector('[data-f=engine]')!.innerHTML = notes.map((n) => `<span>${n}</span>`).join('');
+    status.title = `revm/wasm · the chain persists in IndexedDB${s.restoredFromPersistence ? ' (Reset to start clean)' : ''}`;
+    if (s.txs) { const bad = s.txs.failed ? `<span class="badge bad" title="${s.txs.failed} failed">${s.txs.failed} ✗</span>` : ''; const pend = s.txs.pending ? `<span class="badge" title="${s.txs.pending} pending">${s.txs.pending} ⏳</span>` : ''; bTxs.innerHTML = `Transactions<span class="badge">${s.txs.total}</span>${pend}${bad}`; }
     const ck = JSON.stringify(s.controls ?? []);
-    if (ck !== controlsKey) { controlsKey = ck; controls.replaceChildren(...(s.controls ?? []).map((c: any, i: number) => btn(c.label, `control-${i}`, c.title ?? c.method, () => rpc(c.method, c.params ?? [])))); }
+    if (ck !== controlsKey) { controlsKey = ck; controls.replaceChildren(...(s.controls ?? []).map((c: any, i: number) => btn(c.label, `control-${i}`, c.title ?? c.method, async () => { const r = await rpc(c.method, c.params ?? []); toast(`${c.label}${r !== undefined && r !== null && typeof r !== 'object' ? ` → ${r}` : ''}`); }))); }
     bActors.hidden = !s.hasActors; bActors.textContent = `${s.actorsLabel} ${s.actors ? 'on' : 'off'}`; bActors.classList.toggle('on', s.actors);
+    gScenario.hidden = !s.hasActors && !(s.controls?.length);
     bReject.textContent = s.wallet.rejectNext > 0 ? `Reject next tx · armed (${s.wallet.rejectNext})` : 'Reject next tx'; bReject.classList.toggle('armed', s.wallet.rejectNext > 0);
     bLatency.textContent = s.wallet.latencyMs ? `Wallet: ${s.wallet.latencyMs / 1000}s delay` : 'Wallet: instant'; bLatency.classList.toggle('on', !!s.wallet.latencyMs);
     bLag.textContent = s.wallet.receiptLagMs ? `Receipts: ${s.wallet.receiptLagMs / 1000}s late` : 'Receipts: instant'; bLag.classList.toggle('on', !!s.wallet.receiptLagMs);
+    if (!bar.hidden) place();
     if (!panel.hidden) await refreshTxs();
   };
-  refresh(); const timer = setInterval(() => { if (document.getElementById('terrarium-devbar')) refresh(); else clearInterval(timer); }, 500);
+  refresh(); refreshScenarios();
+  let ticks = 0;
+  const timer = setInterval(() => { if (!document.getElementById('terrarium-devbar')) return clearInterval(timer); refresh(); if (++ticks % 10 === 0) refreshScenarios(); }, 500);
 }
 
-/** Remove the dev bar, its explorer and the show pill; restore the page's bottom padding. Idempotent. */
+/** Remove the dev bar, its explorer, the toasts and the show pill; restore the page's bottom padding. Idempotent. */
 export function unmountDevBar() {
   document.getElementById('terrarium-devbar')?.remove();
   document.getElementById('terrarium-devbar-show')?.remove();
+  document.getElementById('terrarium-toast')?.remove();
+  document.getElementById('terrarium-devbar-menu')?.remove();
   document.body?.style.removeProperty('padding-bottom');
 }

package/src/engine.js

@@ -66,7 +66,7 @@ class RecordingRPCStateManager extends RPCStateManager {
   async getStorage(address, key) { if (this.knownAbsent(address) && this._caches.storage.get(address, key) === undefined) return new Uint8Array(); const rk = `${address.toString()}_${bytesToHex(key)}`; if (this._caches.storage.get(address, key) === undefined && this.remote.storage.has(rk)) { const v = this.remote.storage.get(rk); this._caches.storage.put(address, key, v); return v; } if (this.offline && this._caches.storage.get(address, key) === undefined) this.miss('storage', `${address.toString()}:${bytesToHex(key)}`); if (globalThis.process?.env?.TERRARIUM_DEBUG && this._caches.storage.get(address, key) === undefined) console.log('[remote] storage', address.toString(), bytesToHex(key)); const v = await this.retry(() => super.getStorage(address, key)); this.remote.storage.set(`${address.toString()}_${bytesToHex(key)}`, v); return v; }
 }
 
-const STATE_CHANGING = new Set(['eth_sendTransaction', 'eth_sendRawTransaction', 'evm_mine', 'anvil_mine', 'hardhat_mine', 'evm_setNextBlockTimestamp', 'anvil_setNextBlockTimestamp', 'evm_increaseTime', 'anvil_increaseTime', 'evm_setAutomine', 'anvil_setAutomine', 'anvil_setBalance', 'hardhat_setBalance', 'anvil_setCode', 'hardhat_setCode', 'anvil_setNonce', 'hardhat_setNonce', 'anvil_setStorageAt', 'hardhat_setStorageAt', 'anvil_impersonateAccount', 'hardhat_impersonateAccount', 'anvil_stopImpersonatingAccount', 'hardhat_stopImpersonatingAccount', 'anvil_setNextBlockBaseFeePerGas', 'hardhat_setNextBlockBaseFeePerGas', 'sim_deal', 'sim_setState']);
+const STATE_CHANGING = new Set(['eth_sendTransaction', 'eth_sendRawTransaction', 'evm_mine', 'anvil_mine', 'hardhat_mine', 'evm_setNextBlockTimestamp', 'anvil_setNextBlockTimestamp', 'evm_increaseTime', 'anvil_increaseTime', 'evm_setAutomine', 'anvil_setAutomine', 'anvil_setBalance', 'hardhat_setBalance', 'anvil_setCode', 'hardhat_setCode', 'anvil_setNonce', 'hardhat_setNonce', 'anvil_setStorageAt', 'hardhat_setStorageAt', 'anvil_loadState', 'hardhat_loadState', 'anvil_impersonateAccount', 'hardhat_impersonateAccount', 'anvil_stopImpersonatingAccount', 'hardhat_stopImpersonatingAccount', 'anvil_setNextBlockBaseFeePerGas', 'hardhat_setNextBlockBaseFeePerGas', 'sim_deal', 'sim_setState']);
 const pad32 = (h) => pad(typeof h === 'bigint' ? numberToHex(h, { size: 32 }) : h, { size: 32 });
 
 /** small deterministic PRNG (mulberry32) so scripted actors are reproducible when a seed is given */
@@ -458,7 +458,7 @@ export async function createTerrarium(opts = {}) {
       return { ...t.rpc, status, receipt: t.receipt, timestamp: b ? hex(b.timestamp) : null, error: t.error ?? null, revertData: t.revertData ?? null };
     });
     const from = before ? all.findIndex((t) => t.hash === before) + 1 : 0;
-    return { total: all.length, transactions: all.slice(from, from + Math.max(0, limit)) };
+    return { total: all.length, pending: all.filter((t) => t.status === 'pending').length, failed: all.filter((t) => t.status === 'reverted' || t.status === 'dropped').length, transactions: all.slice(from, from + Math.max(0, limit)) };
   }
 
   // ---- RPC formatting ----------------------------------------------------------------------------
@@ -583,6 +583,7 @@ export async function createTerrarium(opts = {}) {
         case 'anvil_setCode': case 'hardhat_setCode': await sm.putCode(createAddressFromString(params[0]), hexToBytes(params[1])); return null;
         case 'anvil_setNonce': case 'hardhat_setNonce': await sm.modifyAccountFields(createAddressFromString(params[0]), { nonce: hexToBigInt(params[1]) }); return null;
         case 'anvil_setStorageAt': case 'hardhat_setStorageAt': await sm.putStorage(createAddressFromString(params[0]), hexToBytes(numberToHex(hexToBigInt(params[1]), { size: 32 })), hexToBytes(numberToHex(hexToBigInt(params[2]), { size: 32 }))); return null;
+        case 'anvil_loadState': case 'hardhat_loadState': return loadAnvilState(params[0]);
         case 'anvil_impersonateAccount': case 'hardhat_impersonateAccount': impersonated.add(params[0].toLowerCase()); return null;
         case 'anvil_stopImpersonatingAccount': case 'hardhat_stopImpersonatingAccount': impersonated.delete(params[0].toLowerCase()); return null;
         case 'anvil_setNextBlockBaseFeePerGas': case 'hardhat_setNextBlockBaseFeePerGas': baseFee = hexToBigInt(params[0]); return null;
@@ -709,6 +710,37 @@ export async function createTerrarium(opts = {}) {
     return written;
   }
 
+  // ---- anvil_loadState: an Anvil state dump (anvil_dumpState / --dump-state) written into this chain ------------------
+  // Accepts what Anvil hands out: the gzipped JSON as a hex string, or the parsed object. Every account's code, nonce,
+  // balance and storage land through the state manager like the single cheatcodes do, in one journaled call. Deploy a
+  // protocol with its own tooling (Foundry scripts, Hardhat deploys) against Anvil, dump, and boot the Terrarium from it.
+  async function loadAnvilState(input) {
+    const dump = typeof input === 'string' ? await parseAnvilDump(input) : input;
+    const accounts = dump?.accounts ?? dump;
+    if (!accounts || typeof accounts !== 'object') throw new RpcError(-32602, 'anvil_loadState: expected an Anvil state dump ({ accounts: { address: { nonce, balance, code, storage } } })');
+    let n = 0, slots = 0;
+    for (const [a, acct] of Object.entries(accounts)) {
+      if (!acct) continue;
+      const addr = createAddressFromString(a);
+      if (acct.code && acct.code !== '0x') await sm.putCode(addr, hexToBytes(acct.code));
+      const fields = {};
+      if (acct.nonce !== undefined) fields.nonce = BigInt(acct.nonce);
+      if (acct.balance !== undefined) fields.balance = BigInt(acct.balance);
+      if (Object.keys(fields).length) await sm.modifyAccountFields(addr, fields);
+      for (const [k, v] of Object.entries(acct.storage ?? {})) { await sm.putStorage(addr, hexToBytes(pad32(hexToBigInt(k))), hexToBytes(pad32(hexToBigInt(v)))); slots++; }
+      n++;
+    }
+    return { accounts: n, slots };
+  }
+  /** Anvil's wire format: hex of gzipped JSON. Inflated with the platform's DecompressionStream (browsers, Workers, Node 18+). */
+  async function parseAnvilDump(hexDump) {
+    const bytes = hexToBytes(hexDump);
+    if (bytes[0] !== 0x1f || bytes[1] !== 0x8b) return JSON.parse(new TextDecoder().decode(bytes));   // not gzipped: plain JSON as hex
+    if (typeof DecompressionStream === 'undefined') throw new RpcError(-32000, 'anvil_loadState: gzipped dump but no DecompressionStream here; pass the parsed object');
+    const inflated = await new Response(new Blob([bytes]).stream().pipeThrough(new DecompressionStream('gzip'))).text();
+    return JSON.parse(inflated);
+  }
+
   // ---- persistence: dump the diff, restore it, or replay the journal -------------------------------
   const serBlock = (b) => ({ ...b, number: hex(b.number), timestamp: hex(b.timestamp), gasLimit: hex(b.gasLimit), gasUsed: hex(b.gasUsed), baseFeePerGas: hex(b.baseFeePerGas) });
   const deserBlock = (b) => ({ ...b, number: hexToBigInt(b.number), timestamp: hexToBigInt(b.timestamp), gasLimit: hexToBigInt(b.gasLimit), gasUsed: hexToBigInt(b.gasUsed), baseFeePerGas: hexToBigInt(b.baseFeePerGas) });
@@ -778,7 +810,7 @@ export async function createTerrarium(opts = {}) {
     dumpState: () => exclusive(dumpState), loadState: (d) => exclusive(() => loadState(d)), replayJournal: (j) => exclusive(() => replayJournal(j)),
     get journal() { return journal.slice(); }, flush: () => { clearTimeout(persistTimer); return persister ? exclusive(async () => persister.setItem(persistKey, JSON.stringify(await dumpState()))) : Promise.resolve(); },
     get blockNumber() { return latest().number; },
-    /** transactions newest first ({ total, transactions }): tx + receipt + status word + revert reason/data + block timestamp */
+    /** transactions newest first ({ total, pending, failed, transactions }): tx + receipt + status word + revert reason/data + block timestamp */
     transactions: (o) => listTransactions(o),
     /** React to on-chain events with scripted actors (keepers, oracles, other users, bridges...). */
     onLog(filter, handler) { const l = { filter, handler }; logListeners.push(l); return () => logListeners.splice(logListeners.indexOf(l), 1); },

package/src/inject.ts

@@ -8,8 +8,9 @@ import { installHttpInterceptor, type WireRoute } from './http.ts';
 const ICON = 'data:image/svg+xml,' + encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="8" fill="#1F6F5C"/><path d="M6 25.5c2-6 5.5-8.5 10-8.5s8 2.5 10 8.5" fill="none" stroke="#E8C547" stroke-width="2.5" stroke-linecap="round"/><path d="M16 17.5V9" stroke="#E8C547" stroke-width="2.5" stroke-linecap="round"/><path d="M16 12c0-4.5 3-7 7-7 0 4.5-3 7-7 7Z M16 14.5c0-4.5-3-7-7-7 0 4.5 3 7 7 7Z" fill="#E8C547"/></svg>');
 
 export interface StartOptions {
-  /** mount the dev bar (default true); false for a host that draws its own controls */
-  devBar?: boolean;
+  /** mount the dev bar (default true); 'hidden' mounts it collapsed to the leaf at the bottom right (a Hide/Show click is
+   *  remembered and wins); false for a host that draws its own controls */
+  devBar?: boolean | 'hidden';
 }
 let current: { worker: Worker; announce: () => void } | null = null;
 
@@ -20,6 +21,8 @@ export function startTerrarium(worker: Worker, opts: StartOptions = {}) {
   // the RPC is the fallback. Until either arrives, the dapp's fetches wait; nothing else about them changes.
   const routes = new Promise<WireRoute[]>((res) => { provider.on('httpRoutes', (r) => res(r as WireRoute[])); provider.request({ method: 'terrarium_httpRoutes' }).then((r) => res(r as WireRoute[]), () => res([])); });
   installHttpInterceptor(provider, routes);
+  // a scenario method that reset or rebuilt the chain asks the page to start over (ctx.reload())
+  provider.on('reload', () => window.location.reload());
   const detail = Object.freeze({ info: { uuid: '7e44a1c0-5f0b-4c1e-9b7a-a1b2c3d4e5f6', name: 'Terrarium Wallet', icon: ICON, rdns: 'dev.terrarium' }, provider });
   const announce = () => window.dispatchEvent(new CustomEvent('eip6963:announceProvider', { detail }));
   window.addEventListener('eip6963:requestProvider', announce);
@@ -27,7 +30,7 @@ export function startTerrarium(worker: Worker, opts: StartOptions = {}) {
   current = { worker, announce };
   // the wallet's own global (like window.ethereum) — for tests and the console, never for the dapp
   (window as any).terrarium = { provider, request: (method: string, params: unknown[] = []) => provider.request({ method, params }) };
-  if (opts.devBar !== false) { const mount = () => mountDevBar(provider); if (document.body) mount(); else document.addEventListener('DOMContentLoaded', mount); }
+  if (opts.devBar !== false) { const mount = () => mountDevBar(provider, { hidden: opts.devBar === 'hidden' }); if (document.body) mount(); else document.addEventListener('DOMContentLoaded', mount); }
   return provider;
 }
 

package/src/known-abi.ts

@@ -0,0 +1,79 @@
+// known-abi.ts — what the transaction explorer decodes with no configuration: the events, functions and errors that
+// most protocols share (token standards, WETH, Uniswap V2 pairs, Ownable, proxies, OpenZeppelin's custom errors).
+// A scenario's own `abis` and per-address `ctx.label(address, name, abi)` take precedence; this is the fallback.
+import { parseAbi } from 'viem';
+
+export const KNOWN_ABI = parseAbi([
+  // ERC-20 / ERC-721 / ERC-1155
+  'event Transfer(address indexed from, address indexed to, uint256 value)',
+  'event Transfer(address indexed from, address indexed to, uint256 indexed tokenId)',
+  'event Approval(address indexed owner, address indexed spender, uint256 value)',
+  'event Approval(address indexed owner, address indexed approved, uint256 indexed tokenId)',
+  'event ApprovalForAll(address indexed owner, address indexed operator, bool approved)',
+  'event TransferSingle(address indexed operator, address indexed from, address indexed to, uint256 id, uint256 value)',
+  'event TransferBatch(address indexed operator, address indexed from, address indexed to, uint256[] ids, uint256[] values)',
+  'function transfer(address to, uint256 value) returns (bool)',
+  'function transferFrom(address from, address to, uint256 value) returns (bool)',
+  'function approve(address spender, uint256 value) returns (bool)',
+  'function mint(address to, uint256 amount)',
+  'function burn(uint256 amount)',
+  'function safeTransferFrom(address from, address to, uint256 tokenId)',
+  'function setApprovalForAll(address operator, bool approved)',
+  'function permit(address owner, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s)',
+  // WETH
+  'event Deposit(address indexed dst, uint256 wad)',
+  'event Withdrawal(address indexed src, uint256 wad)',
+  'function deposit()',
+  'function withdraw(uint256 wad)',
+  // ERC-4626
+  'event Deposit(address indexed sender, address indexed owner, uint256 assets, uint256 shares)',
+  'event Withdraw(address indexed sender, address indexed receiver, address indexed owner, uint256 assets, uint256 shares)',
+  'function deposit(uint256 assets, address receiver) returns (uint256)',
+  'function mint(uint256 shares, address receiver) returns (uint256)',
+  'function withdraw(uint256 assets, address receiver, address owner) returns (uint256)',
+  'function redeem(uint256 shares, address receiver, address owner) returns (uint256)',
+  // Uniswap V2 pair / factory
+  'event Swap(address indexed sender, uint256 amount0In, uint256 amount1In, uint256 amount0Out, uint256 amount1Out, address indexed to)',
+  'event Sync(uint112 reserve0, uint112 reserve1)',
+  'event Mint(address indexed sender, uint256 amount0, uint256 amount1)',
+  'event Burn(address indexed sender, uint256 amount0, uint256 amount1, address indexed to)',
+  'event PairCreated(address indexed token0, address indexed token1, address pair, uint256)',
+  // Uniswap V3 pool
+  'event Swap(address indexed sender, address indexed recipient, int256 amount0, int256 amount1, uint160 sqrtPriceX96, uint128 liquidity, int24 tick)',
+  // Ownable, pausable, proxies, roles
+  'event OwnershipTransferred(address indexed previousOwner, address indexed newOwner)',
+  'event Paused(address account)',
+  'event Unpaused(address account)',
+  'event Upgraded(address indexed implementation)',
+  'event AdminChanged(address previousAdmin, address newAdmin)',
+  'event BeaconUpgraded(address indexed beacon)',
+  'event Initialized(uint64 version)',
+  'event RoleGranted(bytes32 indexed role, address indexed account, address indexed sender)',
+  'event RoleRevoked(bytes32 indexed role, address indexed account, address indexed sender)',
+  'function transferOwnership(address newOwner)',
+  'function renounceOwnership()',
+  'function upgradeTo(address newImplementation)',
+  'function upgradeToAndCall(address newImplementation, bytes data)',
+  'function multicall(bytes[] data) returns (bytes[])',
+  // OpenZeppelin 5 custom errors
+  'error ERC20InsufficientBalance(address sender, uint256 balance, uint256 needed)',
+  'error ERC20InvalidSender(address sender)',
+  'error ERC20InvalidReceiver(address receiver)',
+  'error ERC20InsufficientAllowance(address spender, uint256 allowance, uint256 needed)',
+  'error ERC20InvalidApprover(address approver)',
+  'error ERC20InvalidSpender(address spender)',
+  'error ERC721InvalidOwner(address owner)',
+  'error ERC721NonexistentToken(uint256 tokenId)',
+  'error ERC721IncorrectOwner(address sender, uint256 tokenId, address owner)',
+  'error ERC721InsufficientApproval(address operator, uint256 tokenId)',
+  'error OwnableUnauthorizedAccount(address account)',
+  'error OwnableInvalidOwner(address owner)',
+  'error EnforcedPause()',
+  'error ExpectedPause()',
+  'error ReentrancyGuardReentrantCall()',
+  'error AccessControlUnauthorizedAccount(address account, bytes32 neededRole)',
+  'error SafeERC20FailedOperation(address token)',
+  'error AddressEmptyCode(address target)',
+  'error FailedCall()',
+  'error InsufficientBalance(uint256 balance, uint256 needed)',
+]);

package/src/scenario.ts

@@ -12,7 +12,10 @@ export { reply } from './http.ts';
 export type { HttpRoute, HttpRequest, HttpReply, GraphqlQuery, GraphqlResolver } from './http.ts';
 
 /** Runtime bytecode of deployed contracts, installed at fixed addresses (`terrarium fetch-code` produces these). */
-export interface Fixture { contracts: Record<string, { address: string; code: string }> }   // plain strings: JSON imports fit as-is
+export interface Fixture extends FixtureMeta { contracts: Record<string, { address: string; code: string }> }   // plain strings: JSON imports fit as-is
+/** what any fixture may add for the transaction explorer: names and ABIs by address (`terrarium import-anvil --broadcast --artifacts`
+ *  fills them from a Foundry deployment). `install(fixture)` registers them like `ctx.label` would */
+export interface FixtureMeta { names?: Record<string, string>; abis?: Record<string, Abi | readonly unknown[]> }
 export interface LogFilter { address?: Address | Address[]; topics?: (Hex | Hex[] | null)[] }
 
 export interface ScenarioContext {
@@ -36,14 +39,31 @@ export interface ScenarioContext {
   /** true when nothing was persisted yet (first boot or after a reset), even if a fixture was restored: seed the user once */
   firstBoot: boolean;
   codeAt(address: Address): Promise<Hex>;
-  /** put a fixture's bytecode at its addresses (skips contracts already present, so it is safe on every boot) */
-  install(fixture: Fixture): Promise<void>;
+  /** put a fixture on the chain, safe on every boot. A code fixture (`terrarium fetch-code`) writes each contract's
+   *  bytecode where there is none yet. An Anvil state dump (`terrarium import-anvil`, or `anvil_dumpState` by hand)
+   *  writes whole accounts (code, storage, nonce, balance) through `anvil_loadState`: contracts that already have code
+   *  are skipped, accounts without code (the deployer's nonce, funded EOAs) are only written on a fresh chain */
+  install(fixture: Fixture | AnvilStateFixture): Promise<void>;
+  /** name an address in the transaction explorer and, optionally, give the ABI that decodes calls to it, its events and its
+   *  custom errors: `ctx.label(pair, 'PEPE/WETH pair', pairAbi)`. `install(fixture)` labels contracts by their fixture keys */
+  label(address: Address | string, name: string, abi?: Abi): void;
+  /** ask the page to reload: for a method that reset or rebuilt the chain and wants the dapp to start over on it */
+  reload(): void;
   /** a bag for whatever setup() discovers (addresses...) that actors and status() need later */
   state: Record<string, any>;
 }
 
+/** what `anvil_dumpState` / `anvil --dump-state` produce (and `terrarium import-anvil` writes): whole accounts */
+export interface AnvilStateFixture extends FixtureMeta {
+  accounts: Record<string, { nonce?: number | string; balance?: string; code?: Hex; storage?: Record<string, string> } | null>;
+  [extra: string]: unknown;
+}
+
 export interface Actor {
   name?: string;
+  /** run from the first boot, outside the actors toggle: a keeper the protocol cannot work without (an oracle answering
+   *  requests) belongs here; other people trading belongs in the toggled actors */
+  always?: boolean;
   /** run every N ms */
   every?: number;
   /** ...or run when a matching log is mined (a function, if the filter depends on setup() results) */
@@ -52,6 +72,11 @@ export interface Actor {
 }
 
 export interface ScenarioConfig {
+  /** shown in the dev bar; with several scenarios (`export default [a, b]`) it is what the selector lists and what
+   *  `terrarium_selectScenario` takes. Default: `Scenario <n>`. Its slug is the default `persist` key of a listed scenario */
+  name?: string;
+  /** one line under the name in the selector: what this scenario puts the UI through */
+  description?: string;
   chainId?: number;
   /** seed for ctx.random() and the actors; omit for a fresh seed per boot */
   seed?: number;
@@ -89,12 +114,18 @@ export interface ScenarioConfig {
    *  intercepted for matching URLs, the handler runs here in the Worker with `ctx`, everything else goes to the network.
    *  http: [{ match: 'https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2', graphql: { swaps: (ctx, q) => … } }] */
   http?: HttpRoute[];
-  /** ABIs used to decode calls, events and revert reasons in `terrarium_transactions` (the dev bar's transaction explorer);
-   *  anything they do not cover is shown raw (selector, topics, data) */
+  /** extra ABIs for the transaction explorer (`terrarium_transactions`): calls, events and custom errors decode with an
+   *  address's own ABI (`ctx.label(address, name, abi)`) first, then these, then the built-in set of standard events, functions
+   *  and errors (ERC-20/721/1155/4626, WETH, Uniswap V2, Ownable, proxies, OpenZeppelin errors). Anything left is shown raw */
   abis?: Abi[];
-  /** names for addresses in the explorer (`{ [address]: 'Uniswap V2 Router' }`), or a function of ctx for addresses only
-   *  known after setup. The sim's accounts are labelled `Account #i` unless you name them */
-  labels?: Record<string, string> | ((ctx: ScenarioContext) => Record<string, string>);
+  /** names for addresses known up front (`{ [ROUTER]: 'Uniswap V2 Router' }`); for addresses discovered in setup use
+   *  `ctx.label(address, name)`. The sim's accounts are `Account #i` unless named */
+  labels?: Record<string, string>;
 }
 
 export function defineScenario(config: ScenarioConfig): ScenarioConfig { return config; }
+/** several scenarios in one file: the dev bar shows a selector, each keeps its own persisted chain, the choice survives
+ *  reloads. `export default defineScenarios([fresh, afterCrash, indexerDown])`; a plain array works too */
+export function defineScenarios(list: ScenarioConfig[]): ScenarioConfig[] { return list; }
+/** what the Worker entry hands to `runScenario`: one scenario or a list */
+export type ScenarioInput = ScenarioConfig | ScenarioConfig[];

package/src/transport.ts

@@ -0,0 +1,47 @@
+// transport.ts — a viem transport over the Terrarium Wallet, for dapps whose reads go through a configured transport
+// rather than the connected wallet (wagmi's `createConfig({ transports })`, a `createPublicClient` per chain).
+//
+// The Terrarium has no RPC server: the wallet provider is the node. A dapp on viem alone can `custom()` the provider it
+// discovered through EIP-6963; a wagmi dapp declares one transport per chain up front, before any wallet is known, and
+// needs one that finds the provider when the first request comes. That is all this is: `custom()` over the EIP-6963
+// announcement with rdns `dev.terrarium`, resolved lazily and once. It imports nothing of the engine, so a dapp that
+// uses it ships a few dozen lines, not the simulator; still, keep it behind the same guard as the mount, since a page
+// without a Terrarium has nothing to find and reads on that chain fail like reads on an unreachable RPC.
+import { custom, type CustomTransport } from 'viem';
+
+export const TERRARIUM_RDNS = 'dev.terrarium';
+
+export interface TerrariumTransportOptions {
+  /** how long to wait for the wallet's EIP-6963 announcement before a request fails (default 4000 ms) */
+  timeoutMs?: number;
+}
+
+let found: Promise<any> | null = null;
+
+/** the Terrarium Wallet's EIP-1193 provider, discovered through EIP-6963 (or `window.terrarium` when already injected) */
+export function discoverTerrarium(timeoutMs = 4000): Promise<any> {
+  if (typeof window === 'undefined') return Promise.reject(new Error('no window: the Terrarium lives in a page'));
+  const injected = (window as any).terrarium?.provider;
+  if (injected) return Promise.resolve(injected);
+  if (found) return found;
+  found = new Promise((resolve, reject) => {
+    const onAnnounce = (e: Event) => {
+      const detail = (e as CustomEvent).detail;
+      if (detail?.info?.rdns !== TERRARIUM_RDNS) return;
+      done(); resolve(detail.provider);
+    };
+    const timer = setTimeout(() => { done(); found = null; reject(new Error('Terrarium Wallet not found on this page')); }, timeoutMs);
+    const done = () => { clearTimeout(timer); window.removeEventListener('eip6963:announceProvider', onAnnounce); };
+    window.addEventListener('eip6963:announceProvider', onAnnounce);
+    window.dispatchEvent(new Event('eip6963:requestProvider'));
+  });
+  return found;
+}
+
+/** a viem transport whose requests go to the Terrarium Wallet: `transports: { [31337]: terrariumTransport() }` in wagmi */
+export function terrariumTransport(opts: TerrariumTransportOptions = {}): CustomTransport {
+  return custom(
+    { request: async (args: { method: string; params?: unknown[] }) => (await discoverTerrarium(opts.timeoutMs)).request(args) },
+    { name: 'Terrarium', key: 'terrarium', retryCount: 0 },
+  );
+}

package/src/vite-plugin.d.ts

@@ -3,11 +3,34 @@ import type { Plugin } from 'vite';
 export interface TerrariumPluginOptions {
   /** the scenario module (default export of defineScenario), relative to the Vite root. Default: terrarium.scenario.ts */
   scenario?: string;
+  /** the dev bar: true (default), 'hidden' (starts collapsed to the leaf; a Hide/Show click is remembered and wins), false (none) */
+  devBar?: boolean | 'hidden';
+  /** how the Terrarium reaches the page. 'script' (default): one module script injected into index.html, the app's
+   *  source untouched. 'react': nothing injected; the app renders `TerrariumMount` from 'virtual:terrarium/react' at its
+   *  root (a `@terrariumlabs/react` <Terrarium> over the generated Worker, so StrictMode, context and unmount are handled),
+   *  and that module exports null when the Terrarium is off. Needs `@terrariumlabs/react` installed */
+  mount?: 'script' | 'react';
 }
 
-/** Injects the Terrarium (chain in a Worker + EIP-6963 wallet + dev bar) into index.html as a separate module script.
- *  The dapp's source is untouched: remove the plugin, or set VITE_TERRARIUM=off, and nothing of it is built. */
+/** Injects the Terrarium (chain in a Worker + EIP-6963 wallet + dev bar) into the page: a script tag by default, or a
+ *  React mount the app imports from 'virtual:terrarium/react'. Remove the plugin, or set VITE_TERRARIUM=off, and nothing
+ *  of it is built. */
 export function terrarium(opts?: TerrariumPluginOptions): Plugin;
 
 /** the Worker entry: the user's scenario + the runtime (also used by the CLI's standalone build) */
 export function workerEntry(scenarioImport: string): string;
+
+/** the generated React mount module (what 'virtual:terrarium/react' resolves to when the Terrarium is on) */
+export function reactMountEntry(devBar?: boolean | 'hidden'): string;
+
+/** the virtual module id of the React mount */
+export const REACT_MOUNT_ID: 'virtual:terrarium/react';
+
+declare module 'virtual:terrarium/react' {
+  import type { ComponentType, ReactNode } from 'react';
+  /** true when the Terrarium is on in this build */
+  export const enabled: boolean;
+  /** the mount, or null when the Terrarium is off: `{TerrariumMount && <TerrariumMount />}` */
+  const TerrariumMount: ComponentType<{ children?: ReactNode }> | null;
+  export default TerrariumMount;
+}

package/src/vite-plugin.js

@@ -4,12 +4,20 @@ import { mkdirSync, writeFileSync } from 'node:fs';
 import { join, relative, resolve, sep } from 'node:path';
 import { loadEnv } from 'vite';
 
-/** Injects the Terrarium (chain in a Worker + EIP-6963 wallet + dev bar) into index.html as a separate module script.
- *  The dapp's source is untouched: remove the plugin, or set VITE_TERRARIUM=off, and nothing of it is built.
+/** the virtual module a React app imports its mount from when `mount: 'react'` */
+export const REACT_MOUNT_ID = 'virtual:terrarium/react';
+const REACT_MOUNT_OFF = '\0terrarium/react-off';
+
+/** Injects the Terrarium (chain in a Worker + EIP-6963 wallet + dev bar) into the page.
+ *  Default: one module script added to index.html; the dapp's source is untouched. `mount: 'react'`: nothing is injected
+ *  and the app imports `TerrariumMount` from 'virtual:terrarium/react' and renders it at its root (a `@terrariumlabs/react`
+ *  <Terrarium> over the generated Worker); when the Terrarium is off that module exports null, so the app renders
+ *  nothing and bundles none of it. Remove the plugin, or set VITE_TERRARIUM=off, and nothing of it is built either way.
  *  @param {import('./vite-plugin.d.ts').TerrariumPluginOptions} [opts]
  *  @returns {import('vite').Plugin} */
 export function terrarium(opts = {}) {
-  let enabled = true;
+  let enabled = true, reactMount = null;
+  const react = opts.mount === 'react';
   return {
     name: 'terrarium',
     configResolved(config) {
@@ -18,12 +26,27 @@ export function terrarium(opts = {}) {
       const scenario = '/' + relative(config.root, resolve(config.root, opts.scenario ?? 'terrarium.scenario.ts')).split(sep).join('/');
       const dir = resolve(config.root, '.terrarium'); mkdirSync(dir, { recursive: true });
       writeFileSync(join(dir, 'worker.ts'), workerEntry(scenario));
-      writeFileSync(join(dir, 'inject.ts'), `import { startTerrarium } from '@terrariumlabs/core/inject';\nstartTerrarium(new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' }));\n`);
+      if (react) {
+        reactMount = join(dir, 'react.tsx');
+        writeFileSync(reactMount, reactMountEntry(opts.devBar));
+        config.logger.info(`[terrarium] React mount at ${REACT_MOUNT_ID} (scenario ${scenario})`);
+        return;
+      }
+      const start = opts.devBar === undefined ? '' : `, { devBar: ${JSON.stringify(opts.devBar)} }`;
+      writeFileSync(join(dir, 'inject.ts'), `import { startTerrarium } from '@terrariumlabs/core/inject';\nstartTerrarium(new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' })${start});\n`);
       config.logger.info(`[terrarium] injecting the simulated chain (scenario ${scenario})`);
     },
+    resolveId(source) {
+      if (source !== REACT_MOUNT_ID) return null;
+      return enabled && react ? reactMount : REACT_MOUNT_OFF;
+    },
+    load(id) {
+      if (id !== REACT_MOUNT_OFF) return null;
+      return 'export const enabled = false;\nexport default null;\n';
+    },
     transformIndexHtml: {
       order: 'pre',
-      handler(html) { return enabled ? { html, tags: [{ tag: 'script', attrs: { type: 'module', src: '/.terrarium/inject.ts' }, injectTo: 'body' }] } : html; },
+      handler(html) { return enabled && !react ? { html, tags: [{ tag: 'script', attrs: { type: 'module', src: '/.terrarium/inject.ts' }, injectTo: 'body' }] } : html; },
     },
   };
 }
@@ -31,3 +54,15 @@ export function terrarium(opts = {}) {
 /** the Worker entry: the user's scenario + the runtime (also used by the CLI's standalone build)
  *  @param {string} scenarioImport */
 export const workerEntry = (scenarioImport) => `import scenario from '${scenarioImport}';\nimport { runScenario } from '@terrariumlabs/core/worker';\nrunScenario(scenario);\n`;
+
+/** the generated React mount: a <Terrarium> over the generated Worker, with the plugin's devBar option baked in
+ *  @param {boolean | 'hidden' | undefined} devBar */
+export const reactMountEntry = (devBar) => `import { createElement, type ReactNode } from 'react';
+import { Terrarium } from '@terrariumlabs/react';
+export const enabled = true;
+/** the Terrarium mounted from the React tree: render once at the root, with the app as its children (they render once
+ *  the wallet is announced, so a wallet library that reconnects during its first render finds it) */
+export default function TerrariumMount({ children }: { children?: ReactNode } = {}) {
+  return createElement(Terrarium, { worker: () => new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' }), defer: true${devBar === undefined ? '' : `, devBar: ${JSON.stringify(devBar)}`} }, children);
+}
+`;

package/src/worker-runtime.ts

@@ -1,20 +1,37 @@
 // worker-runtime.ts — runs a scenario inside the Worker: boot the chain, run setup(), wire the actors, expose the
 // generic terrarium_* controls, and serve the provider to the page over postMessage.
-import { createPublicClient, createWalletClient, custom, defineChain, decodeErrorResult, decodeEventLog, decodeFunctionData, toHex, type Abi, type Address, type Hex } from 'viem';
+import { createPublicClient, createWalletClient, custom, defineChain, decodeErrorResult, decodeEventLog, decodeFunctionData, toEventSelector, toHex, type Abi, type Address, type Hex } from 'viem';
+import { KNOWN_ABI } from './known-abi.ts';
 // @ts-ignore — the engine is plain ESM JavaScript
 import { createTerrarium, indexedDBStorage } from './engine.js';
 import { serveProvider } from './bridge.ts';
 import { runRoute, toWire } from './http.ts';
-import type { ScenarioConfig, ScenarioContext } from './scenario.ts';
+import type { Actor, ScenarioConfig, ScenarioContext, ScenarioInput } from './scenario.ts';
 
-export async function runScenario(config: ScenarioConfig) {
+type Storage = { getItem(k: string): Promise<any>; setItem(k: string, v: any): Promise<any>; removeItem(k: string): Promise<any>; clear(): Promise<any> };
+const SELECTION_KEY = 'terrarium:scenario';
+const slug = (s: string) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '') || 'scenario';
+const nameOf = (s: ScenarioConfig, i: number) => s.name ?? `Scenario ${i + 1}`;
+
+/** Boot one scenario, or the active one of a list (the dev bar's selector picks; the choice is stored so a reload keeps it).
+ *  `opts.storage` replaces IndexedDB (tests). */
+export async function runScenario(input: ScenarioInput, opts: { storage?: Storage } = {}) {
+  const list = Array.isArray(input) ? input : [input];
+  if (!list.length) throw new Error('runScenario: no scenario');
+  const names = list.map(nameOf);
+  const anyPersist = list.some((s) => s.persist !== false);
+  const store: Storage | null = opts.storage ?? (anyPersist ? indexedDBStorage('terrarium') : null);
+  const selected = list.length > 1 && store ? await store.getItem(SELECTION_KEY) : null;
+  const index = Math.max(0, names.indexOf(selected));
+  const config = list[index], scenarioName = names[index];
   const chainId = config.chainId ?? 31337;
   // the page learns what to intercept before the chain boots, so the dapp's first fetches are not held up by setup()
   const httpRoutes = toWire(config.http ?? []);
   if (typeof (globalThis as any).postMessage === 'function') (globalThis as any).postMessage({ event: 'httpRoutes', payload: httpRoutes });
   let httpHits = 0;
-  const key = config.persist === false ? null : (config.persist ?? 'default');
-  const storage = key ? indexedDBStorage('terrarium') : null;
+  // a listed scenario persists under its own slug unless it says otherwise, so switching back finds its chain again
+  const key = config.persist === false ? null : (config.persist ?? (list.length > 1 ? slug(scenarioName) : 'default'));
+  const storage = key ? store : null;
   const firstBoot = storage ? (await storage.getItem(key!)) === null : true;
   const restore = typeof config.restore === 'function' ? await config.restore() : config.restore;
   const bootWall = Math.floor(Date.now() / 1000);
@@ -24,6 +41,8 @@ export async function runScenario(config: ScenarioConfig) {
   const chain = defineChain({ id: chainId, name: 'Terrarium', nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 }, rpcUrls: { default: { http: [] } } });
   const pub = createPublicClient({ chain, transport: custom(sim.provider), pollingInterval: 20 });
   const rpc = (method: string, params: unknown[] = []) => sim.provider.request({ method, params });
+  // what the explorer knows about addresses: a name and/or an ABI, from ctx.label() and from install()'s fixture keys
+  const registry = new Map<string, { name?: string; auto?: boolean; abi?: Abi }>();
   const ctx: ScenarioContext = {
     sim, chainId, rpc, pub,
     accounts: sim.accounts.map((a: any) => a.address as Address),
@@ -34,56 +53,98 @@ export async function runScenario(config: ScenarioConfig) {
     fresh: sim.blockNumber === 0n,
     firstBoot,
     codeAt: async (a) => (await rpc('eth_getCode', [a, 'latest'])) as Hex,
-    install: async (fixture) => { for (const c of Object.values(fixture.contracts)) if ((await ctx.codeAt(c.address as Address)) === '0x') await rpc('anvil_setCode', [c.address, c.code]); },
+    install: async (fixture: any) => {
+      // names and ABIs the fixture carries (import-anvil --broadcast/--artifacts, or written by hand): the explorer uses them
+      for (const [a, name] of Object.entries((fixture?.names ?? {}) as Record<string, string>)) { const k = a.toLowerCase(); registry.set(k, { ...registry.get(k), name, auto: true }); }
+      for (const [a, abi] of Object.entries((fixture?.abis ?? {}) as Record<string, Abi>)) { const k = a.toLowerCase(); registry.set(k, { ...registry.get(k), abi }); }
+      // an Anvil state dump (`terrarium import-anvil`, or anvil_dumpState by hand): whole accounts, code and storage,
+      // through anvil_loadState. Idempotent like the code fixtures: an account that already has code is left alone, and
+      // accounts without code (the deployer's nonce, funded EOAs) are only written on a fresh chain.
+      if (fixture?.accounts && !fixture.contracts) {
+        const accounts: Record<string, any> = {};
+        for (const [a, acct] of Object.entries(fixture.accounts as Record<string, any>)) {
+          if (!acct) continue;
+          const hasCode = acct.code && acct.code !== '0x';
+          if (hasCode ? (await ctx.codeAt(a as Address)) === '0x' : ctx.fresh) accounts[a] = acct;
+        }
+        if (Object.keys(accounts).length) await rpc('anvil_loadState', [{ accounts }]);
+        return;
+      }
+      for (const [key, c] of Object.entries(fixture.contracts) as [string, any][]) {
+        const k = c.address.toLowerCase(); if (!registry.get(k)?.name) registry.set(k, { ...registry.get(k), name: key, auto: true });   // the explorer names it by its fixture key
+        if ((await ctx.codeAt(c.address as Address)) === '0x') await rpc('anvil_setCode', [c.address, c.code]);
+      }
+    },
+    label: (address, name, abi) => { const k = address.toLowerCase(); registry.set(k, { ...registry.get(k), name, auto: false, ...(abi ? { abi } : {}) }); },
+    // the page reloads (a scenario that reset the chain, or rebuilt it, wants the dapp to start over on the new state)
+    reload: () => { if (typeof (globalThis as any).postMessage === 'function') (globalThis as any).postMessage({ event: 'reload', payload: null }); },
     state: {},
   };
   await config.setup?.(ctx);
   if (ctx.fresh && storage) await sim.flush();
 
-  // ---- actors: toggled together, persisted, off by default ----------------------------------------------------
+  // ---- actors: toggled together, persisted, off by default; `always` actors run regardless (keepers the protocol needs) ---
+  const wire = (a: Actor) => {
+    const safe = (log?: any) => Promise.resolve().then(() => a.run(ctx, log)).catch((e) => console.warn(`[terrarium] actor ${a.name ?? ''} failed:`, e?.message ?? e));
+    const out: (() => void)[] = [];
+    if (a.every) { const t = setInterval(() => safe(), a.every); out.push(() => clearInterval(t)); }
+    if (a.on) out.push(sim.onLog(typeof a.on === 'function' ? a.on(ctx) : a.on, (log: any) => safe(log)));
+    return out;
+  };
+  const toggled = (config.actors ?? []).filter((a) => !a.always);
+  for (const a of (config.actors ?? []).filter((a) => a.always)) wire(a);
   const actorsKey = `${key}:actors`;
-  let timers: ReturnType<typeof setInterval>[] = [], unsubs: (() => void)[] = [];
+  let unsubs: (() => void)[] = [];
   const actors = {
     enabled: storage ? (await storage.getItem(actorsKey)) === 'on' : false,
     async toggle(on: boolean) {
       actors.enabled = on; await storage?.setItem(actorsKey, on ? 'on' : 'off');
-      timers.forEach(clearInterval); timers = []; unsubs.forEach((u) => u()); unsubs = [];
+      unsubs.forEach((u) => u()); unsubs = [];
       if (!on) return;
-      for (const a of config.actors ?? []) {
-        const safe = (log?: any) => Promise.resolve().then(() => a.run(ctx, log)).catch((e) => console.warn(`[terrarium] actor ${a.name ?? ''} failed:`, e?.message ?? e));
-        if (a.every) timers.push(setInterval(() => safe(), a.every));
-        if (a.on) unsubs.push(sim.onLog(typeof a.on === 'function' ? a.on(ctx) : a.on, (log: any) => safe(log)));
-      }
+      for (const a of toggled) unsubs.push(...wire(a));
     },
   };
   if (actors.enabled) await actors.toggle(true);
 
   // ---- generic controls, reachable through the provider like any RPC method -----------------------------------
   sim.addMethod('terrarium_actors', async (on?: boolean) => { await actors.toggle(on ?? !actors.enabled); return actors.enabled; });
-  sim.addMethod('terrarium_status', async () => ({ chainId, engine: sim.engine, block: toHex(sim.blockNumber), accounts: ctx.accounts, actors: actors.enabled, actorsLabel: config.actorsLabel ?? 'Actors', hasActors: (config.actors?.length ?? 0) > 0, wallet: { ...sim.wallet }, controls: config.controls ?? [], restoredFromPersistence: sim.restoredFromPersistence, localBlocks: Number(sim.blockNumber) - (config.fork ? config.fork.blockNumber + 1 : 0), http: { routes: httpRoutes.length, hits: httpHits }, fork: config.fork ? { blockNumber: config.fork.blockNumber, offline: !!config.fork.offline, misses: sim.offlineMisses.length } : null, ...(await config.status?.(ctx)) }));
-  // ---- the transaction explorer: the engine's list, decoded with the scenario's ABIs and labelled -------------------
-  const abi = (config.abis ?? []).flat() as Abi;
+  sim.addMethod('terrarium_status', async () => ({ scenario: scenarioName, chainId, engine: sim.engine, block: toHex(sim.blockNumber), now: toHex(sim.now()), txs: (({ total, pending, failed }) => ({ total, pending, failed }))(sim.transactions({ limit: 0 })), accounts: ctx.accounts, actors: actors.enabled, actorsLabel: config.actorsLabel ?? 'Actors', hasActors: toggled.length > 0, wallet: { ...sim.wallet }, controls: config.controls ?? [], restoredFromPersistence: sim.restoredFromPersistence, localBlocks: Number(sim.blockNumber) - (config.fork ? config.fork.blockNumber + 1 : 0), http: { routes: httpRoutes.length, hits: httpHits }, fork: config.fork ? { blockNumber: config.fork.blockNumber, offline: !!config.fork.offline, misses: sim.offlineMisses.length } : null, ...(await config.status?.(ctx)) }));
+  // ---- the transaction explorer: the engine's list, decoded (address's own ABI, then `abis`, then the known set) and labelled
+  const configAbi = (config.abis ?? []).flat() as Abi;
+  const abisFor = (address: string | null): Abi[] => [registry.get((address ?? '').toLowerCase())?.abi, configAbi, KNOWN_ABI].filter((a): a is Abi => !!a && a.length > 0);
   const labelsOf = () => {
     const out: Record<string, string> = {};
-    ctx.accounts.forEach((a, i) => { out[a.toLowerCase()] = `Account #${i}`; });
-    const own = typeof config.labels === 'function' ? config.labels(ctx) : config.labels ?? {};
-    for (const [a, name] of Object.entries(own)) if (a) out[a.toLowerCase()] = name;
+    ctx.accounts.forEach((a, i) => { out[a.toLowerCase()] = i === 0 ? 'You (#0)' : `Account #${i}`; });   // accounts[0] is the browser user
+    for (const [a, e] of registry) if (e.name && e.auto) out[a] = e.name;                            // fixture keys
+    for (const [a, name] of Object.entries(config.labels ?? {})) if (a) out[a.toLowerCase()] = name;   // the config
+    for (const [a, e] of registry) if (e.name && !e.auto) out[a] = e.name;                           // ctx.label() wins
     return out;
   };
   const plain = (v: any): any => typeof v === 'bigint' ? v.toString() : Array.isArray(v) ? v.map(plain) : v && typeof v === 'object' ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, plain(x)])) : v;
-  const attempt = <T,>(fn: () => T): T | null => { try { return fn(); } catch { return null; } };
+  const first = <T,>(items: readonly any[], fn: (item: any) => T | null): T | null => { for (const item of items) { try { const r = fn(item); if (r) return r; } catch {} } return null; };
+  const decodeCall = (to: string, data: Hex) => first(abisFor(to), (abi: Abi) => { const d = decodeFunctionData({ abi, data }); return { name: d.functionName, args: plain(d.args ?? []) }; });
+  const decodeRevert = (to: string | null, data: Hex) => first(abisFor(to), (abi: Abi) => { const d = decodeErrorResult({ abi, data }); return { name: d.errorName, args: plain(d.args ?? []) }; });
+  // events: every candidate with the log's topic0 is tried (ERC-20 and ERC-721 Transfer share it and differ in indexed params)
+  const decodeLog = (l: { address: string; topics: Hex[]; data: Hex }) => first(abisFor(l.address), (abi: Abi) => first(abi.filter((i) => i.type === 'event' && toEventSelector(i as any) === l.topics[0]), (item: any) => { const d: any = decodeEventLog({ abi: [item], data: l.data, topics: l.topics as [Hex, ...Hex[]] }); return { name: d.eventName as string, args: plain(d.args ?? {}) }; }));
   sim.addMethod('terrarium_transactions', (opts?: { limit?: number; before?: string }) => {
-    const { total, transactions } = sim.transactions(opts ?? {});
-    const labels = labelsOf();
-    return { total, labels, transactions: transactions.map((t: any) => {
-      const call = t.to && t.input && t.input.length >= 10 && abi.length ? attempt(() => decodeFunctionData({ abi, data: t.input })) : null;
-      const method = !t.to ? { name: 'create', args: [] } : call ? { name: call.functionName, args: plain(call.args ?? []) } : t.input && t.input.length >= 10 ? { name: null, selector: t.input.slice(0, 10) } : null;
-      const revert = t.status === 'reverted' && t.revertData && t.revertData !== '0x' ? attempt(() => { const d = decodeErrorResult({ abi, data: t.revertData }); return { name: d.errorName, args: plain(d.args ?? []) }; }) : null;
-      const logs = (t.receipt?.logs ?? []).map((l: any) => { const d = abi.length ? attempt(() => decodeEventLog({ abi, data: l.data, topics: l.topics })) : null; return { ...l, decoded: d ? { name: d.eventName, args: plain(d.args ?? {}) } : null }; });
+    const { total, pending, failed, transactions } = sim.transactions(opts ?? {});
+    return { total, pending, failed, labels: labelsOf(), transactions: transactions.map((t: any) => {
+      const hasData = t.input && t.input.length >= 10;
+      const method = !t.to ? { name: 'create', args: [] } : hasData ? decodeCall(t.to, t.input) ?? { name: null, selector: t.input.slice(0, 10) } : null;
+      const revert = t.status === 'reverted' && t.revertData && t.revertData !== '0x' ? decodeRevert(t.to, t.revertData) : null;
+      const logs = (t.receipt?.logs ?? []).map((l: any) => ({ ...l, decoded: decodeLog(l) }));
       return { ...t, method, revert, logs };
     }) };
   });
-  sim.addMethod('terrarium_reset', async () => { await actors.toggle(false); sim.stop(); await storage?.clear(); return true; });
+  // reset wipes this scenario's chain (its key and its actors flag); other scenarios and the selection stay
+  sim.addMethod('terrarium_reset', async () => { await actors.toggle(false); sim.stop(); if (storage && key) { await storage.removeItem(key); await storage.removeItem(actorsKey); } return true; });
+  // several scenarios: the list for the selector, and the switch (stored, then the page reloads and boots the chosen one)
+  sim.addMethod('terrarium_scenarios', () => ({ active: scenarioName, scenarios: list.map((s, i) => ({ name: names[i], description: s.description ?? null, persist: s.persist === false ? null : (s.persist ?? (list.length > 1 ? slug(names[i]) : 'default')) })) }));
+  sim.addMethod('terrarium_selectScenario', async (name: string) => {
+    if (!names.includes(name)) throw new Error(`no scenario named ${JSON.stringify(name)}; have: ${names.join(', ')}`);
+    if (name !== scenarioName) { await store?.setItem(SELECTION_KEY, name); await actors.toggle(false); sim.stop(); ctx.reload(); }
+    return name;
+  });
   for (const [name, fn] of Object.entries(config.methods ?? {})) sim.addMethod(name, (...args: any[]) => fn(ctx, ...args));
 
   // ---- HTTP routes: the page's fetch forwards matching requests here; the handler answers from the chain --------------