kasaframe 0.0.0-stage → 0.1.1

package/templates/shorts/template.json

@@ -0,0 +1,127 @@
+{
+  "id": "shorts",
+  "label": "쇼츠",
+  "summary": "세로 쇼츠 — 첫 1.5초에 결과, 화면 글은 전문 낱말만, 말은 자막 트랙으로, 끝이 처음으로 이어진다",
+  "aspect": "9:16",
+  "width": 1080,
+  "height": 1920,
+  "fps": 60,
+  "duration": {
+    "min": 15,
+    "max": 60,
+    "default": 45
+  },
+  "music": "optional",
+  "captions": "off",
+  "loop": true,
+  "style": "og",
+  "safeArea": {
+    "top": 230,
+    "bottom": 460,
+    "left": 40,
+    "right": 40
+  },
+  "text": {
+    "policy": "terms-only",
+    "maxOnScreen": 3,
+    "minPx": 48
+  },
+  "motion": {
+    "beatPulse": "off",
+    "shake": {
+      "on": [],
+      "maxPerPhrase": 0,
+      "maxPx": 0
+    },
+    "cameraMove": "once-per-phrase",
+    "repeatSameMove": false,
+    "maxFreezeSec": 0.1,
+    "staticSec": {
+      "warn": 1.5,
+      "error": 3
+    },
+    "beatMove": "every-beat"
+  },
+  "scenes": [
+    {
+      "id": "hook",
+      "role": "hook",
+      "sec": 1.5,
+      "anchor": "start",
+      "idea": "결과 먼저 — 가장 센 숫자나 그림 하나가 첫 프레임부터 화면에 있다"
+    },
+    {
+      "id": "setup",
+      "role": "setup",
+      "weight": 2,
+      "snap": "beat",
+      "idea": "조건 하나로 문제를 재현한다 — 보는 사람이 예상하는 쪽을 먼저 보여 준다"
+    },
+    {
+      "id": "explain",
+      "role": "explain",
+      "weight": 4,
+      "snap": "beat",
+      "idea": "원리 — 큰 대상 하나를 끝까지 변신시킨다. 장면을 자르지 말고, 드러낼 때 다가가고 비교할 때 물러난다(stage.camera — 이유 없는 이동은 안 된다). 화면 글은 전문 낱말·숫자만"
+    },
+    {
+      "id": "reveal",
+      "role": "reveal",
+      "weight": 2,
+      "snap": "beat",
+      "idea": "이름 공개 — 지금까지 본 것의 이름과 숫자 하나"
+    },
+    {
+      "id": "limit",
+      "role": "limit",
+      "weight": 1,
+      "snap": "beat",
+      "idea": "남는 한계 한 가지 — 숫자나 낱말 하나로"
+    },
+    {
+      "id": "end",
+      "role": "end",
+      "sec": 2,
+      "anchor": "end",
+      "idea": "로고 — 되돌이 — 마지막으로 찍히는 프레임(lib/stage.ts 의 lastT = dur - 1/fps)에서 hook 첫 화면과 똑같아지게 움직임을 끝낸다"
+    }
+  ],
+  "assets": {
+    "need": [],
+    "want": [
+      "logo",
+      "data"
+    ],
+    "gen": [
+      "img:hook-bg"
+    ]
+  },
+  "deliverables": [
+    "mp4",
+    "cover",
+    "srt",
+    "vtt"
+  ],
+  "detect": {
+    "words": [
+      "쇼츠",
+      "숏츠",
+      "숏폼",
+      "릴스",
+      "틱톡",
+      "세로 영상",
+      "shorts",
+      "short-form",
+      "reels",
+      "tiktok"
+    ],
+    "hints": [
+      "세로",
+      "9:16",
+      "vertical",
+      "45초",
+      "30초"
+    ],
+    "aspect": "9:16"
+  }
+}

package/templates/square/template.json

@@ -0,0 +1,113 @@
+{
+  "id": "square",
+  "label": "피드",
+  "summary": "정사각 피드 — 소리 없이도 읽히게 글을 굽는다",
+  "aspect": "1:1",
+  "width": 1080,
+  "height": 1080,
+  "fps": 60,
+  "duration": {
+    "min": 15,
+    "max": 60,
+    "default": 30
+  },
+  "music": "optional",
+  "captions": "on",
+  "loop": true,
+  "style": "kawaii-pastel",
+  "safeArea": {
+    "top": 60,
+    "bottom": 60,
+    "left": 60,
+    "right": 60
+  },
+  "text": {
+    "policy": "captions",
+    "maxOnScreen": 8,
+    "minPx": 44
+  },
+  "motion": {
+    "beatPulse": "off",
+    "shake": {
+      "on": [],
+      "maxPerPhrase": 0,
+      "maxPx": 0
+    },
+    "cameraMove": "once-per-phrase",
+    "repeatSameMove": false,
+    "maxFreezeSec": 0.1,
+    "staticSec": {
+      "warn": 1.5,
+      "error": 3
+    },
+    "beatMove": "every-beat"
+  },
+  "scenes": [
+    {
+      "id": "hook",
+      "role": "hook",
+      "sec": 2,
+      "anchor": "start",
+      "idea": "첫 프레임에 무엇에 관한 영상인지 글 한 줄로 — 소리 없이도 읽힌다"
+    },
+    {
+      "id": "point1",
+      "role": "point",
+      "weight": 1,
+      "snap": "beat",
+      "idea": "요점 하나 — 굵은 글 한 줄 + 그림"
+    },
+    {
+      "id": "point2",
+      "role": "point",
+      "weight": 1,
+      "snap": "beat",
+      "idea": "요점 둘 — point1 과 다른 움직임"
+    },
+    {
+      "id": "point3",
+      "role": "point",
+      "weight": 1,
+      "snap": "beat",
+      "idea": "요점 셋"
+    },
+    {
+      "id": "end",
+      "role": "end",
+      "sec": 2,
+      "anchor": "end",
+      "idea": "이름 — 되돌이 — 마지막으로 찍히는 프레임(lastT = dur - 1/fps)에서 hook 첫 화면과 똑같아지게"
+    }
+  ],
+  "assets": {
+    "need": [],
+    "want": [
+      "logo"
+    ],
+    "gen": []
+  },
+  "deliverables": [
+    "mp4",
+    "cover"
+  ],
+  "detect": {
+    "words": [
+      "피드",
+      "정사각",
+      "정사각형",
+      "인스타 피드",
+      "1:1",
+      "square",
+      "feed post"
+    ],
+    "hints": [
+      "무음",
+      "소리 없이",
+      "자막 넣어",
+      "인스타",
+      "instagram",
+      "carousel"
+    ],
+    "aspect": "1:1"
+  }
+}

package/themes/debug-hud/THEME.md

@@ -0,0 +1,39 @@
+# 디버그 HUD `debug-hud`
+
+**비유: 화면이 계측되며 드러난다.** 검정 위에 형광 한 색. 무엇이 나타나든 먼저 잰다 — 모서리 꺾쇠가 서고, 변이 뻗고, 이름과 크기가 찍힌다. 값은 그 프레임에 실제로 잰 숫자(시각·프레임·박·마디·대역 에너지)만 화면에 오르고, 선은 오실로스코프처럼 흐른다.
+
+## 맞는 내용·용도
+
+- 측정·분석·성능·로그·파이프라인 — 숫자와 신호가 주인공인 내용. 곡 분석, 빌드·렌더 진행, 모델 지표, 계측 장비, 개발 도구.
+- 용도: 설명(explainer)·시연(demo)·홍보(promo)·쇼츠(shorts)·공개(launch). 드롭에 `dropTrigger`.
+- 화면 글은 로그 줄·측정 이름·숫자. 전부 모노(한글은 모노 뒤 Pretendard).
+
+## 금지
+
+- 형광 라임(`ink`)과 그 어두운 단(`dim`·`line`) 말고 다른 색. 면 채우기는 드롭 섬광 한 번뿐.
+- 지어낸 숫자 — 화면의 값은 그 순간 잰 것(시각·프레임·박)이나 확인된 사실(브리프·실측 데이터)만. 「99.9%」 같은 장식 숫자 금지.
+- 그림자·흐림·그라데이션·둥근 모서리. 선은 1–3px.
+- 슬로건·감성 문장.
+
+## 움직임
+
+- 쉬지 않는다: `hudFrame` 의 계측판 눈금과 `plotTrace` 선이 늘 흐르고, 과녁(`crosshair`)이 박마다 다음 값으로 뛴다.
+- 구도는 마디마다 바꾼다 — 컷마다 재는 대상이 다르다(흩어진 상자 · 막대 상자 · 주소 · 요청 로그 · 큰 숫자 · 가격선 · 로고), 들어올 때마다 `wireBox` 가 상자를 새로 잰다.
+- 움직임은 「잡고 멈춘다」(outExpo 0.18초) 한 손으로.
+
+## 효과
+
+같은 레포 안에서는 `effects.ts` 를 바로, 프로젝트에서는 `fx("debug-hud")`. layer 는 `build` 에서 만들고 `(t) => …` 에서 부른다. 캔버스는 그리는 자리만큼만 잡으므로 한 장면에 배치를 여럿 겹쳐 둬도 가볍다.
+
+| 효과 | 꼴 | 하는 일 |
+|---|---|---|
+| `readout` | value | 고정 폭 숫자(앞을 0 으로), 굴러도 폭이 안 흔들린다. NaN 은 「--」 |
+| `wireBox` | layer | 와이어 상자 — 꺾쇠 → 변 → 이름, `dims` 면 크기 표 |
+| `scanLine` | layer | 스캔선. 돌려준 clip 을 내용 틀에 — `reveal` 드러내기 · `hide` 지우기 |
+| `logTail` | layer | 로그 꼬리. 줄마다 시각을 주면 빠르게 찍히고 한 줄씩 밀린다 |
+| `plotTrace` | layer | 오실로스코프 — 지난 `window` 초, 박 눈금·DROP 표시가 같이 흐른다 |
+| `crosshair` | layer | 조준선 — 키마다 잡고 멈추듯 뛴다, `coords` 좌표 표 |
+| `hudFrame` | layer | 안전 영역 꺾쇠 + 곡 시각·프레임·마디·구간. `grid` 면 계측판 눈금이 늘 흐른다 |
+| `dropTrigger` | layer | 드롭 — 형광으로 뒤집힌 두 프레임 + 가로 띠, 흔들림을 돌려준다 |
+
+견본: `sample/` — 공통 주제 「OpenGateway 소개 15초」, kawaii-friends 4.0–19.0초(드롭 7.34초), 장면 넷 × 마디마다 컷. 숫자는 전부 브리프의 OG 사실(모델 102·회사별 수·주소·가격·실측 ms)이고 굴러가는 중간값만 지나가는 값이다.

package/themes/debug-hud/effects.ts

@@ -0,0 +1,389 @@
+import { clamp, ease, type SceneCtx, type Style } from "@kasaframe/core";
+import { dropBurst, type DropBurstState } from "@kasaframe/motion";
+
+const ink = (ctx: SceneCtx, key: string | undefined, fallback = "ink"): string => ctx.style.colors[key ?? fallback] ?? key ?? fallback;
+const mono = (ctx: SceneCtx, px: number, weight = ctx.style.type.weightBody): string => `${weight} ${px}px ${ctx.style.fonts.mono}`;
+
+type Rect = [x: number, y: number, w: number, h: number];
+const areas = new WeakMap<CanvasRenderingContext2D, Rect>();
+
+// 계기판은 한 장면에 배치를 여럿 겹쳐 둔다 — 효과마다 화면 전체 캔버스를 잡으면 탭 셋이 기가바이트를 먹는다. 그리는 자리만큼만 잡고 좌표는 화면 기준 그대로 쓴다
+function canvas(el: HTMLElement, ctx: SceneCtx, area?: Rect): CanvasRenderingContext2D {
+  const [x, y, w, h] = (area ?? [0, 0, ctx.meta.width, ctx.meta.height]).map(Math.round) as Rect;
+  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);
+};
+
+// 계측 화면은 미끄러지지 않고 「잡고 멈춘다」 — 빠른 outExpo 한 가지로 통일해 모든 효과가 같은 손으로 움직인다
+const SNAP = 0.18;
+const snap = (t: number, at: number, dur = SNAP): number => ease.outExpo(clamp((t - at) / dur));
+
+/** 고정 폭 숫자. 지정한 칸 수를 늘 지키고(앞을 0 으로) NaN·Infinity 는 「--」로 — 굴러도 글 폭이 안 흔들린다 */
+export function readout(t: number, o: { to: number; from?: number; at?: number; dur?: number; width?: number; decimals?: number; unit?: string; sign?: boolean }): string {
+  const dur = o.dur ?? 0;
+  const p = dur > 0 ? clamp((t - (o.at ?? 0)) / dur) : t >= (o.at ?? 0) ? 1 : 0;
+  const v = (o.from ?? o.to) + (o.to - (o.from ?? o.to)) * p;
+  const dec = o.decimals ?? 0;
+  const width = o.width ?? 0;
+  const unit = o.unit ? ` ${o.unit}` : "";
+  if (!Number.isFinite(v)) return `${"-".repeat(Math.max(2, width))}${unit}`;
+  const abs = Math.abs(v).toFixed(dec);
+  const [i, f] = abs.split(".");
+  const body = (f === undefined ? i.padStart(width, "0") : `${i.padStart(Math.max(1, width - dec - 1), "0")}.${f}`).slice(-Math.max(width, abs.length));
+  const sign = v < 0 ? "-" : o.sign ? "+" : "";
+  return `${sign}${body}${unit}`;
+}
+
+export interface Box {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  at: number;
+  label?: string;
+  /** 오른쪽 아래에 「w×h」를 단다 */
+  dims?: boolean;
+}
+
+/** 와이어 상자 — 모서리 꺾쇠가 먼저 서고 변이 가운데로 뻗은 뒤 이름이 찍힌다 */
+export function wireBox(el: HTMLElement, o: { ctx: SceneCtx; boxes: Box[]; dur?: number; until?: number }): (t: number) => void {
+  const { ctx } = o;
+  const x0 = Math.min(...o.boxes.map((b) => b.x)) - 8;
+  const y0 = Math.min(...o.boxes.map((b) => b.y)) - 48;
+  const x1 = Math.max(...o.boxes.map((b) => b.x + Math.max(b.w, 520))) + 8;
+  const y1 = Math.max(...o.boxes.map((b) => b.y + b.h)) + 44;
+  const g = canvas(el, ctx, [x0, y0, x1 - x0, y1 - y0]);
+  const dur = o.dur ?? 0.36;
+  const line = ink(ctx, "ink");
+  const dim = ink(ctx, "dim");
+  return (t) => {
+    clear(g);
+    if (o.until !== undefined && t >= o.until) return;
+    g.lineWidth = 2;
+    g.textBaseline = "bottom";
+    for (const b of o.boxes) {
+      if (t < b.at) continue;
+      const pc = snap(t, b.at, dur * 0.4);
+      const pe = snap(t, b.at + dur * 0.3, dur * 0.7);
+      const arm = Math.min(28, b.w / 2, b.h / 2) * pc;
+      const ex = (b.w / 2 - arm) * pe;
+      const ey = (b.h / 2 - arm) * pe;
+      g.strokeStyle = line;
+      g.beginPath();
+      for (const [cx, cy, sx, sy] of [
+        [b.x, b.y, 1, 1],
+        [b.x + b.w, b.y, -1, 1],
+        [b.x, b.y + b.h, 1, -1],
+        [b.x + b.w, b.y + b.h, -1, -1],
+      ] as const) {
+        g.moveTo(cx + sx * (arm + ex), cy);
+        g.lineTo(cx, cy);
+        g.lineTo(cx, cy + sy * (arm + ey));
+      }
+      g.stroke();
+      if (b.label && t >= b.at + dur * 0.5) {
+        const n = Math.ceil(Array.from(b.label).length * clamp((t - b.at - dur * 0.5) / 0.2));
+        g.font = mono(ctx, 26, 600);
+        g.fillStyle = line;
+        g.fillText(Array.from(b.label).slice(0, n).join(""), b.x, b.y - 8);
+      }
+      if (b.dims && pe > 0.98) {
+        g.font = mono(ctx, 22);
+        g.fillStyle = dim;
+        g.textAlign = "right";
+        g.textBaseline = "top";
+        g.fillText(`${Math.round(b.w)}×${Math.round(b.h)}`, b.x + b.w, b.y + b.h + 8);
+        g.textAlign = "left";
+        g.textBaseline = "bottom";
+      }
+    }
+  };
+}
+
+/** 스캔선 — 지나간 자리만 보이게(reveal) 또는 지나간 자리를 지우게(hide) 하는 clip 을 돌려주고 선과 잔상 줄 셋을 그린다 */
+export function scanLine(el: HTMLElement, o: { ctx: SceneCtx; at: number; dur?: number; dir?: "down" | "up"; mode?: "reveal" | "hide" }): (t: number) => Style {
+  const { ctx } = o;
+  const g = canvas(el, ctx);
+  const H = ctx.meta.height;
+  const dur = o.dur ?? 0.5;
+  const color = ink(ctx, "ink");
+  return (t) => {
+    clear(g);
+    const p = ease.inOutCubic(clamp((t - o.at) / dur));
+    const y = o.dir === "up" ? H * (1 - p) : H * p;
+    if (p > 0 && p < 1) {
+      g.fillStyle = color;
+      for (let i = 0; i < 4; i++) {
+        g.globalAlpha = [1, 0.4, 0.2, 0.08][i];
+        g.fillRect(0, y + (o.dir === "up" ? 1 : -1) * i * 6 - 1, ctx.meta.width, i === 0 ? 3 : 2);
+      }
+      g.globalAlpha = 1;
+    }
+    if (o.mode === "hide") return o.dir === "up" ? { clip: { bottom: p } } : { clip: { top: p } };
+    if (p >= 1) return { clip: { top: 0, bottom: 0 } };
+    return o.dir === "up" ? { clip: { top: 1 - p } } : { clip: { bottom: 1 - p } };
+  };
+}
+
+/** 로그 꼬리(tail -f) — 줄은 정한 시각에 빠르게 찍히고, 칸이 차면 한 줄씩 끊어 위로 민다 */
+export function logTail(el: HTMLElement, o: { ctx: SceneCtx; x: number; y: number; w: number; h: number; lines: { t: number; text: string; dim?: boolean }[]; size?: number; cps?: number }): (t: number) => void {
+  const { ctx } = o;
+  const g = canvas(el, ctx, [o.x, o.y, o.w, o.h]);
+  const size = o.size ?? 26;
+  const lh = Math.round(size * 1.5);
+  const rows = Math.max(1, Math.floor(o.h / lh));
+  const cps = o.cps ?? 140;
+  const lines = [...o.lines].sort((a, b) => a.t - b.t);
+  return (t) => {
+    clear(g);
+    const shown = lines.filter((l) => l.t <= t);
+    const tail = shown.slice(-rows);
+    g.save();
+    g.beginPath();
+    g.rect(o.x, o.y, o.w, o.h);
+    g.clip();
+    g.font = mono(ctx, size);
+    g.textBaseline = "top";
+    tail.forEach((l, i) => {
+      const chars = Array.from(l.text);
+      const n = Math.min(chars.length, Math.ceil((t - l.t) * cps));
+      g.fillStyle = ink(ctx, l.dim ? "dim" : "ink");
+      g.fillText(chars.slice(0, n).join(""), o.x, o.y + i * lh);
+      if (n < chars.length || l === tail.at(-1)) {
+        const cw = g.measureText(chars.slice(0, n).join("")).width;
+        if (n < chars.length || Math.floor((t - l.t) / 0.5) % 2 === 0) g.fillRect(o.x + cw + 4, o.y + i * lh + 2, size * 0.55, size);
+      }
+    });
+    g.restore();
+  };
+}
+
+export interface Series {
+  /** 장면 시각 → 0..1 */
+  value(t: number): number;
+  label: string;
+  /** 0 이 가장 밝다 — 한 색의 단으로만 가른다 */
+  tone?: 0 | 1 | 2;
+}
+
+/** 오실로스코프 — 지난 window 초를 오른쪽 끝이 지금인 선으로. 박 눈금이 같이 흘러가고 드롭 자리에 표시가 선다 */
+export function plotTrace(el: HTMLElement, o: { ctx: SceneCtx; x: number; y: number; w: number; h: number; series: Series[]; window?: number; at?: number; since?: number }): (t: number) => void {
+  const { ctx } = o;
+  const g = canvas(el, ctx, [o.x - 12, o.y - 12, o.w + 260, o.h + 24]);
+  const win = o.window ?? 4;
+  const N = 160;
+  const color = ink(ctx, "ink");
+  const dim = ink(ctx, "dim");
+  const faint = ink(ctx, "line");
+  const since = o.since ?? 0;
+  const xOf = (tt: number, t: number) => o.x + o.w * (1 - (t - tt) / win);
+  return (t) => {
+    clear(g);
+    if (t < (o.at ?? 0)) return;
+    const reveal = snap(t, o.at ?? 0, 0.3);
+    g.save();
+    g.beginPath();
+    g.rect(o.x, o.y - 4, o.w * reveal, o.h + 8);
+    g.clip();
+    const b = ctx.beats;
+    for (const bt of b.beats) {
+      if (bt < t - win || bt > t) continue;
+      const down = b.downbeats.some((d) => Math.abs(d - bt) < 1e-3);
+      g.fillStyle = down ? dim : faint;
+      g.fillRect(Math.round(xOf(bt, t)), o.y, down ? 2 : 1, o.h);
+    }
+    g.font = mono(ctx, 22, 600);
+    g.textBaseline = "top";
+    for (const d of b.drops) {
+      if (d < t - win || d > t) continue;
+      const x = xOf(d, t);
+      g.fillStyle = color;
+      g.fillRect(Math.round(x) - 1, o.y, 3, o.h);
+      g.fillText("DROP", x + 8, o.y + 6);
+    }
+    o.series.forEach((s, k) => {
+      g.strokeStyle = [color, dim, faint][s.tone ?? k] ?? color;
+      g.lineWidth = s.tone === 0 || (s.tone === undefined && k === 0) ? 3 : 2;
+      g.beginPath();
+      let started = false;
+      for (let i = 0; i <= N; i++) {
+        const tt = t - win + (win * i) / N;
+        if (tt < since) continue;
+        const v = clamp(s.value(tt));
+        const px = xOf(tt, t);
+        const py = o.y + o.h * (1 - v);
+        if (!started) g.moveTo(px, py);
+        else g.lineTo(px, py);
+        started = true;
+      }
+      g.stroke();
+    });
+    g.restore();
+    const head = o.series[0];
+    if (head && t >= since) {
+      const v = clamp(head.value(t));
+      g.fillStyle = color;
+      g.fillRect(o.x + o.w - 6, o.y + o.h * (1 - v) - 6, 12, 12);
+    }
+    g.font = mono(ctx, 24, 600);
+    g.textBaseline = "top";
+    o.series.forEach((s, k) => {
+      g.fillStyle = [color, dim, dim][s.tone ?? k] ?? color;
+      g.fillText(`${s.label} ${readout(0, { to: t >= since ? clamp(s.value(t)) : NaN, width: 4, decimals: 2 })}`, o.x + o.w + 40, o.y + k * 40);
+    });
+  };
+}
+
+/** 조준선 — 화면을 가로지르는 가는 선 둘과 가운데 과녁, 좌표 표. 키 사이를 잡고 멈추듯 옮긴다 */
+export function crosshair(el: HTMLElement, o: { ctx: SceneCtx; keys: { t: number; x: number; y: number; label?: string }[]; move?: number; at?: number; area?: [number, number, number, number]; coords?: boolean; size?: number }): (t: number) => void {
+  const { ctx } = o;
+  const keys = [...o.keys].sort((a, b) => a.t - b.t);
+  const move = o.move ?? 0.24;
+  const [ax, ay, aw, ah] = o.area ?? [0, 0, ctx.meta.width, ctx.meta.height];
+  const r0 = o.size ?? 26;
+  const g = canvas(el, ctx, [ax - r0 - 4, ay - r0 - 40, aw + r0 + 300, ah + 2 * r0 + 80]);
+  const color = ink(ctx, "ink");
+  const dim = ink(ctx, "dim");
+  return (t) => {
+    clear(g);
+    if (!keys.length || t < (o.at ?? keys[0].t)) return;
+    let i = 0;
+    while (i + 1 < keys.length && keys[i + 1].t <= t) i++;
+    const a = keys[Math.max(0, i - 1)];
+    const b = keys[i];
+    const p = i === 0 ? 1 : snap(t, b.t, move);
+    const x = a.x + (b.x - a.x) * p;
+    const y = a.y + (b.y - a.y) * p;
+    g.fillStyle = dim;
+    g.fillRect(ax, Math.round(y), aw, 1);
+    g.fillRect(Math.round(x), ay, 1, ah);
+    g.strokeStyle = color;
+    g.lineWidth = 2;
+    const r = o.size ?? 26;
+    g.strokeRect(x - r, y - r, r * 2, r * 2);
+    g.fillStyle = color;
+    g.fillRect(x - 3, y - 3, 6, 6);
+    g.font = mono(ctx, 22, 600);
+    g.textBaseline = "top";
+    if (o.coords !== false) g.fillText(`x ${readout(0, { to: x, width: 4 })}  y ${readout(0, { to: y, width: 4 })}`, x + r + 10, y + r + 6);
+    if (b.label && p > 0.9) g.fillText(b.label, x + r + 10, y - r - 2);
+  };
+}
+
+/** HUD 틀 — 안전 영역 모서리 꺾쇠, 곡 시각·프레임 번호·마디·구간. 전부 그 프레임에 잰 값이라 멈추지 않는다 */
+export function hudFrame(el: HTMLElement, o: { ctx: SceneCtx; title: string; songFrom?: number; barFrom?: number; at?: number; grid?: { step?: number; speed?: number } }): (t: number) => void {
+  const { ctx } = o;
+  const g = canvas(el, ctx);
+  const s = ctx.safe;
+  const W = ctx.meta.width;
+  const H = ctx.meta.height;
+  const L = s.left || 60;
+  const T = s.top || 40;
+  const R = W - (s.right || 60);
+  const B = H - (s.bottom || 40);
+  const color = ink(ctx, "ink");
+  const dim = ink(ctx, "dim");
+  const step = o.grid?.step ?? 60;
+  const speed = o.grid?.speed ?? 360;
+  return (t) => {
+    clear(g);
+    // 계측판 눈금 — 늘 한쪽으로 흘러 재는 동안 화면이 한순간도 서지 않는다
+    if (o.grid) {
+      const off = (((ctx.from + t) * speed) % step + step) % step;
+      g.fillStyle = ink(ctx, "line");
+      for (let x = off - step; x < W; x += step) g.fillRect(Math.round(x), 0, 2, H);
+      for (let y = (off * 0.5) % step - step; y < H; y += step) g.fillRect(0, Math.round(y), W, 2);
+      // 마디마다 화면을 한 번 가로지르는 계측 커서
+      const b0 = ctx.beats.prev(t, "bar");
+      const b1 = ctx.beats.next(t, "bar");
+      if (Number.isFinite(b0) && Number.isFinite(b1) && b1 > b0) {
+        g.fillStyle = ink(ctx, "dim");
+        g.fillRect(Math.round(((t - b0) / (b1 - b0)) * W), 0, 3, H);
+      }
+    }
+    const p = snap(t, o.at ?? 0, 0.3);
+    if (p <= 0) return;
+    const arm = 44 * p;
+    g.strokeStyle = color;
+    g.lineWidth = 3;
+    g.beginPath();
+    for (const [cx, cy, sx, sy] of [
+      [L - 30, T - 20, 1, 1],
+      [R + 30, T - 20, -1, 1],
+      [L - 30, B + 20, 1, -1],
+      [R + 30, B + 20, -1, -1],
+    ] as const) {
+      g.moveTo(cx + sx * arm, cy);
+      g.lineTo(cx, cy);
+      g.lineTo(cx, cy + sy * arm);
+    }
+    g.stroke();
+    if (p < 0.6) return;
+    const song = (o.songFrom ?? 0) + ctx.from + t;
+    const bar = (o.barFrom ?? 0) + ctx.beats.bars.filter((x) => x <= t + 1e-6).length;
+    const f = Math.floor((ctx.from + t) * ctx.meta.fps + 1e-6);
+    const sec = ctx.beats.section(t);
+    g.font = mono(ctx, 26, 600);
+    g.fillStyle = color;
+    g.textBaseline = "top";
+    g.fillText(o.title, L, T);
+    g.textAlign = "right";
+    g.fillText(`${readout(0, { to: Math.floor(song / 60), width: 2 })}:${readout(0, { to: song % 60, width: 5, decimals: 2 })}`, R, T);
+    g.fillStyle = dim;
+    g.fillText(`F ${readout(0, { to: f, width: 5 })}`, R, T + 36);
+    g.textBaseline = "bottom";
+    g.fillStyle = color;
+    g.fillText(`BAR ${readout(0, { to: bar, width: 3 })}`, R, B);
+    g.textAlign = "left";
+    g.fillText(`${String(sec.kind).toUpperCase()} ${readout(0, { to: sec.strength ?? 0, width: 4, decimals: 2 })}`, L, B);
+  };
+}
+
+/** 드롭 트리거 — 화면이 두 프레임 형광으로 뒤집히고 가로 띠가 어긋났다 돌아온다. 흔들림을 돌려준다 */
+export function dropTrigger(el: HTMLElement, o: { ctx: SceneCtx; drop?: number; label?: string }): (t: number) => DropBurstState {
+  const { ctx } = o;
+  const g = canvas(el, ctx);
+  const W = ctx.meta.width;
+  const H = ctx.meta.height;
+  const color = ink(ctx, "ink");
+  const bg = ink(ctx, "bg");
+  return (t) => {
+    const s = dropBurst(t, { beats: ctx.beats, drop: o.drop ?? 0, rules: ctx.style.motion, scene: ctx.id, source: "dropTrigger" });
+    clear(g);
+    const local = t - ctx.beats.drop(o.drop ?? 0);
+    if (local < 0 || local > 0.5) return s;
+    if (s.flash > 0.6) {
+      g.fillStyle = color;
+      g.fillRect(0, 0, W, H);
+      g.fillStyle = bg;
+      g.font = mono(ctx, 160, 800);
+      g.textBaseline = "middle";
+      g.textAlign = "center";
+      g.fillText(o.label ?? "TRIG", W / 2, H / 2);
+      g.textAlign = "left";
+      return s;
+    }
+    // 섬광이 걷히는 동안 형광 가로 띠 몇 줄 — 줄 수와 자리는 드롭에서 지난 시각만으로 정한다
+    const k = Math.floor(local * 30);
+    g.fillStyle = color;
+    for (let i = 0; i < 6 - k; i++) {
+      const y = ((i * 397 + k * 131) % H) | 0;
+      g.globalAlpha = s.flash * 0.9 + 0.1;
+      g.fillRect(0, y, W, 6 + ((i * 7) % 18));
+    }
+    g.globalAlpha = 1;
+    return s;
+  };
+}

package/themes/debug-hud/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>