kasaframe 0.1.4 → 0.1.5

package/packages/themes/package.json

@@ -14,7 +14,9 @@
     "./vary": "./src/vary.ts",
     "./color": "./src/color.ts",
     "./palette": "./src/palette.ts",
-    "./look": "./src/look.ts"
+    "./look": "./src/look.ts",
+    "./fonts": "./src/fonts.ts",
+    "./fontfile": "./src/fontfile.ts"
   },
   "dependencies": {
     "@kasaframe/core": "0.0.0",

package/packages/themes/src/fontfile.ts

@@ -0,0 +1,183 @@
+// 글꼴 파일에서 짝 검사에 드는 표(cmap·OS/2·fvar·name)만 읽는다 — TTF/OTF·WOFF·WOFF2.
+// fontTools 대신 직접 읽는 까닭: 드는 것이 글자 목록·굵기·이름뿐이고, WOFF2 도 cmap 은 변환 없이 brotli 한 줄기에 있어
+// node zlib 만으로 풀린다. 파이썬 venv 를 깔 일이 없어 kf fonts check 가 vitest 안에서도, 처음 쓰는 기계에서도 바로 돈다.
+import { brotliDecompressSync, inflateSync } from "node:zlib";
+
+export interface FontFileInfo {
+  format: "ttf" | "otf" | "woff" | "woff2";
+  /** cmap 이 글리프로 잇는 코드 포인트(글리프 0 은 뺀다) */
+  cps: Set<number>;
+  /** OS/2 usWeightClass */
+  weight: number;
+  /** 가변 글꼴의 wght 축 [최소, 최대] */
+  wght?: [number, number];
+  /** name 표 family(16·1) — 크롬이 찍은 글꼴 이름을 이것에 댄다 */
+  families: string[];
+  postScript: string;
+  /** name 13(라이선스 설명) — 배포처 페이지가 JS 로 그려져 글을 못 받을 때 파일 자체가 밝힌 라이선스 */
+  licenseText: string;
+}
+
+const tag = (b: Buffer, o: number) => b.toString("latin1", o, o + 4);
+
+// WOFF2 표 머리의 알려진 태그 63개(차례가 곧 번호)
+const WOFF2_TAGS = "cmap head hhea hmtx maxp name OS/2 post cvt  fpgm glyf loca prep CFF  VORG EBDT EBLC gasp hdmx kern LTSH PCLT VDMX vhea vmtx BASE GDEF GPOS GSUB EBSC JSTF MATH CBDT CBLC COLR CPAL SVG  sbix acnt avar bdat bloc bsln cvar fdsc feat fmtx fvar gvar hsty just lcar mort morx opbd prop trak Zapf Silf Glat Gloc Feat Sill"
+  .match(/.{4}(?: |$)/g)!
+  .map((s) => s.slice(0, 4));
+
+function base128(b: Buffer, o: { at: number }): number {
+  let v = 0;
+  for (let i = 0; i < 5; i++) {
+    const x = b[o.at++];
+    v = v * 128 + (x & 0x7f);
+    if (!(x & 0x80)) return v;
+  }
+  throw new Error("WOFF2 UIntBase128 이 길다");
+}
+
+function tablesOf(b: Buffer): { format: FontFileInfo["format"]; tables: Map<string, Buffer> } {
+  const sig = tag(b, 0);
+  const tables = new Map<string, Buffer>();
+  if (sig === "wOF2") {
+    if (tag(b, 4) === "ttcf") throw new Error("WOFF2 글꼴 모음(ttc)은 읽지 않는다");
+    const n = b.readUInt16BE(12);
+    const compressed = b.readUInt32BE(20);
+    const o = { at: 48 };
+    const dir: { tag: string; len: number }[] = [];
+    for (let i = 0; i < n; i++) {
+      const flags = b[o.at++];
+      const t = (flags & 0x3f) === 63 ? tag(b, (o.at += 4) - 4) : WOFF2_TAGS[flags & 0x3f];
+      const version = flags >> 6;
+      const orig = base128(b, o);
+      const transformed = t === "glyf" || t === "loca" ? version !== 3 : version !== 0;
+      dir.push({ tag: t, len: transformed ? base128(b, o) : orig });
+    }
+    const data = brotliDecompressSync(b.subarray(o.at, o.at + compressed));
+    let at = 0;
+    for (const d of dir) {
+      tables.set(d.tag, data.subarray(at, at + d.len));
+      at += d.len;
+    }
+    return { format: "woff2", tables };
+  }
+  if (sig === "wOFF") {
+    const n = b.readUInt16BE(12);
+    for (let i = 0; i < n; i++) {
+      const r = 44 + i * 20;
+      const [off, comp, orig] = [b.readUInt32BE(r + 4), b.readUInt32BE(r + 8), b.readUInt32BE(r + 12)];
+      const raw = b.subarray(off, off + comp);
+      tables.set(tag(b, r), comp < orig ? inflateSync(raw) : raw);
+    }
+    return { format: "woff", tables };
+  }
+  const v = b.readUInt32BE(0);
+  if (v !== 0x00010000 && sig !== "OTTO" && sig !== "true") throw new Error(`글꼴 파일이 아니다(머리 ${JSON.stringify(sig)})`);
+  const n = b.readUInt16BE(4);
+  for (let i = 0; i < n; i++) {
+    const r = 12 + i * 16;
+    tables.set(tag(b, r), b.subarray(b.readUInt32BE(r + 8), b.readUInt32BE(r + 8) + b.readUInt32BE(r + 12)));
+  }
+  return { format: sig === "OTTO" ? "otf" : "ttf", tables };
+}
+
+function cmapOf(t: Buffer): Set<number> {
+  const out = new Set<number>();
+  const n = t.readUInt16BE(2);
+  const seen = new Set<number>();
+  for (let i = 0; i < n; i++) {
+    const [platform, encoding, off] = [t.readUInt16BE(4 + i * 8), t.readUInt16BE(6 + i * 8), t.readUInt32BE(8 + i * 8)];
+    if (!(platform === 0 || (platform === 3 && (encoding === 1 || encoding === 10))) || seen.has(off)) continue;
+    seen.add(off);
+    const s = t.subarray(off);
+    const format = s.readUInt16BE(0);
+    if (format === 4) {
+      const seg = s.readUInt16BE(6) / 2;
+      const ends = 14, starts = 16 + seg * 2, deltas = starts + seg * 2, ranges = deltas + seg * 2;
+      for (let k = 0; k < seg; k++) {
+        const [end, start, delta, range] = [s.readUInt16BE(ends + k * 2), s.readUInt16BE(starts + k * 2), s.readInt16BE(deltas + k * 2), s.readUInt16BE(ranges + k * 2)];
+        for (let c = start; c <= end && c !== 0xffff; c++) {
+          let g: number;
+          if (range === 0) g = (c + delta) & 0xffff;
+          else {
+            const at = ranges + k * 2 + range + (c - start) * 2;
+            g = at + 2 <= s.length ? s.readUInt16BE(at) : 0;
+            if (g) g = (g + delta) & 0xffff;
+          }
+          if (g) out.add(c);
+        }
+      }
+    } else if (format === 12 || format === 13) {
+      const groups = s.readUInt32BE(12);
+      for (let k = 0; k < groups; k++) {
+        const r = 16 + k * 12;
+        const [start, end, g0] = [s.readUInt32BE(r), s.readUInt32BE(r + 4), s.readUInt32BE(r + 8)];
+        for (let c = start; c <= end; c++) if (format === 13 ? g0 : g0 + (c - start)) out.add(c);
+      }
+    }
+  }
+  return out;
+}
+
+/** name 표에서 이 번호들의 글 — 플랫폼·언어별로 다른 것까지 모두, 겹치면 하나 */
+function namesOf(t: Buffer | undefined, ids: number[]): string[] {
+  if (!t) return [];
+  const count = t.readUInt16BE(2);
+  const strings = t.readUInt16BE(4);
+  const out = new Set<string>();
+  for (const id of ids)
+    for (let i = 0; i < count; i++) {
+      const r = 6 + i * 12;
+      const [platform, , , nameId, len, off] = [0, 2, 4, 6, 8, 10].map((k) => t.readUInt16BE(r + k));
+      if (nameId !== id) continue;
+      const raw = t.subarray(strings + off, strings + off + len);
+      const s = platform === 1 ? raw.toString("latin1") : Buffer.from(raw).swap16().toString("utf16le");
+      if (s) out.add(s);
+    }
+  return [...out];
+}
+
+export function readFontFile(b: Buffer): FontFileInfo {
+  const { format, tables } = tablesOf(b);
+  const cmap = tables.get("cmap");
+  if (!cmap) throw new Error("cmap 표가 없다");
+  const os2 = tables.get("OS/2");
+  const fvar = tables.get("fvar");
+  let wght: [number, number] | undefined;
+  if (fvar) {
+    const [axes, count, size] = [fvar.readUInt16BE(4), fvar.readUInt16BE(8), fvar.readUInt16BE(10)];
+    for (let i = 0; i < count; i++) {
+      const r = axes + i * size;
+      if (tag(fvar, r) === "wght") wght = [Math.round(fvar.readInt32BE(r + 4) / 65536), Math.round(fvar.readInt32BE(r + 12) / 65536)];
+    }
+  }
+  return {
+    format,
+    cps: cmapOf(cmap),
+    weight: os2 ? os2.readUInt16BE(4) : 400,
+    ...(wght ? { wght } : {}),
+    families: namesOf(tables.get("name"), [16, 1]),
+    postScript: namesOf(tables.get("name"), [6])[0] ?? "",
+    licenseText: namesOf(tables.get("name"), [13]).join("\n"),
+  };
+}
+
+const HANGUL = [0xac00, 0xd7a3] as const;
+let ks: number[] | null = null;
+/** KS X 1001 완성형 한글 2,350자 — EUC-KR 의 B0A1–C8FE */
+export function ksHangul(): number[] {
+  if (ks) return ks;
+  const bytes: number[] = [];
+  for (let hi = 0xb0; hi <= 0xc8; hi++) for (let lo = 0xa1; lo <= 0xfe; lo++) bytes.push(hi, lo);
+  return (ks = [...new TextDecoder("euc-kr").decode(Uint8Array.from(bytes))].map((c) => c.codePointAt(0)!));
+}
+
+export type HangulCover = "full" | "ks2350" | "partial" | "none";
+
+/** 한글 음절 덮음 — full 은 11,172자 전부, ks2350 은 KS X 1001 2,350자를 다 가진 것 */
+export function hangulCover(cps: Set<number>): { cover: HangulCover; syllables: number; ksMissing: number } {
+  let syllables = 0;
+  for (let c = HANGUL[0]; c <= HANGUL[1]; c++) if (cps.has(c)) syllables++;
+  const ksMissing = ksHangul().filter((c) => !cps.has(c)).length;
+  const cover = syllables === HANGUL[1] - HANGUL[0] + 1 ? "full" : syllables && !ksMissing ? "ks2350" : syllables ? "partial" : "none";
+  return { cover, syllables, ksMissing };
+}

package/packages/themes/src/fonts.ts

@@ -0,0 +1,296 @@
+// 글꼴 짝 — kit/fonts.json 과 kit/fonts/<무리>.json 을 합친 목록, 그리고 짝을 넣기 전에 거르는 판정(SPEC 9 변주의 글꼴 축).
+// 판정은 순수 함수로 두고, 주소를 받고 크롬으로 찍어 보는 일은 kf fonts check(packages/cli/src/fonts.ts)가 한다.
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { FontFace } from "@kasaframe/core";
+import { hangulCover, type HangulCover } from "./fontfile.ts";
+
+export interface PairFace extends FontFace {
+  /** OFL-1.1 · Apache-2.0 · 그만큼 열린 자체 라이선스 이름 */
+  license: string;
+  /** 라이선스 글 주소 — 판을 박은 것이면 kf fonts check 가 글까지 대 본다 */
+  source: string;
+}
+
+export interface FontPair {
+  id: string;
+  name: string;
+  ko: string;
+  tags: string[];
+  /** 한글 음절 덮음 — full 은 11,172자, ks2350 은 KS X 1001 2,350자(드문 음절은 다음 글꼴로 떨어져 섞여 보일 수 있다) */
+  hangul: "full" | "ks2350";
+  sans: string;
+  display: string;
+  mono: string;
+  faces: PairFace[];
+  weightDisplay: number;
+  weightBody: number;
+  tracking: string;
+  monoAll?: boolean;
+}
+
+export interface FontGroup {
+  /** kit/fonts.json 은 core, kit/fonts/<무리>.json 은 <무리> */
+  group: string;
+  file: string;
+  pairs: FontPair[];
+}
+
+const kitDir = fileURLToPath(new URL("../kit/", import.meta.url));
+
+export function fontGroups(dir = kitDir): FontGroup[] {
+  const sub = join(dir, "fonts");
+  const files = existsSync(sub) ? readdirSync(sub).filter((f) => f.endsWith(".json")).sort() : [];
+  return [{ group: "core", file: join(dir, "fonts.json") }, ...files.map((f) => ({ group: f.slice(0, -5), file: join(sub, f) }))].map((g) => {
+    const pairs: FontPair[] = JSON.parse(readFileSync(g.file, "utf8"));
+    if (!Array.isArray(pairs)) throw new Error(`${g.file}: 글꼴 짝 배열이 아니다`);
+    return { ...g, pairs };
+  });
+}
+
+/** 무리 파일은 학생마다 따로 채워서, 합칠 때 id 가 겹치면 어느 쪽이 이기는지 숨지 않게 멈춘다 */
+export function loadFontPairs(dir = kitDir): FontPair[] {
+  const seen = new Map<string, string>();
+  return fontGroups(dir).flatMap((g) =>
+    g.pairs.map((p) => {
+      const prev = seen.get(p.id);
+      if (prev) throw new Error(`글꼴 짝 id ${p.id} 이 겹친다 — ${prev} · ${g.file}`);
+      seen.set(p.id, g.file);
+      return p;
+    }),
+  );
+}
+
+let pairs: FontPair[] | null = null;
+export const fontPairs = (): FontPair[] => (pairs ??= loadFontPairs());
+
+/**
+ * 라이선스 글에서 찾을 문구 — 이름만 적고 글이 다르면 잡는다. 목록 밖 이름은 사람이 글을 읽는다.
+ * OFL 은 머리줄 없이 본문만 넣은 글꼴(배민 name 13)이 있어 1.1 본문에만 있는 낱말도 받는다 — 1.0 은 cooperative·distributed using
+ */
+export const LICENSE_TEXT: Record<string, RegExp> = {
+  "OFL-1.1": /SIL OPEN FONT LICENSE[\s\S]{0,40}Version 1\.1|collaborative\s+font\s+projects[\s\S]*distributed\s+entirely\s+under\s+this\s+license/i,
+  "Apache-2.0": /Apache License[\s\S]{0,40}Version 2\.0/i,
+};
+
+const COMMIT = /^[0-9a-f]{7,40}$/;
+const VERSION = /^v?\d+(\.\d+)*([-+][\w.]+)?$/;
+const EXACT = /^\d+\.\d+\.\d+([-+][\w.]+)?$/;
+
+/**
+ * 라이선스를 무엇으로 확인했나 — 라이선스 글(source)이나, 판 박힌 그 파일의 name 13 에 이름에 맞는 문구가 있으면 된다.
+ * 「OFL」 석 자만 적은 배포처 문구는 받지 않는다(판도 조건도 안 보인다). 목록 밖 이름은 사람이 읽을 것으로 남긴다
+ */
+export function licenseVerdict(f: Pick<PairFace, "family" | "weight" | "license" | "source">, sourceText: string, fileText: string): { problem?: string; note?: string } {
+  const where = `${f.family}(${f.weight})`;
+  const want = LICENSE_TEXT[f.license];
+  if (!want) return { note: `${where} 라이선스 ${f.license} — 목록 밖이라 사람이 글을 읽고 상업·영상 사용·출처 표기 의무를 확인한다` };
+  if (want.test(sourceText) || want.test(fileText)) return {};
+  return { problem: `${where} 라이선스 글(${f.source})에도 파일 name 13 에도 ${f.license} 문구가 없다 — 판 박힌 라이선스 글 주소를 찾거나, 배포처의 자체 표기뿐이면 license 를 목록 밖 이름으로 적어 사람 확인으로` };
+}
+
+/** 주소가 판을 박았나 — @main·@latest·범위는 저쪽이 바뀌면 같은 영상이 다르게 구워진다 */
+export function pinProblem(url: string): string | null {
+  let u: URL;
+  try {
+    u = new URL(url);
+  } catch {
+    return `주소가 아니다: ${url}`;
+  }
+  if (u.protocol !== "https:") return `https 가 아니다: ${url}`;
+  if (u.hostname === "fonts.googleapis.com") return "구글 폰트 CSS 는 unicode-range 조각이라 글이 투명하게 찍힌다 — 파일 하나 주소로";
+  if (u.hostname === "cdn.jsdelivr.net") {
+    const gh = /^\/gh\/([^/]+)\/([^/@]+)(?:@([^/]+))?\//.exec(u.pathname);
+    if (gh) {
+      const ref = gh[3];
+      if (!ref) return `판이 없다 — gh/${gh[1]}/${gh[2]}@<커밋|태그>`;
+      if (gh[1] === "google" && gh[2] === "fonts") return COMMIT.test(ref) && ref.length === 40 ? null : `google/fonts 는 커밋(40자)으로 박는다 — @${ref}`;
+      return COMMIT.test(ref) || VERSION.test(ref) ? null : `브랜치처럼 보인다 — @${ref}, 커밋이나 판 태그로`;
+    }
+    const npm = /^\/npm\/((?:@[^/]+\/)?[^/@]+)(?:@([^/]+))?\//.exec(u.pathname);
+    if (npm) {
+      if (!npm[2]) return `판이 없다 — npm/${npm[1]}@<x.y.z>`;
+      return EXACT.test(npm[2]) ? null : `판 범위 @${npm[2]} — 정확한 판(x.y.z)으로`;
+    }
+    return `jsdelivr 의 gh·npm 꼴이 아니다: ${u.pathname}`;
+  }
+  if (u.hostname === "raw.githubusercontent.com") {
+    const ref = u.pathname.split("/")[3] ?? "";
+    return COMMIT.test(ref) && ref.length === 40 ? null : `raw.githubusercontent 는 커밋(40자)으로 박는다 — ${ref}`;
+  }
+  return `판이 박혔는지 모르는 배포처 ${u.hostname} — jsdelivr gh@커밋·npm@판으로`;
+}
+
+/** CSS font-family 값 → 이름 차례(따옴표 벗김) */
+export const stackFamilies = (stack: string): string[] => stack.split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+
+const FALLBACK = "Pretendard Variable";
+const fileExt = (src: string) => /\.(woff2|woff|ttf|otf)$/i.exec(new URL(src).pathname)?.[1];
+
+/** 받지 않고 보는 것 — 칸·판·라이선스 이름·스택 */
+export function pairProblems(p: FontPair): string[] {
+  const bad: string[] = [];
+  for (const k of ["id", "name", "ko", "sans", "display", "mono", "tracking"] as const) if (!p[k]) bad.push(`${k} 가 비었다`);
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(p.id)) bad.push(`id ${p.id} 은 소문자·숫자·하이픈`);
+  if (!p.tags?.length) bad.push("tags 가 비었다");
+  if (p.hangul !== "full" && p.hangul !== "ks2350") bad.push(`hangul 은 full·ks2350 — ${p.hangul}`);
+  for (const k of ["weightDisplay", "weightBody"] as const) if (!(p[k] >= 1 && p[k] <= 1000)) bad.push(`${k} ${p[k]} 이 1–1000 밖`);
+  if (!/^(0|-?\d*\.?\d+em)$/.test(p.tracking ?? "")) bad.push(`tracking ${p.tracking} 은 em 값`);
+  if (!p.faces?.length) return [...bad, "faces 가 비었다"];
+  const families = new Set(p.faces.map((f) => f.family));
+  for (const k of ["sans", "display", "mono"] as const) {
+    const st = stackFamilies(p[k] ?? "");
+    if (!families.has(st[0])) bad.push(`${k} 첫 글꼴 ${st[0]} 의 face 가 없다 — 기계마다 다른 시스템 글꼴로 찍힌다`);
+    if (!st.includes(FALLBACK)) bad.push(`${k} 가 ${FALLBACK} 로 끝나지 않는다 — 한글이 설 바닥이 없다`);
+  }
+  if (!families.has(FALLBACK)) bad.push(`${FALLBACK} face 가 없다`);
+  const used = new Set(["sans", "display", "mono"].flatMap((k) => stackFamilies(p[k as "sans"])));
+  for (const f of p.faces) {
+    const where = `${f.family}(${f.weight ?? "?"})`;
+    if (!used.has(f.family)) bad.push(`${where} 를 어느 스택도 안 쓴다`);
+    const pin = pinProblem(f.src);
+    if (pin) bad.push(`${where} 주소 — ${pin}`);
+    else if (!fileExt(f.src)) bad.push(`${where} 주소가 .woff2·.woff·.ttf·.otf 파일이 아니다`);
+    if (!f.weight || !/^\d+( \d+)?$/.test(f.weight)) bad.push(`${where} weight 는 "700" 이나 가변 범위 "100 900"`);
+    if (!f.license) bad.push(`${where} license 가 없다`);
+    if (!f.source) bad.push(`${where} source 가 없다`);
+    else if (!/^https:\/\/\S+$/.test(f.source)) bad.push(`${where} source 가 https 주소가 아니다`);
+  }
+  return bad;
+}
+
+/** 파일에서 읽은 것 중 판정에 드는 것 */
+export interface FaceFile {
+  cps: Set<number>;
+  weight: number;
+  wght?: [number, number];
+  /** 파일 name 표의 family(1·16) — 크롬이 찍은 글꼴을 이 이름으로 댄다 */
+  names: string[];
+  licenseText?: string;
+}
+
+const rangeOf = (f: FontFace): [number, number] => {
+  const [a, b = a] = (f.weight ?? "100 900").split(" ").map(Number);
+  return [a, b];
+};
+
+/** CSS 글꼴 고르기의 굵기 차례 — 같은 이름 face 중 w 에 쓸 하나 */
+export function faceFor(faces: PairFace[], family: string, w: number): PairFace | undefined {
+  const c = faces.filter((f) => f.family === family);
+  const hit = c.find((f) => rangeOf(f)[0] <= w && w <= rangeOf(f)[1]);
+  if (hit || !c.length) return hit;
+  const below = c.filter((f) => rangeOf(f)[1] < w).sort((a, b) => rangeOf(b)[1] - rangeOf(a)[1]);
+  const above = c.filter((f) => rangeOf(f)[0] > w).sort((a, b) => rangeOf(a)[0] - rangeOf(b)[0]);
+  if (w >= 400 && w <= 500) {
+    const upTo500 = above.filter((f) => rangeOf(f)[0] <= 500);
+    return upTo500[0] ?? below[0] ?? above[0];
+  }
+  return w < 400 ? (below[0] ?? above[0]) : (above[0] ?? below[0]);
+}
+
+/** 이 굵기로 고른 face 가 실제로 내는 굵기 */
+const servedWeight = (f: PairFace, w: number): number => {
+  const [a, b] = rangeOf(f);
+  return Math.min(b, Math.max(a, w));
+};
+
+/** 글자 하나를 스택에서 누가 그리나 — 짝의 face 가 아무도 없으면 null(시스템 글꼴로 떨어짐) */
+export function faceForChar(p: FontPair, stack: string, w: number, cp: number, files: Map<string, FaceFile>): PairFace | null {
+  for (const fam of stackFamilies(stack)) {
+    const f = faceFor(p.faces, fam, w);
+    if (f && files.get(f.src)?.cps.has(cp)) return f;
+  }
+  return null;
+}
+
+/** 견본 — 한글 줄은 KS X 1001 안 낱자만이라 ks2350 짝도 한 글꼴로 찍혀야 한다 */
+export const FONT_SAMPLE = { ko: "다람쥐 헌 쳇바퀴에 타고파", latin: "Sphinx of black quartz, judge my vow", num: "₩12,000 · 45% → 0123456789" } as const;
+export type SampleLine = keyof typeof FONT_SAMPLE;
+
+/**
+ * 제목에 실제로 쓸 굵기 — 제목 스택 첫 글꼴(monoAll 이면 고정폭)의 가장 굵은 실제 단을 넘지 않게.
+ * 넘겨 두면 크롬이 가짜 굵기로 그리고, 도트 글꼴은 화소가 번진다(galmuri 짝의 GalmuriMono11 은 400 하나뿐)
+ */
+export function titleWeight(p: FontPair, monoAll = false): number {
+  const fam = stackFamilies(monoAll ? p.mono : p.display)[0];
+  const faces = p.faces.filter((f) => f.family === fam);
+  return faces.length ? Math.min(p.weightDisplay, Math.max(...faces.map((f) => rangeOf(f)[1]))) : p.weightDisplay;
+}
+
+export type StackName = "display" | "sans" | "mono";
+/** 짝이 실제로 쓰는 (스택, 굵기) — monoAll 짝은 고정폭이 제목·본문을 다 맡는다 */
+export function stackUses(p: FontPair): { stack: StackName; css: string; weight: number }[] {
+  const out = [
+    { stack: "display" as const, css: p.display, weight: titleWeight(p) },
+    { stack: "sans" as const, css: p.sans, weight: p.weightBody },
+    { stack: "mono" as const, css: p.mono, weight: p.weightBody },
+  ];
+  if (p.monoAll) out.push({ stack: "mono", css: p.mono, weight: titleWeight(p, true) });
+  return out;
+}
+
+export interface PairMeasure {
+  /** 스택마다 한글을 그리는 face 의 덮음 중 가장 나쁜 것 */
+  hangul: HangulCover;
+  syllables: number;
+  /** 제목 한글 글꼴의 가장 굵은 단 */
+  boldest: number;
+  problems: string[];
+  notes: string[];
+}
+
+const RANK: Record<HangulCover, number> = { full: 3, ks2350: 2, partial: 1, none: 0 };
+
+/** 스택에서 한글을 맡는 face — 음절을 하나라도 가진 첫 face(「가」 하나로 보면 그 글자만 빠진 글꼴을 놓친다) */
+function hangulFace(p: FontPair, stack: string, w: number, files: Map<string, FaceFile>): PairFace | null {
+  for (const fam of stackFamilies(stack)) {
+    const f = faceFor(p.faces, fam, w);
+    if (f && hangulCover(files.get(f.src)?.cps ?? new Set()).syllables) return f;
+  }
+  return null;
+}
+
+/** 받은 파일로 보는 것 — 한글 덮음·굵기·견본 글자가 시스템 글꼴로 떨어지는지 */
+export function measurePair(p: FontPair, files: Map<string, FaceFile>): PairMeasure {
+  const problems: string[] = [];
+  const notes: string[] = [];
+  for (const f of p.faces) {
+    const file = files.get(f.src);
+    if (!file) continue;
+    const [a, b] = rangeOf(f);
+    const where = `${f.family}(${f.weight})`;
+    // 한 굵기 제목체를 제목 굵기로 적은 것은 가짜 굵기를 막으려는 뜻이라 알리지 않는다
+    const meant = a === p.weightDisplay && p.faces.filter((x) => x.family === f.family).length === 1;
+    if (a !== b) {
+      if (!file.wght) problems.push(`${where} 는 가변이 아닌데 굵기 범위를 적었다 — 파일은 고정 ${file.weight}`);
+      else if (a < file.wght[0] || b > file.wght[1]) problems.push(`${where} 범위가 파일 wght ${file.wght.join("–")} 밖`);
+    } else if (!file.wght && !meant && Math.abs(file.weight - a) >= 100) notes.push(`${where} 파일 usWeightClass 는 ${file.weight}`);
+  }
+  let worst: HangulCover = "full";
+  let syllables = 11172;
+  for (const u of stackUses(p)) {
+    for (const [line, text] of Object.entries(FONT_SAMPLE)) {
+      const sys = [...new Set([...text].filter((ch) => ch !== " " && !faceForChar(p, u.css, u.weight, ch.codePointAt(0)!, files)))];
+      if (sys.length) problems.push(`${u.stack} ${line} 줄 ${sys.join("")} 를 짝의 글꼴이 못 그려 시스템 글꼴로 떨어진다`);
+    }
+    const ko = hangulFace(p, u.css, u.weight, files);
+    const cov = ko ? hangulCover(files.get(ko.src)!.cps) : { cover: "none" as const, syllables: 0 };
+    if (RANK[cov.cover] < RANK[worst] || (cov.cover === worst && cov.syllables < syllables)) [worst, syllables] = [cov.cover, cov.syllables];
+    for (const fam of new Set([ko?.family, stackFamilies(u.css)[0]])) {
+      const f = fam && faceFor(p.faces, fam, u.weight);
+      if (!f) continue;
+      const got = servedWeight(f, u.weight);
+      if (u.weight >= 600 && got < 600) problems.push(`${u.stack} ${fam} 에 굵기 ${u.weight} 단이 없어 크롬이 가짜 굵기로 그린다(있는 단 ${got})`);
+      else if (Math.abs(got - u.weight) >= 150) notes.push(`${u.stack} ${fam} 굵기 ${u.weight} 대신 ${got}`);
+    }
+  }
+  if (worst === "partial" || worst === "none") problems.push(`한글 음절 ${syllables}자 — KS X 1001 2,350자를 다 덮지 못한다`);
+  else if (worst !== p.hangul) problems.push(`hangul 을 ${p.hangul} 로 적었는데 재 보면 ${worst}`);
+  const ko = hangulFace(p, p.display, titleWeight(p), files);
+  const boldest = ko ? Math.max(...p.faces.filter((f) => f.family === ko.family).map((f) => rangeOf(f)[1])) : 0;
+  if (titleWeight(p) < p.weightDisplay) notes.push(`제목 굵기 ${p.weightDisplay} → ${titleWeight(p)}(제목 첫 글꼴의 가장 굵은 단)`);
+  if (p.monoAll && titleWeight(p, true) < p.weightDisplay) notes.push(`monoAll 세계에서는 제목 굵기 ${p.weightDisplay} → ${titleWeight(p, true)}(고정폭 face 의 가장 굵은 단)`);
+  if (ko && boldest < 600 && !p.tags.includes("display")) notes.push(`제목 굵은 단이 없다 — 한글 제목 글꼴 ${ko.family} 의 가장 굵은 단 ${boldest}`);
+  return { hangul: worst, syllables, boldest, problems, notes };
+}

package/packages/themes/src/index.ts

@@ -5,7 +5,8 @@ import { fileURLToPath } from "node:url";
 import type { KfStyle } from "@kasaframe/core";
 import { splitThemeId } from "./name.ts";
 import { THEME_STATUSES, type Theme, type ThemeCard, type ThemeManifest, type ThemeStatus, type VariantManifest } from "./types.ts";
-import { allowedFonts, fontPairs, mergeVariant } from "./vary.ts";
+import { fontPairs } from "./fonts.ts";
+import { allowedFonts, mergeVariant } from "./vary.ts";
 
 export type * from "./types.ts";
 export { THEME_STATUSES } from "./types.ts";
@@ -45,9 +46,16 @@ export function checkTheme(dir: string): string[] {
   if (s.name !== m.id) bad.push(`style.json name 이 테마 id 와 다르다`);
   if (m.vary) {
     const known = new Set(fontPairs().map((p) => p.id));
-    for (const f of m.vary.fonts ?? []) if (f !== "base" && !f.startsWith("tag:") && !known.has(f)) bad.push(`vary.fonts 의 글꼴 짝 ${f} 이 kit/fonts.json 에 없다`);
+    for (const f of m.vary.fonts ?? []) {
+      if (f.startsWith("tag:") ? !fontPairs().some((p) => f.slice(4).split("+").every((t) => p.tags.includes(t))) : f !== "base" && !known.has(f)) bad.push(`vary.fonts 의 ${f} 에 맞는 글꼴 짝이 kit/fonts.json·kit/fonts/ 에 없다`);
+    }
     if (m.vary.fonts && !allowedFonts(m.vary).length) bad.push("vary.fonts 에 맞는 글꼴 짝이 하나도 없다");
     for (const k of [...(m.vary.keep ?? []), ...(m.vary.fixedHue ?? [])]) if (s.colors && !(k in s.colors)) bad.push(`vary 의 색 열쇠 ${k} 가 style.json colors 에 없다`);
+    for (const [scheme, pal] of Object.entries(m.vary.palettes ?? {})) {
+      const want = Object.keys(s.colors ?? {}).sort().join(",");
+      if (s.colors && Object.keys(pal).sort().join(",") !== want) bad.push(`vary.palettes.${scheme} 의 색 열쇠가 style.json colors 와 다르다`);
+      if (!(m.vary.scheme ?? [s.scheme]).includes(scheme as "light" | "dark")) bad.push(`vary.palettes.${scheme} 가 있는데 vary.scheme 에 ${scheme} 가 없다`);
+    }
   }
   if (m.tags && (!Array.isArray(m.tags.mood) || !Array.isArray(m.tags.use) || !["light", "dark"].includes(m.tags.light) || !["2D", "3D"].includes(m.tags.dims))) bad.push("theme.json tags 는 { mood: [], light: light|dark, use: [], dims: 2D|3D }");
   if (!s.fonts?.sans || !s.colors?.bg || !s.motion) bad.push("style.json 이 KfStyle 꼴이 아니다(fonts·colors·motion)");

package/packages/themes/src/look.ts

@@ -3,7 +3,8 @@
 import { hueDist, labOf, parseColor } from "./color.ts";
 import { lchOf } from "./palette.ts";
 import type { TextureKind, Theme } from "./types.ts";
-import { baseParams, fontPairs } from "./vary.ts";
+import { fontPairs, stackFamilies } from "./fonts.ts";
+import { baseParams } from "./vary.ts";
 
 export interface LookWant {
   scheme?: "light" | "dark";
@@ -65,14 +66,36 @@ const LEXICON: [Cue[], LookWant][] = [
   [["따뜻", "따스", "포근", "warm", "노을", "가을", "선셋", "sunset", "햇살"], { warm: true }],
   [["차가운", "시원", "청량", "cool", "겨울", "바다", "얼음", "냉철"], { cool: true }],
   [["선명", "쨍", "강렬", "vivid", "네온", "neon", "팝", "pop", "원색", "화려"], { vivid: true }],
-  [["차분", "은은", "잔잔", "muted", "파스텔", "pastel", "미니멀", "minimal", "절제", "담백"], { muted: true }],
+  [["차분", "은은", "잔잔", "muted", "파스텔", "pastel", "미니멀", "minimal", "절제", "담백"], { muted: true, fontTags: ["calm", "minimal"] }],
   [["종이", "아날로그", "인쇄", "빈티지", "vintage", "paper", "질감", "손맛", "잡지", "zine", "필름", "film"], { textures: ["paper", "grain", "halftone"] }],
-  [["레트로", "retro", "crt", "브라운관", "옛날", "80년대", "90년대", "오락실"], { textures: ["scan", "noise"], fontTags: ["pixel"] }],
+  [["레트로", "retro", "crt", "브라운관", "옛날", "80년대", "90년대", "오락실"], { textures: ["scan", "noise"], fontTags: ["pixel", "retro"] }],
   [["픽셀", "pixel", "도트", "8비트", "8bit"], { fontTags: ["pixel"] }],
-  [["명조", "세리프", "serif", "클래식", "고전", "우아", "에디토리얼", "editorial", "신문", "문학"], { fontTags: ["serif", "editorial"] }],
-  [["귀여운", "귀엽", "cute", "카와이", "kawaii", "둥근", "말랑", "아기자기", "친근"], { fontTags: ["rounded", "friendly"] }],
+  // 글꼴 결 낱말 — 짝 태그(kit/fonts*.json)로 잇는다. 내용 낱말과 겹치는 조각은 뺐다(캘리포니아·일기예보·고급 기능·기계 학습·와이드 화면)
+  [["명조", "세리프", "serif", "클래식", "고전", "에디토리얼", "editorial", "문학"], { fontTags: ["serif", "editorial", "classic"] }],
+  [["우아", "elegant", "럭셔리", "luxury", "격조", "품격"], { fontTags: ["elegant", "classic"] }],
+  [["전통", "한옥", "사극", "traditional", "붓글씨", "서예", "캘리그라피", "캘리그래피", "brush", "수묵"], { fontTags: ["brush", "traditional"] }],
+  [["신문", "뉴스", "news", "newspaper", "기사", "보도", "헤드라인", "속보"], { fontTags: ["newspaper", "editorial"] }],
+  [["독서", "소설", "에세이", "book"], { fontTags: ["book", "serif"] }],
+  [["손글씨", "손편지", "필기", "메모", "낙서", "다이어리", "handwriting", "handwritten"], { fontTags: ["hand", "marker"] }],
+  [["귀여운", "귀엽", "cute", "카와이", "kawaii", "둥근", "말랑", "아기자기", "친근"], { fontTags: ["rounded", "friendly", "playful"] }],
+  [["발랄", "장난", "유쾌", "신나", "playful", "fun"], { fontTags: ["playful", "friendly"] }],
+  [["만화", "코믹", "comic", "웹툰", "말풍선"], { fontTags: ["comic", "playful"] }],
   [["기술", "테크", "tech", "코딩", "개발자", "터미널", "로그", "해커", "hacker", "고정폭"], { fontTags: ["mono", "tech"] }],
-  [["굵은", "볼드", "bold", "임팩트", "포스터"], { fontTags: ["bold", "display"] }],
+  [["대시보드", "dashboard", "지표", "통계", "데이터"], { fontTags: ["data", "mono"] }],
+  [["모던", "modern", "현대적", "세련", "깔끔", "스마트"], { fontTags: ["modern", "clean", "geometric"] }],
+  [["제품", "프로덕트", "product", "saas", "스타트업"], { fontTags: ["product", "clean"] }],
+  [["산업", "공장", "industrial", "공업", "중공업"], { fontTags: ["industrial", "condensed", "square"] }],
+  [["미래", "futuristic", "sf", "사이버", "cyber", "우주"], { fontTags: ["futuristic", "wide"] }],
+  [["안내판", "표지판", "사이니지", "signage", "지하철", "교통", "공항", "길찾기", "wayfinding"], { fontTags: ["signage", "condensed"] }],
+  [["그로테스크", "grotesque", "스위스", "swiss", "헬베티카", "helvetica"], { fontTags: ["grotesque"] }],
+  [["기하", "geometric", "지오메트릭"], { fontTags: ["geometric"] }],
+  [["휴머니스트", "humanist", "인간적", "다정"], { fontTags: ["humanist", "friendly"] }],
+  [["넓적", "익스텐디드", "extended"], { fontTags: ["wide"] }],
+  [["콘덴스드", "condensed", "길쭉"], { fontTags: ["condensed"] }],
+  [["강한", "힘있", "파워", "묵직", "단단", "strong"], { fontTags: ["strong", "bold"] }],
+  [["굵은", "볼드", "bold", "임팩트", "포스터", "poster"], { fontTags: ["bold", "display", "poster"] }],
+  [["네온", "neon", "간판"], { fontTags: ["neon"] }],
+  [["낡은", "거친", "그런지", "grunge", "distressed"], { fontTags: ["distressed", "retro"] }],
   [["입체", "3d", "깊이"], { dims: "3D" }],
   [["평면", "2d", "플랫", "flat"], { dims: "2D" }],
 ];
@@ -163,7 +186,10 @@ function lookOf(t: Theme): Looked {
   const p = t.variant?.params ?? baseParams(t.style);
   const acc = lchOf(t.style.colors.accent);
   const pair = fontPairs().find((x) => x.id === p.fonts);
-  // 세계 글꼴은 짝 목록에 없다 — 제목 글꼴 이름으로 어림한다
+  // 세계 글꼴은 짝 목록에 없다 — 제목 첫 글꼴이 같은 짝의 태그를 빌리고, 그런 짝도 없으면 글꼴 이름으로 어림한다.
+  // Pretendard 는 모든 짝의 바닥이라 그 짝의 태그는 다른 글꼴(고정폭 등) 이야기다 — 빌리지 않는다
+  const first = stackFamilies(t.style.fonts.display)[0];
+  const like = first === "Pretendard Variable" ? undefined : fontPairs().find((x) => stackFamilies(x.display)[0] === first);
   const display = t.style.fonts.display.toLowerCase();
   const baseTags = [/mono|coding|galmuri/.test(display) && "mono", /myeongjo|batang|serif|hahmlet/.test(display) && "serif", /jua|dodum|dongle|bagel/.test(display) && "rounded", /black han|gasoek|do hyeon/.test(display) && "bold"].filter(Boolean) as string[];
   return {
@@ -172,7 +198,7 @@ function lookOf(t: Theme): Looked {
     chroma: acc.c,
     bg: labOf(parseColor(t.style.colors.bg)),
     texture: t.style.look?.texture?.kind ?? "none",
-    fontTags: pair?.tags ?? baseTags,
+    fontTags: pair?.tags ?? like?.tags ?? baseTags,
     dims: t.tags?.dims ?? (t.effects.some((e) => e.kind === "rig") ? "3D" : "2D"),
   };
 }

package/packages/themes/src/types.ts

@@ -57,6 +57,11 @@ export interface ThemeVary {
   keep?: string[];
   /** 색상은 두고 명도·채도만 따라가는 색 열쇠(풀·물 같은 재료 색) */
   fixedHue?: string[];
+  /**
+   * 밝기마다 세계가 정해 둔 색 한 벌 — 브랜드가 라이트·다크를 따로 정한 세계(두 벌이 서로 거울상이 아니라 뒤집어 옮기면 정본 값이 안 나온다).
+   * 그 밝기 판은 이 벌을 원점으로 삼고, 안 적은 축(바탕 빛깔·글 명도·강조 색상)은 그 벌 값 그대로. 열쇠는 style.json colors 와 같다
+   */
+  palettes?: Partial<Record<"light" | "dark", Record<string, string>>>;
   /** 글꼴 짝 id(packages/themes/kit/fonts.json)·`tag:<태그>`·`base`(세계 글꼴) */
   fonts?: string[];
   /** 세 글꼴 스택을 짝의 고정폭 하나로(한 글꼴 HUD) — 그러면 monoAll 짝만 받는다 */