kasaframe 0.1.4 → 0.1.6

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";
@@ -57,6 +85,11 @@ export interface ThemeVary {
   keep?: string[];
   /** 색상은 두고 명도·채도만 따라가는 색 열쇠(풀·물 같은 재료 색) */
   fixedHue?: string[];
+  /**
+   * 밝기마다 세계가 정해 둔 색 한 벌 — 브랜드가 라이트·다크를 따로 정한 세계(두 벌이 서로 거울상이 아니라 뒤집어 옮기면 정본 값이 안 나온다).
+   * 그 밝기 판은 이 벌을 원점으로 삼고, 안 적은 축(바탕 빛깔·글 명도·강조 색상)은 그 벌 값 그대로. 열쇠는 style.json colors 와 같다
+   */
+  palettes?: Partial<Record<"light" | "dark", Record<string, string>>>;
   /** 글꼴 짝 id(packages/themes/kit/fonts.json)·`tag:<태그>`·`base`(세계 글꼴) */
   fonts?: string[];
   /** 세 글꼴 스택을 짝의 고정폭 하나로(한 글꼴 HUD) — 그러면 monoAll 짝만 받는다 */

package/packages/themes/src/vary.ts

@@ -1,34 +1,16 @@
 // 변주 — 세계 하나에서 겉모습만 바꾼 판을 데이터로 뽑는다(SPEC 9 변주). 코드는 세계 것을 그대로 쓰고, 여기서는 style 위에 덮을 판만 짓는다.
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
 import { rand, randRange, type KfStyle } from "@kasaframe/core";
 import { hueDist, labOf, parseColor } from "./color.ts";
+import { type FontPair, fontPairs, titleWeight } from "./fonts.ts";
 import { lchOf, NEUTRAL_C, transformPalette } from "./palette.ts";
 import type { TextureKind, ThemeManifest, ThemeTags, ThemeVary, VariantManifest, VariantParams } from "./types.ts";
 
-export interface FontPair {
-  id: string;
-  name: string;
-  ko: string;
-  tags: string[];
-  sans: string;
-  display: string;
-  mono: string;
-  faces: NonNullable<KfStyle["fonts"]["faces"]>;
-  weightDisplay: number;
-  weightBody: number;
-  tracking: string;
-  monoAll?: boolean;
-}
-
-let pairs: FontPair[] | null = null;
-export const fontPairs = (): FontPair[] => (pairs ??= JSON.parse(readFileSync(fileURLToPath(new URL("../kit/fonts.json", import.meta.url)), "utf8")));
-
 /** 세계가 허락한 글꼴 짝 — 「base」는 세계 글꼴 그대로 */
 export function allowedFonts(vary: ThemeVary): string[] {
   const all = fontPairs().filter((p) => !vary.monoAll || p.monoAll);
   const want = vary.fonts ?? ["base"];
-  const ids = want.flatMap((w) => (w === "base" ? ["base"] : w.startsWith("tag:") ? all.filter((p) => p.tags.includes(w.slice(4))).map((p) => p.id) : all.some((p) => p.id === w) ? [w] : []));
+  // tag:sans+geometric 은 두 태그를 다 가진 짝 — 짝이 수백이라 태그 하나로는 결이 다른 무리까지 딸려 온다
+  const ids = want.flatMap((w) => (w === "base" ? ["base"] : w.startsWith("tag:") ? all.filter((p) => w.slice(4).split("+").every((t) => p.tags.includes(t))).map((p) => p.id) : all.some((p) => p.id === w) ? [w] : []));
   return [...new Set(ids)];
 }
 
@@ -71,28 +53,40 @@ function sampleHue(seed: string, i: number, ranges: [number, number][]): number
   return ranges[0][0];
 }
 
+/** 그 밝기의 원점 색 — 세계가 밝기마다 한 벌을 정해 뒀으면(vary.palettes) 그 벌, 세계 자신의 밝기면 세계 색. 안 정한 세계는 null(세계 색을 옮긴다) */
+export function paletteOf(style: KfStyle, vary: ThemeVary, scheme: "light" | "dark"): KfStyle["colors"] | null {
+  if (!vary.palettes) return null;
+  if (scheme === style.scheme) return style.colors;
+  return (vary.palettes[scheme] as KfStyle["colors"] | undefined) ?? null;
+}
+
 /** 손잡이 값 하나 — 세계가 안 받는 축은 세계 값 */
 export function sampleParams(style: KfStyle, vary: ThemeVary, seed: string, n: number): VariantParams {
   const base = baseParams(style);
   const r = (k: number, lo: number, hi: number) => randRange(seed, n * 32 + k, lo, hi);
   const pickOf = <T>(k: number, items: readonly T[]): T => items[Math.min(items.length - 1, Math.floor(rand(seed, n * 32 + k) * items.length))];
   const scheme = pickOf(0, vary.scheme ?? [style.scheme]);
-  const bgR = vary.bg?.[scheme] ?? BG_L[scheme];
-  const hue = vary.hue ? sampleHue(seed, n * 32 + 1, vary.hue) : base.hue;
+  const own = paletteOf(style, vary, scheme);
+  const origin = own ? baseParams({ ...style, scheme, colors: own }) : null;
+  const bgR = vary.bg?.[scheme] ?? (origin ? [origin.bgL, origin.bgL] : BG_L[scheme]);
+  const hue = vary.hue ? sampleHue(seed, n * 32 + 1, vary.hue) : (origin ?? base).hue;
   // 무채색 빛깔은 반쯤은 강조색 쪽(한 집안), 반쯤은 아무 쪽
   const tintH = rand(seed, n * 32 + 2) < 0.5 ? (hue + r(3, -30, 30) + 360) % 360 : r(4, 0, 360);
   const tex = pickOf(5, vary.texture ?? [base.texture.kind]);
   const chroma = vary.chroma ? r(10, vary.chroma[0], vary.chroma[1]) : 1;
   // 바탕이 색 잉크인 세계는 바탕이 강조색과 같은 각도로 돌아야 모눈·선과 한 벌로 남는다 — tint 축은 무채색 바탕 세계 것
-  const tint = base.tint.c >= NEUTRAL_C
-    ? { h: (base.tint.h + hue - base.hue + 360) % 360, c: base.tint.c * chroma }
-    : { h: tintH, c: vary.tint ? r(7, vary.tint[0], vary.tint[1]) * (scheme === "dark" ? DARK_TINT : 1) : base.tint.c };
+  // 정해 둔 벌이 있으면 바탕 빛깔·글 명도는 그 벌의 것 — 브랜드 무채색(푸른 회색)에 아무 빛깔이나 얹지 않는다
+  const tint = origin && !vary.tint
+    ? origin.tint
+    : base.tint.c >= NEUTRAL_C
+      ? { h: (base.tint.h + hue - base.hue + 360) % 360, c: base.tint.c * chroma }
+      : { h: tintH, c: vary.tint ? r(7, vary.tint[0], vary.tint[1]) * (scheme === "dark" ? DARK_TINT : 1) : base.tint.c };
   const q = (v: number) => +v.toFixed(4);
   return {
     scheme,
     bgL: q(r(6, bgR[0], bgR[1])),
     tint: { h: q(tint.h), c: q(tint.c) },
-    inkL: q(scheme === style.scheme && rand(seed, n * 32 + 8) < 0.5 ? base.inkL : r(9, INK_L[scheme][0], INK_L[scheme][1])),
+    inkL: q(origin ? origin.inkL : scheme === style.scheme && rand(seed, n * 32 + 8) < 0.5 ? base.inkL : r(9, INK_L[scheme][0], INK_L[scheme][1])),
     hue: q(hue),
     chroma: q(chroma),
     fonts: pickOf(11, allowedFonts(vary)),
@@ -107,13 +101,15 @@ export function sampleParams(style: KfStyle, vary: ThemeVary, seed: string, n: n
 /** 손잡이 값 → 세계 style 위에 덮을 판. 색이 검사를 못 넘으면 bad 에 까닭 */
 export function overlayOf(style: KfStyle, manifest: Pick<ThemeManifest, "vary">, p: VariantParams): { style: VariantManifest["style"]; bad: string[]; measured: Record<string, number> } {
   const vary = manifest.vary ?? {};
-  const pal = transformPalette(style.colors, p, { keep: vary.keep, fixedHue: vary.fixedHue });
+  const pal = transformPalette(paletteOf(style, vary, p.scheme) ?? style.colors, p, { keep: vary.keep, fixedHue: vary.fixedHue });
   const out: VariantManifest["style"] = { scheme: p.scheme, colors: pal.colors as KfStyle["colors"] };
   if (p.fonts !== "base") {
     const f = fontPairs().find((x) => x.id === p.fonts);
     if (!f) return { style: out, bad: [`글꼴 짝 ${p.fonts} 이 없다`], measured: pal.measured };
-    out.fonts = vary.monoAll ? { sans: f.mono, display: f.mono, mono: f.mono, faces: f.faces } : { sans: f.sans, display: f.display, mono: f.mono, faces: f.faces };
-    out.type = { weightDisplay: f.weightDisplay, weightBody: f.weightBody, tracking: f.tracking };
+    // 라이선스·출처는 짝 목록의 것 — style.json 의 face 는 core 계약(family·src·weight) 그대로
+    const faces = f.faces.map(({ license: _l, source: _s, ...face }) => face);
+    out.fonts = vary.monoAll ? { sans: f.mono, display: f.mono, mono: f.mono, faces } : { sans: f.sans, display: f.display, mono: f.mono, faces };
+    out.type = { weightDisplay: titleWeight(f, vary.monoAll), weightBody: f.weightBody, tracking: f.tracking };
   }
   if (p.radius !== null) {
     const md0 = style.radius.md || 12;
@@ -265,6 +261,14 @@ export function nameVariant(params: VariantParams, taken: Set<string>, colors?:
   return { id, name, desc };
 }
 
+// 글꼴 짝 태그 → 변주 분위기 낱말. kf theme suggest 가 요청 낱말을 이 낱말과도 견준다
+const FONT_MOOD: [string, string][] = [
+  ["serif", "고전적"], ["classic", "고전적"], ["elegant", "우아한"], ["traditional", "전통"], ["brush", "붓글씨"], ["newspaper", "신문"],
+  ["rounded", "귀여운"], ["playful", "발랄한"], ["comic", "만화"], ["hand", "손글씨"], ["pixel", "레트로"], ["retro", "레트로"],
+  ["mono", "기술적"], ["tech", "기술적"], ["futuristic", "미래적"], ["modern", "모던"], ["industrial", "산업"], ["signage", "안내판"],
+  ["calm", "차분한"], ["strong", "강한"], ["neon", "네온"],
+];
+
 /** 변주 태그 — 세계 태그에 색·질감·글꼴이 주는 분위기를 더한다 */
 export function variantTags(world: ThemeTags, params: VariantParams, colors?: Record<string, string>): ThemeTags {
   const p = seen(params, colors);
@@ -277,10 +281,7 @@ export function variantTags(world: ThemeTags, params: VariantParams, colors?: Re
   if (["paper", "grain", "halftone", "noise"].includes(p.texture.kind)) mood.add("아날로그");
   if (p.texture.kind === "scan") mood.add("레트로");
   const tags = fontPairs().find((x) => x.id === p.fonts)?.tags ?? [];
-  if (tags.includes("serif")) mood.add("고전적");
-  if (tags.includes("rounded")) mood.add("귀여운");
-  if (tags.includes("pixel")) mood.add("레트로");
-  if (tags.includes("mono")) mood.add("기술적");
+  for (const [tag, word] of FONT_MOOD) if (tags.includes(tag)) mood.add(word);
   return { ...world, mood: [...mood], light: p.scheme };
 }
 

package/presets/kawaii-pastel.json

@@ -35,12 +35,12 @@
       },
       {
         "family": "JetBrains Mono",
-        "src": "https://cdn.jsdelivr.net/npm/@fontsource-variable/jetbrains-mono@5/files/jetbrains-mono-latin-wght-normal.woff2",
+        "src": "https://cdn.jsdelivr.net/npm/@fontsource-variable/jetbrains-mono@5.3.0/files/jetbrains-mono-latin-wght-normal.woff2",
         "weight": "100 800"
       },
       {
         "family": "Jua",
-        "src": "https://cdn.jsdelivr.net/gh/google/fonts@main/ofl/jua/Jua-Regular.ttf",
+        "src": "https://cdn.jsdelivr.net/gh/google/fonts@bd8f81ddb5c74d5c8897b36ad88b440266245103/ofl/jua/Jua-Regular.ttf",
         "weight": "400"
       }
     ]

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 |