@hover-dev/core 0.14.1 → 0.16.0

package/dist/specs/generatePageObject.js

@@ -0,0 +1,149 @@
+import { selectorFromDescription, selectorForFormField, emitInteraction, blockScope, } from './writeSpec.js';
+const PAGE_VAR = 'this.page';
+export function generatePageObject(steps, override = {}) {
+    const derived = deriveNames(steps);
+    const className = override.className ?? derived.className;
+    const methodName = override.methodName ?? derived.methodName;
+    const params = [];
+    const used = new Set();
+    const body = [];
+    for (const s of steps) {
+        if (s.kind !== 'step' || !s.tool)
+            continue;
+        const i = (s.input ?? {});
+        switch (s.tool) {
+            case 'browser_navigate':
+                body.push(`await ${PAGE_VAR}.goto(${JSON.stringify(navPath(String(i.url ?? '')))});`);
+                break;
+            case 'browser_click':
+                body.push(...blockScope(emitInteraction(selectorFromDescription(String(i.element ?? ''), PAGE_VAR), 'click()')));
+                break;
+            case 'browser_double_click':
+                body.push(...blockScope(emitInteraction(selectorFromDescription(String(i.element ?? ''), PAGE_VAR), 'dblclick()')));
+                break;
+            case 'browser_hover':
+                body.push(...blockScope(emitInteraction(selectorFromDescription(String(i.element ?? ''), PAGE_VAR), 'hover()')));
+                break;
+            case 'browser_type': {
+                const p = uniqueParam(paramName(String(i.element ?? '')), used);
+                params.push(p);
+                body.push(...blockScope(emitInteraction(selectorFromDescription(String(i.element ?? ''), PAGE_VAR), `fill(${p})`)));
+                break;
+            }
+            case 'browser_select_option': {
+                const p = uniqueParam(paramName(String(i.element ?? '')), used);
+                params.push(p);
+                body.push(...blockScope(emitInteraction(selectorFromDescription(String(i.element ?? ''), PAGE_VAR), `selectOption(${p})`)));
+                break;
+            }
+            case 'browser_fill_form': {
+                const fields = i.fields ?? [];
+                for (const f of fields) {
+                    const target = String(f.name ?? f.element ?? '');
+                    const p = uniqueParam(paramName(target), used);
+                    params.push(p);
+                    body.push(...blockScope(emitInteraction(selectorForFormField(target, f.type, PAGE_VAR), `fill(${p})`)));
+                }
+                break;
+            }
+            case 'browser_press_key':
+                body.push(`await ${PAGE_VAR}.keyboard.press(${JSON.stringify(String(i.key ?? ''))});`);
+                break;
+            default:
+                break; // diagnostics / non-replayable — skipped
+        }
+    }
+    const paramList = params.map(p => `${p}: string`).join(', ');
+    return {
+        className,
+        methodName,
+        fileName: `${className}.ts`,
+        source: renderClass(className, methodName, paramList, body),
+    };
+}
+function renderClass(className, methodName, paramList, body) {
+    const out = body.length > 0 ? body : ['// (no replayable steps)'];
+    const lines = [];
+    lines.push(`import { expect, type Page } from '@playwright/test';`);
+    lines.push('');
+    lines.push('/**');
+    lines.push(' * Generated by Hover from a flow shared across saved specs.');
+    lines.push(' * Selectors live here so a UI change is a one-file edit; data values are');
+    lines.push(' * method parameters. Plain Playwright — no Hover runtime.');
+    lines.push(' */');
+    lines.push(`export class ${className} {`);
+    lines.push(`  constructor(private readonly page: Page) {}`);
+    lines.push('');
+    lines.push(`  async ${methodName}(${paramList}): Promise<void> {`);
+    for (const b of out)
+        lines.push(`    ${b}`);
+    lines.push(`  }`);
+    lines.push(`}`);
+    lines.push('');
+    return lines.join('\n');
+}
+function deriveNames(steps) {
+    for (const s of steps) {
+        if (s.kind === 'step' && s.tool === 'browser_navigate') {
+            const seg = lastSegment(String((s.input ?? {}).url ?? ''));
+            if (seg)
+                return { className: pascal(seg) + 'Page', methodName: camel(seg) };
+        }
+    }
+    return { className: 'FlowPage', methodName: 'run' };
+}
+function lastSegment(url) {
+    let path = url;
+    try {
+        if (/^https?:\/\//.test(url))
+            path = new URL(url).pathname;
+    }
+    catch {
+        /* keep raw */
+    }
+    const segs = path.split('/').filter(Boolean);
+    return segs.length ? segs[segs.length - 1].replace(/[^a-zA-Z0-9]+/g, ' ').trim() : '';
+}
+/** Tokenize a label into words, dropping a trailing MCP role keyword. */
+function words(raw) {
+    return raw
+        .replace(/\s+(button|link|textbox|checkbox|radio|combobox|switch|field|input)$/i, '')
+        .replace(/[^a-zA-Z0-9]+/g, ' ')
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean);
+}
+function camel(raw) {
+    const w = words(raw);
+    if (w.length === 0)
+        return 'value';
+    const c = w[0].toLowerCase() +
+        w.slice(1).map(x => x[0].toUpperCase() + x.slice(1).toLowerCase()).join('');
+    return /^[a-zA-Z_]/.test(c) ? c : `v${c}`;
+}
+function pascal(raw) {
+    const c = camel(raw);
+    return c.charAt(0).toUpperCase() + c.slice(1);
+}
+/** Parameter name derived from a field/element label. */
+const paramName = camel;
+function uniqueParam(base, used) {
+    const root = base || 'value';
+    let name = root;
+    let n = 2;
+    while (used.has(name))
+        name = `${root}${n++}`;
+    used.add(name);
+    return name;
+}
+function navPath(url) {
+    if (!/^https?:\/\//.test(url))
+        return url;
+    try {
+        const u = new URL(url);
+        return u.pathname + u.search + u.hash || '/';
+    }
+    catch {
+        return url;
+    }
+}

package/dist/specs/listSpecs.d.ts

@@ -1,3 +1,4 @@
+import { type OptimizationSuggestion } from './optimizationSuggestion.js';
 export interface SpecSummary {
     /** Path-relative slug, e.g. `login-and-counter`. Identifies the spec. */
     slug: string;
@@ -13,6 +14,17 @@ export interface SpecSummary {
     stepCount: number;
     /** File mtime in ms — used to show "saved 2 hours ago" in the UI. */
     mtimeMs: number;
+    /** Whether a structured `.hover/<slug>.json` sidecar exists. The widget
+     *  gates the optimization pass on this — without a captured session there's
+     *  no observed feedback for the LLM to add assertions from. */
+    hasSidecar: boolean;
+    /** Count of `// hover:optimizable` markers the deterministic translator left
+     *  — interactions it couldn't fully translate single-step. >0 is a strong
+     *  signal to run the optimization pass (or add a seed). */
+    optimizableCount: number;
+    /** The default-off "review optimization?" nudge (F7/D10): suggested + reasons,
+     *  derived from optimizable markers + relevant seeds. */
+    optimization: OptimizationSuggestion;
 }
 export interface SpecHeader {
     /** Raw text of `Original prompt:` line, or null when absent. */

package/dist/specs/listSpecs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"listSpecs.d.ts","sourceRoot":"","sources":["../../src/specs/listSpecs.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb;;qCAEiC;IACjC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,kEAAkE;IAClE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,gCAAgC;IAChC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,oDAAoD;IACpD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAsB1D;AA4BD;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAkCvE"}
+{"version":3,"file":"listSpecs.d.ts","sourceRoot":"","sources":["../../src/specs/listSpecs.ts"],"names":[],"mappings":"AAoBA,OAAO,EAA0B,KAAK,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAGlG,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb;;qCAEiC;IACjC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,kEAAkE;IAClE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB;;mEAE+D;IAC/D,UAAU,EAAE,OAAO,CAAC;IACpB;;+DAE2D;IAC3D,gBAAgB,EAAE,MAAM,CAAC;IACzB;6DACyD;IACzD,YAAY,EAAE,sBAAsB,CAAC;CACtC;AAED,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,gCAAgC;IAChC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,oDAAoD;IACpD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAsB1D;AA4BD;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CA2DvE"}

package/dist/specs/listSpecs.js

@@ -10,11 +10,15 @@
  * `originalPrompt: null` — the UI / CLI surfaces that "this spec can't be
  * re-recorded automatically; the natural-language intent isn't recorded."
  *
- * Mirrors the listSkills shape so widget UI can use the same row renderer.
+ * Shares the SpecSummary row shape the widget's Specs tab renders.
  */
 import { readdir, readFile } from 'node:fs/promises';
 import { stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { countOptimizableMarkers } from './writeSpec.js';
+import { readSeeds, relevantSeeds } from './seeds.js';
+import { optimizationSuggestion } from './optimizationSuggestion.js';
 /**
  * Parse the JSDoc header that `writeSpec.ts` emits. Tolerant of:
  *   - Specs without any JSDoc (returns all-null).
@@ -84,6 +88,8 @@ export async function listSpecs(devRoot) {
     catch {
         return [];
     }
+    // Seeds are devRoot-wide; read once and reuse for every spec's suggestion.
+    const seeds = await readSeeds(devRoot);
     const summaries = [];
     for (const entry of entries) {
         if (!entry.endsWith('.spec.ts'))
@@ -100,13 +106,32 @@ export async function listSpecs(devRoot) {
             continue;
         }
         const header = parseSpecHeader(content);
+        const slug = entry.replace(/\.spec\.ts$/, '');
+        const sidecarPath = join(root, '.hover', `${slug}.json`);
+        const hasSidecar = existsSync(sidecarPath);
+        const optimizableCount = countOptimizableMarkers(content);
+        // Which seeds could plausibly apply, from the sidecar's captured tools.
+        let relevantSeedNames = [];
+        if (hasSidecar && seeds.length > 0) {
+            try {
+                const sc = JSON.parse(await readFile(sidecarPath, 'utf-8'));
+                const tools = new Set((sc.steps ?? []).filter(s => s.kind === 'step' && s.tool).map(s => s.tool));
+                relevantSeedNames = relevantSeeds(seeds, tools).map(s => s.name);
+            }
+            catch {
+                /* malformed sidecar — treat as no relevant seeds */
+            }
+        }
         summaries.push({
-            slug: entry.replace(/\.spec\.ts$/, ''),
+            slug,
             path,
             originalPrompt: header.originalPrompt,
             outcome: header.outcome,
             stepCount: header.steps.length,
             mtimeMs,
+            hasSidecar,
+            optimizableCount,
+            optimization: optimizationSuggestion({ hasSidecar, optimizableCount, relevantSeedNames }),
         });
     }
     summaries.sort((a, b) => b.mtimeMs - a.mtimeMs);

package/dist/specs/optimizationSuggestion.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The default-off "should we nudge the user to optimize this spec?" signal
+ * (F7 / D10). Optimization never runs automatically; instead, when a saved spec
+ * has a clear improvable shape, the widget surfaces a "review optimization?"
+ * prompt. This computes that decision + human-readable reasons.
+ *
+ * Pure function so it's trivially testable; `listSpecs` gathers the inputs
+ * (optimizable-marker count, sidecar presence, relevant seed names) and attaches
+ * the result to each SpecSummary.
+ */
+export interface OptimizationSuggestion {
+    /** Whether to nudge the user to run the optimization pass on this spec. */
+    suggested: boolean;
+    /** Human-readable reasons, for the widget tooltip / prompt. Empty when not
+     *  suggested. */
+    reasons: string[];
+}
+export declare function optimizationSuggestion(args: {
+    /** Whether a `.hover/<slug>.json` sidecar exists. */
+    hasSidecar: boolean;
+    /** Count of `// hover:optimizable` markers in the spec. */
+    optimizableCount: number;
+    /** Names of seeds whose signature is relevant to this spec's tools. */
+    relevantSeedNames: string[];
+}): OptimizationSuggestion;
+//# sourceMappingURL=optimizationSuggestion.d.ts.map

package/dist/specs/optimizationSuggestion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimizationSuggestion.d.ts","sourceRoot":"","sources":["../../src/specs/optimizationSuggestion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,sBAAsB;IACrC,2EAA2E;IAC3E,SAAS,EAAE,OAAO,CAAC;IACnB;qBACiB;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,qDAAqD;IACrD,UAAU,EAAE,OAAO,CAAC;IACpB,2DAA2D;IAC3D,gBAAgB,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B,GAAG,sBAAsB,CAqBzB"}

package/dist/specs/optimizationSuggestion.js

@@ -0,0 +1,28 @@
+/**
+ * The default-off "should we nudge the user to optimize this spec?" signal
+ * (F7 / D10). Optimization never runs automatically; instead, when a saved spec
+ * has a clear improvable shape, the widget surfaces a "review optimization?"
+ * prompt. This computes that decision + human-readable reasons.
+ *
+ * Pure function so it's trivially testable; `listSpecs` gathers the inputs
+ * (optimizable-marker count, sidecar presence, relevant seed names) and attaches
+ * the result to each SpecSummary.
+ */
+export function optimizationSuggestion(args) {
+    const { hasSidecar, optimizableCount, relevantSeedNames } = args;
+    const reasons = [];
+    // The optimization pass reads the sidecar (observed feedback, captured steps);
+    // without one there's nothing to optimize from. Matches the widget's Optimize
+    // gate, so we never suggest what can't be acted on.
+    if (!hasSidecar)
+        return { suggested: false, reasons };
+    if (optimizableCount > 0) {
+        const n = optimizableCount;
+        reasons.push(`${n} interaction${n === 1 ? '' : 's'} couldn't be fully translated — the optimization pass can complete ${n === 1 ? 'it' : 'them'}`);
+    }
+    if (relevantSeedNames.length > 0) {
+        const k = relevantSeedNames.length;
+        reasons.push(`${k} seed${k === 1 ? '' : 's'} may apply: ${relevantSeedNames.join(', ')}`);
+    }
+    return { suggested: reasons.length > 0, reasons };
+}

package/dist/specs/optimizeSpec.d.ts

@@ -0,0 +1,42 @@
+import { type SpecSidecar } from './sidecar.js';
+import { type SeedRule } from './seeds.js';
+export declare class OptimizeError extends Error {
+    constructor(message: string);
+}
+/** Runs the codegen LLM on a prompt and returns its raw text output. */
+export type RunCodegen = (prompt: string) => Promise<string>;
+export interface OptimizeResult {
+    /** Absolute path of the written candidate (never the original spec). */
+    candidatePath: string;
+    /** The validated candidate source. */
+    code: string;
+    /** The original (deterministic) spec the candidate was generated from —
+     *  returned so callers can show a diff without re-reading the file. */
+    original: string;
+}
+export declare function optimizeSpec(devRoot: string, slug: string, runCodegen: RunCodegen): Promise<OptimizeResult>;
+/**
+ * Build the codegen prompt: the current spec + the observed session, plus the
+ * same rules the deterministic path enforces (semantic selectors, no XPath, no
+ * waitForTimeout, keep the test.step shape).
+ */
+export declare function buildOptimizePrompt(draft: string, sidecar: SpecSidecar | null, seeds?: SeedRule[]): string;
+/** Strip a ```ts fence if the model wrapped its output in one. */
+export declare function extractCode(raw: string): string;
+/**
+ * Code-level guardrails — the same constraints the deterministic path keeps,
+ * enforced on the LLM's output so an optimization can't drift off-policy. This
+ * is what lets us allow an LLM to author here without a markdown constitution.
+ */
+export declare function validateSpecCode(code: string): {
+    ok: boolean;
+    errors: string[];
+};
+/** Promote an optimization candidate to the real spec (overwriting it) and
+ *  remove the candidate. Returns the written spec path. The human's "Use
+ *  optimized" / `mv` action. */
+export declare function promoteOptimized(devRoot: string, slug: string): Promise<string>;
+/** Discard an optimization candidate (delete the .draft, leave the spec). The
+ *  human's "Keep original". */
+export declare function discardOptimized(devRoot: string, slug: string): Promise<void>;
+//# sourceMappingURL=optimizeSpec.d.ts.map

package/dist/specs/optimizeSpec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimizeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/optimizeSpec.ts"],"names":[],"mappings":"AAeA,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAA4B,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGrE,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE7D,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,aAAa,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb;2EACuE;IACvE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,cAAc,CAAC,CA2CzB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,GAAG,IAAI,EAC3B,KAAK,GAAE,QAAQ,EAAO,GACrB,MAAM,CAmDR;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAWhF;AAyBD;;gCAEgC;AAChC,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYrF;AAED;+BAC+B;AAC/B,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnF"}

package/dist/specs/optimizeSpec.js

@@ -0,0 +1,188 @@
+/**
+ * Stage 7 (F7): the optional LLM optimization pass.
+ *
+ * Reads a deterministic draft spec + its sidecar, asks an LLM (the codegen
+ * mode — no browser, no MCP) to improve it (chiefly: add assertions for the
+ * feedback the session observed), validates the result, and writes it as a
+ * CANDIDATE at `.hover/optimized/<slug>.spec.ts.draft` — never overwriting the
+ * original (D10). A human promotes or discards it via diff.
+ *
+ * The LLM call is injected (`runCodegen`) so callers wire their own agent and
+ * tests run deterministically without spawning anything.
+ */
+import { readFile, mkdir, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Project } from 'ts-morph';
+import { sidecarDir } from './sidecar.js';
+import { readSeeds, relevantSeeds } from './seeds.js';
+import { softBatch } from './softBatch.js';
+export class OptimizeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OptimizeError';
+    }
+}
+export async function optimizeSpec(devRoot, slug, runCodegen) {
+    const specPath = join(devRoot, '__vibe_tests__', `${slug}.spec.ts`);
+    let draft;
+    try {
+        draft = await readFile(specPath, 'utf-8');
+    }
+    catch {
+        throw new OptimizeError(`spec not found: ${slug} (looked at ${specPath})`);
+    }
+    let sidecar = null;
+    try {
+        sidecar = JSON.parse(await readFile(join(sidecarDir(devRoot), `${slug}.json`), 'utf-8'));
+    }
+    catch {
+        /* no sidecar — optimize from the draft alone */
+    }
+    const specTools = new Set((sidecar?.steps ?? [])
+        .filter(s => s.kind === 'step' && s.tool)
+        .map(s => s.tool));
+    const seeds = relevantSeeds(await readSeeds(devRoot), specTools);
+    const raw = await runCodegen(buildOptimizePrompt(draft, sidecar, seeds));
+    const llmCode = extractCode(raw);
+    const check = validateSpecCode(llmCode);
+    if (!check.ok) {
+        throw new OptimizeError(`optimization rejected — ${check.errors.join('; ')}`);
+    }
+    // Deterministic finishing step: the LLM decided WHAT to assert; soft-batch
+    // applies the safe mechanical rewrite (trailing run of independent assertions
+    // → expect.soft) surgically on its output. See softBatch.ts for the guard.
+    const code = softBatch(llmCode).code;
+    const dir = join(devRoot, '__vibe_tests__', '.hover', 'optimized');
+    await mkdir(dir, { recursive: true });
+    // `.spec.ts.draft`, never `*.spec.ts` — Playwright's glob must not collect a
+    // candidate before a human reviews it.
+    const candidatePath = join(dir, `${slug}.spec.ts.draft`);
+    await writeFile(candidatePath, code.endsWith('\n') ? code : `${code}\n`, 'utf-8');
+    return { candidatePath, code, original: draft };
+}
+/**
+ * Build the codegen prompt: the current spec + the observed session, plus the
+ * same rules the deterministic path enforces (semantic selectors, no XPath, no
+ * waitForTimeout, keep the test.step shape).
+ */
+export function buildOptimizePrompt(draft, sidecar, seeds = []) {
+    const done = sidecar?.steps.find(s => s.kind === 'done');
+    const stepsJson = sidecar
+        ? JSON.stringify(sidecar.steps.filter(s => s.kind === 'step'), null, 2)
+        : '(no sidecar captured)';
+    return [
+        `You are improving an already-correct, generated Playwright spec. You are`,
+        `given the current deterministic spec and the structured browser session it`,
+        `was crystallized from.`,
+        ``,
+        `Improve it WITHOUT changing what it tests:`,
+        `  - Add assertions for the success/error feedback the session OBSERVED —`,
+        `    e.g. await expect(page.getByText('Invalid email')).toBeVisible(), a`,
+        `    success toast, a counter value. Use the captured steps + the outcome`,
+        `    summary below to know what to assert.`,
+        `  - Keep semantic selectors: getByRole / getByLabel / getByText. NEVER emit`,
+        `    XPath or CSS-id selectors. NEVER use waitForTimeout (Playwright`,
+        `    auto-waits).`,
+        `  - Keep the existing import line and the test.step(...) structure.`,
+        `  - Do not invent steps the session did not perform.`,
+        `  - If an observed outcome looks like a BUG (it contradicts what a correct`,
+        `    app should do — a stale error that never clears, the wrong message, a`,
+        `    value that should have changed but didn't), STILL assert the observed`,
+        `    reality (Hover records what actually happened), but put a comment`,
+        `    "// KNOWN BUG: <one line>" on the line directly above that assertion so a`,
+        `    human can find it and so the test breaks loudly once the app is fixed.`,
+        `    Never silently lock buggy behavior into a normal-looking assertion.`,
+        ``,
+        `Output ONLY the complete .ts file contents — no markdown fences, no prose,`,
+        `no explanation.`,
+        ``,
+        `=== CURRENT SPEC ===`,
+        draft,
+        ``,
+        `=== OBSERVED OUTCOME ===`,
+        done?.summary?.trim() || '(none)',
+        ``,
+        `=== CAPTURED STEPS ===`,
+        stepsJson,
+        ...(seeds.length > 0
+            ? [
+                ``,
+                `=== WORKED EXAMPLES (apply a pattern ONLY if the steps genuinely match it) ===`,
+                ...seeds.map(s => `# ${s.name}${s.note ? ` — ${s.note}` : ''}\n` +
+                    `WHEN steps look like: ${JSON.stringify(s.example.steps)}\n` +
+                    `EMIT something like:\n${s.example.code}`),
+            ]
+            : []),
+    ].join('\n');
+}
+/** Strip a ```ts fence if the model wrapped its output in one. */
+export function extractCode(raw) {
+    const t = raw.trim();
+    const fence = t.match(/```(?:ts|typescript|tsx|javascript|js)?\s*\n([\s\S]*?)```/);
+    return (fence ? fence[1] : t).trim();
+}
+/**
+ * Code-level guardrails — the same constraints the deterministic path keeps,
+ * enforced on the LLM's output so an optimization can't drift off-policy. This
+ * is what lets us allow an LLM to author here without a markdown constitution.
+ */
+export function validateSpecCode(code) {
+    const errors = [];
+    if (!code.trim())
+        errors.push('empty output');
+    if (/\bwaitForTimeout\b/.test(code))
+        errors.push('uses waitForTimeout');
+    if (/xpath\s*=|locator\(\s*['"`]\/\//i.test(code))
+        errors.push('uses an XPath selector');
+    if (!/\btest\s*\(/.test(code))
+        errors.push('no test() block');
+    if (!/from\s+['"](@playwright\/test|\.\/fixtures)['"]/.test(code)) {
+        errors.push('missing @playwright/test (or ./fixtures) import');
+    }
+    if (hasSyntaxError(code))
+        errors.push('has a syntax error');
+    return { ok: errors.length === 0, errors };
+}
+/**
+ * Real syntax check via the TypeScript parser (the same ts-morph the soft-batch
+ * step uses). Replaces a naive `{`/`}` count that mis-flagged a valid spec
+ * asserting on a string like 'a { b' — braces inside string literals are not
+ * structural. We look at SYNTACTIC diagnostics only: a candidate references
+ * `page` / `expect` / `@playwright/test` that aren't resolvable in this throwaway
+ * project, so SEMANTIC ("cannot find module", "implicitly any") diagnostics are
+ * expected and must be ignored — only a genuine parse error (an unbalanced
+ * brace, a stray token) should reject the optimization.
+ */
+function hasSyntaxError(code) {
+    const project = new Project({
+        useInMemoryFileSystem: true,
+        compilerOptions: { allowJs: true },
+    });
+    const sf = project.createSourceFile('__candidate.ts', code, { overwrite: true });
+    return project.getProgram().getSyntacticDiagnostics(sf).length > 0;
+}
+function candidatePathFor(devRoot, slug) {
+    return join(devRoot, '__vibe_tests__', '.hover', 'optimized', `${slug}.spec.ts.draft`);
+}
+/** Promote an optimization candidate to the real spec (overwriting it) and
+ *  remove the candidate. Returns the written spec path. The human's "Use
+ *  optimized" / `mv` action. */
+export async function promoteOptimized(devRoot, slug) {
+    const candidate = candidatePathFor(devRoot, slug);
+    const specPath = join(devRoot, '__vibe_tests__', `${slug}.spec.ts`);
+    let code;
+    try {
+        code = await readFile(candidate, 'utf-8');
+    }
+    catch {
+        throw new OptimizeError(`no optimization candidate to promote for "${slug}"`);
+    }
+    await writeFile(specPath, code, 'utf-8');
+    await rm(candidate, { force: true });
+    return specPath;
+}
+/** Discard an optimization candidate (delete the .draft, leave the spec). The
+ *  human's "Keep original". */
+export async function discardOptimized(devRoot, slug) {
+    await rm(candidatePathFor(devRoot, slug), { force: true });
+}

package/dist/specs/optimizeSpecWithAgent.d.ts

@@ -0,0 +1,11 @@
+import { type OptimizeResult } from './optimizeSpec.js';
+export interface OptimizeAgentOptions {
+    agentId: string;
+    model?: string;
+    maxBudgetUsd?: number;
+    /** Optional model API key, injected into the spawned CLI's env. */
+    apiKey?: string;
+    signal?: AbortSignal;
+}
+export declare function optimizeSpecWithAgent(devRoot: string, slug: string, opts: OptimizeAgentOptions): Promise<OptimizeResult>;
+//# sourceMappingURL=optimizeSpecWithAgent.d.ts.map

package/dist/specs/optimizeSpecWithAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimizeSpecWithAgent.d.ts","sourceRoot":"","sources":["../../src/specs/optimizeSpecWithAgent.ts"],"names":[],"mappings":"AAUA,OAAO,EAAgB,KAAK,cAAc,EAAmB,MAAM,mBAAmB,CAAC;AAEvF,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,cAAc,CAAC,CA4BzB"}

package/dist/specs/optimizeSpecWithAgent.js

@@ -0,0 +1,40 @@
+/**
+ * Wires optimizeSpec's injected codegen call to a real agent via invokeAgent,
+ * in "codegen mode": no MCP, no browser tools, the agent's own built-in tools
+ * disallowed — it just reads the prompt and emits the improved spec as text.
+ *
+ * Kept separate from optimizeSpec.ts so the core (prompt / extract / validate /
+ * write) stays a pure, spawn-free module that tests import directly.
+ */
+import { invokeAgent } from '../agents/invoke.js';
+import { getAgent } from '../agents/registry.js';
+import { optimizeSpec } from './optimizeSpec.js';
+export async function optimizeSpecWithAgent(devRoot, slug, opts) {
+    const descriptor = getAgent(opts.agentId);
+    // Codegen mode: deny the agent's built-in tools so it answers with text only;
+    // pass no mcpConfig / allowedTools so it never reaches a browser.
+    const disallowedTools = descriptor?.defaultDisallowedTools
+        ? [...descriptor.defaultDisallowedTools]
+        : undefined;
+    const runCodegen = async (prompt) => {
+        let streamed = '';
+        let summary = '';
+        for await (const ev of invokeAgent({
+            agentId: opts.agentId,
+            prompt,
+            model: opts.model,
+            maxBudgetUsd: opts.maxBudgetUsd,
+            apiKey: opts.apiKey,
+            signal: opts.signal,
+            disallowedTools,
+        })) {
+            if (ev.kind === 'text' && ev.text)
+                streamed += `${ev.text}\n`;
+            else if (ev.kind === 'session_end' && ev.summary)
+                summary = ev.summary;
+        }
+        // Prefer the final result summary; fall back to streamed text blocks.
+        return summary || streamed;
+    };
+    return optimizeSpec(devRoot, slug, runCodegen);
+}

package/dist/specs/pageObjectManifest.d.ts

@@ -0,0 +1,20 @@
+export declare const MANIFEST_VERSION = 1;
+export interface PageObjectEntry {
+    className: string;
+    methodName: string;
+    /** Fixture key in fixtures.ts, e.g. `loginPage`. */
+    fixtureName: string;
+    fileName: string;
+    /** The signature prefix this Page Object's method replays (one per step). */
+    signatures: string[];
+    /** Slugs of the specs the Page Object was lifted from. */
+    specs: string[];
+}
+export interface PageObjectManifest {
+    version: number;
+    pages: PageObjectEntry[];
+}
+export declare function writePageObjectManifest(devRoot: string, pages: PageObjectEntry[]): Promise<string>;
+/** Read the manifest, or null when none exists (no extraction has run). */
+export declare function readPageObjectManifest(devRoot: string): Promise<PageObjectManifest | null>;
+//# sourceMappingURL=pageObjectManifest.d.ts.map

package/dist/specs/pageObjectManifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pageObjectManifest.d.ts","sourceRoot":"","sources":["../../src/specs/pageObjectManifest.ts"],"names":[],"mappings":"AAiBA,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,0DAA0D;IAC1D,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,eAAe,EAAE,CAAC;CAC1B;AAMD,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,eAAe,EAAE,GACvB,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED,2EAA2E;AAC3E,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAQhG"}

package/dist/specs/pageObjectManifest.js

@@ -0,0 +1,40 @@
+/**
+ * Page Object manifest — the link between extraction (Stage 3b) and
+ * consumption (Stage 3c).
+ *
+ * extractPageObjects writes `.hover/page-objects.json` describing each emitted
+ * Page Object: its class/method/fixture names and the signature prefix it
+ * replays. writeSpec reads it to decide whether a freshly-saved spec's prefix
+ * matches a Page Object — if so it consumes `await loginPage.login(…)` and
+ * imports from `./fixtures` instead of re-emitting the steps inline.
+ *
+ * Kept separate from extractPageObjects so writeSpec can read the manifest
+ * without importing the detection/generation chain.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { sidecarDir } from './sidecar.js';
+export const MANIFEST_VERSION = 1;
+function manifestPath(devRoot) {
+    return join(sidecarDir(devRoot), 'page-objects.json');
+}
+export async function writePageObjectManifest(devRoot, pages) {
+    const dir = sidecarDir(devRoot);
+    await mkdir(dir, { recursive: true });
+    const path = manifestPath(devRoot);
+    const manifest = { version: MANIFEST_VERSION, pages };
+    await writeFile(path, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+    return path;
+}
+/** Read the manifest, or null when none exists (no extraction has run). */
+export async function readPageObjectManifest(devRoot) {
+    try {
+        const m = JSON.parse(await readFile(manifestPath(devRoot), 'utf-8'));
+        if (Array.isArray(m.pages))
+            return m;
+    }
+    catch {
+        /* no manifest / malformed — treat as none */
+    }
+    return null;
+}