kasaframe 0.0.0-stage → 0.1.3

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

@@ -0,0 +1,600 @@
+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" | "rise" | "land" | `gl:${string}` | `smooth:${string}`;
+
+export const TRANSITIONS_3D = ["dive", "portal", "cards", "shatter", "zoomOut", "fold", "diveChain", "whip", "rise", "land"] 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, rise: 1.8, land: 1.6 };
+
+/** 혼자 쓸 때 기본 길이 — 셰이더 전환(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));
+    // 통로를 나는 동안 한 바퀴 통째로 돈다 — 끝 판이 화면의 25% 를 넘기 전(u 0.78)에 다 돈다. 커진 밝은 판이 어두운 통로 위에서 돌면
+    // 칸마다 밝음·어둠이 빠르게 오가 섬광 검사(frame.flash)에 걸린다
+    barrel = side * 2 * Math.PI * seg(u, 0.52, 0.78, "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 },
+    // 화면은 가장 멀리 물러난 동안 통로로 녹는다 — 다시 다가가 화면이 시야를 채울 때 밝은 앞 장면이 한 번 더 차오르면
+    // 밝음·어둠이 한 전환 안에서 두 번 오가 섬광 검사(frame.flash)에 걸린다
+    dissolve: seg(u, 0.18, 0.32, "inOutQuad"),
+    inside: pos[2] < 0.04,
+    glitch: hump(seg(u, 0.08, 0.26)),
+  };
+}
+
+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° 를 휙 돈다 ──
+
+/**
+ * 반대로 살짝 감았다가(예비 동작) 확 돌고, 1.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));
+  // 넘침은 1.5% — 밝은 판 가장자리가 되돌아오며 칸을 한 번 더 쓸면 섬광 검사(frame.flash)가 꺾임을 두 번 더 센다
+  const turn = u < 0.8 ? 1.015 * seg(u, 0.14, 0.8, "inOutQuart") : 1 + 0.015 * (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)),
+    },
+  };
+}
+
+// ── 공간 잇기: 2D 와 3D 사이를 같은 공간으로 ──
+
+/** 판 위 주인공 상자 — 판 좌표(가로 aspect·세로 1, 가운데가 0, 위가 +). 앞 장면이 stage.hero 로 짚은 요소를 잰다 */
+export interface HeroBox {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** 주인공 블록이 서는 높이 — 2D 상자가 클수록 높게, 화면 높이의 1/3 안에서 */
+export const liftOf = (hero: HeroBox): number => Math.min(0.22, 0.08 + 0.45 * Math.min(hero.w, hero.h));
+
+/** rise — 뒤 장면 벽이 서는 깊이. 누운 앞 판(깊이 1) 끝보다 멀어 끝 구도에서 블록이 카메라 뒤로 빠진다 */
+export const RISE_WALL = 1 + FIT + 0.35;
+
+export interface RiseState {
+  cam: Pose;
+  /** 앞 판이 아래 가장자리를 축으로 뒤로 누운 각(0 → -π/2) — 판의 법선이 위를 보게 되어 블록이 바로 선다 */
+  lie: number;
+  /** 주인공 블록 높이(판 법선 방향) */
+  lift: number;
+}
+
+/**
+ * 2D → 3D. 처음엔 앞 장면 판이 화면을 꽉 채우고(경계 프레임 그대로), 주인공 상자가 같은 화면 자리에서 블록으로 솟는다.
+ * 판이 아래 가장자리를 축으로 뒤로 누워 바닥이 되면 블록은 그 위에 선 물체가 되고, 카메라가 깊이로 기울어 들어가
+ * 블록 위를 지나 바닥 끝 벽(뒤 장면 첫 화면)을 정면으로 꽉 채우며 선다
+ */
+export function riseRig(u: number, env: Env, hero: HeroBox): RiseState {
+  const hx = hero.x;
+  const near = -(hero.y + 0.5);
+  // 블록 위를 높이 지난다 — 낮게 스치면 블록 옆면이 화면을 크게 쓸어 섬광 검사(frame.flash)에 걸린다
+  const keys: Vec3[] = [
+    [0, 0, FIT],
+    [hx * 0.2, 0.16, FIT * 0.85],
+    [hx * 0.1, 0.52, near - 0.35],
+    [0, 0, -RISE_WALL + FIT],
+  ];
+  const looks: Vec3[] = [
+    [0, 0, 0],
+    [hx * 0.45, -0.32, near * 0.7],
+    [0, -0.1, -RISE_WALL],
+    [0, 0, -RISE_WALL],
+  ];
+  const sway = rand(env.seed, 70) < 0.5 ? -1 : 1;
+  const edge = u <= 0 || u >= 1;
+  return {
+    cam: { pos: spline(keys, u), look: spline(looks, u), roll: edge ? 0 : sway * 0.06 * hump(seg(u, 0.15, 0.9)) },
+    lie: (-Math.PI / 2) * seg(u, 0.1, 0.6, "inOutCubic"),
+    lift: u <= 0 ? 0 : liftOf(hero) * seg(u, 0, 0.42, "outCubic"),
+  };
+}
+
+/** land — 뒤 장면 판의 크기와 자리. 작게 두어야 카메라가 다가가며(뒤로 물러나지 않고) 판이 화면을 꽉 채운다 */
+export const LAND_CARD = 0.4;
+export const LAND_Z = 0.3;
+
+export interface LandState {
+  cam: Pose;
+  /** 뒤 장면 판이 누운 각(-π/2 누움 → 0 섰다) — 아래 가장자리가 축 */
+  lie: number;
+  /** 뒤 장면 주인공 블록 높이 — 판이 서며 평면으로 내려앉는다 */
+  lift: number;
+  /** 뒤 장면 판의 불투명도 — 처음 프레임은 앞 장면 그대로 */
+  alpha: number;
+}
+
+/**
+ * 3D → 2D. 앞 장면(3D 샷 마지막 화면)이 꽉 찬 채 시작해, 그 앞 공간에 누워 있던 판 하나가 일어서고 카메라가 그 판으로 다가간다.
+ * 판 위 주인공 블록은 평면으로 내려앉고, 판이 화면을 정면으로 꽉 채운 순간이 뒤 장면 첫 화면이다
+ */
+export function landRig(u: number, env: Env, hero: HeroBox): LandState {
+  const z = LAND_Z;
+  const keys: Vec3[] = [
+    [0, 0, FIT],
+    [hero.x * LAND_CARD * 0.2, 0.08, FIT * 0.85],
+    [0, 0.04, z + FIT * LAND_CARD * 1.5],
+    [0, 0, z + FIT * LAND_CARD],
+  ];
+  const looks: Vec3[] = [
+    [0, 0, 0],
+    [0, -0.12, z - 0.2],
+    [0, -0.02, z],
+    [0, 0, z],
+  ];
+  return {
+    cam: { pos: spline(keys, u), look: spline(looks, u) },
+    lie: (-Math.PI / 2) * (1 - seg(u, 0.12, 0.85, "inOutCubic")),
+    lift: u >= 1 ? 0 : liftOf(hero) * LAND_CARD * (1 - seg(u, 0.45, 0.95, "inOutCubic")),
+    alpha: seg(u, 0, 0.14),
+  };
+}