docs: document professional grading and media treatments - #2826

Pull request overview

This PR updates the HyperFrames documentation to reflect the shipped professional SDR/Rec.709 media-treatment surfaces by restructuring the Color Grading guide and adding dedicated guides for shader-based Media Effects and Registry-based Media Overlays, then wiring those new guides into the docs navigation.

Changes:

• Rewrites Color Grading documentation around scopes, wheels, curves, HSL selections, LUTs, and the CLI/agent workflow.
• Adds new Media Effects and Media Overlays guides to clearly separate shader treatments from editable composition-layer overlays.
• Updates docs/docs.json navigation to include the new guides.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

SSOT -- Clean Three-Way Split, Verified Against Main

Verified the full diff (+839/-326 across 6 files) against the current main branch codebase. The old monolithic color-grading guide covered correction, effects, overlays, and the full data shape in one page. This PR splits that into three focused guides with clean domain boundaries and no duplicated decisions.

Accuracy against codebase -- all confirmed

Every code-level claim in the docs matches main:

• Presets: All 13 documented presets (neutral, warm-daylight, clean-studio, skin-soft, food-pop, night-lift, muted-editorial, vintage-wash, mono-clean, mono-fade, soft-boost, bright-pop, deep-contrast) exist as HfColorGradingPresetId variants in packages/core/src/colorGrading.ts. The 5 effect presets (creator-camcorder, vhs-playback, home-movie-8mm, editorial-halftone, two-ink-print) are also registered with their correct display labels.
• Color wheels (shadows/midtones/highlights with hue/amount/level): HfColorGradingTonalWheel and HfColorGradingWheels types exist, keyed by COLOR_GRADING_WHEEL_KEYS.
• RGB curves and hue curves: HfColorGradingCurves and HfColorGradingHueCurves types with their point types are fully defined.
• HSL secondaries: HfColorGradingSecondary with enabled, key (hue/saturation/luma ranges), and correction (hueShift/saturation/luma/temperature/tint) matches the documented shape. COLOR_GRADING_MAX_SECONDARIES is exported.
• Registry overlay blocks: All four exist in registry/blocks/ on main: camcorder-hud, editorial-flash-overlay, organic-light-leak-overlay, freeze-frame-dressing.
• media-treatment CLI: Command registered in packages/cli/src/cli.ts, implementation in packages/cli/src/commands/media-treatment.ts. All 13 documented flags (--capabilities, --capability, --all, --project, --file, --selector, --selector-index, --analyze, --grading, --apply, --clear, --dry-run, --json) confirmed in the command's args definition.
• media-use skill: Exists in skills/media-use/ on main.
• remove-background CLI: Exists in packages/cli/src/commands/remove-background.ts.
• data-color-grading attribute: Wired through core, runtime, engine, and studio.

Internal consistency -- all cross-references resolve

• All inter-page links (/guides/color-grading, /guides/media-effects, /guides/media-overlays, /guides/hdr, /guides/4k-rendering, /guides/keyframes, /guides/performance, /guides/remove-background) point to existing .mdx files.
• docs/docs.json nav includes all three pages in the correct position: color-grading -> media-effects -> media-overlays, placed between video-components and html-in-canvas.
• The html-schema.mdx addition cross-links to both guides and the CLI command anchor.
• The cli.mdx media-treatment section cross-links to the two guides.

SSOT evaluation

Good separation:

• Color grading covers correction, wheels, curves, HSL selections, scopes, presets, LUTs, and the persistence contract. No effects details.
• Media effects covers the 18 shader effects, palettes, animation/keyframe paths, pipeline order, and performance. No grading details.
• Media overlays covers the 4 registry blocks, compositing model, and editing/reuse. No pixel-level treatment details.
• Each page's "Next Steps" card group links to the other two, forming a clean triangle.

Old content correctly removed:

• The exhaustive "Data Shape" JSON block is gone. The new docs point to npx hyperframes media-treatment --capability <id> --json and --all --json for the canonical contract, keeping the code as the single source of truth rather than a manually-maintained doc copy.
• The "What Belongs Where" mega-table is replaced by a concise "Choose the Right Tool" table plus domain-specific routing in each guide.
• Effect-by-effect behavioral documentation (chromaBleed, tapeDamage, halftone, etc.) moved cleanly to media-effects.mdx's "Important Effect Behavior" section.

One pre-existing adjacent page to be aware of (non-blocking):
docs/concepts/variables.mdx has a "Parameterizing media color grading" section (lines ~81-120) with its own data-color-grading example. It's already reasonably current (includes details, effects, blur) and serves a different purpose (explaining variable resolution, not grading features). A future cross-link to /guides/color-grading from that section would be nice, but it's not stale and doesn't block this PR.

CI

All 29 check runs completed. 6 passed (regression, format, semantic PR title, file size, CodeQL, detect-changes). 22 skipped (correctly gated by detect-changes for a docs-only diff). 0 failures. PR is mergeable.

Verdict

Ship it. The documentation is accurate against the shipped codebase, internally consistent, properly navigated, and cleanly separated across three focused guides with no duplicated decisions.

-- Miga

Docs pass verifies clean against the runtime at HEAD. I fanned out three parallel verification agents (color grading, media effects, media overlays + nav) and every runtime claim I put to them landed:

Color Grading

• data-color-grading is the canonical persistence attribute (packages/core/src/colorGrading.ts:26).
• The media-treatment CLI + all documented flags (--capabilities, --capability, --project, --file, --selector, --grading, --apply, --analyze, --clear, --dry-run, --json) exist at packages/cli/src/commands/media-treatment.ts:686-716.
• All 7 capability slugs (grading, curves, wheels, hue-curves, secondary, scopes, lut) resolve via getMediaTreatmentCapabilityDetail at media-treatment.ts:172-297.
• RGB curve bounds (2-16 points) and hue curve bounds (3-16 unique inputs, 0 ≤ hue < 360) both match the parser at packages/parsers/src/colorGradingContract.ts:246-249, 285-309.
• All 13 documented preset display names (Neutral, Warm Daylight, Clean Studio, Skin Soft, Food Pop, Night Lift, Muted Editorial, Vintage Wash, Soft Boost, Bright Pop, Deep Contrast, Mono Clean, Mono Fade) are real entries in HF_COLOR_GRADING_PRESETS at packages/core/src/colorGrading.ts:447-627.
• Project-wide LUT-relative-path refusal is a real runtime guard (packages/studio/src/components/studioColorGradingScope.ts:90-96 + studioMediaJobs.ts:22-25).
• All --grading payload keys (adjust, wheels, curves, hueCurves, secondaries, details, colorSpace) and their sub-keys accept via the whitelist at colorGradingContract.ts:22-76.

Media Effects

• All 17 effects across all four families (Essentials × 3, Retro & Glitch × 7, Print × 4, Art × 4) are registered in EFFECT_METADATA at packages/core/src/colorGrading.ts:740-834 with the documented family assignments.
• All 7 documented digitalGlitch* payload keys accept via colorGradingContract.ts:113-120 and default via HF_COLOR_GRADING_EFFECT_APPLY_DEFAULTS at colorGrading.ts:862-871.
• HDR gating claim ("SDR effects don't apply to native HDR layers") is faithful — the HDR compositor's two-pipeline design (packages/producer/src/services/hdrCompositor.ts:454-459, 547-562 + packages/engine/src/utils/layerCompositor.ts:17-58) bypasses the DOM screenshot layer where the WebGL grading overlay lives.
• The 9 GSAP-animatable strengths listed at media-effects.mdx:171-180 match HF_COLOR_GRADING_ANIMATABLE_PROPERTIES at colorGrading.ts:921-931 one-for-one.

Media Overlays / Nav

• All 4 registry blocks (camcorder-hud, editorial-flash-overlay, organic-light-leak-overlay, freeze-frame-dressing) exist in registry/blocks/*/registry-item.json and are tagged media-treatment-overlay; Studio's Overlays surface at packages/studio/src/components/editor/propertyPanelFlatOverlaysSection.tsx:10 filters by that tag.
• hyperframes add ... --no-clipboard and hyperframes remove-background ... -o ... both real (packages/cli/src/commands/add.ts:227-251, remove-background.ts:44-60).
• Camcorder HUD counter is timeline-driven via gsap.timeline({paused: true}) reading data-hf-counter-start and data-duration (registry/blocks/camcorder-hud/camcorder-hud.html:137, 153, 157-160).
• All 3 new/updated guides are wired into docs/docs.json in the Guides group (lines 81-83).
• cli.mdx and html-schema.mdx additions all reference real runtime symbols; no dead cross-references.
• No stale in-app help panel copy in packages/studio/src/ referencing the older combined guide.

Two polish nits worth considering (no blockers)

1. Display-name → payload-slug mapping. Two Retro & Glitch effects have Studio display names that don't match their JSON payload keys, and agents writing raw payloads will bounce off if they only know the display name:

• Docs say Chroma Softening → runtime payload key is chromaBleed (not chromaSoftening)
• Docs say Channel Separation → runtime payload key is chromaticAberration (not channelSeparation)

The --grading code examples in this guide correctly use the payload keys, so the docs aren't wrong — but an "if you're authoring payloads by hand, note that Chroma Softening = chromaBleed and Channel Separation = chromaticAberration" line under the Retro & Glitch table would close the gap for agents. Every other effect's display name matches its slug (case-insensitive).

2. RGB curve endpoint wording. color-grading.mdx:101-102 says "Every RGB curve must include input endpoints 0 and 1" — this is slightly stronger than the input contract. The parser at packages/parsers/src/colorGradingContract.ts:268-274 and the normalizer at packages/core/src/colorGrading.ts:1187-1190 (completeCurveEndpoints unshifts [0,0] if first input > 0 and pushes [1,1] if last < 1) auto-infer the endpoints if the author omits them. The capability descriptor even flags this via implicitEndpoints: true, endpointsCountTowardMax: true at colorGrading.ts:995. Softening to "the resolved curve always contains endpoints 0 and 1" (or "endpoints are auto-inferred; the 2-16 bound counts inferred endpoints toward the max") would match the actual input contract.

CI

All docs / broken-link / typecheck / player-perf / regression / preview-regression checks pass at 182862773. Format check is CANCELLED (superseded by a later run in the same commit); the winning run is green. Mintlify Deployment SUCCESS.

Very clean docs PR — nothing that needs to block merge from where I sit.

— Review by Rames D Jusso

Reviewed at 182862773187dc01f08b2c29d2a3a5951afe5c5e.

Independent exact-head verification is clean:

• docs/guides/media-overlays.mdx:114-128 now describes the real compositing contract: grading/effects produce the visible media canvas, while overlays/captions/other layers compose by authored track and CSS z-index. That resolves the earlier fixed-order ambiguity.
• The 13 corrective/editorial preset labels match HF_COLOR_GRADING_PRESETS; the five stylized preset families remain correctly routed to Media Effects.
• All 13 documented media-treatment flags match the command definition at packages/cli/src/commands/media-treatment.ts:692-738.
• The four named overlays exist, carry media-treatment-overlay, and are installed as editable registry blocks.
• docs/docs.json, the CLI anchor, HTML-schema cross-links, and the new guide triangle resolve. git diff --check is clean.

Rames’s endpoint-wording and display-name/slug notes are useful polish but do not make the current docs incorrect or unsafe to ship. Current docs validation, regression, preview-regression, CodeQL, Format, and Mintlify checks are green; the earlier cancelled Format run was superseded by a success at the same head.

Verdict: APPROVE
Reasoning: The docs accurately reflect the shipped runtime and CLI contracts, the three-way grading/effects/overlays split is coherent, and the prior overlay-ordering concern is resolved.

— Magi

Verdict: APPROVE

Reasoning: Re-reviewed the delta from 182862773 to 12452a115. Both documentation clarifications now match the implementation exactly: RGB curves resolve missing 0/1 endpoints and count those inferred points inside the 16-point ceiling (colorGradingContract.ts:268-273, colorGrading.ts:1187-1204), and the two display-name→payload-key mismatches are now explicit (Chroma Softening → chromaBleed, Channel Separation → chromaticAberration). No unrelated surface changed; git diff --check is clean. Exact-head docs validation, build, lint, typecheck, unit/integration, preview, perf, CodeQL, and Mintlify checks are green; remaining regression/Windows jobs are still running and should gate merge normally.

Delta-only re-review against the previously reviewed head. Both earlier nits are addressed, and the slug callout is correct — chromaBleed and chromaticAberration are both real payload keys, present in the color-grading module, the parser contract, and the studio property-panel specs. One correction on the revised curve sentence, since it is the clause being fixed and the new phrasing over-generalizes.

The ceiling half is exactly right. validateCurve computes inferredPointCount = value.length + (inputs.has(0) ? 0 : 1) + (inputs.has(1) ? 0 : 1) and rejects anything above the max, with an error message that literally says "including inferred 0 and 1 endpoints". So a 15-point curve that omits both endpoints resolves to 17 and is refused. The doc now matches that, which the previous wording did not.

The floor half doesn't hold. The minimum-2 check runs on the raw supplied array before any inference — it's the first guard in the same function, value.length < 2. A single supplied point would resolve to 3 after inference, so under "the 2–16-point limit includes those inferred points" it reads as legal. It's rejected outright.

So the two bounds have different semantics: the floor counts supplied points, the ceiling counts resolved ones. For a guide aimed at authors composing JSON directly, the current sentence both implies a 1-point curve is valid and hides the genuinely useful consequence — with neither endpoint supplied, the real ceiling is 14.

Suggested:

Supply 2 to 16 points. HyperFrames infers missing 0 and 1 endpoints, and the 16-point ceiling counts them, so a curve that omits both endpoints can supply at most 14.

Not blocking — this is one clause in a docs pass that is a clear net improvement, and everything else in the delta checks out. Flagging it because it's the same sentence that was already corrected once, and the replacement trades one imprecision for a smaller one.

Withholding a formal approval only on CI: the regression shards are still outstanding at this head, nothing failing.

— Review by Rames Jusso