@leviosa-ai/detail-page-editor 0.1.0

package/lib/detail-page/data-gif-payload.ts

@@ -0,0 +1,167 @@
+/**
+ * '수치를 GIF로' 요청 본문 만들기 + 선택 텍스트에서 숫자 읽어내기.
+ *
+ * 운영 편집기(editor-client)와 데모 하니스(dev-canvas)가 같은 계약으로 호출해야 해서
+ * 한 곳에 둔다 — 한쪽에만 필드를 더하면 데모에서만 값이 빠지는 식으로 갈린다.
+ *
+ * 카운트업은 **입력 폼을 따로 두지 않는다.** 이미 캔버스에 적어 둔 "279.45%" 를 고르면
+ * 거기서 목표값·소수 자릿수·접두/접미사를 읽는다. 숫자를 두 번 적게 하면 캔버스의 값과
+ * GIF의 값이 어긋나는 사고가 난다.
+ */
+
+export type CountUpParsed = {
+  to: number;
+  decimals: number;
+  /** 원문에 천 단위 쉼표가 있었는지(없었으면 GIF에도 안 찍는다). */
+  grouping: boolean;
+  prefix: string;
+  suffix: string;
+};
+
+/** 서버 스키마 상한(스키마를 넘기면 422). */
+const AFFIX_MAX = 8;
+const DECIMALS_MAX = 4;
+
+/**
+ * 텍스트 한 줄에서 숫자 하나를 읽는다. 숫자가 없으면 ``null`` — 호출부는 그때 섹션을
+ * 아예 감춘다("2천만 개" 같은 문구에 카운트업 버튼을 띄워도 눌러봐야 헛것이 나온다).
+ */
+export function parseCountUpText(raw: string): CountUpParsed | null {
+  const text = String(raw ?? "").trim();
+  // 쉼표는 자릿수 구분으로만 인정한다(뒤에 정확히 세 자리가 올 때).
+  const match = text.match(/\d{1,3}(?:,\d{3})+(?:\.\d+)?|\d+(?:\.\d+)?/);
+  if (!match || match.index === undefined) return null;
+  const token = match[0];
+  const to = Number(token.replace(/,/g, ""));
+  if (!Number.isFinite(to)) return null;
+  const dot = token.indexOf(".");
+  return {
+    to,
+    decimals: dot < 0 ? 0 : Math.min(token.length - dot - 1, DECIMALS_MAX),
+    grouping: token.includes(","),
+    prefix: text.slice(0, match.index).slice(-AFFIX_MAX),
+    suffix: text.slice(match.index + token.length).slice(0, AFFIX_MAX),
+  };
+}
+
+/** SVG ``text-anchor``. Canvas 의 left/center/right 를 그대로 옮긴 것. */
+export type TextAnchor = "start" | "middle" | "end";
+
+/**
+ * 편집기 정렬 → SVG 앵커. 모르는 값은 왼쪽으로 둔다(Canvas 기본값과 같다).
+ *
+ * 상자가 글자보다 넓을 때는 정렬이 곧 자리다. 이걸 안 넘기면 서버가 항상 가운데로
+ * 그려서, 제자리 교체인데 숫자만 가운데로 옮겨 앉는다.
+ */
+export function textAnchorOf(align: unknown): TextAnchor {
+  const value = String(align ?? "")
+    .trim()
+    .toLowerCase();
+  if (value === "center") return "middle";
+  if (value === "right") return "end";
+  return "start";
+}
+
+export type CountUpGifInput = {
+  kind: "count_up";
+  to: number;
+  start?: number;
+  decimals?: number;
+  grouping?: boolean;
+  prefix?: string;
+  suffix?: string;
+  color?: string;
+  fontSize?: number;
+  fontWeight?: number;
+  fontFamily?: string;
+  letterSpacing?: number;
+  anchor?: TextAnchor;
+  italic?: boolean;
+  /** 형광 마커 띠 색. 선택 텍스트에 하이라이트가 걸려 있으면 그 색이 온다. */
+  marker?: string;
+  /** 원본 상자 크기와 글자 기준선(px). 주면 서버가 캔버스를 추정하지 않는다. */
+  width?: number;
+  height?: number;
+};
+
+export type CellGridGifInput = {
+  kind: "cell_grid";
+  /** 행별로 채울 칸 수(위→아래). */
+  filled: number[];
+  cols?: number;
+  shape?: string;
+  size?: number;
+  pitchX?: number;
+  pitchY?: number;
+  fill?: string;
+  empty?: string;
+  order?: string;
+};
+
+export type DataGifRequestInput = (CountUpGifInput | CellGridGifInput) & {
+  background?: string;
+  transparent?: boolean;
+  fonts?: Array<{ family: string; url: string; weight: number }>;
+  brandId?: string;
+};
+
+export function buildDataGifPayload(input: DataGifRequestInput) {
+  const common = {
+    background: input.background,
+    transparent: input.transparent,
+    fonts: input.fonts ?? [],
+    brand_id: input.brandId,
+  };
+  if (input.kind === "count_up") {
+    return {
+      kind: "count_up",
+      count_up: {
+        to: input.to,
+        start: input.start,
+        decimals: input.decimals,
+        grouping: input.grouping,
+        prefix: input.prefix,
+        suffix: input.suffix,
+        color: input.color,
+        font_size: input.fontSize,
+        font_weight: input.fontWeight,
+        font_family: input.fontFamily,
+        letter_spacing: input.letterSpacing,
+        anchor: input.anchor,
+        italic: input.italic,
+        marker: input.marker,
+        width: input.width,
+        height: input.height,
+      },
+      ...common,
+    };
+  }
+  return {
+    kind: "cell_grid",
+    cell_grid: {
+      filled: input.filled,
+      cols: input.cols,
+      shape: input.shape,
+      size: input.size,
+      pitch_x: input.pitchX,
+      pitch_y: input.pitchY,
+      fill: input.fill,
+      empty: input.empty,
+      order: input.order,
+    },
+    ...common,
+  };
+}
+
+/**
+ * "6,4,3" / "6 4 3" 같은 입력 → 행별 채움 수. 서버가 422로 되돌려 주기 전에 여기서
+ * 숫자가 아닌 것과 음수를 걸러 낸다.
+ */
+export function parseFilledRows(raw: string): number[] {
+  return String(raw ?? "")
+    .split(/[^\d]+/)
+    .filter(Boolean)
+    .map((v) => Math.max(0, Math.trunc(Number(v))))
+    .filter((v) => Number.isFinite(v))
+    .slice(0, 40);
+}

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

@@ -0,0 +1,244 @@
+/**
+ * 디자인 레퍼런스 — "이런 식으로"를 그림으로 가리키는 입력의 **브라우저 쪽 계약**.
+ *
+ * 서버(``app/services/detail_page/design_reference.py``)와 같은 어휘·같은 상한을 쓴다.
+ * 한쪽만 고치면 화면에서는 붙었는데 요청이 422 로 돌아오거나, 반대로 화면이 미리 막아
+ * 서버가 허용하는 것을 못 넣게 된다.
+ *
+ * ## 왜 축을 고르게 하는가
+ *
+ * 레퍼런스를 통째로 따라가면 남의 상세페이지가 된다. 실제로 원하는 것은 축 하나씩이다 —
+ * 이 장에서는 색감만, 저 장에서는 배치만. 축을 안 고르면 예전처럼 배치와 구성만
+ * 참고한다(기존 동작이 기본값이다).
+ *
+ * ## 왜 붙이는 자리에서 막는가
+ *
+ * 크기·형식 검사는 서버에도 있다. 그런데 서버에서만 막으면 유저는 **제출을 누른 다음에야**
+ * 알게 된다 — 그림을 고르고, 축을 고르고, 지시를 다 적은 뒤다. 같은 규칙을 붙이는
+ * 자리에도 두어 그 자리에서 말해 준다.
+ */
+
+import { shrinkReferenceDataUri } from "./reference-image";
+
+/**
+ * 참고할 축. 서버의 ``ASPECT_LABELS`` 와 **키가 같아야 한다**.
+ *
+ * ``content`` 는 **문구가 아니라 정보 구성**이다 — 어떤 항목을 어떤 순서로 다루는지
+ * (성분표 · 사용법 · 비교표 · 후기). 남의 문장을 옮겨 오는 축이 아니라서 설명도 그렇게
+ * 적는다. 셀러가 "내용을 참고"를 "문구를 베낀다"로 읽으면 안 된다.
+ */
+export const DESIGN_REFERENCE_ASPECTS = [
+  { key: "palette", label: "색감", hint: "바탕·글자·강조의 색 관계" },
+  { key: "typography", label: "서체", hint: "굵기 대비와 글자 크기 리듬" },
+  { key: "layout", label: "레이아웃", hint: "단 수, 정렬, 여백 리듬" },
+  { key: "content", label: "내용 구성", hint: "다루는 정보 항목과 순서" },
+  { key: "mood", label: "분위기", hint: "여백의 양과 요소 밀도" },
+  { key: "decoration", label: "장식", hint: "구분선·도형의 성격" },
+] as const;
+
+export type DesignReferenceAspect = (typeof DESIGN_REFERENCE_ASPECTS)[number]["key"];
+
+/** 레퍼런스 한 장. 서버 요청 본문과 같은 모양이다. */
+export type DesignReference = {
+  url: string;
+  aspects: DesignReferenceAspect[];
+};
+
+/**
+ * 장수 상한. 서버와 **같은 수**여야 한다 — 프론트가 더 보내면 서버가 거절하고,
+ * 서버보다 적게 막으면 유저가 넣을 수 있는 것을 못 넣는다.
+ */
+export const MAX_DESIGN_REFERENCES = 6;
+
+/**
+ * 고를 수 있는 파일 형식. 비전 모델이 읽는 것은 정지 이미지뿐이라 PDF·HEIC 는 못 쓴다.
+ *
+ * GIF 는 받는다. 움짤이어도 줄이기가 첫 프레임을 굳히고(캔버스는 한 프레임만 그린다),
+ * 줄이기를 건너뛴 작은 GIF 는 서버가 평탄화한다. 막는 것보다 첫 프레임으로 읽히는 편이
+ * 낫다 — "이 움짤 느낌으로"는 멀쩡한 요청이다.
+ */
+export const ACCEPTED_REFERENCE_TYPES = [
+  "image/png",
+  "image/jpeg",
+  "image/webp",
+  "image/gif",
+] as const;
+
+/** ``<input accept>`` 에 넣을 값. */
+export const REFERENCE_ACCEPT_ATTR = ACCEPTED_REFERENCE_TYPES.join(",");
+
+/** 고를 수 있는 원본 파일 크기. 이보다 크면 줄이기 전에 브라우저 메모리가 먼저 눕는다. */
+export const MAX_REFERENCE_FILE_BYTES = 12 * 1024 * 1024;
+
+/** 줄인 **뒤** 서버가 받아 주는 한 장의 크기. 서버의 ``MAX_REFERENCE_BYTES`` 와 같다. */
+export const MAX_REFERENCE_UPLOAD_BYTES = 4 * 1024 * 1024;
+
+/** 붙일 수 없는 파일이면 이유를, 괜찮으면 null. */
+export function referenceFileRejection(file: File): string | null {
+  const type = String(file.type || "").toLowerCase();
+  if (!ACCEPTED_REFERENCE_TYPES.includes(type as (typeof ACCEPTED_REFERENCE_TYPES)[number])) {
+    return "PNG · JPG · WEBP · GIF 만 참고 사진으로 쓸 수 있어요.";
+  }
+  if (file.size > MAX_REFERENCE_FILE_BYTES) {
+    const limit = Math.round(MAX_REFERENCE_FILE_BYTES / (1024 * 1024));
+    return `참고 사진은 한 장에 ${limit}MB 까지예요.`;
+  }
+  return null;
+}
+
+/** base64 data URI 가 실제로 몇 바이트인지. 요청 본문 크기를 재는 데 쓴다. */
+export function dataUriByteLength(uri: string): number {
+  const comma = uri.indexOf(",");
+  if (comma < 0) return 0;
+  const payload = uri.slice(comma + 1);
+  const padding = payload.endsWith("==") ? 2 : payload.endsWith("=") ? 1 : 0;
+  return Math.max(0, Math.floor((payload.length * 3) / 4) - padding);
+}
+
+/**
+ * 고른 파일을 **바로 걸 수 있는** data URI 로 읽는다. 줄이기는 여기서 하지 않는다.
+ *
+ * 썸네일을 줄이기까지 기다렸다가 띄우면 안 된다 — 줄이기는 디코드를 기다리는 일이고,
+ * 디코더가 못 읽는 파일에서는 몇 초 뒤에야 포기한다. 그 사이 화면에 아무것도 안 뜨면
+ * 유저는 첨부가 먹히지 않은 줄 안다. 형식·원본 크기는 **읽기 전에** 이미 걸렀다.
+ *
+ * @throws Error 붙일 수 없는 파일. message 를 그대로 보여 주면 된다.
+ */
+export async function readReferenceFile(file: File): Promise<string> {
+  const rejection = referenceFileRejection(file);
+  if (rejection) throw new Error(rejection);
+  return readFileAsDataUri(file);
+}
+
+/**
+ * 붙여 둔 레퍼런스를 보낼 크기로 줄인다.
+ *
+ * 줄이기는 **실패해도 원본을 돌려준다**(``shrinkReferenceDataUri``). 그래서 줄인 뒤에 한
+ * 번 더 잰다 — 줄이기가 못 돈 큰 그림이 그대로 서버까지 가서 422 로 돌아오면, 유저는
+ * 붙이는 자리가 아니라 제출 자리에서 실패를 본다.
+ *
+ * 크기(``inputTokens``)도 여기서 함께 잰다. 판독 값이 그 크기로 정해지는데, 재는 자리를
+ * 따로 두면 그림을 한 번 더 디코딩하게 된다. 못 쟀으면 0 이고, 값은 비싼 쪽으로 잡힌다.
+ *
+ * @returns 줄인 data URI, 또는 그래도 상한을 넘겼으면 이유.
+ */
+export async function finalizeReferenceDataUri(
+  original: string,
+): Promise<{ uri: string; inputTokens: number } | { error: string }> {
+  const shrunk = await shrinkReferenceDataUri(original);
+  if (dataUriByteLength(shrunk.uri) > MAX_REFERENCE_UPLOAD_BYTES) {
+    const limit = Math.round(MAX_REFERENCE_UPLOAD_BYTES / (1024 * 1024));
+    return {
+      error: `참고 사진을 ${limit}MB 아래로 줄이지 못했어요. 더 작은 그림을 써 주세요.`,
+    };
+  }
+  return {
+    uri: shrunk.uri,
+    inputTokens: estimateImageInputTokens(shrunk.width, shrunk.height),
+  };
+}
+
+function readFileAsDataUri(file: File): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onloadend = () =>
+      typeof reader.result === "string"
+        ? resolve(reader.result)
+        : reject(new Error("참고 사진을 읽지 못했어요."));
+    reader.onerror = () => reject(new Error("참고 사진을 읽지 못했어요."));
+    reader.readAsDataURL(file);
+  });
+}
+
+/** 셀러가 "1번 이미지"라고 쓰므로 화면도 1부터 센다. */
+export function referenceOrdinal(index: number): string {
+  return `${index + 1}번`;
+}
+
+/* ---- 판독 크레딧 ------------------------------------------------------------ *
+ *
+ * 판독은 **선차감**이다. 그래서 값은 누르기 전에 화면에 떠 있어야 하고, 그러려면 화면이
+ * 서버와 **같은 공식**을 갖고 있어야 한다. 서버가 실제 usage 가 아니라 추정으로 청구하는
+ * 이유도 이것이다(``app/services/detail_page/design_brief.py``) — 미리 말해 준 값과 실제
+ * 청구가 다르면 그건 안내가 아니다.
+ *
+ * 값을 정하는 것은 장수가 아니라 **그림의 크기**다. 비전 입력은 픽셀이 아니라 512px 타일
+ * 수로 청구되므로, 정사각 썸네일과 세로로 긴 상세페이지 캡쳐는 같은 한 장이어도 값이
+ * 두 배 가까이 벌어진다.
+ */
+
+const IMAGE_TOKENS_BASE = 85;
+const IMAGE_TOKENS_PER_TILE = 170;
+const IMAGE_TILE_PX = 512;
+const IMAGE_SHORT_SIDE_PX = 768;
+const IMAGE_LONG_SIDE_PX = 2048;
+
+/**
+ * 크기를 못 잰 그림 한 장으로 잡는 토큰. 서버의 ``UNKNOWN_IMAGE_TOKENS`` 와 같다.
+ *
+ * 디코더가 못 읽는 파일이면 크기를 모르는 채로 값을 말해야 한다. 그때 싸게 잡으면
+ * 화면이 말한 값보다 실제 청구가 커진다 — 모르는 쪽은 **비싸게** 잡아야 안전하다.
+ */
+export const UNKNOWN_IMAGE_TOKENS = 1445;
+
+/** 그림을 뺀 나머지 입력(시스템 프롬프트 + 딱지 + 지시)의 대략치. 서버와 같은 값. */
+const BRIEF_PROMPT_OVERHEAD_TOKENS = 1100;
+
+/** 판독 출력의 대략치. 몇 장을 붙이든 돌려주는 것은 같은 크기의 JSON 한 덩이다. */
+const BRIEF_OUTPUT_ALLOWANCE_TOKENS = 500;
+
+/** 판독 모델(gpt-5.6-luna) USD per 1M = [입력, 출력]. 서버 단가표와 같아야 한다. */
+const BRIEF_MODEL_PRICE_USD_PER_MILLION = [0.2, 1.2] as const;
+
+/** 원가 → 크레딧 환산. 카피·재저작과 **같은 환율**이다(원가 1.5원 = 1크레딧). */
+const USD_TO_KRW_RATE = 1500;
+const KRW_PER_CREDIT = 1.5;
+
+/**
+ * 그림 한 장이 비전 입력에서 차지하는 토큰. 서버의 ``estimate_image_input_tokens``.
+ *
+ * 긴 변을 2048 안에, 그다음 짧은 변을 768 로 **줄이기만** 한다(작은 그림을 키우면 없는
+ * 비용이 생긴다). 크기를 모르면 {@link UNKNOWN_IMAGE_TOKENS}.
+ */
+export function estimateImageInputTokens(width: number, height: number): number {
+  let w = Math.floor(Number(width) || 0);
+  let h = Math.floor(Number(height) || 0);
+  if (w <= 0 || h <= 0) return UNKNOWN_IMAGE_TOKENS;
+
+  const longest = Math.max(w, h);
+  if (longest > IMAGE_LONG_SIDE_PX) {
+    const scale = IMAGE_LONG_SIDE_PX / longest;
+    w = Math.max(1, Math.round(w * scale));
+    h = Math.max(1, Math.round(h * scale));
+  }
+  const shortest = Math.min(w, h);
+  if (shortest > IMAGE_SHORT_SIDE_PX) {
+    const scale = IMAGE_SHORT_SIDE_PX / shortest;
+    w = Math.max(1, Math.round(w * scale));
+    h = Math.max(1, Math.round(h * scale));
+  }
+  const tiles = Math.ceil(w / IMAGE_TILE_PX) * Math.ceil(h / IMAGE_TILE_PX);
+  return IMAGE_TOKENS_BASE + IMAGE_TOKENS_PER_TILE * tiles;
+}
+
+/**
+ * 붙여 둔 레퍼런스를 읽는 데 드는 크레딧. 서버의 ``estimate_brief_credits`` 와 같은 값을
+ * 낸다 — 다르면 화면이 말한 값과 청구가 어긋난다.
+ *
+ * @param imageTokens 장별 입력 토큰. 못 잰 장은 0 으로 넣으면 비싼 쪽으로 잡는다.
+ */
+export function estimateBriefCredits(imageTokens: number[]): number {
+  if (!imageTokens.length) return 0;
+  const [inputPrice, outputPrice] = BRIEF_MODEL_PRICE_USD_PER_MILLION;
+  const inputTokens =
+    BRIEF_PROMPT_OVERHEAD_TOKENS +
+    imageTokens.reduce(
+      (sum, tokens) => sum + (tokens > 0 ? tokens : UNKNOWN_IMAGE_TOKENS),
+      0,
+    );
+  const costUsd =
+    (inputTokens / 1_000_000) * inputPrice +
+    (BRIEF_OUTPUT_ALLOWANCE_TOKENS / 1_000_000) * outputPrice;
+  if (costUsd <= 0) return 0;
+  return Math.max(1, Math.ceil((costUsd * USD_TO_KRW_RATE) / KRW_PER_CREDIT));
+}

package/lib/detail-page/distribute.ts

@@ -0,0 +1,89 @@
+/**
+ * 선택 요소끼리 **간격**을 고르게. Figma·Canva의 distribute.
+ *
+ * 정렬(``alignInFrame``)은 기준 상자 안에서 한 줄로 세우는 것이고, 이건 이미 흩어져
+ * 있는 것들의 사이를 고르게 벌리는 것이다. 아이콘 3~5개를 나란히 놓는 배치에서
+ * 지금까지는 매번 눈대중이었다.
+ *
+ * **중심 간격이 아니라 여백을 고르게 한다.** 크기가 다른 요소들에서 중심을 등간격으로
+ * 두면 큰 것 옆이 좁아 보인다 — 눈이 재는 건 사이 여백이다.
+ */
+
+export type DistributeAxis = "x" | "y";
+
+export type DistributeItem = {
+  id: string;
+  /** 축 방향 시작 좌표(x 또는 y). */
+  start: number;
+  /** 축 방향 크기(width 또는 height). */
+  size: number;
+};
+
+/**
+ * 각 요소가 가야 할 시작 좌표. 양 끝은 **그대로 둔다** — 사용자가 잡아 둔 전체 폭이
+ * 안 변해야 결과가 예측된다.
+ *
+ * 셋 미만이거나 전체 폭이 없으면 null(버튼을 비활성).
+ */
+export function distributeCoords(
+  items: ReadonlyArray<DistributeItem>,
+): Map<string, number> | null {
+  if (items.length < 3) return null;
+  const sorted = [...items].sort((a, b) => a.start - b.start);
+  const first = sorted[0];
+  const last = sorted[sorted.length - 1];
+  const span = last.start + last.size - first.start;
+  if (!Number.isFinite(span) || span <= 0) return null;
+
+  const content = sorted.reduce((sum, it) => sum + it.size, 0);
+  // 겹쳐 있으면 음수가 나온다 — 그대로 쓴다. 고르게 겹치는 게 제멋대로 겹치는 것보다
+  // 낫고, 사용자가 폭을 넓히면 바로 풀린다.
+  const gap = (span - content) / (sorted.length - 1);
+
+  const out = new Map<string, number>();
+  let cursor = first.start;
+  for (const it of sorted) {
+    out.set(it.id, Math.round(cursor));
+    cursor += it.size + gap;
+  }
+  // 반올림이 쌓여 마지막이 밀리지 않게 끝은 못 박는다.
+  out.set(last.id, Math.round(last.start));
+  return out;
+}
+
+export type DistributeElement = {
+  id: string;
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  parent?: unknown;
+};
+
+/**
+ * 배분할 수 있는 선택인가.
+ *
+ * 셋 이상이면서 **부모가 같아야** 한다. 그룹 자식과 최상위 요소가 섞이면 좌표계가
+ * 달라(그룹 자식의 x/y는 그룹 로컬 공간) 뒤섞인 결과가 나온다.
+ */
+export function canDistribute(els: ReadonlyArray<DistributeElement>): boolean {
+  if (els.length < 3) return false;
+  const parent = els[0].parent;
+  return els.every((el) => el.parent === parent);
+}
+
+/** 축 좌표를 뽑아 배분 항목으로. 숫자가 아닌 값이 하나라도 있으면 null. */
+export function toItems(
+  els: ReadonlyArray<DistributeElement>,
+  axis: DistributeAxis,
+): DistributeItem[] | null {
+  const out: DistributeItem[] = [];
+  for (const el of els) {
+    const start = axis === "x" ? el.x : el.y;
+    const size = axis === "x" ? el.width : el.height;
+    if (typeof start !== "number" || typeof size !== "number") return null;
+    if (!Number.isFinite(start) || !Number.isFinite(size)) return null;
+    out.push({ id: el.id, start, size });
+  }
+  return out;
+}

package/lib/detail-page/editor-routes.ts

@@ -0,0 +1,10 @@
+const PRODUCTION_EDITOR_PATH =
+  "/branding/detail-page-generator/editor";
+
+/** Routes that render the shared full-screen detail-page editor chrome. */
+export function isDetailPageEditorPath(pathname: string): boolean {
+  return (
+    pathname.startsWith(PRODUCTION_EDITOR_PATH) ||
+    pathname.startsWith("/dev-canvas")
+  );
+}

package/lib/detail-page/element-recents.ts

@@ -0,0 +1,167 @@
+/**
+ * 요소 서랍의 "최근 사용 / 즐겨찾기".
+ *
+ * 상세페이지는 같은 배지·구분선·체크 아이콘을 20섹션 내내 반복해서 넣는다. 그때마다 다시
+ * 검색하는 것이 지금의 값이라 **검색의 절반은 "다시 안 찾기"** 다.
+ *
+ * ## 왜 마크업을 통째로 들고 있나
+ *
+ * 식별자(`"tabler:truck"`)만 저장하면 다시 넣을 때 제공처를 또 두드려야 하고, 세트에서
+ * 아이콘이 사라지면 최근 목록이 죽는다. 마크업은 아이콘 하나에 수백 바이트라 통째로
+ * 들고 있는 편이 싸고 확실하다.
+ *
+ * ## 왜 서버가 아니라 localStorage 인가
+ *
+ * 브랜드가 아니라 **사람의 손버릇**이다. 같은 브랜드를 여럿이 만져도 각자 최근이 다르고,
+ * 이걸 서버에 두면 테이블·RLS·동기화가 붙는데 값에 비해 비싸다. 오래 두고 팀이 공유할
+ * 자산은 이미 "내 도형"이 맡는다.
+ */
+
+const STORAGE_KEY = "leviosa.detail-page.element-recents";
+
+/** 최근은 짧게. 길면 스트립이 스크롤이 되고 스트립인 이유가 사라진다. */
+const RECENT_MAX = 24;
+/** 즐겨찾기는 사람이 직접 고른 것이라 넉넉히. */
+const PINNED_MAX = 48;
+/** localStorage 한도(보통 5MB)를 혼자 먹지 않게. 넘치면 오래된 최근부터 버린다. */
+const BYTE_BUDGET = 512 * 1024;
+
+export type ElementRecent = {
+  /** 같은 것인지 판정하는 키. 아이콘은 `"tabler:truck"`, 그 밖은 용도별 접두사를 붙인다. */
+  key: string;
+  markup: string;
+  viewBox: string;
+  /** 툴팁에 쓰는 사람 말. 없으면 키를 쓴다. */
+  label?: string;
+};
+
+export type ElementRecentsState = {
+  recent: ElementRecent[];
+  pinned: ElementRecent[];
+};
+
+const EMPTY: ElementRecentsState = { recent: [], pinned: [] };
+
+let cache: ElementRecentsState | null = null;
+const listeners = new Set<() => void>();
+
+function isEntry(value: unknown): value is ElementRecent {
+  if (!value || typeof value !== "object") return false;
+  const entry = value as Record<string, unknown>;
+  return (
+    typeof entry.key === "string" &&
+    entry.key.length > 0 &&
+    typeof entry.markup === "string" &&
+    entry.markup.length > 0 &&
+    typeof entry.viewBox === "string"
+  );
+}
+
+function sanitize(list: unknown, max: number): ElementRecent[] {
+  if (!Array.isArray(list)) return [];
+  const out: ElementRecent[] = [];
+  const seen = new Set<string>();
+  for (const item of list) {
+    if (!isEntry(item) || seen.has(item.key)) continue;
+    seen.add(item.key);
+    out.push({
+      key: item.key,
+      markup: item.markup,
+      viewBox: item.viewBox,
+      ...(typeof item.label === "string" ? { label: item.label } : {}),
+    });
+    if (out.length >= max) break;
+  }
+  return out;
+}
+
+function read(): ElementRecentsState {
+  if (cache) return cache;
+  if (typeof window === "undefined") return EMPTY;
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    if (!raw) {
+      cache = EMPTY;
+      return cache;
+    }
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    cache = {
+      recent: sanitize(parsed.recent, RECENT_MAX),
+      pinned: sanitize(parsed.pinned, PINNED_MAX),
+    };
+  } catch {
+    // 남이 망가뜨린 값에 편집기가 멈추면 안 된다.
+    cache = EMPTY;
+  }
+  return cache;
+}
+
+/**
+ * 예산을 넘으면 **최근 목록의 꼬리부터** 버린다. 즐겨찾기는 사람이 고른 것이라 마지막까지
+ * 지킨다. 그래도 안 되면 저장을 포기한다 — 최근 목록 때문에 편집이 막히면 안 된다.
+ */
+function write(next: ElementRecentsState): void {
+  if (typeof window === "undefined") return;
+  const state: ElementRecentsState = {
+    recent: next.recent.slice(0, RECENT_MAX),
+    pinned: next.pinned.slice(0, PINNED_MAX),
+  };
+  for (;;) {
+    const payload = JSON.stringify(state);
+    if (payload.length <= BYTE_BUDGET) {
+      try {
+        window.localStorage.setItem(STORAGE_KEY, payload);
+      } catch {
+        // 용량 초과·프라이빗 모드. 이번 세션 동안 메모리로만 산다.
+      }
+      break;
+    }
+    if (!state.recent.length) break;
+    state.recent = state.recent.slice(0, -1);
+  }
+  cache = state;
+  for (const listener of listeners) listener();
+}
+
+export function subscribeElementRecents(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function getElementRecents(): ElementRecentsState {
+  return read();
+}
+
+/** 넣은 것을 최근 맨 앞으로. 이미 있으면 앞으로 끌어올린다(LRU). */
+export function rememberElement(entry: ElementRecent): void {
+  const state = read();
+  write({
+    pinned: state.pinned,
+    recent: [entry, ...state.recent.filter((item) => item.key !== entry.key)],
+  });
+}
+
+/** 즐겨찾기 토글. 새로 꽂으면 맨 앞에 온다. */
+export function toggleElementPin(entry: ElementRecent): void {
+  const state = read();
+  const has = state.pinned.some((item) => item.key === entry.key);
+  write({
+    recent: state.recent,
+    pinned: has
+      ? state.pinned.filter((item) => item.key !== entry.key)
+      : [entry, ...state.pinned],
+  });
+}
+
+export function isElementPinned(key: string): boolean {
+  return read().pinned.some((item) => item.key === key);
+}
+
+export function clearElementRecents(): void {
+  write({ recent: [], pinned: read().pinned });
+}
+
+/** 테스트용 — 모듈 캐시를 비운다. */
+export function resetElementRecentsCache(): void {
+  cache = null;
+}