Grading

For a vague but explicit polish request, do not jump directly from intent to a preset name. Read media-treatments.md, choose a treatment whose subject and avoid rules match the actual media, apply its conservative base with only justified bounded tuning, then complete its visual verification steps. A named owned treatment uses the exact preset/payload in its recipe; do not run the generic grade/LUT resolver first.

Stop here and use that treatment workflow for requests such as retro, old home video, camcorder, film, print, ASCII, glitch, privacy, or a media reveal. Do not assemble those from a generic LUT plus handmade CSS vignette/grain/opacity.

Never cat/read a .cube file into context. A 3D LUT is ~size^3 lines of raw numbers (33^3 ≈ 36k lines at the default size). It bloats context and carries zero human/agent-legible signal. To understand or choose a LUT, use hyperframes grade-compare to see it rendered, or cube-validate.mjs for a one-line {ok,size} check. Read .media/index.md or luts/index.json for the description. Never read the LUT body itself.

Preset-first output uses the core runtime vocabulary and does not freeze a file:

Apply that payload to one unambiguous real media element:

Use --dry-run before writing when scope is uncertain and --clear to remove the treatment. The low-level persisted result is still normal HTML:

Direct attribute authoring is a fallback for environments where the CLI is not available, not the primary agent workflow.

To build a treatment that is not already represented by a recipe, inspect the canonical toolbox first:

It reports a concise family map. Read --capability grading for the processing order, then request only the focused family needed to get its legal controls and ranges from Core. Compose one nested payload and pass it back through hyperframes media-treatment; the command rejects unknown keys before mutation. Do not generate or hand-edit a LUT merely to combine controls already owned by the realtime shader.

For seek-safe effect motion, animate only the runtime-supported CSS properties on that same real media element with its registered paused GSAP timeline:

Author the initial value directly in the media element’s inline style, then use finite tl.to() keyframes. Do not use a frame-zero tl.set(), CSS animation clocks, timers, random values, or onUpdate callbacks. The static data-color-grading payload remains the fallback and source of the other controls.

For a reusable color transform beyond the preset vocabulary, freeze a validated .cube under .media/luts/ and return a block that references it:

Use lut when you only need the reusable .cube file:

For a describable technical look, author an explicit parametric LUT with --params:

For a LUT generated by your own script, ingest it with --from; media-use validates it before registration and rejects invalid or oversized cubes:

Parametric math (buildCube) cannot reproduce real film stocks or emulsion transforms. Use a CDN-backed scanned .cube entry or ingest a real scanned .cube for those.

For visual selection, list reusable LUT candidates with resolve --type grade --candidates, write the promising entries to a grades.json, run hyperframes grade-compare --for <frame> --grades grades.json, then commit the winner with resolve -t grade as the final data-color-grading block.

For media already selected in a composition, use media-treatment --analyze when you need side-effect-free ffmpeg/ffprobe signalstats evidence. It returns source metadata, HDR/unknown-LOG warnings, and a bounded adjust suggestion without modifying the composition. The suggestion is a starting point for visual review, not an automatic neutralization of intentional color.

For an unbound source file, resolve --type grade --for ... --analyze remains available. Without --analyze, that resolver records a grade candidate in .media; use that form only when you intend to keep the candidate.

Library LUT entries live in luts/index.json. Each entry keeps id, description, tags, and intensity, then supplies either compact params for on-demand buildCube(params) generation or a direct CDN url for future scanned .cube files. Do not commit generated .cube bodies; resolve validates generated or downloaded cubes as it freezes them under .media/luts/.