qiksy-mcp 0.1.0 → 1.0.7

package/README.md

@@ -2,7 +2,9 @@
 
 An **MCP (Model Context Protocol) bridge** for the [Qiksy](../) browser extension. It lets any MCP-capable coding agent — **Claude Code, Cursor, Cline, Windsurf, Zed, VS Code** — read the live QA state (findings with CSS selectors, detected forms, failed requests with server error bodies, recorded repro steps) straight from the browser, so you can say *"fix what Qiksy found on this page"* and the agent has the full context.
 
-The agent can also **drive Qiksy's own surfaces**: open the panel, run the audit, pull the exploratory-tour checklist, generate the session report, and spotlight an element. What it **never** does is act on the **app under test** — no filling, clicking, submitting, or navigating the page you're testing. Qiksy senses and reports; a human (or a purpose-built driver like [Playwright MCP](#driving-the-browser-pair-with-playwright-mcp)) does the driving. This boundary is deliberate — it's what keeps a QA tool that watches *other people's* apps trustworthy.
+The agent can also **drive Qiksy's own surfaces**: open the panel, run the audit, pull the exploratory-tour checklist, generate the session report, and spotlight an element.
+
+By default it stops there — it does **not** fill, click, submit or navigate the app you're testing. Qiksy senses and reports; you drive. **Agent control** (Pro, off until you switch it on and confirm a prompt of its own) is the deliberate exception: it lets the agent act inside the session you are *already logged into*, which is the whole reason to use this rather than a cold automated browser. The default posture is unchanged — that boundary is what keeps a tool that watches *other people's* apps trustworthy — but a professional can move it knowingly.
 
 ## How it works
 
@@ -12,9 +14,23 @@ agent  ⟷ (MCP over stdio, JSON-RPC)  ⟷  qiksy-mcp  ⟷ (WebSocket @ 127.0.0.
 
 The extension is the WebSocket **client** (a service worker can't listen on a socket); this process is the WebSocket **server**, bound to loopback only. When the agent calls a tool, this process asks the extension for the current tab's `qa-export/v1` bundle and returns it.
 
+## Two things to know before you wire it up
+
+**The bridge as a whole is a Pro surface.** Inside the extension the free tier stays
+fully usable, but the socket itself is gated: `ensureConnected()` refuses to dial
+unless the licence (or the 14-day trial) is valid, so once a trial lapses *every*
+tool fails — `qa_export` included — with a message saying so. Do not plan a
+free-tier integration around read-only tools.
+
+**npm carries `qiksy-mcp@1.0.6`** — the current build, versioned in lockstep with
+the extension, with all sixteen tools including Agent control (`qa_click`,
+`qa_type`, `qa_press`, `qa_navigate`, `qa_open_isolated`, `qa_close_tab`). Just
+`npx qiksy-mcp` — no clone, no local path. (For hacking on the bridge itself, see
+**Local run** at the bottom.)
+
 ## Tools
 
-**Read** — sense the page (all accept an optional `tabId` from `qa_tabs`; default = active tab):
+Sixteen in total. **Read** — sense the page (all accept an optional `tabId` from `qa_tabs`; default = active tab):
 
 | Tool          | What it returns |
 |---------------|-----------------|
@@ -35,9 +51,40 @@ The extension is the WebSocket **client** (a service worker can't listen on a so
 
 Because tools accept a `tabId`, an agent can read **several logins at once**: call `qa_tabs`, then `qa_export` per isolated tab to compare what admin vs. member vs. anon each see.
 
-## Driving the browser: pair with Playwright MCP
+**Agent control (Pro)** — these ACT on the app under test:
+
+| Tool       | What it does |
+|------------|--------------|
+| `qa_click` | Click an element by CSS selector. Sends the full pointer sequence (`pointerdown` → `mouseup` → `click`), so Radix/shadcn/MUI components that listen for `pointerdown` react like they would to a real click. Scrolls into view first; refuses a selector that matches nothing or has zero size instead of silently doing nothing. |
+| `qa_type`  | Set an input / textarea / contenteditable value using the native setter + `InputEvent`, so React and Vue controlled inputs keep it (a plain assignment is swallowed). Reports `stuck: false` when the field rejected the value — masked, read-only or controlled. |
+| `qa_press` | Dispatch a key (`Enter`, `Escape`, `Tab`, …). Without a selector it goes to the focused element, like a real keyboard. |
+
+**Chaining** — what makes a multi-page, multi-role run reliable:
+
+| Tool               | What it does |
+|--------------------|--------------|
+| `qa_wait_ready`    | **Free.** Block until the tab finished loading AND a fresh Qiksy answers in the new document. Call it after anything that navigates — a submit, a link click, `qa_navigate` — before the next `qa_type`/`qa_click`, or the call lands on a page still being replaced. `timeoutMs` default 15000, max 60000. |
+| `qa_navigate`      | Point a tab at a URL and wait for that same ready signal (built in). |
+| `qa_open_isolated` | Open one or MANY tabs, each with its own private session — `sessions: ["admin","manager","member","viewer"]` or `count: N` (max 12). Returns a `tabId` per login; pass it to any tool to run the whole flow as that user. **Also needs the multi-login confirmation**, because it intercepts the site's cookies — a separate acknowledgement from Agent control. |
+| `qa_close_tab`     | Close one tab (`tabId`) or a batch (`tabIds`) — how you tidy up after a role matrix. |
+
+Three independent gates, re-checked on **every** call, all inside the extension where the server cannot bypass them:
+
+1. a **Pro** licence (or the trial) — note this is *also* what the socket itself requires, so on the bridge nothing is free once a trial lapses;
+2. the **`drive` consent**, granted separately from the bridge's own (Qiksy panel → Tools → **Agent control**) and revoked when you switch it off, so the warning is faced again next time;
+3. the bridge itself — loopback only, shared token, off by default.
+
+Fail either of the first two and the call returns `pro-required` / `consent-required` and does nothing. **It acts for real**: it can submit, spend and delete under your live login, with no undo. Point it at test environments.
+
+## Driving the browser: Agent control, or pair with Playwright MCP
+
+Qiksy is the **QA brain** (what happened, what's wrong, coverage, reports). Two ways to give an agent hands:
 
-Qiksy is the **QA brain** (what happened, what's wrong, coverage, reports). It does **not** click through the app for you. To let an agent also *drive* the browser, run a purpose-built driver alongside it — e.g. [Playwright MCP](https://github.com/microsoft/playwright-mcp) — and register **both** servers in your agent:
+**Agent control (Pro)** drives the browser *you are already using* — the session you logged into by hand, including isolated multi-login tabs. Nothing to launch, no second browser, no re-authentication. Best when the app is behind SSO/MFA or the state is painful to reproduce from cold.
+
+**[Playwright MCP](https://github.com/microsoft/playwright-mcp)** drives a browser *it* launches, and is the mature, dedicated tool for repeatable automation: waits, assertions, tracing, parallel contexts, CI. Best when the run must be reproducible from scratch.
+
+They compose — Playwright can attach over CDP to the very browser Qiksy runs in, so the agent drives with one and *sees* with the other:
 
 ```
 your agent
@@ -52,7 +99,9 @@ your agent
 3. After each step it calls **qiksy-mcp** (`qa_export`, `qa_run_audit`, `qa_findings`) to see what *actually* happened — console/JS errors, failed requests **with server bodies**, a11y/markup issues, the detected form structure.
 4. The agent reconciles the story against reality, then writes test cases (using `qa_tour` for coverage) and, if History was recording, pulls a `qa_report` as the artifact.
 
-Why not build driving into Qiksy itself? Playwright is a mature, dedicated driver, and keeping Qiksy read-and-report keeps its trust/permissions story clean. (Embedding Playwright *inside* the extension isn't possible anyway — it's an external Node automation framework, not something an MV3 extension can host.)
+**Which to reach for.** Measured on the same page and question ("what forms are here with selectors, and what is broken?"): `qa_export` answers in **~9 ms** from an already-open tab, against **~2.5 s** for Playwright from a cold start — but that gap is almost entirely browser launch. With both browsers already up it is ~9 ms vs ~28 ms for an equivalent DOM scrape: the same order. The reason to use Qiksy is not raw speed, it is that the 9 ms carries *meaning* — `kind: "first-name"`, the label, `required`, `maxLength`, plus findings, failed requests with server bodies and repro steps in the same payload. A scrape returns raw DOM and leaves the agent to work out what each field is; matching the rest needs more code and a reload to attach console listeners before load.
+
+So: **Playwright when the run must be reproducible from cold. Agent control when the value is the live, already-authenticated session.** Reading is worth doing through Qiksy either way.
 
 ### Wiring both servers (Playwright MCP needs a CDP browser)
 
@@ -65,7 +114,7 @@ Playwright MCP drives a browser over the **Chrome DevTools Protocol** — a *nor
    # Windows:  "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
    # Linux:    google-chrome --remote-debugging-port=9222
    ```
-2. **In the Qiksy popup** → *MCP bridge*: **On**, **Generate** a token, **Save**.
+2. **In the Qiksy popup** → *Agent bridge*: **On**, **Generate** a token (it saves as you go), then **📋 Copy agent config**.
 3. **Register both MCP servers** in your agent — one config, paste and go. Claude Code `.mcp.json` (project root):
    ```json
    {
@@ -94,11 +143,37 @@ Qiksy runs several logins on one domain at once — one per tab, each with its o
 
 ## Setup
 
-1. **In the extension popup** → *MCP bridge*: toggle **On**, click **Generate** for a token, pick a port (default `7333`), **Save bridge**.
-2. **Register the server in your agent** (below), using the **same token and port**. The token is passed via the `QIKSY_MCP_TOKEN` env var.
+1. **In the extension popup** → *Agent bridge*: toggle **On**, click **Generate** for a token, keep the default port `7333` (or pick your own). It **saves as you go** — there is no separate Save step.
+2. **Click 📋 Copy agent config** in the popup — it copies the whole `mcpServers` block below with **your port and token already filled in** — and paste it into your agent's MCP config file (below). No hand-editing the token or port.
+3. **Watch the status line** under the toggle. 🟡 *Waiting…* until your agent's `qiksy-mcp` is up, then 🟢 *Agent connected on port 7333*. If it stays yellow or turns red, see [Connection status & troubleshooting](#connection-status--troubleshooting).
 
 The token is the only thing guarding the bridge — localhost is reachable by any local process/page, so keep it secret and unique.
 
+### Connection status & troubleshooting
+
+The popup shows the live link state, so you fix the right thing instead of guessing:
+
+| Status | Means | Fix |
+|--------|-------|-----|
+| 🟢 **Agent connected** | Socket open on that port, token matched. | Nothing — you're live. |
+| 🟡 **Waiting for the agent** | Bridge on, but nothing answering on that port. | Start your agent so `qiksy-mcp` runs, and make sure **its `--port` matches the popup's port**. The #1 snag: docs pin `7333` but the agent was launched on a different port — the numbers must match. |
+| 🔴 **Token rejected** | Something answered, but the shared secret didn't match. | The popup token and the agent's `QIKSY_MCP_TOKEN` must be identical. Re-copy with **📋 Copy agent config** and repaste. |
+| 🔴 **Another browser took over** | A second browser connected on the same port+token and claimed the slot. | Expected when switching browsers. To run **both at once**, give each its own port (see below). To reclaim, toggle the bridge **off then on**. |
+| 🔴 **Qiksy Pro required** | Trial ended; the bridge is a Pro surface. | Activate a license key in the popup. |
+
+### Two browsers at once
+
+One bridge is **one port + one token = one browser**. Pointing a second browser at the **same** port+token doesn't double up — it **takes over the slot** (last writer wins), and the first browser's status flips to *Another browser took over*. That's exactly how you **switch** between browsers. To run **both simultaneously**, give each its own port and register a second server name:
+
+```json
+{ "mcpServers": {
+  "qiksy":   { "command": "npx", "args": ["qiksy-mcp", "--port", "7333"], "env": { "QIKSY_MCP_TOKEN": "TOKEN_A" } },
+  "qiksy-2": { "command": "npx", "args": ["qiksy-mcp", "--port", "7334"], "env": { "QIKSY_MCP_TOKEN": "TOKEN_B" } }
+} }
+```
+
+Set browser A's popup to `7333`/`TOKEN_A` and browser B's to `7334`/`TOKEN_B`. One agent drives one browser per bridge — a single bridge can't fan out to two browsers; different ports are independent links that never fight over the slot.
+
 ### Claude Code
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qiksy-mcp",
-  "version": "0.1.0",
+  "version": "1.0.7",
   "description": "MCP bridge for the Qiksy browser extension — expose live QA findings, forms, network and session to any MCP-capable coding agent.",
   "type": "module",
   "bin": {

package/server.mjs

@@ -26,9 +26,91 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { WebSocketServer, WebSocket } from 'ws';
 import { z } from 'zod';
 import { randomUUID, timingSafeEqual } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 
 const log = (...a) => console.error('[qiksy-mcp]', ...a);
 
+// A little IT/QA humour in the STDERR log (never in tool results — the agent parses
+// those). It rides the connect line and each action, to make a testing session a bit
+// more fun. Set QIKSY_MCP_QUIPS=0 to keep the log strictly business (CI, demos).
+const QUIPS_ON = process.env.QIKSY_MCP_QUIPS !== '0';
+const QUIPS = [
+  'it works on my machine ✨',
+  "it's not a bug, it's a feature",
+  'no bugs — only undocumented features',
+  'have you tried turning it off and on again?',
+  'shipping it 🚀',
+  'passed on the third retry 🟢',
+  'flaky test? must be the network',
+  'reproduced locally, naturally',
+  'works 60% of the time, every time',
+  "trust me, I'm a QA engineer",
+  '0 bugs found (that we know of)',
+  'definitely tested in production',
+  'green tests, clear conscience',
+  'clicking so you don\'t have to',
+  'one does not simply skip QA',
+  'red, green, refactor, repeat',
+  'escalating to the rubber duck 🦆',
+  'edge case #418: I\'m a teapot',
+  'the build is fine, it\'s the vibes that are off',
+  'QA: because prod is not a test environment',
+];
+let lastQuip = -1;
+function quip() {
+  if (!QUIPS_ON) return '';
+  let i;
+  do {
+    i = Math.floor(Math.random() * QUIPS.length);
+  } while (QUIPS.length > 1 && i === lastQuip);
+  lastQuip = i;
+  return QUIPS[i];
+}
+
+// Little ASCII faces / kaomoji to ride along with the quips — sticks, circles, meme
+// faces. Same QIKSY_MCP_QUIPS gate.
+const FACES = [
+  '¯\\_(ツ)_/¯',
+  '(⌐■_■)',
+  '( •_•)>⌐■-■',
+  'ᕕ( ᐛ )ᕗ',
+  '(づ｡◕‿‿◕｡)づ',
+  'ヽ(´▽`)/',
+  '(ノ◕ヮ◕)ノ*:･ﾟ✧',
+  '◉_◉',
+  '(•_•)',
+  '༼ つ ◕_◕ ༽つ',
+  '~(˘▾˘~)',
+  '(☞ﾟヮﾟ)☞',
+  '[▰▰▰▱▱]',
+  'ᕦ(ò_óˇ)ᕤ',
+  '(◕‿◕)',
+];
+// A happier subset for the connect banner (no table-flips when things just worked).
+const HAPPY = ['\\(^o^)/', 'ヽ(´▽`)/', '(ノ◕ヮ◕)ノ*:･ﾟ✧', 'ᕕ( ᐛ )ᕗ', '(づ｡◕‿‿◕｡)づ', '~(˘▾˘~)'];
+let lastFace = -1;
+function face(happy = false) {
+  if (!QUIPS_ON) return '';
+  const pool = happy ? HAPPY : FACES;
+  let i;
+  do {
+    i = Math.floor(Math.random() * pool.length);
+  } while (pool.length > 1 && i === lastFace);
+  lastFace = i;
+  return pool[i];
+}
+
+// Read the version off package.json rather than repeating it here — a hardcoded
+// copy silently rots, and this one is what every MCP client displays.
+const VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(fileURLToPath(new URL('./package.json', import.meta.url)), 'utf8')).version;
+  } catch {
+    return '0.0.0';
+  }
+})();
+
 const TOKEN = process.env.QIKSY_MCP_TOKEN || '';
 const portArg = process.argv.indexOf('--port');
 const PORT = portArg !== -1 ? Number(process.argv[portArg + 1]) : Number(process.env.QIKSY_MCP_PORT) || 7333;
@@ -50,6 +132,9 @@ function tokenOk(got) {
 
 // ── WebSocket bridge to the extension ──────────────────────────────────────
 let client = null; // the one authenticated extension socket
+// Set when the extension checked in only to report an expired licence — turns the
+// generic 'not connected' into the actual reason.
+let lapsed = false;
 const pending = new Map(); // id → { resolve, reject, timer }
 
 const wss = new WebSocketServer({ host: HOST, port: PORT });
@@ -81,11 +166,36 @@ wss.on('connection', (ws, req) => {
         ws.close(4001, 'auth failed');
         return;
       }
-      authed = true;
       clearTimeout(helloTimer);
+      // The extension dials in ONLY to say its licence lapsed, then hangs up. It
+      // is not a client — remember the reason so every tool call answers with a
+      // sentence a human can act on, instead of the generic "not connected",
+      // which reads like a broken port or a bad token and sends people digging
+      // in the wrong place.
+      if (msg.lapsed) {
+        lapsed = true;
+        log('extension reports a lapsed licence — bridge stays closed');
+        ws.close(4002, 'lapsed');
+        return;
+      }
+      authed = true;
+      lapsed = false;
+      // Last-writer-wins, but EXPLICITLY. If another browser already holds the one
+      // client slot, close it with a distinct code (4004) instead of silently
+      // orphaning it — so its extension can say "another browser took over" rather
+      // than going dark, and (crucially) so it YIELDS instead of instantly
+      // reconnecting and starting a slot-stealing war. Two browsers at once = two
+      // bridge instances on two ports, not one shared slot.
+      if (client && client !== ws && client.readyState === WebSocket.OPEN) {
+        try {
+          client.close(4004, 'replaced by a newer connection');
+        } catch {
+          /* already gone */
+        }
+      }
       client = ws;
       ws.send(JSON.stringify({ t: 'welcome', v: PROTOCOL_VERSION }));
-      log('extension connected');
+      log(QUIPS_ON ? `${face(true)}  extension connected — ${quip()}` : 'extension connected');
       return;
     }
     if (msg.t === 'ping') {
@@ -113,7 +223,15 @@ wss.on('connection', (ws, req) => {
 function callExtension(tool, args, timeoutMs = 15_000) {
   return new Promise((resolve, reject) => {
     if (!client || client.readyState !== WebSocket.OPEN) {
-      reject(new Error('Qiksy extension is not connected. Open Chrome with the extension and enable the MCP bridge in its popup (matching token & port).'));
+      reject(
+        new Error(
+          lapsed
+            ? 'Your Qiksy trial has ended, so the bridge is closed — I cannot read or drive the browser until it is renewed. ' +
+              'Open the Qiksy popup in Chrome and add a licence key (Pro, $49/year), then this reconnects on its own. ' +
+              'Everything inside the extension itself still works; only the agent link is paused.'
+            : 'Qiksy extension is not connected. Open Chrome with the extension and enable the MCP bridge in its popup (matching token & port).',
+        ),
+      );
       return;
     }
     const id = randomUUID();
@@ -122,6 +240,7 @@ function callExtension(tool, args, timeoutMs = 15_000) {
       reject(new Error(`Timed out after ${timeoutMs}ms waiting for "${tool}". Is a normal web page focused in Chrome?`));
     }, timeoutMs);
     pending.set(id, { resolve, reject, timer });
+    if (QUIPS_ON) log(`▸ ${tool}  ${face()}  ${quip()}`);
     client.send(JSON.stringify({ t: 'req', id, tool, args: args || {} }));
   });
 }
@@ -130,7 +249,7 @@ function callExtension(tool, args, timeoutMs = 15_000) {
 const asText = (v) => ({ content: [{ type: 'text', text: typeof v === 'string' ? v : JSON.stringify(v, null, 2) }] });
 const asError = (e) => ({ isError: true, content: [{ type: 'text', text: e instanceof Error ? e.message : String(e) }] });
 
-const server = new McpServer({ name: 'qiksy', version: '0.1.0' });
+const server = new McpServer({ name: 'qiksy', version: VERSION });
 
 server.registerTool(
   'qa_tabs',
@@ -242,6 +361,26 @@ server.registerTool(
   },
 );
 
+server.registerTool(
+  'qa_snapshot',
+  {
+    title: 'Full page snapshot (accessibility tree)',
+    description:
+      'A compact accessibility / interaction snapshot of the WHOLE page: every interactive control, landmark and heading with a role, an accessible name, its state, and a STABLE ref like [ref=e12]. ' +
+      'Unlike qa_export — which lists only the FORM fields Qiksy detects and can miss inputs, file uploads, date pickers, selects and buttons — this "sees everything". ' +
+      'Pass a ref straight back to qa_click / qa_type / qa_spotlight: a ref is unique and unambiguous, so it works where a CSS selector is duplicated across fields. ' +
+      'Built in the live, already-authenticated page in ~milliseconds — no browser launch, no CDP. Re-run it after the page changes to refresh the refs (a ref goes stale when its element is re-rendered).',
+    inputSchema: { tabId: tabIdArg },
+  },
+  async ({ tabId }) => {
+    try {
+      return asText(await callExtension('qa_snapshot', { tabId }, 30_000));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
 server.registerTool(
   'qa_tour',
   {
@@ -264,12 +403,36 @@ server.registerTool(
   {
     title: 'Generate session report',
     description:
-      'Generate Qiksy\'s self-contained HTML session report (coverage stats, per-page table, steps with screenshots, findings) from the recorded session and return the HTML. Requires History recording to have captured steps; otherwise returns a note.',
-    inputSchema: { tabId: tabIdArg },
+      "Generate Qiksy's self-contained HTML report — coverage stats, per-page table, steps with screenshots, findings — and return the HTML. " +
+      'Pass `spec` to make it answer the question the TICKET asked: give it the story and your verdict on each acceptance criterion, and the report leads with those, ' +
+      'rendered next to the evidence Qiksy collected itself (errors, failed requests with server bodies, screenshots). ' +
+      'That turns a log into a deliverable a developer or a client can read. You supply the verdicts — you are the one who read the story; Qiksy supplies the proof. ' +
+      'Requires History recording to have captured steps; otherwise returns a note.',
+    inputSchema: {
+      tabId: tabIdArg,
+      spec: z
+        .object({
+          title: z.string().optional().describe('Report heading, e.g. the ticket key + name'),
+          story: z.string().optional().describe('The story / requirement text the criteria came from'),
+          checks: z
+            .array(
+              z.object({
+                id: z.string().optional().describe('Criterion id, e.g. "AC-3"'),
+                text: z.string().describe('What was supposed to happen'),
+                status: z.enum(['pass', 'fail', 'blocked']),
+                evidence: z.string().optional().describe('What you actually observed'),
+                selector: z.string().optional().describe('Where, if it is element-specific'),
+              }),
+            )
+            .optional(),
+        })
+        .optional()
+        .describe('Acceptance criteria + verdicts to lead the report with'),
+    },
   },
-  async ({ tabId }) => {
+  async ({ tabId, spec }) => {
     try {
-      return asText(await callExtension('qa_report', { tabId }, 45_000));
+      return asText(await callExtension('qa_report', { tabId, spec }, 45_000));
     } catch (e) {
       return asError(e);
     }
@@ -281,16 +444,227 @@ server.registerTool(
   {
     title: 'Spotlight an element',
     description:
-      'Visually highlight (dim + outline) an element on the page by CSS selector, so the human tester can see what the agent is referring to. A non-destructive overlay — it does not click, focus, or modify the element.',
+      'Visually highlight (dim + outline) an element on the page — target it by a qa_snapshot ref (preferred) or a CSS selector — so the human tester can see what the agent is referring to. A non-destructive overlay — it does not click, focus, or modify the element.',
     inputSchema: {
       tabId: tabIdArg,
-      selector: z.string().describe('CSS selector of the element to spotlight'),
+      selector: z.string().optional().describe('CSS selector of the element to spotlight'),
+      ref: z.string().optional().describe('A ref from qa_snapshot (e.g. "e12") — preferred over selector'),
       label: z.string().optional().describe('Optional caption shown on the highlight'),
     },
   },
-  async ({ tabId, selector, label }) => {
+  async ({ tabId, selector, ref, label }) => {
+    try {
+      return asText(await callExtension('qa_spotlight', { tabId, selector, ref, label }));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
+/* ── Agent control (Pro) ───────────────────────────────────────────────────
+ *
+ * Everything above this line reads. These three ACT on the app under test, and
+ * they are the reason the tester's own login is worth something to an agent: it
+ * drives the real, already-authenticated session instead of starting cold.
+ *
+ * The gate is NOT here. The extension re-checks a Pro licence and the separate
+ * `drive` consent on every single call and answers `pro-required` /
+ * `consent-required`, so nothing this server can be told to do bypasses it —
+ * which is also why these tools are safe to advertise unconditionally.
+ */
+const DRIVE_NOTE =
+  ' Requires Qiksy Pro and the one-time “Agent control” confirmation in the panel; without both the extension answers pro-required / consent-required and does nothing.';
+
+server.registerTool(
+  'qa_click',
+  {
+    title: 'Click an element (Pro)',
+    description:
+      'Click an element on the page under test, by a qa_snapshot ref (preferred) or a CSS selector. Sends the full pointer sequence (pointerdown → mouseup → click), so component libraries that listen for pointerdown — Radix, shadcn, MUI — react to it like a real click. Scrolls the element into view first, and refuses a target that matches nothing or has zero size rather than silently doing nothing.' +
+      DRIVE_NOTE,
+    inputSchema: {
+      tabId: tabIdArg,
+      selector: z.string().optional().describe('CSS selector of the element to click'),
+      ref: z.string().optional().describe('A ref from qa_snapshot (e.g. "e12") — preferred over selector; unique where a selector is ambiguous'),
+    },
+  },
+  async ({ tabId, selector, ref }) => {
+    try {
+      return asText(await callExtension('qa_click', { tabId, selector, ref }));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
+server.registerTool(
+  'qa_type',
+  {
+    title: 'Type into a field (Pro)',
+    description:
+      'Set the value of an input, textarea, select or contenteditable — target it by a qa_snapshot ref (preferred) or a CSS selector. Uses the native value setter plus InputEvent, so React/Vue controlled inputs actually keep the value — a plain assignment is swallowed by them. For a <select>, matches your text against the option labels. Reports back whether the value stuck, so a masked or read-only field is visible to you rather than silently ignored.' +
+      DRIVE_NOTE,
+    inputSchema: {
+      tabId: tabIdArg,
+      selector: z.string().optional().describe('CSS selector of the field'),
+      ref: z.string().optional().describe('A ref from qa_snapshot (e.g. "e12") — preferred over selector; unique where a selector is ambiguous'),
+      value: z.string().describe('Text to put in the field'),
+    },
+  },
+  async ({ tabId, selector, ref, value }) => {
+    try {
+      return asText(await callExtension('qa_type', { tabId, selector, ref, value }));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
+server.registerTool(
+  'qa_type_many',
+  {
+    title: 'Fill many fields at once (Pro)',
+    description:
+      'Fill a WHOLE form in ONE call instead of a round-trip per field: pass an array of { selector, value, action? }. `action` defaults to "type" (which also handles <select>, checkbox and radio from the value), or "click" for buttons / toggles. Returns a per-field result list plus filled/total — far faster than one qa_type per field on a big form.' +
+      DRIVE_NOTE,
+    inputSchema: {
+      tabId: tabIdArg,
+      fields: z
+        .array(
+          z.object({
+            selector: z.string().describe('CSS selector of the field'),
+            value: z.string().optional().describe('Value to set (text input / <select> / checkbox / radio)'),
+            action: z.enum(['type', 'click']).optional().describe('Default "type"; use "click" for buttons and toggles'),
+          }),
+        )
+        .describe('The fields to fill, in order'),
+    },
+  },
+  async ({ tabId, fields }) => {
+    try {
+      return asText(await callExtension('qa_type_many', { tabId, fields }, 45_000));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
+server.registerTool(
+  'qa_press',
+  {
+    title: 'Press a key (Pro)',
+    description:
+      'Dispatch a keyboard key (keydown/keypress/keyup) — Enter to submit, Escape to close, Tab to move focus. Without a selector it goes to whatever currently has focus, like a real keyboard.' +
+      DRIVE_NOTE,
+    inputSchema: {
+      tabId: tabIdArg,
+      key: z.string().describe('Key value, e.g. "Enter", "Escape", "Tab", "a"'),
+      selector: z.string().optional().describe('Optional target (CSS); defaults to the focused element'),
+      ref: z.string().optional().describe('Optional target (a qa_snapshot ref); defaults to the focused element'),
+    },
+  },
+  async ({ tabId, key, selector, ref }) => {
+    try {
+      return asText(await callExtension('qa_press', { tabId, key, selector, ref }));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
+/* ── Chaining across pages and roles ───────────────────────────────────────
+ *
+ * A submit replaces the document, and with it the Qiksy instance the previous
+ * call was talking to. `qa_wait_ready` is the join point: it returns only once a
+ * FRESH Qiksy answers in the new page, which is what makes fill → submit → act on
+ * the next page a reliable chain instead of a race.
+ *
+ * Doing the same flow as another user is then just a different tabId:
+ * `qa_open_isolated` gives you a tab with its own empty session (multi-login), and
+ * every tool already accepts `tabId`.
+ */
+server.registerTool(
+  'qa_wait_ready',
+  {
+    title: 'Wait for the page to be ready',
+    description:
+      'Block until the tab has finished loading AND Qiksy is live in the new document. Call this after anything that navigates — a submit, a link click, qa_navigate — before the next qa_type/qa_click, or the call lands on a page that is still being replaced. Read-only: waiting is not acting, so this needs no Pro and no consent.',
+    inputSchema: {
+      tabId: tabIdArg,
+      timeoutMs: z.number().optional().describe('How long to wait, default 15000, max 60000'),
+    },
+  },
+  async ({ tabId, timeoutMs }) => {
+    try {
+      return asText(await callExtension('qa_wait_ready', { tabId, timeoutMs }, 65_000));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
+server.registerTool(
+  'qa_navigate',
+  {
+    title: 'Navigate a tab (Pro)',
+    description:
+      'Point a tab at a URL and wait until it is loaded and Qiksy is live again — the ready-wait is built in, so the next step can run straight after. Use it to jump between steps of a flow that are not reachable by clicking.' +
+      DRIVE_NOTE,
+    inputSchema: {
+      tabId: tabIdArg,
+      url: z.string().describe('Absolute http(s) URL'),
+    },
+  },
+  async ({ tabId, url }) => {
+    try {
+      return asText(await callExtension('qa_navigate', { tabId, url }, 40_000));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
+server.registerTool(
+  'qa_open_isolated',
+  {
+    title: 'Open an isolated login tab (Pro)',
+    description:
+      'Open a tab with its OWN private session — separate cookies, localStorage, IndexedDB — so a second (or third) user can be logged in at the same time in the same browser. Returns its `tabId`; pass that to any tool to run the whole flow as that user, while the first login keeps working untouched. This is how you test a hand-off: submit as one role here, then verify it as another role there, side by side.' +
+      DRIVE_NOTE,
+    inputSchema: {
+      url: z.string().describe('Absolute http(s) URL to open in the isolated tab(s)'),
+      session: z.string().optional().describe('Name for a single session, e.g. "admin"'),
+      sessions: z
+        .array(z.string())
+        .optional()
+        .describe('Open SEVERAL at once, named: ["admin","manager","member","viewer"] — one tab each, all live side by side'),
+      count: z.number().int().optional().describe('Open this many (max 12); unnamed ones become user-1, user-2, …'),
+    },
+  },
+  async ({ url, session, sessions, count }) => {
+    try {
+      return asText(await callExtension('qa_open_isolated', { url, session, sessions, count }, 120_000));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
+server.registerTool(
+  'qa_close_tab',
+  {
+    title: 'Close tabs (Pro)',
+    description:
+      'Close one tab or a list of them — how you tidy up the isolated logins when a matrix run is finished. Returns which ids closed and which were already gone.' +
+      DRIVE_NOTE,
+    inputSchema: {
+      tabId: z.number().int().optional().describe('A single tab to close'),
+      tabIds: z.array(z.number().int()).optional().describe('Several tabs to close, e.g. every isolated login from qa_tabs'),
+    },
+  },
+  async ({ tabId, tabIds }) => {
     try {
-      return asText(await callExtension('qa_spotlight', { tabId, selector, label }));
+      return asText(await callExtension('qa_close_tab', { tabId, tabIds }, 30_000));
     } catch (e) {
       return asError(e);
     }