kasaframe 0.0.0-stage → 0.1.1

package/packages/motion/src/type.ts

@@ -0,0 +1,131 @@
+import { rand, safeTime } from "@kasaframe/core";
+import { typingFrames } from "./hangul.ts";
+
+export interface TypeOpts {
+  /** 첫 키를 누르는 시각(초) */
+  at?: number;
+  /** 초당 키 수. 한글은 자모 하나가 키 하나 */
+  cps?: number;
+  /** 키 간격을 시드 난수로 ±비율만큼 흔든다 — 사람 손 같게. 0 이면 고르게 */
+  jitter?: number;
+  seed?: number | string;
+  /** 띄어쓰기·문장부호 뒤에 쉬는 배수 */
+  pause?: { space?: number; comma?: number; stop?: number; newline?: number };
+  ime?: boolean;
+  /** 커서 깜빡임 주기(초). 0 이면 늘 보인다 */
+  blink?: number;
+}
+
+export interface TypeState {
+  /** 지금 화면에 보일 글 — 언제나 문자열 */
+  text: string;
+  keys: number;
+  total: number;
+  done: boolean;
+  /** 0..1 */
+  p: number;
+  /** 커서를 그릴지 */
+  caret: boolean;
+  /** 마지막 키를 누른 뒤 지난 초 — 키 누름 튐 연출에 */
+  sinceKey: number;
+  /** 다 치는 데 걸리는 초 */
+  duration: number;
+}
+
+interface Plan {
+  frames: string[];
+  times: number[];
+  duration: number;
+}
+
+const cache = new Map<string, Plan>();
+
+function planOf(text: string, o: Required<Omit<TypeOpts, "at" | "blink">>): Plan {
+  const key = JSON.stringify([text, o.cps, o.jitter, o.seed, o.pause, o.ime]);
+  const hit = cache.get(key);
+  if (hit) return hit;
+  const frames = typingFrames(text, { ime: o.ime });
+  const base = 1 / Math.max(0.1, o.cps);
+  const times: number[] = [0];
+  let t = 0;
+  for (let k = 1; k < frames.length; k++) {
+    if (k > 1) {
+      const typed = frames[k - 1];
+      const last = typed.slice(-1);
+      let mul = 1;
+      if (last === "\n") mul = o.pause.newline ?? 6;
+      else if (/[.!?…。]/.test(last)) mul = o.pause.stop ?? 5;
+      else if (/[,、·:;]/.test(last)) mul = o.pause.comma ?? 3;
+      else if (last === " ") mul = o.pause.space ?? 1.6;
+      const j = o.jitter > 0 ? 1 + (rand(o.seed, k) * 2 - 1) * o.jitter : 1;
+      t += base * mul * j;
+    }
+    times.push(t);
+  }
+  const plan = { frames, times, duration: t };
+  if (cache.size > 256) cache.clear();
+  cache.set(key, plan);
+  return plan;
+}
+
+/** 첫 키 시각 at 부터 한 키씩 친다. times[k] 는 at 기준으로 k 번째 키를 누르는 때 */
+export function typeText(text: string, t: number, opts: TypeOpts = {}): TypeState {
+  t = safeTime(t);
+  // 글이 아닌 값이 오면 빈 글 — String(NaN)·String(undefined) 가 그대로 화면에 찍히던 사고를 막는다
+  const src = typeof text === "string" ? text : typeof text === "number" && Number.isFinite(text) ? String(text) : "";
+  const o = {
+    cps: opts.cps ?? 16,
+    jitter: opts.jitter ?? 0.35,
+    seed: opts.seed ?? src,
+    pause: opts.pause ?? {},
+    ime: opts.ime ?? true,
+  };
+  const plan = planOf(src, o);
+  const local = t - (opts.at ?? 0);
+  const total = plan.frames.length - 1;
+  let k = 0;
+  if (local >= 0) {
+    let lo = 1;
+    let hi = total;
+    k = 0;
+    while (lo <= hi) {
+      const mid = (lo + hi) >> 1;
+      if (plan.times[mid] <= local + 1e-9) {
+        k = mid;
+        lo = mid + 1;
+      } else hi = mid - 1;
+    }
+  }
+  const done = k >= total;
+  const sinceKey = k > 0 ? local - plan.times[k] : Math.max(0, local);
+  const blink = opts.blink ?? 1.06;
+  // 치는 동안은 켜 두고 멈춰 있을 때만 깜빡인다 — 칠 때 깜빡이면 글자가 끊겨 보인다
+  const phase = (x: number) => Number.isFinite(x) && ((x % blink) + blink) % blink < blink / 2;
+  const caret = blink <= 0 || (k > 0 && !done) || phase(done ? local - plan.duration : local);
+  return {
+    text: plan.frames[k] ?? "",
+    keys: k,
+    total,
+    done,
+    p: total === 0 ? 1 : k / total,
+    caret,
+    sinceKey,
+    duration: plan.duration,
+  };
+}
+
+/** 여러 줄을 차례로 — 앞 줄이 끝나고 gap 초 뒤에 다음 줄 */
+export function typeLines(lines: string[], t: number, opts: TypeOpts & { gap?: number } = {}): (TypeState & { line: number })[] {
+  t = safeTime(t);
+  const out: (TypeState & { line: number })[] = [];
+  let at = opts.at ?? 0;
+  for (let i = 0; i < lines.length; i++) {
+    const s = typeText(lines[i], t, { ...opts, at, seed: `${opts.seed ?? ""}${i}` });
+    out.push({ ...s, line: i });
+    at += s.duration + (opts.gap ?? 0.35);
+  }
+  return out;
+}
+
+/** 다 치는 데 걸리는 초 — 장면 길이를 맞출 때 */
+export const typeDuration = (text: string, opts: TypeOpts = {}): number => typeText(text, Infinity, opts).duration;

package/packages/motion/src/ui.ts

@@ -0,0 +1,172 @@
+import { progress, toEase, type Ease, type EaseName, safeTime } from "@kasaframe/core";
+import { typeText, type TypeOpts } from "./type.ts";
+
+export interface CursorKey {
+  /** 이 자리에 닿는 시각(초) */
+  t: number;
+  x: number;
+  y: number;
+  /** 닿은 뒤 누른다 */
+  click?: boolean;
+}
+
+export interface CursorState {
+  x: number;
+  y: number;
+  /** 누르고 있는 중 — 커서를 살짝 줄인다 */
+  pressed: boolean;
+  /** 누른 자리에서 퍼지는 물결. 없으면 null */
+  ripple: { x: number; y: number; scale: number; opacity: number } | null;
+}
+
+/** 키 사이를 감속 곡선으로 옮긴다. 사람 손처럼 살짝 휘게 가운데를 옆으로 민다 */
+export function cursor(t: number, keys: CursorKey[], opts: { ease?: EaseName | Ease; arc?: number; pressDur?: number } = {}): CursorState {
+  t = safeTime(t);
+  if (keys.length === 0) return { x: 0, y: 0, pressed: false, ripple: null };
+  const ks = keys.slice().sort((a, b) => a.t - b.t);
+  const ease = toEase(opts.ease, toEase("inOutCubic"));
+  let x = ks[0].x;
+  let y = ks[0].y;
+  for (let i = 1; i < ks.length; i++) {
+    const a = ks[i - 1];
+    const b = ks[i];
+    if (t <= a.t) break;
+    // 앞 키에서 누른 시간만큼 기다렸다가 떠난다
+    const leave = a.t + (a.click ? (opts.pressDur ?? 0.14) + 0.08 : 0);
+    const p = ease(progress(t, leave, Math.max(0.05, b.t - leave)));
+    const bend = Math.sin(Math.PI * p) * (opts.arc ?? 0.12);
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    x = a.x + dx * p - dy * bend;
+    y = a.y + dy * p + dx * bend;
+  }
+  const press = opts.pressDur ?? 0.14;
+  let pressed = false;
+  let ripple: CursorState["ripple"] = null;
+  for (const k of ks) {
+    if (!k.click) continue;
+    const d = t - k.t;
+    if (d >= 0 && d < press) pressed = true;
+    if (d >= 0 && d < 0.6) {
+      const q = toEase("outCubic")(d / 0.6);
+      ripple = { x: k.x, y: k.y, scale: 0.2 + q, opacity: (1 - q) * 0.6 };
+    }
+  }
+  return { x, y, pressed, ripple };
+}
+
+/** 막대·수치가 자란다. values 마다 stagger 만큼 늦게 */
+export function grow(t: number, values: number[], opts: { at?: number; dur?: number; stagger?: number; ease?: EaseName | Ease; from?: number } = {}): number[] {
+  t = safeTime(t);
+  const ease = toEase(opts.ease, toEase("outCubic"));
+  return values.map((v, i) => {
+    const target = Number.isFinite(v) ? v : 0;
+    const from = opts.from ?? 0;
+    return from + (target - from) * ease(progress(t, (opts.at ?? 0) + i * (opts.stagger ?? 0.08), opts.dur ?? 0.9));
+  });
+}
+
+/** 선 그리기 진행도 — SVG stroke-dashoffset = 길이 × (1 - p) */
+export const draw = (t: number, opts: { at?: number; dur?: number; ease?: EaseName | Ease } = {}): number =>
+  toEase(opts.ease, toEase("inOutCubic"))(progress(t, opts.at ?? 0, opts.dur ?? 1));
+
+export interface CodeState {
+  lines: string[];
+  /** 지금 쓰는 줄(강조용). 다 나왔으면 -1 */
+  active: number;
+  done: boolean;
+}
+
+/** 코드 블록 — 줄 단위로 나타나거나(line) 타자로 친다(type) */
+export function codeReveal(code: string, t: number, opts: { at?: number; mode?: "line" | "type"; lps?: number } & TypeOpts = {}): CodeState {
+  t = safeTime(t);
+  const src = typeof code === "string" ? code : "";
+  const all = src.split("\n");
+  if ((opts.mode ?? "line") === "type") {
+    const st = typeText(src, t, { cps: 40, jitter: 0.2, pause: { newline: 3 }, ...opts });
+    const lines = st.text.split("\n");
+    return { lines, active: st.done ? -1 : lines.length - 1, done: st.done };
+  }
+  const local = t - (opts.at ?? 0);
+  const n = local < 0 ? 0 : Math.min(all.length, Math.floor(local * (opts.lps ?? 8)) + 1);
+  return { lines: all.slice(0, n), active: n < all.length ? n - 1 : -1, done: n >= all.length };
+}
+
+export interface TermStep {
+  cmd: string;
+  /** 명령 뒤에 나오는 출력 줄 */
+  out?: string | string[];
+  prompt?: string;
+  /** 앞 단계가 끝나고 이 명령을 치기 전에 쉬는 초 */
+  wait?: number;
+}
+
+export interface TermLine {
+  kind: "cmd" | "out";
+  prompt: string;
+  text: string;
+  /** 커서가 이 줄 끝에 있다 */
+  caret: boolean;
+}
+
+export interface TermState {
+  lines: TermLine[];
+  done: boolean;
+  /** 마지막 키를 누른 뒤 지난 초 */
+  sinceKey: number;
+}
+
+/**
+ * 터미널 창 + 입력. 명령은 타자로, 출력은 outDelay 뒤 줄마다 lineDelay 간격으로 나온다.
+ * 아직 안 온 줄은 아예 만들지 않는다 — 빈 줄을 그려 두면 자리가 비어 보인다.
+ */
+export function terminal(
+  t: number,
+  steps: TermStep[],
+  opts: { at?: number; prompt?: string; outDelay?: number; lineDelay?: number; maxLines?: number } & TypeOpts = {},
+): TermState {
+  t = safeTime(t);
+  const lines: TermLine[] = [];
+  let at = opts.at ?? 0;
+  let sinceKey = Infinity;
+  let done = true;
+  for (let i = 0; i < steps.length; i++) {
+    const s = steps[i];
+    at += s.wait ?? (i === 0 ? 0 : 0.5);
+    if (t < at) {
+      done = false;
+      lines.push({ kind: "cmd", prompt: s.prompt ?? opts.prompt ?? "$", text: "", caret: true });
+      break;
+    }
+    const st = typeText(s.cmd, t, { ...opts, at, seed: `${opts.seed ?? "term"}${i}` });
+    lines.push({ kind: "cmd", prompt: s.prompt ?? opts.prompt ?? "$", text: st.text, caret: !st.done });
+    sinceKey = Math.min(sinceKey, st.sinceKey);
+    if (!st.done) {
+      done = false;
+      break;
+    }
+    at += st.duration + (opts.outDelay ?? 0.25);
+    const outs = s.out === undefined ? [] : Array.isArray(s.out) ? s.out : s.out.split("\n");
+    for (let j = 0; j < outs.length; j++) {
+      const show = at + j * (opts.lineDelay ?? 0.06);
+      if (t < show) {
+        done = false;
+        break;
+      }
+      lines.push({ kind: "out", prompt: "", text: typeof outs[j] === "string" ? outs[j] : "", caret: false });
+    }
+    if (!done) break;
+    at += outs.length * (opts.lineDelay ?? 0.06);
+  }
+  const last = lines[lines.length - 1];
+  if (done && last) lines.push({ kind: "cmd", prompt: opts.prompt ?? "$", text: "", caret: true });
+  const max = opts.maxLines ?? 0;
+  return { lines: max > 0 ? lines.slice(-max) : lines, done, sinceKey: Number.isFinite(sinceKey) ? sinceKey : 0 };
+}
+
+/** 문자열이 화면에 찍히기 전 마지막 거름 — 이상한 값이면 빈 글 */
+export function safeText(v: unknown): string {
+  if (typeof v === "string") return v;
+  if (typeof v === "number" && Number.isFinite(v)) return String(v);
+  return "";
+}

package/packages/plan/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@kasaframe/plan",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@kasaframe/core": "*",
+    "@kasaframe/gen": "*",
+    "@kasaframe/motion": "*",
+    "@kasaframe/themes": "*"
+  }
+}

package/packages/plan/src/brief.ts

@@ -0,0 +1,254 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { captionMode } from "@kasaframe/motion/captions";
+import { loadTheme } from "@kasaframe/themes";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repo = fileURLToPath(new URL("../../../", import.meta.url));
+
+export interface ProjectScene {
+  id: string;
+  from: number;
+  dur: number;
+  file: string;
+  role: string;
+  idea: string;
+  assets?: string[];
+}
+
+export interface ProjectFile {
+  template: string;
+  theme?: string;
+  title: string;
+  fps: number;
+  width: number;
+  height: number;
+  duration: number;
+  music: string | null;
+  beats: string | null;
+  captions: string;
+  safeArea: { top: number; bottom: number; left: number; right: number };
+  text: { policy: string; maxOnScreen: number; minPx: number };
+  scenes: ProjectScene[];
+}
+
+export function readProject(dir: string): ProjectFile {
+  return JSON.parse(readFileSync(join(dir, "kf.json"), "utf8"));
+}
+
+// 모델이 부품 이름을 지어내지 않게 실제로 내보낸 함수의 첫 줄(인자·반환 타입)만 모은다
+function signatures(pkg: string): string[] {
+  const src = join(repo, "packages", pkg, "src");
+  if (!existsSync(src)) return [];
+  const out: string[] = [];
+  for (const f of readdirSync(src).filter((x) => x.endsWith(".ts") && !x.endsWith(".test.ts") && x !== "index.ts" && x !== "captions.ts")) {
+    const text = readFileSync(join(src, f), "utf8");
+    for (const m of text.matchAll(/^export (?:function|const) (\w+)[^\n]*/gm)) {
+      const line = m[0].replace(/\s*\{\s*$/, "").replace(/^export (function|const) /, "");
+      if (line.length < 220) out.push(line);
+    }
+  }
+  return out;
+}
+
+const TEXT_POLICY: Record<string, string> = {
+  none: "화면에 문장을 쓰지 않는다. 기능 낱말 하나·제품 이름·끝 카드만.",
+  "terms-only": "화면 글은 전문 낱말과 숫자만(한 번에 몇 개까지). 말은 자막 트랙으로 따로 간다.",
+  captions: "소리 없이도 읽히게 — 들릴 말은 captions.json 에 쓰면 엔진이 화면 아래 자막 판에 얹는다. 장면 글은 핵심 낱말만.",
+  lyrics: "가사는 키네틱 타이포로 — 부른 낱말이 부른 시각에 뜨고, 뜻을 그림·움직임으로 받친다. 슬로건 금지는 가사에 걸지 않는다.",
+};
+
+function sceneBeats(dir: string, kf: ProjectFile, s: ProjectScene): string {
+  if (!kf.beats || !existsSync(join(dir, kf.beats))) return "곡 없음";
+  const b = JSON.parse(readFileSync(join(dir, kf.beats), "utf8"));
+  const inside = (xs: number[] = []) => xs.filter((t) => t >= s.from && t < s.from + s.dur).map((t) => +(t - s.from).toFixed(2));
+  const drops = inside(b.drops);
+  const bars = inside(b.bars ?? b.downbeats);
+  return `${b.bpm?.toFixed?.(1) ?? "?"} BPM · 장면 안 드롭 ${drops.length ? drops.join(", ") + "초" : "없음"} · 마디 ${bars.slice(0, 12).join(", ")}${bars.length > 12 ? " …" : ""}초`;
+}
+
+interface PurposeRules {
+  staticSec: { warn: number; error: number };
+  beatMove: "every-beat" | "drop-sections";
+  maxFreezeSec: number;
+}
+
+// 틀(templates/<용도>/template.json motion)이 기본값을 덮는다 — kf check 도 같은 값을 읽는다
+function purposeRules(id: string): PurposeRules {
+  const file = join(repo, "templates", id, "template.json");
+  const m = existsSync(file) ? (JSON.parse(readFileSync(file, "utf8")).motion ?? {}) : {};
+  return { staticSec: m.staticSec ?? { warn: 1.5, error: 3 }, beatMove: m.beatMove ?? "every-beat", maxFreezeSec: m.maxFreezeSec ?? 0.1 };
+}
+
+// 용도별 표 — 같은 값을 쓰는 틀끼리 한 줄로
+export function purposeTable(): string[] {
+  const dir = join(repo, "templates");
+  const ids = existsSync(dir) ? readdirSync(dir).filter((d) => existsSync(join(dir, d, "template.json"))) : [];
+  const groups = new Map<string, string[]>();
+  for (const id of ids) {
+    const r = purposeRules(id);
+    const key = `같은 구도 ${r.staticSec.warn}초 경고·${r.staticSec.error}초 오류 · 큰 움직임 ${r.beatMove === "every-beat" ? "박마다" : "후렴·드롭 구간만(벌스는 화면 안 움직임으로 충분)"} · 정지 ${r.maxFreezeSec}초 금지`;
+    groups.set(key, [...(groups.get(key) ?? []), id]);
+  }
+  return [...groups].map(([k, v]) => `- ${v.join("·")}: ${k}`);
+}
+
+function dropSections(dir: string, kf: ProjectFile): string {
+  if (!kf.beats || !existsSync(join(dir, kf.beats))) return "곡이 없어 드롭 구간도 없다 — 화면 안 움직임으로 간다";
+  const b = JSON.parse(readFileSync(join(dir, kf.beats), "utf8"));
+  const secs: { t: number; kind: string }[] = b.sections ?? [];
+  const spans: { t: number; to: number }[] = [];
+  secs.forEach((x, i) => {
+    if (x.kind !== "drop") return;
+    const to = secs[i + 1]?.t ?? kf.duration;
+    const last = spans[spans.length - 1];
+    if (last && Math.abs(last.to - x.t) < 0.05) last.to = to;
+    else spans.push({ t: x.t, to });
+  });
+  return spans.length ? spans.map((x) => `${x.t.toFixed(2)}–${x.to.toFixed(2)}초`).join(", ") : "드롭 구간이 잡히지 않았다";
+}
+
+// 장면을 채우는 모델(Claude Code 든 OG 의 아무 모델이든)이 읽는 한 장. 사용서(docs/AGENTS.md)가 있으면 뒤에 붙인다
+export function projectBrief(dir: string): string {
+  const kf = readProject(dir);
+  const style = JSON.parse(readFileSync(join(dir, "style.json"), "utf8"));
+  const plan = existsSync(join(dir, "plan.json")) ? JSON.parse(readFileSync(join(dir, "plan.json"), "utf8")) : {};
+  const rules = purposeRules(kf.template);
+  const tplFile = join(repo, "templates", kf.template, "template.json");
+  const tplMotion = existsSync(tplFile) ? (JSON.parse(readFileSync(tplFile, "utf8")).motion ?? {}) : {};
+  const colors = Object.keys(style.colors ?? {}).map((k: string) => `--kf-${k.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`);
+  const core = signatures("core");
+  const motion = signatures("motion");
+  const agents = join(repo, "docs", "AGENTS.md");
+  const lines = [
+    `# ${kf.title || plan.request || "kasaframe 프로젝트"} — 장면 작성 지시서`,
+    "",
+    `**이 영상의 규칙 — 용도 ${kf.template}(틀이 기본값을 덮는다, kf check 가 같은 값으로 잡는다)**`,
+    `1. 화면은 ${rules.maxFreezeSec}초(60fps 6프레임) 넘게 멈추지 않는다 — 끝 카드·큰 숫자·로고도 예외 없이 화면 안 움직임(숫자 굴러가기·칸 채우기·반짝임·글자 흐름·바탕 흐름)으로 계속 살아 있게.`,
+    `2. 같은 구도는 ${rules.staticSec.warn}초 넘기지 않는다(${rules.staticSec.error}초 넘으면 오류) — 새 요소·칸 채우기·숫자 키우기·컷·전환으로 바꾼다.`,
+    rules.beatMove === "every-beat"
+      ? "3. 미세하게 흔들리는 것만으로 때우지 않는다 — 눈에 보이는 큰 움직임이 박마다 하나 이상."
+      : `3. 눈에 보이는 큰 움직임을 박마다 요구하는 건 후렴·드롭 구간(beats.json sections 의 drop — ${dropSections(dir, kf)})뿐이다. 벌스·브레이크는 화면 안 움직임(가사·숫자·바탕 흐름)으로 충분하다 — 절제했다가 드롭에서 터뜨린다.`,
+    "4. **카메라는 이유가 있을 때만** 움직인다 — 기본은 정지, 주인공은 안전 영역 가운데. 드러냄에 다가가기(`stage.camera.pushIn`)·비교에 물러나기(`pullOut`)·주인공 따라가기(`follow`)·드롭에 한 번 툭(`impact`), 끝나면 선다. 화면 전체를 사인으로 흔들거나 박마다 자세를 바꾸지 않는다(kf check `camera.wander`·`layout.edge`). 회전·원근 기울기는 0.",
+    "5. **섬광은 1초에 3번까지**(kf check frame.flash — 빛 민감 발작). 화면 25% 넘게 번쩍이는 건 두 박·한 마디에 한 번, 빨강 전체 깜빡임·대비 큰 줄무늬 연타·어둠↔흰 화면 컷 이어 붙이기는 쓰지 않는다.",
+    "",
+    "용도별 기본값(templates/<용도>/template.json motion):",
+    ...purposeTable(),
+    "",
+    "그림 보기: `npx kf look <폴더>` 가 찍는 장면 모음(out/look-sheet.png)을 Read 로 직접 보고 장면별 확인표(out/look.md)대로 고친다. **Read 로 그림이 안 보이면(눈 없는 모델)만** `npx kf look <폴더> --vision-model google/gemini-3.5-flash [--ask \"<볼 것>\"]` — 그림 보는 모델이 장면마다 글로 알려 준다.",
+    "",
+    `요청: ${plan.request ?? "(없음)"}`,
+    `용도 ${kf.template} · ${kf.width}×${kf.height} · ${kf.fps}fps · ${kf.duration}초 · 스타일 ${style.name}(${style.scheme}) · 곡 ${kf.music ?? "없음"} · 자막 ${kf.captions}`,
+    `안전 영역(글은 이 안에): 위 ${kf.safeArea.top}px · 아래 ${kf.safeArea.bottom}px · 왼쪽 ${kf.safeArea.left}px · 오른쪽 ${kf.safeArea.right}px`,
+    `화면 글: ${TEXT_POLICY[kf.text?.policy] ?? kf.text?.policy} 글자 크기 최소 ${kf.text?.minPx}px.`,
+    `움직임 규칙(style.json motion 위에 틀 motion): ${JSON.stringify({ ...style.motion, ...tplMotion })}`,
+    ...(style.notes?.length ? ["디자인 메모: " + style.notes.join(" / ")] : []),
+    "",
+    "## 장면 파일 꼴 — 이 꼴만 쓴다",
+    "",
+    "```ts",
+    'import { applyStyle, clip, ease, type SceneCtx } from "@kasaframe/core";',
+    "export default {",
+    "  build(root: HTMLElement, ctx: SceneCtx) {",
+    "    const box = document.createElement(\"div\"); // root.style.display 는 엔진이 켜고 끈다 — 배치는 box 에",
+    "    box.style.cssText = \"position:absolute;inset:0;overflow:hidden;background:var(--kf-bg)\";",
+    "    root.append(box);",
+    "    // DOM 은 여기서 한 번만 짓는다",
+    "    return (t: number) => { /* t = 장면 안 초(0..ctx.dur). 같은 t 면 같은 화면 */ };",
+    "  },",
+    "};",
+    "```",
+    "",
+    "- 시각 함수 밖에서 상태를 쌓지 않는다(앞 프레임 값을 기억하지 않는다). 탭 여러 개가 아무 시각이나 찍는다.",
+    "- `Math.random`·`Date.now`·`performance.now`·`setTimeout` 금지 — 난수는 `rand(seed, i)`, 시간은 `t` 만.",
+    "- 글자에 `undefined`·`NaN`·`null` 이 찍히지 않게 값은 미리 문자열로 만든다. 이모지 금지(아이콘은 인라인 SVG).",
+    "- 장면이 1초 넘게 멈추지 않게 한다(아주 느린 다가가기라도). 빈 화면으로 시작·끝내지 않는다.",
+    "- **화면을 채운다**(kf check layout.fill): 주 요소가 안전 영역을 크게 차지한다 — 세로 화면은 폭의 70% 넘게, 글은 큰 글자 단계(hero·title)로. 가운데 작은 그림 하나에 나머지가 흰 여백이면 실패다.",
+    "- 구도 판정(kf check layout.static)은 칸 평균 밝기와 화면 안 내용(글·칸의 센 가장자리)으로 본다 — 숫자가 구르고 칸이 차면 바뀐 것이고, 부드럽게 흐르는 바탕만으로는 안 바뀐다. 카메라 샷으로 메우지 않는다.",
+    "- `../lib/stage.ts` 의 `makeStage(root, ctx)`(늘 흐르는 빛 방울 바탕·컷마다 모양을 바꾸는 바탕 판·정지 카메라 `stage.camera`)·`makeCamera(layer, ctx, { frame })`(자기 카메라 층에)·`bigWord`·`fitPx`·`cutTimes`·`lastT` 를 써도 된다 — 위 규칙을 처음부터 넘게 짜 둔 도구다. 카메라가 요소를 겨누면 `stage.tick(t)` 은 내용을 칠한 뒤 맨 끝에.",
+    "- 박에 붙이는 움직임은 `ctx.beats`(장면 시작 0 기준: `ctx.beats.drops`, `ctx.beats.nearestBeat(t)`, `ctx.beats.pulse(t, {...})`). 시각을 BPM 으로 곱해 만들지 않는다.",
+    "- 자산은 `ctx.asset(\"gen/<id>.png\")` 처럼 assets/ 기준 경로로. 없는 파일을 가리키지 않는다.",
+    "- 색·글꼴·크기는 CSS 변수로: " + [...colors, "--kf-font-sans", "--kf-font-display", "--kf-font-mono", "--kf-size-hero", "--kf-size-title", "--kf-size-body", "--kf-size-caption", "--kf-radius-md", "--kf-shadow-soft"].join(" "),
+    "",
+    "## 쓸 수 있는 함수",
+    "",
+    "`@kasaframe/core`:",
+    ...core.map((s) => `- ${s}`),
+    "",
+    ...(motion.length ? ["`@kasaframe/motion`(움직임 부품 — 숫자만 넣으면 Style 이나 상태를 돌려준다. applyStyle 로 붙인다):", ...motion.map((s) => `- ${s}`), ""] : []),
+    "## 장면",
+    "",
+    ...kf.scenes.flatMap((s) => [
+      `### ${s.id} — ${s.file} (${s.from.toFixed(2)}–${(s.from + s.dur).toFixed(2)}초, ${s.dur.toFixed(2)}초, 역할 ${s.role})`,
+      `- 할 일: ${s.idea}`,
+      ...(s.role === "seam" ? ["- 이 장면 파일은 고치지 않는다 — 3D 전환(transition3d)이 앞뒤 화면을 이어 준다"] : []),
+      `- 박: ${sceneBeats(dir, kf, s)}`,
+      ...(s.assets?.length ? [`- 자산: ${s.assets.map((a) => a.replace(/^gen:(img|vid):(.+)$/, (_, k, id) => `assets/gen/${id}.${k === "img" ? "png" : "mp4"}`)).join(", ")}`] : []),
+      "",
+    ]),
+    ...genSection(dir, kf, plan),
+    ...themeSection(kf.theme, plan),
+    ...(existsSync(join(dir, "lyrics.json"))
+      ? ["## 가사(lyrics.json — 낱말 시각까지)", "", '`import.meta.glob("../lyrics.json", { eager: true, import: "default" })` 로 읽는다(꼴 `{ lines: [{ text, start, end, words?: [{ w, start, end }] }] }`, 시각은 영상 전체 기준 초 — 장면 안 시각은 `start - ctx.from`). 낱말이 없으면 줄을 글자 수 비율로 나눈다.', ""]
+      : []),
+    ...(existsSync(join(dir, "assets", "in"))
+      ? ["## 받은 자산(사람이 준 것 — 쓸 수 있으면 쓴다)", "", ...readdirSync(join(dir, "assets", "in")).map((f) => `- \`ctx.asset("in/${f}")\``), ""]
+      : []),
+    ...(captionMode(kf.captions) !== "none"
+      ? [
+          "## 자막",
+          "",
+          '들릴 말은 프로젝트 `captions.json` 에 `[{"scene": "장면 id", "text": "짧은 마디를 쉼표로"}]` 로 쓴다 — `kf make --finish` 가 out/captions.ko.srt·vtt 로 만든다. 장면 파일에는 문장을 쓰지 않는다.',
+          captionMode(kf.captions) === "on"
+            ? `이 영상은 자막을 화면에도 얹는다 — 엔진이 장면 위에 판을 깐다(안전 영역 아래쪽 가운데, 두 줄까지). 그 자리(아래 가장자리에서 ${kf.safeArea.bottom}px 위 언저리)에 장면의 큰 글을 두지 않는다.`
+            : "화면에는 얹지 않는다(kf render --captions on 이면 그 판만 얹는다).",
+          "",
+        ]
+      : []),
+    ...(existsSync(agents) ? ["## 사용서(docs/AGENTS.md)", "", readFileSync(agents, "utf8")] : []),
+  ];
+  return lines.join("\n");
+}
+
+// 테마를 골랐으면 그 비유·금지·효과 쓰는 꼴을 그대로 싣는다(SPEC 9). auto 인데 맞는 테마가 없으면 강한 모델이 새 테마를 draft 로 써 넣을 수 있다
+function themeSection(id: string | undefined, plan: { themeCandidates?: { id: string; why: string }[]; request?: string }): string[] {
+  if (id) {
+    const t = loadTheme(id);
+    const pick = plan.themeCandidates?.find((c) => c.id === id);
+    return [
+      `## 테마 ${t.name}(${t.id}) — ${t.metaphor}`,
+      "",
+      ...(pick ? [`고른 이유: ${pick.why}`, ""] : []),
+      `효과는 복사하지 말고 가져다 쓴다: \`import { fx } from "@kasaframe/themes/fx"; const { ${t.effects.map((e) => e.name).join(", ")} } = fx("${t.id}");\``,
+      "",
+      ...t.effects.map((e) => `- \`${e.name}\`(${e.kind}) — ${e.does} · \`${e.use}\``),
+      "",
+      ...(plan.themeCandidates && plan.themeCandidates.length > 1 ? [`다른 후보: ${plan.themeCandidates.slice(1).map((c) => c.id).join(" · ")} — 첫 장면을 각 테마로 찍은 그림은 out/theme-<id>.png`, ""] : []),
+      t.guide,
+      "",
+    ];
+  }
+  if (plan.themeCandidates && !plan.themeCandidates.length) {
+    return [
+      "## 테마 — 맞는 approved 테마가 없다",
+      "",
+      "프리셋 style 로 간다. 이 내용에 맞는 비유가 뚜렷하면 SPEC 계약 9 대로 `themes/<새 id>/` 에 테마 팩(theme.json status draft · THEME.md · style.json · effects.ts 5–10개)을 써 넣어도 된다 — 사람이 견본을 보고 OK 하기 전까지는 draft 라 이 프로젝트에는 쓰지 않는다.",
+      "",
+    ];
+  }
+  return [];
+}
+
+// 그림 생성은 돈이 들고, 막연한 자동 프롬프트는 엉뚱한 그림을 냈다 — 아직 없는 그림은 목록으로만 내고 세션이 프롬프트를 써서 만든다
+function genSection(dir: string, kf: ProjectFile, plan: { gen?: { id: string; kind: string; scene?: string; prompt: string; size?: string }[] }): string[] {
+  const todo = (plan.gen ?? []).filter((g) => g.kind === "img" && !existsSync(join(dir, "assets", "gen", `${g.id}.png`)));
+  if (!todo.length) return [];
+  return [
+    "## 만들 그림 — 아직 안 만들었다(묻지 않고 돈을 쓰지 않는다)",
+    "",
+    "받은 자산·실제 화면 오리기·도형으로 되면 만들지 않는다. 만들 땐 요청 내용으로 **구체적인** 프롬프트를 써서(무엇이·어떤 구도로·어떤 색·글자 없음):",
+    "",
+    ...todo.map((g) => `- \`${g.id}\`(장면 ${g.scene ?? "-"}) — 틀이 제안한 뜻: ${g.prompt}\n  \`npx kf gen img "<구체적 프롬프트>" --id ${g.id} --size ${g.size ?? `${kf.width}x${kf.height}`} --project ${dir}\` → \`ctx.asset("gen/${g.id}.png")\``),
+    "",
+  ];
+}

package/packages/plan/src/captions.ts

@@ -0,0 +1,75 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { captionMetrics, captionMode, toCues, type CaptionLine, type CaptionMode, type Cue } from "@kasaframe/motion/captions";
+import { readProject } from "./brief.ts";
+
+// 자막 트랙 — srt(유튜브)·vtt(사이트). OG 쇼츠 scripts/srt3d.py 의 관례를 따른다.
+// 마디 나누기는 화면 자막 판(@kasaframe/motion/captions)과 같은 toCues 라 트랙과 화면이 한 마디도 어긋나지 않는다.
+
+export { toCues };
+export type { CaptionLine, Cue };
+
+function ts(s: number, sep: string): string {
+  const ms = Math.round(s * 1000);
+  const p = (n: number, w = 2) => String(n).padStart(w, "0");
+  return `${p(Math.floor(ms / 3600000))}:${p(Math.floor(ms / 60000) % 60)}:${p(Math.floor(ms / 1000) % 60)}${sep}${p(ms % 1000, 3)}`;
+}
+
+export function srt(cues: Cue[]): string {
+  return cues.map((c, i) => `${i + 1}\n${ts(c.from, ",")} --> ${ts(c.to, ",")}\n${c.text}\n`).join("\n");
+}
+
+export function vtt(cues: Cue[]): string {
+  return `WEBVTT\n\n${cues.map((c) => `${ts(c.from, ".")} --> ${ts(c.to, ".")}\n${c.text}\n`).join("\n")}`;
+}
+
+// 뮤비 가사. 시각이 붙은 lyrics.json(natsu_mv align_lyrics.py 꼴: {lines:[{text,start,end}]})이 있으면 그대로,
+// 시각 없는 lyrics.txt 뿐이면 인트로·아웃트로를 뺀 구간에 줄 길이 비율로 대충 편다 — 정확한 시각은 보컬 분리(demucs) + 강제 정렬로(큰 모델이라 GPU 있는 기계에서)
+function lyricLines(dir: string, scenes: { id: string; role: string; from: number; dur: number }[]): CaptionLine[] | null {
+  const find = (f: string) => [join(dir, f), join(dir, "assets", "in", f)].find((p) => existsSync(p));
+  const timed = find("lyrics.json");
+  if (timed) {
+    const j = JSON.parse(readFileSync(timed, "utf8")) as { lines?: { text: string; start: number; end: number; words?: { w: string; start: number; end: number }[] }[] };
+    return (j.lines ?? []).map((l) => ({ from: l.start, to: l.end, text: l.text, words: l.words?.map((w) => ({ text: w.w, from: w.start, to: w.end })) }));
+  }
+  const plain = find("lyrics.txt");
+  if (!plain) return null;
+  const lines = readFileSync(plain, "utf8").split("\n").map((l) => l.trim()).filter(Boolean);
+  const sung = scenes.filter((s) => !/intro|outro/.test(s.role));
+  const total = sung.reduce((a, s) => a + s.dur, 0);
+  const chars = lines.reduce((a, l) => a + l.length, 0);
+  const out: CaptionLine[] = [];
+  let k = 0;
+  let acc = 0;
+  for (const l of lines) {
+    let at = (acc / chars) * total;
+    while (k < sung.length - 1 && at > sung[k].dur) {
+      at -= sung[k].dur;
+      acc -= (sung[k].dur / total) * chars;
+      k++;
+    }
+    const from = sung[k].from + at;
+    out.push({ from, to: from + (l.length / chars) * total, text: l });
+    acc += l.length;
+  }
+  return out;
+}
+
+// 프로젝트의 captions.json(또는 가사) → out/captions.ko.srt·vtt. 자막 none 이거나 들릴 말이 없으면 빈 배열. mode 는 kf.json 을 그 판만 덮는다
+export function writeCaptions(dir: string, mode?: CaptionMode): string[] {
+  const kf = readProject(dir);
+  // captions 칸이 없는 옛 프로젝트는 들릴 말이 있으면 트랙만 낸다
+  if ((mode ?? (kf.captions === undefined ? "off" : captionMode(kf.captions))) === "none") return [];
+  const scenes = kf.scenes;
+  const file = join(dir, "captions.json");
+  const lines = existsSync(file) ? (JSON.parse(readFileSync(file, "utf8")) as CaptionLine[]) : lyricLines(dir, scenes);
+  if (!lines) return [];
+  const maxEm = kf.width && kf.height ? captionMetrics({ width: kf.width, height: kf.height, safe: kf.safeArea, minPx: kf.text?.minPx }).maxEm : undefined;
+  const cues = toCues(lines, scenes, { maxEm, duration: kf.duration });
+  if (!cues.length) return [];
+  mkdirSync(join(dir, "out"), { recursive: true });
+  const out = [join(dir, "out", "captions.ko.srt"), join(dir, "out", "captions.ko.vtt")];
+  writeFileSync(out[0], srt(cues));
+  writeFileSync(out[1], vtt(cues));
+  return out;
+}