@hover-dev/core 0.5.0 → 0.7.0

package/dist/playwright/launchChrome.d.ts

@@ -9,6 +9,18 @@ export interface LaunchOptions {
     readyTimeoutMs?: number;
     /** Poll interval while waiting (default 300ms). */
     pollMs?: number;
+    /** Security-mode proxy config. When provided, Chrome is launched with
+     *  `--proxy-server=127.0.0.1:<proxyPort>` and the given SPKI pinned via
+     *  `--ignore-certificate-errors-spki-list` so HTTPS certs from the
+     *  Hover MITM CA validate without polluting the OS trust store. The
+     *  caller is expected to pick a different `userDataDir` and `port` from
+     *  the normal-mode launch so the two profiles don't share state. */
+    proxy?: {
+        /** Local mockttp port the proxy is listening on. */
+        port: number;
+        /** Base64 SHA-256 of the MITM CA's SubjectPublicKeyInfo. */
+        spki: string;
+    };
 }
 export type LaunchResult = {
     ok: true;

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;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;AAiCD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAwDvF"}
+{"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"}

package/dist/playwright/launchChrome.js

@@ -111,8 +111,11 @@ export async function launchDebugChrome(opts = {}) {
         `--user-data-dir=${userDataDir}`,
         '--no-first-run',
         '--no-default-browser-check',
-        url,
     ];
+    if (opts.proxy) {
+        args.push(`--proxy-server=127.0.0.1:${opts.proxy.port}`, `--ignore-certificate-errors-spki-list=${opts.proxy.spki}`);
+    }
+    args.push(url);
     const child = spawn(chrome, args, {
         detached: true,
         stdio: 'ignore',

package/dist/playwright/resolveMcpConfig.d.ts

@@ -18,10 +18,27 @@
  * which lets multiple Hover services (one per example app) coexist
  * without stepping on each other's CDP endpoint.
  */
+export interface ExtraMcpServer {
+    /** Stable id of the server. Becomes the JSON key under mcpServers; also
+     *  the prefix Claude exposes its tools under (`mcp__<id>__<tool>`). */
+    id: string;
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
 export declare function resolveMcpConfig(opts: {
     /** CDP URL passed to the MCP server's `--cdp-endpoint` flag. */
     cdpUrl: string;
     /** Service port — used to namespace the temp config file. */
     port: number;
+    /** Additional MCP servers contributed by active plugins. Each becomes
+     *  a key under the mcpServers object. The id is also used to name the
+     *  tool prefix Claude exposes (e.g. `mcp__hover_security__list_flows`),
+     *  but Claude sanitises non-alphanumeric chars to underscores, so the
+     *  caller does NOT need to do that. */
+    extra?: ExtraMcpServer[];
+    /** 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;
 }): string;
 //# sourceMappingURL=resolveMcpConfig.d.ts.map

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,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,MAAM,CAsCT"}
+{"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,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;CACjB,GAAG,MAAM,CAgDT"}

package/dist/playwright/resolveMcpConfig.js

@@ -3,26 +3,6 @@ import { mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
 import process from 'node:process';
-/**
- * Resolve a ready-to-use MCP config file path that points at the local
- * `@playwright/mcp` package via an absolute Node-resolved path.
- *
- * Why this exists: Hover originally shipped a static `mcp.config.json`
- * with `"command": "npx", "args": ["-y", "@playwright/mcp@latest", …]`.
- * That meant every `claude -p` invocation kicked off a registry lookup
- * for `@latest` plus a tarball metadata round-trip before the MCP server
- * even started — adding 300 ms - 2 s of dead air to first-token latency
- * on every command (verified via `time npx -y @playwright/mcp@latest`).
- *
- * The fix is to (a) declare `@playwright/mcp` as a real dependency of
- * `@hover-dev/core` so npm resolves it locally at install time, and
- * (b) write a synthetic config file pointing `node <abs-path>/cli.js`
- * at the resolved location. No registry hit on the hot path.
- *
- * The config file is written to `<tmpdir>/hover/mcp-config-<port>.json`,
- * which lets multiple Hover services (one per example app) coexist
- * without stepping on each other's CDP endpoint.
- */
 export function resolveMcpConfig(opts) {
     // Resolve the package's main file, then walk back to its package root.
     // Using `package.json` as the resolution target is the documented
@@ -46,17 +26,27 @@ export function resolveMcpConfig(opts) {
     // 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 config = {
-        mcpServers: {
-            playwright: {
-                command: process.execPath, // current Node binary
-                args: [cliPath, '--cdp-endpoint', opts.cdpUrl],
-            },
+    const mcpServers = {
+        playwright: {
+            command: process.execPath, // current Node binary
+            args: [cliPath, '--cdp-endpoint', opts.cdpUrl],
         },
     };
+    for (const extra of opts.extra ?? []) {
+        // Claude sanitises the key for tool naming; we keep the raw id here
+        // because mcp-config consumers (claude / codex) accept arbitrary
+        // strings and do their own normalisation.
+        mcpServers[extra.id] = {
+            command: extra.command,
+            args: extra.args,
+            env: extra.env,
+        };
+    }
+    const config = { mcpServers };
     const outDir = resolve(tmpdir(), 'hover');
     mkdirSync(outDir, { recursive: true });
-    const outPath = resolve(outDir, `mcp-config-${opts.port}.json`);
+    const suffix = opts.suffix ? `-${opts.suffix}` : '';
+    const outPath = resolve(outDir, `mcp-config-${opts.port}${suffix}.json`);
     writeFileSync(outPath, JSON.stringify(config, null, 2), 'utf-8');
     return outPath;
 }

package/dist/plugin-api.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Hover plugin API — the public contract third-party packages target.
+ *
+ * Plugins are *mostly declarative*: they ship a manifest describing what
+ * resources they contribute (a mode, MCP servers, Chrome flags, agent
+ * prompt fragments, widget event schemas). For genuinely time-bound work
+ * — booting a sidecar like mockttp when a mode activates, tearing it down
+ * when the mode deactivates or the service shuts down — they register
+ * namespaced lifecycle hooks.
+ *
+ * Patterned after Astro Integrations (declarative manifest + namespaced
+ * hooks: `astro:config:setup` etc). The `apiVersion` literal lets us
+ * evolve the manifest and reject mismatched plugins at load time with a
+ * clear error rather than silent breakage.
+ *
+ * Stability:
+ *   - `apiVersion: 1` is what this file declares; breaking changes bump.
+ *   - Adding new optional fields or new hook names is non-breaking.
+ *   - Plugin authors should import only from this module; deep imports
+ *     into `@hover-dev/core` internals are not part of the contract.
+ */
+/**
+ * The Hover plugin API version this build of @hover-dev/core understands.
+ * Plugins declare which version they target via their manifest; mismatches
+ * are rejected at load time.
+ */
+export type HoverApiVersion = 1;
+export declare const CURRENT_API_VERSION: HoverApiVersion;
+export interface HoverPluginMode {
+    /** Globally unique id (across all loaded plugins). Lowercase kebab. */
+    id: string;
+    /** Human-readable label shown in the widget mode-picker. */
+    label: string;
+    /** One-liner help text shown in the dropdown. */
+    description?: string;
+    /** Mode ids this mode cannot be active alongside. Two plugins both
+     *  needing an exclusive proxy would set each other here. */
+    conflictsWith?: string[];
+}
+export interface HoverPluginMcpServer {
+    /** Stable, namespaced id (`@hover-dev/security:flows`). Host enforces
+     *  uniqueness across all loaded plugins. */
+    id: string;
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    /** Modes in which this MCP is exposed to the agent. Default: only the
+     *  plugin's own mode. Use `['*']` to mean "always on". */
+    activeInModes?: string[];
+}
+export interface HoverPluginChromeFlags {
+    /** Extra args appended to the Chrome launch argv. */
+    args?: string[];
+    /** Custom user-data-dir for this mode. Strongly recommended when proxy
+     *  is set, so the secured profile doesn't share cookies with normal mode. */
+    userDataDir?: string;
+    /** Custom CDP port for this mode. Strongly recommended for the same
+     *  reason — keeps the two modes' Chromes addressable independently. */
+    cdpPort?: number;
+    /** When present, Chrome is launched with --proxy-server + the
+     *  --ignore-certificate-errors-spki-list pin so the proxy's MITM CA is
+     *  accepted without polluting the OS trust store. */
+    proxy?: {
+        port: number;
+        spki: string;
+    };
+    /** Modes in which these flags apply. Default: only the plugin's own mode. */
+    activeInModes?: string[];
+}
+export interface HoverPluginSystemPromptAddition {
+    text: string;
+    /** Modes in which this paragraph is included in the agent's system
+     *  prompt. Default: only the plugin's own mode. */
+    activeInModes?: string[];
+}
+export interface HoverBroadcast {
+    /** Push a JSON event to every WebSocket-connected widget. Event `type`
+     *  should be namespaced by the plugin (`security:flow:added`). */
+    (event: {
+        type: string;
+        payload?: unknown;
+    }): void;
+}
+export interface HoverHookCtxBase {
+    /** Absolute path of the user's project root (Vite's `server.config.root`,
+     *  Astro's project dir, etc.). Use this for persisting CA material, not
+     *  process.cwd(). */
+    devRoot: string;
+    /** Push a custom event to every connected widget. */
+    broadcast: HoverBroadcast;
+}
+/** Fired when this plugin's mode becomes active. The plugin may boot
+ *  sidecars (mockttp, profilers, …) here and return any settings that
+ *  affect downstream subsystems (Chrome relaunch, MCP server env vars). */
+export interface ModeActivateCtx extends HoverHookCtxBase {
+    modeId: string;
+    /** Tell the host "Chrome should be relaunched with these proxy settings"
+     *  for the duration of this mode. Pass null to clear. */
+    setChromeProxy(proxy: {
+        port: number;
+        spki: string;
+    } | null): void;
+    /** Set additional env vars on one of this plugin's declared MCP servers.
+     *  The MCP server isn't actually spawned until the agent runs a command,
+     *  so plugins use this in activate() to pass runtime data (port numbers,
+     *  auth tokens) that didn't exist at manifest-construction time.
+     *  Merged on top of any env declared in the manifest; subsequent calls
+     *  for the same id replace previous overrides. */
+    setMcpServerEnv(id: string, env: Record<string, string>): void;
+}
+/** Fired when this plugin's mode is being deactivated. The plugin
+ *  MUST stop any sidecar it started in activate. */
+export interface ModeDeactivateCtx extends HoverHookCtxBase {
+    modeId: string;
+}
+/** 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:mode:activate'?: (ctx: ModeActivateCtx) => void | Promise<void>;
+    'hover:mode:deactivate'?: (ctx: ModeDeactivateCtx) => void | Promise<void>;
+    'hover:service:shutdown'?: (ctx: ShutdownCtx) => void | Promise<void>;
+}
+export interface HoverPluginManifest {
+    /** Always 1 in this build. Future versions may add 2, 3, … */
+    apiVersion: HoverApiVersion;
+    /** Globally unique plugin name. Use the npm package name. */
+    name: string;
+    /** Optional widget mode contributed by this plugin. */
+    mode?: HoverPluginMode;
+    /** Extra MCP servers exposed to the agent in the indicated modes. */
+    mcpServers?: HoverPluginMcpServer[];
+    /** Chrome launch overrides for the indicated modes. */
+    chromeFlags?: HoverPluginChromeFlags;
+    /** System-prompt paragraphs concatenated into the agent's prompt in
+     *  the indicated modes. */
+    systemPromptAdditions?: HoverPluginSystemPromptAddition[];
+    /** Names of custom event types this plugin broadcasts. Documented
+     *  here so the widget side can be tree-shaken to skip handlers for
+     *  events that no loaded plugin will ever produce. */
+    widgetEventTypes?: string[];
+    hooks?: HoverHooks;
+}
+/**
+ * Branded factory that wraps a plugin manifest factory. The wrapper
+ * - asserts `apiVersion` matches this core's version at construction time
+ *   (catches authors who copy-pasted from a tutorial for a different core),
+ * - returns a `(opts) => manifest` so call sites read `securityMode()` /
+ *   `perfMode({ sampleHz: 100 })` uniformly.
+ *
+ * Use:
+ *
+ *   export default defineHoverPlugin<MyOpts>((opts) => ({
+ *     apiVersion: 1,
+ *     name: '@hover-dev/security',
+ *     mode: { id: 'security', label: 'Security testing' },
+ *     ...
+ *   }));
+ */
+export declare function defineHoverPlugin<TOpts = void>(factory: (opts: TOpts) => HoverPluginManifest): (opts: TOpts) => HoverPluginManifest;
+//# sourceMappingURL=plugin-api.d.ts.map

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

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

package/dist/plugin-api.js

@@ -0,0 +1,52 @@
+/**
+ * Hover plugin API — the public contract third-party packages target.
+ *
+ * Plugins are *mostly declarative*: they ship a manifest describing what
+ * resources they contribute (a mode, MCP servers, Chrome flags, agent
+ * prompt fragments, widget event schemas). For genuinely time-bound work
+ * — booting a sidecar like mockttp when a mode activates, tearing it down
+ * when the mode deactivates or the service shuts down — they register
+ * namespaced lifecycle hooks.
+ *
+ * Patterned after Astro Integrations (declarative manifest + namespaced
+ * hooks: `astro:config:setup` etc). The `apiVersion` literal lets us
+ * evolve the manifest and reject mismatched plugins at load time with a
+ * clear error rather than silent breakage.
+ *
+ * Stability:
+ *   - `apiVersion: 1` is what this file declares; breaking changes bump.
+ *   - Adding new optional fields or new hook names is non-breaking.
+ *   - Plugin authors should import only from this module; deep imports
+ *     into `@hover-dev/core` internals are not part of the contract.
+ */
+export const CURRENT_API_VERSION = 1;
+// ──────────────────────────────────────────────────────────────────────
+// Author helper
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * Branded factory that wraps a plugin manifest factory. The wrapper
+ * - asserts `apiVersion` matches this core's version at construction time
+ *   (catches authors who copy-pasted from a tutorial for a different core),
+ * - returns a `(opts) => manifest` so call sites read `securityMode()` /
+ *   `perfMode({ sampleHz: 100 })` uniformly.
+ *
+ * Use:
+ *
+ *   export default defineHoverPlugin<MyOpts>((opts) => ({
+ *     apiVersion: 1,
+ *     name: '@hover-dev/security',
+ *     mode: { id: 'security', label: 'Security testing' },
+ *     ...
+ *   }));
+ */
+export function defineHoverPlugin(factory) {
+    return (opts) => {
+        const manifest = factory(opts);
+        if (manifest.apiVersion !== CURRENT_API_VERSION) {
+            throw new Error(`[hover] plugin "${manifest.name}" targets apiVersion ` +
+                `${String(manifest.apiVersion)} but this Hover supports ` +
+                `${CURRENT_API_VERSION}. Update either the plugin or @hover-dev/core.`);
+        }
+        return manifest;
+    };
+}

package/dist/service/types.d.ts

@@ -32,6 +32,9 @@ export interface ClientMessage {
         pageUrl?: string;
         /** switch-agent only — id of the agent to switch the service to. */
         agentId?: string;
+        /** set-mode only — id of the plugin-contributed mode to activate,
+         *  or null to return to normal (unmoded) operation. */
+        modeId?: string | null;
     };
 }
 export declare function send(ws: WebSocket, message: {

package/dist/service/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/service/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;QACpB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;QAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB;uDAC+C;QAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB;;2DAEmD;QACnD,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,oEAAoE;QACpE,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED,wBAAgB,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAEtF"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/service/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;QACpB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;QAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB;uDAC+C;QAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB;;2DAEmD;QACnD,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,oEAAoE;QACpE,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB;+DACuD;QACvD,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACxB,CAAC;CACH;AAED,wBAAgB,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAEtF"}

package/dist/service.d.ts

@@ -1,3 +1,4 @@
+import { type HoverPluginManifest } from './plugin-api.js';
 export interface ServiceOptions {
     port: number;
     agentId?: string;
@@ -11,6 +12,12 @@ export interface ServiceOptions {
      *  In Vite plugin context, set to `server.config.root` so Claude
      *  auto-discovers skills the user previously saved from this project. */
     devRoot?: string;
+    /** Plugins contributed by the bundler-plugin wrapper. Each manifest can
+     *  add a widget mode, MCP servers, Chrome flags, and lifecycle hooks.
+     *  Empty array (default) means "no plugins, behaviour identical to
+     *  pre-plugin Hover" — important for the long tail of users who never
+     *  install one. */
+    plugins?: HoverPluginManifest[];
 }
 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":"AA+DA,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;CAClB;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,CAiV/E"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAoEA,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,CAknB/E"}

package/dist/service.js

@@ -34,6 +34,12 @@
  *
  *   server → client (in addition to those documented in the file body):
  *     { type: 'agents',        payload: { current: string, available: AgentAvailability[] } }
+ *     { type: 'modes',         payload: { current: string|null, available: ModeEntry[] } }
+ *     { type: '<plugin-namespaced>', payload: <plugin-specific> }
+ *
+ *   client → server (plugin-aware additions):
+ *     { type: 'set-mode',      payload: { modeId: string|null } }   // null = exit moded operation
+ *     { type: 'list-modes' }
  */
 import { WebSocketServer, WebSocket } from 'ws';
 import { invokeAgent } from './agents/invoke.js';
@@ -46,6 +52,7 @@ import { send } from './service/types.js';
 import { buildCdpHint, buildCdpHintResume } from './service/cdpHint.js';
 import { handleCheckCdp, handleLaunchChrome, handleFocusDebug, } from './service/cdpHandlers.js';
 import { handleSaveArtifact, SKILL_CONFIG, SPEC_CONFIG, CASE_CSV_CONFIG, } from './service/saveHandlers.js';
+import { CURRENT_API_VERSION, } from './plugin-api.js';
 // ClientMessage + send moved to ./service/types.ts so the cdp + save
 // handler modules can share them. See those files for the wire shape.
 const PROTOCOL_VERSION = 1;
@@ -122,15 +129,168 @@ export async function startService(opts) {
     const devRoot = opts.devRoot ?? process.cwd();
     const wss = await pickAndBind('127.0.0.1', requestedPort, PORT_RETRIES);
     const port = wss.address().port;
-    // Resolve a CDP-pinned MCP config pointing at our local
-    // `@playwright/mcp` install. See resolveMcpConfig.ts for the rationale
-    // (avoids `npx -y @playwright/mcp@latest`'s registry round-trip on
-    // every command — 300 ms - 2 s of hot-path latency).
-    const mcpConfig = opts.mcpConfig ?? resolveMcpConfig({ cdpUrl, port });
+    // Build a fresh MCP config per command, so the currently-active mode's
+    // contributed servers (plus runtime env from setMcpServerEnv) land in
+    // the file the agent reads. `opts.mcpConfig` still wins if the host
+    // forced an explicit one, but in that case mode-contributed servers
+    // are silently dropped — we log a warning the first time it happens.
+    let warnedExplicitMcpOverride = false;
+    const buildMcpConfig = () => {
+        if (opts.mcpConfig) {
+            const activePlugin = currentModeId ? pluginsByModeId.get(currentModeId) : null;
+            if (activePlugin?.mcpServers?.length && !warnedExplicitMcpOverride) {
+                process.stderr.write(`[hover] explicit opts.mcpConfig overrides plugin-contributed MCP servers ` +
+                    `(plugin "${activePlugin.name}" wanted ${activePlugin.mcpServers
+                        .map((s) => s.id)
+                        .join(', ')}).\n`);
+                warnedExplicitMcpOverride = true;
+            }
+            return opts.mcpConfig;
+        }
+        const extra = [];
+        if (currentModeId) {
+            for (const p of plugins) {
+                for (const srv of p.mcpServers ?? []) {
+                    const scope = srv.activeInModes ?? (p.mode ? [p.mode.id] : []);
+                    const inMode = scope.includes('*') || scope.includes(currentModeId);
+                    if (!inMode)
+                        continue;
+                    extra.push({
+                        id: srv.id,
+                        command: srv.command,
+                        args: srv.args,
+                        env: {
+                            ...(srv.env ?? {}),
+                            ...(mcpEnvOverrides.get(srv.id) ?? {}),
+                        },
+                    });
+                }
+            }
+        }
+        return resolveMcpConfig({
+            cdpUrl,
+            port,
+            extra,
+            // Suffix the filename by the mode so different mode toggles within
+            // one service produce distinct config files (debugging aid).
+            suffix: currentModeId ?? undefined,
+        });
+    };
     // Surface post-listen errors instead of crashing the host process.
     wss.on('error', err => {
         process.stderr.write(`[hover] WebSocketServer error: ${err.message}\n`);
     });
+    // ──────────────────────────────────────────────────────────────────
+    // Plugin registry
+    // ──────────────────────────────────────────────────────────────────
+    // Validate + index plugins once at startup. Reasons we fail loud here
+    // (rather than at first use): mode-id collisions are a configuration
+    // bug, not a runtime one — the widget mode-picker would silently miss
+    // entries, which is worse than a startup error the user has to fix.
+    const plugins = opts.plugins ?? [];
+    const pluginsByName = new Map();
+    const pluginsByModeId = new Map();
+    for (const p of plugins) {
+        if (p.apiVersion !== CURRENT_API_VERSION) {
+            throw new Error(`[hover] plugin "${p.name}" targets apiVersion ${String(p.apiVersion)} but this Hover supports ${CURRENT_API_VERSION}.`);
+        }
+        if (pluginsByName.has(p.name)) {
+            throw new Error(`[hover] duplicate plugin name: ${p.name}`);
+        }
+        pluginsByName.set(p.name, p);
+        if (p.mode) {
+            if (pluginsByModeId.has(p.mode.id)) {
+                throw new Error(`[hover] two plugins contribute the same mode id "${p.mode.id}": ` +
+                    `${pluginsByModeId.get(p.mode.id)?.name} and ${p.name}`);
+            }
+            pluginsByModeId.set(p.mode.id, p);
+        }
+    }
+    /** 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.
+     *  Surfaced to launchDebugChrome calls when the widget asks us to
+     *  launch a debug Chrome. */
+    let modeChromeProxy = 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();
+    /** Send the current mode catalogue to one ws (or all if undefined). */
+    const broadcastModes = (target) => {
+        const available = plugins
+            .filter((p) => Boolean(p.mode))
+            .map((p) => ({
+            id: p.mode.id,
+            label: p.mode.label,
+            description: p.mode.description,
+            pluginName: p.name,
+        }));
+        const payload = { current: currentModeId, available };
+        const targets = target ? [target] : [...wss.clients];
+        for (const client of targets) {
+            if (client.readyState === WebSocket.OPEN) {
+                send(client, { type: 'modes', payload });
+            }
+        }
+    };
+    /** Broadcast helper passed to plugin hooks. Plugin-side events should
+     *  be namespaced ("security:flow:added") to avoid collisions with
+     *  core's protocol vocabulary. */
+    const broadcastPluginEvent = (event) => {
+        for (const client of wss.clients) {
+            if (client.readyState === WebSocket.OPEN) {
+                send(client, event);
+            }
+        }
+    };
+    const switchMode = async (newModeId) => {
+        if (newModeId === currentModeId)
+            return;
+        // Tear down old mode
+        if (currentModeId) {
+            const old = pluginsByModeId.get(currentModeId);
+            if (old?.hooks?.['hover:mode:deactivate']) {
+                try {
+                    await old.hooks['hover:mode:deactivate']({
+                        devRoot,
+                        broadcast: broadcastPluginEvent,
+                        modeId: currentModeId,
+                    });
+                }
+                catch (err) {
+                    process.stderr.write(`[hover] plugin "${old.name}" deactivate failed: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+            }
+        }
+        modeChromeProxy = null;
+        mcpEnvOverrides.clear();
+        currentModeId = null;
+        // Bring up new mode
+        if (newModeId) {
+            const next = pluginsByModeId.get(newModeId);
+            if (!next) {
+                throw new Error(`[hover] unknown modeId "${newModeId}"`);
+            }
+            currentModeId = newModeId;
+            if (next.hooks?.['hover:mode:activate']) {
+                const ctx = {
+                    devRoot,
+                    broadcast: broadcastPluginEvent,
+                    modeId: newModeId,
+                    setChromeProxy(proxy) {
+                        modeChromeProxy = proxy;
+                    },
+                    setMcpServerEnv(id, env) {
+                        mcpEnvOverrides.set(id, env);
+                    },
+                };
+                await next.hooks['hover:mode:activate'](ctx);
+            }
+        }
+        broadcastModes();
+    };
     // Cache the agent-availability list. The PATH scan is cheap (one `which`
     // per registered agent) but we still don't want to re-run it on every
     // hello; a single Vite dev server typically sees the widget connect and
@@ -165,6 +325,9 @@ export async function startService(opts) {
         void getAvailability(false).then(available => {
             send(ws, { type: 'agents', payload: { current: currentAgentId, available } });
         });
+        // Send the mode catalogue too, so the widget can render the mode
+        // toggle immediately. Empty list when no plugins are loaded.
+        broadcastModes(ws);
         let busy = false;
         let inflight = null;
         let cancelled = false;
@@ -210,6 +373,46 @@ export async function startService(opts) {
                 cancel();
                 return;
             }
+            if (msg.type === 'list-modes') {
+                broadcastModes(ws);
+                return;
+            }
+            if (msg.type === 'set-mode') {
+                if (busy) {
+                    send(ws, {
+                        type: 'error',
+                        payload: { message: 'set-mode: a command is already running; stop it first' },
+                    });
+                    return;
+                }
+                const wanted = msg.payload?.modeId ?? null;
+                if (wanted !== null && typeof wanted !== 'string') {
+                    send(ws, {
+                        type: 'error',
+                        payload: { message: 'set-mode: modeId must be a string or null' },
+                    });
+                    return;
+                }
+                if (wanted !== null && !pluginsByModeId.has(wanted)) {
+                    send(ws, {
+                        type: 'error',
+                        payload: { message: `set-mode: unknown modeId "${wanted}"` },
+                    });
+                    return;
+                }
+                try {
+                    await switchMode(wanted);
+                }
+                catch (err) {
+                    send(ws, {
+                        type: 'error',
+                        payload: {
+                            message: `set-mode failed: ${err instanceof Error ? err.message : String(err)}`,
+                        },
+                    });
+                }
+                return;
+            }
             if (msg.type === 'list-agents') {
                 // Force a refresh — the user may have just installed a new CLI
                 // and clicked the dropdown to see the change.
@@ -300,6 +503,11 @@ export async function startService(opts) {
             cancelled = false;
             inflight = new AbortController();
             try {
+                // Build the MCP config first — it's pure local file IO and lets
+                // us assert plugin-contributed servers landed in the config even
+                // when CDP preflight subsequently fails (useful for smoke tests
+                // that don't have a real debug Chrome wired up).
+                const mcpConfig = buildMcpConfig();
                 // Preflight: refuse to invoke if CDP isn't reachable. Otherwise the
                 // Playwright MCP server would silently launch its own Chromium —
                 // and Hover's premise is to drive the user's existing Chrome (with
@@ -328,9 +536,25 @@ export async function startService(opts) {
                 // re-sending them fragments Anthropic's prompt-cache fingerprint
                 // (cache hits require byte-identical system prompts across turns).
                 // See cdpHint.ts for the why.
-                const appendSystemPrompt = resumeSessionId
+                let appendSystemPrompt = resumeSessionId
                     ? buildCdpHintResume(cdp.tabs)
                     : buildCdpHint(cdp.tabs);
+                // Add the active mode's plugin prompt additions, if any. We only
+                // include additions whose `activeInModes` is the current mode or
+                // '*' (always-on); plugins that contribute prompts but no mode
+                // are treated as mode-scoped to their own plugin's mode by
+                // default (handled by the empty activeInModes case below).
+                const activePlugin = currentModeId ? pluginsByModeId.get(currentModeId) : null;
+                if (activePlugin?.systemPromptAdditions) {
+                    for (const add of activePlugin.systemPromptAdditions) {
+                        const inMode = !add.activeInModes ||
+                            add.activeInModes.includes('*') ||
+                            (currentModeId !== null && add.activeInModes.includes(currentModeId));
+                        if (inMode) {
+                            appendSystemPrompt = `${appendSystemPrompt}\n\n${add.text}`;
+                        }
+                    }
+                }
                 // 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.)
@@ -343,6 +567,25 @@ export async function startService(opts) {
                 // a soft one gets nothing and relies on its descriptor's built-in
                 // sandbox flags + developer_instructions.
                 const isHardSandbox = invokedDescriptor?.sandboxStrength === 'hard';
+                // Active mode's plugin-contributed MCP server ids — added to the
+                // hard-sandbox allow list so Claude can actually call them. Claude
+                // sanitises non-alphanumeric chars in the id when forming tool
+                // names (e.g. "@hover-dev/security:flows" → "mcp__hover_dev_security_flows"),
+                // and `--allowedTools mcp__foo` matches every tool under that
+                // prefix. We pass the prefix `mcp__<sanitized>` so all of the
+                // server's tools are reachable.
+                const sanitize = (s) => s.replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+                const activePluginMcpIds = [];
+                if (currentModeId) {
+                    for (const p of plugins) {
+                        for (const srv of p.mcpServers ?? []) {
+                            const scope = srv.activeInModes ?? (p.mode ? [p.mode.id] : []);
+                            if (scope.includes('*') || scope.includes(currentModeId)) {
+                                activePluginMcpIds.push(`mcp__${sanitize(srv.id)}`);
+                            }
+                        }
+                    }
+                }
                 for await (const ev of invokeAgent({
                     agentId: invokedAgentId,
                     prompt: text,
@@ -354,8 +597,11 @@ export async function startService(opts) {
                     appendSystemPrompt,
                     // Skill stays in the allow list so saved skills under
                     // <devRoot>/.claude/skills/ can be invoked. mcp__playwright covers
-                    // every browser tool.
-                    allowedTools: isHardSandbox ? ['mcp__playwright', 'Skill'] : undefined,
+                    // every browser tool. Plugin-contributed MCPs are appended when
+                    // the corresponding mode is active.
+                    allowedTools: isHardSandbox
+                        ? ['mcp__playwright', 'Skill', ...activePluginMcpIds]
+                        : undefined,
                     disallowedTools: isHardSandbox
                         ? [
                             // file / shell / data access — never appropriate for browser driving
@@ -409,8 +655,34 @@ export async function startService(opts) {
     });
     return {
         port,
-        close: () => new Promise((res, rej) => {
-            wss.close(err => (err ? rej(err) : res()));
-        }),
+        async close() {
+            // Deactivate the active mode first, then run every plugin's
+            // shutdown hook (regardless of which mode is active — a plugin may
+            // own background state even outside its mode). Best-effort: log
+            // and continue on individual failures so one buggy plugin doesn't
+            // strand the others' sidecars.
+            if (currentModeId) {
+                try {
+                    await switchMode(null);
+                }
+                catch (err) {
+                    process.stderr.write(`[hover] error deactivating mode during shutdown: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+            }
+            for (const p of plugins) {
+                const hook = p.hooks?.['hover:service:shutdown'];
+                if (!hook)
+                    continue;
+                try {
+                    await hook({ devRoot, broadcast: broadcastPluginEvent });
+                }
+                catch (err) {
+                    process.stderr.write(`[hover] plugin "${p.name}" shutdown failed: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+            }
+            await new Promise((res, rej) => {
+                wss.close(err => (err ? rej(err) : res()));
+            });
+        },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hover-dev/core",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Hover's local Node service: agent invocation, Playwright CDP preflight, WebSocket bridge.",
   "license": "Apache-2.0",
   "author": "Hyperyond",
@@ -38,6 +38,10 @@
     "./launch-chrome": {
       "types": "./dist/playwright/launchChrome.d.ts",
       "import": "./dist/playwright/launchChrome.js"
+    },
+    "./plugin-api": {
+      "types": "./dist/plugin-api.d.ts",
+      "import": "./dist/plugin-api.js"
     }
   },
   "files": [