kasaframe 0.0.0-stage → 0.1.3

package/packages/motion/src/moves/imageSwarm.ts

@@ -0,0 +1,113 @@
+import { clamp, rand, safeTime, spring } from "@kasaframe/core";
+import { div, mark } from "./fit.ts";
+
+export interface ImageSwarmOpts {
+  /** 카드 그림들 — 모자라면 돌려 쓰고, 없으면 colors 로 칠한 카드 */
+  srcs?: string[];
+  colors?: string[];
+  /** 카드 안을 짓는다(그림 대신·위에 글 등) */
+  build?: (card: HTMLElement, i: number) => void;
+  count?: number;
+  /** 앉을 격자 */
+  grid: { cols: number; rows: number; x?: number; y?: number; w?: number; h?: number; gap?: number };
+  /** 흩어진 구름에서 격자로 모이기 시작하는 시각 */
+  gatherAt: number;
+  /** 카드마다 늦춤(초) */
+  stagger?: number;
+  /** 다시 흩어지는 시각 */
+  scatterAt?: number;
+  /** 한 장만 커져 화면을 채운다(다음 장면으로) */
+  hero?: { index: number; at: number };
+  radius?: number;
+  seed?: string | number;
+  w?: number;
+  h?: number;
+  scene?: string;
+}
+
+/**
+ * 그림 카드 떼 — 카드마다 흩어진 자리·기울기·깊이(시드)가 있어 구름처럼 떠다니다가, 차례로 스프링을 타고 벽돌 격자로 앉는다.
+ * 다시 흩어지거나 한 장만 커져 다음 장면이 된다. (Cosmos 공개 영상 1.5–3.6·20.5–22·34초)
+ */
+export function imageSwarm(el: HTMLElement, o: ImageSwarmOpts): (t: number) => void {
+  const doc = el.ownerDocument;
+  const W = o.w ?? 1920;
+  const H = o.h ?? 1080;
+  const gx = o.grid.x ?? W * 0.06;
+  const gy = o.grid.y ?? H * 0.12;
+  const gw = o.grid.w ?? W - gx * 2;
+  const gh = o.grid.h ?? H - gy * 1.4;
+  const gap = o.grid.gap ?? 14;
+  const cw = (gw - gap * (o.grid.cols - 1)) / o.grid.cols;
+  const ch = (gh - gap * (o.grid.rows - 1)) / o.grid.rows;
+  const n = Math.min(o.count ?? o.grid.cols * o.grid.rows, o.grid.cols * o.grid.rows);
+  const seed = o.seed ?? "swarm";
+  const colors = o.colors ?? ["#ff6b6b", "#ffd93d", "#6bcB77", "#4d96ff", "#c77dff", "#ff9a3c"];
+  const layer = div(doc, "position:absolute;inset:0;overflow:hidden");
+  el.append(layer);
+  const cards = Array.from({ length: n }, (_, i) => {
+    const r = (k: number) => rand(seed, i * 13 + k);
+    const card = div(doc, `position:absolute;left:0;top:0;width:${cw}px;height:${ch}px;border-radius:${o.radius ?? 10}px;overflow:hidden;background:${colors[i % colors.length]};box-shadow:0 10px 30px rgba(0,0,0,.25);will-change:transform`);
+    if (o.srcs?.length) {
+      const img = doc.createElement("img");
+      img.src = o.srcs[i % o.srcs.length];
+      img.style.cssText = "width:100%;height:100%;object-fit:cover;display:block";
+      card.append(img);
+    }
+    o.build?.(card, i);
+    layer.append(card);
+    // 벽돌 격자 — 홀수 줄은 4분의 1 칸 밀어 줄눈이 엇갈리게
+    const col = i % o.grid.cols;
+    const row = Math.floor(i / o.grid.cols);
+    const home = { x: gx + col * (cw + gap) + (row % 2 ? (cw + gap) / 4 : 0), y: gy + row * (ch + gap) };
+    const depth = r(0);
+    return {
+      card,
+      home,
+      // 구름 자리도 화면 안 — 화면 끝에 걸친 카드의 글이 잘린 채 떠 있지 않게(검사 text.offscreen)
+      cloud: { x: 60 + (W - cw * 1.3 - 120) * r(1), y: 40 + (H - ch * 1.3 - 80) * r(2), rot: (r(3) - 0.5) * 50, s: 0.55 + 0.75 * depth, blur: (1 - depth) * 4 },
+      drift: { x: (r(4) - 0.5) * 100, y: (r(5) - 0.5) * 70, phase: r(6) * 6.28 },
+      order: r(7),
+    };
+  });
+  const stagger = o.stagger ?? 0.025;
+  return (t: number) => {
+    t = safeTime(t);
+    let moving = false;
+    cards.forEach((c, i) => {
+      // 구름 자리 — 천천히 떠다닌다(닫힌 식이라 t 만으로)
+      const fx = c.cloud.x + c.drift.x * Math.sin(t * 0.9 + c.drift.phase);
+      const fy = c.cloud.y + c.drift.y * Math.cos(t * 0.7 + c.drift.phase);
+      const start = o.gatherAt + c.order * stagger * n;
+      // 거의 출렁이지 않게 — 여러 색 카드가 출렁이며 칸을 오가면 섬광 검사(frame.flash)에 걸린다
+      let g = spring(t - start, { stiffness: 140, damping: 22 });
+      if (o.scatterAt !== undefined) g -= spring(t - o.scatterAt - c.order * stagger * n * 0.5, { stiffness: 120, damping: 21 });
+      const x = fx + (c.home.x - fx) * g;
+      const y = fy + (c.home.y - fy) * g;
+      let rot = c.cloud.rot * (1 - g);
+      let s = c.cloud.s + (1 - c.cloud.s) * g;
+      let opacity = 1;
+      let tx = x;
+      let ty = y;
+      if (o.hero && t >= o.hero.at) {
+        const k = spring(t - o.hero.at, { stiffness: 160, damping: 20 });
+        if (i === o.hero.index) {
+          // 화면을 채운 뒤에도 천천히 다가간다 — 다음 장면이 된 카드가 멈춘 단색 화면이 되지 않게
+          const big = Math.max(W / cw, H / ch) * (1.02 + 0.12 * (t - o.hero.at));
+          tx = x + (W / 2 - cw / 2 - x) * k;
+          ty = y + (H / 2 - ch / 2 - y) * k;
+          s = s + (big - s) * k;
+          rot = rot * (1 - k);
+          c.card.style.zIndex = "99";
+        } else opacity = 1 - clamp(k * 1.4);
+      }
+      c.card.style.opacity = opacity.toFixed(3);
+      // 격자에 앉았는가(0·1) — 카드 안 글은 앉았을 때만 보이게 쓸 수 있다(흐리게 떠도는 카드 위 글은 대비 검사에 걸린다)
+      c.card.style.setProperty("--kf-seated", g > 0.92 ? "1" : "0");
+      c.card.style.filter = g < 0.98 ? `blur(${(c.cloud.blur * (1 - g)).toFixed(2)}px)` : "";
+      c.card.style.transform = `translate(${tx.toFixed(1)}px, ${ty.toFixed(1)}px) rotate(${rot.toFixed(2)}deg) scale(${s.toFixed(4)})`;
+      if (Math.abs(1 - g) > 0.01 && g > 0.01) moving = true;
+    });
+    mark("imageSwarm", o.scene, moving);
+  };
+}

package/packages/motion/src/moves/index.ts

@@ -0,0 +1,38 @@
+// 영상에서 모은 연출 수 — docs/references/opus-videos.md. 수마다 3–5초 예시: examples/moves/<이름>/
+export * from "./fit.ts";
+export * from "./slamWords.ts";
+export * from "./path.ts";
+export * from "./sparkTrail.ts";
+export * from "./pathText.ts";
+export * from "./ghostStack.ts";
+export * from "./echoStack.ts";
+export * from "./wordWall.ts";
+export * from "./tokenPicker.ts";
+export * from "./splitFlap.ts";
+export * from "./karaokeLine.ts";
+export * from "./stepWords.ts";
+export * from "./ransomLetters.ts";
+export * from "./tickerRows.ts";
+export * from "./strikeOut.ts";
+export * from "./worldRoll.ts";
+export * from "./markerWrite.ts";
+export * from "./neonSign.ts";
+export * from "./ledBoard.ts";
+export * from "./brushWipe.ts";
+export * from "./paperTear.ts";
+export * from "./irisBlades.ts";
+export * from "./flood.ts";
+export * from "./sunburst.ts";
+export * from "./speedLines.ts";
+export * from "./gridFloor.ts";
+export * from "./truchet.ts";
+export * from "./pointSphere.ts";
+export * from "./shapeMorph.ts";
+export * from "./panelPop.ts";
+export * from "./imageSwarm.ts";
+export * from "./liquidTab.ts";
+export * from "./cloneArray.ts";
+export * from "./curtains.ts";
+export * from "./morphBox.ts";
+export * from "./menu.ts";
+export * from "./dress.ts";

package/packages/motion/src/moves/irisBlades.ts

@@ -0,0 +1,113 @@
+import { safeTime } from "@kasaframe/core";
+import { mark } from "./fit.ts";
+import { springSteps } from "./liquidTab.ts";
+
+export interface IrisBladesOpts {
+  /** 조리개 가운데(px) */
+  x?: number;
+  y?: number;
+  /** 열림 정도가 바뀌는 시각 — 0 닫힘 · 1 완전히 열림(구멍 반지름 = radius) */
+  steps: { at: number; open: number }[];
+  /** 다 열렸을 때 구멍 반지름(px). 안 주면 화면 대각선의 반 — 다 열리면 화면이 드러난다 */
+  radius?: number;
+  /** 몸통 반지름(px) — 주면 날이 둥근 렌즈 안에만 있고 테두리 고리가 생긴다. 안 주면 화면 전체를 덮는다 */
+  housing?: number;
+  blades?: number;
+  color?: string;
+  /** 날 사이 금 색 */
+  seam?: string;
+  /** 닫힐수록 날이 도는 각(도) */
+  twist?: number;
+  w?: number;
+  h?: number;
+  stiffness?: number;
+  damping?: number;
+  scene?: string;
+}
+
+/**
+ * 여섯 날 조리개 — 날마다 곧은 가장자리가 구멍의 변을 이루고 그 너머로 길게 뻗어 서로 겹친다. 열림 정도를 스프링으로 옮기며
+ * 닫힐수록 날이 돈다. 둥근 구멍만 여는 GL circleopen 과 달리 날이 보인다. (twoclipping 공개 영상 2.3–3.2초)
+ */
+export function irisBlades(el: HTMLElement, o: IrisBladesOpts): (t: number) => void {
+  const doc = el.ownerDocument;
+  const W = o.w ?? 1920;
+  const H = o.h ?? 1080;
+  const cx = o.x ?? W / 2;
+  const cy = o.y ?? H / 2;
+  const n = o.blades ?? 6;
+  const R = o.radius ?? Math.hypot(W, H) / 2;
+  const far = Math.hypot(W, H) * 1.5;
+  const twist = ((o.twist ?? 40) * Math.PI) / 180;
+  const NS = "http://www.w3.org/2000/svg";
+  const svg = doc.createElementNS(NS, "svg");
+  svg.setAttribute("width", String(W));
+  svg.setAttribute("height", String(H));
+  svg.setAttribute("viewBox", `0 0 ${W} ${H}`);
+  svg.style.cssText = "position:absolute;left:0;top:0;overflow:visible";
+  const g = doc.createElementNS(NS, "g");
+  if (o.housing) {
+    const id = `iris-clip-${Math.round(cx)}-${Math.round(cy)}-${Math.round(o.housing)}`;
+    const defs = doc.createElementNS(NS, "defs");
+    const clip = doc.createElementNS(NS, "clipPath");
+    clip.setAttribute("id", id);
+    const c = doc.createElementNS(NS, "circle");
+    c.setAttribute("cx", String(cx));
+    c.setAttribute("cy", String(cy));
+    c.setAttribute("r", String(o.housing));
+    clip.append(c);
+    defs.append(clip);
+    svg.append(defs);
+    g.setAttribute("clip-path", `url(#${id})`);
+  }
+  svg.append(g);
+  const polys = Array.from({ length: n }, (_, i) => {
+    const p = doc.createElementNS(NS, "polygon");
+    p.setAttribute("fill", o.color ?? "var(--kf-ink)");
+    p.setAttribute("stroke", o.seam ?? "rgba(255,255,255,.28)");
+    p.setAttribute("stroke-width", "3");
+    p.setAttribute("stroke-linejoin", "round");
+    // 날마다 아주 조금 다른 밝기 — 겹친 날이 한 덩어리로 뭉개지지 않게
+    p.style.filter = `brightness(${(0.92 + 0.16 * (i % 2)).toFixed(2)})`;
+    g.append(p);
+    return p;
+  });
+  let ring: SVGCircleElement | null = null;
+  if (o.housing) {
+    ring = doc.createElementNS(NS, "circle");
+    ring.setAttribute("cx", String(cx));
+    ring.setAttribute("cy", String(cy));
+    ring.setAttribute("r", String(o.housing));
+    ring.setAttribute("fill", "none");
+    ring.setAttribute("stroke", o.color ?? "var(--kf-ink)");
+    ring.setAttribute("stroke-width", "14");
+    svg.append(ring);
+  }
+  el.append(svg);
+  const steps = o.steps.map((s) => ({ at: s.at, to: s.open }));
+  const step = (2 * Math.PI) / n;
+  return (t: number) => {
+    t = safeTime(t);
+    const open = Math.max(0, springSteps(t, steps, { stiffness: o.stiffness ?? 200, damping: o.damping ?? 24 }));
+    const r = Math.max(0.5, R * open);
+    const rot = twist * (1 - Math.min(1, open));
+    // 꼭짓점 V_i 와 그 변의 방향·바깥 법선을 각으로 바로 셈한다 — 닫혀 r→0 이어도 방향이 흐트러지지 않는다
+    polys.forEach((p, i) => {
+      const a = i * step + rot - Math.PI / 2;
+      const vx = cx + r * Math.cos(a);
+      const vy = cy + r * Math.sin(a);
+      const dir = a + Math.PI / 2 + step / 2;
+      const nor = a + step / 2;
+      const edge = 2 * r * Math.sin(step / 2);
+      const back = 0.15 * edge + 2;
+      // 날의 곧은 변은 다음 꼭짓점 너머 화면 밖까지 — 짧으면 거의 닫혔을 때 먼 구석이 덮이지 않는다
+      const fwd = far;
+      const p0 = [vx - back * Math.cos(dir), vy - back * Math.sin(dir)];
+      const p1 = [vx + fwd * Math.cos(dir), vy + fwd * Math.sin(dir)];
+      const p2 = [p1[0] + far * Math.cos(nor), p1[1] + far * Math.sin(nor)];
+      const p3 = [p0[0] + far * Math.cos(nor), p0[1] + far * Math.sin(nor)];
+      p.setAttribute("points", [p0, p1, p2, p3].map(([x, y]) => `${x.toFixed(1)},${y.toFixed(1)}`).join(" "));
+    });
+    mark("irisBlades", o.scene, o.steps.some((s) => t >= s.at && t < s.at + 0.5));
+  };
+}

package/packages/motion/src/moves/karaokeLine.ts

@@ -0,0 +1,108 @@
+import { clamp, ease, lerp, safeTime } from "@kasaframe/core";
+import { div, mark } from "./fit.ts";
+
+export interface KaraokeLine {
+  /** 낱말들(빈칸으로 나눈 가사 한 줄) */
+  words: string[];
+  /** 낱말마다 부르기 시작하는 시각(장면 초). 없으면 from–to 를 글자 수로 나눈다 */
+  times?: number[];
+  from?: number;
+  to?: number;
+}
+
+export interface KaraokeLineOpts {
+  lines: KaraokeLine[];
+  size?: number;
+  /** 띠 가운데 높이(px) — 기본 화면 아래 12% */
+  y?: number;
+  /** 줄이 부르기 전에 미리 떠 있는 초 */
+  lead?: number;
+  w?: number;
+  h?: number;
+  scene?: string;
+}
+
+/**
+ * 부른 데까지 차오르는 가사 띠 — 줄은 부르기 전에 미리 읽히게 떠 있고, 낱말마다 부르는 동안 왼쪽부터 강조색이 찬다. 줄이 끝나면 위로 빠진다.
+ * (Claude Pop p(doom) 38.8–41초 아래 띠 · Crab Walk 아래 줄 · Moonlight in Code 「부르기 2프레임 전에 읽히게」)
+ */
+export function karaokeLine(el: HTMLElement, o: KaraokeLineOpts): (t: number) => void {
+  const doc = el.ownerDocument;
+  const W = o.w ?? 1920;
+  const H = o.h ?? 1080;
+  const size = o.size ?? 64;
+  const y = o.y ?? H * 0.88;
+  const lead = o.lead ?? 0.3;
+  const layer = div(doc, "position:absolute;inset:0;overflow:hidden;pointer-events:none");
+  el.append(layer);
+  // 낱말 시각 — 없으면 줄 길이를 글자 수 비율로 편다
+  const timed = o.lines.map((l) => {
+    if (l.times && l.times.length >= l.words.length) return { words: l.words, times: l.times, end: l.to ?? l.times[l.times.length - 1] + 0.6 };
+    const from = l.from ?? 0;
+    const to = l.to ?? from + 2;
+    const total = l.words.reduce((a, w) => a + w.length, 0) || 1;
+    let acc = 0;
+    const times = l.words.map((w) => {
+      const s = from + ((to - from) * acc) / total;
+      acc += w.length;
+      return s;
+    });
+    return { words: l.words, times, end: to };
+  });
+  const rows = timed.map((l) => {
+    const band = div(
+      doc,
+      `position:absolute;left:50%;top:${y}px;display:flex;gap:.3em;white-space:nowrap;padding:.22em .6em;border-radius:.5em;` +
+        `background:rgba(10,10,14,.72);font-family:var(--kf-font-display);font-weight:800;font-size:${size}px;line-height:1.1;color:rgba(242,243,245,.42)`,
+    );
+    // 지금 부르는 낱말 뒤 알약 — 낱말에서 낱말로 옮겨 가며 부르는 자리를 짚는다. 안 부른 글은 흐리게 둬 차오름이 밝기로도 보인다
+    const pill = div(doc, "position:absolute;left:0;top:.12em;height:1.3em;border-radius:.4em;background:color-mix(in srgb, var(--kf-accent) 30%, transparent)");
+    band.append(pill);
+    const spans: HTMLDivElement[] = [];
+    const words = l.words.map((w) => {
+      const span = div(doc, "position:relative;display:inline-block", w);
+      const fill = div(doc, "position:absolute;left:0;top:0;color:var(--kf-accent)", w);
+      span.append(fill);
+      band.append(span);
+      spans.push(span);
+      return fill;
+    });
+    layer.append(band);
+    return { band, words, pill, spans };
+  });
+
+  return (t: number) => {
+    t = safeTime(t);
+    let moving = false;
+    rows.forEach((r, i) => {
+      const l = timed[i];
+      const start = l.times[0] - lead;
+      const next = timed[i + 1] ? timed[i + 1].times[0] - lead : l.end + 0.3;
+      const inP = ease.outCubic(clamp((t - start) / 0.2));
+      const outP = ease.inCubic(clamp((t - next) / 0.2));
+      const shown = t >= start && outP < 1;
+      r.band.style.display = shown ? "flex" : "none";
+      if (!shown) return;
+      if (inP < 1 || outP > 0) moving = true;
+      r.band.style.opacity = (inP * (1 - outP)).toFixed(3);
+      r.band.style.transform = `translate(-50%, ${(-50 + 40 * (1 - inP) - 60 * outP).toFixed(1)}%)`;
+      let k = 0;
+      r.words.forEach((f, j) => {
+        const a = l.times[j];
+        const b = Math.min(l.times[j + 1] ?? l.end, a + 0.6);
+        const p = clamp((t - a) / Math.max(0.05, b - a));
+        if (p > 0 && p < 1) moving = true;
+        if (t >= a) k = j;
+        f.style.clipPath = `inset(0 ${((1 - p) * 100).toFixed(2)}% 0 0)`;
+      });
+      // 알약은 부르는 낱말 자리로 미끄러져 간다 — 앞 낱말 자리에서 0.18초에 걸쳐
+      const cur = r.spans[k];
+      const prev = r.spans[Math.max(0, k - 1)];
+      const m = k > 0 ? ease.outCubic(clamp((t - l.times[k]) / 0.18)) : 1;
+      const pad = size * 0.18;
+      r.pill.style.transform = `translateX(${(lerp(prev.offsetLeft, cur.offsetLeft, m) - pad).toFixed(1)}px)`;
+      r.pill.style.width = `${(lerp(prev.offsetWidth, cur.offsetWidth, m) + pad * 2).toFixed(1)}px`;
+    });
+    mark("karaokeLine", o.scene, moving);
+  };
+}

package/packages/motion/src/moves/ledBoard.ts

@@ -0,0 +1,94 @@
+import { safeTime } from "@kasaframe/core";
+import { div, mark } from "./fit.ts";
+
+export interface LedBoardOpts {
+  text: string;
+  /** scroll: 오른쪽에서 흘러 들어와 지나간다 · type: 왼쪽부터 한 칸씩 찍힌다 */
+  mode?: "scroll" | "type";
+  at?: number;
+  /** 초당 몇 칸(점 열) */
+  speed?: number;
+  /** 글자 높이(점 줄 수) */
+  rows?: number;
+  /** 판(무대 px) */
+  x?: number;
+  y?: number;
+  w?: number;
+  h?: number;
+  color?: string;
+  stageW?: number;
+  stageH?: number;
+  scene?: string;
+}
+
+/**
+ * LED 점 글판 — 글을 점 격자로 찍어 켜진 점만 번지게 칠한다. 흘러가거나(scroll) 한 칸씩 찍힌다(type). 꺼진 점도 희미하게 보인다.
+ * (Ghost in the Booth 12.5–15초 극장 앞 글판)
+ */
+export function ledBoard(el: HTMLElement, o: LedBoardOpts): (t: number) => void {
+  const doc = el.ownerDocument;
+  const SW = o.stageW ?? 1920;
+  const SH = o.stageH ?? 1080;
+  const bw = o.w ?? SW * 0.9;
+  const bh = o.h ?? SH * 0.36;
+  const bx = o.x ?? (SW - bw) / 2;
+  const by = o.y ?? (SH - bh) / 2;
+  const rows = o.rows ?? 16;
+  const pitch = bh / (rows + 2);
+  const cols = Math.floor(bw / pitch);
+  const color = o.color ?? "#FFB23E";
+  const at = o.at ?? 0;
+  const speed = o.speed ?? 40;
+  const wrap = div(doc, `position:absolute;left:${bx}px;top:${by}px;width:${bw}px;height:${bh}px;background:#0B0B0D;border-radius:${pitch}px;box-shadow:0 0 0 ${pitch * 0.6}px #1A1A1F`);
+  const cv = doc.createElement("canvas");
+  cv.width = Math.round(bw);
+  cv.height = Math.round(bh);
+  cv.style.cssText = "position:absolute;inset:0;width:100%;height:100%";
+  wrap.append(cv);
+  el.append(wrap);
+  const g = cv.getContext("2d")!;
+  // 글자 점 지도 — 글꼴이 다 받아진 뒤(처음 그릴 때) 한 번 찍는다
+  let map: Uint8Array | null = null;
+  let mapW = 0;
+  const raster = () => {
+    const font = getComputedStyle(doc.documentElement).getPropertyValue("--kf-font-mono").trim() || "monospace";
+    const off = doc.createElement("canvas");
+    const fx = off.getContext("2d")!;
+    fx.font = `700 ${rows}px ${font}`;
+    mapW = Math.ceil(fx.measureText(o.text).width) + 2;
+    off.width = mapW;
+    off.height = rows;
+    fx.font = `700 ${rows}px ${font}`;
+    fx.textBaseline = "middle";
+    fx.fillStyle = "#fff";
+    fx.fillText(o.text, 1, rows / 2 + 1);
+    const data = fx.getImageData(0, 0, mapW, rows).data;
+    map = new Uint8Array(mapW * rows);
+    for (let i = 0; i < mapW * rows; i++) map[i] = data[i * 4 + 3] > 110 ? 1 : 0;
+  };
+
+  return (t: number) => {
+    t = safeTime(t);
+    if (!map) raster();
+    const local = Math.max(0, t - at);
+    const typing = o.mode === "type";
+    const shift = typing ? 0 : Math.floor(cols - local * speed);
+    const shown = typing ? Math.floor(local * speed) : Infinity;
+    g.clearRect(0, 0, cv.width, cv.height);
+    const r = pitch * 0.36;
+    for (let cy = 0; cy < rows; cy++)
+      for (let cx = 0; cx < cols; cx++) {
+        const mx = cx - shift;
+        const on = t >= at && mx >= 0 && mx < mapW && mx < shown && map![cy * mapW + mx] === 1;
+        g.fillStyle = on ? color : "rgba(255,255,255,.06)";
+        if (on) {
+          g.shadowColor = color;
+          g.shadowBlur = pitch * 0.9;
+        } else g.shadowBlur = 0;
+        g.beginPath();
+        g.arc(pitch * (cx + 0.5), pitch * (cy + 1.5), r, 0, Math.PI * 2);
+        g.fill();
+      }
+    mark("ledBoard", o.scene, t >= at);
+  };
+}

package/packages/motion/src/moves/liquidTab.ts

@@ -0,0 +1,72 @@
+import { safeTime, spring } from "@kasaframe/core";
+import { mark } from "./fit.ts";
+
+export interface SpringStep {
+  /** 목표가 바뀌는 시각(장면 초) */
+  at: number;
+  to: number;
+  /** 이 걸음만 강성을 바꾼다 */
+  stiffness?: number;
+}
+
+export interface SpringStepsOpts {
+  /** 첫 걸음 전 값. 안 주면 첫 걸음의 to 에서 움직이지 않고 시작한다 */
+  from?: number;
+  stiffness?: number;
+  damping?: number;
+  mass?: number;
+}
+
+/**
+ * 목표가 여러 번 바뀌는 값 — 바뀔 때마다 0→1 스프링 하나를 그 차이만큼 더한다. 앞 프레임 상태가 없는 닫힌 식이라
+ * 아무 t 로 건너뛰어도 같은 값이고, 움직이는 도중에 목표가 바뀌어도 속도가 이어져 보인다.
+ */
+export function springSteps(t: number, steps: readonly SpringStep[], o: SpringStepsOpts = {}): number {
+  t = safeTime(t);
+  if (!steps.length) return o.from ?? 0;
+  let prev = o.from ?? steps[0].to;
+  let v = prev;
+  for (const s of steps) {
+    const k = spring(t - s.at, { from: 0, to: 1, stiffness: s.stiffness ?? o.stiffness ?? 220, damping: o.damping ?? 22, mass: o.mass ?? 1 });
+    v += (s.to - prev) * k;
+    prev = s.to;
+  }
+  return v;
+}
+
+export interface LiquidTabOpts {
+  /** 탭마다 왼쪽 끝과 폭(px) */
+  tabs: { x: number; w: number }[];
+  /** 고른 탭이 바뀌는 시각과 그 번호 */
+  steps: { at: number; index: number }[];
+  /** 앞서 가는 가장자리 강성 — 크면 먼저 튀어 나간다 */
+  lead?: number;
+  /** 따라오는 가장자리 강성 */
+  trail?: number;
+  damping?: number;
+  scene?: string;
+}
+
+/**
+ * 두 가장자리 스프링 탭 — 표시가 옮겨 갈 때 가는 쪽 가장자리가 먼저 늘어나고 뒤 가장자리가 따라와 물방울처럼 늘었다 줄어든다.
+ * 토글 손잡이·슬라이더 손잡이도 같은 수(탭 둘). (Raphael Aubry UI 릴 9.0–9.8초)
+ */
+export function liquidTab(t: number, o: LiquidTabOpts): { left: number; right: number; x: number; w: number } {
+  t = safeTime(t);
+  const lead = o.lead ?? 420;
+  const trail = o.trail ?? 140;
+  const at = (i: number) => o.tabs[Math.max(0, Math.min(o.tabs.length - 1, i))];
+  const leftSteps: SpringStep[] = [];
+  const rightSteps: SpringStep[] = [];
+  let prev = o.steps[0]?.index ?? 0;
+  for (const s of o.steps) {
+    const right = at(s.index).x > at(prev).x;
+    leftSteps.push({ at: s.at, to: at(s.index).x, stiffness: right ? trail : lead });
+    rightSteps.push({ at: s.at, to: at(s.index).x + at(s.index).w, stiffness: right ? lead : trail });
+    prev = s.index;
+  }
+  const left = springSteps(t, leftSteps, { damping: o.damping ?? 20 });
+  const right = springSteps(t, rightSteps, { damping: o.damping ?? 20 });
+  mark("liquidTab", o.scene, o.steps.some((s, i) => i > 0 && t >= s.at && t < s.at + 0.5));
+  return { left, right: Math.max(left + 1, right), x: left, w: Math.max(1, right - left) };
+}

package/packages/motion/src/moves/markerWrite.ts

@@ -0,0 +1,63 @@
+import { clamp, ease, noise1, safeTime } from "@kasaframe/core";
+import { div, mark, textEm } from "./fit.ts";
+
+export interface MarkerWriteOpts {
+  text: string;
+  /** 쓰기 시작하는 시각(장면 초) */
+  at?: number;
+  /** 다 쓰는 데 드는 초 — 없으면 글자당 0.09초 */
+  dur?: number;
+  /** 글 왼쪽 위(무대 px) */
+  x: number;
+  y: number;
+  size?: number;
+  color?: string;
+  /** 손글씨 글꼴 — 프로젝트 style 에 불러 둔 것. 없으면 화면 글꼴 */
+  font?: string;
+  /** 기울기(도) */
+  tilt?: number;
+  seed?: string | number;
+  scene?: string;
+}
+
+/**
+ * 마커로 써지는 글 — 글이 왼쪽부터 드러나고 마커 촉이 그 끝을 따라 위아래로 움직이며 간다. 획 순서는 안 따르고 쓰는 손의 흐름만 흉내 낸다.
+ * (mexicat p(doom) 80.4초 「obsolete」 필기 · Nothing Went Foom 155–186초 화이트보드)
+ */
+export function markerWrite(el: HTMLElement, o: MarkerWriteOpts): (t: number) => void {
+  const doc = el.ownerDocument;
+  const size = o.size ?? 120;
+  const at = o.at ?? 0;
+  const dur = o.dur ?? Math.max(0.3, [...o.text].length * 0.09);
+  const seed = o.seed ?? o.text;
+  const width = textEm(o.text) * size * 1.05;
+  const color = o.color ?? "var(--kf-accent)";
+  const box = div(doc, `position:absolute;left:${o.x}px;top:${o.y}px;transform:rotate(${o.tilt ?? -3}deg);transform-origin:0 50%`);
+  const ink = div(
+    doc,
+    `position:relative;white-space:nowrap;font-family:${o.font ?? "var(--kf-font-display)"};font-size:${size}px;line-height:1.1;color:${color}`,
+    o.text,
+  );
+  // 마커 촉 — 둥근 몸통 + 색 끝
+  const pen = div(doc, `position:absolute;left:0;top:0;width:${size * 0.22}px;height:${size * 1.1}px;border-radius:${size * 0.06}px;background:#E9E9EC;box-shadow:0 ${size * 0.05}px ${size * 0.12}px rgba(0,0,0,.35);transform-origin:50% 100%`);
+  const tip = div(doc, `position:absolute;left:18%;right:18%;bottom:-${size * 0.08}px;height:${size * 0.14}px;border-radius:0 0 ${size * 0.05}px ${size * 0.05}px;background:${color}`);
+  pen.append(tip);
+  box.append(ink, pen);
+  el.append(box);
+
+  return (t: number) => {
+    t = safeTime(t);
+    const p = ease.inOutQuad(clamp((t - at) / dur));
+    // 글자 끝에서 조금 덜 드러나 촉이 막 쓰는 자리를 덮는다
+    ink.style.clipPath = `inset(-20% ${((1 - p) * 100).toFixed(2)}% -20% 0)`;
+    const writing = p > 0 && p < 1;
+    const x = width * p;
+    const bob = writing ? noise1(seed, t * 9) * size * 0.28 : 0;
+    const after = Math.max(0, t - at - dur);
+    // 다 쓴 뒤 촉은 들려 비켜난다
+    const lift = ease.outCubic(clamp(after / 0.35));
+    pen.style.opacity = t < at - 0.15 ? "0" : String(1 - lift);
+    pen.style.transform = `translate(${(x - size * 0.11 + lift * size * 0.6).toFixed(1)}px,${(-size * 0.55 + bob - lift * size * 0.5).toFixed(1)}px) rotate(${(24 + 6 * Math.sin(t * 7)).toFixed(2)}deg)`;
+    mark("markerWrite", o.scene, writing);
+  };
+}