@terrariumlabs/core 0.3.0 → 0.5.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.3.0",
+  "version": "0.5.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",
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "bin": {
-    "terrarium": "./bin/terrarium.mjs"
+    "terrarium": "bin/terrarium.mjs"
   },
   "exports": {
     ".": "./src/engine.js",
@@ -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.3.0"
+    "@terrariumlabs/evm": "^0.5.0"
   },
   "peerDependencies": {
     "viem": "^2.0.0",

package/src/devbar.ts

@@ -1,21 +1,78 @@
 // 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.
+// on top of any dapp (React or not) and never touches the dapp's code. Three 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`), and the
+// scenario selector (`terrarium_scenarios` / `terrarium_selectScenario`) when the Worker runs a list of scenarios.
 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 .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] { display: none; }
+#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 { 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 .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); }
+#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; }
+#terrarium-devbar 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.6); }
+#terrarium-devbar button.quiet:hover { color: #fff; background: rgba(255,255,255,0.08); }
+#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-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 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 { background: rgba(255,255,255,0.08); border: 1px solid rgba(255,255,255,0.14); color: #fff; padding: 3px 6px; border-radius: 6px; font: inherit; }
+#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: 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 .name { color: #e8c547; }
+#terrarium-explorer .dim { color: rgba(223,233,227,0.55); }
+#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; }
+#terrarium-explorer .events li { padding: 6px 0 6px 10px; border-left: 2px solid rgba(232,197,71,0.5); margin-bottom: 4px; word-break: break-all; }
+#terrarium-explorer .args { color: #dfe9e3; }
+#terrarium-explorer .empty { padding: 24px; text-align: center; color: rgba(223,233,227,0.55); font: 13px ui-sans-serif, system-ui, sans-serif; }
 `;
 
-export function mountDevBar(provider: Provider) {
+const esc = (s: unknown) => String(s ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]!);
+const short = (h: string) => (h && h.length > 14 ? `${h.slice(0, 8)}…${h.slice(-6)}` : h);
+const num = (hex: string | null | undefined) => (hex ? BigInt(hex).toString() : '');
+/** wei (hex) as ETH with up to 6 decimals, trailing zeros trimmed */
+export const formatEth = (hex: string | null | undefined) => {
+  if (!hex) return '0';
+  const wei = BigInt(hex), whole = wei / 10n ** 18n, frac = (wei % 10n ** 18n).toString().padStart(18, '0').slice(0, 6).replace(/0+$/, '');
+  return frac ? `${whole}.${frac}` : whole.toString();
+};
+/** wei (hex) as gwei with up to 3 decimals */
+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() : '');
+
+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');
@@ -23,47 +80,157 @@ export function mountDevBar(provider: Provider) {
   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)}">${label}</button>`); b.onclick = () => Promise.resolve(onClick()).catch((e) => console.warn('[terrarium]', e)); return b; };
+  const group = (label: string, testid: string, ...children: HTMLElement[]) => { const g = el(`<div class="group" data-testid="${testid}"><span class="glabel">${label}</span></div>`); g.append(...children); return g; };
 
-  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>`);
+  // ---- 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" 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 = () => rpc('terrarium_selectScenario', [scenarioSelect.value]).catch((e) => console.warn('[terrarium]', e));
+  const status = el(`<span class="status">block <b data-testid="block" data-f="block">…</b> · chain <span data-f="chain">…</span><span data-f="engine"></span></span>`);
+
+  // ---- chain ------------------------------------------------------------------------------------------------------------
   let mining: 'auto' | 'interval' = 'auto', snap: string | null = null;
   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');
   });
   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]); snap = null; bSnap.textContent = 'Snapshot'; bSnap.classList.remove('on'); }
+    else { snap = await rpc('evm_snapshot'); bSnap.textContent = 'Revert to snapshot'; bSnap.classList.add('on'); }
   });
-  const bActors = btn('Actors off', 'actors', 'Scripted actors: other users, keepers, arbitrageurs trading on their own', () => rpc('terrarium_actors'));
+  const gChain = group('chain', 'group-chain',
+    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);
+
+  // ---- 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', () => 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 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', () => rpc('terrarium_actors'));
   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, bReset);
-  document.body.append(bar);
-  document.body.style.paddingBottom = '64px';
+  const gScenario = group('scenario', 'group-scenario', bActors, controls);
 
+  // ---- the transaction explorer -----------------------------------------------------------------------------------------
+  const panel = el(`<section id="terrarium-explorer" data-testid="explorer" hidden></section>`);
+  const open = new Set<string>();   // expanded rows, by hash, kept across refreshes
+  let lastRender = '', filter: 'all' | 'mine' | 'failed' = 'all', 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', 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`; };
+  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 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], filter, me]);
+    if (key === lastRender) return; lastRender = key;
+    const L = data.labels ?? {};
+    const shown = data.transactions.filter((t) => filter === 'all' ? true : filter === 'failed' ? t.status !== 'success' && t.status !== 'pending' : !!me && t.from?.toLowerCase() === me.toLowerCase());
+    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>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>
+        <dt>to</dt><dd>${t.to ? `${who(L, t.to)} <span class="dim">${esc(t.to)}</span>` : `<span class="dim">created</span> ${esc(t.receipt?.contractAddress ?? '')}`}</dd>
+        <dt>value</dt><dd>${formatEth(t.value)} ETH</dd>
+        <dt>nonce</dt><dd>${num(t.nonce)}</dd>
+        <dt>gas</dt><dd>${t.receipt ? `${num(t.receipt.gasUsed)} used` : ''} of ${num(t.gas)} limit${t.receipt ? ` · ${esc(formatGwei(t.receipt.effectiveGasPrice))} gwei/gas · fee ${esc(formatEth('0x' + (BigInt(t.receipt.gasUsed) * BigInt(t.receipt.effectiveGasPrice)).toString(16)))} ETH` : ''}</dd>
+        <dt>input</dt><dd>${t.method?.name ? `<span class="name">${esc(t.method.name)}</span>(<span class="args">${esc(fmtArgs(t.method.args))}</span>)<br>` : ''}<span class="dim">${esc(t.input === '0x' ? '0x (no data)' : t.input)}</span></dd>
+        ${t.revertData && t.revertData !== '0x' ? `<dt>revert data</dt><dd class="dim">${esc(t.revertData)}</dd>` : ''}
+      </dl>
+      ${t.logs?.length ? `<ul class="events" data-testid="tx-events">${t.logs.map((l: any) => `<li><span class="dim">#${num(l.logIndex)}</span> ${who(L, l.address)} ${l.decoded ? `<span class="name">${esc(l.decoded.name)}</span>(<span class="args">${esc(fmtArgs(l.decoded.args))}</span>)` : `<span class="dim">topics ${l.topics.map(esc).join(' ')}<br>data ${esc(l.data)}</span>`}</li>`).join('')}</ul>` : `<div class="dim" style="margin-top:8px">no events</div>`}
+      </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>${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})` : ''}${filter !== 'all' ? `, ${shown.length} ${filter === 'mine' ? 'from you' : 'failed'}` : ''}</span>
+      <select data-testid="tx-filter" 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</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">${data.total ? 'Nothing matches this filter.' : 'No transactions yet. Do something in the dapp and it appears here.'}</div>`);
+    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('click', (e) => {
+    const row = (e.target as HTMLElement).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); };
+
+  // ---- reset, hide / show -------------------------------------------------------------------------------------------------
+  const bReset = btn('Reset', 'reset', 'Wipe this scenario\'s chain and boot it again from scratch', async () => { 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" hidden>🌱</button>`);
+  const remember = (hidden: boolean) => { try { localStorage.setItem(HIDDEN_KEY, hidden ? '1' : '0'); } 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 ? '' : '56px';
+    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));
+  bHide.classList.add('quiet');
+  pill.onclick = () => setHidden(false);
+  const gTools = group('', 'group-tools', bTxs, bReset, bHide);
+
+  bar.append(brand, status, el('<span class="spacer"></span>'), gChain, gWallet, gScenario, gTools, panel);
+  document.body.append(bar, pill);
+  let startHidden = !!opts.hidden; try { const v = localStorage.getItem(HIDDEN_KEY); if (v !== null) startHidden = v === '1'; } catch {}
+  bar.hidden = startHidden; pill.hidden = !startHidden; document.body.style.paddingBottom = startHidden ? '' : '56px';   // apply without remembering: the default is not a choice
+
+  // ---- 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 () => {
     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;
+    status.querySelector('[data-f=chain]')!.textContent = String(s.chainId);
+    status.querySelector('[data-f=block]')!.textContent = String(parseInt(s.block, 16));
+    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.length ? ' · ' + notes.join(' · ') : '';
+    status.title = `revm/wasm · the chain persists in IndexedDB${s.restoredFromPersistence ? ' (Reset to start clean)' : ''}`;
     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 ?? [])))); }
     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 (!panel.hidden) { await refreshTxs(); place(); }
   };
-  refresh(); setInterval(refresh, 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. */
+export function unmountDevBar() {
+  document.getElementById('terrarium-devbar')?.remove();
+  document.getElementById('terrarium-devbar-show')?.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 */
@@ -364,11 +364,12 @@ export async function createTerrarium(opts = {}) {
           r = await exec({ tx: entry.tx, block, flags: { blockGasUsed: cumulative } });
         } catch (e) { // invalid tx (nonce too low, insufficient funds...): a node would drop it silently and the dapp
           // would wait for a receipt forever. Record a failed receipt instead so waiters resolve and the reason is visible.
-          const t = txs.get(entry.hash); t.error = String(e.message);
+          const t = txs.get(entry.hash); t.error = String(e.message); t.dropped = true;
           receipts.push({ transactionHash: entry.hash, transactionIndex: hex(idx), from: entry.from, to: entry.rpc.to, cumulativeGasUsed: hex(cumulative), gasUsed: '0x0', effectiveGasPrice: hex(baseFee), contractAddress: null, logs: [], logsBloom: '0x' + '00'.repeat(256), status: '0x0', type: '0x2', droppedReason: t.error });
           hashes.push(entry.hash); sealTxs.push(entry.tx); sealReceipts.push({ status: 0, cumulativeBlockGasUsed: cumulative, bitvector: new Uint8Array(256), logs: [] }); continue;
         }
         cumulative += r.gasUsed;
+        if (!r.success) { const t = txs.get(entry.hash); t.error = r.error ?? 'execution reverted'; t.revertData = bytesToHex(r.returnValue); }
         if (globalThis.process?.env?.TERRARIUM_DEBUG && !r.success) console.log('[tx reverted]', entry.hash, r.error, bytesToHex(r.returnValue), 'gasUsed', r.gasUsed, 'gasLimit', entry.tx.gasLimit);
         const bloom = bloomOf(r.logs);
         const logs = r.logs.map(([addr, topics, data]) => ({ address: bytesToHex(addr), topics: topics.map(bytesToHex), data: bytesToHex(data), blockNumber: hex(header.number), transactionHash: entry.hash, transactionIndex: hex(idx), logIndex: hex(logIndex++), removed: false }));
@@ -447,6 +448,19 @@ export async function createTerrarium(opts = {}) {
     return hi;
   }
 
+  /** Transactions newest first, as an explorer lists them: the RPC tx merged with its receipt, a `status` word, the
+   *  revert reason and data of a failed one, and the block timestamp. Pending (interval mining) come first. */
+  function listTransactions({ limit = 50, before } = {}) {
+    const all = [...txs.values()].reverse().map((t) => {
+      const mined = !!t.receipt, n = mined ? hexToBigInt(t.receipt.blockNumber) : null;
+      const b = mined ? blocks.find((b) => BigInt(b.number) === n) : null;
+      const status = !mined ? 'pending' : t.receipt.status === '0x1' ? 'success' : t.dropped ? 'dropped' : 'reverted';
+      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)) };
+  }
+
   // ---- RPC formatting ----------------------------------------------------------------------------
   function rpcBlock(b, full) {
     const transactions = full ? b.transactions.map((h) => txs.get(h).rpc) : b.transactions;
@@ -540,6 +554,7 @@ export async function createTerrarium(opts = {}) {
         case 'eth_sendRawTransaction': { const tx = createTxFromRLP(hexToBytes(params[0]), { common }); return submit(tx, tx.getSenderAddress().toString()); }
         case 'eth_getTransactionReceipt': { const t = txs.get(params[0]); if (!t?.receipt) return null; if (walletKnobs.receiptLagMs > 0 && Date.now() - (t.minedAt ?? 0) < walletKnobs.receiptLagMs) return null; return t.receipt; }
         case 'eth_getTransactionByHash': return txs.get(params[0])?.rpc ?? null;
+        case 'terrarium_transactions': return listTransactions(params[0] ?? {});
         case 'eth_getLogs': return getLogs(params[0] ?? {});
         case 'eth_newFilter': filters.set(hex(nextFilterId), { type: 'logs', f: params[0] ?? {}, cursor: latest().number + 1n }); return hex(nextFilterId++);
         case 'eth_newBlockFilter': filters.set(hex(nextFilterId), { type: 'blocks', cursor: latest().number + 1n }); return hex(nextFilterId++);
@@ -568,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;
@@ -694,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) });
@@ -706,7 +753,7 @@ export async function createTerrarium(opts = {}) {
     const remote = sm.remote ? { accounts: Object.fromEntries([...sm.remote.accounts].map(([a, acct]) => [a, acct ? { nonce: hex(acct.nonce), balance: hex(acct.balance), codeHash: bytesToHex(acct.codeHash) } : null])), code: Object.fromEntries([...sm.remote.code].map(([a, c]) => [a, bytesToHex(c)])), storage: Object.fromEntries([...sm.remote.storage].map(([k, v]) => [k, bytesToHex(v)])) } : undefined;
     return { version: 1, chainId, savedAt: Date.now(), state: { accounts: accountsOut, code: codeOut, storage: storageOut }, remote,
       // tx bodies: only the most recent blocks' worth (like a pruned node), and without their logs (rebuilt from block logs on load)
-      chain: { blocks: blocks.map(serBlock), txs: Object.fromEntries([...txs].filter(([, t]) => !t.receipt || hexToBigInt(t.receipt.blockNumber) >= keepFrom).map(([h, t]) => [h, { rpc: t.rpc, receipt: t.receipt ? { ...t.receipt, logs: undefined } : null, error: t.error }])), timeOffset: hex(timeOffset), baseFee: hex(baseFee), mining, impersonated: [...impersonated], dealtSlots: Object.fromEntries(dealtSlots) },
+      chain: { blocks: blocks.map(serBlock), txs: Object.fromEntries([...txs].filter(([, t]) => !t.receipt || hexToBigInt(t.receipt.blockNumber) >= keepFrom).map(([h, t]) => [h, { rpc: t.rpc, receipt: t.receipt ? { ...t.receipt, logs: undefined } : null, error: t.error, revertData: t.revertData, dropped: t.dropped }])), timeOffset: hex(timeOffset), baseFee: hex(baseFee), mining, impersonated: [...impersonated], dealtSlots: Object.fromEntries(dealtSlots) },
       journal: { entries: journal, timestamps: blocks.slice(1).map((b) => hex(b.timestamp)) } };
   }
   async function seedState({ accounts: accs = {}, code = {}, storage = {} }) {
@@ -763,6 +810,8 @@ 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: (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); },
     /** Cheat: send a tx "from" any address without keys (impersonation), e.g. to simulate another user. */

package/src/inject.ts

@@ -2,14 +2,15 @@
 // wallet (so the dapp's own connect modal lists "Terrarium Wallet") and mount the dev bar. Nothing here is imported by
 // the dapp; this is the analogue of a browser extension's injected script.
 import { createWorkerProvider } from './bridge.ts';
-import { mountDevBar } from './devbar.ts';
+import { mountDevBar, unmountDevBar } from './devbar.ts';
 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;
 }
 
@@ -38,7 +41,6 @@ export function stopTerrarium() {
   window.removeEventListener('eip6963:requestProvider', current.announce);
   current.worker.terminate();
   current = null;
-  document.getElementById('terrarium-devbar')?.remove();
-  document.body?.style.removeProperty('padding-bottom');
+  unmountDevBar();
   delete (window as any).terrarium;
 }

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

@@ -6,13 +6,16 @@
 //     actors: [{ every: 5000, run: (ctx) => ... }, { on: { address, topics }, run: (ctx, log) => ... }],
 //     status: (ctx) => ({ addresses: ctx.state }),
 //   });
-import type { Account, Address, Chain, Hex, PublicClient, TransactionReceipt, Transport, WalletClient } from 'viem';
+import type { Abi, Account, Address, Chain, Hex, PublicClient, TransactionReceipt, Transport, WalletClient } from 'viem';
 import type { HttpRoute } from './http.ts';
 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,6 +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[];
+  /** 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 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, toHex, 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,34 +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)) }));
-  sim.addMethod('terrarium_reset', async () => { await actors.toggle(false); sim.stop(); await storage?.clear(); return true; });
+  sim.addMethod('terrarium_status', async () => ({ scenario: scenarioName, chainId, engine: sim.engine, block: toHex(sim.blockNumber), 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()] = 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 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 ?? {});
+    return { total, 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 };
+    }) };
+  });
+  // 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 --------------