kasaframe 0.1.1 → 0.1.4

package/packages/director/src/content.ts

@@ -0,0 +1,343 @@
+// content.json — LLM 이 정하는 것은 「무엇을 보일지」뿐이다(장면마다 type·필드·들릴 말·출처). 화면 문법·움직임·전환·카메라는 감독이 고른다.
+// 모델마다 버릇이 달라 칸 이름·숫자 쓰는 법이 흔들린다 — 별칭·「9.2 GB」 같은 붙여 쓴 숫자는 여기서 정규화하고, 고친 것은 경고로 남긴다.
+
+export const SCENE_TYPES = [
+  "hook-number",
+  "compare",
+  "bars",
+  "steps",
+  "before-after",
+  "timeline",
+  "flow",
+  "fill",
+  "formula",
+  "term-reveal",
+  "limit",
+  "toggle-sim",
+  "list",
+  "quote",
+  "end",
+  "title",
+  "words",
+  "trend",
+  "code",
+  "screen",
+  "media",
+  "custom",
+] as const;
+export type SceneType = (typeof SCENE_TYPES)[number];
+
+export const TYPE_ALIASES: Readonly<Record<string, SceneType>> = {
+  stat: "hook-number",
+  number: "hook-number",
+  ranking: "bars",
+  features: "list",
+  term: "term-reveal",
+  "before/after": "before-after",
+  toggle: "toggle-sim",
+};
+
+type Field =
+  | { kind: "string" | "number" | "int" | "boolean" | "source" | "box"; need?: boolean; doc: string }
+  | { kind: "enum"; values: string[]; need?: boolean; doc: string }
+  | { kind: "strings"; need?: boolean; min?: number; max?: number; doc: string }
+  | { kind: "object"; need?: boolean; of: Record<string, Field>; doc: string }
+  | { kind: "list"; need?: boolean; min?: number; max?: number; of: Record<string, Field>; doc: string; shorthand?: string };
+
+const s = (doc: string, need = false): Field => ({ kind: "string", need, doc });
+const n = (doc: string, need = false): Field => ({ kind: "number", need, doc });
+const side = (doc: string): Field => ({ kind: "object", need: true, doc, of: { label: s("이름", true), value: n("값"), unit: s("단위"), note: s("짧은 덧말") } });
+
+export interface TypeSpec {
+  does: string;
+  fields: Record<string, Field>;
+  /** 숫자를 보이는 type — source 가 없으면 경고 */
+  numbers?: boolean;
+}
+
+/** 모든 type 이 같이 갖는 칸 */
+export const COMMON: Record<string, Field> = {
+  id: s("장면 id(영문 소문자·숫자·-). 없으면 <type>-<n>"),
+  type: s("아래 type 하나", true),
+  say: s("이 장면에서 들릴 말(내레이션·자막) — 화면 글이 아니다. 차분한 설명체, 마디는 쉼표, 1초에 4–5글자"),
+  source: { kind: "source", doc: "사실 출처(주소·문서 이름) — 숫자를 보이는 type 은 꼭" },
+  emphasis: s("강조색을 받을 낱말 하나(필드 값 안에 있는 것)"),
+  dur: n("초 — say 가 없을 때만 쓴다(있으면 목소리가 길이를 정한다)"),
+  space: { kind: "enum", values: ["2d", "3d"], doc: "3d 면 3D 샷 장면(Blender·three) — 2D 장면과의 경계엔 감독이 공간 잇기 전환을 넣는다" },
+};
+
+export const TYPES: Readonly<Record<SceneType, TypeSpec>> = {
+  "hook-number": { does: "큰 숫자 하나 — 훅·결과", numbers: true, fields: { value: n("숫자", true), unit: s("단위(×·GB·%)"), label: s("무엇의 숫자인가", true), from: n("굴러 오르기 시작 값(기본 0)"), decimals: { kind: "int", doc: "소수 자리" }, prefix: s("숫자 앞 글(1/ 같은)") } },
+  compare: { does: "둘 대비 — A 대 B", numbers: true, fields: { a: side("왼쪽(앞)"), b: side("오른쪽(뒤)"), better: { kind: "enum", values: ["lower", "higher"], doc: "어느 쪽이 나은가" }, ratio: s("배율 글(×57)") } },
+  bars: { does: "여러 값 막대·순위", numbers: true, fields: { items: { kind: "list", need: true, min: 2, max: 8, doc: "막대", of: { label: s("이름", true), value: n("값", true), unit: s("단위") } }, unit: s("공통 단위"), highlight: s("강조할 막대 label") } },
+  steps: { does: "순서가 있는 과정", fields: { steps: { kind: "list", need: true, min: 2, max: 6, doc: "단계", shorthand: "label", of: { label: s("단계 이름", true), detail: s("덧말") } } } },
+  "before-after": { does: "같은 것의 전후 변화", numbers: true, fields: { before: side("전"), after: side("후"), change: s("바뀐 정도 글(-98%·57배 작게)"), better: { kind: "enum", values: ["lower", "higher"], doc: "어느 쪽이 나은가" } } },
+  timeline: {
+    does: "시간 축 위 표시 — 하루 24시·연표",
+    fields: {
+      span: { kind: "object", doc: "축 범위(기본 marks 의 최소–최대)", of: { from: n("시작", true), to: n("끝", true), unit: s("단위(시·년)") } },
+      marks: { kind: "list", need: true, min: 1, max: 8, doc: "표시", of: { at: n("축 위 자리", true), label: s("딱지", true), hot: { kind: "boolean", doc: "강조" } } },
+      window: { kind: "object", doc: "칠할 구간", of: { from: n("시작", true), to: n("끝", true), label: s("구간 이름", true) } },
+    },
+  },
+  flow: {
+    does: "구조 — 무엇이 무엇으로 흐르나",
+    fields: {
+      nodes: { kind: "list", need: true, min: 2, max: 8, doc: "상자", of: { id: s("노드 id", true), label: s("이름", true), group: s("묶음") } },
+      edges: { kind: "list", min: 1, max: 12, doc: "연결(없으면 nodes 차례로)", of: { from: s("노드 id", true), to: s("노드 id", true), label: s("딱지") } },
+    },
+  },
+  fill: { does: "칸이 차고 빈다 — GPU 자리·메모리·대기열", numbers: true, fields: { total: { kind: "int", need: true, doc: "칸 수(2–400)" }, filled: { kind: "int", need: true, doc: "찬 칸 수" }, from: { kind: "int", doc: "처음 찬 칸 수(기본 0)" }, label: s("무엇의 칸인가", true), unit: s("칸 단위(자리·GB)") } },
+  formula: { does: "식이 한 항씩 선다", fields: { parts: { kind: "list", need: true, min: 2, max: 9, doc: "항 차례 — 문자열 하나(\"KV = 2 × L × d\")도 받는다", shorthand: "text", of: { text: s("항", true), kind: { kind: "enum", values: ["term", "op", "value", "result"], doc: "항 종류(없으면 감독이 어림)" } } }, label: s("식 이름") } },
+  "term-reveal": { does: "용어 공개·약자 풀이", fields: { term: s("용어", true), full: s("풀어 쓴 이름"), ko: s("한국어 이름"), meaning: s("뜻 한 줄(글 정책이 terms-only 면 화면에 안 쓴다)") } },
+  limit: { does: "남는 한계·대가 한 가지", fields: { label: s("한계", true), value: n("숫자"), unit: s("단위"), cost: s("치르는 것 한 낱말") } },
+  "toggle-sim": { does: "스위치를 바꾸면 결과가 바뀐다 — 평일/주말·켬/끔", fields: { knob: s("무엇을 바꾸나", true), states: { kind: "list", need: true, min: 2, max: 3, doc: "상태", of: { label: s("상태 이름", true), value: n("그때 값"), unit: s("단위"), note: s("덧말") } } } },
+  list: { does: "낱말 둘에서 다섯 — 기능·장점", fields: { items: { kind: "list", need: true, min: 2, max: 5, doc: "낱말", shorthand: "word", of: { word: s("낱말", true), line: s("덧말"), icon: s("아이콘 이름") } }, title: s("묶음 이름") } },
+  quote: { does: "인용·한 문장", fields: { text: s("문장", true), who: s("누가"), role: s("직함") } },
+  end: { does: "끝 카드", fields: { title: s("이름", true), line: s("한 줄"), url: s("주소"), logo: s("로고 그림(assets 기준)") } },
+  title: { does: "이름·제목이 서는 순간", fields: { title: s("이름", true), sub: s("부제"), kicker: s("위 작은 글") } },
+  words: { does: "낱말 리듬 — 훅·주장 한 마디", fields: { words: { kind: "strings", need: true, min: 1, max: 6, doc: "낱말" } } },
+  trend: { does: "시간 따라 변하는 값", numbers: true, fields: { points: { kind: "list", need: true, min: 3, max: 24, doc: "점", of: { x: s("가로 딱지(날짜·시각)", true), y: n("값", true) } }, unit: s("단위"), mark: { kind: "object", doc: "짚을 점", of: { x: s("가로 딱지", true), label: s("딱지", true) } } } },
+  code: { does: "명령·코드·로그", fields: { kind: { kind: "enum", values: ["terminal", "code"], doc: "창 종류" }, lines: { kind: "list", max: 10, doc: "터미널 줄", of: { cmd: s("명령"), out: s("출력") } }, code: s("코드"), lang: s("언어") } },
+  screen: { does: "제품 화면을 짚기", fields: { asset: s("화면 그림·영상(assets 기준)", true), focus: { kind: "list", max: 4, doc: "짚을 곳", of: { label: s("딱지"), box: { kind: "box", doc: "짚을 상자 [x, y, w, h] — 그림 기준 0..1, 왼쪽 위 원점(없으면 짚을 자리를 지어내지 않는다)" } } } } },
+  media: { does: "그림·영상", fields: { assets: { kind: "strings", need: true, min: 1, max: 12, doc: "자산 경로" }, label: s("딱지") } },
+  custom: { does: "감독 패턴에 없는 화면 — 모델이 장면 코드를 직접 쓴다", fields: { idea: s("무엇을 보일지 한두 문장", true), file: s("이미 쓴 장면 파일(프로젝트 기준) — 있으면 그대로 둔다") } },
+};
+
+export interface Scene {
+  id: string;
+  type: SceneType;
+  say?: string;
+  source?: string | string[];
+  emphasis?: string;
+  dur?: number;
+  space?: "2d" | "3d";
+  [field: string]: unknown;
+}
+
+export interface Content {
+  version?: number;
+  title: string;
+  /** 원 요청 글 — 용도 판별·시리즈 짚기·씨앗 */
+  request?: string;
+  purpose?: string;
+  series?: string;
+  theme?: string;
+  /** 바라는 길이(초) — 목소리 빠르기를 0.9–1.1 안에서 맞춘다 */
+  duration?: number;
+  aspect?: string;
+  voice?: string;
+  music?: string;
+  seed?: string;
+  scenes: Scene[];
+}
+
+export interface Problem {
+  at: string;
+  msg: string;
+}
+
+export interface Checked {
+  content: Content;
+  errors: Problem[];
+  warnings: Problem[];
+}
+
+// 「9.2 GB」·「57×」·「1,024」 처럼 붙여 쓴 숫자 — 굴리기·자리 폭이 깨져서 숫자와 단위로 나눈다
+const NUM_UNIT = /^\s*([-+]?\d[\d,]*(?:\.\d+)?)\s*(.*?)\s*$/;
+
+function asNumber(v: unknown): { value: number; unit?: string } | null {
+  if (typeof v === "number" && Number.isFinite(v)) return { value: v };
+  if (typeof v !== "string") return null;
+  const m = NUM_UNIT.exec(v);
+  if (!m) return null;
+  const value = Number(m[1].replace(/,/g, ""));
+  return Number.isFinite(value) ? { value, unit: m[2] || undefined } : null;
+}
+
+function walk(spec: Record<string, Field>, obj: Record<string, unknown>, at: string, out: Checked): void {
+  for (const [k, f] of Object.entries(spec)) {
+    const where = `${at}.${k}`;
+    let v = obj[k];
+    if (v === undefined || v === null || v === "") {
+      if (f.need) out.errors.push({ at: where, msg: `없다 — ${f.doc}` });
+      delete obj[k];
+      continue;
+    }
+    switch (f.kind) {
+      case "string":
+        if (typeof v === "number") obj[k] = String(v);
+        else if (typeof v !== "string") out.errors.push({ at: where, msg: `글이어야 한다 — ${f.doc}` });
+        break;
+      case "source":
+        if (typeof v !== "string" && !(Array.isArray(v) && v.every((x) => typeof x === "string"))) out.errors.push({ at: where, msg: "글이나 글 목록이어야 한다" });
+        break;
+      case "number":
+      case "int": {
+        const num = asNumber(v);
+        if (!num) {
+          out.errors.push({ at: where, msg: `숫자여야 한다 — ${f.doc}` });
+          break;
+        }
+        if (typeof v === "string") {
+          obj[k] = num.value;
+          // 붙여 쓴 단위는 옆 unit 칸이 비었을 때만 옮긴다
+          if (num.unit && "unit" in spec && obj.unit === undefined) obj.unit = num.unit;
+          out.warnings.push({ at: where, msg: `"${v}" 를 숫자 ${num.value}${num.unit ? ` + 단위 "${num.unit}"` : ""}로 나눴다 — 숫자와 단위는 따로 쓴다` });
+        }
+        if (f.kind === "int" && !Number.isInteger(obj[k])) out.errors.push({ at: where, msg: "정수여야 한다" });
+        break;
+      }
+      case "boolean":
+        if (typeof v !== "boolean") obj[k] = v === "true" || v === 1;
+        break;
+      case "box": {
+        const b = Array.isArray(v) ? v.map((x) => (typeof x === "string" ? Number(x) : x)) : null;
+        if (!b || b.length !== 4 || !b.every((x) => typeof x === "number" && Number.isFinite(x) && x >= 0 && x <= 1)) out.errors.push({ at: where, msg: `[x, y, w, h] 0..1 숫자 넷 — ${f.doc}` });
+        else if (b[0] + b[2] > 1.0001 || b[1] + b[3] > 1.0001 || b[2] <= 0 || b[3] <= 0) out.errors.push({ at: where, msg: "상자가 그림 밖으로 나가거나 크기가 0" });
+        else obj[k] = b;
+        break;
+      }
+      case "enum":
+        if (!f.values.includes(String(v))) out.errors.push({ at: where, msg: `${f.values.join("·")} 중 하나 — "${v}"` });
+        break;
+      case "strings": {
+        if (typeof v === "string") v = obj[k] = v.split(/\s*[·,]\s*/).filter(Boolean);
+        if (!Array.isArray(v)) {
+          out.errors.push({ at: where, msg: `글 목록이어야 한다 — ${f.doc}` });
+          break;
+        }
+        obj[k] = v = v.map((x) => (typeof x === "string" ? x : String(x)));
+        lengthCheck(f, (v as unknown[]).length, where, out);
+        break;
+      }
+      case "object":
+        if (typeof v !== "object" || Array.isArray(v)) out.errors.push({ at: where, msg: `객체여야 한다 — ${f.doc}` });
+        else walk(f.of, v as Record<string, unknown>, where, out);
+        break;
+      case "list": {
+        // 「KV = 2 × L × d」 같은 식 한 줄 — 연산자 앞뒤로 나눠 항 목록으로
+        if (typeof v === "string" && k === "parts") v = obj[k] = splitFormula(v);
+        if (!Array.isArray(v)) {
+          out.errors.push({ at: where, msg: `목록이어야 한다 — ${f.doc}` });
+          break;
+        }
+        obj[k] = v = v.map((x) => (typeof x === "string" && f.shorthand ? { [f.shorthand]: x } : x));
+        lengthCheck(f, (v as unknown[]).length, where, out);
+        (v as unknown[]).forEach((item, i) => {
+          if (typeof item !== "object" || item === null || Array.isArray(item)) out.errors.push({ at: `${where}[${i}]`, msg: "객체여야 한다" });
+          else walk(f.of, item as Record<string, unknown>, `${where}[${i}]`, out);
+        });
+        break;
+      }
+    }
+  }
+}
+
+function lengthCheck(f: { min?: number; max?: number; doc: string }, len: number, where: string, out: Checked): void {
+  if (f.min !== undefined && len < f.min) out.errors.push({ at: where, msg: `${f.min}개 넘게 — 지금 ${len}개` });
+  if (f.max !== undefined && len > f.max) out.errors.push({ at: where, msg: `${f.max}개까지 — 지금 ${len}개(나누어 두 장면으로)` });
+}
+
+const OPS = /\s*([=×x*+\-−÷/≈→])\s*/;
+
+export function splitFormula(expr: string): { text: string; kind: string }[] {
+  return expr
+    .split(OPS)
+    .map((x) => x.trim())
+    .filter(Boolean)
+    .map((text, i, all) => ({ text, kind: OPS.test(` ${text} `) && text.length === 1 ? "op" : all[i - 1] === "=" && i === all.length - 1 ? "result" : /^\d/.test(text) ? "value" : "term" }));
+}
+
+/** content.json 을 읽어 정규화하고 오류·경고를 모은다. 오류가 있으면 감독이 장면을 짓지 않는다 */
+export function checkContent(raw: unknown): Checked {
+  const out: Checked = { content: { title: "", scenes: [] }, errors: [], warnings: [] };
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    out.errors.push({ at: "content", msg: "객체여야 한다 — { title, scenes: [...] }" });
+    return out;
+  }
+  const c = structuredClone(raw) as Record<string, unknown>;
+  if (typeof c.title !== "string" || !c.title.trim()) out.errors.push({ at: "title", msg: "없다 — 영상 이름(끝 카드·씨앗)" });
+  if (!Array.isArray(c.scenes) || !c.scenes.length) {
+    out.errors.push({ at: "scenes", msg: "장면이 없다 — scenes: [{ type, ... }]" });
+    out.content = c as unknown as Content;
+    return out;
+  }
+  for (const k of ["duration"] as const) if (c[k] !== undefined && asNumber(c[k]) === null) out.errors.push({ at: k, msg: "숫자여야 한다" });
+  if (typeof c.duration === "string") c.duration = asNumber(c.duration)!.value;
+  const seen = new Map<string, number>();
+  const counts: Record<string, number> = {};
+  c.scenes = (c.scenes as unknown[]).map((x, i) => {
+    const at = `scenes[${i}]`;
+    if (typeof x !== "object" || x === null || Array.isArray(x)) {
+      out.errors.push({ at, msg: "객체여야 한다" });
+      return { id: `scene-${i + 1}`, type: "custom" } as Scene;
+    }
+    const sc = x as Record<string, unknown>;
+    const given = String(sc.type ?? "").trim().toLowerCase();
+    const type = (TYPE_ALIASES[given] ?? given) as SceneType;
+    if (!SCENE_TYPES.includes(type)) {
+      out.errors.push({ at: `${at}.type`, msg: `모르는 type "${sc.type ?? ""}" — ${SCENE_TYPES.join("·")}` });
+      return { ...sc, id: String(sc.id ?? `scene-${i + 1}`), type: "custom" } as Scene;
+    }
+    if (given !== type) out.warnings.push({ at: `${at}.type`, msg: `"${given}" 를 "${type}" 로 읽었다` });
+    sc.type = type;
+    counts[type] = (counts[type] ?? 0) + 1;
+    let id = typeof sc.id === "string" && sc.id.trim() ? sc.id.trim() : `${type}-${counts[type]}`;
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) {
+      const fixed = id.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || `${type}-${counts[type]}`;
+      out.warnings.push({ at: `${at}.id`, msg: `"${id}" → "${fixed}"(영문 소문자·숫자·- 만)` });
+      id = fixed;
+    }
+    if (seen.has(id)) {
+      out.errors.push({ at: `${at}.id`, msg: `"${id}" 가 scenes[${seen.get(id)}] 와 겹친다` });
+    }
+    seen.set(id, i);
+    sc.id = id;
+    walk({ ...COMMON, ...TYPES[type].fields }, sc, at, out);
+    const spec = TYPES[type];
+    if (spec.numbers && !sc.source) out.warnings.push({ at, msg: `숫자를 보이는 ${type} 인데 source(출처)가 없다` });
+    if (typeof sc.emphasis === "string" && !JSON.stringify(Object.fromEntries(Object.entries(sc).filter(([k]) => k !== "emphasis" && k !== "say"))).includes(sc.emphasis))
+      out.warnings.push({ at: `${at}.emphasis`, msg: `"${sc.emphasis}" 가 필드 값에 없다` });
+    for (const k of Object.keys(sc)) if (!(k in COMMON) && !(k in spec.fields)) out.warnings.push({ at: `${at}.${k}`, msg: `${type} 에 없는 칸 — 쓰지 않는다` });
+    if (type === "flow" && Array.isArray(sc.nodes)) {
+      const ids = new Set((sc.nodes as { id?: string }[]).map((nd) => nd.id));
+      for (const [j, e] of ((sc.edges as { from?: string; to?: string }[] | undefined) ?? []).entries()) for (const end of [e.from, e.to]) if (end && !ids.has(end)) out.errors.push({ at: `${at}.edges[${j}]`, msg: `없는 노드 "${end}"` });
+    }
+    if (type === "fill" && typeof sc.total === "number" && typeof sc.filled === "number") {
+      if (sc.total < 2 || sc.total > 400) out.errors.push({ at: `${at}.total`, msg: "2–400 칸" });
+      if (sc.filled < 0 || sc.filled > sc.total) out.errors.push({ at: `${at}.filled`, msg: `0–${sc.total}` });
+    }
+    return sc as Scene;
+  });
+  out.content = c as unknown as Content;
+  return out;
+}
+
+/** 모델에게 줄 칸 표 — 지시서(MAKE.md)·OG 모드 프롬프트가 같은 표를 쓴다 */
+export function contentGuide(): string {
+  const field = (k: string, f: Field): string => {
+    const opt = f.need ? "" : "?";
+    switch (f.kind) {
+      case "object":
+        return `${k}${opt}: { ${Object.entries(f.of).map(([a, b]) => field(a, b)).join(", ")} }`;
+      case "list":
+        return `${k}${opt}: [{ ${Object.entries(f.of).map(([a, b]) => field(a, b)).join(", ")} }]${f.min || f.max ? `(${f.min ?? 0}–${f.max ?? "∞"})` : ""}`;
+      case "strings":
+        return `${k}${opt}: string[]${f.min || f.max ? `(${f.min ?? 0}–${f.max ?? "∞"})` : ""}`;
+      case "enum":
+        return `${k}${opt}: ${f.values.map((v) => `"${v}"`).join("|")}`;
+      default:
+        return `${k}${opt}: ${f.kind === "int" ? "integer" : f.kind === "source" ? "string" : f.kind === "box" ? "[x, y, w, h](0..1)" : f.kind}`;
+    }
+  };
+  const rows = SCENE_TYPES.map((t) => `| \`${t}\` | ${TYPES[t].does} | ${Object.entries(TYPES[t].fields).map(([k, f]) => `\`${field(k, f)}\``).join(" · ")} |`);
+  return [
+    "모든 장면: `id?` · `type` · `say?`(들릴 말 — 화면 글 아님) · `source?`(출처 — 숫자가 있는 장면은 꼭) · `emphasis?` · `dur?`(say 가 없을 때만) · `space?`(\"3d\" 면 3D 샷 장면)",
+    "숫자는 `value` 와 `unit` 을 따로(\"9.2 GB\" 로 붙이지 않는다). 글 칸은 모두 짧게 — 문장은 say 로.",
+    "",
+    "| type | 언제 | 칸 |",
+    "|---|---|---|",
+    ...rows,
+  ].join("\n");
+}

package/packages/director/src/fallback.ts

@@ -0,0 +1,58 @@
+import { definePattern } from "./pattern.ts";
+
+// 감독 안 기본 — 어느 type 이든 내용의 낱말을 뽑아 무대의 글 수(dress.text)로 띄운다. 그 type 의 패턴이 아직 없거나
+// 다 떨어졌을 때만 고른다(점수 -8). 글 수는 검사를 넘긴 기본값이 박혀 있어 이 길도 kf check 를 넘는다.
+
+const MAX_WORD = 14;
+
+function words(content: Record<string, unknown>): string[] {
+  const out: string[] = [];
+  const add = (v: unknown, unit?: unknown) => {
+    if (typeof v === "number") out.push(`${v}${typeof unit === "string" ? unit : ""}`);
+    else if (typeof v === "string" && v.trim()) out.push(v.trim());
+  };
+  const each = (list: unknown, key: string) => Array.isArray(list) && list.forEach((x) => (typeof x === "string" ? add(x) : x && typeof x === "object" && add((x as Record<string, unknown>)[key])));
+  const side = (x: unknown) => {
+    if (!x || typeof x !== "object") return;
+    const o = x as Record<string, unknown>;
+    add(o.label);
+    add(o.value, o.unit);
+  };
+  add(content.prefix !== undefined && typeof content.value === "number" ? `${content.prefix}${content.value}${content.unit ?? ""}` : undefined);
+  if (content.prefix === undefined) add(content.value, content.unit);
+  for (const k of ["title", "term", "full", "ko", "label", "knob", "ratio", "change", "cost", "text", "who", "line", "url"]) add(content[k]);
+  side(content.a);
+  side(content.b);
+  side(content.before);
+  side(content.after);
+  each(content.items, "word");
+  each(content.items, "label");
+  each(content.steps, "label");
+  each(content.nodes, "label");
+  each(content.marks, "label");
+  each(content.parts, "text");
+  each(content.states, "label");
+  each(content.words, "");
+  if (content.window && typeof content.window === "object") add((content.window as Record<string, unknown>).label);
+  if (content.total !== undefined) add(`${content.filled ?? 0}/${content.total}`);
+  return [...new Set(out)].filter((w) => [...w].length <= MAX_WORD).slice(0, 8);
+}
+
+export default definePattern({
+  id: "any.words",
+  type: "*",
+  does: "내용의 낱말을 무대 글 수로 차례로 — 패턴이 없을 때의 기본",
+  energy: ["low", "mid", "high"],
+  family: "stack",
+  camera: ["none"],
+  bg: "stage",
+  aspects: [],
+  dur: { min: 0.8, max: 60 },
+  fits: (c) => (words(c).length ? true : "띄울 낱말이 없다"),
+  build(_root, _ctx, content, kit) {
+    const { paint } = kit.stage.say(words(content), { ready: kit.first });
+    return (t) => paint(t);
+  },
+});
+
+export { words as fallbackWords };

package/packages/director/src/index.ts

@@ -0,0 +1,13 @@
+// 감독 — content.json(무엇을 보일지)에서 장면 문법·전환·바탕을 골라 장면 파일을 조립한다. Node 쪽 입구(장면 감싸개는 ./scene).
+export { checkContent, contentGuide, splitFormula, COMMON, SCENE_TYPES, TYPE_ALIASES, TYPES } from "./content.ts";
+export type { Checked, Content, Problem, Scene, SceneType, TypeSpec } from "./content.ts";
+export { definePattern } from "./pattern.ts";
+export type { AspectName, CameraKind, Energy, Family, FitInfo, Kit, Pattern, PatternMeta, SpokenWord, StageLike, TextPolicy } from "./pattern.ts";
+export { order, reject, repick, score, selectAll } from "./select.ts";
+export type { Entry, Pick, Ranked, Rejected, SelectCtx, Slot } from "./select.ts";
+export { BRIDGE_KIND, cyclingText, dressAll, energyOf, SEAM_KINDS, seamKinds, seamSpots, STILL_BG } from "./transitions.ts";
+export type { Spot } from "./transitions.ts";
+export { catalog } from "./catalog.ts";
+export { build, contentHash, layout, MARK } from "./assemble.ts";
+export type { BuildOpts, Report, SceneReport } from "./assemble.ts";
+export { directBrief, contentPrompt } from "./brief.ts";

package/packages/director/src/pattern.ts

@@ -0,0 +1,90 @@
+import type { SceneCtx, Style } from "@kasaframe/core";
+import type { ThemeSlots } from "@kasaframe/themes/slots";
+
+// 패턴 꼴 — 감독이 Node 에서 meta·fits 로 고르고, 장면 파일이 브라우저에서 build 로 그린다. 그래서 패턴 파일은 맨 위에서
+// DOM 을 만지거나 Vite 전용 API(import.meta.glob)를 부르지 않는다. 이 파일도 Node 의존이 없다(패턴이 import type 으로 가져간다).
+
+export type Energy = "low" | "mid" | "high";
+export type Family = "slam" | "flap" | "grow" | "draw" | "type" | "pop" | "mask" | "flow" | "stack" | "morph";
+export type CameraKind = "none" | "pushIn" | "pullOut" | "follow" | "impact";
+export type AspectName = "16:9" | "9:16" | "1:1";
+export type TextPolicy = "none" | "terms-only" | "captions" | "lyrics";
+
+/** 고를 때 fits 에 주는 장면 사정 */
+export interface FitInfo {
+  aspect: AspectName;
+  dur: number;
+  policy: TextPolicy;
+}
+
+export interface PatternMeta<C = Record<string, unknown>> {
+  /** "<type>.<이름>" — 장면 파일이 @kasaframe/patterns/<type>/<이름> 으로 가져간다 */
+  id: string;
+  type: string;
+  does: string;
+  /** 곡 구간 — intro·verse·break = low, main = mid, drop = high */
+  energy: Energy[];
+  /** 이어지는 장면이 같은 계열이면 감점 */
+  family: Family;
+  /** 쓰는 카메라 이벤트(이유는 does 에) — 그 밖엔 정지 */
+  camera: CameraKind[];
+  /** stage: 감독이 고른 dress 바탕을 쓴다 · own: 패턴이 제 바탕을 깐다 */
+  bg: "stage" | "own";
+  aspects: AspectName[];
+  /** 초 — min 보다 짧은 장면엔 안 고른다, max 를 넘으면 감점 */
+  dur: { min: number; max: number };
+  /** 테마 궁합 -1..1, 없으면 0 */
+  themes?: Record<string, number>;
+  purposes?: { prefer?: string[]; avoid?: string[] };
+  /** 이 내용을 그릴 수 있나 — 못 그리면 까닭(막대 9개 → 다른 후보로) */
+  fits?(content: C, info: FitInfo): true | string;
+}
+
+/** 패턴이 받는 무대 — 프로젝트 lib/stage.ts 의 Stage 와 같은 꼴(구조로만 맞춘다) */
+export interface StageLike {
+  box: HTMLDivElement;
+  cam: HTMLDivElement;
+  safeW: number;
+  safeH: number;
+  vertical: boolean;
+  camera: {
+    pushIn(at: number, o?: { to?: unknown; scale?: number; dur?: number }): unknown;
+    pullOut(at: number, o?: { to?: unknown; scale?: number; dur?: number }): unknown;
+    follow(target: unknown, from: number, to: number, o?: { scale?: number }): unknown;
+    impact(at: number, o?: { amount?: number; dur?: number }): unknown;
+  };
+  hero(el: HTMLElement): HTMLElement;
+  say(words: readonly string[], o?: { color?: string; weight?: number; ready?: boolean }): { el: HTMLElement; paint: (t: number, extra?: Style) => void };
+}
+
+export interface SpokenWord {
+  text: string;
+  /** 장면 안 초 */
+  from: number;
+  to: number;
+}
+
+export interface Kit {
+  /** 감독이 준 씨앗 — 패턴 안 난수는 rand(kit.seed, i) 만 */
+  seed: string;
+  /** 장면 안 박(dress hitTimes 꼴 — 빠른 곡은 묶어서) */
+  hits: number[];
+  /** 들리는 낱말 시각(장면 안 초) — kf narrate 를 지났을 때만 */
+  say: SpokenWord[];
+  /** 테마 슬롯(themes/<id>/slots.ts) — 테마가 비운 자리는 패턴 기본으로 그린다 */
+  slots: ThemeSlots;
+  /** 감독이 dress 바탕·경계 덮기를 건 무대. 감싸개가 paint 다음에 stage.tick 을 부르니 패턴은 부르지 않는다 */
+  stage: StageLike;
+  policy: TextPolicy;
+  /** 영상 안 자리 — 첫 장면·마지막 장면·되돌이 */
+  first: boolean;
+  last: boolean;
+  loop: boolean;
+}
+
+export interface Pattern<C = Record<string, unknown>> extends PatternMeta<C> {
+  /** root = 무대 카메라 층(안전 영역 상자). 같은 t 면 같은 화면 */
+  build(root: HTMLElement, ctx: SceneCtx, content: C, kit: Kit): (t: number) => void;
+}
+
+export const definePattern = <C = Record<string, unknown>>(p: Pattern<C>): Pattern<C> => p;

package/packages/director/src/patterns/fill/cells.ts

@@ -0,0 +1,115 @@
+import { definePattern } from "../../pattern.ts";
+import { clamp01, el, fit, glide, passed, times } from "../util.ts";
+
+interface Fill {
+  total: number;
+  filled: number;
+  from?: number;
+  label: string;
+  unit?: string;
+}
+
+// 칸 격자가 박마다 한 칸씩 차거나 빈다 — GPU 자리·메모리·대기열. 칸 하나 = 내용 한 단위(자리 하나·GB 하나)라 장식 칸은 없다.
+// 바늘은 지금 바뀌는 칸을 짚고, 다 바뀐 뒤엔 박마다 「바뀐 칸」을 차례로 다시 짚어(무엇이 달라졌나) 구도가 계속 바뀐다.
+// 다 차면 결과를 드러내러 한 번 다가간다(pushIn — 격자 가운데, 배율 작게).
+
+const MAX_CELLS = 400;
+
+export default definePattern<Fill>({
+  id: "fill.cells",
+  type: "fill",
+  does: "칸 격자가 박마다 한 칸씩 차고, 바늘이 칸을 훑고, 숫자가 같이 오른다 — 다 차면 한 번 다가간다(결과 드러냄)",
+  energy: ["low", "mid"],
+  family: "grow",
+  camera: ["pushIn"],
+  bg: "stage",
+  aspects: ["16:9", "9:16", "1:1"],
+  dur: { min: 2.5, max: 16 },
+  themes: { "og-measure": 0.5, "debug-hud": 0.5, "kasaterm-cells": 1 },
+  fits: (c) => (c.total > MAX_CELLS ? `칸 ${c.total}개는 너무 많다(${MAX_CELLS}까지)` : true),
+  build(root, ctx, c, kit) {
+    const W = kit.stage.safeW;
+    const H = kit.stage.safeH;
+    const vertical = kit.stage.vertical;
+    const from = Math.max(0, Math.min(c.total, c.from ?? 0));
+    const to = c.filled;
+    const unit = c.unit ?? "";
+
+    // 격자 자리 — 글 두 줄을 빼고 안전 영역의 84% 안(다가가도 안전 영역을 안 넘게)
+    const labelPx = fit(c.label, W * 0.86, 48, vertical ? 120 : 110);
+    const countPx = Math.round(Math.min(labelPx * 1.25, vertical ? 150 : 130));
+    const gw = W * 0.9;
+    const gh = H * 0.84 - labelPx * 1.2 - countPx * 1.2 - 56;
+    const cols = Math.max(1, Math.min(c.total, Math.round(Math.sqrt((c.total * gw) / Math.max(1, gh)))));
+    const rows = Math.ceil(c.total / cols);
+    const cell = Math.floor(Math.min(gw / cols, gh / rows));
+    const gap = Math.max(2, Math.round(cell * 0.14));
+    const side = cell - gap;
+
+    root.style.gap = "28px";
+    const label = el("div", `font-family:var(--kf-font-display);font-weight:800;font-size:${labelPx}px;line-height:1.1;color:var(--kf-ink);text-align:center;white-space:nowrap;letter-spacing:var(--kf-tracking)`, c.label);
+    const grid = el("div", `position:relative;width:${cols * cell}px;height:${rows * cell}px`);
+    const count = el("div", `font-family:var(--kf-font-display);font-weight:800;font-size:${countPx}px;line-height:1;color:var(--kf-ink);font-variant-numeric:tabular-nums;white-space:nowrap`);
+    root.append(label, grid, count);
+    kit.stage.hero(grid);
+
+    const cells = Array.from({ length: c.total }, (_, i) => {
+      const x = (i % cols) * cell + gap / 2;
+      const y = Math.floor(i / cols) * cell + gap / 2;
+      const box = el("div", `position:absolute;left:${x}px;top:${y}px;width:${side}px;height:${side}px;border-radius:${Math.round(side * 0.18)}px;box-sizing:border-box;border:${Math.max(2, Math.round(side * 0.06))}px solid color-mix(in srgb, var(--kf-ink) 28%, transparent)`);
+      const fillEl = el("div", `position:absolute;inset:-1px;border-radius:inherit;background:var(--kf-accent);transform-origin:50% 50%`);
+      box.append(fillEl);
+      grid.append(box);
+      return { fillEl };
+    });
+    const needle = el("div", `position:absolute;left:0;top:0;width:${cell + gap}px;height:${cell + gap}px;box-sizing:border-box;border:${Math.max(3, Math.round(side * 0.09))}px solid var(--kf-ink);border-radius:${Math.round(side * 0.26)}px;pointer-events:none`);
+    grid.append(needle);
+
+    // 바뀌는 칸 차례 — 차면 앞에서부터, 비면 뒤에서부터
+    const k = Math.abs(to - from);
+    const fillEnd = Math.min(ctx.dur * 0.62, ctx.dur - 1.3);
+    const at = times(kit.hits, k, Math.min(0.25, ctx.dur * 0.1), Math.max(0.3, fillEnd));
+    const order = Array.from({ length: k }, (_, i) => (to >= from ? from + i : from - 1 - i));
+    const changeAt = new Map(order.map((idx, i) => [idx, at[i]]));
+    // 바늘은 바뀌는 칸을 따라가고, 다 바뀐 뒤엔 박마다 바뀐 칸을 처음부터 다시 짚는다(바뀐 칸이 하나뿐이면 찬 칸을 하나씩 센다).
+    // 정지점 사이를 내내 옮겨 가 화면이 멈추지 않는다 — 처음엔 격자 반대편에서 첫 칸으로 오고, 끝은 장면 밖 다음 칸으로 가는 중에 끝난다
+    const after = kit.hits.filter((h) => h > (at[k - 1] ?? 0) + 0.2);
+    const recap = k >= 2 ? order : Array.from({ length: Math.min(c.total, Math.max(2, from, to)) }, (_, i) => i);
+    const first = order[0] ?? recap[0];
+    const stops = [
+      { t: 0, idx: first === 0 ? c.total - 1 : 0 },
+      ...order.map((idx, i) => ({ t: at[i], idx })),
+      ...after.map((t, i) => ({ t, idx: recap[i % recap.length] })),
+    ];
+    stops.push({ t: ctx.dur + 0.4, idx: recap[after.length % recap.length] });
+    const stopAt = stops.map((x) => x.t);
+    const zoomAt = (at[k - 1] ?? 0) + 0.25;
+    if (ctx.dur - zoomAt > 1.4) kit.stage.camera.pushIn(zoomAt, { scale: 1.07, dur: 0.9 });
+
+    const pos = (idx: number) => ({ x: (idx % cols) * cell - gap / 2, y: Math.floor(idx / cols) * cell - gap / 2 });
+    return (t: number) => {
+      const n = passed(at, t);
+      const nowFilled = to >= from ? from + n : from - n;
+      count.textContent = `${nowFilled} / ${c.total}${unit}`;
+      for (const [i, cl] of cells.entries()) {
+        const when = changeAt.get(i);
+        const startFull = i < from;
+        let s: number;
+        if (when === undefined) s = startFull ? 1 : 0;
+        else {
+          // 다음 칸이 바뀔 때까지 내내 차오른다(빈다) — 칸 하나가 바로 그 사이의 양이다
+          const next = at[order.indexOf(i) + 1] ?? when + 0.6;
+          const p = clamp01((t - when) / Math.min(1.2, Math.max(0.28, next - when)));
+          const e = 1 - (1 - p) * (1 - p);
+          s = startFull ? 1 - e : e;
+        }
+        cl.fillEl.style.transform = `scale(${Math.max(0, s).toFixed(3)})`;
+        cl.fillEl.style.opacity = s > 0 ? "1" : "0";
+      }
+      const { j, e } = glide(stopAt, t);
+      const a = pos(stops[j].idx);
+      const b = pos(stops[j + 1]?.idx ?? stops[j].idx);
+      needle.style.transform = `translate(${(a.x + (b.x - a.x) * e).toFixed(1)}px, ${(a.y + (b.y - a.y) * e).toFixed(1)}px)`;
+    };
+  },
+});