@solhun/feedback-kit-web 0.1.0

package/src/index.ts

@@ -0,0 +1,97 @@
+// @solhun/feedback-kit-web
+//
+// 웹용 피드백 위젯 엔트리.
+//
+// 화면 지도·리포트 모달·핀 좌표 계산은 전부 코어에 있다. 여기 있는 건 웹에서만 뜻이 있는 것들 —
+// DOM 요소를 제보에 실을 형태로 옮기고(`element-info`), 지목 모드와 마커를 브라우저 저장소에
+// 남기고(`marker-store`), 페이지 클릭을 가로채 주석을 다는 것(`picking`) — 뿐이다.
+
+export type {
+  FeedbackReport,
+  SubmitResult,
+  FeedbackContext,
+  FeedbackUser,
+  FeedbackStorage,
+  FeedbackAdapter,
+  ElementInfo,
+  FeedbackPin,
+} from "@solhun/feedback-kit-core";
+
+// 설정은 코어가 정의한다. 웹/앱이 각자 다른 설정 타입을 갖지 않는 게 중요해서
+// (같은 설정을 두 곳에 적으면 갈라진다) 여기서는 다시 내보내기만 한다.
+export type {
+  FeedbackConfig,
+  ResolvedConfig,
+  Visibility,
+  VisibilityEnv,
+  VisibilityFn,
+  WidgetPosition,
+} from "@solhun/feedback-kit-core";
+export { resolveConfig, shouldShowWidget } from "@solhun/feedback-kit-core";
+
+// 빌드 플러그인이 심은 소스 경로를 읽는 쪽. 플러그인이 없으면 조용히 null 이다.
+export { parseSourceAttr, SOURCE_ATTR, sourceFromElement } from "@solhun/feedback-kit-core";
+
+// 코어의 헤드리스 위젯 계층. 웹 컴포넌트가 이 상태기계를 그대로 그린다.
+export type {
+  ModalSubmitStatus,
+  ReportModalState,
+  ScreenshotStatus,
+  WidgetScreen,
+  WidgetState,
+} from "@solhun/feedback-kit-core";
+export {
+  COMMENT_MAX_CHARS,
+  COMMENT_REQUIRED_MESSAGE,
+  COMMENT_TOO_LONG_MESSAGE,
+  denormalizePin,
+  FLOATING_BUTTON_ID,
+  MODAL_ACTION_PICK,
+  normalizePin,
+  ReportModalController,
+  SCREENSHOT_FAILED_MESSAGE,
+  SUBMIT_DONE_MESSAGE,
+  SUBMIT_PENDING_MESSAGE,
+  WidgetController,
+} from "@solhun/feedback-kit-core";
+
+// ── 웹 전용 ────────────────────────────────────────────────────────────────
+
+export {
+  cssSelectorPath,
+  describeElement,
+  ELEMENT_TEXT_MAX_CHARS,
+  SELECTOR_MAX_DEPTH,
+  visibleText,
+} from "./element-info.js";
+
+export type { MarkerStatus, StorageLike, StoredMarker } from "./marker-store.js";
+export {
+  MARKER_KEY_PREFIX,
+  MarkerStore,
+  MAX_MARKERS_PER_PATH,
+  PICKING_MODE_KEY,
+} from "./marker-store.js";
+
+export type {
+  AnnotationPopupState,
+  ElementPickingOpts,
+  PickingListener,
+  PickingQueueLike,
+  PickingState,
+} from "./picking.js";
+export { ElementPickingController, OWN_UI_ATTR } from "./picking.js";
+
+export { captureWebScreenshot, isOwnUi, reencodeWebScreenshot } from "./screenshot.js";
+
+export type { WebWidget, WebWidgetOpts } from "./widget.js";
+export { createWebWidget } from "./widget.js";
+
+export type { FeedbackKitProps } from "./feedback-kit.js";
+export { FeedbackKit } from "./feedback-kit.js";
+
+// 웹 기본 저장소(localStorage). 앱마다 다시 쓰지 않게 패키지가 제공한다.
+export { createWebStorage } from "./storage.js";
+
+// 웹 기본 컨텍스트 제공자(getUrl 등). 붙이는 쪽이 잊으면 제보가 버려진다.
+export { webContextProviders } from "./providers.js";

package/src/marker-store.ts

@@ -0,0 +1,153 @@
+// 요소 지목 모드와 마커를 브라우저 저장소에 남긴다.
+//
+// 왜 저장하나: 지목 모드는 페이지를 옮겨 다니며 쓰는 기능이라 새로고침·이동에 살아남아야 하고,
+// 찍은 마커는 같은 경로로 돌아왔을 때 원래 자리에 다시 보여야 한다.
+//
+// 키 이름은 `feedback-kit:` 로 시작하는 우리 고유 네임스페이스를 쓴다. 남의 위젯과 키가 겹치면
+// 서로의 상태를 지우게 된다.
+
+/** 지목 모드 on/off 플래그. */
+export const PICKING_MODE_KEY = "feedback-kit:picking-mode";
+
+/** 경로별 마커 목록. 실제 키는 여기에 pathname 을 이어 붙인다. */
+export const MARKER_KEY_PREFIX = "feedback-kit:markers:";
+
+/** 한 경로에 남겨 둘 마커 상한. 넘으면 오래된 것부터 버린다. */
+export const MAX_MARKERS_PER_PATH = 50;
+
+/** 마커에 보이는 전송 상태. `sending` → `done`, 실패하면 `pending`. */
+export type MarkerStatus = "sending" | "done" | "pending";
+
+export interface StoredMarker {
+  /** 제보의 `clientSubmissionId` 와 같다 — 전송 상태를 되짚어 갱신하려고 맞춰 둔다. */
+  id: string;
+  /** 뷰포트 기준 상대 좌표(0~1). 해상도가 달라도 같은 지점을 가리킨다. */
+  x: number;
+  y: number;
+  selector: string | null;
+  comment: string;
+  status: MarkerStatus;
+  /** 생성 시각(ISO). 상한을 넘겼을 때 무엇을 버릴지 정하는 기준. */
+  at: string;
+}
+
+/** `localStorage` 가 만족하는 최소 계약. 테스트에서 갈아 끼운다. */
+export interface StorageLike {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+function defaultStorage(): StorageLike | null {
+  try {
+    const ls = (globalThis as { localStorage?: StorageLike }).localStorage;
+    return ls ?? null;
+  } catch {
+    // 사파리 프라이빗 모드처럼 접근 자체가 던지는 환경이 있다.
+    return null;
+  }
+}
+
+function markerKey(pathname: string): string {
+  return `${MARKER_KEY_PREFIX}${pathname}`;
+}
+
+/**
+ * 저장소 접근을 한 곳으로 모은다.
+ *
+ * 저장소가 없거나(SSR) 던지는 환경(프라이빗 모드·용량 초과)에서도 위젯이 죽으면 안 되므로
+ * 모든 접근을 try/catch 로 감싸고 실패는 조용히 흘린다. 저장 실패는 "마커가 안 남는다" 정도의
+ * 불편이지 제보 자체를 막을 이유가 아니다.
+ */
+export class MarkerStore {
+  private readonly storage: StorageLike | null;
+
+  constructor(storage?: StorageLike | null) {
+    this.storage = storage === undefined ? defaultStorage() : storage;
+  }
+
+  private read(key: string): string | null {
+    try {
+      return this.storage?.getItem(key) ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  private write(key: string, value: string): void {
+    try {
+      this.storage?.setItem(key, value);
+    } catch {
+      /* 저장 실패는 흘린다 */
+    }
+  }
+
+  private drop(key: string): void {
+    try {
+      this.storage?.removeItem(key);
+    } catch {
+      /* 삭제 실패도 흘린다 */
+    }
+  }
+
+  // ── 지목 모드 ─────────────────────────────────────────────────────────────
+
+  isPickingActive(): boolean {
+    return this.read(PICKING_MODE_KEY) === "1";
+  }
+
+  setPickingActive(active: boolean): void {
+    if (active) this.write(PICKING_MODE_KEY, "1");
+    else this.drop(PICKING_MODE_KEY);
+  }
+
+  // ── 마커 ──────────────────────────────────────────────────────────────────
+
+  list(pathname: string): StoredMarker[] {
+    const raw = this.read(markerKey(pathname));
+    if (!raw) return [];
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      if (!Array.isArray(parsed)) return [];
+      // 남이 쓴 값이나 옛 포맷이 섞여 있어도 위젯이 깨지지 않게 형태를 확인하고 거른다.
+      return parsed.filter((item): item is StoredMarker => {
+        if (typeof item !== "object" || item === null) return false;
+        const m = item as Partial<StoredMarker>;
+        return (
+          typeof m.id === "string" && typeof m.x === "number" && typeof m.y === "number"
+        );
+      });
+    } catch {
+      return [];
+    }
+  }
+
+  /** 같은 id 가 있으면 덮어쓰고, 없으면 뒤에 붙인다. */
+  upsert(pathname: string, marker: StoredMarker): StoredMarker[] {
+    const current = this.list(pathname);
+    const index = current.findIndex((m) => m.id === marker.id);
+    if (index >= 0) current[index] = marker;
+    else current.push(marker);
+
+    const trimmed =
+      current.length > MAX_MARKERS_PER_PATH
+        ? current.slice(current.length - MAX_MARKERS_PER_PATH)
+        : current;
+    this.write(markerKey(pathname), JSON.stringify(trimmed));
+    return trimmed;
+  }
+
+  /** 전송 상태만 바꾼다. 없는 id 면 아무것도 하지 않는다. */
+  updateStatus(pathname: string, id: string, status: MarkerStatus): StoredMarker[] {
+    const current = this.list(pathname);
+    const index = current.findIndex((m) => m.id === id);
+    if (index < 0) return current;
+    current[index] = { ...current[index], status };
+    this.write(markerKey(pathname), JSON.stringify(current));
+    return current;
+  }
+
+  clear(pathname: string): void {
+    this.drop(markerKey(pathname));
+  }
+}

package/src/picking.test.ts

@@ -0,0 +1,249 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  MODAL_ACTION_PICK,
+  MODAL_ACTION_PIN,
+  WidgetController,
+  sourceFromElement,
+  type FeedbackReport,
+  type QueueStatus,
+  type ReportParts,
+  type SubmitOutcome,
+} from "@solhun/feedback-kit-core";
+import { MarkerStore, type StorageLike } from "./marker-store.js";
+import { ElementPickingController } from "./picking.js";
+
+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 TestQueue {
+  readonly submitted: FeedbackReport[] = [];
+  private readonly listeners = new Set<(status: QueueStatus) => void>();
+  private readonly outcomes = new Map<
+    string,
+    Pick<SubmitOutcome, "delivered" | "id">
+  >();
+  outcome: SubmitOutcome = { delivered: true, id: "server-1", queued: false };
+  pending = 0;
+  deferred: Promise<SubmitOutcome> | null = null;
+
+  async submit(report: FeedbackReport): Promise<SubmitOutcome> {
+    this.submitted.push(report);
+    const outcome = this.deferred ? await this.deferred : this.outcome;
+    if (outcome.queued) {
+      this.pending += 1;
+      this.emit();
+    } else {
+      this.outcomes.set(report.clientSubmissionId, outcome);
+    }
+    return outcome;
+  }
+
+  async retryNow(): Promise<void> {}
+  async size(): Promise<number> { return this.pending; }
+
+  subscribe(listener: (status: QueueStatus) => void): () => void {
+    this.listeners.add(listener);
+    listener(this.status());
+    return () => this.listeners.delete(listener);
+  }
+
+  getOutcome(clientSubmissionId: string): Pick<SubmitOutcome, "delivered" | "id"> | null {
+    return this.outcomes.get(clientSubmissionId) ?? null;
+  }
+
+  settle(
+    clientSubmissionId: string,
+    outcome: Pick<SubmitOutcome, "delivered" | "id">,
+    remaining: number,
+  ): void {
+    this.outcomes.set(clientSubmissionId, outcome);
+    this.pending = remaining;
+    this.emit();
+  }
+
+  private status(): QueueStatus {
+    return { state: this.pending > 0 ? "pending" : "idle", pending: this.pending, lastError: null };
+  }
+
+  private emit(): void {
+    const status = this.status();
+    for (const listener of this.listeners) listener(status);
+  }
+}
+
+function reportFactory() {
+  let sequence = 0;
+  return async (parts: ReportParts): Promise<FeedbackReport> => {
+    sequence += 1;
+    return {
+      clientSubmissionId: `annotation-${sequence}`,
+      ...parts,
+      context: {
+        app: "picking-test",
+        screen: "/",
+        url: null,
+        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 button(label: string, withSource = false): HTMLButtonElement {
+  const element = document.createElement("button");
+  element.textContent = label;
+  element.id = `button-${document.body.childElementCount + 1}`;
+  if (withSource) element.setAttribute("data-fk-source", "src/Button.tsx:12:3");
+  element.getBoundingClientRect = () =>
+    ({ left: 10, top: 20, width: 120, height: 36 }) as DOMRect;
+  document.body.append(element);
+  return element;
+}
+
+function fixture(options: { queue?: TestQueue; path?: { current: string }; storage?: MemoryStorage } = {}) {
+  const queue = options.queue ?? new TestQueue();
+  const path = options.path ?? { current: "/a" };
+  const storage = options.storage ?? new MemoryStorage();
+  const store = new MarkerStore(storage);
+  const picking = new ElementPickingController({
+    queue,
+    createReport: reportFactory(),
+    store,
+    doc: document,
+    getPathname: () => path.current,
+    getViewport: () => ({ width: 1000, height: 500 }),
+  });
+  picking.start();
+  return { path, picking, queue, storage, store };
+}
+
+async function annotate(
+  picking: ElementPickingController,
+  element: Element,
+  comment: string,
+  point = { x: 100, y: 50 },
+): Promise<SubmitOutcome | null> {
+  picking.openAnnotation(element, point);
+  picking.setAnnotationComment(comment);
+  return picking.saveAnnotation();
+}
+
+describe("DP-259 요소 지목 모드", () => {
+  it("TC1 앱에서는 지목 토글이 노출되지 않는다", async () => {
+    const queue = new TestQueue();
+    const widget = new WidgetController({
+      queue,
+      createReport: reportFactory(),
+      platform: "native",
+      capture: () => ({ base64: "shot", contentType: "image/png" }),
+    });
+    await widget.openReport();
+
+    expect(widget.getState().modal.actions).toEqual([MODAL_ACTION_PIN]);
+    expect(widget.getState().modal.actions).not.toContain(MODAL_ACTION_PICK);
+    expect(widget.startPicking()).toBe(false);
+    widget.dispose();
+  });
+
+  it("TC2 마커에 전송 상태가 단계별로 보인다", async () => {
+    const queue = new TestQueue();
+    let finish!: (outcome: SubmitOutcome) => void;
+    queue.deferred = new Promise((resolve) => { finish = resolve; });
+    const { picking } = fixture({ queue });
+
+    const saving = annotate(picking, button("저장"), "상태 확인");
+    await vi.waitFor(() => expect(picking.getState().markers[0]?.status).toBe("sending"));
+    finish({ delivered: true, id: "server-1", queued: false });
+    await saving;
+
+    expect(picking.getState().markers[0]?.status).toBe("done");
+    picking.dispose();
+  });
+
+  it("TC3 같은 경로로 돌아오면 기존 마커가 다시 보인다", async () => {
+    const path = { current: "/original" };
+    const { picking } = fixture({ path });
+    await annotate(picking, button("첫째"), "주석 1");
+    await annotate(picking, button("둘째"), "주석 2");
+    expect(picking.getState().markers).toHaveLength(2);
+
+    path.current = "/other";
+    await vi.waitFor(() => expect(picking.getState().markers).toHaveLength(0));
+    path.current = "/original";
+    await vi.waitFor(() => expect(picking.getState().markers).toHaveLength(2));
+    picking.dispose();
+  });
+
+  it("TC4 주석에 요소 정보가 함께 담긴다", async () => {
+    const { picking, queue } = fixture();
+    await annotate(picking, button("결제하기"), "버튼 위치", { x: 250, y: 125 });
+
+    const report = queue.submitted[0]!;
+    expect(report.element?.selector).toContain("#button-");
+    expect(report.element?.text).toBe("결제하기");
+    expect(report.element?.boundingBox).toEqual({ x: 10, y: 20, width: 120, height: 36 });
+    expect(report.pin).toEqual({ x: 0.25, y: 0.25 });
+    picking.dispose();
+  });
+
+  it("TC5 소스 경로를 못 얻어도 주석은 정상 저장된다", async () => {
+    const { picking, queue } = fixture();
+    const outcome = await annotate(picking, button("플러그인 없음"), "정상 저장");
+
+    expect(outcome?.delivered).toBe(true);
+    expect(queue.submitted).toHaveLength(1);
+    expect(sourceFromElement(queue.submitted[0]?.element)).toEqual({
+      screenId: null,
+      sourceFile: null,
+      sourceLine: null,
+    });
+    expect(picking.getState().markers[0]?.status).toBe("done");
+    picking.dispose();
+  });
+
+  it("TC6 전송에 실패한 마커는 대기 표시로 남는다", async () => {
+    const queue = new TestQueue();
+    queue.outcome = { delivered: false, id: null, queued: true };
+    const { picking } = fixture({ queue });
+    await annotate(picking, button("오프라인"), "나중에 전송");
+
+    expect(picking.getState().markers).toHaveLength(1);
+    expect(picking.getState().markers[0]?.status).toBe("pending");
+    expect(await queue.size()).toBe(1);
+    picking.dispose();
+  });
+
+  it("다른 경로의 전송 완료를 현재 경로 마커에 잘못 적용하지 않는다", async () => {
+    const queue = new TestQueue();
+    queue.outcome = { delivered: false, id: null, queued: true };
+    const path = { current: "/a" };
+    const { picking } = fixture({ queue, path });
+    await annotate(picking, button("A"), "A 주석");
+    const firstId = queue.submitted[0]!.clientSubmissionId;
+
+    path.current = "/b";
+    picking.syncPath();
+    await annotate(picking, button("B"), "B 주석");
+    queue.settle(firstId, { delivered: true, id: "server-a" }, 1);
+
+    expect(picking.getState().markers[0]?.status).toBe("pending");
+    path.current = "/a";
+    picking.syncPath();
+    expect(picking.getState().markers[0]?.status).toBe("done");
+    picking.dispose();
+  });
+});