kasaframe 0.0.0-stage → 0.1.1

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,105 @@
+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;
+}
+
+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/stage3d.ts

@@ -0,0 +1,177 @@
+import type { SceneCtx } from "@kasaframe/core";
+import * as THREE from "three";
+import { RoomEnvironment } from "three/examples/jsm/environments/RoomEnvironment.js";
+
+// 입체 테마가 같이 쓰는 바탕 — 렌더러 하나·한글 글자판·환경광. 테마의 효과(rig)는 이 위에 물체를 얹고 t 로 움직인다.
+
+let shared: THREE.WebGLRenderer | null = null;
+
+// 크롬은 한 페이지에 WebGL 문맥을 16 개쯤만 살려 둔다 — 장면이 여럿이어도 렌더러 하나를 돌려 쓰고, 그리는 장면으로 캔버스를 옮긴다
+export function renderer3d(w: number, h: number): THREE.WebGLRenderer {
+  if (!shared) {
+    shared = new THREE.WebGLRenderer({ antialias: true, preserveDrawingBuffer: true, alpha: false, powerPreference: "high-performance" });
+    shared.setPixelRatio(1);
+    shared.outputColorSpace = THREE.SRGBColorSpace;
+    shared.toneMapping = THREE.ACESFilmicToneMapping;
+    shared.shadowMap.enabled = true;
+    shared.shadowMap.type = THREE.PCFSoftShadowMap;
+    shared.domElement.style.cssText = "position:absolute;inset:0;width:100%;height:100%;display:block";
+  }
+  const size = shared.getSize(new THREE.Vector2());
+  if (size.x !== w || size.y !== h) shared.setSize(w, h, false);
+  return shared;
+}
+
+let envTex: THREE.Texture | null = null;
+/** 방 하나의 빛을 환경 맵으로 — 금속·유리가 비칠 것이 생긴다. 한 번만 굽는다 */
+export function roomEnvironment(renderer: THREE.WebGLRenderer): THREE.Texture {
+  if (!envTex) {
+    const pmrem = new THREE.PMREMGenerator(renderer);
+    envTex = pmrem.fromScene(new RoomEnvironment(), 0.04).texture;
+    pmrem.dispose();
+  }
+  return envTex;
+}
+
+/** 3D 부품(rig) — 무대 위에 물체를 얹고 t 마다 움직인다. 같은 t 면 같은 자리 */
+export type Rig = (t: number) => void;
+
+export interface Stage3D {
+  scene: THREE.Scene;
+  camera: THREE.PerspectiveCamera | THREE.OrthographicCamera;
+  renderer: THREE.WebGLRenderer;
+  /** 무대가 박힌 DOM 자리(장면 루트 안) — 겹칠 DOM 은 여기 형제로 */
+  el: HTMLElement;
+  /** rig 를 등록 — paint(t) 가 카메라를 놓은 뒤 차례로 부른다 */
+  add(rig: Rig): void;
+  /** rig 를 다 부르고 그린다 */
+  paint(t: number): void;
+}
+
+export interface StageOpts {
+  ctx: SceneCtx;
+  camera?: "perspective" | "ortho";
+  fov?: number;
+  /** 정사영일 때 화면 세로에 담길 세계 단위 */
+  frustum?: number;
+  background?: string;
+  fog?: [near: number, far: number];
+  env?: boolean;
+  exposure?: number;
+  /** 카메라를 t 로 — 자리와 보는 곳 */
+  shot?(t: number, camera: THREE.Camera): void;
+}
+
+export function stage3d(root: HTMLElement, o: StageOpts): Stage3D {
+  const { ctx } = o;
+  const W = ctx.meta.width;
+  const H = ctx.meta.height;
+  const el = document.createElement("div");
+  el.style.cssText = "position:absolute;inset:0;";
+  root.append(el);
+  const renderer = renderer3d(W, H);
+  const scene = new THREE.Scene();
+  const bg = new THREE.Color(o.background ?? ctx.style.colors.bg);
+  scene.background = bg;
+  if (o.fog) scene.fog = new THREE.Fog(bg, o.fog[0], o.fog[1]);
+  if (o.env) scene.environment = roomEnvironment(renderer);
+  let camera: THREE.PerspectiveCamera | THREE.OrthographicCamera;
+  if (o.camera === "ortho") {
+    const f = o.frustum ?? 10;
+    const a = W / H;
+    camera = new THREE.OrthographicCamera((-f * a) / 2, (f * a) / 2, f / 2, -f / 2, 0.1, 400);
+  } else {
+    camera = new THREE.PerspectiveCamera(o.fov ?? 50, W / H, 0.1, 400);
+  }
+  const rigs: Rig[] = [];
+  return {
+    scene,
+    camera,
+    renderer,
+    el,
+    add: (rig) => rigs.push(rig),
+    paint(t) {
+      if (renderer.domElement.parentElement !== el) el.prepend(renderer.domElement);
+      renderer.toneMappingExposure = o.exposure ?? 1;
+      o.shot?.(t, camera);
+      for (const r of rigs) r(t);
+      renderer.render(scene, camera);
+    },
+  };
+}
+
+export interface TextPlaneOpts {
+  text: string;
+  /** CSS font 단축 꼴의 앞부분 없이 글꼴 스택만 — 굵기·크기는 따로 */
+  family: string;
+  weight?: number;
+  color: string;
+  /** 세계 단위 높이(글 한 줄) */
+  height: number;
+  /** 캔버스에 그릴 글 크기 px — 클수록 가까이서도 또렷하다 */
+  px?: number;
+  align?: "left" | "center" | "right";
+  /** 바탕을 칠하면 판, 없으면 투명 */
+  plate?: string;
+  pad?: number;
+  emissive?: boolean;
+}
+
+/** 한글이 서는 글꼴로 캔버스에 그린 글을 판(평면 메시)으로. 장면 build 에서 만든다(글꼴을 다 받은 뒤라 치수가 맞다) */
+export function textPlane(o: TextPlaneOpts): THREE.Mesh<THREE.PlaneGeometry, THREE.MeshBasicMaterial> {
+  const px = o.px ?? 160;
+  const pad = o.pad ?? px * 0.25;
+  const font = `${o.weight ?? 700} ${px}px ${o.family}`;
+  const probe = document.createElement("canvas").getContext("2d")!;
+  probe.font = font;
+  const w = Math.ceil(probe.measureText(o.text).width + pad * 2);
+  const h = Math.ceil(px * 1.3 + pad * 2);
+  const c = document.createElement("canvas");
+  c.width = w;
+  c.height = h;
+  const g = c.getContext("2d")!;
+  if (o.plate) {
+    g.fillStyle = o.plate;
+    g.fillRect(0, 0, w, h);
+  }
+  g.font = font;
+  g.fillStyle = o.color;
+  g.textBaseline = "middle";
+  g.textAlign = "left";
+  g.fillText(o.text, pad, h / 2);
+  const tex = new THREE.CanvasTexture(c);
+  tex.colorSpace = THREE.SRGBColorSpace;
+  tex.anisotropy = 4;
+  const worldH = (o.height * h) / (px * 1.3);
+  const worldW = (worldH * w) / h;
+  const geo = new THREE.PlaneGeometry(worldW, worldH);
+  if (o.align === "left") geo.translate(worldW / 2, 0, 0);
+  if (o.align === "right") geo.translate(-worldW / 2, 0, 0);
+  const mat = new THREE.MeshBasicMaterial({ map: tex, transparent: true, depthWrite: false, toneMapped: !o.emissive, side: THREE.DoubleSide });
+  return new THREE.Mesh(geo, mat);
+}
+
+/** 둥근 사각 테(관문) 모양 — OG 로고의 두 칸이 이 꼴이다 */
+export function roundRectShape(w: number, h: number, r: number, hole = 0): THREE.Shape {
+  const s = new THREE.Shape();
+  const rr = (p: THREE.Path | THREE.Shape, x: number, y: number, ww: number, hh: number, rad: number) => {
+    p.moveTo(x + rad, y);
+    p.lineTo(x + ww - rad, y);
+    p.quadraticCurveTo(x + ww, y, x + ww, y + rad);
+    p.lineTo(x + ww, y + hh - rad);
+    p.quadraticCurveTo(x + ww, y + hh, x + ww - rad, y + hh);
+    p.lineTo(x + rad, y + hh);
+    p.quadraticCurveTo(x, y + hh, x, y + hh - rad);
+    p.lineTo(x, y + rad);
+    p.quadraticCurveTo(x, y, x + rad, y);
+  };
+  rr(s, -w / 2, -h / 2, w, h, r);
+  if (hole > 0) {
+    const p = new THREE.Path();
+    rr(p, -w / 2 + hole, -h / 2 + hole, w - hole * 2, h - hole * 2, Math.max(0.01, r - hole * 0.6));
+    s.holes.push(p);
+  }
+  return s;
+}
+
+export { THREE };

package/packages/themes/src/types.ts

@@ -0,0 +1,58 @@
+import type { KfStyle } from "@kasaframe/core";
+
+/** draft 만드는 중 · review 견본이 나와 사람이 볼 차례 · approved 사람이 OK 해서 라이브러리에 정식으로 들어감 */
+export type ThemeStatus = "draft" | "review" | "approved";
+
+export const THEME_STATUSES: readonly ThemeStatus[] = ["draft", "review", "approved"];
+
+export interface ThemeEffectInfo {
+  /** effects.ts 의 이름 있는 내보내기와 같다 */
+  name: string;
+  /** value: (t, opts) => Style·수·글 · layer: (el, opts) => (t) => void · rig: (stage, opts) => (t) => void(3D 무대에 물체를 얹는다) — 모두 같은 t 면 같은 화면 */
+  kind: "value" | "layer" | "rig";
+  /** 무엇을 하나 — 한 줄 */
+  does: string;
+  /** 부르는 꼴 한 줄(모델이 그대로 베낀다) */
+  use: string;
+}
+
+/** themes/<id>/theme.json */
+export interface ThemeManifest {
+  id: string;
+  name: string;
+  /** 내용에서 나온 비유 한 줄 — 「무엇이 무엇처럼 되며 화면이 찍힌다」 */
+  metaphor: string;
+  status: ThemeStatus;
+  /** approved 로 바꾼 날(ISO). 그 전엔 null */
+  approvedAt: string | null;
+  /** 어울리는 용도 — templates/<id> */
+  purposes: string[];
+  /** 견본이 서는 화면비. 앞이 견본의 화면비 */
+  aspect: string[];
+  effects: ThemeEffectInfo[];
+  /** 테마 폴더 기준 파일 이름. 기본 still.png · sample.mp4 */
+  still?: string;
+  sample?: string;
+}
+
+export interface Theme extends ThemeManifest {
+  dir: string;
+  style: KfStyle;
+  /** THEME.md 원문 — 비유·맞는 내용·금지 */
+  guide: string;
+  /** 절대 경로. 파일이 아직 없으면 null */
+  files: { still: string | null; sample: string | null; sampleProject: string | null; effects: string };
+}
+
+/** 작업실·plan 이 목록에 쓰는 꼴. still·sample 은 절대 경로(없으면 null) */
+export interface ThemeCard {
+  id: string;
+  name: string;
+  metaphor: string;
+  status: ThemeStatus;
+  approvedAt: string | null;
+  still: string | null;
+  sample: string | null;
+  purposes: string[];
+  aspect: string[];
+}