@hover-dev/core 0.14.1 → 0.15.0

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":"AAcA,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAA4B,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAErE,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,CAsCzB;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,CAahF;AAMD;;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,166 @@
+/**
+ * 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 { sidecarDir } from './sidecar.js';
+import { readSeeds, relevantSeeds } from './seeds.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 code = extractCode(raw);
+    const check = validateSpecCode(code);
+    if (!check.ok) {
+        throw new OptimizeError(`optimization rejected — ${check.errors.join('; ')}`);
+    }
+    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');
+    }
+    const open = (code.match(/\{/g) ?? []).length;
+    const close = (code.match(/\}/g) ?? []).length;
+    if (open !== close)
+        errors.push('unbalanced braces');
+    return { ok: errors.length === 0, errors };
+}
+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;
+}

package/dist/specs/seeds.d.ts

@@ -0,0 +1,36 @@
+export interface SeedRule {
+    /** Identifier, e.g. `download`. */
+    name: string;
+    /** Rough match signature — tool names (optionally `tool:detail`), used only
+     *  to pick relevant seeds for a spec, NOT for exact matching. */
+    signature: string[];
+    /** One-line human note: what the pattern is / when it applies. */
+    note?: string;
+    /** A concrete worked example the LLM generalizes from. */
+    example: {
+        steps: unknown[];
+        code: string;
+    };
+}
+/**
+ * Built-in seeds ship with core and feed EVERY project's optimization pass, so
+ * the bar is high: a pattern qualifies as built-in ONLY if it's a *highly
+ * certain* optimization — a fixed, app-agnostic translation whose output is
+ * deterministic and can't mislead (e.g. download → waitForEvent pairing).
+ *
+ * Deliberately NOT built-in:
+ *   - Semantic / judgement-based optimizations (e.g. WHICH feedback text to
+ *     assert) — those are already standing instructions in buildOptimizePrompt,
+ *     and a bad generalization would pollute every user's spec.
+ *   - Popup/new-tab — hardcoded in the translator (writeSpec), not a seed.
+ * Project-specific or speculative patterns live in <root>/.hover/rules/, where
+ * the bar is the user's own call.
+ */
+export declare const BUILTIN_SEEDS: SeedRule[];
+/** Built-in seeds + any in <projectRoot>/.hover/rules/*.json. Malformed files
+ *  are skipped rather than failing the whole read. */
+export declare function readSeeds(projectRoot: string): Promise<SeedRule[]>;
+/** Pick seeds whose signature's base tool appears in the spec — a cheap
+ *  relevance filter so the prompt only carries plausibly-applicable examples. */
+export declare function relevantSeeds(seeds: SeedRule[], specTools: Set<string>, cap?: number): SeedRule[];
+//# sourceMappingURL=seeds.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"seeds.d.ts","sourceRoot":"","sources":["../../src/specs/seeds.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,QAAQ;IACvB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb;qEACiE;IACjE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,OAAO,EAAE;QAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,EAenC,CAAC;AAEF;sDACsD;AACtD,wBAAsB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAiBxE;AAED;iFACiF;AACjF,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,GAAG,SAAI,GAAG,QAAQ,EAAE,CAG5F"}

package/dist/specs/seeds.js

@@ -0,0 +1,74 @@
+/**
+ * Community translation seeds (Stage 6, approach A): human-written worked
+ * examples that teach the optimization pass (F7) new patterns by few-shot,
+ * NOT by deterministic match+template. A seed is a rough `signature` (tool
+ * names, used only to pick relevant seeds) + a concrete `example`
+ * (input steps → output code) the LLM generalizes from.
+ *
+ * Sources: a small built-in set + the project's <projectRoot>/.hover/rules/.
+ * Adding a pattern = dropping an example JSON in .hover/rules/ — no core change.
+ *
+ * Built-in seeds deliberately cover patterns the deterministic translator does
+ * NOT hardcode (popup is already hardcoded in writeSpec, so it's not here).
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Built-in seeds ship with core and feed EVERY project's optimization pass, so
+ * the bar is high: a pattern qualifies as built-in ONLY if it's a *highly
+ * certain* optimization — a fixed, app-agnostic translation whose output is
+ * deterministic and can't mislead (e.g. download → waitForEvent pairing).
+ *
+ * Deliberately NOT built-in:
+ *   - Semantic / judgement-based optimizations (e.g. WHICH feedback text to
+ *     assert) — those are already standing instructions in buildOptimizePrompt,
+ *     and a bad generalization would pollute every user's spec.
+ *   - Popup/new-tab — hardcoded in the translator (writeSpec), not a seed.
+ * Project-specific or speculative patterns live in <root>/.hover/rules/, where
+ * the bar is the user's own call.
+ */
+export const BUILTIN_SEEDS = [
+    {
+        name: 'download',
+        signature: ['browser_click'],
+        note: 'a click that triggers a file download → pair with waitForEvent("download")',
+        example: {
+            steps: [{ tool: 'browser_click', element: 'Export CSV button' }],
+            code: "const [download] = await Promise.all([\n" +
+                "  page.waitForEvent('download'),\n" +
+                "  page.getByRole('button', { name: 'Export CSV' }).click(),\n" +
+                "]);\n" +
+                "expect(await download.suggestedFilename()).toContain('.csv');",
+        },
+    },
+];
+/** Built-in seeds + any in <projectRoot>/.hover/rules/*.json. Malformed files
+ *  are skipped rather than failing the whole read. */
+export async function readSeeds(projectRoot) {
+    const out = [...BUILTIN_SEEDS];
+    try {
+        const dir = join(projectRoot, '.hover', 'rules');
+        for (const f of await readdir(dir)) {
+            if (!f.endsWith('.json'))
+                continue;
+            try {
+                const s = JSON.parse(await readFile(join(dir, f), 'utf-8'));
+                if (s && s.name && Array.isArray(s.signature) && s.example?.code)
+                    out.push(s);
+            }
+            catch {
+                /* skip malformed seed file */
+            }
+        }
+    }
+    catch {
+        /* no .hover/rules/ directory */
+    }
+    return out;
+}
+/** Pick seeds whose signature's base tool appears in the spec — a cheap
+ *  relevance filter so the prompt only carries plausibly-applicable examples. */
+export function relevantSeeds(seeds, specTools, cap = 6) {
+    const hits = seeds.filter(s => s.signature.some(sig => specTools.has(sig.split(':')[0])));
+    return hits.slice(0, cap);
+}

package/dist/specs/sidecar.d.ts

@@ -0,0 +1,25 @@
+import type { SkillStep } from '../skills/writeSkill.js';
+import type { SpecAssertion } from './writeSpec.js';
+/** Current sidecar schema version. Bump when the shape changes so readers
+ *  (Stage 2 detection, Stage 7 optimization) can migrate or skip cleanly. */
+export declare const SIDECAR_VERSION = 1;
+export interface SpecSidecar {
+    version: number;
+    slug: string;
+    name: string;
+    /** ISO timestamp the sidecar was written. */
+    createdAt: string;
+    /** The full captured session, structured and verbatim — never re-derived
+     *  from the generated `.spec.ts`. */
+    steps: SkillStep[];
+    /** Alt-click assertions captured alongside the session. */
+    assertions: SpecAssertion[];
+}
+/** Sidecar directory under the spec output dir. Dot-prefixed on purpose:
+ *  Playwright's default `*.spec.ts` glob never reaches into `.hover/`. */
+export declare function sidecarDir(devRoot: string): string;
+/** Write the structured-session sidecar at `.hover/<slug>.json`. Caller passes
+ *  the data minus the stamped fields (`version`, `createdAt`), which this
+ *  function fills. Returns the absolute path written. */
+export declare function writeSidecar(devRoot: string, data: Omit<SpecSidecar, 'version' | 'createdAt'>): Promise<string>;
+//# sourceMappingURL=sidecar.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar.d.ts","sourceRoot":"","sources":["../../src/specs/sidecar.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;6EAC6E;AAC7E,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB;yCACqC;IACrC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,2DAA2D;IAC3D,UAAU,EAAE,aAAa,EAAE,CAAC;CAC7B;AAED;0EAC0E;AAC1E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;yDAEyD;AACzD,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,WAAW,CAAC,GAC/C,OAAO,CAAC,MAAM,CAAC,CAWjB"}

package/dist/specs/sidecar.js

@@ -0,0 +1,38 @@
+/**
+ * Structured-session sidecar for a generated spec.
+ *
+ * Every saved spec gets a companion `__vibe_tests__/.hover/<slug>.json` holding
+ * the original structured `SpecStep[]` (plus assertions + metadata). The
+ * `.spec.ts` is the human / CI artifact; this sidecar is the machine record
+ * that downstream work reads instead of parsing generated code:
+ *   - F4 cross-session extraction signature-matches `steps` across sidecars.
+ *   - F7 optimization pass feeds the draft + this sidecar to the LLM.
+ *
+ * It lands in a dot-prefixed `.hover/` dir so Playwright's default `*.spec.ts`
+ * glob never collects it, and it is pure data — no Hover runtime import.
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Current sidecar schema version. Bump when the shape changes so readers
+ *  (Stage 2 detection, Stage 7 optimization) can migrate or skip cleanly. */
+export const SIDECAR_VERSION = 1;
+/** Sidecar directory under the spec output dir. Dot-prefixed on purpose:
+ *  Playwright's default `*.spec.ts` glob never reaches into `.hover/`. */
+export function sidecarDir(devRoot) {
+    return join(devRoot, '__vibe_tests__', '.hover');
+}
+/** Write the structured-session sidecar at `.hover/<slug>.json`. Caller passes
+ *  the data minus the stamped fields (`version`, `createdAt`), which this
+ *  function fills. Returns the absolute path written. */
+export async function writeSidecar(devRoot, data) {
+    const dir = sidecarDir(devRoot);
+    await mkdir(dir, { recursive: true });
+    const path = join(dir, `${data.slug}.json`);
+    const sidecar = {
+        version: SIDECAR_VERSION,
+        createdAt: new Date().toISOString(),
+        ...data,
+    };
+    await writeFile(path, JSON.stringify(sidecar, null, 2) + '\n', 'utf-8');
+    return path;
+}

package/dist/specs/writeSpec.d.ts

@@ -1,5 +1,18 @@
 import type { SkillStep } from '../skills/writeSkill.js';
 export type SpecStep = SkillStep;
+/**
+ * Marker the deterministic translator leaves where a captured action is a real
+ * interaction but has no single-step Playwright translation (e.g. file upload,
+ * drag, a dialog handler) — a shape that needs a multi-step pattern. It is a
+ * structured signal, not a `// TODO`: the optimization pass (F7) and the
+ * "seeds could complete this — review?" suggestion grep for it, and
+ * `countOptimizableMarkers` reads it back off a saved spec.
+ */
+export declare const OPTIMIZABLE_MARKER = "// hover:optimizable";
+/** How many `// hover:optimizable` markers a generated spec carries. Used to
+ *  surface "this spec has an interaction the deterministic pass couldn't fully
+ *  translate — the optimization pass can complete it". */
+export declare function countOptimizableMarkers(source: string): number;
 export interface SpecAssertion {
     /** Generated Playwright code (single line, no leading "await "). */
     code: string;
@@ -24,4 +37,41 @@ export interface WriteSpecResult {
     slug: string;
 }
 export declare function writeSpec(opts: WriteSpecOptions): Promise<WriteSpecResult>;
+/**
+ * Emit an interaction (click / dblclick / hover / fill / selectOption) as a
+ * visibility-guarded prelude: hoist the locator to `el`, assert it's visible,
+ * then act.
+ *
+ *    const el = page.getByRole('button', { name: 'Submit' });
+ *    await expect(el).toBeVisible();
+ *    await el.click();
+ *
+ * Why: `getByRole` is "visible OR attached" by default. A button that drifted
+ * behind a closed `<details>` / kebab menu / drawer is still in the role tree,
+ * so the locator stays green AND `.click()` may still fire — but the actual
+ * user flow has degraded. Asserting visibility first makes that drift fail
+ * loudly with "Locator expected to be visible" instead of silently passing.
+ *
+ * Scoping: renderSpec wraps each step in its own `test.step(… async () => {})`,
+ * whose closure already scopes `el`, so a single interaction needs no extra
+ * braces. browser_fill_form emits several fields into one step, so it wraps
+ * each field in `blockScope(...)` to keep the per-field `el` from colliding.
+ */
+export declare function emitInteraction(selectorExpr: string, action: string): string[];
+/** Wrap lines in a `{ … }` block scope (2-space inner indent). Used by
+ *  browser_fill_form so each field's `const el` lives in its own scope inside
+ *  the shared test.step closure. */
+export declare function blockScope(lines: string[]): string[];
+/**
+ * Parse element descriptions like "Submit button" / "+1 button" / "Email
+ * textbox" / "Plan radio" into `getByRole(role, { name })` selectors. The
+ * trailing role keyword is the convention Playwright MCP uses.
+ */
+export declare function selectorFromDescription(desc: string, pageVar?: string): string;
+/**
+ * Form fields from browser_fill_form have a `name` that's typically the
+ * accessible name / label / aria-label. getByLabel is the right primitive.
+ * Fall back to getByRole('textbox') if we have a hint.
+ */
+export declare function selectorForFormField(name: string, type?: string, pageVar?: string): string;
 //# sourceMappingURL=writeSpec.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"writeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/writeSpec.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAGzD,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC;AAEjC,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,eAAgB,SAAQ,KAAK;aACZ,IAAI,EAAE,MAAM;aAAkB,IAAI,EAAE,MAAM;gBAA1C,IAAI,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAIvE;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;CAAE;AAEhE,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAkBhF"}
+{"version":3,"file":"writeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/writeSpec.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAUzD,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC;AAEjC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD;;0DAE0D;AAC1D,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,eAAgB,SAAQ,KAAK;aACZ,IAAI,EAAE,MAAM;aAAkB,IAAI,EAAE,MAAM;gBAA1C,IAAI,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAIvE;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;CAAE;AAEhE,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAiChF;AAgVD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAM9E;AAED;;oCAEoC;AACpC,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAqB9E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAQ1F"}