kasaframe 0.0.0-stage → 0.1.3

package/templates/square/template.json

@@ -0,0 +1,133 @@
+{
+  "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"
+  },
+  "moves": {
+    "text": [
+      "slamWords",
+      "splitFlap",
+      "echoStack",
+      "ransomLetters"
+    ],
+    "wipe": [
+      "brushWipe",
+      "flood"
+    ],
+    "roles": {
+      "hook": {
+        "text": [
+          "slamWords"
+        ]
+      }
+    }
+  },
+  "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": [],
+    "act": "hook"
+  },
+  "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>

package/themes/debug-hud/sample/beats.json

@@ -0,0 +1 @@
+{"source": "assets/music/kawaii-friends-0400.mp3", "from": 0, "duration": 15.0, "bpm": 170.0, "beats": [0.2899, 0.6382, 0.9923, 1.3464, 1.6947, 2.0546, 2.4029, 2.757, 3.1169, 3.4652, 3.8251, 4.1734, 4.5275, 4.8758, 5.2299, 5.584, 5.9381, 6.2922, 6.6463, 6.9946, 7.336, 7.6971, 8.0628, 8.4053, 8.7478, 9.1135, 9.4676, 9.8159, 10.1816, 10.5241, 10.8782, 11.2265, 11.5748, 11.9405, 12.3004, 12.6487, 12.997, 13.3453, 13.7052, 14.0477, 14.396, 14.7617], "downbeats": [0.2899, 1.6947, 3.1169, 4.5275, 5.9381, 7.336, 8.7478, 10.1816, 11.5748, 12.997, 14.396], "bars": [0.2899, 1.6947, 3.1169, 4.5275, 5.9381, 7.336, 8.7478, 10.1816, 11.5748, 12.997, 14.396], "phrases": [0.0, 1.6947, 7.336, 12.997], "sections": [{"t": 0.0, "kind": "intro"}, {"t": 7.336, "kind": "drop", "strength": 0.99}], "drops": [7.336], "energy": {"hz": 20, "low": [0.0, 0.144, 0.183, 0.0, 0.0, 0.001, 0.0, 0.0, 0.208, 0.21, 0.0, 0.0, 0.0, 0.0, 0.0, 0.226, 0.241, 0.0, 0.0, 0.394, 0.25, 0.0, 0.131, 0.19, 0.033, 0.024, 0.245, 0.101, 0.009, 0.0, 0.0, 0.016, 0.134, 0.285, 0.097, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.371, 0.335, 0.0, 0.0, 0.148, 0.0, 0.0, 0.265, 0.171, 0.0, 0.0, 0.184, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.249, 0.015, 0.0, 0.0, 0.0, 0.0, 0.072, 0.297, 0.092, 0.009, 0.312, 0.389, 0.096, 0.031, 0.133, 0.021, 0.112, 0.0, 0.0, 0.074, 0.0, 0.227, 0.089, 0.018, 0.0, 0.091, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.022, 0.0, 0.0, 0.026, 0.02, 0.006, 0.184, 0.411, 0.068, 0.0, 0.156, 0.083, 0.0, 0.055, 0.182, 0.074, 0.0, 0.288, 0.232, 0.072, 0.022, 0.0, 0.0, 0.0, 0.0, 0.0, 0.015, 0.018, 0.053, 0.0, 0.03, 0.0, 0.0, 0.004, 0.094, 0.461, 0.453, 0.505, 0.55, 0.588, 0.627, 0.672, 0.72, 0.752, 0.759, 0.767, 0.772, 0.761, 0.724, 0.896, 0.998, 0.973, 0.838, 0.624, 0.667, 0.733, 0.796, 0.819, 0.8, 0.747, 0.833, 0.811, 0.816, 0.733, 0.507, 0.341, 0.066, 0.062, 0.0, 0.0, 0.798, 0.981, 1.0, 0.943, 0.813, 0.803, 0.799, 0.747, 0.606, 0.6, 0.606, 0.622, 0.649, 0.684, 0.812, 0.992, 0.986, 0.92, 0.668, 0.628, 0.572, 0.479, 0.365, 0.0, 0.0, 0.075, 0.0, 0.0, 0.758, 1.0, 1.0, 0.979, 0.876, 0.899, 0.9, 0.844, 0.772, 0.805, 0.811, 0.83, 0.858, 0.897, 0.945, 1.0, 0.961, 0.898, 0.862, 0.911, 0.902, 0.822, 0.611, 0.352, 0.0, 0.083, 0.0, 0.0, 0.682, 0.999, 0.985, 0.983, 0.897, 0.871, 0.869, 0.855, 0.74, 0.678, 0.686, 0.705, 0.733, 0.771, 0.793, 0.956, 0.999, 0.955, 0.815, 0.738, 0.75, 0.757, 0.672, 0.597, 0.618, 0.761, 0.977, 0.994, 0.935, 0.8, 0.8, 0.792, 0.782, 0.743, 0.643, 0.522, 0.898, 0.996, 0.975, 0.829, 0.577, 0.615, 0.683, 0.739, 0.765, 0.748, 0.703, 0.763, 0.752, 0.757, 0.68, 0.478, 0.287, 0.03, 0.055, 0.0, 0.022, 0.832, 0.99, 0.967, 0.886, 0.739, 0.749, 0.76, 0.719, 0.607, 0.613, 0.628, 0.645, 0.669, 0.713, 0.823, 1.0, 0.989, 0.916, 0.754, 0.736], "mid": [0.625, 0.806, 0.843, 0.738, 0.642, 0.71, 0.726, 0.582, 0.708, 0.759, 0.668, 0.544, 0.611, 0.572, 0.451, 0.785, 0.835, 0.629, 0.607, 0.911, 0.834, 0.737, 0.856, 0.806, 0.755, 0.566, 0.739, 0.759, 0.685, 0.742, 0.708, 0.66, 0.649, 0.834, 0.819, 0.654, 0.626, 0.747, 0.713, 0.526, 0.65, 0.711, 0.616, 0.518, 0.679, 0.644, 0.437, 0.861, 0.792, 0.499, 0.6, 0.773, 0.665, 0.541, 0.865, 0.918, 0.817, 0.666, 0.852, 0.772, 0.629, 0.697, 0.756, 0.683, 0.585, 0.767, 0.706, 0.55, 0.633, 0.706, 0.632, 0.595, 0.805, 0.726, 0.689, 0.822, 0.841, 0.661, 0.738, 0.746, 0.585, 0.553, 0.588, 0.601, 0.599, 0.566, 0.831, 0.755, 0.6, 0.698, 0.863, 0.782, 0.543, 0.66, 0.617, 0.593, 0.647, 0.707, 0.746, 0.728, 0.746, 0.741, 0.665, 0.748, 0.881, 0.656, 0.472, 0.682, 0.66, 0.618, 0.719, 0.915, 0.852, 0.797, 0.899, 0.862, 0.789, 0.769, 0.7, 0.637, 0.575, 0.608, 0.638, 0.653, 0.664, 0.714, 0.763, 0.732, 0.705, 0.722, 0.722, 0.794, 0.908, 0.714, 0.575, 0.602, 0.584, 0.615, 0.628, 0.732, 0.814, 0.826, 0.779, 0.756, 0.718, 0.641, 0.947, 0.785, 0.711, 0.7, 0.742, 0.817, 0.844, 0.879, 0.896, 0.888, 0.878, 0.878, 0.864, 0.82, 0.876, 0.775, 0.496, 0.503, 0.591, 0.607, 0.65, 0.945, 0.901, 0.821, 0.799, 0.845, 0.875, 0.891, 0.863, 0.757, 0.747, 0.77, 0.796, 0.821, 0.837, 0.935, 0.898, 0.746, 0.732, 0.823, 0.791, 0.805, 0.854, 0.843, 0.515, 0.434, 0.63, 0.711, 0.701, 0.893, 0.92, 0.775, 0.78, 0.834, 0.793, 0.723, 0.708, 0.777, 0.773, 0.82, 0.845, 0.876, 0.918, 0.993, 1.0, 1.0, 0.9, 0.954, 0.887, 0.84, 0.841, 0.888, 0.601, 0.394, 0.659, 0.815, 0.862, 0.939, 1.0, 0.974, 0.953, 0.891, 0.902, 0.903, 0.91, 0.818, 0.778, 0.724, 0.712, 0.78, 0.789, 0.831, 0.966, 0.839, 0.816, 0.822, 0.822, 0.823, 0.843, 0.891, 0.736, 0.674, 0.871, 0.882, 0.8, 0.831, 0.886, 0.902, 0.898, 0.884, 0.909, 0.859, 0.787, 0.949, 0.796, 0.732, 0.753, 0.82, 0.825, 0.862, 0.904, 0.887, 0.883, 0.891, 0.89, 0.876, 0.789, 0.877, 0.733, 0.36, 0.504, 0.736, 0.773, 0.788, 0.977, 0.945, 0.924, 0.905, 0.866, 0.864, 0.867, 0.828, 0.737, 0.731, 0.776, 0.775, 0.75, 0.804, 0.959, 0.923, 0.796, 0.789, 0.85, 0.849], "high": [0.498, 0.853, 0.762, 0.559, 0.557, 0.552, 0.53, 0.517, 0.82, 0.775, 0.541, 0.543, 0.521, 0.483, 0.506, 0.845, 0.835, 0.601, 0.653, 0.952, 0.836, 0.629, 0.85, 0.779, 0.549, 0.583, 0.814, 0.62, 0.566, 0.76, 0.644, 0.544, 0.692, 0.884, 0.66, 0.547, 0.555, 0.615, 0.504, 0.5, 0.528, 0.522, 0.522, 0.513, 0.482, 0.507, 0.549, 0.923, 0.885, 0.563, 0.615, 0.731, 0.497, 0.47, 0.745, 0.681, 0.508, 0.594, 0.784, 0.576, 0.546, 0.547, 0.52, 0.543, 0.638, 0.806, 0.585, 0.587, 0.633, 0.633, 0.643, 0.713, 0.881, 0.809, 0.828, 0.905, 0.936, 0.696, 0.726, 0.85, 0.646, 0.663, 0.682, 0.705, 0.706, 0.728, 0.892, 0.764, 0.738, 0.731, 0.693, 0.645, 0.625, 0.653, 0.654, 0.695, 0.751, 0.773, 0.773, 0.782, 0.837, 0.836, 0.832, 0.884, 0.96, 0.761, 0.678, 0.85, 0.793, 0.786, 0.871, 0.962, 0.906, 0.882, 0.903, 0.888, 0.891, 0.864, 0.758, 0.674, 0.697, 0.712, 0.726, 0.752, 0.807, 0.838, 0.836, 0.848, 0.85, 0.868, 0.897, 0.907, 0.977, 0.839, 0.709, 0.726, 0.751, 0.78, 0.825, 0.863, 0.856, 0.857, 0.864, 0.875, 0.874, 1.0, 1.0, 0.811, 0.806, 0.793, 0.789, 0.826, 0.86, 0.895, 0.892, 0.888, 0.883, 0.879, 0.87, 0.847, 0.948, 0.885, 0.649, 0.574, 0.654, 0.671, 0.696, 0.831, 0.804, 0.843, 0.812, 0.839, 0.899, 0.906, 0.845, 0.707, 0.727, 0.774, 0.771, 0.783, 0.813, 0.877, 0.77, 0.659, 0.672, 0.81, 0.843, 0.864, 0.932, 0.928, 0.637, 0.439, 0.61, 0.671, 0.644, 0.802, 0.77, 0.736, 0.728, 0.714, 0.616, 0.503, 0.548, 0.683, 0.71, 0.714, 0.705, 0.758, 0.831, 0.872, 0.872, 0.875, 0.885, 0.89, 0.854, 0.82, 0.892, 0.961, 0.726, 0.496, 0.603, 0.74, 0.744, 0.828, 0.847, 0.846, 0.831, 0.786, 0.846, 0.859, 0.837, 0.747, 0.713, 0.673, 0.715, 0.84, 0.868, 0.829, 0.848, 0.796, 0.803, 0.838, 0.921, 0.944, 0.927, 0.968, 0.831, 0.699, 0.812, 0.798, 0.799, 0.863, 0.888, 0.847, 0.839, 0.861, 0.884, 0.834, 0.78, 0.832, 0.689, 0.707, 0.686, 0.702, 0.801, 0.858, 0.88, 0.871, 0.862, 0.852, 0.882, 0.867, 0.806, 0.946, 0.851, 0.52, 0.458, 0.679, 0.739, 0.75, 0.862, 0.857, 0.873, 0.821, 0.899, 0.924, 0.921, 0.846, 0.77, 0.781, 0.774, 0.783, 0.81, 0.867, 0.948, 0.824, 0.734, 0.722, 0.894, 0.935]}}

package/themes/debug-hud/sample/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="ko">
+  <head>
+    <meta charset="utf-8" />
+    <title>debug-hud 견본</title>
+  </head>
+  <body>
+    <div id="stage"></div>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>

package/themes/debug-hud/sample/kf.json

@@ -0,0 +1,59 @@
+{
+  "template": "promo",
+  "title": "debug-hud · OpenGateway 15초",
+  "theme": "debug-hud",
+  "fps": 60,
+  "width": 1920,
+  "height": 1080,
+  "duration": 15.0,
+  "mode": "seek",
+  "style": "style.json",
+  "music": "assets/music/kawaii-friends-0400.mp3",
+  "beats": "beats.json",
+  "captions": "none",
+  "safeArea": {
+    "top": 60,
+    "bottom": 60,
+    "left": 80,
+    "right": 80
+  },
+  "text": {
+    "policy": "terms-only",
+    "maxOnScreen": 0,
+    "minPx": 0
+  },
+  "scenes": [
+    {
+      "id": "gather",
+      "from": 0,
+      "dur": 3.1169,
+      "file": "scenes/gather.ts",
+      "role": "hook",
+      "idea": "회사 아홉을 흩어진 상자로 박마다 재고, 회사별 모델 수를 막대 상자로 잰다"
+    },
+    {
+      "id": "models",
+      "from": 3.1169,
+      "dur": 4.2191,
+      "file": "scenes/models.ts",
+      "role": "explain",
+      "idea": "한 주소를 재고 엔드포인트가 로그로, 같은 주소에 모델 ID 만 바뀌는 요청이 박마다 로그로, 모델 수가 102 로 굴러 오른다"
+    },
+    {
+      "id": "price",
+      "from": 7.336,
+      "dur": 4.2388,
+      "file": "scenes/price.ts",
+      "role": "drop",
+      "idea": "드롭 트리거 102, 하루 가격선이 흐르며 00–10시 창을 재고 -90%, deepseek 가격 숫자가 굴러 내려간다"
+    },
+    {
+      "id": "end",
+      "from": 11.5748,
+      "dur": 3.4252,
+      "file": "scenes/end.ts",
+      "role": "end",
+      "idea": "첫 토큰 실측 ms 셋을 굴려 재고, OG 로고를 상자로 재는 끝 카드"
+    }
+  ]
+}