kasaframe 0.0.0-stage → 0.1.3

package/packages/plan/src/plan.ts

@@ -0,0 +1,179 @@
+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, ShotSpec, Template } from "./types.ts";
+
+const IMAGE = /\.(png|jpe?g|webp)$/i;
+
+// 이음매 기본은 모션그래픽 전환이다. 영상 모델은 요청에 분명히 적었을 때만 부른다(돈·시간이 크고 결이 들쭉날쭉하다)
+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; // 사람이 못 박으면 판별을 건너뛴다
+  assets?: string[];
+  music?: string | null;
+  beats?: BeatsLike | null;
+  duration?: number;
+  aspect?: Aspect;
+  style?: string;
+  title?: string;
+  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 }
+    : 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 후보 셋 중 첫째
+  // 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 ?? 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,
+    role: s.role,
+    from: s.from,
+    dur: s.dur,
+    idea: s.idea,
+    assets: gen.filter((g) => g.scene === s.id).map((g) => `gen:${g.kind}:${g.id}`),
+  }));
+
+  const top = det.ranked[0];
+  const plan: Plan = {
+    request: input.request,
+    purpose: det.purpose,
+    confidence: det.confidence,
+    alternatives: det.ranked.slice(1, 3).map((r) => ({ purpose: r.purpose, p: r.p })),
+    reasons: [...(series ? [`시리즈 ${series.id}(${series.label})`] : []), ...(top?.reasons ?? (input.purpose ? ["사람이 정함"] : [])), ...notes, ...laid.notes],
+    title,
+    aspect: frame.aspect,
+    width: frame.width,
+    height: frame.height,
+    fps: tpl.fps,
+    duration: laid.duration,
+    style,
+    music: input.music ?? null,
+    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 = [
+      {
+        id: "purpose",
+        ask: "어떤 용도의 영상인가?",
+        choices: det.ranked.slice(0, 4).map((r) => `${r.purpose} — ${templates.find((t) => t.id === r.purpose)?.label}`),
+      },
+    ];
+  }
+  if (tpl.music === "required" && !input.music) {
+    plan.questions = [...(plan.questions ?? []), { id: "music", ask: `${tpl.label} 영상은 곡이 끌고 간다. 쓸 곡 파일은?`, choices: [] }];
+  }
+  return plan;
+}
+
+// "img:hook-bg" → hook 장면 바탕 그림, "vid:seam" → seam 장면 전체를 채우는 이음매 클립(앞 장면 끝 프레임 → 뒤 장면 첫 프레임, 계약 8)
+function genSpecs(
+  tpl: Template,
+  scenes: { id: string; role: string; idea: 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 ?? []) : [])]) {
+    const [kind, id] = spec.split(":") as ["img" | "vid", string];
+    if (kind === "vid") {
+      const i = scenes.findIndex((s) => s.id === id);
+      if (i <= 0 || i === scenes.length - 1) continue;
+      gen.push({
+        id,
+        kind,
+        scene: id,
+        seam: true,
+        prompt: `${o.subject} — 「${scenes[i - 1].idea}」 화면에서 「${scenes[i + 1].idea}」 화면으로 이음매 없이 빨려 들어가는 카메라 이동. ${o.style} 결, 글자 없음.`,
+      });
+      continue;
+    }
+    // 뮤비 주인공은 받은 그림을 참조해 한 장 만들고, 나머지 그림은 그 주인공을 참조해 같은 얼굴로 간다
+    if (id === "character") {
+      gen.push({ id, kind, scene: scenes[0].id, prompt: `${o.subject} 뮤직비디오 주인공 캐릭터 — 정면 전신 한 명, 단색 바탕, 글자 없음. ${o.style} 결.`, size: `${o.width}x${o.height}`, ...(o.refs.length ? { refs: o.refs } : {}) });
+      continue;
+    }
+    const scene = scenes.find((s) => id === s.id || id.startsWith(`${s.id}-`)) ?? scenes[0];
+    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/request.ts

@@ -0,0 +1,55 @@
+import type { Aspect } from "./types.ts";
+
+// 요청 글에서 사람이 못 박은 값만 뽑는다. 못 찾으면 undefined — 틀 기본값이 채운다.
+
+export function parseDuration(text: string): number | undefined {
+  const t = text.toLowerCase();
+  const min = t.match(/(\d+(?:\.\d+)?)\s*(?:분|min(?:ute)?s?\b)/);
+  const sec = t.match(/(\d+(?:\.\d+)?)\s*(?:초|s\b|sec(?:ond)?s?\b)/);
+  if (!min && !sec) {
+    if (/한\s*분|일\s*분/.test(t)) return 60;
+    if (/반\s*분/.test(t)) return 30;
+    return undefined;
+  }
+  return (min ? Number(min[1]) * 60 : 0) + (sec ? Number(sec[1]) : 0);
+}
+
+export function parseAspect(text: string): Aspect | undefined {
+  const t = text.toLowerCase();
+  if (/9\s*[:x×]\s*16|세로|vertical|portrait/.test(t)) return "9:16";
+  if (/1\s*[:x×]\s*1\b|정사각|square/.test(t)) return "1:1";
+  if (/16\s*[:x×]\s*9|가로|landscape|widescreen/.test(t)) return "16:9";
+  return undefined;
+}
+
+const STYLE_HINTS: [RegExp, string][] = [
+  [/카와이|kawaii|파스텔|pastel|귀여운|큐트|cute/i, "kawaii-pastel"],
+  [/카사텀|kasaterm/i, "kasaterm"],
+  [/\bog\b|오픈게이트웨이|opengateway|open gateway/i, "og"],
+  [/다크|어두운|dark|시네마틱|cinematic/i, "neutral-dark"],
+];
+
+export function parseStyle(text: string): string | undefined {
+  return STYLE_HINTS.find(([re]) => re.test(text))?.[1];
+}
+
+const SUBJECTS: [RegExp, string][] = [
+  [/카사텀|kasaterm/i, "kasaterm"],
+  [/\bog\b|오픈게이트웨이|opengateway|open gateway/i, "OpenGateway"],
+];
+
+// 아는 제품만 잡는다. 모르면 비워 두고 kf new(폴더 이름)·kf make(LLM)가 채운다 — 첫 낱말을 이름으로 찍으면 "15초" 같은 게 끝 카드에 뜬다
+export function parseTitle(text: string): string | undefined {
+  return SUBJECTS.find(([re]) => re.test(text))?.[1];
+}
+
+const ASCII_WORD = /^[a-z0-9 .:-]+$/i;
+
+// 영어 짧은 낱말("ad")이 "made" 같은 데 걸리지 않게 영문은 낱말 경계로, 한글은 그대로 찾는다
+export function mentions(text: string, word: string): boolean {
+  const t = text.toLowerCase();
+  const w = word.toLowerCase();
+  if (!ASCII_WORD.test(w)) return t.includes(w);
+  const esc = w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(^|[^a-z0-9])${esc}([^a-z0-9]|$)`).test(t);
+}

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/studio.ts

@@ -0,0 +1,53 @@
+// 말로 시작한 kf make 도 작업실이 떠 있으면 거기에 등록한다 — 페이지 「지난 작업」·실시간 미리보기로 보이게. 서버가 없으면 조용히 넘어간다
+const base = () => (process.env.KF_APP_URL ?? "http://127.0.0.1:5150").replace(/\/$/, "");
+
+async function post<T>(path: string, body: unknown): Promise<T | null> {
+  try {
+    const r = await fetch(`${base()}${path}`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal: AbortSignal.timeout(1500) });
+    return r.ok ? ((await r.json()) as T) : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface StudioLink {
+  id: string;
+  url: string;
+  send(p: { lines?: string[]; phase?: string; done?: boolean; ok?: boolean }): Promise<void>;
+  // console.error 로 찍는 진행 줄을 작업실로도 흘린다(모아서 0.5초마다)
+  mirror(): () => Promise<void>;
+}
+
+export async function attachStudio(o: { dir: string; request: string; model?: string; purpose?: string }): Promise<StudioLink | null> {
+  const r = await post<{ id: string; url: string }>("/api/jobs/attach", o);
+  if (!r) return null;
+  const send = async (p: Parameters<StudioLink["send"]>[0]) => {
+    await post(`/api/jobs/${r.id}/progress`, p);
+  };
+  return {
+    ...r,
+    send,
+    mirror() {
+      const orig = console.error;
+      let queue: string[] = [];
+      let chain = Promise.resolve();
+      const flush = () => {
+        if (!queue.length) return chain;
+        const lines = queue;
+        queue = [];
+        chain = chain.then(() => send({ lines }));
+        return chain;
+      };
+      const timer = setInterval(flush, 500);
+      console.error = (...args: unknown[]) => {
+        orig(...args);
+        queue.push(...args.map(String).join(" ").split("\n"));
+      };
+      return async () => {
+        clearInterval(timer);
+        console.error = orig;
+        await flush();
+      };
+    },
+  };
+}

package/packages/plan/src/templates.ts

@@ -0,0 +1,42 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { type Aspect, PURPOSES, type Purpose, type SafeArea, type Template } from "./types.ts";
+
+export const templatesDir = fileURLToPath(new URL("../../../templates/", import.meta.url));
+
+export function listTemplates(): Template[] {
+  return readdirSync(templatesDir)
+    .filter((d) => existsSync(join(templatesDir, d, "template.json")))
+    .map((d) => loadTemplate(d))
+    .sort((a, b) => PURPOSES.indexOf(a.id) - PURPOSES.indexOf(b.id));
+}
+
+export function loadTemplate(id: string): Template {
+  const file = join(templatesDir, id, "template.json");
+  if (!existsSync(file)) {
+    const have = readdirSync(templatesDir).filter((d) => existsSync(join(templatesDir, d, "template.json")));
+    throw new Error(`틀 "${id}" 가 없다. 있는 틀: ${have.join(" ")}`);
+  }
+  return JSON.parse(readFileSync(file, "utf8")) as Template;
+}
+
+export function frameFor(tpl: Template, aspect?: Aspect): { aspect: Aspect; width: number; height: number; safeArea: SafeArea } {
+  if (!aspect || aspect === tpl.aspect) return { aspect: tpl.aspect, width: tpl.width, height: tpl.height, safeArea: tpl.safeArea };
+  const v = tpl.variants?.[aspect];
+  if (!v) throw new Error(`틀 ${tpl.id} 는 ${aspect} 를 받지 않는다(${[tpl.aspect, ...Object.keys(tpl.variants ?? {})].join("·")})`);
+  return { aspect, width: v.width, height: v.height, safeArea: v.safeArea ?? tpl.safeArea };
+}
+
+// 틀 고유(장면 id → 틀 기본) → 역할 공용 → 공용 기본. 뮤비처럼 장면 id 가 곡마다 바뀌는 틀은 틀 기본(scenes/default.ts)이 받는다
+export function sceneSkeleton(tpl: Purpose, sceneId: string, role: string): string {
+  const tries = [
+    join(templatesDir, tpl, "scenes", `${sceneId}.ts`),
+    join(templatesDir, tpl, "scenes", "default.ts"),
+    join(templatesDir, "_shared", "scenes", `${role}.ts`),
+    join(templatesDir, "_shared", "scenes", "default.ts"),
+  ];
+  const hit = tries.find((p) => existsSync(p));
+  if (!hit) throw new Error(`장면 뼈대가 없다: ${tries.join(" · ")}`);
+  return readFileSync(hit, "utf8");
+}

package/packages/plan/src/themes.ts

@@ -0,0 +1,48 @@
+import { listThemes, loadTheme, type Theme } from "@kasaframe/themes";
+import { parseTitle } from "./request.ts";
+import type { Aspect, Purpose } from "./types.ts";
+
+export interface ThemePick {
+  id: string;
+  why: string;
+}
+
+const words = (s: string) => s.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((w) => w.length >= 2);
+
+// 자동 추천은 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));
+  const scored = pool.map((t) => {
+    const hay = `${t.name} ${t.metaphor} ${t.guide}`.toLowerCase();
+    const hit = [...ask].filter((w) => hay.includes(w));
+    return { t, score: hit.length, hit };
+  });
+  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();
+  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());
+    const hit = keys.filter((k) => t.includes(k));
+    if (!hit.length) continue;
+    // 제품 이름(「카사텀」·「OG」)은 무엇을 찍나일 뿐 결이 아니다 — 「카와이」·「리소」 같은 결 낱말보다 약하게, 「~ 느낌·풍·스타일」로 짚으면 가장 세게.
+    // 용도에 안 맞는 테마도 사람이 짚었으면 쓰되, 같은 점수면 용도에 맞는 쪽
+    const weight = (k: string) => (parseTitle(k) ? 4 : 10) + (new RegExp(`${k.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*(느낌|풍|스타일|결|톤|테마|처럼)`).test(t) ? 20 : 0);
+    const score = hit.reduce((a, k) => a + weight(k), 0) + (purpose && th.purposes.includes(purpose) ? 1 : 0);
+    if (!best || score > best.score) best = { th, score, hit };
+  }
+  return best ? { id: best.th.id, why: `요청이 「${best.hit.join("·")}」 로 ${best.th.name} 을(를) 짚었다 — ${best.th.metaphor}` } : null;
+}
+
+// 사람이 고른 id 는 review 까지 쓴다. draft 는 테마 폴더 sample/ 안에서만이라 여기선 막는다
+export function pickTheme(id: string): Theme {
+  const t = loadTheme(id);
+  if (t.status === "draft") throw new Error(`테마 ${id} 는 아직 draft — 견본이 review 로 올라온 뒤에 쓴다`);
+  return t;
+}

package/packages/plan/src/types.ts

@@ -0,0 +1,157 @@
+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"];
+
+export interface SafeArea { top: number; bottom: number; left: number; right: number }
+
+export interface TemplateScene {
+  id: string;
+  role: string;
+  sec?: number;
+  weight?: number;
+  anchor?: string; // start · end · drop:<k> · drop:last · section:<kind>
+  snap?: "bar" | "beat" | "none";
+  idea: string;
+  transition?: string; // 이음매 장면의 3D 전환 종류(dive·portal·cards·shatter·zoomOut·fold)
+}
+
+export interface Template {
+  id: Purpose;
+  label: string;
+  summary: string; // 틀 고르는 화면의 한 줄
+  aspect: Aspect;
+  width: number;
+  height: number;
+  fps: number;
+  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;
+  style: string;
+  safeArea: SafeArea;
+  text: { policy: "none" | "terms-only" | "captions" | "lyrics"; maxOnScreen: number; minPx: number };
+  // 뮤비: 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 는 요청에 「영상 생성」을 분명히 적었을 때만(이음매 기본은 모션그래픽 전환).
+  // 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[] };
+}
+
+// SPEC 4 중 장면 배치에 쓰는 것만
+export interface BeatsLike {
+  duration: number;
+  beats: number[];
+  downbeats?: number[];
+  bars?: number[];
+  drops?: number[];
+  sections?: { t: number; kind: string; strength?: number }[];
+}
+
+export interface PlannedScene {
+  id: string;
+  role: string;
+  from: number;
+  dur: number;
+  idea: string;
+  assets: string[];
+}
+
+// SPEC 계약 8 — @kasaframe/gen 의 GenSpec 과 같은 꼴. 이음매(seam) 영상의 id 는 kf.json 장면 id 와 같다
+export interface GenSpec {
+  id: string;
+  kind: "img" | "vid";
+  scene?: string;
+  prompt: string;
+  size?: string;
+  transparent?: boolean;
+  quality?: string;
+  refs?: string[];
+  seam?: boolean;
+  dur?: number;
+  first?: string;
+  last?: string;
+  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;
+  confidence: number;
+  alternatives: { purpose: Purpose; p: number }[];
+  reasons: string[];
+  title: string;
+  aspect: Aspect;
+  width: number;
+  height: number;
+  fps: number;
+  duration: number;
+  style: string;
+  music: string | null;
+  // 목소리 "<엔진>:<목소리>" · "none"(자막만). 정하기 전에는 없다
+  voice?: string;
+  captions: Template["captions"];
+  deliverables: string[];
+  scenes: PlannedScene[];
+  gen: GenSpec[];
+  // 고른 테마(themes/<id>). auto 면 approved 후보 셋을 themeCandidates 에 남기고 첫째를 쓴다
+  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/studio/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@kasaframe/studio",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "devDependencies": {
+    "vite": "^8.3.3"
+  }
+}

package/packages/studio/src/index.ts

@@ -0,0 +1 @@
+export { studioPlugin, studioConfig, type StudioConfig } from "./plugin.ts";