@leviosa-ai/detail-page-editor 0.1.0

package/lib/detail-page/text-gif-layout.ts

@@ -0,0 +1,245 @@
+/**
+ * '텍스트를 GIF로'가 서버에 넘길 **실측 레이아웃**.
+ *
+ * 예전에는 글자와 색만 넘겼고 서버가 캔버스를 글자 수로 추정했다(``fontSize * chars *
+ * 0.66 + 96``). 그렇게 나온 GIF를 편집기가 페이지 폭의 62%로 꽂으니, 원본이 600px짜리
+ * 상자였어도 결과는 훨씬 크게 들어갔다 — 유저가 본 "폰트 크기가 커지고 줄이 밀리는"
+ * 증상의 정체다.
+ *
+ * 그래서 여기서 편집기가 아는 것을 전부 잰다: 원본 상자, 줄마다의 자리와 정렬, 그리고
+ * **눈에 보이는 줄바꿈**. 편집기의 텍스트는 상자 폭에서 자동으로 접히는데(soft wrap)
+ * SVG ``<text>``는 접히지 않으므로, 접힌 결과를 여기서 미리 줄로 쪼개 넘겨야 같은 모양이
+ * 나온다.
+ */
+
+export type TextElementLike = {
+  x?: unknown;
+  y?: unknown;
+  width?: unknown;
+  height?: unknown;
+  text?: unknown;
+  fill?: unknown;
+  fontSize?: unknown;
+  fontWeight?: unknown;
+  fontFamily?: unknown;
+  lineHeight?: unknown;
+  align?: unknown;
+  verticalAlign?: unknown;
+};
+
+export type Box = { x: number; y: number; width: number; height: number };
+
+export type LaidOutLine = {
+  text: string;
+  color: string;
+  fontSize: number;
+  fontWeight: number;
+  fontFamily: string;
+  /** 상자 좌상단 기준 앵커 x. */
+  x: number;
+  /** 상자 좌상단 기준 줄의 세로 중심 y. */
+  y: number;
+  anchor: "start" | "middle" | "end";
+};
+
+/** 한 줄의 렌더 폭을 재는 함수(브라우저에서는 canvas measureText). */
+export type Measure = (spec: {
+  text: string;
+  fontSize: number;
+  fontWeight: number;
+  fontFamily: string;
+}) => number;
+
+/** Canvas 텍스트 기본값(model/text-model.js). */
+const DEFAULT_LINE_HEIGHT = 1.2;
+const DEFAULT_FONT_SIZE = 14;
+
+/** 접기 폭주 방지 — 폭이 말도 안 되게 좁아도 무한 루프에 빠지지 않게. */
+const MAX_WRAPPED_LINES = 60;
+
+function num(value: unknown, fallback = 0): number {
+  const parsed = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+/** ``normal``/``bold`` 같은 CSS 키워드를 숫자 굵기로. */
+export function toFontWeight(value: unknown): number {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return Math.min(900, Math.max(100, Math.round(value)));
+  }
+  const text = String(value ?? "").trim().toLowerCase();
+  if (text === "bold") return 700;
+  if (text === "normal" || text === "") return 400;
+  const parsed = Number(text);
+  return Number.isFinite(parsed)
+    ? Math.min(900, Math.max(100, Math.round(parsed)))
+    : 400;
+}
+
+/**
+ * 편집기가 보여주는 줄바꿈을 그대로 재현한다.
+ *
+ * 하드 개행으로 먼저 쪼개고, 각 줄이 상자 폭을 넘으면 들어가는 만큼 잘라 접는다.
+ * 자를 자리는 마지막 공백을 우선하되(단어 보존), 공백이 없는 한국어·중국어 문장은
+ * 글자 단위로 접는다 — Konva가 하는 것과 같은 결이다.
+ */
+export function wrapText(
+  text: string,
+  maxWidth: number,
+  measure: Measure,
+  style: { fontSize: number; fontWeight: number; fontFamily: string },
+): string[] {
+  const hard = String(text ?? "").split(/\r?\n/);
+  if (!(maxWidth > 0)) {
+    return hard.map((line) => line.trim()).filter(Boolean);
+  }
+  const out: string[] = [];
+  for (const raw of hard) {
+    let rest = raw.trim();
+    if (!rest) continue;
+    let guard = 0;
+    while (rest && guard < MAX_WRAPPED_LINES) {
+      guard += 1;
+      if (measure({ ...style, text: rest }) <= maxWidth) {
+        out.push(rest);
+        break;
+      }
+      // 들어가는 가장 긴 앞부분(폭은 길이에 대해 단조 증가한다).
+      let low = 1;
+      let high = rest.length;
+      let fit = 1;
+      while (low <= high) {
+        const mid = (low + high) >> 1;
+        if (measure({ ...style, text: rest.slice(0, mid) }) <= maxWidth) {
+          fit = mid;
+          low = mid + 1;
+        } else {
+          high = mid - 1;
+        }
+      }
+      let cut = fit;
+      const lastSpace = rest.lastIndexOf(" ", cut);
+      if (lastSpace > 0) cut = lastSpace;
+      const head = rest.slice(0, cut).trim();
+      const tail = rest.slice(cut).replace(/^\s+/, "");
+      if (!head) {
+        // 한 글자도 안 들어가는 극단 — 그래도 진도는 나가야 한다.
+        out.push(rest.slice(0, 1));
+        rest = rest.slice(1);
+        continue;
+      }
+      out.push(head);
+      rest = tail;
+      if (!rest) break;
+      if (guard >= MAX_WRAPPED_LINES - 1 && rest) out.push(rest);
+    }
+  }
+  return out;
+}
+
+function anchorOf(align: unknown): "start" | "middle" | "end" {
+  const value = String(align ?? "").trim().toLowerCase();
+  if (value === "right") return "end";
+  if (value === "center") return "middle";
+  return "start";
+}
+
+/** 정렬에 따른 앵커 x(요소 좌표계). */
+function anchorX(el: TextElementLike, anchor: "start" | "middle" | "end"): number {
+  const x = num(el.x);
+  const width = num(el.width);
+  if (anchor === "middle") return x + width / 2;
+  if (anchor === "end") return x + width;
+  return x;
+}
+
+/**
+ * 텍스트 요소들 → 상자 기준 줄 목록(위→아래).
+ *
+ * ``box``는 보통 이 요소들의 합집합 상자다. 서버는 이 좌표를 그대로 SVG에 찍고, 편집기는
+ * 같은 상자에 결과를 되꽂으므로 글자 크기와 자리가 원본과 일치한다.
+ */
+export function layoutTextLines(
+  els: TextElementLike[],
+  box: Box,
+  measure: Measure,
+): LaidOutLine[] {
+  const ordered = [...els].sort((a, b) => num(a.y) - num(b.y));
+  const out: LaidOutLine[] = [];
+  for (const el of ordered) {
+    const fontSize = Math.max(1, Math.round(num(el.fontSize, DEFAULT_FONT_SIZE)));
+    const fontWeight = toFontWeight(el.fontWeight);
+    const fontFamily = String(el.fontFamily ?? "");
+    const lineHeight = Math.max(
+      0.5,
+      num(el.lineHeight, DEFAULT_LINE_HEIGHT) || DEFAULT_LINE_HEIGHT,
+    );
+    const step = fontSize * lineHeight;
+    const anchor = anchorOf(el.align);
+    const lines = wrapText(String(el.text ?? ""), num(el.width), measure, {
+      fontSize,
+      fontWeight,
+      fontFamily,
+    });
+    if (lines.length === 0) continue;
+
+    // 세로 정렬: 요소 높이가 줄 높이 합보다 크면 top/middle/bottom에 따라 밀린다.
+    const block = step * lines.length;
+    const slack = Math.max(0, num(el.height) - block);
+    const vertical = String(el.verticalAlign ?? "top").trim().toLowerCase();
+    const offset =
+      vertical === "middle" ? slack / 2 : vertical === "bottom" ? slack : 0;
+
+    const x = anchorX(el, anchor) - box.x;
+    const top = num(el.y) + offset - box.y;
+    lines.forEach((line, index) => {
+      out.push({
+        text: line,
+        color: String(el.fill ?? "#26221e"),
+        fontSize,
+        fontWeight,
+        fontFamily,
+        x,
+        y: top + step * index + step / 2,
+        anchor,
+      });
+    });
+  }
+  return out;
+}
+
+/**
+ * 상자 밖으로 번지는 이펙트(글로우·물결·바운스)를 위한 여백.
+ *
+ * 가장 큰 글자를 기준으로 잡는다 — 진폭과 번짐이 글자 크기에 비례하기 때문이다.
+ * 편집기도 결과를 이만큼 키운 상자에 꽂으므로 글자 자리는 그대로 맞는다.
+ */
+export function gifBleed(lines: Array<{ fontSize: number }>): number {
+  const largest = lines.reduce((max, line) => Math.max(max, line.fontSize), 0);
+  return Math.round(Math.min(120, Math.max(12, largest * 0.45)));
+}
+
+/** 브라우저 canvas 기반 폭 측정기. canvas를 못 얻으면 null(호출부가 폴백). */
+export function createCanvasMeasure(): Measure | null {
+  if (typeof document === "undefined") return null;
+  const context = document.createElement("canvas").getContext("2d");
+  if (!context) return null;
+  return ({ text, fontSize, fontWeight, fontFamily }) => {
+    const family = fontFamily ? `"${fontFamily}", sans-serif` : "sans-serif";
+    context.font = `${fontWeight} ${fontSize}px ${family}`;
+    return context.measureText(text).width;
+  };
+}
+
+/**
+ * 측정기가 없을 때 쓰는 대략치(폰트 폭 ≈ 글자 크기의 0.62배, ASCII는 절반).
+ *
+ * 실측보다 나쁘지만 "아예 안 접힌다"보다는 낫다.
+ */
+export const estimateMeasure: Measure = ({ text, fontSize }) => {
+  let width = 0;
+  for (const char of String(text ?? "")) {
+    width += /[ -ÿ]/.test(char) ? fontSize * 0.52 : fontSize;
+  }
+  return width;
+};

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

@@ -0,0 +1,67 @@
+/**
+ * '텍스트를 GIF로' 요청 본문 만들기(camelCase 입력 → snake_case 페이로드).
+ *
+ * 운영 편집기(editor-client)와 데모 하니스(dev-canvas)가 같은 계약으로 호출해야 해서
+ * 한 곳에 둔다 — 한쪽에만 필드를 더하면 데모에서만 폰트가 안 실리는 식으로 갈린다.
+ */
+
+export type TextGifRequestInput = {
+  text: string;
+  effect: string;
+  color?: string;
+  accent?: string;
+  background?: string;
+  fontSize?: number;
+  fontWeight?: number;
+  fontFamily?: string;
+  lines?: Array<{
+    text: string;
+    color: string;
+    fontSize: number;
+    fontWeight: number;
+    fontFamily: string;
+    /** 원본 상자 기준 앵커 x(px). 주면 서버가 그 자리에 그대로 찍는다. */
+    x?: number;
+    /** 원본 상자 기준 줄의 세로 중심 y(px). */
+    y?: number;
+    /** 가로 정렬 기준(편집기 left/center/right → start/middle/end). */
+    anchor?: "start" | "middle" | "end";
+  }>;
+  fonts?: Array<{ family: string; url: string; weight: number }>;
+  /** 원본 텍스트 상자 크기(px). 주면 서버가 캔버스를 추정하지 않는다. */
+  boxWidth?: number;
+  boxHeight?: number;
+  /** 상자 밖으로 번지는 이펙트를 위한 사방 여백(px). */
+  bleed?: number;
+  brandId?: string;
+};
+
+export function buildTextGifPayload(input: TextGifRequestInput) {
+  return {
+    text: input.text,
+    effect: input.effect,
+    color: input.color,
+    accent: input.accent,
+    background: input.background,
+    font_size: input.fontSize,
+    font_weight: input.fontWeight,
+    font_family: input.fontFamily,
+    // 한 줄짜리도 lines 로 보낸다 — 요소 안의 줄바꿈이 이미 여기서 줄로 쪼개져 있고,
+    // 서버는 lines 가 있으면 그걸 쌓는다.
+    lines: (input.lines ?? []).map((line) => ({
+      text: line.text,
+      color: line.color,
+      font_size: line.fontSize,
+      font_weight: line.fontWeight,
+      font_family: line.fontFamily,
+      x: line.x,
+      y: line.y,
+      anchor: line.anchor,
+    })),
+    fonts: input.fonts ?? [],
+    box_width: input.boxWidth,
+    box_height: input.boxHeight,
+    bleed: input.bleed,
+    brand_id: input.brandId,
+  };
+}

package/lib/detail-page/text-presets.ts

@@ -0,0 +1,230 @@
+/**
+ * 텍스트 프리셋 — 여러 줄이 한 덩어리로 들어가는 글 묶음.
+ *
+ * 스톡 `TextSection`도 크기 버튼 아래에 이런 묶음 격자를 달고 있었지만, 그건 벤더
+ * 서버에서 받아 오는 영문 포스터 디자인이라 우리 상세페이지에서 쓸 자리가 없었다.
+ * 여기 있는 건 우리 템플릿이 실제로 반복하는 짜임이다 — 제목+설명, 눈썹라벨+제목,
+ * 번호 매긴 단계, 인용, 각주 달린 문장.
+ *
+ * 좌표는 폭 `REFERENCE_WIDTH` 기준으로 적어 두고, 넣을 때 페이지 폭에 맞춰 한 번에
+ * 줄인다. 그래서 750짜리 섹션이든 860짜리든 같은 비율로 앉는다.
+ *
+ * 넣는 글자는 문서 기본 서체로만 들어간다. 서체·색은 넣은 뒤 우측 인스펙터에서 고른다.
+ */
+
+import type { ElementLike, StoreLike } from "./spec-group/sync";
+
+/** 프리셋 좌표계의 폭. 실제 삽입 폭은 페이지 폭의 80%다. */
+export const REFERENCE_WIDTH = 1000;
+const PAGE_RATIO = 0.8;
+
+export type TextPresetNode = {
+  /** 문구 i18n 키의 꼬리(`detailPage.textPresets.<preset>.<key>`). */
+  key: string;
+  y: number;
+  fontSize: number;
+  fontWeight: number;
+  align: "left" | "center";
+  /** 안 주면 `fontSize * 1.35`. 여러 줄로 접힐 수 있는 칸만 따로 준다. */
+  height?: number;
+  lineHeight?: number;
+  letterSpacing?: number;
+  fill?: string;
+  /** 좌우 여백(기준 폭 안에서). 안 주면 0. */
+  x?: number;
+  width?: number;
+};
+
+export type TextPreset = {
+  key: string;
+  /** 묶음 전체 높이(기준 폭 기준). 미리보기 비율에도 쓴다. */
+  height: number;
+  nodes: TextPresetNode[];
+};
+
+const INK = "#111111";
+const MUTED = "#6b6b6b";
+
+export const TEXT_PRESETS: TextPreset[] = [
+  {
+    key: "headingBody",
+    height: 190,
+    nodes: [
+      { key: "heading", y: 0, fontSize: 62, fontWeight: 700, align: "center" },
+      {
+        key: "body",
+        y: 100,
+        fontSize: 26,
+        fontWeight: 400,
+        align: "center",
+        height: 80,
+        lineHeight: 1.6,
+        fill: MUTED,
+      },
+    ],
+  },
+  {
+    key: "eyebrowHeading",
+    height: 160,
+    nodes: [
+      {
+        key: "eyebrow",
+        y: 0,
+        fontSize: 22,
+        fontWeight: 600,
+        align: "center",
+        letterSpacing: 4,
+        fill: MUTED,
+      },
+      { key: "heading", y: 48, fontSize: 58, fontWeight: 700, align: "center" },
+    ],
+  },
+  {
+    key: "numberedStep",
+    height: 210,
+    nodes: [
+      { key: "number", y: 0, fontSize: 40, fontWeight: 700, align: "left", fill: MUTED },
+      { key: "heading", y: 56, fontSize: 40, fontWeight: 600, align: "left" },
+      {
+        key: "body",
+        y: 118,
+        fontSize: 24,
+        fontWeight: 400,
+        align: "left",
+        height: 84,
+        lineHeight: 1.6,
+        fill: MUTED,
+      },
+    ],
+  },
+  {
+    key: "quote",
+    height: 220,
+    nodes: [
+      {
+        key: "quote",
+        y: 0,
+        fontSize: 36,
+        fontWeight: 500,
+        align: "center",
+        height: 130,
+        lineHeight: 1.5,
+      },
+      {
+        key: "source",
+        y: 158,
+        fontSize: 22,
+        fontWeight: 400,
+        align: "center",
+        fill: MUTED,
+      },
+    ],
+  },
+  {
+    key: "claimFootnote",
+    height: 190,
+    nodes: [
+      {
+        key: "claim",
+        y: 0,
+        fontSize: 46,
+        fontWeight: 700,
+        align: "center",
+        height: 120,
+        lineHeight: 1.4,
+      },
+      {
+        key: "footnote",
+        y: 146,
+        fontSize: 18,
+        fontWeight: 400,
+        align: "center",
+        fill: MUTED,
+      },
+    ],
+  },
+];
+
+function num(value: unknown, fallback = 0): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+/** 하나의 undo 단계로 묶는다. history가 없으면(테스트 페이크) 그냥 실행한다. */
+function inTransaction<T>(store: StoreLike, run: () => T): T {
+  const history = store.history;
+  history?.startTransaction?.();
+  try {
+    return run();
+  } finally {
+    history?.endTransaction?.();
+  }
+}
+
+export type InsertTextPresetOptions = {
+  /** 문구 해석기 — 패널이 자기 `t`를 넘긴다. */
+  text: (nodeKey: string) => string;
+  /** 문서에서 물려받을 서체. 안 주면 Pretendard. */
+  fontFamily?: string;
+  /** 레이어 트리에 뜰 이름. 안 주면 프리셋 키. */
+  name?: string;
+};
+
+/**
+ * 프리셋을 그룹 하나로 놓는다.
+ *
+ * 자식 좌표는 **페이지 절대 좌표**로 적는다 — 그룹에 base x/y를 남기면 자식이 두 번
+ * 밀린다(예전에 카드 밖으로 글자가 튀어나온 원인이 이거였다).
+ */
+export function insertTextPreset(
+  store: StoreLike,
+  preset: TextPreset,
+  { text, fontFamily = "Pretendard", name }: InsertTextPresetOptions,
+): ElementLike | null {
+  const page = store.activePage ?? store.pages[0];
+  if (!page || !store.groupElements) return null;
+
+  const pageWidth = num(page.computedWidth, 750);
+  const pageHeight = num(page.computedHeight, 1000);
+  const width = Math.round(pageWidth * PAGE_RATIO);
+  const scale = width / REFERENCE_WIDTH;
+  const height = Math.round(preset.height * scale);
+  const originX = Math.round((pageWidth - width) / 2);
+  const originY = Math.round((pageHeight - height) / 2);
+
+  return inTransaction(store, () => {
+    const ids: string[] = [];
+    for (const node of preset.nodes) {
+      const fontSize = Math.round(node.fontSize * scale);
+      const added = page.addElement(
+        {
+          type: "text",
+          text: text(node.key),
+          fontFamily,
+          fontSize,
+          fontWeight: node.fontWeight,
+          fill: node.fill ?? INK,
+          align: node.align,
+          ...(node.lineHeight ? { lineHeight: node.lineHeight } : {}),
+          ...(node.letterSpacing
+            ? { letterSpacing: node.letterSpacing * scale }
+            : {}),
+          x: originX + Math.round(num(node.x) * scale),
+          y: originY + Math.round(node.y * scale),
+          width: Math.round((node.width ?? REFERENCE_WIDTH) * scale),
+          // 상자 높이를 안 주면 넣자마자 글자가 잘린다.
+          height: Math.round((node.height ?? node.fontSize * 1.35) * scale),
+        },
+        // 부품마다 선택이 옮겨 다니면 그사이 우측 인스펙터가 깜빡인다. 최종 선택은
+        // groupElements가 그룹으로 잡아 준다.
+        { skipSelect: true },
+      ) as ElementLike | undefined;
+      const id = added?.id;
+      if (typeof id === "string") ids.push(id);
+    }
+    if (ids.length === 0) return null;
+    const group = store.groupElements?.(ids, {
+      name: name ?? preset.key,
+    }) as ElementLike | undefined;
+    return group ?? null;
+  });
+}

package/lib/detail-page/use-fake-progress.ts

@@ -0,0 +1,67 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+
+/**
+ * 긴 AI 생성(이미지·GIF·카피)이 진행되는 동안 "체감상" 진행률을 보여주는 가짜
+ * 프로그레스 훅.
+ *
+ * 백엔드는 실제 진행률을 스트리밍하지 않으므로(폴링만), 대략적인 예상 소요시간을
+ * 근거로 감속 곡선을 그려 준다. 핵심 규칙:
+ *  - 초반엔 빠르게 차오르고 끝으로 갈수록 느려진다(지수 감쇠) — "멈춘 것 같은"
+ *    구간을 최소화하고, 예상보다 오래 걸려도 계속 야금야금 전진해 신뢰를 준다.
+ *  - 완료 전에는 절대 100%에 닿지 않는다(상한 `cap`). 100%에서 오래 머무는 건
+ *    가짜 티가 가장 많이 나는 안티패턴이라 피한다.
+ *  - 완료(`active`가 true→false)되는 순간에만 1(100%)로 스냅한 뒤, 짧은 여운 후
+ *    0으로 리셋한다.
+ *
+ * 반환값은 0~1. `estimateMs`는 그 작업의 대략적 소요시간(초과해도 안전).
+ */
+export function useFakeProgress(
+  active: boolean,
+  estimateMs: number,
+  opts?: { cap?: number; tickMs?: number },
+): number {
+  const cap = opts?.cap ?? 0.95;
+  const tickMs = opts?.tickMs ?? 120;
+  const [progress, setProgress] = useState(0);
+  const startRef = useRef<number | null>(null);
+
+  useEffect(() => {
+    if (!active) return;
+    // 새 실행 시작: 타임스탬프 고정 후 0부터.
+    startRef.current = Date.now();
+    setProgress(0);
+    const id = window.setInterval(() => {
+      const start = startRef.current;
+      if (start == null) return;
+      const elapsed = Date.now() - start;
+      // r=경과/예상. displayed = cap*(1-e^{-2.2r}) → r=1에서 ~0.85cap, 이후 cap로 수렴.
+      const r = elapsed / Math.max(1, estimateMs);
+      const next = cap * (1 - Math.exp(-2.2 * r));
+      setProgress((prev) => (next > prev ? next : prev));
+    }, tickMs);
+    return () => window.clearInterval(id);
+  }, [active, estimateMs, cap, tickMs]);
+
+  useEffect(() => {
+    if (active) return;
+    // 완료: 100%로 잠깐 채우고 여운 후 리셋(다음 실행 대비).
+    startRef.current = null;
+    setProgress((prev) => (prev > 0 ? 1 : 0));
+    const id = window.setTimeout(() => setProgress(0), 500);
+    return () => window.clearTimeout(id);
+  }, [active]);
+
+  return progress;
+}
+
+/** 상세페이지 생성 종류별 대략 예상 소요시간(ms). 실측 기반의 여유 있는 값. */
+export const GENERATION_ESTIMATE_MS = {
+  /** gpt-image 계열 이미지 1장(티어 무관 여유값). */
+  image: 35_000,
+  /** wan i2v GIF: 예측 22s + 다운로드·인코딩·폴링 오버헤드(콜드 포함). */
+  gif: 75_000,
+  /** 카피/텍스트·프롬프트 편집(LLM 1회 왕복). */
+  text: 15_000,
+} as const;

package/lib/detail-page/z-order.ts

@@ -0,0 +1,82 @@
+/**
+ * 정렬 순서(z-order) 한 벌. 우측 패널과 캔버스 우클릭 메뉴가 같은 규칙을 쓴다.
+ *
+ * **``element.moveUp()`` 을 쓰면 안 된다.** 스톡 편집기의 그 액션은 `e.page`를 기준으로
+ * 삼아서, 그룹 **안** 요소에 대고 부르면 조용히 아무 일도 안 한다(no-op). 우리 문서는
+ * 대부분이 그룹이라 그 경로는 실질적으로 죽은 경로다. 직접 부모(그룹 또는 페이지)가
+ * 공통으로 노출하는 ``setElementZIndex(id, index)``만 쓴다. index가 클수록 앞이다.
+ */
+
+export type ZOrderParent = {
+  children?: ReadonlyArray<{ id: string }>;
+  setElementZIndex?: (id: string, index: number) => void;
+};
+
+export type ZOrderElement = {
+  id: string;
+  zIndex?: number;
+  parent?: ZOrderParent | null;
+};
+
+export type ZOrder = {
+  /** 형제 중 몇 번째인가(0 = 맨 뒤). */
+  z: number;
+  /** 형제 수. */
+  count: number;
+  atFront: boolean;
+  atBack: boolean;
+};
+
+/** 순서를 만질 수 있는 요소인가 — 아니면 null(컨트롤을 아예 안 그린다). */
+export function zOrderOf(el: ZOrderElement | undefined | null): ZOrder | null {
+  const parent = el?.parent;
+  if (!el || !parent?.setElementZIndex) return null;
+  const siblings = parent.children ?? [];
+  const count = siblings.length;
+  // zIndex 게터가 있으면 그걸 믿는다(mobx 관찰 대상). 없으면 형제 배열에서 찾는다.
+  const z =
+    typeof el.zIndex === "number"
+      ? el.zIndex
+      : siblings.findIndex((c) => c.id === el.id);
+  if (count <= 1 || z < 0) return null;
+  return { z, count, atFront: z >= count - 1, atBack: z <= 0 };
+}
+
+export type ZMove = "front" | "forward" | "backward" | "back";
+
+/** 목표 index. 범위 밖 요청은 끝으로 눌러 담는다. */
+export function zTarget(order: ZOrder, move: ZMove): number {
+  const raw =
+    move === "front"
+      ? order.count - 1
+      : move === "back"
+        ? 0
+        : move === "forward"
+          ? order.z + 1
+          : order.z - 1;
+  return Math.max(0, Math.min(order.count - 1, raw));
+}
+
+/** 그 방향으로 더 갈 데가 있는가 — 버튼/메뉴 항목 비활성 판정. */
+export function canMoveZ(order: ZOrder | null, move: ZMove): boolean {
+  if (!order) return false;
+  return move === "front" || move === "forward" ? !order.atFront : !order.atBack;
+}
+
+/** 실제로 옮긴다. 움직일 데가 없으면 false(호출부가 아무 것도 안 해도 되게). */
+export function moveZ(el: ZOrderElement, move: ZMove): boolean {
+  const order = zOrderOf(el);
+  if (!canMoveZ(order, move)) return false;
+  el.parent?.setElementZIndex?.(el.id, zTarget(order!, move));
+  return true;
+}
+
+/** 임의의 자리로. 우측 패널의 "n/총" 표시와 짝. */
+export function setZ(el: ZOrderElement, index: number): void {
+  const order = zOrderOf(el);
+  if (!order) return;
+  el.parent?.setElementZIndex?.(
+    el.id,
+    Math.max(0, Math.min(order.count - 1, index)),
+  );
+}