explorbot 0.2.1 → 0.2.3

package/dist/boat/doc-collector/src/interaction-screenshots.js

@@ -0,0 +1,156 @@
+import { writeFileSync } from 'node:fs';
+import pixelmatch from 'pixelmatch';
+import { PNG } from 'pngjs';
+const REGION_PADDING = 30;
+const SCREENSHOT_OPTIONS = { animations: 'disabled', caret: 'hide' };
+export async function captureInteractionBefore(page) {
+    await removeVisualAnnotations(page);
+    try {
+        return await page.screenshot(SCREENSHOT_OPTIONS);
+    }
+    catch {
+        return null;
+    }
+}
+export async function captureInteractionAfter(page, beforeScreenshot, filePath, detectUnmarkedOverlay = false) {
+    if (!beforeScreenshot)
+        return 'failed';
+    await removeVisualAnnotations(page);
+    try {
+        const afterScreenshot = await page.screenshot(SCREENSHOT_OPTIONS);
+        const before = PNG.sync.read(beforeScreenshot);
+        const after = PNG.sync.read(afterScreenshot);
+        if (before.width !== after.width || before.height !== after.height)
+            return 'failed';
+        const changedPixels = findChangedPixelBounds(before, after);
+        if (!changedPixels)
+            return 'unchanged';
+        const fullViewportChanged = changedPixels.x === 0 && changedPixels.y === 0 && changedPixels.width === after.width && changedPixels.height === after.height;
+        const changedRegion = addPadding(changedPixels, after.width, after.height);
+        const overlayRegion = fullViewportChanged ? await findOverlayRegion(page, after, detectUnmarkedOverlay) : null;
+        saveRegion(after, overlayRegion || changedRegion, filePath);
+        return 'captured';
+    }
+    catch {
+        return 'failed';
+    }
+}
+export function findChangedRegion(beforeScreenshot, afterScreenshot, padding = REGION_PADDING) {
+    const before = PNG.sync.read(beforeScreenshot);
+    const after = PNG.sync.read(afterScreenshot);
+    if (before.width !== after.width || before.height !== after.height)
+        return null;
+    const changedPixels = findChangedPixelBounds(before, after);
+    return changedPixels ? addPadding(changedPixels, before.width, before.height, padding) : null;
+}
+function saveRegion(after, region, filePath) {
+    const cropped = new PNG({ width: region.width, height: region.height });
+    PNG.bitblt(after, cropped, region.x, region.y, region.width, region.height, 0, 0);
+    writeFileSync(filePath, PNG.sync.write(cropped));
+}
+function findChangedPixelBounds(before, after) {
+    const diff = Buffer.alloc(before.width * before.height * 4);
+    const changedPixels = pixelmatch(before.data, after.data, diff, before.width, before.height, { diffMask: true });
+    if (changedPixels === 0)
+        return null;
+    let left = before.width;
+    let top = before.height;
+    let right = 0;
+    let bottom = 0;
+    for (let y = 0; y < before.height; y++) {
+        for (let x = 0; x < before.width; x++) {
+            if (diff[(y * before.width + x) * 4 + 3] === 0)
+                continue;
+            left = Math.min(left, x);
+            top = Math.min(top, y);
+            right = Math.max(right, x);
+            bottom = Math.max(bottom, y);
+        }
+    }
+    return { x: left, y: top, width: right - left + 1, height: bottom - top + 1 };
+}
+function addPadding(region, imageWidth, imageHeight, padding = REGION_PADDING) {
+    const x = Math.max(0, region.x - padding);
+    const y = Math.max(0, region.y - padding);
+    const maxX = Math.min(imageWidth, region.x + region.width + padding);
+    const maxY = Math.min(imageHeight, region.y + region.height + padding);
+    return { x, y, width: maxX - x, height: maxY - y };
+}
+async function removeVisualAnnotations(page) {
+    try {
+        await page.locator('[data-explorbot-annotation]').evaluateAll((elements) => {
+            for (const element of elements)
+                element.remove();
+        });
+    }
+    catch { }
+}
+async function findOverlayRegion(page, image, detectUnmarkedOverlay) {
+    let box = null;
+    try {
+        const dialogs = page.locator('[role="dialog"]:visible, [role="alertdialog"]:visible, [aria-modal="true"]:visible');
+        if ((await dialogs.count()) > 0)
+            box = await dialogs.last().boundingBox();
+    }
+    catch { }
+    if (!box && detectUnmarkedOverlay) {
+        try {
+            box = await findUnmarkedOverlay(page);
+        }
+        catch { }
+    }
+    try {
+        const viewport = page.viewportSize();
+        if (!box || !viewport)
+            return null;
+        const scaleX = image.width / viewport.width;
+        const scaleY = image.height / viewport.height;
+        const x = Math.max(0, Math.floor(box.x * scaleX) - REGION_PADDING);
+        const y = Math.max(0, Math.floor(box.y * scaleY) - REGION_PADDING);
+        const maxX = Math.min(image.width, Math.ceil((box.x + box.width) * scaleX) + REGION_PADDING);
+        const maxY = Math.min(image.height, Math.ceil((box.y + box.height) * scaleY) + REGION_PADDING);
+        if (maxX <= x || maxY <= y)
+            return null;
+        return { x, y, width: maxX - x, height: maxY - y };
+    }
+    catch {
+        return null;
+    }
+}
+async function findUnmarkedOverlay(page) {
+    return page.evaluate(() => {
+        const elements = [...document.body.querySelectorAll('*')].map((element) => {
+            const style = getComputedStyle(element);
+            const box = element.getBoundingClientRect();
+            const zIndex = Number.parseInt(style.zIndex, 10);
+            return { element, style, box, zIndex, area: box.width * box.height };
+        });
+        const isVisibleLayer = ({ style, box, zIndex }) => {
+            if (style.visibility === 'hidden' || style.display === 'none' || Number(style.opacity) === 0)
+                return false;
+            if (box.width <= 0 || box.height <= 0)
+                return false;
+            if (style.position !== 'fixed' && style.position !== 'absolute')
+                return false;
+            return Number.isFinite(zIndex);
+        };
+        const backdropZIndex = elements.filter((item) => isVisibleLayer(item) && item.box.width >= window.innerWidth && item.box.height >= window.innerHeight).reduce((highest, item) => Math.max(highest, item.zIndex), Number.NEGATIVE_INFINITY);
+        if (!Number.isFinite(backdropZIndex))
+            return null;
+        const candidates = elements
+            .filter((item) => {
+            if (!isVisibleLayer(item))
+                return false;
+            if (item.box.width >= window.innerWidth && item.box.height >= window.innerHeight)
+                return false;
+            if (item.zIndex < backdropZIndex)
+                return false;
+            return item.element.matches('button, input, select, textarea, a[href]') || !!item.element.querySelector('button, input, select, textarea, a[href]');
+        })
+            .sort((left, right) => right.zIndex - left.zIndex || left.area - right.area);
+        const box = candidates[0]?.box;
+        if (!box)
+            return null;
+        return { x: box.x, y: box.y, width: box.width, height: box.height };
+    });
+}

package/dist/boat/doc-collector/src/screenshots.js

@@ -1,8 +1,8 @@
 import { mkdirSync } from 'node:fs';
 import path from 'node:path';
 import { parseResearchSections } from "../../../src/ai/researcher/parser.js";
-import { detectFocusArea } from "../../../src/utils/aria.js";
 import { safeFilename, sanitizeFilename } from "../../../src/utils/strings.js";
+import { captureInteractionAfter, captureInteractionBefore } from "./interaction-screenshots.js";
 const DEFAULT_MAX_SECTION_SCREENSHOTS = 8;
 export async function captureDocumentationScreenshots(explorer, state, research, options) {
     const page = explorer.page;
@@ -47,7 +47,7 @@ export function getScreenshotSections(research) {
     }
     return sections;
 }
-export async function captureInteractionScreenshot(explorer, state, transition, options) {
+export async function captureInteractionScreenshot(explorer, beforeScreenshot, state, transition, options) {
     const page = explorer.page;
     if (!page) {
         return null;
@@ -55,19 +55,13 @@ export async function captureInteractionScreenshot(explorer, state, transition,
     mkdirSync(options.screenshotsDir, { recursive: true });
     const pageName = sanitizeFilename(state.url || 'page') || 'page';
     const stateName = sanitizeFilename(transition.targetState?.label || transition.action) || 'state';
-    const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_${stateName}`, '.png'));
-    const focus = detectFocusArea(state.ariaSnapshot || null);
-    try {
-        if (focus.detected) {
-            await page.locator('[role="dialog"], [role="alertdialog"], [aria-modal="true"]').last().screenshot({ path: filePath });
-        }
-        else {
-            await page.screenshot({ path: filePath });
-        }
-    }
-    catch {
+    const stateId = state.id ? `_${state.id}` : '';
+    const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_${stateName}${stateId}`, '.png'));
+    const result = await captureInteractionAfter(page, beforeScreenshot, filePath, transition.changes?.urlChanged !== true);
+    if (result === 'unchanged')
+        return null;
+    if (result === 'failed' && !(await captureViewport(page, filePath)))
         return null;
-    }
     return {
         title: transition.targetState?.label || transition.action,
         path: filePath,
@@ -75,6 +69,21 @@ export async function captureInteractionScreenshot(explorer, state, transition,
         kind: 'state',
     };
 }
+export async function captureBeforeInteraction(explorer) {
+    const page = explorer.page;
+    if (!page)
+        return null;
+    return captureInteractionBefore(page);
+}
+async function captureViewport(page, filePath) {
+    try {
+        await page.screenshot({ path: filePath });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function captureFullPageScreenshot(page, pageName, options) {
     const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_page`, '.png'));
     try {

package/dist/boat/doc-collector/src/state-diagram.js

@@ -60,8 +60,11 @@ function buildStateGraph(outputDir, pages) {
             if (!targetId) {
                 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;
                 }
@@ -69,9 +72,6 @@ function buildStateGraph(outputDir, pages) {
                 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 });
         }
@@ -90,8 +90,8 @@ function buildStateGraph(outputDir, pages) {
 function renderMermaidBody(outputDir, pages) {
     return renderMermaidFromGraph(buildStateGraph(outputDir, pages));
 }
-function renderMermaidFromGraph(graph) {
-    const lines = ['flowchart TD'];
+function renderMermaidFromGraph(graph, compact = false) {
+    const lines = [compact ? 'flowchart LR' : 'flowchart TD'];
     if (graph.pages.length === 0) {
         lines.push('  empty["No documented states"]');
         return lines.join('\n');
@@ -102,6 +102,12 @@ function renderMermaidFromGraph(graph) {
         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)}`);
@@ -109,11 +115,13 @@ function renderMermaidFromGraph(graph) {
         lines.push('  end');
     }
     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;');
     lines.push('  classDef dialog fill:#ffedd5,stroke:#ea580c,color:#0f172a;');
@@ -153,6 +161,42 @@ function renderStateMapFromGraph(graph) {
     }
     return rows.join('\n');
 }
+function renderPageStateDiagram(label, url, interactions) {
+    const targets = new Map();
+    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 = ['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) {
     const label = `${escapeMermaidLabel(node.label)}<br/>${escapeMermaidLabel(node.subLabel)}`;
     if (node.kind === 'dialog' || node.kind === 'modal') {
@@ -183,7 +227,7 @@ function createsCycle(sourceId, targetId, adjacency) {
     return false;
 }
 function escapeMermaidLabel(value) {
-    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) {
     return normalizeInlineText(value).replaceAll('|', '\\|');
@@ -197,4 +241,4 @@ function classForKind(kind) {
     }
     return 'dialog';
 }
-export { buildStateGraph, renderMermaidBody, renderMermaidFromGraph, renderStateMapFromGraph };
+export { buildStateGraph, renderMermaidBody, renderMermaidFromGraph, renderPageStateDiagram, renderStateMapFromGraph };

package/dist/boat/prima/bin/prima-cli.js

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

package/dist/boat/prima/src/cli.js

@@ -0,0 +1,200 @@
+import { Command } from 'commander';
+import dedent from 'dedent';
+import { keepServerRunning } from "../../../src/browser-server.js";
+import { browserErrorMessage } from "../../../src/utils/browser-errors.js";
+import { setPreserveConsoleLogs } from "../../../src/utils/logger.js";
+import { renderEnvelope } from "./envelope.js";
+import { Prima } from "./prima.js";
+const helpContract = dedent `
+  Prima drives a browser that is already open. One command per process; every command
+  prints a plain-text envelope on stdout and exits 0 when ok, 1 when not.
+
+  TIERS - choose by what you hold, not by how hard the step looks
+    pw <fn>        Precise. A Playwright function expression built from a locator you
+                   already verified. No AI on the happy path.
+                     prima pw "({ page }) => page.click('[data-test=submit]')"
+    click / fill   One action described in words; AI resolves it on the current page.
+                     prima click "the primary action button in the header"
+                     prima fill "the search box" "a search term"
+    do <steps...>  Several described steps, run tester-style in one process.
+                     prima do "open the account menu" "choose the settings entry"
+    Never pass a locator or a function expression to click/fill/do - describe the target.
+    Never pass a description to pw - it takes executable code only.
+
+  LOOP
+    prima go <url|path|words>  reach the page you want to work on
+    prima research             once per new page; returns verified locators
+    prima pw "..."             drive the page with those locators
+    prima verify "..."         assert the outcome (prima ask "..." to inspect instead)
+    Fall back to click/fill/do whenever research left you no locator to hold.
+
+  ENVELOPE
+    ### Result     ok, command, healed, used
+    ### Page       url, title, state hash, visit count
+    ### Changes    what the accessibility tree gained or lost
+    ### Answer | ### Research | ### Verdict   output of ask, research, verify
+    ### Failure    error, reasoning, healing attempts, compact ARIA of the page
+    ### Instance   the browser you are on and the other instances running
+    ### Artifacts  paths to the full aria.yml, page.html and network.jsonl
+    used: is code that already executed - CodeceptJS steps to copy as they are, except
+          for pw, whose Playwright expression a test needs inside I.usePlaywrightTo(...).
+    Log lines can precede the envelope; start parsing at the first ### line.
+
+  HEALING AND FAILURE
+    A failed action is retried by AI along a different route; healed: true means the
+    outcome was reached another way and used: holds the code that worked.
+    --no-heal skips that and fails fast.
+    Failures print compact ARIA inline, so retarget from the envelope itself and open
+    the artifact files only when the inline snapshot is not enough.
+
+  SESSIONS
+    By default prima attaches to the playwright-cli browser of this workspace and works
+    on the tabs it already has open; driving the same session from both tools is the
+    intended usage.
+    playwright-cli open <url>  the session prima attaches to
+    --pw-session <title>       which playwright-cli session, when several are open
+    --endpoint <ep>            attach to a browser server endpoint directly
+    prima browser start        a prima-owned browser instead, when no session is open
+    --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, the attached session keeps its own
+    Prima never launches a browser implicitly and never closes an attached one - it
+    disconnects. browser list shows both kinds; ### Instance names the one you are on.
+    Every browser is reached over a Playwright browser-server endpoint, which needs the
+    Node build - run prima as "npx explorbot prima ..." or through the published prima
+    bin; from source under Bun the connection does not open.
+    When no AI model is usable pw still works; for everything else drive
+    playwright-cli directly.
+    Parsed but not active yet: --framework, so reported code is CodeceptJS whatever
+    you pass.
+`;
+function buildOptions(options) {
+    return {
+        verbose: options.verbose || options.debug,
+        config: options.config,
+        path: options.path,
+        instance: options.instance,
+        session: options.session,
+        heal: options.heal,
+        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 addCommonOptions(cmd) {
+    return cmd
+        .option('-v, --verbose', 'Enable verbose logging')
+        .option('--debug', 'Enable debug logging (same as --verbose)')
+        .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('--no-heal', 'Fail immediately instead of letting AI retry a failed action')
+        .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');
+}
+function primaFor(options) {
+    setPreserveConsoleLogs(true);
+    if (options.ephemeral)
+        process.env.EXPLORBOT_EPHEMERAL = '1';
+    return new Prima(buildOptions(options));
+}
+async function runPrima(options, command, run) {
+    const prima = primaFor(options);
+    let envelope;
+    try {
+        await prima.start();
+        envelope = await run(prima);
+    }
+    catch (error) {
+        envelope = await prima.toolFailureEnvelope(command, error);
+    }
+    console.log(renderEnvelope(envelope));
+    await prima.stop().catch(() => { });
+    process.exit(envelope.ok ? 0 : 1);
+}
+async function runBrowser(options, run) {
+    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') {
+    const cmd = new Command(name);
+    cmd.description('Drive an already-open browser one command at a time and report back in a plain-text envelope');
+    cmd.addHelpText('after', `\n${helpContract}`);
+    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')).action(async (instructions, options) => {
+        await runPrima(options, `do ${instructions.join(' ')}`, (prima) => prima.do(instructions));
+    });
+    addCommonOptions(cmd.command('click <target>').description('Click an element described in plain words')).action(async (target, options) => {
+        await runPrima(options, `click ${target}`, (prima) => prima.click(target));
+    });
+    addCommonOptions(cmd.command('fill <field> <value>').description('Fill a field described in plain words')).action(async (field, value, options) => {
+        await runPrima(options, `fill ${field} ${value}`, (prima) => prima.fill(field, value));
+    });
+    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')).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));
+    });
+    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/dist/boat/prima/src/envelope.js

@@ -0,0 +1,116 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+export function renderEnvelope(data) {
+    const sections = [renderResult(data), renderPage(data), renderOutcome(data), ...renderFailure(data), renderInstance(data.instance), renderArtifacts(data)];
+    return sections.filter((section) => section).join('\n\n');
+}
+export function writeArtifacts(dir, snapshot) {
+    mkdirSync(dir, { recursive: true });
+    const paths = {
+        aria: path.resolve(dir, 'aria.yml'),
+        html: path.resolve(dir, 'page.html'),
+        network: path.resolve(dir, 'network.jsonl'),
+    };
+    writeFileSync(paths.aria, snapshot.aria ?? '', 'utf-8');
+    writeFileSync(paths.html, snapshot.html ?? '', 'utf-8');
+    writeFileSync(paths.network, snapshot.requests.map((request) => `${JSON.stringify(request)}\n`).join(''), 'utf-8');
+    return paths;
+}
+function renderResult(data) {
+    const lines = [`ok: ${data.ok}`, `command: ${data.command}`];
+    const healed = renderHealed(data);
+    if (healed)
+        lines.push(healed);
+    if (data.used?.length)
+        lines.push(`used: ${data.used.join('; ')}`);
+    return section('Result', lines.join('\n'));
+}
+function renderHealed(data) {
+    if (data.healed === undefined)
+        return null;
+    if (data.healNote)
+        return `healed: ${data.healed} (${data.healNote})`;
+    return `healed: ${data.healed}`;
+}
+function renderPage(data) {
+    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 renderOutcome(data) {
+    if (data.changes)
+        return section('Changes', data.changes);
+    if (data.answer)
+        return section('Answer', data.answer);
+    if (data.research)
+        return section('Research', data.research);
+    if (!data.verdict)
+        return null;
+    const lines = [`passed: ${data.verdict.passed}`, `evidence: ${data.verdict.evidence}`, `code: ${data.verdict.code}`];
+    return section('Verdict', lines.join('\n'));
+}
+function renderFailure(data) {
+    if (!data.failure)
+        return [];
+    const lines = [`error: ${data.failure.error}`];
+    if (data.failure.reasoning)
+        lines.push(`reasoning: ${data.failure.reasoning}`);
+    return [section('Failure', lines.join('\n')), renderAttempts(data.failure.attempts), renderCompactAria(data.failure.compactAria)];
+}
+function renderAttempts(attempts) {
+    if (!attempts?.length)
+        return null;
+    const labels = attempts.map((attempt, index) => `${index + 1}. ${attempt.code}`);
+    const width = Math.max(...labels.map((label) => label.length)) + 3;
+    const lines = labels.map((label, index) => align(label, `→ ${attempts[index].outcome}`, width));
+    return section(`Healing attempts (${attempts.length})`, lines.join('\n'));
+}
+function renderCompactAria(compactAria) {
+    if (!compactAria)
+        return null;
+    return section('Current page (compact ARIA)', compactAria);
+}
+function renderInstance(instance) {
+    const others = instance.others.map((other) => `${other.name} (${tabsLabel(other.tabs)})`);
+    const lines = [`instance: ${instance.name} (${tabsLabel(instance.tabs)}) | other instances: ${otherInstances(others)}`, browserLine(instance)];
+    return section('Instance', lines.join('\n'));
+}
+function otherInstances(others) {
+    if (!others.length)
+        return 'none';
+    return others.join(', ');
+}
+function browserLine(instance) {
+    if (instance.attached)
+        return `browser: attached (${instance.attached})`;
+    if (instance.startedAgo)
+        return `browser: running, started ${instance.startedAgo} ago`;
+    if (instance.tabs > 0)
+        return 'browser: running';
+    return 'browser: not running';
+}
+function tabsLabel(tabs) {
+    if (tabs === 1)
+        return '1 tab';
+    return `${tabs} tabs`;
+}
+function renderArtifacts(data) {
+    if (!data.artifacts)
+        return null;
+    const lines = [`aria: ${data.artifacts.aria}`, `html: ${data.artifacts.html}`, `network: ${data.artifacts.network}`];
+    return section('Artifacts', lines.join('\n'));
+}
+function align(label, marker, width) {
+    if (!marker)
+        return label;
+    return `${label.padEnd(width)}${marker}`;
+}
+function section(title, body) {
+    return `### ${title}\n${body}`;
+}