kasaframe 0.1.3 → 0.1.5

package/packages/themes/package.json

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

package/packages/themes/src/color.ts

@@ -0,0 +1,152 @@
+// 변주 색 계산 — OKLCH 로 옮기고, WCAG 대비·색각 이상 모의·OKLab 거리로 거른다. Node·페이지 어디서나 도는 순수 함수만.
+
+export interface Rgba {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+export interface Lch {
+  l: number;
+  c: number;
+  /** 도 0..360 */
+  h: number;
+  a: number;
+}
+
+type Vec = [number, number, number];
+
+export function parseColor(s: string): Rgba {
+  const t = s.trim();
+  const hex = /^#([0-9a-f]{3,8})$/i.exec(t)?.[1];
+  if (hex && [3, 6, 8].includes(hex.length)) {
+    const full = hex.length === 3 ? [...hex].map((c) => c + c).join("") : hex;
+    const n = (i: number) => parseInt(full.slice(i, i + 2), 16);
+    return { r: n(0), g: n(2), b: n(4), a: full.length === 8 ? n(6) / 255 : 1 };
+  }
+  const m = /^rgba?\(([^)]+)\)$/i.exec(t);
+  if (m) {
+    const p = m[1].split(/[\s,/]+/).filter(Boolean).map(Number);
+    if (p.length >= 3 && p.slice(0, 3).every(Number.isFinite)) return { r: p[0], g: p[1], b: p[2], a: Number.isFinite(p[3]) ? p[3] : 1 };
+  }
+  throw new Error(`색 "${s}" 을 못 읽는다 — #hex 나 rgb()·rgba() 만`);
+}
+
+const h2 = (v: number) => Math.round(Math.min(255, Math.max(0, v))).toString(16).padStart(2, "0").toUpperCase();
+
+export function formatColor(c: Rgba): string {
+  if (c.a >= 0.999) return `#${h2(c.r)}${h2(c.g)}${h2(c.b)}`;
+  return `rgba(${Math.round(c.r)}, ${Math.round(c.g)}, ${Math.round(c.b)}, ${+c.a.toFixed(3)})`;
+}
+
+const toLin = (v: number) => {
+  const x = v / 255;
+  return x <= 0.04045 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4;
+};
+const fromLin = (v: number) => 255 * (v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055);
+
+const linOf = (c: Rgba): Vec => [toLin(c.r), toLin(c.g), toLin(c.b)];
+
+function labOfLin([r, g, b]: Vec): Vec {
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+  return [
+    0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  ];
+}
+
+function linOfLab([L, A, B]: Vec): Vec {
+  const l = (L + 0.3963377774 * A + 0.2158037573 * B) ** 3;
+  const m = (L - 0.1055613458 * A - 0.0638541728 * B) ** 3;
+  const s = (L - 0.0894841775 * A - 1.291485548 * B) ** 3;
+  return [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ];
+}
+
+export const labOf = (c: Rgba): Vec => labOfLin(linOf(c));
+
+export function toLch(c: Rgba): Lch {
+  const [l, a, b] = labOf(c);
+  const h = (Math.atan2(b, a) * 180) / Math.PI;
+  return { l, c: Math.hypot(a, b), h: h < 0 ? h + 360 : h, a: c.a };
+}
+
+const inGamut = (v: Vec) => v.every((x) => x >= -1e-4 && x <= 1 + 1e-4);
+
+/** sRGB 밖이면 명도·색상은 두고 채도만 줄여 넣는다 */
+export function fromLch(o: Lch): Rgba {
+  const l = Math.min(1, Math.max(0, o.l));
+  const rad = (o.h * Math.PI) / 180;
+  const lin = (c: number) => linOfLab([l, c * Math.cos(rad), c * Math.sin(rad)]);
+  let c = Math.max(0, o.c);
+  if (!inGamut(lin(c))) {
+    let lo = 0;
+    let hi = c;
+    for (let i = 0; i < 24; i++) {
+      const mid = (lo + hi) / 2;
+      if (inGamut(lin(mid))) lo = mid;
+      else hi = mid;
+    }
+    c = lo;
+  }
+  const [r, g, b] = lin(c).map((x) => fromLin(Math.min(1, Math.max(0, x))));
+  return { r, g, b, a: o.a };
+}
+
+/** 반투명 색을 바탕 위에 얹은 색 */
+export const over = (c: Rgba, bg: Rgba): Rgba => ({ r: c.r * c.a + bg.r * (1 - c.a), g: c.g * c.a + bg.g * (1 - c.a), b: c.b * c.a + bg.b * (1 - c.a), a: 1 });
+
+export function luminance(c: Rgba): number {
+  const [r, g, b] = linOf(c);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/** WCAG 2 대비 — 반투명 글은 바탕에 얹어 잰다 */
+export function contrast(fg: Rgba, bg: Rgba): number {
+  const a = luminance(over(fg, bg));
+  const b = luminance(bg);
+  return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+}
+
+/** OKLab 거리 — 0.02 아래는 거의 같은 색, 0.1 넘으면 뚜렷이 다른 색 */
+export function deltaE(x: Rgba, y: Rgba): number {
+  const [a1, b1, c1] = labOf(x);
+  const [a2, b2, c2] = labOf(y);
+  return Math.hypot(a1 - a2, b1 - b2, c1 - c2);
+}
+
+export type Cvd = "protan" | "deutan" | "tritan";
+export const CVDS: readonly Cvd[] = ["protan", "deutan", "tritan"];
+
+// Machado·Oliveira·Fernandes 2009, 심한 정도 1.0 — 선형 RGB 에 곱한다
+const MACHADO: Record<Cvd, number[]> = {
+  protan: [0.152286, 1.052583, -0.204868, 0.114503, 0.786281, 0.099216, -0.003882, -0.048116, 1.051998],
+  deutan: [0.367322, 0.860646, -0.227968, 0.280085, 0.672501, 0.047413, -0.01182, 0.04294, 0.968881],
+  tritan: [1.255528, -0.076749, -0.178779, -0.078411, 0.930809, 0.147602, 0.004733, 0.691367, 0.3039],
+};
+
+export function simulate(c: Rgba, kind: Cvd): Rgba {
+  const m = MACHADO[kind];
+  const [r, g, b] = linOf(c);
+  const mix = (i: number) => fromLin(Math.min(1, Math.max(0, m[i] * r + m[i + 1] * g + m[i + 2] * b)));
+  return { r: mix(0), g: mix(3), b: mix(6), a: c.a };
+}
+
+/** 정상 시각과 세 색각 이상 모의 중 가장 작은 OKLab 거리 — 바탕에 얹은 색으로 */
+export function worstDelta(x: Rgba, y: Rgba, bg: Rgba): number {
+  const a = over(x, bg);
+  const b = over(y, bg);
+  return Math.min(deltaE(a, b), ...CVDS.map((k) => deltaE(simulate(a, k), simulate(b, k))));
+}
+
+export const hueDist = (a: number, b: number): number => {
+  const d = Math.abs(a - b) % 360;
+  return d > 180 ? 360 - d : d;
+};

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

@@ -1,14 +1,16 @@
 /// <reference types="vite/client" />
 // 페이지(Vite) 쪽. 테마 폴더를 늘려도 이 파일은 그대로 — themes/*/effects.ts 를 모아 id 로 꺼낸다.
+import { worldOf } from "./name.ts";
+
 const mods = import.meta.glob("../../../themes/*/effects.ts", { eager: true }) as Record<string, Record<string, unknown>>;
 
 const byId = new Map(Object.entries(mods).map(([path, mod]) => [path.split("/").at(-2)!, mod]));
 
 export const themeIds = (): string[] => [...byId.keys()].sort();
 
-/** 장면에서: `const { plateStamp, misregister } = fx("riso-zine")` */
+/** 장면에서: `const { plateStamp, misregister } = fx("riso-zine")` — 변주 이름(`riso-zine/night-teal`)이면 그 세계 효과 */
 export function fx<T = Record<string, (...args: any[]) => any>>(id: string): T {
-  const mod = byId.get(id);
+  const mod = byId.get(worldOf(id));
   if (!mod) throw new Error(`테마 효과 "${id}" 가 없다. 있는 테마: ${themeIds().join(" ") || "(없음)"}`);
   return mod as T;
 }