kasaframe 0.1.1 → 0.1.4

package/themes/subway-map/effects.ts

@@ -0,0 +1,662 @@
+import { clamp, ease, scaleOf, spring, type SceneCtx } from "@kasaframe/core";
+import { dropBurst, type DropBurstState } from "@kasaframe/motion";
+
+// 노선도는 벽에 붙은 지도다 — 바탕은 꼼짝 않고, 움직이는 것은 그어지는 노선 끝·서는 역·달리는 열차(요청)뿐.
+// 그림은 전부 SVG: 노선을 길이만큼 그었다 지웠다 해도 선이 뭉개지지 않고, 화면 전체 캔버스를 장면마다 잡지 않는다
+
+type Pt = readonly [number, number];
+
+const NS = "http://www.w3.org/2000/svg";
+
+// 변주가 route 칸을 안 줬으면 기본 칸을 돌려 쓴다 — 노선마다 색이 달라야 노선도가 읽힌다
+const ROUTE_FALLBACK = ["accent", "warning", "danger", "success", "inkSoft", "dim", "accentText", "ink", "line"];
+
+function paint(ctx: SceneCtx, key: string): string {
+  const c = ctx.style.colors;
+  if (c[key]) return c[key];
+  const m = /^route(\d+)$/.exec(key);
+  if (m) return c[ROUTE_FALLBACK[(Number(m[1]) - 1) % ROUTE_FALLBACK.length]] ?? c.accent;
+  return key;
+}
+
+function svgLayer(el: HTMLElement, ctx: SceneCtx): SVGSVGElement {
+  const { width: W, height: H } = ctx.meta;
+  const s = document.createElementNS(NS, "svg");
+  s.setAttribute("viewBox", `0 0 ${W} ${H}`);
+  s.setAttribute("width", String(W));
+  s.setAttribute("height", String(H));
+  s.style.cssText = "position:absolute;left:0;top:0;overflow:visible;pointer-events:none";
+  el.append(s);
+  return s;
+}
+
+function shape<K extends keyof SVGElementTagNameMap>(parent: Element, tag: K, attrs: Record<string, string | number>): SVGElementTagNameMap[K] {
+  const n = document.createElementNS(NS, tag);
+  for (const [k, v] of Object.entries(attrs)) n.setAttribute(k, String(v));
+  parent.append(n);
+  return n;
+}
+
+function html(parent: HTMLElement, css: string, text = ""): HTMLDivElement {
+  const d = document.createElement("div");
+  d.style.cssText = `position:absolute;pointer-events:none;${css}`;
+  d.textContent = text;
+  parent.append(d);
+  return d;
+}
+
+// 노선 표지 글 — 흰 글이 3:1 에 못 미치는 밝은 노선(하늘·주황)이면 먹 글
+function onRoute(ctx: SceneCtx, color: string): string {
+  const m = /^#?([0-9a-f]{6})$/i.exec(color);
+  if (!m) return paint(ctx, "onAccent");
+  const lin = [0, 2, 4].map((i) => {
+    const v = parseInt(m[1].slice(i, i + 2), 16) / 255;
+    return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+  });
+  const lum = 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2];
+  return 1.05 / (lum + 0.05) >= 3.2 ? "#FFFFFF" : paint(ctx, "ink");
+}
+
+const show = (n: Element, on: boolean) => ((n as SVGElement | HTMLElement).style.visibility = on ? "visible" : "hidden");
+
+// ── 노선 기하 ─────────────────────────────────────────────────────────────
+// 꼭짓점은 사람이 0°·45°·90° 로 찍고, 꺾이는 곳만 짧은 반지름으로 둥글린다(벡·Mini Metro). 길이 표를 같이 들고 있어
+// 노선을 길이 p 까지 긋는 것과 열차를 길이 s 자리에 두는 것이 같은 자를 쓴다
+
+interface Route {
+  pts: [number, number][];
+  at: number[];
+  total: number;
+  d: string;
+}
+
+function route(points: readonly Pt[], radius: number, closed = false): Route {
+  const v = closed ? [mid(points[0], points[1]), ...points.slice(1), points[0], mid(points[0], points[1])] : [...points];
+  const pts: [number, number][] = [[v[0][0], v[0][1]]];
+  let d = `M${v[0][0]} ${v[0][1]}`;
+  for (let i = 1; i < v.length - 1; i++) {
+    const [a, b, c] = [v[i - 1], v[i], v[i + 1]];
+    const l1 = Math.hypot(b[0] - a[0], b[1] - a[1]);
+    const l2 = Math.hypot(c[0] - b[0], c[1] - b[1]);
+    const r = Math.min(radius, l1 / 2, l2 / 2);
+    const p1: Pt = [b[0] - ((b[0] - a[0]) / (l1 || 1)) * r, b[1] - ((b[1] - a[1]) / (l1 || 1)) * r];
+    const p2: Pt = [b[0] + ((c[0] - b[0]) / (l2 || 1)) * r, b[1] + ((c[1] - b[1]) / (l2 || 1)) * r];
+    pts.push([p1[0], p1[1]]);
+    for (let k = 1; k <= 6; k++) {
+      const u = k / 6;
+      pts.push([(1 - u) ** 2 * p1[0] + 2 * (1 - u) * u * b[0] + u * u * p2[0], (1 - u) ** 2 * p1[1] + 2 * (1 - u) * u * b[1] + u * u * p2[1]]);
+    }
+    d += ` L${p1[0].toFixed(1)} ${p1[1].toFixed(1)} Q${b[0]} ${b[1]} ${p2[0].toFixed(1)} ${p2[1].toFixed(1)}`;
+  }
+  const last = v[v.length - 1];
+  pts.push([last[0], last[1]]);
+  d += ` L${last[0]} ${last[1]}`;
+  const at = [0];
+  for (let i = 1; i < pts.length; i++) at.push(at[i - 1] + Math.hypot(pts[i][0] - pts[i - 1][0], pts[i][1] - pts[i - 1][1]));
+  return { pts, at, total: at[at.length - 1], d };
+}
+
+function mid(a: Pt, b: Pt): Pt {
+  return [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2];
+}
+
+/** 길이 s 자리와 그 자리 진행 방향(도) */
+function pointAt(r: Route, s: number): [number, number, number] {
+  const x = clamp(s, 0, r.total);
+  let lo = 0;
+  let hi = r.at.length - 1;
+  while (hi - lo > 1) {
+    const m = (lo + hi) >> 1;
+    if (r.at[m] <= x) lo = m;
+    else hi = m;
+  }
+  const seg = r.at[hi] - r.at[lo] || 1;
+  const k = (x - r.at[lo]) / seg;
+  const [a, b] = [r.pts[lo], r.pts[hi]];
+  return [a[0] + (b[0] - a[0]) * k, a[1] + (b[1] - a[1]) * k, (Math.atan2(b[1] - a[1], b[0] - a[0]) * 180) / Math.PI];
+}
+
+/** 노선 위(또는 가까이) 점이 노선 길이로 어디쯤인가 */
+function lengthOf(r: Route, p: Pt): number {
+  let best = Infinity;
+  let at = 0;
+  for (let i = 1; i < r.pts.length; i++) {
+    const [a, b] = [r.pts[i - 1], r.pts[i]];
+    const dx = b[0] - a[0];
+    const dy = b[1] - a[1];
+    const len2 = dx * dx + dy * dy || 1;
+    const k = clamp(((p[0] - a[0]) * dx + (p[1] - a[1]) * dy) / len2);
+    const dist = Math.hypot(a[0] + dx * k - p[0], a[1] + dy * k - p[1]);
+    if (dist < best) {
+      best = dist;
+      at = r.at[i - 1] + (r.at[i] - r.at[i - 1]) * k;
+    }
+  }
+  return at;
+}
+
+/** 노선을 길이 비율 p 만큼 그어 둔 path — pathLength 를 내 자로 맞춰 dash 와 열차 자리가 어긋나지 않게 */
+function strokePath(parent: Element, r: Route, o: { color: string; width: number; cap?: "round" | "butt" }): (p: number) => void {
+  const path = shape(parent, "path", {
+    d: r.d,
+    fill: "none",
+    stroke: o.color,
+    "stroke-width": o.width,
+    "stroke-linecap": o.cap ?? "round",
+    "stroke-linejoin": "round",
+    pathLength: r.total.toFixed(2),
+  });
+  return (p) => {
+    show(path, p > 0);
+    path.setAttribute("stroke-dasharray", `${(clamp(p) * r.total).toFixed(2)} ${(r.total + 10).toFixed(2)}`);
+  };
+}
+
+// 손으로 끄는 선 — 그어지는 끝이 처음부터 끝까지 보이게 고른 몫을 섞는다
+const drawEase = (k: number): number => 0.35 * k + 0.65 * ease.inOutCubic(k);
+
+/** drawEase 를 거꾸로 — 그어지는 끝이 길이 비율 p 를 지나는 진행도(역이 그때 선다) */
+function drawReach(p: number): number {
+  let lo = 0;
+  let hi = 1;
+  for (let j = 0; j < 18; j++) {
+    const m = (lo + hi) / 2;
+    if (drawEase(m) < p) lo = m;
+    else hi = m;
+  }
+  return lo;
+}
+
+/** 역에 서는 톡 — 0 에서 넘쳤다 앉는 배율 */
+const popScale = (t: number, at: number): number => (t < at ? 0 : spring(t - at, { from: 0, to: 1, stiffness: 520, damping: 17 }));
+
+// ── 효과 ─────────────────────────────────────────────────────────────
+
+/**
+ * 지도 종이 — 바탕 색 한 장. 꼼짝 않는다(움직임은 노선·역·열차가 진다).
+ * river 는 내용에 경계가 있을 때만(두 형식·두 지역처럼 노선이 건너는 것) — 45° 로 꺾인 물 띠 하나
+ */
+export function paperMap(el: HTMLElement, o: { ctx: SceneCtx; river?: readonly Pt[]; width?: number }): (t: number) => void {
+  const { ctx } = o;
+  const { width: W, height: H } = ctx.meta;
+  const u = scaleOf(ctx.meta);
+  const s = svgLayer(el, ctx);
+  shape(s, "rect", { x: -40, y: -40, width: W + 80, height: H + 80, fill: paint(ctx, "bg") });
+  if (o.river) shape(s, "path", { d: route(o.river, 120 * u).d, fill: "none", stroke: paint(ctx, "water"), "stroke-width": o.width ?? 90 * u, "stroke-linejoin": "round" });
+  return () => {};
+}
+
+export interface RouteDrawOpts {
+  ctx: SceneCtx;
+  /** 꼭짓점 — 0°·45°·90° 로만 꺾이게 찍는다 */
+  points: readonly Pt[];
+  /** style.colors 키(route1–9·accent·ink …)나 색 */
+  color?: string;
+  at?: number;
+  dur?: number;
+  width?: number;
+  radius?: number;
+  closed?: boolean;
+  /** bar 면 다 그은 뒤 양 끝에 종점 막대(Mini Metro) */
+  ends?: "round" | "bar";
+}
+
+/** 노선 긋기 — 꼭짓점을 따라 0°·45°·90° 로 꺾이며 그어진다. 꺾이는 곳은 짧게 둥글고, 다 그으면 종점 막대가 선다 */
+export function routeDraw(el: HTMLElement, o: RouteDrawOpts): (t: number) => void {
+  const { ctx } = o;
+  const u = scaleOf(ctx.meta);
+  const width = o.width ?? 16 * u;
+  const r = route(o.points, o.radius ?? 34 * u, o.closed);
+  const s = svgLayer(el, ctx);
+  const color = paint(ctx, o.color ?? "accent");
+  const draw = strokePath(s, r, { color, width, cap: o.ends === "bar" ? "butt" : "round" });
+  const bars = o.ends === "bar" && !o.closed ? [0, r.total].map((at) => {
+    const [x, y, a] = pointAt(r, at === 0 ? 0.5 : at - 0.5);
+    return shape(s, "rect", { x: -width * 0.5, y: -width * 1.3, width, height: width * 2.6, fill: color, transform: `translate(${x} ${y}) rotate(${a})` });
+  }) : [];
+  const at = o.at ?? 0;
+  const dur = o.dur ?? 0.4;
+  return (t) => {
+    const p = t < at ? 0 : drawEase(clamp((t - at) / dur));
+    draw(p);
+    for (const b of bars) show(b, p >= 1);
+  };
+}
+
+export interface StationOpts {
+  ctx: SceneCtx;
+  x: number;
+  y: number;
+  at: number;
+  /** stop 역 점 · hub 환승 캡슐(흰 바탕 굵은 먹 테두리) · tick 노선 옆 눈금(벡) */
+  kind?: "stop" | "hub" | "tick";
+  /** 역 점 반지름 · 캡슐 두께의 반 */
+  size?: number;
+  /** hub 캡슐 길이(두께 방향 빼고) · tick 길이 */
+  length?: number;
+  /** hub·tick 이 노선을 따라 놓일 각도(도) */
+  angle?: number;
+  /** tick 색 — 그 노선 색 */
+  color?: string;
+}
+
+/** 역 찍기 — 박에 톡 서며(넘쳤다 앉는다) 둘레 고리가 한 번 퍼진다. 비넬리 「점이 없으면 서지 않는다」 */
+export function stationStop(el: HTMLElement, o: StationOpts): (t: number) => void {
+  const { ctx } = o;
+  const u = scaleOf(ctx.meta);
+  const kind = o.kind ?? "stop";
+  const size = o.size ?? (kind === "hub" ? 26 : 15) * u;
+  const s = svgLayer(el, ctx);
+  const g = shape(s, "g", {});
+  const ring = shape(s, "circle", { cx: o.x, cy: o.y, r: size, fill: "none", stroke: paint(ctx, kind === "tick" ? (o.color ?? "accent") : "ink"), "stroke-width": 4 * u });
+  if (kind === "tick") {
+    const len = o.length ?? 22 * u;
+    shape(g, "rect", { x: -4 * u, y: -len, width: 8 * u, height: len, fill: paint(ctx, o.color ?? "accent") });
+  } else {
+    const len = kind === "hub" ? (o.length ?? size * 2) : 0;
+    const stroke = (kind === "hub" ? 7 : 5) * u;
+    shape(g, "rect", { x: -len / 2 - size, y: -size, width: len + size * 2, height: size * 2, rx: size, fill: paint(ctx, "surface"), stroke: paint(ctx, "ink"), "stroke-width": stroke });
+  }
+  const at = o.at;
+  return (t) => {
+    const k = popScale(t, at);
+    show(g, k > 0);
+    g.setAttribute("transform", `translate(${o.x} ${o.y}) rotate(${o.angle ?? 0}) scale(${Math.max(0, k).toFixed(4)})`);
+    const w = clamp((t - at) / 0.45);
+    show(ring, t >= at && w < 1);
+    if (t >= at && w < 1) {
+      const e = ease.outCubic(w);
+      ring.setAttribute("r", (size * (1.1 + 1.9 * e) + (kind === "hub" ? (o.length ?? size * 2) / 2 : 0)).toFixed(2));
+      ring.setAttribute("opacity", ((1 - e) * 0.9).toFixed(3));
+    }
+  };
+}
+
+/**
+ * 역 이름 펼치기 — 역 점 쪽 글자부터 한 자씩 서고, 막 선 글자는 노선 색으로 켜졌다 먹으로 앉는다.
+ * 글꼴 크기·자리는 그대로(색만 바꾼다). at + dur 부터 el.textContent === text
+ */
+export function nameplate(el: HTMLElement, o: { ctx: SceneCtx; text: string; at: number; dur?: number; from?: "left" | "right"; color?: string }): (t: number) => void {
+  const { ctx } = o;
+  el.textContent = "";
+  const spans = Array.from(o.text).map((ch) => {
+    const sp = document.createElement("span");
+    sp.textContent = ch;
+    el.append(sp);
+    return sp;
+  });
+  const n = spans.length;
+  const dur = o.dur ?? Math.min(0.5, 0.03 * n + 0.12);
+  const lit = paint(ctx, o.color ?? "accentText");
+  const right = o.from === "right";
+  return (t) => {
+    const p = clamp((t - o.at) / Math.max(1e-3, dur));
+    const shown = t < o.at ? 0 : t >= o.at + dur ? n : Math.min(n, Math.floor(p * n) + 1);
+    spans.forEach((sp, i) => {
+      const order = right ? n - 1 - i : i;
+      sp.style.visibility = order < shown ? "visible" : "hidden";
+      // 이 글자가 선 시각 — 0.12초 동안 노선 색
+      const bornAt = o.at + (order / n) * dur;
+      sp.style.color = order < shown && t - bornAt < 0.12 && t < o.at + dur + 0.12 ? lit : "";
+    });
+  };
+}
+
+export interface TimetableOpts {
+  /** 역 자리 — 노선 길이(px)나 무엇이든 커지는 수 */
+  stops: readonly number[];
+  at?: number;
+  /** 평균 역 간 걸리는 초 — 역 사이가 멀수록 길게(역 사이 시간). 배열이면 구간마다 그대로 */
+  hop?: number | readonly number[];
+  /** 역마다 서 있는 초 */
+  dwell?: number;
+  /** pingpong 종점에서 되돌아온다 · loop 끝에서 처음으로(stops 끝에 total 을 준다) · once 끝에 선다 */
+  mode?: "pingpong" | "loop" | "once";
+  /** loop 의 한 바퀴 길이 */
+  total?: number;
+  /** 급행(캐시) — 서지 않고 같은 빠르기로 통과 */
+  express?: boolean;
+}
+
+/**
+ * 시간표 — t 에 열차가 노선 어디(s)에 있나. 역 사이는 가속·감속(inOutCubic), 역에서는 dwell 만큼 선다.
+ * 급행은 서지 않고 고르게 지난다. 같은 t 면 같은 자리
+ */
+export function timetable(t: number, o: TimetableOpts): { s: number; leg: number; dwelling: boolean; started: boolean } {
+  const stops = [...o.stops];
+  const at = o.at ?? 0;
+  if (stops.length < 2) return { s: stops[0] ?? 0, leg: 0, dwelling: true, started: t >= at };
+  const seq: [number, number][] = [];
+  for (let i = 0; i < stops.length - 1; i++) seq.push([stops[i], stops[i + 1]]);
+  if (o.mode === "loop") seq.push([stops[stops.length - 1], (o.total ?? stops[stops.length - 1]) + stops[0]]);
+  else if ((o.mode ?? "pingpong") === "pingpong") for (let i = stops.length - 1; i > 0; i--) seq.push([stops[i], stops[i - 1]]);
+  const mean = seq.reduce((a, [p, q]) => a + Math.abs(q - p), 0) / seq.length || 1;
+  const hop = o.hop ?? 0.5;
+  const legDur = seq.map(([p, q], i) => (Array.isArray(hop) ? (hop as readonly number[])[i % hop.length] : Math.max(0.25, Math.abs(q - p) / mean) * (hop as number)));
+  const dwell = o.express ? 0 : (o.dwell ?? 0.12);
+  const period = legDur.reduce((a, d) => a + d + dwell, 0);
+  if (t < at) return { s: stops[0], leg: 0, dwelling: true, started: false };
+  let tau = t - at;
+  if (o.mode === "once") {
+    if (tau >= period - dwell) return { s: stops[stops.length - 1], leg: seq.length - 1, dwelling: true, started: true };
+  } else tau %= period;
+  for (let i = 0; i < seq.length; i++) {
+    const [p, q] = seq[i];
+    if (tau < legDur[i]) {
+      const k = tau / legDur[i];
+      // 역 사이 가속·감속 — 역 앞에서도 아주 서지는 않게 고른 몫을 섞는다(서는 것은 dwell 이 맡는다)
+      const e = o.express ? k : 0.3 * k + 0.7 * ease.inOutCubic(k);
+      const s = p + (q - p) * e;
+      return { s: o.mode === "loop" && o.total ? s % o.total : s, leg: i, dwelling: false, started: true };
+    }
+    tau -= legDur[i];
+    if (tau < dwell) return { s: o.mode === "loop" && o.total ? q % o.total : q, leg: i, dwelling: true, started: true };
+    tau -= dwell;
+  }
+  return { s: stops[0], leg: 0, dwelling: true, started: true };
+}
+
+export interface TrainOpts {
+  ctx: SceneCtx;
+  points: readonly Pt[];
+  closed?: boolean;
+  radius?: number;
+  /** 역 자리(노선 위 점). 없으면 두 종점만 */
+  stops?: readonly Pt[];
+  color?: string;
+  at?: number;
+  /** 몇 대가 headway 초 간격으로 */
+  count?: number;
+  headway?: number;
+  hop?: number | readonly number[];
+  dwell?: number;
+  mode?: "pingpong" | "loop" | "once";
+  /** 급행(캐시) — 서지 않고 통과 */
+  express?: boolean;
+  /** 폴백 = 환승 — 이 역을 지나면 열차가 다른 노선 색으로 갈아탄다 */
+  transfer?: { at: Pt; color: string };
+  /** 열차 길이(px) */
+  size?: number;
+  /** 이 시각에 내린다(다른 열차 무리에 노선을 넘길 때) */
+  until?: number;
+}
+
+/**
+ * 열차 = 요청 — 노선을 따라 역마다 서며(가속·감속) 달린다. 몸통은 먹, 칸 셋은 실은 토큰으로 노선 색이 켜져 있다
+ * (몸통까지 노선 색이면 제 노선 위에서 묻혀 달리는 게 안 보인다 — 흰 역 캡슐과도 갈린다).
+ * 여러 대가 간격을 두고 달려 화면이 쉬지 않는다. express 는 급행(캐시 적중), transfer 는 환승(폴백)해 칸 색이 바뀐다, until 에 내린다
+ */
+export function trainRun(el: HTMLElement, o: TrainOpts): (t: number) => void {
+  const { ctx } = o;
+  const u = scaleOf(ctx.meta);
+  const r = route(o.points, o.radius ?? 34 * u, o.closed);
+  const stops = o.stops?.length ? o.stops.map((p) => lengthOf(r, p)).sort((a, b) => a - b) : [0, r.total];
+  const mode = o.mode ?? (o.closed ? "loop" : "pingpong");
+  const swap = o.transfer ? lengthOf(r, o.transfer.at) : Infinity;
+  const colorA = paint(ctx, o.color ?? "accent");
+  const colorB = o.transfer ? paint(ctx, o.transfer.color) : colorA;
+  const L = o.size ?? 72 * u;
+  const Hh = Math.min(30 * u, L * 0.5);
+  const s = svgLayer(el, ctx);
+  const trains = Array.from({ length: o.count ?? 1 }, () => {
+    const g = shape(s, "g", {});
+    shape(g, "rect", { x: -L / 2, y: -Hh / 2, width: L, height: Hh, rx: 7 * u, fill: paint(ctx, "ink"), stroke: paint(ctx, "surface"), "stroke-width": 3 * u });
+    const cars = shape(g, "g", { fill: colorA });
+    for (let k = 0; k < 3; k++) shape(cars, "rect", { x: -L / 2 + L * (0.12 + k * 0.28), y: -Hh * 0.24, width: L * 0.2, height: Hh * 0.48, rx: 2 * u });
+    return { g, cars };
+  });
+  const at = o.at ?? 0;
+  const until = o.until ?? Infinity;
+  const headway = o.headway ?? 0.6;
+  return (t) => {
+    trains.forEach(({ g, cars }, i) => {
+      const tt = timetable(t, { stops, at: at + i * headway, hop: o.hop, dwell: o.dwell, mode, total: r.total, express: o.express });
+      show(g, tt.started && t < until);
+      if (!tt.started) return;
+      const [x, y, a] = pointAt(r, tt.s);
+      g.setAttribute("transform", `translate(${x.toFixed(2)} ${y.toFixed(2)}) rotate(${a.toFixed(2)})`);
+      cars.setAttribute("fill", tt.s >= swap ? colorB : colorA);
+    });
+  };
+}
+
+export interface LegTimeOpts {
+  ctx: SceneCtx;
+  from: Pt;
+  to: Pt;
+  at: number;
+  /** 이 구간을 지나는 데 걸린 초 — 실측이면 그 값 그대로 */
+  dur: number;
+  value: number;
+  decimals?: number;
+  unit?: string;
+  color?: string;
+  side?: "above" | "below";
+  /** 노선에서 떨어진 거리(px) */
+  offset?: number;
+  /** 시간 딱지 글자 크기 */
+  size?: number;
+}
+
+/**
+ * 지연 = 역 사이 시간 — 두 역 사이에 분(分) 점이 한 알씩 차오르고, 가운데 시간 딱지가 0 에서 값까지 센다.
+ * 열차가 그 구간을 지나는 시간과 같은 dur 로 걸면 점이 열차를 따라 찬다
+ */
+export function legTime(el: HTMLElement, o: LegTimeOpts): (t: number) => void {
+  const { ctx } = o;
+  const u = scaleOf(ctx.meta);
+  const dx = o.to[0] - o.from[0];
+  const dy = o.to[1] - o.from[1];
+  const len = Math.hypot(dx, dy) || 1;
+  const sign = o.side === "above" ? -1 : 1;
+  const off = (o.offset ?? 44 * u) * sign;
+  const nx = (-dy / len) * off;
+  const ny = (dx / len) * off;
+  const n = Math.round(clamp(len / (26 * u), 4, 48));
+  const s = svgLayer(el, ctx);
+  const color = paint(ctx, o.color ?? "accent");
+  const pale = paint(ctx, "line");
+  const pips = Array.from({ length: n }, (_, i) => {
+    const k = (i + 0.5) / n;
+    return shape(s, "circle", { cx: o.from[0] + dx * k + nx, cy: o.from[1] + dy * k + ny, r: 5 * u, fill: pale });
+  });
+  const size = o.size ?? 40 * u;
+  const tag = html(el, `left:${o.from[0] + dx / 2 + nx * 2.1}px;top:${o.from[1] + dy / 2 + ny * 2.1}px;transform:translate(-50%,-50%);padding:${0.18 * size}px ${0.5 * size}px ${0.1 * size}px;border:${4 * u}px solid ${paint(ctx, "ink")};border-radius:999px;background:${paint(ctx, "surface")};color:${paint(ctx, "ink")};font:700 ${size}px/1 ${ctx.style.fonts.mono};white-space:pre;visibility:hidden`);
+  const dec = o.decimals ?? 0;
+  const unit = o.unit ?? "";
+  return (t) => {
+    const p = clamp((t - o.at) / Math.max(1e-3, o.dur));
+    pips.forEach((c, i) => c.setAttribute("fill", t >= o.at && (i + 0.5) / n <= p ? color : pale));
+    show(tag, t >= o.at);
+    tag.textContent = `${(p >= 1 ? o.value : o.value * p).toFixed(dec)}${unit}`;
+    const k = popScale(t, o.at);
+    tag.style.transform = `translate(-50%,-50%) scale(${Math.max(0, k).toFixed(4)})`;
+  };
+}
+
+export interface HourLoopOpts {
+  ctx: SceneCtx;
+  cx: number;
+  cy: number;
+  w: number;
+  h: number;
+  at?: number;
+  dur?: number;
+  /** 다른 운임이 붙는 시간대 [시작 시, 끝 시) — 00–10 이면 [0, 10] */
+  window?: [number, number];
+  windowAt?: number;
+  color?: string;
+  windowColor?: string;
+  /** 시각 딱지를 달 시(0–23) */
+  labels?: readonly number[];
+  /** 하루를 도는 급행 열차 수 */
+  trains?: number;
+}
+
+/**
+ * 하루 = 순환선 — 24 시를 역 스물넷으로 둔 순환선(45° 로 모를 깎은 팔각). 위 가운데가 00 시, 시계 방향.
+ * 노선이 한 바퀴 그어지며 역이 서고, windowAt 에 한 구간(00–10)이 다른 운임 색으로 덧칠되고, 열차가 늘 돈다
+ */
+export function hourLoop(el: HTMLElement, o: HourLoopOpts): (t: number) => void {
+  const { ctx } = o;
+  const u = scaleOf(ctx.meta);
+  const c = Math.min(o.w, o.h) * 0.29;
+  const [l, r, tp, b] = [o.cx - o.w / 2, o.cx + o.w / 2, o.cy - o.h / 2, o.cy + o.h / 2];
+  const corners: Pt[] = [[l + c, tp], [r - c, tp], [r, tp + c], [r, b - c], [r - c, b], [l + c, b], [l, b - c], [l, tp + c]];
+  const loop = route(corners, 60 * u, true);
+  const at = o.at ?? 0;
+  const dur = o.dur ?? 0.6;
+  const s = svgLayer(el, ctx);
+  // 하루 전체는 회색 노선(정가), 할인 시간대만 운임 색
+  const drawBase = strokePath(s, loop, { color: paint(ctx, o.color ?? "dim"), width: 16 * u });
+  const win = o.window ?? [0, 10];
+  const winPath = route(
+    Array.from({ length: 25 }, (_, i) => {
+      const [x, y] = pointAt(loop, (loop.total * (win[0] + ((win[1] - win[0]) * i) / 24)) / 24);
+      return [x, y] as Pt;
+    }),
+    1,
+  );
+  const drawWin = strokePath(s, winPath, { color: paint(ctx, o.windowColor ?? "accent"), width: 26 * u });
+  const hours = Array.from({ length: 24 }, (_, hh) => {
+    const [x, y, a] = pointAt(loop, (loop.total * hh) / 24);
+    const big = hh % 6 === 0;
+    const dot = shape(s, "circle", { cx: x, cy: y, r: (big ? 15 : 9) * u, fill: paint(ctx, "surface"), stroke: paint(ctx, "ink"), "stroke-width": (big ? 5 : 4) * u });
+    return { dot, x, y, a, hh, born: at + dur * drawReach(hh / 24) };
+  });
+  const labels = (o.labels ?? [0, 6, 12, 18]).map((hh) => {
+    const { x, y, a } = hours[hh % 24];
+    // 노선 바깥쪽(진행 방향 왼쪽 = 시계 방향 순환선의 바깥)
+    const rad = ((a - 90) * Math.PI) / 180;
+    const d = 62 * u;
+    const lab = html(el, `left:${x + Math.cos(rad) * d}px;top:${y + Math.sin(rad) * d}px;transform:translate(-50%,-50%);font:700 ${44 * u}px/1 ${ctx.style.fonts.mono};color:${paint(ctx, "ink")};white-space:pre;visibility:hidden`, String(hh).padStart(2, "0"));
+    return { lab, born: hours[hh % 24].born };
+  });
+  const run = trainRun(el, { ctx, points: corners, closed: true, radius: 60 * u, color: o.windowColor ?? "accent", at: at + dur, count: o.trains ?? 5, headway: 0.35, hop: 0.12, express: true, stops: hours.map((q) => [q.x, q.y] as Pt) });
+  const wAt = o.windowAt ?? at + dur;
+  return (t) => {
+    drawBase(t < at ? 0 : drawEase(clamp((t - at) / dur)));
+    drawWin(t < wAt ? 0 : ease.outCubic(clamp((t - wAt) / 0.45)));
+    for (const q of hours) {
+      const k = popScale(t, q.born);
+      show(q.dot, k > 0);
+      q.dot.setAttribute("transform", `translate(${q.x} ${q.y}) scale(${Math.max(0, k).toFixed(4)}) translate(${-q.x} ${-q.y})`);
+    }
+    for (const q of labels) show(q.lab, t >= q.born);
+    run(t);
+  };
+}
+
+export interface TallyOpts {
+  ctx: SceneCtx;
+  /** 노선 표지 왼쪽 끝 · 노선 높이(가운데) */
+  x: number;
+  y: number;
+  /** max 일 때 노선 길이(px) */
+  length: number;
+  count: number;
+  max: number;
+  color: string;
+  at: number;
+  dur?: number;
+  /** 노선 표지 안 글(호선 번호) */
+  bullet?: string;
+  name?: string;
+  /** 이름 칸 폭(px) */
+  nameWidth?: number;
+  size?: number;
+  /** 다 그은 뒤(수를 주면 그 시각부터) 급행 열차가 오간다 */
+  train?: boolean | number;
+}
+
+/**
+ * 노선으로 세기 — 노선 표지·이름 옆으로 노선이 그어지며 역이 하나씩 서고, 끝의 수가 선 역 수만큼 센다.
+ * 노선 길이 = 수, 역 = 하나(모델 하나). 다 그은 뒤엔 급행 열차가 오간다
+ */
+export function routeTally(el: HTMLElement, o: TallyOpts): (t: number) => void {
+  const { ctx } = o;
+  const u = scaleOf(ctx.meta);
+  const size = o.size ?? 44 * u;
+  const R = size * 0.62;
+  const color = paint(ctx, o.color);
+  const bullet = html(el, `left:${o.x}px;top:${o.y - R}px;width:${R * 2}px;height:${R * 2}px;border-radius:50%;background:${color};color:${onRoute(ctx, color)};font:800 ${size * 0.8}px/${R * 2}px ${ctx.style.fonts.display};text-align:center;visibility:hidden`, o.bullet ?? "");
+  const name = o.name ? html(el, `left:${o.x + R * 2 + 18 * u}px;top:${o.y}px;transform:translateY(-50%);font:800 ${size}px/1.1 ${ctx.style.fonts.sans};color:${paint(ctx, "ink")};white-space:pre`, "") : null;
+  const writeName = name ? nameplate(name, { ctx, text: o.name!, at: o.at, dur: 0.25 }) : null;
+  const x0 = o.x + R * 2 + 18 * u + (o.nameWidth ?? 280 * u);
+  const span = (o.length * o.count) / o.max;
+  const step = span / o.count;
+  const points: Pt[] = [[x0, o.y], [x0 + span, o.y]];
+  const dur = o.dur ?? 0.3 + 0.35 * (o.count / o.max);
+  const line = routeDraw(el, { ctx, points, color: o.color, at: o.at, dur, width: 14 * u });
+  const s = svgLayer(el, ctx);
+  const dots = Array.from({ length: o.count }, (_, i) => {
+    const x = x0 + step * (i + 0.5);
+    return { c: shape(s, "circle", { cx: x, cy: o.y, r: Math.min(8 * u, step * 0.32), fill: paint(ctx, "surface"), stroke: paint(ctx, "ink"), "stroke-width": 3 * u }), born: o.at + drawReach((i + 0.5) / o.count) * dur };
+  });
+  const num = html(el, `left:${x0 + span + 22 * u}px;top:${o.y}px;transform:translateY(-50%);font:800 ${size * 1.15}px/1 ${ctx.style.fonts.mono};color:${paint(ctx, "ink")};white-space:pre;visibility:hidden`, "");
+  const run = o.train !== undefined && o.train !== false ? trainRun(el, { ctx, points, color: o.color, at: typeof o.train === "number" ? o.train : o.at + dur, express: true, hop: 0.35 + 0.5 * (o.count / o.max), size: Math.min(72 * u, Math.max(36 * u, span * 0.5)) }) : null;
+  return (t) => {
+    show(bullet, t >= o.at);
+    const k = popScale(t, o.at);
+    bullet.style.transform = `scale(${Math.max(0, k).toFixed(4)})`;
+    writeName?.(t);
+    line(t);
+    let n = 0;
+    for (const d of dots) {
+      const on = t >= d.born;
+      if (on) n++;
+      show(d.c, on);
+    }
+    show(num, n > 0);
+    num.textContent = String(n);
+    run?.(t);
+  };
+}
+
+export interface HubDropOpts {
+  ctx: SceneCtx;
+  drop?: number;
+  x?: number;
+  y?: number;
+  /** 사방으로 뻗는 노선 — 색과 각도(도, 0 = 오른쪽). 없으면 45° 마다 route1–8 */
+  spokes?: readonly { color: string; angle: number }[];
+  /** 가운데 환승역 반지름 */
+  size?: number;
+}
+
+/**
+ * 드롭 — 모든 노선이 한 환승역에서 사방으로 한꺼번에 뻗고, 환승역 둘레로 신호 고리가 퍼진다.
+ * 돌려준 shake 는 화면 틀에, punch 는 주인공에
+ */
+export function hubDrop(el: HTMLElement, o: HubDropOpts): (t: number) => DropBurstState {
+  const { ctx } = o;
+  const u = scaleOf(ctx.meta);
+  const { width: W, height: H } = ctx.meta;
+  const x = o.x ?? W / 2;
+  const y = o.y ?? H / 2;
+  const size = o.size ?? 90 * u;
+  const far = Math.hypot(W, H);
+  const spokes = o.spokes ?? Array.from({ length: 8 }, (_, i) => ({ color: `route${i + 1}`, angle: i * 45 }));
+  const s = svgLayer(el, ctx);
+  const lines = spokes.map((sp, i) => {
+    const a = (sp.angle * Math.PI) / 180;
+    const r = route([[x, y], [x + Math.cos(a) * far, y + Math.sin(a) * far]], 1);
+    return { draw: strokePath(s, r, { color: paint(ctx, sp.color), width: 22 * u, cap: "butt" }), delay: (i % 3) * 0.04 };
+  });
+  const wave = shape(s, "circle", { cx: x, cy: y, r: size, fill: "none", stroke: paint(ctx, "accent"), "stroke-width": 18 * u });
+  const hub = shape(s, "circle", { cx: x, cy: y, r: size, fill: paint(ctx, "surface"), stroke: paint(ctx, "ink"), "stroke-width": 14 * u });
+  const flood = html(el, `inset:0;background:${paint(ctx, "accent")};opacity:0`);
+  const D = ctx.beats.drop(o.drop ?? 0);
+  return (t) => {
+    const st = dropBurst(t, { beats: ctx.beats, drop: o.drop ?? 0, rules: ctx.style.motion, scene: ctx.id, source: "hubDrop" });
+    for (const l of lines) l.draw(t < D + l.delay ? 0 : ease.outCubic(clamp((t - D - l.delay) / 0.32)));
+    const k = popScale(t, D);
+    show(hub, k > 0);
+    hub.setAttribute("r", (size * Math.max(0, k)).toFixed(2));
+    show(wave, st.ring.opacity > 0.01);
+    wave.setAttribute("r", (size * (1 + st.ring.scale)).toFixed(2));
+    wave.setAttribute("opacity", st.ring.opacity.toFixed(3));
+    flood.style.opacity = (st.flash * 0.55).toFixed(3);
+    return st;
+  };
+}

package/themes/subway-map/sample/assets/og/logo.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1140 650" width="1140" height="650" fill="none" role="img" aria-label="OpenGateway">
+  <title>OpenGateway</title>
+  <g id="logo" stroke="currentColor" fill="currentColor">
+    <rect id="node-in" x="36" y="36" width="420" height="578" rx="89" fill="none" stroke-width="72"/>
+    <rect id="bar-in" x="72" y="272" width="277" height="106" stroke="none"/>
+    <path id="node-out" d="M684 213 L684 125 A89 89 0 0 1 773 36 L1015 36 A89 89 0 0 1 1104 125 L1104 525 A89 89 0 0 1 1015 614 L773 614 A89 89 0 0 1 684 525 L684 436" fill="none" stroke-width="72" stroke-linecap="butt"/>
+    <g id="arrow">
+      <rect id="arrow-shaft" x="420" y="272" width="394" height="106" stroke="none"/>
+      <path id="arrow-head" d="M833 220 L970 325 L833 430 Z" stroke-width="38" stroke-linejoin="round"/>
+    </g>
+  </g>
+</svg>