@hover-dev/core 0.16.0 → 0.18.0

package/dist/specs/optimizeSpec.js

@@ -4,17 +4,17 @@
  * 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
+ * CANDIDATE at `.hover/cache/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 { readFile, mkdir, writeFile, readdir } 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 { readSidecar } from './sidecar.js';
+import { BUILTIN_SEEDS, relevantSeeds } from './seeds.js';
 import { softBatch } from './softBatch.js';
 export class OptimizeError extends Error {
     constructor(message) {
@@ -22,6 +22,32 @@ export class OptimizeError extends Error {
         this.name = 'OptimizeError';
     }
 }
+/** Total Page-Object source budget injected into the prompt (chars). Keeps the
+ *  refinement context bounded on a large suite; extra POMs are dropped (logged in
+ *  the prompt) rather than blowing the window. */
+const POM_CONTEXT_BUDGET = 16_000;
+/** Best-effort gather of the suite context (conventions.md + __vibe_tests__/pages
+ *  Page Objects). Missing files → empty; never throws. */
+export async function gatherSuiteContext(devRoot) {
+    const conventions = (await readFile(join(devRoot, '.hover', 'conventions.md'), 'utf-8').catch(() => ''))
+        .trim() || undefined;
+    const pages = [];
+    let used = 0;
+    try {
+        const dir = join(devRoot, '__vibe_tests__', 'pages');
+        for (const f of (await readdir(dir)).sort()) {
+            if (!f.endsWith('.ts'))
+                continue;
+            const source = (await readFile(join(dir, f), 'utf-8').catch(() => '')).trim();
+            if (!source || used + source.length > POM_CONTEXT_BUDGET)
+                continue;
+            used += source.length;
+            pages.push({ name: f, source });
+        }
+    }
+    catch { /* no pages dir — plain spec, no POMs to reuse */ }
+    return { conventions, pages };
+}
 export async function optimizeSpec(devRoot, slug, runCodegen) {
     const specPath = join(devRoot, '__vibe_tests__', `${slug}.spec.ts`);
     let draft;
@@ -31,18 +57,14 @@ export async function optimizeSpec(devRoot, slug, runCodegen) {
     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 */
-    }
+    // Legacy-aware read; null → no sidecar, optimize from the draft alone.
+    const sidecar = await readSidecar(devRoot, slug);
     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 seeds = relevantSeeds(BUILTIN_SEEDS, specTools);
+    const suite = await gatherSuiteContext(devRoot);
+    const raw = await runCodegen(buildOptimizePrompt(draft, sidecar, seeds, suite));
     const llmCode = extractCode(raw);
     const check = validateSpecCode(llmCode);
     if (!check.ok) {
@@ -52,7 +74,9 @@ export async function optimizeSpec(devRoot, slug, runCodegen) {
     // 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');
+    // Candidates are disposable derived artifacts → `.hover/cache/` (always
+    // gitignored). Losing one costs a re-run of the optimization, nothing more.
+    const dir = join(devRoot, '.hover', 'cache', '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.
@@ -65,7 +89,7 @@ export async function optimizeSpec(devRoot, slug, runCodegen) {
  * same rules the deterministic path enforces (semantic selectors, no XPath, no
  * waitForTimeout, keep the test.step shape).
  */
-export function buildOptimizePrompt(draft, sidecar, seeds = []) {
+export function buildOptimizePrompt(draft, sidecar, seeds = [], suite = { pages: [] }) {
     const done = sidecar?.steps.find(s => s.kind === 'done');
     const stepsJson = sidecar
         ? JSON.stringify(sidecar.steps.filter(s => s.kind === 'step'), null, 2)
@@ -78,8 +102,29 @@ export function buildOptimizePrompt(draft, sidecar, seeds = []) {
         `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`,
+        `    success toast, a confirmation. Use the captured steps + the outcome`,
         `    summary below to know what to assert.`,
+        `  - ASSERT THE INVARIANT, NOT THIS RUN'S VALUE. When the asserted content`,
+        `    varies run-to-run (a generated id, an order number, a date, a counter, a`,
+        `    drawn word — and ANY step whose captured input has "dynamic": true),`,
+        `    assert the contract with a pattern, never the literal: expect(loc).not`,
+        `    .toHaveText('') or .toContainText(/…/), or .toHaveCount(n). Reserve an`,
+        `    exact-literal assertion for genuinely fixed text (a heading, a fixed`,
+        `    confirmation). Any captured assert_visible step already encodes this —`,
+        `    preserve its matcher/intent; don't tighten a dynamic one back to a literal.`,
+        `  - DE-LITERALIZE VOLATILE VALUES — even ones NOT pre-flagged. Scan every`,
+        `    selector and assertion in the spec for values that are this run's DATA, not`,
+        `    stable UI: a word/title/name/id/order number/date/price/count drawn from`,
+        `    app content. Judge from what this app IS (the conventions + Page Objects`,
+        `    below tell you) and the captured values. For each volatile one:`,
+        `    getByRole(role, { name: "<value>" }) -> a stable anchor (getByTestId, or`,
+        `    getByRole(role).first(), or a Page Object method); toHaveText("<value>") ->`,
+        `    .not.toHaveText('') or .toContainText(/.../). When unsure if a value is`,
+        `    volatile, PREFER the invariant — over-asserting a changing value is the`,
+        `    failure we are fixing. But NEVER newly hard-code a value that wasn't there.`,
+        `  - REUSE the project's Page Objects + conventions (below). If a step sequence`,
+        `    matches a Page Object method, CALL it instead of re-emitting raw locators,`,
+        `    and follow the naming / structure the existing suite uses.`,
         `  - Keep semantic selectors: getByRole / getByLabel / getByText. NEVER emit`,
         `    XPath or CSS-id selectors. NEVER use waitForTimeout (Playwright`,
         `    auto-waits).`,
@@ -104,6 +149,16 @@ export function buildOptimizePrompt(draft, sidecar, seeds = []) {
         ``,
         `=== CAPTURED STEPS ===`,
         stepsJson,
+        ...(suite.conventions
+            ? [``, `=== PROJECT CONVENTIONS (follow these) ===`, suite.conventions]
+            : []),
+        ...(suite.pages.length > 0
+            ? [
+                ``,
+                `=== REUSABLE PAGE OBJECTS (prefer calling these over raw locators) ===`,
+                ...suite.pages.map(p => `// ${p.name}\n${p.source}`),
+            ]
+            : []),
         ...(seeds.length > 0
             ? [
                 ``,
@@ -161,28 +216,3 @@ function hasSyntaxError(code) {
     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/pageObjectManifest.d.ts

@@ -15,6 +15,8 @@ export interface PageObjectManifest {
     pages: PageObjectEntry[];
 }
 export declare function writePageObjectManifest(devRoot: string, pages: PageObjectEntry[]): Promise<string>;
-/** Read the manifest, or null when none exists (no extraction has run). */
+/** Read the manifest, or null when none exists (no extraction has run).
+ *  Falls back to the legacy `__vibe_tests__/.hover/` home for manifests
+ *  written before the `.hover/sidecars/` relocation. */
 export declare function readPageObjectManifest(devRoot: string): Promise<PageObjectManifest | null>;
 //# sourceMappingURL=pageObjectManifest.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"pageObjectManifest.d.ts","sourceRoot":"","sources":["../../src/specs/pageObjectManifest.ts"],"names":[],"mappings":"AAkBA,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;;wDAEwD;AACxD,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAUhG"}

package/dist/specs/pageObjectManifest.js

@@ -1,19 +1,20 @@
 /**
- * Page Object manifest — the link between extraction (Stage 3b) and
- * consumption (Stage 3c).
+ * Page Object manifest — `.hover/page-objects.json` describing each emitted
+ * Page Object (class/method/fixture names + the signature prefix it replays).
+ * writeSpec reads it (`readPageObjectManifest`) to decide whether a freshly-saved
+ * spec's prefix matches an existing Page Object — if so it consumes
+ * `await loginPage.login(…)` and imports from `./fixtures` instead of re-emitting
+ * the steps inline.
  *
- * 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.
+ * NOTE: cross-spec reuse is currently DORMANT — the manifest writer
+ * (`writePageObjectManifest`) has no caller since the standalone extraction stage
+ * was removed, so the read path returns null and writeSpec emits Page Objects
+ * inline. Kept as the seam for when cross-spec Page Object reuse is wired into
+ * the MCP-first flow.
  */
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { sidecarDir } from './sidecar.js';
+import { sidecarDir, legacySidecarDir } from './sidecar.js';
 export const MANIFEST_VERSION = 1;
 function manifestPath(devRoot) {
     return join(sidecarDir(devRoot), 'page-objects.json');
@@ -26,15 +27,19 @@ export async function writePageObjectManifest(devRoot, 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). */
+/** Read the manifest, or null when none exists (no extraction has run).
+ *  Falls back to the legacy `__vibe_tests__/.hover/` home for manifests
+ *  written before the `.hover/sidecars/` relocation. */
 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 */
+    for (const path of [manifestPath(devRoot), join(legacySidecarDir(devRoot), 'page-objects.json')]) {
+        try {
+            const m = JSON.parse(await readFile(path, 'utf-8'));
+            if (Array.isArray(m.pages))
+                return m;
+        }
+        catch {
+            /* no manifest / malformed — try next */
+        }
     }
     return null;
 }

package/dist/specs/replayGrounded.d.ts

@@ -0,0 +1,45 @@
+import { type Locator, type Page } from 'playwright-core';
+export interface GroundedTarget {
+    role?: string;
+    name?: string;
+    text?: string;
+    testId?: string;
+    within?: {
+        role?: string;
+        name?: string;
+    };
+}
+export interface ReplayStep {
+    kind?: string;
+    tool?: string;
+    input?: unknown;
+}
+export interface ReplayFailure {
+    index: number;
+    tool: string;
+    target: string;
+    error: string;
+}
+export interface ReplayResult {
+    ok: boolean;
+    /** Grounded actions that ran successfully. */
+    ran: number;
+    /** Total grounded actions in the flow. */
+    total: number;
+    failures: ReplayFailure[];
+}
+export declare function groundedLocate(page: Page, g: GroundedTarget): Locator | null;
+/** Replay ONE grounded step on a page. Returns 'skipped' for non-actuation
+ *  steps; throws on a failed locate / action (the caller records it). */
+export declare function applyGroundedStep(page: Page, step: ReplayStep): Promise<'ok' | 'skipped'>;
+/** Replay a flow's grounded steps on a given page (injected, so it's testable
+ *  without a real browser). Navigates to `devUrl` first for a consistent start,
+ *  then runs each grounded action, stopping at the first failure. */
+export declare function replayOnPage(page: Page, devUrl: string, steps: ReplayStep[]): Promise<ReplayResult>;
+/** Connect to the debug Chrome over CDP and replay a flow's grounded steps. */
+export declare function replayGroundedSteps(opts: {
+    cdpUrl: string;
+    devUrl: string;
+    steps: ReplayStep[];
+}): Promise<ReplayResult>;
+//# sourceMappingURL=replayGrounded.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"replayGrounded.d.ts","sourceRoot":"","sources":["../../src/specs/replayGrounded.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAiBlF,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C;AAGD,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AACD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AACD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AA+BD,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,cAAc,GAAG,OAAO,GAAG,IAAI,CAS5E;AAED;yEACyE;AACzE,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,GAAG,SAAS,CAAC,CA4B/F;AAED;;qEAEqE;AACrE,wBAAsB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAqBzG;AAuBD,+EAA+E;AAC/E,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,EAAE,CAAA;CAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAoB9H"}

package/dist/specs/replayGrounded.js

@@ -0,0 +1,155 @@
+import { chromium } from 'playwright-core';
+const ACTUATION_TOOLS = new Set(['click_control', 'fill_control', 'select_control', 'check_control', 'assert_visible']);
+const ACTION_TIMEOUT = 8000;
+function bare(tool) {
+    if (!tool)
+        return '';
+    const p = tool.split('__');
+    return p[0] === 'mcp' && p.length >= 3 ? p.slice(2).join('__') : tool;
+}
+function errLine(e) {
+    return e instanceof Error ? e.message.split('\n')[0] : String(e);
+}
+function originOf(u) {
+    try {
+        return new URL(u).origin;
+    }
+    catch {
+        return null;
+    }
+}
+function describe(g) {
+    if (g.role && g.name)
+        return `${g.role} "${g.name}"`;
+    if (g.testId)
+        return `testId "${g.testId}"`;
+    if (g.text)
+        return `text "${g.text}"`;
+    return '(no target)';
+}
+// Mirrors mcp/actuateServer.ts `locate` — role+name → testId → text, optionally
+// scoped to a `within` container. See file header. Exported so non-extension
+// consumers (the replayer here, the standalone `hover-mcp`) share ONE grounded
+// resolver without touching the load-bearing actuateServer.
+export function groundedLocate(page, g) {
+    const base = g.within?.role && g.within?.name
+        ? page.getByRole(g.within.role, { name: g.within.name, exact: true })
+        : page;
+    if (g.role && g.name)
+        return base.getByRole(g.role, { name: g.name, exact: true });
+    if (g.testId)
+        return base.getByTestId(g.testId);
+    if (g.text)
+        return base.getByText(g.text).first();
+    return null;
+}
+/** Replay ONE grounded step on a page. Returns 'skipped' for non-actuation
+ *  steps; throws on a failed locate / action (the caller records it). */
+export async function applyGroundedStep(page, step) {
+    const tool = bare(step.tool);
+    if (!ACTUATION_TOOLS.has(tool))
+        return 'skipped';
+    const input = (step.input ?? {});
+    const loc = groundedLocate(page, input);
+    if (!loc)
+        throw new Error(`could not locate ${describe(input)}`);
+    switch (tool) {
+        case 'click_control':
+            await loc.click({ timeout: ACTION_TIMEOUT });
+            return 'ok';
+        case 'fill_control':
+            await loc.fill(String(input.value ?? ''), { timeout: ACTION_TIMEOUT });
+            return 'ok';
+        case 'select_control':
+            await loc.selectOption(String(input.value ?? ''), { timeout: ACTION_TIMEOUT });
+            return 'ok';
+        case 'check_control':
+            if (input.checked === false)
+                await loc.uncheck({ timeout: ACTION_TIMEOUT });
+            else
+                await loc.check({ timeout: ACTION_TIMEOUT });
+            return 'ok';
+        case 'assert_visible': {
+            const visible = await loc.first().isVisible();
+            if (!visible)
+                throw new Error(`${describe(input)} not visible`);
+            return 'ok';
+        }
+        default:
+            return 'skipped';
+    }
+}
+/** Replay a flow's grounded steps on a given page (injected, so it's testable
+ *  without a real browser). Navigates to `devUrl` first for a consistent start,
+ *  then runs each grounded action, stopping at the first failure. */
+export async function replayOnPage(page, devUrl, steps) {
+    const failures = [];
+    let ran = 0;
+    const total = steps.filter((s) => ACTUATION_TOOLS.has(bare(s.tool))).length;
+    try {
+        await page.goto(devUrl, { waitUntil: 'domcontentloaded', timeout: 15000 });
+    }
+    catch {
+        // SPA / already on the origin — replay anyway.
+    }
+    for (let i = 0; i < steps.length; i++) {
+        if (!ACTUATION_TOOLS.has(bare(steps[i].tool)))
+            continue;
+        try {
+            if ((await applyGroundedStep(page, steps[i])) === 'ok')
+                ran++;
+        }
+        catch (e) {
+            failures.push({ index: i, tool: bare(steps[i].tool), target: describe((steps[i].input ?? {})), error: errLine(e) });
+            break; // a broken step breaks the flow — stop here
+        }
+    }
+    return { ok: failures.length === 0, ran, total, failures };
+}
+/** Pick the page on the dev origin, else the foreground page. */
+async function pickPage(browser, devUrl) {
+    const wantOrigin = originOf(devUrl);
+    const pages = browser.contexts().flatMap((c) => c.pages());
+    if (pages.length === 0)
+        return null;
+    const matches = wantOrigin ? pages.filter((p) => originOf(p.url()) === wantOrigin) : [];
+    const candidates = matches.length ? matches : pages;
+    let chosen = candidates[candidates.length - 1];
+    for (const p of candidates) {
+        try {
+            if (await p.evaluate(() => document.visibilityState === 'visible')) {
+                chosen = p;
+                break;
+            }
+        }
+        catch {
+            /* busy/closed */
+        }
+    }
+    return chosen;
+}
+/** Connect to the debug Chrome over CDP and replay a flow's grounded steps. */
+export async function replayGroundedSteps(opts) {
+    let browser;
+    try {
+        browser = await chromium.connectOverCDP(opts.cdpUrl, { timeout: 5000 });
+    }
+    catch (e) {
+        return { ok: false, ran: 0, total: 0, failures: [{ index: -1, tool: 'connect', target: opts.cdpUrl, error: errLine(e) }] };
+    }
+    try {
+        const page = await pickPage(browser, opts.devUrl);
+        if (!page) {
+            return { ok: false, ran: 0, total: 0, failures: [{ index: -1, tool: 'page', target: opts.devUrl, error: 'no page on the dev origin' }] };
+        }
+        return await replayOnPage(page, opts.devUrl, opts.steps);
+    }
+    finally {
+        try {
+            await browser.close();
+        }
+        catch {
+            /* disconnect only — never kill the user's debug Chrome */
+        }
+    }
+}

package/dist/specs/runFailures.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Self-heal Stage 1 — the failure → heal-hint bridge.
+ *
+ * Playwright's JSON reporter records pass/fail but not *which locator* failed.
+ * Self-healing needs that to know what to re-locate. The locator IS in the error
+ * message (e.g. `waiting for getByRole('button', { name: 'Submit' })`), so this
+ * module parses the run JSON's failed tests and pulls out, per failure, the
+ * `getBy…` expression + the action that failed — the hint the heal session
+ * (Stage 2) drives the agent with.
+ *
+ * Pure + total: bad/partial JSON yields []. No FS, no agent — just parsing.
+ */
+export interface RunFailure {
+    /** Spec file as Playwright reports it (path or basename). */
+    specFile: string;
+    /** Test title. */
+    title: string;
+    /** First line of the error message (the human-readable failure). */
+    error: string;
+    /** The `getBy…` locator expression parsed from the error — the thing to
+     *  re-locate — or undefined if the failure wasn't a locator miss. */
+    failingLocator?: string;
+    /** The Playwright action that failed: 'click' / 'fill' / 'assert' / … */
+    failingAction?: string;
+}
+/** The `getBy…` expression in an error message, if any. */
+export declare function extractLocator(message: string): string | undefined;
+/** The failing action (click / fill / assert / …) inferred from the message. */
+export declare function extractAction(message: string): string | undefined;
+/** Parse a Playwright JSON-reporter run into its failures (with the failing
+ *  locator + action pulled from each error). Accepts the parsed object or a
+ *  JSON string; anything malformed yields []. */
+export declare function parseRunFailures(json: unknown): RunFailure[];
+//# sourceMappingURL=runFailures.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runFailures.d.ts","sourceRoot":"","sources":["../../src/specs/runFailures.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,UAAU;IACzB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd;yEACqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAgBD,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGlE;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOjE;AAoCD;;iDAEiD;AACjD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,EAAE,CAY5D"}

package/dist/specs/runFailures.js

@@ -0,0 +1,93 @@
+/**
+ * Self-heal Stage 1 — the failure → heal-hint bridge.
+ *
+ * Playwright's JSON reporter records pass/fail but not *which locator* failed.
+ * Self-healing needs that to know what to re-locate. The locator IS in the error
+ * message (e.g. `waiting for getByRole('button', { name: 'Submit' })`), so this
+ * module parses the run JSON's failed tests and pulls out, per failure, the
+ * `getBy…` expression + the action that failed — the hint the heal session
+ * (Stage 2) drives the agent with.
+ *
+ * Pure + total: bad/partial JSON yields []. No FS, no agent — just parsing.
+ */
+/** A `getBy…(...)` call with an optional `.first()/.last()/.nth()` tail. The
+ *  inner `(?:[^()]|\([^()]*\))*` tolerates one level of nested parens so
+ *  `getByRole('button', { name: 'x' })` matches whole. */
+const LOCATOR_RE = /getBy\w+\((?:[^()]|\([^()]*\))*\)(?:\.(?:first|last|nth)\([^)]*\))?/;
+/** A KNOWN Playwright interaction at the head of an error (`locator.click: …`),
+ *  restricted to real actions so a generic `Error:` / `Some:` prefix is NOT
+ *  mistaken for one. */
+const ACTION_RE = /^(?:locator\.)?(click|dblclick|fill|type|press|check|uncheck|selectOption|setInputFiles|hover|tap|focus|clear)\b/;
+const ASSERT_RE = /\b(?:toBeVisible|toHaveText|toContainText|toHaveCount|toHaveValue|toBeChecked|toBeEnabled)\b|^expect\(/;
+function firstLine(s) {
+    return (s.split('\n').find(l => l.trim()) ?? '').trim();
+}
+/** The `getBy…` expression in an error message, if any. */
+export function extractLocator(message) {
+    const m = message.match(LOCATOR_RE);
+    return m ? m[0] : undefined;
+}
+/** The failing action (click / fill / assert / …) inferred from the message. */
+export function extractAction(message) {
+    const head = firstLine(message);
+    // Assert first — an `Error: expect(...)` line leads with "Error:", which a
+    // generic action match would wrongly read as the action.
+    if (ASSERT_RE.test(head) || ASSERT_RE.test(message))
+        return 'assert';
+    const m = head.match(ACTION_RE);
+    return m ? m[1].toLowerCase() : undefined;
+}
+/** The error message of the first failed/timed-out result on a spec, if any. */
+function failedMessage(spec) {
+    for (const t of spec.tests ?? []) {
+        for (const r of t.results ?? []) {
+            if (r.status === 'failed' || r.status === 'timedOut' || r.status === 'interrupted') {
+                return r.error?.message || r.errors?.find(e => e.message)?.message || 'Test failed (no error message).';
+            }
+        }
+    }
+    return undefined;
+}
+function walk(suite, fileFallback, out) {
+    const file = suite.file || fileFallback;
+    for (const spec of suite.specs ?? []) {
+        if (spec.ok === true)
+            continue;
+        const message = failedMessage(spec);
+        if (!message)
+            continue; // not a failure (ok may be undefined but no failed result)
+        out.push({
+            specFile: spec.file || file,
+            title: spec.title || '(untitled)',
+            error: firstLine(message),
+            failingLocator: extractLocator(message),
+            failingAction: extractAction(message),
+        });
+    }
+    for (const child of suite.suites ?? [])
+        walk(child, file, out);
+}
+/** Parse a Playwright JSON-reporter run into its failures (with the failing
+ *  locator + action pulled from each error). Accepts the parsed object or a
+ *  JSON string; anything malformed yields []. */
+export function parseRunFailures(json) {
+    let root;
+    if (typeof json === 'string') {
+        try {
+            root = JSON.parse(json);
+        }
+        catch {
+            return [];
+        }
+    }
+    else if (json && typeof json === 'object') {
+        root = json;
+    }
+    else {
+        return [];
+    }
+    const out = [];
+    for (const suite of root.suites ?? [])
+        walk(suite, suite.file || '', out);
+    return out;
+}

package/dist/specs/seeds.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Translation seeds: human-written worked examples that teach the optimization
+ * pass (F7) a multi-step Playwright pattern 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.
+ *
+ * These ship inlined as the `BUILTIN_SEEDS` constant below. They used to be
+ * JSON files under `packages/core/seeds/optimization/` plus a `.hover/rules/`
+ * "author your own seed" mechanism and a `.hover/seeds.json` opt-out — all
+ * removed: that user-facing surface added burden for a small curated catalogue
+ * that feeds an optional, manually-invoked pass. To add a pattern, append a
+ * `SeedRule` here.
+ */
 export interface SeedRule {
     /** Identifier, e.g. `download`. */
     name: string;
@@ -13,23 +27,10 @@ export interface SeedRule {
     };
 }
 /**
- * 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.
+ * Built-in optimization seeds, inlined. They feed EVERY project's optimization
+ * pass (the prompt builder and the relevance filter consume this directly).
  */
 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[];

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

@@ -1 +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"}
+{"version":3,"file":"seeds.d.ts","sourceRoot":"","sources":["../../src/specs/seeds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,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;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,EAiFnC,CAAC;AAEF;iFACiF;AACjF,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,GAAG,SAAI,GAAG,QAAQ,EAAE,CAG5F"}