@solhun/feedback-kit-core 0.1.0

package/src/widget/screenshot.ts

@@ -0,0 +1,109 @@
+// 스크린샷 용량 정책.
+//
+// 캡처는 "있으면 좋은 것"이지 제출의 전제가 아니다. 그래서 이 모듈의 모든 실패 경로는
+// 예외를 던지지 않고 `failed: true` 로 내려온다 — 호출부가 제출을 막지 않게 하려는 것이다.
+
+import type { FeedbackScreenshot } from "../types.js";
+
+/** 계약상 스크린샷 상한. base64 문자열 기준 8 MiB. */
+export const SCREENSHOT_MAX_BASE64_BYTES = 8 * 1024 * 1024;
+
+/** 캡처가 불가능할 때 사용자에게 보여줄 문구. */
+export const SCREENSHOT_FAILED_MESSAGE = "캡처 실패 — 파일로 첨부할 수 있습니다";
+
+/** 상한을 넘겼을 때 차례로 시도할 재인코딩 품질. 앞에서부터 시도하고 처음 통과하는 값을 쓴다. */
+export const SCREENSHOT_QUALITY_STEPS: readonly number[] = [0.7, 0.5, 0.3];
+
+/**
+ * base64 페이로드의 바이트 수.
+ * base64 는 ASCII 라 문자 수가 곧 바이트 수다(디코딩 후 원본 크기가 아니라 전송량 기준).
+ */
+export function screenshotBytes(shot: FeedbackScreenshot | null | undefined): number {
+  if (!shot || typeof shot.base64 !== "string") return 0;
+  return shot.base64.length;
+}
+
+export type ScreenshotCapture = () =>
+  | FeedbackScreenshot
+  | null
+  | Promise<FeedbackScreenshot | null>;
+
+export type ScreenshotReencode = (
+  shot: FeedbackScreenshot,
+  quality: number,
+) => FeedbackScreenshot | null | Promise<FeedbackScreenshot | null>;
+
+export interface CaptureWithinLimitOpts {
+  capture: ScreenshotCapture;
+  /** 상한 초과 시 다시 인코딩하는 훅. 없으면 재인코딩 없이 바로 포기한다. */
+  reencode?: ScreenshotReencode | null;
+  qualitySteps?: readonly number[];
+  limitBytes?: number;
+}
+
+export interface ScreenshotOutcome {
+  screenshot: FeedbackScreenshot | null;
+  /** 캡처를 끝내 얻지 못했다. 제출은 계속 가능해야 한다. */
+  failed: boolean;
+  /** 실패했을 때만 채워지는 안내 문구. */
+  message: string | null;
+  /** 품질을 낮춰 다시 인코딩한 결과인가. */
+  reencoded: boolean;
+}
+
+function failure(): ScreenshotOutcome {
+  return {
+    screenshot: null,
+    failed: true,
+    message: SCREENSHOT_FAILED_MESSAGE,
+    reencoded: false,
+  };
+}
+
+function usable(shot: FeedbackScreenshot | null | undefined): shot is FeedbackScreenshot {
+  return !!shot && typeof shot.base64 === "string" && shot.base64.length > 0;
+}
+
+/**
+ * 캡처한 뒤 용량 상한 안으로 들여보낸다.
+ *
+ * 1. 캡처 → 실패하거나 빈 결과면 곧장 실패로 내린다.
+ * 2. 상한 이내면 그대로 쓴다.
+ * 3. 초과하면 품질을 단계별로 낮춰 재인코딩하고, 처음 통과한 결과를 쓴다.
+ * 4. 끝내 못 맞추면 스크린샷을 버리고 실패 문구로 대체한다(제출은 막지 않는다).
+ */
+export async function captureWithinLimit(
+  opts: CaptureWithinLimitOpts,
+): Promise<ScreenshotOutcome> {
+  const limit = opts.limitBytes ?? SCREENSHOT_MAX_BASE64_BYTES;
+
+  let shot: FeedbackScreenshot | null = null;
+  try {
+    shot = (await opts.capture()) ?? null;
+  } catch {
+    // 캡처 구현이 던지는 예외는 여기서 흡수한다. 위로 새면 모달이 열리다 만다.
+    shot = null;
+  }
+  if (!usable(shot)) return failure();
+
+  if (screenshotBytes(shot) <= limit) {
+    return { screenshot: shot, failed: false, message: null, reencoded: false };
+  }
+
+  const steps = opts.qualitySteps ?? SCREENSHOT_QUALITY_STEPS;
+  if (opts.reencode) {
+    for (const quality of steps) {
+      let next: FeedbackScreenshot | null = null;
+      try {
+        next = (await opts.reencode(shot, quality)) ?? null;
+      } catch {
+        next = null;
+      }
+      if (usable(next) && screenshotBytes(next) <= limit) {
+        return { screenshot: next, failed: false, message: null, reencoded: true };
+      }
+    }
+  }
+
+  return failure();
+}