kasaframe 0.1.1 → 0.1.3

package/skills/kasaframe/SKILL.md

@@ -17,8 +17,8 @@ argument-hint: "[만들 영상 한 줄]"
    ```
    kf make "<사람이 한 말 그대로>"
    ```
-   결과 폴더는 지금 폴더 아래 생긴다(`--out` 으로 바꾼다). 용도(홍보·쇼츠·설명·공개·시연·광고·피드·뮤비)·테마(「~ 느낌·풍」으로 짚으면 그 테마, 아니면 내용에 맞는 승인 테마)·곡(`--music`, 없으면 곡 모음 `KF_MUSIC_DIR` 에서)을 알아서 고른다. **종료 코드 3** 이면 확신이 낮다는 뜻 — 찍힌 보기 중 맞는 것을 `--purpose` 로 다시(그래도 모르겠으면 그때 사람에게 묻는다).
-2. 찍힌 `<폴더>/MAKE.md`(장면 지시서 — 용도별 규칙·장면별 시각·할 일·박·테마 효과·만들 그림)를 읽고 `scenes/*.ts` 를 채운다. 무대 `lib/stage.ts` 를 겉에 씌우면 「0.1초도 쉬지 않기·같은 구도 오래 두지 않기(용도별 기준)·화면 채우기」가 처음부터 선다.
+   결과 폴더는 지금 폴더 아래 생긴다(`--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` 를 사람이 보는 공유 폴더에 넣어 보여 준다.
@@ -27,6 +27,7 @@ argument-hint: "[만들 영상 한 줄]"
 
 ## 하지 않는 것
 
-- 돈이 드는 그림·영상 생성을 묻지 않고 부르지 않는다 — 지시서의 「만들 그림」은 받은 자산·실제 화면·도형으로 안 될 때만 구체적인 프롬프트로 `kf gen img`. 영상 생성은 사람이 요청에 적었을 때만.
+- 돈이 드는 그림·영상 생성을 묻기 전에 부르지 않는다 — 사람이 고른 답(또는 `--yes`·`--allow`)이 있을 때만. 「만들 그림」은 받은 자산·실제 화면·도형으로 안 될 때만 구체적인 프롬프트로.
+- 지역 제한이 걸린 공급자(사내 H3)를 회사·바깥 결과물에 쓰지 않는다 — 보기의 경고를 그대로 사람에게 보인다.
 - 슬로건·감성 카피를 화면에 쓰지 않는다(홍보 틀). 이모지 금지.
 - 렌더·검사를 잠금 없이 여러 개 동시에 돌리지 않는다.

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

@@ -1,10 +1,14 @@
-import { applyStyle, ease, emit, lerp, progress, rand, type SceneCtx, type Style } from "@kasaframe/core";
+import { applyStyle, combine, ease, emit, lerp, progress, type SceneCtx, type Style } from "@kasaframe/core";
+import { enter, type MoveName } from "@kasaframe/motion";
+import { dressBg, dressText, dressWipe, type Dress } from "@kasaframe/motion/moves";
 
 // 장면 뼈대가 같이 쓰는 무대. 카메라는 가만히 있고 주인공은 안전 영역 가운데에 선다 — 이유 없이 화면 전체를 흔들면
 // 보는 사람이 주인공을 놓친다(카메라 드리프트·박마다 자세를 겹친 판이 쇼츠마다 기울고 가장자리로 밀렸다).
-// 「단 0.1초도 쉬지 않는다」는 화면 안 움직임이 맡는다 — 바탕 층의 빛 방울 흐름과, 박마다 모양을 바꾸는 바탕 판.
+// 「단 0.1초도 쉬지 않는다」는 내용의 움직임이 맡는다 — 글·숫자 수(dress.text)가 박마다 바뀌고, 글 뒤 강조 띠가 박마다 차오른다.
+// 바탕은 정지(still) — 뜻 없이 떠도는 빛 방울·옮겨 가는 판은 보는 사람이 무엇인지 묻게 만들어 걷었다.
 // 카메라는 장면이 이유를 댈 때만 움직인다: stage.camera.pushIn·pullOut·follow·impact. 움직이는 동안만 __kf.events 에 남아
 // kf check 의 camera.wander 가 「이유 없는 이동」과 가른다. 장면을 채울 때 그대로 써도, 지워도 된다.
+// 연출 수(dress)를 주면 바탕·글·경계 덮기를 수 메뉴(@kasaframe/motion/moves menu)에서 건다 — kf new 가 장면마다 시드로 골라 넣는다.
 
 export interface Stage {
   box: HTMLDivElement; // 바탕 층(장면 전체) — 늘 흐르는 것은 여기에만
@@ -15,7 +19,12 @@ export interface Stage {
   vertical: boolean;
   /** 주인공 표시 — kf check 의 layout.edge 가 이 상자가 안전 영역 가장자리에 붙는지 본다(bigWord 는 스스로 단다) */
   hero(el: HTMLElement): HTMLElement;
-  /** 바탕 흐름 + 카메라. 카메라가 요소를 겨누면(to·follow) 내용을 칠한 뒤 맨 끝에 부른다 — 그 프레임의 자리를 잰다 */
+  /**
+   * 낱말을 고른 글 수(dress.text)로 띄운다 — bigWord 면 큰 낱말 + 등장 움직임. paint 를 매 프레임 부른다(extra 는 그 위에 얹을 흔들림·펀치).
+   * ready 면 첫 프레임부터 글이 서 있다(훅·썸네일)
+   */
+  say(words: readonly string[], o?: { enter?: MoveName; color?: string; weight?: number; ready?: boolean }): { el: HTMLElement; paint: (t: number, extra?: Style) => void };
+  /** 경계 덮기 + 카메라(+ 이름으로 부른 움직이는 바탕). 카메라가 요소를 겨누면(to·follow) 내용을 칠한 뒤 맨 끝에 부른다 — 그 프레임의 자리를 잰다 */
   tick(t: number): void;
 }
 
@@ -175,17 +184,7 @@ export function cutTimes(ctx: SceneCtx): number[] {
   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 {
+export function makeStage(root: HTMLElement, ctx: SceneCtx, o: { panel?: boolean; dress?: Dress } = {}): Stage {
   const { top, right, bottom, left } = ctx.safe;
   const { width, height } = ctx.meta;
   // root 의 display 는 mountProject 가 장면을 켜고 끌 때 쓴다 — 배치는 안쪽 상자에
@@ -193,33 +192,30 @@ export function makeStage(root: HTMLElement, ctx: SceneCtx, o: { panel?: boolean
   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 };
-  });
+  // 바탕은 정지(still) — 패턴이 제 바탕을 그리면(panel: false) 바탕색만
+  const bgLayer = document.createElement("div");
+  bgLayer.style.cssText = "position:absolute;inset:0";
+  const bg = o.panel === false ? null : dressBg(o.dress?.bg ?? "still", bgLayer, ctx);
+  if (o.panel !== false) box.append(bgLayer);
   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);
+  // 경계 덮기는 맨 위 층 — 앞 장면 끝을 덮은 덮개가 다음 장면 첫 프레임에서 그대로 걷힌다
+  const wipes = (["in", "out"] as const)
+    .map((side) => {
+      const name = side === "in" ? o.dress?.wipeIn : o.dress?.wipeOut;
+      if (!name || name === "none") return null;
+      const layer = document.createElement("div");
+      layer.style.cssText = "position:absolute;inset:0;pointer-events:none;z-index:60";
+      const paint = dressWipe(name, layer, ctx, side);
+      if (paint) box.append(layer);
+      return paint;
+    })
+    .filter((p): p is (t: number) => void => !!p);
   root.append(box);
   const camera = makeCamera(cam, ctx, { frame: { x: 0, y: 0, w: safeW, h: safeH } });
   const cuts = cutTimes(ctx);
-  return {
+  const stage: Stage = {
     box,
     cam,
     camera,
@@ -230,26 +226,50 @@ export function makeStage(root: HTMLElement, ctx: SceneCtx, o: { panel?: boolean
       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) {
+    say(words, x = {}) {
+      // 글 뒤 강조 띠 — 컷(박)마다 글 폭만큼 왼쪽부터 차오른다(형광펜으로 지금 읽힐 자리를 칠하는 강조).
+      // 글 수가 박에 바뀐 뒤 다음 박까지 서 있는 사이에도 내용이 움직인다 — 0.1초 멈춤 규칙을 이 띠가 넘긴다
+      const mark = document.createElement("div");
+      mark.style.cssText = `position:absolute;left:${Math.round(safeW * 0.1)}px;top:${Math.round(safeH * 0.37)}px;width:${Math.round(safeW * 0.8)}px;height:${Math.round(safeH * 0.26)}px;border-radius:${Math.round(safeH * 0.03)}px;background:color-mix(in srgb, var(--kf-accent) 50%, transparent);transform-origin:0 50%`;
+      stage.cam.append(mark);
+      const sweep = (t: number) => {
         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`;
+        while (k + 1 < cuts.length && cuts[k + 1] <= t) k++;
+        const a = cuts[k] ?? 0;
+        const b = cuts[k + 1] ?? ctx.dur;
+        mark.style.transform = `scaleX(${progress(t, a, Math.max(0.05, b - a)).toFixed(4)})`;
+      };
+      const host = document.createElement("div");
+      host.style.cssText = "position:absolute;inset:0";
+      const move = o.dress ? dressText(o.dress.text, host, ctx, { words, w: safeW, h: safeH, ready: x.ready }) : null;
+      if (move) {
+        // 수가 안전 영역 전체를 쓰니 그 상자를 주인공으로 짚으면 늘 가장자리에 붙은 것으로 잡힌다 — 글은 수가 가운데에 세운다
+        stage.cam.append(host);
+        return {
+          el: host,
+          paint(t, extra) {
+            sweep(t);
+            move(t);
+            if (extra) applyStyle(host, extra);
+          },
+        };
       }
+      const word = bigWord(words[0] ?? "", stage, { color: x.color, weight: x.weight });
+      return {
+        el: word,
+        paint(t, extra) {
+          sweep(t);
+          applyStyle(word, combine(x.enter ? enter(x.enter, t, { at: 0, scene: ctx.id }) : {}, extra));
+        },
+      };
+    },
+    tick(t: number) {
+      bg?.(t);
+      for (const w of wipes) w(t);
       camera.apply(t);
     },
   };
+  return stage;
 }
 
 // 렌더가 마지막으로 찍는 장면 안 시각 — 되돌이(끝 화면이 첫 화면으로 이어지는 쇼츠·피드)는 ctx.dur 이 아니라 여기서 움직임을 끝낸다

package/templates/_shared/scenes/default.ts

@@ -1,18 +1,21 @@
-import { applyStyle, type SceneCtx } from "@kasaframe/core";
-import { enter, type MoveName } from "@kasaframe/motion";
-import { bigWord, makeStage } from "../lib/stage.ts";
+import type { SceneCtx } from "@kasaframe/core";
+import type { MoveName } from "@kasaframe/motion";
+import type { Dress } from "@kasaframe/motion/moves";
+import { makeStage } from "../lib/stage.ts";
 
-const WORD = "{{word}}";
+const WORDS = ["{{word}}", "{{title}}"];
 // 이어지는 두 장면이 같은 등장을 쓰면 검사가 잡는다(repeatSameMove) — kf new 가 장면 순번으로 돌려 넣는다
 const MOVE: MoveName = "{{move}}";
+// 연출 수 — kf new 가 용도·테마 묶음에서 시드로 골랐다(같은 요청이면 같은 수). 바꾸려면 MAKE.md 「연출 수」 메뉴의 이름으로
+const DRESS: Dress = { bg: "{{bg}}", text: "{{text}}", wipeIn: "{{wipeIn}}", wipeOut: "{{wipeOut}}" };
 
 export default {
   build(root: HTMLElement, ctx: SceneCtx) {
-    const stage = makeStage(root, ctx);
-    const word = bigWord(WORD, stage);
+    const stage = makeStage(root, ctx, { dress: DRESS });
+    const words = stage.say(WORDS, { enter: MOVE });
     return (t: number) => {
+      words.paint(t);
       stage.tick(t);
-      applyStyle(word, enter(MOVE, t, { at: 0, scene: ctx.id }));
     };
   },
 };

package/templates/_shared/scenes/drop.ts

@@ -1,30 +1,33 @@
 import { applyStyle, combine, type SceneCtx } from "@kasaframe/core";
-import { beatPulse, dropBurst, enter, type MoveName } from "@kasaframe/motion";
-import { bigWord, makeStage } from "../lib/stage.ts";
+import { beatPulse, dropBurst, type MoveName } from "@kasaframe/motion";
+import type { Dress } from "@kasaframe/motion/moves";
+import { makeStage } from "../lib/stage.ts";
 
-const WORD = "{{word}}";
+const WORDS = ["{{word}}", "{{title}}"];
 const MOVE: MoveName = "{{move}}";
+const DRESS: Dress = { bg: "{{bg}}", text: "{{text}}", wipeIn: "{{wipeIn}}", wipeOut: "{{wipeOut}}" };
 
 // 장면 시작이 드롭에 붙어 있다(template anchor drop:k). 섬광·충격파·흔들림은 dropBurst 가 style.json 규칙(드롭 전용·maxPx)대로 내고
 // window.__kf.events 에 남겨 검사가 센다 — 손으로 짜면 규칙 위반을 못 잡는다
 export default {
   build(root: HTMLElement, ctx: SceneCtx) {
-    const stage = makeStage(root, ctx);
+    const stage = makeStage(root, ctx, { dress: DRESS });
     const ring = document.createElement("div");
     ring.style.cssText = "position:absolute;left:50%;top:50%;width:600px;height:600px;margin:-300px 0 0 -300px;border-radius:50%;border:12px solid var(--kf-accent)";
     stage.box.insertBefore(ring, stage.cam);
-    const word = bigWord(WORD, stage, { weight: 900 });
+    const words = stage.say(WORDS, { enter: MOVE, weight: 900, ready: true });
     const flash = document.createElement("div");
     flash.style.cssText = "position:absolute;inset:0;background:var(--kf-accent)";
     stage.box.append(flash);
     const drop = ctx.beats.drops.findIndex((d) => d >= -0.05 && d < ctx.dur);
     return (t: number) => {
-      stage.tick(t);
       const b = drop >= 0 ? dropBurst(t, { beats: ctx.beats, drop, rules: ctx.style.motion, scene: ctx.id }) : null;
       flash.style.opacity = String((b?.flash ?? 0) * 0.85);
       applyStyle(ring, b ? { scale: b.ring.scale, opacity: b.ring.opacity } : { opacity: 0 });
-      const pulse = beatPulse(t, { beats: ctx.beats, rules: ctx.style.motion, scene: ctx.id, source: "drop-word" });
-      applyStyle(word, combine(enter(MOVE, t, { at: 0.02, scene: ctx.id }), b?.shake, b?.punch, pulse));
+      // 박 펄스는 큰 낱말에만 — 글 수는 스스로 박에 터지고, 수가 깐 판 전체를 박마다 키우면 가장자리가 깜빡여 섬광 검사에 걸린다
+      const pulse = DRESS.text === "bigWord" ? beatPulse(t, { beats: ctx.beats, rules: ctx.style.motion, scene: ctx.id, source: "drop-word" }) : undefined;
+      words.paint(t, combine(b?.shake, b?.punch, pulse));
+      stage.tick(t);
     };
   },
 };

package/templates/_shared/scenes/end.ts

@@ -1,23 +1,26 @@
 import { applyStyle, type SceneCtx } from "@kasaframe/core";
 import { enter, type MoveName } from "@kasaframe/motion";
-import { bigWord, fitPx, makeStage } from "../lib/stage.ts";
+import type { Dress } from "@kasaframe/motion/moves";
+import { fitPx, makeStage } from "../lib/stage.ts";
 
 const NAME = "{{title}}";
 const LINE = "{{line}}";
 const MOVE: MoveName = "{{move}}";
+const DRESS: Dress = { bg: "{{bg}}", text: "{{text}}", wipeIn: "{{wipeIn}}", wipeOut: "{{wipeOut}}" };
 
 export default {
   build(root: HTMLElement, ctx: SceneCtx) {
-    const stage = makeStage(root, ctx);
-    const name = bigWord(NAME, stage);
+    const stage = makeStage(root, ctx, { dress: DRESS });
+    const name = stage.say([NAME], { enter: MOVE });
     const line = document.createElement("div");
     line.textContent = LINE;
-    line.style.cssText = `position:relative;font-family:var(--kf-font-sans);font-size:${fitPx(LINE, stage.safeW, { share: 0.6, max: 64, min: 40 })}px;color:var(--kf-dim);word-break:keep-all;text-align:center`;
+    // 이름 수가 안전 영역을 다 쓰니 한 줄은 아래 띠에 — 이름과 겹치지 않는다
+    line.style.cssText = `position:absolute;left:0;right:0;bottom:4%;z-index:5;font-family:var(--kf-font-sans);font-size:${fitPx(LINE, stage.safeW, { share: 0.6, max: 64, min: 40 })}px;color:var(--kf-dim);word-break:keep-all;text-align:center`;
     if (LINE) stage.cam.append(line);
     return (t: number) => {
-      stage.tick(t);
-      applyStyle(name, enter(MOVE, t, { at: 0, scene: ctx.id }));
+      name.paint(t);
       applyStyle(line, enter("fade", t, { at: 0.25, scene: ctx.id }));
+      stage.tick(t);
     };
   },
 };

package/templates/_shared/scenes/hook.ts

@@ -1,16 +1,18 @@
-import { applyStyle, clip, ease, type SceneCtx } from "@kasaframe/core";
-import { bigWord, makeStage } from "../lib/stage.ts";
+import { clip, ease, type SceneCtx } from "@kasaframe/core";
+import type { Dress } from "@kasaframe/motion/moves";
+import { makeStage } from "../lib/stage.ts";
 
-const WORD = "{{word}}";
+const WORDS = ["{{word}}", "{{title}}"];
+const DRESS: Dress = { bg: "{{bg}}", text: "{{text}}", wipeIn: "{{wipeIn}}", wipeOut: "{{wipeOut}}" };
 
 // 훅은 첫 프레임부터 내용이 있어야 한다 — 페이드로 시작하면 썸네일·첫 화면이 빈다
 export default {
   build(root: HTMLElement, ctx: SceneCtx) {
-    const stage = makeStage(root, ctx);
-    const word = bigWord(WORD, stage, { color: "var(--kf-accent)", weight: 900 });
+    const stage = makeStage(root, ctx, { dress: DRESS });
+    const words = stage.say(WORDS, { color: "var(--kf-accent)", weight: 900, ready: true });
     return (t: number) => {
+      words.paint(t, { scale: 1.12 - 0.12 * ease.outBack(clip(t, 0, 0.5).p) });
       stage.tick(t);
-      applyStyle(word, { scale: 1.12 - 0.12 * ease.outBack(clip(t, 0, 0.5).p) });
     };
   },
 };

package/templates/_shared/scenes/step.ts

@@ -1,16 +1,19 @@
 import { applyStyle, type SceneCtx } from "@kasaframe/core";
 import { cursor, enter, terminal, type MoveName } from "@kasaframe/motion";
+import type { Dress } from "@kasaframe/motion/moves";
 import { makeStage } from "../lib/stage.ts";
 
 const STEP = "{{word}}";
 const MOVE: MoveName = "{{move}}";
 const COMMANDS = [{ cmd: "kf new demo --template demo", out: ["장면 6개 · 60초"] }];
+// 창이 주인공이라 글 수는 안 쓰고 바탕·경계 덮기만 건다
+const DRESS: Dress = { bg: "{{bg}}", text: "bigWord", wipeIn: "{{wipeIn}}", wipeOut: "{{wipeOut}}" };
 
 // 시연 한 단계 — 창(터미널) 하나 + 누를 자리로 다가가는 카메라 + 커서 + 단계 번호. 화면 녹화가 있으면 창 안을 <video data-kf-from> 로 바꾼다
 export default {
   build(root: HTMLElement, ctx: SceneCtx) {
     // 흐르는 바탕·컷마다 바뀌는 판이 「쉬지 않기」를 진다 — 창은 가만히 서고, 카메라는 누른 뒤 한 번만 다가간다
-    const stage = makeStage(root, ctx);
+    const stage = makeStage(root, ctx, { dress: DRESS });
     const cam = document.createElement("div");
     // 창이 바탕을 다 덮으면 흐르는 바탕이 안 보여 멈춘 화면이 된다 — 둘레를 남긴다
     cam.style.cssText = "position:relative;width:min(1100px, 70%)";
@@ -25,12 +28,18 @@ export default {
     cam.append(win, badge, pointer);
     stage.cam.append(cam);
     const click = Math.min(1.2, ctx.dur * 0.3);
+    const typed = 0.5 + COMMANDS[0].cmd.length / 16 + 0.3;
+    const FRAMES = Math.round(ctx.dur * ctx.meta.fps);
     stage.camera.pushIn(click, { to: () => ({ x: cam.offsetLeft + 0.42 * cam.offsetWidth, y: cam.offsetTop + 0.45 * cam.offsetHeight }), scale: 1.12, dur: 1.2 });
     return (t: number) => {
       const st = terminal(t, COMMANDS, { at: 0.5, cps: 16 });
-      win.innerHTML = st.lines
-        .map((l) => `<div>${l.kind === "cmd" ? `<span style="color:var(--kf-accent)">${l.prompt} </span>` : ""}${l.text.replace(/</g, "&lt;")}${l.caret ? '<span style="display:inline-block;width:.55em;height:1.1em;vertical-align:-.2em;background:var(--kf-accent)"></span>' : ""}</div>`)
-        .join("");
+      // 명령을 친 뒤에는 그 일의 진행이 구른다 — 프레임 수가 장면 끝까지 차오른다(쉬지 않기를 뜻 있는 숫자가 진다)
+      const done = Math.round(FRAMES * Math.min(1, Math.max(0, (t - typed) / Math.max(0.5, ctx.dur - typed))));
+      const run = t > typed ? `<div style="color:var(--kf-dim)">프레임 ${String(done).padStart(4, " ")} / ${FRAMES}</div>` : "";
+      win.innerHTML =
+        st.lines
+          .map((l) => `<div>${l.kind === "cmd" ? `<span style="color:var(--kf-accent)">${l.prompt} </span>` : ""}${l.text.replace(/</g, "&lt;")}${l.caret ? '<span style="display:inline-block;width:.55em;height:1.1em;vertical-align:-.2em;background:var(--kf-accent)"></span>' : ""}</div>`)
+          .join("") + run;
       const c = cursor(t, [{ t: 0, x: 900, y: 520 }, { t: click, x: 300, y: 120, click: true }, { t: ctx.dur, x: 360, y: 160 }]);
       applyStyle(pointer, { x: c.x, y: c.y, scale: c.pressed ? 0.9 : 1 });
       applyStyle(cam, enter(MOVE, t, { at: 0, scene: ctx.id }));

package/templates/ad/template.json

@@ -69,6 +69,24 @@
     },
     "beatMove": "every-beat"
   },
+  "moves": {
+    "text": [
+      "slamWords",
+      "splitFlap",
+      "ransomLetters"
+    ],
+    "wipe": [
+      "brushWipe",
+      "flood"
+    ],
+    "roles": {
+      "brand": {
+        "text": [
+          "slamWords"
+        ]
+      }
+    }
+  },
   "scenes": [
     {
       "id": "brand",
@@ -101,7 +119,8 @@
     ],
     "gen": [
       "img:message-hero"
-    ]
+    ],
+    "act": "message"
   },
   "deliverables": [
     "mp4",

package/templates/demo/template.json

@@ -42,6 +42,17 @@
     },
     "beatMove": "drop-sections"
   },
+  "moves": {
+    "text": [
+      "bigWord",
+      "ghostStack",
+      "splitFlap"
+    ],
+    "wipe": [
+      "irisBlades",
+      "none"
+    ]
+  },
   "scenes": [
     {
       "id": "intro",

package/templates/explainer/template.json

@@ -1,7 +1,7 @@
 {
   "id": "explainer",
   "label": "설명",
-  "summary": "원리 설명 — 도식 하나를 단계마다 키워 가며, 화면 글은 전문 낱말만, 자막 트랙",
+  "summary": "원리 설명 — 도식 하나를 단계마다 키워 가며, 화면 글은 전문 낱말만, 차분한 내레이션·자막 트랙·깊은 앰비언트 곡",
   "aspect": "16:9",
   "width": 1920,
   "height": 1080,
@@ -23,7 +23,29 @@
     "max": 120,
     "default": 90
   },
-  "music": "optional",
+  "music": "required",
+  "mood": "deep",
+  "narration": {
+    "on": true,
+    "lang": "ko",
+    "style": "차분하고 낮은 다큐멘터리 내레이션. 서두르지 않고 문장 끝을 내려 놓는다",
+    "voice": "elevenlabs:George",
+    "voices": {
+      "elevenlabs": "George",
+      "gemini": "Charon",
+      "dashscope": "Neil",
+      "local": "Sohee"
+    },
+    "lead": 0.25,
+    "tail": 0.5
+  },
+  "audio": {
+    "musicDb": -20,
+    "duck": true,
+    "lufs": -14,
+    "truePeak": -1.5,
+    "fadeOut": 1.5
+  },
   "captions": "off",
   "loop": false,
   "style": "og",
@@ -54,6 +76,25 @@
     },
     "beatMove": "drop-sections"
   },
+  "moves": {
+    "text": [
+      "bigWord",
+      "ghostStack",
+      "splitFlap"
+    ],
+    "wipe": [
+      "irisBlades",
+      "flood",
+      "none"
+    ],
+    "roles": {
+      "hook": {
+        "text": [
+          "slamWords"
+        ]
+      }
+    }
+  },
   "scenes": [
     {
       "id": "hook",
@@ -69,6 +110,14 @@
       "snap": "beat",
       "idea": "질문 하나 — 왜 그런가. 낱말 하나와 도식의 빈자리"
     },
+    {
+      "id": "turn",
+      "role": "seam",
+      "sec": 1.5,
+      "snap": "beat",
+      "transition": "portal",
+      "idea": "이음매 — question 의 빈자리가 문이 되어 mechanism 도식 안으로 들어간다(3D 전환, 틀이 맡는다 — 장면 파일은 그대로 둔다)"
+    },
     {
       "id": "mechanism",
       "role": "explain",
@@ -104,7 +153,9 @@
       "data",
       "logo"
     ],
-    "gen": []
+    "gen": [],
+    "shot3d": "mechanism",
+    "act": "example"
   },
   "deliverables": [
     "mp4",

package/templates/launch/template.json

@@ -42,6 +42,37 @@
     },
     "beatMove": "every-beat"
   },
+  "moves": {
+    "text": [
+      "ghostStack",
+      "splitFlap",
+      "slamWords",
+      "echoStack"
+    ],
+    "wipe": [
+      "irisBlades",
+      "flood",
+      "brushWipe"
+    ],
+    "roles": {
+      "tease": {
+        "text": [
+          "ghostStack"
+        ]
+      },
+      "reveal": {
+        "text": [
+          "slamWords"
+        ]
+      },
+      "end": {
+        "text": [
+          "neonSign",
+          "splitFlap"
+        ]
+      }
+    }
+  },
   "scenes": [
     {
       "id": "tease",
@@ -98,7 +129,9 @@
     ],
     "gen": [
       "img:reveal-hero"
-    ]
+    ],
+    "shot3d": "reveal",
+    "act": "tease"
   },
   "deliverables": [
     "mp4",

package/templates/mv/scenes/default.ts

@@ -20,14 +20,11 @@ function plans(ctx: SceneCtx) {
 }
 
 // 뮤비 한 구간 — 바탕은 잰 마디마다(드롭 구간은 박마다) 색·자리를 바꾸고, 가사는 JIZURA 층이 부른 시각에 그린다.
-// JIZURA 가 안 깔렸거나(kf setup jizura) lyrics.json 이 없으면 부른 낱말을 DOM 으로 띄운다
+// lyrics.json 이 없거나 사람이 낱말로를 골랐으면(kf lyrics use <폴더> words) 부른 낱말을 DOM 으로 띄운다
 export default {
   build(root: HTMLElement, ctx: SceneCtx) {
-    // 흐르는 빛 방울·컷마다 바뀌는 판(makeStage 바탕)이 「쉬지 않기」를 진다 — 가사 층은 흔들지 않는다
+    // 「쉬지 않기」는 가사가 진다 — 가사 층, 없으면 부르는 낱말이 왼쪽부터 차오른다. 바탕은 정지(마디마다 색만 바뀐다)
     const st = makeStage(root, ctx);
-    const dots = document.createElement("div");
-    dots.style.cssText = "position:absolute;inset:-120px;background-image:radial-gradient(circle, var(--kf-line) 3px, transparent 3.6px);background-size:60px 60px";
-    st.box.insertBefore(dots, st.box.firstChild);
     const stage = document.createElement("div");
     stage.style.cssText = "position:absolute;inset:0;display:flex;flex-wrap:wrap;align-content:center;justify-content:center;padding:8% 10%;box-sizing:border-box;container-type:size";
     st.cam.append(stage);
@@ -39,7 +36,6 @@ export default {
     const decided = jizuraReady().then((ok) => (jz = ok));
 
     const lines = (lyrics?.lines ?? []).filter((l) => l.end > ctx.from && l.start < ctx.from + ctx.dur).map((l) => ({ ...l, ws: wordsOf(l) }));
-    // accent-soft 바탕에는 같은 계열인 빛 방울(늘 흐르는 몫)이 묻혀 가사가 서 있는 동안 0.1초 멈춤이 된다 — 빼 둔다
     const tones = ["var(--kf-bg)", "var(--kf-surface)", "var(--kf-raised)"];
     const spots = ["center", "flex-start", "flex-end"];
     let shown = "";
@@ -62,7 +58,15 @@ export default {
         });
       }
       const pulse = beatPulse(t, { beats: ctx.beats, rules: ctx.style.motion, scene: ctx.id, source: "lyric" });
-      spans.forEach((s, i) => applyStyle(s, combine(enter("pop", T, { at: ws[i]?.start ?? 0, scene: ctx.id }), pulse)));
+      spans.forEach((s, i) => {
+        applyStyle(s, combine(enter("pop", T, { at: ws[i]?.start ?? 0, scene: ctx.id }), pulse));
+        // 부르는 동안 왼쪽부터 강조색이 찬다 — 부른 데까지가 보인다
+        const w = ws[i];
+        const p = w ? Math.min(1, Math.max(0, (T - w.start) / Math.max(0.05, w.end - w.start))) : 1;
+        s.style.backgroundImage = `linear-gradient(90deg, var(--kf-accent) ${(p * 100).toFixed(2)}%, var(--kf-ink) ${(p * 100).toFixed(2)}%)`;
+        s.style.backgroundClip = "text";
+        s.style.color = "transparent";
+      });
     }
 
     let last = 0;
@@ -70,7 +74,6 @@ export default {
     const draw = (t: number) => {
       last = t;
       undecided = jz === null;
-      dots.style.transform = `translate(${((t * 24) % 60).toFixed(2)}px, ${((t * 36) % 60).toFixed(2)}px)`;
       const inDrop = ctx.beats.inDrop(t);
       const grid = inDrop ? ctx.beats.beats : ctx.beats.bars;
       const cut = Math.max(0, grid.filter((g) => g <= t).length - 1);

package/templates/mv/template.json

@@ -28,7 +28,7 @@
   "lyrics": {
     "mode": "kinetic",
     "align": "kf lyrics align <곡> --text 공식가사.txt --lang ko — 보컬 분리 + whisper 강제 정렬로 줄·어절 시각 → lyrics.json(공식 가사가 글자 정본, MMS 는 비상업 가중치라 안 씀)",
-    "layer": "JIZURA 가사 층(@kasaframe/jizura jizuraLayer) — kf setup jizura, 없으면 DOM 낱말",
+    "layer": "JIZURA 가사 층(@kasaframe/jizura jizuraLayer) — 엔진·자주 쓰는 한글 글꼴은 실려 있다, lyrics.json 이 없으면 DOM 낱말",
     "lipsync": "rhubarb — 캐릭터 입 모양을 보컬에 맞출 자리(선택)"
   },
   "loop": false,
@@ -144,7 +144,9 @@
       "img:character",
       "img:world-bg"
     ],
-    "genVideo": []
+    "genVideo": [],
+    "shot3d": "drop",
+    "act": "main"
   },
   "deliverables": [
     "mp4",