Skip to content

Write HTML. Render video. Built for agents.

fix(cli): agents can apply a color correction from media-treatment's capabilities (#5850)

Miguel Ángele31838159d90
diff --git a/packages/cli/src/commands/media-treatment.test.ts b/packages/cli/src/commands/media-treatment.test.ts
index 70ecd2da29..c7dd916f1d 100644
--- a/packages/cli/src/commands/media-treatment.test.ts
+++ b/packages/cli/src/commands/media-treatment.test.ts
@@ -16,6 +16,10 @@ import {
resolveMediaTreatmentSource,
} from "./media-treatment.js";
import { CliRuntimeError } from "../utils/commandResult.js";
+import {
+ COLOR_GRADING_TOP_LEVEL_KEYS,
+ validateColorGradingContract,
+} from "@hyperframes/parsers/color-grading-contract";
const VIDEO = `<!doctype html><html><body><video id="hero" src="hero.mp4"></video></body></html>`;
const SEGMENTS = `<!doctype html><html><body><video class="seg" src="a.mp4"></video><video class="seg" src="b.mp4"></video></body></html>`;
@@ -26,6 +30,24 @@ function gradingsOf(html: string): Array<string | null> {
);
}
+describe("media-treatment capabilities", () => {
+ it("name every catalog section after the payload key it documents, and carry a valid example", () => {
+ const catalog = getHfColorGradingCapabilities() as Record<string, unknown>;
+ const payloadKeys: readonly string[] = COLOR_GRADING_TOP_LEVEL_KEYS;
+ const describedSections = Object.keys(catalog).filter((key) =>
+ ["adjust", "adjustments", "details", "finishing"].includes(key),
+ );
+ expect(describedSections.every((key) => payloadKeys.includes(key))).toBe(true);
+
+ const overview = getMediaTreatmentCapabilityOverview() as { example?: unknown };
+ const correction = getMediaTreatmentCapabilityDetail("correction") as { apply?: unknown };
+ for (const payload of [catalog.example, overview.example, correction.apply]) {
+ expect(payload).toBeDefined();
+ expect(validateColorGradingContract(payload)).toEqual([]);
+ }
+ });
+});
+
describe("applyMediaTreatmentToHtml", () => {
it("provides a concise first-hop overview of the complete treatment surface", () => {
const overview = getMediaTreatmentCapabilityOverview();
diff --git a/packages/cli/src/commands/media-treatment.ts b/packages/cli/src/commands/media-treatment.ts
index 83a48ce2af..34c94e59a2 100644
--- a/packages/cli/src/commands/media-treatment.ts
+++ b/packages/cli/src/commands/media-treatment.ts
@@ -47,6 +47,7 @@ export function getMediaTreatmentCapabilityOverview() {
version: capabilities.version,
targetTags: capabilities.targetTags,
colorSpace: capabilities.colorSpace,
+ example: capabilities.example,
families: [
family("correction", "Adjust", "Fix exposure, tonal balance, color casts, and saturation."),
family(
@@ -137,7 +138,7 @@ export function getMediaTreatmentCapabilityDetail(id: string): unknown {
};
}
- const adjustment = capabilities.adjustments.find(({ key }) => key === id);
+ const adjustment = capabilities.adjust.find(({ key }) => key === id);
if (adjustment) {
return {
id,
@@ -149,7 +150,7 @@ export function getMediaTreatmentCapabilityDetail(id: string): unknown {
};
}
- const finishing = capabilities.finishing.find(({ key }) => key === id);
+ const finishing = capabilities.details.find(({ key }) => key === id);
if (finishing) {
return {
id,
@@ -193,7 +194,8 @@ export function getMediaTreatmentCapabilityDetail(id: string): unknown {
correction: {
id,
description: "Fix exposure, tonal balance, color casts, and saturation.",
- controls: capabilities.adjustments,
+ controls: capabilities.adjust,
+ apply: { adjust: capabilities.example.adjust },
},
wheels: {
id,
@@ -272,7 +274,8 @@ export function getMediaTreatmentCapabilityDetail(id: string): unknown {
finishing: {
id,
description: "Vignette and deterministic film-grain controls.",
- controls: capabilities.finishing,
+ controls: capabilities.details,
+ apply: { details: capabilities.example.details },
},
palettes: {
id,
diff --git a/packages/core/src/colorGrading.test.ts b/packages/core/src/colorGrading.test.ts
index c336992f21..08e0435850 100644
--- a/packages/core/src/colorGrading.test.ts
+++ b/packages/core/src/colorGrading.test.ts
@@ -129,7 +129,7 @@ describe("color grading", () => {
expect(capabilities.version).toBe(2);
expect(capabilities.colorSpace).toBe("rec709");
- expect(capabilities.adjustments.map(({ key }) => key)).toEqual([
+ expect(capabilities.adjust.map(({ key }) => key)).toEqual([
"exposure",
"contrast",
"highlights",
diff --git a/packages/core/src/colorGrading.ts b/packages/core/src/colorGrading.ts
index 23285dda14..77eea925dc 100644
--- a/packages/core/src/colorGrading.ts
+++ b/packages/core/src/colorGrading.ts
@@ -2,6 +2,7 @@ import { DEFAULT_MAX_CUBE_LUT_SIZE } from "./colorLuts";
import type { HfColorCurvePoint, HfHueCurvePoint } from "./colorGradingCurves";
import {
COLOR_GRADING_ADJUST_KEYS,
+ COLOR_GRADING_EXAMPLE,
COLOR_GRADING_ADVANCED_LIMITS,
COLOR_GRADING_COLOR_SPACE,
COLOR_GRADING_CONTRACT_VERSION,
@@ -967,7 +968,8 @@ export function getHfColorGradingCapabilities() {
intensity: preset.intensity,
}),
),
- adjustments: HF_COLOR_GRADING_ADJUST_KEYS.map((key) => ({
+ example: COLOR_GRADING_EXAMPLE,
+ adjust: HF_COLOR_GRADING_ADJUST_KEYS.map((key) => ({
key,
identity: ADJUST_ZERO[key],
...ADJUST_LIMITS[key],
@@ -1038,7 +1040,7 @@ export function getHfColorGradingCapabilities() {
},
},
effectFamilies: EFFECT_FAMILIES,
- finishing: HF_COLOR_GRADING_DETAIL_KEYS.map((key) => ({
+ details: HF_COLOR_GRADING_DETAIL_KEYS.map((key) => ({
key,
identity: DETAIL_DEFAULTS[key],
...DETAIL_LIMITS[key],
diff --git a/packages/parsers/src/colorGradingContract.docs.test.ts b/packages/parsers/src/colorGradingContract.docs.test.ts
new file mode 100644
index 0000000000..137a6b473a
--- /dev/null
+++ b/packages/parsers/src/colorGradingContract.docs.test.ts
@@ -0,0 +1,56 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { validateColorGradingContract } from "./colorGradingContract";
+
+const REPO = resolve(import.meta.dirname, "../../..");
+const GRADING_SECTIONS = ["adjust", "wheels", "curves", "hueCurves", "secondaries", "details"];
+
+function markdownFiles(dir: string): string[] {
+ return readdirSync(dir).flatMap((name) => {
+ const path = join(dir, name);
+ if (name === "node_modules") return [];
+ if (statSync(path).isDirectory()) return markdownFiles(path);
+ return /\.mdx?$/.test(name) ? [path] : [];
+ });
+}
+
+/** Every grading payload the docs and skills show: inline CLI/attribute JSON and fenced JSON objects. */
+function documentedGradings(): { where: string; grading: unknown }[] {
+ return ["docs", "skills"].flatMap((root) =>
+ markdownFiles(join(REPO, root)).flatMap((file) => {
+ const text = readFileSync(file, "utf8");
+ const where = relative(REPO, file);
+ const inline = [...text.matchAll(/(?:--grading\s+|data-color-grading=)'(\{[^']*\})'/g)].map(
+ (match) => ({ where, grading: JSON.parse(match[1]!) as unknown }),
+ );
+ const fenced = [...text.matchAll(/```jsonc?\n([\s\S]*?)```/g)].flatMap((match) => {
+ let value: unknown;
+ try {
+ value = JSON.parse(match[1]!);
+ } catch {
+ return [];
+ }
+ const entries = Array.isArray(value) ? value : [value];
+ return entries
+ .map((entry) => (entry as { grading?: unknown })?.grading ?? entry)
+ .filter(
+ (g) => typeof g === "object" && g !== null && GRADING_SECTIONS.some((k) => k in g),
+ )
+ .map((grading) => ({ where, grading }));
+ });
+ return [...inline, ...fenced];
+ }),
+ );
+}
+
+describe("documented color-grading payloads", () => {
+ it("are all accepted by the validator", () => {
+ const documented = documentedGradings();
+ expect(documented.length).toBeGreaterThan(10);
+ const rejected = documented
+ .map(({ where, grading }) => ({ where, issues: validateColorGradingContract(grading) }))
+ .filter(({ issues }) => issues.length > 0);
+ expect(rejected).toEqual([]);
+ });
+});
diff --git a/packages/parsers/src/colorGradingContract.test.ts b/packages/parsers/src/colorGradingContract.test.ts
index b8412a6bf1..d10de979ee 100644
--- a/packages/parsers/src/colorGradingContract.test.ts
+++ b/packages/parsers/src/colorGradingContract.test.ts
@@ -1,5 +1,6 @@
import { describe, expect, it } from "vitest";
import {
+ COLOR_GRADING_EXAMPLE,
COLOR_GRADING_ADJUST_KEYS,
COLOR_GRADING_ADVANCED_LIMITS,
COLOR_GRADING_DETAIL_KEYS,
@@ -13,6 +14,15 @@ import {
} from "./colorGradingContract";
describe("color grading contract", () => {
+ it("accepts its own correction example", () => {
+ expect(validateColorGradingContract(COLOR_GRADING_EXAMPLE)).toEqual([]);
+ });
+
+ it("names the real top-level keys when a container is misnamed", () => {
+ const [issue] = validateColorGradingContract({ adjustments: { exposure: 0.1 } });
+ expect(issue?.hint).toContain('"adjust"');
+ });
+
it("publishes one complete key registry", () => {
expect(COLOR_GRADING_TOP_LEVEL_KEYS).toContain("effects");
expect(COLOR_GRADING_ADJUST_KEYS).toContain("exposure");
diff --git a/packages/parsers/src/colorGradingContract.ts b/packages/parsers/src/colorGradingContract.ts
index 7949da17cc..b7ef09cca9 100644
--- a/packages/parsers/src/colorGradingContract.ts
+++ b/packages/parsers/src/colorGradingContract.ts
@@ -48,6 +48,11 @@ export const COLOR_GRADING_ADJUST_KEYS = [
"saturation",
] as const;
+export const COLOR_GRADING_EXAMPLE = {
+ adjust: { exposure: 0.1, contrast: 0.05, temperature: 0.08 },
+ details: { vignette: 0.15 },
+} as const;
+
export const COLOR_GRADING_WHEEL_KEYS = ["shadows", "midtones", "highlights"] as const;
export const COLOR_GRADING_CURVE_KEYS = ["master", "red", "green", "blue"] as const;
export const COLOR_GRADING_HUE_CURVE_KEYS = ["hueVsHue", "hueVsSaturation", "hueVsLuma"] as const;
@@ -185,7 +190,7 @@ function unknownKeysHint(path: string, unknown: readonly string[]): string {
);
return sections.size === 1
? `Move those controls under "${[...sections][0]}".`
- : "Use only the documented media-treatment keys at the top level.";
+ : `Top-level keys are ${COLOR_GRADING_TOP_LEVEL_KEYS.map((key) => `"${key}"`).join(", ")}.`;
}
function validateObject(