kasaframe 0.0.0-stage → 0.1.1

package/packages/core/src/beats.ts

@@ -0,0 +1,283 @@
+import { emit } from "./frame.ts";
+
+export type SectionKind = "intro" | "drop" | "main" | "break" | "outro" | (string & {});
+
+export interface BeatsJson {
+  source?: string;
+  /** 곡에서 잘라 쓴 시작(초). 시각은 모두 여기를 0 으로 센다 — 소리를 낼 때만 from + t */
+  from?: number;
+  duration: number;
+  bpm: number;
+  beats: number[];
+  downbeats?: number[];
+  bars?: number[];
+  /** 4 마디 묶음 시작 — style.json 의 once-per-phrase·maxPerPhrase 가 세는 단위 */
+  phrases?: number[];
+  sections?: { t: number; kind: SectionKind; strength?: number }[];
+  drops?: number[];
+  energy?: { hz: number; low: number[]; mid: number[]; high: number[] };
+}
+
+export interface Section {
+  index: number;
+  kind: SectionKind;
+  t: number;
+  end: number;
+  /** 0..1 — 드롭은 저역 대비, main 은 바뀐 정도. 분석이 안 줬으면 1 */
+  strength: number;
+}
+
+export interface Phrase {
+  index: number;
+  t: number;
+  end: number;
+}
+
+export type BeatGrid = "beat" | "downbeat" | "bar" | "phrase" | "drop" | "section";
+
+export interface PulseOpts {
+  /** 무엇마다 — 박·첫박·마디·드롭, 또는 n 박마다 */
+  every?: BeatGrid | number;
+  /** 지수 감쇠 시간 상수(초). 작을수록 짧게 튄다 */
+  decay?: number;
+  /** 어디서 — 기본은 드롭 구간만(style.json beatPulse 기본 drops-only) */
+  within?: "drops" | "all";
+  /** 이벤트 기록용 부품 id·장면 id. emit:false 면 기록하지 않는다(화면에 안 쓰는 계산일 때) */
+  source?: string;
+  scene?: string;
+  emit?: boolean;
+}
+
+export interface Beats {
+  readonly data: BeatsJson;
+  /** 이 도구의 0 초가 곡의 몇 초인지 — 장면 ctx 는 장면 시작 */
+  readonly offset: number;
+  readonly bpm: number;
+  readonly duration: number;
+  beats: number[];
+  downbeats: number[];
+  bars: number[];
+  drops: number[];
+  phrases: number[];
+  sections: Section[];
+  /** n 번째 박 시각. 소수면 사이를 잇고, 배열 밖이면 끝 박 간격의 중앙값으로 늘린다 */
+  beatAt(n: number): number;
+  beatIndex(t: number): number;
+  nearestBeat(t: number, grid?: BeatGrid): number;
+  /** grid 에서 t 이하 가장 최근 시각. 없으면 -Infinity */
+  prev(t: number, grid?: BeatGrid): number;
+  next(t: number, grid?: BeatGrid): number;
+  drop(i: number): number;
+  section(t: number): Section;
+  phrase(t: number): Phrase;
+  inDrop(t: number): boolean;
+  pulse(t: number, opts?: PulseOpts): number;
+  /** 대역 에너지 0..1(곡 전체 기준). 곡 분석에 energy 가 없으면 0 */
+  energy(t: number, band?: "low" | "mid" | "high"): number;
+}
+
+const sorted = (a: number[] | undefined): number[] =>
+  (a ?? []).filter((v) => Number.isFinite(v)).slice().sort((x, y) => x - y);
+
+function median(xs: number[]): number {
+  if (xs.length === 0) return 0;
+  const s = xs.slice().sort((a, b) => a - b);
+  return s[Math.floor(s.length / 2)];
+}
+
+/** 이분 탐색 — t 이하인 마지막 인덱스, 없으면 -1 */
+function floorIndex(xs: number[], t: number): number {
+  let lo = 0;
+  let hi = xs.length - 1;
+  let ans = -1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    if (xs[mid] <= t + 1e-9) {
+      ans = mid;
+      lo = mid + 1;
+    } else hi = mid - 1;
+  }
+  return ans;
+}
+
+/** beats.json 을 검사하고 빈 칸을 채운다. 틀린 값은 렌더 중이 아니라 여기서 바로 던진다 */
+export function parseBeats(input: unknown): BeatsJson {
+  const j = (typeof input === "string" ? JSON.parse(input) : input) as Partial<BeatsJson> | null;
+  if (!j || typeof j !== "object") throw new Error("beats.json: 객체가 아니다");
+  if (!Array.isArray(j.beats) || j.beats.length < 2) throw new Error("beats.json: beats 가 두 개 이상 있어야 한다");
+  const beats = sorted(j.beats);
+  const duration = Number.isFinite(j.duration) && j.duration! > 0 ? j.duration! : beats[beats.length - 1];
+  const bpm = Number.isFinite(j.bpm) && j.bpm! > 0 ? j.bpm! : 60 / median(beats.slice(1).map((b, i) => b - beats[i]));
+  const downbeats = j.downbeats?.length ? sorted(j.downbeats) : beats.filter((_, i) => i % 4 === 0);
+  const bars = j.bars?.length ? sorted(j.bars) : downbeats;
+  const sections = (j.sections ?? [])
+    .filter((s) => s && Number.isFinite(s.t))
+    .slice()
+    .sort((a, b) => a.t - b.t);
+  if (sections.length === 0 || sections[0].t > 0) sections.unshift({ t: 0, kind: "intro" });
+  // 분석이 phrases 를 안 줬으면 4 마디씩 센다
+  const phrases = j.phrases?.length ? sorted(j.phrases) : bars.filter((_, i) => i % 4 === 0);
+  if (phrases.length === 0 || phrases[0] > 0) phrases.unshift(0);
+  const out: BeatsJson = { duration, bpm, beats, downbeats, bars, phrases, sections, drops: sorted(j.drops) };
+  if (j.source !== undefined) out.source = j.source;
+  if (Number.isFinite(j.from)) out.from = j.from;
+  if (j.energy) out.energy = j.energy;
+  return out;
+}
+
+export function createBeats(input: BeatsJson | unknown, offset = 0): Beats {
+  const data = parseBeats(input);
+  const shift = (xs: number[]) => xs.map((v) => v - offset);
+  const beats = shift(data.beats);
+  const downbeats = shift(data.downbeats!);
+  const bars = shift(data.bars!);
+  const drops = shift(data.drops!);
+  const phrases = shift(data.phrases!);
+  const raw = data.sections!;
+  const end = data.duration - offset;
+  const sections: Section[] = raw.map((s, index) => ({
+    index,
+    kind: s.kind,
+    t: s.t - offset,
+    end: index + 1 < raw.length ? raw[index + 1].t - offset : end,
+    strength: Number.isFinite(s.strength) ? s.strength! : 1,
+  }));
+  const hasDropSections = sections.some((s) => s.kind === "drop");
+  const gap = median(data.beats.slice(1).map((b, i) => b - data.beats[i])) || 60 / data.bpm;
+  const barLen = median(bars.slice(1).map((b, i) => b - bars[i])) || gap * 4;
+
+  const gridOf = (g: BeatGrid): number[] =>
+    g === "beat" ? beats : g === "downbeat" ? downbeats : g === "bar" ? bars : g === "phrase" ? phrases : g === "drop" ? drops : sections.map((s) => s.t);
+
+  const beatAt = (n: number): number => {
+    if (!Number.isFinite(n)) throw new Error(`beatAt(${n}): 박 번호가 수가 아니다`);
+    const last = beats.length - 1;
+    if (n < 0) return beats[0] + n * gap;
+    if (n > last) return beats[last] + (n - last) * gap;
+    const i = Math.floor(n);
+    const f = n - i;
+    return f === 0 || i === last ? beats[i] : beats[i] + (beats[i + 1] - beats[i]) * f;
+  };
+
+  const prev = (t: number, g: BeatGrid = "beat"): number => {
+    const xs = gridOf(g);
+    const i = floorIndex(xs, t);
+    return i < 0 ? -Infinity : xs[i];
+  };
+
+  const next = (t: number, g: BeatGrid = "beat"): number => {
+    const xs = gridOf(g);
+    const i = floorIndex(xs, t);
+    return i + 1 < xs.length ? xs[i + 1] : Infinity;
+  };
+
+  const nearestBeat = (t: number, g: BeatGrid = "beat"): number => {
+    const xs = gridOf(g);
+    if (xs.length === 0) return t;
+    const a = prev(t, g);
+    const b = next(t, g);
+    if (!Number.isFinite(a)) return b;
+    if (!Number.isFinite(b)) return a;
+    return t - a <= b - t ? a : b;
+  };
+
+  const sectionStarts = sections.map((s) => s.t);
+  const section = (t: number): Section => sections[Math.max(0, floorIndex(sectionStarts, t))];
+
+  const phrase = (t: number): Phrase => {
+    const i = Math.max(0, floorIndex(phrases, t));
+    return { index: i, t: phrases[i], end: i + 1 < phrases.length ? phrases[i + 1] : end };
+  };
+
+  const inDrop = (t: number): boolean => {
+    if (hasDropSections) return section(t).kind === "drop";
+    // 분석이 구간 종류를 못 붙였으면 드롭에서 8 마디(한 프레이즈)를 드롭 구간으로 본다
+    const d = prev(t, "drop");
+    return Number.isFinite(d) && t - d < barLen * 8;
+  };
+
+  const pulse = (t: number, opts: PulseOpts = {}): number => {
+    const every = opts.every ?? "beat";
+    const decay = opts.decay ?? 0.16;
+    if ((opts.within ?? "drops") === "drops" && !inDrop(t)) return 0;
+    let at: number;
+    if (typeof every === "number") {
+      const i = floorIndex(beats, t);
+      if (i < 0) return 0;
+      at = beats[i - (i % Math.max(1, Math.round(every)))];
+    } else at = prev(t, every);
+    if (!Number.isFinite(at)) return 0;
+    const dt = t - at;
+    const v = dt < 0 || dt > decay * 6 ? 0 : Math.exp(-dt / Math.max(decay, 1e-3));
+    if (opts.emit !== false && v > 0.05) emit({ kind: "pulse", source: opts.source ?? "pulse", scene: opts.scene, value: v });
+    return v;
+  };
+
+  const drop = (i: number): number => {
+    if (!Number.isInteger(i) || i < 0 || i >= drops.length)
+      throw new Error(`drop(${i}): 이 곡의 드롭은 ${drops.length}개(0..${drops.length - 1})`);
+    return drops[i];
+  };
+
+  // 분석이 곡 전체 기준으로 0..1 을 맞춰 준다 — 여기서 다시 최댓값으로 나누면 조용한 구간이 부푼다
+  const energy = (t: number, band: "low" | "mid" | "high" = "low"): number => {
+    const e = data.energy;
+    const xs = e?.[band];
+    if (!e || !xs || xs.length === 0 || !(e.hz > 0)) return 0;
+    const x = (t + offset) * e.hz;
+    const i = Math.floor(x);
+    const v = i < 0 ? xs[0] : i >= xs.length - 1 ? xs[xs.length - 1] : xs[i] + (xs[i + 1] - xs[i]) * (x - i);
+    return Number.isFinite(v) ? Math.min(1, Math.max(0, v)) : 0;
+  };
+
+  return {
+    data,
+    offset,
+    bpm: data.bpm,
+    duration: data.duration,
+    beats,
+    downbeats,
+    bars,
+    drops,
+    phrases,
+    sections,
+    beatAt,
+    beatIndex: (t) => floorIndex(beats, t),
+    nearestBeat,
+    prev,
+    next,
+    drop,
+    section,
+    phrase,
+    inDrop,
+    pulse,
+    energy,
+  };
+}
+
+let current: Beats | null = null;
+
+export function setBeats(input: BeatsJson | unknown): Beats {
+  current = createBeats(input);
+  return current;
+}
+
+export async function loadBeats(url: string): Promise<Beats> {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`beats.json 을 못 받았다: ${url} (${res.status})`);
+  return setBeats(await res.json());
+}
+
+export function getBeats(): Beats {
+  if (!current) throw new Error("beats.json 이 아직 없다 — setBeats(json) 이나 loadBeats(url) 를 먼저 부른다");
+  return current;
+}
+
+export const hasBeats = (): boolean => current !== null;
+
+/** 곡 전체 시각 기준 도구들. 장면 안에서는 ctx.beats(장면 시작 0 기준)를 쓴다 */
+export const beatAt = (n: number): number => getBeats().beatAt(n);
+export const nearestBeat = (t: number, grid?: BeatGrid): number => getBeats().nearestBeat(t, grid);
+export const pulse = (t: number, opts?: PulseOpts): number => getBeats().pulse(t, opts);
+export const drop = (i: number): number => getBeats().drop(i);
+export const section = (t: number): Section => getBeats().section(t);

package/packages/core/src/ease.ts

@@ -0,0 +1,87 @@
+export type Ease = (p: number) => number;
+
+const c1 = 1.70158;
+const c3 = c1 + 1;
+const c4 = (2 * Math.PI) / 3;
+
+const out = (f: Ease): Ease => (p) => 1 - f(1 - p);
+const inOut = (f: Ease): Ease => (p) => (p < 0.5 ? f(2 * p) / 2 : 1 - f(2 - 2 * p) / 2);
+
+const pow = (n: number): Ease => (p) => p ** n;
+const expoIn: Ease = (p) => (p <= 0 ? 0 : 2 ** (10 * p - 10));
+const backIn: Ease = (p) => c3 * p ** 3 - c1 * p * p;
+const circIn: Ease = (p) => 1 - Math.sqrt(1 - p * p);
+const elasticOut: Ease = (p) => (p <= 0 ? 0 : p >= 1 ? 1 : 2 ** (-10 * p) * Math.sin((p * 10 - 0.75) * c4) + 1);
+
+/** CSS cubic-bezier 와 같은 곡선. x 로 s 를 뉴턴법 + 이분법으로 찾는다 */
+export function bezier(x1: number, y1: number, x2: number, y2: number): Ease {
+  const at = (a: number, b: number, s: number) => 3 * a * s * (1 - s) ** 2 + 3 * b * s * s * (1 - s) + s ** 3;
+  const dAt = (a: number, b: number, s: number) => 3 * a * (1 - s) ** 2 + 6 * (b - a) * s * (1 - s) + 3 * (1 - b) * s * s;
+  return (p) => {
+    if (p <= 0) return 0;
+    if (p >= 1) return 1;
+    let s = p;
+    for (let i = 0; i < 8; i++) {
+      const d = dAt(x1, x2, s);
+      if (Math.abs(d) < 1e-6) break;
+      const next = s - (at(x1, x2, s) - p) / d;
+      if (next < 0 || next > 1) break;
+      s = next;
+    }
+    if (Math.abs(at(x1, x2, s) - p) > 1e-5) {
+      let lo = 0;
+      let hi = 1;
+      for (let i = 0; i < 40; i++) {
+        s = (lo + hi) / 2;
+        if (at(x1, x2, s) < p) lo = s;
+        else hi = s;
+      }
+    }
+    return at(y1, y2, s);
+  };
+}
+
+export const ease = {
+  linear: ((p) => p) as Ease,
+  inQuad: pow(2),
+  outQuad: out(pow(2)),
+  inOutQuad: inOut(pow(2)),
+  inCubic: pow(3),
+  outCubic: out(pow(3)),
+  inOutCubic: inOut(pow(3)),
+  inQuart: pow(4),
+  outQuart: out(pow(4)),
+  inOutQuart: inOut(pow(4)),
+  inQuint: pow(5),
+  outQuint: out(pow(5)),
+  inOutQuint: inOut(pow(5)),
+  inExpo: expoIn,
+  outExpo: out(expoIn),
+  inOutExpo: inOut(expoIn),
+  inCirc: circIn,
+  outCirc: out(circIn),
+  inOutCirc: inOut(circIn),
+  inBack: backIn,
+  outBack: out(backIn),
+  inOutBack: inOut(backIn),
+  outElastic: elasticOut,
+  /** CSS 기본값들 */
+  css: bezier(0.25, 0.1, 0.25, 1),
+  cssIn: bezier(0.42, 0, 1, 1),
+  cssOut: bezier(0, 0, 0.58, 1),
+  cssInOut: bezier(0.42, 0, 0.58, 1),
+  /** 카사텀·OG 공통 감속 cubic-bezier(0.22, 1, 0.36, 1) */
+  snappy: bezier(0.22, 1, 0.36, 1),
+  steps: (n: number): Ease => (p) => (p >= 1 ? 1 : Math.floor(p * n) / n),
+} as const;
+
+export type EaseName = Exclude<keyof typeof ease, "steps">;
+
+/** 이름이나 함수를 받아 함수로. 모르는 이름은 조용히 넘기지 않고 던진다 — 오타가 linear 로 바뀌어 묻히지 않게 */
+export function toEase(e: EaseName | Ease | undefined, fallback: Ease = ease.outCubic): Ease {
+  if (e === undefined) return fallback;
+  if (typeof e === "function") return e;
+  const f = ease[e];
+  if (typeof f !== "function") throw new Error(`모르는 이징: ${String(e)}`);
+  return f as Ease;
+}

package/packages/core/src/frame.ts

@@ -0,0 +1,99 @@
+/**
+ * 지금 그리는 프레임의 전체 시각. 페이지의 seek(t) 가 setFrameTime 을 한 번 부르면
+ * React(useSyncExternalStore)·바닐라·three 가 onFrame 으로 같은 값을 받는다 — 시간 출처를 하나로 묶는 자리.
+ */
+let now = 0;
+const listeners = new Set<(t: number) => void>();
+
+export function setFrameTime(t: number): void {
+  if (!Number.isFinite(t)) throw new Error(`setFrameTime: 유한한 초가 아니다 (${t})`);
+  if (t === now) return;
+  now = t;
+  for (const fn of listeners) fn(t);
+}
+
+export const frameTime = (): number => now;
+
+export interface FrameSample {
+  /** 0..count-1 */
+  index: number;
+  count: number;
+}
+
+let sample: FrameSample = { index: 0, count: 1 };
+
+/**
+ * 모션 블러 하위 프레임 — 렌더가 한 프레임을 count 장으로 나눠 찍어 평균할 때 지금이 몇 번째인가.
+ * 3D 전환은 이 번호로 카메라를 조리개 위에서 흔들어, 같은 평균에서 피사계 심도까지 얻는다. 평소엔 { 0, 1 }
+ */
+export function setFrameSample(index: number, count: number): void {
+  sample = count > 1 ? { index, count } : { index: 0, count: 1 };
+}
+
+export const frameSample = (): FrameSample => sample;
+
+export function onFrame(fn: (t: number) => void): () => void {
+  listeners.add(fn);
+  return () => {
+    listeners.delete(fn);
+  };
+}
+
+export type MotionEventKind = "pulse" | "shake" | "camera" | "flash" | "move";
+
+/** 검사(kf check)가 style.json 움직임 규칙 위반을 세는 기록. 효과가 0 이 아닌 프레임마다 한 줄 */
+export interface KfMotionEvent {
+  /** 전체 시각(초) — 그 프레임 */
+  t: number;
+  kind: MotionEventKind;
+  /** 부품 id */
+  source: string;
+  /** pulse 0..1, shake 는 px, camera 는 이동량(px 또는 배율 차), flash 0..1, move 1 */
+  value: number;
+  /** move 일 때 움직임 이름(fade·rise·whip …) — 같은 움직임 되풀이를 센다 */
+  name?: string;
+  scene?: string;
+}
+
+interface KfEventHost {
+  __kf?: { events?: KfMotionEvent[] };
+}
+
+const seen = new Set<string>();
+let fallback: KfMotionEvent[] = [];
+
+function sink(): KfMotionEvent[] {
+  const g = globalThis as unknown as KfEventHost;
+  if (typeof window === "undefined") return fallback;
+  g.__kf ??= {};
+  g.__kf.events ??= [];
+  return g.__kf.events;
+}
+
+/**
+ * 같은 프레임에서 같은 부품이 여러 번 그려져도(React 재렌더) 한 줄만 남긴다.
+ * seek 사이에 비우지 않는다 — 검사는 탭별 배열을 모아 합친다.
+ */
+export function emit(e: Omit<KfMotionEvent, "t"> & { t?: number }): void {
+  if (!(Math.abs(e.value) > 1e-3)) return;
+  const t = Math.round((e.t ?? now) * 1000) / 1000;
+  const key = `${t}|${e.kind}|${e.source}|${e.scene ?? ""}`;
+  if (seen.has(key)) return;
+  seen.add(key);
+  const row: KfMotionEvent = { t, kind: e.kind, source: e.source, value: Math.round(e.value * 1000) / 1000 };
+  if (e.name !== undefined) row.name = e.name;
+  if (e.scene !== undefined) row.scene = e.scene;
+  sink().push(row);
+}
+
+export function motionEvents(): KfMotionEvent[] {
+  return sink();
+}
+
+/** 시험·미리보기 다시 그리기용 */
+export function resetMotionEvents(): void {
+  seen.clear();
+  fallback = [];
+  const g = globalThis as unknown as KfEventHost;
+  if (typeof window !== "undefined" && g.__kf) g.__kf.events = [];
+}

package/packages/core/src/index.ts

@@ -0,0 +1,27 @@
+export { clamp, safeTime, lerp, progress, clip, seq, interpolate, toFrame, toTime } from "./time.ts";
+export type { Clip, Seq, SeqItem, SeqSlot } from "./time.ts";
+export { ease, bezier, toEase } from "./ease.ts";
+export type { Ease, EaseName } from "./ease.ts";
+export { spring, springDuration } from "./spring.ts";
+export type { SpringOpts } from "./spring.ts";
+export { rand, randRange, randInt, randNormal, pick, shuffle, noise1 } from "./rand.ts";
+export {
+  parseBeats,
+  createBeats,
+  setBeats,
+  loadBeats,
+  getBeats,
+  hasBeats,
+  beatAt,
+  nearestBeat,
+  pulse,
+  drop,
+  section,
+} from "./beats.ts";
+export type { Beats, BeatsJson, BeatGrid, PulseOpts, Phrase, Section, SectionKind } from "./beats.ts";
+export { combine, toCss, applyStyle } from "./style.ts";
+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";

package/packages/core/src/project.ts

@@ -0,0 +1,146 @@
+import { createBeats, type Beats } from "./beats.ts";
+
+export interface KfMeta {
+  fps: number;
+  width: number;
+  height: number;
+  /** 초 */
+  duration: number;
+}
+
+export interface SafeArea {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+
+export interface MotionRules {
+  /** drops-only: 드롭 구간에서만 박 펄스 · downbeats: 첫박만 · every-beat · off */
+  beatPulse: "drops-only" | "downbeats" | "every-beat" | "off";
+  shake: { on: ("drop" | "impact")[]; maxPerPhrase: number; maxPx: number };
+  cameraMove: "once-per-phrase" | "free" | "off";
+  /** false 면 이어지는 두 장면이 같은 등장 움직임을 쓰지 않는다 */
+  repeatSameMove: boolean;
+  /** 이보다 오래 화면이 멈추면 검사가 잡는다(초) */
+  maxFreezeSec: number;
+  /** 아무 1초에 화면 25% 넘게 번쩍이는 섬광이 이보다 많으면 검사 오류(빛 민감 발작 — ITU-R BT.1702 취지, 기본 3) */
+  maxFlashPerSec?: number;
+  /** 같은 구도가 이 초를 넘으면 검사 경고·오류(기본 1.5·3). 곡 구조를 따르는 뮤비·설명·시연은 틀이 5·8 로 덮는다 */
+  staticSec?: { warn: number; error: number };
+  /** 눈에 보이는 큰 움직임을 박마다 요구하는 곳 — every-beat 어디서나 · drop-sections 후렴·드롭 구간만(벌스는 화면 안 움직임으로 충분) */
+  beatMove?: "every-beat" | "drop-sections";
+  /** 기본 등장 움직임 · 이징 · 길이(초) — 숫자를 안 넣은 부품이 이걸 쓴다 */
+  enter?: string;
+  ease?: string;
+  durations?: { fast: number; base: number; slow: number };
+}
+
+export interface FontFace {
+  family: string;
+  src: string;
+  weight?: string;
+  style?: string;
+}
+
+/** style.json — presets/<이름>.json 을 프로젝트에 복사한 것 */
+export interface KfStyle {
+  name: string;
+  label: string;
+  /** light·dark — 검사가 대비를 볼 때 바탕 쪽을 고른다 */
+  scheme: "light" | "dark";
+  colors: {
+    bg: string;
+    surface: string;
+    raised: string;
+    line: string;
+    ink: string;
+    inkSoft: string;
+    dim: string;
+    accent: string;
+    accentSoft: string;
+    onAccent: string;
+    success: string;
+    danger: string;
+    warning: string;
+    [k: string]: string;
+  };
+  /** font-family 값. 셋 다 한글이 서는 글꼴로 끝난다 */
+  fonts: {
+    sans: string;
+    display: string;
+    mono: string;
+    faces?: FontFace[];
+    /**
+     * @font-face 묶음을 주는 CSS 주소. 구글 폰트 CSS 처럼 unicode-range 로 쪼갠 것은 피한다 —
+     * 화면에 처음 나온 글자 조각을 그때 받느라 그 프레임 글이 투명하게 찍힌다. 되도록 faces 에 한 파일로
+     */
+    css?: string[];
+  };
+  type: {
+    /** 1920×1080 기준 px. 화면 크기가 다르면 짧은 변 비율로 곱해 쓴다 */
+    hero: number;
+    title: number;
+    body: number;
+    caption: number;
+    weightDisplay: number;
+    weightBody: number;
+    tracking: string;
+  };
+  radius: { sm: number; md: number; lg: number; pill: number };
+  shadow: { soft: string; lift: string };
+  motion: MotionRules;
+  /** 디자인 출처·지킬 점 — 사람과 모델이 읽는다 */
+  notes?: string[];
+}
+
+export interface SceneCtx {
+  id: string;
+  /** 영상 전체에서 장면이 시작하는 시각(초) */
+  from: number;
+  dur: number;
+  meta: KfMeta;
+  /** 장면 시작을 0 으로 옮긴 박·드롭 시각. 곡이 없으면 드롭 없는 120 BPM 격자 */
+  beats: Beats;
+  style: KfStyle;
+  safe: SafeArea;
+  /** 프로젝트 assets/ 기준 경로 → 페이지에서 쓸 주소 */
+  asset(path: string): string;
+}
+
+/** 곡 없는 프로젝트용. pulse 는 늘 0(드롭이 없다), drop(i) 는 던진다 */
+export function silentBeats(duration: number, offset = 0): Beats {
+  const n = Math.max(2, Math.ceil(duration * 2) + 1);
+  return createBeats(
+    { duration, bpm: 120, beats: Array.from({ length: n }, (_, i) => i * 0.5), sections: [{ t: 0, kind: "intro" }], drops: [] },
+    offset,
+  );
+}
+
+/** 짧은 변 1080 을 1 로 본 배율 — 세로 쇼츠도 같은 type 값으로 맞는 크기가 나온다 */
+export const scaleOf = (meta: Pick<KfMeta, "width" | "height">): number => Math.min(meta.width, meta.height) / 1080;
+
+export function cssVars(style: KfStyle, meta?: Pick<KfMeta, "width" | "height">): string {
+  const k = meta ? scaleOf(meta) : 1;
+  const lines: string[] = [];
+  for (const [name, v] of Object.entries(style.colors)) lines.push(`--kf-${name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}: ${v};`);
+  lines.push(`--kf-font-sans: ${style.fonts.sans};`, `--kf-font-display: ${style.fonts.display};`, `--kf-font-mono: ${style.fonts.mono};`);
+  for (const t of ["hero", "title", "body", "caption"] as const) lines.push(`--kf-size-${t}: ${Math.round(style.type[t] * k)}px;`);
+  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};`);
+  return `:root {\n  ${lines.join("\n  ")}\n}`;
+}
+
+/** @font-face·@import 묶음. 설치된 글꼴을 먼저 쓰고 없으면 받는다 */
+export function fontCss(style: KfStyle): string {
+  const out: string[] = (style.fonts.css ?? []).map((u) => `@import url("${u}");`);
+  const formats: Record<string, string> = { woff2: "woff2", woff: "woff", ttf: "truetype", otf: "opentype" };
+  for (const f of style.fonts.faces ?? []) {
+    const ext = /\.(woff2|woff|ttf|otf)(?:[?#].*)?$/i.exec(f.src)?.[1].toLowerCase() ?? "woff2";
+    out.push(
+      `@font-face { font-family: "${f.family}"; src: local("${f.family}"), url("${f.src}") format("${formats[ext]}"); font-weight: ${f.weight ?? "100 900"}; font-style: ${f.style ?? "normal"}; font-display: block; }`,
+    );
+  }
+  return out.join("\n");
+}