kasaframe 0.0.0-stage → 0.1.1

package/packages/check/src/check.ts

@@ -0,0 +1,273 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { clockScript } from "@kasaframe/clock";
+import { openProject, repoRoot } from "@kasaframe/cli";
+import { scanPage } from "./scan.ts";
+import { serveStatic } from "./serve.ts";
+import { probeVideo, videoText, videoThumbs } from "./video.ts";
+import { badText, glyphProblems, offscreenText, textPolicy, type TextPolicy } from "./rules/text.ts";
+import { captionOverlap } from "./rules/captions.ts";
+import { genAssets } from "./rules/assets.ts";
+import { blanks, cuts, freezes, spikes } from "./rules/frames.ts";
+import { flashes } from "./rules/flash.ts";
+import { fill, staticLayout, type SceneSpan } from "./rules/layout.ts";
+import { cameraWander, heroEdge } from "./rules/camera.ts";
+import { boundaries, motionRules } from "./rules/beats.ts";
+import { contrast, pageErrors, repeatable } from "./rules/page.ts";
+import type { Beats, Finding, MotionEvent, MotionRules, Report, SafeArea } from "./types.ts";
+
+export interface CheckOptions {
+  target: string;
+  from?: number;
+  to?: number;
+  tabs?: number;
+  // 옛 페이지(window.seek 만 있는 곳)에서 meta 대신
+  fps?: number;
+  duration?: number;
+  width?: number;
+  height?: number;
+  query?: string;
+  thumbFps?: number;
+  shotFps?: number;
+  ocr?: boolean;
+  ocrFps?: number;
+  beats?: string;
+  style?: string;
+  log?: (s: string) => void;
+}
+
+interface Project {
+  dir: string | null;
+  kf: any | null;
+  beats: Beats | null;
+  rules: MotionRules;
+  safe?: SafeArea;
+  text: TextPolicy;
+  allowText: string[];
+  scenes: number[];
+}
+
+function readJson(p: string): any | null {
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// kf.json 이 있는 폴더가 프로젝트. mp4 는 보통 <proj>/out/ 에 있으니 위로 두 칸까지 찾는다.
+function findProject(start: string): string | null {
+  let d = resolve(start);
+  for (let i = 0; i < 3; i++) {
+    if (existsSync(join(d, "kf.json"))) return d;
+    d = dirname(d);
+  }
+  return null;
+}
+
+function loadProject(dir: string | null, o: CheckOptions): Project {
+  const kf = dir ? readJson(join(dir, "kf.json")) : null;
+  const at = (p: string | undefined, fallback: string) => (dir ? join(dir, p ?? fallback) : null);
+  const beatsPath = o.beats ?? at(kf?.beats, "beats.json");
+  const stylePath = o.style ?? at(kf?.style, "style.json");
+  const beats = beatsPath ? readJson(beatsPath) : null;
+  const style = stylePath ? readJson(stylePath) : null;
+  // 틀의 motion 이 style.json 위에 덮인다(SPEC 계약 7).
+  const template = kf?.template ? readJson(join(repoRoot, "templates", kf.template, "template.json")) : null;
+  const rules: MotionRules = { ...(style?.motion ?? {}), ...(template?.motion ?? {}) };
+  const scenes: number[] = Array.isArray(kf?.scenes) ? kf.scenes.map((s: any) => Number(s.from)).filter((t: number) => Number.isFinite(t)) : [];
+  return {
+    dir,
+    kf,
+    beats: beats && Array.isArray(beats.beats) ? beats : null,
+    rules,
+    safe: kf?.safeArea,
+    text: { ...(template?.text ?? {}), ...(kf?.text ?? {}) },
+    allowText: kf?.check?.allowText ?? [],
+    scenes,
+  };
+}
+
+// 화면 채움·장면 안 구도 변화는 장면 단위로 본다 — kf.json 장면이 없으면 영상 하나를 한 장면으로
+function sceneSpans(kf: any): SceneSpan[] {
+  return Array.isArray(kf?.scenes) ? kf.scenes.filter((s: any) => Number.isFinite(Number(s.from))).map((s: any) => ({ id: String(s.id), from: Number(s.from), dur: Number(s.dur) || 0 })) : [];
+}
+
+// 이음매는 화면 전체를 옮기는 게 일이다 — 카메라·주인공 자리 판정에서 뺀다
+function seamScenes(kf: any): string[] {
+  return Array.isArray(kf?.scenes) ? kf.scenes.filter((s: any) => s.role === "seam").map((s: any) => String(s.id)) : [];
+}
+
+function sortFindings(f: Finding[]): Finding[] {
+  return f.sort((a, b) => (a.severity === b.severity ? a.from - b.from : a.severity === "error" ? -1 : 1));
+}
+
+function finish(target: string, kind: Report["kind"], meta: Report["meta"], findings: Finding[], skipped: string[], sampled: Report["sampled"], t0: number): Report {
+  const counts = { error: findings.filter((f) => f.severity === "error").length, warn: findings.filter((f) => f.severity === "warn").length };
+  const round = (x: number) => Math.round(x * 1000) / 1000;
+  for (const f of findings) {
+    f.from = round(f.from);
+    f.to = round(f.to);
+  }
+  return { target, kind, ok: counts.error === 0, meta, sampled, counts, findings: sortFindings(findings), skipped, elapsedSec: round((Date.now() - t0) / 1000) };
+}
+
+// kf.json 이 없어도 TS·TSX 모듈을 부르는 페이지는 묶어야 돈다 — 엔진의 Vite 길로 연다.
+function needsVite(dir: string): boolean {
+  if (["vite.config.ts", "vite.config.js", "vite.config.mjs"].some((f) => existsSync(join(dir, f)))) return true;
+  const html = join(dir, "index.html");
+  return existsSync(html) && /<script[^>]+src="[^"]+\.tsx?"/.test(readFileSync(html, "utf8"));
+}
+
+const VIDEO = new Set([".mp4", ".mov", ".webm", ".mkv", ".m4v"]);
+
+export async function check(o: CheckOptions): Promise<Report> {
+  const isUrl = /^https?:\/\//.test(o.target);
+  if (!isUrl && !existsSync(o.target)) throw new Error(`없는 경로: ${o.target}`);
+  if (!isUrl && statSync(o.target).isFile() && VIDEO.has(extname(o.target).toLowerCase())) return checkVideo(o);
+  return checkPage(o);
+}
+
+async function checkPage(o: CheckOptions): Promise<Report> {
+  const t0 = Date.now();
+  const log = o.log ?? (() => {});
+  const isUrl = /^https?:\/\//.test(o.target);
+  const dir = isUrl ? null : resolve(o.target);
+  const projDir = dir ? findProject(dir) : null;
+  const proj = loadProject(projDir, o);
+  const skipped: string[] = [];
+
+  let url: string;
+  let close: () => Promise<void>;
+  let clock: string | undefined;
+  if (isUrl) {
+    url = o.target;
+    close = async () => {};
+  } else if (projDir || needsVite(dir!)) {
+    const p = await openProject(projDir ?? dir!, { hmr: false });
+    url = p.url;
+    close = p.close;
+    clock = await clockScript();
+  } else {
+    if (!existsSync(join(dir!, "index.html"))) throw new Error(`${dir} 에 index.html 도 kf.json 도 없다`);
+    const s = await serveStatic(dir!);
+    url = s.url + "index.html";
+    close = s.close;
+  }
+  if (o.query) url += (url.includes("?") ? "&" : "?") + o.query.replace(/^\?/, "");
+
+  try {
+    const r = await scanPage({
+      url,
+      width: o.width ?? proj.kf?.width ?? 1920,
+      height: o.height ?? proj.kf?.height ?? 1080,
+      fps: o.fps,
+      duration: o.duration,
+      from: o.from,
+      to: o.to,
+      // 팬 소리 줄이기 — 탭은 둘까지
+      tabs: Math.min(2, o.tabs ?? 2),
+      // 0.1초 멈춤을 잡으려면 0.1초보다 촘촘히 봐야 한다
+      thumbFps: o.thumbFps ?? 30,
+      shotFps: o.shotFps ?? 2,
+      clock,
+      log,
+    });
+    const { meta } = r;
+    if (r.legacy) skipped.push("페이지 계약(window.__kf) 대신 옛 window.seek(t) 로 훑었다");
+    const f: Finding[] = [];
+    f.push(...pageErrors(r.errors, meta.fps));
+    f.push(...badText(r.texts, { fps: meta.fps, allow: proj.allowText }));
+    f.push(...glyphProblems(r.texts, r.glyphs, meta.fps));
+    f.push(...offscreenText(r.texts, { width: meta.width, height: meta.height, fps: meta.fps, safe: proj.safe }));
+    f.push(...captionOverlap(r.texts, { fps: meta.fps }));
+    f.push(...contrast(r.contrast, { shotFps: o.shotFps ?? 2 }));
+    if (proj.text.minPx || proj.text.maxOnScreen) f.push(...textPolicy(r.texts, proj.text, { fps: meta.fps }));
+    if (projDir) f.push(...genAssets(projDir));
+    f.push(...freezes(r.thumbs, { warnSec: proj.rules.maxFreezeSec }));
+    f.push(...blanks(r.thumbs, meta.duration));
+    f.push(...spikes(r.thumbs, { exclude: [...sceneSpans(proj.kf).map((s) => s.from), ...(proj.beats?.drops ?? []), ...r.markers.filter((m) => m.kind === "scene" || m.kind === "drop").map((m) => m.t)] }));
+    f.push(...flashes(r.thumbs, { maxPerSec: proj.rules.maxFlashPerSec, cuts: [...sceneSpans(proj.kf).map((s) => s.from), ...cuts(r.thumbs)] }));
+    f.push(...fill(r.thumbs, sceneSpans(proj.kf), { width: meta.width, height: meta.height, safe: proj.safe }));
+    f.push(...staticLayout(r.thumbs, sceneSpans(proj.kf), { width: meta.width, height: meta.height, warnSec: proj.rules.staticSec?.warn, errorSec: proj.rules.staticSec?.error }));
+    const seams = seamScenes(proj.kf);
+    f.push(...cameraWander(r.cams, r.events, { fps: meta.fps, skipScenes: seams }));
+    f.push(...heroEdge(r.cams, r.texts, sceneSpans(proj.kf), { width: meta.width, height: meta.height, fps: meta.fps, safe: proj.safe, skipScenes: seams }));
+    if (r.repeat.length) f.push(...repeatable(r.repeat));
+    else skipped.push(r.mode === "step" ? "같은 프레임 두 번 찍기 — step 모드는 되감을 수 없다" : "같은 프레임 두 번 찍기 — 구간이 1초보다 짧다");
+
+    const sceneStarts = r.markers.filter((m) => m.kind === "scene").map((m) => m.t);
+    const starts = sceneStarts.length ? sceneStarts : proj.scenes;
+    if (proj.beats && starts.length) f.push(...boundaries(starts, proj.beats, { fps: meta.fps, duration: meta.duration, source: "scene" }));
+    else skipped.push(proj.beats ? "장면 경계 — markers·kf.json scenes 가 없다" : "장면 경계·박 — beats.json 이 없다");
+    motionPart(f, skipped, r.events, proj, meta);
+
+    return { ...finish(o.target, "page", meta, f, skipped, { frames: r.frames, textFrames: r.texts.length, thumbFps: r.thumbFps }, t0), mode: r.mode };
+  } finally {
+    await close();
+  }
+}
+
+function motionPart(f: Finding[], skipped: string[], events: MotionEvent[] | null, proj: Project, meta: Report["meta"]): void {
+  if (!Object.keys(proj.rules).length) {
+    skipped.push("움직임 규칙 — style.json motion 이 없다");
+  } else if (!events) {
+    skipped.push("움직임 규칙 — 렌더 옆 .json(events)이 없다. 프로젝트 폴더로 kf check 하면 센다");
+  } else {
+    f.push(...motionRules(events, proj.beats, proj.rules, { fps: meta.fps, duration: meta.duration }));
+    if (!events.length) skipped.push("움직임 규칙 — window.__kf.events 가 비었다(움직임 부품을 안 썼거나 core emit 을 안 부른다)");
+    if (!proj.beats) skipped.push("움직임 규칙 중 드롭·프레이즈 기준 — beats.json 이 없다");
+  }
+}
+
+async function checkVideo(o: CheckOptions): Promise<Report> {
+  const t0 = Date.now();
+  const log = o.log ?? (() => {});
+  const file = resolve(o.target);
+  const info = probeVideo(file);
+  const from = Math.max(0, o.from ?? 0);
+  const to = Math.min(info.duration, o.to ?? info.duration);
+  const proj = loadProject(findProject(dirname(file)), o);
+  // kf render 가 남긴 x.json — markers·events 가 들어 있어 페이지를 다시 안 열어도 된다.
+  const side = readJson(join(dirname(file), basename(file, extname(file)) + ".json"));
+  const skipped: string[] = [];
+  const f: Finding[] = [];
+  const meta = { fps: info.fps, width: info.width, height: info.height, duration: info.duration };
+
+  log(`프레임 읽기: ${from.toFixed(2)}–${to.toFixed(2)}초 · ${info.width}×${info.height} · ${info.fps.toFixed(2)}fps`);
+  const thumbs = await videoThumbs(file, info, from, to);
+  f.push(...freezes(thumbs, { warnSec: proj.rules.maxFreezeSec }));
+  f.push(...blanks(thumbs, info.duration));
+  f.push(...spikes(thumbs, { exclude: [...sceneSpans(proj.kf).map((s) => s.from), ...(proj.beats?.drops ?? [])] }));
+  f.push(...flashes(thumbs, { maxPerSec: proj.rules.maxFlashPerSec, cuts: [...sceneSpans(proj.kf).map((s) => s.from), ...cuts(thumbs)] }));
+  f.push(...fill(thumbs, sceneSpans(proj.kf), { width: info.width, height: info.height, safe: proj.safe }));
+  f.push(...staticLayout(thumbs, sceneSpans(proj.kf), { width: info.width, height: info.height, warnSec: proj.rules.staticSec?.warn, errorSec: proj.rules.staticSec?.error }));
+
+  let textFrames = 0;
+  if (o.ocr === false) skipped.push("화면 글 훑기 — --no-ocr");
+  else {
+    const ocrFps = o.ocrFps ?? 2;
+    log(`글 읽기(OCR ${ocrFps}fps)`);
+    const texts = await videoText(file, info, { fps: ocrFps, from, to });
+    if (!texts) skipped.push("화면 글 훑기 — OCR(macOS Vision·swiftc)이 없다. 프로젝트 폴더로 kf check 하면 글을 직접 본다");
+    else {
+      textFrames = texts.length;
+      f.push(...badText(texts, { fps: ocrFps, allow: proj.allowText, fuzzy: true }));
+      skipped.push(`mp4 글 훑기는 OCR ${ocrFps}fps — 두부 글자·화면 밖 글·대비·짧게 스친 글은 프로젝트 폴더 검사에서 본다`);
+    }
+  }
+
+  const markers: { t: number; kind: string }[] = side?.markers ?? [];
+  const sceneStarts = markers.filter((m) => m.kind === "scene").map((m) => m.t);
+  const starts = sceneStarts.length ? sceneStarts : proj.scenes;
+  if (proj.beats) {
+    if (starts.length) f.push(...boundaries(starts, proj.beats, { fps: info.fps, duration: info.duration, source: "scene" }));
+    else f.push(...boundaries(cuts(thumbs), proj.beats, { fps: info.fps, duration: info.duration, source: "cut" }));
+  } else skipped.push("장면 경계·박 — beats.json 이 없다(--beats 로 줄 수 있다)");
+  motionPart(f, skipped, side?.events ?? null, proj, meta);
+  if (proj.dir) f.push(...genAssets(proj.dir));
+  skipped.push("같은 프레임 두 번 찍기 — mp4 로는 못 한다");
+  skipped.push("카메라 떠돌기·주인공 자리(camera.wander·layout.edge) — mp4 로는 못 본다. 프로젝트 폴더로 kf check 하면 카메라 층을 직접 잰다");
+
+  return finish(o.target, "video", meta, f, skipped, { frames: thumbs.length, textFrames, thumbFps: info.fps }, t0);
+}

package/packages/check/src/cli.ts

@@ -0,0 +1,70 @@
+import { mkdirSync, writeFileSync, existsSync, statSync } from "node:fs";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { num, parseFlags } from "@kasaframe/cli";
+import { check } from "./check.ts";
+import { formatReport } from "./report.ts";
+
+export const usage = `kf check <프로젝트 폴더 | 영상.mp4 | http 주소> [옵션]
+
+  폴더(kf.json 또는 index.html)는 페이지를 열어 프레임마다 훑는다 — 가장 정확하다.
+  mp4 는 프레임 차·OCR 로 본다. 옆에 kf render 가 남긴 같은 이름 .json 이 있으면 움직임 규칙도 센다.
+
+  --from <초> --to <초>   이 구간만
+  --json <경로>           JSON 보고서 자리 (기본: 폴더/out/check.json · 영상 옆 <이름>.check.json)
+  --strict                경고도 실패로 친다
+  --tabs <n>              크롬 탭 수(기본 2, 최대 2)
+  --query <a=1>           페이지 주소 뒤에 붙일 질의(옛 페이지의 ?rec=1 따위)
+  --fps <n> --duration <초> --width <px> --height <px>   window.__kf 가 없는 옛 페이지용
+  --beats <beats.json> --style <style.json>              프로젝트 밖 영상용
+  --ocr-fps <n>           mp4 글 읽기 빈도(기본 2) · --no-ocr 로 끈다
+
+  종료 코드: 0 통과 · 1 오류 있음(--strict 면 경고도) · 2 검사를 못 돌림`;
+
+function defaultJson(target: string): string | null {
+  if (/^https?:\/\//.test(target)) return null;
+  const p = resolve(target);
+  if (statSync(p).isDirectory()) return join(p, "out", "check.json");
+  return join(dirname(p), basename(p, extname(p)) + ".check.json");
+}
+
+export async function run(argv: string[]): Promise<number> {
+  const { args, opts } = parseFlags(argv);
+  const target = args[0];
+  if (!target) {
+    console.error(usage);
+    return 2;
+  }
+  const opt = (k: string) => (typeof opts[k] === "string" ? (opts[k] as string) : undefined);
+  const n = (k: string) => (opts[k] === undefined ? undefined : num(opts[k], NaN));
+  try {
+    if (!/^https?:\/\//.test(target) && !existsSync(target)) throw new Error(`없는 경로: ${target}`);
+    const report = await check({
+      target,
+      from: n("from"),
+      to: n("to"),
+      tabs: n("tabs"),
+      fps: n("fps"),
+      duration: n("duration"),
+      width: n("width"),
+      height: n("height"),
+      query: opt("query"),
+      ocr: opts["no-ocr"] ? false : undefined,
+      ocrFps: n("ocr-fps"),
+      beats: opt("beats"),
+      style: opt("style"),
+      log: (s) => console.error(s),
+    });
+    if (opts.strict && report.counts.warn) report.ok = false;
+    const jsonPath = opt("json") ?? defaultJson(target);
+    console.log(formatReport(report));
+    if (jsonPath) {
+      mkdirSync(dirname(jsonPath), { recursive: true });
+      writeFileSync(jsonPath, JSON.stringify(report, null, 2) + "\n");
+      console.log(`JSON: ${jsonPath}`);
+    }
+    return report.ok ? 0 : 1;
+  } catch (err) {
+    console.error(`kf check: 검사를 못 돌렸다 — ${err instanceof Error ? err.message : String(err)}`);
+    return 2;
+  }
+}

package/packages/check/src/image.ts

@@ -0,0 +1,146 @@
+import { PNG } from "pngjs";
+import type { Box } from "./types.ts";
+
+export interface Rgba {
+  width: number;
+  height: number;
+  data: Uint8Array;
+}
+
+export interface Thumb {
+  t: number;
+  luma: Uint8Array;
+  mean: number;
+  std: number;
+  // FLASH_GRID×FLASH_GRID 칸마다 채도 높은 빨강 픽셀 몫 — 색을 받아 찍은 썸네일만(섬광 검사의 빨강 깜빡임)
+  red?: Float32Array;
+}
+
+export function decodePng(buf: Buffer): Rgba {
+  const png = PNG.sync.read(buf);
+  return { width: png.width, height: png.height, data: png.data };
+}
+
+export function luma(img: Rgba): Uint8Array {
+  const out = new Uint8Array(img.width * img.height);
+  for (let i = 0, j = 0; j < out.length; i += 4, j++) {
+    out[j] = (img.data[i] * 54 + img.data[i + 1] * 183 + img.data[i + 2] * 19) >> 8;
+  }
+  return out;
+}
+
+export function stats(l: Uint8Array): { mean: number; std: number } {
+  let s = 0;
+  let s2 = 0;
+  for (const v of l) {
+    s += v;
+    s2 += v * v;
+  }
+  const mean = s / l.length;
+  return { mean, std: Math.sqrt(Math.max(0, s2 / l.length - mean * mean)) };
+}
+
+export function thumb(t: number, l: Uint8Array): Thumb {
+  return { t, luma: l, ...stats(l) };
+}
+
+export const FLASH_GRID = 8;
+
+// ITU-R BT.1702·WCAG 의 「채도 높은 빨강」 — R/(R+G+B) ≥ 0.8 이고 (R−G−B)×320 > 20(0..1 눈금)
+export function redGrid(img: Rgba): Float32Array {
+  const g = FLASH_GRID;
+  const hit = new Float32Array(g * g);
+  const cnt = new Float32Array(g * g);
+  for (let y = 0; y < img.height; y++) {
+    const r = Math.min(g - 1, Math.floor((y * g) / img.height));
+    for (let x = 0; x < img.width; x++) {
+      const k = r * g + Math.min(g - 1, Math.floor((x * g) / img.width));
+      const i = (y * img.width + x) * 4;
+      const R = img.data[i] / 255;
+      const G = img.data[i + 1] / 255;
+      const B = img.data[i + 2] / 255;
+      cnt[k]++;
+      if (R + G + B > 0 && R / (R + G + B) >= 0.8 && (R - G - B) * 320 > 20) hit[k]++;
+    }
+  }
+  for (let k = 0; k < hit.length; k++) hit[k] /= cnt[k] || 1;
+  return hit;
+}
+
+export function colorThumb(t: number, img: Rgba): Thumb {
+  return { ...thumb(t, luma(img)), red: redGrid(img) };
+}
+
+export function meanAbsDiff(a: Uint8Array, b: Uint8Array): number {
+  if (a.length !== b.length) return 255;
+  let s = 0;
+  for (let i = 0; i < a.length; i++) s += Math.abs(a[i] - b[i]);
+  return s / a.length;
+}
+
+function channel(v: number): number {
+  const c = v / 255;
+  return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+export function relLum(r: number, g: number, b: number): number {
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+
+export function contrastRatio(a: number, b: number): number {
+  const [hi, lo] = a > b ? [a, b] : [b, a];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+// 글 상자 바로 바깥 테두리 띠의 가운데값을 바탕색으로 본다. 상자 안은 글자가 섞여 못 쓴다.
+export function backgroundAround(img: Rgba, box: Box, ring = 4): [number, number, number] | null {
+  const x0 = Math.max(0, Math.floor(box.x0) - ring);
+  const y0 = Math.max(0, Math.floor(box.y0) - ring);
+  const x1 = Math.min(img.width - 1, Math.ceil(box.x1) + ring);
+  const y1 = Math.min(img.height - 1, Math.ceil(box.y1) + ring);
+  if (x1 <= x0 || y1 <= y0) return null;
+  const rs: number[] = [];
+  const gs: number[] = [];
+  const bs: number[] = [];
+  const push = (x: number, y: number) => {
+    const i = (y * img.width + x) * 4;
+    rs.push(img.data[i]);
+    gs.push(img.data[i + 1]);
+    bs.push(img.data[i + 2]);
+  };
+  const step = Math.max(1, Math.floor((x1 - x0 + y1 - y0) / 200));
+  for (let x = x0; x <= x1; x += step) {
+    push(x, y0);
+    push(x, y1);
+  }
+  for (let y = y0; y <= y1; y += step) {
+    push(x0, y);
+    push(x1, y);
+  }
+  const med = (a: number[]) => a.sort((p, q) => p - q)[a.length >> 1];
+  return [med(rs), med(gs), med(bs)];
+}
+
+// 칠한 색(fillStyle)이 아니라 실제로 찍힌 픽셀로 잰다 — 위에 다른 것이 덮였거나 반투명이면 그게 보이는 대비다.
+// 상자 안에서 바탕과 가장 멀리 떨어진 픽셀들(상위 5%)을 글자 색으로 본다. 그것도 바탕과 같으면 글이 안 보이는 것(덮임)이라 null.
+export function inkContrast(img: Rgba, box: Box): number | null {
+  const bg = backgroundAround(img, box);
+  if (!bg) return null;
+  const bgLum = relLum(bg[0], bg[1], bg[2]);
+  const x0 = Math.max(0, Math.floor(box.x0));
+  const y0 = Math.max(0, Math.floor(box.y0));
+  const x1 = Math.min(img.width, Math.ceil(box.x1));
+  const y1 = Math.min(img.height, Math.ceil(box.y1));
+  const lums: number[] = [];
+  for (let y = y0; y < y1; y++) {
+    for (let x = x0; x < x1; x++) {
+      const i = (y * img.width + x) * 4;
+      lums.push(relLum(img.data[i], img.data[i + 1], img.data[i + 2]));
+    }
+  }
+  if (lums.length < 4) return null;
+  lums.sort((a, b) => Math.abs(b - bgLum) - Math.abs(a - bgLum));
+  const ink = lums[Math.floor(lums.length * 0.05)];
+  const ratio = contrastRatio(ink, bgLum);
+  return ratio < 1.15 ? null : ratio;
+}

package/packages/check/src/index.ts

@@ -0,0 +1,9 @@
+export { check } from "./check.ts";
+export type { CheckOptions } from "./check.ts";
+export { run, usage } from "./cli.ts";
+export { formatReport } from "./report.ts";
+export { scanPage } from "./scan.ts";
+export { assembleLines, badText, glyphProblems, offscreenText } from "./rules/text.ts";
+export { freezes, blanks, cuts } from "./rules/frames.ts";
+export { boundaries, motionRules } from "./rules/beats.ts";
+export type { Finding, Report, Severity, TextHit, FrameText, MotionEvent, MotionRules, Beats } from "./types.ts";

package/packages/check/src/ocr.swift

@@ -0,0 +1,37 @@
+// mp4 는 글자 정보가 없으니 macOS Vision 으로 읽는다. 폴더의 png 를 이름 순으로 읽어 한 줄에 한 장씩 JSON 을 낸다.
+// usesLanguageCorrection 을 끄는 이유: 켜면 「undefined」「NaN」 같은 낱말을 사전 낱말로 고쳐 버린다.
+import AppKit
+import Foundation
+import Vision
+
+let dir = CommandLine.arguments.count > 1 ? CommandLine.arguments[1] : "."
+let files = ((try? FileManager.default.contentsOfDirectory(atPath: dir)) ?? [])
+  .filter { $0.hasSuffix(".png") }
+  .sorted()
+
+for name in files {
+  let path = (dir as NSString).appendingPathComponent(name)
+  var items: [[String: Any]] = []
+  if let img = NSImage(contentsOfFile: path),
+    let cg = img.cgImage(forProposedRect: nil, context: nil, hints: nil)
+  {
+    let req = VNRecognizeTextRequest()
+    req.recognitionLevel = .accurate
+    req.recognitionLanguages = ["ko-KR", "en-US"]
+    req.usesLanguageCorrection = false
+    try? VNImageRequestHandler(cgImage: cg, options: [:]).perform([req])
+    for obs in req.results ?? [] {
+      guard let top = obs.topCandidates(1).first else { continue }
+      let b = obs.boundingBox
+      items.append([
+        "s": top.string, "c": top.confidence,
+        "x0": b.minX, "y0": 1 - b.maxY, "x1": b.maxX, "y1": 1 - b.minY,
+      ])
+    }
+  }
+  let obj: [String: Any] = ["file": name, "items": items]
+  if let data = try? JSONSerialization.data(withJSONObject: obj), let s = String(data: data, encoding: .utf8) {
+    print(s)
+    fflush(stdout)
+  }
+}