kasaframe 0.1.4 → 0.1.6

package/packages/patterns/src/kit.ts

@@ -2,6 +2,8 @@ import { clamp, ease, progress, spring, type SceneCtx, type Style } from "@kasaf
 import { mark } from "@kasaframe/motion/moves";
 import { typeDuration, typeText } from "@kasaframe/motion";
 import { partial } from "@kasaframe/themes/slotkit";
+import type { MarkBox, MarkPaint } from "@kasaframe/themes/slots";
+import { keyCue, rollCues, slamCue, stopCues, withSfx } from "./sfx.ts";
 import type { Kit, ThemeSlots } from "./types.ts";
 
 // 패턴들이 같이 쓰는 몫. 모듈 맨 위에서 DOM 을 만지지 않는다 — 감독이 Node 에서 meta·fits 를 읽는다.
@@ -58,12 +60,40 @@ export function inkLike(ctx: SceneCtx): boolean {
   return !Number.isFinite(a) || !Number.isFinite(b) || (hi + 0.05) / (lo + 0.05) < 3;
 }
 
+// 글을 짚는 겹의 칠 — 강조색 글. 강조색 글이 본문 글과 같은 테마(HUD)면 반전 칸으로(같은 색으로 채우면 아무것도 안 바뀐다)
+const readCss = (ctx: SceneCtx): string => (inkLike(ctx) ? "background:var(--kf-accent);color:var(--kf-on-accent)" : `color:${ACCENT_TEXT}`);
+
+/**
+ * 다시 짚기 진행도 — 정지점 사이마다 0→1→0 으로 박마다 한 번 차올랐다 빠진다. 마지막 사이(장면 끝)는 차오르기만 해 끝 프레임에 다 짚혀 있다.
+ * 첫 정지점 전엔 0. 훑는 짚개를 쓰는 테마에서 짚을 대상이 하나뿐인 장면(짚개 없음)이 그 글을 박마다 강조로 채웠다 비워 쉬지 않는 몫
+ */
+export function reread(t: number, stops: readonly number[]): number {
+  if (stops.length < 2 || t < stops[0]) return 0;
+  let j = 0;
+  while (j + 2 < stops.length && stops[j + 1] <= t) j++;
+  const p = clamp((t - stops[j]) / Math.max(1e-3, stops[j + 1] - stops[j]));
+  return j === stops.length - 2 ? p : 1 - Math.abs(2 * p - 1);
+}
+
+/**
+ * 글 상자 el(position:relative) 위에 같은 글의 강조 겹(readCss) — p 만큼 아래부터 글 전체에 차오른다(reread 로 다시 짚기).
+ * 왼쪽부터 짚으면 빈칸·가는 글자(1·i)를 지나는 동안 화면이 거의 안 바뀌어 멈춘 화면이 된다 — 차오름은 모든 글자를 함께 지난다
+ */
+export function readOver(el: HTMLElement, text: string, ctx: SceneCtx): (p: number) => void {
+  const hi = node(el, `position:absolute;inset:0;${readCss(ctx)};white-space:inherit;text-align:inherit;visibility:hidden;pointer-events:none`, text);
+  return (p) => {
+    const k = clamp(p);
+    hi.style.visibility = k > 0 ? "visible" : "hidden";
+    hi.style.clipPath = `inset(${((1 - k) * 100).toFixed(2)}% 0 0 0)`;
+  };
+}
+
 /**
- * 큰 이름 — 글자마다 가림막 아래에서 올라와 서고(riseAt 부터 each 간격), fill 진행도(0..1)만큼 강조가 왼쪽부터 글자를 짚는다.
- * 강조색 글이 본문 글과 같은 테마(HUD)면 반전 칸으로 — 같은 색으로 채우면 아무것도 안 바뀐다
+ * 큰 이름 — 글자마다 가림막 아래에서 올라와 서고(riseAt 부터 each 간격), fill 진행도(0..1)만큼 강조가 왼쪽부터 글자를 짚는다(readCss).
+ * up 을 주면 강조가 모든 글자에 아래부터 그만큼 차오른다(다시 짚기 — readOver 와 같은 결)
  */
-export function riseName(el: HTMLElement, text: string, ctx: SceneCtx): (t: number, o: { riseAt: number; each: number; fill: number }) => void {
-  const hiCss = inkLike(ctx) ? "background:var(--kf-accent);color:var(--kf-on-accent)" : `color:${ACCENT_TEXT}`;
+export function riseName(el: HTMLElement, text: string, ctx: SceneCtx): (t: number, o: { riseAt: number; each: number; fill: number; up?: number }) => void {
+  const hiCss = readCss(ctx);
   odoStyle(el);
   const glyphs = Array.from(text).map((ch) => {
     const clip = node(el, "display:inline-block;overflow:hidden;padding:0.06em 0 0.12em;margin:-0.06em 0 -0.12em");
@@ -87,9 +117,9 @@ export function riseName(el: HTMLElement, text: string, ctx: SceneCtx): (t: numb
         g.firstChild.remove();
       }
       if (!up) g.dataset.kfOdo = g.dataset.ch ?? "";
-      const k = clamp(fp - i);
+      const k = clamp(o.up ?? fp - i);
       hi.style.visibility = k > 0 ? "visible" : "hidden";
-      hi.style.clipPath = `inset(0 ${((1 - k) * 100).toFixed(2)}% 0 0)`;
+      hi.style.clipPath = o.up === undefined ? `inset(0 ${((1 - k) * 100).toFixed(2)}% 0 0)` : `inset(${((1 - k) * 100).toFixed(2)}% 0 0 0)`;
     });
   };
 }
@@ -151,16 +181,68 @@ export function odometer(el: HTMLElement, o: { template: string; decimals: numbe
   };
 }
 
+/** 테마 짚음 슬롯을 이 장면에 묶은 것 — 칸 요소를 받아 칠하고 자리 함수를 준다 */
+export type Marker = (el: HTMLElement) => MarkPaint;
+
+/** 테마가 짚는 칸 모양(mark 슬롯)을 채웠으면 그것, 아니면 null — 짚개·반전 짚음이 패턴 기본(강조색 꽉 찬 칸)으로 그린다 */
+export const markOf = (kit: Kit, ctx: SceneCtx): Marker | null => {
+  const slot = kit.slots.mark;
+  return slot ? (el) => slot(el, { ctx, seed: `${kit.seed}:mark` }) : null;
+};
+
+// 짚는 칸 요소 — 대상 글 뒤에 깔린다(놓는 쪽 상자에 isolation). 칠은 테마 슬롯이나 plainMark 가 한다
+const MARK_CSS = "position:absolute;left:0;top:0;width:0;height:0;z-index:-1;visibility:hidden;pointer-events:none";
+
+// 테마가 비운 짚음 — 강조색 꽉 찬 칸이 크기 그대로 미끄러진다(직선 7 + smoothstep 3 — 훑는 동안 정지점에 닿아 서면 그 사이가 멈춘 화면)
+function plainMark(el: HTMLElement): MarkPaint {
+  el.style.background = "var(--kf-accent)";
+  el.style.borderRadius = "var(--kf-radius-sm)";
+  return {
+    ink: "var(--kf-on-accent)",
+    at(from, to, u) {
+      const a = from ?? to;
+      const e = 0.7 * u + 0.3 * u * u * (3 - 2 * u);
+      const mix = (p: number, q: number) => p + (q - p) * e;
+      return { x: mix(a.x, to.x), y: mix(a.y, to.y), w: mix(a.w, to.w), h: mix(a.h, to.h) };
+    },
+  };
+}
+
+function place(el: HTMLElement, b: MarkBox): void {
+  el.style.transform = `translate(${b.x.toFixed(1)}px, ${b.y.toFixed(1)}px)`;
+  el.style.width = `${b.w.toFixed(1)}px`;
+  el.style.height = `${b.h.toFixed(1)}px`;
+}
+
 /**
  * 반전 짚음 — el(글 상자, position:relative — 쓰기 슬롯이 글을 갈아 끼우는 요소면 그 부모에 건다) 위에 강조색 면 + onAccent 글 겹을 깔고 p 만큼 왼쪽부터 드러낸다.
- * 옅은 형광펜(accentSoft)은 밝은 바탕에서 화면이 바뀐 것으로 안 읽혀 이쪽이 쉬지 않는 몫을 진다
+ * 옅은 형광펜(accentSoft)은 밝은 바탕에서 화면이 바뀐 것으로 안 읽혀 이쪽이 쉬지 않는 몫을 진다.
+ * 테마 짚음(mark)이 있으면 그 칸이 글 뒤에 p 만큼 나타나고(모양은 테마 몫), 칸 위 글은 테마 ink 로
  */
-export function inverseOver(el: HTMLElement, text: string): (p: number) => void {
-  const hi = node(el, "position:absolute;inset:0;background:var(--kf-accent);color:var(--kf-on-accent);white-space:inherit;text-align:inherit;visibility:hidden;pointer-events:none", text);
+export function inverseOver(el: HTMLElement, text: string, mark: Marker | null = null): (p: number) => void {
+  if (!mark) {
+    const hi = node(el, "position:absolute;inset:0;background:var(--kf-accent);color:var(--kf-on-accent);white-space:inherit;text-align:inherit;visibility:hidden;pointer-events:none", text);
+    return (p) => {
+      const k = clamp(p);
+      hi.style.visibility = k > 0 ? "visible" : "hidden";
+      hi.style.clipPath = `inset(0 ${((1 - k) * 100).toFixed(2)}% 0 0)`;
+    };
+  }
+  el.style.isolation = "isolate";
+  const block = node(el, MARK_CSS);
+  const shape = mark(block);
+  const hi = shape.ink ? node(el, `position:absolute;inset:0;color:${shape.ink};white-space:inherit;text-align:inherit;visibility:hidden;pointer-events:none`, text) : null;
   return (p) => {
     const k = clamp(p);
+    const w = el.offsetWidth;
+    const h = el.offsetHeight;
+    const pad = (parseFloat(getComputedStyle(el).fontSize) || 20) * 0.12;
+    const b = shape.at(null, { x: -pad, y: -pad * 0.5, w: w + pad * 2, h: h + pad }, k);
+    block.style.visibility = k > 0 ? "visible" : "hidden";
+    place(block, b);
+    if (!hi) return;
     hi.style.visibility = k > 0 ? "visible" : "hidden";
-    hi.style.clipPath = `inset(0 ${((1 - k) * 100).toFixed(2)}% 0 0)`;
+    hi.style.clipPath = `inset(${b.y.toFixed(1)}px ${(w - b.x - b.w).toFixed(1)}px ${(h - b.y - b.h).toFixed(1)}px ${b.x.toFixed(1)}px)`;
   };
 }
 
@@ -175,6 +257,7 @@ export function sceneDrop(ctx: SceneCtx): number | null {
  * 등장 전엔 opacity 0 이라 그 사이를 다른 움직임이 채워야 한다
  */
 export function slam(t: number, at: number, from = 1.9): Style {
+  slamCue(t, at);
   const lead = 0.16;
   if (t < at - lead) return { opacity: 0 };
   if (t < at) {
@@ -210,9 +293,9 @@ export function fitOnce(el: HTMLElement, maxW: number, maxPx: number, text?: str
 }
 
 /**
- * 짚개의 정지점 — from 뒤의 박을 간격 gap 넘게 골라 쓰고(빈 곳은 고르게 메운다), 마지막 정지점은 장면 끝(to)이다.
- * 끝 프레임에서 칸이 대상에 거의 앉아 있어야 표지·견본 스틸에 반쯤 걸친 띠가 안 찍힌다. 칸은 그 순간까지 움직이니(직선 7) 서지는 않는다.
- * 장면이 길어도 짚개 빠르기는 박이 정한다 — 장면 길이에 비례해 느려지는 차오름은 긴 장면에서 멈춘 화면이 된다
+ * 박 정지점 — from 뒤의 박을 간격 gap 넘게 골라 쓰고(빈 곳은 고르게 메운다), 마지막 정지점은 장면 끝(to)이다.
+ * 끝 프레임에서 옮겨 다니는 틀이 대상에 거의 앉아 있어야 표지·견본 스틸에 반쯤 걸친 틀이 안 찍힌다.
+ * 장면이 길어도 빠르기는 박이 정한다 — 장면 길이에 비례해 느려지는 차오름은 긴 장면에서 멈춘 화면이 된다
  */
 export function beatStops(hits: readonly number[], from: number, to: number, gap = 0.4): number[] {
   const out = [from];
@@ -225,18 +308,13 @@ export function beatStops(hits: readonly number[], from: number, to: number, gap
   return out;
 }
 
-/**
- * 짚개 — 강조색 칸이 대상 사이를 정지점마다 옮겨 다니며 「지금 볼 항」을 짚는다. 정지점 사이를 내내 움직인다(직선 7 + smoothstep 3 —
- * 닿아서 서면 그 사이가 멈춘 화면). 칸은 대상 글 뒤에 깔리고(host 에 isolation), 칸이 앉은 대상 글은 onAccent 로 바뀐다.
- * 대상 자리는 그 프레임에 잰다 — 대상이 굴러가거나 내려앉아도 따라간다
- */
 // 글자를 두 색으로 — over 사각형(글 상자 안 좌표) 안은 띠 위 글색, 밖은 그 글의 원래 색. 글자 모양으로 오려 칠하니 반쯤 겹쳐도 겹친 글자 부분만 바뀐다.
 // 글색(color)은 건드리지 않아 원래 색을 늘 다시 읽을 수 있다. 칠하기 전 인라인 값을 그대로 되돌린다 — 테마 슬롯이 글에 칠한 배경을 지우면
 // 한 번 짚고 지나간 뒤로 그림이 바뀌어 같은 시각이 다르게 그려졌다(frame.nondeterministic)
 const TONE_PROPS = ["-webkit-text-fill-color", "background-image", "background-color", "background-repeat", "background-size", "background-position", "-webkit-background-clip", "background-clip"];
 const toneSaved = new WeakMap<HTMLElement, [string, string, string][]>();
 
-function paintTone(el: HTMLElement, over: { x: number; y: number; w: number; h: number } | null): void {
+function paintTone(el: HTMLElement, over: MarkBox | null, ink = "var(--kf-on-accent)"): void {
   const s = el.style;
   if (!over) {
     const saved = toneSaved.get(el);
@@ -250,7 +328,7 @@ function paintTone(el: HTMLElement, over: { x: number; y: number; w: number; h:
   el.dataset.kfTone = "";
   s.setProperty("-webkit-text-fill-color", "transparent");
   s.backgroundColor = "currentColor";
-  s.backgroundImage = "linear-gradient(var(--kf-on-accent), var(--kf-on-accent))";
+  s.backgroundImage = `linear-gradient(${ink}, ${ink})`;
   s.backgroundRepeat = "no-repeat";
   s.backgroundSize = `${over.w.toFixed(1)}px ${over.h.toFixed(1)}px`;
   s.backgroundPosition = `${over.x.toFixed(1)}px ${over.y.toFixed(1)}px`;
@@ -258,17 +336,22 @@ function paintTone(el: HTMLElement, over: { x: number; y: number; w: number; h:
   s.setProperty("background-clip", "text");
 }
 
-// 대상 안에 바탕이 칠해진 요소가 있나 — 투명·알파 0 이면 없는 것
+// 대상 안에 글 뒤를 가리는 판이 있나 — 바탕이 칠해졌고(투명·알파 0 이면 없는 것) 대상 상자의 절반 넘게 덮는 것만.
+// 판 위 구분선·모서리 눈금처럼 가는 장식(og-measure 의 위 구분선 3px)을 판으로 읽으면 띠는 숫자 뒤에 훤히 보이는데 글은 원래 색으로 남았다.
+// 넓이는 변환 전 크기로 잰다 — 판이 내려앉는 중(scale)이어도 같은 답이 나오게
 function hasPlate(root: HTMLElement): boolean {
+  const area = (el: HTMLElement) => el.offsetWidth * el.offsetHeight;
+  const whole = area(root);
   const els = [root, ...Array.from(root.querySelectorAll<HTMLElement>("*"))];
   return els.some((el) => {
     // 짚개가 글에 칠한 배경(표식 data-kf-tone)은 판이 아니다 — 앞 프레임에 칠했는지와 상관없이 같은 답이 나오게
     if (el.dataset.kfTone !== undefined) return false;
     const cs = getComputedStyle(el);
-    if (cs.backgroundImage !== "none") return true;
     const m = /rgba?\(([^)]+)\)/.exec(cs.backgroundColor);
-    const a = m ? Number(m[1].split(",")[3] ?? 1) : 0;
-    return a > 0.05;
+    const painted = cs.backgroundImage !== "none" || (m ? Number(m[1].split(",")[3] ?? 1) : 0) > 0.05;
+    if (!painted) return false;
+    // SVG 처럼 레이아웃 크기가 없는 것과 아직 자리를 안 잡은 대상은 칠했으면 판으로 둔다
+    return !(el instanceof HTMLElement) || !whole || area(el) >= whole * 0.5;
   });
 }
 
@@ -287,9 +370,145 @@ function leavesOf(root: HTMLElement): HTMLElement[] {
   return out;
 }
 
-export function glider(host: HTMLElement, targets: HTMLElement[], o: { pad?: number; hub?: boolean } = {}): (t: number, stops: readonly number[], until?: number) => void {
+/** 요점 — 그 시각부터 짚개가 내려앉아 머무는 대상 */
+export interface Focus {
+  at: number;
+  el: HTMLElement;
+}
+
+// 낱말·글을 견줄 꼴 — 문장부호를 떼고 소문자로
+const bare = (s: string) => s.toLowerCase().replace(/[^\p{L}\p{N}.]+/gu, " ").trim();
+
+// 목소리 낱말 w 가 글 text 를 말했나 — 낱말이 글의 한 마디이거나 거기에 조사·어미가 붙은 꼴(「캐시가」 = 캐시). 두 글자 아래 마디는 숫자만
+function said(w: string, text: string): boolean {
+  const word = bare(w);
+  if (!word) return false;
+  return bare(text)
+    .split(" ")
+    .some((tk) => (tk.length >= 2 || /^\d/.test(tk)) && (word === tk || (word.startsWith(tk) && word.length - tk.length <= 3) || (tk.startsWith(word) && word.length >= 2)));
+}
+
+/**
+ * 짚을 요점과 그 시각 — 첫 대상(장면이 주인공·강조로 세운 것)에 from 에 내려앉고, 그 뒤엔 목소리가 다른 대상의 글을 말하는 낱말 시각에만
+ * 그리로 옮긴다(주인공 글을 다시 말하면 돌아온다). 나타나는 차례로 훑지 않는다 — 요점이 바뀌지 않으면 머문다.
+ * 대상 글은 다 찍힌 뒤의 글(패턴이 아는 내용)로 견준다 — 찍히는 중인 화면 글로 견주면 시각마다 답이 달라진다.
+ * 짚을 것이 하나뿐이면 빈 목록 — 하나뿐인 것을 짚는 칸은 「지금 볼 것」을 가리키지 못하고 의미 없는 네모로 남는다
+ */
+export function keyPoints(say: readonly { text: string; from: number }[], from: number, points: readonly { el: HTMLElement; text?: string }[]): Focus[] {
+  if (points.length < 2) return [];
+  const out: Focus[] = [{ at: from, el: points[0].el }];
+  for (const w of say) {
+    if (w.from < from) continue;
+    const hit = points.find((p) => p.text && said(w.text, p.text));
+    if (hit && hit.el !== out[out.length - 1].el) out.push({ at: w.from, el: hit.el });
+  }
+  return out;
+}
+
+/** 글 text 가 [from, to) 안에서 말해지는 시각 — 목소리 낱말이 있으면 그 글을 말하는 첫 낱말, 없으면 자막 줄 안에서 그 글이 놓인 자리만큼. 못 찾으면 null */
+export function heardAt(kit: Kit, text: string, from: number, to: number): number | null {
+  if (kit.say.length) return kit.say.find((w) => w.from >= from - 0.05 && w.from < to && said(w.text, text))?.from ?? null;
+  const key = bare(text).split(" ").find((tk) => tk.length >= 2 || /^\d/.test(tk));
+  for (const l of key ? kit.lines : []) {
+    const i = bare(l.text).indexOf(key!);
+    const at = l.from + ((l.to - l.from) * i) / Math.max(1, bare(l.text).length);
+    if (i >= 0 && at >= from - 0.05 && at < to) return at;
+  }
+  return null;
+}
+
+/**
+ * 항목이 말해지는 시각 — 목소리 낱말(kit.say)이 그 글을 말하는 첫 시각, 낱말 시각 없이 자막 줄(kit.lines)만 있으면 줄 안에서 그 글이 놓인 자리만큼.
+ * 못 찾은 항목은 앞뒤로 찾은 항목 사이(처음은 from, 끝은 to)를 고르게 메우고, 하나도 없으면 [from, to] 를 고르게 — 셋 다 박에 붙인다(0.15초 안).
+ * 항목 차례대로 늦어지기만 한다. 감독 장면은 목소리가 길이를 정해 4–9초인데 내용은 2–3초 안에 다 서 — 항목을 말하는 순간에 나눠 세워 그 사이를 메운다
+ */
+export function sayTimes(kit: Kit, texts: readonly (string | undefined)[], from: number, to: number): number[] {
+  const found = texts.map((tx) => (tx ? heardAt(kit, tx, from, to) : null));
+  const out = found.map((x) => (x === null ? NaN : clamp(x, from, to)));
+  // 못 찾은 줄 — 앞 닻(없으면 from)과 뒤 닻(없으면 to) 사이를 고르게
+  for (let i = 0; i < out.length; ) {
+    if (!Number.isNaN(out[i])) {
+      i++;
+      continue;
+    }
+    let j = i;
+    while (j < out.length && Number.isNaN(out[j])) j++;
+    const a = i > 0 ? out[i - 1] : from;
+    const b = j < out.length ? out[j] : to;
+    const lead = i === 0 ? 0 : 1;
+    const span = j - i + lead + (j < out.length ? 1 : 0) - 1;
+    for (let k = i; k < j; k++) out[k] = a + ((b - a) * (k - i + lead)) / Math.max(1, span);
+    i = j;
+  }
+  let last = -Infinity;
+  return out.map((x, i) => {
+    const near = kit.hits.reduce((best, h) => (Math.abs(h - x) < Math.abs(best - x) ? h : best), Infinity);
+    const snapped = found[i] === null && Math.abs(near - x) < 0.15 ? near : x;
+    last = Math.max(snapped, last);
+    return last;
+  });
+}
+
+/**
+ * 지금 말하는 항목 쪽으로 다가가는 카메라 — 장면 첫 프레임부터 첫 항목 쪽으로, 항목이 말해질 때마다 그쪽으로 천천히 다가가 다음 항목까지,
+ * 마지막 항목 뒤엔 장면 끝까지 한 번의 움직임으로 잇는다. 내용이 다 선 뒤 쉬는 구간을 뜻 있는 움직임으로 메운다(다가감의 이유가 그 순간 말하는 것).
+ * 다가갈수록 조금씩 가까이(배율 1.02 씩, 1.08 까지). 머무는 짚개(dwell) 테마만 — 훑는 테마는 짚개가 쉬지 않는 몫을 진다. 카메라를 끈 영상엔 안 건다
+ */
+export function followSpoken(kit: Kit, ctx: SceneCtx, shots: readonly Focus[]): void {
+  if (!cameraOk(ctx) || !kit.stage || !dwells(kit, ctx)) return;
+  const sorted = [...shots].filter((s) => s.at < ctx.dur - 0.2).sort((a, b) => a.at - b.at);
+  if (!sorted.length) return;
+  // 첫 프레임부터 주인공 쪽으로 — 앞 장면의 다가감과 끊김 없이 이어져 한 번으로 센다(틀이 카메라를 프레이즈당 한 번 허락한다). 0 에서 시작하면
+  // 첫 프레임엔 아직 안 움직여 사이가 뜬다. 아직 안 찍힌(빈) 항목 쪽으로 먼저 가면 화면이 비켜 내용이 안전 영역 밖으로 밀린다
+  const hero = kit.stage.cam.querySelector<HTMLElement>("[data-kf-hero]") ?? sorted[0].el;
+  const list = [{ at: -0.05, el: hero }, ...sorted.filter((s) => s.at > 0.05)];
+  // 다음 다가감과 조금 겹쳐 잇는다 — 사이에 한 프레임이라도 서면 검사가 카메라를 두 번 움직인 것으로 센다
+  list.forEach((s, i) => {
+    const end = list[i + 1] ? list[i + 1].at + 0.1 : ctx.dur + 0.1;
+    kit.stage.camera.pushIn(s.at, { to: s.el, scale: Math.min(1.08, 1 + 0.02 * (i + 1)), dur: Math.max(0.4, end - s.at) });
+  });
+}
+
+// 요점 사이 옮김 — 스타일가이드 자리 옮김 300ms. 다음 요점이 그보다 가까우면 닿을 틈을 남기고 더 빨리
+const MOVE = 0.3;
+const REST = 0.03;
+
+/** 짚을 대상 — text 는 다 찍힌 뒤의 글(목소리 낱말과 견준다) */
+export interface Point {
+  el: HTMLElement;
+  text?: string;
+}
+
+/** 테마 짚음이 요점에 머무는 방식(mark 의 dwell)인가 — 칸 모양만 묻는다(붙이지 않는 빈 칸에 칠하게 하고 읽는다) */
+export const dwells = (kit: Kit, ctx: SceneCtx): boolean => !!markOf(kit, ctx)?.(document.createElement("div")).dwell;
+
+/**
+ * 짚개 — 칸이 「지금 볼 것」을 짚는다. 짚기 방식은 테마 짚음(mark)이 고른다:
+ * - 머묾(dwell): 첫 대상(장면이 주인공·강조로 세운 것)에 from 에 내려앉아 머물고, 목소리가 다른 대상의 글을 말할 때만 0.3초에 옮긴다(keyPoints).
+ *   hub 가 아닌 목록(차례로 늘어선 낱말·줄)은 주인공이 없어 짚지 않는다
+ * - 훑기(비운 테마): from 부터 박 정지점(beatStops — to 까지)마다 대상 사이를 내내 옮긴다. hub 면 주인공과 나머지를 번갈아 —
+ *   작은 글 사이를 옮겨 다니면 칸이 조금밖에 안 움직여 멈춘 화면으로 읽힌다. 마지막 정지점(장면 끝)이 주인공이 되게 차례를 맞춘다
+ * 짚을 것이 하나뿐이면 짚지 않는다(의미 없는 네모). until 부터는 걷는다. 칸 모양·옮겨 가는 길·칸 위 글색도 테마 짚음(비우면 강조색 꽉 찬 칸),
+ * 칸은 대상 글 뒤에 깔리고(host 에 isolation) 칸이 덮은 글은 그 짚음의 ink 로 바뀐다. 대상 자리는 그 프레임에 잰다 — 대상이 굴러가거나 내려앉아도 따라간다
+ */
+export function glider(host: HTMLElement, points: readonly Point[], o: { kit: Kit; ctx: SceneCtx; from: number; to?: number; until?: number; hub?: boolean; pad?: number }): (t: number) => void {
+  const hub = o.hub ?? true;
+  if (points.length < 2) return () => {};
   host.style.isolation = "isolate";
-  const block = node(host, "position:absolute;left:0;top:0;width:0;height:0;background:var(--kf-accent);border-radius:var(--kf-radius-sm);z-index:-1;visibility:hidden;pointer-events:none");
+  const block = node(host, MARK_CSS);
+  const shape = markOf(o.kit, o.ctx)?.(block) ?? plainMark(block);
+  const focus = shape.dwell ? (hub ? keyPoints(o.kit.say, o.from, points) : []) : null;
+  if (focus && !focus.length) {
+    block.remove();
+    return () => {};
+  }
+  const targets = focus ? [...new Set(focus.map((f) => f.el))] : points.map((p) => p.el);
+  const stops = focus ? [] : beatStops(o.kit.hits, o.from, o.to ?? o.ctx.dur);
+  const until = o.until ?? Infinity;
+  const n = targets.length;
+  // 훑기 차례 — 마지막 정지점(장면 끝)이 주인공이 되게 맞춘다. 끝 프레임(표지·견본)에 곁가지 글이 아니라 주인공이 짚혀 있다
+  const base = hub ? (stops.length - 1) % 2 : 0;
+  const order = (k: number) => (hub ? ((k + base) % 2 === 0 ? 0 : 1 + (((k + base - 1) / 2) % (n - 1))) : k % n);
   let toned = new Set<HTMLElement>();
   const pad = o.pad ?? 0.12;
   // 프레임마다 잰다 — 처음 그린 프레임에서 한 번만 재면 탭마다 첫 프레임이 달라 같은 시각이 다르게 그려졌다(frame.nondeterministic)
@@ -306,50 +525,52 @@ export function glider(host: HTMLElement, targets: HTMLElement[], o: { pad?: num
     const fs = parseFloat(getComputedStyle(el).fontSize) || 20;
     return { x: b.x - fs * pad, y: b.y - fs * pad * 0.5, w: b.w + fs * pad * 2, h: b.h + fs * pad };
   };
-  return (t, stops, until = Infinity) => {
-    const n = targets.length;
-    if (!n || t < stops[0] || t >= until) {
-      block.style.visibility = "hidden";
-      for (const el of toned) paintTone(el, null);
-      toned = new Set();
-      return;
+  // 이 프레임 칸 자리 — 아직 안 나타났거나 걷었으면 null
+  const where = (t: number): MarkBox | null => {
+    if (t >= until) return null;
+    if (focus) {
+      let k = -1;
+      while (k + 1 < focus.length && focus[k + 1].at <= t) k++;
+      if (k < 0) return null;
+      keyCue(t, focus[k].at);
+      const next = focus[k + 1];
+      const move = Math.max(0.1, Math.min(MOVE, (next ? next.at - focus[k].at : Infinity) - REST));
+      return shape.at(k ? rect(focus[k - 1].el) : null, rect(focus[k].el), clamp((t - focus[k].at) / move));
     }
+    if (t < stops[0]) return null;
+    stopCues(t, stops, (k) => order(k) === 0);
     let j = 0;
     while (j + 1 < stops.length && stops[j + 1] <= t) j++;
     const a = stops[j];
     const b = stops[j + 1] ?? a + 1;
-    const p = clamp((t - a) / Math.max(1e-3, b - a));
-    const e = 0.7 * p + 0.3 * p * p * (3 - 2 * p);
-    // hub 면 주인공(첫 대상)과 나머지를 번갈아 — 작은 글 사이를 옮겨 다니면 칸이 조금밖에 안 움직여 멈춘 화면으로 읽힌다.
-    // 마지막 정지점(장면 끝)이 주인공이 되게 차례를 맞춘다 — 끝 프레임(표지·견본)에 곁가지 글이 아니라 주인공이 짚혀 있다
-    const base = o.hub ? (stops.length - 1) % 2 : 0;
-    const order = (k: number) => (o.hub && n > 1 ? ((k + base) % 2 === 0 ? 0 : 1 + (((k + base - 1) / 2) % (n - 1))) : k % n);
-    const from = rect(targets[order(j)]);
-    const to = rect(targets[order(j + 1)]);
-    const mix = (u: number, v: number) => u + (v - u) * e;
+    return shape.at(rect(targets[order(j)]), rect(targets[order(j + 1)]), clamp((t - a) / Math.max(1e-3, b - a)));
+  };
+  return (t) => {
+    const box = where(t);
+    if (!box) {
+      block.style.visibility = "hidden";
+      for (const el of toned) paintTone(el, null);
+      toned = new Set();
+      return;
+    }
     block.style.visibility = "visible";
-    block.style.transform = `translate(${mix(from.x, to.x).toFixed(1)}px, ${mix(from.y, to.y).toFixed(1)}px)`;
-    block.style.width = `${mix(from.w, to.w).toFixed(1)}px`;
-    block.style.height = `${mix(from.h, to.h).toFixed(1)}px`;
-    // 띠와 겹친 글자 부분만 흰 글로 — 글자에 「겹친 사각형만 on-accent, 나머지는 원래 글색」인 배경을 깔고 글자 모양으로 오린다.
-    // 통째로 덮였을 때만 글색을 바꾸면, 쉬지 않고 옮겨 가는 띠는 거의 늘 반쯤 걸쳐 있어 띠 위 글이 검은 채로 남았다
-    const bx = mix(from.x, to.x);
-    const by = mix(from.y, to.y);
-    const bw = mix(from.w, to.w);
-    const bh = mix(from.h, to.h);
+    place(block, box);
     const now = new Set<HTMLElement>();
+    // 띠와 겹친 글자 부분만 띠 위 글색으로 — 글자에 「겹친 사각형만 ink, 나머지는 원래 글색」인 배경을 깔고 글자 모양으로 오린다.
+    // 통째로 덮였을 때만 글색을 바꾸면, 옮겨 가는 동안 반쯤 걸친 띠 위 글이 원래 색으로 남았다.
     // 불투명한 판을 품은 대상(테마 panel 이 깔린 숫자판·계기 판)은 띠가 그 판 뒤로 가려 안 보인다 — 거기 글을 흰 글로 칠하면 흰 판 위 흰 글이 된다
-    for (const el of targets.filter((x) => !opaqueOf(x)).flatMap(leavesOf)) {
+    const ink = shape.ink;
+    for (const el of ink ? targets.filter((x) => !opaqueOf(x)).flatMap(leavesOf) : []) {
       const r = boxOf(el);
-      const x0 = Math.max(bx, r.x);
-      const y0 = Math.max(by, r.y);
-      const x1 = Math.min(bx + bw, r.x + r.w);
-      const y1 = Math.min(by + bh, r.y + r.h);
+      const x0 = Math.max(box.x, r.x);
+      const y0 = Math.max(box.y, r.y);
+      const x1 = Math.min(box.x + box.w, r.x + r.w);
+      const y1 = Math.min(box.y + box.h, r.y + r.h);
       if (x1 - x0 < 1 || y1 - y0 < 1) continue;
       // 글 상자에 변환(배율)이 걸려 있으면 배경 좌표는 변환 전 크기로
       const sx = (el.offsetWidth || r.w) / (r.w || 1);
       const sy = (el.offsetHeight || r.h) / (r.h || 1);
-      paintTone(el, { x: (x0 - r.x) * sx, y: (y0 - r.y) * sy, w: (x1 - x0) * sx, h: (y1 - y0) * sy });
+      paintTone(el, { x: (x0 - r.x) * sx, y: (y0 - r.y) * sy, w: (x1 - x0) * sx, h: (y1 - y0) * sy }, ink);
       now.add(el);
     }
     for (const el of toned) if (!now.has(el)) paintTone(el, null);
@@ -400,6 +621,7 @@ export function factRoll(t: number, o: { from: number; to: number; at: number; d
   const dec = o.decimals ?? decimalsOf(o.to);
   const x = progress(t, o.at, o.dur);
   const p = 0.75 * ease.outCubic(x) + 0.25 * x;
+  rollCues(t, { at: o.at, dur: o.dur, p: (u) => 0.75 * ease.outCubic(u) + 0.25 * u });
   const lo = Math.min(o.from, o.to);
   const hi = Math.max(o.from, o.to);
   const value = p >= 1 ? o.to : clamp(o.from + (o.to - o.from) * p, lo, hi);
@@ -446,5 +668,6 @@ const DEFAULT_SLOTS: Required<Pick<ThemeSlots, "panel" | "land" | "write" | "tra
 
 /** 테마 슬롯 + 비운 자리는 기본 */
 export function slotsOf(kit: Kit): ThemeSlots & typeof DEFAULT_SLOTS {
-  return { ...DEFAULT_SLOTS, ...kit.slots } as ThemeSlots & typeof DEFAULT_SLOTS;
+  // 소리 자리는 감싸개가 단다 — 테마 슬롯이든 기본이든 같은 자리에서
+  return withSfx({ ...DEFAULT_SLOTS, ...kit.slots }) as ThemeSlots & typeof DEFAULT_SLOTS;
 }

package/packages/patterns/src/limit/gauge.ts

@@ -1,6 +1,6 @@
 import { applyStyle, clamp, spring } from "@kasaframe/core";
 import { fitSize, textEm } from "@kasaframe/motion/moves";
-import { area, beatStops, decimalsOf, factRoll, fmt, glider, moving, node, slotsOf } from "../kit.ts";
+import { area, decimalsOf, dwells, factRoll, fmt, followSpoken, glider, moving, node, sayTimes, slotsOf } from "../kit.ts";
 import type { Pattern } from "../types.ts";
 
 export interface LimitContent {
@@ -12,12 +12,12 @@ export interface LimitContent {
 
 /**
  * 한계 — 굵은 계기가 차올라 끝의 위험 칸(한계)에 부딪힌다. 값이 있으면 계기와 같은 진행도로 굴러 그 값에 닿는다.
- * 부딪힌 뒤 치르는 것 한 낱말이 딱지로 붙고, 짚개가 한계 문장·계기·치르는 것을 번갈아 박마다 짚는다.
+ * 부딪힌 뒤 치르는 것 한 낱말이 딱지로 붙고, 짚개가 한계 문장부터 짚는다(머무는 테마는 목소리가 계기 값·치르는 것을 말할 때만 그리로).
  */
 const pattern: Pattern<LimitContent> = {
   id: "limit.gauge",
   type: "limit",
-  does: "계기가 차올라 끝의 위험 칸에 부딪히고, 치르는 것이 붙은 뒤 짚개가 한계·계기·대가를 번갈아 짚는다",
+  does: "계기가 차올라 끝의 위험 칸에 부딪히고, 치르는 것이 붙은 뒤 짚개가 한계부터 짚는다",
   energy: ["low", "mid"],
   family: "grow",
   camera: ["none"],
@@ -78,24 +78,29 @@ const pattern: Pattern<LimitContent> = {
     const hits = kit.hits.length ? kit.hits : [0];
     const labelDur = clamp([...c.label].length * 0.03, 0.3, 0.7);
     const fillAt = labelDur * 0.5;
-    // 계기는 1–2.2초 안에 벽에 닿는다 — 장면이 길다고 느리게 차오르면 그 사이가 멈춘 화면이다
+    // 머무는 짚개 테마는 목소리가 한계를 말하는 순간 벽에 닿는다 — 그때까지 고른 빠르기로 차오르고, 치르는 것은 그것을 말할 때 붙고,
+    // 닿은 뒤엔 카메라가 한계·치르는 것 쪽으로 다가간다. 훑는 테마·목소리 없는 영상은 1–2.2초 안 박에 닿는다
+    const tail = Math.max(fillAt + 1, ctx.dur - 0.6);
+    const heard = dwells(kit, ctx) && (kit.say.length > 0 || kit.lines.length > 0);
+    const [heardLabel, heardCost] = heard ? sayTimes(kit, [c.label, c.cost], fillAt + 0.9, tail) : [0, 0];
     const hitWant = clamp(ctx.dur * 0.45, fillAt + 0.9, fillAt + 2.2);
-    const hitAt = hits.reduce((best, b) => (Math.abs(b - hitWant) < Math.abs(best - hitWant) && b > fillAt + 0.6 ? b : best), hitWant);
-    const costAt = hitAt + 0.1;
+    const hitAt = heard ? heardLabel : hits.reduce((best, b) => (Math.abs(b - hitWant) < Math.abs(best - hitWant) && b > fillAt + 0.6 ? b : best), hitWant);
+    const costAt = Math.max(hitAt + 0.1, heardCost);
     const markFrom = hitAt + 0.2;
+    followSpoken(kit, ctx, [{ at: hitAt, el: labelBox }, ...(cost ? [{ at: costAt, el: cost }] : [])]);
 
-    const writeLabel = slots.write(label, { ctx, text: c.label, at: 0, dur: labelDur, seed: `${kit.seed}:l` });
+    // 한계 문장은 목소리가 말하는 순간 찍힌다(그 밖엔 처음부터)
+    const writeLabel = slots.write(label, { ctx, text: c.label, at: heard ? Math.max(0, hitAt - labelDur) : 0, dur: labelDur, seed: `${kit.seed}:l` });
     const writeCost = cost ? slots.write(cost, { ctx, text: c.cost!, at: costAt, dur: 0.25, seed: `${kit.seed}:c` }) : null;
     const landed = slots.land(wallEl, { ctx, at: hitAt, seed: `${kit.seed}:wall` });
-    // 벽에 닿은 뒤엔 짚개가 한계 문장 ↔ 계기 ↔ 치르는 것을 번갈아 박마다 짚는다
+    // 벽에 닿으면 짚개가 한계 문장부터 짚는다 — 머무는 테마는 목소리가 치르는 것을 말할 때만 그리로
     // 세로면 계기 판은 짚지 않는다 — 띠가 판 뒤로 가려 그 사이가 멈춘 화면이 된다. 한계 문장 ↔ 대가를 오간다
-    const point = glider(host, vertical && cost ? [labelBox, cost] : [labelBox, gauge, ...(cost ? [cost] : [])], { hub: true });
-    const stops = beatStops(kit.hits, markFrom, ctx.dur);
+    const point = glider(host, vertical && cost ? [{ el: labelBox, text: c.label }, { el: cost, text: c.cost }] : [{ el: labelBox, text: c.label }, { el: gauge }, ...(cost ? [{ el: cost, text: c.cost }] : [])], { kit, ctx, from: markFrom });
 
     return (t: number) => {
       moving("limit.gauge", ctx);
       writeLabel(t);
-      point(t, stops);
+      point(t);
       // 고른 빠르기로 차올라 벽에 부딪힌다 — 감속하면 부딪힘이 없고 끝자락이 멈춘 화면이 된다
       const p = clamp((t - fillAt) / (hitAt - fillAt));
       fill.style.transform = vertical ? `scaleY(${(p * wall).toFixed(4)})` : `scaleX(${(p * wall).toFixed(4)})`;

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);
     };
   },
 };