kasaframe 0.0.0-stage → 0.1.1

package/packages/cli/src/browser.ts

@@ -0,0 +1,203 @@
+// window.__kf 전역 타입은 adapters 의 페이지 계약에 있다. cli 만 따로 타입 검사해도 보이게 끌어온다.
+import type {} from "@kasaframe/adapters";
+import { chromium, type Browser, type BrowserContext, type CDPSession, type Page } from "playwright";
+import { clockScript, type ClockOptions } from "@kasaframe/clock";
+import { openProject, type OpenProject } from "./serve.ts";
+
+export interface PageMeta {
+  fps: number;
+  width: number;
+  height: number;
+  duration: number;
+  music?: string;
+}
+
+export interface PageInfo {
+  meta: PageMeta;
+  mode: "seek" | "step";
+  markers: { t: number; label: string; kind: string }[];
+}
+
+// 같은 프레임을 두 번 찍어 같아야 하므로 GPU 래스터·LCD 글자 다듬기처럼 흔들리는 것을 끈다.
+// partial raster 는 바뀐 조각만 다시 그려, 앞서 몇 번 찍었느냐에 따라 안티에일리어싱 가장자리가 갈린다(탭 이음매가 어긋남).
+const ARGS = [
+  "--disable-partial-raster",
+  // 합성기 쓰레드가 opacity·transform 애니메이션을 따로 돌리면, 일시정지가 닿기 전 자기 진행값으로 한 번 그린다.
+  "--disable-threaded-animation",
+  "--font-render-hinting=none",
+  "--disable-lcd-text",
+  "--disable-skia-runtime-opts",
+  "--force-color-profile=srgb",
+  "--hide-scrollbars",
+  "--mute-audio",
+  "--autoplay-policy=no-user-gesture-required",
+  // HTML-in-Canvas — 3D 전환이 살아 있는 장면 DOM 을 시각마다 WebGL 텍스처로 올린다(texElementImage2D)
+  "--enable-features=CanvasDrawElement",
+  "--disable-background-timer-throttling",
+  "--disable-renderer-backgrounding",
+  "--disable-backgrounding-occluded-windows",
+];
+
+export async function launch(): Promise<Browser> {
+  try {
+    return await chromium.launch({ headless: true, args: ARGS });
+  } catch (err) {
+    if (!String(err).includes("Executable doesn't exist")) throw err;
+    return chromium.launch({ headless: true, channel: "chrome", args: ARGS });
+  }
+}
+
+export class Tab {
+  readonly page: Page;
+  private cdp: CDPSession;
+  info!: PageInfo;
+
+  private constructor(page: Page, cdp: CDPSession) {
+    this.page = page;
+    this.cdp = cdp;
+  }
+
+  static async open(context: BrowserContext, url: string): Promise<Tab> {
+    const page = await context.newPage();
+    const errors: string[] = [];
+    page.on("pageerror", (e) => errors.push(e.message));
+    page.on("console", (m) => {
+      if (m.type() === "error") errors.push(m.text());
+    });
+    const tab = new Tab(page, await context.newCDPSession(page));
+    await page.goto(url, { waitUntil: "load" });
+    try {
+      await page.waitForFunction(() => typeof window.__kf?.seek === "function", null, { timeout: 15000 });
+    } catch {
+      throw new Error(`페이지가 window.__kf 를 걸지 않았다 (${url})${errors.length ? `\n  페이지 오류: ${errors.join("\n  ")}` : ""}`);
+    }
+    await page.evaluate(() => window.__kf!.ready!());
+    tab.info = await page.evaluate(() => {
+      const k = window.__kf!;
+      return {
+        meta: { ...k.meta! },
+        mode: k.mode ?? "seek",
+        markers: (k.markers ?? []).map((m) => ({ t: m.t, label: m.label, kind: m.kind })),
+      };
+    });
+    const { width, height } = tab.info.meta;
+    const vp = page.viewportSize();
+    if (!vp || vp.width !== width || vp.height !== height) await page.setViewportSize({ width, height });
+    return tab;
+  }
+
+  async seek(t: number, sample?: { index: number; count: number }): Promise<void> {
+    await this.page.evaluate(([t, s]) => window.__kf!.seek!(t, s ?? undefined), [t, sample ?? null] as const);
+  }
+
+  // Playwright screenshot 보다 빠르다. optimizeForSpeed 는 PNG 압축만 줄이고 픽셀은 같다.
+  private async shot(): Promise<Buffer> {
+    const { data } = await this.cdp.send("Page.captureScreenshot", {
+      format: "png",
+      optimizeForSpeed: true,
+      captureBeyondViewport: false,
+    });
+    return Buffer.from(data, "base64");
+  }
+
+  // 이번 seek 에서 <video> 를 옮겼으면 합성기가 새 프레임을 받을 때까지 두 번 연속 같은 그림이 나오게 다시 찍는다.
+  async capture(): Promise<Buffer> {
+    let png = await this.shot();
+    const moved = await this.page.evaluate(() => {
+      const m = !!window.__kfMediaMoved;
+      window.__kfMediaMoved = false;
+      return m;
+    });
+    if (!moved) return png;
+    for (let i = 0; i < 8; i++) {
+      await this.page.evaluate(
+        () => new Promise<void>((r) => (window.__kfClock?.real.requestAnimationFrame ?? requestAnimationFrame)(() => r())),
+      );
+      const again = await this.shot();
+      if (again.equals(png)) return png;
+      png = again;
+    }
+    return png;
+  }
+
+  async close(): Promise<void> {
+    await this.page.close().catch(() => {});
+  }
+}
+
+export interface Session {
+  project: OpenProject;
+  browser: Browser;
+  context: BrowserContext;
+  first: Tab;
+  info: PageInfo;
+  tab(): Promise<Tab>;
+  close(): Promise<void>;
+}
+
+export interface SessionOptions {
+  clock?: boolean | ClockOptions;
+  width?: number;
+  height?: number;
+  // 페이지 주소 뒤에 붙일 질의 — captions=on 처럼 kf.json 을 그 판만 덮는 값
+  query?: string;
+}
+
+// 프로젝트를 띄우고 탭 하나를 준비한다. 렌더는 tab() 으로 더 연다.
+export async function openSession(dir: string, o: SessionOptions = {}): Promise<Session> {
+  const project = await openProject(dir);
+  const browser = await launch();
+  try {
+    const context = await browser.newContext({
+      viewport: { width: o.width ?? 1920, height: o.height ?? 1080 },
+      deviceScaleFactor: 1,
+    });
+    if (o.clock !== false) {
+      await context.addInitScript({ content: await clockScript(o.clock === true || !o.clock ? {} : o.clock) });
+    }
+    const url = o.query ? `${project.url}${project.url.includes("?") ? "&" : "?"}${o.query.replace(/^\?/, "")}` : project.url;
+    const first = await Tab.open(context, url);
+    return {
+      project,
+      browser,
+      context,
+      first,
+      info: first.info,
+      tab: () => Tab.open(context, url),
+      async close() {
+        await browser.close().catch(() => {});
+        await project.close();
+      },
+    };
+  } catch (err) {
+    await browser.close().catch(() => {});
+    await project.close();
+    throw err;
+  }
+}
+
+export interface OpenPage {
+  page: Page;
+  meta: PageMeta;
+  mode: "seek" | "step";
+  markers: PageInfo["markers"];
+  url: string;
+  seek(t: number): Promise<void>;
+  capture(): Promise<Buffer>;
+  close(): Promise<void>;
+}
+
+// 검사·생성처럼 엔진 밖에서 렌더와 같은 길로 페이지를 열 때.
+export async function openPage(dir: string, o: SessionOptions = {}): Promise<OpenPage> {
+  const s = await openSession(dir, o);
+  return {
+    page: s.first.page,
+    meta: s.info.meta,
+    mode: s.info.mode,
+    markers: s.info.markers,
+    url: s.project.url,
+    seek: (t) => s.first.seek(t),
+    capture: () => s.first.capture(),
+    close: () => s.close(),
+  };
+}

package/packages/cli/src/command.ts

@@ -0,0 +1,44 @@
+// 명령 파일 하나 = commands/<이름>.ts 의 default export.
+export interface Command {
+  summary: string;
+  usage?: string;
+  // 반환값이 종료 코드. 없으면 0.
+  run(argv: string[]): Promise<number | void>;
+}
+
+export interface Flags {
+  args: string[];
+  opts: Record<string, string | boolean | undefined>;
+}
+
+// --key value · --key=value · --flag(값 없으면 true). 짧은 옵션은 쓰지 않는다.
+export function parseFlags(argv: string[]): Flags {
+  const out: Flags = { args: [], opts: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) {
+      out.args.push(a);
+      continue;
+    }
+    const eq = a.indexOf("=");
+    if (eq > 0) {
+      out.opts[a.slice(2, eq)] = a.slice(eq + 1);
+      continue;
+    }
+    const next = argv[i + 1];
+    if (next !== undefined && !next.startsWith("--")) {
+      out.opts[a.slice(2)] = next;
+      i++;
+    } else {
+      out.opts[a.slice(2)] = true;
+    }
+  }
+  return out;
+}
+
+export function num(v: string | boolean | undefined, fallback: number): number {
+  if (typeof v !== "string") return fallback;
+  const n = Number(v);
+  if (!Number.isFinite(n)) throw new Error(`숫자가 아니다: ${v}`);
+  return n;
+}

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

@@ -0,0 +1,25 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { type Command, parseFlags } from "../command.ts";
+import { installed } from "../serve.ts";
+
+const cmd: Command = {
+  summary: "작업실 — 요청 칸·실시간 미리보기·렌더·검사 보고를 브라우저 화면으로",
+  usage: `kf app [--port 5150] [--host 127.0.0.1] [--dir 일 폴더]
+  --host 0.0.0.0 이면 같은 망의 폰에서도 연다. 일 폴더 기본은 레포 out/app, 설치된 패키지는 ~/.kasaframe/app
+  곡 모음은 KF_MUSIC_DIR. 말로 시작한 kf make 도 작업실이 떠 있으면 스스로 붙는다(KF_APP_URL)`,
+  async run(argv) {
+    const { opts } = parseFlags(argv);
+    const set = (flag: string, env: string) => {
+      if (typeof opts[flag] === "string") process.env[env] = opts[flag] as string;
+    };
+    set("port", "KF_APP_PORT");
+    set("host", "KF_APP_HOST");
+    set("dir", "KF_APP_DIR");
+    if (installed) process.env.KF_APP_DIR ??= join(homedir(), ".kasaframe", "app");
+    await import("../../../../app/server/main.ts");
+    // 서버가 멈출 때까지 돌려 둔다 — 끝내기는 main.ts 의 SIGINT 처리가 맡는다
+    return new Promise<never>(() => {});
+  },
+};
+export default cmd;

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

@@ -0,0 +1,36 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { type Command, parseFlags } from "../command.ts";
+import { python as pythonBin, requirements } from "../deps.ts";
+
+const script = fileURLToPath(new URL("../../../../tools/beats/beats.py", import.meta.url));
+
+const cmd: Command = {
+  summary: "곡을 재서 beats.json — 박·마디·프레이즈·구간·드롭·대역 에너지",
+  usage: `kf beats <곡> [--out beats.json] [--from 초] [--duration 초] [--hz 20] [--bpm 힌트]
+
+  --from·--duration  곡의 일부만 쓸 때. 모든 시각은 --from 을 0 으로 센다
+  --bpm              반박·두 배 박으로 잡힐 때만 박 추적 시작값으로 준다(시각을 곱해 만들지 않는다)
+  요약은 stderr 로 나온다. python3 + librosa 가 필요하다 — kf setup beats 가 ~/.cache/kasaframe/py/beats 에 깐다(KF_PYTHON 으로 바꿀 수 있다).`,
+  async run(argv) {
+    const { args } = parseFlags(argv);
+    if (args.length === 0) {
+      console.error("kf beats: 곡 경로가 필요하다. kf beats --help");
+      return 2;
+    }
+    if (!existsSync(args[0])) {
+      console.error(`kf beats: 곡이 없다: ${args[0]}`);
+      return 2;
+    }
+    const python = pythonBin();
+    const probe = spawnSync(python, ["-c", "import librosa"], { stdio: "ignore" });
+    if (probe.status !== 0) {
+      console.error(`kf beats: ${python} 에 librosa 가 없다 — kf setup beats (또는 ${python} -m pip install -r ${requirements})`);
+      return 1;
+    }
+    const r = spawnSync(python, [script, ...argv], { stdio: "inherit" });
+    return r.status ?? 1;
+  },
+};
+export default cmd;

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

@@ -0,0 +1,270 @@
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, 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 { 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.
+
+interface KfJson {
+  fps: number;
+  width: number;
+  height: number;
+  duration: number;
+  beats?: string | null;
+  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"))) {
+    throw new Error(
+      `Blender 헬퍼(kfb.py·run.py)가 없다: ${dir}\n` +
+        "헬퍼는 bpy 를 써서 GPL-3.0 으로 갈라 두었고 npm 묶음에는 넣지 않았다 — 레포의 tools/blender 를 받아 KF_BLENDER_LIB=<그 폴더> 로 가리켜라.",
+    );
+  }
+  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)}`);
+    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 에서 열어 보기)
+  --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`);
+    writeFileSync(cfgPath, JSON.stringify(cfg, null, 2));
+
+    const { exe, version } = findBlender(typeof opts.blender === "string" ? opts.blender : undefined);
+    const release = opts["no-lock"] ? () => {} : await acquireRenderLock(proj, num(opts["lock-wait"], 900));
+    const started = Date.now();
+    try {
+      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 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,
+        renderedAt: new Date().toISOString(),
+      };
+      writeFileSync(join(outDir, `${id}.json`), `${JSON.stringify(meta, 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;
+
+// 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/doctor.ts

@@ -0,0 +1,22 @@
+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 { repoRoot } from "../serve.ts";
+
+const cmd: Command = {
+  summary: "바깥 도구 점검 — ffmpeg·크롬(Playwright)·python3+librosa·OG 키, 없으면 까는 명령",
+  usage: `kf doctor
+  없음 은 렌더가 안 되는 것, 선택 은 그 기능만 빠지는 것. 크롬·librosa 는 kf setup 이 깐다. 종료 코드: 없음 이 있으면 1`,
+  async run() {
+    const version = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8")).version ?? "?";
+    console.log(`kasaframe ${version} · Node ${process.version} · ${platform()} ${arch()}\n`);
+    const list = await checks();
+    report(list);
+    const missing = list.filter((c) => c.required && !c.ok);
+    console.log(missing.length ? `\n렌더에 필요한 것이 ${missing.length}개 없다 — 위 → 대로 깔고 다시 kf doctor` : "\n렌더 준비 됨 — kf new <폴더> --template shorts 부터");
+    return missing.length ? 1 : 0;
+  },
+};
+export default cmd;