@solhun/feedback-kit-core 0.1.0

package/src/ring-buffer.ts

@@ -0,0 +1,42 @@
+// 고정 용량 링버퍼.
+//
+// 진단 수집은 "최근 것"만 있으면 된다. 상한이 없으면 오래 켜둔 화면에서 메모리가
+// 계속 늘고, 상한을 넘겼을 때 새 항목을 버리면 정작 사고 직전의 기록이 안 남는다.
+// 그래서 상한 초과 시 **가장 오래된 것부터** 밀어낸다.
+
+export class RingBuffer<T> {
+  /** 보관 상한. 0 이하/비정상 값이면 0(아무것도 담지 않음)으로 떨어진다. */
+  readonly capacity: number;
+
+  private items: T[] = [];
+
+  constructor(capacity: number) {
+    this.capacity =
+      Number.isFinite(capacity) && capacity > 0 ? Math.floor(capacity) : 0;
+  }
+
+  push(item: T): void {
+    if (this.capacity === 0) {
+      return;
+    }
+    this.items.push(item);
+    const overflow = this.items.length - this.capacity;
+    if (overflow > 0) {
+      // 한 번에 여러 개가 넘칠 일은 없지만(push 마다 검사), 방어적으로 잘라낸다.
+      this.items.splice(0, overflow);
+    }
+  }
+
+  /** 현재 내용의 복사본. 호출자가 들고 있어도 이후 push 에 영향받지 않는다. */
+  toArray(): T[] {
+    return this.items.slice();
+  }
+
+  get size(): number {
+    return this.items.length;
+  }
+
+  clear(): void {
+    this.items = [];
+  }
+}

package/src/source-attr.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+
+import { parseSourceAttr, SOURCE_ATTR, sourceFromElement } from "./source-attr.js";
+
+describe("parseSourceAttr", () => {
+  it("파일:줄:칼럼 을 해석한다", () => {
+    expect(parseSourceAttr("src/pages/Home.tsx:42:7")).toEqual({
+      file: "src/pages/Home.tsx",
+      line: 42,
+      column: 7,
+    });
+  });
+
+  it("칼럼이 없어도 된다", () => {
+    expect(parseSourceAttr("src/App.tsx:3")).toEqual({
+      file: "src/App.tsx",
+      line: 3,
+      column: null,
+    });
+  });
+
+  // 윈도우 경로에는 콜론이 들어 있다. 앞에서부터 자르면 드라이브 문자에서 깨진다.
+  it("경로에 콜론이 있어도 뒤에서부터 잘라 안전하다", () => {
+    expect(parseSourceAttr("C:/repo/src/App.tsx:10:2")).toEqual({
+      file: "C:/repo/src/App.tsx",
+      line: 10,
+      column: 2,
+    });
+  });
+
+  it("모양이 아니면 null 이다", () => {
+    expect(parseSourceAttr(undefined)).toBeNull();
+    expect(parseSourceAttr("")).toBeNull();
+    expect(parseSourceAttr("src/App.tsx")).toBeNull();
+    expect(parseSourceAttr("src/App.tsx:0")).toBeNull();
+    expect(parseSourceAttr(":12:3")).toBeNull();
+    expect(parseSourceAttr(42)).toBeNull();
+  });
+});
+
+describe("sourceFromElement", () => {
+  const base = { screenId: "home", sourceFile: "src/screens/Home.tsx" };
+
+  // TC6: 프로덕션에서도 번들 경로가 아니라 원본 파일 경로와 줄 번호가 남는다.
+  it("요소에 심긴 경로가 화면 단위 매핑보다 구체적이라 우선한다", () => {
+    const el = {
+      attributes: { [SOURCE_ATTR]: "src/components/SubmitButton.tsx:17:5" },
+    };
+    expect(sourceFromElement(el, base)).toEqual({
+      screenId: "home",
+      sourceFile: "src/components/SubmitButton.tsx",
+      sourceLine: 17,
+    });
+  });
+
+  // TC7: 빌드 플러그인을 안 붙였을 때. 조용히 화면 단위 매핑으로 떨어진다.
+  it("속성이 없으면 화면 단위 매핑을 그대로 쓴다", () => {
+    expect(sourceFromElement({ attributes: {} }, base)).toEqual({
+      screenId: "home",
+      sourceFile: "src/screens/Home.tsx",
+      sourceLine: null,
+    });
+  });
+
+  it("요소도 매핑도 없으면 전부 null 이다(던지지 않는다)", () => {
+    expect(sourceFromElement(null)).toEqual({
+      screenId: null,
+      sourceFile: null,
+      sourceLine: null,
+    });
+  });
+
+  it("속성 값이 망가져 있어도 화면 단위 매핑으로 떨어진다", () => {
+    const el = { attributes: { [SOURCE_ATTR]: "쓰레기값" } };
+    expect(sourceFromElement(el, base).sourceFile).toBe("src/screens/Home.tsx");
+  });
+});

package/src/source-attr.ts

@@ -0,0 +1,86 @@
+// 소스 경로 읽기 — 빌드 플러그인이 요소에 심어둔 속성을 해석한다.
+//
+// 왜 속성인가: 런타임에 React 내부(`_debugSource` 등)에서 얻는 소스 정보는 **개발
+// 빌드에서만** 채워진다. 프로덕션 번들에는 없다. 반면 빌드 시점에 심은 문자열 속성은
+// 미니파이에 훼손되지 않고 React 내부 구조에도 의존하지 않아서, 프로덕션에서도 원본
+// 파일 경로와 줄 번호가 그대로 남는다.
+//
+// 이 모듈은 **읽기만** 한다. 심는 쪽은 `@solhun/feedback-kit-build` 이고, 그 패키지는
+// 선택 사항이다. 속성이 없으면 여기서는 조용히 null 을 돌려주고 위젯은 그대로 동작한다
+// (소스 경로만 빈다).
+
+import type { ElementInfo, SourceMapping } from "./types.js";
+
+/** 빌드 플러그인이 심는 속성 이름. `data-` 라서 DOM 이 그대로 통과시킨다. */
+export const SOURCE_ATTR = "data-fk-source";
+
+/** 해석된 소스 위치. */
+export interface SourceLocation {
+  /** 원본 파일 경로(번들 경로가 아니다). */
+  file: string;
+  /** 1부터 시작하는 줄 번호. */
+  line: number;
+  /** 1부터 시작하는 칼럼. 없으면 null. */
+  column: number | null;
+}
+
+/**
+ * `"src/pages/Home.tsx:42:7"` 을 해석한다.
+ *
+ * 뒤에서부터 숫자 꼬리를 떼어낸다 — 파일 경로 자체에 콜론이 들어갈 수 있어서
+ * (윈도우 드라이브 문자 `C:\`) 앞에서부터 자르면 깨진다.
+ */
+export function parseSourceAttr(value: unknown): SourceLocation | null {
+  if (typeof value !== "string") return null;
+  const raw = value.trim();
+  if (raw === "") return null;
+
+  let rest = raw;
+  let line: number | null = null;
+  let column: number | null = null;
+
+  for (let i = 0; i < 2; i += 1) {
+    const at = rest.lastIndexOf(":");
+    if (at <= 0) break;
+    const tail = rest.slice(at + 1);
+    if (!/^\d+$/.test(tail)) break;
+    const n = Number.parseInt(tail, 10);
+    if (!Number.isFinite(n) || n <= 0) break;
+    rest = rest.slice(0, at);
+    // 뒤에서부터 읽으므로 첫 번째로 떼어낸 숫자가 칼럼, 두 번째가 줄이다.
+    if (line === null) line = n;
+    else {
+      column = line;
+      line = n;
+    }
+  }
+
+  // `rest` 가 콜론으로 시작하면(`":12:3"`) 파일 자리가 비어 있다는 뜻이라 경로가 아니다.
+  if (line === null || rest === "" || rest.startsWith(":")) return null;
+  return { file: rest, line, column };
+}
+
+/**
+ * 지목된 요소에서 소스 매핑을 뽑는다.
+ *
+ * `base` 는 화면 단위 매핑(빌드 플러그인의 screen-map)이다. 요소에서 얻은 파일 경로가
+ * 더 구체적이므로 그걸 우선하고, 화면 식별자는 base 것을 유지한다.
+ */
+export function sourceFromElement(
+  element: Pick<ElementInfo, "attributes"> | null | undefined,
+  base?: SourceMapping | null
+): SourceMapping {
+  const fallback: SourceMapping = {
+    screenId: base?.screenId ?? null,
+    sourceFile: base?.sourceFile ?? null,
+    sourceLine: base?.sourceLine ?? null,
+  };
+
+  const attrs = element?.attributes;
+  if (!attrs) return fallback;
+
+  const loc = parseSourceAttr(attrs[SOURCE_ATTR]);
+  if (!loc) return fallback;
+
+  return { screenId: fallback.screenId, sourceFile: loc.file, sourceLine: loc.line };
+}

package/src/types.ts

@@ -0,0 +1,320 @@
+// @solhun/feedback-kit-core — 통합 계약(공개 타입)
+//
+// 이 파일에 정의된 타입들은 호스트(웹/앱)와 수집 백엔드가 모두 합의한 "제보 계약"이다.
+// 어댑터(FeedbackAdapter)와 위젯은 이 타입들만 안다. 내부 구현(큐/UUID/진단 버퍼)은
+// 비공개 모듈로 숨긴다.
+//
+// 주의: 코어는 플랫폼 무관(순수 TS)이어야 한다. document/window/react-native를 직접
+// 참조하지 않는다. 글로벌(fetch/XMLHttpRequest/console/crypto)은 globalThis로만 접근한다.
+
+// ────────────────────────────────────────────────────────────────────────────
+// 종류 / 우선순위
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 제보 종류. `report`=일반 의견, `annotation`=화면 위 핀 찍힌 주석. */
+export type FeedbackKind = "report" | "annotation";
+
+/**
+ * 우선순위.
+ * - unset: 사용자가 고르지 않음(기본)
+ * - normal / high / urgent: 사용자가 명시적으로 선택
+ */
+export type FeedbackPriority = "unset" | "normal" | "high" | "urgent";
+
+// ────────────────────────────────────────────────────────────────────────────
+// 제보 본문
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 스크린샷 캡처 결과. base64 인코딩된 이미지 데이터 + MIME. 없으면 null. */
+export interface FeedbackScreenshot {
+  base64: string;
+  contentType: "image/png" | "image/jpeg";
+}
+
+/**
+ * 핀 좌표. 스크린샷 이미지 기준 0~1 정규화 실수.
+ * (0,0)=좌상단, (1,1)=우하단. 핀이 없으면 null.
+ */
+export interface FeedbackPin {
+  x: number;
+  y: number;
+}
+
+/** 핀이 찍힌 DOM/RN 요소 정보(선택). 호스트가 채워 넣는다. */
+export interface ElementInfo {
+  tag: string;
+  id: string | null;
+  className: string | null;
+  /** 잘린 가시 텍스트(너무 길면 자른다). */
+  text: string | null;
+  /** 뷰포트/스크린샷 기준 bounding box. 알 수 없으면 null. */
+  boundingBox: { x: number; y: number; width: number; height: number } | null;
+  /** 기타 속성. 값은 문자열로 직렬화한다. */
+  attributes: Record<string, string>;
+  /**
+   * 요소를 다시 찾기 위한 CSS 선택자 경로(웹 전용). 앱처럼 DOM 이 없는 곳은 생략한다.
+   * 선택 필드로 둔 이유: 이 값을 못 구해도 제보 자체는 성립해야 하기 때문이다.
+   */
+  selector?: string | null;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 사용자 / 화면 컨텍스트
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 호스트가 `getUser` 로 넘기는 제보자 신원.
+ * id는 필수(게스트면 영구 게스트 식별자). 나머지는 선택.
+ */
+export interface FeedbackUser {
+  id: string;
+  name?: string;
+  email?: string;
+  role?: string;
+  /** 로그인 사용자가 아니라 게스트면 true. 생략하면 로그인 사용자로 본다. */
+  isGuest?: boolean;
+}
+
+/**
+ * 제보에 실제로 실리는, 해석이 끝난 사용자.
+ *
+ * **게스트도 객체를 채운다** — `isGuest: true` + 기기에 영구 저장된 게스트 식별자.
+ * 전체가 `null`인 경우는 게스트 식별자조차 아직 없는 최초 실행 순간뿐이다
+ * (저장소 접근이 실패해 id를 만들지도 읽지도 못한 상태).
+ */
+export interface ContextUser {
+  id: string | null;
+  email: string | null;
+  isGuest: boolean;
+  name?: string;
+  role?: string;
+}
+
+/**
+ * 빌드 플러그인이 심는 화면↔소스파일 매핑. 후속 wave에서 채워진다.
+ * 코어는 통과만 한다(값을 해석하지 않는다).
+ */
+export interface SourceMapping {
+  screenId: string | null;
+  sourceFile: string | null;
+  /**
+   * 소스 파일 안의 줄 번호(선택).
+   *
+   * 요소 단위 매핑(빌드 플러그인이 심는 `data-fk-source`)에서만 채워진다.
+   * 화면 단위 매핑에는 줄 번호가 없으므로 생략되거나 null 이다.
+   */
+  sourceLine?: number | null;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 진단 링버퍼 항목
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 네트워크 기록 1건.
+ *
+ * 기록 항목은 **메서드·URL·상태코드·소요시간까지**다.
+ * `Authorization` 헤더·쿠키·요청 본문·응답 본문은 어떤 경우에도 담기지 않는다
+ * (수집 코드가 애초에 읽지 않는다 — 필드가 없는 게 아니라 접근 자체를 안 한다).
+ */
+export interface DiagNetworkEntry {
+  method: string;
+  /** 쿼리스트링의 자격증명형 파라미터는 값이 가려진 상태. */
+  url: string;
+  /** 응답을 못 받았으면(네트워크 실패·중단) null. */
+  status: number | null;
+  durationMs: number;
+  /** 기록 시각(ISO 8601). */
+  at: string;
+}
+
+/** 콘솔 기록 1건. `console.warn` / `console.error` 만 대상. */
+export interface DiagLogEntry {
+  level: "warn" | "error";
+  message: string;
+  at: string;
+}
+
+/**
+ * 제보에 실리는 진단 스냅샷.
+ *
+ * 두 배열은 **수집기가 실제로 모은 결과**다. 제출 시점에 비어 있는 것은 정상이고
+ * (그 세션에 요청·경고가 없었다는 뜻), 배선이 안 됐을 때는 배열이 아니라
+ * 컨텍스트의 `diagnostics` 자체가 `null`이 된다. 그래서 "빈 배열"과
+ * "수집 안 함"이 페이로드에서 구분된다.
+ */
+export interface DiagnosticsPayload {
+  network: DiagNetworkEntry[];
+  logs: DiagLogEntry[];
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 앱/웹 전용 컨텍스트
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 앱 빌드 정보. 어느 빌드에서 났는지 특정하는 데 쓴다. */
+export interface AppInfo {
+  version: string | null;
+  channel: string | null;
+  updateId: string | null;
+  runtimeVersion: string | null;
+}
+
+/** 기기 정보. **화면 크기는 여기가 아니라 `display` 다.** */
+export interface DeviceInfo {
+  model: string | null;
+  osName: string | null;
+  osVersion: string | null;
+  deviceType: string | null;
+}
+
+/** 화면 크기/배율. */
+export interface DisplayInfo {
+  width: number | null;
+  height: number | null;
+  pixelRatio: number | null;
+  fontScale: number | null;
+}
+
+/** 앱(React Native) 전용 컨텍스트. */
+export interface NativeContext {
+  /** 화면↔파일 매핑이 있을 때의 소스 파일 경로. 매핑이 없으면 null. */
+  screenPath: string | null;
+  /** 전체 라우트 스택. 바깥(루트)부터 안쪽(현재 화면) 순서. */
+  navPath: string[];
+  /** 현재 화면의 파라미터. JSON 왕복으로 함수·순환참조를 제거한 값. */
+  routeParams: Record<string, unknown> | null;
+  appInfo: AppInfo;
+  device: DeviceInfo;
+  display: DisplayInfo;
+}
+
+/** 웹 전용 컨텍스트. */
+export interface WebContext {
+  viewport: {
+    width: number | null;
+    height: number | null;
+    devicePixelRatio: number | null;
+  };
+  /** userAgent 원문(파싱하지 않고 그대로 싣는다). */
+  userAgent: string | null;
+}
+
+/**
+ * 제보가 만들어진 환경 컨텍스트. 사용자 신원(user)도 여기에 포함된다.
+ * (FeedbackReport의 8개 스펙 필드를 건드리지 않고 신원을 전달하기 위해 context 안에 둔다.)
+ *
+ * 이 타입은 **수집까지**를 정의한다. 여기 담긴 값을 어느 필드에 실어 보낼지는
+ * 어댑터가 정한다(코어는 특정 어댑터의 필드명을 모른다).
+ */
+export interface FeedbackContext {
+  /** 앱/제품 식별자. config.app에서 온다. */
+  app: string;
+  /** 현재 화면 이름/경로(navigationRef에서 채움). 없으면 null. */
+  screen: string | null;
+  /** 현재 URL(웹) 또는 딥링크(앱). 없으면 null. */
+  url: string | null;
+  /** 세션 식별자(UUID). 위젯 인스턴스 단위로 하나. */
+  sessionId: string;
+  /** 제출 시점에 결정된 사용자. 게스트도 객체를 채운다. */
+  user: ContextUser | null;
+  /** 빌드 플러그인 매핑(선택). 없으면 screenId/sourceFile 이 null. */
+  source: SourceMapping;
+  /** 실행 플랫폼. */
+  platform: "web" | "native" | "unknown";
+  /** IANA 타임존 이름(예: `Asia/Seoul`). 알 수 없으면 null. */
+  timezone: string | null;
+  /** 클라이언트 기준 제출 시각(ISO 8601). */
+  clientTimestamp: string;
+  /** 앱 전용 컨텍스트. 웹이거나 공급자가 없으면 null. */
+  native: NativeContext | null;
+  /** 웹 전용 컨텍스트. 앱이거나 공급자가 없으면 null. */
+  web: WebContext | null;
+  /** 진단 링버퍼 스냅샷. 수집이 배선되지 않았으면 null. */
+  diagnostics: DiagnosticsPayload | null;
+  /** 자유 형식 추가 메타. 직렬화 가능한 값만. */
+  extra: Record<string, unknown>;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 제보 / 제출 결과
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 하나의 피드백 제보. 통합 계약의 핵심.
+ * clientSubmissionId / context / createdAt 은 코어가 채운다.
+ * 나머지는 호스트가 submit() 호출 시 제공한다.
+ */
+export interface FeedbackReport {
+  /** 클라이언트에서 만든 UUID v4. 멱등 키(중복 제출 식별용). */
+  clientSubmissionId: string;
+  kind: FeedbackKind;
+  comment: string;
+  priority: FeedbackPriority;
+  screenshot: FeedbackScreenshot | null;
+  pin: FeedbackPin | null;
+  element: ElementInfo | null;
+  context: FeedbackContext;
+  /** 제출 시각(ISO 8601). */
+  createdAt: string;
+}
+
+/**
+ * 어댑터 제출 결과.
+ * - ok: 백엔드가 정상 수락. **HTTP 2xx 만으로는 부족하다** — 응답 본문의 `ok=true`까지
+ *   확인한 뒤에만 true 여야 한다(2xx + ok=false 는 실패로 취급).
+ * - id: 백엔드가 부여한 제보 id(수락 안 됐으면 null). 표시용이며 로컬 키로 쓰지 않는다.
+ * - retryable: 일시적 실패면 true(코어가 재시도).
+ * - retryAfterMs: 백엔드가 권장한 대기 시간. 없으면 null(코어가 백오프로 계산).
+ * - rateLimited: 429(요청 한도 초과)면 true. 재시도 간격의 일반 상한(5분)을 넘겨
+ *   최소 10분 뒤에 다시 시도해야 한다는 신호. 정책 판단은 코어가 한다
+ *   (어댑터는 "429였다"는 사실만 전달한다).
+ */
+export interface SubmitResult {
+  ok: boolean;
+  id: string | null;
+  retryable: boolean;
+  retryAfterMs: number | null;
+  rateLimited?: boolean;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 저장소 / 어댑터 인터페이스 (호스트가 구현)
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 영속 저장소 인터페이스. 코어는 인터페이스만 안다.
+ * - web: localStorage 구현 제공
+ * - native: AsyncStorage 구현 제공
+ * 큐/게스트 식별자가 이 저장소에 의존한다 → 저장소를 바꿔도 동작이 동일(TC4).
+ */
+export interface FeedbackStorage {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  remove(key: string): Promise<void>;
+}
+
+/** 제보를 수집 백엔드로 보내는 어댑터. 호스트(또는 SDK)가 구현. */
+export interface FeedbackAdapter {
+  submit(report: FeedbackReport): Promise<SubmitResult>;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 설정 / 콜백 타입
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 제출 시점에 호출돼 사용자를 반환. 동기/비동기 모두 허용. */
+export type GetUserFn = () => FeedbackUser | Promise<FeedbackUser>;
+
+/** 현재 화면(라우트/스크린 이름)을 반환. 없으면 null. */
+export type GetCurrentScreenFn = () => string | null;
+
+/**
+ * 진단 버퍼가 요청을 캡처할지 결정하는 매처.
+ * true 반환 = 이 요청은 캡처에서 제외(예: 위젯 자신의 전송 요청).
+ */
+export interface DiagRequestRef {
+  url: string;
+  method: string;
+}
+export type DiagnosticsExcludeMatcher = (req: DiagRequestRef) => boolean;

package/src/uuid.test.ts

@@ -0,0 +1,116 @@
+// clientSubmissionId 생성기 검증.
+//
+// 담당 TC: "clientSubmissionId 가 표준 API 없이도 생성된다"(w1 패키지 구조).
+//
+// 이 값은 서버가 쓰는 **멱등 키**다. 재시도할 때마다 값이 흔들리면 같은 제보가 서버에
+// 여러 건 쌓인다. 그래서 검증 대상은 "그럴듯한 문자열이 나온다"가 아니라
+// (1) 형식이 RFC 4122 v4 이고 (2) crypto 가 아예 없는 런타임에서도 나오고
+// (3) 매번 다른 값이라는 세 가지다.
+//
+// crypto 를 지웠다 되돌리는 테스트라 globalThis 를 직접 만진다. 각 케이스가 끝나면
+// 원래 서술자를 복원한다(다른 파일이 crypto 를 쓰기 때문에 누수되면 안 된다).
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { uuidv4 } from "./uuid.js";
+
+const UUID_V4 =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+const g = globalThis as Record<string, unknown>;
+const originalCrypto = Object.getOwnPropertyDescriptor(globalThis, "crypto");
+
+function restoreCrypto(): void {
+  if (originalCrypto) {
+    Object.defineProperty(globalThis, "crypto", originalCrypto);
+  } else {
+    delete g.crypto;
+  }
+}
+
+/** 전역 crypto 를 통째로 교체한다(undefined 면 없는 런타임을 흉내낸다). */
+function setCrypto(value: unknown): void {
+  Object.defineProperty(globalThis, "crypto", {
+    value,
+    configurable: true,
+    writable: true,
+  });
+}
+
+afterEach(() => {
+  restoreCrypto();
+  vi.restoreAllMocks();
+});
+
+describe("uuidv4", () => {
+  it("RFC 4122 v4 형식을 지킨다(버전 4 · 변형 10xx)", () => {
+    for (let i = 0; i < 50; i++) {
+      expect(uuidv4()).toMatch(UUID_V4);
+    }
+  });
+
+  it("crypto 가 아예 없어도 유효한 값을 만든다", () => {
+    setCrypto(undefined);
+
+    const id = uuidv4();
+
+    expect(id).toMatch(UUID_V4);
+  });
+
+  it("crypto 는 있는데 getRandomValues 가 없어도 유효한 값을 만든다", () => {
+    // 보안 컨텍스트가 아닌 웹뷰처럼 crypto 객체는 있지만 알맹이가 빠진 경우.
+    setCrypto({});
+
+    const id = uuidv4();
+
+    expect(id).toMatch(UUID_V4);
+  });
+
+  it("getRandomValues 가 있으면 그걸 쓴다", () => {
+    const getRandomValues = vi.fn((arr: Uint8Array) => {
+      arr.fill(0xab);
+      return arr;
+    });
+    setCrypto({ getRandomValues });
+
+    const id = uuidv4();
+
+    expect(getRandomValues).toHaveBeenCalledTimes(1);
+    // 0xab 로 채운 뒤 버전·변형 비트만 덮이므로 나머지 자리는 전부 ab 다.
+    expect(id).toBe("abababab-abab-4bab-abab-abababababab");
+  });
+
+  it("getRandomValues 가 this 를 요구해도 깨지지 않는다", () => {
+    // 실제 브라우저 구현은 crypto 에 바인딩되지 않은 채 호출하면 예외를 던진다.
+    const cryptoObj = {
+      marker: "real-crypto",
+      getRandomValues(this: { marker?: string }, arr: Uint8Array) {
+        if (this?.marker !== "real-crypto") {
+          throw new TypeError("Illegal invocation");
+        }
+        arr.fill(0x11);
+        return arr;
+      },
+    };
+    setCrypto(cryptoObj);
+
+    expect(() => uuidv4()).not.toThrow();
+    expect(uuidv4()).toMatch(UUID_V4);
+  });
+
+  it("매번 다른 값이다(멱등 키가 겹치면 제보가 서로를 덮는다)", () => {
+    const ids = new Set<string>();
+    for (let i = 0; i < 500; i++) ids.add(uuidv4());
+
+    expect(ids.size).toBe(500);
+  });
+
+  it("crypto 가 없는 폴백 경로에서도 값이 겹치지 않는다", () => {
+    setCrypto(undefined);
+
+    const ids = new Set<string>();
+    for (let i = 0; i < 500; i++) ids.add(uuidv4());
+
+    expect(ids.size).toBe(500);
+  });
+});