kasaframe 0.1.1 → 0.1.3

package/packages/director/src/assemble.ts

@@ -0,0 +1,361 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { dressSeed, type Dress } from "@kasaframe/motion/menu";
+import { loadTemplate, sceneSkeleton, type Template } from "@kasaframe/plan";
+import { catalog } from "./catalog.ts";
+import { TYPES, type Content, type Scene, type SceneType } from "./content.ts";
+import type { AspectName, Energy, TextPolicy } from "./pattern.ts";
+import { type Entry, type Pick, repick, selectAll, type Slot } from "./select.ts";
+import { type BeatsLite, cyclingText, dressAll, energyOf, seamKinds, seamSpots, type Spot } from "./transitions.ts";
+
+// content.json → 장면 시간표·장면 파일. 두 단계로 나뉜다 — 그 사이에 kf narrate 가 목소리로 장면 길이를 정한다.
+//   1. layout: 내용 장면 + 이음매를 kf.json 에 놓고 들릴 말을 captions.json 에(길이는 어림)
+//   2. build:  정해진 길이·곡 구간으로 패턴을 고르고 장면 파일·director.json 을 쓴다(LLM 없이 템플릿 조립)
+// 같은 content.json·틀·테마·씨앗이면 쓰는 파일이 바이트까지 같다 — 시각·경로·난수 없이 씨앗으로만 고른다.
+
+export const MARK = "// kf direct 가 지은 장면";
+// kf new 뼈대(무대·이음매) — 감독이 처음 들어설 때 지워도 되는 파일
+const SKELETON = /makeStage\(root, ctx, \{ dress: DRESS \}\)|transition3d\(root, ctx, \{ kind: KIND/;
+
+interface KfScene {
+  id: string;
+  from: number;
+  dur: number;
+  file: string;
+  role: string;
+  idea: string;
+  type?: SceneType;
+  space?: "2d" | "3d";
+  pattern?: string;
+  transition?: string;
+  dress?: Dress;
+  [k: string]: unknown;
+}
+
+const readJson = <T = any>(p: string): T => JSON.parse(readFileSync(p, "utf8"));
+const writeJson = (p: string, v: unknown) => writeFileSync(p, `${JSON.stringify(v, null, 2)}\n`);
+
+// say 가 없을 때 장면 길이 — 숫자·이름 하나는 짧게, 구조를 보이는 것은 길게
+const TYPE_SEC: Partial<Record<SceneType, number>> = { "hook-number": 3, title: 2.5, words: 2.5, end: 2.5, quote: 4, limit: 3, "term-reveal": 3.5 };
+const CHARS_PER_SEC = 4.5;
+
+function roleOf(s: Scene, i: number): string {
+  if (s.type === "end") return "end";
+  if (i === 0) return "hook";
+  if (s.type === "term-reveal" || s.type === "title") return "reveal";
+  if (s.type === "limit") return "limit";
+  return "explain";
+}
+
+const spaceOf = (s: { space?: string }): "2d" | "3d" => (s.space === "3d" ? "3d" : "2d");
+
+export function contentHash(c: Content): string {
+  return createHash("sha256").update(JSON.stringify(c)).digest("hex").slice(0, 16);
+}
+
+/** 1단계 — 내용 장면과 이음매를 시간표에. 길이는 어림(kf narrate 가 목소리로 고친다) */
+export function layout(dir: string, content: Content, o: { keepTiming?: boolean } = {}): { scenes: KfScene[]; seams: number } {
+  const kfPath = join(dir, "kf.json");
+  const kf = readJson(kfPath);
+  const tpl = loadTemplate(kf.template);
+  const fps: number = kf.fps;
+  const frame = (x: number) => Math.max(1, Math.round(x * fps)) / fps;
+  const n = tpl.narration ?? { lead: 0.25, tail: 0.5 };
+  // keepTiming(kf narrate 를 건너뛸 때) — 같은 장면(id·type)에 들릴 말도 같으면 앞 길이(목소리로 잰 것)를 그대로 둔다.
+  // 내레이션을 다시 돌릴 땐 늘 어림에서 시작한다 — 말 없는 장면·이음매에 앞 실행의 길이가 남으면 같은 content.json 이 다른 시간표를 낸다
+  const capPath = join(dir, "captions.json");
+  const oldCaps: { scene: string; text: string; from?: number }[] = existsSync(capPath) ? readJson(capPath) : [];
+  const said = (id: string) => oldCaps.filter((l) => l.scene === id).map((l) => l.text.trim()).join(" ");
+  const oldScenes = new Map<string, KfScene>((kf.scenes ?? []).map((x: KfScene) => [x.id, x]));
+  const est = (s: Scene) => {
+    const old = oldScenes.get(s.id);
+    if (o.keepTiming && old && old.type === s.type && said(s.id) === (s.say?.trim() ?? "")) return old.dur;
+    return s.say ? n.lead + [...s.say].length / CHARS_PER_SEC + n.tail : (s.dur ?? TYPE_SEC[s.type] ?? 5);
+  };
+
+  const tplSeams = tpl.scenes.filter((s) => s.role === "seam");
+  const seamSec = tplSeams[0]?.sec ?? 1.2;
+  // 투영을 맞춰 구운 3D 샷(kf blender 가 kf.json 장면에 남긴 matched)은 다시 놓아도 잃지 않는다
+  const matched = new Set<string>((kf.scenes ?? []).filter((s: KfScene) => s.matched).map((s: KfScene) => s.id));
+  const spots = seamSpots(content.scenes.map((s) => s.type), content.scenes.map(spaceOf), tplSeams.length, content.scenes.map((s) => matched.has(s.id)));
+  const taken = new Set(content.scenes.map((s) => s.id));
+  const seamIds: string[] = [];
+  for (let k = 0; seamIds.length < spots.length; k++) {
+    const id = tplSeams[k]?.id ?? `seam-${k + 1}`;
+    if (!taken.has(id) && !seamIds.includes(id)) seamIds.push(id);
+  }
+  const scenes: KfScene[] = [];
+  let t = 0;
+  const put = (s: { id: string; role: string; dur: number; idea: string; [k: string]: unknown }) => {
+    const dur = frame(s.dur);
+    scenes.push({ ...s, from: +t.toFixed(4), dur: +dur.toFixed(4), file: `scenes/${s.id}.ts` });
+    t += dur;
+  };
+  for (const [i, s] of content.scenes.entries()) {
+    const sp = spots.findIndex((x) => x.at === i);
+    // 이음매도 앞 길이(박에 붙인 것)를 그대로 — 안 그러면 뒤 장면 시각이 다 밀린다
+    if (sp >= 0) put({ id: seamIds[sp], role: "seam", dur: o.keepTiming && oldScenes.get(seamIds[sp])?.role === "seam" ? oldScenes.get(seamIds[sp])!.dur : seamSec, idea: spots[sp].bridge ? "공간 잇기 — 2D 와 3D 장면 사이(감독이 고른 전환)" : "이음매 — 감독이 고른 3D 전환", ...(spots[sp].bridge ? { bridge: spots[sp].bridge } : {}) });
+    put({ id: s.id, role: roleOf(s, i), dur: est(s), idea: s.type === "custom" ? String(s.idea ?? "") : `${s.type} — ${TYPES[s.type].does}`, type: s.type, ...(s.space ? { space: s.space } : {}), ...(matched.has(s.id) ? { matched: true } : {}) });
+  }
+  kf.title = content.title;
+  kf.scenes = scenes;
+  kf.duration = +t.toFixed(4);
+  writeJson(kfPath, kf);
+
+  // 낱말 시각(kf narrate 가 단 것)은 말이 같으면 남긴다
+  const lines = content.scenes.filter((s) => s.say?.trim()).map((s) => oldCaps.find((l) => l.scene === s.id && l.text.trim() === s.say!.trim() && l.from !== undefined) ?? { scene: s.id, text: s.say!.trim() });
+  if (lines.length) writeJson(capPath, lines);
+  const planPath = join(dir, "plan.json");
+  if (existsSync(planPath)) {
+    const plan = readJson(planPath);
+    plan.title = content.title;
+    plan.duration = kf.duration;
+    plan.scenes = scenes.map((s) => ({ id: s.id, role: s.role, from: s.from, dur: s.dur, idea: s.idea, assets: [] }));
+    const end = content.scenes.find((s) => s.type === "end");
+    if (typeof end?.line === "string") plan.line = end.line;
+    writeJson(planPath, plan);
+  }
+  return { scenes, seams: spots.length };
+}
+
+export interface BuildOpts {
+  seed?: string;
+  /** 장면 id → kf check 에서 떨어진 패턴 id */
+  failed?: Record<string, string[]>;
+  /** 이음매 장면 id → 떨어진 전환 종류 */
+  seamFailed?: Record<string, string[]>;
+  entries?: Entry[];
+  /** 이 장면만 다시 짓는다 — 나머지 장면 파일·고름·이음매는 손대지 않는다(조각 렌더가 바뀐 장면만 다시 굽게) */
+  only?: string[];
+  /** 사람이 고른 것 — 장면 id → 패턴 id·장면 씨앗. director.json 의 pinned 에 남아 다음 kf direct 가 덮지 않는다 */
+  pins?: Record<string, Pin>;
+  /** 장면마다 진행 줄(「장면 <id>: 쓰는 중|씀|실패 <까닭>」 — 굽기·검사까지 끝난 「끝」은 작업실·render 몫) */
+  log?: (line: string) => void;
+}
+
+export interface Pin {
+  pattern?: string;
+  seed?: string;
+}
+
+export interface SceneReport {
+  id: string;
+  role: string;
+  from: number;
+  dur: number;
+  type?: string;
+  energy?: Energy;
+  pattern?: string;
+  transition?: string;
+  dress?: Dress;
+  custom?: "kept" | "skeleton";
+  order?: { id: string; score: number; why: string[] }[];
+  rejected?: { id: string; why: string }[];
+  attempt?: number;
+  /** 그 장면 내용의 해시 — 안 바뀐 장면은 고름을 그대로 둔다 */
+  hash?: string;
+}
+
+export interface Report {
+  version: 1;
+  seed: string;
+  key: string;
+  content: string;
+  purpose: string;
+  theme: string | null;
+  aspect: AspectName;
+  scenes: SceneReport[];
+  failed: Record<string, string[]>;
+  seamFailed: Record<string, string[]>;
+  pinned: Record<string, Pin>;
+}
+
+const aspectOf = (w: number, h: number): AspectName => (w > h ? "16:9" : w < h ? "9:16" : "1:1");
+
+function fill(src: string, vars: Record<string, string>): string {
+  return src.replace(/\{\{(\w+)\}\}/g, (_, k) => (vars[k] ?? "").replace(/["\\]/g, "\\$&"));
+}
+
+/** 장면에서 패턴에 넘길 내용 — 장면 칸(id·type·say·dur·space)을 뺀 나머지 */
+function payload(s: Scene): Record<string, unknown> {
+  const { id: _i, type: _t, say: _s, dur: _d, space: _p, ...rest } = s;
+  return rest;
+}
+
+const sceneHash = (s: Scene): string => createHash("sha256").update(JSON.stringify([s.type, payload(s)])).digest("hex").slice(0, 12);
+
+function patternFile(spec: string, d: Record<string, unknown>): string {
+  return `${MARK} — 정본은 content.json 이다. 고치려면 content.json 을 고치고 kf direct 를 다시 부른다(이 파일은 덮인다).
+import pattern from "${spec}";
+import { directed } from "@kasaframe/director/scene";
+import { makeStage } from "../lib/stage.ts";
+
+const captions = import.meta.glob("../captions.json", { eager: true, import: "default" });
+
+export default directed(pattern, ${JSON.stringify(d, null, 2)}, { makeStage, captions });
+`;
+}
+
+/** 2단계 — 패턴·전환·바탕을 고르고 장면 파일을 쓴다 */
+export async function build(dir: string, content: Content, o: BuildOpts = {}): Promise<Report> {
+  const kf = readJson(join(dir, "kf.json"));
+  const plan = existsSync(join(dir, "plan.json")) ? readJson(join(dir, "plan.json")) : {};
+  const tpl: Template = loadTemplate(kf.template);
+  const entries = o.entries ?? (await catalog());
+  const beats: BeatsLite | null = kf.beats && existsSync(join(dir, kf.beats)) ? readJson(join(dir, kf.beats)) : null;
+  const theme: string | null = kf.theme ?? null;
+  const purpose: string = kf.template;
+  const aspect = aspectOf(kf.width, kf.height);
+  const policy: TextPolicy = kf.text?.policy ?? tpl.text.policy;
+  const seed = o.seed ?? content.seed ?? "0";
+  const key = dressSeed(content.title, purpose, theme ?? plan.style, seed);
+  const hash = contentHash(content);
+  const scenes: KfScene[] = kf.scenes;
+  const byId = new Map(content.scenes.map((s) => [s.id, s]));
+
+  const prevPath = join(dir, "director.json");
+  const prev: Report | null = existsSync(prevPath) ? readJson(prevPath) : null;
+  // 씨앗 열쇠가 같고 내용이 같은 장면만 앞 기록(떨어진 패턴·핀)을 이어 간다
+  const same = !!prev && prev.key === key;
+  const prevHash = new Map((same ? prev.scenes : []).map((x) => [x.id, x.hash]));
+  const unchanged = (id: string) => byId.has(id) && prevHash.get(id) === sceneHash(byId.get(id)!);
+  // 떨어진 기록은 「패턴 id@판」 — 그 패턴이 그 뒤 고쳐졌으면(판이 다르면) 다시 후보로 돌아온다
+  const revOf = new Map(entries.map((e) => [e.meta.id, e.rev ?? ""]));
+  const tag = (id: string) => `${id}@${revOf.get(id) ?? ""}`;
+  const stored: Record<string, string[]> = {};
+  for (const [id, list] of Object.entries(same ? prev.failed : {})) if (unchanged(id)) stored[id] = list.filter((x) => x.includes("@") && revOf.has(x.slice(0, x.indexOf("@"))) && x === tag(x.slice(0, x.indexOf("@"))));
+  for (const [id, list] of Object.entries(o.failed ?? {})) stored[id] = [...new Set([...(stored[id] ?? []), ...list.map(tag)])];
+  const failed: Record<string, string[]> = Object.fromEntries(Object.entries(stored).filter(([, l]) => l.length).map(([id, l]) => [id, l.map((x) => x.slice(0, x.indexOf("@")))]));
+  const seamFailed = { ...(same ? prev.seamFailed : {}), ...o.seamFailed };
+  const pinned: Record<string, Pin> = { ...(same ? (prev.pinned ?? {}) : {}) };
+  for (const [id, p] of Object.entries(o.pins ?? {})) pinned[id] = { ...pinned[id], ...p };
+  const only = o.only ? new Set(o.only) : null;
+  for (const id of only ?? []) if (!scenes.some((s) => s.id === id)) throw new Error(`--scenes: 시간표에 없는 장면 ${id}`);
+
+  // 패턴 자리
+  const slotScenes = scenes.filter((s) => s.role !== "seam" && s.type && s.type !== "custom");
+  const slots: Slot[] = slotScenes.map((s) => ({ id: s.id, type: s.type!, content: payload(byId.get(s.id)!), dur: s.dur, energy: energyOf(beats, s.from, s.dur, s === scenes[0]) }));
+  const ctx = { aspect, purpose, theme, policy, seed: key };
+  const entryOf = new Map(entries.map((e) => [e.meta.id, e]));
+  const prevOf = new Map((same ? prev.scenes : []).filter((s) => s.pattern).map((s) => [s.id, s]));
+  // 전체 짓기는 늘 처음부터 같은 길(selectAll) — 고름이 (내용·씨앗·떨어진 기록)에만 달려 앞 실행의 이력이 안 남는다.
+  // 고른 장면만(only)일 때만 앞 고름을 핀으로 두고 그 장면만 앞뒤와 다시 따진다
+  let picks: Pick[];
+  if (only && slots.every((s) => prevOf.has(s.id))) {
+    picks = slots.map((s) => {
+      const p = prevOf.get(s.id)!;
+      return { scene: s.id, pattern: p.pattern!, order: p.order ?? [], rejected: p.rejected ?? [], attempt: (failed[s.id] ?? []).length };
+    });
+    for (const [i, s] of slots.entries()) {
+      if (!only.has(s.id)) continue;
+      const r = repick(picks, i, slots, entries, ctx, failed[s.id] ?? []);
+      if (!r) throw new Error(`장면 ${s.id}: 남은 패턴 후보가 없다 — 떨어진 것 ${(failed[s.id] ?? []).join(", ")}`);
+      picks[i] = r;
+    }
+  } else picks = selectAll(slots, entries, ctx, failed);
+  // 사람이 고른 패턴이 이긴다 — 그 type 의 패턴이어야 한다
+  for (const [i, s] of slots.entries()) {
+    const want = pinned[s.id]?.pattern;
+    if (!want || picks[i].pattern === want) continue;
+    const e = entryOf.get(want);
+    if (!e || (!e.fallback && e.meta.type !== s.type)) throw new Error(`--pattern ${s.id}=${want}: ${e ? `${s.type} 장면에 ${e.meta.type} 패턴` : "없는 패턴"} — 후보는 director.json 의 order`);
+    picks[i] = { ...picks[i], pattern: want };
+  }
+  const pickOf = new Map(picks.map((p) => [p.scene, p]));
+
+  // 이음매 종류 — 2D↔3D 경계는 공간 잇기
+  const seamIdx = scenes.flatMap((s, i) => (s.role === "seam" ? [i] : []));
+  const spots: Spot[] = seamIdx.map((i) => {
+    const a = spaceOf(scenes[i - 1] ?? {});
+    const b = spaceOf(scenes[i + 1] ?? {});
+    return { at: i, bridge: a === b ? false : b === "3d" ? "up" : "down" };
+  });
+  const kinds = seamKinds(spots, key, tpl.scenes.find((s) => s.role === "seam")?.transition ?? "dive", Object.fromEntries(seamIdx.map((i, k) => [k, seamFailed[scenes[i].id] ?? []])));
+
+  const dress = dressAll(key, scenes, tpl.moves, theme);
+  const scenesDir = join(dir, "scenes");
+  mkdirSync(scenesDir, { recursive: true });
+  const report: SceneReport[] = [];
+  const keep = new Set<string>();
+  const log = o.log ?? (() => {});
+  for (const [i, s] of scenes.entries()) {
+    const file = join(dir, s.file);
+    keep.add(s.file);
+    const base = { id: s.id, role: s.role, from: s.from, dur: s.dur };
+    if (only && !only.has(s.id)) {
+      const kept = prev?.scenes.find((x) => x.id === s.id);
+      if (kept) report.push(kept);
+      continue;
+    }
+    log(`장면 ${s.id}: 쓰는 중`);
+    if (s.role === "seam") {
+      const kind = kinds[seamIdx.indexOf(i)];
+      s.transition = kind;
+      delete s.dress;
+      writeOwned(file, `${MARK} — 이음매(전환은 director.json)\n${fill(sceneSkeleton(kf.template, s.id, "seam"), { transition: kind, title: content.title })}`, !prev);
+      report.push({ ...base, transition: kind });
+      log(`장면 ${s.id}: 씀`);
+      continue;
+    }
+    const c = byId.get(s.id)!;
+    if (c.type === "custom") {
+      const own = typeof c.file === "string" ? c.file : s.file;
+      if (own !== s.file) {
+        keep.add(own);
+        s.file = own;
+      }
+      s.dress = dress[i];
+      if (existsSync(join(dir, own)) && !SKELETON.test(readFileSync(join(dir, own), "utf8"))) {
+        report.push({ ...base, type: "custom", custom: "kept" });
+        log(`장면 ${s.id}: 씀`);
+        continue;
+      }
+      writeFileSync(join(dir, own), fill(sceneSkeleton(kf.template, s.id, s.role), { word: content.title, title: content.title, line: String(plan.line ?? ""), move: "rise", transition: "dive", ...dress[i] }));
+      report.push({ ...base, type: "custom", custom: "skeleton" });
+      log(`장면 ${s.id}: 씀`);
+      continue;
+    }
+    const p = pickOf.get(s.id)!;
+    const e = entryOf.get(p.pattern)!;
+    // 감독 기본은 무대 글 수가 낱말을 돌려 띄운다 — 판 넘김·유령 줄만(자르거나 겹쳐 흐리는 수는 안 쓴다)
+    const prevText = scenes[i - 1]?.dress?.text;
+    const d = e.fallback ? { ...dress[i], text: cyclingText(key, s.id, prevText) } : dress[i];
+    s.dress = d;
+    s.pattern = p.pattern;
+    s.idea = `${s.type} — ${e.meta.does}`;
+    const directedArgs = { scene: s.id, type: s.type, content: payload(c), seed: pinned[s.id]?.seed ?? `${key}|${s.id}`, theme, dress: d, policy, first: i === 0, last: i === scenes.length - 1, loop: !!tpl.loop };
+    writeOwned(file, patternFile(e.spec, directedArgs), !prev);
+    report.push({ ...base, type: s.type, energy: slots.find((x) => x.id === s.id)!.energy, pattern: p.pattern, dress: d, order: p.order.slice(0, 5), rejected: p.rejected, attempt: p.attempt, hash: sceneHash(c) });
+    log(`장면 ${s.id}: 씀`);
+  }
+
+  // 시간표에 없는 장면 파일 — 뼈대는 지우고, 손으로 쓴 것은 scenes/_unused/ 로 비켜 둔다(main.ts 가 안 싣는다)
+  for (const f of readdirSync(scenesDir)) {
+    if (!f.endsWith(".ts") || keep.has(`scenes/${f}`)) continue;
+    const p = join(scenesDir, f);
+    const body = readFileSync(p, "utf8");
+    if (body.startsWith(MARK) || SKELETON.test(body)) unlinkSync(p);
+    else stash(dir, f);
+  }
+
+  writeJson(join(dir, "kf.json"), kf);
+  const out: Report = { version: 1, seed, key, content: hash, purpose, theme, aspect, scenes: report, failed: Object.fromEntries(Object.entries(failed).map(([id, l]) => [id, l.map(tag)])), seamFailed, pinned };
+  writeJson(prevPath, out);
+  return out;
+}
+
+function stash(dir: string, name: string): void {
+  mkdirSync(join(dir, "scenes", "_unused"), { recursive: true });
+  renameSync(join(dir, "scenes", name), join(dir, "scenes", "_unused", name));
+}
+
+// 감독 몫 파일만 덮는다 — 손으로 쓴 파일이 같은 자리에 있으면 _unused 로 비켜 두고 쓴다(처음 들어설 땐 뼈대도 지운다)
+function writeOwned(file: string, body: string, first: boolean): void {
+  if (existsSync(file)) {
+    const old = readFileSync(file, "utf8");
+    if (old === body) return;
+    if (!old.startsWith(MARK) && !(first && SKELETON.test(old))) stash(join(file, "..", ".."), file.split("/").at(-1)!);
+  }
+  writeFileSync(file, body);
+}

package/packages/director/src/brief.ts

@@ -0,0 +1,122 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { type Question, questionsMarkdown } from "@kasaframe/gen";
+import { loadTemplate, parseDuration } from "@kasaframe/plan";
+import { contentGuide } from "./content.ts";
+
+// 감독 모드에서 모델이 쓰는 것은 content.json 하나 — 지시서(Claude Code)와 OG 프롬프트가 같은 칸 표·요령을 쓴다.
+
+const readJson = <T = any>(p: string): T => JSON.parse(readFileSync(p, "utf8"));
+
+const EXAMPLE = {
+  title: "MLA",
+  request: "OG 쇼츠 — MLA 가 뭔지 45초",
+  scenes: [
+    { id: "hook", type: "hook-number", value: 57, unit: "×", prefix: "1/", label: "KV 캐시", say: "KV 캐시가, 57분의 1로 줄어듭니다.", source: "DeepSeek-V2 논문 표 1" },
+    { id: "cost", type: "fill", total: 80, filled: 80, label: "GPU 한 장 80GB", unit: "GB", say: "…", source: "…" },
+    { id: "how", type: "formula", parts: "K = c × W_UK", say: "…" },
+    { id: "name", type: "term-reveal", term: "MLA", full: "Multi-head Latent Attention", ko: "멀티헤드 잠재 어텐션", say: "…" },
+    { id: "end", type: "end", title: "MLA", line: "캐시를 57배 줄이는 어텐션", say: "…" },
+  ],
+};
+
+interface Brief {
+  request: string;
+  title: string;
+  purpose: string;
+  label: string;
+  aspect: string;
+  target: number;
+  policy: string;
+  maxOnScreen: number;
+  theme: string | null;
+  voice: string;
+  music: string;
+}
+
+function facts(dir: string): Brief {
+  const kf = readJson(join(dir, "kf.json"));
+  const plan = existsSync(join(dir, "plan.json")) ? readJson(join(dir, "plan.json")) : {};
+  const tpl = loadTemplate(kf.template);
+  return {
+    request: plan.request ?? kf.title,
+    title: kf.title,
+    purpose: kf.template,
+    label: tpl.label,
+    aspect: plan.aspect ?? (kf.width > kf.height ? "16:9" : kf.width < kf.height ? "9:16" : "1:1"),
+    target: parseDuration(plan.request ?? "") ?? tpl.duration.default,
+    policy: kf.text?.policy ?? tpl.text.policy,
+    maxOnScreen: kf.text?.maxOnScreen ?? tpl.text.maxOnScreen,
+    theme: kf.theme ?? null,
+    voice: plan.voice ?? plan.answers?.voice ?? tpl.narration?.voice ?? "none",
+    music: plan.answers?.music ?? kf.music ?? "none",
+  };
+}
+
+function rules(b: Brief): string[] {
+  const chars = Math.round(b.target * 4.5);
+  return [
+    `- **say** 가 장면 길이를 정한다(목소리 먼저) — 차분한 설명체, 마디는 쉼표·문장은 마침표, 1초에 4–5글자. 영상 ${b.target}초면 say 를 다 합쳐 ${chars}자 안팎. 훅은 한 마디.`,
+    `- **화면 글은 칸에만** — 글 정책 \`${b.policy}\`${b.policy === "terms-only" ? "(전문 낱말·숫자만 — 문장은 say 로)" : ""}, 한 화면 ${b.maxOnScreen}개 안팎. 칸은 짧게.`,
+    "- **숫자는 value 와 unit 을 따로**(\"9.2 GB\" 가 아니라 value 9.2 · unit \"GB\"), 숫자가 있는 장면은 **source**(출처) 를 꼭.",
+    "- 첫 장면은 결과 먼저(`hook-number`·`compare`·`words`), 마지막은 `end`. 같은 type 을 잇달아 쓰지 않는다 — 내용이 같은 꼴이면 다른 type 으로 바꿔 보인다(막대 → 칸 채우기 → 식).",
+    "- 장면 6–9개. 화면 문법·움직임·전환·카메라·바탕은 감독이 고른다 — content.json 에 쓰지 않는다. 패턴에 없는 화면만 `custom`(idea 를 적으면 kf direct 가 뼈대를 두고, 그 파일은 직접 쓴다).",
+  ];
+}
+
+/** Claude Code 감독 모드 지시서 — MAKE.md */
+export function directBrief(dir: string): string {
+  const b = facts(dir);
+  const plan = existsSync(join(dir, "plan.json")) ? readJson(join(dir, "plan.json")) : {};
+  const asks: Question[] = plan.asks ?? [];
+  const answers: Record<string, string> = plan.answers ?? {};
+  const pending = (id: string) => asks.some((q) => q.id === id);
+  const gen = [
+    answers.image && answers.image !== "none" ? `- 그림이 필요한 장면(\`media\`·\`screen\`)은 \`npx kf gen img "<구체적 프롬프트>" --id <id> --provider ${answers.image} --project ${dir}\` 로 만들고 칸에 \`gen/<id>.png\`. 받은 자산·실제 화면으로 되면 만들지 않는다.` : "- 그림 생성은 하지 않는다(고른 답 none) — `media`·`screen` 은 받은 자산만.",
+    answers.blender && answers.blender !== "none" ? `- 주인공 3D 샷이 맞는 장면은 \`"space": "3d"\` — 3D 장면은 ${answers.blender === "three" ? "three(stage3d)" : "Blender 툰 샷(kf blender)"}로, 2D 장면과의 경계엔 감독이 공간 잇기 전환을 넣는다.` : "",
+    answers.video && answers.video !== "none" ? `- 캐릭터가 실제로 움직여야 하면 \`npx kf gen vid … --provider ${answers.video} --yes\` 로 만든 클립을 \`media\` 장면 assets 에.` : "",
+  ].filter(Boolean);
+  return [
+    `# 감독 모드 — ${b.title}`,
+    "",
+    `요청: ${b.request}`,
+    `${b.label}(${b.purpose}) · ${b.aspect} · 목표 ${b.target}초 · ${pending("theme") ? `테마 아직 — 맨 위 질문의 답(지금 깔린 것 ${b.theme ?? "프리셋"})` : b.theme ? `테마 ${b.theme}` : "프리셋"} · 목소리 ${pending("voice") ? "아직 — 맨 위 질문의 답" : b.voice} · 곡 ${pending("music") ? "아직 — 맨 위 질문의 답" : b.music}`,
+    "",
+    ...questionsMarkdown(asks, (flags) => `npx kf make --answer ${dir} ${flags}`),
+    "## 할 일 — 장면 코드는 쓰지 않는다",
+    "",
+    `1. \`${dir}/content.json\` 을 쓴다 — **무엇을** 보일지만(장면마다 type·칸·say·source). 아래 칸 표가 정본이다.`,
+    `2. \`npx kf direct ${dir}\` — 감독이 장면마다 검증된 장면 문법(패턴)을 테마·용도·곡 구간 에너지·앞뒤 장면과 안 겹치기로 골라 장면 파일을 조립하고, 내레이션으로 길이를 맞추고, \`kf check\` 가 떨어진 장면은 다음 후보로 다시 짓는다. 칸이 틀렸으면 어느 칸인지 찍고 멈춘다.`,
+    `3. \`npx kf look ${dir}\` 의 장면 모음·확인표를 직접 본다. 마음에 안 들면 content.json 을 고치거나 \`--seed <아무 글>\` 로 다른 고름을 본다(같은 씨앗이면 늘 같은 그림).`,
+    `4. \`npx kf make --finish ${dir}\` — 렌더·검사·표지·자막.`,
+    "",
+    "## 쓰는 요령",
+    "",
+    ...rules(b),
+    ...gen,
+    "",
+    "## content.json 꼴",
+    "",
+    "```json",
+    JSON.stringify(EXAMPLE, null, 2),
+    "```",
+    "",
+    contentGuide(),
+    "",
+  ].join("\n");
+}
+
+/** OG 모드 — 모델이 content.json 을 한 번에 쓰게 하는 메시지 */
+export function contentPrompt(dir: string, fix?: string): { role: "system" | "user"; content: string }[] {
+  const b = facts(dir);
+  return [
+    {
+      role: "system",
+      content: `너는 짧은 영상의 내용만 정한다 — 장면마다 무엇을 보일지(type 과 칸)와 들릴 말(say). 화면 문법·움직임·전환·카메라·바탕은 알고리즘이 고르니 쓰지 않는다. JSON 하나로만 답한다.\n\n${contentGuide()}`,
+    },
+    {
+      role: "user",
+      content: `요청: ${b.request}\n용도: ${b.label}(${b.purpose}) · ${b.aspect} · 목표 ${b.target}초 · 이름 후보: ${b.title}\n\n요령:\n${rules(b).join("\n")}\n\n꼴(예시 — 내용은 요청에 맞게 새로):\n${JSON.stringify(EXAMPLE)}${fix ? `\n\n앞 답의 고칠 곳:\n${fix}` : ""}`,
+    },
+  ];
+}

package/packages/director/src/catalog.ts

@@ -0,0 +1,49 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import fallback from "./fallback.ts";
+import type { Pattern } from "./pattern.ts";
+import fillCells from "./patterns/fill/cells.ts";
+import formulaStack from "./patterns/formula/stack.ts";
+import type { Entry } from "./select.ts";
+
+// 고를 수 있는 패턴 전부 — 패턴 라이브러리(@kasaframe/patterns, 장면 문법 담당)가 있으면 그 PATTERNS 와, 감독이 엔진을 세우려고 둔 것.
+// 같은 id 면 라이브러리 쪽이 이긴다(감독 쪽은 라이브러리로 옮겨 가는 중인 것).
+
+const OWN: Pattern<any>[] = [fillCells, formulaStack];
+
+const specOf = (pkg: string, id: string): string => {
+  const dot = id.indexOf(".");
+  return `${pkg}/${id.slice(0, dot)}/${id.slice(dot + 1)}`;
+};
+
+export async function catalog(): Promise<Entry[]> {
+  let lib: Pattern<any>[] = [];
+  try {
+    const mod = (await import("@kasaframe/patterns" as string)) as { PATTERNS?: Pattern<any>[] };
+    lib = mod.PATTERNS ?? [];
+  } catch (e) {
+    // 라이브러리가 아직 없으면 감독 쪽 것만 — 깨진 패턴은 숨기지 않는다
+    if (!/Cannot find (package|module)|ERR_MODULE_NOT_FOUND/.test(String(e))) throw e;
+  }
+  const ids = new Set(lib.map((p) => p.id));
+  const entries: Entry[] = [
+    ...lib.map((p) => ({ meta: p, spec: specOf("@kasaframe/patterns", p.id) })),
+    ...OWN.filter((p) => !ids.has(p.id)).map((p) => ({ meta: p, spec: specOf("@kasaframe/director/patterns", p.id) })),
+    { meta: fallback, spec: "@kasaframe/director/fallback", fallback: true },
+  ];
+  for (const e of entries) {
+    if (!e.fallback && !/^[a-z0-9-]+\.[a-z0-9-]+$/.test(e.meta.id)) throw new Error(`패턴 id "${e.meta.id}" 는 <type>.<이름> 꼴이어야 한다`);
+    e.rev = revOf(e.spec);
+  }
+  return entries.sort((a, b) => (a.meta.id < b.meta.id ? -1 : a.meta.id > b.meta.id ? 1 : 0));
+}
+
+// 패턴 파일 내용의 해시 — 장면 문법 쪽이 패턴을 고치면 판이 바뀐다
+function revOf(spec: string): string | undefined {
+  try {
+    return createHash("sha256").update(readFileSync(fileURLToPath(import.meta.resolve(spec)))).digest("hex").slice(0, 8);
+  } catch {
+    return undefined;
+  }
+}