Covers the HDR still-image pipeline end-to-end with no HDR video
sources present:
- 16-bit BT.2020 PQ PNG (cICP-tagged) is detected via ffprobe,
- decoded once into rgb48le and blitted under the SDR DOM overlay,
- encoded as HEVC Main10 with HDR10 mastering display + content
light level metadata.
Includes a deterministic Python fixture generator (ffmpeg does not
embed cICP in PNGs, so we synthesize the bitmap and inject the chunk
manually) and wires the test into the existing `hdr` CI shard.
Made-with: Cursor
The --hdr flag was silently dropped when combined with --docker because
renderDocker did not include it in the args passed to the in-container
hyperframes render invocation. Forwarding it produces the same HDR10 MP4
(HEVC, yuv420p10le, BT.2020 PQ, mastering display + max-cll) as a local
render — verified end-to-end with the new hdr-pq regression fixture.
This PR also fills in the documentation gaps from the HDR feature stack
(#288, #289, #290, #265, #268), which each added a slice of HDR support
without pulling it together into a single guide.
Code change:
- packages/cli/src/commands/render.ts: refactor renderDocker to use a new
pure helper buildDockerRunArgs (packages/cli/src/utils/dockerRunArgs.ts)
that explicitly threads every render flag — including --hdr, --gpu,
--quiet — into the docker run argv. Snapshot-tested in dockerRunArgs.test.ts
so any future flag drop fails loudly.
Docs:
- New docs/guides/hdr.mdx — top-level HDR guide: quickstart, how detection
works, source media requirements (HDR video + 16-bit HDR PNG), output
format constraints, ffprobe verification, Docker rendering, limitations,
common pitfalls
- docs/guides/common-mistakes.mdx — "Expected HDR but got SDR" entry; --hdr
is detection, not force; notes Docker now supports it
- docs/guides/rendering.mdx — --hdr row in flags table; HDR card under
Next Steps
- docs/packages/cli.mdx — expanded --hdr description with link to the guide
- docs/packages/producer.mdx — HDR Output section under RenderConfig
- docs/packages/engine.mdx — HDR APIs section (color-space utilities +
WebGPU readback runtime); now compiles because DEFAULT_HDR10_MASTERING
and HdrMasteringMetadata are re-exported from packages/engine/src/index.ts
- docs/docs.json — register the new HDR guide in nav
Review feedback from PR #346:
- packages/engine/src/index.ts — export DEFAULT_HDR10_MASTERING and
HdrMasteringMetadata so the engine docs example compiles
- docs/guides/hdr.mdx — drop fabricated "animated HDR images log a warning
and use first frame" claim (not implemented); clarify that HDR <img> is
16-bit PNG only and other formats fall back to SDR; broaden the yt-dlp
example to bestvideo[dynamic_range=HDR]+bestaudio so AV1-HDR streams
are also picked up; qualify the Docker render benchmark claim
- packages/producer/src/services/renderOrchestrator.ts — bump the HDR + non-mp4
fallback from log.info to log.warn and make the message actionable
Regression test (hdr-pq):
- packages/producer/tests/hdr-regression — delete the broken sub-tree.
The old hdr-pq composition relied on a CDN shader-transitions library
and window.__hf injection with scenes defaulting to opacity:0, so when
the library failed to load most of the render was invisible. The fixture
was also nested two directories deep, so discoverTestSuites (which only
scans direct children of tests/) never picked it up.
- packages/producer/tests/hdr-pq — new top-level fixture: 5s of an HDR10
HEVC Main10 BT.2020 PQ source clip with a static SDR DOM overlay. Source
is a 5s excerpt (1:18–1:23) from https://youtu.be/56hEFqjKG0s, downloaded
via yt-dlp and re-encoded to HEVC Main10 / 1920x1080 / 30fps with HDR10
mastering metadata. Self-contained: no external CDNs, no custom fonts,
no animation libraries. NOTICE.md captures attribution.
- packages/producer/src/regression-harness.ts — add optional hdr boolean
to TestMetadata.renderConfig, validate it, and forward it to
createRenderJob so HDR fixtures actually run through the HDR pipeline.
- .github/workflows/regression.yml — exclude hdr from the fast shard and
add a dedicated hdr shard so the new fixture runs on CI.
- .gitattributes — LFS-track packages/producer/tests/*/src/*.mp4 so source
clips don't bloat the repo.
- packages/engine/src/services/frameCapture.ts — inject a no-op __name
shim into every page via evaluateOnNewDocument. tsx transforms the
engine source on the fly with esbuild's keepNames, which wraps every
named function in __name(fn, "name"). When page.evaluate() serializes
a callback those calls would crash with "__name is not defined" because
the helper only exists in Node. The shim makes the engine work whether
it's imported from compiled dist or from source via tsx.
* fix(core): drive adapter seeks when composition has no GSAP timeline
renderSeek returned early when deps.getTimeline() was null, skipping the
onDeterministicSeek call that drives all frame adapters (CSS, WAAPI,
Lottie, Three.js). That meant compositions using any non-GSAP animation
primitive froze on their initial frame during capture.
Now we still quantize the seek time and fire onDeterministicSeek even
without a timeline, so each adapter gets a chance to advance.
GSAP compositions are unaffected — timeline-driven seek still takes the
same path it did before.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(producer): auto-fallback screenshot capture for raf and iframes
Co-Authored-By: Codex <codex@openai.com>
* test(producer): add render compatibility regression fixtures
Co-Authored-By: Codex <codex@openai.com>
* fix(core): scrub CSS animations via WAAPI currentTime
Co-Authored-By: Codex <codex@openai.com>
* test(producer): cover css keyframe renders
Co-Authored-By: Codex <codex@openai.com>
* fix(producer): propagate virtual time into iframe documents
Co-Authored-By: Codex <codex@openai.com>
* test(producer): refresh iframe docker golden
Co-Authored-By: Codex <codex@openai.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Codex <codex@openai.com>
* feat(docs): add template gallery page with visual previews
* fix(docs): remove invalid MDX heading anchors
* chore: retrigger CI
* feat(docs): merge gallery into templates page with hover-to-play video previews
- Consolidated gallery.mdx and templates.mdx into single templates.mdx
- Moved templates page to Getting Started section
- Added MP4 video previews rendered by hyperframes (hover to play)
- Custom JS for hover-to-play behavior (Mintlify strips JSX event handlers)
- 2-column grid for landscape, 3-column for portrait
- Remotion-style cards with gradient overlay labels
* fix(docs): update broken links after templates page move
* ci(regression): remove scripts/ from regression trigger paths
scripts/ contains dev utilities (lint, versioning, preview generation)
that don't affect the rendering engine.
## What
Updated the GitHub Actions regression workflow to monitor specific package directories instead of the entire packages folder.
## Why
This change provides more granular control over when regression tests are triggered, allowing the workflow to run only when changes are made to the core, producer, or engine packages rather than any package in the repository.
## How
Modified the path filters in the regression workflow to explicitly list the three critical package directories (`packages/core/**`, `packages/producer/**`, `packages/engine/**`) instead of using the broad `packages/**` pattern.
## Test plan
How was this tested?
- [ ] Unit tests added/updated
- [ ] Manual testing performed
- [ ] Documentation updated (if applicable)
* fix(ci): update publish workflow to use bun install
pnpm-lock.yaml was removed in the bun migration but publish.yml
still referenced it. Use bun for install/build, keep pnpm for
publish (publishConfig overrides + --provenance).
* docs: update stale pnpm references to bun across docs and scripts
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The CI and regression path filters included their own workflow files,
which meant any PR that changed CI config would trigger the full
build/test/regression suite. Workflow file changes don't need code
validation — they need a test run of the workflow itself, which
happens automatically.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The repo has a ruleset requiring these checks: Build, Typecheck,
Test: core, Test: engine, Test: runtime contract, regression.
With paths-ignore, docs-only PRs would never report these checks,
blocking merge forever.
Fix: add a `changes` job using dorny/paths-filter that detects
whether code files changed. Each job uses `if: needs.changes.outputs.code == 'true'`
which causes GitHub to report the job as "skipped" (counts as passing)
rather than "never started" (counts as pending).
The regression summary job explicitly handles the no-code-changes case
by checking the filter output before evaluating shard results.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- New docs.yml: runs `mint validate` and `mint broken-links` on docs/** changes
- ci.yml: paths-ignore docs/**, *.md so build/typecheck/tests don't run on docs-only PRs
- regression.yml: same paths-ignore to skip Docker regression tests on docs-only PRs
No branch protection is configured, so paths-ignore won't block merges.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Split 21 style tests into 6 shards (3 each, last has 2) to reduce
max wall time from ~38min to ~25min. Each test takes ~7-8min plus
~5min Docker overhead per shard.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
All style regression tests passed on first run — promote them from
optional (continue-on-error) to required. Rebalanced into 4 style
shards + 1 fast shard, all gated by the summary job.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Port the regression test infrastructure from the internal repo to OSS.
Runs golden-baseline visual/audio comparisons inside Docker for deterministic results.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>