@hover-dev/core 0.16.0 → 0.17.0

package/dist/specs/detectSharedFlows.js

@@ -17,9 +17,9 @@
  * same signature even though their typed values differ — value vs. structure
  * separation is mechanical (D4).
  */
-import { readdir, readFile } from 'node:fs/promises';
+import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { sidecarDir } from './sidecar.js';
+import { sidecarDir, legacySidecarDir, parseSidecarFile } from './sidecar.js';
 import { humanStep } from './humanSteps.js';
 /**
  * Reduce one captured step to a signature string: the tool plus its structural
@@ -60,31 +60,30 @@ export function stepSignature(tool, rawInput) {
             return null;
     }
 }
-/** Read and parse every sidecar under `.hover/`. Malformed files are skipped
- *  (better to detect across the valid ones than fail because one is broken). */
+/** Read and parse every sidecar under `.hover/sidecars/`, unioned with any
+ *  still in the legacy `__vibe_tests__/.hover/` home (current home wins on a
+ *  slug collision). Malformed files are skipped (better to detect across the
+ *  valid ones than fail because one is broken). */
 async function readSidecars(devRoot) {
-    const dir = sidecarDir(devRoot);
-    let entries;
-    try {
-        entries = await readdir(dir);
-    }
-    catch {
-        return [];
-    }
-    const out = [];
-    for (const entry of entries) {
-        if (!entry.endsWith('.json'))
-            continue;
+    const bySlug = new Map();
+    for (const dir of [legacySidecarDir(devRoot), sidecarDir(devRoot)]) {
+        let entries;
         try {
-            const sc = JSON.parse(await readFile(join(dir, entry), 'utf-8'));
-            if (Array.isArray(sc.steps) && typeof sc.slug === 'string')
-                out.push(sc);
+            entries = await readdir(dir);
         }
         catch {
-            // skip malformed sidecar
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.endsWith('.json'))
+                continue;
+            const sc = await parseSidecarFile(join(dir, entry));
+            if (sc && Array.isArray(sc.steps) && typeof sc.slug === 'string') {
+                bySlug.set(sc.slug, sc); // later dir (current home) overwrites
+            }
         }
     }
-    return out;
+    return [...bySlug.values()];
 }
 /** Project a sidecar's steps to (signature, prose) lists, dropping
  *  non-flow steps. */

package/dist/specs/generatePageObject.d.ts

@@ -11,7 +11,7 @@
  * emitters with a `this.page` page variable, so a Page Object's selectors match
  * the crystallized specs exactly.
  */
-import type { SkillStep } from '../skills/writeSkill.js';
+import type { SkillStep } from '../specs/specStep.js';
 export interface PageObjectResult {
     /** PascalCase class name, e.g. `LoginPage`. */
     className: string;

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

@@ -1 +1 @@
-{"version":3,"file":"generatePageObject.d.ts","sourceRoot":"","sources":["../../src/specs/generatePageObject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAUzD,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,EAAE,EAClB,QAAQ,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACzD,gBAAgB,CAoElB"}
+{"version":3,"file":"generatePageObject.d.ts","sourceRoot":"","sources":["../../src/specs/generatePageObject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAUtD,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,EAAE,EAClB,QAAQ,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACzD,gBAAgB,CAoElB"}

package/dist/specs/healPrompt.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Self-heal Stage 2 — the heal prompt.
+ *
+ * When a saved spec fails on replay (the app changed → a locator no longer
+ * matches), healing re-performs the flow against the LIVE app and fixes the
+ * broken step(s). This builds the instruction that drives that run: the agent
+ * gets the spec's intended flow (its source) + exactly what broke (the parsed
+ * failures), and re-locates via the grounded control tools + source reader.
+ *
+ * The heal then crystallizes through the normal candidate flow (record_candidate
+ * / fallback) — deterministic re-render, human-reviewed; the agent re-locates,
+ * it does not author the spec. Pure: prompt-building only.
+ */
+import type { RunFailure } from './runFailures.js';
+/** A short, chat-friendly label for the heal run (the user bubble), vs the full
+ *  prompt the agent receives. */
+export declare function healLabel(slug: string): string;
+export declare function buildHealPrompt(slug: string, specSource: string, failures: RunFailure[]): string;
+//# sourceMappingURL=healPrompt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"healPrompt.d.ts","sourceRoot":"","sources":["../../src/specs/healPrompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;iCACiC;AACjC,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,MAAM,CA2ChG"}

package/dist/specs/healPrompt.js

@@ -0,0 +1,48 @@
+/** A short, chat-friendly label for the heal run (the user bubble), vs the full
+ *  prompt the agent receives. */
+export function healLabel(slug) {
+    return `🏥 Heal "${slug}" — re-running the flow to fix what changed`;
+}
+export function buildHealPrompt(slug, specSource, failures) {
+    const failureLines = failures.length > 0
+        ? failures.map(f => {
+            const what = f.failingLocator
+                ? `${f.failingAction ?? 'a step'} on \`${f.failingLocator}\` no longer matches`
+                : (f.error || 'a step failed');
+            return `  - ${what}`;
+        }).join('\n')
+        : '  - (no structured failure captured — re-run the whole flow and fix whatever no longer works)';
+    return [
+        `You are REPAIRING a saved Playwright test that no longer passes because the`,
+        `app under test changed. Re-perform its flow against the LIVE app and fix only`,
+        `the step(s) that broke — do not invent new behavior or add unrelated steps.`,
+        ``,
+        `Test: "${slug}"`,
+        ``,
+        `What it does (the saved spec — this is the intended flow to reproduce):`,
+        `\`\`\`ts`,
+        specSource.trim(),
+        `\`\`\``,
+        ``,
+        `What broke on replay:`,
+        failureLines,
+        ``,
+        `How to repair it:`,
+        `  - Open the app and walk the SAME flow, interacting through the grounded`,
+        `    control tools (click_control / fill_control / select_control / …) so the`,
+        `    repaired selectors stay replayable.`,
+        `  - Where a step's old selector no longer matches, find the element that step`,
+        `    INTENDED and operate that instead. Read the component source if you are`,
+        `    unsure why it moved or what replaced it.`,
+        `  - JUDGE broke-vs-changed: if a failure is because the app INTENTIONALLY`,
+        `    changed (the feature now works differently — not a regression), adapt the`,
+        `    flow to the new correct behavior and say so in your summary. If it looks`,
+        `    like a real regression (the app is wrong), report it as a finding and heal`,
+        `    to what the test originally intended.`,
+        `  - Keep dynamic content dynamic: if a step grounds on data that varies`,
+        `    run-to-run, flag it dynamic — don't freeze this run's value.`,
+        ``,
+        `When the flow works end to end, call record_candidate with the test's name so`,
+        `the repaired version can be saved. Do not write any file yourself.`,
+    ].join('\n');
+}

package/dist/specs/humanSteps.d.ts

@@ -1,18 +1,14 @@
 /**
  * Translate the captured `browser_*` tool calls into plain English.
  *
- * Used by:
- *   - writeSpec.ts — to enrich the generated `.spec.ts` JSDoc with a
- *     numbered "Steps:" block that QA / PMs can read without grokking
- *     `getByRole(...)`.
- *   - writeCaseCsv.ts — to populate the Step column of an
- *     Xray-compatible test case CSV, so the same prose travels into
- *     Jira / Xray / Zephyr.
+ * Used by writeSpec.ts to enrich the generated `.spec.ts` JSDoc with a
+ * numbered "Steps:" block that QA / PMs can read without grokking
+ * `getByRole(...)`.
  *
  * Mirrors the tool dispatch table in writeSpec.ts:translateStep — when
  * a new replayable browser action is added there, add it here too.
  */
-import type { SkillStep } from '../skills/writeSkill.js';
+import type { SkillStep } from '../specs/specStep.js';
 /** A single human-readable line for one tool call, or null to skip. */
 export declare function humanStep(tool: string, rawInput: unknown): string | null;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"humanSteps.d.ts","sourceRoot":"","sources":["../../src/specs/humanSteps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAwDxE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,CAmBvD"}
+{"version":3,"file":"humanSteps.d.ts","sourceRoot":"","sources":["../../src/specs/humanSteps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAwDxE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,CAmBvD"}

package/dist/specs/humanSteps.js

@@ -91,7 +91,12 @@ function describe(raw) {
     const s = String(raw ?? '').trim();
     return s.length > 0 ? s : 'the target element';
 }
-/** Wrap in double-quotes for prose; escape internal quotes. */
+/** Wrap in double-quotes for prose; escape internal quotes. A redacted
+ *  credential (stored as a `process.env.X …` expression) shows as the masked
+ *  `$X` instead — the prose, like the code, never reveals the secret. */
 function quote(s) {
+    const env = /^process\.env\.([A-Za-z0-9_]+)/.exec(s);
+    if (env)
+        return `$${env[1]}`;
     return `"${s.replace(/"/g, '\\"')}"`;
 }

package/dist/specs/optimizeSpec.d.ts

@@ -5,6 +5,20 @@ export declare class OptimizeError extends Error {
 }
 /** Runs the codegen LLM on a prompt and returns its raw text output. */
 export type RunCodegen = (prompt: string) => Promise<string>;
+/** Project context fed to the refinement pass so the candidate FITS the existing
+ *  suite: the team's conventions + the reusable Page Objects to prefer over raw
+ *  locators. Relevant files only (POMs + conventions), NOT the whole suite — the
+ *  refinement is a cheap pass, keep the context bounded. */
+export interface SuiteContext {
+    conventions?: string;
+    pages: {
+        name: string;
+        source: string;
+    }[];
+}
+/** Best-effort gather of the suite context (conventions.md + __vibe_tests__/pages
+ *  Page Objects). Missing files → empty; never throws. */
+export declare function gatherSuiteContext(devRoot: string): Promise<SuiteContext>;
 export interface OptimizeResult {
     /** Absolute path of the written candidate (never the original spec). */
     candidatePath: string;
@@ -20,7 +34,7 @@ export declare function optimizeSpec(devRoot: string, slug: string, runCodegen:
  * 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;
+export declare function buildOptimizePrompt(draft: string, sidecar: SpecSidecar | null, seeds?: SeedRule[], suite?: SuiteContext): string;
 /** Strip a ```ts fence if the model wrapped its output in one. */
 export declare function extractCode(raw: string): string;
 /**
@@ -32,11 +46,4 @@ 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

@@ -1 +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"}
+{"version":3,"file":"optimizeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/optimizeSpec.ts"],"names":[],"mappings":"AAeA,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAgC,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGzE,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;;;4DAG4D;AAC5D,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3C;AAOD;0DAC0D;AAC1D,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAgB/E;AAED,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,CAwCzB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,GAAG,IAAI,EAC3B,KAAK,GAAE,QAAQ,EAAO,EACtB,KAAK,GAAE,YAA4B,GAClC,MAAM,CAkFR;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"}

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/optimizeSpecWithAgent.d.ts

@@ -3,8 +3,6 @@ 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>;

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

@@ -1 +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"}
+{"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,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,CA2BzB"}

package/dist/specs/optimizeSpecWithAgent.js

@@ -24,7 +24,6 @@ export async function optimizeSpecWithAgent(devRoot, slug, opts) {
             prompt,
             model: opts.model,
             maxBudgetUsd: opts.maxBudgetUsd,
-            apiKey: opts.apiKey,
             signal: opts.signal,
             disallowedTools,
         })) {

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":"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;;wDAEwD;AACxD,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAUhG"}

package/dist/specs/pageObjectManifest.js

@@ -13,7 +13,7 @@
  */
 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 +26,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;AAkBlF,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"}