@hover-dev/core 0.14.1 → 0.15.0

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"}

package/dist/specs/generatePageObject.js

@@ -0,0 +1,149 @@
+import { selectorFromDescription, selectorForFormField, emitInteraction, blockScope, } from './writeSpec.js';
+const PAGE_VAR = 'this.page';
+export function generatePageObject(steps, override = {}) {
+    const derived = deriveNames(steps);
+    const className = override.className ?? derived.className;
+    const methodName = override.methodName ?? derived.methodName;
+    const params = [];
+    const used = new Set();
+    const body = [];
+    for (const s of steps) {
+        if (s.kind !== 'step' || !s.tool)
+            continue;
+        const i = (s.input ?? {});
+        switch (s.tool) {
+            case 'browser_navigate':
+                body.push(`await ${PAGE_VAR}.goto(${JSON.stringify(navPath(String(i.url ?? '')))});`);
+                break;
+            case 'browser_click':
+                body.push(...blockScope(emitInteraction(selectorFromDescription(String(i.element ?? ''), PAGE_VAR), 'click()')));
+                break;
+            case 'browser_double_click':
+                body.push(...blockScope(emitInteraction(selectorFromDescription(String(i.element ?? ''), PAGE_VAR), 'dblclick()')));
+                break;
+            case 'browser_hover':
+                body.push(...blockScope(emitInteraction(selectorFromDescription(String(i.element ?? ''), PAGE_VAR), 'hover()')));
+                break;
+            case 'browser_type': {
+                const p = uniqueParam(paramName(String(i.element ?? '')), used);
+                params.push(p);
+                body.push(...blockScope(emitInteraction(selectorFromDescription(String(i.element ?? ''), PAGE_VAR), `fill(${p})`)));
+                break;
+            }
+            case 'browser_select_option': {
+                const p = uniqueParam(paramName(String(i.element ?? '')), used);
+                params.push(p);
+                body.push(...blockScope(emitInteraction(selectorFromDescription(String(i.element ?? ''), PAGE_VAR), `selectOption(${p})`)));
+                break;
+            }
+            case 'browser_fill_form': {
+                const fields = i.fields ?? [];
+                for (const f of fields) {
+                    const target = String(f.name ?? f.element ?? '');
+                    const p = uniqueParam(paramName(target), used);
+                    params.push(p);
+                    body.push(...blockScope(emitInteraction(selectorForFormField(target, f.type, PAGE_VAR), `fill(${p})`)));
+                }
+                break;
+            }
+            case 'browser_press_key':
+                body.push(`await ${PAGE_VAR}.keyboard.press(${JSON.stringify(String(i.key ?? ''))});`);
+                break;
+            default:
+                break; // diagnostics / non-replayable — skipped
+        }
+    }
+    const paramList = params.map(p => `${p}: string`).join(', ');
+    return {
+        className,
+        methodName,
+        fileName: `${className}.ts`,
+        source: renderClass(className, methodName, paramList, body),
+    };
+}
+function renderClass(className, methodName, paramList, body) {
+    const out = body.length > 0 ? body : ['// (no replayable steps)'];
+    const lines = [];
+    lines.push(`import { expect, type Page } from '@playwright/test';`);
+    lines.push('');
+    lines.push('/**');
+    lines.push(' * Generated by Hover from a flow shared across saved specs.');
+    lines.push(' * Selectors live here so a UI change is a one-file edit; data values are');
+    lines.push(' * method parameters. Plain Playwright — no Hover runtime.');
+    lines.push(' */');
+    lines.push(`export class ${className} {`);
+    lines.push(`  constructor(private readonly page: Page) {}`);
+    lines.push('');
+    lines.push(`  async ${methodName}(${paramList}): Promise<void> {`);
+    for (const b of out)
+        lines.push(`    ${b}`);
+    lines.push(`  }`);
+    lines.push(`}`);
+    lines.push('');
+    return lines.join('\n');
+}
+function deriveNames(steps) {
+    for (const s of steps) {
+        if (s.kind === 'step' && s.tool === 'browser_navigate') {
+            const seg = lastSegment(String((s.input ?? {}).url ?? ''));
+            if (seg)
+                return { className: pascal(seg) + 'Page', methodName: camel(seg) };
+        }
+    }
+    return { className: 'FlowPage', methodName: 'run' };
+}
+function lastSegment(url) {
+    let path = url;
+    try {
+        if (/^https?:\/\//.test(url))
+            path = new URL(url).pathname;
+    }
+    catch {
+        /* keep raw */
+    }
+    const segs = path.split('/').filter(Boolean);
+    return segs.length ? segs[segs.length - 1].replace(/[^a-zA-Z0-9]+/g, ' ').trim() : '';
+}
+/** Tokenize a label into words, dropping a trailing MCP role keyword. */
+function words(raw) {
+    return raw
+        .replace(/\s+(button|link|textbox|checkbox|radio|combobox|switch|field|input)$/i, '')
+        .replace(/[^a-zA-Z0-9]+/g, ' ')
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean);
+}
+function camel(raw) {
+    const w = words(raw);
+    if (w.length === 0)
+        return 'value';
+    const c = w[0].toLowerCase() +
+        w.slice(1).map(x => x[0].toUpperCase() + x.slice(1).toLowerCase()).join('');
+    return /^[a-zA-Z_]/.test(c) ? c : `v${c}`;
+}
+function pascal(raw) {
+    const c = camel(raw);
+    return c.charAt(0).toUpperCase() + c.slice(1);
+}
+/** Parameter name derived from a field/element label. */
+const paramName = camel;
+function uniqueParam(base, used) {
+    const root = base || 'value';
+    let name = root;
+    let n = 2;
+    while (used.has(name))
+        name = `${root}${n++}`;
+    used.add(name);
+    return name;
+}
+function navPath(url) {
+    if (!/^https?:\/\//.test(url))
+        return url;
+    try {
+        const u = new URL(url);
+        return u.pathname + u.search + u.hash || '/';
+    }
+    catch {
+        return url;
+    }
+}

package/dist/specs/listSpecs.d.ts

@@ -1,3 +1,4 @@
+import { type OptimizationSuggestion } from './optimizationSuggestion.js';
 export interface SpecSummary {
     /** Path-relative slug, e.g. `login-and-counter`. Identifies the spec. */
     slug: string;
@@ -13,6 +14,17 @@ export interface SpecSummary {
     stepCount: number;
     /** File mtime in ms — used to show "saved 2 hours ago" in the UI. */
     mtimeMs: number;
+    /** Whether a structured `.hover/<slug>.json` sidecar exists. The widget
+     *  gates the optimization pass on this — without a captured session there's
+     *  no observed feedback for the LLM to add assertions from. */
+    hasSidecar: boolean;
+    /** Count of `// hover:optimizable` markers the deterministic translator left
+     *  — interactions it couldn't fully translate single-step. >0 is a strong
+     *  signal to run the optimization pass (or add a seed). */
+    optimizableCount: number;
+    /** The default-off "review optimization?" nudge (F7/D10): suggested + reasons,
+     *  derived from optimizable markers + relevant seeds. */
+    optimization: OptimizationSuggestion;
 }
 export interface SpecHeader {
     /** Raw text of `Original prompt:` line, or null when absent. */

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

@@ -1 +1 @@
-{"version":3,"file":"listSpecs.d.ts","sourceRoot":"","sources":["../../src/specs/listSpecs.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb;;qCAEiC;IACjC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,kEAAkE;IAClE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,gCAAgC;IAChC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,oDAAoD;IACpD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAsB1D;AA4BD;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAkCvE"}
+{"version":3,"file":"listSpecs.d.ts","sourceRoot":"","sources":["../../src/specs/listSpecs.ts"],"names":[],"mappings":"AAoBA,OAAO,EAA0B,KAAK,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAGlG,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb;;qCAEiC;IACjC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,kEAAkE;IAClE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB;;mEAE+D;IAC/D,UAAU,EAAE,OAAO,CAAC;IACpB;;+DAE2D;IAC3D,gBAAgB,EAAE,MAAM,CAAC;IACzB;6DACyD;IACzD,YAAY,EAAE,sBAAsB,CAAC;CACtC;AAED,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,gCAAgC;IAChC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,oDAAoD;IACpD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAsB1D;AA4BD;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CA2DvE"}

package/dist/specs/listSpecs.js

@@ -10,11 +10,15 @@
  * `originalPrompt: null` — the UI / CLI surfaces that "this spec can't be
  * re-recorded automatically; the natural-language intent isn't recorded."
  *
- * Mirrors the listSkills shape so widget UI can use the same row renderer.
+ * Shares the SpecSummary row shape the widget's Specs tab renders.
  */
 import { readdir, readFile } from 'node:fs/promises';
 import { stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { countOptimizableMarkers } from './writeSpec.js';
+import { readSeeds, relevantSeeds } from './seeds.js';
+import { optimizationSuggestion } from './optimizationSuggestion.js';
 /**
  * Parse the JSDoc header that `writeSpec.ts` emits. Tolerant of:
  *   - Specs without any JSDoc (returns all-null).
@@ -84,6 +88,8 @@ export async function listSpecs(devRoot) {
     catch {
         return [];
     }
+    // Seeds are devRoot-wide; read once and reuse for every spec's suggestion.
+    const seeds = await readSeeds(devRoot);
     const summaries = [];
     for (const entry of entries) {
         if (!entry.endsWith('.spec.ts'))
@@ -100,13 +106,32 @@ export async function listSpecs(devRoot) {
             continue;
         }
         const header = parseSpecHeader(content);
+        const slug = entry.replace(/\.spec\.ts$/, '');
+        const sidecarPath = join(root, '.hover', `${slug}.json`);
+        const hasSidecar = existsSync(sidecarPath);
+        const optimizableCount = countOptimizableMarkers(content);
+        // Which seeds could plausibly apply, from the sidecar's captured tools.
+        let relevantSeedNames = [];
+        if (hasSidecar && seeds.length > 0) {
+            try {
+                const sc = JSON.parse(await readFile(sidecarPath, 'utf-8'));
+                const tools = new Set((sc.steps ?? []).filter(s => s.kind === 'step' && s.tool).map(s => s.tool));
+                relevantSeedNames = relevantSeeds(seeds, tools).map(s => s.name);
+            }
+            catch {
+                /* malformed sidecar — treat as no relevant seeds */
+            }
+        }
         summaries.push({
-            slug: entry.replace(/\.spec\.ts$/, ''),
+            slug,
             path,
             originalPrompt: header.originalPrompt,
             outcome: header.outcome,
             stepCount: header.steps.length,
             mtimeMs,
+            hasSidecar,
+            optimizableCount,
+            optimization: optimizationSuggestion({ hasSidecar, optimizableCount, relevantSeedNames }),
         });
     }
     summaries.sort((a, b) => b.mtimeMs - a.mtimeMs);

package/dist/specs/optimizationSuggestion.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The default-off "should we nudge the user to optimize this spec?" signal
+ * (F7 / D10). Optimization never runs automatically; instead, when a saved spec
+ * has a clear improvable shape, the widget surfaces a "review optimization?"
+ * prompt. This computes that decision + human-readable reasons.
+ *
+ * Pure function so it's trivially testable; `listSpecs` gathers the inputs
+ * (optimizable-marker count, sidecar presence, relevant seed names) and attaches
+ * the result to each SpecSummary.
+ */
+export interface OptimizationSuggestion {
+    /** Whether to nudge the user to run the optimization pass on this spec. */
+    suggested: boolean;
+    /** Human-readable reasons, for the widget tooltip / prompt. Empty when not
+     *  suggested. */
+    reasons: string[];
+}
+export declare function optimizationSuggestion(args: {
+    /** Whether a `.hover/<slug>.json` sidecar exists. */
+    hasSidecar: boolean;
+    /** Count of `// hover:optimizable` markers in the spec. */
+    optimizableCount: number;
+    /** Names of seeds whose signature is relevant to this spec's tools. */
+    relevantSeedNames: string[];
+}): OptimizationSuggestion;
+//# sourceMappingURL=optimizationSuggestion.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"optimizationSuggestion.d.ts","sourceRoot":"","sources":["../../src/specs/optimizationSuggestion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,sBAAsB;IACrC,2EAA2E;IAC3E,SAAS,EAAE,OAAO,CAAC;IACnB;qBACiB;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,qDAAqD;IACrD,UAAU,EAAE,OAAO,CAAC;IACpB,2DAA2D;IAC3D,gBAAgB,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B,GAAG,sBAAsB,CAqBzB"}

package/dist/specs/optimizationSuggestion.js

@@ -0,0 +1,28 @@
+/**
+ * The default-off "should we nudge the user to optimize this spec?" signal
+ * (F7 / D10). Optimization never runs automatically; instead, when a saved spec
+ * has a clear improvable shape, the widget surfaces a "review optimization?"
+ * prompt. This computes that decision + human-readable reasons.
+ *
+ * Pure function so it's trivially testable; `listSpecs` gathers the inputs
+ * (optimizable-marker count, sidecar presence, relevant seed names) and attaches
+ * the result to each SpecSummary.
+ */
+export function optimizationSuggestion(args) {
+    const { hasSidecar, optimizableCount, relevantSeedNames } = args;
+    const reasons = [];
+    // The optimization pass reads the sidecar (observed feedback, captured steps);
+    // without one there's nothing to optimize from. Matches the widget's Optimize
+    // gate, so we never suggest what can't be acted on.
+    if (!hasSidecar)
+        return { suggested: false, reasons };
+    if (optimizableCount > 0) {
+        const n = optimizableCount;
+        reasons.push(`${n} interaction${n === 1 ? '' : 's'} couldn't be fully translated — the optimization pass can complete ${n === 1 ? 'it' : 'them'}`);
+    }
+    if (relevantSeedNames.length > 0) {
+        const k = relevantSeedNames.length;
+        reasons.push(`${k} seed${k === 1 ? '' : 's'} may apply: ${relevantSeedNames.join(', ')}`);
+    }
+    return { suggested: reasons.length > 0, reasons };
+}