kasaframe 0.0.0-stage → 0.1.3

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;
+}

package/packages/check/src/scan.ts

@@ -0,0 +1,240 @@
+import type { Browser, CDPSession, Page } from "playwright";
+import { launch } from "@kasaframe/cli";
+import { probe, legacyShim } from "./probe.ts";
+import { colorThumb, decodePng, inkContrast, luma, meanAbsDiff, type Rgba, type Thumb } from "./image.ts";
+import type { FrameText, Marker, MotionEvent, TextHit } from "./types.ts";
+import type { CamSample } from "./rules/camera.ts";
+
+export interface ScanOptions {
+  url: string;
+  width: number;
+  height: number;
+  // 옛 페이지처럼 meta 를 안 주는 곳에서만 쓴다
+  fps?: number;
+  duration?: number;
+  from?: number;
+  to?: number;
+  tabs: number;
+  thumbFps: number;
+  shotFps: number;
+  clock?: string;
+  log?: (s: string) => void;
+}
+
+export interface ContrastSample {
+  t: number;
+  text: string;
+  ratio: number;
+  sizePx: number;
+  box: { x0: number; y0: number; x1: number; y1: number };
+}
+
+export interface RepeatSample {
+  t: number;
+  diff: number;
+  textSame: boolean;
+}
+
+export interface ScanResult {
+  meta: { fps: number; width: number; height: number; duration: number };
+  mode: "seek" | "step";
+  legacy: boolean;
+  markers: Marker[];
+  events: MotionEvent[];
+  texts: FrameText[];
+  thumbs: Thumb[];
+  thumbFps: number;
+  contrast: ContrastSample[];
+  errors: { t: number; text: string }[];
+  repeat: RepeatSample[];
+  glyphs: Record<string, string>;
+  // 썸네일 시각마다 카메라 층 transform·주인공 상자
+  cams: CamSample[];
+  frames: number;
+}
+
+interface Opened {
+  page: Page;
+  cdp: CDPSession;
+  meta: ScanResult["meta"];
+  mode: "seek" | "step";
+  legacy: boolean;
+  markers: Marker[];
+  errors: { t: number; text: string }[];
+  cur: { t: number };
+}
+
+const THUMB_W = 160;
+
+async function open(browser: Browser, o: ScanOptions): Promise<Opened> {
+  const page = await browser.newPage({ viewport: { width: o.width, height: o.height }, deviceScaleFactor: 1 });
+  const cur = { t: -1 };
+  const errors: Opened["errors"] = [];
+  page.on("pageerror", (e) => errors.push({ t: cur.t, text: `pageerror: ${e.message}` }));
+  page.on("console", (m) => {
+    if (m.type() === "error") errors.push({ t: cur.t, text: m.text() });
+  });
+  await page.addInitScript(probe);
+  if (o.clock) await page.addInitScript({ content: o.clock });
+  await page.goto(o.url, { waitUntil: "load" });
+  // main.ts 가 모듈 스크립트라 load 뒤에도 __kf 가 늦게 설 수 있다.
+  let kind = "none";
+  for (let i = 0; i < 150 && kind === "none"; i++) {
+    kind = await page.evaluate(legacyShim, { fps: o.fps ?? 60, duration: o.duration ?? 0 });
+    if (kind === "none") await page.waitForTimeout(100);
+  }
+  if (kind === "none") throw new Error(`페이지에 window.__kf 도 window.seek(t) 도 없다: ${o.url}`);
+  await page.evaluate(() => (window as any).__kf.ready());
+  const info = await page.evaluate(() => {
+    const k = (window as any).__kf;
+    return { meta: k.meta, mode: k.mode, markers: k.markers ?? [] };
+  });
+  const meta = { ...info.meta };
+  if (o.fps) meta.fps = o.fps;
+  if (o.duration) meta.duration = o.duration;
+  if (!(meta.duration > 0)) throw new Error("영상 길이를 모른다 — __kf.meta.duration 을 두거나 --duration 을 준다");
+  if (meta.width !== o.width || meta.height !== o.height) {
+    await page.setViewportSize({ width: meta.width, height: meta.height });
+  }
+  const cdp = await page.context().newCDPSession(page);
+  await page.evaluate(() => (window as any).__kfCheck.clear());
+  return { page, cdp, meta, mode: info.mode === "step" ? "step" : "seek", legacy: kind === "legacy", markers: info.markers, errors, cur };
+}
+
+async function capture(cdp: CDPSession, w: number, h: number, scale: number): Promise<Rgba> {
+  const r = await cdp.send("Page.captureScreenshot", {
+    format: "png",
+    clip: { x: 0, y: 0, width: w, height: h, scale },
+    optimizeForSpeed: true,
+  });
+  return decodePng(Buffer.from(r.data, "base64"));
+}
+
+async function seekTake(p: Opened, t: number): Promise<TextHit[]>;
+async function seekTake(p: Opened, t: number, cam: true): Promise<{ hits: TextHit[]; cam: Omit<CamSample, "t"> }>;
+async function seekTake(p: Opened, t: number, cam = false): Promise<any> {
+  p.cur.t = t;
+  return p.page.evaluate(
+    async ([tt, withCam]) => {
+      const w = window as any;
+      await w.__kf.seek(tt);
+      const hits = w.__kfCheck.take();
+      return withCam ? { hits, cam: w.__kfCheck.camera() } : hits;
+    },
+    [t, cam] as const,
+  );
+}
+
+function contrastOf(img: Rgba, t: number, hits: TextHit[]): ContrastSample[] {
+  const out: ContrastSample[] = [];
+  for (const h of hits) {
+    // 「·」 같은 문장부호 하나는 대비를 따질 글이 아니다.
+    if (!h.box || h.alpha < 0.6 || h.sizePx < 6 || !/[\p{L}\p{N}]/u.test(h.text)) continue;
+    const { x0, y0, x1, y1 } = h.box;
+    if (x1 <= 0 || y1 <= 0 || x0 >= img.width || y0 >= img.height) continue;
+    const ratio = inkContrast(img, h.box);
+    if (ratio === null) continue;
+    out.push({ t, text: h.text.slice(0, 60), ratio: Math.round(ratio * 100) / 100, sizePx: Math.round(h.sizePx), box: h.box });
+  }
+  return out;
+}
+
+export async function scanPage(o: ScanOptions): Promise<ScanResult> {
+  const log = o.log ?? (() => {});
+  // 엔진과 같은 실행 플래그여야 「같은 프레임 두 번 찍기」가 렌더와 같은 조건이 된다.
+  const browser = await launch();
+  try {
+    const first = await open(browser, o);
+    const { meta } = first;
+    const tabs = first.mode === "step" ? 1 : Math.max(1, Math.min(3, o.tabs));
+    const opened = [first];
+    for (let i = 1; i < tabs; i++) opened.push(await open(browser, o));
+
+    const fps = meta.fps;
+    const total = Math.round(meta.duration * fps);
+    const i0 = Math.max(0, Math.floor((o.from ?? 0) * fps));
+    const i1 = Math.min(total, Math.ceil((o.to ?? meta.duration) * fps));
+    const thumbStep = Math.max(1, Math.round(fps / o.thumbFps));
+    const shotStep = Math.max(1, Math.round(fps / o.shotFps));
+    const per = Math.ceil((i1 - i0) / tabs);
+    const scale = THUMB_W / meta.width;
+    log(`훑기: ${(i0 / fps).toFixed(2)}–${(i1 / fps).toFixed(2)}초 ${i1 - i0}프레임 · 탭 ${tabs} · ${first.mode}${first.legacy ? "(옛 seek)" : ""}`);
+
+    const parts = await Promise.all(
+      opened.map(async (p, k) => {
+        const a = i0 + k * per;
+        const b = Math.min(i1, a + per);
+        const texts: FrameText[] = [];
+        const thumbs: Thumb[] = [];
+        const contrast: ContrastSample[] = [];
+        const cams: CamSample[] = [];
+        let next = 0.1;
+        for (let i = a; i < b; i++) {
+          const t = i / fps;
+          const onThumb = i % thumbStep === 0;
+          const got = onThumb ? await seekTake(p, t, true) : { hits: await seekTake(p, t), cam: null };
+          const hits = got.hits;
+          if (got.cam) cams.push({ t, ...got.cam });
+          if (hits.length) texts.push({ t, hits });
+          if (onThumb) thumbs.push(colorThumb(t, await capture(p.cdp, meta.width, meta.height, scale)));
+          if (i % shotStep === 0 && hits.length) contrast.push(...contrastOf(await capture(p.cdp, meta.width, meta.height, 1), t, hits));
+          if ((i - a) / (b - a) >= next) {
+            log(`  탭 ${k + 1}: ${Math.round(next * 100)}%`);
+            next += 0.25;
+          }
+        }
+        const repeat: RepeatSample[] = [];
+        if (p.mode === "seek" && b - a > 10) {
+          for (const f of [0.2, 0.5, 0.8]) {
+            const t = Math.round(a + (b - a) * f) / fps;
+            const hA = await seekTake(p, t);
+            const A = luma(await capture(p.cdp, meta.width, meta.height, 0.25));
+            await seekTake(p, Math.max(0, t - 0.5));
+            const hB = await seekTake(p, t);
+            const B = luma(await capture(p.cdp, meta.width, meta.height, 0.25));
+            const key = (h: TextHit[]) => h.map((x) => x.text).join("\u0001");
+            repeat.push({ t, diff: Math.round(meanAbsDiff(A, B) * 1000) / 1000, textSame: key(hA) === key(hB) });
+          }
+        }
+        const events: MotionEvent[] = await p.page.evaluate(() => (window as any).__kf.events ?? []);
+        return { texts, thumbs, contrast, repeat, events, cams };
+      }),
+    );
+
+    const texts = parts.flatMap((x) => x.texts).sort((a, b) => a.t - b.t);
+    const pairs = new Set<string>();
+    for (const f of texts) for (const h of f.hits) for (const ch of new Set(h.text)) if (ch.trim()) pairs.add(h.font + "\u0000" + ch);
+    const list = [...pairs].slice(0, 6000).map((k) => k.split("\u0000") as [string, string]);
+    const glyphs: Record<string, string> = list.length ? await first.page.evaluate((ps) => (window as any).__kfCheck.glyphs(ps), list) : {};
+
+    const seen = new Set<string>();
+    const events = parts
+      .flatMap((x) => x.events)
+      .filter((e) => {
+        const key = `${e.t}|${e.kind}|${e.source}|${e.scene ?? ""}`;
+        if (seen.has(key)) return false;
+        seen.add(key);
+        return true;
+      })
+      .sort((a, b) => a.t - b.t);
+
+    return {
+      meta,
+      mode: first.mode,
+      legacy: first.legacy,
+      markers: first.markers,
+      events,
+      texts,
+      thumbs: parts.flatMap((x) => x.thumbs).sort((a, b) => a.t - b.t),
+      thumbFps: fps / thumbStep,
+      contrast: parts.flatMap((x) => x.contrast),
+      errors: opened.flatMap((p) => p.errors).sort((a, b) => a.t - b.t),
+      repeat: parts.flatMap((x) => x.repeat),
+      glyphs,
+      cams: parts.flatMap((x) => x.cams).sort((a, b) => a.t - b.t),
+      frames: i1 - i0,
+    };
+  } finally {
+    await browser.close();
+  }
+}

package/packages/check/src/serve.ts

@@ -0,0 +1,67 @@
+import { createServer, type Server } from "node:http";
+import { createReadStream, statSync } from "node:fs";
+import { extname, join, normalize, resolve, sep } from "node:path";
+
+const MIME: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+};
+
+// 빌드가 필요 없는 페이지(옛 방식·바닐라 html)를 띄우는 정적 서버.
+// kf 프로젝트는 엔진의 openProject(Vite)로 연다.
+export async function serveStatic(dir: string): Promise<{ url: string; close(): Promise<void> }> {
+  const root = resolve(dir);
+  const server = createServer((req, res) => {
+    const path = decodeURIComponent((req.url || "/").split("?")[0]);
+    let file = normalize(join(root, path));
+    if (file !== root && !file.startsWith(root + sep)) {
+      res.writeHead(403).end();
+      return;
+    }
+    try {
+      if (statSync(file).isDirectory()) file = join(file, "index.html");
+      const st = statSync(file);
+      res.writeHead(200, { "content-type": MIME[extname(file).toLowerCase()] || "application/octet-stream", "content-length": st.size });
+      createReadStream(file).pipe(res);
+    } catch {
+      res.writeHead(404).end();
+    }
+  });
+  const port = await listen(server);
+  return {
+    url: `http://127.0.0.1:${port}/`,
+    close: () => new Promise((r) => server.close(() => r())),
+  };
+}
+
+// TEAM.md 가 검사 담당에 준 포트 5130–5139 를 먼저 쓰고, 다 차면 아무 빈 포트.
+async function listen(server: Server): Promise<number> {
+  for (const port of [5130, 5131, 5132, 5133, 5134, 5135, 5136, 5137, 5138, 5139, 0]) {
+    const ok = await new Promise<boolean>((r) => {
+      server.once("error", () => r(false));
+      server.listen(port, "127.0.0.1", () => r(true));
+    });
+    if (ok) {
+      const a = server.address();
+      return typeof a === "object" && a ? a.port : port;
+    }
+  }
+  throw new Error("빈 포트가 없다");
+}