kasaframe 0.1.1 → 0.1.3

package/packages/patterns/src/types.ts

@@ -0,0 +1,67 @@
+import type { SceneCtx, Style } from "@kasaframe/core";
+import type { ThemeSlots } from "@kasaframe/themes/slots";
+
+// 감독 packages/director/src/pattern.ts 와 같은 꼴(구조로 맞춘다). 감독이 패키지로 서면 그쪽 꼴을 import type 으로 받는다 — slots 만 테마 슬롯 꼴로 좁힌다.
+
+export type Energy = "low" | "mid" | "high";
+export type Family = "slam" | "flap" | "grow" | "draw" | "type" | "pop" | "mask" | "flow" | "stack" | "morph";
+export type CameraKind = "none" | "pushIn" | "pullOut" | "follow" | "impact";
+export type AspectName = "16:9" | "9:16" | "1:1";
+export type TextPolicy = "none" | "terms-only" | "captions" | "lyrics";
+
+export interface FitInfo {
+  aspect: AspectName;
+  dur: number;
+  policy: TextPolicy;
+}
+
+export interface StageLike {
+  box: HTMLDivElement;
+  cam: HTMLDivElement;
+  safeW: number;
+  safeH: number;
+  vertical: boolean;
+  camera: {
+    pushIn(at: number, o?: { to?: unknown; scale?: number; dur?: number }): unknown;
+    pullOut(at: number, o?: { to?: unknown; scale?: number; dur?: number }): unknown;
+    follow(target: unknown, from: number, to: number, o?: { scale?: number }): unknown;
+    impact(at: number, o?: { amount?: number; dur?: number }): unknown;
+  };
+  hero(el: HTMLElement): HTMLElement;
+}
+
+export interface SpokenWord {
+  text: string;
+  from: number;
+  to: number;
+}
+
+export interface Kit {
+  seed: string;
+  hits: number[];
+  say: SpokenWord[];
+  slots: ThemeSlots;
+  stage: StageLike;
+  policy: TextPolicy;
+  first: boolean;
+  last: boolean;
+  loop: boolean;
+}
+
+export interface Pattern<C = any> {
+  id: string;
+  type: string;
+  does: string;
+  energy: Energy[];
+  family: Family;
+  camera: CameraKind[];
+  bg: "stage" | "own";
+  aspects: AspectName[];
+  dur: { min: number; max: number };
+  themes?: Record<string, number>;
+  purposes?: { prefer?: string[]; avoid?: string[] };
+  fits?(content: C, info: FitInfo): true | string;
+  build(root: HTMLElement, ctx: SceneCtx, content: C, kit: Kit): (t: number) => void;
+}
+
+export type { SceneCtx, Style, ThemeSlots };

package/packages/patterns/src/words/moves.ts

@@ -0,0 +1,42 @@
+import { dressText } from "@kasaframe/motion/moves";
+import { area, moving, node } from "../kit.ts";
+import type { Energy, Family, Pattern } from "../types.ts";
+
+export interface WordsContent {
+  words: string[];
+}
+
+// 낱말 리듬은 연출 수 메뉴(@kasaframe/motion/moves dress)의 글 수가 이미 박에 맞춰 검사를 넘긴 값으로 그린다 — 패턴은 고를 수 있는 이름과
+// 고르는 표(에너지·계열)만 붙인다. 수마다 낱말 수·길이 한계가 다르다. ghostStack·splitFlap 은 세로 밝은 테마에서 멈춤 검사를 못 넘어 아직 안 건다
+function wordsPattern(o: { name: string; move: string; does: string; energy: Energy[]; family: Family; max: number; maxLen: number }): Pattern<WordsContent> {
+  return {
+    id: `words.${o.name}`,
+    type: "words",
+    does: o.does,
+    energy: o.energy,
+    family: o.family,
+    camera: ["none"],
+    bg: "stage",
+    aspects: ["16:9", "9:16", "1:1"],
+    dur: { min: 1.2, max: 9 },
+    fits(c) {
+      const ws = (c?.words ?? []).filter((x) => typeof x === "string" && x.trim());
+      if (!ws.length) return "words 가 비었다";
+      if (ws.length > o.max) return `낱말이 ${o.max}개를 넘는다`;
+      if (ws.some((x) => [...x].length > o.maxLen)) return `낱말 하나가 ${o.maxLen}자를 넘는다`;
+      return true;
+    },
+    build(root, ctx, c, kit) {
+      const { w, h } = area(ctx, kit);
+      const host = node(root, "position:absolute;inset:0");
+      const paint = dressText(o.move, host, ctx, { words: c.words, w, h, ready: kit.first }) ?? (() => {});
+      kit.stage?.hero(host);
+      return (t: number) => {
+        moving(`words.${o.name}`, ctx);
+        paint(t);
+      };
+    },
+  };
+}
+
+export const wordsSlam = wordsPattern({ name: "slam", move: "slamWords", does: "박마다 낱말 하나가 화면 띠를 꽉 채우며 쾅 — 판과 글색이 뒤집힌다", energy: ["high"], family: "slam", max: 6, maxLen: 10 });

package/packages/patterns/src/words/slam.ts

@@ -0,0 +1,4 @@
+import { wordsSlam } from "./moves.ts";
+
+// 장면 파일이 @kasaframe/patterns/words/slam 로 가져간다
+export default wordsSlam;

package/packages/plan/src/asks.ts

@@ -0,0 +1,256 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { byMood, estimateImageUsd, howToGet, listLibrary, musicQuestion, ttsProviders, videoProviders, voiceQuestion, WAIT, type CapabilityReport, type Choice, type Question, type VideoRequest } from "@kasaframe/gen";
+import { listThemes, sheetDir, themeDims, themeSample } from "@kasaframe/themes";
+import { loadSeries } from "./series.ts";
+import { loadTemplate } from "./templates.ts";
+import { suggestThemes, themeFromRequest } from "./themes.ts";
+import type { Plan } from "./types.ts";
+
+// 계획이 쓰려는 능력을 지금 있는 능력에 맞춘다 — 돈이 들거나 없거나 제한이 걸린 것만 묻고, 나머지는 바로 정한다(auto)
+export interface PlanQuestions {
+  questions: Question[];
+  auto: Record<string, string>; // 물을 것 없이 정해진 답(공짜로 있는 능력)
+}
+
+export { WAIT };
+
+// 없는 능력 — 조용히 대체하지 않는다. ① 넣는 법(권장) ② 지금 쓸 수 있는 다른 엔진 ③ 빼기를 나란히 두고 사람이 고른다
+function missing(q: Omit<Question, "default" | "skip" | "missing" | "choices">, install: Choice, others: Choice[], drop: Choice): Question {
+  return { ...q, choices: [install, ...others, drop], default: WAIT, skip: drop.value, missing: true };
+}
+
+const money = (n: number) => (n < 0.1 ? `$${n.toFixed(3)}` : `$${n.toFixed(2)}`);
+const ids = (xs: { id: string }[]) => xs.map((x) => x.id).join("·");
+
+function imageQuestion(plan: Plan, caps: CapabilityReport): { q?: Question; auto?: string } {
+  const imgs = plan.gen.filter((g) => g.kind === "img");
+  if (!imgs.length) return {};
+  const ready = caps.providers.filter((p) => p.ready);
+  const og = ready.find((p) => p.id.startsWith("og-"));
+  const codex = ready.find((p) => p.id === "codex-imagegen");
+  const none: Choice = { value: "none", label: "그림 없이", note: "받은 자산·도형·실제 화면 오리기로 장면을 채운다" };
+  if (og) {
+    const usd = imgs.reduce((n, g) => n + estimateImageUsd({ prompt: "", size: g.size ?? `${plan.width}x${plan.height}`, quality: g.quality ?? "high", refs: g.refs }), 0);
+    return {
+      q: {
+        id: "image",
+        cap: "image",
+        header: "그림 생성",
+        ask: `그림 ${imgs.length}장(${ids(imgs)})을 OG gpt-image 로 만들까? 견적 최대 ${money(usd)}`,
+        choices: [
+          { value: og.id, label: `OG ${og.id.replace(/^og-/, "")}`, costUsd: usd, note: "장당 20–30초" },
+          ...(codex ? [{ value: codex.id, label: "codex imagegen", costUsd: 0, note: "ChatGPT 요금제 안 — 장당 1–2분" }] : []),
+          none,
+        ],
+        default: og.id,
+        skip: "none",
+        flag: "--image",
+      },
+    };
+  }
+  // 기본 그림 모델(OG)이 없다 — codex 가 있어도 조용히 넘어가지 않고 다른 엔진 보기로 둔다
+  return {
+    q: missing(
+      { id: "image", cap: "image", header: "그림 모델", ask: `그림 ${imgs.length}장(${ids(imgs)})을 만들 기본 그림 모델(OG gpt-image)이 없다`, flag: "--image" },
+      { value: WAIT, label: "키를 넣고 다시", note: `${howToGet("opengateway")}${codex ? "" : " · 또는 0원 codex: npm i -g @openai/codex && codex login(ChatGPT 계정)"}` },
+      codex ? [{ value: codex.id, label: "codex imagegen 으로", costUsd: 0, note: "ChatGPT 로그인 — 0원, 장당 1–2분" }] : [],
+      none,
+    ),
+  };
+}
+
+function videoQuestion(plan: Plan, caps: CapabilityReport): { q?: Question; auto?: string } {
+  const vids = plan.gen.filter((g) => g.kind === "vid");
+  if (!vids.length) return {};
+  const scene = (id?: string) => plan.scenes.find((s) => s.id === id);
+  const reqs: VideoRequest[] = vids.map((g) => ({
+    prompt: g.prompt,
+    duration: g.seam ? (scene(g.scene)?.dur ?? 5) : (g.dur ?? 5),
+    aspect: plan.aspect,
+    ...(g.seam || g.first ? { firstFrame: "x" } : {}),
+    ...(g.seam || g.last ? { lastFrame: "y" } : {}),
+  }));
+  const ready = new Set(caps.providers.filter((p) => p.ready).map((p) => p.id));
+  const restrict = new Map(caps.providers.map((p) => [p.id, p.restrict]));
+  const options = videoProviders()
+    .filter((p) => ready.has(p.id))
+    .filter((p) => reqs.every((r) => !r.lastFrame || p.firstLast))
+    .map((p) => ({ p, usd: reqs.reduce((n, r) => n + p.estimateUsd(r), 0), restrict: restrict.get(p.id) }))
+    .sort((a, b) => a.usd - b.usd);
+  const open = options.filter((o) => !o.restrict);
+  const limited = options.filter((o) => o.restrict);
+  const what = `영상 모델 컷 ${vids.length}개(${vids.map((g) => `${g.id}${g.seam ? " 이음매" : ""}`).join("·")})`;
+  const none: Choice = { value: "none", label: "영상 모델 없이", note: "이음매는 three 3D 전환, 움직임 컷은 그림·모션그래픽으로" };
+  if (!options.length) {
+    return {
+      q: missing(
+        { id: "video", cap: "video", header: "영상 모델", ask: `${what}를 만들 영상 모델이 없다`, flag: "--video" },
+        { value: WAIT, label: "키를 넣고 다시", note: `${howToGet("fal")} · 또는 ${howToGet("gemini")} · 사내 ${howToGet("h3")}` },
+        [],
+        none,
+      ),
+    };
+  }
+  // 돈도 제한도 없는 길이 있으면 묻지 않는다(아직 그런 공급자는 없다 — H3 는 0원이지만 지역 제한이 걸린다)
+  if (open[0] && open[0].usd === 0) return { auto: open[0].p.id };
+  const choices: Choice[] = [
+    ...open.slice(0, 2).map((o) => ({ value: o.p.id, label: o.p.id, costUsd: o.usd })),
+    ...limited.slice(0, 1).map((o) => ({ value: o.p.id, label: `${o.p.id}(사내 파드)`, costUsd: o.usd, note: o.restrict })),
+    none,
+  ];
+  return {
+    q: {
+      id: "video",
+      cap: "video",
+      header: "영상 모델",
+      ask: open.length ? `${what} — ${open[0].p.id} 로 만들까? 견적 ${money(open[0].usd)}` : `${what} — 쓸 수 있는 건 지역 제한이 걸린 것뿐이다`,
+      choices: choices.slice(0, 4),
+      // 제한 걸린 길은 사람이 짚어야만 — --yes 로 회사·바깥 결과물에 섞이지 않게
+      default: open[0]?.p.id ?? "none",
+      skip: "none",
+      flag: "--video",
+    },
+  };
+}
+
+function blenderQuestion(plan: Plan, caps: CapabilityReport): { q?: Question; auto?: string } {
+  if (!plan.shots?.length) return {};
+  const b = caps.providers.find((p) => p.id === "blender");
+  if (b?.ready) return { auto: "blender" };
+  return {
+    q: missing(
+      { id: "blender", cap: "blender", header: "3D 샷", ask: `주인공 3D 장면(${plan.shots.map((s) => s.scene).join("·")})을 구울 Blender 가 없다 — ${b?.detail ?? "못 찾음"}`, flag: "--blender" },
+      { value: WAIT, label: "Blender 를 깔고 다시", note: `${b?.fix ?? "blender.org 에서 4.3 이상"} — 확인은 kf doctor 「생성 능력」` },
+      [{ value: "three", label: "three.js 로", note: "장면 안에서 stage3d 로 3D 를 짓는다(툰 셰이딩·라인아트는 없다)" }],
+      { value: "none", label: "3D 없이", note: "2D 모션그래픽 장면으로" },
+    ),
+  };
+}
+
+// 목소리 — 틀이 내레이션을 켰을 때만. 시리즈가 박은 목소리는 사람이 미리 준 답이라 그 엔진이 있으면 묻지 않는다.
+// 그 밖엔 늘 묻는다(목소리는 결이라 돈이 안 들어도) — 보기 차례는 voiceQuestion(로컬 Qwen3·ElevenLabs·자막만·그 밖)
+function voicePart(plan: Plan, caps: CapabilityReport): { q?: Question; auto?: string } {
+  const n = loadTemplate(plan.purpose).narration;
+  if (!n?.on || plan.voice) return {};
+  const ready = caps.providers.filter((p) => p.ready).map((p) => p.id);
+  const want = plan.series ? loadSeries(plan.series).voice : undefined;
+  if (!want) return n.voice === "none" ? { auto: "none" } : { q: voiceQuestion({ voices: n.voices, ready }) };
+  if (want === "none") return { auto: "none" };
+  const engine = want.split(":")[0];
+  if (ready.includes(engine)) return { auto: want };
+  const p = ttsProviders().find((x) => x.id === engine);
+  const others = ttsProviders().filter((x) => ready.includes(x.id)).slice(0, 2);
+  return {
+    q: missing(
+      { id: "voice", cap: "voice", header: "목소리", ask: `시리즈 목소리 ${want}(${p?.label ?? engine})을 이 기계에서 못 쓴다`, flag: "--voice", accepts: (v: string) => v === "none" || ready.includes(v.split(":")[0]) },
+      { value: WAIT, label: `${p?.label ?? engine} 키를 넣고 다시`, note: howToGet(p?.keyName ?? engine) },
+      others.map((x) => {
+        const v = n.voices[x.id] ?? x.defaultVoice;
+        return { value: `${x.id}:${v}`, label: `${x.label} ${v} 로`, costUsd: x.estimateUsd("가".repeat(300)), note: `시리즈 목소리(${want})와 다르다 — 같은 시리즈의 다른 영상과 목소리가 달라진다` };
+      }),
+      { value: "none", label: "목소리 없이 — 자막만", costUsd: 0 },
+    ),
+  };
+}
+
+// 테마 — 시리즈가 정했거나 요청이 「리소 느낌」처럼 짚었으면 묻지 않는다(kf new 의 auto 가 그대로 짚은 테마를 쓴다).
+// 보기는 「알아서」(= auto, 권장)와 이 용도·화면비의 approved 테마 전부(요청에 맞는 차례) — theme.json status 만 approved 로 바꾸면 들어온다
+function themePart(plan: Plan): { q?: Question; auto?: string } {
+  if ((plan.series && loadSeries(plan.series).theme) || themeFromRequest(plan.request, plan.purpose)) return {};
+  const ranked = suggestThemes(plan.request, plan.purpose, plan.aspect, Infinity);
+  if (!ranked.length) return {};
+  const byId = new Map(listThemes({ status: "approved" }).map((t) => [t.id, t]));
+  const grid = join(sheetDir, "sheet.png");
+  const first = byId.get(ranked[0].id)!;
+  return {
+    q: {
+      id: "theme",
+      cap: "theme",
+      header: "테마",
+      ask: `테마는? ${existsSync(grid) ? `같은 문장 한 장면을 테마마다 찍은 견본 시트 ${grid}` : "보기마다 견본 그림 경로"}`,
+      choices: [
+        { value: "auto", label: "알아서", note: `요청 낱말에 맞는 approved 테마를 고른다 — 지금이면 ${first.name}` },
+        ...ranked.map(({ id }) => {
+          const t = byId.get(id)!;
+          const sample = themeSample(t);
+          return { value: t.id, label: `${t.name} · ${themeDims(t)}`, note: `${t.metaphor}${sample ? ` — 견본 ${sample}` : ""}` };
+        }),
+      ],
+      default: "auto",
+      skip: "auto",
+      flag: "--theme",
+      // 보기 밖이라도 사람이 짚은 review 테마·none(프리셋만)은 받는다 — kf new --theme 과 같은 범위
+      accepts: (v: string) => v === "none" || listThemes({ status: ["approved", "review"] }).some((t) => t.id === v),
+    },
+  };
+}
+
+// 곡 — 틀이 분위기를 정한 용도만. 시리즈 곡·분위기 맞는 곡 모음 곡(0원·늘 같은 곡)은 묻지 않는다.
+// 없으면 생성(돈)·곡 넣기·없음을 묻고, 생성 키도 없으면 다른 분위기 곡·「곡 없이」로 조용히 넘어가지 않고 missing 으로 묻는다
+function musicPart(plan: Plan, caps: CapabilityReport): { q?: Question; auto?: string } {
+  // 시리즈가 정한 분위기가 틀 분위기를 덮는다 — 같은 시리즈면 같은 곡
+  const mood = plan.mood ?? loadTemplate(plan.purpose).mood;
+  if (!mood || plan.music) return {};
+  const file = plan.series ? loadSeries(plan.series).music?.file : undefined;
+  if (file) return { auto: fileURLToPath(new URL(`../../../${file}`, import.meta.url)) };
+  const lib = byMood(mood);
+  if (lib.length) return { auto: lib[0].path };
+  const ready = caps.providers.filter((p) => p.ready && p.id !== "library").map((p) => p.id);
+  const put: Choice = { value: WAIT, label: "곡을 넣고 다시", note: `kf music add <곡> --mood ${mood} --source <원본> --license "<라이선스>" 로 곡 모음에 넣거나 --music <곡 파일>` };
+  const q = musicQuestion({ mood, duration: plan.duration, ready });
+  if (ready.length) return { q: { ...q, choices: [q.choices[0], put, ...q.choices.slice(1)].slice(0, 4) } };
+  const { default: _d, skip: _s, choices: _c, ...head } = q;
+  return {
+    q: missing(
+      { ...head, ask: `분위기 ${mood} 에 맞는 곡이 곡 모음에 없고 음악 생성 키도 없다` },
+      { ...put, label: "곡이나 생성 키를 넣고 다시", note: `${put.note} · 생성은 ${howToGet("gemini")}(Lyria 3.5, 유료 등급) 또는 ${howToGet("elevenlabs")}(Eleven Music)` },
+      listLibrary().filter((t) => t.license && t.mood.length).slice(0, 1).map((t) => ({ value: t.path, label: `곡 모음 「${t.title}」로`, costUsd: 0, note: `틀 분위기(${mood})와 다른 곡(${t.mood.join("·")}) — ${t.license}` })),
+      { value: "none", label: "곡 없이", costUsd: 0 },
+    ),
+  };
+}
+
+export function planQuestions(plan: Plan, caps: CapabilityReport[]): PlanQuestions {
+  const by = (c: string) => caps.find((x) => x.cap === c) ?? { cap: c, label: c, providers: [], best: null };
+  const parts: [string, { q?: Question; auto?: string }][] = [
+    ["theme", themePart(plan)],
+    ["image", imageQuestion(plan, by("image") as CapabilityReport)],
+    ["video", videoQuestion(plan, by("video") as CapabilityReport)],
+    ["blender", blenderQuestion(plan, by("blender") as CapabilityReport)],
+    ["voice", voicePart(plan, by("voice") as CapabilityReport)],
+    ["music", musicPart(plan, by("music") as CapabilityReport)],
+  ];
+  const out: PlanQuestions = { questions: [], auto: {} };
+  for (const [id, r] of parts) {
+    if (r.q) out.questions.push(r.q);
+    else if (r.auto) out.auto[id] = r.auto;
+  }
+  return out;
+}
+
+// 답대로 계획을 고친다 — 빼기로 한 능력의 만들 거리를 지우고, 고른 공급자를 적는다. wait 를 고른 질문은 stop 으로 돌려준다
+export function applyAnswers(plan: Plan, answers: Record<string, string>, questions: Question[] = []): { plan: Plan; stop: string[] } {
+  const stop = questions.filter((q) => answers[q.id] === WAIT).map((q) => `${q.ask} — ${q.choices.find((c) => c.value === WAIT)?.note ?? ""}`);
+  const p: Plan = { ...plan, answers: { ...(plan.answers ?? {}), ...answers } };
+  const drop = (kind: "img" | "vid") => {
+    const gone = new Set(p.gen.filter((g) => g.kind === kind).map((g) => g.id));
+    p.gen = p.gen.filter((g) => g.kind !== kind);
+    p.scenes = p.scenes.map((s) => ({ ...s, assets: s.assets.filter((a) => !gone.has(a.replace(/^gen:(img|vid):/, ""))) }));
+    // 지운 그림을 첫 프레임으로 기다리던 영상은 글만으로 간다
+    if (kind === "img") p.gen = p.gen.map((g) => (g.first && gone.has(g.first.replace(/^assets\/gen\/|\.png$/g, "")) ? { ...g, first: undefined } : g));
+  };
+  const pick = (kind: "img" | "vid", v?: string) => {
+    if (!v || v === WAIT) return;
+    if (v === "none") drop(kind);
+    else p.gen = p.gen.map((g) => (g.kind === kind ? { ...g, provider: v } : g));
+  };
+  pick("img", answers.image);
+  pick("vid", answers.video);
+  // 목소리·곡은 kf narrate 가 읽는 칸으로 — 곡 파일 경로는 kf new 가 곡으로 깔고, gen:·none 은 narrate 가 처리한다
+  if (answers.voice && answers.voice !== WAIT) p.voice = answers.voice;
+  if (answers.blender === "none") p.shots = [];
+  else if (answers.blender === "three") p.shots = (p.shots ?? []).map((s) => ({ ...s, tool: "three" }));
+  return { plan: p, stop };
+}

package/packages/plan/src/brief.ts

@@ -1,6 +1,9 @@
 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";
 
@@ -14,6 +17,8 @@ export interface ProjectScene {
   role: string;
   idea: string;
   assets?: string[];
+  // kf new 가 고른 연출 수 — 뼈대 장면 파일의 DRESS 와 같다
+  dress?: Dress;
 }
 
 export interface ProjectFile {
@@ -27,6 +32,10 @@ export interface ProjectFile {
   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[];
@@ -123,6 +132,8 @@ export function projectBrief(dir: string): string {
   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}초 넘으면 오류) — 새 요소·칸 채우기·숫자 키우기·컷·전환으로 바꾼다.`,
@@ -164,8 +175,8 @@ export function projectBrief(dir: string): string {
     "- 글자에 `undefined`·`NaN`·`null` 이 찍히지 않게 값은 미리 문자열로 만든다. 이모지 금지(아이콘은 인라인 SVG).",
     "- 장면이 1초 넘게 멈추지 않게 한다(아주 느린 다가가기라도). 빈 화면으로 시작·끝내지 않는다.",
     "- **화면을 채운다**(kf check layout.fill): 주 요소가 안전 영역을 크게 차지한다 — 세로 화면은 폭의 70% 넘게, 글은 큰 글자 단계(hero·title)로. 가운데 작은 그림 하나에 나머지가 흰 여백이면 실패다.",
-    "- 구도 판정(kf check layout.static)은 칸 평균 밝기와 화면 안 내용(글·칸의 센 가장자리)으로 본다 — 숫자가 구르고 칸이 차면 바뀐 것이고, 부드럽게 흐르는 바탕만으로는 안 바뀐다. 카메라 샷으로 메우지 않는다.",
-    "- `../lib/stage.ts` 의 `makeStage(root, ctx)`(늘 흐르는 빛 방울 바탕·컷마다 모양을 바꾸는 바탕 판·정지 카메라 `stage.camera`)·`makeCamera(layer, ctx, { frame })`(자기 카메라 층에)·`bigWord`·`fitPx`·`cutTimes`·`lastT` 를 써도 된다 — 위 규칙을 처음부터 넘게 짜 둔 도구다. 카메라가 요소를 겨누면 `stage.tick(t)` 은 내용을 칠한 뒤 맨 끝에.",
+    "- 구도 판정(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(" "),
@@ -176,17 +187,21 @@ export function projectBrief(dir: string): string {
     ...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`). 낱말이 없으면 줄을 글자 수 비율로 나눈다.', ""]
@@ -210,14 +225,81 @@ export function projectBrief(dir: string): string {
   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 }): string[] {
+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}");\``,
       "",
@@ -239,16 +321,63 @@ function themeSection(id: string | undefined, plan: { themeCandidates?: { id: st
   return [];
 }
 
-// 그림 생성은 돈이 들고, 막연한 자동 프롬프트는 엉뚱한 그림을 냈다 — 아직 없는 그림은 목록으로만 내고 세션이 프롬프트를 써서 만든다
-function genSection(dir: string, kf: ProjectFile, plan: { gen?: { id: string; kind: string; scene?: string; prompt: string; size?: string }[] }): string[] {
+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}`} --project ${dir}\` → \`ctx.asset("gen/${g.id}.png")\``),
+    ...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

@@ -64,8 +64,11 @@ export function writeCaptions(dir: string, mode?: CaptionMode): string[] {
   const file = join(dir, "captions.json");
   const lines = existsSync(file) ? (JSON.parse(readFileSync(file, "utf8")) as CaptionLine[]) : lyricLines(dir, scenes);
   if (!lines) return [];
-  const maxEm = kf.width && kf.height ? captionMetrics({ width: kf.width, height: kf.height, safe: kf.safeArea, minPx: kf.text?.minPx }).maxEm : undefined;
-  const cues = toCues(lines, scenes, { maxEm, duration: kf.duration });
+  // 화면 판과 같은 마디로 — 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")];

package/packages/plan/src/index.ts

@@ -6,9 +6,11 @@ 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, wantsVideo } from "./plan.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 } from "./llm.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";
@@ -21,3 +23,5 @@ 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";