kasaframe 0.1.3 → 0.1.5

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/doctor.ts

@@ -5,14 +5,27 @@ import { join } from "node:path";
 import type { Command } from "../command.ts";
 import { checks, pad, report } from "../deps.ts";
 import { repoRoot } from "../serve.ts";
+import { commandFor, isNewer, refresh } from "../update.ts";
+
+async function versionLine(now: string): Promise<string> {
+  try {
+    const latest = await refresh(5000);
+    if (!isNewer(latest, now)) return `판: 지금 ${now} · 최신 ${latest} — 최신이다`;
+    const command = commandFor(latest);
+    return `판: 지금 ${now} · 최신 ${latest} · ${command ? `올리기 kf update (${command.join(" ")})` : "레포 체크아웃 — git pull"}`;
+  } catch (e) {
+    return `판: 지금 ${now} · 최신을 확인하지 못했다(${(e as Error).message}) — kf update --check`;
+  }
+}
 
 const cmd: Command = {
-  summary: "바깥 도구 점검 — ffmpeg·크롬(Playwright)·python3+librosa·OG 키, 없으면 까는 명령",
+  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`);
+    console.log(`kasaframe ${version} · Node ${process.version} · ${platform()} ${arch()}`);
+    console.log(`${await versionLine(version)}\n`);
     const list = await checks();
     report(list);
     const missing = list.filter((c) => c.required && !c.ok);

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

@@ -0,0 +1,118 @@
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { type FontPair, fontGroups, fontPairs } from "@kasaframe/themes/fonts";
+import { type Command, parseFlags } from "../command.ts";
+import { checkFonts, fontCacheDir, fontSheet, noticeSection, type PairReport, replaceNotice } from "../fonts.ts";
+
+const cmd: Command = {
+  summary: "글꼴 짝 검사·견본 격자 — 주소·판·라이선스 글·한글 덮음·굵기, 크롬으로 찍어 투명·두부·떨어짐",
+  usage: `kf fonts list [--group <무리>]
+kf fonts check [--group <무리>[,…]] [--id <짝>[,…]] [--json] [--no-render] [--offline]
+kf fonts sheet [--group <무리>[,…]] [--id <짝>[,…]] [--out 파일.png] [--share]
+kf fonts notice [--write]
+
+  짝 목록은 packages/themes/kit/fonts.json(무리 core)과 kit/fonts/<무리>.json 을 합친 것.
+  check 는 짝마다
+    - 칸: hangul(full|ks2350)·face 마다 license·source, 스택 첫 글꼴의 face, 모든 스택이 Pretendard Variable 로 끝남
+    - 주소: 파일·라이선스 글이 200, 판 박힘(jsdelivr gh@커밋|태그·npm@x.y.z — @main·@latest·@5 는 안 된다)
+    - 라이선스 글: OFL-1.1·Apache-2.0 은 글에 그 문구가 있는지. 목록 밖 이름은 사람이 읽을 것으로 남긴다
+    - 파일: 한글 음절 수(11,172 = full, KS X 1001 2,350 다 = ks2350, 그 아래는 탈락)와 적은 hangul 이 맞는지,
+      적은 굵기 범위가 파일(wght 축·usWeightClass)과 맞는지, 제목 굵기 단이 있는지(없으면 가짜 굵기)
+    - 크롬: 스택마다 한글·라틴·숫자 견본 한 줄을 찍어 투명·두부·시스템 글꼴로 떨어짐·예상과 다른 face 를 잡는다
+  받은 파일은 ${fontCacheDir()}/files 에 두고 다음부터는 주소가 살았는지만 묻는다. 문제가 있는 짝이 있으면 종료 1.
+  --json      { pairs: [{ id, group, ok, hangul, syllables, boldest, licenses, problems, notes }], summary }
+  --no-render 크롬 없이(파일·주소만)
+  --offline   주소를 묻지 않고 캐시만(라이선스 글 대조도 건너뛴다)
+  sheet 는 짝마다 제목·본문·고정폭 견본 칸을 격자 한 장으로 — 기본 ${fontCacheDir()}/sheet[-<무리>].png.
+  --share 면 kasaterm 공유 폴더 kasaframe-글꼴 로 옮긴다.
+  notice 는 모든 무리를 합친 목록으로 NOTICE 의 글꼴 절(글꼴 이름 · 라이선스 · 라이선스 글)을 찍는다. --write 면 레포 NOTICE 에
+  그 절을 갈아 끼운다 — 무리 파일을 고친 뒤 한 번.`,
+  async run(argv) {
+    const [sub, ...rest] = argv;
+    const { opts } = parseFlags(rest);
+    const list = pick(opts);
+    if (!list) return 2;
+    if (sub === "list" || !sub) {
+      for (const { group, pair } of list) console.log(`${group.padEnd(10)} ${pair.id.padEnd(26)} ${String(pair.hangul ?? "?").padEnd(7)} ${pair.tags.join(",").padEnd(30)} ${pair.name}`);
+      console.log(`짝 ${list.length}`);
+      return 0;
+    }
+    if (sub === "check") {
+      const reports = await checkFonts(list, { offline: !!opts.offline, render: !opts["no-render"], log: (l) => console.error(l) });
+      const summary = summarize(reports);
+      if (opts.json) console.log(JSON.stringify({ pairs: reports, summary }, null, 1));
+      else print(reports, summary);
+      return reports.every((r) => r.ok) ? 0 : 1;
+    }
+    if (sub === "notice") {
+      const section = noticeSection(fontPairs());
+      if (!opts.write) {
+        process.stdout.write(section);
+        return 0;
+      }
+      const file = fileURLToPath(new URL("../../../../NOTICE", import.meta.url));
+      writeFileSync(file, replaceNotice(readFileSync(file, "utf8"), section));
+      console.log(file);
+      return 0;
+    }
+    if (sub === "sheet") {
+      const groups = typeof opts.group === "string" ? opts.group.replace(/,/g, "+") : "";
+      const out = resolve(typeof opts.out === "string" ? opts.out : join(fontCacheDir(), `sheet${groups ? `-${groups}` : ""}.png`));
+      await fontSheet(list, out, { log: (l) => console.error(l) });
+      console.log(out);
+      if (opts.share) {
+        const r = spawnSync("kasaterm-cli", ["share", "new", "kasaframe-글꼴"], { encoding: "utf8" });
+        let dir = r.status === 0 ? (r.stdout.trim().split("\n").pop() ?? "") : "";
+        if (!dir || !existsSync(dir)) {
+          dir = join(homedir(), "Desktop", "kasaframe-글꼴");
+          mkdirSync(dir, { recursive: true });
+        }
+        copyFileSync(out, join(dir, basename(out)));
+        console.log(`공유 폴더 ${dir}`);
+      }
+      return 0;
+    }
+    console.error(`kf fonts: 모르는 하위 명령 ${sub} — list·check·sheet·notice`);
+    return 2;
+  },
+};
+
+function pick(opts: Record<string, string | boolean | undefined>): { group: string; pair: FontPair }[] | null {
+  const groups = fontGroups();
+  const want = typeof opts.group === "string" ? opts.group.split(",") : null;
+  const unknown = want?.filter((g) => !groups.some((x) => x.group === g));
+  if (unknown?.length) {
+    console.error(`kf fonts: 무리 ${unknown.join(",")} 가 없다 — 있는 무리: ${groups.map((g) => g.group).join(" ")}`);
+    return null;
+  }
+  const ids = typeof opts.id === "string" ? new Set(opts.id.split(",")) : null;
+  const list = groups.filter((g) => !want || want.includes(g.group)).flatMap((g) => g.pairs.map((pair) => ({ group: g.group, pair }))).filter(({ pair }) => !ids || ids.has(pair.id));
+  if (ids && list.length < ids.size) console.error(`kf fonts: 없는 짝 — ${[...ids].filter((i) => !list.some((x) => x.pair.id === i)).join(",")}`);
+  return list;
+}
+
+const tally = (xs: string[]) => Object.fromEntries([...new Set(xs)].sort().map((x) => [x, xs.filter((y) => y === x).length]));
+
+function summarize(reports: PairReport[]) {
+  return {
+    pairs: reports.length,
+    ok: reports.filter((r) => r.ok).length,
+    hangul: tally(reports.map((r) => r.hangul ?? "?")),
+    licenses: tally(reports.flatMap((r) => r.licenses)),
+  };
+}
+
+function print(reports: PairReport[], s: ReturnType<typeof summarize>): void {
+  for (const r of reports) {
+    console.log(`${r.ok ? "ok  " : "문제"} ${r.group.padEnd(10)} ${r.id.padEnd(26)} 한글 ${r.hangul ?? "?"}(${r.syllables ?? "?"}) · 굵은 단 ${r.boldest ?? "?"} · ${r.licenses.join(",")}`);
+    for (const p of r.problems) console.log(`       ! ${p}`);
+    for (const n of r.notes) console.log(`       · ${n}`);
+  }
+  const fmt = (o: Record<string, number>) => Object.entries(o).map(([k, v]) => `${k} ${v}`).join(" · ");
+  console.log(`\n짝 ${s.pairs} — 통과 ${s.ok} · 문제 ${s.pairs - s.ok} | 한글 ${fmt(s.hangul)} | 라이선스(짝 기준) ${fmt(s.licenses)}`);
+}
+
+export default cmd;

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

@@ -4,14 +4,15 @@ import { basename, dirname, extname, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { askTerminal, blenderLibDir, capabilities, genImage, genVideo, hasKey, NeedsApproval, parseAllow, type Question, questionsText, seam, seamFrames, settle, still, whereToPut } from "@kasaframe/gen";
-import { applyAnswers, attachStudio, loadSeries, type Series, seriesFromRequest, chat, codeBlock, detect, formatLook, jsonBlock, listTemplates, loadTemplate, look, lookSheet, makePlan, type Message, type Plan, planQuestions, premiumBlock, projectBrief, PURPOSES, type Purpose, readProject, spend, spentLine, WAIT, writeCaptions, writeStats } from "@kasaframe/plan";
+import { applyAnswers, attachStudio, type LookInput, loadSeries, suggestThemes, usableTheme, type Series, seriesFromRequest, chat, codeBlock, detect, formatLook, jsonBlock, listTemplates, loadTemplate, look, lookSheet, makePlan, type Message, type Plan, planQuestions, premiumBlock, projectBrief, PURPOSES, type Purpose, readProject, spend, spentLine, WAIT, writeCaptions, writeStats } from "@kasaframe/plan";
 import { checkContent, contentPrompt, directBrief } from "@kasaframe/director";
 import { transform } from "esbuild";
 import { bundleFor, dressSeed, pickDress } from "@kasaframe/motion/menu";
-import { themeStyle } from "@kasaframe/themes";
+import { themeStyle, worldOf } from "@kasaframe/themes";
 import { captionMode } from "@kasaframe/motion/captions";
 import { jizuraCheck } from "@kasaframe/jizura/install";
 import { openPage } from "../browser.ts";
+import { askThemeTerminal, candidateSheet, refLook } from "../pick.ts";
 import { librosa } from "../deps.ts";
 import { lyricsCheck } from "./lyrics.ts";
 import { type Command, num, parseFlags } from "../command.ts";
@@ -92,8 +93,11 @@ kf make --answer <폴더> --image <값> --video <값> …   Claude Code 모드
   끝날 때(성공·실패·중단) <작업 폴더>/make-stats.json 에 단계별 모델·ms·토큰·usd 와 합계를 남기고 「OG 호출 N번 · 토큰 · $」 한 줄을 찍는다
   --series        시리즈 묶음(series/<id>.json) · none. 안 주면 요청이 짚은 시리즈(「OG 쇼츠」처럼) — 용도·테마·목소리·곡·자막·길이·끝 카드·생성 답을 묻지 않고 그 묶음대로
   --purpose       용도를 못 박는다: ${PURPOSES.join(" · ")}
-  --theme         테마 id · auto(요청이 「리소 느낌」처럼 짚은 테마, 아니면 내용에 맞는 approved 후보 셋 중 첫째. 첫 장면을 셋 다 찍어 out/theme-<id>.png) · none(프리셋만)
-                  안 주면(시리즈가 정하지도 않았으면) 묻는다 — 보기는 approved 테마 전부(생김새 한 줄·2D/3D·견본)와 「알아서」(= auto). kf theme sheet
+  --theme         테마 id·변주 「<세계>/<변주>」 · auto(요청이 「리소 느낌」처럼 짚은 테마, 아니면 요청·분위기에 맞는 approved 후보 중 첫째) · none(프리셋만)
+                  안 주면(시리즈가 정하지도 않았으면) 묻는다 — 보기는 「알아서」(= auto)와 요청·용도·분위기 낱말에 맞는 approved 세계·변주 넷,
+                  넷만 담은 견본 시트를 그 자리에서 만든다(칸은 캐시). 테마 이름이 아닌 말을 주면 분위기 한 마디로 읽는다
+  --theme-mood    분위기 한 마디(「따뜻한 종이 느낌」·「어두운 네온」) — 그걸로 후보 넷을 다시 고른다. --answer 와 함께 주면 다시 묻는다
+  --theme-ref     레퍼런스 그림 경로·그림 주소·웹 페이지 주소 — 바탕·강조색을 읽어 후보 넷을 다시 고른다
   --yes           묻지 않고 권장 답으로 — 돈이 드는 그림·영상도 승인한다(지역 제한이 걸린 H3 는 --video h3-pod 로 짚어야만)
   --max-usd       영상 하나 상한(기본 1)
   --video-provider  영상 공급자를 못 박는다(예: h3-pod — KF_H3_URL·KF_H3_STEPS 필요). 기본은 KF_VIDEO_PROVIDER, 없으면 생성 담당 기본
@@ -228,6 +232,13 @@ async function make(argv: string[], at: Track): Promise<number> {
     return 2;
   }
   const assetFiles = str("assets") ? listFiles(resolve(str("assets")!)) : [];
+  let themeLook: LookInput;
+  try {
+    themeLook = await lookFlags(opts);
+  } catch (e) {
+    console.error(`kf make: ${(e as Error).message}`);
+    return 2;
+  }
   // 시리즈가 먼저 — 같은 시리즈면 매번 같은 묶음. 사람이 따로 준 플래그는 그대로 이긴다
   const series: Series | null = str("series") === "none" ? null : str("series") ? loadSeries(str("series")!) : seriesFromRequest(request);
   if (series) console.error(`시리즈 ${series.id}(${series.label}) — 용도·테마·목소리·곡·자막·길이·끝 카드를 묶음대로`);
@@ -256,8 +267,10 @@ async function make(argv: string[], at: Track): Promise<number> {
 
   // 만들기 전에 묻는다 — 뼈대를 만들고 나서 멈추면 반쯤 만든 폴더가 남는다
   const caps = await capabilities({ probe: true });
-  const draft = makePlan({ request, purpose, assets: assetFiles, music: given ?? null, series: series?.id ?? "none" });
+  const draft = makePlan({ request, purpose, assets: assetFiles, music: given ?? null, series: series?.id ?? "none", look: themeLook });
   const { questions, auto } = planQuestions(draft, caps);
+  // 테마를 물을 거면 후보 넷 견본 시트를 그 자리에서 — 질문 글에 시트 경로가 붙는다
+  const themeQ = questions.find((q) => q.id === "theme");
   const flags = { ...seriesAnswers(series), ...opts };
   const settled = settle(questions, { given: flags, yes: !!opts.yes, noGen: !!opts["no-gen"], allow: parseAllow(opts.allow) });
   // 묻지 않고 정한 답(있는 공짜 능력)도 사람이 준 플래그·시리즈 답이 이긴다. --no-gen 이면 공짜라도 생성 모델(그림·영상)은 뺀다
@@ -282,6 +295,20 @@ async function make(argv: string[], at: Track): Promise<number> {
     answers = { ...answers, ...asked };
   }
   if (answers.beats === "none" && answers.music && !/^(gen:|none$)/.test(answers.music)) answers.music = "none";
+  if (themeQ && open.includes(themeQ)) await candidateSheet(themeQ, (l) => console.error(l));
+  // 터미널이면 테마는 따로 — 분위기 한 마디·그림 경로·주소를 치면 그걸로 후보를 다시 골라 다시 묻는다
+  if (themeQ && open.includes(themeQ) && model !== "claude-code") {
+    const picked = await askThemeTerminal(themeQ, async (r) => {
+      themeLook = { ...themeLook, ...r, ...(r.mood ? { mood: [themeLook.mood, r.mood].filter(Boolean).join(" ") } : {}) };
+      const q = planQuestions(makePlan({ request, purpose, assets: assetFiles, music: given ?? null, series: series?.id ?? "none", look: themeLook }), caps).questions.find((x) => x.id === "theme")!;
+      await candidateSheet(q, (l) => console.error(l));
+      return q;
+    });
+    if (picked) {
+      answers.theme = picked;
+      open = open.filter((q) => q !== themeQ);
+    }
+  }
   if (open.length && model !== "claude-code") {
     const asked = await askTerminal(open);
     if (!asked) {
@@ -307,7 +334,10 @@ async function make(argv: string[], at: Track): Promise<number> {
   if (song) newArgs.push("--music", song);
   if (str("title")) newArgs.push("--title", str("title")!);
   // 테마 질문의 답(플래그·터미널) → 아직 묻는 중이거나 묻지 않은 테마(시리즈·요청이 짚은 것)는 auto. 테마 없이 프리셋만 쓰려면 --theme none
-  newArgs.push("--theme", answers.theme && answers.theme !== WAIT ? answers.theme : (str("theme") ?? "auto"));
+  // 「알아서」·묻는 중이면 후보 첫째 — 분위기·레퍼런스로 고른 넷이라 kf new 의 auto(요청 낱말만)와 다를 수 있다
+  const firstPick = themeQ?.choices.find((c) => c.value !== "auto")?.value;
+  const themeArg = answers.theme && answers.theme !== WAIT && answers.theme !== "auto" ? answers.theme : (str("theme") ?? (firstPick && (answers.theme === "auto" || open.includes(themeQ!)) ? firstPick : "auto"));
+  newArgs.push("--theme", themeArg);
   if (opts.force) newArgs.push("--force");
   const made = spawnSync(process.execPath, newArgs, { stdio: ["ignore", "inherit", "inherit"] });
   if (made.status !== 0) return made.status ?? 1;
@@ -315,7 +345,7 @@ async function make(argv: string[], at: Track): Promise<number> {
   const studio = await attachStudio({ dir, request, model, purpose });
   const unmirror = studio?.mirror();
   if (studio) console.log(`작업실: ${studio.url}`);
-  const plan: Plan = { ...applyAnswers(JSON.parse(readFileSync(join(dir, "plan.json"), "utf8")), answers).plan, asks: open };
+  const plan: Plan = { ...applyAnswers(JSON.parse(readFileSync(join(dir, "plan.json"), "utf8")), answers).plan, asks: open, ...(themeLook.mood || themeLook.ref ? { themeLook } : {}) };
   // 새 프로젝트는 이 영상의 기본으로 적는다 — 계획 다듬기가 내레이션을 쓸지도 이걸 본다
   if (captions) {
     const kfPath = join(dir, "kf.json");
@@ -582,6 +612,19 @@ async function probeScene(dir: string, id: string): Promise<string[]> {
   return [...new Set(problems)];
 }
 
+// 테마 고르기 플래그 — --theme-mood·--theme-ref, 그리고 테마 이름이 아닌 --theme 값(분위기 한 마디로 읽는다)
+async function lookFlags(opts: Record<string, string | boolean | undefined>): Promise<LookInput> {
+  const look: LookInput = {};
+  const theme = typeof opts.theme === "string" ? opts.theme : undefined;
+  if (theme && theme !== "auto" && theme !== "none" && !usableTheme(theme)) {
+    look.mood = theme;
+    delete opts.theme;
+  }
+  if (typeof opts["theme-mood"] === "string") look.mood = [look.mood, opts["theme-mood"]].filter(Boolean).join(" ");
+  if (typeof opts["theme-ref"] === "string") look.ref = await refLook(opts["theme-ref"]);
+  return look;
+}
+
 // 테마 후보마다 첫 장면을 그 테마로 한 장 — 사람이 셋을 나란히 보고 고른다. style.json 만 잠깐 바꿔 찍고 되돌린다
 function themeStills(dir: string, ids: string[]): void {
   const stylePath = join(dir, "style.json");
@@ -734,6 +777,30 @@ async function answerProject(dir: string, opts: Record<string, string | boolean
     return 2;
   }
   const plan: Plan = JSON.parse(readFileSync(file, "utf8"));
+  // 테마에 분위기 한 마디·레퍼런스를 줬으면 후보 넷을 다시 고르고 견본 시트를 새로 만들어 다시 묻는다 — 답은 그다음
+  let look: LookInput;
+  try {
+    look = await lookFlags(opts);
+  } catch (e) {
+    console.error(`kf make --answer: ${(e as Error).message}`);
+    return 2;
+  }
+  if (look.mood || look.ref) {
+    plan.themeLook = { ...plan.themeLook, ...look, ...(look.mood ? { mood: [plan.themeLook?.mood, look.mood].filter(Boolean).join(" ") } : {}) };
+    const q = planQuestions(plan, await capabilities({ probe: false })).questions.find((x) => x.id === "theme");
+    if (!q) {
+      console.error("kf make --answer: 이 프로젝트는 테마를 묻지 않는다(시리즈나 요청이 테마를 정했다) — --theme <id> 로 바꾼다");
+      return 2;
+    }
+    const sheet = await candidateSheet(q, (l) => console.error(l));
+    plan.asks = [...(plan.asks ?? []).filter((x) => x.id !== "theme"), q];
+    writeJson(file, plan);
+    writeFileSync(join(dir, "MAKE.md"), isDirect(dir) ? directBrief(dir) : projectBrief(dir));
+    console.log(`테마 후보를 다시 골랐다${sheet ? ` — 견본 시트 ${sheet}` : ""}:`);
+    for (const c of q.choices) console.log(`  --theme ${c.value.padEnd(30)} ${c.label}${c.note ? ` — ${c.note}` : ""}`);
+    console.error("사람에게 다시 묻고 kf make --answer <폴더> --theme <값> 으로 답을 넣는다");
+    return 3;
+  }
   const waiting = new Set((plan.asks ?? []).map((q) => q.id));
   const fresh = planQuestions(plan, await capabilities({ probe: true })).questions.filter((q) => waiting.has(q.id));
   const settled = settle(fresh, { given: opts, yes: !!opts.yes, noGen: !!opts["no-gen"], allow: parseAllow(opts.allow) });
@@ -765,7 +832,8 @@ function retheme(dir: string, answer: string): string | null {
   const plan = readPlan(dir) as Plan;
   const kfPath = join(dir, "kf.json");
   const kf = JSON.parse(readFileSync(kfPath, "utf8"));
-  const id: string | null = answer === "auto" ? (plan.themeCandidates?.[0]?.id ?? kf.theme ?? null) : answer === "none" ? null : answer;
+  const id: string | null =
+    answer === "auto" ? (suggestThemes(plan.request, plan.purpose, plan.aspect, 1, plan.themeLook ?? {})[0]?.id ?? plan.themeCandidates?.[0]?.id ?? kf.theme ?? null) : answer === "none" ? null : answer;
   if ((kf.theme ?? null) === id) return id;
   const tpl = loadTemplate(plan.purpose);
   // 프리셋으로 돌아가면 kf new 가 테마 없이 골랐을 프리셋 — 시리즈·요청 낱말·틀 차례
@@ -774,7 +842,7 @@ function retheme(dir: string, answer: string): string | null {
   style.motion = { ...style.motion, ...tpl.motion };
   writeJson(join(dir, "style.json"), style);
   if (tpl.moves) {
-    const dress = pickDress(dressSeed(plan.request || plan.title, plan.purpose, id ?? preset!), plan.scenes, bundleFor(tpl.moves, id ?? undefined));
+    const dress = pickDress(dressSeed(plan.request || plan.title, plan.purpose, worldOf(id) ?? preset!), plan.scenes, bundleFor(tpl.moves, id ?? undefined));
     const byId = new Map(plan.scenes.map((s, i) => [s.id, dress[i]]));
     for (const s of kf.scenes as { id: string; file: string; dress?: Record<string, string> }[]) {
       const next = byId.get(s.id);

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

@@ -3,7 +3,7 @@ import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFi
 import { basename, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { bundleFor, dressSeed, NO_DRESS, pickDress } from "@kasaframe/motion/menu";
-import { themeStyle } from "@kasaframe/themes";
+import { themeStyle, worldOf } from "@kasaframe/themes";
 import { type Aspect, type BeatsLike, type Plan, type Purpose, listTemplates, loadTemplate, makePlan, parseTitle, PURPOSES, sceneSkeleton, templatesDir } from "@kasaframe/plan";
 import { type Command, num, parseFlags } from "../command.ts";
 
@@ -116,7 +116,7 @@ kf new <폴더> --plan plan.json                        kf make 가 세운 계
 
     // 장면마다 연출 수(바탕·글·경계 덮기) — 용도 틀·테마 묶음에서 요청 글을 씨앗으로 고른다. 같은 요청이면 같은 수가 걸린다
     // 틀에 묶음이 없으면(뮤비 — 가사 층이 화면을 맡는다) 무대 기본 그대로
-    const dress = tpl.moves ? pickDress(dressSeed(plan.request || plan.title, plan.purpose, plan.theme ?? plan.style), plan.scenes, bundleFor(tpl.moves, plan.theme ?? undefined)) : plan.scenes.map(() => ({ ...NO_DRESS }));
+    const dress = tpl.moves ? pickDress(dressSeed(plan.request || plan.title, plan.purpose, worldOf(plan.theme) ?? plan.style), plan.scenes, bundleFor(tpl.moves, plan.theme ?? undefined)) : plan.scenes.map(() => ({ ...NO_DRESS }));
 
     const frame = { width: plan.width, height: plan.height };
     const safeArea = plan.aspect === tpl.aspect ? tpl.safeArea : (tpl.variants?.[plan.aspect]?.safeArea ?? tpl.safeArea);