kasaframe 0.1.3 → 0.1.4

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) };
 }
 

package/packages/themes/src/slots.ts

@@ -3,6 +3,7 @@
 // effects.ts 와 따로 두는 까닭: effects.ts 내보내기는 theme.json 효과 목록과 같아야 한다(테마 시험).
 import type { SceneCtx, Style } from "@kasaframe/core";
 import type { DropBurstState } from "@kasaframe/motion";
+import { worldOf } from "./name.ts";
 
 export type Paint = (t: number) => void;
 
@@ -40,7 +41,21 @@ const mods = import.meta.glob("../../../themes/*/slots.ts", { eager: true }) as
 
 const byId = new Map(Object.entries(mods).map(([path, mod]) => [path.split("/").at(-2)!, mod.slots ?? {}]));
 
-/** 테마 슬롯 — 없는 테마(npm 묶음에 안 든 테마 포함)나 슬롯을 안 채운 테마는 빈 객체 */
-export const themeSlots = (id: string | undefined | null): ThemeSlots => (id ? byId.get(id) ?? {} : {});
+// 변주의 움직임 빠르기(style.look.tempo) — 세계 코드는 그대로 두고 글 찍기·선 긋기에 주는 길이만 줄이고 늘린다. 너무 짧으면 글이 한 번에 찍혀 보여 하한을 둔다
+const paced = <O extends { ctx: SceneCtx; dur: number }>(o: O): O => {
+  const k = o.ctx.style?.look?.tempo ?? 1;
+  return k === 1 ? o : { ...o, dur: Math.max(0.12, o.dur / k) };
+};
+
+function withLook(s: ThemeSlots): ThemeSlots {
+  return {
+    ...s,
+    ...(s.write ? { write: (el, o) => s.write!(el, paced(o)) } : {}),
+    ...(s.trace ? { trace: (el, o) => s.trace!(el, paced(o)) } : {}),
+  };
+}
+
+/** 테마 슬롯 — 변주 이름이면 그 세계 슬롯. 없는 테마(npm 묶음에 안 든 테마 포함)나 슬롯을 안 채운 테마는 빈 객체 */
+export const themeSlots = (id: string | undefined | null): ThemeSlots => (id ? withLook(byId.get(worldOf(id)) ?? {}) : {});
 
 export const slotThemeIds = (): string[] => [...byId.keys()].sort();

package/packages/themes/src/types.ts

@@ -33,9 +33,92 @@ export interface ThemeManifest {
   /** 테마 폴더 기준 파일 이름. 기본 still.png · sample.mp4 */
   still?: string;
   sample?: string;
+  /** 변주가 바꿔도 되는 축과 범위 — 없으면 변주를 안 받는다(SPEC 9 변주) */
+  vary?: ThemeVary;
+  /** 고르기 태그 — 분위기·밝기·용도·2D/3D */
+  tags?: ThemeTags;
+}
+
+export type TextureKind = "none" | "grain" | "paper" | "noise" | "scan" | "halftone";
+
+/** theme.json vary — 세계가 허락한 축만 돈다. 안 적은 축은 세계 값 그대로 */
+export interface ThemeVary {
+  /** 받는 밝기. 안 주면 세계 scheme 하나 */
+  scheme?: ("light" | "dark")[];
+  /** 강조 색상 범위들(OKLCH 도, [시작, 끝] — 끝이 작으면 360 을 넘어 돈다). 안 주면 세계 색상 그대로 */
+  hue?: [number, number][];
+  /** 색 있는 잉크 채도 배수 */
+  chroma?: [number, number];
+  /** 무채색에 얹는 빛깔 채도(OKLCH C) */
+  tint?: [number, number];
+  /** 바탕 명도(OKLCH L) — 밝음·어두움마다 */
+  bg?: { light?: [number, number]; dark?: [number, number] };
+  /** 늘 그대로 두는 색 열쇠 */
+  keep?: string[];
+  /** 색상은 두고 명도·채도만 따라가는 색 열쇠(풀·물 같은 재료 색) */
+  fixedHue?: string[];
+  /** 글꼴 짝 id(packages/themes/kit/fonts.json)·`tag:<태그>`·`base`(세계 글꼴) */
+  fonts?: string[];
+  /** 세 글꼴 스택을 짝의 고정폭 하나로(한 글꼴 HUD) — 그러면 monoAll 짝만 받는다 */
+  monoAll?: boolean;
+  /** 받는 질감 */
+  texture?: TextureKind[];
+  /** 선 굵기 배수 범위 */
+  stroke?: [number, number];
+  /** 판 모서리(radius.md px) 범위 — sm·lg 는 세계 비율로 따라간다 */
+  radius?: [number, number];
+  /** 움직임 빠르기 배수 범위(1 보다 크면 빠르다) */
+  tempo?: [number, number];
+  /** 장식·입자 밀도 배수 범위 — 세계 코드가 look.density·--kf-density 를 읽을 때만 적는다 */
+  density?: [number, number];
+}
+
+export interface ThemeTags {
+  /** 분위기 낱말(한국어) */
+  mood: string[];
+  light: "light" | "dark";
+  /** 맞는 내용·용도 낱말 */
+  use: string[];
+  dims: "2D" | "3D";
+}
+
+/** 변주를 지은 손잡이 값 — 다시 지을 때·서로 다름을 잴 때 */
+export interface VariantParams {
+  scheme: "light" | "dark";
+  bgL: number;
+  tint: { h: number; c: number };
+  inkL: number;
+  hue: number;
+  chroma: number;
+  fonts: string;
+  texture: { kind: TextureKind; amount: number };
+  stroke: number;
+  /** radius.md px, 세계가 안 받으면 null */
+  radius: number | null;
+  tempo: number;
+  density: number;
+}
+
+/** themes/<세계>/variants/<id>.json — 데이터만. 코드는 세계 것 */
+export interface VariantManifest {
+  id: string;
+  world: string;
+  /** 생김새가 떠오르는 영어 이름 */
+  name: string;
+  /** 한 줄 한국어 설명 */
+  desc: string;
+  params: VariantParams;
+  /** 세계 style.json 위에 덮는 판 — colors 는 통째, 나머지는 칸마다 */
+  style: Partial<Pick<KfStyle, "scheme" | "colors" | "fonts" | "radius" | "look">> & { type?: Partial<KfStyle["type"]> };
+  tags: ThemeTags;
+  check: { ok: boolean; at: string; colors: Record<string, number>; frame: string; pattern?: string };
 }
 
 export interface Theme extends ThemeManifest {
+  /** 세계 id — 변주가 아니면 id 와 같다 */
+  world: string;
+  /** 변주면 그 매니페스트, 세계 자신이면 null */
+  variant: VariantManifest | null;
   dir: string;
   style: KfStyle;
   /** THEME.md 원문 — 비유·맞는 내용·금지 */
@@ -47,6 +130,7 @@ export interface Theme extends ThemeManifest {
 /** 작업실·plan 이 목록에 쓰는 꼴. still·sample 은 절대 경로(없으면 null) */
 export interface ThemeCard {
   id: string;
+  world: string;
   name: string;
   metaphor: string;
   status: ThemeStatus;

package/packages/themes/src/vary.ts

@@ -0,0 +1,290 @@
+// 변주 — 세계 하나에서 겉모습만 바꾼 판을 데이터로 뽑는다(SPEC 9 변주). 코드는 세계 것을 그대로 쓰고, 여기서는 style 위에 덮을 판만 짓는다.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { rand, randRange, type KfStyle } from "@kasaframe/core";
+import { hueDist, labOf, parseColor } from "./color.ts";
+import { lchOf, NEUTRAL_C, transformPalette } from "./palette.ts";
+import type { TextureKind, ThemeManifest, ThemeTags, ThemeVary, VariantManifest, VariantParams } from "./types.ts";
+
+export interface FontPair {
+  id: string;
+  name: string;
+  ko: string;
+  tags: string[];
+  sans: string;
+  display: string;
+  mono: string;
+  faces: NonNullable<KfStyle["fonts"]["faces"]>;
+  weightDisplay: number;
+  weightBody: number;
+  tracking: string;
+  monoAll?: boolean;
+}
+
+let pairs: FontPair[] | null = null;
+export const fontPairs = (): FontPair[] => (pairs ??= JSON.parse(readFileSync(fileURLToPath(new URL("../kit/fonts.json", import.meta.url)), "utf8")));
+
+/** 세계가 허락한 글꼴 짝 — 「base」는 세계 글꼴 그대로 */
+export function allowedFonts(vary: ThemeVary): string[] {
+  const all = fontPairs().filter((p) => !vary.monoAll || p.monoAll);
+  const want = vary.fonts ?? ["base"];
+  const ids = want.flatMap((w) => (w === "base" ? ["base"] : w.startsWith("tag:") ? all.filter((p) => p.tags.includes(w.slice(4))).map((p) => p.id) : all.some((p) => p.id === w) ? [w] : []));
+  return [...new Set(ids)];
+}
+
+// 질감마다 기본 세기 — 엔진이 깐 층의 불투명도
+const TEXTURE_AMOUNT: Record<TextureKind, number> = { none: 0, grain: 0.55, paper: 0.8, noise: 0.35, scan: 0.22, halftone: 0.16 };
+
+const BG_L = { light: [0.93, 0.99], dark: [0.12, 0.22] } as const;
+// 어두운 바탕은 같은 채도라도 빛깔이 덜 보인다 — 거기서는 무채색 빛깔을 더 얹는다
+const DARK_TINT = 1.7;
+const INK_L = { light: [0.14, 0.26], dark: [0.91, 0.97] } as const;
+
+/** 세계 자신 — 변주를 잴 때의 원점 */
+export function baseParams(style: KfStyle): VariantParams {
+  const bg = lchOf(style.colors.bg);
+  return {
+    scheme: style.scheme,
+    bgL: bg.l,
+    tint: { h: bg.h, c: bg.c },
+    inkL: lchOf(style.colors.ink).l,
+    hue: lchOf(style.colors.accent).h,
+    chroma: 1,
+    fonts: "base",
+    texture: style.look?.texture ?? { kind: "none", amount: 0 },
+    stroke: style.look?.stroke ?? 1,
+    radius: null,
+    tempo: style.look?.tempo ?? 1,
+    density: style.look?.density ?? 1,
+  };
+}
+
+const inRanges = (h: number, ranges: [number, number][]) => ranges.some(([a, b]) => (a <= b ? h >= a && h <= b : h >= a || h <= b));
+
+function sampleHue(seed: string, i: number, ranges: [number, number][]): number {
+  const span = ranges.map(([a, b]) => (a <= b ? b - a : 360 - a + b));
+  let x = rand(seed, i) * span.reduce((s, v) => s + v, 0);
+  for (const [k, [a]] of ranges.entries()) {
+    if (x <= span[k]) return (a + x) % 360;
+    x -= span[k];
+  }
+  return ranges[0][0];
+}
+
+/** 손잡이 값 하나 — 세계가 안 받는 축은 세계 값 */
+export function sampleParams(style: KfStyle, vary: ThemeVary, seed: string, n: number): VariantParams {
+  const base = baseParams(style);
+  const r = (k: number, lo: number, hi: number) => randRange(seed, n * 32 + k, lo, hi);
+  const pickOf = <T>(k: number, items: readonly T[]): T => items[Math.min(items.length - 1, Math.floor(rand(seed, n * 32 + k) * items.length))];
+  const scheme = pickOf(0, vary.scheme ?? [style.scheme]);
+  const bgR = vary.bg?.[scheme] ?? BG_L[scheme];
+  const hue = vary.hue ? sampleHue(seed, n * 32 + 1, vary.hue) : base.hue;
+  // 무채색 빛깔은 반쯤은 강조색 쪽(한 집안), 반쯤은 아무 쪽
+  const tintH = rand(seed, n * 32 + 2) < 0.5 ? (hue + r(3, -30, 30) + 360) % 360 : r(4, 0, 360);
+  const tex = pickOf(5, vary.texture ?? [base.texture.kind]);
+  const chroma = vary.chroma ? r(10, vary.chroma[0], vary.chroma[1]) : 1;
+  // 바탕이 색 잉크인 세계는 바탕이 강조색과 같은 각도로 돌아야 모눈·선과 한 벌로 남는다 — tint 축은 무채색 바탕 세계 것
+  const tint = base.tint.c >= NEUTRAL_C
+    ? { h: (base.tint.h + hue - base.hue + 360) % 360, c: base.tint.c * chroma }
+    : { h: tintH, c: vary.tint ? r(7, vary.tint[0], vary.tint[1]) * (scheme === "dark" ? DARK_TINT : 1) : base.tint.c };
+  const q = (v: number) => +v.toFixed(4);
+  return {
+    scheme,
+    bgL: q(r(6, bgR[0], bgR[1])),
+    tint: { h: q(tint.h), c: q(tint.c) },
+    inkL: q(scheme === style.scheme && rand(seed, n * 32 + 8) < 0.5 ? base.inkL : r(9, INK_L[scheme][0], INK_L[scheme][1])),
+    hue: q(hue),
+    chroma: q(chroma),
+    fonts: pickOf(11, allowedFonts(vary)),
+    texture: { kind: tex, amount: tex === base.texture.kind ? base.texture.amount || TEXTURE_AMOUNT[tex] : TEXTURE_AMOUNT[tex] },
+    stroke: vary.stroke ? +r(12, vary.stroke[0], vary.stroke[1]).toFixed(2) : base.stroke,
+    radius: vary.radius ? Math.round(r(13, vary.radius[0], vary.radius[1])) : null,
+    tempo: vary.tempo ? +r(14, vary.tempo[0], vary.tempo[1]).toFixed(2) : base.tempo,
+    density: vary.density ? +r(15, vary.density[0], vary.density[1]).toFixed(2) : base.density,
+  };
+}
+
+/** 손잡이 값 → 세계 style 위에 덮을 판. 색이 검사를 못 넘으면 bad 에 까닭 */
+export function overlayOf(style: KfStyle, manifest: Pick<ThemeManifest, "vary">, p: VariantParams): { style: VariantManifest["style"]; bad: string[]; measured: Record<string, number> } {
+  const vary = manifest.vary ?? {};
+  const pal = transformPalette(style.colors, p, { keep: vary.keep, fixedHue: vary.fixedHue });
+  const out: VariantManifest["style"] = { scheme: p.scheme, colors: pal.colors as KfStyle["colors"] };
+  if (p.fonts !== "base") {
+    const f = fontPairs().find((x) => x.id === p.fonts);
+    if (!f) return { style: out, bad: [`글꼴 짝 ${p.fonts} 이 없다`], measured: pal.measured };
+    out.fonts = vary.monoAll ? { sans: f.mono, display: f.mono, mono: f.mono, faces: f.faces } : { sans: f.sans, display: f.display, mono: f.mono, faces: f.faces };
+    out.type = { weightDisplay: f.weightDisplay, weightBody: f.weightBody, tracking: f.tracking };
+  }
+  if (p.radius !== null) {
+    const md0 = style.radius.md || 12;
+    const k = p.radius / md0;
+    out.radius = { sm: Math.round((style.radius.sm || md0 * 0.6) * k), md: p.radius, lg: Math.round((style.radius.lg || md0 * 1.6) * k), pill: style.radius.pill };
+  }
+  out.look = {
+    ...(p.texture.kind !== "none" ? { texture: p.texture } : {}),
+    ...(p.stroke !== 1 ? { stroke: p.stroke } : {}),
+    ...(p.tempo !== 1 ? { tempo: p.tempo } : {}),
+    ...(p.density !== 1 ? { density: p.density } : {}),
+  };
+  return { style: out, bad: pal.bad, measured: pal.measured };
+}
+
+/** 세계 style + 변주 판 → 프로젝트 style.json 으로 쓸 통째 */
+export function mergeVariant(style: KfStyle, v: Pick<VariantManifest, "id" | "world" | "name" | "style" | "params">): KfStyle {
+  const o = v.style;
+  const k = v.params.tempo || 1;
+  const durations = style.motion.durations && k !== 1 ? Object.fromEntries(Object.entries(style.motion.durations).map(([n, d]) => [n, +(d / k).toFixed(3)])) : style.motion.durations;
+  return {
+    ...structuredClone(style),
+    name: `${v.world}/${v.id}`,
+    label: `${style.label} · ${v.name}`,
+    ...(o.scheme ? { scheme: o.scheme } : {}),
+    ...(o.colors ? { colors: { ...o.colors } } : {}),
+    ...(o.fonts ? { fonts: structuredClone(o.fonts) } : {}),
+    type: { ...style.type, ...o.type },
+    ...(o.radius ? { radius: { ...o.radius } } : {}),
+    motion: { ...style.motion, ...(durations ? { durations: durations as KfStyle["motion"]["durations"] } : {}) },
+    look: { ...style.look, ...o.look },
+  };
+}
+
+// --- 서로 다름: 색이 먼저(바탕·강조), 글꼴·질감이 그다음, 선·모서리는 덤
+
+export interface Candidate {
+  params: VariantParams;
+  overlay: VariantManifest["style"];
+  measured: Record<string, number>;
+  /** 바탕·강조·잉크 OKLab — 거리 잴 때마다 다시 풀지 않게 */
+  lab: Record<"bg" | "accent" | "ink", [number, number, number]>;
+}
+
+const candidate = (params: VariantParams, overlay: VariantManifest["style"], measured: Record<string, number>): Candidate => {
+  const c = overlay.colors!;
+  return { params, overlay, measured, lab: { bg: labOf(parseColor(c.bg)), accent: labOf(parseColor(c.accent)), ink: labOf(parseColor(c.ink)) } };
+};
+
+export function distance(a: Candidate, b: Candidate): number {
+  const d = (k: "bg" | "accent" | "ink") => Math.hypot(a.lab[k][0] - b.lab[k][0], a.lab[k][1] - b.lab[k][1], a.lab[k][2] - b.lab[k][2]);
+  return (
+    1.6 * d("bg") +
+    1.4 * d("accent") +
+    0.5 * d("ink") +
+    (a.params.fonts !== b.params.fonts ? 0.12 : 0) +
+    (a.params.texture.kind !== b.params.texture.kind ? 0.08 : 0) +
+    0.06 * Math.abs(a.params.stroke - b.params.stroke) +
+    (a.params.radius !== null && b.params.radius !== null ? 0.004 * Math.abs(a.params.radius - b.params.radius) : 0)
+  );
+}
+
+/**
+ * 후보를 많이 굴려 색 검사를 넘은 것만 두고, 이미 고른 것들과 가장 먼 것부터 차례로 늘어놓는다(먼 점 고르기).
+ * 앞의 n 개가 뽑을 판이고 뒤는 굽기 검사에서 떨어진 판의 자리를 메울 예비다
+ */
+export function rankCandidates(style: KfStyle, manifest: Pick<ThemeManifest, "vary">, o: { seed: string; pool?: number; taken?: Candidate[] }): Candidate[] {
+  const vary = manifest.vary ?? {};
+  const base = baseParams(style);
+  const ok: Candidate[] = [];
+  for (let i = 0; i < (o.pool ?? 400); i++) {
+    const params = sampleParams(style, vary, o.seed, i);
+    const r = overlayOf(style, manifest, params);
+    if (!r.bad.length) ok.push(candidate(params, r.style, r.measured));
+  }
+  const near = ok.map((c) => Math.min(...[candidate(base, { colors: style.colors }, {}), ...(o.taken ?? [])].map((x) => distance(c, x))));
+  const out: Candidate[] = [];
+  const left = new Set(ok.keys());
+  while (left.size) {
+    let best = -1;
+    for (const i of left) if (best < 0 || near[i] > near[best]) best = i;
+    left.delete(best);
+    out.push(ok[best]);
+    for (const i of left) near[i] = Math.min(near[i], distance(ok[i], ok[best]));
+  }
+  return out;
+}
+
+// --- 이름: 바탕 낱말 + 강조 낱말(겹치면 글꼴·질감 낱말)
+
+const ACCENT_WORDS: [number, string, string][] = [
+  [15, "rose", "장밋빛"], [35, "coral", "산호색"], [55, "orange", "주황"], [78, "amber", "호박색"], [100, "gold", "금빛"],
+  [125, "lime", "라임색"], [150, "green", "초록"], [178, "jade", "옥색"], [200, "teal", "청록"], [222, "cyan", "하늘빛 청록"],
+  [242, "sky", "하늘색"], [262, "blue", "파랑"], [282, "indigo", "남색"], [305, "violet", "보라"], [330, "plum", "자두색"], [350, "magenta", "자홍"], [361, "pink", "분홍"],
+];
+
+function accentWord(h: number): [string, string] {
+  const w = ACCENT_WORDS.find(([max]) => h < max) ?? ACCENT_WORDS[0];
+  return [w[1], w[2]];
+}
+
+function bgWord(p: VariantParams): [string, string] {
+  const tinted = p.tint.c >= (p.scheme === "dark" ? 0.02 : 0.012);
+  const h = p.tint.h;
+  const fam = !tinted ? "neutral" : h < 40 || h >= 340 ? "pink" : h < 100 ? "warm" : h < 170 ? "green" : h < 280 ? "cool" : "violet";
+  const light: Record<string, [string, string]> = {
+    neutral: p.bgL > 0.975 ? ["snow", "새하얀"] : ["chalk", "분필빛"],
+    pink: ["blush", "연분홍"],
+    warm: p.bgL > 0.96 ? ["cream", "크림색"] : ["sand", "모래빛"],
+    green: ["sage", "세이지"],
+    cool: ["frost", "서리빛"],
+    violet: ["lilac", "연보라"],
+  };
+  const dark: Record<string, [string, string]> = {
+    neutral: p.bgL < 0.14 ? ["night", "검은"] : ["slate", "짙은 회색"],
+    pink: ["wine", "포도주빛"],
+    warm: ["cocoa", "코코아빛"],
+    green: ["forest", "짙은 숲빛"],
+    cool: p.tint.h < 230 ? ["deep", "깊은 청록"] : ["navy", "짙은 남색"],
+    violet: ["dusk", "해 질 녘 보랏빛"],
+  };
+  return (p.scheme === "dark" ? dark : light)[fam];
+}
+
+const TEXTURE_KO: Record<TextureKind, [string, string]> = {
+  none: ["", ""], grain: ["grain", "고운 필름 입자"], paper: ["paper", "종이 결"], noise: ["noise", "거친 잡음"], scan: ["scan", "주사선"], halftone: ["dots", "망점"],
+};
+
+const FONT_WORD = (p: FontPair | undefined): string => (!p ? "" : p.tags.includes("serif") ? "serif" : p.tags.includes("pixel") ? "pixel" : p.tags.includes("rounded") ? "round" : p.tags.includes("mono") ? "mono" : p.tags.includes("bold") ? "bold" : p.id.split("-")[0]);
+
+// 이름·태그는 손잡이가 아니라 화면에 실린 색으로 — 세계가 강조·바탕을 묶어 둔 판(회로 기판의 금 강조)은 hue 를 굴려도 그 색이 안 돈다
+function seen(p: VariantParams, colors?: Record<string, string>): VariantParams {
+  if (!colors?.bg || !colors.accent) return p;
+  const bg = lchOf(colors.bg);
+  return { ...p, bgL: bg.l, tint: { h: bg.h, c: bg.c }, hue: lchOf(colors.accent).h };
+}
+
+export function nameVariant(params: VariantParams, taken: Set<string>, colors?: Record<string, string>): { id: string; name: string; desc: string } {
+  const p = seen(params, colors);
+  const [bg, bgKo] = bgWord(p);
+  const [acc, accKo] = accentWord(p.hue);
+  const pair = fontPairs().find((x) => x.id === p.fonts);
+  const [tex, texKo] = TEXTURE_KO[p.texture.kind];
+  const tries = [`${bg}-${acc}`, ...(tex ? [`${bg}-${acc}-${tex}`] : []), ...(pair ? [`${bg}-${acc}-${FONT_WORD(pair)}`] : [])];
+  let id = tries.find((t) => !taken.has(t));
+  for (let i = 2; !id; i++) if (!taken.has(`${bg}-${acc}-${i}`)) id = `${bg}-${acc}-${i}`;
+  const name = id.split("-").map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
+  const desc = [`${bgKo} 바탕에 ${accKo} 강조`, pair ? pair.ko.split(/\s*—\s*/)[0] : "", texKo].filter(Boolean).join(" · ");
+  return { id, name, desc };
+}
+
+/** 변주 태그 — 세계 태그에 색·질감·글꼴이 주는 분위기를 더한다 */
+export function variantTags(world: ThemeTags, params: VariantParams, colors?: Record<string, string>): ThemeTags {
+  const p = seen(params, colors);
+  const mood = new Set(world.mood);
+  mood.add(p.scheme === "dark" ? "어두운" : "밝은");
+  if (inRanges(p.hue, [[20, 100]])) mood.add("따뜻한");
+  if (inRanges(p.hue, [[180, 290]])) mood.add("차가운");
+  if (p.chroma >= 1.12) mood.add("선명한");
+  if (p.chroma <= 0.85) mood.add("차분한");
+  if (["paper", "grain", "halftone", "noise"].includes(p.texture.kind)) mood.add("아날로그");
+  if (p.texture.kind === "scan") mood.add("레트로");
+  const tags = fontPairs().find((x) => x.id === p.fonts)?.tags ?? [];
+  if (tags.includes("serif")) mood.add("고전적");
+  if (tags.includes("rounded")) mood.add("귀여운");
+  if (tags.includes("pixel")) mood.add("레트로");
+  if (tags.includes("mono")) mood.add("기술적");
+  return { ...world, mood: [...mood], light: p.scheme };
+}
+
+export const candidateOf = candidate;
+
+export const hueOf = (colors: Record<string, string>): number => lchOf(colors.accent).h;
+export { hueDist };