@usercase/mcp 0.2.3-next.1 → 0.2.3-next.3

package/README.md

@@ -106,7 +106,7 @@ Claude suggests the moment, the question and its answers, and saves it only afte
 - They stay on your site and block analytics tools such as Google Analytics and Hotjar.
 - Either way they never pay, delete, connect a wallet, sign out or change a password, and never type into personal fields such as email or phone.
 - They stop when blocked. They do not solve CAPTCHAs or get around bot protection.
-- When they cannot do something on your site, a short diagnostic (what failed and the element's shape, never its text) is sent to Usercase so the tool gets better. Turn it off with `USERCASE_DIAGNOSTICS=off`.
+- When the tool cannot do something on your site or misreads the screen, a diagnostic is sent to Usercase so the tool gets better: what failed, the page path, the HTML around the element and a screenshot of that moment. Only the Usercase team sees it, and it is kept for 30 days. Turn it off with `USERCASE_DIAGNOSTICS=off`.
 
 ## Running on a production site
 
@@ -133,7 +133,7 @@ Pass with `claude mcp add ... -e NAME=value`.
 | `USERCASE_API_KEY` | Your project API key. Without it, visits stay on your machine only. |
 | `USERCASE_AGENT_KEY` | Your firewall secret (see above). 16+ characters. |
 | `USERCASE_ALLOW_WRITE_PATHS` | Comma-separated path patterns where non-GET requests are allowed, for sites that load pages with `POST` after sign-in. Everything else stays blocked. |
-| `USERCASE_DIAGNOSTICS` | `off` stops sending diagnostics. On by default: when a visitor cannot do something (a button cut off, covered or unreachable), the kind of failure and the element's shape (tag, icon or not, inside a carousel or dialog, size) are sent to Usercase to improve the tool. No text, addresses or input from your site are sent. |
+| `USERCASE_DIAGNOSTICS` | `off` stops sending diagnostics. On by default: when the tool cannot do something or misreads the screen (a button cut off or covered, a click that landed elsewhere, a change it did not notice), Usercase receives the kind of failure, the element's shape, the page path, the HTML around the element and a screenshot of that moment, to improve the tool. Only the Usercase team sees them; they are kept for 30 days. |
 | `USERCASE_HEADED` | `1` shows the visitors' browser on screen. |
 | `USERCASE_DIR` | Working folder. Default: `.usercase` in your repository. |
 

package/mcp/hub.js

@@ -200,10 +200,10 @@ class Hub {
           ? "· Writes: SENT — visitors really sign up, post, comment and save on this site (payments, deleting and sign-out stay blocked). Change with set_writes"
           : "· Writes: not sent — visitors may press Post or Save, but nothing is written to the site. Ask the user before the first round whether to send them (set_writes)",
       );
-      // 도구가 하지 못한 것(진단) — 사이트 글자·주소 없이 종류와 요소 생김새만 우리 서버로 간다
+      // 도구가 하지 못한 것(진단) — 그 순간의 화면·요소 주변 HTML·페이지 경로가 우리 서버로 간다. 고객에게 숨기지 않는다
       out.push(
         require("../src/run/diag.js").enabled()
-          ? "· Diagnostics on — when a visitor cannot do something (a button cut off, covered, unreachable), the kind of failure and the element's shape (tag, icon, in a carousel …) go to Usercase to improve the tool. No text, addresses or input from the site. Turn off with USERCASE_DIAGNOSTICS=off"
+          ? "· Diagnostics on — when the tool cannot do something or misreads the screen, Usercase gets what failed, the page path, the HTML around the element and a screenshot of that moment, to fix the tool. Only the Usercase team sees them; they are not shown in your dashboard. Turn off with USERCASE_DIAGNOSTICS=off"
           : "· Diagnostics off (USERCASE_DIAGNOSTICS=off)",
       );
       // 지키는 선을 고객이 볼 수 있게. 막혔는데 왜인지 모르면 우리 도구 탓으로 읽힌다
@@ -401,6 +401,11 @@ class Hub {
     const look = await v.look();
     if (look.ended) return "This visit has ended.";
     if (look.card) return renderCard(look.card);
+    // 브라우저 창(confirm 등)이 떠 있다. 페이지는 멈춰 있다 — 아이콘 그림·위치는 안 본다
+    if (look.view.dialog) {
+      this.pictures.set(rec.id, null);
+      return renderScreen(look);
+    }
     const lines = [];
     // 굴리지 않았는데 맨 위로 돌아갔다(창이 닫히며 주소가 바뀐 사이트). 사람은 화면이 튀는 걸 본다(10/21 실험실 q3)
     // 다른 페이지로 간 것은 원래 맨 위에서 시작한다 — 같은 페이지(? 뒤만 바뀐 것 포함)일 때만
@@ -516,15 +521,15 @@ class Hub {
       ms: Date.now() - rec.startedAt,
       sdkReady: rec.visit ? !!rec.visit.sdk?.ready : null,
       ...(rec.account ? { account: rec.account } : {}),
-      // 도구가 하지 못한 것 — 고객도 자기 기록에서 볼 수 있게 같이 남긴다(서버로 가는 것과 같은 내용)
-      ...(rec.visit && rec.visit.diag && rec.visit.diag.length ? { diag: rec.visit.diag } : {}),
+      // 도구가 하지 못한 것 — 고객도 자기 기록에서 볼 수 있게 종류만 남긴다(HTML·화면은 서버로만)
+      ...(rec.visit && rec.visit.diag && rec.visit.diag.length ? { diag: rec.visit.diag.map(({ kind, action, shape, detail }) => ({ kind, action, shape, detail })) } : {}),
       ...extra,
     };
     ws.appendRun(row);
     // 대시보드로 — 키가 없으면 건너뛴다. 실패해도 방문은 끝낸다
     const uploaded = await report.sendVisit(row, rec.person, rec.startedAt, rec.visit ? rec.visit.screens : []).catch((e) => `⚠ Could not upload to the dashboard (${e.message})`);
-    // 도구가 하지 못한 것들 — 우리 쪽 진단으로(사이트 글자 없음). 기본으로 켜져 있다, USERCASE_DIAGNOSTICS=off 로 끈다
-    if (rec.visit && rec.visit.diag && rec.visit.diag.length) await report.sendDiagnostics(rec.visit.diag, rec.person.device).catch(() => 0);
+    // 도구가 하지 못한 것들 — 우리 쪽 진단으로(화면·HTML 포함, 고객 대시보드에는 안 보인다). 기본으로 켜져 있다, USERCASE_DIAGNOSTICS=off 로 끈다
+    if (rec.visit && rec.visit.diag && rec.visit.diag.length) await report.sendDiagnostics(rec.visit.diag, rec.person.device, rec.visit.diagShots).catch(() => 0);
     const doc = ws.loadPeople();
     const p = doc.people.find((x) => x.id === rec.person.id);
     if (p) {

package/mcp/report.js

@@ -168,14 +168,17 @@ async function sendVisit(row, person, startedAt, screens = []) {
 }
 
 /**
- * 도구가 하지 못한 것들(진단)을 보낸다 — 우리 도구를 고치려고. 사이트 글자·주소는 없다(src/run/diag.js).
+ * 도구가 하지 못했거나 잘못 본 것들(진단)을 보낸다 — 우리 도구를 고치려고. 고객 대시보드에는 안 보인다.
+ * 그 순간의 페이지 경로·요소 주변 HTML·화면을 같이 보낸다 — 종류만으로는 못 고친다(10/22, src/run/diag.js).
  * 키가 있고 꺼 두지 않았을 때만. 실패해도 조용히 넘어간다 — 방문과는 상관없다
  */
-async function sendDiagnostics(events, device) {
+async function sendDiagnostics(events, device, shots = []) {
   const diag = require("../src/run/diag.js");
   if (!events || !events.length || !diag.enabled() || !KEY_RE.test(apiKey())) return 0;
   try {
     const out = await call("POST", "/agent/diagnostics", { run: RUN_REF, version: require("../package.json").version, device, events: events.slice(0, 100) });
+    // 화면은 진단 줄이 생긴 뒤에 — 진단 id 로 붙는다
+    for (const s of shots) await call("POST", "/agent/diagnostics/screen", { id: s.id, image: s.image.toString("base64") }).catch(() => null);
     return (out && out.saved) || 0;
   } catch {
     return 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usercase/mcp",
-  "version": "0.2.3-next.1",
+  "version": "0.2.3-next.3",
   "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/hand.js

@@ -137,6 +137,83 @@ async function coveredBy(page, el) {
   return { invisible: true, x: cx, y: cy };
 }
 
+/** 그 점을 지금 누르면 그 요소에 닿나 */
+async function hits(el, x, y) {
+  return el
+    .evaluate((node, [qx, qy]) => {
+      const hit = document.elementFromPoint(qx, qy);
+      return !!hit && (node === hit || node.contains(hit) || hit.contains(node));
+    }, [x, y])
+    .catch(() => false);
+}
+
+/**
+ * 겨눈 곳으로 가서 누른다. 누르기 직전에 그 자리에 아직 그것이 있나 본다 — 저절로 넘어가는 배너는
+ * 커서가 가는 사이 다음 카드가 와서, OKX 를 누르려다 Uniswap 이 열렸다(10/22 실험실 k5). 옮겨 갔으면 다시 겨눈다.
+ * 헛클릭(missed)은 원래 빈 곳이라 그대로 누른다. 끝내 못 맞추면 null
+ */
+async function pressAt(page, state, el, aim) {
+  for (let t = 0; t < 3 && aim; t++) {
+    await moveTo(page, state, aim.x, aim.y);
+    await sleep(rand(40, 140));
+    if (aim.missed || (await hits(el, aim.x, aim.y))) {
+      await page.mouse.click(aim.x, aim.y);
+      return aim;
+    }
+    aim = await aimAt(page, state, el);
+  }
+  return null;
+}
+
+/**
+ * 화면 안에 보이는 같은 것(쌍둥이). 무한히 도는 배너(slick 등)는 카드마다 복사본을 앞뒤에 깔아 둔다 —
+ * 잡은 것이 화면 밖 복사본이면 사람은 화면에 보이는 그 카드를 누른다(10/22 실험실 k5: 같은 카드가 3벌)
+ */
+async function visibleTwin(page, el, vw) {
+  const h = await el
+    .evaluateHandle((node, w) => {
+      const key = (n) => [n.tagName, n.getAttribute("href") || "", (n.textContent || "").replace(/\s+/g, " ").trim()].join("|");
+      const k = key(node);
+      if (k.length < 8) return null;
+      for (const n of document.querySelectorAll(node.tagName)) {
+        if (n === node || key(n) !== k) continue;
+        const r = n.getBoundingClientRect();
+        const cx = r.x + r.width / 2;
+        const cy = r.y + r.height / 2;
+        if (r.width > 0 && cx > 1 && cx < w - 1 && cy > 1 && cy < innerHeight - 1) return n;
+      }
+      return null;
+    }, vw)
+    .catch(() => null);
+  const twin = h && h.asElement();
+  return twin || null;
+}
+
+/**
+ * 저절로 넘어가는 줄(자동 배너)에서 잘린 것 — 사람은 밀지 않고 그 카드가 돌아와 화면 안에 들 때까지 본다.
+ * 3.5초 동안 안 움직이면 멈춰 있는 줄이다(null — 밀어야 한다). 8초 안에 화면 가운데쯤 오면 그것(또는 복사본)
+ */
+async function waitComeAround(page, el, vw) {
+  const first = await el.boundingBox().catch(() => null);
+  if (!first) return null;
+  let moved = false;
+  for (let i = 0; i < 32; i++) {
+    await sleep(250);
+    const b = await el.boundingBox().catch(() => null);
+    if (!b) return null;
+    if (Math.abs(b.x - first.x) > 3) moved = true;
+    // 자동 배너는 보통 3초마다 넘어간다
+    if (!moved && i >= 14) return null;
+    if (!moved) continue;
+    const c = b.x + b.width / 2;
+    if (c > vw * 0.15 && c < vw * 0.85) return el;
+    // 무한 배너는 복사본이 대신 돌아온다
+    const twin = await visibleTwin(page, el, vw);
+    if (twin) return twin;
+  }
+  return null;
+}
+
 /** 손가락으로 옆으로 민다(Chrome 터치 입력). 터치가 없는 화면이면 아무 일 없다 */
 async function touchSwipe(page, x0, x1, y) {
   const cdp = await page.context().newCDPSession(page);
@@ -283,17 +360,29 @@ async function clickLikePerson(page, state, el) {
     // 가로로 넘치는 줄(회전 배너·가로 목록) 안에서 잘린 것이면, 사람은 그 줄을 옆으로 밀어 가져온 뒤 누른다
     // (10/15 실험실 p1·p3: 모바일 첫 화면 배너 끝에 걸친 카드를 끝내 못 눌렀다)
     if (bb && (bb.x + bb.width / 2 > vw - 1 || bb.x + bb.width / 2 < 1)) {
-      const swiped = await swipeIntoView(page, state, el, vw).catch(() => false);
-      if (swiped) {
-        bb = await el.boundingBox().catch(() => null);
-        const again = await aimAt(page, state, el);
-        if (again && bb && bb.x + bb.width / 2 > 1 && bb.x + bb.width / 2 < vw - 1) {
-          await moveTo(page, state, again.x, again.y);
-          await sleep(rand(40, 140));
-          await page.mouse.click(again.x, again.y);
-          return { missed: again.missed, swiped: true };
-        }
+      const twin = await visibleTwin(page, el, vw);
+      if (twin) {
+        const got = await pressAt(page, state, twin, await aimAt(page, state, twin));
+        if (got) return { missed: got.missed };
       }
+      // 저절로 넘어가는 줄이면 밀지 않고 돌아오길 기다린다. 넘어가는 줄을 밀면 반쯤은 엇나가 "잘렸다" 로 끝났다(10/22 실험실 k5)
+      const round = await waitComeAround(page, el, vw);
+      if (round) {
+        const came = await pressAt(page, state, round, await aimAt(page, state, round));
+        if (came) return { missed: came.missed };
+      }
+      await swipeIntoView(page, state, el, vw).catch(() => false);
+      // 무한 배너는 밀고 나면 잡은 것 대신 그 복사본이 화면에 와 있다 — 화면에 든 쪽을 누른다(10/22 실험실 k5)
+      bb = await el.boundingBox().catch(() => null);
+      const inView = bb && bb.x + bb.width / 2 > 1 && bb.x + bb.width / 2 < vw - 1;
+      const target = inView ? el : await visibleTwin(page, el, vw);
+      const done = target ? await pressAt(page, state, target, await aimAt(page, state, target)) : null;
+      if (done) return { missed: done.missed, swiped: true };
+      // 밀어도 못 가져왔다 — 저절로 넘어가는 줄이면 한 번 더 돌아오길 기다린다
+      const later = await waitComeAround(page, el, vw);
+      const came = later ? await pressAt(page, state, later, await aimAt(page, state, later)) : null;
+      if (came) return { missed: came.missed, swiped: true };
+      bb = await el.boundingBox().catch(() => null);
     }
     if (bb && (bb.x + bb.width / 2 > vw - 1 || bb.x + bb.width / 2 < 1)) {
       const say = bb.x < vw && bb.x + bb.width > 0 ? "it is cut off at the edge of the screen — only a sliver of it shows, and you cannot reach it" : "it is off the edge of the screen and you cannot reach it";
@@ -305,10 +394,24 @@ async function clickLikePerson(page, state, el) {
     await el.click({ timeout: 8000 });
     return { missed: false };
   }
-  await moveTo(page, state, aim.x, aim.y);
-  await sleep(rand(40, 140));
-  await page.mouse.click(aim.x, aim.y);
-  return { missed: aim.missed };
+  const done = await pressAt(page, state, el, aim);
+  if (done) return { missed: done.missed };
+  // 누르려는 사이 자꾸 옮겨 갔다 — 저절로 넘어가는 줄이다. 한 번 돌아오길 기다려 본다
+  const vw = (page.viewportSize() || { width: 1200 }).width;
+  const twin = await visibleTwin(page, el, vw);
+  if (twin) {
+    const got = await pressAt(page, state, twin, await aimAt(page, state, twin));
+    if (got) return { missed: got.missed };
+  }
+  const round = await waitComeAround(page, el, vw);
+  if (round) {
+    const came = await pressAt(page, state, round, await aimAt(page, state, round));
+    if (came) return { missed: came.missed };
+  }
+  const say = "it slid away as you went to tap it — that row moves by itself";
+  const e = new Error(say);
+  e.human = say;
+  throw e;
 }
 
 const NEAR = { a: "s", s: "d", d: "f", f: "g", g: "h", h: "j", j: "k", k: "l", l: "k", q: "w", w: "e", e: "r", r: "t", t: "y", y: "u", u: "i", i: "o", o: "p", p: "o", z: "x", x: "c", c: "v", v: "b", b: "n", n: "m", m: "n" };

package/src/run/diag.js

@@ -5,8 +5,10 @@
  * 사이트마다 다른 이유로 막힌다(회전 배너를 밀 수 없어서, 화면 밖으로 잘려서, 덮개 때문에 …).
  * bluetags 하나로는 다 못 찾는다(10/15 — 스와이프가 없어서 배너 끝 카드를 못 눌렀다).
  *
- * **사이트 글자·주소·입력값은 보내지 않는다.** 실패의 종류와 요소의 생김새(태그·역할·아이콘인지·회전 배너 안인지·
- * 고정 위치인지·대화상자 안인지·크기)만. 고객 방문 기록(/agent/visits)과 따로 간다.
+ * 실패의 종류와 요소의 생김새(태그·역할·아이콘인지·회전 배너 안인지·고정 위치인지·대화상자 안인지·크기)에 더해
+ * 그 순간의 페이지 경로·요소 주변 HTML·화면을 보낸다(10/22 — 종류만으로는 무한 배너 복사본 같은 원인을 못 찾았다).
+ * 우리만 본다 — 고객 대시보드에는 안 보인다. 고객 방문 기록(/agent/visits)과 따로 간다.
+ * 도구가 못 한 것뿐 아니라 잘못 본 것도 — 방문자의 다음 말과 도구 판단이 엇갈리면(visit.js checkLastJudgement)
  * 기본으로 켜져 있고 USERCASE_DIAGNOSTICS=off 로 끈다. API 키가 있을 때만 간다(키가 프로젝트를 정한다).
  */
 
@@ -17,6 +19,7 @@ const enabled = () => !OFF.test(String(process.env.USERCASE_DIAGNOSTICS || "").t
 function kindOf(skipped) {
   const s = String(skipped || "");
   if (/cut off at the edge|off the edge of the screen/.test(s)) return "cut_off";
+  if (/slid away as you went to tap it/.test(s)) return "moving";
   if (/survey card is on top/.test(s)) return "covered_by_card";
   if (/on top of it/.test(s)) return "covered";
   if (/greyed out/.test(s)) return "disabled";

package/src/run/visit.js

@@ -18,6 +18,7 @@
  */
 const fs = require("fs");
 const path = require("path");
+const { randomUUID } = require("crypto");
 const { listControls, visibleText, handleAt, clickBlocked } = require("../browser/page.js");
 const { readCard, waitCard, screenText, answerCard, noteReason, sleep, waitForSdk } = require("../browser/card.js");
 const hand = require("../browser/hand.js");
@@ -54,6 +55,15 @@ const MAX_TIMES = { click: 4, scroll: 5, scroll_up: 5 };
  * 누른 곳(box)은 사진에 그리지 않고 걸음에 비율(0~1)로 적는다. 대시보드가 위에 그린다
  */
 const MAX_SCREENS = 6;
+/** 진단(도구가 못 했거나 잘못 본 것)마다 찍는 화면 — 우리만 본다. 고객 대시보드에는 안 간다(10/22) */
+const MAX_DIAG_SHOTS = 6;
+/** 진단에 붙이는 요소 주변 HTML 길이 */
+const MAX_DIAG_HTML = 6000;
+/** 진단으로 볼 만한 것이 아니다 — 의도한 동작(밀어서 가져옴·사람 같은 헛클릭) */
+const DIAG_NO_CONTEXT = new Set(["swiped", "missed"]);
+// 방문자가 바로 다음에 하는 말 — 도구 판단과 엇갈리면 도구가 잘못 본 것이다
+const SAYS_CHANGED = /\b(saved|bookmarked|liked|went (blue|red|green|grey|gray|dark|bold)|turned (blue|red|green|on|off)|it (worked|opened|changed)|that (worked|opened)|now (shows|says)|popped (up|open)|opened up)\b/i;
+const SAYS_NOTHING = /\b(nothing happened|nothing changed|didn.?t (open|work|do anything|respond|change|load|go anywhere)|not (working|responding|loading)|won.?t (open|load|work)|still the same|no response|dead)\b/i;
 // 서버 앞 nginx 의 기본 본문 한도가 1MB 다 — base64 로 커지니 원본은 600KB 아래로
 const MAX_SCREEN_BYTES = 600 * 1024;
 
@@ -64,13 +74,24 @@ const MAX_SCREEN_BYTES = 600 * 1024;
 async function errorScreen(page) {
   return page
     .evaluate(() => {
-      const t = ((document.body && document.body.innerText) || "").replace(/s+/g, " ").trim();
+      const t = ((document.body && document.body.innerText) || "").replace(/\s+/g, " ").trim();
       if (t.length > 600) return false;
-      return /(404|500|502|503)|not found|page (doesn.?t|does not|could not|cannot) (exist|be found)|application error|something went wrong|internal server error/i.test(t);
+      return /\b(404|500|502|503)\b|not found|page (doesn.?t|does not|could not|cannot) (exist|be found)|application error|something went wrong|internal server error/i.test(t);
     })
     .catch(() => false);
 }
 
+/** 같은 사이트 주소의 경로(+쿼리). 다른 사이트면 null */
+function sameDocPath(href, base) {
+  try {
+    const u = new URL(href, base);
+    if (u.origin !== new URL(base).origin) return null;
+    return (u.pathname.replace(/\/+$/, "") || "/") + u.search;
+  } catch {
+    return null;
+  }
+}
+
 /** 요소가 화면에서 차지한 곳(화면 비율). 화면 밖이거나 사라졌으면 null */
 async function boxOf(page, el) {
   const b = el ? await el.boundingBox().catch(() => null) : null;
@@ -86,7 +107,7 @@ async function boxOf(page, el) {
 }
 
 /**
- * 누르기 전후를 견줄 지문 — 주소, 페이지 전체 글(보이는 것만, 굴려도 같다), 보이는 입력칸·그림, 누른 요소의 상태(색만 바뀌는 좋아요·토글).
+ * 누르기 전후를 견줄 지문 — 주소, 페이지 전체 글(보이는 것만, 굴려도 같다), 보이는 입력칸·그림, 누른 요소와 감싼 버튼의 상태·HTML(색만 바뀌는 좋아요·저장·토글).
  * 입력칸은 글(innerText)에 안 잡힌다 — 검색 아이콘을 눌러 검색칸이 열렸는데 "그대로" 로 찍혔다(10/22 실험실 e4)
  * 글이 저절로 바뀌는 사이트(넘어가는 배너)에서는 "바뀌었다" 로 본다 — 그대로라고 잘못 찍는 것보다 낫다
  */
@@ -109,11 +130,21 @@ async function clickPrint(page, el) {
     .catch(() => null);
   const own = el
     ? await el
-        .evaluate((n) =>
-          n.isConnected
-            ? [n.className && String(n.className), ...["aria-pressed", "aria-expanded", "aria-checked", "aria-selected", "aria-current", "data-state"].map((a) => n.getAttribute(a)), n.checked, n.value, (n.textContent || "").slice(0, 200)].join("|")
-            : null,
-        )
+        .evaluate((n) => {
+          if (!n.isConnected) return null;
+          // 색만 바뀌는 아이콘(저장·좋아요)은 속의 svg 나 감싼 버튼의 속성·클래스가 바뀐다 — 그 HTML 까지 본다.
+          // 누른 요소만 봤더니 북마크가 파랗게 됐는데 "그대로" 로 찍혔다(10/22 bluetags 저장).
+          // 계산된 색은 안 본다 — 누르기 전에는 커서가 없어서 마우스를 올린 색(hover)만으로 "바뀌었다" 가 된다
+          const host = n.closest("a,button,[role],label") || n.parentElement || n;
+          return [
+            n.className && String(n.className),
+            ...["aria-pressed", "aria-expanded", "aria-checked", "aria-selected", "aria-current", "data-state"].map((a) => n.getAttribute(a)),
+            n.checked,
+            n.value,
+            (n.textContent || "").slice(0, 200),
+            host.outerHTML.slice(0, 3000),
+          ].join("|");
+        })
         .catch(() => null)
     : null;
   return { url: page.url(), doc, own };
@@ -374,6 +405,8 @@ class Visit {
     this.externalTold = new Set();
     /** 도구가 하지 못한 것들 — 방문이 끝나면 hub 가 서버로 보낸다(diag.js). 사이트 글자는 없다 */
     this.diag = [];
+    /** 진단 순간의 화면 { id(진단 id), image } — 우리 쪽으로만 간다 */
+    this.diagShots = [];
     this.log = log;
     // 손은 방문 내내 이어진다 — 커서가 있던 자리에서 다음 곳으로 간다
     this.handState = { rhythm, mouse: null };
@@ -411,6 +444,113 @@ class Visit {
         .then((a) => (this.fileWindow = { accept: a || "" }))
         .catch(() => {});
     });
+    /**
+     * 브라우저 창(alert·confirm·prompt). 듣지 않으면 Playwright 가 조용히 "취소" 한다 — bluetags 커뮤니티 나가기는
+     * "Are you sure you want to leave?" 가 세 번 다 취소돼 "눌러도 그대로" 로 찍히고 고객 화면에 사이트 탓으로 나갔다(10/22 p2038).
+     * 창이 떠 있는 동안 페이지는 멈추고 누르기도 안 끝난다 — 방문자에게 문구를 보여 주고 고르게 한다(answerDialog)
+     */
+    this.dialog = null;
+    this.dialogWake = null;
+    this.dialogWork = null;
+    this.dialogText = null;
+    this.acting = false;
+    this.curRecord = null;
+    page.on("dialog", (d) => this.onDialog(d));
+  }
+
+  /** 창이 떴다. 걸음 중이면 방문자에게 넘기고, 아니면(화면 보는 중·카드) 사람이 그냥 넘기듯 닫는다 — 열어 두면 페이지가 멈춘다 */
+  onDialog(d) {
+    const type = d.type();
+    const message = String(d.message() || "").slice(0, 500);
+    // 떠나며 "저장 안 한 내용이 있다" 는 사람도 대개 떠난다
+    if (type === "beforeunload") return void d.accept().catch(() => {});
+    if (!this.acting || this.dialog) {
+      (type === "alert" ? d.accept() : d.dismiss()).catch(() => {});
+      this.history.push(`A box from the browser popped up saying "${message}" and went away.`);
+      return;
+    }
+    this.dialog = { d, type, message, defaultValue: d.defaultValue() || "", path: this.pathNow() };
+    this.dialogText = null;
+    if (this.dialogWake) this.dialogWake();
+  }
+
+  pathNow() {
+    try {
+      const u = new URL(this.page.url());
+      return u.pathname + u.search;
+    } catch {
+      return "";
+    }
+  }
+
+  /** 창 안에서 고를 것 — 화면의 번호 목록처럼 준다 */
+  dialogItems() {
+    const d = this.dialog;
+    const ok = { key: "ok", label: "OK", where: "in the box" };
+    const cancel = { key: "cancel", label: "Cancel", where: "in the box" };
+    const items = d.type === "alert" ? [ok] : d.type === "prompt" ? [{ key: "field", label: "(text box)", where: "in the box" }, ok, cancel] : [ok, cancel];
+    return items.map((it, i) => ({ ...it, i }));
+  }
+
+  /** 창이 떠 있는 화면. 페이지를 읽을 수 없다(멈춰 있다) — 창만 보인다 */
+  dialogLook() {
+    const d = this.dialog;
+    const what = d.type === "alert" ? "A message box from the browser popped up over the page:" : d.type === "prompt" ? "A box from the browser popped up over the page, asking you to type something:" : "A box from the browser popped up over the page, asking:";
+    const lines = [what, "", d.message || "(no text)", ""];
+    if (d.type === "prompt") lines.push(this.dialogText !== null ? `You have typed: ${this.dialogText}` : d.defaultValue ? `It already says: ${d.defaultValue}` : "The text box is empty.", "");
+    lines.push(d.type === "alert" ? "The page behind it is frozen until you close the box." : "The page behind it is frozen until you answer.");
+    const view = { path: d.path, scrollY: 0, height: 0, viewport: 0, items: this.dialogItems().map(({ i, label, where }) => ({ i, label, where })), dialog: true };
+    return { view, text: lines.join("\n") };
+  }
+
+  /**
+   * 창에 답한다 — OK·Cancel 을 누르거나 prompt 칸에 친다. 원래 걸음(_act)은 창이 닫힌 뒤 마저 끝난다.
+   * 고른 것은 그 걸음 기록에 붙는다(record.dialogs). 다른 조작은 창이 막는다 — 떠나기는 Cancel 하고 떠난다
+   */
+  async answerDialog(decision) {
+    await this.waitTurn();
+    const dl = this.dialog;
+    const item = this.dialogItems()[decision.index];
+    let choice = null;
+    if (decision.action === "leave") choice = "cancel";
+    else if (decision.action === "type" && item && item.key === "field") {
+      this.dialogText = String(decision.text || "").slice(0, 200);
+      await sleep(800 + Math.random() * 1500);
+      this.nextAt = Date.now() + 600;
+      return { dialog: true };
+    } else if (decision.action === "click" && item && item.key !== "field") choice = item.key;
+    else if (decision.action === "click" && item) return { skipped: "you can only type into that text box" };
+    else return { skipped: decision.action === "click" || decision.action === "type" ? "that number is not on the screen" : "the box from the browser is still open on top of the page — answer it first" };
+
+    this.dialog = null;
+    const answer = choice === "ok" ? (dl.type === "prompt" ? "typed and pressed OK" : "OK") : "Cancel";
+    await (choice === "ok" ? dl.d.accept(dl.type === "prompt" ? this.dialogText ?? dl.defaultValue : undefined) : dl.d.dismiss()).catch(() => {});
+    if (this.curRecord) (this.curRecord.dialogs = this.curRecord.dialogs || []).push({ type: dl.type, message: dl.message, answer, why: decision.why, t: Date.now() - this.t0 });
+    this.log(`  browser box "${dl.message.slice(0, 40)}" → ${answer}`);
+    // 원래 걸음이 마저 끝나기를 본다. 창이 또 뜨면 다시 방문자에게
+    const r = await this.untilDialog(this.dialogWork);
+    if (r && r.dialog) return r;
+    this.dialogWork = null;
+    if (decision.action === "leave") return this.act(decision);
+    return r || { step: this.steps.length };
+  }
+
+  /** 걸음을 하다가 창이 뜨면 거기서 돌려준다({ dialog: true }) — 걸음은 창이 닫힌 뒤 마저 간다 */
+  async untilDialog(work) {
+    let wake;
+    const seen = new Promise((res) => (wake = res));
+    this.dialogWake = wake;
+    this.acting = true;
+    const first = await Promise.race([work.then((r) => ({ r })), seen.then(() => null)]);
+    if (first) {
+      this.acting = false;
+      this.dialogWake = null;
+      return first.r;
+    }
+    this.dialogWork = work;
+    // 창 글을 읽는 시간
+    this.nextAt = Date.now() + 1200 + Math.min(4000, this.dialog.message.length * 40);
+    return { dialog: true };
   }
 
   /**
@@ -456,6 +596,8 @@ class Visit {
    */
   async look() {
     if (this.ended) return { ended: true };
+    // 브라우저 창이 떠 있다. 페이지는 멈춰 있어 읽으면 걸린다 — 창만 보여 준다
+    if (this.dialog) return this.dialogLook();
     if (!this.card && !this.pending) {
       const shown = await waitCard(this.page, 500);
       if (shown) this.pending = shown;
@@ -512,8 +654,14 @@ class Visit {
    * 한 걸음. decision 은 STEP_SCHEMA 모양({ why, action, index, text, done, times }).
    * 번호는 마지막 look() 화면 기준이다. 떠나면 끝나고, 떠나는 순간 뜬 카드가 있으면 pending 에 남는다.
    * 보고 있던 사이에 카드가 떴으면 하려던 걸 하지 않고 { interrupted: true } 를 돌려준다 — 카드부터 본다.
+   * 하는 도중 브라우저 창이 뜨면 { dialog: true } — 다음 look() 이 창을 보여 주고, 다음 act() 가 창에 답한다
    */
   async act(decision) {
+    if (this.dialog) return this.answerDialog(decision);
+    return this.untilDialog(this._act(decision));
+  }
+
+  async _act(decision) {
     if (this.ended) throw new Error("This visit has already ended");
     if (this.pending) throw new Error("A card is showing — answer or close it first");
     await this.waitTurn();
@@ -529,6 +677,9 @@ class Visit {
     const view = this.lastView || (await listControls(page));
     const item = view.items[decision.index];
     const record = { step: this.steps.length + 1, t: Date.now() - this.t0, path: view.path, action: decision.action, why: decision.why, label: item?.label ?? null };
+    this.curRecord = record;
+    await this.checkLastJudgement(decision);
+    const diagFrom = this.diag.length;
     const times = Math.max(1, Math.min(MAX_TIMES[decision.action] || 1, Math.round(Number(decision.times) || 1)));
     if (times > 1) record.times = times;
     // 한 번에 할 수 있는 수보다 많이 달라고 했다. 말없이 줄이면 "사이트가 클릭을 삼킨다" 로 읽었다(10/20 실험실 p7: 15·20·30번이 다 4번)
@@ -700,7 +851,8 @@ class Visit {
           // 안 눌린다 싶어 거듭 누른다. 화면이 바뀌면 멈춘다
           for (let i = 1; i < times && !record.skipped && this.handState.mouse; i++) {
             await sleep(150 + Math.random() * 450);
-            if (page.url() !== before || this.offsite.length > offsiteBefore) break;
+            // 창이 떴었다 — 화면이 반응한 것이다. 또 누르면 같은 창이 또 뜬다
+            if (page.url() !== before || this.offsite.length > offsiteBefore || record.dialogs) break;
             await page.mouse.click(this.handState.mouse.x, this.handState.mouse.y).catch(() => {});
           }
           if ((await settle(page, before, net)).navTimeout) this.diag.push({ kind: "nav_timeout", action: "click", shape: await diag.shapeOf(el) });
@@ -761,10 +913,12 @@ class Visit {
     )
       await this.shoot(record, "error");
 
-    // 눌렀는데 그대로. 우리 쪽 사정(빗나감·막은 요청·바깥 사이트·파일 창)으로 그대로인 것은 빼고, 같은 것은 한 번만
+    // 눌렀는데 그대로. 우리 쪽 사정(빗나감·막은 요청·바깥 사이트·파일 창)으로 그대로인 것은 빼고, 같은 것은 한 번만.
+    // 브라우저 창이 떴으면 반응한 것이다 — Cancel 을 골라 그대로인 것은 사이트 탓이 아니다
     if (
       probe &&
       !record.skipped &&
+      !record.dialogs &&
       !record.missed &&
       !record.closedOverlay &&
       !record.offsite &&
@@ -781,9 +935,18 @@ class Visit {
         await this.shoot(record, "no_change", await boxOf(page, probe.el));
     }
 
+    // 누른 링크와 다른 곳으로 왔다 — 움직이는 줄에서 다른 카드를 눌렀을 수 있다(10/22 실험실 k5: OKX 를 눌렀는데 Uniswap).
+    // 사이트가 돌려보낸 것(로그인 등)일 수도 있다 — 우리가 보고 가린다
+    if (decision.action === "click" && !record.skipped && !record.offsite && item?.href && page.url() !== before) {
+      const want = sameDocPath(item.href, before);
+      const got = sameDocPath(page.url(), before);
+      if (want && got && want !== got) this.diag.push({ kind: "landed_elsewhere", action: "click", shape: await diag.shapeOf(probe && probe.el) });
+    }
+    await this.diagContext(record, diagFrom, probe ? probe.el : diagEl);
+
     this.steps.push(record);
     this.history.push(
-      `${decision.action}${times > 1 ? ` ×${times}` : ""}${item ? ` "${item.label}"` : ""} — ${decision.why}${record.skipped ? ` (${record.skipped})` : ""}${record.cappedTimes ? " (that is the most in one go)" : ""}${record.offsite ? ` (it leads to another website, ${record.offsite})` : ""}${record.notSent ? " (it would have sent something to the site; it was not sent)" : ""}${record.fileWindow ? " (a window to choose a file opened; you closed it without choosing)" : ""}${record.personalField !== undefined ? " (you chose not to enter personal details there)" : ""}${record.openedApp ? " (it tried to open another app; nothing opened)" : ""}${record.backOut ? " (going back from here would have taken you off the site; you stayed)" : ""}`,
+      `${decision.action}${times > 1 ? ` ×${times}` : ""}${item ? ` "${item.label}"` : ""} — ${decision.why}${record.skipped ? ` (${record.skipped})` : ""}${record.cappedTimes ? " (that is the most in one go)" : ""}${record.offsite ? ` (it leads to another website, ${record.offsite})` : ""}${record.notSent ? " (it would have sent something to the site; it was not sent)" : ""}${record.fileWindow ? " (a window to choose a file opened; you closed it without choosing)" : ""}${record.personalField !== undefined ? " (you chose not to enter personal details there)" : ""}${record.openedApp ? " (it tried to open another app; nothing opened)" : ""}${record.backOut ? " (going back from here would have taken you off the site; you stayed)" : ""}${(record.dialogs || []).map((d) => ` (a box from the browser said "${d.message.slice(0, 120)}"; you pressed ${d.answer === "Cancel" ? "Cancel" : "OK"})`).join("")}`,
     );
     this.log(`${record.step}. ${decision.action}${item ? ` "${String(item.label).slice(0, 30)}"` : ""}${record.skipped ? ` · ${record.skipped}` : ""} — ${decision.why}`);
     this.lastView = null;
@@ -806,6 +969,64 @@ class Visit {
       this.diag.push({ kind: "reclick_same", action, shape: await diag.shapeOf(el) });
   }
 
+  /**
+   * 바로 앞 걸음에 대한 도구 판단이 방문자의 다음 말과 엇갈리나. 엇갈리면 도구가 잘못 본 것이다 — 진단으로 남긴다.
+   *  - "눌렀는데 그대로" 로 찍었는데 방문자는 "저장됐다·파랗게 됐다·열렸다" 고 한다 → 그 사진은 고객에게 안 보낸다
+   *    (10/22 bluetags 저장: 북마크가 파랗게 됐는데 그대로로 찍혔다)
+   *  - 화면이 바뀌었다고 봤는데 방문자는 "아무 일 없다·안 열린다" 고 한다
+   * 방문자의 말은 사이트 글자가 아니라 우리 AI 가 쓴 말이다
+   */
+  async checkLastJudgement(decision) {
+    const last = this.steps[this.steps.length - 1];
+    if (!last || last.action !== "click" || last.skipped || !decision.why) return;
+    const from = this.diag.length;
+    if (last.screen && last.screen.kind === "no_change" && SAYS_CHANGED.test(decision.why)) {
+      this.diag.push({ kind: "no_change_doubt", action: "click", detail: `step ${last.step}` });
+      this.screens = this.screens.filter((x) => x.step !== last.step);
+      delete last.screen;
+    } else if (!last.screen && !last.missed && !last.closedOverlay && SAYS_NOTHING.test(decision.why)) {
+      this.diag.push({ kind: "visitor_saw_nothing", action: "click", detail: `step ${last.step}` });
+    }
+    // 지금 화면이 그 걸음 바로 뒤의 화면이다
+    if (this.diag.length > from) await this.diagContext(last, from, null);
+  }
+
+  /**
+   * 이번 걸음에 생긴 진단에 그 순간을 붙인다 — 화면(우리만 본다), 요소 주변 HTML, 페이지 경로.
+   * 종류와 생김새만으로는 못 고친다: 10/22 무한 배너는 "잘림·회전 배너" 까지만 알았고, 같은 카드 복사본 때문인 건 열어 봐야 알았다
+   */
+  async diagContext(record, from, el) {
+    const events = this.diag.slice(from).filter((e) => !e.id && !DIAG_NO_CONTEXT.has(e.kind));
+    if (!events.length) return;
+    let pagePath = null;
+    try {
+      const u = new URL(this.page.url());
+      pagePath = (u.pathname + u.search).slice(0, 300);
+    } catch {}
+    const html = el
+      ? await el
+          .evaluate((n, max) => {
+            if (!n.isConnected) return null;
+            let best = n;
+            for (let p = n.parentElement, d = 0; p && p !== document.body && d < 4; p = p.parentElement, d++) if (p.outerHTML.length <= max) best = p;
+            return best.outerHTML.slice(0, max);
+          }, MAX_DIAG_HTML)
+          .catch(() => null)
+      : null;
+    let shotId = null;
+    if (this.diagShots.length < MAX_DIAG_SHOTS) {
+      const image = await this.snap();
+      if (image) shotId = randomUUID();
+      if (image) this.diagShots.push({ id: shotId, image });
+    }
+    events.forEach((e, i) => {
+      e.id = i === 0 && shotId ? shotId : randomUUID();
+      e.step = record.step;
+      if (pagePath) e.path = pagePath;
+      if (html) e.html = html;
+    });
+  }
+
   /**
    * 문제가 있던 화면을 찍어 이 걸음에 붙인다(record.screen). 보이는 만큼만(뷰포트). 크면 한 번 더 작게, 그래도 크면 안 찍는다
    * 실패해도 방문은 그대로 간다