kasaframe 0.0.0-stage → 0.1.1

package/packages/core/src/rand.ts

@@ -0,0 +1,56 @@
+/**
+ * 시드 고정 난수. 상태가 없어서 (seed, i) 만 같으면 어느 탭·어느 순서로 불러도 같은 값이다.
+ * Math.random 은 쓰지 않는다 — 탭 나눠 찍기에서 탭마다 다른 그림이 나온다.
+ */
+function hash32(n: number): number {
+  let h = n | 0;
+  h = Math.imul(h ^ (h >>> 16), 0x85ebca6b);
+  h = Math.imul(h ^ (h >>> 13), 0xc2b2ae35);
+  return (h ^ (h >>> 16)) >>> 0;
+}
+
+function seedOf(seed: number | string): number {
+  if (typeof seed === "number") return Number.isFinite(seed) ? Math.floor(seed * 1000003) | 0 : 0;
+  let h = 0x811c9dc5;
+  for (let i = 0; i < seed.length; i++) h = Math.imul(h ^ seed.charCodeAt(i), 0x01000193);
+  return h | 0;
+}
+
+/** [0, 1) */
+export function rand(seed: number | string, i = 0): number {
+  const s = seedOf(seed);
+  return hash32(hash32(s) ^ hash32(Math.imul((i | 0) + 0x9e3779b9, 0x27d4eb2d))) / 4294967296;
+}
+
+export const randRange = (seed: number | string, i: number, lo: number, hi: number): number => lo + (hi - lo) * rand(seed, i);
+
+export const randInt = (seed: number | string, i: number, lo: number, hi: number): number =>
+  Math.min(hi, lo + Math.floor((hi - lo + 1) * rand(seed, i)));
+
+export const pick = <T>(seed: number | string, i: number, items: readonly T[]): T => items[randInt(seed, i, 0, items.length - 1)];
+
+/** 평균 0 표준편차 1 근사(박스-뮐러) */
+export function randNormal(seed: number | string, i: number): number {
+  const u = Math.max(rand(seed, i * 2), 1e-12);
+  const v = rand(seed, i * 2 + 1);
+  return Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v);
+}
+
+export function shuffle<T>(seed: number | string, items: readonly T[]): T[] {
+  const a = items.slice();
+  for (let i = a.length - 1; i > 0; i--) {
+    const j = randInt(seed, i, 0, i);
+    [a[i], a[j]] = [a[j], a[i]];
+  }
+  return a;
+}
+
+/** 부드럽게 흔들리는 1차원 잡음 [-1, 1]. 정수 격자의 시드 난수를 코사인으로 잇는다 */
+export function noise1(seed: number | string, x: number): number {
+  const i = Math.floor(x);
+  const f = x - i;
+  const a = rand(seed, i) * 2 - 1;
+  const b = rand(seed, i + 1) * 2 - 1;
+  const s = (1 - Math.cos(f * Math.PI)) / 2;
+  return a + (b - a) * s;
+}

package/packages/core/src/spring.ts

@@ -0,0 +1,52 @@
+export interface SpringOpts {
+  from?: number;
+  to?: number;
+  stiffness?: number;
+  damping?: number;
+  mass?: number;
+  /** t=0 에서 값이 변하는 속도(단위/초) */
+  velocity?: number;
+}
+
+const DEFAULTS = { from: 0, to: 1, stiffness: 170, damping: 26, mass: 1, velocity: 0 };
+
+/**
+ * 감쇠 조화 진동의 닫힌 해. 앞 프레임 상태를 이어 받지 않으므로 아무 t 로 건너뛰어도 같은 값이 나온다 —
+ * seek 모드와 탭 나눠 찍기가 이것에 기댄다.
+ */
+export function spring(t: number, opts: SpringOpts = {}): number {
+  const { from, to, stiffness, damping, mass, velocity } = { ...DEFAULTS, ...opts };
+  if (!(t > 0)) return from;
+  if (stiffness <= 0 || mass <= 0) return to;
+  const x0 = from - to;
+  const v0 = velocity;
+  const w0 = Math.sqrt(stiffness / mass);
+  const zeta = damping / (2 * Math.sqrt(stiffness * mass));
+  let x: number;
+  if (zeta < 1) {
+    const wd = w0 * Math.sqrt(1 - zeta * zeta);
+    x = Math.exp(-zeta * w0 * t) * (x0 * Math.cos(wd * t) + ((v0 + zeta * w0 * x0) / wd) * Math.sin(wd * t));
+  } else if (zeta === 1) {
+    x = Math.exp(-w0 * t) * (x0 + (v0 + w0 * x0) * t);
+  } else {
+    const s = Math.sqrt(zeta * zeta - 1);
+    const r1 = -w0 * (zeta - s);
+    const r2 = -w0 * (zeta + s);
+    const c2 = (v0 - r1 * x0) / (r2 - r1);
+    const c1 = x0 - c2;
+    x = c1 * Math.exp(r1 * t) + c2 * Math.exp(r2 * t);
+  }
+  return to + x;
+}
+
+/** 값이 목표에서 eps 안으로 들어와 다시 나가지 않는 첫 시각(초). 1/240 초 간격으로 훑는다 */
+export function springDuration(opts: SpringOpts = {}, eps = 0.001, max = 10): number {
+  const to = opts.to ?? DEFAULTS.to;
+  const span = Math.abs((opts.from ?? DEFAULTS.from) - to) || 1;
+  const dt = 1 / 240;
+  let settled = 0;
+  for (let t = 0; t <= max; t += dt) {
+    if (Math.abs(spring(t, opts) - to) / span > eps) settled = t + dt;
+  }
+  return Math.min(settled, max);
+}

package/packages/core/src/style.ts

@@ -0,0 +1,100 @@
+/**
+ * 움직임 원형이 돌려주는 값. CSS 도 three 도 아닌 일반 객체라 어댑터가 제 값으로 바꾼다.
+ * 없는 칸은 「바꾸지 않음」이다 — 0 이나 기본값을 채워 넣지 않는다.
+ */
+export interface Style {
+  opacity?: number;
+  /** px */
+  x?: number;
+  y?: number;
+  z?: number;
+  scale?: number;
+  scaleX?: number;
+  scaleY?: number;
+  /** 도 */
+  rotate?: number;
+  rotateX?: number;
+  rotateY?: number;
+  skewX?: number;
+  /** px */
+  blur?: number;
+  brightness?: number;
+  /** 가려 보이는 비율 0..1 — 위·오른쪽·아래·왼쪽에서 얼마나 깎는지 */
+  clip?: { top?: number; right?: number; bottom?: number; left?: number };
+}
+
+const num = (v: number | undefined, fallback: number): number => (v !== undefined && Number.isFinite(v) ? v : fallback);
+
+/** 겹쳐 쓰기: 투명도·배율은 곱하고, 이동·회전·흐림은 더하고, 가림은 큰 쪽을 쓴다 */
+export function combine(...styles: (Style | undefined | null | false)[]): Style {
+  const out: Style = {};
+  for (const s of styles) {
+    if (!s) continue;
+    if (s.opacity !== undefined) out.opacity = num(out.opacity, 1) * num(s.opacity, 1);
+    for (const k of ["x", "y", "z", "rotate", "rotateX", "rotateY", "skewX", "blur"] as const) {
+      if (s[k] !== undefined) out[k] = num(out[k], 0) + num(s[k], 0);
+    }
+    for (const k of ["scale", "scaleX", "scaleY", "brightness"] as const) {
+      if (s[k] !== undefined) out[k] = num(out[k], 1) * num(s[k], 1);
+    }
+    if (s.clip) {
+      const c = (out.clip ??= {});
+      for (const side of ["top", "right", "bottom", "left"] as const) {
+        const v = s.clip[side];
+        if (v !== undefined) c[side] = Math.max(num(c[side], 0), num(v, 0));
+      }
+    }
+  }
+  return out;
+}
+
+const r = (v: number, d = 3): number => {
+  const m = 10 ** d;
+  return Math.round(v * m) / m;
+};
+
+export interface CssStyle {
+  opacity?: number;
+  transform?: string;
+  filter?: string;
+  clipPath?: string;
+}
+
+/** React style 객체로 바로 넘길 수 있는 꼴. 유한하지 않은 값은 버린다 — NaN 이 CSS 로 새면 요소가 통째로 사라진다 */
+export function toCss(s: Style): CssStyle {
+  const out: CssStyle = {};
+  if (s.opacity !== undefined && Number.isFinite(s.opacity)) out.opacity = r(Math.min(1, Math.max(0, s.opacity)));
+  const tf: string[] = [];
+  const x = num(s.x, 0);
+  const y = num(s.y, 0);
+  const z = num(s.z, 0);
+  if (x || y || z) tf.push(z ? `translate3d(${r(x)}px, ${r(y)}px, ${r(z)}px)` : `translate(${r(x)}px, ${r(y)}px)`);
+  if (s.rotate !== undefined && Number.isFinite(s.rotate) && s.rotate !== 0) tf.push(`rotate(${r(s.rotate)}deg)`);
+  if (s.rotateX !== undefined && Number.isFinite(s.rotateX) && s.rotateX !== 0) tf.push(`rotateX(${r(s.rotateX)}deg)`);
+  if (s.rotateY !== undefined && Number.isFinite(s.rotateY) && s.rotateY !== 0) tf.push(`rotateY(${r(s.rotateY)}deg)`);
+  if (s.skewX !== undefined && Number.isFinite(s.skewX) && s.skewX !== 0) tf.push(`skewX(${r(s.skewX)}deg)`);
+  const sx = num(s.scale, 1) * num(s.scaleX, 1);
+  const sy = num(s.scale, 1) * num(s.scaleY, 1);
+  if (sx !== 1 || sy !== 1) tf.push(sx === sy ? `scale(${r(sx, 4)})` : `scale(${r(sx, 4)}, ${r(sy, 4)})`);
+  if (tf.length) out.transform = tf.join(" ");
+  const fl: string[] = [];
+  if (s.blur !== undefined && Number.isFinite(s.blur) && s.blur > 0.01) fl.push(`blur(${r(s.blur, 2)}px)`);
+  if (s.brightness !== undefined && Number.isFinite(s.brightness) && s.brightness !== 1) fl.push(`brightness(${r(s.brightness)})`);
+  if (fl.length) out.filter = fl.join(" ");
+  if (s.clip) {
+    const pc = (v: number | undefined) => `${r(Math.min(1, Math.max(0, num(v, 0))) * 100, 2)}%`;
+    out.clipPath = `inset(${pc(s.clip.top)} ${pc(s.clip.right)} ${pc(s.clip.bottom)} ${pc(s.clip.left)})`;
+  }
+  return out;
+}
+
+const kebab = (k: string): string => k.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+
+/** 바닐라 DOM 용. 이전 프레임에 있던 칸이 이번에 빠져도 남지 않게 네 칸을 늘 다시 쓴다 */
+export function applyStyle(el: { style: CSSStyleDeclaration }, s: Style): void {
+  const css = toCss(s);
+  for (const k of ["opacity", "transform", "filter", "clipPath"] as const) {
+    const v = css[k];
+    el.style.setProperty(kebab(k), v === undefined ? "" : String(v));
+  }
+}

package/packages/core/src/time.ts

@@ -0,0 +1,88 @@
+export interface Clip {
+  /** 구간 시작에서 잰 시각(초). 구간 밖이어도 그대로 — 앞이면 음수 */
+  local: number;
+  /** 0..1 로 자른 진행도 */
+  p: number;
+  active: boolean;
+}
+
+export const clamp = (v: number, lo = 0, hi = 1): number => (v < lo ? lo : v > hi ? hi : v === v ? v : lo);
+
+/** NaN 시각은 0 으로 — 움직임 입구에서 한 번 걸러 화면 값에 NaN 이 번지지 않게 */
+export const safeTime = (t: number): number => (typeof t === "number" && t === t ? t : 0);
+
+export const lerp = (a: number, b: number, p: number): number => a + (b - a) * p;
+
+/** 0 길이 구간에서 0 으로 나누지 않게 — dur 0 은 시작하는 순간 끝난 것으로 본다 */
+export const progress = (t: number, from: number, dur: number): number =>
+  dur > 0 ? clamp((t - from) / dur) : t >= from ? 1 : 0;
+
+export function clip(t: number, from: number, dur: number): Clip {
+  const local = t - from;
+  return { local, p: progress(t, from, dur), active: local >= 0 && local < dur };
+}
+
+export interface SeqItem {
+  id?: string;
+  dur: number;
+  /** 앞 항목과 겹치는 길이(초). 전환에 쓴다 */
+  overlap?: number;
+}
+
+export interface SeqSlot {
+  id: string;
+  index: number;
+  from: number;
+  to: number;
+  dur: number;
+}
+
+export interface Seq {
+  items: SeqSlot[];
+  duration: number;
+  /** t 에서 그려야 할 항목들 — 겹치는 구간이면 둘 */
+  at(t: number): (SeqSlot & Clip)[];
+}
+
+export function seq(items: SeqItem[], start = 0): Seq {
+  let cursor = start;
+  const slots: SeqSlot[] = items.map((it, index) => {
+    const from = index === 0 ? cursor : cursor - (it.overlap ?? 0);
+    cursor = from + it.dur;
+    return { id: it.id ?? String(index), index, from, to: from + it.dur, dur: it.dur };
+  });
+  return {
+    items: slots,
+    duration: cursor - start,
+    at: (t) => slots.filter((s) => t >= s.from && t < s.to).map((s) => ({ ...s, ...clip(t, s.from, s.dur) })),
+  };
+}
+
+type Easing = (p: number) => number;
+
+/**
+ * 값 구간 사상. 입력은 오름차순이어야 하고, 밖은 기본으로 끝값에 붙인다(clamp).
+ * NaN 이 들어오면 첫 출력값을 돌려 화면에 NaN 이 새지 않게 한다.
+ */
+export function interpolate(
+  v: number,
+  input: readonly number[],
+  output: readonly number[],
+  opts: { ease?: Easing; extrapolate?: "clamp" | "extend" } = {},
+): number {
+  if (input.length !== output.length || input.length < 2) throw new Error("interpolate: input·output 길이가 같고 2 이상이어야 한다");
+  if (!Number.isFinite(v)) return output[0];
+  const ext = opts.extrapolate ?? "clamp";
+  let i = 1;
+  while (i < input.length - 1 && v > input[i]) i++;
+  const a = input[i - 1];
+  const b = input[i];
+  let p = b === a ? (v >= b ? 1 : 0) : (v - a) / (b - a);
+  if (ext === "clamp") p = clamp(p);
+  if (opts.ease && p >= 0 && p <= 1) p = opts.ease(p);
+  return lerp(output[i - 1], output[i], p);
+}
+
+/** 초 ↔ 프레임. 프레임 경계 오차로 같은 프레임을 두 번 찍지 않게 반올림한다 */
+export const toFrame = (t: number, fps: number): number => Math.round(t * fps);
+export const toTime = (frame: number, fps: number): number => frame / fps;

package/packages/gen/PROVIDERS.md

@@ -0,0 +1,55 @@
+# 생성 모델 — 비용·속도·라이선스·지역 (2026-10-08 조사)
+
+`kf gen models` 가 같은 표를 키 유무와 함께 찍는다. 값이 바뀌면 `src/video/*.ts`·`src/image/og.ts` 의 단가와 이 표를 같이 고친다.
+
+## 그림
+
+| 공급자 id | 모델 | 단가 | 1920x1080 한 장 | 걸린 시간(실측) | 라이선스 · 지역 |
+|---|---|---|---|---|---|
+| `og-gpt-image-2.5-sunburst` (기본) | OG `openai/gpt-image-2.5-sunburst` | 1M 토큰당 글 입력 $5 · 그림 입력 $8 · 그림 출력 $30 | medium $0.011(실측) · high 약 $0.08 | 생성 20–28초 · 편집 20초 | OpenAI 약관 — 출력물 권리 사용자, 상업 가능 · OG live 전 세계 |
+| `og-gpt-image-2.5-flare` | OG `openai/gpt-image-2.5-flare` | 같음 | 같음 | 더 빠르다고 함(미측정) | 같음 |
+| `og-gpt-image-2` | OG `openai/gpt-image-2` | 같음 | 같은 품질값에서 토큰 더 씀 | — | 같음 |
+
+- 투명 배경: 2.5 는 `background: transparent` 를 직접 받는다(실측 알파 61%). 안 되면 한 장 더 써서 초록 바탕 + ffmpeg 키잉으로 간다(`notes` 에 `alpha-failed`).
+- 참조 편집은 `/v1/images/edits` multipart. 참조는 흰 바탕 512px JPEG 로 보낸다(OG 업로드 413 한도). 참조가 먹었는지는 `usage.input_tokens_details.image_tokens > 0` 으로만 안다 — 0 이면 `notes` 에 `refs-ignored`.
+- 크기: 변이 16의 배수여야 해서 1080 은 1088 로 만든 뒤 잘라 맞춘다(`notes` 에 `fit`).
+
+## 영상
+
+OG `/v1/models` 에는 영상 모델이 없다(2026-10-08 — 출력 모달리티는 text·image·embedding·decision 뿐). 영상은 공급자에 직접 붙는다.
+
+| 공급자 id | 단가 | 5초 720p | 길이 | 첫+끝 프레임 | 속도 | 라이선스 | 지역 | 키 |
+|---|---|---|---|---|---|---|---|---|
+| `h3-pod` (설정돼 있으면 기본) | GPU 자체 호스팅 — API 요금 없음, GPU 한 장이라 줄 선다 | $0 | 4–15초(서버 검증, 짧은 이음매는 4초로 만들어 맞춰 감는다) | 됨(fl2va 키프레임 0·-1) | L40S 1344x768·5초: 터보 LoRA 9걸음 170초, LoRA 없이 50걸음 940초(파드 운영자 실측) | **공개 가중치 — 지역 제한 확인 필요**: MiniMax H3 커뮤니티 라이선스가 한국을 제외 지역으로 두고 산출물에도 걸린다. 밖에 낼 결과물에는 쓰기 전에 확인 | 사내 | `KF_H3_URL`(SGLang 주소, 터널이면 `http://127.0.0.1:<포트>`) |
+| `fal-wan-2.2-turbo` (기본) | 클립당 720p $0.10 · 580p $0.075 · 480p $0.05 | **$0.10** | 5초 고정(81프레임@16fps) | 됨 | 빠름(수십 초) | 가중치 Apache-2.0 — 출력 상업 가능 | 제한 없음 · fal(미국) API 한국 결제 가능 | `FAL_KEY` |
+| `fal-wan-2.2` | 초당 720p $0.08 · 580p $0.06 · 480p $0.04 (16fps 기준 초) | $0.41 | 1–10초 | 됨 | 1분 안팎 | Apache-2.0 | 제한 없음 | `FAL_KEY` |
+| `fal-kling-3-std` | 초당 $0.084(소리 끔) · $0.126(소리) | $0.42 | 3–15초 | 됨 | 약 2–2.5분 | Kling API 약관 — 유료 생성물 상업 가능 | fal 경유 한국 가능 | `FAL_KEY` |
+| `fal-kling-3-pro` | 초당 $0.112(소리 끔) · $0.168(소리) | $0.56 | 3–15초 | 됨 | 약 2–2.5분 | 같음 | 같음 | `FAL_KEY` |
+| `minimax-h3` | 초당 768P $0.08 · 2K $0.13, 참조 그림 6장째부터 $0.04 | $0.40 | 4–15초 | 됨 | 느림(OpenRouter 기준 약 6분) | API 약관 상업 가능. **공개 가중치는 한국·미국·EU·영국 제외**(신청제), 2천만 달러 넘는 매출·UI 표기·증류 금지 조건 | API 전 세계(한국 포함) | `MINIMAX_API_KEY` |
+| `veo-3.1-lite` | 초당 720p $0.05 · 1080p $0.08 | $0.30(6초로 올림) | 4·6·8초 (1080p 는 8초만) | 됨 | 1–2분(미측정) | Google 약관, SynthID 워터마크 | Gemini API 한국 제공, 사람은 `allow_adult` 만 | `GEMINI_API_KEY` |
+| `veo-3.1-fast` | 초당 720p $0.10 · 1080p $0.12 | $0.60(6초) | 4·6·8초 | 됨 | 1–2분(미측정) | 같음 | 같음 | `GEMINI_API_KEY` |
+| `ltx-2-3-fast` | 초당 1080p $0.06 · 1440p $0.12 · 4K $0.24 | $0.36(6초부터) | 6–20초(1080p) | 됨 | 8초 첫+끝 약 33초(Runware 기준) | LTX 커뮤니티 — **연 매출 1천만 달러 미만 무료**, 넘으면 계약 | 전 세계 | `LTX_API_KEY` |
+
+나중 후보(v0 에서 안 감쌌다):
+
+- **Wan 2.2 를 Modal 에 직접 띄우기** — 클립당 비용은 GPU 초 단위라 많이 뽑을수록 싸지만 띄우는 일과 콜드 스타트가 든다. 많이 뽑는 단계에서.
+- **Kling 직접 API** — 키(`~/.secrets/gcp-sm/kling-api-credentials`)는 있으나 잔액 충전이 따로다. fal 경유가 같은 값이라 v0 은 fal 로.
+- **MiniMax H3 Max**(fal 후학습 고속판, 480P $0.05/초) — 끝 프레임을 받는지 확인 전.
+
+## 고르는 법
+
+- 이름을 안 주면 **키가 있는 것 중 견적이 가장 싼 것**(끝 프레임이 필요하면 그걸 받는 것만). `KF_H3_URL` 이 있으면 `h3-pod`(0원), 없으면 `fal-wan-2.2-turbo`.
+- `h3-pod` 걸음 수는 `KF_H3_STEPS` 로 꼭 준다(기본값 없음). 서버에 터보 LoRA 가 걸려 있으면 9, 없으면 50 — 터보가 걸린 채 50 을 주면 학습과 다른 스케줄이라 그림이 틀어진다. LoRA 는 서버 전체 상태라 kasaframe 이 걸거나 풀지 않고 파드 운영자에게 상태를 묻는다. 같은 시드라도 걸음 수가 다르면 다른 그림이다(캐시 키에도 들어간다). `quality` 는 보내지 않는다(터보와 `high` 를 같이 쓰면 안 된다). 서버마다 다른 필드는 `KF_H3_EXTRA`(JSON)로 얹는다.
+- 짧은 이음매(1–2초)도 5초로 만들어 장면 길이에 맞춰 빨리 감는다(`retime`). 움직임이 빨라 보이면 `fal-wan-2.2` 로 길이를 맞춰 뽑는다.
+- 소리 없이 쓴다 — 곡이 소리를 쥔다. Kling·LTX 는 `generate_audio:false` 로 부른다.
+- 이음매 실측(h3-pod, 터보 9걸음, 4초→2초): H3 는 16:9 프레임을 1344x768 로 **잘라 내지 않고 늘려** 받는다 — 프로젝트 크기로 되늘려야 자리가 겹친다. 첫 키프레임은 꽉 붙잡고(PSNR 37.8 dB) 끝 키프레임은 몇 픽셀 밀린다(24.6 dB). 양 끝 0.15초를 진짜 앞뒤 프레임으로 녹이면 48.8·44.8 dB, 렌더한 영상에서 경계 이웃 프레임 차이(39 dB)가 장면 안 이웃 프레임(33–36 dB)보다 작아 컷이 안 보인다.
+- 검증 상태: OG 그림은 실호출로 확인. 영상은 h3-pod 로 시험한다(fal·Veo 실호출은 하지 않기로 함). fal·MiniMax·Veo·LTX 는 문서대로 짰고 아직 안 불렀다.
+
+## 출처
+
+- MiniMax H3: platform.minimax.io/docs/guides/video-generation · 가중치 라이선스 huggingface.co/MiniMaxAI/MiniMax-H3 (Excluded Territories: EU·UK·Republic of Korea·USA)
+- fal Wan 2.2: fal.ai/models/fal-ai/wan/v2.2-a14b/image-to-video · /turbo
+- fal Kling 3: fal.ai/models/fal-ai/kling-video/v3/standard/image-to-video · /pro
+- Veo 3.1: ai.google.dev/gemini-api/docs/veo · 단가 ai.google.dev/gemini-api/docs/pricing (2026-09-24 갱신분)
+- LTX: docs.ltx.io/pricing · ltx.io/model/license
+- gpt-image-2.5: developers.openai.com/api/docs/pricing

package/packages/gen/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@kasaframe/gen",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  }
+}

package/packages/gen/src/generate.ts

@@ -0,0 +1,204 @@
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { chromaKey, fitImage, KEY_BG, probe, transparentRatio } from "./media.ts";
+import { apiSize } from "./image/og.ts";
+import { pickImage, pickVideo } from "./registry.ts";
+import type { Asset, AssetKind, AssetMeta, ImageProvider, ImageRequest, ProviderInfo, RawResult, VideoRequest } from "./types.ts";
+
+export interface GenContext {
+  outDir: string; // 보통 <proj>/assets/gen
+  cacheDir?: string;
+  maxUsd?: number; // 영상 하나 상한
+  imageMaxUsd?: number; // 그림 한 장 상한
+  approve?: boolean; // 영상은 이게 true 일 때만 돈을 쓴다
+  log?: (line: string) => void;
+}
+
+export const DEFAULT_MAX_USD = 1;
+export const DEFAULT_IMAGE_MAX_USD = 0.25;
+
+// 돈을 쓰기 전에 멈춘 이유. CLI 는 이걸 보고 종료 코드 3 과 견적을 낸다.
+export class NeedsApproval extends Error {
+  estimateUsd: number;
+  provider: string;
+  constructor(provider: string, estimateUsd: number, why: string) {
+    super(`${why} — ${provider} 견적 $${estimateUsd.toFixed(3)}`);
+    this.provider = provider;
+    this.estimateUsd = estimateUsd;
+  }
+}
+
+export function cacheDir(ctx: GenContext): string {
+  return ctx.cacheDir ?? process.env.KF_GEN_CACHE ?? join(homedir(), ".cache", "kasaframe", "gen");
+}
+
+function stable(v: unknown): unknown {
+  if (Array.isArray(v)) return v.map(stable);
+  if (v && typeof v === "object") {
+    return Object.fromEntries(
+      Object.keys(v)
+        .filter((k) => (v as any)[k] !== undefined)
+        .sort()
+        .map((k) => [k, stable((v as any)[k])]),
+    );
+  }
+  return v;
+}
+
+export function sha256(data: Uint8Array | string): string {
+  return createHash("sha256").update(data).digest("hex");
+}
+
+// 입력 파일은 경로가 아니라 내용으로 센다 — 같은 그림을 다른 곳에 두어도 같은 결과를 다시 쓴다.
+export function cacheKey(kind: AssetKind, p: ProviderInfo, req: object, inputs: { role: string; sha256: string }[]): string {
+  const r: Record<string, unknown> = { ...req };
+  for (const k of ["refs", "firstFrame", "lastFrame"]) delete r[k];
+  return sha256(JSON.stringify(stable({ kind, provider: p.id, model: p.model, variant: p.variant, req: r, inputs })));
+}
+
+function inputsOf(req: { refs?: string[]; firstFrame?: string; lastFrame?: string }): { role: string; sha256: string }[] {
+  const list: { role: string; path: string }[] = [
+    ...(req.refs ?? []).map((path, i) => ({ role: `ref${i}`, path })),
+    ...(req.firstFrame ? [{ role: "first", path: req.firstFrame }] : []),
+    ...(req.lastFrame ? [{ role: "last", path: req.lastFrame }] : []),
+  ];
+  return list.map(({ role, path }) => {
+    if (!existsSync(path)) throw new Error(`입력 파일 없음: ${path}`);
+    return { role, sha256: sha256(readFileSync(path)) };
+  });
+}
+
+// 1024x1024 출력 토큰(OpenAI 계산기, 2.5 계열). 실제 비용은 응답 usage 로 다시 적는다.
+const IMAGE_TOKENS: Record<string, number> = { low: 196, medium: 439, high: 1756, xhigh: 3122, max: 7024, auto: 1756 };
+
+export function estimateImageUsd(req: ImageRequest): number {
+  const { w, h } = apiSize(req.size);
+  const out = (IMAGE_TOKENS[req.quality ?? "high"] ?? 1756) * ((w * h) / 1_048_576) * 30e-6;
+  const refs = (req.refs?.length ?? 0) * 1024 * 8e-6;
+  return out + refs;
+}
+
+function fromCache(id: string, key: string, ctx: GenContext): Asset | null {
+  const dir = cacheDir(ctx);
+  const metaPath = join(dir, `${key}.json`);
+  if (!existsSync(metaPath)) return null;
+  const meta = JSON.parse(readFileSync(metaPath, "utf8")) as AssetMeta;
+  const src = join(dir, meta.file);
+  if (!existsSync(src)) return null;
+  mkdirSync(ctx.outDir, { recursive: true });
+  const file = `${id}.${meta.file.split(".").pop()}`;
+  const path = join(ctx.outDir, file);
+  if (!existsSync(path) || sha256(readFileSync(path)) !== sha256(readFileSync(src))) copyFileSync(src, path);
+  const out = { ...meta, id, file };
+  writeFileSync(join(ctx.outDir, `${id}.json`), JSON.stringify(out, null, 2) + "\n");
+  return { path, meta: out, cached: true };
+}
+
+async function store(
+  id: string,
+  kind: AssetKind,
+  key: string,
+  p: ProviderInfo,
+  prompt: string,
+  raw: RawResult,
+  tmpPath: string,
+  inputs: AssetMeta["inputs"],
+  elapsedMs: number,
+  ctx: GenContext,
+): Promise<Asset> {
+  const dir = cacheDir(ctx);
+  const ext = tmpPath.split(".").pop()!;
+  const cached = join(dir, `${key}.${ext}`);
+  renameSync(tmpPath, cached);
+  const pr = await probe(cached);
+  const meta: AssetMeta = {
+    id,
+    kind,
+    file: basename(cached),
+    provider: p.id,
+    model: raw.model,
+    prompt,
+    seed: raw.seed,
+    params: raw.params,
+    inputs,
+    costUsd: Number(raw.costUsd.toFixed(5)),
+    costEstimated: raw.costEstimated,
+    elapsedMs,
+    license: p.license,
+    region: p.region,
+    cacheKey: key,
+    createdAt: new Date().toISOString(),
+    width: pr.width,
+    height: pr.height,
+    ...(kind === "vid" ? { duration: pr.duration, fps: pr.fps } : {}),
+    ...(raw.notes?.length ? { notes: raw.notes } : {}),
+  };
+  writeFileSync(join(dir, `${key}.json`), JSON.stringify(meta, null, 2) + "\n");
+  return { ...fromCache(id, key, ctx)!, cached: false };
+}
+
+async function makeImage(p: ImageProvider, req: ImageRequest, tmp: string): Promise<RawResult> {
+  const call = (r: ImageRequest) => (r.refs?.length && p.edit ? p.edit(r) : p.generate(r));
+  let raw = await call(req);
+  writeFileSync(tmp, raw.bytes);
+  if (req.transparent) {
+    if (raw.notes?.includes("chroma-key")) {
+      await chromaKey(tmp, tmp);
+    } else if ((await transparentRatio(tmp)) < 0.005) {
+      // 투명을 받는다던 모델이 불투명하게 돌려줬다 — 한 장 더 써서 단색 바탕 + 키잉으로 간다.
+      const again = await call({ ...req, prompt: `${req.prompt}\n\n${KEY_BG}`, transparent: false });
+      writeFileSync(tmp, again.bytes);
+      await chromaKey(tmp, tmp);
+      raw = { ...again, costUsd: raw.costUsd + again.costUsd, notes: [...(again.notes ?? []), "alpha-failed", "chroma-key"] };
+    }
+  }
+  const { w, h } = apiSize(req.size);
+  const [rw, rh] = req.size.split("x").map(Number);
+  if (w !== rw || h !== rh) {
+    await fitImage(tmp, tmp, rw, rh);
+    raw.notes = [...(raw.notes ?? []), `fit ${w}x${h}->${rw}x${rh}`];
+  }
+  return raw;
+}
+
+export async function genImage(id: string, req: ImageRequest, ctx: GenContext, providerId?: string): Promise<Asset> {
+  const p = pickImage(providerId);
+  const inputs = inputsOf(req);
+  const key = cacheKey("img", p, req, inputs);
+  const hit = fromCache(id, key, ctx);
+  if (hit) return hit;
+  const est = estimateImageUsd(req);
+  const cap = ctx.imageMaxUsd ?? DEFAULT_IMAGE_MAX_USD;
+  if (est > cap) throw new NeedsApproval(p.id, est, `그림 한 장 상한 $${cap} 초과`);
+  mkdirSync(cacheDir(ctx), { recursive: true });
+  const tmp = join(cacheDir(ctx), `.${key}.tmp.png`);
+  ctx.log?.(`그림 ${id}: ${p.id} 견적 $${est.toFixed(3)}`);
+  const t0 = Date.now();
+  const raw = await makeImage(p, req, tmp);
+  return store(id, "img", key, p, req.prompt, raw, tmp, inputs, Date.now() - t0, ctx);
+}
+
+export function planVideo(req: VideoRequest, ctx: GenContext, providerId?: string) {
+  const p = pickVideo(providerId, req);
+  const inputs = inputsOf(req);
+  const key = cacheKey("vid", p, req, inputs);
+  return { provider: p, inputs, key, estimateUsd: p.estimateUsd(req), cached: existsSync(join(cacheDir(ctx), `${key}.json`)) };
+}
+
+export async function genVideo(id: string, req: VideoRequest, ctx: GenContext, providerId?: string): Promise<Asset> {
+  const { provider: p, inputs, key, estimateUsd: est } = planVideo(req, ctx, providerId);
+  const hit = fromCache(id, key, ctx);
+  if (hit) return hit;
+  const cap = ctx.maxUsd ?? DEFAULT_MAX_USD;
+  if (est > cap) throw new NeedsApproval(p.id, est, `영상 하나 상한 $${cap} 초과`);
+  if (!ctx.approve) throw new NeedsApproval(p.id, est, "영상 생성은 승인(--yes)이 있어야 돌린다");
+  mkdirSync(cacheDir(ctx), { recursive: true });
+  ctx.log?.(`영상 ${id}: ${p.id} 견적 $${est.toFixed(3)} — 생성 중(몇십 초~몇 분)`);
+  const t0 = Date.now();
+  const raw = await p.generate(req);
+  const tmp = join(cacheDir(ctx), `.${key}.tmp.${raw.ext}`);
+  writeFileSync(tmp, raw.bytes);
+  return store(id, "vid", key, p, req.prompt, raw, tmp, inputs, Date.now() - t0, ctx);
+}