kasaframe 0.0.0-stage → 0.1.1

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/skills/kasaframe/SKILL.md

@@ -0,0 +1,32 @@
+---
+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` 으로 바꾼다). 용도(홍보·쇼츠·설명·공개·시연·광고·피드·뮤비)·테마(「~ 느낌·풍」으로 짚으면 그 테마, 아니면 내용에 맞는 승인 테마)·곡(`--music`, 없으면 곡 모음 `KF_MUSIC_DIR` 에서)을 알아서 고른다. **종료 코드 3** 이면 확신이 낮다는 뜻 — 찍힌 보기 중 맞는 것을 `--purpose` 로 다시(그래도 모르겠으면 그때 사람에게 묻는다).
+2. 찍힌 `<폴더>/MAKE.md`(장면 지시서 — 용도별 규칙·장면별 시각·할 일·박·테마 효과·만들 그림)를 읽고 `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` 가 거기에 등록하고 주소를 찍는다 — 사람은 페이지에서 실시간 미리보기·지난 작업을 본다.
+
+## 하지 않는 것
+
+- 돈이 드는 그림·영상 생성을 묻지 않고 부르지 않는다 — 지시서의 「만들 그림」은 받은 자산·실제 화면·도형으로 안 될 때만 구체적인 프롬프트로 `kf gen img`. 영상 생성은 사람이 요청에 적었을 때만.
+- 슬로건·감성 카피를 화면에 쓰지 않는다(홍보 틀). 이모지 금지.
+- 렌더·검사를 잠금 없이 여러 개 동시에 돌리지 않는다.

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)));
+  };
+}

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

@@ -0,0 +1,272 @@
+import { applyStyle, ease, emit, lerp, progress, rand, type SceneCtx, type Style } from "@kasaframe/core";
+
+// 장면 뼈대가 같이 쓰는 무대. 카메라는 가만히 있고 주인공은 안전 영역 가운데에 선다 — 이유 없이 화면 전체를 흔들면
+// 보는 사람이 주인공을 놓친다(카메라 드리프트·박마다 자세를 겹친 판이 쇼츠마다 기울고 가장자리로 밀렸다).
+// 「단 0.1초도 쉬지 않는다」는 화면 안 움직임이 맡는다 — 바탕 층의 빛 방울 흐름과, 박마다 모양을 바꾸는 바탕 판.
+// 카메라는 장면이 이유를 댈 때만 움직인다: stage.camera.pushIn·pullOut·follow·impact. 움직이는 동안만 __kf.events 에 남아
+// kf check 의 camera.wander 가 「이유 없는 이동」과 가른다. 장면을 채울 때 그대로 써도, 지워도 된다.
+
+export interface Stage {
+  box: HTMLDivElement; // 바탕 층(장면 전체) — 늘 흐르는 것은 여기에만
+  cam: HTMLDivElement; // 카메라 층 — 주 요소는 여기에. 가만히 있다가 camera 가 시킬 때만 움직인다
+  camera: Camera;
+  safeW: number;
+  safeH: number;
+  vertical: boolean;
+  /** 주인공 표시 — kf check 의 layout.edge 가 이 상자가 안전 영역 가장자리에 붙는지 본다(bigWord 는 스스로 단다) */
+  hero(el: HTMLElement): HTMLElement;
+  /** 바탕 흐름 + 카메라. 카메라가 요소를 겨누면(to·follow) 내용을 칠한 뒤 맨 끝에 부른다 — 그 프레임의 자리를 잰다 */
+  tick(t: number): void;
+}
+
+/** 카메라 층 안 좌표(px, 변환 전) — w·h 를 주면 그 상자가 화면에 들어오게 배율을 줄인다 */
+export interface Spot {
+  x: number;
+  y: number;
+  w?: number;
+  h?: number;
+}
+export type Target = HTMLElement | Spot | ((t: number) => Spot);
+
+export interface Camera {
+  /** 드러냄에 다가가기 — to 가 없으면 화면 가운데로 */
+  pushIn(at: number, o?: { to?: Target; scale?: number; dur?: number }): Camera;
+  /** 비교 전체를 보이게 물러나기 — 기본은 처음 구도(배율 1)로 돌아온다. 더 넓게는 scale: 0.9 */
+  pullOut(at: number, o?: { to?: Target; scale?: number; dur?: number }): Camera;
+  /** from–to 동안 주인공 상자를 가운데에 두고 따라간다. 끝나면 앞 구도로 돌아와 선다 */
+  follow(target: Target, from: number, to: number, o?: { scale?: number }): Camera;
+  /** 한 번 툭 — 드롭·결과가 서는 순간에. 배율만 잠깐 키웠다 돌아온다 */
+  impact(at: number, o?: { amount?: number; dur?: number }): Camera;
+  /** 그 시각 카메라 층 Style — 다른 움직임과 combine 해서 쓸 때 */
+  pose(t: number): Style;
+  apply(t: number): void;
+}
+
+interface Pose {
+  s: number;
+  fx: number;
+  fy: number;
+}
+
+type Move =
+  | { kind: "push" | "pull"; at: number; dur: number; to?: Target; scale?: number }
+  | { kind: "follow"; at: number; end: number; to: Target; scale?: number }
+  | { kind: "impact"; at: number; dur: number; amount: number };
+
+const FOLLOW_IN = 0.5;
+const FOLLOW_OUT = 0.6;
+
+/**
+ * 층 하나에 거는 카메라. frame 은 층 안 좌표로 본 「화면에 보일 자리」(보통 안전 영역) — 기본은 층 전체.
+ * 주인공을 frame 가운데로 데려오고, 배율은 상자가 frame 의 86% 안에 들어오게 누른다. 회전·원근은 쓰지 않는다.
+ */
+export function makeCamera(layer: HTMLElement, ctx: SceneCtx, o: { frame?: { x: number; y: number; w: number; h: number } } = {}): Camera {
+  const frame = o.frame;
+  const cx = () => (frame ? frame.x + frame.w / 2 : layer.offsetWidth / 2);
+  const cy = () => (frame ? frame.y + frame.h / 2 : layer.offsetHeight / 2);
+  const fw = () => frame?.w ?? layer.offsetWidth;
+  const fh = () => frame?.h ?? layer.offsetHeight;
+  const moves: Move[] = [];
+  const add = (m: Move) => {
+    moves.push(m);
+    moves.sort((a, b) => a.at - b.at);
+  };
+
+  // 변환을 걷어 낸 층 안 좌표 — 층 상자와 요소 상자를 같은 화면에서 재고 층 배율로 나눈다(조상 배율까지 함께 나뉜다)
+  function spotOf(target: Target, t: number): Spot | null {
+    if (typeof target === "function") return target(t);
+    if (!(target instanceof HTMLElement)) return target;
+    const r = target.getBoundingClientRect();
+    if (r.width < 1 || r.height < 1) return null;
+    const lr = layer.getBoundingClientRect();
+    const k = lr.width / (layer.offsetWidth || 1) || 1;
+    return { x: (r.left + r.width / 2 - lr.left) / k, y: (r.top + r.height / 2 - lr.top) / k, w: r.width / k, h: r.height / k };
+  }
+
+  function goal(to: Target | undefined, scale: number | undefined, fallback: number, t: number): Pose {
+    const s = to ? spotOf(to, t) : null;
+    if (!s) return { s: scale ?? fallback, fx: cx(), fy: cy() };
+    const fit = Math.min(s.w ? (fw() * 0.86) / s.w : Infinity, s.h ? (fh() * 0.86) / s.h : Infinity);
+    return { s: Math.min(scale ?? fallback, fit), fx: s.x, fy: s.y };
+  }
+
+  const mix = (a: Pose, b: Pose, p: number): Pose => ({ s: lerp(a.s, b.s, p), fx: lerp(a.fx, b.fx, p), fy: lerp(a.fy, b.fy, p) });
+
+  // 앞 움직임이 다 끝났으면 그 끝 구도에서, 겹치면 지금 구도에서 이어 간다 — 늘 t 하나로 정해진다
+  function at(t: number): { p: Pose; kick: number } {
+    let p: Pose = { s: 1, fx: cx(), fy: cy() };
+    let kick = 0;
+    for (const m of moves) {
+      if (t < m.at) break;
+      if (m.kind === "impact") {
+        const e = t - m.at;
+        if (e < m.dur) {
+          kick += m.amount * Math.exp(-e / (m.dur * 0.3)) * (1 - e / m.dur);
+          emit({ kind: "camera", source: "stage:impact", scene: ctx.id, value: kick * 1000 });
+        }
+        continue;
+      }
+      if (m.kind === "follow") {
+        const w = ease.inOutCubic(progress(t, m.at, FOLLOW_IN)) * (1 - ease.inOutCubic(progress(t, m.end, FOLLOW_OUT)));
+        if (w > 0) {
+          p = mix(p, goal(m.to, m.scale, p.s, t), w);
+          emit({ kind: "camera", source: "stage:follow", scene: ctx.id, value: 1 });
+        }
+        continue;
+      }
+      const raw = progress(t, m.at, m.dur);
+      const target = goal(m.to, m.scale, m.kind === "push" ? 1.15 : 1, t);
+      p = mix(p, target, ease.inOutCubic(raw));
+      if (raw > 0 && raw < 1) emit({ kind: "camera", source: `stage:${m.kind}`, scene: ctx.id, value: Math.abs(target.s - p.s) * 1000 + Math.hypot(target.fx - p.fx, target.fy - p.fy) });
+    }
+    return { p, kick };
+  }
+
+  const cam: Camera = {
+    pushIn(t, x = {}) {
+      add({ kind: "push", at: t, dur: x.dur ?? 1, to: x.to, scale: x.scale });
+      return cam;
+    },
+    pullOut(t, x = {}) {
+      add({ kind: "pull", at: t, dur: x.dur ?? 0.9, to: x.to, scale: x.scale });
+      return cam;
+    },
+    follow(target, from, to, x = {}) {
+      add({ kind: "follow", at: from, end: to, to: target, scale: x.scale });
+      return cam;
+    },
+    impact(t, x = {}) {
+      add({ kind: "impact", at: t, dur: x.dur ?? 0.35, amount: x.amount ?? 0.04 });
+      return cam;
+    },
+    pose(t) {
+      if (!moves.length) return {};
+      const { p, kick } = at(t);
+      const s = p.s * (1 + kick);
+      return { x: -s * (p.fx - cx()), y: -s * (p.fy - cy()), scale: s };
+    },
+    apply(t) {
+      layer.style.transformOrigin = `${cx()}px ${cy()}px`;
+      applyStyle(layer, cam.pose(t));
+    },
+  };
+  return cam;
+}
+
+// 컷 시각 — 잰 박 목록을 그대로 쓴다(BPM 을 곱하지 않는다). 빠른 곡은 박 몇 개를 묶어 0.6초 넘는 간격으로.
+// 박이 끊긴 곳(곡 앞뒤·잘라 쓴 끝)은 1.2초 간격으로 메워 장면 처음부터 끝까지 컷이 이어진다.
+// 화면 안 내용을 바꾸는 시각이다(새 요소·숫자·칸 채우기) — 카메라를 여기마다 옮기지 않는다
+export function cutTimes(ctx: SceneCtx): number[] {
+  const b = ctx.beats.beats.filter((x) => x >= 0 && x < ctx.dur);
+  let picked: number[] = [];
+  if (b.length >= 2) {
+    const gap = (b[b.length - 1] - b[0]) / (b.length - 1);
+    const every = Math.max(1, Math.round(0.6 / gap));
+    picked = b.filter((_, i) => i % every === 0);
+  }
+  const anchors = [0];
+  for (const t of picked) if (t - anchors[anchors.length - 1] >= 0.3) anchors.push(t);
+  anchors.push(ctx.dur);
+  const out: number[] = [];
+  for (let i = 0; i < anchors.length - 1; i++) {
+    const n = Math.max(1, Math.ceil((anchors[i + 1] - anchors[i]) / 1.2));
+    for (let k = 0; k < n; k++) out.push(anchors[i] + ((anchors[i + 1] - anchors[i]) * k) / n);
+  }
+  return out;
+}
+
+// 바탕 판의 꼴(안전 영역에 대한 비율) — 컷에서 컷까지 다음 꼴로 쉬지 않고 옮겨 가 같은 구도가 1.5초를 넘지 않고 0.1초도 멈추지 않는다.
+// 빛 방울만으로는 작은 그림의 멈춤 판정을 늘 넘지 못한다(방울 자리에 따라 장면마다 들쭉날쭉). 주인공은 그대로 선다
+const PANELS = [
+  { x: 0.07, y: 0.15, w: 0.86, h: 0.7, r: 0.12 },
+  { x: 0, y: 0.55, w: 1, h: 0.45, r: 0.04 },
+  { x: 0.18, y: 0.05, w: 0.64, h: 0.9, r: 0.5 },
+  { x: 0, y: 0, w: 0.5, h: 1, r: 0.04 },
+  { x: 0.05, y: 0.3, w: 0.9, h: 0.4, r: 0.2 },
+];
+
+export function makeStage(root: HTMLElement, ctx: SceneCtx, o: { panel?: boolean } = {}): Stage {
+  const { top, right, bottom, left } = ctx.safe;
+  const { width, height } = ctx.meta;
+  // root 의 display 는 mountProject 가 장면을 켜고 끌 때 쓴다 — 배치는 안쪽 상자에
+  const box = document.createElement("div");
+  box.style.cssText = "position:absolute;inset:0;overflow:hidden;background:var(--kf-bg)";
+  const safeW = width - left - right;
+  const safeH = height - top - bottom;
+  // 글 한 줄만 있는 화면도 비어 보이지 않게 — 안전 영역을 크게 채우는 판 하나. 바탕 층이라 카메라를 따라가지 않는다.
+  // 빛 방울은 판 위로 흐른다 — 판 밑에 깔리면 판이 덮은 만큼 흐림이 죽어 그 장면이 멈춘 프레임이 된다
+  let panel: HTMLDivElement | null = null;
+  if (o.panel !== false) {
+    panel = document.createElement("div");
+    panel.style.cssText = `position:absolute;left:${left}px;top:${top}px;width:${safeW}px;height:${safeH}px;transform-origin:0 0;background:var(--kf-accent-soft);opacity:.55`;
+    box.append(panel);
+  }
+  // 바탕 패럴랙스 — 큰 빛 방울 여럿이 서로 다른 빠르기로 흐른다. 카메라가 서 있으니 0.1초 멈춤 판정을 이 흐름이 넘겨야 한다 —
+  // 연한 accent-soft 만으로는 작은 그림에서 안 바뀐 것으로 읽혀 accent 를 섞는다. 잔무늬는 작은 그림에 안 잡혀 「멈춤」으로 읽힌다
+  const orbs = Array.from({ length: 9 }, (_, i) => {
+    const el = document.createElement("div");
+    const r = Math.round(Math.min(width, height) * (0.12 + 0.18 * rand(ctx.id, i)));
+    el.style.cssText = `position:absolute;left:0;top:0;width:${r * 2}px;height:${r * 2}px;border-radius:50%;background:radial-gradient(circle, color-mix(in srgb, var(--kf-accent) 30%, var(--kf-accent-soft)) 0%, transparent 70%);opacity:${(0.6 + 0.35 * rand(ctx.id, i + 20)).toFixed(2)}`;
+    box.append(el);
+    // 빠르기는 70–190px/초 — 거의 서 있는 방울이 섞이면 그 사이가 멈춘 프레임이 된다
+    const a = rand(ctx.id, i + 80) * Math.PI * 2;
+    const v = 70 + 120 * rand(ctx.id, i + 100);
+    return { el, r, x0: rand(ctx.id, i + 40) * width, y0: rand(ctx.id, i + 60) * height, vx: v * Math.cos(a), vy: v * Math.sin(a) * 0.7 };
+  });
+  const cam = document.createElement("div");
+  cam.style.cssText = `position:absolute;left:${left}px;top:${top}px;right:${right}px;bottom:${bottom}px;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:28px`;
+  box.append(cam);
+  root.append(box);
+  const camera = makeCamera(cam, ctx, { frame: { x: 0, y: 0, w: safeW, h: safeH } });
+  const cuts = cutTimes(ctx);
+  return {
+    box,
+    cam,
+    camera,
+    safeW,
+    safeH,
+    vertical: height > width,
+    hero(el) {
+      el.dataset.kfHero = "";
+      return el;
+    },
+    tick(t: number) {
+      for (const o of orbs) {
+        const x = ((o.x0 + o.vx * t) % (width + o.r * 2) + width + o.r * 2) % (width + o.r * 2) - o.r * 2;
+        const y = ((o.y0 + o.vy * t) % (height + o.r * 2) + height + o.r * 2) % (height + o.r * 2) - o.r * 2;
+        o.el.style.transform = `translate(${x.toFixed(1)}px, ${y.toFixed(1)}px)`;
+      }
+      if (panel) {
+        let k = 0;
+        while (k < cuts.length && cuts[k] <= t) k++;
+        const from = k > 0 ? cuts[k - 1] : 0;
+        const p = progress(t, from, Math.max(0.3, (cuts[k] ?? from + 1.2) - from));
+        const a = PANELS[Math.max(0, k - 2) % PANELS.length];
+        const b = PANELS[Math.max(0, k - 1) % PANELS.length];
+        const f = (key: "x" | "y" | "w" | "h" | "r") => lerp(a[key], b[key], p);
+        panel.style.transform = `translate(${(f("x") * safeW).toFixed(1)}px, ${(f("y") * safeH).toFixed(1)}px) scale(${f("w").toFixed(4)}, ${f("h").toFixed(4)})`;
+        panel.style.borderRadius = `${(f("r") * Math.min(safeW, safeH)) / f("w")}px / ${(f("r") * Math.min(safeW, safeH)) / f("h")}px`;
+      }
+      camera.apply(t);
+    },
+  };
+}
+
+// 렌더가 마지막으로 찍는 장면 안 시각 — 되돌이(끝 화면이 첫 화면으로 이어지는 쇼츠·피드)는 ctx.dur 이 아니라 여기서 움직임을 끝낸다
+export const lastT = (ctx: SceneCtx): number => ctx.dur - 1 / ctx.meta.fps;
+
+// 글자 수로 크기를 정한다(렌더 전엔 잴 수 없다) — 한글·한자는 1em, 라틴은 0.62em 으로 어림해 안전 영역 폭의 몫에 맞춘다
+export function fitPx(text: string, width: number, o: { share?: number; max?: number; min?: number } = {}): number {
+  const em = [...text].reduce((a, c) => a + (/[ᄀ-ᇿ㄰-㆏가-힯一-鿿]/.test(c) ? 1 : c === " " ? 0.3 : 0.62), 0) || 1;
+  return Math.round(Math.max(o.min ?? 48, Math.min(o.max ?? 420, (width * (o.share ?? 0.7)) / em)));
+}
+
+// 큰 낱말 하나 — 화면 채움 규칙에 맞는 크기로, 주인공 표시를 달아 카메라 층 가운데에
+export function bigWord(text: string, stage: Stage, o: { color?: string; weight?: number; share?: number } = {}): HTMLDivElement {
+  const el = document.createElement("div");
+  el.textContent = text;
+  const px = fitPx(text, stage.safeW, { share: o.share ?? (stage.vertical ? 0.72 : 0.62), max: stage.vertical ? 360 : 420 });
+  el.style.cssText = `position:relative;font-family:var(--kf-font-display);font-size:${px}px;font-weight:${o.weight ?? 800};line-height:1.02;color:${o.color ?? "var(--kf-ink)"};letter-spacing:var(--kf-tracking);text-align:center;word-break:keep-all;white-space:nowrap`;
+  stage.cam.append(stage.hero(el));
+  return el;
+}

package/templates/_shared/project/main.ts

@@ -0,0 +1,9 @@
+import { mountProject } from "@kasaframe/adapters";
+import kf from "./kf.json";
+import style from "./style.json";
+
+// 장면 파일을 늘리거나 빼도 이 파일은 그대로 — 시간표는 kf.json 한 곳. 글꼴·색 변수는 mountProject 가 건다
+const scenes = import.meta.glob("./scenes/*.ts", { eager: true });
+const beats = Object.values(import.meta.glob("./beats.json", { eager: true, import: "default" }))[0] ?? null;
+
+mountProject({ kf, scenes, beats, style, stage: document.getElementById("stage")! });

package/templates/_shared/scenes/default.ts

@@ -0,0 +1,18 @@
+import { applyStyle, type SceneCtx } from "@kasaframe/core";
+import { enter, type MoveName } from "@kasaframe/motion";
+import { bigWord, makeStage } from "../lib/stage.ts";
+
+const WORD = "{{word}}";
+// 이어지는 두 장면이 같은 등장을 쓰면 검사가 잡는다(repeatSameMove) — kf new 가 장면 순번으로 돌려 넣는다
+const MOVE: MoveName = "{{move}}";
+
+export default {
+  build(root: HTMLElement, ctx: SceneCtx) {
+    const stage = makeStage(root, ctx);
+    const word = bigWord(WORD, stage);
+    return (t: number) => {
+      stage.tick(t);
+      applyStyle(word, enter(MOVE, t, { at: 0, scene: ctx.id }));
+    };
+  },
+};