kasaframe 0.1.1 → 0.1.4

package/docs/AGENTS.md

@@ -8,14 +8,34 @@
 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 <모델>` 을 줄 때만.
+- **기본 `--model claude-code`**(Claude Code 안팎·작업실 어디서 부르든): 뼈대·곡 분석·장면 지시서 `MAKE.md` 까지 만들고 멈춘다. 다른 모델을 부르지 않는다. **`MAKE.md` 맨 위에 「사용자에게 먼저 물을 것」이 있으면 장면을 쓰기 전에 사람에게 한 번에 묻는다**(AskUserQuestion 한 번에 질문 여럿 — 적힌 `header` 를 칩으로, 보기 첫째가 권장) → 답을 `kf make --answer <폴더> --theme <값> --voice <값> --image <값> …` 로 넣으면 지시서가 고쳐진다(테마 답은 style.json·kf.json·장면 뼈대까지 바꾼다). 그다음 「만들 그림」·「주인공 3D 장면」·「영상 모델 컷」을 보고 네가 구체적인 프롬프트로 고른 공급자에 `kf gen img`·`kf blender`·`kf gen vid` 를 부른다(받은 자산·실제 화면·도형으로 되면 만들지 않는다). 장면을 다 채우고 `kf look <폴더>` 가 찍는 장면 모음·확인표를 직접 본 뒤 `kf make --finish <폴더>`(렌더·검사·표지·자막. 그림 보는 모델도 안 부르고 끝에 장면 모음·확인표 경로를 다시 찍는다).
+- **OG 모드**(짚을 때만 — `--model deepseek/deepseek-v4-pro` 같은 이름): 장면 작성·고치기까지 OG `chat/completions` 로 끝까지. 그림 검사는 `--vision-model <모델>` 을 줄 때만. Opus·GPT 계열(`anthropic/claude-opus*`·`openai/gpt*`·`gpt-*`·`o3` 따위)은 `--allow-premium`(또는 `KF_ALLOW_PREMIUM=1`) 없이는 부르기 전에 막는다. 끝나면(성공·실패·중단) `<폴더>/make-stats.json` 에 단계별 모델·ms·토큰·usd 와 합계, 마지막 줄 「OG 호출 N번 · 입력/출력 토큰 · $X」.
 - **그림 보기는 세션이 직접**: `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).
+- **곡**: 홍보·공개·뮤비는 곡이 끌고 간다. `--music` 을 안 주면 곡 모음(`KF_MUSIC_DIR`, 없으면 레포 `music/` — 곡마다 원본·라이선스·분위기 태그는 `music/tags.json`·`README.md`. npm 패키지에는 곡이 없다)에서 요청 낱말과 맞는 곡을 고른다. 곡 모음이 비었으면 `--music` 으로 준다.
+- **목소리·곡(쇼츠·설명)**: 차분한 TTS 내레이션 + 깊은 앰비언트 곡(`deep`)이 기본이다. 곡은 분위기 태그가 맞는 곡 모음 곡을 묻지 않고 고르고(같은 틀이면 늘 같은 곡), 없으면 생성(Lyria·Eleven Music, 돈)·곡 넣기·없음을 묻는다. 목소리는 늘 맨 위 질문으로 묻는다 — 보기 차례 로컬 Qwen3(`KF_QWEN3_TTS_URL` 이 있을 때)·ElevenLabs(키가 없으면 넣는 법)·자막만·그 밖 엔진(`kf narrate --voices`). 로컬도 ElevenLabs 도 없거나 생성 키가 없으면 다른 엔진·「자막만」·「곡 없이」로 넘어가지 말고 맨 위 질문대로 사람에게 묻는다(키 넣기가 권장). 묻지 않으려면 `--voice <엔진>:<목소리>|none`·`--music <곡>|gen:lyria-3.5|none`. 그다음은 아래 「내레이션 먼저」.
+- **용도·테마**: 용도는 확신이 낮을 때만 묻는다. 테마는 요청이 「리소 느낌으로」처럼 짚었거나 시리즈가 정했으면 그대로, 아니면 맨 위 질문으로 묻는다 — 테마는 「세계 × 변주」(세계 = 비유와 효과 코드, 변주 = 겉모습만 바꾼 판 `<세계>/<변주>`, 예 `og-measure/night-amber`)라 수백 판이고, 보기는 「알아서」(= `auto`, 첫 후보)와 요청·용도·분위기 낱말에 맞는 넷뿐이다. 질문 글에 넷만 담은 견본 시트 경로가 붙는다 — 그 그림을 사람에게 보인다. 사람이 보기 밖으로 분위기 한 마디나 그림·주소를 주면 `kf make --answer <폴더> --theme-mood "<말>"`·`--theme-ref <경로|URL>` 로 넣는다(후보 넷·시트·MAKE.md 를 다시 고쳐 쓰고 종료 3 — 다시 묻는다). 답이 오기 전 뼈대는 첫 후보로 깔려 있다. 못 박으려면 `--purpose <용도>`·`--theme <id>`, 테마 없이 프리셋만이면 `--theme none`. **시리즈**(`kf series list` — 예 「OG 쇼츠」)를 짚으면 용도·테마보다 먼저 그 묶음(용도·테마·목소리·곡·자막·길이·끝 카드·생성 답)으로 묻지 않고 간다 — 같은 시리즈면 매번 같다. 잘 나온 프로젝트를 묶음으로: `kf series new <id> --from <폴더> --match "…"`. 같은 말이 같은 결과를 내는지는 `kf bench "<요청>" --runs 3`. 묻는 것은 용도 확신이 낮을 때뿐(종료 코드 3).
 - **작업실**: `kf app` 이 떠 있으면 `kf make` 가 거기에 등록하고 주소를 찍는다 — 사람은 페이지에서 실시간 미리보기·지난 작업을 본다.
 - **Claude Code 스킬**: `kf skill install` 하면 「영상 만들어」 같은 말에 kasaframe 으로 오는 스킬이 깔린다(`skills/kasaframe/SKILL.md`).
-- 영상 생성 모델은 요청 글에 「영상 생성」을 적었을 때만 쓴다(이음매 기본은 3D 모션그래픽 전환). 영상은 `--yes` 가 있어야 돈을 쓴다.
+- **생성 능력**(`kf doctor` 「생성 능력」): 계획은 그림 컷·주인공 3D 장면(Blender 툰 샷, 없으면 three.js)·이음매 3D 전환(three)·캐릭터가 실제로 움직이는 컷(영상 모델 — 요청에 캐릭터와 몸짓이 있거나 뮤비일 때)·곡·내레이션을 기본으로 넣는다. **묻는 것은 돈이 들거나 없는 능력뿐**이고 나머지는 틀·테마가 정한 기본값으로 간다 — 같은 말이면 같은 결과. **없는 능력은 조용히 대체하지 않는다** — 「키·도구 넣는 법(권장) · 지금 되는 다른 엔진 · 빼기(자막만·곡 없이)」를 사람에게 묻고 고른 값을 플래그로 넣는다. 네가 대신 길을 고르지 않는다(`--yes` 로도 안 넘어간다). 키는 `kf setup key <이름>` 이 숨겨 받는다. 묻지 않고 가려면 `--yes`(권장 답 — 돈도 쓴다) · `--no-gen`(돈 안 드는 길) · `--allow image,video,…`(목록 능력만 권장, 나머지는 돈 안 드는 길) · `--image`·`--video`·`--blender`·`--voice`·`--music <값>`(그 질문에 미리 답). OG 모드는 뼈대 전에 터미널에서 묻고, 터미널이 아니면 보기를 찍고 종료 코드 3.
+- **H3**(사내 파드 `h3-pod`)는 0원이지만 MiniMax 공개 가중치가 한국을 제외 지역으로 둔다 — 회사·바깥 결과물엔 쓰지 않는다. 보기에 경고가 붙고 `--yes` 로는 골라지지 않으며, 쓰면 자산 메타·`out/<영상>.credits.json`·`kf check` 의 `asset.restrict` 에 남는다. API 판 `minimax-h3` 는 전 세계 가능.
+
+### 감독 모드(기본) — 장면 코드 대신 `content.json`
+
+뮤비가 아니면 `kf make` 는 감독 모드다. **너는 `content.json` 하나만 쓴다** — 장면마다 무엇을 보일지(type·칸)와 들릴 말(say)·출처(source). 화면 문법·움직임·전환·카메라·바탕은 감독이 검증된 패턴 중에서 고른다(같은 content.json·씨앗이면 바이트까지 같은 장면). 칸 표는 `MAKE.md` 「content.json 꼴」이 정본(계약 11).
+
+```
+kf make "OG 쇼츠 — MLA 가 뭔지 45초"      # 뼈대·묻기·MAKE.md(content.json 쓰는 법)까지
+# <폴더>/content.json 을 쓴다 — {"title", "scenes": [{"id", "type": "hook-number", "value": 57, "unit": "×", "label": "…", "say": "…", "source": "…"}, …]}
+kf direct <폴더>                         # 칸 검사 → 내레이션으로 길이 → 패턴 고르기·장면 파일 → kf check(떨어진 장면만 다음 후보로)
+kf look <폴더>                           # 장면 모음을 직접 본다 — 마음에 안 들면 content.json 을 고치거나 --seed <글>
+kf make --finish <폴더>
+kf direct content.json                   # 폴더 없이 바로 — content.json 옆 같은 이름 폴더에 뼈대부터
+```
+
+- type: `hook-number`·`compare`·`bars`·`steps`·`before-after`·`timeline`·`flow`·`fill`·`formula`·`term-reveal`·`limit`·`toggle-sim`·`list`·`quote`·`end`·`title`·`words`·`trend`·`code`·`screen`·`media`·`custom`. 숫자는 `value`·`unit` 따로, 숫자가 있으면 `source` 꼭, 문장은 `say` 로(화면 칸은 낱말·숫자).
+- 칸이 틀리면 `kf direct` 가 `scenes[2].total: 없다 — …` 처럼 짚고 멈춘다. 고를 패턴·까닭은 `director.json`.
+- 장면 하나만: `kf direct <폴더> --scenes b` · 후보를 사람이 고르기 `--pattern b=<패턴 id>` · 그 장면만 다른 그림 `--scene-seed b=<글>`(둘 다 director.json `pinned` 에 남는다).
+- 패턴에 없는 화면은 `{"type": "custom", "idea": "…"}` — kf direct 가 뼈대만 두고 그 파일은 네가 쓴다(아래 3장). 감독 없이 처음부터 장면 코드를 쓰려면 `kf make … --no-direct`.
 
 **규칙 — 단 0.1초도 쉬지 않는다**(검사가 오류로 잡는다. 용도마다 틀이 기준을 정한다 — 아래 표, 이 영상의 값은 MAKE.md 첫머리): ① 0.1초(60fps 6프레임) 넘게 화면이 안 바뀌면 오류 — 끝 카드·큰 숫자·로고도 예외 없음 ② 같은 구도가 표의 초를 넘으면 경고·오류 — 새 요소·칸 채우기·숫자 키우기·컷·전환 ③ 미세한 흔들림 말고 눈에 보이는 큰 움직임 — 표의 자리에서 박마다 하나 이상 ④ 주 요소가 화면을 채운다(세로는 폭 70% 넘게). 쉬지 않는 몫은 **화면 안 움직임**이 진다 — 카메라는 이유가 있을 때만 움직인다(3장 「카메라」). `kf new` 가 넣어 주는 `lib/stage.ts`(`makeStage`·`makeCamera`·`bigWord`·`cutTimes`·`lastT`)가 이걸 처음부터 넘게 짜 둔 무대다 — 장면을 하나하나 고치기 전에 겉에 씌워라.
 
@@ -76,6 +96,7 @@ export default {
 };
 ```
 
+- **연출 수는 뼈대에 이미 걸려 있다**: `kf new` 가 장면마다 바탕·글·경계 덮기(`DRESS`)를 용도·테마 묶음에서 골라 넣는다(같은 요청이면 같은 수). 수는 두고 `WORDS` 와 내용을 바꾼다 — 바꿀 이름은 `MAKE.md` 「연출 수」, 수만 따로 본 예시는 `examples/moves/`.
 - `t` 는 **장면 안 초**(장면 시작 = 0). 반환 함수는 **같은 t 면 같은 화면** — 앞 프레임 상태를 쌓지 않는다.
 - DOM 은 `build` 에서 한 번 짓고, `(t) => …` 에서는 글·스타일만 바꾼다.
 - 박자는 `ctx.beats`(`drop(0)`·`nearestBeat`·`phrase`·`inDrop`), 그림은 `ctx.asset("x.png")`, 글은 `ctx.safe` 안에.
@@ -94,7 +115,7 @@ export default {
 기본은 **정지**, 주인공은 안전 영역 가운데. 화면 전체를 사인으로 흔들거나 박마다 자세를 바꾸면 격자가 기울고 주인공이 가장자리로 밀린다 — `kf check` 가 `camera.wander`(이유 없는 카메라 이동)·`layout.edge`(주인공이 안전 영역 가장자리 4% 띠에) 로 경고한다. 카메라는 장면이 이유를 댈 때만:
 
 ```ts
-const stage = makeStage(root, ctx);   // 흐르는 바탕 + 컷마다 모양을 바꾸는 바탕 판 + 정지 카메라
+const stage = makeStage(root, ctx);   // 정지 바탕(still) + 정지 카메라 — stage.say(낱말) 이면 글 수 + 박마다 차는 강조 띠
 stage.camera
   .pushIn(2.0, { to: answer })        // 드러냄에 다가가기 — 요소 상자를 가운데로, 안전 영역 86% 안에 들게 배율을 누른다
   .pullOut(5.5)                       // 비교 전체를 보이게 물러나기 — 기본은 처음 구도. 더 넓게는 { scale: 0.9 }
@@ -119,21 +140,42 @@ return (t: number) => {
 - 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 폴더).
+- **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` 로 몇 장 본다. 앞뒤 2D 장면과 공간을 이으려면 `--match` 로 굽고 샷에서 `kfb.match_start`·`match_end`(첫·끝 프레임을 그 2D 화면과 투영 일치)·`rise_block`(주인공 칸이 같은 자리에서 3D 로 선다) — 맞춘 경계는 컷이어도 이어진다. 맞추지 않은 2D↔3D 경계는 이음매 `rise`(2D→3D)·`land`(3D→2D). 예시·쓰는 법: `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)`) — 움직임을 거기서 끝내야 끝 화면과 첫 화면이 픽셀까지 같다.
 
+### 내레이션 먼저 — 쇼츠·설명
+
+말이 장면 길이를 정한다. 장면을 쓰기 **전에**:
+
+```
+# 1. captions.json — 장면마다 들릴 말(차분한 설명체, 마디는 쉼표, 문장은 마침표, 1초에 4–5글자, 훅은 한 마디, 끝·이음매는 비워도 된다)
+[{"scene": "hook", "text": "모든 낱말이, 서로를 봅니다."}, {"scene": "setup", "text": "..."}]
+# 2. 읽혀서 장면 길이를 목소리에 맞춘다(곡이 있으면 다음 박에) — 같은 문장·목소리는 캐시라 다시 불러도 0원
+kf narrate <폴더> [--voice elevenlabs:George] [--music <곡>|gen:lyria-3.5|none]
+kf narrate --voices                                  # 쓸 수 있는 엔진·목소리
+kf narrate --say "한 문장" --voice elevenlabs:George  # 한 문장만 들어 본다 → say.wav
+```
+
+- 장면 길이 = 앞 숨(틀 `narration.lead`) + 말 + 뒤 숨(`tail`). 요청에 길이(「30초」)가 있으면 빠르기를 **0.9–1.1 안에서만** 맞추고 남는 시간은 뒤 숨으로 편다 — 그래도 길면 「대본을 줄이면 맞는다」고 알려 준다. 대본을 줄인다(빠르기를 더 올리지 않는다).
+- `kf.json` 장면 시각이 바뀐다 — 장면은 그 뒤에 쓰고 `ctx.dur` 로 짠다. 문장을 고치면 `kf narrate` 를 다시.
+- `captions.json` 줄마다 `words`(영상 기준 초)가 생긴다 — 그 낱말이 들리는 순간에 같은 낱말·도식이 서게 맞춘다(`w.from - ctx.from` 이 장면 안 시각, `import.meta.glob("../captions.json", { eager: true, import: "default" })`). 화면 글 정책은 그대로 — 문장은 소리·자막으로 가고 화면엔 전문 낱말만.
+- 섞기는 `kf render` 가 한다: 말할 때 곡은 목소리보다 20dB 안팎 아래(덕킹), 끝 1.5초 페이드, -14 LUFS(틀 `audio`). 소리를 따로 만지지 않는다.
+- `kf make --finish` 가 `kf narrate` 를 안 거친 프로젝트를 만나면 먼저 부른다(문장이 없으면 곡만 깐다).
+- 곡 모음: `kf music list --mood deep` · 생성 곡을 모음에 넣기 `kf music gen --mood deep --dur 60 --add`(원본·라이선스가 태그에 남는다).
+
 ### 뮤비 가사 — `kf lyrics align` · JIZURA 가사 층
 
 ```
-npx kf setup jizura lyrics                                   # 한 번만 — 가사 층 엔진·한글 글꼴(60MB), 정렬 꾸러미(2GB)
+npx kf setup lyrics                                          # 한 번만 — 정렬 꾸러미(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 으로 띄운다.
+- `kf new --template mv` 의 장면은 프로젝트 뿌리의 `lyrics.json` 을 JIZURA 가사 층으로 그린다 — 벌스는 차분한 플랜, 드롭(`ctx.beats.inDrop`)부터 큰 플랜. `lyrics.json` 이 없으면 부른 낱말을 DOM 으로 띄운다.
+- 가사 층 글꼴: 자주 쓰는 한글 얼굴은 실려 있고, 나머지 얼굴·한자·가나는 처음 굽거나 볼 때 받는다. 못 받으면 다른 글꼴로 대신 그리지 않고 `kf render`·`kf check` 가 끝에 묻는다(종료 3) — **사람에게 묻고**(네가 대신 고르지 않는다) 답을 `kf lyrics use <폴더> wait|builtin|words` 로 넣은 뒤 같은 명령을 다시. 오프라인으로 구울 기계면 `kf setup jizura` 로 미리 받아 둔다.
 - 직접 쓸 때: `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` 경고로만 나온다 — 읽혀야 할 가사 줄이 잘리면 그 부품을 막는다.
@@ -147,7 +189,7 @@ npx kf lyrics align 곡.mp3 --text 공식가사.txt --lang ko --out <폴더>/lyr
 - **크기를 className CSS 로 받는 컴포넌트**(캔버스 등)는 그대로 넣으면 300×150 — 장면에 `<style>` 로 그 클래스 크기를 준다.
 - **스크린리더 전용 글**(1px·clip 으로 숨긴 span)은 검사가 대비·화면 밖 판정에서 뺀다. 그래도 걸리면 그 클래스를 `display:none`.
 - **`build` 에서 장면이 숨어 있다**(앞 장면 차례엔 `display:none`) — 그때 잰 크기는 0 이다. 크기는 글자 수로 어림하거나(`fitPx`) 처음 그려질 때 잰다.
-- **0.1초 규칙** — 끝 카드·큰 숫자 화면이 제일 먼저 걸린다. 구도는 칸 평균 밝기와 화면 안 내용(글·칸의 센 가장자리 지도) 둘로 본다 — 숫자가 구르고 칸이 차고 줄이 붙으면 바뀐 것으로 치지만, 빛 방울·모눈 같은 부드러운 바탕 흐름만으로는 안 바뀐다. 컷(`cutTimes`)마다 화면 안 내용을 바꾼다(새 줄·칸 채우기·숫자 키우기·바탕 판).
+- **0.1초 규칙** — 끝 카드·큰 숫자 화면이 제일 먼저 걸린다. 구도는 칸 평균 밝기와 화면 안 내용(글·칸의 센 가장자리 지도) 둘로 본다 — 숫자가 구르고 칸이 차고 줄이 붙으면 바뀐 것으로 친다(바탕은 정지 — 뜻 없이 흐르는 장식으로 메우지 않는다). 컷(`cutTimes`)마다 화면 안 내용을 바꾼다(새 줄·칸 채우기·숫자 키우기·바탕 판).
 
 ## 4. 보기 — `kf preview` · `kf still` · `kf sheet`
 
@@ -166,13 +208,17 @@ kf look <폴더> --vision-model google/gemini-3.5-flash   # 그림을 못 보는
 ## 5. 굽기 — `kf render`
 
 ```
-kf render <폴더> [--tabs 2]       # → out/render.mp4 + out/render.json(markers·움직임 기록)
+kf render <폴더> [--tabs 2]       # → out/render.mp4 + out/render.json(markers·움직임 기록) — 장면 조각으로, 바뀐 장면만 다시 찍는다
+kf render <폴더> --scenes hook    # 그 장면 조각만(out/segments/hook-<해시>.mp4) — 잇기는 다음 kf render
 kf render <폴더> --from 10 --to 14 --no-lock   # 고친 구간만 빨리
+kf render <폴더> --motion-blur 8 [--shutter 180]  # 한 프레임을 하위 프레임 8장 평균 — 빠른 것만 번진다(seek 모드만, 그만큼 느리다)
 ```
 
+쇼츠·홍보 틀은 `kf.json` 의 `render.motionBlur` 로 모션 블러를 기본으로 켠다 — 끌 땐 `--motion-blur 0`.
+
 ### 자막 켜고 끄기
 
-들릴 말은 장면 파일이 아니라 `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`(장면 전체를 띠 위로 줄여 올린다 — 안 겹치지만 내용이 작아지고 움직이는 면적도 준다).
+들릴 말은 장면 파일이 아니라 `captions.json` 에 쓴다 — `[{"scene": "<id>", "text": "짧은 마디를 쉼표로"}]`(`from`·`to` 초나 `words` 낱말 시각도 된다). `kf.json` 의 `captions` 가 `off`(쇼츠·설명 기본 — srt·vtt 만) · `on`(화면에 얹고 srt·vtt 도) · `none`. 화면 자막은 엔진이 장면 위에 판을 얹는다(안전 영역 아래쪽 가운데, 테마 글꼴, 어절 단위 두 줄까지, 세로 화면은 폭의 8% 크기 — `style.json` 의 `"captions": { "size": 50, "position": 1400, "maxLines": 2 }` 로 글자 px·판 가운데 y·줄 수를 덮는다, srt·vtt 마디도 같은 값) — 장면에 문장을 쓰지 않는다. 켜면 `ctx.safe` 아래쪽에서 자막 띠(판 두 줄 높이)를 뺀다 — 무대(`makeStage`)처럼 `ctx.safe` 로 배치하는 장면은 제 크기 그대로 띠 위로 올라간다. 픽셀을 박아 둔 장면은 안 움직여 `kf check` 가 `caption.overlap` 으로 잡는다 — 글을 `ctx.safe` 안으로 옮기거나, 장면을 못 고치면 `--captions fit`(장면 전체를 띠 위로 줄여 올린다 — 안 겹치지만 내용이 작아지고 움직이는 면적도 준다).
 
 ```
 kf render <폴더> --captions on --suffix   # 다시 만들지 않고 자막 판만 → out/render-자막.mp4 (원본은 그대로). fit 이면 장면을 줄여 올린다
@@ -201,11 +247,11 @@ kf check <폴더>/out/render.mp4    # 영상만 있을 때 — 프레임 차 + O
 | `text.safe-area` | 플랫폼 UI 가 가리는 자리에 글 | `ctx.safe` 안으로 |
 | `text.contrast` | 바탕과 대비가 낮다 | 글 색이나 바탕을 3:1 이상 벌린다. 덮개 아래 글이면 덮개를 걷는다 |
 | `text.small` · `text.crowded` | 틀이 정한 글 크기·한 화면 글 수를 넘었다 | 낱말을 줄이고 키운다(터미널·코드 화면이면 둬도 된다) |
-| `frame.freeze` | 0.1초 넘게 거의 안 바뀐다(30fps 로 훑는다) | 늘 도는 화면 안 움직임 — 숫자 굴러가기·반짝임·`makeStage` 의 흐르는 바탕을 겉에, 끝 카드도 |
+| `frame.freeze` | 0.1초 넘게 거의 안 바뀐다(30fps 로 훑는다) | 내용의 움직임 — 숫자 굴러가기·칸 채우기·연결선·`stage.say` 의 박마다 차는 강조 띠, 끝 카드도. 뜻 없는 장식(떠다니는 방울·판)으로 메우지 않는다 |
 | `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`, 도식 확대, 화면을 채우는 면 |
+| `layout.fill` | 장면 내용이 안전 영역의 12% 아래(오류) · 세로 화면 폭 70%·높이 55% 아래(경고 — 높이는 자막 띠를 빼고 잰다) | 주 요소를 키운다 — `bigWord`·`fitPx`, 도식 확대, 화면을 채우는 면. 세로 화면은 위아래로 쓴다(큰 숫자 아래 자·막대, 목록은 세로로 쌓기) |
 | `caption.overlap` | 화면 자막 판이 장면 글을 덮는다(경고) | 그 글을 `ctx.safe` 안으로 — 자막을 켜면 안전 영역 아래쪽 띠 자리가 빠진다. 장면을 못 고치면 `--captions fit` |
 | `frame.spike` | 한 프레임만 앞뒤와 크게 다르다(경고) — 깜빡임·한 프레임 오류 | 그 시각 장면의 조건 분기·켜고 끄기 경계를 본다. 일부러 한 섬광·컷이면 드롭·장면 경계에 붙인다(거기선 안 센다) |
 | `frame.flash` | 화면 25% 넘게 번쩍이는 섬광이 1초에 3번 넘게(빛 민감 발작 — `style.json` `motion.maxFlashPerSec`) | 박마다 섬광이면 두 박·한 마디에 한 번으로, 섬광 연타는 2마디 안. 빠른 곡(150BPM 넘게)은 반 박이 아니라 2박에 한 번 |
@@ -220,15 +266,17 @@ kf check <폴더>/out/render.mp4    # 영상만 있을 때 — 프레임 차 + O
 | `motion.repeat` | 이어지는 두 장면이 같은 등장 움직임 | 한쪽을 다른 `enter` 로 |
 | `asset.*` | 생성 자산의 라이선스·지역 제한·투명 실패 | 밖에 내기 전에 사람에게 알린다 |
 
-고친 뒤: 그 구간만 `kf check <폴더> --from 10 --to 14` → 다 고쳤으면 `kf render` → `kf check <영상>`.
+고친 뒤: 그 구간만 `kf check <폴더> --from 10 --to 14` → 다 고쳤으면 `kf render` → `kf check <영상>`. `kf render` 는 장면마다 조각(`out/segments/`)을 두고 그 장면이 불러온 파일·자산·kf.json 그 장면 칸이 그대로면 다시 찍지 않는다 — 이음매는 앞뒤 장면을 고치면 같이 다시. 장면 몇 개만 고쳤으면 `kf make --finish <폴더> --scenes a,b`(바뀐 조각만 굽고 그 구간만 검사), 그 장면을 모델에게 다시 쓰게 하려면 `kf make --rewrite <폴더> --scenes a`(감독 프로젝트는 content.json 의 그 장면을 고치고 같은 명령 — `--pattern a=<패턴>`·`--scene-seed a=<글>` 로 다른 후보).
 
 ## 8. 없는 그림·영상 — `kf gen`
 
 ```
+kf doctor                                              # 생성 능력 — 지금 쓸 수 있는 공급자·권장·견적·켜는 법
 kf gen models                                          # 키·단가 표
-kf gen img "<구체적 프롬프트>" --id hook-bg --project <폴더> [--size 1080x1920 --transparent --ref a.png]   # 그림 한 장 — 돈이 든다(한 장 $0.25 상한)
+kf gen img "<구체적 프롬프트>" --id hook-bg --project <폴더> [--size 1080x1920 --transparent --ref a.png] [--provider codex-imagegen]   # 그림 한 장 — OG 는 돈이 든다(한 장 $0.25 상한), codex-imagegen 은 ChatGPT 로그인으로 0원(1–2분)
 kf gen plan <폴더> [--yes]                             # plan.json 의 gen:img·gen:vid 를 다 만든다
 kf gen seam <폴더> <장면id> "<프롬프트>" --yes          # 앞 장면 끝 → 다음 장면 첫 프레임을 잇는 전환 클립
+kf music gen --mood deep --dur 45 [--provider lyria-3.5]   # 분위기 곡 — 분위기·길이 칸이 같으면 캐시에서 같은 곡
 ```
 
 영상은 `--yes` 가 없으면 견적만 내고 종료 코드 3 — 돈이 드는 호출은 사람 승인 뒤에. 단가·라이선스: `packages/gen/PROVIDERS.md`.

package/music/README.md

@@ -1,13 +1,37 @@
 # 곡 모음 — kf make 가 곡을 안 받았을 때 고르는 곳
 
-`kf make` 는 곡이 필요한 용도(홍보·공개·뮤비)인데 `--music` 이 없으면 여기서 요청 낱말과 파일 이름이 맞는 곡을 고른다(「카와이·퓨처베이스·칠·로파이·애니…」 같은 한국어 장르 낱말은 영어로도 찾는다). 다른 폴더를 쓰려면 `KF_MUSIC_DIR=<폴더>`.
+곡마다 **분위기 태그**·원본·라이선스를 `tags.json` 에 둔다(사람용 표는 아래). 다른 폴더를 쓰려면 `KF_MUSIC_DIR=<폴더>` — 그 폴더에도 `tags.json` 을 둔다.
 
-곡 파일은 깃에 올리지 않는다(`.gitignore`) — 아래 표의 원본에서 받아 이 폴더에 둔다. 파일 이름에 장르·분위기 낱말을 넣어 두면 잘 골린다.
+- 틀이 분위기를 정한 용도(쇼츠·설명은 `deep`)는 그 분위기 태그가 맞는 곡을 **묻지 않고** 고른다 — 맞은 태그가 많은 곡, 같으면 파일 이름 순이라 같은 틀이면 늘 같은 곡이다. 맞는 곡이 없을 때만 음악 생성(돈)·곡 넣기·없음을 묻고, 생성 키도 없으면 다른 분위기 곡이나 「곡 없이」로 넘어가지 않고 곡·키 넣는 법을 권장으로 묻는다.
+- 곡이 끌고 가는 용도(홍보·공개·뮤비)는 `--music` 이 없으면 요청 낱말과 파일 이름이 맞는 곡을 고른다(「카와이·퓨처베이스·칠·로파이·애니…」 같은 한국어 장르 낱말은 영어로도 찾는다).
+- 라이선스를 모르는 곡은 분위기로 고르는 데서 빠진다. 출처를 모르는 곡은 넣지 않는다.
 
-| 파일 | 곡 | 장르 · 길이 | 원본 · 라이선스 |
+곡 파일은 깃에 올리지 않는다(`.gitignore`) — 아래 표의 원본에서 받아 이 폴더에 둔다. 생성 곡은 `kf music gen --mood deep --dur 60 --add` 로 다시 만든다(같은 기계면 캐시에서 같은 곡, 다른 기계면 같은 프롬프트의 새 곡).
+
+```
+kf music list [--mood deep]
+kf music add <곡> --mood deep,ambient --source <원본 주소> --license "<라이선스>" [--title 이름]
+kf music gen --mood deep --dur 45 [--provider lyria-3.5|elevenlabs-music] [--add]
+```
+
+## 분위기
+
+| 이름 | 곡 태그(하나라도 맞으면 후보, 많이 맞을수록 앞) | 생성 프롬프트 결 |
+|---|---|---|
+| `deep` | deep · ambient · cinematic · minimal · piano · calm · dark | 딥 앰비언트·미니멀 시네마틱, 낮은 패드·느린 피아노·서브 드론, 타악은 멀리 약하게, 70 BPM 안팎, 말소리 중역을 비워 둔다 |
+| `bright` | upbeat · bright · pop · kawaii · future-bass | 밝은 일렉트로 팝, 110 BPM |
+| `calm` | calm · lofi · chill · piano · ambient | 차분한 로파이, 80 BPM |
+| `epic` | epic · cinematic · orchestral · trailer | 시네마틱 현·금관, 90 BPM |
+
+프롬프트 원문은 `packages/gen/src/music/library.ts` 의 `MOOD_PROMPT` — 요청 글을 섞지 않아서 분위기·길이 칸(30·45·60·90·120…초)이 같으면 같은 프롬프트다.
+
+## 곡
+
+| 파일 | 곡 | 분위기 · 장르 · 길이 | 원본 · 라이선스 |
 |---|---|---|---|
-| `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 · 같은 라이선스 |
+| `kawaii-friends.mp3` | Kawaii Friends — ckotty3 | bright·kawaii·future-bass·upbeat · 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 | bright·upbeat·anime · Anime · 1:49 · 107 BPM | Pixabay · 같은 라이선스 |
+| `gummy-drive-mvncm.mp3` | Gummy Drive — mvncm | (태그 없음) · 2:00 안팎 | Pixabay · 같은 라이선스 |
+| `deep-lyria-3.5-60s.mp3` | deep 60초 (lyria-3.5 생성) | deep·ambient·cinematic·minimal · 60.3초 | Gemini API Lyria 3.5 생성(MOOD_PROMPT.deep, 2026-10-09) · Google 생성형 AI 약관 — 출력물 소유권 주장 없음, 상업 가능 · SynthID 소리 워터마크(안 들림) |
 
-새 곡을 넣을 땐 이 표에 한 줄(원본 주소·라이선스)을 더한다. 출처를 모르는 곡은 넣지 않는다.
+새 곡을 넣을 땐 `kf music add` 가 `tags.json` 과 이 표에 한 줄씩 더한다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kasaframe",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "말로 시키는 코드 영상 엔진 — 쇼츠·홍보·설명·뮤비를 장면 파일로 짜고 박에 맞춰 MP4 로 굽고 검사한다",
   "keywords": [
     "video",
@@ -19,7 +19,7 @@
     "kf": "bin/kf.mjs"
   },
   "engines": {
-    "node": ">=22.18"
+    "node": ">=22.15"
   },
   "dependencies": {
     "esbuild": "^0.28.2",

package/packages/adapters/src/project.ts

@@ -10,6 +10,7 @@ import {
   type SceneCtx,
 } from "@kasaframe/core";
 import { definePage, type KfMarker, type KfMode, type KfPage } from "./page.ts";
+import { textureLayer } from "./texture.ts";
 
 export interface KfSceneEntry {
   id: string;
@@ -151,7 +152,7 @@ export function mountProject(o: MountOptions): KfPage {
     const meta = { fps: kf.fps, width: kf.width, height: kf.height, duration: kf.duration };
     // 자막을 켜면 장면을 짓기 전에 안전 영역 아래쪽 자막 띠를 뺀다 — 주소 ?captions=on|off|fit 가 kf.json 을 그 판만 덮는다(kf render --captions)
     const { captionsPlan } = await import("@kasaframe/motion/captions");
-    const caps = await captionsPlan({ kf: kf as Parameters<typeof captionsPlan>[0]["kf"], mode: new URLSearchParams(location.search).get("captions") });
+    const caps = await captionsPlan({ kf: kf as Parameters<typeof captionsPlan>[0]["kf"], mode: new URLSearchParams(location.search).get("captions"), style: style as KfStyle | null });
     for (const entry of kf.scenes) {
       const mod = findModule(o.scenes, entry);
       const root = document.createElement("div");
@@ -180,6 +181,9 @@ export function mountProject(o: MountOptions): KfPage {
       }
       live.push({ entry, root, draw });
     }
+    // 변주 질감은 장면들 위·자막 아래 한 겹 — 장면 파일은 그대로다
+    const tex = style ? textureLayer(document, style.look?.texture, style.scheme, Math.min(kf.width, kf.height) / 1080) : null;
+    if (tex) stage.appendChild(tex);
     // 자막 판은 장면들 위 한 겹 — 장면 파일은 그대로다
     captions = (await caps?.mount(stage, style)) ?? null;
   }

package/packages/adapters/src/texture.ts

@@ -0,0 +1,94 @@
+import { rand, type StyleLook } from "@kasaframe/core";
+
+// 변주 질감 — 세계 코드를 안 고치고 겉모습만 바꾸는 길이라 엔진이 장면 위·자막 아래 한 겹으로 깐다.
+// 서 있는 그림 한 장(정지 화면 검사·섬광 검사에 안 걸린다), 무늬는 씨앗 고정이라 어느 탭에서 찍어도 같다.
+
+type Texture = NonNullable<StyleLook["texture"]>;
+
+function tile(doc: Document, w: number, h: number, paint: (img: ImageData) => void): string {
+  const c = doc.createElement("canvas");
+  c.width = w;
+  c.height = h;
+  const g = c.getContext("2d")!;
+  const img = g.createImageData(w, h);
+  paint(img);
+  g.putImageData(img, 0, 0);
+  return c.toDataURL("image/png");
+}
+
+/** 점 하나 — 어두운 바탕엔 흰 티, 밝은 바탕엔 검은 티 */
+function dot(img: ImageData, i: number, ink: number, alpha: number) {
+  const o = i * 4;
+  img.data[o] = img.data[o + 1] = img.data[o + 2] = ink;
+  img.data[o + 3] = Math.max(0, Math.min(255, Math.round(alpha * 255)));
+}
+
+// 이어 붙여도 이음매가 없는 값 잡음 — 격자를 둘레로 감는다
+function wrapNoise(seed: string, x: number, y: number, cells: number, size: number): number {
+  const fx = (x / size) * cells;
+  const fy = (y / size) * cells;
+  const x0 = Math.floor(fx);
+  const y0 = Math.floor(fy);
+  const v = (i: number, j: number) => rand(seed, ((i % cells) + cells) % cells + (((j % cells) + cells) % cells) * cells);
+  const sx = fx - x0;
+  const sy = fy - y0;
+  const ux = sx * sx * (3 - 2 * sx);
+  const uy = sy * sy * (3 - 2 * sy);
+  const a = v(x0, y0) + (v(x0 + 1, y0) - v(x0, y0)) * ux;
+  const b = v(x0, y0 + 1) + (v(x0 + 1, y0 + 1) - v(x0, y0 + 1)) * ux;
+  return a + (b - a) * uy;
+}
+
+export function textureLayer(doc: Document, tex: Texture | undefined, scheme: "light" | "dark", scale: number): HTMLDivElement | null {
+  if (!tex || tex.kind === "none" || !(tex.amount > 0)) return null;
+  const el = doc.createElement("div");
+  el.dataset.kfTexture = tex.kind;
+  el.style.cssText = `position:absolute;inset:0;pointer-events:none;z-index:49;opacity:${Math.min(1, tex.amount)}`;
+  const ink = scheme === "dark" ? 255 : 0;
+  const rgb = scheme === "dark" ? "255,255,255" : "0,0,0";
+  const s = Math.max(1, scale);
+  if (tex.kind === "scan") {
+    el.style.backgroundImage = `repeating-linear-gradient(0deg, rgba(${rgb},0.5) 0 ${s}px, transparent ${s}px ${4 * s}px)`;
+  } else if (tex.kind === "halftone") {
+    el.style.backgroundImage = `radial-gradient(rgba(${rgb},0.55) ${1.2 * s}px, transparent ${1.7 * s}px)`;
+    el.style.backgroundSize = `${7 * s}px ${7 * s}px`;
+  } else if (tex.kind === "grain") {
+    const n = 160;
+    el.style.backgroundImage = `url(${tile(doc, n, n, (img) => {
+      for (let i = 0; i < n * n; i++) {
+        const v = rand("kf-grain", i) - 0.5;
+        dot(img, i, v < 0 ? 255 - ink : ink, Math.abs(v) * 0.5);
+      }
+    })})`;
+    el.style.backgroundSize = `${n * s}px ${n * s}px`;
+  } else if (tex.kind === "noise") {
+    const n = 96;
+    el.style.backgroundImage = `url(${tile(doc, n, n, (img) => {
+      for (let i = 0; i < n * n; i++) dot(img, i, ink, rand("kf-noise", i) ** 2 * 0.6);
+    })})`;
+    el.style.backgroundSize = `${n * 3 * s}px ${n * 3 * s}px`;
+    el.style.imageRendering = "pixelated";
+  } else if (tex.kind === "paper") {
+    // 종이 — 큰 얼룩 두 겹에 짧은 섬유
+    const n = 256;
+    el.style.backgroundImage = `url(${tile(doc, n, n, (img) => {
+      for (let y = 0; y < n; y++)
+        for (let x = 0; x < n; x++) {
+          const v = 0.6 * wrapNoise("kf-paper-a", x, y, 6, n) + 0.4 * wrapNoise("kf-paper-b", x, y, 24, n) + 0.25 * (rand("kf-paper-c", x + y * n) - 0.5);
+          dot(img, x + y * n, ink, Math.max(0, v - 0.35) * 0.32);
+        }
+      for (let f = 0; f < 140; f++) {
+        let x = rand("kf-fiber", f * 4) * n;
+        let y = rand("kf-fiber", f * 4 + 1) * n;
+        const a = rand("kf-fiber", f * 4 + 2) * Math.PI * 2;
+        const len = 6 + rand("kf-fiber", f * 4 + 3) * 18;
+        for (let k = 0; k < len; k++, x += Math.cos(a), y += Math.sin(a)) {
+          const i = (((Math.round(x) % n) + n) % n) + (((Math.round(y) % n) + n) % n) * n;
+          dot(img, i, ink, Math.max(img.data[i * 4 + 3] / 255, 0.16));
+        }
+      }
+    })})`;
+    el.style.backgroundSize = `${n * 2 * s}px ${n * 2 * s}px`;
+  }
+  return el;
+}

package/packages/check/src/check.ts

@@ -184,11 +184,11 @@ async function checkPage(o: CheckOptions): Promise<Report> {
     f.push(...contrast(r.contrast, { shotFps: o.shotFps ?? 2 }));
     if (proj.text.minPx || proj.text.maxOnScreen) f.push(...textPolicy(r.texts, proj.text, { fps: meta.fps }));
     if (projDir) f.push(...genAssets(projDir));
-    f.push(...freezes(r.thumbs, { warnSec: proj.rules.maxFreezeSec }));
+    f.push(...freezes(r.thumbs, { errorSec: proj.rules.maxFreezeSec }));
     f.push(...blanks(r.thumbs, meta.duration));
     f.push(...spikes(r.thumbs, { exclude: [...sceneSpans(proj.kf).map((s) => s.from), ...(proj.beats?.drops ?? []), ...r.markers.filter((m) => m.kind === "scene" || m.kind === "drop").map((m) => m.t)] }));
     f.push(...flashes(r.thumbs, { maxPerSec: proj.rules.maxFlashPerSec, cuts: [...sceneSpans(proj.kf).map((s) => s.from), ...cuts(r.thumbs)] }));
-    f.push(...fill(r.thumbs, sceneSpans(proj.kf), { width: meta.width, height: meta.height, safe: proj.safe }));
+    f.push(...fill(r.thumbs, sceneSpans(proj.kf), { width: meta.width, height: meta.height, safe: proj.safe, captionTop: captionTop(r.texts) }));
     f.push(...staticLayout(r.thumbs, sceneSpans(proj.kf), { width: meta.width, height: meta.height, warnSec: proj.rules.staticSec?.warn, errorSec: proj.rules.staticSec?.error }));
     const seams = seamScenes(proj.kf);
     f.push(...cameraWander(r.cams, r.events, { fps: meta.fps, skipScenes: seams }));
@@ -236,7 +236,7 @@ async function checkVideo(o: CheckOptions): Promise<Report> {
 
   log(`프레임 읽기: ${from.toFixed(2)}–${to.toFixed(2)}초 · ${info.width}×${info.height} · ${info.fps.toFixed(2)}fps`);
   const thumbs = await videoThumbs(file, info, from, to);
-  f.push(...freezes(thumbs, { warnSec: proj.rules.maxFreezeSec }));
+  f.push(...freezes(thumbs, { errorSec: proj.rules.maxFreezeSec }));
   f.push(...blanks(thumbs, info.duration));
   f.push(...spikes(thumbs, { exclude: [...sceneSpans(proj.kf).map((s) => s.from), ...(proj.beats?.drops ?? [])] }));
   f.push(...flashes(thumbs, { maxPerSec: proj.rules.maxFlashPerSec, cuts: [...sceneSpans(proj.kf).map((s) => s.from), ...cuts(thumbs)] }));
@@ -271,3 +271,10 @@ async function checkVideo(o: CheckOptions): Promise<Report> {
 
   return finish(o.target, "video", meta, f, skipped, { frames: thumbs.length, textFrames, thumbFps: info.fps }, t0);
 }
+
+// 화면 자막 판의 윗변 — 판 글 상자 위에 판 안쪽 여백(글자 크기의 ⅓)을 더한 자리 중 가장 위. 자막이 없으면 undefined
+function captionTop(frames: { hits: { via: string; box?: { y0: number }; sizePx: number }[] }[]): number | undefined {
+  let top = Infinity;
+  for (const f of frames) for (const h of f.hits) if (h.via === "caption" && h.box) top = Math.min(top, h.box.y0 - h.sizePx * 0.3);
+  return Number.isFinite(top) ? top : undefined;
+}

package/packages/check/src/rules/assets.ts

@@ -22,7 +22,10 @@ export function genAssets(projectDir: string): Finding[] {
     const id = meta.id ?? f.replace(/\.json$/, "");
     const license = String(meta.license ?? "");
     const region = String(meta.region ?? "");
-    if (region || /제한|비상업|non-?commercial|restrict/i.test(license)) {
+    // 공급자가 박아 둔 제한(H3 공개 가중치의 한국 제외 등)은 라이선스 글을 읽지 않고 그대로 알린다
+    if (meta.restrict) {
+      out.push({ rule: "asset.restrict", severity: "warn", from: 0, to: 0, message: `생성 자산 ${id} — ${meta.restrict}`, detail: { file: join("assets", "gen", f), provider: meta.provider, model: meta.model } });
+    } else if (region || /제한|비상업|non-?commercial|restrict/i.test(license)) {
       out.push({
         rule: "asset.license",
         severity: "warn",

package/packages/check/src/rules/frames.ts

@@ -4,6 +4,7 @@ import type { Finding } from "../types.ts";
 export interface FreezeOptions {
   // 160×90 회색조 평균 절대차(0..255). 커서 깜빡임 한 번이면 넘는 정도.
   threshold?: number;
+  // 틀·style.json 의 motion.maxFreezeSec(틀이 이긴다) — 고정 관찰 화면(설명·뮤비)은 틀에서 늘려 허용한다. 없으면 0.1초
   errorSec?: number;
   warnSec?: number;
 }
@@ -46,7 +47,7 @@ export function freezes(thumbs: Thumb[], o: FreezeOptions = {}): Finding[] {
         severity,
         from: thumbs[a].t,
         to: thumbs[end].t,
-        message: `화면이 ${len.toFixed(2)}초 ${area > 0 ? `거의 멈췄다(바뀐 면적 ${(area * 100).toFixed(1)}%)` : "멈췄다"}${severity === "warn" ? ` — style.json maxFreezeSec ${warnSec}초 넘음` : ""} — 그 사이에 눈에 띄는 움직임 하나를 둔다`,
+        message: `화면이 ${len.toFixed(2)}초 ${area > 0 ? `거의 멈췄다(바뀐 면적 ${(area * 100).toFixed(1)}%)` : "멈췄다"}${severity === "warn" ? ` — 경고 기준 ${warnSec}초 넘음` : ` — 기준 ${errorSec}초(틀·style.json maxFreezeSec)`} — 그 사이에 눈에 띄는 움직임 하나를 둔다`,
         detail: { seconds: Math.round(len * 100) / 100, changedArea: Math.round(area * 10000) / 10000 },
       });
     }

package/packages/check/src/rules/layout.ts

@@ -78,9 +78,18 @@ export interface FillOptions {
   safe?: SafeArea;
   // 세로 화면은 주 요소가 안전 영역 폭의 이만큼은 차야 한다
   minWidthVertical?: number;
+  // 세로 화면은 위아래로도 써야 한다 — 내용이 위쪽에만 몰려 아래가 비면 경고(자막 띠는 빼고 잰다)
+  minHeightVertical?: number;
   minArea?: number;
+  // 화면 자막 판의 윗변(영상 px) — 그 아래는 장면 내용이 아니라서 채움에서 뺀다
+  captionTop?: number;
 }
 
+// 판정에 쓸 만큼 그 장면을 봤나 — 구간 검사가 장면 경계에서 시작하면 앞 장면의 마지막 프레임 한두 장(덮기·전환 중)만
+// 그 장면 몫으로 들어와 「채움 0%」로 잡혔다
+const MIN_SAMPLES = 3;
+const enoughOf = (times: number[], dur: number): boolean => times.length >= MIN_SAMPLES && times[times.length - 1] - times[0] >= Math.min(0.5, dur * 0.4);
+
 // 시작이 t 이하인 마지막 장면 — kf.json 시각은 넷째 자리에서 반올림돼 경계에 0.0001초 틈이 날 수 있다
 function sceneOf(t: number, scenes: SceneSpan[]): SceneSpan | undefined {
   let hit: SceneSpan | undefined;
@@ -93,33 +102,39 @@ function median(xs: number[]): number {
   return s.length ? s[Math.floor(s.length / 2)] : 0;
 }
 
-// 화면 채움 — 장면마다 내용 상자의 가운데값. 세로 화면은 폭 70% 아래면 경고, 넓이 12% 아래면 오류
+// 화면 채움 — 장면마다 내용 상자의 가운데값. 넓이 12% 아래면 오류, 세로 화면은 폭 70%·높이 55% 아래면 경고
 export function fill(thumbs: Thumbish[], scenes: SceneSpan[], o: FillOptions): Finding[] {
   if (!thumbs.length) return [];
   const aspect = o.width / o.height;
   const vertical = o.height > o.width;
   const minW = o.minWidthVertical ?? 0.7;
+  const minH = o.minHeightVertical ?? 0.55;
   const minArea = o.minArea ?? 0.12;
-  const groups = new Map<string, { span: SceneSpan; w: number[]; a: number[] }>();
+  const groups = new Map<string, { span: SceneSpan; w: number[]; h: number[]; a: number[]; t: number[] }>();
   for (const t of thumbs) {
     const s = sceneOf(t.t, scenes) ?? { id: "영상", from: 0, dur: Infinity };
     const { w, h } = dims(t, aspect);
     const k = w / o.width;
     const sa = o.safe ?? { top: 0, bottom: 0, left: 0, right: 0 };
+    const y0 = Math.max(0, Math.round(sa.top * k));
     const box = contentBox(t.luma, w, h, {
       x0: Math.max(0, Math.round(sa.left * k)),
-      y0: Math.max(0, Math.round(sa.top * k)),
+      y0,
       x1: Math.min(w, w - Math.round(sa.right * k)),
-      y1: Math.min(h, h - Math.round(sa.bottom * k)),
+      y1: Math.max(y0 + 1, Math.min(h, h - Math.round(sa.bottom * k), o.captionTop !== undefined ? Math.round(o.captionTop * k) : h)),
     });
-    const g = groups.get(s.id) ?? { span: s, w: [], a: [] };
+    const g = groups.get(s.id) ?? { span: s, w: [], h: [], a: [], t: [] };
     g.w.push(box.wFrac);
+    g.h.push(box.hFrac);
     g.a.push(box.area);
+    g.t.push(t.t);
     groups.set(s.id, g);
   }
   const out: Finding[] = [];
-  for (const { span, w, a } of groups.values()) {
+  for (const { span, w, h, a, t } of groups.values()) {
+    if (!enoughOf(t, span.dur)) continue;
     const mw = median(w);
+    const mh = median(h);
     const ma = median(a);
     const to = Number.isFinite(span.dur) ? span.from + span.dur : thumbs.at(-1)!.t;
     if (ma < minArea) {
@@ -140,6 +155,15 @@ export function fill(thumbs: Thumbish[], scenes: SceneSpan[], o: FillOptions): F
         message: `장면 ${span.id} 의 주 요소 폭이 안전 영역의 ${(mw * 100).toFixed(0)}% — 세로 화면은 ${Math.round(minW * 100)}% 넘게 채운다`,
         detail: { scene: span.id, area: Math.round(ma * 1000) / 1000, width: Math.round(mw * 1000) / 1000 },
       });
+    } else if (vertical && mh < minH) {
+      out.push({
+        rule: "layout.fill",
+        severity: "warn",
+        from: span.from,
+        to,
+        message: `장면 ${span.id} 의 내용이 안전 영역 높이의 ${(mh * 100).toFixed(0)}% 에 몰렸다(자막 띠 빼고) — 세로 화면은 위아래로 써서 ${Math.round(minH * 100)}% 넘게 채운다(큰 숫자 아래 자·막대, 목록은 세로로 쌓기)`,
+        detail: { scene: span.id, area: Math.round(ma * 1000) / 1000, width: Math.round(mw * 1000) / 1000, height: Math.round(mh * 1000) / 1000 },
+      });
     }
   }
   return out;

package/packages/cli/package.json

@@ -17,7 +17,8 @@
     "vite": "^8.3.3",
     "@kasaframe/motion": "0.0.0",
     "pngjs": "^7.0.0",
-    "@kasaframe/jizura": "^0.0.0"
+    "@kasaframe/jizura": "^0.0.0",
+    "@kasaframe/director": "^0.0.0"
   },
   "devDependencies": {
     "@sveltejs/vite-plugin-svelte": "^7.3.1",

package/packages/cli/src/blur.ts

@@ -1,3 +1,5 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { PNG } from "pngjs";
 import type { PageInfo, Tab } from "./browser.ts";
 
@@ -8,10 +10,20 @@ export interface BlurOpts {
   shutter: number;
 }
 
-export function blurOpts(opts: Record<string, string | boolean | undefined>): BlurOpts | null {
-  const count = Math.round(Number(opts["motion-blur"] ?? 0));
+/** kf.json 의 render — 빠른 움직임이 많은 용도(쇼츠·홍보)는 틀이 모션 블러를 기본으로 켜 둔다 */
+export function projectBlur(dir: string): { motionBlur?: number; shutter?: number } | undefined {
+  try {
+    return JSON.parse(readFileSync(join(dir, "kf.json"), "utf8")).render;
+  } catch {
+    return undefined;
+  }
+}
+
+/** 플래그가 프로젝트 기본(kf.json render)을 이긴다 — --motion-blur 0 이면 끈다 */
+export function blurOpts(opts: Record<string, string | boolean | undefined>, base?: { motionBlur?: number; shutter?: number }): BlurOpts | null {
+  const count = Math.round(Number(opts["motion-blur"] ?? base?.motionBlur ?? 0));
   if (!(count > 1)) return null;
-  const shutter = Number(opts.shutter ?? 180);
+  const shutter = Number(opts.shutter ?? base?.shutter ?? 180);
   return { count, shutter: Number.isFinite(shutter) ? Math.min(360, Math.max(1, shutter)) : 180 };
 }