feat(core): define media treatment capabilities#2751
Conversation
There was a problem hiding this comment.
Pull request overview
Defines and exports an expanded core data-color-grading contract to support richer “media treatment” metadata (presets, effects, palettes, LUT constraints, and animatable properties) so Studio/runtime/render/agents share a single typed source of truth.
Changes:
- Expanded color grading schema with canonical key registries, effect families + defaults, palette support, and a capabilities catalog (
getHfColorGradingCapabilities). - Added new preset families (grade vs effect presets) and “apply defaults” payloads for active effects.
- Updated/extended core tests to cover new presets, palettes, effect normalization, and capabilities output.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| packages/core/src/index.ts | Exports new color grading constants/types and the capabilities accessor from core. |
| packages/core/src/colorGrading.ts | Extends the grading schema (effects, palettes, presets, limits) and adds capability discovery metadata for downstream consumers. |
| packages/core/src/colorGrading.test.ts | Adds coverage for new presets/effects/palettes/capabilities and updates normalization/serialization expectations. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| export interface HfColorGrading { | ||
| enabled?: boolean; | ||
| preset?: HfColorGradingPresetId | string | null; | ||
| intensity?: number; | ||
| adjust?: HfColorGradingAdjust; | ||
| details?: HfColorGradingDetails; | ||
| effects?: HfColorGradingEffects; | ||
| palette?: readonly string[]; | ||
| lut?: HfColorGradingLutRef | string | null; |
| it("keeps every canonical grading key accepted by lint", async () => { | ||
| const grading = normalizeHfColorGrading("neutral"); | ||
| expect(grading).not.toBeNull(); | ||
| const result = await lintHyperframeHtml(` | ||
| <html><body> | ||
| <div id="root" data-composition-id="c1" data-width="1920" data-height="1080"> | ||
| <img id="media" src="media.jpg" data-color-grading='${serializeHfColorGrading(grading)}'> | ||
| </div> | ||
| <script>window.__timelines = {};</script> | ||
| </body></html> | ||
| `); | ||
| expect( | ||
| result.findings.find((finding) => finding.code.startsWith("color_grading_")), | ||
| ).toBeUndefined(); | ||
| }); |
miguel-heygen
left a comment
miguel-heygen
left a comment
There was a problem hiding this comment.
Audited all 3 changed files at exact head 6703b7c5: normalization/serialization, preset partitioning, palette/LUT bounds, effect activation/defaults, exported capability metadata, and the public index surface. The contract is internally coherent and its canonical key registries drive the derived types/capabilities.
The existing lint-parity test comment is valid but non-blocking for this contract PR: at this head the test is vacuous because color_grading_* findings are introduced only in the runtime PR above it. Please make that parity assertion real in the stack so future key additions cannot drift silently. The nullable input-type observation for palette is also worth aligning with the normalized/runtime JSON contract, but it does not break current authored JSON normalization.
CI is green across build/lint/typecheck/unit/runtime/Windows/CodeQL/CLI/global-install; regression shards were still running when I stamped.
Verdict: Approve.
Reasoning: The core schema and capability catalog are correctly derived from shared defaults and preserve legacy preset compatibility. Remaining comments are type/test-contract hardening, not present-tense correctness blockers.
— Magi
jrusso1020
left a comment
jrusso1020
left a comment
There was a problem hiding this comment.
Additive review at 6703b7c5 — @magi has APPROVED and @Copilot commented (palette input-type nullability + the currently-vacuous lint-parity test). Layering the render/determinism angle on top; not repeating those.
Verified — the backward-compat claim holds. The body says it "preserv[es] shipped preset IDs and persisted data-color-grading compatibility." Confirmed against the diff:
- Every shipped preset ID is retained — the old
HfColorGradingPresetIdunion ended atdeep-contrast; the new IDs (creator-camcorder,vhs-playback,home-movie-8mm,editorial-halftone,two-ink-print) are all appended, none removed or renamed. - The one behavior change in
normalizeHfColorGrading—intensitynow defaults topreset?.intensity ?? 1instead of a hard1(colorGrading.ts:933) — is compat-safe: the only presets whose intensity ≠ 1 are the new ones (creator-camcorder/home-movie-8mmat 0.72). No persisted attribute can carry a new preset, so every existingdata-color-gradingre-normalizes identically.
Verified — serialization is deterministic and persistence-stable (matters for the stack's "same pixels" thesis). serializeHfColorGrading (colorGrading.ts:953) re-normalizes and bakes preset values into concrete adjust/details/effects numbers, emitted in canonical registry order (the reduce over HF_COLOR_GRADING_*_KEYS + stable insertion order). Two useful properties fall out: (a) the serialized attribute is byte-stable across re-serialization; (b) persisted projects are immune to future preset retuning, because on re-read rawAdjust[key] ?? presetAdjust[key] (colorGrading.ts:907) always finds the baked raw value first.
Concur (minor), already noted by others: Copilot's palette input/normalized nullability mismatch (HfColorGrading.palette: readonly string[] vs NormalizedHfColorGrading.palette: … | null) is a type-only cosmetic inconsistency, not a runtime bug. The lint-parity assertion in colorGrading.test.ts is vacuous until #2752's media rule emits color_grading_* codes, as @magi noted — worth tightening there.
Verdict: COMMENT — Ready on the merits. Clean, well-tested contract expansion; I concur with @magi's approve. (Deferring the approving stamp to the maintainer.)
Review by Jerrai (hyperframes)
6703b7c to
7d7c18f
Compare
What
Defines the Core media-treatment contract for real
<img>and<video>elements: normalized grading, LUT, finishing, effect, preset, capability, and animation metadata.Why
Studio, runtime, render, and agents need one typed source of truth instead of parallel effect lists or ad hoc payloads.
How
Extends the existing color-grading schema while preserving shipped preset IDs and persisted
data-color-gradingcompatibility. Canonical key registries drive validation and capability discovery.Test plan
Stack 1/6. This PR has no dependency on later PRs.