@solhun/feedback-kit-web 0.1.0

package/src/screen-map.test.ts

@@ -0,0 +1,455 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  MODAL_ACTION_PICK,
+  MODAL_ACTION_PIN,
+  MODAL_FIELD_COMMENT,
+  FeedbackQueue,
+  type FeedbackAdapter,
+  type FeedbackReport,
+  type FeedbackStorage,
+  type QueueStatus,
+  type ReportParts,
+  type SubmitResult,
+  type SubmitOutcome,
+} from "@solhun/feedback-kit-core";
+import { createNativeWidget } from "../../native/src/widget.js";
+import { MarkerStore, type StorageLike } from "./marker-store.js";
+import { createWebWidget } from "./widget.js";
+
+const SHOT = { base64: "c2NyZWVuc2hvdA==", contentType: "image/png" as const };
+
+class MemoryStorage implements StorageLike {
+  private readonly values = new Map<string, string>();
+
+  getItem(key: string): string | null {
+    return this.values.get(key) ?? null;
+  }
+
+  setItem(key: string, value: string): void {
+    this.values.set(key, value);
+  }
+
+  removeItem(key: string): void {
+    this.values.delete(key);
+  }
+}
+
+class AsyncMemoryStorage implements FeedbackStorage {
+  private readonly values = new Map<string, string>();
+
+  async get(key: string): Promise<string | null> {
+    return this.values.get(key) ?? null;
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    this.values.set(key, value);
+  }
+
+  async remove(key: string): Promise<void> {
+    this.values.delete(key);
+  }
+}
+
+class TestQueue {
+  readonly submitted: FeedbackReport[] = [];
+  private readonly listeners = new Set<(status: QueueStatus) => void>();
+  private nextOutcome: SubmitOutcome = { delivered: true, id: "server-1", queued: false };
+  private deferred: Promise<SubmitOutcome> | null = null;
+  private pendingCount = 0;
+
+  setOutcome(outcome: SubmitOutcome): void {
+    this.nextOutcome = outcome;
+  }
+
+  defer(outcome: Promise<SubmitOutcome>): void {
+    this.deferred = outcome;
+  }
+
+  async submit(report: FeedbackReport): Promise<SubmitOutcome> {
+    this.submitted.push(report);
+    const outcome = this.deferred ? await this.deferred : this.nextOutcome;
+    this.deferred = null;
+    if (!outcome.delivered && outcome.queued) {
+      this.pendingCount += 1;
+      this.emit("pending");
+    }
+    return outcome;
+  }
+
+  async retryNow(): Promise<void> {
+    this.recover();
+  }
+
+  async size(): Promise<number> {
+    return this.pendingCount;
+  }
+
+  subscribe(listener: (status: QueueStatus) => void): () => void {
+    this.listeners.add(listener);
+    listener(this.status());
+    return () => this.listeners.delete(listener);
+  }
+
+  recover(): void {
+    this.pendingCount = 0;
+    this.emit("idle");
+  }
+
+  private status(state: QueueStatus["state"] = this.pendingCount > 0 ? "pending" : "idle"):
+    QueueStatus {
+    return { state, pending: this.pendingCount, lastError: null };
+  }
+
+  private emit(state: QueueStatus["state"]): void {
+    const status = this.status(state);
+    for (const listener of this.listeners) listener(status);
+  }
+}
+
+function reportFactory() {
+  let sequence = 0;
+  return async (parts: ReportParts): Promise<FeedbackReport> => {
+    sequence += 1;
+    return {
+      clientSubmissionId: `submission-${sequence}`,
+      ...parts,
+      context: {
+        app: "test",
+        screen: "/screen",
+        url: "https://example.test/screen",
+        sessionId: "session",
+        user: null,
+        source: { screenId: null, sourceFile: null },
+        platform: "web",
+        timezone: "Asia/Seoul",
+        clientTimestamp: "2026-08-07T00:00:00.000Z",
+        native: null,
+        web: null,
+        diagnostics: null,
+        extra: {},
+      },
+      createdAt: `2026-08-07T00:00:0${sequence}.000Z`,
+    };
+  };
+}
+
+function webFixture(options: {
+  queue?: TestQueue;
+  storage?: MemoryStorage;
+  path?: { current: string };
+} = {}) {
+  const queue = options.queue ?? new TestQueue();
+  const storage = options.storage ?? new MemoryStorage();
+  const path = options.path ?? { current: "/first" };
+  const store = new MarkerStore(storage);
+  const kit = createWebWidget({
+    queue,
+    createReport: reportFactory(),
+    capture: async () => SHOT,
+    store,
+    doc: document,
+    getPathname: () => path.current,
+    getViewport: () => ({ width: 1000, height: 500 }),
+  });
+  return { ...kit, queue, storage, path };
+}
+
+function targetButton(): HTMLButtonElement {
+  const button = document.createElement("button");
+  button.textContent = "저장";
+  button.id = `target-${document.body.childElementCount}`;
+  button.getBoundingClientRect = () =>
+    ({ left: 10, top: 20, width: 100, height: 40 }) as DOMRect;
+  document.body.append(button);
+  return button;
+}
+
+describe("DP-257 화면 지도와 제보 단위", () => {
+  it("TC1 플로팅 버튼을 누르면 리포트 모달이 열린다", async () => {
+    const { widget, dispose } = webFixture();
+
+    expect(widget.getState().screen).toBe("button");
+    await widget.openReport();
+
+    const state = widget.getState();
+    expect(state.screen).toBe("modal");
+    expect(state.modal.open).toBe(true);
+    expect(state.modal.focusOrder).toContain(MODAL_FIELD_COMMENT);
+    expect(state.modal.screenshotStatus).toBe("ready");
+    dispose();
+  });
+
+  it("TC2 주석을 저장하면 마커가 생기고 지목 모드가 유지된다", async () => {
+    const { widget, picking, queue, dispose } = webFixture();
+    widget.startPicking();
+    picking.openAnnotation(targetButton(), { x: 100, y: 100 });
+    picking.setAnnotationComment("첫 주석");
+
+    await picking.saveAnnotation();
+
+    expect(queue.submitted).toHaveLength(1);
+    expect(picking.getState().markers).toHaveLength(1);
+    expect(picking.getState().markers[0]?.status).toBe("done");
+    expect(widget.getState().screen).toBe("picking");
+    expect(picking.isActive).toBe(true);
+    dispose();
+  });
+
+  it("TC3 모달을 취소하면 플로팅 버튼 화면으로 돌아온다", async () => {
+    const { widget, queue, dispose } = webFixture();
+    await widget.openReport();
+
+    expect(widget.closeReport()).toBe("closed");
+
+    expect(widget.getState().screen).toBe("button");
+    expect(queue.submitted).toHaveLength(0);
+    dispose();
+  });
+
+  it("TC4 주석 팝업을 취소하면 아무것도 남지 않는다", () => {
+    const { widget, picking, queue, dispose } = webFixture();
+    widget.startPicking();
+    picking.openAnnotation(targetButton(), { x: 10, y: 20 });
+    picking.setAnnotationComment("취소할 주석");
+
+    picking.cancelAnnotation();
+
+    expect(picking.getState().popup).toBeNull();
+    expect(picking.getState().markers).toHaveLength(0);
+    expect(queue.submitted).toHaveLength(0);
+    expect(picking.isActive).toBe(true);
+    dispose();
+  });
+
+  it("TC5 코멘트를 넣고 보내면 전송 상태가 보인다", async () => {
+    const queue = new TestQueue();
+    let finish!: (outcome: SubmitOutcome) => void;
+    queue.defer(new Promise((resolve) => { finish = resolve; }));
+    const { widget, dispose } = webFixture({ queue });
+    await widget.openReport();
+    widget.modal.setComment("전송 상태 확인");
+
+    const submitting = widget.submitReport();
+    expect(widget.getState().modal.submitStatus).toBe("sending");
+    finish({ delivered: true, id: "server-1", queued: false });
+    await submitting;
+    dispose();
+  });
+
+  it("TC6 페이지를 이동하거나 새로고침해도 지목 모드가 유지된다", () => {
+    const storage = new MemoryStorage();
+    const path = { current: "/first" };
+    const first = webFixture({ storage, path });
+    first.widget.startPicking();
+    path.current = "/second";
+    first.picking.syncPath();
+    expect(first.picking.isActive).toBe(true);
+    first.dispose();
+
+    const restored = webFixture({ storage, path });
+    const target = targetButton();
+    target.dispatchEvent(new MouseEvent("mouseover", { bubbles: true }));
+    expect(restored.widget.getState().screen).toBe("picking");
+    expect(restored.picking.isActive).toBe(true);
+    expect(restored.picking.getState().hovered?.selector).not.toBeNull();
+    restored.dispose();
+  });
+
+  it("TC7 전송에 성공하면 완료를 알리고 모달이 닫힌다", async () => {
+    const { widget, queue, dispose } = webFixture();
+    await widget.openReport();
+    widget.modal.setComment("성공 제보");
+
+    await widget.submitReport();
+
+    expect(widget.getState().modal.submitMessage).toBe("보냈습니다");
+    expect(widget.getState().modal.open).toBe(false);
+    expect(widget.getState().screen).toBe("button");
+    expect(await queue.size()).toBe(0);
+    dispose();
+  });
+
+  it("TC8 지목 종료를 누르면 모드가 꺼진다", () => {
+    const storage = new MemoryStorage();
+    const first = webFixture({ storage });
+    first.widget.startPicking();
+    first.widget.stopPicking();
+    expect(first.widget.getState().screen).toBe("button");
+    first.dispose();
+
+    const restored = webFixture({ storage });
+    expect(restored.picking.isActive).toBe(false);
+    expect(restored.widget.getState().screen).toBe("button");
+    restored.dispose();
+  });
+
+  it("TC9 전송에 실패하면 입력을 보존한 채 대기 큐에 남는다", async () => {
+    const queue = new TestQueue();
+    queue.setOutcome({ delivered: false, id: null, queued: true });
+    const { widget, dispose } = webFixture({ queue });
+    await widget.openReport();
+    widget.modal.setComment("오프라인 제보");
+    widget.modal.setPriority("urgent");
+
+    await widget.submitReport();
+
+    const state = widget.getState().modal;
+    expect(state.submitMessage).toBe("대기 중");
+    expect(state.showRetry).toBe(true);
+    expect(state.pending).toBe(1);
+    expect(state.comment).toBe("오프라인 제보");
+    expect(state.priority).toBe("urgent");
+    expect(state.screenshot).toEqual(SHOT);
+    dispose();
+  });
+
+  it("TC10 앱에서 핀 찍기로 좌표를 지정한다", async () => {
+    const queue = new TestQueue();
+    const widget = createNativeWidget({
+      queue,
+      createReport: reportFactory(),
+      capture: () => SHOT,
+    });
+    await widget.openReport();
+
+    expect(widget.getState().modal.actions).toContain(MODAL_ACTION_PIN);
+    expect(widget.openPinScreen()).toBe(true);
+    widget.placePin({ x: 25, y: 75 }, { width: 100, height: 100 });
+    expect(widget.getState().screen).toBe("pin");
+    expect(widget.getState().pinDraft).toEqual({ x: 0.25, y: 0.75 });
+    widget.dispose();
+  });
+
+  it("TC11 연결이 복구되면 대기 큐가 같은 id로 자동으로 비워진다", async () => {
+    let online = false;
+    const requests: string[] = [];
+    const stored = new Set<string>();
+    const adapter: FeedbackAdapter = {
+      async submit(report): Promise<SubmitResult> {
+        requests.push(report.clientSubmissionId);
+        if (!online) {
+          return { ok: false, id: null, retryable: true, retryAfterMs: null };
+        }
+        stored.add(report.clientSubmissionId);
+        return { ok: true, id: "server-1", retryable: false, retryAfterMs: null };
+      },
+    };
+    const queue = new FeedbackQueue({
+      adapter,
+      storage: new AsyncMemoryStorage(),
+      flushIntervalMs: 0,
+    });
+    const storage = new MemoryStorage();
+    const store = new MarkerStore(storage);
+    const kit = createWebWidget({
+      queue,
+      createReport: reportFactory(),
+      capture: () => SHOT,
+      store,
+      doc: document,
+    });
+    const { widget, dispose } = kit;
+    await widget.openReport();
+    widget.modal.setComment("복구할 제보");
+    await widget.submitReport();
+    const firstId = widget.modal.getLastReport()?.clientSubmissionId;
+
+    online = true;
+    // 브라우저의 online listener가 내부적으로 호출하는 동일 경로를 직접 실행한다.
+    await queue.retryNow();
+    await vi.waitFor(async () => {
+      expect(await queue.size()).toBe(0);
+    });
+
+    expect(requests).toEqual([firstId, firstId]);
+    expect(stored).toEqual(new Set([firstId!]));
+    expect(widget.modal.getLastReport()?.clientSubmissionId).toBe(firstId);
+    expect(widget.getState().modal.pending).toBe(0);
+    expect(widget.getState().screen).toBe("button");
+    dispose();
+  });
+
+  it("TC12 핀을 지정하면 모달로 돌아와 좌표가 유지된다", async () => {
+    const queue = new TestQueue();
+    const widget = createNativeWidget({
+      queue,
+      createReport: reportFactory(),
+      capture: () => SHOT,
+    });
+    await widget.openReport();
+    widget.openPinScreen();
+    widget.placePin({ x: 20, y: 30 }, { width: 100, height: 100 });
+
+    widget.confirmPin();
+    widget.modal.setComment("핀 포함");
+    await widget.submitReport();
+
+    expect(queue.submitted[0]?.pin).toEqual({ x: 0.2, y: 0.3 });
+    widget.dispose();
+  });
+
+  it("TC13 모달에서 요소 지목 모드로 전환된다", async () => {
+    const { widget, picking, dispose } = webFixture();
+    await widget.openReport();
+    expect(widget.getState().modal.actions).toContain(MODAL_ACTION_PICK);
+
+    expect(widget.startPicking()).toBe(true);
+
+    expect(widget.getState().modal.open).toBe(false);
+    expect(widget.getState().screen).toBe("picking");
+    expect(picking.isActive).toBe(true);
+    dispose();
+  });
+
+  it("TC14 리포트 모달 제출 1회는 제보 1건만 만든다", async () => {
+    const { widget, queue, dispose } = webFixture();
+    await widget.openReport();
+    widget.modal.setComment("한 번만");
+
+    await widget.submitReport();
+
+    expect(queue.submitted).toHaveLength(1);
+    expect(queue.submitted[0]?.kind).toBe("report");
+    dispose();
+  });
+
+  it("TC15 요소를 클릭하면 주석 팝업이 열리고 페이지 클릭은 막힌다", () => {
+    const { widget, picking, dispose } = webFixture();
+    const link = document.createElement("a");
+    link.href = "https://example.test/next";
+    link.textContent = "이동";
+    document.body.append(link);
+    const pageHandler = vi.fn();
+    link.addEventListener("click", pageHandler);
+    widget.startPicking();
+
+    const allowed = link.dispatchEvent(new MouseEvent("click", {
+      bubbles: true,
+      cancelable: true,
+      clientX: 100,
+      clientY: 50,
+    }));
+
+    expect(allowed).toBe(false);
+    expect(pageHandler).not.toHaveBeenCalled();
+    expect(picking.getState().popup?.element?.tag).toBe("a");
+    dispose();
+  });
+
+  it("TC16 주석 3개를 찍으면 제보 3건이 생긴다", async () => {
+    const { widget, picking, queue, dispose } = webFixture();
+    widget.startPicking();
+
+    for (let index = 0; index < 3; index += 1) {
+      picking.openAnnotation(targetButton(), { x: 100 + index, y: 50 });
+      picking.setAnnotationComment(`주석 ${index + 1}`);
+      await picking.saveAnnotation();
+    }
+
+    expect(queue.submitted).toHaveLength(3);
+    expect(new Set(queue.submitted.map((report) => report.clientSubmissionId)).size).toBe(3);
+    expect(queue.submitted.every((report) => report.kind === "annotation")).toBe(true);
+    dispose();
+  });
+});

package/src/screenshot.test.ts

@@ -0,0 +1,47 @@
+// 웹 스크린샷 캡처.
+//
+// 라이브러리(html2canvas-pro)가 실제 래스터화를 맡으므로 여기서 검증하는 것은
+// **우리가 책임지는 계약**이다: 위젯 자기 UI 제외 / 실패해도 던지지 않고 null /
+// 비브라우저에서 안전.
+//
+// 왜 직접 만든 SVG foreignObject 방식을 버렸나: 그 방식은 캔버스를 tainted 시켜
+// `toDataURL` 이 SecurityError 를 던진다 → 캡처가 **항상** 실패한다. 실측 확인:
+// 같은 브라우저에서 일반 SVG 는 오염되지 않고 foreignObject 만 오염된다.
+
+import { describe, expect, it, vi } from "vitest";
+
+import { captureWebScreenshot, isOwnUi } from "./screenshot.js";
+import { OWN_UI_ATTR } from "./picking.js";
+
+describe("자기 UI 제외", () => {
+  it("위젯 루트와 그 자손은 캡처에서 뺀다", () => {
+    document.body.innerHTML = `
+      <div id="page"><p id="text">본문</p></div>
+      <div id="widget" ${OWN_UI_ATTR}><button id="btn">보내기</button></div>`;
+
+    expect(isOwnUi(document.getElementById("widget")!)).toBe(true);
+    // 자손도 빠져야 한다 — 모달 안 버튼이 결과에 찍히면 안 된다.
+    expect(isOwnUi(document.getElementById("btn")!)).toBe(true);
+    expect(isOwnUi(document.getElementById("page")!)).toBe(false);
+    expect(isOwnUi(document.getElementById("text")!)).toBe(false);
+  });
+});
+
+describe("captureWebScreenshot", () => {
+  it("라이브러리가 던져도 null 로 물러난다(제보 흐름을 막지 않는다)", async () => {
+    // jsdom 에는 캔버스가 없어 라이브러리가 실패한다 — 그 경로가 곧 이 테스트다.
+    // 여기서 예외가 새면 모달이 통째로 죽는다.
+    await expect(captureWebScreenshot()).resolves.toBeNull();
+  });
+
+  it("document 가 없는 환경에서도 던지지 않는다", async () => {
+    const original = Object.getOwnPropertyDescriptor(globalThis, "document");
+    Object.defineProperty(globalThis, "document", { value: undefined, configurable: true });
+    try {
+      await expect(captureWebScreenshot()).resolves.toBeNull();
+    } finally {
+      if (original) Object.defineProperty(globalThis, "document", original);
+      vi.restoreAllMocks();
+    }
+  });
+});

package/src/screenshot.ts

@@ -0,0 +1,90 @@
+import type { ScreenshotCapture, ScreenshotReencode } from "@solhun/feedback-kit-core";
+import html2canvas from "html2canvas-pro";
+
+import { OWN_UI_ATTR } from "./picking.js";
+
+/**
+ * 왜 라이브러리를 쓰나 (직접 만든 SVG foreignObject 방식에서 갈아탄 이유):
+ *
+ * `<foreignObject>` 로 DOM 을 감싼 SVG 를 캔버스에 그리면 **캔버스가 tainted 되어**
+ * `toDataURL()` 이 `SecurityError` 를 던진다. 즉 캡처가 항상 null 이 되고, 사용자는
+ * 매번 "캡처 실패 — 파일로 첨부할 수 있습니다"만 본다. 실측으로 확인했다:
+ * 같은 브라우저에서 일반 SVG(rect)는 오염되지 않고 `foreignObject` 만 오염된다.
+ *
+ * html2canvas-pro(MIT)는 foreignObject 를 쓰지 않는다. DOM 을 순회하며 캔버스에
+ * 직접 그리므로 오염 자체가 생기지 않는다. 명세의 "DOM 을 이미지로 변환하는 MIT
+ * 라이브러리를 쓴다"도 원래 이 뜻이었다.
+ */
+
+function payload(dataUrl: string): string | null {
+  const comma = dataUrl.indexOf(",");
+  return comma >= 0 ? dataUrl.slice(comma + 1) : null;
+}
+
+/** 캡처에서 빼야 할 노드인가(위젯 자신의 UI). 결과에 자기 모달이 찍히면 안 된다. */
+export function isOwnUi(node: Element): boolean {
+  return node.hasAttribute?.(OWN_UI_ATTR) === true
+    || node.closest?.(`[${OWN_UI_ATTR}]`) !== null;
+}
+
+/**
+ * 웹 기본 캡처 — 현재 viewport 를 JPEG 로.
+ *
+ * 실패하면 **null 을 돌려준다**(던지지 않는다). 코어가 "캡처 실패" 상태로 바꾸고
+ * 사용자는 파일로 첨부할 수 있다 — 그림 때문에 제보 자체를 잃지 않는다.
+ */
+export const captureWebScreenshot: ScreenshotCapture = async () => {
+  const doc = globalThis.document;
+  const view = doc?.defaultView;
+  if (!doc?.documentElement || !view) return null;
+
+  try {
+    const canvas = await html2canvas(doc.documentElement, {
+      // 현재 보이는 화면만. 문서 전체를 그리면 제보와 무관한 영역까지 커진다.
+      width: view.innerWidth,
+      height: view.innerHeight,
+      x: view.scrollX,
+      y: view.scrollY,
+      windowWidth: view.innerWidth,
+      windowHeight: view.innerHeight,
+      // 배율은 2배까지만. 그 위는 용량만 커지고 8 MiB 한도에 먼저 걸린다.
+      scale: Math.min(2, Math.max(1, view.devicePixelRatio || 1)),
+      // 위젯 자신의 UI 는 결과에서 뺀다.
+      ignoreElements: isOwnUi,
+      // 외부 이미지가 CORS 를 안 열어두면 그것 때문에 전체가 실패할 수 있다.
+      // 못 가져오는 리소스는 건너뛰고 나머지를 그린다.
+      useCORS: true,
+      allowTaint: false,
+      logging: false,
+      backgroundColor: null,
+    });
+    return { base64: payload(canvas.toDataURL("image/jpeg", 0.9)) ?? "", contentType: "image/jpeg" };
+  } catch {
+    return null;
+  }
+};
+
+/** 8 MiB 정책이 요구할 때 기존 이미지를 JPEG 품질 단계로 다시 인코딩한다. */
+export const reencodeWebScreenshot: ScreenshotReencode = async (shot, quality) => {
+  const doc = globalThis.document;
+  if (!doc) return null;
+  try {
+    const image = await new Promise<HTMLImageElement | null>((resolve) => {
+      const img = new Image();
+      img.onload = () => resolve(img);
+      img.onerror = () => resolve(null);
+      img.src = `data:${shot.contentType};base64,${shot.base64}`;
+    });
+    if (!image) return null;
+    const canvas = doc.createElement("canvas");
+    canvas.width = image.naturalWidth || image.width;
+    canvas.height = image.naturalHeight || image.height;
+    const context = canvas.getContext("2d");
+    if (!context) return null;
+    context.drawImage(image, 0, 0);
+    const base64 = payload(canvas.toDataURL("image/jpeg", quality));
+    return base64 ? { base64, contentType: "image/jpeg" } : null;
+  } catch {
+    return null;
+  }
+};

package/src/storage.test.ts

@@ -0,0 +1,65 @@
+// 웹 기본 저장소 — localStorage 계약과 폴백.
+
+import { describe, expect, it, vi } from "vitest";
+
+import { createWebStorage } from "./storage.js";
+
+function fake() {
+  const map = new Map<string, string>();
+  return {
+    map,
+    getItem: (k: string) => map.get(k) ?? null,
+    setItem: (k: string, v: string) => void map.set(k, v),
+    removeItem: (k: string) => void map.delete(k),
+  };
+}
+
+describe("createWebStorage", () => {
+  it("get/set/remove 왕복이 된다", async () => {
+    const s = createWebStorage(fake());
+    await s.set("k", "v");
+    expect(await s.get("k")).toBe("v");
+    await s.remove("k");
+    expect(await s.get("k")).toBeNull();
+  });
+
+  it("없는 키는 null 이다", async () => {
+    expect(await createWebStorage(fake()).get("nope")).toBeNull();
+  });
+
+  it("쿼터 초과는 그대로 던진다(큐가 스크린샷을 떼어내야 한다)", async () => {
+    const backing = fake();
+    backing.setItem = () => {
+      throw new Error("QuotaExceededError");
+    };
+    // 여기서 삼키면 큐가 축소 경로를 못 타고 제보를 통째로 잃는다.
+    await expect(createWebStorage(backing).set("k", "v")).rejects.toThrow(/Quota/);
+  });
+
+  it("읽기가 던지면 null 로 물러난다(제보 흐름을 막지 않는다)", async () => {
+    const backing = fake();
+    backing.getItem = () => {
+      throw new Error("SecurityError");
+    };
+    expect(await createWebStorage(backing).get("k")).toBeNull();
+  });
+
+  it("localStorage 를 아예 못 쓰면 메모리로 물러난다", async () => {
+    const original = Object.getOwnPropertyDescriptor(globalThis, "localStorage");
+    Object.defineProperty(globalThis, "localStorage", {
+      configurable: true,
+      get() {
+        throw new Error("사파리 프라이빗 모드");
+      },
+    });
+    try {
+      const s = createWebStorage(); // 인자 없이 = 전역을 고르는 경로
+      await s.set("k", "v");
+      expect(await s.get("k")).toBe("v"); // 메모리라도 동작은 같다
+    } finally {
+      if (original) Object.defineProperty(globalThis, "localStorage", original);
+      else delete (globalThis as Record<string, unknown>).localStorage;
+      vi.restoreAllMocks();
+    }
+  });
+});