kasaframe 0.1.3 → 0.1.5

package/packages/cli/src/kf.ts

@@ -3,6 +3,7 @@ import { readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { fontsMissing } from "@kasaframe/jizura/install";
 import type { Command } from "./command.ts";
+import { updateGate } from "./update.ts";
 
 const commandsDir = fileURLToPath(new URL("./commands/", import.meta.url));
 
@@ -42,6 +43,10 @@ async function main(argv: string[]): Promise<number> {
     console.log(`kf ${name} — ${cmd.summary}\n\n${cmd.usage ?? ""}`.trimEnd());
     return 0;
   }
+  if (name !== "update") {
+    const relaunched = await updateGate(argv).catch(() => null);
+    if (relaunched !== null) return relaunched;
+  }
   return (await cmd.run(rest)) ?? 0;
 }
 

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

@@ -0,0 +1,250 @@
+// 새 판 알림 — Codex CLI 처럼 확인은 떨어진 자식이 뒤에서 하고 결과를 캐시에 둔다. kf 는 네트워크를 기다리지 않고 지난 확인 결과로 묻거나 알린다.
+// 여기는 모든 kf 명령 앞에서 불리니 무거운 것을 import 하지 않는다.
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+
+export const PACKAGE = "kasaframe";
+const root = fileURLToPath(new URL("../../../", import.meta.url));
+const versionAt = (dir: string): string => JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).version;
+export const current = versionAt(root);
+// 몇 시간에 한 번 — 하루에 몇 번 켜도 레지스트리는 한두 번만 본다
+export const CHECK_EVERY_MS = 6 * 3600_000;
+
+export interface UpdateCache {
+  latest?: string;
+  checkedAt?: string;
+  /** 「이 판은 다시 묻지 않기」로 넘긴 판 — 더 새 판이 나오면 다시 묻는다 */
+  dismissed?: string;
+}
+
+export const cacheFile = (): string => join(process.env.KF_CACHE_DIR ?? join(homedir(), ".cache", "kasaframe"), "update.json");
+
+export function readCache(): UpdateCache {
+  try {
+    return JSON.parse(readFileSync(cacheFile(), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+// kf 여럿이 한꺼번에 써도 반쯤 쓴 파일을 읽지 않게 다른 이름에 쓰고 옮긴다
+export function writeCache(c: UpdateCache): void {
+  const file = cacheFile();
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify(c)}\n`);
+  renameSync(tmp, file);
+}
+
+const SEMVER = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+
+/** latest 가 now 보다 새 정식 판인가 — 미리보기 판(prerelease)은 권하지 않는다 */
+export function isNewer(latest: string, now: string): boolean {
+  const l = SEMVER.exec(latest.trim());
+  const c = SEMVER.exec(now.trim());
+  if (!l || !c || l[4]) return false;
+  for (let i = 1; i <= 3; i++) {
+    const d = Number(l[i]) - Number(c[i]);
+    if (d) return d > 0;
+  }
+  return !!c[4];
+}
+
+export type Manager = "npm" | "pnpm" | "bun" | "yarn";
+export interface Install {
+  manager: Manager;
+  /** npm 전역 자리 — 기본 자리가 아니면 올릴 때도 거기에 깔아야 이 kf 가 바뀐다 */
+  prefix?: string;
+}
+
+/** 패키지가 놓인 자리로 어느 관리자의 전역 설치인가. 레포 체크아웃·npx 가 잠깐 받은 것·프로젝트 의존성은 null — 판은 그쪽이 정한다 */
+export function installOf(dir: string, win = process.platform === "win32"): Install | null {
+  const p = dir.replace(/\\/g, "/").replace(/\/+$/, "");
+  if (!p.includes("/node_modules/")) return null;
+  if (p.includes("/_npx/")) return null;
+  if (p.includes("/.bun/install/global/")) return { manager: "bun" };
+  if (/\/pnpm\/global\//i.test(p)) return { manager: "pnpm" };
+  if (/\/yarn\/(data\/)?global\/node_modules\//i.test(p)) return { manager: "yarn" };
+  const npm = (win ? /^(.+)\/node_modules\/kasaframe$/ : /^(.+)\/lib\/node_modules\/kasaframe$/).exec(p);
+  return npm ? { manager: "npm", prefix: win ? npm[1].replace(/\//g, "\\") : npm[1] } : null;
+}
+
+export function updateCommand(inst: Install, version: string, npmDefaultPrefix?: string): string[] {
+  const spec = `${PACKAGE}@${version}`;
+  if (inst.manager === "pnpm") return ["pnpm", "add", "-g", spec];
+  if (inst.manager === "bun") return ["bun", "add", "-g", spec];
+  if (inst.manager === "yarn") return ["yarn", "global", "add", spec];
+  const custom = inst.prefix && npmDefaultPrefix !== undefined && !samePath(inst.prefix, npmDefaultPrefix);
+  return ["npm", "i", "-g", spec, ...(custom ? ["--prefix", inst.prefix!] : [])];
+}
+
+function samePath(a: string, b: string): boolean {
+  const real = (p: string) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return p;
+    }
+  };
+  return real(a) === real(b);
+}
+
+const shell = process.platform === "win32";
+
+function npmPrefix(): string | undefined {
+  const r = spawnSync("npm", ["prefix", "-g"], { encoding: "utf8", shell, timeout: 10_000 });
+  return r.status === 0 ? r.stdout.trim() : undefined;
+}
+
+/** 이 kf 를 올리는 명령 — npm 이면 기본 전역 자리와 비교해야 해서 npm 을 한 번 부른다(묻거나 올릴 때만) */
+export function commandFor(version: string): string[] | null {
+  const inst = installOf(root);
+  return inst && updateCommand(inst, version, inst.manager === "npm" && inst.prefix ? npmPrefix() : undefined);
+}
+
+// 환경 변수 → npm 설정(사용자·전역·프로젝트 .npmrc) — 올리는 명령도 같은 npm 설정을 따른다
+export function registry(env: NodeJS.ProcessEnv = process.env): string {
+  const set = env.npm_config_registry ?? env.NPM_CONFIG_REGISTRY;
+  if (set) return set;
+  const r = spawnSync("npm", ["config", "get", "registry"], { encoding: "utf8", shell, timeout: 10_000 });
+  const got = r.status === 0 ? r.stdout.trim() : "";
+  return /^https?:\/\//.test(got) ? got : "https://registry.npmjs.org/";
+}
+
+export async function fetchLatest(timeoutMs: number): Promise<string> {
+  const url = `${registry().replace(/\/+$/, "")}/${PACKAGE}`;
+  const r = await fetch(url, {
+    headers: { accept: "application/vnd.npm.install-v1+json; q=1.0, application/json; q=0.8" },
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!r.ok) throw new Error(`${url} → HTTP ${r.status}`);
+  const latest = ((await r.json()) as { "dist-tags"?: { latest?: unknown } })["dist-tags"]?.latest;
+  if (typeof latest !== "string") throw new Error(`${url} 에 dist-tags.latest 가 없다`);
+  return latest;
+}
+
+/** 레지스트리를 지금 보고 캐시에 적는다 — kf update·kf doctor 와 뒤에서 도는 자식이 쓴다 */
+export async function refresh(timeoutMs = 8000): Promise<string> {
+  const latest = await fetchLatest(timeoutMs);
+  writeCache({ ...readCache(), latest, checkedAt: new Date().toISOString() });
+  return latest;
+}
+
+const on = (v: string | undefined) => !!v && v !== "0" && v.toLowerCase() !== "false";
+
+export interface Decision {
+  show: "prompt" | "notice" | "none";
+  refresh: boolean;
+  latest?: string;
+}
+
+export function decide(i: { current: string; cache: UpdateCache; install: Install | null; tty: boolean; env: NodeJS.ProcessEnv; now: number }): Decision {
+  if (!i.install || on(i.env.KF_NO_UPDATE_CHECK) || on(i.env.CI)) return { show: "none", refresh: false };
+  // 시각이 없거나 미래(시계가 돌아갔다)면 지금 본다
+  const age = i.now - Date.parse(i.cache.checkedAt ?? "");
+  const refresh = !(age >= 0 && age < CHECK_EVERY_MS);
+  const latest = i.cache.latest;
+  if (!latest || !isNewer(latest, i.current) || i.cache.dismissed === latest) return { show: "none", refresh };
+  return { show: i.tty ? "prompt" : "notice", refresh, latest };
+}
+
+// 뜻이 고정된 한 줄 — 에이전트가 이 꼴을 보고 kf update --yes 를 돌린다(skills/kasaframe/SKILL.md)
+export const noticeLine = (latest: string, now = current): string => `[kasaframe] 새 판 ${latest} (지금 ${now}) — kf update`;
+
+// 확인이 안 돼도(캐시 자리를 못 쓰거나 오프라인) kf 명령은 그대로 돈다
+function refreshInBackground(): void {
+  try {
+    // 같이 뜬 kf 들이 저마다 확인을 띄우지 않게 시각부터 적는다 — 실패하면 다음 주기에 다시 본다
+    writeCache({ ...readCache(), checkedAt: new Date().toISOString() });
+    const code = `const m = await import(${JSON.stringify(import.meta.url)}); await m.refresh(15000).catch(() => {});`;
+    spawn(process.execPath, ["--input-type=module", "-e", code], { detached: true, stdio: "ignore", windowsHide: true })
+      .on("error", () => {})
+      .unref();
+  } catch {}
+}
+
+// 설치본 입구가 NODE_OPTIONS 에 넣은 형 지우기 훅 — 새 판으로 다시 띄울 땐 빼야 새 입구가 제 훅을 넣는다(pnpm 은 옛 판 자리를 지운다)
+const hooksArg = `--import=${new URL("../../../bin/hooks.mjs", import.meta.url).href}`;
+
+function install(cmd: string[]): { ok: boolean; why: string } {
+  const r = spawnSync(cmd[0], cmd.slice(1), { stdio: "inherit", shell });
+  if (r.error) return { ok: false, why: r.error.message };
+  return { ok: r.status === 0, why: r.signal ? `신호 ${r.signal}` : `종료 ${r.status}` };
+}
+
+/** 사람이 친 kf 입구(심볼릭 링크 그대로)가 이제 가리키는 판 */
+function versionBehind(entry: string): string | null {
+  try {
+    return versionAt(join(dirname(realpathSync(entry)), ".."));
+  } catch {
+    return null;
+  }
+}
+
+/** 올리고, 이 kf 입구가 실제로 새 판을 가리키는지까지 본다 */
+export function upgrade(cmd: string[], latest: string, entry = process.argv[1]): boolean {
+  process.stderr.write(`\n${cmd.join(" ")}\n`);
+  const r = install(cmd);
+  if (!r.ok) {
+    process.stderr.write(`\n올리지 못했다(${r.why}). 직접 올리려면: ${cmd.join(" ")}\n`);
+    return false;
+  }
+  const now = versionBehind(entry);
+  if (now !== latest) {
+    process.stderr.write(`\n설치는 끝났는데 이 kf(${entry})는 ${now ?? "?"} 그대로다 — 다른 자리에 깔렸다. 직접: ${cmd.join(" ")}\n`);
+    return false;
+  }
+  return true;
+}
+
+async function ask(latest: string, cmd: string[]): Promise<"update" | "skip" | "dismiss"> {
+  // 묻는 동안 표준 출력이 터미널임은 확인했다 — 표준 오류가 파일로 가 있어도 보이게 표준 출력에 묻는다
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  rl.on("SIGINT", () => {
+    rl.close();
+    process.exit(130);
+  });
+  try {
+    const a = (
+      await rl.question(
+        `\n새 판이 있다 · kasaframe ${current} → ${latest}\n  1) 지금 업데이트 (${cmd.join(" ")})\n  2) 건너뛰기\n  3) 이 판은 다시 묻지 않기\n번호(엔터 = 1): `,
+      )
+    ).trim();
+    return a === "" || a === "1" ? "update" : a === "3" ? "dismiss" : "skip";
+  } catch {
+    return "skip";
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * 명령 앞 관문. 터미널이면 보기 셋을 묻고, 아니면 표준 오류에 한 줄(표준 출력은 --json 을 읽는 도구가 있어 건드리지 않는다).
+ * 「지금 업데이트」가 되면 원래 명령을 새 판으로 다시 띄우고 그 종료 코드를, 아니면 null(지금 판으로 이어 간다)
+ */
+export async function updateGate(argv: string[]): Promise<number | null> {
+  const env = process.env;
+  const d = decide({ current, cache: readCache(), install: installOf(root), tty: !!(process.stdin.isTTY && process.stdout.isTTY), env, now: Date.now() });
+  // kf 가 띄우는 kf(make → render 따위)는 다시 묻거나 찍지 않는다
+  env.KF_NO_UPDATE_CHECK = "1";
+  if (d.refresh) refreshInBackground();
+  if (d.show === "notice") process.stderr.write(`${noticeLine(d.latest!)}\n`);
+  if (d.show !== "prompt") return null;
+
+  const cmd = commandFor(d.latest!)!;
+  const pick = await ask(d.latest!, cmd);
+  if (pick === "dismiss") writeCache({ ...readCache(), dismissed: d.latest });
+  if (pick !== "update") return null;
+  if (!upgrade(cmd, d.latest!)) {
+    process.stderr.write(`${current} 로 이어 간다\n\n`);
+    return null;
+  }
+  process.stderr.write(`\nkasaframe ${d.latest} 로 올렸다 — 이어서 kf ${argv.join(" ")}\n\n`);
+  const nodeOptions = (env.NODE_OPTIONS ?? "").split(" ").filter((t) => t && t !== hooksArg).join(" ");
+  const r = spawnSync(process.execPath, [process.argv[1], ...argv], { stdio: "inherit", env: { ...env, NODE_OPTIONS: nodeOptions } });
+  return r.status ?? (r.signal === "SIGINT" ? 130 : 1);
+}

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)`;
     }