@hover-dev/core 0.16.0 → 0.17.0

package/dist/mcp/sourceServer.js

@@ -26,6 +26,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { readFileSync, realpathSync, statSync, readdirSync } from 'node:fs';
+import { WebSocket } from 'ws';
 import { resolveSourcePath, isWithinRoot } from './sourceFence.js';
 const root = process.env.HOVER_PROJECT_ROOT;
 if (!root) {
@@ -37,6 +38,76 @@ const MAX_BYTES = 256 * 1024;
 function md(text) {
     return { content: [{ type: 'text', text }] };
 }
+// ── Read-approval gate ──────────────────────────────────────────────────────
+// When the host runs us with HOVER_SOURCE_GATE=ask, every read/list first asks
+// the editor (over the Hover service WS at HOVER_APPROVAL_PORT) for the user's
+// one-click approval. The reader is fenced + read-only, so the gate is consent
+// UX, not a security boundary: if the editor can't be reached or doesn't answer
+// within 30s we FAIL OPEN (allow) rather than stall the agent's run.
+const GATE = process.env.HOVER_SOURCE_GATE;
+const APPROVAL_PORT = process.env.HOVER_APPROVAL_PORT;
+let approvalWs = null;
+let approvalSeq = 0;
+const pendingApprovals = new Map();
+function ensureApprovalWs() {
+    if (GATE !== 'ask' || !APPROVAL_PORT)
+        return null;
+    if (approvalWs && (approvalWs.readyState === WebSocket.OPEN || approvalWs.readyState === WebSocket.CONNECTING))
+        return approvalWs;
+    try {
+        const sock = new WebSocket(`ws://127.0.0.1:${APPROVAL_PORT}`);
+        sock.on('message', (data) => {
+            try {
+                const m = JSON.parse(data.toString());
+                if (m?.type === 'source-approval-response' && m.payload?.approvalId) {
+                    const settle = pendingApprovals.get(m.payload.approvalId);
+                    if (settle)
+                        settle(m.payload.allow === true);
+                }
+            }
+            catch { /* ignore malformed */ }
+        });
+        // Channel lost → fail OPEN for every waiting read (the reader is fenced +
+        // read-only; the gate is consent UX, not a security boundary, so never hang
+        // a run on a dead channel). The user taking their time is NOT a loss — only
+        // a closed/errored socket settles here.
+        const drain = () => { for (const s of [...pendingApprovals.values()])
+            s(true); };
+        sock.on('error', () => { drain(); });
+        sock.on('close', () => { if (approvalWs === sock)
+            approvalWs = null; drain(); });
+        approvalWs = sock;
+    }
+    catch {
+        approvalWs = null;
+    }
+    return approvalWs;
+}
+async function approve(path, kind) {
+    if (GATE !== 'ask' || !APPROVAL_PORT)
+        return true; // not gated → allow
+    const sock = ensureApprovalWs();
+    if (!sock)
+        return true; // no channel → fail open
+    const id = `a${++approvalSeq}`;
+    return new Promise((resolve) => {
+        // NO timeout: the consent prompt waits for the user (they may not see it for
+        // a while — that must never auto-allow). It settles only on their answer, or
+        // when the channel drops (drain() above → fail open), or run cancel.
+        const settle = (allow) => {
+            if (!pendingApprovals.has(id))
+                return;
+            pendingApprovals.delete(id);
+            resolve(allow);
+        };
+        pendingApprovals.set(id, settle);
+        const req = () => sock.send(JSON.stringify({ type: 'source-approval-request', payload: { approvalId: id, sourcePath: path, sourceKind: kind } }));
+        if (sock.readyState === WebSocket.OPEN)
+            req();
+        else
+            sock.once('open', req);
+    });
+}
 const server = new McpServer({ name: 'hover-source', version: '0.0.0' });
 server.registerTool('read_source', {
     description: "Read a source file from THIS project (read-only). Pass a repo-relative path (e.g. the one in an element's data-hover-source, `src/app/login.tsx:42` → path `src/app/login.tsx`). Fenced to the project root: paths that escape it, or that name secrets / keys / .env / .git / node_modules / build output, are refused. Use this to write tests against the real selectors & routes, or — in security/pentest mode — to confirm a finding against the actual server code (the SQL query, the authz check). You cannot write, run, or delete anything.",
@@ -44,6 +115,8 @@ server.registerTool('read_source', {
         path: z.string().describe('Repo-relative path to a source file, e.g. "src/api/orders.ts".'),
     },
 }, async ({ path }) => {
+    if (!(await approve(path, 'read')))
+        return md(`✗ source read declined by the user — continue from what's visible on the page.`);
     const f = resolveSourcePath(ROOT, path);
     if (!f.ok)
         return md(`✗ ${f.reason}`);
@@ -85,6 +158,8 @@ server.registerTool('list_source', {
         subdir: z.string().optional().describe('Repo-relative directory, e.g. "src/api". Omit for the root.'),
     },
 }, async ({ subdir }) => {
+    if (!(await approve(subdir || '.', 'list')))
+        return md(`✗ source listing declined by the user.`);
     let dirAbs = ROOT;
     let base = '';
     if (subdir && subdir.trim() && subdir.trim() !== '.') {

package/dist/memory/businessMemory.d.ts

@@ -0,0 +1,29 @@
+/** A learned business fact about the app under test. */
+export interface BusinessFact {
+    /** kebab-case slug; also the filename stem. */
+    name: string;
+    /** One-line summary used for recall relevance + the index hook. */
+    description: string;
+    /** What kind of knowledge this is. */
+    type: 'business-rule' | 'expected-behavior' | 'validation' | 'access-policy';
+    /** The fact itself (markdown). */
+    body: string;
+}
+export declare function memoryDir(devRoot: string): string;
+/** kebab-case a title into a safe filename stem. */
+export declare function slugify(s: string): string;
+/** Load every fact under `.hover/memory/` (excluding the MEMORY.md index).
+ *  Pure + total: a missing dir / unreadable file just yields fewer facts. */
+export declare function loadMemory(devRoot: string): Promise<BusinessFact[]>;
+/** Format loaded facts as a system-prompt block, or '' when there are none (so
+ *  the caller appends nothing). Grouped nothing-fancy: one bullet per fact. */
+export declare function formatMemoryForPrompt(facts: BusinessFact[]): string;
+/** Write (or overwrite) a fact file + refresh the MEMORY.md index line. NEVER
+ *  throws — returns the path or an error string for the caller to log. Business
+ *  RULES only; the caller must never pass secrets / PII / credentials. */
+export declare function writeFact(devRoot: string, fact: BusinessFact): Promise<{
+    path: string;
+} | {
+    error: string;
+}>;
+//# sourceMappingURL=businessMemory.d.ts.map

package/dist/memory/businessMemory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"businessMemory.d.ts","sourceRoot":"","sources":["../../src/memory/businessMemory.ts"],"names":[],"mappings":"AAwBA,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,IAAI,EAAE,eAAe,GAAG,mBAAmB,GAAG,YAAY,GAAG,eAAe,CAAC;IAC7E,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,oDAAoD;AACpD,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAMzC;AAsBD;6EAC6E;AAC7E,wBAAsB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAkBzE;AAED;+EAC+E;AAC/E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,MAAM,CAQnE;AAED;;0EAE0E;AAC1E,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAc/C"}

package/dist/memory/businessMemory.js

@@ -0,0 +1,125 @@
+/**
+ * Business memory — the per-app knowledge QA / API modes accumulate so they stop
+ * re-asking the same business questions every run. Lives at `<devRoot>/.hover/
+ * memory/`, mirroring Claude's own memory layout (an index + one fact per file):
+ *
+ *   .hover/memory/
+ *     MEMORY.md        ← index: one `- [title](file.md) — hook` line per fact
+ *     checkout-tax.md  ← frontmatter (name / description / type) + the fact body
+ *     ...
+ *
+ * Loop: load at run start → inject as agent context ("Known business rules…");
+ * after the user answers a business clarification (trigger-B, a later QA stage),
+ * write the learned fact. The more an app is tested, the fewer popups — see the
+ * QA-tester-mode design + project-moat-strategy.
+ *
+ * CONTRACT: business RULES only, NEVER secrets / PII / credentials (extends the
+ * standing "never read env / secrets" rule). Writes are best-effort — a memory
+ * failure must NEVER break a run (same rule as the session ledger). Used by QA +
+ * API modes only; Flow / Pentest don't read or write it.
+ */
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { hoverDir } from '../specs/sidecar.js';
+export function memoryDir(devRoot) {
+    return join(hoverDir(devRoot), 'memory');
+}
+/** kebab-case a title into a safe filename stem. */
+export function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60) || 'fact';
+}
+/** Parse a fact file's `---` frontmatter + body. Minimal + total — a malformed
+ *  file yields nulls and is skipped by the caller. Only the three known keys are
+ *  read; everything after the closing `---` is the body. */
+function parseFact(slug, raw) {
+    const m = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!m)
+        return null;
+    const fm = m[1];
+    const body = m[2].trim();
+    const field = (k) => {
+        const f = fm.match(new RegExp(`^${k}\\s*:\\s*(.+)$`, 'm'));
+        return f ? f[1].trim().replace(/^["']|["']$/g, '') : '';
+    };
+    const description = field('description');
+    const rawType = field('type');
+    const types = ['business-rule', 'expected-behavior', 'validation', 'access-policy'];
+    const type = types.includes(rawType) ? rawType : 'business-rule';
+    if (!body)
+        return null;
+    return { name: field('name') || slug, description, type, body };
+}
+/** Load every fact under `.hover/memory/` (excluding the MEMORY.md index).
+ *  Pure + total: a missing dir / unreadable file just yields fewer facts. */
+export async function loadMemory(devRoot) {
+    try {
+        const dir = memoryDir(devRoot);
+        const entries = (await readdir(dir)).filter((e) => e.endsWith('.md') && e.toLowerCase() !== 'memory.md');
+        const facts = [];
+        for (const entry of entries.sort()) {
+            try {
+                const raw = await readFile(join(dir, entry), 'utf-8');
+                const fact = parseFact(entry.replace(/\.md$/, ''), raw);
+                if (fact)
+                    facts.push(fact);
+            }
+            catch {
+                /* skip unreadable */
+            }
+        }
+        return facts;
+    }
+    catch {
+        return [];
+    }
+}
+/** Format loaded facts as a system-prompt block, or '' when there are none (so
+ *  the caller appends nothing). Grouped nothing-fancy: one bullet per fact. */
+export function formatMemoryForPrompt(facts) {
+    if (!facts.length)
+        return '';
+    const lines = facts.map((f) => `- ${f.description ? f.description + ' — ' : ''}${f.body.replace(/\s+/g, ' ').trim()}`);
+    return ('KNOWN BUSINESS KNOWLEDGE FOR THIS APP (learned from earlier runs — treat as ' +
+        'ground truth; do NOT re-ask what these already answer):\n' +
+        lines.join('\n'));
+}
+/** Write (or overwrite) a fact file + refresh the MEMORY.md index line. NEVER
+ *  throws — returns the path or an error string for the caller to log. Business
+ *  RULES only; the caller must never pass secrets / PII / credentials. */
+export async function writeFact(devRoot, fact) {
+    try {
+        const dir = memoryDir(devRoot);
+        await mkdir(dir, { recursive: true });
+        const slug = slugify(fact.name);
+        const file = `${slug}.md`;
+        const content = `---\nname: ${slug}\ndescription: ${fact.description}\ntype: ${fact.type}\n---\n\n${fact.body.trim()}\n`;
+        await writeFile(join(dir, file), content, 'utf-8');
+        await upsertIndex(dir, slug, fact);
+        return { path: join(dir, file) };
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Add/replace this fact's line in MEMORY.md (`- [title](file.md) — hook`),
+ *  keyed by the file link so re-writing a fact updates rather than duplicates. */
+async function upsertIndex(dir, slug, fact) {
+    const indexPath = join(dir, 'MEMORY.md');
+    const link = `(${slug}.md)`;
+    const line = `- [${fact.name}](${slug}.md) — ${fact.description || fact.type}`;
+    let existing = '';
+    try {
+        existing = await readFile(indexPath, 'utf-8');
+    }
+    catch {
+        existing = '# Business memory\n\nWhat Hover has learned about this app. One fact per file.\n';
+    }
+    const kept = existing
+        .split('\n')
+        .filter((l) => !(l.startsWith('- [') && l.includes(link)));
+    await writeFile(indexPath, `${kept.join('\n').replace(/\n+$/, '')}\n${line}\n`, 'utf-8');
+}

package/dist/modes.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Built-in (non-plugin) mode behavior. Hover's core modes — Flow (the default,
+ * modeId `null`) and the planned QA mode — are pure agent-behavior config: which
+ * actuation tools the agent uses and how a run crystallizes. (Plugin modes —
+ * api-test / pentest — bring runtime machinery instead: a MITM proxy, sidecars,
+ * Chrome proxy flags, lifecycle hooks; they resolve to PLUGIN_MODE_BEHAVIOR.)
+ *
+ * `resolveModeBehavior(modeId)` is the SINGLE place that answers "how does this
+ * mode drive the agent", replacing scattered `currentModeId === null` checks.
+ * Adding a built-in mode (e.g. QA) = one entry in BUILTIN_MODE_BEHAVIOR, not new
+ * conditionals threaded through the run-assembly path.
+ */
+export interface ModeBehavior {
+    /** Deny Playwright's loose interaction tools (browser_click / type / fill_form
+     *  / select_option / file_upload) AND inject the grounded-actuation directive,
+     *  so the agent actuates via the Hover control MCP and saved selectors are
+     *  role+name (record == replay). Flow and QA want this — they crystallize
+     *  browser steps; plugin modes don't — they explore to capture traffic and
+     *  keep the Playwright tools. */
+    groundedActuation: boolean;
+}
+/** Resolve the agent-behavior config for a mode id (null = Flow). Built-in modes
+ *  are table-driven; any other (plugin) id falls back to PLUGIN_MODE_BEHAVIOR. */
+export declare function resolveModeBehavior(modeId: string | null): ModeBehavior;
+/** Picker metadata for built-in non-Flow modes (Flow is the implicit null
+ *  default, not listed). core's broadcastModes merges these into the mode
+ *  catalogue alongside plugin-contributed modes, and switchMode/set-mode accept
+ *  them without requiring a plugin. */
+export interface BuiltinMode {
+    id: string;
+    label: string;
+    description: string;
+    accent: string;
+}
+export declare const BUILTIN_MODES: BuiltinMode[];
+/** True for a built-in non-null mode id (currently just `qa`). Lets core accept
+ *  it in set-mode / switchMode without a contributing plugin. */
+export declare function isBuiltinMode(modeId: string): boolean;
+//# sourceMappingURL=modes.d.ts.map

package/dist/modes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modes.d.ts","sourceRoot":"","sources":["../src/modes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;qCAKiC;IACjC,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAmBD;kFACkF;AAClF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,YAAY,CAGvE;AAED;;;uCAGuC;AACvC,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AACD,eAAO,MAAM,aAAa,EAAE,WAAW,EAOtC,CAAC;AAEF;iEACiE;AACjE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAErD"}

package/dist/modes.js

@@ -0,0 +1,34 @@
+/** Flow — the default mode (modeId `null`): author a Playwright spec via grounded
+ *  actuation. */
+const FLOW_MODE_BEHAVIOR = { groundedActuation: true };
+/** Built-in modes other than Flow, keyed by modeId.
+ *  QA = comprehensive testing umbrella; its Functional capability reuses Flow's
+ *  grounded actuation (record == replay for promoted candidate flows). (Its API
+ *  capability — when enabled — delegates to the api-test plugin's MITM runtime;
+ *  that orchestration is a later QA stage, not a ModeBehavior field.) */
+const BUILTIN_MODE_BEHAVIOR = {
+    qa: { groundedActuation: true },
+};
+/** Plugin-contributed modes (api-test / pentest): full Playwright tool access —
+ *  they explore to capture traffic, not to crystallize browser steps. */
+const PLUGIN_MODE_BEHAVIOR = { groundedActuation: false };
+/** Resolve the agent-behavior config for a mode id (null = Flow). Built-in modes
+ *  are table-driven; any other (plugin) id falls back to PLUGIN_MODE_BEHAVIOR. */
+export function resolveModeBehavior(modeId) {
+    if (modeId === null)
+        return FLOW_MODE_BEHAVIOR;
+    return BUILTIN_MODE_BEHAVIOR[modeId] ?? PLUGIN_MODE_BEHAVIOR;
+}
+export const BUILTIN_MODES = [
+    {
+        id: 'qa',
+        label: 'QA Testing',
+        description: 'explore the whole app → findings report + promotable specs',
+        accent: '#22c55e',
+    },
+];
+/** True for a built-in non-null mode id (currently just `qa`). Lets core accept
+ *  it in set-mode / switchMode without a contributing plugin. */
+export function isBuiltinMode(modeId) {
+    return modeId in BUILTIN_MODE_BEHAVIOR;
+}

package/dist/playwright/cdpStatus.d.ts

@@ -11,19 +11,4 @@ export interface CdpStatusResult {
     reason?: string;
 }
 export declare function checkCdpStatus(cdpUrl: string, pageUrl: string): Promise<CdpStatusResult>;
-/**
- * Bring the debug-Chrome tab matching `pageUrl`'s origin to the front. If no
- * matching tab exists, open a new tab on the origin. Returns the URL of the
- * tab that was focused (or opened) for logging.
- *
- * Uses a short-lived playwright-core connection — opens it, does the work,
- * closes it. We don't keep a long-lived browser handle.
- */
-export declare function focusDebugTab(cdpUrl: string, pageUrl: string): Promise<{
-    ok: true;
-    focusedUrl: string;
-} | {
-    ok: false;
-    reason: string;
-}>;
 //# sourceMappingURL=cdpStatus.d.ts.map

package/dist/playwright/cdpStatus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cdpStatus.d.ts","sourceRoot":"","sources":["../../src/playwright/cdpStatus.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,QAAQ,GAAG,aAAa,GAAG,cAAc,GAAG,QAAQ,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,QAAQ,CAAC;IAChB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,eAAe,CAAC,CA4B1B;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA8C3E"}
+{"version":3,"file":"cdpStatus.d.ts","sourceRoot":"","sources":["../../src/playwright/cdpStatus.ts"],"names":[],"mappings":"AAeA,MAAM,MAAM,QAAQ,GAAG,aAAa,GAAG,cAAc,GAAG,QAAQ,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,QAAQ,CAAC;IAChB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,eAAe,CAAC,CA4B1B"}

package/dist/playwright/cdpStatus.js

@@ -11,9 +11,7 @@
  *   - 'no-cdp'        no debug Chrome at all; the widget should let the user
  *                     trigger a launch.
  */
-import { chromium } from 'playwright-core';
 import { getPreflight } from './preflightCache.js';
-import { findCdpPid, raiseChromeWindow } from './raiseWindow.js';
 /**
  * Parse a page URL down to its origin (protocol + host + port). We compare
  * by origin, not full URL — the user might be on /login while the debug
@@ -52,68 +50,3 @@ export async function checkCdpStatus(cdpUrl, pageUrl) {
         browser: cdp.browser,
     };
 }
-/**
- * Bring the debug-Chrome tab matching `pageUrl`'s origin to the front. If no
- * matching tab exists, open a new tab on the origin. Returns the URL of the
- * tab that was focused (or opened) for logging.
- *
- * Uses a short-lived playwright-core connection — opens it, does the work,
- * closes it. We don't keep a long-lived browser handle.
- */
-export async function focusDebugTab(cdpUrl, pageUrl) {
-    const wantOrigin = originOf(pageUrl);
-    if (!wantOrigin) {
-        return { ok: false, reason: `unparseable page URL: ${pageUrl}` };
-    }
-    let browser;
-    try {
-        browser = await chromium.connectOverCDP(cdpUrl);
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return { ok: false, reason: `couldn't connect to CDP at ${cdpUrl}: ${msg}` };
-    }
-    let focusedUrl;
-    try {
-        const pages = browser.contexts().flatMap(c => c.pages());
-        const match = pages.find(p => originOf(p.url()) === wantOrigin);
-        if (match) {
-            await match.bringToFront();
-            focusedUrl = match.url();
-        }
-        else {
-            // No tab on the dev origin yet — open one so the widget appears.
-            const context = browser.contexts()[0] ?? (await browser.newContext());
-            const page = await context.newPage();
-            await page.goto(pageUrl, { waitUntil: 'domcontentloaded' });
-            await page.bringToFront();
-            focusedUrl = page.url();
-        }
-    }
-    catch (err) {
-        await browser.close().catch(() => { });
-        const msg = err instanceof Error ? err.message : String(err);
-        return { ok: false, reason: `bringToFront failed: ${msg}` };
-    }
-    await browser.close().catch(() => { });
-    // CDP-level bringToFront only activates the tab inside the Chrome process;
-    // on macOS in particular the Chrome *window* stays buried if it wasn't
-    // foreground already. Raise the OS window too. Best-effort, never fatal.
-    const port = portFromCdpUrl(cdpUrl);
-    if (port !== null) {
-        const pid = await findCdpPid(port);
-        if (pid !== null)
-            await raiseChromeWindow(pid);
-    }
-    return { ok: true, focusedUrl };
-}
-function portFromCdpUrl(cdpUrl) {
-    try {
-        const u = new URL(cdpUrl);
-        const port = Number.parseInt(u.port, 10);
-        return Number.isInteger(port) && port > 0 ? port : null;
-    }
-    catch {
-        return null;
-    }
-}

package/dist/playwright/launchChrome.d.ts

@@ -21,6 +21,17 @@ export interface LaunchOptions {
         /** Base64 SHA-256 of the MITM CA's SubjectPublicKeyInfo. */
         spki: string;
     };
+    /** Launch Chrome headless (`--headless=new`) — no visible window. Still
+     *  CDP-drivable and still uses the persistent profile, so login state set in
+     *  a prior headed launch carries over. Used by the VSCode extension's silent
+     *  mode. Default false (visible window). */
+    headless?: boolean;
+    /** Close any existing debug Chrome on this port FIRST, then launch fresh.
+     *  The plain launch is idempotent (returns the running instance), so it can't
+     *  switch headless↔visible or recover a window that's there-but-not-showing —
+     *  `force` makes the headless/visible toggle and the "reopen browser" action
+     *  actually relaunch. Default false. */
+    force?: boolean;
 }
 export type LaunchResult = {
     ok: true;
@@ -32,6 +43,13 @@ export type LaunchResult = {
     reason: string;
 };
 export declare function findChromeBinary(): string | null;
+/**
+ * Close a debug Chrome on `port` by sending CDP `Browser.close` over its
+ * DevTools WebSocket (from /json/version). Works without a child-process handle
+ * — Hover spawns Chrome detached — so it's the only way to relaunch in a
+ * different mode. Resolves once closed (or the timeout lapses); never throws.
+ */
+export declare function closeDebugChrome(port: number, timeoutMs?: number): Promise<boolean>;
 /**
  * Start (or detect) a debug Chrome listening on the given CDP port. Detaches
  * the child process so the calling script can exit cleanly while Chrome keeps

package/dist/playwright/launchChrome.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"launchChrome.d.ts","sourceRoot":"","sources":["../../src/playwright/launchChrome.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;wEAKoE;IACpE,KAAK,CAAC,EAAE;QACN,oDAAoD;QACpD,IAAI,EAAE,MAAM,CAAC;QACb,4DAA4D;QAC5D,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,cAAc,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACxE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAMlC,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CA0ChD;AAiCD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CA8DvF"}
+{"version":3,"file":"launchChrome.d.ts","sourceRoot":"","sources":["../../src/playwright/launchChrome.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;wEAKoE;IACpE,KAAK,CAAC,EAAE;QACN,oDAAoD;QACpD,IAAI,EAAE,MAAM,CAAC;QACb,4DAA4D;QAC5D,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF;;;gDAG4C;IAC5C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;4CAIwC;IACxC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,cAAc,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACxE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAMlC,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CA0ChD;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAmBvF;AAiCD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAuEvF"}

package/dist/playwright/launchChrome.js

@@ -1,9 +1,8 @@
 /**
  * Cross-platform launcher for an isolated debug Chrome on a known CDP port.
  *
- * Idempotent — if the port already responds, returns immediately. Used by:
- *   - `pnpm smoke:chrome` (monorepo) via src/scripts/start-chrome.ts
- *   - `pnpm exec hover-chrome` (npm consumers) via vite-plugin-hover's bin
+ * Idempotent — if the port already responds, returns immediately. The VS Code
+ * extension calls this on demand (first ✨ click) to bring up the debug Chrome.
  *
  * The user-data-dir is isolated under tmpdir so we never touch the user's
  * primary Chrome profile.
@@ -12,6 +11,7 @@ import { spawn } from 'node:child_process';
 import { existsSync, unlinkSync } from 'node:fs';
 import { platform, tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { WebSocket } from 'ws';
 const DEFAULT_PORT = 9222;
 const DEFAULT_READY_TIMEOUT_MS = 9000;
 const DEFAULT_POLL_MS = 300;
@@ -53,6 +53,39 @@ export function findChromeBinary() {
     }
     return null;
 }
+/**
+ * Close a debug Chrome on `port` by sending CDP `Browser.close` over its
+ * DevTools WebSocket (from /json/version). Works without a child-process handle
+ * — Hover spawns Chrome detached — so it's the only way to relaunch in a
+ * different mode. Resolves once closed (or the timeout lapses); never throws.
+ */
+export async function closeDebugChrome(port, timeoutMs = 4000) {
+    let wsUrl;
+    try {
+        const res = await fetch(`http://localhost:${port}/json/version`, { signal: AbortSignal.timeout(1500) });
+        if (!res.ok)
+            return false;
+        wsUrl = (await res.json()).webSocketDebuggerUrl ?? '';
+    }
+    catch {
+        return false;
+    }
+    if (!wsUrl)
+        return false;
+    return await new Promise((resolve) => {
+        let done = false;
+        const finish = (ok) => { if (done)
+            return; done = true; try {
+            sock.close();
+        }
+        catch { /* ignore */ } resolve(ok); };
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        const sock = new WebSocket(wsUrl);
+        sock.on('open', () => sock.send(JSON.stringify({ id: 1, method: 'Browser.close' })));
+        sock.on('message', () => { clearTimeout(timer); finish(true); });
+        sock.on('error', () => { clearTimeout(timer); finish(false); });
+    });
+}
 async function isCdpAlive(port) {
     try {
         const res = await fetch(`http://localhost:${port}/json/version`, {
@@ -95,6 +128,14 @@ export async function launchDebugChrome(opts = {}) {
     const url = opts.url ?? 'about:blank';
     const readyTimeoutMs = opts.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
     const pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
+    // force: close any existing instance first so a headless↔visible switch (or
+    // a "reopen browser" click) actually relaunches instead of no-opping.
+    if (opts.force && (await isCdpAlive(port))) {
+        await closeDebugChrome(port);
+        // Give the port a moment to free up before relaunch.
+        for (let i = 0; i < 20 && (await isCdpAlive(port)); i++)
+            await new Promise((r) => setTimeout(r, 150));
+    }
     if (await isCdpAlive(port)) {
         return { ok: true, alreadyRunning: true, userDataDir, port };
     }
@@ -112,6 +153,8 @@ export async function launchDebugChrome(opts = {}) {
         '--no-first-run',
         '--no-default-browser-check',
     ];
+    if (opts.headless)
+        args.push('--headless=new');
     if (opts.proxy) {
         args.push(`--proxy-server=127.0.0.1:${opts.proxy.port}`, `--ignore-certificate-errors-spki-list=${opts.proxy.spki}`);
     }

package/dist/playwright/resolveMcpConfig.d.ts

@@ -28,7 +28,7 @@ export interface ExtraMcpServer {
 }
 /** The `mcp__<id>` tool-name prefix Claude Code exposes a plugin MCP server's
  *  tools under: non-alphanumerics collapse to `_` and edges are trimmed (e.g.
- *  `@hover-dev/security:flows` → `mcp__hover_dev_security_flows`). Used to build
+ *  `@hover-dev/api-test:flows` → `mcp__hover_dev_api_test_flows`). Used to build
  *  the hard-sandbox allow-list. Single source so the service and the CLI scan
  *  command can't drift on how the prefix is derived. */
 export declare function mcpToolPrefix(serverId: string): string;
@@ -46,6 +46,12 @@ export declare function resolveMcpConfig(opts: {
     /** Suffix for the output filename so multiple parallel configs from
      *  the same service (e.g. mode toggle round-trips) don't share state. */
     suffix?: string;
+    /** Directory the Playwright MCP server writes its output files
+     *  (screenshots, PDFs, traces) into — passed as `--output-dir`. Hover
+     *  points this at `<devRoot>/.hover/screenshots/<session>` so test
+     *  artifacts land in the project's Hover home, grouped per run, instead
+     *  of the MCP server's default OS temp dir. Created if missing. */
+    outputDir?: string;
     /** Project root to resolve `@playwright/mcp` from. Defaults to
      *  `process.cwd()`. `hover run --cwd apps/web` passes the target workspace
      *  so a monorepo that installed `@hover-dev/core` only under that app (not

package/dist/playwright/resolveMcpConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolveMcpConfig.d.ts","sourceRoot":"","sources":["../../src/playwright/resolveMcpConfig.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,cAAc;IAC7B;2EACuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED;;;;wDAIwD;AACxD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb;;;;2CAIuC;IACvC,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB;6EACyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;kFAG8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,MAAM,CAsDT"}
+{"version":3,"file":"resolveMcpConfig.d.ts","sourceRoot":"","sources":["../../src/playwright/resolveMcpConfig.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,cAAc;IAC7B;2EACuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED;;;;wDAIwD;AACxD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb;;;;2CAIuC;IACvC,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB;6EACyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;uEAImE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;kFAG8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,MAAM,CAyET"}

package/dist/playwright/resolveMcpConfig.js

@@ -5,7 +5,7 @@ import { tmpdir } from 'node:os';
 import process from 'node:process';
 /** The `mcp__<id>` tool-name prefix Claude Code exposes a plugin MCP server's
  *  tools under: non-alphanumerics collapse to `_` and edges are trimmed (e.g.
- *  `@hover-dev/security:flows` → `mcp__hover_dev_security_flows`). Used to build
+ *  `@hover-dev/api-test:flows` → `mcp__hover_dev_api_test_flows`). Used to build
  *  the hard-sandbox allow-list. Single source so the service and the CLI scan
  *  command can't drift on how the prefix is derived. */
 export function mcpToolPrefix(serverId) {
@@ -28,17 +28,35 @@ export function resolveMcpConfig(opts) {
     // and `@playwright/mcp` is always reachable from there because it's
     // a declared dependency of `@hover-dev/core`, which the user installed.
     // The caller may override with an explicit `cwd` (e.g. `hover run --cwd`).
-    const require = createRequire(resolve(opts.cwd ?? process.cwd(), 'package.json'));
-    const pkgJsonPath = require.resolve('@playwright/mcp/package.json');
+    //
+    // Fallback for the engine-in-extension model (`@hover-dev/vscode-ext`): there
+    // the project (devRoot) is the USER's repo, which does NOT have
+    // `@playwright/mcp` — the engine is shipped as a flat node_modules inside the
+    // .vsix, so `@playwright/mcp` lives next to `@hover-dev/core` itself. When the
+    // cwd-based resolution fails, fall back to resolving from this module's own
+    // location (which reaches the staged engine's node_modules).
+    let pkgJsonPath;
+    try {
+        pkgJsonPath = createRequire(resolve(opts.cwd ?? process.cwd(), 'package.json')).resolve('@playwright/mcp/package.json');
+    }
+    catch {
+        pkgJsonPath = createRequire(import.meta.url).resolve('@playwright/mcp/package.json');
+    }
     const pkgRoot = dirname(pkgJsonPath);
     // The package's `bin` map declares "playwright-mcp": "cli.js" — we
     // pin to that file directly via Node so the user doesn't need the
     // bin shim on PATH and we skip yet another resolution layer.
     const cliPath = resolve(pkgRoot, 'cli.js');
+    const playwrightArgs = [cliPath, '--cdp-endpoint', opts.cdpUrl];
+    if (opts.outputDir) {
+        const abs = resolve(opts.outputDir);
+        mkdirSync(abs, { recursive: true });
+        playwrightArgs.push('--output-dir', abs);
+    }
     const mcpServers = {
         playwright: {
             command: process.execPath, // current Node binary
-            args: [cliPath, '--cdp-endpoint', opts.cdpUrl],
+            args: playwrightArgs,
         },
     };
     for (const extra of opts.extra ?? []) {