@leviosa-ai/detail-page-editor 0.1.0

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

@@ -0,0 +1,120 @@
+/**
+ * 문서 전체 텍스트 찾기·바꾸기.
+ *
+ * 상세페이지는 20섹션짜리다. 브랜드명·용량 표기(``30ml``)·성분 학명이 그 안에 흩어져
+ * 있고, "30ml → 50ml"를 손으로 찾아 고치는 건 빠뜨리는 작업이다.
+ */
+
+export type SearchElement = {
+  id: string;
+  type?: string;
+  text?: string;
+  custom?: Record<string, unknown> | null;
+  children?: SearchElement[];
+};
+
+export type SearchPage = { id: string; children?: SearchElement[] };
+
+export type SearchOptions = { caseSensitive?: boolean };
+
+export type TextMatch = {
+  pageId: string;
+  elementId: string;
+  /** 그 요소 안에 몇 번 나오는가. */
+  count: number;
+};
+
+/**
+ * 차트 그룹 안인가.
+ *
+ * 표 안 텍스트는 **바꾼다** — 캔버스에서 고친 칸 글자는 다음 ``syncSpecGroup``에서
+ * ``harvestTableEdits``가 스펙으로 걷어 올리므로 살아남는다.
+ *
+ * 차트 안 텍스트는 **건너뛴다** — 차트에는 harvest가 없어서 다음 동기화에 스펙이
+ * 다시 그리며 되돌아간다. 조용히 되돌아가느니 아예 안 잡는 게 낫다. 그래서 세지도
+ * 않는다(카운터가 바꿀 수 없는 것을 세면 거짓말이 된다).
+ */
+export function isChartGroup(el: SearchElement): boolean {
+  return !!el.custom && "chart" in el.custom;
+}
+
+/** 겹치지 않게 센다 — "aaa"에서 "aa"는 두 번이 아니라 한 번이다(치환과 같은 셈법). */
+export function countOccurrences(
+  text: string,
+  query: string,
+  opts: SearchOptions = {},
+): number {
+  if (!query) return 0;
+  const hay = opts.caseSensitive ? text : text.toLowerCase();
+  const needle = opts.caseSensitive ? query : query.toLowerCase();
+  // split은 겹치지 않는 조각으로 자른다 — 정규식을 안 쓰므로 사용자가 넣은 `.`·`(`가
+  // 메타문자로 새지 않는다.
+  return hay.split(needle).length - 1;
+}
+
+/**
+ * 검색어가 든 텍스트 요소들. 그리는 순서(=페이지 순서, 그 안에서 자식 순서)를 지켜
+ * ↑/↓로 훑는 순서가 문서를 읽는 순서와 같게 한다.
+ */
+export function collectTextMatches(
+  pages: ReadonlyArray<SearchPage>,
+  query: string,
+  opts: SearchOptions = {},
+): TextMatch[] {
+  if (!query) return [];
+  const out: TextMatch[] = [];
+  const visit = (el: SearchElement, pageId: string) => {
+    if (isChartGroup(el)) return;
+    if (el.type === "text" && typeof el.text === "string") {
+      const count = countOccurrences(el.text, query, opts);
+      if (count > 0) out.push({ pageId, elementId: el.id, count });
+    }
+    for (const child of el.children ?? []) visit(child, pageId);
+  };
+  for (const page of pages) {
+    for (const child of page.children ?? []) visit(child, page.id);
+  }
+  return out;
+}
+
+/** 전체 등장 횟수. 요소 수가 아니라 실제로 바뀔 자리 수다. */
+export function totalOccurrences(matches: ReadonlyArray<TextMatch>): number {
+  return matches.reduce((sum, m) => sum + m.count, 0);
+}
+
+/**
+ * 문자열 그대로 치환. 정규식을 안 쓴다 — 검색어의 ``.``·``(``와 바꿀 말의 ``$&``가
+ * 특수문자로 새면 사용자가 친 그대로가 안 들어간다.
+ */
+export function replaceInText(
+  text: string,
+  query: string,
+  replacement: string,
+  opts: SearchOptions = {},
+): string {
+  if (!query) return text;
+  if (opts.caseSensitive) return text.split(query).join(replacement);
+
+  // 대소문자를 무시할 땐 자리만 소문자로 찾고 잘라내기는 원문에서 한다.
+  const hay = text.toLowerCase();
+  const needle = query.toLowerCase();
+  let out = "";
+  let from = 0;
+  for (;;) {
+    const at = hay.indexOf(needle, from);
+    if (at < 0) break;
+    out += text.slice(from, at) + replacement;
+    from = at + needle.length;
+  }
+  return out + text.slice(from);
+}
+
+/** ↑/↓로 감싸 돌기. 목록이 비면 null. */
+export function stepIndex(
+  current: number,
+  length: number,
+  direction: 1 | -1,
+): number | null {
+  if (length <= 0) return null;
+  return (((current + direction) % length) + length) % length;
+}

package/lib/detail-page/format-painter.ts

@@ -0,0 +1,159 @@
+/**
+ * 서식 복사·붙이기(Canva의 "서식 붓").
+ *
+ * 상세페이지는 **같은 톤의 소제목이 20섹션 반복되는 문서**다. 하나를 다듬어 놓고
+ * 나머지에 같은 폰트·크기·색·자간·하이라이트를 먹이려면 지금은 인스펙터에서 값을
+ * 하나씩 다시 맞춰야 한다.
+ *
+ * 스톡 편집기의 ``useCopyStyle``을 안 쓰는 이유가 셋 있다.
+ *
+ * 1. 공통 필드에 ``width``·``height``가 들어 있어, 같은 타입끼리 붙이면 **크기까지
+ *    바뀐다**. Canva의 서식 붓은 크기를 안 건드린다.
+ * 2. 타입별 필드 표에 ``group``이 없다. ``intersect(map[a.type], map[b.type])``에
+ *    undefined가 들어가 그룹(=우리 문서의 대부분)에 대고 쓰면 터진다.
+ * 3. 발동 조건이 ``selectedElements[0]`` 변화 감지라, 우리 드릴인·다중선택과 섞이면
+ *    예측이 안 된다. 여기서는 복사·붙이기 두 동작만 둔다.
+ */
+
+/** 타입이 무엇이든 옮겨도 되는 것 — 크기·좌표·내용은 하나도 없다. */
+const COMMON = [
+  "opacity",
+  "blurEnabled",
+  "blurRadius",
+  "shadowEnabled",
+  "shadowBlur",
+  "shadowColor",
+  "shadowOffsetX",
+  "shadowOffsetY",
+] as const;
+
+/**
+ * 타입별로 옮길 서식.
+ *
+ * ``fontSize``는 **넣는다** — 소제목 20개의 크기를 맞추는 게 이 기능의 알맹이다.
+ * 상자(``width``/``height``)는 안 건드리므로 글자만 커진다.
+ * ``crop*``은 **뺀다** — 어디를 잘라 보여줄지는 서식이 아니라 내용이다.
+ */
+const BY_TYPE: Record<string, ReadonlyArray<string>> = {
+  text: [
+    ...COMMON,
+    "fontFamily",
+    "fontSize",
+    "fontWeight",
+    "fontStyle",
+    "lineHeight",
+    "letterSpacing",
+    "align",
+    "verticalAlign",
+    "textDecoration",
+    "fill",
+    "stroke",
+    "strokeWidth",
+    "backgroundEnabled",
+    "backgroundColor",
+    "backgroundOpacity",
+    "backgroundCornerRadius",
+    "backgroundPadding",
+  ],
+  figure: [...COMMON, "fill", "stroke", "strokeWidth", "dash", "cornerRadius"],
+  svg: [...COMMON, "colorsReplace", "borderColor", "borderSize", "cornerRadius"],
+  image: [...COMMON, "borderColor", "borderSize", "cornerRadius"],
+};
+
+/**
+ * 서식을 읽고 쓰는 데 필요한 것만. 나머지 필드는 이름으로 집으므로 열어 둔다 — 타입을
+ * 좁히면 호출부(캔버스 메뉴의 요소, 테스트 픽스처)가 전부 캐스팅을 달아야 한다.
+ */
+export type FormatElement = {
+  type?: string;
+  set?: (props: Record<string, unknown>) => void;
+  [key: string]: unknown;
+};
+
+export type CopiedFormat = {
+  type: string;
+  props: Record<string, unknown>;
+};
+
+/** 서식을 복사할 수 있는 타입인가. 그룹·차트·표는 아니다(자기 스펙이 모양을 정한다). */
+export function canCopyFormat(el: FormatElement | undefined | null): boolean {
+  return !!el?.type && el.type in BY_TYPE;
+}
+
+/** 배열·객체 값은 얕게 복사한다 — 원본과 같은 참조를 공유하면 한쪽을 고칠 때 둘 다 바뀐다. */
+function detach(value: unknown): unknown {
+  if (Array.isArray(value)) return [...value];
+  if (value && typeof value === "object") return { ...(value as object) };
+  return value;
+}
+
+/**
+ * 요소의 서식을 떠 낸다. 값이 없는(``undefined``) 필드는 **키 자체를 안 만든다** —
+ * 나중에 붙일 때 대상의 멀쩡한 값을 undefined로 뭉개지 않기 위해서다.
+ */
+export function copyFormat(el: FormatElement | undefined | null): CopiedFormat | null {
+  if (!canCopyFormat(el)) return null;
+  const type = el!.type!;
+  const bag = el as Record<string, unknown>;
+  const props: Record<string, unknown> = {};
+  for (const key of BY_TYPE[type]) {
+    const value = bag[key];
+    if (value === undefined) continue;
+    props[key] = detach(value);
+  }
+  return { type, props };
+}
+
+/**
+ * 이 대상에 실제로 먹일 값. 타입이 다르면 **교집합만** 간다 — 텍스트 서식을 도형에
+ * 붙이면 불투명도와 그림자만 옮는다.
+ */
+export function formatToApply(
+  copied: CopiedFormat,
+  target: FormatElement | undefined | null,
+): Record<string, unknown> {
+  const fields = target?.type ? BY_TYPE[target.type] : undefined;
+  if (!fields) return {};
+  const out: Record<string, unknown> = {};
+  for (const key of fields) {
+    if (key in copied.props) out[key] = detach(copied.props[key]);
+  }
+  return out;
+}
+
+/** 붙일 게 하나라도 있는가 — 메뉴 항목 비활성 판정. */
+export function canPasteFormat(
+  copied: CopiedFormat | null,
+  targets: ReadonlyArray<FormatElement>,
+): boolean {
+  if (!copied || targets.length === 0) return false;
+  return targets.some((el) => Object.keys(formatToApply(copied, el)).length > 0);
+}
+
+/** 선택 전부에 붙인다. 실제로 바뀐 요소 수를 돌려준다. */
+export function applyFormat(
+  copied: CopiedFormat,
+  targets: ReadonlyArray<FormatElement>,
+): number {
+  let touched = 0;
+  for (const el of targets) {
+    const props = formatToApply(copied, el);
+    if (!Object.keys(props).length) continue;
+    el.set?.(props);
+    touched += 1;
+  }
+  return touched;
+}
+
+// ── 세션 클립보드 ───────────────────────────────────────────────────────────
+// 문서에 저장하지 않는다. 서식 붓은 "지금 이 작업 동안"의 도구다.
+
+let held: CopiedFormat | null = null;
+
+export function holdFormat(copied: CopiedFormat | null): void {
+  held = copied;
+}
+
+export function heldFormat(): CopiedFormat | null {
+  return held;
+}

package/lib/detail-page/gif-frames.ts

@@ -0,0 +1,216 @@
+/**
+ * Decode an animated image (WebP or GIF) into fully-composited RGBA frames.
+ *
+ * Two decoders, picked from the container magic rather than the URL — a
+ * presigned S3 link carries no reliable extension, and ``.webp`` is shared by
+ * still and animated files anyway.
+ *
+ * - **WebP** goes through WebCodecs ``ImageDecoder``, which hands back complete
+ *   frames. Nothing to composite.
+ * - **GIF** goes through gifuct-js, which hands back per-frame *patches* in the
+ *   frame's own sub-rectangle, so we paint them onto a persistent full-size
+ *   canvas honoring GIF disposal methods — otherwise frames that only redraw a
+ *   changed region come out corrupt.
+ *
+ * Where ``ImageDecoder`` is missing (older Safari, Firefox) an animated WebP
+ * decodes to its first frame and simply sits still. That is the same outcome as
+ * a failed decode, and the caller already handles a one-frame result.
+ *
+ * Browser-only (needs canvas); import lazily from export glue.
+ */
+
+import { parseGIF, decompressFrames, type ParsedFrame } from "gifuct-js";
+
+import { assetBytesUrl } from "./asset-bytes-url";
+import { sniffAnimationType } from "./animation-sniff";
+
+export type DecodedFrame = {
+  /** Full-size composited frame, ready to draw. */
+  canvas: HTMLCanvasElement;
+  /** This frame's on-screen duration (ms), clamped to a sane minimum. */
+  delayMs: number;
+  /** Cumulative start time of this frame within the loop (ms). */
+  timeMs: number;
+};
+
+export type DecodedAnimation = {
+  width: number;
+  height: number;
+  durationMs: number;
+  frames: DecodedFrame[];
+};
+
+/** Back-compat aliases — these were GIF-only names before WebP landed. */
+export type DecodedGifFrame = DecodedFrame;
+export type DecodedGif = DecodedAnimation;
+
+/** GIF spec allows 0 delay; browsers floor it — mirror that so loops aren't instant. */
+const MIN_DELAY_MS = 20;
+
+async function fetchArrayBuffer(source: string | ArrayBuffer): Promise<ArrayBuffer> {
+  if (source instanceof ArrayBuffer) return source;
+  // 리다이렉트를 따라가면 CORS가 깨지는 주소가 있다 — assetBytesUrl 주석 참고.
+  const res = await fetch(assetBytesUrl(source));
+  if (!res.ok) throw new Error(`animation fetch failed: ${res.status}`);
+  return res.arrayBuffer();
+}
+
+function makeCanvas(w: number, h: number): HTMLCanvasElement {
+  const canvas = document.createElement("canvas");
+  canvas.width = Math.max(1, w);
+  canvas.height = Math.max(1, h);
+  return canvas;
+}
+
+type ImageDecoderCtor = new (init: { data: ArrayBuffer; type: string }) => {
+  completed: Promise<void>;
+  tracks: { ready: Promise<void>; selectedTrack?: { frameCount: number } | null };
+  decode: (opts: { frameIndex: number }) => Promise<{
+    image: CanvasImageSource & { displayWidth: number; displayHeight: number; duration: number | null; close: () => void };
+  }>;
+  close: () => void;
+};
+
+function imageDecoderCtor(): ImageDecoderCtor | null {
+  const ctor = (globalThis as { ImageDecoder?: ImageDecoderCtor }).ImageDecoder;
+  return typeof ctor === "function" ? ctor : null;
+}
+
+/** Draw the whole animation as a single still frame — the no-decoder fallback. */
+async function decodeStill(buffer: ArrayBuffer, mime: string): Promise<DecodedAnimation> {
+  const blob = new Blob([buffer], { type: mime });
+  const url = URL.createObjectURL(blob);
+  try {
+    const img = await new Promise<HTMLImageElement>((resolve, reject) => {
+      const el = new Image();
+      el.onload = () => resolve(el);
+      el.onerror = () => reject(new Error("still decode failed"));
+      el.src = url;
+    });
+    const canvas = makeCanvas(img.naturalWidth, img.naturalHeight);
+    canvas.getContext("2d")?.drawImage(img, 0, 0);
+    return {
+      width: canvas.width,
+      height: canvas.height,
+      durationMs: 0,
+      frames: [{ canvas, delayMs: MIN_DELAY_MS, timeMs: 0 }],
+    };
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}
+
+async function decodeWebp(buffer: ArrayBuffer): Promise<DecodedAnimation> {
+  const Ctor = imageDecoderCtor();
+  if (!Ctor) return decodeStill(buffer, "image/webp");
+
+  const decoder = new Ctor({ data: buffer, type: "image/webp" });
+  try {
+    // 트랙 메타데이터를 기다리는 약속은 ``tracks.ready`` 하나뿐이다. ``completed`` 만
+    // 기다리면 ``selectedTrack`` 이 아직 **null** 이라 프레임 수가 1로 읽히고, 움직이는
+    // WebP 가 통째로 정지 이미지가 된다 — 편집기에서 멈춰 보이고 내보내기도 한 장으로
+    // 나갔던 원인이다(실측: Chrome 150 에서 4프레임 WebP 가 completed 뒤엔 null,
+    // tracks.ready 뒤엔 4). 실패가 아니라서 아무 로그도 남지 않는다.
+    await decoder.tracks.ready;
+    await decoder.completed;
+    const count = decoder.tracks.selectedTrack?.frameCount ?? 1;
+    const frames: DecodedFrame[] = [];
+    let timeMs = 0;
+    let width = 0;
+    let height = 0;
+
+    for (let i = 0; i < count; i++) {
+      const { image } = await decoder.decode({ frameIndex: i });
+      try {
+        width = width || image.displayWidth;
+        height = height || image.displayHeight;
+        const canvas = makeCanvas(image.displayWidth, image.displayHeight);
+        canvas.getContext("2d")?.drawImage(image, 0, 0);
+        // VideoFrame.duration is microseconds; a still track reports null.
+        const delayMs = Math.max(MIN_DELAY_MS, Math.round((image.duration ?? 0) / 1000));
+        frames.push({ canvas, delayMs, timeMs });
+        timeMs += delayMs;
+      } finally {
+        image.close();
+      }
+    }
+    if (!frames.length) return decodeStill(buffer, "image/webp");
+    return { width, height, durationMs: timeMs, frames };
+  } finally {
+    decoder.close();
+  }
+}
+
+function decodeGifBuffer(buffer: ArrayBuffer): DecodedAnimation {
+  const parsed = parseGIF(buffer);
+  const rawFrames = decompressFrames(parsed, true);
+  const width = parsed.lsd.width;
+  const height = parsed.lsd.height;
+
+  // Persistent full-frame canvas we mutate patch-by-patch.
+  const stage = makeCanvas(width, height);
+  const stageCtx = stage.getContext("2d");
+  if (!stageCtx) throw new Error("2d context unavailable");
+  // Scratch canvas to turn a patch (RGBA) into something drawImage can place.
+  const patchCanvas = makeCanvas(width, height);
+  const patchCtx = patchCanvas.getContext("2d");
+  if (!patchCtx) throw new Error("2d context unavailable");
+
+  const frames: DecodedFrame[] = [];
+  let timeMs = 0;
+  let prevSnapshot: ImageData | null = null;
+  let prevFrame: ParsedFrame | null = null;
+
+  for (const frame of rawFrames) {
+    // Apply the *previous* frame's disposal before drawing this one.
+    if (prevFrame) {
+      const d = prevFrame.disposalType;
+      const { left, top, width: fw, height: fh } = prevFrame.dims;
+      if (d === 2) stageCtx.clearRect(left, top, fw, fh);
+      else if (d === 3 && prevSnapshot) stageCtx.putImageData(prevSnapshot, 0, 0);
+    }
+    if (frame.disposalType === 3) prevSnapshot = stageCtx.getImageData(0, 0, width, height);
+
+    const { left, top, width: fw, height: fh } = frame.dims;
+    const patch = new ImageData(new Uint8ClampedArray(frame.patch), fw, fh);
+    patchCtx.clearRect(0, 0, width, height);
+    patchCtx.putImageData(patch, left, top);
+    stageCtx.drawImage(patchCanvas, 0, 0);
+
+    const out = makeCanvas(width, height);
+    out.getContext("2d")?.drawImage(stage, 0, 0);
+
+    const delayMs = Math.max(MIN_DELAY_MS, frame.delay || 0);
+    frames.push({ canvas: out, delayMs, timeMs });
+    timeMs += delayMs;
+    prevFrame = frame;
+  }
+
+  return { width, height, durationMs: timeMs, frames };
+}
+
+/** Decode an animated WebP or GIF into composited frames. */
+export async function decodeAnimation(
+  source: string | ArrayBuffer,
+): Promise<DecodedAnimation> {
+  const buffer = await fetchArrayBuffer(source);
+  const kind = sniffAnimationType(buffer);
+  if (kind === "webp") return decodeWebp(buffer);
+  if (kind === "gif") return decodeGifBuffer(buffer);
+  // Unknown container: it still may be something <img> can draw (PNG/JPEG).
+  return decodeStill(buffer, "image/*");
+}
+
+/** @deprecated Use {@link decodeAnimation} — kept so older imports keep working. */
+export const decodeGif = decodeAnimation;
+
+/** The frame visible at time ``tMs`` within the loop (wraps on duration). */
+export function frameAtTime(gif: DecodedAnimation, tMs: number): DecodedFrame {
+  if (gif.frames.length <= 1 || gif.durationMs <= 0) return gif.frames[0];
+  const t = ((tMs % gif.durationMs) + gif.durationMs) % gif.durationMs;
+  // Linear scan is fine: frame counts are capped and small.
+  for (let i = gif.frames.length - 1; i >= 0; i--) {
+    if (t >= gif.frames[i].timeMs) return gif.frames[i];
+  }
+  return gif.frames[0];
+}

package/lib/detail-page/gif-timeline.ts

@@ -0,0 +1,65 @@
+/**
+ * Pure timeline math for encoding a section as one animated GIF. A section may
+ * hold several source GIFs of different lengths; we sample a single shared
+ * timeline so the exported loop is seamless, then clamp fps and frame count so
+ * a full-width section never explodes into a multi-MB file.
+ */
+
+export const GIF_MAX_FPS = 12;
+export const GIF_MAX_FRAMES = 40;
+/** Cap the shared loop so LCM of mismatched sources can't run away. */
+export const GIF_MAX_LOOP_MS = 8000;
+
+function gcd(a: number, b: number): number {
+  return b === 0 ? a : gcd(b, a % b);
+}
+
+function lcm(a: number, b: number): number {
+  if (a === 0 || b === 0) return 0;
+  return Math.abs(a * b) / gcd(a, b);
+}
+
+export type GifTimeline = {
+  /** Sample times (ms) from loop start; one exported frame each. */
+  times: number[];
+  /** Per-frame delay written into the output GIF (ms). */
+  frameDelayMs: number;
+  /** Total loop length the samples cover (ms). */
+  loopMs: number;
+  /** Effective frames-per-second after clamping. */
+  fps: number;
+};
+
+/**
+ * Build the shared sampling timeline for a section from its source GIF
+ * durations (ms). One source → its own duration; several → the LCM (so every
+ * source lands on a whole loop), capped by ``GIF_MAX_LOOP_MS``. Sample at up to
+ * ``maxFps``, then reduce fps if that would exceed ``maxFrames``.
+ */
+export function buildGifTimeline(
+  durationsMs: number[],
+  opts: { maxFps?: number; maxFrames?: number; maxLoopMs?: number } = {},
+): GifTimeline {
+  const maxFps = opts.maxFps ?? GIF_MAX_FPS;
+  const maxFrames = opts.maxFrames ?? GIF_MAX_FRAMES;
+  const maxLoopMs = opts.maxLoopMs ?? GIF_MAX_LOOP_MS;
+
+  const valid = durationsMs.filter((d) => Number.isFinite(d) && d > 0);
+  if (valid.length === 0) {
+    return { times: [0], frameDelayMs: 1000 / maxFps, loopMs: 0, fps: maxFps };
+  }
+
+  // Seed the fold with the first duration (not 0) — lcm(0, x) is 0 and would
+  // collapse the whole loop.
+  let loopMs = valid.map((d) => Math.round(d)).reduce((acc, d) => lcm(acc, d));
+  if (!Number.isFinite(loopMs) || loopMs <= 0) loopMs = Math.max(...valid);
+  if (loopMs > maxLoopMs) loopMs = Math.max(...valid.map((d) => Math.min(d, maxLoopMs)));
+  loopMs = Math.min(loopMs, maxLoopMs);
+
+  let count = Math.max(1, Math.round((loopMs / 1000) * maxFps));
+  if (count > maxFrames) count = maxFrames;
+
+  const frameDelayMs = loopMs / count;
+  const times = Array.from({ length: count }, (_, i) => i * frameDelayMs);
+  return { times, frameDelayMs, loopMs, fps: 1000 / frameDelayMs };
+}

package/lib/detail-page/group-action.ts

@@ -0,0 +1,62 @@
+/**
+ * ⌘G / ⌘⇧G(그리고 우클릭 메뉴)가 지금 선택에 대해 무엇을 해야 하는가.
+ *
+ * 스톡 편집기의 자기 핸들러(``canvas/canvas/hotkeys.js``)는 **첫 번째** 선택 요소만 보고,
+ * 그게 마침 그룹이면 그룹을 해제한다.
+ *
+ *     const e = v.selectedElements[0];
+ *     if (e && e.type === "group") { v.ungroupElements([e.id]); }
+ *     else { v.groupElements(v.selectedElements.map(e => e.id)); }
+ *
+ * 그래서 그룹 둘을 shift로 골라 ⌘G를 누르면 중첩되는 게 아니라 첫 그룹이 조용히
+ * 풀려 자식들이 페이지로 쏟아진다(``groupElements`` 자체는 그룹 안 그룹을 잘 다룬다 —
+ * 핫키의 분기만 틀렸다).
+ *
+ * 단축키와 메뉴가 같은 판정을 써야 하므로 컴포넌트에서 떼어 놓았다.
+ */
+
+/** ``groupAction``이 실제로 읽는 것 전부. */
+export type GroupStore = {
+  selectedElementsIds?: string[];
+  pages?: Array<{ id: string; children?: Array<{ id: string; type?: string }> }>;
+};
+
+/**
+ * 선택 중 **페이지 직속** 자식인 id들. 그룹 묶기는 형제끼리만 뜻이 있다 — 드릴인해서
+ * 고른 그룹 자식을 ⌘G가 새 그룹으로 뽑아낼 이유가 없다.
+ */
+export function groupableIds(store: GroupStore): string[] {
+  const selected = new Set(store.selectedElementsIds ?? []);
+  if (!selected.size) return [];
+  const out: string[] = [];
+  for (const page of store.pages ?? []) {
+    for (const child of page.children ?? []) {
+      if (selected.has(child.id)) out.push(child.id);
+    }
+  }
+  return out;
+}
+
+export function groupAction(
+  store: GroupStore,
+  shift: boolean,
+): { kind: "group" | "ungroup"; ids: string[] } | null {
+  const ids = groupableIds(store);
+  if (!ids.length) return null;
+  const typeOf = (id: string) => {
+    for (const page of store.pages ?? []) {
+      for (const child of page.children ?? []) {
+        if (child.id === id) return child.type;
+      }
+    }
+    return undefined;
+  };
+  const groups = ids.filter((id) => typeOf(id) === "group");
+  // ⌘⇧G는 늘 해제. 그룹 하나만 골라 ⌘G를 눌렀을 때도 해제다(스톡 편집기의 토글을 유지 —
+  // 사람들이 이미 익힌 동작).
+  if (shift || (ids.length === 1 && groups.length === 1)) {
+    return groups.length ? { kind: "ungroup", ids: groups } : null;
+  }
+  if (ids.length < 2) return null; // 묶을 게 없다
+  return { kind: "group", ids };
+}

package/lib/detail-page/hangul-roman.ts

@@ -0,0 +1,58 @@
+/**
+ * 한글을 라틴 글자로 옮긴다. **외래어를 되짚기 위한** 것이지 표기법을 지키려는 것이 아니다.
+ *
+ * 아이콘 이름은 전부 영어다. "사과"처럼 순우리말은 사전(`icon-keywords.ko.ts`)이
+ * 옮겨 주지만, "애플"·"카메라"처럼 **영어를 한글로 적은 말**은 사전에 다 담을 수 없다 —
+ * 브랜드·제품 이름은 끝이 없기 때문이다. 그런 말은 소리로 되짚는 편이 낫다.
+ *
+ * "애플" → `aepeul` → (`icon-fuzzy`의 자리표) → `apl` ← `apple`.
+ *
+ * 국어의 로마자 표기법을 그대로 따르지는 않는다(음운 변동·붙임표를 안 본다). 뒤에서
+ * 자리표가 모음을 뭉개고 비슷한 자음을 합치므로 여기서는 **글자 그대로** 옮기면 된다.
+ */
+
+const BASE = 0xac00;
+const LAST = 0xd7a3;
+
+const CHO = [
+  "g", "kk", "n", "d", "tt", "r", "m", "b", "pp", "s",
+  "ss", "", "j", "jj", "ch", "k", "t", "p", "h",
+];
+
+const JUNG = [
+  "a", "ae", "ya", "yae", "eo", "e", "yeo", "ye", "o", "wa",
+  "wae", "oe", "yo", "u", "wo", "we", "wi", "yu", "eu", "ui", "i",
+];
+
+const JONG = [
+  "", "k", "k", "ks", "n", "nj", "nh", "t", "l", "lk",
+  "lm", "lp", "ls", "lt", "lp", "lh", "m", "p", "ps", "t",
+  "t", "ng", "t", "t", "k", "t", "p", "t",
+];
+
+/** 한글이 하나라도 있는가. */
+export function hasHangul(text: string): boolean {
+  return /[가-힣]/.test(text);
+}
+
+/**
+ * 한글을 소리 나는 대로 라틴 글자로. 한글이 아닌 글자는 그대로 지나간다.
+ *
+ * 겹받침은 앞의 대표음만 남기는 대신 두 글자를 그대로 적는다(`ks`, `lm`) — 자리표가
+ * 어차피 뭉갠다.
+ */
+export function romanizeHangul(text: string): string {
+  let out = "";
+  for (const char of text) {
+    const code = char.codePointAt(0) ?? 0;
+    if (code < BASE || code > LAST) {
+      out += char;
+      continue;
+    }
+    const index = code - BASE;
+    out += CHO[Math.floor(index / 588)];
+    out += JUNG[Math.floor((index % 588) / 28)];
+    out += JONG[index % 28];
+  }
+  return out;
+}