kasaframe 0.0.0-stage → 0.1.1

package/docs/AGENTS.md

@@ -0,0 +1,238 @@
+# kasaframe 사용서 — 영상을 만드는 모델용
+
+웹 화면을 시각 t 의 함수로 짜면 kasaframe 이 1/60초마다 찍어 MP4 로 붙인다. 연출·박자·검사는 라이브러리가 쥔다. 너는 **장면 파일만 채운다**. 명령은 `kf <명령>` — `npm i -g kasaframe` 로 깔았으면 어느 폴더에서나, 레포에서는 뿌리에서 `npx kf <명령>`(또는 `node packages/cli/src/kf.ts <명령>`). 처음이면 `kf doctor`(ffmpeg·크롬·librosa·OG 키 점검)·`kf setup`(크롬·librosa 깔기).
+
+## 0. 한 줄로 끝까지 가려면
+
+```
+kf make "카사텀 홍보 영상 1분, 카와이 퓨처베이스" [--music 곡.mp3] [--purpose promo] [--theme auto]
+```
+
+- **Claude Code 안**(기본 `--model claude-code`): 뼈대·곡 분석·장면 지시서 `MAKE.md` 까지 만들고 멈춘다. 다른 모델을 부르지 않고, **돈이 드는 그림도 묻지 않고 만들지 않는다** — 지시서의 「만들 그림」을 보고 필요할 때만 네가 구체적인 프롬프트로 `kf gen img` 를 부른다. 장면을 다 채우고 `kf look <폴더>` 가 찍는 장면 모음·확인표를 직접 본 뒤 `kf make --finish <폴더>`(렌더·검사·표지·자막. 그림 보는 모델도 안 부르고 끝에 장면 모음·확인표 경로를 다시 찍는다).
+- **OG 모드**(`--model deepseek/deepseek-v4-pro` 같은 이름): 장면 작성·고치기까지 OG `chat/completions` 로 끝까지. 그림 검사는 `--vision-model <모델>` 을 줄 때만.
+- **그림 보기는 세션이 직접**: `kf look <폴더|mp4>` 가 장면 모음(`out/look-sheet.png`)과 장면별 확인표(`out/look.md` — 빈 화면·글 깨짐·대비·잘림·주인공 자리·할 일·테마)를 만들고 경로만 찍는다. 외부 모델을 부르지 않는다. **눈 없는 모델**(Claude Code 를 OG 로 딥시크 같은 모델에 붙였을 때 — OG `/v1/messages` 는 그림을 버려서 Read 해도 안 보인다)만 `kf look <폴더|mp4> --vision-model google/gemini-3.5-flash [--ask "<볼 것>"]` 로 그림 보는 모델이 장면마다 글로 보고한다(한 번 1센트 안팎, 묻지 않고 써도 된다). `kf make --finish` 도 기본은 그림 보는 모델 없이 끝에 장면 모음·확인표 경로를 찍는다.
+- **곡**: 홍보·공개·뮤비는 곡이 끌고 간다. `--music` 을 안 주면 곡 모음(`KF_MUSIC_DIR`, 없으면 레포 `music/` — 곡마다 원본·라이선스는 `music/README.md`. npm 패키지에는 곡이 없다)에서 요청 낱말과 맞는 곡을 고른다. 곡 모음이 비었으면 `--music` 으로 준다.
+- **용도·테마**: 말로만 해도 알아서 고른다 — 테마는 기본 `auto`: 요청이 「리소 느낌으로」처럼 짚은 테마(이름·비유에서 찾는다), 아니면 내용에 맞는 approved 후보 셋 중 첫째(고른 이유·다른 후보 둘이 지시서에, 첫 장면을 셋 다 찍어 `out/theme-<id>.png`). 못 박으려면 `--purpose <용도>`·`--theme <id>`, 테마 없이 프리셋만이면 `--theme none`. 묻는 것은 용도 확신이 낮을 때뿐(종료 코드 3).
+- **작업실**: `kf app` 이 떠 있으면 `kf make` 가 거기에 등록하고 주소를 찍는다 — 사람은 페이지에서 실시간 미리보기·지난 작업을 본다.
+- **Claude Code 스킬**: `kf skill install` 하면 「영상 만들어」 같은 말에 kasaframe 으로 오는 스킬이 깔린다(`skills/kasaframe/SKILL.md`).
+- 영상 생성 모델은 요청 글에 「영상 생성」을 적었을 때만 쓴다(이음매 기본은 3D 모션그래픽 전환). 영상은 `--yes` 가 있어야 돈을 쓴다.
+
+**규칙 — 단 0.1초도 쉬지 않는다**(검사가 오류로 잡는다. 용도마다 틀이 기준을 정한다 — 아래 표, 이 영상의 값은 MAKE.md 첫머리): ① 0.1초(60fps 6프레임) 넘게 화면이 안 바뀌면 오류 — 끝 카드·큰 숫자·로고도 예외 없음 ② 같은 구도가 표의 초를 넘으면 경고·오류 — 새 요소·칸 채우기·숫자 키우기·컷·전환 ③ 미세한 흔들림 말고 눈에 보이는 큰 움직임 — 표의 자리에서 박마다 하나 이상 ④ 주 요소가 화면을 채운다(세로는 폭 70% 넘게). 쉬지 않는 몫은 **화면 안 움직임**이 진다 — 카메라는 이유가 있을 때만 움직인다(3장 「카메라」). `kf new` 가 넣어 주는 `lib/stage.ts`(`makeStage`·`makeCamera`·`bigWord`·`cutTimes`·`lastT`)가 이걸 처음부터 넘게 짜 둔 무대다 — 장면을 하나하나 고치기 전에 겉에 씌워라.
+
+| 용도 | 0.1초 정지 | 같은 구도 경고·오류 | 박마다 큰 움직임 |
+|---|---|---|---|
+| `shorts` `promo` `ad` `launch` `square` | 금지 | 1.5초 · 3초 | 어디서나 |
+| `mv` `explainer` `demo` | 금지 | 5초 · 8초 | 후렴·드롭 구간(beats.json sections 의 drop)만 — 벌스는 화면 안 움직임(가사·숫자·바탕 흐름)으로 충분 |
+
+## 1. 용도 고르기
+
+요청 글과 받은 자산을 보고 하나 고른다. 애매할 때만 사람에게 묻는다.
+
+| 용도 | 화면 · 길이 | 글 |
+|---|---|---|
+| `promo` 홍보 | 16:9 · 30–60초 | 문구 없이 기능 낱말·끝 카드만. 곡이 끌고 감, 드롭에서 가장 크게 |
+| `shorts` 쇼츠 | 9:16 · 15–60초 | 전문 낱말만, 자막은 따로(srt·vtt). 첫 1.5초 훅, 끝이 처음으로 이어지게 |
+| `explainer` 설명 | 16:9 · 60–120초 | 도식·3D, 전문 낱말만, 자막 트랙 |
+| `launch` 공개 | 16:9 · 30–90초 | 감추고 → 드러내고 → 기능 셋 → 이름 |
+| `demo` 시연 | 16:9 · 30–180초 | 화면 녹화 + 확대·커서·단계 표시 |
+| `ad` 광고 | 6·15·30초 | 브랜드 첫 2초 안, 자막 굽기 |
+| `square` 피드 | 1:1 · 15–60초 | 소리 없이도 읽히게, 자막 굽기 |
+| `mv` 뮤비 | 16:9·9:16 · 곡 전체 | 곡 구간마다 장면, 가사 키네틱 타이포(`lyrics.json` 낱말 시각), 컷은 마디·박마다 |
+
+## 2. 뼈대 — `kf new`
+
+```
+kf new <폴더> --template promo --music 곡.mp3 --style og
+```
+
+곡을 재고(`beats.json`) 장면 경계를 박·드롭에 붙인 시간표(`kf.json`)와 장면 파일을 만든다. 스타일: `presets/` 의 `og` `neutral-dark` `kawaii-pastel`(틀이 고른 프리셋이 없으면 `neutral-dark`).
+
+곡만 다시 재려면 `kf beats 곡.mp3 --out <폴더>/beats.json [--from 초 --duration 초]` — 요약(bpm·드롭·구간)은 stderr. 드롭·구간은 **잰 시각**이다. BPM 을 곱해 시각을 만들지 않는다(뒤로 갈수록 밀린다).
+
+```
+<폴더>/kf.json        장면 시간표 — 시각은 여기 한 곳. 장면마다 할 일이 idea 에 적혀 있다
+<폴더>/scenes/<id>.ts 네가 채울 곳 — 장면 하나 = 파일 하나
+<폴더>/style.json     색·글꼴·움직임 규칙   <폴더>/beats.json  박·드롭·프레이즈
+<폴더>/assets/        받은 자산 · assets/gen/(생성한 것)    <폴더>/out/  결과
+```
+
+`main.ts`·`index.html` 은 고치지 않는다. 장면 경계를 옮기려면 `kf.json` 의 숫자만.
+
+## 3. 장면 채우기 — `scenes/<id>.ts`
+
+```ts
+import { applyStyle, type SceneCtx } from "@kasaframe/core";
+import { enter, typeText } from "@kasaframe/motion";
+
+export default {
+  build(root: HTMLElement, ctx: SceneCtx) {
+    const title = document.createElement("h1");
+    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 }));
+    };
+  },
+};
+```
+
+- `t` 는 **장면 안 초**(장면 시작 = 0). 반환 함수는 **같은 t 면 같은 화면** — 앞 프레임 상태를 쌓지 않는다.
+- DOM 은 `build` 에서 한 번 짓고, `(t) => …` 에서는 글·스타일만 바꾼다.
+- 박자는 `ctx.beats`(`drop(0)`·`nearestBeat`·`phrase`·`inDrop`), 그림은 `ctx.asset("x.png")`, 글은 `ctx.safe` 안에.
+- 움직임은 `@kasaframe/motion` 부품을 쓴다 — 손으로 짠 흔들림·펄스는 검사가 셀 수 없다. 부품 표와 Remotion 대응표: [`packages/motion/README.md`](../packages/motion/README.md).
+- React 장면: `export default { react: Component }`, `Component({ t, ctx })`.
+
+하지 말 것:
+
+- `Math.random` · `Date.now` · `setInterval` 로 상태 쌓기 → `rand(seed, i)` · `t`
+- 배열·객체를 그대로 글에 넣기(`undefined`·`[object Object]` 가 화면에 찍힌다) → 글은 늘 문자열로 만들고 길이를 맞춘다
+- 박마다 화면 흔들기 · 이유 없이 카메라 떠다니기(사인 드리프트·박마다 자세·늘 다가가기) · 같은 등장 움직임을 이어서 두 장면에 · 드롭 시각을 BPM 으로 곱해 만들기
+- 한글이 없는 글꼴로 한글 쓰기 → 스타일 프리셋 글꼴(전부 한글이 선다)
+
+### 카메라 — 이유가 있을 때만
+
+기본은 **정지**, 주인공은 안전 영역 가운데. 화면 전체를 사인으로 흔들거나 박마다 자세를 바꾸면 격자가 기울고 주인공이 가장자리로 밀린다 — `kf check` 가 `camera.wander`(이유 없는 카메라 이동)·`layout.edge`(주인공이 안전 영역 가장자리 4% 띠에) 로 경고한다. 카메라는 장면이 이유를 댈 때만:
+
+```ts
+const stage = makeStage(root, ctx);   // 흐르는 바탕 + 컷마다 모양을 바꾸는 바탕 판 + 정지 카메라
+stage.camera
+  .pushIn(2.0, { to: answer })        // 드러냄에 다가가기 — 요소 상자를 가운데로, 안전 영역 86% 안에 들게 배율을 누른다
+  .pullOut(5.5)                       // 비교 전체를 보이게 물러나기 — 기본은 처음 구도. 더 넓게는 { scale: 0.9 }
+  .follow(ball, 6.5, 9.0)             // 움직이는 주인공 따라가기 — 끝나면 앞 구도로 돌아와 선다
+  .impact(ctx.beats.drop(0));         // 드롭·결과가 서는 순간에 한 번 툭
+return (t: number) => {
+  /* 내용을 칠한다 */
+  stage.tick(t);                      // 요소를 겨누면(to·follow) 맨 끝에 — 그 프레임의 자리를 잰다
+};
+```
+
+- 부드럽게(inOutCubic) 가고 끝나면 선다. 움직이는 동안만 `__kf.events` 에 카메라로 남아 이유 있는 이동으로 친다 — 프레이즈당 한 번 규칙(`motion.camera`)도 이걸 센다.
+- 자기 카메라 층을 짠 장면은 `makeCamera(layer, ctx, { frame })` 로 같은 넷을 건다. `frame` 은 층 안 좌표로 본 안전 영역, 다른 움직임과 섞으려면 `camera.pose(t)` 를 `combine` 한다.
+- 회전·원근 기울기는 0 — 3D 전환(이음매)·입체 테마가 원할 때만.
+- 「쉬지 않기」는 화면 안 움직임이 맡는다: 숫자가 구르고, 칸이 차고, 반짝이고, 바탕이 흐른다. 바탕 흐름은 바탕 층(`stage.box`)에만, 주인공 층(`stage.cam`)은 흔들지 않는다.
+- `stage.hero(el)` 로 주인공을 짚으면 `layout.edge` 가 그 상자를 늘 본다(`bigWord` 는 스스로 짚는다). 짚지 않으면 그 프레임의 가장 큰 글을 주인공으로 보되, 카메라가 처음 자리를 벗어난 동안만 센다(일부러 구석에 둔 배치는 안 잡는다).
+
+### 이미 있는 컴포넌트·영상·3D 를 넣을 때
+
+- 자기 rAF·타이머·물리로 도는 컴포넌트를 **고치지 않고** 넣으려면 `kf.json` 에 `"mode": "step"` — 0 초부터 차례로 돌린다. 기본 `seek` 는 화면이 t 의 순수 함수일 때(탭 병렬로 빠르다).
+- 렌더 중에는 `requestAnimationFrame`·`performance.now`·`Date`(0 초 = 2026-01-01T00:00Z)·`setTimeout`·`setInterval` 이 영상 시각을 따르고 `Math.random` 은 프레임마다 그 번호로 다시 씨를 뿌린다(같은 프레임은 어느 탭에서 찍어도 같은 값 — 남이 만든 라이브러리의 난수도 이음매가 맞는다). 캔버스에 그리는 그림은 처음 그리기 전에 엔진이 한 번 데워 둔다.
+- seek 모드의 CSS 애니메이션·트랜지션은 0 초에 시작한 것으로 본다 — 장면 가운데서 시작할 것은 `animation-delay` 로 박거나 움직임 부품으로.
+- 영상: `<video src data-kf-from="<영상 전체 기준 초>" muted>` — seek 마다 맞춘다. 소리는 `kf.json` 의 `music` 만 얹힌다.
+- Lottie·GSAP·three.js: `@kasaframe/adapters` 의 `bindLottie(anim, { from })` · `bindGsap(gsap)` · `bindThree({ renderer, scene, camera, update(t) })`.
+- **Blender 툰 3D**(카메라가 공간을 지나가는 샷·박에 맞춰 움직이는 물체): `kf blender <샷.py> --project <폴더> --scene <id>` 가 헤드리스 Blender 로 굽어 `assets/blender/<id>.mp4` 를 두고 `<video data-kf-from>` 값을 찍어 준다. 샷은 `tools/blender/kfb.py` 헬퍼로 — `update(t)` 가 t 만 보고 자세를 정하고, 카메라 열쇠는 `S.downbeats`·`S.drops` 에(`Track(..., move=…)` 로 도착하면 선다). 굽기 전에 `--still 1.2,4.5` 로 몇 장 본다. 예시·쓰는 법: `tools/blender/README.md`(Blender 4.3 이상, GPL-3.0 폴더).
+- 글꼴·`<img>`·CSS `background-image`·영상은 받을 때까지 기다린다. 더 기다릴 것이 있으면 `definePage({ ready: async () => … })`.
+- **이미 있는 React 컴포넌트**는 `lib/react.ts` 의 `bit(host, Comp)` 로 — 장면이 처음 그려질 때 붙인다(`build` 에서 바로 붙이면 장면이 숨은 동안 등장 애니메이션이 끝나 버린다). 컴포넌트가 쓰는 npm 패키지는 프로젝트 폴더에 `package.json` 을 두고 `npm i <패키지> --legacy-peer-deps`. **react·react-dom 은 프로젝트에 깔지 않는다**(레포 것 한 벌로 묶인다 — 두 벌이면 훅이 깨진다). 새 의존을 넣은 첫 실행은 Vite 가 다시 묶으며 한 번 새로 고칠 수 있다 — 두 번째부터 본다. 자기 시계로 도는 컴포넌트면 `"mode": "step"`(대신 「같은 프레임 두 번 찍기」 검사는 못 한다).
+- **이음매 장면**(`role: "seam"`)은 고치지 않는다 — 틀의 3D 전환(`transition3d`)이 앞 장면 마지막 화면에서 뒤 장면 첫 화면으로 잇는다. 앞뒤 화면 그림은 `kf make --finish` 가 장면을 다 쓴 뒤 찍는다.
+- **되돌이**(쇼츠·피드처럼 끝이 처음으로 이어질 때): 렌더가 마지막으로 찍는 장면 안 시각은 `ctx.dur` 이 아니라 `ctx.dur - 1/fps`(`lastT(ctx)`) — 움직임을 거기서 끝내야 끝 화면과 첫 화면이 픽셀까지 같다.
+
+### 뮤비 가사 — `kf lyrics align` · JIZURA 가사 층
+
+```
+npx kf setup jizura lyrics                                   # 한 번만 — 가사 층 엔진·한글 글꼴(60MB), 정렬 꾸러미(2GB)
+npx kf lyrics align 곡.mp3 --text 공식가사.txt --lang ko --out <폴더>/lyrics.json [--from 초 --duration 초]
+```
+
+- 글자는 공식 가사(한 줄 = 가사 한 줄)가 정본이고 정렬은 시각만 붙인다 — 받아쓰기 글자를 화면에 쓰지 않는다. 곡 일부만 쓰면 `kf beats` 와 같은 `--from` 을 준다(시각의 0 이 같아야 한다). 첫 실행은 whisper 모델(1.6GB)을 받는다.
+- `kf new --template mv` 의 장면은 프로젝트 뿌리의 `lyrics.json` 을 JIZURA 가사 층으로 그린다 — 벌스는 차분한 플랜, 드롭(`ctx.beats.inDrop`)부터 큰 플랜. 엔진이 없거나 `lyrics.json` 이 없으면 부른 낱말을 DOM 으로 띄운다.
+- 직접 쓸 때: `jizuraPlans({ day: { style: "ocean", schemes: "light" } })` 로 플랜을 이름 짓고 `const paint = jizuraLayer(root, { ctx, plan: "day" })` → `(t) => paint(t)`. 같은 설정의 플랜은 장면끼리 나눠 쓴다. 밝은 바탕엔 `schemes: "light"`(어두운 글), 밤 장면엔 `"dark"`, 주인공 얼굴이 요점이면 `centerFree: true`(가운데를 비운다). 분위기는 `moods: ["calm", "emotional", "editorial"]` 처럼 부품 태그로 거른다.
+- 화면을 덮는 부품(불투명 판·카드 카메라·화면 전체 섬광)은 기본 거부 목록(`DENY`)이 막는다. 더 막을 것은 `deny: { layout: ["…"] }`. **거부 목록·`moods`·`seed` 를 바꾸면 그 플랜의 컷이 전부 다시 굴려진다** — 스틸을 다시 본다. 어느 부품인지는 `jizuraCuts({ ctx, plan })` 로 그 시각의 컷(layout·enter·hold·exit·decor·cam)을 본다.
+- 가사 층 글은 검사에서 장면 글과 따로 묶인다. 띠·배경 큰 글자처럼 일부러 화면 끝을 넘기는 장식은 `text.offscreen` 경고로만 나온다 — 읽혀야 할 가사 줄이 잘리면 그 부품을 막는다.
+- 가사 층으로 낸 영상에는 「JIZURA 字面 (c) 2026 hakoniwa (github.com/852wa), MIT」를 적는다.
+
+### 자주 밟는 곳
+
+- **`visibility` 로 고르면 숨긴 컷에서도 비친다** — 부모 `visibility:hidden` 을 자식 `visibility:visible` 이 뒤집는다. 여러 장 중 하나만 보일 땐 `opacity` 나 `display`.
+- **CSS `zoom` 으로 키우지 않는다** — `left/top` 까지 같이 커져 화면 밖으로 나가고, 검사의 글 상자 자리도 어긋난다. 부품의 크기 인자나 `transform: scale` 로.
+- **이름 겹침** — 장면 안 지역 변수·함수가 가져온 이름을 덮으면(겉층 `live` 와 컷 판정 `live(t, i)` 처럼) 던지지 않고 늘 거짓이 되어 화면이 통째로 빈다. 검사는 `frame.blank`·`layout.fill` 로만 잡고 `page.error` 는 안 뜬다 — 빈 화면이 나오면 이름부터 본다.
+- **크기를 className CSS 로 받는 컴포넌트**(캔버스 등)는 그대로 넣으면 300×150 — 장면에 `<style>` 로 그 클래스 크기를 준다.
+- **스크린리더 전용 글**(1px·clip 으로 숨긴 span)은 검사가 대비·화면 밖 판정에서 뺀다. 그래도 걸리면 그 클래스를 `display:none`.
+- **`build` 에서 장면이 숨어 있다**(앞 장면 차례엔 `display:none`) — 그때 잰 크기는 0 이다. 크기는 글자 수로 어림하거나(`fitPx`) 처음 그려질 때 잰다.
+- **0.1초 규칙** — 끝 카드·큰 숫자 화면이 제일 먼저 걸린다. 구도는 칸 평균 밝기와 화면 안 내용(글·칸의 센 가장자리 지도) 둘로 본다 — 숫자가 구르고 칸이 차고 줄이 붙으면 바뀐 것으로 치지만, 빛 방울·모눈 같은 부드러운 바탕 흐름만으로는 안 바뀐다. 컷(`cutTimes`)마다 화면 안 내용을 바꾼다(새 줄·칸 채우기·숫자 키우기·바탕 판).
+
+## 4. 보기 — `kf preview` · `kf still` · `kf sheet`
+
+```
+kf preview <폴더> [--t 12.3]      # 주소 한 줄(stdout). / 가 미리보기, /index.html 이 프로젝트 페이지, ?t=12.3
+kf still <폴더> --t 12.3          # 한 장 → out/still-12.3.png
+kf sheet <폴더>                   # 장면마다 한 장씩 모은 한 장
+kf look <폴더>                    # 장면 모음 + 장면별 확인표(out/look.md) 경로 — 직접 Read 로 본다(외부 모델 0)
+kf look <폴더> --vision-model google/gemini-3.5-flash   # 그림을 못 보는 세션만 — 다른 모델이 장면마다 글로 보고(out/look.json)
+```
+
+미리보기: Space 재생 · ←→ 한 프레임 · Shift+←→ 1초 · Alt+←→ 박 · ↑↓ 장면·구간·드롭 경계 · 타임라인 Shift 끌기는 박에 붙인다. 장면을 저장하면 보던 시각 그대로 새로 그리고, 깨진 장면은 붉은 줄로 알린다.
+
+그림을 못 보면 미리보기 대신 `kf check`(숫자·글로 다 나온다)와 `kf still`.
+
+## 5. 굽기 — `kf render`
+
+```
+kf render <폴더> [--tabs 2]       # → out/render.mp4 + out/render.json(markers·움직임 기록)
+kf render <폴더> --from 10 --to 14 --no-lock   # 고친 구간만 빨리
+```
+
+### 자막 켜고 끄기
+
+들릴 말은 장면 파일이 아니라 `captions.json` 에 쓴다 — `[{"scene": "<id>", "text": "짧은 마디를 쉼표로"}]`(`from`·`to` 초나 `words` 낱말 시각도 된다). `kf.json` 의 `captions` 가 `off`(쇼츠·설명 기본 — srt·vtt 만) · `on`(화면에 얹고 srt·vtt 도) · `none`. 화면 자막은 엔진이 장면 위에 판을 얹는다(안전 영역 아래쪽 가운데, 테마 글꼴, 어절 단위 두 줄까지, 세로 화면은 폭의 8% 크기) — 장면에 문장을 쓰지 않는다. 켜면 `ctx.safe` 아래쪽에서 자막 띠(판 두 줄 높이)를 뺀다 — 무대(`makeStage`)처럼 `ctx.safe` 로 배치하는 장면은 제 크기 그대로 띠 위로 올라간다. 픽셀을 박아 둔 장면은 안 움직여 `kf check` 가 `caption.overlap` 으로 잡는다 — 글을 `ctx.safe` 안으로 옮기거나, 장면을 못 고치면 `--captions fit`(장면 전체를 띠 위로 줄여 올린다 — 안 겹치지만 내용이 작아지고 움직이는 면적도 준다).
+
+```
+kf render <폴더> --captions on --suffix   # 다시 만들지 않고 자막 판만 → out/render-자막.mp4 (원본은 그대로). fit 이면 장면을 줄여 올린다
+kf make --finish <폴더> --captions on --suffix   # out/video-자막.mp4 + srt·vtt
+kf check <폴더> --captions on             # 자막 켠 화면으로 훑는다
+kf preview <폴더> --captions on           # 미리보기 단추(C)로도 켜고 끈다
+```
+
+## 6. 검사 — `kf check`
+
+```
+kf check <폴더>                   # 가장 정확하다 — 페이지를 열어 프레임마다 훑는다
+kf check <폴더>/out/render.mp4    # 영상만 있을 때 — 프레임 차 + OCR
+```
+
+렌더·검사는 한 기계에서 하나씩 돈다(`.render-lock`, npm 으로 깐 판은 임시 폴더의 `kasaframe-render-lock` — 다른 렌더가 쥐고 있으면 기다린다, 탭은 둘까지). 렌더를 되풀이하기 전에 고칠 것을 모아 한 번에. 종료 코드 `0` 통과 · `1` 오류 · `2` 못 돌림. 보고서는 글로 나오고 JSON 은 `out/check.json`. **오류가 0 이 될 때까지 7 로 간다.** 경고는 읽고 판단한다(`--strict` 면 경고도 실패).
+
+## 7. 고치기 — 보고서 규칙별로
+
+| 규칙 | 뜻 | 고치는 법 |
+|---|---|---|
+| `text.bad` | 화면에 `undefined`·`NaN`·`[object Object]`·`null` | `자리:` 의 파일·줄로 간다. 배열 길이·빠진 칸·숫자 포맷을 고친다. 코드 화면에서 일부러 보이면 `kf.json` 에 `"check": { "allowText": ["null"] }` |
+| `text.tofu` | 어떤 글꼴에도 없는 글자(빈 네모) | 그 글자를 빼거나 SVG 로. 이모지 금지 |
+| `text.fallback` | 첫 글꼴이 안 불러와졌거나 그 글자가 없다 | 글꼴 이름·`@font-face` 를 확인, 한글이면 프리셋 글꼴로 |
+| `text.offscreen` | 글이 화면 밖으로 잘린 채 0.5초 넘게(가사 층 `data-kf-lyrics` 의 띠·배경 글자는 경고) | 자리·크기를 줄여 화면 안으로. 가사 층 경고는 장식 띠면 두고, 읽혀야 할 가사 줄이면 화면 안으로 |
+| `text.safe-area` | 플랫폼 UI 가 가리는 자리에 글 | `ctx.safe` 안으로 |
+| `text.contrast` | 바탕과 대비가 낮다 | 글 색이나 바탕을 3:1 이상 벌린다. 덮개 아래 글이면 덮개를 걷는다 |
+| `text.small` · `text.crowded` | 틀이 정한 글 크기·한 화면 글 수를 넘었다 | 낱말을 줄이고 키운다(터미널·코드 화면이면 둬도 된다) |
+| `frame.freeze` | 0.1초 넘게 거의 안 바뀐다(30fps 로 훑는다) | 늘 도는 화면 안 움직임 — 숫자 굴러가기·반짝임·`makeStage` 의 흐르는 바탕을 겉에, 끝 카드도 |
+| `layout.static` | 장면 안에서 같은 구도가 표의 초(기본 1.5초 경고·3초 오류, 뮤비·설명·시연 5·8초) | 새 요소·칸 채우기·숫자 키우기·컷 — `cutTimes(ctx)` 박마다 내용을 바꾼다(카메라로 메우지 않는다) |
+| `camera.wander` | 글을 품은 큰 층(카메라 층)이 카메라 이벤트 없이 움직였다 — 장면 안 합 0.8초 넘게 | 사인 드리프트·박마다 자세·늘 다가가는 줌을 걷는다. 이유가 있으면 `stage.camera`(pushIn·pullOut·follow·impact)로 — 그쪽은 이벤트가 남아 안 센다 |
+| `layout.edge` | 주인공 상자(`data-kf-hero`, 없으면 카메라가 움직여 있는 동안의 가장 큰 글)가 안전 영역 가장자리 4% 띠에 0.5초 넘게 | 주인공을 안전 영역 가운데로. 카메라가 밀었으면 그 이동을 걷고, 왼쪽에 붙인 배치면 가운데로 옮긴다 |
+| `layout.fill` | 장면 내용이 안전 영역의 12% 아래(오류) · 세로 화면 폭 70% 아래(경고) | 주 요소를 키운다 — `bigWord`·`fitPx`, 도식 확대, 화면을 채우는 면 |
+| `caption.overlap` | 화면 자막 판이 장면 글을 덮는다(경고) | 그 글을 `ctx.safe` 안으로 — 자막을 켜면 안전 영역 아래쪽 띠 자리가 빠진다. 장면을 못 고치면 `--captions fit` |
+| `frame.spike` | 한 프레임만 앞뒤와 크게 다르다(경고) — 깜빡임·한 프레임 오류 | 그 시각 장면의 조건 분기·켜고 끄기 경계를 본다. 일부러 한 섬광·컷이면 드롭·장면 경계에 붙인다(거기선 안 센다) |
+| `frame.flash` | 화면 25% 넘게 번쩍이는 섬광이 1초에 3번 넘게(빛 민감 발작 — `style.json` `motion.maxFlashPerSec`) | 박마다 섬광이면 두 박·한 마디에 한 번으로, 섬광 연타는 2마디 안. 빠른 곡(150BPM 넘게)은 반 박이 아니라 2박에 한 번 |
+| `frame.flash-red` · `frame.flash-pattern` · `frame.flash-cut` | 빨강 전체 깜빡임(오류) · 대비 큰 줄무늬·나선이 빠르게 화면 25% 넘게(경고) · 컷 앞뒤 밝기 50%p 넘게 뜀(경고) | 빨강은 화면 10% 아래 작은 요소로 · 무늬를 줄이거나 느리게 · 흰 화면 섬광 대신 색 섬광 |
+| `frame.blank` | 한 색 화면이 0.5초 넘게 | 장면이 비었거나 그리기가 실패했다. `page.error` 부터 본다 |
+| `frame.nondeterministic` | 같은 t 를 두 번 그렸더니 달랐다 | `Math.random`·`Date.now`·쌓는 상태를 `t` 의 함수로 |
+| `page.error` | 장면이 던졌다 | 메시지의 장면·시각으로 간다 |
+| `beat.boundary` · `beat.boundary-drop` | 장면 경계가 박·드롭에서 어긋났다 | `kf.json` 의 `from` 을 알려 준 박·드롭 시각으로 |
+| `motion.beat-pulse` | 규칙 밖에서 박 펄스 | `beatPulse` 를 드롭 구간에서만(부품 기본값) |
+| `motion.shake-*` | 드롭 밖 흔들림 · 프레이즈당 횟수 · 상한 px 넘음 | `dropBurst` 로 드롭에서만, 한 프레이즈에 한 번 |
+| `motion.camera` | 한 프레이즈에 카메라 두 번 넘게 | 프레이즈당 한 번 |
+| `motion.repeat` | 이어지는 두 장면이 같은 등장 움직임 | 한쪽을 다른 `enter` 로 |
+| `asset.*` | 생성 자산의 라이선스·지역 제한·투명 실패 | 밖에 내기 전에 사람에게 알린다 |
+
+고친 뒤: 그 구간만 `kf check <폴더> --from 10 --to 14` → 다 고쳤으면 `kf render` → `kf check <영상>`.
+
+## 8. 없는 그림·영상 — `kf gen`
+
+```
+kf gen models                                          # 키·단가 표
+kf gen img "<구체적 프롬프트>" --id hook-bg --project <폴더> [--size 1080x1920 --transparent --ref a.png]   # 그림 한 장 — 돈이 든다(한 장 $0.25 상한)
+kf gen plan <폴더> [--yes]                             # plan.json 의 gen:img·gen:vid 를 다 만든다
+kf gen seam <폴더> <장면id> "<프롬프트>" --yes          # 앞 장면 끝 → 다음 장면 첫 프레임을 잇는 전환 클립
+```
+
+영상은 `--yes` 가 없으면 견적만 내고 종료 코드 3 — 돈이 드는 호출은 사람 승인 뒤에. 단가·라이선스: `packages/gen/PROVIDERS.md`.
+
+## 예제
+
+[`examples/`](../examples/) — 채운 프로젝트와 검사가 잡는 버그 표본.

package/music/README.md

@@ -0,0 +1,13 @@
+# 곡 모음 — kf make 가 곡을 안 받았을 때 고르는 곳
+
+`kf make` 는 곡이 필요한 용도(홍보·공개·뮤비)인데 `--music` 이 없으면 여기서 요청 낱말과 파일 이름이 맞는 곡을 고른다(「카와이·퓨처베이스·칠·로파이·애니…」 같은 한국어 장르 낱말은 영어로도 찾는다). 다른 폴더를 쓰려면 `KF_MUSIC_DIR=<폴더>`.
+
+곡 파일은 깃에 올리지 않는다(`.gitignore`) — 아래 표의 원본에서 받아 이 폴더에 둔다. 파일 이름에 장르·분위기 낱말을 넣어 두면 잘 골린다.
+
+| 파일 | 곡 | 장르 · 길이 | 원본 · 라이선스 |
+|---|---|---|---|
+| `kawaii-friends.mp3` | Kawaii Friends — ckotty3 | Future Bass · 2:31.8 · 170 BPM, 드롭 11.34·22.63·45.22초 | https://pixabay.com/music/future-bass-kawaii-friends-110954/ · Pixabay Content License(상업 이용 가능, 출처 표기 의무 없음) |
+| `anime-star-ckotty3.mp3` | Anime Star — ckotty3 | Anime · 1:49 · 107 BPM | Pixabay · 같은 라이선스 |
+| `gummy-drive-mvncm.mp3` | Gummy Drive — mvncm | 2:00 안팎 | Pixabay · 같은 라이선스 |
+
+새 곡을 넣을 땐 이 표에 한 줄(원본 주소·라이선스)을 더한다. 출처를 모르는 곡은 넣지 않는다.

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "kasaframe",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "말로 시키는 코드 영상 엔진 — 쇼츠·홍보·설명·뮤비를 장면 파일로 짜고 박에 맞춰 MP4 로 굽고 검사한다",
+  "keywords": [
+    "video",
+    "motion-graphics",
+    "shorts",
+    "music-video",
+    "render",
+    "playwright",
+    "vite",
+    "claude-code"
+  ],
+  "license": "MIT",
+  "author": "2rami",
+  "type": "module",
+  "bin": {
+    "kf": "bin/kf.mjs"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "dependencies": {
+    "esbuild": "^0.28.2",
+    "motion": "^12.43.0",
+    "playwright": "^1.64.0",
+    "pngjs": "^7.0.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "three": "^0.186.1",
+    "vite": "^8.3.3"
+  },
+  "peerDependencies": {
+    "vue": ">=3.3",
+    "svelte": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "vue": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    }
+  }
+}

package/packages/adapters/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@kasaframe/adapters",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./react": "./src/react.ts",
+    "./vue": "./src/vue.ts",
+    "./svelte": "./src/svelte.ts"
+  },
+  "dependencies": {
+    "@kasaframe/clock": "^0.0.0",
+    "@kasaframe/core": "^0.0.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "svelte": "^5.57.2",
+    "vue": "^3.5.43"
+  },
+  "peerDependencies": {
+    "vue": ">=3.3",
+    "svelte": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "vue": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    }
+  }
+}

package/packages/adapters/src/css.ts

@@ -0,0 +1,11 @@
+// 가상 시계가 없을 때(미리보기) seek 모드 페이지의 CSS·WAAPI 애니메이션을 t 에 세운다.
+// 렌더 때는 시계가 애니메이션마다 태어난 시각을 기억해 맞추므로 이걸 쓰지 않는다.
+export function syncCss(t: number, root: Document | Element = document): void {
+  const ms = t * 1000;
+  const list = root instanceof Document ? root.getAnimations() : root.getAnimations({ subtree: true });
+  for (const a of list) {
+    if (a.timeline !== document.timeline && a.timeline !== null) continue;
+    if (a.playState !== "paused") a.pause();
+    a.currentTime = ms * (a.playbackRate || 1);
+  }
+}

package/packages/adapters/src/gsap.ts

@@ -0,0 +1,26 @@
+import { onSeek } from "./page.ts";
+
+interface TimelineLike {
+  pause(): unknown;
+  totalTime(t: number, suppressEvents?: boolean): unknown;
+  autoRemoveChildren?: boolean;
+}
+interface GsapLike {
+  ticker: { lagSmoothing(threshold: number, adjustedLag?: number): void };
+  globalTimeline: TimelineLike;
+}
+
+// step 모드에서는 가상 rAF·performance.now 로 GSAP 이 스스로 돈다 — 렉 보정만 끈다.
+// seek 모드에서는 타임라인(없으면 globalTimeline)을 멈추고 seek 마다 그 시각으로 옮긴다.
+export function bindGsap(gsap: GsapLike, opts: { timeline?: TimelineLike; from?: number } = {}): () => void {
+  gsap.ticker.lagSmoothing(0);
+  if (window.__kf?.mode === "step") return () => {};
+  const tl = opts.timeline ?? gsap.globalTimeline;
+  const from = opts.from ?? 0;
+  // globalTimeline 은 끝난 트윈을 빼 버려서, 끝을 지나 찾아갔다가 뒤로 오면 트윈이 사라진다.
+  tl.autoRemoveChildren = false;
+  tl.pause();
+  return onSeek((t) => {
+    tl.totalTime(Math.max(0, t - from), true);
+  });
+}

package/packages/adapters/src/index.ts

@@ -0,0 +1,9 @@
+export { definePage, onSeek, clock } from "./page.ts";
+export type { KfPage, KfPageMeta, KfMarker, KfMode, PageOptions } from "./page.ts";
+export { mountProject, projectMarkers } from "./project.ts";
+export type { KfProjectJson, KfSceneEntry, MountOptions, SceneModule, SceneDraw } from "./project.ts";
+export { syncCss } from "./css.ts";
+export { syncMedia, mediaTime } from "./media.ts";
+export { bindLottie } from "./lottie.ts";
+export { bindGsap } from "./gsap.ts";
+export { bindThree } from "./three.ts";

package/packages/adapters/src/lottie.ts

@@ -0,0 +1,22 @@
+import { onSeek } from "./page.ts";
+
+interface LottieLike {
+  pause(): void;
+  goToAndStop(value: number, isFrame?: boolean): void;
+  totalFrames?: number;
+  frameRate?: number;
+}
+
+// lottie-web 애니메이션을 시각에 묶는다. 만들 때 autoplay:false 를 권한다.
+export function bindLottie(anim: LottieLike, opts: { from?: number; rate?: number; loop?: boolean } = {}): () => void {
+  const from = opts.from ?? 0;
+  const rate = opts.rate ?? 1;
+  anim.pause();
+  return onSeek((t) => {
+    let ms = Math.max(0, (t - from) * rate * 1000);
+    if (opts.loop && anim.totalFrames && anim.frameRate) {
+      ms %= (anim.totalFrames / anim.frameRate) * 1000;
+    }
+    anim.goToAndStop(ms, false);
+  });
+}

package/packages/adapters/src/media.ts

@@ -0,0 +1,59 @@
+// <video data-kf-from="2.5" data-kf-rate="1"> — 영상 위 시각 from 에 0 초부터 튼다. loop 속성이면 되감는다.
+// 소리는 렌더가 곡을 따로 얹으므로 여기서는 늘 끈다.
+function waitSeeked(v: HTMLVideoElement): Promise<void> {
+  const realTimeout = window.__kfClock?.real.setTimeout ?? setTimeout;
+  return new Promise((resolve) => {
+    const done = () => resolve();
+    v.addEventListener("seeked", done, { once: true });
+    realTimeout(done, 3000);
+  });
+}
+
+// seeked 는 디코더 쪽 준비일 뿐, 합성기가 새 프레임을 받기 전에 찍으면 직전 프레임이 나온다.
+// requestVideoFrameCallback 은 멈춘 영상에서 헤드리스가 거의 부르지 않아, 진짜 렌더링 기회를 두 번 넘긴다.
+function waitPresented(): Promise<void> {
+  const raf = window.__kfClock?.real.requestAnimationFrame ?? requestAnimationFrame;
+  return new Promise((resolve) => raf(() => raf(() => resolve())));
+}
+
+export function mediaTime(v: HTMLMediaElement, t: number): number {
+  const from = Number(v.dataset.kfFrom ?? 0);
+  const rate = Number(v.dataset.kfRate ?? 1);
+  let local = Math.max(0, (t - from) * rate);
+  const d = v.duration;
+  if (Number.isFinite(d) && d > 0) local = v.loop ? local % d : Math.min(local, Math.max(0, d - 0.001));
+  return local;
+}
+
+export async function syncMedia(t: number, root: ParentNode = document): Promise<void> {
+  const rendering = !!window.__kfClock;
+  const jobs: Promise<void>[] = [];
+  for (const a of Array.from(root.querySelectorAll("audio"))) {
+    if (rendering) {
+      a.muted = true;
+      if (!a.paused) a.pause();
+    }
+  }
+  for (const v of Array.from(root.querySelectorAll("video"))) {
+    v.muted = true;
+    if (!v.paused) v.pause();
+    // 받지 못한 영상은 seeked 가 오지 않는다 — 기다리지 않고 넘긴다(ready 가 이미 경고했다).
+    if (v.readyState === HTMLMediaElement.HAVE_NOTHING || v.error) continue;
+    const local = mediaTime(v, t);
+    if (Math.abs(v.currentTime - local) < 1e-4) continue;
+    v.currentTime = local;
+    jobs.push(waitSeeked(v));
+  }
+  await Promise.all(jobs);
+  if (jobs.length) {
+    await waitPresented();
+    // 부하가 걸리면 합성기가 더 늦는다. 렌더러가 이 표시를 보고 그림이 멈출 때까지 다시 찍는다.
+    window.__kfMediaMoved = true;
+  }
+}
+
+declare global {
+  interface Window {
+    __kfMediaMoved?: boolean;
+  }
+}