kasaframe 0.1.1 → 0.1.4

package/themes/manga-panel/effects.ts

@@ -0,0 +1,791 @@
+// 테마 manga-panel 전용 효과 — 정보가 만화 한 쪽의 칸으로 나뉘어 그려지고, 결정타에 집중선이 터진다.
+// 같은 t 면 같은 화면, 난수는 rand(seed, i) 로만. 집중선·효과선은 애니처럼 몇 장마다 다시 그려 끓는다(초당 12장).
+import { applyStyle, clamp, rand, randRange, type SceneCtx, type Style } from "@kasaframe/core";
+import { dropBurst, type DropBurstState } from "@kasaframe/motion";
+
+export type { SceneCtx };
+
+// 0.1초 넘게 같은 그림이면 멈춘 화면이라 끓는 선은 초당 12장(0.083초) — 만화 선이 애니처럼 두 장마다 다시 그려진다
+const FPS = 12;
+const SVG = "http://www.w3.org/2000/svg";
+
+type Pt = [number, number];
+type Area = [x: number, y: number, w: number, h: number];
+
+const color = (ctx: SceneCtx, key: string): string => ctx.style.colors[key] ?? key;
+const frameOf = (t: number, fps = FPS): number => Math.floor(t * fps + 1e-6);
+
+function div(parent: HTMLElement, css: string): HTMLDivElement {
+  const d = document.createElement("div");
+  d.style.cssText = `position:absolute;pointer-events:none;${css}`;
+  parent.append(d);
+  return d;
+}
+
+function svgEl<K extends keyof SVGElementTagNameMap>(parent: Element, tag: K, attrs: Record<string, string | number>): SVGElementTagNameMap[K] {
+  const e = document.createElementNS(SVG, tag);
+  for (const [k, v] of Object.entries(attrs)) e.setAttribute(k, String(v));
+  parent.append(e);
+  return e;
+}
+
+const areas = new WeakMap<CanvasRenderingContext2D, Area>();
+
+// 그리는 자리만큼만 캔버스를 잡고 화면 좌표를 그대로 쓴다 — 쪽마다 칸마다 선 층이 생겨 화면 전체 캔버스면 메모리를 먹는다
+function canvas(el: HTMLElement, area: Area): CanvasRenderingContext2D {
+  const [x, y, w, h] = area.map((v, i) => (i < 2 ? Math.floor(v) : Math.ceil(v))) as Area;
+  const c = document.createElement("canvas");
+  c.width = Math.max(1, w);
+  c.height = Math.max(1, h);
+  c.style.cssText = `position:absolute;left:${x}px;top:${y}px;width:${w}px;height:${h}px;pointer-events:none;`;
+  el.append(c);
+  const g = c.getContext("2d")!;
+  g.translate(-x, -y);
+  areas.set(g, [x, y, w, h]);
+  return g;
+}
+
+const clear = (g: CanvasRenderingContext2D): void => {
+  const [x, y, w, h] = areas.get(g)!;
+  g.clearRect(x, y, w, h);
+};
+
+const bbox = (pts: readonly Pt[]): Area => {
+  const xs = pts.map((p) => p[0]);
+  const ys = pts.map((p) => p[1]);
+  return [Math.min(...xs), Math.min(...ys), Math.max(...xs) - Math.min(...xs), Math.max(...ys) - Math.min(...ys)];
+};
+
+const clipPoly = (g: CanvasRenderingContext2D, poly?: readonly Pt[]): void => {
+  if (!poly) return;
+  g.beginPath();
+  poly.forEach((p, i) => (i ? g.lineTo(p[0], p[1]) : g.moveTo(p[0], p[1])));
+  g.closePath();
+  g.clip();
+};
+
+/** t 를 초당 12장으로 끊는다 — 선이 두 장마다 다시 그려지는 박자. 손으로 짠 움직임도 이걸 거치면 만화 PV 처럼 끊긴다 */
+export function onTwos(t: number, fps = FPS): number {
+  return frameOf(t, fps) / fps;
+}
+
+export interface PanelRow {
+  /** 줄 높이 비 */
+  h: number;
+  /** 줄 안 칸 폭 비 — 오른쪽 위부터 읽으니 순서는 오른쪽 칸이 먼저 */
+  cols: number[];
+  /** 칸 사이 세로 홈이 기우는 정도(px, 위 끝과 아래 끝의 차) — 기운 칸은 긴장 */
+  slant?: number;
+  /** 이 줄 아래 가로 홈이 기우는 정도(px, 왼쪽 끝과 오른쪽 끝의 차) */
+  tilt?: number;
+}
+
+export interface PanelBox {
+  /** 화면 좌표 꼭짓점(시계 방향) */
+  poly: Pt[];
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export interface PanelPageOpts {
+  ctx: SceneCtx;
+  /** 쪽 자리 — 기본 안전 영역 */
+  area?: Area;
+  /** 줄과 칸 비로 나누기. quads 를 주면 그걸 그대로(읽는 순서대로) */
+  rows?: PanelRow[];
+  quads?: Pt[][];
+  /** [줄 사이, 옆 칸 사이] 홈 px — 홈 폭은 시간이다(넓으면 그만큼 시간이 흘렀다) */
+  gutter?: [number, number];
+  /** 칸이 열리는 시각 — 칸마다(읽는 순서) 또는 함수 */
+  at: number[] | ((i: number) => number);
+  /** 이 시각부터 쪽 전체를 숨긴다(다음 쪽으로 컷) */
+  until?: number;
+  /** 칸 테두리 먹 굵기 px */
+  border?: number;
+  /** 칸 안을 짓는다 — cell 은 칸 바운딩 상자 크기의 div(칸 꼴로 잘림), 좌표는 상자 안 px */
+  build?(cell: HTMLElement, i: number, box: PanelBox): void;
+  /** 칸 바탕 — surface(흰 칸)·bg·accent 따위 style 색 이름이나 색 */
+  fill?: string | ((i: number) => string);
+}
+
+function layoutRows(area: Area, rows: PanelRow[], gutter: [number, number]): Pt[][] {
+  const [ax, ay, aw, ah] = area;
+  const [gy, gx] = gutter;
+  const sumH = rows.reduce((a, r) => a + r.h, 0);
+  const free = ah - gy * (rows.length - 1);
+  // 줄 경계는 y(x) = 가운데 y + tilt·(0.5 - (x-ax)/aw) — 홈 반쪽씩 위아래 칸이 물러선다
+  const mids: number[] = [];
+  let acc = ay;
+  rows.forEach((r, i) => {
+    acc += (free * r.h) / sumH;
+    if (i < rows.length - 1) {
+      mids.push(acc + gy / 2);
+      acc += gy;
+    }
+  });
+  const edgeY = (k: number, x: number, side: 1 | -1): number => {
+    if (k < 0) return ay;
+    if (k >= mids.length) return ay + ah;
+    return mids[k] + (rows[k].tilt ?? 0) * (0.5 - (x - ax) / aw) + (side * gy) / 2;
+  };
+  const out: Pt[][] = [];
+  rows.forEach((r, ri) => {
+    const sumW = r.cols.reduce((a, b) => a + b, 0);
+    const freeW = aw - gx * (r.cols.length - 1);
+    const xs: number[] = [ax];
+    let cx = ax;
+    r.cols.forEach((c, ci) => {
+      cx += (freeW * c) / sumW;
+      xs.push(cx);
+      if (ci < r.cols.length - 1) {
+        cx += gx;
+        xs.push(cx);
+      }
+    });
+    const s = r.slant ?? 0;
+    const cells: Pt[][] = [];
+    for (let ci = 0; ci < r.cols.length; ci++) {
+      const l = xs[ci * 2];
+      const rr = xs[ci * 2 + 1];
+      // 바깥 가장자리는 곧게, 안쪽 세로 홈만 기운다
+      const lt = ci === 0 ? l : l + s / 2;
+      const lb = ci === 0 ? l : l - s / 2;
+      const rt = ci === r.cols.length - 1 ? rr : rr + s / 2;
+      const rb = ci === r.cols.length - 1 ? rr : rr - s / 2;
+      cells.push([
+        [lt, edgeY(ri - 1, lt, 1)],
+        [rt, edgeY(ri - 1, rt, 1)],
+        [rb, edgeY(ri, rb, -1)],
+        [lb, edgeY(ri, lb, -1)],
+      ]);
+    }
+    // 오른쪽 위부터 읽는다
+    out.push(...cells.reverse());
+  });
+  return out;
+}
+
+/**
+ * 칸 나누기 — 쪽을 칸으로 나누고, 칸마다 펜이 테두리를 한 바퀴 긋고 나면 칸이 쾅 열린다(오른쪽 위부터).
+ * 칸 크기가 무게, 홈 폭이 시간, 기운 칸이 긴장. 칸 안 내용은 build 로
+ */
+export function panelPage(el: HTMLElement, o: PanelPageOpts): (t: number) => void {
+  const { ctx } = o;
+  const s = ctx.safe;
+  const area: Area = o.area ?? [s.left, s.top, ctx.meta.width - s.left - s.right, ctx.meta.height - s.top - s.bottom];
+  const quads = o.quads ?? layoutRows(area, o.rows ?? [{ h: 1, cols: [1] }], o.gutter ?? [40, 18]);
+  const bw = o.border ?? 7;
+  const page = div(el, "inset:0");
+  const atOf = (i: number) => (typeof o.at === "function" ? o.at(i) : (o.at[i] ?? o.at[o.at.length - 1] ?? 0));
+  const panels = quads.map((poly, i) => {
+    const [x, y, w, h] = bbox(poly);
+    const box: PanelBox = { poly, x, y, w, h };
+    const wrap = div(page, `left:${x}px;top:${y}px;width:${w}px;height:${h}px;display:none;transform-origin:50% 50%`);
+    const fillKey = typeof o.fill === "function" ? o.fill(i) : (o.fill ?? "surface");
+    const clip = poly.map(([px, py]) => `${(px - x).toFixed(1)}px ${(py - y).toFixed(1)}px`).join(",");
+    const cell = div(wrap, `inset:0;overflow:hidden;clip-path:polygon(${clip});background:${color(ctx, fillKey)}`);
+    o.build?.(cell, i, box);
+    const pad = bw;
+    const sv = svgEl(wrap, "svg", { width: w + pad * 2, height: h + pad * 2, viewBox: `${x - pad} ${y - pad} ${w + pad * 2} ${h + pad * 2}` });
+    sv.style.cssText = `position:absolute;left:${-pad}px;top:${-pad}px;overflow:visible;pointer-events:none`;
+    const edge = svgEl(sv, "polygon", {
+      points: poly.map((p) => p.join(",")).join(" "),
+      fill: "none",
+      stroke: color(ctx, "ink"),
+      "stroke-width": bw,
+      "stroke-linejoin": "miter",
+      pathLength: 1,
+      "stroke-dasharray": "1 1",
+    });
+    // 화면 끝까지 뚫은 칸(타치키리)은 테두리가 화면 밖이라 긋는 동안이 빈 화면으로만 보인다 — 바로 연다
+    const bleed = x <= 0 && y <= 0 && x + w >= ctx.meta.width && y + h >= ctx.meta.height;
+    return { wrap, cell, edge, at: atOf(i), pen: bleed ? 0 : 0.125 };
+  });
+  return (t) => {
+    const gone = o.until !== undefined && t >= o.until;
+    page.style.display = gone ? "none" : "block";
+    if (gone) return;
+    for (const p of panels) {
+      const on = t >= p.at;
+      p.wrap.style.display = on ? "block" : "none";
+      if (!on) continue;
+      // 펜이 한 바퀴 긋는 0.125초(24장 끊김) 동안 칸 안은 비어 있다가, 다 그으면 칸이 한 번 부풀며 열린다
+      const ink = p.pen ? clamp(onTwos(t - p.at, 24) / p.pen) : 1;
+      p.edge.setAttribute("stroke-dashoffset", String(1 - ink));
+      p.cell.style.visibility = ink >= 1 ? "visible" : "hidden";
+      const k = frameOf(t - p.at - p.pen);
+      p.wrap.style.transform = k === 0 ? "scale(1.035)" : k === 1 ? "scale(0.992)" : "none";
+    }
+  };
+}
+
+export interface FocusLinesOpts {
+  ctx: SceneCtx;
+  /** 모이는 점 */
+  cx: number;
+  cy: number;
+  /** 비워 둘 가운데 타원 반지름 */
+  rx: number;
+  ry: number;
+  /** 그리는 자리(기본 화면 전체)와 칸 꼴로 자르기 */
+  area?: Area;
+  clip?: Pt[];
+  at?: number;
+  until?: number;
+  /** 선 수 */
+  count?: number;
+  /** 0..1 선 길이·굵기 — 박마다 바꾸면 집중이 조였다 풀린다 */
+  strength?: number | ((t: number) => number);
+  /** 선이 가장자리에서 가운데로 쏘아 들어오는 시간 */
+  burst?: number;
+  ink?: string;
+  seed?: string | number;
+}
+
+/**
+ * 집중선 — 가장자리에서 한 점으로 모이는 먹 선. 가운데 타원은 비워 그 안의 숫자·이름이 빛나 보인다.
+ * 초당 12번 다시 그려 끓는다. at 에 가장자리에서 쏘아 들어온다
+ */
+export function focusLines(el: HTMLElement, o: FocusLinesOpts): (t: number) => void {
+  const { ctx } = o;
+  const area = o.area ?? [0, 0, ctx.meta.width, ctx.meta.height];
+  const g = canvas(el, area);
+  const [ax, ay, aw, ah] = area;
+  const far = Math.max(...[[ax, ay], [ax + aw, ay], [ax, ay + ah], [ax + aw, ay + ah]].map(([x, y]) => Math.hypot((x - o.cx) / o.rx, (y - o.cy) / o.ry)));
+  const n = o.count ?? 150;
+  const at = o.at ?? 0;
+  const seed = o.seed ?? "focus";
+  const fill = color(ctx, o.ink ?? "ink");
+  return (t) => {
+    clear(g);
+    if (t < at || (o.until !== undefined && t >= o.until)) return;
+    const f = frameOf(t);
+    const str = clamp(typeof o.strength === "function" ? o.strength(t) : (o.strength ?? 1));
+    const shoot = o.burst ? clamp(onTwos(t - at, 24) / o.burst) : 1;
+    g.save();
+    clipPoly(g, o.clip);
+    g.fillStyle = fill;
+    g.beginPath();
+    for (let i = 0; i < n; i++) {
+      const a = ((i + rand(`${seed}:${f}`, i * 3)) / n) * Math.PI * 2;
+      // 선 끝은 타원 밖 1.05–1.9 배 사이 — 길고 짧은 선이 섞여야 손으로 그은 집중선이다
+      const inner = 1.05 + (1 - str * 0.75) * 0.9 + rand(`${seed}:${f}`, i * 3 + 1) * 0.85;
+      const reach = far + 0.2 - (far + 0.2 - inner) * shoot;
+      const wide = (0.004 + rand(`${seed}:${f}`, i * 3 + 2) * 0.012) * (0.5 + str * 0.5);
+      const c = Math.cos(a);
+      const sn = Math.sin(a);
+      const tipX = o.cx + c * o.rx * reach;
+      const tipY = o.cy + sn * o.ry * reach;
+      const outR = far + 0.3;
+      g.moveTo(tipX, tipY);
+      g.lineTo(o.cx + Math.cos(a - wide) * o.rx * outR, o.cy + Math.sin(a - wide) * o.ry * outR);
+      g.lineTo(o.cx + Math.cos(a + wide) * o.rx * outR, o.cy + Math.sin(a + wide) * o.ry * outR);
+      g.closePath();
+    }
+    g.fill();
+    g.restore();
+  };
+}
+
+export interface SpeedLinesOpts {
+  ctx: SceneCtx;
+  area: Area;
+  clip?: Pt[];
+  /** 흐르는 방향(도) — 0 = 오른쪽으로 */
+  angle?: number;
+  /** 처리량 — 초당 지나가는 선 수에 비례. 밀도·속도가 함께 오른다 */
+  rate?: number | ((t: number) => number);
+  at?: number;
+  until?: number;
+  ink?: string;
+  seed?: string | number;
+}
+
+/** 효과선 — 평행한 먹 선이 한 방향으로 흐른다. rate 가 처리량(높을수록 선이 빽빽하고 길다). 초당 12번 다시 그려 끓는다 */
+export function speedLines(el: HTMLElement, o: SpeedLinesOpts): (t: number) => void {
+  const { ctx } = o;
+  const g = canvas(el, o.area);
+  const [ax, ay, aw, ah] = o.area;
+  const a = ((o.angle ?? 0) * Math.PI) / 180;
+  const ux = Math.cos(a);
+  const uy = Math.sin(a);
+  const span = Math.abs(aw * uy) + Math.abs(ah * ux);
+  const len = Math.abs(aw * ux) + Math.abs(ah * uy);
+  const cx = ax + aw / 2;
+  const cy = ay + ah / 2;
+  const seed = o.seed ?? "speed";
+  const fill = color(ctx, o.ink ?? "ink");
+  const at = o.at ?? 0;
+  return (t) => {
+    clear(g);
+    if (t < at || (o.until !== undefined && t >= o.until)) return;
+    const f = frameOf(t);
+    const rate = Math.max(0, typeof o.rate === "function" ? o.rate(t) : (o.rate ?? 1));
+    const n = Math.round(18 + rate * 46);
+    g.save();
+    clipPoly(g, o.clip);
+    g.fillStyle = fill;
+    g.beginPath();
+    for (let i = 0; i < n; i++) {
+      const r1 = rand(`${seed}:${f}`, i * 4);
+      const r2 = rand(`${seed}:${f}`, i * 4 + 1);
+      const r3 = rand(`${seed}:${f}`, i * 4 + 2);
+      const off = (r1 - 0.5) * span;
+      const L = len * (0.18 + 0.5 * Math.min(1, rate) * r2);
+      const along = (r3 - 0.5) * (len + L);
+      const w = 1.2 + rand(`${seed}:${f}`, i * 4 + 3) * 3.2;
+      const mx = cx + ux * along - uy * off;
+      const my = cy + uy * along + ux * off;
+      // 양끝이 뾰족한 선 — 펜을 빠르게 그어 뺀 모양
+      g.moveTo(mx - (ux * L) / 2, my - (uy * L) / 2);
+      g.lineTo(mx - uy * w, my + ux * w);
+      g.lineTo(mx + (ux * L) / 2, my + (uy * L) / 2);
+      g.lineTo(mx + uy * w, my - ux * w);
+      g.closePath();
+    }
+    g.fill();
+    g.restore();
+  };
+}
+
+export type BalloonKind = "round" | "electric" | "blast" | "thought" | "box" | "flash";
+
+export interface BalloonOpts {
+  ctx: SceneCtx;
+  /** round 말 · electric 기계(모델) 목소리 · blast 외침(장애) · thought 생각(캐시) · box 설명 · flash 충격 */
+  kind?: BalloonKind;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  text: string;
+  size?: number;
+  font?: "sans" | "display" | "mono";
+  /** 꼬리 끝(말하는 쪽) */
+  tail?: Pt;
+  at: number;
+  until?: number;
+  seed?: string | number;
+  ink?: string;
+}
+
+function balloonPath(kind: BalloonKind, w: number, h: number, seed: string | number): string {
+  const rx = w / 2;
+  const ry = h / 2;
+  if (kind === "box") return `M${-rx},${-ry}H${rx}V${ry}H${-rx}Z`;
+  if (kind === "electric") {
+    // 꺾인 다각형 — 전화·스피커·기계에서 나오는 목소리 풍선
+    const n = 6;
+    const pts = Array.from({ length: n }, (_, i) => {
+      const a = ((i + randRange(seed, i, -0.18, 0.18)) / n) * Math.PI * 2 - Math.PI / 2;
+      const r = randRange(seed, i + 10, 1.02, 1.12);
+      return `${(Math.cos(a) * rx * r).toFixed(1)},${(Math.sin(a) * ry * r).toFixed(1)}`;
+    });
+    return `M${pts.join("L")}Z`;
+  }
+  if (kind === "blast") {
+    const n = 18;
+    const pts = Array.from({ length: n * 2 }, (_, i) => {
+      const a = ((i + randRange(seed, i, -0.25, 0.25)) / (n * 2)) * Math.PI * 2;
+      const r = i % 2 ? randRange(seed, i + 40, 0.82, 0.9) : randRange(seed, i + 40, 1.08, 1.3);
+      return `${(Math.cos(a) * rx * r).toFixed(1)},${(Math.sin(a) * ry * r).toFixed(1)}`;
+    });
+    return `M${pts.join("L")}Z`;
+  }
+  if (kind === "thought") {
+    const n = 11;
+    let d = "";
+    for (let i = 0; i < n; i++) {
+      const a0 = (i / n) * Math.PI * 2;
+      const a1 = ((i + 1) / n) * Math.PI * 2;
+      const p0 = [Math.cos(a0) * rx * 0.94, Math.sin(a0) * ry * 0.94];
+      const p1 = [Math.cos(a1) * rx * 0.94, Math.sin(a1) * ry * 0.94];
+      const am = (a0 + a1) / 2;
+      const bulge = randRange(seed, i, 1.12, 1.22);
+      d += `${i ? "" : `M${p0[0].toFixed(1)},${p0[1].toFixed(1)}`}Q${(Math.cos(am) * rx * bulge).toFixed(1)},${(Math.sin(am) * ry * bulge).toFixed(1)} ${p1[0].toFixed(1)},${p1[1].toFixed(1)}`;
+    }
+    return `${d}Z`;
+  }
+  return `M${-rx},0A${rx},${ry} 0 1 0 ${rx},0A${rx},${ry} 0 1 0 ${-rx},0Z`;
+}
+
+function tailPath(kind: BalloonKind, rx: number, ry: number, tip: Pt, seed: string | number): string {
+  const a = Math.atan2(tip[1] / ry, tip[0] / rx);
+  const spread = kind === "blast" ? 0.12 : 0.22;
+  const b1: Pt = [Math.cos(a - spread) * rx * 0.86, Math.sin(a - spread) * ry * 0.86];
+  const b2: Pt = [Math.cos(a + spread) * rx * 0.86, Math.sin(a + spread) * ry * 0.86];
+  if (kind === "electric") {
+    // 번개처럼 한 번 꺾인 꼬리 — 사람 말이 아니라 기계 목소리
+    const m: Pt = [(b1[0] + b2[0]) / 2 * 0.4 + tip[0] * 0.6, (b1[1] + b2[1]) / 2 * 0.4 + tip[1] * 0.6];
+    const nx = -(tip[1] - m[1]);
+    const ny = tip[0] - m[0];
+    const k = 0.22 * (rand(seed, 99) > 0.5 ? 1 : -1);
+    const m1: Pt = [m[0] + nx * k, m[1] + ny * k];
+    const m2: Pt = [m[0] + nx * k * 0.35, m[1] + ny * k * 0.35];
+    return `M${b1.join(",")}L${m1.join(",")}L${tip.join(",")}L${m2.join(",")}L${b2.join(",")}Z`;
+  }
+  const c: Pt = [(b1[0] + b2[0]) / 2 * 0.5 + tip[0] * 0.5, (b1[1] + b2[1]) / 2 * 0.5 + tip[1] * 0.5];
+  const nx = -(tip[1] - c[1]) * 0.15;
+  const ny = (tip[0] - c[0]) * 0.15;
+  return `M${b1.join(",")}Q${c[0] + nx},${c[1] + ny} ${tip.join(",")}Q${c[0] - nx * 0.4},${c[1] - ny * 0.4} ${b2.join(",")}Z`;
+}
+
+/**
+ * 말풍선 — 요청은 둥근 풍선, 모델 응답은 꺾인 전자음 풍선, 장애는 가시 풍선, 캐시는 생각 풍선, 설명은 각진 상자.
+ * 박에 짓눌렸다 튀어 선다(세 장). 꼬리는 말하는 쪽을 짚는다
+ */
+export function balloon(el: HTMLElement, o: BalloonOpts): (t: number) => void {
+  const { ctx } = o;
+  const kind = o.kind ?? "round";
+  const seed = o.seed ?? `${ctx.id}:${o.text}`;
+  const tip: Pt | null = o.tail && kind !== "box" && kind !== "flash" ? [o.tail[0] - o.x, o.tail[1] - o.y] : null;
+  const ext = Math.max(o.w, o.h) * (kind === "flash" ? 0.75 : kind === "blast" ? 0.72 : 0.62);
+  const minX = Math.min(-ext, tip ? tip[0] - 12 : 0);
+  const minY = Math.min(-ext, tip ? tip[1] - 12 : 0);
+  const maxX = Math.max(ext, tip ? tip[0] + 12 : 0);
+  const maxY = Math.max(ext, tip ? tip[1] + 12 : 0);
+  const host = div(el, `left:${o.x}px;top:${o.y}px;width:0;height:0;display:none`);
+  const sv = svgEl(host, "svg", { width: maxX - minX, height: maxY - minY, viewBox: `${minX} ${minY} ${maxX - minX} ${maxY - minY}` });
+  sv.style.cssText = `position:absolute;left:${minX}px;top:${minY}px;overflow:visible`;
+  const inkC = color(ctx, o.ink ?? "ink");
+  const paper = color(ctx, "surface");
+  const body = balloonPath(kind, o.w, o.h, seed);
+  if (kind === "flash") {
+    // 플래시 풍선 — 테두리 대신 둘레에서 바깥으로 뻗는 가는 가시
+    const n = 90;
+    let d = "";
+    for (let i = 0; i < n; i++) {
+      const a = (i / n) * Math.PI * 2;
+      const w = 0.012;
+      const r0 = 1.0;
+      const r1 = randRange(seed, i, 1.16, 1.36);
+      d += `M${Math.cos(a - w) * (o.w / 2) * r0},${Math.sin(a - w) * (o.h / 2) * r0}L${Math.cos(a) * (o.w / 2) * r1},${Math.sin(a) * (o.h / 2) * r1}L${Math.cos(a + w) * (o.w / 2) * r0},${Math.sin(a + w) * (o.h / 2) * r0}Z`;
+    }
+    svgEl(sv, "path", { d, fill: inkC });
+    svgEl(sv, "path", { d: body, fill: paper });
+  } else {
+    const tail = tip ? tailPath(kind, o.w / 2, o.h / 2, tip, seed) : "";
+    // 테두리를 먼저 굵게 긋고 흰 면을 그 위에 덮는다 — 꼬리와 몸이 이음매 없이 한 풍선이 된다
+    const sw = kind === "box" ? 5 : 4.5;
+    svgEl(sv, "path", { d: body + tail, fill: "none", stroke: inkC, "stroke-width": sw * 2, "stroke-linejoin": "round" });
+    if (kind === "thought" && tip) {
+      for (let k = 1; k <= 2; k++) {
+        const p = 1 + k * 0.32;
+        const cxp = tip[0] * (0.55 + k * 0.18);
+        const cyp = tip[1] * (0.55 + k * 0.18);
+        svgEl(sv, "ellipse", { cx: cxp, cy: cyp, rx: 26 / p, ry: 18 / p, fill: paper, stroke: inkC, "stroke-width": 4 });
+      }
+    }
+    svgEl(sv, "path", { d: body + (kind === "thought" ? "" : tail), fill: paper });
+  }
+  const size = o.size ?? 48;
+  const label = div(host, `left:${-o.w * 0.42}px;top:${-o.h / 2}px;width:${o.w * 0.84}px;height:${o.h}px;display:flex;align-items:center;justify-content:center;text-align:center;font-family:${ctx.style.fonts[o.font ?? "sans"]};font-size:${size}px;line-height:1.08;color:${inkC};white-space:pre-line;word-break:keep-all;overflow-wrap:anywhere`);
+  label.textContent = o.text;
+  return (t) => {
+    const on = t >= o.at && (o.until === undefined || t < o.until);
+    host.style.display = on ? "block" : "none";
+    if (!on) return;
+    const k = frameOf(t - o.at);
+    // 짓눌림 → 튐 → 앉음, 초당 12장
+    const s = k === 0 ? [1.18, 0.62] : k === 1 ? [0.94, 1.1] : k === 2 ? [1.02, 0.98] : [1, 1];
+    host.style.transform = `scale(${s[0]}, ${s[1]})`;
+  };
+}
+
+export interface SfxOpts {
+  ctx: SceneCtx;
+  /** 실제 숫자·주소·모델 ID·짧은 낱말만 — 뜻 없는 소리 글자를 지어내지 않는다 */
+  text: string;
+  x: number;
+  y: number;
+  size: number;
+  rotate?: number;
+  skew?: number;
+  at: number;
+  /** 글자 사이 간격(초) — 0 이면 한 번에 쾅 */
+  stagger?: number;
+  until?: number;
+  /** 글자 색 — ink(검은 글자 흰 테두리)·accent(붉은 별색) */
+  ink?: string;
+  /** 흰 테두리 px */
+  outline?: number;
+  seed?: string | number;
+}
+
+/**
+ * 효과음 글자 — 숫자·낱말이 흰 테두리 굵은 글자로 한 자씩 쾅 찍힌다(크게 → 눌림 → 앉음). 앉은 뒤에도 손글씨처럼 초당 12번 1px 끓는다.
+ * 글자마다 조금씩 기울어 손으로 쓴 효과음 꼴
+ */
+export function sfx(el: HTMLElement, o: SfxOpts): (t: number) => void {
+  const { ctx } = o;
+  const seed = o.seed ?? `${ctx.id}:sfx:${o.text}`;
+  const out = o.outline ?? Math.max(6, Math.round(o.size * 0.075));
+  const inkC = color(ctx, o.ink ?? "ink");
+  const edge = color(ctx, "ink");
+  const ring = Math.max(3, Math.round(out * 0.45));
+  const host = div(
+    el,
+    `left:${o.x}px;top:${o.y}px;transform:translate(-50%,-50%) rotate(${o.rotate ?? -4}deg) skewX(${o.skew ?? -8}deg);white-space:nowrap;font-family:${ctx.style.fonts.display};font-size:${o.size}px;line-height:1;letter-spacing:-0.02em;color:${inkC};-webkit-text-stroke:${out}px ${color(ctx, "surface")};paint-order:stroke fill;filter:drop-shadow(${ring}px 0 0 ${edge}) drop-shadow(-${ring}px 0 0 ${edge}) drop-shadow(0 ${ring}px 0 ${edge}) drop-shadow(0 -${ring}px 0 ${edge});display:none`,
+  );
+  host.style.position = "absolute";
+  const chars = Array.from(o.text).map((ch, i) => {
+    const s = document.createElement("span");
+    s.textContent = ch;
+    s.style.cssText = `display:inline-block;transform-origin:50% 70%;white-space:pre`;
+    host.append(s);
+    return { s, rot: randRange(seed, i, -7, 7), dy: randRange(seed, i + 50, -0.06, 0.06) * o.size };
+  });
+  const stagger = o.stagger ?? 1 / 24;
+  return (t) => {
+    const on = t >= o.at && (o.until === undefined || t < o.until);
+    host.style.display = on ? "block" : "none";
+    if (!on) return;
+    const f = frameOf(t);
+    chars.forEach((c, i) => {
+      const a = o.at + i * stagger;
+      if (t < a) {
+        c.s.style.visibility = "hidden";
+        return;
+      }
+      c.s.style.visibility = "visible";
+      const k = frameOf(t - a);
+      const sc = k === 0 ? 1.7 : k === 1 ? 0.9 : 1;
+      const jx = k >= 2 ? randRange(`${seed}:b`, f * 31 + i, -1, 1) : 0;
+      const jy = k >= 2 ? randRange(`${seed}:b`, f * 31 + i + 13, -1, 1) : 0;
+      c.s.style.transform = `translate(${jx.toFixed(1)}px, ${(c.dy + jy).toFixed(1)}px) rotate(${c.rot.toFixed(1)}deg) scale(${sc})`;
+    });
+  };
+}
+
+export interface ScreentoneOpts {
+  ctx: SceneCtx;
+  /** 톤을 붙일 꼴(화면 좌표) */
+  poly: Pt[];
+  /** 망점 간격 px */
+  pitch?: number;
+  /** 0..1 먹 양 — 수거나 (u, v) => 수(상자 안 0..1). 계조는 점 크기로만 */
+  value?: number | ((u: number, v: number) => number);
+  /** dots 망점 · lines 평행선 */
+  pattern?: "dots" | "lines";
+  angle?: number;
+  at?: number;
+  until?: number;
+  ink?: string;
+}
+
+/** 스크린톤 — 칼로 오려 붙인 망점 톤. 회색은 이것으로만 낸다. at 에 칼이 대각선으로 한 번 지나가며 붙는다 */
+export function screentone(el: HTMLElement, o: ScreentoneOpts): (t: number) => void {
+  const { ctx } = o;
+  const [bx, by, bw, bh] = bbox(o.poly);
+  const g = canvas(el, [bx - 2, by - 2, bw + 4, bh + 4]);
+  const pitch = o.pitch ?? 10;
+  const a = ((o.angle ?? 45) * Math.PI) / 180;
+  const val = (u: number, v: number) => clamp(typeof o.value === "function" ? o.value(u, v) : (o.value ?? 0.3));
+  const fill = color(ctx, o.ink ?? "ink");
+  const cx = bx + bw / 2;
+  const cy = by + bh / 2;
+  const half = Math.hypot(bw, bh) / 2;
+  const n = Math.ceil(half / pitch) + 1;
+  const pts: [number, number, number][] = [];
+  for (let j = -n; j <= n; j++) {
+    for (let i = -n; i <= n; i++) {
+      const x = cx + Math.cos(a) * i * pitch - Math.sin(a) * j * pitch;
+      const y = cy + Math.sin(a) * i * pitch + Math.cos(a) * j * pitch;
+      if (x < bx - pitch || x > bx + bw + pitch || y < by - pitch || y > by + bh + pitch) continue;
+      pts.push([x, y, val((x - bx) / bw, (y - by) / bh)]);
+    }
+  }
+  const at = o.at ?? 0;
+  let drawn = -1;
+  return (t) => {
+    const on = t >= at && (o.until === undefined || t < o.until);
+    // 칼이 지나가는 0.125초 — 24장으로 끊어 대각선 경계가 나아간다
+    const p = on ? clamp(onTwos(t - at, 24) / 0.125) : -1;
+    if (p === drawn) return;
+    drawn = p;
+    clear(g);
+    if (!on) return;
+    g.save();
+    clipPoly(g, o.poly);
+    g.beginPath();
+    const reach = bx + (bw + bh) * p;
+    g.moveTo(bx - 4, by - 4);
+    g.lineTo(reach + 4, by - 4);
+    g.lineTo(reach - bh - 4, by + bh + 4);
+    g.lineTo(bx - 4, by + bh + 4);
+    g.closePath();
+    g.clip();
+    g.fillStyle = fill;
+    g.strokeStyle = fill;
+    if (o.pattern === "lines") {
+      g.lineWidth = pitch * 0.5 * val(0.5, 0.5);
+      g.beginPath();
+      for (let j = -n; j <= n; j++) {
+        const x0 = cx - Math.sin(a) * j * pitch;
+        const y0 = cy + Math.cos(a) * j * pitch;
+        g.moveTo(x0 - Math.cos(a) * half * 1.5, y0 - Math.sin(a) * half * 1.5);
+        g.lineTo(x0 + Math.cos(a) * half * 1.5, y0 + Math.sin(a) * half * 1.5);
+      }
+      g.stroke();
+    } else {
+      g.beginPath();
+      for (const [x, y, v] of pts) {
+        const r = pitch * 0.56 * Math.sqrt(v);
+        if (r < 0.35) continue;
+        g.moveTo(x + r, y);
+        g.arc(x, y, r, 0, Math.PI * 2);
+      }
+      g.fill();
+    }
+    g.restore();
+  };
+}
+
+export interface PenStrokeOpts {
+  ctx: SceneCtx;
+  points: readonly Pt[];
+  at: number;
+  dur?: number;
+  until?: number;
+  /** 가운데 굵기 px — 들어가고 빠질 때 가늘다(G펜 필압) */
+  width?: number;
+  ink?: string;
+  /** 다 그은 뒤 선 끝에 화살촉 */
+  arrow?: boolean;
+}
+
+/** G펜 선 — 들어가고 빠질 때 가늘고 가운데가 굵은 먹 선이 펜 속도로 그어진다. 취소선·바늘·연결선에 */
+export function penStroke(el: HTMLElement, o: PenStrokeOpts): (t: number) => void {
+  const { ctx } = o;
+  const [bx, by, bw, bh] = bbox(o.points as Pt[]);
+  const W = o.width ?? 10;
+  const g = canvas(el, [bx - W * 3, by - W * 3, bw + W * 6, bh + W * 6]);
+  const segs = o.points.slice(1).map((q, i) => Math.hypot(q[0] - o.points[i][0], q[1] - o.points[i][1]));
+  const total = segs.reduce((a, b) => a + b, 0) || 1;
+  // 길이 1.5px 마다 점 — 점마다 필압으로 굵기를 정해 원을 찍는다
+  const samples: [number, number, number][] = [];
+  segs.forEach((L, i) => {
+    const [x0, y0] = o.points[i];
+    const [x1, y1] = o.points[i + 1];
+    const steps = Math.max(1, Math.ceil(L / 1.5));
+    for (let k = 0; k < steps; k++) {
+      const u = k / steps;
+      const done = (segs.slice(0, i).reduce((a, b) => a + b, 0) + L * u) / total;
+      samples.push([x0 + (x1 - x0) * u, y0 + (y1 - y0) * u, done]);
+    }
+  });
+  samples.push([o.points.at(-1)![0], o.points.at(-1)![1], 1]);
+  const fill = color(ctx, o.ink ?? "ink");
+  const dur = o.dur ?? 0.25;
+  return (t) => {
+    clear(g);
+    if (t < o.at || (o.until !== undefined && t >= o.until)) return;
+    const p = clamp(onTwos(t - o.at, 24) / dur);
+    g.fillStyle = fill;
+    g.beginPath();
+    for (const [x, y, d] of samples) {
+      if (d > p) break;
+      const press = Math.sin(Math.PI * clamp(d * 0.92 + 0.04));
+      const r = (W / 2) * (0.25 + 0.75 * press);
+      g.moveTo(x + r, y);
+      g.arc(x, y, r, 0, Math.PI * 2);
+    }
+    g.fill();
+    if (o.arrow && p >= 1 && o.points.length >= 2) {
+      const [x1, y1] = o.points.at(-1)!;
+      const [x0, y0] = o.points.at(-2)!;
+      const a = Math.atan2(y1 - y0, x1 - x0);
+      const L = W * 3.2;
+      g.beginPath();
+      g.moveTo(x1 + Math.cos(a) * W, y1 + Math.sin(a) * W);
+      g.lineTo(x1 - Math.cos(a - 0.45) * L, y1 - Math.sin(a - 0.45) * L);
+      g.lineTo(x1 - Math.cos(a + 0.45) * L, y1 - Math.sin(a + 0.45) * L);
+      g.closePath();
+      g.fill();
+    }
+  };
+}
+
+/**
+ * 임팩트 프레임 — 드롭(결정타)에 화면이 두 장 흑백 반전되고, 주인공 둘레로 검은 가시(베타 플래시)가 터졌다 걷힌다.
+ * 반환한 흔들림은 칸 틀에, punch 는 주인공에
+ */
+export function impactFrame(el: HTMLElement, o: { ctx: SceneCtx; drop?: number; origin?: Pt; rx?: number; ry?: number }): (t: number) => DropBurstState {
+  const { ctx } = o;
+  const W = ctx.meta.width;
+  const H = ctx.meta.height;
+  const [ox, oy] = o.origin ?? [W / 2, H / 2];
+  const rx = o.rx ?? W * 0.3;
+  const ry = o.ry ?? H * 0.3;
+  const g = canvas(el, [0, 0, W, H]);
+  const invert = div(el, `inset:0;background:#fff;mix-blend-mode:difference;display:none`);
+  const inkC = color(ctx, "ink");
+  const drop = o.drop ?? 0;
+  const at = ctx.beats.drop(drop);
+  return (t) => {
+    const s = dropBurst(t, { beats: ctx.beats, drop, rules: ctx.style.motion, scene: ctx.id, source: "impactFrame" });
+    const local = t - at;
+    // 반전은 두 장(초당 12장) — 섬광 횟수 규칙 안에서 한 번
+    invert.style.display = local >= 0 && frameOf(local) < 2 ? "block" : "none";
+    clear(g);
+    if (local >= 0 && local < 0.5) {
+      const f = frameOf(local);
+      const k = 1 - clamp(onTwos(local) / 0.5);
+      const n = 70;
+      const far = Math.hypot(W, H);
+      g.fillStyle = inkC;
+      g.beginPath();
+      for (let i = 0; i < n; i++) {
+        const a = ((i + rand(`impact:${f}`, i)) / n) * Math.PI * 2;
+        const inner = 1 + (1 - k) * 0.9 + rand(`impact:${f}`, i + 200) * 0.35;
+        const w = 0.03 + rand(`impact:${f}`, i + 400) * 0.03;
+        g.moveTo(ox + Math.cos(a) * rx * inner, oy + Math.sin(a) * ry * inner);
+        g.lineTo(ox + Math.cos(a - w) * far, oy + Math.sin(a - w) * far);
+        g.lineTo(ox + Math.cos(a + w) * far, oy + Math.sin(a + w) * far);
+        g.closePath();
+      }
+      g.fill();
+    }
+    return s;
+  };
+}
+
+/** 쪽 넘김 — 장면 끝에 새 원고지 한 장이 넘어와 앞 쪽을 덮는다. 접힌 자리에 망점 그림자 띠. 다음 장면은 빈 쪽에서 칸을 긋기 시작한다 */
+export function pageTurn(el: HTMLElement, o: { ctx: SceneCtx; at: number; dur?: number; from?: "right" | "left" }): (t: number) => void {
+  const { ctx } = o;
+  const W = ctx.meta.width;
+  const H = ctx.meta.height;
+  const sheet = div(el, `left:-60px;top:-60px;width:${W + 120}px;height:${H + 120}px;background:${color(ctx, "bg")};display:none`);
+  const fold = document.createElement("canvas");
+  fold.width = 90;
+  fold.height = H + 120;
+  const fromLeft = o.from === "left";
+  fold.style.cssText = `position:absolute;top:0;${fromLeft ? "right:-90px" : "left:-90px"};width:90px;height:${H + 120}px`;
+  sheet.append(fold);
+  const fg = fold.getContext("2d")!;
+  fg.fillStyle = color(ctx, "ink");
+  for (let y = 0; y < H + 120; y += 9) {
+    for (let x = 4; x < 90; x += 9) {
+      const v = fromLeft ? x / 90 : 1 - x / 90;
+      const r = 4.6 * Math.sqrt(v * 0.55);
+      fg.moveTo(x + r, y + ((x / 9) % 2) * 4.5);
+      fg.arc(x, y + ((x / 9) % 2) * 4.5, r, 0, Math.PI * 2);
+    }
+  }
+  fg.fill();
+  div(sheet, `top:0;${fromLeft ? "right:0" : "left:0"};width:6px;height:100%;background:${color(ctx, "ink")}`);
+  const dur = o.dur ?? 0.3;
+  return (t) => {
+    if (t < o.at) {
+      sheet.style.display = "none";
+      return;
+    }
+    sheet.style.display = "block";
+    const p = clamp(onTwos(t - o.at, 24) / dur);
+    const e = 1 - (1 - p) ** 3;
+    const off = (1 - e) * (W + 220);
+    applyStyle(sheet, { x: fromLeft ? -off : off, skewX: (1 - e) * (fromLeft ? 6 : -6) } as Style);
+  };
+}