@leviosa-ai/detail-page-editor 0.1.0

package/lib/detail-page/icon-search.ts

@@ -0,0 +1,257 @@
+/**
+ * 아이콘 검색 결과를 그리드에 뿌릴 수 있는 모양으로 다듬는 순수 함수들.
+ *
+ * 제공처(Iconify)가 돌려주는 것은 `"tabler:truck"` 같은 **문자열 배열**과 세트별 메타뿐이다.
+ * 그대로 뿌리면 세 가지가 깨진다.
+ *
+ *  1. 개수가 큰 세트가 격자를 독점한다(`material-symbols` 혼자 15,585개다).
+ *  2. 같은 개념이 변형 이름으로 도배된다 — "truck" 28건 중 `ph:truck-*`만 5건이다.
+ *  3. 선 아이콘과 채움 아이콘이 뒤섞여 상세페이지에 넣으면 바로 티가 난다.
+ *
+ * 그래서 **스타일로 거르고 → 세트를 섞고 → 같은 개념을 접는다.** 이 순서가 중요하다.
+ * 접기를 먼저 하면 한 세트가 대표를 다 가져간다.
+ *
+ * 라이선스 판정도 여기 있다. 세트 이름 목록을 손으로 관리하지 않고 제공처가 주는
+ * `license.spdx`를 본다 — 상류가 바뀌어도 무단 자산이 통과하지 못한다.
+ */
+
+export type IconStyle = "stroke" | "fill";
+
+/** 제공처의 세트 메타 중 우리가 쓰는 부분만. */
+export type IconCollectionMeta = {
+  name?: string;
+  license?: { title?: string; spdx?: string; url?: string };
+  /** true면 색이 구워져 있다(Twemoji 등) — 브랜드 색 치환이 안 먹는다. */
+  palette?: boolean;
+  tags?: string[];
+  category?: string;
+};
+
+export type IconHit = {
+  /** `"tabler:truck"` — 제공처 식별자 그대로. */
+  id: string;
+  prefix: string;
+  name: string;
+  /** 변형 접미사를 뗀 개념 이름. 접기 기준이다. */
+  concept: string;
+  style: IconStyle;
+};
+
+/**
+ * 제공처가 **표기를 지키기만 하면** 결과물에 출처를 안 박아도 되는 것들.
+ *
+ * CC BY(예: Font Awesome Free)는 뺐다. 아이콘은 고객 상세페이지에 그대로 박히는
+ * 결과물이라 저작자 표시를 붙일 자리가 없다 — 패널 하단 링크로 되는 스톡 사진과 다르다.
+ */
+export const ALLOWED_ICON_SPDX: readonly string[] = [
+  "MIT",
+  "ISC",
+  "Apache-2.0",
+  "CC0-1.0",
+  "Unlicense",
+];
+
+/**
+ * 이름 끝에 붙는 변형 접미사. 세트마다 표기가 다르다:
+ * Phosphor `-fill/-bold/-thin/-light/-duotone`, Tabler `-filled`,
+ * Remix `-line/-fill`, Material Symbols `-outline/-rounded/-sharp`(중첩된다).
+ */
+const VARIANT_SUFFIXES: readonly string[] = [
+  "outline",
+  "outlined",
+  "filled",
+  "fill",
+  "solid",
+  "line",
+  "duotone",
+  "twotone",
+  "two-tone",
+  "rounded",
+  "round",
+  "sharp",
+  "bold",
+  "light",
+  "thin",
+  "regular",
+];
+
+/** 접미사가 "채움"을 뜻하는 것들. 나머지는 세트 성격을 따른다. */
+const FILL_SUFFIXES = new Set(["fill", "filled", "solid", "duotone", "twotone", "two-tone"]);
+/** 접미사가 "선"을 뜻하는 것들. */
+const STROKE_SUFFIXES = new Set(["outline", "outlined", "line", "thin", "light"]);
+
+export function parseIconId(id: string): { prefix: string; name: string } | null {
+  const colon = id.indexOf(":");
+  if (colon <= 0 || colon === id.length - 1) return null;
+  return { prefix: id.slice(0, colon), name: id.slice(colon + 1) };
+}
+
+/**
+ * 이름에서 변형 접미사를 **모두** 떼어 개념만 남긴다.
+ * `desktop-access-disabled-outline-sharp` → `desktop-access-disabled`.
+ *
+ * 통째로 비어 버리는 이름(`tabler:line`)은 원문을 지킨다 — 그런 아이콘이 실제로 있다.
+ */
+export function conceptOf(name: string): string {
+  let out = name;
+  for (;;) {
+    const hit = VARIANT_SUFFIXES.find((suffix) => out.endsWith(`-${suffix}`));
+    if (!hit) break;
+    const next = out.slice(0, -(hit.length + 1));
+    if (!next) break;
+    out = next;
+  }
+  return out;
+}
+
+/** 이름에 붙은 변형 접미사 목록(뒤에서 앞으로). 없으면 빈 배열. */
+function suffixesOf(name: string): string[] {
+  const out: string[] = [];
+  let rest = name;
+  for (;;) {
+    const hit = VARIANT_SUFFIXES.find((suffix) => rest.endsWith(`-${suffix}`));
+    if (!hit) break;
+    const next = rest.slice(0, -(hit.length + 1));
+    if (!next) break;
+    out.push(hit);
+    rest = next;
+  }
+  return out;
+}
+
+/**
+ * 이 아이콘이 선인지 채움인지.
+ *
+ * 이름의 접미사가 먼저다 — 한 세트 안에 둘 다 있는 경우가 흔하다(Phosphor, Remix).
+ * 접미사가 말이 없으면 세트 메타의 `"Uses Stroke"` 태그를 본다(Lucide·Tabler가 여기 걸린다).
+ */
+export function iconStyleOf(name: string, meta?: IconCollectionMeta): IconStyle {
+  for (const suffix of suffixesOf(name)) {
+    if (FILL_SUFFIXES.has(suffix)) return "fill";
+    if (STROKE_SUFFIXES.has(suffix)) return "stroke";
+  }
+  return meta?.tags?.includes("Uses Stroke") ? "stroke" : "fill";
+}
+
+/** 라이선스와 색 구움 여부로 세트를 통과시킬지 정한다. */
+export function isAllowedCollection(
+  meta: IconCollectionMeta | undefined,
+  allowed: readonly string[] = ALLOWED_ICON_SPDX,
+): boolean {
+  if (!meta) return false;
+  // 색이 구워진 세트는 브랜드 색 치환이 안 먹는다 — 라이선스와 무관하게 뺀다.
+  if (meta.palette === true) return false;
+  const spdx = meta.license?.spdx;
+  return typeof spdx === "string" && allowed.includes(spdx);
+}
+
+/**
+ * 세트별로 한 개씩 돌아가며 뽑는다. 세트 안의 순서(제공처의 관련도)는 지킨다.
+ *
+ * `order`를 주면 그 순서로 돈다 — 우리가 정한 세트 우선순위를 반영하는 자리다.
+ * 목록에 없는 세트는 뒤에 붙는다.
+ */
+export function interleaveBySet<T extends { prefix: string }>(
+  items: T[],
+  order: readonly string[] = [],
+): T[] {
+  const buckets = new Map<string, T[]>();
+  for (const item of items) {
+    const bucket = buckets.get(item.prefix);
+    if (bucket) bucket.push(item);
+    else buckets.set(item.prefix, [item]);
+  }
+
+  const prefixes = [...buckets.keys()].sort((a, b) => {
+    const ai = order.indexOf(a);
+    const bi = order.indexOf(b);
+    if (ai === bi) return 0;
+    if (ai < 0) return 1;
+    if (bi < 0) return -1;
+    return ai - bi;
+  });
+
+  const out: T[] = [];
+  for (let round = 0; out.length < items.length; round += 1) {
+    let moved = false;
+    for (const prefix of prefixes) {
+      const bucket = buckets.get(prefix)!;
+      if (round < bucket.length) {
+        out.push(bucket[round]);
+        moved = true;
+      }
+    }
+    if (!moved) break;
+  }
+  return out;
+}
+
+export type RankOptions = {
+  /** 제공처 검색 응답의 `icons` 배열(`"prefix:name"`). 순서가 관련도다. */
+  icons: readonly string[];
+  /** 제공처 검색 응답의 `collections`. */
+  collections: Readonly<Record<string, IconCollectionMeta>>;
+  /** 보고 싶은 축. 안 주면 안 거른다. */
+  style?: IconStyle;
+  /** 세트 우선순위. 인터리브 순서가 된다. */
+  order?: readonly string[];
+  /** 허용 SPDX. 기본은 `ALLOWED_ICON_SPDX`. */
+  allowedSpdx?: readonly string[];
+  /** 최대 개수. */
+  limit?: number;
+};
+
+/**
+ * 원시 결과 → 그리드에 뿌릴 목록.
+ *
+ * 거르기(라이선스·스타일) → 섞기(세트 인터리브) → 접기(같은 개념 하나) 순이다.
+ * 접기를 먼저 하면 목록 앞을 차지한 세트가 대표를 독식한다.
+ */
+export function rankIcons({
+  icons,
+  collections,
+  style,
+  order = [],
+  allowedSpdx = ALLOWED_ICON_SPDX,
+  limit,
+}: RankOptions): IconHit[] {
+  const kept: IconHit[] = [];
+  for (const id of icons) {
+    const parsed = parseIconId(id);
+    if (!parsed) continue;
+    const meta = collections[parsed.prefix];
+    if (!isAllowedCollection(meta, allowedSpdx)) continue;
+
+    const hitStyle = iconStyleOf(parsed.name, meta);
+    if (style && hitStyle !== style) continue;
+
+    kept.push({
+      id,
+      prefix: parsed.prefix,
+      name: parsed.name,
+      concept: conceptOf(parsed.name),
+      style: hitStyle,
+    });
+  }
+
+  const mixed = interleaveBySet(kept, order);
+
+  const seen = new Set<string>();
+  const out: IconHit[] = [];
+  for (const hit of mixed) {
+    if (seen.has(hit.concept)) continue;
+    seen.add(hit.concept);
+    out.push(hit);
+    if (limit && out.length >= limit) break;
+  }
+  return out;
+}
+
+/** `{prefix: [name, ...]}` — 마크업을 세트당 한 번에 받기 위한 묶음. */
+export function groupByPrefix(hits: readonly IconHit[]): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const hit of hits) {
+    (out[hit.prefix] ??= []).push(hit.name);
+  }
+  return out;
+}

package/lib/detail-page/icons.ts

@@ -0,0 +1,67 @@
+/**
+ * 아이콘 검색 — 편집기 "요소 · 아이콘" 그룹이 쓰는 얇은 층.
+ *
+ * 검색은 우리 서버(`/api/icons`)를 거친다. 이유는 그 라우트 주석에 있다(라이선스 게이트 ·
+ * 한국어 확장 · 마크업 배치).
+ *
+ * 사진과 달리 **S3로 옮겨 담지 않는다.** 아이콘은 삽입하는 순간 마크업이 문서 안에
+ * 박히므로 저장된 상세페이지가 제공처 수명에 묶이지 않는다.
+ */
+
+import type { IconStyle } from "./icon-search";
+
+export type { IconStyle };
+
+/** 일반 아이콘과 브랜드 로고는 성격이 달라 그룹을 나눈다(로고는 상표다). */
+export type IconGroup = "icons" | "logos";
+
+export type IconItem = {
+  /** `"tabler:truck"` — 제공처 식별자. 최근 목록의 키로도 쓴다. */
+  id: string;
+  style: IconStyle;
+  /** 완성된 `<svg>` 마크업. 모노크롬 세트는 `currentColor`를 쓴다. */
+  markup: string;
+  viewBox: string;
+  /** 사람이 읽는 세트 이름 — 격자에는 안 쓰고 툴팁·출처에만 쓴다. */
+  setName: string;
+  /** 통과한 SPDX. 화면에는 안 쓰지만 사고가 났을 때 추적할 수 있어야 한다. */
+  license: string;
+};
+
+export type IconSearchResponse = {
+  items: IconItem[];
+  group: IconGroup;
+  /** 0-based 쪽 번호. */
+  page: number;
+  /** 다음 쪽이 있다. 격자 바닥에 닿으면 이어 받는다. */
+  hasMore: boolean;
+  /** 전체 상한에서 잘렸다는 뜻. 패널이 "검색어를 좁혀 보라"고 안내한다. */
+  truncated: boolean;
+};
+
+export type IconSearchQuery = {
+  query: string;
+  group?: IconGroup;
+  style?: IconStyle;
+  /** 0-based. 안 주면 첫 쪽. */
+  page?: number;
+  signal?: AbortSignal;
+};
+
+export async function searchIcons({
+  query,
+  group = "icons",
+  style,
+  page = 0,
+  signal,
+}: IconSearchQuery): Promise<IconSearchResponse> {
+  const params = new URLSearchParams();
+  if (query.trim()) params.set("q", query.trim());
+  if (group !== "icons") params.set("group", group);
+  if (style) params.set("style", style);
+  if (page > 0) params.set("page", String(page));
+
+  const response = await fetch(`/api/icons?${params.toString()}`, { signal });
+  if (!response.ok) throw new Error(`icons ${response.status}`);
+  return (await response.json()) as IconSearchResponse;
+}

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

@@ -0,0 +1,121 @@
+// 편집기 AI 이미지(개인 생성 / 우측 실시간 편집) 크레딧 게이트 유틸.
+//
+// 백엔드는 잔액을 못 읽어 원자적 decrement가 <1배에서만 실패한다. 안정성을 위한
+// 1.5배 안전 마진은 프론트가 생성 전 soft 게이트로 건다(잔액 < 1.5×비용이면 차단).
+// 티어별 feature 키는 백엔드 config 기본값과 일치해야 하며, 실제 단가는 중앙
+// Supabase feature_costs에서 읽는다(useCredits). 단가 0(미구성)이면 게이트 비활성.
+
+export const IMAGE_CREDIT_MULTIPLIER = 1.5;
+export const DEFAULT_IMAGE_TIER: ImageTier = "pro";
+
+export type ImageTier = "basic" | "pro" | "max";
+
+/** 선택 UI에 노출할 티어 순서(저→고 품질). */
+export const IMAGE_TIERS: ImageTier[] = ["basic", "pro", "max"];
+
+export const IMAGE_FEATURE_KEYS: Record<ImageTier, string> = {
+  basic: "detail_page_image_basic",
+  pro: "detail_page_image_pro",
+  max: "detail_page_image_max",
+};
+
+/**
+ * AI GIF 생성 feature 키(백엔드 `DETAIL_PAGE_GIF_FEATURE` 기본값과 일치해야 함).
+ * 단가는 feature_costs에서 읽으며 현재 50크레딧으로 등록.
+ */
+export const GIF_FEATURE_KEY = "detail_page_gif";
+
+/**
+ * 텍스트→GIF 이펙트 feature 키(백엔드 `DETAIL_PAGE_TEXT_GIF_FEATURE` 기본값과 일치).
+ * 헤드리스 렌더라 원가 ~0이라 basic 이미지 티어급 소액(5크레딧)으로 feature_costs 등록.
+ */
+export const TEXT_GIF_FEATURE_KEY = "detail_page_text_gif";
+
+/**
+ * 이미지→GIF 이펙트 feature 키(백엔드 `DETAIL_PAGE_IMAGE_GIF_FEATURE` 기본값과 일치).
+ * PIL 프레임 합성이라 AI 원가는 없지만, 홀로그램 포일은 물체 검출(배경제거) 1콜이
+ * 붙으므로 텍스트 GIF보다 높게 feature_costs에 등록한다.
+ */
+export const IMAGE_GIF_FEATURE_KEY = "detail_page_image_gif";
+
+/**
+ * 수치→GIF(카운트업·셀 차오름) feature 키(백엔드 `DETAIL_PAGE_DATA_GIF_FEATURE` 기본값과
+ * 일치). 텍스트 GIF와 **같은 렌더러**라 원가가 같아 단가도 5크레딧으로 맞췄다.
+ */
+export const DATA_GIF_FEATURE_KEY = "detail_page_data_gif";
+
+/**
+ * 배경 제거(누끼) feature 키(백엔드 `DETAIL_PAGE_BG_REMOVE_FEATURE` 기본값과 일치).
+ * 배경제거 모델 1콜이 전부라 이미지 생성보다 훨씬 싸고, 홀로그램 포일이 쓰는 컷아웃
+ * 캐시를 공유해 같은 이미지를 다시 눌러도 모델 왕복이 없다. 1크레딧으로 등록.
+ */
+export const BG_REMOVE_FEATURE_KEY = "detail_page_bg_remove";
+
+/**
+ * 티어별 표시 메타. 모델·품질 설명은 백엔드 `_TIER_MODEL_CONFIG`와 일치해야 한다:
+ * basic=chatgpt-image-latest/low, pro(기본)=chatgpt-image-latest/medium,
+ * max=gpt-image-2/high.
+ */
+export const IMAGE_TIER_META: Record<
+  ImageTier,
+  {
+    /** 드롭다운에 보이는 짧은 이름. */
+    label: string;
+    /** 한 줄 품질 요약. */
+    quality: string;
+    /** 툴팁 상세(속도·용도 트레이드오프). */
+    description: string;
+    /** 배지/추천 표기(선택). */
+    badge?: string;
+    /**
+     * 라이브 단가(feature_costs)를 못 읽는 데모(dev-canvas)에서 쓰는 대체 단가.
+     * 실제 편집기는 useCredits의 getCost로 덮어쓴다. 값은 중앙 feature_costs와
+     * 맞춰야 한다(2026-07-20: 5 / 20 / 70).
+     */
+    fallbackCost: number;
+  }
+> = {
+  basic: {
+    label: "베이직",
+    quality: "빠르고 저렴 · 기본 품질",
+    description:
+      "가장 빠르고 저렴해요. 초안·썸네일처럼 가볍게 여러 장 시도할 때 좋아요. (저화질)",
+    fallbackCost: 5,
+  },
+  pro: {
+    label: "프로",
+    quality: "권장 · 균형잡힌 품질/속도",
+    description:
+      "품질과 속도의 균형이 가장 좋아 기본값으로 권장해요. 대부분의 상세페이지 컷에 적합합니다. (중화질)",
+    badge: "추천",
+    fallbackCost: 20,
+  },
+  max: {
+    label: "맥스",
+    quality: "최고 품질 · 느리고 비쌈",
+    description:
+      "가장 정교한 최고 화질이지만 생성이 느리고 크레딧이 많이 들어요. 최종 확정 컷에만 쓰는 걸 권장해요. (고화질)",
+    fallbackCost: 70,
+  },
+};
+
+export function imageFeatureKey(tier?: string): string {
+  return IMAGE_FEATURE_KEYS[(tier as ImageTier) ?? DEFAULT_IMAGE_TIER] ?? IMAGE_FEATURE_KEYS.pro;
+}
+
+/** 데모(라이브 단가 미주입)에서 쓸 티어별 대체 단가 맵. */
+export const IMAGE_TIER_FALLBACK_COST: Record<ImageTier, number> = {
+  basic: IMAGE_TIER_META.basic.fallbackCost,
+  pro: IMAGE_TIER_META.pro.fallbackCost,
+  max: IMAGE_TIER_META.max.fallbackCost,
+};
+
+/** 생성/편집에 필요한 최소 보유 크레딧(비용의 1.5배, 올림). */
+export function imageCreditRequired(cost: number): number {
+  return Math.ceil(Math.max(0, cost) * IMAGE_CREDIT_MULTIPLIER);
+}
+
+/** 잔액이 1.5배 미만이면 차단. 비용 0(미구성)이면 항상 허용. */
+export function isImageCreditBlocked(cost: number, balance: number): boolean {
+  return cost > 0 && balance < imageCreditRequired(cost);
+}

package/lib/detail-page/image-data-uri.ts

@@ -0,0 +1,29 @@
+/**
+ * 편집기 이미지 src 를 **캔버스에 그릴 수 있는** data URI 로 바꾼다.
+ *
+ * 주석 합성은 밑그림을 캔버스에 그린 다음 ``toDataURL`` 로 뽑는다. 교차 출처 이미지를
+ * 그리면 그 캔버스가 오염돼 ``toDataURL`` 이 SecurityError 로 터진다 — 그것도 유저가
+ * 다 그리고 제출을 누른 **다음에야**. 그래서 그리기 전에 바이트를 먼저 확보한다.
+ *
+ * 실패하면 ``null``. 호출부는 그때 "그림으로 지시"를 열지 않거나 글로만 받는다.
+ */
+export async function toDrawableDataUri(src: string): Promise<string | null> {
+  const cleaned = String(src || "").trim();
+  if (!cleaned) return null;
+  if (cleaned.startsWith("data:")) return cleaned;
+  try {
+    const res = await fetch(cleaned);
+    if (!res.ok) return null;
+    const blob = await res.blob();
+    return await new Promise<string | null>((resolve) => {
+      const reader = new FileReader();
+      reader.onloadend = () =>
+        resolve(typeof reader.result === "string" ? reader.result : null);
+      reader.onerror = () => resolve(null);
+      reader.readAsDataURL(blob);
+    });
+  } catch {
+    // 교차 출처·CORS 미허용. 원본 URL 을 그대로 돌려주면 캔버스가 오염되므로 안 준다.
+    return null;
+  }
+}

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

@@ -0,0 +1,75 @@
+/**
+ * Insert a personal image/GIF onto the active Canvas page.
+ *
+ * Every image is measured and placed at its own aspect ratio, fitted inside a
+ * box of 62% of the page. Stills used to drop in as a fixed ``62% × 62%``
+ * *square* regardless of the source: on a 750-wide page every asset landed at
+ * 465×465, and since Canvas cover-crops images, a tall product cutout was
+ * center-cropped to a square. Fitting to the real ratio makes the element match
+ * the source, so the cover-crop becomes a no-op.
+ *
+ * The box is capped on both axes — capping width alone let a tall cutout
+ * (e.g. 171×669) come in at 465×1817 and run off a short section page.
+ *
+ * GIFs are additionally tagged ``custom.detailPageGif`` so the exporter treats
+ * their section as animated even if the presigned URL lacks a ``.gif`` suffix.
+ */
+
+type AddElementOpts = Record<string, unknown>;
+type PageLike = {
+  computedWidth: number;
+  computedHeight: number;
+  addElement: (opts: AddElementOpts) => unknown;
+};
+type StoreLike = { activePage?: PageLike; pages: PageLike[] };
+
+const BOX_RATIO = 0.62;
+
+export function insertPersonalImage(
+  store: unknown,
+  src: string,
+  opts: { isGif?: boolean } = {},
+): void {
+  const s = store as StoreLike;
+  const page = s.activePage ?? s.pages[0];
+  if (!page) return;
+  const maxWidth = page.computedWidth * BOX_RATIO;
+  const maxHeight = page.computedHeight * BOX_RATIO;
+
+  const place = (width: number, height: number) => {
+    page.addElement({
+      type: "image",
+      src,
+      x: Math.round((page.computedWidth - width) / 2),
+      y: Math.round((page.computedHeight - height) / 2),
+      width,
+      height,
+      // GIF는 레이어 트리에서 "image-2" 같은 자동 이름 대신 "GIF"로 보이게 이름을
+      // 박고, 내보내기가 이 섹션을 애니메이션으로 다루도록 custom 플래그를 단다.
+      ...(opts.isGif ? { name: "GIF", custom: { detailPageGif: true } } : {}),
+    });
+  };
+
+  /** 원본 비율을 박스 안에 맞춘다. 어느 축으로도 박스를 넘지 않는다. */
+  const fit = (naturalWidth: number, naturalHeight: number) => {
+    if (naturalWidth <= 0 || naturalHeight <= 0) {
+      place(Math.round(maxWidth), Math.round(maxWidth));
+      return;
+    }
+    const scale = Math.min(maxWidth / naturalWidth, maxHeight / naturalHeight);
+    place(Math.round(naturalWidth * scale), Math.round(naturalHeight * scale));
+  };
+
+  // Load with the same ``crossOrigin`` mode Canvas/Konva uses for the canvas.
+  // The S3 bucket DOES send CORS headers, but only when the request carries an
+  // ``Origin`` (and it omits ``Vary: Origin``): a no-CORS preload here caches an
+  // ACAO-less 200 that Konva's later crossOrigin load then reuses → blocked as
+  // "Can not load the image...". Matching the mode makes both share a CORS-safe
+  // cache entry. data: URIs never need CORS.
+  const img = new Image();
+  if (!src.startsWith("data:")) img.crossOrigin = "anonymous";
+  img.onload = () => fit(img.naturalWidth, img.naturalHeight);
+  // 측정 실패는 배치 실패가 아니다 — 예전처럼 정사각으로라도 넣는다.
+  img.onerror = () => place(Math.round(maxWidth), Math.round(maxWidth));
+  img.src = src;
+}

package/lib/detail-page/insert-shape.ts

@@ -0,0 +1,49 @@
+import { encodeSvgDataUri } from "../detail-page-canvas/export/svg";
+
+/**
+ * 공용/개인 도형(SVG 마크업)을 현재 페이지 중앙에 ``svg`` 요소로 삽입한다.
+ *
+ * Canvas svg 요소는 마크업을 ``src``에 data URI로 담는다(편집기의 인라인 렌더가
+ * el.src를 디코드한다). viewBox 종횡비를 유지하고, 아이콘이 과하게 커지지 않게
+ * 페이지 폭 대비 적당한 크기로 배치한다.
+ */
+
+type AddElementOpts = Record<string, unknown>;
+type PageLike = {
+  computedWidth: number;
+  computedHeight: number;
+  addElement: (opts: AddElementOpts) => unknown;
+};
+type StoreLike = { activePage?: PageLike; pages: PageLike[] };
+
+function aspectFromViewBox(viewBox: string): number {
+  const parts = viewBox.trim().split(/\s+/).map(Number);
+  if (parts.length === 4 && parts[2] > 0 && parts[3] > 0) {
+    return parts[2] / parts[3];
+  }
+  return 1;
+}
+
+export function insertShape(
+  store: unknown,
+  markup: string,
+  viewBox = "0 0 24 24",
+): void {
+  const s = store as StoreLike;
+  const page = s.activePage ?? s.pages[0];
+  if (!page || !markup) return;
+
+  const aspect = aspectFromViewBox(viewBox);
+  // 아이콘/장식이라 페이지 폭의 ~18%(상한 200px)로 얌전하게.
+  const width = Math.round(Math.min(page.computedWidth * 0.18, 200));
+  const height = Math.round(width / (aspect || 1));
+
+  page.addElement({
+    type: "svg",
+    src: encodeSvgDataUri(markup),
+    x: Math.round((page.computedWidth - width) / 2),
+    y: Math.round((page.computedHeight - height) / 2),
+    width,
+    height,
+  });
+}