kasaframe 0.1.1 → 0.1.4

package/themes/cartography/effects.ts

@@ -0,0 +1,845 @@
+import { clamp, ease, noise1, rand, spring, type SceneCtx } from "@kasaframe/core";
+import { dropBurst, type DropBurstState } from "@kasaframe/motion";
+import { partial, type Pt } from "@kasaframe/themes/slotkit";
+
+export type { SceneCtx };
+
+export interface Rect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** 높이 장의 봉우리 하나 — 자리(px)·높이·퍼짐(px). 높이가 음수면 골짜기 */
+export interface Peak {
+  x: number;
+  y: number;
+  h: number;
+  r: number;
+}
+
+const col = (ctx: SceneCtx, key: string): string => ctx.style.colors[key] ?? key;
+const mix = (c: string, a: number): string => `color-mix(in srgb, ${c} ${Math.round(clamp(a) * 100)}%, transparent)`;
+
+function div(doc: Document, css: string, parent?: HTMLElement): HTMLDivElement {
+  const d = doc.createElement("div");
+  d.style.cssText = `position:absolute;${css}`;
+  parent?.append(d);
+  return d;
+}
+
+/** 그리는 자리만큼만 잡는 캔버스 — 좌표는 화면(층) 기준 그대로 */
+function canvasIn(el: HTMLElement, r: Rect): { g: CanvasRenderingContext2D; clear(): void; c: HTMLCanvasElement } {
+  const x = Math.floor(r.x);
+  const y = Math.floor(r.y);
+  const w = Math.max(1, Math.ceil(r.w));
+  const h = Math.max(1, Math.ceil(r.h));
+  const c = el.ownerDocument.createElement("canvas");
+  c.width = w;
+  c.height = 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);
+  return { g, c, clear: () => g.clearRect(x, y, w, h) };
+}
+
+// 지명 글자 둘레 바탕색 테 — 등고선·길 위에서도 글이 먼저 읽힌다
+const halo = (bg: string, px = 2): string =>
+  [`0 0 ${px}px ${bg}`, `0 0 ${px * 2}px ${bg}`, `${px}px 0 0 ${bg}`, `-${px}px 0 0 ${bg}`, `0 ${px}px 0 ${bg}`, `0 -${px}px 0 ${bg}`, `${px}px ${px}px 0 ${bg}`, `-${px}px -${px}px 0 ${bg}`].join(", ");
+
+const fieldAt = (peaks: Peak[], x: number, y: number): number => {
+  let v = 0;
+  for (const p of peaks) v += p.h * Math.exp(-((x - p.x) ** 2 + (y - p.y) ** 2) / (2 * p.r * p.r));
+  return v;
+};
+
+// 굽은 길 — 점들을 Catmull-Rom 으로 잇고 촘촘한 꺾은선(4px 마다)으로 바꾼다. 길이 누적도 같이
+function smooth(points: readonly Pt[]): { pts: Pt[]; len: number[] } {
+  const out: Pt[] = [];
+  const P = [points[0], ...points, points[points.length - 1]];
+  for (let i = 1; i < P.length - 2; i++) {
+    const [p0, p1, p2, p3] = [P[i - 1], P[i], P[i + 1], P[i + 2]];
+    const n = Math.max(2, Math.ceil(Math.hypot(p2[0] - p1[0], p2[1] - p1[1]) / 4));
+    for (let k = 0; k < n; k++) {
+      const s = k / n;
+      const s2 = s * s;
+      const s3 = s2 * s;
+      out.push([
+        0.5 * (2 * p1[0] + (-p0[0] + p2[0]) * s + (2 * p0[0] - 5 * p1[0] + 4 * p2[0] - p3[0]) * s2 + (-p0[0] + 3 * p1[0] - 3 * p2[0] + p3[0]) * s3),
+        0.5 * (2 * p1[1] + (-p0[1] + p2[1]) * s + (2 * p0[1] - 5 * p1[1] + 4 * p2[1] - p3[1]) * s2 + (-p0[1] + 3 * p1[1] - 3 * p2[1] + p3[1]) * s3),
+      ]);
+    }
+  }
+  out.push(points[points.length - 1]);
+  const len = [0];
+  for (let i = 1; i < out.length; i++) len.push(len[i - 1] + Math.hypot(out[i][0] - out[i - 1][0], out[i][1] - out[i - 1][1]));
+  return { pts: out, len };
+}
+
+const along = (path: { pts: Pt[]; len: number[] }, s: number): Pt => {
+  const L = path.len[path.len.length - 1];
+  const d = clamp(s, 0, L);
+  let i = 1;
+  while (i < path.len.length - 1 && path.len[i] < d) i++;
+  const a = path.pts[i - 1];
+  const b = path.pts[i];
+  const seg = path.len[i] - path.len[i - 1] || 1;
+  const k = (d - path.len[i - 1]) / seg;
+  return [a[0] + (b[0] - a[0]) * k, a[1] + (b[1] - a[1]) * k];
+};
+
+const stroke = (g: CanvasRenderingContext2D, pts: readonly Pt[]): void => {
+  if (pts.length < 2) return;
+  g.beginPath();
+  g.moveTo(pts[0][0], pts[0][1]);
+  for (let i = 1; i < pts.length; i++) g.lineTo(pts[i][0], pts[i][1]);
+  g.stroke();
+};
+
+/**
+ * 지도 종이 — 바탕색 종이에 킬로미터 격자(가는 선)와 도곽선(두 줄 테). 서 있다.
+ * 격자에 좌표 숫자를 달지 않는다 — 지도 위 숫자는 사실만
+ */
+export function mapPaper(el: HTMLElement, o: { ctx: SceneCtx; grid?: number; frame?: boolean }): (t: number) => void {
+  const { ctx } = o;
+  const doc = el.ownerDocument;
+  const W = ctx.meta.width;
+  const H = ctx.meta.height;
+  div(doc, `inset:0;background:${col(ctx, "paper")}`, el);
+  const gap = o.grid ?? Math.round(Math.min(W, H) / 4.5);
+  const ink = col(ctx, "ink");
+  div(doc, `inset:0;background-image:linear-gradient(to right, ${mix(ink, 0.13)} 1px, transparent 1px), linear-gradient(to bottom, ${mix(ink, 0.13)} 1px, transparent 1px);background-size:${gap}px ${gap}px;background-position:${(W / 2) % gap}px ${(H / 2) % gap}px`, el);
+  if (o.frame !== false) {
+    div(doc, `left:22px;top:22px;right:22px;bottom:22px;border:3px solid ${mix(ink, 0.85)}`, el);
+    div(doc, `left:30px;top:30px;right:30px;bottom:30px;border:1px solid ${mix(ink, 0.6)}`, el);
+  }
+  return () => {};
+}
+
+export interface ContourOpts {
+  ctx: SceneCtx;
+  peaks: Peak[];
+  /** 등고선 간격(높이 단위). 다섯 줄마다 굵은 줄 */
+  interval?: number;
+  /** 측량 시작 — origin 에서 반지름이 커지며 선이 그려진다. 없으면 처음부터 다 있다 */
+  at?: number;
+  dur?: number;
+  origin?: [number, number];
+  /** 지형 음영·숲(아주 옅게). 기본 true */
+  relief?: boolean;
+}
+
+/**
+ * 등고선 지도 — 봉우리 높이 장에서 등고선을 뽑아(다섯 줄마다 굵게) 측량 지점에서 번져 그린다. 봉우리 = 공급자, 높이 = 그 값.
+ * 다 그린 뒤엔 서 있다
+ */
+export function contourMap(el: HTMLElement, o: ContourOpts): (t: number) => void {
+  const { ctx } = o;
+  const doc = el.ownerDocument;
+  const W = ctx.meta.width;
+  const H = ctx.meta.height;
+  const s = 10;
+  const nx = Math.ceil(W / s) + 1;
+  const ny = Math.ceil(H / s) + 1;
+  const v = new Float32Array(nx * ny);
+  let lo = Infinity;
+  let hi = -Infinity;
+  for (let j = 0; j < ny; j++)
+    for (let i = 0; i < nx; i++) {
+      const f = fieldAt(o.peaks, i * s, j * s);
+      v[j * nx + i] = f;
+      lo = Math.min(lo, f);
+      hi = Math.max(hi, f);
+    }
+  const step = o.interval ?? Math.max(0.1, (hi - lo) / 24);
+  // 칸마다 꼭짓점 넷의 위아래로 선분을 고른다(marching squares). 가장자리 0 위·1 오른·2 아래·3 왼
+  const CASES: number[][][] = [[], [[3, 2]], [[2, 1]], [[3, 1]], [[0, 1]], [[3, 0], [2, 1]], [[0, 2]], [[3, 0]], [[3, 0]], [[0, 2]], [[0, 1], [3, 2]], [[0, 1]], [[3, 1]], [[2, 1]], [[3, 2]], []];
+  const segs: { d: number; idx: boolean; x1: number; y1: number; x2: number; y2: number }[] = [];
+  const [ox, oy] = o.origin ?? [W / 2, H / 2];
+  for (let k = Math.ceil(lo / step); k * step <= hi; k++) {
+    const L = k * step;
+    if (Math.abs(L) < 1e-6) continue;
+    for (let j = 0; j < ny - 1; j++)
+      for (let i = 0; i < nx - 1; i++) {
+        const a = v[j * nx + i];
+        const b = v[j * nx + i + 1];
+        const c = v[(j + 1) * nx + i + 1];
+        const d = v[(j + 1) * nx + i];
+        const id = (a > L ? 8 : 0) | (b > L ? 4 : 0) | (c > L ? 2 : 0) | (d > L ? 1 : 0);
+        if (id === 0 || id === 15) continue;
+        const x0 = i * s;
+        const y0 = j * s;
+        const edge = (e: number): Pt => {
+          if (e === 0) return [x0 + s * ((L - a) / (b - a)), y0];
+          if (e === 1) return [x0 + s, y0 + s * ((L - b) / (c - b))];
+          if (e === 2) return [x0 + s * ((L - d) / (c - d)), y0 + s];
+          return [x0, y0 + s * ((L - a) / (d - a))];
+        };
+        for (const [e1, e2] of CASES[id]) {
+          const p = edge(e1);
+          const q = edge(e2);
+          segs.push({ d: Math.hypot((p[0] + q[0]) / 2 - ox, (p[1] + q[1]) / 2 - oy), idx: k % 5 === 0, x1: p[0], y1: p[1], x2: q[0], y2: q[1] });
+        }
+      }
+  }
+  segs.sort((p, q) => p.d - q.d);
+  const far = Math.hypot(Math.max(ox, W - ox), Math.max(oy, H - oy));
+  // 지형 음영 — 북서쪽 빛, 1/8 크기로 그려 늘린다. 숲은 낮고 완만한 곳에 옅게
+  let shade: HTMLCanvasElement | null = null;
+  if (o.relief !== false) {
+    const rw = Math.ceil(W / 8);
+    const rh = Math.ceil(H / 8);
+    shade = doc.createElement("canvas");
+    shade.width = rw;
+    shade.height = rh;
+    shade.style.cssText = `position:absolute;left:0;top:0;width:${W}px;height:${H}px;pointer-events:none`;
+    const sg = shade.getContext("2d")!;
+    const im = sg.createImageData(rw, rh);
+    const span = Math.max(1e-6, hi - lo);
+    const forest = col(ctx, "forest");
+    const relief = col(ctx, "relief");
+    const rgb = (c: string): [number, number, number] => {
+      const m = /^#([0-9a-f]{6})$/i.exec(c.trim());
+      const n = m ? parseInt(m[1], 16) : 0x8f989c;
+      return [n >> 16, (n >> 8) & 255, n & 255];
+    };
+    const [fr, fg, fb] = rgb(forest);
+    const [rr, rg, rb] = rgb(relief);
+    for (let j = 0; j < rh; j++)
+      for (let i = 0; i < rw; i++) {
+        const x = i * 8;
+        const y = j * 8;
+        const dx = (fieldAt(o.peaks, x + 8, y) - fieldAt(o.peaks, x - 8, y)) / span;
+        const dy = (fieldAt(o.peaks, x, y + 8) - fieldAt(o.peaks, x, y - 8)) / span;
+        // 빛이 북서에서 — 동남으로 기운 비탈이 어둡다
+        const lit = clamp(0.5 - (dx + dy) * 6);
+        const dark = clamp(0.5 - lit) * 2;
+        const p = (j * rw + i) * 4;
+        const wood = noise1("forest", x * 0.006 + y * 0.0091) + noise1("forest-y", y * 0.007 - x * 0.003) > 0.9 && Math.hypot(dx, dy) < 0.015;
+        if (wood) {
+          im.data[p] = fr;
+          im.data[p + 1] = fg;
+          im.data[p + 2] = fb;
+          im.data[p + 3] = 110;
+        } else {
+          im.data[p] = rr;
+          im.data[p + 1] = rg;
+          im.data[p + 2] = rb;
+          im.data[p + 3] = Math.round(dark * 60);
+        }
+      }
+    sg.putImageData(im, 0, 0);
+    el.append(shade);
+  }
+  const { g, clear } = canvasIn(el, { x: 0, y: 0, w: W, h: H });
+  const brown = col(ctx, "contour");
+  const deep = col(ctx, "contourDeep");
+  let drawn = -1;
+  return (t) => {
+    // 측량은 고른 빠르기로 — 끝에서 느려지면 화면이 서 버린다
+    const p = o.at === undefined ? 1 : clamp((t - o.at) / (o.dur ?? 1.2));
+    // 드러나는 넓이가 고르게 늘도록 — 반지름이 처음에 빨리 커진다
+    const R = Math.sqrt(p) * far * 1.02;
+    if (shade) shade.style.clipPath = p >= 1 ? "" : `circle(${R.toFixed(1)}px at ${ox}px ${oy}px)`;
+    let n = 0;
+    while (n < segs.length && segs[n].d <= R) n++;
+    if (n === drawn) return;
+    drawn = n;
+    clear();
+    if (!n) return;
+    g.lineCap = "round";
+    for (const pass of [false, true]) {
+      g.strokeStyle = pass ? deep : brown;
+      g.lineWidth = pass ? 3 : 1.6;
+      g.beginPath();
+      for (let i = 0; i < n; i++) {
+        const q = segs[i];
+        if (q.idx !== pass) continue;
+        g.moveTo(q.x1, q.y1);
+        g.lineTo(q.x2, q.y2);
+      }
+      g.stroke();
+    }
+  };
+}
+
+export interface LetterOpts {
+  ctx: SceneCtx;
+  text: string;
+  x: number;
+  y: number;
+  at: number;
+  /** 글자 px */
+  size: number;
+  font?: "display" | "sans" | "mono";
+  /** colors 키나 색. 기본 ink */
+  color?: string;
+  /** 다 앉은 자간(em) — 넓은 지역 이름은 0.3 넘게. 기본 0.02 */
+  spaced?: number;
+  /** x 가 글의 어디인가. 기본 left */
+  anchor?: "left" | "center" | "right";
+  italic?: boolean;
+  weight?: number;
+  /** 다 쓰는 데 걸리는 시간. 기본 글자 수 × 0.025 */
+  dur?: number;
+}
+
+/** 지명 글자 — 바탕색 테를 두르고, 땅에 내려앉으며 넓게 벌어졌던 자간이 제자리로 모인다 */
+export function lettering(el: HTMLElement, o: LetterOpts): (t: number) => void {
+  const { ctx } = o;
+  const doc = el.ownerDocument;
+  const f = o.font ?? "sans";
+  const weight = o.weight ?? (f === "display" ? 700 : f === "mono" ? 500 : 700);
+  const shift = o.anchor === "center" ? "translateX(-50%)" : o.anchor === "right" ? "translateX(-100%)" : "";
+  const box = div(doc, `left:${o.x}px;top:${o.y}px;white-space:pre;line-height:1;font:${o.italic ? "italic " : ""}${weight} ${o.size}px ${ctx.style.fonts[f]};color:${col(ctx, o.color ?? "ink")};text-shadow:${halo(col(ctx, "paper"), Math.max(2, Math.round(o.size / 16)))};transform:${shift}`, el);
+  const chars = Array.from(o.text).map((ch) => {
+    const s = doc.createElement("span");
+    s.textContent = ch;
+    box.append(s);
+    return s;
+  });
+  const spaced = o.spaced ?? 0.02;
+  const dur = o.dur ?? Math.min(0.5, chars.length * 0.025);
+  return (t) => {
+    const k = t - o.at;
+    box.style.display = k < 0 ? "none" : "";
+    if (k < 0) return;
+    const n = k >= dur ? chars.length : Math.floor((k / Math.max(0.01, dur)) * chars.length) + 1;
+    chars.forEach((s, i) => (s.style.visibility = i < n ? "visible" : "hidden"));
+    const settle = ease.outCubic(clamp(k / (dur + 0.25)));
+    box.style.letterSpacing = `${(spaced + 0.35 * (1 - settle)).toFixed(3)}em`;
+  };
+}
+
+export interface MarkOpts {
+  ctx: SceneCtx;
+  x: number;
+  y: number;
+  at: number;
+  /** dot 마을 · peak 봉우리 세모 · pass 고개 · origin 출발점(겹 동그라미) · node 길목 */
+  kind?: "dot" | "peak" | "pass" | "origin" | "node";
+  size?: number;
+  /** colors 키나 색. 기본 ink, origin 은 accent */
+  color?: string;
+  label?: string;
+  labelSize?: number;
+  side?: "right" | "left" | "above" | "below";
+  font?: "display" | "sans" | "mono";
+  spaced?: number;
+  italic?: boolean;
+}
+
+/** 지점 기호 — 측량 고리가 한 번 번지며 기호가 찍히고, 곁에 지명이 내려앉는다 */
+export function placeMark(el: HTMLElement, o: MarkOpts): (t: number) => void {
+  const { ctx } = o;
+  const doc = el.ownerDocument;
+  const size = o.size ?? 22;
+  const kind = o.kind ?? "dot";
+  const c = col(ctx, o.color ?? (kind === "origin" ? "accent" : "ink"));
+  const paper = col(ctx, "paper");
+  const sym = div(doc, `left:${o.x - size}px;top:${o.y - size}px;width:${size * 2}px;height:${size * 2}px;pointer-events:none`, el);
+  const S = size;
+  const shapes: Record<string, string> = {
+    dot: `<circle cx="${S}" cy="${S}" r="${S * 0.42}" fill="${c}" stroke="${paper}" stroke-width="${S * 0.16}"/>`,
+    node: `<circle cx="${S}" cy="${S}" r="${S * 0.42}" fill="${paper}" stroke="${c}" stroke-width="${S * 0.2}"/>`,
+    peak: `<path d="M${S} ${S * 0.25} L${S * 1.75} ${S * 1.6} L${S * 0.25} ${S * 1.6} Z" fill="${c}" stroke="${paper}" stroke-width="${S * 0.12}" stroke-linejoin="round"/>`,
+    pass: `<path d="M${S * 0.45} ${S * 0.3} Q${S * 0.95} ${S} ${S * 0.45} ${S * 1.7} M${S * 1.55} ${S * 0.3} Q${S * 1.05} ${S} ${S * 1.55} ${S * 1.7}" fill="none" stroke="${c}" stroke-width="${S * 0.22}" stroke-linecap="round"/>`,
+    origin: `<circle cx="${S}" cy="${S}" r="${S * 0.78}" fill="none" stroke="${c}" stroke-width="${S * 0.14}"/><circle cx="${S}" cy="${S}" r="${S * 0.36}" fill="${c}"/>`,
+  };
+  sym.innerHTML = `<svg viewBox="0 0 ${S * 2} ${S * 2}" width="${S * 2}" height="${S * 2}" style="display:block;overflow:visible">${shapes[kind]}</svg>`;
+  const ring = div(doc, `left:${o.x - size * 2}px;top:${o.y - size * 2}px;width:${size * 4}px;height:${size * 4}px;border-radius:50%;border:3px solid ${col(ctx, "accent")};pointer-events:none`, el);
+  const ls = o.labelSize ?? 40;
+  const side = o.side ?? "right";
+  const gap = size + 8;
+  const label = o.label
+    ? lettering(el, {
+        ctx,
+        text: o.label,
+        x: side === "right" ? o.x + gap : side === "left" ? o.x - gap : o.x,
+        y: side === "above" ? o.y - gap - ls : side === "below" ? o.y + gap : o.y - ls * 0.52,
+        at: o.at + 0.06,
+        size: ls,
+        font: o.font,
+        spaced: o.spaced,
+        italic: o.italic,
+        anchor: side === "left" ? "right" : side === "right" ? "left" : "center",
+      })
+    : null;
+  return (t) => {
+    const k = t - o.at;
+    sym.style.display = k < 0 ? "none" : "";
+    if (k >= 0) sym.style.transform = `scale(${spring(k, { from: 0, to: 1, stiffness: 380, damping: 16 }).toFixed(4)})`;
+    const rk = clamp(k / 0.5);
+    ring.style.display = k >= 0 && k < 0.5 ? "" : "none";
+    if (k >= 0 && k < 0.5) {
+      ring.style.transform = `scale(${(0.3 + 1.2 * ease.outCubic(rk)).toFixed(3)})`;
+      ring.style.opacity = (1 - rk).toFixed(3);
+    }
+    label?.(t);
+  };
+}
+
+export interface RouteOpts {
+  ctx: SceneCtx;
+  /** 지나는 점(px) — 부드럽게 굽혀 잇는다 */
+  points: Pt[];
+  at: number;
+  /** 긋는 시간. 기본 길이 / 1400px·초 */
+  dur?: number;
+  /** colors 키나 색. 기본 accent */
+  color?: string;
+  width?: number;
+  /** 다 그은 뒤 길 위를 가는 나그네 점 수. 기본 2 */
+  walkers?: number;
+  /** 나그네 빠르기(px/초). 기본 320 */
+  speed?: number;
+  /** 나그네가 든 이름표(되풀이) — 요청에 실린 것 */
+  tags?: string[];
+  tagSize?: number;
+}
+
+/**
+ * 길 = 요청 — 빨간 점선이 땅을 따라 굽어 그어지고(머리에 나그네 점), 다 그은 뒤엔 점선이 흐르고 나그네가 길 위를 늘 간다.
+ * 길이가 곧 거리 = 지연. 끊긴 길(폴백)은 다른 길을 하나 더 그어 돌아간다
+ */
+export function route(el: HTMLElement, o: RouteOpts): (t: number) => void {
+  const { ctx } = o;
+  const doc = el.ownerDocument;
+  const path = smooth(o.points);
+  const L = path.len[path.len.length - 1];
+  const xs = path.pts.map((q) => q[0]);
+  const ys = path.pts.map((q) => q[1]);
+  const pad = 40;
+  const box = { x: Math.min(...xs) - pad, y: Math.min(...ys) - pad, w: Math.max(...xs) - Math.min(...xs) + pad * 2, h: Math.max(...ys) - Math.min(...ys) + pad * 2 };
+  const { g, clear } = canvasIn(el, box);
+  const c = col(ctx, o.color ?? "accent");
+  const paper = col(ctx, "paper");
+  const w = o.width ?? 7;
+  const dur = o.dur ?? L / 1400;
+  const n = o.walkers ?? 2;
+  const speed = o.speed ?? 320;
+  const W = ctx.meta.width;
+  const tagSize = o.tagSize ?? 26;
+  const tags = (o.tags ?? []).length
+    ? Array.from({ length: n }, (_, k) => {
+        const text = o.tags![k % o.tags!.length];
+        const s = div(doc, `left:0;top:0;white-space:pre;line-height:1;font:500 ${tagSize}px ${ctx.style.fonts.mono};color:${c};text-shadow:${halo(paper, 2)}`, el);
+        s.textContent = text;
+        return { s, w: Array.from(text).length * tagSize * 0.6 };
+      })
+    : [];
+  const dot = (q: Pt, r: number) => {
+    g.beginPath();
+    g.arc(q[0], q[1], r + 3, 0, Math.PI * 2);
+    g.fillStyle = paper;
+    g.fill();
+    g.beginPath();
+    g.arc(q[0], q[1], r, 0, Math.PI * 2);
+    g.fillStyle = c;
+    g.fill();
+  };
+  return (t) => {
+    clear();
+    for (const tg of tags) tg.s.style.display = "none";
+    const k = t - o.at;
+    if (k < 0) return;
+    const p = clamp(k / Math.max(0.01, dur));
+    const pts = p >= 1 ? path.pts : partial(path.pts, p);
+    g.lineCap = "round";
+    g.lineJoin = "round";
+    g.setLineDash([]);
+    g.strokeStyle = paper;
+    g.lineWidth = w + 6;
+    stroke(g, pts);
+    g.strokeStyle = c;
+    g.lineWidth = w;
+    g.setLineDash([w * 3.4, w * 2]);
+    // 점선이 가는 쪽으로 흐른다 — 다 그은 뒤에도 길 안이 쉬지 않는다
+    g.lineDashOffset = -k * 150;
+    stroke(g, pts);
+    g.setLineDash([]);
+    if (p < 1) {
+      dot(pts[pts.length - 1], w * 1.5);
+      return;
+    }
+    for (let i = 0; i < n; i++) {
+      const sDist = (((k - dur) * speed + (i * L) / n) % L + L) % L;
+      const q = along(path, sDist);
+      dot(q, w * 1.4);
+      const tg = tags[i];
+      if (tg && sDist > 30 && sDist < L - 30) {
+        tg.s.style.display = "";
+        const left = clamp(q[0] - tg.w / 2, 80, W - 80 - tg.w);
+        tg.s.style.transform = `translate(${left.toFixed(1)}px, ${(q[1] - tagSize - w * 2 - 6).toFixed(1)}px)`;
+      }
+    }
+  };
+}
+
+/**
+ * 축척 막대 — 흑백 번갈이 칸이 at 부터 every 초마다 한 칸씩 붙는다. 칸 하나 = 단위 하나(값이 곧 길이).
+ * shrinkAt 에 keep 칸만 남기고 오른쪽부터 접혀 들어간다(값이 줄었다). 끝 글자는 막대 끝을 따라간다
+ */
+export function scaleBar(
+  el: HTMLElement,
+  o: { ctx: SceneCtx; x: number; y: number; seg: number; count: number; at: number; every?: number; h?: number; shrinkAt?: number; keep?: number; start?: string; ends?: [string, string?]; labelSize?: number },
+): (t: number) => void {
+  const { ctx } = o;
+  const doc = el.ownerDocument;
+  const h = o.h ?? 26;
+  const ink = col(ctx, "ink");
+  const paper = col(ctx, "paper");
+  const bar = div(doc, `left:${o.x}px;top:${o.y}px;height:${h}px;width:0px;overflow:hidden;border:3px solid ${ink};box-sizing:content-box`, el);
+  for (let i = 0; i < o.count; i++) div(doc, `left:${i * o.seg}px;top:0;width:${o.seg}px;height:${h}px;background:${i % 2 ? paper : ink}`, bar);
+  const ls = o.labelSize ?? 34;
+  const start = o.start ? lettering(el, { ctx, text: o.start, x: o.x, y: o.y + h + 14, at: o.at, size: ls * 0.8, font: "mono", anchor: "center" }) : null;
+  const endA = o.ends ? div(doc, `top:${o.y + h / 2 - ls * 0.55}px;white-space:pre;line-height:1;font:700 ${ls}px ${ctx.style.fonts.display};color:${ink};text-shadow:${halo(paper, 2)}`, el) : null;
+  if (endA && o.ends) endA.textContent = o.ends[0];
+  const every = o.every ?? 0.05;
+  return (t) => {
+    let len = (t < o.at ? 0 : Math.min(o.count, Math.floor((t - o.at) / every) + 1)) * o.seg;
+    if (o.shrinkAt !== undefined && t >= o.shrinkAt) {
+      const k = ease.inOutCubic(clamp((t - o.shrinkAt) / 0.3));
+      len = (o.count + ((o.keep ?? 1) - o.count) * k) * o.seg;
+    }
+    bar.style.display = len > 0 ? "" : "none";
+    bar.style.width = `${len.toFixed(1)}px`;
+    start?.(t);
+    if (endA && o.ends) {
+      endA.style.display = len > 0 ? "" : "none";
+      endA.style.left = `${(o.x + len + 24).toFixed(1)}px`;
+      endA.textContent = o.shrinkAt !== undefined && t >= o.shrinkAt + 0.3 && o.ends[1] ? o.ends[1] : o.ends[0];
+    }
+  };
+}
+
+export interface IsoOpts {
+  ctx: SceneCtx;
+  origin: [number, number];
+  /** 고리 사이(px) — 같은 시간 간격 */
+  step: number;
+  rings: number;
+  at: number;
+  /** 고리 하나 그리는 사이(초). 기본 0.1 */
+  every?: number;
+  /** 고리마다 붙일 글(시간) — 없으면 글 없음 */
+  labels?: string[];
+  /** 글이 붙는 방위(도, 0 = 오른쪽, 시계 방향). 기본 -50 */
+  labelAngle?: number;
+  /** 밖에서 안으로 좁혀 온다(드롭 앞 모아 올리기) */
+  inward?: boolean;
+  seed?: string | number;
+}
+
+/**
+ * 등시선 — 출발점에서 같은 시간에 닿는 곳을 잇는 굽은 고리가 한 겹씩 번진다(안에서 밖으로, inward 면 밖에서 안으로).
+ * 거리가 곧 지연 — 고리 사이가 같은 ms. 띠는 번갈아 아주 옅게 칠한다
+ */
+export function isochrones(el: HTMLElement, o: IsoOpts): (t: number) => void {
+  const { ctx } = o;
+  const W = ctx.meta.width;
+  const H = ctx.meta.height;
+  const { g, clear } = canvasIn(el, { x: 0, y: 0, w: W, h: H });
+  const seed = o.seed ?? `${ctx.id}:iso`;
+  const N = 120;
+  const wob = Array.from({ length: N }, (_, i) => 0.085 * (noise1(seed, (i / N) * 7) + 0.5 * noise1(`${seed}:2`, (i / N) * 17)));
+  const ring = (k: number): Pt[] =>
+    Array.from({ length: N + 1 }, (_, i) => {
+      const a = (i / N) * Math.PI * 2;
+      const r = k * o.step * (1 + wob[i % N] * Math.min(1, k / 2));
+      return [o.origin[0] + Math.cos(a) * r, o.origin[1] + Math.sin(a) * r] as Pt;
+    });
+  const rings = Array.from({ length: o.rings }, (_, i) => ring(i + 1));
+  const water = col(ctx, "water");
+  const every = o.every ?? 0.1;
+  const when = (i: number) => o.at + (o.inward ? o.rings - 1 - i : i) * every;
+  const labels = (o.labels ?? []).slice(0, o.rings).map((text, i) => {
+    const a = ((o.labelAngle ?? -50) * Math.PI) / 180;
+    const idx = Math.round(((((a / (Math.PI * 2)) % 1) + 1) % 1) * N);
+    const q = rings[i][idx];
+    return lettering(el, { ctx, text, x: q[0], y: q[1] - 14, at: when(i) + 0.15, size: 26, font: "mono", color: "water", anchor: "center" });
+  });
+  let drawn = "";
+  return (t) => {
+    const state = rings.map((_, i) => clamp((t - when(i)) / 0.15)).map((p) => p.toFixed(3)).join(",");
+    if (state !== drawn) {
+      drawn = state;
+      clear();
+      // 띠 — 고리 사이만 번갈아 아주 옅게(원판을 겹쳐 칠하면 가운데가 짙어진다)
+      rings.forEach((r, i) => {
+        if (t < when(i) + 0.15) return;
+        g.beginPath();
+        r.forEach((q, j) => (j ? g.lineTo(q[0], q[1]) : g.moveTo(q[0], q[1])));
+        g.closePath();
+        if (i > 0) {
+          rings[i - 1].forEach((q, j) => (j ? g.lineTo(q[0], q[1]) : g.moveTo(q[0], q[1])));
+          g.closePath();
+        }
+        g.fillStyle = mix(water, i % 2 ? 0.05 : 0.11);
+        g.fill("evenodd");
+      });
+      g.lineWidth = 2.2;
+      g.strokeStyle = water;
+      rings.forEach((r, i) => {
+        const p = clamp((t - when(i)) / 0.15);
+        if (p <= 0) return;
+        stroke(g, p >= 1 ? r : partial(r, p));
+      });
+    }
+    for (const paint of labels) paint(t);
+  };
+}
+
+/**
+ * 단면도 — 값을 높이로 본 땅의 옆모습(왼쪽→오른쪽으로 그려진다). 아래는 빗금, 낮은 골(water 구간)엔 물이 찬다.
+ * 다 그린 뒤엔 나그네 점이 단면 위를 왼쪽에서 오른쪽으로 늘 걷는다(하루가 흐른다)
+ */
+export function profile(
+  el: HTMLElement,
+  o: { ctx: SceneCtx; rect: Rect; value: (u: number) => number; at: number; dur?: number; water?: [number, number]; walk?: number },
+): (t: number) => void {
+  const { ctx, rect: r } = o;
+  const { g, clear } = canvasIn(el, { x: r.x - 20, y: r.y - 30, w: r.w + 40, h: r.h + 50 });
+  const N = 240;
+  const pts: Pt[] = Array.from({ length: N + 1 }, (_, i) => [r.x + (r.w * i) / N, r.y + r.h * (1 - clamp(o.value(i / N)))] as Pt);
+  const ink = col(ctx, "ink");
+  const brown = col(ctx, "contour");
+  const water = col(ctx, "water");
+  const paper = col(ctx, "paper");
+  const dur = o.dur ?? 0.7;
+  const base = r.y + r.h;
+  return (t) => {
+    clear();
+    const k = t - o.at;
+    if (k < 0) return;
+    const p = clamp(k / dur);
+    const m = Math.max(1, Math.round(p * N));
+    const vis = pts.slice(0, m + 1);
+    const xEnd = vis[vis.length - 1][0];
+    // 빗금 — 땅 속
+    g.save();
+    g.beginPath();
+    g.moveTo(r.x, base);
+    for (const q of vis) g.lineTo(q[0], q[1]);
+    g.lineTo(xEnd, base);
+    g.closePath();
+    g.clip();
+    g.strokeStyle = mix(brown, 0.55);
+    g.lineWidth = 2;
+    g.beginPath();
+    for (let x = r.x - r.h; x < xEnd; x += 16) {
+      g.moveTo(x, base);
+      g.lineTo(x + r.h, base - r.h);
+    }
+    g.stroke();
+    g.restore();
+    // 물 — 골이 다 그려진 뒤 땅 위로 차오른다(가장 싼 골짜기 = 호수)
+    if (o.water) {
+      const fill = ease.outCubic(clamp((t - (o.at + dur * o.water[1])) / 0.4));
+      if (fill > 0) {
+        const i0 = Math.round(o.water[0] * N);
+        const i1 = Math.round(o.water[1] * N);
+        let low = -Infinity;
+        for (let i = i0; i <= i1; i++) low = Math.max(low, pts[i][1]);
+        const rim = Math.max(pts[i0][1], pts[i1][1]);
+        const level = low - (low - rim) * 0.85 * fill;
+        g.save();
+        g.beginPath();
+        g.moveTo(pts[i0][0], rim - 400);
+        for (let i = i0; i <= i1; i++) g.lineTo(pts[i][0], pts[i][1]);
+        g.lineTo(pts[i1][0], rim - 400);
+        g.closePath();
+        g.clip();
+        g.fillStyle = mix(water, 0.55);
+        g.fillRect(pts[i0][0], level, pts[i1][0] - pts[i0][0], low - level + 2);
+        g.restore();
+        let a = i0;
+        while (a < i1 && pts[a][1] < level) a++;
+        let b = i1;
+        while (b > i0 && pts[b][1] < level) b--;
+        g.strokeStyle = water;
+        g.lineWidth = 3;
+        g.beginPath();
+        g.moveTo(pts[a][0], level);
+        g.lineTo(pts[b][0], level);
+        g.stroke();
+      }
+    }
+    g.strokeStyle = ink;
+    g.lineWidth = 5;
+    g.lineJoin = "round";
+    stroke(g, vis);
+    g.lineWidth = 2;
+    g.beginPath();
+    g.moveTo(r.x, base);
+    g.lineTo(xEnd, base);
+    g.stroke();
+    const head = p < 1 ? vis[vis.length - 1] : pts[Math.round(((((k - dur) * (o.walk ?? 0.22)) % 1) + 1) % 1 * N)];
+    g.beginPath();
+    g.arc(head[0], head[1], 12, 0, Math.PI * 2);
+    g.fillStyle = paper;
+    g.fill();
+    g.beginPath();
+    g.arc(head[0], head[1], 9, 0, Math.PI * 2);
+    g.fillStyle = col(ctx, "accent");
+    g.fill();
+  };
+}
+
+export interface LegendRow {
+  /** route 빨간 점선 · contour 등고선 · peak 봉우리 · dot 마을 · iso 등시선 */
+  sym: "route" | "contour" | "peak" | "dot" | "iso";
+  label: string;
+}
+
+/** 범례 상자 — 두 줄 도곽 테 안에 제목, 기호와 낱말이 한 줄씩 붙는다. 끝 카드(도곽 표제)로도 쓴다 */
+export function legendBox(
+  el: HTMLElement,
+  o: { ctx: SceneCtx; rect: Rect; title?: string; rows?: LegendRow[]; at: number; every?: number; titleSize?: number; rowSize?: number; logo?: string; logoW?: number; sub?: string; subAt?: number },
+): (t: number) => void {
+  const { ctx, rect: r } = o;
+  const doc = el.ownerDocument;
+  const ink = col(ctx, "ink");
+  const paper = col(ctx, "paper");
+  const box = div(doc, `left:${r.x}px;top:${r.y}px;width:${r.w}px;height:${r.h}px;background:${col(ctx, "surface")};border:3px solid ${ink};box-sizing:border-box`, el);
+  div(doc, `left:6px;top:6px;right:6px;bottom:6px;border:1px solid ${ink}`, box);
+  const ts = o.titleSize ?? 40;
+  const rs = o.rowSize ?? 30;
+  // 표제(끝 카드) — 로고가 맨 위, 그 아래 제목, 맨 아래 부제(주소)
+  let logo: HTMLDivElement | null = null;
+  let logoH = 0;
+  if (o.logo) {
+    const lw = o.logoW ?? r.w * 0.4;
+    logoH = lw * 0.57;
+    logo = div(doc, `left:${r.x + (r.w - lw) / 2}px;top:${r.y + 40}px;width:${lw}px;color:${ink};transform-origin:50% 50%`, el);
+    logo.innerHTML = o.logo.replace(/ width="\d+" height="\d+"/, ' width="100%" style="display:block"');
+  }
+  const titleY = r.y + (logo ? 40 + logoH + 36 : 26);
+  const title = o.title ? lettering(el, { ctx, text: o.title, x: r.x + r.w / 2, y: titleY, at: o.at + (logo ? 0.3 : 0.08), size: ts, font: "display", anchor: "center" }) : null;
+  const sub = o.sub ? lettering(el, { ctx, text: o.sub, x: r.x + r.w / 2, y: titleY + ts + 34, at: o.subAt ?? o.at + 0.6, size: Math.round(ts * 0.36), font: "mono", anchor: "center", color: "accentText" }) : null;
+  const every = o.every ?? 0.1;
+  const symSvg = (s: LegendRow["sym"]): string => {
+    const a = col(ctx, "accent");
+    if (s === "route") return `<path d="M2 12 L54 12" stroke="${a}" stroke-width="6" stroke-dasharray="14 8"/>`;
+    if (s === "contour") return `<path d="M2 16 Q16 4 28 12 T54 8" stroke="${col(ctx, "contour")}" stroke-width="3" fill="none"/>`;
+    if (s === "iso") return `<path d="M2 18 Q28 0 54 18" stroke="${col(ctx, "water")}" stroke-width="3" fill="none"/>`;
+    if (s === "peak") return `<path d="M28 2 L44 22 L12 22 Z" fill="${ink}"/>`;
+    return `<circle cx="28" cy="12" r="8" fill="${ink}" stroke="${paper}" stroke-width="3"/>`;
+  };
+  const top0 = titleY + (o.title ? ts + 22 : 0);
+  const rows = (o.rows ?? []).map((row, i) => {
+    const y = top0 + i * (rs + 18);
+    const sym = div(doc, `left:${r.x + 28}px;top:${y + rs / 2 - 12}px;width:56px;height:24px`, el);
+    sym.innerHTML = `<svg width="56" height="24" viewBox="0 0 56 24" style="display:block">${symSvg(row.sym)}</svg>`;
+    const lab = lettering(el, { ctx, text: row.label, x: r.x + 100, y, at: o.at + 0.15 + i * every, size: rs, font: "sans" });
+    return { sym, lab, at: o.at + 0.15 + i * every };
+  });
+  return (t) => {
+    const k = t - o.at;
+    box.style.display = k < 0 ? "none" : "";
+    // 도곽이 위에서 아래로 펼쳐진다
+    box.style.clipPath = k < 0 ? "" : `inset(0 0 ${((1 - ease.outCubic(clamp(k / 0.2))) * 100).toFixed(1)}% 0)`;
+    if (logo) {
+      logo.style.display = k < 0.1 ? "none" : "";
+      if (k >= 0.1) logo.style.transform = `scale(${spring(k - 0.1, { from: 0.6, to: 1, stiffness: 260, damping: 15 }).toFixed(4)})`;
+    }
+    title?.(t);
+    sub?.(t);
+    for (const row of rows) {
+      row.sym.style.display = t >= row.at ? "" : "none";
+      row.lab(t);
+    }
+  };
+}
+
+/**
+ * 드롭 — 고개(origin)에서 충격 고리 셋이 땅을 따라 굽어 번지고, 사방 가장자리에서 trails 개의 길이 한꺼번에 그 고개로 모인다.
+ * 흔들림·한 번 튐을 돌려준다(shake 는 지도 틀에, punch 는 주인공에)
+ */
+export function mapBurst(el: HTMLElement, o: { ctx: SceneCtx; drop?: number; origin?: [number, number]; trails?: number; seed?: string | 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 { g, clear } = canvasIn(el, { x: 0, y: 0, w: W, h: H });
+  const seed = o.seed ?? `${ctx.id}:burst`;
+  const accent = col(ctx, "accent");
+  const paper = col(ctx, "paper");
+  const far = Math.hypot(Math.max(ox, W - ox), Math.max(oy, H - oy));
+  const N = 90;
+  const wob = Array.from({ length: N }, (_, i) => 0.09 * noise1(seed, (i / N) * 6));
+  // 가장자리 출발점에서 고개까지 — 땅을 따라 조금씩 굽는다
+  const trails = Array.from({ length: o.trails ?? 0 }, (_, i) => {
+    const a = (i / (o.trails ?? 1)) * Math.PI * 2 + rand(seed, i) * 0.05;
+    const R = far * (0.95 + 0.3 * rand(seed, i + 500));
+    const sx = clamp(ox + Math.cos(a) * R, 40, W - 40);
+    const sy = clamp(oy + Math.sin(a) * R, 40, H - 40);
+    const bend = (rand(seed, i + 900) - 0.5) * 0.5;
+    const mx = (sx + ox) / 2 - (sy - oy) * bend;
+    const my = (sy + oy) / 2 + (sx - ox) * bend;
+    return { pts: Array.from({ length: 25 }, (_, k) => {
+      const s = k / 24;
+      return [(1 - s) ** 2 * sx + 2 * (1 - s) * s * mx + s * s * ox, (1 - s) ** 2 * sy + 2 * (1 - s) * s * my + s * s * oy] as Pt;
+    }), delay: rand(seed, i + 300) * 0.45 };
+  });
+  const at = ctx.beats.drop(o.drop ?? 0);
+  return (t) => {
+    const s = dropBurst(t, { beats: ctx.beats, drop: o.drop ?? 0, rules: ctx.style.motion, scene: ctx.id, source: "mapBurst" });
+    clear();
+    const k = t - at;
+    if (k < 0) return s;
+    g.lineCap = "round";
+    if (trails.length) {
+      g.strokeStyle = mix(accent, 0.45);
+      g.lineWidth = 1.6;
+      g.beginPath();
+      for (const tr of trails) {
+        const p = ease.outCubic(clamp((k - tr.delay) / 0.45));
+        if (p <= 0) continue;
+        const pts = partial(tr.pts, p);
+        g.moveTo(pts[0][0], pts[0][1]);
+        for (const q of pts.slice(1)) g.lineTo(q[0], q[1]);
+      }
+      g.stroke();
+    }
+    for (let j = 0; j < 3; j++) {
+      const p = clamp((k - j * 0.09) / 0.7);
+      if (p <= 0 || p >= 1) continue;
+      const r = ease.outCubic(p) * far * 1.05;
+      g.strokeStyle = accent;
+      g.lineWidth = 7 * (1 - p) + 1;
+      g.globalAlpha = 1 - p;
+      g.beginPath();
+      for (let i = 0; i <= N; i++) {
+        const a = (i / N) * Math.PI * 2;
+        const rr = r * (1 + wob[i % N]);
+        const x = ox + Math.cos(a) * rr;
+        const y = oy + Math.sin(a) * rr;
+        if (i) g.lineTo(x, y);
+        else g.moveTo(x, y);
+      }
+      g.stroke();
+      g.globalAlpha = 1;
+    }
+    // 측량 십자 — 드롭 순간 고개를 짚는다
+    if (k < 0.6) {
+      const a = 1 - k / 0.6;
+      g.globalAlpha = a;
+      g.strokeStyle = paper;
+      g.lineWidth = 9;
+      g.beginPath();
+      g.moveTo(ox - 70, oy);
+      g.lineTo(ox + 70, oy);
+      g.moveTo(ox, oy - 70);
+      g.lineTo(ox, oy + 70);
+      g.stroke();
+      g.strokeStyle = accent;
+      g.lineWidth = 4;
+      g.stroke();
+      g.globalAlpha = 1;
+    }
+    return s;
+  };
+}