@hover-dev/core 0.14.1 → 0.16.0

package/dist/skills/writeSkill.d.ts

@@ -1,8 +1,15 @@
-export declare class SkillExistsError extends Error {
-    readonly slug: string;
-    readonly path: string;
-    constructor(slug: string, path: string);
-}
+/**
+ * Captured-step type.
+ *
+ * NOTE: Save-as-Skill (writing `.claude/skills/<slug>/SKILL.md` for agent
+ * replay) was retired — `spec` + ⟳ Re-record covers intent-driven replay, and
+ * "skill" collided with Claude Code's own skills concept. All that remains
+ * here is `SkillStep`: the serialized message shape from the widget's
+ * localStorage, which the whole spec pipeline (writeSpec, sidecar, listSpecs,
+ * Page-Object extraction) consumes as `SpecStep`. The file keeps its path so
+ * the many `import { SkillStep } from '../skills/writeSkill.js'` call sites
+ * don't churn; renaming to a neutral module is a separate mechanical pass.
+ */
 /**
  * Serialized message shape from the widget's localStorage. Matches the
  * `state.messages` schema in packages/widget-bootstrap/src/widget/client.js.
@@ -17,34 +24,4 @@ export interface SkillStep {
     costUsd?: number;
     summary?: string;
 }
-export interface WriteSkillOptions {
-    /** Directory under which `.claude/skills/<slug>/` is created. Usually the
-     *  Vite project root (`server.config.root`). */
-    devRoot: string;
-    name: string;
-    description?: string;
-    steps: SkillStep[];
-    /** If false (default), throws SkillExistsError when a skill with the same
-     *  slug already exists. If true, overwrites unconditionally. The widget
-     *  uses the two paths to give the user a confirm dialog. */
-    overwrite?: boolean;
-}
-export interface WriteSkillResult {
-    path: string;
-    slug: string;
-}
-export declare function writeSkill(opts: WriteSkillOptions): Promise<WriteSkillResult>;
-export interface SkillSummary {
-    slug: string;
-    name: string;
-    description: string;
-    path: string;
-}
-/**
- * List skills under <devRoot>/.claude/skills/, reading the YAML frontmatter
- * of each SKILL.md for `name` and `description`. Malformed entries are
- * silently skipped — better to show 9 valid skills than refuse to render
- * because one is broken. Hand-edited skills are first-class.
- */
-export declare function listSkills(devRoot: string): Promise<SkillSummary[]>;
 //# sourceMappingURL=writeSkill.d.ts.map

package/dist/skills/writeSkill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"writeSkill.d.ts","sourceRoot":"","sources":["../../src/skills/writeSkill.ts"],"names":[],"mappings":"AAmBA,qBAAa,gBAAiB,SAAQ,KAAK;aACb,IAAI,EAAE,MAAM;aAAkB,IAAI,EAAE,MAAM;gBAA1C,IAAI,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAIvE;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC;oDACgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB;;gEAE4D;IAC5D,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAoBnF;AA8ED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CA8BzE"}
+{"version":3,"file":"writeSkill.d.ts","sourceRoot":"","sources":["../../src/skills/writeSkill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/skills/writeSkill.js

@@ -1,169 +1,13 @@
 /**
- * Save a completed Hover session as a Claude Code skill.
+ * Captured-step type.
  *
- * Writes a SKILL.md under `<devRoot>/.claude/skills/<slug>/`. When the agent
- * is later spawned with `cwd: devRoot`, Claude Code auto-discovers the skill
- * and can replay it when the user describes the same task in natural language
- * (e.g. "run the login-and-add-todo skill").
- *
- * Two reasons this is just-good-enough for v1:
- *  - The exact tool calls (with args) become numbered steps the agent can
- *    replay literally. Same dev server, same selectors → same outcome.
- *  - The original user prompt + AI outcome are preserved as prose. If the
- *    page changed and the literal selectors no longer apply, the agent has
- *    enough context to adapt rather than fail.
- */
-import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-export class SkillExistsError extends Error {
-    slug;
-    path;
-    constructor(slug, path) {
-        super(`Skill "${slug}" already exists at ${path}`);
-        this.slug = slug;
-        this.path = path;
-        this.name = 'SkillExistsError';
-    }
-}
-export async function writeSkill(opts) {
-    const slug = slugify(opts.name);
-    if (!slug) {
-        throw new Error('skill name must contain at least one alphanumeric character');
-    }
-    if (!opts.steps.some(s => s.kind === 'step')) {
-        throw new Error('skill must contain at least one tool_use step to replay');
-    }
-    const dir = join(opts.devRoot, '.claude', 'skills', slug);
-    const path = join(dir, 'SKILL.md');
-    if (!opts.overwrite && existsSync(path)) {
-        throw new SkillExistsError(slug, path);
-    }
-    await mkdir(dir, { recursive: true });
-    const md = renderSkill(slug, opts.description ?? '', opts.steps);
-    await writeFile(path, md, 'utf-8');
-    return { path, slug };
-}
-function slugify(name) {
-    return name
-        .toLowerCase()
-        .trim()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
-}
-function renderSkill(slug, description, steps) {
-    const userMsg = steps.find(s => s.kind === 'user');
-    const doneMsg = [...steps].reverse().find(s => s.kind === 'done');
-    const toolSteps = steps.filter(s => s.kind === 'step');
-    const out = [];
-    out.push('---');
-    out.push(`name: ${slug}`);
-    // YAML description — quote if it contains anything that could confuse the parser
-    out.push(`description: ${yamlString(description || slug)}`);
-    out.push('---');
-    out.push('');
-    if (userMsg?.text) {
-        out.push('## Original intent');
-        out.push('');
-        out.push(blockquote(userMsg.text));
-        out.push('');
-    }
-    out.push('## Replay steps');
-    out.push('');
-    out.push('Replay these steps using the `mcp__playwright` tools, in order. ' +
-        'If a literal selector id (e.g. `e15`) no longer matches, interpret the ' +
-        'natural-language element description instead — selector ids regenerate on every snapshot.');
-    out.push('');
-    out.push('Do not narrate each step, do not summarize at the end. Hover surfaces ' +
-        'tool calls + the final result to the user automatically — extra commentary is noise.');
-    out.push('');
-    toolSteps.forEach((step, i) => {
-        const tool = step.tool ?? '(unknown)';
-        const inputStr = JSON.stringify(step.input ?? {});
-        const truncated = inputStr.length > 240 ? inputStr.slice(0, 237) + '…' : inputStr;
-        out.push(`${i + 1}. \`${tool}\` — \`${truncated}\``);
-    });
-    out.push('');
-    if (doneMsg?.summary) {
-        out.push('## Original outcome');
-        out.push('');
-        out.push(doneMsg.summary.trim());
-        out.push('');
-    }
-    return out.join('\n');
-}
-function yamlString(s) {
-    // Cheap quoting — if it has YAML-significant chars, double-quote and escape.
-    if (/[:#\n"'\\]/.test(s)) {
-        return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
-    }
-    return s;
-}
-function blockquote(s) {
-    return s
-        .split('\n')
-        .map(line => `> ${line}`)
-        .join('\n');
-}
-/**
- * List skills under <devRoot>/.claude/skills/, reading the YAML frontmatter
- * of each SKILL.md for `name` and `description`. Malformed entries are
- * silently skipped — better to show 9 valid skills than refuse to render
- * because one is broken. Hand-edited skills are first-class.
+ * NOTE: Save-as-Skill (writing `.claude/skills/<slug>/SKILL.md` for agent
+ * replay) was retired — `spec` + ⟳ Re-record covers intent-driven replay, and
+ * "skill" collided with Claude Code's own skills concept. All that remains
+ * here is `SkillStep`: the serialized message shape from the widget's
+ * localStorage, which the whole spec pipeline (writeSpec, sidecar, listSpecs,
+ * Page-Object extraction) consumes as `SpecStep`. The file keeps its path so
+ * the many `import { SkillStep } from '../skills/writeSkill.js'` call sites
+ * don't churn; renaming to a neutral module is a separate mechanical pass.
  */
-export async function listSkills(devRoot) {
-    const root = join(devRoot, '.claude', 'skills');
-    let entries;
-    try {
-        entries = await readdir(root);
-    }
-    catch {
-        return [];
-    }
-    const skills = [];
-    for (const slug of entries) {
-        if (slug.startsWith('.'))
-            continue;
-        const path = join(root, slug, 'SKILL.md');
-        let content;
-        try {
-            content = await readFile(path, 'utf-8');
-        }
-        catch {
-            continue;
-        }
-        const fm = parseFrontmatter(content);
-        skills.push({
-            slug,
-            name: fm.name ?? slug,
-            description: fm.description ?? '',
-            path,
-        });
-    }
-    // Sort newest-first by mtime would require fs.stat; alpha is fine and stable.
-    skills.sort((a, b) => a.slug.localeCompare(b.slug));
-    return skills;
-}
-function parseFrontmatter(content) {
-    const match = content.match(/^---\n([\s\S]*?)\n---/);
-    if (!match)
-        return {};
-    const out = {};
-    for (const line of match[1].split('\n')) {
-        const m = line.match(/^(\w+)\s*:\s*(.+)$/);
-        if (!m)
-            continue;
-        let value = m[2].trim();
-        // Strip wrapping quotes if present (yamlString() in renderSkill quotes
-        // strings with YAML-significant chars).
-        if ((value.startsWith('"') && value.endsWith('"')) ||
-            (value.startsWith("'") && value.endsWith("'"))) {
-            value = value
-                .slice(1, -1)
-                .replace(/\\"/g, '"')
-                .replace(/\\\\/g, '\\');
-        }
-        out[m[1]] = value;
-    }
-    return out;
-}
+export {};

package/dist/specs/detectSharedFlows.d.ts

@@ -0,0 +1,35 @@
+import type { SkillStep } from '../skills/writeSkill.js';
+export interface SharedFlow {
+    /** The shared signature prefix, one entry per step. */
+    signatures: string[];
+    /** Human-readable prose for each prefix step (from one representative spec),
+     *  for display in the widget / CLI. */
+    prose: string[];
+    /** Slugs of the specs that share this prefix, sorted. */
+    specs: string[];
+    /** The representative spec's original steps for the shared prefix, fed to
+     *  generatePageObject during Stage 3 extraction. */
+    prefixSteps: SkillStep[];
+}
+export interface DetectOptions {
+    /** Minimum number of specs that must share the prefix to report it.
+     *  Default 2 (surface candidates early); Stage 3 extraction uses 3. */
+    minSpecs?: number;
+    /** Minimum prefix length (in steps) worth reporting. Default 2 — a single
+     *  shared navigation is too weak to be a flow. */
+    minLen?: number;
+}
+/**
+ * Reduce one captured step to a signature string: the tool plus its structural
+ * target, with data values stripped. Returns null for steps that aren't part
+ * of a replayable flow (diagnostics, tab switches, waits) so they don't anchor
+ * or break a prefix.
+ */
+export declare function stepSignature(tool: string, rawInput: unknown): string | null;
+/**
+ * Detect flows shared as a common prefix across saved specs. Groups specs by
+ * their first step's signature (the entry move), then reports each group's
+ * longest common prefix that ≥ minSpecs specs share and is ≥ minLen steps long.
+ */
+export declare function detectSharedFlows(devRoot: string, opts?: DetectOptions): Promise<SharedFlow[]>;
+//# sourceMappingURL=detectSharedFlows.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"detectSharedFlows.d.ts","sourceRoot":"","sources":["../../src/specs/detectSharedFlows.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,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;AAuDD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,UAAU,EAAE,CAAC,CAiCvB"}

package/dist/specs/detectSharedFlows.js

@@ -0,0 +1,171 @@
+/**
+ * Stage 2 of structured spec output: detect flows repeated across saved specs.
+ *
+ * Reads the `.hover/<slug>.json` sidecars (Stage 1), normalizes each captured
+ * step to a **signature** that keeps structure (tool + target) and drops data
+ * values, then reports the shared *prefix* across specs. This is read-only —
+ * it surfaces "these N specs all start by logging in" to the widget / CLI. It
+ * does NOT generate Page Objects; that is Stage 3 (F4), which consumes this.
+ *
+ * Why prefixes only (not arbitrary common subsequences): D5 — the dominant
+ * real case is many specs sharing an entry flow (login / navigate-to-X), and
+ * prefix detection is near-zero false positives and cheap. Arbitrary fragments
+ * are a later iteration.
+ *
+ * Why signatures (not parsing generated code): the sidecar already holds the
+ * structured `SpecStep[]`. Two sessions that both "click Sign in" produce the
+ * same signature even though their typed values differ — value vs. structure
+ * separation is mechanical (D4).
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { sidecarDir } from './sidecar.js';
+import { humanStep } from './humanSteps.js';
+/**
+ * Reduce one captured step to a signature string: the tool plus its structural
+ * target, with data values stripped. Returns null for steps that aren't part
+ * of a replayable flow (diagnostics, tab switches, waits) so they don't anchor
+ * or break a prefix.
+ */
+export function stepSignature(tool, rawInput) {
+    const i = (rawInput ?? {});
+    switch (tool) {
+        case 'browser_navigate':
+            return `navigate:${stripPath(String(i.url ?? ''))}`;
+        case 'browser_click':
+            return `click:${normElement(i.element)}`;
+        case 'browser_double_click':
+            return `dblclick:${normElement(i.element)}`;
+        case 'browser_hover':
+            return `hover:${normElement(i.element)}`;
+        case 'browser_type':
+            // The typed text is data — only the target field is structure.
+            return `type:${normElement(i.element)}`;
+        case 'browser_select_option':
+            return `select:${normElement(i.element)}`;
+        case 'browser_fill_form': {
+            // Field names are structure; their values are data. Sort so field order
+            // doesn't change the signature.
+            const fields = i.fields ?? [];
+            const names = fields
+                .map(f => normElement(f.name ?? f.element))
+                .filter(Boolean)
+                .sort();
+            return `fill:${names.join(',')}`;
+        }
+        case 'browser_press_key':
+            return `press:${String(i.key ?? '')}`;
+        default:
+            // Diagnostics / browser_tabs / browser_wait_for — not flow structure.
+            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). */
+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;
+        try {
+            const sc = JSON.parse(await readFile(join(dir, entry), 'utf-8'));
+            if (Array.isArray(sc.steps) && typeof sc.slug === 'string')
+                out.push(sc);
+        }
+        catch {
+            // skip malformed sidecar
+        }
+    }
+    return out;
+}
+/** Project a sidecar's steps to (signature, prose) lists, dropping
+ *  non-flow steps. */
+function signatureSeq(sc) {
+    const sigs = [];
+    const prose = [];
+    const steps = [];
+    for (const s of sc.steps) {
+        if (s.kind !== 'step' || !s.tool)
+            continue;
+        const sig = stepSignature(s.tool, s.input);
+        if (sig == null)
+            continue;
+        sigs.push(sig);
+        prose.push(humanStep(s.tool, s.input) ?? s.tool);
+        steps.push(s);
+    }
+    return { slug: sc.slug, sigs, prose, steps };
+}
+function longestCommonPrefixLen(seqs) {
+    if (seqs.length === 0)
+        return 0;
+    const minL = Math.min(...seqs.map(s => s.length));
+    let i = 0;
+    for (; i < minL; i++) {
+        const v = seqs[0][i];
+        if (!seqs.every(s => s[i] === v))
+            break;
+    }
+    return i;
+}
+/**
+ * Detect flows shared as a common prefix across saved specs. Groups specs by
+ * their first step's signature (the entry move), then reports each group's
+ * longest common prefix that ≥ minSpecs specs share and is ≥ minLen steps long.
+ */
+export async function detectSharedFlows(devRoot, opts = {}) {
+    const minSpecs = opts.minSpecs ?? 2;
+    const minLen = opts.minLen ?? 2;
+    const seqs = (await readSidecars(devRoot))
+        .map(signatureSeq)
+        .filter(s => s.sigs.length > 0);
+    // Group by first signature — the dominant case is many specs that all start
+    // with the same entry flow (login / navigate-to-X).
+    const groups = new Map();
+    for (const s of seqs) {
+        const key = s.sigs[0];
+        const arr = groups.get(key);
+        if (arr)
+            arr.push(s);
+        else
+            groups.set(key, [s]);
+    }
+    const flows = [];
+    for (const group of groups.values()) {
+        if (group.length < minSpecs)
+            continue;
+        const lcp = longestCommonPrefixLen(group.map(g => g.sigs));
+        if (lcp < minLen)
+            continue;
+        flows.push({
+            signatures: group[0].sigs.slice(0, lcp),
+            prose: group[0].prose.slice(0, lcp),
+            specs: group.map(g => g.slug).sort(),
+            prefixSteps: group[0].steps.slice(0, lcp),
+        });
+    }
+    // Longest shared prefix first — the richest extraction candidate on top.
+    flows.sort((a, b) => b.signatures.length - a.signatures.length);
+    return flows;
+}
+function normElement(raw) {
+    return String(raw ?? '').trim().replace(/\s+/g, ' ');
+}
+function stripPath(url) {
+    if (!/^https?:\/\//.test(url))
+        return url;
+    try {
+        return new URL(url).pathname || '/';
+    }
+    catch {
+        return url;
+    }
+}

package/dist/specs/extractPageObjects.d.ts

@@ -0,0 +1,18 @@
+export interface ExtractedPage {
+    className: string;
+    methodName: string;
+    fileName: string;
+    /** Absolute path written. */
+    path: string;
+    /** Slugs of the specs that share this flow. */
+    specs: string[];
+}
+export interface ExtractResult {
+    pages: ExtractedPage[];
+    /** Absolute path of the written fixtures.ts, or null when nothing extracted. */
+    fixturesPath: string | null;
+}
+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":"AAoBA,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,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,gFAAgF;IAChF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,aAAa,CAAC,CA4CxB"}

package/dist/specs/extractPageObjects.js

@@ -0,0 +1,98 @@
+/**
+ * Stage 3 (F4): extract Page Objects + a fixtures entry point from flows shared
+ * across saved specs.
+ *
+ * Reads detectSharedFlows (>= 3 specs sharing an entry prefix — the scaffold's
+ * 3-use threshold), generates a `pages/<Name>.ts` per flow, and (re)writes a
+ * single `fixtures.ts` that registers each Page Object via `base.extend`. New
+ * specs `import { test, expect } from './fixtures'` and consume e.g.
+ * `async ({ page, loginPage }) => …`.
+ *
+ * Manual trigger (Stage 3b): invoked by a CLI command, not on every save, and
+ * it never rewrites already-committed specs (D6) — it only emits the shared
+ * pages/ + fixtures.ts going forward.
+ */
+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';
+export async function extractPageObjects(devRoot, opts = {}) {
+    // 3-use threshold for extraction; lower thresholds only *report* (Stage 2).
+    const flows = await detectSharedFlows(devRoot, { minSpecs: opts.minSpecs ?? 3 });
+    if (flows.length === 0)
+        return { pages: [], fixturesPath: null };
+    const testsDir = join(devRoot, '__vibe_tests__');
+    const pagesDir = join(testsDir, 'pages');
+    await mkdir(pagesDir, { recursive: true });
+    const pages = [];
+    const entries = [];
+    const usedNames = 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,
+        });
+    }
+    const fixturesPath = join(testsDir, 'fixtures.ts');
+    await writeFile(fixturesPath, renderFixtures(pages), 'utf-8');
+    // Manifest lets writeSpec match a new spec's prefix to a Page Object and
+    // consume it (Stage 3c) without re-running detection.
+    await writePageObjectManifest(devRoot, entries);
+    return { pages, fixturesPath };
+}
+function renderFixtures(pages) {
+    const lines = [];
+    lines.push(`import { test as base } from '@playwright/test';`);
+    for (const p of pages) {
+        lines.push(`import { ${p.className} } from './pages/${p.className}';`);
+    }
+    lines.push('');
+    lines.push('/**');
+    lines.push(' * Generated by Hover — Page Object fixtures lifted from flows shared');
+    lines.push(" * across specs. In a new spec: `import { test, expect } from './fixtures';`");
+    lines.push(' * then consume e.g. `async ({ page, loginPage }) => …`.');
+    lines.push(' */');
+    const typeMembers = pages.map(p => `${fixtureName(p.className)}: ${p.className}`).join('; ');
+    lines.push(`export const test = base.extend<{ ${typeMembers} }>({`);
+    for (const p of pages) {
+        lines.push(`  ${fixtureName(p.className)}: async ({ page }, use) => {`);
+        lines.push(`    await use(new ${p.className}(page));`);
+        lines.push(`  },`);
+    }
+    lines.push(`});`);
+    lines.push('');
+    lines.push(`export { expect } from '@playwright/test';`);
+    lines.push('');
+    return lines.join('\n');
+}
+/** Class name -> fixture key: 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

@@ -0,0 +1,29 @@
+/**
+ * Stage 3 (F4): generate a Page Object class from a flow shared across specs.
+ *
+ * Given the captured steps of a shared prefix (from detectSharedFlows), emit a
+ * `pages/<Name>.ts` class whose single method replays the flow. Per D4,
+ * structure becomes the method (selectors centralized here) and data values
+ * become method parameters. Naming follows D7: the entry navigation's last path
+ * segment (`/login` -> `LoginPage.login`), falling back to `FlowPage.run`.
+ *
+ * Deterministic, no LLM. Reuses writeSpec's selector + visibility-prelude
+ * 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';
+export interface PageObjectResult {
+    /** PascalCase class name, e.g. `LoginPage`. */
+    className: string;
+    /** camelCase method name, e.g. `login`. */
+    methodName: string;
+    /** File to write under `pages/`, e.g. `LoginPage.ts`. */
+    fileName: string;
+    /** Generated TypeScript source. */
+    source: string;
+}
+export declare function generatePageObject(steps: SkillStep[], override?: {
+    className?: string;
+    methodName?: string;
+}): PageObjectResult;
+//# sourceMappingURL=generatePageObject.d.ts.map

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

@@ -0,0 +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"}