kasaframe 0.1.1 → 0.1.4

package/packages/cli/src/cells.ts

@@ -0,0 +1,227 @@
+// 테마 견본 칸 — 같은 문장 한 장면(쇼츠 첫 장면 hook-number)을 테마·변주마다 찍은 한 장. kf theme sheet·vary 와 kf make 테마 질문이 같이 쓴다.
+// 변주는 세계 기본 판 표준 장면을 한 번 지어 두고 style.json 만 갈아 찍는다 — 감독이 고른 장면 문법이 같아야 겉모습만 견줄 수 있다.
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { KfStyle } from "@kasaframe/core";
+import { cellPath, loadTheme, themeDims, themesDir, type Theme } from "@kasaframe/themes";
+import { launch } from "./browser.ts";
+
+const kfBin = new URL("./kf.ts", import.meta.url).pathname;
+const kf = (...a: string[]) => spawnSync(process.execPath, [kfBin, ...a], { encoding: "utf8" });
+const tail = (r: { stdout?: string; stderr?: string }, n = 3) => `${r.stderr ?? ""}${r.stdout ?? ""}`.trim().split("\n").slice(-n).join(" / ");
+
+export const SAMPLE = {
+  title: "kasaframe",
+  request: "테마 견본 — 같은 문장을 테마마다",
+  scenes: [{ id: "hook", type: "hook-number", value: 57, unit: "×", label: "KV 캐시가 이만큼 작아진다", source: "DeepSeek-V2 기술 보고서", dur: 4 }],
+};
+
+export interface Frame {
+  width: number;
+  height: number;
+  safe: { top: number; bottom: number; left: number; right: number };
+  /** 장면 끝 프레임 — 움직임이 다 앉은 자리 */
+  at: number;
+  dur: number;
+  pattern?: string;
+}
+
+const readJson = (p: string) => JSON.parse(readFileSync(p, "utf8"));
+
+function frameOf(dir: string): Frame {
+  const p = readJson(join(dir, "kf.json"));
+  const scene = p.scenes.find((x: { id: string }) => x.id === SAMPLE.scenes[0].id);
+  const d = existsSync(join(dir, "director.json")) ? readJson(join(dir, "director.json")) : null;
+  return { width: p.width, height: p.height, safe: p.safeArea, at: +(scene.from + scene.dur - 1 / p.fps).toFixed(4), dur: scene.dur, pattern: d?.scenes?.find((s: { id: string }) => s.id === scene.id)?.pattern };
+}
+
+/** 표준 장면 프로젝트 — 감독이 짓고, check 면 검사 고리까지(떨어진 패턴은 감독이 다음 후보로). 1 = 다시 지어도 검사 오류가 남음 */
+export function standardProject(theme: string, dir: string, o: { check: boolean }): { status: number; why: string; frame: Frame | null } {
+  rmSync(dir, { recursive: true, force: true });
+  let r = kf("new", dir, "--template", "shorts", "--theme", theme, "--title", SAMPLE.title, "--series", "none");
+  if (r.status === 0) {
+    writeFileSync(join(dir, "content.json"), `${JSON.stringify(SAMPLE, null, 2)}\n`);
+    r = kf("direct", dir, "--no-narrate", "--no-lock", ...(o.check ? [] : ["--no-check"]));
+  }
+  const built = r.status === 0 || r.status === 1;
+  return { status: r.status ?? 1, why: r.status === 0 ? "" : tail(r), frame: built && existsSync(join(dir, "director.json")) ? frameOf(dir) : null };
+}
+
+/** 지어 둔 표준 장면에 테마(변주) style 만 갈아 끼운 복사본 — 장면 파일·패턴은 그대로 */
+export function restyle(from: string, dir: string, id: string, style: KfStyle = loadTheme(id).style): void {
+  rmSync(dir, { recursive: true, force: true });
+  cpSync(from, dir, { recursive: true, filter: (src) => !src.startsWith(join(from, "out")) });
+  const was = readJson(join(from, "style.json"));
+  style = structuredClone(style);
+  // 틀의 움직임 규칙은 kf new 가 덮은 그대로 — 변주가 바꾸는 건 빠르기(durations)뿐
+  style.motion = { ...was.motion, ...(style.motion.durations ? { durations: style.motion.durations } : {}) };
+  writeFileSync(join(dir, "style.json"), `${JSON.stringify(style, null, 2)}\n`);
+  const p = readJson(join(dir, "kf.json"));
+  writeFileSync(join(dir, "kf.json"), `${JSON.stringify({ ...p, theme: id }, null, 2)}\n`);
+}
+
+export interface Verdict {
+  ok: boolean;
+  /** 오류 규칙·한 줄 */
+  errors: string[];
+  ran: boolean;
+}
+
+/** kf check — 잠금은 부르는 쪽이 쥔다. from·to 를 주면 그 구간만(입체 세계는 무거워 끝 구간만) */
+export function checkProject(dir: string, win?: { from: number; to: number }): Verdict {
+  const file = join(dir, "out", "check.json");
+  rmSync(file, { force: true });
+  const r = kf("check", dir, "--no-lock", "--tabs", "2", ...(win ? ["--from", String(win.from), "--to", String(win.to)] : []));
+  if (!existsSync(file)) return { ok: false, ran: false, errors: [`kf check 를 못 돌렸다(종료 ${r.status}) — ${tail(r)}`] };
+  const rep = readJson(file);
+  const errors = (rep.findings ?? []).filter((f: { severity: string }) => f.severity === "error").map((f: { rule: string; message: string }) => `${f.rule}: ${f.message}`);
+  return { ok: r.status === 0 && !errors.length, ran: true, errors };
+}
+
+export function still(dir: string, at: number, out: string): string | null {
+  mkdirSync(dirname(out), { recursive: true });
+  const r = kf("still", dir, "--t", String(at), "--out", out);
+  return r.status === 0 ? null : tail(r);
+}
+
+/** 칸 그림을 36×64 로 줄인 RGB — 판끼리 얼마나 다른지 잰다 */
+export function thumb(png: string): Uint8Array {
+  const r = spawnSync("ffmpeg", ["-v", "error", "-i", png, "-vf", "scale=36:64:flags=area", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"], { maxBuffer: 1 << 20 });
+  return new Uint8Array(r.stdout ?? []);
+}
+
+/** 0..1 — 평균 화소 차. 0.04 아래면 사람 눈에 같은 판 */
+export function imageDiff(a: Uint8Array, b: Uint8Array): number {
+  if (!a.length || a.length !== b.length) return 1;
+  let s = 0;
+  for (let i = 0; i < a.length; i++) s += Math.abs(a[i] - b[i]);
+  return s / a.length / 255;
+}
+
+// 칸 캐시 열쇠 — 겉모습(style)·견본 내용·세계 코드·견본 장면 문법(hook-number 패턴과 그 도구)이 같으면 같은 칸
+const patternsDir = fileURLToPath(new URL("../../patterns/src/", import.meta.url));
+const SAMPLE_CODE = [join(patternsDir, "kit.ts"), ...readdirSync(join(patternsDir, "hook-number")).sort().map((f) => join(patternsDir, "hook-number", f))];
+
+export function cellKey(t: Theme): string {
+  const h = createHash("sha256");
+  h.update(JSON.stringify(t.style));
+  h.update(JSON.stringify(SAMPLE));
+  for (const f of ["effects.ts", "slots.ts"]) if (existsSync(join(themesDir, t.world, f))) h.update(readFileSync(join(themesDir, t.world, f)));
+  for (const f of SAMPLE_CODE) if (existsSync(f)) h.update(readFileSync(f));
+  return h.digest("hex").slice(0, 16);
+}
+
+const metaOf = (id: string) => cellPath(id).replace(/\.png$/, ".json");
+
+export function cellFresh(t: Theme): boolean {
+  const m = metaOf(t.id);
+  return existsSync(cellPath(t.id)) && existsSync(m) && readJson(m).key === cellKey(t);
+}
+
+export function markCell(t: Theme, frame: Frame): void {
+  writeFileSync(metaOf(t.id), `${JSON.stringify({ key: cellKey(t), at: frame.at, width: frame.width, height: frame.height, safe: frame.safe, pattern: frame.pattern ?? null }, null, 2)}\n`);
+}
+
+export const cellFrame = (id: string): Frame | null => (existsSync(metaOf(id)) ? readJson(metaOf(id)) : null);
+
+/**
+ * 칸이 없거나 낡은 테마만 찍는다(검사 없이 — 변주는 뽑을 때 검사를 넘었다). 세계마다 표준 장면을 한 번 짓고 변주는 style 만 갈아 찍는다.
+ * 돌려주는 것: id → 칸 경로(못 찍은 것은 빠진다)
+ */
+export function ensureCells(ids: string[], tmp: string, log: (l: string) => void = () => {}): Map<string, string> {
+  const out = new Map<string, string>();
+  const byWorld = new Map<string, Theme[]>();
+  for (const id of ids) {
+    const t = loadTheme(id);
+    if (cellFresh(t)) out.set(id, cellPath(id));
+    else byWorld.set(t.world, [...(byWorld.get(t.world) ?? []), t]);
+  }
+  for (const [world, list] of byWorld) {
+    const base = join(tmp, `${world}-base`);
+    const b = standardProject(world, base, { check: false });
+    if (!b.frame) {
+      log(`견본 칸 ${world}: 표준 장면을 못 지었다 — ${b.why}`);
+      continue;
+    }
+    for (const t of list) {
+      const dir = t.variant ? join(tmp, t.id.replace("/", "--")) : base;
+      if (t.variant) restyle(base, dir, t.id);
+      const bad = still(dir, b.frame.at, cellPath(t.id));
+      if (bad) {
+        log(`견본 칸 ${t.id}: 못 찍음 — ${bad}`);
+        continue;
+      }
+      markCell(t, b.frame);
+      out.set(t.id, cellPath(t.id));
+      log(`견본 칸 ${t.id}: ${cellPath(t.id)}`);
+    }
+  }
+  return out;
+}
+
+export interface GridCell {
+  png: string;
+  title: string;
+  sub?: string;
+  note?: string;
+  swatches?: string[];
+  badge?: string;
+  bad?: boolean;
+}
+
+const esc = (s: string) => s.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]!);
+
+/** 칸 격자 한 장 — 안전 영역 점선, 이름·설명·색 견본 */
+export async function gridSheet(cells: GridCell[], out: string, o: { heading: string; cols: number; w: number; frame: Pick<Frame, "width" | "height" | "safe"> }): Promise<string> {
+  const { w, cols, frame } = o;
+  const h = Math.round((w * frame.height) / frame.width);
+  const k = w / frame.width;
+  const html = `<!doctype html><meta charset="utf-8"><style>
+    body { margin: 0; padding: 24px; background: #111; font: 15px/1.35 -apple-system, "Apple SD Gothic Neo", sans-serif; color: #ddd; width: ${cols * w + (cols - 1) * 16}px; }
+    h1 { margin: 0 0 16px; font-size: 18px; font-weight: 600; color: #fff; }
+    main { display: grid; grid-template-columns: repeat(${cols}, ${w}px); gap: 22px 16px; }
+    figure { margin: 0; position: relative; }
+    .safe { position: absolute; left: 0; width: ${w}px; border-top: 2px dashed #ff4d4d; opacity: .8; }
+    img { display: block; width: ${w}px; height: ${h}px; outline: 1px solid #333; object-fit: cover; }
+    figcaption { padding: 8px 2px 0; }
+    b { color: #fff; }
+    .d { display: inline-block; margin-left: 6px; padding: 0 6px; border: 1px solid #666; border-radius: 4px; font-size: 12px; }
+    small { display: block; color: #999; font-size: 12.5px; word-break: keep-all; }
+    .sw { display: flex; gap: 3px; margin-top: 5px; }
+    .sw i { width: 18px; height: 12px; border-radius: 2px; outline: 1px solid #444; }
+    .bad { color: #ff6b6b; }
+  </style><h1>${esc(o.heading)}</h1><main>${cells
+    .map(
+      (c) =>
+        `<figure><img src="${pathToFileURL(c.png).href}"><div class="safe" style="top:${Math.round(frame.safe.top * k)}px"></div><div class="safe" style="top:${Math.round((frame.height - frame.safe.bottom) * k)}px"></div><figcaption><b>${esc(c.title)}</b>${c.badge ? `<span class="d">${esc(c.badge)}</span>` : ""}${c.sub ? `<small>${esc(c.sub)}</small>` : ""}${c.note ? `<small class="${c.bad ? "bad" : ""}">${esc(c.note)}</small>` : ""}${c.swatches ? `<div class="sw">${c.swatches.map((s) => `<i style="background:${s}"></i>`).join("")}</div>` : ""}</figcaption></figure>`,
+    )
+    .join("")}</main>`;
+  mkdirSync(dirname(out), { recursive: true });
+  const page = out.replace(/\.png$/, ".html");
+  writeFileSync(page, html);
+  const browser = await launch();
+  try {
+    const p = await browser.newPage({ viewport: { width: 48 + cols * w + (cols - 1) * 16, height: 400 } });
+    await p.goto(pathToFileURL(page).href, { waitUntil: "load" });
+    writeFileSync(out, await p.screenshot({ fullPage: true, type: "png" }));
+  } finally {
+    await browser.close();
+    rmSync(page, { force: true });
+  }
+  return out;
+}
+
+/** 격자 칸 글 — 이름·2D/3D·설명·색 견본 */
+export function cellOf(t: Theme, png: string): GridCell {
+  const c = t.style.colors;
+  return {
+    png,
+    title: t.variant ? t.variant.name : `${t.name} · 기본`,
+    badge: themeDims(t),
+    sub: t.variant ? `${t.id} — ${t.variant.desc}` : `${t.id} — 세계 그대로`,
+    swatches: [c.bg, c.surface, c.ink, c.accent, c.success, c.danger],
+  };
+}

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

@@ -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) => {