@usercase/mcp 0.2.10-next.0 → 0.2.10-next.2

package/src/browser/study.js

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * 리서치 참여(가상 사용자 리서치 진행). SDK 위젯(#eb-plugin 그림자 DOM)을 읽고 누른다.
+ *
+ * 사람 참여자와 같은 길이다 — SDK 가 agentResearch 로 그 리서치 초대를 바로 띄우고(core TriggerEngine.showAgentResearch),
+ * 우리는 수락 → 동의 → 과제 진행 → 과제마다의 질문 → 끝난 뒤 설문 탭까지 화면에 보이는 대로 간다.
+ * 수락·동의·다음 과제 넘기기는 참여하기로 한 사람이 늘 하는 것이라 도구가 누른다. 과제를 어떻게 하는지,
+ * 질문에 무엇을 답하는지, 포기할지는 방문자가 정한다.
+ *
+ * 화면 구성(earningbirds-core layouts/Widget.ts · components/frost/*):
+ *   #eb-pill[data-state] — idle·invite·consent·loading·testing·timeout·survey·next·submit·done …
+ *   #eb-frost(.eb-visible 이면 열림) > #eb-frost-body
+ *   testing: .eb-frost-testing .eb-gf-section(진행) .eb-gf-flat-title(과제) .eb-gf-flat-sub(설명) #eb-task-lefttime-text #eb-test-skip
+ *   timeout: .eb-frost-timeout #eb-timeout-continue #eb-timeout-skip
+ *   survey:  .eb-frost-survey .eb-gf-card-title .eb-gf-card-sub #eb-survey-action-btn (과제 질문·실패 이유)
+ *   next:    #eb-pill-next-btn · done: #eb-pill-done-btn
+ * Playwright 의 CSS 선택자는 열린 그림자 DOM 안까지 본다.
+ *
+ * 의존성 없음. Playwright page 를 받아 쓴다.
+ */
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** 끝난 뒤 설문(survey.usercase.io / 개발 survey.localhost:3000)의 시작 주소 */
+const SURVEY_URL = /^https?:\/\/survey\.(usercase\.io|localhost)(:\d+)?\/(?:[a-z]{2}\/)?surveys\/[^/]+\/start/i;
+const isSurveyUrl = (u) => SURVEY_URL.test(String(u || ""));
+
+/** 위젯이 지금 보여 주는 것. 위젯이 없으면 null */
+async function readStudy(page) {
+  return page
+    .evaluate(() => {
+      const host = document.getElementById("eb-plugin");
+      const sr = host && host.shadowRoot;
+      if (!sr) return null;
+      const txt = (el) => (el ? (el.innerText || el.textContent || "").replace(/\s+/g, " ").trim() : "");
+      const shown = (el) => {
+        if (!el) return false;
+        const st = getComputedStyle(el);
+        if (st.display === "none" || st.visibility === "hidden") return false;
+        const r = el.getBoundingClientRect();
+        return r.width > 0 && r.height > 0;
+      };
+      const pill = sr.querySelector("#eb-pill");
+      const frost = sr.querySelector("#eb-frost");
+      const out = {
+        state: pill ? pill.getAttribute("data-state") || "" : "",
+        open: !!(frost && frost.classList.contains("eb-visible")),
+        pillText: txt(pill),
+      };
+      const testing = sr.querySelector(".eb-frost-testing");
+      if (testing) {
+        out.task = {
+          progress: txt(testing.querySelector(".eb-gf-section")),
+          title: txt(testing.querySelector(".eb-gf-flat-title")),
+          about: txt(testing.querySelector(".eb-gf-flat-sub")),
+          timeLeft: shown(sr.querySelector("#eb-gf-lefttime-wrap")) ? txt(sr.querySelector("#eb-task-lefttime-text")) : "",
+          skip: shown(sr.querySelector("#eb-test-skip")) ? txt(sr.querySelector("#eb-test-skip")) || "Skip" : null,
+        };
+      }
+      const timeout = sr.querySelector(".eb-frost-timeout");
+      if (timeout) {
+        const c = sr.querySelector("#eb-timeout-continue");
+        const s = sr.querySelector("#eb-timeout-skip");
+        const clone = timeout.cloneNode(true);
+        clone.querySelectorAll("button").forEach((b) => b.remove());
+        out.timeout = { text: txt(clone), keepGoing: txt(c) || "Continue", skip: txt(s) || "Skip" };
+      }
+      const survey = sr.querySelector(".eb-frost-survey");
+      if (survey) {
+        const btn = sr.querySelector("#eb-survey-action-btn");
+        const q = {
+          title: txt(survey.querySelector(".eb-gf-card-title")),
+          sub: txt(survey.querySelector(".eb-gf-card-sub")),
+          label: txt(sr.querySelector("#eb-survey-pill-label")),
+          button: txt(btn) || "Next",
+          // 필수 질문 단추는 eb-survey-disabled-button 이 붙은 채 disabled 만 풀린다(core Choice.ts) — disabled 만 본다
+          canSubmit: !!(btn && !btn.disabled),
+          kind: "text",
+          options: [],
+          other: false,
+          multiline: false,
+        };
+        const choices = [...survey.querySelectorAll(".eb-sq-choice")].filter((c) => !c.querySelector("input"));
+        const likert = [...survey.querySelectorAll(".eb-sq-likert-btn")];
+        const yesno = [...survey.querySelectorAll(".eb-sq-yesno-btn")];
+        if (choices.length) {
+          q.kind = "choice";
+          q.options = choices.map(txt);
+          q.other = !!survey.querySelector("input.eb-sq-choice-other");
+        } else if (likert.length) {
+          q.kind = "scale";
+          q.options = likert.map(txt);
+          q.scaleLabels = [...survey.querySelectorAll(".eb-sq-likert-labels span")].map(txt).filter(Boolean);
+        } else if (yesno.length) {
+          q.kind = "yesno";
+          // 라벨 번역이 없으면 빈 단추다(core YesNo.ts — 기본 글이 없다). 첫째가 예다
+          q.options = yesno.map((b, i) => txt(b) || (i === 0 ? "Yes" : "No"));
+        } else {
+          q.multiline = !!survey.querySelector("textarea.eb-sq-textarea");
+        }
+        out.question = q;
+      }
+      const next = sr.querySelector("#eb-pill-next-btn");
+      if (shown(next)) out.next = txt(next) || "Next task";
+      const done = sr.querySelector("#eb-pill-done-btn");
+      if (shown(done)) out.done = { label: txt(done), enabled: !done.disabled };
+      return out;
+    })
+    .catch(() => null);
+}
+
+/** 위젯이 이 상태들 중 하나가 될 때까지. 안 되면 마지막에 본 것. 끝난 뒤 설문으로 옮겨 가면 그만 본다(null) */
+async function waitState(page, states, ms) {
+  let s = null;
+  for (let t = 0; t <= ms; t += 400) {
+    if (isSurveyUrl(page.url())) return null;
+    s = await readStudy(page);
+    if (s && states.includes(s.state)) return s;
+    await sleep(400);
+  }
+  return s;
+}
+
+/** 리서치 초대 카드(#eb-insight 의 수락 단추가 있는 카드)를 기다린다 */
+async function waitInvite(page, ms) {
+  for (let t = 0; t <= ms; t += 500) {
+    const ok = await page
+      .evaluate(() => {
+        const host = document.getElementById("eb-insight");
+        const card = host && host.shadowRoot && host.shadowRoot.querySelector(".eb-ip-card.eb-ip-visible");
+        return !!(card && card.querySelector(".eb-ip-accept"));
+      })
+      .catch(() => false);
+    if (ok) return true;
+    await sleep(500);
+  }
+  return false;
+}
+
+/**
+ * 초대를 받고 동의해 첫 과제가 시작될 때까지. 참여하기로 한 사람이라 도구가 누른다.
+ * @returns { ok: true, study } | { ok: false, why }
+ */
+async function join(page, { inviteMs = 25000 } = {}) {
+  if (!(await waitInvite(page, inviteMs)))
+    return { ok: false, why: "the research invitation never appeared (is the research deployed, and is the Usercase SDK running on this page?)" };
+  // 초대를 읽는 시간
+  await sleep(1500 + Math.random() * 2000);
+  await page.locator("#eb-insight .eb-ip-accept").click({ timeout: 5000 }).catch(() => {});
+  const consent = await waitState(page, ["consent", "loading", "testing"], 12000);
+  if (consent && consent.state === "consent") {
+    await sleep(1500 + Math.random() * 2500);
+    await page.locator("#eb-plugin #eb-consent-agree").click({ timeout: 5000 }).catch(() => {});
+  }
+  const s = await waitState(page, ["testing", "survey", "done"], 40000);
+  if (!s || s.state !== "testing") return { ok: false, why: `the research did not start (the study panel is at "${s ? s.state || "?" : "nothing"}")` };
+  return { ok: true, study: s };
+}
+
+const PRESS = {
+  skip: "#eb-plugin #eb-test-skip",
+  keepGoing: "#eb-plugin #eb-timeout-continue",
+  timeoutSkip: "#eb-plugin #eb-timeout-skip",
+  next: "#eb-plugin #eb-pill-next-btn",
+  submit: "#eb-plugin #eb-survey-action-btn",
+};
+
+/** 위젯 단추를 누른다 */
+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 });
+}
+
+/**
+ * 과제 질문(실패 이유 포함)에 답하고 보낸다.
+ * @param answer { index } 고르기 · { text } 쓰기(고르는 질문이면 "기타") · {} 비워 두고 넘기기
+ * @returns 보냈으면 null, 못 보냈으면 사람이 읽을 이유
+ */
+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 });
+  } 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 box.fill(String(answer.text).slice(0, q.multiline ? 1000 : 200), { timeout: 5000 });
+  }
+  await sleep(400);
+  const now = await readStudy(page);
+  if (!now || !now.question) return null;
+  if (!now.question.canSubmit) return "this question needs an answer before you can go on";
+  await press(page, "submit");
+  return null;
+}
+
+module.exports = { readStudy, waitState, join, press, answerQuestion, isSurveyUrl };

package/src/run/visit.js

@@ -398,8 +398,13 @@ class Visit {
    * @param shape   persona.drawShape 가 뽑은 이번 방문 모양(튕김·훑기·깊게). 인내심 표시에 쓴다
    * @param offsite 사이트 밖으로 가려던 주소가 쌓이는 배열(guard.js onOffsite 가 채운다)
    */
-  constructor(page, person, { rhythm = null, shape = null, allowAccounts = false, policy = null, offsite = [], notSent = [], external = [], log = () => {} } = {}) {
+  /**
+   * @param study   리서치에 참여 중인 방문이면 { press(key) } — 위젯 단추(과제 건너뛰기)를 누른다(hub · browser/study.js).
+   *                그 방문에서 리서치 초대 카드는 질문 카드로 다루지 않는다
+   */
+  constructor(page, person, { rhythm = null, shape = null, allowAccounts = false, policy = null, offsite = [], notSent = [], external = [], study = null, log = () => {} } = {}) {
     this.page = page;
+    this.study = study;
     this.person = person;
     /** 방문 시작 — 걸음마다 몇 초째인지(t) 적는다 */
     this.t0 = Date.now();
@@ -492,6 +497,11 @@ class Visit {
     if (this.dialogWake) this.dialogWake();
   }
 
+  /** 질문 카드로 다룰 카드인가. 리서치에 참여 중인 방문의 리서치 초대는 아니다(study.js 가 받는다) */
+  asCard(c) {
+    return c && !(this.study && c.invite) ? c : null;
+  }
+
   pathNow() {
     try {
       const u = new URL(this.page.url());
@@ -617,7 +627,7 @@ class Visit {
     // 브라우저 창이 떠 있다. 페이지는 멈춰 있어 읽으면 걸린다 — 창만 보여 준다
     if (this.dialog) return this.dialogLook();
     if (!this.card && !this.pending) {
-      const shown = await waitCard(this.page, 500);
+      const shown = this.asCard(await waitCard(this.page, 500));
       if (shown) this.pending = shown;
     }
     // 카드 판단에는 페이지 전체를 준다 — 이 방문에서 본 것을 다 기억하는 사람이다
@@ -684,18 +694,31 @@ class Visit {
     if (this.pending) throw new Error("A card is showing — answer or close it first");
     await this.waitTurn();
     if (!this.card) {
-      const c = await readCard(this.page);
+      const c = this.asCard(await readCard(this.page));
       if (c && c.visible) {
         this.pending = c;
         return { interrupted: true };
       }
     }
+    // 보는 사이 리서치가 질문을 띄웠다(과제 타이머가 끝났다 등). 페이지를 덮으니 하려던 걸 하지 않는다 — 질문부터
+    if (this.study && this.study.blocking && (await this.study.blocking())) return { interrupted: true, study: true };
     if (this.steps.length >= HARD_STEP_CAP) decision = { ...decision, action: "leave", why: `(${HARD_STEP_CAP}-step limit) ${decision.why}` };
     const page = this.page;
     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;
+    // 리서치 위젯의 단추(과제 건너뛰기). 페이지 조작이 아니라 위젯을 누른다 — 화면 목록에 hub 가 붙여 둔 것이다
+    if (decision.action === "click" && item && item.study && this.study) {
+      record.study = item.study;
+      await this.study.press(item.study).catch(() => (record.skipped = "it did not respond"));
+      await sleep(1500);
+      this.steps.push(record);
+      this.history.push(`click "${item.label}" — ${decision.why}${record.skipped ? ` (${record.skipped})` : ""}`);
+      this.log(`${record.step}. study ${item.study} — ${decision.why}`);
+      this.lastView = null;
+      return 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)));
@@ -724,7 +747,7 @@ class Visit {
       this.ended = true;
       // 떠나려는 순간에 뜨는 카드가 있다. 모바일은 SDK 가 멈춤으로 대신 보므로 더 기다린다
       if (!this.card) {
-        const parting = await waitCard(page, this.person.device === "mobile" ? 16000 : 6000);
+        const parting = this.asCard(await waitCard(page, this.person.device === "mobile" ? 16000 : 6000));
         if (parting) this.pending = parting;
       }
       return record;
@@ -929,6 +952,11 @@ class Visit {
       record.external = ext;
     }
     if (this.fileWindow) record.fileWindow = fileWindowNote(this.fileWindow);
+    // 누르는 순간 리서치 질문이 페이지를 덮었다 — 도구가 못 한 게 아니라 리서치가 끼어든 것이다(10/30 실험실: 과제 타이머가 클릭과 겹쳤다)
+    if (record.skipped && /survey card is on top/.test(record.skipped) && this.study && this.study.blocking && (await this.study.blocking())) {
+      record.skipped = "the study's question came up just as you clicked, so the click did not reach the page";
+      record.studyCut = true;
+    }
     await this.noteDiag(record, decision, diagEl);
 
     // 화면이 깨졌다 — 오류로 온 문서, 오류 문구뿐인 화면. 바깥 사이트·앱·빈 페이지로 간 것은 뺀다