dsh-hyperframes 0.10.1 → 0.11.0

package/skills/media-use/scripts/lib/error-diffusion.test.mjs

@@ -0,0 +1,102 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { ERROR_DIFFUSION_ALGORITHMS, applyErrorDiffusionRgba } from "./error-diffusion.mjs";
+
+const EXPECTED_GRADIENTS = {
+  "floyd-steinberg": "00000101/00010101/00100101/00010111/01010101/01011011",
+  atkinson: "00000011/00001100/00010011/00010111/01001101/00111011",
+  "jarvis-judice-ninke": "00000011/00001011/00011001/00101111/00100111/01011011",
+  stucki: "00000011/00010101/00010110/00101011/00101101/01010111",
+  burkes: "00000101/00010011/00010110/00101011/01010111/00101011",
+  sierra: "00000011/00010101/00010110/00100111/00110111/00101101",
+  "sierra-lite": "00000101/00010101/00100101/00010110/01010111/01010101",
+  "two-row-sierra": "00000101/00010011/00010110/00101011/00101101/01011011",
+};
+
+test("exposes the eight article error-diffusion algorithms", () => {
+  assert.deepEqual(Object.keys(ERROR_DIFFUSION_ALGORITHMS), Object.keys(EXPECTED_GRADIENTS));
+});
+
+test("matches deterministic golden patterns for every diffusion kernel", () => {
+  const width = 8;
+  const height = 6;
+  const source = new Uint8ClampedArray(width * height * 4);
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const value = Math.round((255 * (x + y * 0.7)) / (width - 1 + (height - 1) * 0.7));
+      const offset = (y * width + x) * 4;
+      source[offset] = value;
+      source[offset + 1] = Math.round(value * 0.8);
+      source[offset + 2] = Math.round(value * 0.55);
+      source[offset + 3] = 17 + x + y;
+    }
+  }
+
+  for (const [algorithm, expected] of Object.entries(EXPECTED_GRADIENTS)) {
+    const output = source.slice();
+    applyErrorDiffusionRgba(output, width, height, {
+      algorithm,
+      brightness: 1,
+      contrast: 1,
+      detail: 1,
+      palette: ["#000000", "#ffffff"],
+      pointSize: 1,
+    });
+    const rows = [];
+    for (let y = 0; y < height; y++) {
+      let row = "";
+      for (let x = 0; x < width; x++) row += output[(y * width + x) * 4] ? "1" : "0";
+      rows.push(row);
+    }
+    assert.equal(rows.join("/"), expected, algorithm);
+    for (let i = 0; i < width * height; i++) assert.equal(output[i * 4 + 3], source[i * 4 + 3]);
+  }
+});
+
+test("fills point-size blocks from their center sample", () => {
+  const data = new Uint8ClampedArray([
+    0, 0, 0, 1, 0, 0, 0, 2, 0, 0, 0, 3, 0, 0, 0, 4, 0, 0, 0, 5, 255, 255, 255, 6, 0, 0, 0, 7, 255,
+    255, 255, 8,
+  ]);
+  applyErrorDiffusionRgba(
+    data,
+    4,
+    2,
+    {
+      algorithm: "floyd-steinberg",
+      brightness: 1,
+      contrast: 1,
+      detail: 1,
+      palette: ["#000000", "#ffffff"],
+      pointSize: 2,
+    },
+    new Float32Array(6),
+  );
+  assert.deepEqual(
+    [...data],
+    [
+      255, 255, 255, 1, 255, 255, 255, 2, 255, 255, 255, 3, 255, 255, 255, 4, 255, 255, 255, 5, 255,
+      255, 255, 6, 255, 255, 255, 7, 255, 255, 255, 8,
+    ],
+  );
+});
+
+test("preserves authored palette order and validates the public contract", () => {
+  const reversed = new Uint8ClampedArray([0, 0, 0, 255]);
+  applyErrorDiffusionRgba(reversed, 1, 1, {
+    palette: ["#ffffff", "#000000"],
+  });
+  assert.deepEqual([...reversed], [255, 255, 255, 255]);
+
+  assert.throws(
+    () => applyErrorDiffusionRgba(new Uint8ClampedArray(4), 1, 1, { palette: ["#000000"] }),
+    /2 to 6 colors/,
+  );
+  assert.throws(
+    () =>
+      applyErrorDiffusionRgba(new Uint8ClampedArray(4), 1, 1, {
+        algorithm: "ordered-bayer",
+      }),
+    /unknown error-diffusion algorithm/,
+  );
+});

package/skills/media-use/scripts/lib/ff-binaries.mjs

@@ -0,0 +1,37 @@
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+
+// The binaries media-use spawns: HYPERFRAMES_FFMPEG_PATH / HYPERFRAMES_FFPROBE_PATH when set, else PATH.
+// A set path that is not a working ffmpeg/ffprobe throws, so a broken override never reads as "no metadata".
+const runsByPath = new Map();
+
+export class FfBinarySettingError extends Error {}
+
+function configuredOr(name, envVar) {
+  const setting = process.env[envVar]?.trim();
+  if (!setting) return name;
+  const path = resolve(setting);
+  if (!runsByPath.has(path)) runsByPath.set(path, isWorking(path, name));
+  if (!runsByPath.get(path)) {
+    const why = `${envVar} names "${path}", which is not a working ${name}: fix it or unset it.`;
+    throw new FfBinarySettingError(why);
+  }
+  return path;
+}
+
+function isWorking(path, name) {
+  try {
+    const out = execFileSync(path, ["-version"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 15000,
+      windowsHide: true,
+    });
+    return out.startsWith(`${name} version`);
+  } catch {
+    return false;
+  }
+}
+
+export const ffmpegBinary = () => configuredOr("ffmpeg", "HYPERFRAMES_FFMPEG_PATH");
+export const ffprobeBinary = () => configuredOr("ffprobe", "HYPERFRAMES_FFPROBE_PATH");

package/skills/media-use/scripts/lib/freeze.mjs

@@ -0,0 +1,72 @@
+import { fetchMedia, isPublicMediaUrl, readCappedBody } from "./media-fetch.mjs";
+import { sanitizeSvg } from "./svg-sanitize.mjs";
+import { writeFileSync, copyFileSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+// ponytail: bound the download so a hostile/runaway URL can't fill the disk.
+// 256MB covers any real media asset; raise if 4K video sources ever exceed it.
+const MAX_FREEZE_BYTES = 256 * 1024 * 1024;
+// Bounds only the wait for response headers; a large video body may stream for minutes.
+const FREEZE_HEADERS_TIMEOUT_MS = 10_000;
+
+const isSvgPath = (destPath) => /\.svg$/i.test(destPath);
+
+// Every logo/icon SVG comes from a third-party host (theSVG, a --from URL, a local file), so it
+// passes the Figma import's sanitizeSvg allowlist before it touches disk.
+function writeFrozen(destPath, buffer) {
+  mkdirSync(dirname(destPath), { recursive: true });
+  const bytes = isSvgPath(destPath) ? Buffer.from(sanitizeSvg(buffer.toString("utf8"))) : buffer;
+  writeFileSync(destPath, bytes);
+  return bytes.byteLength;
+}
+
+export async function freezeUrl(url, destPath) {
+  const where = String(url).slice(0, 80);
+  const headerWait = new AbortController();
+  const timer = setTimeout(
+    () =>
+      headerWait.abort(
+        new Error(`freeze failed: no response within ${FREEZE_HEADERS_TIMEOUT_MS} ms for ${where}`),
+      ),
+    FREEZE_HEADERS_TIMEOUT_MS,
+  );
+  const res = await fetchMedia(url, { signal: headerWait.signal }).finally(() =>
+    clearTimeout(timer),
+  );
+  if (!res.ok) throw new Error(`freeze failed: HTTP ${res.status} for ${where}`);
+
+  const body = await readCappedBody(res, MAX_FREEZE_BYTES, `freeze failed for ${where}`);
+  if (body.byteLength === 0) throw new Error(`freeze failed: empty response for ${where}`);
+
+  return writeFrozen(destPath, body);
+}
+
+export function freezeLocalFile(srcPath, destPath) {
+  if (isSvgPath(destPath)) {
+    writeFrozen(destPath, readFileSync(srcPath));
+    return;
+  }
+  mkdirSync(dirname(destPath), { recursive: true });
+  copyFileSync(srcPath, destPath);
+}
+
+// Ingest accepts a DIRECT public media URL only — not a platform page. yt-dlp is
+// deliberately out (cloud IPs get blocked, and it's brittle); the supported case
+// is "user points at their own file or a direct asset link". A direct URL is a
+// non-platform host whose path ends in a known media extension.
+const PLATFORM_HOSTS =
+  /(^|\.)(youtube\.com|youtu\.be|vimeo\.com|tiktok\.com|instagram\.com|twitter\.com|x\.com|facebook\.com|dailymotion\.com)$/i;
+const MEDIA_EXT = /\.(mp3|wav|m4a|aac|ogg|flac|mp4|mov|webm|mkv|png|jpe?g|webp|gif|svg|avif)$/i;
+
+export function isDirectMediaUrl(u) {
+  let url;
+  try {
+    url = new URL(u);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+  if (PLATFORM_HOSTS.test(url.hostname)) return false;
+  if (!isPublicMediaUrl(url)) return false;
+  return MEDIA_EXT.test(url.pathname);
+}

package/skills/media-use/scripts/lib/freeze.test.mjs

@@ -0,0 +1,138 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { isDirectMediaUrl, freezeUrl, freezeLocalFile } from "./freeze.mjs";
+
+const HOSTILE_SVG =
+  '<svg xmlns="http://www.w3.org/2000/svg"><script>alert(1)</script>' +
+  '<rect onload="alert(2)" width="1" height="1"/>' +
+  '<a href="javascript:alert(3)"><circle r="1"/></a></svg>';
+
+test("accepts direct public media URLs", () => {
+  assert.equal(isDirectMediaUrl("https://cdn.example.com/clip.mp4"), true);
+  assert.equal(isDirectMediaUrl("https://example.com/a/b/track.mp3"), true);
+  assert.equal(isDirectMediaUrl("http://example.com/logo.svg"), true);
+});
+
+test("rejects platform pages (no yt-dlp)", () => {
+  assert.equal(isDirectMediaUrl("https://www.youtube.com/watch?v=abc"), false);
+  assert.equal(isDirectMediaUrl("https://youtu.be/abc"), false);
+  assert.equal(isDirectMediaUrl("https://vimeo.com/12345"), false);
+  assert.equal(isDirectMediaUrl("https://x.com/u/status/1"), false);
+});
+
+test("rejects non-direct / non-media URLs", () => {
+  assert.equal(isDirectMediaUrl("https://example.com/page"), false, "no media extension");
+  assert.equal(isDirectMediaUrl("ftp://example.com/a.mp4"), false, "non-http(s)");
+  assert.equal(isDirectMediaUrl("not a url"), false);
+});
+
+test("rejects local / private hosts (SSRF guard, m11)", () => {
+  for (const u of [
+    "http://localhost/a.mp4",
+    "http://127.0.0.1/a.mp4",
+    "http://127.1.2.3/a.mp4",
+    "http://0.0.0.0/a.mp4",
+    "http://10.0.0.5/a.mp4",
+    "http://192.168.1.1/a.mp4",
+    "http://172.16.0.1/a.mp4",
+    "http://172.31.255.255/a.mp4",
+    "http://169.254.169.254/a.mp4", // cloud metadata endpoint
+    "http://printer.local/a.mp4",
+    "http://svc.internal/a.mp4",
+    "http://[::1]/a.mp4",
+    "http://[fe80::1]/a.mp4",
+    "http://[fd00::1]/a.mp4",
+  ]) {
+    assert.equal(isDirectMediaUrl(u), false, `should block ${u}`);
+  }
+  // A public host that merely starts with similar digits is still allowed.
+  assert.equal(isDirectMediaUrl("https://172.40.0.1/a.mp4"), true, "172.40 is public");
+  assert.equal(isDirectMediaUrl("https://11.example.com/a.mp4"), true);
+});
+
+test("freezeUrl strips <script>, on* handlers and javascript: hrefs from a fetched SVG", async (t) => {
+  t.mock.method(
+    globalThis,
+    "fetch",
+    async () =>
+      new Response(HOSTILE_SVG, { status: 200, headers: { "content-type": "image/svg+xml" } }),
+  );
+  const dest = join(mkdtempSync(join(tmpdir(), "media-use-freeze-")), "logo.svg");
+  await freezeUrl("https://example.com/hostile.svg", dest);
+  const out = readFileSync(dest, "utf8");
+  assert.ok(!out.includes("<script"), "script element stripped");
+  assert.ok(!out.includes("onload="), "event handler stripped");
+  assert.ok(!out.includes("javascript:"), "javascript: href stripped");
+  assert.ok(out.includes("<circle"), "benign markup survives");
+});
+
+// Puts setTimeout and AbortSignal.timeout on node:test's fake clock.
+function fakeClock(t) {
+  t.mock.timers.enable({ apis: ["setTimeout"] });
+  t.mock.method(AbortSignal, "timeout", (ms) => {
+    const controller = new AbortController();
+    setTimeout(() => controller.abort(new DOMException("timed out", "TimeoutError")), ms);
+    return controller.signal;
+  });
+}
+
+test("freezeUrl keeps streaming a slow body past the header timeout", async (t) => {
+  fakeClock(t);
+  let body;
+  t.mock.method(globalThis, "fetch", async (_url, { signal }) => {
+    const stream = new ReadableStream({
+      start(controller) {
+        body = controller;
+        // undici aborts the body stream too when the request signal fires.
+        signal.addEventListener("abort", () => controller.error(signal.reason));
+        controller.enqueue(new Uint8Array([1, 2, 3]));
+      },
+    });
+    return new Response(stream, { status: 200 });
+  });
+  const dest = join(mkdtempSync(join(tmpdir(), "media-use-freeze-")), "clip.mp4");
+  const frozen = freezeUrl("https://cdn.example.com/clip.mp4", dest);
+  await new Promise(setImmediate);
+  t.mock.timers.tick(60_000);
+  body.enqueue(new Uint8Array([4, 5]));
+  body.close();
+  assert.equal(await frozen, 5);
+  assert.deepEqual([...readFileSync(dest)], [1, 2, 3, 4, 5]);
+});
+
+test("freezeUrl times out when no response headers arrive", { timeout: 5_000 }, async (t) => {
+  fakeClock(t);
+  t.mock.method(
+    globalThis,
+    "fetch",
+    (_url, { signal }) =>
+      new Promise((_, reject) => signal.addEventListener("abort", () => reject(signal.reason))),
+  );
+  const dest = join(mkdtempSync(join(tmpdir(), "media-use-freeze-")), "clip.mp4");
+  const frozen = freezeUrl("https://cdn.example.com/clip.mp4", dest);
+  t.mock.timers.tick(10_000);
+  await assert.rejects(frozen, /no response within 10000 ms/);
+});
+
+test("freezeLocalFile strips the same hostile SVG content from a local source", () => {
+  const srcDir = mkdtempSync(join(tmpdir(), "media-use-freeze-src-"));
+  const src = join(srcDir, "in.svg");
+  writeFileSync(src, HOSTILE_SVG);
+  const dest = join(mkdtempSync(join(tmpdir(), "media-use-freeze-dest-")), "logo.svg");
+  freezeLocalFile(src, dest);
+  const out = readFileSync(dest, "utf8");
+  assert.ok(!out.includes("<script"));
+  assert.ok(!out.includes("onload="));
+});
+
+test("freezeLocalFile still byte-copies a non-SVG file untouched", () => {
+  const srcDir = mkdtempSync(join(tmpdir(), "media-use-freeze-src-"));
+  const src = join(srcDir, "in.png");
+  writeFileSync(src, Buffer.from([0x89, 0x50, 0x4e, 0x47]));
+  const dest = join(mkdtempSync(join(tmpdir(), "media-use-freeze-dest-")), "logo.png");
+  freezeLocalFile(src, dest);
+  assert.deepEqual(readFileSync(dest), Buffer.from([0x89, 0x50, 0x4e, 0x47]));
+});

package/skills/media-use/scripts/lib/grade-analyzer.mjs

@@ -0,0 +1,277 @@
+// Vendored plain-JS copy of packages/core/src/mediaGradeAnalyzer.ts.
+// packages/core/src/mediaGradeAnalyzer.vendoredParity.test.ts guards behavior drift.
+import { execFileSync } from "node:child_process";
+import { basename, extname } from "node:path";
+
+const IMAGE_EXT = new Set([".jpg", ".jpeg", ".png", ".webp", ".gif", ".bmp", ".tif", ".tiff"]);
+const SAMPLE_FRAMES = 5;
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+const ADJUST_LIMITS = {
+  exposure: { min: -2, max: 2 },
+  contrast: { min: -1, max: 1 },
+  whites: { min: -1, max: 1 },
+  blacks: { min: -1, max: 1 },
+  temperature: { min: -1, max: 1 },
+  tint: { min: -1, max: 1 },
+};
+
+function clamp(value, key) {
+  const limit = ADJUST_LIMITS[key];
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(limit.max, Math.max(limit.min, value));
+}
+
+function round(value) {
+  const rounded = Math.round(value * 1000) / 1000;
+  return Object.is(rounded, -0) ? 0 : rounded;
+}
+
+function average(values) {
+  return values.reduce((sum, value) => sum + value, 0) / Math.max(1, values.length);
+}
+
+function probeMedia(mediaPath, ffprobePath) {
+  try {
+    const raw = execFileSync(
+      ffprobePath,
+      [
+        "-v",
+        "error",
+        "-select_streams",
+        "v:0",
+        "-show_entries",
+        "stream=color_space,color_transfer,color_primaries,pix_fmt,duration:format=duration",
+        "-of",
+        "json",
+        "--",
+        mediaPath,
+      ],
+      { encoding: "utf8", timeout: 5_000, stdio: ["ignore", "pipe", "pipe"] },
+    );
+    const parsed = JSON.parse(raw);
+    const stream = Array.isArray(parsed.streams) ? (parsed.streams[0] ?? {}) : {};
+    const duration = Number(stream.duration ?? parsed.format?.duration);
+    const text = (key) =>
+      typeof stream[key] === "string" && stream[key] ? stream[key] : "unknown";
+    return {
+      duration: Number.isFinite(duration) && duration > 0 ? duration : null,
+      colorSpace: text("color_space"),
+      transfer: text("color_transfer"),
+      primaries: text("color_primaries"),
+      pixelFormat: text("pix_fmt"),
+    };
+  } catch {
+    return {
+      duration: null,
+      colorSpace: "unknown",
+      transfer: "unknown",
+      primaries: "unknown",
+      pixelFormat: "unknown",
+    };
+  }
+}
+
+export function parseMediaTreatmentSignalStats(raw) {
+  const frames = [];
+  let current = null;
+  for (const line of String(raw).split(/\r?\n/)) {
+    // One digit is enough: .* consumes the rest without overlapping repetitions.
+    const frame = line.match(/^frame:\d.*pts_time:([+-]?(?:\d+(?:\.\d+)?|\.\d+))/);
+    if (frame) {
+      if (current) frames.push(current);
+      current = { ptsTime: Number(frame[1]) };
+      continue;
+    }
+    const stat = line.match(/lavfi\.signalstats\.([A-Z]+)=([+-]?(?:\d+(?:\.\d+)?|\.\d+))/);
+    if (!stat) continue;
+    current ??= {};
+    current[stat[1]] = Number(stat[2]);
+  }
+  if (current) frames.push(current);
+  return frames.filter(
+    (frame) =>
+      Number.isFinite(frame.YMIN) &&
+      Number.isFinite(frame.YLOW) &&
+      Number.isFinite(frame.YAVG) &&
+      Number.isFinite(frame.YHIGH) &&
+      Number.isFinite(frame.YMAX) &&
+      Number.isFinite(frame.UAVG) &&
+      Number.isFinite(frame.VAVG),
+  );
+}
+
+function summarizeFrames(frames) {
+  if (frames.length === 0) throw new Error("FFmpeg returned no analyzable video frames");
+  return {
+    frames: frames.length,
+    yMin: Math.min(...frames.map((frame) => frame.YMIN)),
+    yLow: average(frames.map((frame) => frame.YLOW)),
+    yAvg: average(frames.map((frame) => frame.YAVG)),
+    yHigh: average(frames.map((frame) => frame.YHIGH)),
+    yMax: Math.max(...frames.map((frame) => frame.YMAX)),
+    uAvg: average(frames.map((frame) => frame.UAVG)),
+    vAvg: average(frames.map((frame) => frame.VAVG)),
+    satAvg: average(frames.map((frame) => frame.SATAVG ?? 0)),
+    shadowClipRisk: average(frames.map((frame) => (frame.YLOW <= 16 ? 1 : 0))),
+    highlightClipRisk: average(frames.map((frame) => (frame.YHIGH >= 235 ? 1 : 0))),
+  };
+}
+
+function suggestedExposure(normalizedAverage, yLow, yHigh) {
+  if (normalizedAverage < 0.28 && yHigh / 255 < 0.65) {
+    return clamp((0.32 - normalizedAverage) * 1.2, "exposure");
+  }
+  if (normalizedAverage > 0.72 && yLow / 255 > 0.3) {
+    return clamp((0.68 - normalizedAverage) * 1.2, "exposure");
+  }
+  return 0;
+}
+
+function suggestedTemperature(uAverage, vAverage) {
+  const chromaWarmth = (vAverage - 128 + (128 - uAverage)) / 128;
+  return Math.abs(chromaWarmth) >= 0.08 ? clamp(-chromaWarmth * 0.25, "temperature") : 0;
+}
+
+function suggestedTint(uAverage, vAverage) {
+  const cast = uAverage + vAverage - 256;
+  return Math.abs(cast) >= 10 ? clamp(-cast / 512, "tint") : 0;
+}
+
+export function statsToAdjust(stats) {
+  const yMin = Number(stats.yMin);
+  const yLow = Number(stats.yLow ?? stats.yMin);
+  const yMax = Number(stats.yMax);
+  const yHigh = Number(stats.yHigh ?? stats.yMax);
+  const yAvg = Number(stats.yAvg);
+  const uAvg = Number(stats.uAvg);
+  const vAvg = Number(stats.vAvg);
+  const shadowClipRisk = Number(stats.shadowClipRisk ?? (yLow <= 16 ? 1 : 0));
+  const highlightClipRisk = Number(stats.highlightClipRisk ?? (yHigh >= 235 ? 1 : 0));
+  const percentileSpread = (yHigh - yLow) / 255;
+  const normalizedAverage = yAvg / 255;
+  const contrast = percentileSpread < 0.35 ? clamp((0.35 - percentileSpread) * 0.4, "contrast") : 0;
+
+  return {
+    adjust: {
+      exposure: round(suggestedExposure(normalizedAverage, yLow, yHigh)),
+      contrast: round(contrast),
+      blacks: round(clamp(shadowClipRisk * 0.08, "blacks")),
+      whites: round(clamp(-highlightClipRisk * 0.08, "whites")),
+      temperature: round(suggestedTemperature(uAvg, vAvg)),
+      tint: round(suggestedTint(uAvg, vAvg)),
+    },
+    measured: {
+      frames: Number(stats.frames ?? 1),
+      yMin: round(yMin),
+      yLow: round(yLow),
+      yAvg: round(yAvg),
+      yHigh: round(yHigh),
+      yMax: round(yMax),
+      uAvg: round(uAvg),
+      vAvg: round(vAvg),
+      satAvg: round(Number(stats.satAvg ?? 0)),
+      shadowClipRisk: round(shadowClipRisk),
+      highlightClipRisk: round(highlightClipRisk),
+    },
+  };
+}
+
+export function summarizeMediaTreatmentAnalysis(probe, frames) {
+  const result = statsToAdjust(summarizeFrames(frames));
+  const hdr = ["smpte2084", "arib-std-b67"].includes(probe.transfer);
+  const diagnosis = [];
+  if (result.measured.shadowClipRisk > 0) {
+    diagnosis.push("sampled frames contain deep or clipped shadows");
+  }
+  if (result.measured.highlightClipRisk > 0) {
+    diagnosis.push("sampled frames contain bright or clipped highlights");
+  }
+  if (diagnosis.length === 0) diagnosis.push("no obvious technical imbalance in sampled frames");
+
+  const warnings = [];
+  if (hdr) warnings.push("HDR transfer detected; the realtime treatment path is SDR/Rec.709.");
+  if (probe.colorSpace === "unknown" || probe.transfer === "unknown") {
+    warnings.push(
+      "Source color metadata is incomplete; camera LOG cannot be identified reliably from container metadata alone.",
+    );
+  }
+
+  return {
+    ...result,
+    source: {
+      colorSpace: probe.colorSpace,
+      transfer: probe.transfer,
+      primaries: probe.primaries,
+      pixelFormat: probe.pixelFormat,
+      hdr,
+      log: "unknown",
+    },
+    diagnosis,
+    warnings,
+  };
+}
+
+export function gradeSampleTimes(duration) {
+  return Array.from({ length: SAMPLE_FRAMES }, (_, i) => (duration * (i + 0.5)) / SAMPLE_FRAMES);
+}
+
+function readSignalStats(ffmpegPath, mediaPath, seekSeconds, frames) {
+  const timeoutMs = Number(process.env.HYPERFRAMES_ANALYZE_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS;
+  const keyframeSeek =
+    seekSeconds === null ? [] : ["-noaccurate_seek", "-ss", seekSeconds.toFixed(3)];
+  try {
+    return execFileSync(
+      ffmpegPath,
+      [
+        "-hide_banner",
+        "-nostdin",
+        "-v",
+        "error",
+        ...keyframeSeek,
+        "-i",
+        mediaPath,
+        "-vf",
+        `trim=end_frame=${frames},format=yuv444p,signalstats,metadata=print:file=-`,
+        "-frames:v",
+        String(frames),
+        "-f",
+        "null",
+        "-",
+      ],
+      { encoding: "utf8", timeout: timeoutMs, stdio: ["ignore", "pipe", "pipe"] },
+    );
+  } catch (error) {
+    if (error.code !== "ETIMEDOUT") throw error;
+    const target =
+      seekSeconds === null
+        ? `the first ${frames} frames`
+        : `the frame at ${seekSeconds.toFixed(1)}s`;
+    throw new Error(
+      `FFmpeg took longer than ${timeoutMs / 1000}s to measure ${target}; set HYPERFRAMES_ANALYZE_TIMEOUT_MS to allow more`,
+    );
+  }
+}
+
+export function analyzeMediaGrade(
+  mediaPath,
+  { ffmpegPath = "ffmpeg", ffprobePath = "ffprobe" } = {},
+) {
+  try {
+    const probe = probeMedia(mediaPath, ffprobePath);
+    const isImage = IMAGE_EXT.has(extname(mediaPath).toLowerCase());
+    const raw =
+      !isImage && probe.duration
+        ? gradeSampleTimes(probe.duration)
+            .map((time) => readSignalStats(ffmpegPath, mediaPath, time, 1))
+            .join("\n")
+        : readSignalStats(ffmpegPath, mediaPath, null, SAMPLE_FRAMES);
+    return summarizeMediaTreatmentAnalysis(probe, parseMediaTreatmentSignalStats(raw));
+  } catch (error) {
+    throw new Error(`grade analysis failed for ${mediaPath}: ${error.message}`);
+  }
+}
+
+export function formatMeasuredNote(mediaPath, measured) {
+  return `media-use: measured ${basename(mediaPath)}: frames=${measured.frames}, YMIN=${measured.yMin}, YLOW=${measured.yLow}, YAVG=${measured.yAvg}, YHIGH=${measured.yHigh}, YMAX=${measured.yMax}, UAVG=${measured.uAvg}, VAVG=${measured.vAvg}; adjust is a starting suggestion`;
+}