kasaframe 0.0.0-stage → 0.1.3

package/packages/cli/src/commands/bench.ts

@@ -0,0 +1,123 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Command } from "../command.ts";
+import { num, parseFlags } from "../command.ts";
+
+const kfBin = fileURLToPath(new URL("../kf.ts", import.meta.url));
+
+const USAGE = `kf bench "<대충 한 요청>" [--runs 3] [--model claude-code|<OG 모델>] [--out 폴더] [kf make 에 넘길 플래그…]
+
+같은 요청으로 kf make 를 여러 번 돌려 나란히 본다 — 「대충 말해도 같은 결과」를 재는 시험 틀.
+  같아야 할 것: 용도·시리즈·테마·스타일·목소리·곡·자막·길이·장면 수·장면 시간표·장면 연출·생성 거리·3D 샷·고른 답·물을 것
+  달라도 되는 것: 검사 점수·장면 모음(모델이 장면을 쓰는 OG 모드에서만 나온다)
+  claude-code 모드(기본)는 kf make 가 지시서에서 멈추니 계획까지 본다. --model <OG 모델> 이면 끝까지 굽고 검사·장면 모음까지(실행마다 렌더 — 오래 걸린다)
+  결과: <out>/report.md · report.json · (OG) sheets.png. 같아야 할 것이 달라지면 빨간 「다름」, 종료 코드 1`;
+
+const RED = (s: string) => (process.stdout.isTTY ? `\x1b[31m${s}\x1b[0m` : s);
+const DIM = (s: string) => (process.stdout.isTTY ? `\x1b[2m${s}\x1b[0m` : s);
+
+const read = (f: string) => (existsSync(f) ? JSON.parse(readFileSync(f, "utf8")) : null);
+const short = (v: unknown) => createHash("sha256").update(JSON.stringify(v ?? null)).digest("hex").slice(0, 8);
+
+interface Run {
+  dir: string;
+  code: number;
+  same: Record<string, string>;
+  vary: Record<string, string>;
+  sheet?: string;
+}
+
+// 실행 하나에서 비교할 값 — 긴 것(시간표·연출·생성 거리)은 지문으로 줄이고 report.json 에 원본을 둔다
+function measure(dir: string, code: number): Run {
+  const plan = read(join(dir, "plan.json")) ?? {};
+  const kf = read(join(dir, "kf.json")) ?? {};
+  const scenes: { id: string; from: number; dur: number; dress?: unknown }[] = kf.scenes ?? plan.scenes ?? [];
+  const same: Record<string, string> = {
+    용도: plan.purpose ?? "-",
+    시리즈: plan.series ?? "-",
+    테마: plan.theme ?? "-",
+    스타일: plan.style ?? "-",
+    목소리: plan.voice ?? plan.answers?.voice ?? "-",
+    곡: (kf.music ?? plan.music ?? plan.answers?.music ?? "-").toString().split("/").pop(),
+    자막: kf.captions ?? plan.captions ?? "-",
+    길이: String(kf.duration ?? plan.duration ?? "-"),
+    "장면 수": String(scenes.length),
+    시간표: short(scenes.map((s) => [s.id, s.from, s.dur])),
+    연출: short(scenes.map((s) => s.dress ?? null)),
+    "생성 거리": (plan.gen ?? []).map((g: { kind: string; id: string; provider?: string }) => `${g.kind}:${g.id}${g.provider ? `@${g.provider}` : ""}`).join(" ") || "-",
+    "3D 샷": (plan.shots ?? []).map((s: { id: string; tool: string }) => `${s.id}@${s.tool}`).join(" ") || "-",
+    "고른 답": Object.entries(plan.answers ?? {}).map(([k, v]) => `${k}=${String(v).split("/").pop()}`).sort().join(" ") || "-",
+    "물을 것": (plan.asks ?? []).map((q: { id: string }) => q.id).join(" ") || "-",
+  };
+  const check = read(join(dir, "out", "check.json"));
+  const vary: Record<string, string> = {};
+  if (check) {
+    const fs: { severity: string }[] = check.findings ?? [];
+    vary["검사"] = `오류 ${fs.filter((f) => f.severity === "error").length} · 경고 ${fs.filter((f) => f.severity === "warn").length}`;
+  }
+  vary["종료 코드"] = String(code);
+  const sheet = join(dir, "out", "look-sheet.png");
+  return { dir, code, same, vary, ...(existsSync(sheet) ? { sheet } : {}) };
+}
+
+function table(runs: Run[]): { lines: string[]; diff: string[] } {
+  const keys = Object.keys(runs[0].same);
+  const diff = keys.filter((k) => new Set(runs.map((r) => r.same[k])).size > 1);
+  const w = Math.max(...keys.map((k) => [...k].length * 2)) + 2;
+  const pad = (s: string, n: number) => s + " ".repeat(Math.max(0, n - [...s].reduce((a, c) => a + (/[ㄱ-힯]/.test(c) ? 2 : 1), 0)));
+  const lines = [pad("", w) + runs.map((_, i) => `실행 ${i + 1}`).join(" | ")];
+  for (const k of keys) {
+    const row = `${pad(k, w)}${runs.map((r) => r.same[k]).join(" | ")}`;
+    lines.push(diff.includes(k) ? RED(`${row}   다름`) : row);
+  }
+  for (const k of Object.keys(runs[0].vary)) lines.push(DIM(`${pad(k, w)}${runs.map((r) => r.vary[k] ?? "-").join(" | ")}`));
+  return { lines, diff };
+}
+
+const cmd: Command = {
+  summary: "일관성 시험 — 같은 요청으로 kf make 를 여러 번, 같아야 할 것이 달라지면 빨갛게",
+  usage: USAGE,
+  async run(argv) {
+    const { args, opts } = parseFlags(argv);
+    const request = args.join(" ").trim();
+    if (!request) {
+      console.error(USAGE);
+      return 2;
+    }
+    const runs = Math.max(2, Math.round(num(opts.runs, 3)));
+    const model = typeof opts.model === "string" ? opts.model : "claude-code";
+    const out = resolve(typeof opts.out === "string" ? opts.out : `bench-${new Date().toISOString().slice(0, 16).replace(/[-:T]/g, "")}`);
+    mkdirSync(out, { recursive: true });
+    // kf make 로 그대로 넘길 플래그(--yes·--no-gen·--allow·--image 등) — bench 자신의 것은 뺀다
+    const pass: string[] = [];
+    for (const [k, v] of Object.entries(opts)) {
+      if (["runs", "model", "out"].includes(k)) continue;
+      pass.push(`--${k}`, ...(v === true ? [] : [String(v)]));
+    }
+    const done: Run[] = [];
+    for (let i = 1; i <= runs; i++) {
+      const dir = join(out, `run-${i}`);
+      console.error(`실행 ${i}/${runs} — kf make (${model}) → ${dir}`);
+      const r = spawnSync(process.execPath, [kfBin, "make", request, "--out", dir, "--model", model, "--force", ...pass], { stdio: ["ignore", "ignore", "inherit"] });
+      done.push(measure(dir, r.status ?? 1));
+    }
+    const { lines, diff } = table(done);
+    console.log(`\n「${request}」 × ${runs} (${model})\n`);
+    console.log(lines.join("\n"));
+    const sheets = done.filter((r) => r.sheet).map((r) => r.sheet!);
+    if (sheets.length > 1) {
+      const png = join(out, "sheets.png");
+      const r = spawnSync("ffmpeg", ["-v", "error", "-y", ...sheets.flatMap((s) => ["-i", s]), "-filter_complex", `${sheets.map((_, i) => `[${i}]scale=-2:900[s${i}]`).join(";")};${sheets.map((_, i) => `[s${i}]`).join("")}hstack=${sheets.length}`, png]);
+      if (r.status === 0) console.log(`\n장면 모음 나란히: ${png}`);
+    }
+    const md = [`# kf bench — 「${request}」 × ${runs} (${model})`, "", "```", ...lines.map((l) => l.replace(/\x1b\[[0-9;]*m/g, "")), "```", "", diff.length ? `같아야 하는데 달라진 것: ${diff.join(" · ")}` : "같아야 할 것이 모두 같다.", ""].join("\n");
+    writeFileSync(join(out, "report.md"), md);
+    writeFileSync(join(out, "report.json"), `${JSON.stringify({ request, runs, model, diff, results: done.map((r) => ({ ...r, plan: read(join(r.dir, "plan.json")), scenes: read(join(r.dir, "kf.json"))?.scenes })) }, null, 2)}\n`);
+    console.log(`\n${diff.length ? RED(`다름 ${diff.length}가지: ${diff.join(" · ")}`) : "같아야 할 것이 모두 같다"}\n보고서: ${join(out, "report.md")}`);
+    return diff.length ? 1 : 0;
+  },
+};
+export default cmd;

package/packages/cli/src/commands/blender.ts

@@ -0,0 +1,293 @@
+import { spawn } from "node:child_process";
+import { blenderLibDir, findBlender, hasBlenderLib } from "@kasaframe/gen";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import type { Command } from "../command.ts";
+import { num, parseFlags } from "../command.ts";
+import { openSession } from "../browser.ts";
+import { encoder } from "../ffmpeg.ts";
+import { acquireRenderLock } from "../lock.ts";
+import { fmtTime } from "../out.ts";
+
+// 이 파일은 Blender 를 바깥 프로그램으로 띄우기만 한다(bpy 를 가져오지 않는다). bpy 를 쓰는 헬퍼·샷은 GPL 로 갈라 둔
+// tools/blender 에 있고 npm 묶음에는 없다 — 근거는 tools/blender/README.md.
+
+interface KfJson {
+  fps: number;
+  width: number;
+  height: number;
+  duration: number;
+  beats?: string | null;
+  scenes?: { id: string; from: number; dur: number }[];
+}
+
+function blenderLib(): string {
+  const dir = blenderLibDir();
+  if (!hasBlenderLib(dir)) {
+    throw new Error(
+      `Blender 헬퍼(kfb.py·run.py)가 없다: ${dir}\n` +
+        "헬퍼는 bpy 를 써서 GPL-3.0 으로 갈라 두었고 npm 묶음에는 넣지 않았다 — 레포의 tools/blender 를 받아 KF_BLENDER_LIB=<그 폴더> 로 가리켜라.",
+    );
+  }
+  return dir;
+}
+
+function findProject(given: string | undefined, shot: string): string {
+  if (given) {
+    if (!existsSync(join(resolve(given), "kf.json"))) throw new Error(`kf.json 이 없다: ${resolve(given)}`);
+    return resolve(given);
+  }
+  for (const start of [dirname(shot), process.cwd()]) {
+    for (let d = start; ; d = dirname(d)) {
+      if (existsSync(join(d, "kf.json"))) return d;
+      if (dirname(d) === d) break;
+    }
+  }
+  throw new Error("프로젝트(kf.json)를 못 찾았다 — --project <폴더>. fps·크기·beats.json 을 거기서 읽는다");
+}
+
+const cmd: Command = {
+  summary: "Blender 툰 3D 샷을 프로젝트 fps mp4 로 — 장면엔 <video data-kf-from>",
+  usage: `kf blender <샷.py> [--project <폴더>] [--scene <id> | --from 초 --to 초] [--id 이름]
+  --project   kf.json 이 있는 폴더(기본: 샷 파일이나 지금 폴더에서 위로 찾는다) — fps·크기·beats.json 을 읽는다
+  --scene     그 장면의 시작·끝을 구간으로. 아니면 --from·--to(프로젝트 초, 기본 0..duration)
+  --id        결과 이름(기본 샷 파일 이름) → <프로젝트>/assets/blender/<id>.mp4 + <id>.json
+  --res 100   해상도 %(50 이면 절반 크기로 빨리 — 페이지가 늘려 보인다)
+  --samples 16  EEVEE 샘플
+  --step 1    N 프레임마다 한 장만 찍고 그 사이는 붙든다(2 = 애니메이션 「2코마」, 시간 반)
+  --still 1.2,4.5  그 시각들만 PNG 로(out/blender/<id>/still-<t>.png) — 굽기 전에 그림부터 본다
+  --blend     만든 장면을 out/blender/<id>.blend 로 저장(Blender 에서 열어 보기)
+  --match     앞 장면 마지막 화면·뒤 장면 첫 화면과 그 주인공 상자를 찍어 샷에 넘긴다 — 샷이 kfb.match_start·match_end 로
+              첫·끝 프레임을 그 2D 화면과 같은 구도로 맞추면(투영 일치) 경계가 컷이어도 공간이 이어진다. --scene 과 함께
+  --blender <실행 파일>  기본: BLENDER 환경 변수 → PATH 의 blender → /Applications/Blender*.app (4.3 이상)
+  --keep      다 묶은 뒤에도 PNG 를 out/blender/<id>/ 에 남긴다
+  --no-lock · --lock-wait 900   렌더 잠금(kf render 와 같은 것 — 무거운 일은 한 번에 하나)
+
+샷 스크립트는 tools/blender/kfb.py 헬퍼로 짠다(예: tools/blender/shots/lighthouse.py). update(t) 가 t(프로젝트 초)만 보고 자세를 정하고,
+카메라 열쇠는 S.downbeats·S.drops 같은 beats.json 박에 둔다. 헬퍼 위치는 KF_BLENDER_LIB 로 바꾼다.`,
+  async run(argv) {
+    const { args, opts } = parseFlags(argv);
+    if (!args[0]) {
+      console.error("kf blender: 샷 스크립트를 줘라 — kf blender <샷.py> --project <폴더>");
+      return 2;
+    }
+    const shot = resolve(args[0]);
+    if (!existsSync(shot)) throw new Error(`샷 스크립트가 없다: ${shot}`);
+    const lib = blenderLib();
+    const proj = findProject(typeof opts.project === "string" ? opts.project : undefined, shot);
+    const kf = JSON.parse(readFileSync(join(proj, "kf.json"), "utf8")) as KfJson;
+    const fps = kf.fps;
+    const id = typeof opts.id === "string" ? opts.id : basename(shot).replace(/\.py$/, "");
+
+    let from = num(opts.from, 0);
+    let to = num(opts.to, kf.duration);
+    if (typeof opts.scene === "string") {
+      const sc = kf.scenes?.find((s) => s.id === opts.scene);
+      if (!sc) throw new Error(`장면 ${opts.scene} 이 kf.json 에 없다 — ${(kf.scenes ?? []).map((s) => s.id).join(", ")}`);
+      from = sc.from;
+      to = sc.from + sc.dur;
+    }
+    // 프레임 시각은 어디서나 f / fps — kf render 처럼 [from, to) 에 드는 프레임을 센다. 클립 0 번은 전체 영상의 startF 번 프레임
+    const startF = Math.ceil(from * fps - 1e-6);
+    const endF = Math.min(Math.round(kf.duration * fps), Math.ceil(to * fps - 1e-6));
+    const count = endF - startF;
+    if (count <= 0) throw new Error(`구간이 비었다 (${from}..${to})`);
+    const t0 = startF / fps;
+    const step = Math.max(1, Math.round(num(opts.step, 1)));
+    const res = Math.max(1, Math.min(100, Math.round(num(opts.res, 100))));
+
+    const stills = typeof opts.still === "string" ? opts.still.split(",").map((s) => num(s.trim(), 0)) : null;
+    const frames = stills ? stills.map((t) => Math.max(0, Math.min(count - 1, Math.round((t - t0) * fps)))) : [];
+    if (!stills) for (let f = 0; f < count; f += step) frames.push(f);
+    const names = stills ? stills.map((t) => `still-${fmtTime(t)}`) : frames.map((f) => `f_${String(f).padStart(5, "0")}`);
+
+    const work = join(proj, "out", "blender", id);
+    rmSync(work, { recursive: true, force: true });
+    mkdirSync(work, { recursive: true });
+    const beats = kf.beats ? resolve(proj, kf.beats) : null;
+    const cfg = {
+      shot,
+      from: t0,
+      to: endF / fps,
+      fps,
+      width: kf.width,
+      height: kf.height,
+      res,
+      samples: Math.round(num(opts.samples, 16)),
+      frames,
+      names,
+      out: work,
+      beats: beats && existsSync(beats) ? beats : null,
+      blend: opts.blend ? join(proj, "out", "blender", `${id}.blend`) : null,
+    };
+    const cfgPath = join(proj, "out", "blender", `${id}.cfg.json`);
+
+    const { exe, version } = findBlender(typeof opts.blender === "string" ? opts.blender : undefined, (l) => console.error(`kf blender: ${l}`));
+    const release = opts["no-lock"] ? () => {} : await acquireRenderLock(proj, num(opts["lock-wait"], 900));
+    const started = Date.now();
+    try {
+      const match = opts.match && typeof opts.scene === "string" ? await matchFrames(proj, kf, opts.scene, work) : null;
+      writeFileSync(cfgPath, JSON.stringify({ ...cfg, match }, null, 2));
+      console.error(
+        `Blender ${version.join(".")} · ${relative(process.cwd(), shot)} · ${fmtTime(t0)}–${fmtTime(endF / fps)}초 · ` +
+          `${stills ? `스틸 ${frames.length}장` : `${count}프레임${step > 1 ? ` (${step}장마다 찍음 ${frames.length}장)` : ""}`} · ${Math.round((kf.width * res) / 100)}x${Math.round((kf.height * res) / 100)}`,
+      );
+      const perFrame = await runBlender(exe, lib, cfgPath);
+
+      if (stills) {
+        for (const n of names) console.log(join(work, `${n}.png`));
+        return 0;
+      }
+      const usedFile = join(work, "match-used.json");
+      const used: string[] = existsSync(usedFile) ? JSON.parse(readFileSync(usedFile, "utf8")) : [];
+
+      const outDir = join(proj, "assets", "blender");
+      mkdirSync(outDir, { recursive: true });
+      const mp4 = join(outDir, `${id}.mp4`);
+      const enc = encoder(mp4, fps, "h264");
+      for (let f = 0; f < count; f++) {
+        const held = Math.floor(f / step) * step;
+        await enc.write(readFileSync(join(work, `f_${String(held).padStart(5, "0")}.png`)));
+      }
+      await enc.end();
+
+      // 디코더가 프레임 경계에서 앞 프레임을 집지 않게 반 프레임 앞을 0 으로 잡는다
+      const kfFrom = Number((t0 - 0.5 / fps).toFixed(6));
+      const elapsed = (Date.now() - started) / 1000;
+      const meta = {
+        shot: relative(proj, shot),
+        blender: version.join("."),
+        from: t0,
+        to: endF / fps,
+        fps,
+        frames: count,
+        step,
+        res,
+        samples: cfg.samples,
+        width: Math.round((kf.width * res) / 100),
+        height: Math.round((kf.height * res) / 100),
+        secPerFrame: Number(perFrame.toFixed(3)),
+        elapsedSec: Number(elapsed.toFixed(1)),
+        dataKfFrom: kfFrom,
+        ...(used.length ? { match: { in: used.includes("in"), out: used.includes("out") } } : {}),
+        renderedAt: new Date().toISOString(),
+      };
+      writeFileSync(join(outDir, `${id}.json`), `${JSON.stringify(meta, null, 2)}\n`);
+      // 첫·끝 프레임을 앞뒤 2D 화면과 투영 일치로 맞췄으면 그 장면에 적는다 — 감독은 matched 장면 경계에 이음매를 넣지 않는다(컷으로 이어진다)
+      if (used.length && typeof opts.scene === "string") {
+        const file = join(proj, "kf.json");
+        const doc = JSON.parse(readFileSync(file, "utf8"));
+        const sc = doc.scenes?.find((x: { id: string }) => x.id === opts.scene);
+        if (sc) {
+          sc.matched = true;
+          writeFileSync(file, `${JSON.stringify(doc, null, 2)}\n`);
+        }
+      }
+      if (!opts.keep) rmSync(work, { recursive: true, force: true });
+      console.error(`${count}프레임 · 한 장 ${perFrame.toFixed(2)}초 · 모두 ${Math.round(elapsed)}초`);
+      console.error(`장면에서: <video src="\${ctx.asset("blender/${id}.mp4")}" data-kf-from="${kfFrom}" muted playsinline>`);
+      console.log(mp4);
+      return 0;
+    } finally {
+      release();
+    }
+  },
+};
+export default cmd;
+
+interface Rect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+// 샷 앞 장면의 마지막 프레임·뒤 장면의 첫 프레임과 그 장면이 짚은 주인공([data-kf-hero]) 상자(화면 비율, 왼쪽 위 0).
+// 샷 자리의 장면은 찍지 않으니 샷 영상이 아직 없어도 된다
+async function matchFrames(proj: string, kf: KfJson, sceneId: string, work: string): Promise<{ in?: string; inHero?: Rect; out?: string; outHero?: Rect } | null> {
+  const list = kf.scenes ?? [];
+  const i = list.findIndex((s) => s.id === sceneId);
+  const prev = list[i - 1];
+  const next = list[i + 1];
+  if (i < 0 || (!prev && !next)) return null;
+  const s = await openSession(proj);
+  try {
+    const grab = async (t: number, id: string, file: string) => {
+      await s.first.seek(t);
+      writeFileSync(file, await s.first.capture());
+      const hero = await s.first.page.evaluate((sid) => {
+        const stage = document.getElementById("stage") ?? document.body;
+        const el = document.querySelector(`[data-kf-scene="${sid}"] [data-kf-hero]`);
+        if (!el) return null;
+        const b = stage.getBoundingClientRect();
+        const r = el.getBoundingClientRect();
+        return { x: (r.left - b.left) / b.width, y: (r.top - b.top) / b.height, w: r.width / b.width, h: r.height / b.height };
+      }, id);
+      return { file, hero: hero ?? undefined };
+    };
+    const out: { in?: string; inHero?: Rect; out?: string; outHero?: Rect } = {};
+    if (prev) {
+      const g = await grab(prev.from + prev.dur - 1 / kf.fps, prev.id, join(work, "match-in.png"));
+      out.in = g.file;
+      out.inHero = g.hero;
+    }
+    if (next) {
+      const g = await grab(next.from, next.id, join(work, "match-out.png"));
+      out.out = g.file;
+      out.outHero = g.hero;
+    }
+    console.error(`kf blender: 맞출 화면 — ${prev ? `앞 ${prev.id} 끝` : ""}${prev && next ? " · " : ""}${next ? `뒤 ${next.id} 처음` : ""}`);
+    return out;
+  } finally {
+    await s.close();
+  }
+}
+
+// Blender 를 헤드리스로 돌리고 KFB 줄로 진행을 센다. 평균 한 장 시간(첫 장의 셰이더 컴파일 빼고)을 돌려준다.
+function runBlender(exe: string, lib: string, cfgPath: string): Promise<number> {
+  return new Promise((resolveRun, reject) => {
+    const proc = spawn(exe, ["-b", "--factory-startup", "--python-exit-code", "1", "-P", join(lib, "run.py"), "--", cfgPath], {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const tail: string[] = [];
+    const times: number[] = [];
+    let total = 0;
+    let lastShown = 0;
+    let buf = "";
+    const onData = (d: Buffer) => {
+      buf += d.toString();
+      let nl: number;
+      while ((nl = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, nl).trimEnd();
+        buf = buf.slice(nl + 1);
+        tail.push(line);
+        if (tail.length > 60) tail.shift();
+        const m = /^KFB (start|frame) (\d+)(?: (\d+) ([\d.]+))?/.exec(line);
+        if (!m) continue;
+        if (m[1] === "start") {
+          total = Number(m[2]);
+          continue;
+        }
+        times.push(Number(m[4]));
+        const i = Number(m[2]);
+        if (i === total || Date.now() - lastShown > 5000) {
+          lastShown = Date.now();
+          const steady = times.length > 1 ? times.slice(1) : times;
+          const avg = steady.reduce((a, b) => a + b, 0) / steady.length;
+          console.error(`  ${i}/${total} · 한 장 ${avg.toFixed(2)}초 · 남은 ~${Math.ceil(((total - i) * avg) / 60)}분`);
+        }
+      }
+    };
+    proc.stdout.on("data", onData);
+    proc.stderr.on("data", onData);
+    proc.on("error", (e) => reject(new Error(`Blender 를 못 띄웠다: ${e.message}`)));
+    proc.on("close", (code) => {
+      if (code === 0 && times.length === total && total > 0) {
+        const steady = times.length > 1 ? times.slice(1) : times;
+        resolveRun(steady.reduce((a, b) => a + b, 0) / steady.length);
+      } else {
+        reject(new Error(`Blender 가 실패했다 (종료 ${code}, ${times.length}/${total}장)\n${tail.join("\n")}`));
+      }
+    });
+  });
+}

package/packages/cli/src/commands/check.ts

@@ -0,0 +1,25 @@
+import { resolve } from "node:path";
+import type { Command } from "../command.ts";
+import { parseFlags } from "../command.ts";
+import { acquireRenderLock } from "../lock.ts";
+import { run, usage } from "@kasaframe/check";
+
+// 검사도 크롬으로 영상 전체를 훑는 무거운 일이라 렌더와 같은 잠금을 잡는다 — 한 기계에서 하나씩
+const cmd: Command = {
+  summary: "검사 — 멈춤·빈 화면·화면 글(undefined·두부)·화면 밖 글·대비·결정성·박 경계·움직임 규칙",
+  usage: `${usage}\n  --no-lock               렌더 잠금(.render-lock) 없이 — 짧은 구간 시험용\n  --captions on|off|fit   화면 자막을 켜고(끄고) 훑는다 — kf render --captions 로 구운 판과 같은 화면`,
+  async run(argv) {
+    // --captions 는 페이지 질의로 넘긴다(mountProject 가 읽는다)
+    const at = argv.indexOf("--captions");
+    if (at >= 0) argv = [...argv.slice(0, at), "--query", `captions=${argv[at + 1]}`, ...argv.slice(at + 2)];
+    const { args, opts } = parseFlags(argv);
+    if (opts["no-lock"] || !args[0]) return run(argv.filter((a) => a !== "--no-lock"));
+    const release = await acquireRenderLock(resolve(args[0]), 900);
+    try {
+      return await run(argv);
+    } finally {
+      release();
+    }
+  },
+};
+export default cmd;

package/packages/cli/src/commands/direct.ts

@@ -0,0 +1,210 @@
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, readFileSync, rmSync } from "node:fs";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { build, checkContent, type Content, layout, type Problem, type Report } from "@kasaframe/director";
+import { questionsText } from "@kasaframe/gen";
+import { parseDuration } from "@kasaframe/plan";
+import { type Command, num, parseFlags } from "../command.ts";
+
+const kfBin = fileURLToPath(new URL("../kf.ts", import.meta.url));
+// 검사가 떨어뜨려도 패턴 탓이 아닌 규칙 — 장면 경계(시간표)·생성 자산·자막 판
+const NOT_PATTERN = /^(beat\.|asset\.|caption\.)/;
+// 생성 능력 질문의 답 — kf make 로 그대로 넘긴다
+const PASS = ["image", "video", "blender", "voice", "music", "allow", "series", "theme", "purpose"];
+
+const cmd: Command = {
+  summary: "감독 모드 — content.json(무엇을 보일지)에서 장면 문법·전환·바탕을 골라 장면 파일을 조립(LLM 없이)",
+  usage: `kf direct <content.json|프로젝트 폴더> [--out 폴더] [--seed 글] [--series id] [--voice …] [--music …]
+  content.json 의 장면마다(type·칸·say·source) 감독이 검증된 장면 문법(패턴) 후보에 점수를 매겨 — 테마 궁합·용도·곡 구간 에너지(벌스·후렴·드롭)·
+  앞뒤 장면과 계열·카메라 안 겹치기 — 씨앗 고정 난수로 고르고, 패턴 매개변수를 내용으로 채워 장면 파일을 쓴다. 장면 사이 이음매(3D 전환)도
+  감독이 고른다(기본 dive, 같은 전환 연속 금지, 2D↔3D 경계는 공간 잇기). 같은 content.json·시리즈·씨앗이면 장면 파일이 바이트까지 같다.
+
+  폴더가 아직 없으면 content.json 의 request(없으면 title)로 kf make 뼈대(용도·테마·목소리·곡 묻기 포함)를 먼저 세운다 — 기본 폴더는 content.json 옆 같은 이름.
+  순서: 칸 검사 → 시간표(이음매 포함) → kf narrate(say 를 읽혀 장면 길이를 목소리에) → 패턴 고르기·장면 파일 → kf check(떨어진 장면만 다음 후보로, --retries 번)
+
+  --seed       다른 고름을 본다(같은 씨앗이면 늘 같은 그림). 기본 content.json 의 seed, 없으면 0
+  --scenes a,b 그 장면만 다시 짓는다 — 시간표·다른 장면 파일·이음매는 바이트까지 그대로(조각 렌더가 바뀐 장면만 다시 굽게)
+  --pattern a=<패턴 id>[,b=…]   사람이 고른 후보(director.json 의 order) · --scene-seed a=<글>[,…] 그 장면만 다른 그림
+               고른 값은 director.json 의 pinned 에 남아 다음 kf direct 도 지킨다
+  진행 줄(stderr): 「장면 <id>: 쓰는 중」·「장면 <id>: 씀」·「장면 <id>: 실패 <까닭>」(굽기·검사까지 끝난 「끝」은 작업실·render 몫)
+  --no-narrate 목소리 없이 어림 길이로 · --no-check 검사 없이 · --retries N(기본 2) · --finish 다 되면 kf make --finish(렌더·표지·자막)
+  --no-lock    검사 고리만 렌더 잠금 없이(남의 긴 굽기 뒤에서 기다리지 않게) — --finish 의 굽기는 그대로 잠금
+  --image · --video · --blender · --voice · --music · --allow · --yes · --no-gen   뼈대를 세울 때 묻기 답(kf make 와 같다)
+  결과: kf.json(장면·패턴·전환) · scenes/*.ts · captions.json · director.json(장면마다 후보 점수·까닭·떨어진 것)`,
+  async run(argv) {
+    const { args, opts } = parseFlags(argv);
+    const str = (k: string) => (typeof opts[k] === "string" ? (opts[k] as string) : undefined);
+    const target = args[0] ? resolve(args[0]) : undefined;
+    if (!target || !existsSync(target)) {
+      console.error("kf direct: content.json 이나 그것이 든 프로젝트 폴더가 필요하다 — kf direct --help");
+      return 2;
+    }
+    const isDir = !extname(target) || existsSync(join(target, "kf.json"));
+    const file = isDir ? join(target, "content.json") : target;
+    if (!existsSync(file)) {
+      console.error(`kf direct: ${file} 가 없다 — 지시서(MAKE.md)의 「content.json 꼴」대로 먼저 쓴다`);
+      return 2;
+    }
+    const dir = isDir ? target : existsSync(join(dirname(target), "kf.json")) ? dirname(target) : resolve(str("out") ?? join(dirname(target), basename(target, extname(target))));
+
+    let raw: unknown;
+    try {
+      raw = JSON.parse(readFileSync(file, "utf8"));
+    } catch (e) {
+      console.error(`kf direct: ${file} 가 JSON 이 아니다 — ${e instanceof Error ? e.message : e}`);
+      return 1;
+    }
+    const checked = checkContent(raw);
+    const say = (p: Problem) => `  ${p.at}: ${p.msg}`;
+    if (checked.warnings.length) console.error(`content.json 고친 곳·볼 곳 ${checked.warnings.length}:\n${checked.warnings.map(say).join("\n")}`);
+    if (checked.errors.length) {
+      console.error(`kf direct: content.json 칸이 틀렸다 ${checked.errors.length}곳 — 고치고 다시:\n${checked.errors.map(say).join("\n")}`);
+      return 1;
+    }
+    const content: Content = checked.content;
+
+    // 뼈대 — 용도·테마·목소리·곡 묻기는 kf make 와 같은 길을 지난다
+    if (!existsSync(join(dir, "kf.json"))) {
+      const req = content.request ?? content.title;
+      const request = content.duration && parseDuration(req) === undefined ? `${req} ${content.duration}초` : req;
+      const make = [kfBin, "make", request, "--out", dir, "--model", "claude-code", "--title", content.title];
+      for (const [k, v] of [["series", content.series], ["purpose", content.purpose], ["theme", content.theme], ["voice", content.voice], ["music", content.music]] as const) if (v && str(k) === undefined) make.push(`--${k}`, v);
+      for (const k of PASS) if (str(k)) make.push(`--${k}`, str(k)!);
+      for (const k of ["yes", "no-gen"]) if (opts[k]) make.push(`--${k}`);
+      const r = spawnSync(process.execPath, make, { stdio: ["inherit", "inherit", "inherit"] });
+      if (r.status !== 0) return r.status ?? 1;
+    } else if (PASS.some((k) => str(k)) && planAsks(dir).length) {
+      const flags = PASS.filter((k) => str(k)).flatMap((k) => [`--${k}`, str(k)!]);
+      const r = spawnSync(process.execPath, [kfBin, "make", "--answer", dir, ...flags], { stdio: "inherit" });
+      if (r.status !== 0) return r.status ?? 1;
+    }
+    const open = planAsks(dir);
+    if (open.length) {
+      console.error(`kf direct: 만들기 전에 정할 것이 ${open.length}가지 — 사람에게 묻고 플래그로 답해 다시 부른다\n\n${questionsText(open as never)}\n\n  kf direct ${args[0]} ${open.map((q) => `${q.flag} <값>`).join(" ")}`);
+      return 3;
+    }
+    if (resolve(file) !== join(dir, "content.json")) copyFileSync(file, join(dir, "content.json"));
+
+    const only = str("scenes")?.split(",").map((x) => x.trim()).filter(Boolean);
+    const pins: Record<string, { pattern?: string; seed?: string }> = {};
+    for (const [flag, k] of [["pattern", "pattern"], ["scene-seed", "seed"]] as const)
+      for (const pair of (str(flag) ?? "").split(",").filter(Boolean)) {
+        const eq = pair.indexOf("=");
+        if (eq < 1) {
+          console.error(`kf direct: --${flag} 는 <장면>=<값> — "${pair}"`);
+          return 2;
+        }
+        (pins[pair.slice(0, eq)] ??= {})[k] = pair.slice(eq + 1);
+      }
+    // 고른 장면만이면 시간표를 다시 놓지 않는다 — 다른 장면의 시각이 한 프레임도 안 움직이게
+    if (!only) {
+      const { seams } = layout(dir, content, { keepTiming: !!opts["no-narrate"] });
+      console.error(`시간표: 장면 ${content.scenes.length} + 이음매 ${seams}`);
+    }
+    if (!opts["no-narrate"]) {
+      const hasSay = content.scenes.some((s) => s.say?.trim());
+      const n = [kfBin, "narrate", dir];
+      const voice = str("voice") ?? content.voice ?? (hasSay ? undefined : "none");
+      if (voice) n.push("--voice", voice);
+      if (str("music") ?? content.music) n.push("--music", (str("music") ?? content.music)!);
+      const r = spawnSync(process.execPath, n, { stdio: ["inherit", "inherit", "inherit"] });
+      if (r.status !== 0) {
+        console.error("kf direct: 내레이션(kf narrate)에서 멈췄다 — 위 보기대로 답하거나 --no-narrate 로 어림 길이");
+        return r.status ?? 1;
+      }
+    }
+
+    const seed = str("seed");
+    const log = (l: string) => console.error(l);
+    let report: Report;
+    try {
+      report = await build(dir, content, { seed, only, pins, log });
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      for (const id of only ?? []) console.error(`장면 ${id}: 실패 ${msg}`);
+      console.error(`kf direct: ${msg}`);
+      return 1;
+    }
+    print(dir, report);
+    let code = 0;
+    if (!opts["no-check"]) {
+      const retries = num(opts.retries, 2);
+      for (let round = 0; ; round++) {
+        // 옛 결과를 치우고 돌린다 — 검사가 돌지 못하고 끝나면 옛 check.json 을 이번 결과로 읽게 된다
+        const report_ = join(dir, "out", "check.json");
+        const fresh = () => {
+          rmSync(report_, { force: true });
+          return spawnSync(process.execPath, [kfBin, "check", dir, ...(opts["no-lock"] ? ["--no-lock"] : [])], { encoding: "utf8" });
+        };
+        let r = fresh();
+        // 남의 긴 굽기가 잠금을 쥐면 검사가 15분 기다리다 물러난다 — 한 시간까지 다시 줄을 선다
+        for (let wait = 0; /잠금을 못 얻었다/.test(r.stderr ?? "") && wait < 4; wait++) {
+          console.error("kf check: 다른 굽기가 잠금을 쥐고 있어 다시 기다린다");
+          r = fresh();
+        }
+        code = r.status ?? 1;
+        if (code === 0) {
+          console.log("kf check 통과");
+          break;
+        }
+        if (code !== 1 || !existsSync(report_)) {
+          console.error(`kf check 를 못 돌렸다(종료 ${code}) — ${`${r.stderr ?? ""}`.trim().split("\n").slice(-3).join(" / ")}`);
+          break;
+        }
+        const blame = blameScenes(dir, report);
+        console.error(`kf check 오류 — ${blame.lines.join(" · ")}`);
+        if (round >= retries || (!Object.keys(blame.failed).length && !Object.keys(blame.seamFailed).length)) break;
+        try {
+          report = await build(dir, content, { seed, failed: blame.failed, seamFailed: blame.seamFailed, log });
+        } catch (e) {
+          console.error(`kf direct: ${e instanceof Error ? e.message : e}`);
+          break;
+        }
+        console.error(`다시 지음(${round + 1}/${retries}) — ${[...Object.entries(blame.failed), ...Object.entries(blame.seamFailed)].map(([id]) => `${id} → ${report.scenes.find((s) => s.id === id)?.pattern ?? report.scenes.find((s) => s.id === id)?.transition}`).join(" · ")}`);
+      }
+      if (code !== 0) console.error(`kf check 가 아직 떨어진다 — ${dir}/out/check.json 을 보고 content.json 을 고치거나 --seed 를 바꿔 다시`);
+    }
+    if (opts.finish && code === 0) {
+      const r = spawnSync(process.execPath, [kfBin, "make", "--finish", dir], { stdio: "inherit" });
+      return r.status ?? 1;
+    }
+    if (!opts.finish) console.log(`\n다음: kf look ${dir} 로 장면 모음을 보고 → kf make --finish ${dir}`);
+    return code;
+  },
+};
+export default cmd;
+
+function planAsks(dir: string): { id: string; flag: string }[] {
+  const p = join(dir, "plan.json");
+  return existsSync(p) ? (JSON.parse(readFileSync(p, "utf8")).asks ?? []) : [];
+}
+
+function print(dir: string, r: Report): void {
+  console.log(`${dir} — 씨앗 ${r.seed} · ${r.purpose} ${r.aspect}${r.theme ? ` · 테마 ${r.theme}` : ""}`);
+  for (const s of r.scenes) {
+    const what = s.transition ? `이음매 ${s.transition}` : s.custom ? `custom(${s.custom === "kept" ? "있는 파일" : "뼈대 — 직접 쓴다"})` : `${s.pattern}${s.energy ? ` · ${s.energy}` : ""}${s.attempt ? ` · ${s.attempt + 1}번째 후보` : ""}`;
+    console.log(`  ${s.from.toFixed(2).padStart(6)}–${(s.from + s.dur).toFixed(2).padEnd(6)} ${s.id.padEnd(10)} ${(s.type ?? "").padEnd(12)} ${what}`);
+  }
+}
+
+// out/check.json 의 오류를 시각으로 장면에 묶는다 — 패턴 장면은 그 패턴을, 이음매는 그 전환을 떨어뜨린다
+function blameScenes(dir: string, r: Report): { failed: Record<string, string[]>; seamFailed: Record<string, string[]>; lines: string[] } {
+  const p = join(dir, "out", "check.json");
+  const failed: Record<string, string[]> = {};
+  const seamFailed: Record<string, string[]> = {};
+  const lines: string[] = [];
+  if (!existsSync(p)) return { failed, seamFailed, lines };
+  const findings = (JSON.parse(readFileSync(p, "utf8")).findings ?? []) as { rule: string; severity: string; from: number }[];
+  for (const f of findings) {
+    if (f.severity !== "error") continue;
+    const s = r.scenes.find((x) => f.from >= x.from - 1e-6 && f.from < x.from + x.dur) ?? r.scenes.at(-1)!;
+    lines.push(`${s.id} ${f.rule}`);
+    if (NOT_PATTERN.test(f.rule)) continue;
+    if (s.pattern) failed[s.id] = [...new Set([...(failed[s.id] ?? []), s.pattern])];
+    else if (s.transition) seamFailed[s.id] = [...new Set([...(seamFailed[s.id] ?? []), s.transition])];
+  }
+  const count = new Map<string, number>();
+  for (const l of lines) count.set(l, (count.get(l) ?? 0) + 1);
+  return { failed, seamFailed, lines: [...count].map(([l, n]) => (n > 1 ? `${l}×${n}` : l)) };
+}