kasaframe 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,257 @@
+import type { Thumb } from "../image.ts";
+import type { Finding, SafeArea } from "../types.ts";
+
+// 멈춤·빈 화면 검사를 다 통과하고도 「화면이 비었다」가 나온다 — 9:16 에 그림·글이 가운데 20% 만 차지하거나,
+// 흐르는 바탕 위에 같은 구도가 9초씩 가는 경우. 둘 다 엄지만 한 썸네일(160px 회색조)로 잰다.
+
+export interface SceneSpan {
+  id: string;
+  from: number;
+  dur: number;
+}
+
+interface Thumbish extends Thumb {
+  width?: number;
+  height?: number;
+}
+
+const THUMB_W = 160;
+
+function dims(t: Thumbish, aspect: number): { w: number; h: number } {
+  const w = t.width ?? THUMB_W;
+  return { w, h: t.height ?? (Math.round(t.luma.length / w) || Math.round(w / aspect)) };
+}
+
+// 가장 흔한 밝기(±3)를 바탕으로 본다 — 생성 그림처럼 바탕이 고르지 않으면 바탕 몫이 작아 「꽉 참」으로 나온다
+function background(l: Uint8Array): { value: number; share: number } {
+  const hist = new Uint32Array(256);
+  for (const v of l) hist[v]++;
+  let best = 0;
+  let value = 0;
+  for (let v = 0; v < 256; v++) {
+    let n = 0;
+    for (let d = -3; d <= 3; d++) n += hist[v + d] ?? 0;
+    if (n > best) {
+      best = n;
+      value = v;
+    }
+  }
+  return { value, share: best / l.length };
+}
+
+// 내용 상자 — 바탕과 다른 픽셀의 가로·세로 분포에서 양 끝 3% 씩 떼어 낸 범위(구석의 작은 로고 하나가 상자를 키우지 않게)
+export function contentBox(l: Uint8Array, w: number, h: number, safe: { x0: number; y0: number; x1: number; y1: number }): { wFrac: number; hFrac: number; area: number } {
+  const bg = background(l);
+  if (bg.share < 0.45) return { wFrac: 1, hFrac: 1, area: 1 };
+  const cols = new Float64Array(w);
+  const rows = new Float64Array(h);
+  let total = 0;
+  for (let y = safe.y0; y < safe.y1; y++) {
+    for (let x = safe.x0; x < safe.x1; x++) {
+      if (Math.abs(l[y * w + x] - bg.value) > 14) {
+        cols[x]++;
+        rows[y]++;
+        total++;
+      }
+    }
+  }
+  const sw = safe.x1 - safe.x0;
+  const sh = safe.y1 - safe.y0;
+  if (total < 4) return { wFrac: 0, hFrac: 0, area: 0 };
+  const span = (arr: Float64Array, lo: number, hi: number) => {
+    let acc = 0;
+    let a = lo;
+    while (a < hi && acc + arr[a] <= total * 0.03) acc += arr[a++];
+    acc = 0;
+    let b = hi - 1;
+    while (b > a && acc + arr[b] <= total * 0.03) acc += arr[b--];
+    return b - a + 1;
+  };
+  const wFrac = span(cols, safe.x0, safe.x1) / sw;
+  const hFrac = span(rows, safe.y0, safe.y1) / sh;
+  return { wFrac, hFrac, area: wFrac * hFrac };
+}
+
+export interface FillOptions {
+  width: number;
+  height: number;
+  safe?: SafeArea;
+  // 세로 화면은 주 요소가 안전 영역 폭의 이만큼은 차야 한다
+  minWidthVertical?: number;
+  minArea?: number;
+}
+
+// 시작이 t 이하인 마지막 장면 — kf.json 시각은 넷째 자리에서 반올림돼 경계에 0.0001초 틈이 날 수 있다
+function sceneOf(t: number, scenes: SceneSpan[]): SceneSpan | undefined {
+  let hit: SceneSpan | undefined;
+  for (const s of scenes) if (s.from <= t + 1e-3) hit = s;
+  return hit;
+}
+
+function median(xs: number[]): number {
+  const s = [...xs].sort((a, b) => a - b);
+  return s.length ? s[Math.floor(s.length / 2)] : 0;
+}
+
+// 화면 채움 — 장면마다 내용 상자의 가운데값. 세로 화면은 폭 70% 아래면 경고, 넓이 12% 아래면 오류
+export function fill(thumbs: Thumbish[], scenes: SceneSpan[], o: FillOptions): Finding[] {
+  if (!thumbs.length) return [];
+  const aspect = o.width / o.height;
+  const vertical = o.height > o.width;
+  const minW = o.minWidthVertical ?? 0.7;
+  const minArea = o.minArea ?? 0.12;
+  const groups = new Map<string, { span: SceneSpan; w: number[]; a: number[] }>();
+  for (const t of thumbs) {
+    const s = sceneOf(t.t, scenes) ?? { id: "영상", from: 0, dur: Infinity };
+    const { w, h } = dims(t, aspect);
+    const k = w / o.width;
+    const sa = o.safe ?? { top: 0, bottom: 0, left: 0, right: 0 };
+    const box = contentBox(t.luma, w, h, {
+      x0: Math.max(0, Math.round(sa.left * k)),
+      y0: Math.max(0, Math.round(sa.top * k)),
+      x1: Math.min(w, w - Math.round(sa.right * k)),
+      y1: Math.min(h, h - Math.round(sa.bottom * k)),
+    });
+    const g = groups.get(s.id) ?? { span: s, w: [], a: [] };
+    g.w.push(box.wFrac);
+    g.a.push(box.area);
+    groups.set(s.id, g);
+  }
+  const out: Finding[] = [];
+  for (const { span, w, a } of groups.values()) {
+    const mw = median(w);
+    const ma = median(a);
+    const to = Number.isFinite(span.dur) ? span.from + span.dur : thumbs.at(-1)!.t;
+    if (ma < minArea) {
+      out.push({
+        rule: "layout.fill",
+        severity: "error",
+        from: span.from,
+        to,
+        message: `장면 ${span.id} 의 내용이 안전 영역의 ${(ma * 100).toFixed(0)}% 만 차지한다 — 화면이 비어 보인다. 주 요소를 키우거나(큰 글자 단계·도식 확대) 화면을 채우는 바탕·요소를 더한다`,
+        detail: { scene: span.id, area: Math.round(ma * 1000) / 1000, width: Math.round(mw * 1000) / 1000 },
+      });
+    } else if (vertical && mw < minW) {
+      out.push({
+        rule: "layout.fill",
+        severity: "warn",
+        from: span.from,
+        to,
+        message: `장면 ${span.id} 의 주 요소 폭이 안전 영역의 ${(mw * 100).toFixed(0)}% — 세로 화면은 ${Math.round(minW * 100)}% 넘게 채운다`,
+        detail: { scene: span.id, area: Math.round(ma * 1000) / 1000, width: Math.round(mw * 1000) / 1000 },
+      });
+    }
+  }
+  return out;
+}
+
+// 구도 — 썸네일을 16×N 칸으로 줄인 평균 밝기. 흐르는 점무늬처럼 잔 움직임은 칸 평균에 묻히고, 카메라·확대·새 요소는 칸을 바꾼다
+function layoutSig(t: Thumbish, aspect: number, cols = 16): Float32Array {
+  const { w, h } = dims(t, aspect);
+  const rows = Math.max(4, Math.round((cols * h) / w));
+  const sig = new Float32Array(cols * rows);
+  const cnt = new Uint32Array(cols * rows);
+  for (let y = 0; y < h; y++) {
+    const r = Math.min(rows - 1, Math.floor((y * rows) / h));
+    for (let x = 0; x < w; x++) {
+      const c = Math.min(cols - 1, Math.floor((x * cols) / w));
+      sig[r * cols + c] += t.luma[y * w + x];
+      cnt[r * cols + c]++;
+    }
+  }
+  for (let i = 0; i < sig.length; i++) sig[i] /= cnt[i] || 1;
+  return sig;
+}
+
+function sigDiff(a: Float32Array, b: Float32Array): number {
+  let s = 0;
+  for (let i = 0; i < a.length; i++) s += Math.abs(a[i] - b[i]);
+  return s / a.length;
+}
+
+// 화면 안 내용 — 칸마다 센 가장자리(이웃 픽셀 밝기 차 합이 24 넘는 픽셀) 수와 평균 밝기. 숫자가 구르고 칸이 차고 줄이 붙으면 이 지도가 바뀐다.
+// 칸 평균 밝기만 보면 이런 변화가 묻혀 모델이 카메라 샷을 박아 넘겼다. 빛 방울·모눈처럼 부드럽거나 가는 바탕 흐름은 센 가장자리를 거의 안 만든다
+interface ContentSig {
+  edges: Uint16Array;
+  mean: Float32Array;
+}
+
+export function contentSig(t: Thumbish, aspect: number, cols = 32): ContentSig {
+  const { w, h } = dims(t, aspect);
+  const rows = Math.max(4, Math.round((cols * h) / w));
+  const edges = new Uint16Array(cols * rows);
+  const mean = new Float32Array(cols * rows);
+  const cnt = new Uint16Array(cols * rows);
+  const l = t.luma;
+  for (let y = 0; y < h; y++) {
+    const r = Math.min(rows - 1, Math.floor((y * rows) / h));
+    for (let x = 0; x < w; x++) {
+      const k = r * cols + Math.min(cols - 1, Math.floor((x * cols) / w));
+      const i = y * w + x;
+      mean[k] += l[i];
+      cnt[k]++;
+      if (x < w - 1 && y < h - 1 && Math.abs(l[i] - l[i + 1]) + Math.abs(l[i] - l[i + w]) > 24) edges[k]++;
+    }
+  }
+  for (let k = 0; k < mean.length; k++) mean[k] /= cnt[k] || 1;
+  return { edges, mean };
+}
+
+// 바뀐 칸의 몫 — 가장자리 수가 3 넘게 달라졌거나, 가장자리가 있는 칸(글·칸·막대)의 밝기가 20 넘게 달라졌다(회색 칸이 검게 차는 것).
+// 가장자리 없는 칸의 밝기 변화(부드러운 바탕 흐름)는 세지 않는다
+export function contentChange(a: ContentSig, b: ContentSig): number {
+  let n = 0;
+  for (let i = 0; i < a.edges.length; i++) {
+    if (Math.abs(a.edges[i] - b.edges[i]) > 3 || ((a.edges[i] > 3 || b.edges[i] > 3) && Math.abs(a.mean[i] - b.mean[i]) > 20)) n++;
+  }
+  return n / a.edges.length;
+}
+
+export interface StaticOptions {
+  width: number;
+  height: number;
+  warnSec?: number;
+  errorSec?: number;
+  // 칸 평균 밝기 차(0..255). 이보다 덜 바뀌고
+  threshold?: number;
+  // 화면 안 내용이 바뀐 칸의 몫도 이보다 작으면 같은 구도로 본다
+  contentThreshold?: number;
+}
+
+// 장면 안 변화량 — 같은 구도가 1.5초 넘게 가면 경고, 3초 넘으면 오류. 칸 평균 밝기(컷·확대·새 면)와 화면 안 내용(숫자·칸·줄)
+// 둘 다 닻 프레임에서 안 바뀌어야 같은 구도다 — 카메라 컷 없이도 내용이 움직이면 넘는다. 카메라로 메우면 camera.wander
+export function staticLayout(thumbs: Thumbish[], scenes: SceneSpan[], o: StaticOptions): Finding[] {
+  const aspect = o.width / o.height;
+  const warnSec = o.warnSec ?? 1.5;
+  const errorSec = o.errorSec ?? 3;
+  const thr = o.threshold ?? 2.5;
+  const cthr = o.contentThreshold ?? 0.015;
+  const out: Finding[] = [];
+  const spans = scenes.length ? scenes : [{ id: "영상", from: 0, dur: Infinity }];
+  for (const s of spans) {
+    const ts = thumbs.filter((t) => sceneOf(t.t, spans) === s);
+    if (ts.length < 2) continue;
+    const sigs = ts.map((t) => layoutSig(t, aspect));
+    const content = ts.map((t) => contentSig(t, aspect));
+    let a = 0;
+    while (a < ts.length - 1) {
+      let j = a + 1;
+      while (j < ts.length && sigDiff(sigs[a], sigs[j]) < thr && contentChange(content[a], content[j]) < cthr) j++;
+      const end = j - 1;
+      const len = ts[end].t - ts[a].t;
+      if (len > warnSec + 1e-6) {
+        const severity = len > errorSec + 1e-6 ? "error" : "warn";
+        out.push({
+          rule: "layout.static",
+          severity,
+          from: ts[a].t,
+          to: ts[end].t,
+          message: `장면 ${s.id} 에서 같은 구도가 ${len.toFixed(1)}초 간다 — ${warnSec}초 안에 새 요소·칸 채우기·숫자 키우기·컷·전환으로 구도를 바꾼다(카메라를 이유 없이 옮겨 메우지 않는다)`,
+          detail: { scene: s.id, seconds: Math.round(len * 10) / 10 },
+        });
+      }
+      a = Math.max(end, a + 1);
+    }
+  }
+  return out;
+}

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

@@ -0,0 +1,87 @@
+import type { ContrastSample, RepeatSample } from "../scan.ts";
+import type { Finding } from "../types.ts";
+import { roundBox } from "./text.ts";
+import { runs } from "./runs.ts";
+
+// 페이드 중인 글은 낮은 대비가 당연하다. 같은 글이 minSec 넘게 낮은 대비로 머물 때만 말한다.
+// 장식으로 흐리게 깐 작은 글은 일부러일 수 있어 경고에 그친다. 읽으라고 크게 쓴 글이 거의 안 보이면 오류.
+export function contrast(samples: ContrastSample[], o: { shotFps: number; minSec?: number; warnBelow?: number; errorBelow?: number; errorMinPx?: number }): Finding[] {
+  const minSec = o.minSec ?? 0.9;
+  const warnBelow = o.warnBelow ?? 3;
+  const errorBelow = o.errorBelow ?? 1.5;
+  const errorMinPx = o.errorMinPx ?? 24;
+  const byText = new Map<string, ContrastSample[]>();
+  for (const s of samples) {
+    if (s.ratio >= warnBelow) continue;
+    const key = s.text;
+    if (!byText.has(key)) byText.set(key, []);
+    byText.get(key)!.push(s);
+  }
+  const each: { from: number; to: number; text: string; worst: ContrastSample; severe: boolean }[] = [];
+  for (const [text, list] of byText) {
+    for (const r of runs(list.map((s) => s.t), 1.5 / o.shotFps)) {
+      if (r.to - r.from + 1 / o.shotFps < minSec) continue;
+      const inRun = list.filter((s) => s.t >= r.from && s.t <= r.to);
+      const worst = inRun.reduce((a, b) => (b.ratio < a.ratio ? b : a));
+      each.push({ from: r.from, to: r.to + 1 / o.shotFps, text, worst, severe: worst.ratio < errorBelow && worst.sizePx >= errorMinPx });
+    }
+  }
+  // 한 화면에 흐린 글이 여럿이면 한 줄로 — 고칠 곳은 대개 그 화면의 바탕이나 덮개 하나다.
+  each.sort((a, b) => a.from - b.from);
+  const groups: (typeof each)[] = [];
+  for (const e of each) {
+    const g = groups.find((x) => x[0].severe === e.severe && e.from < Math.max(...x.map((y) => y.to)) && e.to > x[0].from);
+    if (g) g.push(e);
+    else groups.push([e]);
+  }
+  return groups.map((g) => {
+    const worst = g.reduce((a, b) => (b.worst.ratio < a.worst.ratio ? b : a)).worst;
+    const severe = g[0].severe;
+    const names = g.slice(0, 4).map((x) => `"${x.text.trim()}"`).join(" · ");
+    return {
+      rule: "text.contrast",
+      severity: severe ? ("error" as const) : ("warn" as const),
+      from: Math.min(...g.map((x) => x.from)),
+      to: Math.max(...g.map((x) => x.to)),
+      message: `글자 대비가 낮다 — 가장 낮은 ${worst.ratio}:1 (${worst.sizePx}px) · 글 ${g.length}개: ${names}${g.length > 4 ? " …" : ""}${severe ? " — 거의 안 보인다" : " — 바탕과 3:1 이상 벌린다"}`,
+      detail: { ratio: worst.ratio, sizePx: worst.sizePx, box: roundBox(worst.box), texts: g.map((x) => ({ text: x.text, ratio: x.worst.ratio, from: x.from, to: x.to })) },
+    };
+  });
+}
+
+export function repeatable(samples: RepeatSample[]): Finding[] {
+  const bad = samples.filter((s) => s.diff > 0.5 || !s.textSame);
+  return bad.map((s) => ({
+    rule: "frame.nondeterministic",
+    severity: "error" as const,
+    from: s.t,
+    to: s.t,
+    message: `같은 시각을 두 번 그렸더니 달랐다(차 ${s.diff}${s.textSame ? "" : ", 글도 다름"}) — Math.random·Date.now·누적 상태를 t 의 함수로 바꾼다`,
+    detail: { diff: s.diff, textSame: s.textSame },
+  }));
+}
+
+export function pageErrors(errors: { t: number; text: string }[], fps: number): Finding[] {
+  const byText = new Map<string, number[]>();
+  for (const e of errors) {
+    // 시각만 다른 같은 오류(「@7.300」 따위)는 한데 묶는다.
+    const key = e.text.replace(/@?\d+\.\d+/g, "#").slice(0, 300);
+    if (!byText.has(key)) byText.set(key, []);
+    byText.get(key)!.push(e.t);
+  }
+  const out: Finding[] = [];
+  for (const [key, times] of byText) {
+    const first = errors.find((e) => e.text.replace(/@?\d+\.\d+/g, "#").slice(0, 300) === key)!;
+    const valid = times.filter((t) => t >= 0);
+    const rs = valid.length ? runs(valid, 1.5 / fps) : [{ from: 0, to: 0, count: times.length }];
+    out.push({
+      rule: "page.error",
+      severity: "error",
+      from: rs[0].from,
+      to: rs[rs.length - 1].to,
+      message: `페이지 오류 ${times.length}번${valid.length ? "" : "(불러올 때)"} — ${first.text.slice(0, 200)}`,
+      detail: { count: times.length, spans: rs.length },
+    });
+  }
+  return out;
+}

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

@@ -0,0 +1,20 @@
+export interface Run {
+  from: number;
+  to: number;
+  count: number;
+}
+
+// 정렬된 시각들을 maxGap 보다 가까운 것끼리 묶는다 — 「연속 프레임 묶음 = 한 번」.
+export function runs(times: number[], maxGap: number): Run[] {
+  const out: Run[] = [];
+  for (const t of [...times].sort((a, b) => a - b)) {
+    const last = out[out.length - 1];
+    if (last && t - last.to <= maxGap) {
+      last.to = t;
+      last.count++;
+    } else {
+      out.push({ from: t, to: t, count: 1 });
+    }
+  }
+  return out;
+}

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

@@ -0,0 +1,326 @@
+import type { Box, Finding, FrameText, SafeArea, TextHit } from "../types.ts";
+import { runs } from "./runs.ts";
+
+export interface Line {
+  text: string;
+  box?: Box;
+  sizePx: number;
+  alpha: number;
+  hits: TextHit[];
+}
+
+// 터미널 셀 렌더러처럼 글자를 한 자씩 그리는 화면이 많다. 같은 줄에 놓인 조각을 x 순서로 이어 붙여야
+// 「u」「n」「d」… 로 흩어진 undefined 가 한 낱말로 보인다.
+export function assembleLines(hits: TextHit[]): Line[] {
+  const placed = hits.filter((h) => h.box && h.alpha > 0.05);
+  const lines: Line[] = hits.filter((h) => !h.box).map((h) => ({ text: h.text, sizePx: h.sizePx, alpha: h.alpha, hits: [h] }));
+  // 가운데 높이로 묶으면 g·y 처럼 아래로 내려가는 글자가 딴 줄로 빠진다. 세로로 겹치는 정도로 묶는다.
+  const rows: { y0: number; y1: number; hits: TextHit[] }[] = [];
+  const size = (h: TextHit) => Math.max(h.sizePx, 1);
+  for (const h of [...placed].sort((a, b) => a.box!.y0 - b.box!.y0)) {
+    const b = h.box!;
+    const row = rows.find((r) => {
+      const ref = r.hits[0];
+      const overlap = Math.min(r.y1, b.y1) - Math.max(r.y0, b.y0);
+      return h.via === ref.via && !!h.lyrics === !!ref.lyrics && overlap >= 0.5 * Math.min(r.y1 - r.y0, b.y1 - b.y0) && Math.max(size(h), size(ref)) / Math.min(size(h), size(ref)) < 1.35;
+    });
+    if (row) {
+      row.hits.push(h);
+      row.y0 = Math.min(row.y0, b.y0);
+      row.y1 = Math.max(row.y1, b.y1);
+    } else rows.push({ y0: b.y0, y1: b.y1, hits: [h] });
+  }
+  for (const { hits: row } of rows) {
+    row.sort((a, b) => a.box!.x0 - b.box!.x0);
+    let cur: TextHit[] = [row[0]];
+    let text = row[0].text;
+    const flush = () => {
+      const b = cur.map((h) => h.box!);
+      lines.push({
+        text,
+        box: { x0: Math.min(...b.map((x) => x.x0)), y0: Math.min(...b.map((x) => x.y0)), x1: Math.max(...b.map((x) => x.x1)), y1: Math.max(...b.map((x) => x.y1)) },
+        sizePx: Math.max(...cur.map(size)),
+        alpha: Math.max(...cur.map((h) => h.alpha)),
+        hits: cur,
+      });
+    };
+    for (let i = 1; i < row.length; i++) {
+      const prev = cur[cur.length - 1];
+      const h = row[i];
+      const gap = h.box!.x0 - prev.box!.x1;
+      // 다른 덩어리(옆 pane·다른 칸)면 끊는다. 한 칸쯤 벌어졌으면 띄어쓰기로 본다.
+      if (gap > 2.2 * size(prev)) {
+        flush();
+        cur = [h];
+        text = h.text;
+        continue;
+      }
+      text += gap > 0.45 * size(prev) ? " " + h.text : h.text;
+      cur.push(h);
+    }
+    flush();
+  }
+  return lines;
+}
+
+const TOKENS: { name: string; re: RegExp }[] = [
+  { name: "undefined", re: /undefined/ },
+  { name: "NaN", re: /(^|[^A-Za-z])NaN([^A-Za-z]|$)/ },
+  { name: "[object Object]", re: /\[object [A-Za-z]+\]/ },
+  // 터미널 화면의 2>/dev/null 같은 경로는 빼고
+  { name: "null", re: /(^|[^A-Za-z/._-])null([^A-Za-z/._-]|$)/ },
+  { name: "Infinity", re: /(^|[^A-Za-z])-?Infinity([^A-Za-z]|$)/ },
+];
+
+export interface TextRuleOptions {
+  // 코드 화면처럼 일부러 null 을 보이는 영상이면 여기 넣는다(kf.json check.allowText)
+  allow?: string[];
+  fps: number;
+  // OCR 로 읽은 글은 겹친 글자가 뭉개져 「DuHdefined」처럼 나온다. 긴 낱말은 두 글자까지 틀려도 잡는다.
+  fuzzy?: boolean;
+}
+
+function editDistance(a: string, b: string): number {
+  const d = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = d[0];
+    d[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cur = d[j];
+      d[j] = Math.min(d[j] + 1, d[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+      prev = cur;
+    }
+  }
+  return d[b.length];
+}
+
+export function fuzzyHas(text: string, word: string, maxDist: number): boolean {
+  const s = text.toLowerCase().replace(/\s+/g, "");
+  const w = word.toLowerCase();
+  for (let len = w.length - 1; len <= w.length + 1; len++) {
+    for (let i = 0; i + len <= s.length; i++) if (editDistance(s.slice(i, i + len), w) <= maxDist) return true;
+  }
+  return false;
+}
+
+const FUZZY: { name: string; word: string; dist: number }[] = [
+  { name: "undefined", word: "undefined", dist: 2 },
+  { name: "[object Object]", word: "objectobject", dist: 2 },
+];
+
+export function badText(frames: FrameText[], o: TextRuleOptions): Finding[] {
+  const allow = new Set(o.allow ?? []);
+  const hitsAt = new Map<string, { t: number; line: string; where?: string; argType?: string }[]>();
+  for (const f of frames) {
+    const found = new Map<string, { line: string; where?: string; argType?: string }>();
+    for (const h of f.hits) {
+      if (h.argType && h.argType !== "number") {
+        const key = `argType:${h.argType}`;
+        if (!found.has(key)) found.set(key, { line: h.text, where: h.where, argType: h.argType });
+      }
+    }
+    for (const line of assembleLines(f.hits)) {
+      const names = TOKENS.filter((tok) => tok.re.test(line.text)).map((tok) => tok.name);
+      if (o.fuzzy) for (const z of FUZZY) if (!names.includes(z.name) && fuzzyHas(line.text, z.word, z.dist)) names.push(z.name);
+      for (const name of names) {
+        const key = `token:${name}`;
+        if (allow.has(name) || found.has(key)) continue;
+        found.set(key, { line: line.text.slice(0, 120), where: line.hits.find((h) => h.where)?.where });
+      }
+    }
+    for (const [key, v] of found) {
+      if (!hitsAt.has(key)) hitsAt.set(key, []);
+      hitsAt.get(key)!.push({ t: f.t, ...v });
+    }
+  }
+  const out: Finding[] = [];
+  for (const [key, list] of hitsAt) {
+    for (const r of runs(list.map((x) => x.t), 1.5 / o.fps)) {
+      const first = list.find((x) => x.t >= r.from)!;
+      const [kind, name] = key.split(":");
+      out.push({
+        rule: "text.bad",
+        severity: "error",
+        from: r.from,
+        to: r.to + 1 / o.fps,
+        message:
+          kind === "argType"
+            ? `화면 글에 문자열이 아닌 값(${name})이 들어갔다 — "${first.line}"`
+            : `화면 글에 「${name}」 — "${first.line}"`,
+        detail: { line: first.line, where: first.where, frames: r.count },
+      });
+    }
+  }
+  return out;
+}
+
+function primaryFamily(font: string): string {
+  const m = /\d(?:\.\d+)?px(?:\/\S+)?\s+("[^"]+"|'[^']+'|[^,]+)/.exec(font);
+  return (m?.[1] ?? font).trim().replace(/^["']|["']$/g, "");
+}
+
+// 글꼴 크기·굵기만 다른 것은 한 줄로 묶는다 — 고칠 곳은 글꼴 이름 하나다.
+export function glyphProblems(frames: FrameText[], glyphs: Record<string, string>, fps: number): Finding[] {
+  const groups = new Map<string, { status: string; family: string; chars: Set<string>; times: number[] }>();
+  for (const f of frames) {
+    for (const h of f.hits) {
+      for (const ch of new Set(h.text)) {
+        const st = glyphs[h.font + "\u0000" + ch];
+        if (!st || st === "ok" || st === "stack") continue;
+        const status = st === "blank" ? "tofu" : st;
+        const family = primaryFamily(h.font);
+        const key = `${status}\u0000${family}`;
+        let g = groups.get(key);
+        if (!g) groups.set(key, (g = { status, family, chars: new Set(), times: [] }));
+        g.chars.add(ch);
+        if (g.times[g.times.length - 1] !== f.t) g.times.push(f.t);
+      }
+    }
+  }
+  const out: Finding[] = [];
+  for (const g of groups.values()) {
+    const chars = [...g.chars];
+    const shown = chars.slice(0, 24).join("");
+    const span = runs(g.times, 1.5 / fps);
+    const from = span[0]?.from ?? 0;
+    const to = (span[span.length - 1]?.to ?? 0) + 1 / fps;
+    if (g.status === "tofu") {
+      out.push({
+        rule: "text.tofu",
+        severity: "error",
+        from,
+        to,
+        // 두부 글자는 화면에 찍어도 안 보이니 코드 포인트로 알린다.
+        message: `어떤 글꼴에도 없는 글자가 두부(빈 네모)로 나온다 — 글꼴 ${g.family} · ${chars
+          .slice(0, 12)
+          .map((c) => `U+${c.codePointAt(0)!.toString(16).toUpperCase().padStart(4, "0")}`)
+          .join(" ")}`,
+        detail: { family: g.family, chars },
+      });
+      continue;
+    }
+    const latin = g.status === "missing-font";
+    const hangul = chars.some((c) => /[\u3131-\u318E\uAC00-\uD7A3]/.test(c));
+    out.push({
+      rule: "text.fallback",
+      severity: "warn",
+      from,
+      to,
+      message: latin
+        ? `글꼴 「${g.family}」이 안 불러와져 다른 글꼴로 그렸다 — 이름이 틀렸거나 @font-face·글꼴 파일이 없다 (글자 ${chars.length}개)`
+        : `글꼴 「${g.family}」에 없는 글자를 다른 글꼴이 대신 그린다${hangul ? " — 한글이 서는 글꼴을 쓴다" : ""} · 「${shown}」`,
+      detail: { family: g.family, chars, notLoaded: latin },
+    });
+  }
+  return out;
+}
+
+export interface OffscreenOptions {
+  width: number;
+  height: number;
+  fps: number;
+  safe?: SafeArea;
+  minSec?: number;
+}
+
+// 들어오고 나가는 글은 잠깐 걸쳐도 된다. 같은 글이 minSec 넘게 걸쳐 있으면 잘린 채 머무는 것.
+export function offscreenText(frames: FrameText[], o: OffscreenOptions): Finding[] {
+  const minSec = o.minSec ?? 0.5;
+  const pad = 2;
+  const safe = o.safe && (o.safe.top || o.safe.bottom || o.safe.left || o.safe.right) ? o.safe : null;
+  const seen = new Map<string, { kind: "clip" | "safe"; times: number[]; text: string; box: Box; lyrics: boolean }>();
+  for (const f of frames) {
+    for (const line of assembleLines(f.hits)) {
+      const b = line.box;
+      if (!b || line.alpha < 0.3) continue;
+      const fullyOut = b.x1 <= 0 || b.y1 <= 0 || b.x0 >= o.width || b.y0 >= o.height;
+      if (fullyOut) continue;
+      const clipped = b.x0 < -pad || b.y0 < -pad || b.x1 > o.width + pad || b.y1 > o.height + pad;
+      const unsafe =
+        !clipped &&
+        safe !== null &&
+        (b.x0 < safe.left - pad || b.y0 < safe.top - pad || b.x1 > o.width - safe.right + pad || b.y1 > o.height - safe.bottom + pad);
+      if (!clipped && !unsafe) continue;
+      const kind = clipped ? "clip" : "safe";
+      const lyrics = line.hits.every((h) => h.lyrics);
+      const key = `${kind}\u0000${lyrics ? "lyrics" : ""}\u0000${line.text}`;
+      let s = seen.get(key);
+      if (!s) seen.set(key, (s = { kind, times: [], text: line.text, box: b, lyrics }));
+      s.times.push(f.t);
+    }
+  }
+  const out: Finding[] = [];
+  for (const s of seen.values()) {
+    for (const r of runs(s.times, 1.5 / o.fps)) {
+      if (r.to - r.from + 1 / o.fps < minSec) continue;
+      // 가사 층의 마퀴 띠·배경 큰 글자는 일부러 화면 끝을 넘긴다 — 잘림은 경고로만(글 내용·두부·대비 판정은 그대로)
+      out.push({
+        rule: s.kind === "clip" ? "text.offscreen" : "text.safe-area",
+        severity: s.kind === "clip" && !s.lyrics ? "error" : "warn",
+        from: r.from,
+        to: r.to + 1 / o.fps,
+        message:
+          s.kind === "clip"
+            ? `${s.lyrics ? "가사 층 글" : "글"}이 화면 밖으로 잘린 채 ${(r.to - r.from).toFixed(1)}초 머문다 — "${s.text.slice(0, 60)}"${s.lyrics ? " — 띠·배경 장식이면 둬도 된다. 읽혀야 할 가사 줄이면 화면 안으로" : ""}`
+            : `글이 안전 영역(플랫폼 UI 가 가리는 자리)에 걸친다 — "${s.text.slice(0, 60)}"`,
+        detail: { text: s.text.slice(0, 120), box: roundBox(s.box) },
+      });
+    }
+  }
+  return out;
+}
+
+export function roundBox(b: Box): Box {
+  return { x0: Math.round(b.x0), y0: Math.round(b.y0), x1: Math.round(b.x1), y1: Math.round(b.y1) };
+}
+
+export interface TextPolicy {
+  minPx?: number;
+  maxOnScreen?: number;
+}
+
+// 틀(template.json text)이 정한 글 규칙. 한 화면에 글 덩어리가 너무 많거나 작으면 영상에서 안 읽힌다.
+export function textPolicy(frames: FrameText[], policy: TextPolicy, o: { fps: number; minSec?: number }): Finding[] {
+  const minSec = o.minSec ?? 1;
+  const small = new Map<string, number[]>();
+  const crowded: number[] = [];
+  let crowdMax = 0;
+  for (const f of frames) {
+    const lines = assembleLines(f.hits).filter((l) => l.box && l.alpha > 0.5 && /[\p{L}\p{N}]/u.test(l.text));
+    // 자막 판은 틀의 화면 글 수(장면이 쓰는 글)와 따로 센다 — 자막을 켰다고 장면 글이 많아진 게 아니다
+    const scene = lines.filter((l) => l.hits[0]?.via !== "caption").length;
+    if (policy.maxOnScreen && scene > policy.maxOnScreen) {
+      crowded.push(f.t);
+      crowdMax = Math.max(crowdMax, scene);
+    }
+    if (policy.minPx) for (const l of lines) if (l.sizePx < policy.minPx * 0.95) (small.get(l.text) ?? small.set(l.text, []).get(l.text)!).push(f.t);
+  }
+  const out: Finding[] = [];
+  for (const r of runs(crowded, 1.5 / o.fps)) {
+    if (r.to - r.from < minSec) continue;
+    out.push({
+      rule: "text.crowded",
+      severity: "warn",
+      from: r.from,
+      to: r.to + 1 / o.fps,
+      message: `한 화면에 글 덩어리가 최대 ${crowdMax}개 — 틀은 ${policy.maxOnScreen}개까지 (터미널·코드 화면이면 그대로 둬도 된다)`,
+    });
+  }
+  const smallRuns: { from: number; to: number; text: string }[] = [];
+  for (const [text, times] of small) for (const r of runs(times, 1.5 / o.fps)) if (r.to - r.from >= minSec) smallRuns.push({ from: r.from, to: r.to + 1 / o.fps, text });
+  if (smallRuns.length) {
+    smallRuns.sort((a, b) => a.from - b.from);
+    out.push({
+      rule: "text.small",
+      severity: "warn",
+      from: smallRuns[0].from,
+      to: Math.max(...smallRuns.map((x) => x.to)),
+      message: `틀의 최소 글 크기 ${policy.minPx}px 보다 작은 글 ${smallRuns.length}개 — 예: ${smallRuns
+        .slice(0, 4)
+        .map((x) => `"${x.text.trim().slice(0, 30)}"`)
+        .join(" · ")}`,
+      detail: { texts: smallRuns.slice(0, 50).map((x) => ({ text: x.text.slice(0, 60), from: x.from, to: x.to })) },
+    });
+  }
+  return out;
+}