@leviosa-ai/detail-page-editor 0.1.0

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

@@ -0,0 +1,251 @@
+/**
+ * 만든 GIF로 원본(텍스트·그룹·이미지·도형)을 **그 자리 그대로** 갈아 끼운다.
+ *
+ * 예전에는 결과 GIF를 페이지 가운데에 62% 폭으로 새로 얹었다. 그러면 원본은 그대로
+ * 남고 GIF는 엉뚱한 크기·자리에 떨어져서, 유저가 매번 지우고 옮기고 크기를 맞춰야 했다.
+ *
+ * 자리 계산은 **잎 요소들의 합집합 상자**로 한다. 스톡 편집기의 group은 캔버스에서 offset을
+ * 주지 않고 자식이 페이지 좌표를 그대로 들고 있어서(canvas/element.js의 group 렌더러는
+ * ``<Group>``에 x/y를 안 건다), 그룹 모델에 저장된 x/y/width/height는 실제로 보이는
+ * 상자와 어긋날 수 있다. 자식에서 다시 재는 게 유일하게 믿을 수 있는 값이다.
+ *
+ * 쌓임 순서(z-order)도 원본 자리를 따른다. ``page.addElement``는 페이지 맨 앞(children
+ * 끝)에 붙이므로, 그냥 두면 GIF가 항상 모든 요소 위로 튀어나와 원본이 뒤에 깔려 있던
+ * 관계가 무너진다. 그래서 넣은 뒤 ``page.setElementZIndex``로 원본이 있던 칸에 되돌린다.
+ *
+ * 원본이 **그룹 안**에 있었다면 GIF도 그 그룹 안 같은 칸에 넣는다(``layer-move``의
+ * 재부모화). 그래야 그룹 안에서의 앞뒤가 지켜지고, 나중에 그룹을 옮길 때 GIF도 따라간다.
+ */
+
+import { locate, moveLayer } from "./layer-move";
+
+export type ElementLike = {
+  id?: string;
+  type?: string;
+  x?: unknown;
+  y?: unknown;
+  width?: unknown;
+  height?: unknown;
+  rotation?: unknown;
+  cropX?: unknown;
+  cropY?: unknown;
+  cropWidth?: unknown;
+  cropHeight?: unknown;
+  children?: unknown;
+};
+
+export type Box = { x: number; y: number; width: number; height: number };
+
+type PageLike = {
+  id?: string;
+  computedWidth?: number;
+  computedHeight?: number;
+  children?: unknown;
+  addElement: (opts: Record<string, unknown>) => unknown;
+  /** 페이지와 그룹이 공통으로 노출하는 유일한 재정렬 API(index가 클수록 앞). */
+  setElementZIndex?: (id: string, index: number) => void;
+};
+
+type StoreLike = {
+  activePage?: PageLike;
+  pages: PageLike[];
+  deleteElements?: (ids: string[]) => void;
+  selectElements?: (ids: string[]) => void;
+};
+
+function num(value: unknown, fallback = 0): number {
+  const parsed = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+/** 그룹이면 잎(그룹이 아닌 자식)들, 아니면 자기 자신. */
+export function leafElements(els: ElementLike[]): ElementLike[] {
+  const out: ElementLike[] = [];
+  const walk = (el: ElementLike) => {
+    const children = Array.isArray(el.children)
+      ? (el.children as ElementLike[])
+      : null;
+    if (el.type === "group" && children && children.length > 0) {
+      children.forEach(walk);
+      return;
+    }
+    out.push(el);
+  };
+  els.forEach(walk);
+  return out;
+}
+
+/**
+ * 요소들이 실제로 차지하는 상자.
+ *
+ * 회전은 상자 계산에서 무시한다 — 회전한 요소는 회전값을 그대로 GIF에 물려주므로,
+ * 회전 전 상자로 재는 게 맞다(회전 후 bbox로 재면 그 위에 회전을 또 걸어 커진다).
+ */
+export function unionBox(els: ElementLike[]): Box | null {
+  const leaves = leafElements(els);
+  if (leaves.length === 0) return null;
+  let left = Infinity;
+  let top = Infinity;
+  let right = -Infinity;
+  let bottom = -Infinity;
+  for (const el of leaves) {
+    const x = num(el.x);
+    const y = num(el.y);
+    left = Math.min(left, x);
+    top = Math.min(top, y);
+    right = Math.max(right, x + num(el.width));
+    bottom = Math.max(bottom, y + num(el.height));
+  }
+  if (!Number.isFinite(left) || !Number.isFinite(top)) return null;
+  return {
+    x: left,
+    y: top,
+    width: Math.max(1, right - left),
+    height: Math.max(1, bottom - top),
+  };
+}
+
+/** 상자를 사방으로 ``bleed``만큼 키운다(상자 밖으로 번지는 이펙트용 여백). */
+export function expandBox(box: Box, bleed: number): Box {
+  const pad = Math.max(0, bleed);
+  return {
+    x: box.x - pad,
+    y: box.y - pad,
+    width: box.width + pad * 2,
+    height: box.height + pad * 2,
+  };
+}
+
+function pageOf(store: StoreLike, el: ElementLike): PageLike | undefined {
+  const hit = (children: unknown): boolean =>
+    Array.isArray(children) &&
+    (children as ElementLike[]).some(
+      (child) => child.id === el.id || hit(child.children),
+    );
+  return (
+    store.pages.find((page) => hit(page.children)) ??
+    store.activePage ??
+    store.pages[0]
+  );
+}
+
+function childList(node: PageLike | ElementLike): ElementLike[] {
+  return Array.isArray(node.children) ? (node.children as ElementLike[]) : [];
+}
+
+function idOf(el: ElementLike | undefined | null): string {
+  return String(el?.id ?? "");
+}
+
+/**
+ * ``el``을 품고 있는 **페이지 직속 자식**의 인덱스. el 자신이 직속이면 그 인덱스다.
+ *
+ * 그룹 안의 요소는 페이지 children에 없으므로 조상을 타고 올라가 대표를 찾는다.
+ */
+function topLevelIndexOf(page: PageLike, el: ElementLike): number {
+  const target = idOf(el);
+  if (!target) return -1;
+  const holds = (node: ElementLike): boolean =>
+    idOf(node) === target || childList(node).some(holds);
+  return childList(page).findIndex(holds);
+}
+
+/**
+ * 갈아 끼운 뒤 GIF를 원본이 있던 페이지 칸으로 되돌린다.
+ *
+ * 페이지 직속 원본을 통째로 대체했으면 원본이 비운 칸에 그대로 앉는다. 그룹 안의
+ * 자식만 대체한 경우엔 일단 그 그룹 바로 위에 앉히고, 이어서 그룹 안으로 넣는다.
+ */
+function restoreZIndex(
+  page: PageLike,
+  gifId: string,
+  beforeIds: string[],
+  anchorTopIndex: number,
+): void {
+  if (!page.setElementZIndex || !gifId || anchorTopIndex < 0) return;
+  const survivors = new Set(childList(page).map(idOf));
+  let target = 0;
+  for (let i = 0; i < anchorTopIndex; i += 1) {
+    if (survivors.has(beforeIds[i])) target += 1;
+  }
+  // 그룹은 남고 그 자식만 갈아 끼운 경우: 그룹 바로 위(원본이 그룹 안에서 그려지던 자리).
+  if (survivors.has(beforeIds[anchorTopIndex])) target += 1;
+  page.setElementZIndex(gifId, target);
+}
+
+export type ReplaceOptions = {
+  /** 상자 밖으로 번지는 이펙트 여백(px). 텍스트 GIF가 서버에 넘긴 값과 같아야 한다. */
+  bleed?: number;
+  /** 원본이 사진 하나였다면 그 자르기(crop)를 물려받아 프레이밍을 유지한다. */
+  inheritCrop?: boolean;
+};
+
+/**
+ * ``els``를 지우고 그 자리에 GIF 이미지 요소를 넣는다. 넣은 요소를 돌려준다.
+ *
+ * 상자를 못 재면(요소가 없거나 좌표가 이상하면) 아무것도 지우지 않고 null을 돌려준다 —
+ * 원본을 날린 뒤 대체에 실패하는 게 제일 나쁘다.
+ */
+export function replaceWithGif(
+  store: unknown,
+  els: ElementLike[],
+  src: string,
+  options: ReplaceOptions = {},
+): unknown {
+  const s = store as StoreLike;
+  if (!src || els.length === 0) return null;
+  const inner = unionBox(els);
+  if (!inner) return null;
+  const box = expandBox(inner, options.bleed ?? 0);
+  const page = pageOf(s, els[0]) ?? s.activePage ?? s.pages[0];
+  if (!page) return null;
+
+  const single = els.length === 1 ? els[0] : null;
+  const rotation = num(single?.rotation, 0);
+  const crop: Record<string, number> = {};
+  if (options.inheritCrop && single?.type === "image") {
+    // 스톡 편집기는 이미지를 cover-crop으로 채운다. 원본이 잘려 있었다면 그 자르기를
+    // 그대로 물려줘야 프레이밍이 안 바뀐다.
+    for (const key of ["cropX", "cropY", "cropWidth", "cropHeight"] as const) {
+      const value = single[key];
+      if (typeof value === "number" && Number.isFinite(value)) crop[key] = value;
+    }
+  }
+
+  const ids = els.map((el) => String(el.id ?? "")).filter(Boolean);
+  // 원본이 페이지 몇 번째 칸에 있었는지 지우기 전에 재둔다. 여럿을 대체할 때는 가장
+  // 앞(위)에 있던 것을 기준으로 삼는다 — 그것들이 덮고 있던 것을 GIF도 덮어야 한다.
+  const beforeIds = childList(page).map(idOf);
+  const anchorTopIndex = els.reduce(
+    (top, el) => Math.max(top, topLevelIndexOf(page, el)),
+    -1,
+  );
+  // 하나짜리 원본이 그룹 안에 있었다면 그 그룹의 같은 칸으로 돌려보낸다.
+  const nest = els.length === 1 ? locate(page, idOf(els[0])) : null;
+  const nestInto =
+    nest?.parent && idOf(nest.parent) !== idOf(els[0])
+      ? { parentId: idOf(nest.parent), index: nest.index }
+      : null;
+  const added = page.addElement({
+    type: "image",
+    src,
+    x: Math.round(box.x),
+    y: Math.round(box.y),
+    width: Math.round(box.width),
+    height: Math.round(box.height),
+    ...(rotation ? { rotation } : {}),
+    ...crop,
+    // 레이어 트리에서 "image-2" 대신 "GIF"로 보이게 하고, 내보내기가 이 섹션을
+    // 애니메이션으로 다루도록 표시한다.
+    name: "GIF",
+    custom: { detailPageGif: true },
+  });
+  if (ids.length > 0) s.deleteElements?.(ids);
+  const gifId = idOf(added as ElementLike);
+  restoreZIndex(page, gifId, beforeIds, anchorTopIndex);
+  if (nestInto && gifId) {
+    // 그룹이 자식 하나로 사라졌을 수도 있다. 그때는 페이지 칸(위에서 되돌린 자리)이 답.
+    moveLayer(s, gifId, nestInto);
+  }
+  return added;
+}

package/lib/detail-page/section-height.ts

@@ -0,0 +1,131 @@
+/**
+ * 섹션(편집기 한 장) 높이 — 재는 법, 바꾸는 법.
+ *
+ * 상세페이지의 한 장은 상품 카드가 아니라 **세로로 이어 붙는 띠**다. 그래서 높이가 고정된
+ * 캔버스와 달리 장마다 다르고, 바꿀 수 있어야 한다("여기 좀 답답해요", "이 장이 너무 길어요").
+ * Canvas 는 페이지 높이를 모델에 들고 있으므로(``page.set({height})``) 바꾸는 것 자체는
+ * 한 줄이다. 여기 있는 것은 그 한 줄로는 안 되는 두 가지다.
+ *
+ * ## 1. 배경은 같이 늘어나야 한다
+ *
+ * 디컴포즈된 화면은 배경을 **요소로** 깐다 — 페이지를 꽉 채우는 사진, 그라데이션 사각형,
+ * 색 띠. 페이지만 늘리면 그 요소는 옛 높이 그대로 남아 아래에 흰 띠가 생긴다. 유저가 보기에
+ * 이건 기능이 아니라 고장이다. 그래서 **페이지를 꽉 채우고 있던** 요소는 늘어난 만큼 같이
+ * 늘린다. 판정은 Canvas 자신이 ``setSize({useMagic})`` 에서 쓰는 것과 같은 모양이다
+ * (원점에 붙어 있고 페이지만 한 크기).
+ *
+ * ## 2. 굽기 상한이 진짜 상한이다
+ *
+ * 편집기 문서를 HTML 로 굽는 서버(``editor_document_service``)는 페이지 높이를 120~8000px
+ * 로 자른다. 편집기에서 9000px 을 잡을 수 있게 두면 화면에서는 멀쩡한데 구운 결과만 조용히
+ * 잘린다 — 그건 편집기에서 막는 게 맞다.
+ */
+
+export type SectionHeightElement = {
+  type?: string;
+  x?: unknown;
+  y?: unknown;
+  width?: unknown;
+  height?: unknown;
+  children?: SectionHeightElement[];
+  set?: (attrs: Record<string, unknown>) => void;
+};
+
+export type SectionHeightPage = {
+  computedWidth?: number;
+  computedHeight?: number;
+  children?: SectionHeightElement[];
+  set?: (attrs: Record<string, unknown>) => void;
+};
+
+/** 서버가 굽기에서 자르는 하한. 이보다 낮게 잡아도 구운 결과는 이 값이 된다. */
+export const MIN_SECTION_HEIGHT = 200;
+
+/**
+ * 굽기 상한과 **같은 수**여야 한다(``editor_document_service._render_editor_document_html``).
+ * 여기만 키우면 편집기에서는 되는데 구운 상세페이지만 잘린다.
+ */
+export const MAX_SECTION_HEIGHT = 8000;
+
+function num(value: unknown, fallback = 0): number {
+  const n = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+export function clampSectionHeight(value: unknown): number {
+  const n = Math.round(num(value, MIN_SECTION_HEIGHT));
+  return Math.max(MIN_SECTION_HEIGHT, Math.min(MAX_SECTION_HEIGHT, n));
+}
+
+/**
+ * 이 요소가 **페이지 배경 노릇을 하고 있는가**.
+ *
+ * 원점에 붙어 있고(1px 오차 허용) 페이지를 거의 꽉 채우는 것. 텍스트와 그룹은 제외한다 —
+ * 그룹은 자식이 좌표를 들고 있어 높이를 늘려도 화면이 달라지지 않고, 페이지만 한 텍스트
+ * 상자를 배경으로 잘못 잡으면 글줄이 세로로 늘어난다.
+ */
+export function isSectionBackdrop(
+  el: SectionHeightElement,
+  pageWidth: number,
+  pageHeight: number,
+): boolean {
+  const type = String(el?.type ?? "");
+  if (type === "text" || type === "group") return false;
+  return (
+    num(el?.x) <= 1 &&
+    num(el?.y) <= 1 &&
+    num(el?.width) >= pageWidth - 2 &&
+    num(el?.height) >= pageHeight - 2
+  );
+}
+
+/**
+ * 내용이 실제로 끝나는 y(px). "내용에 맞추기"가 이 값을 쓴다.
+ *
+ * 배경 요소는 세지 않는다 — 배경은 페이지를 따라다니는 것이라, 세면 "지금 높이"가 그대로
+ * 답이 되어 버튼이 아무 일도 안 하게 된다. 그룹 자식은 페이지 절대 좌표를 들고 있고
+ * (디컴포저가 그룹을 원점에 고정한다), 유저가 그룹을 끌면 그 이동량이 그룹 x/y 에 쌓이므로
+ * 둘을 더해야 진짜 자리가 나온다.
+ */
+export function sectionContentBottom(page: SectionHeightPage): number {
+  const pageWidth = num(page?.computedWidth);
+  const pageHeight = num(page?.computedHeight);
+  let bottom = 0;
+  const visit = (el: SectionHeightElement, offsetY: number) => {
+    const kids = el?.children;
+    if (kids?.length) {
+      const groupOffset = offsetY + num(el?.y);
+      for (const kid of kids) visit(kid, groupOffset);
+      return;
+    }
+    bottom = Math.max(bottom, offsetY + num(el?.y) + num(el?.height));
+  };
+  for (const el of page?.children ?? []) {
+    if (isSectionBackdrop(el, pageWidth, pageHeight)) continue;
+    visit(el, 0);
+  }
+  return Math.ceil(bottom);
+}
+
+/**
+ * 높이를 바꾼다(배경까지 같이). 실제로 적용된 높이를 돌려준다.
+ *
+ * 늘어난 양을 **먼저** 재고 나서 페이지를 바꾼다 — 순서를 바꾸면 배경 판정이 이미 새 높이를
+ * 보게 되어 아무것도 배경으로 안 잡힌다.
+ */
+export function applySectionHeight(
+  page: SectionHeightPage,
+  nextHeight: number,
+): number {
+  const next = clampSectionHeight(nextHeight);
+  const prev = Math.round(num(page?.computedHeight));
+  if (prev > 0 && next !== prev) {
+    const pageWidth = num(page?.computedWidth);
+    for (const el of page?.children ?? []) {
+      if (!isSectionBackdrop(el, pageWidth, prev)) continue;
+      el.set?.({ height: Math.max(1, num(el.height) + (next - prev)) });
+    }
+  }
+  page?.set?.({ height: next });
+  return next;
+}

package/lib/detail-page/section-reauthor-bus.ts

@@ -0,0 +1,61 @@
+// 화면 재저작 요청용 초경량 pub/sub.
+//
+// 요청은 캔버스 옆 페이지 툴바(화면 하나에 붙어 있는 컨트롤)에서 나오고, 실제 일은
+// 편집기 최상단(store·generatedId·모달을 쥔 쪽)이 한다. 그 사이에는 Canvas 워크스페이스가
+// 있어 props 로 잇기 어렵다 — '내 이미지' 갱신과 같은 방식으로 모듈 레벨에서 느슨하게 잇는다.
+
+type Listener = (pageId: string) => void;
+
+const listeners = new Set<Listener>();
+const availabilityWatchers = new Set<() => void>();
+
+function notifyAvailability(): void {
+  for (const watcher of [...availabilityWatchers]) {
+    try {
+      watcher();
+    } catch {
+      // 구독자 하나가 터져도 나머지는 받는다.
+    }
+  }
+}
+
+/** 재저작 요청을 구독한다. 반환된 함수로 구독 해제. */
+export function onSectionReauthorRequested(listener: Listener): () => void {
+  listeners.add(listener);
+  notifyAvailability();
+  return () => {
+    listeners.delete(listener);
+    notifyAvailability();
+  };
+}
+
+/** 이 화면을 다시 만들어 달라고 요청한다(``pageId`` = 화면 라벨). */
+export function requestSectionReauthor(pageId: string): void {
+  for (const listener of [...listeners]) {
+    try {
+      listener(pageId);
+    } catch {
+      // 리스너 하나가 터져도 나머지는 받는다.
+    }
+  }
+}
+
+/**
+ * 배선 여부 구독(``useSyncExternalStore`` 용).
+ *
+ * 툴바는 편집기보다 **먼저** 그려질 수 있다. 한 번 읽고 마는 헬퍼로는 배선이 끝난
+ * 뒤에도 버튼이 계속 숨어 있게 된다 — 그래서 구독 가능한 형태로 낸다.
+ */
+export function subscribeSectionReauthorAvailability(
+  watcher: () => void,
+): () => void {
+  availabilityWatchers.add(watcher);
+  return () => {
+    availabilityWatchers.delete(watcher);
+  };
+}
+
+/** 지금 재저작이 배선돼 있는지. 미배선이면 툴바 버튼을 띄우지 않는다(막다른 길 방지). */
+export function isSectionReauthorWired(): boolean {
+  return listeners.size > 0;
+}

package/lib/detail-page/shape-to-image.ts

@@ -0,0 +1,219 @@
+/**
+ * 편집기 도형(벡터) → 투명 PNG data URI.
+ *
+ * 도형을 GIF로 만들려면 이펙트 파이프라인에 픽셀을 줘야 한다. 서버에 SVG를 보내
+ * 헤드리스 브라우저로 굽는 방법도 있지만, 색 치환(``colorsReplace``)과 그라데이션까지
+ * 편집기와 똑같이 재현하려면 결국 렌더 규칙을 서버에 복제해야 한다. 브라우저는 이미
+ * 그 규칙을 들고 있으므로 여기서 굽고 픽셀만 올린다.
+ *
+ * 도형은 두 종류다.
+ *  - ``svg``: 마크업이 ``src``에 data URI로 들어 있다(색 치환은 ``colorsReplace``).
+ *  - ``figure``: 네이티브 도형. 마크업이 없어 subType/치수에서 만들어 낸다
+ *    (``leviosa-canvas/paint/figure-svg``가 화면과 같은 규칙으로 그린다).
+ *
+ * 배경은 투명하게 둔다 — GIF 인코더가 투명 소스를 알아보고 투명 배경 GIF로 굽는다.
+ */
+
+import { parseStops } from "../../components/detail-page/fill-control";
+import { encodeSvgDataUri } from "../detail-page-canvas/export/svg";
+import { figureToSvg } from "@leviosa-ai/canvas/paint/figure-svg";
+import {
+  ensureSvgNamespace,
+  loadSvgMarkup,
+  readColorReplace,
+  replaceSvgColors,
+} from "@leviosa-ai/canvas/render/svg-source";
+
+export type ShapeElementLike = {
+  type?: unknown;
+  src?: unknown;
+  width?: unknown;
+  height?: unknown;
+  fill?: unknown;
+  stroke?: unknown;
+  strokeWidth?: unknown;
+  dash?: unknown;
+  cornerRadius?: unknown;
+  subType?: unknown;
+  colorsReplace?: unknown;
+  id?: unknown;
+};
+
+/** 굽는 해상도 배율. 편집기 좌표는 작아서 1배로 구우면 이펙트에서 뭉갠다. */
+const RASTER_SCALE = 2;
+/** 한 변 상한(서버 GIF 소스 상한과 렌더 시간 양쪽을 고려). */
+const MAX_EDGE = 1400;
+
+function num(value: unknown, fallback: number): number {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+/** GIF로 구울 수 있는 도형인지(그룹·텍스트·이미지는 각자의 경로가 따로 있다). */
+export function isShapeElement(
+  el: ShapeElementLike | null | undefined,
+): boolean {
+  const type = String(el?.type ?? "");
+  return type === "svg" || type === "figure";
+}
+
+/**
+ * ``linear-gradient(...)`` 채우기를 SVG ``<linearGradient>``로 바꾼다.
+ *
+ * 방향은 스톡 편집기가 캔버스에 그릴 때 쓰는 규칙과 같다(``useColor``: CSS 각도 A의 진행
+ * 방향이 ``(sin A, -cos A)``). 각도를 무시하면 편집기에서 가로로 흐르던 그라데이션이
+ * GIF에서만 세로로 흐른다.
+ *
+ * 그라데이션이 아니면 ``null``(호출부가 색 문자열을 그대로 쓴다).
+ */
+export function gradientToSvgPaint(
+  fill: unknown,
+  id: string,
+): { def: string; ref: string } | null {
+  const parsed = parseStops(String(fill ?? ""));
+  if (!parsed) return null;
+  const rad = (parsed.angle * Math.PI) / 180;
+  const dx = Math.sin(rad) / 2;
+  const dy = Math.cos(rad) / 2;
+  const stops = parsed.stops
+    .map(
+      (stop) =>
+        `<stop offset="${Math.round(stop.pos)}%" stop-color="${stop.color}"/>`,
+    )
+    .join("");
+  return {
+    def:
+      `<linearGradient id="${id}" x1="${(0.5 - dx).toFixed(4)}" ` +
+      `y1="${(0.5 + dy).toFixed(4)}" x2="${(0.5 + dx).toFixed(4)}" ` +
+      `y2="${(0.5 - dy).toFixed(4)}">${stops}</linearGradient>`,
+    ref: `url(#${id})`,
+  };
+}
+
+/**
+ * ``figureToSvg``가 만든 마크업의 그라데이션 채우기를 defs로 바꿔 끼운다.
+ *
+ * 그 함수는 ``fill``을 문자열 그대로 박기 때문에 ``linear-gradient(...)``가 무효한
+ * paint가 되어 도형이 통째로 검게 굳는다.
+ */
+export function patchFigureGradient(
+  markup: string,
+  el: ShapeElementLike,
+): string {
+  const fill = String(el.fill ?? "");
+  const paint = gradientToSvgPaint(fill, `dp-grad-${String(el.id ?? "shape")}`);
+  if (!paint) return markup;
+  const withDefs = markup.includes("<defs>")
+    ? markup.replace("<defs>", `<defs>${paint.def}`)
+    : markup.replace(/<svg([^>]*)>/, `<svg$1><defs>${paint.def}</defs>`);
+  return withDefs.split(`fill="${fill}"`).join(`fill="${paint.ref}"`);
+}
+
+/**
+ * 루트 ``<svg>``에 픽셀 크기를 못 박는다.
+ *
+ * ``<img>``로 SVG를 그릴 때 루트에 width/height가 없으면 브라우저가 기본 300×150을
+ * 고유 크기로 잡는다. 그 상태로 다른 비율의 캔버스에 그리면 도형이 눌리거나 늘어난다
+ * (viewBox만 있는 라이브러리 도형이 여기 해당한다).
+ */
+export function withExplicitSize(
+  markup: string,
+  width: number,
+  height: number,
+): string {
+  const root = markup.match(/<svg\b[^>]*>/i);
+  if (!root) return markup;
+  const cleaned = root[0]
+    .replace(/\swidth="[^"]*"/i, "")
+    .replace(/\sheight="[^"]*"/i, "")
+    .replace(/\spreserveAspectRatio="[^"]*"/i, "")
+    .replace(
+      /^<svg/i,
+      `<svg width="${width}" height="${height}" preserveAspectRatio="none"`,
+    );
+  return markup.replace(root[0], cleaned);
+}
+
+/**
+ * 도형 요소 → ``<img>``에 바로 물릴 수 있는 SVG data URI.
+ *
+ * 색 치환이 있는 svg 도형은 스톡 편집기의 ``replaceColors``가 이미 data URI를 돌려주므로
+ * 마크업으로 되돌리지 않는다(되돌렸다 다시 인코딩하면 한글이 깨질 여지만 생긴다).
+ */
+export async function shapeSvgDataUri(
+  el: ShapeElementLike,
+): Promise<string | null> {
+  const type = String(el.type ?? "");
+  const width = num(el.width, 0);
+  const height = num(el.height, 0);
+  if (width <= 0 || height <= 0) return null;
+
+  if (type === "figure") {
+    const markup = figureToSvg({
+      ...el,
+      width,
+      height,
+      strokeWidth: num(el.strokeWidth, 0),
+      cornerRadius: num(el.cornerRadius, 0),
+      dash: Array.isArray(el.dash) ? el.dash : [],
+    });
+    if (!markup) return null;
+    return encodeSvgDataUri(
+      withExplicitSize(patchFigureGradient(markup, el), width, height),
+    );
+  }
+  if (type !== "svg") return null;
+  const src = String(el.src ?? "");
+  if (!src) return null;
+
+  const raw = await loadSvgMarkup(src);
+  const sized = ensureSvgNamespace(withExplicitSize(raw, width, height));
+  return encodeSvgDataUri(
+    replaceSvgColors(sized, readColorReplace(el.colorsReplace)),
+  );
+}
+
+/** SVG data URI를 투명 배경 PNG data URI로 굽는다. 실패하면 null. */
+export async function rasterizeSvgDataUri(
+  uri: string,
+  width: number,
+  height: number,
+): Promise<string | null> {
+  const w = Math.max(1, Math.round(width));
+  const h = Math.max(1, Math.round(height));
+  const scale = Math.min(RASTER_SCALE, MAX_EDGE / Math.max(w, h));
+  const canvas = document.createElement("canvas");
+  canvas.width = Math.max(1, Math.round(w * scale));
+  canvas.height = Math.max(1, Math.round(h * scale));
+  const ctx = canvas.getContext("2d");
+  if (!ctx) return null;
+
+  const image = await loadImage(uri);
+  if (!image) return null;
+  ctx.drawImage(image, 0, 0, canvas.width, canvas.height);
+  return canvas.toDataURL("image/png");
+}
+
+function loadImage(uri: string): Promise<HTMLImageElement | null> {
+  return new Promise((resolve) => {
+    const image = new Image();
+    image.onload = () => resolve(image);
+    image.onerror = () => resolve(null);
+    // data URI는 캔버스를 오염시키지 않는다(외부 호스트가 아니라 CORS도 없다).
+    image.src = uri;
+  });
+}
+
+/**
+ * 선택 도형 → GIF 소스로 보낼 투명 PNG data URI.
+ *
+ * 도형이 아니거나 구울 수 없으면 ``null`` — 호출부가 안내를 띄운다.
+ */
+export async function shapeSourceImage(
+  el: ShapeElementLike,
+): Promise<string | null> {
+  if (!isShapeElement(el)) return null;
+  const uri = await shapeSvgDataUri(el);
+  if (!uri) return null;
+  return rasterizeSvgDataUri(uri, num(el.width, 0), num(el.height, 0));
+}

package/lib/detail-page/spec-group/clipboard.ts

@@ -0,0 +1,35 @@
+/**
+ * 엑셀·구글시트에서 붙여넣은 텍스트를 격자로 쪼갠다.
+ *
+ * 클립보드의 ``text/plain``은 스프레드시트에서 탭 구분 텍스트로 온다. Canva·미리캔버스가
+ * 하는 것도 이거고, 파일 업로드보다 압도적으로 자주 쓰인다. CSV(쉼표)·세미콜론도 같이
+ * 받아 준다. 차트와 표가 같은 규칙으로 읽어야 사용자가 두 번 배우지 않는다.
+ */
+
+export function splitLines(text: string): string[] {
+  return text
+    .replace(/\r\n?/g, "\n")
+    .split("\n")
+    .filter((line) => line.trim().length > 0);
+}
+
+/** 구분자 추론: 탭 > 쉼표 > 세미콜론 > 연속 공백. */
+export function pickDelimiter(lines: string[]): RegExp {
+  const joined = lines.join("\n");
+  if (joined.includes("\t")) return /\t/;
+  if (joined.includes(",")) return /,/;
+  if (joined.includes(";")) return /;/;
+  return /\s{2,}/;
+}
+
+export function cellsOf(line: string, delimiter: RegExp): string[] {
+  return line.split(delimiter).map((cell) => cell.trim());
+}
+
+/** 붙여넣은 텍스트를 문자열 격자로. 읽을 게 없으면 빈 배열. */
+export function parseGrid(text: string): string[][] {
+  const lines = splitLines(text ?? "");
+  if (lines.length === 0) return [];
+  const delimiter = pickDelimiter(lines);
+  return lines.map((line) => cellsOf(line, delimiter));
+}