` and animate the wrapper instead. See [Common Mistakes](/guides/common-mistakes) for a detailed explanation.
-
-
-## Next Steps
-
-
-
- Understand the building blocks that timelines animate
-
-
- Learn how GSAP plugs into the render pipeline
-
-
- Avoid pitfalls that break animations
-
-
- Full reference for composition attributes
-
-
+- [Edit animation and keyframes in Studio](/studio/animation)
+- [Understand deterministic rendering](/concepts/determinism)
+- [Use the HTML composition schema](/reference/html-schema)
diff --git a/docs/guides/hdr.mdx b/docs/guides/hdr.mdx
index 150e579af6..93e2d75d94 100644
--- a/docs/guides/hdr.mdx
+++ b/docs/guides/hdr.mdx
@@ -1,133 +1,27 @@
---
-title: HDR Rendering
-description: "Render compositions to HDR10 MP4 (BT.2020 PQ or HLG, 10-bit H.265) when sources contain HDR video or images."
+title: Render HDR video
+description: Preserve BT.2020 PQ or HLG sources in a 10-bit H.265 MP4.
---
-Hyperframes can render to HDR10 MP4 (H.265 10-bit, BT.2020) when your composition references HDR video or HDR still images. HDR is auto-detected by default from your media sources and falls back to SDR when none are present.
-
-
- By default, Hyperframes probes your media and enables HDR only when HDR sources are present. Use `--hdr` to force HDR even without HDR sources, or `--sdr` to force SDR even when HDR sources are present.
-
-
-## Quickstart
-
-
-
- Hyperframes detects HDR from the source's color space metadata. The most reliable HDR sources are:
-
- - **HDR video** tagged BT.2020 with PQ (`smpte2084`) or HLG (`arib-std-b67`) transfer
- - **HDR still images** as 16-bit PNG with BT.2020 PQ encoding
-
- See [Source Media](#source-media-requirements) for full details.
-
-
- ```bash Terminal
- npx hyperframes render --output output.mp4
- ```
-
- HDR output requires `--format mp4`. If Hyperframes detects HDR sources, it renders HDR automatically. If you also pass `--format mov` or `--format webm`, Hyperframes logs a warning and falls back to SDR.
-
-
- Use `ffprobe` to confirm the encoded stream carries HDR color tagging and HDR10 metadata:
-
- ```bash Terminal
- ffprobe -v error -show_streams output.mp4 | grep -E 'color_transfer|color_primaries|color_space'
- ```
-
- See [Verifying HDR output](#verifying-hdr-output) for what to look for.
-
-
-
-## How HDR Mode Works
-
-During render, the producer:
-
-
-
- Runs `ffprobe` on each `
-
- If any source uses PQ (`smpte2084`), the output uses **PQ**. Otherwise, if any source uses HLG (`arib-std-b67`), the output uses **HLG**. If no HDR sources are found, the render stays SDR.
-
-
- The video encoder switches to `libx265` with `-pix_fmt yuv420p10le`, color tagging `colorprim=bt2020:transfer=:colormatrix=bt2020nc`, and HDR10 static metadata (`master-display` and `max-cll`). Without that metadata, players (QuickTime, YouTube, HDR TVs) tone-map the stream as if it were SDR BT.2020 — which looks wrong.
-
-
- HDR videos and images are extracted as 16-bit linear-light pixels via FFmpeg, kept out of the DOM screenshot, and composited server-side at full bit depth. SDR DOM overlays (text, shapes, UI from your HTML) are converted from **sRGB** to **BT.2020** before being layered on top, so colors do not shift.
-
-
-
-## Source Media Requirements
-
-### HDR video
-
-Hyperframes recognizes HDR video from its `ffprobe` color space metadata:
-
-| Indicator | Recognized as HDR |
-|-----------|-------------------|
-| `color_primaries` contains `bt2020` | Yes |
-| `color_space` contains `bt2020` | Yes |
-| `color_transfer = smpte2084` (PQ) | Yes — PQ |
-| `color_transfer = arib-std-b67` (HLG) | Yes — HLG |
-| All else (e.g. `bt709`, `smpte170m`) | No — treated as SDR |
-
-A valid HDR source is any MP4 whose stream metadata reports BT.2020 primaries plus PQ or HLG transfer. Hyperframes will detect it automatically:
-
-```bash Terminal
-ffprobe -v error -show_streams assets/clip.mp4 | grep color
-# color_primaries=bt2020
-# color_transfer=smpte2084
-# color_space=bt2020nc
-```
-
-### HDR still images
+HyperFrames detects HDR media during render. When an MP4 project contains a BT.2020 PQ or HLG source, the output uses 10-bit H.265 and keeps the HDR signal. Projects without HDR media stay SDR.
-Hyperframes supports HDR still images delivered as **16-bit PNGs** tagged with BT.2020 primaries and PQ transfer. Drop them into the composition as a normal `
![]()
`:
+## Render and verify
-```html index.html
-
+```bash
+npx hyperframes render --output final-hdr.mp4
```
-When HDR is enabled, the image is decoded once to 16-bit linear-light RGB and composited natively into the HDR output.
-
-
- HDR `![]()
` decoding is limited to **16-bit PNG**. JPEG, WebP, AVIF, and APNG are not recognized as HDR sources — they load through the normal SDR DOM path. For HDR motion, use a `
-
-### SDR sources mixed with HDR
-
-You can freely mix SDR and HDR media in the same composition:
-
-- **SDR videos** stay in the DOM screenshot path and get the sRGB → BT.2020 conversion described above
-- **HDR videos** are extracted natively at 16-bit and composited underneath the SDR DOM layer
-- **SDR images and DOM elements** (text, shapes, gradients, GSAP animations) are converted from sRGB to BT.2020
-
-This is the same pipeline that handles compositions where, for example, an HDR drone clip plays under an SDR lower-third with animated text.
-
-## Output Format Requirements
-
-| Output format | HDR supported |
-|---------------|---------------|
-| `mp4` | Yes — H.265 10-bit BT.2020, HDR10 metadata |
-| `mov` | No — falls back to SDR |
-| `webm` | No — falls back to SDR |
-| `gif` | No — falls back to SDR |
-
-If HDR is enabled and you also pass `--format mov`, `--format webm`, or `--format gif`, Hyperframes logs a message and produces the equivalent SDR render. There is no error — the render still completes — so check the logs (or your verification step) to confirm you got HDR.
+Check the result:
-## Verifying HDR Output
-
-Use `ffprobe` to confirm both the color tagging and the HDR10 static metadata are present:
-
-```bash Terminal
-ffprobe -v error -show_streams -select_streams v:0 output.mp4 \
- | grep -E 'codec_name|pix_fmt|color_transfer|color_primaries|color_space'
+```bash
+ffprobe -v error -select_streams v:0 -show_entries \
+ stream=codec_name,pix_fmt,color_space,color_primaries,color_transfer \
+ final-hdr.mp4
```
-For a PQ HDR10 render you should see:
+A PQ output should report values equivalent to:
-```
+```text
codec_name=hevc
pix_fmt=yuv420p10le
color_space=bt2020nc
@@ -135,63 +29,36 @@ color_primaries=bt2020
color_transfer=smpte2084
```
-Then check the HDR10 SEI / container boxes:
+HLG reports `arib-std-b67` as the transfer.
-```bash Terminal
-ffprobe -v error -show_frames -read_intervals "%+#1" \
- -show_entries frame=side_data_list output.mp4
-```
+## Control detection
-You should see entries for **Mastering display metadata** and **Content light level metadata**. Without them, HDR-aware players will treat the file as SDR BT.2020 and the colors will look washed-out or wrong on an HDR display.
+| Command | Use it when |
+| --- | --- |
+| `hyperframes render` | Let source metadata decide between HDR and SDR |
+| `hyperframes render --hdr` | Force HDR; without detected HDR media, HyperFrames uses HLG and warns |
+| `hyperframes render --sdr` | Deliver an SDR version even when the project contains HDR media |
-For HLG renders the only difference is `color_transfer=arib-std-b67` — the rest of the checks are the same.
+The source files must contain correct color metadata. HyperFrames recognizes video tagged as BT.2020 with PQ (`smpte2084`) or HLG (`arib-std-b67`). It can also preserve supported HDR still images through the native HDR image path.
-## Docker Rendering
+## Mixed compositions
-Docker uses the same auto-detect logic as local rendering, so you can produce HDR10 MP4 output from the containerized renderer without extra flags:
+You can place HTML text, CSS graphics, and SDR media over HDR footage. HyperFrames keeps native HDR layers outside the normal browser screenshot, converts the SDR DOM layer into the HDR color space, and composites the result before encoding.
-```bash Terminal
-npx hyperframes render --docker --output output.mp4
-```
+This is why a lower third or animated interface can remain visually consistent over an HDR source instead of forcing the whole project through an SDR screenshot.
+
+## Limits
+
+- HDR output is MP4 only. MOV, WebM, GIF, PNG sequence, and alpha output fall back to SDR.
+- HDR and `--resolution` supersampling cannot be combined in one render. Author at the target dimensions or resize in a separate step.
+- Distributed AWS Lambda and Cloud Run renders are currently SDR.
+- Hardware H.265 encoding carries the color tags but does not include the same static mastering metadata as the software `libx265` path. Use software encoding for HDR10 delivery.
+- Browser playback depends on the host browser, display, and operating system; `
` does not add its own HDR playback pipeline.
+
+If the file looks SDR, run `ffprobe` on both the source and output before changing the composition. Missing or incorrect source metadata is the most common cause.
+
+## Related topics
-The container runs the same probe → composite → encode pipeline as the local renderer. Verify the output with the same `ffprobe` checks described in [Verifying HDR output](#verifying-hdr-output).
-
-
- Docker HDR rendering currently runs **CPU-side** for the SDR DOM layer (the container falls back to software WebGL because GPU passthrough is not configured by default). Frame capture is therefore slower than local headed Chrome — measure your own composition with `--quiet` off and compare wall-clock times before sizing CI runners. The encoded HDR10 metadata and pixel data are identical to a local render.
-
-
-## Limitations
-
-- **MP4 only** — HDR output with `--format mov` or `--format webm` falls back to SDR
-- **HDR images: 16-bit PNG only** — other formats (JPEG, WebP, AVIF, APNG) are not decoded as HDR and fall through the SDR DOM path
-- **H.265 only — H.264 is stripped** — calling the encoder with `codec: "h264"` and `hdr: { transfer }` is rejected; the encoder logs a warning, drops `hdr`, and tags the output as SDR/BT.709. `libx264` cannot encode HDR, so the alternative would be a "half-HDR" file (BT.2020 container tags but a BT.709 VUI block in the bitstream) which confuses HDR-aware players.
-- **GPU H.265 emits color tags but no static mastering metadata** — `useGpu: true` with HDR (nvenc, videotoolbox, amf, qsv, vaapi) tags the stream with BT.2020 + the correct transfer (smpte2084 / arib-std-b67) but does **not** embed `master-display` or `max-cll` SEI. ffmpeg does not let those flags pass through hardware encoders. The output is suitable for previews and authoring but not for HDR10-aware delivery (Apple TV, YouTube, Netflix). For spec-compliant HDR10 production output, leave `useGpu: false` so the SW `libx265` path embeds the mastering metadata.
-- **Player support** — the [``](/packages/player) web component plays back the encoded MP4 in the browser and inherits whatever HDR support the host browser provides; it does not implement its own HDR pipeline
-- **Headed Chrome HDR DOM capture** — the engine ships a separate WebGPU-based capture path for rendering CSS-animated DOM directly into HDR (`initHdrReadback`, `launchHdrBrowser`). It requires headed Chrome with `--enable-unsafe-webgpu` and is not used by the default render pipeline. See [Engine: HDR](/packages/engine#hdr-apis) if you are building a custom integration.
-
-## Common Pitfalls
-
-| Symptom | Likely cause |
-|---------|--------------|
-| Output looks identical to SDR | Source media is SDR, or SDR was forced with `--sdr`. Run `ffprobe` on your inputs and check the render logs |
-| Output is "kind of HDR" but tone-mapped wrong on YouTube/QuickTime | Missing HDR10 static metadata on the encoded stream. Verify with the ffprobe snippet above |
-| Docker render is much slower than local | Expected — the container falls back to software WebGL for SDR DOM capture. Pixel output is the same |
-| Used `--format webm` and got SDR | Expected — HDR output is MP4 only |
-| HDR `![]()
` looks SDR / washed out | Source is not a 16-bit PNG. Re-export as 16-bit PNG (BT.2020 PQ) or use a `