kasaframe 0.1.1 → 0.1.3

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 { loadSeries, type Series, seriesFromRequest } from "./series.ts";
 import { 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,47 @@ 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)
 }
 
 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).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 +99,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 +108,14 @@ 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 } : {}),
+    ...(series ? { series: series.id, ...(series.music?.mood ? { mood: series.music.mood } : {}) } : {}),
   };
   if (det.ambiguous) {
     plan.questions = [
@@ -95,7 +136,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 +162,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/types.ts

@@ -1,3 +1,5 @@
+import type { Question } from "@kasaframe/gen";
+import type { Bundle } from "@kasaframe/motion/menu";
 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 +28,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 +43,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 +94,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 +137,8 @@ export interface Plan {
   duration: number;
   style: string;
   music: string | null;
+  // 목소리 "<엔진>:<목소리>" · "none"(자막만). 정하기 전에는 없다
+  voice?: string;
   captions: Template["captions"];
   deliverables: string[];
   scenes: PlannedScene[];
@@ -103,4 +147,11 @@ export interface Plan {
   theme?: string | null;
   themeCandidates?: { id: string; why: string }[];
   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/package.json

@@ -7,10 +7,13 @@
     ".": "./src/index.ts",
     "./fx": "./src/fx.ts",
     "./factory": "./src/factory.ts",
-    "./stage3d": "./src/stage3d.ts"
+    "./stage3d": "./src/stage3d.ts",
+    "./slots": "./src/slots.ts",
+    "./slotkit": "./src/slotkit.ts"
   },
   "dependencies": {
     "@kasaframe/core": "0.0.0",
-    "three": "^0.186.1"
+    "three": "^0.186.1",
+    "@kasaframe/motion": "^0.0.0"
   }
 }

package/packages/themes/src/index.ts

@@ -80,6 +80,15 @@ export function listThemes(filter: ThemeFilter = {}): Theme[] {
   return out;
 }
 
+/** 3D 무대(rig 효과)를 쓰는 테마인가 — 묻기 보기·견본 시트의 2D/3D 표시 */
+export const themeDims = (t: Pick<ThemeManifest, "effects">): "2D" | "3D" => (t.effects.some((e) => e.kind === "rig") ? "3D" : "2D");
+
+/** kf theme sheet 가 찍는 견본 — 같은 문장 한 장면을 테마마다 <id>.png, 한 장에 모은 격자 sheet.png */
+export const sheetDir = join(themesDir, "_sheet");
+
+/** 묻기 보기에 붙일 견본 — 견본 시트의 그 테마 칸, 아직 안 찍었으면 테마 대표 장면 */
+export const themeSample = (t: Theme): string | null => (existsSync(join(sheetDir, `${t.id}.png`)) ? join(sheetDir, `${t.id}.png`) : t.files.still);
+
 export function themeCards(filter: ThemeFilter = {}): ThemeCard[] {
   return listThemes(filter).map((t) => ({
     id: t.id,

package/packages/themes/src/slotkit.ts

@@ -0,0 +1,79 @@
+import { clamp } from "@kasaframe/core";
+
+// 테마 slots.ts 들이 같이 쓰는 작은 도구. 슬롯은 build 때(장면이 숨어 있어 크기 0) 불리므로 크기를 재지 않는 길만 둔다 —
+// 판은 % 로, 선은 점 좌표를 감싸는 캔버스로.
+
+export function layer(parent: HTMLElement, css: string, first = false): HTMLDivElement {
+  const d = parent.ownerDocument.createElement("div");
+  d.style.cssText = `position:absolute;pointer-events:none;${css}`;
+  if (first) parent.prepend(d);
+  else parent.append(d);
+  return d;
+}
+
+/** 글자마다 span — 배치를 바꾸지 않게 inline 그대로. 빈칸은 글자로 남긴다 */
+export function letters(el: HTMLElement, text: string): HTMLSpanElement[] {
+  el.textContent = "";
+  return Array.from(text).map((ch) => {
+    const s = el.ownerDocument.createElement("span");
+    s.textContent = ch;
+    el.append(s);
+    return s;
+  });
+}
+
+/** at 부터 dur 동안 앞에서부터 몇 글자가 찍혔나 — at+dur 부터는 전부 */
+export const shownCount = (n: number, t: number, at: number, dur: number): number =>
+  t >= at + dur ? n : t < at ? 0 : Math.min(n, Math.floor(clamp((t - at) / Math.max(1e-3, dur)) * n) + 1);
+
+export type Pt = readonly [number, number];
+
+/** 꺾은선 길이 비율 p 까지의 점들 — 마지막 점은 선분 안에서 끊는다 */
+export function partial(points: readonly Pt[], p: number): [number, number][] {
+  if (points.length < 2) return points.map((q) => [q[0], q[1]]);
+  const seg = points.slice(1).map((q, i) => Math.hypot(q[0] - points[i][0], q[1] - points[i][1]));
+  const total = seg.reduce((a, b) => a + b, 0) || 1;
+  let left = clamp(p) * total;
+  const out: [number, number][] = [[points[0][0], points[0][1]]];
+  for (let i = 0; i < seg.length; i++) {
+    if (left >= seg[i]) {
+      out.push([points[i + 1][0], points[i + 1][1]]);
+      left -= seg[i];
+      continue;
+    }
+    const k = seg[i] ? left / seg[i] : 0;
+    out.push([points[i][0] + (points[i + 1][0] - points[i][0]) * k, points[i][1] + (points[i + 1][1] - points[i][1]) * k]);
+    break;
+  }
+  return out;
+}
+
+/** 점들을 감싸는 캔버스(여백 pad) — 그리기는 층 좌표 그대로 */
+export function traceCanvas(el: HTMLElement, points: readonly Pt[], pad = 40): { g: CanvasRenderingContext2D; clear(): void } {
+  const xs = points.map((q) => q[0]);
+  const ys = points.map((q) => q[1]);
+  const x = Math.floor(Math.min(...xs) - pad);
+  const y = Math.floor(Math.min(...ys) - pad);
+  const w = Math.ceil(Math.max(...xs) + pad) - x;
+  const h = Math.ceil(Math.max(...ys) + pad) - y;
+  const c = el.ownerDocument.createElement("canvas");
+  c.width = Math.max(1, w);
+  c.height = Math.max(1, h);
+  c.style.cssText = `position:absolute;left:${x}px;top:${y}px;width:${w}px;height:${h}px;pointer-events:none`;
+  el.append(c);
+  const g = c.getContext("2d")!;
+  g.translate(-x, -y);
+  return { g, clear: () => g.clearRect(x, y, w, h) };
+}
+
+export function strokePath(g: CanvasRenderingContext2D, pts: readonly Pt[]): void {
+  if (pts.length < 2) return;
+  g.beginPath();
+  g.moveTo(pts[0][0], pts[0][1]);
+  for (const q of pts.slice(1)) g.lineTo(q[0], q[1]);
+  g.stroke();
+}
+
+/** CSS 변수 색 — 슬롯은 테마 토큰만 쓴다 */
+export const cssVar = (el: HTMLElement, name: string, fallback: string): string =>
+  getComputedStyle(el).getPropertyValue(`--kf-${name}`).trim() || fallback;

package/packages/themes/src/slots.ts

@@ -0,0 +1,46 @@
+/// <reference types="vite/client" />
+// 페이지(Vite) 쪽. 장면 문법 패턴은 테마 이름을 모른다 — 일반 자리 여섯을 부르고, 테마가 themes/<id>/slots.ts 에서 자기 효과로 채운다.
+// effects.ts 와 따로 두는 까닭: effects.ts 내보내기는 theme.json 효과 목록과 같아야 한다(테마 시험).
+import type { SceneCtx, Style } from "@kasaframe/core";
+import type { DropBurstState } from "@kasaframe/motion";
+
+export type Paint = (t: number) => void;
+
+/**
+ * 모든 슬롯은 같은 t 면 같은 화면이고, 난수는 seed 로만. 비운 슬롯은 패턴이 제 기본으로 그린다.
+ * 화면 전체를 덮는 3D(three)는 surface 에서만 — 크롬이 WebGL 문맥을 몇 개만 살려 두므로 나머지 슬롯은 DOM·캔버스 2D 로.
+ */
+export interface ThemeSlots {
+  /** 화면 전체 바탕 질감. el = 장면 맨 뒤 inset:0 층. 장면마다 한 번 짓는다. 글을 두지 않는다 */
+  surface?(el: HTMLElement, o: { ctx: SceneCtx; seed: string }): Paint;
+  /**
+   * 카드·상자 판. el = 패턴이 자리·크기를 잡은 상자(position:absolute). 판은 el 안 맨 앞 자식으로 깔고 내용은 패턴이 그 위에 둔다.
+   * at 에 선다(그 전엔 안 보인다). 상자 크기·자리는 바꾸지 않는다 — 배치는 패턴 몫. tone 은 accent 면 강조 판
+   */
+  panel?(el: HTMLElement, o: { ctx: SceneCtx; at: number; seed: string; tone?: "base" | "accent" }): Paint;
+  /**
+   * 앉는 순간 한 번 — 숫자·이름·칸이 at 에 앉을 때. el 둘레에 곁 그림(빛·그림자·도장)을 지어도 되고, 돌려준 Style 은 패턴이 el 에 combine 한다.
+   * 섬광·흔들림은 motion 부품(dropBurst·shake)을 거쳐 __kf.events 에 남게. at 에서 0.6초 안에 끝나 선다
+   */
+  land?(el: HTMLElement, o: { ctx: SceneCtx; at: number; seed: string }): (t: number) => Style;
+  /**
+   * 글 찍기 — el(패턴이 글꼴 크기·자리를 잡은 글 상자)에 text 를 at 부터 찍는다. at + dur 부터는 el.textContent 가 text 그대로.
+   * 글꼴 크기·줄 수는 바꾸지 않는다(배치가 흔들린다) — 색·그림자·글자 굴림만
+   */
+  write?(el: HTMLElement, o: { ctx: SceneCtx; text: string; at: number; dur: number; seed: string }): Paint;
+  /** 선 긋기 — el = inset:0 층, points 는 그 층 px. at 부터 dur 동안 그어지고, 다 그은 뒤에도 선 안이 흐른다 */
+  trace?(el: HTMLElement, o: { ctx: SceneCtx; points: readonly (readonly [number, number])[]; at: number; dur: number; seed: string; tone?: "base" | "accent" }): Paint;
+  /** 드롭 터짐 — 그 테마의 드롭 연출. 돌려준 shake 는 패턴이 화면 틀에, punch 는 주인공에 준다. 드롭 번호로만 */
+  drop?(el: HTMLElement, o: { ctx: SceneCtx; drop: number }): (t: number) => DropBurstState;
+}
+
+export const SLOT_NAMES = ["surface", "panel", "land", "write", "trace", "drop"] as const satisfies readonly (keyof ThemeSlots)[];
+
+const mods = import.meta.glob("../../../themes/*/slots.ts", { eager: true }) as Record<string, { slots?: ThemeSlots }>;
+
+const byId = new Map(Object.entries(mods).map(([path, mod]) => [path.split("/").at(-2)!, mod.slots ?? {}]));
+
+/** 테마 슬롯 — 없는 테마(npm 묶음에 안 든 테마 포함)나 슬롯을 안 채운 테마는 빈 객체 */
+export const themeSlots = (id: string | undefined | null): ThemeSlots => (id ? byId.get(id) ?? {} : {});
+
+export const slotThemeIds = (): string[] => [...byId.keys()].sort();

package/packages/themes/src/stage3d.ts

@@ -100,6 +100,26 @@ export function stage3d(root: HTMLElement, o: StageOpts): Stage3D {
   };
 }
 
+/**
+ * 서 있는 무대 — 처음 한 번만 그려 2D 캔버스로 옮겨 두고 그 뒤로는 다시 그리지 않는다.
+ * 움직이지 않는 3D 바탕(테마 슬롯 surface)을 프레임마다 SwiftShader 로 그릴 까닭이 없고, 렌더러 캔버스는 다른 무대가 가져가도 된다
+ */
+export function stillStage(stage: Stage3D, paint: (t: number) => void = (t) => stage.paint(t)): (t: number) => void {
+  let done = false;
+  return () => {
+    if (done) return;
+    paint(0);
+    const src = stage.renderer.domElement;
+    const c = document.createElement("canvas");
+    c.width = src.width;
+    c.height = src.height;
+    c.style.cssText = src.style.cssText;
+    c.getContext("2d")!.drawImage(src, 0, 0);
+    src.replaceWith(c);
+    done = true;
+  };
+}
+
 export interface TextPlaneOpts {
   text: string;
   /** CSS font 단축 꼴의 앞부분 없이 글꼴 스택만 — 굵기·크기는 따로 */

package/series/og-shorts.json

@@ -0,0 +1,14 @@
+{
+  "id": "og-shorts",
+  "label": "OG 쇼츠",
+  "summary": "OpenGateway 기술 쇼츠 — 측정 테마·차분한 남성 내레이션·깊은 앰비언트 곡·화면 자막, 45–60초, 끝 카드 OpenGateway",
+  "match": ["OG 쇼츠", "OG 숏츠", "OG 숏폼", "OG shorts", "오픈게이트웨이 쇼츠", "OpenGateway 쇼츠", "OpenGateway shorts"],
+  "purpose": "shorts",
+  "theme": "og-measure",
+  "voice": "gemini:Charon",
+  "music": { "mood": "deep" },
+  "captions": "on",
+  "duration": { "min": 45, "max": 60, "default": 45 },
+  "end": { "title": "OpenGateway", "line": "opengateway.ai" },
+  "answers": { "image": "og-gpt-image-2.5-sunburst", "video": "none" }
+}