kasaframe 0.1.1 → 0.1.4

package/packages/themes/package.json

@@ -7,10 +7,18 @@
     ".": "./src/index.ts",
     "./fx": "./src/fx.ts",
     "./factory": "./src/factory.ts",
-    "./stage3d": "./src/stage3d.ts"
+    "./stage3d": "./src/stage3d.ts",
+    "./slots": "./src/slots.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"
   },
   "dependencies": {
     "@kasaframe/core": "0.0.0",
-    "three": "^0.186.1"
+    "three": "^0.186.1",
+    "@kasaframe/motion": "^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/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;
 }

package/packages/themes/src/index.ts

@@ -1,11 +1,15 @@
 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 { allowedFonts, fontPairs, 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 +18,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 +43,13 @@ 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 !== "base" && !f.startsWith("tag:") && !known.has(f)) bad.push(`vary.fonts 의 글꼴 짝 ${f} 이 kit/fonts.json 에 없다`);
+    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 에 없다`);
+  }
+  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 +58,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,13 +130,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(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,223 @@
+// 고르기 — 500 판 가까이 되는 세계·변주 가운데 요청·분위기 낱말·레퍼런스 그림에 맞는 판을 점수로 줄 세운다(SPEC 9 변주).
+// 내용 맞음(세계 비유·용도 낱말)과 생김새 맞음(밝기·색상·채도·질감·글꼴)을 따로 재 더한다.
+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";
+
+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 }],
+  [["종이", "아날로그", "인쇄", "빈티지", "vintage", "paper", "질감", "손맛", "잡지", "zine", "필름", "film"], { textures: ["paper", "grain", "halftone"] }],
+  [["레트로", "retro", "crt", "브라운관", "옛날", "80년대", "90년대", "오락실"], { textures: ["scan", "noise"], fontTags: ["pixel"] }],
+  [["픽셀", "pixel", "도트", "8비트", "8bit"], { fontTags: ["pixel"] }],
+  [["명조", "세리프", "serif", "클래식", "고전", "우아", "에디토리얼", "editorial", "신문", "문학"], { fontTags: ["serif", "editorial"] }],
+  [["귀여운", "귀엽", "cute", "카와이", "kawaii", "둥근", "말랑", "아기자기", "친근"], { fontTags: ["rounded", "friendly"] }],
+  [["기술", "테크", "tech", "코딩", "개발자", "터미널", "로그", "해커", "hacker", "고정폭"], { fontTags: ["mono", "tech"] }],
+  [["굵은", "볼드", "bold", "임팩트", "포스터"], { fontTags: ["bold", "display"] }],
+  [["입체", "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);
+  // 세계 글꼴은 짝 목록에 없다 — 제목 글꼴 이름으로 어림한다
+  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 ?? 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);