kasaframe 0.1.1 → 0.1.3

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;
+}

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

@@ -0,0 +1,117 @@
+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 type { Pattern } from "../types.ts";
+
+export interface LimitContent {
+  label: string;
+  value?: number;
+  unit?: string;
+  cost?: string;
+}
+
+/**
+ * 한계 — 굵은 계기가 차올라 끝의 위험 칸(한계)에 부딪힌다. 값이 있으면 계기와 같은 진행도로 굴러 그 값에 닿는다.
+ * 부딪힌 뒤 치르는 것 한 낱말이 딱지로 붙고, 짚개가 한계 문장·계기·치르는 것을 번갈아 박마다 짚는다.
+ */
+const pattern: Pattern<LimitContent> = {
+  id: "limit.gauge",
+  type: "limit",
+  does: "계기가 차올라 끝의 위험 칸에 부딪히고, 치르는 것이 붙은 뒤 짚개가 한계·계기·대가를 번갈아 짚는다",
+  energy: ["low", "mid"],
+  family: "grow",
+  camera: ["none"],
+  bg: "stage",
+  aspects: ["16:9", "9:16", "1:1"],
+  dur: { min: 2.4, max: 7 },
+  fits(c) {
+    if (typeof c?.label !== "string" || !c.label.trim()) return "label 이 비었다";
+    if ([...c.label].length > 24) return "label 이 24자를 넘는다";
+    if (c.value !== undefined && !(Number.isFinite(c.value) && c.value >= 0)) return "value 가 0 이상 수가 아니다";
+    if (c.cost && [...c.cost].length > 10) return "cost 가 10자를 넘는다";
+    return true;
+  },
+  build(root, ctx, c, kit) {
+    const slots = slotsOf(kit);
+    const { w, h, vertical, u } = area(ctx, kit);
+    // 세로 화면은 계기를 세워 아래에서 위로 차오르게 한다 — 위아래를 다 써서 화면 위쪽에만 몰리지 않는다
+    const gw = vertical ? Math.round(w * 0.74) : w * 0.9;
+    const gh = Math.round(h * (vertical ? 0.5 : 0.14));
+    // 계기 두께(차오르는 방향과 직각) — 값 글자 크기의 기준
+    const thick = vertical ? gw : gh;
+    const wall = 0.82;
+    const pieces = c.label.split(/\s+/);
+    const lines = vertical ? Math.min(3, pieces.length) : Math.min(2, pieces.length);
+    const labelPx = fitSize(vertical ? pieces.reduce((a, p) => (textEm(p) > textEm(a) ? p : a), "") : c.label, gw * (vertical ? 0.95 : 0.9 * lines), h, { hShare: (vertical ? 0.3 : 0.26) / lines, max: Math.round((vertical ? 200 : 150) * u), min: Math.round(44 * u) });
+    const dec = c.value !== undefined ? decimalsOf(c.value) : 0;
+    const valText = c.value !== undefined ? `${factRoll(Infinity, { from: 0, to: c.value, at: 0, dur: 1, decimals: dec }).text}${c.unit ? ` ${c.unit}` : ""}` : "";
+    const valPx = Math.round(Math.min(thick * (vertical ? 0.3 : 0.62), fitSize(valText || "0", vertical ? gw * 0.86 : gw * 0.3, h)));
+    const costPx = Math.round(Math.max(52 * u, labelPx * 0.42));
+
+    const host = node(root, "position:absolute;inset:0;display:flex;align-items:center;justify-content:center");
+    const labelW = vertical ? w * 0.92 : gw;
+    // 세로면 문장과 계기 사이에 대가 칩이 설 줄 하나를 비워 둔다 — 칩이 문장 아래 끝에 겹쳤다
+    const col = node(host, `display:flex;flex-direction:column;align-items:center;gap:${Math.round(vertical ? Math.max(h * 0.05, c.cost ? costPx * 2.4 : 0) : gh * 0.45)}px;width:${labelW}px`);
+    const labelBox = node(col, `position:relative;display:inline-block;max-width:${labelW}px;text-align:center`);
+    const label = node(labelBox, `font-family:var(--kf-font-display);font-size:${labelPx}px;font-weight:${ctx.style.type?.weightDisplay ?? 800};color:var(--kf-ink);text-align:center;line-height:1.12;word-break:keep-all;max-width:${labelW}px`);
+    // 세로면 계기 옆에 치르는 것을 벽 높이에 — 가로면 계기 아래 오른쪽
+    const row = vertical ? node(col, "position:relative;display:flex;justify-content:center;width:100%") : col;
+    const line = Math.max(2, Math.round(3 * u));
+    const gauge = node(row, `position:relative;width:${gw}px;height:${gh}px;background:var(--kf-raised);border:${line}px solid var(--kf-line);box-sizing:border-box`);
+    const fill = node(gauge, vertical ? "position:absolute;left:0;right:0;bottom:0;height:100%;background:var(--kf-accent);transform-origin:50% 100%;transform:scaleY(0)" : "position:absolute;left:0;top:0;bottom:0;width:100%;background:var(--kf-accent);transform-origin:0 50%;transform:scaleX(0)");
+    const danger = node(gauge, vertical ? `position:absolute;left:0;right:0;top:0;height:${(1 - wall) * 100}%;background:var(--kf-danger, var(--kf-accent));opacity:.28` : `position:absolute;left:${wall * 100}%;right:0;top:0;bottom:0;background:var(--kf-danger, var(--kf-accent));opacity:.28`);
+    const bar = Math.max(4, Math.round(6 * u));
+    const wallEl = node(
+      gauge,
+      vertical
+        ? `position:absolute;top:${(1 - wall) * 100}%;left:-${Math.round(gw * 0.12)}px;right:-${Math.round(gw * 0.12)}px;height:${bar}px;margin-top:-${bar / 2}px;background:var(--kf-danger, var(--kf-ink))`
+        : `position:absolute;left:${wall * 100}%;top:-${Math.round(gh * 0.3)}px;bottom:-${Math.round(gh * 0.3)}px;width:${bar}px;margin-left:-${bar / 2}px;background:var(--kf-danger, var(--kf-ink))`,
+    );
+    const val = valText
+      ? node(gauge, vertical ? `position:absolute;left:0;right:0;display:flex;justify-content:center;font-family:var(--kf-font-mono);font-size:${valPx}px;font-weight:700;color:var(--kf-on-accent);white-space:nowrap;font-variant-numeric:tabular-nums;line-height:1.2` : `position:absolute;top:0;bottom:0;display:flex;align-items:center;padding:0 ${Math.round(gh * 0.25)}px;font-family:var(--kf-font-mono);font-size:${valPx}px;font-weight:700;color:var(--kf-on-accent);white-space:nowrap;font-variant-numeric:tabular-nums`)
+      : null;
+    const costCss = `font-family:var(--kf-font-sans);font-size:${costPx}px;font-weight:800;color:var(--kf-ink);border:${Math.max(3, Math.round(4 * u))}px solid var(--kf-danger, var(--kf-ink));padding:0.08em 0.45em;line-height:1.2;white-space:nowrap`;
+    // 세로면 치르는 것은 계기 위 바깥, 위험 칸 바로 위 오른쪽에 — 계기 안에 두면 짚개 띠가 불투명한 계기 판 뒤로만 오가 화면이 안 바뀐다
+    const cost = c.cost ? node(vertical ? row : col, vertical ? `position:absolute;right:${Math.round((w * 0.92 - gw) / 2)}px;top:-${Math.round(costPx * 1.75)}px;${costCss}` : `align-self:flex-end;${costCss}`) : null;
+    kit.stage?.hero(gauge);
+
+    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초 안에 벽에 닿는다 — 장면이 길다고 느리게 차오르면 그 사이가 멈춘 화면이다
+    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 markFrom = hitAt + 0.2;
+
+    const writeLabel = slots.write(label, { ctx, text: c.label, at: 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);
+
+    return (t: number) => {
+      moving("limit.gauge", ctx);
+      writeLabel(t);
+      point(t, stops);
+      // 고른 빠르기로 차올라 벽에 부딪힌다 — 감속하면 부딪힘이 없고 끝자락이 멈춘 화면이 된다
+      const p = clamp((t - fillAt) / (hitAt - fillAt));
+      fill.style.transform = vertical ? `scaleY(${(p * wall).toFixed(4)})` : `scaleX(${(p * wall).toFixed(4)})`;
+      if (val && c.value !== undefined) {
+        val.textContent = `${p >= 1 ? fmt(c.value, dec) : fmt(c.value * p, dec)}${c.unit ? ` ${c.unit}` : ""}`;
+        // 세로면 값이 차오르는 면 꼭대기 바로 아래를 따라 오른다
+        if (vertical) val.style.top = `${Math.round(Math.min(gh * (1 - p * wall) + valPx * 0.25, gh - valPx * 1.35))}px`;
+        else val.style.left = "0";
+        val.style.visibility = p > 0.18 ? "visible" : "hidden";
+      }
+      danger.style.opacity = t >= hitAt ? String(0.28 + 0.5 * spring(t - hitAt, { from: 1, to: 0, stiffness: 200, damping: 12 })) : "0.28";
+      applyStyle(wallEl, landed(t));
+      if (cost) cost.style.visibility = t >= costAt ? "visible" : "hidden";
+      writeCost?.(t);
+    };
+  },
+};
+
+export default pattern;