kasaframe 0.1.5 → 0.1.6

package/packages/patterns/src/quote/karaoke.ts

@@ -1,6 +1,6 @@
 import { applyStyle, clamp, spring } from "@kasaframe/core";
 import { fitSize, textEm } from "@kasaframe/motion/moves";
-import { ACCENT_TEXT, area, beatStops, glider, moving, node, slotsOf } from "../kit.ts";
+import { ACCENT_TEXT, area, glider, inverseOver, markOf, moving, node, slotsOf } from "../kit.ts";
 import type { Pattern, SpokenWord } from "../types.ts";
 
 export interface QuoteContent {
@@ -80,14 +80,23 @@ const pattern: Pattern<QuoteContent> = {
     const mark = node(col, `font-family:var(--kf-font-display);font-size:${Math.round(px * 1.4)}px;line-height:.6;height:${Math.round(px * 0.6)}px;font-weight:900;color:${ACCENT_TEXT}`, "“");
     const body = node(col, `font-family:var(--kf-font-display);font-size:${px}px;font-weight:${ctx.style.type?.weightDisplay ?? 800};line-height:1.3;color:var(--kf-ink);word-break:keep-all`);
     kit.stage?.hero(body);
+    const shape = markOf(kit, ctx);
     const spans = words.map((wd, i) => {
       const sp = body.ownerDocument.createElement("span");
       sp.style.cssText = "position:relative;white-space:nowrap";
       sp.textContent = wd;
-      const hi = node(sp, "position:absolute;left:-0.08em;right:-0.08em;top:0.02em;bottom:0.02em;padding:0 0.08em;background:var(--kf-accent);color:var(--kf-on-accent);white-space:nowrap;visibility:hidden", wd);
       body.append(sp);
       if (i < words.length - 1) body.append(body.ownerDocument.createTextNode(" "));
-      return { sp, hi };
+      // 읽는 낱말 반전 칸 — 테마가 짚는 칸 모양을 정했으면 그 칸(반전 짚음)
+      if (shape) return { sp, paint: inverseOver(sp, wd, shape) };
+      const hi = node(sp, "position:absolute;left:-0.08em;right:-0.08em;top:0.02em;bottom:0.02em;padding:0 0.08em;background:var(--kf-accent);color:var(--kf-on-accent);white-space:nowrap;visibility:hidden", wd);
+      return {
+        sp,
+        paint: (k: number) => {
+          hi.style.visibility = k > 0 ? "visible" : "hidden";
+          hi.style.clipPath = `inset(0 ${((1 - k) * 100).toFixed(2)}% 0 0)`;
+        },
+      };
     });
     const whoText = [c.who, c.role].filter(Boolean).join(" · ");
     const who = whoText ? node(col, `align-self:flex-end;font-family:var(--kf-font-sans);font-size:${whoPx}px;font-weight:600;color:var(--kf-ink-soft, var(--kf-ink));white-space:nowrap;line-height:1.3;height:1.3em`) : null;
@@ -101,24 +110,20 @@ const pattern: Pattern<QuoteContent> = {
     const times = kit.say.length ? timing(words, kit.say, readFrom, ctx.dur - 0.05) : even(words, readFrom, readTo);
     const readEnd = times[times.length - 1][1];
     const whoAt = Math.min(Math.max(readFrom, ctx.dur - whoDur - 0.6), readEnd);
-    // 다 읽은 뒤엔 짚개가 문장 ↔ 누가 말했는지를 박마다 번갈아 짚는다(누가 없으면 낱말을 차례로)
-    const point = glider(host, who ? [body, who] : spans.map((x) => x.sp), { hub: !!who, pad: 0.06 });
-    const stops = beatStops(kit.hits, readEnd + 0.05, ctx.dur);
+    // 다 읽으면 짚개가 문장부터 짚는다(머무는 테마는 목소리가 누가를 말할 때만 그리로). 누가가 없으면 훑는 테마만 낱말을 차례로 — 머무는 테마엔 주인공이 없다
+    const point = glider(host, who ? [{ el: body, text: c.text }, { el: who, text: whoText }] : spans.map((x) => ({ el: x.sp })), { kit, ctx, from: readEnd + 0.05, hub: !!who, pad: 0.06 });
     const writeWho = who ? slots.write(who, { ctx, text: whoText, at: whoAt, dur: whoDur, seed: `${kit.seed}:who` }) : null;
 
     return (t: number) => {
       moving("quote.karaoke", ctx);
       applyStyle(mark, { scale: spring(t, { from: 0.4, to: 1, stiffness: 260, damping: 14 }) });
+      // 짚는 동안은 낱말 반전 칸을 걷는다 — 두 강조가 겹치면 무엇을 짚는지 흐려진다
       spans.forEach((s, i) => {
         const [a, b] = times[i];
-        const k = clamp((t - a) / Math.max(0.05, b - a));
-        s.hi.style.visibility = k > 0 ? "visible" : "hidden";
-        s.hi.style.clipPath = `inset(0 ${((1 - k) * 100).toFixed(2)}% 0 0)`;
+        s.paint(t >= readEnd + 0.05 ? 0 : clamp((t - a) / Math.max(0.05, b - a)));
       });
       writeWho?.(t);
-      // 짚는 동안은 낱말 반전 칸을 걷는다 — 두 강조가 겹치면 무엇을 짚는지 흐려진다
-      if (t >= readEnd + 0.05) spans.forEach((x) => (x.hi.style.visibility = "hidden"));
-      point(t, stops);
+      point(t);
     };
   },
 };

package/packages/patterns/src/sfx.ts

@@ -0,0 +1,80 @@
+import { cue } from "@kasaframe/core";
+import type { ThemeSlots } from "./types.ts";
+
+// 패턴이 부르는 테마 슬롯에 소리 자리를 단다 — 테마 슬롯도 패턴 기본 슬롯도 같은 자리에서 소리가 나고, 장면·테마 코드는 그대로다
+
+/** 글 찍기 소리 간격(초) — 글자마다 내면 1초에 열 번이 넘어 밀도 상한에 다 잘린다 */
+const TYPE_EVERY = 0.09;
+const TYPE_MAX = 10;
+
+export function withSfx<S extends ThemeSlots>(s: S): S {
+  const out: ThemeSlots = { ...s };
+  if (s.panel)
+    out.panel = (el, o) => {
+      const paint = s.panel!(el, o);
+      return (t) => {
+        cue("appear", t - o.at, { source: `panel:${o.seed}@${o.at.toFixed(3)}`, scene: o.ctx.id, weight: 0.8, minor: true });
+        paint(t);
+      };
+    };
+  if (s.land)
+    out.land = (el, o) => {
+      const style = s.land!(el, o);
+      return (t) => {
+        cue("land", t - o.at, { source: `land:${o.seed}@${o.at.toFixed(3)}`, scene: o.ctx.id });
+        return style(t);
+      };
+    };
+  if (s.write)
+    out.write = (el, o) => {
+      const paint = s.write!(el, o);
+      const n = Math.min(TYPE_MAX, Math.max(1, Math.floor(o.dur / TYPE_EVERY)));
+      return (t) => {
+        const k = Math.floor((t - o.at) / TYPE_EVERY);
+        for (const j of [k - 1, k]) if (j >= 0 && j < n) cue("type", t - o.at - j * TYPE_EVERY, { source: `write:${o.seed}:${j}@${o.at.toFixed(3)}`, scene: o.ctx.id, minor: true });
+        paint(t);
+      };
+    };
+  if (s.drop)
+    out.drop = (el, o) => {
+      const burst = s.drop!(el, o);
+      const at = o.ctx.beats.drop(o.drop);
+      return (t) => {
+        cue("drop", t - at, { source: `slot-drop:${o.drop}`, scene: o.ctx.id });
+        return burst(t);
+      };
+    };
+  return out as S;
+}
+
+/** 쾅 앉는 순간 — kit slam 이 부른다 */
+export const slamCue = (t: number, at: number): void => cue("land", t - at, { source: `slam@${at.toFixed(3)}` });
+
+/** 짚개가 요점(핵심 값)으로 옮겨 가는 순간 딸깍 — 요점만 짚으니 잔소리가 아니다 */
+export const keyCue = (t: number, at: number): void => cue("select", t - at, { source: `glider@${at.toFixed(3)}`, weight: 0.8 });
+
+/** 박마다 훑는 짚개가 주인공(핵심 값)에 닿는 순간 딸깍 — 곁가지에 닿는 것은 잔소리. 첫 정지점은 짚개가 나타나는 자리라 빼고 */
+export function stopCues(t: number, stops: readonly number[], key: (k: number) => boolean = () => true): void {
+  for (let j = 1; j < stops.length - 1; j++)
+    if (t >= stops[j] && t < stops[j] + 0.2) cue("select", t - stops[j], { source: `glider@${stops[j].toFixed(3)}`, weight: 0.8, minor: !key(j) });
+}
+
+/**
+ * 숫자 굴림이 째깍거리는 시각 — 진행도 p(x)(감속)가 k/n 을 지나는 x 에. 빨리 구르는 앞은 촘촘, 앉기 전은 띄엄띄엄(슬롯 머신처럼).
+ * p 는 단조라 이분법으로 거꾸로 푼다
+ */
+export function rollCues(t: number, o: { at: number; dur: number; p: (x: number) => number; n?: number }): void {
+  if (t < o.at || t > o.at + o.dur + 0.2) return;
+  const n = o.n ?? Math.max(3, Math.min(10, Math.round(o.dur / 0.12)));
+  for (let k = 1; k <= n; k++) {
+    let lo = 0;
+    let hi = 1;
+    for (let i = 0; i < 24; i++) {
+      const mid = (lo + hi) / 2;
+      if (o.p(mid) < k / n) lo = mid;
+      else hi = mid;
+    }
+    const at = o.at + hi * o.dur;
+    cue(k === n ? "land" : "tick", t - at, { source: `roll:${k}@${o.at.toFixed(3)}`, weight: k === n ? 0.8 : 0.7, minor: k !== n });
+  }
+}

package/packages/patterns/src/term-reveal/chips.ts

@@ -1,12 +1,13 @@
 import { applyStyle, clamp, spring } from "@kasaframe/core";
 import { fitSize, textEm } from "@kasaframe/motion/moves";
-import { ACCENT_TEXT, area, inverseOver, moving, node, slotsOf } from "../kit.ts";
+import { ACCENT_TEXT, area, dwells, followSpoken, glider, inverseOver, markOf, moving, node, sayTimes, slotsOf } from "../kit.ts";
 import type { TermContent } from "./expand.ts";
 import type { Pattern } from "../types.ts";
 
 /**
  * 용어 해부 — 약자가 큰 판 위에 서고, 풀이 낱말이 박마다 하나씩 판 아래 칩으로 톡 붙는다(첫 글자는 강조색 — 약자 글자와 같은 글자).
  * 다 붙으면 한국어 이름이 판 아래에 찍히고, 판이 아래부터 강조색으로 차올라 장면 끝까지 그 용어를 짚는다.
+ * 테마가 짚는 칸 모양을 정했으면 판을 칠하지 않는다 — 짚개가 약자부터 짚는다(머무는 테마는 목소리가 풀이·한국어 이름을 말할 때만 그리로).
  */
 const pattern: Pattern<TermContent> = {
   id: "term-reveal.chips",
@@ -42,11 +43,15 @@ const pattern: Pattern<TermContent> = {
     const col = node(host, `display:flex;flex-direction:column;align-items:center;gap:${Math.round(h * 0.035)}px`);
     const board = node(col, `position:relative;width:${boardW}px;height:${boardH}px`);
     const panel = slots.panel(board, { ctx, at: 0, seed: `${kit.seed}:board` });
-    const fill = node(board, "position:absolute;inset:0;background:var(--kf-accent);border-radius:var(--kf-radius-md)");
+    const mark = markOf(kit, ctx);
+    const fill = mark ? null : node(board, "position:absolute;inset:0;background:var(--kf-accent);border-radius:var(--kf-radius-md)");
     const face = (lit: boolean) =>
       node(board, `position:absolute;inset:0;display:flex;align-items:center;justify-content:center;font-family:var(--kf-font-display);font-size:${termPx}px;font-weight:${ctx.style.type?.weightDisplay ?? 800};letter-spacing:0.04em;color:${lit ? "var(--kf-on-accent)" : "var(--kf-ink)"}`, c.term);
-    face(false);
-    const lit = face(true);
+    const plain = face(false);
+    const lit = mark ? null : face(true);
+    // 짚개가 잴 약자 글 상자 — 판 전체가 아니라 글자에 칸이 앉게
+    const termText = mark ? node(plain, "position:relative", c.term) : null;
+    if (termText) plain.firstChild!.remove();
     kit.stage?.hero(board);
     const row = words.length ? node(col, `display:flex;flex-direction:${vertical ? "column" : "row"};align-items:center;gap:${Math.round(chipPx * 0.35)}px;min-height:${Math.round(chipPx * 1.5)}px`) : null;
     const chips = words.map((wd) => {
@@ -57,17 +62,25 @@ const pattern: Pattern<TermContent> = {
     });
     const koBox = c.ko ? node(col, `position:relative;font-family:var(--kf-font-sans);font-size:${koPx}px;font-weight:700;white-space:nowrap;line-height:1.3;height:1.3em`) : null;
     const ko = koBox ? node(koBox, "color:var(--kf-ink)") : null;
-    const koMark = koBox ? inverseOver(koBox, c.ko!) : null;
+    const koMark = koBox && !mark ? inverseOver(koBox, c.ko!) : null;
+    // 짚개가 이름 자리를 찍히기 전부터 짚는다 — 빈 상자는 폭이 0 이라 칸이 점으로 줄어든다
+    if (koBox && mark) koBox.style.cssText += `;min-width:${Math.round(textEm(c.ko!) * koPx)}px;text-align:center`;
 
-    const hits = kit.hits.length ? kit.hits : [0];
     const boardAt = kit.first ? -0.3 : 0;
-    const chipAt = words.map((_, i) => hits.find((b) => b >= 0.12 + i * 0.3) ?? 0.2 + i * 0.3);
-    const koAt = (chipAt[chipAt.length - 1] ?? 0.2) + 0.3;
+    // 머무는 짚개 테마는 풀이 칩·한국어 이름을 목소리가 그것을 말할 때 붙인다(못 들으면 판이 열린 뒤부터 장면 끝 무렵까지 박에 붙여 고르게) —
+    // 처음에 몰아 띄우면 남은 시간이 빈다. 붙을 때마다 카메라가 그쪽으로 다가간다. 훑는 테마는 0.3초 간격 박에 붙인다(판 차오름이 끝까지 간다)
+    const hits = kit.hits.length ? kit.hits : [0];
+    const times = dwells(kit, ctx) ? sayTimes(kit, [...words, c.ko], 0.12, Math.max(0.6, ctx.dur - 0.9)) : null;
+    const chipAt = words.map((_, i) => times?.[i] ?? hits.find((b) => b >= 0.12 + i * 0.3) ?? 0.2 + i * 0.3);
+    const koAt = c.ko && times ? times[words.length] : (chipAt[chipAt.length - 1] ?? 0.2) + 0.3;
+    followSpoken(kit, ctx, [...chips.map((el, i) => ({ at: chipAt[i], el })), ...(koBox ? [{ at: koAt, el: koBox }] : [])]);
     const koDur = c.ko ? clamp([...c.ko].length * 0.05, 0.25, 0.6) : 0;
     // 판이 열리는 것만으로는 밝은 바탕에서 화면이 바뀐 것으로 안 읽힌다 — 차오름을 곧바로 시작한다
     const fillFrom = 0;
     const writeKo = ko ? slots.write(ko, { ctx, text: c.ko!, at: koAt, dur: koDur, seed: `${kit.seed}:ko` }) : null;
     const lands = chips.map((ch, i) => slots.land(ch, { ctx, at: chipAt[i], seed: `${kit.seed}:c${i}` }));
+    // 판이 열리면 짚개가 약자부터 짚고, 머무는 테마는 목소리가 풀이·한국어 이름을 말할 때만 그리로 옮긴다 — 칠한 판이 차오르던 몫
+    const point = termText ? glider(host, [{ el: termText, text: c.term }, ...(row ? [{ el: row, text: words.join(" ") }] : []), ...(koBox ? [{ el: koBox, text: c.ko }] : [])], { kit, ctx, from: boardAt + 0.2 }) : null;
 
     return (t: number) => {
       moving("term-reveal.chips", ctx);
@@ -81,8 +94,9 @@ const pattern: Pattern<TermContent> = {
       // 판은 칩이 붙기 시작할 때부터 장면 끝까지 차오른다 — 용어를 짚는 몫
       const k = clamp((t - fillFrom) / Math.max(0.3, ctx.dur - fillFrom - 0.05));
       const clip = `inset(${((1 - k) * 100).toFixed(2)}% 0 0 0)`;
-      fill.style.clipPath = clip;
-      lit.style.clipPath = clip;
+      if (fill) fill.style.clipPath = clip;
+      if (lit) lit.style.clipPath = clip;
+      point?.(t);
       writeKo?.(t);
       koMark?.((t - koAt - koDur) / Math.max(0.2, ctx.dur - koAt - koDur - 0.05));
     };

package/packages/patterns/src/term-reveal/expand.ts

@@ -1,6 +1,6 @@
 import { applyStyle, clamp, ease, progress } from "@kasaframe/core";
 import { fitSize, textEm } from "@kasaframe/motion/moves";
-import { ACCENT_TEXT, area, beatStops, fitOnce, glider, moving, node, slotsOf } from "../kit.ts";
+import { ACCENT_TEXT, area, dwells, fitOnce, followSpoken, glider, moving, node, sayTimes, slotsOf } from "../kit.ts";
 import type { Pattern } from "../types.ts";
 
 export interface TermContent {
@@ -21,12 +21,12 @@ function spell(term: string, full: string | undefined): string[] | null {
 
 /**
  * 용어 공개 — 약자가 크게 서고, 약자 글자마다 풀이 낱말이 그 글자에서 아래로 펴져 나온다(글자 → 낱말이 같은 첫 글자로 이어진다).
- * 풀이가 약자와 안 맞으면 풀이 한 줄이 펴진다. 그다음 한국어 이름이 찍히고, 짚개가 약자와 풀이 낱말을 번갈아 박마다 짚는다.
+ * 풀이가 약자와 안 맞으면 풀이 한 줄이 펴진다. 그다음 한국어 이름이 찍히고, 짚개가 약자부터 짚는다(머무는 테마는 목소리가 풀이 낱말·이름을 말할 때만 그리로).
  */
 const pattern: Pattern<TermContent> = {
   id: "term-reveal.expand",
   type: "term-reveal",
-  does: "약자가 서고 글자마다 풀이 낱말이 펴진다, 한국어 이름이 찍히고 짚개가 약자와 풀이를 번갈아 짚는다",
+  does: "약자가 서고 글자마다 풀이 낱말이 펴진다, 한국어 이름이 찍히고 짚개가 약자부터 짚는다",
   energy: ["mid"],
   family: "mask",
   camera: ["none"],
@@ -83,17 +83,21 @@ const pattern: Pattern<TermContent> = {
     // 펴기는 약자가 서자마자 낱말마다 이어서 — 사이에 빈 틈이 있으면 화면이 선 것으로 읽힌다
     const unfoldAt = termAt + 0.06 * Math.max(0, chars.length - 1) + 0.2;
     const each = parts.length > 1 ? 0.3 : 0;
-    const unfoldEnd = unfoldAt + each * Math.max(0, parts.length - 1) + 0.35;
-    const koAt = parts.length ? unfoldEnd : termAt + 0.2;
     const koDur = c.ko ? clamp([...c.ko].length * 0.05, 0.25, 0.6) : 0;
-    const meanAt = koAt + koDur;
+    // 머무는 짚개 테마는 풀이 낱말·한국어 이름·뜻을 목소리가 그것을 말할 때 펴고 찍는다(못 들으면 약자가 선 뒤부터 장면 끝 무렵까지 박에 붙여 고르게).
+    // 펴지고 찍힐 때마다 카메라가 그쪽으로 다가간다. 훑는 테마는 약자가 서자마자 낱말마다 0.3초 간격으로 이어 편다
+    const said = dwells(kit, ctx) ? sayTimes(kit, [...parts.map((_, i) => (words ?? [fullText])[i]), c.ko, c.meaning], unfoldAt, Math.max(unfoldAt + 0.3, ctx.dur - 0.9)) : null;
+    const partAt = parts.map((_, i) => said?.[i] ?? unfoldAt + i * each);
+    const unfoldEnd = unfoldAt + each * Math.max(0, parts.length - 1) + 0.35;
+    const koAt = said && (parts.length || kit.say.length || kit.lines.length) ? said[parts.length] : parts.length ? unfoldEnd : termAt + 0.2;
+    const meanAt = Math.max(koAt + koDur, said?.[parts.length + 1] ?? 0);
+    followSpoken(kit, ctx, [...parts.map((p, i) => ({ at: partAt[i], el: p.box })), ...(ko ? [{ at: koAt, el: ko }] : []), ...(meaning ? [{ at: meanAt, el: meaning }] : [])]);
     const meanDur = meaning ? clamp([...c.meaning!].length * 0.035, 0.4, 1.2) : 0;
     // 짚음은 첫 낱말이 다 펴지자마자 — 펴기와 겹쳐 장면 끝까지 이어진다
     // 풀이 낱말이 없으면(약자가 아닌 용어) 펼 것이 없다 — 용어가 서자마자 짚기 시작한다
-    const markFrom = parts.length ? unfoldAt + Math.max(each, 0.3) : termAt + 0.06 * Math.max(0, chars.length - 1) + 0.12;
-    // 짚개 — 약자와 풀이 낱말·한국어 이름을 번갈아 짚는다(약자 → 낱말 → 약자 → 다음 낱말 …). 빠르기는 박이 정한다
-    const point = glider(host, [termEl, ...parts.map((p) => p.box), ...(ko ? [ko] : [])], { hub: true });
-    const stops = beatStops(kit.hits, markFrom, ctx.dur);
+    const markFrom = parts.length ? partAt[0] + Math.max(each, 0.3) : termAt + 0.06 * Math.max(0, chars.length - 1) + 0.12;
+    // 짚개 — 약자부터 짚고, 머무는 테마는 목소리가 풀이 낱말·한국어 이름(풀이·이름이 없으면 뜻)을 말할 때만 그리로 옮긴다
+    const point = glider(host, [{ el: termEl, text: c.term }, ...parts.map((p, i) => ({ el: p.box, text: (words ?? [fullText])[i] })), ...(ko ? [{ el: ko, text: c.ko }] : []), ...(meaning && !parts.length && !ko ? [{ el: meaning, text: c.meaning }] : [])], { kit, ctx, from: markFrom });
 
     const writeKo = ko ? slots.write(ko, { ctx, text: c.ko!, at: koAt, dur: koDur, seed: `${kit.seed}:ko` }) : null;
     const writeMeaning = meaning ? slots.write(meaning, { ctx, text: c.meaning!, at: meanAt, dur: meanDur, seed: `${kit.seed}:m` }) : null;
@@ -106,18 +110,18 @@ const pattern: Pattern<TermContent> = {
         const p = ease.outExpo(progress(t, termAt + i * 0.06, 0.3));
         applyStyle(ch, { y: (1 - p) * termPx * 0.4, opacity: p });
         // 약자 글자는 제 낱말이 펴질 때 강조색으로 — 글자와 낱말이 이어진다
-        const k = words ? clamp((t - (unfoldAt + i * each)) / 0.2) : 0;
+        const k = words ? clamp((t - ((partAt[i] ?? unfoldAt))) / 0.2) : 0;
         ch.style.color = k > 0.5 ? ACCENT_TEXT : "var(--kf-ink)";
       });
       applyStyle(termEl, landed(t));
       parts.forEach((pt, i) => {
         // 고른 빠르기로 편다 — 감속 끝자락이 길면 그 사이가 멈춘 화면이 된다
-        const p = progress(t, unfoldAt + i * each, 0.3);
+        const p = progress(t, (partAt[i] ?? unfoldAt), 0.3);
         pt.box.style.width = `${(p * pt.em * fullPx * 1.02).toFixed(1)}px`;
         pt.box.style.visibility = p > 0 ? "visible" : "hidden";
       });
       // 풀이를 낱말 차례로 반전해 짚는다 — 펴기가 끝난 뒤 장면 끝까지
-      point(t, stops);
+      point(t);
       writeKo?.(t);
       writeMeaning?.(t);
     };

package/packages/patterns/src/title/mask.ts

@@ -1,7 +1,7 @@
 import { applyStyle, clamp } from "@kasaframe/core";
 import { sweep } from "@kasaframe/motion";
 import { fitSize } from "@kasaframe/motion/moves";
-import { ACCENT_TEXT, area, beatStops, cameraOk, glider, node, riseName, slotsOf, moving } from "../kit.ts";
+import { ACCENT_TEXT, area, beatStops, cameraOk, dwells, glider, moving, node, reread, riseName, slotsOf } from "../kit.ts";
 import type { Pattern } from "../types.ts";
 
 export interface TitleContent {
@@ -12,12 +12,12 @@ export interface TitleContent {
 
 /**
  * 이름이 글자마다 아래에서 가림막을 뚫고 올라와 서고(드러냄), 카메라가 그 이름으로 한 번 다가간다 — 다가감의 이유가 드러냄이다.
- * 다가가는 동안 밑줄·부제가 서고, 짚개가 이름과 작은 글을 박마다 번갈아 짚는다.
+ * 다가가는 동안 밑줄·부제가 서고, 작은 글이 있으면 짚개가 이름부터 짚는다(머무는 테마는 목소리가 작은 글을 말할 때만 그리로).
  */
 const pattern: Pattern<TitleContent> = {
   id: "title.mask",
   type: "title",
-  does: "이름이 글자마다 가림막을 뚫고 서고, 다가가는 동안 짚개가 이름과 작은 글을 번갈아 짚는다",
+  does: "이름이 글자마다 가림막을 뚫고 서고, 다가가는 동안 짚개가 이름부터 짚는다",
   energy: ["mid"],
   family: "mask",
   camera: ["pushIn"],
@@ -61,17 +61,18 @@ const pattern: Pattern<TitleContent> = {
     const subAt = sweepAt + 0.3;
     const subDur = Math.max(0.3, ctx.dur - subAt - 0.08);
     if (cameraOk(ctx)) kit.stage?.camera.pushIn(settle, { to: name, scale: 1.07, dur: Math.max(0.6, ctx.dur - settle) });
-    // 이름이 선 뒤엔 짚개가 이름 ↔ 위 작은 글·부제를 박마다 번갈아 짚는다(카메라를 끈 영상에서도 쉬지 않는 몫, 장면이 길어도 박이 빠르기를 정한다)
-    const point = glider(host, [name, ...(kicker ? [kicker] : []), ...(sub ? [sub] : [])], { hub: true });
-    const stops = beatStops(kit.hits, Math.min(settle, nameAt + 0.35), ctx.dur);
+    // 이름이 서면 짚개가 이름과 위 작은 글·부제를 짚는다(짚기 방식은 테마 짚음). 작은 글이 없고 훑는 테마면 이름 글자를 박마다 다시 짚는다
+    const markFrom = Math.min(settle, nameAt + 0.35);
+    const point = glider(host, [{ el: name, text: c.title }, ...(kicker ? [{ el: kicker, text: c.kicker }] : []), ...(sub ? [{ el: sub, text: c.sub }] : [])], { kit, ctx, from: markFrom });
+    const again = !kicker && !sub && !dwells(kit, ctx) ? beatStops(kit.hits, markFrom, ctx.dur) : null;
     const writeKicker = kicker ? slots.write(kicker, { ctx, text: c.kicker!, at: 0, dur: Math.min(0.35, nameEnd * 0.6), seed: `${kit.seed}:kicker` }) : null;
     const writeSub = sub ? slots.write(sub, { ctx, text: c.sub!, at: subAt, dur: subDur, seed: `${kit.seed}:sub` }) : null;
     const landed = slots.land(name, { ctx, at: nameEnd, seed: `${kit.seed}:land` });
 
     return (t: number) => {
       moving("title.mask", ctx);
-      paintName(t, { riseAt: nameAt, each, fill: 0 });
-      point(t, stops);
+      paintName(t, { riseAt: nameAt, each, fill: 0, up: again ? reread(t, again) : undefined });
+      point(t);
       applyStyle(name, landed(t));
 
       applyStyle(bar, sweep(t, { at: sweepAt, dur: 0.3 }));

package/packages/patterns/src/title/slam.ts

@@ -7,7 +7,7 @@ const pattern: Pattern<TitleContent> = {
   ...endSlam,
   id: "title.slam",
   type: "title",
-  does: "옅은 자리표 이름이 먼저 서고 드롭에 꽉 찬 이름이 쾅 내려앉는다, 부제·작은 글이 붙고 짚개가 번갈아 짚는다",
+  does: "옅은 자리표 이름이 먼저 서고 드롭에 꽉 찬 이름이 쾅 내려앉는다, 부제·작은 글이 붙고 짚개가 이름부터 짚는다",
   purposes: { prefer: ["promo", "launch", "ad", "mv"] },
   fits(c, info) {
     if (typeof c?.title !== "string" || !c.title.trim() || [...c.title].length > 16) return "title 이 비었거나 16자를 넘는다";

package/packages/patterns/src/types.ts

@@ -40,6 +40,7 @@ export interface Kit {
   seed: string;
   hits: number[];
   say: SpokenWord[];
+  lines: SpokenWord[];
   slots: ThemeSlots;
   stage: StageLike;
   policy: TextPolicy;

package/packages/plan/src/brief.ts

@@ -1,8 +1,9 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { freezeLimits } from "@kasaframe/core";
 import { captionMode } from "@kasaframe/motion/captions";
 import { bundleFor, MENU, type Dress } from "@kasaframe/motion/menu";
 import { questionsMarkdown, type Question } from "@kasaframe/gen";
-import { loadTheme } from "@kasaframe/themes";
+import { loadTheme, themeFreezeSec } from "@kasaframe/themes";
 import type { GenSpec, ShotSpec } from "./types.ts";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -125,6 +126,8 @@ export function projectBrief(dir: string): string {
   const rules = purposeRules(kf.template);
   const tplFile = join(repo, "templates", kf.template, "template.json");
   const tplMotion = existsSync(tplFile) ? (JSON.parse(readFileSync(tplFile, "utf8")).motion ?? {}) : {};
+  // kf check 와 같은 기준 — 틀이 style.json 을 덮고, 테마는 오류 기준을 늘리기만 한다(늘린 만큼은 경고로 남는다)
+  const freeze = freezeLimits({ ...(style.motion ?? {}), ...tplMotion }.maxFreezeSec, themeFreezeSec(kf.theme));
   const colors = Object.keys(style.colors ?? {}).map((k: string) => `--kf-${k.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`);
   const core = signatures("core");
   const motion = signatures("motion");
@@ -135,7 +138,7 @@ export function projectBrief(dir: string): string {
     ...questionsMarkdown(plan.asks ?? [], (flags) => `npx kf make --answer ${dir} ${flags}`),
     ...narrationSection(dir, kf, plan),
     `**이 영상의 규칙 — 용도 ${kf.template}(틀이 기본값을 덮는다, kf check 가 같은 값으로 잡는다)**`,
-    `1. 화면은 ${rules.maxFreezeSec}초(60fps 6프레임) 넘게 멈추지 않는다 — 끝 카드·큰 숫자·로고도 예외 없이 화면 안 움직임(숫자 굴러가기·칸 채우기·반짝임·글자 흐름·바탕 흐름)으로 계속 살아 있게.`,
+    `1. 화면은 ${freeze.error}초(60fps ${Math.round(freeze.error * 60)}프레임) 넘게 멈추지 않는다${freeze.error > freeze.warn ? `(테마 ${kf.theme} 가 늘린 기준 — ${freeze.warn}초 넘는 멈춤도 경고로 남는다)` : ""} — 끝 카드·큰 숫자·로고도 예외 없이 화면 안 움직임(숫자 굴러가기·칸 채우기·반짝임·글자 흐름·바탕 흐름)으로 계속 살아 있게.`,
     `2. 같은 구도는 ${rules.staticSec.warn}초 넘기지 않는다(${rules.staticSec.error}초 넘으면 오류) — 새 요소·칸 채우기·숫자 키우기·컷·전환으로 바꾼다.`,
     rules.beatMove === "every-beat"
       ? "3. 미세하게 흔들리는 것만으로 때우지 않는다 — 눈에 보이는 큰 움직임이 박마다 하나 이상."

package/packages/themes/src/index.ts

@@ -39,6 +39,9 @@ export function checkTheme(dir: string): string[] {
   if (m.status === "approved" && !m.approvedAt) bad.push("approved 인데 approvedAt 이 없다");
   if (!Array.isArray(m.purposes) || !m.purposes.length) bad.push("theme.json purposes 가 비었다");
   if (!Array.isArray(m.aspect) || !m.aspect.length) bad.push("theme.json aspect 가 비었다");
+  if (m.transitions !== undefined && (!Array.isArray(m.transitions) || !m.transitions.length || m.transitions.some((x) => typeof x !== "string" || !x))) bad.push("theme.json transitions 는 전환 이름 배열(비우려면 칸을 지운다)");
+  const freeze = m.motion?.maxFreezeSec;
+  if (m.motion !== undefined && (typeof m.motion !== "object" || (freeze !== undefined && !(typeof freeze === "number" && freeze > 0 && freeze <= 1)))) bad.push("theme.json motion.maxFreezeSec 는 0 보다 크고 1 이하인 초(멈춤 오류 기준 — 틀·style.json 값보다 늘리기만 한다)");
   const n = m.effects?.length ?? 0;
   if (n < 5 || n > 10) bad.push(`효과는 5–10개 — 지금 ${n}개`);
   for (const e of m.effects ?? []) if (!["value", "layer", "rig"].includes(e.kind)) bad.push(`효과 ${e.name} kind 는 value|layer|rig`);
@@ -150,6 +153,25 @@ export const cellPath = (id: string): string => {
   return join(cellsDir, world, `${variant ?? "base"}.png`);
 };
 
+// 세계의 theme.json — 변주는 세계 것을 따른다. 없는 테마(npm 묶음에 안 든 것 포함)면 null
+function worldManifest(id: string | null | undefined): Partial<ThemeManifest> | null {
+  if (!id) return null;
+  const file = join(themesDir, splitThemeId(id).world, "theme.json");
+  return existsSync(file) ? readJson<Partial<ThemeManifest>>(file) : null;
+}
+
+/** 테마가 허용한 장면 사이 전환(theme.json transitions). 정하지 않았거나 없는 테마면 null(다 허용) */
+export function themeTransitions(id: string | null | undefined): string[] | null {
+  const t = worldManifest(id)?.transitions;
+  return Array.isArray(t) ? t : null;
+}
+
+/** 테마가 정한 멈춤 오류 기준(theme.json motion.maxFreezeSec, 초) — 쓰는 쪽은 freezeLimits 로 틀·style.json 값과 견준다. 없으면 null */
+export function themeFreezeSec(id: string | null | undefined): number | null {
+  const v = worldManifest(id)?.motion?.maxFreezeSec;
+  return typeof v === "number" && v > 0 ? v : null;
+}
+
 /** 3D 무대(rig 효과)를 쓰는 테마인가 — 묻기 보기·견본 시트의 2D/3D 표시 */
 export const themeDims = (t: Pick<ThemeManifest, "effects">): "2D" | "3D" => (t.effects.some((e) => e.kind === "rig") ? "3D" : "2D");
 

package/packages/themes/src/slots.ts

@@ -1,5 +1,5 @@
 /// <reference types="vite/client" />
-// 페이지(Vite) 쪽. 장면 문법 패턴은 테마 이름을 모른다 — 일반 자리 여섯을 부르고, 테마가 themes/<id>/slots.ts 에서 자기 효과로 채운다.
+// 페이지(Vite) 쪽. 장면 문법 패턴은 테마 이름을 모른다 — 일반 자리 일곱을 부르고, 테마가 themes/<id>/slots.ts 에서 자기 효과로 채운다.
 // effects.ts 와 따로 두는 까닭: effects.ts 내보내기는 theme.json 효과 목록과 같아야 한다(테마 시험).
 import type { SceneCtx, Style } from "@kasaframe/core";
 import type { DropBurstState } from "@kasaframe/motion";
@@ -7,6 +7,31 @@ import { worldOf } from "./name.ts";
 
 export type Paint = (t: number) => void;
 
+/** 짚는 칸 자리 — 칸을 깔 상자(왼쪽 위·크기, 패턴이 정한 좌표 px) */
+export interface MarkBox {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export interface MarkPaint {
+  /** 칸이 덮은 글의 색 — 비우면 글색을 그대로 둔다(칸이 옅게 글 뒤에 깔리는 테마) */
+  ink?: string;
+  /**
+   * 짚기 방식 — true 면 장면의 요점(주인공·그 순간 목소리가 말하는 값)에 내려앉아 머물고 다음 요점에서만 옮긴다. 비우면 박 정지점마다
+   * 주인공과 나머지를 번갈아 훑는다(내용이 다 선 뒤 쉬지 않는 몫을 짚개가 진다). 머무는 테마는 쉬는 구간을 멈춤 기준(theme.json
+   * motion.maxFreezeSec)과 내용 움직임으로 감당해야 한다
+   */
+  dwell?: boolean;
+  /**
+   * u(0..1)만큼 간 칸 자리 — from 칸(앞 요점)에서 to 칸(새 요점)으로 옮겨 가는 중. from 이 null 이면 to 자리에 처음 나타나는 중.
+   * u 는 옮김 동안 고르게 흐르고 u=1 이면 to 그대로 — 머무는 짚개(dwell)는 0.3초 안팎에 옮겨 다음 요점까지 서고, 훑는 짚개는 박 정지점 사이를 내내 옮긴다.
+   * 감속·모양 바꿈(높이·칠 짙기)은 테마 몫이고 el 칠을 그 크기에 맞춰 바꿔도 된다
+   */
+  at(from: MarkBox | null, to: MarkBox, u: number): MarkBox;
+}
+
 /**
  * 모든 슬롯은 같은 t 면 같은 화면이고, 난수는 seed 로만. 비운 슬롯은 패턴이 제 기본으로 그린다.
  * 화면 전체를 덮는 3D(three)는 surface 에서만 — 크롬이 WebGL 문맥을 몇 개만 살려 두므로 나머지 슬롯은 DOM·캔버스 2D 로.
@@ -33,9 +58,14 @@ export interface ThemeSlots {
   trace?(el: HTMLElement, o: { ctx: SceneCtx; points: readonly (readonly [number, number])[]; at: number; dur: number; seed: string; tone?: "base" | "accent" }): Paint;
   /** 드롭 터짐 — 그 테마의 드롭 연출. 돌려준 shake 는 패턴이 화면 틀에, punch 는 주인공에 준다. 드롭 번호로만 */
   drop?(el: HTMLElement, o: { ctx: SceneCtx; drop: number }): (t: number) => DropBurstState;
+  /**
+   * 짚음 — 패턴이 「지금 볼 것」(장면의 요점·목소리가 말하는 값)을 짚는 칸(짚개·반전 짚음)의 모양. el = 패턴이 지은 빈 칸(position:absolute, 글 뒤에 깔린다).
+   * 칸 칠(바탕·테두리·모서리)은 여기서 하고, 자리·크기는 패턴이 프레임마다 돌려받은 at 으로 준다. 비우면 강조색 꽉 찬 칸 + onAccent 글
+   */
+  mark?(el: HTMLElement, o: { ctx: SceneCtx; seed: string }): MarkPaint;
 }
 
-export const SLOT_NAMES = ["surface", "panel", "land", "write", "trace", "drop"] as const satisfies readonly (keyof ThemeSlots)[];
+export const SLOT_NAMES = ["surface", "panel", "land", "write", "trace", "drop", "mark"] as const satisfies readonly (keyof ThemeSlots)[];
 
 const mods = import.meta.glob("../../../themes/*/slots.ts", { eager: true }) as Record<string, { slots?: ThemeSlots }>;
 

package/packages/themes/src/types.ts

@@ -29,6 +29,13 @@ export interface ThemeManifest {
   purposes: string[];
   /** 견본이 서는 화면비. 앞이 견본의 화면비 */
   aspect: string[];
+  /** 장면 사이 전환 허용 목록 — 덮기(none·fade·brushWipe·irisBlades·flood)와 이음매(dive·portal·… · gl:<이름>) 이름. 없으면 다 허용, 모르는 이름은 허용 안 한 것과 같다 */
+  transitions?: string[];
+  /**
+   * 검사 기준 — maxFreezeSec 은 멈춤 오류 기준(초). 실제 오류 기준은 틀·style.json 값과 이것 중 큰 쪽이라 테마는 늘리기만 하고,
+   * 경고는 틀·style.json 값 그대로 남는다(core freezeLimits). 화면을 살려 두려고 칸을 돌리지 않고 쉬는 구간을 두는 세계가 쓴다
+   */
+  motion?: { maxFreezeSec?: number };
   effects: ThemeEffectInfo[];
   /** 테마 폴더 기준 파일 이름. 기본 still.png · sample.mp4 */
   still?: string;
@@ -37,6 +44,27 @@ export interface ThemeManifest {
   vary?: ThemeVary;
   /** 고르기 태그 — 분위기·밝기·용도·2D/3D */
   tags?: ThemeTags;
+  /** 효과음 결 — 없으면 기본 결(ui)·기본 크기 */
+  sfx?: ThemeSfx;
+}
+
+/**
+ * theme.json sfx — 그 세계가 내는 소리 결. 렌더가 장면 움직임에서 뽑은 소리 자리에 이 결의 파일을 깐다(레포 sfx/<set>/<역할>.wav).
+ * kf.json sfx 가 칸마다 덮고, kf.json sfx: false 나 kf render --sfx off 면 끈다
+ */
+export interface ThemeSfx {
+  /** 소리 결 — sfx/tags.json 의 sets 이름(pop 뽁·통 · click 딸깍·째깍 · ui 기본) */
+  set: string;
+  /** 둘레 곡(소리 자리 앞뒤 0.2초) 크기 대비 dB — 0 이면 곡과 비슷하게. 역할마다 렌더의 역할 크기(드롭 +2 · 째깍 -4 …)를 더한다 */
+  db?: number;
+  /** 1초에 몇 개까지(2초 창으로 센다 — 0.5 면 2초에 하나) — 넘으면 드롭·끝·휙·착지… 차례로 남긴다 */
+  perSec?: number;
+  /** 이 역할만 낸다 — 없으면 다 */
+  only?: string[];
+  /** 잔소리(낱낱이 나타남·숫자 째깍·타자)도 낸다 — 기본은 장면 바뀜·드롭·주인공 착지·짚개가 핵심 값에 닿는 순간만 */
+  chatter?: boolean;
+  /** 소리마다 곡을 이만큼(dB, 기본 3) 100ms 남짓 눌러 자리를 낸다 */
+  duck?: number;
 }
 
 export type TextureKind = "none" | "grain" | "paper" | "noise" | "scan" | "halftone";

package/sfx/README.md

@@ -0,0 +1,82 @@
+# 효과음 — 렌더가 장면 움직임 자리에 까는 짧은 소리
+
+곡·목소리 위 세 번째 층. 장면 코드를 안 고쳐도 라이브러리 부품이 움직임이 시작하는 순간을 `__kf.events` 에 `sfx` 로 남기고(`@kasaframe/core` `cue`), `kf render` 가 **뜻 있는 자리만** 적게 골라 테마가 고른 **결**의 파일을 둘레 곡과 비슷한 크기로 깔고, 그 순간 곡을 짧게 눌러 자리를 낸다. 곡과 달리 npm 묶음에 실린다(전부 CC0).
+
+- 결(`sets`)마다 역할 하나에 파일 하나 — `sfx/<결>/<역할>.wav`(48kHz 모노 16비트, 꼭대기 -1dBFS). 원본·겹친 소리·라이선스·`lead`(파일 시작 → 꼭대기 초)·`level`(100ms 창 RMS 최댓값 dBFS — 섞을 때 크기를 맞추는 기준)는 `tags.json`.
+- **곡에 안 묻히는 건 2–6kHz 다.** 600–2000Hz 에 몸이 있는 소리는 6dB 키워도 곡 아래였다(렌더 보고서의 가려짐). 그래서 몸이 낮은 소리(뽁·통·쿵)는 그 대역의 짧은 어택을 꼭대기에 맞춰 겹쳐 짓는다(아래 표의 `+`).
+- 테마가 결과 크기를 고른다 — `theme.json` 의 `sfx: { set, db, perSec, only, chatter, duck }`. 없으면 `ui` 결·둘레 곡 -2dB·1초 1개·잔소리 없음·곡 3dB 누름. 프로젝트 `kf.json` 의 `sfx` 가 칸마다 덮고, `sfx: false` 나 `kf render|make --sfx off` 면 끈다(끄면 소리는 효과음 이전과 바이트까지 같다).
+- 다른 폴더를 쓰려면 `KF_SFX_DIR=<폴더>` — 그 폴더에도 같은 꼴의 `tags.json`.
+- 다시 짓기: Kenney 묶음 zip 여섯(`https://kenney.nl/assets/<ui-audio|interface-sounds|impact-sounds|digital-audio|rpg-audio|casino-audio>`)을 한 폴더에 풀고 `node tools/sfx/build.ts --src <그 폴더>`. 묶음마다 `License.txt` 에서 CC0 를 확인하고 없으면 멈춘다.
+
+## 결
+
+| 결 | 소리 | 쓰는 세계 |
+|---|---|---|
+| `pop` | 물방울 뽁·나무 통·둥근 쿵에 또렷한 톡 어택 | kawaii-sticker(둘레 곡과 같은 크기, 1초에 하나까지) |
+| `click` | 역할마다 작은 스위치·시계 소리만(전부 2–6kHz) | og-measure(딸깍·째깍만, 둘레 곡 -4dB, 2초에 하나까지) |
+| `ui` | 가벼운 UI 소리 — 퉁김·휙·주먹 쿵에 또렷한 어택 | 결을 안 고른 세계 |
+
+## 역할 — 누가 저절로 남기나
+
+기본으로 까는 것은 뜻 있는 자리 — 장면 바뀜·드롭·주인공 착지·짚개가 요점에 닿는 순간. 부품이 잔소리(`minor`)로 남긴 것(표의 「잔소리」)은 `chatter: true` 일 때만 깐다.
+
+| 역할 | 뜻 | 저절로 남기는 부품 |
+|---|---|---|
+| `appear` | 나타남 | 잔소리 — motion `enter`(rise·scaleIn·maskWipe·slide, fade·blurIn 은 소리 없이) · 패턴 판(panel) · og-measure 칸이 서는 순간 |
+| `stick` | 톡 붙기 | kawaii 주인공 스티커(폭 400px 넘는 것 — 작은 이름표는 잔소리) · `stickOn` · 잔소리 — motion `enter("pop")` |
+| `land` | 착지 | 패턴 `land` 슬롯·`slam`·숫자 굴림이 앉을 때 · og-measure 숫자 꽂힘 · 잔소리 — motion `enter("drop")` |
+| `hop` | 통 뛰기 | 잔소리 — kawaii 스티커 `hops` |
+| `whoosh` | 휙 전환 | 이음매(`transition3d` — 화면이 여럿이면 넘어갈 때마다) · `transition`(whip·zoomThrough·slide) · 컷 카메라(shotCam·trackCam) · 잔소리 — 떼어짐·테이프 |
+| `tick` | 숫자 째깍 | 잔소리 — 패턴 숫자 굴림·카운터 · og-measure 계기판·점 |
+| `select` | 짚기 딸깍 | 패턴 짚개가 요점으로 옮겨 갈 때 · og-measure 읽는 칸이 새 값에 닿을 때 |
+| `type` | 타자 | 잔소리 — 패턴 `write` 슬롯(0.09초마다) · og-measure 로그 줄 |
+| `drop` | 드롭 쿵 | motion `dropBurst`(slap·패턴 drop 슬롯) · beats.json 드롭 |
+| `burst` | 팡 터짐 | kawaii `stickerBurst` |
+| `end` | 끝 마무리 | og-measure 끝 도장 |
+
+손으로 지은 움직임은 장면에서 `ctx.sfx("<역할>", 장면 초)` — 잔소리로 치지 않는다.
+
+## 섞기
+
+- 밀도: 같은 역할은 0.1초 안에 하나, 아무 소리끼리 0.25초 띄우고, 아무 2초 창에 `perSec`×2 개(적어도 하나)까지. 넘치면 드롭 > 끝 > 휙 > 착지 > 붙기·팡 > 뛰기 > 짚기 > 나타남 > 째깍 > 타자 차례로 남기고, 드롭 앞뒤 0.35초는 드롭만.
+- 크기: 둘레 곡(소리 자리 앞뒤 0.2초) 크기 + `db` + 역할 크기(드롭 +2 … 째깍·타자 -4), 목소리가 있으면 4dB 더 낮게. 역할마다 저역을 걷는다(드롭 60Hz·그 밖 150–300Hz — 킥·베이스와 안 겹치게).
+- 자리 내기: 소리마다 곡을 `duck` dB(기본 3) 소리 시작 10ms 앞부터 꼭대기 100ms 뒤까지 누른다.
+- 가려짐: 소리가 차지하는 대역(제 가장 센 대역에서 10dB 안쪽) 가운데 곡을 가장 넘는 대역에서, 소리 순간(꼭대기 앞 10ms·뒤 90ms) 효과음 ÷ 눌린 곡이 4dB 가 안 되면 6dB 까지 더 키운다. 렌더 보고서 `sfx.hits` 에 소리마다 `band`·`smr`·`boost`·`over`(넓은 대역 크기 − 둘레 곡).
+
+<!-- 파일 표 — tools/sfx/build.ts 가 짓는다 -->
+
+| 파일 | 역할 | 길이 | 원본 | 라이선스 |
+|---|---|---|---|---|
+| `pop/appear.wav` | 나타남 | 0.15초 | Kenney Interface Sounds (1.0) — `drop_004.ogg` + Kenney Interface Sounds (1.0) — `select_001.ogg`(-6dB) | CC0 1.0 |
+| `pop/stick.wav` | 톡 붙기 | 0.15초 | Kenney Interface Sounds (1.0) — `drop_002.ogg` + Kenney Interface Sounds (1.0) — `tick_004.ogg`(-4dB) | CC0 1.0 |
+| `pop/land.wav` | 착지 | 0.12초 | Kenney Impact Sounds (1.0) — `impactWood_light_000.ogg` + Kenney Casino Audio (1.1) — `chip-lay-1.ogg`(-4dB) | CC0 1.0 |
+| `pop/hop.wav` | 통 뛰기 | 0.30초 | Kenney Digital Audio — `phaseJump1.ogg` + Kenney UI SFX Set — `click5.ogg`(-6dB) | CC0 1.0 |
+| `pop/whoosh.wav` | 휙 전환 | 0.25초 | Kenney Interface Sounds (1.0) — `maximize_002.ogg` | CC0 1.0 |
+| `pop/tick.wav` | 숫자 째깍 | 0.02초 | Kenney Interface Sounds (1.0) — `tick_002.ogg` | CC0 1.0 |
+| `pop/select.wav` | 짚기 딸깍 | 0.04초 | Kenney Interface Sounds (1.0) — `select_001.ogg` | CC0 1.0 |
+| `pop/type.wav` | 타자 | 0.03초 | Kenney UI SFX Set — `click5.ogg` | CC0 1.0 |
+| `pop/drop.wav` | 드롭 쿵 | 0.52초 | Kenney Impact Sounds (1.0) — `impactSoft_heavy_000.ogg` + Kenney Impact Sounds (1.0) — `impactMetal_light_000.ogg`(-3dB) | CC0 1.0 |
+| `pop/burst.wav` | 팡 터짐 | 0.19초 | Kenney Digital Audio — `powerUp2.ogg` + Kenney Casino Audio (1.1) — `chips-collide-1.ogg`(-4dB) | CC0 1.0 |
+| `pop/end.wav` | 끝 마무리 | 0.32초 | Kenney Interface Sounds (1.0) — `confirmation_003.ogg` | CC0 1.0 |
+| `click/appear.wav` | 나타남 | 0.09초 | Kenney UI SFX Set — `click1.ogg` | CC0 1.0 |
+| `click/stick.wav` | 톡 붙기 | 0.01초 | Kenney Interface Sounds (1.0) — `click_003.ogg` | CC0 1.0 |
+| `click/land.wav` | 착지 | 0.14초 | Kenney Interface Sounds (1.0) — `switch_001.ogg` | CC0 1.0 |
+| `click/hop.wav` | 통 뛰기 | 0.06초 | Kenney Interface Sounds (1.0) — `toggle_004.ogg` | CC0 1.0 |
+| `click/whoosh.wav` | 휙 전환 | 0.22초 | Kenney Interface Sounds (1.0) — `scroll_004.ogg` | CC0 1.0 |
+| `click/tick.wav` | 숫자 째깍 | 0.02초 | Kenney Interface Sounds (1.0) — `tick_001.ogg` | CC0 1.0 |
+| `click/select.wav` | 짚기 딸깍 | 0.04초 | Kenney Interface Sounds (1.0) — `select_001.ogg` | CC0 1.0 |
+| `click/type.wav` | 타자 | 0.05초 | Kenney UI SFX Set — `switch12.ogg` | CC0 1.0 |
+| `click/drop.wav` | 드롭 쿵 | 0.21초 | Kenney RPG Audio — `metalLatch.ogg` | CC0 1.0 |
+| `click/burst.wav` | 팡 터짐 | 0.13초 | Kenney Casino Audio (1.1) — `chip-lay-1.ogg` | CC0 1.0 |
+| `click/end.wav` | 끝 마무리 | 0.11초 | Kenney Interface Sounds (1.0) — `toggle_002.ogg` | CC0 1.0 |
+| `ui/appear.wav` | 나타남 | 0.13초 | Kenney Interface Sounds (1.0) — `pluck_001.ogg` + Kenney Interface Sounds (1.0) — `tick_004.ogg`(-6dB) | CC0 1.0 |
+| `ui/stick.wav` | 톡 붙기 | 0.15초 | Kenney Interface Sounds (1.0) — `drop_001.ogg` + Kenney Interface Sounds (1.0) — `tick_004.ogg`(-6dB) | CC0 1.0 |
+| `ui/land.wav` | 착지 | 0.15초 | Kenney Impact Sounds (1.0) — `impactGeneric_light_000.ogg` + Kenney Casino Audio (1.1) — `chip-lay-1.ogg`(-4dB) | CC0 1.0 |
+| `ui/hop.wav` | 통 뛰기 | 0.14초 | Kenney Interface Sounds (1.0) — `pluck_002.ogg` + Kenney UI SFX Set — `click5.ogg`(-6dB) | CC0 1.0 |
+| `ui/whoosh.wav` | 휙 전환 | 0.25초 | Kenney Interface Sounds (1.0) — `maximize_001.ogg` | CC0 1.0 |
+| `ui/tick.wav` | 숫자 째깍 | 0.01초 | Kenney Interface Sounds (1.0) — `click_003.ogg` | CC0 1.0 |
+| `ui/select.wav` | 짚기 딸깍 | 0.23초 | Kenney Interface Sounds (1.0) — `select_003.ogg` | CC0 1.0 |
+| `ui/type.wav` | 타자 | 0.03초 | Kenney UI SFX Set — `click5.ogg` | CC0 1.0 |
+| `ui/drop.wav` | 드롭 쿵 | 0.45초 | Kenney Impact Sounds (1.0) — `impactPunch_heavy_000.ogg` + Kenney Impact Sounds (1.0) — `impactMetal_light_000.ogg`(-3dB) | CC0 1.0 |
+| `ui/burst.wav` | 팡 터짐 | 0.16초 | Kenney Casino Audio (1.1) — `chips-collide-1.ogg` | CC0 1.0 |
+| `ui/end.wav` | 끝 마무리 | 0.14초 | Kenney Interface Sounds (1.0) — `switch_001.ogg` | CC0 1.0 |