/** * Flow Discovery — autonomous mode. * * No flow.json, no video, no narration: a Claude-driven agent explores the * dev app by trial and error, figures out the UI flow for a doc page, locks * it into pipeline/flows/{slug}.json, then replays it through the normal * capture pipeline (screenshots + MDX update). * * Usage: * node pipeline/discover.js apps/scroller.mdx * node pipeline/discover.js apps/new-feature.mdx --goal "Create a Weather app and preview it" * node pipeline/discover.js apps/scroller.mdx --no-capture # discover + lock only * node pipeline/discover.js apps/scroller.mdx --max-actions 40 * * How it works (observe → decide → act): * 1. Restores the saved Playwright session (run save-session.js first) * 2. Loop: digest the page's interactive elements → ask `claude --print` * for ONE next action → execute it → feed the result (incl. failures) * back into the next prompt * 3. Claude marks "step boundaries" — page states worth documenting — and * the successful actions between boundaries become that step's replay * recipe * 4. The synthesized flow.json is validated and saved, then the standard * orchestrator replays it for clean styled screenshots and MDX updates * * Costs one `claude --print` call per action (~10-20s each). A typical app * flow discovers in 10-25 actions. */ const path = require('path'); const fs = require('fs'); const { spawnSync } = require('child_process'); const config = require('./config'); const { callClaudeJSON, callClaude } = require('./claude-client'); const { loginToDevApp, slugFromMdxPath, parseMdxSteps } = require('./flow-mapper'); const { runAction } = require('./screenshot-capture'); const DOCS_ROOT = path.resolve(__dirname, '..', config.DOCS_DIR); const FLOWS_DIR = path.join(__dirname, 'flows'); const SESSION_FILE = path.resolve(__dirname, '..', 'tmp', 'session.json'); const MAX_CONSECUTIVE_FAILURES = 4; // ── Observation ────────────────────────────────────────────────────────────── /** * Build a compact digest of the page: URL, visible headings, and interactive * elements with suggested Playwright selectors. */ async function observe(page) { const raw = await page.evaluate(() => { const els = []; const seen = new Set(); const counters = {}; const visible = el => { const r = el.getBoundingClientRect(); const style = getComputedStyle(el); return r.width > 2 && r.height > 2 && r.bottom > -50 && r.top < innerHeight * 1.5 && style.visibility !== 'hidden' && style.display !== 'none'; }; document.querySelectorAll( 'button, a[href], input, select, textarea, [role="button"], [role="menuitem"], [role="tab"]' ).forEach(el => { if (!visible(el) || els.length >= 80) return; const tag = el.tagName.toLowerCase(); const kind = el.getAttribute('role') || tag; counters[kind] = (counters[kind] || 0); const info = { kind, idx: counters[kind] }; const text = (el.innerText || el.value || '').trim().replace(/\s+/g, ' ').slice(0, 60); if (text) info.text = text; if (el.placeholder) info.placeholder = el.placeholder; const aria = el.getAttribute('aria-label'); if (aria) info.aria = aria; if (el.name) info.name = el.name; if (el.disabled) info.disabled = true; if (tag === 'select') { info.options = Array.from(el.options).map(o => o.label).slice(0, 10); info.selected = el.options[el.selectedIndex] ? el.options[el.selectedIndex].label : null; // Nearby label text helps identify the field const wrap = el.closest('div, label, fieldset'); const label = wrap ? (wrap.innerText || '').trim().split('\n')[0].slice(0, 40) : null; if (label && label !== info.selected) info.label = label; } const key = JSON.stringify(info); if (seen.has(key)) return; seen.add(key); counters[kind]++; els.push(info); }); const headings = Array.from(document.querySelectorAll('h1, h2, h3, [role="dialog"] h1, [role="dialog"] h2')) .map(h => (h.innerText || '').trim().replace(/\s+/g, ' ').slice(0, 80)) .filter(Boolean).slice(0, 10); const dialogOpen = !!document.querySelector('[role="dialog"], [class*="modal"]:not([style*="display: none"])'); return { url: location.pathname + location.hash, headings, dialogOpen, elements: els }; }); // Attach suggested selectors (computed Node-side so quoting stays sane) for (const el of raw.elements) { el.suggest = suggestSelector(el); } return raw; } function suggestSelector(el) { const esc = s => String(s).replace(/'/g, "\\'"); if (el.kind === 'select') return `select >> nth=${el.idx}`; if (el.kind === 'textarea') return el.placeholder ? `textarea[placeholder*='${esc(el.placeholder.slice(0, 25))}']` : `textarea >> nth=${el.idx}`; if (el.kind === 'input') { if (el.placeholder) return `input[placeholder*='${esc(el.placeholder.slice(0, 25))}']`; if (el.name) return `input[name='${esc(el.name)}']`; return `input >> nth=${el.idx}`; } if (el.kind === 'a' || el.kind === 'link') return el.text ? `a:has-text('${esc(el.text.slice(0, 30))}')` : `a >> nth=${el.idx}`; if (el.text) return `${el.kind === 'button' ? 'button' : `[role="${el.kind}"]`}:has-text('${esc(el.text.slice(0, 30))}')`; if (el.aria) return `[aria-label*='${esc(el.aria.slice(0, 30))}']`; return `${el.kind} >> nth=${el.idx}`; } function formatObservation(obs) { const lines = [`URL: ${obs.url}${obs.dialogOpen ? ' [dialog/modal is open]' : ''}`]; if (obs.headings.length) lines.push(`Headings: ${obs.headings.join(' | ')}`); lines.push('Interactive elements (suggested selector ⇒ details):'); for (const el of obs.elements) { const bits = []; if (el.text) bits.push(`"${el.text}"`); if (el.placeholder) bits.push(`placeholder="${el.placeholder}"`); if (el.aria) bits.push(`aria="${el.aria}"`); if (el.label) bits.push(`field="${el.label}"`); if (el.options) bits.push(`options=[${el.options.join(', ')}] selected="${el.selected}"`); if (el.disabled) bits.push('DISABLED'); lines.push(` ${el.suggest} ⇒ ${el.kind} ${bits.join(' ')}`); } return lines.join('\n'); } // ── Decision prompt ─────────────────────────────────────────────────────────── function buildSystemPrompt(goal, mdxTitles) { return `You are an autonomous UI explorer for Pickcel, a React digital-signage SaaS console at ${config.DEV_URL}. GOAL: ${goal} You control a real browser ONE action at a time, discovering the exact UI flow so it can be documented with annotated screenshots. After each action you receive the new page state. Respond with ONLY a JSON object (no prose, no fences): { "thought": "brief reasoning about the current state and what to do", "stepBoundary": false, "stepTitle": "", "annotate": "", "action": { "type": "click|fill|selectOption|goto|scroll|wait|done", "selector": "", "value": "", "label": "", "url": "", "ms": 0 } } stepBoundary semantics: - Set stepBoundary=true when the page state you are CURRENTLY looking at completes a documentation-worthy step (you'll typically mark 5-12 boundaries total). - stepTitle: short imperative title for that step. annotate: selector of the key element to ring in the screenshot. - Mark the boundary in the SAME response as your NEXT action (the boundary describes the present, the action moves forward). Action rules: - ONE action per response. Prefer the suggested selectors from the element list. - Native