@usercase/mcp 0.2.2-next.5 → 0.2.3-next.0

package/mcp/hub.js

@@ -459,6 +459,7 @@ class Hub {
     if (r.sentWithEnter) said.push("You pressed Enter to send it, as you would in a chat box.");
     if (r.heldEnter) said.push("The screen changed as you typed, so you did not press Enter — what you see is what typing alone did. If you would press Enter now, type the same text into that field again.");
     if (r.fileWindow) said.push(r.fileWindow);
+    if (r.backOut) said.push("This is the first page you opened on this site, so going back from here would take you off the site. You are still on the page you were on — if leaving the site is what you meant, leave; otherwise carry on here.");
     if (r.openedApp) said.push("That tried to open another app outside the browser (a share or app link). Nothing opened, and you are back on the page you were on.");
     if (r.swiped) said.push("It was cut off at the edge, so you swiped that row sideways to bring it into view, then tapped it.");
     // 개인정보 칸. 사이트가 막은 게 아니라 이 사람이 안 친 것이다 — 그렇게 알린다
@@ -521,7 +522,7 @@ class Hub {
     };
     ws.appendRun(row);
     // 대시보드로 — 키가 없으면 건너뛴다. 실패해도 방문은 끝낸다
-    const uploaded = await report.sendVisit(row, rec.person, rec.startedAt).catch((e) => `⚠ Could not upload to the dashboard (${e.message})`);
+    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);
     const doc = ws.loadPeople();

package/mcp/report.js

@@ -123,13 +123,32 @@ function payload(row, person, startedAt) {
   };
 }
 
+/**
+ * 문제가 있던 순간의 화면을 방문 id 로 먼저 올린다(서버 R2 screens/). 못 올린 걸음은 표시를 지운다 —
+ * 대시보드가 없는 사진 자리를 남기지 않게. 사진은 다시 보내지 않는다(outbox 에 넣지 않는다)
+ */
+async function sendScreens(item, screens) {
+  if (!screens || !screens.length) return item;
+  const failed = new Set();
+  for (const s of screens) {
+    try {
+      await call("POST", "/agent/screens", { id: item.id, step: s.step, image: s.image.toString("base64") }, 30000);
+    } catch {
+      failed.add(s.step);
+    }
+  }
+  const sent = new Set(screens.map((s) => s.step).filter((n) => !failed.has(n)));
+  return { ...item, steps: (item.steps || []).map((s) => (s && s.screen && !sent.has(s.step) ? { ...s, screen: undefined } : s)) };
+}
+
 /**
  * 방문 하나를 보내고, 전에 못 보낸 것도 같이 보낸다. 실패해도 방문은 막지 않는다 — 결과 한 줄만 돌려준다.
+ * @param screens  문제가 있던 순간의 화면 [{ step, image }] (Visit.screens)
  * @returns 요약에 붙일 한 줄, 키가 없으면 null
  */
-async function sendVisit(row, person, startedAt) {
+async function sendVisit(row, person, startedAt, screens = []) {
   if (!KEY_RE.test(apiKey())) return null;
-  const queue = [...readOutbox(), payload(row, person, startedAt)];
+  const queue = [...readOutbox(), await sendScreens(payload(row, person, startedAt), screens)];
   const left = [];
   let sent = 0;
   let lastErr = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usercase/mcp",
-  "version": "0.2.2-next.5",
+  "version": "0.2.3-next.0",
   "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/run/visit.js

@@ -42,6 +42,58 @@ const STEP_SCHEMA = {
 /** 같은 조작을 연달아 몇 번까지. 굴리며 훑기·안 눌려서 거듭 누르기 */
 const MAX_TIMES = { click: 4, scroll: 5, scroll_up: 5 };
 
+/**
+ * 문제가 있던 순간의 화면 — 대시보드가 그 걸음 아래에 보인다(서버 /agent/screens). **방문자(AI)에게는 안 보인다.**
+ * 걸음마다 찍지 않는다. 영상(세션 리플레이)은 봇의 움직임이 드러나 쓰지 않기로 했다(10/21)
+ *   no_change    눌렀는데 화면이 그대로
+ *   left_unhappy 원하던 걸 못 이루고 떠남(leave, done=false) — 마지막 화면
+ *   bounced      들어오자마자 뒤로
+ *   card         질문 카드가 뜬 화면 — 카드는 걸음이 아니라 바로 앞 걸음에 붙인다(첫 걸음 전이면 다음 걸음)
+ * 누른 곳(box)은 사진에 그리지 않고 걸음에 비율(0~1)로 적는다. 대시보드가 위에 그린다
+ */
+const MAX_SCREENS = 6;
+// 서버 앞 nginx 의 기본 본문 한도가 1MB 다 — base64 로 커지니 원본은 600KB 아래로
+const MAX_SCREEN_BYTES = 600 * 1024;
+
+/** 요소가 화면에서 차지한 곳(화면 비율). 화면 밖이거나 사라졌으면 null */
+async function boxOf(page, el) {
+  const b = el ? await el.boundingBox().catch(() => null) : null;
+  const vp = page.viewportSize();
+  if (!b || !vp || b.width <= 0 || b.height <= 0) return null;
+  const x0 = Math.max(0, b.x);
+  const y0 = Math.max(0, b.y);
+  const x1 = Math.min(vp.width, b.x + b.width);
+  const y1 = Math.min(vp.height, b.y + b.height);
+  if (x1 <= x0 || y1 <= y0) return null;
+  const r = (n) => Math.round(n * 1000) / 1000;
+  return { x: r(x0 / vp.width), y: r(y0 / vp.height), w: r((x1 - x0) / vp.width), h: r((y1 - y0) / vp.height) };
+}
+
+/**
+ * 누르기 전후를 견줄 지문 — 주소, 페이지 전체 글(보이는 것만, 굴려도 같다), 누른 요소의 상태(색만 바뀌는 좋아요·토글).
+ * 글이 저절로 바뀌는 사이트(넘어가는 배너)에서는 "바뀌었다" 로 본다 — 그대로라고 잘못 찍는 것보다 낫다
+ */
+async function clickPrint(page, el) {
+  const doc = await page
+    .evaluate(() => {
+      const t = (document.body && document.body.innerText) || "";
+      let h = 5381;
+      for (let i = 0; i < t.length; i++) h = ((h << 5) + h + t.charCodeAt(i)) | 0;
+      return `${t.length}:${h}`;
+    })
+    .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,
+        )
+        .catch(() => null)
+    : null;
+  return { url: page.url(), doc, own };
+}
+
 /**
  * 클릭 뒤 화면이 자리 잡기를 기다린다. 사람도 눌렀으면 뜰 때까지 본다.
  * 안 기다리면 느린 화면이 "눌러도 안 열린다" 로 읽힌다 — 10/13 bluetags 에서 카드가 "안 열린다 → 조금 뒤 열렸다".
@@ -301,6 +353,8 @@ class Visit {
     // 손은 방문 내내 이어진다 — 커서가 있던 자리에서 다음 곳으로 간다
     this.handState = { rhythm, mouse: null };
     this.steps = [];
+    /** 문제가 있던 순간의 화면 { step, image(JPEG) } — 방문이 끝나면 hub 가 서버로 올린다 */
+    this.screens = [];
     this.history = [];
     this.seenPaths = new Set();
     this.card = null; // 처리한 카드(한 방문에 하나)
@@ -393,6 +447,9 @@ class Visit {
   async answer(decision) {
     const shown = this.pending;
     if (!shown) throw new Error("No card is showing");
+    // 첫 걸음 전에 뜬 카드(들어오자마자)는 붙일 걸음이 없다 — 찍어 두었다가 다음 걸음에 붙인다(10/22 실험실 w5)
+    if (this.steps.length) await this.shoot(this.steps[this.steps.length - 1], "card");
+    else this.early = { kind: "card", image: await this.snap() };
     const act = answer.toAction(decision, shown);
     // 카드를 읽고 정하는 시간. 닫는 건 금방, 쓰는 건 치는 만큼
     await sleep(act.kind === "close" ? 600 + Math.random() * 1800 : 1500 + Math.random() * 3000);
@@ -443,6 +500,13 @@ 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 };
+    if (this.early) {
+      if (this.early.image && this.screens.length < MAX_SCREENS) {
+        record.screen = { kind: this.early.kind, box: null };
+        this.screens.push({ step: record.step, image: this.early.image });
+      }
+      this.early = null;
+    }
     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번)
@@ -456,6 +520,7 @@ class Visit {
 
     if (decision.action === "leave") {
       record.done = !!decision.done;
+      if (!record.done) await this.shoot(record, "left_unhappy");
       this.steps.push(record);
       this.log(`${record.step}. left — ${decision.why}`);
       // 떠나는 모양도 사람처럼. 데스크톱은 커서가 창 위로 빠져나간다
@@ -475,6 +540,7 @@ class Visit {
 
     const net = watchNet(page);
     let diagEl = null; // 진단에 생김새를 남길 요소
+    let probe = null; // 누르기 전 지문 — 눌렀는데 그대로였나
     if (decision.action === "read") {
       // 가만히 읽는 시간. 사람은 계속 누르지 않는다 — 이게 없으면 "N초 머묾" 같은 조건이 영영 안 걸린다.
       // 기다리는 건 다음 조작 때(waitTurn). 그 사이 카드가 뜨면 다음 조작 전에 본다
@@ -490,6 +556,10 @@ class Visit {
       }
       await sleep(250);
     } else if (decision.action === "back") {
+      // 이 화면에 와서 한 걸음도 채 안 하고 돌아간다 — 들어오자마자 뒤로. 돌아가기 전 화면을 찍는다
+      let here = 0;
+      for (let i = this.steps.length - 1; i >= 0 && this.steps[i].path === view.path; i--) here++;
+      if (here <= 1) await this.shoot(record, "bounced");
       await page.goBack({ waitUntil: "domcontentloaded" }).catch(() => {});
       if ((await settle(page, before, net)).navTimeout) this.diag.push({ kind: "nav_timeout", action: "back" });
     } else if (decision.action === "type") {
@@ -582,6 +652,7 @@ class Visit {
           // 같은 사이트를 새 탭으로 여는 링크는 이 탭에서 열게 한다. 사람은 열린 탭에서 이어 보고, 방문은 한 탭이다.
           // 새 탭을 잡아 옮기는 건(hub) 브라우저가 새 탭을 늦게, 주소 없이 알려 줘서 놓쳤다 —
           // 방문자는 "안 열린다" 를 보고 다시 누르면 "없어졌다" 가 됐다(10/14 실험실 p3, 첫 화면 카드)
+          probe = { el, before: await clickPrint(page, el) };
           await el
             .evaluate((n) => {
               const a = n.closest("a[target]");
@@ -621,8 +692,19 @@ class Visit {
     if (/^https?:/i.test(before) && !/^https?:/i.test(page.url())) {
       await page.goto(before, { waitUntil: "domcontentloaded", timeout: 30000 }).catch(() => {});
       await page.waitForLoadState("networkidle", { timeout: 8000 }).catch(() => {});
-      record.openedApp = true;
-      this.diag.push({ kind: "left_to_blank", action: decision.action, shape: null });
+      // 뒤로 가기가 빈 페이지로 간 것은 앱이 아니라 방문의 시작보다 앞으로 간 것이다(바로 들어온 첫 페이지).
+      // "다른 앱을 열려 했다" 고 알리면 방문자가 사이트 탓으로 적었다(10/22 실험실 q4)
+      if (decision.action === "back") {
+        record.backOut = true;
+        // 돌아가지 못했다 — 들어오자마자 뒤로(bounced)로 찍은 것은 무른다
+        if (record.screen && record.screen.kind === "bounced") {
+          delete record.screen;
+          this.screens = this.screens.filter((s) => s.step !== record.step);
+        }
+      } else {
+        record.openedApp = true;
+        this.diag.push({ kind: "left_to_blank", action: decision.action, shape: null });
+      }
     }
 
     // 사이트 밖으로 가는 링크였다. 끊었으니 방문자는 그대로 이 화면에 있다.
@@ -652,9 +734,29 @@ class Visit {
     if (this.fileWindow) record.fileWindow = fileWindowNote(this.fileWindow);
     await this.noteDiag(record, decision, diagEl);
 
+    // 눌렀는데 그대로. 우리 쪽 사정(빗나감·막은 요청·바깥 사이트·파일 창)으로 그대로인 것은 빼고, 같은 것은 한 번만
+    if (
+      probe &&
+      !record.skipped &&
+      !record.missed &&
+      !record.closedOverlay &&
+      !record.offsite &&
+      !record.notSent &&
+      !record.notSentQuiet &&
+      !record.external &&
+      !record.fileWindow &&
+      !record.openedApp &&
+      !record.backOut &&
+      !this.steps.some((s) => s.screen && s.screen.kind === "no_change" && s.label === record.label && s.path === record.path)
+    ) {
+      const after = await clickPrint(page, probe.el);
+      if (after.url === probe.before.url && after.doc && after.doc === probe.before.doc && after.own !== null && after.own === probe.before.own)
+        await this.shoot(record, "no_change", await boxOf(page, probe.el));
+    }
+
     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)" : ""}`,
+      `${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)" : ""}`,
     );
     this.log(`${record.step}. ${decision.action}${item ? ` "${String(item.label).slice(0, 30)}"` : ""}${record.skipped ? ` · ${record.skipped}` : ""} — ${decision.why}`);
     this.lastView = null;
@@ -677,6 +779,28 @@ class Visit {
       this.diag.push({ kind: "reclick_same", action, shape: await diag.shapeOf(el) });
   }
 
+  /**
+   * 지금 화면을 찍어 이 걸음에 붙인다(record.screen). 보이는 만큼만(뷰포트). 크면 한 번 더 작게, 그래도 크면 안 찍는다
+   * 실패해도 방문은 그대로 간다
+   */
+  async shoot(record, kind, box = null) {
+    if (!record || record.screen || this.screens.length >= MAX_SCREENS) return;
+    const image = await this.snap();
+    if (!image) return;
+    record.screen = { kind, box };
+    this.screens.push({ step: record.step, image });
+  }
+
+  /** 뷰포트 JPEG. 크면 한 번 더 작게, 그래도 크면 null */
+  async snap() {
+    let image = null;
+    for (const quality of [70, 45]) {
+      image = await this.page.screenshot({ type: "jpeg", quality, scale: "css", timeout: 5000 }).catch(() => null);
+      if (!image || image.length <= MAX_SCREEN_BYTES) break;
+    }
+    return image && image.length <= MAX_SCREEN_BYTES ? image : null;
+  }
+
   /** 카드 판단에 넘길 "이번 방문에 한 일" */
   pathText() {
     return this.history.length ? this.history.slice(-6).join(" / ") : "just arrived";