kasaframe 0.1.1 → 0.1.3

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

@@ -1,12 +1,13 @@
-import { spawn, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+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";
-import { repoRoot } from "../serve.ts";
 
 // 이 파일은 Blender 를 바깥 프로그램으로 띄우기만 한다(bpy 를 가져오지 않는다). bpy 를 쓰는 헬퍼·샷은 GPL 로 갈라 둔
 // tools/blender 에 있고 npm 묶음에는 없다 — 근거는 tools/blender/README.md.
@@ -20,11 +21,9 @@ interface KfJson {
   scenes?: { id: string; from: number; dur: number }[];
 }
 
-const MIN = [4, 3]; // Grease Pencil v3(라인아트가 일반 모디파이어)가 4.3 부터
-
 function blenderLib(): string {
-  const dir = process.env.KF_BLENDER_LIB ? resolve(process.env.KF_BLENDER_LIB) : join(repoRoot, "tools", "blender");
-  if (!existsSync(join(dir, "run.py")) || !existsSync(join(dir, "kfb.py"))) {
+  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=<그 폴더> 로 가리켜라.",
@@ -33,46 +32,6 @@ function blenderLib(): string {
   return dir;
 }
 
-function candidates(given?: string): string[] {
-  const out: string[] = [];
-  if (given) out.push(given);
-  if (process.env.BLENDER) out.push(process.env.BLENDER);
-  const which = spawnSync(process.platform === "win32" ? "where" : "which", ["blender"], { encoding: "utf8" });
-  if (which.status === 0) out.push(...which.stdout.split(/\r?\n/).filter(Boolean));
-  if (process.platform === "darwin") {
-    const apps = existsSync("/Applications") ? readdirSync("/Applications").filter((n) => /^Blender.*\.app$/.test(n)) : [];
-    // 이름에 판 번호를 붙여 여러 개 깔아 둔 기계면 높은 판부터
-    apps.sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
-    out.push(...apps.map((a) => `/Applications/${a}/Contents/MacOS/Blender`));
-  }
-  if (process.platform === "win32") {
-    const base = "C:\\Program Files\\Blender Foundation";
-    if (existsSync(base)) {
-      const dirs = readdirSync(base).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
-      out.push(...dirs.map((d) => join(base, d, "blender.exe")));
-    }
-  }
-  return out;
-}
-
-function findBlender(given?: string): { exe: string; version: number[] } {
-  const tried: string[] = [];
-  for (const exe of candidates(given)) {
-    if (tried.includes(exe)) continue;
-    tried.push(exe);
-    const r = spawnSync(exe, ["--version"], { encoding: "utf8", timeout: 30_000 });
-    const m = /Blender (\d+)\.(\d+)(?:\.(\d+))?/.exec(r.stdout ?? "");
-    if (r.status !== 0 || !m) continue;
-    const version = [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)];
-    if (version[0] < MIN[0] || (version[0] === MIN[0] && version[1] < MIN[1])) {
-      console.error(`kf blender: ${exe} 는 ${version.join(".")} — ${MIN.join(".")} 이상이 필요해 건너뛴다`);
-      continue;
-    }
-    return { exe, version };
-  }
-  throw new Error(`Blender ${MIN.join(".")} 이상을 못 찾았다 — --blender <실행 파일> 또는 BLENDER=<경로>. 본 곳: ${tried.join(", ") || "(없음)"}`);
-}
-
 function findProject(given: string | undefined, shot: string): string {
   if (given) {
     if (!existsSync(join(resolve(given), "kf.json"))) throw new Error(`kf.json 이 없다: ${resolve(given)}`);
@@ -98,6 +57,8 @@ const cmd: Command = {
   --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 와 같은 것 — 무거운 일은 한 번에 하나)
@@ -160,12 +121,13 @@ const cmd: Command = {
       blend: opts.blend ? join(proj, "out", "blender", `${id}.blend`) : null,
     };
     const cfgPath = join(proj, "out", "blender", `${id}.cfg.json`);
-    writeFileSync(cfgPath, JSON.stringify(cfg, null, 2));
 
-    const { exe, version } = findBlender(typeof opts.blender === "string" ? opts.blender : undefined);
+    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)}`,
@@ -176,6 +138,8 @@ const cmd: Command = {
         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 });
@@ -205,9 +169,20 @@ const cmd: Command = {
         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>`);
@@ -220,6 +195,54 @@ const cmd: Command = {
 };
 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) => {

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)) };
+}

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

@@ -1,8 +1,9 @@
+import { capabilities } from "@kasaframe/gen";
 import { readFileSync } from "node:fs";
 import { arch, platform } from "node:os";
 import { join } from "node:path";
 import type { Command } from "../command.ts";
-import { checks, report } from "../deps.ts";
+import { checks, pad, report } from "../deps.ts";
 import { repoRoot } from "../serve.ts";
 
 const cmd: Command = {
@@ -15,6 +16,13 @@ const cmd: Command = {
     const list = await checks();
     report(list);
     const missing = list.filter((c) => c.required && !c.ok);
+    console.log("\n생성 능력(kf make 가 쓰는 것 — 없으면 kf make 가 만들기 전에 묻는다. 키는 값 없이 유무만)");
+    for (const c of await capabilities({ probe: true })) {
+      const ok = c.providers.filter((p) => p.ready);
+      console.log(`  ${pad(ok.length ? "ok" : "없음", 4)}  ${pad(c.label, 30)}${c.best ? `권장 ${c.best.id}${c.best.unitUsd ? ` $${c.best.unitUsd.toFixed(3)}/${c.best.unit}` : " 0원"}` : "쓸 수 있는 것 없음"}${ok.length > 1 ? ` · 그 밖 ${ok.filter((p) => p !== c.best).map((p) => p.id).join(" ")}` : ""}`);
+      for (const p of c.providers.filter((x) => !x.ready && x.fix)) console.log(`  ${pad("", 36)}${p.id}: ${p.detail} → ${p.fix}`);
+      for (const p of ok.filter((x) => x.restrict)) console.log(`  ${pad("", 36)}${p.id} 제한: ${p.restrict}`);
+    }
     console.log(missing.length ? `\n렌더에 필요한 것이 ${missing.length}개 없다 — 위 → 대로 깔고 다시 kf doctor` : "\n렌더 준비 됨 — kf new <폴더> --template shorts 부터");
     return missing.length ? 1 : 0;
   },

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

@@ -1,6 +1,6 @@
 import { writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { DEFAULT_EYES, formatLook, look, lookSheet } from "@kasaframe/plan";
+import { DEFAULT_EYES, formatLook, look, lookSheet, premiumBlock } from "@kasaframe/plan";
 import { type Command, parseFlags } from "../command.ts";
 
 const cmd: Command = {
@@ -14,7 +14,8 @@ const cmd: Command = {
   --vision-model  그림을 못 보는 세션(Claude Code 를 OG 로 딥시크 같은 모델에 붙이면 OG /v1/messages 가 그림을 버린다)용.
                   그 모델이 OG chat/completions 로 장면 모음을 보고 장면별 글 보고(한 번에 1센트 안팎) — JSON 은 out/look.json,
                   문제 장면이 있으면 종료 코드 1
-  --ask           --vision-model 에게 따로 물을 것`,
+  --ask           --vision-model 에게 따로 물을 것
+  --allow-premium Opus·GPT 계열 모델을 푼다(KF_ALLOW_PREMIUM=1 과 같다) — 없으면 부르기 전에 막는다`,
   async run(argv) {
     const { args, opts } = parseFlags(argv);
     if (!args[0]) {
@@ -29,6 +30,12 @@ const cmd: Command = {
       console.log(opts.json ? JSON.stringify(s, null, 2) : `장면 모음: ${s.sheet}\n확인표:   ${s.checklist}\n— 장면 ${s.scenes}개. 그림을 Read 로 직접 보고 확인표대로 고친다`);
       return 0;
     }
+    if (opts["allow-premium"]) process.env.KF_ALLOW_PREMIUM = "1";
+    const why = premiumBlock(model);
+    if (why) {
+      console.error(`kf look: ${why}`);
+      return 2;
+    }
     const r = await look(target, { ask: typeof opts.ask === "string" ? opts.ask : undefined, model });
     const out = /\.(mp4|mov|webm|m4v)$/i.test(target) ? join(dirname(target), "look.json") : join(target, "out", "look.json");
     writeFileSync(out, `${JSON.stringify(r, null, 2)}\n`);

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

@@ -2,6 +2,8 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { type Question, WAIT } from "@kasaframe/gen";
+import { install, type Missing } from "@kasaframe/jizura/install";
 import { parseLyrics, toLrc } from "@kasaframe/jizura/lyrics";
 import { type Command, num, parseFlags } from "../command.ts";
 import { pyVenv, venvPython } from "../deps.ts";
@@ -47,6 +49,46 @@ export function setupLyrics(): boolean {
   return (existsSync(venvPython(dir)) || step(py, ["-m", "venv", dir])) && step(venvPython(dir), ["-m", "pip", "install", "-r", requirements]);
 }
 
+/** 가사 층이 처음 쓰는 글꼴을 못 받았을 때 — 다른 글꼴로 대신 그리지 않고 묻는다. 답은 kf lyrics use 가 kf.json 에 적는다 */
+export function fontsQuestion(missing: Missing[]): Question {
+  const stand = missing.every((m) => m.stand);
+  return {
+    id: "lyrics", cap: "lyrics", header: "가사 글꼴", flag: `kf lyrics use ${missing[0].project ?? "<폴더>"}`, missing: true, default: WAIT, skip: "words",
+    ask: `가사 층이 처음 쓰는 글꼴 ${missing.map((m) => m.family).join("·")} 을 못 받았다(${missing[0].reason}) — 다른 글꼴로 대신 그리지 않고 멈췄다`,
+    choices: [
+      { value: WAIT, label: "받고 다시", note: "지금 다시 받아 본다(kf setup jizura 와 같다 — 막힌 망이면 KF_JIZURA_FONTS_URL 에 google/fonts 거울) → 같은 명령을 다시" },
+      ...(stand ? [{ value: "builtin", label: "내장 글꼴로", note: `${missing.map((m) => `${m.family} → ${m.stand}`).join(", ")} — 플랜·컷은 그대로, 글자 모양만 바뀐다` }] : []),
+      { value: "words", label: "가사 층 없이 낱말로", note: "JIZURA 레이아웃·효과 없이 부른 낱말을 DOM 글로" },
+    ],
+  };
+}
+
+// kf.json "lyrics" — 가사 층이 읽는다(layer.ts lyricsMode). wait 는 지금 받아 보고 되면 원래대로(jizura)
+async function use(dir: string | undefined, value: string | undefined): Promise<number> {
+  const kfPath = dir ? join(resolve(dir), "kf.json") : "";
+  if (!dir || !existsSync(kfPath) || !value || ![WAIT, "jizura", "builtin", "words"].includes(value)) {
+    console.error("kf lyrics use <폴더> wait|builtin|words|jizura");
+    return 2;
+  }
+  if (value === WAIT) {
+    const lyricsPath = join(resolve(dir), "lyrics.json");
+    const lang = existsSync(lyricsPath) && JSON.parse(readFileSync(lyricsPath, "utf8")).lang === "ja" ? "ja" : "ko";
+    try {
+      await install([lang]);
+    } catch (err) {
+      console.error(`kf lyrics use: 아직 못 받는다 — ${err instanceof Error ? err.message : err}`);
+      return 1;
+    }
+    value = "jizura";
+  }
+  const kf = JSON.parse(readFileSync(kfPath, "utf8"));
+  if (value === "jizura") delete kf.lyrics;
+  else kf.lyrics = value;
+  writeFileSync(kfPath, `${JSON.stringify(kf, null, 2)}\n`);
+  console.log(`${kfPath} lyrics: ${value} — 같은 명령을 다시`);
+  return 0;
+}
+
 function writeLrc(json: string, lrcPath: string): void {
   const lyrics = parseLyrics(JSON.parse(readFileSync(json, "utf8")));
   writeFileSync(lrcPath, toLrc(lyrics));
@@ -56,15 +98,19 @@ const cmd: Command = {
   summary: "가사 — 공식 가사에 줄·어절 시각을 붙여 lyrics.json + LRC (보컬 분리 + whisper 강제 정렬)",
   usage: `kf lyrics align <곡> --text 공식가사.txt [--lang ko|ja] [--out lyrics.json] [--from 초 --duration 초] [--model large-v3-turbo] [--vocals]
 kf lyrics lrc <lyrics.json> [--out x.lrc]
+kf lyrics use <폴더> wait|builtin|words|jizura
 
   align  글자는 공식 가사(한 줄 = 가사 한 줄)가 정본이고 시각만 붙인다. 곡의 일부만 쓰면 --from·--duration(시각은 --from 을 0 으로 —
          beats.json 과 같다). 보컬만 있는 소리면 --vocals(분리를 건너뛴다). 옆에 같은 이름 .lrc 도 쓴다(2.5초 넘는 빈 자리는 [間奏]).
          MMS 강제 정렬은 가중치가 비상업(CC-BY-NC)이라 쓰지 않는다. 깔기: kf setup lyrics (KF_LYRICS_PYTHON 으로 바꿀 수 있다)
          모델·장치: --model(기본 large-v3-turbo) · WHISPER_DEVICE(기본 cpu — mps 는 정렬에서 깨질 때가 있다)
-  lrc    lyrics.json → LRC(JIZURA·노래방 형식)`,
+  lrc    lyrics.json → LRC(JIZURA·노래방 형식)
+  use    가사 층 글꼴을 처음 쓰다 못 받았을 때 고른 답을 kf.json 에 — wait(지금 다시 받기) · builtin(못 받은 얼굴을 내장 글꼴로)
+         · words(가사 층 없이 낱말로) · jizura(원래대로). 페이지 주소 ?lyrics= 가 그 판만 덮는다`,
   async run(argv) {
     const { args, opts } = parseFlags(argv);
     const [sub, input] = args;
+    if (sub === "use") return use(input, args[2]);
     if (sub === "lrc") {
       if (!input || !existsSync(input)) {
         console.error("kf lyrics lrc: lyrics.json 경로가 필요하다");