kasaframe 0.0.0-stage → 0.1.3

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;

package/packages/patterns/src/list/cards.ts

@@ -0,0 +1,131 @@
+import { applyStyle, clamp, combine, spring } from "@kasaframe/core";
+import { fitSize, textEm } from "@kasaframe/motion/moves";
+import { area, cadence, node, slotsOf, spaced, moving } from "../kit.ts";
+import { objectCss, objectFor } from "../objects.ts";
+import type { Pattern } from "../types.ts";
+
+export interface ListContent {
+  items: { word: string; line?: string; icon?: string }[];
+  title?: string;
+}
+
+/**
+ * 낱말 카드가 박마다 하나씩 붙고, 그다음 차례마다 한 장씩 강조색으로 차오른다 — 차오름이 「지금 이 낱말」과 그 차례의 길이다.
+ * 낱말이 객체 사전의 물체면 그 모양을 카드 머리에 둔다(GPU 면 GPU 판). 장식은 두지 않는다 — 움직이는 것은 붙는 카드와 차오르는 차례뿐.
+ */
+const pattern: Pattern<ListContent> = {
+  id: "list.cards",
+  type: "list",
+  does: "낱말 카드가 박마다 붙고, 차례마다 한 장씩 강조색으로 차오른다",
+  energy: ["mid", "high"],
+  family: "pop",
+  camera: ["none"],
+  bg: "stage",
+  aspects: ["16:9", "9:16", "1:1"],
+  dur: { min: 2.5, max: 9 },
+  themes: { "kawaii-sticker": 0.6, "riso-zine": 0.3 },
+  fits(c) {
+    const items = c?.items;
+    if (!Array.isArray(items) || items.length < 2) return "items 가 둘보다 적다";
+    if (items.length > 5) return "items 가 다섯을 넘는다";
+    for (const [i, it] of items.entries()) {
+      if (typeof it?.word !== "string" || !it.word.trim()) return `items[${i}].word 가 비었다`;
+      if ([...it.word].length > 12) return `items[${i}].word 가 12자를 넘는다`;
+    }
+    return true;
+  },
+  build(root, ctx, c, kit) {
+    const slots = slotsOf(kit);
+    const { w, h, vertical, u } = area(ctx, kit);
+    const items = c.items;
+    const n = items.length;
+    const showLine = kit.policy !== "terms-only" && kit.policy !== "none";
+
+    const titlePx = Math.round(46 * u);
+    const top = c.title ? Math.round(titlePx * 1.9) : 0;
+    const gap = Math.round(28 * u);
+    const cols = vertical ? 1 : n;
+    const rows = vertical ? n : 1;
+    const gridW = w * 0.92;
+    const gridH = (h - top) * (vertical ? 0.94 : 0.66);
+    const cardW = (gridW - gap * (cols - 1)) / cols;
+    const cardH = (gridH - gap * (rows - 1)) / rows;
+    const x0 = (w - gridW) / 2;
+    const y0 = top + (h - top - gridH) / 2;
+
+    const host = node(root, "position:absolute;inset:0");
+    const title = c.title ? node(host, `position:absolute;left:${x0}px;top:${Math.round(titlePx * 0.4)}px;font-family:var(--kf-font-sans);font-size:${titlePx}px;font-weight:700;color:var(--kf-ink);white-space:nowrap`) : null;
+
+    // 낱말은 띄어쓰기에서 두 줄까지 — 가장 긴 덩이가 카드 폭에 들게
+    const pieces = items.flatMap((it) => (vertical ? [it.word] : it.word.split(/\s+/)));
+    const longest = pieces.reduce((a, p) => (textEm(p) > textEm(a) ? p : a), "");
+    const lines = vertical ? 1 : Math.max(...items.map((it) => Math.min(2, it.word.split(/\s+/).length)));
+    const wordPx = fitSize(longest, cardW * (vertical ? 0.62 : 0.8), (cardH * (vertical ? 0.5 : 0.36)) / lines, { hShare: 1, max: Math.round(170 * u), min: Math.round(40 * u) });
+    const linePx = Math.round(Math.max(30 * u, wordPx * 0.26));
+    const glyphPx = Math.round(Math.min(cardH * (vertical ? 0.5 : 0.3), wordPx * 1.4));
+
+    const hits = spaced(kit.hits.length ? kit.hits : [0], 0.3);
+    const enters = cadence(hits, n);
+    const walkFrom = enters[n - 1] + 0.3;
+    const turn = Math.max(0.3, (ctx.dur - walkFrom) / n);
+    // 차례 시작은 박에 붙인다 — 붙일 박이 없으면 고르게
+    const turns = items.map((_, i) => {
+      const want = walkFrom + i * turn;
+      const near = hits.find((b) => Math.abs(b - want) < turn * 0.3);
+      return near ?? want;
+    });
+    const ends = turns.map((s, i) => (i + 1 < n ? turns[i + 1] : ctx.dur - 1 / ctx.meta.fps));
+
+    const cards = items.map((it, i) => {
+      const col = vertical ? 0 : i;
+      const row = vertical ? i : 0;
+      const card = node(host, `position:absolute;left:${x0 + col * (cardW + gap)}px;top:${y0 + row * (cardH + gap)}px;width:${cardW}px;height:${cardH}px;transform-origin:50% 60%`);
+      const panel = slots.panel(card, { ctx, at: enters[i], seed: `${kit.seed}:card${i}` });
+      const fill = node(card, "position:absolute;inset:0;background:var(--kf-accent);border-radius:var(--kf-radius-md)");
+      const obj = objectFor(it.word) ?? (it.icon ? objectFor(it.icon) : null);
+      // 같은 내용을 두 벌 — 아래는 바탕색 위 글, 위는 강조색 위 글. 차오른 만큼만 위 벌이 보인다
+      const face = (onAccent: boolean) => {
+        const f = node(card, `position:absolute;inset:0;display:flex;flex-direction:${vertical ? "row" : "column"};align-items:center;justify-content:center;gap:${Math.round(wordPx * 0.25)}px;padding:${Math.round(wordPx * 0.3)}px;box-sizing:border-box;color:${onAccent ? "var(--kf-on-accent)" : "var(--kf-ink)"}`);
+        const head = obj
+          ? node(f, objectCss(obj, glyphPx))
+          : node(f, `font-family:var(--kf-font-mono);font-size:${Math.round(glyphPx * 0.55)}px;font-weight:700;color:${onAccent ? "var(--kf-on-accent)" : "var(--kf-accent)"}`, String(i + 1).padStart(2, "0"));
+        if (obj && onAccent) head.style.setProperty(obj.shape2d.outline ? "border-color" : "background", "var(--kf-on-accent)");
+        const text = node(f, `display:flex;flex-direction:column;align-items:${vertical ? "flex-start" : "center"};gap:${Math.round(linePx * 0.3)}px;min-width:0`);
+        const word = node(text, `font-family:var(--kf-font-display);font-size:${wordPx}px;font-weight:${ctx.style.type?.weightDisplay ?? 800};line-height:1.05;white-space:${vertical ? "nowrap" : "normal"};word-break:keep-all;text-align:${vertical ? "left" : "center"};min-height:${lines * 1.05}em`);
+        const line = showLine && it.line ? node(text, `font-family:var(--kf-font-sans);font-size:${linePx}px;line-height:1.25;opacity:.8;min-height:1.25em;text-align:${vertical ? "left" : "center"}`) : null;
+        return { f, word, line };
+      };
+      const base = face(false);
+      const lit = face(true);
+      const writes = [base, lit].flatMap((v) => [
+        slots.write(v.word, { ctx, text: it.word, at: enters[i] + 0.05, dur: 0.25, seed: `${kit.seed}:w${i}` }),
+        ...(v.line ? [slots.write(v.line, { ctx, text: it.line!, at: enters[i] + 0.2, dur: 0.35, seed: `${kit.seed}:l${i}` })] : []),
+      ]);
+      const landed = slots.land(card, { ctx, at: enters[i], seed: `${kit.seed}:land${i}` });
+      return { card, panel, fill, lit: lit.f, writes, landed };
+    });
+
+    const writeTitle = title ? slots.write(title, { ctx, text: c.title!, at: 0, dur: 0.35, seed: `${kit.seed}:title` }) : null;
+
+    return (t: number) => {
+      moving("list.cards", ctx);
+      cards.forEach((c2, i) => {
+        const at = enters[i];
+        const on = t >= at;
+        c2.card.style.visibility = on ? "visible" : "hidden";
+        if (!on) return;
+        const pop = spring(t - at, { from: 0.6, to: 1, stiffness: 300, damping: 15 });
+        applyStyle(c2.card, combine({ scale: pop }, c2.landed(t)));
+        c2.panel(t);
+        c2.writes.forEach((wr) => wr(t));
+        const p = clamp((t - turns[i]) / Math.max(0.05, ends[i] - turns[i]));
+        const clip = `inset(${((1 - p) * 100).toFixed(2)}% 0 0 0)`;
+        c2.fill.style.clipPath = clip;
+        c2.lit.style.clipPath = clip;
+      });
+      writeTitle?.(t);
+    };
+  },
+};
+
+export default pattern;

package/packages/patterns/src/list/cycle.ts

@@ -0,0 +1,22 @@
+import { wordsSlam } from "../words/moves.ts";
+import type { ListContent } from "./cards.ts";
+import type { Pattern } from "../types.ts";
+
+// 기능 낱말을 박마다 하나씩 띠를 꽉 채워 쾅 — 낱말 리듬(words.slam)과 같은 그림, 덧말은 소리·자막으로 간다
+const pattern: Pattern<ListContent> = {
+  ...(wordsSlam as unknown as Pattern<ListContent>),
+  id: "list.cycle",
+  type: "list",
+  does: "기능 낱말이 박마다 하나씩 띠를 꽉 채우며 쾅 — 판과 글색이 뒤집힌다",
+  fits(c) {
+    const items = c?.items;
+    if (!Array.isArray(items) || items.length < 2 || items.length > 5) return "items 가 둘에서 다섯이 아니다";
+    if (items.some((it) => typeof it?.word !== "string" || !it.word.trim() || [...it.word].length > 10)) return "낱말이 비었거나 10자를 넘는다";
+    return true;
+  },
+  build(root, ctx, c, kit) {
+    return wordsSlam.build(root, ctx, { words: c.items.map((it) => it.word) }, kit);
+  },
+};
+
+export default pattern;

package/packages/patterns/src/media/panels.ts

@@ -0,0 +1,100 @@
+import { applyStyle, clamp, rand, spring } from "@kasaframe/core";
+import { area, beatStops, cadence, moving, node, slotsOf } from "../kit.ts";
+import type { Pattern } from "../types.ts";
+
+export interface MediaContent {
+  /** assets 기준 그림 경로 */
+  assets: string[];
+  label?: string;
+}
+
+const grid = (n: number, vertical: boolean): [number, number] => {
+  const [c, r] = n <= 2 ? [2, 1] : n <= 4 ? [2, 2] : n <= 6 ? [3, 2] : n <= 9 ? [3, 3] : [4, 3];
+  return vertical ? [r, c] : [c, r];
+};
+
+/**
+ * 그림 여럿 — 칸이 박마다 하나씩 톡 붙어 격자를 채우고, 다 붙으면 「지금 볼 그림」이 박마다 다음 칸으로 옮겨 간다.
+ * 지금 칸은 또렷하고 나머지는 옅어진다 — 옮겨 가는 동안 내내 서서히 바뀌어 서지 않는다.
+ */
+const pattern: Pattern<MediaContent> = {
+  id: "media.panels",
+  type: "media",
+  does: "그림 칸이 박마다 붙어 격자를 채우고, 지금 볼 칸이 박마다 옮겨 가며 또렷해진다",
+  energy: ["mid", "high"],
+  family: "pop",
+  camera: ["none"],
+  bg: "stage",
+  aspects: ["16:9", "9:16", "1:1"],
+  dur: { min: 2.4, max: 10 },
+  themes: { "kawaii-sticker": 0.5 },
+  fits(c) {
+    const a = c?.assets;
+    if (!Array.isArray(a) || a.length < 2) return "그림이 둘보다 적다";
+    if (a.length > 12) return "그림이 열둘을 넘는다";
+    if (a.some((x) => typeof x !== "string" || !x.trim())) return "그림 경로가 비었다";
+    if (c.label && [...c.label].length > 30) return "label 이 30자를 넘는다";
+    return true;
+  },
+  build(root, ctx, c, kit) {
+    const slots = slotsOf(kit);
+    const { w, h, vertical, u } = area(ctx, kit);
+    const n = c.assets.length;
+    const [cols, rows] = grid(n, vertical);
+    const labelPx = c.label ? Math.round(Math.max(44 * u, Math.min(72 * u, h * 0.05))) : 0;
+    const gap = Math.round(20 * u);
+    const gw = w * 0.94;
+    const gh = h * 0.92 - (labelPx ? labelPx * 1.8 : 0);
+    const cw = (gw - gap * (cols - 1)) / cols;
+    const ch = (gh - gap * (rows - 1)) / rows;
+    const x0 = (w - gw) / 2;
+    const y0 = (h - gh - (labelPx ? labelPx * 1.8 : 0)) / 2;
+
+    const host = node(root, "position:absolute;inset:0");
+    const enters = cadence(kit.hits, n);
+    const panels = c.assets.map((src, i) => {
+      const x = x0 + (i % cols) * (cw + gap);
+      const y = y0 + Math.floor(i / cols) * (ch + gap);
+      const box = node(host, `position:absolute;left:${x}px;top:${y}px;width:${cw}px;height:${ch}px;transform-origin:50% 50%`);
+      const panel = slots.panel(box, { ctx, at: enters[i], seed: `${kit.seed}:p${i}` });
+      const img = node(box, `position:absolute;inset:${Math.round(8 * u)}px;background:center/cover no-repeat url("${ctx.asset(src)}")`);
+      const tilt = (rand(kit.seed, i) - 0.5) * 3;
+      return { box, panel, img, tilt };
+    });
+    const label = c.label ? node(host, `position:absolute;left:0;right:0;bottom:${Math.round(h * 0.03)}px;text-align:center;font-family:var(--kf-font-sans);font-size:${labelPx}px;font-weight:700;color:var(--kf-ink);white-space:nowrap;line-height:1.3;height:1.3em`) : null;
+    kit.stage?.hero(host);
+
+    const doneAt = enters[n - 1] + 0.3;
+    const stops = beatStops(kit.hits, doneAt, ctx.dur, 0.5);
+    const writeLabel = label ? slots.write(label, { ctx, text: c.label!, at: 0.1, dur: 0.35, seed: `${kit.seed}:label` }) : null;
+
+    return (t: number) => {
+      moving("media.panels", ctx);
+      writeLabel?.(t);
+      // 지금 볼 칸의 자리(정수 사이를 내내 오간다) — 다 붙기 전엔 마지막으로 붙은 칸
+      let focus = -1;
+      if (t >= stops[0]) {
+        let j = 0;
+        while (j + 1 < stops.length && stops[j + 1] <= t) j++;
+        const p = clamp((t - stops[j]) / Math.max(1e-3, (stops[j + 1] ?? stops[j] + 1) - stops[j]));
+        const e = 0.7 * p + 0.3 * p * p * (3 - 2 * p);
+        focus = (j % n) + e;
+      }
+      panels.forEach((p, i) => {
+        const on = t >= enters[i];
+        p.box.style.visibility = on ? "visible" : "hidden";
+        if (!on) return;
+        p.panel(t);
+        const pop = spring(t - enters[i], { from: 0.5, to: 1, stiffness: 300, damping: 15 });
+        // 지금 칸과의 거리(되돌아 이어지는 고리) — 가까울수록 또렷하고 살짝 앞으로
+        const d = focus < 0 ? 0 : Math.min(Math.abs(i - focus), Math.abs(i + n - focus), Math.abs(i - n - focus));
+        const near = focus < 0 ? 1 : clamp(1 - d);
+        applyStyle(p.box, { scale: pop * (1 + 0.05 * near), rotate: p.tilt * (1 - near) });
+        p.img.style.opacity = (0.35 + 0.65 * near).toFixed(3);
+        p.box.style.zIndex = String(Math.round(near * 10));
+      });
+    };
+  },
+};
+
+export default pattern;

package/packages/patterns/src/objects.ts

@@ -0,0 +1,234 @@
+import type { KfStyle } from "@kasaframe/core";
+
+// 객체 사전 — 내용 낱말 하나에 화면의 모양·색 하나. 「파란 칸 = KV 한 칸」처럼 같은 것은 2D 패턴·three·Blender 샷·공간 잇기 전환에서
+// 같은 색·같은 모양으로 이어진다. 화면에서 움직이는 것은 이 사전의 무엇 하나여야 한다(뜻 없는 판·방울·입자는 두지 않는다).
+// 색은 테마 토큰 이름으로만 — 테마가 바뀌면 같이 바뀌고, 한 영상 안에서는 늘 같은 색이다. DOM 을 만지지 않아 Node·Blender 내보내기에서도 읽는다.
+
+export type ColorToken = "accent" | "ink" | "inkSoft" | "dim" | "success" | "warning" | "danger" | "raised" | "line";
+
+/** 2D 모양 — 한 단위의 상자 비율(가로/세로)과 모서리 */
+export interface Shape2d {
+  kind: "cell" | "chip" | "dot" | "bar" | "card" | "ring" | "line" | "stack";
+  /** 가로/세로 */
+  aspect: number;
+  radius: "none" | "sm" | "md" | "pill";
+  /** 테두리만(속 빈) — 아직 안 찬 자리·자리표 */
+  outline?: boolean;
+}
+
+/** 3D 모양 — 같은 물체가 일어설 때. size 는 2D 한 단위 가로를 1 로 본 [가로, 높이, 깊이] */
+export interface Shape3d {
+  kind: "box" | "slab" | "sphere" | "cylinder" | "capsule" | "tile" | "torus";
+  size: readonly [number, number, number];
+  /** 모서리 둥글림(가로 대비 0..0.5) */
+  bevel: number;
+  /** 빛을 내나(발광 재질) */
+  glow?: boolean;
+}
+
+export interface VisualObject {
+  id: string;
+  /** 이 낱말이 나오면 이 물체 — 대소문자·띄어쓰기 무시 */
+  words: readonly string[];
+  /** 무엇을 뜻하나 한 줄 */
+  means: string;
+  color: ColorToken;
+  shape2d: Shape2d;
+  shape3d: Shape3d;
+  /** 수를 그릴 때 한 단위가 무엇인가(칸 하나 = 토큰 하나 따위) */
+  unit?: string;
+}
+
+export const OBJECTS: readonly VisualObject[] = [
+  {
+    id: "kv-cell",
+    words: ["KV", "KV 칸", "KV 캐시 칸", "kv cell", "key value", "키 값"],
+    means: "KV 캐시 한 칸 — 토큰 하나·층 하나가 남기는 키·값",
+    color: "accent",
+    shape2d: { kind: "cell", aspect: 0.58, radius: "none" },
+    shape3d: { kind: "box", size: [1, 1.72, 0.5], bevel: 0.04 },
+    unit: "토큰 하나의 키·값",
+  },
+  {
+    id: "kv-cache",
+    words: ["KV 캐시", "KV cache", "캐시", "cache", "prefix cache", "프리픽스 캐시"],
+    means: "KV 칸을 쌓은 더미 — 길어질수록 높아진다",
+    color: "accent",
+    shape2d: { kind: "stack", aspect: 0.58, radius: "none" },
+    shape3d: { kind: "box", size: [1, 1.72, 0.5], bevel: 0.04 },
+    unit: "KV 칸",
+  },
+  {
+    id: "latent",
+    words: ["latent", "잠재", "압축", "c_KV", "MLA", "low-rank", "저랭크"],
+    means: "눌러 담은 잠재 벡터 — KV 칸보다 얇다",
+    color: "accent",
+    shape2d: { kind: "cell", aspect: 0.3, radius: "none" },
+    shape3d: { kind: "slab", size: [0.5, 1.72, 0.5], bevel: 0.04 },
+  },
+  {
+    id: "rope",
+    words: ["RoPE", "로프", "위치", "position", "rotary"],
+    means: "위치 정보 반 칸 — 따로 들고 다니는 몫",
+    color: "warning",
+    shape2d: { kind: "cell", aspect: 0.29, radius: "none" },
+    shape3d: { kind: "slab", size: [0.5, 1.72, 0.5], bevel: 0.04 },
+  },
+  {
+    id: "token",
+    words: ["토큰", "token", "tokens", "낱말 조각"],
+    means: "글 조각 하나 — 줄지어 흐른다",
+    color: "ink",
+    shape2d: { kind: "chip", aspect: 1.8, radius: "sm" },
+    shape3d: { kind: "tile", size: [1.8, 1, 0.25], bevel: 0.12 },
+    unit: "토큰 하나",
+  },
+  {
+    id: "head",
+    words: ["head", "헤드", "어텐션 헤드", "attention head", "MHA", "GQA", "MQA"],
+    means: "어텐션 머리 하나 — 같은 줄의 칸을 따로 본다",
+    color: "inkSoft",
+    shape2d: { kind: "ring", aspect: 1, radius: "pill" },
+    shape3d: { kind: "torus", size: [1, 1, 0.25], bevel: 0 },
+  },
+  {
+    id: "layer",
+    words: ["층", "layer", "레이어", "transformer block", "블록"],
+    means: "모델 층 하나 — 얇은 판이 겹친다",
+    color: "dim",
+    shape2d: { kind: "bar", aspect: 6, radius: "sm" },
+    shape3d: { kind: "slab", size: [6, 0.2, 3], bevel: 0.02 },
+  },
+  {
+    id: "gpu",
+    words: ["GPU", "그래픽카드", "H100", "B200", "B300", "가속기", "accelerator"],
+    means: "계산하는 판 — 칸을 담는 그릇",
+    color: "ink",
+    shape2d: { kind: "card", aspect: 1.6, radius: "sm" },
+    shape3d: { kind: "slab", size: [3.2, 0.4, 2], bevel: 0.03 },
+  },
+  {
+    id: "memory",
+    words: ["메모리", "memory", "HBM", "VRAM", "GB", "용량"],
+    means: "GPU 메모리 — 칸이 차오르는 상자, 넘치면 위험색",
+    color: "line",
+    shape2d: { kind: "card", aspect: 0.7, radius: "sm", outline: true },
+    shape3d: { kind: "box", size: [3, 4.2, 1], bevel: 0.02 },
+    unit: "GB",
+  },
+  {
+    id: "request",
+    words: ["요청", "request", "호출", "call", "API 호출", "프롬프트", "prompt"],
+    means: "나가는 요청 하나 — 선을 따라 간다",
+    color: "accent",
+    shape2d: { kind: "dot", aspect: 1, radius: "pill" },
+    shape3d: { kind: "sphere", size: [1, 1, 1], bevel: 0.5, glow: true },
+  },
+  {
+    id: "response",
+    words: ["응답", "response", "답", "결과", "output", "출력"],
+    means: "돌아오는 응답 — 요청과 같은 모양, 성공색",
+    color: "success",
+    shape2d: { kind: "dot", aspect: 1, radius: "pill" },
+    shape3d: { kind: "sphere", size: [1, 1, 1], bevel: 0.5, glow: true },
+  },
+  {
+    id: "error",
+    words: ["오류", "에러", "error", "실패", "fail", "timeout", "429", "500"],
+    means: "실패한 요청 — 같은 점이 위험색으로",
+    color: "danger",
+    shape2d: { kind: "dot", aspect: 1, radius: "pill" },
+    shape3d: { kind: "sphere", size: [1, 1, 1], bevel: 0.5 },
+  },
+  {
+    id: "model",
+    words: ["모델", "model", "LLM", "엔진"],
+    means: "모델 하나 — 요청이 들어가 응답이 나오는 상자",
+    color: "ink",
+    shape2d: { kind: "card", aspect: 1, radius: "md" },
+    shape3d: { kind: "box", size: [2, 2, 2], bevel: 0.15 },
+  },
+  {
+    id: "server",
+    words: ["서버", "server", "노드", "node", "게이트웨이", "gateway", "라우터", "router"],
+    means: "요청이 지나는 마디",
+    color: "dim",
+    shape2d: { kind: "card", aspect: 0.8, radius: "sm" },
+    shape3d: { kind: "box", size: [1.6, 2, 1.2], bevel: 0.06 },
+  },
+  {
+    id: "latency",
+    words: ["지연", "latency", "TTFT", "ms", "속도", "시간"],
+    means: "걸린 시간 — 길이가 시간인 막대",
+    color: "warning",
+    shape2d: { kind: "bar", aspect: 8, radius: "pill" },
+    shape3d: { kind: "capsule", size: [8, 1, 1], bevel: 0.5 },
+    unit: "ms",
+  },
+  {
+    id: "cost",
+    words: ["비용", "cost", "가격", "price", "$", "원", "요금"],
+    means: "드는 돈 — 쌓이는 동전 기둥",
+    color: "warning",
+    shape2d: { kind: "dot", aspect: 1, radius: "pill", outline: true },
+    shape3d: { kind: "cylinder", size: [1, 0.18, 1], bevel: 0.02 },
+    unit: "동전 하나",
+  },
+  {
+    id: "user",
+    words: ["사용자", "user", "사람", "고객", "client", "클라이언트"],
+    means: "요청을 보내는 쪽",
+    color: "inkSoft",
+    shape2d: { kind: "dot", aspect: 1, radius: "pill", outline: true },
+    shape3d: { kind: "capsule", size: [1, 1.8, 1], bevel: 0.5 },
+  },
+  {
+    id: "document",
+    words: ["문서", "document", "파일", "file", "자료", "source", "출처"],
+    means: "읽어 들이는 글 묶음",
+    color: "raised",
+    shape2d: { kind: "card", aspect: 0.75, radius: "sm" },
+    shape3d: { kind: "slab", size: [0.75, 1, 0.06], bevel: 0.02 },
+  },
+];
+
+const norm = (s: string): string => s.toLowerCase().replace(/\s+/g, "");
+
+/** 낱말 → 물체. 가장 길게 맞은 낱말이 이긴다(「KV 캐시 칸」이 「KV 캐시」보다 먼저). 없으면 null — 패턴은 제 기본 모양으로 */
+export function objectFor(word: string | undefined | null): VisualObject | null {
+  if (!word) return null;
+  const w = norm(word);
+  let best: { o: VisualObject; len: number } | null = null;
+  for (const o of OBJECTS) {
+    for (const k of o.words) {
+      const n = norm(k);
+      if (n && w.includes(n) && (!best || n.length > best.len)) best = { o, len: n.length };
+    }
+  }
+  return best?.o ?? null;
+}
+
+export const objectById = (id: string): VisualObject | null => OBJECTS.find((o) => o.id === id) ?? null;
+
+/** 장면(브라우저 DOM)에서 — CSS 변수 이름 */
+export const cssColor = (token: ColorToken): string => `var(--kf-${token.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)})`;
+
+/** three·Blender 에서 — 그 테마 style 의 실제 색(#rrggbb). 토큰이 없으면 ink */
+export const styleColor = (style: Pick<KfStyle, "colors">, token: ColorToken): string => {
+  const c = style.colors as Record<string, string | undefined>;
+  return c[token] ?? c.ink ?? "#ffffff";
+};
+
+/** 2D 한 단위의 CSS — px 은 한 단위 높이 */
+export function objectCss(o: VisualObject, px: number): string {
+  const s = o.shape2d;
+  const w = Math.round(px * s.aspect);
+  const r = s.radius === "pill" ? "999px" : s.radius === "md" ? "var(--kf-radius-md)" : s.radius === "sm" ? "var(--kf-radius-sm)" : "0";
+  const c = cssColor(o.color);
+  return `width:${w}px;height:${Math.round(px)}px;border-radius:${r};box-sizing:border-box;` + (s.outline ? `border:${Math.max(2, Math.round(px * 0.06))}px solid ${c}` : `background:${c}`);
+}
+
+/** Blender·three 로 넘길 사전 한 벌 — 색은 그 테마 style 로 풀어 둔다. `node -e` 로 JSON 을 뽑아 kfb.py 가 읽는다 */
+export function objectsJson(style: Pick<KfStyle, "colors">): { id: string; words: readonly string[]; color: string; shape2d: Shape2d; shape3d: Shape3d }[] {
+  return OBJECTS.map((o) => ({ id: o.id, words: o.words, color: styleColor(style, o.color), shape2d: o.shape2d, shape3d: o.shape3d }));
+}