kasaframe 0.1.1 → 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

@@ -0,0 +1,92 @@
+import { clamp } from "@kasaframe/core";
+
+// 테마 slots.ts 들이 같이 쓰는 작은 도구. 슬롯은 build 때(장면이 숨어 있어 크기 0) 불리므로 크기를 재지 않는 길만 둔다 —
+// 판은 % 로, 선은 점 좌표를 감싸는 캔버스로.
+
+export function layer(parent: HTMLElement, css: string, first = false): HTMLDivElement {
+  const d = parent.ownerDocument.createElement("div");
+  d.style.cssText = `position:absolute;pointer-events:none;${css}`;
+  if (first) parent.prepend(d);
+  else parent.append(d);
+  return d;
+}
+
+/** 글자마다 span — 배치를 바꾸지 않게 inline 그대로. 빈칸은 글자로 남긴다 */
+export function letters(el: HTMLElement, text: string): HTMLSpanElement[] {
+  el.textContent = "";
+  return Array.from(text).map((ch) => {
+    const s = el.ownerDocument.createElement("span");
+    s.textContent = ch;
+    el.append(s);
+    return s;
+  });
+}
+
+/** at 부터 dur 동안 앞에서부터 몇 글자가 찍혔나 — at+dur 부터는 전부 */
+export const shownCount = (n: number, t: number, at: number, dur: number): number =>
+  t >= at + dur ? n : t < at ? 0 : Math.min(n, Math.floor(clamp((t - at) / Math.max(1e-3, dur)) * n) + 1);
+
+export type Pt = readonly [number, number];
+
+/** 꺾은선 길이 비율 p 까지의 점들 — 마지막 점은 선분 안에서 끊는다 */
+export function partial(points: readonly Pt[], p: number): [number, number][] {
+  if (points.length < 2) return points.map((q) => [q[0], q[1]]);
+  const seg = points.slice(1).map((q, i) => Math.hypot(q[0] - points[i][0], q[1] - points[i][1]));
+  const total = seg.reduce((a, b) => a + b, 0) || 1;
+  let left = clamp(p) * total;
+  const out: [number, number][] = [[points[0][0], points[0][1]]];
+  for (let i = 0; i < seg.length; i++) {
+    if (left >= seg[i]) {
+      out.push([points[i + 1][0], points[i + 1][1]]);
+      left -= seg[i];
+      continue;
+    }
+    const k = seg[i] ? left / seg[i] : 0;
+    out.push([points[i][0] + (points[i + 1][0] - points[i][0]) * k, points[i][1] + (points[i + 1][1] - points[i][1]) * k]);
+    break;
+  }
+  return out;
+}
+
+/** 변주의 선 굵기 배수(--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);
+  const y = Math.floor(Math.min(...ys) - pad);
+  const w = Math.ceil(Math.max(...xs) + pad) - x;
+  const h = Math.ceil(Math.max(...ys) + pad) - y;
+  const c = el.ownerDocument.createElement("canvas");
+  c.width = Math.max(1, w);
+  c.height = Math.max(1, h);
+  c.style.cssText = `position:absolute;left:${x}px;top:${y}px;width:${w}px;height:${h}px;pointer-events:none`;
+  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) };
+}
+
+export function strokePath(g: CanvasRenderingContext2D, pts: readonly Pt[]): void {
+  if (pts.length < 2) return;
+  g.beginPath();
+  g.moveTo(pts[0][0], pts[0][1]);
+  for (const q of pts.slice(1)) g.lineTo(q[0], q[1]);
+  g.stroke();
+}
+
+/** CSS 변수 색 — 슬롯은 테마 토큰만 쓴다 */
+export const cssVar = (el: HTMLElement, name: string, fallback: string): string =>
+  getComputedStyle(el).getPropertyValue(`--kf-${name}`).trim() || fallback;

package/packages/themes/src/slots.ts

@@ -0,0 +1,61 @@
+/// <reference types="vite/client" />
+// 페이지(Vite) 쪽. 장면 문법 패턴은 테마 이름을 모른다 — 일반 자리 여섯을 부르고, 테마가 themes/<id>/slots.ts 에서 자기 효과로 채운다.
+// 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;
+
+/**
+ * 모든 슬롯은 같은 t 면 같은 화면이고, 난수는 seed 로만. 비운 슬롯은 패턴이 제 기본으로 그린다.
+ * 화면 전체를 덮는 3D(three)는 surface 에서만 — 크롬이 WebGL 문맥을 몇 개만 살려 두므로 나머지 슬롯은 DOM·캔버스 2D 로.
+ */
+export interface ThemeSlots {
+  /** 화면 전체 바탕 질감. el = 장면 맨 뒤 inset:0 층. 장면마다 한 번 짓는다. 글을 두지 않는다 */
+  surface?(el: HTMLElement, o: { ctx: SceneCtx; seed: string }): Paint;
+  /**
+   * 카드·상자 판. el = 패턴이 자리·크기를 잡은 상자(position:absolute). 판은 el 안 맨 앞 자식으로 깔고 내용은 패턴이 그 위에 둔다.
+   * at 에 선다(그 전엔 안 보인다). 상자 크기·자리는 바꾸지 않는다 — 배치는 패턴 몫. tone 은 accent 면 강조 판
+   */
+  panel?(el: HTMLElement, o: { ctx: SceneCtx; at: number; seed: string; tone?: "base" | "accent" }): Paint;
+  /**
+   * 앉는 순간 한 번 — 숫자·이름·칸이 at 에 앉을 때. el 둘레에 곁 그림(빛·그림자·도장)을 지어도 되고, 돌려준 Style 은 패턴이 el 에 combine 한다.
+   * 섬광·흔들림은 motion 부품(dropBurst·shake)을 거쳐 __kf.events 에 남게. at 에서 0.6초 안에 끝나 선다
+   */
+  land?(el: HTMLElement, o: { ctx: SceneCtx; at: number; seed: string }): (t: number) => Style;
+  /**
+   * 글 찍기 — el(패턴이 글꼴 크기·자리를 잡은 글 상자)에 text 를 at 부터 찍는다. at + dur 부터는 el.textContent 가 text 그대로.
+   * 글꼴 크기·줄 수는 바꾸지 않는다(배치가 흔들린다) — 색·그림자·글자 굴림만
+   */
+  write?(el: HTMLElement, o: { ctx: SceneCtx; text: string; at: number; dur: number; seed: string }): Paint;
+  /** 선 긋기 — el = inset:0 층, points 는 그 층 px. at 부터 dur 동안 그어지고, 다 그은 뒤에도 선 안이 흐른다 */
+  trace?(el: HTMLElement, o: { ctx: SceneCtx; points: readonly (readonly [number, number])[]; at: number; dur: number; seed: string; tone?: "base" | "accent" }): Paint;
+  /** 드롭 터짐 — 그 테마의 드롭 연출. 돌려준 shake 는 패턴이 화면 틀에, punch 는 주인공에 준다. 드롭 번호로만 */
+  drop?(el: HTMLElement, o: { ctx: SceneCtx; drop: number }): (t: number) => DropBurstState;
+}
+
+export const SLOT_NAMES = ["surface", "panel", "land", "write", "trace", "drop"] as const satisfies readonly (keyof ThemeSlots)[];
+
+const mods = import.meta.glob("../../../themes/*/slots.ts", { eager: true }) as Record<string, { slots?: ThemeSlots }>;
+
+const byId = new Map(Object.entries(mods).map(([path, mod]) => [path.split("/").at(-2)!, mod.slots ?? {}]));
+
+// 변주의 움직임 빠르기(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/stage3d.ts

@@ -100,6 +100,26 @@ export function stage3d(root: HTMLElement, o: StageOpts): Stage3D {
   };
 }
 
+/**
+ * 서 있는 무대 — 처음 한 번만 그려 2D 캔버스로 옮겨 두고 그 뒤로는 다시 그리지 않는다.
+ * 움직이지 않는 3D 바탕(테마 슬롯 surface)을 프레임마다 SwiftShader 로 그릴 까닭이 없고, 렌더러 캔버스는 다른 무대가 가져가도 된다
+ */
+export function stillStage(stage: Stage3D, paint: (t: number) => void = (t) => stage.paint(t)): (t: number) => void {
+  let done = false;
+  return () => {
+    if (done) return;
+    paint(0);
+    const src = stage.renderer.domElement;
+    const c = document.createElement("canvas");
+    c.width = src.width;
+    c.height = src.height;
+    c.style.cssText = src.style.cssText;
+    c.getContext("2d")!.drawImage(src, 0, 0);
+    src.replaceWith(c);
+    done = true;
+  };
+}
+
 export interface TextPlaneOpts {
   text: string;
   /** CSS font 단축 꼴의 앞부분 없이 글꼴 스택만 — 굵기·크기는 따로 */

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;