kasaframe 0.0.0-stage → 0.1.3

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

@@ -0,0 +1,292 @@
+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초도 쉬지 않는다」는 내용의 움직임이 맡는다 — 글·숫자 수(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; // 바탕 층(장면 전체) — 늘 흐르는 것은 여기에만
+  cam: HTMLDivElement; // 카메라 층 — 주 요소는 여기에. 가만히 있다가 camera 가 시킬 때만 움직인다
+  camera: Camera;
+  safeW: number;
+  safeH: number;
+  vertical: boolean;
+  /** 주인공 표시 — kf check 의 layout.edge 가 이 상자가 안전 영역 가장자리에 붙는지 본다(bigWord 는 스스로 단다) */
+  hero(el: HTMLElement): HTMLElement;
+  /**
+   * 낱말을 고른 글 수(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;
+}
+
+/** 카메라 층 안 좌표(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;
+}
+
+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 가 장면을 켜고 끌 때 쓴다 — 배치는 안쪽 상자에
+  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;
+  // 바탕은 정지(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);
+  const stage: Stage = {
+    box,
+    cam,
+    camera,
+    safeW,
+    safeH,
+    vertical: height > width,
+    hero(el) {
+      el.dataset.kfHero = "";
+      return el;
+    },
+    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 + 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 이 아니라 여기서 움직임을 끝낸다
+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,21 @@
+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 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, { dress: DRESS });
+    const words = stage.say(WORDS, { enter: MOVE });
+    return (t: number) => {
+      words.paint(t);
+      stage.tick(t);
+    };
+  },
+};

package/templates/_shared/scenes/drop.ts

@@ -0,0 +1,33 @@
+import { applyStyle, combine, type SceneCtx } from "@kasaframe/core";
+import { beatPulse, dropBurst, type MoveName } from "@kasaframe/motion";
+import type { Dress } from "@kasaframe/motion/moves";
+import { makeStage } from "../lib/stage.ts";
+
+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, { 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 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) => {
+      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 = 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

@@ -0,0 +1,26 @@
+import { applyStyle, type SceneCtx } from "@kasaframe/core";
+import { enter, type MoveName } from "@kasaframe/motion";
+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, { dress: DRESS });
+    const name = stage.say([NAME], { enter: MOVE });
+    const line = document.createElement("div");
+    line.textContent = LINE;
+    // 이름 수가 안전 영역을 다 쓰니 한 줄은 아래 띠에 — 이름과 겹치지 않는다
+    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) => {
+      name.paint(t);
+      applyStyle(line, enter("fade", t, { at: 0.25, scene: ctx.id }));
+      stage.tick(t);
+    };
+  },
+};

package/templates/_shared/scenes/hook.ts

@@ -0,0 +1,18 @@
+import { clip, ease, type SceneCtx } from "@kasaframe/core";
+import type { Dress } from "@kasaframe/motion/moves";
+import { makeStage } from "../lib/stage.ts";
+
+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, { 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);
+    };
+  },
+};

package/templates/_shared/scenes/seam.ts

@@ -0,0 +1,41 @@
+import type { SceneCtx } from "@kasaframe/core";
+import { transition3d, type Transition3dName } from "@kasaframe/motion/transition3d";
+import kf from "../kf.json";
+
+// 앞·뒤 장면을 살아 있는 화면으로 넘긴다(전환 중에도 앞 장면이 계속 돈다). 그걸 못 하는 브라우저면 assets/seam 정지 그림
+const scenes = import.meta.glob("./*.ts", { eager: true });
+
+// 이음매 — 앞 장면 마지막 화면에서 뒤 장면 첫 화면으로 잇는 모션그래픽 전환. 앞뒤 화면 두 장(assets/seam/<id>-from·to.png)은
+// kf make 가 장면을 다 쓴 뒤 찍어 넣고, 없으면 style 색 대체 화면으로 돈다. 종류: dive·portal·cards·shatter·zoomOut·fold
+const KIND = "{{transition}}" as Transition3dName;
+
+// 요청에 「영상 생성」을 적어 생성 영상(assets/gen/<id>.mp4)이 만들어졌으면 그걸 깐다 —
+// 없는 <video> 를 넣으면 페이지 ready 가 loadeddata 를 끝없이 기다려서 먼저 있는지 본다
+function exists(url: string): boolean {
+  const x = new XMLHttpRequest();
+  x.open("HEAD", url, false);
+  try {
+    x.send();
+  } catch {
+    return false;
+  }
+  return x.status === 200 && (x.getResponseHeader("content-type") ?? "").startsWith("video/");
+}
+
+export default {
+  build(root: HTMLElement, ctx: SceneCtx) {
+    const url = ctx.asset(`gen/${ctx.id}.mp4`);
+    if (exists(url)) {
+      const video = document.createElement("video");
+      video.src = url;
+      video.muted = true;
+      video.playsInline = true;
+      video.preload = "auto";
+      video.dataset.kfFrom = String(ctx.from);
+      video.style.cssText = "position:absolute;inset:0;width:100%;height:100%;object-fit:cover";
+      root.append(video);
+      return () => {};
+    }
+    return transition3d(root, ctx, { kind: KIND, live: { kf, scenes } });
+  },
+};

package/templates/_shared/scenes/step.ts

@@ -0,0 +1,49 @@
+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, { dress: DRESS });
+    const cam = document.createElement("div");
+    // 창이 바탕을 다 덮으면 흐르는 바탕이 안 보여 멈춘 화면이 된다 — 둘레를 남긴다
+    cam.style.cssText = "position:relative;width:min(1100px, 70%)";
+    const win = document.createElement("div");
+    win.style.cssText = "background:var(--kf-surface);border:1px solid var(--kf-line);border-radius:var(--kf-radius-lg);box-shadow:var(--kf-shadow-lift);padding:40px 48px;min-height:520px;font-family:var(--kf-font-mono);font-size:46px;line-height:1.6;color:var(--kf-ink)";
+    const badge = document.createElement("div");
+    badge.textContent = STEP;
+    badge.style.cssText = "position:absolute;left:-24px;top:-36px;background:var(--kf-accent);color:var(--kf-on-accent);font-family:var(--kf-font-display);font-weight:800;font-size:max(44px, var(--kf-size-body));padding:10px 22px;border-radius:var(--kf-radius-pill)";
+    const pointer = document.createElement("div");
+    pointer.innerHTML = '<svg width="44" height="44" viewBox="0 0 24 24"><path d="M4 2 L4 20 L9 15 L12.5 22 L15.5 20.5 L12 13.8 L19 13.8 Z" fill="currentColor" stroke="white" stroke-width="1.4" stroke-linejoin="round"/></svg>';
+    pointer.style.cssText = "position:absolute;left:0;top:0;color:var(--kf-ink);filter:drop-shadow(0 2px 4px rgba(0,0,0,.25))";
+    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 });
+      // 명령을 친 뒤에는 그 일의 진행이 구른다 — 프레임 수가 장면 끝까지 차오른다(쉬지 않기를 뜻 있는 숫자가 진다)
+      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 }));
+      stage.tick(t);
+    };
+  },
+};

package/templates/ad/template.json

@@ -0,0 +1,151 @@
+{
+  "id": "ad",
+  "label": "광고",
+  "summary": "광고 — 6·15·30초 고정, 브랜드는 첫 2초 안",
+  "aspect": "16:9",
+  "width": 1920,
+  "height": 1080,
+  "fps": 60,
+  "variants": {
+    "9:16": {
+      "width": 1080,
+      "height": 1920,
+      "safeArea": {
+        "top": 230,
+        "bottom": 460,
+        "left": 40,
+        "right": 40
+      }
+    },
+    "1:1": {
+      "width": 1080,
+      "height": 1080,
+      "safeArea": {
+        "top": 60,
+        "bottom": 60,
+        "left": 60,
+        "right": 60
+      }
+    }
+  },
+  "duration": {
+    "min": 6,
+    "max": 30,
+    "default": 15,
+    "allowed": [
+      6,
+      15,
+      30
+    ]
+  },
+  "music": "optional",
+  "captions": "on",
+  "loop": false,
+  "style": "kasaterm",
+  "safeArea": {
+    "top": 60,
+    "bottom": 60,
+    "left": 80,
+    "right": 80
+  },
+  "text": {
+    "policy": "captions",
+    "maxOnScreen": 6,
+    "minPx": 56
+  },
+  "motion": {
+    "beatPulse": "drops-only",
+    "shake": {
+      "on": [],
+      "maxPerPhrase": 0,
+      "maxPx": 0
+    },
+    "cameraMove": "once-per-phrase",
+    "repeatSameMove": false,
+    "maxFreezeSec": 0.1,
+    "staticSec": {
+      "warn": 1.5,
+      "error": 3
+    },
+    "beatMove": "every-beat"
+  },
+  "moves": {
+    "text": [
+      "slamWords",
+      "splitFlap",
+      "ransomLetters"
+    ],
+    "wipe": [
+      "brushWipe",
+      "flood"
+    ],
+    "roles": {
+      "brand": {
+        "text": [
+          "slamWords"
+        ]
+      }
+    }
+  },
+  "scenes": [
+    {
+      "id": "brand",
+      "role": "brand",
+      "sec": 2,
+      "anchor": "start",
+      "idea": "브랜드 — 로고나 이름이 첫 2초 안에 또렷하게"
+    },
+    {
+      "id": "message",
+      "role": "message",
+      "weight": 1,
+      "snap": "beat",
+      "idea": "한 가지 약속 — 문장 하나, 그걸 보여 주는 그림 하나"
+    },
+    {
+      "id": "cta",
+      "role": "end",
+      "sec": 2,
+      "anchor": "end",
+      "idea": "행동 한 줄 — 주소·버튼·날짜. 로고 다시"
+    }
+  ],
+  "assets": {
+    "need": [
+      "logo"
+    ],
+    "want": [
+      "product-shots"
+    ],
+    "gen": [
+      "img:message-hero"
+    ],
+    "act": "message"
+  },
+  "deliverables": [
+    "mp4",
+    "cover"
+  ],
+  "detect": {
+    "words": [
+      "광고",
+      "범퍼",
+      "범퍼 광고",
+      "CF",
+      "광고 영상",
+      "ad",
+      "advert",
+      "commercial",
+      "bumper"
+    ],
+    "hints": [
+      "6초",
+      "15초",
+      "30초",
+      "캠페인",
+      "campaign",
+      "cta"
+    ],
+    "aspect": "16:9"
+  }
+}