@solhun/feedback-kit-core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1234 @@
+/** 제보 종류. `report`=일반 의견, `annotation`=화면 위 핀 찍힌 주석. */
+type FeedbackKind = "report" | "annotation";
+/**
+ * 우선순위.
+ * - unset: 사용자가 고르지 않음(기본)
+ * - normal / high / urgent: 사용자가 명시적으로 선택
+ */
+type FeedbackPriority = "unset" | "normal" | "high" | "urgent";
+/** 스크린샷 캡처 결과. base64 인코딩된 이미지 데이터 + MIME. 없으면 null. */
+interface FeedbackScreenshot {
+    base64: string;
+    contentType: "image/png" | "image/jpeg";
+}
+/**
+ * 핀 좌표. 스크린샷 이미지 기준 0~1 정규화 실수.
+ * (0,0)=좌상단, (1,1)=우하단. 핀이 없으면 null.
+ */
+interface FeedbackPin {
+    x: number;
+    y: number;
+}
+/** 핀이 찍힌 DOM/RN 요소 정보(선택). 호스트가 채워 넣는다. */
+interface ElementInfo {
+    tag: string;
+    id: string | null;
+    className: string | null;
+    /** 잘린 가시 텍스트(너무 길면 자른다). */
+    text: string | null;
+    /** 뷰포트/스크린샷 기준 bounding box. 알 수 없으면 null. */
+    boundingBox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    /** 기타 속성. 값은 문자열로 직렬화한다. */
+    attributes: Record<string, string>;
+    /**
+     * 요소를 다시 찾기 위한 CSS 선택자 경로(웹 전용). 앱처럼 DOM 이 없는 곳은 생략한다.
+     * 선택 필드로 둔 이유: 이 값을 못 구해도 제보 자체는 성립해야 하기 때문이다.
+     */
+    selector?: string | null;
+}
+/**
+ * 호스트가 `getUser` 로 넘기는 제보자 신원.
+ * id는 필수(게스트면 영구 게스트 식별자). 나머지는 선택.
+ */
+interface FeedbackUser {
+    id: string;
+    name?: string;
+    email?: string;
+    role?: string;
+    /** 로그인 사용자가 아니라 게스트면 true. 생략하면 로그인 사용자로 본다. */
+    isGuest?: boolean;
+}
+/**
+ * 제보에 실제로 실리는, 해석이 끝난 사용자.
+ *
+ * **게스트도 객체를 채운다** — `isGuest: true` + 기기에 영구 저장된 게스트 식별자.
+ * 전체가 `null`인 경우는 게스트 식별자조차 아직 없는 최초 실행 순간뿐이다
+ * (저장소 접근이 실패해 id를 만들지도 읽지도 못한 상태).
+ */
+interface ContextUser {
+    id: string | null;
+    email: string | null;
+    isGuest: boolean;
+    name?: string;
+    role?: string;
+}
+/**
+ * 빌드 플러그인이 심는 화면↔소스파일 매핑. 후속 wave에서 채워진다.
+ * 코어는 통과만 한다(값을 해석하지 않는다).
+ */
+interface SourceMapping {
+    screenId: string | null;
+    sourceFile: string | null;
+    /**
+     * 소스 파일 안의 줄 번호(선택).
+     *
+     * 요소 단위 매핑(빌드 플러그인이 심는 `data-fk-source`)에서만 채워진다.
+     * 화면 단위 매핑에는 줄 번호가 없으므로 생략되거나 null 이다.
+     */
+    sourceLine?: number | null;
+}
+/**
+ * 네트워크 기록 1건.
+ *
+ * 기록 항목은 **메서드·URL·상태코드·소요시간까지**다.
+ * `Authorization` 헤더·쿠키·요청 본문·응답 본문은 어떤 경우에도 담기지 않는다
+ * (수집 코드가 애초에 읽지 않는다 — 필드가 없는 게 아니라 접근 자체를 안 한다).
+ */
+interface DiagNetworkEntry {
+    method: string;
+    /** 쿼리스트링의 자격증명형 파라미터는 값이 가려진 상태. */
+    url: string;
+    /** 응답을 못 받았으면(네트워크 실패·중단) null. */
+    status: number | null;
+    durationMs: number;
+    /** 기록 시각(ISO 8601). */
+    at: string;
+}
+/** 콘솔 기록 1건. `console.warn` / `console.error` 만 대상. */
+interface DiagLogEntry {
+    level: "warn" | "error";
+    message: string;
+    at: string;
+}
+/**
+ * 제보에 실리는 진단 스냅샷.
+ *
+ * 두 배열은 **수집기가 실제로 모은 결과**다. 제출 시점에 비어 있는 것은 정상이고
+ * (그 세션에 요청·경고가 없었다는 뜻), 배선이 안 됐을 때는 배열이 아니라
+ * 컨텍스트의 `diagnostics` 자체가 `null`이 된다. 그래서 "빈 배열"과
+ * "수집 안 함"이 페이로드에서 구분된다.
+ */
+interface DiagnosticsPayload {
+    network: DiagNetworkEntry[];
+    logs: DiagLogEntry[];
+}
+/** 앱 빌드 정보. 어느 빌드에서 났는지 특정하는 데 쓴다. */
+interface AppInfo {
+    version: string | null;
+    channel: string | null;
+    updateId: string | null;
+    runtimeVersion: string | null;
+}
+/** 기기 정보. **화면 크기는 여기가 아니라 `display` 다.** */
+interface DeviceInfo {
+    model: string | null;
+    osName: string | null;
+    osVersion: string | null;
+    deviceType: string | null;
+}
+/** 화면 크기/배율. */
+interface DisplayInfo {
+    width: number | null;
+    height: number | null;
+    pixelRatio: number | null;
+    fontScale: number | null;
+}
+/** 앱(React Native) 전용 컨텍스트. */
+interface NativeContext {
+    /** 화면↔파일 매핑이 있을 때의 소스 파일 경로. 매핑이 없으면 null. */
+    screenPath: string | null;
+    /** 전체 라우트 스택. 바깥(루트)부터 안쪽(현재 화면) 순서. */
+    navPath: string[];
+    /** 현재 화면의 파라미터. JSON 왕복으로 함수·순환참조를 제거한 값. */
+    routeParams: Record<string, unknown> | null;
+    appInfo: AppInfo;
+    device: DeviceInfo;
+    display: DisplayInfo;
+}
+/** 웹 전용 컨텍스트. */
+interface WebContext {
+    viewport: {
+        width: number | null;
+        height: number | null;
+        devicePixelRatio: number | null;
+    };
+    /** userAgent 원문(파싱하지 않고 그대로 싣는다). */
+    userAgent: string | null;
+}
+/**
+ * 제보가 만들어진 환경 컨텍스트. 사용자 신원(user)도 여기에 포함된다.
+ * (FeedbackReport의 8개 스펙 필드를 건드리지 않고 신원을 전달하기 위해 context 안에 둔다.)
+ *
+ * 이 타입은 **수집까지**를 정의한다. 여기 담긴 값을 어느 필드에 실어 보낼지는
+ * 어댑터가 정한다(코어는 특정 어댑터의 필드명을 모른다).
+ */
+interface FeedbackContext {
+    /** 앱/제품 식별자. config.app에서 온다. */
+    app: string;
+    /** 현재 화면 이름/경로(navigationRef에서 채움). 없으면 null. */
+    screen: string | null;
+    /** 현재 URL(웹) 또는 딥링크(앱). 없으면 null. */
+    url: string | null;
+    /** 세션 식별자(UUID). 위젯 인스턴스 단위로 하나. */
+    sessionId: string;
+    /** 제출 시점에 결정된 사용자. 게스트도 객체를 채운다. */
+    user: ContextUser | null;
+    /** 빌드 플러그인 매핑(선택). 없으면 screenId/sourceFile 이 null. */
+    source: SourceMapping;
+    /** 실행 플랫폼. */
+    platform: "web" | "native" | "unknown";
+    /** IANA 타임존 이름(예: `Asia/Seoul`). 알 수 없으면 null. */
+    timezone: string | null;
+    /** 클라이언트 기준 제출 시각(ISO 8601). */
+    clientTimestamp: string;
+    /** 앱 전용 컨텍스트. 웹이거나 공급자가 없으면 null. */
+    native: NativeContext | null;
+    /** 웹 전용 컨텍스트. 앱이거나 공급자가 없으면 null. */
+    web: WebContext | null;
+    /** 진단 링버퍼 스냅샷. 수집이 배선되지 않았으면 null. */
+    diagnostics: DiagnosticsPayload | null;
+    /** 자유 형식 추가 메타. 직렬화 가능한 값만. */
+    extra: Record<string, unknown>;
+}
+/**
+ * 하나의 피드백 제보. 통합 계약의 핵심.
+ * clientSubmissionId / context / createdAt 은 코어가 채운다.
+ * 나머지는 호스트가 submit() 호출 시 제공한다.
+ */
+interface FeedbackReport {
+    /** 클라이언트에서 만든 UUID v4. 멱등 키(중복 제출 식별용). */
+    clientSubmissionId: string;
+    kind: FeedbackKind;
+    comment: string;
+    priority: FeedbackPriority;
+    screenshot: FeedbackScreenshot | null;
+    pin: FeedbackPin | null;
+    element: ElementInfo | null;
+    context: FeedbackContext;
+    /** 제출 시각(ISO 8601). */
+    createdAt: string;
+}
+/**
+ * 어댑터 제출 결과.
+ * - ok: 백엔드가 정상 수락. **HTTP 2xx 만으로는 부족하다** — 응답 본문의 `ok=true`까지
+ *   확인한 뒤에만 true 여야 한다(2xx + ok=false 는 실패로 취급).
+ * - id: 백엔드가 부여한 제보 id(수락 안 됐으면 null). 표시용이며 로컬 키로 쓰지 않는다.
+ * - retryable: 일시적 실패면 true(코어가 재시도).
+ * - retryAfterMs: 백엔드가 권장한 대기 시간. 없으면 null(코어가 백오프로 계산).
+ * - rateLimited: 429(요청 한도 초과)면 true. 재시도 간격의 일반 상한(5분)을 넘겨
+ *   최소 10분 뒤에 다시 시도해야 한다는 신호. 정책 판단은 코어가 한다
+ *   (어댑터는 "429였다"는 사실만 전달한다).
+ */
+interface SubmitResult {
+    ok: boolean;
+    id: string | null;
+    retryable: boolean;
+    retryAfterMs: number | null;
+    rateLimited?: boolean;
+}
+/**
+ * 영속 저장소 인터페이스. 코어는 인터페이스만 안다.
+ * - web: localStorage 구현 제공
+ * - native: AsyncStorage 구현 제공
+ * 큐/게스트 식별자가 이 저장소에 의존한다 → 저장소를 바꿔도 동작이 동일(TC4).
+ */
+interface FeedbackStorage {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+/** 제보를 수집 백엔드로 보내는 어댑터. 호스트(또는 SDK)가 구현. */
+interface FeedbackAdapter {
+    submit(report: FeedbackReport): Promise<SubmitResult>;
+}
+/** 제출 시점에 호출돼 사용자를 반환. 동기/비동기 모두 허용. */
+type GetUserFn = () => FeedbackUser | Promise<FeedbackUser>;
+/** 현재 화면(라우트/스크린 이름)을 반환. 없으면 null. */
+type GetCurrentScreenFn = () => string | null;
+/**
+ * 진단 버퍼가 요청을 캡처할지 결정하는 매처.
+ * true 반환 = 이 요청은 캡처에서 제외(예: 위젯 자신의 전송 요청).
+ */
+interface DiagRequestRef {
+    url: string;
+    method: string;
+}
+type DiagnosticsExcludeMatcher = (req: DiagRequestRef) => boolean;
+
+/**
+ * 웹 공급자가 돌려주는 원자료.
+ * 모든 칸이 선택이다 — 못 구한 값은 빼면 되고, 코어가 null 로 채운다.
+ */
+interface WebContextInput {
+    viewport?: {
+        width?: number | null;
+        height?: number | null;
+        devicePixelRatio?: number | null;
+    };
+    userAgent?: string | null;
+}
+/** 앱/웹 컨텍스트를 채우는 공급자 묶음. 전부 선택이다. */
+interface ContextProviders {
+    /** 현재 URL(웹) 또는 딥링크(앱). */
+    getUrl?: () => string | null;
+    /** 라우트 스택. 바깥(루트)부터 안쪽(현재 화면) 순서. */
+    getNavPath?: () => string[] | null;
+    /** 현재 화면 파라미터 원본. JSON 왕복으로 정제해서 싣는다. */
+    getRouteParams?: () => unknown;
+    /** 앱 빌드 정보(version/channel/updateId/runtimeVersion). */
+    getAppInfo?: () => Partial<AppInfo> | null;
+    /** 기기 정보(model/osName/osVersion/deviceType). */
+    getDevice?: () => Partial<DeviceInfo> | null;
+    /** 화면 크기·배율(width/height/pixelRatio/fontScale). */
+    getDisplay?: () => Partial<DisplayInfo> | null;
+    /** 웹 뷰포트·userAgent. */
+    getWebContext?: () => WebContextInput | null;
+    /**
+     * 진단 스냅샷 공급자.
+     * 주지 않으면 `diagnostics` 는 **빈 배열이 아니라 null** 이다
+     * (수집이 배선되지 않았다는 뜻과 "그 세션에 아무 일도 없었다"는 뜻을 구분한다).
+     */
+    getDiagnostics?: () => DiagnosticsPayload | null;
+    /** 화면 이름 → 소스 파일 경로. 빌드 플러그인이 생성한다. 없으면 screenPath: null. */
+    screenSourceMap?: Record<string, string> | null;
+    /** 타임존 결정(테스트 주입용). 없으면 Intl 로 알아낸다. */
+    getTimezone?: () => string | null;
+}
+interface BuildContextOpts extends ContextProviders {
+    app: string;
+    sessionId: string;
+    storage: FeedbackStorage;
+    platform: FeedbackContext["platform"];
+    /** 제출 시점 사용자 결정. 없으면 게스트. */
+    getUser?: GetUserFn;
+    /** 현재 화면 이름. 없거나 null 반환 → screen: null. */
+    getCurrentScreen?: GetCurrentScreenFn;
+    /** 빌드 플러그인 매핑. 없으면 screenId/sourceFile 이 null. */
+    source?: SourceMapping;
+    /** 자유 메타. 기본 {}. */
+    extra?: Record<string, unknown>;
+    /** 시간 주입(테스트용). */
+    now?: () => number;
+    iso?: (n: number) => string;
+}
+/**
+ * getUser prop을 **제출 시점에** 호출해 사용자를 결정한다(캐싱하지 않는다).
+ * - getUser 없음 → 게스트(기기에 영구 저장된 id).
+ * - getUser 는 있지만 빈 결과/예외 → 게스트 폴백(제보 자체는 잃지 않는다).
+ * - getUser 결과에 id 있음 → 그대로 사용.
+ *
+ * 게스트도 `isGuest: true` 로 **객체를 채운다**. 반환이 null 인 경우는 저장소 접근이
+ * 실패해 게스트 식별자조차 만들지 못한 최초 실행 순간뿐이다.
+ */
+declare function resolveContextUser(getUser: GetUserFn | undefined, storage: FeedbackStorage): Promise<ContextUser | null>;
+/** 호스트가 준 FeedbackUser 를 제보에 실리는 ContextUser 로 정규화한다. */
+declare function normalizeUser(u: FeedbackUser): ContextUser;
+/** FeedbackReport.context 를 조립한다. 사용자·화면·기기·진단 수집을 모두 포함. */
+declare function buildContext(opts: BuildContextOpts): Promise<FeedbackContext>;
+
+/** 호스트가 submit() 호출 시 넘기는 부분 데이터. 계약의 나머지는 코어가 채운다. */
+interface ReportParts {
+    kind: FeedbackKind;
+    comment: string;
+    priority: FeedbackPriority;
+    screenshot: FeedbackScreenshot | null;
+    pin: FeedbackPin | null;
+    element: ElementInfo | null;
+}
+/** 제보 조립 옵션. 컨텍스트 조립 옵션과 동일하다(제보 쪽에 추가 입력이 없다). */
+type BuildReportOpts = BuildContextOpts;
+/**
+ * 부분 데이터 + 옵션으로 FeedbackReport 하나를 만든다.
+ * clientSubmissionId(UUID)와 createdAt(ISO)은 매 호출마다 새로 생성.
+ */
+declare function buildReport(parts: ReportParts, opts: BuildReportOpts): Promise<FeedbackReport>;
+
+/** 대기 큐 최대 길이. 넘치면 오래된 것부터 버린다. */
+declare const MAX_QUEUE_ITEMS = 50;
+/** 대기 큐 최대 보관 기간(ms). 7일. */
+declare const MAX_QUEUE_AGE_MS: number;
+/** 백오프 시작 간격(ms). */
+declare const BACKOFF_BASE_MS: number;
+/** 백오프 상한(ms). 429 는 이 상한의 예외다. */
+declare const BACKOFF_MAX_MS: number;
+/** 429 를 받았을 때의 최소 대기(ms). 상한 5분을 넘겨 잡는다. */
+declare const RATE_LIMIT_MIN_DELAY_MS: number;
+/** UI 가 구독하는 전송 상태. */
+interface QueueStatus {
+    /** idle=대기 중 제보 없음, sending=전송 중, pending=대기 중(연결되면 자동 전송). */
+    state: "idle" | "sending" | "pending";
+    /** 대기 중인 제보 수. */
+    pending: number;
+    /** 마지막 실패 요약(사용자 노출용 아님, 개발자 진단용). 성공/초기엔 null. */
+    lastError: string | null;
+}
+/** `submit()` 한 건의 결과. */
+interface SubmitOutcome {
+    /** 서버가 수락(2xx + ok=true)했는가. */
+    delivered: boolean;
+    /** 서버가 부여한 id(표시용). 수락 전이면 null. */
+    id: string | null;
+    /** 아직 큐에 남아 있는가(=나중에 자동 재전송). */
+    queued: boolean;
+}
+type QueueStatusListener = (status: QueueStatus) => void;
+interface FeedbackQueueOpts {
+    storage: FeedbackStorage;
+    adapter: FeedbackAdapter;
+    /** 주기적 flush 간격(ms). 기본 30000. 0/음수면 주기 flush 를 끈다. */
+    flushIntervalMs?: number;
+    /** 시각 주입(테스트용). */
+    now?: () => number;
+    /** 백오프 계산 주입(테스트용). */
+    backoff?: (attempts: number, retryAfterMs: number | null, rateLimited: boolean) => number;
+    /**
+     * 개발자 콘솔 경고 싱크. 기본은 `console.warn`.
+     * 진단 버퍼가 콘솔을 패치한 환경에서는 원본 콘솔(`DiagnosticsCollector.originalConsole.warn`)을
+     * 넘겨 위젯 자신의 경고가 다시 수집되는 되먹임을 막는다.
+     */
+    warn?: (...a: unknown[]) => void;
+}
+/**
+ * 지수 백오프 계산.
+ * - 429(rateLimited)면 상한 예외: `max(10분, 서버 권장)`.
+ * - 서버가 `retryAfterMs` 를 줬으면 그것을 쓰되 5분으로 자른다.
+ * - 아니면 5초 * 2^(attempts-1), 상한 5분.
+ *
+ * attempts=10 이면 5s*2^9 = 2560s 지만 상한에 걸려 정확히 5분이다(연속 실패해도 간격이
+ * 5분을 넘지 않는다).
+ */
+declare function defaultBackoff(attempts: number, retryAfterMs: number | null, rateLimited?: boolean): number;
+declare class FeedbackQueue {
+    private storage;
+    private adapter;
+    private flushIntervalMs;
+    private now;
+    private backoff;
+    private warn;
+    /**
+     * 저장소 접근 직렬화 체인.
+     *
+     * 왜 필요한가: `load → 수정 → save` 사이에 다른 경로가 끼어들면 그 사이 쓰기가 통째로
+     * 사라진다(flush 가 [A]를 읽는 동안 enqueue 가 [A,B]를 저장 → flush 가 []를 저장 →
+     * B 유실). 단순한 `flushing` 불리언은 재진입을 "무시"할 뿐이라 이 경합을 못 막고,
+     * 무시된 flush 를 기다리던 `submit()` 이 자기 전송을 await 할 수도 없다.
+     */
+    private chain;
+    /** 아직 시작하지 않은 flush 요청(있으면 재사용해서 타이머 연타를 합친다). */
+    private queuedFlush;
+    private timer;
+    private onlineHandler;
+    private pending;
+    private sending;
+    private lastError;
+    private listeners;
+    /** 제출 단위 결과 캐시. `submit()` 이 자기 건의 결말을 알아내는 데 쓴다. */
+    private outcomes;
+    constructor(opts: FeedbackQueueOpts);
+    /**
+     * 제보를 큐에 넣고 전송을 시도한 뒤, 그 한 건의 결말을 돌려준다.
+     * 실패해도 예외를 던지지 않는다 — 제보는 큐에 남고 `queued: true` 로 알린다.
+     */
+    submit(report: FeedbackReport): Promise<SubmitOutcome>;
+    /** 큐에 제보를 추가하고, 전송을 백그라운드로 시도한다. */
+    enqueue(report: FeedbackReport): Promise<void>;
+    /**
+     * 만기된 큐 항목들을 한 건씩 순서대로 전송한다.
+     * 이미 진행 중이면 그 뒤에 한 번만 예약해 붙는다(타이머 연타로 flush 가 쌓이지 않는다).
+     */
+    flush(): Promise<void>;
+    /**
+     * 지금 즉시 재시도한다. 네트워크 복귀·앱 포그라운드 복귀·[다시 보내기] 용.
+     * 백오프 대기를 앞당기되, **429 로 묶인 항목은 앞당기지 않는다**(서버가 명시한 한도라
+     * 무시하면 다시 429 만 받는다).
+     */
+    retryNow(): Promise<void>;
+    /** 현재 큐 길이(대기 중 제보 수). 검증/진단용. */
+    size(): Promise<number>;
+    /** 현재 전송 상태 스냅샷. */
+    getStatus(): QueueStatus;
+    /** 특정 clientSubmissionId의 마지막 확정 결말. 큐에 있거나 아직 시도 전이면 null이다. */
+    getOutcome(clientSubmissionId: string): Pick<SubmitOutcome, "delivered" | "id"> | null;
+    /** 전송 상태 구독. 반환값을 호출하면 해지된다. 구독 즉시 현재 상태를 1회 통지한다. */
+    subscribe(listener: QueueStatusListener): () => void;
+    /**
+     * 마운트 시 호출. 만기 항목 정리 + 즉시 재시도 + 주기 flush + `online` 재시도를 건다.
+     * 앱(RN)에는 `online` 이벤트가 없으므로, 호스트가 포그라운드 복귀 시 `retryNow()` 를
+     * 직접 부른다(코어는 플랫폼 API 를 모른다).
+     */
+    start(): void;
+    /** 타이머와 이벤트 구독을 해제한다. 큐 내용은 그대로 남는다. */
+    stop(): void;
+    private enqueueInner;
+    private doFlush;
+    /** 어댑터 호출. 어댑터가 예외를 던져도 결과값으로 흡수한다(전송 보장 우선). */
+    private submitOne;
+    private load;
+    /**
+     * 큐를 저장한다. 저장소 한도(쿼터)에 걸리면 **스크린샷부터** 떼어내고, 그래도 안 되면
+     * 가장 오래된 제보를 버린다. 사용자가 쓴 글이 스크린샷보다 우선이다.
+     * 인자로 받은 배열을 제자리에서 수정한다(호출부가 들고 있는 항목 참조는 유지된다).
+     */
+    private persist;
+    /** 7일이 지난 항목을 걸러낸다. 만기 항목은 전송을 시도하지 않는다. */
+    private purgeExpired;
+    private recordOutcome;
+    private setPending;
+    private emit;
+    private serialize;
+}
+
+/** `fetch` keepalive 요청 본문 한도(바이트). Fetch 표준의 inflight keepalive quota. */
+declare const KEEPALIVE_BODY_LIMIT_BYTES: number;
+/**
+ * 이 본문을 keepalive 로 보내도 되는지.
+ * @param bodyByteLength 직렬화된 요청 본문의 바이트 수.
+ */
+declare function canUseKeepalive(bodyByteLength: number): boolean;
+/**
+ * 문자열 본문의 UTF-8 바이트 수. `TextEncoder` 가 없으면(구형 RN 등) 보수적으로
+ * 근사한다 — 근사는 항상 실제보다 크거나 같게 잡아 한도를 넘겨 켜는 일이 없게 한다.
+ */
+declare function byteLengthOf(body: string): number;
+
+declare class RingBuffer<T> {
+    /** 보관 상한. 0 이하/비정상 값이면 0(아무것도 담지 않음)으로 떨어진다. */
+    readonly capacity: number;
+    private items;
+    constructor(capacity: number);
+    push(item: T): void;
+    /** 현재 내용의 복사본. 호출자가 들고 있어도 이후 push 에 영향받지 않는다. */
+    toArray(): T[];
+    get size(): number;
+    clear(): void;
+}
+
+/** 네트워크 링버퍼 용량. 넘치면 오래된 것부터 밀려난다. */
+declare const NETWORK_BUFFER_LIMIT = 30;
+/** 콘솔 로그(warn/error) 링버퍼 용량. 넘치면 오래된 것부터 밀려난다. */
+declare const LOG_BUFFER_LIMIT = 50;
+/** 로그 한 건의 최대 길이. 스택 덤프 하나가 버퍼를 통째로 먹는 걸 막는다. */
+declare const MAX_LOG_MESSAGE_CHARS = 2000;
+interface DiagnosticsInstallOpts {
+    /** true 를 반환하면 그 요청은 기록하지 않는다(위젯 자신의 전송 등). */
+    excludeMatcher?: DiagnosticsExcludeMatcher;
+    /** 시각 주입(테스트용). */
+    now?: () => number;
+    iso?: (n: number) => string;
+}
+/**
+ * 진단 수집기. `install()` 로 글로벌을 패치하고 `uninstall()` 로 원복한다.
+ * 생성 자체는 부작용이 없다 — `install()` 을 호출해야 패치가 일어난다.
+ */
+declare class DiagnosticsCollector {
+    readonly network: RingBuffer<DiagNetworkEntry>;
+    readonly logs: RingBuffer<DiagLogEntry>;
+    private installed;
+    private originalFetch;
+    private originalXhrOpen;
+    private originalXhrSend;
+    private originalWarn;
+    private originalError;
+    private excludeMatcher;
+    private now;
+    private iso;
+    /**
+     * 패치된 fetch 안에서 동기적으로 XHR 이 열리는 깊이.
+     *
+     * React Native 의 `fetch` 는 whatwg-fetch 폴리필이라 내부에서 XMLHttpRequest 를 쓴다.
+     * 둘 다 패치해두면 요청 1건이 2건으로 기록된다. fetch 폴리필은 Promise 실행자 안에서
+     * **동기적으로** `send()` 를 부르므로, 그 구간을 세어 XHR 쪽 기록만 건너뛴다.
+     */
+    private fetchDepth;
+    constructor(opts?: {
+        now?: () => number;
+        iso?: (n: number) => string;
+        networkLimit?: number;
+        logLimit?: number;
+    });
+    /** 위젯이 자신의 로그를 캡처 없이 찍을 때 쓰는 원본 console. */
+    readonly originalConsole: {
+        warn: (...a: unknown[]) => void;
+        error: (...a: unknown[]) => void;
+        log: (...a: unknown[]) => void;
+    };
+    /** 글로벌 fetch/XHR/console 을 패치한다. 이미 설치했으면 no-op. */
+    install(opts?: DiagnosticsInstallOpts): void;
+    /** 글로벌 패치를 모두 원복한다. 버퍼 내용은 그대로 남는다. */
+    uninstall(): void;
+    /**
+     * 지금까지 모인 것을 그대로 스냅샷으로 낸다.
+     * 반환 배열은 사본이라 이후 수집이 제보 페이로드를 바꾸지 않는다.
+     */
+    snapshot(): DiagnosticsPayload;
+    /** 두 버퍼를 비운다. */
+    clear(): void;
+    private recordNetwork;
+    private recordLog;
+    private isExcluded;
+    private patchFetch;
+    private patchXhr;
+    private patchConsole;
+}
+/**
+ * 모듈 스코프 공유 수집기.
+ *
+ * 화면·컴포넌트마다 수집기를 연결할 필요가 없어야 한다는 요구사항 때문에 여기 하나를 둔다.
+ * 위젯이 어느 화면에서 열리든 이 인스턴스의 스냅샷을 싣는다.
+ */
+declare const sharedDiagnostics: DiagnosticsCollector;
+/** 가려진 값 표시. 파라미터가 "있었다"는 사실은 남기고 값만 지운다. */
+declare const REDACTED = "REDACTED";
+/**
+ * URL 에서 자격증명을 걷어낸다.
+ * - `#fragment` 는 통째로 버린다(진단 가치는 없고 토큰이 실리는 경우가 있다).
+ * - `scheme://user:pass@host` 의 userinfo 를 지운다.
+ * - 자격증명형 쿼리 파라미터의 **값만** `REDACTED` 로 바꾼다.
+ */
+declare function sanitizeUrl(raw: string): string;
+
+/** 노출 판정에 쓰이는 현재 상황. 함수형 `visibility` 가 그대로 받는다. */
+interface VisibilityEnv {
+    /** 현재 사용자. 로그인 전이면 게스트이거나 null. */
+    user: ContextUser | FeedbackUser | null;
+    /** 개발 빌드 여부. */
+    isDev: boolean;
+    platform: "web" | "native" | "unknown";
+}
+/** 프로젝트가 직접 판정하는 형태. true 면 노출. */
+type VisibilityFn = (env: VisibilityEnv) => boolean;
+/**
+ * 누구에게 위젯을 노출할지.
+ *
+ * 기본값은 `all` 이다. 실사용자 제보가 실제로 가치를 냈기 때문에 패키지가 먼저 막지
+ * 않는다. 좁혀야 하는 프로젝트가 `internal`·`dev-only`·함수로 좁힌다.
+ */
+type Visibility = "all" | "internal" | "dev-only" | VisibilityFn;
+/** `internal` 판정의 기본 근거. 프로젝트가 `internalRoles` 로 갈아끼운다. */
+declare const DEFAULT_INTERNAL_ROLES: readonly string[];
+type WidgetCorner = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+interface WidgetPosition {
+    corner: WidgetCorner;
+    /** 모서리로부터의 가로 여백(px). */
+    offsetX: number;
+    /** 모서리로부터의 세로 여백(px). */
+    offsetY: number;
+}
+declare const DEFAULT_POSITION: WidgetPosition;
+/** 내장 어댑터 이름. 실제 구현과 전송 규약은 어댑터 섹션이 갖는다. */
+type AdapterName = "lasso" | "linear" | "notion";
+declare const DEFAULT_ADAPTER: AdapterName;
+/**
+ * 수집 엔드포인트 기본값은 **어댑터가 갖는다.**
+ *
+ * 코어가 특정 백엔드 URL 을 상수로 들고 있으면 어댑터 교체가 무의미해지고, 코어가
+ * 어댑터별 사정을 아는 셈이 된다. 그래서 여기서는 "지정 안 함"을 `null` 로 표현하고,
+ * 어댑터가 자기 내장 기본값을 쓰도록 넘긴다.
+ */
+declare const ENDPOINT_FROM_ADAPTER: null;
+type ConfigWarningCode = 
+/** 토큰이 없다 — 전송은 되지만 미귀속이다. */
+"missing-token"
+/** 환경변수가 치환되지 않은 채로 들어왔다(빌드 설정 사고). */
+ | "unsubstituted-token"
+/** 모르는 어댑터 이름 — 기본 어댑터로 되돌린다. */
+ | "unknown-adapter"
+/** 모르는 visibility 값 — `all` 로 되돌린다. */
+ | "unknown-visibility"
+/** 모르는 위치 값 — 우하단으로 되돌린다. */
+ | "unknown-position"
+/** 사용자가 준 판정 함수가 예외를 던졌다 — 숨김으로 처리한다. */
+ | "visibility-threw";
+interface ConfigWarning {
+    code: ConfigWarningCode;
+    message: string;
+}
+interface FeedbackConfig {
+    /** 수집 토큰. 없으면 미귀속으로 전송된다(막지 않는다). */
+    token?: string | null;
+    /** 수집 엔드포인트. 없으면 어댑터 내장 기본값. */
+    endpoint?: string | null;
+    /** 어댑터 이름 또는 어댑터 구현체. */
+    adapter?: AdapterName | FeedbackAdapter;
+    /** 노출 범위. 기본 `all`. */
+    visibility?: Visibility;
+    /** 모달을 열 때 화면을 자동 캡처할지. */
+    captureScreenshot?: boolean;
+    /** network·logs 링버퍼를 수집할지. false 면 아예 설치하지 않는다. */
+    captureDiagnostics?: boolean;
+    /** 플로팅 버튼 위치. 모서리만 주면 여백은 기본값. */
+    position?: WidgetCorner | Partial<WidgetPosition>;
+    /** `internal` 판정을 프로젝트가 직접 할 때. 주면 `internalRoles` 보다 우선한다. */
+    isInternal?: VisibilityFn;
+    /** `internal` 로 볼 역할 목록. 기본 {@link DEFAULT_INTERNAL_ROLES}. */
+    internalRoles?: readonly string[];
+    /** 개발 빌드 여부. 안 주면 런타임 전역에서 추론한다. */
+    isDev?: boolean;
+    /** 경고 출구. 안 주면 `resolveConfig` 결과의 `warnings` 로만 남는다. */
+    onWarn?: (warning: ConfigWarning) => void;
+}
+/** 기본값이 모두 채워진 설정. 위젯은 이것만 본다. */
+interface ResolvedConfig {
+    token: string | null;
+    endpoint: string | null;
+    adapter: AdapterName | FeedbackAdapter;
+    visibility: Visibility;
+    captureScreenshot: boolean;
+    captureDiagnostics: boolean;
+    position: WidgetPosition;
+    isInternal: VisibilityFn | null;
+    internalRoles: readonly string[];
+    isDev: boolean;
+    warnings: ConfigWarning[];
+}
+/**
+ * 개발 빌드 여부 추론.
+ *
+ * 코어는 플랫폼 무관이라 `__DEV__`(RN)·`process.env.NODE_ENV`(웹/노드)를 **globalThis
+ * 를 통해서만** 본다. 어느 쪽도 없으면 프로덕션으로 본다 — 모르는 상태에서 개발 빌드로
+ * 단정하면 `dev-only` 가 실사용자에게 새기 때문이다.
+ */
+declare function detectDevBuild(): boolean;
+/**
+ * 부분 설정을 기본값으로 채운다.
+ *
+ * **던지지 않는다.** 설정이 틀렸다고 위젯이 호스트 앱을 깨거나 사용자 화면에 오류를
+ * 띄우면, 붙이는 비용이 한 줄이라는 전제가 무너진다. 모르는 값은 기본값으로 되돌리고
+ * 경고만 남긴다.
+ */
+declare function resolveConfig(config?: FeedbackConfig): ResolvedConfig;
+declare function isInternalUser(resolved: ResolvedConfig, env: VisibilityEnv): boolean;
+/**
+ * 지금 이 사용자에게 플로팅 버튼을 보여줄지.
+ *
+ * 판정에 실패하면(사용자가 준 함수가 던지면) **숨긴다.** 노출 범위를 좁힌 프로젝트가
+ * 있다는 건 보이면 안 되는 이유가 있다는 뜻이므로, 애매할 때 새는 쪽보다 안 보이는
+ * 쪽이 안전하다.
+ */
+declare function shouldShowWidget(resolved: ResolvedConfig, input?: Partial<VisibilityEnv>): boolean;
+/** `DiagnosticsCollector` 중 설정 배선에 필요한 최소 형태. */
+interface DiagnosticsSource {
+    install(): void;
+    snapshot(): DiagnosticsPayload;
+}
+/**
+ * `captureDiagnostics` 를 실제 배선으로 옮긴다.
+ *
+ * 꺼져 있으면 **공급자를 만들지 않고 수집기도 설치하지 않는다.** 빈 배열을 상수로
+ * 돌려주는 공급자를 만들면 "수집했는데 아무 일도 없었다"와 "애초에 수집하지 않았다"가
+ * 구분되지 않는다. 공급자가 없으면 `buildContext` 가 `diagnostics: null` 을 쓴다.
+ */
+declare function diagnosticsProviderFor(resolved: Pick<ResolvedConfig, "captureDiagnostics">, collector: DiagnosticsSource): (() => DiagnosticsPayload) | undefined;
+
+/** 빌드 플러그인이 심는 속성 이름. `data-` 라서 DOM 이 그대로 통과시킨다. */
+declare const SOURCE_ATTR = "data-fk-source";
+/** 해석된 소스 위치. */
+interface SourceLocation {
+    /** 원본 파일 경로(번들 경로가 아니다). */
+    file: string;
+    /** 1부터 시작하는 줄 번호. */
+    line: number;
+    /** 1부터 시작하는 칼럼. 없으면 null. */
+    column: number | null;
+}
+/**
+ * `"src/pages/Home.tsx:42:7"` 을 해석한다.
+ *
+ * 뒤에서부터 숫자 꼬리를 떼어낸다 — 파일 경로 자체에 콜론이 들어갈 수 있어서
+ * (윈도우 드라이브 문자 `C:\`) 앞에서부터 자르면 깨진다.
+ */
+declare function parseSourceAttr(value: unknown): SourceLocation | null;
+/**
+ * 지목된 요소에서 소스 매핑을 뽑는다.
+ *
+ * `base` 는 화면 단위 매핑(빌드 플러그인의 screen-map)이다. 요소에서 얻은 파일 경로가
+ * 더 구체적이므로 그걸 우선하고, 화면 식별자는 base 것을 유지한다.
+ */
+declare function sourceFromElement(element: Pick<ElementInfo, "attributes"> | null | undefined, base?: SourceMapping | null): SourceMapping;
+
+/** 계약상 스크린샷 상한. base64 문자열 기준 8 MiB. */
+declare const SCREENSHOT_MAX_BASE64_BYTES: number;
+/** 캡처가 불가능할 때 사용자에게 보여줄 문구. */
+declare const SCREENSHOT_FAILED_MESSAGE = "\uCEA1\uCC98 \uC2E4\uD328 \u2014 \uD30C\uC77C\uB85C \uCCA8\uBD80\uD560 \uC218 \uC788\uC2B5\uB2C8\uB2E4";
+/** 상한을 넘겼을 때 차례로 시도할 재인코딩 품질. 앞에서부터 시도하고 처음 통과하는 값을 쓴다. */
+declare const SCREENSHOT_QUALITY_STEPS: readonly number[];
+/**
+ * base64 페이로드의 바이트 수.
+ * base64 는 ASCII 라 문자 수가 곧 바이트 수다(디코딩 후 원본 크기가 아니라 전송량 기준).
+ */
+declare function screenshotBytes(shot: FeedbackScreenshot | null | undefined): number;
+type ScreenshotCapture = () => FeedbackScreenshot | null | Promise<FeedbackScreenshot | null>;
+type ScreenshotReencode = (shot: FeedbackScreenshot, quality: number) => FeedbackScreenshot | null | Promise<FeedbackScreenshot | null>;
+interface CaptureWithinLimitOpts {
+    capture: ScreenshotCapture;
+    /** 상한 초과 시 다시 인코딩하는 훅. 없으면 재인코딩 없이 바로 포기한다. */
+    reencode?: ScreenshotReencode | null;
+    qualitySteps?: readonly number[];
+    limitBytes?: number;
+}
+interface ScreenshotOutcome {
+    screenshot: FeedbackScreenshot | null;
+    /** 캡처를 끝내 얻지 못했다. 제출은 계속 가능해야 한다. */
+    failed: boolean;
+    /** 실패했을 때만 채워지는 안내 문구. */
+    message: string | null;
+    /** 품질을 낮춰 다시 인코딩한 결과인가. */
+    reencoded: boolean;
+}
+/**
+ * 캡처한 뒤 용량 상한 안으로 들여보낸다.
+ *
+ * 1. 캡처 → 실패하거나 빈 결과면 곧장 실패로 내린다.
+ * 2. 상한 이내면 그대로 쓴다.
+ * 3. 초과하면 품질을 단계별로 낮춰 재인코딩하고, 처음 통과한 결과를 쓴다.
+ * 4. 끝내 못 맞추면 스크린샷을 버리고 실패 문구로 대체한다(제출은 막지 않는다).
+ */
+declare function captureWithinLimit(opts: CaptureWithinLimitOpts): Promise<ScreenshotOutcome>;
+
+interface PixelPoint {
+    x: number;
+    y: number;
+}
+interface PixelSize {
+    width: number;
+    height: number;
+}
+/**
+ * 픽셀 좌표를 스크린샷 기준 0~1 상대 좌표로 바꾼다.
+ * 크기가 0 이하이면(아직 레이아웃 전) 나눗셈이 무의미하므로 0 으로 떨어뜨린다.
+ */
+declare function normalizePin(point: PixelPoint, size: PixelSize): FeedbackPin;
+/** 상대 좌표를 다시 픽셀로 되돌린다(마커를 그릴 때 쓴다). */
+declare function denormalizePin(pin: FeedbackPin, size: PixelSize): PixelPoint;
+/**
+ * 핀 지정 화면의 상태기계.
+ *
+ * `draft` 는 지정 화면에서 만지는 중인 값, `confirmed` 는 모달로 돌아간 확정값이다.
+ * 둘을 나눠 둔 이유는 취소했을 때 이전 확정값이 살아남아야 하기 때문이다.
+ */
+declare class PinController {
+    private confirmedPin;
+    private draftPin;
+    private opened;
+    constructor(initial?: FeedbackPin | null);
+    get isOpen(): boolean;
+    get draft(): FeedbackPin | null;
+    get confirmed(): FeedbackPin | null;
+    /** 화면에 떠 있는 핀 개수. 단일 핀 규칙이라 0 아니면 1이다. */
+    get count(): number;
+    open(): void;
+    /** 탭한 자리에 핀을 찍는다. 기존 핀이 있으면 그 자리로 옮긴다(추가가 아니다). */
+    place(point: PixelPoint, size: PixelSize): FeedbackPin;
+    /** 이미 상대 좌표를 갖고 있을 때 쓰는 경로. */
+    placeRelative(pin: FeedbackPin): FeedbackPin;
+    confirm(): FeedbackPin | null;
+    /** 취소 — 이전에 확정한 좌표로 되돌린다. */
+    cancel(): FeedbackPin | null;
+    reset(): void;
+}
+
+/** 위젯 플로팅 버튼의 고정 id. 모달을 닫으면 여기로 포커스를 되돌린다. */
+declare const FLOATING_BUTTON_ID = "feedback-kit-floating-button";
+/**
+ * 순환하는 포커스 링. 끝에서 Tab 하면 처음으로 돌아온다 = 포커스가 모달 밖으로 새지 않는다.
+ */
+declare class FocusRing {
+    private items;
+    private index;
+    constructor(items?: readonly string[]);
+    get order(): readonly string[];
+    get current(): string | null;
+    /**
+     * 항목 목록을 바꾼다. 지금 포커스된 항목이 새 목록에도 있으면 그 자리를 유지한다
+     * (스크린샷을 지웠다고 포커스가 처음으로 튀면 키보드 사용자가 길을 잃는다).
+     */
+    setItems(items: readonly string[]): void;
+    focus(id: string): boolean;
+    next(): string | null;
+    prev(): string | null;
+    contains(id: string): boolean;
+}
+
+/** 코멘트 상한. 넘으면 자르지 않고 거부한다(사용자가 쓴 글을 임의로 삭제하지 않는다). */
+declare const COMMENT_MAX_CHARS = 4000;
+declare const COMMENT_REQUIRED_MESSAGE = "\uC758\uACAC\uC744 \uC785\uB825\uD574\uC8FC\uC138\uC694";
+declare const COMMENT_TOO_LONG_MESSAGE = "4,000\uC790 \uC774\uD558\uB85C \uC785\uB825\uD574\uC8FC\uC138\uC694";
+declare const SUBMIT_DONE_MESSAGE = "\uBCF4\uB0C8\uC2B5\uB2C8\uB2E4";
+declare const SUBMIT_PENDING_MESSAGE = "\uB300\uAE30 \uC911";
+declare const SUBMIT_FAILED_MESSAGE = "\uBCF4\uB0B4\uC9C0 \uBABB\uD588\uC2B5\uB2C8\uB2E4";
+type WidgetPlatform = "web" | "native";
+type ScreenshotStatus = "none" | "capturing" | "ready" | "failed";
+type ModalSubmitStatus = "idle" | "sending" | "sent" | "pending" | "failed";
+/** 모달 안에서 포커스를 받는 요소들의 고정 id. 렌더러가 그대로 매단다. */
+declare const MODAL_FIELD_COMMENT = "comment";
+declare const MODAL_FIELD_PRIORITY = "priority";
+declare const MODAL_ACTION_ATTACH = "attach";
+declare const MODAL_ACTION_REMOVE_SCREENSHOT = "remove-screenshot";
+declare const MODAL_ACTION_PIN = "pin";
+declare const MODAL_ACTION_PICK = "pick";
+declare const MODAL_ACTION_RETRY = "retry";
+declare const MODAL_ACTION_CANCEL = "cancel";
+declare const MODAL_ACTION_SEND = "send";
+interface ReportModalState {
+    open: boolean;
+    comment: string;
+    priority: FeedbackPriority;
+    screenshot: FeedbackScreenshot | null;
+    screenshotStatus: ScreenshotStatus;
+    screenshotMessage: string | null;
+    pin: FeedbackPin | null;
+    submitStatus: ModalSubmitStatus;
+    submitMessage: string | null;
+    commentError: string | null;
+    canSubmit: boolean;
+    /** 핀 찍기를 열 수 있는가. 스크린샷이 있어야 좌표가 의미를 갖는다. */
+    canPin: boolean;
+    showRetry: boolean;
+    /** 대기 큐에 남아 있는 건수. */
+    pending: number;
+    closeConfirmVisible: boolean;
+    /** 이 플랫폼에서 노출되는 부가 동작들. 웹은 요소 지목, 앱은 핀 찍기. */
+    actions: readonly string[];
+    focusOrder: readonly string[];
+    focused: string | null;
+    /** 모달이 닫힌 뒤 포커스를 돌려줄 곳. */
+    restoreFocusTo: string | null;
+}
+/** 모달이 큐에게 요구하는 최소 계약. `FeedbackQueue` 가 그대로 만족한다. */
+interface ModalQueueLike {
+    submit(report: FeedbackReport): Promise<SubmitOutcome>;
+    retryNow(): Promise<void>;
+    size(): Promise<number>;
+    subscribe(listener: (status: QueueStatus) => void): () => void;
+    /** 현재 모달 제보만 다른 대기 항목과 구분하기 위한 제출 단위 결말. */
+    getOutcome?(clientSubmissionId: string): Pick<SubmitOutcome, "delivered" | "id"> | null;
+    /** 실제 FeedbackQueue의 online/주기 재시도 lifecycle. 테스트 대역은 생략할 수 있다. */
+    start?(): void;
+    stop?(): void;
+}
+interface ReportModalOpts {
+    queue: ModalQueueLike;
+    /** 제보 조립. 보통 `buildReport` 를 부분 적용해 넘긴다. */
+    createReport: (parts: ReportParts) => Promise<FeedbackReport>;
+    platform: WidgetPlatform;
+    /** 모달을 열 때 자동 캡처. 없으면 캡처 단계를 건너뛴다. */
+    capture?: ScreenshotCapture | null;
+    reencode?: ScreenshotReencode | null;
+    screenshotLimitBytes?: number;
+}
+type ReportModalListener = (state: ReportModalState) => void;
+declare class ReportModalController {
+    private readonly queue;
+    private readonly createReport;
+    private readonly platform;
+    private readonly capture;
+    private readonly reencode;
+    private readonly screenshotLimitBytes;
+    private readonly listeners;
+    private readonly ring;
+    private readonly unsubscribeQueue;
+    /** 사용자가 입력란을 건드렸는가. 열자마자 빨간 문구가 뜨는 걸 막으려고 둔다. */
+    private touched;
+    private submitAttempted;
+    private lastReport;
+    /** 이전 open/recapture가 늦게 끝나 최신 상태를 덮지 못하게 하는 세대 번호. */
+    private captureGeneration;
+    private state;
+    constructor(opts: ReportModalOpts);
+    getState(): ReportModalState;
+    /** 마지막으로 조립한 제보. 재시도가 같은 멱등키를 쓰는지 확인할 때 쓴다. */
+    getLastReport(): FeedbackReport | null;
+    subscribe(listener: ReportModalListener): () => void;
+    dispose(): void;
+    /** WidgetController가 소유한 큐 lifecycle을 함께 정리한다. */
+    stopQueue(): void;
+    open(): Promise<void>;
+    /**
+     * 닫기 요청. 쓰던 내용이 있으면 곧장 닫지 않고 확인을 받는다.
+     * @returns 실제로 닫혔으면 `"closed"`, 확인이 필요하면 `"confirm"`.
+     */
+    requestClose(): "closed" | "confirm";
+    /** 확인 대화에서 "닫기"를 고른 경우. */
+    confirmClose(): void;
+    /** 확인 대화에서 "계속 쓰기"를 고른 경우. 입력은 그대로 남는다. */
+    cancelClose(): void;
+    /** 확인 없이 닫는다(요소 지목 모드로 넘어갈 때처럼 흐름이 이어지는 경우). */
+    dismiss(): void;
+    private close;
+    /** 상한을 넘겨도 값을 자르지 않는다. 거부는 하되 사용자가 쓴 글은 보존한다. */
+    setComment(value: string): void;
+    setPriority(priority: FeedbackPriority): void;
+    setPin(pin: FeedbackPin | null): void;
+    /** 스크린샷 제거 — 핀은 스크린샷 위 좌표라 함께 사라진다. */
+    removeScreenshot(): void;
+    recapture(): Promise<void>;
+    /** 캡처가 실패했을 때의 대체 경로 — 사용자가 직접 고른 파일. */
+    attachFile(shot: FeedbackScreenshot): Promise<void>;
+    private runCapture;
+    private applyScreenshot;
+    tabNext(): string | null;
+    tabPrev(): string | null;
+    focus(id: string): boolean;
+    /**
+     * 제출. 실패해도 예외를 던지지 않는다 — 대기 큐에 남기고 입력을 보존한다.
+     * @returns 검증에 걸려 아무것도 보내지 않았으면 `null`.
+     */
+    submit(): Promise<SubmitOutcome | null>;
+    /** [다시 보내기]. 큐가 비면 완료로 넘어간다. */
+    retry(): Promise<void>;
+    private isCommentValid;
+    private isDraftLocked;
+    private commentErrorFor;
+    private actionsFor;
+    private focusOrderFor;
+    private recompute;
+    private patch;
+    private emit;
+}
+
+/** 위젯이 보여줄 수 있는 화면. */
+type WidgetScreen = "button" | "modal" | "pin" | "picking";
+interface WidgetControllerOpts extends ReportModalOpts {
+    /** 저장돼 있던 요소 지목 모드를 복원할 때 쓴다(새로고침·페이지 이동 후). */
+    initialPicking?: boolean;
+    /** 지목 모드가 켜지고 꺼질 때 호출. 호스트가 저장소에 기록한다. */
+    onPickingChange?: (active: boolean) => void;
+}
+interface WidgetState {
+    screen: WidgetScreen;
+    modal: ReportModalState;
+    /** 핀 지정 화면에서 만지는 중인 좌표. */
+    pinDraft: FeedbackPin | null;
+    /** 모달로 돌아간 확정 좌표. */
+    pinConfirmed: FeedbackPin | null;
+    pickingActive: boolean;
+}
+type WidgetListener = (state: WidgetState) => void;
+declare class WidgetController {
+    readonly modal: ReportModalController;
+    readonly pin: PinController;
+    private readonly platform;
+    private readonly onPickingChange;
+    private readonly listeners;
+    private readonly unsubscribeModal;
+    private screen;
+    private picking;
+    constructor(opts: WidgetControllerOpts);
+    getScreen(): WidgetScreen;
+    getState(): WidgetState;
+    get isPicking(): boolean;
+    subscribe(listener: WidgetListener): () => void;
+    dispose(): void;
+    openReport(): Promise<void>;
+    /** 모달 닫기 요청. 쓰던 내용이 있으면 확인부터 받는다(화면은 그대로 모달). */
+    closeReport(): "closed" | "confirm";
+    confirmCloseReport(): void;
+    cancelCloseReport(): void;
+    submitReport(): Promise<SubmitOutcome | null>;
+    retryReport(): Promise<void>;
+    /**
+     * 핀 지정 화면 열기. 스크린샷이 없으면 좌표가 가리킬 대상이 없으므로 열지 않는다.
+     * @returns 열렸으면 true.
+     */
+    openPinScreen(): boolean;
+    /** 핀 지정 화면에서 탭. 기존 핀이 있으면 그 자리로 옮긴다. */
+    placePin(point: PixelPoint, size: PixelSize): FeedbackPin | null;
+    /** 확정 — 모달로 돌아가고 좌표가 제출에 실린다. */
+    confirmPin(): FeedbackPin | null;
+    /** 취소 — 이전 확정 좌표를 그대로 두고 모달로 돌아간다. */
+    cancelPin(): FeedbackPin | null;
+    /**
+     * 요소 지목 모드 시작. 모달에서 넘어오는 흐름이라 닫기 확인을 묻지 않는다
+     * (사용자가 이미 "지목하러 가겠다"고 밝힌 상태다).
+     */
+    startPicking(): boolean;
+    /** [지목 종료]. 플로팅 버튼 화면으로 돌아가고 저장된 모드 표시도 지운다. */
+    stopPicking(): void;
+    private setPicking;
+    private emit;
+}
+
+/** 제목 최대 길이. 대상마다 제한이 다르지만, 한 줄로 읽히는 길이가 실질 상한이다. */
+declare const TITLE_MAX_CHARS = 80;
+/**
+ * 제보 하나를 사람이 읽는 본문으로 만든다.
+ *
+ * 형태: `사용자 코멘트` + 빈 줄 + `접힌 진단 블록 하나`.
+ * 코멘트는 **이스케이프하지 않는다** — 접힌 블록보다 앞에 있어서 우리 블록을 깨뜨릴 수 없고,
+ * 사람이 쓴 문장을 우리가 변형하는 쪽이 더 나쁘다.
+ */
+declare function renderReportBody(report: FeedbackReport): string;
+/**
+ * 제목. 코멘트 첫 줄을 쓰되, 비어 있으면 종류와 화면으로 대신한다.
+ * 제목이 비면 대상에서 목록이 읽히지 않으므로 항상 비어 있지 않은 문자열을 돌려준다.
+ */
+declare function buildTitle(report: FeedbackReport): string;
+
+/**
+ * Linear 이슈 생성 입력의 최소 형태.
+ *
+ * 필드명이 라쏘런 봉투와 다르다는 게 핵심이다 — 같은 제보라도 대상마다 이름이 다르고,
+ * 코어는 그 어느 쪽도 모른다.
+ */
+interface LinearIssueInput {
+    /** 이슈 제목. 목록에서 한 줄로 보인다. */
+    title: string;
+    /** 이슈 본문(마크다운). 대상이 못 받는 값은 전부 여기 접힌 블록으로 들어간다. */
+    description: string;
+}
+/**
+ * 제보를 Linear 이슈 입력으로 바꾼다.
+ *
+ * 본문은 공용 렌더러가 만든 것을 **그대로** 쓴다. 여기서 다시 조립하면
+ * "Linear 로 간 제보에는 소스 경로가 없다" 같은 차이가 조용히 생긴다.
+ */
+declare function buildLinearIssue(report: FeedbackReport): LinearIssueInput;
+
+/** Notion 페이지 생성 입력의 최소 형태. */
+interface NotionPageInput {
+    /** 페이지 제목 속성. */
+    title: string;
+    /**
+     * 페이지 본문(마크다운 원문).
+     *
+     * 블록 배열로 쪼개지 않는 이유: 쪼개는 규칙(어디서 문단을 나눌지, 접힌 블록을
+     * toggle 로 옮길지)은 실제 Notion API 계약이 정해진 뒤에야 의미가 있다.
+     * 지금 추측으로 쪼개두면 본문 내용이 대상마다 갈라지고, 그게 이 wave 가 막으려는 것이다.
+     */
+    content: string;
+}
+/** 제보를 Notion 페이지 입력으로 바꾼다. 본문은 공용 렌더러 결과 그대로다. */
+declare function buildNotionPage(report: FeedbackReport): NotionPageInput;
+
+/**
+ * 엔드포인트 기본값. 코어가 아니라 **어댑터**가 갖는다(config.ts 의 ENDPOINT_FROM_ADAPTER).
+ *
+ * 상대 경로인 이유: 웹은 같은 오리진의 수집 라우트로 보내는 게 기본이고, 그래야
+ * Origin 허용 목록이라는 실제 방어선이 그대로 작동한다. 앱(RN)에는 오리진이 없으므로
+ * `endpoint` 를 절대 URL 로 지정해야 한다 — 지정 없이 앱에서 쓰면 아래에서 설정 오류로 끊는다.
+ */
+declare const LASSO_DEFAULT_ENDPOINT = "/api/feedback";
+/** 최소한의 응답 형태. 코어는 DOM 타입(lib)에 의존하지 않으므로 구조적으로 정의한다. */
+interface LassoResponseLike {
+    status: number;
+    headers?: {
+        get(name: string): string | null;
+    } | undefined;
+    text(): Promise<string>;
+}
+/** 최소한의 요청 형태. 표준 fetch 의 부분집합이라 그대로 꽂힌다. */
+interface LassoRequestInit {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    keepalive?: boolean;
+}
+type LassoFetch = (url: string, init: LassoRequestInit) => Promise<LassoResponseLike>;
+interface LassoAdapterOpts {
+    /** 수집 토큰. 없으면 `Authorization` 헤더 자체를 붙이지 않는다(미귀속 전송). */
+    token?: string | null;
+    /** 수집 엔드포인트. 없으면 LASSO_DEFAULT_ENDPOINT. */
+    endpoint?: string | null;
+    /** 전송 함수 주입(테스트용). 없으면 globalThis.fetch. */
+    fetch?: LassoFetch | null;
+    /** 경고 출력 주입. 위젯은 캡처를 우회하는 원본 console 을 넘긴다. */
+    warn?: ((message: string, ...rest: unknown[]) => void) | null;
+}
+/**
+ * 라쏘런으로 보내는 봉투.
+ *
+ * 필드명이 코어의 FeedbackReport 와 일부러 다르다. 코어는 이 이름들을 **모른다** —
+ * 대상마다 받는 모양이 다르다는 게 어댑터를 두는 이유 자체다(DP-255 TC5).
+ */
+/**
+ * 라쏘런 `dp-agentation-ingest` 가 실제로 요구하는 봉투.
+ *
+ * 이 모양은 **상상하지 않고 실호출로 확정했다.** 이전 버전은 필드명을 지어내서
+ * (submissionKey/bodyMarkdown/severity …) 실 엔드포인트에 100% 400 으로 거절당했고,
+ * 400 은 재시도 불가라 모든 제보가 조용히 데드레터로 사라졌다.
+ * 계약을 바꿀 때는 반드시 실호출로 다시 확인한다(adapters.live.test.ts).
+ */
+interface LassoEnvelope {
+    /** UUID. **Idempotency-Key 헤더와 반드시 같은 값**이어야 서버가 받는다. */
+    clientSubmissionId: string;
+    /**
+     * 수집 소스의 종류와 같아야 한다(서버가 대조한다). 코어의 platform 을 옮긴 값이다:
+     * web → "web", native → "app". 앱은 report.create 만 보낼 수 있다(요소 지목은 DOM 이 필요).
+     */
+    clientType: "web" | "app";
+    /** 지목 주석은 annotation.add, 리포트 모달 제출은 report.create. */
+    event: "annotation.add" | "report.create";
+    /** epoch ms 정수. ISO 문자열을 보내면 거절된다. */
+    timestamp: number;
+    /** 절대 HTTP(S) URL. 소스의 host_patterns 에 등록된 origin 이어야 한다. */
+    url: string;
+    priority: "unset" | "normal" | "high" | "urgent";
+    annotation?: {
+        id: string;
+        comment: string;
+        x: number | null;
+        y: number | null;
+        element: string | null;
+        elementPath: string | null;
+        selectedText: string | null;
+        boundingBox: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        } | null;
+        timestamp: number;
+    };
+    report?: {
+        comment: string;
+        pin: {
+            x: number;
+            y: number;
+        } | null;
+        sourceFile: string | null;
+        screenshotBase64: string | null;
+        screenshotContentType: "image/jpeg" | "image/png" | null;
+        network: unknown[];
+        logs: unknown[];
+    };
+}
+/** 제보를 라쏘런 봉투로 바꾼다. 순수 함수라 테스트가 전송 없이 모양만 볼 수 있다. */
+declare function buildLassoEnvelope(report: FeedbackReport): LassoEnvelope;
+/**
+ * 라쏘런 어댑터를 만든다.
+ *
+ * 실패 분류(코어가 이 값만 보고 재시도 여부를 정한다):
+ * - 429 → 재시도 가능 + rateLimited. 코어가 최소 10분을 띄운다.
+ * - 408/425/5xx/네트워크 오류 → 재시도 가능(일시적).
+ * - 그 밖의 4xx → **재시도 불가.** 400/401/413 은 다시 보내도 같은 답이라 큐만 막는다.
+ * - 2xx 인데 본문의 `ok` 가 true 가 아님 → 재시도 불가. 스키마 거절은 저절로 낫지 않는다.
+ * - 2xx 인데 본문을 못 읽음 → **재시도 가능.** 프록시·CDN 이 HTML 을 끼워 넣는 일이 실제로 있고,
+ *   멱등 키가 있어 다시 보내도 중복이 생기지 않는다.
+ */
+declare function createLassoAdapter(opts?: LassoAdapterOpts): FeedbackAdapter;
+
+/**
+ * 저장소에서 게스트 id를 찾아 반환하고, 없으면 새로 만들어 저장한다.
+ * 반환값은 사용자가 "이미 알고 있던" 식별자이므로 멱등(같은 저장소 → 같은 id).
+ */
+declare function getOrCreateGuestId(storage: FeedbackStorage): Promise<string>;
+/**
+ * 게스트 id로 FeedbackUser 객체를 만든다.
+ *
+ * `isGuest: true` 를 반드시 붙인다. 게스트를 `user: null` 로 보내면 받는 쪽에서
+ * "신원 수집이 안 된 제보"와 "게스트가 남긴 제보"를 구분할 수 없다.
+ */
+declare function guestUser(id: string): FeedbackUser;
+
+/**
+ * RFC 4122 v4 UUID 문자열을 만든다(8-4-4-4-16).
+ * crypto.getRandomValues가 있으면 그것을, 없으면 Math.random을 쓴다.
+ */
+declare function uuidv4(): string;
+
+export { type AdapterName, type AppInfo, BACKOFF_BASE_MS, BACKOFF_MAX_MS, type BuildContextOpts, type BuildReportOpts, COMMENT_MAX_CHARS, COMMENT_REQUIRED_MESSAGE, COMMENT_TOO_LONG_MESSAGE, type CaptureWithinLimitOpts, type ConfigWarning, type ConfigWarningCode, type ContextProviders, type ContextUser, DEFAULT_ADAPTER, DEFAULT_INTERNAL_ROLES, DEFAULT_POSITION, type DeviceInfo, type DiagLogEntry, type DiagNetworkEntry, type DiagRequestRef, DiagnosticsCollector, type DiagnosticsExcludeMatcher, type DiagnosticsInstallOpts, type DiagnosticsPayload, type DiagnosticsSource, type DisplayInfo, ENDPOINT_FROM_ADAPTER, type ElementInfo, FLOATING_BUTTON_ID, type FeedbackAdapter, type FeedbackConfig, type FeedbackContext, type FeedbackKind, type FeedbackPin, type FeedbackPriority, FeedbackQueue, type FeedbackQueueOpts, type FeedbackReport, type FeedbackScreenshot, type FeedbackStorage, type FeedbackUser, FocusRing, type GetCurrentScreenFn, type GetUserFn, KEEPALIVE_BODY_LIMIT_BYTES, LASSO_DEFAULT_ENDPOINT, LOG_BUFFER_LIMIT, type LassoAdapterOpts, type LassoEnvelope, type LassoFetch, type LassoRequestInit, type LassoResponseLike, type LinearIssueInput, MAX_LOG_MESSAGE_CHARS, MAX_QUEUE_AGE_MS, MAX_QUEUE_ITEMS, MODAL_ACTION_ATTACH, MODAL_ACTION_CANCEL, MODAL_ACTION_PICK, MODAL_ACTION_PIN, MODAL_ACTION_REMOVE_SCREENSHOT, MODAL_ACTION_RETRY, MODAL_ACTION_SEND, MODAL_FIELD_COMMENT, MODAL_FIELD_PRIORITY, type ModalQueueLike, type ModalSubmitStatus, NETWORK_BUFFER_LIMIT, type NativeContext, type NotionPageInput, PinController, type PixelPoint, type PixelSize, type QueueStatus, type QueueStatusListener, RATE_LIMIT_MIN_DELAY_MS, REDACTED, ReportModalController, type ReportModalListener, type ReportModalOpts, type ReportModalState, type ReportParts, type ResolvedConfig, RingBuffer, SCREENSHOT_FAILED_MESSAGE, SCREENSHOT_MAX_BASE64_BYTES, SCREENSHOT_QUALITY_STEPS, SOURCE_ATTR, SUBMIT_DONE_MESSAGE, SUBMIT_FAILED_MESSAGE, SUBMIT_PENDING_MESSAGE, type ScreenshotCapture, type ScreenshotOutcome, type ScreenshotReencode, type ScreenshotStatus, type SourceLocation, type SourceMapping, type SubmitOutcome, type SubmitResult, TITLE_MAX_CHARS, type Visibility, type VisibilityEnv, type VisibilityFn, type WebContext, type WebContextInput, WidgetController, type WidgetControllerOpts, type WidgetCorner, type WidgetListener, type WidgetPlatform, type WidgetPosition, type WidgetScreen, type WidgetState, buildContext, buildLassoEnvelope, buildLinearIssue, buildNotionPage, buildReport, buildTitle, byteLengthOf, canUseKeepalive, captureWithinLimit, createLassoAdapter, defaultBackoff, denormalizePin, detectDevBuild, diagnosticsProviderFor, getOrCreateGuestId, guestUser, isInternalUser, normalizePin, normalizeUser, parseSourceAttr, renderReportBody, resolveConfig, resolveContextUser, sanitizeUrl, screenshotBytes, sharedDiagnostics, shouldShowWidget, sourceFromElement, uuidv4 };