kasaframe 0.0.0-stage → 0.1.1

package/packages/check/src/probe.ts

@@ -0,0 +1,328 @@
+// 페이지 안에서 도는 탐침. addInitScript 로 페이지 스크립트보다 먼저 들어가야
+// 장면이 처음 부르는 fillText 부터 잡힌다. 함수 본문만 직렬화되므로 바깥 이름을 쓰지 않는다.
+export function probe(): void {
+  const w = window as any;
+  if (w.__kfCheck) return;
+
+  const C2D: any = CanvasRenderingContext2D.prototype;
+  const O2D: any = typeof OffscreenCanvasRenderingContext2D !== "undefined" ? OffscreenCanvasRenderingContext2D.prototype : null;
+  // 판정용 작은 판은 OffscreenCanvas 라 그쪽 원본 fillText 를 따로 쥔다(다른 원형으로 부르면 Illegal invocation).
+  const origFill = (O2D || C2D).fillText;
+  const hits: any[] = [];
+  const rects = new Map<any, any>();
+  const SUSPECT = /undefined|NaN|\[object |null|Infinity/;
+
+  function canvasRect(cv: HTMLCanvasElement) {
+    let r = rects.get(cv);
+    if (!r) {
+      const b = cv.getBoundingClientRect();
+      r = { x: b.left, y: b.top, sx: b.width / (cv.width || 1), sy: b.height / (cv.height || 1) };
+      rects.set(cv, r);
+    }
+    return r;
+  }
+
+  // 나쁜 글자가 나온 순간만 스택을 떠서 어느 장면 파일 몇째 줄인지 알려 준다.
+  function caller(): string | undefined {
+    const limit = (Error as any).stackTraceLimit;
+    (Error as any).stackTraceLimit = 30;
+    const stack = new Error().stack || "";
+    (Error as any).stackTraceLimit = limit;
+    // 탐침 자신은 주소 없는 <anonymous> 로 찍힌다. 주소가 붙은 첫 줄들이 장면 코드다.
+    const lines = stack.split("\n").slice(1).map((s) => s.trim()).filter((s) => /(https?|file):\/\//.test(s));
+    return lines.slice(0, 3).join(" <- ") || undefined;
+  }
+
+  function record(ctx: any, raw: unknown, x: number, y: number) {
+    const text = String(raw);
+    if (!text.trim()) return;
+    const m = /(\d+(?:\.\d+)?)px/.exec(ctx.font);
+    const hit: any = {
+      text,
+      via: "canvas",
+      font: ctx.font,
+      sizePx: m ? parseFloat(m[1]) : 0,
+      alpha: ctx.globalAlpha,
+    };
+    if (typeof raw !== "string") hit.argType = raw === null ? "null" : typeof raw;
+    if (SUSPECT.test(text) || hit.argType) hit.where = caller();
+    const cv = ctx.canvas;
+    if (typeof HTMLCanvasElement !== "undefined" && cv instanceof HTMLCanvasElement && cv.closest("[data-kf-lyrics]")) hit.lyrics = true;
+    if (typeof HTMLCanvasElement !== "undefined" && cv instanceof HTMLCanvasElement && cv.isConnected) {
+      const mt = ctx.measureText(text);
+      const l = x - mt.actualBoundingBoxLeft;
+      const r = x + mt.actualBoundingBoxRight;
+      const t = y - mt.actualBoundingBoxAscent;
+      const b = y + mt.actualBoundingBoxDescent;
+      const M = ctx.getTransform();
+      const cr = canvasRect(cv);
+      let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity;
+      for (const [px, py] of [[l, t], [r, t], [l, b], [r, b]]) {
+        const qx = (M.a * px + M.c * py + M.e) * cr.sx + cr.x;
+        const qy = (M.b * px + M.d * py + M.f) * cr.sy + cr.y;
+        x0 = Math.min(x0, qx); y0 = Math.min(y0, qy); x1 = Math.max(x1, qx); y1 = Math.max(y1, qy);
+      }
+      hit.box = { x0, y0, x1, y1 };
+      hit.sizePx *= Math.hypot(M.b, M.d) * cr.sy;
+    }
+    hits.push(hit);
+  }
+
+  for (const proto of [C2D, O2D]) {
+    if (!proto) continue;
+    const fill = proto.fillText;
+    const stroke = proto.strokeText;
+    proto.fillText = function (this: any, text: unknown, x: number, y: number, maxWidth?: number) {
+      try { record(this, text, x, y); } catch {}
+      return maxWidth === undefined ? fill.call(this, text, x, y) : fill.call(this, text, x, y, maxWidth);
+    };
+    proto.strokeText = function (this: any, text: unknown, x: number, y: number, maxWidth?: number) {
+      try { record(this, text, x, y); } catch {}
+      return maxWidth === undefined ? stroke.call(this, text, x, y) : stroke.call(this, text, x, y, maxWidth);
+    };
+  }
+
+  function selector(el: Element | null): string {
+    const parts: string[] = [];
+    for (let e = el, i = 0; e && e !== document.body && i < 3; e = e.parentElement, i++) {
+      let s = e.tagName.toLowerCase();
+      if (e.id) s += "#" + e.id;
+      else if (typeof e.className === "string" && e.className.trim()) s += "." + e.className.trim().split(/\s+/).slice(0, 2).join(".");
+      parts.unshift(s);
+    }
+    // mountProject 가 장면 뿌리에 data-kf-scene 을 단다 — 고칠 파일 이름이 곧 그것이다.
+    const scene = el?.closest("[data-kf-scene]")?.getAttribute("data-kf-scene");
+    return scene ? `scenes/${scene}.ts · ${parts.join(" > ")}` : parts.join(" > ");
+  }
+
+  // 스크린리더 전용 글(1px 상자·clip·clip-path 로 숨김)은 화면에 없다. checkVisibility 는 이걸 못 거른다.
+  const hiddenBox = new Map<Element, boolean>();
+  function srOnly(el: Element | null, depth = 0): boolean {
+    if (!el || el === document.body || depth > 3) return false;
+    const c = hiddenBox.get(el);
+    if (c !== undefined) return c;
+    const cs = getComputedStyle(el);
+    const r = el.getBoundingClientRect();
+    const v =
+      ((r.width <= 1 || r.height <= 1) && cs.overflow !== "visible") ||
+      ((cs.position === "absolute" || cs.position === "fixed") && !!cs.clip && cs.clip !== "auto") ||
+      /inset\(\s*(50|100)%|circle\(\s*0/.test(cs.clipPath || "") ||
+      srOnly(el.parentElement, depth + 1);
+    hiddenBox.set(el, v);
+    return v;
+  }
+
+  function domHits(): any[] {
+    const root = document.getElementById("stage") || document.body;
+    if (!root) return [];
+    hiddenBox.clear();
+    const out: any[] = [];
+    const opacity = new Map<Element, number>();
+    const effOpacity = (el: Element | null): number => {
+      if (!el) return 1;
+      const c = opacity.get(el);
+      if (c !== undefined) return c;
+      const v = parseFloat(getComputedStyle(el).opacity || "1") * effOpacity(el.parentElement);
+      opacity.set(el, v);
+      return v;
+    };
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+    const range = document.createRange();
+    for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+      const text = n.nodeValue || "";
+      if (!text.trim()) continue;
+      const el = n.parentElement;
+      if (!el || /^(SCRIPT|STYLE|NOSCRIPT|TEMPLATE)$/.test(el.tagName)) continue;
+      if ((el as any).checkVisibility && !(el as any).checkVisibility({ opacityProperty: true, visibilityProperty: true })) continue;
+      range.selectNodeContents(n);
+      const b = range.getBoundingClientRect();
+      if (b.width < 1 || b.height < 1) continue;
+      const cs = getComputedStyle(el);
+      const scale = (el as HTMLElement).offsetWidth ? el.getBoundingClientRect().width / (el as HTMLElement).offsetWidth : 1;
+      const hit: any = {
+        text: text.trim(),
+        via: el.closest("[data-kf-captions]") ? "caption" : "dom",
+        lyrics: !!el.closest("[data-kf-lyrics]") || undefined,
+        font: `${cs.fontStyle} ${cs.fontWeight} ${cs.fontSize} ${cs.fontFamily}`,
+        sizePx: parseFloat(cs.fontSize) * (scale || 1),
+        alpha: effOpacity(el),
+        box: { x0: b.left, y0: b.top, x1: b.right, y1: b.bottom },
+      };
+      // 캔버스 자식(HTML-in-Canvas)은 DOM 으로 안 보이고 텍스처가 되어 3D 화면 어딘가에 그려진다. 스크린리더 전용 글은 화면에 없다.
+      // 둘 다 화면 자리를 빼 대비·화면 밖·글 크기 판정에서만 빠지게 한다 — undefined·두부 같은 글 내용 판정에는 남는다
+      if (el.closest("canvas") || srOnly(el)) delete hit.box;
+      if (SUSPECT.test(hit.text)) hit.where = selector(el);
+      out.push(hit);
+    }
+    return out;
+  }
+
+  // 글리프 판정용 작은 판. 가로챈 fillText 를 거치지 않게 원본을 쓴다.
+  const pad = typeof OffscreenCanvas !== "undefined" ? new OffscreenCanvas(64, 64) : null;
+  const pctx: any = pad ? pad.getContext("2d", { willReadFrequently: true }) : null;
+  const GENERIC = /^(serif|sans-serif|monospace|cursive|fantasy|system-ui|ui-\w+|emoji|math|fangsong)$/i;
+
+  function ink(font: string, ch: string): Uint8ClampedArray {
+    pctx.clearRect(0, 0, 64, 64);
+    pctx.font = font;
+    pctx.fillStyle = "#000";
+    // middle·center 는 첫 글꼴의 높이·폭으로 자리를 잡아, 같은 대체 글리프도 스택마다 다른 자리에 찍힌다.
+    // 글자 시작점과 기본 기준선은 어느 글꼴이든 같은 자리다.
+    pctx.textBaseline = "alphabetic";
+    pctx.textAlign = "left";
+    origFill.call(pctx, ch, 8, 46);
+    return pctx.getImageData(0, 0, 64, 64).data;
+  }
+  function same(a: Uint8ClampedArray, b: Uint8ClampedArray): boolean {
+    for (let i = 3; i < a.length; i += 4) if (a[i] !== b[i]) return false;
+    return true;
+  }
+  function empty(a: Uint8ClampedArray): boolean {
+    for (let i = 3; i < a.length; i += 4) if (a[i] > 16) return false;
+    return true;
+  }
+  function splitFont(font: string) {
+    const m = /^(.*?)(\d+(?:\.\d+)?)px(?:\/\S+)?\s+(.+)$/.exec(font.trim());
+    if (!m) return null;
+    const families = m[3];
+    const primary = (families.match(/^\s*("[^"]+"|'[^']+'|[^,]+)/)?.[1] || "").trim();
+    return { pre: m[1], families, primary };
+  }
+
+  // 글꼴마다 글자마다: ok · stack(스택에 적힌 다음 글꼴이 그림) · fallback(시스템 글꼴로 넘어감) · missing-font(첫 글꼴이 안 불러와짐) · tofu(어떤 글꼴에도 없음) · blank(빈 글리프)
+  async function glyphs(pairs: [string, string][]): Promise<Record<string, string>> {
+    const out: Record<string, string> = {};
+    if (!pctx) return out;
+    const fonts = [...new Set(pairs.map((p) => p[0]))];
+    for (const f of fonts) {
+      const chars = pairs.filter((p) => p[0] === f).map((p) => p[1]).join("");
+      try { await document.fonts.load(f, chars); } catch {}
+    }
+    const lr = ink("40px LastResort", "A");
+    const lastResortUsable = !same(lr, ink("40px serif", "A")) && !same(lr, ink("40px sans-serif", "A"));
+    for (const [f, ch] of pairs) {
+      const key = f + "\u0000" + ch;
+      const sp = splitFont(f);
+      if (!sp) { out[key] = "ok"; continue; }
+      const full = `${sp.pre}40px ${sp.families}`;
+      const got = ink(full, ch);
+      if (empty(got)) { out[key] = "blank"; continue; }
+      if (same(got, ink(full, "\u{10FFFD}")) || (lastResortUsable && same(got, ink("40px LastResort", ch)))) {
+        out[key] = "tofu";
+        continue;
+      }
+      const primary = sp.primary.replace(/^["']|["']$/g, "");
+      if (GENERIC.test(primary)) { out[key] = "ok"; continue; }
+      if (covers(sp.pre, sp.primary, ch)) { out[key] = "ok"; continue; }
+      if (!loaded(sp.pre, sp.primary)) { out[key] = "missing-font"; continue; }
+      // 모노 글꼴 뒤에 한글 글꼴을 일부러 적어 두는 스택이 흔하다 — 그 글꼴이 실제로 그렸으면 괜찮다.
+      out[key] = "fallback";
+      for (const fam of splitFamilies(sp.families).slice(1)) {
+        // ui-monospace 처럼 스택 가운데 낀 일반 이름은 건너뛰고 뒤에 적힌 글꼴을 본다.
+        if (GENERIC.test(fam.replace(/^["']|["']$/g, ""))) continue;
+        if (!covers(sp.pre, fam, ch)) continue;
+        if (same(got, ink(`${sp.pre}40px ${fam}, serif`, ch))) out[key] = "stack";
+        break;
+      }
+    }
+    return out;
+  }
+  function covers(pre: string, family: string, ch: string): boolean {
+    return same(ink(`${pre}40px ${family}, serif`, ch), ink(`${pre}40px ${family}, monospace`, ch));
+  }
+  const loadedCache = new Map<string, boolean>();
+  function loaded(pre: string, family: string): boolean {
+    const k = pre + family;
+    let v = loadedCache.get(k);
+    if (v === undefined) loadedCache.set(k, (v = covers(pre, family, "a") || covers(pre, family, "0")));
+    return v;
+  }
+  function splitFamilies(families: string): string[] {
+    return (families.match(/"[^"]+"|'[^']+'|[^,]+/g) || []).map((x) => x.trim()).filter(Boolean);
+  }
+
+  // 카메라 층 = 화면의 30% 넘게 덮고 글을 품은 층 중 transform 이 걸린 것. 글 없는 큰 층(바탕 흐름·모눈)은 카메라로 치지 않는다.
+  // 열쇠는 장면 뿌리에서 자식 번호로 내려간 길 — 탭이 달라도 같은 층이 같은 열쇠가 된다.
+  const textInside = new WeakMap<Element, boolean>();
+  function hasText(el: Element): boolean {
+    if (textInside.get(el)) return true;
+    const tw = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+    for (let n = tw.nextNode(); n; n = tw.nextNode()) {
+      if ((n.nodeValue || "").trim()) {
+        textInside.set(el, true);
+        return true;
+      }
+    }
+    return false;
+  }
+  function camera() {
+    const root = document.getElementById("stage") || document.body;
+    const area = innerWidth * innerHeight;
+    const layers: any[] = [];
+    const walk = (el: Element, path: string, scene: string | null, depth: number) => {
+      Array.from(el.children).forEach((c, i) => {
+        if (!(c instanceof HTMLElement) || c.offsetWidth * c.offsetHeight < area * 0.3) return;
+        const cs = getComputedStyle(c);
+        if (cs.visibility === "hidden" || parseFloat(cs.opacity || "1") < 0.05) return;
+        const sc = c.getAttribute("data-kf-scene") ?? scene;
+        const key = `${path}/${i}`;
+        if (cs.transform && cs.transform !== "none" && hasText(c)) {
+          const m = new DOMMatrixReadOnly(cs.transform);
+          layers.push({ key, scene: sc, sel: selector(c), a: m.a, b: m.b, e: m.e, f: m.f, flat: m.is2D });
+        }
+        if (depth < 8) walk(c, key, sc, depth + 1);
+      });
+    };
+    walk(root, "", null, 0);
+    // 주인공 — 장면이 data-kf-hero 로 짚은 요소(무대의 bigWord 가 단다). 없으면 검사가 가장 큰 글을 주인공으로 본다
+    const heroes: any[] = [];
+    for (const el of Array.from(root.querySelectorAll("[data-kf-hero]"))) {
+      if ((el as any).checkVisibility && !(el as any).checkVisibility({ opacityProperty: true, visibilityProperty: true })) continue;
+      const b = el.getBoundingClientRect();
+      if (b.width < 1 || b.height < 1) continue;
+      heroes.push({ scene: el.closest("[data-kf-scene]")?.getAttribute("data-kf-scene") ?? null, sel: selector(el), box: { x0: b.left, y0: b.top, x1: b.right, y1: b.bottom } });
+    }
+    return { layers, heroes };
+  }
+
+  w.__kfCheck = {
+    take(): any[] {
+      const all = hits.splice(0, hits.length).concat(domHits());
+      rects.clear();
+      return all;
+    },
+    camera,
+    clear() {
+      hits.length = 0;
+      rects.clear();
+    },
+    glyphs,
+  };
+}
+
+// 옛 방식(window.seek(t) 하나만 있는 페이지)을 페이지 계약 꼴로 감싼다.
+// 계약을 따르는 페이지면 아무것도 하지 않는다.
+export function legacyShim(o: { fps: number; duration: number }): string {
+  const w = window as any;
+  if (w.__kf) return "kf";
+  const seek = typeof w.seek === "function" ? w.seek : typeof w.__setTime === "function" ? w.__setTime : null;
+  if (!seek) return "none";
+  const stage = document.getElementById("stage") || document.querySelector("canvas") || document.body;
+  const r = stage.getBoundingClientRect();
+  const dur = o.duration || w.T?.dur || w.DURATION || 0;
+  w.__kf = {
+    meta: { fps: o.fps, width: Math.round(r.width) || innerWidth, height: Math.round(r.height) || innerHeight, duration: dur },
+    mode: "seek",
+    legacy: true,
+    async ready() {
+      const t0 = performance.now();
+      while ("__ready" in w && w.__ready !== true && performance.now() - t0 < 30000) await new Promise((res) => setTimeout(res, 50));
+      await document.fonts.ready;
+    },
+    // 옛 seek 는 동기로 다 그린다. 스크린샷은 어차피 새 프레임을 기다린다.
+    async seek(t: number) {
+      seek(t);
+    },
+  };
+  return "legacy";
+}

package/packages/check/src/report.ts

@@ -0,0 +1,44 @@
+import type { Finding, Report } from "./types.ts";
+
+const sec = (t: number) => t.toFixed(2);
+
+function span(f: Finding): string {
+  return Math.abs(f.to - f.from) < 0.0005 ? `${sec(f.from)}초` : `${sec(f.from)}–${sec(f.to)}초`;
+}
+
+// 그림을 못 보는 모델도 이것만 읽고 고칠 수 있게: 무엇이·언제·어디서·어떻게 고치나를 한 덩어리로.
+export function formatReport(r: Report, o: { maxPerRule?: number } = {}): string {
+  const max = o.maxPerRule ?? 8;
+  const kind = r.kind === "page" ? "페이지" : "영상 파일";
+  const lines: string[] = [];
+  lines.push(`kf check — ${r.target}`);
+  lines.push(`${kind} · ${sec(r.meta.duration)}초 · ${r.meta.width}×${r.meta.height} · ${Math.round(r.meta.fps * 100) / 100}fps · 프레임 ${r.sampled.frames}장 훑음 · ${r.elapsedSec.toFixed(1)}초 걸림`);
+  lines.push("");
+  lines.push(`오류 ${r.counts.error} · 경고 ${r.counts.warn}`);
+
+  const byRule = new Map<string, Finding[]>();
+  for (const f of r.findings) {
+    const key = `${f.severity}\u0000${f.rule}`;
+    if (!byRule.has(key)) byRule.set(key, []);
+    byRule.get(key)!.push(f);
+  }
+  for (const [key, list] of byRule) {
+    const [severity, rule] = key.split("\u0000");
+    lines.push("");
+    lines.push(`[${severity === "error" ? "오류" : "경고"}] ${rule} — ${list.length}건`);
+    for (const f of list.slice(0, max)) {
+      lines.push(`  ${span(f)}  ${f.message}`);
+      const where = f.detail?.where;
+      if (typeof where === "string" && where) lines.push(`    자리: ${where}`);
+    }
+    if (list.length > max) lines.push(`  … 외 ${list.length - max}건 (JSON 에 다 있다)`);
+  }
+  if (r.skipped.length) {
+    lines.push("");
+    lines.push("못 본 것:");
+    for (const s of r.skipped) lines.push(`  - ${s}`);
+  }
+  lines.push("");
+  lines.push(r.ok ? `결과: 통과${r.counts.warn ? ` (경고 ${r.counts.warn})` : ""}` : `결과: 실패 — 오류 ${r.counts.error}건을 고치고 다시 kf check`);
+  return lines.join("\n");
+}

package/packages/check/src/rules/assets.ts

@@ -0,0 +1,42 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Finding } from "../types.ts";
+
+const NOTE: Record<string, string> = {
+  "alpha-failed": "투명 배경을 못 받아 단색 바탕을 키잉했다 — 가장자리 번짐을 본다",
+  "refs-ignored": "참고 그림(refs)을 모델이 안 받았다 — 모양이 브리프와 다를 수 있다",
+};
+
+// 생성 담당이 assets/gen/<id>.json 에 남긴 출처 기록. 밖에 내는 결과물이면 지역·라이선스 제한을 먼저 본다.
+export function genAssets(projectDir: string): Finding[] {
+  const dir = join(projectDir, "assets", "gen");
+  if (!existsSync(dir)) return [];
+  const out: Finding[] = [];
+  for (const f of readdirSync(dir).filter((x) => x.endsWith(".json")).sort()) {
+    let meta: any;
+    try {
+      meta = JSON.parse(readFileSync(join(dir, f), "utf8"));
+    } catch {
+      continue;
+    }
+    const id = meta.id ?? f.replace(/\.json$/, "");
+    const license = String(meta.license ?? "");
+    const region = String(meta.region ?? "");
+    if (region || /제한|비상업|non-?commercial|restrict/i.test(license)) {
+      out.push({
+        rule: "asset.license",
+        severity: "warn",
+        from: 0,
+        to: 0,
+        message: `생성 자산 ${id} — 라이선스 「${license || "?"}」${region ? ` · 지역 「${region}」` : ""} — 밖에 내기 전에 확인한다`,
+        detail: { file: join("assets", "gen", f), provider: meta.provider, model: meta.model },
+      });
+    }
+    for (const n of (meta.notes ?? []) as string[]) {
+      const key = Object.keys(NOTE).find((k) => n.startsWith(k));
+      if (!key) continue;
+      out.push({ rule: "asset.note", severity: "warn", from: 0, to: 0, message: `생성 자산 ${id} — ${NOTE[key]}`, detail: { file: join("assets", "gen", f), note: n } });
+    }
+  }
+  return out;
+}

package/packages/check/src/rules/beats.ts

@@ -0,0 +1,212 @@
+import type { Beats, Finding, MotionEvent, MotionRules } from "../types.ts";
+import { runs, type Run } from "./runs.ts";
+
+function nearest(list: number[], t: number): number | undefined {
+  let best: number | undefined;
+  for (const x of list) if (best === undefined || Math.abs(x - t) < Math.abs(best - t)) best = x;
+  return best;
+}
+
+const ms = (s: number) => `${Math.round(s * 1000)}ms`;
+
+// 장면 경계는 박 위에, 드롭 근처면 드롭 위에. 한 프레임까지는 반올림 차로 본다.
+export function boundaries(times: number[], beats: Beats, o: { fps: number; duration: number; source: "scene" | "cut" }): Finding[] {
+  const tol = 1 / o.fps + 0.004;
+  const out: Finding[] = [];
+  const drops = beats.drops ?? [];
+  for (const t of times) {
+    if (t <= tol || t >= o.duration - tol) continue;
+    const drop = nearest(drops, t);
+    if (drop !== undefined && Math.abs(drop - t) > tol && Math.abs(drop - t) < 0.6) {
+      out.push({
+        rule: "beat.boundary-drop",
+        severity: "warn",
+        from: t,
+        to: t,
+        message: `${o.source === "scene" ? "장면 경계" : "컷"} ${t.toFixed(3)}초가 드롭 ${drop.toFixed(3)}초에서 ${ms(t - drop)} 어긋났다 — 드롭에 붙인다`,
+        detail: { at: t, drop, offsetMs: Math.round((t - drop) * 1000) },
+      });
+      continue;
+    }
+    const beat = nearest(beats.beats, t);
+    if (beat === undefined || Math.abs(beat - t) <= tol) continue;
+    // 컷은 장면 안 연출(섬광·글자 교체)도 잡히니 박 사이 한가운데쯤 떨어진 것만 말한다.
+    if (o.source === "cut" && Math.abs(beat - t) < 0.06) continue;
+    out.push({
+      rule: "beat.boundary",
+      severity: "warn",
+      from: t,
+      to: t,
+      message: `${o.source === "scene" ? "장면 경계" : "컷"} ${t.toFixed(3)}초가 박 ${beat.toFixed(3)}초에서 ${ms(t - beat)} 어긋났다`,
+      detail: { at: t, beat, offsetMs: Math.round((t - beat) * 1000) },
+    });
+  }
+  return out;
+}
+
+interface Window {
+  from: number;
+  to: number;
+}
+
+function dropWindows(beats: Beats, duration: number): Window[] {
+  const sections = [...(beats.sections ?? [])].sort((a, b) => a.t - b.t);
+  const out: Window[] = [];
+  sections.forEach((s, i) => {
+    if (s.kind === "drop") out.push({ from: s.t, to: sections[i + 1]?.t ?? duration });
+  });
+  const phrases = beats.phrases ?? [];
+  for (const d of beats.drops ?? []) {
+    if (out.some((w) => d >= w.from - 0.05 && d < w.to)) continue;
+    const next = phrases.find((p) => p > d + 0.05);
+    out.push({ from: d, to: next ?? Math.min(duration, d + 4) });
+  }
+  return out;
+}
+
+function phraseOf(phrases: number[], t: number): number {
+  let k = -1;
+  for (let i = 0; i < phrases.length; i++) if (phrases[i] <= t + 0.001) k = i;
+  return k;
+}
+
+function inside(ws: Window[], t: number, slack = 0.05): boolean {
+  return ws.some((w) => t >= w.from - slack && t < w.to);
+}
+
+function occurrences(events: MotionEvent[], kind: MotionEvent["kind"], fps: number): (Run & { max: number; sources: string[] })[] {
+  const list = events.filter((e) => e.kind === kind);
+  return runs(
+    list.map((e) => e.t),
+    1.5 / fps,
+  ).map((r) => {
+    const inRun = list.filter((e) => e.t >= r.from - 1e-6 && e.t <= r.to + 1e-6);
+    return { ...r, max: Math.max(...inRun.map((e) => Math.abs(e.value))), sources: [...new Set(inRun.map((e) => e.source))] };
+  });
+}
+
+// style.json motion 규칙을 페이지가 남긴 window.__kf.events 로 센다. 연속 프레임 묶음 = 한 번.
+export function motionRules(events: MotionEvent[], beats: Beats | null, rules: MotionRules, o: { fps: number; duration: number }): Finding[] {
+  const out: Finding[] = [];
+  const drops = beats ? dropWindows(beats, o.duration) : [];
+  const phrases = beats?.phrases?.length ? beats.phrases : [];
+  const end = (r: Run) => r.to + 1 / o.fps;
+
+  const pulse = rules.beatPulse;
+  if (pulse === "off" || pulse === "drops-only" || pulse === "downbeats") {
+    for (const r of occurrences(events, "pulse", o.fps)) {
+      let bad = pulse === "off";
+      if (pulse === "drops-only") bad = !inside(drops, r.from);
+      if (pulse === "downbeats") {
+        const db = nearest(beats?.downbeats ?? beats?.bars ?? [], r.from);
+        bad = db === undefined || Math.abs(db - r.from) > 2 / o.fps;
+      }
+      if (!bad) continue;
+      out.push({
+        rule: "motion.beat-pulse",
+        severity: "error",
+        from: r.from,
+        to: end(r),
+        message: `박 펄스가 규칙(beatPulse: ${pulse}) 밖에서 뛴다 — ${r.sources.join(", ")}`,
+        detail: { sources: r.sources, max: r.max },
+      });
+    }
+  }
+
+  const shake = rules.shake;
+  if (shake) {
+    const occ = occurrences(events, "shake", o.fps);
+    const perPhrase = new Map<number, typeof occ>();
+    for (const r of occ) {
+      if (shake.maxPx !== undefined && r.max > shake.maxPx + 0.5) {
+        out.push({
+          rule: "motion.shake-px",
+          severity: "error",
+          from: r.from,
+          to: end(r),
+          message: `흔들림 ${r.max.toFixed(1)}px — 상한 ${shake.maxPx}px 넘음 (${r.sources.join(", ")})`,
+          detail: { max: r.max, sources: r.sources },
+        });
+      }
+      const on = shake.on ?? [];
+      if (on.length && !on.includes("impact" as never) && on.includes("drop" as never) && beats && !inside(drops, r.from)) {
+        out.push({
+          rule: "motion.shake-where",
+          severity: "error",
+          from: r.from,
+          to: end(r),
+          message: `드롭이 아닌 곳에서 흔들린다 (shake.on: ${on.join(",")}) — ${r.sources.join(", ")}`,
+          detail: { sources: r.sources },
+        });
+      }
+      const k = phraseOf(phrases, r.from);
+      if (!perPhrase.has(k)) perPhrase.set(k, []);
+      perPhrase.get(k)!.push(r);
+    }
+    if (shake.maxPerPhrase !== undefined && phrases.length) {
+      for (const [k, list] of perPhrase) {
+        if (list.length <= shake.maxPerPhrase) continue;
+        out.push({
+          rule: "motion.shake-count",
+          severity: "error",
+          from: list[0].from,
+          to: end(list[list.length - 1]),
+          message: `한 프레이즈(${(phrases[k] ?? 0).toFixed(2)}초~)에서 ${list.length}번 흔들린다 — 최대 ${shake.maxPerPhrase}번`,
+          detail: { phrase: phrases[k], times: list.map((r) => Math.round(r.from * 1000) / 1000) },
+        });
+      }
+    }
+  }
+
+  const cam = rules.cameraMove;
+  if (cam === "off" || cam === "once-per-phrase") {
+    const occ = occurrences(events, "camera", o.fps);
+    if (cam === "off") {
+      for (const r of occ)
+        out.push({ rule: "motion.camera", severity: "error", from: r.from, to: end(r), message: `카메라가 움직인다 (cameraMove: off) — ${r.sources.join(", ")}` });
+    } else if (phrases.length) {
+      const per = new Map<number, typeof occ>();
+      for (const r of occ) {
+        const k = phraseOf(phrases, r.from);
+        if (!per.has(k)) per.set(k, []);
+        per.get(k)!.push(r);
+      }
+      for (const [k, list] of per) {
+        if (list.length <= 1) continue;
+        out.push({
+          rule: "motion.camera",
+          severity: "error",
+          from: list[0].from,
+          to: end(list[list.length - 1]),
+          message: `한 프레이즈(${(phrases[k] ?? 0).toFixed(2)}초~)에서 카메라가 ${list.length}번 움직인다 — 프레이즈당 한 번`,
+          detail: { phrase: phrases[k], moves: list.map((r) => ({ t: Math.round(r.from * 1000) / 1000, sources: r.sources })) },
+        });
+      }
+    }
+  }
+
+  if (rules.repeatSameMove === false) {
+    // 장면마다 처음 나온 enter: 움직임이 그 장면의 등장이다.
+    const first = new Map<string, { t: number; name: string }>();
+    for (const e of events) {
+      if (e.kind !== "move" || !e.scene || !e.name?.startsWith("enter:")) continue;
+      const cur = first.get(e.scene);
+      if (!cur || e.t < cur.t) first.set(e.scene, { t: e.t, name: e.name });
+    }
+    const order = [...first.entries()].sort((a, b) => a[1].t - b[1].t);
+    for (let i = 1; i < order.length; i++) {
+      const [pa, a] = order[i - 1];
+      const [pb, b] = order[i];
+      if (a.name !== b.name) continue;
+      out.push({
+        rule: "motion.repeat",
+        severity: "warn",
+        from: b.t,
+        to: b.t,
+        message: `이어지는 두 장면(${pa} → ${pb})이 같은 등장 움직임 ${b.name} 을 쓴다 (repeatSameMove: false)`,
+        detail: { scenes: [pa, pb], name: b.name },
+      });
+    }
+  }
+  return out;
+}