Merge pull request #2798 from heygen-com/feat/agent-native-color-grading

feat(cli): expose agent-native color grading

packages/cli/src/commands/media-treatment-analysis.ts

@@ -0,0 +1,20 @@
+import {
+  analyzeMediaGrade,
+  type MediaTreatmentAnalysis,
+} from "@hyperframes/core/media-grade-analyzer";
+import { findFFmpeg, findFFprobe, getFFmpegInstallHint } from "../browser/ffmpeg.js";
+
+interface CliMediaTreatmentAnalysis extends Omit<MediaTreatmentAnalysis, "adjust"> {
+  suggestedPatch: { adjust: MediaTreatmentAnalysis["adjust"] };
+}
+
+export function analyzeMediaTreatment(mediaPath: string): CliMediaTreatmentAnalysis {
+  const ffmpegPath = findFFmpeg();
+  const ffprobePath = findFFprobe();
+  if (!ffmpegPath || !ffprobePath) {
+    throw new Error(`FFmpeg and ffprobe are required. ${getFFmpegInstallHint()}`);
+  }
+  const analysis = analyzeMediaGrade(mediaPath, { ffmpegPath, ffprobePath });
+  const { adjust, ...evidence } = analysis;
+  return { ...evidence, suggestedPatch: { adjust } };
+}

packages/cli/src/commands/media-treatment.test.ts

@@ -1,6 +1,6 @@
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { runCommand } from "citty";
 import { describe, expect, it, vi } from "vitest";
 import {
@@ -12,6 +12,7 @@ import {
   getMediaTreatmentCapabilityDetail,
   getMediaTreatmentCapabilityOverview,
   mediaTreatmentCommand,
+  resolveMediaTreatmentSource,
 } from "./media-treatment.js";
 import { CliRuntimeError } from "../utils/commandResult.js";
 
@@ -22,6 +23,9 @@ describe("applyMediaTreatmentToHtml", () => {
     const overview = getMediaTreatmentCapabilityOverview();
 
     expect(overview.families.find(({ id }) => id === "correction")).not.toHaveProperty("items");
+    expect(overview.families.find(({ id }) => id === "grading")).toMatchObject({
+      label: "Color Grading",
+    });
     expect(overview.families.find(({ id }) => id === "art")).not.toHaveProperty("items");
     expect(overview.families.find(({ id }) => id === "overlays")).toMatchObject({
       owner: "registry",
@@ -76,6 +80,40 @@ describe("applyMediaTreatmentToHtml", () => {
       family: "finishing",
       control: expect.objectContaining({ key: "vignette" }),
     });
+    expect(getMediaTreatmentCapabilityDetail("wheels")).toMatchObject({
+      contract: expect.objectContaining({ zones: ["shadows", "midtones", "highlights"] }),
+    });
+    expect(getMediaTreatmentCapabilityDetail("curves")).toMatchObject({
+      contract: expect.objectContaining({ channels: ["master", "red", "green", "blue"] }),
+    });
+    const hueCurves = getMediaTreatmentCapabilityDetail("hue-curves");
+    const serializedHueCurves = JSON.stringify(hueCurves);
+    expect(serializedHueCurves).toContain('"maxPoints":16');
+    expect(serializedHueCurves).toContain('"key":"hueVsHue"');
+    expect(serializedHueCurves).toContain('"key":"hueVsSaturation"');
+    expect(serializedHueCurves).toContain('"key":"hueVsLuma"');
+    expect(getMediaTreatmentCapabilityDetail("secondary")).toMatchObject({
+      contract: expect.objectContaining({
+        max: 4,
+        saturation: expect.objectContaining({ relation: "min < max" }),
+        luma: expect.objectContaining({ relation: "min < max" }),
+      }),
+    });
+    expect(getMediaTreatmentCapabilityDetail("grading")).toMatchObject({
+      order: [
+        "adjust",
+        "wheels",
+        "curves",
+        "hueCurves",
+        "secondaries",
+        "lut",
+        "details",
+        "effects",
+      ],
+    });
+    expect(getMediaTreatmentCapabilityDetail("scopes")).toMatchObject({
+      command: expect.stringContaining("--analyze"),
+    });
   });
 
   it("rejects unknown capability lookups", () => {
@@ -113,6 +151,118 @@ describe("applyMediaTreatmentToHtml", () => {
     expect(result.html).toContain("data-color-grading=");
   });
 
+  it("normalizes and persists advanced grading on real media", () => {
+    const result = applyMediaTreatmentToHtml(VIDEO, {
+      selector: "#hero",
+      grading: {
+        wheels: { shadows: { hue: 205, amount: 0.08, level: 0.02 } },
+        curves: {
+          master: [
+            [0, 0],
+            [0.5, 0.55],
+            [1, 1],
+          ],
+        },
+        hueCurves: {
+          hueVsSaturation: [
+            [180, 0],
+            [210, 0.15],
+            [240, 0],
+          ],
+        },
+        secondaries: [
+          {
+            key: {
+              hue: { center: 215, range: 25, softness: 10 },
+              saturation: { min: 0.2, max: 1, softness: 0.08 },
+              luma: { min: 0.1, max: 0.9, softness: 0.08 },
+            },
+            correction: { saturation: 0.15, luma: 0.03 },
+          },
+        ],
+      },
+    });
+
+    expect(result.changed).toBe(true);
+    expect(result.value).toContain('"wheels"');
+    expect(result.value).toContain('"curves"');
+    expect(result.value).toContain('"hueCurves"');
+    expect(result.value).toContain('"secondaries"');
+  });
+
+  it("persists a disabled secondary without treating it as an active grade", () => {
+    const result = applyMediaTreatmentToHtml(VIDEO, {
+      selector: "#hero",
+      grading: {
+        secondaries: [
+          {
+            enabled: false,
+            key: { hue: { center: 215, range: 25 } },
+            correction: { saturation: 0.15 },
+          },
+        ],
+      },
+    });
+
+    expect(result.changed).toBe(true);
+    expect(result.value).toContain('"enabled":false');
+    expect(result.value).toContain('"secondaries"');
+  });
+
+  it("resolves nested composition media through the shared project-root contract", () => {
+    const project = mkdtempSync(join(tmpdir(), "hf-media-treatment-assets-"));
+    const escapedAsset = join(project, "..", `${basename(project)}-escape.mp4`);
+    mkdirSync(join(project, "capture"), { recursive: true });
+    mkdirSync(join(project, "assets"), { recursive: true });
+    writeFileSync(join(project, "capture", "talking-head.mp4"), "");
+    writeFileSync(join(project, "assets", "photo.webp"), "");
+    writeFileSync(join(project, "assets", "My Clip.mp4"), "");
+    writeFileSync(escapedAsset, "");
+
+    try {
+      expect(
+        resolveMediaTreatmentSource(
+          project,
+          "compositions/scene.html",
+          "../capture/talking-head.mp4?v=1#frame",
+        ),
+      ).toBe(join(project, "capture/talking-head.mp4"));
+      expect(
+        resolveMediaTreatmentSource(project, "compositions/scene.html", "assets/photo.webp"),
+      ).toBe(join(project, "assets/photo.webp"));
+      expect(
+        resolveMediaTreatmentSource(
+          project,
+          "compositions/scene.html",
+          "/assets/My%20Clip.mp4?v=1",
+        ),
+      ).toBe(join(project, "assets/My Clip.mp4"));
+      expect(() =>
+        resolveMediaTreatmentSource(
+          project,
+          "compositions/scene.html",
+          "https://example.com/a.mp4",
+        ),
+      ).toThrow(/local project asset/);
+      expect(() => resolveMediaTreatmentSource(project, "compositions/scene.html", "#")).toThrow(
+        /local project asset/,
+      );
+      expect(() =>
+        resolveMediaTreatmentSource(project, "compositions/scene.html", "missing.mp4"),
+      ).toThrow(/Media file not found/);
+      expect(() =>
+        resolveMediaTreatmentSource(
+          project,
+          "compositions/scene.html",
+          `../../${basename(escapedAsset)}`,
+        ),
+      ).toThrow(/Media file not found/);
+    } finally {
+      rmSync(project, { recursive: true, force: true });
+      rmSync(escapedAsset, { force: true });
+    }
+  });
+
   it("merges a validated patch and reports the stored before and after payloads", () => {
     const initial = applyMediaTreatmentToHtml(VIDEO, {
       selector: "#hero",

packages/cli/src/commands/media-treatment.ts

@@ -3,7 +3,7 @@ import { relative, resolve } from "node:path";
 import {
   HF_COLOR_GRADING_ATTR,
   getHfColorGradingCapabilities,
-  isHfColorGradingActive,
+  hasHfColorGradingAuthoredValues,
   isPathInside,
   normalizeHfColorGrading,
   serializeHfColorGrading,
@@ -12,6 +12,12 @@ import {
   isColorGradingVariableRef,
   validateColorGradingContract,
 } from "@hyperframes/parsers/color-grading-contract";
+import {
+  cleanAssetUrl,
+  isRemoteOrInlineUrl,
+  resolveExistingLocalAsset,
+} from "@hyperframes/parsers/asset-resolution";
+import { rewriteAssetPath } from "@hyperframes/parsers/asset-paths";
 import { patchElementInHtml } from "@hyperframes/studio-server/source-mutation";
 import { defineCommand } from "citty";
 import { parseHTML } from "linkedom";
@@ -22,6 +28,7 @@ import { normalizeErrorMessage } from "../utils/errorMessage.js";
 import { readOptionalString } from "../utils/pathArgs.js";
 import { resolveProject } from "../utils/project.js";
 import { withMeta } from "../utils/updateCheck.js";
+import { analyzeMediaTreatment } from "./media-treatment-analysis.js";
 
 export function getMediaTreatmentCapabilityOverview() {
   const capabilities = getHfColorGradingCapabilities();
@@ -37,6 +44,11 @@ export function getMediaTreatmentCapabilityOverview() {
     colorSpace: capabilities.colorSpace,
     families: [
       family("correction", "Adjust", "Fix exposure, tonal balance, color casts, and saturation."),
+      family(
+        "grading",
+        "Color Grading",
+        "Shape tonal color with wheels, RGB and hue curves, and selective HSL correction.",
+      ),
       family(
         "presets",
         "Presets",
@@ -157,11 +169,96 @@ export function getMediaTreatmentCapabilityDetail(id: string): unknown {
   if (palette) return { ...palette, apply: { palette: palette.colors } };
 
   const details = {
+    grading: {
+      id,
+      description:
+        "Shape media after primary correction with wheels, curves, HSL secondaries, and an optional user-owned LUT.",
+      order: [
+        "adjust",
+        "wheels",
+        "curves",
+        "hueCurves",
+        "secondaries",
+        "lut",
+        "details",
+        "effects",
+      ],
+      discover: ["wheels", "curves", "hue-curves", "secondary", "scopes", "lut"],
+    },
     correction: {
       id,
       description: "Fix exposure, tonal balance, color casts, and saturation.",
       controls: capabilities.adjustments,
     },
+    wheels: {
+      id,
+      description: "Shadow, midtone, and highlight color wheels.",
+      contract: capabilities.wheels,
+      apply: {
+        wheels: {
+          shadows: { hue: 205, amount: 0.08, level: 0 },
+          highlights: { hue: 35, amount: 0.06, level: 0 },
+        },
+      },
+    },
+    curves: {
+      id,
+      description: "Master and per-channel curves using normalized [input, output] points.",
+      contract: capabilities.curves,
+      apply: {
+        curves: {
+          master: [
+            [0, 0],
+            [0.25, 0.2],
+            [0.75, 0.82],
+            [1, 1],
+          ],
+        },
+      },
+    },
+    "hue-curves": {
+      id,
+      description: "Hue-selective curves using [hueDegrees, delta] points.",
+      contract: capabilities.hueCurves,
+      apply: {
+        hueCurves: {
+          hueVsSaturation: [
+            [180, 0],
+            [210, 0.15],
+            [240, 0],
+          ],
+        },
+      },
+    },
+    secondary: {
+      id,
+      description: "Up to four ordered HSL selections with bounded color correction.",
+      contract: capabilities.secondaries,
+      apply: {
+        secondaries: [
+          {
+            key: {
+              hue: { center: 215, range: 25, softness: 10 },
+              saturation: { min: 0.2, max: 1, softness: 0.08 },
+              luma: { min: 0.1, max: 0.9, softness: 0.08 },
+            },
+            correction: { saturation: 0.15, luma: 0.03 },
+          },
+        ],
+      },
+    },
+    scopes: {
+      id,
+      description:
+        "Deterministic source measurements for agent decisions; visual scopes remain a Studio display.",
+      command:
+        "hyperframes media-treatment --file compositions/scene.html --selector '#hero' --analyze --json",
+      output: [
+        "source color metadata and HDR/LOG warnings",
+        "luma percentile and clipping evidence",
+        "bounded suggested primary correction",
+      ],
+    },
     presets: {
       id,
       description: "Tested starting points for color and stylized media effects.",
@@ -222,6 +319,10 @@ export const examples: Example[] = [
     "Preview the exact mutation without writing",
     `hyperframes media-treatment --file compositions/scene.html --selector 'video' --grading '{"preset":"warm-daylight"}' --apply --dry-run --json`,
   ],
+  [
+    "Measure one local media source before choosing a correction",
+    `hyperframes media-treatment --selector '#hero' --analyze --json`,
+  ],
   ["Remove a treatment", `hyperframes media-treatment --selector '#hero' --clear`],
 ];
 
@@ -298,7 +399,7 @@ function serializeGradingPatch(before: unknown, patch: unknown): string | null {
   }
   const normalized = normalizeHfColorGrading(grading);
   if (!normalized) throw new Error("--grading must be valid HyperFrames color-grading JSON");
-  return isHfColorGradingActive(normalized) ? serializeHfColorGrading(normalized) : null;
+  return hasHfColorGradingAuthoredValues(normalized) ? serializeHfColorGrading(normalized) : null;
 }
 
 function queryIncludingTemplates(root: Document | Element, selector: string): Element[] {
@@ -375,6 +476,38 @@ function parseSelectorIndex(raw: string | undefined): number | undefined {
   return value;
 }
 
+function mediaSourceForElement(element: Element): string {
+  const src =
+    element.getAttribute("src") ??
+    (element.tagName.toLowerCase() === "video"
+      ? element.querySelector("source")?.getAttribute("src")
+      : null);
+  if (!src) throw new Error("Selected media has no analyzable src");
+  return src;
+}
+
+export function resolveMediaTreatmentSource(
+  projectDir: string,
+  compositionFile: string,
+  source: string,
+): string {
+  const sourceUrl = source.trim();
+  if (!sourceUrl) throw new Error("Selected media has no analyzable local src");
+  if (isRemoteOrInlineUrl(sourceUrl)) {
+    throw new Error(
+      "Media analysis requires a local project asset; freeze remote media with media-use first",
+    );
+  }
+  const cleanSource = cleanAssetUrl(sourceUrl);
+  if (!cleanSource) throw new Error("Selected media has no analyzable local src");
+  const projectRelative = cleanSource.startsWith("/")
+    ? cleanSource
+    : rewriteAssetPath(compositionFile, cleanSource);
+  const asset = resolveExistingLocalAsset(projectDir, projectRelative);
+  if (!asset) throw new Error(`Media file not found: ${source}`);
+  return asset.resolved;
+}
+
 function parseGrading(raw: string | undefined, apply: boolean, clear: boolean): unknown {
   if (clear) {
     if (raw !== undefined || apply) {
@@ -400,6 +533,157 @@ function mutationVerb(action: "apply" | "clear", changed: boolean, dryRun: boole
   return action === "apply" ? "Applied" : "Cleared";
 }
 
+interface MediaTreatmentCommandArgs {
+  capabilities?: boolean;
+  capability?: string;
+  all?: boolean;
+  project?: string;
+  file?: string;
+  selector?: string;
+  "selector-index"?: string;
+  grading?: string;
+  apply?: boolean;
+  analyze?: boolean;
+  clear?: boolean;
+  "dry-run"?: boolean;
+  json?: boolean;
+}
+
+function runCapabilityQuery(args: MediaTreatmentCommandArgs): void {
+  const capability = readOptionalString(args.capability);
+  const hasMutationOption = [
+    readOptionalString(args.selector),
+    readOptionalString(args.grading),
+    args.clear,
+    args["dry-run"],
+    args.apply,
+    args.analyze,
+  ].some(Boolean);
+  if (hasMutationOption) throw new Error("--capabilities cannot be combined with mutation options");
+  if (args.all === true && capability)
+    throw new Error("Use either --all or --capability, not both");
+
+  let capabilities: unknown = getMediaTreatmentCapabilityOverview();
+  if (args.all === true) capabilities = getHfColorGradingCapabilities();
+  else if (capability) capabilities = getMediaTreatmentCapabilityDetail(capability);
+  console.log(JSON.stringify(withMeta({ ok: true, capabilities }), null, 2));
+}
+
+function resolveMutationFile(args: MediaTreatmentCommandArgs) {
+  const project = resolveProject(readOptionalString(args.project));
+  const fileArg = readOptionalString(args.file) ?? "index.html";
+  const filePath = resolve(project.dir, fileArg);
+  if (!isPathInside(filePath, project.dir) || !filePath.toLowerCase().endsWith(".html")) {
+    throw new Error("--file must be an HTML file inside the project");
+  }
+  if (!existsSync(filePath)) throw new Error(`Composition file not found: ${fileArg}`);
+  return { project, filePath };
+}
+
+function analyzeTarget(args: MediaTreatmentCommandArgs) {
+  const { project, filePath } = resolveMutationFile(args);
+  const selector = readOptionalString(args.selector);
+  if (!selector) throw new Error("--selector is required");
+  if (
+    readOptionalString(args.grading) ||
+    args.clear === true ||
+    args.apply === true ||
+    args["dry-run"] === true
+  ) {
+    throw new Error("--analyze cannot be combined with mutation options");
+  }
+  const selectorIndex = parseSelectorIndex(readOptionalString(args["selector-index"]));
+  const { element, tag } = selectMediaElement(
+    readFileSync(filePath, "utf8"),
+    selector,
+    selectorIndex,
+  );
+  const source = mediaSourceForElement(element);
+  const compositionFile = relative(project.dir, filePath).split("\\").join("/");
+  const mediaPath = resolveMediaTreatmentSource(project.dir, compositionFile, source);
+  return {
+    ok: true,
+    action: "analyze",
+    file: compositionFile || "index.html",
+    selector,
+    selectorIndex: selectorIndex ?? 0,
+    tag,
+    media: source,
+    ...analyzeMediaTreatment(mediaPath),
+  };
+}
+
+function prepareMutation(args: MediaTreatmentCommandArgs) {
+  const { project, filePath } = resolveMutationFile(args);
+  const selector = readOptionalString(args.selector);
+  if (!selector) throw new Error("--selector is required");
+  const clear = args.clear === true;
+  const apply = args.apply === true;
+  const selectorIndex = parseSelectorIndex(readOptionalString(args["selector-index"]));
+  const result = applyMediaTreatmentToHtml(readFileSync(filePath, "utf8"), {
+    selector,
+    selectorIndex,
+    grading: parseGrading(readOptionalString(args.grading), apply, clear),
+    clear,
+  });
+  const dryRun = args["dry-run"] === true;
+  if (result.changed && !dryRun) writeFileSync(filePath, result.html);
+
+  const action: "clear" | "apply" = result.value === null ? "clear" : "apply";
+  return {
+    action,
+    result,
+    selector,
+    payload: {
+      ok: true,
+      action,
+      file: relative(project.dir, filePath) || "index.html",
+      selector,
+      selectorIndex: selectorIndex ?? 0,
+      tag: result.tag,
+      changed: result.changed,
+      dryRun,
+      before: result.before,
+      after: result.after,
+    },
+  };
+}
+
+function isCapabilityQuery(args: MediaTreatmentCommandArgs): boolean {
+  return (
+    args.capabilities === true || Boolean(readOptionalString(args.capability)) || args.all === true
+  );
+}
+
+function printAnalysis(args: MediaTreatmentCommandArgs): void {
+  const result = analyzeTarget(args);
+  if (args.json === true) {
+    console.log(JSON.stringify(withMeta(result), null, 2));
+    return;
+  }
+  console.log(`${c.success("◇")}  Analyzed ${c.accent(result.selector)}`);
+  for (const diagnosis of result.diagnosis) console.log(`   ${diagnosis}`);
+  for (const warning of result.warnings) console.log(`   ${c.warn(warning)}`);
+  console.log(`   suggested patch: ${JSON.stringify(result.suggestedPatch)}`);
+}
+
+function printMutation(args: MediaTreatmentCommandArgs): void {
+  const { action, result, selector, payload } = prepareMutation(args);
+  if (args.json === true) {
+    console.log(JSON.stringify(withMeta(payload), null, 2));
+    return;
+  }
+  const verb = mutationVerb(action, result.changed, payload.dryRun);
+  console.log(`${c.success("◇")}  ${verb} media treatment on ${c.accent(selector)}`);
+}
+
+function printFailure(error: unknown, json: boolean): void {
+  const message = normalizeErrorMessage(error);
+  if (json) console.log(JSON.stringify(withMeta({ ok: false, error: message })));
+  else console.error(`${c.error("✗")} ${message}`);
+  failCommand();
+}
+
 export const mediaTreatmentCommand = defineCommand({
   meta: {
     name: "media-treatment",
@@ -439,6 +723,11 @@ export const mediaTreatmentCommand = defineCommand({
       description: "Apply the validated grading patch (explicit agent form)",
       default: false,
     },
+    analyze: {
+      type: "boolean",
+      description: "Measure selected local media and suggest a bounded primary correction",
+      default: false,
+    },
     clear: { type: "boolean", description: "Remove color grading from the target", default: false },
     "dry-run": {
       type: "boolean",
@@ -448,90 +737,15 @@ export const mediaTreatmentCommand = defineCommand({
     json: { type: "boolean", description: "Output an agent-friendly JSON result", default: false },
   },
   run({ args }) {
-    const runCapabilityQuery = () => {
-      const capability = readOptionalString(args.capability);
-      const hasMutationOption = [
-        readOptionalString(args.selector),
-        readOptionalString(args.grading),
-        args.clear,
-        args["dry-run"],
-        args.apply,
-      ].some(Boolean);
-      if (hasMutationOption) {
-        throw new Error("--capabilities cannot be combined with mutation options");
-      }
-      if (args.all === true && capability) {
-        throw new Error("Use either --all or --capability, not both");
-      }
-      let capabilities: unknown = getMediaTreatmentCapabilityOverview();
-      if (args.all === true) capabilities = getHfColorGradingCapabilities();
-      else if (capability) capabilities = getMediaTreatmentCapabilityDetail(capability);
-      console.log(JSON.stringify(withMeta({ ok: true, capabilities }), null, 2));
-    };
-
-    const resolveMutationFile = () => {
-      const project = resolveProject(readOptionalString(args.project));
-      const fileArg = readOptionalString(args.file) ?? "index.html";
-      const filePath = resolve(project.dir, fileArg);
-      if (!isPathInside(filePath, project.dir) || !filePath.toLowerCase().endsWith(".html")) {
-        throw new Error("--file must be an HTML file inside the project");
-      }
-      if (!existsSync(filePath)) throw new Error(`Composition file not found: ${fileArg}`);
-      return { project, filePath };
-    };
-
-    const prepareMutation = () => {
-      const { project, filePath } = resolveMutationFile();
-      const selector = readOptionalString(args.selector);
-      if (!selector) throw new Error("--selector is required");
-      const clear = args.clear === true;
-      const apply = args.apply === true;
-      const selectorIndex = parseSelectorIndex(readOptionalString(args["selector-index"]));
-      const result = applyMediaTreatmentToHtml(readFileSync(filePath, "utf8"), {
-        selector,
-        selectorIndex,
-        grading: parseGrading(readOptionalString(args.grading), apply, clear),
-        clear,
-      });
-      const dryRun = args["dry-run"] === true;
-      if (result.changed && !dryRun) writeFileSync(filePath, result.html);
-
-      const action: "clear" | "apply" = result.value === null ? "clear" : "apply";
-      return {
-        action,
-        result,
-        selector,
-        payload: {
-          ok: true,
-          action,
-          file: relative(project.dir, filePath) || "index.html",
-          selector,
-          selectorIndex: selectorIndex ?? 0,
-          tag: result.tag,
-          changed: result.changed,
-          dryRun,
-          before: result.before,
-          after: result.after,
-        },
-      };
-    };
-
     try {
-      if (args.capabilities === true || readOptionalString(args.capability) || args.all === true) {
-        return runCapabilityQuery();
-      }
-      const { action, result, selector, payload } = prepareMutation();
-      if (args.json === true) {
-        console.log(JSON.stringify(withMeta(payload), null, 2));
-      } else {
-        const verb = mutationVerb(action, result.changed, payload.dryRun);
-        console.log(`${c.success("◇")}  ${verb} media treatment on ${c.accent(selector)}`);
+      if (isCapabilityQuery(args)) return runCapabilityQuery(args);
+      if (args.analyze === true) {
+        printAnalysis(args);
+        return;
       }
+      printMutation(args);
     } catch (error) {
-      const message = normalizeErrorMessage(error);
-      if (args.json === true) console.log(JSON.stringify(withMeta({ ok: false, error: message })));
-      else console.error(`${c.error("✗")} ${message}`);
-      failCommand();
+      printFailure(error, args.json === true);
     }
   },
 });

packages/core/package-subpaths.json

@@ -86,6 +86,12 @@
       "types": "./dist/colorLuts.d.ts",
       "environments": ["browser", "bun", "node"]
     },
+    "./media-grade-analyzer": {
+      "source": "./src/mediaGradeAnalyzer.ts",
+      "runtime": "./dist/mediaGradeAnalyzer.js",
+      "types": "./dist/mediaGradeAnalyzer.d.ts",
+      "environments": ["bun", "node"]
+    },
     "./storyboard": {
       "source": "./src/storyboard/index.ts",
       "runtime": "./dist/storyboard/index.js",

packages/core/package.json

@@ -100,6 +100,12 @@
       "import": "./src/colorLuts.ts",
       "types": "./src/colorLuts.ts"
     },
+    "./media-grade-analyzer": {
+      "bun": "./src/mediaGradeAnalyzer.ts",
+      "node": "./dist/mediaGradeAnalyzer.js",
+      "import": "./src/mediaGradeAnalyzer.ts",
+      "types": "./src/mediaGradeAnalyzer.ts"
+    },
     "./storyboard": {
       "bun": "./src/storyboard/index.ts",
       "node": "./dist/storyboard/index.js",
@@ -334,6 +340,10 @@
         "import": "./dist/colorLuts.js",
         "types": "./dist/colorLuts.d.ts"
       },
+      "./media-grade-analyzer": {
+        "import": "./dist/mediaGradeAnalyzer.js",
+        "types": "./dist/mediaGradeAnalyzer.d.ts"
+      },
       "./storyboard": {
         "import": "./dist/storyboard/index.js",
         "types": "./dist/storyboard/index.d.ts"

packages/core/src/mediaGradeAnalyzer.ts

@@ -0,0 +1,356 @@
+import { execFileSync } from "node:child_process";
+import { basename, extname } from "node:path";
+
+const IMAGE_EXTENSIONS = new Set([
+  ".jpg",
+  ".jpeg",
+  ".png",
+  ".webp",
+  ".gif",
+  ".bmp",
+  ".tif",
+  ".tiff",
+]);
+const SAMPLE_FRAMES = 5;
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+export interface GradeSignalFrame {
+  [key: string]: number | undefined;
+  ptsTime?: number;
+  YMIN?: number;
+  YLOW?: number;
+  YAVG?: number;
+  YHIGH?: number;
+  YMAX?: number;
+  UAVG?: number;
+  VAVG?: number;
+  SATAVG?: number;
+}
+
+export interface GradeMediaProbe {
+  duration: number | null;
+  colorSpace: string;
+  transfer: string;
+  primaries: string;
+  pixelFormat: string;
+}
+
+export interface MediaGradeAdjust {
+  exposure: number;
+  contrast: number;
+  whites: number;
+  blacks: number;
+  temperature: number;
+  tint: number;
+}
+
+export interface MediaTreatmentMeasurements {
+  frames: number;
+  yMin: number;
+  yLow: number;
+  yAvg: number;
+  yHigh: number;
+  yMax: number;
+  uAvg: number;
+  vAvg: number;
+  satAvg: number;
+  shadowClipRisk: number;
+  highlightClipRisk: number;
+}
+
+export interface MediaTreatmentAnalysis {
+  adjust: MediaGradeAdjust;
+  measured: MediaTreatmentMeasurements;
+  source: {
+    colorSpace: string;
+    transfer: string;
+    primaries: string;
+    pixelFormat: string;
+    hdr: boolean;
+    log: "unknown";
+  };
+  diagnosis: string[];
+  warnings: string[];
+}
+
+type AdjustKey = keyof MediaGradeAdjust;
+type NumericStats = Readonly<Record<string, number | undefined>>;
+
+const ADJUST_LIMITS: Record<AdjustKey, { min: number; max: number }> = {
+  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: number, key: AdjustKey): number {
+  const limit = ADJUST_LIMITS[key];
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(limit.max, Math.max(limit.min, value));
+}
+
+function round(value: number): number {
+  const rounded = Math.round(value * 1000) / 1000;
+  return Object.is(rounded, -0) ? 0 : rounded;
+}
+
+function average(values: number[]): number {
+  return values.reduce((sum, value) => sum + value, 0) / Math.max(1, values.length);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return isRecord(value) ? value : {};
+}
+
+function probeMedia(mediaPath: string, ffprobePath: string): GradeMediaProbe {
+  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 = asRecord(JSON.parse(raw));
+    const streams = Array.isArray(parsed.streams) ? parsed.streams : [];
+    const stream = asRecord(streams[0]);
+    const format = asRecord(parsed.format);
+    const duration = Number(stream.duration ?? format.duration);
+    const text = (key: string) => {
+      const value = stream[key];
+      return typeof value === "string" && value ? value : "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: string): GradeSignalFrame[] {
+  const frames: GradeSignalFrame[] = [];
+  let current: GradeSignalFrame | null = null;
+  for (const line of raw.split(/\r?\n/)) {
+    const frame = line.match(/^frame:\d+.*pts_time:([+-]?(?:\d+(?:\.\d+)?|\.\d+))/);
+    if (frame?.[1]) {
+      if (current) frames.push(current);
+      current = { ptsTime: Number(frame[1]) };
+      continue;
+    }
+    const stat = line.match(/lavfi\.signalstats\.([A-Z]+)=([+-]?(?:\d+(?:\.\d+)?|\.\d+))/);
+    if (!stat?.[1] || !stat[2]) 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: readonly GradeSignalFrame[]): NumericStats {
+  if (frames.length === 0) throw new Error("FFmpeg returned no analyzable video frames");
+  const values = (key: string) => frames.map((frame) => Number(frame[key]));
+  return {
+    frames: frames.length,
+    yMin: Math.min(...values("YMIN")),
+    yLow: average(values("YLOW")),
+    yAvg: average(values("YAVG")),
+    yHigh: average(values("YHIGH")),
+    yMax: Math.max(...values("YMAX")),
+    uAvg: average(values("UAVG")),
+    vAvg: average(values("VAVG")),
+    satAvg: average(frames.map((frame) => frame.SATAVG ?? 0)),
+    shadowClipRisk: average(frames.map((frame) => (Number(frame.YLOW) <= 16 ? 1 : 0))),
+    highlightClipRisk: average(frames.map((frame) => (Number(frame.YHIGH) >= 235 ? 1 : 0))),
+  };
+}
+
+function suggestedExposure(normalizedAverage: number, yLow: number, yHigh: number): number {
+  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: number, vAverage: number): number {
+  const chromaWarmth = (vAverage - 128 + (128 - uAverage)) / 128;
+  return Math.abs(chromaWarmth) >= 0.08 ? clamp(-chromaWarmth * 0.25, "temperature") : 0;
+}
+
+function suggestedTint(uAverage: number, vAverage: number): number {
+  const cast = uAverage + vAverage - 256;
+  return Math.abs(cast) >= 10 ? clamp(-cast / 512, "tint") : 0;
+}
+
+export function statsToAdjust(
+  stats: NumericStats,
+): Pick<MediaTreatmentAnalysis, "adjust" | "measured"> {
+  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: GradeMediaProbe,
+  frames: readonly GradeSignalFrame[],
+): MediaTreatmentAnalysis {
+  const result = statsToAdjust(summarizeFrames(frames));
+  const hdr = ["smpte2084", "arib-std-b67"].includes(probe.transfer);
+  const diagnosis: string[] = [];
+  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: string[] = [];
+  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 analyzeMediaGrade(
+  mediaPath: string,
+  options: { ffmpegPath?: string; ffprobePath?: string } = {},
+): MediaTreatmentAnalysis {
+  const ffmpegPath = options.ffmpegPath ?? "ffmpeg";
+  const ffprobePath = options.ffprobePath ?? "ffprobe";
+  try {
+    const probe = probeMedia(mediaPath, ffprobePath);
+    const isImage = IMAGE_EXTENSIONS.has(extname(mediaPath).toLowerCase());
+    const fps =
+      !isImage && probe.duration
+        ? Math.max(0.1, Math.min(2, SAMPLE_FRAMES / probe.duration))
+        : null;
+    const filters = [
+      fps ? `fps=${fps.toFixed(4)}` : null,
+      "format=yuv444p",
+      "signalstats",
+      "metadata=print:file=-",
+    ]
+      .filter(Boolean)
+      .join(",");
+    const raw = execFileSync(
+      ffmpegPath,
+      [
+        "-hide_banner",
+        "-nostdin",
+        "-v",
+        "error",
+        "-i",
+        mediaPath,
+        "-vf",
+        filters,
+        "-frames:v",
+        String(SAMPLE_FRAMES),
+        "-f",
+        "null",
+        "-",
+      ],
+      {
+        encoding: "utf8",
+        timeout: Number(process.env.HYPERFRAMES_ANALYZE_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS,
+        stdio: ["ignore", "pipe", "pipe"],
+      },
+    );
+    return summarizeMediaTreatmentAnalysis(probe, parseMediaTreatmentSignalStats(raw));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`grade analysis failed for ${mediaPath}: ${message}`);
+  }
+}
+
+export function formatMeasuredNote(
+  mediaPath: string,
+  measured: MediaTreatmentMeasurements,
+): string {
+  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`;
+}

packages/core/src/mediaGradeAnalyzer.vendoredParity.test.ts

@@ -0,0 +1,100 @@
+// @vitest-environment node
+
+import { describe, expect, it } from "vitest";
+import {
+  formatMeasuredNote,
+  parseMediaTreatmentSignalStats,
+  statsToAdjust,
+  summarizeMediaTreatmentAnalysis,
+  type GradeMediaProbe,
+} from "./mediaGradeAnalyzer";
+
+const SIGNALSTATS = `frame:0 pts:0 pts_time:0
+lavfi.signalstats.YMIN=4
+lavfi.signalstats.YLOW=8
+lavfi.signalstats.YAVG=100
+lavfi.signalstats.YHIGH=240
+lavfi.signalstats.YMAX=250
+lavfi.signalstats.UAVG=120
+lavfi.signalstats.VAVG=140
+lavfi.signalstats.SATAVG=40
+frame:1 pts:1 pts_time:1
+lavfi.signalstats.YMIN=20
+lavfi.signalstats.YLOW=20
+lavfi.signalstats.YAVG=120
+lavfi.signalstats.YHIGH=220
+lavfi.signalstats.YMAX=230
+lavfi.signalstats.UAVG=125
+lavfi.signalstats.VAVG=135
+lavfi.signalstats.SATAVG=60`;
+
+const UNDEREXPOSED_SIGNALSTATS = `frame:0 pts:0 pts_time:0
+lavfi.signalstats.YMIN=2
+lavfi.signalstats.YLOW=8
+lavfi.signalstats.YAVG=50
+lavfi.signalstats.YHIGH=120
+lavfi.signalstats.YMAX=135
+lavfi.signalstats.UAVG=128
+lavfi.signalstats.VAVG=128
+lavfi.signalstats.SATAVG=30`;
+
+const BLOWN_HIGHLIGHT_SIGNALSTATS = `frame:0 pts:0 pts_time:0
+lavfi.signalstats.YMIN=70
+lavfi.signalstats.YLOW=90
+lavfi.signalstats.YAVG=200
+lavfi.signalstats.YHIGH=248
+lavfi.signalstats.YMAX=255
+lavfi.signalstats.UAVG=128
+lavfi.signalstats.VAVG=128
+lavfi.signalstats.SATAVG=30`;
+
+const PROBE: GradeMediaProbe = {
+  duration: 4,
+  colorSpace: "bt2020nc",
+  transfer: "smpte2084",
+  primaries: "bt2020",
+  pixelFormat: "yuv420p10le",
+};
+
+function productResult(signalStats = SIGNALSTATS) {
+  const frames = parseMediaTreatmentSignalStats(signalStats);
+  const summary = summarizeMediaTreatmentAnalysis(PROBE, frames);
+  return {
+    frames,
+    summary,
+    adjust: statsToAdjust(summary.measured),
+    note: formatMeasuredNote("/tmp/frame.png", summary.measured),
+  };
+}
+
+async function vendoredResult(signalStats = SIGNALSTATS) {
+  const moduleUrl = new URL(
+    "../../../skills/media-use/scripts/lib/grade-analyzer.mjs",
+    import.meta.url,
+  );
+  const analyzer = await import(moduleUrl.href);
+  const frames = analyzer.parseMediaTreatmentSignalStats(signalStats);
+  const summary = analyzer.summarizeMediaTreatmentAnalysis(PROBE, frames);
+  return {
+    frames,
+    summary,
+    adjust: analyzer.statsToAdjust(summary.measured),
+    note: analyzer.formatMeasuredNote("/tmp/frame.png", summary.measured),
+  };
+}
+
+describe("vendored media grade analyzer parity", () => {
+  it("keeps the standalone skill copy aligned with the typed product module", async () => {
+    expect(await vendoredResult()).toEqual(productResult());
+  });
+
+  it.each([
+    ["underexposed", UNDEREXPOSED_SIGNALSTATS, 1],
+    ["blown-highlight", BLOWN_HIGHLIGHT_SIGNALSTATS, -1],
+  ])("covers the %s exposure branch", async (_, signalStats, expectedSign) => {
+    const product = productResult(signalStats);
+
+    expect(Math.sign(product.adjust.adjust.exposure)).toBe(expectedSign);
+    expect(await vendoredResult(signalStats)).toEqual(product);
+  });
+});