explorbot 0.2.2 → 0.2.4

package/boat/doc-collector/src/docs-renderer.ts

@@ -1,9 +1,11 @@
 import path from 'node:path';
+import matter from 'gray-matter';
+import { APPLICATION_SPEC_FORMAT, APPLICATION_SPEC_VERSION } from '../../../src/application-spec-contract.ts';
 import { type WebPageState } from '../../../src/state-manager.ts';
+import { normalizeInlineText } from '../../../src/utils/strings.ts';
 import type { PageDocumentation, StateTransition } from './ai/documentarian.ts';
 import type { DocumentationScreenshot } from './screenshots.ts';
-import { buildStateGraph, renderMermaidFromGraph, renderStateMapFromGraph, type DocumentedPage, type SkippedPage } from './state-diagram.ts';
-import { normalizeInlineText } from '../../../src/utils/strings.ts';
+import { type DocumentedPage, type SkippedPage, buildStateGraph, renderMermaidFromGraph, renderPageStateDiagram, renderStateMapFromGraph } from './state-diagram.ts';
 
 function renderPageDocumentation(state: WebPageState, documentation: PageDocumentation, screenshots: DocumentationScreenshot[] = []): string {
   const lines: string[] = [];
@@ -33,6 +35,13 @@ function renderPageDocumentation(state: WebPageState, documentation: PageDocumen
   }
 
   const interactions = documentation.interactions;
+  const pageStateDiagram = renderPageStateDiagram(state.title || state.url || 'page', state.url || '', interactions || []);
+  if (pageStateDiagram) {
+    lines.push('## State Map');
+    lines.push('');
+    lines.push(`\`\`\`mermaid\n${pageStateDiagram}\n\`\`\``);
+    lines.push('');
+  }
   if (interactions && interactions.length > 0) {
     lines.push('## State Transitions');
     lines.push('');
@@ -101,7 +110,11 @@ function renderPageDocumentation(state: WebPageState, documentation: PageDocumen
     lines.push('');
   }
 
-  return `${lines.join('\n').trimEnd()}\n`;
+  return matter.stringify(`${lines.join('\n').trimEnd()}\n`, {
+    url: state.url,
+    format: APPLICATION_SPEC_FORMAT,
+    version: APPLICATION_SPEC_VERSION,
+  });
 }
 
 function renderSpecIndex(outputDir: string, startPath: string, pages: DocumentedPage[], skipped: SkippedPage[], maxPages: number): string {
@@ -116,9 +129,10 @@ function renderSpecIndex(outputDir: string, startPath: string, pages: Documented
   lines.push(`Max pages: ${maxPages}`);
   lines.push('');
   const graph = buildStateGraph(outputDir, pages);
+  const mermaid = renderMermaidFromGraph(graph, true);
   lines.push('## State Transitions');
   lines.push('');
-  lines.push(`\`\`\`mermaid\n${renderMermaidFromGraph(graph)}\n\`\`\``);
+  lines.push(`\`\`\`mermaid\n${mermaid}\n\`\`\``);
   lines.push('');
   const stateMap = renderStateMapFromGraph(graph);
   if (stateMap) {

package/boat/doc-collector/src/state-diagram.ts

@@ -69,8 +69,12 @@ function buildStateGraph(outputDir: string, pages: DocumentedPage[]): StateGraph
         continue;
       }
 
-      const pairKey = `${sourceId}>${targetId}`;
-      if (adjacency.get(targetId)?.has(sourceId)) {
+      if (adjacency.get(sourceId)?.has(targetId)) {
+        continue;
+      }
+
+      if (createsCycle(sourceId, targetId, adjacency)) {
+        const pairKey = `${sourceId}>${targetId}`;
         if (drawnBack.has(pairKey)) {
           continue;
         }
@@ -78,10 +82,6 @@ function buildStateGraph(outputDir: string, pages: DocumentedPage[]): StateGraph
         edges.push({ source: sourceId, target: targetId, action: transition.action, isBack: true });
         continue;
       }
-
-      if (adjacency.get(sourceId)?.has(targetId) || createsCycle(sourceId, targetId, adjacency)) {
-        continue;
-      }
       adjacency.get(sourceId)?.add(targetId);
       edges.push({ source: sourceId, target: targetId, action: transition.action, isBack: false });
     }
@@ -104,8 +104,8 @@ function renderMermaidBody(outputDir: string, pages: DocumentedPage[]): string {
   return renderMermaidFromGraph(buildStateGraph(outputDir, pages));
 }
 
-function renderMermaidFromGraph(graph: StateGraph): string {
-  const lines: string[] = ['flowchart TD'];
+function renderMermaidFromGraph(graph: StateGraph, compact = false): string {
+  const lines: string[] = [compact ? 'flowchart LR' : 'flowchart TD'];
   if (graph.pages.length === 0) {
     lines.push('  empty["No documented states"]');
     return lines.join('\n');
@@ -117,6 +117,12 @@ function renderMermaidFromGraph(graph: StateGraph): string {
     if (!children || children.length === 0) {
       continue;
     }
+    if (compact) {
+      for (const child of children) {
+        lines.push(`  ${renderNodeLine(child)}`);
+      }
+      continue;
+    }
     lines.push(`  subgraph sg_${page.id} ["${escapeMermaidLabel(page.label)} — transient states"]`);
     for (const child of children) {
       lines.push(`    ${renderNodeLine(child)}`);
@@ -125,11 +131,12 @@ function renderMermaidFromGraph(graph: StateGraph): string {
   }
 
   for (const edge of graph.edges) {
-    let arrow = '-->';
-    if (edge.isBack) {
-      arrow = '-.->';
+    const arrow = edge.isBack ? '-.->' : '-->';
+    if (compact) {
+      lines.push(`  ${edge.source} ${arrow} ${edge.target}`);
+    } else {
+      lines.push(`  ${edge.source} ${arrow}|"${escapeMermaidLabel(edge.action)}"| ${edge.target}`);
     }
-    lines.push(`  ${edge.source} ${arrow}|"${escapeMermaidLabel(edge.action)}"| ${edge.target}`);
   }
 
   lines.push('  classDef page fill:#dbeafe,stroke:#2563eb,color:#0f172a;');
@@ -174,6 +181,46 @@ function renderStateMapFromGraph(graph: StateGraph): string {
   return rows.join('\n');
 }
 
+function renderPageStateDiagram(label: string, url: string, interactions: StateTransition[]): string {
+  const targets = new Map<string, { node: StateNode; action: string; screenshot?: { title: string; relativePath: string } }>();
+  let index = 0;
+  for (const interaction of interactions) {
+    const targetState = interaction.targetState;
+    if (!targetState) {
+      continue;
+    }
+    const key = `${targetState.kind}:${targetState.label}:${normalizeUrl(targetState.url)}`;
+    if (targets.has(key)) {
+      continue;
+    }
+    targets.set(key, {
+      node: { id: `target${index++}`, kind: targetState.kind, label: targetState.label, subLabel: targetState.kind },
+      action: interaction.action,
+      screenshot: interaction.screenshot,
+    });
+  }
+
+  if (targets.size === 0) {
+    return '';
+  }
+
+  const lines: string[] = ['flowchart LR'];
+  lines.push(`  ${renderNodeLine({ id: 'self', kind: 'page', label, subLabel: url })}`);
+  for (const target of targets.values()) {
+    lines.push(`  ${renderNodeLine(target.node)}`);
+  }
+  for (const target of targets.values()) {
+    lines.push(`  self -->|"${escapeMermaidLabel(target.action)}"| ${target.node.id}`);
+  }
+  for (const target of targets.values()) {
+    if (target.screenshot) {
+      lines.push(`  click ${target.node.id} "${target.screenshot.relativePath}" "${escapeMermaidLabel(target.screenshot.title)}"`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
 function renderNodeLine(node: StateNode): string {
   const label = `${escapeMermaidLabel(node.label)}<br/>${escapeMermaidLabel(node.subLabel)}`;
   if (node.kind === 'dialog' || node.kind === 'modal') {
@@ -207,7 +254,7 @@ function createsCycle(sourceId: string, targetId: string, adjacency: Map<string,
 }
 
 function escapeMermaidLabel(value: string): string {
-  return normalizeInlineText(value).replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('|', '&#124;');
+  return normalizeInlineText(value).replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('#', '&#35;').replaceAll('<', '&#60;').replaceAll('>', '&#62;').replaceAll('|', '&#124;');
 }
 
 function escapeTable(value: string): string {
@@ -277,5 +324,5 @@ interface StateGraph {
   classAssignment: Map<StateClass, string[]>;
 }
 
-export { buildStateGraph, renderMermaidBody, renderMermaidFromGraph, renderStateMapFromGraph };
+export { buildStateGraph, renderMermaidBody, renderMermaidFromGraph, renderPageStateDiagram, renderStateMapFromGraph };
 export type { DocumentedPage, SkippedPage, StateGraph, StateNode, StateEdge, StateClick };

package/boat/prima/bin/prima-cli.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+import { createPrimaCommands } from '../src/cli.ts';
+
+const program = createPrimaCommands('prima');
+program.parse();

package/boat/prima/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "prima",
+  "version": "1.0.0",
+  "description": "High-level browser driver CLI for orchestrating agents",
+  "type": "module",
+  "bin": { "prima": "./bin/prima-cli.ts" },
+  "scripts": {
+    "format": "biome format --write .",
+    "lint:fix": "biome lint --write .",
+    "check:fix": "biome check --write ."
+  },
+  "dependencies": {
+    "commander": "^14.0.1",
+    "dedent": "^1.6.0"
+  }
+}

package/boat/prima/src/activity-line.ts

@@ -0,0 +1,33 @@
+import chalk from 'chalk';
+import { type ActivityEntry, addActivityListener, removeActivityListener } from '../../../src/activity.ts';
+import { isVerboseMode } from '../../../src/utils/logger.ts';
+
+const RESET_LINE = '\r\u001b[2K';
+
+const stream = process.stderr;
+let tracking = false;
+
+export function trackActivityLine(): void {
+  if (tracking) return;
+  if (!stream.isTTY) return;
+  if (isVerboseMode()) return;
+
+  tracking = true;
+  addActivityListener(writeActivityLine);
+}
+
+export function clearActivityLine(): void {
+  if (!tracking) return;
+
+  tracking = false;
+  removeActivityListener(writeActivityLine);
+  stream.write(RESET_LINE);
+}
+
+function writeActivityLine(activity: ActivityEntry | null): void {
+  if (!activity) return;
+
+  const width = (stream.columns || 80) - 2;
+  const message = Array.from(activity.message.replace(/\s+/g, ' ').trim()).slice(0, width).join('');
+  stream.write(`${RESET_LINE}${chalk.gray(message)}`);
+}

package/boat/prima/src/cli.ts

@@ -0,0 +1,251 @@
+import { Command } from 'commander';
+import dedent from 'dedent';
+import { keepServerRunning } from '../../../src/browser-server.ts';
+import { browserErrorMessage } from '../../../src/utils/browser-errors.ts';
+import { isVerboseMode, setQuietMode } from '../../../src/utils/logger.ts';
+import { clearActivityLine, trackActivityLine } from './activity-line.ts';
+import { type EnvelopeData, renderEnvelope } from './envelope.ts';
+import { Prima, type PrimaOptions } from './prima.ts';
+
+const helpContract = dedent`
+  Prima is a high-level AI extension to playwright-cli, driving the browser it has open.
+
+    playwright-cli open <url>    starts the session
+    prima <command> ...          drives it
+    playwright-cli close         ends it
+
+  One call takes a whole job:
+
+    prima check "a workflow can be created and appears in the list" --expected "the new workflow is listed"
+    prima do "open the account menu" "choose the settings entry" "switch the theme to dark" "check it took effect"
+    prima pw "({ page }) => page.click('[data-test=submit]')"
+`;
+
+const checkHelp = dedent`
+  check takes an outcome rather than a click path, and works out how to reach it.
+  --expected  one outcome the run must reach, repeatable for several. Without it the
+              scenario text is the single expected outcome. Each comes back under
+              ### Expected outcomes as PASSED, FAILED or not verified - "not verified"
+              means the run never checked it, which is not the same as false.
+  Page problems seen on the way appear under ### Answer, not as step failures.
+`;
+
+const doHelp = dedent`
+  Each instruction is numbered and accounted for: ### Steps reports each as ok or FAIL
+  with what proved it. One that could not be carried out fails the command and says why.
+  Nothing runs past the last instruction given. A whole remaining sequence in one call is
+  what makes this tier cheap.
+`;
+
+const verifyHelp = dedent`
+  Reports each assertion it could express as PASSED or FAILED with its playwright form,
+  and gives no overall verdict - read the lines and decide. "none ran" means the claim
+  could not be expressed, which is not the same as false.
+`;
+
+const reportHelp = dedent`
+  Commands are logged as they run, so the report needs no browser and outlives the session.
+  The most recent session is reported unless --pw-session names another.
+`;
+
+const sessionHelp = dedent`
+  --endpoint <ep>    attach to a browser server endpoint directly, skipping discovery
+  --instance <name>  which prima-owned browser you talk to; parallel work needs one each
+  --session [file]   cookies and storage persisted across processes; ignored while
+                     attached, since the attached session keeps its own
+  --framework        parsed but not active yet; reported code is CodeceptJS either way
+  DEBUG='explorbot:*' in front of a command prints the log of everything it does.
+  When no AI model is usable pw still works; for everything else drive playwright-cli.
+`;
+
+let rootOptions: () => any = () => ({});
+
+function buildOptions(subcommand: any): PrimaOptions {
+  const options = { ...rootOptions(), ...stripEmpty(subcommand) };
+  return {
+    config: options.config,
+    path: options.path,
+    instance: options.instance,
+    session: options.session,
+    ephemeral: options.ephemeral,
+    framework: options.framework,
+    noVision: options.vision === false,
+    url: options.url,
+    baseUrl: options.baseUrl,
+    show: options.show,
+    headless: options.headless,
+    endpoint: options.endpoint,
+    pwSession: options.pwSession,
+  };
+}
+
+function stripEmpty(options: any): any {
+  const present: any = {};
+  for (const [key, value] of Object.entries(options || {})) {
+    if (value === undefined) continue;
+    present[key] = value;
+  }
+  return present;
+}
+
+function addCommonOptions(cmd: Command): Command {
+  return cmd
+    .option('-c, --config <path>', 'Path to explorbot configuration file')
+    .option('-p, --path <path>', 'Working directory path')
+    .option('-i, --instance <name>', 'Browser instance to drive')
+    .option('--session [file]', 'Persist cookies and storage to a session file')
+    .option('--ephemeral', 'Keep no state between runs; applies to config-free runs, where output goes to a temp directory')
+    .option('--framework <name>', 'Not active yet: framework the reported code targets, codeceptjs or playwright')
+    .option('--url <url>', 'Page to open when the session has no page yet')
+    .option('--endpoint <ep>', 'Websocket endpoint of a browser server to attach to, skipping discovery')
+    .option('--pw-session <title>', 'Title of the playwright-cli session to attach to')
+    .addHelpText('after', `\n${sessionHelp}`);
+}
+
+function primaFor(options: any): Prima {
+  if (options.ephemeral) process.env.EXPLORBOT_EPHEMERAL = '1';
+  return new Prima(buildOptions(options));
+}
+
+async function runPrima(options: any, command: string, run: (prima: Prima) => Promise<EnvelopeData>, record = true): Promise<void> {
+  setQuietMode(!isVerboseMode());
+  trackActivityLine();
+  const prima = primaFor(options);
+  const startedAt = Date.now();
+
+  let envelope: EnvelopeData;
+  try {
+    await prima.start();
+    envelope = await run(prima);
+  } catch (error) {
+    envelope = await prima.toolFailureEnvelope(command, error);
+  }
+
+  if (record) prima.record(envelope, Date.now() - startedAt);
+  clearActivityLine();
+  console.log(renderEnvelope(envelope));
+  await prima.stop().catch(() => {});
+  process.exit(envelope.ok ? 0 : 1);
+}
+
+async function runBrowser(options: any, run: (prima: Prima) => Promise<boolean>): Promise<void> {
+  let ok = false;
+  try {
+    ok = await run(primaFor(options));
+  } catch (error) {
+    console.error(browserErrorMessage(error));
+    process.exit(1);
+  }
+
+  process.exit(ok ? 0 : 1);
+}
+
+export function createPrimaCommands(name = 'prima'): Command {
+  const cmd = new Command(name);
+  cmd.description('Tests and drives a web app through described behaviour instead of locators: one command carries a whole scenario, verifies it, and reports the proof');
+  cmd.option('--pw-session <title>', 'Title of the playwright-cli session to attach to');
+  cmd.option('--url <url>', 'Page to open when the session has no page yet');
+  cmd.addHelpText('after', `\n${helpContract}`);
+  rootOptions = () => cmd.opts();
+
+  addCommonOptions(cmd.command('pw <fn>').description('Run a Playwright function expression against the open page')).action(async (fn, options) => {
+    await runPrima(options, `pw ${fn}`, (prima) => prima.pw(fn));
+  });
+
+  addCommonOptions(cmd.command('do <instructions...>').description('Run high-level instructions tester-style, one argument per instruction'))
+    .addHelpText('after', `\n${doHelp}`)
+    .action(async (instructions, options) => {
+      await runPrima(options, `do ${instructions.join(' ')}`, (prima) => prima.do(instructions));
+    });
+
+  addCommonOptions(cmd.command('check <scenario>').description('Run a scenario end to end as a test, with its own verification, and report the steps it took'))
+    .option('--expected <outcome>', 'An outcome the run must reach; repeat the flag for several', (value: string, all: string[]) => [...all, value], [])
+    .addHelpText('after', `\n${checkHelp}`)
+    .action(async (scenario, options) => {
+      await runPrima(options, `check ${scenario}`, (prima) => prima.check(scenario, options.expected));
+    });
+
+  addCommonOptions(cmd.command('ask <question>').description('Answer a question about the current page').option('--no-vision', 'Answer from page structure only, without a screenshot')).action(async (question, options) => {
+    await runPrima(options, `ask ${question}`, (prima) => prima.ask(question));
+  });
+
+  addCommonOptions(cmd.command('verify <assertion>').alias('assert').description('Assert a statement about the current page'))
+    .addHelpText('after', `\n${verifyHelp}`)
+    .action(async (assertion, options) => {
+      await runPrima(options, `verify ${assertion}`, (prima) => prima.verify(assertion));
+    });
+
+  addCommonOptions(
+    cmd.command('research').description('Map the current page and return verified locators').option('--data', 'Include data extraction in the map').option('--deep', 'Expand hidden elements for a deeper map').option('--fresh', 'Ignore the cached map and research the page again')
+  ).action(async (options) => {
+    await runPrima(options, 'research', (prima) => prima.research({ data: options.data, deep: options.deep, fresh: options.fresh }));
+  });
+
+  addCommonOptions(cmd.command('go <target>').description('Navigate to a url, a path, or a page described in plain words')).action(async (target, options) => {
+    if (URL.canParse(target)) options.baseUrl = target;
+    await runPrima(options, `go ${target}`, (prima) => prima.go(target));
+  });
+
+  addCommonOptions(cmd.command('config').description('Show the AI models prima runs on and the config file they come from')).action(async (options) => {
+    setQuietMode(!isVerboseMode());
+    const prima = primaFor(options);
+    console.log(await prima.config().catch((error: unknown) => browserErrorMessage(error)));
+    await prima.stop().catch(() => {});
+    process.exit(0);
+  });
+
+  addCommonOptions(cmd.command('status <hash>').description('Show the artifacts and page detail recorded for an earlier command')).action(async (hash, options) => {
+    await runPrima(options, `status ${hash}`, (prima) => prima.status(hash), false);
+  });
+
+  addCommonOptions(cmd.command('report').description('Turn every command of a session into one html and markdown report'))
+    .addHelpText('after', `\n${reportHelp}`)
+    .action(async (options) => {
+      setQuietMode(!isVerboseMode());
+      console.log(
+        await primaFor(options)
+          .report()
+          .catch((error: unknown) => browserErrorMessage(error))
+      );
+      process.exit(0);
+    });
+
+  const browser = cmd.command('browser').description('Manage the browsers prima drives');
+
+  addCommonOptions(browser.command('start').description('Start a prima-owned browser and hold it open until Ctrl+C'))
+    .option('-s, --show', 'Launch the browser in a visible window')
+    .option('--headless', 'Launch the browser without a window')
+    .action(async (options) => {
+      await runBrowser(options, async (prima) => {
+        await prima.browserStart();
+        console.log(await prima.browserStatus());
+        return keepServerRunning(() => prima.browserStop());
+      });
+    });
+
+  addCommonOptions(browser.command('stop').description('Stop the browser of this instance'))
+    .option('--all', 'Stop every running instance')
+    .action(async (options) => {
+      await runBrowser(options, async (prima) => {
+        const stopped = await prima.browserStop(options.all);
+        console.log(await prima.browserStatus());
+        return stopped;
+      });
+    });
+
+  addCommonOptions(browser.command('status').description('Report the browser of this instance')).action(async (options) => {
+    await runBrowser(options, async (prima) => {
+      console.log(await prima.browserStatus());
+      return true;
+    });
+  });
+
+  addCommonOptions(browser.command('list').description('List every browser instance that is running')).action(async (options) => {
+    await runBrowser(options, async (prima) => {
+      console.log(await prima.browserList());
+      return true;
+    });
+  });
+
+  return cmd;
+}

package/boat/prima/src/envelope.ts

@@ -0,0 +1,169 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+const EXPECTATION_LABELS = {
+  passed: 'PASSED      ',
+  failed: 'FAILED      ',
+  unverified: 'not verified',
+};
+
+export interface InstanceInfo {
+  name: string;
+  tabs: number;
+  startedAgo?: string;
+  attached?: string;
+  others: Array<{ name: string; tabs: number }>;
+}
+
+export interface EnvelopeData {
+  ok: boolean;
+  command: string;
+  used?: string[];
+  page: { url: string; previousUrl?: string; title: string; state: string; visits: number };
+  changes?: string | null;
+  steps?: Array<{ label: string; ok: boolean; proof: string }>;
+  expectations?: Array<{ text: string; status: 'passed' | 'failed' | 'unverified' }>;
+  stepFiles?: string;
+  value?: string;
+  answer?: string;
+  research?: string;
+  assertions?: Array<{ code: string; passed: boolean; proof: string[] }>;
+  failure?: { error: string; compactAria?: string };
+  instance: InstanceInfo;
+  status?: string;
+  artifacts?: { aria: string; html: string; network?: string };
+}
+
+export function renderEnvelope(data: EnvelopeData): string {
+  const sections = [renderResult(data), renderPage(data), renderValue(data), renderChanges(data), renderSteps(data), renderExpectations(data), renderOutcome(data), ...renderFailure(data), renderInstance(data), renderArtifacts(data)];
+  return sections.filter((section) => section).join('\n\n');
+}
+
+export function writeArtifacts(dir: string, snapshot: { aria: string | null; html: string | null; requests: unknown[] }): { aria: string; html: string; network?: string } {
+  mkdirSync(dir, { recursive: true });
+  const paths: { aria: string; html: string; network?: string } = {
+    aria: path.resolve(dir, 'aria.yml'),
+    html: path.resolve(dir, 'page.html'),
+  };
+  writeFileSync(paths.aria, snapshot.aria ?? '', 'utf-8');
+  writeFileSync(paths.html, snapshot.html ?? '', 'utf-8');
+
+  if (!snapshot.requests.length) return paths;
+
+  paths.network = path.resolve(dir, 'network.jsonl');
+  writeFileSync(paths.network, snapshot.requests.map((request) => `${JSON.stringify(request)}\n`).join(''), 'utf-8');
+  return paths;
+}
+
+function renderResult(data: EnvelopeData): string {
+  const lines = [`ok: ${data.ok}`, `command: ${data.command}`];
+  if (data.used?.length) lines.push(`used: ${data.used.join('; ')}`);
+  return section('Result', lines.join('\n'));
+}
+
+function renderPage(data: EnvelopeData): string {
+  const { url, previousUrl, title, state, visits } = data.page;
+  const urlLabel = `url: ${url}`;
+  const stateLabel = `state: ${state}`;
+  const width = Math.max(urlLabel.length, stateLabel.length) + 3;
+  let changedMarker = '';
+  if (previousUrl && previousUrl !== url) changedMarker = `(changed: ${previousUrl} → ${url})`;
+  const lines = [align(urlLabel, changedMarker, width), `title: ${title}`, align(stateLabel, `(visit #${visits})`, width)];
+  return section('Page', lines.join('\n'));
+}
+
+function renderValue(data: EnvelopeData): string | null {
+  if (data.value === undefined) return null;
+  return section('Value', data.value);
+}
+
+function renderChanges(data: EnvelopeData): string | null {
+  if (data.changes === undefined || data.changes === null) return null;
+  return section('Changes', data.changes);
+}
+
+function renderSteps(data: EnvelopeData): string | null {
+  if (!data.steps?.length) return null;
+
+  const lines: string[] = [];
+  data.steps.forEach((step, index) => {
+    lines.push(`${index + 1}. ${step.ok ? 'ok  ' : 'FAIL'} ${step.label}`);
+    for (const line of (step.proof || '').split('\n').filter(Boolean)) lines.push(`      ${line}`);
+  });
+  if (data.stepFiles) lines.push('', `page after each step: ${data.stepFiles}`);
+  return section('Steps', lines.join('\n'));
+}
+
+function renderExpectations(data: EnvelopeData): string | null {
+  if (!data.expectations?.length) return null;
+  const lines = data.expectations.map((expectation, index) => `${index + 1}. ${EXPECTATION_LABELS[expectation.status]} ${expectation.text}`);
+  return section('Expected outcomes', lines.join('\n'));
+}
+
+function renderOutcome(data: EnvelopeData): string | null {
+  if (data.answer) return section('Answer', data.answer);
+  if (data.research) return section('Research', data.research);
+  if (!data.assertions) return null;
+
+  if (!data.assertions.length) return section('Assertions', 'none ran — no assertion could express this claim, so nothing was checked against the page');
+
+  const lines = data.assertions.map((assertion) => {
+    const code = assertion.code
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith('//'))
+      .join(' ');
+    return `${code}  => ${assertion.passed ? 'PASSED' : 'FAILED'}`;
+  });
+
+  const proof = data.assertions.flatMap((assertion) => assertion.proof);
+  if (proof.length) lines.push('', 'playwright:', ...proof);
+
+  return section('Assertions', lines.join('\n'));
+}
+
+function renderFailure(data: EnvelopeData): Array<string | null> {
+  if (!data.failure) return [];
+  return [section('Failure', `error: ${data.failure.error}`), renderCompactAria(data.failure.compactAria)];
+}
+
+function renderCompactAria(compactAria?: string): string | null {
+  if (!compactAria) return null;
+  return section('Current page (compact ARIA)', compactAria);
+}
+
+function renderInstance(data: EnvelopeData): string | null {
+  const instance = data.instance;
+  const parts = [`${instance.name} (${tabsLabel(instance.tabs)})`, browserLine(instance)];
+  if (instance.others.length) parts.push(`other instances: ${instance.others.map((other) => `${other.name} (${tabsLabel(other.tabs)})`).join(', ')}`);
+  if (data.status) parts.push(`details: prima status ${data.status}`);
+  return section('Instance', parts.join(' | '));
+}
+
+function browserLine(instance: InstanceInfo): string {
+  if (instance.attached) return `attached to ${instance.attached}`;
+  if (instance.startedAgo) return `running, started ${instance.startedAgo} ago`;
+  if (instance.tabs > 0) return 'running';
+  return 'not running';
+}
+
+function tabsLabel(tabs: number): string {
+  if (tabs === 1) return '1 tab';
+  return `${tabs} tabs`;
+}
+
+export function renderArtifacts(data: EnvelopeData): string | null {
+  if (!data.artifacts) return null;
+  const lines = [`aria: ${data.artifacts.aria}`, `html: ${data.artifacts.html}`];
+  if (data.artifacts.network) lines.push(`network: ${data.artifacts.network}`);
+  return section('Artifacts', lines.join('\n'));
+}
+
+function align(label: string, marker: string, width: number): string {
+  if (!marker) return label;
+  return `${label.padEnd(width)}${marker}`;
+}
+
+function section(title: string, body: string): string {
+  return `### ${title}\n${body}`;
+}