kasaframe 0.0.0-stage → 0.1.3

package/packages/motion/README.md

@@ -0,0 +1,153 @@
+# @kasaframe/motion · @kasaframe/core — 움직임 사용서
+
+모든 부품은 `(t, opts)` 의 순수 함수다. **같은 t 면 같은 값** — 앞 프레임 상태가 없어서 아무 시각으로 건너뛰어도, 탭을 나눠 찍어도 같은 그림이 나온다. t 는 **장면 안 초**(장면 시작이 0). 글을 돌려주는 부품은 무엇이 들어와도 `undefined`·`NaN` 을 찍지 않는다.
+
+## 장면에서 쓰는 꼴
+
+```ts
+import { applyStyle, combine, type SceneCtx } from "@kasaframe/core";
+import { enter, typeText, dropBurst, beatPulse } from "@kasaframe/motion";
+
+export default {
+  build(root: HTMLElement, ctx: SceneCtx) {
+    const title = document.createElement("div");
+    root.append(title);
+    return (t: number) => {
+      title.textContent = typeText("선택한 줄을 보냅니다", t, { at: 0.3 }).text;
+      applyStyle(title, enter("rise", t, { at: 0.2, scene: ctx.id }));
+    };
+  },
+};
+```
+
+React 장면은 `<KfScene t={t} ctx={ctx}>` 로 감싸면 아래 부품이 시각·박자·스타일을 알아서 받는다(`@kasaframe/motion/react`).
+
+## core
+
+| 부품 | 하는 일 |
+|---|---|
+| `clip(t, from, dur)` → `{ local, p, active }` | 구간 진행도 |
+| `seq([{ id, dur, overlap? }])` → `{ items, duration, at(t) }` | 이어 붙이기 |
+| `interpolate(v, [0, 1], [0, 100], { ease, extrapolate })` | 값 사상(밖은 끝값에 붙음) |
+| `ease.outCubic` … `ease.snappy` · `bezier(x1,y1,x2,y2)` · `toEase("name")` | 이징(모르는 이름은 던진다) |
+| `spring(t, { from, to, stiffness, damping, mass, velocity })` | 닫힌 식 스프링 — t 는 초 |
+| `rand(seed, i)` · `randRange` · `randInt` · `pick` · `shuffle` · `noise1(seed, x)` | 시드 난수. `Math.random` 금지 |
+| `ctx.beats` — `beatAt(n)` · `nearestBeat(t, grid)` · `prev`/`next(t, grid)` · `drop(i)` · `section(t)` · `phrase(t)` · `inDrop(t)` · `pulse(t, { every, decay, within })` · `energy(t, band)` | 장면 기준 박자. grid = `beat`·`downbeat`·`bar`·`phrase`·`drop`·`section` |
+| `combine(a, b, …)` · `toCss(style)` · `applyStyle(el, style)` | `Style` 겹치기·CSS 로 |
+
+## motion
+
+| 부품 | 하는 일 |
+|---|---|
+| `enter(move, t, { at, dur, ease, distance, from })` · `exit(…)` · `inOut(…, { out })` | 등장·퇴장 `fade` `rise` `drop` `pop` `blurIn` `scaleIn` `maskWipe` `slide` |
+| `stagger(i, { each, origin, count })` | i 번째 늦춤 |
+| `typeText(text, t, { at, cps, jitter, ime })` → `{ text, caret, done, … }` | **한글 자모 단위 타자**(두벌식 — `가 → 간 → 가나`). 끝은 늘 원문 |
+| `typeLines(lines, t)` · `typeDuration(text)` | 여러 줄 · 걸리는 초 |
+| `counter(t, { to, from, decimals, unit: "ko", prefix, suffix })` | 굴러 오르는 숫자 글 |
+| `words(text, t, { move, each })` · `letters(…)` | 낱말·글자 키네틱 |
+| `sweep(t, { at })` | 형광펜 쓸기(`Style.clip`) |
+| `transition(name, t, { at, dur, width, dir })` → `{ out, in }` | `whip` `zoomThrough` `slide` `matchCut` `crossfade` |
+| `camera(t, { at, kind: "push"·"pull"·"pan"·"tilt", amount })` | 카메라 — 프레이즈당 한 번 |
+| `breathe(t, { seed: ctx.id })` | 숨 쉬는 틀 — 가만히 있는 화면이 멈춤 검사에 걸리지 않게. **바탕이 아닌 내용 층에** 건다 |
+| `dropBurst(t, { beats: ctx.beats, drop: 0, rules: ctx.style.motion })` → `{ flash, ring, shake, punch }` | 드롭 터짐 — 드롭 번호로만 건다 |
+| `beatPulse(t, { beats, rules, amount })` | 박 펄스 — 기본은 드롭 구간만 |
+| `shake(t, { at, px, rules })` | 흔들림(`rules.shake.maxPx` 상한) |
+| `sparkles(t, { width, height, count, seed })` · `burst(t, { at, x, y })` | 반짝이 · 터지는 조각 |
+| `cursor(t, [{ t, x, y, click }])` | 커서 이동·클릭 물결 |
+| `terminal(t, [{ cmd, out }], { at })` · `codeReveal(code, t)` | 터미널 입력 · 코드 블록 |
+| `grow(t, values, { at, stagger })` · `draw(t, { at })` | 차트 자라기 · 선 그리기 |
+| `flyPath(t, [{ t, pos, look }])` | three.js 카메라 비행 |
+| `transition3d(root, ctx, { kind })` | 3D 장면 전환·셰이더 전환(`gl:<이름>`·`smooth:<이름>`) — 아래 절, 목록은 `kf transitions` |
+
+React(`@kasaframe/motion/react`): `KfScene` `Sequence` `Series`+`SeriesItem` `Fill` `useTime` `useCtx` `useBeats` · `Enter` `Typewriter` `Counter` `Words` `Highlight` `Transition` `Camera` `Breathe` `BeatPulse` `DropBurst` `Sparkles` `Burst` `Cursor` `Terminal` `CodeBlock` `BarChart` `DeviceFrame`. 부품마다 `t` 를 직접 줘도 된다.
+
+## 3D 전환 — `@kasaframe/motion/transition3d`
+
+앞 장면 화면을 three.js 공간의 판에 붙이고 카메라를 움직여 뒤 장면 화면에 내려앉는다. 영상 모델 없이 코드로 그리므로 같은 t 면 같은 그림이고, **구간 앞은 앞 장면 그림, 끝은 뒤 장면 그림 그대로**(텍셀을 색 공간 변환 없이 1:1 로 낸다 — 경계 프레임 차 0).
+
+```ts
+import { transition3d } from "@kasaframe/motion/transition3d";
+
+// 이음매 장면(kf.json 장면 하나) — ctx 만 주면 된다
+export default {
+  build(root: HTMLElement, ctx: SceneCtx) {
+    return transition3d(root, ctx, { kind: "dive" });
+  },
+};
+```
+
+| `kind` | 그림 |
+|---|---|
+| `dive` | 화면 속으로 — 짧게 물러나면 책상 위 모니터, 옆으로 쓸며 다가가 화면이 칸칸이 녹으며 뚫고 들어가 깊은 빛 고리 통로를 한 바퀴 돌며 날아 뒤 장면으로 |
+| `portal` | 화면에 둥근 구멍이 열리고 깊은 터널을 날아 뒤 장면으로 |
+| `cards` | 장면들이 3D 공간의 판으로 떠 있고 카메라가 다음 판으로 날아간다 |
+| `shatter` | 앞 장면이 칸으로 쪼개져 흩어지고 뒤 장면 칸이 날아와 맞춰진다 |
+| `zoomOut` | 앞 장면이 뒤 장면 속 작은 창이었음이 드러난다(`window: { x, y, h }` — 뒤 장면 안 창 중심·높이 0..1) |
+| `fold` | 병풍처럼 접혀 옆으로 빠진다. `fold: "roll"` 이면 아래부터 말려 올라간다 |
+| `diveChain` | 화면 속 화면 — `screens` 를 깊이로 늘어놓고 끊김 없이 뚫고 들어간다. `arrivals: "bar"`·`"beat"`(박마다 한 겹) 또는 시각 배열, `settle` 0 흘러가기 … 1 화면마다 멈추기 |
+| `whip` | 휙 넘기기 — 제자리에서 90° 를 휙 돈다. 반대로 살짝 감았다가 확 돌고 넘쳤다 선다, 도는 동안 기울고 화각이 넓어진다 |
+| `rise` | 2D → 3D 공간 잇기 — 앞 장면 판이 바닥으로 눕고, 그 주인공 상자(`[data-kf-hero]`, 없으면 가장 넓은 글·`hero` 로 직접)가 같은 화면 자리에서 블록으로 선다(옆면은 그 요소의 2D 색). 카메라는 깊이로 기울어 들어가 블록 위를 지나 뒤 장면 벽 앞에 정면으로 선다 |
+| `land` | 3D → 2D 공간 잇기 — 앞 장면(3D 샷 끝 화면) 앞 공간에 누운 판이 일어서고 카메라가 그 판으로 다가간다. 판 위 주인공 블록은 평면으로 내려앉고, 판이 정면으로 꽉 찬 순간이 뒤 장면 첫 화면 |
+
+- **섬광 안전** — 화면 사이로 보이는 하늘은 앞 화면 바탕색 → 뒤 화면 바탕색으로 서서히 넘어간다(`bridgeSky` — 밝기 순 가운데 절반 평균). 밝은 화면과 어두운 공간이 칸마다 엇갈려 오가면 `kf check` 의 `frame.flash` 에 걸린다. `whip` 은 가장 빠를 때 두 판의 대비를 그 색 쪽으로 누른다(셔터가 번진 것처럼, 양 끝은 0).
+
+- **살아 있는 화면** — `live: { kf, scenes: import.meta.glob("./*.ts", { eager: true }) }` 를 주면 앞 장면은 자기 끝을 지나 계속 돌고(타자·카운터가 전환 중에도 이어진다) 뒤 장면은 첫 프레임에서 기다린다. 다른 장면 하나는 `sceneSource(모듈, ctx, { id, from, dur }, (t) => 그 장면 시각)`, 영상은 `{ video: 주소, from: 영상 전체 기준 0 초 }`, 아무 DOM 은 `{ dom(root) { …; return (t) => … }, still? }`. DOM 은 크롬 HTML-in-Canvas(`--enable-features=CanvasDrawElement`, 렌더·검사 브라우저는 켜져 있다)로 seek 마다 paint 이벤트 안에서 텍스처에 올리고 `onSeek` 이 그 페인트를 기다린다 — 같은 t 두 번이 바이트까지 같다. 플래그 없는 브라우저는 `still`(이음매는 `assets/seam` 그림)로 물러난다.
+- **그림** — `from`·`to` 에 주소(`kf still` PNG 등)·`<img>`·`<canvas>`·그리기 함수 `(g, t, w, h) => void`(같은 t 같은 그림). ctx 만 주면 `assets/seam/<장면id>-from.png`(앞 장면 마지막 프레임)·`-to.png`(뒤 장면 첫 프레임)을 쓰고, 없으면 스타일 색으로 그린 대체 화면(없는 파일을 부르지 않아 검사가 깨끗하다). 찍는 곳은 `kf make`(장면을 다 쓴 뒤 `@kasaframe/gen` 의 `seamFrames` 프레임으로).
+- **시각** — ctx 만 주면 앞 장면 마지막 프레임에서 뒤 장면 첫 프레임까지(그 두 프레임은 이웃 장면이 찍으므로 같은 그림이 두 번 나오지 않는다). 직접 주려면 `at`·`dur`, 드롭·박에 끝을 맞추려면 `endAt: ctx.beats.drop(0)` 또는 `snap: "beat" | "bar" | "drop"`.
+- **역동성(기본 켬)** — `pace: "ramp"`(천천히 들어가다 확 빨라진다, `"linear"` 면 종류 그대로) · 3D 는 `land`(끝에서 살짝 넘쳐 들어갔다 선다) · `hits`(카메라 충격 — 흔들림 + 화각 펀치, 기본은 전환 안에 든 드롭, 흔들림은 `shake` 이벤트로 검사가 센다) · `dof`(피사계 심도 조리개, 기본 0.03). 전부 양 끝에서 0 이라 경계 프레임은 그대로다.
+- **모션 블러** — `npx kf render <폴더> --motion-blur 8 --shutter 180`(`kf still` 도 같다). 엔진이 한 프레임을 하위 프레임 8 장으로 찍어 평균해 빠른 것만 번진다. 하위 프레임 번호가 페이지 `seek(t, { index, count })` 로 넘어와, 3D 전환은 그 번호로 카메라를 조리개 위에서 옮겨 같은 평균에서 피사계 심도가 생긴다(초점은 시선 점). 셔터는 장면 경계를 넘지 않는다. seek 모드만, N 배 느리다.
+- `seed`(기본 장면 id) 로 방향·흩어짐이 바뀐다. `colors: { bg, deep, accent, glow }` 로 공간 색을 덮는다(기본은 `style.json` — 밝은 스타일이면 밤 색을 깊은 바탕으로).
+- 렌더러 하나를 돌려 쓴다(크롬은 페이지당 WebGL 문맥이 16 개쯤) — 전환이 몇 개든 괜찮다. 받는 중인 그림이 있으면 엔진 `onSeek` 에서 다 받고 같은 t 로 다시 그린다(React 장면이 첫 seek 에서 지어져도 대체 화면이 안 찍힌다).
+- React: `import { Transition3D } from "@kasaframe/motion/transition3d/react"` → `<KfScene t={t} ctx={ctx}><Transition3D kind="portal" /></KfScene>`.
+- 순수 리그(`diveRig(u, env)`·`chainZ` 등)는 브라우저 없이 시험한다. 데모: `packages/motion/demo/transition3d`(정지 그림 일곱 가지 — 경계 픽셀 시험용), `packages/motion/demo/transition3d-live`(곡에 맞춰 재생 중인 영상·살아 있는 장면 사이를 쉬지 않고 — 연속 다이브 마디·박), 한 장 모으기 `node packages/motion/demo/strip.ts <프로젝트> <out.png>`.
+
+## 전환 모음 — 이름 하나로 부르기 · `kf transitions`
+
+`transition3d` 의 `kind` 에 3D 일곱 가지 말고도 셰이더 전환을 이름으로 준다. 앞·뒤 화면(정지 그림·영상·살아 있는 장면·`live`)과 시각 규칙은 그대로다.
+
+```ts
+transition3d(root, ctx, { kind: "gl:crosswarp" });            // gl-transitions 125개 — `gl:<이름>`
+transition3d(root, ctx, { kind: "gl:Swirl", params: { radius: 0.8 } }); // 셰이더 uniform 덮기
+transition3d(root, ctx, { kind: "smooth:sdf-merge" });        // SmoothUI 덮개 13개 — reveal-* · sdf-*
+```
+
+- 전부 진행도의 순수 함수(seek)라 같은 t 면 바이트까지 같다. 양 끝(u = 0·1)은 셰이더를 거치지 않고 앞·뒤 화면 텍셀 그대로 낸다 — 원본 셰이더가 0·1 에서 어떻든 경계가 이어진다.
+- 공유 WebGL 렌더러 하나에서 GLSL ES 1.00 그대로 컴파일한다. 원본 기본값이 형과 어긋난 것(float 90, bool 1)은 맞춰 넣는다. 무늬 그림을 받는 것(`displacement`·`luma`)엔 시드 고정 노이즈를 꽂는다.
+- SmoothUI 덮개는 가운데에서 바탕을 앞→뒤로 갈고 끝 0.2 동안 사라진다. 원본은 덮개를 앞쪽에 몰아(outQuart) 첫 15% 에 다 지나가서, 영상에선 고르게(inOutCubic) 편다.
+- 목록 — `npx kf transitions [찾을 말] [--source gl] [--clock seek|step] [--use transition3d|react|vendor] [--json]`. 197개(3D 7 · gl-transitions 125 · MIT 웹 부품 62 · Skiper UI 3)의 이름·출처·라이선스·시계·쓰는 법. 코드에서는 `import { CATALOG } from "@kasaframe/motion/transitions2d"`.
+- 이름으로 못 부르는 웹 부품 — React 부품 10개는 `@kasaframe/motion/transitions2d/react`(`MorphText` 는 CSS 라 seek, 나머지 rAF 는 `kf.json` 의 `"mode": "step"`). 나머지 42개는 원본만 geono-hub `vendor/transitions/` 에 있다(목록의 `원본만`).
+- 들이지 않은 것 — React Bits·Animate UI(MIT + Commons Clause), Aceternity UI(재배포 금지). 출처·라이선스 원문은 레포 루트 `NOTICE`, 폴더마다 원본 `LICENSE`.
+- 갤러리 — `packages/motion/demo/transitions-gallery`(이름으로 부르는 145개 + CSS 부품, seek), `transitions-gallery-step`(rAF 부품 8개, step). `npx kf sheet <폴더> --per-scene 1` 이 전환마다 가운데 프레임 한 장.
+
+## 연출 수 — `@kasaframe/motion/moves`
+
+영상에서 모은 수(글·선·그림 바탕·전환·UI) — 수마다 3–5초 예시와 갤러리는 [`examples/moves/`](../../examples/moves/README.md). 꼴은 거의 다 `수(el, { w, h, hits, scene, … }) → (t) => void`.
+
+- `MENU`·`bundleFor(틀 moves, 테마)`·`pickDress(씨앗, 장면, 묶음)`(`@kasaframe/motion/menu` — DOM 없이 Node 에서도): 뼈대가 바로 거는 메뉴와 장면마다 시드로 고르기. 같은 요청이면 같은 수, 이어지는 장면은 다른 수, 경계 덮기는 이음매·드롭 앞에 안 건다.
+- `dressBg`·`dressText`·`dressWipe`: 메뉴 이름을 장면에 거는 쪽 — 예시에서 검사를 넘긴 값을 기본으로. 덮기는 경계의 영상 시각을 씨앗으로 써 앞 장면 끝과 뒤 장면 처음이 같은 덮개로 이어진다. 무대(`lib/stage.ts` `makeStage(root, ctx, { dress })`)가 부른다.
+
+## 규칙(style.json `motion`)과 검사
+
+- 박 펄스·흔들림·섬광·카메라·등장 움직임은 효과가 0 이 아닌 프레임마다 `window.__kf.events` 에 한 줄 남긴다 — `kf check` 가 규칙 위반을 센다. **손으로 짠 흔들림은 안 잡힌다** — 위 부품을 쓴다.
+- `scene: ctx.id` 를 넘기면 장면 단위로 센다(React 부품은 `KfScene` 이 넣는다).
+- 이어지는 두 장면에 같은 등장 움직임을 쓰지 않는다(`repeatSameMove: false`).
+- 등장이 끝나고 가만히 있는 화면은 `maxFreezeSec`(0.5초)를 넘기면 멈춤으로 잡힌다 — 장면 내용을 `breathe` 로 감싼다. 커서 깜빡임만으로는 모자란다.
+- 드롭 연출은 `drop(i)` 로 잰 시각에만. BPM 을 곱해 시각을 만들지 않는다.
+
+## Remotion 에서 옮길 때
+
+| Remotion | kasaframe |
+|---|---|
+| `useCurrentFrame()` | 장면 함수의 `t`(초) · React 는 `useTime()`. 프레임이 필요하면 `toFrame(t, fps)` |
+| `useVideoConfig()` | `ctx.meta` — `{ fps, width, height, duration }` |
+| `<AbsoluteFill>` | `<Fill>` |
+| `<Sequence from durationInFrames>` | `<Sequence from={초} dur={초}>` |
+| `<Series>` · `<Series.Sequence>` | `<Series>` · `<SeriesItem dur={초}>` |
+| `spring({ frame, fps, config })` | `spring(t, { stiffness, damping, mass })` — 초 |
+| `interpolate(frame, [..], [..], { extrapolateRight: "clamp" })` | `interpolate(t, [..], [..])` — 기본이 clamp |
+| `random(seed)` | `rand(seed, i)` |
+| `staticFile("x.png")` | `ctx.asset("x.png")` |
+| `<Img>` | `<img src={ctx.asset(…)}>` — 엔진 `ready()` 가 받을 때까지 기다린다 |
+| `<Video>` · `<OffthreadVideo>` | `<video data-kf-from="초">` — 엔진 `syncMedia` |
+| `<Audio>` | 곡은 `kf.json` 의 `music` — 렌더가 얹는다 |
+| `delayRender()` / `continueRender()` | 엔진 페이지의 `ready()` |

package/packages/motion/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@kasaframe/motion",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./react": "./src/react/index.tsx",
+    "./transition3d": "./src/transition3d/index.ts",
+    "./transition3d/react": "./src/transition3d/react.tsx",
+    "./transitions2d": "./src/transitions2d/index.ts",
+    "./transitions2d/react": "./src/transitions2d/react.ts",
+    "./moves": "./src/moves/index.ts",
+    "./menu": "./src/moves/menu.ts",
+    "./captions": "./src/captions.ts"
+  },
+  "dependencies": {
+    "@kasaframe/adapters": "^0.0.0",
+    "@kasaframe/core": "0.0.0",
+    "motion": "^12.43.0",
+    "react": "^19.3.0",
+    "three": "^0.186.1"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@types/three": "^0.186.0",
+    "react-dom": "^19.3.0"
+  }
+}

package/packages/motion/src/camera.ts

@@ -0,0 +1,97 @@
+import { emit, progress, rand, toEase, type Ease, type EaseName, type Style, safeTime } from "@kasaframe/core";
+
+export interface CameraOpts {
+  at: number;
+  dur?: number;
+  /** push 다가가기 · pull 물러나기 · pan 옆으로 · tilt 위아래 */
+  kind?: "push" | "pull" | "pan" | "tilt";
+  /** push·pull 은 배율 차(0.08 = 8%), pan·tilt 는 px */
+  amount?: number;
+  dir?: 1 | -1;
+  ease?: EaseName | Ease;
+  source?: string;
+  scene?: string;
+  emit?: boolean;
+}
+
+/**
+ * 장면 틀 하나에 거는 카메라 움직임. style.json 의 cameraMove 가 once-per-phrase 면
+ * 프레이즈마다 한 번만 쓴다 — 검사가 camera 이벤트로 센다.
+ */
+export function camera(t: number, opts: CameraOpts): Style {
+  t = safeTime(t);
+  const kind = opts.kind ?? "push";
+  const dur = opts.dur ?? 2.4;
+  const raw = progress(t, opts.at, dur);
+  const p = toEase(opts.ease, toEase("inOutCubic"))(raw);
+  const dir = opts.dir ?? 1;
+  const amount = opts.amount ?? (kind === "push" || kind === "pull" ? 0.08 : 120);
+  let s: Style;
+  let moved: number;
+  if (kind === "push" || kind === "pull") {
+    const d = (kind === "push" ? 1 : -1) * amount * p;
+    s = { scale: 1 + d };
+    moved = Math.abs(d) * 1000;
+  } else {
+    const d = -dir * amount * p;
+    s = kind === "pan" ? { x: d } : { y: d };
+    moved = Math.abs(d);
+  }
+  if (opts.emit !== false && raw > 0 && raw < 1) emit({ kind: "camera", source: opts.source ?? `camera:${kind}`, scene: opts.scene, value: moved });
+  return s;
+}
+
+export interface BreatheOpts {
+  /** 한 번 숨 쉬는 초 */
+  period?: number;
+  /** 커졌다 돌아오는 배율 차 */
+  scale?: number;
+  /** 옆으로 흐르는 px */
+  drift?: number;
+  /** 시작 위상 — 장면마다 다르게 주면 같은 숨이 반복돼 보이지 않는다 */
+  seed?: number | string;
+}
+
+/**
+ * 가만히 있는 화면이 멈춤으로 보이지 않게 아주 느리게 숨 쉬는 틀. 흐름은 타원을 돌아 속도가 0 이 되는
+ * 순간이 없다 — 어느 0.5 초를 잘라도 움직임이 남는다(kf check 의 멈춤 검사를 통과하는 까닭).
+ * 바탕이 아닌 내용 층에 건다: 바탕째 밀면 가장자리에 페이지 바탕이 비친다. 카메라 이동으로 치지 않는다(이벤트 없음).
+ */
+export function breathe(t: number, opts: BreatheOpts = {}): Style {
+  t = safeTime(t);
+  const period = Math.max(0.5, opts.period ?? 3.2);
+  const phase = rand(opts.seed ?? "breathe", 0) * Math.PI * 2;
+  const w = (Math.PI * 2 * t) / period + phase;
+  const s = opts.scale ?? 0.03;
+  const d = opts.drift ?? 16;
+  return { scale: 1 + s * (0.5 - 0.5 * Math.cos(w)), x: d * Math.sin(w), y: d * 0.5 * Math.cos(w) };
+}
+
+export type Vec3 = [number, number, number];
+
+export interface FlyKey {
+  t: number;
+  pos: Vec3;
+  look: Vec3;
+}
+
+/** 카트멀-롬으로 키 사이를 잇는다 — three.js 카메라 비행. 키가 하나면 그 자리에 선다 */
+export function flyPath(t: number, keys: FlyKey[], opts: { ease?: EaseName | Ease } = {}): { pos: Vec3; look: Vec3 } {
+  t = safeTime(t);
+  if (keys.length === 0) return { pos: [0, 0, 10], look: [0, 0, 0] };
+  const ks = keys.slice().sort((a, b) => a.t - b.t);
+  if (t <= ks[0].t || ks.length === 1) return { pos: [...ks[0].pos], look: [...ks[0].look] };
+  const last = ks[ks.length - 1];
+  if (t >= last.t) return { pos: [...last.pos], look: [...last.look] };
+  let i = 0;
+  while (i < ks.length - 2 && t >= ks[i + 1].t) i++;
+  const a = ks[Math.max(0, i - 1)];
+  const b = ks[i];
+  const c = ks[i + 1];
+  const d = ks[Math.min(ks.length - 1, i + 2)];
+  const u = toEase(opts.ease, toEase("inOutCubic"))((t - b.t) / (c.t - b.t));
+  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);
+  const mix = (k: "pos" | "look"): Vec3 => [0, 1, 2].map((j) => cr(a[k][j], b[k][j], c[k][j], d[k][j])) as Vec3;
+  return { pos: mix("pos"), look: mix("look") };
+}