@solhun/feedback-kit-web 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { ElementInfo, FeedbackPin, FeedbackScreenshot, FeedbackReport, SubmitOutcome, QueueStatus, ReportParts, ScreenshotCapture, ScreenshotReencode, WidgetControllerOpts, WidgetController, FeedbackStorage, ContextProviders } from '@solhun/feedback-kit-core';
-export { COMMENT_MAX_CHARS, COMMENT_REQUIRED_MESSAGE, COMMENT_TOO_LONG_MESSAGE, ElementInfo, FLOATING_BUTTON_ID, FeedbackAdapter, FeedbackConfig, FeedbackContext, FeedbackPin, FeedbackReport, FeedbackStorage, FeedbackUser, 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, resolveConfig, shouldShowWidget, sourceFromElement } from '@solhun/feedback-kit-core';
+import { ElementInfo, FeedbackPin, FeedbackScreenshot, FeedbackHint, FeedbackReport, SubmitOutcome, QueueStatus, ReportParts, ScreenshotCapture, ScreenshotReencode, WidgetControllerOpts, HintProvider, WidgetController, FeedbackStorage, ContextProviders } 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';
 
 /** 요소 텍스트를 담을 때의 상한. 본문 전체가 실려 페이로드가 붓는 걸 막는다. */
@@ -96,6 +96,16 @@ interface AnnotationPopupState {
     screenshotStatus: AnnotationShotStatus;
     /** 저장 중인가. 두 번 눌러 같은 주석이 두 번 가는 것을 막는다. */
     saving: boolean;
+    /**
+     * 자주 나오는 제보 제안 칩. 리포트 모달과 같은 계약(같은 `rankHints` 결과, 같은 접힘 규칙,
+     * 같은 `hintIds` 흐름)이다 — "들어온 문이 달라도 담기는 정보는 같다"가 이 위젯의 약속이고,
+     * 제안 칩도 예외가 아니다. `widget.ts` 가 만든 `HintProvider` 를 그대로 물려 쓴다
+     * (팝업이 자기 카탈로그를 따로 들고 있지 않는다).
+     */
+    hints: readonly FeedbackHint[];
+    hintsExpanded: boolean;
+    hintsAvailable: boolean;
+    usedHintIds: readonly string[];
 }
 interface PickingState {
     active: boolean;
@@ -136,6 +146,11 @@ interface ElementPickingOpts {
      * 요소 하나 고를 때마다 모드가 꺼지면 매번 다시 켜야 한다.
      */
     onPick?: (element: ElementInfo | null, point: FeedbackPin) => void;
+    /**
+     * 힌트 랭킹 계산. `widget.ts` 가 만든 `HintProvider` 의 카탈로그를 그 시점의 경로·요소로
+     * `rankHints` 한 결과를 돌려준다. 없으면(힌트 기능이 꺼져 있으면) 팝업에 칩이 안 뜬다.
+     */
+    rankHintsFor?: ((element: ElementInfo | null) => readonly FeedbackHint[]) | null;
 }
 declare class ElementPickingController {
     private readonly queue;
@@ -149,6 +164,7 @@ declare class ElementPickingController {
     private readonly reencode;
     private readonly screenshotLimitBytes;
     private readonly unsubscribeQueue;
+    private readonly rankHintsFor;
     private readonly listeners;
     private active;
     private attached;
@@ -162,6 +178,11 @@ declare class ElementPickingController {
     private shotGeneration;
     /** 지금 도는 자동 캡처. Enter 가 캡처보다 빨랐을 때 기다릴 대상. */
     private capturing;
+    /**
+     * 사용자가 [제안 ▾] 를 직접 건드렸는가. 한 번이라도 건드리면 이후 타이핑에 의한 자동
+     * 접힘/펼침이 멈춘다 — 모달의 `userToggledHints` 와 같은 규칙. 팝업을 새로 열 때마다 리셋된다.
+     */
+    private userToggledHints;
     private readonly onClick;
     private readonly onMouseOver;
     constructor(opts: ElementPickingOpts);
@@ -189,6 +210,18 @@ declare class ElementPickingController {
         y: number;
     }): void;
     setAnnotationComment(value: string): void;
+    /**
+     * 코멘트가 비었는지에 따라 칩 줄 상태를 갱신하는 조각. `setAnnotationComment`·`applyHint`
+     * 양쪽에서 쓴다 — 모달의 `hintsPatchFor` 와 같은 규칙이다.
+     */
+    private hintsPatchFor;
+    /**
+     * 칩 누름. 이미 눌린 칩이면 아무 일도 하지 않는다. 코멘트가 비어 있으면 초안으로 치환,
+     * 아니면 줄바꿈 뒤 이어붙인다 — 모달의 `applyHint` 와 동일한 규칙이다.
+     */
+    applyHint(hintId: string): void;
+    /** [제안 ▾] 토글. 방향과 무관하게 이후 자동 접힘/펼침을 멈춘다. */
+    toggleHints(): void;
     /**
      * 사용자가 붙여넣기(Cmd+V)나 드래그로 넣은 그림. 자동 캡처 결과를 덮는다.
      *
@@ -268,6 +301,13 @@ interface WebWidgetOpts extends Omit<WidgetControllerOpts, "platform" | "initial
     };
     /** 요소를 고른 뒤 띄울 UI. 기본은 `popup`. */
     pickTarget?: PickTarget;
+    /**
+     * 정적 힌트 목록(설정으로 직접 넘김). 주면 서버에서 받아오지 않는다 — 도입 초기·오프라인
+     * 데모·테스트용이다. 서버 목록과 합치지 않는다(둘을 섞으면 무엇이 보이는지 설명이 안 된다).
+     */
+    hints?: readonly FeedbackHint[];
+    /** 힌트 조회 컨트롤러 주입(테스트용). 주면 큐 어댑터의 fetchHints 를 보지 않는다. */
+    hintProvider?: HintProvider;
 }
 interface WebWidget {
     widget: WidgetController;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { ElementInfo, FeedbackPin, FeedbackScreenshot, FeedbackReport, SubmitOutcome, QueueStatus, ReportParts, ScreenshotCapture, ScreenshotReencode, WidgetControllerOpts, WidgetController, FeedbackStorage, ContextProviders } from '@solhun/feedback-kit-core';
-export { COMMENT_MAX_CHARS, COMMENT_REQUIRED_MESSAGE, COMMENT_TOO_LONG_MESSAGE, ElementInfo, FLOATING_BUTTON_ID, FeedbackAdapter, FeedbackConfig, FeedbackContext, FeedbackPin, FeedbackReport, FeedbackStorage, FeedbackUser, 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, resolveConfig, shouldShowWidget, sourceFromElement } from '@solhun/feedback-kit-core';
+import { ElementInfo, FeedbackPin, FeedbackScreenshot, FeedbackHint, FeedbackReport, SubmitOutcome, QueueStatus, ReportParts, ScreenshotCapture, ScreenshotReencode, WidgetControllerOpts, HintProvider, WidgetController, FeedbackStorage, ContextProviders } 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';
 
 /** 요소 텍스트를 담을 때의 상한. 본문 전체가 실려 페이로드가 붓는 걸 막는다. */
@@ -96,6 +96,16 @@ interface AnnotationPopupState {
     screenshotStatus: AnnotationShotStatus;
     /** 저장 중인가. 두 번 눌러 같은 주석이 두 번 가는 것을 막는다. */
     saving: boolean;
+    /**
+     * 자주 나오는 제보 제안 칩. 리포트 모달과 같은 계약(같은 `rankHints` 결과, 같은 접힘 규칙,
+     * 같은 `hintIds` 흐름)이다 — "들어온 문이 달라도 담기는 정보는 같다"가 이 위젯의 약속이고,
+     * 제안 칩도 예외가 아니다. `widget.ts` 가 만든 `HintProvider` 를 그대로 물려 쓴다
+     * (팝업이 자기 카탈로그를 따로 들고 있지 않는다).
+     */
+    hints: readonly FeedbackHint[];
+    hintsExpanded: boolean;
+    hintsAvailable: boolean;
+    usedHintIds: readonly string[];
 }
 interface PickingState {
     active: boolean;
@@ -136,6 +146,11 @@ interface ElementPickingOpts {
      * 요소 하나 고를 때마다 모드가 꺼지면 매번 다시 켜야 한다.
      */
     onPick?: (element: ElementInfo | null, point: FeedbackPin) => void;
+    /**
+     * 힌트 랭킹 계산. `widget.ts` 가 만든 `HintProvider` 의 카탈로그를 그 시점의 경로·요소로
+     * `rankHints` 한 결과를 돌려준다. 없으면(힌트 기능이 꺼져 있으면) 팝업에 칩이 안 뜬다.
+     */
+    rankHintsFor?: ((element: ElementInfo | null) => readonly FeedbackHint[]) | null;
 }
 declare class ElementPickingController {
     private readonly queue;
@@ -149,6 +164,7 @@ declare class ElementPickingController {
     private readonly reencode;
     private readonly screenshotLimitBytes;
     private readonly unsubscribeQueue;
+    private readonly rankHintsFor;
     private readonly listeners;
     private active;
     private attached;
@@ -162,6 +178,11 @@ declare class ElementPickingController {
     private shotGeneration;
     /** 지금 도는 자동 캡처. Enter 가 캡처보다 빨랐을 때 기다릴 대상. */
     private capturing;
+    /**
+     * 사용자가 [제안 ▾] 를 직접 건드렸는가. 한 번이라도 건드리면 이후 타이핑에 의한 자동
+     * 접힘/펼침이 멈춘다 — 모달의 `userToggledHints` 와 같은 규칙. 팝업을 새로 열 때마다 리셋된다.
+     */
+    private userToggledHints;
     private readonly onClick;
     private readonly onMouseOver;
     constructor(opts: ElementPickingOpts);
@@ -189,6 +210,18 @@ declare class ElementPickingController {
         y: number;
     }): void;
     setAnnotationComment(value: string): void;
+    /**
+     * 코멘트가 비었는지에 따라 칩 줄 상태를 갱신하는 조각. `setAnnotationComment`·`applyHint`
+     * 양쪽에서 쓴다 — 모달의 `hintsPatchFor` 와 같은 규칙이다.
+     */
+    private hintsPatchFor;
+    /**
+     * 칩 누름. 이미 눌린 칩이면 아무 일도 하지 않는다. 코멘트가 비어 있으면 초안으로 치환,
+     * 아니면 줄바꿈 뒤 이어붙인다 — 모달의 `applyHint` 와 동일한 규칙이다.
+     */
+    applyHint(hintId: string): void;
+    /** [제안 ▾] 토글. 방향과 무관하게 이후 자동 접힘/펼침을 멈춘다. */
+    toggleHints(): void;
     /**
      * 사용자가 붙여넣기(Cmd+V)나 드래그로 넣은 그림. 자동 캡처 결과를 덮는다.
      *
@@ -268,6 +301,13 @@ interface WebWidgetOpts extends Omit<WidgetControllerOpts, "platform" | "initial
     };
     /** 요소를 고른 뒤 띄울 UI. 기본은 `popup`. */
     pickTarget?: PickTarget;
+    /**
+     * 정적 힌트 목록(설정으로 직접 넘김). 주면 서버에서 받아오지 않는다 — 도입 초기·오프라인
+     * 데모·테스트용이다. 서버 목록과 합치지 않는다(둘을 섞으면 무엇이 보이는지 설명이 안 된다).
+     */
+    hints?: readonly FeedbackHint[];
+    /** 힌트 조회 컨트롤러 주입(테스트용). 주면 큐 어댑터의 fetchHints 를 보지 않는다. */
+    hintProvider?: HintProvider;
 }
 interface WebWidget {
     widget: WidgetController;

package/dist/index.js

@@ -7,6 +7,7 @@ import {
   COMMENT_TOO_LONG_MESSAGE,
   denormalizePin,
   FLOATING_BUTTON_ID as FLOATING_BUTTON_ID2,
+  MODAL_ACTION_HINT_TOGGLE as MODAL_ACTION_HINT_TOGGLE2,
   MODAL_ACTION_PICK as MODAL_ACTION_PICK2,
   normalizePin as normalizePin2,
   ReportModalController,
@@ -15,6 +16,7 @@ import {
   SUBMIT_PENDING_MESSAGE,
   WidgetController as WidgetController2
 } from "@solhun/feedback-kit-core";
+import { HintProvider as HintProvider2, rankHints as rankHints2 } from "@solhun/feedback-kit-core";
 
 // src/react-tree.ts
 var FRAMEWORK_INTERNALS = /* @__PURE__ */ new Set([
@@ -328,6 +330,11 @@ var ElementPickingController = class {
     this.shotGeneration = 0;
     /** 지금 도는 자동 캡처. Enter 가 캡처보다 빨랐을 때 기다릴 대상. */
     this.capturing = null;
+    /**
+     * 사용자가 [제안 ▾] 를 직접 건드렸는가. 한 번이라도 건드리면 이후 타이핑에 의한 자동
+     * 접힘/펼침이 멈춘다 — 모달의 `userToggledHints` 와 같은 규칙. 팝업을 새로 열 때마다 리셋된다.
+     */
+    this.userToggledHints = false;
     this.onClick = (event) => this.handleClick(event);
     this.onMouseOver = (event) => this.handleMouseOver(event);
     this.queue = opts.queue;
@@ -340,6 +347,7 @@ var ElementPickingController = class {
     this.capture = opts.capture ?? null;
     this.reencode = opts.reencode ?? null;
     this.screenshotLimitBytes = opts.screenshotLimitBytes;
+    this.rankHintsFor = opts.rankHintsFor ?? null;
     this.lastPathname = this.getPathname();
     this.markers = this.store.list(this.lastPathname);
     this.unsubscribeQueue = this.queue.subscribe?.(() => {
@@ -454,14 +462,22 @@ var ElementPickingController = class {
       this.onPick(describeElement(element), point);
       return;
     }
+    const info = describeElement(element);
+    this.userToggledHints = false;
+    const hints = this.rankHintsFor ? this.rankHintsFor(info) : [];
     this.popup = {
-      element: describeElement(element),
+      element: info,
       point,
       comment: "",
       canSave: false,
       screenshot: null,
       screenshotStatus: this.capture ? "capturing" : "none",
-      saving: false
+      saving: false,
+      hints,
+      // 코멘트가 비어 있을 때만 펼친다 — 모달과 같은 규칙(계약 원문). 방금 연 팝업은 항상 빈다.
+      hintsExpanded: true,
+      hintsAvailable: hints.length > 0,
+      usedHintIds: []
     };
     this.emit();
     if (this.capture) this.capturing = this.runCapture();
@@ -471,10 +487,48 @@ var ElementPickingController = class {
     this.popup = {
       ...this.popup,
       comment: value,
-      canSave: this.isSavable(value)
+      canSave: this.isSavable(value),
+      ...this.hintsPatchFor(value)
     };
     this.emit();
   }
+  /**
+   * 코멘트가 비었는지에 따라 칩 줄 상태를 갱신하는 조각. `setAnnotationComment`·`applyHint`
+   * 양쪽에서 쓴다 — 모달의 `hintsPatchFor` 와 같은 규칙이다.
+   */
+  hintsPatchFor(nextComment) {
+    if (nextComment.trim().length === 0) {
+      return { hintsExpanded: true, usedHintIds: [] };
+    }
+    return this.userToggledHints ? {} : { hintsExpanded: false };
+  }
+  /**
+   * 칩 누름. 이미 눌린 칩이면 아무 일도 하지 않는다. 코멘트가 비어 있으면 초안으로 치환,
+   * 아니면 줄바꿈 뒤 이어붙인다 — 모달의 `applyHint` 와 동일한 규칙이다.
+   */
+  applyHint(hintId) {
+    if (!this.popup || this.popup.saving) return;
+    if (this.popup.usedHintIds.includes(hintId)) return;
+    const hint = this.popup.hints.find((h) => h.id === hintId);
+    if (!hint) return;
+    const comment = this.popup.comment.length === 0 ? hint.draft : `${this.popup.comment}
+${hint.draft}`;
+    this.popup = {
+      ...this.popup,
+      comment,
+      canSave: this.isSavable(comment),
+      usedHintIds: [...this.popup.usedHintIds, hintId],
+      ...this.hintsPatchFor(comment)
+    };
+    this.emit();
+  }
+  /** [제안 ▾] 토글. 방향과 무관하게 이후 자동 접힘/펼침을 멈춘다. */
+  toggleHints() {
+    if (!this.popup) return;
+    this.userToggledHints = true;
+    this.popup = { ...this.popup, hintsExpanded: !this.popup.hintsExpanded };
+    this.emit();
+  }
   /**
    * 사용자가 붙여넣기(Cmd+V)나 드래그로 넣은 그림. 자동 캡처 결과를 덮는다.
    *
@@ -581,7 +635,9 @@ var ElementPickingController = class {
       priority: "unset",
       screenshot: settled.screenshot,
       pin: settled.point,
-      element: settled.element
+      element: settled.element,
+      // 눌린 칩 기록. 리포트 모달과 같은 필드 — 들어온 문이 달라도 채택 신호는 같은 값으로 쌓인다.
+      hintIds: settled.usedHintIds
     };
     let report;
     try {
@@ -741,12 +797,105 @@ var reencodeWebScreenshot = async (shot, quality) => {
 };
 
 // src/widget.ts
-import { WidgetController } from "@solhun/feedback-kit-core";
+import {
+  WidgetController,
+  HintProvider,
+  rankHints
+} from "@solhun/feedback-kit-core";
+
+// src/storage.ts
+function memoryStorage() {
+  const map = /* @__PURE__ */ new Map();
+  return {
+    getItem: (key) => map.get(key) ?? null,
+    setItem: (key, value) => void map.set(key, value),
+    removeItem: (key) => void map.delete(key)
+  };
+}
+function pickBacking() {
+  try {
+    const ls = globalThis.localStorage;
+    if (!ls) return memoryStorage();
+    const probe = "__feedback_kit_probe__";
+    ls.setItem(probe, "1");
+    ls.removeItem(probe);
+    return ls;
+  } catch {
+    return memoryStorage();
+  }
+}
+function createWebStorage(backing) {
+  const store = backing ?? pickBacking();
+  return {
+    async get(key) {
+      try {
+        return store.getItem(key);
+      } catch {
+        return null;
+      }
+    },
+    async set(key, value) {
+      store.setItem(key, value);
+    },
+    async remove(key) {
+      try {
+        store.removeItem(key);
+      } catch {
+      }
+    }
+  };
+}
+
+// src/widget.ts
+function stripQueryHash(path) {
+  const cut = [path.indexOf("?"), path.indexOf("#")].filter((i) => i >= 0);
+  return cut.length > 0 ? path.slice(0, Math.min(...cut)) : path;
+}
+function defaultPathname2() {
+  const loc = globalThis.location;
+  return loc?.pathname ?? "/";
+}
+function hintSourceFrom(queue) {
+  const adapter = queue.adapter;
+  if (!adapter || typeof adapter.fetchHints !== "function") return null;
+  const cacheKey = adapter.hintsCacheKey ?? "default";
+  return { fetchHints: adapter.fetchHints.bind(adapter), cacheKey };
+}
+function resolveHintProvider(opts) {
+  if (opts.hintProvider) return opts.hintProvider;
+  if (opts.hints) {
+    return new HintProvider({ source: null, staticHints: opts.hints, cacheKey: "static" });
+  }
+  const found = hintSourceFrom(opts.queue);
+  if (!found) return null;
+  return new HintProvider({
+    source: { fetchHints: (etag) => found.fetchHints(etag) },
+    storage: createWebStorage(),
+    cacheKey: found.cacheKey
+  });
+}
+var POPUP_HINT_DISPLAY_MAX = 3;
+function rankFor(hintProvider, opts, element, limitOverride) {
+  const catalog = hintProvider.catalog();
+  if (!catalog) return [];
+  const input = {
+    platform: "web",
+    path: stripQueryHash(opts.getPathname ? opts.getPathname() : defaultPathname2()),
+    element,
+    components: element ? element.attributes["react-components"] ?? null : null
+  };
+  const limit = limitOverride !== void 0 ? Math.min(limitOverride, catalog.maxDisplay) : catalog.maxDisplay;
+  return rankHints(catalog.hints, input, limit);
+}
 function createWebWidget(opts) {
   const store = opts.store ?? new MarkerStore();
   let widgetRef = null;
   const capture = opts.capture === void 0 ? captureWebScreenshot : opts.capture;
   const reencode = opts.reencode === void 0 ? reencodeWebScreenshot : opts.reencode;
+  const hintProvider = resolveHintProvider(opts);
+  if (hintProvider) {
+    void hintProvider.load().then(() => hintProvider.refresh());
+  }
   const picking = new ElementPickingController({
     queue: opts.queue,
     createReport: opts.createReport,
@@ -762,7 +911,8 @@ function createWebWidget(opts) {
     // 모드는 어느 쪽이든 켜진 채로 둬서 한 번 켜고 여러 요소를 연달아 지목할 수 있다.
     onPick: opts.pickTarget === "modal" ? (element, point) => {
       void widgetRef?.openReport({ element, pin: point });
-    } : void 0
+    } : void 0,
+    rankHintsFor: hintProvider ? (element) => rankFor(hintProvider, opts, element, POPUP_HINT_DISPLAY_MAX) : null
   });
   const widget = new WidgetController({
     ...opts,
@@ -777,6 +927,13 @@ function createWebWidget(opts) {
     }
   });
   widgetRef = widget;
+  const originalOpenReport = widget.openReport.bind(widget);
+  widget.openReport = async (openOpts = {}) => {
+    if (hintProvider) {
+      widget.modal.setHints(rankFor(hintProvider, opts, openOpts.element ?? null));
+    }
+    await originalOpenReport(openOpts);
+  };
   const originalSubmit = widget.submitReport.bind(widget);
   widget.submitReport = async () => {
     const outcome = await originalSubmit();
@@ -801,6 +958,7 @@ import {
   COMMENT_MAX_CHARS as COMMENT_MAX_CHARS2,
   FLOATING_BUTTON_ID,
   MODAL_ACTION_CANCEL,
+  MODAL_ACTION_HINT_TOGGLE,
   MODAL_ACTION_PICK,
   MODAL_ACTION_REMOVE_SCREENSHOT,
   MODAL_ACTION_RETRY,
@@ -815,7 +973,7 @@ import {
 } from "react";
 
 // src/version.ts
-var VERSION = true ? "0.5.0" : "dev";
+var VERSION = true ? "0.6.0" : "dev";
 
 // src/feedback-kit.tsx
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
@@ -1077,6 +1235,69 @@ function MarkerStatus({ status }) {
     /* @__PURE__ */ jsx("span", { children: presentation.text })
   ] });
 }
+function HintChips({
+  hints,
+  hintsExpanded,
+  usedHintIds,
+  disabled,
+  onApply,
+  onToggle
+}) {
+  return /* @__PURE__ */ jsxs("div", { style: { marginBottom: 16 }, children: [
+    hintsExpanded ? /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx("p", { style: { margin: "0 0 7px", color: TOKENS.muted, fontSize: 12 }, children: "\uC774\uB7F0 \uAC74\uAC00\uC694?" }),
+      /* @__PURE__ */ jsx(
+        "div",
+        {
+          role: "group",
+          "aria-label": "\uC790\uC8FC \uB098\uC624\uB294 \uC81C\uBCF4 \uC81C\uC548",
+          style: { display: "flex", flexWrap: "wrap", gap: 6, marginBottom: 7 },
+          children: hints.map((hint) => {
+            const used = usedHintIds.includes(hint.id);
+            return /* @__PURE__ */ jsx(
+              "button",
+              {
+                type: "button",
+                "data-fk-focus-id": `hint:${hint.id}`,
+                disabled: used || disabled,
+                "aria-pressed": used,
+                onClick: () => onApply(hint.id),
+                style: {
+                  ...baseButton,
+                  minHeight: 30,
+                  padding: "5px 10px",
+                  fontSize: 12,
+                  fontWeight: 600,
+                  borderRadius: 999,
+                  ...used ? {
+                    background: TOKENS.subtle,
+                    color: TOKENS.muted,
+                    borderColor: TOKENS.line,
+                    cursor: "default"
+                  } : {}
+                },
+                children: hint.label
+              },
+              hint.id
+            );
+          })
+        }
+      )
+    ] }) : null,
+    /* @__PURE__ */ jsx(
+      "button",
+      {
+        type: "button",
+        "data-fk-focus-id": MODAL_ACTION_HINT_TOGGLE,
+        "aria-expanded": hintsExpanded,
+        disabled,
+        onClick: onToggle,
+        style: { ...baseButton, minHeight: 28, padding: "4px 10px", fontSize: 12 },
+        children: hintsExpanded ? "\uC81C\uC548 \u25B4" : "\uC81C\uC548 \u25BE"
+      }
+    )
+  ] });
+}
 function FeedbackKit(props) {
   const rootRef = useRef(null);
   const floatingButtonRef = useRef(null);
@@ -1099,7 +1320,10 @@ function FeedbackKit(props) {
     store,
     getPathname,
     doc,
-    getViewport
+    getViewport,
+    pickTarget,
+    hints,
+    hintProvider
   } = props;
   useEffect(() => {
     const created = createWebWidget({
@@ -1111,7 +1335,10 @@ function FeedbackKit(props) {
       store,
       getPathname,
       doc,
-      getViewport
+      getViewport,
+      pickTarget,
+      hints,
+      hintProvider
     });
     setKit(created);
     const unsubscribeWidget = created.widget.subscribe(setWidgetState);
@@ -1129,6 +1356,9 @@ function FeedbackKit(props) {
     screenshotLimitBytes,
     store,
     getPathname,
+    pickTarget,
+    hints,
+    hintProvider,
     doc,
     getViewport
   ]);
@@ -1427,6 +1657,17 @@ function FeedbackKit(props) {
                         )
                       ] })
                     ] }),
+                    modal.hintsAvailable ? /* @__PURE__ */ jsx(
+                      HintChips,
+                      {
+                        hints: modal.hints,
+                        hintsExpanded: modal.hintsExpanded,
+                        usedHintIds: modal.usedHintIds,
+                        disabled: draftLocked,
+                        onApply: (hintId) => kit.widget.modal.applyHint(hintId),
+                        onToggle: () => kit.widget.modal.toggleHints()
+                      }
+                    ) : null,
                     /* @__PURE__ */ jsxs("label", { htmlFor: "feedback-kit-comment", style: { display: "block", fontWeight: 700 }, children: [
                       "\uCF54\uBA58\uD2B8 ",
                       /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "*" })
@@ -1683,6 +1924,17 @@ function FeedbackKit(props) {
                         ]
                       }
                     ),
+                    popup.hintsAvailable ? /* @__PURE__ */ jsx(
+                      HintChips,
+                      {
+                        hints: popup.hints,
+                        hintsExpanded: popup.hintsExpanded,
+                        usedHintIds: popup.usedHintIds,
+                        disabled: popup.saving,
+                        onApply: (hintId) => kit.picking.applyHint(hintId),
+                        onToggle: () => kit.picking.toggleHints()
+                      }
+                    ) : null,
                     /* @__PURE__ */ jsx("label", { htmlFor: "feedback-kit-annotation", style: visuallyHidden, children: "\uC774 \uC694\uC18C\uC5D0 \uB0A8\uAE38 \uC758\uACAC" }),
                     /* @__PURE__ */ jsx(
                       "textarea",
@@ -1783,49 +2035,6 @@ function FeedbackKit(props) {
   );
 }
 
-// src/storage.ts
-function memoryStorage() {
-  const map = /* @__PURE__ */ new Map();
-  return {
-    getItem: (key) => map.get(key) ?? null,
-    setItem: (key, value) => void map.set(key, value),
-    removeItem: (key) => void map.delete(key)
-  };
-}
-function pickBacking() {
-  try {
-    const ls = globalThis.localStorage;
-    if (!ls) return memoryStorage();
-    const probe = "__feedback_kit_probe__";
-    ls.setItem(probe, "1");
-    ls.removeItem(probe);
-    return ls;
-  } catch {
-    return memoryStorage();
-  }
-}
-function createWebStorage(backing) {
-  const store = backing ?? pickBacking();
-  return {
-    async get(key) {
-      try {
-        return store.getItem(key);
-      } catch {
-        return null;
-      }
-    },
-    async set(key, value) {
-      store.setItem(key, value);
-    },
-    async remove(key) {
-      try {
-        store.removeItem(key);
-      } catch {
-      }
-    }
-  };
-}
-
 // src/providers.ts
 function webContextProviders() {
   return {
@@ -1855,8 +2064,10 @@ export {
   ElementPickingController,
   FLOATING_BUTTON_ID2 as FLOATING_BUTTON_ID,
   FeedbackKit,
+  HintProvider2 as HintProvider,
   MARKER_KEY_PREFIX,
   MAX_MARKERS_PER_PATH,
+  MODAL_ACTION_HINT_TOGGLE2 as MODAL_ACTION_HINT_TOGGLE,
   MODAL_ACTION_PICK2 as MODAL_ACTION_PICK,
   MarkerStore,
   OWN_UI_ATTR,
@@ -1877,6 +2088,7 @@ export {
   isOwnUi2 as isOwnUi,
   normalizePin2 as normalizePin,
   parseSourceAttr,
+  rankHints2 as rankHints,
   reactComponentPath,
   reactComponentSummary,
   reencodeWebScreenshot,