@leviosa-ai/detail-page-editor 0.12.1 → 0.13.1

package/components/detail-page/detail-page-download-dialog.tsx

@@ -19,6 +19,7 @@ import {
 } from "../ui/select";
 import type { ExportDocument } from "../../lib/detail-page-canvas/export/document-model";
 import { detectGifPages } from "../../lib/detail-page-canvas/export/gif-plan";
+import { activeFramePages } from "../../lib/detail-page/frame-pages";
 import { isMp4EncodeSupported } from "../../lib/detail-page-canvas/export/mp4-support";
 import {
   detailPageEditorProfile,
@@ -43,6 +44,8 @@ type ExportPageLike = {
   id: string;
   computedWidth: number;
   computedHeight: number;
+  /** 이 판이 속한 프레임 이름이 여기 산다(`custom.frame`). */
+  custom?: unknown;
 };
 
 type ExportStoreLike = {
@@ -199,7 +202,10 @@ export const DetailPageDownloadDialog = observer(function DetailPageDownloadDial
 
   const selectedPages = useMemo(() => {
     if (scope === "current" && s.activePage) return [s.activePage];
-    return s.pages;
+    // 후보 여러 벌이 한 문서에 있으면 «전체»는 문서 전체가 아니라 **보고 있는 한 벌**
+    // 이다. 넷을 다 내보내면 마흔 장짜리 묶음이 나오고, 그걸 원해서 누르는 사람은
+    // 없다. 꼬리표 없는 문서에서는 지금까지처럼 전부다.
+    return activeFramePages(s.pages, s.activePage?.id);
   }, [scope, s.activePage, s.pages]);
 
   const docWidth = useMemo(

package/components/detail-page/detail-page-editor.tsx

@@ -117,6 +117,16 @@ export type DetailPageEditorProps = {
   structurePanel?: ReactNode;
   /** 헤더에 표시할 현재 상품/상세페이지 이름. 없으면 기본 라벨. */
   productName?: string;
+  /**
+   * 결과물이 될 벌 — 내려받기·발행이 향하는 곳.
+   *
+   * 문서에 안 적고 밖에서 받는다. 후보를 담은 화면은 이미 서버가 «고른 후보»를
+   * 들고 있고(목록 썸네일과 레퍼런스가 읽는 자리가 그것이다), 두 곳에 적어 두면
+   * 언젠가 서로 다른 답을 한다.
+   */
+  chosenFrame?: string;
+  /** 안 주면 벌에 체크를 안 그린다. */
+  onChooseFrame?: (frameKey: string) => void;
   /** 헤더 좌측 "뒤로가기" 동작. 없으면 버튼을 숨긴다. */
   onBack?: () => void;
   /**
@@ -152,6 +162,8 @@ export function DetailPageEditor({
   generatedId,
   structurePanel,
   productName,
+  chosenFrame,
+  onChooseFrame,
   onBack,
   headerActions,
 }: DetailPageEditorProps) {
@@ -289,14 +301,19 @@ export function DetailPageEditor({
           />
         )}
         <div className="relative min-w-0 flex-1">
-          <LeviosaCanvasWorkspace store={store} gap={4}>
+          <LeviosaCanvasWorkspace
+            store={store}
+            gap={4}
+            chosenFrame={chosenFrame}
+            onChooseFrame={onChooseFrame}
+          >
             {findReplace}
             <DetailPagePagesTimeline store={store} />
           </LeviosaCanvasWorkspace>
         </div>
       </div>
     );
-  }, [store, sidebarSections, SidebarSlot]);
+  }, [store, sidebarSections, SidebarSlot, chosenFrame, onChooseFrame]);
 
   const aiValue = useMemo(
     () => ({

package/components/detail-page/detail-page-frame-header.tsx

@@ -0,0 +1,103 @@
+"use client";
+
+/**
+ * 벌 위에 붙는 것 — **이게 결과물인가**, 그리고 **바꾸는 길**.
+ *
+ * ## 화면에 라벨은 최대 둘
+ *
+ * 넷에 다 라벨을 달면 «라벨 넷»으로 읽히고, 무엇이 상태이고 무엇이 행동인지 모양으로
+ * 구분이 안 된다. Shopify 의 테마 목록도 Vercel 의 배포 목록도 반대로 한다 — 지금
+ * 나가는 것 **하나에만** 표를 달고, 바꾸는 행동은 조용한 곳에 둔다.
+ *
+ *   대표인 벌     →  «대표»          글씨. 누를 것이 아니라 상태다
+ *   보고 있는 벌  →  «대표로 지정»    테두리 버튼. 누르면 바뀐다
+ *   나머지        →  아무것도 없음
+ *
+ * 고르려면 먼저 그 벌을 본다 — 이미 하던 동작이라 클릭이 하나 느는 것이 아니다.
+ *
+ * ## 뱃지에 손잡이를 달지 않는다
+ *
+ * 상태를 나타내는 표는 누르는 것이 아니고, 누르는 것은 버튼처럼 생겨야 한다. 둘을
+ * 같은 모양으로 두면 어느 쪽이 무엇인지 읽어 봐야 안다. 그래서 대표는 **글씨**,
+ * 지정은 **테두리 있는 버튼**이다.
+ *
+ * ## 왜 «최종»이 아닌가
+ *
+ * 언제든 바꾸는 값인데 «최종»이라 적으면 되돌릴 수 없다는 느낌을 준다 — 누르기 전에
+ * 한 번 망설이게 된다. 게다가 계속 고칠 문서라 최종도 아니다. «대표»는 여럿 중 밖으로
+ * 나가는 하나라는 뜻이 이미 붙어 있는 말이고(대표 사진), 실제로 이 값이 목록 카드
+ * 썸네일과 레퍼런스로 나가는 판까지 정한다.
+ *
+ * ## 흰 판 위가 아니라 회색 바닥 위
+ *
+ * 작업물을 가리지 않는 자리다. 피그마가 프레임 이름을 두는 그 자리이기도 하다.
+ */
+
+/** 이 줄이 차지하는 높이(화면 px). 배율과 무관하게 읽혀야 하므로 안 줄인다. */
+export const FRAME_HEAD_HEIGHT = 22;
+
+const COPY = {
+  chosen: "대표",
+  choose: "대표로 지정",
+  hint: "내려받기와 발행은 대표만 나갑니다",
+};
+
+export function DetailPageFrameHeader({
+  chosen,
+  selected,
+  onChoose,
+}: {
+  chosen: boolean;
+  /** 지금 보고 있는 벌인가. 여기에만 바꾸는 버튼이 뜬다. */
+  selected: boolean;
+  /** 안 주면 아무것도 안 그린다 — 고를 것이 없는 문서도 있다. */
+  onChoose?: () => void;
+}) {
+  if (!onChoose) return null;
+
+  const place = {
+    position: "absolute" as const,
+    left: 2,
+    bottom: "100%" as const,
+    marginBottom: 4,
+    height: FRAME_HEAD_HEIGHT - 4,
+    whiteSpace: "nowrap" as const,
+  };
+
+  if (chosen) {
+    return (
+      <span
+        style={place}
+        title={COPY.hint}
+        className="flex items-center gap-1 text-[11px] font-dpe-bold text-dpe-ink-900"
+      >
+        <svg width="11" height="11" viewBox="0 0 16 16" aria-hidden="true">
+          <path
+            d="M3 8.5 6.5 12 13 4.5"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2.6"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          />
+        </svg>
+        {COPY.chosen}
+      </span>
+    );
+  }
+
+  // 보고 있지 않은 벌은 아무 말도 안 한다. 누르면 보게 되고, 그때 이 버튼이 뜬다.
+  if (!selected) return null;
+
+  return (
+    <button
+      type="button"
+      style={place}
+      title={COPY.hint}
+      onClick={onChoose}
+      className="flex items-center rounded-full border border-dpe-ink-400 bg-dpe-surface px-2 text-[11px] font-dpe-semibold text-dpe-ink-700 transition-colors hover:border-dpe-ink-900 hover:text-dpe-ink-900"
+    >
+      {COPY.choose}
+    </button>
+  );
+}

package/components/detail-page/detail-page-pages-panel.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { detailPageEditorProfile } from "../../lib/detail-page/editor-profile";
+import { activeFramePages } from "../../lib/detail-page/frame-pages";
 
 import { Fragment, useCallback, useSyncExternalStore } from "react";
 import { observer } from "./canvas-observer";
@@ -151,11 +152,14 @@ const PageRow = observer(function PageRow({
   store,
   page,
   index,
+  canDuplicate,
   thumb,
 }: {
   store: StoreLike;
   page: PageLike;
   index: number;
+  /** 이 벌에 한 장을 더 넣을 수 있는가. 세는 것은 목록이 한다. */
+  canDuplicate: boolean;
   thumb: string | undefined;
 }) {
   const { t } = useTranslation("branding");
@@ -171,7 +175,6 @@ const PageRow = observer(function PageRow({
   const active = store.activePage?.id === page.id;
   const ratio = page.computedHeight / Math.max(1, page.computedWidth);
   const { role, title } = pageLabel(page, index, t);
-  const maxPages = detailPageEditorProfile().maxPages;
 
   const style: React.CSSProperties = {
     transform: CSS.Transform.toString(transform),
@@ -238,7 +241,7 @@ const PageRow = observer(function PageRow({
         <div className="flex shrink-0 flex-col gap-1">
           <button
             type="button"
-            disabled={store.pages.length >= maxPages}
+            disabled={!canDuplicate}
             onClick={(event) => {
               event.stopPropagation();
               page.clone?.();
@@ -311,22 +314,26 @@ export const DetailPagePagesPanel = observer(function DetailPagePagesPanel({
   // 합계가 곧 문서 높이지만, 캐러셀은 판이 따로따로라 합계가 아무 뜻이 없다 —
   // 8판짜리가 1080×10800 으로 보였다.
   const profile = detailPageEditorProfile();
-  const width = Math.round(s.pages[0]?.computedWidth ?? 0);
+  // 목록은 «지금 보고 있는 한 벌»만 담는다. 후보 넷을 담은 문서에서 마흔 줄을
+  // 늘어놓으면 어느 줄이 어느 벌인지 알 수가 없다.
+  const pages = activeFramePages(s.pages, s.activePage?.id);
+  const width = Math.round(pages[0]?.computedWidth ?? 0);
   const shownHeight = profile.page.fixed
     ? Math.round(
         typeof profile.page.height === "number"
           ? profile.page.height
-          : (s.pages[0]?.computedHeight ?? 0),
+          : (pages[0]?.computedHeight ?? 0),
       )
-    : Math.round(s.pages.reduce((acc, p) => acc + p.computedHeight, 0));
+    : Math.round(pages.reduce((acc, p) => acc + p.computedHeight, 0));
 
-  const canAdd = s.pages.length < profile.maxPages;
+  // 장 수 상한도 프레임마다다 — 한 벌이 열 장이라고 다른 벌까지 막을 이유가 없다.
+  const canAdd = pages.length < profile.maxPages;
 
   return (
     <div className="flex h-full flex-col">
       <div className="flex items-baseline justify-between px-4 py-3">
         <p className="text-base font-dpe-bold text-dpe-ink-900">
-          {t("detailPage.pages.totalPages", { count: s.pages.length })}
+          {t("detailPage.pages.totalPages", { count: pages.length })}
         </p>
         <p className="text-xs text-dpe-ink-400">
           {width} × {shownHeight} px
@@ -341,17 +348,18 @@ export const DetailPagePagesPanel = observer(function DetailPagePagesPanel({
           onDragEnd={handleDragEnd}
         >
           <SortableContext
-            items={s.pages.map((p) => p.id)}
+            items={pages.map((p) => p.id)}
             strategy={verticalListSortingStrategy}
           >
             <div className="space-y-2">
-              {s.pages.map((page, index) => (
+              {pages.map((page, index) => (
                 <Fragment key={page.id}>
                   <PageRow
                     store={s}
                     page={page}
                     index={index}
-                    thumb={detailPageThumbnailBus.get(page.id)}
+                    canDuplicate={canAdd}
+                    thumb={detailPageThumbnailBus.get(s, page.id)}
                   />
                   {/* 새 화면은 «어디에» 가 먼저다. 목록 끝에 버튼 하나를 두면 넣고 나서
                       다시 끌어 옮기게 되므로, 넣을 자리마다 하나씩 둔다. */}

package/components/detail-page/detail-page-pages-timeline.tsx

@@ -15,6 +15,7 @@ import { useSyncExternalStore } from "react";
 
 import { detailPageThumbnailBus } from "./detail-page-thumbnail-bus";
 import { observer } from "./canvas-observer";
+import { activeFramePages } from "../../lib/detail-page/frame-pages";
 
 type PageLike = { id: string; name?: unknown };
 type StoreLike = {
@@ -48,6 +49,8 @@ export const DetailPagePagesTimeline = observer(function DetailPagePagesTimeline
     () => 0,
   );
   const activeId = s.activePage?.id;
+  // 아래 띠도 목록과 같은 것을 본다 — 둘 다 «지금 어디 있나»를 말하는 물건이다.
+  const pages = activeFramePages(s.pages, activeId);
 
   if (!pagesTimelineVisible(s)) return null;
 
@@ -57,9 +60,9 @@ export const DetailPagePagesTimeline = observer(function DetailPagePagesTimeline
       style={{ minHeight: PAGES_TIMELINE_HEIGHT }}
       className="pointer-events-auto absolute inset-x-0 bottom-0 z-20 flex items-center gap-1.5 overflow-x-auto border-t border-dpe-ink-200 bg-dpe-surface/95 px-3 py-1.5 backdrop-blur-sm"
     >
-      {s.pages.map((page, index) => {
+      {pages.map((page, index) => {
         const active = page.id === activeId;
-        const thumb = detailPageThumbnailBus.get(page.id);
+        const thumb = detailPageThumbnailBus.get(s, page.id);
         return (
           <button
             key={page.id}

package/components/detail-page/detail-page-thumbnail-bus.ts

@@ -1,7 +1,7 @@
 "use client";
 
 /**
- * Tiny cross-component cache for page thumbnails (data URLs), keyed by page id.
+ * Tiny cross-component cache for page thumbnails (data URLs), keyed by store + page id.
  *
  * The stacked workspace owns the live Konva canvases (it renders the real
  * ``<Page>`` components), so it captures thumbnails from the DOM canvas there and
@@ -12,22 +12,33 @@
  * download for the same reason — real exports are server-side).
  */
 
-const cache = new Map<string, string>();
+// 캐러셀마다 `p01`부터 다시 쓰므로 page id만 키로 쓰면 다른 문서의 그림이 섞인다.
+// WeakMap이면 편집기를 닫았을 때 그 문서의 data URL도 같이 버려진다.
+const cache = new WeakMap<object, Map<string, string>>();
 const listeners = new Set<() => void>();
 let version = 0;
 
+function entries(scope: object): Map<string, string> {
+  const found = cache.get(scope);
+  if (found) return found;
+  const created = new Map<string, string>();
+  cache.set(scope, created);
+  return created;
+}
+
 export const detailPageThumbnailBus = {
-  get(id: string): string | undefined {
-    return cache.get(id);
+  get(scope: object, id: string): string | undefined {
+    return cache.get(scope)?.get(id);
   },
-  set(id: string, dataUrl: string): void {
-    if (cache.get(id) === dataUrl) return;
-    cache.set(id, dataUrl);
+  set(scope: object, id: string, dataUrl: string): void {
+    const scoped = entries(scope);
+    if (scoped.get(id) === dataUrl) return;
+    scoped.set(id, dataUrl);
     version += 1;
     listeners.forEach((l) => l());
   },
-  has(id: string): boolean {
-    return cache.has(id);
+  has(scope: object, id: string): boolean {
+    return cache.get(scope)?.has(id) ?? false;
   },
   // Monotonic version for useSyncExternalStore — changes whenever a thumbnail lands.
   getVersion(): number {

package/components/detail-page/frame-drag-bus.ts

@@ -0,0 +1,65 @@
+/**
+ * 손잡이와 끌기 층을 잇는 한 줄.
+ *
+ * 손잡이는 **판 상자 안**에 그려진다(엔진의 판 위 슬롯). 끌리는 동안 보이는 것들은
+ * 모든 판 **위**에 뜬 층이 그린다. 둘은 트리에서 멀리 떨어져 있는데, 그 사이로
+ * props 를 나르자고 여러 겹을 뚫는 것보다 이 한 줄이 싸다 — 이 저장소가 썸네일과
+ * 화면 다시 만들기를 잇는 방식과 같다.
+ */
+
+type Starter = (pageId: string, event: React.PointerEvent) => void;
+
+let starter: Starter | null = null;
+
+/**
+ * 지금 끼어들 자리. 판들이 **밀려나며** 만드는 빈칸이라, 이 값은 판을 그리는 쪽이
+ * 읽어야 한다 — 위에 겹쳐 그리면 밑에 있는 판을 가릴 뿐이고 «사이가 벌어졌다»가
+ * 안 된다.
+ */
+export type FrameInsert = {
+  frameKey: string;
+  /** 그 벌 안에서 몇 번째 자리인가. */
+  at: number;
+  /** 빈칸 높이(화면 px) — 끌고 있는 판의 높이다. */
+  height: number;
+  /** 넘쳐서 못 놓는 자리인가. */
+  full: boolean;
+} | null;
+
+let insert: FrameInsert = null;
+const listeners = new Set<() => void>();
+
+export function setFrameInsert(next: FrameInsert): void {
+  const same =
+    insert === next ||
+    (insert &&
+      next &&
+      insert.frameKey === next.frameKey &&
+      insert.at === next.at &&
+      insert.full === next.full &&
+      insert.height === next.height);
+  if (same) return;
+  insert = next;
+  for (const listener of [...listeners]) listener();
+}
+
+export function getFrameInsert(): FrameInsert {
+  return insert;
+}
+
+export function subscribeFrameInsert(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** 끌기 층이 자기를 걸어 둔다. */
+export function setFrameDragStarter(fn: Starter | null): void {
+  starter = fn;
+}
+
+/** 손잡이가 부른다. 층이 없으면 아무 일도 안 일어난다. */
+export function startFrameDrag(pageId: string, event: React.PointerEvent): void {
+  starter?.(pageId, event);
+}

package/components/detail-page/frame-drag-grip.tsx

@@ -0,0 +1,37 @@
+"use client";
+
+/**
+ * 판을 다른 벌로 끌 때 잡는 자리.
+ *
+ * **판 상자 안에** 산다. 예전에는 마우스 자리를 재어 판 위에 띄웠는데, 손잡이가 판
+ * 모서리에 있다 보니 바깥에서 다가가는 손은 «판 밖»을 지나 온다 — 그때마다 사라져서
+ * 잡으러 가는 내내 깜빡였다. 크기를 키워도 그대로였다. 안에 있으면 잴 것이 없고
+ * 깜빡일 일도 없다.
+ *
+ * **흐리게 두지 않는다.** 옅게 깔아 두면 «있는 줄 몰라서 못 잡는» 물건이 된다.
+ * 20px 짜리라 늘 또렷해도 시끄럽지 않다.
+ */
+
+import { GripVertical } from "lucide-react";
+
+import { startFrameDrag } from "./frame-drag-bus";
+
+export function FrameDragGrip({ pageId }: { pageId: string }) {
+  return (
+    <button
+      type="button"
+      data-dp-frame-grip=""
+      title="다른 벌로 끌어오기"
+      aria-label="이 판을 다른 벌로 끌어오기"
+      onPointerDown={(event) => {
+        event.preventDefault();
+        event.stopPropagation();
+        startFrameDrag(pageId, event);
+      }}
+      style={{ position: "absolute", left: 5, top: 5, width: 20, height: 20, zIndex: 6 }}
+      className="flex cursor-grab items-center justify-center rounded bg-dpe-surface/80 text-dpe-ink-800 transition-colors hover:bg-dpe-ink-900 hover:text-dpe-on-accent"
+    >
+      <GripVertical aria-hidden="true" size={13} />
+    </button>
+  );
+}

package/components/detail-page/frame-drag-layer.tsx

@@ -0,0 +1,261 @@
+"use client";
+
+/**
+ * 판을 **다른 벌로 끌어오는 층.**
+ *
+ * ## 왜 캔버스가 아니라 여기서 하나
+ *
+ * 판마다 제 무대(Konva Stage)가 따로다. 판 위의 것을 끌어 그 무대 밖으로 나가면 그
+ * 캔버스에 **잘려서 사라진다** — 끌고 있다는 느낌 자체가 없다. 그래서 끌리는 동안
+ * 보이는 것은 무대가 아니라 모든 무대 **위에 뜬 이 층**이 그린다.
+ *
+ * 잡는 자리(손잡이)는 여기 없다. 그건 판 상자 안에 산다(`frame-drag-grip`) — 밖에서
+ * 자리를 재어 띄우면 손이 다가가는 동안 깜빡인다. 둘은 한 줄짜리 다리로 잇는다.
+ *
+ * ## 끄는 동안 문서는 한 글자도 안 바뀐다
+ *
+ * 놓는 순간에만 바꾼다. 그래야 중간에 그만두거나 창을 닫아도 남는 것이 없고,
+ * 되돌리기도 «놓은 것» 한 단계로 깔끔하다.
+ *
+ * ## 열 장은 놓기 **전에** 막는다
+ *
+ * 넘겨 놓고 서버가 거절하게 두면, 3초마다 도는 자동저장이 «저장 실패»만 띄우고
+ * 사람은 무엇을 되돌려야 하는지 모른다. 여기서 미리 막고 이유를 한 줄 적는다.
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { copyPageToFrame } from "@leviosa-ai/canvas/edit/commands";
+import { frameInsertIndex, frameOf } from "@leviosa-ai/canvas/render/frames";
+import type { CanvasStore } from "@leviosa-ai/canvas/store";
+import { detailPageEditorProfile } from "../../lib/detail-page/editor-profile";
+import { setFrameDragStarter, setFrameInsert } from "./frame-drag-bus";
+
+/** 벌어지는 칸의 높이 — 끌고 있는 판 높이의 이만큼. */
+const SLOT_RATIO = 0.28;
+
+type Box = { left: number; top: number; width: number; height: number };
+
+type Drop = {
+  frameKey: string;
+  /** 그 벌 안에서 몇 번째 자리인가. */
+  at: number;
+  /** 놓일 벌 전체(층 좌표). 여기를 통째로 밝혀 «저기로 간다»를 말한다. */
+  area: Box;
+  /** 넘쳐서 못 놓는가. */
+  full: boolean;
+};
+
+function boxIn(node: Element, host: DOMRect): Box {
+  const rect = node.getBoundingClientRect();
+  return {
+    left: rect.left - host.left,
+    top: rect.top - host.top,
+    width: rect.width,
+    height: rect.height,
+  };
+}
+
+export function FrameDragLayer({
+  store,
+  containerRef,
+}: {
+  store: CanvasStore;
+  containerRef: React.RefObject<HTMLDivElement | null>;
+}) {
+  const [drag, setDrag] = useState<{
+    pageId: string;
+    from: string;
+    box: Box;
+    x: number;
+    y: number;
+    drop: Drop | null;
+  } | null>(null);
+  const dragRef = useRef(drag);
+  dragRef.current = drag;
+
+  /** 커서 아래에서 놓을 자리를 읽는다. DOM 에서 직접 잰다 — 배율·스크롤이 다 반영돼 있다. */
+  const readDrop = useCallback(
+    (clientX: number, clientY: number): Drop | null => {
+      const host = containerRef.current?.getBoundingClientRect();
+      if (!host) return null;
+      const frames = Array.from(
+        document.querySelectorAll<HTMLElement>("[data-lc-frame]"),
+      );
+      if (!frames.length) return null;
+
+      // 커서를 품은 열, 없으면 가로로 제일 가까운 열.
+      const scored = frames.map((node) => {
+        const rect = node.getBoundingClientRect();
+        return {
+          node,
+          dx: Math.max(rect.left - clientX, 0, clientX - rect.right),
+        };
+      });
+      scored.sort((a, b) => a.dx - b.dx);
+      const target = scored[0];
+      const frameKey = target.node.dataset.lcFrame ?? "";
+
+      const pages = Array.from(
+        target.node.querySelectorAll<HTMLElement>("[data-lc-page]"),
+      );
+      // 커서보다 위에서 끝난 판의 개수가 곧 끼어들 자리다.
+      let at = pages.length;
+      for (let index = 0; index < pages.length; index += 1) {
+        const rect = pages[index].getBoundingClientRect();
+        if (clientY < rect.top + rect.height / 2) {
+          at = index;
+          break;
+        }
+      }
+
+      const held = store.pages.filter((page) => frameOf(page) === frameKey).length;
+      return {
+        frameKey,
+        at,
+        area: boxIn(target.node, host),
+        full: held >= detailPageEditorProfile().maxPages,
+      };
+    },
+    [containerRef, store],
+  );
+
+  // 손잡이가 부를 자리를 걸어 둔다.
+  useEffect(() => {
+    setFrameDragStarter((pageId, event) => {
+      const host = containerRef.current?.getBoundingClientRect();
+      const node = document.querySelector<HTMLElement>(
+        `[data-lc-page="${CSS.escape(pageId)}"]`,
+      );
+      const page = store.getPageById(pageId);
+      if (!host || !node || !page) return;
+      setDrag({
+        pageId,
+        from: frameOf(page),
+        box: boxIn(node, host),
+        x: event.clientX - host.left,
+        y: event.clientY - host.top,
+        drop: null,
+      });
+    });
+    return () => setFrameDragStarter(null);
+  }, [containerRef, store]);
+
+  // 끄는 동안은 창 전체를 듣는다 — 커서가 판 밖으로 나가도 따라가야 한다.
+  useEffect(() => {
+    if (!drag) return;
+    const host = containerRef.current?.getBoundingClientRect();
+    if (!host) return;
+    const dragBox = drag.box;
+
+    const onMove = (event: PointerEvent) => {
+      const drop = readDrop(event.clientX, event.clientY);
+      // 빈칸은 판을 그리는 쪽이 흐름 안에 넣는다 — 그래야 판들이 실제로 밀린다.
+      // 여기서는 «어느 벌 몇 번째»만 말한다.
+      setFrameInsert(
+        drop
+          ? {
+              frameKey: drop.frameKey,
+              at: drop.at,
+              // 판 한 장만큼 벌리면 열이 통째로 쿵 내려가서 놀란다. 자리가
+              // 생겼다는 것만 보이면 되므로 그보다 얕게 연다.
+              height: Math.max(24, dragBox.height * SLOT_RATIO),
+              full: drop.full,
+            }
+          : null,
+      );
+      setDrag((current) =>
+        current
+          ? {
+              ...current,
+              x: event.clientX - host.left,
+              y: event.clientY - host.top,
+              drop,
+            }
+          : current,
+      );
+    };
+    const onUp = () => {
+      const current = dragRef.current;
+      setDrag(null);
+      setFrameInsert(null);
+      if (!current?.drop || current.drop.full) return;
+      // 같은 벌 안이면 순서를 바꾼다. 예전에는 아무 일도 안 일어나서 «놓아도
+      // 그대로»라고 적어 줘야 했는데, 그건 설명이 필요한 동작이라는 뜻이었다.
+      if (current.drop.frameKey === current.from) {
+        const page = store.getPageById(current.pageId);
+        if (!page) return;
+        const from = store.pages.indexOf(page);
+        let to = frameInsertIndex(store.pages, current.drop.frameKey, current.drop.at);
+        // 빼고 나면 뒤쪽 자리는 한 칸 당겨진다.
+        if (from < to) to -= 1;
+        if (from !== to) page.setZIndex(to);
+        return;
+      }
+      copyPageToFrame(store, current.pageId, current.drop.frameKey, current.drop.at);
+    };
+    window.addEventListener("pointermove", onMove);
+    window.addEventListener("pointerup", onUp);
+    return () => {
+      window.removeEventListener("pointermove", onMove);
+      window.removeEventListener("pointerup", onUp);
+    };
+  }, [containerRef, drag, readDrop, store]);
+
+  if (!drag) return null;
+
+  return (
+    <>
+      {/* 끌리는 판. 무대 밖에서도 보여야 하므로 여기서 그린다. */}
+      <div
+        style={{
+          position: "absolute",
+          left: drag.x - drag.box.width / 2,
+          top: drag.y - drag.box.height / 2,
+          width: drag.box.width,
+          height: drag.box.height,
+          zIndex: 40,
+          pointerEvents: "none",
+        }}
+        className="rounded-dpe-md border-2 border-dpe-ink-900 bg-dpe-ink-900/10"
+      />
+
+      {drag.drop ? (
+        <>
+          {/* 놓일 벌을 통째로 밝힌다. 가는 선 하나로는 «어디로 가는지»가 안 읽힌다. */}
+          <div
+            style={{
+              position: "absolute",
+              left: drag.drop.area.left,
+              top: drag.drop.area.top,
+              width: drag.drop.area.width,
+              height: drag.drop.area.height,
+              zIndex: 39,
+              pointerEvents: "none",
+              borderRadius: 10,
+              outline: `3px solid ${drag.drop.full ? "#c0392b" : "#2563eb"}`,
+              background: drag.drop.full
+                ? "rgba(192, 57, 43, 0.06)"
+                : "rgba(37, 99, 235, 0.06)",
+            }}
+          />
+          {/* 못 놓는 경우에만 이유를 적는다. 되는 경우는 벌어진 자리가 대신 말한다. */}
+          {drag.drop.full ? (
+            <span
+              style={{
+                position: "absolute",
+                left: drag.x + 16,
+                top: drag.y + 16,
+                zIndex: 42,
+                pointerEvents: "none",
+              }}
+              className="rounded-dpe-md bg-dpe-danger-600 px-2 py-1 text-[11px] font-dpe-semibold text-dpe-on-accent"
+            >
+              {detailPageEditorProfile().maxPages}장이 최대입니다
+            </span>
+          ) : null}
+        </>
+      ) : null}
+    </>
+  );
+}

package/components/detail-page/leviosa-canvas-workspace.tsx

@@ -22,6 +22,7 @@ import {
   useMemo,
   useRef,
   useState,
+  useSyncExternalStore,
   type ReactNode,
 } from "react";
 
@@ -36,6 +37,12 @@ import {
   pagesTimelineVisible,
 } from "./detail-page-pages-timeline";
 import { detailPageThumbnailBus } from "./detail-page-thumbnail-bus";
+import { FrameDragGrip } from "./frame-drag-grip";
+import {
+  getFrameInsert,
+  subscribeFrameInsert,
+} from "./frame-drag-bus";
+import { FrameDragLayer } from "./frame-drag-layer";
 import { GifAnimator } from "./gif-animator";
 import { GroupDrillIn } from "./group-drill-in";
 import { HoverHighlightOverlay } from "./hover-highlight-overlay";
@@ -43,6 +50,11 @@ import { CanvasSectionHeightHandle } from "./section-height-handle";
 import { loadEditorFont } from "../../lib/detail-page-canvas/editor-fonts";
 import { ZoomButtons } from "@leviosa-ai/canvas";
 import { CanvasView } from "@leviosa-ai/canvas/render/canvas-view";
+import { frameOf, groupFrames } from "@leviosa-ai/canvas/render/frames";
+import {
+  DetailPageFrameHeader,
+  FRAME_HEAD_HEIGHT,
+} from "./detail-page-frame-header";
 import { useCanvasVersion } from "@leviosa-ai/canvas/use-canvas";
 import type { CanvasStore } from "@leviosa-ai/canvas/store";
 
@@ -51,6 +63,24 @@ const MAX_SCALE = 5;
 const clamp = (v: number, lo: number, hi: number) =>
   Math.max(lo, Math.min(hi, v));
 
+/**
+ * 벌 사이 거리 — **판 좌표**로 잰다.
+ *
+ * 화면 px 로 고정하면 확대했을 때는 붙어 보이고 축소했을 때는 벌어져 보인다. 판
+ * 하나가 1080 인 캐러셀에서 이 값은 판의 4분의 1쯤이라, 어느 배율에서 보든 «저건
+ * 다른 벌»이 한눈에 잡힌다.
+ */
+const FRAME_GAP_DOC = 240;
+
+/**
+ * 벌 위의 줄이 설 자리(화면 px).
+ *
+ * 그 줄은 흰 판 **밖**, 회색 바닥 위에 앉는다 — 작업물을 안 가리는 자리이고 피그마가
+ * 프레임 이름을 두는 자리다. 대신 작업 영역 위쪽에 그만큼을 비워 둬야 한다. 안 그러면
+ * 스크롤 영역 바깥으로 잘려서 아예 안 보인다(실제로 그렇게 사라져 있었다).
+ */
+const FRAME_HEAD = FRAME_HEAD_HEIGHT + 6;
+
 /** 썸네일 해상도. 페이지 패널의 칸이 작아 이 정도면 충분하다. */
 const THUMB_PIXEL_RATIO = 0.12;
 
@@ -62,12 +92,18 @@ export function LeviosaCanvasWorkspace({
   gap = 4,
   paddingX = 16,
   backgroundColor = "rgb(241, 241, 241)",
+  chosenFrame,
+  onChooseFrame,
   children,
 }: {
   store: CanvasStore;
   gap?: number;
   paddingX?: number;
   backgroundColor?: string;
+  /** 결과물이 될 벌. 내려받기·발행이 향하는 곳이다. */
+  chosenFrame?: string;
+  /** 안 주면 체크박스를 안 그린다 — 고를 것이 없는 문서도 있다. */
+  onChooseFrame?: (frameKey: string) => void;
   /** 작업 영역 위에 얹을 것(찾기·바꾸기 같은 편집기 고유 층). */
   children?: ReactNode;
 }) {
@@ -108,8 +144,21 @@ export function LeviosaCanvasWorkspace({
     const page = store.activePage ?? store.pages[0];
     const usableW = Math.max(1, viewport.width - 2 * paddingX);
     const usableH = Math.max(1, viewport.height - 2 * gap);
+    // 프레임이 여럿이면 **열 전체**가 가로로 들어와야 한다 — 한 벌만 보이면
+    // 나란히 놓은 뜻이 없다. 세로는 여전히 한 장 기준이다: 시안 하나가 스무
+    // 장이 넘는 상세페이지에서 기둥 전체를 넣으면 아무것도 안 읽힌다.
+    const frames = groupFrames(store.pages);
+    const spread =
+      frames.length > 1
+        ? frames.reduce(
+            (sum, frame) =>
+              sum + Math.max(1, ...frame.pages.map((one) => one.width)),
+            0,
+          ) +
+          (frames.length - 1) * FRAME_GAP_DOC
+        : page.width;
     const next = clamp(
-      Math.min(usableW / page.width, usableH / page.height) * 0.94,
+      Math.min(usableW / spread, usableH / page.height) * 0.94,
       MIN_SCALE,
       MAX_SCALE,
     );
@@ -152,15 +201,28 @@ export function LeviosaCanvasWorkspace({
   const recomputeActive = useCallback(() => {
     const inner = innerRef.current;
     if (!inner) return;
-    const middle = inner.getBoundingClientRect().top + inner.clientHeight / 2;
+    // 화면 한가운데를 **점으로** 잡는다. 열이 하나뿐이던 때는 세로만 봐도 답이
+    // 하나였지만, 열이 여럿이면 그 높이를 지나는 페이지가 열 수만큼 나온다 —
+    // 세로만 보면 언제나 맨 왼쪽 열이 이겨서 다른 벌을 고를 수가 없다.
+    const frame = inner.getBoundingClientRect();
+    const cx = frame.left + inner.clientWidth / 2;
+    const cy = frame.top + inner.clientHeight / 2;
     const nodes = Array.from(
       inner.querySelectorAll<HTMLElement>("[data-lc-page]"),
     );
-    const hit =
-      nodes.find((node) => {
-        const box = node.getBoundingClientRect();
-        return box.top <= middle && box.bottom >= middle;
-      }) ?? nodes[0];
+    const distance = (node: HTMLElement) => {
+      const box = node.getBoundingClientRect();
+      const dx = Math.max(box.left - cx, 0, cx - box.right);
+      const dy = Math.max(box.top - cy, 0, cy - box.bottom);
+      return dx * dx + dy * dy;
+    };
+    // 가운데를 품은 페이지는 거리가 0이라 그대로 이긴다. 아무것도 안 품으면
+    // (확대해서 빈 자리를 보고 있을 때) 제일 가까운 것으로 떨어진다.
+    const hit = nodes.reduce<HTMLElement | undefined>(
+      (best, node) =>
+        !best || distance(node) < distance(best) ? node : best,
+      undefined,
+    );
     const id = hit?.dataset.lcPage;
     if (!id || store.activePage?.id === id) return;
     scrollSetId.current = id;
@@ -197,29 +259,66 @@ export function LeviosaCanvasWorkspace({
   // 굽는 동안 그 페이지를 화면 밖에서도 그려야 해서다 — 30장을 한꺼번에 띄우면
   // 브라우저가 멈춘다.
   const panelOpen = store.openedSidePanel === "pages";
+  const panelOpenRef = useRef(panelOpen);
+  panelOpenRef.current = panelOpen;
+  const dirtyThumbnailIds = useRef(new Set<string>());
+  const [thumbnailRevision, setThumbnailRevision] = useState(0);
+
+  // 요소 속성 변경은 page.version을 올리지 않는다. 문서 변경 알림에서 현재 페이지만
+  // 더럽다고 적어 두고, 패널이 열려 있을 때만 아래 굽기 작업을 깨운다.
+  useEffect(
+    () =>
+      store.on("change", () => {
+        const id = store.activePage?.id;
+        if (id) dirtyThumbnailIds.current.add(id);
+        if (panelOpenRef.current) setThumbnailRevision((value) => value + 1);
+      }),
+    [store],
+  );
+
   useEffect(() => {
     if (!panelOpen) return;
     let cancelled = false;
-    void (async () => {
-      for (const page of store.pages) {
-        if (cancelled) return;
-        if (detailPageThumbnailBus.has(page.id)) continue;
-        try {
-          const uri = await store.toDataURL({
-            pageId: page.id,
-            pixelRatio: THUMB_PIXEL_RATIO,
-          });
+    // 타이핑·드래그 중 매 프레임 다시 굽지 않고, 손을 잠깐 놓았을 때 바뀐 페이지만 굽는다.
+    const timer = window.setTimeout(() => {
+      void (async () => {
+        for (const page of store.pages) {
           if (cancelled) return;
-          detailPageThumbnailBus.set(page.id, uri);
-        } catch {
-          // 못 구운 페이지는 다음에 다시 시도한다(패널을 다시 열면 온다).
+          if (
+            !dirtyThumbnailIds.current.has(page.id) &&
+            detailPageThumbnailBus.has(store, page.id)
+          ) {
+            continue;
+          }
+          try {
+            const uri = await store.toDataURL({
+              pageId: page.id,
+              pixelRatio: THUMB_PIXEL_RATIO,
+            });
+            if (cancelled) return;
+            dirtyThumbnailIds.current.delete(page.id);
+            detailPageThumbnailBus.set(store, page.id, uri);
+          } catch {
+            // 못 구운 페이지는 다음에 다시 시도한다(패널을 다시 열면 온다).
+          }
         }
-      }
-    })();
+      })();
+    }, 250);
     return () => {
       cancelled = true;
+      window.clearTimeout(timer);
     };
-  }, [panelOpen, pageIds, store]);
+  }, [panelOpen, pageIds, store, thumbnailRevision]);
+
+  const frameCount = groupFrames(store.pages).length;
+  // 끼어들 자리는 끌기 층이 정하고, 빈칸은 판을 그리는 쪽이 흐름 안에 넣는다.
+  const frameInsert = useSyncExternalStore(
+    subscribeFrameInsert,
+    getFrameInsert,
+    () => null,
+  );
+  // 보고 있는 벌 — 활성 페이지가 속한 벌이다. 목록·아래 띠가 보는 것과 같다.
+  const activeFrame = frameOf(store.activePage ?? store.pages[0] ?? {});
 
   const pageWidth = useMemo(
     () => Math.max(1, ...store.pages.map((page) => page.width)),
@@ -249,27 +348,68 @@ export function LeviosaCanvasWorkspace({
           // 페이지 바깥의 빈 자리를 누르면 선택 해제. 페이지 안은 캔버스가 처리한다.
           const target = event.target as HTMLElement;
           if (
-            !target.closest("[data-lc-page]") &&
-            !target.closest("[data-dp-quicktoolbar]")
+            target.closest("[data-lc-page]") ||
+            target.closest("[data-dp-quicktoolbar]")
           ) {
-            store.selectElements([]);
+            return;
           }
+          store.selectElements([]);
+          // 판 밖이어도 벌의 빈 자리를 눌렀으면 그 벌로 간다 — 이름표를 없앴으니
+          // 여기가 «저 벌을 보겠다»고 말하는 유일한 자리다.
+          const key = target.closest<HTMLElement>("[data-lc-frame]")?.dataset
+            .lcFrame;
+          if (key === undefined) return;
+          const first = store.pages.find((page) => frameOf(page) === key);
+          if (first) store.selectPage(first.id);
         }}
         style={{
           position: "absolute",
           inset: 0,
-          overflowX: "hidden",
+          // 프레임이 하나뿐이면 예전 그대로다. 가운데 정렬은 내용이 넘칠 때
+          // 왼쪽으로 스크롤을 못 하게 만드는 자리라, 열이 여럿일 때는 왼쪽에
+          // 붙여 놓고 가로 스크롤을 연다.
+          overflowX: frameCount > 1 ? "auto" : "hidden",
           overflowY: "auto",
           display: "flex",
           flexDirection: "column",
-          alignItems: "center",
-          padding: `${gap}px ${paddingX}px`,
+          alignItems: frameCount > 1 ? "flex-start" : "center",
+          padding: `${frameCount > 1 ? gap + FRAME_HEAD : gap}px ${paddingX}px ${gap}px`,
         }}
       >
         <CanvasView
           store={store}
           scale={scale}
           gap={gap}
+          // 열이 여럿이면 가운데 정렬을 정렬 속성이 아니라 자동 여백으로 준다 —
+          // 축소해서 남는 자리가 생겨도 가운데를 지키고, 커져도 스크롤이 산다.
+          center={frameCount > 1}
+          // 손잡이는 판 상자 **안**에 산다. 밖에서 자리를 재어 띄우면 손이 다가가는
+          // 동안 «판 밖»을 지나며 깜빡인다.
+          renderPageChrome={
+            frameCount > 1 ? (id) => <FrameDragGrip pageId={id} /> : undefined
+          }
+          frameGap={FRAME_GAP_DOC * scale}
+          frameInsert={frameInsert}
+          renderFrameHeader={(key) => (
+            <DetailPageFrameHeader
+              chosen={key === chosenFrame}
+              selected={key === activeFrame}
+              onChoose={onChooseFrame ? () => onChooseFrame(key) : undefined}
+            />
+          )}
+          frameStyle={(key) => ({
+            padding: 8,
+            borderRadius: 10,
+            // 회색 바닥 위의 **흰 판** — 피그마의 프레임이 그렇다. 판을 얹을 자리가
+            // 밝아야 «저기서 저기까지가 한 벌»이 읽힌다.
+            background: "#ffffff",
+            border: `1px solid ${key === activeFrame ? "rgba(0,0,0,0.45)" : "rgba(0,0,0,0.10)"}`,
+            // **흐리게 하지 않는다.** 한때 «보고 있거나 대표인 것만 선명»으로 뒀는데,
+            // 이 화면은 후보를 **견주는** 자리다 — 넷 중 둘이 바래 있으면 견줄 수가
+            // 없고, 판을 옮기면 색이 달라져서 옮긴 것이 변한 것처럼 보인다.
+            // 무엇이 나가는지는 «대표» 표가, 무엇을 보고 있는지는 테두리가 이미 말한다.
+            transition: "border-color 0.15s ease",
+          })}
           interactive
           loadFont={loadEditorFont}
         />
@@ -295,6 +435,9 @@ export function LeviosaCanvasWorkspace({
         scrollRef={innerRef}
       />
       <GroupDrillIn store={store} containerRef={outerRef} />
+      {/* 판을 다른 벌로 끌어오는 층. 무대마다 캔버스가 따로라, 끌리는 동안 보이는
+          것은 무대가 아니라 그 위에 뜬 이 층이 그린다. */}
+      <FrameDragLayer store={store} containerRef={outerRef} />
       <GifAnimator store={store} />
       {/* 활성 화면의 아래 끝을 잡아 끌어 길이를 바꾸는 손잡이. 우측 패널의 숫자와
           같은 함수를 거친다(`section-height.ts`) — 배경 요소까지 같이 늘리고 서버

package/lib/detail-page/frame-pages.ts

@@ -0,0 +1,27 @@
+import { frameOf } from "@leviosa-ai/canvas/render/frames";
+
+type PageLike = { id: string; custom?: unknown };
+
+/**
+ * 지금 **보고 있는 프레임**의 페이지들.
+ *
+ * 후보 여러 벌을 한 문서에 담으면 페이지 목록과 아래 띠가 곧장 쓸모를 잃는다 — 열두
+ * 줄짜리 목록에서 어느 줄이 어느 벌인지 알 수가 없다. 그 둘은 «지금 어디 있나»를
+ * 말하는 물건이라, 보고 있는 한 벌만 담는 것이 맞다.
+ *
+ * 보고 있는 프레임은 **활성 페이지가 속한 프레임**이다. 따로 기억하지 않는다 —
+ * 상태가 하나 더 생기면 캔버스와 목록이 서로 다른 답을 하는 날이 온다.
+ *
+ * 꼬리표가 하나도 없으면 문서 전체가 한 프레임이다. 지금까지 만들어진 문서에서
+ * 이 함수는 아무것도 안 거른다.
+ */
+export function activeFramePages<T extends PageLike>(
+  pages: readonly T[],
+  activePageId?: string,
+): T[] {
+  if (!pages.some((page) => frameOf(page))) return [...pages];
+  const active = pages.find((page) => page.id === activePageId) ?? pages[0];
+  if (!active) return [];
+  const frame = frameOf(active);
+  return pages.filter((page) => frameOf(page) === frame);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leviosa-ai/detail-page-editor",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "description": "Leviosa detail-page editor shell. Source-only: consumers compile it through Next transpilePackages. Every app coupling (sourcing server, brand store, cache keys, toast) arrives through the DetailPageHost interface, and every URL it fetches comes from configureDetailPageEditor.",
   "type": "module",
   "license": "UNLICENSED",
@@ -67,7 +67,7 @@
     "woff2-encoder": "2.0.0"
   },
   "peerDependencies": {
-    "@leviosa-ai/canvas": "0.5.0",
+    "@leviosa-ai/canvas": "0.6.1",
     "@tanstack/react-query": "^5.100.3",
     "konva": "^10.0.0",
     "lucide-react": "^0.563.0 || ^1.0.0",