aipeek 0.2.6 → 0.2.7

package/README.md

@@ -39,9 +39,10 @@ All endpoints are available on your Vite dev server:
 | `GET /__aipeek/{section}/{index}` | Detail for a specific item in a section |
 | `GET /__aipeek/{section}?full` | Full detail (no truncation) |
 | `GET /__aipeek/dom[?scope=Name\|?sel=css]` | Semantic DOM — UI as text (see below) |
+| `GET /__aipeek/query?sel=css` | Read-side twin of `sel=`: a selector's live `count` + each match's `text`/`visible`/`attrs` (role, `data-state`, `aria-*`/`data-*`, value, disabled). Per-element assertions without `/eval`. |
 | `GET /__aipeek/{action}?...` | Drive the page (see Actions) |
 | `POST /__aipeek/chain` | Run a JSON array of actions in one round-trip (see Actions) |
-| `GET\|POST /__aipeek/eval` | Run arbitrary JS in the page (`?code=` or POST body); returns the result. Escape hatch for what typed endpoints can't do. |
+| `GET\|POST /__aipeek/eval` | Run arbitrary JS in the page (`?code=` or POST body); returns the result. Escape hatch for what typed endpoints can't do — for count/text/state/attr checks reach for `/query` first. |
 
 ### Perception layers — UI as text, not pixels
 

package/dist/{chunk-XA2LT6I4.js → chunk-37VLLZIU.js}

@@ -6,7 +6,7 @@ import { fileURLToPath } from "url";
 import { transformSync } from "esbuild";
 
 // src/core/action.ts
-var TYPES = ["click", "fill", "press", "wait", "screenshot"];
+var TYPES = ["click", "fill", "press", "wait", "screenshot", "realclick", "query"];
 function resolveAction(type, args) {
   if (!TYPES.includes(type))
     return { valid: false, error: `unknown action: ${type}` };
@@ -14,6 +14,8 @@ function resolveAction(type, args) {
   switch (type) {
     case "click":
       return hasTarget ? { valid: true } : { valid: false, error: "click needs sel= or text=" };
+    case "realclick":
+      return hasTarget || args.x !== void 0 && args.y !== void 0 ? { valid: true } : { valid: false, error: "realclick needs sel=, text=, or x= & y=" };
     case "fill":
       if (!hasTarget)
         return { valid: false, error: "fill needs sel= or text=" };
@@ -26,6 +28,8 @@ function resolveAction(type, args) {
       return hasTarget ? { valid: true } : { valid: false, error: "wait needs sel= or text=" };
     case "screenshot":
       return { valid: true };
+    case "query":
+      return args.sel ? { valid: true } : { valid: false, error: "query needs sel=" };
     default:
       return { valid: false, error: `unknown action: ${type}` };
   }
@@ -797,8 +801,12 @@ curl ${base}/console  # console logs (errors, warnings, info)
 curl ${base}/network  # fetch/XHR requests with status and timing
 curl ${base}/errors   # uncaught errors and unhandled rejections
 curl ${base}/state    # registered store snapshots
+curl '${base}/query?sel=[role=menuitem]' # this selector right now: count + each element's text/visible/attrs
 \`\`\`
 
+\`/query\` is the read-side twin of click/fill's \`sel=\` \u2014 assert on a specific element
+(how many match, its text, \`data-state\`, \`aria-*\`/\`data-*\`, value, disabled) without \`/eval\`.
+
 \`/screen\` projects the whole UI to a few state variables \u2014 start there, not \`/ui\`. Append
 \`?full\` for untruncated output. Append \`/{index}\` for a specific item's detail.
 
@@ -835,34 +843,33 @@ curl -X POST ${base}/chain -d '[
 \`\`\`
 
 **Escape hatch.** \`curl '${base}/eval?code=...'\` (or POST the code as the body) runs arbitrary
-JS in the page and returns the result \u2014 for anything the typed endpoints can't do.
+JS in the page and returns the result \u2014 for what the typed endpoints can't do (install listeners,
+read closures, probe event flow). For count/text/state/attr assertions reach for \`/query\` first.
 
 aipeek auto-detects errors after HMR and prints them to the terminal \u2014 watch for \`[aipeek]\` messages.
 `;
 }
 var START_TAG = "<!-- AIPEEK:START -->";
 var END_TAG = "<!-- AIPEEK:END -->";
-function injectClaudeMd(root, port) {
-  const path = resolve(root, "CLAUDE.md");
+function renderClaudeMd(existing, port) {
   const block = `${START_TAG}
 ${aipeekSnippet(port).trim()}
 ${END_TAG}
 `;
+  if (existing === null)
+    return block;
+  const si = existing.indexOf(START_TAG);
+  const ei = existing.indexOf(END_TAG);
+  if (si !== -1 && ei !== -1)
+    return existing.slice(0, si) + block.trimEnd() + existing.slice(ei + END_TAG.length);
+  const sep = existing.endsWith("\n") ? "" : "\n";
+  return `${existing}${sep}
+${block}`;
+}
+function injectClaudeMd(root, port) {
+  const path = resolve(root, "CLAUDE.md");
   try {
-    if (!existsSync(path)) {
-      writeFileSync(path, block);
-      return;
-    }
-    const content = readFileSync(path, "utf-8");
-    const si = content.indexOf(START_TAG);
-    const ei = content.indexOf(END_TAG);
-    if (si !== -1 && ei !== -1) {
-      writeFileSync(path, content.slice(0, si) + block.trimEnd() + content.slice(ei + END_TAG.length));
-      return;
-    }
-    const sep = content.endsWith("\n") ? "" : "\n";
-    writeFileSync(path, `${content}${sep}
-${block}`);
+    writeFileSync(path, renderClaudeMd(existsSync(path) ? readFileSync(path, "utf-8") : null, port));
   } catch {
   }
 }
@@ -873,6 +880,27 @@ function aipeekPlugin() {
   let pushTimer;
   const pendingActions = /* @__PURE__ */ new Map();
   let actionId = 0;
+  const cdpQueue = [];
+  let cdpWaiter = null;
+  const cdpResults = /* @__PURE__ */ new Map();
+  let cdpId = 0;
+  function runCdpClick(x, y, button) {
+    const id = ++cdpId;
+    const cmd = { id, x, y, button };
+    return new Promise((resolve2, reject) => {
+      cdpResults.set(id, resolve2);
+      if (cdpWaiter) {
+        cdpWaiter(cmd);
+        cdpWaiter = null;
+      } else {
+        cdpQueue.push(cmd);
+      }
+      setTimeout(() => {
+        if (cdpResults.delete(id))
+          reject(new Error("cdp timeout: no extension result within 10s (is the aipeek extension loaded and the debugger attached?)"));
+      }, 1e4);
+    });
+  }
   let pendingDom = null;
   let pendingScreen = null;
   const pendingEvals = /* @__PURE__ */ new Map();
@@ -933,6 +961,18 @@ function aipeekPlugin() {
       };
     }, fullMs);
   }
+  async function runAction(type, args) {
+    const result = await sendAction(type, args);
+    lastRaw = null;
+    if (type === "realclick" && result.ok && result.ui === void 0) {
+      const cdp = await runCdpClick(result.x, result.y, args.button ?? "left");
+      if (!cdp.ok)
+        return { ok: false, error: `cdp click failed: ${cdp.error ?? "unknown"}` };
+      result.detail = `${result.detail} \u2192 clicked via extension`;
+      result.ui = await collectScreenFromClient();
+    }
+    return result;
+  }
   function evalInClient(code) {
     const id = ++evalId;
     return twoPhase("aipeek:eval", { id, code }, (resolve2) => {
@@ -1045,6 +1085,44 @@ function aipeekPlugin() {
             send(res, 200, screen || "(empty)");
             return;
           }
+          if (parts[0] === "cdp" && parts[1] === "poll") {
+            const queued = cdpQueue.shift();
+            if (queued) {
+              send(res, 200, JSON.stringify(queued));
+              return;
+            }
+            const cmd = await new Promise((resolve2) => {
+              cdpWaiter = resolve2;
+              setTimeout(() => {
+                if (cdpWaiter === resolve2) {
+                  cdpWaiter = null;
+                  resolve2(null);
+                }
+              }, 25e3);
+            });
+            if (cmd)
+              send(res, 200, JSON.stringify(cmd));
+            else
+              send(res, 204, "");
+            return;
+          }
+          if (parts[0] === "cdp" && parts[1] === "result") {
+            const body = await readBody(req);
+            let data;
+            try {
+              data = JSON.parse(body);
+            } catch {
+              send(res, 400, "cdp/result needs a JSON body {id, ok, error?}");
+              return;
+            }
+            const resolveCdp = cdpResults.get(data.id);
+            if (resolveCdp) {
+              cdpResults.delete(data.id);
+              resolveCdp({ ok: data.ok, error: data.error });
+            }
+            send(res, 200, "ok");
+            return;
+          }
           if (parts[0] === "chain") {
             const body = await readBody(req);
             let steps;
@@ -1068,7 +1146,7 @@ function aipeekPlugin() {
                 allOk = false;
                 break;
               }
-              const r = await sendAction(type, args);
+              const r = await runAction(type, args);
               lines.push(`[${i}] ${r.ok ? "\u2713" : "\u2717"} ${type}: ${r.ok ? r.detail || "ok" : r.error}`);
               if (r.screen)
                 lines.push(r.screen.split("\n").map((l) => `    ${l}`).join("\n"));
@@ -1085,7 +1163,7 @@ function aipeekPlugin() {
 ${lastUi}` : lines.join("\n"));
             return;
           }
-          if (["click", "fill", "press", "wait", "screenshot"].includes(parts[0])) {
+          if (["click", "fill", "press", "wait", "screenshot", "realclick", "query"].includes(parts[0])) {
             const q = url.searchParams;
             const args = {
               sel: q.get("sel") || void 0,
@@ -1093,15 +1171,17 @@ ${lastUi}` : lines.join("\n"));
               value: q.has("value") ? q.get("value") : void 0,
               key: q.get("key") || void 0,
               timeout: q.has("timeout") ? Number(q.get("timeout")) : void 0,
-              gone: q.has("gone") ? q.get("gone") !== "false" : void 0
+              gone: q.has("gone") ? q.get("gone") !== "false" : void 0,
+              button: q.get("button") === "right" ? "right" : q.get("button") === "left" ? "left" : void 0,
+              x: q.has("x") ? Number(q.get("x")) : void 0,
+              y: q.has("y") ? Number(q.get("y")) : void 0
             };
             const check2 = resolveAction(parts[0], args);
             if (!check2.valid) {
               send(res, 400, check2.error ?? "invalid action");
               return;
             }
-            const result = await sendAction(parts[0], args);
-            lastRaw = null;
+            const result = await runAction(parts[0], args);
             if (parts[0] === "screenshot" && result.dataUrl) {
               const dir = resolve(server.config.root, ".aipeek");
               mkdirSync(dir, { recursive: true });
@@ -1163,6 +1243,7 @@ export {
   emitDiff,
   START_TAG,
   END_TAG,
+  renderClaudeMd,
   injectClaudeMd,
   aipeekPlugin
 };

package/dist/{chunk-5ZZYOETF.cjs → chunk-STYCUT23.cjs}

@@ -10,7 +10,7 @@ var _url = require('url');
 var _esbuild = require('esbuild');
 
 // src/core/action.ts
-var TYPES = ["click", "fill", "press", "wait", "screenshot"];
+var TYPES = ["click", "fill", "press", "wait", "screenshot", "realclick", "query"];
 function resolveAction(type, args) {
   if (!TYPES.includes(type))
     return { valid: false, error: `unknown action: ${type}` };
@@ -18,6 +18,8 @@ function resolveAction(type, args) {
   switch (type) {
     case "click":
       return hasTarget ? { valid: true } : { valid: false, error: "click needs sel= or text=" };
+    case "realclick":
+      return hasTarget || args.x !== void 0 && args.y !== void 0 ? { valid: true } : { valid: false, error: "realclick needs sel=, text=, or x= & y=" };
     case "fill":
       if (!hasTarget)
         return { valid: false, error: "fill needs sel= or text=" };
@@ -30,6 +32,8 @@ function resolveAction(type, args) {
       return hasTarget ? { valid: true } : { valid: false, error: "wait needs sel= or text=" };
     case "screenshot":
       return { valid: true };
+    case "query":
+      return args.sel ? { valid: true } : { valid: false, error: "query needs sel=" };
     default:
       return { valid: false, error: `unknown action: ${type}` };
   }
@@ -801,8 +805,12 @@ curl ${base}/console  # console logs (errors, warnings, info)
 curl ${base}/network  # fetch/XHR requests with status and timing
 curl ${base}/errors   # uncaught errors and unhandled rejections
 curl ${base}/state    # registered store snapshots
+curl '${base}/query?sel=[role=menuitem]' # this selector right now: count + each element's text/visible/attrs
 \`\`\`
 
+\`/query\` is the read-side twin of click/fill's \`sel=\` \u2014 assert on a specific element
+(how many match, its text, \`data-state\`, \`aria-*\`/\`data-*\`, value, disabled) without \`/eval\`.
+
 \`/screen\` projects the whole UI to a few state variables \u2014 start there, not \`/ui\`. Append
 \`?full\` for untruncated output. Append \`/{index}\` for a specific item's detail.
 
@@ -839,34 +847,33 @@ curl -X POST ${base}/chain -d '[
 \`\`\`
 
 **Escape hatch.** \`curl '${base}/eval?code=...'\` (or POST the code as the body) runs arbitrary
-JS in the page and returns the result \u2014 for anything the typed endpoints can't do.
+JS in the page and returns the result \u2014 for what the typed endpoints can't do (install listeners,
+read closures, probe event flow). For count/text/state/attr assertions reach for \`/query\` first.
 
 aipeek auto-detects errors after HMR and prints them to the terminal \u2014 watch for \`[aipeek]\` messages.
 `;
 }
 var START_TAG = "<!-- AIPEEK:START -->";
 var END_TAG = "<!-- AIPEEK:END -->";
-function injectClaudeMd(root, port) {
-  const path = _path.resolve.call(void 0, root, "CLAUDE.md");
+function renderClaudeMd(existing, port) {
   const block = `${START_TAG}
 ${aipeekSnippet(port).trim()}
 ${END_TAG}
 `;
+  if (existing === null)
+    return block;
+  const si = existing.indexOf(START_TAG);
+  const ei = existing.indexOf(END_TAG);
+  if (si !== -1 && ei !== -1)
+    return existing.slice(0, si) + block.trimEnd() + existing.slice(ei + END_TAG.length);
+  const sep = existing.endsWith("\n") ? "" : "\n";
+  return `${existing}${sep}
+${block}`;
+}
+function injectClaudeMd(root, port) {
+  const path = _path.resolve.call(void 0, root, "CLAUDE.md");
   try {
-    if (!_fs.existsSync.call(void 0, path)) {
-      _fs.writeFileSync.call(void 0, path, block);
-      return;
-    }
-    const content = _fs.readFileSync.call(void 0, path, "utf-8");
-    const si = content.indexOf(START_TAG);
-    const ei = content.indexOf(END_TAG);
-    if (si !== -1 && ei !== -1) {
-      _fs.writeFileSync.call(void 0, path, content.slice(0, si) + block.trimEnd() + content.slice(ei + END_TAG.length));
-      return;
-    }
-    const sep = content.endsWith("\n") ? "" : "\n";
-    _fs.writeFileSync.call(void 0, path, `${content}${sep}
-${block}`);
+    _fs.writeFileSync.call(void 0, path, renderClaudeMd(_fs.existsSync.call(void 0, path) ? _fs.readFileSync.call(void 0, path, "utf-8") : null, port));
   } catch (e7) {
   }
 }
@@ -877,6 +884,27 @@ function aipeekPlugin() {
   let pushTimer;
   const pendingActions = /* @__PURE__ */ new Map();
   let actionId = 0;
+  const cdpQueue = [];
+  let cdpWaiter = null;
+  const cdpResults = /* @__PURE__ */ new Map();
+  let cdpId = 0;
+  function runCdpClick(x, y, button) {
+    const id = ++cdpId;
+    const cmd = { id, x, y, button };
+    return new Promise((resolve2, reject) => {
+      cdpResults.set(id, resolve2);
+      if (cdpWaiter) {
+        cdpWaiter(cmd);
+        cdpWaiter = null;
+      } else {
+        cdpQueue.push(cmd);
+      }
+      setTimeout(() => {
+        if (cdpResults.delete(id))
+          reject(new Error("cdp timeout: no extension result within 10s (is the aipeek extension loaded and the debugger attached?)"));
+      }, 1e4);
+    });
+  }
   let pendingDom = null;
   let pendingScreen = null;
   const pendingEvals = /* @__PURE__ */ new Map();
@@ -937,6 +965,18 @@ function aipeekPlugin() {
       };
     }, fullMs);
   }
+  async function runAction(type, args) {
+    const result = await sendAction(type, args);
+    lastRaw = null;
+    if (type === "realclick" && result.ok && result.ui === void 0) {
+      const cdp = await runCdpClick(result.x, result.y, _nullishCoalesce(args.button, () => ( "left")));
+      if (!cdp.ok)
+        return { ok: false, error: `cdp click failed: ${_nullishCoalesce(cdp.error, () => ( "unknown"))}` };
+      result.detail = `${result.detail} \u2192 clicked via extension`;
+      result.ui = await collectScreenFromClient();
+    }
+    return result;
+  }
   function evalInClient(code) {
     const id = ++evalId;
     return twoPhase("aipeek:eval", { id, code }, (resolve2) => {
@@ -1049,6 +1089,44 @@ function aipeekPlugin() {
             send(res, 200, screen || "(empty)");
             return;
           }
+          if (parts[0] === "cdp" && parts[1] === "poll") {
+            const queued = cdpQueue.shift();
+            if (queued) {
+              send(res, 200, JSON.stringify(queued));
+              return;
+            }
+            const cmd = await new Promise((resolve2) => {
+              cdpWaiter = resolve2;
+              setTimeout(() => {
+                if (cdpWaiter === resolve2) {
+                  cdpWaiter = null;
+                  resolve2(null);
+                }
+              }, 25e3);
+            });
+            if (cmd)
+              send(res, 200, JSON.stringify(cmd));
+            else
+              send(res, 204, "");
+            return;
+          }
+          if (parts[0] === "cdp" && parts[1] === "result") {
+            const body = await readBody(req);
+            let data;
+            try {
+              data = JSON.parse(body);
+            } catch (e9) {
+              send(res, 400, "cdp/result needs a JSON body {id, ok, error?}");
+              return;
+            }
+            const resolveCdp = cdpResults.get(data.id);
+            if (resolveCdp) {
+              cdpResults.delete(data.id);
+              resolveCdp({ ok: data.ok, error: data.error });
+            }
+            send(res, 200, "ok");
+            return;
+          }
           if (parts[0] === "chain") {
             const body = await readBody(req);
             let steps;
@@ -1072,7 +1150,7 @@ function aipeekPlugin() {
                 allOk = false;
                 break;
               }
-              const r = await sendAction(type, args);
+              const r = await runAction(type, args);
               lines.push(`[${i}] ${r.ok ? "\u2713" : "\u2717"} ${type}: ${r.ok ? r.detail || "ok" : r.error}`);
               if (r.screen)
                 lines.push(r.screen.split("\n").map((l) => `    ${l}`).join("\n"));
@@ -1089,7 +1167,7 @@ function aipeekPlugin() {
 ${lastUi}` : lines.join("\n"));
             return;
           }
-          if (["click", "fill", "press", "wait", "screenshot"].includes(parts[0])) {
+          if (["click", "fill", "press", "wait", "screenshot", "realclick", "query"].includes(parts[0])) {
             const q = url.searchParams;
             const args = {
               sel: q.get("sel") || void 0,
@@ -1097,15 +1175,17 @@ ${lastUi}` : lines.join("\n"));
               value: q.has("value") ? q.get("value") : void 0,
               key: q.get("key") || void 0,
               timeout: q.has("timeout") ? Number(q.get("timeout")) : void 0,
-              gone: q.has("gone") ? q.get("gone") !== "false" : void 0
+              gone: q.has("gone") ? q.get("gone") !== "false" : void 0,
+              button: q.get("button") === "right" ? "right" : q.get("button") === "left" ? "left" : void 0,
+              x: q.has("x") ? Number(q.get("x")) : void 0,
+              y: q.has("y") ? Number(q.get("y")) : void 0
             };
             const check2 = resolveAction(parts[0], args);
             if (!check2.valid) {
               send(res, 400, _nullishCoalesce(check2.error, () => ( "invalid action")));
               return;
             }
-            const result = await sendAction(parts[0], args);
-            lastRaw = null;
+            const result = await runAction(parts[0], args);
             if (parts[0] === "screenshot" && result.dataUrl) {
               const dir = _path.resolve.call(void 0, server.config.root, ".aipeek");
               _fs.mkdirSync.call(void 0, dir, { recursive: true });
@@ -1169,4 +1249,5 @@ ${result.ui}` : head);
 
 
 
-exports.check = check; exports.diffState = diffState; exports.emitSummary = emitSummary; exports.emitCheck = emitCheck; exports.emitDiff = emitDiff; exports.START_TAG = START_TAG; exports.END_TAG = END_TAG; exports.injectClaudeMd = injectClaudeMd; exports.aipeekPlugin = aipeekPlugin;
+
+exports.check = check; exports.diffState = diffState; exports.emitSummary = emitSummary; exports.emitCheck = emitCheck; exports.emitDiff = emitDiff; exports.START_TAG = START_TAG; exports.END_TAG = END_TAG; exports.renderClaudeMd = renderClaudeMd; exports.injectClaudeMd = injectClaudeMd; exports.aipeekPlugin = aipeekPlugin;

package/dist/index.cjs

@@ -5,7 +5,7 @@
 
 
 
-var _chunk5ZZYOETFcjs = require('./chunk-5ZZYOETF.cjs');
+var _chunkSTYCUT23cjs = require('./chunk-STYCUT23.cjs');
 require('./chunk-Z2Y65YOY.cjs');
 
 
@@ -14,4 +14,4 @@ require('./chunk-Z2Y65YOY.cjs');
 
 
 
-exports.aipeekPlugin = _chunk5ZZYOETFcjs.aipeekPlugin; exports.check = _chunk5ZZYOETFcjs.check; exports.diffState = _chunk5ZZYOETFcjs.diffState; exports.emitCheck = _chunk5ZZYOETFcjs.emitCheck; exports.emitDiff = _chunk5ZZYOETFcjs.emitDiff; exports.emitSummary = _chunk5ZZYOETFcjs.emitSummary;
+exports.aipeekPlugin = _chunkSTYCUT23cjs.aipeekPlugin; exports.check = _chunkSTYCUT23cjs.check; exports.diffState = _chunkSTYCUT23cjs.diffState; exports.emitCheck = _chunkSTYCUT23cjs.emitCheck; exports.emitDiff = _chunkSTYCUT23cjs.emitDiff; exports.emitSummary = _chunkSTYCUT23cjs.emitSummary;

package/dist/index.js

@@ -5,7 +5,7 @@ import {
   emitCheck,
   emitDiff,
   emitSummary
-} from "./chunk-XA2LT6I4.js";
+} from "./chunk-37VLLZIU.js";
 export {
   aipeekPlugin,
   check,

package/dist/plugin.cjs

@@ -3,11 +3,13 @@
 
 
 
-var _chunk5ZZYOETFcjs = require('./chunk-5ZZYOETF.cjs');
+
+var _chunkSTYCUT23cjs = require('./chunk-STYCUT23.cjs');
 require('./chunk-Z2Y65YOY.cjs');
 
 
 
 
 
-exports.END_TAG = _chunk5ZZYOETFcjs.END_TAG; exports.START_TAG = _chunk5ZZYOETFcjs.START_TAG; exports.aipeekPlugin = _chunk5ZZYOETFcjs.aipeekPlugin; exports.injectClaudeMd = _chunk5ZZYOETFcjs.injectClaudeMd;
+
+exports.END_TAG = _chunkSTYCUT23cjs.END_TAG; exports.START_TAG = _chunkSTYCUT23cjs.START_TAG; exports.aipeekPlugin = _chunkSTYCUT23cjs.aipeekPlugin; exports.injectClaudeMd = _chunkSTYCUT23cjs.injectClaudeMd; exports.renderClaudeMd = _chunkSTYCUT23cjs.renderClaudeMd;

package/dist/plugin.js

@@ -2,11 +2,13 @@ import {
   END_TAG,
   START_TAG,
   aipeekPlugin,
-  injectClaudeMd
-} from "./chunk-XA2LT6I4.js";
+  injectClaudeMd,
+  renderClaudeMd
+} from "./chunk-37VLLZIU.js";
 export {
   END_TAG,
   START_TAG,
   aipeekPlugin,
-  injectClaudeMd
+  injectClaudeMd,
+  renderClaudeMd
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "aipeek",
-    "version": "0.2.6",
+    "version": "0.2.7",
     "description": "Gives AI a peek into your running browser app — UI tree, console, network, errors, state",
     "license": "MIT",
     "repository": {

package/src/client/client.ts

@@ -647,10 +647,21 @@ if (import.meta.hot) {
         const { result, dialogs } = await withDialogGuard(() => performAction(msg.type, msg.args))
         if (dialogs.length)
             result.detail = `${result.detail ?? ''} [auto-dismissed ${dialogs.join('; ')}]`.trim()
+        // realclick resolved to (x,y) but didn't click — synthetic events can't open a Radix
+        // ContextMenu. Fire a trusted click through whatever channel can: in Electron the page
+        // can reach the main process via electronAPI.invoke('aipeek:input') → sendInputEvent;
+        // in a plain Chrome tab it can't (no chrome.debugger from page JS), so leave ui
+        // undefined and let the server drive its extension queue.
+        const electronAPI = (window as { electronAPI?: { invoke: (channel: string, ...args: unknown[]) => Promise<unknown> } }).electronAPI
+        if (msg.type === 'realclick' && result.ok && electronAPI) {
+            await electronAPI.invoke('aipeek:input', { type: 'click', button: msg.args.button ?? 'left', x: result.x, y: result.y })
+            result.ui = await waitForStable()
+            result.screen = collectScreen()
+        }
         // For mutating actions, settle the DOM then ship both the full UI tree and
         // the compact screen projection — the caller skips a round-trip to /ui, and
         // /chain uses the per-step screen so an interaction's every transition shows.
-        if (result.ok && (msg.type === 'click' || msg.type === 'fill' || msg.type === 'press')) {
+        else if (result.ok && (msg.type === 'click' || msg.type === 'fill' || msg.type === 'press')) {
             result.ui = await waitForStable()
             result.screen = collectScreen()
         }

package/src/core/action.ts

@@ -6,7 +6,7 @@
 //   - performAction(): real DOM mutation. Runs browser-side (client.ts imports it).
 //     References window/document — never imported plugin-side.
 
-export type ActionType = 'click' | 'fill' | 'press' | 'wait' | 'screenshot'
+export type ActionType = 'click' | 'fill' | 'press' | 'wait' | 'screenshot' | 'realclick' | 'query'
 
 export interface ActionArgs {
     sel?: string
@@ -15,6 +15,9 @@ export interface ActionArgs {
     key?: string
     timeout?: number
     gone?: boolean
+    button?: 'left' | 'right'
+    x?: number
+    y?: number
 }
 
 export interface ActionResult {
@@ -24,9 +27,11 @@ export interface ActionResult {
     dataUrl?: string
     ui?: string
     screen?: string
+    x?: number
+    y?: number
 }
 
-const TYPES: ActionType[] = ['click', 'fill', 'press', 'wait', 'screenshot']
+const TYPES: ActionType[] = ['click', 'fill', 'press', 'wait', 'screenshot', 'realclick', 'query']
 
 // --- Pure validation (plugin-side) ---
 
@@ -38,6 +43,8 @@ export function resolveAction(type: string, args: ActionArgs): { valid: boolean,
     switch (type) {
         case 'click':
             return hasTarget ? { valid: true } : { valid: false, error: 'click needs sel= or text=' }
+        case 'realclick':
+            return hasTarget || (args.x !== undefined && args.y !== undefined) ? { valid: true } : { valid: false, error: 'realclick needs sel=, text=, or x= & y=' }
         case 'fill':
             if (!hasTarget)
                 return { valid: false, error: 'fill needs sel= or text=' }
@@ -50,6 +57,8 @@ export function resolveAction(type: string, args: ActionArgs): { valid: boolean,
             return hasTarget ? { valid: true } : { valid: false, error: 'wait needs sel= or text=' }
         case 'screenshot':
             return { valid: true }
+        case 'query':
+            return args.sel ? { valid: true } : { valid: false, error: 'query needs sel=' }
         default:
             return { valid: false, error: `unknown action: ${type}` }
     }
@@ -103,10 +112,12 @@ export async function performAction(type: ActionType, args: ActionArgs): Promise
     try {
         switch (type) {
             case 'click': return doClick(args)
+            case 'realclick': return doResolveRealClick(args)
             case 'fill': return doFill(args)
             case 'press': return doPress(args)
             case 'wait': return await doWait(args)
             case 'screenshot': return await doScreenshot(args)
+            case 'query': return doQuery(args)
         }
     }
     catch (e) {
@@ -226,6 +237,24 @@ function doClick(args: ActionArgs): ActionResult {
     return { ok: true, detail: `clicked ${visibleText(el).slice(0, 40) || el.tagName.toLowerCase()}${note}` }
 }
 
+// realclick resolves an element to a viewport-center (x,y) but does NOT synthetic-click.
+// The trusted click is fired by whichever channel can produce isTrusted=true input:
+// Electron's webContents.sendInputEvent (via electronAPI.invoke, in client.ts) or a Chrome
+// extension's chrome.debugger (via the server's CDP queue). Synthetic events can't open a
+// Radix ContextMenu — that's the whole reason this path exists. When x= & y= are given
+// directly we pass them through unchanged.
+function doResolveRealClick(args: ActionArgs): ActionResult {
+    if (args.x !== undefined && args.y !== undefined)
+        return { ok: true, x: args.x, y: args.y, detail: `resolved (${args.x}, ${args.y})` }
+    const el = findElement(args.sel, args.text)
+    if (!el)
+        return { ok: false, error: `no element for ${args.sel || args.text}`, detail: clickableList() }
+    const r = el.getBoundingClientRect()
+    const x = Math.round(r.left + r.width / 2)
+    const y = Math.round(r.top + r.height / 2)
+    return { ok: true, x, y, detail: `resolved ${visibleText(el).slice(0, 40) || el.tagName.toLowerCase()} at (${x}, ${y})` }
+}
+
 function doFill(args: ActionArgs): ActionResult {
     const el = findElement(args.sel, args.text)
     if (!el)
@@ -250,8 +279,15 @@ function doFill(args: ActionArgs): ActionResult {
         return { ok: true, detail: `filled contenteditable, ${value.length} chars` }
     }
 
+    // React overrides the value setter on the element *instance* to track changes; a plain
+    // `input.value = x` writes through it so React's tracker never sees a diff and onChange
+    // never fires (controlled inputs stay empty). Call the *prototype* setter instead — the
+    // tracker observes the change and the synthetic onChange fires.
     const input = el as HTMLInputElement
-    input.value = value
+    const proto = el.tagName === 'TEXTAREA' ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype
+    const setter = Object.getOwnPropertyDescriptor(proto, 'value')?.set
+    if (setter) setter.call(input, value)
+    else input.value = value
     input.dispatchEvent(new Event('input', { bubbles: true }))
     input.dispatchEvent(new Event('change', { bubbles: true }))
     return { ok: true, detail: `filled ${value.length} chars` }
@@ -323,3 +359,46 @@ async function doScreenshot(args: ActionArgs): Promise<ActionResult> {
         return { ok: false, error: `screenshot failed: ${msg}` }
     }
 }
+
+// The read-side twin of click/fill's `sel=`: instead of acting on the matched
+// element, report the facts you'd otherwise reach for via /eval — count of
+// matches, and per-element text / visible / assertion-relevant attrs. /wait
+// answers "appears over time"; query answers "what is it now". Attrs are a
+// whitelist (role, data-state, data-*, aria-*, value, disabled, checked, href,
+// title) — a node's full class/style set is noise. Capped at 20 matches.
+const QUERY_ATTRS = ['role', 'data-state', 'value', 'href', 'title']
+const QUERY_PREFIXES = ['data-', 'aria-']
+
+function elAttrs(el: Element): Record<string, string> {
+    const out: Record<string, string> = {}
+    for (const attr of Array.from(el.attributes)) {
+        if (QUERY_ATTRS.includes(attr.name) || QUERY_PREFIXES.some(p => attr.name.startsWith(p)))
+            out[attr.name] = attr.value
+    }
+    const input = el as HTMLInputElement
+    if (typeof input.value === 'string' && out.value === undefined && (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' || el.tagName === 'SELECT'))
+        out.value = input.value
+    if (input.disabled)
+        out.disabled = 'true'
+    if (input.checked)
+        out.checked = 'true'
+    return out
+}
+
+function doQuery(args: ActionArgs): ActionResult {
+    let els: Element[]
+    try {
+        els = Array.from(document.querySelectorAll(args.sel!))
+    }
+    catch {
+        return { ok: false, error: `invalid selector: ${args.sel} — URL-encode it (curl -G --data-urlencode 'sel=...')` }
+    }
+    const count = els.length
+    const matches = els.slice(0, 20).map(el => ({
+        text: visibleText(el).slice(0, 80),
+        visible: isVisible(el),
+        attrs: elAttrs(el),
+    }))
+    const head = count > 20 ? `(showing 20 of ${count})\n` : ''
+    return { ok: true, detail: head + JSON.stringify({ count, matches }, null, 2) }
+}

package/src/server/plugin.ts

@@ -69,8 +69,12 @@ curl ${base}/console  # console logs (errors, warnings, info)
 curl ${base}/network  # fetch/XHR requests with status and timing
 curl ${base}/errors   # uncaught errors and unhandled rejections
 curl ${base}/state    # registered store snapshots
+curl '${base}/query?sel=[role=menuitem]' # this selector right now: count + each element's text/visible/attrs
 \`\`\`
 
+\`/query\` is the read-side twin of click/fill's \`sel=\` — assert on a specific element
+(how many match, its text, \`data-state\`, \`aria-*\`/\`data-*\`, value, disabled) without \`/eval\`.
+
 \`/screen\` projects the whole UI to a few state variables — start there, not \`/ui\`. Append
 \`?full\` for untruncated output. Append \`/{index}\` for a specific item's detail.
 
@@ -107,7 +111,8 @@ curl -X POST ${base}/chain -d '[
 \`\`\`
 
 **Escape hatch.** \`curl '${base}/eval?code=...'\` (or POST the code as the body) runs arbitrary
-JS in the page and returns the result — for anything the typed endpoints can't do.
+JS in the page and returns the result — for what the typed endpoints can't do (install listeners,
+read closures, probe event flow). For count/text/state/attr assertions reach for \`/query\` first.
 
 aipeek auto-detects errors after HMR and prints them to the terminal — watch for \`[aipeek]\` messages.
 `
@@ -116,27 +121,26 @@ aipeek auto-detects errors after HMR and prints them to the terminal — watch f
 export const START_TAG = '<!-- AIPEEK:START -->'
 export const END_TAG = '<!-- AIPEEK:END -->'
 
-// Marker-based injection — the block lives between START_TAG and END_TAG, so
-// re-injection is a deterministic splice (find markers, replace between) rather
-// than fuzzy line matching. New file → write markers + snippet. Existing markers
-// → replace their contents. No markers yet → append a fresh marked block.
+// Marker-based injection 的纯核心：existing（文件现内容，缺文件传 null）+ port → 新内容。
+// 块夹在 START_TAG..END_TAG 间，再注入是确定性 splice（找标记替换中间）而非模糊行匹配。
+// 缺文件 → 仅块；有标记 → 替换其内容；无标记 → 末尾追加新块。fs 读写是 injectClaudeMd 的边界，
+// 这里 0 副作用——四条分支（新建/替换/追加/补换行）全可被快照锁死。
+export function renderClaudeMd(existing: string | null, port: number): string {
+    const block = `${START_TAG}\n${aipeekSnippet(port).trim()}\n${END_TAG}\n`
+    if (existing === null)
+        return block
+    const si = existing.indexOf(START_TAG)
+    const ei = existing.indexOf(END_TAG)
+    if (si !== -1 && ei !== -1)
+        return existing.slice(0, si) + block.trimEnd() + existing.slice(ei + END_TAG.length)
+    const sep = existing.endsWith('\n') ? '' : '\n'
+    return `${existing}${sep}\n${block}`
+}
+
 export function injectClaudeMd(root: string, port: number) {
     const path = resolve(root, 'CLAUDE.md')
-    const block = `${START_TAG}\n${aipeekSnippet(port).trim()}\n${END_TAG}\n`
     try {
-        if (!existsSync(path)) {
-            writeFileSync(path, block)
-            return
-        }
-        const content = readFileSync(path, 'utf-8')
-        const si = content.indexOf(START_TAG)
-        const ei = content.indexOf(END_TAG)
-        if (si !== -1 && ei !== -1) {
-            writeFileSync(path, content.slice(0, si) + block.trimEnd() + content.slice(ei + END_TAG.length))
-            return
-        }
-        const sep = content.endsWith('\n') ? '' : '\n'
-        writeFileSync(path, `${content}${sep}\n${block}`)
+        writeFileSync(path, renderClaudeMd(existsSync(path) ? readFileSync(path, 'utf-8') : null, port))
     }
     catch {}
 }
@@ -149,6 +153,38 @@ export function aipeekPlugin(): Plugin {
     const pendingActions = new Map<number, (r: ActionResult) => void>()
     let actionId = 0
 
+    // Chrome real-input channel: synthetic events can't open a Radix ContextMenu, and the
+    // in-page script can't reach chrome.debugger. So for a plain browser tab, realclick is a
+    // two-step handshake — the page resolves the element to (x,y), then the server enqueues a
+    // CDP command here for the extension to execute with trusted input. The extension long-polls
+    // /cdp/poll for the next command and POSTs the verdict to /cdp/result. Electron never touches
+    // this (it fires sendInputEvent in-process from the page — see client.ts).
+    interface CdpCommand { id: number, x: number, y: number, button: 'left' | 'right' }
+    const cdpQueue: CdpCommand[] = []
+    let cdpWaiter: ((cmd: CdpCommand | null) => void) | null = null
+    const cdpResults = new Map<number, (r: { ok: boolean, error?: string }) => void>()
+    let cdpId = 0
+
+    function runCdpClick(x: number, y: number, button: 'left' | 'right'): Promise<{ ok: boolean, error?: string }> {
+        const id = ++cdpId
+        const cmd: CdpCommand = { id, x, y, button }
+        return new Promise((resolve, reject) => {
+            cdpResults.set(id, resolve)
+            // hand the command to a parked poller, else queue it for the next poll
+            if (cdpWaiter) {
+                cdpWaiter(cmd)
+                cdpWaiter = null
+            }
+            else {
+                cdpQueue.push(cmd)
+            }
+            setTimeout(() => {
+                if (cdpResults.delete(id))
+                    reject(new Error('cdp timeout: no extension result within 10s (is the aipeek extension loaded and the debugger attached?)'))
+            }, 10000)
+        })
+    }
+
     let pendingDom: ((dom: string) => void) | null = null
     let pendingScreen: ((screen: string) => void) | null = null
     const pendingEvals = new Map<number, (r: { ok: boolean, value?: string, error?: string }) => void>()
@@ -226,6 +262,24 @@ export function aipeekPlugin(): Plugin {
         }, fullMs)
     }
 
+    // sendAction + the Chrome realclick handshake, in one place so the single endpoint and
+    // /chain both get it. The page resolves realclick to (x,y): if it set result.ui, Electron
+    // already fired the trusted click in-process — done. If ui is undefined (plain Chrome tab),
+    // the page couldn't click, so drive the extension's CDP queue with the coords, then collect
+    // the settled screen as the ui. A CDP failure comes back as a normal ok:false result.
+    async function runAction(type: string, args: ActionArgs): Promise<ActionResult> {
+        const result = await sendAction(type, args)
+        lastRaw = null // page mutated; force fresh collect next read
+        if (type === 'realclick' && result.ok && result.ui === undefined) {
+            const cdp = await runCdpClick(result.x!, result.y!, args.button ?? 'left')
+            if (!cdp.ok)
+                return { ok: false, error: `cdp click failed: ${cdp.error ?? 'unknown'}` }
+            result.detail = `${result.detail} → clicked via extension`
+            result.ui = await collectScreenFromClient()
+        }
+        return result
+    }
+
     function evalInClient(code: string): Promise<{ ok: boolean, value?: string, error?: string }> {
         const id = ++evalId
         return twoPhase('aipeek:eval', { id, code }, (resolve) => {
@@ -362,6 +416,51 @@ export function aipeekPlugin(): Plugin {
                         return
                     }
 
+                    // /__aipeek/cdp/poll — the Chrome extension long-polls here for the next
+                    // trusted-input command. Returns the command as JSON, or 204 on timeout
+                    // (the extension simply re-polls). Only one poller is parked at a time.
+                    if (parts[0] === 'cdp' && parts[1] === 'poll') {
+                        const queued = cdpQueue.shift()
+                        if (queued) {
+                            send(res, 200, JSON.stringify(queued))
+                            return
+                        }
+                        const cmd = await new Promise<CdpCommand | null>((resolve) => {
+                            cdpWaiter = resolve
+                            setTimeout(() => {
+                                if (cdpWaiter === resolve) {
+                                    cdpWaiter = null
+                                    resolve(null)
+                                }
+                            }, 25000)
+                        })
+                        if (cmd)
+                            send(res, 200, JSON.stringify(cmd))
+                        else
+                            send(res, 204, '')
+                        return
+                    }
+
+                    // /__aipeek/cdp/result — POST {id, ok, error?}; resolves the awaiting realclick.
+                    if (parts[0] === 'cdp' && parts[1] === 'result') {
+                        const body = await readBody(req)
+                        let data: { id: number, ok: boolean, error?: string }
+                        try {
+                            data = JSON.parse(body)
+                        }
+                        catch {
+                            send(res, 400, 'cdp/result needs a JSON body {id, ok, error?}')
+                            return
+                        }
+                        const resolveCdp = cdpResults.get(data.id)
+                        if (resolveCdp) {
+                            cdpResults.delete(data.id)
+                            resolveCdp({ ok: data.ok, error: data.error })
+                        }
+                        send(res, 200, 'ok')
+                        return
+                    }
+
                     // /__aipeek/chain — POST a JSON array of actions, run them in
                     // sequence (each settles the DOM before the next), stop on first
                     // failure. One round-trip for a whole interaction.
@@ -389,7 +488,7 @@ export function aipeekPlugin(): Plugin {
                                 allOk = false
                                 break
                             }
-                            const r = await sendAction(type, args)
+                            const r = await runAction(type, args)
                             lines.push(`[${i}] ${r.ok ? '✓' : '✗'} ${type}: ${r.ok ? (r.detail || 'ok') : r.error}`)
                             // Per-step screen projection — captures the transition each
                             // mutating step caused, so a view change mid-chain is visible
@@ -407,8 +506,8 @@ export function aipeekPlugin(): Plugin {
                         return
                     }
 
-                    // action endpoints: /__aipeek/{click|fill|press|wait|screenshot}?...
-                    if (['click', 'fill', 'press', 'wait', 'screenshot'].includes(parts[0])) {
+                    // action endpoints: /__aipeek/{click|fill|press|wait|screenshot|realclick}?...
+                    if (['click', 'fill', 'press', 'wait', 'screenshot', 'realclick', 'query'].includes(parts[0])) {
                         const q = url.searchParams
                         const args: ActionArgs = {
                             sel: q.get('sel') || undefined,
@@ -417,14 +516,16 @@ export function aipeekPlugin(): Plugin {
                             key: q.get('key') || undefined,
                             timeout: q.has('timeout') ? Number(q.get('timeout')) : undefined,
                             gone: q.has('gone') ? q.get('gone') !== 'false' : undefined,
+                            button: q.get('button') === 'right' ? 'right' : q.get('button') === 'left' ? 'left' : undefined,
+                            x: q.has('x') ? Number(q.get('x')) : undefined,
+                            y: q.has('y') ? Number(q.get('y')) : undefined,
                         }
                         const check = resolveAction(parts[0], args)
                         if (!check.valid) {
                             send(res, 400, check.error ?? 'invalid action')
                             return
                         }
-                        const result = await sendAction(parts[0], args)
-                        lastRaw = null // page mutated; force fresh collect next read
+                        const result = await runAction(parts[0], args)
                         if (parts[0] === 'screenshot' && result.dataUrl) {
                             const dir = resolve(server.config.root, '.aipeek')
                             mkdirSync(dir, { recursive: true })