@hover-dev/core 0.21.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/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;AAonBD;;;;;;;;;;;;;;;;;;;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. */
@@ -277,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.
@@ -812,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 : '';

package/package.json

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