kasaframe 0.0.0-stage → 0.1.3

package/packages/themes/src/factory.ts

@@ -0,0 +1,296 @@
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, extname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { checkTheme, themesDir } from "./index.ts";
+import type { ThemeManifest, ThemeStatus } from "./types.ts";
+
+// 테마 공장 — 참고 자료에서 테마 팩 뼈대와 지시서(THEME-MAKE.md)를 짓고, 계약을 검사하고, 견본을 review 로 올린다.
+// 테마를 만드는 건 지시서를 받은 모델 세션이다. 공장은 그 세션이 매번 같은 틀·같은 브리프·같은 검사로 끝나게 하는 몫.
+
+export const kitDir = fileURLToPath(new URL("../kit/", import.meta.url));
+const repoRoot = resolve(themesDir, "..");
+const kfBin = join(repoRoot, "packages/cli/src/kf.ts");
+
+const IMAGE = new Set([".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg", ".avif"]);
+const VIDEO = new Set([".mp4", ".mov", ".webm", ".mkv", ".m4v"]);
+const KOREAN = /Pretendard|Noto Sans KR|Apple SD Gothic Neo|Jua|Galmuri|DungGeunMo|NeoDunggeunmo/;
+// 장면 뼈대에 남겨 둔 표시 — 이게 남아 있으면 장면을 아직 안 썼다
+const SKELETON = "THEME-MAKE.md 5단계에서 이 파일을 통째로 다시 쓴다";
+
+export interface BriefKit {
+  id: string;
+  doc: string;
+  label: string;
+  share: string;
+  music: string;
+  from: number;
+  to: number;
+  assets: Record<string, string>;
+  scenes: { id: string; role: string; until: string; idea: string }[];
+}
+
+export const briefs = (): string[] => readdirSync(join(kitDir, "briefs")).filter((d) => existsSync(join(kitDir, "briefs", d, "brief.json")));
+
+export function loadBrief(id: string): BriefKit {
+  const file = join(kitDir, "briefs", id, "brief.json");
+  if (!existsSync(file)) throw new Error(`브리프 "${id}" 가 없다. 있는 브리프: ${briefs().join(" ")}`);
+  return JSON.parse(readFileSync(file, "utf8")) as BriefKit;
+}
+
+const tilde = (p: string) => (p.startsWith("~/") ? join(homedir(), p.slice(2)) : p);
+const fill = (s: string, v: Record<string, string>) => s.replace(/\{\{(\w+)\}\}/g, (_, k: string) => v[k] ?? `{{${k}}}`);
+const writeJson = (file: string, v: unknown) => writeFileSync(file, `${JSON.stringify(v, null, 2)}\n`);
+const readJson = <T>(file: string): T => JSON.parse(readFileSync(file, "utf8")) as T;
+
+function run(cmd: string, args: string[], quiet = false): number {
+  const r = spawnSync(cmd, args, { cwd: repoRoot, stdio: quiet ? ["ignore", "ignore", "inherit"] : "inherit" });
+  return r.status ?? 1;
+}
+const kf = (args: string[], quiet = false) => run(process.execPath, [kfBin, ...args], quiet);
+
+const THREE_NOTE = `
+## 입체(three.js) 테마 — 평면이 아니라 깊이·원근·빛으로 선다
+
+- 바탕은 \`@kasaframe/themes/stage3d\`: \`stage3d(root, { ctx, camera: "perspective" | "ortho", fog, env, shot(t, camera) })\` 가 무대(씬·카메라·\`add(rig)\`·\`paint(t)\`)를 주고, 렌더러는 페이지에 하나를 돌려 쓴다(크롬은 한 페이지에 WebGL 문맥을 16 개쯤만 살린다). \`textPlane({ text, family, color, height })\` 은 한글이 서는 글꼴로 그린 글자판, \`roomEnvironment(renderer)\` 는 금속·유리가 비칠 환경광, \`roundRectShape\` 는 OG 로고의 둥근 사각 칸 꼴. \`THREE\` 도 거기서 다시 내보낸다.
+- 테마 효과 중 3D 부품은 kind \`rig\` = \`(stage, opts) => (t) => void\` — 무대에 물체를 얹고 t 로 움직인다. 카메라·빛·재질 값을 **전부 t 로** 정한다 — \`THREE.Clock\`·\`requestAnimationFrame\`·누적 회전 금지.
+- 카메라 경로는 \`flyPath\`(@kasaframe/motion) 나 닫힌 식. 마디마다 컷(카메라를 새 자리로 끊어 옮기거나 다른 세트로), 박마다 큰 사건(물체가 날아들고·켜지고·갈라지고).
+- 화면 글은 3D 공간 안의 글자판으로. 검사의 화면 글 훑기는 WebGL 안 글을 못 읽으니, 끝 카드처럼 꼭 읽혀야 하는 글은 DOM 으로 겹쳐 둬도 된다.
+- 헤드리스 크롬은 GPU 없이 SwiftShader 로 그린다 — 한 프레임 50ms 안을 넘지 않게 정점 수·그림자 맵·후처리를 아낀다. 큰 원통·구는 분할 수를 낮게, 그림자는 하나. 투과 유리(\`MeshPhysicalMaterial.transmission\`)는 그리기를 한 번 더 하니 한 화면에 몇 개만.
+- 컷은 씬 안 오브젝트의 \`visible\` 로(CSS 가 아니다).
+`;
+
+export interface ScaffoldOpts {
+  refs: string[];
+  name?: string;
+  brief?: string;
+  like?: string;
+  kind?: "flat" | "3d";
+  force?: boolean;
+}
+
+/** themes/<id>/ 를 짓는다 — 계약 파일 뼈대 · refs/ · 브리프대로 자른 곡과 박 · 장면 넷 뼈대 · THEME-MAKE.md */
+export function scaffold(id: string, o: ScaffoldOpts): { dir: string; make: string; refs: string[]; urls: string[] } {
+  if (!/^[a-z][a-z0-9-]{1,40}$/.test(id)) throw new Error(`테마 id 는 소문자·숫자·하이픈(첫 글자는 영문): "${id}"`);
+  const dir = join(themesDir, id);
+  if (existsSync(dir) && readdirSync(dir).length && !o.force) throw new Error(`${dir} 가 이미 있다 — 덮어쓰려면 --force`);
+  const brief = loadBrief(o.brief ?? "og-intro-15s");
+  const like = o.like && existsSync(join(themesDir, o.like, "style.json")) ? o.like : null;
+  mkdirSync(join(dir, "refs", "frames"), { recursive: true });
+
+  // 참고 자료 — 파일·폴더는 복사, 영상은 장면 여섯 장을 뽑고, 주소는 목록으로
+  const files: string[] = [];
+  const urls: string[] = [];
+  const take = (src: string) => {
+    const ext = extname(src).toLowerCase();
+    if (!IMAGE.has(ext) && !VIDEO.has(ext)) return;
+    const name = basename(src).replace(/[^\w.가-힣-]/g, "_");
+    copyFileSync(src, join(dir, "refs", name));
+    files.push(`refs/${name}`);
+    if (VIDEO.has(ext)) {
+      const probe = spawnSync("ffprobe", ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", src], { encoding: "utf8" });
+      const dur = Number(probe.stdout) || 6;
+      for (let k = 1; k <= 6; k++) {
+        const out = join(dir, "refs", "frames", `${name.replace(/\.\w+$/, "")}-${k}.jpg`);
+        spawnSync("ffmpeg", ["-v", "error", "-y", "-ss", String((dur * k) / 7), "-i", src, "-frames:v", "1", "-vf", "scale=960:-2", out]);
+        if (existsSync(out)) files.push(`refs/frames/${basename(out)}`);
+      }
+    }
+  };
+  for (const r of o.refs) {
+    if (/^https?:\/\//.test(r)) {
+      urls.push(r);
+      continue;
+    }
+    const p = resolve(tilde(r));
+    if (!existsSync(p)) throw new Error(`참고 자료가 없다: ${r}`);
+    if (statSync(p).isDirectory()) for (const f of readdirSync(p)) take(join(p, f));
+    else take(p);
+  }
+  writeJson(join(dir, "refs", "refs.json"), { files, urls });
+
+  const name = o.name ?? id;
+  writeJson(join(dir, "theme.json"), {
+    id,
+    name,
+    metaphor: "",
+    status: "draft",
+    approvedAt: null,
+    purposes: [],
+    aspect: ["16:9"],
+    effects: [],
+  } satisfies ThemeManifest);
+  const base = like ? readJson<Record<string, unknown>>(join(themesDir, like, "style.json")) : readJson<Record<string, unknown>>(join(repoRoot, "presets", "neutral-dark.json"));
+  writeJson(join(dir, "style.json"), { ...base, name: id, label: name, notes: [`뼈대: ${like ? `테마 ${like}` : "presets/neutral-dark"} 에서 — 3단계에서 통째로 바꾼다`] });
+  const vars = { id, name, brief: `${brief.label}(${brief.doc}), 곡 ${basename(brief.music)} ${brief.from}–${brief.to}초`, share: brief.share };
+  writeFileSync(join(dir, "THEME.md"), fill(readFileSync(join(kitDir, "THEME.md"), "utf8"), vars));
+  writeFileSync(join(dir, "effects.ts"), fill(readFileSync(join(kitDir, "effects.ts"), "utf8"), vars));
+
+  // 견본 뼈대 — 곡을 브리프 구간으로 자르고 박을 재서 장면 경계를 마디·드롭에 붙인다
+  const sample = join(dir, "sample");
+  mkdirSync(join(sample, "scenes"), { recursive: true });
+  mkdirSync(join(sample, "lib"), { recursive: true });
+  mkdirSync(join(sample, "assets", "music"), { recursive: true });
+  // 브리프의 곡은 곡 모음(music/·KF_MUSIC_DIR) 안 이름 — 절대 경로·~/ 도 받는다
+  const song = isAbsolute(tilde(brief.music)) ? tilde(brief.music) : join(process.env.KF_MUSIC_DIR ?? join(repoRoot, "music"), brief.music);
+  const dur = +(brief.to - brief.from).toFixed(4);
+  const cut = `${basename(song).replace(/\.\w+$/, "")}-${String(Math.round(brief.from * 100)).padStart(4, "0")}.mp3`;
+  spawnSync("ffmpeg", ["-v", "error", "-y", "-ss", String(brief.from), "-t", String(dur), "-i", song, "-af", `afade=t=in:d=0.03,afade=t=out:st=${dur - 0.3}:d=0.3`, "-c:a", "libmp3lame", "-b:a", "192k", join(sample, "assets", "music", cut)]);
+  if (kf(["beats", song, "--from", String(brief.from), "--duration", String(dur), "--out", join(sample, "beats.json")], true) !== 0) throw new Error("kf beats 가 실패했다");
+  const beats = readJson<{ bars: number[]; drops: number[]; source: string; from: number }>(join(sample, "beats.json"));
+  writeJson(join(sample, "beats.json"), { ...beats, source: `assets/music/${cut}`, from: 0 });
+  const edge = (until: string): number => {
+    if (until === "end") return dur;
+    const [kind, v] = until.split(":");
+    if (kind === "drop") return beats.drops[Number(v)] ?? dur / 2;
+    const want = Number(v);
+    return beats.bars.reduce((a, b) => (Math.abs(b - want) < Math.abs(a - want) ? b : a), beats.bars[0] ?? want);
+  };
+  let from = 0;
+  const scenes = brief.scenes.map((s) => {
+    const to = +edge(s.until).toFixed(4);
+    const e = { id: s.id, from, dur: +(to - from).toFixed(4), file: `scenes/${s.id}.ts`, role: s.role, idea: s.idea };
+    from = to;
+    return e;
+  });
+  writeJson(join(sample, "kf.json"), {
+    template: "promo",
+    title: `${id} · ${brief.label}`,
+    theme: id,
+    fps: 60,
+    width: 1920,
+    height: 1080,
+    duration: dur,
+    mode: "seek",
+    style: "style.json",
+    music: `assets/music/${cut}`,
+    beats: "beats.json",
+    captions: "none",
+    safeArea: { top: 60, bottom: 60, left: 80, right: 80 },
+    text: { policy: "terms-only", maxOnScreen: 0, minPx: 0 },
+    scenes,
+  });
+  copyFileSync(join(dir, "style.json"), join(sample, "style.json"));
+  writeFileSync(join(sample, "index.html"), fill(readFileSync(join(kitDir, "sample", "index.html"), "utf8"), vars));
+  copyFileSync(join(kitDir, "sample", "main.ts"), join(sample, "main.ts"));
+  const sceneKit = readFileSync(join(kitDir, "sample", "scenes", "scene.ts"), "utf8");
+  for (const s of scenes) writeFileSync(join(sample, s.file), fill(sceneKit, { ...vars, scene: s.id, idea: s.idea }));
+  copyFileSync(join(kitDir, "briefs", brief.id, "facts.ts"), join(sample, "lib", "facts.ts"));
+  for (const [to, src] of Object.entries(brief.assets)) {
+    mkdirSync(join(sample, "assets", to, ".."), { recursive: true });
+    copyFileSync(join(kitDir, "briefs", brief.id, src), join(sample, "assets", to));
+  }
+
+  const make = join(dir, "THEME-MAKE.md");
+  const refsLine = [...files.map((f) => `\`${f}\``), ...urls.map((u) => `<${u}>`)].join(" · ") || "(없음 — 브리프와 approved 테마만 보고 정한다)";
+  writeFileSync(
+    make,
+    fill(readFileSync(join(kitDir, "THEME-MAKE.md"), "utf8"), {
+      ...vars,
+      refs: refsLine,
+      like: like ?? "(없음)",
+      briefDoc: brief.doc,
+      kindNote: o.kind === "3d" ? THREE_NOTE : "",
+    }),
+  );
+  return { dir, make, refs: files, urls };
+}
+
+/** 계약 + 지시서가 남긴 빈칸까지 — 견본 페이지 검사(kf check)는 따로 */
+export async function staticCheck(id: string): Promise<string[]> {
+  const dir = join(themesDir, id);
+  if (!existsSync(join(dir, "theme.json"))) return [`themes/${id} 가 없다`];
+  const bad = checkTheme(dir);
+  const m = readJson<ThemeManifest>(join(dir, "theme.json"));
+  const guide = existsSync(join(dir, "THEME.md")) ? readFileSync(join(dir, "THEME.md"), "utf8") : "";
+  if (/TODO/.test(guide)) bad.push("THEME.md 에 TODO 가 남았다");
+  // 머리말 꼴은 공장이 지은 테마(지시서가 있는 것)에만 — 공장 전에 손으로 만든 테마는 꼴이 다를 수 있다
+  if (existsSync(join(dir, "THEME-MAKE.md"))) for (const h of ["**비유:", "## 맞는 내용·용도", "## 금지", "## 움직임", "## 효과"]) if (!guide.includes(h)) bad.push(`THEME.md 에 「${h.replace(/\*/g, "")}」 가 없다`);
+  if (existsSync(join(dir, "refs")) && !existsSync(join(dir, "refs", "NOTES.md"))) bad.push("refs/NOTES.md 가 없다 — 참고 자료에서 본 것을 적는다(2단계)");
+  try {
+    const style = readJson<{ fonts?: Record<string, string> }>(join(dir, "style.json"));
+    for (const k of ["sans", "display", "mono"]) if (!KOREAN.test(style.fonts?.[k] ?? "")) bad.push(`style.json fonts.${k} 가 한글이 서는 글꼴로 끝나지 않는다`);
+  } catch {
+    bad.push("style.json 을 못 읽는다");
+  }
+  if (existsSync(join(dir, "effects.ts"))) {
+    try {
+      const mod = (await import(pathToFileURL(join(dir, "effects.ts")).href)) as Record<string, unknown>;
+      const exported = Object.keys(mod).filter((k) => typeof mod[k] === "function").sort();
+      const listed = (m.effects ?? []).map((e) => e.name).sort();
+      const missing = listed.filter((n) => !exported.includes(n));
+      const extra = exported.filter((n) => !listed.includes(n));
+      if (missing.length) bad.push(`theme.json 에 있는데 effects.ts 에 없는 효과: ${missing.join(" ")}`);
+      if (extra.length) bad.push(`effects.ts 가 내보내는데 theme.json 에 없는 효과: ${extra.join(" ")}`);
+    } catch (e) {
+      bad.push(`effects.ts 를 불러오지 못했다 — ${(e as Error).message.split("\n")[0]}`);
+    }
+  }
+  const sample = join(dir, "sample");
+  if (existsSync(join(sample, "scenes"))) {
+    for (const f of readdirSync(join(sample, "scenes"))) if (readFileSync(join(sample, "scenes", f), "utf8").includes(SKELETON)) bad.push(`sample/scenes/${f} 가 아직 뼈대다`);
+  }
+  return bad;
+}
+
+export function setStatus(id: string, status: ThemeStatus): ThemeManifest {
+  const file = join(themesDir, id, "theme.json");
+  const m = readJson<ThemeManifest>(file);
+  const d = new Date();
+  const today = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+  const next = { ...m, status, approvedAt: status === "approved" ? today : null };
+  writeJson(file, next);
+  return next;
+}
+
+/** 견본을 굽고 검사하고 장면 모음·대표 장면·작은 sample.mp4 를 만들어 공유 폴더에 넣고 status 를 review 로 */
+export function review(id: string, o: { brief?: string; tabs?: number; share?: boolean } = {}): { ok: boolean; share: string | null; notes: string[] } {
+  const dir = join(themesDir, id);
+  const sample = join(dir, "sample");
+  const out = join(sample, "out");
+  const notes: string[] = [];
+  const brief = loadBrief(o.brief ?? "og-intro-15s");
+  const tabs = String(o.tabs ?? 2);
+  if (kf(["render", sample, "--tabs", tabs]) !== 0) return { ok: false, share: null, notes: ["kf render 가 실패했다"] };
+  if (kf(["check", join(out, "render.mp4")]) !== 0) return { ok: false, share: null, notes: ["mp4 검사가 실패했다 — 보고서를 보고 고친다"] };
+  kf(["sheet", sample, "--count", "16", "--cols", "4", "--width", "640", "--out", join(out, "scenes.png")], true);
+  const beats = readJson<{ drops: number[] }>(join(sample, "beats.json"));
+  const stillAt = Math.min((beats.drops[0] ?? 5) + 0.7, brief.to - brief.from - 0.5);
+  kf(["still", sample, "--t", stillAt.toFixed(2)], true);
+  const still = readdirSync(out).find((f) => f.startsWith("still-") && f.endsWith(".png"));
+  if (still) {
+    // 종이결·잡음이 많은 테마는 대표 장면이 몇 MB — 레포에는 1280 폭으로
+    spawnSync("ffmpeg", ["-v", "error", "-y", "-i", join(out, still), "-vf", "scale='min(1920,iw)':-2", join(dir, "still.png")]);
+    if (statSync(join(dir, "still.png")).size > 2_000_000) spawnSync("ffmpeg", ["-v", "error", "-y", "-i", join(out, still), "-vf", "scale=1280:-2", join(dir, "still.png")]);
+  }
+  const enc = (args: string[], to: string) =>
+    spawnSync("ffmpeg", ["-v", "error", "-y", "-i", join(out, "render.mp4"), ...args, "-pix_fmt", "yuv420p", "-color_range", "tv", "-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709", "-c:a", "copy", "-movflags", "+faststart", to]);
+  const shareMp4 = join(out, "share.mp4");
+  enc(["-c:v", "libx264", "-preset", "slow", "-crf", "24"], shareMp4);
+  enc(["-c:v", "libx264", "-preset", "slow", "-crf", "26"], join(dir, "sample.mp4"));
+  if (statSync(join(dir, "sample.mp4")).size > 8_000_000) enc(["-vf", "scale=1280:720:flags=lanczos", "-c:v", "libx264", "-preset", "slow", "-crf", "30"], join(dir, "sample.mp4"));
+  notes.push(`sample.mp4 ${(statSync(join(dir, "sample.mp4")).size / 1e6).toFixed(1)}MB`);
+  let share: string | null = null;
+  if (o.share !== false) {
+    const r = spawnSync("kasaterm-cli", ["share", "new", `kasaframe-테마-${id}`], { encoding: "utf8" });
+    share = r.status === 0 ? (r.stdout.trim().split("\n").pop() ?? null) : null;
+    if (!share || !existsSync(share)) {
+      share = join(homedir(), "Desktop", `kasaframe-테마-${id}`);
+      mkdirSync(share, { recursive: true });
+      notes.push("kasaterm-cli share 가 없어 바탕화면에 폴더를 만들었다");
+    }
+    copyFileSync(shareMp4, join(share, `${id}-${brief.share}.mp4`));
+    if (existsSync(join(out, "scenes.png"))) copyFileSync(join(out, "scenes.png"), join(share, `장면모음-${brief.share}.png`));
+    if (still) copyFileSync(join(out, still), join(share, `대표장면-${brief.share}.png`));
+    copyFileSync(join(dir, "THEME.md"), join(share, "THEME.md"));
+  }
+  setStatus(id, "review");
+  return { ok: true, share, notes };
+}
+
+/** 지시서 원문 — 새 세션에 그대로 넘기는 첫 메시지 */
+export function sessionPrompt(id: string): string {
+  return `themes/${id}/THEME-MAKE.md 를 처음부터 끝까지 읽고 그대로 따라 테마 ${id} 를 만든다. 끝나면 npx kf theme review ${id} 까지.`;
+}
+

package/packages/themes/src/fx.ts

@@ -0,0 +1,14 @@
+/// <reference types="vite/client" />
+// 페이지(Vite) 쪽. 테마 폴더를 늘려도 이 파일은 그대로 — themes/*/effects.ts 를 모아 id 로 꺼낸다.
+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")` */
+export function fx<T = Record<string, (...args: any[]) => any>>(id: string): T {
+  const mod = byId.get(id);
+  if (!mod) throw new Error(`테마 효과 "${id}" 가 없다. 있는 테마: ${themeIds().join(" ") || "(없음)"}`);
+  return mod as T;
+}

package/packages/themes/src/index.ts

@@ -0,0 +1,114 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+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";
+
+export type * from "./types.ts";
+export { THEME_STATUSES } from "./types.ts";
+
+export const themesDir = fileURLToPath(new URL("../../../themes/", import.meta.url));
+
+export interface ThemeFilter {
+  /** 하나나 여럿. 안 주면 전부 */
+  status?: ThemeStatus | ThemeStatus[];
+  purpose?: string;
+  aspect?: string;
+}
+
+const readJson = <T>(path: string): T => JSON.parse(readFileSync(path, "utf8")) as T;
+const fileOrNull = (path: string): string | null => (existsSync(path) ? path : null);
+
+/** 틀이 깨진 곳을 사람이 읽을 줄로. 빈 배열이면 통과 */
+export function checkTheme(dir: string): string[] {
+  const bad: string[] = [];
+  for (const f of ["theme.json", "style.json", "THEME.md", "effects.ts"]) if (!existsSync(join(dir, f))) bad.push(`${f} 가 없다`);
+  if (bad.length) return bad;
+  const m = readJson<Partial<ThemeManifest>>(join(dir, "theme.json"));
+  const id = dir.replace(/\/+$/, "").split("/").pop();
+  if (m.id !== id) bad.push(`theme.json id "${m.id}" 가 폴더 이름 "${id}" 와 다르다`);
+  for (const k of ["name", "metaphor"] as const) if (typeof m[k] !== "string" || !m[k]) bad.push(`theme.json ${k} 가 비었다`);
+  if (!THEME_STATUSES.includes(m.status as ThemeStatus)) bad.push(`theme.json status 는 ${THEME_STATUSES.join("|")} 중 하나`);
+  if (m.status === "approved" && !m.approvedAt) bad.push("approved 인데 approvedAt 이 없다");
+  if (!Array.isArray(m.purposes) || !m.purposes.length) bad.push("theme.json purposes 가 비었다");
+  if (!Array.isArray(m.aspect) || !m.aspect.length) bad.push("theme.json aspect 가 비었다");
+  const n = m.effects?.length ?? 0;
+  if (n < 5 || n > 10) bad.push(`효과는 5–10개 — 지금 ${n}개`);
+  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 (!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"} 가 없다`);
+    if (!existsSync(join(dir, "sample", "kf.json"))) bad.push(`${m.status} 인데 견본 프로젝트 sample/ 이 없다`);
+  }
+  return bad;
+}
+
+export function loadTheme(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,
+    dir,
+    style: readJson<KfStyle>(join(dir, "style.json")),
+    guide: readFileSync(join(dir, "THEME.md"), "utf8"),
+    files: {
+      still: fileOrNull(join(dir, m.still ?? "still.png")),
+      sample: fileOrNull(join(dir, m.sample ?? "sample.mp4")),
+      sampleProject: fileOrNull(join(dir, "sample")),
+      effects: join(dir, "effects.ts"),
+    },
+  };
+}
+
+/** 틀이 깨진 테마는 건너뛴다 — 하나가 깨져도 목록은 선다 */
+export function listThemes(filter: ThemeFilter = {}): Theme[] {
+  if (!existsSync(themesDir)) return [];
+  const want = filter.status === undefined ? null : [filter.status].flat();
+  const out: Theme[] = [];
+  for (const id of readdirSync(themesDir).sort()) {
+    if (!existsSync(join(themesDir, id, "theme.json")) || checkTheme(join(themesDir, id)).length) continue;
+    const t = loadTheme(id);
+    if (want && !want.includes(t.status)) continue;
+    if (filter.purpose && !t.purposes.includes(filter.purpose)) continue;
+    if (filter.aspect && !t.aspect.includes(filter.aspect)) continue;
+    out.push(t);
+  }
+  return out;
+}
+
+/** 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 function themeCards(filter: ThemeFilter = {}): ThemeCard[] {
+  return listThemes(filter).map((t) => ({
+    id: t.id,
+    name: t.name,
+    metaphor: t.metaphor,
+    status: t.status,
+    approvedAt: t.approvedAt,
+    still: t.files.still,
+    sample: t.files.sample,
+    purposes: t.purposes,
+    aspect: t.aspect,
+  }));
+}
+
+/**
+ * 프로젝트 style.json 으로 쓸 것 — 프리셋과 같은 꼴 통째. 틀의 motion 은 프리셋 때처럼 위에 덮는다.
+ * 고른 id 가 draft 면 던진다(견본을 만드는 테마 폴더 안에서만 쓴다)
+ */
+export function themeStyle(id: string, opts: { allowDraft?: boolean } = {}): KfStyle {
+  const t = loadTheme(id);
+  if (t.status === "draft" && !opts.allowDraft) throw new Error(`테마 ${id} 는 아직 draft — 견본이 review 로 올라온 뒤에 쓴다`);
+  return structuredClone(t.style);
+}

package/packages/themes/src/slotkit.ts

@@ -0,0 +1,79 @@
+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;
+}
+
+/** 점들을 감싸는 캔버스(여백 pad) — 그리기는 층 좌표 그대로 */
+export function traceCanvas(el: HTMLElement, points: readonly Pt[], pad = 40): { g: CanvasRenderingContext2D; clear(): void } {
+  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);
+  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,46 @@
+/// <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";
+
+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 ?? {}]));
+
+/** 테마 슬롯 — 없는 테마(npm 묶음에 안 든 테마 포함)나 슬롯을 안 채운 테마는 빈 객체 */
+export const themeSlots = (id: string | undefined | null): ThemeSlots => (id ? byId.get(id) ?? {} : {});
+
+export const slotThemeIds = (): string[] => [...byId.keys()].sort();