@hover-dev/core 0.16.0 → 0.18.0

package/dist/specs/seeds.js

@@ -1,71 +1,103 @@
 /**
- * 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.
+ * Translation seeds: human-written worked examples that teach the optimization
+ * pass (F7) a multi-step Playwright pattern 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).
+ * These ship inlined as the `BUILTIN_SEEDS` constant below. They used to be
+ * JSON files under `packages/core/seeds/optimization/` plus a `.hover/rules/`
+ * "author your own seed" mechanism and a `.hover/seeds.json` opt-out — all
+ * removed: that user-facing surface added burden for a small curated catalogue
+ * that feeds an optional, manually-invoked pass. To add a pattern, append a
+ * `SeedRule` 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.
+ * Built-in optimization seeds, inlined. They feed EVERY project's optimization
+ * pass (the prompt builder and the relevance filter consume this directly).
  */
 export const BUILTIN_SEEDS = [
     {
         name: 'download',
         signature: ['browser_click'],
-        note: 'a click that triggers a file download → pair with waitForEvent("download")',
+        note: 'A click that triggers a file download — pair it with waitForEvent(\'download\') so the listener is registered before the click fires.',
         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');",
+            code: `const [download] = await Promise.all([
+  page.waitForEvent('download'),
+  page.getByRole('button', { name: 'Export CSV' }).click(),
+]);
+expect(await download.suggestedFilename()).toContain('.csv');`,
+        },
+    },
+    {
+        name: 'file-upload',
+        signature: ['browser_file_upload'],
+        note: 'Set a file on a (often hidden) <input type=file>. The file chooser opens synchronously on click, so register waitForEvent(\'filechooser\') before the click — same race as download.',
+        example: {
+            steps: [
+                { tool: 'browser_click', element: 'Upload avatar button' },
+                { tool: 'browser_file_upload', paths: ['avatar.png'] },
+            ],
+            code: `const [chooser] = await Promise.all([
+  page.waitForEvent('filechooser'),
+  page.getByRole('button', { name: 'Upload avatar' }).click(),
+]);
+await chooser.setFiles('tests/fixtures/avatar.png');
+await expect(page.getByText('avatar.png')).toBeVisible();`,
+        },
+    },
+    {
+        name: 'dialog',
+        signature: ['browser_handle_dialog'],
+        note: 'A click that triggers a native dialog (alert/confirm/prompt). Register the page \'dialog\' handler BEFORE the click that fires it — otherwise Playwright auto-dismisses it and the assertion is wrong.',
+        example: {
+            steps: [
+                { tool: 'browser_click', element: 'Delete account button' },
+                { tool: 'browser_handle_dialog', action: 'accept' },
+            ],
+            code: `page.once('dialog', dialog => dialog.accept());
+await page.getByRole('button', { name: 'Delete account' }).click();
+await expect(page.getByText('Account deleted')).toBeVisible();`,
+        },
+    },
+    {
+        name: 'oauth-popup',
+        signature: ['browser_click', 'browser_tabs:select'],
+        note: 'Sign in through a provider popup that opens a new tab. Pair the opener click with context.waitForEvent(\'page\'), then drive the returned popup page.',
+        example: {
+            steps: [
+                { tool: 'browser_click', element: 'Sign in with Google button' },
+                { tool: 'browser_tabs', action: 'select', idx: 1 },
+            ],
+            code: `const [popup] = await Promise.all([
+  context.waitForEvent('page'),
+  page.getByRole('button', { name: 'Sign in with Google' }).click(),
+]);
+await popup.getByLabel('Email').fill('user@example.com');
+await popup.getByRole('button', { name: 'Next' }).click();
+await popup.waitForEvent('close');
+await expect(page.getByText('Signed in')).toBeVisible();`,
+        },
+    },
+    {
+        name: 'network-gated-assertion',
+        signature: ['browser_click', 'browser_wait_for'],
+        note: 'A click fires an XHR/fetch and the result is asserted. Pair the click with page.waitForResponse so the test waits for the real request to settle, instead of a guessed timeout or a race.',
+        example: {
+            steps: [
+                { tool: 'browser_click', element: 'Place order button' },
+                { tool: 'browser_wait_for', text: 'Order confirmed' },
+            ],
+            code: `const [res] = await Promise.all([
+  page.waitForResponse(r => r.url().includes('/api/orders') && r.request().method() === 'POST'),
+  page.getByRole('button', { name: 'Place order' }).click(),
+]);
+expect(res.ok()).toBeTruthy();
+await expect(page.getByText('Order confirmed')).toBeVisible();`,
         },
     },
 ];
-/** 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) {

package/dist/specs/sidecar.d.ts

@@ -1,4 +1,4 @@
-import type { SkillStep } from '../skills/writeSkill.js';
+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. */
@@ -15,11 +15,39 @@ export interface SpecSidecar {
     /** 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/`. */
+/** Project-root `.hover/` directory — the single home for Hover-derived data
+ *  (sidecars, runs, rules, conventions). */
+export declare function hoverDir(devRoot: string): string;
+/** Sanitize an id segment for use as a directory name (conversation / run id). */
+export declare function safeSeg(s: string): string;
+/** Per-run home: `<devRoot>/.hover/conversations/<conversationId>/<runId>/`.
+ *  Everything a single agent run produces — meta.json (the ledger record),
+ *  report.md (QA), screenshots/ — lives here, grouped under its conversation so
+ *  deleting a conversation is one `rm -rf .hover/conversations/<conversationId>`.
+ *  (Distinct from `.hover/runs/`, which is the Playwright spec-run-results
+ *  ledger written by ▶ Run.) */
+export declare function conversationsDir(devRoot: string): string;
+export declare function conversationDir(devRoot: string, conversationId: string): string;
+export declare function runDir(devRoot: string, conversationId: string, runId: string): string;
+/** Sidecar directory: `<devRoot>/.hover/sidecars`. Outside `__vibe_tests__/`,
+ *  so Playwright's default `*.spec.ts` glob trivially never reaches it. */
 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. */
+/** Pre-relocation sidecar home (`__vibe_tests__/.hover/`). Read-only fallback;
+ *  nothing writes here anymore. */
+export declare function legacySidecarDir(devRoot: string): string;
+/** Write the structured-session sidecar at `.hover/sidecars/<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>;
+/**
+ * Read one sidecar by slug, with legacy fallback + lazy copy-forward: when a
+ * sidecar only exists at the pre-relocation `__vibe_tests__/.hover/` path it
+ * is parsed from there and best-effort re-written into `.hover/sidecars/` so
+ * the next read hits the new home. Returns `null` when absent or malformed.
+ */
+export declare function readSidecar(devRoot: string, slug: string): Promise<SpecSidecar | null>;
+/** Parse one sidecar file, or `null` when absent / not JSON. Deliberately
+ *  lenient on shape (an empty `{}` still counts as "a sidecar exists") —
+ *  consumers that need `steps`/`slug` filter for themselves. */
+export declare function parseSidecarFile(path: string): Promise<SpecSidecar | null>;
 //# sourceMappingURL=sidecar.d.ts.map

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

@@ -1 +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"}
+{"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"}

package/dist/specs/sidecar.js

@@ -1,29 +1,62 @@
 /**
  * Structured-session sidecar for a generated spec.
  *
- * Every saved spec gets a companion `__vibe_tests__/.hover/<slug>.json` holding
+ * Every saved spec gets a companion `.hover/sidecars/<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.
+ * Home is the project-root `.hover/` directory (the same home as
+ * `.hover/conventions.md`) — Hover-derived data lives outside
+ * `__vibe_tests__/`, which stays 100% user-owned Playwright code. Sidecars
+ * historically lived nested at `__vibe_tests__/.hover/<slug>.json`; readers
+ * fall back to that legacy path and lazily copy-forward, so pre-existing
+ * projects keep working without a migration step.
  */
-import { mkdir, writeFile } from 'node:fs/promises';
+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;
-/** Sidecar directory under the spec output dir. Dot-prefixed on purpose:
- *  Playwright's default `*.spec.ts` glob never reaches into `.hover/`. */
+/** Project-root `.hover/` directory — the single home for Hover-derived data
+ *  (sidecars, runs, rules, conventions). */
+export function hoverDir(devRoot) {
+    return join(devRoot, '.hover');
+}
+/** Sanitize an id segment for use as a directory name (conversation / run id). */
+export function safeSeg(s) {
+    return (s || '').replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80) || 'unknown';
+}
+/** Per-run home: `<devRoot>/.hover/conversations/<conversationId>/<runId>/`.
+ *  Everything a single agent run produces — meta.json (the ledger record),
+ *  report.md (QA), screenshots/ — lives here, grouped under its conversation so
+ *  deleting a conversation is one `rm -rf .hover/conversations/<conversationId>`.
+ *  (Distinct from `.hover/runs/`, which is the Playwright spec-run-results
+ *  ledger written by ▶ Run.) */
+export function conversationsDir(devRoot) {
+    return join(hoverDir(devRoot), 'conversations');
+}
+export function conversationDir(devRoot, conversationId) {
+    return join(conversationsDir(devRoot), safeSeg(conversationId));
+}
+export function runDir(devRoot, conversationId, runId) {
+    return join(conversationDir(devRoot, conversationId), safeSeg(runId));
+}
+/** Sidecar directory: `<devRoot>/.hover/sidecars`. Outside `__vibe_tests__/`,
+ *  so Playwright's default `*.spec.ts` glob trivially never reaches it. */
 export function sidecarDir(devRoot) {
+    return join(hoverDir(devRoot), 'sidecars');
+}
+/** Pre-relocation sidecar home (`__vibe_tests__/.hover/`). Read-only fallback;
+ *  nothing writes here anymore. */
+export function legacySidecarDir(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. */
+/** Write the structured-session sidecar at `.hover/sidecars/<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 });
@@ -36,3 +69,40 @@ export async function writeSidecar(devRoot, data) {
     await writeFile(path, JSON.stringify(sidecar, null, 2) + '\n', 'utf-8');
     return path;
 }
+/**
+ * Read one sidecar by slug, with legacy fallback + lazy copy-forward: when a
+ * sidecar only exists at the pre-relocation `__vibe_tests__/.hover/` path it
+ * is parsed from there and best-effort re-written into `.hover/sidecars/` so
+ * the next read hits the new home. Returns `null` when absent or malformed.
+ */
+export async function readSidecar(devRoot, slug) {
+    const current = await parseSidecarFile(join(sidecarDir(devRoot), `${slug}.json`));
+    if (current)
+        return current;
+    const legacy = await parseSidecarFile(join(legacySidecarDir(devRoot), `${slug}.json`));
+    if (legacy) {
+        // Copy-forward, best effort — a read must never fail because the
+        // migration write did.
+        try {
+            const dir = sidecarDir(devRoot);
+            await mkdir(dir, { recursive: true });
+            await writeFile(join(dir, `${slug}.json`), JSON.stringify(legacy, null, 2) + '\n', 'utf-8');
+        }
+        catch {
+            /* leave it in the legacy home */
+        }
+    }
+    return legacy;
+}
+/** Parse one sidecar file, or `null` when absent / not JSON. Deliberately
+ *  lenient on shape (an empty `{}` still counts as "a sidecar exists") —
+ *  consumers that need `steps`/`slug` filter for themselves. */
+export async function parseSidecarFile(path) {
+    try {
+        const sc = JSON.parse(await readFile(path, 'utf-8'));
+        return sc && typeof sc === 'object' ? sc : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/specs/specStep.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The serialized captured-step shape the whole spec pipeline (writeSpec,
+ * sidecar, Page-Object extraction, the session record) consumes.
+ *
+ * One entry per recorded chat message: a user prompt, an agent narration, a
+ * `browser_*` / control-MCP tool call (`step`), or the terminal `done` summary.
+ * (Formerly `SkillStep` in specs/specStep.ts, back when a run could be saved
+ * as a `.claude/skills/<slug>/SKILL.md` — that feature was retired; only the
+ * type survived, now relocated here.)
+ */
+export interface SkillStep {
+    kind: 'user' | 'system' | 'step' | 'ai' | 'done';
+    text?: string;
+    tool?: string;
+    input?: unknown;
+    isError?: boolean;
+    turns?: number;
+    costUsd?: number;
+    summary?: string;
+}
+//# sourceMappingURL=specStep.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"specStep.d.ts","sourceRoot":"","sources":["../../src/specs/specStep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;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/specs/specStep.js

@@ -0,0 +1 @@
+export {};

package/dist/specs/text.d.ts

@@ -1,17 +1,19 @@
 /**
- * Small text helpers shared across the spec/CSV emitters.
+ * Small text helpers for the spec emitter.
  *
- * 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.
+ * Hoisted here so writeSpec's JSDoc header derives a slug and a one-sentence
+ * "Expected" line through one shared implementation.
  */
 /** 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.
+ * follows sentence-ending punctuation — Latin (`.`, `!`, `?`) AND CJK
+ * (`。`, `！`, `？`) so a Chinese summary doesn't dump its whole multi-line body
+ * (which then broke the JSDoc block). Also cuts at the first hard line break, so
+ * a summary that runs straight into a `\n\n- bullet` list keeps only the lead
+ * sentence. A summary with no such break comes back trimmed in full.
  */
 export declare function firstSentence(summary: string): string;
 //# sourceMappingURL=text.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/specs/text.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGrD"}

package/dist/specs/text.js

@@ -1,9 +1,8 @@
 /**
- * Small text helpers shared across the spec/CSV emitters.
+ * Small text helpers for the spec emitter.
  *
- * 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.
+ * Hoisted here so writeSpec's JSDoc header derives a slug and a one-sentence
+ * "Expected" line through one shared implementation.
  */
 /** Lowercase, hyphenate, and trim a display name into a filesystem-safe slug. */
 export function slugify(name) {
@@ -16,9 +15,13 @@ export function slugify(name) {
 /**
  * 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.
+ * follows sentence-ending punctuation — Latin (`.`, `!`, `?`) AND CJK
+ * (`。`, `！`, `？`) so a Chinese summary doesn't dump its whole multi-line body
+ * (which then broke the JSDoc block). Also cuts at the first hard line break, so
+ * a summary that runs straight into a `\n\n- bullet` list keeps only the lead
+ * sentence. A summary with no such break comes back trimmed in full.
  */
 export function firstSentence(summary) {
-    return summary.split(/(?<=[.!?])\s+/)[0]?.trim() ?? summary.trim();
+    const bySentence = summary.split(/(?<=[.!?。！？])\s+/)[0] ?? summary;
+    return bySentence.split(/\n/)[0]?.trim() ?? summary.trim();
 }

package/dist/specs/writeSpec.d.ts

@@ -1,4 +1,4 @@
-import type { SkillStep } from '../skills/writeSkill.js';
+import type { SkillStep } from '../specs/specStep.js';
 export type SpecStep = SkillStep;
 /**
  * Marker the deterministic translator leaves where a captured action is a real
@@ -24,6 +24,18 @@ export declare class SpecExistsError extends Error {
     readonly path: string;
     constructor(slug: string, path: string);
 }
+/**
+ * A credential to keep out of the generated spec. The deterministic translator
+ * replaces any fill value that exactly equals `value` with a
+ * `process.env.<envVar>` reference — so the literal password/username never
+ * lands in the spec source, the JSDoc header, OR the `.hover/` sidecar. The
+ * value comes from the caller (the editor resolves an `@account` mention from
+ * its vault); core only uses it to match-and-replace, never to write.
+ */
+export interface Redaction {
+    value: string;
+    envVar: string;
+}
 export interface WriteSpecOptions {
     devRoot: string;
     name: string;
@@ -31,10 +43,51 @@ export interface WriteSpecOptions {
     steps: SpecStep[];
     assertions?: SpecAssertion[];
     overwrite?: boolean;
+    /** Credentials to parameterize into `process.env.<envVar>` references. */
+    redactions?: Redaction[];
+    /** The run's target URL (the active environment / dev origin). Used to
+     *  guarantee the spec opens the app: if the captured session has NO
+     *  navigation (the agent connected to an already-open tab and never called
+     *  browser_navigate), a leading `page.goto()` is synthesized from this, and
+     *  it's the fallback origin for the scaffolded playwright config. */
+    startUrl?: string;
+    /** Recon-discovered reset recipe for the run's environment (debt-2 reproducible
+     *  state isolation). When tier 1, a shared `support/resetState.ts` helper is
+     *  generated and called in a `beforeEach` so the spec re-enters from a clean
+     *  client state every run. Tier 2/3 (backend-state) emit no reset here. (Engine
+     *  shape, decoupled from the extension's ResetRecipe — only tier/keys matter.) */
+    resetRecipe?: {
+        tier: number;
+        storageKeys?: string[];
+        hook?: string;
+    };
+    /** Auth-as-fixture (debt 3): engage the fixture EVEN WHEN a user playwright.config
+     *  already exists — i.e. the user approved Hover editing their config (Stage 4).
+     *  Without it, an existing config keeps login inline (Hover never edits a user's
+     *  config unprompted). When true, writeSpec also applies the setup-project edit
+     *  to the config. No effect when no login prefix is detected. */
+    authFixture?: boolean;
 }
 export interface WriteSpecResult {
+    /** Primary written file (the first flow when split, else the single spec). */
     path: string;
     slug: string;
+    /** Every file written — one per `mark_flow` feature when the run was split. */
+    files: {
+        path: string;
+        slug: string;
+        flow: string;
+    }[];
+    /** Auth-as-fixture (debt 3, Stage 4): a login was detected but a USER
+     *  playwright.config already exists, so Hover left login inline rather than
+     *  edit their config unprompted. This is the proposed edit to offer for
+     *  approval — on approval the caller re-saves with `authFixture: true`, which
+     *  applies it. Absent when there's no login, no user config, or the config
+     *  can't be safely edited (already has `projects`). */
+    authFixtureOffer?: {
+        configPath: string;
+        proposedConfig: string;
+    };
 }
 export declare function writeSpec(opts: WriteSpecOptions): Promise<WriteSpecResult>;
 /**
@@ -68,6 +121,14 @@ 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;
+/**
+ * browser_select_option always targets a native `<select>` — whose ARIA role
+ * is `combobox`. The agent's description is usually the label ("marital
+ * status"), with no role keyword, so selectorFromDescription would fall back to
+ * getByText and match the *label text*, not the control — and `.selectOption()`
+ * on a text node throws. Force the combobox role by accessible name instead.
+ */
+export declare function selectorForSelect(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.

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;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"}
+{"version":3,"file":"writeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/writeSpec.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAatD,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC;AAEjC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD;;0DAE0D;AAC1D,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE9D;AA2CD,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,eAAgB,SAAQ,KAAK;aACZ,IAAI,EAAE,MAAM;aAAkB,IAAI,EAAE,MAAM;gBAA1C,IAAI,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAIvE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB;;;;yEAIqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;sFAIkF;IAClF,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE;;;;qEAIiE;IACjE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAiDD,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtD;;;;;2DAKuD;IACvD,gBAAgB,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE;AAQD,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAchF;AA+mBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAM9E;AAED;;oCAEoC;AACpC,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAqB9E;AA0DD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAMxE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAQ1F"}