kasaframe 0.0.0-stage → 0.1.1

package/packages/motion/src/captions.ts

@@ -0,0 +1,479 @@
+import type { KfStyle, SafeArea } from "@kasaframe/core";
+
+// 자막 — 들릴 말(captions.json)을 장면 시각에 나눠 화면 아래 판에 얹는다.
+// srt·vtt(plan 의 writeCaptions)와 같은 toCues 를 써서 트랙과 화면 자막이 한 마디도 어긋나지 않는다.
+// 이 파일은 Node(트랙 쓰기)와 페이지 양쪽에서 불리므로 DOM 은 mountCaptions 안에서만 만진다.
+
+/** kf.json captions — off: 화면엔 없이 srt·vtt 만 · on: 화면에 얹고 srt·vtt 도 · none: 아무것도 */
+export type CaptionMode = "on" | "off" | "none";
+
+/** 옛 이름(track·burned)도 받는다. fit 은 on 과 같고 장면을 띠 위로 줄여 올리는 방식만 다르다(captionsPlan) */
+export function captionMode(v: unknown): CaptionMode {
+  if (v === "on" || v === "fit" || v === "burned" || v === true) return "on";
+  if (v === "off" || v === "track") return "off";
+  return "none";
+}
+
+/** 낱말 하나와 그 시각(영상 전체 기준 초). lyrics.json 꼴({ w, start, end })도 받는다 */
+export interface CaptionWord {
+  text?: string;
+  from?: number;
+  to?: number;
+  w?: string;
+  start?: number;
+  end?: number;
+}
+
+export interface CaptionLine {
+  scene?: string;
+  from?: number;
+  to?: number;
+  text: string;
+  /** 낱말마다 잰 시각이 있으면 마디를 그 시각 그대로 끊는다 */
+  words?: CaptionWord[];
+}
+
+export interface Cue {
+  from: number;
+  to: number;
+  text: string;
+}
+
+interface Span {
+  id: string;
+  from: number;
+  dur: number;
+}
+
+// 화면 자막 판이 놓일 자리와 크기. 페이지에서 재기 전에(Node 의 srt 쓰기에서도) 같은 값을 내야 해서 글꼴 없이 화면 크기만으로 정한다
+export interface CaptionMetrics {
+  fontPx: number;
+  lineHeight: number;
+  padX: number;
+  padY: number;
+  /** 판 안 글 한 줄의 최대 폭(px) */
+  textMaxPx: number;
+  /** 한 줄에 들어가는 폭을 글자 크기 단위(em)로 */
+  maxEm: number;
+  /** 판 아래 끝의 y(px) — 안전 영역 아래 가장자리에서 gap 만큼 띄운다 */
+  bottom: number;
+  /** 판 가운데의 x(px) — 안전 영역 가운데 */
+  centerX: number;
+  /** 자막 띠 위아래 여백(px) */
+  gap: number;
+}
+
+/** 판 높이(px) — 줄 수만큼 */
+export function plateHeight(m: CaptionMetrics, lines: number): number {
+  return Math.round(m.fontPx * m.lineHeight * lines + m.padY * 2);
+}
+
+/** 자막 띠 — 안전 영역 아래쪽에서 장면이 비워 줄 높이(px). 판 + 위아래 여백 */
+export function captionBand(m: CaptionMetrics, lines = 2): number {
+  return plateHeight(m, lines) + m.gap * 2;
+}
+
+export function captionMetrics(o: { width: number; height: number; safe?: SafeArea | null; minPx?: number }): CaptionMetrics {
+  const safe = o.safe ?? { top: 0, bottom: 0, left: 0, right: 0 };
+  const short = Math.min(o.width, o.height);
+  const vertical = o.height > o.width;
+  // 세로 쇼츠는 폰 한 손 거리에서 읽혀야 한다 — 폭의 8%(1080 폭이면 86px). 가로는 높이의 5%
+  const fontPx = Math.max(o.minPx ?? 0, Math.round(vertical ? o.width * 0.08 : short * 0.05));
+  const padX = Math.round(fontPx * 0.5);
+  const padY = Math.round(fontPx * 0.2);
+  const gap = Math.round(short * 0.02);
+  const room = o.width - safe.left - safe.right - Math.round(short * 0.04);
+  // 가로 화면은 한 줄이 너무 길면 눈이 따라가지 못한다 — 화면 폭 2/3 까지
+  const plateMax = vertical ? room : Math.min(room, Math.round(o.width * 0.66));
+  const textMaxPx = plateMax - padX * 2;
+  return {
+    fontPx,
+    lineHeight: 1.28,
+    padX,
+    padY,
+    textMaxPx,
+    maxEm: textMaxPx / fontPx,
+    bottom: o.height - safe.bottom - gap,
+    centerX: safe.left + (o.width - safe.left - safe.right) / 2,
+    gap,
+  };
+}
+
+// 글꼴 없이 어림하는 폭(em). 한글·한자는 정사각에 가깝고 라틴은 좁다. 어림이 실제보다 넓게 나와야 페이지에서 잰 줄바꿈이 두 줄을 넘지 않는다
+export function emWidth(s: string): number {
+  let w = 0;
+  for (const ch of s) {
+    const c = ch.codePointAt(0)!;
+    if (ch === " ") w += 0.3;
+    else if ((c >= 0x1100 && c <= 0x11ff) || (c >= 0x3000 && c <= 0x9fff) || (c >= 0xac00 && c <= 0xd7af) || (c >= 0xff00 && c <= 0xffef)) w += 1;
+    else if (/[0-9]/.test(ch)) w += 0.62;
+    else if (/[A-Z]/.test(ch)) w += 0.72;
+    else if (/[a-z]/.test(ch)) w += 0.58;
+    else if (/[.,:;'"!?·]/.test(ch)) w += 0.34;
+    else w += 0.62;
+  }
+  return w;
+}
+
+// 한글로 끝나는데 조사·어미가 아닌 어절(「잠재」「512차원」) — 그 뒤에서 끊으면 말이 갈린다
+const ENDINGS = new Set([..."은는이가을를에서로와과도만의께랑엔고며면니데해게지요다까죠라여야듯록나서"]);
+function looseEnd(word: string): boolean {
+  const w = word.replace(/[^\p{L}\p{N}]+$/u, "");
+  const last = [...w].pop() ?? "";
+  // 「3만 2768」「57분의 1」 — 수를 세는 말 뒤는 조사처럼 보여도 수가 이어진다
+  if (/\d[만천억조]$|\d분의$/.test(w)) return true;
+  return /[가-힣]/.test(last) && !ENDINGS.has(last);
+}
+
+/**
+ * 어절(띄어쓰기) 단위로 두 줄까지 나눈다. 한 줄에 들면 한 줄, 아니면 두 줄 폭이 가장 고른 자리에서 끊는다.
+ * 두 줄로도 안 들면 null — 마디를 더 잘게 나눠야 한다. measure 는 글 폭(px 든 em 이든 maxWidth 와 같은 단위).
+ */
+export function wrapCaption(text: string, maxWidth: number, measure: (s: string) => number = emWidth, maxLines = 2): string[] | null {
+  const t = text.trim().replace(/\s+/g, " ");
+  if (measure(t) <= maxWidth) return [t];
+  const words = t.split(" ");
+  if (maxLines < 2 || words.length < 2) return null;
+  let best: string[] | null = null;
+  let bestW = Infinity;
+  for (let i = 1; i < words.length; i++) {
+    const a = words.slice(0, i).join(" ");
+    const b = words.slice(i).join(" ");
+    const wa = measure(a);
+    const wb = measure(b);
+    if (wa > maxWidth) break;
+    if (wb > maxWidth) continue;
+    // 위 줄이 조금 짧은 쪽(역삼각형)을 같은 폭보다 살짝 낫게 본다 — 한국 방송 자막 관례.
+    // 조사·어미로 끝난 어절 뒤에서 끊는다 — 「잠재 / 공간」처럼 한 덩어리 말을 가르면 폭이 고르더라도 읽다가 걸린다
+    const score = Math.max(wa, wb) + (wa > wb ? 0.01 * maxWidth : 0) + (looseEnd(words[i - 1]) ? 0.12 * maxWidth : 0);
+    if (score < bestW) {
+      bestW = score;
+      best = [a, b];
+    }
+  }
+  return best;
+}
+
+// 쉼표·마침표 뒤에서 끊는다. 숫자 사이 쉼표·점(1,000 · 3.5)은 끊지 않는다. 쉼표 뒤 띄어쓰기가 없어도 끊는다
+export function splitPhrases(text: string): string[] {
+  const out: string[] = [];
+  let cur = "";
+  const chars = [...text];
+  for (let i = 0; i < chars.length; i++) {
+    const ch = chars[i];
+    cur += ch;
+    if (!/[,.?!。、]/.test(ch)) continue;
+    if ((ch === "," || ch === ".") && /\d/.test(chars[i - 1] ?? "") && /\d/.test(chars[i + 1] ?? "")) continue;
+    if (/[.?!。]/.test(chars[i + 1] ?? "")) continue;
+    out.push(cur);
+    cur = "";
+  }
+  if (cur.trim()) out.push(cur);
+  return out.map((p) => p.trim().replace(/[,、]$/, "").replace(/(?<!\.)\.$/, "").trim()).filter(Boolean);
+}
+
+// 두 줄에 안 드는 마디는 어절 경계에서 몇 토막으로 나눈다 — 토막 길이는 고르게, 끝은 조사·어미 뒤에서(「흡수해 잠재 / 공간에서」처럼 덩어리를 가르지 않게)
+function chunk(text: string, maxEm: number): string[] {
+  if (wrapCaption(text, maxEm)) return [text];
+  const words = text.split(/\s+/).filter(Boolean);
+  const n = words.length;
+  const part = (i: number, j: number) => words.slice(i, j).join(" ");
+  for (let k = 2; k <= n; k++) {
+    const ideal = emWidth(text) / k;
+    // best[j][c] = 앞 j 어절을 c 토막으로 나눈 가장 싼 값
+    const best = Array.from({ length: n + 1 }, () => new Array<number>(k + 1).fill(Infinity));
+    const from = Array.from({ length: n + 1 }, () => new Array<number>(k + 1).fill(-1));
+    best[0][0] = 0;
+    for (let c = 1; c <= k; c++)
+      for (let j = 1; j <= n; j++)
+        for (let i = c - 1; i < j; i++) {
+          if (!Number.isFinite(best[i][c - 1])) continue;
+          const p = part(i, j);
+          if (!wrapCaption(p, maxEm)) continue;
+          const cost = best[i][c - 1] + Math.abs(emWidth(p) - ideal) / ideal + (j < n && looseEnd(words[j - 1]) ? 0.6 : 0);
+          if (cost < best[j][c]) {
+            best[j][c] = cost;
+            from[j][c] = i;
+          }
+        }
+    if (!Number.isFinite(best[n][k])) continue;
+    const parts: string[] = [];
+    for (let j = n, c = k; c > 0; c--) {
+      const i = from[j][c];
+      parts.unshift(part(i, j));
+      j = i;
+    }
+    return parts;
+  }
+  return words;
+}
+
+// 한 줄 반에 못 미치는 짧은 마디(「MLA,」)는 다음 마디에 붙인다 — 0.5초짜리 자막은 읽기 전에 사라진다
+function merge(parts: string[], maxEm: number): string[] {
+  const out: string[] = [];
+  for (const p of parts) {
+    const prev = out[out.length - 1];
+    if (prev !== undefined && emWidth(prev) < 4 && wrapCaption(`${prev}, ${p}`, maxEm)) out[out.length - 1] = `${prev}, ${p}`;
+    else out.push(p);
+  }
+  return out;
+}
+
+// 소리 길이는 띄어쓰기 뺀 글자 수에 가깝다
+const spoken = (s: string) => Math.max(1, s.replace(/\s/g, "").length);
+
+function spread(texts: string[], from: number, to: number, cues: Cue[]): void {
+  const total = texts.reduce((a, p) => a + spoken(p), 0);
+  let t = from;
+  for (const p of texts) {
+    const d = ((to - from) * spoken(p)) / total;
+    cues.push({ from: t, to: t + d, text: p });
+    t += d;
+  }
+}
+
+function fromWords(raw: CaptionWord[], maxEm: number, cues: Cue[]): number {
+  const before = cues.length;
+  const words = raw
+    .map((w) => ({ text: (w.text ?? w.w ?? "").trim(), from: w.from ?? w.start ?? NaN, to: w.to ?? w.end ?? NaN }))
+    .filter((w) => w.text && Number.isFinite(w.from) && Number.isFinite(w.to));
+  let cur: typeof words = [];
+  const flush = () => {
+    if (!cur.length) return;
+    cues.push({ from: cur[0].from, to: cur[cur.length - 1].to, text: splitPhrases(cur.map((w) => w.text).join(" ")).join(", ") });
+    cur = [];
+  };
+  for (const w of words) {
+    if (cur.length && !wrapCaption([...cur, w].map((x) => x.text).join(" "), maxEm)) flush();
+    cur.push(w);
+    if (/[.?!。]$/.test(w.text)) flush();
+  }
+  flush();
+  return cues.length - before;
+}
+
+/**
+ * captions.json 줄 → 시각 붙은 자막 마디. 장면에만 묶인 줄은 쉼표·마침표 마디로 나눠 글자 수 비율로 장면 시간에 펴고,
+ * from·to 가 있으면 그 안에, words 가 있으면 낱말 시각 그대로. maxEm(captionMetrics) 을 주면 마디마다 두 줄 안에 들게 더 나눈다.
+ */
+export function toCues(lines: CaptionLine[], scenes: Span[], o: { maxEm?: number; duration?: number } = {}): Cue[] {
+  const maxEm = o.maxEm ?? Infinity;
+  const cues: Cue[] = [];
+  for (const l of lines) {
+    const text = (l.text ?? "").trim();
+    if (l.words?.length && fromWords(l.words, maxEm, cues) > 0) continue;
+    if (!text) continue;
+    let from: number;
+    let to: number;
+    if (l.from !== undefined && l.to !== undefined) {
+      from = l.from;
+      to = l.to;
+    } else {
+      const s = scenes.find((x) => x.id === l.scene);
+      if (!s) continue;
+      const pad = Math.min(0.25, s.dur * 0.05);
+      from = s.from + pad;
+      to = s.from + s.dur - pad;
+    }
+    const parts = merge(splitPhrases(text).flatMap((p) => chunk(p, maxEm)), maxEm);
+    spread(parts, from, to, cues);
+  }
+  cues.sort((a, b) => a.from - b.from);
+  for (let i = 0; i < cues.length; i++) {
+    const c = cues[i];
+    const next = cues[i + 1];
+    // 말 사이 짧은 숨에 자막이 깜빡이지 않게 다음 자막까지 붙여 남긴다 — 틈이 한 프레임이라도 있으면 판이 꺼졌다 켜진다
+    if (next && next.from - c.to < 0.6) c.to = next.from;
+    // 한두 프레임짜리 자막은 읽히지도 않고 검사에 깜빡임(frame.spike)으로 잡힌다
+    if (c.to - c.from < 0.3) c.to = next ? Math.min(next.from, c.from + 0.3) : c.from + 0.3;
+    if (o.duration !== undefined) c.to = Math.min(c.to, o.duration);
+  }
+  return cues.filter((c) => c.to > c.from);
+}
+
+export interface CaptionLayerOptions {
+  cues: Cue[];
+  width: number;
+  height: number;
+  safe?: SafeArea | null;
+  style?: KfStyle | null;
+  minPx?: number;
+}
+
+interface Laid {
+  cue: Cue;
+  lines: string[];
+  fontPx: number;
+}
+
+const FADE = 0.12;
+
+// 판 색은 테마의 어두운 쪽, 글은 밝은 쪽 — 어느 장면 위에서도 대비 3:1 을 넘게 판을 거의 불투명하게
+function palette(style: KfStyle | null | undefined): { plate: string; ink: string; edge: string } {
+  const c = style?.colors;
+  if (!c) return { plate: "rgba(8, 10, 14, 0.86)", ink: "#ffffff", edge: "transparent" };
+  const [dark, light] = style!.scheme === "light" ? [c.ink, c.bg] : [c.bg, c.ink];
+  return { plate: `color-mix(in srgb, ${dark} 86%, transparent)`, ink: light, edge: c.accent };
+}
+
+/**
+ * 화면 자막 판을 짓고 t 마다 칠하는 함수(같은 t 면 같은 화면)와 판이 차지할 띠 높이를 돌려준다. 글꼴이 다 받아진 뒤에 불러야 줄바꿈 폭이 맞는다.
+ * 판은 안전 영역 아래쪽 가운데, 한 마디는 두 줄까지 — 넘치면 글자를 줄인다.
+ */
+export async function captionLayer(host: HTMLElement, o: CaptionLayerOptions): Promise<{ draw: (t: number) => void; band: number }> {
+  const m = captionMetrics(o);
+  const fam = o.style?.fonts?.sans ?? '"Pretendard Variable", Pretendard, "Noto Sans KR", "Apple SD Gothic Neo", sans-serif';
+  const weight = 700;
+  const font = (px: number) => `${weight} ${px}px ${fam}`;
+  // unicode-range 로 쪼갠 글꼴이면 처음 나오는 글자 조각을 그 프레임에 받느라 투명하게 찍힌다 — 쓸 글자를 미리 다 받는다
+  const all = [...new Set(o.cues.map((c) => c.text).join(""))].join("");
+  if (all) await document.fonts.load(font(m.fontPx), all).catch(() => {});
+  const ctx2d = document.createElement("canvas").getContext("2d")!;
+  const measure = (px: number) => (s: string) => {
+    ctx2d.font = font(px);
+    return ctx2d.measureText(s).width;
+  };
+  const laid: Laid[] = o.cues.map((cue) => {
+    for (let px = m.fontPx; px >= Math.round(m.fontPx * 0.8); px--) {
+      const lines = wrapCaption(cue.text, m.textMaxPx, measure(px));
+      if (lines) return { cue, lines, fontPx: px };
+    }
+    const px = Math.round(m.fontPx * 0.8);
+    return { cue, lines: wrapCaption(cue.text, m.textMaxPx, measure(px), 3) ?? [cue.text], fontPx: px };
+  });
+
+  const { plate: plateBg, ink, edge } = palette(o.style);
+  const layer = document.createElement("div");
+  layer.dataset.kfCaptions = "on";
+  layer.style.cssText = "position:absolute;inset:0;pointer-events:none;z-index:50;";
+  const plate = document.createElement("div");
+  const radius = Math.min(o.style?.radius?.md ?? 10, Math.round(m.fontPx * 0.35));
+  plate.style.cssText = [
+    "position:absolute",
+    `left:${m.centerX}px`,
+    `bottom:${o.height - m.bottom}px`,
+    "transform:translateX(-50%)",
+    `max-width:${m.textMaxPx + m.padX * 2}px`,
+    "box-sizing:border-box",
+    `padding:${m.padY}px ${m.padX}px`,
+    `background:${plateBg}`,
+    `color:${ink}`,
+    `border-radius:${radius}px`,
+    `box-shadow:inset 0 -${Math.max(2, Math.round(m.fontPx * 0.06))}px 0 ${edge}`,
+    `font-family:${fam}`,
+    `font-weight:${weight}`,
+    `line-height:${m.lineHeight}`,
+    "letter-spacing:-0.01em",
+    "text-align:center",
+    "white-space:nowrap",
+    "word-break:keep-all",
+  ].join(";");
+  plate.hidden = true;
+  layer.append(plate);
+  host.append(layer);
+
+  let shown = -1;
+  const band = captionBand(m, Math.max(1, ...laid.map((l) => l.lines.length)));
+  const draw = (t: number) => {
+    let i = -1;
+    for (let k = 0; k < laid.length; k++) {
+      if (laid[k].cue.from > t) break;
+      if (t < laid[k].cue.to) i = k;
+    }
+    if (i < 0) {
+      plate.hidden = true;
+      shown = -1;
+      return;
+    }
+    const { cue, lines, fontPx } = laid[i];
+    if (i !== shown) {
+      shown = i;
+      plate.style.fontSize = `${fontPx}px`;
+      plate.replaceChildren(
+        ...lines.map((l) => {
+          const s = document.createElement("div");
+          s.textContent = l;
+          return s;
+        }),
+      );
+    }
+    plate.hidden = false;
+    // 바로 이어지는 마디끼리는 글만 바꾼다. 앞뒤가 빈 자리에서만 서서히 켜고 끈다
+    const joinedIn = i > 0 && laid[i - 1].cue.to >= cue.from - 1e-6;
+    const joinedOut = i < laid.length - 1 && laid[i + 1].cue.from <= cue.to + 1e-6;
+    const a = Math.min(joinedIn ? 1 : (t - cue.from) / FADE, joinedOut ? 1 : (cue.to - t) / FADE, 1);
+    plate.style.opacity = String(Math.max(0, a));
+  };
+  return { draw, band };
+}
+
+/**
+ * 자막 띠 자리를 비운다 — 장면을 하나도 고치지 않고, 안전 영역(위 끝 ~ 아래 끝)에 있던 내용을 (위 끝 ~ 띠 위)로 한 배율로 줄여 올린다.
+ * 장면이 ctx.safe 를 쓰든 절대 좌표로 놓든, React·캔버스든 똑같이 올라간다. 줄어 남는 가장자리는 테마 바탕색.
+ */
+export function liftScenes(stage: HTMLElement, o: { width: number; height: number; safe?: SafeArea | null; band: number }): number {
+  const safe = o.safe ?? { top: 0, bottom: 0, left: 0, right: 0 };
+  const top = safe.top;
+  const room = o.height - safe.bottom - top;
+  const k = Math.max(0.5, (room - o.band) / room);
+  stage.style.background = "var(--kf-bg, #000)";
+  // 줄어든 장면의 가장자리(모눈·바탕 무늬)가 칼로 자른 듯 끊기지 않게 바탕색으로 녹인다 — 녹는 폭은 안전 영역 밖이라 글은 안 닿는다
+  const fade = Math.round(Math.min(o.width, o.height) * 0.06 / k);
+  const edge = (dir: string) => `linear-gradient(${dir}, transparent, #000 ${fade}px, #000 calc(100% - ${fade}px), transparent)`;
+  for (const r of stage.querySelectorAll<HTMLElement>(":scope > [data-kf-scene]")) {
+    r.style.transformOrigin = `${o.width / 2}px ${top}px`;
+    r.style.transform = `scale(${k})`;
+    r.style.maskImage = `${edge("to right")}, ${edge("to bottom")}`;
+    r.style.maskComposite = "intersect";
+  }
+  return k;
+}
+
+interface ProjectLike {
+  width: number;
+  height: number;
+  duration?: number;
+  captions?: unknown;
+  safeArea?: SafeArea;
+  text?: { minPx?: number };
+  scenes: Span[];
+}
+
+export interface CaptionsPlan {
+  /** 장면에 줄 안전 영역 — on 이면 아래쪽에 자막 띠를 더 뺀다(무대가 그 위로 배치한다). fit 이면 그대로 */
+  safe: SafeArea;
+  /** 장면을 다 지은 뒤 부른다 — 판을 얹고(fit 이면 장면을 띠 위로 줄여 올리고) t 마다 칠하는 함수를 돌려준다 */
+  mount(stage: HTMLElement, style?: KfStyle | null): Promise<(t: number) => void>;
+}
+
+/**
+ * mountProject 가 장면을 짓기 전에 부른다 — 주소 ?captions=on|off|fit 가 kf.json 의 captions 를 그 판만 덮는다.
+ * 자막이 켜져 있고 captions.json 에 들릴 말이 있으면 띠를 뺀 안전 영역과 판 짓기를, 아니면 null.
+ * on: 무대(ctx.safe 로 배치하는 장면)가 띠 위로 제 크기 그대로 올라간다. 픽셀을 박아 둔 장면은 안 움직여 kf check 가 caption.overlap 으로 잡는다.
+ * fit: 장면 코드와 안전 영역은 그대로 두고 장면 뿌리를 띠 위로 줄여 올린다 — 어떤 장면이든 안 겹치지만 내용이 작아지고 움직이는 면적도 준다.
+ */
+export async function captionsPlan(o: { kf: ProjectLike; mode?: string | null }): Promise<CaptionsPlan | null> {
+  const raw = o.mode ?? o.kf.captions;
+  if (captionMode(raw) !== "on") return null;
+  const res = await fetch(new URL("captions.json", document.baseURI)).catch(() => null);
+  if (!res?.ok) return null;
+  const lines = (await res.json().catch(() => null)) as CaptionLine[] | null;
+  if (!Array.isArray(lines)) return null;
+  const { kf } = o;
+  const minPx = kf.text?.minPx;
+  const base = kf.safeArea ?? { top: 0, bottom: 0, left: 0, right: 0 };
+  const m = captionMetrics({ width: kf.width, height: kf.height, safe: base, minPx });
+  const cues = toCues(lines, kf.scenes, { maxEm: m.maxEm, duration: kf.duration });
+  if (!cues.length) return null;
+  const fit = raw === "fit";
+  // 띠는 판이 실제로 쓸 줄 수만큼(어림) — 장면을 짓기 전이라 아직 글꼴로 잴 수 없다
+  const band = captionBand(m, cues.some((c) => !wrapCaption(c.text, m.maxEm, emWidth, 1)) ? 2 : 1);
+  return {
+    safe: fit ? base : { ...base, bottom: base.bottom + band },
+    async mount(stage, style) {
+      const { draw, band: used } = await captionLayer(stage, { cues, width: kf.width, height: kf.height, safe: base, style, minPx });
+      if (fit) liftScenes(stage, { width: kf.width, height: kf.height, safe: base, band: used });
+      return draw;
+    },
+  };
+}

package/packages/motion/src/enter.ts

@@ -0,0 +1,128 @@
+import { clamp, emit, progress, rand, spring, toEase, type Ease, type EaseName, type Style, safeTime } from "@kasaframe/core";
+
+export type MoveName = "fade" | "rise" | "drop" | "pop" | "blurIn" | "scaleIn" | "maskWipe" | "slide";
+export type Side = "left" | "right" | "top" | "bottom";
+
+export interface MoveOpts {
+  /** 시작 시각(초, 장면 안) */
+  at?: number;
+  /** 길이(초) */
+  dur?: number;
+  ease?: EaseName | Ease;
+  /** 움직이는 거리(px) — rise·drop·slide */
+  distance?: number;
+  /** slide·maskWipe 가 들어오는 쪽 */
+  from?: Side;
+  /** 이벤트 기록 — 같은 등장 움직임 되풀이를 검사가 센다 */
+  source?: string;
+  scene?: string;
+  emit?: boolean;
+}
+
+export const MOVES: readonly MoveName[] = ["fade", "rise", "drop", "pop", "blurIn", "scaleIn", "maskWipe", "slide"];
+
+const DEFAULT_DUR: Record<MoveName, number> = {
+  fade: 0.4,
+  rise: 0.5,
+  drop: 0.5,
+  pop: 0.55,
+  blurIn: 0.6,
+  scaleIn: 0.5,
+  maskWipe: 0.6,
+  slide: 0.5,
+};
+
+/** p 는 0(안 보임) → 1(제자리). 등장과 퇴장이 같은 모양을 반대로 쓴다 */
+function shape(name: MoveName, p: number, e: number, local: number, o: MoveOpts): Style {
+  const d = o.distance;
+  switch (name) {
+    case "fade":
+      return { opacity: e };
+    case "rise":
+      return { opacity: clamp(p * 1.6), y: (1 - e) * (d ?? 28) };
+    case "drop":
+      return { opacity: clamp(p * 1.6), y: -(1 - e) * (d ?? 28) };
+    case "pop": {
+      // 스프링이 닫힌 식이라 퇴장(시간을 거꾸로)에도 같은 값이 나온다
+      const s = local <= 0 ? 0.6 : spring(local, { from: 0.6, to: 1, stiffness: 320, damping: 17 });
+      return { opacity: clamp(p * 3), scale: p >= 1 ? 1 : s };
+    }
+    case "blurIn":
+      return { opacity: e, blur: (1 - e) * 18, scale: 1.04 - 0.04 * e };
+    case "scaleIn":
+      return { opacity: e, scale: 0.86 + 0.14 * e };
+    case "maskWipe": {
+      const side = o.from ?? "left";
+      const hide = 1 - e;
+      const opposite = { left: "right", right: "left", top: "bottom", bottom: "top" } as const;
+      return { clip: { [opposite[side]]: hide } };
+    }
+    case "slide": {
+      const side = o.from ?? "left";
+      const dist = d ?? 120;
+      const dx = side === "left" ? -dist : side === "right" ? dist : 0;
+      const dy = side === "top" ? -dist : side === "bottom" ? dist : 0;
+      return { opacity: clamp(p * 2), x: (1 - e) * dx, y: (1 - e) * dy };
+    }
+  }
+}
+
+function check(name: string): MoveName {
+  if (!(MOVES as readonly string[]).includes(name)) throw new Error(`모르는 움직임: ${name} (있는 것: ${MOVES.join(" · ")})`);
+  return name as MoveName;
+}
+
+export function enter(name: MoveName, t: number, opts: MoveOpts = {}): Style {
+  t = safeTime(t);
+  const n = check(name);
+  const at = opts.at ?? 0;
+  const dur = opts.dur ?? DEFAULT_DUR[n];
+  const p = progress(t, at, dur);
+  const e = toEase(opts.ease, n === "pop" ? (x) => x : undefined)(p);
+  if (opts.emit !== false && p > 0 && p < 1) emit({ kind: "move", source: opts.source ?? n, scene: opts.scene, name: `enter:${n}`, value: 1 });
+  return shape(n, p, e, t - at, opts);
+}
+
+/** 퇴장 — at 에서 시작해 dur 뒤에 사라져 있다 */
+export function exit(name: MoveName, t: number, opts: MoveOpts = {}): Style {
+  t = safeTime(t);
+  const n = check(name);
+  const at = opts.at ?? 0;
+  const dur = opts.dur ?? DEFAULT_DUR[n] * 0.7;
+  const p = 1 - progress(t, at, dur);
+  const e = toEase(opts.ease, (x) => x * x)(p);
+  // 스프링 튐은 들어올 때만 — 나갈 때 튀면 떨림으로 보인다
+  return shape(n === "pop" ? "scaleIn" : n, p, e, 0, opts);
+}
+
+/** 들어와 머물다 나간다. out 이 없으면 나가지 않는다 */
+export function inOut(name: MoveName, t: number, opts: MoveOpts & { out?: number; exitAs?: MoveName; outDur?: number } = {}): Style {
+  t = safeTime(t);
+  const a = enter(name, t, opts);
+  if (opts.out === undefined || t < opts.out) return a;
+  return exit(opts.exitAs ?? name, t, { ...opts, at: opts.out, dur: opts.outDur, emit: false });
+}
+
+export interface StaggerOpts {
+  each?: number;
+  /** 어디서부터 번지나 — MoveOpts.from(들어오는 쪽)과 이름이 겹치지 않게 origin */
+  origin?: "start" | "end" | "center" | "random";
+  count?: number;
+  seed?: number | string;
+}
+
+/** i 번째 항목의 늦춤(초) */
+export function stagger(i: number, opts: StaggerOpts = {}): number {
+  const each = opts.each ?? 0.06;
+  const n = opts.count ?? i + 1;
+  switch (opts.origin ?? "start") {
+    case "start":
+      return i * each;
+    case "end":
+      return (n - 1 - i) * each;
+    case "center":
+      return Math.abs(i - (n - 1) / 2) * each;
+    case "random":
+      return rand(opts.seed ?? "stagger", i) * (n - 1) * each;
+  }
+}