explorbot 0.2.2 → 0.2.3

package/boat/prima/src/pw-parser.ts

@@ -0,0 +1,17 @@
+const FUNCTION_SHAPE = /^(async\s+)?(function\b|\()/;
+
+export function isFunctionExpression(expr: string): { valid: boolean; error?: string } {
+  const trimmed = expr.trim();
+  if (!trimmed) return { valid: false, error: 'empty expression; pass a function like ({ page }) => ...' };
+  if (!FUNCTION_SHAPE.test(trimmed)) return { valid: false, error: 'expression must be a function like ({ page }) => ... destructuring the playwright objects it needs' };
+  try {
+    new Function(`return (${trimmed})`);
+  } catch (e) {
+    return { valid: false, error: `not a valid function expression: ${(e as Error).message}` };
+  }
+  return { valid: true };
+}
+
+export function toCodeceptWrapper(expr: string): string {
+  return `I.usePlaywrightTo('pw', async (playwright) => (${expr.trim()})(playwright))`;
+}

package/boat/prima/src/pw-registry.ts

@@ -0,0 +1,75 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const DEFAULT_TITLE = 'default';
+const DEFAULT_BROWSER = 'chromium';
+
+export function registryDir(): string {
+  if (process.platform === 'darwin') return path.join(os.homedir(), 'Library', 'Caches', 'ms-playwright', 'b');
+  if (process.platform === 'win32') return path.join(process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'), 'ms-playwright', 'b');
+  return path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), 'ms-playwright', 'b');
+}
+
+export function readDescriptors(dir = registryDir()): PwServerDescriptor[] {
+  const descriptors: PwServerDescriptor[] = [];
+  for (const fileName of listFiles(dir)) {
+    const descriptor = parseDescriptor(path.join(dir, fileName));
+    if (descriptor) descriptors.push(descriptor);
+  }
+  return descriptors;
+}
+
+export function selectDescriptor(descriptors: PwServerDescriptor[], opts: { workspaceDir: string; title?: string }): { match?: PwServerDescriptor; candidates: PwServerDescriptor[] } {
+  const workspaceDir = path.resolve(opts.workspaceDir);
+  const candidates = descriptors.filter((descriptor) => path.resolve(descriptor.workspaceDir) === workspaceDir);
+  if (!candidates.length) return { candidates };
+
+  if (opts.title) {
+    const titled = candidates.find((descriptor) => descriptor.title === opts.title);
+    if (titled) return { match: titled, candidates };
+    return { candidates };
+  }
+
+  const preferred = candidates.find((descriptor) => descriptor.title === DEFAULT_TITLE);
+  if (preferred) return { match: preferred, candidates };
+  if (candidates.length === 1) return { match: candidates[0], candidates };
+  return { candidates };
+}
+
+function listFiles(dir: string): string[] {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+function parseDescriptor(file: string): PwServerDescriptor | null {
+  let data: any;
+  try {
+    data = JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+
+  if (!data?.endpoint || !data?.title || !data?.workspaceDir) return null;
+
+  return {
+    file,
+    title: data.title,
+    endpoint: data.endpoint,
+    workspaceDir: data.workspaceDir,
+    browserName: data.browser?.browserName || DEFAULT_BROWSER,
+    playwrightLib: data.playwrightLib || '',
+  };
+}
+
+export interface PwServerDescriptor {
+  file: string;
+  title: string;
+  endpoint: string;
+  workspaceDir: string;
+  browserName: string;
+  playwrightLib: string;
+}

package/dist/bin/explorbot-cli.js

@@ -36,6 +36,7 @@ function buildExplorBotOptions(from, options) {
         headless: options.headless,
         incognito: options.incognito,
         session: options.session,
+        applicationSpec: options.spec,
     };
 }
 function addCommonOptions(cmd) {
@@ -47,6 +48,7 @@ function addCommonOptions(cmd) {
         .option('-s, --show', 'Show browser window')
         .option('--headless', 'Run browser in headless mode')
         .option('--incognito', 'Run without recording experiences')
+        .option('--spec <path>', 'Use a Docbot application spec directory or index.md')
         .option('--session [file]', 'Save/restore browser session from file');
 }
 async function startTUI(explorBot) {
@@ -341,6 +343,13 @@ program
         process.exit(1);
     }
 });
+program
+    .command('sites')
+    .description('List sites registered in the global installation')
+    .action(async () => {
+    const { SitesCommand } = await import('../src/commands/sites-command.js');
+    await new SitesCommand(new ExplorBot()).execute('');
+});
 addCommonOptions(program.command('rerun <filename> [index]').description('Re-run generated tests with AI auto-healing')).action(async (filename, index, options) => {
     try {
         const explorBot = new ExplorBot(buildExplorBotOptions(undefined, options));
@@ -373,17 +382,29 @@ addCommonOptions(program
 });
 program
     .command('init')
-    .description('Initialize a new project with configuration')
-    .option('-c, --config-path <path>', 'Path for the config file', './explorbot.config.js')
+    .description('Initialize configuration for a project or for this machine')
+    .option('-c, --config-path <path>', 'Path for the config file')
     .option('-f, --force', 'Overwrite existing config file')
     .option('-p, --path <path>', 'Working directory for initialization')
+    .option('-g, --global', 'Configure explorbot in ~/.explorbot to run from anywhere')
+    .option('--provider <name>', `AI provider for the global config: ${Object.keys(PROVIDERS).join(', ')}`)
+    .option('--api-key <key>', 'API key stored in ~/.explorbot/.env')
     .action(async (options) => {
-    const { runInitCommand } = await import('../src/commands/init-command.js');
-    runInitCommand({
-        configPath: options.configPath,
-        force: options.force,
-        path: options.path,
-    });
+    try {
+        const { runInit } = await import('../src/commands/init-command.js');
+        await runInit({
+            configPath: options.configPath,
+            force: options.force,
+            path: options.path,
+            global: options.global,
+            provider: options.provider,
+            apiKey: options.apiKey,
+        });
+    }
+    catch (error) {
+        console.error('Failed:', error instanceof Error ? error.message : 'Unknown error');
+        process.exit(1);
+    }
 });
 program
     .command('clean [target]')
@@ -626,7 +647,7 @@ program
         };
         const explorBot = new ExplorBot(mainOptions);
         await explorBot.start();
-        await explorBot.agentNavigator().visit(url);
+        await explorBot.visit(url);
         const { ContextCommand } = await import('../src/commands/context-command.js');
         const argParts = [];
         if (options.full)
@@ -650,7 +671,7 @@ addCommonOptions(program.command('shell <url> <command>').description('Execute a
     try {
         const explorBot = new ExplorBot(buildExplorBotOptions(url, options));
         await explorBot.start();
-        await explorBot.agentNavigator().visit(url);
+        await explorBot.visit(url);
         const action = explorBot.getExplorer().action();
         await action.execute(command);
         log('Command executed successfully');
@@ -671,10 +692,11 @@ browserCmd
     .description('Launch a persistent browser server')
     .option('-s, --show', 'Launch browser in headed mode (visible window)')
     .option('--headless', 'Launch browser in headless mode')
+    .option('--instance <name>', 'Named browser instance (lowercase letters, digits, dashes)')
     .option('-c, --config <path>', 'Path to configuration file')
     .option('-p, --path <path>', 'Working directory path')
     .action(async (options) => {
-    const { launchServer, removeEndpointFile } = await import('../src/browser-server.js');
+    const { launchServer, removeEndpointFile, keepServerRunning } = await import('../src/browser-server.js');
     await ConfigParser.getInstance().loadConfig({
         config: options.config,
         path: options.path,
@@ -688,45 +710,34 @@ browserCmd
     const server = await launchServer({
         browser: config.playwright.browser,
         show,
+    }, options.instance);
+    await keepServerRunning(async () => {
+        await server.close();
+        removeEndpointFile(options.instance);
     });
-    console.log('Browser server is running. Press Ctrl+C to stop.');
-    const cleanup = () => {
-        console.log('\nStopping browser server...');
-        server.close();
-        removeEndpointFile();
-        process.exit(0);
-    };
-    process.on('SIGINT', cleanup);
-    process.on('SIGTERM', cleanup);
 });
 browserCmd
     .command('stop')
     .description('Stop a running browser server')
+    .option('--instance <name>', 'Named browser instance (lowercase letters, digits, dashes)')
     .option('-c, --config <path>', 'Path to configuration file')
     .option('-p, --path <path>', 'Working directory path')
     .action(async (options) => {
-    const { getAliveEndpoint, removeEndpointFile } = await import('../src/browser-server.js');
+    const { stopServer } = await import('../src/browser-server.js');
     await ConfigParser.getInstance().loadConfig({
         config: options.config,
         path: options.path,
     });
-    const endpoint = await getAliveEndpoint();
-    if (!endpoint) {
+    if (!(await stopServer(options.instance))) {
         console.log('No running browser server found.');
         process.exit(0);
     }
-    try {
-        const { chromium } = await import('playwright-core');
-        const browser = await chromium.connect(endpoint, { timeout: 3000 });
-        await browser.close();
-    }
-    catch { }
-    removeEndpointFile();
     console.log('Browser server stopped.');
 });
 browserCmd
     .command('status')
     .description('Check if a browser server is running')
+    .option('--instance <name>', 'Named browser instance (lowercase letters, digits, dashes)')
     .option('-c, --config <path>', 'Path to configuration file')
     .option('-p, --path <path>', 'Working directory path')
     .action(async (options) => {
@@ -735,7 +746,7 @@ browserCmd
         config: options.config,
         path: options.path,
     });
-    const endpoint = await getAliveEndpoint();
+    const endpoint = await getAliveEndpoint(options.instance);
     if (endpoint) {
         console.log(`Browser server is running at: ${endpoint}`);
     }
@@ -790,8 +801,10 @@ program
 });
 import { createApiCommands } from "../boat/api-tester/src/cli.js";
 import { createDocsCommands } from "../boat/doc-collector/src/cli.js";
+import { createPrimaCommands } from "../boat/prima/src/cli.js";
 program.addCommand(createApiCommands('api'));
 program.addCommand(createDocsCommands('docs'));
+program.addCommand(createPrimaCommands('prima'));
 const envHelp = () => {
     const width = Math.max(...EXPLORBOT_ENV_VARS.map((v) => v.name.length));
     const rows = EXPLORBOT_ENV_VARS.map((v) => `  ${v.name.padEnd(width)}  ${v.description}`).join('\n');

package/dist/boat/api-tester/src/apibot.js

@@ -30,7 +30,7 @@ export class ApiBot {
         }
     }
     async start() {
-        this.config = await this.configParser.loadConfig({ config: this.options.config, path: this.options.path });
+        this.config = await this.configParser.loadConfig({ config: this.options.config, path: this.options.path, endpoint: this.options.endpoint });
         this.provider = new AIProvider(this.config.ai);
         await this.provider.validateConnection();
         this.apiClient = new ApiClient(this.config.api.baseEndpoint, this.config.api.headers || {}, {
@@ -86,11 +86,12 @@ export class ApiBot {
     agentCurler() {
         return (this.agents.curler ||= this.createAgent(({ ai, apiClient, requestState }) => new Curler(ai, apiClient, requestState, this.reporter)));
     }
-    async plan(endpoint, opts = {}) {
+    async plan(target, opts = {}) {
         if (opts.fresh) {
             this.currentPlan = undefined;
             this.agents.chief = undefined;
         }
+        const endpoint = this.configParser.resolveEndpointPath(target);
         const chief = this.agentChief();
         const specDefinition = this.getEndpointDefinition(endpoint);
         this.currentPlan = await chief.plan(endpoint, { style: opts.style, specDefinition });

package/dist/boat/api-tester/src/cli.js

@@ -40,7 +40,7 @@ export function createApiCommands(name = 'api') {
     addCommonOptions(cmd.command('plan <endpoint>').description('Generate test plan for an API endpoint').option('--style <style>', 'Planning style: basename of a file in rules/chief/styles/').option('--fresh', 'Start planning from scratch')).action(async (endpoint, options) => {
         setPreserveConsoleLogs(true);
         try {
-            const bot = new ApiBot(buildOptions(options));
+            const bot = new ApiBot({ ...buildOptions(options), endpoint });
             await bot.start();
             await bot.plan(endpoint, { style: options.style, fresh: options.fresh });
             const plan = bot.getCurrentPlan();
@@ -104,7 +104,7 @@ export function createApiCommands(name = 'api') {
     addCommonOptions(cmd.command('explore <endpoint>').description('Full cycle: plan all styles, execute tests, re-plan')).action(async (endpoint, options) => {
         setPreserveConsoleLogs(true);
         try {
-            const bot = new ApiBot(buildOptions(options));
+            const bot = new ApiBot({ ...buildOptions(options), endpoint });
             await bot.start();
             const styles = Object.keys(getStyles());
             let totalPassed = 0;

package/dist/boat/api-tester/src/config.js

@@ -9,11 +9,13 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import path, { resolve } from 'node:path';
 import { parseEnv } from 'node:util';
-import { EXPLORBOT_CONFIG_PATHS, createModel, materializeKnowledge, resolveModel, resolveOutputRoot } from "../../../src/config.js";
+import { ConfigMissingError, EXPLORBOT_CONFIG_PATHS, createModel, envConfigRequested, materializeKnowledge, missingConfigMessage, resolveConfigModels, resolveModel, resolveOutputRoot } from "../../../src/config.js";
+import { findGlobalConfig, globalEnvPath, isGlobalConfigPath, registerSite, resolveSiteTarget } from "../../../src/global-config.js";
 export class ApibotConfigParser {
     static instance;
     config = null;
     configPath = null;
+    site = null;
     constructor() { }
     static getInstance() {
         if (!ApibotConfigParser.instance) {
@@ -34,6 +36,7 @@ export class ApibotConfigParser {
         if (options?.path) {
             process.chdir(resolve(options.path));
         }
+        ApibotConfigParser.loadEnv(globalEnvPath());
         ApibotConfigParser.loadEnv('.env');
         const resolvedPath = options?.config || this.findConfigFile();
         if (!resolvedPath) {
@@ -59,7 +62,12 @@ export class ApibotConfigParser {
                 };
             }
             this.config = this.mergeWithDefaults(loadedConfig);
+            await resolveConfigModels(this.config.ai);
             this.configPath = resolvedPath;
+            this.site = null;
+            if (isGlobalConfigPath(resolvedPath)) {
+                this.enterGlobalMode(this.config, options?.endpoint);
+            }
             this.validateConfig(this.config);
             return this.config;
         }
@@ -79,10 +87,23 @@ export class ApibotConfigParser {
     }
     getOutputDir() {
         const config = this.getConfig();
+        return path.join(this.getProjectRoot(), config.dirs?.output || 'output');
+    }
+    getProjectRoot() {
+        if (this.site)
+            return this.site.dir;
         const configPath = this.getConfigPath();
         if (!configPath)
             throw new Error('Config path not found');
-        return path.join(path.dirname(configPath), config.dirs?.output || 'output');
+        return path.dirname(configPath);
+    }
+    resolveEndpointPath(endpoint) {
+        if (!this.site)
+            return endpoint;
+        const resolved = resolveSiteTarget(endpoint, this.site.url);
+        if (resolved.baseUrl !== this.site.url)
+            return endpoint;
+        return resolved.path;
     }
     getPlansDir() {
         return path.join(this.getOutputDir(), 'plans');
@@ -92,21 +113,26 @@ export class ApibotConfigParser {
     }
     getKnowledgeDir() {
         const config = this.getConfig();
-        const configPath = this.getConfigPath();
-        if (!configPath)
-            throw new Error('Config path not found');
-        return path.join(path.dirname(configPath), config.dirs?.knowledge || 'knowledge');
+        return path.join(this.getProjectRoot(), config.dirs?.knowledge || 'knowledge');
     }
     ensureDirectory(dirPath) {
         if (!existsSync(dirPath)) {
             mkdirSync(dirPath, { recursive: true });
         }
     }
+    enterGlobalMode(config, endpoint) {
+        const site = resolveSiteTarget(endpoint);
+        this.site = registerSite(site.baseUrl);
+        config.dirs = { output: 'output', knowledge: 'knowledge' };
+        config.api = { ...config.api, baseEndpoint: site.baseUrl };
+        if (process.env.EXPLORBOT_API_SPEC)
+            config.api.spec = [process.env.EXPLORBOT_API_SPEC];
+    }
     async loadEnvConfig() {
         const provider = process.env.EXPLORBOT_AI_PROVIDER;
         const modelSpec = process.env.EXPLORBOT_AI_MODEL;
         if (!provider && !modelSpec) {
-            throw new Error('No configuration file found. Create apibot.config.js or set EXPLORBOT_URL and EXPLORBOT_AI_PROVIDER environment variables');
+            throw new ConfigMissingError(missingConfigMessage('apibot.config.js'));
         }
         if (modelSpec && !provider && !modelSpec.includes('/')) {
             throw new Error('EXPLORBOT_AI_MODEL needs a provider — set EXPLORBOT_AI_PROVIDER, or write it as "provider/model-id"');
@@ -149,7 +175,9 @@ export class ApibotConfigParser {
             if (existsSync(fullPath))
                 return fullPath;
         }
-        return null;
+        if (envConfigRequested())
+            return null;
+        return findGlobalConfig();
     }
     async loadConfigModule(configPath) {
         const ext = configPath.split('.').pop();

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

@@ -47,6 +47,7 @@ export function createDocsCommands(name = 'docs') {
             console.log(`Skipped ${result.skipped.length} page(s)`);
             console.log(`Spec index: ${result.indexPath}`);
             console.log(`Pages dir: ${path.join(result.outputDir, 'pages')}`);
+            console.log(`Use in Explorbot: npx explorbot start ${startPath} --spec "${result.outputDir}"`);
             await bot.stop();
             process.exit(0);
         }

package/dist/boat/doc-collector/src/docs-renderer.js

@@ -1,6 +1,8 @@
 import path from 'node:path';
-import { buildStateGraph, renderMermaidFromGraph, renderStateMapFromGraph } from "./state-diagram.js";
+import matter from 'gray-matter';
+import { APPLICATION_SPEC_FORMAT, APPLICATION_SPEC_VERSION } from "../../../src/application-spec-contract.js";
 import { normalizeInlineText } from "../../../src/utils/strings.js";
+import { buildStateGraph, renderMermaidFromGraph, renderPageStateDiagram, renderStateMapFromGraph } from "./state-diagram.js";
 function renderPageDocumentation(state, documentation, screenshots = []) {
     const lines = [];
     lines.push(`# ${state.url}`);
@@ -25,6 +27,13 @@ function renderPageDocumentation(state, documentation, screenshots = []) {
         }
     }
     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('');
@@ -83,7 +92,11 @@ function renderPageDocumentation(state, documentation, screenshots = []) {
         }
         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, startPath, pages, skipped, maxPages) {
     const lines = [];
@@ -97,9 +110,10 @@ function renderSpecIndex(outputDir, startPath, pages, skipped, maxPages) {
     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/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();