@terrariumlabs/core 0.3.0

package/src/http.ts

@@ -0,0 +1,217 @@
+// http.ts — answer the dapp's HTTP calls (REST APIs, subgraphs, indexers) from the chain in the Worker.
+//
+// A dapp rarely reads the chain alone: it asks a subgraph for the last swaps, a price API for USD values, its own
+// backend for a leaderboard. Inside the Terrarium there is no indexer, so those calls would go to the real internet and
+// describe a chain that is not the one in the page. A scenario declares `http` routes: which URLs to intercept and how
+// to answer them with data computed from the chain (ctx.pub, ctx.sim, logs). The page side patches `fetch` (like a
+// wallet extension or a Service Worker would; the dapp's code is untouched), matching requests are posted to the
+// Worker, the route's handler runs with the scenario context, and the page builds a real `Response` from the answer.
+// Everything else passes through to the network untouched.
+import type { ScenarioContext } from './scenario.ts';
+
+/** what a handler receives: a plain, serialisable view of the request */
+export interface HttpRequest {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  /** the raw body (null for GET / HEAD) */
+  body: string | null;
+  /** the body parsed as JSON, or null */
+  json: any;
+  /** the query string as an object */
+  query: Record<string, string>;
+}
+/** what a handler may return explicitly (see `reply`); anything else is serialised as JSON with status 200 */
+export interface HttpReply { __terrariumReply: true; status: number; headers: Record<string, string>; body: string }
+/** one top-level field of a GraphQL operation, as the `graphql` resolvers receive it */
+export interface GraphqlQuery {
+  /** the field name (`swaps`) and the alias the client wants it under (defaults to the name) */
+  field: string; alias: string;
+  /** the field's arguments with variables substituted: `{ first: 5, orderBy: 'timestamp', where: { pair: '0x…' } }` */
+  args: Record<string, unknown>;
+  /** the names of the sub-fields the client selected (one level): `['id', 'timestamp', 'amount0In']` */
+  selection: string[];
+  variables: Record<string, unknown>;
+  operationName: string | null;
+  /** the whole operation text, if you need more than this parser gives */
+  query: string;
+}
+export type GraphqlResolver = (ctx: ScenarioContext, q: GraphqlQuery) => unknown;
+
+export interface HttpRoute {
+  name?: string;
+  /** which requests: a URL prefix (`'https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2'`), a glob with `*`
+   *  (`'https://api.coingecko.com/api/v3/simple/price*'`), or a RegExp. Matched against the full URL. */
+  match: string | RegExp;
+  /** restrict to one HTTP method (default: any) */
+  method?: string;
+  /** answer the request: return JSON-serialisable data (→ 200 application/json; bigints become strings), a string
+   *  (→ 200 text/plain), or `reply(body, { status, headers })` for anything else */
+  handler?(ctx: ScenarioContext, req: HttpRequest): unknown;
+  /** ...or, for a GraphQL endpoint, one resolver per top-level query field. The runtime parses the operation, calls each
+   *  selected field's resolver with its arguments (variables substituted) and answers `{ data: { field: result } }`;
+   *  a missing resolver or a throwing one becomes a GraphQL `errors` entry, as a real server would answer.
+   *  With both `handler` and `graphql`, the handler runs first as a gate: return `undefined` to let the resolvers
+   *  answer, or a `reply(…, { status: 503 })` to take the whole endpoint down. */
+  graphql?: Record<string, GraphqlResolver>;
+}
+
+const JSON_HEADERS = { 'content-type': 'application/json' };
+export const toJson = (v: unknown) => JSON.stringify(v, (_, x) => (typeof x === 'bigint' ? x.toString() : x));
+
+/** an explicit HTTP answer: `reply({ error: 'indexer down' }, { status: 503 })`, `reply('<xml/>', { headers: { 'content-type': 'text/xml' } })` */
+export function reply(body: unknown, init: { status?: number; headers?: Record<string, string> } = {}): HttpReply {
+  const text = typeof body === 'string';
+  return { __terrariumReply: true, status: init.status ?? 200, headers: { ...(text ? { 'content-type': 'text/plain' } : JSON_HEADERS), ...init.headers }, body: text ? body : toJson(body) };
+}
+const isReply = (v: any): v is HttpReply => !!v && typeof v === 'object' && v.__terrariumReply === true;
+
+// ---- matching: the page needs to know what to intercept without asking the Worker for every fetch -----------------
+export type WireRoute = { index: number; name?: string; match: string | { regex: string; flags: string }; method?: string };
+export const toWire = (routes: HttpRoute[]): WireRoute[] => routes.map((r, index) => ({ index, name: r.name, method: r.method?.toUpperCase(), match: r.match instanceof RegExp ? { regex: r.match.source, flags: r.match.flags } : r.match }));
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** a string is a prefix (`https://api.example.com/v1/` matches every URL under it); `*` is a wildcard; a RegExp is itself */
+export function compileMatcher(w: WireRoute): (url: string, method: string) => boolean {
+  const re = typeof w.match === 'string'
+    ? (w.match.includes('*') ? new RegExp('^' + w.match.split('*').map(escapeRe).join('.*') + '$') : null)
+    : new RegExp(w.match.regex, w.match.flags);
+  const prefix = typeof w.match === 'string' && !re ? w.match : null;
+  return (url, method) => (!w.method || w.method === method.toUpperCase()) && (prefix !== null ? url.startsWith(prefix) : re!.test(url));
+}
+
+// ---- the Worker side: run a route ---------------------------------------------------------------------------------
+export async function runRoute(ctx: ScenarioContext, route: HttpRoute, raw: { url: string; method: string; headers?: Record<string, string>; body?: string | null }): Promise<Omit<HttpReply, '__terrariumReply'>> {
+  let json: any = null; try { json = raw.body ? JSON.parse(raw.body) : null; } catch { json = null; }
+  const query: Record<string, string> = {}; try { for (const [k, v] of new URL(raw.url).searchParams) query[k] = v; } catch { /* relative or odd URL: no query */ }
+  const req: HttpRequest = { url: raw.url, method: raw.method.toUpperCase(), headers: raw.headers ?? {}, body: raw.body ?? null, json, query };
+  let result: unknown;
+  if (route.graphql && route.handler) result = await route.handler(ctx, req);   // the gate
+  if (route.graphql && result === undefined) {
+    const source = req.json?.query ?? req.query.query ?? '';
+    let variables = req.json?.variables ?? {}; if (typeof variables === 'string') { try { variables = JSON.parse(variables); } catch { variables = {}; } }
+    if (!req.json?.variables && req.query.variables) { try { variables = JSON.parse(req.query.variables); } catch { variables = {}; } }
+    const operationName = req.json?.operationName ?? req.query.operationName ?? null;
+    const data: Record<string, unknown> = {}, errors: { message: string; path?: string[] }[] = [];
+    let ops: GraphqlQuery[] = [];
+    try { ops = parseGraphql(source, variables, operationName); }
+    catch (e: any) { const r = reply({ errors: [{ message: `Syntax Error: ${e?.message ?? e}` }] }, { status: 400 }); return { status: r.status, headers: r.headers, body: r.body }; }
+    for (const q of ops) {
+      const resolver = route.graphql[q.field];
+      if (!resolver) { data[q.alias] = null; errors.push({ message: `Type "Query" has no field "${q.field}"`, path: [q.alias] }); continue; }
+      try { data[q.alias] = await resolver(ctx, q); } catch (e: any) { data[q.alias] = null; errors.push({ message: String(e?.message ?? e), path: [q.alias] }); }
+    }
+    result = errors.length ? { data, errors } : { data };
+  } else if (!route.graphql && route.handler) result = await route.handler(ctx, req);
+  else if (!route.graphql) throw new Error(`http route ${route.name ?? route.match} has neither handler nor graphql`);
+  const r = isReply(result) ? result : reply(result === undefined ? null : result);
+  return { status: r.status, headers: r.headers, body: r.body };
+}
+
+// ---- a small GraphQL parser: the top-level fields of one operation, their arguments and selections ----------------
+type Tok = { t: 'punct' | 'name' | 'num' | 'str' | 'var'; v: string };
+function tokenize(src: string): Tok[] {
+  const out: Tok[] = []; let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    if (/\s|,/.test(c)) { i++; continue; }
+    if (c === '#') { while (i < src.length && src[i] !== '\n') i++; continue; }
+    if (src.startsWith('"""', i)) { const end = src.indexOf('"""', i + 3); if (end < 0) throw new Error('unterminated block string'); out.push({ t: 'str', v: src.slice(i + 3, end) }); i = end + 3; continue; }
+    if (c === '"') { let j = i + 1, s = ''; while (j < src.length && src[j] !== '"') { if (src[j] === '\\') { s += JSON.parse(`"${src.slice(j, j + (src[j + 1] === 'u' ? 6 : 2))}"`); j += src[j + 1] === 'u' ? 6 : 2; } else s += src[j++]; } if (j >= src.length) throw new Error('unterminated string'); out.push({ t: 'str', v: s }); i = j + 1; continue; }
+    if (c === '$') { const m = /^[_A-Za-z][_0-9A-Za-z]*/.exec(src.slice(i + 1)); if (!m) throw new Error('bad variable'); out.push({ t: 'var', v: m[0] }); i += 1 + m[0].length; continue; }
+    if (src.startsWith('...', i)) { out.push({ t: 'punct', v: '...' }); i += 3; continue; }
+    if ('{}()[]:!=@|&'.includes(c)) { out.push({ t: 'punct', v: c }); i++; continue; }
+    let m = /^-?\d+(\.\d+)?([eE][+-]?\d+)?/.exec(src.slice(i)); if (m) { out.push({ t: 'num', v: m[0] }); i += m[0].length; continue; }
+    m = /^[_A-Za-z][_0-9A-Za-z]*/.exec(src.slice(i)); if (m) { out.push({ t: 'name', v: m[0] }); i += m[0].length; continue; }
+    throw new Error(`unexpected character ${JSON.stringify(c)} at ${i}`);
+  }
+  return out;
+}
+/** Parse a GraphQL document and return the top-level fields of the selected operation (the first one, or `operationName`).
+ *  Arguments become plain values with variables substituted (and variable defaults applied); fragments are not expanded. */
+export function parseGraphql(source: string, variables: Record<string, unknown> = {}, operationName: string | null = null): GraphqlQuery[] {
+  const toks = tokenize(source); let p = 0;
+  const peek = () => toks[p], next = () => { if (p >= toks.length) throw new Error('unexpected end of query'); return toks[p++]; };
+  const expect = (v: string) => { const t = next(); if (t.t !== 'punct' || t.v !== v) throw new Error(`expected ${v}, got ${t.v}`); };
+  const skipBalanced = (open: string, close: string) => { expect(open); let depth = 1; while (depth) { const t = next(); if (t.t === 'punct' && t.v === open) depth++; else if (t.t === 'punct' && t.v === close) depth--; } };
+  const skipDirectives = () => { while (peek()?.t === 'punct' && peek().v === '@') { next(); next(); if (peek()?.t === 'punct' && peek().v === '(') skipBalanced('(', ')'); } };
+  const value = (vars: Record<string, unknown>): unknown => {
+    const t = next();
+    if (t.t === 'var') return vars[t.v];
+    if (t.t === 'num') return Number(t.v);
+    if (t.t === 'str') return t.v;
+    if (t.t === 'name') return t.v === 'true' ? true : t.v === 'false' ? false : t.v === 'null' ? null : t.v;   // enums stay strings
+    if (t.v === '[') { const a: unknown[] = []; while (!(peek().t === 'punct' && peek().v === ']')) a.push(value(vars)); next(); return a; }
+    if (t.v === '{') { const o: Record<string, unknown> = {}; while (!(peek().t === 'punct' && peek().v === '}')) { const k = next().v; expect(':'); o[k] = value(vars); } next(); return o; }
+    throw new Error(`unexpected ${t.v}`);
+  };
+  const args = (vars: Record<string, unknown>) => { const o: Record<string, unknown> = {}; if (!(peek()?.t === 'punct' && peek().v === '(')) return o; next(); while (!(peek().t === 'punct' && peek().v === ')')) { const k = next().v; expect(':'); o[k] = value(vars); } next(); return o; };
+  /** one level of field names inside { … }, skipping each field's own args, directives and nested selection */
+  const selectionNames = (): string[] => { const names: string[] = []; expect('{'); while (!(peek().t === 'punct' && peek().v === '}')) { const t = next(); if (t.t === 'punct' && t.v === '...') { if (peek().t === 'name' && peek().v === 'on') { next(); next(); } else if (peek().t === 'name') { next(); continue; } skipDirectives(); selectionNames(); continue; } let name = t.v; if (peek().t === 'punct' && peek().v === ':') { next(); name = next().v; } names.push(name); if (peek().t === 'punct' && peek().v === '(') skipBalanced('(', ')'); skipDirectives(); if (peek().t === 'punct' && peek().v === '{') selectionNames(); } next(); return names; };
+
+  // ---- definitions: pick the operation ----
+  type Op = { name: string | null; start: number; vars: Record<string, unknown> };
+  const ops: Op[] = [];
+  while (p < toks.length) {
+    const t = peek();
+    if (t.t === 'name' && t.v === 'fragment') { next(); next(); next(); next(); skipDirectives(); skipBalanced('{', '}'); continue; }
+    const vars: Record<string, unknown> = { ...variables }; let name: string | null = null;
+    if (t.t === 'name' && ['query', 'mutation', 'subscription'].includes(t.v)) {
+      next(); if (peek().t === 'name') name = next().v;
+      if (peek().t === 'punct' && peek().v === '(') {   // variable definitions: $x: Type! = default
+        next();
+        while (!(peek().t === 'punct' && peek().v === ')')) {
+          const v = next(); if (v.t !== 'var') throw new Error('expected a variable definition'); expect(':');
+          if (peek().t === 'punct' && peek().v === '[') skipBalanced('[', ']'); else next(); if (peek().t === 'punct' && peek().v === '!') next();
+          if (peek().t === 'punct' && peek().v === '=') { next(); const d = value({}); if (vars[v.v] === undefined) vars[v.v] = d; }
+          skipDirectives();
+        }
+        next();
+      }
+      skipDirectives();
+    } else if (!(t.t === 'punct' && t.v === '{')) throw new Error(`unexpected ${t.v}`);
+    ops.push({ name, start: p, vars }); skipBalanced('{', '}');
+  }
+  if (!ops.length) throw new Error('no operation in query');
+  const op = operationName ? ops.find((o) => o.name === operationName) : ops[0];
+  if (!op) throw new Error(`unknown operation "${operationName}"`);
+  // ---- its top-level fields ----
+  p = op.start; expect('{');
+  const fields: GraphqlQuery[] = [];
+  while (!(peek().t === 'punct' && peek().v === '}')) {
+    const t = next();
+    if (t.t === 'punct' && t.v === '...') { if (peek().t === 'name' && peek().v === 'on') { next(); next(); } else if (peek().t === 'name') { next(); continue; } skipDirectives(); skipBalanced('{', '}'); continue; }   // top-level fragments are not expanded
+    let field = t.v, alias = t.v;
+    if (peek().t === 'punct' && peek().v === ':') { next(); field = next().v; }
+    const a = args(op.vars); skipDirectives();
+    const selection = peek()?.t === 'punct' && peek().v === '{' ? selectionNames() : [];
+    fields.push({ field, alias, args: a, selection, variables: op.vars, operationName: op.name, query: source });
+  }
+  return fields;
+}
+
+// ---- the page side: patch fetch, forward matching requests to the Worker --------------------------------------------
+type Provider = { request(a: { method: string; params?: unknown[] }): Promise<any> };
+/** Replace `globalThis.fetch` with one that answers the scenario's routes from the Worker and passes everything else
+ *  through. `routes` resolves to the Worker's route list (it can take a moment: the first fetches wait for it).
+ *  Returns a function that restores the original fetch. */
+export function installHttpInterceptor(provider: Provider, routes: Promise<WireRoute[]>, scope: any = globalThis): () => void {
+  const realFetch: typeof fetch = scope.fetch.bind(scope);
+  const compiled = routes.then((rs) => rs.map((w) => ({ ...w, test: compileMatcher(w) })), () => []);
+  scope.fetch = async (input: any, init?: RequestInit) => {
+    const list = await compiled;
+    if (!list.length) return realFetch(input, init);
+    const req = input instanceof Request ? input.clone() : new Request(input, init);
+    const route = list.find((r) => r.test(req.url, req.method));
+    if (!route) return realFetch(input, init);
+    const body = req.method === 'GET' || req.method === 'HEAD' ? null : await req.text();
+    const headers: Record<string, string> = {}; req.headers.forEach((v, k) => { headers[k] = v; });
+    try {
+      const r = await provider.request({ method: 'terrarium_http', params: [route.index, { url: req.url, method: req.method, headers, body }] });
+      return new Response(r.body, { status: r.status, headers: r.headers });
+    } catch (e: any) {   // a bug in the scenario's handler: surface it as the failed API call it would be, and say so
+      console.warn(`[terrarium] http route ${route.name ?? route.index} failed:`, e?.message ?? e);
+      return new Response(toJson({ error: String(e?.message ?? e) }), { status: 500, headers: JSON_HEADERS });
+    }
+  };
+  return () => { scope.fetch = realFetch; };
+}

package/src/inject.ts

@@ -0,0 +1,44 @@
+// inject.ts — main-thread side, shared by the dev entry and the standalone bundle: wire the Worker up as an EIP-6963
+// 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 { 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;
+}
+let current: { worker: Worker; announce: () => void } | null = null;
+
+export function startTerrarium(worker: Worker, opts: StartOptions = {}) {
+  if (current) stopTerrarium();
+  const provider = createWorkerProvider(worker);
+  // the scenario's HTTP routes (subgraphs, APIs answered from the chain): the Worker announces them before it boots;
+  // 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);
+  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);
+  announce();
+  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); }
+  return provider;
+}
+
+/** Undo startTerrarium: stop announcing, terminate the Worker, remove the dev bar and window.terrarium. Used by hosts that
+ *  mount and unmount (React StrictMode runs effects twice; a Storybook story unmounts). */
+export function stopTerrarium() {
+  if (!current) return;
+  window.removeEventListener('eip6963:requestProvider', current.announce);
+  current.worker.terminate();
+  current = null;
+  document.getElementById('terrarium-devbar')?.remove();
+  document.body?.style.removeProperty('padding-bottom');
+  delete (window as any).terrarium;
+}

package/src/scenario.ts

@@ -0,0 +1,94 @@
+// scenario.ts — the declarative entry point: what runs inside the Worker when the Terrarium boots.
+//
+//   export default defineScenario({
+//     chainId: 31337, seed: 1337, persist: 'my-dapp',
+//     async setup(ctx) { await ctx.install(uniswap); if (ctx.fresh) { /* deploy + seed with ctx.wallet(...) */ } },
+//     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 { 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 LogFilter { address?: Address | Address[]; topics?: (Hex | Hex[] | null)[] }
+
+export interface ScenarioContext {
+  /** the engine itself: sim.deal, sim.setState, sim.sendAs, sim.onLog, sim.snapshot ... */
+  sim: any;
+  chainId: number;
+  /** the 10 Anvil test accounts, each with 10,000 ETH; the wallet exposes all of them */
+  accounts: Address[];
+  /** raw JSON-RPC against the chain (cheatcodes included) */
+  rpc(method: string, params?: unknown[]): Promise<any>;
+  /** viem clients wired to the chain */
+  pub: PublicClient;
+  wallet(account: Address): WalletClient<Transport, Chain, Account>;
+  wait(hash: Promise<Hex> | Hex): Promise<TransactionReceipt>;
+  /** a deadline from the CHAIN clock (never Date.now(): the dev bar can shift time) */
+  deadline(seconds?: number): bigint;
+  /** seeded PRNG: reproducible actors */
+  random(): number;
+  /** true when the chain has no blocks yet (first boot, or after a reset): deploy and seed only then */
+  fresh: boolean;
+  /** 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>;
+  /** a bag for whatever setup() discovers (addresses...) that actors and status() need later */
+  state: Record<string, any>;
+}
+
+export interface Actor {
+  name?: string;
+  /** run every N ms */
+  every?: number;
+  /** ...or run when a matching log is mined (a function, if the filter depends on setup() results) */
+  on?: LogFilter | ((ctx: ScenarioContext) => LogFilter);
+  run(ctx: ScenarioContext, log?: any): Promise<unknown> | unknown;
+}
+
+export interface ScenarioConfig {
+  chainId?: number;
+  /** seed for ctx.random() and the actors; omit for a fresh seed per boot */
+  seed?: number;
+  /** IndexedDB key the chain persists under; false = in-memory only */
+  persist?: string | false;
+  hardfork?: string;
+  /** 'merkle' (default): real stateRoot in every header. 'simple': flat maps, placeholder root. */
+  state?: 'merkle' | 'simple';
+  /** fork a live chain: state is read lazily from `url` at `blockNumber` (and recorded). `offline: true` forbids the
+   *  network: reads the fixture cannot answer throw and are listed in sim.offlineMisses. */
+  fork?: { url?: string; blockNumber: number; offline?: boolean };
+  /** the chain clock. 'wall' (default): the wall clock. 'recording': the wall clock re-based to the restored fixture's last
+   *  block, so oracles with staleness checks keep working however long ago the fixture was recorded. A number: fixed seconds
+   *  (blocks then advance one second at a time, plus whatever evm_increaseTime adds). */
+  clock?: 'wall' | 'recording' | number;
+  /** a recorded dump (sim.dumpState(), e.g. from a fork recording) used as the baseline when nothing is persisted yet */
+  restore?: Record<string, any> | (() => Promise<Record<string, any>>);
+  /** extra buttons for the dev bar: each calls one of your `methods` (or any RPC method) with fixed params */
+  controls?: { label: string; method: string; params?: unknown[]; title?: string }[];
+  /** 'exact' (geth-style estimation, default) or 'fast' (block gas limit, no estimation) */
+  gasEstimation?: 'exact' | 'fast';
+  /** how the wallet misbehaves, from the start (all changeable at runtime via terrarium_setWallet) */
+  wallet?: { rejectNext?: number; latencyMs?: number; receiptLagMs?: number };
+  /** runs on EVERY boot; use ctx.fresh to deploy/seed once, ctx.install for fixtures (idempotent) */
+  setup?(ctx: ScenarioContext): Promise<unknown> | unknown;
+  /** background actors: other users, keepers, arbitrageurs. Toggled together (dev bar / terrarium_actors), off by default. */
+  actors?: Actor[];
+  /** what the dev bar calls the actors toggle, e.g. "Pond life" */
+  actorsLabel?: string;
+  /** extra fields for terrarium_status (addresses, whatever the dev bar / tests want to know) */
+  status?(ctx: ScenarioContext): Promise<Record<string, unknown>> | Record<string, unknown>;
+  /** extra RPC methods, reachable through the provider: methods: { terrarium_faucet: (ctx, to) => ... } */
+  methods?: Record<string, (ctx: ScenarioContext, ...args: any[]) => unknown>;
+  /** HTTP calls of the dapp to answer from the chain (subgraphs, price APIs, your backend): the page's `fetch` is
+   *  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[];
+}
+
+export function defineScenario(config: ScenarioConfig): ScenarioConfig { return config; }

package/src/vite-plugin.d.ts

@@ -0,0 +1,13 @@
+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;
+}
+
+/** 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. */
+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;

package/src/vite-plugin.js

@@ -0,0 +1,33 @@
+// The Vite plugin. Plain JavaScript on purpose: Vite loads it in Node straight from the consumer's node_modules, where
+// Node refuses to strip types from .ts files (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING). Types live in vite-plugin.d.ts.
+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.
+ *  @param {import('./vite-plugin.d.ts').TerrariumPluginOptions} [opts]
+ *  @returns {import('vite').Plugin} */
+export function terrarium(opts = {}) {
+  let enabled = true;
+  return {
+    name: 'terrarium',
+    configResolved(config) {
+      enabled = loadEnv(config.mode, config.envDir ?? config.root, 'VITE_').VITE_TERRARIUM !== 'off';   // loadEnv merges .env files and the process environment
+      if (!enabled) { config.logger.info('[terrarium] off — plain dapp build'); return; }
+      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`);
+      config.logger.info(`[terrarium] injecting the simulated chain (scenario ${scenario})`);
+    },
+    transformIndexHtml: {
+      order: 'pre',
+      handler(html) { return enabled ? { html, tags: [{ tag: 'script', attrs: { type: 'module', src: '/.terrarium/inject.ts' }, injectTo: 'body' }] } : html; },
+    },
+  };
+}
+
+/** 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`;

package/src/worker-runtime.ts

@@ -0,0 +1,76 @@
+// 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';
+// @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';
+
+export async function runScenario(config: ScenarioConfig) {
+  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;
+  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);
+  const anchor = config.clock === 'recording' ? Number(BigInt(restore?.chain?.blocks?.at(-1)?.timestamp ?? bootWall)) : null;
+  const clock = typeof config.clock === 'number' ? () => config.clock as number : anchor !== null ? () => anchor + (Math.floor(Date.now() / 1000) - bootWall) : undefined;
+  const sim: any = await createTerrarium({ chainId, seed: config.seed, hardfork: config.hardfork, state: config.state, gasEstimation: config.gasEstimation, wallet: config.wallet, fork: config.fork, restore, clock, persist: storage ? { storage, key } : undefined });
+  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 });
+  const ctx: ScenarioContext = {
+    sim, chainId, rpc, pub,
+    accounts: sim.accounts.map((a: any) => a.address as Address),
+    wallet: (account) => createWalletClient({ chain, transport: custom(sim.provider), account }),
+    wait: async (h) => pub.waitForTransactionReceipt({ hash: await h }),
+    deadline: (seconds = 3600) => sim.now() + BigInt(seconds),
+    random: () => sim.random(),
+    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]); },
+    state: {},
+  };
+  await config.setup?.(ctx);
+  if (ctx.fresh && storage) await sim.flush();
+
+  // ---- actors: toggled together, persisted, off by default ----------------------------------------------------
+  const actorsKey = `${key}:actors`;
+  let timers: ReturnType<typeof setInterval>[] = [], 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 = [];
+      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)));
+      }
+    },
+  };
+  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; });
+  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 --------------
+  sim.addMethod('terrarium_httpRoutes', () => httpRoutes);
+  sim.addMethod('terrarium_http', async (index: number, raw: { url: string; method: string; headers?: Record<string, string>; body?: string | null }) => {
+    const route = (config.http ?? [])[index]; if (!route) throw new Error(`no http route ${index}`);
+    httpHits++; return runRoute(ctx, route, raw);
+  });
+
+  serveProvider(sim.provider);
+  return sim;
+}