@leviosa-ai/detail-page-editor 0.1.0

package/lib/detail-page/qr-code.ts

@@ -0,0 +1,214 @@
+/**
+ * QR·바코드 → SVG. **전부 브라우저 안에서 끝난다** — 서버도, 크레딧도 안 든다.
+ *
+ * 나오는 마크업은 도형과 같은 규약이다: `<svg viewBox>` 하나에 색은 속성으로만 단다.
+ * 그래야 삽입 경로(`insertShape`)도, 우측 색 컨트롤(`svg-colors.ts`)도 그대로 먹는다.
+ *
+ * 모듈 하나를 `<rect>` 하나로 그리면 요소가 수백 개가 되고 색 스와치도 수백 개로 읽힌다.
+ * 그래서 **검은 모듈 전체를 `<path>` 하나로 합친다** — 색은 배경과 전경 둘뿐이다.
+ */
+
+import qrcode from "qrcode-generator";
+
+export type CodeColors = {
+  /** 모듈·막대 색. */
+  foreground: string;
+  /** 여백 색. `"none"`이면 투명하게 둔다. */
+  background: string;
+};
+
+const DEFAULT_COLORS: CodeColors = { foreground: "#000000", background: "#ffffff" };
+
+/** 스캐너가 요구하는 여백. QR은 4모듈, EAN-13은 좌우 9·7모듈이 규격이다. */
+const QR_QUIET_ZONE = 4;
+
+/**
+ * QR 코드 SVG.
+ *
+ * 오류정정은 M(약 15% 복원)으로 고정한다. 상세페이지의 QR은 인쇄물이 아니라 화면이나
+ * 종이 한 장이라 H까지 올릴 이유가 없고, 올리면 모듈이 촘촘해져 작게 넣었을 때 오히려
+ * 안 읽힌다. 버전은 0(자동) — 내용 길이에 맞춰 알아서 고른다.
+ */
+export function qrCodeSvg(
+  text: string,
+  colors: CodeColors = DEFAULT_COLORS,
+): { markup: string; viewBox: string } | null {
+  const value = text.trim();
+  if (!value) return null;
+
+  let modules: boolean[][];
+  try {
+    const qr = qrcode(0, "M");
+    qr.addData(value);
+    qr.make();
+    const count = qr.getModuleCount();
+    modules = Array.from({ length: count }, (_, row) =>
+      Array.from({ length: count }, (_, col) => qr.isDark(row, col)),
+    );
+  } catch {
+    // 내용이 너무 길어 버전 40에도 안 들어가는 경우.
+    return null;
+  }
+
+  const count = modules.length;
+  const size = count + QR_QUIET_ZONE * 2;
+  const path = modulesToPath(modules, QR_QUIET_ZONE);
+  const viewBox = `0 0 ${size} ${size}`;
+
+  return {
+    viewBox,
+    markup:
+      `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${viewBox}">` +
+      backgroundRect(size, size, colors.background) +
+      `<path fill="${colors.foreground}" d="${path}"/>` +
+      `</svg>`,
+  };
+}
+
+/** 어두운 모듈을 가로로 이어 붙여 한 path로. 인접한 칸을 합쳐 경로 길이를 줄인다. */
+function modulesToPath(modules: boolean[][], offset: number): string {
+  const parts: string[] = [];
+  for (let row = 0; row < modules.length; row += 1) {
+    let col = 0;
+    while (col < modules[row].length) {
+      if (!modules[row][col]) {
+        col += 1;
+        continue;
+      }
+      let run = 1;
+      while (col + run < modules[row].length && modules[row][col + run]) run += 1;
+      parts.push(`M${col + offset} ${row + offset}h${run}v1h-${run}z`);
+      col += run;
+    }
+  }
+  return parts.join("");
+}
+
+function backgroundRect(width: number, height: number, color: string): string {
+  if (!color || color === "none") return "";
+  return `<rect width="${width}" height="${height}" fill="${color}"/>`;
+}
+
+// ── EAN-13 ────────────────────────────────────────────────────────────────────
+
+/**
+ * EAN-13만 낸다. CODE128·CODE39는 물류 라벨용이라 상세페이지에 실릴 일이 없고,
+ * 국내 상품 바코드(KAN)가 EAN-13이다. 필요해지면 여기 옆에 붙인다.
+ */
+
+/** A(왼쪽 홀수 패리티) 집합. R은 이것의 보수, G는 R을 뒤집은 것이다. */
+const EAN_L = [
+  "0001101", "0011001", "0010011", "0111101", "0100011",
+  "0110001", "0101111", "0111011", "0110111", "0001011",
+];
+
+const EAN_R = EAN_L.map((bits) =>
+  [...bits].map((bit) => (bit === "0" ? "1" : "0")).join(""),
+);
+const EAN_G = EAN_R.map((bits) => [...bits].reverse().join(""));
+
+/** 첫 자리가 왼쪽 여섯 자리의 A/G 배치를 정한다 — 13번째 자리는 막대로 안 그려진다. */
+const EAN_PARITY = [
+  "LLLLLL", "LLGLGG", "LLGGLG", "LLGGGL", "LGLLGG",
+  "LGGLLG", "LGGGLL", "LGLGLG", "LGLGGL", "LGGLGL",
+];
+
+/** 오른쪽에서부터 1·3 가중치를 번갈아 곱해 10의 보수를 취한다. */
+export function ean13CheckDigit(digits12: string): number | null {
+  if (!/^\d{12}$/.test(digits12)) return null;
+  let sum = 0;
+  for (let i = 0; i < 12; i += 1) {
+    // 왼쪽부터 0-index 짝수 자리가 가중치 1이다(오른쪽에서 홀수 번째).
+    sum += Number(digits12[i]) * (i % 2 === 0 ? 1 : 3);
+  }
+  return (10 - (sum % 10)) % 10;
+}
+
+/** 12자리면 체크디짓을 붙이고, 13자리면 체크디짓이 맞는지 본다. */
+export function normalizeEan13(input: string): string | null {
+  const digits = input.replace(/\D/g, "");
+  if (digits.length === 12) {
+    const check = ean13CheckDigit(digits);
+    return check === null ? null : `${digits}${check}`;
+  }
+  if (digits.length === 13) {
+    const check = ean13CheckDigit(digits.slice(0, 12));
+    return check !== null && check === Number(digits[12]) ? digits : null;
+  }
+  return null;
+}
+
+/**
+ * EAN-13 SVG. 막대 95모듈 + 좌우 여백(9·7모듈)이 규격이고, 숫자를 아래에 얹는다.
+ *
+ * 가드 막대(양끝·가운데)는 숫자 영역까지 내려온다 — 장식이 아니라 스캐너가 시작·끝을
+ * 잡는 자리라 길이가 규격이다.
+ */
+export function ean13Svg(
+  input: string,
+  colors: CodeColors = DEFAULT_COLORS,
+): { markup: string; viewBox: string; value: string } | null {
+  const value = normalizeEan13(input);
+  if (!value) return null;
+
+  const parity = EAN_PARITY[Number(value[0])];
+  let bits = "101";
+  for (let i = 0; i < 6; i += 1) {
+    const digit = Number(value[i + 1]);
+    bits += parity[i] === "L" ? EAN_L[digit] : EAN_G[digit];
+  }
+  bits += "01010";
+  for (let i = 0; i < 6; i += 1) bits += EAN_R[Number(value[i + 7])];
+  bits += "101";
+
+  const LEFT_QUIET = 11;
+  const RIGHT_QUIET = 7;
+  const BAR_HEIGHT = 68;
+  const GUARD_EXTRA = 5;
+  const TEXT_BASELINE = BAR_HEIGHT + GUARD_EXTRA + 8;
+  const width = LEFT_QUIET + bits.length + RIGHT_QUIET;
+  const height = TEXT_BASELINE + 3;
+
+  // 가드 막대가 서 있는 칸(비트 인덱스). 이 칸만 아래로 더 내려온다.
+  // 시작 3 · 왼쪽 42 · 가운데 5 · 오른쪽 42 · 끝 3 = 95모듈.
+  const guards = new Set<number>();
+  for (const [start, len] of [
+    [0, 3],
+    [45, 5],
+    [92, 3],
+  ] as const) {
+    for (let i = 0; i < len; i += 1) guards.add(start + i);
+  }
+
+  const bars: string[] = [];
+  for (let i = 0; i < bits.length; i += 1) {
+    if (bits[i] !== "1") continue;
+    const tall = guards.has(i);
+    bars.push(
+      `M${LEFT_QUIET + i} 0h1v${tall ? BAR_HEIGHT + GUARD_EXTRA : BAR_HEIGHT}h-1z`,
+    );
+  }
+
+  const viewBox = `0 0 ${width} ${height}`;
+  // 숫자는 `monospace` 한 가지만 쓴다. 이 마크업은 data URI로 `<img>`에 실려 그려지므로
+  // 문서의 `@font-face`가 안 닿는다(차트 기획서에서 같은 이유로 SVG 라벨을 포기했다).
+  // 시스템마다 글꼴이 갈릴 수 있지만 스캐너가 읽는 것은 막대지 숫자가 아니다.
+  const digits = (text: string, x: number, anchor: string) =>
+    `<text x="${x}" y="${TEXT_BASELINE}" fill="${colors.foreground}" ` +
+    `font-family="monospace" font-size="9" text-anchor="${anchor}">${text}</text>`;
+  const label =
+    digits(value[0], LEFT_QUIET - 2, "end") +
+    digits(value.slice(1, 7), LEFT_QUIET + 24, "middle") +
+    digits(value.slice(7), LEFT_QUIET + 71, "middle");
+
+  return {
+    value,
+    viewBox,
+    markup:
+      `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${viewBox}">` +
+      backgroundRect(width, height, colors.background) +
+      `<path fill="${colors.foreground}" d="${bars.join("")}"/>` +
+      label +
+      `</svg>`,
+  };
+}

package/lib/detail-page/reference-image.ts

@@ -0,0 +1,103 @@
+/**
+ * 첨부한 레퍼런스 사진을 **모델에 보낼 크기**로 줄인다.
+ *
+ * 유저가 붙이는 것은 대개 남의 상세페이지 스크린샷이라 길이가 몇천 픽셀이고 파일도
+ * 수 MB다. 그대로 보내면 요청 본문이 통째로 커지는데, 정작 모델이 읽는 것은 배치와
+ * 구성뿐이라 긴 변 1,024px 이면 충분하다. 비용도 여기서 갈린다 — 비전 입력은 픽셀이
+ * 아니라 타일 수로 계산되므로 줄인 만큼 그대로 싸진다.
+ *
+ * JPEG 로 굳힌다. 레퍼런스는 사진이지 도형이 아니라서 무손실이 필요 없고, PNG 로 두면
+ * 같은 그림이 서너 배 무겁다.
+ */
+
+/** 긴 변 상한. 이보다 작은 그림은 확대하지 않는다. */
+export const REFERENCE_MAX_EDGE = 1024;
+
+const QUALITY = 0.82;
+
+/**
+ * 디코드 상한. 넘기면 줄이기를 포기하고 원본을 쓴다.
+ *
+ * 깨진 파일이나 디코더가 못 읽는 포맷은 ``onload`` 도 ``onerror`` 도 **안 뜬다.** 기다리는
+ * 쪽에 상한이 없으면 모달이 제출을 누른 채로 굳는다 — 유저에게는 그냥 먹통이다.
+ */
+const DECODE_TIMEOUT_MS = 3000;
+
+function loadImage(src: string): Promise<HTMLImageElement> {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    const timer = setTimeout(
+      () => reject(new Error("image decode timed out")),
+      DECODE_TIMEOUT_MS,
+    );
+    img.onload = () => {
+      clearTimeout(timer);
+      resolve(img);
+    };
+    img.onerror = () => {
+      clearTimeout(timer);
+      reject(new Error("image decode failed"));
+    };
+    img.src = src;
+  });
+}
+
+function readAsDataUri(file: Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onloadend = () =>
+      typeof reader.result === "string"
+        ? resolve(reader.result)
+        : reject(new Error("read failed"));
+    reader.onerror = () => reject(new Error("read failed"));
+    reader.readAsDataURL(file);
+  });
+}
+
+/** 파일 바이트를 그대로 data URI 로. 붙이자마자 썸네일을 띄우는 데 쓴다. */
+export function readImageFileAsDataUri(file: File): Promise<string> {
+  return readAsDataUri(file);
+}
+
+/**
+ * 줄이기 결과. ``width``/``height`` 는 **보낼 그림의 크기**다 — 판독 값이 그 크기로
+ * 정해지므로(비전 입력은 타일 수로 청구된다) 원본이 아니라 줄인 뒤 크기여야 한다.
+ * 디코드가 안 되면 0 이고, 그때는 부르는 쪽이 "모른다"로 다뤄야 한다.
+ */
+export type ShrunkReference = { uri: string; width: number; height: number };
+
+/**
+ * 이미 읽어 둔 data URI 를 줄인다. 디코드나 캔버스가 안 되면 **원본을 그대로** 돌려준다 —
+ * 줄이지 못한 것이 아예 못 붙이는 것보다 낫다.
+ */
+export async function shrinkReferenceDataUri(
+  original: string,
+): Promise<ShrunkReference> {
+  // 캔버스를 **디코드보다 먼저** 확인한다. 그릴 곳이 없으면 어차피 줄이지 못하는데,
+  // 순서를 뒤집으면 줄이지도 못할 그림을 몇 초씩 기다렸다가 포기하게 된다.
+  const canvas = document.createElement("canvas");
+  const ctx = canvas.getContext("2d");
+  if (!ctx) return { uri: original, width: 0, height: 0 };
+
+  try {
+    const img = await loadImage(original);
+    const longest = Math.max(img.naturalWidth, img.naturalHeight);
+    if (!longest) return { uri: original, width: 0, height: 0 };
+    const scale = Math.min(1, REFERENCE_MAX_EDGE / longest);
+    if (scale >= 1) {
+      // 줄일 것이 없어도 크기는 안다 — 여기서 0 을 내면 안 줄인 그림만 값이 비싸진다.
+      return { uri: original, width: img.naturalWidth, height: img.naturalHeight };
+    }
+
+    canvas.width = Math.max(1, Math.round(img.naturalWidth * scale));
+    canvas.height = Math.max(1, Math.round(img.naturalHeight * scale));
+    ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
+    return {
+      uri: canvas.toDataURL("image/jpeg", QUALITY),
+      width: canvas.width,
+      height: canvas.height,
+    };
+  } catch {
+    return { uri: original, width: 0, height: 0 };
+  }
+}

package/lib/detail-page/reference-upload.ts

@@ -0,0 +1,181 @@
+/**
+ * 상품 사진을 브랜드 버킷에 올리는 길 — **줄이기 + presigned 업로드**.
+ *
+ * 생성 화면 안에만 있던 것을 꺼냈다. 새 상품 시작 화면(`/branding/detail-page-generator/new`)
+ * 도 같은 사진을 같은 자리에 올려야 하는데, 화면 두 곳이 각자 줄이면 압축 품질과 상한이
+ * 갈라진다 — 한쪽에서 올린 사진만 유독 뭉개지는 식이다.
+ *
+ * ## 왜 브라우저에서 먼저 줄이는가
+ *
+ * 원본 그대로 올리면 요즘 폰 사진 한 장이 8MB 를 넘는다. 열 장이면 업로드만 몇 분이고,
+ * 그 사이 유저는 아무것도 못 한다. 그리고 상세페이지에 실릴 크기는 어차피 긴 변
+ * 1600px 이라 그 위는 버리는 픽셀이다.
+ *
+ * 품질은 위에서부터 내려가며 상한(1.5MB)에 처음 걸리는 값을 쓴다. 고정 품질로 잡으면
+ * 단색 그림은 필요 이상으로 뭉개지고, 복잡한 그림은 상한을 못 지킨다.
+ */
+
+import type { DetailPageHostApi } from "../../components/detail-page/detail-page-host-context";
+
+/** 고를 수 있는 원본 크기. 이보다 크면 캔버스에 그리기 전에 메모리가 먼저 눕는다. */
+export const MAX_REFERENCE_IMAGE_BYTES = 10 * 1024 * 1024;
+/** 줄인 뒤 목표 크기. */
+export const MAX_COMPRESSED_REFERENCE_BYTES = 1.5 * 1024 * 1024;
+/** 줄인 뒤 긴 변. 상세페이지가 쓰는 폭보다 넉넉하다. */
+export const MAX_REFERENCE_IMAGE_DIMENSION = 1600;
+
+export interface UploadedReferenceImage {
+  id: string;
+  name: string;
+  previewUrl: string;
+  size: number;
+  contentType: string;
+  s3Key: string;
+  role: string;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" ? (value as Record<string, unknown>) : null;
+}
+
+function firstString(...values: unknown[]): string {
+  for (const value of values) {
+    if (typeof value !== "string") continue;
+    const normalized = value.trim();
+    if (normalized) return normalized;
+  }
+  return "";
+}
+
+export function blobToDataUrl(blob: Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(String(reader.result ?? ""));
+    reader.onerror = () => reject(reader.error);
+    reader.readAsDataURL(blob);
+  });
+}
+
+function loadImageElement(src: string): Promise<HTMLImageElement> {
+  return new Promise((resolve, reject) => {
+    const image = new window.Image();
+    image.onload = () => resolve(image);
+    image.onerror = () => reject(new Error("Failed to load image"));
+    image.src = src;
+  });
+}
+
+export async function compressReferenceImage(file: File): Promise<Blob> {
+  const objectUrl = URL.createObjectURL(file);
+  try {
+    const image = await loadImageElement(objectUrl);
+    const scale = Math.min(
+      1,
+      MAX_REFERENCE_IMAGE_DIMENSION / Math.max(image.naturalWidth, image.naturalHeight),
+    );
+    const width = Math.max(1, Math.round(image.naturalWidth * scale));
+    const height = Math.max(1, Math.round(image.naturalHeight * scale));
+    const canvas = document.createElement("canvas");
+    canvas.width = width;
+    canvas.height = height;
+    const context = canvas.getContext("2d");
+    if (!context) throw new Error("Canvas is not available");
+    // 투명 PNG 를 JPEG 로 바꾸면 투명한 자리가 검게 남는다. 흰색을 먼저 깐다.
+    context.fillStyle = "#FFFFFF";
+    context.fillRect(0, 0, width, height);
+    context.drawImage(image, 0, 0, width, height);
+
+    for (const quality of [0.88, 0.82, 0.76, 0.7]) {
+      const blob = await new Promise<Blob | null>((resolve) =>
+        canvas.toBlob(resolve, "image/jpeg", quality),
+      );
+      if (!blob) continue;
+      if (blob.size <= MAX_COMPRESSED_REFERENCE_BYTES || quality === 0.7) {
+        return blob;
+      }
+    }
+    throw new Error("Image compression failed");
+  } finally {
+    URL.revokeObjectURL(objectUrl);
+  }
+}
+
+export async function uploadReferenceImage(input: {
+  blob: Blob;
+  fileName: string;
+  userId: string;
+  productId?: string;
+  generatedId?: string | null;
+  slotRole?: string;
+  /**
+   * presigned URL 을 발급하는 소싱 서버 호출. 훅을 못 쓰는 자리라 호출부가 넘긴다
+   * (`DetailPageHost.api.createDetailPageReferenceImageUploadUrl`).
+   */
+  createUploadUrl: DetailPageHostApi["createDetailPageReferenceImageUploadUrl"];
+}): Promise<{ s3Key: string; contentType: string }> {
+  const shouldAttachSlotMeta = Boolean(input.generatedId && input.slotRole);
+  const payload = await input.createUploadUrl({
+    user_id: input.userId,
+    product_id: input.productId || undefined,
+    generated_id: shouldAttachSlotMeta ? input.generatedId : undefined,
+    slot_role: shouldAttachSlotMeta ? input.slotRole : undefined,
+    file_name: input.fileName.replace(/\.[^.]+$/, ".jpg"),
+    content_type: "image/jpeg",
+    file_size_bytes: input.blob.size,
+  });
+
+  const uploadUrl = firstString(payload.upload_url, payload.uploadUrl);
+  const uploadMethod = firstString(payload.upload_method, payload.uploadMethod, "POST");
+  const s3Key = firstString(payload.s3_key, payload.s3Key, payload.key);
+  const contentType = firstString(payload.content_type, payload.contentType, "image/jpeg");
+  if (!uploadUrl) throw new Error("Upload URL is missing");
+  if (!s3Key) throw new Error("S3 key is missing");
+
+  const fields = asRecord(payload.form_fields ?? payload.formFields ?? payload.fields);
+  const uploadedFileName = input.fileName.replace(/\.[^.]+$/, ".jpg");
+  if (uploadMethod.toUpperCase() === "POST" && fields) {
+    const formData = new FormData();
+    Object.entries(fields).forEach(([key, value]) => {
+      formData.append(key, String(value));
+    });
+    const uploadFile =
+      input.blob instanceof File
+        ? input.blob
+        : new File([input.blob], uploadedFileName, { type: contentType });
+    formData.append("file", uploadFile);
+    const uploadResponse = await fetch(uploadUrl, { method: "POST", body: formData });
+    if (
+      uploadResponse.status !== 204 &&
+      uploadResponse.status !== 201 &&
+      uploadResponse.status !== 200
+    ) {
+      const errorText = await uploadResponse.text().catch(() => "");
+      throw new Error(errorText || "Reference image upload failed");
+    }
+  } else {
+    const presignedHeaders = asRecord(payload.headers);
+    const uploadResponse = await fetch(uploadUrl, {
+      method: uploadMethod || "PUT",
+      headers: {
+        ...Object.fromEntries(
+          Object.entries(presignedHeaders ?? {}).map(([key, value]) => [
+            key,
+            String(value),
+          ]),
+        ),
+        "Content-Type": contentType,
+      },
+      body: input.blob,
+    });
+    if (
+      uploadResponse.status !== 204 &&
+      uploadResponse.status !== 201 &&
+      uploadResponse.status !== 200
+    ) {
+      const errorText = await uploadResponse.text().catch(() => "");
+      throw new Error(errorText || "Reference image upload failed");
+    }
+  }
+
+  return { s3Key, contentType };
+}

package/lib/detail-page/replace-page.ts

@@ -0,0 +1,35 @@
+/**
+ * 재저작한 화면 하나를 문서에 갈아 끼운다.
+ *
+ * 서버는 그 화면만 다시 디컴포즈해 **페이지 하나**를 돌려준다. 문서를 통째로 다시
+ * 받지 않는 이유는 단순하다: 16개 화면을 전부 브라우저에 다시 태우면 유저가 수십 초를
+ * 기다린다. 슬롯 이름이 화면 단위로 스코프돼 있어(``<라벨>.<이름>``) 페이지 하나만
+ * 바꿔도 다른 화면의 슬롯과 섞이지 않는다.
+ *
+ * **자리를 지킨다.** 지웠다 뒤에 붙이면 재저작한 화면이 문서 맨 끝으로 간다 — 유저는
+ * 고쳐 달라고 했지 옮겨 달라고 하지 않았다.
+ */
+
+export type CanvasDocument = {
+  pages?: Array<Record<string, unknown>>;
+  [key: string]: unknown;
+};
+
+/**
+ * ``page.id`` 가 같은 페이지를 새 페이지로 교체한 문서를 돌려준다(원본 불변).
+ *
+ * 같은 id 의 페이지가 없으면 문서를 그대로 돌려준다 — 새 화면을 조용히 덧붙이면
+ * 유저 화면에는 고쳐진 것과 안 고쳐진 것이 나란히 남는다.
+ */
+export function replaceCanvasPage(
+  document: CanvasDocument,
+  page: Record<string, unknown>,
+): CanvasDocument {
+  const pages = document.pages ?? [];
+  const id = String(page?.id ?? "");
+  const index = pages.findIndex((entry) => String(entry?.id ?? "") === id);
+  if (!id || index < 0) return document;
+  const next = pages.slice();
+  next[index] = page;
+  return { ...document, pages: next };
+}