kasaframe 0.0.0-stage → 0.1.3

package/packages/patterns/src/hook-number/slam.ts

@@ -0,0 +1,91 @@
+import { applyStyle, clamp, combine } from "@kasaframe/core";
+import { textEm } from "@kasaframe/motion/moves";
+import { area, beatStops, cameraOk, decimalsOf, factRoll, fitOnce, glider, moving, node, sceneDrop, slam, slotsOf } from "../kit.ts";
+import type { HookNumber } from "./roll.ts";
+import type { Pattern } from "../types.ts";
+
+/**
+ * 결과가 서는 순간 — 숫자가 화면을 꽉 채우며 드롭(없으면 첫 박)에 쾅 내려앉고, 그 박에 테마 드롭이 터진다.
+ * 앉기 전엔 라벨이 먼저 찍혀 무엇의 숫자인지 알리고, 앉은 뒤엔 반전 칸이 숫자를 장면 끝까지 짚는다. 굴리지 않는다 — 결과 그 자체.
+ */
+const pattern: Pattern<HookNumber> = {
+  id: "hook-number.slam",
+  type: "hook-number",
+  does: "숫자가 화면을 꽉 채우며 드롭에 쾅 내려앉고, 라벨이 먼저 서고 반전 칸이 숫자를 짚는다",
+  energy: ["high"],
+  family: "slam",
+  camera: ["impact"],
+  bg: "stage",
+  aspects: ["16:9", "9:16", "1:1"],
+  dur: { min: 1.6, max: 5 },
+  fits(c) {
+    if (!Number.isFinite(c?.value)) return "value 가 수가 아니다";
+    if (typeof c.label !== "string" || !c.label.trim() || [...c.label].length > 24) return "label 이 비었거나 24자를 넘는다";
+    if (c.unit && [...c.unit].length > 6) return "unit 이 6자를 넘는다";
+    return true;
+  },
+  build(root, ctx, c, kit) {
+    const slots = slotsOf(kit);
+    const { w, h, vertical, u } = area(ctx, kit);
+    const dec = c.decimals ?? decimalsOf(c.value);
+    const text = `${c.prefix ?? ""}${factRoll(Infinity, { from: 0, to: c.value, at: 0, dur: 1, decimals: dec }).text}`;
+    const unit = c.unit ?? "";
+    const rowEm = textEm(text) + (unit ? 0.1 + 0.42 * textEm(unit) : 0);
+    // 화면을 꽉 — 폭 90%, 세로 화면은 높이 42% 까지
+    const numPx = Math.round(Math.min((w * 0.9) / rowEm, h * (vertical ? 0.42 : 0.62)));
+    const labelPx = Math.round(Math.max(52 * u, numPx * 0.13));
+    const weight = ctx.style.type?.weightDisplay ?? 800;
+
+    const host = node(root, "position:absolute;inset:0;display:flex;align-items:center;justify-content:center");
+    const col = node(host, `position:relative;display:flex;flex-direction:column;align-items:center;gap:${Math.round(numPx * 0.06)}px`);
+    const labelBox = node(col, `position:relative;font-family:var(--kf-font-sans);font-size:${labelPx}px;font-weight:700;white-space:nowrap;line-height:1.2;height:1.2em`);
+    const label = node(labelBox, "color:var(--kf-ink)");
+    const row = node(col, `display:flex;align-items:baseline;gap:${Math.round(numPx * 0.06)}px;transform-origin:50% 60%`);
+    // 쾅 전엔 같은 숫자가 외곽선으로 제자리에 먼저 서 있다 — 무엇이 올지 보이고, 앉으면 꽉 찬 숫자가 그 위를 덮는다
+    const ghostRow = node(col, `position:absolute;display:flex;align-items:baseline;gap:${Math.round(numPx * 0.06)}px;visibility:hidden`);
+    node(ghostRow, `font-family:var(--kf-font-display);font-size:${numPx}px;font-weight:${weight};line-height:.95;letter-spacing:-0.04em;color:transparent;-webkit-text-stroke:${Math.max(2, Math.round(numPx * 0.008))}px var(--kf-ink);white-space:pre;opacity:.5`, text);
+    if (unit) node(ghostRow, `font-family:var(--kf-font-display);font-size:${Math.round(numPx * 0.42)}px;font-weight:${weight};color:transparent;white-space:nowrap`, unit);
+    const numBox = node(row, "position:relative;color:var(--kf-ink)");
+    node(numBox, `font-family:var(--kf-font-display);font-size:${numPx}px;font-weight:${weight};line-height:.95;letter-spacing:-0.04em;white-space:pre`, text);
+    if (unit) node(row, `font-family:var(--kf-font-display);font-size:${Math.round(numPx * 0.42)}px;font-weight:${weight};color:var(--kf-accent-text, var(--kf-accent));white-space:nowrap`, unit);
+    kit.stage?.hero(row);
+    // 드롭 터짐은 화면 전체 층에 — 카메라 층(안전 영역)에 깔면 터짐이 네모 판으로 보인다
+    const burst = node(kit.stage?.box ?? root, "position:absolute;inset:0;pointer-events:none;z-index:50");
+
+    // 앉는 박 — 이 장면에 드롭이 있으면 그 드롭, 없으면 라벨이 다 찍힌 뒤 첫 박
+    const di = sceneDrop(ctx);
+    const labelDur = clamp([...c.label].length * 0.03, 0.25, 0.5);
+    const hits = kit.hits.length ? kit.hits : [0];
+    const at = di !== null ? ctx.beats.drop(di) : (hits.find((b) => b >= labelDur + 0.1) ?? labelDur + 0.15);
+    const dropPaint = di !== null && slots.drop ? slots.drop(burst, { ctx, drop: di }) : null;
+    if (di === null && kit.stage && cameraOk(ctx)) kit.stage.camera.impact(at, { amount: 0.04 });
+    const writeLabel = slots.write(label, { ctx, text: c.label, at: 0, dur: labelDur, seed: `${kit.seed}:l` });
+    const landed = slots.land(row, { ctx, at, seed: `${kit.seed}:land` });
+    // 짚개 — 쾅 전엔 라벨 ↔ 외곽선 자리(무엇의 숫자가 어디 오나), 쾅 뒤엔 숫자 ↔ 라벨을 박마다 번갈아 짚는다
+    const before = glider(host, [labelBox, ghostRow], { hub: true });
+    const after = glider(host, [numBox, labelBox], { hub: true });
+    const preStops = beatStops(kit.hits, labelDur, at - 0.2);
+    // 라벨은 그 글꼴로 재서 안전 영역 폭 92% 안에
+    const fitLabel = fitOnce(labelBox, w * 0.92, labelPx, c.label);
+    const postStops = beatStops(kit.hits, at + 0.25, ctx.dur);
+
+    return (t: number) => {
+      moving("hook-number.slam", ctx);
+      fitLabel();
+      writeLabel(t);
+      const s = dropPaint?.(t);
+      applyStyle(row, combine(slam(t, at), landed(t), s?.punch));
+      // 외곽선은 숫자 줄과 같은 자리에 — 처음 보일 때 숫자 줄 자리를 잰다(장면이 보인 뒤라 잴 수 있다)
+      ghostRow.style.visibility = t < at ? "visible" : "hidden";
+      if (t < at) {
+        ghostRow.style.left = `${row.offsetLeft}px`;
+        ghostRow.style.top = `${row.offsetTop}px`;
+      }
+      before(t, preStops, at - 0.16);
+      after(t, postStops);
+      if (s) applyStyle(host, s.shake);
+    };
+  },
+};
+
+export default pattern;

package/packages/patterns/src/index.ts

@@ -0,0 +1,38 @@
+import codeTerminal from "./code/terminal.ts";
+import compareBars from "./compare/bars.ts";
+import compareDuel from "./compare/duel.ts";
+import beforeAfterShrink from "./before-after/shrink.ts";
+import beforeAfterStrike from "./before-after/strike.ts";
+import barsRank from "./bars/rank.ts";
+import endLockup from "./end/lockup.ts";
+import endSlam from "./end/slam.ts";
+import flowGraph from "./flow/graph.ts";
+import hookNumberCounter from "./hook-number/counter.ts";
+import hookNumberRoll from "./hook-number/roll.ts";
+import hookNumberSlam from "./hook-number/slam.ts";
+import limitGauge from "./limit/gauge.ts";
+import listCards from "./list/cards.ts";
+import listCycle from "./list/cycle.ts";
+import mediaPanels from "./media/panels.ts";
+import quoteKaraoke from "./quote/karaoke.ts";
+import quoteSlam from "./quote/slam.ts";
+import screenFocus from "./screen/focus.ts";
+import stepsPath from "./steps/path.ts";
+import stepsStack from "./steps/stack.ts";
+import termRevealChips from "./term-reveal/chips.ts";
+import termRevealExpand from "./term-reveal/expand.ts";
+import timelineAxis from "./timeline/axis.ts";
+import toggleSimSwitch from "./toggle-sim/switch.ts";
+import trendColumns from "./trend/columns.ts";
+import trendDraw from "./trend/draw.ts";
+import wordsSlam from "./words/slam.ts";
+import titleMask from "./title/mask.ts";
+import titleSlam from "./title/slam.ts";
+import type { Pattern } from "./types.ts";
+
+// 감독이 Node 에서 meta·fits 로 고른다 — 여기 모인 패턴만 후보다. 장면 파일은 @kasaframe/patterns/<type>/<이름> 으로 하나씩 가져간다
+export const PATTERNS: readonly Pattern[] = [hookNumberRoll, hookNumberSlam, listCards, titleMask, barsRank, beforeAfterStrike, flowGraph, endLockup, endSlam, termRevealExpand, termRevealChips, compareBars, compareDuel, stepsPath, stepsStack, limitGauge, timelineAxis, quoteKaraoke, trendDraw, codeTerminal, wordsSlam, toggleSimSwitch, mediaPanels, screenFocus, titleSlam, listCycle, beforeAfterShrink, hookNumberCounter, quoteSlam, trendColumns];
+
+export { OBJECTS, objectFor, objectById, objectCss, objectsJson, cssColor, styleColor } from "./objects.ts";
+export type { VisualObject, ColorToken, Shape2d, Shape3d } from "./objects.ts";
+export type * from "./types.ts";

package/packages/patterns/src/kit.ts

@@ -0,0 +1,449 @@
+import { clamp, ease, progress, spring, type SceneCtx, type Style } from "@kasaframe/core";
+import { mark } from "@kasaframe/motion/moves";
+import { typeDuration, typeText } from "@kasaframe/motion";
+import { partial } from "@kasaframe/themes/slotkit";
+import type { Kit, ThemeSlots } from "./types.ts";
+
+// 패턴들이 같이 쓰는 몫. 모듈 맨 위에서 DOM 을 만지지 않는다 — 감독이 Node 에서 meta·fits 를 읽는다.
+
+export type Paint = (t: number) => void;
+
+/** 패턴이 그릴 상자(= 무대 카메라 층 = 안전 영역). u 는 짧은 변 1080 을 1 로 본 배율 */
+export function area(ctx: SceneCtx, kit: Kit): { w: number; h: number; vertical: boolean; u: number } {
+  const w = kit.stage?.safeW ?? ctx.meta.width - ctx.safe.left - ctx.safe.right;
+  const h = kit.stage?.safeH ?? ctx.meta.height - ctx.safe.top - ctx.safe.bottom;
+  return { w, h, vertical: ctx.meta.height > ctx.meta.width, u: Math.min(w, h) / 1080 };
+}
+
+/** 패턴이 화면을 움직이는 동안 검사용 기록 — 같은 패턴을 이어지는 장면에 되풀이하면 motion.repeat 가 잡는다 */
+export const moving = (id: string, ctx: SceneCtx): void => mark(id, ctx.id, true);
+
+/** 배수 기호(57×) — 숫자에 붙어 한 덩어리로 읽힌다. 세로 화면이라도 아래 줄로 내리면 혼자 떠서 지우기 아이콘처럼 읽혀 늘 숫자 옆에 둔다 */
+export const timesSign = (unit: string): boolean => /^[×✕✖xX]$/.test(unit.trim());
+
+/** 강조색 글 — 테마의 accentText(바탕 위에서 읽히는 강조색). 면은 accent, 글은 이것 */
+export const ACCENT_TEXT = "var(--kf-accent-text, var(--kf-accent))";
+
+/** 스타일·틀이 카메라를 끈 영상(cameraMove: off)이면 패턴은 카메라 대신 화면 안 강조로 */
+export const cameraOk = (ctx: SceneCtx): boolean => ctx.style.motion?.cameraMove !== "off";
+
+/** 형광펜 띠 — 글 뒤에 accentSoft 면이 왼쪽부터 차오른다(강조). p 는 0..1 */
+export function marker(parent: HTMLElement, css = ""): (p: number) => void {
+  const band = node(parent, `position:absolute;left:-3%;right:-3%;top:8%;bottom:4%;background:var(--kf-accent-soft);transform-origin:0 50%;z-index:-1;${css}`);
+  return (p) => {
+    band.style.visibility = p > 0 ? "visible" : "hidden";
+    band.style.transform = `scaleX(${clamp(p).toFixed(4)})`;
+  };
+}
+
+// 상대휘도(WCAG) — #rgb·#rrggbb 만, 못 읽으면 NaN
+function lum(hex: string | undefined): number {
+  const m = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec((hex ?? "").trim());
+  if (!m) return NaN;
+  const h = m[1].length === 3 ? [...m[1]].map((c) => c + c).join("") : m[1];
+  const ch = [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16) / 255).map((c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4));
+  return 0.2126 * ch[0] + 0.7152 * ch[1] + 0.0722 * ch[2];
+}
+
+/**
+ * 강조색 글이 본문 글과 대비가 3:1 이 안 되는 테마(HUD 형광 하나·OG 짙은 파랑·리소 파랑) — 글 색만 바꾸면 화면이 안 바뀐 것으로 읽혀
+ * (kf check frame.freeze) 반전 칸으로 짚는다
+ */
+export function inkLike(ctx: SceneCtx): boolean {
+  const c = ctx.style.colors as Record<string, string | undefined>;
+  const a = lum(c.accentText ?? c.accent);
+  const b = lum(c.ink);
+  const hi = Math.max(a, b);
+  const lo = Math.min(a, b);
+  return !Number.isFinite(a) || !Number.isFinite(b) || (hi + 0.05) / (lo + 0.05) < 3;
+}
+
+/**
+ * 큰 이름 — 글자마다 가림막 아래에서 올라와 서고(riseAt 부터 each 간격), fill 진행도(0..1)만큼 강조가 왼쪽부터 글자를 짚는다.
+ * 강조색 글이 본문 글과 같은 테마(HUD)면 반전 칸으로 — 같은 색으로 채우면 아무것도 안 바뀐다
+ */
+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}`;
+  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");
+    // 올라오는 동안은 ::before 로 그린다 — 가림막에 반쯤 걸린 글자를 검사가 「대비 낮은 글」로 읽지 않게. 다 서면 진짜 글
+    const g = node(clip, "position:relative;display:inline-block;white-space:pre");
+    g.dataset.ch = ch;
+    // 강조 겹은 글자 안에 — 이름 전체를 한 진행도로 채울 때 글자 자리가 어긋나지 않게
+    const hi = node(g, `position:absolute;inset:0;visibility:hidden;white-space:pre;${hiCss}`, ch);
+    return { g, hi };
+  });
+  return (t, o) => {
+    const fp = clamp(o.fill) * glyphs.length;
+    glyphs.forEach(({ g, hi }, i) => {
+      const p = ease.outExpo(progress(t, o.riseAt + i * o.each, 0.3));
+      g.style.transform = `translateY(${((1 - p) * 110).toFixed(2)}%)`;
+      const up = p >= 0.995;
+      if (up && g.firstChild?.nodeType !== 3) {
+        delete g.dataset.kfOdo;
+        g.insertBefore(g.ownerDocument.createTextNode(g.dataset.ch ?? ""), g.firstChild);
+      } else if (!up && g.firstChild?.nodeType === 3) {
+        g.firstChild.remove();
+      }
+      if (!up) g.dataset.kfOdo = g.dataset.ch ?? "";
+      const k = clamp(fp - i);
+      hi.style.visibility = k > 0 ? "visible" : "hidden";
+      hi.style.clipPath = `inset(0 ${((1 - k) * 100).toFixed(2)}% 0 0)`;
+    });
+  };
+}
+
+/** 가림막에 걸린 글자를 ::before 로 그리는 규칙 — 페이지에 한 번 */
+function odoStyle(el: HTMLElement): void {
+  if (el.ownerDocument.getElementById("kf-odo-style")) return;
+  const st = el.ownerDocument.createElement("style");
+  st.id = "kf-odo-style";
+  st.textContent = "[data-kf-odo]::before{content:attr(data-kf-odo)}";
+  el.ownerDocument.head.append(st);
+}
+
+/**
+ * 주행계 숫자 — 끝자리 띠가 값을 따라 연속으로 굴러, 0→57 처럼 작은 범위도 프레임마다 화면이 바뀐다. 윗자리는 아랫자리가 9 를 넘을 때만 같이 구른다.
+ * 보이는 숫자는 늘 이웃한 두 숫자 사이(엉뚱한 값 없음). 맨 앞 0 자리는 비운다. 쉼표·음수가 있으면 null(글 굴림으로)
+ */
+export function odometer(el: HTMLElement, o: { template: string; decimals: number; linePx: number }): ((v: number) => void) | null {
+  if (/[^0-9.]/.test(o.template)) return null;
+  el.textContent = "";
+  el.style.display = "inline-flex";
+  // 띠의 숫자는 ::before 로 — 창 가장자리에 반쯤 걸린 숫자를 검사가 「대비 낮은 글」로 읽지 않게. 앉은 뒤엔 패턴이 진짜 글로 바꾼다
+  odoStyle(el);
+  const lowest = -o.decimals;
+  let place = (o.template.split(".")[0] ?? "").length - 1;
+  const cols: { strip: HTMLDivElement; glyphs: HTMLDivElement[]; j: number }[] = [];
+  for (const ch of o.template) {
+    if (ch === ".") {
+      node(el, "display:inline-block", ".");
+      continue;
+    }
+    const k = place;
+    const box = node(el, `display:inline-block;position:relative;overflow:hidden;height:${o.linePx}px;width:0.62em;text-align:center`);
+    const strip = node(box, "position:absolute;left:0;right:0;top:0");
+    const glyphs = "01234567890".split("").map((d) => {
+      const g = node(strip, `height:${o.linePx}px;line-height:${o.linePx}px`);
+      g.dataset.kfOdo = d;
+      return g;
+    });
+    cols.push({ strip, glyphs, j: k - lowest });
+    place--;
+  }
+  return (v) => {
+    const n = Math.max(0, v) / 10 ** lowest;
+    const whole = Math.floor(n + 1e-9);
+    const frac = n - whole;
+    for (const c of cols) {
+      const base = Math.floor(whole / 10 ** c.j);
+      const lower = whole % 10 ** c.j;
+      const roll = c.j === 0 || lower === 10 ** c.j - 1 ? frac : 0;
+      // 맨 앞 0 은 비운다 — 다음 자리로 올라가는 동안은 빈칸에서 1 로 구른다
+      const pos = (base % 10) + roll;
+      // 창에 걸친 두 숫자만 보인다 — 띠 밖 숫자는 검사가 읽지 않게 숨긴다
+      c.glyphs.forEach((g, i) => (g.style.visibility = i === Math.floor(pos) || i === Math.floor(pos) + 1 ? "visible" : "hidden"));
+      if (base === 0 && c.j > -lowest) c.glyphs[0].style.visibility = "hidden";
+      c.strip.style.transform = `translateY(${(-pos * o.linePx).toFixed(2)}px)`;
+    }
+  };
+}
+
+/**
+ * 반전 짚음 — el(글 상자, position:relative — 쓰기 슬롯이 글을 갈아 끼우는 요소면 그 부모에 건다) 위에 강조색 면 + onAccent 글 겹을 깔고 p 만큼 왼쪽부터 드러낸다.
+ * 옅은 형광펜(accentSoft)은 밝은 바탕에서 화면이 바뀐 것으로 안 읽혀 이쪽이 쉬지 않는 몫을 진다
+ */
+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);
+  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)`;
+  };
+}
+
+/** 이 장면 안에 든 첫 드롭의 번호(곡 전체 기준 — 테마 drop 슬롯·dropBurst 가 받는 번호). 없으면 null */
+export function sceneDrop(ctx: SceneCtx): number | null {
+  const i = ctx.beats.drops.findIndex((d) => d >= 0 && d < ctx.dur);
+  return i < 0 ? null : i;
+}
+
+/**
+ * 쾅 — at 에 크게(from 배) 흐린 채 들어와 내려앉고 출렁인다. 앉는 순간이 주인공이 서는 박.
+ * 등장 전엔 opacity 0 이라 그 사이를 다른 움직임이 채워야 한다
+ */
+export function slam(t: number, at: number, from = 1.9): Style {
+  const lead = 0.16;
+  if (t < at - lead) return { opacity: 0 };
+  if (t < at) {
+    const p = ease.inCubic((t - (at - lead)) / lead);
+    return { opacity: clamp(p * 2.5), scale: from - (from - 1) * p, blur: 14 * (1 - p) };
+  }
+  const s = t - at;
+  const wob = Math.exp(-s / 0.14) * Math.cos(s * 30);
+  return { scaleX: 1 + 0.08 * wob, scaleY: 1 - 0.08 * wob };
+}
+
+/**
+ * 글 폭을 실제로 재서 맞춘다 — build 때는 장면이 숨어 글 폭을 못 재 글자 수로 어림하는데, 라틴 글꼴은 어림보다 좁아 화면이 빈다.
+ * 처음 보이는 프레임에 한 번 재서 el 의 글 크기를 maxW 폭(maxPx 상한)에 맞춘다. 글꼴이 다 받아진 뒤라 어느 탭에서 재도 같다
+ */
+export function fitOnce(el: HTMLElement, maxW: number, maxPx: number, text?: string): () => void {
+  let done = false;
+  return () => {
+    // 글이 주어지면 움직이지 않는 숨은 견본을 문서 본문(늘 보이는 자리)에 두고 잰다 — 장면이 아직 숨은 첫 프레임엔 폭이 0 이라 맞춤을
+    // 건너뛰고 다음 프레임부터 맞춰져, 그 장면을 처음 그린 시각만 다른 크기가 됐다. 올라오는 중인 글자(riseName)를 재도 프레임 상태를 따랐다
+    if (done || (text === undefined && !el.offsetWidth)) return;
+    done = true;
+    const px = parseFloat(el.style.fontSize) || 16;
+    let width = el.offsetWidth;
+    if (text !== undefined) {
+      const cs = getComputedStyle(el);
+      const probe = node(el.ownerDocument.body, `position:absolute;left:-100000px;top:0;visibility:hidden;white-space:pre;font-family:${cs.fontFamily};font-weight:${cs.fontWeight};letter-spacing:${cs.letterSpacing};font-size:${px}px`, text);
+      width = probe.offsetWidth;
+      probe.remove();
+    }
+    if (width > 0) el.style.fontSize = `${Math.round(Math.min(maxPx, (px * maxW) / width))}px`;
+  };
+}
+
+/**
+ * 짚개의 정지점 — from 뒤의 박을 간격 gap 넘게 골라 쓰고(빈 곳은 고르게 메운다), 마지막 정지점은 장면 끝(to)이다.
+ * 끝 프레임에서 칸이 대상에 거의 앉아 있어야 표지·견본 스틸에 반쯤 걸친 띠가 안 찍힌다. 칸은 그 순간까지 움직이니(직선 7) 서지는 않는다.
+ * 장면이 길어도 짚개 빠르기는 박이 정한다 — 장면 길이에 비례해 느려지는 차오름은 긴 장면에서 멈춘 화면이 된다
+ */
+export function beatStops(hits: readonly number[], from: number, to: number, gap = 0.4): number[] {
+  const out = [from];
+  for (const b of hits) if (b > out[out.length - 1] + gap - 1e-6 && b < to) out.push(b);
+  for (let i = 0; i + 1 < out.length; i++) if (out[i + 1] - out[i] > gap * 1.6) out.splice(i + 1, 0, (out[i] + out[i + 1]) / 2);
+  while (to - out[out.length - 1] > gap * 1.6) out.push(out[out.length - 1] + gap * 1.2);
+  // 끝 바로 앞 정지점은 뺀다 — 남은 토막이 짧으면 칸이 한두 프레임 만에 건너뛴다
+  if (out.length > 1 && to - out[out.length - 1] < gap * 0.6) out.pop();
+  out.push(to);
+  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 {
+  const s = el.style;
+  if (!over) {
+    const saved = toneSaved.get(el);
+    if (!saved) return;
+    for (const [k, v, pri] of saved) v ? s.setProperty(k, v, pri) : s.removeProperty(k);
+    toneSaved.delete(el);
+    delete el.dataset.kfTone;
+    return;
+  }
+  if (!toneSaved.has(el)) toneSaved.set(el, TONE_PROPS.map((k) => [k, s.getPropertyValue(k), s.getPropertyPriority(k)]));
+  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.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`;
+  s.setProperty("-webkit-background-clip", "text");
+  s.setProperty("background-clip", "text");
+}
+
+// 대상 안에 바탕이 칠해진 요소가 있나 — 투명·알파 0 이면 없는 것
+function hasPlate(root: HTMLElement): boolean {
+  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;
+  });
+}
+
+// 글을 담는 잎 자리 — 글 노드를 품었거나, riseName 처럼 ::before 로 글자를 그리거나, 자식 요소가 없는 것(글 찍기 슬롯이 곧 글을 넣을 칸).
+// 처음부터 띠 위 글색(on-accent)으로 칠한 글(게이지 값)은 뺀다. 보이는지·지금 글이 있는지로 고르지 않는다 — 짚개가 같은 프레임의
+// 글 찍기보다 먼저 돌아 그 둘은 앞 프레임 상태라, 앞에 어느 시각을 그렸느냐에 따라 칠할 글이 달라졌다(frame.nondeterministic).
+// 부모에 오리기를 걸면 변환 걸린 자식 글자를 못 잡아 글이 사라져서 잎마다 칠한다
+function leavesOf(root: HTMLElement): HTMLElement[] {
+  const out: HTMLElement[] = [];
+  const walk = (el: HTMLElement) => {
+    const own = el.dataset.kfOdo !== undefined || el.dataset.ch !== undefined || !el.children.length || Array.from(el.childNodes).some((n) => n.nodeType === 3);
+    if (own && !/on-accent/.test(el.style.color)) out.push(el);
+    for (const c of Array.from(el.children)) walk(c as HTMLElement);
+  };
+  walk(root);
+  return out;
+}
+
+export function glider(host: HTMLElement, targets: HTMLElement[], o: { pad?: number; hub?: boolean } = {}): (t: number, stops: readonly number[], until?: number) => void {
+  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");
+  let toned = new Set<HTMLElement>();
+  const pad = o.pad ?? 0.12;
+  // 프레임마다 잰다 — 처음 그린 프레임에서 한 번만 재면 탭마다 첫 프레임이 달라 같은 시각이 다르게 그려졌다(frame.nondeterministic)
+  const opaqueOf = hasPlate;
+  // 대상 글 상자(raw)와 칸이 덮을 자리(여백 붙임)
+  const boxOf = (el: HTMLElement) => {
+    const hr = host.getBoundingClientRect();
+    const k = hr.width / (host.offsetWidth || 1) || 1;
+    const r = el.getBoundingClientRect();
+    return { x: (r.left - hr.left) / k, y: (r.top - hr.top) / k, w: r.width / k, h: r.height / k };
+  };
+  const rect = (el: HTMLElement) => {
+    const b = boxOf(el);
+    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;
+    }
+    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;
+    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);
+    const now = new Set<HTMLElement>();
+    // 불투명한 판을 품은 대상(테마 panel 이 깔린 숫자판·계기 판)은 띠가 그 판 뒤로 가려 안 보인다 — 거기 글을 흰 글로 칠하면 흰 판 위 흰 글이 된다
+    for (const el of 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);
+      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 });
+      now.add(el);
+    }
+    for (const el of toned) if (!now.has(el)) paintTone(el, null);
+    toned = now;
+  };
+}
+
+/** n 개가 차례로 붙는 시각 — 0.32초 간격을 박에 붙이되(0.08초 안의 박만), 박이 멀면 간격대로. 첫 붙음과 둘째 사이가 비면 멈춘 화면이다 */
+export function cadence(hits: readonly number[], n: number, from = 0, gap = 0.32): number[] {
+  return Array.from({ length: n }, (_, i) => {
+    const want = from + i * gap;
+    const near = hits.reduce((b, h) => (Math.abs(h - want) < Math.abs(b - want) ? h : b), Infinity);
+    return Math.abs(near - want) < 0.08 ? near : want;
+  });
+}
+
+export function node(parent: HTMLElement, css: string, text?: string): HTMLDivElement {
+  const d = parent.ownerDocument.createElement("div");
+  d.style.cssText = css;
+  if (text !== undefined) d.textContent = text;
+  parent.append(d);
+  return d;
+}
+
+/** t 이후 첫 박 — 없으면 fallback */
+export const hitAfter = (hits: readonly number[], t: number, fallback = t): number => hits.find((h) => h >= t - 1e-6) ?? fallback;
+
+/** 박을 빠른 곡에서도 간격 gap 넘게 솎는다(잰 시각 그대로) */
+export function spaced(hits: readonly number[], gap: number): number[] {
+  const out: number[] = [];
+  for (const h of hits) if (!out.length || h - out[out.length - 1] >= gap - 1e-6) out.push(h);
+  return out;
+}
+
+export const decimalsOf = (n: number): number => {
+  const s = String(n);
+  return s.includes("e") ? 0 : (s.split(".")[1] ?? "").length;
+};
+
+export const fmt = (v: number, dec: number): string => v.toLocaleString("en-US", { minimumFractionDigits: dec, maximumFractionDigits: dec });
+
+/**
+ * 사실 숫자 사이만 지나는 굴림 — from 에서 to 로 단조(넘침 없음), 지나는 값은 늘 둘 사이, 소수 자리는 to 기준으로 고정.
+ * 다 굴린 뒤엔 to 를 그 자리 수로 찍은 글 그대로. p 는 0..1 진행도(자·게이지가 같은 값을 쓴다).
+ * 감속은 끝까지 빠르기가 0 이 되지 않게 곧은 몫을 섞는다 — 끝자리가 오래 서 있으면 앉기 전에 멈춘 화면이 된다
+ */
+export function factRoll(t: number, o: { from: number; to: number; at: number; dur: number; decimals?: number }): { text: string; value: number; p: number } {
+  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;
+  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);
+  return { text: fmt(value, dec), value, p };
+}
+
+// 테마가 비운 슬롯은 여기 기본으로 — 테마 토큰(CSS 변수)만 쓴다
+const DEFAULT_SLOTS: Required<Pick<ThemeSlots, "panel" | "land" | "write" | "trace">> = {
+  panel(el, { at, tone }) {
+    const plate = el.ownerDocument.createElement("div");
+    plate.style.cssText =
+      `position:absolute;inset:0;border-radius:var(--kf-radius-md);box-shadow:var(--kf-shadow-soft);` +
+      `background:${tone === "accent" ? "var(--kf-accent)" : "var(--kf-raised)"};border:2px solid var(--kf-line)`;
+    el.prepend(plate);
+    return (t) => {
+      plate.style.opacity = String(clamp((t - at) / 0.08));
+    };
+  },
+  land(_el, { at }) {
+    return (t): Style => (t < at ? {} : { scale: spring(t - at, { from: 1.16, to: 1, stiffness: 320, damping: 17 }) });
+  },
+  trace(el, { points, at, dur, tone }) {
+    const svg = el.ownerDocument.createElementNS("http://www.w3.org/2000/svg", "svg");
+    svg.setAttribute("style", "position:absolute;inset:0;width:100%;height:100%;overflow:visible;pointer-events:none");
+    const line = el.ownerDocument.createElementNS("http://www.w3.org/2000/svg", "polyline");
+    line.setAttribute("fill", "none");
+    line.setAttribute("stroke", tone === "accent" ? "var(--kf-accent)" : "var(--kf-dim)");
+    line.setAttribute("stroke-width", "4");
+    line.setAttribute("stroke-linejoin", "round");
+    svg.append(line);
+    el.append(svg);
+    return (t) => {
+      const p = clamp((t - at) / Math.max(0.05, dur));
+      line.setAttribute("points", p > 0 ? partial(points, p).map((v) => `${v[0].toFixed(1)},${v[1].toFixed(1)}`).join(" ") : "");
+    };
+  },
+  write(el, { text, at, dur, seed }) {
+    const cps = typeDuration(text, { cps: 1, jitter: 0 }) / Math.max(0.05, dur);
+    return (t) => {
+      el.textContent = t >= at + dur ? text : t < at ? "" : typeText(text, t, { at, cps, jitter: 0, seed }).text;
+    };
+  },
+};
+
+/** 테마 슬롯 + 비운 자리는 기본 */
+export function slotsOf(kit: Kit): ThemeSlots & typeof DEFAULT_SLOTS {
+  return { ...DEFAULT_SLOTS, ...kit.slots } as ThemeSlots & typeof DEFAULT_SLOTS;
+}