kasaframe 0.1.3 → 0.1.4

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

@@ -1,11 +1,14 @@
 import { spawnSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
-import { listThemes, sheetDir, type Theme, themeDims, themesDir } from "@kasaframe/themes";
+import { type Aspect, PURPOSES, type Purpose, suggestThemes } from "@kasaframe/plan";
+import { cellPath, cellsDir, listThemes, listVariants, loadTheme, sheetDir, type Theme, themeDims, themeSample, themesDir } from "@kasaframe/themes";
 import { briefs, review, scaffold, sessionPrompt, setStatus, staticCheck } from "@kasaframe/themes/factory";
 import { launch } from "../browser.ts";
+import { cellFrame, cellOf, ensureCells, type GridCell, gridSheet, SAMPLE } from "../cells.ts";
 import { type Command, num, parseFlags } from "../command.ts";
+import { vary } from "../vary.ts";
 
 const kfBin = new URL("../kf.ts", import.meta.url).pathname;
 
@@ -16,6 +19,19 @@ kf theme new <id> --ref <그림·영상·폴더·URL> [--ref …] [--name 이름
 kf theme check <id> [--no-page]     계약·빈칸 검사 + kf check sample
 kf theme review <id> [--tabs 2]     굽기 → mp4 검사 → 장면 모음·대표 장면 → 공유 폴더 → status review
 kf theme approve <id>               사람이 견본을 보고 OK 한 뒤에만
+kf theme vary <세계|all> [--n 16] [--force] [--seed 글]
+                                    세계 하나에서 겉모습만 바꾼 변주를 기본 포함 n 개까지 — 색 조합(밝음·어두움)·글꼴 짝·질감·선·모서리·빠르기를
+                                    세계 theme.json vary 범위 안에서 섞고, 대비·의미색·색각 이상을 계산으로 거른 뒤 서로 먼 차례로 표준 장면에 입혀
+                                    kf check 를 넘고 이미 뽑은 판과 충분히 다른 것만 themes/<세계>/variants/<이름>.json 에 남긴다(입체 세계는 끝 구간만 검사).
+                                    이미 있으면 모자란 만큼만. all 은 approved 세계 전부. 끝에 그 세계 변주 격자
+kf theme sheet --variants <세계|all> [--share]
+                                    변주 격자 — 세계마다 기본+변주 한 장(<캐시>/theme-cells/<세계>/sheet.png), all 이면 전체 한 장(all.png)과
+                                    목록(변주목록.md)까지. 칸이 없거나 낡으면 그 자리에서 찍는다. --share 면 kasaterm 공유 폴더 kasaframe-테마-변주 로
+kf theme list [--variants [세계]]   세계 목록, --variants 면 변주까지
+kf theme suggest [--request 글] [--purpose ${PURPOSES.join("|")}] [--aspect 9:16|16:9|1:1] [--mood 글] [--use 낱말,…] [--n 4] [--json]
+                                    요청에 맞는 approved 세계·변주 후보 — kf make 의 테마 질문과 같은 고르기(요청 낱말·분위기 낱말·쓰임 낱말).
+                                    --json 이면 { candidates: [{ id, world, variant, name, dims, why, cell, sample }] } — cell 은 칸 캐시
+                                    그림(없으면 null), sample 은 묻기 보기에 붙일 견본(칸 → 견본 시트 칸 → 대표 장면)
 kf theme sheet [--out 파일.png]     approved 테마마다 같은 문장 한 장면(쇼츠 9:16)을 감독 모드로 짓고 검사를 거쳐, 장면 끝 프레임을
                                     격자 한 장으로 — 이름·2D/3D 딱지, 안전 영역 점선. 기본 themes/_sheet/sheet.png, 칸은 그 옆 <id>.png
                                     (kf make 의 테마 질문 보기가 이 칸을 견본으로 짚는다). 검사 오류가 남은 칸은 표시하고 종료 1
@@ -26,13 +42,41 @@ kf theme sheet [--out 파일.png]     approved 테마마다 같은 문장 한
     const [sub, ...rest] = argv;
     const { args, opts } = parseFlags(rest);
     const id = args[0];
+    if (sub === "sheet" && opts.variants) return variantSheets(typeof opts.variants === "string" ? opts.variants : (args[0] ?? "all"), !!opts.share);
     if (sub === "sheet") return sheet(resolve(typeof opts.out === "string" ? opts.out : join(sheetDir, "sheet.png")));
     if (sub === "list" || !sub) {
-      const all = listThemes();
+      const only = typeof opts.variants === "string" ? opts.variants : args[0];
+      const all = listThemes({ variants: !!opts.variants }).filter((t) => !only || t.world === only);
       if (!all.length) console.log("(테마 없음)");
-      for (const t of all) console.log(`${t.id.padEnd(18)} ${t.status.padEnd(9)} ${String(t.approvedAt ?? "").padEnd(11)} 효과 ${String(t.effects.length).padStart(2)} · ${t.metaphor}`);
+      for (const t of all)
+        console.log(
+          t.variant
+            ? `  ${t.id.padEnd(34)} ${t.status.padEnd(9)} ${t.style.scheme.padEnd(5)} · ${t.variant.desc}`
+            : `${t.id.padEnd(18)} ${t.status.padEnd(9)} ${String(t.approvedAt ?? "").padEnd(11)} 효과 ${String(t.effects.length).padStart(2)}${opts.variants ? ` · 변주 ${listVariants(t.id).length}` : ""} · ${t.metaphor}`,
+        );
       return 0;
     }
+    if (sub === "suggest") return suggest(opts);
+    if (sub === "vary") {
+      if (!id) {
+        console.error("kf theme vary: 세계 id 나 all 을 준다");
+        return 2;
+      }
+      const worlds = id === "all" ? listThemes({ status: "approved" }).map((t) => t.id) : [id];
+      let bad = 0;
+      for (const w of worlds) {
+        try {
+          const r = await vary(w, { n: num(opts.n, 16), force: !!opts.force, seed: typeof opts.seed === "string" ? opts.seed : undefined, log: (l) => console.error(l) });
+          console.log(`${w}: 새 변주 ${r.made.length}개 · 있던 것 ${r.kept}개 · 탈락 ${r.rejected.length}개`);
+          if (r.kept + r.made.length + 1 < num(opts.n, 16)) bad++;
+        } catch (e) {
+          console.error(`kf theme vary ${w}: ${(e as Error).message}`);
+          bad++;
+        }
+      }
+      const code = await variantSheets(id, !!opts.share);
+      return bad ? 1 : code;
+    }
     if (!id) {
       console.error(`kf theme ${sub}: 테마 id 가 필요하다. kf theme --help`);
       return 2;
@@ -91,13 +135,38 @@ kf theme sheet [--out 파일.png]     approved 테마마다 같은 문장 한
 
 export default cmd;
 
+const ASPECTS: Aspect[] = ["9:16", "16:9", "1:1"];
+
+// 다른 도구(쇼츠 스킬 따위)가 kf make 와 같은 후보를 받아 가는 자리 — 고르기를 옮겨 적지 않게
+function suggest(opts: Record<string, string | boolean | undefined>): number {
+  const str = (k: string) => (typeof opts[k] === "string" ? (opts[k] as string) : "");
+  const purpose = (str("purpose") || "shorts") as Purpose;
+  const aspect = str("aspect") as Aspect;
+  if (!PURPOSES.includes(purpose)) {
+    console.error(`kf theme suggest: --purpose 는 ${PURPOSES.join("·")} 중 하나`);
+    return 2;
+  }
+  if (aspect && !ASPECTS.includes(aspect)) {
+    console.error(`kf theme suggest: --aspect 는 ${ASPECTS.join("·")} 중 하나`);
+    return 2;
+  }
+  const use = str("use").split(/[,·]/).map((w) => w.trim()).filter(Boolean);
+  const picks = suggestThemes(str("request"), purpose, aspect || undefined, num(opts.n, 4), { mood: str("mood") }, use);
+  const candidates = picks.map(({ id, why }) => {
+    const t = loadTheme(id);
+    return { id, world: t.world, variant: t.variant?.id ?? null, name: t.name, dims: t.tags?.dims ?? themeDims(t), why, cell: existsSync(cellPath(id)) ? cellPath(id) : null, sample: themeSample(t) };
+  });
+  if (opts.json) {
+    console.log(JSON.stringify({ request: str("request"), purpose, aspect: aspect || null, mood: str("mood"), use, candidates }, null, 1));
+    return 0;
+  }
+  if (!candidates.length) console.log("(맞는 approved 테마 없음)");
+  for (const [i, c] of candidates.entries()) console.log(`${i + 1}. ${c.name} · ${c.dims} (${c.id}) — ${c.why}`);
+  return 0;
+}
+
 // 견본 시트 — 테마끼리 견주려면 내용이 같아야 한다. 감독 모드가 실제로 짓는 장면(쇼츠 첫 장면 hook-number)을 테마만 바꿔,
 // 검사를 거쳐(떨어진 패턴은 감독이 다음 후보로 다시 짓는다) 사람이 실제로 받을 화면을 장면 끝 프레임에서 찍는다 — 움직임이 다 앉은 자리
-const SAMPLE = {
-  title: "kasaframe",
-  request: "테마 견본 — 같은 문장을 테마마다",
-  scenes: [{ id: "hook", type: "hook-number", value: 57, unit: "×", label: "KV 캐시가 이만큼 작아진다", source: "DeepSeek-V2 기술 보고서", dur: 4 }],
-};
 
 async function sheet(out: string): Promise<number> {
   const themes = listThemes({ status: "approved" });
@@ -170,3 +239,65 @@ async function sheet(out: string): Promise<number> {
     rmSync(tmp, { recursive: true, force: true });
   }
 }
+
+// 변주 격자 — 세계마다 기본+변주 한 장, all 이면 전체 한 장과 목록. 칸은 캐시(없거나 낡은 것만 찍는다)
+async function variantSheets(which: string, share: boolean): Promise<number> {
+  const worlds = which === "all" ? listThemes({ status: "approved" }).filter((t) => listVariants(t.id).length) : [loadTheme(which)];
+  if (!worlds.length) {
+    console.error("kf theme sheet --variants: 변주를 뽑은 세계가 없다 — kf theme vary <세계>");
+    return 1;
+  }
+  const tmp = mkdtempSync(join(tmpdir(), "kf-variant-sheet-"));
+  const out: string[] = [];
+  const every: { t: Theme; png: string }[] = [];
+  try {
+    for (const w of worlds) {
+      const ids = [w.id, ...listVariants(w.id).map((v) => `${w.id}/${v.id}`)];
+      const cells = ensureCells(ids, join(tmp, w.id), (l) => console.error(l));
+      const themes = ids.filter((i) => cells.has(i)).map((i) => loadTheme(i));
+      const frame = cellFrame(w.id) ?? { width: 1080, height: 1920, safe: { top: 230, bottom: 460, left: 40, right: 40 } };
+      const file = join(cellsDir, w.id, "sheet.png");
+      await gridSheet(
+        themes.map((t) => cellOf(t, cells.get(t.id)!)),
+        file,
+        { heading: `${w.name}(${w.id}) — 기본 + 변주 ${themes.length - 1} · 같은 문장 한 장면(쇼츠 9:16) 끝 프레임 · ${w.status === "approved" ? "세계가 approved 라 검사를 넘은 변주는 바로 쓴다" : "세계가 review 라 변주도 review"} · 빨간 점선 밖은 플랫폼 UI 자리`, cols: 8, w: 240, frame },
+      );
+      console.log(file);
+      out.push(file);
+      every.push(...themes.map((t) => ({ t, png: cells.get(t.id)! })));
+    }
+    let list: string | null = null;
+    if (which === "all") {
+      const frame = cellFrame(worlds[0].id) ?? { width: 1080, height: 1920, safe: { top: 230, bottom: 460, left: 40, right: 40 } };
+      const all = join(cellsDir, "all.png");
+      await gridSheet(
+        every.map(({ t, png }): GridCell => ({ png, title: t.variant ? t.variant.name : `${t.world} 기본`, sub: t.world, swatches: [t.style.colors.bg, t.style.colors.ink, t.style.colors.accent] })),
+        all,
+        { heading: `approved 세계 ${worlds.length} × 변주 — 모두 ${every.length}판 · 같은 문장 한 장면`, cols: 16, w: 150, frame },
+      );
+      console.log(all);
+      out.push(all);
+      list = join(cellsDir, "변주목록.md");
+      writeFileSync(
+        list,
+        [`# kasaframe 테마 변주 — ${every.length}판`, "", "부르는 이름은 `<세계>/<변주>` — `kf make --theme`·`kf new --theme`·시리즈 `theme`·kf.json `theme` 어디서나.", "", "| 이름 | 밝기 | 설명 | 분위기 |", "|---|---|---|---|",
+          ...every.map(({ t }) => `| \`${t.id}\` | ${t.style.scheme} | ${t.variant?.desc ?? `세계 그대로 — ${t.metaphor}`} | ${(t.tags?.mood ?? []).join("·")} |`)].join("\n") + "\n",
+      );
+      console.log(list);
+    }
+    if (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 });
+      }
+      for (const f of out) copyFileSync(f, join(dir, f.endsWith("all.png") ? "전체.png" : `${f.split("/").at(-2)}.png`));
+      if (list) copyFileSync(list, join(dir, "변주목록.md"));
+      console.log(`공유 폴더 ${dir}`);
+    }
+    return 0;
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}

package/packages/cli/src/lock.ts

@@ -31,18 +31,20 @@ export async function acquireRenderLock(dir: string, waitSec: number): Promise<(
       mkdirSync(LOCK);
       writeFileSync(join(LOCK, "owner.json"), JSON.stringify({ pid: process.pid, dir, started: new Date().toISOString() }));
       let held = true;
+      const onSig = () => {
+        release();
+        process.exit(130);
+      };
+      // 한 프로세스가 잠금을 여러 번 쥐었다 놓는다(kf theme vary 는 변주마다) — 놓을 때 건 귀를 떼야 쌓이지 않는다
       const release = () => {
         if (!held) return;
         held = false;
+        process.off("exit", release);
+        for (const sig of ["SIGINT", "SIGTERM"] as const) process.off(sig, onSig);
         if (owner()?.pid === process.pid) rmSync(LOCK, { recursive: true, force: true });
       };
       process.once("exit", release);
-      for (const sig of ["SIGINT", "SIGTERM"] as const) {
-        process.once(sig, () => {
-          release();
-          process.exit(130);
-        });
-      }
+      for (const sig of ["SIGINT", "SIGTERM"] as const) process.once(sig, onSig);
       return release;
     } catch (err) {
       if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;

package/packages/cli/src/pick.ts

@@ -0,0 +1,110 @@
+// kf make 테마 고르기 — 후보 넷만 담은 견본 시트를 그 자리에서(칸은 캐시), 레퍼런스 그림·주소에서 생김새 읽기, 터미널에서 분위기 한 마디로 다시 고르기
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import type { Question } from "@kasaframe/gen";
+import { cellsDir, loadTheme } from "@kasaframe/themes";
+import { refFromPixels, type RefLook } from "@kasaframe/themes/look";
+import { launch } from "./browser.ts";
+import { cellFrame, cellOf, ensureCells, gridSheet } from "./cells.ts";
+
+const IMAGE = /\.(png|jpe?g|webp|gif|bmp|avif)(\?.*)?$/i;
+
+function pixels(file: string): Uint8Array {
+  const r = spawnSync("ffmpeg", ["-v", "error", "-i", file, "-frames:v", "1", "-vf", "scale=48:48:flags=area", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"], { maxBuffer: 1 << 20 });
+  if (r.status !== 0 || !r.stdout?.length) throw new Error(`레퍼런스 ${file} 를 못 읽었다 — ${String(r.stderr ?? "").trim().split("\n").pop()}`);
+  return new Uint8Array(r.stdout);
+}
+
+/** 그림 파일·그림 주소·웹 페이지 주소(첫 화면을 찍는다) → 생김새 */
+export async function refLook(src: string): Promise<RefLook> {
+  if (!/^https?:\/\//.test(src)) {
+    const file = resolve(src);
+    if (!existsSync(file)) throw new Error(`레퍼런스 ${src} 가 없다`);
+    return refFromPixels(pixels(file), src);
+  }
+  const tmp = mkdtempSync(join(tmpdir(), "kf-ref-"));
+  try {
+    const file = join(tmp, "ref.png");
+    const head = await fetch(src, { method: "GET" }).catch(() => null);
+    const type = head?.headers.get("content-type") ?? "";
+    if (head?.ok && (type.startsWith("image/") || IMAGE.test(src))) writeFileSync(join(tmp, "ref"), Buffer.from(await head.arrayBuffer()));
+    else {
+      const browser = await launch();
+      try {
+        const page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
+        await page.goto(src, { waitUntil: "load", timeout: 30_000 });
+        await page.waitForTimeout(800);
+        writeFileSync(file, await page.screenshot({ type: "png" }));
+      } finally {
+        await browser.close();
+      }
+    }
+    return refFromPixels(pixels(existsSync(file) ? file : join(tmp, "ref")), src);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+const candidatesOf = (q: Question) => q.choices.map((c) => c.value).filter((v) => v !== "auto" && v !== "none");
+
+/** 후보 넷 견본 시트 — 칸이 없거나 낡은 후보만 그 자리에서 찍고, 시트 경로를 질문 글에 붙인다 */
+export async function candidateSheet(q: Question, log: (l: string) => void = () => {}): Promise<string | null> {
+  const ids = candidatesOf(q);
+  if (!ids.length) return null;
+  const tmp = mkdtempSync(join(tmpdir(), "kf-pick-"));
+  try {
+    const cells = ensureCells(ids, tmp, log);
+    const have = ids.filter((id) => cells.has(id));
+    if (!have.length) return null;
+    const out = join(cellsDir, "picks", `${createHash("sha256").update(have.join("|")).digest("hex").slice(0, 12)}.png`);
+    const frame = cellFrame(have[0]) ?? { width: 1080, height: 1920, safe: { top: 230, bottom: 460, left: 40, right: 40 } };
+    await gridSheet(
+      have.map((id, i) => {
+        const t = loadTheme(id);
+        return { ...cellOf(t, cells.get(id)!), title: `${i + 1}. ${t.name}` };
+      }),
+      out,
+      { heading: "테마 후보 — 같은 문장 한 장면(쇼츠 9:16) 끝 프레임. 번호는 보기 차례", cols: have.length, w: 300, frame },
+    );
+    q.ask = `${q.ask} — 후보 견본 시트 ${out}`;
+    return out;
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+export interface Retry {
+  mood?: string;
+  ref?: RefLook;
+}
+
+/**
+ * 터미널 테마 묻기 — 번호로 고르거나, 분위기 한 마디·그림 경로·주소를 치면 그걸로 후보를 다시 고른다(again 이 새 질문을 돌려준다).
+ * 터미널이 아니면 null
+ */
+export async function askThemeTerminal(first: Question, again: (r: Retry) => Promise<Question>): Promise<string | null> {
+  if (!process.stdin.isTTY) return null;
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  let q = first;
+  try {
+    for (;;) {
+      const lines = q.choices.map((c, i) => `  ${i + 1}) ${c.label}${c.value === q.default ? " (권장)" : ""}${c.note ? ` — ${c.note}` : ""}`).join("\n");
+      const a = (await rl.question(`\n${q.ask}\n${lines}\n번호(엔터 = 알아서) · 분위기 한 마디 · 그림 경로·주소: `)).trim();
+      if (a === "") return q.default;
+      if (/^\d+$/.test(a) && q.choices[Number(a) - 1]) return q.choices[Number(a) - 1].value;
+      if (q.accepts?.(a)) return a;
+      const isRef = /^https?:\/\//.test(a) || IMAGE.test(a) || existsSync(resolve(a));
+      try {
+        q = await again(isRef ? { ref: await refLook(a) } : { mood: a });
+      } catch (e) {
+        process.stderr.write(`${(e as Error).message}\n`);
+      }
+    }
+  } finally {
+    rl.close();
+  }
+}

package/packages/cli/src/vary.ts

@@ -0,0 +1,124 @@
+// kf theme vary — 세계 하나에서 변주를 뽑는다. 색 검사(대비·의미색·색각 이상)는 계산으로 먼저 거르고,
+// 남은 후보를 서로 먼 차례로 표준 장면에 입혀 kf check 와 칸 그림 차이까지 넘은 것만 themes/<세계>/variants/ 에 남긴다.
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cellPath, listVariants, loadTheme, themeDims, variantsDir, type Theme, type ThemeTags, type ThemeVary, type VariantManifest } from "@kasaframe/themes";
+import { candidateOf, mergeVariant, nameVariant, rankCandidates, variantTags } from "@kasaframe/themes/vary";
+import { checkProject, imageDiff, markCell, restyle, standardProject, still, thumb } from "./cells.ts";
+import { acquireRenderLock } from "./lock.ts";
+
+/** 세계가 vary 를 안 적었을 때 — 새 세계도 approved 가 되면 한 줄로 뽑히게, 세계 밝기·글꼴·질감은 그대로 두고 색만 돈다 */
+export const defaultVary = (t: Theme): ThemeVary => ({ scheme: [t.style.scheme], hue: [[0, 360]], chroma: [0.85, 1.15], tint: [0, 0.025], fonts: ["base"], texture: ["none"], tempo: [0.9, 1.15] });
+
+export const defaultTags = (t: Theme): ThemeTags => ({ mood: [], light: t.style.scheme, use: [...t.purposes], dims: themeDims(t) });
+
+// 칸 그림 평균 화소 차가 이 아래면 이미 뽑은 판과 같은 판으로 본다
+const SAME_LOOK = 0.035;
+
+export interface VaryResult {
+  made: VariantManifest[];
+  kept: number;
+  rejected: { id: string; why: string }[];
+}
+
+export async function vary(world: string, o: { n: number; force?: boolean; seed?: string; log: (l: string) => void }): Promise<VaryResult> {
+  const t = loadTheme(world);
+  if (t.variant) throw new Error(`${world} 는 변주다 — 세계 id 를 준다`);
+  if (t.status === "draft") throw new Error(`${world} 는 draft — review·approved 세계만 변주를 뽑는다`);
+  const spec = t.vary && Object.keys(t.vary).length ? t.vary : defaultVary(t);
+  if (spec !== t.vary) o.log(`${world}: theme.json 에 vary 가 없어 색만 도는 기본 범위로(밝기·글꼴·질감은 세계 그대로)`);
+  if (o.force) for (const v of listVariants(world)) unlinkSync(join(variantsDir(world), `${v.id}.json`));
+  const existing = listVariants(world);
+  const need = o.n - 1 - existing.length;
+  const result: VaryResult = { made: [], kept: existing.length, rejected: [] };
+  if (need <= 0) {
+    o.log(`${world}: 이미 변주 ${existing.length}개(기본 포함 ${existing.length + 1}) — 다시 뽑으려면 --force`);
+    return result;
+  }
+  const solid = themeDims(t) === "3D";
+  const tmp = mkdtempSync(join(tmpdir(), `kf-vary-${world}-`));
+  try {
+    // 세계 기본 판 — 표준 장면을 감독이 짓고 검사까지. 변주는 이 장면 파일 그대로 style 만 갈아 입는다
+    o.log(`${world}: 기본 판 표준 장면 짓는 중${solid ? "(입체 — 변주는 끝 구간만 검사)" : ""}`);
+    const base = join(tmp, "base");
+    let release = await acquireRenderLock(base, 900);
+    let b;
+    try {
+      b = standardProject(world, base, { check: true });
+      if (b.frame) still(base, b.frame.at, cellPath(world));
+    } finally {
+      release();
+    }
+    if (b.status !== 0 || !b.frame) throw new Error(`${world} 기본 판이 표준 장면 검사를 못 넘는다 — ${b.why}`);
+    markCell(t, b.frame);
+    const frame = b.frame;
+    const win = solid ? { from: +Math.max(0, frame.at - 0.8).toFixed(3), to: frame.dur } : undefined;
+
+    const shots = [thumb(cellPath(world)), ...existing.map((v) => cellPath(`${world}/${v.id}`)).filter(existsSync).map(thumb)];
+    const taken = new Set([...existing.map((v) => v.id), "base"]);
+    const ranked = rankCandidates(t.style, { vary: spec }, { seed: o.seed ?? world, taken: existing.map((v) => candidateOf(v.params, v.style, {})) });
+    o.log(`${world}: 색 검사를 넘은 후보 ${ranked.length}개 — 서로 먼 차례로 ${need}개를 굽는다`);
+    const today = new Date().toLocaleDateString("sv-SE");
+    mkdirSync(variantsDir(world), { recursive: true });
+    for (const c of ranked) {
+      if (result.made.length >= need || result.rejected.length >= need * 2) break;
+      const nm = nameVariant(c.params, taken, c.overlay.colors);
+      const id = `${world}/${nm.id}`;
+      const v: VariantManifest = {
+        id: nm.id,
+        world,
+        name: nm.name,
+        desc: nm.desc,
+        params: c.params,
+        style: c.overlay,
+        tags: variantTags(t.tags ?? defaultTags(t), c.params, c.overlay.colors),
+        check: { ok: false, at: today, colors: c.measured, frame: "", ...(frame.pattern ? { pattern: frame.pattern } : {}) },
+      };
+      const dir = join(tmp, nm.id);
+      restyle(base, dir, id, mergeVariant(t.style, v));
+      const png = join(dir, "cell.png");
+      release = await acquireRenderLock(dir, 900);
+      let verdict;
+      let shotBad: string | null;
+      try {
+        verdict = checkProject(dir, win);
+        shotBad = verdict.ok ? still(dir, frame.at, png) : null;
+      } finally {
+        release();
+      }
+      const reject = (why: string) => {
+        result.rejected.push({ id, why });
+        o.log(`  탈락 ${id} — ${why}`);
+      };
+      if (!verdict.ok) {
+        reject(verdict.errors.slice(0, 2).join(" · "));
+        continue;
+      }
+      if (shotBad) {
+        reject(`칸을 못 찍었다 — ${shotBad}`);
+        continue;
+      }
+      const th = thumb(png);
+      const near = Math.min(...shots.map((s) => imageDiff(s, th)));
+      if (near < SAME_LOOK) {
+        reject(`이미 뽑은 판과 거의 같다(화소 차 ${near.toFixed(3)})`);
+        continue;
+      }
+      v.check = { ...v.check, ok: true, frame: win ? `kf check 통과 — 끝 구간 ${win.from}–${win.to}초(입체라 가볍게)·끝 프레임 한 장` : `kf check 통과 — 표준 장면 0–${frame.dur}초` };
+      writeFileSync(join(variantsDir(world), `${nm.id}.json`), `${JSON.stringify(v, null, 2)}\n`);
+      mkdirSync(join(cellPath(id), ".."), { recursive: true });
+      copyFileSync(png, cellPath(id));
+      markCell(loadTheme(id), frame);
+      shots.push(th);
+      taken.add(nm.id);
+      result.made.push(v);
+      o.log(`  통과 ${id} — ${v.desc}`);
+      rmSync(dir, { recursive: true, force: true });
+    }
+    if (result.made.length < need) o.log(`${world}: ${need}개 중 ${result.made.length}개만 남았다 — 후보가 모자라면 vary 범위를 넓히거나 --seed 를 바꿔 다시`);
+    return result;
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}

package/packages/core/src/index.ts

@@ -24,4 +24,4 @@ export type { Style, CssStyle } from "./style.ts";
 export { setFrameTime, frameTime, onFrame, emit, motionEvents, resetMotionEvents, setFrameSample, frameSample } from "./frame.ts";
 export type { KfMotionEvent, MotionEventKind, FrameSample } from "./frame.ts";
 export { silentBeats, scaleOf, cssVars, fontCss } from "./project.ts";
-export type { CaptionLook, KfMeta, KfStyle, MotionRules, SafeArea, SceneCtx, FontFace } from "./project.ts";
+export type { CaptionLook, KfMeta, KfStyle, MotionRules, SafeArea, SceneCtx, FontFace, StyleLook } from "./project.ts";

package/packages/core/src/project.ts

@@ -94,6 +94,20 @@ export interface KfStyle {
   captions?: CaptionLook;
   /** 디자인 출처·지킬 점 — 사람과 모델이 읽는다 */
   notes?: string[];
+  /** 테마 변주가 고른 겉모습 손잡이(SPEC 9 변주). 없으면 모두 기본(질감 없음·배수 1) */
+  look?: StyleLook;
+}
+
+/** 엔진·테마 코드가 읽는 겉모습 손잡이 — CSS 변수 --kf-stroke·--kf-tempo·--kf-density 로도 나간다 */
+export interface StyleLook {
+  /** 화면 전체에 얹는 정지 질감 — 엔진이 장면 위·자막 아래 한 겹으로 깐다 */
+  texture?: { kind: "none" | "grain" | "paper" | "noise" | "scan" | "halftone"; amount: number };
+  /** 선 굵기 배수 */
+  stroke?: number;
+  /** 움직임 빠르기 배수 — 1 보다 크면 빠르다 */
+  tempo?: number;
+  /** 장식·입자 밀도 배수 — 읽는 세계만 쓴다 */
+  density?: number;
 }
 
 export interface CaptionLook {
@@ -140,6 +154,7 @@ export function cssVars(style: KfStyle, meta?: Pick<KfMeta, "width" | "height">)
   lines.push(`--kf-tracking: ${style.type.tracking};`);
   for (const [n, v] of Object.entries(style.radius)) lines.push(`--kf-radius-${n}: ${v}px;`);
   lines.push(`--kf-shadow-soft: ${style.shadow.soft};`, `--kf-shadow-lift: ${style.shadow.lift};`);
+  for (const k of ["stroke", "tempo", "density"] as const) lines.push(`--kf-${k}: ${style.look?.[k] ?? 1};`);
   return `:root {\n  ${lines.join("\n  ")}\n}`;
 }
 

package/packages/director/src/assemble.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { worldOf } from "@kasaframe/themes/name";
 import { dressSeed, type Dress } from "@kasaframe/motion/menu";
 import { loadTemplate, sceneSkeleton, type Template } from "@kasaframe/plan";
 import { catalog } from "./catalog.ts";
@@ -205,11 +206,13 @@ export async function build(dir: string, content: Content, o: BuildOpts = {}): P
   const entries = o.entries ?? (await catalog());
   const beats: BeatsLite | null = kf.beats && existsSync(join(dir, kf.beats)) ? readJson(join(dir, kf.beats)) : null;
   const theme: string | null = kf.theme ?? null;
+  // 변주(<세계>/<변주>)는 겉모습만 다르다 — 장면 문법·연출 수는 세계로 골라 같은 세계면 같은 장면이 선다
+  const world = worldOf(theme);
   const purpose: string = kf.template;
   const aspect = aspectOf(kf.width, kf.height);
   const policy: TextPolicy = kf.text?.policy ?? tpl.text.policy;
   const seed = o.seed ?? content.seed ?? "0";
-  const key = dressSeed(content.title, purpose, theme ?? plan.style, seed);
+  const key = dressSeed(content.title, purpose, world ?? plan.style, seed);
   const hash = contentHash(content);
   const scenes: KfScene[] = kf.scenes;
   const byId = new Map(content.scenes.map((s) => [s.id, s]));
@@ -236,7 +239,7 @@ export async function build(dir: string, content: Content, o: BuildOpts = {}): P
   // 패턴 자리
   const slotScenes = scenes.filter((s) => s.role !== "seam" && s.type && s.type !== "custom");
   const slots: Slot[] = slotScenes.map((s) => ({ id: s.id, type: s.type!, content: payload(byId.get(s.id)!), dur: s.dur, energy: energyOf(beats, s.from, s.dur, s === scenes[0]) }));
-  const ctx = { aspect, purpose, theme, policy, seed: key };
+  const ctx = { aspect, purpose, theme: world, policy, seed: key };
   const entryOf = new Map(entries.map((e) => [e.meta.id, e]));
   const prevOf = new Map((same ? prev.scenes : []).filter((s) => s.pattern).map((s) => [s.id, s]));
   // 전체 짓기는 늘 처음부터 같은 길(selectAll) — 고름이 (내용·씨앗·떨어진 기록)에만 달려 앞 실행의 이력이 안 남는다.
@@ -273,7 +276,7 @@ export async function build(dir: string, content: Content, o: BuildOpts = {}): P
   });
   const kinds = seamKinds(spots, key, tpl.scenes.find((s) => s.role === "seam")?.transition ?? "dive", Object.fromEntries(seamIdx.map((i, k) => [k, seamFailed[scenes[i].id] ?? []])));
 
-  const dress = dressAll(key, scenes, tpl.moves, theme);
+  const dress = dressAll(key, scenes, tpl.moves, world);
   const scenesDir = join(dir, "scenes");
   mkdirSync(scenesDir, { recursive: true });
   const report: SceneReport[] = [];

package/packages/motion/src/moves/menu.ts

@@ -64,7 +64,8 @@ const known = (kind: DressKind) => (n: string) => menuItem(n)?.kind === kind;
 
 /** 틀 묶음 + 테마 묶음 → 한 벌. 테마 수를 앞에, 메뉴에 없는 이름은 버린다 */
 export function bundleFor(tpl?: Bundle, theme?: string): Required<Bundle> {
-  const th = theme ? THEME_POOLS[theme] : undefined;
+  // 변주 이름(<세계>/<변주>)이면 그 세계 묶음
+  const th = theme ? THEME_POOLS[theme.split("/")[0]] : undefined;
   const merge = (kind: DressKind, ...lists: (string[] | undefined)[]) => [...new Set(lists.flatMap((l) => l ?? []))].filter(known(kind));
   const roles: Record<string, Pool> = {};
   for (const [role, p] of Object.entries(tpl?.roles ?? {})) {

package/packages/patterns/src/kit.ts

@@ -142,8 +142,9 @@ export function odometer(el: HTMLElement, o: { template: string; decimals: numbe
       const roll = c.j === 0 || lower === 10 ** c.j - 1 ? frac : 0;
       // 맨 앞 0 은 비운다 — 다음 자리로 올라가는 동안은 빈칸에서 1 로 구른다
       const pos = (base % 10) + roll;
-      // 창에 걸친 두 숫자만 보인다 — 띠 밖 숫자는 검사가 읽지 않게 숨긴다
-      c.glyphs.forEach((g, i) => (g.style.visibility = i === Math.floor(pos) || i === Math.floor(pos) + 1 ? "visible" : "hidden"));
+      // 창에 걸친 두 숫자만 보인다 — 띠 밖 숫자는 검사가 읽지 않게 숨긴다. 보일 숫자는 부모를 따른다("visible" 로 박으면 패턴이 띠를 통째로 숨겨도 남아,
+      // 칸 폭 0.62em 과 글자 폭이 다른 고정폭 글꼴에서 앉은 숫자와 두 겹으로 찍힌다)
+      c.glyphs.forEach((g, i) => (g.style.visibility = i === Math.floor(pos) || i === Math.floor(pos) + 1 ? "" : "hidden"));
       if (base === 0 && c.j > -lowest) c.glyphs[0].style.visibility = "hidden";
       c.strip.style.transform = `translateY(${(-pos * o.linePx).toFixed(2)}px)`;
     }

package/packages/plan/src/asks.ts

@@ -1,8 +1,6 @@
-import { existsSync } from "node:fs";
-import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { byMood, estimateImageUsd, howToGet, listLibrary, musicQuestion, ttsProviders, videoProviders, voiceQuestion, WAIT, type CapabilityReport, type Choice, type Question, type VideoRequest } from "@kasaframe/gen";
-import { listThemes, sheetDir, themeDims, themeSample } from "@kasaframe/themes";
+import { loadTheme, themeDims, themeSample } from "@kasaframe/themes";
 import { loadSeries } from "./series.ts";
 import { loadTemplate } from "./templates.ts";
 import { suggestThemes, themeFromRequest } from "./themes.ts";
@@ -155,38 +153,49 @@ function voicePart(plan: Plan, caps: CapabilityReport): { q?: Question; auto?: s
   };
 }
 
-// 테마 — 시리즈가 정했거나 요청이 「리소 느낌」처럼 짚었으면 묻지 않는다(kf new 의 auto 가 그대로 짚은 테마를 쓴다).
-// 보기는 「알아서」(= auto, 권장)와 이 용도·화면비의 approved 테마 전부(요청에 맞는 차례) — theme.json status 만 approved 로 바꾸면 들어온다
+// 테마 — 시리즈가 정했거나 요청이 「리소 느낌」·「og-measure/night-amber」처럼 짚었으면 묻지 않는다(kf new 의 auto 가 그대로 짚은 판을 쓴다).
+// 보기는 「알아서」(= auto, 권장)와 요청·용도·분위기 낱말(사람이 준 한 마디·레퍼런스까지)에 맞는 approved 세계·변주 넷 — 수백 판을 다 늘어놓지 않는다.
+// 사람이 보기 밖으로 분위기 한 마디나 그림·주소를 주면 그걸로 넷을 다시 고른다(kf make --theme-mood·--theme-ref)
+export const THEME_PICKS = 4;
+
 function themePart(plan: Plan): { q?: Question; auto?: string } {
   if ((plan.series && loadSeries(plan.series).theme) || themeFromRequest(plan.request, plan.purpose)) return {};
-  const ranked = suggestThemes(plan.request, plan.purpose, plan.aspect, Infinity);
+  const ranked = suggestThemes(plan.request, plan.purpose, plan.aspect, THEME_PICKS, plan.themeLook ?? {});
   if (!ranked.length) return {};
-  const byId = new Map(listThemes({ status: "approved" }).map((t) => [t.id, t]));
-  const grid = join(sheetDir, "sheet.png");
-  const first = byId.get(ranked[0].id)!;
+  const first = loadTheme(ranked[0].id);
+  const look = plan.themeLook;
   return {
     q: {
       id: "theme",
       cap: "theme",
       header: "테마",
-      ask: `테마는? ${existsSync(grid) ? `같은 문장 한 장면을 테마마다 찍은 견본 시트 ${grid}` : "보기마다 견본 그림 경로"}`,
+      ask: `테마는? ${look?.mood || look?.ref ? `${[look.mood && `분위기 「${look.mood}」`, look.ref && `레퍼런스 ${look.ref.source}`].filter(Boolean).join("·")}로 다시 고른 ` : "요청에 맞는 "}후보 ${ranked.length}개. 마음에 드는 게 없으면 분위기 한 마디(--theme-mood "<말>")나 레퍼런스 그림·주소(--theme-ref <경로|URL>)를 주면 그걸로 다시 고른다`,
       choices: [
-        { value: "auto", label: "알아서", note: `요청 낱말에 맞는 approved 테마를 고른다 — 지금이면 ${first.name}` },
-        ...ranked.map(({ id }) => {
-          const t = byId.get(id)!;
+        { value: "auto", label: "알아서", note: `요청·분위기에 맞는 첫 후보 — 지금이면 ${first.name}` },
+        ...ranked.map(({ id, why }) => {
+          const t = loadTheme(id);
           const sample = themeSample(t);
-          return { value: t.id, label: `${t.name} · ${themeDims(t)}`, note: `${t.metaphor}${sample ? ` — 견본 ${sample}` : ""}` };
+          return { value: t.id, label: `${t.name} · ${themeDims(t)}`, note: `${why}${sample ? ` — 견본 ${sample}` : ""}` };
         }),
       ],
       default: "auto",
       skip: "auto",
       flag: "--theme",
-      // 보기 밖이라도 사람이 짚은 review 테마·none(프리셋만)은 받는다 — kf new --theme 과 같은 범위
-      accepts: (v: string) => v === "none" || listThemes({ status: ["approved", "review"] }).some((t) => t.id === v),
+      // 보기 밖이라도 사람이 짚은 테마(review 까지·변주 포함)·none(프리셋만)은 받는다 — kf new --theme 과 같은 범위
+      accepts: (v: string) => v === "none" || usableTheme(v),
     },
   };
 }
 
+/** kf new --theme 이 받는 이름인가 — approved·review 세계와 그 변주 */
+export function usableTheme(id: string): boolean {
+  try {
+    return loadTheme(id).status !== "draft";
+  } catch {
+    return false;
+  }
+}
+
 // 곡 — 틀이 분위기를 정한 용도만. 시리즈 곡·분위기 맞는 곡 모음 곡(0원·늘 같은 곡)은 묻지 않는다.
 // 없으면 생성(돈)·곡 넣기·없음을 묻고, 생성 키도 없으면 다른 분위기 곡·「곡 없이」로 조용히 넘어가지 않고 missing 으로 묻는다
 function musicPart(plan: Plan, caps: CapabilityReport): { q?: Question; auto?: string } {