kasaframe 0.1.1 → 0.1.4

package/packages/plan/src/index.ts

@@ -6,18 +6,22 @@ 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, THEME_PICKS, usableTheme, 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";
 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 type { LookInput, 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";

package/packages/plan/src/llm.ts

@@ -1,15 +1,27 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { readKey } from "@kasaframe/gen";
 
 // OG chat/completions 하나로 어떤 모델이든 부른다. 그림 보는 검사도 여기로 — OG /v1/messages 는 딥시크에 그림을 넘기지 않는다
 const BASE = process.env.KF_OG_BASE ?? "https://apis.opengateway.ai/v1";
 
+// Opus·GPT 계열은 한 번에 값이 크게 뛴다 — 장면 쓰기·고치기·그림 검사가 모두 이 문을 지나니 여기서 한 번만 막는다.
+// 짚은 사람이 풀어야만(--allow-premium 이 KF_ALLOW_PREMIUM=1 로 넘긴다 — 자식 kf 까지 같은 값)
+export function premiumBlock(model: string): string | null {
+  if (process.env.KF_ALLOW_PREMIUM === "1") return null;
+  const name = model.toLowerCase().split("/").pop() ?? "";
+  if (!/^claude.*opus|^opus/.test(name) && !/^(gpt|chatgpt|o\d+)([-.]|$)/.test(name)) return null;
+  return `${model} 은 비싼 모델(Opus·GPT 계열)이라 부르기 전에 막았다 — 꼭 써야 하면 --allow-premium(또는 KF_ALLOW_PREMIUM=1)`;
+}
+
 export type Part = { type: "text"; text: string } | { type: "image_url"; image_url: { url: string } };
 export interface Message {
   role: "system" | "user" | "assistant";
   content: string | Part[];
 }
 
-// 모델별로 쓴 만큼 — kf make 가 끝에 out/make-stats.json 으로 남겨 모델끼리 시간·토큰·비용을 견준다
+// 모델별로 쓴 만큼 — kf make 가 끝날 때(성공·실패·중단) <작업 폴더>/make-stats.json 에 남겨 모델끼리 시간·토큰·비용을 견준다.
+// og 는 OG 를 거친 호출(chat·OG 그림) — 그 밖의 생성(fal 영상 따위)도 같은 장부에 두되 「OG 호출」 줄에는 안 센다
 export interface Spent {
   model: string;
   stage: string;
@@ -18,9 +30,57 @@ export interface Spent {
   completion: number;
   cached: number;
   usd: number | null;
+  og: boolean;
 }
 const spent: Spent[] = [];
 export const ledger = (): Spent[] => [...spent];
+export const spend = (s: Spent): void => void spent.push(s);
+
+interface Total {
+  calls: number;
+  prompt: number;
+  completion: number;
+  cached: number;
+  usd: number;
+  ms: number;
+  // 가격표를 못 받아 값을 모르는 호출 수 — usd 합에 안 들어갔다
+  unpriced: number;
+}
+
+function sum(xs: Spent[]): Total {
+  const t: Total = { calls: xs.length, prompt: 0, completion: 0, cached: 0, usd: 0, ms: 0, unpriced: 0 };
+  for (const x of xs) {
+    t.prompt += x.prompt;
+    t.completion += x.completion;
+    t.cached += x.cached;
+    t.ms += x.ms;
+    if (x.usd === null) t.unpriced++;
+    else t.usd += x.usd;
+  }
+  t.usd = Number(t.usd.toFixed(6));
+  return t;
+}
+
+export function spentLine(xs: Spent[] = spent): string {
+  const og = sum(xs.filter((x) => x.og));
+  const other = sum(xs.filter((x) => !x.og));
+  const head = og.calls ? `OG 호출 ${og.calls}번 · 입력 ${og.prompt.toLocaleString("en-US")}/출력 ${og.completion.toLocaleString("en-US")} 토큰 · $${og.usd.toFixed(4)}${og.unpriced ? `(값 모름 ${og.unpriced}번)` : ""}` : "OG 호출 0";
+  return other.calls ? `${head} · 그 밖 생성 ${other.calls}번 $${other.usd.toFixed(4)}` : head;
+}
+
+// 한 kf make 실행이 한 판 — --finish·--rewrite 가 같은 폴더에 다시 돌아도 앞 판을 지우지 않고 뒤에 붙인다
+export function writeStats(dir: string, run: { command: string; model: string; code: number | string }): string {
+  const file = join(dir, "make-stats.json");
+  let runs: unknown[] = [];
+  try {
+    runs = (JSON.parse(readFileSync(file, "utf8")) as { runs?: unknown[] }).runs ?? [];
+  } catch {}
+  const stages = ledger();
+  runs.push({ at: new Date().toISOString(), ...run, stages, total: sum(stages), og: sum(stages.filter((x) => x.og)), line: spentLine(stages) });
+  const all = (runs as { stages?: Spent[] }[]).flatMap((r) => r.stages ?? []);
+  writeFileSync(file, `${JSON.stringify({ runs, total: sum(all), og: sum(all.filter((x) => x.og)), line: spentLine(all) }, null, 2)}\n`);
+  return file;
+}
 
 let prices: Record<string, { inputCostPerToken?: number; outputCostPerToken?: number; cacheReadInputTokenCost?: number }> | null = null;
 // 공개 가격표(키 없이). 못 받으면 비용은 null 로 두고 토큰만 남긴다
@@ -48,6 +108,8 @@ export async function chat(
   messages: Message[],
   o: { temperature?: number; maxTokens?: number; json?: boolean; timeoutSec?: number; effort?: "low" | "medium" | "high"; stage?: string } = {},
 ): Promise<ChatResult> {
+  const blocked = premiumBlock(model);
+  if (blocked) throw new Error(blocked);
   const t0 = Date.now();
   const body: Record<string, unknown> = { model, messages, max_tokens: o.maxTokens ?? 8000 };
   // 추론을 켠 Claude 는 temperature 를 받지 않는다
@@ -76,7 +138,7 @@ export async function chat(
       const prompt = u.prompt_tokens ?? 0;
       const completion = u.completion_tokens ?? 0;
       const usd = p?.inputCostPerToken !== undefined ? (prompt - cached) * p.inputCostPerToken + cached * (p.cacheReadInputTokenCost ?? p.inputCostPerToken) + completion * (p.outputCostPerToken ?? 0) : null;
-      spent.push({ model, stage: o.stage ?? "", ms, prompt, completion, cached, usd });
+      spent.push({ model, stage: o.stage ?? "", ms, prompt, completion, cached, usd, og: true });
       return { text: j.choices?.[0]?.message?.content ?? "", finish: j.choices?.[0]?.finish_reason, usage: j.usage, ms };
     } catch (e) {
       if ((e as any)?.fatal) throw e;

package/packages/plan/src/look.ts

@@ -149,6 +149,8 @@ function checklistText(kf: KfLike | null, sheet: string): string {
     "글이 읽힌다 — 깨진 글자(빈 네모·undefined·NaN·null) 없음, 바탕과 대비가 선다, 잘림·겹침 없음",
     "주인공이 안전 영역 가운데에 선다 — 가장자리로 밀리거나 잘리지 않았다",
     `화면 글 정책(${kf?.text?.policy ?? "모름"})을 지킨다`,
+    "뜻 없는 장식이 없다 — 움직이거나 놓인 것은 다 내용 하나를 뜻한다(떠다니는 판·빛 방울·큐브·흩뿌린 입자 없음, 바탕은 정지거나 아주 옅은 질감)",
+    "3D↔2D 가 끊기지 않는다 — 3D 샷과 2D 장면 사이는 공간 잇기 이음매(rise·land)나 투영을 맞춘 컷으로, 같은 물체·자리가 이어진다",
     ...(theme ? [`테마 ${theme.name}(${theme.metaphor})의 생김새·금지를 지킨다 — themes/${kf?.theme}/THEME.md`] : []),
   ];
   return [
@@ -183,7 +185,7 @@ export async function look(target: string, o: { ask?: string; model?: string } =
 장면: ${JSON.stringify(scenes.map((s) => ({ id: s.id, from: +s.from.toFixed(2), to: +(s.from + s.dur).toFixed(2), role: s.role, idea: s.idea })))}
 화면 글 정책: ${kf?.text?.policy ?? "모름"}${theme}
 
-장면마다 그림만 보고 문제를 짧게 적는다 — 빈 화면·화면을 못 채운 작은 요소·글자 깨짐(빈 네모·undefined·NaN)·겹침·잘림·대비 낮은 글·할 일(idea)과 다른 화면·테마 위반. 정지 그림이라 박·움직임은 판단하지 않는다. 문제가 없으면 problems 를 비운다.${o.ask ? `\n그리고 이것에 답한다: ${o.ask}` : ""}
+장면마다 그림만 보고 문제를 짧게 적는다 — 빈 화면·화면을 못 채운 작은 요소·글자 깨짐(빈 네모·undefined·NaN)·겹침·잘림·대비 낮은 글·할 일(idea)과 다른 화면·테마 위반·뜻 없는 장식(내용과 상관없이 떠다니는 판·빛 방울·큐브·입자)·3D 장면과 2D 장면 사이가 끊김(앞뒤가 다른 세계로 튐). 정지 그림이라 박·움직임은 판단하지 않는다. 문제가 없으면 problems 를 비운다.${o.ask ? `\n그리고 이것에 답한다: ${o.ask}` : ""}
 JSON 하나로만: {"scenes":[{"id":"…","problems":["…"]}],"summary":"전체 한두 문장"${o.ask ? ',"answer":"…"' : ""}}`;
   const ask = (m: string) => chat(m, [{ role: "user", content: [...parts, { type: "text", text: prompt }] }], { json: true, temperature: 0.2, maxTokens: 6000, stage: "look" });
   let used = model;

package/packages/plan/src/plan.ts

@@ -2,9 +2,10 @@ import { detect, type Detection } from "./detect.ts";
 import { layoutScenes, pickDuration } from "./layout.ts";
 import { parseAspect, parseDuration, parseStyle, parseTitle } from "./request.ts";
 import { frameFor, listTemplates, loadTemplate } from "./templates.ts";
-import { pickTheme, suggestThemes, themeFromRequest } from "./themes.ts";
+import { loadSeries, type Series, seriesFromRequest } from "./series.ts";
+import { type LookInput, pickTheme, suggestThemes, themeFromRequest } from "./themes.ts";
 import { basename } from "node:path";
-import type { Aspect, BeatsLike, GenSpec, Plan, PlannedScene, Purpose, Template } from "./types.ts";
+import type { Aspect, BeatsLike, GenSpec, Plan, PlannedScene, Purpose, ShotSpec, Template } from "./types.ts";
 
 const IMAGE = /\.(png|jpe?g|webp)$/i;
 
@@ -13,6 +14,24 @@ export function wantsVideo(request: string): boolean {
   return /영상\s*생성|생성\s*영상|AI\s*영상|영상\s*모델|video\s*(gen|model)|generated\s*video/i.test(request);
 }
 
+// 캐릭터가 실제로 움직여야 하는 컷 — 모션그래픽·3D 툰으로는 몸짓이 안 서서 영상 모델이 맡는다
+const CHARACTER = /캐릭터|마스코트|인물|사람|소녀|소년|아이돌|댄서|동물|고양이|강아지|새|로봇|주인공|character|mascot|person|girl|boy|dancer|animal|cat|dog|robot/i;
+const ACTION = /움직|춤|걷|달리|뛰|날아|날갯|헤엄|싸우|연기|몸짓|손짓|표정|돌아보|dance|walk|run|jump|fly|swim|wave|move|gesture/i;
+export function wantsMotionCut(request: string): boolean {
+  return CHARACTER.test(request) && ACTION.test(request);
+}
+
+// 「2D 로」「3D 없이」라고 하면 주인공 3D 샷을 넣지 않는다
+export function refuses3d(request: string): boolean {
+  return /3D\s*(없이|빼|말고)|2D\s*(로|만)|평면(으로|만)|no\s*3d|flat\s*only/i.test(request);
+}
+
+// 틀의 자리 이름은 장면 id 먼저, 없으면 그 역할의 첫 장면(뮤비처럼 곡 구간으로 id 가 바뀌는 틀)
+function slot<T extends { id: string; role: string }>(scenes: T[], name?: string): T | undefined {
+  if (!name) return undefined;
+  return scenes.find((s) => s.id === name) ?? scenes.find((s) => s.role === name);
+}
+
 export interface PlanInput {
   request: string;
   purpose?: Purpose; // 사람이 못 박으면 판별을 건너뛴다
@@ -23,27 +42,48 @@ export interface PlanInput {
   aspect?: Aspect;
   style?: string;
   title?: string;
-  theme?: string; // 테마 id 나 "auto"
+  theme?: string; // 테마 id · "auto" · "none"(프리셋만)
+  series?: string; // 시리즈 id · "none". 안 주면 요청 글이 짚은 시리즈(series/<id>.json 의 match)
+  look?: LookInput; // 테마 고르기에 사람이 준 분위기 한 마디·레퍼런스 생김새
 }
 
 export function makePlan(input: PlanInput): Plan {
   const templates = listTemplates();
+  // 시리즈가 먼저 — 짚었으면 용도·테마·길이·자막·끝 카드를 그 묶음이 정한다(사람이 따로 준 값은 그대로 이긴다)
+  const series: Series | null = input.series === "none" ? null : input.series ? loadSeries(input.series) : seriesFromRequest(input.request);
   const det: Detection = input.purpose
     ? { purpose: input.purpose, confidence: 1, ranked: [], ambiguous: false }
-    : detect({ request: input.request, assets: input.assets, music: input.music }, templates);
-  const tpl = loadTemplate(det.purpose);
+    : series
+      ? { purpose: series.purpose, confidence: 1, ranked: [], ambiguous: false }
+      : detect({ request: input.request, assets: input.assets, music: input.music }, templates);
+  const base = loadTemplate(det.purpose);
+  const tpl: Template = series?.duration ? { ...base, duration: { ...base.duration, ...series.duration } } : base;
   const aspect = input.aspect ?? parseAspect(input.request);
   const frame = frameFor(tpl, aspect && (aspect === tpl.aspect || tpl.variants?.[aspect]) ? aspect : undefined);
   const { duration, notes } = pickDuration(tpl, { requested: input.duration ?? parseDuration(input.request), beats: input.beats });
   const laid = layoutScenes(tpl, duration, input.beats);
   // auto: 요청이 테마를 말로 짚었으면 그 테마, 아니면 내용에 맞는 approved 후보 셋 중 첫째
-  const named = input.theme === "auto" ? themeFromRequest(input.request, tpl.id) : null;
-  const themeCandidates = input.theme === "auto" ? [...(named ? [named] : []), ...suggestThemes(input.request, tpl.id, frame.aspect).filter((c) => c.id !== named?.id)].slice(0, 3) : undefined;
-  const theme = input.theme === "auto" ? (themeCandidates?.[0]?.id ?? null) : input.theme ? pickTheme(input.theme).id : null;
+  // none 은 프리셋만 — 시리즈 테마도 쓰지 않는다
+  const themeIn = input.theme === "none" ? undefined : (input.theme === undefined || input.theme === "auto") && series?.theme ? series.theme : input.theme;
+  const named = themeIn === "auto" ? themeFromRequest(input.request, tpl.id) : null;
+  const themeCandidates = themeIn === "auto" ? [...(named ? [named] : []), ...suggestThemes(input.request, tpl.id, frame.aspect, 3, input.look).filter((c) => c.id !== named?.id)].slice(0, 3) : undefined;
+  const theme = themeIn === "auto" ? (themeCandidates?.[0]?.id ?? null) : themeIn ? pickTheme(themeIn).id : null;
   // 테마를 고르면 그 테마의 style 이 프리셋을 대신한다(kf new 가 themeStyle 로 쓴다)
-  const style = theme ?? input.style ?? parseStyle(input.request) ?? tpl.style;
-  const title = input.title ?? parseTitle(input.request) ?? "";
-  const gen = genSpecs(tpl, laid.scenes, { subject: title || input.request, style, width: frame.width, height: frame.height, video: wantsVideo(input.request), refs: (input.assets ?? []).filter((a) => IMAGE.test(a)).map((a) => `assets/in/${basename(a)}`) });
+  const style = theme ?? input.style ?? series?.style ?? parseStyle(input.request) ?? tpl.style;
+  const title = input.title ?? series?.end?.title ?? parseTitle(input.request) ?? "";
+  const gen = genSpecs(tpl, laid.scenes, {
+    subject: title || input.request,
+    style,
+    width: frame.width,
+    height: frame.height,
+    video: wantsVideo(input.request),
+    act: tpl.id === "mv" || wantsMotionCut(input.request),
+    refs: (input.assets ?? []).filter((a) => IMAGE.test(a)).map((a) => `assets/in/${basename(a)}`),
+  });
+  const hero = refuses3d(input.request) ? undefined : slot(laid.scenes, tpl.assets.shot3d);
+  const shots: ShotSpec[] = hero
+    ? [{ id: `${hero.id}-3d`, scene: hero.id, tool: "blender", idea: `${title || input.request} — 「${hero.idea}」을 주인공 3D 장면으로(툰 셰이딩·라인아트, 카메라 열쇠는 첫박·드롭에)`, file: `shots/${hero.id}-3d.py` }]
+    : [];
 
   const scenes: PlannedScene[] = laid.scenes.map((s) => ({
     id: s.id,
@@ -60,7 +100,7 @@ export function makePlan(input: PlanInput): Plan {
     purpose: det.purpose,
     confidence: det.confidence,
     alternatives: det.ranked.slice(1, 3).map((r) => ({ purpose: r.purpose, p: r.p })),
-    reasons: [...(top?.reasons ?? (input.purpose ? ["사람이 정함"] : [])), ...notes, ...laid.notes],
+    reasons: [...(series ? [`시리즈 ${series.id}(${series.label})`] : []), ...(top?.reasons ?? (input.purpose ? ["사람이 정함"] : [])), ...notes, ...laid.notes],
     title,
     aspect: frame.aspect,
     width: frame.width,
@@ -69,12 +109,15 @@ export function makePlan(input: PlanInput): Plan {
     duration: laid.duration,
     style,
     music: input.music ?? null,
-    captions: tpl.captions,
+    captions: series?.captions ?? tpl.captions,
     deliverables: tpl.deliverables,
     scenes,
     gen,
+    shots,
     theme,
     ...(themeCandidates ? { themeCandidates } : {}),
+    ...(input.look && (input.look.mood || input.look.ref) ? { themeLook: input.look } : {}),
+    ...(series ? { series: series.id, ...(series.music?.mood ? { mood: series.music.mood } : {}) } : {}),
   };
   if (det.ambiguous) {
     plan.questions = [
@@ -95,7 +138,7 @@ export function makePlan(input: PlanInput): Plan {
 function genSpecs(
   tpl: Template,
   scenes: { id: string; role: string; idea: string }[],
-  o: { subject: string; style: string; width: number; height: number; video: boolean; refs: string[] },
+  o: { subject: string; style: string; width: number; height: number; video: boolean; act: boolean; refs: string[] },
 ): GenSpec[] {
   const gen: GenSpec[] = [];
   for (const spec of [...tpl.assets.gen, ...(o.video ? (tpl.assets.genVideo ?? []) : [])]) {
@@ -121,5 +164,18 @@ function genSpecs(
     const refs = gen.some((g) => g.id === "character") ? { refs: ["assets/gen/character.png"] } : {};
     gen.push({ id, kind, scene: scene.id, prompt: `${o.subject} ${tpl.label} 영상 「${scene.idea}」 장면의 바탕 그림. ${o.style} 결, 글자·로고 없음.`, size: `${o.width}x${o.height}`, ...refs });
   }
+  const act = o.act ? slot(scenes, tpl.assets.act) : undefined;
+  if (act) {
+    // 주인공 그림이 있으면 그 얼굴로 시작한다(첫 프레임) — 그림은 영상보다 먼저 만든다(resolvePlan 순서)
+    const face = gen.find((g) => g.id === "character") ?? gen.find((g) => g.kind === "img" && g.scene === act.id);
+    gen.push({
+      id: `${act.id}-act`,
+      kind: "vid",
+      scene: act.id,
+      dur: 5,
+      prompt: `${o.subject} — 「${act.idea}」 장면에서 캐릭터가 실제로 움직이는 컷(몸짓·걸음·표정). 카메라는 거의 고정, ${o.style} 결, 글자 없음.`,
+      ...(face ? { first: `assets/gen/${face.id}.png` } : {}),
+    });
+  }
   return gen;
 }

package/packages/plan/src/series.ts

@@ -0,0 +1,76 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PURPOSES, type Purpose } from "./types.ts";
+
+// 시리즈 묶음 — 같은 시리즈면 생김새·목소리·곡·자막·길이·끝 카드·생성 답이 매번 같다. 요청이 시리즈를 짚으면 묻지 않고 이 묶음을 쓴다
+export interface Series {
+  id: string;
+  label: string;
+  summary?: string;
+  match: string[]; // 요청 글에 이 말이 있으면 이 시리즈(대소문자·띄어쓰기 무시)
+  purpose: Purpose;
+  theme?: string;
+  style?: string; // 테마 없이 프리셋으로 갈 때
+  voice?: string; // "<엔진>:<목소리>" · "none"
+  music?: { mood?: string; file?: string }; // file 은 레포 기준 곡 — 있으면 늘 그 곡, 없으면 분위기로 곡 모음에서(같은 분위기면 같은 곡)
+  captions?: "on" | "off" | "none";
+  duration?: { min?: number; max?: number; default?: number };
+  end?: { title?: string; line?: string }; // 끝 카드
+  answers?: Record<string, string>; // 생성 질문에 미리 박은 답(image·video·blender·voice·music) — 묻지 않는다
+}
+
+export const seriesDir = (): string => process.env.KF_SERIES_DIR || fileURLToPath(new URL("../../../series/", import.meta.url));
+
+export function checkSeries(s: Partial<Series>): string[] {
+  const bad: string[] = [];
+  if (!s.id || !/^[a-z0-9][a-z0-9-]*$/.test(s.id)) bad.push("id 는 소문자·숫자·- 로");
+  if (!s.label) bad.push("label 이 없다");
+  if (!s.match?.length) bad.push("match 가 비었다 — 요청에서 짚을 말을 하나 이상");
+  if (!s.purpose || !PURPOSES.includes(s.purpose)) bad.push(`purpose 는 ${PURPOSES.join("·")} 중 하나`);
+  if (s.captions && !["on", "off", "none"].includes(s.captions)) bad.push("captions 는 on·off·none");
+  return bad;
+}
+
+export function listSeries(): Series[] {
+  const dir = seriesDir();
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".json"))
+    .map((f) => JSON.parse(readFileSync(join(dir, f), "utf8")) as Series)
+    .filter((s) => !checkSeries(s).length)
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function loadSeries(id: string): Series {
+  const file = join(seriesDir(), `${id}.json`);
+  if (!existsSync(file)) throw new Error(`시리즈 없음: ${id} (있는 것: ${listSeries().map((s) => s.id).join(" ") || "없음"})`);
+  const s = JSON.parse(readFileSync(file, "utf8")) as Series;
+  const bad = checkSeries(s);
+  if (bad.length) throw new Error(`시리즈 ${id} 가 깨졌다 — ${bad.join(" · ")}`);
+  return s;
+}
+
+const squash = (x: string) => x.toLowerCase().replace(/\s+/g, "");
+
+// 가장 길게 맞은 말의 시리즈 — 「OG 쇼츠」와 「OG 쇼츠 영어판」이 같이 있으면 긴 쪽
+export function seriesFromRequest(request: string): Series | null {
+  const r = squash(request);
+  let best: { s: Series; n: number } | null = null;
+  for (const s of listSeries()) {
+    for (const m of s.match) {
+      const k = squash(m);
+      if (k && r.includes(k) && (!best || k.length > best.n)) best = { s, n: k.length };
+    }
+  }
+  return best?.s ?? null;
+}
+
+export function writeSeries(s: Series): string {
+  const bad = checkSeries(s);
+  if (bad.length) throw new Error(bad.join(" · "));
+  mkdirSync(seriesDir(), { recursive: true });
+  const file = join(seriesDir(), `${s.id}.json`);
+  writeFileSync(file, `${JSON.stringify(s, null, 2)}\n`);
+  return file;
+}

package/packages/plan/src/themes.ts

@@ -1,4 +1,5 @@
 import { listThemes, loadTheme, type Theme } from "@kasaframe/themes";
+import { hasLook, lookDistance, lookScore, type RefLook, textWords, wantsOf } from "@kasaframe/themes/look";
 import { parseTitle } from "./request.ts";
 import type { Aspect, Purpose } from "./types.ts";
 
@@ -7,25 +8,80 @@ export interface ThemePick {
   why: string;
 }
 
-const words = (s: string) => s.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((w) => w.length >= 2);
+/** 사람이 테마 고르기에 덧붙인 것 — 분위기 한 마디·레퍼런스 그림의 생김새 */
+export interface LookInput {
+  mood?: string;
+  ref?: RefLook | null;
+}
+
+// 어느 테마 글에나 나오는 낱말 — 맞음 점수를 부풀리기만 한다
+const STOP = new Set(["영상", "느낌", "분위기", "스타일", "테마", "쇼츠", "릴스", "만들어", "만들어줘", "으로", "처럼", "같은", "video"]);
+/** 요청 글의 내용 낱말 — 조사를 뗀 낱말(textWords — 「압축이」 = 압축) 가운데 두 글자 넘는 것, 어디에나 나오는 낱말·숫자로 시작하는 것은 뺀다 */
+export const requestWords = (s: string): string[] => textWords(s).filter((w) => w.length >= 2 && !STOP.has(w) && !/^\d/.test(w));
+
+// 같은 점수의 차례 — 요청 글로 섞는다. 승인 날짜·id 차례면 내용 낱말이 없는 요청마다 같은 넷(알파벳 앞)이 나와 그것대로 양산형이 된다.
+// 같은 요청이면 늘 같은 차례(FNV-1a)
+function tieKey(text: string, id: string): number {
+  let h = 0x811c9dc5;
+  for (const ch of `${text}\0${id}`) h = Math.imul(h ^ ch.codePointAt(0)!, 0x01000193) >>> 0;
+  return h;
+}
 
-// 자동 추천은 approved 테마만(SPEC 9). 요청 낱말이 테마 이름·비유·THEME.md 에 얼마나 나오나로 줄 세우고, 같으면 최근에 승인된 쪽
-export function suggestThemes(request: string, purpose: Purpose, aspect?: Aspect, n = 3): ThemePick[] {
-  const pool = listThemes({ status: "approved", purpose, ...(aspect ? { aspect } : {}) });
-  const ask = new Set(words(request));
+// 자동 추천은 approved 만(SPEC 9 — 세계가 approved 면 검사를 넘은 변주도). 내용 맞음(요청 낱말이 세계 이름·비유·THEME.md·태그에 나오나)과
+// 생김새 맞음(분위기 낱말·레퍼런스 → 밝기·색상·채도·질감·글꼴)을 더해 줄 세운다. 생김새를 바란 말이 없으면 세계 기본 판끼리만 견준다.
+// 고른 n 개는 서로 겹치지 않게 — 한 세계는 둘까지(생김새를 바라지 않았으면 하나), 생김새가 아주 가까운 판은 뒤로.
+// use: 부르는 쪽의 쓰임 낱말(용도보다 잘게 나눈 쓰임 — 쇼츠 스킬의 「업데이트 소식」 = 소식·발표·출시). 테마 tags.use 와 맞으면 다 합쳐도
+// 요청 낱말 하나보다 가볍게 더한다 — 요청이 남긴 동점끼리 줄을 세운다
+export function suggestThemes(request: string, purpose: Purpose, aspect?: Aspect, n = 3, look: LookInput = {}, use: string[] = []): ThemePick[] {
+  const text = `${request} ${look.mood ?? ""}`;
+  const { want, hits: moodHits } = wantsOf(text);
+  const lookOn = hasLook(want) || !!look.ref;
+  const pool = listThemes({ status: "approved", purpose, ...(aspect ? { aspect } : {}), variants: lookOn });
+  const ask = new Set(requestWords(text));
   const scored = pool.map((t) => {
-    const hay = `${t.name} ${t.metaphor} ${t.guide}`.toLowerCase();
+    const hay = `${t.name} ${t.metaphor} ${t.guide} ${(t.tags?.use ?? []).join(" ")} ${(t.tags?.mood ?? []).join(" ")} ${t.variant?.desc ?? ""}`.toLowerCase();
     const hit = [...ask].filter((w) => hay.includes(w));
-    return { t, score: hit.length, hit };
+    const l = lookOn ? lookScore(t, want, look.ref) : { score: 0, why: [] };
+    const used = use.filter((w) => (t.tags?.use ?? []).some((u) => u.includes(w)));
+    const fit = use.length ? (0.9 * used.length) / use.length : 0;
+    // 같은 점수면 세계 기본 판이 앞 — 바란 생김새가 없을 때 변주를 굳이 고르지 않게
+    return { t, score: hit.length + fit + l.score + (t.variant ? 0 : 0.3), hit, used, why: l.why, tie: tieKey(text, t.id) };
+  });
+  scored.sort((a, b) => b.score - a.score || a.tie - b.tie || a.t.id.localeCompare(b.t.id));
+  const picked: typeof scored = [];
+  const perWorld = (w: string) => picked.filter((p) => p.t.world === w).length;
+  for (const strict of [true, false]) {
+    for (const c of scored) {
+      if (picked.length >= n) break;
+      if (picked.includes(c)) continue;
+      if (strict && (perWorld(c.t.world) >= (lookOn ? 2 : 1) || picked.some((p) => lookDistance(p.t, c.t) < 0.06))) continue;
+      picked.push(c);
+    }
+  }
+  return picked.map(({ t, hit, used, why }) => {
+    const reasons = [
+      ...(hit.length ? [`요청의 ${hit.slice(0, 3).map((w) => `「${w}」`).join("·")} 이(가) 테마와 맞는다`] : []),
+      ...(why.length ? [`${look.ref ? "레퍼런스·" : ""}${moodHits.length ? `분위기 ${moodHits.slice(0, 3).map((w) => `「${w}」`).join("·")}` : "분위기"}에 맞는 ${why.slice(0, 3).join("·")}`] : []),
+      ...(used.length ? [`쓰임 ${used.slice(0, 3).join("·")}`] : []),
+    ];
+    return { id: t.id, why: `${reasons.length ? reasons.join(", ") : `${purpose} 에 쓰는 승인 테마`} — ${t.variant ? `${t.variant.desc}(${t.metaphor})` : t.metaphor}` };
   });
-  scored.sort((a, b) => b.score - a.score || (b.t.approvedAt ?? "").localeCompare(a.t.approvedAt ?? ""));
-  return scored.slice(0, n).map(({ t, hit }) => ({ id: t.id, why: hit.length ? `요청의 ${hit.slice(0, 3).map((w) => `「${w}」`).join("·")} 이(가) 테마 비유와 맞는다 — ${t.metaphor}` : `${purpose} 에 쓰는 승인 테마 — ${t.metaphor}` }));
 }
 
 // 「리소 느낌으로」처럼 사람이 말로 테마를 짚었는지 — 테마 이름 낱말(두 글자 넘게)·id 조각(세 글자 넘게)이 요청에 나오면 그 테마.
 // 사람이 짚은 것이라 review 까지 받는다(draft 는 빼고)
 export function themeFromRequest(request: string, purpose?: Purpose): ThemePick | null {
   const t = request.toLowerCase();
+  // 변주를 이름으로 짚었으면(「og-measure/night-amber 로」) 그 판
+  const full = /([a-z0-9-]+)\/([a-z0-9-]+)/.exec(t);
+  if (full) {
+    try {
+      const v = loadTheme(full[0]);
+      if (v.status !== "draft") return { id: v.id, why: `요청이 변주 ${v.id} 를 짚었다 — ${v.variant?.desc ?? v.metaphor}` };
+    } catch {
+      // 테마 이름이 아닌 경로·주소 조각이면 아래 낱말 짚기로
+    }
+  }
   let best: { th: Theme; score: number; hit: string[] } | null = null;
   for (const th of listThemes({ status: ["approved", "review"] })) {
     const keys = [...th.name.split(/\s+/).filter((w) => w.length >= 2), ...th.id.split("-").filter((w) => w.length >= 3)].map((w) => w.toLowerCase());

package/packages/plan/src/types.ts

@@ -1,3 +1,6 @@
+import type { Question } from "@kasaframe/gen";
+import type { Bundle } from "@kasaframe/motion/menu";
+import type { RefLook } from "@kasaframe/themes/look";
 export type Aspect = "16:9" | "9:16" | "1:1";
 export type Purpose = "promo" | "shorts" | "explainer" | "launch" | "demo" | "ad" | "square" | "mv";
 export const PURPOSES: Purpose[] = ["promo", "shorts", "explainer", "launch", "demo", "ad", "square", "mv"];
@@ -26,6 +29,12 @@ export interface Template {
   variants?: Partial<Record<Aspect, { width: number; height: number; safeArea?: SafeArea }>>;
   duration: { min: number; max: number; default: number; allowed?: number[] };
   music: "required" | "optional" | "none";
+  // 곡 모음 태그·생성 곡 프롬프트를 고르는 분위기(@kasaframe/gen MOOD_TAGS·MOOD_PROMPT) — 같은 틀이면 같은 결의 곡
+  mood?: string;
+  // 내레이션 먼저 — 장면별 문장을 읽혀 길이를 재고 장면을 목소리에 맞춘다. voices 는 엔진마다 박은 목소리(같은 틀이면 같은 목소리)
+  narration?: Narration;
+  // 섞기 — 내레이션 아래 곡 musicDb, 말할 때 덕킹, 끝 페이드, 정규화 LUFS
+  audio?: AudioMix;
   // off: srt·vtt 만 · on: 화면에도 얹는다 · none: 없음 (옛 이름 track·burned 도 읽는다 — @kasaframe/motion/captions 의 captionMode)
   captions: "off" | "on" | "none";
   loop: boolean;
@@ -35,12 +44,17 @@ export interface Template {
   // 뮤비: kinetic 이면 부른 낱말이 그 시각에 화면에 뜬다(lyrics.json 낱말 시각), track 이면 자막 트랙만
   lyrics?: { mode: "kinetic" | "track" | "none"; align?: string; lipsync?: string };
   motion: Record<string, unknown>;
+  // 장면마다 거는 연출 수 묶음(@kasaframe/motion/menu) — kf new 가 요청 글을 씨앗으로 장면마다 고른다. roles 는 역할별(hook·drop·end …)
+  moves?: Bundle;
+  // kf render 기본값 — kf new 가 kf.json render 로 옮긴다. motionBlur 하위 프레임 수(0 이면 끔)·shutter 셔터 각도
+  render?: { motionBlur?: number; shutter?: number };
   scenes: TemplateScene[];
   // sections: 곡 구간(beats.json sections)마다 장면 하나 — scenes 는 곡이 없을 때 쓰는 기본, sectionIdeas 는 구간 종류별 할 일
   layout?: "fixed" | "sections";
   sectionIdeas?: Record<string, string>;
-  // gen 은 늘 만드는 그림, genVideo 는 요청에 「영상 생성」을 분명히 적었을 때만(이음매 기본은 모션그래픽 전환)
-  assets: { need: string[]; want: string[]; gen: string[]; genVideo?: string[] };
+  // gen 은 늘 만드는 그림, genVideo 는 요청에 「영상 생성」을 분명히 적었을 때만(이음매 기본은 모션그래픽 전환).
+  // shot3d 는 주인공 3D 장면(Blender) 자리, act 는 캐릭터가 실제로 움직여야 할 때 영상 모델 컷 자리 — 장면 id, 없으면 역할로 찾는다
+  assets: { need: string[]; want: string[]; gen: string[]; genVideo?: string[]; shot3d?: string; act?: string };
   deliverables: string[];
   detect: { words: string[]; hints: string[]; aspect: Aspect; assetKinds?: string[] };
 }
@@ -81,6 +95,35 @@ export interface GenSpec {
   provider?: string;
 }
 
+// 주인공 3D 장면 — blender 면 shots/<id>.py 를 kf blender 로 굽고, three 면 그 장면이 stage3d 로 3D 를 짓는다(Blender 가 없을 때의 대신)
+export interface ShotSpec {
+  id: string;
+  scene: string;
+  tool: "blender" | "three";
+  idea: string;
+  file: string; // 프로젝트 기준 샷 스크립트 — blender 일 때만 쓴다
+}
+
+export interface Narration {
+  on: boolean;
+  lang: string;
+  style: string;
+  // 이 틀의 목소리 하나 — 같은 틀이면 어느 기계에서든 이 목소리. 그 엔진이 없으면 다른 엔진으로 넘어가지 않고 묻는다
+  voice: string;
+  // 사람이 다른 엔진을 고를 때 그 엔진의 목소리
+  voices: Record<string, string>;
+  lead: number; // 장면 시작에서 말이 들어오기까지(초)
+  tail: number; // 말이 끝나고 장면이 끝나기까지(초)
+}
+
+export interface AudioMix {
+  musicDb: number;
+  duck: boolean;
+  lufs: number;
+  truePeak: number;
+  fadeOut: number;
+}
+
 export interface Plan {
   request: string;
   purpose: Purpose;
@@ -95,6 +138,8 @@ export interface Plan {
   duration: number;
   style: string;
   music: string | null;
+  // 목소리 "<엔진>:<목소리>" · "none"(자막만). 정하기 전에는 없다
+  voice?: string;
   captions: Template["captions"];
   deliverables: string[];
   scenes: PlannedScene[];
@@ -102,5 +147,14 @@ export interface Plan {
   // 고른 테마(themes/<id>). auto 면 approved 후보 셋을 themeCandidates 에 남기고 첫째를 쓴다
   theme?: string | null;
   themeCandidates?: { id: string; why: string }[];
+  /** 테마 고르기에 사람이 준 분위기 한 마디·레퍼런스 생김새 — 테마 질문의 후보 넷을 이걸로 다시 고른다 */
+  themeLook?: { mood?: string; ref?: RefLook | null };
   questions?: { id: string; ask: string; choices: string[] }[];
+  shots?: ShotSpec[];
+  // 시리즈 묶음(series/<id>.json)으로 세운 계획이면 그 id, 곡 분위기는 시리즈가 틀 mood 를 덮는다
+  series?: string;
+  mood?: string;
+  // 만들기 전에 사람이 고를 것(@kasaframe/gen Question) — 아직 안 고른 것만. 고른 답은 answers 에 { 질문 id: 값 }
+  asks?: Question[];
+  answers?: Record<string, string>;
 }

package/packages/themes/kit/THEME-MAKE.md

@@ -25,6 +25,7 @@
 - 비유 한 줄: 「무엇이 무엇처럼 되며 화면이 찍힌다/드러난다」. 내용(정보가 화면에 오르는 방식)에서 나온 개념이어야 한다 — 장식 이름이 아니라 동사가 있는 문장.
 - `style.json`: 프리셋과 같은 KfStyle 꼴 통째, `name` = `{{id}}`. 잉크 2–3색 + 그 어두운 단(`colors`), 바탕 `bg`, 글 `ink`, 강조 `accent`. 글꼴 셋(`sans`·`display`·`mono`)은 **한글이 서는 글꼴로 끝나게**(Pretendard 를 마지막에), `faces` 는 **한 파일 주소**(jsdelivr `gh/google/fonts@main/ofl/<이름>/<파일>.ttf` 나 `npm/pretendard@1.3.9/.../PretendardVariable.woff2`). 구글 폰트 CSS(unicode-range 조각)는 글이 투명하게 찍히니 쓰지 않는다. `theme` 칸에 `inks`·`texture`·`movement` 를 글로.
 - `theme.json`: `name`·`metaphor`·`purposes`·`aspect`. status 는 draft 그대로.
+- `theme.json` 의 `vary`·`tags`(SPEC 9 「변주」): 이 세계가 approved 되면 `kf theme vary {{id}}` 가 겉모습만 바꾼 판 15개를 뽑는다. 비유를 깨지 않는 축과 범위만 적는다 — 밝기(`scheme`), 강조 색상 범위(`hue`, OKLCH 도), 글꼴 짝(`fonts` — `packages/themes/kit/fonts.json` 의 id·`tag:<태그>`·`base`), 질감(`texture`), 선 굵기(`stroke` — 슬롯 `trace` 가 `slotkit.traceCanvas` 를 쓰면 실린다), 모서리(`radius`), 빠르기(`tempo`), 밀도(`density` — 효과가 `ctx.style.look?.density` 를 읽을 때만). 금지에 적은 것과 부딪히는 축은 빼고(「밝은 바탕 금지」면 `scheme: ["dark"]`), 재료처럼 색상이 뜻인 색 열쇠는 `fixedHue`, 늘 같은 색은 `keep`. `tags` 는 `{ mood, light, use, dims }`. 효과·슬롯 색은 `var(--kf-*)`·`ctx.style.colors` 로 읽어야 변주 색이 실린다 — 색을 코드에 박지 않는다.
 - 글자 대비는 찍힌 픽셀로 3:1 이상 — 옅은 잉크로 작은 글을 쓰지 않는다.
 
 ## 4. 효과 — `effects.ts` (5–10개)