kasaframe 0.0.0-stage → 0.1.3

package/packages/themes/src/stage3d.ts

@@ -0,0 +1,197 @@
+import type { SceneCtx } from "@kasaframe/core";
+import * as THREE from "three";
+import { RoomEnvironment } from "three/examples/jsm/environments/RoomEnvironment.js";
+
+// 입체 테마가 같이 쓰는 바탕 — 렌더러 하나·한글 글자판·환경광. 테마의 효과(rig)는 이 위에 물체를 얹고 t 로 움직인다.
+
+let shared: THREE.WebGLRenderer | null = null;
+
+// 크롬은 한 페이지에 WebGL 문맥을 16 개쯤만 살려 둔다 — 장면이 여럿이어도 렌더러 하나를 돌려 쓰고, 그리는 장면으로 캔버스를 옮긴다
+export function renderer3d(w: number, h: number): THREE.WebGLRenderer {
+  if (!shared) {
+    shared = new THREE.WebGLRenderer({ antialias: true, preserveDrawingBuffer: true, alpha: false, powerPreference: "high-performance" });
+    shared.setPixelRatio(1);
+    shared.outputColorSpace = THREE.SRGBColorSpace;
+    shared.toneMapping = THREE.ACESFilmicToneMapping;
+    shared.shadowMap.enabled = true;
+    shared.shadowMap.type = THREE.PCFSoftShadowMap;
+    shared.domElement.style.cssText = "position:absolute;inset:0;width:100%;height:100%;display:block";
+  }
+  const size = shared.getSize(new THREE.Vector2());
+  if (size.x !== w || size.y !== h) shared.setSize(w, h, false);
+  return shared;
+}
+
+let envTex: THREE.Texture | null = null;
+/** 방 하나의 빛을 환경 맵으로 — 금속·유리가 비칠 것이 생긴다. 한 번만 굽는다 */
+export function roomEnvironment(renderer: THREE.WebGLRenderer): THREE.Texture {
+  if (!envTex) {
+    const pmrem = new THREE.PMREMGenerator(renderer);
+    envTex = pmrem.fromScene(new RoomEnvironment(), 0.04).texture;
+    pmrem.dispose();
+  }
+  return envTex;
+}
+
+/** 3D 부품(rig) — 무대 위에 물체를 얹고 t 마다 움직인다. 같은 t 면 같은 자리 */
+export type Rig = (t: number) => void;
+
+export interface Stage3D {
+  scene: THREE.Scene;
+  camera: THREE.PerspectiveCamera | THREE.OrthographicCamera;
+  renderer: THREE.WebGLRenderer;
+  /** 무대가 박힌 DOM 자리(장면 루트 안) — 겹칠 DOM 은 여기 형제로 */
+  el: HTMLElement;
+  /** rig 를 등록 — paint(t) 가 카메라를 놓은 뒤 차례로 부른다 */
+  add(rig: Rig): void;
+  /** rig 를 다 부르고 그린다 */
+  paint(t: number): void;
+}
+
+export interface StageOpts {
+  ctx: SceneCtx;
+  camera?: "perspective" | "ortho";
+  fov?: number;
+  /** 정사영일 때 화면 세로에 담길 세계 단위 */
+  frustum?: number;
+  background?: string;
+  fog?: [near: number, far: number];
+  env?: boolean;
+  exposure?: number;
+  /** 카메라를 t 로 — 자리와 보는 곳 */
+  shot?(t: number, camera: THREE.Camera): void;
+}
+
+export function stage3d(root: HTMLElement, o: StageOpts): Stage3D {
+  const { ctx } = o;
+  const W = ctx.meta.width;
+  const H = ctx.meta.height;
+  const el = document.createElement("div");
+  el.style.cssText = "position:absolute;inset:0;";
+  root.append(el);
+  const renderer = renderer3d(W, H);
+  const scene = new THREE.Scene();
+  const bg = new THREE.Color(o.background ?? ctx.style.colors.bg);
+  scene.background = bg;
+  if (o.fog) scene.fog = new THREE.Fog(bg, o.fog[0], o.fog[1]);
+  if (o.env) scene.environment = roomEnvironment(renderer);
+  let camera: THREE.PerspectiveCamera | THREE.OrthographicCamera;
+  if (o.camera === "ortho") {
+    const f = o.frustum ?? 10;
+    const a = W / H;
+    camera = new THREE.OrthographicCamera((-f * a) / 2, (f * a) / 2, f / 2, -f / 2, 0.1, 400);
+  } else {
+    camera = new THREE.PerspectiveCamera(o.fov ?? 50, W / H, 0.1, 400);
+  }
+  const rigs: Rig[] = [];
+  return {
+    scene,
+    camera,
+    renderer,
+    el,
+    add: (rig) => rigs.push(rig),
+    paint(t) {
+      if (renderer.domElement.parentElement !== el) el.prepend(renderer.domElement);
+      renderer.toneMappingExposure = o.exposure ?? 1;
+      o.shot?.(t, camera);
+      for (const r of rigs) r(t);
+      renderer.render(scene, camera);
+    },
+  };
+}
+
+/**
+ * 서 있는 무대 — 처음 한 번만 그려 2D 캔버스로 옮겨 두고 그 뒤로는 다시 그리지 않는다.
+ * 움직이지 않는 3D 바탕(테마 슬롯 surface)을 프레임마다 SwiftShader 로 그릴 까닭이 없고, 렌더러 캔버스는 다른 무대가 가져가도 된다
+ */
+export function stillStage(stage: Stage3D, paint: (t: number) => void = (t) => stage.paint(t)): (t: number) => void {
+  let done = false;
+  return () => {
+    if (done) return;
+    paint(0);
+    const src = stage.renderer.domElement;
+    const c = document.createElement("canvas");
+    c.width = src.width;
+    c.height = src.height;
+    c.style.cssText = src.style.cssText;
+    c.getContext("2d")!.drawImage(src, 0, 0);
+    src.replaceWith(c);
+    done = true;
+  };
+}
+
+export interface TextPlaneOpts {
+  text: string;
+  /** CSS font 단축 꼴의 앞부분 없이 글꼴 스택만 — 굵기·크기는 따로 */
+  family: string;
+  weight?: number;
+  color: string;
+  /** 세계 단위 높이(글 한 줄) */
+  height: number;
+  /** 캔버스에 그릴 글 크기 px — 클수록 가까이서도 또렷하다 */
+  px?: number;
+  align?: "left" | "center" | "right";
+  /** 바탕을 칠하면 판, 없으면 투명 */
+  plate?: string;
+  pad?: number;
+  emissive?: boolean;
+}
+
+/** 한글이 서는 글꼴로 캔버스에 그린 글을 판(평면 메시)으로. 장면 build 에서 만든다(글꼴을 다 받은 뒤라 치수가 맞다) */
+export function textPlane(o: TextPlaneOpts): THREE.Mesh<THREE.PlaneGeometry, THREE.MeshBasicMaterial> {
+  const px = o.px ?? 160;
+  const pad = o.pad ?? px * 0.25;
+  const font = `${o.weight ?? 700} ${px}px ${o.family}`;
+  const probe = document.createElement("canvas").getContext("2d")!;
+  probe.font = font;
+  const w = Math.ceil(probe.measureText(o.text).width + pad * 2);
+  const h = Math.ceil(px * 1.3 + pad * 2);
+  const c = document.createElement("canvas");
+  c.width = w;
+  c.height = h;
+  const g = c.getContext("2d")!;
+  if (o.plate) {
+    g.fillStyle = o.plate;
+    g.fillRect(0, 0, w, h);
+  }
+  g.font = font;
+  g.fillStyle = o.color;
+  g.textBaseline = "middle";
+  g.textAlign = "left";
+  g.fillText(o.text, pad, h / 2);
+  const tex = new THREE.CanvasTexture(c);
+  tex.colorSpace = THREE.SRGBColorSpace;
+  tex.anisotropy = 4;
+  const worldH = (o.height * h) / (px * 1.3);
+  const worldW = (worldH * w) / h;
+  const geo = new THREE.PlaneGeometry(worldW, worldH);
+  if (o.align === "left") geo.translate(worldW / 2, 0, 0);
+  if (o.align === "right") geo.translate(-worldW / 2, 0, 0);
+  const mat = new THREE.MeshBasicMaterial({ map: tex, transparent: true, depthWrite: false, toneMapped: !o.emissive, side: THREE.DoubleSide });
+  return new THREE.Mesh(geo, mat);
+}
+
+/** 둥근 사각 테(관문) 모양 — OG 로고의 두 칸이 이 꼴이다 */
+export function roundRectShape(w: number, h: number, r: number, hole = 0): THREE.Shape {
+  const s = new THREE.Shape();
+  const rr = (p: THREE.Path | THREE.Shape, x: number, y: number, ww: number, hh: number, rad: number) => {
+    p.moveTo(x + rad, y);
+    p.lineTo(x + ww - rad, y);
+    p.quadraticCurveTo(x + ww, y, x + ww, y + rad);
+    p.lineTo(x + ww, y + hh - rad);
+    p.quadraticCurveTo(x + ww, y + hh, x + ww - rad, y + hh);
+    p.lineTo(x + rad, y + hh);
+    p.quadraticCurveTo(x, y + hh, x, y + hh - rad);
+    p.lineTo(x, y + rad);
+    p.quadraticCurveTo(x, y, x + rad, y);
+  };
+  rr(s, -w / 2, -h / 2, w, h, r);
+  if (hole > 0) {
+    const p = new THREE.Path();
+    rr(p, -w / 2 + hole, -h / 2 + hole, w - hole * 2, h - hole * 2, Math.max(0.01, r - hole * 0.6));
+    s.holes.push(p);
+  }
+  return s;
+}
+
+export { THREE };

package/packages/themes/src/types.ts

@@ -0,0 +1,58 @@
+import type { KfStyle } from "@kasaframe/core";
+
+/** draft 만드는 중 · review 견본이 나와 사람이 볼 차례 · approved 사람이 OK 해서 라이브러리에 정식으로 들어감 */
+export type ThemeStatus = "draft" | "review" | "approved";
+
+export const THEME_STATUSES: readonly ThemeStatus[] = ["draft", "review", "approved"];
+
+export interface ThemeEffectInfo {
+  /** effects.ts 의 이름 있는 내보내기와 같다 */
+  name: string;
+  /** value: (t, opts) => Style·수·글 · layer: (el, opts) => (t) => void · rig: (stage, opts) => (t) => void(3D 무대에 물체를 얹는다) — 모두 같은 t 면 같은 화면 */
+  kind: "value" | "layer" | "rig";
+  /** 무엇을 하나 — 한 줄 */
+  does: string;
+  /** 부르는 꼴 한 줄(모델이 그대로 베낀다) */
+  use: string;
+}
+
+/** themes/<id>/theme.json */
+export interface ThemeManifest {
+  id: string;
+  name: string;
+  /** 내용에서 나온 비유 한 줄 — 「무엇이 무엇처럼 되며 화면이 찍힌다」 */
+  metaphor: string;
+  status: ThemeStatus;
+  /** approved 로 바꾼 날(ISO). 그 전엔 null */
+  approvedAt: string | null;
+  /** 어울리는 용도 — templates/<id> */
+  purposes: string[];
+  /** 견본이 서는 화면비. 앞이 견본의 화면비 */
+  aspect: string[];
+  effects: ThemeEffectInfo[];
+  /** 테마 폴더 기준 파일 이름. 기본 still.png · sample.mp4 */
+  still?: string;
+  sample?: string;
+}
+
+export interface Theme extends ThemeManifest {
+  dir: string;
+  style: KfStyle;
+  /** THEME.md 원문 — 비유·맞는 내용·금지 */
+  guide: string;
+  /** 절대 경로. 파일이 아직 없으면 null */
+  files: { still: string | null; sample: string | null; sampleProject: string | null; effects: string };
+}
+
+/** 작업실·plan 이 목록에 쓰는 꼴. still·sample 은 절대 경로(없으면 null) */
+export interface ThemeCard {
+  id: string;
+  name: string;
+  metaphor: string;
+  status: ThemeStatus;
+  approvedAt: string | null;
+  still: string | null;
+  sample: string | null;
+  purposes: string[];
+  aspect: string[];
+}

package/presets/kawaii-pastel.json

@@ -0,0 +1,94 @@
+{
+  "name": "kawaii-pastel",
+  "label": "카와이 파스텔 — 퓨처베이스",
+  "scheme": "light",
+  "colors": {
+    "bg": "#FFF6FB",
+    "surface": "#FFFFFF",
+    "raised": "#FDE8F3",
+    "line": "#F6CFE4",
+    "ink": "#4A2B4F",
+    "inkSoft": "#6B4A70",
+    "dim": "#7E5F84",
+    "accent": "#FF7EB6",
+    "accentSoft": "#FFD1E6",
+    "accentText": "#C2387A",
+    "onAccent": "#4A2B4F",
+    "mint": "#7FD8C3",
+    "lavender": "#B9A7FF",
+    "sky": "#8FD3FF",
+    "lemon": "#FFE48A",
+    "peach": "#FFB59E",
+    "success": "#3CBF9A",
+    "danger": "#E5537A",
+    "warning": "#F2A93B"
+  },
+  "fonts": {
+    "sans": "\"Pretendard Variable\", Pretendard, \"Noto Sans KR\", \"Apple SD Gothic Neo\", sans-serif",
+    "display": "\"Jua\", \"Pretendard Variable\", \"Noto Sans KR\", \"Apple SD Gothic Neo\", sans-serif",
+    "mono": "\"JetBrains Mono\", ui-monospace, \"Pretendard Variable\", \"Noto Sans KR\", \"Apple SD Gothic Neo\", monospace",
+    "faces": [
+      {
+        "family": "Pretendard Variable",
+        "src": "https://cdn.jsdelivr.net/npm/pretendard@1.3.9/dist/web/variable/woff2/PretendardVariable.woff2",
+        "weight": "45 920"
+      },
+      {
+        "family": "JetBrains Mono",
+        "src": "https://cdn.jsdelivr.net/npm/@fontsource-variable/jetbrains-mono@5/files/jetbrains-mono-latin-wght-normal.woff2",
+        "weight": "100 800"
+      },
+      {
+        "family": "Jua",
+        "src": "https://cdn.jsdelivr.net/gh/google/fonts@main/ofl/jua/Jua-Regular.ttf",
+        "weight": "400"
+      }
+    ]
+  },
+  "type": {
+    "hero": 136,
+    "title": 80,
+    "body": 40,
+    "caption": 32,
+    "weightDisplay": 400,
+    "weightBody": 600,
+    "tracking": "-0.01em"
+  },
+  "radius": {
+    "sm": 16,
+    "md": 28,
+    "lg": 44,
+    "pill": 999
+  },
+  "shadow": {
+    "soft": "0 10px 30px rgba(255, 126, 182, 0.22)",
+    "lift": "0 6px 0 rgba(74, 43, 79, 0.12)"
+  },
+  "motion": {
+    "beatPulse": "drops-only",
+    "shake": {
+      "on": [
+        "drop"
+      ],
+      "maxPerPhrase": 1,
+      "maxPx": 10
+    },
+    "cameraMove": "once-per-phrase",
+    "repeatSameMove": false,
+    "maxFreezeSec": 0.5,
+    "enter": "pop",
+    "ease": "outBack",
+    "durations": {
+      "fast": 0.18,
+      "base": 0.36,
+      "slow": 0.7
+    }
+  },
+  "notes": [
+    "퓨처베이스 곡에 맞춘 밝은 파스텔. 분홍 강조 + 민트·라벤더·하늘·레몬을 보조로 한두 개만.",
+    "제목은 Jua(구글 폰트, OFL) — 굵기 한 벌뿐이라 weightDisplay 400. 본문은 Pretendard 600. 글꼴은 한 파일로 받는다(구글 CSS 의 unicode-range 조각은 안 쓴 글자 조각을 늦게 받아 font-display:block 동안 글이 투명하게 찍힌다).",
+    "accent 분홍은 바탕 위 글자로 2.2:1 — 글자는 accentText, 분홍은 면·반짝이·도형에.",
+    "등장은 pop + outBack 으로 통통 튀게. 그래도 박 펄스는 드롭에서만, 흔들림은 드롭에 한 번.",
+    "반짝이·파티클은 시드 고정(rand)으로 — 탭 나눠 찍어도 같은 자리."
+  ]
+}

package/presets/neutral-dark.json

@@ -0,0 +1,82 @@
+{
+  "name": "neutral-dark",
+  "label": "뉴트럴 다크",
+  "scheme": "dark",
+  "colors": {
+    "bg": "#0E0F12",
+    "surface": "#16181D",
+    "raised": "#1E2128",
+    "line": "#2C3038",
+    "ink": "#F2F3F5",
+    "inkSoft": "#C9CCD3",
+    "dim": "#8B909A",
+    "accent": "#8AB4FF",
+    "accentSoft": "rgba(138, 180, 255, 0.24)",
+    "accentText": "#8AB4FF",
+    "onAccent": "#0E0F12",
+    "success": "#4ADE80",
+    "danger": "#F87171",
+    "warning": "#FBBF24"
+  },
+  "fonts": {
+    "sans": "\"Pretendard Variable\", Pretendard, \"Noto Sans KR\", \"Apple SD Gothic Neo\", sans-serif",
+    "display": "\"Pretendard Variable\", Pretendard, \"Noto Sans KR\", \"Apple SD Gothic Neo\", sans-serif",
+    "mono": "\"Geist Mono\", ui-monospace, \"Pretendard Variable\", \"Noto Sans KR\", \"Apple SD Gothic Neo\", monospace",
+    "faces": [
+      {
+        "family": "Pretendard Variable",
+        "src": "https://cdn.jsdelivr.net/npm/pretendard@1.3.9/dist/web/variable/woff2/PretendardVariable.woff2",
+        "weight": "45 920"
+      },
+      {
+        "family": "Geist Mono",
+        "src": "https://cdn.jsdelivr.net/npm/geist@1.3.1/dist/fonts/geist-mono/GeistMono-Variable.woff2",
+        "weight": "100 900"
+      }
+    ]
+  },
+  "type": {
+    "hero": 124,
+    "title": 72,
+    "body": 38,
+    "caption": 30,
+    "weightDisplay": 720,
+    "weightBody": 450,
+    "tracking": "-0.025em"
+  },
+  "radius": {
+    "sm": 10,
+    "md": 16,
+    "lg": 24,
+    "pill": 999
+  },
+  "shadow": {
+    "soft": "0 12px 32px rgba(0, 0, 0, 0.45)",
+    "lift": "0 0 0 1px rgba(255, 255, 255, 0.06), 0 16px 40px rgba(0, 0, 0, 0.55)"
+  },
+  "motion": {
+    "beatPulse": "drops-only",
+    "shake": {
+      "on": [
+        "drop"
+      ],
+      "maxPerPhrase": 1,
+      "maxPx": 10
+    },
+    "cameraMove": "once-per-phrase",
+    "repeatSameMove": false,
+    "maxFreezeSec": 0.5,
+    "enter": "rise",
+    "ease": "snappy",
+    "durations": {
+      "fast": 0.15,
+      "base": 0.3,
+      "slow": 0.6
+    }
+  },
+  "notes": [
+    "어디에나 무난한 어두운 판. 무채색 면 세 층 + 차가운 파랑 강조 하나.",
+    "글은 ink·inkSoft 로, dim 은 보조 한 줄에만(5.9:1).",
+    "브랜드가 정해지지 않은 설명·시연 영상의 기본값."
+  ]
+}

package/presets/og.json

@@ -0,0 +1,98 @@
+{
+  "name": "og",
+  "label": "OpenGateway — 브랜드 파랑 한 색",
+  "scheme": "light",
+  "colors": {
+    "bg": "#FFFFFF",
+    "surface": "#F8FAFC",
+    "raised": "#F1F5F9",
+    "line": "#E2E8F0",
+    "ink": "#020817",
+    "inkSoft": "#1E293B",
+    "dim": "#64748B",
+    "accent": "#006FD6",
+    "accentSoft": "rgba(0, 111, 214, 0.45)",
+    "accentText": "#01509D",
+    "onAccent": "#FFFFFF",
+    "tint": "rgba(0, 111, 214, 0.08)",
+    "success": "#22C55E",
+    "danger": "#EF4444",
+    "warning": "#F59E0B",
+    "darkBg": "#090A0C",
+    "darkSurface": "#13151B",
+    "darkLine": "#39404F",
+    "darkInk": "#C6CAD6",
+    "darkAccent": "#0085FF"
+  },
+  "fonts": {
+    "sans": "\"Pretendard Variable\", Pretendard, \"Noto Sans KR\", \"Apple SD Gothic Neo\", sans-serif",
+    "display": "\"Geist\", \"Pretendard Variable\", \"Noto Sans KR\", \"Apple SD Gothic Neo\", sans-serif",
+    "mono": "\"Geist Mono\", ui-monospace, \"Pretendard Variable\", \"Noto Sans KR\", \"Apple SD Gothic Neo\", monospace",
+    "faces": [
+      {
+        "family": "Pretendard Variable",
+        "src": "https://cdn.jsdelivr.net/npm/pretendard@1.3.9/dist/web/variable/woff2/PretendardVariable.woff2",
+        "weight": "45 920"
+      },
+      {
+        "family": "Geist",
+        "src": "https://cdn.jsdelivr.net/npm/geist@1.3.1/dist/fonts/geist-sans/Geist-Variable.woff2",
+        "weight": "100 900"
+      },
+      {
+        "family": "Geist Mono",
+        "src": "https://cdn.jsdelivr.net/npm/geist@1.3.1/dist/fonts/geist-mono/GeistMono-Variable.woff2",
+        "weight": "100 900"
+      }
+    ]
+  },
+  "type": {
+    "hero": 132,
+    "title": 72,
+    "body": 38,
+    "caption": 30,
+    "weightDisplay": 800,
+    "weightBody": 500,
+    "tracking": "-0.055em"
+  },
+  "radius": {
+    "sm": 0,
+    "md": 12,
+    "lg": 12,
+    "pill": 999
+  },
+  "shadow": {
+    "soft": "none",
+    "lift": "none"
+  },
+  "motion": {
+    "beatPulse": "drops-only",
+    "shake": {
+      "on": [
+        "drop"
+      ],
+      "maxPerPhrase": 1,
+      "maxPx": 8
+    },
+    "cameraMove": "once-per-phrase",
+    "repeatSameMove": false,
+    "maxFreezeSec": 0.5,
+    "enter": "rise",
+    "ease": "snappy",
+    "durations": {
+      "fast": 0.15,
+      "base": 0.22,
+      "slow": 0.3
+    }
+  },
+  "notes": [
+    "출처: opengateway/cp-fe-og-styleguide/design.md + globals.css(:root 라이트), 쇼츠 mla-swa-remotion/src/mlahost/look.ts.",
+    "강조는 브랜드 파랑 하나, 빨강(danger)은 오류에만. 파랑 글자는 accentText(--on-primary).",
+    "면은 테두리 없이 색으로 가른다(bg 100% → surface 98% → raised 96%). 면 위에 border 를 겹쳐 그리지 않는다. 그림자 없음.",
+    "모서리는 세 칸뿐: 면 12px(md·lg), 그 밖 0(sm), 누르는 것 알약(pill). 영상엔 누르는 것이 거의 없다.",
+    "영문 대제목·큰 숫자는 Geist 800 자간 −0.055em(워드마크 결). Geist 에 한글이 없어 한글은 Pretendard 로 떨어진다 — 한글 제목은 700·자간 −0.045em·한 단계 작게.",
+    "코드·모델 ID·시각은 Geist Mono, 숫자는 tabular-nums.",
+    "움직임은 150/220/300ms 감속 곡선 + 6px 진입. 차트 선을 매번 다시 그리지 않는다.",
+    "다크 판이 필요하면 dark* 색(.dark 토큰)을 쓴다."
+  ]
+}

package/series/og-shorts.json

@@ -0,0 +1,14 @@
+{
+  "id": "og-shorts",
+  "label": "OG 쇼츠",
+  "summary": "OpenGateway 기술 쇼츠 — 측정 테마·차분한 남성 내레이션·깊은 앰비언트 곡·화면 자막, 45–60초, 끝 카드 OpenGateway",
+  "match": ["OG 쇼츠", "OG 숏츠", "OG 숏폼", "OG shorts", "오픈게이트웨이 쇼츠", "OpenGateway 쇼츠", "OpenGateway shorts"],
+  "purpose": "shorts",
+  "theme": "og-measure",
+  "voice": "gemini:Charon",
+  "music": { "mood": "deep" },
+  "captions": "on",
+  "duration": { "min": 45, "max": 60, "default": 45 },
+  "end": { "title": "OpenGateway", "line": "opengateway.ai" },
+  "answers": { "image": "og-gpt-image-2.5-sunburst", "video": "none" }
+}

package/skills/kasaframe/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: kasaframe
+description: 영상을 만들 때 쓴다 — 홍보 영상·쇼츠·릴스·설명 영상·제품 공개·시연·광고·피드·뮤직비디오·모션그래픽·카운트다운·로고 애니메이션. 말로만 해도(「카사텀 홍보 영상 1분, 리소 느낌으로」) kasaframe 이 용도·테마·곡을 알아서 고르고 장면 지시서를 낸다. 영상 만드는 길은 이것 하나다. 한국어 트리거: 영상 만들어, 쇼츠 만들어, 홍보 영상, 뮤비, 모션그래픽, 설명 영상, 시연 영상, 광고 영상. English: make a video, promo video, shorts, music video, motion graphics, explainer.
+version: 0.1.0
+user-invocable: true
+argument-hint: "[만들 영상 한 줄]"
+---
+
+# kasaframe — 말 한 줄로 영상까지
+
+명령은 `kf <명령>` — `npm i -g kasaframe` 로 깔았으면 어느 폴더에서나. `kf` 가 PATH 에 없고 이 스킬 폴더가 레포 안의 링크면(실제 경로의 두 단계 위가 레포 뿌리) 그 뿌리에서 `npx kf <명령>`. 둘 다 아니면 사람에게 `npm i -g kasaframe && kf setup` 을 알린다. 처음이면 `kf doctor` 로 ffmpeg·크롬·librosa·OG 키를 본다.
+규칙·장면 쓰는 법·고치는 법의 정본은 **`docs/AGENTS.md`**(이 스킬 폴더 `kf skill path` 의 두 단계 위) — 장면을 쓰기 전에 0절과 3절을 읽는다.
+
+## 순서
+
+1. **요청을 그대로 넘긴다** — 묻지 말고 시작한다.
+   ```
+   kf make "<사람이 한 말 그대로>"
+   ```
+   결과 폴더는 지금 폴더 아래 생긴다(`--out` 으로 바꾼다). 시리즈(「OG 쇼츠」처럼 `kf series list` 의 묶음을 짚으면 그 묶음이 다 정한다)·용도(홍보·쇼츠·설명·공개·시연·광고·피드·뮤비)·테마(「~ 느낌·풍」으로 짚으면 그 테마, 아니면 맨 위 질문으로 묻는다 — 답 전엔 내용에 맞는 승인 테마로 깔린다)·곡(`--music`, 없으면 곡 모음 `KF_MUSIC_DIR` 에서)을 알아서 고른다. **종료 코드 3** 이면 확신이 낮다는 뜻 — 찍힌 보기 중 맞는 것을 `--purpose` 로 다시(그래도 모르겠으면 그때 사람에게 묻는다).
+2. 찍힌 `<폴더>/MAKE.md`(장면 지시서 — 용도별 규칙·장면별 시각·할 일·박·테마 효과·만들 그림·주인공 3D 장면)를 읽는다. **맨 위에 「사용자에게 먼저 물을 것」이 있으면** 장면을 쓰기 전에 AskUserQuestion 한 번으로 묻고(적힌 header·보기 그대로, 첫째가 권장) 답을 `kf make --answer <폴더> --<플래그> <값> …` 로 넣는다 — 테마·목소리와 돈이 드는 생성·없는 능력이 올라온다(테마는 견본 그림 경로가 보기마다 붙는다 — 사람에게 보여 주고 묻는다). **없는 능력(「넣는 법·다른 엔진·빼기」 보기)은 네가 대신 고르지 말고 꼭 사람에게** 묻는다. `kf make` 가 종료 코드 3 으로 보기를 찍고 멈추면(박자·가사 도구처럼 뼈대 전에 필요한 것) 그 보기를 그대로 물어 플래그로 다시 부른다. **쇼츠·설명은 내레이션 먼저** — 지시서의 「내레이션 먼저」대로 `captions.json` 에 장면별 문장을 쓰고 `kf narrate <폴더>` 로 장면 길이를 목소리에 맞춘 뒤(곡이 있으면 박에) 장면을 쓴다. 그다음 고른 공급자로 그림(`kf gen img`)·3D 샷(`kf blender`)·영상 컷(`kf gen vid`)을 만들고 `scenes/*.ts` 를 채운다. 무대 `lib/stage.ts` 를 겉에 씌우면 「0.1초도 쉬지 않기·같은 구도 오래 두지 않기(용도별 기준)·화면 채우기」가 처음부터 선다.
+3. `kf look <폴더>` 가 찍는 장면 모음을 Read 로 직접 보고 장면별 확인표(`out/look.md`)대로 고친다. **그림이 안 보이면**(OG 로 붙인 모델 등)만 `kf look <폴더> --vision-model google/gemini-3.5-flash` — 그림 보는 모델이 장면마다 글로 알려 준다.
+4. `kf make --finish <폴더>` — 렌더·검사·표지·자막. 검사 오류가 0 이 될 때까지 장면을 고쳐 다시(렌더는 고칠 것을 모아 한 번에 — 한 기계에서 하나씩 돈다).
+5. 결과 `out/video.mp4`·`out/cover.png` 를 사람이 보는 공유 폴더에 넣어 보여 준다.
+
+작업실(`kf app`, :5150)이 떠 있으면 `kf make` 가 거기에 등록하고 주소를 찍는다 — 사람은 페이지에서 실시간 미리보기·지난 작업을 본다.
+
+## 하지 않는 것
+
+- 돈이 드는 그림·영상 생성을 묻기 전에 부르지 않는다 — 사람이 고른 답(또는 `--yes`·`--allow`)이 있을 때만. 「만들 그림」은 받은 자산·실제 화면·도형으로 안 될 때만 구체적인 프롬프트로.
+- 지역 제한이 걸린 공급자(사내 H3)를 회사·바깥 결과물에 쓰지 않는다 — 보기의 경고를 그대로 사람에게 보인다.
+- 슬로건·감성 카피를 화면에 쓰지 않는다(홍보 틀). 이모지 금지.
+- 렌더·검사를 잠금 없이 여러 개 동시에 돌리지 않는다.

package/templates/_shared/project/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="ko">
+  <head>
+    <meta charset="utf-8" />
+    <title>{{title}}</title>
+  </head>
+  <body>
+    <div id="stage"></div>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>

package/templates/_shared/project/lib/react.ts

@@ -0,0 +1,22 @@
+import { createElement, type ComponentType } from "react";
+import { flushSync } from "react-dom";
+import { createRoot, type Root } from "react-dom/client";
+
+// 이미 있는 React 컴포넌트(geono-hub bits 같은)를 고치지 않고 장면에 얹는다.
+// build 에서 바로 붙이면 장면이 숨어 있는 동안(앞 장면 차례) 등장 애니메이션이 다 끝나 버린다 — 장면이 처음 그려질 때 붙인다.
+// 자기 시계(rAF·motion 스프링·타이머)로 도는 컴포넌트면 kf.json 에 "mode": "step"(0 초부터 차례로 돈다).
+// 컴포넌트가 따로 쓰는 npm 패키지는 프로젝트 폴더에 package.json 을 두고 `npm i <패키지> --legacy-peer-deps` —
+// react·react-dom 은 레포 것 한 벌로 묶이니 프로젝트에 또 깔지 않는다(두 벌이면 훅이 깨진다).
+//
+//   const crowd = bit(host, CrowdCanvas);
+//   return (t) => { crowd({ count: 12 }, "once"); ... }   // key 가 같으면 다시 그리지 않는다
+export function bit<P extends object>(host: HTMLElement, Comp: ComponentType<P>): (props: P, key?: string) => void {
+  let root: Root | null = null;
+  let last: string | undefined;
+  return (props, key = JSON.stringify(props)) => {
+    root ??= createRoot(host);
+    if (key === last) return;
+    last = key;
+    flushSync(() => root!.render(createElement(Comp, props)));
+  };
+}