kasaframe 0.0.0-stage → 0.1.3

package/packages/motion/src/moves/menu.ts

@@ -0,0 +1,138 @@
+import { rand } from "@kasaframe/core";
+
+// 뼈대 장면이 바로 거는 연출 수 메뉴. 「대충 한 요청」에서도 좋은 수가 나오게 kf new 가 장면마다 고르고(같은 요청이면 같은 수),
+// 지시서(MAKE.md)가 같은 메뉴를 보여 준다. DOM 을 안 만져 Node(계획·지시서)에서도 읽는다 — 실제로 거는 것은 dress.ts.
+
+export type DressKind = "bg" | "text" | "wipe";
+
+export interface MenuItem {
+  name: string;
+  kind: DressKind;
+  does: string;
+  /** examples/moves/<example>/ — 수만 따로 본 3–5초 예시 */
+  example?: string;
+}
+
+// 바탕(bg)은 장면 전체 뒤 — 정지만 둔다. 뜻 없이 떠도는 장식(빛 방울·도는 줄무늬·흐르는 모눈)은 보는 사람이 무엇인지 묻게 만든다.
+// 움직이는 바탕 수(sunburst·speedLines·gridFloor·truchet)는 장면이 이름으로 부를 때만 dressBg 가 건다.
+// 글(text)은 안전 영역 안, 덮기(wipe)는 장면 경계를 걸쳐 앞 장면 끝을 덮고 뒤 장면 처음에 걷힌다
+export const MENU: readonly MenuItem[] = [
+  { name: "still", kind: "bg", does: "정지 바탕 — 바탕색 위 아주 옅은 점 질감. 쉬지 않기는 글·숫자 수가 진다" },
+  { name: "bigWord", kind: "text", does: "큰 낱말 하나 + 등장 움직임(무대 기본)" },
+  { name: "slamWords", kind: "text", does: "박마다 낱말이 화면을 꽉 채우며 쾅 — 판과 글색이 뒤집힌다", example: "slamWords" },
+  { name: "echoStack", kind: "text", does: "같은 낱말이 박마다 한 벌씩 메아리치며 쌓인다", example: "echoStack" },
+  { name: "splitFlap", kind: "text", does: "판 넘김 글자판 — 칸마다 접히며 글자가 넘어가 앉는다", example: "splitFlap" },
+  { name: "ghostStack", kind: "text", does: "외곽선 유령 줄이 먼저 깔리고 박에 채워지며 위로 밀린다", example: "ghostStack" },
+  { name: "ransomLetters", kind: "text", does: "오려 붙인 글자 — 박마다 글자 모양을 다시 뽑는다", example: "ransomLetters" },
+  { name: "neonSign", kind: "text", does: "네온 관 글자가 시동 걸리듯 깜빡이다 켜진다", example: "neonSign" },
+  { name: "ledBoard", kind: "text", does: "LED 점 글판에 한 칸씩 찍힌다", example: "ledBoard" },
+  { name: "none", kind: "wipe", does: "덮지 않고 바로 컷" },
+  { name: "brushWipe", kind: "wipe", does: "붓 획 띠가 번갈아 덮었다가 꼬리가 빠지며 걷힌다", example: "brushWipe" },
+  { name: "irisBlades", kind: "wipe", does: "여섯 날 조리개가 닫혔다 열린다", example: "irisBlades" },
+  { name: "flood", kind: "wipe", does: "가운데 점이 화면을 넘치게 덮었다가 오므라든다", example: "flood" },
+];
+
+export const menuItem = (name: string): MenuItem | undefined => MENU.find((m) => m.name === name);
+
+export interface Pool {
+  bg?: string[];
+  text?: string[];
+  wipe?: string[];
+}
+
+/** 용도 틀(template.json moves)·테마가 주는 추천 묶음. roles 는 장면 역할(hook·drop·end …)마다 덮어쓴다 */
+export interface Bundle extends Pool {
+  roles?: Record<string, Pool>;
+}
+
+// 틀에 moves 가 없을 때 — 어느 용도에도 무난한 묶음
+const BASE: Required<Pool> = { bg: ["still"], text: ["bigWord", "echoStack", "splitFlap", "ghostStack"], wipe: ["brushWipe", "irisBlades", "flood"] };
+
+// 테마마다 비유에 맞는 수 — 테마를 고르면 용도 묶음보다 앞에 둔다(테마 효과와 결이 같은 것만)
+export const THEME_POOLS: Readonly<Record<string, Pool>> = {
+  "debug-hud": { text: ["splitFlap", "ledBoard", "ghostStack"], wipe: ["irisBlades", "flood"] },
+  "og-measure": { text: ["splitFlap", "ghostStack", "echoStack"], wipe: ["irisBlades", "flood"] },
+  "kasaterm-cells": { text: ["ledBoard", "splitFlap", "slamWords"], wipe: ["flood", "irisBlades"] },
+  "kawaii-sticker": { text: ["ransomLetters", "slamWords", "echoStack"], wipe: ["brushWipe", "flood"] },
+  "riso-zine": { text: ["ransomLetters", "echoStack", "slamWords"], wipe: ["brushWipe", "flood"] },
+  "depth-flight": { text: ["neonSign", "ghostStack", "splitFlap"], wipe: ["irisBlades", "flood"] },
+  "iso-diorama": { text: ["splitFlap", "echoStack", "ghostStack"], wipe: ["irisBlades", "brushWipe"] },
+  "glass-light": { text: ["ghostStack", "echoStack", "splitFlap"], wipe: ["irisBlades", "flood"] },
+};
+
+const known = (kind: DressKind) => (n: string) => menuItem(n)?.kind === kind;
+
+/** 틀 묶음 + 테마 묶음 → 한 벌. 테마 수를 앞에, 메뉴에 없는 이름은 버린다 */
+export function bundleFor(tpl?: Bundle, theme?: string): Required<Bundle> {
+  const th = theme ? THEME_POOLS[theme] : undefined;
+  const merge = (kind: DressKind, ...lists: (string[] | undefined)[]) => [...new Set(lists.flatMap((l) => l ?? []))].filter(known(kind));
+  const roles: Record<string, Pool> = {};
+  for (const [role, p] of Object.entries(tpl?.roles ?? {})) {
+    // 역할 몫은 틀이 이유를 대고 고른 것(훅은 첫 프레임부터 꽉 차는 글) — 테마 수는 그 뒤에 섞지 않는다
+    roles[role] = { bg: p.bg?.filter(known("bg")), text: p.text?.filter(known("text")), wipe: p.wipe?.filter(known("wipe")) };
+  }
+  const bg = merge("bg", th?.bg, tpl?.bg ?? BASE.bg);
+  return {
+    bg: bg.length ? bg : BASE.bg,
+    text: merge("text", th?.text, tpl?.text ?? BASE.text),
+    wipe: merge("wipe", th?.wipe, tpl?.wipe ?? BASE.wipe),
+    roles,
+  };
+}
+
+export interface Dress {
+  bg: string;
+  text: string;
+  /** 앞 장면 경계에서 걷히는 덮기 — 앞 장면의 wipeOut 과 같은 이름이라 이어진다 */
+  wipeIn: string;
+  wipeOut: string;
+}
+
+export const NO_DRESS: Dress = { bg: "still", text: "bigWord", wipeIn: "none", wipeOut: "none" };
+
+/** 같은 요청·용도·테마면 같은 글이 나오게 공백만 고른다 */
+export const dressSeed = (...parts: (string | undefined | null)[]): string =>
+  parts
+    .map((p) => (p ?? "").trim().replace(/\s+/g, " "))
+    .join("|");
+
+// 이어지는 장면이 같은 수를 쓰지 않게 — 고를 게 하나뿐이면 그대로
+function choose(seed: string, i: number, list: readonly string[], avoid: string | undefined): string {
+  const pool = list.length > 1 && avoid ? list.filter((x) => x !== avoid) : list;
+  return pool[Math.min(pool.length - 1, Math.floor(rand(seed, i) * pool.length))];
+}
+
+/**
+ * 장면마다 바탕·글·경계 덮기를 고른다. 시드(요청 글·용도·테마)가 같으면 늘 같은 고름이다.
+ * - 이음매(seam)는 3D 전환이 맡아 아무것도 걸지 않고, 그 앞뒤 경계도 덮지 않는다(전환이 앞뒤 화면을 그대로 잡아야 한다).
+ * - 드롭으로 들어가는 경계는 덮지 않는다 — 드롭 첫 박은 맨 화면으로 터져야 한다. 첫 장면은 첫 프레임부터 내용이 있어야 해서 덮고 시작하지 않는다.
+ * - 되돌이(loop)면 마지막 장면 끝도 덮지 않는다(끝 화면이 첫 화면으로 이어진다).
+ */
+export function pickDress(seed: string, scenes: readonly { id: string; role: string; dur: number }[], bundle: Required<Bundle>): Dress[] {
+  const out: Dress[] = [];
+  for (const [i, s] of scenes.entries()) {
+    if (s.role === "seam") {
+      out.push({ ...NO_DRESS });
+      continue;
+    }
+    const role = bundle.roles[s.role] ?? {};
+    const prev = out[i - 1];
+    const bg = choose(seed, i * 4, role.bg?.length ? role.bg : bundle.bg, prev?.bg);
+    const text = choose(seed, i * 4 + 1, role.text?.length ? role.text : bundle.text, prev?.text);
+    out.push({ bg, text, wipeIn: "none", wipeOut: "none" });
+  }
+  let last = "";
+  for (let i = 0; i + 1 < scenes.length; i++) {
+    const a = scenes[i];
+    const b = scenes[i + 1];
+    if (a.role === "seam" || b.role === "seam" || b.role === "drop" || a.dur < 1.2 || b.dur < 1.2) continue;
+    const list = (bundle.roles[b.role]?.wipe?.length ? bundle.roles[b.role].wipe : bundle.wipe) ?? [];
+    if (!list.length) continue;
+    const w = choose(seed, i * 4 + 2, list, last);
+    if (w === "none") continue;
+    out[i].wipeOut = w;
+    out[i + 1].wipeIn = w;
+    last = w;
+  }
+  return out;
+}

package/packages/motion/src/moves/morphBox.ts

@@ -0,0 +1,96 @@
+import { clamp, ease, safeTime } from "@kasaframe/core";
+import { div, lastIndex, mark } from "./fit.ts";
+import { springSteps } from "./liquidTab.ts";
+
+export interface MorphBoxState {
+  w: number;
+  h: number;
+  radius?: number;
+  /** #rrggbb — 색도 스프링으로 섞으려면 16진수 */
+  color?: string;
+  /** 이 상태의 안을 짓는다. (t, since) => void 를 돌려주면 장면 초·이 상태가 된 뒤 초로 칠한다 */
+  build?: (inner: HTMLElement) => ((t: number, since: number) => void) | void;
+}
+
+export interface MorphBoxOpts {
+  states: MorphBoxState[];
+  /** 상태가 바뀌는 시각과 상태 번호 — 첫 걸음이 처음 상태 */
+  steps: { at: number; state: number }[];
+  x?: number;
+  y?: number;
+  shadow?: string;
+  stiffness?: number;
+  damping?: number;
+  w?: number;
+  h?: number;
+  scene?: string;
+}
+
+function rgb(hex: string): [number, number, number] {
+  const m = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
+  const n = m ? parseInt(m[1], 16) : 0xffffff;
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+
+/**
+ * 상자 하나가 UI 상태를 오간다 — 단추 → 로더 → 카드 → 토글 …, 크기·모서리·색은 springSteps 로 이어지고 안의 내용은 짧은 흐림으로 바뀐다.
+ * (Aubry 0.2–13.8초)
+ */
+export function morphBox(el: HTMLElement, o: MorphBoxOpts): (t: number) => void {
+  const doc = el.ownerDocument;
+  const W = o.w ?? 1920;
+  const H = o.h ?? 1080;
+  const cx = o.x ?? W / 2;
+  const cy = o.y ?? H / 2;
+  const sp = { stiffness: o.stiffness ?? 230, damping: o.damping ?? 21 };
+  const box = div(doc, `position:absolute;left:0;top:0;overflow:hidden;box-shadow:${o.shadow ?? "0 24px 60px rgba(0,0,0,.18)"}`);
+  el.append(box);
+  const layers = o.states.map((s) => {
+    const inner = div(doc, `position:absolute;left:50%;top:50%;width:${s.w}px;height:${s.h}px;margin:${-s.h / 2}px 0 0 ${-s.w / 2}px`);
+    box.append(inner);
+    return { inner, paint: s.build?.(inner) ?? null };
+  });
+  const first = o.steps[0]?.state ?? 0;
+  const key = (f: (s: MorphBoxState) => number) => {
+    const steps = o.steps.slice(1).map((s) => ({ at: s.at, to: f(o.states[s.state]) }));
+    return { steps, from: f(o.states[first]) };
+  };
+  const tracks = {
+    w: key((s) => s.w),
+    h: key((s) => s.h),
+    r: key((s) => s.radius ?? 24),
+    c: [0, 1, 2].map((ch) => key((s) => rgb(s.color ?? "#ffffff")[ch])),
+  };
+  const at = (tr: { steps: { at: number; to: number }[]; from: number }, t: number) => springSteps(t, tr.steps, { from: tr.from, ...sp });
+  const times = o.steps.map((s) => s.at);
+  return (t: number) => {
+    t = safeTime(t);
+    const w = Math.max(1, at(tracks.w, t));
+    const h = Math.max(1, at(tracks.h, t));
+    const r = Math.max(0, Math.min(at(tracks.r, t), w / 2, h / 2));
+    const [cr, cg, cb] = tracks.c.map((tr) => Math.round(clamp(at(tr, t), 0, 255)));
+    box.style.width = `${w.toFixed(1)}px`;
+    box.style.height = `${h.toFixed(1)}px`;
+    box.style.borderRadius = `${r.toFixed(1)}px`;
+    box.style.background = `rgb(${cr},${cg},${cb})`;
+    box.style.transform = `translate(${(cx - w / 2).toFixed(1)}px, ${(cy - h / 2).toFixed(1)}px)`;
+    const k = Math.max(0, lastIndex(times, t));
+    const cur = o.steps[k]?.state ?? first;
+    const prev = k > 0 ? o.steps[k - 1].state : -1;
+    const since = t - (o.steps[k]?.at ?? 0);
+    layers.forEach((l, i) => {
+      // 나가는 내용은 0.1초에 흐려지며 빠지고, 들어오는 내용은 0.06초 뒤 0.18초에 맺힌다
+      let v = 0;
+      if (i === cur) v = k === 0 ? 1 : ease.outCubic(clamp((since - 0.06) / 0.18));
+      else if (i === prev && prev !== cur) v = 1 - clamp(since / 0.1);
+      // display 는 build 가 정한 것(grid 등)이라 건드리지 않는다
+      l.inner.style.visibility = v > 0.001 ? "visible" : "hidden";
+      if (v <= 0.001) return;
+      l.inner.style.opacity = v.toFixed(3);
+      l.inner.style.filter = v < 0.999 ? `blur(${(8 * (1 - v)).toFixed(2)}px)` : "";
+      l.inner.style.transform = `scale(${(0.92 + 0.08 * v).toFixed(4)})`;
+      if (l.paint) l.paint(t, i === cur ? since : 0);
+    });
+    mark("morphBox", o.scene, k > 0 && since < 0.45);
+  };
+}

package/packages/motion/src/moves/neonSign.ts

@@ -0,0 +1,78 @@
+import { clamp, rand, safeTime } from "@kasaframe/core";
+import { div, fitSize, mark } from "./fit.ts";
+
+export interface NeonSignOpts {
+  text: string;
+  /** 첫 글자 관이 켜지기 시작하는 시각 */
+  at?: number;
+  /** 글자마다 늦춤(초) */
+  each?: number;
+  /** 관 색 */
+  color?: string;
+  size?: number;
+  /** 다 켜진 뒤 가끔 꺼졌다 켜지는 글자 수 */
+  dropouts?: number;
+  w?: number;
+  h?: number;
+  seed?: string | number;
+  scene?: string;
+}
+
+/**
+ * 네온 관 글 — 글자마다 시동이 걸리듯 몇 번 깜빡이다 켜지고, 빛이 벽에 번진다. 다 켜진 뒤에도 몇 글자가 가끔 꺼졌다 켜진다.
+ * (Ghost in the Booth 24.5–27초 네온 간판)
+ */
+export function neonSign(el: HTMLElement, o: NeonSignOpts): (t: number) => void {
+  const doc = el.ownerDocument;
+  const W = o.w ?? 1920;
+  const H = o.h ?? 1080;
+  const at = o.at ?? 0;
+  const each = o.each ?? 0.07;
+  const seed = o.seed ?? o.text;
+  const color = o.color ?? "#FF4F7A";
+  const px = o.size ?? fitSize(o.text, W, H, { share: 0.78, hShare: 0.34 });
+  const layer = div(doc, "position:absolute;inset:0;overflow:hidden;display:flex;align-items:center;justify-content:center");
+  const wall = div(doc, `position:absolute;left:50%;top:50%;width:${W * 0.9}px;height:${px * 2.4}px;margin-left:${-W * 0.45}px;margin-top:${-px * 1.2}px;border-radius:50%;background:radial-gradient(closest-side,${color},transparent);filter:blur(${px * 0.3}px)`);
+  const row = div(doc, `position:relative;display:flex;white-space:nowrap;font-family:var(--kf-font-display);font-weight:600;font-size:${px}px;line-height:1;letter-spacing:.02em`);
+  layer.append(wall, row);
+  el.append(layer);
+  const glow = `0 0 .03em #fff,0 0 .12em ${color},0 0 .32em ${color},0 0 .7em ${color}`;
+  const letters = [...o.text].map((c, i) => {
+    const s = doc.createElement("span");
+    s.textContent = c === " " ? "\u00a0" : c;
+    row.append(s);
+    return { s, on: at + i * each + rand(seed, i) * 0.12 };
+  });
+  const n = letters.length;
+  const drops = Array.from({ length: o.dropouts ?? 2 }, (_, k) => Math.floor(rand(seed, 300 + k) * n));
+
+  return (t: number) => {
+    t = safeTime(t);
+    let lit = 0;
+    let moving = false;
+    letters.forEach((l, i) => {
+      const local = t - l.on;
+      let on = local >= 0.24;
+      // 시동: 켜지기 전 0.24초 동안 1/30초 칸마다 켜졌다 꺼졌다
+      if (local >= 0 && local < 0.24) {
+        on = rand(seed, i * 50 + Math.floor(local * 30)) < 0.45 + local * 2;
+        moving = true;
+      }
+      // 다 켜진 뒤 고른 글자만 1.3초쯤마다 잠깐 꺼진다
+      if (on && drops.includes(i)) {
+        const cyc = (t - l.on) % 1.3;
+        if (cyc > 0.9 && cyc < 0.98) on = false;
+      }
+      if (on) lit++;
+      // 꺼진 관도 읽혀야 한다 — 어두운 벽 위 3:1 넘는 흐린 유리색(검사 text.contrast)
+      l.s.style.color = on ? "#FFF3F6" : "#9A6478";
+      l.s.style.textShadow = on ? glow : "none";
+    });
+    // 벽 번짐은 켜진 관 수만큼, 미세하게 웅웅거린다
+    const hum = 0.92 + 0.08 * rand(seed, 900 + Math.floor(t * 30));
+    wall.style.opacity = ((0.35 * lit) / Math.max(1, n) * hum).toFixed(3);
+    // 간판이 조금씩 다가가며 흔들려 다 켜진 뒤에도 멈추지 않는다
+    row.style.transform = `translateX(${(W * 0.012 * Math.sin(t * 1.6)).toFixed(1)}px) scale(${(1 + 0.04 * clamp(t, 0, 30)).toFixed(4)})`;
+    mark("neonSign", o.scene, moving);
+  };
+}

package/packages/motion/src/moves/panelPop.ts

@@ -0,0 +1,78 @@
+import { clamp, rand, safeTime, spring } from "@kasaframe/core";
+import { div, mark } from "./fit.ts";
+
+export interface ComicPanel {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  /** 톡 붙는 시각 — 안 주면 처음부터 있다(가운데 고정 칸) */
+  at?: number;
+  /** 자리 잡은 뒤 기울기(도) */
+  tilt?: number;
+  fill?: string;
+  /** 칸 안을 짓는다 — (t) => void 를 돌려주면 칸 시각(장면 초)으로 칠한다 */
+  build?: (inner: HTMLElement) => ((t: number) => void) | void;
+}
+
+export interface PanelPopOpts {
+  panels: ComicPanel[];
+  /** 검정 테두리(px) */
+  border?: number;
+  /** 칸 바깥 흰 틈(px) */
+  gap?: number;
+  ink?: string;
+  paper?: string;
+  /** 붙은 뒤 살짝 흔들리는 정도 — 0 이면 가만히 */
+  idle?: number;
+  w?: number;
+  h?: number;
+  scene?: string;
+}
+
+/**
+ * 만화 칸 팝 — 칸마다 0.4배에서 출렁이며 커지고 기울기가 스프링으로 자리 잡는다. 굵은 검정 테두리와 흰 틈, 칸 안은 build 로.
+ * (ChillPanic「Benchmark」 31.5–40초 — 가운데 칸은 고정, 둘레에 박마다)
+ */
+export function panelPop(el: HTMLElement, o: PanelPopOpts): (t: number) => void {
+  const doc = el.ownerDocument;
+  const border = o.border ?? 10;
+  const gap = o.gap ?? 12;
+  const ink = o.ink ?? "#111111";
+  const paper = o.paper ?? "#ffffff";
+  const items = o.panels.map((p, i) => {
+    const box = div(
+      doc,
+      `position:absolute;left:${p.x}px;top:${p.y}px;width:${p.w}px;height:${p.h}px;box-sizing:border-box;border:${border}px solid ${ink};` +
+        `background:${p.fill ?? paper};box-shadow:0 0 0 ${gap}px ${paper};overflow:hidden;transform-origin:50% 50%;z-index:${i + 1}`,
+    );
+    const inner = div(doc, "position:absolute;inset:0;overflow:hidden");
+    box.append(inner);
+    el.append(box);
+    const paint = p.build?.(inner) ?? null;
+    return { p, box, paint, seed: i };
+  });
+  const idle = o.idle ?? 1;
+  return (t: number) => {
+    t = safeTime(t);
+    let moving = false;
+    for (const { p, box, paint, seed } of items) {
+      const tilt = p.tilt ?? 0;
+      const local = p.at === undefined ? 10 : t - p.at;
+      if (local < 0) {
+        box.style.display = "none";
+        continue;
+      }
+      box.style.display = "block";
+      const s = p.at === undefined ? 1 : spring(local, { from: 0.4, to: 1, stiffness: 320, damping: 14 });
+      const r = p.at === undefined ? tilt : spring(local, { from: tilt * 3 + (seed % 2 ? 8 : -8), to: tilt, stiffness: 260, damping: 16 });
+      // 붙은 칸도 숨 쉬듯 아주 조금 — 칸만 있는 화면이 멈춰 보이지 않게
+      const wob = idle * Math.sin(t * 2.3 + rand("panel", seed) * 6.28);
+      box.style.opacity = String(clamp(local / 0.06));
+      box.style.transform = `rotate(${(r + 0.5 * wob).toFixed(3)}deg) scale(${(s * (1 + 0.006 * wob)).toFixed(4)})`;
+      if (paint) paint(t);
+      if (local < 0.35) moving = true;
+    }
+    mark("panelPop", o.scene, moving);
+  };
+}

package/packages/motion/src/moves/paperTear.ts

@@ -0,0 +1,75 @@
+import { clamp, ease, rand, safeTime } from "@kasaframe/core";
+import { div, mark } from "./fit.ts";
+
+export interface PaperTearOpts {
+  /** 찢기 시작 시각 */
+  at: number;
+  dur?: number;
+  /** 찢길 앞 화면을 짓는다 — 두 쪽에 한 번씩 불린다. (t) => void 를 돌려주면 장면 초로 칠한다 */
+  build: (half: HTMLElement) => ((t: number) => void) | void;
+  /** 찢긴 가장자리 띠 색·폭(px) */
+  edge?: string;
+  edgeWidth?: number;
+  /** 톱니 수 */
+  teeth?: number;
+  /** 갈라지며 기우는 각(도) */
+  angle?: number;
+  seed?: string | number;
+  w?: number;
+  h?: number;
+  scene?: string;
+}
+
+/**
+ * 화면이 찢어진다 — 앞 화면을 두 벌 지어 시드 지그재그 선으로 잘라 두 쪽에 붙이고, 반대로 기울며 갈라진다. 찢긴 자리엔 흰 종이 띠.
+ * 갈라진 틈으로 이 층 뒤(다음 장면)가 보인다. (mexicat p(doom) 80.9–81.1초)
+ */
+export function paperTear(el: HTMLElement, o: PaperTearOpts): (t: number) => void {
+  const doc = el.ownerDocument;
+  const W = o.w ?? 1920;
+  const H = o.h ?? 1080;
+  const seed = o.seed ?? "tear";
+  const teeth = o.teeth ?? 18;
+  const ew = o.edgeWidth ?? 10;
+  const dur = o.dur ?? 0.45;
+  // 찢는 선 — 위에서 아래로 굽이치며, 톱니는 짧게 엇갈린다
+  const line = Array.from({ length: teeth + 1 }, (_, k) => {
+    const y = (k / teeth) * H;
+    const sway = Math.sin((k / teeth) * Math.PI * 1.3 + rand(seed, 1) * 6) * W * 0.05;
+    return { x: W / 2 + sway + (rand(seed, k + 10) - 0.5) * W * 0.05 + (k % 2 ? 1 : -1) * 9, y };
+  });
+  const pad = Math.max(W, H);
+  const poly = (side: -1 | 1, inset: number) => {
+    const pts = line.map((p) => `${(p.x + side * inset).toFixed(1)}px ${p.y.toFixed(1)}px`);
+    const outer = side < 0 ? [`${-pad}px ${H + pad}px`, `${-pad}px ${-pad}px`] : [`${W + pad}px ${H + pad}px`, `${W + pad}px ${-pad}px`];
+    // 선 끝을 화면 밖으로 늘려 위·아래 가장자리에 틈이 안 남게
+    return `polygon(${outer[1]}, ${(line[0].x + side * inset).toFixed(1)}px ${-pad}px, ${pts.join(", ")}, ${(line[teeth].x + side * inset).toFixed(1)}px ${H + pad}px, ${outer[0]})`;
+  };
+  const halves = ([-1, 1] as const).map((side) => {
+    const part = div(doc, `position:absolute;left:0;top:0;width:${W}px;height:${H}px;transform-origin:${side < 0 ? "0% 100%" : "100% 100%"}`);
+    const paper = div(doc, `position:absolute;inset:0;background:${o.edge ?? "#fbf8f1"};clip-path:${poly(side, 0)}`);
+    const content = div(doc, `position:absolute;inset:0;overflow:hidden;clip-path:${poly(side, 0)}`);
+    part.append(paper, content);
+    el.append(part);
+    const paint = o.build(content) ?? null;
+    return { side, part, paper, content, paint };
+  });
+  return (t: number) => {
+    t = safeTime(t);
+    const p = ease.inCubic(clamp((t - o.at) / dur));
+    // 갈라지기 전 찰나에 흰 띠가 먼저 드러난다 — 찢기는 소리 자리
+    const crack = clamp((t - o.at) / 0.08);
+    for (const h of halves) {
+      if (h.paint) h.paint(t);
+      const shift = h.side * (crack * 6 + p * W * 0.62);
+      const rot = h.side * p * (o.angle ?? 9);
+      const drop = p * p * H * 0.25;
+      h.part.style.transform = `translate(${shift.toFixed(1)}px, ${drop.toFixed(1)}px) rotate(${rot.toFixed(2)}deg)`;
+      // 찢기 전엔 두 쪽 내용이 선에서 딱 맞물리고, 찢는 순간 흰 띠만큼 물러난다
+      h.content.style.clipPath = poly(h.side, ew * crack);
+      h.paper.style.opacity = t < o.at ? "0" : "1";
+      h.part.style.visibility = p >= 1 ? "hidden" : "visible";
+    }
+    mark("paperTear", o.scene, t >= o.at && t < o.at + dur);
+  };
+}

package/packages/motion/src/moves/path.ts

@@ -0,0 +1,64 @@
+// 경로는 점 목록으로 받는다 — DOM 을 재지 않으니 장면이 숨어 있어도, 탭이 달라도 같은 값이다.
+
+export type Pt = [number, number];
+
+/** 지나는 점들을 부드러운 곡선(Catmull-Rom)으로 촘촘히 — 점 사이마다 seg 개 */
+export function curve(points: readonly Pt[], seg = 16): Pt[] {
+  if (points.length < 3) return points.map((p) => [p[0], p[1]] as Pt);
+  const out: Pt[] = [];
+  for (let i = 0; i < points.length - 1; i++) {
+    const p0 = points[Math.max(0, i - 1)];
+    const p1 = points[i];
+    const p2 = points[i + 1];
+    const p3 = points[Math.min(points.length - 1, i + 2)];
+    for (let k = 0; k < seg; k++) {
+      const u = k / seg;
+      const u2 = u * u;
+      const u3 = u2 * u;
+      const f = (a: number, b: number, c: number, d: number) => 0.5 * (2 * b + (-a + c) * u + (2 * a - 5 * b + 4 * c - d) * u2 + (-a + 3 * b - 3 * c + d) * u3);
+      out.push([f(p0[0], p1[0], p2[0], p3[0]), f(p0[1], p1[1], p2[1], p3[1])]);
+    }
+  }
+  const last = points[points.length - 1];
+  out.push([last[0], last[1]]);
+  return out;
+}
+
+/** 점마다 처음부터 잰 길이 */
+export function lengths(pts: readonly Pt[]): number[] {
+  const cum = [0];
+  for (let i = 1; i < pts.length; i++) cum.push(cum[i - 1] + Math.hypot(pts[i][0] - pts[i - 1][0], pts[i][1] - pts[i - 1][1]));
+  return cum;
+}
+
+/** 길이 s 자리의 점과 진행 방향(라디안) */
+export function pointAt(pts: readonly Pt[], cum: readonly number[], s: number): { x: number; y: number; angle: number } {
+  const n = pts.length;
+  if (n === 0) return { x: 0, y: 0, angle: 0 };
+  if (n === 1) return { x: pts[0][0], y: pts[0][1], angle: 0 };
+  const L = cum[n - 1];
+  const v = Math.max(0, Math.min(L, s));
+  let i = 1;
+  while (i < n - 1 && cum[i] < v) i++;
+  const a = pts[i - 1];
+  const b = pts[i];
+  const seg = cum[i] - cum[i - 1] || 1;
+  const f = (v - cum[i - 1]) / seg;
+  return { x: a[0] + (b[0] - a[0]) * f, y: a[1] + (b[1] - a[1]) * f, angle: Math.atan2(b[1] - a[1], b[0] - a[0]) };
+}
+
+/** 처음부터 길이 s 까지만 자른 점 목록 */
+export function sliceTo(pts: readonly Pt[], cum: readonly number[], s: number): Pt[] {
+  const out: Pt[] = [];
+  for (let i = 0; i < pts.length && cum[i] < s; i++) out.push([pts[i][0], pts[i][1]]);
+  if (s > 0) {
+    const e = pointAt(pts, cum, s);
+    out.push([e.x, e.y]);
+  }
+  return out;
+}
+
+/** SVG path d */
+export function toD(pts: readonly Pt[]): string {
+  return pts.map((p, i) => `${i ? "L" : "M"}${p[0].toFixed(1)} ${p[1].toFixed(1)}`).join("");
+}

package/packages/motion/src/moves/pathText.ts

@@ -0,0 +1,107 @@
+import { clamp, ease, lerp, safeTime } from "@kasaframe/core";
+import { lastIndex, mark, textEm } from "./fit.ts";
+import { curve, lengths, pointAt, sliceTo, toD, type Pt } from "./path.ts";
+
+export interface PathTextOpts {
+  /** 경로가 지나는 점(무대 px). 함수면 프레임마다 바뀐다 — 처지는 줄·휘는 곡선 */
+  points: Pt[] | ((t: number) => Pt[]);
+  words: string[];
+  /** 낱말마다 다 놓이는 시각(장면 초) — 불씨가 그 낱말 끝에 닿는 때 */
+  times: number[];
+  size?: number;
+  /** 강조할 낱말 번호 */
+  hot?: number[];
+  /** 경로 선을 그린다(기본 그린다) */
+  line?: boolean;
+  w?: number;
+  h?: number;
+  scene?: string;
+}
+
+const SVG = "http://www.w3.org/2000/svg";
+let uid = 0;
+
+/**
+ * 곡선을 타는 글 — 불씨가 경로를 따라 앞서 가고, 지나간 자리에 글자가 켜진다. 경로가 함수면 글이 줄처럼 처지고 휜다.
+ * (mexicat p(doom) 9.6–12.6초 손실 곡선 위 가사 · The Simulation's Ending 16.5–17.8초 처진 문장)
+ */
+export function pathText(el: HTMLElement, o: PathTextOpts): (t: number) => void {
+  const doc = el.ownerDocument;
+  const W = o.w ?? 1920;
+  const H = o.h ?? 1080;
+  const size = o.size ?? 72;
+  const id = `kf-path-${++uid}`;
+  const svg = doc.createElementNS(SVG, "svg");
+  svg.setAttribute("viewBox", `0 0 ${W} ${H}`);
+  svg.style.cssText = "position:absolute;left:0;top:0;width:100%;height:100%;overflow:visible";
+  svg.innerHTML =
+    `<defs><path id="${id}"/><filter id="${id}-glow" x="-50%" y="-50%" width="200%" height="200%"><feGaussianBlur stdDeviation="9"/></filter></defs>` +
+    `<path class="line" fill="none" stroke="var(--kf-accent)" stroke-width="3" stroke-linecap="round" opacity=".55"/>` +
+    `<text style="font-family:var(--kf-font-display);font-weight:760;letter-spacing:-.01em" font-size="${size}"><textPath href="#${id}"></textPath></text>` +
+    `<circle class="glow" r="${size * 0.32}" fill="var(--kf-accent)" filter="url(#${id}-glow)"/><circle class="core" r="${Math.max(4, size * 0.08)}" fill="#fff"/>`;
+  el.append(svg);
+  const defPath = svg.querySelector("defs path")!;
+  const line = svg.querySelector<SVGPathElement>("path.line")!;
+  const text = svg.querySelector<SVGTextElement>("text")!;
+  const tp = svg.querySelector("textPath")!;
+  const glow = svg.querySelector<SVGCircleElement>("circle.glow")!;
+  const core = svg.querySelector<SVGCircleElement>("circle.core")!;
+  if (o.line === false) line.style.display = "none";
+
+  const n = Math.min(o.words.length, o.times.length);
+  const chars: { span: SVGTSpanElement; word: number }[] = [];
+  for (let i = 0; i < n; i++) {
+    const s = i < n - 1 ? `${o.words[i]} ` : o.words[i];
+    for (const c of s) {
+      const span = doc.createElementNS(SVG, "tspan");
+      span.textContent = c;
+      tp.append(span);
+      chars.push({ span, word: i });
+    }
+  }
+  // 경로를 따라 몇 px 에서 글자가 시작하는지 — 처음 보일 때 한 번 잰다(그 전엔 글자 수로 어림)
+  let starts = chars.map((_, i) => textEm(chars.slice(0, i).map((c) => c.span.textContent).join("")) * size);
+  let measured = false;
+  const wordEnd = (i: number): number => {
+    let k = -1;
+    for (let j = 0; j < chars.length; j++) if (chars[j].word === i) k = j;
+    if (k < 0) return 0;
+    const next = k + 1 < chars.length ? starts[k + 1] : starts[k] + size * 0.6;
+    return next;
+  };
+  const fixed = typeof o.points === "function" ? null : curve(o.points);
+
+  return (t: number) => {
+    t = safeTime(t);
+    const pts = fixed ?? curve((o.points as (t: number) => Pt[])(t));
+    const cum = lengths(pts);
+    defPath.setAttribute("d", toD(pts));
+    if (!measured && text.getComputedTextLength() > 0) {
+      measured = true;
+      starts = chars.map((_, i) => (i === 0 ? 0 : text.getSubStringLength(0, i)));
+    }
+    // 불씨 자리: 낱말 i 의 시각에 그 낱말 끝, 사이에서는 다음 낱말 끝으로 미끄러진다
+    const k = lastIndex(o.times.slice(0, n), t);
+    let s: number;
+    if (k < 0) s = lerp(0, wordEnd(0), ease.inOutCubic(clamp((t - (o.times[0] - 0.35)) / 0.35)));
+    else if (k >= n - 1) s = wordEnd(n - 1) + 36 * (t - o.times[n - 1]);
+    else s = lerp(wordEnd(k), wordEnd(k + 1), ease.inOutCubic(clamp((t - o.times[k]) / (o.times[k + 1] - o.times[k]))));
+    chars.forEach((c, i) => {
+      const on = clamp((s - starts[i]) / (size * 0.5));
+      c.span.setAttribute("opacity", on.toFixed(3));
+      const fresh = t - o.times[c.word] < 0.2 && on > 0;
+      c.span.setAttribute("fill", fresh || o.hot?.includes(c.word) ? "var(--kf-accent)" : "var(--kf-ink)");
+    });
+    line.setAttribute("d", toD(sliceTo(pts, cum, s)));
+    // 글은 선 위에 앉게 — 기준선을 경로 위로 띄운다
+    chars[0]?.span.setAttribute("dy", `${(-size * 0.28).toFixed(1)}`);
+    const hp = pointAt(pts, cum, s);
+    const pulse = 1 + 0.15 * Math.sin(t * 11);
+    for (const c of [glow, core]) {
+      c.setAttribute("cx", hp.x.toFixed(1));
+      c.setAttribute("cy", hp.y.toFixed(1));
+    }
+    glow.setAttribute("transform", `translate(${hp.x} ${hp.y}) scale(${pulse.toFixed(3)}) translate(${-hp.x} ${-hp.y})`);
+    mark("pathText", o.scene, k < n - 1);
+  };
+}