@hover-dev/core 0.12.0 → 0.14.0

package/README.md

@@ -2,7 +2,7 @@
 
 The local Node service. Owns:
 
-- **Agent invocation** (`src/agents/`) — Local CLI Agent First. Spawns `claude` / `codex` / `cursor` / ... and normalizes their output into a single `InvokeEvent` stream.
+- **Agent invocation** (`src/agents/`) — Local CLI Agent First. Spawns `claude` / `codex` / `cursor-agent` / `aider` / `gemini-cli` / `qwen-code` and normalizes their output into a single `InvokeEvent` stream.
 - **Playwright preflight** (`src/playwright/`) — verifies CDP connection to the user's Chrome.
 - **Smoke test** (`src/smoke.ts`) — end-to-end verification of the whole chain.
 
@@ -20,6 +20,9 @@ The local Node service. Owns:
 | `claude.ts` | Claude Code descriptor: `claude -p`, stream-json parser, hard sandbox flags |
 | `codex.ts` | OpenAI Codex CLI descriptor: `codex exec --json`, JSONL parser, soft sandbox (`--sandbox read-only`) |
 | `cursor.ts` | Cursor CLI descriptor (v0.9): stream-JSON / NDJSON parser, soft sandbox |
+| `aider.ts` | Aider CLI descriptor (v0.10): JSON-stream parser, soft sandbox |
+| `gemini.ts` | Gemini CLI descriptor (v0.10): stream parser, soft sandbox |
+| `qwen.ts` | Qwen Code descriptor (v0.10): stream parser, soft sandbox |
 
 To add an agent: implement an `AgentDescriptor`, register it in `registry.ts`. Done.
 
@@ -45,7 +48,7 @@ pnpm smoke http://localhost:5173/ "log in then add a todo named 'verify hover'"
 Environment variables:
 
 - `HOVER_CDP` — CDP URL (default `http://localhost:9222`)
-- `HOVER_AGENT` — agent id (omit to auto-detect; tries the user's stated preference, then the first installed agent in registry order — `claude` → `codex` → `cursor-agent` today)
+- `HOVER_AGENT` — agent id (omit to auto-detect; tries the user's stated preference, then the first installed agent in registry order — `claude` → `codex` → `cursor-agent` → `aider` → `gemini-cli` → `qwen-code` today)
 - `HOVER_MODEL` — model for the agent (default `sonnet`, much cheaper than opus)
 
 ## Sandboxing (what the smoke test enforces)
@@ -53,9 +56,9 @@ Environment variables:
 The `claude -p` invocation is locked down so Claude can only drive the browser:
 
 - `--strict-mcp-config` — ignore any MCP servers in `~/.claude/` or `.mcp.json`
-- `--allowedTools mcp__playwright` — only Playwright MCP is callable
-- `--disallowedTools Bash Edit Write Read Grep Glob Task WebFetch WebSearch` — every built-in tool explicitly denied
+- `--allowedTools mcp__playwright Skill` — only Playwright MCP and the Skill tool are callable
+- `--disallowedTools Bash Edit Write Read Grep Glob Task WebFetch WebSearch EnterWorktree CronCreate …` — every built-in tool explicitly denied (full list in `CLAUDE_DEFAULT_DISALLOWED_TOOLS` in `claude.ts`)
 - `--permission-mode dontAsk` — anything not whitelisted aborts the run
-- `--max-budget-usd 0.50` — hard ceiling per session
+- `--max-budget-usd <n>` — optional hard $ ceiling per session (no default; pass `maxBudgetUsd` in plugin options or via the CLI flag to enable)
 
 Together these enforce the rule that the spawned agent can only reach the browser via Playwright MCP — never the host filesystem, shell, or network. A hijacked prompt or hallucinated destructive action has nowhere to land.

package/dist/playwright/preflight.js

@@ -34,7 +34,7 @@ export async function preflightCDP(cdpUrl, timeoutMs = 2000) {
     catch (err) {
         return {
             ok: false,
-            reason: `Chrome debug session not detected at ${cdpUrl}. Start it with: pnpm exec hover-chrome (or: npx hover-chrome)`,
+            reason: `Chrome debug session not detected at ${cdpUrl}. Click the ✨ launcher in the widget to start it, or run \`pnpm exec hover-chrome\` (npx hover-chrome).`,
         };
     }
     if (!versionRes.ok) {

package/dist/plugin-api.d.ts

@@ -33,6 +33,10 @@ export interface HoverPluginMode {
     label: string;
     /** One-liner help text shown in the dropdown. */
     description?: string;
+    /** Short status shown in the mode bar's right-hand hint slot while this
+     *  mode is engaged. Defaults to "active" if omitted. Keep it terse — e.g.
+     *  "MITM proxy active". */
+    engagedHint?: string;
     /** Mode ids this mode cannot be active alongside. Two plugins both
      *  needing an exclusive proxy would set each other here. */
     conflictsWith?: string[];
@@ -113,10 +117,29 @@ export interface ModeActivateCtx extends HoverHookCtxBase {
 export interface ModeDeactivateCtx extends HoverHookCtxBase {
     modeId: string;
 }
+/** Fired exactly once when the host service starts, BEFORE the debug Chrome
+ *  is (auto-)launched. A plugin that needs Chrome to be born with specific
+ *  flags — e.g. a resident MITM proxy that Chrome must point through from the
+ *  first navigation — boots that sidecar here and calls setChromeProxy so the
+ *  host bakes the flags into the single Chrome launch. This is what lets the
+ *  security plugin run one always-on (transparent-by-default) proxy instead
+ *  of launching a second Chrome on mode entry. */
+export interface ServiceStartCtx extends HoverHookCtxBase {
+    /** Tell the host "the debug Chrome should be launched with these proxy
+     *  settings". Set once here; persists for the whole session. */
+    setChromeProxy(proxy: {
+        port: number;
+        spki: string;
+    } | null): void;
+    /** Same as the activate-time variant — seed runtime env for a declared MCP
+     *  server before it's spawned. */
+    setMcpServerEnv(id: string, env: Record<string, string>): void;
+}
 /** Fired exactly once when the host service is shutting down for any
  *  reason. Hooks must release subprocesses and file handles. */
 export type ShutdownCtx = HoverHookCtxBase;
 export interface HoverHooks {
+    'hover:service:start'?: (ctx: ServiceStartCtx) => void | Promise<void>;
     'hover:mode:activate'?: (ctx: ModeActivateCtx) => void | Promise<void>;
     'hover:mode:deactivate'?: (ctx: ModeDeactivateCtx) => void | Promise<void>;
     'hover:service:shutdown'?: (ctx: ShutdownCtx) => void | Promise<void>;

package/dist/plugin-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-api.d.ts","sourceRoot":"","sources":["../src/plugin-api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plugin-api.d.ts","sourceRoot":"","sources":["../src/plugin-api.ts"],"names":[],"mappings":"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"}

package/dist/service.d.ts

@@ -18,6 +18,18 @@ export interface ServiceOptions {
      *  pre-plugin Hover" — important for the long tail of users who never
      *  install one. */
     plugins?: HoverPluginManifest[];
+    /** When true, the service launches the single debug Chrome itself at
+     *  startup — AFTER firing plugin `hover:service:start` hooks, so a plugin
+     *  that set a resident proxy (e.g. security's MITM) has its flags baked
+     *  into that one Chrome. Previously each bundler shim called
+     *  launchDebugChrome() directly, which bypassed the service and so couldn't
+     *  see the proxy; moving it here is what enables the single-Chrome model.
+     *  Default false (shims pass it through from their own option). */
+    autoLaunchChrome?: boolean;
+    /** The dev-server URL the auto-launched Chrome should open. Each shim knows
+     *  its own framework's dev URL and passes it here. Defaults to the cdp host
+     *  if unset, but shims should always provide it. */
+    devUrl?: string;
 }
 export interface ServiceHandle {
     /** The port the WebSocketServer actually bound to. May differ from

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AA6EA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;6EAGyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;uBAImB;IACnB,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B;4EACwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAiDD,wBAAsB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAqyB/E"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AA8EA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;6EAGyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;uBAImB;IACnB,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAChC;;;;;;uEAMmE;IACnE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;wDAEoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B;4EACwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAiED,wBAAsB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAs2B/E"}

package/dist/service.js

@@ -54,6 +54,7 @@ import { listAgentAvailability, pickPrimaryAgent, } from './agents/detect.js';
 import { getAgent } from './agents/registry.js';
 import { getPreflight, invalidatePreflight } from './playwright/preflightCache.js';
 import { resolveMcpConfig } from './playwright/resolveMcpConfig.js';
+import { launchDebugChrome } from './playwright/launchChrome.js';
 import { listSkills } from './skills/writeSkill.js';
 import { listSpecs } from './specs/listSpecs.js';
 import { send, sendIfOpen } from './service/types.js';
@@ -65,6 +66,19 @@ import { CURRENT_API_VERSION, } from './plugin-api.js';
 // handler modules can share them. See those files for the wire shape.
 const PROTOCOL_VERSION = 1;
 const PORT_RETRIES = 10;
+/** CJK-presence test — mirrors voice.js's detectLanguage. Any Han character
+ *  in the prompt flips the agent's prose output to Chinese. */
+const CJK_RE = /[一-鿿]/;
+/** Appended to the agent's system prompt when the user's prompt contains CJK,
+ *  so the human-facing prose (verification summary / ## Findings / step
+ *  narration) comes back in Chinese — matching how Voice mode picks a Chinese
+ *  TTS voice for the same prompt. Deliberately scoped to PROSE only: the agent
+ *  must still use the page's real (often English) accessible names, labels,
+ *  and selectors when driving the browser. */
+const ZH_OUTPUT_DIRECTIVE = '用户使用中文下达指令。请用简体中文撰写所有面向用户的文字输出：验证结论摘要、' +
+    '`## Findings` 区块（bug / 问题 / 备注）、以及每一步的中文描述。' +
+    '注意：这只影响你写给用户看的文字。操作浏览器时仍要使用页面真实的（通常是英文的）' +
+    '角色名、标签、可访问名称和选择器——不要把它们翻译成中文。';
 /**
  * Try to bind a WebSocketServer to <host>:<port>. Resolves with the wss on
  * success; rejects with the bind error (typically EADDRINUSE) on failure.
@@ -175,15 +189,11 @@ export async function startService(opts) {
                 }
             }
         }
-        // In an active mode, the Playwright MCP must point at THAT mode's
-        // Chrome (e.g. security mode's 9333), not the default 9222.
-        // effectiveLaunchExtras().cdpPort is the source of truth.
-        const extras = effectiveLaunchExtras();
-        const effectiveCdpUrl = extras?.cdpPort
-            ? `http://localhost:${extras.cdpPort}`
-            : cdpUrl;
+        // Single-Chrome model: the Playwright MCP always points at the one debug
+        // Chrome on the normal cdpUrl. (Pre-single-Chrome this branched to a
+        // mode-specific port like 9333; there's no second Chrome anymore.)
         return resolveMcpConfig({
-            cdpUrl: effectiveCdpUrl,
+            cdpUrl,
             port,
             extra,
             // Suffix the filename by the mode so different mode toggles within
@@ -223,44 +233,31 @@ export async function startService(opts) {
     }
     /** id of the currently-active mode, or null for normal (unmoded) mode. */
     let currentModeId = null;
-    /** Chrome-proxy settings the active mode's activate hook set on us.
-     *  Read by `effectiveLaunchExtras()` and threaded into the cdp handlers
-     *  (check-cdp / launch-chrome / focus-debug) so the secured Chrome on
-     *  9333 actually gets `--proxy-server` + SPKI pin when the user clicks
-     *  Launch from the widget. */
-    let modeChromeProxy = null;
+    /** Chrome-proxy settings a plugin's `hover:service:start` hook set on us
+     *  (security's resident MITM). RESIDENT for the whole session — set once
+     *  before Chrome launches, never cleared on mode change — so the single
+     *  debug Chrome is born with `--proxy-server` + the SPKI pin and entering
+     *  Security mode is just a runtime flip of the proxy, not a Chrome relaunch.
+     *  Read by `effectiveLaunchExtras()` and threaded into every cdp handler
+     *  (check-cdp / launch-chrome / focus-debug) plus the initial auto-launch. */
+    let residentChromeProxy = null;
     /** Runtime env overrides keyed by mcpServer id, set by plugin
      *  activate hooks (via ctx.setMcpServerEnv). Cleared on mode change.
      *  Merged with the manifest-declared env when the agent's spawn-time
      *  MCP config is built. */
     const mcpEnvOverrides = new Map();
-    /** The cdp-handler extras (port, userDataDir, proxy) for the active
-     *  mode's chromeFlags manifest field, or undefined when no mode is
-     *  active. The widget's launch-chrome / check-cdp / focus-debug paths
-     *  all consume these so a Chrome relaunch obeys the mode's needs. */
+    /** The cdp-handler extras (proxy) threaded into launch-chrome / check-cdp /
+     *  focus-debug and the initial auto-launch. In the single-Chrome model this
+     *  is driven purely by the RESIDENT proxy (set in `hover:service:start`),
+     *  NOT by the active mode — there is one Chrome on the normal CDP port that
+     *  is always proxied; entering Security mode flips the proxy's behaviour,
+     *  it does not relaunch Chrome on a different port. Returns undefined when
+     *  no plugin set a resident proxy (the common no-security case), so plain
+     *  Hover is byte-for-byte unchanged. */
     const effectiveLaunchExtras = () => {
-        if (!currentModeId)
+        if (!residentChromeProxy)
             return undefined;
-        const plugin = pluginsByModeId.get(currentModeId);
-        const flags = plugin?.chromeFlags;
-        if (!flags && !modeChromeProxy)
-            return undefined;
-        // Belt + suspenders — flags.activeInModes is honoured if set, but
-        // since chromeFlags lives on the plugin that contributed this mode,
-        // the default of "applies in own mode" matches what we want.
-        if (flags?.activeInModes && !flags.activeInModes.includes('*') && !flags.activeInModes.includes(currentModeId)) {
-            // Plugin explicitly restricted its chromeFlags to a different mode.
-            // Honour that and only carry modeChromeProxy (set by setChromeProxy).
-            return modeChromeProxy ? { proxy: modeChromeProxy } : undefined;
-        }
-        return {
-            cdpPort: flags?.cdpPort,
-            userDataDir: flags?.userDataDir,
-            // modeChromeProxy wins over flags.proxy because it's the runtime
-            // value the activate hook computed (after starting mockttp);
-            // flags.proxy is only ever set by tests stubbing the manifest.
-            proxy: modeChromeProxy ?? flags?.proxy,
-        };
+        return { proxy: residentChromeProxy };
     };
     /** Send the current mode catalogue to one ws (or all if undefined). */
     const broadcastModes = (target) => {
@@ -309,8 +306,14 @@ export async function startService(opts) {
                 }
             }
         }
-        modeChromeProxy = null;
-        mcpEnvOverrides.clear();
+        // NOTE: neither residentChromeProxy NOR mcpEnvOverrides is cleared here.
+        // In the single-Chrome model both are RESIDENT — set once in
+        // service:start (e.g. security's HOVER_SECURITY_API base + token), they
+        // must survive every mode toggle so the agent's spawned MCP server can
+        // always reach the control plane. Clearing them on mode change was the
+        // pre-resident behaviour and would leave the security MCP server with no
+        // env → it exits with "failed". Mode changes now only flip plugin runtime
+        // state via the plugin's own activate/deactivate hooks.
         currentModeId = null;
         // Bring up new mode
         if (newModeId) {
@@ -325,7 +328,10 @@ export async function startService(opts) {
                     broadcast: broadcastPluginEvent,
                     modeId: newModeId,
                     setChromeProxy(proxy) {
-                        modeChromeProxy = proxy;
+                        // Retained for API compatibility. In the single-Chrome model the
+                        // proxy is normally set once in service:start; if an activate hook
+                        // still calls this, treat it as updating the resident proxy.
+                        residentChromeProxy = proxy;
                     },
                     setMcpServerEnv(id, env) {
                         mcpEnvOverrides.set(id, env);
@@ -339,9 +345,10 @@ export async function startService(opts) {
                     // pretend to be in `newModeId` with no sidecars running.
                     // Widget still trusts the broadcast below to learn we're back
                     // to default. The error is rethrown so the caller can surface
-                    // it to the user.
-                    modeChromeProxy = null;
-                    mcpEnvOverrides.clear();
+                    // it to the user. residentChromeProxy and mcpEnvOverrides are NOT
+                    // touched — both are owned by service:start, independent of mode
+                    // activation (clearing the env would break the resident security
+                    // MCP server).
                     currentModeId = null;
                     broadcastModes();
                     throw err;
@@ -694,6 +701,17 @@ export async function startService(opts) {
                         }
                     }
                 }
+                // Mirror the prompt's language in the agent's *prose* output — the
+                // verification summary (Result card), the ## Findings block, and the
+                // step narration — the same way Voice mode mirrors it in TTS. A
+                // Chinese prompt should produce a Chinese report. This does NOT change
+                // how the agent operates the browser: selectors, role names, and the
+                // app's own (often English) UI text are unaffected — only the agent's
+                // human-facing writing follows the user. Detection mirrors voice.js's
+                // detectLanguage (CJK presence → zh).
+                if (CJK_RE.test(text)) {
+                    appendSystemPrompt = `${appendSystemPrompt}\n\n${ZH_OUTPUT_DIRECTIVE}`;
+                }
                 // Snapshot the agent id so a switch-agent message during the run
                 // can't smear two agents across one invocation. (We also gate
                 // switch-agent on `busy`, but defense in depth.)
@@ -844,6 +862,58 @@ export async function startService(opts) {
             }
         });
     });
+    // ───────────────────────── service:start + single Chrome ─────────────────
+    // Fire plugin `hover:service:start` hooks BEFORE launching Chrome, so a
+    // plugin (security) can boot its resident proxy and call setChromeProxy.
+    // residentChromeProxy is then baked into the one auto-launched Chrome.
+    for (const p of plugins) {
+        const hook = p.hooks?.['hover:service:start'];
+        if (!hook)
+            continue;
+        try {
+            await hook({
+                devRoot,
+                broadcast: broadcastPluginEvent,
+                setChromeProxy(proxy) {
+                    residentChromeProxy = proxy;
+                },
+                setMcpServerEnv(id, env) {
+                    mcpEnvOverrides.set(id, env);
+                },
+            });
+        }
+        catch (err) {
+            process.stderr.write(`[hover] plugin "${p.name}" service:start failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+    // Auto-launch the single debug Chrome here (moved out of the bundler shims
+    // so it happens AFTER service:start and can carry residentChromeProxy).
+    // Fire-and-forget — startup must not block on Chrome, and a launch failure
+    // is non-fatal (the widget's amber ✨ lets the user retry on demand).
+    if (opts.autoLaunchChrome) {
+        const launchPort = (() => {
+            try {
+                return Number(new URL(cdpUrl).port) || 9222;
+            }
+            catch {
+                return 9222;
+            }
+        })();
+        const launchUrl = opts.devUrl ?? cdpUrl;
+        launchDebugChrome({
+            url: launchUrl,
+            port: launchPort,
+            proxy: residentChromeProxy ?? undefined,
+        })
+            .then((r) => {
+            if (!r.ok) {
+                process.stderr.write(`[hover] auto-launch Chrome failed: ${r.reason}\n`);
+            }
+        })
+            .catch((err) => {
+            process.stderr.write(`[hover] auto-launch Chrome error: ${err instanceof Error ? err.message : String(err)}\n`);
+        });
+    }
     return {
         port,
         async close() {

package/dist/specs/writeSpec.js

@@ -122,10 +122,19 @@ function renderSpec(slug, displayName, description, steps, assertions) {
             continue;
         const calls = translateStep(s.tool, s.input);
         for (const c of calls) {
+            // Each emitted line gets the test-body indent (2 spaces). Lines
+            // inside an emitInteraction block carry an additional 2 spaces of
+            // relative indent embedded in the line itself, so this single
+            // 2-space prefix produces correct 4-space nesting inside `{ … }`.
             lines.push(`  ${c}`);
             hasAwait = true;
         }
     }
+    // `expect` is imported at the top of the generated file regardless of
+    // whether assertions are present — the visibility preludes emitted by
+    // translateStep depend on it for any element-targeting step. (Cheap:
+    // unused imports get tree-shaken out of any future test bundle, and
+    // Playwright's runner doesn't care.)
     if (assertions.length > 0) {
         if (hasAwait)
             lines.push('');
@@ -152,30 +161,30 @@ function translateStep(tool, rawInput) {
             return [`await page.goto(${JSON.stringify(path)});`];
         }
         case 'browser_click':
-            return [`await ${selectorFromDescription(String(input.element ?? ''))}.click();`];
+            return emitInteraction(selectorFromDescription(String(input.element ?? '')), 'click()');
         case 'browser_double_click':
-            return [`await ${selectorFromDescription(String(input.element ?? ''))}.dblclick();`];
+            return emitInteraction(selectorFromDescription(String(input.element ?? '')), 'dblclick()');
         case 'browser_hover':
-            return [`await ${selectorFromDescription(String(input.element ?? ''))}.hover();`];
+            return emitInteraction(selectorFromDescription(String(input.element ?? '')), 'hover()');
         case 'browser_fill_form': {
             const fields = input.fields ?? [];
-            return fields.map(raw => {
+            return fields.flatMap(raw => {
                 const f = raw;
                 const value = String(f.value ?? '');
                 const target = f.name ?? f.element ?? '';
-                return `await ${selectorForFormField(target, f.type)}.fill(${JSON.stringify(value)});`;
+                return emitInteraction(selectorForFormField(target, f.type), `fill(${JSON.stringify(value)})`);
             });
         }
         case 'browser_type': {
             const text = String(input.text ?? '');
             const target = String(input.element ?? '');
-            return [`await ${selectorFromDescription(target)}.fill(${JSON.stringify(text)});`];
+            return emitInteraction(selectorFromDescription(target), `fill(${JSON.stringify(text)})`);
         }
         case 'browser_select_option': {
             const target = String(input.element ?? '');
             const values = input.values;
             const val = (values && values.length > 0 ? values[0] : input.value) ?? '';
-            return [`await ${selectorFromDescription(target)}.selectOption(${JSON.stringify(String(val))});`];
+            return emitInteraction(selectorFromDescription(target), `selectOption(${JSON.stringify(String(val))})`);
         }
         case 'browser_press_key': {
             const key = String(input.key ?? '');
@@ -197,6 +206,40 @@ function translateStep(tool, rawInput) {
             return [`// TODO: translate ${tool} (skipped — unknown tool for spec emission)`];
     }
 }
+/**
+ * Wrap an interaction (click / dblclick / hover / fill / selectOption) in a
+ * block-scoped visibility prelude. Replaces the prior one-liner emit:
+ *
+ *    // before
+ *    await page.getByRole('button', { name: 'Submit' }).click();
+ *
+ *    // after
+ *    {
+ *      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 before each interaction makes
+ * that drift fail loudly with "Locator expected to be visible" instead of
+ * silently passing or timing out generically. Issue raised externally;
+ * the fix is a 1-emit change here.
+ *
+ * Block-scoped (`{ … }`) so each step's local `el` doesn't shadow the next.
+ * The 4-line shape keeps the diff readable when re-record regenerates a spec.
+ */
+function emitInteraction(selectorExpr, action) {
+    return [
+        `{`,
+        `  const el = ${selectorExpr};`,
+        `  await expect(el).toBeVisible();`,
+        `  await el.${action};`,
+        `}`,
+    ];
+}
 /**
  * Parse element descriptions like "Submit button" / "+1 button" / "Email
  * textbox" / "Plan radio" into `getByRole(role, { name })` selectors. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hover-dev/core",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Hover's local Node service: agent invocation, Playwright CDP preflight, WebSocket bridge.",
   "license": "Apache-2.0",
   "author": "Hyperyond",