@solhun/feedback-kit-core 0.1.0

package/src/adapters/lasso.ts

@@ -0,0 +1,316 @@
+// 라쏘런(doc-platform) 어댑터 — 기본 전송 대상.
+//
+// 이 파일이 지는 책임과 지지 않는 책임:
+// - 진다: 제보를 라쏘런이 받는 모양으로 **바꿔서** 보내고, 결과를 SubmitResult 로 **돌려준다.**
+// - 안 진다: 재시도·백오프·큐 적재. 그건 코어(queue.ts)가 한다. 여기서 재시도하면
+//   같은 제보가 두 층에서 각자 재시도돼 서버가 중복을 받는다.
+//
+// 절대 규칙 두 가지:
+// 1. **던지지 않는다.** 네트워크 오류든 파싱 실패든 SubmitResult 로 바꿔 돌려준다.
+//    (큐가 예외를 흡수하긴 하지만, 그때는 전부 "일시 실패"로 뭉뚱그려져 4xx 가 영원히 재시도된다.)
+// 2. **본문·헤더를 로그에 남기지 않는다.** 경고에는 상태 코드와 사유만 적는다.
+//    `Authorization` 헤더와 응답 본문은 어떤 경로로도 콘솔에 닿지 않는다.
+
+import { byteLengthOf, canUseKeepalive } from "../keepalive.js";
+import type { FeedbackAdapter, FeedbackReport, SubmitResult } from "../types.js";
+// 라쏘런은 headline 필드가 없다(comment 하나로 받는다) → buildTitle 을 쓰지 않는다.
+import { renderReportBody } from "./body.js";
+
+/**
+ * 엔드포인트 기본값. 코어가 아니라 **어댑터**가 갖는다(config.ts 의 ENDPOINT_FROM_ADAPTER).
+ *
+ * 상대 경로인 이유: 웹은 같은 오리진의 수집 라우트로 보내는 게 기본이고, 그래야
+ * Origin 허용 목록이라는 실제 방어선이 그대로 작동한다. 앱(RN)에는 오리진이 없으므로
+ * `endpoint` 를 절대 URL 로 지정해야 한다 — 지정 없이 앱에서 쓰면 아래에서 설정 오류로 끊는다.
+ */
+export const LASSO_DEFAULT_ENDPOINT = "/api/feedback";
+
+/** 최소한의 응답 형태. 코어는 DOM 타입(lib)에 의존하지 않으므로 구조적으로 정의한다. */
+export interface LassoResponseLike {
+  status: number;
+  headers?: { get(name: string): string | null } | undefined;
+  text(): Promise<string>;
+}
+
+/** 최소한의 요청 형태. 표준 fetch 의 부분집합이라 그대로 꽂힌다. */
+export interface LassoRequestInit {
+  method: string;
+  headers: Record<string, string>;
+  body: string;
+  keepalive?: boolean;
+}
+
+export type LassoFetch = (url: string, init: LassoRequestInit) => Promise<LassoResponseLike>;
+
+export interface LassoAdapterOpts {
+  /** 수집 토큰. 없으면 `Authorization` 헤더 자체를 붙이지 않는다(미귀속 전송). */
+  token?: string | null;
+  /** 수집 엔드포인트. 없으면 LASSO_DEFAULT_ENDPOINT. */
+  endpoint?: string | null;
+  /** 전송 함수 주입(테스트용). 없으면 globalThis.fetch. */
+  fetch?: LassoFetch | null;
+  /** 경고 출력 주입. 위젯은 캡처를 우회하는 원본 console 을 넘긴다. */
+  warn?: ((message: string, ...rest: unknown[]) => void) | null;
+}
+
+/**
+ * 라쏘런으로 보내는 봉투.
+ *
+ * 필드명이 코어의 FeedbackReport 와 일부러 다르다. 코어는 이 이름들을 **모른다** —
+ * 대상마다 받는 모양이 다르다는 게 어댑터를 두는 이유 자체다(DP-255 TC5).
+ */
+/**
+ * 라쏘런 `dp-agentation-ingest` 가 실제로 요구하는 봉투.
+ *
+ * 이 모양은 **상상하지 않고 실호출로 확정했다.** 이전 버전은 필드명을 지어내서
+ * (submissionKey/bodyMarkdown/severity …) 실 엔드포인트에 100% 400 으로 거절당했고,
+ * 400 은 재시도 불가라 모든 제보가 조용히 데드레터로 사라졌다.
+ * 계약을 바꿀 때는 반드시 실호출로 다시 확인한다(adapters.live.test.ts).
+ */
+export interface LassoEnvelope {
+  /** UUID. **Idempotency-Key 헤더와 반드시 같은 값**이어야 서버가 받는다. */
+  clientSubmissionId: string;
+  /**
+   * 수집 소스의 종류와 같아야 한다(서버가 대조한다). 코어의 platform 을 옮긴 값이다:
+   * web → "web", native → "app". 앱은 report.create 만 보낼 수 있다(요소 지목은 DOM 이 필요).
+   */
+  clientType: "web" | "app";
+  /** 지목 주석은 annotation.add, 리포트 모달 제출은 report.create. */
+  event: "annotation.add" | "report.create";
+  /** epoch ms 정수. ISO 문자열을 보내면 거절된다. */
+  timestamp: number;
+  /** 절대 HTTP(S) URL. 소스의 host_patterns 에 등록된 origin 이어야 한다. */
+  url: string;
+  priority: "unset" | "normal" | "high" | "urgent";
+  annotation?: {
+    id: string;
+    comment: string;
+    x: number | null;
+    y: number | null;
+    element: string | null;
+    elementPath: string | null;
+    selectedText: string | null;
+    boundingBox: { x: number; y: number; width: number; height: number } | null;
+    timestamp: number;
+  };
+  report?: {
+    comment: string;
+    pin: { x: number; y: number } | null;
+    sourceFile: string | null;
+    screenshotBase64: string | null;
+    screenshotContentType: "image/jpeg" | "image/png" | null;
+    network: unknown[];
+    logs: unknown[];
+  };
+}
+
+
+const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+
+function resolveFetch(injected: LassoFetch | null | undefined): LassoFetch | null {
+  if (injected) return injected;
+  const g = globalThis as { fetch?: unknown };
+  return typeof g.fetch === "function" ? (g.fetch as LassoFetch) : null;
+}
+
+/**
+ * 상대 경로를 절대 URL 로 만든다. 오리진을 못 찾으면 null(= 설정 오류).
+ *
+ * 왜 굳이 절대 URL 로 바꾸나: 진단 수집기가 "위젯 자신의 요청"을 제외할 때 URL 로 매칭하는데,
+ * 상대/절대가 섞이면 그 매칭이 헐거워진다. 어느 층에서 보든 같은 문자열이 되게 맞춘다.
+ */
+function absoluteEndpoint(endpoint: string): string | null {
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(endpoint)) return endpoint;
+  const origin = (globalThis as { location?: { origin?: string } }).location?.origin;
+  if (typeof origin !== "string" || origin.length === 0) return null;
+  return endpoint.startsWith("/") ? `${origin}${endpoint}` : `${origin}/${endpoint}`;
+}
+
+/** `Retry-After: 30`(초)만 해석한다. HTTP-date 형식은 코어의 기본 백오프에 맡긴다. */
+function parseRetryAfterMs(res: LassoResponseLike): number | null {
+  const raw = res.headers?.get("Retry-After") ?? null;
+  if (raw === null) return null;
+  const seconds = Number(raw.trim());
+  return Number.isFinite(seconds) && seconds >= 0 ? Math.round(seconds * 1000) : null;
+}
+
+function fail(retryable: boolean, extra?: Partial<SubmitResult>): SubmitResult {
+  return { ok: false, id: null, retryable, retryAfterMs: null, ...extra };
+}
+
+/** 응답 본문에서 서버가 준 id 를 꺼낸다. 없으면 null(성공 판정과는 무관하다). */
+function idFrom(parsed: Record<string, unknown>): string | null {
+  // 라쏘런은 `annotationId` 로 준다(실호출로 확인). `id`/`data.id` 는 다른 대상 대비 폴백.
+  const annotationId = parsed.annotationId;
+  if (typeof annotationId === "string" && annotationId.length > 0) return annotationId;
+  const direct = parsed.id;
+  if (typeof direct === "string" && direct.length > 0) return direct;
+  const data = parsed.data;
+  if (data && typeof data === "object") {
+    const nested = (data as Record<string, unknown>).id;
+    if (typeof nested === "string" && nested.length > 0) return nested;
+  }
+  return null;
+}
+
+/** 제보를 라쏘런 봉투로 바꾼다. 순수 함수라 테스트가 전송 없이 모양만 볼 수 있다. */
+export function buildLassoEnvelope(report: FeedbackReport): LassoEnvelope {
+  const c = report.context;
+  const clientType: "web" | "app" = c.platform === "native" ? "app" : "web";
+  // 서버가 epoch ms 정수만 받는다. createdAt(ISO)이 깨져 있어도 전송을 막지 않는다.
+  const parsed = Date.parse(report.createdAt);
+  const timestamp = Number.isFinite(parsed) ? parsed : 0;
+  const el = report.element;
+
+  // 요소를 지목한 제보는 annotation.add 로, 모달 제출은 report.create 로 간다.
+  // 대상이 둘을 같은 라우트에서 event 로 가른다.
+  if (report.kind === "annotation") {
+    return {
+      clientSubmissionId: report.clientSubmissionId,
+      clientType,
+      event: "annotation.add",
+      timestamp,
+      url: c.url ?? "",
+      priority: report.priority,
+      annotation: {
+        id: report.clientSubmissionId,
+        comment: renderReportBody(report),
+        x: report.pin?.x ?? null,
+        y: report.pin?.y ?? null,
+        element: el ? el.tag : null,
+        elementPath: el?.attributes["data-feedback-source"] ?? null,
+        selectedText: el?.text ?? null,
+        boundingBox: el?.boundingBox ?? null,
+        timestamp,
+      },
+    };
+  }
+
+  return {
+    clientSubmissionId: report.clientSubmissionId,
+    clientType,
+    event: "report.create",
+    timestamp,
+    // 앱에는 URL 이 없다 — 화면 이름을 app:// 경로로 싣는다(서버가 그대로 저장한다).
+    url: c.url ?? (clientType === "app" ? `app://${c.screen ?? "unknown"}` : ""),
+    priority: report.priority,
+    report: {
+      comment: renderReportBody(report),
+      pin: report.pin ? { x: report.pin.x, y: report.pin.y } : null,
+      sourceFile: el?.attributes["data-feedback-source"] ?? null,
+      screenshotBase64: report.screenshot?.base64 ?? null,
+      screenshotContentType: report.screenshot?.contentType ?? null,
+      // 서버가 없으면 빈 배열로 취급하지만, 미연동과 "없었음"을 구분해 보낸다.
+      network: report.context.diagnostics?.network ?? [],
+      logs: report.context.diagnostics?.logs ?? [],
+    },
+  };
+}
+
+/**
+ * 라쏘런 어댑터를 만든다.
+ *
+ * 실패 분류(코어가 이 값만 보고 재시도 여부를 정한다):
+ * - 429 → 재시도 가능 + rateLimited. 코어가 최소 10분을 띄운다.
+ * - 408/425/5xx/네트워크 오류 → 재시도 가능(일시적).
+ * - 그 밖의 4xx → **재시도 불가.** 400/401/413 은 다시 보내도 같은 답이라 큐만 막는다.
+ * - 2xx 인데 본문의 `ok` 가 true 가 아님 → 재시도 불가. 스키마 거절은 저절로 낫지 않는다.
+ * - 2xx 인데 본문을 못 읽음 → **재시도 가능.** 프록시·CDN 이 HTML 을 끼워 넣는 일이 실제로 있고,
+ *   멱등 키가 있어 다시 보내도 중복이 생기지 않는다.
+ */
+export function createLassoAdapter(opts: LassoAdapterOpts = {}): FeedbackAdapter {
+  const token = opts.token ?? null;
+  const endpoint = opts.endpoint && opts.endpoint.trim().length > 0
+    ? opts.endpoint.trim()
+    : LASSO_DEFAULT_ENDPOINT;
+  const warn = opts.warn ?? null;
+
+  const emit = (message: string): void => {
+    if (!warn) return;
+    try {
+      warn(message);
+    } catch {
+      // 로깅 실패가 전송 실패로 번지면 안 된다.
+    }
+  };
+
+  return {
+    async submit(report: FeedbackReport): Promise<SubmitResult> {
+      const url = absoluteEndpoint(endpoint);
+      if (url === null) {
+        // 앱에서 상대 경로를 그대로 둔 설정 오류. 재시도해도 절대 낫지 않으므로
+        // 재시도 불가로 끊는다(큐가 데드레터로 보내고 뒤 제보를 막지 않는다).
+        emit(
+          `feedback-kit: endpoint "${endpoint}" 를 절대 URL 로 만들 수 없다(오리진 없음). ` +
+            "앱에서는 endpoint 를 절대 URL 로 지정해야 한다."
+        );
+        return fail(false);
+      }
+
+      const sender = resolveFetch(opts.fetch);
+      if (sender === null) {
+        // fetch 가 없는 런타임. 폴리필이 늦게 들어올 수 있으니 일시 실패로 둔다.
+        emit("feedback-kit: fetch 를 찾지 못했다(전송을 미룬다).");
+        return fail(true);
+      }
+
+      const body = JSON.stringify(buildLassoEnvelope(report));
+      const headers: Record<string, string> = {
+        "Content-Type": "application/json",
+        // 재시도가 중복 제보가 되지 않게. 코어가 같은 항목을 다시 보내도 키는 그대로다.
+        "Idempotency-Key": report.clientSubmissionId,
+      };
+      if (token !== null) headers.Authorization = `Bearer ${token}`;
+
+      let res: LassoResponseLike;
+      try {
+        res = await sender(url, {
+          method: "POST",
+          headers,
+          body,
+          // 페이지를 즉시 이탈해도 전송이 끝나게. 본문이 한도를 넘으면 브라우저가
+          // 요청 자체를 거절하므로 크기를 보고 켠다.
+          keepalive: canUseKeepalive(byteLengthOf(body)),
+        });
+      } catch {
+        // 오프라인·DNS·CORS 등. 예외 객체에 요청 본문이 들어있을 수 있어 로그에 싣지 않는다.
+        emit("feedback-kit: 전송에 실패했다(네트워크). 큐에 남겨 다시 시도한다.");
+        return fail(true);
+      }
+
+      const status = res.status;
+
+      if (status < 200 || status >= 300) {
+        if (status === 429) {
+          emit("feedback-kit: 수집 한도에 걸렸다(429). 잠시 뒤 다시 시도한다.");
+          return fail(true, { retryAfterMs: parseRetryAfterMs(res), rateLimited: true });
+        }
+        const retryable = RETRYABLE_STATUS.has(status);
+        emit(
+          `feedback-kit: 수집 응답 ${status}${retryable ? " (다시 시도한다)" : " (재시도하지 않는다)"}`
+        );
+        return fail(retryable, { retryAfterMs: retryable ? parseRetryAfterMs(res) : null });
+      }
+
+      let parsed: Record<string, unknown>;
+      try {
+        const text = await res.text();
+        const value: unknown = JSON.parse(text);
+        if (value === null || typeof value !== "object") throw new Error("객체가 아님");
+        parsed = value as Record<string, unknown>;
+      } catch {
+        emit(`feedback-kit: 수집 응답 ${status} 의 본문을 읽지 못했다. 다시 시도한다.`);
+        return fail(true);
+      }
+
+      // 2xx 만으로 성공을 단정하지 않는다. 서버가 200 + ok:false 로 거절할 수 있고,
+      // 그걸 성공으로 읽으면 제보가 큐에서 지워진 채 어디에도 남지 않는다.
+      if (parsed.ok !== true) {
+        emit(`feedback-kit: 수집 서버가 제보를 거절했다(${status}). 재시도하지 않는다.`);
+        return fail(false);
+      }
+
+      return { ok: true, id: idFrom(parsed), retryable: false, retryAfterMs: null };
+    },
+  };
+}

package/src/adapters/linear.ts

@@ -0,0 +1,39 @@
+// Linear 어댑터 — **인터페이스만 열어둔다. 전송은 구현하지 않는다.**
+//
+// 왜 껍데기를 미리 두는가:
+// 어댑터 교체가 실제로 가능한지는 두 번째 대상을 만들어봐야 드러난다. 여기서 확인하는 건
+// "라쏘런에만 있는 모양을 코어가 몰래 전제하고 있지 않은가"이고, 그건 전송 없이
+// **payload 를 조립하는 것만으로** 확인된다(DP-255 TC4·TC5).
+//
+// 전송을 안 쓰는 이유는 게을러서가 아니다. Linear 로 실제로 보내려면 팀 ID·상태 ID·
+// API 키 같은 워크스페이스별 값이 필요한데, 그건 이 wave 에 명세가 없다. 없는 명세를
+// 상상해서 만들어두면 나중에 전부 지워야 한다. 그래서 **모양만** 맞춰둔다.
+
+import type { FeedbackReport } from "../types.js";
+import { buildTitle, renderReportBody } from "./body.js";
+
+/**
+ * Linear 이슈 생성 입력의 최소 형태.
+ *
+ * 필드명이 라쏘런 봉투와 다르다는 게 핵심이다 — 같은 제보라도 대상마다 이름이 다르고,
+ * 코어는 그 어느 쪽도 모른다.
+ */
+export interface LinearIssueInput {
+  /** 이슈 제목. 목록에서 한 줄로 보인다. */
+  title: string;
+  /** 이슈 본문(마크다운). 대상이 못 받는 값은 전부 여기 접힌 블록으로 들어간다. */
+  description: string;
+}
+
+/**
+ * 제보를 Linear 이슈 입력으로 바꾼다.
+ *
+ * 본문은 공용 렌더러가 만든 것을 **그대로** 쓴다. 여기서 다시 조립하면
+ * "Linear 로 간 제보에는 소스 경로가 없다" 같은 차이가 조용히 생긴다.
+ */
+export function buildLinearIssue(report: FeedbackReport): LinearIssueInput {
+  return {
+    title: buildTitle(report),
+    description: renderReportBody(report),
+  };
+}

package/src/adapters/notion.ts

@@ -0,0 +1,30 @@
+// Notion 어댑터 — **인터페이스만 열어둔다. 전송은 구현하지 않는다.**
+//
+// linear.ts 와 같은 이유로 payload 조립까지만 둔다. Notion 은 본문을 블록 배열로 받는
+// 대상이라 "마크다운 문자열 하나"와 모양이 가장 많이 다른데, 그래서 오히려 좋은 대조군이다
+// — 이 대상까지 같은 렌더러로 채워진다면 본문 구성이 특정 대상에 묶여 있지 않다는 뜻이다.
+
+import type { FeedbackReport } from "../types.js";
+import { buildTitle, renderReportBody } from "./body.js";
+
+/** Notion 페이지 생성 입력의 최소 형태. */
+export interface NotionPageInput {
+  /** 페이지 제목 속성. */
+  title: string;
+  /**
+   * 페이지 본문(마크다운 원문).
+   *
+   * 블록 배열로 쪼개지 않는 이유: 쪼개는 규칙(어디서 문단을 나눌지, 접힌 블록을
+   * toggle 로 옮길지)은 실제 Notion API 계약이 정해진 뒤에야 의미가 있다.
+   * 지금 추측으로 쪼개두면 본문 내용이 대상마다 갈라지고, 그게 이 wave 가 막으려는 것이다.
+   */
+  content: string;
+}
+
+/** 제보를 Notion 페이지 입력으로 바꾼다. 본문은 공용 렌더러 결과 그대로다. */
+export function buildNotionPage(report: FeedbackReport): NotionPageInput {
+  return {
+    title: buildTitle(report),
+    content: renderReportBody(report),
+  };
+}

package/src/config.test.ts

@@ -0,0 +1,284 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  DEFAULT_ADAPTER,
+  DEFAULT_POSITION,
+  detectDevBuild,
+  diagnosticsProviderFor,
+  isInternalUser,
+  resolveConfig,
+  shouldShowWidget,
+  type ConfigWarningCode,
+  type DiagnosticsSource,
+} from "./config.js";
+import { buildContext } from "./context.js";
+import type { DiagnosticsPayload, FeedbackStorage } from "./types.js";
+
+function codes(warnings: { code: ConfigWarningCode }[]): ConfigWarningCode[] {
+  return warnings.map((w) => w.code);
+}
+
+function memoryStorage(): FeedbackStorage {
+  const map = new Map<string, string>();
+  return {
+    async get(key) {
+      return map.get(key) ?? null;
+    },
+    async set(key, value) {
+      map.set(key, value);
+    },
+    async remove(key) {
+      map.delete(key);
+    },
+  };
+}
+
+describe("resolveConfig", () => {
+  it("아무것도 안 주면 기본값으로 채운다", () => {
+    const r = resolveConfig();
+    expect(r.adapter).toBe(DEFAULT_ADAPTER);
+    expect(r.visibility).toBe("all");
+    expect(r.captureScreenshot).toBe(true);
+    expect(r.captureDiagnostics).toBe(true);
+    expect(r.position).toEqual(DEFAULT_POSITION);
+    expect(r.endpoint).toBeNull();
+  });
+
+  it("토큰이 없으면 경고만 남기고 던지지 않는다", () => {
+    const r = resolveConfig({ token: "  " });
+    expect(r.token).toBeNull();
+    expect(codes(r.warnings)).toContain("missing-token");
+  });
+
+  // 빌드 타임 인라인이 실패하면 토큰 자리에 이런 문자열이 그대로 박힌다.
+  // 서버가 401 을 주기 전에 여기서 먼저 알려주는 게 목적.
+  it.each([
+    "undefined",
+    "null",
+    "process.env.FEEDBACK_TOKEN",
+    "${VITE_FEEDBACK_TOKEN}",
+    "%NEXT_PUBLIC_FEEDBACK_TOKEN%",
+  ])("치환되지 않은 토큰 %s 을 잡아낸다", (token) => {
+    const r = resolveConfig({ token });
+    expect(codes(r.warnings)).toContain("unsubstituted-token");
+  });
+
+  it("정상 토큰에는 경고가 없다", () => {
+    const r = resolveConfig({ token: "fk_live_abc123" });
+    expect(r.token).toBe("fk_live_abc123");
+    expect(r.warnings).toEqual([]);
+  });
+
+  it("모르는 값이 와도 던지지 않고 기본값으로 되돌린다", () => {
+    const r = resolveConfig({
+      adapter: "지라" as never,
+      visibility: "직원만" as never,
+      position: "가운데" as never,
+    });
+    expect(r.adapter).toBe(DEFAULT_ADAPTER);
+    expect(r.visibility).toBe("all");
+    expect(r.position).toEqual(DEFAULT_POSITION);
+    expect(codes(r.warnings)).toEqual(
+      expect.arrayContaining(["unknown-adapter", "unknown-visibility", "unknown-position"])
+    );
+  });
+
+  it("코너만 줘도 되고 오프셋만 덮어써도 된다", () => {
+    expect(resolveConfig({ position: "top-left" }).position).toEqual({
+      corner: "top-left",
+      offsetX: DEFAULT_POSITION.offsetX,
+      offsetY: DEFAULT_POSITION.offsetY,
+    });
+    expect(resolveConfig({ position: { offsetY: 80 } }).position).toEqual({
+      corner: DEFAULT_POSITION.corner,
+      offsetX: DEFAULT_POSITION.offsetX,
+      offsetY: 80,
+    });
+  });
+
+  it("onWarn 이 던져도 설정 해석은 계속된다", () => {
+    const onWarn = vi.fn(() => {
+      throw new Error("로깅 실패");
+    });
+    const r = resolveConfig({ onWarn });
+    expect(onWarn).toHaveBeenCalled();
+    expect(r.adapter).toBe(DEFAULT_ADAPTER);
+  });
+
+  it("어댑터 객체를 직접 주면 그대로 쓴다", () => {
+    const adapter = {
+      submit: async () => ({ ok: true, id: "1", retryable: false, retryAfterMs: null }),
+    };
+    expect(resolveConfig({ adapter }).adapter).toBe(adapter);
+  });
+});
+
+describe("detectDevBuild", () => {
+  it("__DEV__ 가 있으면 그걸 따른다", () => {
+    const g = globalThis as Record<string, unknown>;
+    g.__DEV__ = true;
+    try {
+      expect(detectDevBuild()).toBe(true);
+      g.__DEV__ = false;
+      expect(detectDevBuild()).toBe(false);
+    } finally {
+      delete g.__DEV__;
+    }
+  });
+});
+
+describe("shouldShowWidget", () => {
+  it("visibility=all 이면 로그인하지 않은 사용자에게도 보인다", () => {
+    const r = resolveConfig({ visibility: "all" });
+    expect(shouldShowWidget(r, { user: null })).toBe(true);
+    expect(shouldShowWidget(r, { user: { id: "u1", isGuest: true } })).toBe(true);
+  });
+
+  it("visibility=internal 이면 일반 사용자에게는 숨긴다", () => {
+    const r = resolveConfig({ visibility: "internal" });
+    expect(shouldShowWidget(r, { user: { id: "u1", role: "user" } })).toBe(false);
+    expect(shouldShowWidget(r, { user: null })).toBe(false);
+    expect(shouldShowWidget(r, { user: { id: "u2", role: "admin" } })).toBe(true);
+  });
+
+  it("게스트는 role 이 붙어 있어도 내부 사용자가 아니다", () => {
+    const r = resolveConfig({ visibility: "internal" });
+    expect(shouldShowWidget(r, { user: { id: "g", role: "admin", isGuest: true } })).toBe(
+      false
+    );
+  });
+
+  it("visibility=dev-only 는 개발 빌드에서만 보인다", () => {
+    const r = resolveConfig({ visibility: "dev-only", isDev: false });
+    expect(shouldShowWidget(r)).toBe(false);
+    expect(shouldShowWidget(r, { isDev: true })).toBe(true);
+  });
+
+  // TC4: visibility 에 false 를 반환하는 함수를 주면 버튼이 렌더되지 않는다.
+  it("visibility 함수의 판정을 그대로 따른다", () => {
+    const never = resolveConfig({ visibility: () => false });
+    expect(shouldShowWidget(never, { user: { id: "u1", role: "admin" } })).toBe(false);
+
+    const seen: unknown[] = [];
+    const always = resolveConfig({
+      visibility: (env) => {
+        seen.push(env.user);
+        return true;
+      },
+    });
+    expect(shouldShowWidget(always, { user: { id: "u1" }, platform: "web" })).toBe(true);
+    expect(seen).toEqual([{ id: "u1" }]);
+  });
+
+  it("판정 함수가 던지면 숨기고 경고를 남긴다", () => {
+    const r = resolveConfig({
+      visibility: () => {
+        throw new Error("세션 조회 실패");
+      },
+    });
+    expect(shouldShowWidget(r)).toBe(false);
+    expect(codes(r.warnings)).toContain("visibility-threw");
+  });
+
+  it("internal 판정 함수가 던져도 숨긴다", () => {
+    const r = resolveConfig({
+      visibility: "internal",
+      isInternal: () => {
+        throw new Error("권한 조회 실패");
+      },
+    });
+    expect(shouldShowWidget(r, { user: { id: "u1" } })).toBe(false);
+    expect(codes(r.warnings)).toContain("visibility-threw");
+  });
+
+  it("internalRoles 로 내부 판정 기준을 바꿀 수 있다", () => {
+    const r = resolveConfig({ visibility: "internal", internalRoles: ["QA"] });
+    expect(isInternalUser(r, { user: { id: "u1", role: "qa" }, isDev: false, platform: "web" })).toBe(
+      true
+    );
+    expect(
+      isInternalUser(r, { user: { id: "u2", role: "admin" }, isDev: false, platform: "web" })
+    ).toBe(false);
+  });
+});
+
+describe("diagnosticsProviderFor", () => {
+  function fakeCollector(): DiagnosticsSource & { installed: number } {
+    const payload: DiagnosticsPayload = {
+      network: [
+        {
+          method: "GET",
+          url: "https://api.example.com/x",
+          status: 500,
+          durationMs: 12,
+          at: "2026-01-01T00:00:00.000Z",
+        },
+      ],
+      logs: [{ level: "error", message: "boom", at: "2026-01-01T00:00:00.000Z" }],
+    };
+    return {
+      installed: 0,
+      install() {
+        this.installed += 1;
+      },
+      snapshot() {
+        return payload;
+      },
+    };
+  }
+
+  it("켜져 있으면 수집기를 설치하고 공급자를 돌려준다", () => {
+    const collector = fakeCollector();
+    const provider = diagnosticsProviderFor({ captureDiagnostics: true }, collector);
+    expect(collector.installed).toBe(1);
+    expect(provider?.().network).toHaveLength(1);
+  });
+
+  // TC5: captureDiagnostics=false 면 수집 자체를 하지 않는다.
+  // 빈 배열을 돌려주면 "수집했는데 없었다"와 구분되지 않으므로 공급자를 아예 만들지 않는다.
+  it("꺼져 있으면 수집기를 설치하지 않고 공급자도 없다", () => {
+    const collector = fakeCollector();
+    expect(diagnosticsProviderFor({ captureDiagnostics: false }, collector)).toBeUndefined();
+    expect(collector.installed).toBe(0);
+  });
+
+  it("꺼진 설정으로 만든 컨텍스트는 diagnostics 가 null 이고 나머지는 정상이다", async () => {
+    const resolved = resolveConfig({ captureDiagnostics: false, token: "fk_t" });
+    const collector = fakeCollector();
+    const ctx = await buildContext({
+      app: "demo",
+      sessionId: "s-1",
+      storage: memoryStorage(),
+      platform: "web",
+      getUser: () => ({ id: "u1", email: "a@b.c" }),
+      getCurrentScreen: () => "홈",
+      getUrl: () => "https://app.example.com/home",
+      getWebContext: () => ({ userAgent: "vitest" }),
+      getDiagnostics: diagnosticsProviderFor(resolved, collector),
+    });
+
+    expect(ctx.diagnostics).toBeNull();
+    expect(collector.installed).toBe(0);
+    // 진단만 빠지고 나머지 컨텍스트는 그대로 채워진다.
+    expect(ctx.user?.id).toBe("u1");
+    expect(ctx.screen).toBe("홈");
+    expect(ctx.url).toBe("https://app.example.com/home");
+    expect(ctx.web?.userAgent).toBe("vitest");
+    expect(ctx.clientTimestamp).toEqual(expect.any(String));
+  });
+
+  it("켜진 설정으로 만든 컨텍스트에는 진단이 채워진다", async () => {
+    const resolved = resolveConfig({ captureDiagnostics: true });
+    const collector = fakeCollector();
+    const ctx = await buildContext({
+      app: "demo",
+      sessionId: "s-1",
+      storage: memoryStorage(),
+      platform: "web",
+      getUrl: () => "https://app.example.com/home",
+      getDiagnostics: diagnosticsProviderFor(resolved, collector),
+    });
+    expect(ctx.diagnostics?.network).toHaveLength(1);
+    expect(ctx.diagnostics?.logs).toHaveLength(1);
+  });
+});