@hover-dev/core 0.16.0 → 0.18.0

package/dist/specs/writeSpec.js

@@ -17,13 +17,15 @@
  * `assertions` field on the input.
  */
 import { mkdir, writeFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { humanSteps, humanStep } from './humanSteps.js';
 import { writeSidecar } from './sidecar.js';
 import { readPageObjectManifest, } from './pageObjectManifest.js';
 import { stepSignature } from './detectSharedFlows.js';
 import { slugify, firstSentence } from './text.js';
+import { markSessionSaved } from '../sessions/sessions.js';
+import { authPrefixLength, addSetupProjectToConfig } from './authFixture.js';
 /**
  * Marker the deterministic translator leaves where a captured action is a real
  * interaction but has no single-step Playwright translation (e.g. file upload,
@@ -39,6 +41,50 @@ export const OPTIMIZABLE_MARKER = '// hover:optimizable';
 export function countOptimizableMarkers(source) {
     return source.split('\n').filter(l => l.trimStart().startsWith(OPTIMIZABLE_MARKER)).length;
 }
+/** Strip the `mcp__<server>__` prefix off a Hover-MCP tool name. The server
+ *  segment is kebab-case (`hover-source`), so the class includes `-`; lazy so
+ *  the tool name (which may contain `_`) is preserved. */
+function bareTool(rawTool) {
+    return rawTool.replace(/^mcp__[a-z0-9_-]+?__/, '');
+}
+/** Tools that never belong in a crystallized spec: read-only exploration the
+ *  agent does to understand the page/code, and meta interactions like asking
+ *  the user a question. Dropped at the filter so they don't reach the body or
+ *  the prose. (browser_* read tools are also dropped inside translateStep.) */
+function isExploratoryTool(rawTool) {
+    const tool = bareTool(rawTool);
+    // take_screenshot is the grounded-mode viewport screenshot (perceive-only,
+    // like browser_take_screenshot) — never a replayable spec step.
+    return tool === 'list_source' || tool === 'read_source' || tool === 'ask_user' || tool === 'take_screenshot';
+}
+/**
+ * Dirty-recording cleanup. An agent run is exploratory: it makes failed
+ * attempts and reads source to orient itself. Those are captured as steps (and
+ * kept in the sidecar), but the runnable spec must reflect only
+ * the working flow. Drop step-kind entries that errored or are pure
+ * exploration; keep everything else (user/done/ai markers and successful
+ * actions) untouched. Returns the filtered steps plus how many were omitted.
+ */
+function filterDirtySteps(steps) {
+    let omitted = 0;
+    const clean = steps.filter(s => {
+        if (s.kind !== 'step' || !s.tool)
+            return true; // non-action entries pass through
+        if (isFlowMarker(s))
+            return false; // mark_flow is a split boundary, not an action — drop, don't count
+        // record_candidate is a QA capture signal, not a replayable browser action —
+        // drop it (silently, like mark_flow) so it never renders as a junk
+        // `hover:optimizable` step in the crystallized spec.
+        if (bareTool(s.tool) === 'record_candidate')
+            return false;
+        if (s.isError || isExploratoryTool(s.tool)) {
+            omitted++;
+            return false;
+        }
+        return true;
+    });
+    return { clean, omitted };
+}
 export class SpecExistsError extends Error {
     slug;
     path;
@@ -49,37 +95,191 @@ export class SpecExistsError extends Error {
         this.name = 'SpecExistsError';
     }
 }
+/** Stored-step form of a redacted credential — a code expression, so it both
+ *  renders as `fill(process.env.X ?? '')` and survives JSON (the sidecar)
+ *  without ever holding the secret. */
+function envExpr(envVar) {
+    return `process.env.${envVar} ?? ''`;
+}
+/** Replace credential fill values with `process.env.<envVar>` expressions,
+ *  ONCE, before both rendering and sidecar persistence. Pure — clones touched
+ *  steps, leaves the rest untouched. */
+function redactSteps(steps, redactions) {
+    const map = new Map(redactions.filter(r => r.value).map(r => [r.value, r.envVar]));
+    if (map.size === 0)
+        return steps;
+    return steps.map(s => {
+        if (s.kind !== 'step' || !s.input)
+            return s;
+        const input = s.input;
+        // Match on the BARE tool name — grounded fills arrive as
+        // `mcp__hover-control__fill_control`, playwright ones as bare `browser_type`.
+        const tool = (s.tool ?? '').replace(/^mcp__[a-z0-9_-]+?__/, '');
+        // A single typed/filled value: browser_type uses `text`, the grounded
+        // fill_control uses `value`. WITHOUT the fill_control case, credentials typed
+        // via grounded actuation (the default mode) leaked into the spec unredacted.
+        const valueKey = tool === 'browser_type' ? 'text' : tool === 'fill_control' ? 'value' : null;
+        if (valueKey && typeof input[valueKey] === 'string' && map.has(input[valueKey])) {
+            return { ...s, input: { ...input, [valueKey]: envExpr(map.get(input[valueKey])) } };
+        }
+        if (tool === 'browser_fill_form' && Array.isArray(input.fields)) {
+            let changed = false;
+            const fields = input.fields.map(f => {
+                if (f && typeof f.value === 'string' && map.has(f.value)) {
+                    changed = true;
+                    return { ...f, value: envExpr(map.get(f.value)) };
+                }
+                return f;
+            });
+            if (changed)
+                return { ...s, input: { ...input, fields } };
+        }
+        return s;
+    });
+}
+/** Render a fill value: a redacted `process.env.…` expression emits as CODE;
+ *  anything else as a string literal. */
+function renderFillValue(value) {
+    return /^process\.env\b/.test(value) ? value : JSON.stringify(value);
+}
+/** True for a `mark_flow` boundary step (the agent's per-feature split marker).
+ *  Matches the raw tool name with or without the `mcp__<server>__` prefix. */
+function isFlowMarker(s) {
+    return s.kind === 'step' && /(^|__)mark_flow$/.test(String(s.tool ?? ''));
+}
 export async function writeSpec(opts) {
-    const slug = slugify(opts.name);
-    if (!slug)
+    if (!slugify(opts.name))
         throw new Error('spec name must contain at least one alphanumeric character');
-    if (!opts.steps.some(s => s.kind === 'step')) {
+    if (!opts.steps.some((s) => s.kind === 'step' && !isFlowMarker(s))) {
         throw new Error('spec must contain at least one tool step to replay');
     }
+    // One run → one file. Frontend runs are NOT auto-split: a single user journey
+    // (especially a multi-step single-page form) is stateful and sequential — each
+    // step depends on the prior steps' state, so chopping it into per-section files
+    // yields fragments that each fail when run standalone. Splitting into truly
+    // independent journeys is a deliberate refactor (the architecture pass), not
+    // something the agent improvises mid-run. (API checks ARE split by module in
+    // writeSecuritySpec — those are stateless and independently replayable.)
+    return writeOneSpec(opts, slugify(opts.name), opts.name, opts.steps);
+}
+/** Write ONE spec file from a (sub)set of steps. The single-file path and each
+ *  per-flow file both go through here, so rendering / sidecar / config logic is
+ *  identical whether or not the run was split. */
+async function writeOneSpec(opts, slug, displayName, rawSteps) {
+    if (!slug)
+        throw new Error('spec name must contain at least one alphanumeric character');
     const dir = join(opts.devRoot, '__vibe_tests__');
     const path = join(dir, `${slug}.spec.ts`);
     if (!opts.overwrite && existsSync(path)) {
         throw new SpecExistsError(slug, path);
     }
     await mkdir(dir, { recursive: true });
+    // Redact credentials ONCE, up front, so every downstream artifact (spec
+    // source, JSDoc header, sidecar) sees only `process.env.…` references — the
+    // literal password/username is never written anywhere.
+    const steps = redactSteps(rawSteps, opts.redactions ?? []);
     // Stage 3c: if a prior extraction left a Page Object whose flow prefixes
     // this spec, consume it (await loginPage.login(…)) instead of re-emitting
     // the steps inline. No manifest (extraction never ran) → plain spec.
+    // Dirty-recording cleanup: the agent's failed attempts (isError) and
+    // read-only exploration (list_source / read_source) are real captured steps
+    // but must NOT land in the runnable spec — only the working flow should. They
+    // stay in `steps` (hence the sidecar) as the full-fidelity record the
+    // optimization pass reads; the spec renders from the filtered view, with a
+    // JSDoc note of how many were omitted.
+    const { clean: cleanSteps, omitted } = filterDirtySteps(steps);
     const manifest = await readPageObjectManifest(opts.devRoot);
-    const match = manifest ? matchPageObject(opts.steps, manifest) : null;
-    const source = renderSpec(slug, opts.name, opts.description ?? '', opts.steps, opts.assertions ?? [], match);
+    let match = manifest ? matchPageObject(cleanSteps, manifest) : null;
+    // Auth-as-fixture (debt 3): when the recorded login is detectable (credentials
+    // were redacted to process.env refs), lift it into auth.setup.ts and start
+    // specs authenticated via storageState — login then runs ONCE, not per test.
+    // Auto-on is gated to the scaffold case: with NO existing playwright.config we
+    // write one that registers the setup project, so it's self-contained. With an
+    // existing user config we can't register the setup project without editing
+    // their file (the Stage-4 approval flow), so keep today's inline login there.
+    const cleanActions = cleanSteps.filter(s => s.kind === 'step' && !!s.tool);
+    const envVars = (opts.redactions ?? []).map(r => r.envVar);
+    const detectedPrefix = authPrefixLength(cleanActions, envVars);
+    const userConfigName = PLAYWRIGHT_CONFIG_NAMES.find(n => existsSync(join(opts.devRoot, n)));
+    // Already opted in: auth.setup.ts exists from a prior approval (and the config
+    // already registers it), so engage AUTOMATICALLY — don't re-ask or re-edit.
+    const authSetupExists = existsSync(join(dir, 'auth.setup.ts'));
+    // Engage the fixture when a login is detected AND we can register the setup
+    // project: we scaffold the config (no user config), the caller approved editing
+    // it (opts.authFixture, Stage 4), or the fixture was already set up earlier.
+    const engage = detectedPrefix > 0 && (!userConfigName || opts.authFixture === true || authSetupExists);
+    const authPrefix = engage ? detectedPrefix : 0;
+    const authFile = engage ? AUTH_STATE_FILE : undefined;
+    let authFixtureOffer;
+    if (authFile) {
+        // Login lifted to setup.ts → a login Page Object fold would double it up.
+        match = null;
+        try {
+            await writeFile(join(dir, 'auth.setup.ts'), renderAuthSetup(cleanActions.slice(0, authPrefix), authFile, opts.startUrl), 'utf-8');
+        }
+        catch { /* auth.setup generation is best-effort, never breaks Save */ }
+        // Approved edit to an EXISTING user config → register the setup project.
+        if (userConfigName && opts.authFixture) {
+            try {
+                const p = join(opts.devRoot, userConfigName);
+                const edited = addSetupProjectToConfig(readFileSync(p, 'utf-8'));
+                if (edited)
+                    await writeFile(p, edited, 'utf-8');
+            }
+            catch { /* config edit is best-effort; the spec still has the paste hint */ }
+        }
+    }
+    else if (detectedPrefix > 0 && userConfigName && !opts.authFixture) {
+        // Login detected but a user config exists and edit wasn't approved → keep
+        // login inline, and surface the proposed config edit for the UI to offer.
+        try {
+            const proposed = addSetupProjectToConfig(readFileSync(join(opts.devRoot, userConfigName), 'utf-8'));
+            // Absolute path so the extension can read the file directly (for the diff
+            // preview) without knowing the project root.
+            if (proposed)
+                authFixtureOffer = { configPath: join(opts.devRoot, userConfigName), proposedConfig: proposed };
+        }
+        catch { /* offer is best-effort */ }
+    }
+    // Debt-2: a Tier-1 (client-resettable) recipe → generate the shared
+    // resetState() helper and call it in a beforeEach so the spec re-enters from a
+    // clean state every run. Tier 2/3 emit no reset (backend state isn't
+    // client-resettable). Best-effort: helper generation must never break Save.
+    const emitReset = opts.resetRecipe?.tier === 1;
+    if (emitReset) {
+        try {
+            await ensureResetStateHelper(opts.devRoot, opts.resetRecipe.storageKeys ?? []);
+        }
+        catch { /* helper generation is best-effort */ }
+    }
+    const source = renderSpec(slug, displayName, opts.description ?? '', cleanSteps, opts.assertions ?? [], match, omitted, opts.startUrl, emitReset, authPrefix, authFile);
     await writeFile(path, source, 'utf-8');
+    // Specs use relative URLs (page.goto("/")), which need a `baseURL` in the
+    // project's Playwright config. If the project has NO config at all, the saved
+    // spec fails on the first goto with "Cannot navigate to invalid URL" — which
+    // breaks Hover's core promise that the saved artifact is plain Playwright that
+    // just runs. Scaffold a minimal config in that case. Best-effort: it must
+    // never break Save-as-spec, and it never overwrites an existing config.
+    try {
+        await ensurePlaywrightConfig(opts.devRoot, steps, opts.startUrl, authFile);
+    }
+    catch { /* config scaffolding is best-effort */ }
     // Persist the structured session next to the spec so cross-session
     // extraction (F4) and the optimization pass (F7) read real SpecStep[]
     // instead of parsing the generated code. Lands in .hover/, which
     // Playwright's *.spec.ts glob never collects.
     await writeSidecar(opts.devRoot, {
         slug,
-        name: opts.name,
-        steps: opts.steps,
+        name: displayName,
+        steps,
         assertions: opts.assertions ?? [],
     });
-    return { path, slug };
+    // Session-ledger patch, best-effort by contract: markSessionSaved swallows
+    // its own failures — it must never break Save-as-spec.
+    const promptText = rawSteps.find(s => s.kind === 'user')?.text;
+    if (promptText)
+        await markSessionSaved(opts.devRoot, promptText, slug);
+    return { path, slug, files: [{ path, slug, flow: displayName }], authFixtureOffer };
 }
 // Escape sequences that would prematurely terminate the JSDoc block.
 // (Backtick literal of close-comment sequence omitted on purpose — see how
@@ -106,13 +306,16 @@ function collectExpected(assertions, doneSummary) {
     }
     return [];
 }
-function renderSpec(slug, displayName, description, steps, assertions, match) {
+function renderSpec(slug, displayName, description, steps, assertions, match, omitted = 0, startUrl, emitReset = false, 
+// Auth-as-fixture: number of leading ACTION steps that form the login flow
+// (lifted into auth.setup.ts) and the storageState path the spec reuses. When
+// authFile is set, the login prefix is skipped from the body and the spec
+// starts already authenticated via `test.use({ storageState })`.
+authPrefix = 0, authFile) {
     const userMsg = steps.find(s => s.kind === 'user');
     const doneMsg = [...steps].reverse().find(s => s.kind === 'done');
     // Plain-English step + expected blocks for the JSDoc header. QA / PMs
-    // can read these without grokking Playwright API; the same prose also
-    // populates the Step column when the user exports the session to Xray
-    // CSV via writeCaseCsv.
+    // can read these without grokking the Playwright API.
     const proseSteps = humanSteps(steps);
     const expectedLines = collectExpected(assertions, doneMsg?.summary);
     // ── Walk the steps into the test body first, so we know whether any F6
@@ -126,7 +329,12 @@ function renderSpec(slug, displayName, description, steps, assertions, match) {
     let pageVar = 'page';
     let popupCount = 0;
     let usesContext = false;
-    const actions = steps.filter(s => s.kind === 'step' && !!s.tool);
+    // Auth-as-fixture: drop the leading login steps from the business spec — they
+    // run once in auth.setup.ts, and `test.use({ storageState })` (added below)
+    // makes this spec start authenticated. Slicing keeps the popup/tab-pairing
+    // logic below operating on the business flow only.
+    const allActions = steps.filter(s => s.kind === 'step' && !!s.tool);
+    const actions = authFile && authPrefix > 0 ? allActions.slice(authPrefix) : allActions;
     for (let i = 0; i < actions.length; i++) {
         const s = actions[i];
         const next = actions[i + 1];
@@ -174,6 +382,24 @@ function renderSpec(slug, displayName, description, steps, assertions, match) {
         if (s.tool !== 'browser_navigate')
             sawInteraction = true;
     }
+    // Guarantee the spec opens the app. The agent often connects to an
+    // already-open debug-Chrome tab and never calls browser_navigate, so the
+    // captured session can lack any navigation — a spec with no page.goto() runs
+    // against about:blank and every locator fails. When no navigation was
+    // captured, synthesize a leading goto from the run's target URL.
+    // Check the BUSINESS actions (login prefix already sliced out): when auth was
+    // lifted to setup.ts, its navigate goes with it, so the spec must synthesize
+    // its own goto to land on the (now authenticated) app.
+    const hasNavigate = actions.some(s => s.tool === 'browser_navigate');
+    // Fall back to the lifted login's navigate URL: with auth-as-fixture the app's
+    // goto went into auth.setup.ts, so the business spec would otherwise start on
+    // about:blank. (storageState restores the session but does NOT navigate.)
+    const gotoTarget = startUrl ?? (authFile ? firstNavigateUrl(steps) : null);
+    if (!hasNavigate && gotoTarget) {
+        const gotoBlock = [];
+        pushTestStep(gotoBlock, `Given · Open ${gotoTarget}`, [`await page.goto(${JSON.stringify(stripBaseUrl(gotoTarget))});`]);
+        body.unshift(...gotoBlock);
+    }
     // Then: Alt-click assertions group under the report's final stage.
     if (assertions.length > 0 && body.length > 0)
         body.push('');
@@ -186,6 +412,22 @@ function renderSpec(slug, displayName, description, steps, assertions, match) {
     lines.push(match
         ? `import { test, expect } from './fixtures';`
         : `import { test, expect } from '@playwright/test';`);
+    // Auth-as-fixture: reuse the session captured once by auth.setup.ts, so this
+    // spec starts already logged in (the recorded login steps live in the setup
+    // project, not inline here).
+    if (authFile) {
+        lines.push('');
+        lines.push(`test.use({ storageState: ${JSON.stringify(authFile)} });`);
+    }
+    // Debt-2: shared reset helper + a beforeEach so every run starts from a clean
+    // client state (the recipe was confirmed reproducible during recon).
+    if (emitReset) {
+        lines.push(`import { resetState } from './support/resetState';`);
+        lines.push('');
+        lines.push(`test.beforeEach(async ({ page, context }) => {`);
+        lines.push(`  await resetState(page, context);`);
+        lines.push(`});`);
+    }
     lines.push('');
     lines.push('/**');
     lines.push(` * Generated by Hover on ${new Date().toISOString().slice(0, 10)}.`);
@@ -201,8 +443,20 @@ function renderSpec(slug, displayName, description, steps, assertions, match) {
     if (expectedLines.length > 0) {
         lines.push(' *');
         lines.push(' * Expected:');
-        for (const e of expectedLines)
-            lines.push(` *   • ${jsdocEscape(e)}`);
+        for (const e of expectedLines) {
+            // Prefix EVERY line — a multi-line entry must not break out of the JSDoc
+            // block (an unprefixed continuation line escapes the comment).
+            const [head, ...rest] = jsdocEscape(e).split('\n');
+            lines.push(` *   • ${head}`);
+            for (const cont of rest)
+                lines.push(` *     ${cont}`);
+        }
+    }
+    if (omitted > 0) {
+        lines.push(' *');
+        lines.push(` * Note: ${omitted} exploratory/failed step${omitted === 1 ? '' : 's'} from the session`);
+        lines.push(' * were omitted from this runnable flow (the full capture is kept in');
+        lines.push(' * .hover/sidecars for the optimization pass).');
     }
     lines.push(' *');
     lines.push(' * Selectors prefer getByRole / getByLabel / getByTestId — generated from');
@@ -227,6 +481,58 @@ function renderSpec(slug, displayName, description, steps, assertions, match) {
     lines.push('');
     return lines.join('\n');
 }
+/** Where the auth-fixture saves/reuses the authenticated session. */
+const AUTH_STATE_FILE = 'playwright/.auth/user.json';
+/**
+ * Auth-as-fixture (debt 3): render the `auth.setup.ts` Playwright setup project
+ * from the recorded login prefix. It replays the login ONCE and saves
+ * `storageState`, which every spec then reuses via `test.use({ storageState })`
+ * — so login isn't re-run per test. `authActions` are the leading (already
+ * redacted) login steps; `startUrl` synthesizes a leading goto when the captured
+ * login lacked its own navigation (agent connected to an open tab).
+ */
+function renderAuthSetup(authActions, authFile, startUrl) {
+    const body = [];
+    if (!authActions.some(s => s.tool === 'browser_navigate') && startUrl) {
+        body.push(`  await page.goto(${JSON.stringify(stripBaseUrl(startUrl))});`);
+    }
+    for (const s of authActions) {
+        const lines = translateStep(s.tool, s.input, 'page');
+        if (lines.length === 0)
+            continue;
+        // Block-scope each step: every translated interaction declares its own
+        // `const el`, so without a block the second step redeclares it (a JS error).
+        body.push('  {');
+        for (const line of lines)
+            body.push(`    ${line}`);
+        body.push('  }');
+    }
+    body.push(`  await context.storageState({ path: authFile });`);
+    return [
+        // `expect` is used by each step's visibility prelude — import it too.
+        `import { test as setup, expect } from '@playwright/test';`,
+        ``,
+        `/**`,
+        ` * Generated by Hover — authenticates ONCE, then specs reuse the saved`,
+        ` * session via test.use({ storageState }). Login was lifted out of the specs`,
+        ` * so it no longer re-runs per test.`,
+        ` *`,
+        ` * If you have your OWN playwright.config, register this setup project so it`,
+        ` * runs before your specs:`,
+        ` *`,
+        ` *   projects: [`,
+        ` *     { name: 'setup', testMatch: /.*\\.setup\\.ts$/ },`,
+        ` *     { name: 'chromium', dependencies: ['setup'] },`,
+        ` *   ]`,
+        ` */`,
+        `const authFile = ${JSON.stringify(authFile)};`,
+        ``,
+        `setup('authenticate', async ({ page, context }) => {`,
+        ...body,
+        `});`,
+        ``,
+    ].join('\n');
+}
 /** Push one `await test.step('<label>', async () => { … })` block (4-space
  *  body indent) onto the assembled spec lines. */
 function pushTestStep(out, label, inner) {
@@ -315,9 +621,73 @@ function flowArgValues(steps) {
     }
     return out;
 }
-function translateStep(tool, rawInput, pageVar = 'page') {
+function translateStep(rawTool, rawInput, pageVar = 'page') {
     const input = (rawInput ?? {});
+    // Non-playwright Hover MCP tools keep their mcp__<server>__ prefix; strip it
+    // so the switch matches (playwright tools are already bare `browser_*`).
+    // The server-name segment is kebab-case (`hover-control`, `hover-source`), so
+    // the class MUST include `-`; a lazy quantifier stops at the first `__` so the
+    // tool name (which may contain `_`) is preserved. Missing the hyphen here used
+    // to drop every Hover-MCP step (e.g. check_control) to an optimizable marker.
+    const tool = rawTool.replace(/^mcp__[a-z0-9_-]+?__/, '');
     switch (tool) {
+        // Hover control-actuation tools → deterministic, grounded role/testid/text
+        // selectors (the agent passed these from the snapshot, so they replay).
+        case 'check_control': {
+            const role = String(input.role ?? 'radio');
+            const name = String(input.name ?? '');
+            const action = input.checked === false ? 'uncheck' : 'check';
+            // { force: true } mirrors what check_control did at record time — these
+            // are sr-only inputs behind a styled label, so a normal .check() fails
+            // the actionability hit-test ("<span> intercepts pointer events"). Force
+            // skips it, the way a label click forwards to the hidden input.
+            return [`await ${pageVar}.getByRole(${JSON.stringify(role)}, { name: ${JSON.stringify(name)}, exact: true }).${action}({ force: true });`];
+        }
+        case 'click_control':
+            return emitInteraction(groundedSelector(input, pageVar), 'click()');
+        case 'fill_control':
+            return emitInteraction(groundedSelector(input, pageVar), `fill(${renderFillValue(String(input.value ?? ''))})`);
+        case 'select_control': {
+            // A <select> is role 'combobox'; default it so a name-only step resolves.
+            const withRole = input.role ? input : { ...input, role: input.name ? 'combobox' : undefined };
+            return emitInteraction(groundedSelector(withRole, pageVar), `selectOption(${JSON.stringify(String(input.value ?? ''))})`);
+        }
+        case 'upload_file': {
+            // setInputFiles directly on the file <input> (mirrors fileInput() in
+            // mcp/actuateServer.ts) — no filechooser dialog. placeholder mode
+            // references the committed fixture; otherwise the user-supplied path.
+            const sel = fileInputSelector(input, pageVar);
+            const rel = input.placeholder ? '__vibe_tests__/fixtures/hover-placeholder.png' : String(input.path ?? '');
+            return [`await ${sel}.setInputFiles(${JSON.stringify(rel)});`];
+        }
+        case 'assert_visible': {
+            // A captured verification → an expect(...). groundedSelector already
+            // swaps a dynamic name/text for a stable anchor, so the locator is sound;
+            // here we pick the MATCHER by volatility — a dynamic value never freezes
+            // to a literal even if the agent passed matcher 'text-exact'.
+            // groundedSelector ALREADY appends `.first()` for text / dynamic-role
+            // anchors, so only add one when it didn't (avoid `.first().first()`).
+            const groundExpr = groundedSelector(input, pageVar);
+            const sel = groundExpr.endsWith('.first()') ? groundExpr : `${groundExpr}.first()`;
+            const dynamic = input.dynamic === true;
+            const expected = input.expected != null ? String(input.expected)
+                : input.observed != null ? String(input.observed) : '';
+            switch (String(input.matcher ?? 'visible')) {
+                case 'non-empty':
+                    return [`await expect(${sel}).not.toHaveText('');`];
+                case 'text-contains':
+                    return [`await expect(${sel}).toContainText(${JSON.stringify(expected)});`];
+                case 'text-exact':
+                    return dynamic
+                        ? [`await expect(${sel}).not.toHaveText('');`]
+                        : [`await expect(${sel}).toHaveText(${JSON.stringify(expected)});`];
+                case 'count':
+                    return [`await expect(${groundedSelector(input, pageVar)}).toHaveCount(${Number(input.count ?? 1)});`];
+                case 'visible':
+                default:
+                    return [`await expect(${sel}).toBeVisible();`];
+            }
+        }
         case 'browser_navigate': {
             const url = String(input.url ?? '');
             const path = stripBaseUrl(url);
@@ -337,19 +707,19 @@ function translateStep(tool, rawInput, pageVar = 'page') {
                 const target = f.name ?? f.element ?? '';
                 // Each field gets its own block scope so the per-field `const el`
                 // declarations don't collide inside the step's shared test.step closure.
-                return blockScope(emitInteraction(selectorForFormField(target, f.type, pageVar), `fill(${JSON.stringify(value)})`));
+                return blockScope(emitInteraction(selectorForFormField(target, f.type, pageVar), `fill(${renderFillValue(value)})`));
             });
         }
         case 'browser_type': {
             const text = String(input.text ?? '');
             const target = String(input.element ?? '');
-            return emitInteraction(selectorFromDescription(target, pageVar), `fill(${JSON.stringify(text)})`);
+            return emitInteraction(selectorFromDescription(target, pageVar), `fill(${renderFillValue(text)})`);
         }
         case 'browser_select_option': {
             const target = String(input.element ?? '');
             const values = input.values;
             const val = (values && values.length > 0 ? values[0] : input.value) ?? '';
-            return emitInteraction(selectorFromDescription(target, pageVar), `selectOption(${JSON.stringify(String(val))})`);
+            return emitInteraction(selectorForSelect(target, pageVar), `selectOption(${JSON.stringify(String(val))})`);
         }
         case 'browser_press_key': {
             const key = String(input.key ?? '');
@@ -371,7 +741,7 @@ function translateStep(tool, rawInput, pageVar = 'page') {
             // A real action with no single-step translation. Leave a structured
             // marker (not a TODO) so the optimization pass / seed library can
             // complete it; the deterministic draft stays runnable around it.
-            return [`${OPTIMIZABLE_MARKER}: ${tool} — no single-step translation; the optimization pass or a .hover/rules/ seed can complete this`];
+            return [`${OPTIMIZABLE_MARKER}: ${tool} — no single-step translation; the optimization pass can complete this`];
     }
 }
 /**
@@ -430,6 +800,82 @@ export function selectorFromDescription(desc, pageVar = 'page') {
         return `${pageVar}.getByText(${JSON.stringify(quoted[1])})`;
     return `${pageVar}.getByText(${JSON.stringify(trimmed)})`;
 }
+/**
+ * Selector for a Hover control-actuation step (click/fill/select_control). The
+ * agent supplied these fields straight from the snapshot, in the same priority
+ * order the actuation server resolves them — role+name → testId → text — so the
+ * crystallized selector is exactly the one that drove the action at record time
+ * (no free-form description, hence no confabulation). Mirrors
+ * `locate()` in `mcp/actuateServer.ts`.
+ */
+function groundedSelector(input, pageVar = 'page') {
+    const role = typeof input.role === 'string' ? input.role : '';
+    const name = typeof input.name === 'string' ? input.name : '';
+    const testId = typeof input.testId === 'string' ? input.testId : '';
+    const text = typeof input.text === 'string' ? input.text : '';
+    // `within` scopes to a container first (e.g. getByRole('radiogroup', { name:
+    // 'pep' })) so a repeated option label / a display:none input resolves to one
+    // match inside the right group. Mirrors locate() in mcp/actuateServer.ts.
+    const w = input.within;
+    const base = w && typeof w.role === 'string' && typeof w.name === 'string'
+        ? `${pageVar}.getByRole(${JSON.stringify(w.role)}, { name: ${JSON.stringify(w.name)}, exact: true })`
+        : pageVar;
+    // dynamic: the agent flagged `name`/`text` as content that varies run-to-run
+    // (a drawn word, a generated id), so freezing it as an exact-name selector
+    // would miss next run. Anchor on something stable instead: testId, then a
+    // content-free role (scoped by `within` when present), then `.first()`.
+    if (input.dynamic === true) {
+        if (testId)
+            return `${base}.getByTestId(${JSON.stringify(testId)})`;
+        if (role)
+            return `${base}.getByRole(${JSON.stringify(role)}).first()`;
+        // No stable anchor available — fall through to the literal logic below; the
+        // step is still recorded but brittle (a later anchor pass can harden it).
+    }
+    // exact: true — the agent passed the exact accessible name from the snapshot,
+    // so match it exactly. Without it, getByRole's default substring match makes
+    // "street" also resolve "previous street" → strict-mode violation on replay.
+    if (role && name)
+        return `${base}.getByRole(${JSON.stringify(role)}, { name: ${JSON.stringify(name)}, exact: true })`;
+    if (testId)
+        return `${base}.getByTestId(${JSON.stringify(testId)})`;
+    // .first(): a label-wrapped control's text matches the <label> AND its inner
+    // <span> → strict-mode violation; the first (outer label) is clickable.
+    if (text)
+        return `${base}.getByText(${JSON.stringify(text)}).first()`;
+    return `${base}.locator('body')`;
+}
+/** Selector for upload_file's target file <input> — by label, testId, or the
+ *  single file input (optionally `within`-scoped). Mirrors fileInput() in
+ *  mcp/actuateServer.ts. */
+function fileInputSelector(input, pageVar = 'page') {
+    const name = typeof input.name === 'string' ? input.name : '';
+    const testId = typeof input.testId === 'string' ? input.testId : '';
+    const w = input.within;
+    const base = w && typeof w.role === 'string' && typeof w.name === 'string'
+        ? `${pageVar}.getByRole(${JSON.stringify(w.role)}, { name: ${JSON.stringify(w.name)}, exact: true })`
+        : pageVar;
+    if (name)
+        return `${base}.getByLabel(${JSON.stringify(name)})`;
+    if (testId)
+        return `${base}.getByTestId(${JSON.stringify(testId)})`;
+    return `${base}.locator('input[type="file"]')`;
+}
+/**
+ * browser_select_option always targets a native `<select>` — whose ARIA role
+ * is `combobox`. The agent's description is usually the label ("marital
+ * status"), with no role keyword, so selectorFromDescription would fall back to
+ * getByText and match the *label text*, not the control — and `.selectOption()`
+ * on a text node throws. Force the combobox role by accessible name instead.
+ */
+export function selectorForSelect(desc, pageVar = 'page') {
+    const name = desc.trim()
+        .replace(/\s+(combobox|select|dropdown|listbox)$/i, '') // drop a trailing role keyword
+        .replace(/^"|"$/g, '');
+    if (!name)
+        return `${pageVar}.locator('select')`;
+    return `${pageVar}.getByRole('combobox', { name: ${JSON.stringify(name)} })`;
+}
 /**
  * Form fields from browser_fill_form have a `name` that's typically the
  * accessible name / label / aria-label. getByLabel is the right primitive.
@@ -466,6 +912,135 @@ function mapInputType(type) {
         default: return null;
     }
 }
+/** Playwright config filenames Playwright itself recognizes. If any exists we
+ *  assume the user owns baseURL config and never scaffold. */
+const PLAYWRIGHT_CONFIG_NAMES = [
+    'playwright.config.ts', 'playwright.config.js', 'playwright.config.mjs',
+    'playwright.config.cjs', 'playwright.config.mts', 'playwright.config.cts',
+];
+/** Parse a URL's origin, or null if it isn't an absolute http(s) URL. */
+function originOf(url) {
+    if (!url || !/^https?:\/\//.test(url))
+        return null;
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return null;
+    }
+}
+/** Origin of the first real navigation captured in the session, e.g.
+ *  http://localhost:5175 — the natural baseURL for the scaffolded config. */
+function firstNavigateOrigin(steps) {
+    for (const s of steps) {
+        if (s.kind !== 'step' || s.tool !== 'browser_navigate')
+            continue;
+        const url = String(s.input?.url ?? '');
+        if (/^https?:\/\//.test(url)) {
+            try {
+                return new URL(url).origin;
+            }
+            catch { /* not a parseable URL */ }
+        }
+    }
+    return null;
+}
+/** The FULL url of the first browser_navigate in the session (not just origin).
+ *  Used to seed the business spec's goto when auth-as-fixture lifted the login's
+ *  navigation into auth.setup.ts and no explicit startUrl was supplied. */
+function firstNavigateUrl(steps) {
+    for (const s of steps) {
+        if (s.kind === 'step' && s.tool === 'browser_navigate') {
+            const url = String(s.input?.url ?? '');
+            if (url)
+                return url;
+        }
+    }
+    return null;
+}
+/**
+ * Bug A fix: crystallized specs use relative URLs, so a project with no
+ * Playwright config (hence no baseURL) can't run them — `page.goto("/")` throws
+ * "Cannot navigate to invalid URL". When no config exists, scaffold a minimal
+ * one with baseURL inferred from the session's first navigation. Never touches
+ * an existing config (the user owns it), and skips silently if no origin can be
+ * inferred (leaves it to the user rather than guessing).
+ */
+/**
+ * Debt-2 (reproducible state isolation): write the shared `support/resetState.ts`
+ * helper that crystallized specs call in a beforeEach. It navigates to the app
+ * (baseURL), clears client state, and reloads — so each run starts clean. The
+ * goto-first ordering matters: localStorage is per-origin, so clearing it on the
+ * initial about:blank would be a no-op. `keys` (the recipe's storageKeys) scopes
+ * the localStorage clear when only some keys gate state (leaving e.g. an auth
+ * token); empty = clear all web storage. Regenerated on every save so it tracks
+ * the current recipe. User-facing Playwright code → lives under __vibe_tests__/.
+ */
+async function ensureResetStateHelper(devRoot, keys) {
+    const dir = join(devRoot, '__vibe_tests__', 'support');
+    await mkdir(dir, { recursive: true });
+    const source = [
+        `import type { Page, BrowserContext } from '@playwright/test';`,
+        ``,
+        `/**`,
+        ` * Generated by Hover — resets the app to a clean client-side state before`,
+        ` * each test, so runs are reproducible. The reset recipe was discovered (and`,
+        ` * verified) during exploration and lives in .hover/environments.json;`,
+        ` * re-crystallize to regenerate this file.`,
+        ` */`,
+        `const KEYS: string[] = ${JSON.stringify(keys)};`,
+        ``,
+        `export async function resetState(page: Page, context: BrowserContext): Promise<void> {`,
+        `  // goto first: localStorage is per-origin, so it can only be cleared once`,
+        `  // the app's origin is loaded (baseURL comes from the Playwright config).`,
+        `  await page.goto('/');`,
+        `  await context.clearCookies();`,
+        `  await page.evaluate((keys) => {`,
+        `    if (keys.length) { for (const k of keys) localStorage.removeItem(k); }`,
+        `    else { localStorage.clear(); sessionStorage.clear(); }`,
+        `  }, KEYS);`,
+        `  await page.reload();`,
+        `}`,
+        ``,
+    ].join('\n');
+    await writeFile(join(dir, 'resetState.ts'), source, 'utf-8');
+}
+async function ensurePlaywrightConfig(devRoot, steps, startUrl, authFile) {
+    if (PLAYWRIGHT_CONFIG_NAMES.some(n => existsSync(join(devRoot, n))))
+        return;
+    const origin = firstNavigateOrigin(steps) ?? originOf(startUrl);
+    if (!origin)
+        return;
+    // Auth-as-fixture: register a `setup` project (matches auth.setup.ts) that the
+    // main project depends on, so login runs ONCE before the specs. Only emitted
+    // when scaffolding our own config (we never touch a user's existing one).
+    const projects = authFile
+        ? [
+            `  projects: [`,
+            `    { name: 'setup', testMatch: /.*\\.setup\\.ts$/ },`,
+            `    { name: 'chromium', dependencies: ['setup'] },`,
+            `  ],`,
+        ]
+        : [];
+    const source = [
+        `import { defineConfig } from '@playwright/test';`,
+        ``,
+        `/**`,
+        ` * Scaffolded by Hover so crystallized specs (which use relative URLs like`,
+        ` * page.goto("/")) resolve against a base. Override HOVER_BASE_URL in CI to`,
+        ` * point the same specs at staging/prod.`,
+        ` */`,
+        `export default defineConfig({`,
+        `  testDir: './__vibe_tests__',`,
+        `  use: {`,
+        `    baseURL: process.env.HOVER_BASE_URL ?? ${JSON.stringify(origin)},`,
+        `  },`,
+        ...projects,
+        `});`,
+        ``,
+    ].join('\n');
+    await writeFile(join(devRoot, 'playwright.config.ts'), source, 'utf-8');
+}
 function stripBaseUrl(url) {
     // http://localhost:5173/checkout → /checkout, http://localhost:5173/ → /
     if (!/^https?:\/\//.test(url))