@hover-dev/core 0.14.1 → 0.16.0

package/dist/specs/seeds.d.ts

@@ -0,0 +1,36 @@
+export interface SeedRule {
+    /** Identifier, e.g. `download`. */
+    name: string;
+    /** Rough match signature — tool names (optionally `tool:detail`), used only
+     *  to pick relevant seeds for a spec, NOT for exact matching. */
+    signature: string[];
+    /** One-line human note: what the pattern is / when it applies. */
+    note?: string;
+    /** A concrete worked example the LLM generalizes from. */
+    example: {
+        steps: unknown[];
+        code: string;
+    };
+}
+/**
+ * Built-in seeds ship with core and feed EVERY project's optimization pass, so
+ * the bar is high: a pattern qualifies as built-in ONLY if it's a *highly
+ * certain* optimization — a fixed, app-agnostic translation whose output is
+ * deterministic and can't mislead (e.g. download → waitForEvent pairing).
+ *
+ * Deliberately NOT built-in:
+ *   - Semantic / judgement-based optimizations (e.g. WHICH feedback text to
+ *     assert) — those are already standing instructions in buildOptimizePrompt,
+ *     and a bad generalization would pollute every user's spec.
+ *   - Popup/new-tab — hardcoded in the translator (writeSpec), not a seed.
+ * Project-specific or speculative patterns live in <root>/.hover/rules/, where
+ * the bar is the user's own call.
+ */
+export declare const BUILTIN_SEEDS: SeedRule[];
+/** Built-in seeds + any in <projectRoot>/.hover/rules/*.json. Malformed files
+ *  are skipped rather than failing the whole read. */
+export declare function readSeeds(projectRoot: string): Promise<SeedRule[]>;
+/** Pick seeds whose signature's base tool appears in the spec — a cheap
+ *  relevance filter so the prompt only carries plausibly-applicable examples. */
+export declare function relevantSeeds(seeds: SeedRule[], specTools: Set<string>, cap?: number): SeedRule[];
+//# sourceMappingURL=seeds.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"seeds.d.ts","sourceRoot":"","sources":["../../src/specs/seeds.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,QAAQ;IACvB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb;qEACiE;IACjE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,OAAO,EAAE;QAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,EAenC,CAAC;AAEF;sDACsD;AACtD,wBAAsB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAiBxE;AAED;iFACiF;AACjF,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,GAAG,SAAI,GAAG,QAAQ,EAAE,CAG5F"}

package/dist/specs/seeds.js

@@ -0,0 +1,74 @@
+/**
+ * Community translation seeds (Stage 6, approach A): human-written worked
+ * examples that teach the optimization pass (F7) new patterns by few-shot,
+ * NOT by deterministic match+template. A seed is a rough `signature` (tool
+ * names, used only to pick relevant seeds) + a concrete `example`
+ * (input steps → output code) the LLM generalizes from.
+ *
+ * Sources: a small built-in set + the project's <projectRoot>/.hover/rules/.
+ * Adding a pattern = dropping an example JSON in .hover/rules/ — no core change.
+ *
+ * Built-in seeds deliberately cover patterns the deterministic translator does
+ * NOT hardcode (popup is already hardcoded in writeSpec, so it's not here).
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Built-in seeds ship with core and feed EVERY project's optimization pass, so
+ * the bar is high: a pattern qualifies as built-in ONLY if it's a *highly
+ * certain* optimization — a fixed, app-agnostic translation whose output is
+ * deterministic and can't mislead (e.g. download → waitForEvent pairing).
+ *
+ * Deliberately NOT built-in:
+ *   - Semantic / judgement-based optimizations (e.g. WHICH feedback text to
+ *     assert) — those are already standing instructions in buildOptimizePrompt,
+ *     and a bad generalization would pollute every user's spec.
+ *   - Popup/new-tab — hardcoded in the translator (writeSpec), not a seed.
+ * Project-specific or speculative patterns live in <root>/.hover/rules/, where
+ * the bar is the user's own call.
+ */
+export const BUILTIN_SEEDS = [
+    {
+        name: 'download',
+        signature: ['browser_click'],
+        note: 'a click that triggers a file download → pair with waitForEvent("download")',
+        example: {
+            steps: [{ tool: 'browser_click', element: 'Export CSV button' }],
+            code: "const [download] = await Promise.all([\n" +
+                "  page.waitForEvent('download'),\n" +
+                "  page.getByRole('button', { name: 'Export CSV' }).click(),\n" +
+                "]);\n" +
+                "expect(await download.suggestedFilename()).toContain('.csv');",
+        },
+    },
+];
+/** Built-in seeds + any in <projectRoot>/.hover/rules/*.json. Malformed files
+ *  are skipped rather than failing the whole read. */
+export async function readSeeds(projectRoot) {
+    const out = [...BUILTIN_SEEDS];
+    try {
+        const dir = join(projectRoot, '.hover', 'rules');
+        for (const f of await readdir(dir)) {
+            if (!f.endsWith('.json'))
+                continue;
+            try {
+                const s = JSON.parse(await readFile(join(dir, f), 'utf-8'));
+                if (s && s.name && Array.isArray(s.signature) && s.example?.code)
+                    out.push(s);
+            }
+            catch {
+                /* skip malformed seed file */
+            }
+        }
+    }
+    catch {
+        /* no .hover/rules/ directory */
+    }
+    return out;
+}
+/** Pick seeds whose signature's base tool appears in the spec — a cheap
+ *  relevance filter so the prompt only carries plausibly-applicable examples. */
+export function relevantSeeds(seeds, specTools, cap = 6) {
+    const hits = seeds.filter(s => s.signature.some(sig => specTools.has(sig.split(':')[0])));
+    return hits.slice(0, cap);
+}

package/dist/specs/sidecar.d.ts

@@ -0,0 +1,25 @@
+import type { SkillStep } from '../skills/writeSkill.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 interface SpecSidecar {
+    version: number;
+    slug: string;
+    name: string;
+    /** ISO timestamp the sidecar was written. */
+    createdAt: string;
+    /** The full captured session, structured and verbatim — never re-derived
+     *  from the generated `.spec.ts`. */
+    steps: SkillStep[];
+    /** Alt-click assertions captured alongside the session. */
+    assertions: SpecAssertion[];
+}
+/** Sidecar directory under the spec output dir. Dot-prefixed on purpose:
+ *  Playwright's default `*.spec.ts` glob never reaches into `.hover/`. */
+export declare function sidecarDir(devRoot: string): string;
+/** Write the structured-session sidecar at `.hover/<slug>.json`. Caller passes
+ *  the data minus the stamped fields (`version`, `createdAt`), which this
+ *  function fills. Returns the absolute path written. */
+export declare function writeSidecar(devRoot: string, data: Omit<SpecSidecar, 'version' | 'createdAt'>): Promise<string>;
+//# sourceMappingURL=sidecar.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar.d.ts","sourceRoot":"","sources":["../../src/specs/sidecar.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,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;0EAC0E;AAC1E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;yDAEyD;AACzD,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,WAAW,CAAC,GAC/C,OAAO,CAAC,MAAM,CAAC,CAWjB"}

package/dist/specs/sidecar.js

@@ -0,0 +1,38 @@
+/**
+ * Structured-session sidecar for a generated spec.
+ *
+ * Every saved spec gets a companion `__vibe_tests__/.hover/<slug>.json` holding
+ * the original structured `SpecStep[]` (plus assertions + metadata). The
+ * `.spec.ts` is the human / CI artifact; this sidecar is the machine record
+ * that downstream work reads instead of parsing generated code:
+ *   - F4 cross-session extraction signature-matches `steps` across sidecars.
+ *   - F7 optimization pass feeds the draft + this sidecar to the LLM.
+ *
+ * It lands in a dot-prefixed `.hover/` dir so Playwright's default `*.spec.ts`
+ * glob never collects it, and it is pure data — no Hover runtime import.
+ */
+import { mkdir, writeFile } 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;
+/** Sidecar directory under the spec output dir. Dot-prefixed on purpose:
+ *  Playwright's default `*.spec.ts` glob never reaches into `.hover/`. */
+export function sidecarDir(devRoot) {
+    return join(devRoot, '__vibe_tests__', '.hover');
+}
+/** Write the structured-session sidecar at `.hover/<slug>.json`. Caller passes
+ *  the data minus the stamped fields (`version`, `createdAt`), which this
+ *  function fills. Returns the absolute path written. */
+export async function writeSidecar(devRoot, data) {
+    const dir = sidecarDir(devRoot);
+    await mkdir(dir, { recursive: true });
+    const path = join(dir, `${data.slug}.json`);
+    const sidecar = {
+        version: SIDECAR_VERSION,
+        createdAt: new Date().toISOString(),
+        ...data,
+    };
+    await writeFile(path, JSON.stringify(sidecar, null, 2) + '\n', 'utf-8');
+    return path;
+}

package/dist/specs/softBatch.d.ts

@@ -0,0 +1,14 @@
+/** A trailing run with fewer than this many assertions is left alone —
+ *  `expect.soft` only earns its keep when ≥2 failures could be collected. */
+export declare const MIN_RUN = 2;
+export interface SoftBatchResult {
+    /** The (possibly) rewritten source. */
+    code: string;
+    /** Whether anything changed. */
+    changed: boolean;
+    /** How many assertions were softened across all tests. */
+    softened: number;
+}
+/** Run the soft-batch step over a spec's source text. Pure: text in, text out. */
+export declare function softBatch(source: string): SoftBatchResult;
+//# sourceMappingURL=softBatch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"softBatch.d.ts","sourceRoot":"","sources":["../../src/specs/softBatch.ts"],"names":[],"mappings":"AAgCA;6EAC6E;AAC7E,eAAO,MAAM,OAAO,IAAI,CAAC;AAEzB,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,kFAAkF;AAClF,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAuBzD"}

package/dist/specs/softBatch.js

@@ -0,0 +1,177 @@
+/**
+ * soft-batch — a deterministic finishing step of the optimization pass.
+ *
+ * After the LLM optimize pass decides WHAT to assert (it reads the observed
+ * feedback and adds the trailing "Then" assertions), this step applies the safe
+ * mechanical rewrite: the maximal *trailing run* of independent assertions in
+ * each `test()` body goes from `expect(...)` to `expect.soft(...)`, so a
+ * field-audit spec reports every failing field in one run instead of halting on
+ * the first. This is the "LLM decides, AST executes" split — the LLM never
+ * reprints the file to do it, so it can't drift; ts-morph applies the soften
+ * surgically and every untouched node stays byte-identical.
+ *
+ * Two assertion shapes are recognised, because that is what specs look like
+ * after optimize:
+ *   A. a bare `await expect(...)....` statement;
+ *   B. a Hover `await test.step('Then · …', async () => { await expect(...) })`
+ *      closure whose body is nothing but assertions — Hover emits one such step
+ *      per observed-feedback assertion, AFTER all the action steps.
+ *
+ * Safety guard (why this is deterministic and never changes test semantics):
+ * we only ever soften an assertion that sits in the trailing run — the suffix
+ * of the test body that is assertions all the way down, with no action after
+ * it. A *gating* assertion — one a later action depends on — is by construction
+ * followed by that action, so it never lands in the trailing run and is never
+ * softened. Softening only changes how failures are *reported* (all collected
+ * vs. stop-on-first), never whether the test passes. We require ≥2 assertions
+ * in the run: soft buys nothing for a single one. `expect.soft` collects across
+ * the whole test regardless of `test.step` nesting, so softening step-wrapped
+ * assertions is sound.
+ */
+import { Project, SyntaxKind, Node } from 'ts-morph';
+/** A trailing run with fewer than this many assertions is left alone —
+ *  `expect.soft` only earns its keep when ≥2 failures could be collected. */
+export const MIN_RUN = 2;
+/** Run the soft-batch step over a spec's source text. Pure: text in, text out. */
+export function softBatch(source) {
+    const project = new Project({
+        useInMemoryFileSystem: true,
+        compilerOptions: { allowJs: true },
+    });
+    const sf = project.createSourceFile('__spec.ts', source, { overwrite: true });
+    // Collect every assertion to soften first (across all test bodies), then
+    // apply — each edit is a localized identifier replace, so sibling targets
+    // stay valid.
+    const targets = [];
+    for (const body of testBodies(sf)) {
+        const run = trailingAssertionRun(body.getStatements());
+        const asserts = run.flatMap(bareAssertionsIn);
+        if (asserts.length >= MIN_RUN)
+            targets.push(...asserts);
+    }
+    let softened = 0;
+    for (const stmt of targets) {
+        if (soften(stmt))
+            softened++;
+    }
+    return { code: sf.getFullText(), changed: softened > 0, softened };
+}
+/**
+ * Yield the block body of every `test(...)` call (including `test.only` /
+ * `.skip` / `.fixme`), but NOT `test.describe` / hooks — those wrap tests, they
+ * aren't a test body.
+ */
+function testBodies(sf) {
+    const bodies = [];
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        if (!isTestCall(call.getExpression()))
+            continue;
+        const cb = call.getArguments().at(-1);
+        if (!cb)
+            continue;
+        if (Node.isArrowFunction(cb) || Node.isFunctionExpression(cb)) {
+            const block = cb.getBody();
+            if (Node.isBlock(block))
+                bodies.push(block);
+        }
+    }
+    return bodies;
+}
+/** `test` | `test.only` | `test.skip` | `test.fixme` — not `test.describe` or hooks. */
+function isTestCall(callee) {
+    if (Node.isIdentifier(callee))
+        return callee.getText() === 'test';
+    if (Node.isPropertyAccessExpression(callee)) {
+        const base = callee.getExpression();
+        if (!Node.isIdentifier(base) || base.getText() !== 'test')
+            return false;
+        return ['only', 'skip', 'fixme'].includes(callee.getName());
+    }
+    return false;
+}
+/** The longest suffix of `statements` that are all assertion units (a bare
+ *  assertion, or a `test.step` whose body is only assertions). */
+function trailingAssertionRun(statements) {
+    const run = [];
+    for (let i = statements.length - 1; i >= 0; i--) {
+        if (!isAssertionUnit(statements[i]))
+            break;
+        run.unshift(statements[i]);
+    }
+    return run;
+}
+/** A statement that contributes only assertions: a bare assertion (case A) or
+ *  an assertion-only `test.step` closure (case B). */
+function isAssertionUnit(stmt) {
+    return isBareAssertion(stmt) || bareAssertionsInStep(stmt) !== null;
+}
+/** The bare-assertion statements a unit contains: itself (case A) or the
+ *  assertions inside its `test.step` closure (case B). */
+function bareAssertionsIn(stmt) {
+    if (isBareAssertion(stmt))
+        return [stmt];
+    return bareAssertionsInStep(stmt) ?? [];
+}
+/** True if the statement is `(await) expect(...)....` — its call chain bottoms
+ *  out at an `expect` identifier. */
+function isBareAssertion(stmt) {
+    if (!Node.isExpressionStatement(stmt))
+        return false;
+    let expr = stmt.getExpression();
+    if (Node.isAwaitExpression(expr))
+        expr = expr.getExpression();
+    return leftmostBase(expr) === 'expect';
+}
+/**
+ * If `stmt` is `await test.step(label, async () => { …only assertions… })`,
+ * return those inner assertion statements; otherwise null. The closure body
+ * must be non-empty and contain ONLY bare assertions — a step that also acts
+ * (a "When" with a check) is not a pure assertion unit and is left alone.
+ */
+function bareAssertionsInStep(stmt) {
+    if (!Node.isExpressionStatement(stmt))
+        return null;
+    let expr = stmt.getExpression();
+    if (Node.isAwaitExpression(expr))
+        expr = expr.getExpression();
+    if (!Node.isCallExpression(expr))
+        return null;
+    const callee = expr.getExpression();
+    if (!Node.isPropertyAccessExpression(callee) ||
+        callee.getName() !== 'step' ||
+        callee.getExpression().getText() !== 'test') {
+        return null;
+    }
+    const cb = expr.getArguments().at(-1);
+    if (!cb || !(Node.isArrowFunction(cb) || Node.isFunctionExpression(cb)))
+        return null;
+    const block = cb.getBody();
+    if (!Node.isBlock(block))
+        return null;
+    const inner = block.getStatements();
+    if (inner.length === 0 || !inner.every(isBareAssertion))
+        return null;
+    return inner;
+}
+/** Descend a call/member chain to its leftmost identifier, e.g.
+ *  `expect(x).toHaveText(y)` → "expect", `page.goto('/')` → "page". */
+function leftmostBase(node) {
+    let cur = node;
+    while (cur && (Node.isCallExpression(cur) || Node.isPropertyAccessExpression(cur))) {
+        cur = cur.getExpression();
+    }
+    return cur && Node.isIdentifier(cur) ? cur.getText() : null;
+}
+/** Rewrite the `expect(` call inside a bare assertion statement to
+ *  `expect.soft(`. Skips ones already soft (their callee is `expect.soft`, not
+ *  the bare identifier `expect`). Returns whether a change was made. */
+function soften(stmt) {
+    for (const call of stmt.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        const callee = call.getExpression();
+        if (Node.isIdentifier(callee) && callee.getText() === 'expect') {
+            callee.replaceWithText('expect.soft');
+            return true;
+        }
+    }
+    return false;
+}

package/dist/specs/text.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Small text helpers shared across the spec/CSV emitters.
+ *
+ * Hoisted here so the two crystallization outputs (writeSpec's JSDoc header and
+ * writeCaseCsv's Xray rows) derive a slug and a one-sentence "Expected" line the
+ * same way — they used to carry byte-identical copies of this logic.
+ */
+/** Lowercase, hyphenate, and trim a display name into a filesystem-safe slug. */
+export declare function slugify(name: string): string;
+/**
+ * The first sentence of a done-summary, trimmed. Agents sometimes ramble; the
+ * Expected blocks only want the leading sentence. Splits on the gap that
+ * follows sentence-ending punctuation (`.`, `!`, `?`); a summary with no such
+ * punctuation comes back trimmed in full.
+ */
+export declare function firstSentence(summary: string): string;
+//# sourceMappingURL=text.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/specs/text.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM5C;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/specs/text.js

@@ -0,0 +1,24 @@
+/**
+ * Small text helpers shared across the spec/CSV emitters.
+ *
+ * Hoisted here so the two crystallization outputs (writeSpec's JSDoc header and
+ * writeCaseCsv's Xray rows) derive a slug and a one-sentence "Expected" line the
+ * same way — they used to carry byte-identical copies of this logic.
+ */
+/** Lowercase, hyphenate, and trim a display name into a filesystem-safe slug. */
+export function slugify(name) {
+    return name
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * The first sentence of a done-summary, trimmed. Agents sometimes ramble; the
+ * Expected blocks only want the leading sentence. Splits on the gap that
+ * follows sentence-ending punctuation (`.`, `!`, `?`); a summary with no such
+ * punctuation comes back trimmed in full.
+ */
+export function firstSentence(summary) {
+    return summary.split(/(?<=[.!?])\s+/)[0]?.trim() ?? summary.trim();
+}

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

@@ -1 +1 @@
-{"version":3,"file":"writeCaseCsv.d.ts","sourceRoot":"","sources":["../../src/specs/writeCaseCsv.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,qBAAa,kBAAmB,SAAQ,KAAK;aACf,IAAI,EAAE,MAAM;aAAkB,IAAI,EAAE,MAAM;gBAA1C,IAAI,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAIvE;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B;;uEAEmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;+CAC2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;CAAE;AAEnE,wBAAsB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAiBzF"}
+{"version":3,"file":"writeCaseCsv.d.ts","sourceRoot":"","sources":["../../src/specs/writeCaseCsv.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD,qBAAa,kBAAmB,SAAQ,KAAK;aACf,IAAI,EAAE,MAAM;aAAkB,IAAI,EAAE,MAAM;gBAA1C,IAAI,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAIvE;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B;;uEAEmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;+CAC2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;CAAE;AAEnE,wBAAsB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAiBzF"}

package/dist/specs/writeCaseCsv.js

@@ -31,6 +31,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { humanSteps } from './humanSteps.js';
+import { slugify, firstSentence } from './text.js';
 export class CaseCsvExistsError extends Error {
     slug;
     path;
@@ -59,13 +60,6 @@ export async function writeCaseCsv(opts) {
     return { path, slug };
 }
 // ───────── helpers ─────────
-function slugify(name) {
-    return name
-        .toLowerCase()
-        .trim()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
-}
 function renderCsv(slug, opts) {
     const rows = buildRows(slug, opts);
     // CRLF row terminator — what Excel / Numbers / Xray's importer all
@@ -112,7 +106,7 @@ function expectedFor(assertions, steps) {
     }
     const done = [...steps].reverse().find(s => s.kind === 'done');
     if (done?.summary) {
-        return done.summary.split(/(?<=[.!?])\s+/)[0]?.trim() ?? done.summary.trim();
+        return firstSentence(done.summary);
     }
     return '';
 }

package/dist/specs/writeSpec.d.ts

@@ -1,5 +1,18 @@
 import type { SkillStep } from '../skills/writeSkill.js';
 export type SpecStep = SkillStep;
+/**
+ * Marker the deterministic translator leaves where a captured action is a real
+ * interaction but has no single-step Playwright translation (e.g. file upload,
+ * drag, a dialog handler) — a shape that needs a multi-step pattern. It is a
+ * structured signal, not a `// TODO`: the optimization pass (F7) and the
+ * "seeds could complete this — review?" suggestion grep for it, and
+ * `countOptimizableMarkers` reads it back off a saved spec.
+ */
+export declare const OPTIMIZABLE_MARKER = "// hover:optimizable";
+/** How many `// hover:optimizable` markers a generated spec carries. Used to
+ *  surface "this spec has an interaction the deterministic pass couldn't fully
+ *  translate — the optimization pass can complete it". */
+export declare function countOptimizableMarkers(source: string): number;
 export interface SpecAssertion {
     /** Generated Playwright code (single line, no leading "await "). */
     code: string;
@@ -24,4 +37,41 @@ export interface WriteSpecResult {
     slug: string;
 }
 export declare function writeSpec(opts: WriteSpecOptions): Promise<WriteSpecResult>;
+/**
+ * Emit an interaction (click / dblclick / hover / fill / selectOption) as a
+ * visibility-guarded prelude: hoist the locator to `el`, assert it's visible,
+ * then act.
+ *
+ *    const el = page.getByRole('button', { name: 'Submit' });
+ *    await expect(el).toBeVisible();
+ *    await el.click();
+ *
+ * Why: `getByRole` is "visible OR attached" by default. A button that drifted
+ * behind a closed `<details>` / kebab menu / drawer is still in the role tree,
+ * so the locator stays green AND `.click()` may still fire — but the actual
+ * user flow has degraded. Asserting visibility first makes that drift fail
+ * loudly with "Locator expected to be visible" instead of silently passing.
+ *
+ * Scoping: renderSpec wraps each step in its own `test.step(… async () => {})`,
+ * whose closure already scopes `el`, so a single interaction needs no extra
+ * braces. browser_fill_form emits several fields into one step, so it wraps
+ * each field in `blockScope(...)` to keep the per-field `el` from colliding.
+ */
+export declare function emitInteraction(selectorExpr: string, action: string): string[];
+/** Wrap lines in a `{ … }` block scope (2-space inner indent). Used by
+ *  browser_fill_form so each field's `const el` lives in its own scope inside
+ *  the shared test.step closure. */
+export declare function blockScope(lines: string[]): string[];
+/**
+ * Parse element descriptions like "Submit button" / "+1 button" / "Email
+ * textbox" / "Plan radio" into `getByRole(role, { name })` selectors. The
+ * trailing role keyword is the convention Playwright MCP uses.
+ */
+export declare function selectorFromDescription(desc: string, pageVar?: string): string;
+/**
+ * Form fields from browser_fill_form have a `name` that's typically the
+ * accessible name / label / aria-label. getByLabel is the right primitive.
+ * Fall back to getByRole('textbox') if we have a hint.
+ */
+export declare function selectorForFormField(name: string, type?: string, pageVar?: string): string;
 //# sourceMappingURL=writeSpec.d.ts.map

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,yBAAyB,CAAC;AAGzD,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC;AAEjC,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,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;CACrB;AAED,MAAM,WAAW,eAAe;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;CAAE;AAEhE,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAkBhF"}
+{"version":3,"file":"writeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/writeSpec.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAWzD,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;AAED,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,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;CACrB;AAED,MAAM,WAAW,eAAe;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;CAAE;AAEhE,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAiChF;AAuUD;;;;;;;;;;;;;;;;;;;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;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAQ1F"}