kasaframe 0.1.4 → 0.1.6

package/packages/core/src/frame.ts

@@ -39,20 +39,22 @@ export function onFrame(fn: (t: number) => void): () => void {
   };
 }
 
-export type MotionEventKind = "pulse" | "shake" | "camera" | "flash" | "move";
+export type MotionEventKind = "pulse" | "shake" | "camera" | "flash" | "move" | "sfx";
 
 /** 검사(kf check)가 style.json 움직임 규칙 위반을 세는 기록. 효과가 0 이 아닌 프레임마다 한 줄 */
 export interface KfMotionEvent {
-  /** 전체 시각(초) — 그 프레임 */
+  /** 전체 시각(초) — 그 프레임. sfx 는 그 소리가 날 시각 */
   t: number;
   kind: MotionEventKind;
   /** 부품 id */
   source: string;
-  /** pulse 0..1, shake 는 px, camera 는 이동량(px 또는 배율 차), flash 0..1, move 1 */
+  /** pulse 0..1, shake 는 px, camera 는 이동량(px 또는 배율 차), flash 0..1, move 1, sfx 는 크기(0..1) */
   value: number;
-  /** move 일 때 움직임 이름(fade·rise·whip …) — 같은 움직임 되풀이를 센다 */
+  /** move 일 때 움직임 이름(fade·rise·whip …) — 같은 움직임 되풀이를 센다. sfx 면 효과음 역할 */
   name?: string;
   scene?: string;
+  /** sfx 만 — 낱낱이 나타남·숫자 째깍·타자 같은 잔소리. 렌더는 기본으로 안 깐다(테마 sfx.chatter 면 깐다) */
+  minor?: boolean;
 }
 
 interface KfEventHost {
@@ -83,6 +85,7 @@ export function emit(e: Omit<KfMotionEvent, "t"> & { t?: number }): void {
   const row: KfMotionEvent = { t, kind: e.kind, source: e.source, value: Math.round(e.value * 1000) / 1000 };
   if (e.name !== undefined) row.name = e.name;
   if (e.scene !== undefined) row.scene = e.scene;
+  if (e.minor) row.minor = true;
   sink().push(row);
 }
 

package/packages/core/src/index.ts

@@ -23,5 +23,7 @@ export { combine, toCss, applyStyle } from "./style.ts";
 export type { Style, CssStyle } from "./style.ts";
 export { setFrameTime, frameTime, onFrame, emit, motionEvents, resetMotionEvents, setFrameSample, frameSample } from "./frame.ts";
 export type { KfMotionEvent, MotionEventKind, FrameSample } from "./frame.ts";
-export { silentBeats, scaleOf, cssVars, fontCss } from "./project.ts";
+export { SFX_ROLES, SFX_LABEL, cue, cueAt, withoutSfx } from "./sfx.ts";
+export type { SfxRole, CueOpts } from "./sfx.ts";
+export { silentBeats, scaleOf, cssVars, fontCss, MAX_FREEZE_SEC, freezeLimits } from "./project.ts";
 export type { CaptionLook, KfMeta, KfStyle, MotionRules, SafeArea, SceneCtx, FontFace, StyleLook } from "./project.ts";

package/packages/core/src/project.ts

@@ -1,4 +1,5 @@
 import { createBeats, type Beats } from "./beats.ts";
+import type { CueOpts, SfxRole } from "./sfx.ts";
 
 export interface KfMeta {
   fps: number;
@@ -36,6 +37,19 @@ export interface MotionRules {
   durations?: { fast: number; base: number; slow: number };
 }
 
+/** 멈춤 기본 기준 — 단 0.1초(60fps 6프레임)도 쉬지 않는다 */
+export const MAX_FREEZE_SEC = 0.1;
+
+/**
+ * 멈춤 기준 — 경고는 틀·style.json 값(틀이 이긴다, 없으면 0.1초), 오류는 그 값과 테마 값(theme.json motion.maxFreezeSec) 중 큰 쪽.
+ * 테마는 늘리기만 한다 — 짚음이 요점에 머물러 화면이 쉬는 세계(OG 측정 화면)가 그 쉼으로 장면을 떨어뜨리지 않게 하되,
+ * 고정 관찰 화면 틀·스타일이 늘린 값(0.5)을 조이지는 못하고, 늘린 만큼도 경고로는 보인다
+ */
+export function freezeLimits(base: number | undefined, theme?: number | null): { warn: number; error: number } {
+  const warn = base ?? MAX_FREEZE_SEC;
+  return { warn, error: Math.max(warn, theme ?? 0) };
+}
+
 export interface FontFace {
   family: string;
   src: string;
@@ -131,6 +145,11 @@ export interface SceneCtx {
   safe: SafeArea;
   /** 프로젝트 assets/ 기준 경로 → 페이지에서 쓸 주소 */
   asset(path: string): string;
+  /**
+   * 효과음 자리 — 장면 시각 at(초)에 그 역할 소리. build 에서 불러도 draw 에서 불러도 된다(같은 자리는 한 번).
+   * 라이브러리 부품(테마 효과·패턴·전환·드롭)은 저절로 남기니, 부품 밖에서 손으로 지은 움직임에만 쓴다
+   */
+  sfx(role: SfxRole, at: number, o?: Omit<CueOpts, "scene">): void;
 }
 
 /** 곡 없는 프로젝트용. pulse 는 늘 0(드롭이 없다), drop(i) 는 던진다 */

package/packages/core/src/sfx.ts

@@ -0,0 +1,70 @@
+import { emit, frameTime } from "./frame.ts";
+
+/**
+ * 효과음 역할 — 소리 결(테마가 고른 묶음)마다 역할 하나에 파일 하나가 있다. 렌더가 이 이름으로 파일을 고르고, 밀도 상한을 넘으면
+ * 앞 역할(드롭·끝·휙…)부터 남긴다
+ */
+export const SFX_ROLES = ["appear", "stick", "land", "hop", "whoosh", "tick", "select", "type", "drop", "burst", "end"] as const;
+
+export type SfxRole = (typeof SFX_ROLES)[number];
+
+export const SFX_LABEL: Record<SfxRole, string> = {
+  appear: "나타남",
+  stick: "톡 붙기",
+  land: "착지",
+  hop: "통 뛰기",
+  whoosh: "휙 전환",
+  tick: "숫자 째깍",
+  select: "짚기 딸깍",
+  type: "타자",
+  drop: "드롭 쿵",
+  burst: "팡 터짐",
+  end: "끝 마무리",
+};
+
+export interface CueOpts {
+  /** 부품 id — 같은 시각·같은 부품은 한 번만 남는다 */
+  source?: string;
+  scene?: string;
+  /** 0..1 — 역할 크기에 곱한다(작은 칸은 작게) */
+  weight?: number;
+  /**
+   * 잔소리 — 낱낱이 나타나는 칸·숫자 째깍·타자처럼 자주 나는 것. 렌더가 기본으로 안 깐다(다 깔면 곡에 묻히고 시끄럽다).
+   * 장면 바뀜·드롭·주인공 착지·짚개가 핵심 값에 닿는 순간만 minor 없이 남긴다
+   */
+  minor?: boolean;
+}
+
+let muted = 0;
+
+/**
+ * 이 안에서 그린 것은 소리 자리를 안 남긴다 — 이음매가 앞뒤 장면을 한 벌 더 지어 다른 시각으로 그릴 때(진짜 장면이 이미 남겼고,
+ * 첫 프레임에 서 있는 뒤 장면은 시작 직후로 보이는 부품이 프레임마다 새 자리를 남긴다)
+ */
+export function withoutSfx<T>(fn: () => T): T {
+  muted++;
+  try {
+    return fn();
+  } finally {
+    muted--;
+  }
+}
+
+// 움직임이 시작하고 이만큼 안에 그린 프레임이 그 자리를 남긴다 — 검사(30fps)·렌더(60fps)·모션 블러 하위 프레임 어느 쪽도 한 번은 이 안에 든다
+const WINDOW = 0.12;
+
+/** 효과음 자리를 전체 시각 t(초)에 남긴다 — 장면 작성자의 ctx.sfx 가 부르는 자리 */
+export function cueAt(role: SfxRole, t: number, o: CueOpts = {}): void {
+  if (muted || !Number.isFinite(t) || t < 0) return;
+  emit({ kind: "sfx", t, name: role, source: o.source ?? role, scene: o.scene, value: o.weight ?? 1, ...(o.minor ? { minor: true } : {}) });
+}
+
+/**
+ * 움직임 부품이 부른다 — since 는 그 움직임이 시작하고 지난 초(그 프레임의 부품 시각 − 시작 시각). 시작 직후 프레임에서
+ * 「지금 프레임 시각 − since」를 소리 자리로 남긴다. 부품이 장면 시각을 얼마나 밀어 받았든 시작 순간의 전체 시각이 나오고,
+ * 어느 프레임이 남기든 같은 값이라 탭을 나눠 찍어도 같은 소리다
+ */
+export function cue(role: SfxRole, since: number, o: CueOpts = {}): void {
+  if (!(since >= 0 && since < WINDOW)) return;
+  cueAt(role, frameTime() - since, o);
+}

package/packages/director/src/assemble.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { themeTransitions } from "@kasaframe/themes";
 import { worldOf } from "@kasaframe/themes/name";
 import { dressSeed, type Dress } from "@kasaframe/motion/menu";
 import { loadTemplate, sceneSkeleton, type Template } from "@kasaframe/plan";
@@ -8,7 +9,7 @@ import { catalog } from "./catalog.ts";
 import { TYPES, type Content, type Scene, type SceneType } from "./content.ts";
 import type { AspectName, Energy, TextPolicy } from "./pattern.ts";
 import { type Entry, type Pick, repick, selectAll, type Slot } from "./select.ts";
-import { type BeatsLite, cyclingText, dressAll, energyOf, seamKinds, seamSpots, type Spot } from "./transitions.ts";
+import { type BeatsLite, cyclingText, dressAll, energyOf, seamKinds, seamsAllowed, seamSpots, type Spot } from "./transitions.ts";
 
 // content.json → 장면 시간표·장면 파일. 두 단계로 나뉜다 — 그 사이에 kf narrate 가 목소리로 장면 길이를 정한다.
 //   1. layout: 내용 장면 + 이음매를 kf.json 에 놓고 들릴 말을 captions.json 에(길이는 어림)
@@ -79,7 +80,8 @@ export function layout(dir: string, content: Content, o: { keepTiming?: boolean
   const seamSec = tplSeams[0]?.sec ?? 1.2;
   // 투영을 맞춰 구운 3D 샷(kf blender 가 kf.json 장면에 남긴 matched)은 다시 놓아도 잃지 않는다
   const matched = new Set<string>((kf.scenes ?? []).filter((s: KfScene) => s.matched).map((s: KfScene) => s.id));
-  const spots = seamSpots(content.scenes.map((s) => s.type), content.scenes.map(spaceOf), tplSeams.length, content.scenes.map((s) => matched.has(s.id)));
+  // 테마가 이음매 전환을 하나도 허용하지 않으면(컷·덮기만) 이음매 장면을 안 넣는다
+  const spots = seamsAllowed(themeTransitions(kf.theme)) ? seamSpots(content.scenes.map((s) => s.type), content.scenes.map(spaceOf), tplSeams.length, content.scenes.map((s) => matched.has(s.id))) : [];
   const taken = new Set(content.scenes.map((s) => s.id));
   const seamIds: string[] = [];
   for (let k = 0; seamIds.length < spots.length; k++) {
@@ -274,9 +276,10 @@ export async function build(dir: string, content: Content, o: BuildOpts = {}): P
     const b = spaceOf(scenes[i + 1] ?? {});
     return { at: i, bridge: a === b ? false : b === "3d" ? "up" : "down" };
   });
-  const kinds = seamKinds(spots, key, tpl.scenes.find((s) => s.role === "seam")?.transition ?? "dive", Object.fromEntries(seamIdx.map((i, k) => [k, seamFailed[scenes[i].id] ?? []])));
+  const allow = themeTransitions(theme);
+  const kinds = seamKinds(spots, key, tpl.scenes.find((s) => s.role === "seam")?.transition ?? "dive", Object.fromEntries(seamIdx.map((i, k) => [k, seamFailed[scenes[i].id] ?? []])), allow);
 
-  const dress = dressAll(key, scenes, tpl.moves, world);
+  const dress = dressAll(key, scenes, tpl.moves, world, allow);
   const scenesDir = join(dir, "scenes");
   mkdirSync(scenesDir, { recursive: true });
   const report: SceneReport[] = [];

package/packages/director/src/index.ts

@@ -5,7 +5,7 @@ export { definePattern } from "./pattern.ts";
 export type { AspectName, CameraKind, Energy, Family, FitInfo, Kit, Pattern, PatternMeta, SpokenWord, StageLike, TextPolicy } from "./pattern.ts";
 export { order, reject, repick, score, selectAll } from "./select.ts";
 export type { Entry, Pick, Ranked, Rejected, SelectCtx, Slot } from "./select.ts";
-export { BRIDGE_KIND, cyclingText, dressAll, energyOf, SEAM_KINDS, seamKinds, seamSpots, STILL_BG } from "./transitions.ts";
+export { BRIDGE_KIND, cyclingText, dressAll, energyOf, SEAM_KINDS, seamKinds, seamPool, seamsAllowed, seamSpots, STILL_BG } from "./transitions.ts";
 export type { Spot } from "./transitions.ts";
 export { catalog } from "./catalog.ts";
 export { build, contentHash, layout, MARK } from "./assemble.ts";

package/packages/director/src/pattern.ts

@@ -71,6 +71,8 @@ export interface Kit {
   hits: number[];
   /** 들리는 낱말 시각(장면 안 초) — kf narrate 를 지났을 때만 */
   say: SpokenWord[];
+  /** 자막 줄(장면 안 초) — 낱말 시각이 없는 프로젝트(목소리 없이 자막만)에서 항목이 말해지는 자리를 어림한다 */
+  lines: SpokenWord[];
   /** 테마 슬롯(themes/<id>/slots.ts) — 테마가 비운 자리는 패턴 기본으로 그린다 */
   slots: ThemeSlots;
   /** 감독이 dress 바탕·경계 덮기를 건 무대. 감싸개가 paint 다음에 stage.tick 을 부르니 패턴은 부르지 않는다 */

package/packages/director/src/scene.ts

@@ -24,19 +24,27 @@ type MakeStage = (root: HTMLElement, ctx: SceneCtx, o: { panel?: boolean; dress?
 
 interface Line {
   scene: string;
+  text: string;
+  from?: number;
+  to?: number;
   words?: { text: string; from: number; to: number }[];
 }
 
 // 패턴이 박에 붙일 때 쓰는 간격 — 장면 문법 예시와 같은 값이라 예시에서 본 그림이 그대로 나온다
 const HIT_GAP = 0.3;
 
-// captions.json 의 낱말 시각은 영상 기준 초 — 장면 안 초로 옮긴다
-function wordsOf(glob: Record<string, unknown> | undefined, ctx: SceneCtx): SpokenWord[] {
+// captions.json 의 시각은 영상 기준 초 — 장면 안 초로 옮긴다
+function linesOf(glob: Record<string, unknown> | undefined, ctx: SceneCtx): Line[] {
   const lines = (Object.values(glob ?? {})[0] ?? []) as Line[];
-  if (!Array.isArray(lines)) return [];
-  return lines.filter((l) => l.scene === ctx.id).flatMap((l) => (l.words ?? []).map((w) => ({ text: w.text, from: w.from - ctx.from, to: w.to - ctx.from })));
+  return Array.isArray(lines) ? lines.filter((l) => l.scene === ctx.id) : [];
 }
 
+const wordsOf = (lines: Line[], ctx: SceneCtx): SpokenWord[] => lines.flatMap((l) => (l.words ?? []).map((w) => ({ text: w.text, from: w.from - ctx.from, to: w.to - ctx.from })));
+
+// 낱말 시각 없이 줄 시각만 있는 자막(목소리 없이 자막만 단 프로젝트)
+const timedLines = (lines: Line[], ctx: SceneCtx): SpokenWord[] =>
+  lines.flatMap((l) => (l.from !== undefined && l.to !== undefined ? [{ text: l.text, from: l.from - ctx.from, to: l.to - ctx.from }] : []));
+
 export function directed(pattern: Pattern<any>, d: Directed, deps: { makeStage: MakeStage; captions?: Record<string, unknown> }) {
   return {
     build(root: HTMLElement, ctx: SceneCtx) {
@@ -50,7 +58,8 @@ export function directed(pattern: Pattern<any>, d: Directed, deps: { makeStage:
         stage.box.prepend(layer);
         surface = slots.surface(layer, { ctx, seed: `${d.seed}:surface` });
       }
-      const kit: Kit = { seed: d.seed, hits: hitTimes(ctx, HIT_GAP), say: wordsOf(deps.captions, ctx), slots, stage, policy: d.policy, first: d.first, last: d.last, loop: d.loop };
+      const lines = linesOf(deps.captions, ctx);
+      const kit: Kit = { seed: d.seed, hits: hitTimes(ctx, HIT_GAP), say: wordsOf(lines, ctx), lines: timedLines(lines, ctx), slots, stage, policy: d.policy, first: d.first, last: d.last, loop: d.loop };
       const paint = pattern.build(stage.cam, ctx, d.content, kit);
       return (t: number) => {
         surface?.(t);

package/packages/director/src/transitions.ts

@@ -6,6 +6,7 @@ import type { Energy } from "./pattern.ts";
 // 장면 사이 — 이음매(3D 전환 장면)를 어디에 몇 개 넣을지, 그 종류, 나머지 경계의 덮기, 장면마다의 바탕.
 // 이음매 기본은 dive, 같은 전환을 잇달아 쓰지 않는다. 덮기·바탕은 연출 수 메뉴(pickDress)의 규칙을 그대로 따른다
 // (이음매·드롭으로 들어가는 경계·1.2초 아래 장면엔 안 덮는다, 이어지는 장면은 다른 바탕).
+// 테마가 허용 목록(theme.json transitions — 덮기·이음매 이름)을 주면 그 안에서만 고른다. 허용한 이음매가 없으면 이음매를 안 넣는다(컷).
 
 export interface BeatsLite {
   sections?: { t: number; kind: string; strength?: number }[];
@@ -66,6 +67,16 @@ export function seamSpots(types: readonly string[], spaces: readonly ("2d" | "3d
 
 export const SEAM_KINDS = ["dive", "portal", "cards", "zoomOut", "fold", "whip"] as const;
 
+/** 고를 수 있는 이음매 종류 — 허용 목록이 없으면 SEAM_KINDS, 있으면 그 안의 것(gl:·smooth: 전환도 이름을 적으면 든다) */
+export function seamPool(allow?: readonly string[] | null): string[] {
+  if (!allow) return [...SEAM_KINDS];
+  return [...SEAM_KINDS, ...allow.filter((k) => /^(gl|smooth):/.test(k))].filter((k) => allow.includes(k));
+}
+
+/** 이음매를 하나라도 넣을 수 있나 — 공간 잇기(rise·land)도 허용 목록을 따른다 */
+export const seamsAllowed = (allow?: readonly string[] | null): boolean =>
+  !allow || seamPool(allow).length > 0 || Object.values(BRIDGE_KIND).some((k) => allow.includes(k));
+
 /** 2D↔3D 경계의 공간 잇기 — 2D→3D 는 주인공 상자가 3D 블록으로 일어서고(rise), 3D→2D 는 한 평면에 내려앉는다(land).
  * 이 판의 transition3d 에 아직 없으면 dive 로(장면이 모르는 kind 로 던지지 않게) */
 const known = new Set<string>(TRANSITIONS_3D);
@@ -75,18 +86,20 @@ export const BRIDGE_KIND = { up: known.has("rise") ? "rise" : "dive", down: know
  * 이음매 종류 — 공간 잇기 자리는 BRIDGE_KIND, 나머지 첫째는 틀이 정한 것(기본 dive), 다음부터는 씨앗으로 앞과 다른 것.
  * failed 는 kf check 에서 떨어진 종류(이음매 차례 번호로)
  */
-export function seamKinds(spots: readonly Spot[], seed: string, first = "dive", failed: Record<number, string[]> = {}): string[] {
+export function seamKinds(spots: readonly Spot[], seed: string, first = "dive", failed: Record<number, string[]> = {}, allow?: readonly string[] | null): string[] {
+  const kinds = seamPool(allow);
+  const lead = kinds.includes(first) ? first : (kinds[0] ?? first);
   const out: string[] = [];
   let plain = 0;
   for (const [i, sp] of spots.entries()) {
     const bad = new Set([out[i - 1], ...(failed[i] ?? [])]);
-    if (sp.bridge && !(failed[i] ?? []).includes(BRIDGE_KIND[sp.bridge])) {
+    if (sp.bridge && !(failed[i] ?? []).includes(BRIDGE_KIND[sp.bridge]) && (!allow || allow.includes(BRIDGE_KIND[sp.bridge]))) {
       out.push(BRIDGE_KIND[sp.bridge]);
       continue;
     }
-    const pool = SEAM_KINDS.filter((k) => !bad.has(k));
-    if (plain++ === 0 && !bad.has(first)) out.push(first);
-    else out.push(pool.length ? pool[Math.floor(rand(`${seed}|seam`, i) * pool.length)] : first);
+    const pool = kinds.filter((k) => !bad.has(k));
+    if (plain++ === 0 && !bad.has(lead)) out.push(lead);
+    else out.push(pool.length ? pool[Math.floor(rand(`${seed}|seam`, i) * pool.length)] : lead);
   }
   return out;
 }
@@ -100,9 +113,9 @@ export interface Placed {
 /** 바탕 정지 — 움직이는 것은 다 내용 하나를 뜻해야 해서 바탕 수(햇살·집중선·모눈·빛 방울)는 감독 장면에 걸지 않는다 */
 export const STILL_BG = "still";
 
-/** 장면마다 글 수·경계 덮기 — 연출 수 메뉴의 고름 그대로(같은 씨앗이면 같은 고름), 바탕은 정지 */
-export function dressAll(seed: string, scenes: readonly Placed[], moves: Bundle | undefined, theme: string | null): Dress[] {
-  return pickDress(seed, scenes, bundleFor(moves, theme ?? undefined)).map((d) => ({ ...d, bg: STILL_BG }));
+/** 장면마다 글 수·경계 덮기 — 연출 수 메뉴의 고름 그대로(같은 씨앗이면 같은 고름), 바탕은 정지. allow 는 테마가 허용한 전환 */
+export function dressAll(seed: string, scenes: readonly Placed[], moves: Bundle | undefined, theme: string | null, allow?: readonly string[] | null): Dress[] {
+  return pickDress(seed, scenes, bundleFor(moves, theme ?? undefined, allow)).map((d) => ({ ...d, bg: STILL_BG }));
 }
 
 // 감독 기본이 쓰는 글 수 — 낱말을 돌려 띄우되 자르지 않고(slamWords 는 긴 낱말이 화면 끝을 넘는다) 겹쳐 흐리지 않는 것(echoStack·ransom 은 겹친 벌이 장식이 된다)

package/packages/motion/src/enter.ts

@@ -1,4 +1,4 @@
-import { clamp, emit, progress, rand, spring, toEase, type Ease, type EaseName, type Style, safeTime } from "@kasaframe/core";
+import { clamp, cue, emit, progress, rand, spring, toEase, type Ease, type EaseName, type SfxRole, type Style, safeTime } from "@kasaframe/core";
 
 export type MoveName = "fade" | "rise" | "drop" | "pop" | "blurIn" | "scaleIn" | "maskWipe" | "slide";
 export type Side = "left" | "right" | "top" | "bottom";
@@ -72,6 +72,9 @@ function check(name: string): MoveName {
   return name as MoveName;
 }
 
+// 등장 소리 — 스며 나오는 것(fade·blurIn)은 소리 없이, 톡 튀어나오는 pop 은 붙기, 위에서 떨어지는 drop 은 착지. 낱낱이 나타나는 것이라 잔소리(minor)
+const ENTER_SFX: Partial<Record<MoveName, SfxRole>> = { rise: "appear", drop: "land", pop: "stick", scaleIn: "appear", maskWipe: "appear", slide: "appear" };
+
 export function enter(name: MoveName, t: number, opts: MoveOpts = {}): Style {
   t = safeTime(t);
   const n = check(name);
@@ -80,6 +83,9 @@ export function enter(name: MoveName, t: number, opts: MoveOpts = {}): Style {
   const p = progress(t, at, dur);
   const e = toEase(opts.ease, n === "pop" ? (x) => x : undefined)(p);
   if (opts.emit !== false && p > 0 && p < 1) emit({ kind: "move", source: opts.source ?? n, scene: opts.scene, name: `enter:${n}`, value: 1 });
+  const role = ENTER_SFX[n];
+  // 같은 부품이 여러 칸을 늦춰 세우면(stagger) 칸마다 자리가 달라 하나씩 남는다
+  if (role && opts.emit !== false) cue(role, t - at, { source: `${opts.source ?? n}@${at.toFixed(3)}`, scene: opts.scene, minor: true });
   return shape(n, p, e, t - at, opts);
 }
 

package/packages/motion/src/impact.ts

@@ -1,4 +1,4 @@
-import { clamp, emit, noise1, progress, toEase, type Beats, type MotionRules, type PulseOpts, type Style, safeTime } from "@kasaframe/core";
+import { clamp, cue, emit, noise1, progress, toEase, type Beats, type MotionRules, type PulseOpts, type Style, safeTime } from "@kasaframe/core";
 
 interface Tagged {
   source?: string;
@@ -63,7 +63,10 @@ export function dropBurst(t: number, opts: DropBurstOpts): DropBurstState {
   const local = t - at;
   const p = progress(t, at, 0.9);
   const flash = local < 0 ? 0 : local < 0.04 ? 1 : clamp(1 - (local - 0.04) / 0.22) ** 2;
-  if (opts.emit !== false) emit({ kind: "flash", source, scene: opts.scene, value: flash });
+  if (opts.emit !== false) {
+    emit({ kind: "flash", source, scene: opts.scene, value: flash });
+    cue("drop", local, { source, scene: opts.scene });
+  }
   const rp = toEase("outCubic")(progress(t, at, 0.7));
   const ring = local < 0 ? { scale: 0, opacity: 0 } : { scale: 0.2 + 2.6 * rp, opacity: (1 - rp) * 0.9 };
   const kick = local < 0 ? 0 : Math.exp(-local / 0.12) * Math.cos(local * 28);

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

@@ -1,7 +1,7 @@
-import type { SceneCtx } from "@kasaframe/core";
+import { clamp, type SceneCtx } from "@kasaframe/core";
 import { brushWipe } from "./brushWipe.ts";
 import { echoStack } from "./echoStack.ts";
-import { div } from "./fit.ts";
+import { div, mark } from "./fit.ts";
 import { flood } from "./flood.ts";
 import { ghostStack } from "./ghostStack.ts";
 import { gridFloor } from "./gridFloor.ts";
@@ -164,6 +164,9 @@ export function dressText(name: string, el: HTMLElement, ctx: SceneCtx, o: { wor
   }
 }
 
+// 짧은 페이드 한쪽 길이 — 경계 양쪽 합쳐 0.3초
+const FADE = 0.15;
+
 /**
  * 장면 경계를 걸치는 덮기 — out 은 장면 끝에서 덮고, in 은 다음 장면 처음에 걷힌다. 다 덮인 채 서 있는 시간은 0.05초 안팎 —
  * 한 색 화면이 0.1초를 넘으면 멈춤 검사(frame.freeze)에 걸린다. 조리개는 끝까지 닫지 않고 바늘구멍에서 되돌아 연다. 두 장면이 경계의 영상 시각을 같은 씨앗으로 써서
@@ -181,6 +184,16 @@ export function dressWipe(name: string, el: HTMLElement, ctx: SceneCtx, side: "i
     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 "fade": {
+      // 바탕색 막이 0.15초 짙어졌다 걷힌다 — 끝까지 덮지 않아 한 색 화면이 서지 않는다
+      const veil = div(el.ownerDocument, `position:absolute;inset:0;background:${color(ctx, "bg", "#000000")};opacity:0`);
+      el.append(veil);
+      return (t) => {
+        const k = side === "out" ? clamp((t - (B - FADE)) / FADE) : 1 - clamp(t / FADE);
+        veil.style.opacity = (0.9 * k).toFixed(3);
+        mark("fade", ctx.id, k > 0);
+      };
+    }
     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 });

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

@@ -27,6 +27,7 @@ export const MENU: readonly MenuItem[] = [
   { name: "neonSign", kind: "text", does: "네온 관 글자가 시동 걸리듯 깜빡이다 켜진다", example: "neonSign" },
   { name: "ledBoard", kind: "text", does: "LED 점 글판에 한 칸씩 찍힌다", example: "ledBoard" },
   { name: "none", kind: "wipe", does: "덮지 않고 바로 컷" },
+  { name: "fade", kind: "wipe", does: "바탕색으로 잠깐 옅어졌다 돌아온다(경계 양쪽 0.15초씩) — 큰 면이 화면을 쓸지 않는 조용한 경계" },
   { name: "brushWipe", kind: "wipe", does: "붓 획 띠가 번갈아 덮었다가 꼬리가 빠지며 걷힌다", example: "brushWipe" },
   { name: "irisBlades", kind: "wipe", does: "여섯 날 조리개가 닫혔다 열린다", example: "irisBlades" },
   { name: "flood", kind: "wipe", does: "가운데 점이 화면을 넘치게 덮었다가 오므라든다", example: "flood" },
@@ -51,7 +52,7 @@ const BASE: Required<Pool> = { bg: ["still"], text: ["bigWord", "echoStack", "sp
 // 테마마다 비유에 맞는 수 — 테마를 고르면 용도 묶음보다 앞에 둔다(테마 효과와 결이 같은 것만)
 export const THEME_POOLS: Readonly<Record<string, Pool>> = {
   "debug-hud": { text: ["splitFlap", "ledBoard", "ghostStack"], wipe: ["irisBlades", "flood"] },
-  "og-measure": { text: ["splitFlap", "ghostStack", "echoStack"], wipe: ["irisBlades", "flood"] },
+  "og-measure": { text: ["splitFlap", "ghostStack", "echoStack"], wipe: ["fade"] },
   "kasaterm-cells": { text: ["ledBoard", "splitFlap", "slamWords"], wipe: ["flood", "irisBlades"] },
   "kawaii-sticker": { text: ["ransomLetters", "slamWords", "echoStack"], wipe: ["brushWipe", "flood"] },
   "riso-zine": { text: ["ransomLetters", "echoStack", "slamWords"], wipe: ["brushWipe", "flood"] },
@@ -62,21 +63,26 @@ export const THEME_POOLS: Readonly<Record<string, Pool>> = {
 
 const known = (kind: DressKind) => (n: string) => menuItem(n)?.kind === kind;
 
-/** 틀 묶음 + 테마 묶음 → 한 벌. 테마 수를 앞에, 메뉴에 없는 이름은 버린다 */
-export function bundleFor(tpl?: Bundle, theme?: string): Required<Bundle> {
+/**
+ * 틀 묶음 + 테마 묶음 → 한 벌. 테마 수를 앞에, 메뉴에 없는 이름은 버린다.
+ * allow 는 테마가 허용한 경계 전환(theme.json transitions) — 주면 덮기는 그 안에서만, 남는 게 없으면 컷(none)
+ */
+export function bundleFor(tpl?: Bundle, theme?: string, allow?: readonly string[] | null): Required<Bundle> {
   // 변주 이름(<세계>/<변주>)이면 그 세계 묶음
   const th = theme ? THEME_POOLS[theme.split("/")[0]] : undefined;
   const merge = (kind: DressKind, ...lists: (string[] | undefined)[]) => [...new Set(lists.flatMap((l) => l ?? []))].filter(known(kind));
+  const allowed = (list: string[]) => (allow ? list.filter((n) => allow.includes(n)) : list);
   const roles: Record<string, Pool> = {};
   for (const [role, p] of Object.entries(tpl?.roles ?? {})) {
     // 역할 몫은 틀이 이유를 대고 고른 것(훅은 첫 프레임부터 꽉 차는 글) — 테마 수는 그 뒤에 섞지 않는다
-    roles[role] = { bg: p.bg?.filter(known("bg")), text: p.text?.filter(known("text")), wipe: p.wipe?.filter(known("wipe")) };
+    roles[role] = { bg: p.bg?.filter(known("bg")), text: p.text?.filter(known("text")), wipe: p.wipe && allowed(p.wipe.filter(known("wipe"))) };
   }
+  const wipe = allowed(merge("wipe", th?.wipe, tpl?.wipe ?? BASE.wipe));
   const bg = merge("bg", th?.bg, tpl?.bg ?? BASE.bg);
   return {
     bg: bg.length ? bg : BASE.bg,
     text: merge("text", th?.text, tpl?.text ?? BASE.text),
-    wipe: merge("wipe", th?.wipe, tpl?.wipe ?? BASE.wipe),
+    wipe: wipe.length || !allow ? wipe : ["none"],
     roles,
   };
 }

package/packages/motion/src/transition.ts

@@ -1,4 +1,4 @@
-import { clamp, emit, progress, toEase, type Ease, type EaseName, type Style, safeTime } from "@kasaframe/core";
+import { clamp, cue, emit, progress, toEase, type Ease, type EaseName, type Style, safeTime } from "@kasaframe/core";
 
 export type TransitionName = "whip" | "zoomThrough" | "slide" | "matchCut" | "crossfade";
 
@@ -43,6 +43,8 @@ export function transition(name: TransitionName, t: number, opts: TransitionOpts
   const sx = dir === "left" ? -1 : dir === "right" ? 1 : 0;
   const sy = dir === "up" ? -1 : dir === "down" ? 1 : 0;
   if (opts.emit !== false && raw > 0 && raw < 1) emit({ kind: "move", source: opts.source ?? name, scene: opts.scene, name: `transition:${name}`, value: 1 });
+  // 끊어 잇기(matchCut)·겹쳐 바꾸기(crossfade)는 소리 없이 — 휙 지나가는 것만
+  if (opts.emit !== false && name !== "matchCut" && name !== "crossfade") cue("whoosh", t - opts.at, { source: opts.source ?? name, scene: opts.scene });
   const both = raw > 0 && raw < 1;
   switch (name) {
     case "whip": {

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

@@ -1,5 +1,5 @@
 import { onSeek } from "@kasaframe/adapters";
-import { clamp, emit, frameSample, rand, safeTime, type BeatGrid, type KfStyle, type SceneCtx } from "@kasaframe/core";
+import { clamp, cue, emit, frameSample, rand, safeTime, type BeatGrid, type KfStyle, type SceneCtx } from "@kasaframe/core";
 import { FIT, TRANSITIONS_3D, arrivalsOn, durOf, hump, rawProgress, resolveTiming, type FoldStyle, type Timing, type TimingOpts, type Transition3dName, type WindowRect } from "./rig.ts";
 import { camera, inPaint, makeScreen, placeholder, sharedRenderer, NO_FX, type CamFx, type Kit, type KindRun, type Palette, type Screen, type Source } from "./world.ts";
 import { liveNeighbors, type LiveProject } from "./live.ts";
@@ -206,6 +206,8 @@ export function transition3d(root: HTMLElement, ctxOrOpts?: SceneCtx | Transitio
     paint(t);
     const u = rawProgress(t, timing);
     if (o.emit !== false && u > 0 && u < 1) emit({ kind: "move", source, scene, name: `transition3d:${kind}`, value: 1 });
+    // 넘어가기 시작하는 순간(화면이 여럿이면 화면마다)에 휙 — 장면 앞 한 프레임에서 시작하는 기본 구간은 장면 시작으로
+    if (o.emit !== false) for (const a of arrivals.length > 1 ? arrivals.slice(0, -1) : [timing.at]) cue("whoosh", t - Math.max(0, a), { source: `${source}:${Math.max(0, a).toFixed(3)}`, scene });
   }) as Transition3dDraw;
   // seek 의 그리기 단계 뒤 — 영상은 엔진이 시각을 맞춘 뒤, DOM 은 이번 DOM 으로 찍힌 스냅숏(paint 이벤트) 안에서 올리고 같은 t 로 다시 그린다.
   // React 장면은 첫 seek 에서야 지어져 페이지 ready 가 그림을 못 기다리므로 여기서 받는다

package/packages/motion/src/transition3d/live.ts

@@ -1,4 +1,4 @@
-import { createBeats, silentBeats, type SceneCtx } from "@kasaframe/core";
+import { createBeats, silentBeats, withoutSfx, type SceneCtx } from "@kasaframe/core";
 import type { KfProjectJson, KfSceneEntry, SceneModule } from "@kasaframe/adapters";
 import { reactScene } from "@kasaframe/adapters/react";
 import type { LiveDom, Source } from "./world.ts";
@@ -42,9 +42,11 @@ export function sceneSource(mod: SceneModule, ctx: SceneCtx, entry: Pick<KfScene
         from: entry.from,
         dur: entry.dur,
         beats: ctx.beats?.data ? createBeats(ctx.beats.data, entry.from) : silentBeats(entry.dur),
+        sfx: () => {},
       };
-      if (mod.react) return reactScene(box, mod.react, sub);
-      return mod.build?.(box, sub) ?? undefined;
+      // 한 벌 더 그린 장면은 소리를 안 낸다 — 진짜 장면이 이미 남겼다
+      const draw = mod.react ? reactScene(box, mod.react, sub) : mod.build?.(box, sub);
+      return draw ? (t: number) => withoutSfx(() => draw(t)) : undefined;
     },
     time,
     still,

package/packages/patterns/src/bars/rank.ts

@@ -1,6 +1,6 @@
 import { applyStyle, clamp, combine } from "@kasaframe/core";
 import { fitSize, textEm } from "@kasaframe/motion/moves";
-import { area, beatStops, decimalsOf, factRoll, glider, node, slotsOf, spaced, moving } from "../kit.ts";
+import { area, decimalsOf, factRoll, glider, moving, node, slotsOf, spaced } from "../kit.ts";
 import { cssColor, objectFor } from "../objects.ts";
 import type { Pattern } from "../types.ts";
 
@@ -12,13 +12,13 @@ export interface BarsContent {
 }
 
 /**
- * 막대가 순위대로 박마다 한 줄씩 자라고 값이 같은 진행도로 굴러 오른다(막대 길이 = 값). 다 자라면 짚개가 강조 줄과 다른 줄을 번갈아 짚는다.
+ * 막대가 순위대로 박마다 한 줄씩 자라고 값이 같은 진행도로 굴러 오른다(막대 길이 = 값). 다 자라면 짚개가 강조 줄부터 짚는다(머무는 테마는 목소리가 다른 줄 이름을 말할 때만 그리로).
  * 단위·이름이 객체 사전의 막대 물체면(지연 ms) 그 색·모서리. 자라는 시각을 장면 끝까지 펴서 쉬지 않는 몫을 막대가 진다.
  */
 const pattern: Pattern<BarsContent> = {
   id: "bars.rank",
   type: "bars",
-  does: "막대가 순위대로 박마다 자라고 값이 굴러 오른다, 다 자라면 짚개가 강조 줄과 다른 줄을 번갈아 짚는다",
+  does: "막대가 순위대로 박마다 자라고 값이 굴러 오른다, 다 자라면 짚개가 강조 줄부터 짚는다",
   energy: ["mid"],
   family: "grow",
   camera: ["none"],
@@ -93,10 +93,9 @@ const pattern: Pattern<BarsContent> = {
     });
     const hotLine = lines[Math.max(0, hot)];
     kit.stage?.hero(hotLine.val);
-    // 다 자라면 짚개가 강조 줄 ↔ 다른 줄을 박마다 번갈아 짚는다 — 강조 줄과 견주는 몫
-    const point = glider(host, [hotLine.row, ...lines.filter((L) => L !== hotLine).map((L) => L.row)], { hub: true, pad: 0.04 });
+    // 다 자라면 짚개가 강조 줄부터 짚는다 — 머무는 테마는 목소리가 다른 줄 이름을 말할 때만 그리로
+    const point = glider(host, [hotLine, ...lines.filter((L) => L !== hotLine)].map((L) => ({ el: L.row, text: L.r.label })), { kit, ctx, from: hotAt - 0.1, pad: 0.04 });
     const hotLand = slots.land(hotLine.val, { ctx, at: hotAt, seed: `${kit.seed}:hot` });
-    const stops = beatStops(kit.hits, hotAt - 0.1, ctx.dur);
 
     return (t: number) => {
       moving("bars.rank", ctx);
@@ -111,7 +110,7 @@ const pattern: Pattern<BarsContent> = {
         L.val.style.left = `${labelW + trackW * (L.r.value / max) * roll.p + 16 * u}px`;
         applyStyle(L.val, L.i === hotLine.i ? combine(L.landed(t), hotLand(t)) : L.landed(t));
       }
-      point(t, stops);
+      point(t);
     };
   },
 };

package/packages/patterns/src/before-after/shrink.ts

@@ -1,6 +1,6 @@
 import { applyStyle, clamp, spring } from "@kasaframe/core";
 import { fitSize } from "@kasaframe/motion/moves";
-import { ACCENT_TEXT, area, beatStops, decimalsOf, fmt, glider, moving, node, slotsOf } from "../kit.ts";
+import { ACCENT_TEXT, area, decimalsOf, fmt, glider, moving, node, slotsOf } from "../kit.ts";
 import { cssColor, objectFor } from "../objects.ts";
 import type { BeforeAfter } from "./strike.ts";
 import type { Pattern } from "../types.ts";
@@ -92,8 +92,7 @@ const pattern: Pattern<BeforeAfter> = {
     const moveFrom = fillEnd + 0.15;
     const moveEnd = moveFrom + (count - 1) / rate;
     const landedAt = moveEnd + 0.05;
-    const stops = beatStops(kit.hits, landedAt + 0.1, ctx.dur);
-    const point = glider(host, [cells[0], label, val], { hub: true });
+    const point = glider(host, [{ el: cells[0] }, { el: label, text: after.label }, { el: val, text: fmt(after.value!, dec) }], { kit, ctx, from: landedAt + 0.1 });
     const writeA = slots.write(label, { ctx, text: before.label, at: 0, dur: 0.3, seed: `${kit.seed}:a` });
     const landed = slots.land(cells[0], { ctx, at: landedAt, seed: `${kit.seed}:land` });
 
@@ -119,7 +118,7 @@ const pattern: Pattern<BeforeAfter> = {
       // 라벨은 전 → 후로 바뀐다
       if (t >= landedAt) label.textContent = after.label;
       else writeA(t);
-      point(t, stops);
+      point(t);
     };
   },
 };

package/packages/patterns/src/before-after/strike.ts

@@ -1,6 +1,6 @@
 import { applyStyle, clamp, combine, ease, progress, spring } from "@kasaframe/core";
 import { textEm } from "@kasaframe/motion/moves";
-import { ACCENT_TEXT, area, beatStops, cameraOk, decimalsOf, factRoll, glider, node, slotsOf, moving } from "../kit.ts";
+import { ACCENT_TEXT, area, cameraOk, decimalsOf, factRoll, glider, moving, node, slotsOf } from "../kit.ts";
 import type { Pattern } from "../types.ts";
 
 interface Side {
@@ -92,9 +92,8 @@ const pattern: Pattern<BeforeAfter> = {
     const writeChange = change ? slots.write(change, { ctx, text: c.change!, at: changeAt, dur: 0.3, seed: `${kit.seed}:ch` }) : null;
     const landed = slots.land(afterNum, { ctx, at: land, seed: `${kit.seed}:land` });
     if (cameraOk(ctx)) kit.stage?.camera.pushIn(land, { to: afterBox, scale: 1.1, dur: Math.max(0.6, ctx.dur - land) });
-    // 앉은 뒤엔 짚개가 후 값 ↔ 바뀐 정도·전 값을 박마다 번갈아 짚는다
-    const point = glider(host, [afterBox, ...(change ? [change] : []), beforeBox], { hub: true });
-    const stops = beatStops(kit.hits, land + 0.1, ctx.dur);
+    // 앉으면 짚개가 후 값부터 짚는다 — 머무는 테마는 목소리가 바뀐 정도·전 값을 말할 때만 그리로
+    const point = glider(host, [{ el: afterBox, text: afterText }, ...(change ? [{ el: change, text: c.change }] : []), { el: beforeBox, text: beforeText }], { kit, ctx, from: land + 0.1 });
 
     return (t: number) => {
       moving("before-after.strike", ctx);
@@ -116,7 +115,7 @@ const pattern: Pattern<BeforeAfter> = {
       afterNum.textContent = shown;
       // 굴리는 동안 긴 글은 같은 폭에 줄여 넣는다 — 상자가 출렁이지 않게
       afterNum.style.fontSize = `${Math.round(bigPx * Math.min(1, textEm(afterText) / textEm(shown)))}px`;
-      point(t, stops);
+      point(t);
       applyStyle(afterNum, combine({ y: (1 - ease.outExpo(progress(t, openAt, 0.35))) * bigPx * 1.1 }, landed(t)));
     };
   },