kasaframe 0.1.3 → 0.1.5

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

@@ -0,0 +1,66 @@
+import { createInterface } from "node:readline/promises";
+import { type Command, parseFlags } from "../command.ts";
+import { commandFor, current, isNewer, noticeLine, refresh, upgrade } from "../update.ts";
+
+async function confirm(q: string): Promise<boolean> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return /^(|y|yes|ㅇ|응|네)$/i.test((await rl.question(q)).trim());
+  } catch {
+    return false;
+  } finally {
+    rl.close();
+  }
+}
+
+const cmd: Command = {
+  summary: "새 판 확인·올리기 — 지금 레지스트리를 보고 새 판이면 깐 방식(npm·pnpm·bun·yarn)대로 올린다",
+  usage: `kf update            지금 확인하고 새 판이면 올린다(터미널이면 한 번 묻는다)
+kf update --check    올리지 않고 보기만
+kf update --json     {current, latest, update, command} 를 표준 출력에 — 올리지 않는다
+kf update --yes      묻지 않고 올린다(에이전트용 — 표준 오류에 「[kasaframe] 새 판 …」 줄이 보이면)
+  레지스트리는 npm 설정(npm_config_registry·~/.npmrc)을 따른다. kf 는 몇 시간에 한 번 뒤에서 확인해 두고,
+  새 판을 알면 터미널에선 명령 전에 묻고 아니면 표준 오류에 한 줄 찍는다. 끄기: KF_NO_UPDATE_CHECK=1 · CI
+  종료 코드: 0 최신이거나 올림 · 1 확인·설치 실패 · 2 올리지 않음(묻기 거절·--yes 없이 터미널 밖·레포 체크아웃)`,
+  async run(argv) {
+    const { opts } = parseFlags(argv);
+    let latest: string;
+    try {
+      latest = await refresh();
+    } catch (e) {
+      const error = (e as Error).message;
+      if (opts.json) console.log(JSON.stringify({ current, latest: null, update: false, command: null, error }));
+      else console.error(`kf update: 새 판을 확인하지 못했다 — ${error}`);
+      return 1;
+    }
+    const update = isNewer(latest, current);
+    const command = update ? commandFor(latest) : null;
+    if (opts.json) {
+      console.log(JSON.stringify({ current, latest, update, command: command?.join(" ") ?? null }));
+      return 0;
+    }
+    if (!update) {
+      console.log(`kasaframe ${current} — 최신이다${latest === current ? "" : `(레지스트리 최신 ${latest})`}`);
+      return 0;
+    }
+    if (!command) {
+      console.log(`${noticeLine(latest)}\n레포 체크아웃에서 돌고 있다 — 설치본이 아니라 올리지 않는다(git pull)`);
+      return opts.check ? 0 : 2;
+    }
+    if (opts.check) {
+      console.log(`${noticeLine(latest)}\n올리는 명령: ${command.join(" ")}`);
+      return 0;
+    }
+    if (!opts.yes) {
+      if (!(process.stdin.isTTY && process.stdout.isTTY)) {
+        console.error(`${noticeLine(latest)}\n터미널이 아니라 묻지 못한다 — 묻지 않고 올리려면 kf update --yes`);
+        return 2;
+      }
+      if (!(await confirm(`kasaframe ${current} → ${latest} 로 올릴까(${command.join(" ")})? [Y/n] `))) return 2;
+    }
+    if (!upgrade(command, latest)) return 1;
+    console.log(`kasaframe ${latest} 로 올렸다`);
+    return 0;
+  },
+};
+export default cmd;

package/packages/cli/src/fonts.ts

@@ -0,0 +1,405 @@
+// kf fonts — 글꼴 짝을 받아 재고(주소·판·라이선스 글·한글 덮음·굵기) 크롬으로 견본을 찍어 글이 실제로 서는지 본다.
+// 받은 파일은 <캐시>/fonts/files 에 두고, 크롬에는 그 파일을 같은 주소로 내준다 — 두 번째부터는 주소가 살았는지만 묻는다.
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { BrowserContext, Page } from "playwright";
+import { readFontFile } from "@kasaframe/themes/fontfile";
+import {
+  type FaceFile,
+  faceForChar,
+  FONT_SAMPLE,
+  type FontPair,
+  licenseVerdict,
+  measurePair,
+  type PairMeasure,
+  pairProblems,
+  type SampleLine,
+  stackFamilies,
+  stackUses,
+} from "@kasaframe/themes/fonts";
+import { launch } from "./browser.ts";
+import { pool } from "./pool.ts";
+
+export const fontCacheDir = (): string => join(process.env.KF_CACHE_DIR ?? join(homedir(), ".cache", "kasaframe"), "fonts");
+export const cachedFontFile = (url: string) => join(fontCacheDir(), "files", `${createHash("sha1").update(url).digest("hex").slice(0, 20)}${/\.\w+$/.exec(new URL(url).pathname)?.[0] ?? ""}`);
+
+interface Fetched {
+  /** HTTP 상태, 못 닿으면 까닭 */
+  status: number | string;
+  text?: string;
+}
+
+async function get(url: string, how: "head" | "file" | "text"): Promise<Fetched> {
+  for (let tries = 0; ; tries++) {
+    try {
+      const r = await fetch(url, { method: how === "head" ? "HEAD" : "GET", redirect: "follow", signal: AbortSignal.timeout(60_000) });
+      if (r.status >= 500 && tries < 2) continue;
+      if (!r.ok || how === "head") return { status: r.status };
+      if (how === "text") return { status: r.status, text: await r.text() };
+      const path = cachedFontFile(url);
+      mkdirSync(join(fontCacheDir(), "files"), { recursive: true });
+      writeFileSync(`${path}.tmp`, Buffer.from(await r.arrayBuffer()));
+      renameSync(`${path}.tmp`, path);
+      return { status: r.status };
+    } catch (err) {
+      if (tries < 2) continue;
+      return { status: (err as Error).message };
+    }
+  }
+}
+
+export interface RenderLine {
+  stack: string;
+  weight: number;
+  line: SampleLine;
+  fonts: { family: string; custom: boolean; glyphs: number }[];
+  ink: number;
+  tofu: string[];
+}
+
+export interface PairReport {
+  id: string;
+  group: string;
+  name: string;
+  ok: boolean;
+  hangul?: PairMeasure["hangul"];
+  syllables?: number;
+  boldest?: number;
+  licenses: string[];
+  problems: string[];
+  notes: string[];
+}
+
+export interface CheckOptions {
+  /** 주소를 묻지 않고 캐시만 — 처음 보는 파일은 문제로 남는다 */
+  offline?: boolean;
+  render?: boolean;
+  log?: (s: string) => void;
+}
+
+/** 짝들을 재고 찍어 본다 — 받기는 주소마다 한 번 */
+export async function checkFonts(list: { group: string; pair: FontPair }[], o: CheckOptions = {}): Promise<PairReport[]> {
+  const log = o.log ?? (() => {});
+  const srcs = [...new Set(list.flatMap(({ pair }) => (pair.faces ?? []).map((f) => f.src)))];
+  const sources = o.offline ? [] : [...new Set(list.flatMap(({ pair }) => (pair.faces ?? []).map((f) => f.source).filter(Boolean)))];
+  // 같은 주소가 파일로도 라이선스 글로도 쓰일 수 있어 둘을 따로 둔다
+  const net = { file: new Map<string, Fetched>(), text: new Map<string, Fetched>() };
+  let done = 0;
+  await pool([...srcs.map((u) => ({ u, kind: "file" as const })), ...sources.map((u) => ({ u, kind: "text" as const }))], 8, async ({ u, kind }) => {
+    let r: Fetched;
+    try {
+      new URL(u);
+    } catch {
+      net[kind].set(u, { status: "주소가 아니다" });
+      return;
+    }
+    const cached = kind === "file" && existsSync(cachedFontFile(u));
+    if (o.offline) r = { status: cached ? 200 : "캐시에 없다(--offline)" };
+    else r = await get(u, cached ? "head" : kind);
+    net[kind].set(u, r);
+    if (++done % 25 === 0) log(`  주소 ${done}/${srcs.length + sources.length}`);
+  });
+
+  const files = new Map<string, FaceFile>();
+  const broken = new Map<string, string>();
+  for (const u of srcs) {
+    if (!existsSync(cachedFontFile(u))) continue;
+    try {
+      const f = readFontFile(readFileSync(cachedFontFile(u)));
+      files.set(u, { cps: f.cps, weight: f.weight, wght: f.wght, names: f.families, licenseText: f.licenseText });
+    } catch (err) {
+      broken.set(u, (err as Error).message);
+    }
+  }
+
+  const reports = list.map(({ group, pair }): PairReport => {
+    const problems = pairProblems(pair);
+    const notes: string[] = [];
+    for (const f of pair.faces ?? []) {
+      const where = `${f.family}(${f.weight})`;
+      const s = net.file.get(f.src)?.status;
+      if (s !== 200) problems.push(`${where} 주소 ${s} — ${f.src}`);
+      if (broken.has(f.src)) problems.push(`${where} 파일을 못 읽는다 — ${broken.get(f.src)}`);
+      if (!f.source || o.offline) continue;
+      const lic = net.text.get(f.source);
+      if (lic?.status !== 200) {
+        problems.push(`${where} 라이선스 글 주소 ${lic?.status} — ${f.source}`);
+        continue;
+      }
+      const v = licenseVerdict(f, lic.text ?? "", files.get(f.src)?.licenseText ?? "");
+      if (v.problem) problems.push(v.problem);
+      if (v.note) notes.push(v.note);
+    }
+    const ready = (pair.faces ?? []).length > 0 && pair.faces.every((f) => files.has(f.src));
+    const m = ready ? measurePair(pair, files) : null;
+    return {
+      id: pair.id,
+      group,
+      name: pair.name,
+      ok: false,
+      ...(m ? { hangul: m.hangul, syllables: m.syllables, boldest: m.boldest } : {}),
+      licenses: [...new Set((pair.faces ?? []).map((f) => f.license))],
+      problems: [...problems, ...(m?.problems ?? [])],
+      notes: [...notes, ...(m?.notes ?? [])],
+    };
+  });
+
+  if (o.render !== false) {
+    const todo = list.filter(({ pair }) => pair.faces?.length && pair.faces.every((f) => files.has(f.src)));
+    log(`  크롬으로 견본 찍기 — 짝 ${todo.length}`);
+    const browser = await launch();
+    try {
+      const context = await browser.newContext({ deviceScaleFactor: 1 });
+      await serveCached(context);
+      const queue = [...todo];
+      let n = 0;
+      await Promise.all(
+        Array.from({ length: Math.min(4, todo.length) }, async () => {
+          const page = await context.newPage();
+          for (let x = queue.shift(); x; x = queue.shift()) {
+            const r = reports.find((y) => y.id === x.pair.id)!;
+            r.problems.push(...judgeRender(x.pair, files, await renderPair(page, x.pair)));
+            if (++n % 20 === 0) log(`  찍음 ${n}/${todo.length}`);
+          }
+        }),
+      );
+    } finally {
+      await browser.close();
+    }
+  }
+  for (const r of reports) r.ok = !r.problems.length;
+  return reports;
+}
+
+const ORIGIN = "https://kf-fonts.local/";
+const MIME: Record<string, string> = { woff2: "font/woff2", woff: "font/woff", ttf: "font/ttf", otf: "font/otf" };
+
+/** 글꼴 주소는 캐시 파일로, 견본 쪽은 빈 문서로 — 크롬이 따로 받지 않아 같은 파일을 본다 */
+async function serveCached(context: BrowserContext): Promise<void> {
+  await context.route("**/*", (route) => {
+    const url = route.request().url();
+    if (url.startsWith(ORIGIN)) return route.fulfill({ contentType: "text/html; charset=utf-8", body: "<!doctype html><meta charset=utf-8><body></body>" });
+    const path = cachedFontFile(url);
+    if (!existsSync(path)) return route.abort();
+    const ext = /\.(\w+)$/.exec(path)?.[1] ?? "woff2";
+    return route.fulfill({ body: readFileSync(path), headers: { "content-type": MIME[ext] ?? "application/octet-stream", "access-control-allow-origin": "*" } });
+  });
+}
+
+export interface Rendered {
+  loadErrors: { family: string; weight: string; error: string }[];
+  lines: RenderLine[];
+}
+
+/** 짝 하나를 빈 문서에 — face 를 하나씩 받아 실패를 그 face 에 붙이고, 줄마다 크롬이 고른 글꼴(CDP)·먹 양·두부 글자를 잰다 */
+async function renderPair(page: Page, p: FontPair): Promise<Rendered> {
+  await page.goto(ORIGIN);
+  const uses = stackUses(p);
+  const spans = uses.flatMap((u) => (Object.keys(FONT_SAMPLE) as SampleLine[]).map((line) => ({ stack: u.stack, css: u.css, weight: u.weight, line, text: FONT_SAMPLE[line] })));
+  const inPage = await page.evaluate(
+    async ({ faces, spans }) => {
+      const loadErrors: { family: string; weight: string; error: string }[] = [];
+      await Promise.all(
+        faces.map(async (f) => {
+          const ff = new FontFace(f.family, `url("${f.src}")`, { weight: f.weight ?? "100 900", display: "block" });
+          document.fonts.add(ff);
+          await ff.load().catch((e: Error) => loadErrors.push({ family: f.family, weight: f.weight ?? "", error: String(e?.message ?? e) }));
+        }),
+      );
+      const canvas = document.createElement("canvas");
+      const ctx = canvas.getContext("2d", { willReadFrequently: true })!;
+      const paint = (font: string, text: string, w: number, h: number): Uint8ClampedArray => {
+        canvas.width = w;
+        canvas.height = h;
+        ctx.font = font;
+        ctx.textBaseline = "middle";
+        ctx.fillText(text, 4, h / 2);
+        return ctx.getImageData(0, 0, w, h).data;
+      };
+      const inkOf = (d: Uint8ClampedArray) => {
+        let n = 0;
+        for (let i = 3; i < d.length; i += 4) if (d[i] > 40) n++;
+        return n;
+      };
+      const measured = spans.map((s, i) => {
+        const el = document.createElement("div");
+        el.dataset.k = String(i);
+        el.style.cssText = `font-family: ${s.css}; font-weight: ${s.weight}; font-size: 48px; white-space: pre; line-height: 1.4`;
+        el.textContent = s.text;
+        document.body.append(el);
+        const font = `${s.weight} 48px ${s.css}`;
+        const notdef = paint(font, "\u{10FFFD}", 80, 80).join(",");
+        const tofu = [...new Set([...s.text].filter((ch) => ch !== " "))].filter((ch) => {
+          const d = paint(font, ch, 80, 80);
+          return inkOf(d) > 0 && d.join(",") === notdef;
+        });
+        return { ink: inkOf(paint(font, s.text, 1600, 90)), tofu };
+      });
+      return { loadErrors, measured };
+    },
+    { faces: p.faces.map(({ family, src, weight }) => ({ family, src, weight })), spans: spans.map(({ css, weight, text }) => ({ css, weight, text })) },
+  );
+  const cdp = await page.context().newCDPSession(page);
+  try {
+    await cdp.send("DOM.enable");
+    await cdp.send("CSS.enable");
+    const { root } = await cdp.send("DOM.getDocument");
+    const lines: RenderLine[] = [];
+    for (const [i, s] of spans.entries()) {
+      const { nodeId } = await cdp.send("DOM.querySelector", { nodeId: root.nodeId, selector: `[data-k="${i}"]` });
+      const { fonts } = await cdp.send("CSS.getPlatformFontsForNode", { nodeId });
+      lines.push({ stack: s.stack, weight: s.weight, line: s.line, fonts: fonts.map((f) => ({ family: f.familyName, custom: f.isCustomFont, glyphs: f.glyphCount })), ...inPage.measured[i] });
+    }
+    return { loadErrors: inPage.loadErrors, lines };
+  } finally {
+    await cdp.detach();
+  }
+}
+
+/** 찍은 것을 cmap 으로 예상한 것과 댄다 — 투명·두부·시스템으로 떨어짐·다른 face 로 떨어짐 */
+export function judgeRender(p: FontPair, files: Map<string, FaceFile>, r: Rendered): string[] {
+  const bad = r.loadErrors.map((e) => `${e.family}(${e.weight}) 를 크롬이 못 읽는다 — ${e.error}`);
+  if (bad.length) return bad;
+  for (const l of r.lines) {
+    const where = `${l.stack}@${l.weight} ${l.line} 줄`;
+    const text = FONT_SAMPLE[l.line];
+    const css = p[l.stack as "display"];
+    const namesOf = (ch: string) => {
+      const f = faceForChar(p, css, l.weight, ch.codePointAt(0)!, files);
+      return f ? (files.get(f.src)?.names ?? []) : [];
+    };
+    const expected = [...new Set([...text].filter((ch) => ch !== " "))].map((ch) => namesOf(ch));
+    const allowed = new Set([...expected.flat(), ...namesOf(" "), ...stackFamilies(css).slice(0, 1).flatMap((fam) => p.faces.filter((f) => f.family === fam).flatMap((f) => files.get(f.src)?.names ?? []))]);
+    if (!l.ink) bad.push(`${where} 이 투명하게 찍힌다`);
+    if (l.tofu.length) bad.push(`${where} ${l.tofu.join("")} 가 두부로 찍힌다`);
+    for (const f of l.fonts) {
+      if (!f.custom) bad.push(`${where} 이 시스템 글꼴 ${f.family} 로 떨어진다(글리프 ${f.glyphs})`);
+      else if (!allowed.has(f.family)) bad.push(`${where} 이 예상 밖 글꼴 ${f.family} 로 찍힌다(글리프 ${f.glyphs})`);
+    }
+    const used = new Set(l.fonts.filter((f) => f.custom).map((f) => f.family));
+    const missed = [...new Set(expected.filter((names) => names.length && !names.some((n) => used.has(n))).map((names) => names[0]))];
+    if (missed.length) bad.push(`${where} 에서 ${missed.join("·")} 가 안 쓰였다 — 다른 글꼴로 떨어졌다`);
+  }
+  return bad;
+}
+
+const GENERIC = new Set(["serif", "sans-serif", "monospace", "cursive", "fantasy", "system-ui", "ui-serif", "ui-sans-serif", "ui-monospace", "ui-rounded", "emoji", "math", "fangsong"]);
+const esc = (s: string) => s.replace(/[&<>"]/g, (c) => `&${{ "&": "amp", "<": "lt", ">": "gt", '"': "quot" }[c]};`);
+
+/** 짝 견본 격자 한 장 — 사람이 눈으로 고르는 용. 같은 이름인데 파일이 다른 face 는 짝끼리 섞이지 않게 이름을 갈라 싣는다 */
+export async function fontSheet(list: { group: string; pair: FontPair }[], out: string, o: { log?: (s: string) => void } = {}): Promise<void> {
+  const log = o.log ?? (() => {});
+  const missing = [...new Set(list.flatMap(({ pair }) => pair.faces.map((f) => f.src)))].filter((u) => !existsSync(cachedFontFile(u)));
+  if (missing.length) {
+    log(`  글꼴 받기 ${missing.length}`);
+    await pool(missing, 8, (u) => get(u, "file"));
+  }
+  const alias = new Map<string, string>();
+  const sigs = new Map<string, string[]>();
+  const aliasOf = (p: FontPair, family: string) => {
+    const sig = p.faces.filter((f) => f.family === family).map((f) => `${f.weight}=${f.src}`).sort().join("|");
+    const seen = sigs.get(family) ?? [];
+    if (!seen.includes(sig)) sigs.set(family, [...seen, sig]);
+    const k = sigs.get(family)!.indexOf(sig);
+    const name = k ? `${family} #${k + 1}` : family;
+    for (const f of p.faces.filter((x) => x.family === family)) alias.set(`${name}\n${f.src}\n${f.weight}`, name);
+    return name;
+  };
+  const stackOf = (p: FontPair, css: string) =>
+    stackFamilies(css)
+      .map((fam) => (p.faces.some((f) => f.family === fam) ? `"${aliasOf(p, fam)}"` : GENERIC.has(fam) ? fam : `"${fam}"`))
+      .join(", ");
+  const cards = list.map(({ group, pair: p }) => {
+    const display = stackOf(p, p.monoAll ? p.mono : p.display);
+    const sans = stackOf(p, p.monoAll ? p.mono : p.sans);
+    const mono = stackOf(p, p.mono);
+    const meta = `${p.hangul ?? "?"} · ${[...new Set(p.faces.map((f) => f.license))].join(",")} · ${p.tags.join(" ")}`;
+    return `<section><header><b>${esc(p.id)}</b><span>${esc(group)}</span></header>
+<p class=t style='font-family:${display};font-weight:${p.weightDisplay};letter-spacing:${p.tracking}'>오늘의 제목 Title 2026</p>
+<p class=b style='font-family:${sans};font-weight:${p.weightBody}'>${esc(p.ko)} — Sphinx of black quartz ₩12,000 · 45% → 0123456789</p>
+<p class=m style='font-family:${mono};font-weight:${p.weightBody}'>const 값 = 42; // 결과 → 1,234</p>
+<footer>${esc(p.name)} · ${esc(meta)}</footer></section>`;
+  });
+  const faces = [...alias.entries()].map(([k, name]) => {
+    const [, src, weight] = k.split("\n");
+    return { family: name, src, weight };
+  });
+  const cols = Math.min(8, Math.max(3, Math.ceil(list.length / 40)));
+  const html = `<!doctype html><meta charset=utf-8><style>
+  body { margin: 0; padding: 28px; background: #efece6; color: #171717; font: 14px/1.35 -apple-system, "Apple SD Gothic Neo", sans-serif; }
+  h1 { font-size: 20px; margin: 0 0 18px; font-weight: 600; }
+  main { display: grid; grid-template-columns: repeat(${cols}, 520px); gap: 14px; }
+  section { background: #fff; border: 1px solid #d9d4ca; padding: 14px 18px 12px; overflow: hidden; }
+  header { display: flex; justify-content: space-between; font: 12px/1 ui-monospace, monospace; color: #6b655c; }
+  header b { color: #171717; }
+  p { margin: 10px 0 0; white-space: nowrap; overflow: hidden; text-overflow: clip; }
+  .t { font-size: 44px; line-height: 1.15; }
+  .b { font-size: 19px; white-space: normal; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; }
+  .m { font-size: 17px; color: #3a3631; }
+  footer { margin-top: 10px; font-size: 12px; color: #8a8378; white-space: nowrap; overflow: hidden; }
+</style><h1>kasaframe 글꼴 짝 ${list.length} — ${esc([...new Set(list.map((x) => x.group))].join(" · "))}</h1><main>${cards.join("")}</main>`;
+  const browser = await launch();
+  try {
+    const context = await browser.newContext({ deviceScaleFactor: 1, viewport: { width: cols * 534 + 56, height: 900 } });
+    await serveCached(context);
+    const page = await context.newPage();
+    await page.goto(ORIGIN);
+    const failed = await page.evaluate(
+      async ({ html, faces }) => {
+        document.open();
+        document.write(html);
+        document.close();
+        const bad: string[] = [];
+        await Promise.all(
+          faces.map(async (f) => {
+            const ff = new FontFace(f.family, `url("${f.src}")`, { weight: f.weight, display: "block" });
+            document.fonts.add(ff);
+            await ff.load().catch(() => bad.push(`${f.family}(${f.weight})`));
+          }),
+        );
+        await document.fonts.ready;
+        return bad;
+      },
+      { html, faces },
+    );
+    if (failed.length) log(`  못 실은 face: ${failed.join(", ")}`);
+    mkdirSync(join(out, ".."), { recursive: true });
+    await page.screenshot({ path: out, fullPage: true });
+  } finally {
+    await browser.close();
+  }
+}
+
+const NOTICE_HEAD = "글꼴 짝 — packages/themes/kit/fonts.json · kit/fonts/<무리>.json (kf fonts notice --write 가 이 절을 짓는다)";
+const RULE = "-".repeat(70);
+
+/** NOTICE 의 글꼴 절 — 글꼴 이름마다 라이선스와 라이선스 글 한 줄 */
+export function noticeSection(pairs: FontPair[]): string {
+  const rows = new Map<string, [string, string, string]>();
+  for (const f of pairs.flatMap((p) => p.faces)) rows.set(`${f.family}\n${f.license}\n${f.source}`, [f.family, f.license, f.source]);
+  const list = [...rows.values()].sort((a, b) => a[0].localeCompare(b[0]) || a[2].localeCompare(b[2]));
+  const w = Math.max(...list.map((r) => r[0].length));
+  const lw = Math.max(...list.map((r) => r[1].length));
+  return [
+    RULE,
+    NOTICE_HEAD,
+    "글꼴 파일은 싣지 않는다 — 영상을 구울 때 판을 박은 주소(jsdelivr gh@커밋·npm@판)에서 받는다. 모두 상업 이용·영상·",
+    "웹 임베딩이 허용된 라이선스이고 출처 표기 의무가 없다. kf fonts check 가 라이선스 글이나 파일 name 13 에서 그 문구를 대 본다.",
+    `짝 ${pairs.length} · 글꼴 ${new Set(list.map((r) => r[0])).size} — 이름 · 라이선스 · 라이선스 글`,
+    "",
+    ...list.map(([fam, lic, src]) => `  ${fam.padEnd(w)}  ${lic.padEnd(lw)}  ${src}`),
+    "",
+  ].join("\n");
+}
+
+/** NOTICE 글에서 글꼴 절을 갈아 끼운다 — 없으면 끝에 붙인다 */
+export function replaceNotice(notice: string, section: string): string {
+  const lines = notice.split("\n");
+  const head = lines.indexOf(NOTICE_HEAD);
+  if (head < 0) return `${notice.trimEnd()}\n\n${section}`;
+  const from = lines[head - 1] === RULE ? head - 1 : head;
+  const next = lines.findIndex((l, i) => i > head && l === RULE);
+  return [...lines.slice(0, from), ...section.split("\n").slice(0, -1), ...(next < 0 ? [""] : lines.slice(next))].join("\n");
+}