kasaframe 0.0.0-stage → 0.1.1

package/packages/motion/src/transition3d/rig.ts

@@ -0,0 +1,502 @@
+import { clamp, progress, rand, toEase, type Beats, type BeatGrid, type Ease, type EaseName } from "@kasaframe/core";
+import type { Vec3 } from "../camera.ts";
+
+export type { Vec3 };
+
+/** 3D 일곱 가지 + gl-transitions(`gl:<이름>`) + SmoothUI 덮개(`smooth:<이름>`) */
+export type Transition3dName = "dive" | "portal" | "cards" | "shatter" | "zoomOut" | "fold" | "diveChain" | "whip" | `gl:${string}` | `smooth:${string}`;
+
+export const TRANSITIONS_3D = ["dive", "portal", "cards", "shatter", "zoomOut", "fold", "diveChain", "whip"] as const satisfies readonly Transition3dName[];
+
+/** 혼자 쓸 때(장면 길이를 안 줄 때) 기본 길이 */
+export const DUR_3D: Record<(typeof TRANSITIONS_3D)[number], number> = { dive: 2.8, portal: 2.2, cards: 2.6, shatter: 2.2, zoomOut: 2.4, fold: 2.0, diveChain: 2.4, whip: 1.2 };
+
+/** 혼자 쓸 때 기본 길이 — 셰이더 전환(gl·smooth)은 짧게 */
+export const durOf = (kind: Transition3dName): number => (kind in DUR_3D ? DUR_3D[kind as keyof typeof DUR_3D] : 1.2);
+
+/** 세로 시야각(도). 높이 1 인 판이 화면을 꽉 채우는 거리가 FIT */
+export const FOV = 40;
+export const FIT = 0.5 / Math.tan((FOV * Math.PI) / 360);
+
+export interface Pose {
+  pos: Vec3;
+  look: Vec3;
+  /** 시선 축 둘레 기울기(라디안) */
+  roll?: number;
+  /** 더하는 화각(도) */
+  fov?: number;
+}
+
+export interface TimingOpts {
+  /** 시작 시각(장면 안 초). 기본 0 */
+  at?: number;
+  /** 길이. 장면 ctx 가 있으면 기본은 장면 끝까지 */
+  dur?: number;
+  /** 이 시각에 끝나게 — 드롭·박 시각을 그대로 넣는다. at 을 안 주면 at = endAt - dur */
+  endAt?: number;
+  /** 끝을 가장 가까운 박·마디·드롭에 붙인다(beats 필요) */
+  snap?: BeatGrid;
+  beats?: Beats;
+}
+
+export interface Timing {
+  at: number;
+  dur: number;
+}
+
+/** at·dur·endAt·snap 을 한 가지 구간으로. 장면 길이(sceneDur)가 있으면 그 안으로 자른다 */
+export function resolveTiming(o: TimingOpts, fallbackDur: number, sceneDur?: number): Timing {
+  let at = o.at ?? 0;
+  let dur = o.dur ?? (sceneDur !== undefined ? sceneDur - at : fallbackDur);
+  if (o.endAt !== undefined) {
+    if (o.at === undefined) at = o.endAt - dur;
+    else dur = o.endAt - at;
+  }
+  if (o.snap && o.beats) {
+    const end = o.beats.nearestBeat(at + dur, o.snap);
+    // 너무 짧아지면 붙이지 않는다 — 그림이 반쯤 넘어가다 잘린다
+    if (Number.isFinite(end) && end - at >= 0.4) dur = end - at;
+  }
+  if (sceneDur !== undefined) {
+    at = Math.max(0, at);
+    dur = Math.min(dur, sceneDur - at);
+  }
+  return { at, dur: Math.max(0, dur) };
+}
+
+/** 구간 진행도 0..1 — 앞은 0(앞 장면 그대로), 뒤는 1(뒤 장면 그대로) */
+export const rawProgress = (t: number, tm: Timing): number => progress(t, tm.at, tm.dur);
+
+/** u 의 [a, b] 부분을 0..1 로 */
+export const seg = (u: number, a: number, b: number, e?: EaseName | Ease): number => {
+  const p = clamp((u - a) / (b - a));
+  return e ? toEase(e)(p) : p;
+};
+
+export const mix = (a: number, b: number, p: number): number => a + (b - a) * p;
+export const mixV = (a: Vec3, b: Vec3, p: number): Vec3 => [mix(a[0], b[0], p), mix(a[1], b[1], p), mix(a[2], b[2], p)];
+export const addV = (a: Vec3, b: Vec3): Vec3 => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+export const scaleV = (a: Vec3, k: number): Vec3 => [a[0] * k, a[1] * k, a[2] * k];
+
+/** 0 과 1 에서 0 인 봉우리 — 양 끝 그림을 정확히 지키면서 가운데에만 얹는 흔들림·비틀기에 */
+export const hump = (u: number): number => Math.sin(Math.PI * clamp(u)) ** 2;
+
+/** 판(높이 h, 중심 c, 바라보는 방향 n)을 화면에 꽉 채우는 카메라 자리 */
+export function fitPose(c: Vec3 = [0, 0, 0], h = 1, n: Vec3 = [0, 0, 1]): Pose {
+  return { pos: addV(c, scaleV(n, FIT * h)), look: [...c] };
+}
+
+/** 카트멀-롬 한 묶음 — 키 사이 속도가 이어진다(키마다 멈추지 않는다). s 는 0..1 */
+export function spline(keys: Vec3[], s: number): Vec3 {
+  if (keys.length === 1) return [...keys[0]];
+  const n = keys.length - 1;
+  const x = clamp(s) * n;
+  const i = Math.min(n - 1, Math.floor(x));
+  const u = x - i;
+  const a = keys[Math.max(0, i - 1)];
+  const b = keys[i];
+  const c = keys[i + 1];
+  const d = keys[Math.min(n, i + 2)];
+  const cr = (p0: number, p1: number, p2: number, p3: number) =>
+    0.5 * (2 * p1 + (-p0 + p2) * u + (2 * p0 - 5 * p1 + 4 * p2 - p3) * u * u + (-p0 + 3 * p1 - 3 * p2 + p3) * u * u * u);
+  return [0, 1, 2].map((j) => cr(a[j], b[j], c[j], d[j])) as Vec3;
+}
+
+/** 시드 난수 [lo, hi) */
+export const rr = (seed: string, i: number, lo: number, hi: number): number => lo + (hi - lo) * rand(seed, i);
+
+// ── 종류별 카메라 리그. 순수 함수라 브라우저 없이 시험한다 ──
+
+export interface Env {
+  aspect: number;
+  seed: string;
+}
+
+export interface DiveState {
+  cam: Pose;
+  /** 앞 장면 화면이 녹아 사라진 정도 0..1 */
+  dissolve: number;
+  /** 카메라가 화면 면을 지나 안쪽 공간에 들어섰는가 */
+  inside: boolean;
+  /** 화면 결 흔들림(지직) 0..1 */
+  glitch: number;
+}
+
+/** 깊이 — 화면 뒤 안쪽 공간에서 뒤 장면 판이 서는 자리. 깊을수록 통로를 나는 빠르기가 커진다 */
+export const DIVE_DEPTH = 18;
+
+export function diveRig(u: number, env: Env): DiveState {
+  const side = rand(env.seed, 1) < 0.5 ? -1 : 1;
+  // 물러났다가 다가가는 길을 한 곡선으로 — 앞뒤 방향이 바뀌는 동안에도 옆으로 쓸고 지나가 카메라가 서는 순간이 없다.
+  // 앞 절반에 몰아 짧게 물러나고 빨리 뚫는다
+  const keys: Vec3[] = [
+    [0, 0, FIT],
+    [side * 0.55, 0.22, FIT * 2.1],
+    [-side * 0.35, 0.16, FIT * 1.8],
+    [-side * 0.1, 0.04, FIT * 0.85],
+    [0, 0, -0.06],
+  ];
+  const looks: Vec3[] = [
+    [0, 0, 0],
+    [side * 0.08, -0.1, 0],
+    [-side * 0.04, -0.06, 0],
+    [0, 0, -0.5],
+    [0, 0, -1],
+  ];
+  let pos: Vec3;
+  let look: Vec3;
+  let barrel = 0;
+  if (u < 0.5) {
+    const x = u / 0.5;
+    // 처음부터 움직이며(0 이 아닌 출발 속도) 점점 빨라져 화면을 뚫는다
+    const s = 0.35 * x + 0.65 * x * x;
+    pos = spline(keys, s);
+    look = spline(looks, s);
+  } else {
+    const fly = seg(u, 0.5, 1, "outCubic");
+    pos = mixV([0, 0, -0.06], [0, 0, -DIVE_DEPTH + FIT], fly);
+    look = mixV([0, 0, -1], [0, 0, -DIVE_DEPTH], Math.min(1, fly * 1.6));
+    // 통로를 나는 동안 한 바퀴 통째로 돈다
+    barrel = side * 2 * Math.PI * seg(u, 0.54, 0.9, "inOutCubic");
+  }
+  const roll = side * -0.14 * hump(seg(u, 0.28, 0.9)) + barrel;
+  return {
+    cam: { pos, look, roll: u <= 0 || u >= 1 ? 0 : roll },
+    dissolve: seg(u, 0.33, 0.47, "inOutQuad"),
+    inside: pos[2] < 0.04,
+    glitch: hump(seg(u, 0.2, 0.36)),
+  };
+}
+
+export interface PortalState {
+  cam: Pose;
+  /** 구멍 반지름 — 화면 높이 1 기준 */
+  radius: number;
+  center: [number, number];
+}
+
+export const PORTAL_DEPTH = 8;
+
+export function portalRig(u: number, env: Env): PortalState {
+  const cx = rr(env.seed, 2, -0.12, 0.12) * env.aspect;
+  const cy = rr(env.seed, 3, -0.08, 0.08);
+  const far = Math.hypot(env.aspect / 2 + Math.abs(cx), 0.5 + Math.abs(cy));
+  const open = seg(u, 0, 0.42, "inOutCubic");
+  // 처음엔 작게 열려 안을 보여 주고(0.18), 그다음 화면 밖까지 벌어진다
+  const radius = mix(0, 0.2, seg(u, 0, 0.16, "outBack")) + (far - 0.2 + 0.05) * seg(u, 0.16, 0.42, "inCubic") * (open > 0 ? 1 : 0);
+  const travel = seg(u, 0.18, 1, "inOutCubic");
+  const z = mix(FIT, -PORTAL_DEPTH + FIT, travel);
+  // 구멍 쪽으로 살짝 끌려갔다가 터널 축으로 돌아온다
+  const pullToHole = hump(seg(u, 0, 0.6)) * 0.7;
+  const pos: Vec3 = [cx * pullToHole * 0.6, cy * pullToHole * 0.6, z];
+  const look: Vec3 = [cx * pullToHole * 0.4, cy * pullToHole * 0.4, z - 1];
+  const side = rand(env.seed, 4) < 0.5 ? -1 : 1;
+  return { cam: { pos, look, roll: side * 0.35 * hump(seg(u, 0.2, 1)) }, radius: u <= 0 ? 0 : u >= 1 ? far + 0.05 : radius, center: [cx, cy] };
+}
+
+export interface CardSlot {
+  pos: Vec3;
+  /** y 축 회전(라디안) */
+  yaw: number;
+  /** 0 = 앞 장면, 1 = 뒤 장면, 2.. = 꾸밈 판(앞·뒤 그림을 흐리게) */
+  img: number;
+  scale: number;
+}
+
+export function cardSlots(env: Env): CardSlot[] {
+  const side = rand(env.seed, 5) < 0.5 ? -1 : 1;
+  const slots: CardSlot[] = [
+    { pos: [0, 0, 0], yaw: 0, img: 0, scale: 1 },
+    { pos: [side * 2.7, 0.35, -2.6], yaw: -side * 0.55, img: 1, scale: 1 },
+  ];
+  const ring = 9;
+  for (let i = 0; i < ring; i++) {
+    const a = (i / ring) * Math.PI * 2 + rr(env.seed, 10 + i, -0.3, 0.3);
+    const r = rr(env.seed, 30 + i, 2.6, 4.6);
+    slots.push({
+      pos: [Math.cos(a) * r * 1.1 + side * 1.2, rr(env.seed, 50 + i, -1.4, 1.6), -1.4 + Math.sin(a) * r * 0.9 - 1.6],
+      yaw: rr(env.seed, 70 + i, -0.7, 0.7),
+      img: 2 + (i % 2),
+      scale: rr(env.seed, 90 + i, 0.45, 0.85),
+    });
+  }
+  // 꾸밈 판이 처음·끝 카메라와 주인공 판 사이에 끼면 경계 프레임이 가려진다 — 주인공 판 뒤로 민다
+  const ends = [fitPose(slots[0].pos), fitPose(slots[1].pos, slots[1].scale, slotNormal(slots[1]))];
+  for (const d of slots.slice(2)) {
+    for (const pose of ends) {
+      const reach = FIT + 0.4;
+      const z = depthIn(pose, d.pos, env.aspect, (d.scale * env.aspect) / 2 + 0.2);
+      if (z !== null && z < reach) d.pos = addV(d.pos, scaleV(forward(pose), reach + 1 - z));
+    }
+  }
+  return slots;
+}
+
+const sub = (a: Vec3, b: Vec3): Vec3 => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const dot = (a: Vec3, b: Vec3): number => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+const cross = (a: Vec3, b: Vec3): Vec3 => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+const norm = (a: Vec3): Vec3 => scaleV(a, 1 / (Math.hypot(...a) || 1));
+const forward = (p: Pose): Vec3 => norm(sub(p.look, p.pos));
+
+/** 점이 카메라 시야(가장자리 pad 만큼 넓혀서) 안에 있으면 시선 방향 깊이, 아니면 null */
+export function depthIn(pose: Pose, p: Vec3, aspect: number, pad = 0): number | null {
+  const f = forward(pose);
+  const r = norm(cross(f, [0, 1, 0]));
+  const up = cross(r, f);
+  const d = sub(p, pose.pos);
+  const z = dot(d, f);
+  if (z <= -pad) return null;
+  const k = Math.tan((FOV * Math.PI) / 360) * Math.max(z, 0);
+  return Math.abs(dot(d, r)) < k * aspect + pad && Math.abs(dot(d, up)) < k + pad ? z : null;
+}
+
+/** 판 하나가 바라보는 방향(앞면 법선) */
+export const slotNormal = (s: CardSlot): Vec3 => [Math.sin(s.yaw), 0, Math.cos(s.yaw)];
+
+export function cardsRig(u: number, env: Env): { cam: Pose } {
+  const [a, b] = cardSlots(env);
+  const start = fitPose(a.pos);
+  const end = fitPose(b.pos, b.scale, slotNormal(b));
+  const mid1: Vec3 = [b.pos[0] * 0.15, 0.55, FIT + 2.4];
+  const mid2: Vec3 = addV(b.pos, addV(scaleV(slotNormal(b), FIT + 2.2), [0, 0.35, 0]));
+  const s = toEase("inOutCubic")(clamp(u));
+  const pos = spline([start.pos, mid1, mid2, end.pos], s);
+  // 시선은 앞 판 → 두 판 사이 → 뒤 판으로 넘어간다
+  const between = mixV(a.pos, b.pos, 0.5);
+  const look = spline([start.look, mixV(a.pos, between, 0.6), mixV(between, b.pos, 0.8), end.look], toEase("inOutQuad")(clamp(u)));
+  return { cam: { pos, look } };
+}
+
+export interface Tile {
+  /** 칸 중심(화면 좌표, 높이 1 기준) */
+  c: [number, number];
+  /** 출발 지연 0..1 */
+  delay: number;
+  /** 날아가는 방향·회전축·회전량 */
+  vel: Vec3;
+  axis: Vec3;
+  spin: number;
+}
+
+export function tileGrid(env: Env, rows = 9): { cols: number; rows: number; tw: number; th: number } {
+  const cols = Math.max(2, Math.round(rows * env.aspect));
+  return { cols, rows, tw: env.aspect / cols, th: 1 / rows };
+}
+
+/** 쪼개질 칸들 — side 0 은 흩어지는 앞 장면, 1 은 조립되는 뒤 장면 */
+export function tiles(env: Env, side: 0 | 1, rows = 9): Tile[] {
+  const { cols, tw, th } = tileGrid(env, rows);
+  const seed = `${env.seed}:${side}`;
+  const ix = rr(env.seed, 7, -0.2, 0.2) * env.aspect;
+  const iy = rr(env.seed, 8, -0.15, 0.15);
+  const far = Math.hypot(env.aspect / 2 + Math.abs(ix), 0.5 + Math.abs(iy));
+  const out: Tile[] = [];
+  for (let r = 0; r < rows; r++) {
+    for (let c = 0; c < cols; c++) {
+      const i = r * cols + c;
+      const x = -env.aspect / 2 + (c + 0.5) * tw;
+      const y = -0.5 + (r + 0.5) * th;
+      const dx = x - ix;
+      const dy = y - iy;
+      const d = Math.hypot(dx, dy) / far;
+      // 앞 장면은 맞은 자리부터 터지고, 뒤 장면은 가장자리부터 모여 가운데가 마지막에 닫힌다
+      const delay = side === 0 ? d * 0.55 + rr(seed, i, 0, 0.12) : (1 - d) * 0.5 + rr(seed, i, 0, 0.12);
+      const len = Math.hypot(dx, dy) || 1;
+      const push = rr(seed, 1000 + i, 0.8, 2.2);
+      const vel: Vec3 = [(dx / len) * push + rr(seed, 2000 + i, -0.4, 0.4), (dy / len) * push + rr(seed, 3000 + i, -0.3, 0.6), side === 0 ? rr(seed, 4000 + i, 0.6, 2.4) : rr(seed, 4000 + i, -4, -1.5)];
+      const ax: Vec3 = [rr(seed, 5000 + i, -1, 1), rr(seed, 6000 + i, -1, 1), rr(seed, 7000 + i, -0.4, 0.4)];
+      const al = Math.hypot(...ax) || 1;
+      out.push({ c: [x, y], delay, vel, axis: [ax[0] / al, ax[1] / al, ax[2] / al], spin: rr(seed, 8000 + i, 1.5, 4.5) * (rand(seed, 9000 + i) < 0.5 ? -1 : 1) });
+    }
+  }
+  return out;
+}
+
+/** 칸 하나의 진행 — 0 이면 제자리. 흩어짐은 u 가 지날수록, 조립은 u=1 에서 정확히 0 */
+export function tileAmount(u: number, tile: Tile, side: 0 | 1): number {
+  if (side === 0) return seg(u, tile.delay * 0.6, tile.delay * 0.6 + 0.45, "inQuad");
+  return 1 - seg(u, 0.35 + tile.delay * 0.45, 0.35 + tile.delay * 0.45 + 0.2, "outCubic");
+}
+
+export function shatterRig(u: number, env: Env): { cam: Pose } {
+  const side = rand(env.seed, 9) < 0.5 ? -1 : 1;
+  const k = hump(u);
+  return { cam: { pos: [side * 0.55 * k, 0.12 * k, FIT + 0.9 * k], look: [side * -0.1 * k, 0, 0], roll: side * 0.05 * k } };
+}
+
+export interface ZoomOutState {
+  cam: Pose;
+  /** 창(앞 장면)의 중심·높이 — 뒤 장면 판 위 좌표 */
+  win: { c: Vec3; h: number };
+  /** 창이 뒤 장면에서 떠 있는 높이 */
+  lift: number;
+  /** 창 테두리·그림자 보이기 0..1 */
+  chrome: number;
+  /** 창 그림이 뒤 장면의 그 자리 그림으로 넘어간 정도 */
+  blend: number;
+  /** 뒤 장면을 어둡게 누르는 정도 */
+  dim: number;
+}
+
+export interface WindowRect {
+  /** 뒤 장면 안 창 중심(0..1, 왼쪽 위가 0) */
+  x: number;
+  y: number;
+  /** 창 높이(뒤 장면 높이 대비 0..1). 창 비율은 화면과 같다 */
+  h: number;
+}
+
+export function zoomOutRig(u: number, env: Env, win: WindowRect): ZoomOutState {
+  const c: Vec3 = [(win.x - 0.5) * env.aspect, 0.5 - win.y, 0];
+  const h = win.h;
+  const lift = 0.5 * (1 - seg(u, 0.55, 0.92, "inOutCubic"));
+  const wc: Vec3 = [c[0], c[1], lift];
+  const start = fitPose(wc, h);
+  const end = fitPose([0, 0, 0]);
+  const side = rand(env.seed, 11) < 0.5 ? -1 : 1;
+  const s = toEase("inOutCubic")(clamp(u));
+  const midA: Vec3 = [c[0] + side * 0.35, c[1] + 0.2, lift + FIT * h * 2.4];
+  const midB: Vec3 = [side * 0.7, 0.35, FIT * 1.5];
+  const pos = spline([start.pos, midA, midB, end.pos], s);
+  const look = mixV(wc, [0, 0, 0], toEase("inOutQuad")(seg(u, 0.15, 1)));
+  return {
+    cam: { pos, look },
+    win: { c: wc, h },
+    lift,
+    chrome: hump(seg(u, 0, 0.9)) * (u < 0.85 ? 1 : 1 - seg(u, 0.85, 0.95)),
+    blend: seg(u, 0.78, 0.97, "inOutQuad"),
+    dim: 0.45 * hump(seg(u, 0, 1)),
+  };
+}
+
+export type FoldStyle = "accordion" | "roll";
+
+export interface FoldState {
+  cam: Pose;
+  /** 아코디언: 접힌 각(라디안). 말기: 말린 선의 높이 */
+  amount: number;
+  /** 접힌 묶음이 옆으로 빠지는 거리 */
+  slide: number;
+  /** 앞 장면이 남아 보이는 정도 */
+  alpha: number;
+}
+
+export function foldRig(u: number, env: Env, style: FoldStyle): FoldState {
+  const side = rand(env.seed, 12) < 0.5 ? -1 : 1;
+  const k = hump(u);
+  const cam: Pose = { pos: [side * 0.5 * k, -0.18 * k, FIT + 0.75 * k], look: [side * -0.12 * k, 0, 0] };
+  if (style === "roll") {
+    return { cam, amount: mix(-0.62, 0.85, seg(u, 0, 0.9, "inOutCubic")), slide: 0, alpha: 1 - seg(u, 0.88, 0.98) };
+  }
+  return {
+    cam,
+    amount: (Math.PI / 2) * 0.94 * seg(u, 0, 0.62, "inOutCubic"),
+    slide: seg(u, 0.55, 0.95, "inCubic") * (env.aspect + 0.6),
+    alpha: 1 - seg(u, 0.85, 0.96),
+  };
+}
+
+// ── 연속 다이브: 화면 속 화면을 끊김 없이 뚫고 들어간다 ──
+
+/** 이어지는 화면 사이 깊이 */
+export const CHAIN_GAP = 6;
+
+export interface ChainOpts {
+  /** 화면 k 가 꽉 차는 시각(장면 안 초) — 늘어나는 순서 */
+  arrivals: number[];
+  /** 0 이면 같은 빠르기로 흘러가고, 1 이면 화면마다 멈췄다 간다. 기본 0.35 */
+  settle?: number;
+  gap?: number;
+}
+
+export interface ChainState {
+  cam: Pose;
+  /** 카메라가 지금 지나는(또는 머문) 화면 번호 */
+  index: number;
+  /** 화면마다 녹은 정도 0..1. 카메라가 지나간 화면은 1 */
+  dissolve: number[];
+}
+
+/** 화면 k 가 꽉 차는 카메라 z 를 지나는 단조 에르미트 곡선 — 도착 사이 속도가 이어진다 */
+export function chainZ(t: number, o: ChainOpts): number {
+  const a = o.arrivals;
+  const gap = o.gap ?? CHAIN_GAP;
+  const Z = (k: number) => -k * gap + FIT;
+  const n = a.length;
+  if (n === 1 || t <= a[0]) return Z(0);
+  if (t >= a[n - 1]) return Z(n - 1);
+  let i = 0;
+  while (i < n - 2 && t >= a[i + 1]) i++;
+  const settle = clamp(o.settle ?? 0.35);
+  const secant = (k: number) => (Z(k + 1) - Z(k)) / (a[k + 1] - a[k]);
+  // 양 끝은 멈춘 채 시작·끝(앞·뒤 장면과 이어진다). 가운데는 이웃 기울기, 단조를 지키게 세 배 안으로
+  const tangent = (k: number) => {
+    if (k === 0 || k === n - 1) return 0;
+    const m = ((1 - settle) * (Z(k + 1) - Z(k - 1))) / (a[k + 1] - a[k - 1]);
+    const lim = 3 * Math.min(Math.abs(secant(k - 1)), Math.abs(secant(k)));
+    return Math.sign(m) * Math.min(Math.abs(m), lim);
+  };
+  const hseg = a[i + 1] - a[i];
+  const s = (t - a[i]) / hseg;
+  const s2 = s * s;
+  const s3 = s2 * s;
+  return (2 * s3 - 3 * s2 + 1) * Z(i) + (s3 - 2 * s2 + s) * hseg * tangent(i) + (-2 * s3 + 3 * s2) * Z(i + 1) + (s3 - s2) * hseg * tangent(i + 1);
+}
+
+export function chainRig(t: number, env: Env, o: ChainOpts): ChainState {
+  const gap = o.gap ?? CHAIN_GAP;
+  const a = o.arrivals;
+  const z = chainZ(t, o);
+  const n = a.length;
+  let index = 0;
+  while (index < n - 1 && t >= a[index + 1]) index++;
+  const dissolve = a.map((_, k) => {
+    if (k === n - 1) return 0;
+    const d = z - -k * gap;
+    // 꽉 찬 순간(d = FIT)은 반올림 찌꺼기 없이 정확히 0 — 그 프레임이 화면 그림 그대로여야 한다
+    return d <= 0 ? 1 : d >= FIT - 1e-9 ? 0 : 1 - clamp((d - 0.25) / (FIT - 0.25));
+  });
+  // 도착 사이에만 살짝 기운다 — 도착 순간은 0 이라 화면이 똑바로 찬다
+  let roll = 0;
+  if (t > a[0] && t < a[n - 1]) {
+    const s = (t - a[index]) / (a[Math.min(n - 1, index + 1)] - a[index] || 1);
+    roll = (rand(env.seed, 20 + index) < 0.5 ? -1 : 1) * 0.16 * hump(s);
+  }
+  return { cam: { pos: [0, 0, z], look: [0, 0, z - 1], roll }, index, dissolve };
+}
+
+/** 박자 격자에서 n 번의 도착 — 첫 도착은 from, 그다음은 격자의 다음 칸마다 */
+export function arrivalsOn(beats: Beats, grid: BeatGrid, from: number, n: number): number[] {
+  const out = [from];
+  while (out.length < n) {
+    const prev = out[out.length - 1];
+    let next = beats.next(prev + 1e-3, grid);
+    if (!Number.isFinite(next)) next = prev + (out.length > 1 ? prev - out[out.length - 2] : 0.5);
+    out.push(next);
+  }
+  return out;
+}
+
+// ── 휙 넘기기: 제자리에서 90° 를 휙 돈다 ──
+
+/**
+ * 반대로 살짝 감았다가(예비 동작) 확 돌고, 4.5% 넘쳤다가 되돌아와 선다. 도는 동안 몸을 기울이고 화각을 넓힌다.
+ * 양 끝은 기울기·화각 0 — 앞 판·뒤 판이 꽉 찬다
+ */
+export function whipRig(u: number, env: Env): { cam: Pose; side: 1 | -1 } {
+  const side = rand(env.seed, 13) < 0.5 ? -1 : 1;
+  const edge = u <= 0 || u >= 1;
+  const wind = -0.045 * Math.sin(Math.PI * seg(u, 0, 0.24));
+  const turn = u < 0.8 ? 1.045 * seg(u, 0.14, 0.8, "inOutQuart") : 1 + 0.045 * (0.5 + 0.5 * Math.cos(Math.PI * seg(u, 0.8, 1)));
+  const p = u <= 0 ? 0 : u >= 1 ? 1 : turn + wind;
+  const yaw = (side * Math.PI * p) / 2;
+  return {
+    side,
+    cam: {
+      pos: [0, 0, 0],
+      look: [-Math.sin(yaw), 0, -Math.cos(yaw)],
+      roll: edge ? 0 : side * -0.22 * hump(seg(u, 0.14, 0.86)),
+      fov: edge ? 0 : 14 * hump(seg(u, 0.18, 0.8)),
+    },
+  };
+}

package/packages/motion/src/transition3d/shatter.ts

@@ -0,0 +1,101 @@
+import * as THREE from "three";
+import { clamp } from "@kasaframe/core";
+import { hump, rr, seg, shatterRig, tileAmount, tileGrid, tiles, type Tile } from "./rig.ts";
+import { aim, disposeTree, imageMaterial, raw, sky, type Kit } from "./world.ts";
+
+// 칸 꼭짓점을 칸 번호의 같은 식으로 셈한다 — 이웃 칸의 맞닿은 모서리가 비트까지 같아야 조립된 그림에 금이 안 간다
+function tileGeometry(aspect: number, cols: number, rows: number, c: number, r: number): THREE.BufferGeometry {
+  const x = (i: number) => -aspect / 2 + (aspect * i) / cols;
+  const y = (j: number) => -0.5 + j / rows;
+  const g = new THREE.BufferGeometry();
+  g.setAttribute("position", new THREE.BufferAttribute(new Float32Array([x(c), y(r), 0, x(c + 1), y(r), 0, x(c + 1), y(r + 1), 0, x(c), y(r + 1), 0]), 3));
+  g.setAttribute("uv", new THREE.BufferAttribute(new Float32Array([c / cols, r / rows, (c + 1) / cols, r / rows, (c + 1) / cols, (r + 1) / rows, c / cols, (r + 1) / rows]), 2));
+  g.setIndex([0, 1, 2, 0, 2, 3]);
+  return g;
+}
+
+const ROWS = 9;
+
+export function shatter(k: Kit) {
+  const { aspect, pal, seed } = k;
+  const env = { aspect, seed };
+  const scene = new THREE.Scene();
+  scene.add(sky({ top: pal.deep, bottom: "#020308", glow: pal.accent, dir: [0, 0, -1], amt: 0.6, pow: 8 }));
+  const { cols } = tileGrid(env, ROWS);
+  const sides: { tile: Tile; mesh: THREE.Mesh; c: THREE.Vector3 }[][] = [[], []];
+  for (const side of [0, 1] as const) {
+    const mat = imageMaterial(side === 0 ? k.from.texture : k.to.texture, { double: true, back: side === 0 ? pal.accent : pal.glow });
+    tiles(env, side, ROWS).forEach((tile, i) => {
+      const mesh = new THREE.Mesh(tileGeometry(aspect, cols, ROWS, i % cols, Math.floor(i / cols)), mat);
+      mesh.matrixAutoUpdate = false;
+      scene.add(mesh);
+      sides[side].push({ tile, mesh, c: new THREE.Vector3(tile.c[0], tile.c[1], 0) });
+    });
+  }
+
+  // 맞은 자리에서 튀는 빛 조각
+  const n = 260;
+  const ix = rr(seed, 7, -0.2, 0.2) * aspect;
+  const iy = rr(seed, 8, -0.15, 0.15);
+  const dirs = Array.from({ length: n }, (_, i) => {
+    const a = rr(seed, 3100 + i, 0, Math.PI * 2);
+    const sp = rr(seed, 3400 + i, 0.4, 2.2);
+    return [Math.cos(a) * sp, Math.sin(a) * sp, rr(seed, 3700 + i, -0.6, 1.2)];
+  });
+  const sparkPos = new Float32Array(n * 3);
+  const sparkGeo = new THREE.BufferGeometry();
+  sparkGeo.setAttribute("position", new THREE.BufferAttribute(sparkPos, 3));
+  const sparkMat = new THREE.PointsMaterial({ color: raw(pal.glow), size: 0.018, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending });
+  const sparks = new THREE.Points(sparkGeo, sparkMat);
+  scene.add(sparks);
+
+  const m = new THREE.Matrix4();
+  const q = new THREE.Quaternion();
+  const axis = new THREE.Vector3();
+  const pos = new THREE.Vector3();
+  const scl = new THREE.Vector3();
+  const back = new THREE.Matrix4();
+  return {
+    frame(u: number) {
+      aim(k.cam, shatterRig(u, env).cam);
+      for (const side of [0, 1] as const) {
+        for (const { tile, mesh, c } of sides[side]) {
+          const a = tileAmount(u, tile, side);
+          if (a === 0) {
+            mesh.visible = true;
+            mesh.matrix.identity();
+          } else if (side === 0 && a >= 1) {
+            mesh.visible = false;
+          } else {
+            mesh.visible = true;
+            const travel = side === 0 ? a * 0.8 + a * a * 1.6 : a * 1.8;
+            pos.set(c.x + tile.vel[0] * travel, c.y + tile.vel[1] * travel, tile.vel[2] * travel);
+            q.setFromAxisAngle(axis.set(...tile.axis), tile.spin * a * Math.PI * 0.7);
+            const s = side === 0 ? 1 - 0.75 * a : 1 - 0.3 * a;
+            scl.set(s, s, s);
+            m.compose(pos, q, scl);
+            back.makeTranslation(-c.x, -c.y, 0);
+            mesh.matrix.multiplyMatrices(m, back);
+          }
+          mesh.matrixWorldNeedsUpdate = true;
+        }
+      }
+      const burst = seg(u, 0.02, 0.75);
+      for (let i = 0; i < n; i++) {
+        const d = dirs[i];
+        const f = burst * (1.2 + burst);
+        sparkPos[i * 3] = ix + d[0] * f;
+        sparkPos[i * 3 + 1] = iy + d[1] * f - 0.4 * burst * burst;
+        sparkPos[i * 3 + 2] = 0.02 + d[2] * f;
+      }
+      sparkGeo.attributes.position.needsUpdate = true;
+      sparkMat.opacity = clamp(hump(seg(u, 0, 0.8)) * 1.5);
+      sparks.visible = u > 0 && u < 0.8;
+      k.renderer.clear(true, true, true);
+      k.renderer.render(scene, k.cam);
+    },
+    dispose() {
+      disposeTree(scene);
+    },
+  };
+}

package/packages/motion/src/transition3d/whip.ts

@@ -0,0 +1,65 @@
+import * as THREE from "three";
+import { FIT, rr, whipRig } from "./rig.ts";
+import { aim, disposeTree, dust, frameRing, imageMaterial, raw, sky, type Kit, type KindRun } from "./world.ts";
+
+/**
+ * 휙 넘기기 — 카메라는 제자리에서 돌고, 앞 판은 정면·뒤 판은 옆(90°)에 선다. 둘레에 판과 빛줄을 둘러
+ * 도는 동안 화면이 쓸려 지나간다(렌더 모션 블러를 켜면 줄무늬로 번진다)
+ */
+export function whip(k: Kit): KindRun {
+  const { aspect, pal, seed } = k;
+  const env = { aspect, seed };
+  const side = whipRig(0, env).side;
+  const scene = new THREE.Scene();
+  scene.add(sky({ top: pal.deep, bottom: "#03050b", glow: pal.accent, dir: [-side, 0, -1], amt: 0.5, pow: 3 }));
+  const at = (yaw: number, r: number, y = 0): THREE.Vector3 => new THREE.Vector3(-Math.sin(yaw) * r, y, -Math.cos(yaw) * r);
+
+  const place = (mesh: THREE.Object3D, yaw: number, r: number, y = 0) => {
+    mesh.position.copy(at(yaw, r, y));
+    mesh.rotation.y = yaw;
+    scene.add(mesh);
+  };
+  place(new THREE.Mesh(new THREE.PlaneGeometry(aspect, 1), imageMaterial(k.from.texture)), 0, FIT);
+  place(new THREE.Mesh(new THREE.PlaneGeometry(aspect, 1), imageMaterial(k.to.texture)), (side * Math.PI) / 2, FIT);
+
+  // 사이를 메우는 판 — 앞·뒤 그림을 흐리게 눌러 쓴다. 정면·옆 판 자리(꽉 찬 시야)는 비운다
+  for (let i = 0; i < 7; i++) {
+    const f = (i + 0.5) / 7;
+    const yaw = side * (Math.PI / 2) * (0.12 + f * 0.76) + rr(seed, 200 + i, -0.05, 0.05);
+    const s = rr(seed, 220 + i, 0.45, 0.8);
+    const mat = imageMaterial((i % 2 ? k.from : k.to).soft(), { double: true, back: pal.deep });
+    mat.uniforms.bias.value = 3;
+    mat.uniforms.dim.value = 0.35;
+    const g = new THREE.Group();
+    g.add(new THREE.Mesh(new THREE.PlaneGeometry(aspect * s, s), mat));
+    g.add(new THREE.Mesh(frameRing(aspect * s, s, 0.008), new THREE.MeshBasicMaterial({ color: raw(pal.glow), transparent: true, opacity: 0.6, blending: THREE.AdditiveBlending, depthWrite: false })));
+    place(g, yaw, FIT * rr(seed, 240 + i, 1.4, 2.4), rr(seed, 260 + i, -0.5, 0.5));
+  }
+  // 빛줄 — 수평으로 둘러 선 얇은 띠. 돌 때 시야를 가로질러 지나간다
+  for (let i = 0; i < 18; i++) {
+    const yaw = side * (Math.PI / 2) * rr(seed, 300 + i, -0.1, 1.1);
+    const bar = new THREE.Mesh(
+      new THREE.PlaneGeometry(rr(seed, 320 + i, 0.3, 1.2), rr(seed, 340 + i, 0.006, 0.02)),
+      new THREE.MeshBasicMaterial({ color: raw(i % 3 ? pal.accent : pal.glow), transparent: true, opacity: 0.8, blending: THREE.AdditiveBlending, depthWrite: false }),
+    );
+    place(bar, yaw, FIT * rr(seed, 360 + i, 2.6, 4.5), rr(seed, 380 + i, -1.2, 1.2));
+  }
+  const n = 500;
+  const pts = new Float32Array(n * 3);
+  for (let i = 0; i < n; i++) {
+    const p = at(rr(seed, 400 + i, -Math.PI, Math.PI), FIT * rr(seed, 1400 + i, 2.5, 6), rr(seed, 2400 + i, -2, 2));
+    pts.set([p.x, p.y, p.z], i * 3);
+  }
+  scene.add(dust(pts, pal.glow, 0.02));
+
+  return {
+    frame(u) {
+      aim(k.cam, whipRig(u, env).cam);
+      k.renderer.clear(true, true, true);
+      k.renderer.render(scene, k.cam);
+    },
+    dispose() {
+      disposeTree(scene);
+    },
+  };
+}