kasaframe 0.1.3 → 0.1.4

package/README.md

@@ -81,7 +81,7 @@ kf skill install                   # ~/.claude/skills/kasaframe 에 스킬 링
 | `kf narrate` | 내레이션 먼저 — 장면별 문장을 TTS 로 읽혀 장면 길이를 목소리에 맞추고(곡이 있으면 박에), 자막을 목소리 시각으로 |
 | `kf music` | 곡 모음(분위기 태그) 보기·넣기, 음악 생성(Lyria · Eleven Music) |
 | `kf transitions` | 전환 목록 — 이름·출처·라이선스 |
-| `kf theme list` · `kf theme sheet` | 테마 — `riso-zine` · `debug-hud` · `og-measure`, 같은 문장 한 장면을 테마마다 찍은 견본 격자 |
+| `kf theme list [--variants]` · `kf theme sheet [--variants <세계\|all>]` · `kf theme vary <세계\|all>` · `kf theme suggest [--json]` | 테마 — 세계(`riso-zine` · `debug-hud` · `og-measure` …)와 겉모습만 바꾼 변주(`og-measure/night-amber`), 같은 문장 한 장면을 테마마다 찍은 견본 격자, 변주 뽑기, 요청에 맞는 후보(kf make 의 테마 질문과 같은 고르기) |
 | `kf app` | 작업실 — 요청 칸·실시간 미리보기·렌더·검사 보고를 브라우저로(:5150) |
 | `kf doctor` · `kf setup` | 바깥 도구 점검 · 깔기 |
 | `kf skill` | Claude Code 스킬 링크 |

package/docs/AGENTS.md

@@ -13,7 +13,7 @@ kf make "카사텀 홍보 영상 1분, 카와이 퓨처베이스" [--music 곡.m
 - **그림 보기는 세션이 직접**: `kf look <폴더|mp4>` 가 장면 모음(`out/look-sheet.png`)과 장면별 확인표(`out/look.md` — 빈 화면·글 깨짐·대비·잘림·주인공 자리·할 일·테마)를 만들고 경로만 찍는다. 외부 모델을 부르지 않는다. **눈 없는 모델**(Claude Code 를 OG 로 딥시크 같은 모델에 붙였을 때 — OG `/v1/messages` 는 그림을 버려서 Read 해도 안 보인다)만 `kf look <폴더|mp4> --vision-model google/gemini-3.5-flash [--ask "<볼 것>"]` 로 그림 보는 모델이 장면마다 글로 보고한다(한 번 1센트 안팎, 묻지 않고 써도 된다). `kf make --finish` 도 기본은 그림 보는 모델 없이 끝에 장면 모음·확인표 경로를 찍는다.
 - **곡**: 홍보·공개·뮤비는 곡이 끌고 간다. `--music` 을 안 주면 곡 모음(`KF_MUSIC_DIR`, 없으면 레포 `music/` — 곡마다 원본·라이선스·분위기 태그는 `music/tags.json`·`README.md`. npm 패키지에는 곡이 없다)에서 요청 낱말과 맞는 곡을 고른다. 곡 모음이 비었으면 `--music` 으로 준다.
 - **목소리·곡(쇼츠·설명)**: 차분한 TTS 내레이션 + 깊은 앰비언트 곡(`deep`)이 기본이다. 곡은 분위기 태그가 맞는 곡 모음 곡을 묻지 않고 고르고(같은 틀이면 늘 같은 곡), 없으면 생성(Lyria·Eleven Music, 돈)·곡 넣기·없음을 묻는다. 목소리는 늘 맨 위 질문으로 묻는다 — 보기 차례 로컬 Qwen3(`KF_QWEN3_TTS_URL` 이 있을 때)·ElevenLabs(키가 없으면 넣는 법)·자막만·그 밖 엔진(`kf narrate --voices`). 로컬도 ElevenLabs 도 없거나 생성 키가 없으면 다른 엔진·「자막만」·「곡 없이」로 넘어가지 말고 맨 위 질문대로 사람에게 묻는다(키 넣기가 권장). 묻지 않으려면 `--voice <엔진>:<목소리>|none`·`--music <곡>|gen:lyria-3.5|none`. 그다음은 아래 「내레이션 먼저」.
-- **용도·테마**: 용도는 확신이 낮을 때만 묻는다. 테마는 요청이 「리소 느낌으로」처럼 짚었거나 시리즈가 정했으면 그대로, 아니면 맨 위 질문으로 묻는다 — 보기는 「알아서」(= `auto`: 내용에 맞는 approved 후보 셋 중 첫째, 첫 장면을 셋 다 찍어 `out/theme-<id>.png`)와 이 용도의 approved 테마 전부(생김새 한 줄·2D/3D·견본 `themes/_sheet/<id>.png` — 같은 문장을 테마마다 찍은 격자는 `kf theme sheet`). 답이 오기 전 뼈대는 auto 로 깔려 있다. 못 박으려면 `--purpose <용도>`·`--theme <id>`, 테마 없이 프리셋만이면 `--theme none`. **시리즈**(`kf series list` — 예 「OG 쇼츠」)를 짚으면 용도·테마보다 먼저 그 묶음(용도·테마·목소리·곡·자막·길이·끝 카드·생성 답)으로 묻지 않고 간다 — 같은 시리즈면 매번 같다. 잘 나온 프로젝트를 묶음으로: `kf series new <id> --from <폴더> --match "…"`. 같은 말이 같은 결과를 내는지는 `kf bench "<요청>" --runs 3`. 묻는 것은 용도 확신이 낮을 때뿐(종료 코드 3).
+- **용도·테마**: 용도는 확신이 낮을 때만 묻는다. 테마는 요청이 「리소 느낌으로」처럼 짚었거나 시리즈가 정했으면 그대로, 아니면 맨 위 질문으로 묻는다 — 테마는 「세계 × 변주」(세계 = 비유와 효과 코드, 변주 = 겉모습만 바꾼 판 `<세계>/<변주>`, 예 `og-measure/night-amber`)라 수백 판이고, 보기는 「알아서」(= `auto`, 첫 후보)와 요청·용도·분위기 낱말에 맞는 넷뿐이다. 질문 글에 넷만 담은 견본 시트 경로가 붙는다 — 그 그림을 사람에게 보인다. 사람이 보기 밖으로 분위기 한 마디나 그림·주소를 주면 `kf make --answer <폴더> --theme-mood "<말>"`·`--theme-ref <경로|URL>` 로 넣는다(후보 넷·시트·MAKE.md 를 다시 고쳐 쓰고 종료 3 — 다시 묻는다). 답이 오기 전 뼈대는 첫 후보로 깔려 있다. 못 박으려면 `--purpose <용도>`·`--theme <id>`, 테마 없이 프리셋만이면 `--theme none`. **시리즈**(`kf series list` — 예 「OG 쇼츠」)를 짚으면 용도·테마보다 먼저 그 묶음(용도·테마·목소리·곡·자막·길이·끝 카드·생성 답)으로 묻지 않고 간다 — 같은 시리즈면 매번 같다. 잘 나온 프로젝트를 묶음으로: `kf series new <id> --from <폴더> --match "…"`. 같은 말이 같은 결과를 내는지는 `kf bench "<요청>" --runs 3`. 묻는 것은 용도 확신이 낮을 때뿐(종료 코드 3).
 - **작업실**: `kf app` 이 떠 있으면 `kf make` 가 거기에 등록하고 주소를 찍는다 — 사람은 페이지에서 실시간 미리보기·지난 작업을 본다.
 - **Claude Code 스킬**: `kf skill install` 하면 「영상 만들어」 같은 말에 kasaframe 으로 오는 스킬이 깔린다(`skills/kasaframe/SKILL.md`).
 - **생성 능력**(`kf doctor` 「생성 능력」): 계획은 그림 컷·주인공 3D 장면(Blender 툰 샷, 없으면 three.js)·이음매 3D 전환(three)·캐릭터가 실제로 움직이는 컷(영상 모델 — 요청에 캐릭터와 몸짓이 있거나 뮤비일 때)·곡·내레이션을 기본으로 넣는다. **묻는 것은 돈이 들거나 없는 능력뿐**이고 나머지는 틀·테마가 정한 기본값으로 간다 — 같은 말이면 같은 결과. **없는 능력은 조용히 대체하지 않는다** — 「키·도구 넣는 법(권장) · 지금 되는 다른 엔진 · 빼기(자막만·곡 없이)」를 사람에게 묻고 고른 값을 플래그로 넣는다. 네가 대신 길을 고르지 않는다(`--yes` 로도 안 넘어간다). 키는 `kf setup key <이름>` 이 숨겨 받는다. 묻지 않고 가려면 `--yes`(권장 답 — 돈도 쓴다) · `--no-gen`(돈 안 드는 길) · `--allow image,video,…`(목록 능력만 권장, 나머지는 돈 안 드는 길) · `--image`·`--video`·`--blender`·`--voice`·`--music <값>`(그 질문에 미리 답). OG 모드는 뼈대 전에 터미널에서 묻고, 터미널이 아니면 보기를 찍고 종료 코드 3.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kasaframe",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "말로 시키는 코드 영상 엔진 — 쇼츠·홍보·설명·뮤비를 장면 파일로 짜고 박에 맞춰 MP4 로 굽고 검사한다",
   "keywords": [
     "video",

package/packages/adapters/src/project.ts

@@ -10,6 +10,7 @@ import {
   type SceneCtx,
 } from "@kasaframe/core";
 import { definePage, type KfMarker, type KfMode, type KfPage } from "./page.ts";
+import { textureLayer } from "./texture.ts";
 
 export interface KfSceneEntry {
   id: string;
@@ -180,6 +181,9 @@ export function mountProject(o: MountOptions): KfPage {
       }
       live.push({ entry, root, draw });
     }
+    // 변주 질감은 장면들 위·자막 아래 한 겹 — 장면 파일은 그대로다
+    const tex = style ? textureLayer(document, style.look?.texture, style.scheme, Math.min(kf.width, kf.height) / 1080) : null;
+    if (tex) stage.appendChild(tex);
     // 자막 판은 장면들 위 한 겹 — 장면 파일은 그대로다
     captions = (await caps?.mount(stage, style)) ?? null;
   }

package/packages/adapters/src/texture.ts

@@ -0,0 +1,94 @@
+import { rand, type StyleLook } from "@kasaframe/core";
+
+// 변주 질감 — 세계 코드를 안 고치고 겉모습만 바꾸는 길이라 엔진이 장면 위·자막 아래 한 겹으로 깐다.
+// 서 있는 그림 한 장(정지 화면 검사·섬광 검사에 안 걸린다), 무늬는 씨앗 고정이라 어느 탭에서 찍어도 같다.
+
+type Texture = NonNullable<StyleLook["texture"]>;
+
+function tile(doc: Document, w: number, h: number, paint: (img: ImageData) => void): string {
+  const c = doc.createElement("canvas");
+  c.width = w;
+  c.height = h;
+  const g = c.getContext("2d")!;
+  const img = g.createImageData(w, h);
+  paint(img);
+  g.putImageData(img, 0, 0);
+  return c.toDataURL("image/png");
+}
+
+/** 점 하나 — 어두운 바탕엔 흰 티, 밝은 바탕엔 검은 티 */
+function dot(img: ImageData, i: number, ink: number, alpha: number) {
+  const o = i * 4;
+  img.data[o] = img.data[o + 1] = img.data[o + 2] = ink;
+  img.data[o + 3] = Math.max(0, Math.min(255, Math.round(alpha * 255)));
+}
+
+// 이어 붙여도 이음매가 없는 값 잡음 — 격자를 둘레로 감는다
+function wrapNoise(seed: string, x: number, y: number, cells: number, size: number): number {
+  const fx = (x / size) * cells;
+  const fy = (y / size) * cells;
+  const x0 = Math.floor(fx);
+  const y0 = Math.floor(fy);
+  const v = (i: number, j: number) => rand(seed, ((i % cells) + cells) % cells + (((j % cells) + cells) % cells) * cells);
+  const sx = fx - x0;
+  const sy = fy - y0;
+  const ux = sx * sx * (3 - 2 * sx);
+  const uy = sy * sy * (3 - 2 * sy);
+  const a = v(x0, y0) + (v(x0 + 1, y0) - v(x0, y0)) * ux;
+  const b = v(x0, y0 + 1) + (v(x0 + 1, y0 + 1) - v(x0, y0 + 1)) * ux;
+  return a + (b - a) * uy;
+}
+
+export function textureLayer(doc: Document, tex: Texture | undefined, scheme: "light" | "dark", scale: number): HTMLDivElement | null {
+  if (!tex || tex.kind === "none" || !(tex.amount > 0)) return null;
+  const el = doc.createElement("div");
+  el.dataset.kfTexture = tex.kind;
+  el.style.cssText = `position:absolute;inset:0;pointer-events:none;z-index:49;opacity:${Math.min(1, tex.amount)}`;
+  const ink = scheme === "dark" ? 255 : 0;
+  const rgb = scheme === "dark" ? "255,255,255" : "0,0,0";
+  const s = Math.max(1, scale);
+  if (tex.kind === "scan") {
+    el.style.backgroundImage = `repeating-linear-gradient(0deg, rgba(${rgb},0.5) 0 ${s}px, transparent ${s}px ${4 * s}px)`;
+  } else if (tex.kind === "halftone") {
+    el.style.backgroundImage = `radial-gradient(rgba(${rgb},0.55) ${1.2 * s}px, transparent ${1.7 * s}px)`;
+    el.style.backgroundSize = `${7 * s}px ${7 * s}px`;
+  } else if (tex.kind === "grain") {
+    const n = 160;
+    el.style.backgroundImage = `url(${tile(doc, n, n, (img) => {
+      for (let i = 0; i < n * n; i++) {
+        const v = rand("kf-grain", i) - 0.5;
+        dot(img, i, v < 0 ? 255 - ink : ink, Math.abs(v) * 0.5);
+      }
+    })})`;
+    el.style.backgroundSize = `${n * s}px ${n * s}px`;
+  } else if (tex.kind === "noise") {
+    const n = 96;
+    el.style.backgroundImage = `url(${tile(doc, n, n, (img) => {
+      for (let i = 0; i < n * n; i++) dot(img, i, ink, rand("kf-noise", i) ** 2 * 0.6);
+    })})`;
+    el.style.backgroundSize = `${n * 3 * s}px ${n * 3 * s}px`;
+    el.style.imageRendering = "pixelated";
+  } else if (tex.kind === "paper") {
+    // 종이 — 큰 얼룩 두 겹에 짧은 섬유
+    const n = 256;
+    el.style.backgroundImage = `url(${tile(doc, n, n, (img) => {
+      for (let y = 0; y < n; y++)
+        for (let x = 0; x < n; x++) {
+          const v = 0.6 * wrapNoise("kf-paper-a", x, y, 6, n) + 0.4 * wrapNoise("kf-paper-b", x, y, 24, n) + 0.25 * (rand("kf-paper-c", x + y * n) - 0.5);
+          dot(img, x + y * n, ink, Math.max(0, v - 0.35) * 0.32);
+        }
+      for (let f = 0; f < 140; f++) {
+        let x = rand("kf-fiber", f * 4) * n;
+        let y = rand("kf-fiber", f * 4 + 1) * n;
+        const a = rand("kf-fiber", f * 4 + 2) * Math.PI * 2;
+        const len = 6 + rand("kf-fiber", f * 4 + 3) * 18;
+        for (let k = 0; k < len; k++, x += Math.cos(a), y += Math.sin(a)) {
+          const i = (((Math.round(x) % n) + n) % n) + (((Math.round(y) % n) + n) % n) * n;
+          dot(img, i, ink, Math.max(img.data[i * 4 + 3] / 255, 0.16));
+        }
+      }
+    })})`;
+    el.style.backgroundSize = `${n * 2 * s}px ${n * 2 * s}px`;
+  }
+  return el;
+}

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/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);