kasaframe 0.1.1 → 0.1.4

package/packages/cli/src/segments.ts

@@ -0,0 +1,402 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import type { ViteDevServer } from "vite";
+import type { Session, Tab } from "./browser.ts";
+import { type BlurOpts, captureBlurred } from "./blur.ts";
+import { concat, encoder, type VideoFormat } from "./ffmpeg.ts";
+import { repoRoot } from "./serve.ts";
+
+// 장면 조각 렌더 — 장면마다 out/segments/<장면>-<해시>.mp4 를 두고, 해시가 같으면 다시 찍지 않는다.
+// 해시는 그 장면이 실제로 불러온 모듈(Vite 모듈 그래프 — 장면 파일·lib·@kasaframe 소스·테마·glob 로 읽은 json)·
+// kf.json 의 그 장면 칸·자산·자막 줄·굽기 설정이다. seek 모드는 프레임이 시각의 순수 함수라 조각을 이어도 통짜로 구운 것과 프레임이 같다.
+
+// 조각 꼴(인코딩·해시 재료)이 바뀌면 올린다 — 옛 조각을 다시 쓰지 않게
+const VERSION = "seg-1";
+// 화면을 안 바꾸는 kf.json 칸 — 소리·굽기 기본값·검사 예외. 굽기 값(모션 블러)은 KeyOpts 로 따로 들어간다
+const NOT_FRAMES = new Set(["scenes", "music", "audio", "voice", "narration", "render", "check"]);
+const AUDIO = /\.(mp3|wav|m4a|aac|flac|ogg)$/i;
+
+export interface SceneEntry {
+  id: string;
+  from: number;
+  dur: number;
+  role?: string;
+  file?: string;
+  [k: string]: unknown;
+}
+
+export interface SceneSpan {
+  id: string;
+  role?: string;
+  /** 프레임 [start, end) */
+  start: number;
+  end: number;
+}
+
+/** 프레임 f 의 장면 — 페이지(mountProject)와 같은 판정 from ≤ f/fps. 조각들이 0..total 을 빈틈·겹침 없이 한 번씩 덮는다 */
+export function sceneSpans(scenes: Pick<SceneEntry, "id" | "from" | "role">[], fps: number, total: number): SceneSpan[] {
+  const firstFrame = (from: number) => {
+    let f = Math.max(0, Math.round(from * fps) - 2);
+    while (f / fps < from) f++;
+    return Math.min(total, f);
+  };
+  return scenes
+    .map((s, i) => ({ id: s.id, role: s.role, start: i === 0 ? 0 : firstFrame(s.from), end: i === scenes.length - 1 ? total : firstFrame(scenes[i + 1].from) }))
+    .filter((s) => s.end > s.start);
+}
+
+export interface KeyOpts {
+  width: number;
+  height: number;
+  fps: number;
+  format: VideoFormat;
+  crf?: number;
+  blur: BlurOpts | null;
+  captions?: string;
+  /** 크롬 판 — 래스터가 판마다 다를 수 있다 */
+  browser: string;
+}
+
+/** 굽기 설정 묶음 하나 — 자막 켠 판·끈 판처럼 같은 장면을 다른 설정으로 구운 조각을 따로 센다 */
+export const variantOf = (o: KeyOpts): string => sha(JSON.stringify([VERSION, o])).slice(0, 10);
+
+const sha = (...parts: (string | Buffer)[]) => {
+  const h = createHash("sha256");
+  for (const p of parts) h.update(p).update("\0");
+  return h.digest("hex");
+};
+
+const omit = (o: Record<string, unknown>, keys: Set<string>) => Object.fromEntries(Object.entries(o).filter(([k]) => !keys.has(k)));
+
+function listFiles(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? listFiles(join(dir, e.name)) : [join(dir, e.name)]));
+}
+
+interface Line {
+  scene?: string;
+  from?: number;
+  to?: number;
+}
+
+export interface SceneKey {
+  key: string;
+  /** 해시 재료 이름 → 그 해시. 조각 기록에 남겨 다음에 「무엇이 바뀌어 다시 찍나」를 짚는다 */
+  inputs: Record<string, string>;
+}
+
+/**
+ * 장면마다 조각 해시. 장면이 다른 장면 모듈을 불러오면(이음매 — 앞 장면 끝·뒤 장면 처음을 살아 있는 화면으로 잇는다) 그 장면들의 해시도 묻는다.
+ * 이음매는 앞뒤 둘만 쓰므로(transition3d live) 이웃 둘로 좁힌다 — 멀리 있는 장면을 고쳐도 이음매는 그대로.
+ */
+export function sceneKeys(server: ViteDevServer, root: string, o: KeyOpts): Map<string, SceneKey> {
+  const kf = JSON.parse(readFileSync(join(root, "kf.json"), "utf8")) as { scenes: SceneEntry[]; [k: string]: unknown };
+  const graph = server.environments.client.moduleGraph;
+  const kfFile = join(root, "kf.json");
+  const capFile = join(root, "captions.json");
+  const sceneFile = new Map(kf.scenes.map((s) => [join(root, s.file ?? `scenes/${s.id}.ts`), s.id]));
+  const memo = new Map<string, string>();
+  const fileHash = (f: string) => {
+    let h = memo.get(f);
+    if (h === undefined) {
+      h = existsSync(f) && statSync(f).isFile() ? sha(readFileSync(f)) : "-";
+      memo.set(f, h);
+    }
+    return h;
+  };
+  // 레포 소스와 프로젝트 파일만 — node_modules(외부 꾸러미·미리 묶은 의존)는 판이 바뀔 일이 드물고 수가 많다
+  const label = (f: string): string | null => {
+    for (const [base, tag] of [[root, ""], [repoRoot, "kf:"]] as const) {
+      const rel = relative(base, f);
+      if (rel.startsWith("..") || rel.split(sep).includes("node_modules")) continue;
+      if (tag === "" && rel.split(sep)[0] === "out") return null;
+      return `${tag}${rel}`;
+    }
+    return null;
+  };
+
+  function walk(start: string): { files: Map<string, string>; scenes: Set<string> } {
+    const files = new Map<string, string>();
+    const scenes = new Set<string>();
+    const stack = [...(graph.getModulesByFile(start) ?? [])];
+    const seen = new Set<unknown>();
+    while (stack.length) {
+      const m = stack.pop()!;
+      if (seen.has(m)) continue;
+      seen.add(m);
+      const f = m.file;
+      if (f && f !== start && sceneFile.has(f)) {
+        scenes.add(sceneFile.get(f)!);
+        continue;
+      }
+      const name = f ? label(f) : null;
+      if (f && !name) continue;
+      if (f && name && f !== kfFile && f !== capFile) files.set(name, fileHash(f));
+      stack.push(...m.importedModules);
+    }
+    if (!files.size && existsSync(start)) files.set(label(start) ?? start, fileHash(start));
+    return { files, scenes };
+  }
+  const listed = (m: Map<string, string>) => JSON.stringify([...m].sort((a, b) => (a[0] < b[0] ? -1 : 1)));
+
+  const base = walk(join(root, "main.ts")).files;
+  base.set("index.html", fileHash(join(root, "index.html")));
+  base.set("kf.json 화면 칸", sha(JSON.stringify(omit(kf, NOT_FRAMES))));
+  base.set("굽기 설정", sha(JSON.stringify([VERSION, o])));
+  const common = sha(listed(base));
+  const lines: Line[] = existsSync(capFile) ? JSON.parse(readFileSync(capFile, "utf8")) : [];
+  const assets = listFiles(join(root, "assets")).filter((f) => !AUDIO.test(f)).map((f) => ({ f, rel: relative(join(root, "assets"), f).split(sep).join("/") }));
+
+  const own = new Map<string, string>();
+  const inputs = new Map<string, Record<string, string>>();
+  const deps = new Map<string, Set<string>>();
+  for (const [i, s] of kf.scenes.entries()) {
+    const file = join(root, s.file ?? `scenes/${s.id}.ts`);
+    const w = walk(file);
+    // 자산은 장면이 글자로 적은 경로(프로젝트 안 소스) + 장면 id 로 시작하는 파일(gen/<id>.png·blender/<id>.mp4·seam/<id>-from.png)
+    const text = [...w.files.keys()].filter((n) => !n.startsWith("kf:")).map((n) => (existsSync(join(root, n)) ? readFileSync(join(root, n), "utf8") : "")).join("\n");
+    const used = assets
+      .filter(({ f, rel }) => text.includes(rel) || new RegExp(`^${s.id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([.\\-_]|$)`).test(f.split(sep).pop()!))
+      .map(({ f, rel }) => [rel, fileHash(f)]);
+    const cap = lines.filter((l) => l.scene === s.id || (l.scene === undefined && l.from !== undefined && l.from < s.from + s.dur && (l.to ?? l.from) >= s.from));
+    own.set(s.id, sha(common, listed(w.files), JSON.stringify(omit(s, new Set(["idea"]))), JSON.stringify(cap), JSON.stringify(used)));
+    inputs.set(s.id, {
+      ...Object.fromEntries(base),
+      ...Object.fromEntries(w.files),
+      "kf.json 장면 칸": sha(JSON.stringify(omit(s, new Set(["idea"])))),
+      "자막 줄": sha(JSON.stringify(cap)),
+      ...Object.fromEntries(used.map(([rel, h]) => [`assets/${rel}`, h])),
+    });
+    const d = new Set(s.role === "seam" ? [kf.scenes[i - 1]?.id, kf.scenes[i + 1]?.id].filter((x): x is string => !!x) : w.scenes);
+    deps.set(s.id, d);
+  }
+  // 경계 프레임에서 앞 장면이 아직 켜져 있으면(from+dur 이 다음 from 보다 끝자리만큼 큰 경우) 그 프레임은 두 장면이 겹쳐 그린다
+  const spans = sceneSpans(kf.scenes, o.fps, Math.round(Number(kf.duration) * o.fps));
+  for (const [i, sp] of spans.entries()) {
+    const prev = kf.scenes.find((s) => s.id === spans[i - 1]?.id);
+    if (prev && sp.start / o.fps < prev.from + prev.dur) deps.get(sp.id)!.add(prev.id);
+  }
+  return new Map(
+    kf.scenes.map((s) => {
+      const ds = [...deps.get(s.id)!].sort();
+      const key = sha(own.get(s.id)!, ...ds.map((d) => own.get(d) ?? d)).slice(0, 12);
+      return [s.id, { key, inputs: { ...inputs.get(s.id)!, ...Object.fromEntries(ds.map((d) => [`장면 ${d}`, own.get(d) ?? d])) } }];
+    }),
+  );
+}
+
+// 그 장면의 가장 최근 조각 기록(해시가 달라도) — 바뀐 재료와 장당 걸린 시간을 여기서 읽는다
+function lastRecord(root: string, id: string): Partial<SegmentReport> & { tabSeconds?: number } | null {
+  const dir = segmentDir(root);
+  if (!existsSync(dir)) return null;
+  const prev = readdirSync(dir)
+    .filter((f) => f.startsWith(`${id}-`) && f.endsWith(".json") && /^[0-9a-f]{12}$/.test(f.slice(id.length + 1, -5)))
+    .map((f) => join(dir, f))
+    .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0];
+  if (!prev) return null;
+  try {
+    return JSON.parse(readFileSync(prev, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** 같은 장면의 지난 조각 기록과 견줘 바뀐 재료 이름 — 「왜 다시 찍나」 */
+export function changedInputs(root: string, id: string, now: Record<string, string>): string[] | null {
+  const old = lastRecord(root, id)?.inputs;
+  if (!old) return null;
+  return [...new Set([...Object.keys(old), ...Object.keys(now)])].filter((k) => old[k] !== now[k]).sort();
+}
+
+export interface SegmentReport {
+  id: string;
+  key: string;
+  file: string;
+  frames: number;
+  seconds: number;
+  events: MotionEvent[];
+  inputs?: Record<string, string>;
+  /** 탭들이 이 장면을 찍는 데 쓴 초의 합 — 다음 굽기가 장면 무게를 어림한다 */
+  tabSeconds?: number;
+}
+
+export interface MotionEvent {
+  t: number;
+  kind: string;
+  source: string;
+  scene?: string;
+}
+
+export const segmentDir = (root: string) => join(root, "out", "segments");
+export const segmentFile = (root: string, id: string, key: string, ext: string) => join(segmentDir(root), `${id}-${key}${ext}`);
+
+/** 이미 구운 조각 — 영상과 기록(.json) 둘 다 있어야 다시 쓴다 */
+export function cachedSegment(root: string, id: string, key: string, ext: string): SegmentReport | null {
+  const file = segmentFile(root, id, key, ext);
+  const meta = segmentFile(root, id, key, ".json");
+  if (!existsSync(file) || !existsSync(meta)) return null;
+  try {
+    return { ...JSON.parse(readFileSync(meta, "utf8")), file };
+  } catch {
+    return null;
+  }
+}
+
+function split(start: number, end: number, n: number): [number, number][] {
+  const out: [number, number][] = [];
+  for (let i = 0; i < n; i++) {
+    const a = start + Math.floor(((end - start) * i) / n);
+    const b = start + Math.floor(((end - start) * (i + 1)) / n);
+    if (b > a) out.push([a, b]);
+  }
+  return out;
+}
+
+export interface SegmentWork {
+  span: SceneSpan;
+  key: string;
+  inputs?: Record<string, string>;
+}
+
+/**
+ * 고른 장면 조각을 탭 여러 개로 굽는다. 장면 하나가 길면 탭 몫으로 쪼개 찍고 그 장면 조각 하나로 잇는다(탭이 놀지 않게).
+ * 장면마다 「장면 <id>: 렌더」「장면 <id>: 구움」 줄을 찍는다 — 작업실이 타임라인 상태로 읽는다
+ */
+export async function renderSegments(o: {
+  session: Session;
+  root: string;
+  work: SegmentWork[];
+  tabs: number;
+  format: VideoFormat;
+  ext: string;
+  crf?: number;
+  blur: BlurOpts | null;
+  tmp: string;
+  onFrame?: () => void;
+}): Promise<SegmentReport[]> {
+  const { session: s, root } = o;
+  const { fps, width, height } = s.info.meta;
+  mkdirSync(segmentDir(root), { recursive: true });
+  mkdirSync(o.tmp, { recursive: true });
+  // 장면마다 장당 무게가 다르다(3D 이음매는 글 장면의 두 배 넘게) — 지난 기록으로 어림해 탭마다 두 몫쯤 되게 쪼개고
+  // 무거운 몫부터 나눠 준다. 기록이 없으면 장 수로 어림한다
+  const perFrame = new Map(o.work.map((w) => {
+    const r = lastRecord(root, w.span.id);
+    return [w.span.id, r?.frames ? (r.tabSeconds ?? r.seconds ?? 0) / r.frames : 0];
+  }));
+  const known = [...perFrame.values()].filter((x) => x > 0);
+  const guess = known.length ? known.reduce((a, b) => a + b, 0) / known.length : 1;
+  const cost = (w: SegmentWork) => (w.span.end - w.span.start) * (perFrame.get(w.span.id) || guess);
+  const unit = o.work.reduce((n, w) => n + cost(w), 0) / Math.max(1, o.tabs * 2);
+  const minFrames = Math.ceil(fps / 2);
+  const parts = o.work
+    .flatMap((w) => {
+      const frames = w.span.end - w.span.start;
+      const n = Math.max(1, Math.min(Math.round(cost(w) / unit), Math.floor(frames / minFrames)));
+      return split(w.span.start, w.span.end, n).map(([a, b], k) => ({ w, k, a, b, cost: (cost(w) * (b - a)) / frames }));
+    })
+    .sort((x, y) => y.cost - x.cost);
+  const busy = new Map<string, number>();
+  const left = new Map(o.work.map((w) => [w.span.id, parts.filter((p) => p.w === w).length]));
+  const started = new Map<string, number>();
+  const finished: Promise<void>[] = [];
+  const queue = [...parts];
+  const tabs: Tab[] = [];
+  const workers = Math.min(o.tabs, parts.length);
+
+  async function join1(w: SegmentWork): Promise<void> {
+    const n = parts.filter((p) => p.w === w).length;
+    const list = join(o.tmp, `${w.span.id}.txt`);
+    writeFileSync(list, Array.from({ length: n }, (_, k) => `file '${join(o.tmp, `${w.span.id}-${k}${o.ext}`).replace(/'/g, "'\\''")}'`).join("\n") + "\n");
+    const tmpOut = join(o.tmp, `${w.span.id}${o.ext}`);
+    await concat({ list, out: tmpOut, format: o.format, from: 0, dur: (w.span.end - w.span.start) / fps });
+    renameSync(tmpOut, segmentFile(root, w.span.id, w.key, o.ext));
+    console.error(`장면 ${w.span.id}: 구움 — ${w.span.end - w.span.start}장 ${((Date.now() - started.get(w.span.id)!) / 1000).toFixed(1)}초`);
+  }
+
+  await Promise.all(
+    Array.from({ length: workers }, async (_, i) => {
+      const tab = i === 0 ? s.first : await s.tab();
+      tabs.push(tab);
+      for (let p = queue.shift(); p; p = queue.shift()) {
+        if (!started.has(p.w.span.id)) {
+          started.set(p.w.span.id, Date.now());
+          const why = p.w.inputs && changedInputs(root, p.w.span.id, p.w.inputs);
+          console.error(`장면 ${p.w.span.id}: 렌더${why?.length ? ` — 바뀜: ${why.slice(0, 3).join(", ")}${why.length > 3 ? ` 외 ${why.length - 3}` : ""}` : ""}`);
+        }
+        const raw = o.blur ? { width, height } : undefined;
+        const t0 = Date.now();
+        const enc = encoder(join(o.tmp, `${p.w.span.id}-${p.k}${o.ext}`), fps, o.format, o.crf, raw);
+        for (let f = p.a; f < p.b; f++) {
+          if (o.blur) await enc.write((await captureBlurred(tab, s.info, f / fps, o.blur)).data);
+          else {
+            await tab.seek(f / fps);
+            await enc.write(await tab.capture());
+          }
+          o.onFrame?.();
+        }
+        await enc.end();
+        busy.set(p.w.span.id, (busy.get(p.w.span.id) ?? 0) + (Date.now() - t0) / 1000);
+        const rest = left.get(p.w.span.id)! - 1;
+        left.set(p.w.span.id, rest);
+        if (rest === 0) finished.push(join1(p.w));
+      }
+    }),
+  );
+  await Promise.all(finished);
+
+  // 움직임 기록은 탭에 쌓인다 — 장면 시각으로 갈라 조각마다 남긴다(검사가 영상 옆 .json 으로 센다)
+  const events = await collectEvents(tabs);
+  return o.work.map((w) => {
+    const from = w.span.start / fps;
+    const to = w.span.end / fps;
+    const rep: SegmentReport = {
+      id: w.span.id,
+      key: w.key,
+      file: segmentFile(root, w.span.id, w.key, o.ext),
+      frames: w.span.end - w.span.start,
+      seconds: Math.round((Date.now() - started.get(w.span.id)!) / 100) / 10,
+      events: events.filter((e) => e.t >= from - 1e-9 && e.t < to - 1e-9),
+      tabSeconds: Math.round((busy.get(w.span.id) ?? 0) * 10) / 10,
+      ...(w.inputs ? { inputs: w.inputs } : {}),
+    };
+    const { file: _f, ...meta } = rep;
+    writeFileSync(segmentFile(root, w.span.id, w.key, ".json"), JSON.stringify(meta));
+    return rep;
+  });
+}
+
+export async function collectEvents(tabs: Tab[]): Promise<MotionEvent[]> {
+  const seen = new Set<string>();
+  const out: MotionEvent[] = [];
+  for (const tab of tabs) {
+    const rows = await tab.page.evaluate(() => (window.__kf?.events ?? []) as unknown[]).catch(() => []);
+    for (const r of rows as MotionEvent[]) {
+      const key = `${r.t}|${r.kind}|${r.source}|${r.scene ?? ""}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(r);
+    }
+  }
+  return out.sort((a, b) => a.t - b.t);
+}
+
+/** 굽기 설정마다 지금 쓰는 조각을 적고, 어느 설정에서도 안 쓰는 옛 조각은 지운다(최근 설정 넷까지 둔다) */
+export function pruneSegments(root: string, variant: string, current: Record<string, string>): void {
+  const dir = segmentDir(root);
+  const indexFile = join(dir, "index.json");
+  let index: Record<string, { at: number; scenes: Record<string, string> }> = {};
+  try {
+    index = JSON.parse(readFileSync(indexFile, "utf8"));
+  } catch {}
+  index[variant] = { at: Date.now(), scenes: current };
+  const keep = Object.entries(index).sort((a, b) => b[1].at - a[1].at).slice(0, 4);
+  index = Object.fromEntries(keep);
+  writeFileSync(indexFile, JSON.stringify(index, null, 1));
+  const used = new Set(keep.flatMap(([, v]) => Object.entries(v.scenes).map(([id, key]) => `${id}-${key}`)));
+  for (const f of readdirSync(dir)) {
+    if (f === "index.json") continue;
+    if (!used.has(f.replace(/\.[^.]+$/, ""))) rmSync(join(dir, f), { force: true });
+  }
+}

package/packages/cli/src/vary.ts

@@ -0,0 +1,124 @@
+// kf theme vary — 세계 하나에서 변주를 뽑는다. 색 검사(대비·의미색·색각 이상)는 계산으로 먼저 거르고,
+// 남은 후보를 서로 먼 차례로 표준 장면에 입혀 kf check 와 칸 그림 차이까지 넘은 것만 themes/<세계>/variants/ 에 남긴다.
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cellPath, listVariants, loadTheme, themeDims, variantsDir, type Theme, type ThemeTags, type ThemeVary, type VariantManifest } from "@kasaframe/themes";
+import { candidateOf, mergeVariant, nameVariant, rankCandidates, variantTags } from "@kasaframe/themes/vary";
+import { checkProject, imageDiff, markCell, restyle, standardProject, still, thumb } from "./cells.ts";
+import { acquireRenderLock } from "./lock.ts";
+
+/** 세계가 vary 를 안 적었을 때 — 새 세계도 approved 가 되면 한 줄로 뽑히게, 세계 밝기·글꼴·질감은 그대로 두고 색만 돈다 */
+export const defaultVary = (t: Theme): ThemeVary => ({ scheme: [t.style.scheme], hue: [[0, 360]], chroma: [0.85, 1.15], tint: [0, 0.025], fonts: ["base"], texture: ["none"], tempo: [0.9, 1.15] });
+
+export const defaultTags = (t: Theme): ThemeTags => ({ mood: [], light: t.style.scheme, use: [...t.purposes], dims: themeDims(t) });
+
+// 칸 그림 평균 화소 차가 이 아래면 이미 뽑은 판과 같은 판으로 본다
+const SAME_LOOK = 0.035;
+
+export interface VaryResult {
+  made: VariantManifest[];
+  kept: number;
+  rejected: { id: string; why: string }[];
+}
+
+export async function vary(world: string, o: { n: number; force?: boolean; seed?: string; log: (l: string) => void }): Promise<VaryResult> {
+  const t = loadTheme(world);
+  if (t.variant) throw new Error(`${world} 는 변주다 — 세계 id 를 준다`);
+  if (t.status === "draft") throw new Error(`${world} 는 draft — review·approved 세계만 변주를 뽑는다`);
+  const spec = t.vary && Object.keys(t.vary).length ? t.vary : defaultVary(t);
+  if (spec !== t.vary) o.log(`${world}: theme.json 에 vary 가 없어 색만 도는 기본 범위로(밝기·글꼴·질감은 세계 그대로)`);
+  if (o.force) for (const v of listVariants(world)) unlinkSync(join(variantsDir(world), `${v.id}.json`));
+  const existing = listVariants(world);
+  const need = o.n - 1 - existing.length;
+  const result: VaryResult = { made: [], kept: existing.length, rejected: [] };
+  if (need <= 0) {
+    o.log(`${world}: 이미 변주 ${existing.length}개(기본 포함 ${existing.length + 1}) — 다시 뽑으려면 --force`);
+    return result;
+  }
+  const solid = themeDims(t) === "3D";
+  const tmp = mkdtempSync(join(tmpdir(), `kf-vary-${world}-`));
+  try {
+    // 세계 기본 판 — 표준 장면을 감독이 짓고 검사까지. 변주는 이 장면 파일 그대로 style 만 갈아 입는다
+    o.log(`${world}: 기본 판 표준 장면 짓는 중${solid ? "(입체 — 변주는 끝 구간만 검사)" : ""}`);
+    const base = join(tmp, "base");
+    let release = await acquireRenderLock(base, 900);
+    let b;
+    try {
+      b = standardProject(world, base, { check: true });
+      if (b.frame) still(base, b.frame.at, cellPath(world));
+    } finally {
+      release();
+    }
+    if (b.status !== 0 || !b.frame) throw new Error(`${world} 기본 판이 표준 장면 검사를 못 넘는다 — ${b.why}`);
+    markCell(t, b.frame);
+    const frame = b.frame;
+    const win = solid ? { from: +Math.max(0, frame.at - 0.8).toFixed(3), to: frame.dur } : undefined;
+
+    const shots = [thumb(cellPath(world)), ...existing.map((v) => cellPath(`${world}/${v.id}`)).filter(existsSync).map(thumb)];
+    const taken = new Set([...existing.map((v) => v.id), "base"]);
+    const ranked = rankCandidates(t.style, { vary: spec }, { seed: o.seed ?? world, taken: existing.map((v) => candidateOf(v.params, v.style, {})) });
+    o.log(`${world}: 색 검사를 넘은 후보 ${ranked.length}개 — 서로 먼 차례로 ${need}개를 굽는다`);
+    const today = new Date().toLocaleDateString("sv-SE");
+    mkdirSync(variantsDir(world), { recursive: true });
+    for (const c of ranked) {
+      if (result.made.length >= need || result.rejected.length >= need * 2) break;
+      const nm = nameVariant(c.params, taken, c.overlay.colors);
+      const id = `${world}/${nm.id}`;
+      const v: VariantManifest = {
+        id: nm.id,
+        world,
+        name: nm.name,
+        desc: nm.desc,
+        params: c.params,
+        style: c.overlay,
+        tags: variantTags(t.tags ?? defaultTags(t), c.params, c.overlay.colors),
+        check: { ok: false, at: today, colors: c.measured, frame: "", ...(frame.pattern ? { pattern: frame.pattern } : {}) },
+      };
+      const dir = join(tmp, nm.id);
+      restyle(base, dir, id, mergeVariant(t.style, v));
+      const png = join(dir, "cell.png");
+      release = await acquireRenderLock(dir, 900);
+      let verdict;
+      let shotBad: string | null;
+      try {
+        verdict = checkProject(dir, win);
+        shotBad = verdict.ok ? still(dir, frame.at, png) : null;
+      } finally {
+        release();
+      }
+      const reject = (why: string) => {
+        result.rejected.push({ id, why });
+        o.log(`  탈락 ${id} — ${why}`);
+      };
+      if (!verdict.ok) {
+        reject(verdict.errors.slice(0, 2).join(" · "));
+        continue;
+      }
+      if (shotBad) {
+        reject(`칸을 못 찍었다 — ${shotBad}`);
+        continue;
+      }
+      const th = thumb(png);
+      const near = Math.min(...shots.map((s) => imageDiff(s, th)));
+      if (near < SAME_LOOK) {
+        reject(`이미 뽑은 판과 거의 같다(화소 차 ${near.toFixed(3)})`);
+        continue;
+      }
+      v.check = { ...v.check, ok: true, frame: win ? `kf check 통과 — 끝 구간 ${win.from}–${win.to}초(입체라 가볍게)·끝 프레임 한 장` : `kf check 통과 — 표준 장면 0–${frame.dur}초` };
+      writeFileSync(join(variantsDir(world), `${nm.id}.json`), `${JSON.stringify(v, null, 2)}\n`);
+      mkdirSync(join(cellPath(id), ".."), { recursive: true });
+      copyFileSync(png, cellPath(id));
+      markCell(loadTheme(id), frame);
+      shots.push(th);
+      taken.add(nm.id);
+      result.made.push(v);
+      o.log(`  통과 ${id} — ${v.desc}`);
+      rmSync(dir, { recursive: true, force: true });
+    }
+    if (result.made.length < need) o.log(`${world}: ${need}개 중 ${result.made.length}개만 남았다 — 후보가 모자라면 vary 범위를 넓히거나 --seed 를 바꿔 다시`);
+    return result;
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}

package/packages/core/src/index.ts

@@ -24,4 +24,4 @@ export type { Style, CssStyle } from "./style.ts";
 export { setFrameTime, frameTime, onFrame, emit, motionEvents, resetMotionEvents, setFrameSample, frameSample } from "./frame.ts";
 export type { KfMotionEvent, MotionEventKind, FrameSample } from "./frame.ts";
 export { silentBeats, scaleOf, cssVars, fontCss } from "./project.ts";
-export type { KfMeta, KfStyle, MotionRules, SafeArea, SceneCtx, FontFace } from "./project.ts";
+export type { CaptionLook, KfMeta, KfStyle, MotionRules, SafeArea, SceneCtx, FontFace, StyleLook } from "./project.ts";

package/packages/core/src/project.ts

@@ -90,8 +90,33 @@ export interface KfStyle {
   radius: { sm: number; md: number; lg: number; pill: number };
   shadow: { soft: string; lift: string };
   motion: MotionRules;
+  /** 화면 자막 판 — 안 주면 화면 크기로 정한다(세로 폭의 8%·안전 영역 아래쪽·두 줄). srt·vtt 마디 나누기도 같은 값을 쓴다 */
+  captions?: CaptionLook;
   /** 디자인 출처·지킬 점 — 사람과 모델이 읽는다 */
   notes?: string[];
+  /** 테마 변주가 고른 겉모습 손잡이(SPEC 9 변주). 없으면 모두 기본(질감 없음·배수 1) */
+  look?: StyleLook;
+}
+
+/** 엔진·테마 코드가 읽는 겉모습 손잡이 — CSS 변수 --kf-stroke·--kf-tempo·--kf-density 로도 나간다 */
+export interface StyleLook {
+  /** 화면 전체에 얹는 정지 질감 — 엔진이 장면 위·자막 아래 한 겹으로 깐다 */
+  texture?: { kind: "none" | "grain" | "paper" | "noise" | "scan" | "halftone"; amount: number };
+  /** 선 굵기 배수 */
+  stroke?: number;
+  /** 움직임 빠르기 배수 — 1 보다 크면 빠르다 */
+  tempo?: number;
+  /** 장식·입자 밀도 배수 — 읽는 세계만 쓴다 */
+  density?: number;
+}
+
+export interface CaptionLook {
+  /** 글자 크기(px) — 틀의 text.minPx 아래로는 안 간다 */
+  size?: number;
+  /** 판 가운데의 y(px, 화면 위에서) — 안 주면 안전 영역 아래 가장자리에 붙인다 */
+  position?: number;
+  /** 한 마디가 차지할 줄 수(기본 2) — 넘치면 마디를 더 잘게 나눈다 */
+  maxLines?: number;
 }
 
 export interface SceneCtx {
@@ -129,6 +154,7 @@ export function cssVars(style: KfStyle, meta?: Pick<KfMeta, "width" | "height">)
   lines.push(`--kf-tracking: ${style.type.tracking};`);
   for (const [n, v] of Object.entries(style.radius)) lines.push(`--kf-radius-${n}: ${v}px;`);
   lines.push(`--kf-shadow-soft: ${style.shadow.soft};`, `--kf-shadow-lift: ${style.shadow.lift};`);
+  for (const k of ["stroke", "tempo", "density"] as const) lines.push(`--kf-${k}: ${style.look?.[k] ?? 1};`);
   return `:root {\n  ${lines.join("\n  ")}\n}`;
 }
 

package/packages/director/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@kasaframe/director",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./pattern": "./src/pattern.ts",
+    "./scene": "./src/scene.ts",
+    "./fallback": "./src/fallback.ts",
+    "./patterns/*": "./src/patterns/*.ts"
+  },
+  "dependencies": {
+    "@kasaframe/core": "0.0.0",
+    "@kasaframe/gen": "*",
+    "@kasaframe/motion": "^0.0.0",
+    "@kasaframe/plan": "*",
+    "@kasaframe/themes": "*"
+  },
+  "optionalDependencies": {
+    "@kasaframe/patterns": "*"
+  }
+}