kasaframe 0.1.1 → 0.1.3

package/packages/motion/README.md

@@ -86,6 +86,10 @@ export default {
 | `fold` | 병풍처럼 접혀 옆으로 빠진다. `fold: "roll"` 이면 아래부터 말려 올라간다 |
 | `diveChain` | 화면 속 화면 — `screens` 를 깊이로 늘어놓고 끊김 없이 뚫고 들어간다. `arrivals: "bar"`·`"beat"`(박마다 한 겹) 또는 시각 배열, `settle` 0 흘러가기 … 1 화면마다 멈추기 |
 | `whip` | 휙 넘기기 — 제자리에서 90° 를 휙 돈다. 반대로 살짝 감았다가 확 돌고 넘쳤다 선다, 도는 동안 기울고 화각이 넓어진다 |
+| `rise` | 2D → 3D 공간 잇기 — 앞 장면 판이 바닥으로 눕고, 그 주인공 상자(`[data-kf-hero]`, 없으면 가장 넓은 글·`hero` 로 직접)가 같은 화면 자리에서 블록으로 선다(옆면은 그 요소의 2D 색). 카메라는 깊이로 기울어 들어가 블록 위를 지나 뒤 장면 벽 앞에 정면으로 선다 |
+| `land` | 3D → 2D 공간 잇기 — 앞 장면(3D 샷 끝 화면) 앞 공간에 누운 판이 일어서고 카메라가 그 판으로 다가간다. 판 위 주인공 블록은 평면으로 내려앉고, 판이 정면으로 꽉 찬 순간이 뒤 장면 첫 화면 |
+
+- **섬광 안전** — 화면 사이로 보이는 하늘은 앞 화면 바탕색 → 뒤 화면 바탕색으로 서서히 넘어간다(`bridgeSky` — 밝기 순 가운데 절반 평균). 밝은 화면과 어두운 공간이 칸마다 엇갈려 오가면 `kf check` 의 `frame.flash` 에 걸린다. `whip` 은 가장 빠를 때 두 판의 대비를 그 색 쪽으로 누른다(셔터가 번진 것처럼, 양 끝은 0).
 
 - **살아 있는 화면** — `live: { kf, scenes: import.meta.glob("./*.ts", { eager: true }) }` 를 주면 앞 장면은 자기 끝을 지나 계속 돌고(타자·카운터가 전환 중에도 이어진다) 뒤 장면은 첫 프레임에서 기다린다. 다른 장면 하나는 `sceneSource(모듈, ctx, { id, from, dur }, (t) => 그 장면 시각)`, 영상은 `{ video: 주소, from: 영상 전체 기준 0 초 }`, 아무 DOM 은 `{ dom(root) { …; return (t) => … }, still? }`. DOM 은 크롬 HTML-in-Canvas(`--enable-features=CanvasDrawElement`, 렌더·검사 브라우저는 켜져 있다)로 seek 마다 paint 이벤트 안에서 텍스처에 올리고 `onSeek` 이 그 페인트를 기다린다 — 같은 t 두 번이 바이트까지 같다. 플래그 없는 브라우저는 `still`(이음매는 `assets/seam` 그림)로 물러난다.
 - **그림** — `from`·`to` 에 주소(`kf still` PNG 등)·`<img>`·`<canvas>`·그리기 함수 `(g, t, w, h) => void`(같은 t 같은 그림). ctx 만 주면 `assets/seam/<장면id>-from.png`(앞 장면 마지막 프레임)·`-to.png`(뒤 장면 첫 프레임)을 쓰고, 없으면 스타일 색으로 그린 대체 화면(없는 파일을 부르지 않아 검사가 깨끗하다). 찍는 곳은 `kf make`(장면을 다 쓴 뒤 `@kasaframe/gen` 의 `seamFrames` 프레임으로).
@@ -115,6 +119,13 @@ transition3d(root, ctx, { kind: "smooth:sdf-merge" });        // SmoothUI 덮개
 - 들이지 않은 것 — React Bits·Animate UI(MIT + Commons Clause), Aceternity UI(재배포 금지). 출처·라이선스 원문은 레포 루트 `NOTICE`, 폴더마다 원본 `LICENSE`.
 - 갤러리 — `packages/motion/demo/transitions-gallery`(이름으로 부르는 145개 + CSS 부품, seek), `transitions-gallery-step`(rAF 부품 8개, step). `npx kf sheet <폴더> --per-scene 1` 이 전환마다 가운데 프레임 한 장.
 
+## 연출 수 — `@kasaframe/motion/moves`
+
+영상에서 모은 수(글·선·그림 바탕·전환·UI) — 수마다 3–5초 예시와 갤러리는 [`examples/moves/`](../../examples/moves/README.md). 꼴은 거의 다 `수(el, { w, h, hits, scene, … }) → (t) => void`.
+
+- `MENU`·`bundleFor(틀 moves, 테마)`·`pickDress(씨앗, 장면, 묶음)`(`@kasaframe/motion/menu` — DOM 없이 Node 에서도): 뼈대가 바로 거는 메뉴와 장면마다 시드로 고르기. 같은 요청이면 같은 수, 이어지는 장면은 다른 수, 경계 덮기는 이음매·드롭 앞에 안 건다.
+- `dressBg`·`dressText`·`dressWipe`: 메뉴 이름을 장면에 거는 쪽 — 예시에서 검사를 넘긴 값을 기본으로. 덮기는 경계의 영상 시각을 씨앗으로 써 앞 장면 끝과 뒤 장면 처음이 같은 덮개로 이어진다. 무대(`lib/stage.ts` `makeStage(root, ctx, { dress })`)가 부른다.
+
 ## 규칙(style.json `motion`)과 검사
 
 - 박 펄스·흔들림·섬광·카메라·등장 움직임은 효과가 0 이 아닌 프레임마다 `window.__kf.events` 에 한 줄 남긴다 — `kf check` 가 규칙 위반을 센다. **손으로 짠 흔들림은 안 잡힌다** — 위 부품을 쓴다.

package/packages/motion/package.json

@@ -11,6 +11,7 @@
     "./transitions2d": "./src/transitions2d/index.ts",
     "./transitions2d/react": "./src/transitions2d/react.ts",
     "./moves": "./src/moves/index.ts",
+    "./menu": "./src/moves/menu.ts",
     "./captions": "./src/captions.ts"
   },
   "dependencies": {

package/packages/motion/src/captions.ts

@@ -1,4 +1,4 @@
-import type { KfStyle, SafeArea } from "@kasaframe/core";
+import type { CaptionLook, KfStyle, SafeArea } from "@kasaframe/core";
 
 // 자막 — 들릴 말(captions.json)을 장면 시각에 나눠 화면 아래 판에 얹는다.
 // srt·vtt(plan 의 writeCaptions)와 같은 toCues 를 써서 트랙과 화면 자막이 한 마디도 어긋나지 않는다.
@@ -61,6 +61,10 @@ export interface CaptionMetrics {
   centerX: number;
   /** 자막 띠 위아래 여백(px) */
   gap: number;
+  /** 한 마디 줄 수 */
+  maxLines: number;
+  /** style.json captions.position — 판 가운데 y(px). 있으면 bottom 대신 이 자리 */
+  centerY?: number;
 }
 
 /** 판 높이(px) — 줄 수만큼 */
@@ -69,16 +73,18 @@ export function plateHeight(m: CaptionMetrics, lines: number): number {
 }
 
 /** 자막 띠 — 안전 영역 아래쪽에서 장면이 비워 줄 높이(px). 판 + 위아래 여백 */
-export function captionBand(m: CaptionMetrics, lines = 2): number {
-  return plateHeight(m, lines) + m.gap * 2;
+export function captionBand(m: CaptionMetrics, lines = m.maxLines): number {
+  if (m.centerY === undefined) return plateHeight(m, lines) + m.gap * 2;
+  // 판을 정한 자리에 두면 띠는 판 윗변부터 안전 영역 아래 끝까지 — 판이 그 아래(플랫폼 UI 자리)에 있으면 장면은 비켜 줄 것이 없다
+  return Math.max(0, Math.round(m.bottom + m.gap - (m.centerY - plateHeight(m, lines) / 2) + m.gap));
 }
 
-export function captionMetrics(o: { width: number; height: number; safe?: SafeArea | null; minPx?: number }): CaptionMetrics {
+export function captionMetrics(o: { width: number; height: number; safe?: SafeArea | null; minPx?: number; look?: CaptionLook | null }): CaptionMetrics {
   const safe = o.safe ?? { top: 0, bottom: 0, left: 0, right: 0 };
   const short = Math.min(o.width, o.height);
   const vertical = o.height > o.width;
   // 세로 쇼츠는 폰 한 손 거리에서 읽혀야 한다 — 폭의 8%(1080 폭이면 86px). 가로는 높이의 5%
-  const fontPx = Math.max(o.minPx ?? 0, Math.round(vertical ? o.width * 0.08 : short * 0.05));
+  const fontPx = Math.max(o.minPx ?? 0, Math.round(o.look?.size ?? (vertical ? o.width * 0.08 : short * 0.05)));
   const padX = Math.round(fontPx * 0.5);
   const padY = Math.round(fontPx * 0.2);
   const gap = Math.round(short * 0.02);
@@ -96,6 +102,8 @@ export function captionMetrics(o: { width: number; height: number; safe?: SafeAr
     bottom: o.height - safe.bottom - gap,
     centerX: safe.left + (o.width - safe.left - safe.right) / 2,
     gap,
+    maxLines: Math.max(1, Math.round(o.look?.maxLines ?? 2)),
+    ...(o.look?.position !== undefined ? { centerY: o.look.position } : {}),
   };
 }
 
@@ -173,8 +181,8 @@ export function splitPhrases(text: string): string[] {
 }
 
 // 두 줄에 안 드는 마디는 어절 경계에서 몇 토막으로 나눈다 — 토막 길이는 고르게, 끝은 조사·어미 뒤에서(「흡수해 잠재 / 공간에서」처럼 덩어리를 가르지 않게)
-function chunk(text: string, maxEm: number): string[] {
-  if (wrapCaption(text, maxEm)) return [text];
+function chunk(text: string, maxEm: number, lines = 2): string[] {
+  if (wrapCaption(text, maxEm, emWidth, lines)) return [text];
   const words = text.split(/\s+/).filter(Boolean);
   const n = words.length;
   const part = (i: number, j: number) => words.slice(i, j).join(" ");
@@ -189,7 +197,7 @@ function chunk(text: string, maxEm: number): string[] {
         for (let i = c - 1; i < j; i++) {
           if (!Number.isFinite(best[i][c - 1])) continue;
           const p = part(i, j);
-          if (!wrapCaption(p, maxEm)) continue;
+          if (!wrapCaption(p, maxEm, emWidth, lines)) continue;
           const cost = best[i][c - 1] + Math.abs(emWidth(p) - ideal) / ideal + (j < n && looseEnd(words[j - 1]) ? 0.6 : 0);
           if (cost < best[j][c]) {
             best[j][c] = cost;
@@ -209,11 +217,11 @@ function chunk(text: string, maxEm: number): string[] {
 }
 
 // 한 줄 반에 못 미치는 짧은 마디(「MLA,」)는 다음 마디에 붙인다 — 0.5초짜리 자막은 읽기 전에 사라진다
-function merge(parts: string[], maxEm: number): string[] {
+function merge(parts: string[], maxEm: number, lines = 2): string[] {
   const out: string[] = [];
   for (const p of parts) {
     const prev = out[out.length - 1];
-    if (prev !== undefined && emWidth(prev) < 4 && wrapCaption(`${prev}, ${p}`, maxEm)) out[out.length - 1] = `${prev}, ${p}`;
+    if (prev !== undefined && emWidth(prev) < 4 && wrapCaption(`${prev}, ${p}`, maxEm, emWidth, lines)) out[out.length - 1] = `${prev}, ${p}`;
     else out.push(p);
   }
   return out;
@@ -232,7 +240,7 @@ function spread(texts: string[], from: number, to: number, cues: Cue[]): void {
   }
 }
 
-function fromWords(raw: CaptionWord[], maxEm: number, cues: Cue[]): number {
+function fromWords(raw: CaptionWord[], maxEm: number, cues: Cue[], lines = 2): number {
   const before = cues.length;
   const words = raw
     .map((w) => ({ text: (w.text ?? w.w ?? "").trim(), from: w.from ?? w.start ?? NaN, to: w.to ?? w.end ?? NaN }))
@@ -244,7 +252,7 @@ function fromWords(raw: CaptionWord[], maxEm: number, cues: Cue[]): number {
     cur = [];
   };
   for (const w of words) {
-    if (cur.length && !wrapCaption([...cur, w].map((x) => x.text).join(" "), maxEm)) flush();
+    if (cur.length && !wrapCaption([...cur, w].map((x) => x.text).join(" "), maxEm, emWidth, lines)) flush();
     cur.push(w);
     if (/[.?!。]$/.test(w.text)) flush();
   }
@@ -256,12 +264,13 @@ function fromWords(raw: CaptionWord[], maxEm: number, cues: Cue[]): number {
  * captions.json 줄 → 시각 붙은 자막 마디. 장면에만 묶인 줄은 쉼표·마침표 마디로 나눠 글자 수 비율로 장면 시간에 펴고,
  * from·to 가 있으면 그 안에, words 가 있으면 낱말 시각 그대로. maxEm(captionMetrics) 을 주면 마디마다 두 줄 안에 들게 더 나눈다.
  */
-export function toCues(lines: CaptionLine[], scenes: Span[], o: { maxEm?: number; duration?: number } = {}): Cue[] {
+export function toCues(lines: CaptionLine[], scenes: Span[], o: { maxEm?: number; duration?: number; maxLines?: number } = {}): Cue[] {
   const maxEm = o.maxEm ?? Infinity;
+  const rows = o.maxLines ?? 2;
   const cues: Cue[] = [];
   for (const l of lines) {
     const text = (l.text ?? "").trim();
-    if (l.words?.length && fromWords(l.words, maxEm, cues) > 0) continue;
+    if (l.words?.length && fromWords(l.words, maxEm, cues, rows) > 0) continue;
     if (!text) continue;
     let from: number;
     let to: number;
@@ -275,7 +284,7 @@ export function toCues(lines: CaptionLine[], scenes: Span[], o: { maxEm?: number
       from = s.from + pad;
       to = s.from + s.dur - pad;
     }
-    const parts = merge(splitPhrases(text).flatMap((p) => chunk(p, maxEm)), maxEm);
+    const parts = merge(splitPhrases(text).flatMap((p) => chunk(p, maxEm, rows)), maxEm, rows);
     spread(parts, from, to, cues);
   }
   cues.sort((a, b) => a.from - b.from);
@@ -321,7 +330,7 @@ function palette(style: KfStyle | null | undefined): { plate: string; ink: strin
  * 판은 안전 영역 아래쪽 가운데, 한 마디는 두 줄까지 — 넘치면 글자를 줄인다.
  */
 export async function captionLayer(host: HTMLElement, o: CaptionLayerOptions): Promise<{ draw: (t: number) => void; band: number }> {
-  const m = captionMetrics(o);
+  const m = captionMetrics({ ...o, look: o.style?.captions });
   const fam = o.style?.fonts?.sans ?? '"Pretendard Variable", Pretendard, "Noto Sans KR", "Apple SD Gothic Neo", sans-serif';
   const weight = 700;
   const font = (px: number) => `${weight} ${px}px ${fam}`;
@@ -335,11 +344,11 @@ export async function captionLayer(host: HTMLElement, o: CaptionLayerOptions): P
   };
   const laid: Laid[] = o.cues.map((cue) => {
     for (let px = m.fontPx; px >= Math.round(m.fontPx * 0.8); px--) {
-      const lines = wrapCaption(cue.text, m.textMaxPx, measure(px));
+      const lines = wrapCaption(cue.text, m.textMaxPx, measure(px), m.maxLines);
       if (lines) return { cue, lines, fontPx: px };
     }
     const px = Math.round(m.fontPx * 0.8);
-    return { cue, lines: wrapCaption(cue.text, m.textMaxPx, measure(px), 3) ?? [cue.text], fontPx: px };
+    return { cue, lines: wrapCaption(cue.text, m.textMaxPx, measure(px), m.maxLines + 1) ?? [cue.text], fontPx: px };
   });
 
   const { plate: plateBg, ink, edge } = palette(o.style);
@@ -351,8 +360,7 @@ export async function captionLayer(host: HTMLElement, o: CaptionLayerOptions): P
   plate.style.cssText = [
     "position:absolute",
     `left:${m.centerX}px`,
-    `bottom:${o.height - m.bottom}px`,
-    "transform:translateX(-50%)",
+    ...(m.centerY !== undefined ? [`top:${m.centerY}px`, "transform:translate(-50%, -50%)"] : [`bottom:${o.height - m.bottom}px`, "transform:translateX(-50%)"]),
     `max-width:${m.textMaxPx + m.padX * 2}px`,
     "box-sizing:border-box",
     `padding:${m.padY}px ${m.padX}px`,
@@ -452,7 +460,7 @@ export interface CaptionsPlan {
  * on: 무대(ctx.safe 로 배치하는 장면)가 띠 위로 제 크기 그대로 올라간다. 픽셀을 박아 둔 장면은 안 움직여 kf check 가 caption.overlap 으로 잡는다.
  * fit: 장면 코드와 안전 영역은 그대로 두고 장면 뿌리를 띠 위로 줄여 올린다 — 어떤 장면이든 안 겹치지만 내용이 작아지고 움직이는 면적도 준다.
  */
-export async function captionsPlan(o: { kf: ProjectLike; mode?: string | null }): Promise<CaptionsPlan | null> {
+export async function captionsPlan(o: { kf: ProjectLike; mode?: string | null; style?: KfStyle | null }): Promise<CaptionsPlan | null> {
   const raw = o.mode ?? o.kf.captions;
   if (captionMode(raw) !== "on") return null;
   const res = await fetch(new URL("captions.json", document.baseURI)).catch(() => null);
@@ -462,12 +470,12 @@ export async function captionsPlan(o: { kf: ProjectLike; mode?: string | null })
   const { kf } = o;
   const minPx = kf.text?.minPx;
   const base = kf.safeArea ?? { top: 0, bottom: 0, left: 0, right: 0 };
-  const m = captionMetrics({ width: kf.width, height: kf.height, safe: base, minPx });
-  const cues = toCues(lines, kf.scenes, { maxEm: m.maxEm, duration: kf.duration });
+  const m = captionMetrics({ width: kf.width, height: kf.height, safe: base, minPx, look: o.style?.captions });
+  const cues = toCues(lines, kf.scenes, { maxEm: m.maxEm, duration: kf.duration, maxLines: m.maxLines });
   if (!cues.length) return null;
   const fit = raw === "fit";
   // 띠는 판이 실제로 쓸 줄 수만큼(어림) — 장면을 짓기 전이라 아직 글꼴로 잴 수 없다
-  const band = captionBand(m, cues.some((c) => !wrapCaption(c.text, m.maxEm, emWidth, 1)) ? 2 : 1);
+  const band = captionBand(m, cues.some((c) => !wrapCaption(c.text, m.maxEm, emWidth, 1)) ? m.maxLines : 1);
   return {
     safe: fit ? base : { ...base, bottom: base.bottom + band },
     async mount(stage, style) {

package/packages/motion/src/moves/brushWipe.ts

@@ -71,7 +71,8 @@ export function brushWipe(el: HTMLElement, o: BrushWipeOpts): (t: number) => voi
       g.closePath();
       g.fill();
       // 마른 붓 줄무늬 — 띠 안에서 밝은 결 몇 줄
-      g.globalAlpha = 0.18;
+      // 결은 옅게 — 진하면 띠가 지나는 동안 칸마다 밝음·어둠이 오가 섬광 검사(frame.flash)에 걸린다
+      g.globalAlpha = 0.07;
       g.fillStyle = "#ffffff";
       const a = Math.min(edge(head, 0, 12), edge(tail, 1, 12));
       const b = Math.max(edge(head, 0, 12), edge(tail, 1, 12));
@@ -83,6 +84,18 @@ export function brushWipe(el: HTMLElement, o: BrushWipeOpts): (t: number) => voi
         g.fillRect(Math.min(x0, x1), y, Math.abs(x1 - x0), 2 + 5 * r(3));
       }
     }
+    // 다 덮인 동안 광택 한 줄이 띠를 따라 휙 지난다 — 한 색으로 덮인 화면이 0.1초 넘게 서 있으면 멈춤(frame.freeze)으로 잡힌다
+    const sp = clamp((t - o.at - dur * 0.22) / (dur * 0.56));
+    if (sp > 0 && sp < 1) {
+      const x = -D / 2 + D * sp;
+      const gr = g.createLinearGradient(x - D * 0.12, 0, x + D * 0.12, 0);
+      gr.addColorStop(0, "rgba(255,255,255,0)");
+      gr.addColorStop(0.5, "rgba(255,255,255,.14)");
+      gr.addColorStop(1, "rgba(255,255,255,0)");
+      g.globalAlpha = 1;
+      g.fillStyle = gr;
+      g.fillRect(x - D * 0.12, -D / 2, D * 0.24, D);
+    }
     g.restore();
     g.globalAlpha = 1;
     mark("brushWipe", o.scene, true);

package/packages/motion/src/moves/dress.ts

@@ -0,0 +1,191 @@
+import type { SceneCtx } from "@kasaframe/core";
+import { brushWipe } from "./brushWipe.ts";
+import { echoStack } from "./echoStack.ts";
+import { div } from "./fit.ts";
+import { flood } from "./flood.ts";
+import { ghostStack } from "./ghostStack.ts";
+import { gridFloor } from "./gridFloor.ts";
+import { irisBlades } from "./irisBlades.ts";
+import { ledBoard } from "./ledBoard.ts";
+import { neonSign } from "./neonSign.ts";
+import { ransomLetters } from "./ransomLetters.ts";
+import { slamWords } from "./slamWords.ts";
+import { speedLines } from "./speedLines.ts";
+import { splitFlap } from "./splitFlap.ts";
+import { sunburst } from "./sunburst.ts";
+import { truchet } from "./truchet.ts";
+
+// 메뉴(menu.ts)의 이름을 장면에 실제로 건다 — 무대(lib/stage.ts)가 부른다. 수마다 예시 장면에서 검사를 넘긴 값을 기본으로 박아 두어,
+// 뼈대가 고른 수를 그대로 둬도 kf check 를 넘는다. 낱말만 바꿔 쓰면 된다.
+
+type Paint = (t: number) => void;
+
+const color = (ctx: SceneCtx, key: string, fallback: string): string => {
+  const v = ctx.style?.colors?.[key];
+  return typeof v === "string" && v ? v : fallback;
+};
+
+// 상대휘도(WCAG) — #rgb·#rrggbb 만. 못 읽으면 NaN
+function lum(hex: string): number {
+  const m = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(hex.trim());
+  if (!m) return NaN;
+  const h = m[1].length === 3 ? [...m[1]].map((c) => c + c).join("") : m[1];
+  const ch = [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16) / 255).map((c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4));
+  return 0.2126 * ch[0] + 0.7152 * ch[1] + 0.0722 * ch[2];
+}
+
+// 오려 붙인 글자는 한 색이 글자색(바탕 위)도 되고 색종이(검은 글자 밑)도 된다 — 둘 다 3:1 을 넘는 가운데 밝기(0.12–0.3)만 쓴다.
+// 밝은 테마·어두운 테마 어디서나 읽힌다. 테마 강조색이 그 안이면 앞에 둔다
+const RANSOM = ["#E4572E", "#2E86DE", "#16A085", "#8E44AD", "#C0392B", "#D35400"];
+
+/** 장면 안 박 — 빠른 곡은 박을 묶어 간격 gap 넘게. 잰 시각 그대로(BPM 을 곱하지 않는다) */
+export function hitTimes(ctx: SceneCtx, gap = 0.4): number[] {
+  const b = ctx.beats.beats.filter((x) => x >= 0 && x < ctx.dur);
+  if (b.length < 2) return b.length ? b : [0];
+  const step = (b[b.length - 1] - b[0]) / (b.length - 1);
+  const every = Math.max(1, Math.ceil(gap / Math.max(step, 1e-3)));
+  const out = b.filter((_, i) => i % every === 0);
+  // 첫 박이 늦으면 첫 화면이 빈다 — 0 에 하나 세운다
+  if (out[0] > 0.12) out.unshift(0);
+  return out;
+}
+
+const cycle = (words: readonly string[], n: number): string[] => Array.from({ length: n }, (_, i) => words[i % words.length]);
+
+// 한 수를 창(박 n 개)마다 새로 세운다 — 박이 쌓일수록 작아지는 수(메아리·네온)를 긴 장면에서도 같은 크기로 되풀이한다
+function windows(host: HTMLElement, hits: readonly number[], per: number, make: (el: HTMLElement, hits: number[], k: number) => Paint): Paint {
+  const starts: number[] = [];
+  const paints: { el: HTMLElement; paint: Paint }[] = [];
+  for (let i = 0, k = 0; i < hits.length; i += per, k++) {
+    const el = div(host.ownerDocument, "position:absolute;inset:0");
+    host.append(el);
+    starts.push(hits[i]);
+    paints.push({ el, paint: make(el, hits.slice(i, i + per), k) });
+  }
+  return (t) => {
+    let k = 0;
+    while (k + 1 < starts.length && starts[k + 1] <= t) k++;
+    paints.forEach((p, i) => {
+      p.el.style.display = i === k ? "block" : "none";
+      if (i === k) p.paint(t);
+    });
+  };
+}
+
+/** 바탕 수 — el 은 화면 전체. still(기본)은 정지라 그리는 함수가 없다(null). 모르는 이름도 still */
+export function dressBg(name: string, el: HTMLElement, ctx: SceneCtx): Paint | null {
+  const { width: w, height: h } = ctx.meta;
+  const hits = hitTimes(ctx);
+  const bg = color(ctx, "bg", "#0b0b0f");
+  const accent = color(ctx, "accent", "#ff5a1f");
+  const soft = color(ctx, "accentSoft", accent);
+  const line = color(ctx, "line", "#888");
+  el.style.background = bg;
+  switch (name) {
+    case "sunburst":
+      // 글 뒤에 깔리니 바탕에 강조색을 조금만 섞은 두 색 — 박마다 툭 도는 줄무늬가 진하면 화면 대부분이 한꺼번에 꺾여 섬광 검사(frame.flash)에 걸린다
+      return sunburst(el, { w, h, hits, rays: h > w ? 16 : 20, colors: [`color-mix(in srgb, ${accent} 14%, ${bg})`, bg], glow: "transparent", speed: 10, scene: ctx.id });
+    case "speedLines":
+      return speedLines(el, { w, h, kind: "radial", color: soft, inner: 0.36, boil: 8, scene: ctx.id });
+    case "gridFloor":
+      return gridFloor(el, { w, h, color: soft, speed: 1.4, glow: 0, scene: ctx.id });
+    case "truchet":
+      return truchet(el, { w, h, hits, cell: Math.round(Math.min(w, h) / 9), bg, line, accent: soft, share: 0.3, scene: ctx.id });
+    default:
+      // 바탕색 위 아주 옅은 점 — 서 있는 질감이라 화면이 비어 보이지 않을 뿐 아무것도 뜻하지 않으니 움직이지 않는다.
+      // 바탕색은 무대 상자에 맡긴다(장면이 마디마다 바탕색을 바꿀 수 있게)
+      el.style.background = "";
+      el.style.backgroundImage = `radial-gradient(circle, color-mix(in srgb, ${line} 55%, transparent) 1.5px, transparent 2px)`;
+      el.style.backgroundSize = `${Math.round(Math.min(w, h) / 24)}px ${Math.round(Math.min(w, h) / 24)}px`;
+      return null;
+  }
+}
+
+/**
+ * 글 수 — el 은 안전 영역 상자(w×h). words 를 차례로 돌려 쓴다. bigWord(무대 기본)거나 모르면 null — 무대가 큰 낱말을 세운다.
+ * 박마다 내용이 바뀌어(새 낱말·새 벌·판 넘김) 같은 구도 검사(layout.static)를 수가 스스로 넘는다
+ */
+export function dressText(name: string, el: HTMLElement, ctx: SceneCtx, o: { words: readonly string[]; w: number; h: number; ready?: boolean }): Paint | null {
+  const given = [...new Set(o.words.map((x) => x.trim()).filter(Boolean))];
+  const words = given.length ? given : ["kasaframe"];
+  const { w, h } = o;
+  const hits = hitTimes(ctx);
+  // 첫 프레임부터 글이 서 있어야 하는 장면(훅) — 첫 박을 장면 앞으로 당겨 이미 내려앉은 낱말로 시작한다
+  if (o.ready && hits[0] <= 0.15) hits[0] = -0.3;
+  const scene = ctx.id;
+  switch (name) {
+    case "slamWords": {
+      // 화면 폭을 채운 낱말이 1초에 두 번 바뀌면 섬광 세 번을 넘는다(frame.flash) — 1.2초 넘는 간격마다
+      const slams = hitTimes(ctx, 1.2);
+      if (o.ready && slams[0] <= 0.15) slams[0] = -0.3;
+      // 낱말 판은 가운데 띠(높이 55%)에 옅은 강조색으로 — 화면 전체를 뒤집으면 판이 바뀌는 박마다 화면 대부분이 한꺼번에
+      // 밝기가 꺾여 섬광 검사(frame.flash)에 걸린다. 띠가 보여야 긴 낱말 하나뿐인 세로 화면도 비어 보이지 않는다(layout.fill)
+      const bh = Math.round(h * 0.55);
+      const band = div(el.ownerDocument, `position:absolute;left:0;top:${Math.round((h - bh) / 2)}px;width:${w}px;height:${bh}px`);
+      el.append(band);
+      return slamWords(band, { words: cycle(words, slams.length), hits: slams, w, h: bh, palettes: [["color-mix(in srgb, var(--kf-accent) 10%, transparent)", "var(--kf-ink)"], ["color-mix(in srgb, var(--kf-accent) 24%, transparent)", "var(--kf-ink)"]], scene });
+    }
+    case "echoStack":
+      return windows(el, hits, 4, (box, hs, k) => echoStack(box, { word: words[k % words.length], hits: hs, dir: k % 2 ? "back" : "down", w, h, scene }));
+    case "splitFlap": {
+      const times = hits.filter((_, i) => i % 2 === 0);
+      const texts = cycle(words, times.length);
+      // 판에 같은 글이 이어 오르면 넘어가지 않는다 — 낱말이 하나면 판 넘김 대신 글자판을 비웠다 채운다
+      if (words.length === 1) texts.forEach((_, i) => i % 2 && (texts[i] = " ".repeat([...words[0]].length)));
+      return splitFlap(el, { texts, times, w, h, scene });
+    }
+    case "ghostStack": {
+      const times = hits.filter((_, i) => i % 2 === 0);
+      const lines = cycle(words, Math.max(4, times.length + 2)).map((text, i) => ({ text, at: times[i] ?? ctx.dur + i, hot: [0] }));
+      return ghostStack(el, { lines, visible: 3, w, h, scene });
+    }
+    case "ransomLetters": {
+      const accent = color(ctx, "accent", "");
+      const l = lum(accent);
+      const palette = l >= 0.12 && l <= 0.3 ? [accent, ...RANSOM] : RANSOM;
+      return windows(el, hits, 6, (box, hs, k) => ransomLetters(box, { text: words[k % words.length], at: Math.max(0, hs[0] - 0.02), hits: hs, palette, w, h, seed: `${scene}:${k}`, scene }));
+    }
+    case "neonSign": {
+      // 네온은 어두운 판 위에서 산다 — 밝은 테마에서도 간판 판을 깐다
+      const plate = div(el.ownerDocument, `position:absolute;inset:0;border-radius:${Math.round(Math.min(w, h) * 0.06)}px;background:#0a090d`);
+      el.append(plate);
+      const neon = color(ctx, "accent", "#FF4F7A");
+      return windows(plate, hits, 6, (box, hs, k) => neonSign(box, { text: words[k % words.length], at: hs[0] + 0.02, color: neon, w, h, seed: `${scene}:${k}`, scene }));
+    }
+    case "ledBoard": {
+      const text = cycle(words, 3).join("  ");
+      // 글이 장면 끝에서야 다 지나가는 빠르기 — 일찍 다 지나가면 빈 판이 멈춘 화면이 된다. 판 칸 수 = 폭 ÷ (판 높이/18), 글 폭은 16점 글꼴 0.6em 어림
+      const cols = Math.floor((w * 18) / (h * 0.4));
+      const speed = (cols + text.length * 16 * 0.6) / (ctx.dur + 0.3);
+      return ledBoard(el, { text, mode: "scroll", speed, at: 0, x: 0, y: h * 0.3, w, h: h * 0.4, stageW: w, stageH: h, color: color(ctx, "accent", "#FFB23E"), scene });
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * 장면 경계를 걸치는 덮기 — out 은 장면 끝에서 덮고, in 은 다음 장면 처음에 걷힌다. 다 덮인 채 서 있는 시간은 0.05초 안팎 —
+ * 한 색 화면이 0.1초를 넘으면 멈춤 검사(frame.freeze)에 걸린다. 조리개는 끝까지 닫지 않고 바늘구멍에서 되돌아 연다. 두 장면이 경계의 영상 시각을 같은 씨앗으로 써서
+ * 앞 장면 마지막 프레임과 뒤 장면 첫 프레임이 같은 덮개로 이어진다. el 은 화면 전체, 맨 위 층
+ */
+export function dressWipe(name: string, el: HTMLElement, ctx: SceneCtx, side: "in" | "out"): Paint | null {
+  const { width: w, height: h } = ctx.meta;
+  const B = side === "out" ? ctx.dur : 0;
+  const seed = `${name}@${(ctx.from + B).toFixed(3)}`;
+  const accent = color(ctx, "accent", "#5b3fd9");
+  const ink = color(ctx, "ink", "#111111");
+  switch (name) {
+    case "brushWipe":
+      return brushWipe(el, { w, h, at: B - 0.35, dur: 0.7, strokes: 5, color: accent, seed, scene: ctx.id });
+    case "irisBlades":
+      // 다 열린 육각 구멍이 화면 모서리까지 덮게 — 변까지 거리가 대각선 반을 넘어야 모서리에 날이 안 남는다
+      return irisBlades(el, { w, h, color: ink, seam: "rgba(255,255,255,.3)", radius: (Math.hypot(w, h) / 2 / Math.cos(Math.PI / 6)) * 1.04, stiffness: 260, damping: 32, steps: [{ at: B - 100, open: 1 }, { at: B - 0.32, open: 0 }, { at: B - 0.02, open: 1 }], scene: ctx.id });
+    case "flood": {
+      const zero = { x: w / 2, y: h / 2, w: 0, h: 0, radius: 0 };
+      return flood(el, { w, h, x: w / 2, y: h / 2, color: accent, steps: [{ at: B - 100, shape: zero }, { at: B - 0.28, shape: "cover" }, { at: B - 0.02, shape: zero }], scene: ctx.id });
+    }
+    default:
+      return null;
+  }
+}

package/packages/motion/src/moves/echoStack.ts

@@ -23,7 +23,7 @@ export function echoStack(el: HTMLElement, o: EchoStackOpts): (t: number) => voi
   const H = o.h ?? 1080;
   const n = o.hits.length;
   const back = o.dir === "back";
-  const px = o.size ?? fitSize(o.word, W, H, back ? { share: 0.7, hShare: 0.5 } : { share: 0.62, hShare: 1.12 / Math.max(1, n) });
+  const px = o.size ?? fitSize(o.word, W, H, back ? { share: 0.7, hShare: 0.44 } : { share: 0.62, hShare: 1.12 / Math.max(1, n) });
   // 벌 사이를 촘촘히 — 메아리가 한 덩어리로 읽히게
   const lh = px * 0.74;
   const layer = div(doc, "position:absolute;inset:0;overflow:hidden");
@@ -63,8 +63,8 @@ export function echoStack(el: HTMLElement, o: EchoStackOpts): (t: number) => voi
         c.style.transform = `translate(calc(-50% + ${x.toFixed(1)}px),${(y - lh / 2).toFixed(1)}px)`;
       }
     });
-    // 묶음 전체가 옆으로 흐르고 조금씩 다가가 멈추지 않는다
-    block.style.transform = `translate(${(W * 0.03 * Math.sin(t * 1.7)).toFixed(1)}px,0) scale(${(1 + 0.02 * t).toFixed(4)})`;
+    // 묶음 전체가 옆으로 흔들리며 흘러 다음 박까지 서지 않는다 — 위아래로 퍼지거나 커지면 끝 벌이 화면 밖으로 잘린다
+    block.style.transform = `translate(${(W * 0.07 * Math.sin(t * 1.9)).toFixed(1)}px,0) scale(${(1 + 0.02 * t).toFixed(4)})`;
     mark("echoStack", o.scene, moving);
   };
 }

package/packages/motion/src/moves/fit.ts

@@ -32,3 +32,39 @@ export function div(doc: Document, css: string, text?: string): HTMLDivElement {
 export function mark(name: string, scene: string | undefined, active: boolean): void {
   if (active) emit({ kind: "move", source: name, scene, name: `move:${name}`, value: 1 });
 }
+
+/**
+ * 띠 글 — 낱말 조각들(pieces, 한 바퀴)을 이어 붙여 흐르게 하되, 화면 끝에 걸친 조각은 끝에 닿기 전에 흐려져 사라진다(양 끝 흐림).
+ * 글이 잘린 채 화면 끝에 머물면 검사가 text.offscreen 으로 잡는다 — 그래서 한 줄 대신 낱말마다 따로 둔다(긴 줄 하나면 늘 끝에 걸려 안 보인다).
+ * cycles 는 화면을 덮는 바퀴 수, em 은 조각 폭 어림(px, 처음 보일 때 잰 폭으로 바뀐다).
+ * 반환 함수: offset(띠 안 px, 흐른 거리) · toScreen(띠 안 x → 화면 x) · view(화면에서 보이는 [왼쪽, 오른쪽]) · fade(흐려지는 폭 px)
+ */
+export function strip(host: HTMLElement, pieces: readonly string[], cycles: number, guess: (piece: string) => number): (offset: number, toScreen: (x: number) => number, view: [number, number], fade: number) => void {
+  const doc = host.ownerDocument;
+  const spans = Array.from({ length: cycles * pieces.length }, (_, k) => {
+    const s = doc.createElement("span");
+    s.textContent = pieces[k % pieces.length];
+    s.style.cssText = "position:absolute;left:0;top:50%;transform:translateY(-50%);white-space:pre";
+    host.append(s);
+    return s;
+  });
+  let widths: number[] | null = null;
+  return (offset, toScreen, view, fade) => {
+    // 조각 폭은 글꼴이 걸린 뒤 처음 보일 때 잰다(build 때는 장면이 숨어 있다)
+    if (!widths && spans[0].offsetWidth) widths = pieces.map((_, i) => spans[i].offsetWidth);
+    const ws = widths ?? pieces.map(guess);
+    const lap = ws.reduce((a, b) => a + b, 0) || 1;
+    const total = lap * cycles;
+    let acc = 0;
+    spans.forEach((s, k) => {
+      const w = ws[k % pieces.length];
+      const x = ((((offset + acc) % total) + total) % total) - lap;
+      acc += w;
+      const a = toScreen(x);
+      const b = toScreen(x + w);
+      const edge = Math.min(Math.min(a, b) - view[0], view[1] - Math.max(a, b));
+      s.style.left = `${x.toFixed(1)}px`;
+      s.style.opacity = Math.max(0, Math.min(1, edge / fade)).toFixed(3);
+    });
+  };
+}

package/packages/motion/src/moves/ghostStack.ts

@@ -13,7 +13,7 @@ export interface GhostStackOpts {
   lines: GhostLine[];
   /** 한 화면에 보이는 줄 수 */
   visible?: number;
-  /** 한 줄이 왼쪽에서 오른쪽으로 다 채워지는 데 드는 초 */
+  /** 한 줄을 채우는 가장 짧은 초 — 다음 줄 박이 있으면 그 박까지 같은 빠르기로 채운다 */
   fill?: number;
   w?: number;
   h?: number;
@@ -39,7 +39,8 @@ export function ghostStack(el: HTMLElement, o: GhostStackOpts): (t: number) => v
   el.append(layer);
   const rows = o.lines.map((l, i) => {
     const row = div(doc, `position:absolute;left:0;top:${i * lh}px;height:${lh}px`);
-    const ghost = div(doc, "position:absolute;left:0;top:0;color:transparent;-webkit-text-stroke:.022em var(--kf-ink);opacity:.5");
+    // 유령 줄도 읽혀야 한다 — 가는 반투명 외곽선은 밝은 바탕에서 대비 1.2:1 로 검사(text.contrast)에 걸렸다
+    const ghost = div(doc, "position:absolute;left:0;top:0;color:transparent;-webkit-text-stroke:.03em var(--kf-ink);opacity:.85");
     const full = div(doc, "position:absolute;left:0;top:0;color:var(--kf-ink)");
     l.text.split(" ").forEach((w, j, all) => {
       const span = doc.createElement("span");
@@ -53,6 +54,8 @@ export function ghostStack(el: HTMLElement, o: GhostStackOpts): (t: number) => v
     return { row, ghost, full };
   });
   const times = o.lines.map((l) => l.at);
+  // 마지막 줄은 다음 박이 없다 — 앞 줄들의 박 간격만큼 채운다
+  const gap = times.length > 1 ? (times[times.length - 1] - times[0]) / (times.length - 1) : fillDur;
 
   return (t: number) => {
     t = safeTime(t);
@@ -65,14 +68,20 @@ export function ghostStack(el: HTMLElement, o: GhostStackOpts): (t: number) => v
     const scroll = prev + (cur - prev) * p;
     // 박 사이에도 묶음이 천천히 떠올라 멈추지 않는다
     const drift = 14 * t;
-    stack.style.transform = `translateY(${(H / 2 - (vis * lh) / 2 - scroll * lh - drift).toFixed(1)}px)`;
+    const top = H / 2 - (vis * lh) / 2 - scroll * lh - drift;
+    stack.style.transform = `translateY(${top.toFixed(1)}px)`;
     rows.forEach((r, i) => {
       // 유령은 앞 줄이 채워질 때 나타난다
       const ghostAt = i === 0 ? times[0] - 0.3 : times[i - 1];
-      r.ghost.style.opacity = (0.5 * clamp((t - ghostAt) / 0.15)).toFixed(3);
-      const f = ease.outCubic(clamp((t - times[i]) / fillDur));
+      r.ghost.style.opacity = (0.85 * clamp((t - ghostAt) / 0.15)).toFixed(3);
+      // 다음 줄 박까지 같은 빠르기로 채운다 — 읽어 나가는 빠르기. 0.2초 만에 다 채우면 다음 박까지 화면이 선다
+      const span = Math.max(fillDur, times[i + 1] !== undefined ? times[i + 1] - times[i] : gap);
+      const f = clamp((t - times[i]) / span);
       r.full.style.clipPath = `inset(0 ${((1 - f) * 100).toFixed(2)}% 0 0)`;
       r.row.style.display = i < cur - 1 || i > k + 1 ? "none" : "block";
+      // 위로 밀려 나가는 줄은 화면 끝에 닿기 전에 흐려진다 — 잘린 글이 남지 않게(검사 text.offscreen)
+      const y = top + i * lh;
+      r.row.style.opacity = Math.max(0, Math.min(1, y / (lh * 0.3), (H - y - lh) / (lh * 0.3))).toFixed(3);
     });
     mark("ghostStack", o.scene, k >= 0 && t - times[k] < fillDur);
   };

package/packages/motion/src/moves/imageSwarm.ts

@@ -64,8 +64,9 @@ export function imageSwarm(el: HTMLElement, o: ImageSwarmOpts): (t: number) => v
     return {
       card,
       home,
-      cloud: { x: W * (-0.1 + 1.2 * r(1)) - cw / 2, y: H * (-0.1 + 1.2 * r(2)) - ch / 2, rot: (r(3) - 0.5) * 50, s: 0.55 + 0.75 * depth, blur: (1 - depth) * 4 },
-      drift: { x: (r(4) - 0.5) * 120, y: (r(5) - 0.5) * 80, phase: r(6) * 6.28 },
+      // 구름 자리도 화면 안 — 화면 끝에 걸친 카드의 글이 잘린 채 떠 있지 않게(검사 text.offscreen)
+      cloud: { x: 60 + (W - cw * 1.3 - 120) * r(1), y: 40 + (H - ch * 1.3 - 80) * r(2), rot: (r(3) - 0.5) * 50, s: 0.55 + 0.75 * depth, blur: (1 - depth) * 4 },
+      drift: { x: (r(4) - 0.5) * 100, y: (r(5) - 0.5) * 70, phase: r(6) * 6.28 },
       order: r(7),
     };
   });
@@ -78,8 +79,9 @@ export function imageSwarm(el: HTMLElement, o: ImageSwarmOpts): (t: number) => v
       const fx = c.cloud.x + c.drift.x * Math.sin(t * 0.9 + c.drift.phase);
       const fy = c.cloud.y + c.drift.y * Math.cos(t * 0.7 + c.drift.phase);
       const start = o.gatherAt + c.order * stagger * n;
-      let g = spring(t - start, { stiffness: 140, damping: 17 });
-      if (o.scatterAt !== undefined) g -= spring(t - o.scatterAt - c.order * stagger * n * 0.5, { stiffness: 120, damping: 15 });
+      // 거의 출렁이지 않게 — 여러 색 카드가 출렁이며 칸을 오가면 섬광 검사(frame.flash)에 걸린다
+      let g = spring(t - start, { stiffness: 140, damping: 22 });
+      if (o.scatterAt !== undefined) g -= spring(t - o.scatterAt - c.order * stagger * n * 0.5, { stiffness: 120, damping: 21 });
       const x = fx + (c.home.x - fx) * g;
       const y = fy + (c.home.y - fy) * g;
       let rot = c.cloud.rot * (1 - g);
@@ -100,6 +102,8 @@ export function imageSwarm(el: HTMLElement, o: ImageSwarmOpts): (t: number) => v
         } else opacity = 1 - clamp(k * 1.4);
       }
       c.card.style.opacity = opacity.toFixed(3);
+      // 격자에 앉았는가(0·1) — 카드 안 글은 앉았을 때만 보이게 쓸 수 있다(흐리게 떠도는 카드 위 글은 대비 검사에 걸린다)
+      c.card.style.setProperty("--kf-seated", g > 0.92 ? "1" : "0");
       c.card.style.filter = g < 0.98 ? `blur(${(c.cloud.blur * (1 - g)).toFixed(2)}px)` : "";
       c.card.style.transform = `translate(${tx.toFixed(1)}px, ${ty.toFixed(1)}px) rotate(${rot.toFixed(2)}deg) scale(${s.toFixed(4)})`;
       if (Math.abs(1 - g) > 0.01 && g > 0.01) moving = true;

package/packages/motion/src/moves/index.ts

@@ -1,6 +1,27 @@
 // 영상에서 모은 연출 수 — docs/references/opus-videos.md. 수마다 3–5초 예시: examples/moves/<이름>/
 export * from "./fit.ts";
 export * from "./slamWords.ts";
+export * from "./path.ts";
+export * from "./sparkTrail.ts";
+export * from "./pathText.ts";
+export * from "./ghostStack.ts";
+export * from "./echoStack.ts";
+export * from "./wordWall.ts";
+export * from "./tokenPicker.ts";
+export * from "./splitFlap.ts";
+export * from "./karaokeLine.ts";
+export * from "./stepWords.ts";
+export * from "./ransomLetters.ts";
+export * from "./tickerRows.ts";
+export * from "./strikeOut.ts";
+export * from "./worldRoll.ts";
+export * from "./markerWrite.ts";
+export * from "./neonSign.ts";
+export * from "./ledBoard.ts";
+export * from "./brushWipe.ts";
+export * from "./paperTear.ts";
+export * from "./irisBlades.ts";
+export * from "./flood.ts";
 export * from "./sunburst.ts";
 export * from "./speedLines.ts";
 export * from "./gridFloor.ts";
@@ -10,10 +31,8 @@ export * from "./shapeMorph.ts";
 export * from "./panelPop.ts";
 export * from "./imageSwarm.ts";
 export * from "./liquidTab.ts";
-export * from "./brushWipe.ts";
-export * from "./paperTear.ts";
-export * from "./irisBlades.ts";
-export * from "./flood.ts";
 export * from "./cloneArray.ts";
 export * from "./curtains.ts";
 export * from "./morphBox.ts";
+export * from "./menu.ts";
+export * from "./dress.ts";