kasaframe 0.0.0-stage → 0.1.1

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("빈 포트가 없다");
+}

package/packages/check/src/types.ts

@@ -0,0 +1,80 @@
+import type { KfMotionEvent, MotionRules as CoreMotionRules, SafeArea } from "@kasaframe/core";
+
+export type Severity = "error" | "warn";
+
+export interface Finding {
+  rule: string;
+  severity: Severity;
+  from: number;
+  to: number;
+  message: string;
+  // 고치는 쪽(사람이든 모델이든)이 곧장 손댈 자리를 찾도록 원자료를 붙인다.
+  detail?: Record<string, unknown>;
+}
+
+export interface Report {
+  target: string;
+  kind: "page" | "video";
+  // 페이지만 — step 이면 「같은 프레임 두 번」을 못 본다
+  mode?: "seek" | "step";
+  ok: boolean;
+  meta: { fps: number; width: number; height: number; duration: number };
+  sampled: { frames: number; textFrames: number; thumbFps: number };
+  counts: { error: number; warn: number };
+  findings: Finding[];
+  skipped: string[];
+  elapsedSec: number;
+}
+
+export interface Box {
+  x0: number;
+  y0: number;
+  x1: number;
+  y1: number;
+}
+
+export interface TextHit {
+  text: string;
+  // canvas 는 fillText·strokeText, DOM 은 text node
+  // caption — 엔진이 장면 위에 얹은 자막 판(data-kf-captions). 장면 글과 한 줄로 잇지 않는다
+  via: "canvas" | "dom" | "caption";
+  // 가사 층(data-kf-lyrics — JIZURA 같은 키네틱 가사) 안의 글. 띠로 흘리는 마퀴·배경 큰 글자처럼 일부러 화면 끝을 넘겨 그린다
+  lyrics?: boolean;
+  // fillText 에 문자열이 아닌 값(undefined·숫자·객체)이 들어왔을 때 그 typeof
+  argType?: string;
+  font: string;
+  sizePx: number;
+  alpha: number;
+  // 화면(뷰포트) 좌표. 화면에 붙지 않은 오프스크린 canvas 면 없다.
+  box?: Box;
+  where?: string;
+}
+
+export interface FrameText {
+  t: number;
+  hits: TextHit[];
+}
+
+export type MotionEvent = KfMotionEvent;
+
+export interface Marker {
+  t: number;
+  label: string;
+  kind: "scene" | "beat" | "drop" | "section";
+}
+
+export interface Beats {
+  duration?: number;
+  bpm?: number;
+  beats: number[];
+  downbeats?: number[];
+  bars?: number[];
+  phrases?: number[];
+  sections?: { t: number; kind: string; strength?: number }[];
+  drops?: number[];
+}
+
+// style.json 은 손으로 고치는 파일이라 빠진 칸이 있어도 검사는 돈다.
+export type MotionRules = Partial<CoreMotionRules>;
+
+export type { SafeArea };

package/packages/check/src/video.ts

@@ -0,0 +1,137 @@
+import { spawn, execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { colorThumb, type Thumb } from "./image.ts";
+import type { FrameText, TextHit } from "./types.ts";
+
+export interface VideoInfo {
+  fps: number;
+  width: number;
+  height: number;
+  duration: number;
+}
+
+export function probeVideo(file: string): VideoInfo {
+  const out = execFileSync("ffprobe", ["-v", "error", "-select_streams", "v:0", "-show_entries", "stream=width,height,r_frame_rate:format=duration", "-of", "json", file], {
+    encoding: "utf8",
+  });
+  const j = JSON.parse(out);
+  const s = j.streams?.[0];
+  if (!s) throw new Error(`영상 스트림이 없다: ${file}`);
+  const [n, d] = String(s.r_frame_rate).split("/").map(Number);
+  return { fps: d ? n / d : n, width: s.width, height: s.height, duration: Number(j.format.duration) };
+}
+
+const TW = 160;
+
+// 모든 프레임을 160×90 회색조로 받아 멈춤·빈 화면·컷을 잰다. 60초 60fps 면 52MB 남짓.
+export async function videoThumbs(file: string, info: VideoInfo, from = 0, to = info.duration): Promise<Thumb[]> {
+  // 페이지 검사의 썸네일처럼 화면비를 지킨다 — 160×90 으로 누르면 세로 영상의 안전 영역이 뒤집혀 layout.fill 이 늘 0% 였다
+  const TH = Math.max(2, Math.round((TW * info.height) / info.width));
+  // 색을 받아 섬광 검사의 빨강도 본다 — 밝기는 페이지 검사와 같은 식으로 여기서 만든다
+  const args = ["-v", "error", "-ss", String(from), "-t", String(to - from), "-i", file, "-vf", `scale=${TW}:${TH}:flags=area,format=rgb24`, "-f", "rawvideo", "-"];
+  const proc = spawn("ffmpeg", args, { stdio: ["ignore", "pipe", "pipe"] });
+  const size = TW * TH * 3;
+  const thumbs: Thumb[] = [];
+  let buf = Buffer.alloc(0);
+  let err = "";
+  proc.stderr.on("data", (d) => (err += d));
+  for await (const chunk of proc.stdout) {
+    buf = buf.length ? Buffer.concat([buf, chunk]) : chunk;
+    while (buf.length >= size) {
+      const data = new Uint8Array(TW * TH * 4);
+      for (let i = 0, j = 0; i < size; i += 3, j += 4) {
+        data[j] = buf[i];
+        data[j + 1] = buf[i + 1];
+        data[j + 2] = buf[i + 2];
+      }
+      thumbs.push(colorThumb(from + thumbs.length / info.fps, { width: TW, height: TH, data }));
+      buf = buf.subarray(size);
+    }
+  }
+  const code = await new Promise<number>((r) => proc.on("close", r));
+  if (code !== 0) throw new Error(`ffmpeg 실패: ${err.slice(0, 300)}`);
+  return thumbs;
+}
+
+function ocrBinary(): string | null {
+  if (process.platform !== "darwin") return null;
+  const src = fileURLToPath(new URL("./ocr.swift", import.meta.url));
+  const hash = createHash("sha1").update(readFileSync(src)).digest("hex").slice(0, 10);
+  const dir = join(homedir(), ".cache", "kasaframe");
+  const bin = join(dir, `kf-ocr-${hash}`);
+  if (existsSync(bin)) return bin;
+  mkdirSync(dir, { recursive: true });
+  try {
+    const tmp = `${bin}.${process.pid}`;
+    execFileSync("swiftc", ["-O", src, "-o", tmp], { stdio: "ignore" });
+    renameSync(tmp, bin);
+    return bin;
+  } catch {
+    return null;
+  }
+}
+
+function runOcr(bin: string, dir: string): Promise<{ file: string; items: { s: string; c: number; x0: number; y0: number; x1: number; y1: number }[] }[]> {
+  return new Promise((resolve, reject) => {
+    const p = spawn(bin, [dir], { stdio: ["ignore", "pipe", "pipe"] });
+    let out = "";
+    p.stdout.on("data", (d) => (out += d));
+    p.on("close", (code) =>
+      code === 0
+        ? resolve(
+            out
+              .split("\n")
+              .filter(Boolean)
+              .map((l) => JSON.parse(l)),
+          )
+        : reject(new Error(`OCR 실패 (${code})`)),
+    );
+  });
+}
+
+// mp4 에는 글자 정보가 없다. macOS Vision 으로 읽어 페이지 검사와 같은 꼴(FrameText)로 돌려준다.
+// 다른 OS 거나 swiftc 가 없으면 null — 그때 글 검사는 건너뛰었다고 보고서에 적는다.
+export async function videoText(file: string, info: VideoInfo, o: { fps: number; from?: number; to?: number; workers?: number }): Promise<FrameText[] | null> {
+  const bin = ocrBinary();
+  if (!bin) return null;
+  const from = o.from ?? 0;
+  const to = o.to ?? info.duration;
+  const root = mkdtempSync(join(tmpdir(), "kf-check-"));
+  try {
+    execFileSync("ffmpeg", ["-v", "error", "-ss", String(from), "-t", String(to - from), "-i", file, "-vf", `fps=${o.fps}`, join(root, "%06d.png")]);
+    const files = readdirSync(root).filter((f) => f.endsWith(".png")).sort();
+    const workers = Math.max(1, Math.min(o.workers ?? 4, files.length));
+    const dirs = Array.from({ length: workers }, (_, i) => {
+      const d = join(root, `w${i}`);
+      mkdirSync(d);
+      return d;
+    });
+    files.forEach((f, i) => renameSync(join(root, f), join(dirs[i % workers], f)));
+    const parts = await Promise.all(dirs.map((d) => runOcr(bin, d)));
+    const frames: FrameText[] = [];
+    for (const r of parts.flat()) {
+      const idx = Number(r.file.replace(/\D/g, "")) - 1;
+      const t = from + idx / o.fps;
+      const hits: TextHit[] = r.items.map((it) => {
+        const h = (it.y1 - it.y0) * info.height;
+        return {
+          text: it.s,
+          via: "dom",
+          font: "ocr",
+          sizePx: h * 0.8,
+          alpha: 1,
+          box: { x0: it.x0 * info.width, y0: it.y0 * info.height, x1: it.x1 * info.width, y1: it.y1 * info.height },
+          where: `ocr ${Math.round(it.c * 100)}%`,
+        };
+      });
+      if (hits.length) frames.push({ t, hits });
+    }
+    return frames.sort((a, b) => a.t - b.t);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}

package/packages/cli/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@kasaframe/cli",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "bin": {
+    "kf": "./src/kf.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@kasaframe/adapters": "^0.0.0",
+    "@kasaframe/clock": "^0.0.0",
+    "esbuild": "^0.28.2",
+    "playwright": "^1.64.0",
+    "vite": "^8.3.3",
+    "@kasaframe/motion": "0.0.0",
+    "pngjs": "^7.0.0",
+    "@kasaframe/jizura": "^0.0.0"
+  },
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^7.3.1",
+    "gsap": "^3.15.0",
+    "lottie-web": "^5.13.0",
+    "three": "^0.186.1",
+    "@types/pngjs": "^6.0.5"
+  }
+}

package/packages/cli/src/blur.ts

@@ -0,0 +1,68 @@
+import { PNG } from "pngjs";
+import type { PageInfo, Tab } from "./browser.ts";
+
+export interface BlurOpts {
+  /** 하위 프레임 수 — 2 이상이면 켠다 */
+  count: number;
+  /** 셔터 각도(도). 180 이면 프레임 간격의 절반 동안 열려 있다 */
+  shutter: number;
+}
+
+export function blurOpts(opts: Record<string, string | boolean | undefined>): BlurOpts | null {
+  const count = Math.round(Number(opts["motion-blur"] ?? 0));
+  if (!(count > 1)) return null;
+  const shutter = Number(opts.shutter ?? 180);
+  return { count, shutter: Number.isFinite(shutter) ? Math.min(360, Math.max(1, shutter)) : 180 };
+}
+
+// 하위 프레임은 그 프레임이 속한 장면 안에서만 — 셔터가 컷을 넘으면 두 장면이 겹쳐 찍힌다
+function sceneSpan(info: PageInfo, t: number): [number, number] {
+  const starts = info.markers.filter((m) => m.kind === "scene").map((m) => m.t).sort((a, b) => a - b);
+  let a = 0;
+  let b = info.meta.duration;
+  for (const s of starts) {
+    if (s <= t + 1e-9) a = s;
+    else {
+      b = s;
+      break;
+    }
+  }
+  return [a, b];
+}
+
+/** 프레임 시각 t 둘레(가운데 맞춤 셔터)의 하위 시각들 */
+export function subTimes(info: PageInfo, t: number, o: BlurOpts): number[] {
+  const [a, b] = sceneSpan(info, t);
+  const open = o.shutter / 360 / info.meta.fps;
+  const last = b - 1 / (info.meta.fps * 1000);
+  return Array.from({ length: o.count }, (_, i) => Math.min(last, Math.max(a, t + ((i + 0.5) / o.count - 0.5) * open)));
+}
+
+/**
+ * 한 프레임을 하위 프레임 count 장으로 찍어 평균한 RGBA. 빨리 움직이는 것만 번지고 서 있는 것은 그대로다.
+ * 하위 프레임 번호를 페이지에 넘겨, 3D 전환이 같은 평균으로 피사계 심도를 얻는다. 같은 t 면 같은 그림
+ */
+export async function captureBlurred(tab: Tab, info: PageInfo, t: number, o: BlurOpts): Promise<{ data: Buffer; width: number; height: number }> {
+  let acc: Uint32Array | null = null;
+  let width = 0;
+  let height = 0;
+  const times = subTimes(info, t, o);
+  for (const [index, ts] of times.entries()) {
+    await tab.seek(ts, { index, count: o.count });
+    const img = PNG.sync.read(await tab.capture());
+    width = img.width;
+    height = img.height;
+    acc ??= new Uint32Array(img.data.length);
+    for (let j = 0; j < img.data.length; j++) acc[j] += img.data[j];
+  }
+  const n = times.length;
+  const data = Buffer.alloc(acc!.length);
+  for (let j = 0; j < acc!.length; j++) data[j] = Math.round(acc![j] / n);
+  return { data, width, height };
+}
+
+export function rgbaToPng(img: { data: Buffer; width: number; height: number }): Buffer {
+  const png = new PNG({ width: img.width, height: img.height });
+  img.data.copy(png.data);
+  return PNG.sync.write(png, { deflateLevel: 1 });
+}