@hover-dev/core 0.20.0 → 0.22.0

package/dist/engine.d.ts

@@ -15,8 +15,12 @@
 export { writeSpec } from './specs/writeSpec.js';
 export type { WriteSpecOptions, WriteSpecResult, Redaction } from './specs/writeSpec.js';
 export type { SkillStep } from './specs/specStep.js';
+export { reRenderSpec } from './specs/writeSpec.js';
 export { writeApiSpec } from './specs/writeApiSpec.js';
 export type { ApiCheck, WriteApiSpecOptions, WriteApiSpecResult } from './specs/writeApiSpec.js';
+export { extractPageObjects, detectExtractableFlows } from './specs/extractPageObjects.js';
+export type { ExtractResult, ExtractedPage } from './specs/extractPageObjects.js';
+export type { SharedFlow } from './specs/detectSharedFlows.js';
 export { replayGroundedSteps, replayOnPage, applyGroundedStep, groundedLocate } from './specs/replayGrounded.js';
 export type { ReplayResult, ReplayFailure, ReplayStep, GroundedTarget } from './specs/replayGrounded.js';
 export { readSidecar } from './specs/sidecar.js';

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACzF,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,YAAY,EAAE,QAAQ,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAEjG,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACjH,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEzG,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrG,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAGhF,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACrG,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAG/D,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACzG,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACzF,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,YAAY,EAAE,QAAQ,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAEjG,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAC3F,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAClF,YAAY,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE/D,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACjH,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEzG,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrG,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAGhF,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACrG,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAG/D,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACzG,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/engine.js

@@ -14,8 +14,11 @@
  */
 // ── crystallization + grounded replay ────────────────────────────────────────
 export { writeSpec } from './specs/writeSpec.js';
+export { reRenderSpec } from './specs/writeSpec.js';
 // API-layer crystallizer — observed/replayed requests → *.api-test.spec.ts.
 export { writeApiSpec } from './specs/writeApiSpec.js';
+// Page-Object extraction — lift NON-login shared flows into pages/ + fixtures.
+export { extractPageObjects, detectExtractableFlows } from './specs/extractPageObjects.js';
 // Creation-verification + self-heal: replay a flow's grounded steps over CDP (no playwright test).
 export { replayGroundedSteps, replayOnPage, applyGroundedStep, groundedLocate } from './specs/replayGrounded.js';
 // Spec sidecar (recorded grounded steps) — read by self-heal to replay a saved spec.

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

@@ -1 +1 @@
-{"version":3,"file":"detectSharedFlows.d.ts","sourceRoot":"","sources":["../../src/specs/detectSharedFlows.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB;2CACuC;IACvC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,yDAAyD;IACzD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;wDACoD;IACpD,WAAW,EAAE,SAAS,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B;2EACuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;sDACkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAgC5E;AAwDD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,UAAU,EAAE,CAAC,CAiCvB"}
+{"version":3,"file":"detectSharedFlows.d.ts","sourceRoot":"","sources":["../../src/specs/detectSharedFlows.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB;2CACuC;IACvC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,yDAAyD;IACzD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;wDACoD;IACpD,WAAW,EAAE,SAAS,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B;2EACuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;sDACkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CA2C5E;AA+DD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,UAAU,EAAE,CAAC,CAiCvB"}

package/dist/specs/detectSharedFlows.js

@@ -55,11 +55,28 @@ export function stepSignature(tool, rawInput) {
         }
         case 'browser_press_key':
             return `press:${String(i.key ?? '')}`;
+        // Grounded control tools (MCP-first): the target is role+name/testId/text on
+        // the input. The typed/selected value is data; only the target is structure.
+        case 'click_control':
+            return `click:${normGround(i)}`;
+        case 'fill_control':
+            return `type:${normGround(i)}`;
+        case 'select_control':
+            return `select:${normGround(i)}`;
+        case 'check_control':
+            return `check:${normGround(i)}`;
         default:
-            // Diagnostics / browser_tabs / browser_wait_for — not flow structure.
+            // Diagnostics / assert_visible / browser_tabs / browser_wait_for — not
+            // flow structure (an assertion isn't part of a reusable action prefix).
             return null;
     }
 }
+/** Normalize a GROUNDED target ({ role, name, testId, text }) to a stable
+ *  signature fragment — the *_control sibling of normElement. */
+function normGround(i) {
+    const parts = [i.role, i.name, i.testId, i.text].filter((v) => typeof v === 'string' && v.length > 0);
+    return normElement(parts.join('|'));
+}
 /** 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

package/dist/specs/extractPageObjects.d.ts

@@ -0,0 +1,22 @@
+import { type SharedFlow } from './detectSharedFlows.js';
+export interface ExtractedPage {
+    className: string;
+    methodName: string;
+    fileName: string;
+    path: string;
+    /** Slugs of the specs that share this flow. */
+    specs: string[];
+}
+export interface ExtractResult {
+    pages: ExtractedPage[];
+    fixturesPath: string | null;
+    /** Slugs re-rendered to consume the new Page Objects. */
+    folded: string[];
+}
+/** Detect shared flows worth extracting — NON-login prefixes shared by >= minSpecs
+ *  specs. Read-only: the agent uses this to decide what to ASK the user about. */
+export declare function detectExtractableFlows(devRoot: string, minSpecs?: number): Promise<SharedFlow[]>;
+export declare function extractPageObjects(devRoot: string, opts?: {
+    minSpecs?: number;
+}): Promise<ExtractResult>;
+//# sourceMappingURL=extractPageObjects.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extractPageObjects.d.ts","sourceRoot":"","sources":["../../src/specs/extractPageObjects.ts"],"names":[],"mappings":"AAeA,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAK5E,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,yDAAyD;IACzD,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAcD;kFACkF;AAClF,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAGjG;AAED,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,aAAa,CAAC,CA+CxB"}

package/dist/specs/extractPageObjects.js

@@ -0,0 +1,118 @@
+/**
+ * Page Object extraction (F4) — lift flows shared across saved specs into
+ * `pages/<Name>.ts` + a `fixtures.ts` entry point, then FOLD the specs that use
+ * them (they consume `await xPage.x()` from `./fixtures` instead of repeating
+ * the steps). Fully deterministic — no LLM.
+ *
+ * MCP-first trigger: after `test_app` crystallizes the suite, the agent calls
+ * `detect_shared_flows`, ASKS the user, and on yes calls this. LOGIN prefixes
+ * are EXCLUDED — auth-fixture already lifts login into auth.setup.ts, and
+ * folding it here would double it. So this only extracts NON-login shared
+ * entry flows (the case that scales on large suites).
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { detectSharedFlows } from './detectSharedFlows.js';
+import { generatePageObject } from './generatePageObject.js';
+import { writePageObjectManifest } from './pageObjectManifest.js';
+import { reRenderSpec } from './writeSpec.js';
+/** A shared prefix is a LOGIN (auth-fixture's job, not a POM) when it types a
+ *  credential — the sidecar's fill value is a `process.env.<X>` ref. */
+function isLoginPrefix(steps) {
+    return steps.some((s) => {
+        if (s.kind !== 'step')
+            return false;
+        const tool = (s.tool ?? '').replace(/^mcp__[a-z0-9_-]+?__/, '');
+        const input = (s.input ?? {});
+        const v = tool === 'browser_type' ? input.text : tool === 'fill_control' ? input.value : null;
+        return typeof v === 'string' && /process\.env\./.test(v);
+    });
+}
+/** Detect shared flows worth extracting — NON-login prefixes shared by >= minSpecs
+ *  specs. Read-only: the agent uses this to decide what to ASK the user about. */
+export async function detectExtractableFlows(devRoot, minSpecs = 2) {
+    const flows = await detectSharedFlows(devRoot, { minSpecs });
+    return flows.filter((f) => !isLoginPrefix(f.prefixSteps));
+}
+export async function extractPageObjects(devRoot, opts = {}) {
+    const flows = await detectExtractableFlows(devRoot, opts.minSpecs ?? 2);
+    if (flows.length === 0)
+        return { pages: [], fixturesPath: null, folded: [] };
+    const testsDir = join(devRoot, '__vibe_tests__');
+    const pagesDir = join(testsDir, 'pages');
+    await mkdir(pagesDir, { recursive: true });
+    const pages = [];
+    const entries = [];
+    const usedNames = new Set();
+    const affected = new Set();
+    for (const flow of flows) {
+        const probe = generatePageObject(flow.prefixSteps);
+        const className = uniqueName(probe.className, usedNames);
+        const po = className === probe.className ? probe : generatePageObject(flow.prefixSteps, { className });
+        const path = join(pagesDir, po.fileName);
+        await writeFile(path, po.source, 'utf-8');
+        pages.push({ className: po.className, methodName: po.methodName, fileName: po.fileName, path, specs: flow.specs });
+        entries.push({
+            className: po.className,
+            methodName: po.methodName,
+            fixtureName: fixtureName(po.className),
+            fileName: po.fileName,
+            signatures: flow.signatures,
+            specs: flow.specs,
+        });
+        flow.specs.forEach((s) => affected.add(s));
+    }
+    const fixturesPath = join(testsDir, 'fixtures.ts');
+    await writeFile(fixturesPath, renderFixtures(pages), 'utf-8');
+    // The manifest lets writeSpec's matchPageObject fold a matching prefix.
+    await writePageObjectManifest(devRoot, entries);
+    // Fold NOW: faithfully re-render each affected spec so it consumes the Page
+    // Object (via reRenderSpec, which re-applies auth-fixture/base-url from the
+    // sidecar — never regressing them). Non-login prefixes → no auth conflict.
+    const folded = [];
+    for (const slug of affected) {
+        try {
+            if (await reRenderSpec(devRoot, slug))
+                folded.push(slug);
+        }
+        catch {
+            /* a fold is best-effort — the page/fixture still exist for future specs */
+        }
+    }
+    return { pages, fixturesPath, folded };
+}
+function renderFixtures(pages) {
+    const lines = [
+        `import { test as base } from '@playwright/test';`,
+        ...pages.map((p) => `import { ${p.className} } from './pages/${p.className}';`),
+        ``,
+        `/**`,
+        ` * Generated by Hover — Page Object fixtures lifted from flows shared across`,
+        ` * specs. In a spec: \`import { test, expect } from './fixtures';\` then consume`,
+        ` * e.g. \`async ({ page, ${pages[0] ? fixtureName(pages[0].className) : 'somePage'} }) => …\`.`,
+        ` */`,
+        `export const test = base.extend<{ ${pages.map((p) => `${fixtureName(p.className)}: ${p.className}`).join('; ')} }>({`,
+        ...pages.flatMap((p) => [
+            `  ${fixtureName(p.className)}: async ({ page }, use) => {`,
+            `    await use(new ${p.className}(page));`,
+            `  },`,
+        ]),
+        `});`,
+        ``,
+        `export { expect } from '@playwright/test';`,
+        ``,
+    ];
+    return lines.join('\n');
+}
+/** LoginPage -> loginPage. */
+function fixtureName(className) {
+    return className.charAt(0).toLowerCase() + className.slice(1);
+}
+function uniqueName(base, used) {
+    let name = base;
+    let n = 2;
+    while (used.has(name))
+        name = `${base}${n++}`;
+    used.add(name);
+    return name;
+}

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,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"}
+{"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;AAWtD,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,CA0FlB"}

package/dist/specs/generatePageObject.js

@@ -1,4 +1,4 @@
-import { selectorFromDescription, selectorForFormField, emitInteraction, blockScope, } from './writeSpec.js';
+import { selectorFromDescription, selectorForFormField, emitInteraction, blockScope, groundedSelector, } from './writeSpec.js';
 const PAGE_VAR = 'this.page';
 export function generatePageObject(steps, override = {}) {
     const derived = deriveNames(steps);
@@ -49,8 +49,29 @@ export function generatePageObject(steps, override = {}) {
             case 'browser_press_key':
                 body.push(`await ${PAGE_VAR}.keyboard.press(${JSON.stringify(String(i.key ?? ''))});`);
                 break;
+            // Grounded control tools (MCP-first): target is role+name/testId/text on
+            // the input; the typed/selected value is data → a method parameter (D4).
+            case 'click_control':
+                body.push(...blockScope(emitInteraction(groundedSelector(i, PAGE_VAR), 'click()')));
+                break;
+            case 'fill_control': {
+                const p = uniqueParam(paramName(groundLabel(i)), used);
+                params.push(p);
+                body.push(...blockScope(emitInteraction(groundedSelector(i, PAGE_VAR), `fill(${p})`)));
+                break;
+            }
+            case 'select_control': {
+                const withRole = i.role ? i : { ...i, role: i.name ? 'combobox' : undefined };
+                const p = uniqueParam(paramName(groundLabel(i)), used);
+                params.push(p);
+                body.push(...blockScope(emitInteraction(groundedSelector(withRole, PAGE_VAR), `selectOption(${p})`)));
+                break;
+            }
+            case 'check_control':
+                body.push(...blockScope(emitInteraction(groundedSelector(i, PAGE_VAR), i.checked === false ? 'uncheck()' : 'check()')));
+                break;
             default:
-                break; // diagnostics / non-replayable — skipped
+                break; // diagnostics / assert_visible / non-replayable — skipped
         }
     }
     const paramList = params.map(p => `${p}: string`).join(', ');
@@ -127,6 +148,10 @@ function pascal(raw) {
 }
 /** Parameter name derived from a field/element label. */
 const paramName = camel;
+/** A grounded target's label (name → testId → text) for naming its data param. */
+function groundLabel(i) {
+    return String(i.name ?? i.testId ?? i.text ?? 'value');
+}
 function uniqueParam(base, used) {
     const root = base || 'value';
     let name = root;

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

@@ -1 +1 @@
-{"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"}
+{"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,CAoExE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,CAmBvD"}

package/dist/specs/humanSteps.js

@@ -40,6 +40,18 @@ export function humanStep(tool, rawInput) {
             const key = String(input.key ?? '');
             return key ? `Press ${key}` : null;
         }
+        // Grounded control tools (MCP-first) — the target is role+name/testId/text
+        // ON the input itself, not an `element` string.
+        case 'click_control':
+            return `Click ${describeGrounded(input)}`;
+        case 'fill_control':
+            return `Fill ${describeGrounded(input)} with ${quote(String(input.value ?? ''))}`;
+        case 'select_control':
+            return `Select ${quote(String(input.value ?? ''))} in ${describeGrounded(input)}`;
+        case 'check_control':
+            return `${input.checked === false ? 'Uncheck' : 'Check'} ${describeGrounded(input)}`;
+        case 'assert_visible':
+            return `Expect ${describeGrounded(input)} to be visible`;
         // Diagnostic / read-only — same skip list as writeSpec.translateStep.
         case 'browser_wait_for':
         case 'browser_tabs':
@@ -91,6 +103,23 @@ function describe(raw) {
     const s = String(raw ?? '').trim();
     return s.length > 0 ? s : 'the target element';
 }
+/** Human phrase for a GROUNDED target ({ role, name, testId, text }) — the shape
+ *  the *_control tools carry, vs the old browser_* tools' `element` string. */
+function describeGrounded(input) {
+    const role = typeof input.role === 'string' ? input.role : '';
+    const name = typeof input.name === 'string' ? input.name : '';
+    const testId = typeof input.testId === 'string' ? input.testId : '';
+    const text = typeof input.text === 'string' ? input.text : '';
+    if (role && name)
+        return `${role} "${name}"`;
+    if (name)
+        return `"${name}"`;
+    if (testId)
+        return `testId "${testId}"`;
+    if (text)
+        return `"${text}"`;
+    return 'the target element';
+}
 /** 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. */

package/dist/specs/sidecar.d.ts

@@ -2,7 +2,7 @@ import type { SkillStep } from '../specs/specStep.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 declare const SIDECAR_VERSION = 2;
 export interface SpecSidecar {
     version: number;
     slug: string;
@@ -10,10 +10,24 @@ export interface SpecSidecar {
     /** ISO timestamp the sidecar was written. */
     createdAt: string;
     /** The full captured session, structured and verbatim — never re-derived
-     *  from the generated `.spec.ts`. */
+     *  from the generated `.spec.ts`. Steps are already REDACTED (credentials are
+     *  `process.env.<X>` refs, never literals), so the sidecar carries no secret. */
     steps: SkillStep[];
     /** Alt-click assertions captured alongside the session. */
     assertions: SpecAssertion[];
+    /** The env-var NAMES the run redacted credentials to (e.g. ['HOVER_PASSWORD']).
+     *  Lets a re-render re-detect the login prefix without the literal secret. */
+    redactionEnvVars?: string[];
+    /** The run's target origin — re-render uses it for baseURL / goto synthesis. */
+    startUrl?: string;
+    /** Recon reset recipe (debt-2), so a re-render re-emits the reset beforeEach. */
+    resetRecipe?: {
+        tier: number;
+        storageKeys?: string[];
+        hook?: string;
+    };
+    /** Whether the run had approved editing an existing user config (Stage 4). */
+    authFixture?: boolean;
 }
 /** Project-root `.hover/` directory — the single home for Hover-derived data
  *  (sidecars, runs, rules, conventions). */

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

@@ -1 +1 @@
-{"version":3,"file":"sidecar.d.ts","sourceRoot":"","sources":["../../src/specs/sidecar.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,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;4CAC4C;AAC5C,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,kFAAkF;AAClF,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED;;;;;gCAKgC;AAChC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AACD,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAE/E;AACD,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAErF;AAED;2EAC2E;AAC3E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;mCACmC;AACnC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;oEAEoE;AACpE,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,WAAW,CAAC,GAC/C,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAoB5F;AAED;;gEAEgE;AAChE,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAOhF"}
+{"version":3,"file":"sidecar.d.ts","sourceRoot":"","sources":["../../src/specs/sidecar.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,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;;qFAEiF;IACjF,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,2DAA2D;IAC3D,UAAU,EAAE,aAAa,EAAE,CAAC;IAI5B;kFAC8E;IAC9E,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,8EAA8E;IAC9E,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;4CAC4C;AAC5C,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,kFAAkF;AAClF,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED;;;;;gCAKgC;AAChC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AACD,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAE/E;AACD,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAErF;AAED;2EAC2E;AAC3E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;mCACmC;AACnC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;oEAEoE;AACpE,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,WAAW,CAAC,GAC/C,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAoB5F;AAED;;gEAEgE;AAChE,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAOhF"}

package/dist/specs/sidecar.js

@@ -19,7 +19,7 @@ import { mkdir, writeFile, readFile } 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;
+export const SIDECAR_VERSION = 2;
 /** Project-root `.hover/` directory — the single home for Hover-derived data
  *  (sidecars, runs, rules, conventions). */
 export function hoverDir(devRoot) {

package/dist/specs/writeSpec.d.ts

@@ -90,6 +90,19 @@ export interface WriteSpecResult {
     };
 }
 export declare function writeSpec(opts: WriteSpecOptions): Promise<WriteSpecResult>;
+/**
+ * Re-crystallize an already-saved spec from its sidecar — FAITHFULLY. Used by
+ * self-heal (re-render the healed flow) and Page-Object extraction (fold a
+ * newly-extracted shared flow into the specs that use it). Reads the v2 sidecar
+ * context so the re-render re-applies the SAME auth-fixture + base URL + reset —
+ * NOT a degraded pass that would drop the login into the spec.
+ *
+ * Credentials never round-trip: the sidecar stores env-var NAMES only and its
+ * steps are already redacted, so we pass `{ value: '', envVar }` placeholders —
+ * enough for authPrefixLength to re-detect the login prefix, with no literal
+ * secret anywhere. Returns null if the spec has no sidecar.
+ */
+export declare function reRenderSpec(devRoot: string, slug: string): Promise<WriteSpecResult | null>;
 /**
  * Emit an interaction (click / dblclick / hover / fill / selectOption) as a
  * visibility-guarded prelude: hoist the locator to `el`, assert it's visible,
@@ -121,6 +134,15 @@ export declare function blockScope(lines: string[]): string[];
  * trailing role keyword is the convention Playwright MCP uses.
  */
 export declare function selectorFromDescription(desc: string, pageVar?: string): string;
+/**
+ * Selector for a Hover control-actuation step (click/fill/select_control). The
+ * agent supplied these fields straight from the snapshot, in the same priority
+ * order the actuation server resolves them — role+name → testId → text — so the
+ * crystallized selector is exactly the one that drove the action at record time
+ * (no free-form description, hence no confabulation). Mirrors
+ * `locate()` in `mcp/actuateServer.ts`.
+ */
+export declare function groundedSelector(input: Record<string, unknown>, pageVar?: string): string;
 /**
  * browser_select_option always targets a native `<select>` — whose ARIA role
  * is `combobox`. The agent's description is usually the label ("marital

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,sBAAsB,CAAC;AAatD,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;AA2CD,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;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;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;IACpB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB;;;;yEAIqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;sFAIkF;IAClF,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE;;;;qEAIiE;IACjE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAiDD,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtD;;;;;2DAKuD;IACvD,gBAAgB,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE;AAQD,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAchF;AA+mBD;;;;;;;;;;;;;;;;;;;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;AA0DD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAMxE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAQ1F"}
+{"version":3,"file":"writeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/writeSpec.ts"],"names":[],"mappings":"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"}

package/dist/specs/writeSpec.js

@@ -20,7 +20,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { humanSteps, humanStep } from './humanSteps.js';
-import { writeSidecar } from './sidecar.js';
+import { writeSidecar, readSidecar } from './sidecar.js';
 import { readPageObjectManifest, } from './pageObjectManifest.js';
 import { stepSignature } from './detectSharedFlows.js';
 import { slugify, firstSentence } from './text.js';
@@ -162,6 +162,34 @@ export async function writeSpec(opts) {
     // writeSecuritySpec — those are stateless and independently replayable.)
     return writeOneSpec(opts, slugify(opts.name), opts.name, opts.steps);
 }
+/**
+ * Re-crystallize an already-saved spec from its sidecar — FAITHFULLY. Used by
+ * self-heal (re-render the healed flow) and Page-Object extraction (fold a
+ * newly-extracted shared flow into the specs that use it). Reads the v2 sidecar
+ * context so the re-render re-applies the SAME auth-fixture + base URL + reset —
+ * NOT a degraded pass that would drop the login into the spec.
+ *
+ * Credentials never round-trip: the sidecar stores env-var NAMES only and its
+ * steps are already redacted, so we pass `{ value: '', envVar }` placeholders —
+ * enough for authPrefixLength to re-detect the login prefix, with no literal
+ * secret anywhere. Returns null if the spec has no sidecar.
+ */
+export async function reRenderSpec(devRoot, slug) {
+    const sc = await readSidecar(devRoot, slug);
+    if (!sc)
+        return null;
+    return writeSpec({
+        devRoot,
+        name: sc.name,
+        steps: sc.steps,
+        assertions: sc.assertions,
+        startUrl: sc.startUrl,
+        resetRecipe: sc.resetRecipe,
+        authFixture: sc.authFixture,
+        redactions: (sc.redactionEnvVars ?? []).map((envVar) => ({ value: '', envVar })),
+        overwrite: true,
+    });
+}
 /** Write ONE spec file from a (sub)set of steps. The single-file path and each
  *  per-flow file both go through here, so rendering / sidecar / config logic is
  *  identical whether or not the run was split. */
@@ -201,13 +229,17 @@ async function writeOneSpec(opts, slug, displayName, rawSteps) {
     const envVars = (opts.redactions ?? []).map(r => r.envVar);
     const detectedPrefix = authPrefixLength(cleanActions, envVars);
     const userConfigName = PLAYWRIGHT_CONFIG_NAMES.find(n => existsSync(join(opts.devRoot, n)));
+    // A config Hover scaffolded earlier this run (e.g. a non-login spec wrote a
+    // plain one first) is OURS to upgrade — treat it like "no user config", not a
+    // hands-off user file. ensurePlaywrightConfig adds the setup project to it.
+    const ownScaffold = !!userConfigName && readFileSync(join(opts.devRoot, userConfigName), 'utf-8').includes(SCAFFOLD_MARKER);
     // Already opted in: auth.setup.ts exists from a prior approval (and the config
     // already registers it), so engage AUTOMATICALLY — don't re-ask or re-edit.
     const authSetupExists = existsSync(join(dir, 'auth.setup.ts'));
     // Engage the fixture when a login is detected AND we can register the setup
-    // project: we scaffold the config (no user config), the caller approved editing
-    // it (opts.authFixture, Stage 4), or the fixture was already set up earlier.
-    const engage = detectedPrefix > 0 && (!userConfigName || opts.authFixture === true || authSetupExists);
+    // project: we scaffold/own the config, the caller approved editing a user
+    // config (opts.authFixture, Stage 4), or the fixture was already set up earlier.
+    const engage = detectedPrefix > 0 && (!userConfigName || ownScaffold || opts.authFixture === true || authSetupExists);
     const authPrefix = engage ? detectedPrefix : 0;
     const authFile = engage ? AUTH_STATE_FILE : undefined;
     let authFixtureOffer;
@@ -273,6 +305,12 @@ async function writeOneSpec(opts, slug, displayName, rawSteps) {
         name: displayName,
         steps,
         assertions: opts.assertions ?? [],
+        // v2 context — NAMES only (no literal creds), so a faithful re-render can
+        // re-apply auth-fixture + base URL + reset without re-driving the browser.
+        redactionEnvVars: (opts.redactions ?? []).map(r => r.envVar),
+        startUrl: opts.startUrl,
+        resetRecipe: opts.resetRecipe,
+        authFixture: opts.authFixture,
     });
     // Session-ledger patch, best-effort by contract: markSessionSaved swallows
     // its own failures — it must never break Save-as-spec.
@@ -808,7 +846,7 @@ export function selectorFromDescription(desc, pageVar = 'page') {
  * (no free-form description, hence no confabulation). Mirrors
  * `locate()` in `mcp/actuateServer.ts`.
  */
-function groundedSelector(input, pageVar = 'page') {
+export function groundedSelector(input, pageVar = 'page') {
     const role = typeof input.role === 'string' ? input.role : '';
     const name = typeof input.name === 'string' ? input.name : '';
     const testId = typeof input.testId === 'string' ? input.testId : '';
@@ -1005,28 +1043,24 @@ async function ensureResetStateHelper(devRoot, keys) {
     ].join('\n');
     await writeFile(join(dir, 'resetState.ts'), source, 'utf-8');
 }
-async function ensurePlaywrightConfig(devRoot, steps, startUrl, authFile) {
-    if (PLAYWRIGHT_CONFIG_NAMES.some(n => existsSync(join(devRoot, n))))
-        return;
-    const origin = firstNavigateOrigin(steps) ?? originOf(startUrl);
-    if (!origin)
-        return;
-    // Auth-as-fixture: register a `setup` project (matches auth.setup.ts) that the
-    // main project depends on, so login runs ONCE before the specs. Only emitted
-    // when scaffolding our own config (we never touch a user's existing one).
+const SCAFFOLD_MARKER = 'Scaffolded by Hover';
+/** The scaffolded config source. When `authFile` is set, a `setup` project runs
+ *  auth.setup.ts ONCE and the main `chromium` project reuses the saved
+ *  storageState — so EVERY spec starts authenticated, not just the login flow. */
+function renderScaffoldConfig(origin, authFile) {
     const projects = authFile
         ? [
             `  projects: [`,
             `    { name: 'setup', testMatch: /.*\\.setup\\.ts$/ },`,
-            `    { name: 'chromium', dependencies: ['setup'] },`,
+            `    { name: 'chromium', dependencies: ['setup'], use: { storageState: ${JSON.stringify(authFile)} } },`,
             `  ],`,
         ]
         : [];
-    const source = [
+    return [
         `import { defineConfig } from '@playwright/test';`,
         ``,
         `/**`,
-        ` * Scaffolded by Hover so crystallized specs (which use relative URLs like`,
+        ` * ${SCAFFOLD_MARKER} so crystallized specs (which use relative URLs like`,
         ` * page.goto("/")) resolve against a base. Override HOVER_BASE_URL in CI to`,
         ` * point the same specs at staging/prod.`,
         ` */`,
@@ -1039,7 +1073,50 @@ async function ensurePlaywrightConfig(devRoot, steps, startUrl, authFile) {
         `});`,
         ``,
     ].join('\n');
-    await writeFile(join(devRoot, 'playwright.config.ts'), source, 'utf-8');
+}
+async function ensurePlaywrightConfig(devRoot, steps, startUrl, authFile) {
+    const origin = firstNavigateOrigin(steps) ?? originOf(startUrl);
+    if (!origin)
+        return;
+    const existingName = PLAYWRIGHT_CONFIG_NAMES.find(n => existsSync(join(devRoot, n)));
+    if (existingName) {
+        // A config already exists. Only ever UPGRADE our OWN scaffold — and only to
+        // add the auth `setup` project when a login was just lifted (authFile) and
+        // it isn't there yet. This makes auth order-independent: whichever spec in
+        // the run triggers auth-fixture upgrades the config, even if a non-login
+        // spec scaffolded a plain config first. A user's own config is never touched
+        // (that's the Stage-4 approval flow via authFixtureOffer).
+        if (!authFile)
+            return;
+        try {
+            const cur = readFileSync(join(devRoot, existingName), 'utf-8');
+            if (!cur.includes(SCAFFOLD_MARKER) || cur.includes(`name: 'setup'`))
+                return;
+            await writeFile(join(devRoot, existingName), renderScaffoldConfig(origin, authFile), 'utf-8');
+        }
+        catch { /* upgrade is best-effort */ }
+        return;
+    }
+    await writeFile(join(devRoot, 'playwright.config.ts'), renderScaffoldConfig(origin, authFile), 'utf-8');
+    await ensurePlaywrightDep(devRoot);
+}
+/** When Hover scaffolds the config it also ensures `@playwright/test` is a
+ *  devDependency — otherwise `npx playwright test` can't run the specs locally.
+ *  Best-effort + idempotent: skips if already present (either dep list) or if
+ *  there's no package.json. Reformats to 2-space JSON (the npm norm). */
+const PLAYWRIGHT_TEST_RANGE = '^1.50.0';
+async function ensurePlaywrightDep(devRoot) {
+    const pkgPath = join(devRoot, 'package.json');
+    if (!existsSync(pkgPath))
+        return;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        if (pkg.dependencies?.['@playwright/test'] || pkg.devDependencies?.['@playwright/test'])
+            return;
+        pkg.devDependencies = { ...(pkg.devDependencies ?? {}), '@playwright/test': PLAYWRIGHT_TEST_RANGE };
+        await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+    }
+    catch { /* best-effort — never break Save */ }
 }
 function stripBaseUrl(url) {
     // http://localhost:5173/checkout → /checkout, http://localhost:5173/ → /

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hover-dev/core",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Hover's local Node service: agent invocation, Playwright CDP preflight, WebSocket bridge.",
   "license": "Apache-2.0",
   "author": "Hyperyond",