kasaframe 0.1.1 → 0.1.3

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

package/packages/patterns/src/quote/karaoke.ts

@@ -0,0 +1,126 @@
+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 type { Pattern, SpokenWord } from "../types.ts";
+
+export interface QuoteContent {
+  text: string;
+  who?: string;
+  role?: string;
+}
+
+const norm = (s: string) => s.replace(/[^\p{L}\p{N}]/gu, "").toLowerCase();
+
+// 들리는 낱말 시각을 문장 낱말에 차례로 짝짓는다 — 못 맞추면 글자 수 비율로 고르게
+function timing(words: string[], say: SpokenWord[], from: number, to: number): [number, number][] {
+  const out: [number, number][] = [];
+  let k = 0;
+  for (const wd of words) {
+    const key = norm(wd);
+    let hit = -1;
+    for (let j = k; j < Math.min(say.length, k + 4); j++) if (key && norm(say[j].text).includes(key.slice(0, 2))) { hit = j; break; }
+    if (hit < 0) return even(words, from, to);
+    out.push([say[hit].from, say[hit].to]);
+    k = hit + 1;
+  }
+  return out;
+}
+
+function even(words: string[], from: number, to: number): [number, number][] {
+  const total = words.reduce((a, w) => a + [...w].length, 0) || 1;
+  let at = from;
+  return words.map((w) => {
+    const d = ((to - from) * [...w].length) / total;
+    const r: [number, number] = [at, at + d];
+    at += d;
+    return r;
+  });
+}
+
+/**
+ * 인용 — 문장은 처음부터 다 떠 있고, 들리는 낱말(kit.say)마다 반전 칸이 그 낱말을 왼쪽부터 채운다(내레이션이 없으면 글자 수 비율로).
+ * 끝자락에 누가 말했는지가 찍힌다. 움직이는 것은 「지금 읽는 낱말」 하나.
+ */
+const pattern: Pattern<QuoteContent> = {
+  id: "quote.karaoke",
+  type: "quote",
+  does: "문장이 떠 있고 들리는 낱말마다 반전 칸이 채워 간다, 끝에 누가 말했는지가 찍힌다",
+  energy: ["low", "mid"],
+  family: "type",
+  camera: ["none"],
+  bg: "stage",
+  aspects: ["16:9", "9:16", "1:1"],
+  dur: { min: 2.4, max: 10 },
+  fits(c) {
+    if (typeof c?.text !== "string" || !c.text.trim()) return "text 가 비었다";
+    if ([...c.text].length > 60) return "text 가 60자를 넘는다";
+    if (c.text.trim().split(/\s+/).length < 2) return "낱말이 하나뿐이다 — words 로";
+    return true;
+  },
+  build(root, ctx, c, kit) {
+    const slots = slotsOf(kit);
+    const { w, h, vertical, u } = area(ctx, kit);
+    const words = c.text.trim().split(/\s+/);
+    // 줄 수를 어림해 글 크기를 고른다 — 넓이에 맞춰 두세 줄
+    const em = textEm(c.text);
+    const boxW = w * (vertical ? 0.88 : 0.84);
+    const boxH = h * (vertical ? 0.5 : 0.56);
+    let px = 40 * u;
+    for (let s = Math.round(210 * u); s >= 40 * u; s -= 4) {
+      const lines = Math.ceil((em * s * 1.08) / boxW);
+      if (lines * s * 1.3 <= boxH && lines <= 4) {
+        px = s;
+        break;
+      }
+    }
+    const whoPx = Math.round(Math.max(36 * u, px * 0.34));
+
+    const host = node(root, "position:absolute;inset:0;display:flex;align-items:center;justify-content:center");
+    const col = node(host, `display:flex;flex-direction:column;align-items:flex-start;gap:${Math.round(px * 0.3)}px;width:${boxW}px`);
+    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 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 };
+    });
+    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;
+
+    const whoDur = whoText ? clamp([...whoText].length * 0.04, 0.3, 0.7) : 0;
+    // 첫 프레임부터 읽기 시작한다 — 문장이 다 떠 있는 채로 서 있으면 멈춘 화면이다
+    const readFrom = 0;
+    // 목소리가 없으면 말하는 빠르기(글자당 0.13초)로 읽는다 — 장면 길이에 맞춰 늘이면 긴 장면에서 칸이 기어가 멈춘 화면이 된다
+    const chars = words.reduce((a, wd) => a + [...wd].length, 0);
+    const readTo = Math.min(ctx.dur - 0.05, Math.max(1.2, chars * 0.13));
+    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 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)`;
+      });
+      writeWho?.(t);
+      // 짚는 동안은 낱말 반전 칸을 걷는다 — 두 강조가 겹치면 무엇을 짚는지 흐려진다
+      if (t >= readEnd + 0.05) spans.forEach((x) => (x.hi.style.visibility = "hidden"));
+      point(t, stops);
+    };
+  },
+};
+
+export default pattern;

package/packages/patterns/src/quote/slam.ts

@@ -0,0 +1,22 @@
+import { wordsSlam } from "../words/moves.ts";
+import type { QuoteContent } from "./karaoke.ts";
+import type { Pattern } from "../types.ts";
+
+// 짧고 센 한 마디 — 낱말이 박마다 하나씩 띠를 꽉 채우며 쾅(낱말 리듬과 같은 그림). 누가 말했는지는 소리·자막으로 간다
+const pattern: Pattern<QuoteContent> = {
+  ...(wordsSlam as unknown as Pattern<QuoteContent>),
+  id: "quote.slam",
+  type: "quote",
+  does: "짧은 한 마디의 낱말이 박마다 하나씩 띠를 꽉 채우며 쾅",
+  fits(c) {
+    const ws = (c?.text ?? "").trim().split(/\s+/).filter(Boolean);
+    if (ws.length < 2 || ws.length > 6) return "낱말이 둘에서 여섯이 아니다 — 긴 문장은 quote.karaoke";
+    if (ws.some((x) => [...x].length > 10)) return "낱말 하나가 10자를 넘는다";
+    return true;
+  },
+  build(root, ctx, c, kit) {
+    return wordsSlam.build(root, ctx, { words: c.text.trim().split(/\s+/) }, kit);
+  },
+};
+
+export default pattern;