@usercase/mcp 0.2.11-next.3 → 0.2.11

package/README.md

@@ -30,6 +30,21 @@ Each repository keeps its own connection, so different sites can go to different
 
 Prefer a key? Create one under **Settings → Integrations → API keys** and add `-e USERCASE_API_KEY=eb_sk_...` before `--`. A key you set this way is used first.
 
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/mcp__usercase__research <url> [count]` | Sends virtual users to your site. [More](#run-a-research) |
+| `/mcp__usercase__install` | Adds the Usercase script to your site. [More](#install-the-script) |
+| `/mcp__usercase__new-research` | Plans a research from your data and code and saves it as a draft. [More](#planning-a-research) |
+| `/mcp__usercase__path <research id>` | Records the route each task is meant to take. [More](#record-a-tasks-expected-path) |
+| `/mcp__usercase__fix <research id> <finding>` | Fixes a finding from a research report, or an issue from Issues, in your code. [More](#fix-a-finding-from-a-report) |
+| `/mcp__usercase__question` | Suggests a question for a precise moment and saves it as a draft. [More](#questions-for-a-precise-moment) |
+| `/mcp__usercase__steps <window id>` | Writes the steps for a question you are making in the dashboard. [More](#questions-for-a-precise-moment) |
+| `/mcp__usercase__connect` | Connects this repository to another project. [More](#connect) |
+
+Wherever a command needs an id, the dashboard shows it ready to copy. You can also just ask Claude, for example "research my staging site with 10 virtual users".
+
 ## Install the script
 
 The survey cards come from the Usercase script on your site. If it isn't there yet, let Claude Code add it:
@@ -67,6 +82,14 @@ The number is how many people visit in total (default 5). Above 5, Claude works
 
 With `unlimited` it keeps going until you press Esc. Every visit uses your Claude usage.
 
+### Focus on one part of the site
+
+Name a part of the site, and Claude casts only people who come for it:
+
+```
+/mcp__usercase__research https://staging.example.com 5 focus=checkout
+```
+
 ### Take part in a research
 
 Give a research id from your dashboard and the people take part in it instead of exploring freely — they accept its invitation and do its tasks from the study panel, the way invited participants do. The research must be live.
@@ -75,6 +98,8 @@ Give a research id from your dashboard and the people take part in it instead of
 /mcp__usercase__research https://staging.example.com 10 research=<research id>
 ```
 
+If the research is moderated by voice, the people read the moderator's captions and answer out loud, with a voice already on your computer (Windows voices, macOS `say` or `espeak`). No outside voice service is used.
+
 When a visit ends, it is sent to your dashboard (**Visits**). If the upload fails, it is kept in `.usercase/outbox.jsonl` and sent with the next one.
 
 ### Sites behind a sign-in
@@ -119,6 +144,26 @@ Claude suggests the moment, the question and its answers, and saves it only afte
 
 Claude asks whether you already know what you want to learn. If you don't, it reads your project's findings and where visitors left, and suggests two or three researches, saying which evidence comes from real visitors and which from virtual users. With no data yet, it offers to send a few virtual users first. It then reads your code to write the tasks, their success conditions (the page that means done, or the exact button) and the route each task is meant to take, and shows you all of it at once. On your approval it walks each route in a browser, checks it, and saves the research with the routes — as a draft in your Inbox, where you create it. The routes move into the research when you create it. A draft you discard, or don't create within 30 days, loses its recorded paths and their screenshots.
 
+## Fix a finding from a report
+
+A research's **Report** lists findings: problems people hit, each backed by what they did, what the screen showed and what they wrote. Each finding has a **Fix with your agent** command:
+
+```
+/mcp__usercase__fix <research id> <finding, e.g. F1>
+```
+
+Add `real` for the report of real people; without it, the report of virtual users is used. Claude reads the finding and any earlier fixes of it, finds the code behind it, and tells you the change it proposes before touching anything. After you approve, it makes the change, runs your checks and records the fix on the finding. It doesn't commit, push or open a pull request unless you ask.
+
+Once the change is deployed, mark it **Live on site** on the finding: the report compares people before and after the fix only from then on. To check it with virtual users, run the same tasks again with `research=<research id>`.
+
+Issues from your questions' answers have the same button in **Issues**:
+
+```
+/mcp__usercase__fix issue <issue id>
+```
+
+Claude reads the question, what people chose and wrote, and any other issues with the same cause, then works the same way. Once the change is deployed, mark the issue reviewed; the question keeps running, so later answers show whether people still hit it.
+
 ## What the visitors will and won't do
 
 - They identify themselves on every request (see below), and their answers are counted separately from real visitors. This cannot be turned off.

package/agents/fix-issue.md

@@ -0,0 +1,40 @@
+# Fix an issue found from your visitors' answers
+
+Issue: {{issue}}
+
+Usercase asks short questions on this site and groups the answers into issues — problems on the site, each backed by the question, what people chose and what they wrote. You fix one issue in this repository's code.
+
+## 1. Read the issue
+
+Call `issue_read` with the issue id. If no issue id is given above, call `issue_list` first, show the user the open issues (title, where, whether it is a clear fix or the cause is unclear, and whether someone is already fixing it), and ask which one to fix.
+
+Read all of it: the question and the page it was asked on, what people chose, what they wrote, the AI's reading of it and the suggested next step. The suggestion was written without seeing the code; treat it as a direction, not a spec.
+
+If the cause is marked unclear, say so to the user: the answers show the problem but not why. Propose the change only if the code makes the cause clear; otherwise suggest running a research on it instead ({{research_cmd}}).
+
+If it lists other issues with the same cause, tell the user — one change may fix them together.
+
+If it lists earlier fixes, read what each changed. Do not repeat an approach that is already in place; say how your change differs. If an earlier fix is probably not deployed yet, tell the user — they may only need to deploy it.
+
+## 2. Find the code
+
+From the page, the question and what people wrote, find the code behind it: routes, the page components, the elements people talk about, the text shown. Confirm you found the right place by matching what people mention (a section, a button, a label) to the code.
+
+## 3. Propose the change — before changing anything
+
+Tell the user, briefly:
+- what in the code causes the problem, with file paths,
+- the change you propose and why it addresses what people chose and wrote, and
+- anything the issue suggests that you would not do, and why (it would break something, it needs a product decision, the code already does it).
+
+Keep the change as small as solves the problem. Do not redesign unrelated parts. Wait for the user's approval or corrections.
+
+## 4. Change the code
+
+When the user approves, call `issue_fix` with `status` `fixing` and the files you will change. Then make the change. Follow the repository's own conventions, and run its checks (type check, lint, tests) if it has them.
+
+## 5. Record the fix
+
+When the change is done, call `issue_fix` with `status` `fixed`, the files changed, a one-sentence summary written for the team (what a visitor now sees differently), and the pull request link if you opened one. Do not commit, push or open a pull request unless the user asks.
+
+Then tell the user that the issue shows as fixed in Issues, and that once the change is deployed they mark it reviewed there. The question keeps running, so later answers show whether people still hit it.

package/agents/fix.md

@@ -12,6 +12,8 @@ Call `report_finding` with the research id, the finding key and the report. If n
 
 Read all of it: the title and why, who it hit, the screen checks (what the page really showed — these come from the recordings, not from opinions), the paths people took, the groups of what they wrote, and the suggested changes. The suggested changes were written without seeing the code; treat them as a direction, not a spec.
 
+If it lists earlier fixes of this finding, read what each changed and how it went. Do not repeat an approach that made things worse or changed nothing; say how your change differs. If an earlier fix is not live yet or probably not deployed, tell the user — they may only need to deploy it.
+
 ## 2. Find the code
 
 From the pages, buttons and texts in the evidence, find the code behind them: routes, the page components, the button and its click handler, the text shown. Confirm you found the right place by matching the exact text on screen (a button label, a heading) to the code.
@@ -31,6 +33,8 @@ When the user approves, call `report_fix` with `status` `fixing` and the files y
 
 ## 5. Record the fix
 
-When the change is done, call `report_fix` with `status` `fixed`, the files changed, a one-sentence summary written for the team (what a visitor now sees differently), and the pull request link if you opened one. Do not commit, push or open a pull request unless the user asks.
+When the change is done, call `report_fix` with `status` `fixed`, the files changed, a one-sentence summary written for the team (what a visitor now sees differently — the next report and the next fix read it), and the pull request link if you opened one. Do not commit, push or open a pull request unless the user asks.
+
+The report compares people only after the fix is live on the site. Tell the user to mark it **Live on site** on the finding once it is deployed; when a new version of their site shows up in sessions, the report also asks whether this fix is in it.
 
 Then tell the user that the finding shows as fixed in the report, and how to check it worked: {{check}}

package/mcp/hub.js

@@ -721,9 +721,15 @@ class Hub {
     }
     if (p.kind === "timeout") {
       const skip = decision.action === "choose" && decision.choiceIndex === 1;
-      await study.press(page, skip ? "timeoutSkip" : "keepGoing").catch(() => {});
+      // 눌리지 않았으면 그대로 알린다 — 전에는 실패를 넘기고 "골랐다"고 해서 같은 창에 갇혔다(11/05)
+      let moved = null;
+      try {
+        moved = await study.press(page, skip ? "timeoutSkip" : "keepGoing");
+      } catch (e) {
+        return [`You pressed "${skip ? "Skip" : "Continue"}", but it did not go through: ${String(e.message).split("\n")[0]}. The study is still asking.`, "", await this.screen(rec)].join("\n");
+      }
       if (skip) st.skipped.push(p.task);
-      said = skip ? `You chose to skip the task "${p.task}".` : "You chose to keep trying.";
+      said = (skip ? `You chose to skip the task "${p.task}".` : "You chose to keep trying.") + (moved ? ` (${moved} was covering the study panel, so you dragged the panel aside first.)` : "");
     } else {
       const q = p.q;
       const ans = decision.action === "choose" ? { index: decision.choiceIndex } : decision.action === "other" ? { text: decision.otherText } : {};

package/mcp/path.js

@@ -91,7 +91,9 @@ function describeInPage(n, { sel: pickSel, lift = false }) {
   } catch (e) {}
   // SDK 는 id 를 이스케이프 없이 `#id` 로 쓴다 — 평범한 id 만(React useId 의 ":r1:" 같은 건 SDK 에서 오류가 난다)
   const ids = pick.id && /^[A-Za-z][\w-]*$/.test(pick.id) && document.querySelectorAll("#" + pick.id).length === 1 ? [pick.id] : [];
-  const label = (pick.getAttribute("aria-label") || pick.innerText || pick.value || pick.getAttribute("title") || "").replace(/\s+/g, " ").trim().slice(0, 80);
+  // 입력칸에 친 값은 이름으로 안 쓴다(방문자 정보·비밀번호가 들어간다). submit·button 의 value 는 버튼 글자라 쓴다.
+  // 아래 path_check 의 label 과 같은 식이어야 한다 — 다르면 같은 요소를 "이름이 다르다"로 본다
+  const label = (pick.getAttribute("aria-label") || pick.innerText || (pick.tagName === "INPUT" && /^(submit|button|reset)$/i.test(pick.type) ? pick.value : "") || pick.getAttribute("title") || pick.getAttribute("placeholder") || "").replace(/\s+/g, " ").trim().slice(0, 80);
   return { xpath: xp(pick), classes, ids, label, tag: pick.tagName.toLowerCase() };
 }
 
@@ -366,7 +368,7 @@ class PathRecorder {
         if (!ok) break;
         const h = (await page.evaluateHandle(byXPathInPage, a.xpath)).asElement();
         const visible = h ? await h.isVisible().catch(() => false) : false;
-        const label = h ? await h.evaluate((n) => (n.getAttribute("aria-label") || n.innerText || n.value || n.getAttribute("title") || "").replace(/\s+/g, " ").trim().slice(0, 80)) : "";
+        const label = h ? await h.evaluate((n) => (n.getAttribute("aria-label") || n.innerText || (n.tagName === "INPUT" && /^(submit|button|reset)$/i.test(n.type) ? n.value : "") || n.getAttribute("title") || n.getAttribute("placeholder") || "").replace(/\s+/g, " ").trim().slice(0, 80)) : "";
         const no = a.step !== null ? `${a.step + 1}. ` : "   ";
         if (!h || !visible) {
           lines.push(`✗ ${no}${a.do} "${a.label || a.text || ""}" — ${h ? "found but not visible" : "not found at its recorded position"} (${a.xpath})`);

package/mcp/report.js

@@ -297,6 +297,10 @@ const rq = (audience) => (audience === "real" ? "?audience=real" : "?audience=vi
 const getReport = (researchId, audience) => keyed("GET", `/agent/researches/${encodeURIComponent(researchId)}/report${rq(audience)}`);
 const getFinding = (researchId, key, audience) => keyed("GET", `/agent/researches/${encodeURIComponent(researchId)}/report/findings/${encodeURIComponent(key)}${rq(audience)}`);
 const saveFix = (researchId, key, body) => keyed("PUT", `/agent/researches/${encodeURIComponent(researchId)}/report/findings/${encodeURIComponent(key)}/fix`, body);
+/** Issues(fix issue) — 열린 문제 목록, 문제 하나와 근거, 고친 기록 */
+const getIssues = () => keyed("GET", "/agent/issues");
+const getIssue = (id) => keyed("GET", `/agent/issues/${encodeURIComponent(id)}`);
+const saveIssueFix = (id, body) => keyed("PUT", `/agent/issues/${encodeURIComponent(id)}/fix`, body);
 /** 대시보드 주소. API 주소에서 /koa 를 뗀다 */
 const dashboardUrl = (p) => apiBase().replace(/\/koa$/, "") + p;
 
@@ -323,5 +327,8 @@ module.exports = {
   getReport,
   getFinding,
   saveFix,
+  getIssues,
+  getIssue,
+  saveIssueFix,
   dashboardUrl,
 };

package/mcp/server.js

@@ -609,6 +609,15 @@ server.registerTool(
     if (e.words.length) L.push("", "What people wrote (grouped by meaning, with examples):", ...e.words.map((w) => `- ${w.text}`));
     if (e.numbers.length) L.push("", "Numbers:", ...e.numbers.map((x) => `- ${x}`));
     L.push("", "Suggested changes (written without seeing the code):", ...f.changes.map((c, i) => `${i + 1}. ${c}`), `Check after the fix: ${f.measure}`);
+    // 지난 고침 — 무엇을 바꿨고 어땠나. 같은 방법을 되풀이하지 않게
+    const VERDICT = { better: "better", worse: "worse", mixed: "mixed", same: "no change", waiting: "not compared yet", not_deployed: "probably not deployed — sessions after it still ran the old version" };
+    if (r.history && r.history.length) {
+      L.push("", "Earlier fixes of this finding (each compared with the version right before it):");
+      for (const h of r.history) {
+        L.push(`- Fix ${h.attempt} by ${h.by}: ${h.summary || "(no note)"} — ${h.liveAt ? `live since ${String(h.liveAt).slice(0, 16).replace("T", " ")}` : "not live yet"}, ${VERDICT[h.verdict] || h.verdict}`);
+        for (const row of h.rows || []) L.push(`  · ${row.label}: ${row.before[0]}/${row.before[1]} → ${row.after[0]}/${row.after[1]}`);
+      }
+    }
     if (r.sessionsUrl) L.push("", `Watch these sessions: ${r.sessionsUrl}`);
     L.push(`Report: ${r.reportUrl}`);
     return text(L.join("\n"));
@@ -619,7 +628,7 @@ server.registerTool(
   "report_fix",
   {
     description:
-      "Record on the research report that you are fixing a finding (status fixing, once the user approved the change) or have fixed it (status fixed, with the files, a one-sentence summary for the team, and the pull request link if any). The report shows it on that finding.",
+      "Record on the research report that you are fixing a finding (status fixing, once the user approved the change) or have fixed it (status fixed, with the files, a one-sentence summary for the team, and the pull request link if any). If the last fix of this finding is already live on the site, this starts the next fix (fix 2, 3 …); otherwise it adds to the current one. The report compares people after each fix goes live with the version right before it.",
     inputSchema: {
       research: z.string().describe("The research id"),
       finding: z.string().describe("Finding key, e.g. F1"),
@@ -633,7 +642,86 @@ server.registerTool(
   wrap(async ({ research, finding, audience, status, files, summary, prUrl }) => {
     const agent = CODEX ? "Codex" : OTHER ? null : "Claude Code";
     const r = await report.saveFix(research, finding, { audience: audience || "virtual", status, agent, files, summary, prUrl });
-    return text(`${r.key} is marked ${r.status} on the report: ${r.reportUrl}`);
+    return text(`${r.key} fix ${r.attempt} is marked ${r.status} on the report: ${r.reportUrl}`);
+  }),
+);
+
+// ── Issues 의 문제 고치기(fix issue) ──
+const issueFixLine = (f) => (f ? ` — ${f.status === "fixed" ? "fixed" : "being fixed"}${f.agent ? ` by ${f.agent}` : ""}` : "");
+
+server.registerTool(
+  "issue_list",
+  {
+    description: "List the open issues of the Usercase project (problems found from visitors' answers to questions on the site): id, title, where, whether it is a clear fix, and whether one is being fixed. Use when the fix command has no issue id.",
+    inputSchema: {},
+  },
+  wrap(async () => {
+    const r = await report.getIssues();
+    if (!r.issues.length) return text("No open issues in this project.");
+    return text(
+      [
+        ...r.issues.map(
+          (i) =>
+            `${i.id} · ${i.title} — ${i.page || "any page"}, ${i.answers} ${i.from === "virtual" ? "virtual users" : "answers"}, ${i.nextStep === "fix" ? "clear fix" : "cause unclear"}${i.status === "acknowledged" ? ", reviewed" : ""}${issueFixLine(i.fix)}`,
+        ),
+        "",
+        `Issues: ${r.url}`,
+      ].join("\n"),
+    );
+  }),
+);
+
+server.registerTool(
+  "issue_read",
+  {
+    description:
+      "Read one issue of the Usercase project with all its evidence: the question and page, what people chose, what they wrote, the AI's reading, other issues with the same cause, and earlier fixes. Read it before looking for the code.",
+    inputSchema: { issue: z.string().describe("The issue id, as in the dashboard command") },
+  },
+  wrap(async ({ issue }) => {
+    const r = await report.getIssue(String(issue).trim());
+    const i = r.issue;
+    const e = r.evidence;
+    const L = [
+      `${i.title}${issueFixLine(i.fix)}`,
+      `From ${i.answers} ${i.from === "virtual" ? "virtual users' answers" : "visitors' answers"} · ${i.nextStep === "fix" ? "clear fix" : "cause unclear — the answers show the problem, not why"}`,
+      "",
+      `Question: "${r.question.text}" (asked on ${r.question.page || "any page"})`,
+      "",
+      `What the answers show: ${i.observation}`,
+      `Likely why: ${i.hypothesis}`,
+    ];
+    if (i.nextStepNote) L.push(`Suggested next step (written without seeing the code): ${i.nextStepNote}`);
+    if (e.distribution.length) L.push("", "What people chose:", ...e.distribution.map((d) => `- ${d.label}: ${d.n}${e.focus.includes(d.label) ? " ← this issue" : ""}`));
+    if (e.words.length) L.push("", "What people wrote:", ...e.words.map((w) => `- "${w.text}"${w.n > 1 ? ` (${w.n} people)` : ""}${w.page ? ` (on ${w.page}${w.device ? `, ${w.device}` : ""})` : ""}`));
+    if (e.pages.length) L.push("", `Pages: ${e.pages.map((p) => `${p.page} (${p.n})`).join(", ")}`);
+    if (r.cause) L.push("", `Same cause as other issues — "${r.cause.title}": ${r.cause.summary}`, ...r.cause.others.map((o) => `- ${o.id} · ${o.title}${o.page ? ` (${o.page})` : ""}`));
+    if (r.history.length) {
+      L.push("", "Earlier fixes of this issue:");
+      for (const h of r.history) L.push(`- Fix ${h.attempt} by ${h.by} (${h.status}): ${h.summary || "(no note)"}${h.files.length ? ` — ${h.files.join(", ")}` : ""}`);
+    }
+    L.push("", `Issue: ${r.url}`);
+    return text(L.join("\n"));
+  }),
+);
+
+server.registerTool(
+  "issue_fix",
+  {
+    description:
+      "Record on a Usercase issue that you are fixing it (status fixing, once the user approved the change) or have fixed it (status fixed, with the files, a one-sentence summary for the team, and the pull request link if any). After a finished fix, starting again records the next fix.",
+    inputSchema: {
+      issue: z.string().describe("The issue id"),
+      status: z.enum(["fixing", "fixed"]),
+      files: z.array(z.string()).optional().describe("Repository paths of the files changed (or to be changed)"),
+      summary: z.string().optional().describe("One sentence for the team: what visitors now see differently"),
+      prUrl: z.string().optional().describe("Pull request link, if one was opened"),
+    },
+  },
+  wrap(async ({ issue, status, files, summary, prUrl }) => {
+    const agent = CODEX ? "Codex" : OTHER ? null : "Claude Code";
+    const r = await report.saveIssueFix(String(issue).trim(), { status, agent, files, summary, prUrl });
+    return text(`"${r.title}" fix ${r.attempt} is marked ${r.status}: ${r.url}`);
   }),
 );
 
@@ -1018,6 +1106,14 @@ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
  */
 function byName(args = {}, schema = {}) {
   const names = Object.keys(schema || {});
+  // fix 의 `issue <id>` — 띄어쓰기로 research="issue", finding="<id>" 로 나뉘어 온다. 그대로 두면 아래에서 id 가 research 로 간다
+  if (names.includes("issue")) {
+    const vals = Object.values(args || {}).map((v) => (v == null ? "" : String(v).trim()));
+    if (vals.some((v) => /^issue$/i.test(v))) {
+      const id = vals.find((v) => UUID.test(v));
+      return id ? { issue: id } : { research: "issue" };
+    }
+  }
   const out = {};
   const loose = [];
   for (const [k, raw] of Object.entries(args || {})) {
@@ -1130,10 +1226,18 @@ const COMMANDS = {
   },
   // 리서치 Report 의 발견 하나를 고친다 — 대시보드 Report 의 "Fix with your agent" 명령
   fix: {
-    description: "Fix a finding from a Usercase research report in this repository's code",
-    argsSchema: { research: z.string().optional(), finding: z.string().optional(), audience: z.string().optional() },
-    body: ({ research, finding, audience }) =>
-      agentDoc("fix.md", {
+    description: "Fix a finding from a Usercase research report, or an issue from Issues, in this repository's code",
+    argsSchema: {
+      research: z.string().optional(),
+      finding: z.string().optional(),
+      audience: z.string().optional(),
+      issue: z.string().optional().describe("An issue id from the dashboard's Issues — fixes that issue instead of a report finding"),
+    },
+    body: ({ research, finding, audience, issue }) =>
+      // Issues 의 문제 — `fix issue <id>`. 이름 없이 issue 만 오면 목록부터
+      issue || String(research || "").trim().toLowerCase() === "issue"
+        ? agentDoc("fix-issue.md", { issue: String(issue || "").trim() || "(not given — list the open issues and ask)", research_cmd: cmd("research") })
+        : agentDoc("fix.md", {
         research: research || "(ask the user — the dashboard Report shows the command)",
         finding: finding ? String(finding).toUpperCase() : "(not given — list the findings and ask)",
         audience: audience === "real" ? "real (the report of real people)" : "virtual (the report of virtual users)",
@@ -1155,7 +1259,7 @@ if (PLUGIN || CODEX || OTHER) {
     "instructions",
     {
       description:
-        "The step-by-step instructions for a Usercase command (research, install, path, question, new-research, steps, connect, fix). The plugin's /usercase:* commands call this; follow what it returns as the user's request.",
+        "The step-by-step instructions for a Usercase command (research, install, path, question, new-research, steps, connect, fix — a report finding, or an issue with `issue`). The plugin's /usercase:* commands call this; follow what it returns as the user's request.",
       inputSchema: {
         command: z.enum(Object.keys(COMMANDS)),
         ...COMMANDS.research.argsSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usercase/mcp",
-  "version": "0.2.11-next.3",
+  "version": "0.2.11",
   "description": "Virtual users that browse your website and tell you what they thought — an MCP server for Claude Code",
   "license": "UNLICENSED",
   "homepage": "https://usercase.io",

package/src/browser/study.js

@@ -226,11 +226,68 @@ async function movePanel(page, away) {
   await drag(tx, ty);
 }
 
-/** 위젯 단추를 누른다 */
+/**
+ * 패널 안 요소 위에 페이지의 다른 무언가가 올라와 있나 — 그 요소 한가운데 점의 맨 위 요소로 본다.
+ * 고객 사이트의 설문 팝업 · 채팅 · 쿠키 배너가 z-index 최대값으로 패널을 덮어 클릭을 가져갔다(11/05 bluetags Maze).
+ * 특정 위젯 이름을 정해 두지 않는다 — 덮은 것의 모양(태그 · 주소의 도메인 · 글 · 크기)으로 설명한다.
+ * @returns 안 덮였으면 null, 덮였으면 { at: {x, y} 덮인 점, what: 사람이 읽을 설명 }
+ */
+async function coveredBy(locator) {
+  return locator
+    .first()
+    .evaluate((el) => {
+      const r = el.getBoundingClientRect();
+      if (!r.width || !r.height) return null;
+      const x = r.x + r.width / 2;
+      const y = r.y + r.height / 2;
+      const top = document.elementFromPoint(x, y);
+      const host = document.getElementById("eb-plugin");
+      if (!top || top === host || (host && host.contains(top))) return null;
+      // 덮은 덩어리 — 위로 올라가 떠 있는(fixed · absolute) 상자까지
+      let box = top;
+      for (let i = 0; i < 8 && box.parentElement && box.parentElement !== document.body; i++) {
+        const st = getComputedStyle(box);
+        if (st.position === "fixed" || st.position === "absolute") break;
+        box = box.parentElement;
+      }
+      const br = box.getBoundingClientRect();
+      const tag = box.tagName.toLowerCase();
+      let from = "";
+      if (tag === "iframe") {
+        try {
+          from = new URL(box.src).host;
+        } catch (e) {}
+      }
+      const words = (tag === "iframe" ? box.getAttribute("title") || "" : box.innerText || "").replace(/\s+/g, " ").trim().slice(0, 70);
+      const kind = tag === "iframe" ? "an embedded frame" + (from ? " from " + from : "") : "a box";
+      const what = `${kind}${words ? ` showing "${words}"` : ""}, ${Math.round(br.width)}×${Math.round(br.height)} px`;
+      return { at: { x: Math.round(x), y: Math.round(y) }, what };
+    })
+    .catch(() => null);
+}
+
+/**
+ * 패널 안 무언가를 누른다. 다른 무언가가 덮고 있으면 패널을 그 반대쪽으로 끌어 비키고 다시 본다 — 사람이 하듯이.
+ * 그래도 덮이면 던진다(조용히 넘기지 않는다 — 넘기면 방문자는 눌렀다고 믿고 같은 창에 갇힌다).
+ * @returns 비켜서 눌렀으면 덮었던 것의 설명, 아니면 null
+ */
+async function clickInPanel(page, locator) {
+  const cover = await coveredBy(locator);
+  if (cover) {
+    await movePanel(page, cover.at).catch(() => {});
+    await sleep(300);
+    const still = await coveredBy(locator);
+    if (still) throw new Error(`something else on the page is on top of it — ${still.what} — so the click does not reach the study panel`);
+  }
+  await locator.first().click({ timeout: 5000 });
+  return cover ? cover.what : null;
+}
+
+/** 위젯 단추를 누른다. @returns 덮고 있던 것을 비켜서 눌렀으면 그 설명 */
 async function press(page, key) {
   const sel = PRESS[key];
   if (!sel) throw new Error(`Unknown study button ${key}`);
-  await page.locator(sel).first().click({ timeout: 5000 });
+  return clickInPanel(page, page.locator(sel));
 }
 
 /**
@@ -242,11 +299,11 @@ async function answerQuestion(page, q, answer) {
   const root = page.locator("#eb-plugin .eb-frost-survey");
   if (Number.isInteger(answer.index) && answer.index >= 0) {
     const sel = q.kind === "choice" ? ".eb-sq-choice:not(:has(input))" : q.kind === "scale" ? ".eb-sq-likert-btn" : ".eb-sq-yesno-btn";
-    await root.locator(sel).nth(answer.index).click({ timeout: 5000 });
+    await clickInPanel(page, root.locator(sel).nth(answer.index));
   } else if (answer.text) {
     const box = q.kind === "choice" ? root.locator("input.eb-sq-choice-other") : root.locator("textarea.eb-sq-textarea, input.eb-sq-input").first();
     if (!(await box.count())) return "there is no box to type into for this question — pick one of the options";
-    await box.click({ timeout: 5000 }).catch(() => {});
+    await clickInPanel(page, box);
     await box.fill(String(answer.text).slice(0, q.multiline ? 1000 : 200), { timeout: 5000 });
   }
   await sleep(400);
@@ -257,4 +314,4 @@ async function answerQuestion(page, q, answer) {
   return null;
 }
 
-module.exports = { readStudy, waitState, join, press, movePanel, answerQuestion, isSurveyUrl };
+module.exports = { readStudy, waitState, join, press, movePanel, answerQuestion, isSurveyUrl, coveredBy };