kasaframe 0.0.0-stage → 0.1.3

package/packages/plan/src/layout.ts

@@ -0,0 +1,176 @@
+import type { BeatsLike, Template, TemplateScene } from "./types.ts";
+
+export interface LaidScene extends TemplateScene {
+  from: number;
+  dur: number;
+}
+
+export interface Layout {
+  duration: number;
+  scenes: LaidScene[];
+  notes: string[];
+}
+
+const MIN_SCENE = 0.75;
+
+// 요청 길이 → 곡 길이 → 틀 기본 순. 곡이 틀 상한보다 길면 틀 기본 길이에서 끊는다.
+export function pickDuration(tpl: Template, o: { requested?: number; beats?: BeatsLike | null }): { duration: number; notes: string[] } {
+  const { min, max, allowed } = tpl.duration;
+  const notes: string[] = [];
+  const music = o.beats?.duration;
+  if (o.requested !== undefined) {
+    let d = o.requested;
+    if (allowed && !allowed.includes(d)) {
+      const near = allowed.reduce((a, b) => (Math.abs(b - d) < Math.abs(a - d) ? b : a));
+      notes.push(`${d}초 대신 ${tpl.label} 고정 길이 ${near}초`);
+      d = near;
+    } else if (d < min || d > max) {
+      const c = Math.min(max, Math.max(min, d));
+      notes.push(`${d}초는 ${tpl.label} 범위(${min}–${max}초) 밖이라 ${c}초`);
+      d = c;
+    }
+    if (music !== undefined && music < d) {
+      notes.push(`곡이 ${music.toFixed(1)}초라 영상도 거기까지`);
+      d = music;
+    }
+    return { duration: d, notes };
+  }
+  if (music === undefined) return { duration: tpl.duration.default, notes };
+  if (music <= max) {
+    if (music < min) notes.push(`곡이 ${music.toFixed(1)}초로 ${tpl.label} 최소 ${min}초보다 짧다`);
+    return { duration: music, notes };
+  }
+  // 구간 경계에서 끊으면 「1분 홍보」가 56초가 된다 — 사람은 길이를 숫자로 기대하니 틀 기본 길이에서 끊는다
+  const d = Math.min(max, Math.max(min, tpl.duration.default));
+  notes.push(`곡(${music.toFixed(1)}초)이 상한 ${max}초보다 길어 기본 길이 ${d}초에서 끊는다`);
+  return { duration: d, notes };
+}
+
+// 곡이 영상보다 길 수 있다 — 영상 안에 든 드롭·구간만 센다
+function anchorTime(anchor: string | undefined, beats: BeatsLike | null | undefined, duration: number): number | undefined {
+  if (!anchor || !beats) return undefined;
+  const drops = (beats.drops ?? []).filter((t) => t > 0 && t < duration);
+  if (anchor === "drop:last") return drops.length ? drops[drops.length - 1] : undefined;
+  const d = anchor.match(/^drop:(\d+)$/);
+  if (d) return drops[Number(d[1])];
+  const s = anchor.match(/^section:(.+)$/);
+  if (s) return beats.sections?.find((x) => x.kind === s[1] && x.t < duration)?.t;
+  return undefined;
+}
+
+// 고정 초(sec)를 먼저 떼고 남은 시간을 weight 로 나눈다. 칸이 모자라면 고정 초도 같은 비율로 줄인다.
+function fill(scenes: TemplateScene[], span: number): number[] {
+  const fixed = scenes.reduce((a, s) => a + (s.sec ?? 0), 0);
+  const weight = scenes.reduce((a, s) => a + (s.sec === undefined ? (s.weight ?? 1) : 0), 0);
+  if (weight === 0 || fixed >= span) {
+    const k = fixed > 0 ? span / fixed : 0;
+    return scenes.map((s) => (fixed > 0 ? (s.sec ?? 0) * k : span / scenes.length));
+  }
+  const rest = span - fixed;
+  return scenes.map((s) => s.sec ?? (rest * (s.weight ?? 1)) / weight);
+}
+
+const MIN_SECTION = 4;
+const MAX_SECTIONS = 14;
+
+// 뮤비처럼 곡 구간이 곧 장면인 틀 — 잰 구간 경계를 그대로 쓰고, 너무 짧은 구간은 앞 구간에 붙이고, 너무 많으면 가장 짧은 것부터 합친다
+function sectionLayout(tpl: Template, duration: number, beats: BeatsLike): Layout {
+  const marks = (beats.sections ?? []).filter((s) => s.t < duration - MIN_SECTION).sort((a, b) => a.t - b.t);
+  if (!marks.length || marks[0].t > 0.5) marks.unshift({ t: 0, kind: "intro" });
+  else marks[0] = { ...marks[0], t: 0 };
+  let segs = marks.map((m, i) => ({ kind: m.kind, from: m.t, to: i + 1 < marks.length ? marks[i + 1].t : duration }));
+  for (let i = segs.length - 1; i > 0; i--) {
+    if (segs[i].to - segs[i].from < MIN_SECTION) {
+      segs[i - 1].to = segs[i].to;
+      segs.splice(i, 1);
+    }
+  }
+  while (segs.length > MAX_SECTIONS) {
+    let k = 0;
+    for (let i = 1; i < segs.length; i++) if (segs[i].to - segs[i].from < segs[k].to - segs[k].from) k = i;
+    const j = k === 0 ? 1 : k === segs.length - 1 ? k - 1 : segs[k - 1].to - segs[k - 1].from < segs[k + 1].to - segs[k + 1].from ? k - 1 : k + 1;
+    const [a, b] = [Math.min(k, j), Math.max(k, j)];
+    segs[a] = { ...segs[a], to: segs[b].to };
+    segs.splice(b, 1);
+  }
+  const f = (x: number) => Math.round(x * tpl.fps) / tpl.fps;
+  const count: Record<string, number> = {};
+  const scenes = segs.map((g) => {
+    count[g.kind] = (count[g.kind] ?? 0) + 1;
+    const from = f(g.from);
+    return { id: `${g.kind}${count[g.kind]}`, role: g.kind, idea: tpl.sectionIdeas?.[g.kind] ?? tpl.sectionIdeas?.main ?? g.kind, snap: "none" as const, from: r4(from), dur: r4(f(g.to) - from) };
+  });
+  return { duration: f(duration), scenes, notes: [`곡 구간 ${scenes.length}개를 장면으로(${MIN_SECTION}초보다 짧은 구간은 앞에 붙임)`] };
+}
+
+export function layoutScenes(tpl: Template, duration: number, beats?: BeatsLike | null): Layout {
+  if (tpl.layout === "sections" && beats?.sections && beats.sections.length >= 2) return sectionLayout(tpl, duration, beats);
+  const scenes = tpl.scenes;
+  const n = scenes.length;
+  const notes: string[] = [];
+
+  // 1. 드롭·구간에 묶인 장면 시작을 못으로 박는다. 앞 장면들이 설 자리가 없으면 그 못은 버린다.
+  const pins = new Map<number, number>([[0, 0], [n, duration]]);
+  for (let i = 1; i < n; i++) {
+    const a = anchorTime(scenes[i].anchor, beats, duration);
+    if (beats && scenes[i].anchor && !scenes[i].anchor!.match(/^(start|end)$/) && a === undefined) {
+      notes.push(`${scenes[i].id}: ${scenes[i].anchor} 이 곡에 없어 비율로 둔다`);
+      continue;
+    }
+    if (a === undefined) continue;
+    const prevPin = Math.max(...[...pins.entries()].filter(([k]) => k < i).map(([, v]) => v));
+    const before = i - [...pins.keys()].filter((k) => k < i).reduce((x, y) => Math.max(x, y), 0);
+    const tailNeed = scenes.slice(i).reduce((s, x) => s + (x.sec ?? MIN_SCENE), 0);
+    if (a - prevPin < before * MIN_SCENE || duration - a < tailNeed) {
+      notes.push(`${scenes[i].id}: ${scenes[i].anchor}(${a.toFixed(2)}초)에 붙이면 앞뒤 장면이 설 자리가 없어 비율로 둔다`);
+      continue;
+    }
+    pins.set(i, a);
+  }
+
+  // 2. 못 사이를 sec·weight 로 채운다
+  const bounds: number[] = new Array(n + 1);
+  const keys = [...pins.keys()].sort((a, b) => a - b);
+  for (let k = 0; k < keys.length - 1; k++) {
+    const i0 = keys[k];
+    const i1 = keys[k + 1];
+    const t0 = pins.get(i0)!;
+    const lens = fill(scenes.slice(i0, i1), pins.get(i1)! - t0);
+    bounds[i0] = t0;
+    let t = t0;
+    for (let j = i0; j < i1; j++) {
+      t += lens[j - i0];
+      bounds[j + 1] = t;
+    }
+  }
+  bounds[n] = duration;
+
+  // 3. 못이 아닌 경계를 마디·박에 붙인다. 고정 초 장면 곁은 0.25초 안에서만 움직인다.
+  if (beats) {
+    for (let i = 1; i < n; i++) {
+      if (pins.has(i)) continue;
+      // snap 을 안 적은 장면(고정 초 장면 곁)도 박에는 붙인다 — 검사가 박에서 어긋난 경계를 잡는다
+      const snap = scenes[i].snap ?? "beat";
+      if (snap === "none") continue;
+      const grid = snap === "bar" ? (beats.bars ?? beats.downbeats ?? beats.beats) : beats.beats;
+      if (!grid?.length) continue;
+      const fixedSide = scenes[i - 1].sec !== undefined || scenes[i].sec !== undefined;
+      const reach = fixedSide ? 0.25 : Math.min(bounds[i] - bounds[i - 1], bounds[i + 1] - bounds[i]) / 2;
+      const near = grid.reduce((a, b) => (Math.abs(b - bounds[i]) < Math.abs(a - bounds[i]) ? b : a));
+      if (Math.abs(near - bounds[i]) <= reach && near - bounds[i - 1] >= MIN_SCENE * 0.5 && bounds[i + 1] - near >= MIN_SCENE * 0.5) bounds[i] = near;
+    }
+  }
+
+  // 4. 프레임에 맞춘다 — 경계가 프레임 사이에 걸리면 한 프레임에 두 장면이 겹치거나 빈다
+  const f = (x: number) => Math.round(x * tpl.fps) / tpl.fps;
+  const out = bounds.map(f);
+  return {
+    duration: out[n],
+    notes,
+    scenes: scenes.map((s, i) => ({ ...s, from: r4(out[i]), dur: r4(out[i + 1] - out[i]) })),
+  };
+}
+
+function r4(x: number): number {
+  return Math.round(x * 10000) / 10000;
+}

package/packages/plan/src/llm.ts

@@ -0,0 +1,172 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { readKey } from "@kasaframe/gen";
+
+// OG chat/completions 하나로 어떤 모델이든 부른다. 그림 보는 검사도 여기로 — OG /v1/messages 는 딥시크에 그림을 넘기지 않는다
+const BASE = process.env.KF_OG_BASE ?? "https://apis.opengateway.ai/v1";
+
+// Opus·GPT 계열은 한 번에 값이 크게 뛴다 — 장면 쓰기·고치기·그림 검사가 모두 이 문을 지나니 여기서 한 번만 막는다.
+// 짚은 사람이 풀어야만(--allow-premium 이 KF_ALLOW_PREMIUM=1 로 넘긴다 — 자식 kf 까지 같은 값)
+export function premiumBlock(model: string): string | null {
+  if (process.env.KF_ALLOW_PREMIUM === "1") return null;
+  const name = model.toLowerCase().split("/").pop() ?? "";
+  if (!/^claude.*opus|^opus/.test(name) && !/^(gpt|chatgpt|o\d+)([-.]|$)/.test(name)) return null;
+  return `${model} 은 비싼 모델(Opus·GPT 계열)이라 부르기 전에 막았다 — 꼭 써야 하면 --allow-premium(또는 KF_ALLOW_PREMIUM=1)`;
+}
+
+export type Part = { type: "text"; text: string } | { type: "image_url"; image_url: { url: string } };
+export interface Message {
+  role: "system" | "user" | "assistant";
+  content: string | Part[];
+}
+
+// 모델별로 쓴 만큼 — kf make 가 끝날 때(성공·실패·중단) <작업 폴더>/make-stats.json 에 남겨 모델끼리 시간·토큰·비용을 견준다.
+// og 는 OG 를 거친 호출(chat·OG 그림) — 그 밖의 생성(fal 영상 따위)도 같은 장부에 두되 「OG 호출」 줄에는 안 센다
+export interface Spent {
+  model: string;
+  stage: string;
+  ms: number;
+  prompt: number;
+  completion: number;
+  cached: number;
+  usd: number | null;
+  og: boolean;
+}
+const spent: Spent[] = [];
+export const ledger = (): Spent[] => [...spent];
+export const spend = (s: Spent): void => void spent.push(s);
+
+interface Total {
+  calls: number;
+  prompt: number;
+  completion: number;
+  cached: number;
+  usd: number;
+  ms: number;
+  // 가격표를 못 받아 값을 모르는 호출 수 — usd 합에 안 들어갔다
+  unpriced: number;
+}
+
+function sum(xs: Spent[]): Total {
+  const t: Total = { calls: xs.length, prompt: 0, completion: 0, cached: 0, usd: 0, ms: 0, unpriced: 0 };
+  for (const x of xs) {
+    t.prompt += x.prompt;
+    t.completion += x.completion;
+    t.cached += x.cached;
+    t.ms += x.ms;
+    if (x.usd === null) t.unpriced++;
+    else t.usd += x.usd;
+  }
+  t.usd = Number(t.usd.toFixed(6));
+  return t;
+}
+
+export function spentLine(xs: Spent[] = spent): string {
+  const og = sum(xs.filter((x) => x.og));
+  const other = sum(xs.filter((x) => !x.og));
+  const head = og.calls ? `OG 호출 ${og.calls}번 · 입력 ${og.prompt.toLocaleString("en-US")}/출력 ${og.completion.toLocaleString("en-US")} 토큰 · $${og.usd.toFixed(4)}${og.unpriced ? `(값 모름 ${og.unpriced}번)` : ""}` : "OG 호출 0";
+  return other.calls ? `${head} · 그 밖 생성 ${other.calls}번 $${other.usd.toFixed(4)}` : head;
+}
+
+// 한 kf make 실행이 한 판 — --finish·--rewrite 가 같은 폴더에 다시 돌아도 앞 판을 지우지 않고 뒤에 붙인다
+export function writeStats(dir: string, run: { command: string; model: string; code: number | string }): string {
+  const file = join(dir, "make-stats.json");
+  let runs: unknown[] = [];
+  try {
+    runs = (JSON.parse(readFileSync(file, "utf8")) as { runs?: unknown[] }).runs ?? [];
+  } catch {}
+  const stages = ledger();
+  runs.push({ at: new Date().toISOString(), ...run, stages, total: sum(stages), og: sum(stages.filter((x) => x.og)), line: spentLine(stages) });
+  const all = (runs as { stages?: Spent[] }[]).flatMap((r) => r.stages ?? []);
+  writeFileSync(file, `${JSON.stringify({ runs, total: sum(all), og: sum(all.filter((x) => x.og)), line: spentLine(all) }, null, 2)}\n`);
+  return file;
+}
+
+let prices: Record<string, { inputCostPerToken?: number; outputCostPerToken?: number; cacheReadInputTokenCost?: number }> | null = null;
+// 공개 가격표(키 없이). 못 받으면 비용은 null 로 두고 토큰만 남긴다
+async function priceOf(model: string) {
+  if (!prices) {
+    try {
+      prices = (await (await fetch("https://opengateway.ai/api/model-prices", { signal: AbortSignal.timeout(10000) })).json()) as typeof prices;
+    } catch {
+      prices = {};
+    }
+  }
+  return prices?.[model] ?? null;
+}
+
+export interface ChatResult {
+  text: string;
+  // "length" 면 답이 상한에서 잘렸다
+  finish?: string;
+  usage?: { prompt_tokens?: number; completion_tokens?: number };
+  ms: number;
+}
+
+export async function chat(
+  model: string,
+  messages: Message[],
+  o: { temperature?: number; maxTokens?: number; json?: boolean; timeoutSec?: number; effort?: "low" | "medium" | "high"; stage?: string } = {},
+): Promise<ChatResult> {
+  const blocked = premiumBlock(model);
+  if (blocked) throw new Error(blocked);
+  const t0 = Date.now();
+  const body: Record<string, unknown> = { model, messages, max_tokens: o.maxTokens ?? 8000 };
+  // 추론을 켠 Claude 는 temperature 를 받지 않는다
+  if (o.effort) body.reasoning_effort = o.effort;
+  else body.temperature = o.temperature ?? 0.4;
+  if (o.json) body.response_format = { type: "json_object" };
+  let last: unknown;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      const r = await fetch(`${BASE}/chat/completions`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${readKey("opengateway")}` },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout((o.timeoutSec ?? 300) * 1000),
+      });
+      const j = (await r.json().catch(() => ({}))) as any;
+      if (!r.ok) {
+        const msg = j?.error?.message ?? JSON.stringify(j).slice(0, 300);
+        if (r.status >= 500 || r.status === 429) throw new Error(`OG ${r.status}: ${msg}`);
+        throw Object.assign(new Error(`OG ${r.status}: ${msg}`), { fatal: true });
+      }
+      const ms = Date.now() - t0;
+      const u = j.usage ?? {};
+      const p = await priceOf(model);
+      const cached = u.prompt_tokens_details?.cached_tokens ?? 0;
+      const prompt = u.prompt_tokens ?? 0;
+      const completion = u.completion_tokens ?? 0;
+      const usd = p?.inputCostPerToken !== undefined ? (prompt - cached) * p.inputCostPerToken + cached * (p.cacheReadInputTokenCost ?? p.inputCostPerToken) + completion * (p.outputCostPerToken ?? 0) : null;
+      spent.push({ model, stage: o.stage ?? "", ms, prompt, completion, cached, usd, og: true });
+      return { text: j.choices?.[0]?.message?.content ?? "", finish: j.choices?.[0]?.finish_reason, usage: j.usage, ms };
+    } catch (e) {
+      if ((e as any)?.fatal) throw e;
+      last = e;
+      // 429 는 잠깐 쉬어서는 안 풀린다 — 더 길게 기다린다
+      const wait = /OG 429/.test(String(e)) ? 5000 * (attempt + 1) : 1500 * (attempt + 1);
+      await new Promise((res) => setTimeout(res, wait));
+    }
+  }
+  throw last instanceof Error ? last : new Error(String(last));
+}
+
+// 모델이 설명을 붙여도 코드 블록 하나만 건진다. 닫는 울타리가 없으면(답이 잘렸거나 빠뜨림) 여는 울타리 뒤를 다 쓴다
+export function codeBlock(text: string, lang = "ts"): string | null {
+  const open = "```(?:" + lang + "|typescript|tsx|js|javascript)?[ \\t]*\\n";
+  const blocks = [...text.matchAll(new RegExp(open + "([\\s\\S]*?)\\n```", "g"))].map((m) => m[1]);
+  if (blocks.length) return blocks.sort((a, b) => b.length - a.length)[0].trim() + "\n";
+  const lone = text.match(new RegExp(open + "([\\s\\S]*)$"));
+  const body = (lone ? lone[1] : text).replace(/\n?```\s*$/, "").trim();
+  return /export default/.test(body) ? body + "\n" : null;
+}
+
+export function jsonBlock<T>(text: string): T | null {
+  const m = text.match(/```(?:json)?\s*\n([\s\S]*?)```/);
+  const raw = m ? m[1] : text.slice(text.indexOf("{"), text.lastIndexOf("}") + 1);
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}

package/packages/plan/src/look.ts

@@ -0,0 +1,222 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { loadTheme } from "@kasaframe/themes";
+import { chat, jsonBlock, type Part } from "./llm.ts";
+
+// 기본은 세션이 직접 본다 — 장면 모음 한 장과 장면별 확인표를 만들어 경로만 찍는다(외부 모델 0, 돈 0).
+// 그림 보는 모델에 남이 대신 보게 하면 장면의 할 일·테마를 모르는 채 겉만 보고, 그림을 볼 수 있는 세션까지 돈을 썼다.
+// 그림을 못 보는 세션(OG 로 붙인 DeepSeek 같은 — OG /v1/messages 는 그림을 버린다)만 --vision-model 로 다른 모델의 눈을 빌린다
+
+export const DEFAULT_EYES = "google/gemini-3.5-flash";
+// 기본 눈이 막히면(429 등) 넘어갈 곳 — 둘 다 chat/completions 로 그림을 받는다
+const SPARE_EYES = "anthropic/claude-haiku-5-5";
+const kfBin = fileURLToPath(new URL("../../cli/src/kf.ts", import.meta.url));
+const VIDEO = /\.(mp4|mov|webm|m4v)$/i;
+
+export interface LookScene {
+  id: string;
+  from: number;
+  to: number;
+  ok: boolean;
+  problems: string[];
+}
+
+export interface LookReport {
+  model: string;
+  scenes: LookScene[];
+  summary: string;
+  answer?: string; // --ask 에 대한 답
+  ms: number;
+}
+
+interface KfLike {
+  scenes: { id: string; from: number; dur: number; idea?: string; role?: string }[];
+  theme?: string;
+  text?: { policy?: string };
+}
+
+function findProject(start: string): string | null {
+  let d = resolve(start);
+  for (let i = 0; i < 3; i++) {
+    if (existsSync(join(d, "kf.json"))) return d;
+    d = dirname(d);
+  }
+  return null;
+}
+
+// 폴더면 kf sheet(장면마다 가운데 한 장을 모은 한 장, 렌더 잠금), mp4 면 장면 가운데마다 ffmpeg 로 한 장씩
+function pictures(target: string, kf: KfLike | null, dir: string | null): { parts: Part[]; note: string } {
+  if (!VIDEO.test(target)) {
+    const out = join(dir!, "out", "look-sheet.png");
+    mkdirSync(dirname(out), { recursive: true });
+    // 다른 렌더가 잠금을 오래 쥐고 있으면 기다리지 않고, 구워 둔 영상이 있으면 그걸 본다
+    const baked = ["video.mp4", "render.mp4"].map((f) => join(dir!, "out", f)).find((f) => existsSync(f));
+    const r = spawnSync(process.execPath, [kfBin, "sheet", dir!, "--out", out, "--cols", "4", "--width", "480", "--lock-wait", baked ? "20" : "900"], { stdio: ["ignore", "ignore", "pipe"], encoding: "utf8" });
+    if ((r.status !== 0 || !existsSync(out)) && baked) return pictures(baked, kf, dir);
+    if (r.status !== 0 || !existsSync(out)) throw new Error(`kf sheet 이 실패했다: ${(r.stderr ?? "").trim().split("\n").slice(-2).join(" ")}`);
+    return { parts: [{ type: "image_url", image_url: { url: `data:image/png;base64,${readFileSync(out).toString("base64")}` } }], note: "장면 모음 한 장 — 왼쪽 위부터 오른쪽으로, 줄을 바꿔 가며 장면 순서대로 한 칸씩(4열)." };
+  }
+  const tmp = join(tmpdir(), `kf-look-${process.pid}`);
+  mkdirSync(tmp, { recursive: true });
+  const times = kf?.scenes.length ? kf.scenes.map((s) => s.from + s.dur / 2) : Array.from({ length: 12 }, (_, i) => i * 5 + 2.5);
+  const parts: Part[] = [];
+  try {
+    times.forEach((t, i) => {
+      const f = join(tmp, `${i}.jpg`);
+      spawnSync("ffmpeg", ["-v", "error", "-y", "-ss", t.toFixed(3), "-i", target, "-frames:v", "1", "-vf", "scale=640:-1", "-q:v", "4", f]);
+      if (!existsSync(f)) return;
+      parts.push({ type: "text", text: `${kf?.scenes[i]?.id ?? `${t.toFixed(1)}초`}` }, { type: "image_url", image_url: { url: `data:image/jpeg;base64,${readFileSync(f).toString("base64")}` } });
+    });
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+  if (!parts.length) throw new Error(`영상에서 프레임을 못 뽑았다: ${target}`);
+  return { parts, note: "장면마다 가운데 한 장 — 그림 앞에 장면 이름." };
+}
+
+function open(target: string): { dir: string | null; kf: KfLike | null } {
+  const dir = findProject(target);
+  const kf: KfLike | null = dir ? JSON.parse(readFileSync(join(dir, "kf.json"), "utf8")) : null;
+  if (!dir && !VIDEO.test(target)) throw new Error(`${target} 에 kf.json 이 없다 — 프로젝트 폴더나 mp4 를 준다`);
+  return { dir, kf };
+}
+
+function themeOf(kf: KfLike | null): { name: string; metaphor: string; guide: string } | null {
+  if (!kf?.theme) return null;
+  try {
+    return loadTheme(kf.theme);
+  } catch {
+    return null;
+  }
+}
+
+export interface LookSheet {
+  sheet: string;
+  checklist: string;
+  scenes: number;
+}
+
+/** 세션이 직접 볼 것 — 장면 모음 한 장(장면마다 가운데 한 장, 4열)과 장면별 확인표(look.md). 폴더면 out/, mp4 면 옆에 */
+export function lookSheet(target: string): LookSheet {
+  const { dir, kf } = open(target);
+  const isVideo = VIDEO.test(target);
+  const outDir = isVideo ? dirname(resolve(target)) : join(dir!, "out");
+  mkdirSync(outDir, { recursive: true });
+  const sheet = join(outDir, "look-sheet.png");
+  const scenes = kf?.scenes ?? [];
+  if (isVideo) videoSheet(target, scenes, sheet);
+  else {
+    const baked = ["video.mp4", "render.mp4"].map((f) => join(dir!, "out", f)).find((f) => existsSync(f));
+    const r = spawnSync(process.execPath, [kfBin, "sheet", dir!, "--out", sheet, "--cols", "4", "--width", "480", "--lock-wait", baked ? "20" : "900"], { stdio: ["ignore", "ignore", "pipe"], encoding: "utf8" });
+    if ((r.status !== 0 || !existsSync(sheet)) && baked) videoSheet(baked, scenes, sheet);
+    else if (r.status !== 0 || !existsSync(sheet)) throw new Error(`kf sheet 이 실패했다: ${(r.stderr ?? "").trim().split("\n").slice(-2).join(" ")}`);
+  }
+  const checklist = join(outDir, "look.md");
+  writeFileSync(checklist, checklistText(kf, sheet));
+  return { sheet, checklist, scenes: scenes.length };
+}
+
+// mp4 — 장면 가운데마다 한 장을 뽑아 4열로 붙인다(kf sheet 와 같은 차례)
+function videoSheet(file: string, scenes: KfLike["scenes"], out: string): void {
+  const times = scenes.length ? scenes.map((s) => s.from + s.dur / 2) : Array.from({ length: 12 }, (_, i) => i * 5 + 2.5);
+  const tmp = join(tmpdir(), `kf-look-${process.pid}`);
+  mkdirSync(tmp, { recursive: true });
+  try {
+    let n = 0;
+    for (const t of times) {
+      const f = join(tmp, `${String(n).padStart(3, "0")}.png`);
+      spawnSync("ffmpeg", ["-v", "error", "-y", "-ss", t.toFixed(3), "-i", file, "-frames:v", "1", "-vf", "scale=480:-2", f]);
+      if (existsSync(f)) n++;
+    }
+    if (!n) throw new Error(`영상에서 프레임을 못 뽑았다: ${file}`);
+    const cols = Math.min(4, n);
+    spawnSync("ffmpeg", ["-v", "error", "-y", "-start_number", "0", "-i", join(tmp, "%03d.png"), "-vf", `tile=${cols}x${Math.ceil(n / cols)}:padding=6:color=black`, "-frames:v", "1", out]);
+    if (!existsSync(out)) throw new Error(`장면 모음을 못 붙였다: ${out}`);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+// 정지 그림으로 볼 수 있는 것만 — 움직임·박·섬광·카메라 이동은 kf check 가 숫자로 본다
+function checklistText(kf: KfLike | null, sheet: string): string {
+  const theme = themeOf(kf);
+  const scenes = kf?.scenes ?? [];
+  const common = [
+    "화면이 비지 않았다 — 주 요소가 안전 영역을 크게 채운다(세로 화면은 폭 70% 넘게)",
+    "글이 읽힌다 — 깨진 글자(빈 네모·undefined·NaN·null) 없음, 바탕과 대비가 선다, 잘림·겹침 없음",
+    "주인공이 안전 영역 가운데에 선다 — 가장자리로 밀리거나 잘리지 않았다",
+    `화면 글 정책(${kf?.text?.policy ?? "모름"})을 지킨다`,
+    "뜻 없는 장식이 없다 — 움직이거나 놓인 것은 다 내용 하나를 뜻한다(떠다니는 판·빛 방울·큐브·흩뿌린 입자 없음, 바탕은 정지거나 아주 옅은 질감)",
+    "3D↔2D 가 끊기지 않는다 — 3D 샷과 2D 장면 사이는 공간 잇기 이음매(rise·land)나 투영을 맞춘 컷으로, 같은 물체·자리가 이어진다",
+    ...(theme ? [`테마 ${theme.name}(${theme.metaphor})의 생김새·금지를 지킨다 — themes/${kf?.theme}/THEME.md`] : []),
+  ];
+  return [
+    "# kf look — 장면별 확인표",
+    "",
+    `장면 모음: \`${sheet}\` — 왼쪽 위부터 오른쪽으로, 줄을 바꿔 가며 장면 차례대로 한 칸씩(4열). 세션이 Read 로 직접 본다.`,
+    "그림을 못 보는 세션이면 `kf look <폴더> --vision-model google/gemini-3.5-flash` 로 다른 모델이 대신 본다.",
+    "정지 그림으로 못 보는 것(0.1초 멈춤·같은 구도·박·섬광·카메라 이동·주인공 가장자리)은 `kf check` 가 본다.",
+    "",
+    "장면마다:",
+    ...common.map((c) => `- [ ] ${c}`),
+    "",
+    ...scenes.flatMap((s, i) => [
+      `## ${i + 1}. ${s.id} — ${s.from.toFixed(2)}–${(s.from + s.dur).toFixed(2)}초${s.role ? ` · ${s.role}` : ""} (칸 ${i + 1})`,
+      "",
+      ...(s.idea ? [`할 일: ${s.idea}`, "", "- [ ] 할 일대로의 화면이다"] : []),
+      "- [ ] 위 「장면마다」를 다 넘는다",
+      "",
+    ]),
+  ].join("\n");
+}
+
+/** 그림을 못 보는 세션용 — 장면 모음을 그림 보는 모델(model)에 보내 장면별 글 보고. 한 번에 1센트 안팎 */
+export async function look(target: string, o: { ask?: string; model?: string } = {}): Promise<LookReport> {
+  const model = o.model ?? DEFAULT_EYES;
+  const { dir, kf } = open(target);
+  const { parts, note } = pictures(target, kf, dir);
+  const scenes = kf?.scenes ?? [];
+  const t = themeOf(kf);
+  const theme = t ? `\n테마 ${t.name} — ${t.metaphor}\n테마 지침(금지 포함):\n${t.guide.slice(0, 2500)}` : "";
+  const prompt = `영상 장면을 검수한다. ${note}
+장면: ${JSON.stringify(scenes.map((s) => ({ id: s.id, from: +s.from.toFixed(2), to: +(s.from + s.dur).toFixed(2), role: s.role, idea: s.idea })))}
+화면 글 정책: ${kf?.text?.policy ?? "모름"}${theme}
+
+장면마다 그림만 보고 문제를 짧게 적는다 — 빈 화면·화면을 못 채운 작은 요소·글자 깨짐(빈 네모·undefined·NaN)·겹침·잘림·대비 낮은 글·할 일(idea)과 다른 화면·테마 위반·뜻 없는 장식(내용과 상관없이 떠다니는 판·빛 방울·큐브·입자)·3D 장면과 2D 장면 사이가 끊김(앞뒤가 다른 세계로 튐). 정지 그림이라 박·움직임은 판단하지 않는다. 문제가 없으면 problems 를 비운다.${o.ask ? `\n그리고 이것에 답한다: ${o.ask}` : ""}
+JSON 하나로만: {"scenes":[{"id":"…","problems":["…"]}],"summary":"전체 한두 문장"${o.ask ? ',"answer":"…"' : ""}}`;
+  const ask = (m: string) => chat(m, [{ role: "user", content: [...parts, { type: "text", text: prompt }] }], { json: true, temperature: 0.2, maxTokens: 6000, stage: "look" });
+  let used = model;
+  let r;
+  try {
+    r = await ask(model);
+  } catch (e) {
+    if (o.model) throw e;
+    used = SPARE_EYES;
+    r = await ask(SPARE_EYES);
+  }
+  const j = jsonBlock<{ scenes?: { id: string; problems?: string[] }[]; summary?: string; answer?: string }>(r.text);
+  if (!j) throw new Error(`그림 보는 모델 답을 못 읽었다: ${r.text.slice(0, 200)}`);
+  const byId = new Map((j.scenes ?? []).map((s) => [s.id, s.problems ?? []]));
+  const rows: LookScene[] = scenes.length
+    ? scenes.map((s) => {
+        const problems = byId.get(s.id) ?? [];
+        return { id: s.id, from: s.from, to: s.from + s.dur, ok: !problems.length, problems };
+      })
+    : (j.scenes ?? []).map((s) => ({ id: s.id, from: 0, to: 0, ok: !s.problems?.length, problems: s.problems ?? [] }));
+  return { model: used, scenes: rows, summary: j.summary ?? "", answer: j.answer, ms: r.ms };
+}
+
+export function formatLook(r: LookReport): string {
+  const bad = r.scenes.filter((s) => !s.ok);
+  return [
+    `kf look — ${r.model} · ${(r.ms / 1000).toFixed(1)}초 · 장면 ${r.scenes.length}개 중 문제 ${bad.length}개`,
+    ...r.scenes.map((s) => `${s.ok ? "  통과" : "  [문제]"} ${s.id}${s.to ? ` ${s.from.toFixed(2)}–${s.to.toFixed(2)}초` : ""}${s.problems.length ? ` — ${s.problems.join(" / ")}` : ""}`),
+    r.summary ? `요약: ${r.summary}` : "",
+    r.answer ? `답: ${r.answer}` : "",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}