@solhun/feedback-kit-core 0.2.3 → 0.4.0

package/dist/index.d.cts

@@ -891,6 +891,18 @@ declare const SUBMIT_FAILED_MESSAGE = "\uBCF4\uB0B4\uC9C0 \uBABB\uD588\uC2B5\uB2
 type WidgetPlatform = "web" | "native";
 type ScreenshotStatus = "none" | "capturing" | "ready" | "failed";
 type ModalSubmitStatus = "idle" | "sending" | "sent" | "pending" | "failed";
+/**
+ * 핀이 **무엇을 기준으로** 찍힌 좌표인가. 이미지가 바뀔 때 핀을 버릴지 말지가 여기서 갈린다.
+ *
+ * - `picture`: 스크린샷 **그림 위**를 탭해서 찍은 좌표(앱 핀 화면). 그림이 바뀌면 가리키는
+ *   대상이 달라지므로 **버려야 한다.**
+ * - `viewport`: **페이지 화면**을 클릭해서 나온 좌표(웹 요소 지목). 같은 뷰포트를 찍은
+ *   스크린샷이면 어느 장이든 같은 지점을 가리키므로 **살려야 한다.**
+ *
+ * 이 구분이 없던 동안 지목 좌표가 전부 유실됐다: 클릭 직후 `setPin` 으로 들어온 좌표를
+ * 수백 ms 뒤 도착한 자동 캡처가 `pin: null` 로 덮었다(실측 — 서버 `x`/`y` 가 전부 null).
+ */
+type PinAnchor = "picture" | "viewport";
 /** 모달 안에서 포커스를 받는 요소들의 고정 id. 렌더러가 그대로 매단다. */
 declare const MODAL_FIELD_COMMENT = "comment";
 declare const MODAL_FIELD_PRIORITY = "priority";
@@ -970,6 +982,8 @@ declare class ReportModalController {
     private lastReport;
     /** 이전 open/recapture가 늦게 끝나 최신 상태를 덮지 못하게 하는 세대 번호. */
     private captureGeneration;
+    /** 지금 들고 있는 핀의 기준. 핀이 없으면 의미 없다(기본 `picture`). */
+    private pinAnchor;
     private state;
     constructor(opts: ReportModalOpts);
     getState(): ReportModalState;
@@ -979,8 +993,14 @@ declare class ReportModalController {
     dispose(): void;
     /** WidgetController가 소유한 큐 lifecycle을 함께 정리한다. */
     stopQueue(): void;
+    /**
+     * @param opts.pin 요소를 지목해서 열 때의 **클릭 지점**(뷰포트 기준 0~1).
+     *   여기로 받아야 뒤늦게 끝나는 자동 캡처가 좌표를 지우지 않는다 — `setPin` 으로
+     *   따로 넣으면 캡처와 경쟁해서 진다(그 경쟁에 계속 져서 좌표가 전부 유실됐다).
+     */
     open(opts?: {
         element?: ElementInfo | null;
+        pin?: FeedbackPin | null;
     }): Promise<void>;
     /**
      * 닫기 요청. 쓰던 내용이 있으면 곧장 닫지 않고 확인을 받는다.
@@ -997,8 +1017,12 @@ declare class ReportModalController {
     /** 상한을 넘겨도 값을 자르지 않는다. 거부는 하되 사용자가 쓴 글은 보존한다. */
     setComment(value: string): void;
     setPriority(priority: FeedbackPriority): void;
-    setPin(pin: FeedbackPin | null): void;
-    /** 스크린샷 제거 — 핀은 스크린샷 위 좌표라 함께 사라진다. */
+    /**
+     * @param anchor 이 좌표의 기준. 기본은 `picture`(그림 위 탭) — 앱 핀 화면이 쓰는 값이다.
+     *   웹에서 페이지를 클릭해 얻은 좌표는 `viewport` 로 넣어야 캡처에 지워지지 않는다.
+     */
+    setPin(pin: FeedbackPin | null, anchor?: PinAnchor): void;
+    /** 스크린샷 제거. 그림 위에 찍은 핀은 가리킬 대상이 사라지므로 함께 버린다. */
     removeScreenshot(): void;
     recapture(): Promise<void>;
     /** 캡처가 실패했을 때의 대체 경로 — 사용자가 직접 고른 파일. */
@@ -1062,9 +1086,12 @@ declare class WidgetController {
      * @param opts.element 요소를 지목해서 열 때 그 요소. 지목 모드에서도 화면을
      *   `modal` 로 바꾼다 — `modal.open()` 을 직접 부르면 상태만 열리고 화면은
      *   `picking` 에 머물러 **모달이 렌더되지 않는다**.
+     * @param opts.pin 지목한 클릭 지점. 열기 인자로 넘겨야 자동 캡처가 좌표를 지우지 않는다
+     *   (열고 난 뒤 `modal.setPin` 으로 넣으면 캡처와 경쟁한다).
      */
     openReport(opts?: {
         element?: ElementInfo | null;
+        pin?: FeedbackPin | null;
     }): Promise<void>;
     /** 모달 닫기 요청. 쓰던 내용이 있으면 확인부터 받는다(화면은 그대로 모달). */
     closeReport(): "closed" | "confirm";
@@ -1194,6 +1221,55 @@ interface LassoAdapterOpts {
  * 400 은 재시도 불가라 모든 제보가 조용히 데드레터로 사라졌다.
  * 계약을 바꿀 때는 반드시 실호출로 다시 확인한다(adapters.live.test.ts).
  */
+/**
+ * 구조화 칸이 따로 없는 값들을 담는 자리 → 서버가 `meta` 로 옮긴다.
+ *
+ * 왜 생겼나: 예전에는 이 값들을 **사람이 읽는 마크다운으로 접어 `comment` 에 넣었다.**
+ * 그런데 라쏘런의 `comment` 는 목록·상세의 **제목 자리**다. 5자짜리 코멘트 하나가
+ * 1,399자 덩어리가 되어 화면에 쏟아졌다(실측). 라쏘런은 구조화 칸이 있는 대상이니
+ * 접어 넣을 이유가 없다 — 대상별로 담는 방식이 다른 게 어댑터를 두는 이유다.
+ *
+ * 이름은 **뷰어가 이미 읽는 키를 그대로** 쓴다(`user`·`device`·`appInfo`·`navPath` …).
+ * 새 이름을 지으면 같은 값이 화면에서 두 군데로 갈린다.
+ */
+interface LassoReportContext {
+    /** 제보 종류(`report`=화면 전체, `annotation`=요소 지목). 서버는 요소 유무로도 가른다. */
+    kind: string;
+    app: string;
+    platform: string;
+    sessionId: string;
+    clientTimestamp: string;
+    timezone: string | null;
+    user: {
+        id: string | null;
+        name: string | null;
+        email: string | null;
+        role: string | null;
+        isGuest: boolean;
+    } | null;
+    /** 빌드 플러그인이 심은 화면·소스 매핑. 없으면 null. */
+    source: {
+        screenId: string | null;
+        sourceFile: string | null;
+        sourceLine: number | null;
+    } | null;
+    /** 지목한 요소의 나머지 정보(id·속성). 태그·선택자·텍스트는 report.element 에 있다. */
+    element: {
+        id: string | null;
+        attributes: Record<string, string>;
+    } | null;
+    /** 앱 전용. 뷰어의 구현 정보 칸(기기·앱 버전·OTA·탐색 경로)이 이걸 읽는다. */
+    native: {
+        screenPath: string | null;
+        navPath: string[];
+        routeParams: Record<string, unknown> | null;
+        appInfo: Record<string, unknown>;
+        device: Record<string, unknown>;
+        display: Record<string, unknown>;
+    } | null;
+    /** 호스트가 넣은 자유 메타. 우리가 해석하지 않는다. */
+    extra: Record<string, unknown>;
+}
 interface LassoEnvelope {
     /** UUID. **Idempotency-Key 헤더와 반드시 같은 값**이어야 서버가 받는다. */
     clientSubmissionId: string;
@@ -1226,7 +1302,16 @@ interface LassoEnvelope {
         timestamp: number;
     };
     report?: {
+        /**
+         * **사용자가 쓴 문장 그대로.** 진단을 여기에 접어 넣지 않는다 — 이 값이 곧 제목이다.
+         * 나머지는 구조화 칸(`web`·`network`·`logs`·`element`)과 `context` 로 간다.
+         */
         comment: string;
+        /**
+         * 좌표. **0~100 백분율**이다(코어의 0~1 정규화를 여기서 옮긴다).
+         * 라쏘런의 `x`/`y` 컬럼과 뷰어 오버레이가 백분율을 전제한다 — 0~1 로 보내면
+         * 뷰어의 뷰포트 역산이 "0.12%" 로 읽어 조용히 버리거나 터무니없는 값을 낸다.
+         */
         pin: {
             x: number;
             y: number;
@@ -1269,8 +1354,12 @@ interface LassoEnvelope {
         screenshotContentType: "image/jpeg" | "image/png" | null;
         network: unknown[];
         logs: unknown[];
+        /** 위 칸에 자리가 없는 값들. 서버가 `meta` 로 펼친다. */
+        context: LassoReportContext;
     };
 }
+/** 구조화 칸에 자리가 없는 값들을 모은다. 비어 있어도 키는 남긴다(미수집과 없음을 구분). */
+declare function buildLassoContext(report: FeedbackReport): LassoReportContext;
 /** 제보를 라쏘런 봉투로 바꾼다. 순수 함수라 테스트가 전송 없이 모양만 볼 수 있다. */
 declare function buildLassoEnvelope(report: FeedbackReport): LassoEnvelope;
 /**
@@ -1305,4 +1394,4 @@ declare function guestUser(id: string): FeedbackUser;
  */
 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 };
+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 LassoReportContext, 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, buildLassoContext, 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 };

package/dist/index.d.ts

@@ -891,6 +891,18 @@ declare const SUBMIT_FAILED_MESSAGE = "\uBCF4\uB0B4\uC9C0 \uBABB\uD588\uC2B5\uB2
 type WidgetPlatform = "web" | "native";
 type ScreenshotStatus = "none" | "capturing" | "ready" | "failed";
 type ModalSubmitStatus = "idle" | "sending" | "sent" | "pending" | "failed";
+/**
+ * 핀이 **무엇을 기준으로** 찍힌 좌표인가. 이미지가 바뀔 때 핀을 버릴지 말지가 여기서 갈린다.
+ *
+ * - `picture`: 스크린샷 **그림 위**를 탭해서 찍은 좌표(앱 핀 화면). 그림이 바뀌면 가리키는
+ *   대상이 달라지므로 **버려야 한다.**
+ * - `viewport`: **페이지 화면**을 클릭해서 나온 좌표(웹 요소 지목). 같은 뷰포트를 찍은
+ *   스크린샷이면 어느 장이든 같은 지점을 가리키므로 **살려야 한다.**
+ *
+ * 이 구분이 없던 동안 지목 좌표가 전부 유실됐다: 클릭 직후 `setPin` 으로 들어온 좌표를
+ * 수백 ms 뒤 도착한 자동 캡처가 `pin: null` 로 덮었다(실측 — 서버 `x`/`y` 가 전부 null).
+ */
+type PinAnchor = "picture" | "viewport";
 /** 모달 안에서 포커스를 받는 요소들의 고정 id. 렌더러가 그대로 매단다. */
 declare const MODAL_FIELD_COMMENT = "comment";
 declare const MODAL_FIELD_PRIORITY = "priority";
@@ -970,6 +982,8 @@ declare class ReportModalController {
     private lastReport;
     /** 이전 open/recapture가 늦게 끝나 최신 상태를 덮지 못하게 하는 세대 번호. */
     private captureGeneration;
+    /** 지금 들고 있는 핀의 기준. 핀이 없으면 의미 없다(기본 `picture`). */
+    private pinAnchor;
     private state;
     constructor(opts: ReportModalOpts);
     getState(): ReportModalState;
@@ -979,8 +993,14 @@ declare class ReportModalController {
     dispose(): void;
     /** WidgetController가 소유한 큐 lifecycle을 함께 정리한다. */
     stopQueue(): void;
+    /**
+     * @param opts.pin 요소를 지목해서 열 때의 **클릭 지점**(뷰포트 기준 0~1).
+     *   여기로 받아야 뒤늦게 끝나는 자동 캡처가 좌표를 지우지 않는다 — `setPin` 으로
+     *   따로 넣으면 캡처와 경쟁해서 진다(그 경쟁에 계속 져서 좌표가 전부 유실됐다).
+     */
     open(opts?: {
         element?: ElementInfo | null;
+        pin?: FeedbackPin | null;
     }): Promise<void>;
     /**
      * 닫기 요청. 쓰던 내용이 있으면 곧장 닫지 않고 확인을 받는다.
@@ -997,8 +1017,12 @@ declare class ReportModalController {
     /** 상한을 넘겨도 값을 자르지 않는다. 거부는 하되 사용자가 쓴 글은 보존한다. */
     setComment(value: string): void;
     setPriority(priority: FeedbackPriority): void;
-    setPin(pin: FeedbackPin | null): void;
-    /** 스크린샷 제거 — 핀은 스크린샷 위 좌표라 함께 사라진다. */
+    /**
+     * @param anchor 이 좌표의 기준. 기본은 `picture`(그림 위 탭) — 앱 핀 화면이 쓰는 값이다.
+     *   웹에서 페이지를 클릭해 얻은 좌표는 `viewport` 로 넣어야 캡처에 지워지지 않는다.
+     */
+    setPin(pin: FeedbackPin | null, anchor?: PinAnchor): void;
+    /** 스크린샷 제거. 그림 위에 찍은 핀은 가리킬 대상이 사라지므로 함께 버린다. */
     removeScreenshot(): void;
     recapture(): Promise<void>;
     /** 캡처가 실패했을 때의 대체 경로 — 사용자가 직접 고른 파일. */
@@ -1062,9 +1086,12 @@ declare class WidgetController {
      * @param opts.element 요소를 지목해서 열 때 그 요소. 지목 모드에서도 화면을
      *   `modal` 로 바꾼다 — `modal.open()` 을 직접 부르면 상태만 열리고 화면은
      *   `picking` 에 머물러 **모달이 렌더되지 않는다**.
+     * @param opts.pin 지목한 클릭 지점. 열기 인자로 넘겨야 자동 캡처가 좌표를 지우지 않는다
+     *   (열고 난 뒤 `modal.setPin` 으로 넣으면 캡처와 경쟁한다).
      */
     openReport(opts?: {
         element?: ElementInfo | null;
+        pin?: FeedbackPin | null;
     }): Promise<void>;
     /** 모달 닫기 요청. 쓰던 내용이 있으면 확인부터 받는다(화면은 그대로 모달). */
     closeReport(): "closed" | "confirm";
@@ -1194,6 +1221,55 @@ interface LassoAdapterOpts {
  * 400 은 재시도 불가라 모든 제보가 조용히 데드레터로 사라졌다.
  * 계약을 바꿀 때는 반드시 실호출로 다시 확인한다(adapters.live.test.ts).
  */
+/**
+ * 구조화 칸이 따로 없는 값들을 담는 자리 → 서버가 `meta` 로 옮긴다.
+ *
+ * 왜 생겼나: 예전에는 이 값들을 **사람이 읽는 마크다운으로 접어 `comment` 에 넣었다.**
+ * 그런데 라쏘런의 `comment` 는 목록·상세의 **제목 자리**다. 5자짜리 코멘트 하나가
+ * 1,399자 덩어리가 되어 화면에 쏟아졌다(실측). 라쏘런은 구조화 칸이 있는 대상이니
+ * 접어 넣을 이유가 없다 — 대상별로 담는 방식이 다른 게 어댑터를 두는 이유다.
+ *
+ * 이름은 **뷰어가 이미 읽는 키를 그대로** 쓴다(`user`·`device`·`appInfo`·`navPath` …).
+ * 새 이름을 지으면 같은 값이 화면에서 두 군데로 갈린다.
+ */
+interface LassoReportContext {
+    /** 제보 종류(`report`=화면 전체, `annotation`=요소 지목). 서버는 요소 유무로도 가른다. */
+    kind: string;
+    app: string;
+    platform: string;
+    sessionId: string;
+    clientTimestamp: string;
+    timezone: string | null;
+    user: {
+        id: string | null;
+        name: string | null;
+        email: string | null;
+        role: string | null;
+        isGuest: boolean;
+    } | null;
+    /** 빌드 플러그인이 심은 화면·소스 매핑. 없으면 null. */
+    source: {
+        screenId: string | null;
+        sourceFile: string | null;
+        sourceLine: number | null;
+    } | null;
+    /** 지목한 요소의 나머지 정보(id·속성). 태그·선택자·텍스트는 report.element 에 있다. */
+    element: {
+        id: string | null;
+        attributes: Record<string, string>;
+    } | null;
+    /** 앱 전용. 뷰어의 구현 정보 칸(기기·앱 버전·OTA·탐색 경로)이 이걸 읽는다. */
+    native: {
+        screenPath: string | null;
+        navPath: string[];
+        routeParams: Record<string, unknown> | null;
+        appInfo: Record<string, unknown>;
+        device: Record<string, unknown>;
+        display: Record<string, unknown>;
+    } | null;
+    /** 호스트가 넣은 자유 메타. 우리가 해석하지 않는다. */
+    extra: Record<string, unknown>;
+}
 interface LassoEnvelope {
     /** UUID. **Idempotency-Key 헤더와 반드시 같은 값**이어야 서버가 받는다. */
     clientSubmissionId: string;
@@ -1226,7 +1302,16 @@ interface LassoEnvelope {
         timestamp: number;
     };
     report?: {
+        /**
+         * **사용자가 쓴 문장 그대로.** 진단을 여기에 접어 넣지 않는다 — 이 값이 곧 제목이다.
+         * 나머지는 구조화 칸(`web`·`network`·`logs`·`element`)과 `context` 로 간다.
+         */
         comment: string;
+        /**
+         * 좌표. **0~100 백분율**이다(코어의 0~1 정규화를 여기서 옮긴다).
+         * 라쏘런의 `x`/`y` 컬럼과 뷰어 오버레이가 백분율을 전제한다 — 0~1 로 보내면
+         * 뷰어의 뷰포트 역산이 "0.12%" 로 읽어 조용히 버리거나 터무니없는 값을 낸다.
+         */
         pin: {
             x: number;
             y: number;
@@ -1269,8 +1354,12 @@ interface LassoEnvelope {
         screenshotContentType: "image/jpeg" | "image/png" | null;
         network: unknown[];
         logs: unknown[];
+        /** 위 칸에 자리가 없는 값들. 서버가 `meta` 로 펼친다. */
+        context: LassoReportContext;
     };
 }
+/** 구조화 칸에 자리가 없는 값들을 모은다. 비어 있어도 키는 남긴다(미수집과 없음을 구분). */
+declare function buildLassoContext(report: FeedbackReport): LassoReportContext;
 /** 제보를 라쏘런 봉투로 바꾼다. 순수 함수라 테스트가 전송 없이 모양만 볼 수 있다. */
 declare function buildLassoEnvelope(report: FeedbackReport): LassoEnvelope;
 /**
@@ -1305,4 +1394,4 @@ declare function guestUser(id: string): FeedbackUser;
  */
 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 };
+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 LassoReportContext, 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, buildLassoContext, 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 };

package/dist/index.js

@@ -1358,6 +1358,8 @@ var ReportModalController = class {
     this.lastReport = null;
     /** 이전 open/recapture가 늦게 끝나 최신 상태를 덮지 못하게 하는 세대 번호. */
     this.captureGeneration = 0;
+    /** 지금 들고 있는 핀의 기준. 핀이 없으면 의미 없다(기본 `picture`). */
+    this.pinAnchor = "picture";
     this.state = {
       open: false,
       element: null,
@@ -1426,12 +1428,18 @@ var ReportModalController = class {
     this.queue.stop?.();
   }
   // ── 열기/닫기 ─────────────────────────────────────────────────────────────
+  /**
+   * @param opts.pin 요소를 지목해서 열 때의 **클릭 지점**(뷰포트 기준 0~1).
+   *   여기로 받아야 뒤늦게 끝나는 자동 캡처가 좌표를 지우지 않는다 — `setPin` 으로
+   *   따로 넣으면 캡처와 경쟁해서 진다(그 경쟁에 계속 져서 좌표가 전부 유실됐다).
+   */
   async open(opts = {}) {
     if (this.state.open) return;
     const wasPending = this.state.submitStatus === "pending" && this.lastReport !== null;
     const pendingReport = wasPending ? this.lastReport : null;
     this.touched = false;
     this.submitAttempted = false;
+    this.pinAnchor = opts.pin && !pendingReport ? "viewport" : "picture";
     this.patch({
       open: true,
       comment: pendingReport?.comment ?? "",
@@ -1441,7 +1449,7 @@ var ReportModalController = class {
       screenshot: pendingReport?.screenshot ?? null,
       screenshotStatus: "none",
       screenshotMessage: null,
-      pin: pendingReport?.pin ?? null,
+      pin: pendingReport?.pin ?? opts.pin ?? null,
       submitStatus: wasPending ? "pending" : "idle",
       submitMessage: wasPending ? SUBMIT_PENDING_MESSAGE : null,
       closeConfirmVisible: false,
@@ -1490,6 +1498,7 @@ var ReportModalController = class {
     };
     this.touched = false;
     this.submitAttempted = false;
+    if (!keepDraft) this.pinAnchor = "picture";
     this.patch({
       open: false,
       closeConfirmVisible: false,
@@ -1509,11 +1518,16 @@ var ReportModalController = class {
     if (this.isDraftLocked()) return;
     this.patch({ priority });
   }
-  setPin(pin) {
+  /**
+   * @param anchor 이 좌표의 기준. 기본은 `picture`(그림 위 탭) — 앱 핀 화면이 쓰는 값이다.
+   *   웹에서 페이지를 클릭해 얻은 좌표는 `viewport` 로 넣어야 캡처에 지워지지 않는다.
+   */
+  setPin(pin, anchor = "picture") {
     if (this.isDraftLocked()) return;
+    this.pinAnchor = anchor;
     this.patch({ pin });
   }
-  /** 스크린샷 제거 — 핀은 스크린샷 위 좌표라 함께 사라진다. */
+  /** 스크린샷 제거. 그림 위에 찍은 핀은 가리킬 대상이 사라지므로 함께 버린다. */
   removeScreenshot() {
     if (this.isDraftLocked()) return;
     this.captureGeneration += 1;
@@ -1521,7 +1535,7 @@ var ReportModalController = class {
       screenshot: null,
       screenshotStatus: "none",
       screenshotMessage: null,
-      pin: null
+      ...this.pinAnchor === "picture" ? { pin: null } : {}
     });
   }
   async recapture() {
@@ -1554,15 +1568,21 @@ var ReportModalController = class {
     }
   }
   applyScreenshot(shot, failed) {
+    const dropPin = this.pinAnchor === "picture" ? { pin: null } : {};
     if (shot && !failed) {
-      this.patch({ screenshot: shot, screenshotStatus: "ready", screenshotMessage: null, pin: null });
+      this.patch({
+        screenshot: shot,
+        screenshotStatus: "ready",
+        screenshotMessage: null,
+        ...dropPin
+      });
       return;
     }
     this.patch({
       screenshot: null,
       screenshotStatus: "failed",
       screenshotMessage: SCREENSHOT_FAILED_MESSAGE,
-      pin: null
+      ...dropPin
     });
   }
   // ── 포커스 ────────────────────────────────────────────────────────────────
@@ -1758,6 +1778,8 @@ var WidgetController = class {
    * @param opts.element 요소를 지목해서 열 때 그 요소. 지목 모드에서도 화면을
    *   `modal` 로 바꾼다 — `modal.open()` 을 직접 부르면 상태만 열리고 화면은
    *   `picking` 에 머물러 **모달이 렌더되지 않는다**.
+   * @param opts.pin 지목한 클릭 지점. 열기 인자로 넘겨야 자동 캡처가 좌표를 지우지 않는다
+   *   (열고 난 뒤 `modal.setPin` 으로 넣으면 캡처와 경쟁한다).
    */
   async openReport(opts = {}) {
     this.screen = "modal";
@@ -2113,6 +2135,47 @@ function idFrom(parsed) {
   }
   return null;
 }
+function toPercent(value) {
+  return Math.round(value * 1e5) / 1e3;
+}
+function buildLassoContext(report) {
+  const c = report.context;
+  const el = report.element;
+  const user = c.user;
+  const source = el ? sourceFromElement(el) : c.source;
+  const hasSource = Boolean(source.screenId || source.sourceFile);
+  return {
+    kind: report.kind,
+    app: c.app,
+    platform: c.platform,
+    sessionId: c.sessionId,
+    clientTimestamp: c.clientTimestamp,
+    timezone: c.timezone,
+    user: user ? {
+      id: user.id,
+      name: user.name ?? null,
+      email: user.email,
+      role: user.role ?? null,
+      isGuest: user.isGuest
+    } : null,
+    source: hasSource ? {
+      screenId: source.screenId,
+      sourceFile: source.sourceFile,
+      sourceLine: source.sourceLine ?? null
+    } : null,
+    // 속성이 하나도 없으면 빈 객체를 보내지 않는다 — 화면에 빈 항목이 늘어난다.
+    element: el && (el.id !== null || Object.keys(el.attributes).length > 0) ? { id: el.id, attributes: el.attributes } : null,
+    native: c.native ? {
+      screenPath: c.native.screenPath,
+      navPath: c.native.navPath,
+      routeParams: c.native.routeParams,
+      appInfo: { ...c.native.appInfo },
+      device: { ...c.native.device },
+      display: { ...c.native.display }
+    } : null,
+    extra: c.extra
+  };
+}
 function buildLassoEnvelope(report) {
   const c = report.context;
   const clientType = c.platform === "native" ? "app" : "web";
@@ -2128,8 +2191,9 @@ function buildLassoEnvelope(report) {
     url: c.url ?? (clientType === "app" ? `app://${c.screen ?? "unknown"}` : ""),
     priority: report.priority,
     report: {
-      comment: renderReportBody(report),
-      pin: report.pin ? { x: report.pin.x, y: report.pin.y } : null,
+      // 서버가 1자 이상을 요구한다. 코멘트 없는 제보를 400 으로 잃지 않게 한 줄을 채운다.
+      comment: report.comment.trim().length > 0 ? report.comment.trim() : "(\uCF54\uBA58\uD2B8 \uC5C6\uC74C)",
+      pin: report.pin ? { x: toPercent(report.pin.x), y: toPercent(report.pin.y) } : null,
       sourceFile: el?.attributes["data-feedback-source"] ?? null,
       element: el ? {
         tag: el.tag,
@@ -2151,7 +2215,8 @@ function buildLassoEnvelope(report) {
       screenshotContentType: report.screenshot?.contentType ?? null,
       // 서버가 없으면 빈 배열로 취급하지만, 미연동과 "없었음"을 구분해 보낸다.
       network: report.context.diagnostics?.network ?? [],
-      logs: report.context.diagnostics?.logs ?? []
+      logs: report.context.diagnostics?.logs ?? [],
+      context: buildLassoContext(report)
     }
   };
 }
@@ -2285,6 +2350,7 @@ export {
   TITLE_MAX_CHARS,
   WidgetController,
   buildContext,
+  buildLassoContext,
   buildLassoEnvelope,
   buildLinearIssue,
   buildNotionPage,