@solhun/feedback-kit-core 0.4.0 → 0.6.0

package/dist/index.js

@@ -216,7 +216,9 @@ async function buildReport(parts, opts) {
     pin: parts.pin,
     element: parts.element,
     context,
-    createdAt: iso(now())
+    createdAt: iso(now()),
+    // 생략과 "정말 아무 것도 안 눌렀음"을 굳이 구분하지 않는다 — 둘 다 빈 배열로 싣는다.
+    hintIds: parts.hintIds ?? []
   };
 }
 
@@ -1339,6 +1341,7 @@ var COMMENT_TOO_LONG_MESSAGE = "4,000\uC790 \uC774\uD558\uB85C \uC785\uB825\uD57
 var SUBMIT_DONE_MESSAGE = "\uBCF4\uB0C8\uC2B5\uB2C8\uB2E4";
 var SUBMIT_PENDING_MESSAGE = "\uB300\uAE30 \uC911";
 var SUBMIT_FAILED_MESSAGE = "\uBCF4\uB0B4\uC9C0 \uBABB\uD588\uC2B5\uB2C8\uB2E4";
+var MODAL_ACTION_HINT_TOGGLE = "hint-toggle";
 var MODAL_FIELD_COMMENT = "comment";
 var MODAL_FIELD_PRIORITY = "priority";
 var MODAL_ACTION_ATTACH = "attach";
@@ -1360,6 +1363,12 @@ var ReportModalController = class {
     this.captureGeneration = 0;
     /** 지금 들고 있는 핀의 기준. 핀이 없으면 의미 없다(기본 `picture`). */
     this.pinAnchor = "picture";
+    /**
+     * 사용자가 [제안 ▾] 를 직접 건드렸는가(방향 무관). 한 번이라도 건드리면 이후
+     * 타이핑에 의한 자동 접힘/펼침이 멈춘다 — "사람이 편 상태는 모달이 닫힐 때까지 유지"를
+     * 이렇게 구현한다. `open()` 에서 매번 리셋된다.
+     */
+    this.userToggledHints = false;
     this.state = {
       open: false,
       element: null,
@@ -1380,7 +1389,11 @@ var ReportModalController = class {
       actions: [],
       focusOrder: [],
       focused: null,
-      restoreFocusTo: null
+      restoreFocusTo: null,
+      hints: [],
+      hintsExpanded: false,
+      hintsAvailable: false,
+      usedHintIds: []
     };
     this.queue = opts.queue;
     this.createReport = opts.createReport;
@@ -1440,9 +1453,11 @@ var ReportModalController = class {
     this.touched = false;
     this.submitAttempted = false;
     this.pinAnchor = opts.pin && !pendingReport ? "viewport" : "picture";
+    this.userToggledHints = false;
+    const resolvedComment = pendingReport?.comment ?? "";
     this.patch({
       open: true,
-      comment: pendingReport?.comment ?? "",
+      comment: resolvedComment,
       // 요소를 지목해서 연 경우엔 그 요소를 물고 간다. 대기 항목 복원이 우선이다.
       element: pendingReport?.element ?? opts.element ?? null,
       priority: pendingReport?.priority ?? "unset",
@@ -1453,7 +1468,10 @@ var ReportModalController = class {
       submitStatus: wasPending ? "pending" : "idle",
       submitMessage: wasPending ? SUBMIT_PENDING_MESSAGE : null,
       closeConfirmVisible: false,
-      restoreFocusTo: null
+      restoreFocusTo: null,
+      // 코멘트가 비어 있을 때만 펼쳐진 채로 연다. 대기 항목을 복원해도 규칙은 같다(계약 원문).
+      hintsExpanded: resolvedComment === "",
+      usedHintIds: []
     });
     this.ring.focus(MODAL_FIELD_COMMENT);
     this.patch({ focused: this.ring.current });
@@ -1512,7 +1530,22 @@ var ReportModalController = class {
   setComment(value) {
     if (this.isDraftLocked()) return;
     this.touched = true;
-    this.patch({ comment: value });
+    this.patch({ comment: value, ...this.hintsPatchFor(value) });
+  }
+  /**
+   * 코멘트가 비었는지에 따라 칩 줄 상태를 갱신하는 조각을 만든다. `setComment`·`applyHint`
+   * 양쪽에서 쓴다.
+   *
+   * - 완전히 비워지면(trim 기준) 눌린 칩 기록을 버리고 다시 펼친다 — "지우고 처음부터 다시
+   *   쓴 글"에 이전 제안을 귀속시키지 않기 위해서다. 사용자가 직접 편 상태여도 예외 없다.
+   * - 비어 있지 않게 되면, 사용자가 직접 편 게 아닌 이상 접는다(좁은 화면에서 입력란을
+   *   밀어내지 않으려고). 직접 편 상태(`userToggledHints`)면 손대지 않는다.
+   */
+  hintsPatchFor(nextComment) {
+    if (nextComment.trim().length === 0) {
+      return { hintsExpanded: true, usedHintIds: [] };
+    }
+    return this.userToggledHints ? {} : { hintsExpanded: false };
   }
   setPriority(priority) {
     if (this.isDraftLocked()) return;
@@ -1585,6 +1618,41 @@ var ReportModalController = class {
       ...dropPin
     });
   }
+  // ── 제안 힌트 ─────────────────────────────────────────────────────────────
+  /**
+   * 컨트롤러가 랭킹 결과를 밀어넣는다. **모달이 열려 있는 동안에는 무시한다** — 지목 대상을
+   * 바꿔 새로 열기 직전에 호출되는 흐름이 정상이고, 열려 있는 모달의 칩을 도중에 바꾸면
+   * 누르려던 칩이 손가락 밑에서 바뀐다(캐시 백그라운드 갱신도 이 경로로 들어올 수 있다).
+   */
+  setHints(hints) {
+    if (this.state.open) return;
+    this.patch({ hints });
+  }
+  /**
+   * 칩 누름. 이미 눌린 칩이면 아무 일도 하지 않는다(같은 문구가 두 번 이어붙는 걸 막는다).
+   * 코멘트가 비어 있으면 초안으로 치환, 아니면 줄바꿈 뒤 이어붙인다 — 어느 쪽도 사용자가
+   * 쓴 글을 지우지 않는다.
+   */
+  applyHint(hintId) {
+    if (this.isDraftLocked()) return;
+    if (this.state.usedHintIds.includes(hintId)) return;
+    const hint = this.state.hints.find((h) => h.id === hintId);
+    if (!hint) return;
+    this.touched = true;
+    const comment = this.state.comment.length === 0 ? hint.draft : `${this.state.comment}
+${hint.draft}`;
+    this.patch({
+      comment,
+      usedHintIds: [...this.state.usedHintIds, hintId],
+      // 방금 채워 넣었으니 비어 있지 않다 — setComment 와 같은 접힘 규칙을 그대로 쓴다.
+      ...this.hintsPatchFor(comment)
+    });
+  }
+  /** [제안 ▾] 토글. 방향과 무관하게 이후 자동 접힘/펼침을 멈춘다(`userToggledHints`). */
+  toggleHints() {
+    this.userToggledHints = true;
+    this.patch({ hintsExpanded: !this.state.hintsExpanded });
+  }
   // ── 포커스 ────────────────────────────────────────────────────────────────
   tabNext() {
     const next = this.ring.next();
@@ -1622,7 +1690,9 @@ var ReportModalController = class {
       priority: this.state.priority,
       screenshot: this.state.screenshot,
       pin: this.state.pin,
-      element: this.state.element
+      element: this.state.element,
+      // 눌린 칩 기록. 문구를 고쳐 보내도 "이 제안을 눌렀다"는 사실은 그대로 남는다.
+      hintIds: this.state.usedHintIds
     };
     let outcome;
     try {
@@ -1688,8 +1758,15 @@ var ReportModalController = class {
   actionsFor() {
     return this.platform === "web" ? [MODAL_ACTION_PICK] : [MODAL_ACTION_PIN];
   }
-  focusOrderFor() {
-    const order = [MODAL_FIELD_COMMENT, MODAL_FIELD_PRIORITY];
+  focusOrderFor(hintsAvailable) {
+    const order = [];
+    if (hintsAvailable) {
+      if (this.state.hintsExpanded) {
+        for (const hint of this.state.hints) order.push(`hint:${hint.id}`);
+      }
+      order.push(MODAL_ACTION_HINT_TOGGLE);
+    }
+    order.push(MODAL_FIELD_COMMENT, MODAL_FIELD_PRIORITY);
     if (this.state.screenshot) order.push(MODAL_ACTION_REMOVE_SCREENSHOT);
     else order.push(MODAL_ACTION_ATTACH);
     order.push(...this.actionsFor());
@@ -1702,7 +1779,8 @@ var ReportModalController = class {
     const canSubmit = this.isCommentValid() && this.state.screenshotStatus !== "capturing" && (this.state.submitStatus === "idle" || this.state.submitStatus === "failed");
     const canPin = this.platform === "native" && this.state.screenshot !== null && this.state.screenshotStatus !== "capturing" && !this.isDraftLocked() && this.state.open;
     const actions = this.actionsFor();
-    const focusOrder = this.state.open ? this.focusOrderFor() : [];
+    const hintsAvailable = this.state.hints.length > 0;
+    const focusOrder = this.state.open ? this.focusOrderFor(hintsAvailable) : [];
     this.ring.setItems(focusOrder);
     this.state = {
       ...this.state,
@@ -1711,6 +1789,7 @@ var ReportModalController = class {
       canPin,
       showRetry: this.state.submitStatus === "pending" || this.state.pending > 0,
       actions,
+      hintsAvailable,
       focusOrder,
       focused: this.state.open ? this.ring.current : null
     };
@@ -2101,6 +2180,13 @@ function absoluteEndpoint(endpoint) {
   if (typeof origin !== "string" || origin.length === 0) return null;
   return endpoint.startsWith("/") ? `${origin}${endpoint}` : `${origin}/${endpoint}`;
 }
+function hintsCacheKeyFrom(endpoint) {
+  const path = endpoint.split(/[?#]/)[0] ?? "";
+  const segments = path.split("/").filter((s) => s.length > 0);
+  const last = segments.at(-1);
+  if (!last || last === "verify") return void 0;
+  return last;
+}
 function parseRetryAfterMs(res) {
   const raw = res.headers?.get("Retry-After") ?? null;
   if (raw === null) return null;
@@ -2165,6 +2251,8 @@ function buildLassoContext(report) {
     } : null,
     // 속성이 하나도 없으면 빈 객체를 보내지 않는다 — 화면에 빈 항목이 늘어난다.
     element: el && (el.id !== null || Object.keys(el.attributes).length > 0) ? { id: el.id, attributes: el.attributes } : null,
+    // 생략과 "정말 하나도 안 눌렀음"을 구분하지 않는다 — 둘 다 빈 배열.
+    hintIds: [...report.hintIds ?? []],
     native: c.native ? {
       screenPath: c.native.screenPath,
       navPath: c.native.navPath,
@@ -2224,6 +2312,7 @@ function createLassoAdapter(opts = {}) {
   const token = opts.token ?? null;
   const endpoint = opts.endpoint && opts.endpoint.trim().length > 0 ? opts.endpoint.trim() : LASSO_DEFAULT_ENDPOINT;
   const warn = opts.warn ?? null;
+  const hintsCacheKey = hintsCacheKeyFrom(endpoint);
   const emit = (message) => {
     if (!warn) return;
     try {
@@ -2232,6 +2321,7 @@ function createLassoAdapter(opts = {}) {
     }
   };
   return {
+    hintsCacheKey,
     async submit(report) {
       const url = absoluteEndpoint(endpoint);
       if (url === null) {
@@ -2302,7 +2392,491 @@ function createLassoAdapter(opts = {}) {
         return fail(false);
       }
       return { ok: true, id: idFrom(parsed), retryable: false, retryAfterMs: null };
+    },
+    /**
+     * 힌트 카탈로그 조회. `submit` 과 같은 절대 규칙이 그대로 적용된다 — **던지지 않는다**,
+     * **본문·헤더를 로그에 남기지 않는다.** 다만 여기는 `warn` 을 아예 부르지 않는다.
+     * "실패하면 조용히 포기"·"개발 빌드에서만 1회 경고"의 판단(쿨다운·환경 분기)은
+     * `HintProvider`(hints/ 소유자) 몫이라, 어댑터가 매 실패마다 경고를 찍으면 그 판단과
+     * 어긋난다.
+     */
+    async fetchHints(etag) {
+      const url = absoluteEndpoint(`${endpoint.replace(/\/+$/, "")}/hints`);
+      if (url === null) return { kind: "fail" };
+      const sender = resolveFetch(opts.fetch);
+      if (sender === null) return { kind: "fail" };
+      const headers = {};
+      if (token !== null) headers.Authorization = `Bearer ${token}`;
+      if (etag !== null) headers["If-None-Match"] = etag;
+      let res;
+      try {
+        res = await sender(url, { method: "GET", headers });
+      } catch {
+        return { kind: "fail" };
+      }
+      if (res.status === 304) return { kind: "not-modified" };
+      if (res.status === 401 || res.status === 403) {
+        return { kind: "fail", permanent: true };
+      }
+      if (res.status < 200 || res.status >= 300) return { kind: "fail" };
+      let text;
+      try {
+        text = await res.text();
+      } catch {
+        return { kind: "fail" };
+      }
+      try {
+        const raw = JSON.parse(text);
+        return { kind: "ok", raw, etag: res.headers?.get("ETag") ?? null };
+      } catch {
+        return { kind: "fail" };
+      }
+    }
+  };
+}
+
+// src/hints/constants.ts
+var HINT_LABEL_MAX_CHARS = 12;
+var HINT_DRAFT_MAX_CHARS = 200;
+var HINT_DISPLAY_DEFAULT = 4;
+var HINT_DISPLAY_MIN = 3;
+var HINT_DISPLAY_MAX = 6;
+var HINT_MAX_ITEMS = 300;
+var HINT_TTL_MS = 24 * 60 * 60 * 1e3;
+var HINT_TIMEOUT_MS = 5e3;
+var HINT_FAIL_COOLDOWN_MS = 5 * 60 * 1e3;
+var SCORE_PATH_EXACT = 40;
+var SCORE_PATH_PATTERN = 25;
+var SCORE_ELEMENT = 30;
+
+// src/hints/chars.ts
+function hintCharCount(value) {
+  return [...value.normalize("NFC")].length;
+}
+
+// src/hints/path.ts
+function appPathFromNav(navPath) {
+  if (navPath === null || navPath === void 0 || navPath.length === 0) return null;
+  return "/" + navPath.join("/");
+}
+function matchPath(pattern, path) {
+  const patternSegs = splitSegments(pattern);
+  const pathSegs = splitSegments(path);
+  if (patternSegs === null || pathSegs === null) return null;
+  const hasWildcard = patternSegs.some((seg) => seg === "*" || seg === "**");
+  if (!hasWildcard) {
+    if (patternSegs.length !== pathSegs.length) return null;
+    for (let i = 0; i < patternSegs.length; i++) {
+      if (patternSegs[i] !== pathSegs[i]) return null;
+    }
+    return "exact";
+  }
+  return matchesFrom(patternSegs, 0, pathSegs, 0) ? "pattern" : null;
+}
+function splitSegments(value) {
+  if (typeof value !== "string" || value.length === 0) return null;
+  if (!value.startsWith("/")) return null;
+  if (value === "/") return [];
+  const trimmed = value.endsWith("/") ? value.slice(0, -1) : value;
+  const segments = trimmed.split("/").slice(1);
+  if (segments.some((seg) => seg.length === 0)) return null;
+  return segments;
+}
+function matchesFrom(pattern, patternIndex, path, pathIndex) {
+  if (patternIndex === pattern.length) return pathIndex === path.length;
+  const seg = pattern[patternIndex];
+  if (seg === "**") {
+    for (let consume = 0; pathIndex + consume <= path.length; consume++) {
+      if (matchesFrom(pattern, patternIndex + 1, path, pathIndex + consume)) return true;
+    }
+    return false;
+  }
+  if (pathIndex >= path.length) return false;
+  if (seg === "*") return matchesFrom(pattern, patternIndex + 1, path, pathIndex + 1);
+  return path[pathIndex] === seg && matchesFrom(pattern, patternIndex + 1, path, pathIndex + 1);
+}
+
+// src/hints/element.ts
+function matchElement(rule, element, components) {
+  if (rule === null) return true;
+  try {
+    const axes = [rule.tags, rule.roles, rule.classIncludes, rule.componentIncludes, rule.testIds];
+    const hasAnyAxis = axes.some((axis) => Array.isArray(axis) && axis.length > 0);
+    if (!hasAnyAxis) return true;
+    if (element === null) return false;
+    return matchesTags(rule.tags, element) || matchesRoles(rule.roles, element) || matchesClassIncludes(rule.classIncludes, element) || matchesComponentIncludes(rule.componentIncludes, components) || matchesTestIds(rule.testIds, element);
+  } catch {
+    return false;
+  }
+}
+function matchesTags(tags, element) {
+  if (!Array.isArray(tags)) return false;
+  const tag = safeLower(element.tag);
+  if (tag === null) return false;
+  return tags.some((t) => typeof t === "string" && t.toLowerCase() === tag);
+}
+function matchesRoles(roles, element) {
+  if (!Array.isArray(roles)) return false;
+  const role = safeLower(element.attributes?.role ?? null);
+  const type = safeLower(element.attributes?.type ?? null);
+  return roles.some((r) => {
+    if (typeof r !== "string") return false;
+    const lowered = r.toLowerCase();
+    return lowered === role || lowered === type;
+  });
+}
+function matchesClassIncludes(classIncludes, element) {
+  if (!Array.isArray(classIncludes)) return false;
+  const className = safeLower(element.className);
+  if (className === null) return false;
+  return classIncludes.some((c) => typeof c === "string" && className.includes(c.toLowerCase()));
+}
+function matchesComponentIncludes(componentIncludes, components) {
+  if (!Array.isArray(componentIncludes)) return false;
+  if (components === null) return false;
+  return componentIncludes.some((c) => typeof c === "string" && components.includes(c));
+}
+function matchesTestIds(testIds, element) {
+  if (!Array.isArray(testIds)) return false;
+  const testId = element.attributes?.["data-testid"];
+  if (typeof testId !== "string") return false;
+  return testIds.some((t) => t === testId);
+}
+function safeLower(value) {
+  return typeof value === "string" ? value.toLowerCase() : null;
+}
+
+// src/hints/parse.ts
+var SCOPES = ["screen", "element", "both"];
+var PLATFORMS = ["web", "app"];
+function parseHintCatalog(raw) {
+  if (typeof raw !== "object" || raw === null) return null;
+  const obj = raw;
+  if (obj.ok !== true) return null;
+  if (!Array.isArray(obj.hints)) return null;
+  const hints = [];
+  for (const item of obj.hints) {
+    if (hints.length >= HINT_MAX_ITEMS) break;
+    const parsed = parseHintItem(item);
+    if (parsed !== null) hints.push(parsed);
+  }
+  return {
+    version: typeof obj.version === "number" && Number.isInteger(obj.version) ? obj.version : null,
+    maxDisplay: parseMaxDisplay(obj.maxDisplay),
+    hints
+  };
+}
+function parseMaxDisplay(value) {
+  if (typeof value === "number" && Number.isInteger(value) && value >= HINT_DISPLAY_MIN && value <= HINT_DISPLAY_MAX) {
+    return value;
+  }
+  return HINT_DISPLAY_DEFAULT;
+}
+function parseHintItem(item) {
+  if (typeof item !== "object" || item === null) return null;
+  const obj = item;
+  const id = nonEmptyString(obj.id);
+  const label = nonEmptyString(obj.label);
+  const draft = nonEmptyString(obj.draft);
+  if (id === null || label === null || draft === null) return null;
+  if (typeof obj.scope !== "string" || !SCOPES.includes(obj.scope)) return null;
+  const scope = obj.scope;
+  const platforms = parsePlatforms(obj.platforms);
+  if (platforms === null) return null;
+  return {
+    id,
+    label,
+    draft,
+    scope,
+    platforms,
+    paths: parsePaths(obj.paths),
+    element: parseElementRule(obj.element),
+    active: parseActive(obj.active)
+  };
+}
+function parseActive(value) {
+  return value !== false;
+}
+function parsePlatforms(value) {
+  if (!Array.isArray(value) || value.length === 0) return null;
+  const result = [];
+  for (const p of value) {
+    if (typeof p !== "string" || !PLATFORMS.includes(p)) return null;
+    result.push(p);
+  }
+  return result;
+}
+function parsePaths(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((p) => typeof p === "string");
+}
+function parseElementRule(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  const obj = value;
+  const rule = {};
+  if (Array.isArray(obj.tags)) rule.tags = obj.tags.filter((v) => typeof v === "string");
+  if (Array.isArray(obj.roles)) rule.roles = obj.roles.filter((v) => typeof v === "string");
+  if (Array.isArray(obj.classIncludes)) {
+    rule.classIncludes = obj.classIncludes.filter((v) => typeof v === "string");
+  }
+  if (Array.isArray(obj.componentIncludes)) {
+    rule.componentIncludes = obj.componentIncludes.filter((v) => typeof v === "string");
+  }
+  if (Array.isArray(obj.testIds)) rule.testIds = obj.testIds.filter((v) => typeof v === "string");
+  return rule;
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+// src/hints/rank.ts
+function rankHints(hints, input, limit) {
+  const scored = [];
+  for (let index = 0; index < hints.length; index++) {
+    const hint = hints[index];
+    if (!passesHardFilter(hint, input)) continue;
+    scored.push({ hint, score: scoreHint(hint, input), index });
+  }
+  const ordered = orderByScoreThenRotatedGroup(scored, input.path);
+  return ordered.slice(0, Math.max(0, limit)).map((s) => s.hint);
+}
+function orderByScoreThenRotatedGroup(scored, path) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const s of scored) {
+    const group = groups.get(s.score);
+    if (group) group.push(s);
+    else groups.set(s.score, [s]);
+  }
+  const scoresDesc = [...groups.keys()].sort((a, b) => b - a);
+  const result = [];
+  for (const score of scoresDesc) {
+    result.push(...rotateGroup(groups.get(score), path));
+  }
+  return result;
+}
+function rotateGroup(group, path) {
+  if (group.length <= 1 || path === null) return group;
+  const offset = fnv1a32(path) % group.length;
+  if (offset === 0) return group;
+  return [...group.slice(offset), ...group.slice(0, offset)];
+}
+function fnv1a32(value) {
+  let hash = 2166136261;
+  for (let i = 0; i < value.length; i++) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+function passesHardFilter(hint, input) {
+  if (!hint.platforms.includes(input.platform)) return false;
+  const wantsElementScope = input.element !== null;
+  if (wantsElementScope) {
+    if (hint.scope !== "element" && hint.scope !== "both") return false;
+  } else if (hint.scope !== "screen" && hint.scope !== "both") {
+    return false;
+  }
+  if (hint.paths.length > 0 && !matchesAnyPath(hint.paths, input.path)) return false;
+  if (hint.active === false) return false;
+  if (hintCharCount(hint.label) > HINT_LABEL_MAX_CHARS) return false;
+  if (hintCharCount(hint.draft) > HINT_DRAFT_MAX_CHARS) return false;
+  return true;
+}
+function matchesAnyPath(paths, path) {
+  if (path === null) return false;
+  return paths.some((pattern) => matchPath(pattern, path) !== null);
+}
+function scoreHint(hint, input) {
+  let score = bestPathScore(hint.paths, input.path);
+  if (input.element !== null && matchElement(hint.element, input.element, input.components)) {
+    score += SCORE_ELEMENT;
+  }
+  return score;
+}
+function bestPathScore(paths, path) {
+  if (paths.length === 0 || path === null) return 0;
+  let best = 0;
+  for (const pattern of paths) {
+    const result = matchPath(pattern, path);
+    if (result === "exact") return SCORE_PATH_EXACT;
+    if (result === "pattern") best = SCORE_PATH_PATTERN;
+  }
+  return best;
+}
+
+// src/hints/provider.ts
+var CACHE_KEY_PREFIX = "feedback-kit:hints:";
+var HintProvider = class {
+  constructor(opts) {
+    this.entry = null;
+    /** refresh() 동시 호출을 한 번의 요청으로 합친다. */
+    this.inflight = null;
+    /**
+     * 401/403 등 설정 문제로 영구 실패했는가 — 이 인스턴스가 살아 있는 동안 재요청하지
+     * 않는다. **저장소에는 남기지 않는다**(메모리만): 토큰을 고치고 재배포하면 그건 새
+     * 페이지 로드 = 새 인스턴스이므로 자연히 풀린다. 캐시에 박아두면 사용자가 캐시를
+     * 지우기 전까지 죽은 채로 남는다.
+     */
+    this.permanentlyFailed = false;
+    /**
+     * 실패(네트워크·타임아웃·5xx·401/403 전부 포함) 경고를 이미 냈는가 — 인스턴스당 1회로
+     * 제한한다. 5분 쿨다운마다 매번 경고를 찍으면 콘솔이 "실패했다"만 반복하는 노이즈가
+     * 된다("개발 빌드에서만 경고를 1회 남긴다" — 계약 원문).
+     */
+    this.warnedFailure = false;
+    this.source = opts.source;
+    this.storage = opts.storage ?? null;
+    this.storageKey = CACHE_KEY_PREFIX + opts.cacheKey;
+    this.now = opts.now ?? (() => Date.now());
+    this.warn = opts.warn ?? (() => void 0);
+    this.staticCatalog = opts.staticHints ? { version: null, maxDisplay: HINT_DISPLAY_DEFAULT, hints: opts.staticHints } : null;
+  }
+  /** 캐시 복원. 마운트 직후 1회. 던지지 않는다. */
+  async load() {
+    if (this.staticCatalog !== null) return;
+    if (this.storage === null) return;
+    try {
+      const raw = await this.storage.get(this.storageKey);
+      if (raw === null) return;
+      const parsed = parseCacheEntry(JSON.parse(raw));
+      if (parsed !== null) this.entry = parsed;
+    } catch (err) {
+      this.warn(`feedback-kit: \uD78C\uD2B8 \uCE90\uC2DC\uB97C \uC77D\uC9C0 \uBABB\uD588\uB2E4(${String(err)})`);
     }
+  }
+  /** 필요하면 네트워크. TTL 안이거나 쿨다운 중이면 아무것도 안 한다. 던지지 않는다. */
+  refresh() {
+    if (this.staticCatalog !== null) return Promise.resolve();
+    if (this.source === null) return Promise.resolve();
+    if (this.inflight !== null) return this.inflight;
+    const p = this.doRefresh().finally(() => {
+      this.inflight = null;
+    });
+    this.inflight = p;
+    return p;
+  }
+  /** 지금 쓸 수 있는 카탈로그. 없으면 null. 동기 — 요청을 기다리지 않는다. */
+  catalog() {
+    if (this.staticCatalog !== null) return this.staticCatalog;
+    if (this.entry === null || this.entry.hints.length === 0) return null;
+    return { version: this.entry.version, maxDisplay: this.entry.maxDisplay, hints: this.entry.hints };
+  }
+  async doRefresh() {
+    if (this.permanentlyFailed) return;
+    const now = this.now();
+    if (this.entry !== null) {
+      if (now - this.entry.fetchedAt < HINT_TTL_MS) return;
+      if (this.entry.failedAt !== null && now - this.entry.failedAt < HINT_FAIL_COOLDOWN_MS) return;
+    }
+    const etag = this.entry?.etag ?? null;
+    const result = await this.fetchWithTimeout(etag);
+    if (result.kind === "ok") {
+      const parsed = parseHintCatalog(result.raw);
+      if (parsed === null) {
+        this.warn("feedback-kit: \uD78C\uD2B8 \uC751\uB2F5\uC774 \uC2A4\uD0A4\uB9C8\uB97C \uBC97\uC5B4\uB098 \uAE30\uC874 \uCE90\uC2DC\uB97C \uC720\uC9C0\uD55C\uB2E4");
+        return;
+      }
+      await this.setEntry({
+        version: parsed.version,
+        etag: result.etag,
+        fetchedAt: now,
+        maxDisplay: parsed.maxDisplay,
+        hints: parsed.hints,
+        failedAt: null
+      });
+      return;
+    }
+    if (result.kind === "not-modified") {
+      if (this.entry !== null) {
+        await this.setEntry({ ...this.entry, fetchedAt: now, failedAt: null });
+      }
+      return;
+    }
+    if (result.permanent === true) {
+      this.permanentlyFailed = true;
+    }
+    if (!this.warnedFailure && detectDevBuild()) {
+      this.warnedFailure = true;
+      this.warn(
+        result.permanent === true ? "feedback-kit: \uD78C\uD2B8 \uC694\uCCAD\uC774 \uAC70\uBD80\uB410\uB2E4(401/403) \u2014 \uC774 \uC138\uC158\uC5D0\uC11C\uB294 \uB2E4\uC2DC \uC2DC\uB3C4\uD558\uC9C0 \uC54A\uB294\uB2E4" : "feedback-kit: \uD78C\uD2B8 \uC694\uCCAD\uC774 \uC2E4\uD328\uD588\uB2E4 \u2014 \uC7A0\uC2DC \uB4A4 \uB2E4\uC2DC \uC2DC\uB3C4\uD55C\uB2E4"
+      );
+    }
+    const base = this.entry ?? {
+      version: null,
+      etag: null,
+      fetchedAt: 0,
+      maxDisplay: HINT_DISPLAY_DEFAULT,
+      hints: [],
+      failedAt: null
+    };
+    await this.setEntry({ ...base, failedAt: now });
+  }
+  async fetchWithTimeout(etag) {
+    if (this.source === null) return { kind: "fail" };
+    const g = globalThis;
+    const controller = typeof g.AbortController === "function" ? new g.AbortController() : null;
+    try {
+      return await withTimeout(
+        this.source.fetchHints(etag, controller?.signal),
+        HINT_TIMEOUT_MS,
+        () => controller?.abort()
+      );
+    } catch {
+      return { kind: "fail" };
+    }
+  }
+  async setEntry(entry) {
+    this.entry = entry;
+    if (this.storage === null) return;
+    try {
+      await this.storage.set(this.storageKey, JSON.stringify(entry));
+    } catch (err) {
+      this.warn(`feedback-kit: \uD78C\uD2B8 \uCE90\uC2DC\uB97C \uC800\uC7A5\uD558\uC9C0 \uBABB\uD588\uB2E4(${String(err)})`);
+    }
+  }
+};
+function withTimeout(promise, ms, onTimeout) {
+  return new Promise((resolve, reject) => {
+    const g = globalThis;
+    let settled = false;
+    const timer = typeof g.setTimeout === "function" ? g.setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      onTimeout?.();
+      reject(new Error("feedback-kit: hint fetch timed out"));
+    }, ms) : null;
+    const clear = () => {
+      if (timer !== null && typeof g.clearTimeout === "function") g.clearTimeout(timer);
+    };
+    promise.then(
+      (value) => {
+        if (settled) return;
+        settled = true;
+        clear();
+        resolve(value);
+      },
+      (err) => {
+        if (settled) return;
+        settled = true;
+        clear();
+        reject(err);
+      }
+    );
+  });
+}
+function parseCacheEntry(value) {
+  if (typeof value !== "object" || value === null) return null;
+  const obj = value;
+  if (!Array.isArray(obj.hints)) return null;
+  if (typeof obj.fetchedAt !== "number") return null;
+  if (typeof obj.maxDisplay !== "number") return null;
+  return {
+    version: typeof obj.version === "number" ? obj.version : null,
+    etag: typeof obj.etag === "string" ? obj.etag : null,
+    fetchedAt: obj.fetchedAt,
+    maxDisplay: obj.maxDisplay,
+    hints: obj.hints,
+    failedAt: typeof obj.failedAt === "number" ? obj.failedAt : null
   };
 }
 export {
@@ -2319,6 +2893,16 @@ export {
   FLOATING_BUTTON_ID,
   FeedbackQueue,
   FocusRing,
+  HINT_DISPLAY_DEFAULT,
+  HINT_DISPLAY_MAX,
+  HINT_DISPLAY_MIN,
+  HINT_DRAFT_MAX_CHARS,
+  HINT_FAIL_COOLDOWN_MS,
+  HINT_LABEL_MAX_CHARS,
+  HINT_MAX_ITEMS,
+  HINT_TIMEOUT_MS,
+  HINT_TTL_MS,
+  HintProvider,
   KEEPALIVE_BODY_LIMIT_BYTES,
   LASSO_DEFAULT_ENDPOINT,
   LOG_BUFFER_LIMIT,
@@ -2327,6 +2911,7 @@ export {
   MAX_QUEUE_ITEMS,
   MODAL_ACTION_ATTACH,
   MODAL_ACTION_CANCEL,
+  MODAL_ACTION_HINT_TOGGLE,
   MODAL_ACTION_PICK,
   MODAL_ACTION_PIN,
   MODAL_ACTION_REMOVE_SCREENSHOT,
@@ -2340,6 +2925,9 @@ export {
   REDACTED,
   ReportModalController,
   RingBuffer,
+  SCORE_ELEMENT,
+  SCORE_PATH_EXACT,
+  SCORE_PATH_PATTERN,
   SCREENSHOT_FAILED_MESSAGE,
   SCREENSHOT_MAX_BASE64_BYTES,
   SCREENSHOT_QUALITY_STEPS,
@@ -2349,6 +2937,7 @@ export {
   SUBMIT_PENDING_MESSAGE,
   TITLE_MAX_CHARS,
   WidgetController,
+  appPathFromNav,
   buildContext,
   buildLassoContext,
   buildLassoEnvelope,
@@ -2366,10 +2955,15 @@ export {
   diagnosticsProviderFor,
   getOrCreateGuestId,
   guestUser,
+  hintCharCount,
   isInternalUser,
+  matchElement,
+  matchPath,
   normalizePin,
   normalizeUser,
+  parseHintCatalog,
   parseSourceAttr,
+  rankHints,
   renderReportBody,
   resolveConfig,
   resolveContextUser,