kasaframe 0.1.3 → 0.1.5

package/packages/themes/src/index.ts

@@ -1,11 +1,16 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { KfStyle } from "@kasaframe/core";
-import { THEME_STATUSES, type Theme, type ThemeCard, type ThemeManifest, type ThemeStatus } from "./types.ts";
+import { splitThemeId } from "./name.ts";
+import { THEME_STATUSES, type Theme, type ThemeCard, type ThemeManifest, type ThemeStatus, type VariantManifest } from "./types.ts";
+import { fontPairs } from "./fonts.ts";
+import { allowedFonts, mergeVariant } from "./vary.ts";
 
 export type * from "./types.ts";
 export { THEME_STATUSES } from "./types.ts";
+export { BASE_VARIANT, splitThemeId, worldOf } from "./name.ts";
 
 export const themesDir = fileURLToPath(new URL("../../../themes/", import.meta.url));
 
@@ -14,6 +19,8 @@ export interface ThemeFilter {
   status?: ThemeStatus | ThemeStatus[];
   purpose?: string;
   aspect?: string;
+  /** 세계마다 변주(`<세계>/<변주>`)도 함께 — 세계 자신이 그 세계의 기본 판으로 앞에 선다 */
+  variants?: boolean;
 }
 
 const readJson = <T>(path: string): T => JSON.parse(readFileSync(path, "utf8")) as T;
@@ -37,6 +44,20 @@ export function checkTheme(dir: string): string[] {
   for (const e of m.effects ?? []) if (!["value", "layer", "rig"].includes(e.kind)) bad.push(`효과 ${e.name} kind 는 value|layer|rig`);
   const s = readJson<Partial<KfStyle>>(join(dir, "style.json"));
   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.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)");
   if (m.status !== "draft") {
     if (!existsSync(join(dir, m.still ?? "still.png"))) bad.push(`${m.status} 인데 대표 장면 ${m.still ?? "still.png"} 가 없다`);
@@ -45,13 +66,54 @@ export function checkTheme(dir: string): string[] {
   return bad;
 }
 
+export const variantsDir = (world: string): string => join(themesDir, world, "variants");
+
+/** 세계의 변주 — 굽기 검사를 넘은 것만(check.ok) */
+export function listVariants(world: string): VariantManifest[] {
+  const dir = variantsDir(world);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".json"))
+    .sort()
+    .map((f) => readJson<VariantManifest>(join(dir, f)))
+    .filter((v) => v.check?.ok && v.world === world);
+}
+
+/** 「<세계>」·「<세계>/<변주>」(「<세계>/base」는 세계 자신) */
 export function loadTheme(id: string): Theme {
+  const { world, variant } = splitThemeId(id);
+  if (!variant) return loadWorld(world);
+  const file = join(variantsDir(world), `${variant}.json`);
+  if (!existsSync(file)) throw new Error(`테마 ${world} 에 변주 ${variant} 가 없다 — kf theme list --variants ${world}`);
+  const v = readJson<VariantManifest>(file);
+  if (!v.check?.ok) throw new Error(`변주 ${id} 는 굽기 검사를 못 넘었다 — kf theme vary ${world} 로 다시`);
+  return variantTheme(loadWorld(world), v);
+}
+
+function variantTheme(w: Theme, v: VariantManifest): Theme {
+  const cell = cellPath(`${w.id}/${v.id}`);
+  return {
+    ...w,
+    id: `${w.id}/${v.id}`,
+    name: `${w.name} · ${v.name}`,
+    variant: v,
+    // 세계가 approved 면 검사를 넘은 변주는 따로 승인 없이 approved, review 면 review(SPEC 9 변주)
+    approvedAt: w.status === "approved" ? w.approvedAt : null,
+    tags: v.tags,
+    style: mergeVariant(w.style, v),
+    files: { ...w.files, still: existsSync(cell) ? cell : w.files.still },
+  };
+}
+
+function loadWorld(id: string): Theme {
   const dir = join(themesDir, id);
   const bad = checkTheme(dir);
   if (bad.length) throw new Error(`테마 ${id}: ${bad.join(" · ")}`);
   const m = readJson<ThemeManifest>(join(dir, "theme.json"));
   return {
     ...m,
+    world: id,
+    variant: null,
     dir,
     style: readJson<KfStyle>(join(dir, "style.json")),
     guide: readFileSync(join(dir, "THEME.md"), "utf8"),
@@ -76,22 +138,32 @@ export function listThemes(filter: ThemeFilter = {}): Theme[] {
     if (filter.purpose && !t.purposes.includes(filter.purpose)) continue;
     if (filter.aspect && !t.aspect.includes(filter.aspect)) continue;
     out.push(t);
+    if (filter.variants) for (const v of listVariants(id)) out.push(variantTheme(t, v));
   }
   return out;
 }
 
+/** 견본 칸 그림 캐시 — 변주 하나 = 쇼츠 첫 장면 끝 프레임 한 장(kf theme vary·sheet 가 찍는다). 세계 자신은 <세계>/base.png */
+export const cellsDir = join(process.env.KF_CACHE_DIR ?? join(homedir(), ".cache", "kasaframe"), "theme-cells");
+export const cellPath = (id: string): string => {
+  const { world, variant } = splitThemeId(id);
+  return join(cellsDir, world, `${variant ?? "base"}.png`);
+};
+
 /** 3D 무대(rig 효과)를 쓰는 테마인가 — 묻기 보기·견본 시트의 2D/3D 표시 */
 export const themeDims = (t: Pick<ThemeManifest, "effects">): "2D" | "3D" => (t.effects.some((e) => e.kind === "rig") ? "3D" : "2D");
 
 /** kf theme sheet 가 찍는 견본 — 같은 문장 한 장면을 테마마다 <id>.png, 한 장에 모은 격자 sheet.png */
 export const sheetDir = join(themesDir, "_sheet");
 
-/** 묻기 보기에 붙일 견본 — 견본 시트의 그 테마 칸, 아직 안 찍었으면 테마 대표 장면 */
-export const themeSample = (t: Theme): string | null => (existsSync(join(sheetDir, `${t.id}.png`)) ? join(sheetDir, `${t.id}.png`) : t.files.still);
+/** 묻기 보기에 붙일 견본 — 칸 캐시, 견본 시트의 그 테마 칸, 아직 안 찍었으면 테마 대표 장면 */
+export const themeSample = (t: Theme): string | null =>
+  existsSync(cellPath(t.id)) ? cellPath(t.id) : !t.variant && existsSync(join(sheetDir, `${t.id}.png`)) ? join(sheetDir, `${t.id}.png`) : t.files.still;
 
 export function themeCards(filter: ThemeFilter = {}): ThemeCard[] {
   return listThemes(filter).map((t) => ({
     id: t.id,
+    world: t.world,
     name: t.name,
     metaphor: t.metaphor,
     status: t.status,

package/packages/themes/src/look.ts

@@ -0,0 +1,249 @@
+// 고르기 — 500 판 가까이 되는 세계·변주 가운데 요청·분위기 낱말·레퍼런스 그림에 맞는 판을 점수로 줄 세운다(SPEC 9 변주).
+// 내용 맞음(세계 비유·용도 낱말)과 생김새 맞음(밝기·색상·채도·질감·글꼴)을 따로 재 더한다.
+import { hueDist, labOf, parseColor } from "./color.ts";
+import { lchOf } from "./palette.ts";
+import type { TextureKind, Theme } from "./types.ts";
+import { fontPairs, stackFamilies } from "./fonts.ts";
+import { baseParams } from "./vary.ts";
+
+export interface LookWant {
+  scheme?: "light" | "dark";
+  warm?: boolean;
+  cool?: boolean;
+  vivid?: boolean;
+  muted?: boolean;
+  textures?: TextureKind[];
+  hue?: number;
+  fontTags?: string[];
+  dims?: "2D" | "3D";
+}
+
+/** 레퍼런스 그림에서 뽑은 생김새 — 바탕(가장 넓은 색)·강조(가장 짙은 색) */
+export interface RefLook {
+  source: string;
+  scheme: "light" | "dark";
+  bg: [number, number, number];
+  accent: { h: number; c: number } | null;
+}
+
+// 한국어 조사 — 「압축이」「파란색으로」를 「압축」「파란색」으로 견주게 뗀다. 떼고 두 글자가 안 남으면(「속도」「경로」「결과」) 낱말 그대로. 긴 것부터
+const JOSA = ["으로부터", "에서부터", "으로서", "으로써", "에게서", "에서", "에게", "한테", "까지", "부터", "처럼", "보다", "으로", "이나", "이랑", "하고", "이", "가", "은", "는", "을", "를", "의", "에", "로", "와", "과", "도", "만", "랑"];
+function stem(w: string): string {
+  if (!/\p{Script=Hangul}$/u.test(w)) return w;
+  const j = JOSA.find((x) => w.endsWith(x) && [...w].length - [...x].length >= 2);
+  return j ? w.slice(0, -j.length) : w;
+}
+
+/** 글의 낱말 — 소문자로 글자·숫자 덩어리마다 조사를 뗀다. 테마 고르기의 요청 낱말과 색 이름이 같이 쓴다 */
+export const textWords = (s: string): string[] => s.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean).map(stem);
+
+// 색 이름은 조각이 아니라 낱말로 — 조각이면 「그린다」가 초록, 「스틸」이 청록, 「블랙박스」가 어둠이 된다.
+// 조사를 뗀 낱말이 색 이름이거나 색 이름 + 색 꼬리(「파란색」「금빛」「그린 톤」은 톤이 따로 낱말이라 그대로)일 때만
+const TAILS = ["", "색", "빛", "톤", "색깔", "빛깔", "계열"];
+const isWord = (words: string[], cue: string): string | undefined => words.find((w) => w.startsWith(cue) && TAILS.includes(w.slice(cue.length)));
+
+// 낱말 하나 — 한글은 조각으로 찾고(「따뜻한」「따스하게」), 라틴 낱말은 낱말 경계로만(「highlight」「nightly」「reduce」가 light·night·red 로 걸리지 않게).
+// 정규식은 맥락이 있을 때만 — 「낮」은 낮 장면일 때지 「낮은 지연」「낮추다」가 아니다. { word } 는 색 이름처럼 낱말로만
+type Cue = string | RegExp | { word: string };
+const LATIN = /^[a-z0-9]+$/;
+function findCue(t: string, words: string[], cues: Cue[]): string | null {
+  for (const c of cues) {
+    if (typeof c === "object" && "word" in c) {
+      const w = isWord(words, c.word);
+      if (w) return w;
+      continue;
+    }
+    const m = typeof c !== "string" ? c.exec(t) : LATIN.test(c) ? new RegExp(`\\b${c}\\b`).exec(t) : t.includes(c) ? [c] : null;
+    if (m) return m[0];
+  }
+  return null;
+}
+
+// 분위기 낱말 → 바라는 생김새. 한 낱말이 여럿을 바랄 수 있다
+const LEXICON: [Cue[], LookWant][] = [
+  [["어두운", "어둡", "다크", "dark", "밤", "night", "야간", "심야", { word: "블랙" }, "검은", "검정", "느와르", "noir"], { scheme: "dark" }],
+  [["밝은", "밝게", "화사", "light", "화이트", "흰", "하얀", "환한", /낮(?![은게아추춘출음고다])/], { scheme: "light" }],
+  [["따뜻", "따스", "포근", "warm", "노을", "가을", "선셋", "sunset", "햇살"], { warm: true }],
+  [["차가운", "시원", "청량", "cool", "겨울", "바다", "얼음", "냉철"], { cool: true }],
+  [["선명", "쨍", "강렬", "vivid", "네온", "neon", "팝", "pop", "원색", "화려"], { vivid: 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"] }],
+  [["픽셀", "pixel", "도트", "8비트", "8bit"], { fontTags: ["pixel"] }],
+  // 글꼴 결 낱말 — 짝 태그(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"] }],
+  [["대시보드", "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" }],
+];
+
+// 색 이름 → OKLCH 색상. 낱말로만 견준다(위 isWord). 뜻이 둘인 자주(자주 쓰는)·시안(디자인 시안)은 색 꼬리가 붙은 꼴로만
+const HUES: [string[], number][] = [
+  [["빨강", "빨간", "레드", "red", "붉은", "적색"], 25],
+  [["산호", "코랄", "coral"], 38],
+  [["주황", "오렌지", "orange"], 55],
+  [["호박", "앰버", "amber"], 75],
+  [["노랑", "노란", "옐로", "yellow", "금빛", "골드", "gold"], 95],
+  [["라임", "lime", "연두"], 125],
+  [["초록", "녹색", "그린", "green", "숲"], 145],
+  [["민트", "mint", "옥색", "jade"], 170],
+  [["청록", "틸", "teal"], 195],
+  [["하늘", "스카이", "sky", "시안색", "cyan"], 230],
+  [["파랑", "파란", "블루", "blue", "코발트"], 260],
+  [["남색", "네이비", "navy", "인디고", "indigo"], 280],
+  [["보라", "보랏빛", "퍼플", "purple", "바이올렛", "violet", "라벤더"], 305],
+  [["자주색", "자줏빛", "마젠타", "magenta", "자두", "plum"], 335],
+  [["분홍", "핑크", "pink", "장밋빛", "로즈", "rose"], 355],
+];
+
+export function wantsOf(text: string): { want: LookWant; hits: string[] } {
+  const t = text.toLowerCase();
+  const tw = textWords(text);
+  const want: LookWant = {};
+  const hits: string[] = [];
+  for (const [words, w] of LEXICON) {
+    const hit = findCue(t, tw, words);
+    if (!hit) continue;
+    hits.push(hit);
+    for (const [k, v] of Object.entries(w)) {
+      const cur = (want as Record<string, unknown>)[k];
+      (want as Record<string, unknown>)[k] = Array.isArray(v) && Array.isArray(cur) ? [...new Set([...cur, ...v])] : v;
+    }
+  }
+  for (const [words, h] of HUES) {
+    const hit = words.map((c) => isWord(tw, c)).find(Boolean);
+    if (hit && want.hue === undefined) {
+      want.hue = h;
+      hits.push(hit);
+    }
+  }
+  return { want, hits };
+}
+
+/** 그림 화소(RGB 줄줄이)에서 바탕·강조 — 다섯 무리로 나눠 가장 넓은 무리가 바탕, 바탕 아닌 무리 가운데 짙고 넓은 것이 강조 */
+export function refFromPixels(rgb: Uint8Array, source: string): RefLook {
+  const px: [number, number, number][] = [];
+  for (let i = 0; i + 2 < rgb.length; i += 3) px.push(labOf({ r: rgb[i], g: rgb[i + 1], b: rgb[i + 2], a: 1 }));
+  if (!px.length) throw new Error(`레퍼런스 ${source} 에서 화소를 못 읽었다`);
+  const k = 5;
+  const sorted = [...px].sort((a, b) => a[0] - b[0]);
+  let centers = Array.from({ length: k }, (_, i) => sorted[Math.min(sorted.length - 1, Math.floor(((i + 0.5) / k) * sorted.length))]);
+  let owner = new Array(px.length).fill(0);
+  for (let it = 0; it < 12; it++) {
+    owner = px.map((p) => centers.reduce((best, c, j) => (Math.hypot(p[0] - c[0], p[1] - c[1], p[2] - c[2]) < Math.hypot(p[0] - centers[best][0], p[1] - centers[best][1], p[2] - centers[best][2]) ? j : best), 0));
+    centers = centers.map((c, j) => {
+      const mine = px.filter((_, i) => owner[i] === j);
+      return mine.length ? ([0, 1, 2].map((d) => mine.reduce((s, p) => s + p[d], 0) / mine.length) as [number, number, number]) : c;
+    });
+  }
+  const share = centers.map((_, j) => owner.filter((o) => o === j).length / px.length);
+  const bgI = share.indexOf(Math.max(...share));
+  const chroma = (c: [number, number, number]) => Math.hypot(c[1], c[2]);
+  const acc = centers
+    .map((c, j) => ({ c, j, score: chroma(c) * Math.sqrt(share[j]) }))
+    .filter((x) => x.j !== bgI && share[x.j] > 0.01 && chroma(x.c) > 0.04)
+    .sort((a, b) => b.score - a.score)[0];
+  const meanL = px.reduce((s, p) => s + p[0], 0) / px.length;
+  const bg = centers[bgI];
+  const h = (c: [number, number, number]) => ((Math.atan2(c[2], c[1]) * 180) / Math.PI + 360) % 360;
+  return { source, scheme: (bg[0] + meanL) / 2 > 0.6 ? "light" : "dark", bg, accent: acc ? { h: h(acc.c), c: chroma(acc.c) } : null };
+}
+
+interface Looked {
+  scheme: "light" | "dark";
+  hue: number;
+  chroma: number;
+  bg: [number, number, number];
+  texture: TextureKind;
+  fontTags: string[];
+  dims: "2D" | "3D";
+}
+
+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 {
+    scheme: t.style.scheme,
+    hue: acc.h,
+    chroma: acc.c,
+    bg: labOf(parseColor(t.style.colors.bg)),
+    texture: t.style.look?.texture?.kind ?? "none",
+    fontTags: pair?.tags ?? like?.tags ?? baseTags,
+    dims: t.tags?.dims ?? (t.effects.some((e) => e.kind === "rig") ? "3D" : "2D"),
+  };
+}
+
+const inWarm = (h: number) => h >= 20 && h <= 100;
+const inCool = (h: number) => h >= 180 && h <= 290;
+
+/** 생김새 점수와 까닭 */
+export function lookScore(t: Theme, want: LookWant, ref?: RefLook | null): { score: number; why: string[] } {
+  const l = lookOf(t);
+  let s = 0;
+  const why: string[] = [];
+  const add = (v: number, w: string) => {
+    s += v;
+    if (v > 0) why.push(w);
+  };
+  if (want.scheme) add(want.scheme === l.scheme ? 3 : -3, want.scheme === "dark" ? "어두운 바탕" : "밝은 바탕");
+  if (want.warm) add(inWarm(l.hue) ? 1.5 : -0.5, "따뜻한 강조색");
+  if (want.cool) add(inCool(l.hue) ? 1.5 : -0.5, "차가운 강조색");
+  if (want.vivid) add(l.chroma >= 0.15 ? 1.2 : -0.4, "선명한 색");
+  if (want.muted) add(l.chroma <= 0.11 ? 1.2 : -0.4, "차분한 색");
+  if (want.textures) add(want.textures.includes(l.texture) ? 2 : -0.3, "질감");
+  if (want.hue !== undefined) {
+    const d = hueDist(want.hue, l.hue);
+    add(d <= 22 ? 3 : d <= 45 ? 1.5 : -0.6, "짚은 색");
+  }
+  if (want.fontTags) add(want.fontTags.some((x) => l.fontTags.includes(x)) ? 1.5 : -0.2, "글꼴 결");
+  if (want.dims) add(want.dims === l.dims ? 2 : -2, want.dims === "3D" ? "입체" : "평면");
+  if (ref) {
+    const dBg = Math.hypot(ref.bg[0] - l.bg[0], ref.bg[1] - l.bg[1], ref.bg[2] - l.bg[2]);
+    add(ref.scheme === l.scheme ? 2 : -2, "레퍼런스와 같은 밝기");
+    add(Math.max(-2, 2 - 8 * dBg), "레퍼런스 바탕색");
+    if (ref.accent && ref.accent.c > 0.05) {
+      const d = hueDist(ref.accent.h, l.hue);
+      add(d <= 20 ? 3 : d <= 40 ? 1.5 : -1, "레퍼런스 강조색");
+    }
+  }
+  return { score: s, why };
+}
+
+export const hasLook = (w: LookWant) => Object.keys(w).length > 0;
+
+/** 두 판의 생김새 거리 — 후보 넷이 서로 겹치지 않게 */
+export function lookDistance(a: Theme, b: Theme): number {
+  const x = lookOf(a);
+  const y = lookOf(b);
+  return Math.hypot(x.bg[0] - y.bg[0], x.bg[1] - y.bg[1], x.bg[2] - y.bg[2]) * 2 + (hueDist(x.hue, y.hue) / 180) * 0.3 + (x.texture !== y.texture ? 0.05 : 0);
+}

package/packages/themes/src/name.ts

@@ -0,0 +1,9 @@
+// 테마 이름 「<세계>」·「<세계>/<변주>」 — 페이지·Node 어디서나 쓰는 순수 함수. 세계 코드(effects·slots)·연출 묶음·장면 문법 궁합은 세계 이름으로 찾는다
+export const BASE_VARIANT = "base";
+
+export function splitThemeId(id: string): { world: string; variant: string | null } {
+  const [world, variant] = id.split("/");
+  return { world, variant: variant && variant !== BASE_VARIANT ? variant : null };
+}
+
+export const worldOf = <T extends string | null | undefined>(id: T): T => (id ? (id.split("/")[0] as T) : id);

package/packages/themes/src/palette.ts

@@ -0,0 +1,194 @@
+// 변주 색 조합 — 세계 색을 버리고 새로 짓지 않고 「옮긴다」. 색이 있는 잉크는 함께 같은 각도만큼 돌아 세계의 짝(리소의 파랑·분홍 두 잉크)이 남고,
+// 무채색은 바탕→잉크 사이 자리(t)를 지킨 채 새 바탕·잉크 사이로 옮겨 밝음·어두움을 뒤집는다. 그런 뒤 대비·의미색·색각 이상을 계산으로 고치고 거른다.
+import { contrast, deltaE, formatColor, fromLch, hueDist, type Lch, over, parseColor, type Rgba, toLch, worstDelta } from "./color.ts";
+
+export interface PaletteParams {
+  scheme: "light" | "dark";
+  /** 바탕 명도(OKLCH L) */
+  bgL: number;
+  /** 무채색에 얹는 옅은 빛깔 */
+  tint: { h: number; c: number };
+  /** 글 잉크 명도 */
+  inkL: number;
+  /** 강조색 색상(도) — 색 있는 잉크가 모두 같은 각도만큼 돈다 */
+  hue: number;
+  /** 색 있는 잉크 채도 배수 */
+  chroma: number;
+}
+
+export interface PaletteRules {
+  /** 그대로 두는 열쇠(세계가 늘 같은 색으로 쓰는 것) */
+  keep?: string[];
+  /** 색상은 두고 명도·채도만 따라가는 열쇠(풀·물처럼 재료 색) */
+  fixedHue?: string[];
+}
+
+export interface PaletteResult {
+  colors: Record<string, string>;
+  /** 떨어진 까닭 — 비면 통과 */
+  bad: string[];
+  /** 잰 값 — 변주 json check 에 남는다 */
+  measured: Record<string, number>;
+}
+
+const SEMANTIC = ["success", "danger", "warning"] as const;
+export const NEUTRAL_C = 0.04;
+
+// 역할마다 [목표, 바닥] — 목표는 WCAG, 세계가 일부러 목표보다 낮게 둔 역할(파스텔 강조 판)은 세계 값까지만 요구하고, 바닥 아래로는 안 간다
+const TEXT_RULES: Record<string, [number, number]> = {
+  ink: [7, 4.5],
+  inkSoft: [4.5, 4.5],
+  dim: [4.5, 3],
+  accentText: [4.5, 4.5],
+  accent: [3, 1.8],
+};
+const ON_ACCENT: [number, number] = [4.5, 2.5];
+const SEMANTIC_ON_BG: [number, number] = [3, 1.8];
+
+const need = ([target, floor]: [number, number], base: number) => Math.max(floor, Math.min(target, base - 0.05));
+
+/** 바탕에서 멀어지는 쪽으로 명도만 밀어 대비 r 을 맞춘다. 못 맞추면 null */
+function pushL(c: Lch, bg: Rgba, r: number): Lch | null {
+  const rgb = fromLch(c);
+  if (contrast(rgb, bg) >= r) return c;
+  const dir = toLch(bg).l > 0.5 ? -1 : 1;
+  let lo = c.l;
+  let hi = dir < 0 ? 0 : 1;
+  if (contrast(fromLch({ ...c, l: hi }), bg) < r) return null;
+  for (let i = 0; i < 28; i++) {
+    const mid = (lo + hi) / 2;
+    if (contrast(fromLch({ ...c, l: mid }), bg) >= r) hi = mid;
+    else lo = mid;
+  }
+  return { ...c, l: hi };
+}
+
+const ab = (c: { c: number; h: number }): [number, number] => [c.c * Math.cos((c.h * Math.PI) / 180), c.c * Math.sin((c.h * Math.PI) / 180)];
+const fromAb = (l: number, a: number, b: number, alpha: number): Lch => {
+  const h = (Math.atan2(b, a) * 180) / Math.PI;
+  return { l, c: Math.hypot(a, b), h: h < 0 ? h + 360 : h, a: alpha };
+};
+
+const same = (a: string, b: string) => a === b || deltaE(parseColor(a), parseColor(b)) < 0.004;
+
+export function transformPalette(base: Record<string, string>, p: PaletteParams, rules: PaletteRules = {}): PaletteResult {
+  const B = Object.fromEntries(Object.entries(base).map(([k, v]) => [k, parseColor(v)]));
+  const L = Object.fromEntries(Object.entries(B).map(([k, v]) => [k, toLch(v)]));
+  const bg0 = L.bg.l;
+  const ink0 = L.ink.l;
+  const span0 = ink0 - bg0 || 1e-6;
+  const dh = p.hue - L.accent.h;
+  const keep = new Set(rules.keep ?? []);
+  const fixed = new Set(rules.fixedHue ?? []);
+  // 같은 색을 두 역할에 쓴 세계(한 잉크 HUD·두 잉크 리소)는 그 묶음을 지킨다 — 앞 차례 역할을 옮기고 같은 색은 그것을 베낀다
+  const order = [...new Set(["bg", "ink", "accent", "surface", "raised", "line", "inkSoft", "dim", "accentText", "accentSoft", "onAccent", ...Object.keys(base)])].filter((k) => base[k]);
+  const alias: Record<string, string> = {};
+  order.forEach((k, i) => {
+    const twin = order.slice(0, i).find((c) => !alias[c] && same(base[c], base[k]));
+    if (twin) alias[k] = twin;
+  });
+  const own = (k: string) => alias[k] ?? k;
+
+  const moveL = (l: number) => p.bgL + ((l - bg0) / span0) * (p.inkL - p.bgL);
+  const out: Record<string, Lch> = {};
+  for (const [k, c] of Object.entries(L)) {
+    if (keep.has(k) || alias[k]) continue;
+    if (k === "bg") out[k] = { l: p.bgL, c: p.tint.c, h: p.tint.h, a: c.a };
+    else if ((SEMANTIC as readonly string[]).includes(k)) out[k] = { ...c };
+    else if (c.c < NEUTRAL_C && L.bg.c >= NEUTRAL_C) {
+      // 바탕이 색 잉크인 세계(청사진 파랑·영수증 주황)의 흰 선·종이는 바탕 빛깔과 무관한 무채색이다 — 바탕을 빼면 옛 바탕의 보색이 묻는다. 바탕과 같은 각도로만 돈다
+      out[k] = { l: moveL(c.l), c: c.c, h: (c.h + dh + 360) % 360, a: c.a };
+    } else if (c.c < NEUTRAL_C) {
+      // 무채색 — 세계가 바탕과 다르게 둔 옅은 빛깔(바탕보다 차가운 판)은 그 차이를 지키고, 새 바탕 빛깔은 잉크 쪽으로 갈수록 절반만
+      const t = Math.min(1, Math.max(0, (c.l - bg0) / span0));
+      const [a, b] = ab(c);
+      const [a0, b0] = ab(L.bg);
+      const [ta, tb] = ab(p.tint);
+      const w = 1 - 0.5 * t;
+      out[k] = fromAb(moveL(c.l), a - a0 + ta * w, b - b0 + tb * w, c.a);
+    } else out[k] = { l: moveL(c.l), c: c.c * p.chroma, h: fixed.has(k) ? c.h : (c.h + dh + 360) % 360, a: c.a };
+  }
+  const bgRgb = fromLch(out.bg);
+  const bad: string[] = [];
+  const measured: Record<string, number> = {};
+  const rgb = (k: string) => (out[own(k)] ? fromLch(out[own(k)]) : B[k]);
+  const baseBg = B.bg;
+
+  for (const [k, rule] of Object.entries(TEXT_RULES)) {
+    if (!out[k] || alias[k]) continue;
+    const r = need(rule, contrast(B[k], baseBg));
+    const fixedL = pushL(out[k], bgRgb, r);
+    if (!fixedL) bad.push(`${k} 대비 ${r.toFixed(1)}:1 을 못 맞춤`);
+    else out[k] = fixedL;
+    measured[k] = +contrast(rgb(k), bgRgb).toFixed(2);
+  }
+  // 강조 판 위 글 — 세계의 onAccent 를 옮긴 것이 모자라면 바탕색·잉크 중 대비가 큰 쪽, 그래도 모자라면 강조색 명도를 민다
+  if (base.onAccent && !keep.has("onAccent")) {
+    const r = need(ON_ACCENT, contrast(B.onAccent, B.accent));
+    const acc = rgb("accent");
+    if (contrast(rgb("onAccent"), acc) < r) {
+      const pick = [out.bg, out.ink, { l: 0.99, c: 0, h: 0, a: 1 }, { l: 0.12, c: 0, h: 0, a: 1 }].sort((a, b) => contrast(fromLch(b), acc) - contrast(fromLch(a), acc))[0];
+      delete alias.onAccent;
+      out.onAccent = pick;
+      if (contrast(fromLch(pick), acc) < r) bad.push(`onAccent 대비 ${r.toFixed(1)}:1 을 못 맞춤`);
+    }
+    measured.onAccent = +contrast(rgb("onAccent"), acc).toFixed(2);
+  }
+  for (const k of SEMANTIC) {
+    if (!out[k] || alias[k]) continue;
+    const r = need(SEMANTIC_ON_BG, contrast(B[k], baseBg));
+    const fixedL = pushL(out[k], bgRgb, r);
+    if (!fixedL) bad.push(`${k} 대비 ${r.toFixed(1)}:1 을 못 맞춤`);
+    else out[k] = fixedL;
+  }
+  // 의미색 — 세계가 따로 둔 짝만 본다(한 잉크·두 잉크 세계가 일부러 같게 둔 짝은 빼고). 정상 시각 0.08, 색각 이상 모의 중 가장 나쁜 것은 세계 값·0.04 중 작은 쪽.
+  // 걸리면 뒤 색의 명도만 조금씩 벌려 본다(색상은 의미라 안 돌린다) — 바탕 대비는 지킨 채
+  const pairs: [string, string][] = [["success", "danger"], ["success", "warning"], ["danger", "warning"], ["accent", "danger"]];
+  const pairWhy = (a: string, b: string): string | null => {
+    const plain = deltaE(over(rgb(a), bgRgb), over(rgb(b), bgRgb));
+    const worst = worstDelta(rgb(a), rgb(b), bgRgb);
+    measured[`${a}~${b}`] = +worst.toFixed(3);
+    if (plain < 0.08) return `${a}·${b} 가 너무 비슷하다(ΔE ${plain.toFixed(3)})`;
+    if (worst < Math.min(0.04, worstDelta(B[a], B[b], baseBg) - 0.005)) return `${a}·${b} 가 색각 이상 모의에서 겹친다(ΔE ${worst.toFixed(3)})`;
+    return null;
+  };
+  for (const [a, b] of pairs) {
+    if (!base[a] || !base[b] || worstDelta(B[a], B[b], baseBg) < 0.02) continue;
+    let why = pairWhy(a, b);
+    const k = own(b);
+    if (why && out[k] && !keep.has(k)) {
+      const was = out[k];
+      const r = need(SEMANTIC_ON_BG, contrast(B[b], baseBg));
+      for (const d of [0.04, -0.04, 0.08, -0.08, 0.12, -0.12]) {
+        out[k] = { ...was, l: Math.min(0.98, Math.max(0.05, was.l + d)) };
+        if (contrast(fromLch(out[k]), bgRgb) >= r && !pairs.some(([x, y]) => (x === b || y === b) && base[x] && base[y] && worstDelta(B[x], B[y], baseBg) >= 0.02 && pairWhy(x, y))) break;
+        out[k] = was;
+      }
+      why = pairWhy(a, b);
+    }
+    if (why) bad.push(why);
+  }
+  // 강조는 글 잉크와 갈려야 강조다 — 한 잉크 세계(강조 = 잉크)는 빼고
+  if (worstDelta(B.accent, B.ink, baseBg) >= 0.02) {
+    const w = worstDelta(rgb("accent"), rgb("ink"), bgRgb);
+    measured["accent~ink"] = +w.toFixed(3);
+    if (w < Math.min(0.1, worstDelta(B.accent, B.ink, baseBg) - 0.005)) bad.push(`강조색이 글 잉크와 색각 이상 모의에서 겹친다(ΔE ${w.toFixed(3)})`);
+  }
+
+  const colors: Record<string, string> = {};
+  for (const k of Object.keys(base)) {
+    if (keep.has(k)) colors[k] = base[k];
+    else if (alias[k]) colors[k] = formatColor({ ...rgb(k), a: B[k].a });
+    else colors[k] = formatColor(fromLch(out[k]));
+  }
+  return { colors, bad, measured };
+}
+
+/** 색 조합 사이 거리 — 고르기가 서로 충분히 다른 판을 뽑을 때 */
+export function paletteDistance(a: Record<string, string>, b: Record<string, string>): number {
+  const d = (k: string) => (a[k] && b[k] ? deltaE(parseColor(a[k]), parseColor(b[k])) : 0);
+  return 1.4 * d("bg") + 1.2 * d("accent") + 0.6 * d("ink") + 0.4 * d("surface");
+}
+
+export const lchOf = (s: string): Lch => toLch(parseColor(s));
+export { hueDist };

package/packages/themes/src/slotkit.ts

@@ -48,8 +48,16 @@ export function partial(points: readonly Pt[], p: number): [number, number][] {
   return out;
 }
 
-/** 점들을 감싸는 캔버스(여백 pad) — 그리기는 층 좌표 그대로 */
+/** 변주의 선 굵기 배수(--kf-stroke) — 세계가 lineWidth 에 넣은 값에 곱해진다 */
+export const strokeK = (el: HTMLElement): number => {
+  const k = parseFloat(getComputedStyle(el.ownerDocument.documentElement).getPropertyValue("--kf-stroke"));
+  return Number.isFinite(k) && k > 0 ? k : 1;
+};
+
+/** 점들을 감싸는 캔버스(여백 pad) — 그리기는 층 좌표 그대로. 선 굵기는 변주 배수를 곱해 긋는다 */
 export function traceCanvas(el: HTMLElement, points: readonly Pt[], pad = 40): { g: CanvasRenderingContext2D; clear(): void } {
+  const k = strokeK(el);
+  pad *= Math.max(1, k);
   const xs = points.map((q) => q[0]);
   const ys = points.map((q) => q[1]);
   const x = Math.floor(Math.min(...xs) - pad);
@@ -63,6 +71,11 @@ export function traceCanvas(el: HTMLElement, points: readonly Pt[], pad = 40): {
   el.append(c);
   const g = c.getContext("2d")!;
   g.translate(-x, -y);
+  if (k !== 1) {
+    const lw = Object.getOwnPropertyDescriptor(CanvasRenderingContext2D.prototype, "lineWidth")!;
+    Object.defineProperty(g, "lineWidth", { get: () => lw.get!.call(g) / k, set: (v: number) => lw.set!.call(g, v * k) });
+    g.lineWidth = 1;
+  }
   return { g, clear: () => g.clearRect(x, y, w, h) };
 }