@solhun/feedback-kit-web 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { ElementInfo, FeedbackPin, FeedbackScreenshot, FeedbackHint, FeedbackReport, SubmitOutcome, QueueStatus, ReportParts, ScreenshotCapture, ScreenshotReencode, WidgetControllerOpts, HintProvider, WidgetController, FeedbackStorage, ContextProviders } from '@solhun/feedback-kit-core';
+import { ElementInfo, FeedbackPin, FeedbackScreenshot, FeedbackHint, FeedbackReport, SubmitOutcome, QueueStatus, ReportParts, ScreenshotCapture, ScreenshotReencode, RouteWatcher, WidgetControllerOpts, HintProvider, WidgetController, FeedbackStorage, ContextProviders, DiagnosticsInstallOpts, RouteTrailStore } from '@solhun/feedback-kit-core';
 export { COMMENT_MAX_CHARS, COMMENT_REQUIRED_MESSAGE, COMMENT_TOO_LONG_MESSAGE, ElementInfo, ElementLike, FLOATING_BUTTON_ID, FeedbackAdapter, FeedbackConfig, FeedbackContext, FeedbackHint, FeedbackPin, FeedbackReport, FeedbackStorage, FeedbackUser, HintCatalog, HintElementRule, HintPlatform, HintProvider, HintRankInput, HintScope, MODAL_ACTION_HINT_TOGGLE, MODAL_ACTION_PICK, ModalSubmitStatus, ReportModalController, ReportModalState, ResolvedConfig, SCREENSHOT_FAILED_MESSAGE, SOURCE_ATTR, SUBMIT_DONE_MESSAGE, SUBMIT_PENDING_MESSAGE, ScreenshotStatus, SubmitResult, Visibility, VisibilityEnv, VisibilityFn, WidgetController, WidgetPosition, WidgetScreen, WidgetState, denormalizePin, normalizePin, parseSourceAttr, rankHints, resolveConfig, shouldShowWidget, sourceFromElement } from '@solhun/feedback-kit-core';
 import * as react from 'react';
 
@@ -163,6 +163,12 @@ interface ElementPickingOpts {
      * `rankHints` 한 결과를 돌려준다. 없으면(힌트 기능이 꺼져 있으면) 팝업에 칩이 안 뜬다.
      */
     rankHintsFor?: ((element: ElementInfo | null) => readonly FeedbackHint[]) | null;
+    /**
+     * 화면 이동 감시자. 기본은 웹 공용 감시자(`webRouteWatcher`) — **진단의 화면 이동 궤적과
+     * 같은 것**이다. 여기만 따로 구현하면 한쪽이 이동을 놓쳤을 때 원인을 가릴 수 없다.
+     * `null` 을 주면 감시하지 않는다(테스트에서 `syncPath()` 를 직접 부를 때).
+     */
+    watchRoutes?: RouteWatcher | null;
 }
 declare class ElementPickingController {
     private readonly queue;
@@ -186,10 +192,14 @@ declare class ElementPickingController {
      */
     private paused;
     private attached;
+    /** 같은 요소 위 mousemove 마다 React 경로·선택자를 다시 만들지 않기 위한 캐시. */
+    private hoveredTarget;
     private hovered;
     private popup;
     private markers;
-    private pathWatch;
+    private readonly watchRoutes;
+    /** 경로 감시 해제. 감시 중이 아니면 null. */
+    private unwatchRoutes;
     private lastPathname;
     private saving;
     /** 늦게 끝난 캡처가 다음 주석의 그림을 덮지 못하게 하는 세대 번호. */
@@ -203,6 +213,7 @@ declare class ElementPickingController {
     private userToggledHints;
     private readonly onClick;
     private readonly onMouseOver;
+    private readonly onMouseMove;
     constructor(opts: ElementPickingOpts);
     getState(): PickingState;
     get isActive(): boolean;
@@ -228,6 +239,17 @@ declare class ElementPickingController {
      * @returns 되살아났으면 true.
      */
     restore(): boolean;
+    /**
+     * 이 화면에 쌓인 마커 표시를 지운다.
+     *
+     * 지워지는 건 **화면 표시뿐**이다. 제보는 이미 큐를 거쳐 수집처로 갔으므로 없어지지 않는다.
+     * 마커는 `localStorage` 에 남아 새로고침에도 살아남는데(그게 원래 목적이다) 정작 치울
+     * 수단이 없어서, 한 번 보낸 [완료] 배지가 그 화면을 볼 때마다 계속 따라다녔다.
+     *
+     * 화면에 보이는 목록의 기준은 `lastPathname` 이다(`reconcileMarkerOutcomes` 와 같다).
+     * 이동 직후 아직 `syncPath` 가 안 돈 순간에도 "지금 눈에 보이는 것"이 지워져야 한다.
+     */
+    clearMarkers(): void;
     /** 경로가 바뀌었을 때 그 경로의 마커로 갈아 끼운다. */
     syncPath(): readonly StoredMarker[];
     dispose(): void;
@@ -375,5 +397,58 @@ declare function createWebStorage(backing?: SyncStorage): FeedbackStorage;
  * 서버 렌더 단계에서 실행될 수 있기 때문이다.
  */
 declare function webContextProviders(): ContextProviders;
+/**
+ * 웹 진단 수집의 기본 배선.
+ *
+ * `sharedDiagnostics.install(webDiagnosticsOptions({ ... }))` 로 쓴다. 넘긴 값이 기본값을
+ * 덮으므로 감시자·저장소를 직접 갈아 끼울 수도 있다.
+ *
+ * 왜 패키지가 주나: 감시자를 호스트가 깜빡하면 **궤적만 조용히 빈다.** 네트워크·로그는
+ * 그대로 모이니 화면상 아무 문제가 없어 보이고, "이 제보엔 이동이 없었나 보다"로 읽힌다 —
+ * 빠진 것과 없는 것이 구분되지 않는 실패다.
+ *
+ * 진단을 끄면(`captureDiagnostics: false`) install 자체가 안 불리므로 궤적도 같이 꺼진다.
+ * 궤적만 따로 켜고 끄는 스위치는 만들지 않는다.
+ */
+declare function webDiagnosticsOptions(opts?: DiagnosticsInstallOpts): DiagnosticsInstallOpts;
+
+/** 감시자가 들여다보는 전역. 테스트에서는 가짜를 넣는다. */
+interface RouteWatchTarget {
+    location?: {
+        pathname?: string;
+    } | null;
+    history?: {
+        pushState?: (...args: unknown[]) => unknown;
+        replaceState?: (...args: unknown[]) => unknown;
+    } | null;
+    addEventListener?: (type: string, listener: () => void) => void;
+    removeEventListener?: (type: string, listener: () => void) => void;
+}
+/**
+ * 경로 감시자 하나를 만든다.
+ *
+ * 돌려주는 것은 **구독 함수**다. 구독하면 현재 경로를 한 번 흘리고(마운트 시점의 화면이
+ * 궤적의 첫 줄이 된다), 이후 이동마다 새 경로를 흘린다. 해제 함수를 부르면 구독이 끊긴다.
+ *
+ * `history` 패치는 **첫 구독자가 생길 때 걸고 마지막이 나가면 푼다.** 구독자가 없는데 패치가
+ * 남아 있으면, 위젯을 떼어낸 뒤에도 호스트의 모든 화면 이동이 우리 코드를 거친다.
+ */
+declare function createRouteWatcher(target?: RouteWatchTarget | null): RouteWatcher;
+/**
+ * 웹 기본 감시자. **모듈 스코프에 하나**라서 궤적과 지목이 같은 인스턴스를 물려 쓴다.
+ * 각자 `createRouteWatcher()` 를 부르면 `history` 가 두 겹으로 패치돼, 해제 순서가 엇갈릴 때
+ * 원본이 복구되지 않는다.
+ */
+declare const webRouteWatcher: RouteWatcher;
+/**
+ * 궤적을 남길 탭 단위 저장소(`sessionStorage`).
+ *
+ * `localStorage` 가 아닌 이유: 궤적은 **이 탭에서 지금 지나온 길**이다. 탭을 나눠 쓰면
+ * 다른 탭의 이동이 섞여 재현 절차가 거짓이 된다.
+ *
+ * 프라이빗 모드·차단 설정에서는 접근 자체가 던진다. 그때는 `null` 을 돌려주고 궤적은
+ * 메모리로 떨어진다 — 저장을 못 한다고 제보를 막지 않는다.
+ */
+declare function webRouteStorage(): RouteTrailStore | null;
 
-export { type AnnotationPopupState, ELEMENT_TEXT_MAX_CHARS, ElementPickingController, type ElementPickingOpts, FeedbackKit, type FeedbackKitProps, MARKER_KEY_PREFIX, MAX_MARKERS_PER_PATH, type MarkerStatus, MarkerStore, OWN_UI_ATTR, PICKING_MODE_KEY, type PickingListener, type PickingQueueLike, type PickingState, SELECTOR_MAX_DEPTH, type StorageLike, type StoredMarker, type WebWidget, type WebWidgetOpts, captureWebScreenshot, createWebStorage, createWebWidget, cssSelectorPath, describeElement, isOwnUi, reactComponentPath, reactComponentSummary, reencodeWebScreenshot, visibleText, webContextProviders };
+export { type AnnotationPopupState, ELEMENT_TEXT_MAX_CHARS, ElementPickingController, type ElementPickingOpts, FeedbackKit, type FeedbackKitProps, MARKER_KEY_PREFIX, MAX_MARKERS_PER_PATH, type MarkerStatus, MarkerStore, OWN_UI_ATTR, PICKING_MODE_KEY, type PickingListener, type PickingQueueLike, type PickingState, type RouteWatchTarget, SELECTOR_MAX_DEPTH, type StorageLike, type StoredMarker, type WebWidget, type WebWidgetOpts, captureWebScreenshot, createRouteWatcher, createWebStorage, createWebWidget, cssSelectorPath, describeElement, isOwnUi, reactComponentPath, reactComponentSummary, reencodeWebScreenshot, visibleText, webContextProviders, webDiagnosticsOptions, webRouteStorage, webRouteWatcher };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ElementInfo, FeedbackPin, FeedbackScreenshot, FeedbackHint, FeedbackReport, SubmitOutcome, QueueStatus, ReportParts, ScreenshotCapture, ScreenshotReencode, WidgetControllerOpts, HintProvider, WidgetController, FeedbackStorage, ContextProviders } from '@solhun/feedback-kit-core';
+import { ElementInfo, FeedbackPin, FeedbackScreenshot, FeedbackHint, FeedbackReport, SubmitOutcome, QueueStatus, ReportParts, ScreenshotCapture, ScreenshotReencode, RouteWatcher, WidgetControllerOpts, HintProvider, WidgetController, FeedbackStorage, ContextProviders, DiagnosticsInstallOpts, RouteTrailStore } from '@solhun/feedback-kit-core';
 export { COMMENT_MAX_CHARS, COMMENT_REQUIRED_MESSAGE, COMMENT_TOO_LONG_MESSAGE, ElementInfo, ElementLike, FLOATING_BUTTON_ID, FeedbackAdapter, FeedbackConfig, FeedbackContext, FeedbackHint, FeedbackPin, FeedbackReport, FeedbackStorage, FeedbackUser, HintCatalog, HintElementRule, HintPlatform, HintProvider, HintRankInput, HintScope, MODAL_ACTION_HINT_TOGGLE, MODAL_ACTION_PICK, ModalSubmitStatus, ReportModalController, ReportModalState, ResolvedConfig, SCREENSHOT_FAILED_MESSAGE, SOURCE_ATTR, SUBMIT_DONE_MESSAGE, SUBMIT_PENDING_MESSAGE, ScreenshotStatus, SubmitResult, Visibility, VisibilityEnv, VisibilityFn, WidgetController, WidgetPosition, WidgetScreen, WidgetState, denormalizePin, normalizePin, parseSourceAttr, rankHints, resolveConfig, shouldShowWidget, sourceFromElement } from '@solhun/feedback-kit-core';
 import * as react from 'react';
 
@@ -163,6 +163,12 @@ interface ElementPickingOpts {
      * `rankHints` 한 결과를 돌려준다. 없으면(힌트 기능이 꺼져 있으면) 팝업에 칩이 안 뜬다.
      */
     rankHintsFor?: ((element: ElementInfo | null) => readonly FeedbackHint[]) | null;
+    /**
+     * 화면 이동 감시자. 기본은 웹 공용 감시자(`webRouteWatcher`) — **진단의 화면 이동 궤적과
+     * 같은 것**이다. 여기만 따로 구현하면 한쪽이 이동을 놓쳤을 때 원인을 가릴 수 없다.
+     * `null` 을 주면 감시하지 않는다(테스트에서 `syncPath()` 를 직접 부를 때).
+     */
+    watchRoutes?: RouteWatcher | null;
 }
 declare class ElementPickingController {
     private readonly queue;
@@ -186,10 +192,14 @@ declare class ElementPickingController {
      */
     private paused;
     private attached;
+    /** 같은 요소 위 mousemove 마다 React 경로·선택자를 다시 만들지 않기 위한 캐시. */
+    private hoveredTarget;
     private hovered;
     private popup;
     private markers;
-    private pathWatch;
+    private readonly watchRoutes;
+    /** 경로 감시 해제. 감시 중이 아니면 null. */
+    private unwatchRoutes;
     private lastPathname;
     private saving;
     /** 늦게 끝난 캡처가 다음 주석의 그림을 덮지 못하게 하는 세대 번호. */
@@ -203,6 +213,7 @@ declare class ElementPickingController {
     private userToggledHints;
     private readonly onClick;
     private readonly onMouseOver;
+    private readonly onMouseMove;
     constructor(opts: ElementPickingOpts);
     getState(): PickingState;
     get isActive(): boolean;
@@ -228,6 +239,17 @@ declare class ElementPickingController {
      * @returns 되살아났으면 true.
      */
     restore(): boolean;
+    /**
+     * 이 화면에 쌓인 마커 표시를 지운다.
+     *
+     * 지워지는 건 **화면 표시뿐**이다. 제보는 이미 큐를 거쳐 수집처로 갔으므로 없어지지 않는다.
+     * 마커는 `localStorage` 에 남아 새로고침에도 살아남는데(그게 원래 목적이다) 정작 치울
+     * 수단이 없어서, 한 번 보낸 [완료] 배지가 그 화면을 볼 때마다 계속 따라다녔다.
+     *
+     * 화면에 보이는 목록의 기준은 `lastPathname` 이다(`reconcileMarkerOutcomes` 와 같다).
+     * 이동 직후 아직 `syncPath` 가 안 돈 순간에도 "지금 눈에 보이는 것"이 지워져야 한다.
+     */
+    clearMarkers(): void;
     /** 경로가 바뀌었을 때 그 경로의 마커로 갈아 끼운다. */
     syncPath(): readonly StoredMarker[];
     dispose(): void;
@@ -375,5 +397,58 @@ declare function createWebStorage(backing?: SyncStorage): FeedbackStorage;
  * 서버 렌더 단계에서 실행될 수 있기 때문이다.
  */
 declare function webContextProviders(): ContextProviders;
+/**
+ * 웹 진단 수집의 기본 배선.
+ *
+ * `sharedDiagnostics.install(webDiagnosticsOptions({ ... }))` 로 쓴다. 넘긴 값이 기본값을
+ * 덮으므로 감시자·저장소를 직접 갈아 끼울 수도 있다.
+ *
+ * 왜 패키지가 주나: 감시자를 호스트가 깜빡하면 **궤적만 조용히 빈다.** 네트워크·로그는
+ * 그대로 모이니 화면상 아무 문제가 없어 보이고, "이 제보엔 이동이 없었나 보다"로 읽힌다 —
+ * 빠진 것과 없는 것이 구분되지 않는 실패다.
+ *
+ * 진단을 끄면(`captureDiagnostics: false`) install 자체가 안 불리므로 궤적도 같이 꺼진다.
+ * 궤적만 따로 켜고 끄는 스위치는 만들지 않는다.
+ */
+declare function webDiagnosticsOptions(opts?: DiagnosticsInstallOpts): DiagnosticsInstallOpts;
+
+/** 감시자가 들여다보는 전역. 테스트에서는 가짜를 넣는다. */
+interface RouteWatchTarget {
+    location?: {
+        pathname?: string;
+    } | null;
+    history?: {
+        pushState?: (...args: unknown[]) => unknown;
+        replaceState?: (...args: unknown[]) => unknown;
+    } | null;
+    addEventListener?: (type: string, listener: () => void) => void;
+    removeEventListener?: (type: string, listener: () => void) => void;
+}
+/**
+ * 경로 감시자 하나를 만든다.
+ *
+ * 돌려주는 것은 **구독 함수**다. 구독하면 현재 경로를 한 번 흘리고(마운트 시점의 화면이
+ * 궤적의 첫 줄이 된다), 이후 이동마다 새 경로를 흘린다. 해제 함수를 부르면 구독이 끊긴다.
+ *
+ * `history` 패치는 **첫 구독자가 생길 때 걸고 마지막이 나가면 푼다.** 구독자가 없는데 패치가
+ * 남아 있으면, 위젯을 떼어낸 뒤에도 호스트의 모든 화면 이동이 우리 코드를 거친다.
+ */
+declare function createRouteWatcher(target?: RouteWatchTarget | null): RouteWatcher;
+/**
+ * 웹 기본 감시자. **모듈 스코프에 하나**라서 궤적과 지목이 같은 인스턴스를 물려 쓴다.
+ * 각자 `createRouteWatcher()` 를 부르면 `history` 가 두 겹으로 패치돼, 해제 순서가 엇갈릴 때
+ * 원본이 복구되지 않는다.
+ */
+declare const webRouteWatcher: RouteWatcher;
+/**
+ * 궤적을 남길 탭 단위 저장소(`sessionStorage`).
+ *
+ * `localStorage` 가 아닌 이유: 궤적은 **이 탭에서 지금 지나온 길**이다. 탭을 나눠 쓰면
+ * 다른 탭의 이동이 섞여 재현 절차가 거짓이 된다.
+ *
+ * 프라이빗 모드·차단 설정에서는 접근 자체가 던진다. 그때는 `null` 을 돌려주고 궤적은
+ * 메모리로 떨어진다 — 저장을 못 한다고 제보를 막지 않는다.
+ */
+declare function webRouteStorage(): RouteTrailStore | null;
 
-export { type AnnotationPopupState, ELEMENT_TEXT_MAX_CHARS, ElementPickingController, type ElementPickingOpts, FeedbackKit, type FeedbackKitProps, MARKER_KEY_PREFIX, MAX_MARKERS_PER_PATH, type MarkerStatus, MarkerStore, OWN_UI_ATTR, PICKING_MODE_KEY, type PickingListener, type PickingQueueLike, type PickingState, SELECTOR_MAX_DEPTH, type StorageLike, type StoredMarker, type WebWidget, type WebWidgetOpts, captureWebScreenshot, createWebStorage, createWebWidget, cssSelectorPath, describeElement, isOwnUi, reactComponentPath, reactComponentSummary, reencodeWebScreenshot, visibleText, webContextProviders };
+export { type AnnotationPopupState, ELEMENT_TEXT_MAX_CHARS, ElementPickingController, type ElementPickingOpts, FeedbackKit, type FeedbackKitProps, MARKER_KEY_PREFIX, MAX_MARKERS_PER_PATH, type MarkerStatus, MarkerStore, OWN_UI_ATTR, PICKING_MODE_KEY, type PickingListener, type PickingQueueLike, type PickingState, type RouteWatchTarget, SELECTOR_MAX_DEPTH, type StorageLike, type StoredMarker, type WebWidget, type WebWidgetOpts, captureWebScreenshot, createRouteWatcher, createWebStorage, createWebWidget, cssSelectorPath, describeElement, isOwnUi, reactComponentPath, reactComponentSummary, reencodeWebScreenshot, visibleText, webContextProviders, webDiagnosticsOptions, webRouteStorage, webRouteWatcher };

package/dist/index.js

@@ -103,6 +103,7 @@ function reactComponentSummary(node) {
 // src/element-info.ts
 var ELEMENT_TEXT_MAX_CHARS = 200;
 var SELECTOR_MAX_DEPTH = 8;
+var PICK_TARGET_SNAP_PX = 24;
 var KEPT_ATTRS = [
   "id",
   "class",
@@ -175,6 +176,55 @@ function visibleText(el) {
   if (collapsed === "") return null;
   return collapsed.length > ELEMENT_TEXT_MAX_CHARS ? collapsed.slice(0, ELEMENT_TEXT_MAX_CHARS) : collapsed;
 }
+function elementRect(element) {
+  try {
+    const rect = element.getBoundingClientRect();
+    const left = rect.left;
+    const top = rect.top;
+    const width = rect.width;
+    const height = rect.height;
+    if (![left, top, width, height].every(Number.isFinite) || width <= 0 || height <= 0) {
+      return null;
+    }
+    return {
+      element,
+      left,
+      top,
+      right: left + width,
+      bottom: top + height,
+      width,
+      height
+    };
+  } catch {
+    return null;
+  }
+}
+function distanceFromPoint(rect, point) {
+  const dx = Math.max(rect.left - point.x, 0, point.x - rect.right);
+  const dy = Math.max(rect.top - point.y, 0, point.y - rect.bottom);
+  return Math.hypot(dx, dy);
+}
+function resolvePickTarget(target, point) {
+  if (!target || typeof target.tagName !== "string") return null;
+  if (!Number.isFinite(point.x) || !Number.isFinite(point.y)) return target;
+  let current = target;
+  while (true) {
+    const currentRect = elementRect(current);
+    const children = Array.from(current.children).map(elementRect).filter((rect) => rect !== null).map((rect) => ({ rect, distance: distanceFromPoint(rect, point) }));
+    if (children.length === 0) return current;
+    const containing = children.filter(({ distance }) => distance === 0).sort((a, b) => a.rect.width * a.rect.height - b.rect.width * b.rect.height);
+    if (containing[0]) {
+      current = containing[0].rect.element;
+      continue;
+    }
+    const nearest = children.sort((a, b) => a.distance - b.distance)[0];
+    const isMorePrecise = currentRect ? nearest.rect.width * nearest.rect.height < currentRect.width * currentRect.height : true;
+    if (nearest.distance <= PICK_TARGET_SNAP_PX && isMorePrecise) {
+      return nearest.rect.element;
+    }
+    return current;
+  }
+}
 function describeElement(el) {
   if (!el || typeof el.tagName !== "string") return null;
   const attributes = {};
@@ -299,6 +349,84 @@ import {
   captureWithinLimit,
   normalizePin
 } from "@solhun/feedback-kit-core";
+
+// src/route-watcher.ts
+function defaultTarget() {
+  const g = globalThis;
+  return g.location ? g : null;
+}
+function createRouteWatcher(target = defaultTarget()) {
+  const listeners = /* @__PURE__ */ new Set();
+  let detach = null;
+  const currentPath = () => {
+    const p = target?.location?.pathname;
+    return typeof p === "string" && p.length > 0 ? p : "/";
+  };
+  const emit = () => {
+    const path = currentPath();
+    for (const listener of [...listeners]) {
+      try {
+        listener(path);
+      } catch {
+      }
+    }
+  };
+  const attach = () => {
+    if (detach !== null || !target) return;
+    const onPop = () => emit();
+    target.addEventListener?.("popstate", onPop);
+    const history = target.history;
+    const originalPush = typeof history?.pushState === "function" ? history.pushState : null;
+    const originalReplace = typeof history?.replaceState === "function" ? history.replaceState : null;
+    if (history && originalPush) {
+      history.pushState = function patched(...args) {
+        const out = originalPush.apply(this, args);
+        emit();
+        return out;
+      };
+    }
+    if (history && originalReplace) {
+      history.replaceState = function patched(...args) {
+        const out = originalReplace.apply(this, args);
+        emit();
+        return out;
+      };
+    }
+    detach = () => {
+      target.removeEventListener?.("popstate", onPop);
+      if (history && originalPush) history.pushState = originalPush;
+      if (history && originalReplace) history.replaceState = originalReplace;
+    };
+  };
+  return (onPath) => {
+    listeners.add(onPath);
+    if (listeners.size === 1) attach();
+    try {
+      onPath(currentPath());
+    } catch {
+    }
+    return () => {
+      listeners.delete(onPath);
+      if (listeners.size === 0 && detach) {
+        detach();
+        detach = null;
+      }
+    };
+  };
+}
+var webRouteWatcher = createRouteWatcher();
+function webRouteStorage() {
+  try {
+    const s = globalThis.sessionStorage;
+    if (!s || typeof s.getItem !== "function" || typeof s.setItem !== "function") return null;
+    s.getItem("feedback-kit:probe");
+    return s;
+  } catch {
+    return null;
+  }
+}
+
+// src/picking.ts
 var OWN_UI_ATTR = "data-feedback-kit";
 function defaultDocument() {
   return globalThis.document ?? null;
@@ -327,10 +455,13 @@ var ElementPickingController = class {
      */
     this.paused = false;
     this.attached = false;
+    /** 같은 요소 위 mousemove 마다 React 경로·선택자를 다시 만들지 않기 위한 캐시. */
+    this.hoveredTarget = null;
     this.hovered = null;
     this.popup = null;
     this.markers = [];
-    this.pathWatch = null;
+    /** 경로 감시 해제. 감시 중이 아니면 null. */
+    this.unwatchRoutes = null;
     this.saving = false;
     /** 늦게 끝난 캡처가 다음 주석의 그림을 덮지 못하게 하는 세대 번호. */
     this.shotGeneration = 0;
@@ -343,6 +474,7 @@ var ElementPickingController = class {
     this.userToggledHints = false;
     this.onClick = (event) => this.handleClick(event);
     this.onMouseOver = (event) => this.handleMouseOver(event);
+    this.onMouseMove = (event) => this.handleMouseOver(event);
     this.queue = opts.queue;
     this.createReport = opts.createReport;
     this.store = opts.store ?? new MarkerStore();
@@ -354,6 +486,7 @@ var ElementPickingController = class {
     this.reencode = opts.reencode ?? null;
     this.screenshotLimitBytes = opts.screenshotLimitBytes;
     this.rankHintsFor = opts.rankHintsFor ?? null;
+    this.watchRoutes = opts.watchRoutes === void 0 ? webRouteWatcher : opts.watchRoutes;
     this.lastPathname = this.getPathname();
     this.markers = this.store.list(this.lastPathname);
     this.unsubscribeQueue = this.queue.subscribe?.(() => {
@@ -402,6 +535,7 @@ var ElementPickingController = class {
     this.store.setPickingActive(false);
     this.detach();
     this.stopPathWatch();
+    this.hoveredTarget = null;
     this.hovered = null;
     this.popup = null;
     this.emit();
@@ -417,6 +551,7 @@ var ElementPickingController = class {
     if (!this.active || this.paused) return;
     this.paused = true;
     this.detach();
+    this.hoveredTarget = null;
     this.hovered = null;
     this.emit();
   }
@@ -444,6 +579,22 @@ var ElementPickingController = class {
     this.start();
     return true;
   }
+  /**
+   * 이 화면에 쌓인 마커 표시를 지운다.
+   *
+   * 지워지는 건 **화면 표시뿐**이다. 제보는 이미 큐를 거쳐 수집처로 갔으므로 없어지지 않는다.
+   * 마커는 `localStorage` 에 남아 새로고침에도 살아남는데(그게 원래 목적이다) 정작 치울
+   * 수단이 없어서, 한 번 보낸 [완료] 배지가 그 화면을 볼 때마다 계속 따라다녔다.
+   *
+   * 화면에 보이는 목록의 기준은 `lastPathname` 이다(`reconcileMarkerOutcomes` 와 같다).
+   * 이동 직후 아직 `syncPath` 가 안 돈 순간에도 "지금 눈에 보이는 것"이 지워져야 한다.
+   */
+  clearMarkers() {
+    if (this.markers.length === 0) return;
+    this.store.clear(this.lastPathname);
+    this.markers = [];
+    this.emit();
+  }
   /** 경로가 바뀌었을 때 그 경로의 마커로 갈아 끼운다. */
   syncPath() {
     if (this.paused) this.resume();
@@ -451,6 +602,7 @@ var ElementPickingController = class {
     this.markers = this.store.list(this.lastPathname);
     this.reconcileMarkerOutcomes();
     this.popup = null;
+    this.hoveredTarget = null;
     this.hovered = null;
     this.emit();
     return this.markers;
@@ -466,17 +618,26 @@ var ElementPickingController = class {
     if (this.attached || !this.doc) return;
     this.doc.addEventListener("click", this.onClick, true);
     this.doc.addEventListener("mouseover", this.onMouseOver, true);
+    this.doc.addEventListener("mousemove", this.onMouseMove, true);
     this.attached = true;
   }
   detach() {
     if (!this.attached || !this.doc) return;
     this.doc.removeEventListener("click", this.onClick, true);
     this.doc.removeEventListener("mouseover", this.onMouseOver, true);
+    this.doc.removeEventListener("mousemove", this.onMouseMove, true);
     this.attached = false;
   }
   handleMouseOver(event) {
     if (!this.active || this.paused || isOwnUi(event.target)) return;
-    this.hovered = describeElement(event.target);
+    const mouse = event;
+    const target = resolvePickTarget(event.target, {
+      x: mouse.clientX ?? 0,
+      y: mouse.clientY ?? 0
+    });
+    if (target === this.hoveredTarget) return;
+    this.hoveredTarget = target;
+    this.hovered = describeElement(target);
     this.emit();
   }
   handleClick(event) {
@@ -497,11 +658,12 @@ var ElementPickingController = class {
   /** 클릭 지점 기준으로 주석 팝업을 연다. 좌표는 해상도 무관한 상대값으로 접어 둔다. */
   openAnnotation(element, clientPoint) {
     const point = normalizePin(clientPoint, this.getViewport());
+    const target = resolvePickTarget(element, clientPoint);
     if (this.onPick) {
-      this.onPick(describeElement(element), point);
+      this.onPick(describeElement(target), point);
       return;
     }
-    const info = describeElement(element);
+    const info = describeElement(target);
     this.userToggledHints = false;
     const hints = this.rankHintsFor ? this.rankHintsFor(info) : [];
     this.popup = {
@@ -716,17 +878,17 @@ ${hint.draft}`;
     return outcome;
   }
   startPathWatch() {
-    if (this.pathWatch !== null || typeof setInterval !== "function") return;
+    if (this.unwatchRoutes !== null || !this.watchRoutes) return;
     this.lastPathname = this.getPathname();
-    this.pathWatch = setInterval(() => {
+    this.unwatchRoutes = this.watchRoutes(() => {
       const pathname = this.getPathname();
       if (pathname !== this.lastPathname) this.syncPath();
-    }, 200);
+    });
   }
   stopPathWatch() {
-    if (this.pathWatch === null) return;
-    clearInterval(this.pathWatch);
-    this.pathWatch = null;
+    if (this.unwatchRoutes === null) return;
+    this.unwatchRoutes();
+    this.unwatchRoutes = null;
   }
   /** 전역 pending 수가 아니라 마커와 같은 clientSubmissionId의 확정 성공만 완료로 바꾼다. */
   reconcileMarkerOutcomes() {
@@ -1012,7 +1174,7 @@ import {
 } from "react";
 
 // src/version.ts
-var VERSION = true ? "0.7.0" : "dev";
+var VERSION = true ? "0.8.0" : "dev";
 
 // src/feedback-kit.tsx
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
@@ -1278,8 +1440,10 @@ function PickToggle({
 }
 function PickBar({
   paused,
+  markerCount,
   onToggle,
-  onTogglePause
+  onTogglePause,
+  onClearMarkers
 }) {
   return /* @__PURE__ */ jsxs(
     "div",
@@ -1287,10 +1451,20 @@ function PickBar({
       style: {
         position: "fixed",
         top: 16,
-        left: "50%",
-        transform: "translateX(-50%)",
+        // `left:50% + translateX(-50%)` 로 가운데를 잡으면 **쓸 수 있는 폭이 화면의 절반**이
+        // 된다(transform 은 레이아웃 계산에 안 들어간다). 버튼이 셋이 되면서 그 절반에
+        // 안 맞아 좁은 화면에서 버튼이 한 줄에 하나씩 세로로 쌓였다(390px 에서 3줄).
+        // 양끝을 물리고 auto 마진으로 가운데를 잡으면 화면 전체 폭을 쓴다 — 같은 화면이 2줄.
+        left: 0,
+        right: 0,
+        marginInline: "auto",
+        width: "fit-content",
+        maxWidth: "calc(100% - 32px)",
         display: "flex",
         alignItems: "stretch",
+        justifyContent: "center",
+        // 셋이 한 줄에 안 들어가는 폭에서는 줄을 바꾼다 — 안 그러면 화면 밖으로 나간다.
+        flexWrap: "wrap",
         gap: 8,
         // 오버레이 자체는 클릭을 통과시킨다(pointerEvents:none) — 이 막대만 되살린다.
         pointerEvents: "auto",
@@ -1323,7 +1497,30 @@ function PickBar({
               paused ? "\uC9C0\uBAA9 \uC7AC\uAC1C" : "\uC7A0\uC2DC \uBA48\uCDA4"
             ]
           }
-        )
+        ),
+        markerCount > 0 ? /* @__PURE__ */ jsxs(
+          "button",
+          {
+            type: "button",
+            "data-fk-pick-clear": markerCount,
+            title: "\uD654\uBA74\uC758 \uD45C\uC2DC\uB9CC \uC9C0\uC6C1\uB2C8\uB2E4. \uBCF4\uB0B8 \uC81C\uBCF4\uB294 \uADF8\uB300\uB85C \uB0A8\uC2B5\uB2C8\uB2E4.",
+            "aria-label": `\uC774 \uD654\uBA74\uC758 \uC8FC\uC11D \uD45C\uC2DC ${markerCount}\uAC1C \uC9C0\uC6B0\uAE30 (\uBCF4\uB0B8 \uC81C\uBCF4\uB294 \uADF8\uB300\uB85C \uB0A8\uC2B5\uB2C8\uB2E4)`,
+            onClick: onClearMarkers,
+            style: {
+              ...baseButton,
+              display: "inline-flex",
+              alignItems: "center",
+              gap: 6,
+              whiteSpace: "nowrap",
+              color: TOKENS.muted
+            },
+            children: [
+              /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\u2715" }),
+              "\uD45C\uC2DC \uC9C0\uC6B0\uAE30 ",
+              markerCount
+            ]
+          }
+        ) : null
       ]
     }
   );
@@ -1988,8 +2185,10 @@ function FeedbackKit(props) {
                 PickBar,
                 {
                   paused: pickingState.paused,
+                  markerCount: pickingState.markers.length,
                   onToggle: togglePicking,
-                  onTogglePause: () => activeKit.picking.togglePause()
+                  onTogglePause: () => activeKit.picking.togglePause(),
+                  onClearMarkers: () => activeKit.picking.clearMarkers()
                 }
               ),
               pickingState.markers.map((marker, index) => /* @__PURE__ */ jsx(
@@ -2215,6 +2414,13 @@ function webContextProviders() {
     }
   };
 }
+function webDiagnosticsOptions(opts = {}) {
+  return {
+    watchRoutes: webRouteWatcher,
+    routeStorage: webRouteStorage(),
+    ...opts
+  };
+}
 export {
   COMMENT_MAX_CHARS3 as COMMENT_MAX_CHARS,
   COMMENT_REQUIRED_MESSAGE,
@@ -2239,6 +2445,7 @@ export {
   SUBMIT_PENDING_MESSAGE,
   WidgetController2 as WidgetController,
   captureWebScreenshot,
+  createRouteWatcher,
   createWebStorage,
   createWebWidget,
   cssSelectorPath,
@@ -2255,6 +2462,9 @@ export {
   shouldShowWidget,
   sourceFromElement,
   visibleText,
-  webContextProviders
+  webContextProviders,
+  webDiagnosticsOptions,
+  webRouteStorage,
+  webRouteWatcher
 };
 //# sourceMappingURL=index.js.map