kasaframe 0.0.0-stage → 0.1.3

package/packages/plan/src/brief.ts

@@ -0,0 +1,383 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { captionMode } from "@kasaframe/motion/captions";
+import { bundleFor, MENU, type Dress } from "@kasaframe/motion/menu";
+import { questionsMarkdown, type Question } from "@kasaframe/gen";
+import { loadTheme } from "@kasaframe/themes";
+import type { GenSpec, ShotSpec } from "./types.ts";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repo = fileURLToPath(new URL("../../../", import.meta.url));
+
+export interface ProjectScene {
+  id: string;
+  from: number;
+  dur: number;
+  file: string;
+  role: string;
+  idea: string;
+  assets?: string[];
+  // kf new 가 고른 연출 수 — 뼈대 장면 파일의 DRESS 와 같다
+  dress?: Dress;
+}
+
+export interface ProjectFile {
+  template: string;
+  theme?: string;
+  title: string;
+  fps: number;
+  width: number;
+  height: number;
+  duration: number;
+  music: string | null;
+  beats: string | null;
+  captions: string;
+  render?: { motionBlur?: number; shutter?: number };
+  // kf narrate 가 적는다 — voice 가 있으면 내레이션 단계를 지났다
+  voice?: string;
+  narration?: string | null;
+  safeArea: { top: number; bottom: number; left: number; right: number };
+  text: { policy: string; maxOnScreen: number; minPx: number };
+  scenes: ProjectScene[];
+}
+
+export function readProject(dir: string): ProjectFile {
+  return JSON.parse(readFileSync(join(dir, "kf.json"), "utf8"));
+}
+
+// 모델이 부품 이름을 지어내지 않게 실제로 내보낸 함수의 첫 줄(인자·반환 타입)만 모은다
+function signatures(pkg: string): string[] {
+  const src = join(repo, "packages", pkg, "src");
+  if (!existsSync(src)) return [];
+  const out: string[] = [];
+  for (const f of readdirSync(src).filter((x) => x.endsWith(".ts") && !x.endsWith(".test.ts") && x !== "index.ts" && x !== "captions.ts")) {
+    const text = readFileSync(join(src, f), "utf8");
+    for (const m of text.matchAll(/^export (?:function|const) (\w+)[^\n]*/gm)) {
+      const line = m[0].replace(/\s*\{\s*$/, "").replace(/^export (function|const) /, "");
+      if (line.length < 220) out.push(line);
+    }
+  }
+  return out;
+}
+
+const TEXT_POLICY: Record<string, string> = {
+  none: "화면에 문장을 쓰지 않는다. 기능 낱말 하나·제품 이름·끝 카드만.",
+  "terms-only": "화면 글은 전문 낱말과 숫자만(한 번에 몇 개까지). 말은 자막 트랙으로 따로 간다.",
+  captions: "소리 없이도 읽히게 — 들릴 말은 captions.json 에 쓰면 엔진이 화면 아래 자막 판에 얹는다. 장면 글은 핵심 낱말만.",
+  lyrics: "가사는 키네틱 타이포로 — 부른 낱말이 부른 시각에 뜨고, 뜻을 그림·움직임으로 받친다. 슬로건 금지는 가사에 걸지 않는다.",
+};
+
+function sceneBeats(dir: string, kf: ProjectFile, s: ProjectScene): string {
+  if (!kf.beats || !existsSync(join(dir, kf.beats))) return "곡 없음";
+  const b = JSON.parse(readFileSync(join(dir, kf.beats), "utf8"));
+  const inside = (xs: number[] = []) => xs.filter((t) => t >= s.from && t < s.from + s.dur).map((t) => +(t - s.from).toFixed(2));
+  const drops = inside(b.drops);
+  const bars = inside(b.bars ?? b.downbeats);
+  return `${b.bpm?.toFixed?.(1) ?? "?"} BPM · 장면 안 드롭 ${drops.length ? drops.join(", ") + "초" : "없음"} · 마디 ${bars.slice(0, 12).join(", ")}${bars.length > 12 ? " …" : ""}초`;
+}
+
+interface PurposeRules {
+  staticSec: { warn: number; error: number };
+  beatMove: "every-beat" | "drop-sections";
+  maxFreezeSec: number;
+}
+
+// 틀(templates/<용도>/template.json motion)이 기본값을 덮는다 — kf check 도 같은 값을 읽는다
+function purposeRules(id: string): PurposeRules {
+  const file = join(repo, "templates", id, "template.json");
+  const m = existsSync(file) ? (JSON.parse(readFileSync(file, "utf8")).motion ?? {}) : {};
+  return { staticSec: m.staticSec ?? { warn: 1.5, error: 3 }, beatMove: m.beatMove ?? "every-beat", maxFreezeSec: m.maxFreezeSec ?? 0.1 };
+}
+
+// 용도별 표 — 같은 값을 쓰는 틀끼리 한 줄로
+export function purposeTable(): string[] {
+  const dir = join(repo, "templates");
+  const ids = existsSync(dir) ? readdirSync(dir).filter((d) => existsSync(join(dir, d, "template.json"))) : [];
+  const groups = new Map<string, string[]>();
+  for (const id of ids) {
+    const r = purposeRules(id);
+    const key = `같은 구도 ${r.staticSec.warn}초 경고·${r.staticSec.error}초 오류 · 큰 움직임 ${r.beatMove === "every-beat" ? "박마다" : "후렴·드롭 구간만(벌스는 화면 안 움직임으로 충분)"} · 정지 ${r.maxFreezeSec}초 금지`;
+    groups.set(key, [...(groups.get(key) ?? []), id]);
+  }
+  return [...groups].map(([k, v]) => `- ${v.join("·")}: ${k}`);
+}
+
+function dropSections(dir: string, kf: ProjectFile): string {
+  if (!kf.beats || !existsSync(join(dir, kf.beats))) return "곡이 없어 드롭 구간도 없다 — 화면 안 움직임으로 간다";
+  const b = JSON.parse(readFileSync(join(dir, kf.beats), "utf8"));
+  const secs: { t: number; kind: string }[] = b.sections ?? [];
+  const spans: { t: number; to: number }[] = [];
+  secs.forEach((x, i) => {
+    if (x.kind !== "drop") return;
+    const to = secs[i + 1]?.t ?? kf.duration;
+    const last = spans[spans.length - 1];
+    if (last && Math.abs(last.to - x.t) < 0.05) last.to = to;
+    else spans.push({ t: x.t, to });
+  });
+  return spans.length ? spans.map((x) => `${x.t.toFixed(2)}–${x.to.toFixed(2)}초`).join(", ") : "드롭 구간이 잡히지 않았다";
+}
+
+// 장면을 채우는 모델(Claude Code 든 OG 의 아무 모델이든)이 읽는 한 장. 사용서(docs/AGENTS.md)가 있으면 뒤에 붙인다
+export function projectBrief(dir: string): string {
+  const kf = readProject(dir);
+  const style = JSON.parse(readFileSync(join(dir, "style.json"), "utf8"));
+  const plan = existsSync(join(dir, "plan.json")) ? JSON.parse(readFileSync(join(dir, "plan.json"), "utf8")) : {};
+  const rules = purposeRules(kf.template);
+  const tplFile = join(repo, "templates", kf.template, "template.json");
+  const tplMotion = existsSync(tplFile) ? (JSON.parse(readFileSync(tplFile, "utf8")).motion ?? {}) : {};
+  const colors = Object.keys(style.colors ?? {}).map((k: string) => `--kf-${k.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`);
+  const core = signatures("core");
+  const motion = signatures("motion");
+  const agents = join(repo, "docs", "AGENTS.md");
+  const lines = [
+    `# ${kf.title || plan.request || "kasaframe 프로젝트"} — 장면 작성 지시서`,
+    "",
+    ...questionsMarkdown(plan.asks ?? [], (flags) => `npx kf make --answer ${dir} ${flags}`),
+    ...narrationSection(dir, kf, plan),
+    `**이 영상의 규칙 — 용도 ${kf.template}(틀이 기본값을 덮는다, kf check 가 같은 값으로 잡는다)**`,
+    `1. 화면은 ${rules.maxFreezeSec}초(60fps 6프레임) 넘게 멈추지 않는다 — 끝 카드·큰 숫자·로고도 예외 없이 화면 안 움직임(숫자 굴러가기·칸 채우기·반짝임·글자 흐름·바탕 흐름)으로 계속 살아 있게.`,
+    `2. 같은 구도는 ${rules.staticSec.warn}초 넘기지 않는다(${rules.staticSec.error}초 넘으면 오류) — 새 요소·칸 채우기·숫자 키우기·컷·전환으로 바꾼다.`,
+    rules.beatMove === "every-beat"
+      ? "3. 미세하게 흔들리는 것만으로 때우지 않는다 — 눈에 보이는 큰 움직임이 박마다 하나 이상."
+      : `3. 눈에 보이는 큰 움직임을 박마다 요구하는 건 후렴·드롭 구간(beats.json sections 의 drop — ${dropSections(dir, kf)})뿐이다. 벌스·브레이크는 화면 안 움직임(가사·숫자·바탕 흐름)으로 충분하다 — 절제했다가 드롭에서 터뜨린다.`,
+    "4. **카메라는 이유가 있을 때만** 움직인다 — 기본은 정지, 주인공은 안전 영역 가운데. 드러냄에 다가가기(`stage.camera.pushIn`)·비교에 물러나기(`pullOut`)·주인공 따라가기(`follow`)·드롭에 한 번 툭(`impact`), 끝나면 선다. 화면 전체를 사인으로 흔들거나 박마다 자세를 바꾸지 않는다(kf check `camera.wander`·`layout.edge`). 회전·원근 기울기는 0.",
+    "5. **섬광은 1초에 3번까지**(kf check frame.flash — 빛 민감 발작). 화면 25% 넘게 번쩍이는 건 두 박·한 마디에 한 번, 빨강 전체 깜빡임·대비 큰 줄무늬 연타·어둠↔흰 화면 컷 이어 붙이기는 쓰지 않는다.",
+    "",
+    "용도별 기본값(templates/<용도>/template.json motion):",
+    ...purposeTable(),
+    "",
+    "그림 보기: `npx kf look <폴더>` 가 찍는 장면 모음(out/look-sheet.png)을 Read 로 직접 보고 장면별 확인표(out/look.md)대로 고친다. **Read 로 그림이 안 보이면(눈 없는 모델)만** `npx kf look <폴더> --vision-model google/gemini-3.5-flash [--ask \"<볼 것>\"]` — 그림 보는 모델이 장면마다 글로 알려 준다.",
+    "",
+    `요청: ${plan.request ?? "(없음)"}`,
+    `용도 ${kf.template} · ${kf.width}×${kf.height} · ${kf.fps}fps · ${kf.duration}초 · 스타일 ${style.name}(${style.scheme}) · 곡 ${kf.music ?? "없음"} · 자막 ${kf.captions}`,
+    `안전 영역(글은 이 안에): 위 ${kf.safeArea.top}px · 아래 ${kf.safeArea.bottom}px · 왼쪽 ${kf.safeArea.left}px · 오른쪽 ${kf.safeArea.right}px`,
+    `화면 글: ${TEXT_POLICY[kf.text?.policy] ?? kf.text?.policy} 글자 크기 최소 ${kf.text?.minPx}px.`,
+    `움직임 규칙(style.json motion 위에 틀 motion): ${JSON.stringify({ ...style.motion, ...tplMotion })}`,
+    ...(style.notes?.length ? ["디자인 메모: " + style.notes.join(" / ")] : []),
+    "",
+    "## 장면 파일 꼴 — 이 꼴만 쓴다",
+    "",
+    "```ts",
+    'import { applyStyle, clip, ease, type SceneCtx } from "@kasaframe/core";',
+    "export default {",
+    "  build(root: HTMLElement, ctx: SceneCtx) {",
+    "    const box = document.createElement(\"div\"); // root.style.display 는 엔진이 켜고 끈다 — 배치는 box 에",
+    "    box.style.cssText = \"position:absolute;inset:0;overflow:hidden;background:var(--kf-bg)\";",
+    "    root.append(box);",
+    "    // DOM 은 여기서 한 번만 짓는다",
+    "    return (t: number) => { /* t = 장면 안 초(0..ctx.dur). 같은 t 면 같은 화면 */ };",
+    "  },",
+    "};",
+    "```",
+    "",
+    "- 시각 함수 밖에서 상태를 쌓지 않는다(앞 프레임 값을 기억하지 않는다). 탭 여러 개가 아무 시각이나 찍는다.",
+    "- `Math.random`·`Date.now`·`performance.now`·`setTimeout` 금지 — 난수는 `rand(seed, i)`, 시간은 `t` 만.",
+    "- 글자에 `undefined`·`NaN`·`null` 이 찍히지 않게 값은 미리 문자열로 만든다. 이모지 금지(아이콘은 인라인 SVG).",
+    "- 장면이 1초 넘게 멈추지 않게 한다(아주 느린 다가가기라도). 빈 화면으로 시작·끝내지 않는다.",
+    "- **화면을 채운다**(kf check layout.fill): 주 요소가 안전 영역을 크게 차지한다 — 세로 화면은 폭의 70% 넘게, 글은 큰 글자 단계(hero·title)로. 가운데 작은 그림 하나에 나머지가 흰 여백이면 실패다.",
+    "- 구도 판정(kf check layout.static)은 칸 평균 밝기와 화면 안 내용(글·칸의 센 가장자리)으로 본다 — 숫자가 구르고 칸이 차면 바뀐 것이다. 카메라 샷이나 떠다니는 장식으로 메우지 않는다.",
+    "- `../lib/stage.ts` 의 `makeStage(root, ctx, { dress })`(정지 바탕·연출 수·정지 카메라 `stage.camera`)·`stage.say(낱말)`(글 수 + 박마다 차는 강조 띠)·`makeCamera(layer, ctx, { frame })`(자기 카메라 층에)·`bigWord`·`fitPx`·`cutTimes`·`lastT` 를 써도 된다 — 위 규칙을 처음부터 넘게 짜 둔 도구다. 카메라가 요소를 겨누면 `stage.tick(t)` 은 내용을 칠한 뒤 맨 끝에.",
+    "- 박에 붙이는 움직임은 `ctx.beats`(장면 시작 0 기준: `ctx.beats.drops`, `ctx.beats.nearestBeat(t)`, `ctx.beats.pulse(t, {...})`). 시각을 BPM 으로 곱해 만들지 않는다.",
+    "- 자산은 `ctx.asset(\"gen/<id>.png\")` 처럼 assets/ 기준 경로로. 없는 파일을 가리키지 않는다.",
+    "- 색·글꼴·크기는 CSS 변수로: " + [...colors, "--kf-font-sans", "--kf-font-display", "--kf-font-mono", "--kf-size-hero", "--kf-size-title", "--kf-size-body", "--kf-size-caption", "--kf-radius-md", "--kf-shadow-soft"].join(" "),
+    "",
+    "## 쓸 수 있는 함수",
+    "",
+    "`@kasaframe/core`:",
+    ...core.map((s) => `- ${s}`),
+    "",
+    ...(motion.length ? ["`@kasaframe/motion`(움직임 부품 — 숫자만 넣으면 Style 이나 상태를 돌려준다. applyStyle 로 붙인다):", ...motion.map((s) => `- ${s}`), ""] : []),
+    ...dressSection(kf),
+    "## 장면",
+    "",
+    ...kf.scenes.flatMap((s) => [
+      `### ${s.id} — ${s.file} (${s.from.toFixed(2)}–${(s.from + s.dur).toFixed(2)}초, ${s.dur.toFixed(2)}초, 역할 ${s.role})`,
+      `- 할 일: ${s.idea}`,
+      ...(s.role === "seam" ? ["- 이 장면 파일은 고치지 않는다 — 3D 전환(transition3d)이 앞뒤 화면을 이어 준다"] : []),
+      ...(s.dress ? [`- 연출 수(뼈대에 걸려 있다): ${dressLine(s.dress)}`] : []),
+      `- 박: ${sceneBeats(dir, kf, s)}`,
+      ...(s.assets?.length ? [`- 자산: ${s.assets.map((a) => a.replace(/^gen:(img|vid):(.+)$/, (_, k, id) => `assets/gen/${id}.${k === "img" ? "png" : "mp4"}`)).join(", ")}`] : []),
+      "",
+    ]),
+    ...genSection(dir, kf, plan),
+    ...videoSection(dir, kf, plan),
+    ...shotSection(dir, kf, plan),
+    ...themeSection(kf.theme, plan),
+    ...(existsSync(join(dir, "lyrics.json"))
+      ? ["## 가사(lyrics.json — 낱말 시각까지)", "", '`import.meta.glob("../lyrics.json", { eager: true, import: "default" })` 로 읽는다(꼴 `{ lines: [{ text, start, end, words?: [{ w, start, end }] }] }`, 시각은 영상 전체 기준 초 — 장면 안 시각은 `start - ctx.from`). 낱말이 없으면 줄을 글자 수 비율로 나눈다.', ""]
+      : []),
+    ...(existsSync(join(dir, "assets", "in"))
+      ? ["## 받은 자산(사람이 준 것 — 쓸 수 있으면 쓴다)", "", ...readdirSync(join(dir, "assets", "in")).map((f) => `- \`ctx.asset("in/${f}")\``), ""]
+      : []),
+    ...(captionMode(kf.captions) !== "none"
+      ? [
+          "## 자막",
+          "",
+          '들릴 말은 프로젝트 `captions.json` 에 `[{"scene": "장면 id", "text": "짧은 마디를 쉼표로"}]` 로 쓴다 — `kf make --finish` 가 out/captions.ko.srt·vtt 로 만든다. 장면 파일에는 문장을 쓰지 않는다.',
+          captionMode(kf.captions) === "on"
+            ? `이 영상은 자막을 화면에도 얹는다 — 엔진이 장면 위에 판을 깐다(안전 영역 아래쪽 가운데, 두 줄까지). 그 자리(아래 가장자리에서 ${kf.safeArea.bottom}px 위 언저리)에 장면의 큰 글을 두지 않는다.`
+            : "화면에는 얹지 않는다(kf render --captions on 이면 그 판만 얹는다).",
+          "",
+        ]
+      : []),
+    ...(existsSync(agents) ? ["## 사용서(docs/AGENTS.md)", "", readFileSync(agents, "utf8")] : []),
+  ];
+  return lines.join("\n");
+}
+
+// 내레이션을 켠 틀(쇼츠·설명) — 장면보다 말이 먼저다. 목소리 길이가 장면 길이를 정하니 장면은 kf narrate 뒤에 쓴다
+function narrationSection(dir: string, kf: ProjectFile, plan: { voice?: string; answers?: Record<string, string>; asks?: { id: string }[] }): string[] {
+  const tplFile = join(repo, "templates", kf.template, "template.json");
+  const tpl = existsSync(tplFile) ? JSON.parse(readFileSync(tplFile, "utf8")) : {};
+  if (!tpl.narration?.on) return [];
+  const asked = (id: string) => plan.asks?.some((q) => q.id === id);
+  const voice = kf.voice ?? plan.voice ?? plan.answers?.voice;
+  const music = kf.music ?? plan.answers?.music;
+  const done = kf.voice !== undefined;
+  const mix = tpl.audio ? `말할 때 곡은 목소리보다 ${-tpl.audio.musicDb}dB 안팎 아래(덕킹), 끝 ${tpl.audio.fadeOut}초 페이드, ${tpl.audio.lufs} LUFS — kf render 가 섞는다` : "";
+  return [
+    `## 내레이션 먼저 — 장면보다 앞${done ? "(됐다)" : ""}`,
+    "",
+    `목소리 ${asked("voice") ? "아직 — 맨 위 질문의 답" : (voice ?? "틀 기본")} · 곡 ${asked("music") ? "아직 — 맨 위 질문의 답" : (music ?? "없음")}${tpl.mood ? `(분위기 ${tpl.mood})` : ""}${mix ? ` · ${mix}` : ""}`,
+    "",
+    ...(done
+      ? [
+          `kf narrate 를 지났다 — 장면 시각(kf.json)이 목소리 길이에 맞춰졌고 captions.json 에 낱말 시각(\`words\`, 영상 기준 초)이 있다. 문장을 고치면 \`npx kf narrate ${dir}\` 를 다시 부른다(같은 문장은 캐시라 0원).`,
+        ]
+      : [
+          `1. \`captions.json\` 에 장면마다 들릴 말을 쓴다 — \`[{"scene": "hook", "text": "..."}]\`. 차분한 설명체, 짧은 마디는 쉼표로, 문장은 마침표로. 한국어 차분한 낭독은 1초에 4–5글자(띄어쓰기·문장부호 빼고) — 지금 장면 길이에 가깝게, 훅은 한 마디(2초 안). 끝 장면·이음매는 비워도 된다. 말은 소리·자막으로 가고 화면 글 정책은 그대로다.`,
+          `2. \`npx kf narrate ${dir}\` — 장면마다 읽혀 장면 길이 = 앞 숨 ${tpl.narration.lead}초 + 말 + 뒤 숨 ${tpl.narration.tail}초 로 맞추고(곡이 있으면 다음 박에 붙인다), 자막 시각을 목소리 시각으로 적는다. 요청에 길이가 있으면 빠르기를 0.9–1.1 안에서만 맞춘다.`,
+          "3. 그다음 장면을 쓴다 — kf.json 장면 시각이 바뀌었으니 다시 읽는다(장면은 `ctx.dur` 로 짠다).",
+        ]),
+    "- 말과 화면을 맞출 때: captions.json 의 `words` 가 영상 기준 초다 — 그 낱말이 들리는 순간에 같은 낱말·도식이 서게(`w.from - ctx.from` 이 장면 안 시각). `import.meta.glob(\"../captions.json\", { eager: true, import: \"default\" })` 로 읽는다.",
+    "",
+  ];
+}
+
+function dressLine(d: Dress): string {
+  const parts = [`바탕 \`${d.bg}\``, `글 \`${d.text}\``];
+  if (d.wipeIn !== "none") parts.push(`들어올 때 \`${d.wipeIn}\`가 걷힌다`);
+  if (d.wipeOut !== "none") parts.push(`나갈 때 \`${d.wipeOut}\`로 덮는다`);
+  return parts.join(" · ");
+}
+
+// 대충 한 요청에서도 연출이 밋밋하지 않게 — 뼈대가 이미 건 수를 알리고, 바꿀 때 고를 메뉴(이 용도·테마 묶음 먼저)를 준다
+function dressSection(kf: ProjectFile): string[] {
+  const tplFile = join(repo, "templates", kf.template, "template.json");
+  const tpl = existsSync(tplFile) ? JSON.parse(readFileSync(tplFile, "utf8")) : {};
+  if (!tpl.moves) return [];
+  const b = bundleFor(tpl.moves, kf.theme);
+  const blur = kf.render?.motionBlur ?? 0;
+  const kinds = [
+    ["bg", "바탕 — 정지만(뜻 없이 떠도는 장식은 쓰지 않는다)", b.bg],
+    ["text", "글 — 안전 영역 안, 박마다 내용이 바뀐다(낱말을 WORDS 에)", b.text],
+    ["wipe", "경계 덮기 — 앞 장면 끝을 덮고 뒤 장면 처음에 걷힌다. 두 장면 파일의 wipeOut·wipeIn 을 같은 이름으로", b.wipe],
+  ] as const;
+  return [
+    "## 연출 수 — 뼈대에 이미 걸려 있다",
+    "",
+    `\`kf new\` 가 장면마다 바탕·글·경계 덮기를 이 용도${kf.theme ? `·테마(${kf.theme})` : ""} 묶음에서 골라 장면 파일 \`DRESS\` 에 넣었다(요청 글이 씨앗 — 같은 요청이면 같은 수). 장면을 채울 때 **수는 두고 낱말(\`WORDS\`)과 내용을 바꾼다** — 수가 쉬지 않기·같은 구도·화면 채움 검사를 이미 넘는다. **화면에서 움직이는 것은 모두 내용 하나를 뜻한다** — 떠다니는 방울·판·큐브·흩뿌린 입자 같은 뜻 없는 장식은 넣지 않고, 쉬지 않기는 숫자 굴러가기·칸 채우기·연결선·강조로 채운다. 바꾸려면 아래 이름으로, 이음매(seam)는 3D 전환(dive 2판 — 화면 속으로 빠르게 다이브)이 맡는다.`,
+    ...(blur > 1 ? [`굽기: 모션 블러 ${blur}장·셔터 ${kf.render?.shutter ?? 180}°(kf.json \`render\`) — 빠르게 움직이는 것만 번지고 서 있는 글은 그대로다. 손으로 끌 땐 \`kf render --motion-blur 0\`.`] : []),
+    "",
+    ...kinds.flatMap(([kind, head, mine]) => [
+      `- ${head}: ${MENU.filter((m) => m.kind === kind)
+        .sort((x, y) => Number(!mine.includes(x.name)) - Number(!mine.includes(y.name)))
+        .map((m) => `${mine.includes(m.name) ? "**" : ""}\`${m.name}\`${mine.includes(m.name) ? "**" : ""} ${m.does}`)
+        .join(" · ")}`,
+    ]),
+    "",
+    "굵은 이름이 이 영상의 묶음이다. 수만 따로 보려면 `examples/moves/<이름>/`, 메뉴 밖 수(곡선 글·도형 변신·만화 칸·찢기…)까지 전체는 `examples/moves/README.md`. 장면을 직접 짤 때도 `import { slamWords, sunburst, … } from \"@kasaframe/motion/moves\"` 로 같은 수를 쓴다.",
+    "",
+  ];
+}
+
+// 테마를 골랐으면 그 비유·금지·효과 쓰는 꼴을 그대로 싣는다(SPEC 9). auto 인데 맞는 테마가 없으면 강한 모델이 새 테마를 draft 로 써 넣을 수 있다
+function themeSection(id: string | undefined, plan: { themeCandidates?: { id: string; why: string }[]; request?: string; asks?: { id: string }[] }): string[] {
+  if (id) {
+    const t = loadTheme(id);
+    const pick = plan.themeCandidates?.find((c) => c.id === id);
+    return [
+      `## 테마 ${t.name}(${t.id}) — ${t.metaphor}`,
+      "",
+      ...(plan.asks?.some((q) => q.id === "theme") ? ["지금은 auto 로 깔아 둔 테마다 — 맨 위 질문의 답을 넣으면(`kf make --answer … --theme <id>`) 테마와 이 지시서가 바뀐다. 장면은 그다음에 쓴다.", ""] : []),
+      ...(pick ? [`고른 이유: ${pick.why}`, ""] : []),
+      `효과는 복사하지 말고 가져다 쓴다: \`import { fx } from "@kasaframe/themes/fx"; const { ${t.effects.map((e) => e.name).join(", ")} } = fx("${t.id}");\``,
+      "",
+      ...t.effects.map((e) => `- \`${e.name}\`(${e.kind}) — ${e.does} · \`${e.use}\``),
+      "",
+      ...(plan.themeCandidates && plan.themeCandidates.length > 1 ? [`다른 후보: ${plan.themeCandidates.slice(1).map((c) => c.id).join(" · ")} — 첫 장면을 각 테마로 찍은 그림은 out/theme-<id>.png`, ""] : []),
+      t.guide,
+      "",
+    ];
+  }
+  if (plan.themeCandidates && !plan.themeCandidates.length) {
+    return [
+      "## 테마 — 맞는 approved 테마가 없다",
+      "",
+      "프리셋 style 로 간다. 이 내용에 맞는 비유가 뚜렷하면 SPEC 계약 9 대로 `themes/<새 id>/` 에 테마 팩(theme.json status draft · THEME.md · style.json · effects.ts 5–10개)을 써 넣어도 된다 — 사람이 견본을 보고 OK 하기 전까지는 draft 라 이 프로젝트에는 쓰지 않는다.",
+      "",
+    ];
+  }
+  return [];
+}
+
+type BriefPlan = { gen?: GenSpec[]; shots?: ShotSpec[]; asks?: Question[]; answers?: Record<string, string>; aspect?: string };
+
+const pending = (plan: BriefPlan, id: string) => (plan.asks ?? []).some((q) => q.id === id);
+
+// 막연한 자동 프롬프트는 엉뚱한 그림을 냈다 — 아직 없는 그림은 목록으로 내고 세션이 구체적인 프롬프트를 써서 고른 공급자로 만든다
+function genSection(dir: string, kf: ProjectFile, plan: BriefPlan): string[] {
+  const todo = (plan.gen ?? []).filter((g) => g.kind === "img" && !existsSync(join(dir, "assets", "gen", `${g.id}.png`)));
+  if (!todo.length) return [];
+  const provider = plan.answers?.image;
+  return [
+    pending(plan, "image") ? "## 만들 그림 — 사람이 그림 생성을 고른 뒤에(맨 위 「사용자에게 먼저 물을 것」)" : `## 만들 그림 — ${provider ?? "기본 공급자"}로(고른 답)`,
+    "",
+    "받은 자산·실제 화면 오리기·도형으로 되면 만들지 않는다. 만들 땐 요청 내용으로 **구체적인** 프롬프트를 써서(무엇이·어떤 구도로·어떤 색·글자 없음):",
+    "",
+    ...todo.map((g) => `- \`${g.id}\`(장면 ${g.scene ?? "-"}) — 틀이 제안한 뜻: ${g.prompt}\n  \`npx kf gen img "<구체적 프롬프트>" --id ${g.id} --size ${g.size ?? `${kf.width}x${kf.height}`}${provider ? ` --provider ${provider}` : ""} --project ${dir}\` → \`ctx.asset("gen/${g.id}.png")\``),
+    "",
+  ];
+}
+
+// 캐릭터가 실제로 움직여야 하는 컷 — 영상 모델은 돈이 들어 고른 답이 있을 때만 부른다. 이음매 영상은 kf make --finish 가 앞뒤 화면으로 만든다
+function videoSection(dir: string, kf: ProjectFile, plan: BriefPlan): string[] {
+  const cuts = (plan.gen ?? []).filter((g) => g.kind === "vid" && !g.seam && !existsSync(join(dir, "assets", "gen", `${g.id}.mp4`)));
+  if (!cuts.length) return [];
+  const provider = plan.answers?.video;
+  const aspect = plan.aspect ?? (kf.width > kf.height ? "16:9" : kf.width < kf.height ? "9:16" : "1:1");
+  return [
+    pending(plan, "video") ? "## 영상 모델 컷 — 사람이 영상 모델을 고른 뒤에(맨 위 「사용자에게 먼저 물을 것」)" : `## 영상 모델 컷 — ${provider}로(고른 답, 돈이 든다)`,
+    "",
+    "캐릭터가 실제로 움직여야 하는 컷이다. 그림을 먼저 만들었으면 그걸 첫 프레임으로 준다. 받은 클립은 장면에 `<video data-kf-from=\"<장면 시작 초>\" muted playsinline>` 로 둔다(장면이 영상보다 길면 다른 화면 안 움직임으로 잇는다).",
+    "",
+    ...cuts.map((g) => `- \`${g.id}\`(장면 ${g.scene}) — ${g.prompt}\n  \`npx kf gen vid "<구체적 프롬프트>" --id ${g.id} --dur ${g.dur ?? 5} --aspect ${aspect}${g.first ? ` --first ${dir}/${g.first}` : ""}${provider ? ` --provider ${provider}` : ""} --project ${dir} --yes\` → \`ctx.asset("gen/${g.id}.mp4")\``),
+    "",
+  ];
+}
+
+// 주인공 3D 장면 — Blender 가 있으면 툰 샷을 굽고, 없어서 three 로 대신하기로 했으면 장면 안에서 stage3d 로 짓는다
+function shotSection(dir: string, kf: ProjectFile, plan: BriefPlan): string[] {
+  const shots = plan.shots ?? [];
+  if (!shots.length) return [];
+  const out = ["## 주인공 3D 장면", ""];
+  for (const s of shots) {
+    const sc = kf.scenes.find((x) => x.id === s.scene);
+    const span = sc ? `${sc.from.toFixed(2)}–${(sc.from + sc.dur).toFixed(2)}초` : "";
+    const meta = join(dir, "assets", "blender", `${s.id}.json`);
+    if (s.tool === "blender" && existsSync(meta)) {
+      const m = JSON.parse(readFileSync(meta, "utf8"));
+      out.push(`- \`${s.scene}\`(${span}) — 구워 둠: \`<video src="\${ctx.asset("blender/${s.id}.mp4")}" data-kf-from="${m.dataKfFrom}" muted playsinline>\` 를 장면 바탕(또는 주인공 판)으로 두고 그 위에 낱말·숫자를 얹는다`);
+    } else if (s.tool === "blender") {
+      out.push(
+        `- \`${s.scene}\`(${span}) — ${s.idea}`,
+        `  1. \`${dir}/${s.file}\` 를 \`tools/blender/kfb.py\` 헬퍼로 짠다 — 쓰는 법 \`tools/blender/README.md\`, 예 \`tools/blender/shots/lighthouse.py\`. 물체는 한 번 짓고 \`update(t)\` 는 t 만 본다, 카메라 열쇠는 \`S.downbeats\`·\`S.drops\` 에(도착하면 선다), 쉬지 않는 몫은 박에 뛰는 물체가 진다. 색은 style.json 잉크.`,
+        `  2. \`npx kf blender ${dir}/${s.file} --project ${dir} --scene ${s.scene} --id ${s.id} --still <장면 안 두세 시각>\` 로 몇 장 보고 고친다`,
+        `  3. \`npx kf blender ${dir}/${s.file} --project ${dir} --scene ${s.scene} --id ${s.id} --res 50 --step 2\` 로 굽는다(무겁다 — 한 번에) → 명령이 찍어 준 \`<video data-kf-from>\` 값으로 장면에 건다`,
+      );
+    } else {
+      out.push(`- \`${s.scene}\`(${span}) — ${s.idea}. Blender 가 없어 three.js 로 — \`import { stage3d, THREE } from "@kasaframe/themes/stage3d"\`: \`const st = stage3d(root, { ctx, shot: (t, cam) => { /* 카메라는 이유 있을 때만 */ } }); st.add((t) => { /* 물체 자세 */ });\` → \`(t) => st.paint(t)\``);
+    }
+  }
+  return [...out, ""];
+}

package/packages/plan/src/captions.ts

@@ -0,0 +1,78 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { captionMetrics, captionMode, toCues, type CaptionLine, type CaptionMode, type Cue } from "@kasaframe/motion/captions";
+import { readProject } from "./brief.ts";
+
+// 자막 트랙 — srt(유튜브)·vtt(사이트). OG 쇼츠 scripts/srt3d.py 의 관례를 따른다.
+// 마디 나누기는 화면 자막 판(@kasaframe/motion/captions)과 같은 toCues 라 트랙과 화면이 한 마디도 어긋나지 않는다.
+
+export { toCues };
+export type { CaptionLine, Cue };
+
+function ts(s: number, sep: string): string {
+  const ms = Math.round(s * 1000);
+  const p = (n: number, w = 2) => String(n).padStart(w, "0");
+  return `${p(Math.floor(ms / 3600000))}:${p(Math.floor(ms / 60000) % 60)}:${p(Math.floor(ms / 1000) % 60)}${sep}${p(ms % 1000, 3)}`;
+}
+
+export function srt(cues: Cue[]): string {
+  return cues.map((c, i) => `${i + 1}\n${ts(c.from, ",")} --> ${ts(c.to, ",")}\n${c.text}\n`).join("\n");
+}
+
+export function vtt(cues: Cue[]): string {
+  return `WEBVTT\n\n${cues.map((c) => `${ts(c.from, ".")} --> ${ts(c.to, ".")}\n${c.text}\n`).join("\n")}`;
+}
+
+// 뮤비 가사. 시각이 붙은 lyrics.json(natsu_mv align_lyrics.py 꼴: {lines:[{text,start,end}]})이 있으면 그대로,
+// 시각 없는 lyrics.txt 뿐이면 인트로·아웃트로를 뺀 구간에 줄 길이 비율로 대충 편다 — 정확한 시각은 보컬 분리(demucs) + 강제 정렬로(큰 모델이라 GPU 있는 기계에서)
+function lyricLines(dir: string, scenes: { id: string; role: string; from: number; dur: number }[]): CaptionLine[] | null {
+  const find = (f: string) => [join(dir, f), join(dir, "assets", "in", f)].find((p) => existsSync(p));
+  const timed = find("lyrics.json");
+  if (timed) {
+    const j = JSON.parse(readFileSync(timed, "utf8")) as { lines?: { text: string; start: number; end: number; words?: { w: string; start: number; end: number }[] }[] };
+    return (j.lines ?? []).map((l) => ({ from: l.start, to: l.end, text: l.text, words: l.words?.map((w) => ({ text: w.w, from: w.start, to: w.end })) }));
+  }
+  const plain = find("lyrics.txt");
+  if (!plain) return null;
+  const lines = readFileSync(plain, "utf8").split("\n").map((l) => l.trim()).filter(Boolean);
+  const sung = scenes.filter((s) => !/intro|outro/.test(s.role));
+  const total = sung.reduce((a, s) => a + s.dur, 0);
+  const chars = lines.reduce((a, l) => a + l.length, 0);
+  const out: CaptionLine[] = [];
+  let k = 0;
+  let acc = 0;
+  for (const l of lines) {
+    let at = (acc / chars) * total;
+    while (k < sung.length - 1 && at > sung[k].dur) {
+      at -= sung[k].dur;
+      acc -= (sung[k].dur / total) * chars;
+      k++;
+    }
+    const from = sung[k].from + at;
+    out.push({ from, to: from + (l.length / chars) * total, text: l });
+    acc += l.length;
+  }
+  return out;
+}
+
+// 프로젝트의 captions.json(또는 가사) → out/captions.ko.srt·vtt. 자막 none 이거나 들릴 말이 없으면 빈 배열. mode 는 kf.json 을 그 판만 덮는다
+export function writeCaptions(dir: string, mode?: CaptionMode): string[] {
+  const kf = readProject(dir);
+  // captions 칸이 없는 옛 프로젝트는 들릴 말이 있으면 트랙만 낸다
+  if ((mode ?? (kf.captions === undefined ? "off" : captionMode(kf.captions))) === "none") return [];
+  const scenes = kf.scenes;
+  const file = join(dir, "captions.json");
+  const lines = existsSync(file) ? (JSON.parse(readFileSync(file, "utf8")) as CaptionLine[]) : lyricLines(dir, scenes);
+  if (!lines) return [];
+  // 화면 판과 같은 마디로 — style.json captions(글자 크기·줄 수)가 있으면 그 값으로 나눈다
+  const stylePath = join(dir, (kf as { style?: string }).style ?? "style.json");
+  const look = existsSync(stylePath) ? JSON.parse(readFileSync(stylePath, "utf8")).captions : undefined;
+  const m = kf.width && kf.height ? captionMetrics({ width: kf.width, height: kf.height, safe: kf.safeArea, minPx: kf.text?.minPx, look }) : undefined;
+  const cues = toCues(lines, scenes, { maxEm: m?.maxEm, duration: kf.duration, maxLines: m?.maxLines });
+  if (!cues.length) return [];
+  mkdirSync(join(dir, "out"), { recursive: true });
+  const out = [join(dir, "out", "captions.ko.srt"), join(dir, "out", "captions.ko.vtt")];
+  writeFileSync(out[0], srt(cues));
+  writeFileSync(out[1], vtt(cues));
+  return out;
+}

package/packages/plan/src/detect.ts

@@ -0,0 +1,93 @@
+import { mentions, parseAspect, parseDuration } from "./request.ts";
+import type { Purpose, Template } from "./types.ts";
+
+export interface DetectInput {
+  request: string;
+  assets?: string[]; // 받은 파일 경로들
+  music?: string | null;
+}
+
+export interface Ranked {
+  purpose: Purpose;
+  score: number;
+  p: number;
+  reasons: string[];
+}
+
+export interface Detection {
+  purpose: Purpose;
+  confidence: number;
+  ranked: Ranked[];
+  // 낱말이 하나도 안 걸렸거나 1·2위가 붙어 있으면 사람에게 묻는다
+  ambiguous: boolean;
+}
+
+const VIDEO = /\.(mp4|mov|webm|mkv|m4v)$/i;
+const TEMPERATURE = 1.5;
+export const ASK_BELOW = 0.5;
+
+export function detect(input: DetectInput, templates: Template[]): Detection {
+  const { request } = input;
+  const dur = parseDuration(request);
+  const aspect = parseAspect(request);
+  const hasVideo = (input.assets ?? []).some((a) => VIDEO.test(a));
+  let anyWord = false;
+
+  const scored = templates.map((tpl) => {
+    let score = 0;
+    const reasons: string[] = [];
+    for (const w of tpl.detect.words) {
+      if (mentions(request, w)) {
+        score += 3;
+        anyWord = true;
+        reasons.push(`"${w}"`);
+      }
+    }
+    for (const w of tpl.detect.hints) {
+      if (mentions(request, w)) {
+        score += 1;
+        reasons.push(`"${w}"(힌트)`);
+      }
+    }
+    if (aspect) {
+      if (aspect === tpl.aspect) {
+        score += 2;
+        reasons.push(`화면 ${aspect}`);
+      } else if (tpl.variants?.[aspect]) score += 0.5;
+      else score -= 1.5;
+    }
+    if (dur !== undefined) {
+      const { min, max, allowed } = tpl.duration;
+      if (allowed?.includes(dur)) {
+        score += 2.5;
+        reasons.push(`${dur}초 = 고정 길이`);
+      } else if (dur >= min && dur <= max) {
+        score += 1.5;
+        reasons.push(`${dur}초가 ${min}–${max}초 안`);
+      } else score -= 2;
+    }
+    if (hasVideo && tpl.detect.assetKinds?.includes("video")) {
+      score += 2;
+      reasons.push("받은 자산에 영상");
+    }
+    if (input.music && tpl.music === "required") score += 0.5;
+    return { purpose: tpl.id, score, reasons };
+  });
+
+  const z = scored.map((s) => Math.exp(s.score / TEMPERATURE));
+  const sum = z.reduce((a, b) => a + b, 0);
+  const ranked: Ranked[] = scored
+    .map((s, i) => ({ ...s, p: round(z[i] / sum) }))
+    .sort((a, b) => b.score - a.score);
+  const top = ranked[0];
+  return {
+    purpose: top.purpose,
+    confidence: top.p,
+    ranked,
+    ambiguous: !anyWord || top.p < ASK_BELOW,
+  };
+}
+
+function round(x: number): number {
+  return Math.round(x * 100) / 100;
+}

package/packages/plan/src/index.ts

@@ -0,0 +1,27 @@
+export type * from "./types.ts";
+export { PURPOSES } from "./types.ts";
+export { templatesDir, listTemplates, loadTemplate, frameFor, sceneSkeleton } from "./templates.ts";
+export { parseAspect, parseDuration, parseStyle, parseTitle, mentions } from "./request.ts";
+export { detect, ASK_BELOW } from "./detect.ts";
+export type { Detection, Ranked, DetectInput } from "./detect.ts";
+export { pickDuration, layoutScenes } from "./layout.ts";
+export type { Layout, LaidScene } from "./layout.ts";
+export { makePlan, refuses3d, wantsMotionCut, wantsVideo } from "./plan.ts";
+export { applyAnswers, planQuestions, WAIT } from "./asks.ts";
+export type { PlanQuestions } from "./asks.ts";
+export type { PlanInput } from "./plan.ts";
+export { chat, codeBlock, jsonBlock, ledger, premiumBlock, spend, spentLine, writeStats } from "./llm.ts";
+export type { Message, Part, ChatResult, Spent } from "./llm.ts";
+export { projectBrief, readProject } from "./brief.ts";
+export type { ProjectFile, ProjectScene } from "./brief.ts";
+export { toCues, srt, vtt, writeCaptions } from "./captions.ts";
+export type { CaptionLine, Cue } from "./captions.ts";
+export { suggestThemes, pickTheme, themeFromRequest } from "./themes.ts";
+export type { ThemePick } from "./themes.ts";
+export { look, lookSheet, formatLook, DEFAULT_EYES } from "./look.ts";
+export type { LookSheet } from "./look.ts";
+export type { LookReport, LookScene } from "./look.ts";
+export { attachStudio } from "./studio.ts";
+export type { StudioLink } from "./studio.ts";
+export { checkSeries, listSeries, loadSeries, seriesDir, seriesFromRequest, writeSeries } from "./series.ts";
+export type { Series } from "./series.ts";