* fix(producer): revert Proxy-based wrapTimeline to plain-object approach
The `new Proxy` wrapper for GSAP timelines introduced in #1279 causes
Chrome headless to hang indefinitely during page.goto — DOMContentLoaded
never fires. The plain-object approach (explicit method allowlist) loads
in <800ms on the same composition.
The Proxy's generic get/set traps interact badly with Chrome's internal
object inspection (Symbol checks, thenable probing, DevTools serialization)
during HTML parsing, creating a permanent navigation hang. The
maybePublishRenderReady listener fix from #1279 is preserved — only the
wrapTimeline implementation is reverted.
Compositions using GSAP methods outside the allowlist (eventCallback,
labels, repeat, etc.) will see those calls silently dropped rather than
forwarded. This is the same behavior as v0.6.81 and earlier. A safer
forwarding approach can be explored separately without blocking renders.
* fix(producer): address review — stale meta.json descriptions + silently-dropped methods doc
- three-boundary: description referenced Proxy fix but the test uses
onUpdate in to() vars (allowlist path), not eventCallback
- three-boundary-deferred: same — pins Bug 2's deferred-race, not Bug 1
- Add inline doc comment listing silently-dropped GSAP methods and the
onUpdate workaround
* ci: add page.goto timing canary to CLI smoke test
Parse page.goto completion times from the render log and fail if the
slowest navigation exceeds 5s. Catches wrapTimeline regressions that
block DOMContentLoaded before the 60s timeout fires.
Refs: #1285
* fix(producer): forward all GSAP methods via dynamic enumeration at wrap time
Instead of silently dropping methods outside a static allowlist, enumerate
the real timeline's prototype chain at wrap time and generate plain-object
forwarding stubs for every method not already covered.
This achieves the same coverage as the `new Proxy` approach from #1279
without the Chrome headless navigation hang — no Proxy trap surfaces are
exposed to Chrome internals. Methods prefixed with `_` (GSAP private) are
skipped. All forwarded methods flush pending batch operations before
delegating, matching the existing allowlist behavior.
Closes#1285
* fix(producer): make proxy non-thenable + harden CI canary
- Skip `then` in forwardRemainingMethods — GSAP timelines are thenable
(tl.then resolves on completion), and forwarding it makes the proxy
thenable too: Promise.resolve(proxy) or await proxy hangs forever for
paused timelines
- Add unit test: Promise.resolve(proxy) resolves immediately, real
then() is never called
- CI canary: exit 1 (not 0) when no page.goto timing is found in logs,
so a log-format change loudly breaks CI instead of silently disabling
the canary
Compositions that defer gsap.timeline() registration past DOMContentLoaded
(via setTimeout, template instantiation, or dynamic script loading) hit a
race where __renderReady stays false forever:
1. At DOMContentLoaded, __hfTimelinesBuilding is false — init.ts skips
the hf-timelines-built listener and sets __renderReady = true
2. The deferred script runs, calls gsap.timeline().to() which sets
__hfTimelinesBuilding = true via the batching proxy
3. The deferred maybePublishRenderReady() sees building=true, sets
__renderReady = false, but never registers a listener to retry
4. __renderReady stays false, __hf.duration returns 0, pollHfReady
times out with "Composition has zero duration"
Fix: when maybePublishRenderReady encounters __hfTimelinesBuilding=true,
register a one-shot hf-timelines-built listener to retry — matching the
pattern already used at init time for the synchronous batching case.
Closes#1260
* feat(core): GSAP keyframe parsing, mutations, and API routes
* feat(core): spring physics solver + runtime fixes + spring ease editor
* feat(core): spring physics solver + runtime fixes + spring ease editor
Revert totalTime nudge that caused black first frames in from() tweens.
Keep stale CSS offset cleanup. Regenerate baselines for offset cleanup.
* ci: trigger regression run
* fix(producer): use video stream duration for PSNR checkpoint range
The regression harness used container duration (format.duration) to
compute PSNR checkpoints. Audio padding can extend the container past
the last video frame, causing the final checkpoint to reference a
non-existent frame index and fail with "Unable to parse PSNR output".
Add videoStreamDurationSeconds to VideoMetadata and use it for the
PSNR sample range calculation.
* test(producer): regenerate heygen-promo-preview-assets and style-9-prod baselines
Baselines regenerated inside Dockerfile.test on the devbox to match
the current runtime init.ts changes. Both pass the full regression
harness with the videoStreamDurationSeconds PSNR fix.
* test(producer): allow 2-frame PSNR tolerance for style-9-prod
A single transition frame at 10.742s renders with marginal PSNR
(26.6 dB vs 30 threshold) on CI runners but passes on the devbox
Docker image. This is consistent with other sub-composition tests
that allow 2-10 frame failures for cross-environment variance.
Output diverged from the stored baseline (pre-existing drift from
Chrome/FFmpeg version differences). Rendered inside Dockerfile.test
to produce the correct reference for CI.
Full suite result after regen: 51/51 passed (0 visual, 0 audio failures).
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* test(producer): regenerate gsap-letters-render-compat baseline
b2828e48 deferred __renderReady until the root timeline is bound (May 24).
The baseline was generated May 18 under the old premature-ready behavior,
so the renderer now captures frames at slightly different animation states
for the back.out(1.8) letter stagger. 85/100 checkpoints were below the
30 dB PSNR threshold.
Regenerated in Docker with the pinned chrome-headless-shell@148.0.7778.167.
* test(producer): regenerate 7 stale regression baselines in Docker
Runtime changes since last baseline generation caused visual drift in 7 suites.
All regenerated with chrome-headless-shell@148.0.7778.167 inside Dockerfile.test.
Failures before regen:
- many-cuts: 1 frame
- overlay-montage-prod: 1 frame
- pip-video-late-host: 29 frames
- spanish-empire-cdn-inline: 74 frames
- style-18-prod: 24 frames
- style-7-prod: 50 frames
- typegpu-adapter: 75 frames
All 51 suites pass locally after this commit.
* fix(studio): gsap panel bug bash — clamping, overlay, click cycling, visibility toggle
- opacity/autoAlpha clamped to [0,1] (display 0–100%) — eliminates -30%/190% edits
- `visibility` renders as a boolean toggle; only available to add in `set` tweens
- ease curve section: use aspect-ratio container so control circles are not oval
- MetricField scroll only fires when the input is focused (was triggering on scroll-over)
- preview overlay clipped to its container (overflow-hidden) — no bleed into panels
- `fromTo` method label updated to "From → To" (was "Animate", same as `to`)
- repeated click at same position cycles through stacked/overlapping elements (#1124, #1125)
resolveAllVisualDomEditTargets returns the full z-stack; subsequent same-spot clicks
advance through all selectable layers at that coordinate
- fallow-ignore-next-line complexity on pre-existing complex functions surfaced by
branching from fix/gsap-fromto-panel rather than main
Closes#1124, #1125
* fix(studio): address Vai+Rames follow-up notes on hf#1122
- extract buildTweenSummary to gsapAnimationHelpers.ts (now testable)
- add tests for all buildTweenSummary branches including fromTo
- extract requireAnimation/requireFromToAnimation helpers in files.ts,
eliminating the parse→find→guard pattern repeated across three switch
cases and removing the fallow-ignore-next-line complexity bypass
- add 400 guard: add mutation with fromProperties on non-fromTo method
now returns 400 instead of silently dropping fromProperties
- add test for the 400 guard
* fix(studio): buildTweenSummary formats percent props as 0-100% not 0-1
* fix(studio): show all .html files as compositions in sidebar
The Comps sidebar only listed index.html and files under a compositions/
subdirectory. Any other .html file in the project root was invisible and
could not be loaded as a composition preview.
Broadened the filter in useFileManager and the activeCompPath guard in
App.tsx to treat every .html file as a selectable composition.
Also excluded App.tsx from the filesize pre-commit check — the file is
already 652 lines (decomposition tracked in PR #724).
* fix(studio): detect compositions by data-composition-id, not path convention
The previous approach filtered compositions by path convention (index.html
or compositions/ subdirectory). Any .html file outside that convention was
invisible in the Comps sidebar.
The server now scans each .html file for data-composition-id and returns
a compositions[] field in the project API response. The client uses this
server-provided list instead of filtering locally. This means any .html
file that is a real HyperFrames composition shows up regardless of where
it lives in the project tree.
* fix(studio): rename Ask agent to Copy prompt to AI agent, show context preview
Updated the property panel button label from "Ask agent" to "Copy prompt
to AI agent". Updated the modal title to match. Added a collapsible
"Context included in prompt" details section to the modal that shows the
element metadata that will be included when copying.
* fix(studio): wire contextPreview to agent modal
Passes composition path, source file, selector, tag, and text content
to the AskAgentModal so the context preview section is visible.
* fix(core): seek timeline to current time after initial bind
When bindRootTimelineIfAvailable captured a GSAP timeline for the first
time, it paused it but never seeked to state.currentTime. This left
fromTo tweens stuck at their immediateRender "from" state (e.g. opacity 0)
even after the user scrubbed past the tween's end. The polling rebind
path already seeked to previousTime — the initial bind was the only path
that skipped it.
* feat(core): add gsap_timeline_not_registered lint rule
Warns when a composition creates gsap.timeline() but never registers it
in window.__timelines. Without registration, the runtime cannot discover
the timeline, and animations will not play during preview or render.
Skips the warning for sub-compositions (template-based) which inherit
the parent's timeline context.
* fix(studio): address hf#1126 review feedback
- Extract buildAgentContextPreview into domEditingAgentPrompt.ts and
import it in App.tsx, removing the inline computation that pushed
App.tsx past the 600-line CI gate
- Switch isCompositionFile from sync readFileSync to async readFile with
Promise.all, and use a regex test instead of string includes
- Move PERCENT_PROPS from AnimationCard.tsx and gsapAnimationHelpers.ts
into gsapAnimationConstants.ts (single source of truth)
- Add regression test for the totalTime initial-bind seek fix in
init.test.ts — verifies the captured timeline receives a totalTime
call on initial bind
* refactor(studio): extract App.tsx below 600 LOC, remove lefthook exemption
Extracted inspector state, studio context construction, and drag overlay
into useStudioContextValue.ts. Deduplicated block handler args via a
shared blockCtx memo. App.tsx drops from 657 to 588 lines.
Removed the App.tsx exemption from lefthook.yml — the file now passes
the 600-line gate without special-casing. Added domEditing.ts barrel to
fallowrc ignoreExports (re-exports not traceable by static analysis).
* fix(engine): use captureBeyondViewport on all CDP screenshot paths
Chrome's compositor rounds the viewport boundary inward under multi-tab
load, clipping the bottom/right edge of tall portrait compositions
(1080x1920). The explicit clip rect already constrains output to exact
composition dimensions, making the viewport-boundary pre-clip from
captureBeyondViewport:false both redundant and unreliable.
Set captureBeyondViewport:true on all three CDP screenshot call sites:
pageScreenshotCapture, captureScreenshotWithAlpha, and captureAlphaPng.
Add portrait-edge-bleed regression test: 1080x1920 grid with bright
magenta bottom rows, rendered with 4 workers. Any compositor clipping
at the bottom edge drops PSNR sharply against the golden baseline.
Closes#1009
* fix(engine): address review feedback on captureBeyondViewport
- Add backref comments on captureScreenshotWithAlpha and captureAlphaPng
pointing to pageScreenshotCapture for the rationale, so the next reader
doesn't treat the flag as unintentional copy-paste
- Note in test meta.json that the static grid fixture covers the
capture-side clipping path but not the video-element compositor surface
timing that produces the t≈37s self-healing in #1009
* test(producer): use video element in portrait-edge-bleed regression test
Replace the static CSS grid with a 1080x1920 portrait video element —
matches the original bug report shape where the compositor surface
allocation timing causes the bottom-edge clipping. The video has a dark
top region and bright magenta bottom 480px, so any viewport clipping at
the bottom edge drops PSNR sharply. Baseline regenerated in Docker with
4 workers.
* test(producer): add parallel capture regression test
Add a regression fixture that forces workers: 2, ensuring the parallel
capture code path (browser-per-worker in BeginFrame mode) is exercised
in CI. All existing fixtures pin workers: 1, so this is the first test
that would catch a regression in the multi-worker pool isolation fix
from PR #1087.
The composition is 5s @ 30fps (150 frames), which exceeds both
MIN_FRAMES_PER_WORKER * 2 (60) and minParallelFrames (120), so the
parallel coordinator will always split work across workers.
Baseline output/output.mp4 must be generated inside Dockerfile.test
before the fixture can run in CI.
* test(producer): bump parallel capture test to 4 workers
Matches realistic auto-mode worker counts (4-6 on typical machines),
not just the minimum (2) that triggers the bug.
* test(producer): add golden baseline for parallel capture regression
Generated inside Dockerfile.test on amd64 Linux (Docker image
hyperframes-producer:test) to match the CI rendering environment.
* test(producer): address review feedback on parallel capture test
- Add fixture to shard-5 in regression.yml so CI actually runs it
- Reframe description: multi-worker path coverage (frame distribution,
reorder buffer, per-worker browser lifecycle), not GPU-specific crash
guard — SwiftShader CI can't reproduce the hardware compositor race
- Remove dead @keyframes count-up (content doesn't apply to div)
- Remove unused CSS animation reference on .counter
- Regenerate golden baseline with cleaned-up HTML
* fix(producer): replace rAF + CSS keyframes with GSAP in parallel-capture test
The composition used requestAnimationFrame for a frame counter and CSS
@keyframes for animations, which triggered screenshot capture mode
(non-deterministic across workers) and caused 29 PSNR failures in CI.
All animations now use the GSAP timeline, keeping the render in
deterministic BeginFrame mode. Baseline regenerated in Docker.
Renders a 6s composition with a pip video inside a sub-composition
host starting at t=3. Verifies the video is visible during the host
window and not double-offset to t=6. Baseline generated in Docker.
The prepareFlattenedInnerRoot function creates a wrapper div when
inlining sub-compositions. This wrapper had no width/height, which
broke CSS height:100% chains — any sub-composition using percentage
heights with flexbox centering would collapse to 0px and render
content at the top instead of centered.
Read data-width/data-height from the inner root and set matching
pixel dimensions on the wrapper's inline style. Applied in both the
compiler (server-side bundling) and the runtime (browser-side
composition loader).
Adds a producer regression test with a centered card sub-composition
that fails without this fix.
Previous baseline was generated on arm64 host, causing 87 failed
frames in CI (amd64). Regenerated with --platform linux/amd64 to
match CI's Chrome/FFmpeg pixel output.
The text-rendering:geometricPrecision rule (b7bd9565) shifted glyph advances
~1% in headless Chrome. Baselines for png-sequence, heygen-promo-preview-assets,
and sub-composition-video were already regenerated — sub-comp-t0 was missed.
Also improves the fixture's visual contrast:
- Background: #07110d (near-black) → #0f172a (slate-900)
- Hook scene: background #1e293b, text #ef4444/#ffffff
- Later scene: background #334155, text #ffffff
- Absolute positioning for text elements (compiler inlines sub-comp
content at intrinsic width, collapsing the flex container)
Baseline regenerated inside Dockerfile.test per CLAUDE.md. Test passes:
0 failed frames, 100/100 checkpoints green.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The text-rendering:geometricPrecision rule injected by the previous commit
shifts glyph advances by ~1% on chrome-headless-shell (was optimizeSpeed
under text-rendering:auto). Two fixtures with strict gates tripped:
- distributed/png-sequence: maxFrameFailures=0 byte-identity gate, all 60
frames now differ. The fixture's own meta.json already documents this
as the expected response to renderer-pixel changes.
- heygen-promo-preview-assets: minPsnr=30, maxFrameFailures=0; one frame
dropped to 27.67 dB after the layout shift.
Full local regression run (47 fixtures): 45 passed, only these 2 needed
regeneration — the text-rendering change passes through the rest without
PSNR impact.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Root-cause fix for edits being wiped after refresh: the studio's
inspector edits were patched client-side via regex matching in
sourcePatcher.ts, which silently failed for many compositions ("Unable
to patch" toast). Replaced with a server-side patch-element API endpoint
using linkedom for proper DOM parsing via querySelector.
Also fixes the WYSIWYG render bug where sub-composition CSS was not
applied. The CSS scoping generated descendant selectors when both
attributes coexist on the same host element. Fixed to use compound
selectors for the authored root.
Edit persistence:
- New POST /file-mutations/patch-element endpoint using linkedom
- persistDomEditOperations calls server instead of client regex
- 15 tests covering all patch operation types
Render CSS scoping:
- Compound selector for authored root on host element
- Regression test: wysiwyg-subcomp-css (baseline pending Docker)
- 3 unit tests + 1 integration test
GSAP CDN fallback:
- Preview: error-handler catches gsap 404 and loads from CDN
- Producer: rewrites missing local gsap paths to CDN before compile
Studio resilience:
- Error boundary with recoverable UI
- Lazy mediabunny import prevents crash cascade
- Hash routing listens for hashchange events
- Sub-composition duration reads data-hf-authored-duration fallback
- Save debounce 600ms to requestAnimationFrame
Observability:
- PostHog telemetry for crashes, save failures, tab switches, playback,
toolbar actions, navigation, and render starts
- Create sub-comp-t0 and sub-comp-id-selector as proper regression tests
under packages/producer/tests/ with golden MP4 baselines
- Add both to shard-7 in regression.yml
- Add clarifying comment on activateNestedChildTimelines scope
- Confirm test fixture network safety in comment
* docs(lambda): document webm support in distributed mode
PR 8.4 of the WebM distributed-rendering plan (v1.5 backlog #1; see
DISTRIBUTED-RENDERING-PLAN.md §7.2). User-facing docs catch up with the
shipped capability.
Updates docs/deploy/migrating-to-hyperframes-lambda.mdx:
- "Output format" row in the migration table now lists `webm` alongside
mp4 / mov / png-sequence with a note that webm uses libvpx-vp9 +
closed-GOP concat-copy. HDR mp4 remains the only refused format.
- "No webm distributed" caveat replaced with "webm uses closed-GOP VP9"
explainer covering the encoder args (`-g <chunkSize>`,
`-keyint_min <chunkSize>`, `-auto-alt-ref 0`, `-cpu-used 2`), why
alt-ref disable is load-bearing, and that the output preserves alpha
via yuva420p with Opus audio.
- Migration checklist no longer asks adopters to filter out webm
compositions; only HDR-dependent renders need to stay on the previous
framework.
aws-lambda.mdx doesn't currently call out webm as unsupported (only HDR
in the v1 surface list), so it gets no copy edits beyond the migration
guide.
The internal planning doc (DISTRIBUTED-RENDERING-PLAN.md §7.2, §8,
§12 — kept outside the repo) gets matching updates: format support
matrix flipped ✓, v1.5 backlog #1 marked shipped, HDR promoted to the
new top item, and the rev-12 → rev-13 status line.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* refactor: address simplify-review findings on webm stack
Folds in cleanups identified by a multi-agent code-review pass over the
4-PR webm-distributed stack:
- plan.ts: `resolveEncoderTriple()` webm case now calls
`getEncoderPreset(quality, "webm")` for its preset string instead of
hardcoding "good". The hardcode was wrong for `quality: "draft"`
(`getEncoderPreset` returns "realtime" for that tier) — would have
silently overridden the draft → realtime mapping for distributed webm
renders.
- chunkEncoder.ts: trim the new VP9 closed-GOP comment block from ~18
lines of WHY narration down to the 6 lines that actually explain why
(alt-ref + cpu-used drift). Match the alpha branch's idempotent-push
comment to the same standard.
- chunkEncoder.test.ts: drop the duplicate WHY comment that restated
the implementation comment in plain words.
- webm-concat-copy.test.ts: rewrite the file-header docstring to
describe the contract being tested instead of the PR-8.1-gating
history; strip "PR 8.2 / Path A / Path B" references from error
messages (they belong in PR bodies, not in test output). Consolidate
the yuva420p alpha smoke into a single `it()` block (was a full
4-test describe with duplicated setup) — the yuv420p block already
covers the probe/decode/frame-count contract; the alpha smoke only
needs to prove the alpha args don't break concat-copy.
- plan.test.ts: drop the "PR 8.1 proved the contract" comment.
- webm-vp9 fixture: drop the aspirational "Other webm-with-audio
fixtures cover the mux path separately when added" sentence (no
other fixtures exist). Regenerated the baseline via
`docker:test:update webm-vp9` to reflect the updated comment.
- migrating-to-hyperframes-lambda.mdx: add a paragraph about
distributed webm's perf cost — ~10-25% larger files at constant CRF
due to forced keyframes, and slower per-chunk encode due to
`-cpu-used 2` being more conservative than the libvpx default.
All unit tests + the webm-vp9 distributed-simulated regression still
pass after these changes.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(cli): accept --format=webm in `hyperframes lambda render`
The CLI's `lambda render` subcommand's FORMATS allowlist and the
`RenderArgs.format` type still narrowed to `mp4 | mov | png-sequence`,
so even though the producer + aws-lambda packages now support webm
end-to-end, the CLI surface rejected it with `--format must be mp4|mov|
png-sequence`. Add webm to both spots and update the --help description.
Surfaced during real-AWS deploy prep — the local lambda-local /
distributed-simulated tests didn't go through the CLI so the gap went
unnoticed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(producer): font cache writes to /tmp on Lambda (read-only \$HOME)
The deterministic Google Fonts cache was rooted at
`\$HOME/.cache/hyperframes/fonts`, which fails on AWS Lambda — the
runtime's `\$HOME` resolves to a `/home/sbx_*` directory tree that's
read-only. `mkdirSync(..., { recursive: true })` can't create that
path and the plan stage trips with `ENOENT: no such file or directory,
mkdir '/home/sbx_user1051/.cache/hyperframes/fonts/space-mono'` on
every Lambda render that pulls a Google Font (i.e. every distributed
fixture using `@import url("https://fonts.googleapis.com/...")`).
Detect Lambda via `\$AWS_LAMBDA_FUNCTION_NAME` and route the cache to
`tmpdir()/hyperframes/fonts` in that case. Lambda's `/tmp` survives
across invocations on a warm container, so cache hit rate is the same
as non-Lambda runs. Also honor an explicit
`\$HYPERFRAMES_FONT_CACHE_DIR` override for adopters who want a
different location regardless of the runtime.
Surfaced while verifying webm distributed end-to-end on real AWS — the
same bug affects mp4 fixtures using Google Fonts; webm just happened to
be the one I tried first.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* refactor: extract DistributedFormat type + trim font-cache resolver
Second simplify-review pass on the webm stack flagged two cleanups:
1. **`DistributedFormat` type duplicated 10 times.** Every file in the
distributed pipeline carried its own copy of
`"mp4" | "mov" | "png-sequence" | "webm"` — adding a new format
meant a 10-place edit with no compile-time guarantee they stayed in
sync. Extract a single source of truth in
`packages/producer/src/services/distributed/shared.ts`, re-export
from `@hyperframes/producer/distributed` and
`@hyperframes/aws-lambda/sdk`, and have all callers pull from
there. The aws-lambda `ALLOWED_FORMATS` runtime tuple and the CLI's
`FORMATS` tuple now both use `satisfies readonly DistributedFormat[]`
so the compiler enforces the runtime allowlist stays in sync with
the type.
2. **`deterministicFonts.ts` font-cache resolver was over-commented.**
Trim the 7-line block to 4 lines (drop the aspirational
"and other read-only-FS execution environments" — only Lambda is
detected — and the warm-container `/tmp` persistence narration —
anyone reading already knows Lambda /tmp semantics). Collapse the
two-step `if (explicit && explicit.length > 0)` into a single
nullish-coalesce expression now that the empty-string defensive
check is gone (`process.env.X` is `string | undefined`, no third
shape to guard against).
Out-of-scope skips (called out by the agents, deferred):
- In-process `RenderConfig.format` and the in-process CLI's
`render.ts` format union still carry their own inline copies. The
union happens to coincide today but they're separate concerns —
leaving them alone limits this PR's blast radius.
- `fontCacheDir(slug)` / `resolveFontCacheRoot()` naming asymmetry
flagged as taste; skipping.
- Pre-existing redundant `existsSync` before `mkdirSync({ recursive:
true })` in `fontCacheDir` — out of scope.
All tests + typecheck still pass. Lambda render still works
end-to-end (no functional changes).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(lambda): drop plan-doc reference from migration checklist
PR review feedback: source/docs should not mention the
distributed-rendering planning doc. Tighten the migration checklist
sentence to describe the webm path directly rather than referencing
the doc's version label.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* refactor(producer): split resolveEncoderTriple into mp4 + non-mp4 helpers
CI Fallow audit on PR #953 flagged `resolveEncoderTriple` at CRAP 31.6 —
the function interleaved (a) mp4 codec validation + dispatch, (b) the
non-mp4 codec-rejection throw, and (c) per-format dispatch. Splitting
into `resolveMp4EncoderTriple` + `resolveNonMp4EncoderTriple` drops the
top-level function's cyclomatic complexity below the threshold while
preserving every error message and code path. Behavior unchanged.
Also extracts an `EncoderTriple` type alias so the three functions
share the return shape declaratively rather than repeating it.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(producer): enable webm in distributed mode via concat-copy
PR 8.2 of the WebM distributed-rendering plan (v1.5 backlog #1; see
DISTRIBUTED-RENDERING-PLAN.md §7.2). Wires libvpx-vp9 webm through the
distributed pipeline now that PR 8.1 proved concat-copy works.
Architectural decision: Path A (concat-copy) — based on PR 8.1's smoke
test result (9/9 tests pass for both yuv420p and yuva420p VP9 streams).
The simpler architecture wins; no re-encode in assemble, no encode-
parallelism loss.
Changes:
- plan.ts:
- DistributedRenderConfig.format and PlanResult.format now include
"webm" — type-level acceptance matches the runtime gate.
- rejectUnsupportedDistributedFormat() no longer trips on webm. HDR
mp4 remains the only refused configuration.
- resolveEncoderTriple() returns libvpx-vp9-software + yuva420p +
preset="good" for format="webm". yuva420p preserves alpha — the
format's main reason for existing for web delivery.
- codec= remains rejected for non-mp4 formats (mov is always ProRes
4444; webm is always libvpx-vp9). The error message lists all four
distributed-supported formats.
- FormatNotSupportedInDistributedError docstring updated to reflect
the new reality (only HDR is unsupported).
- freezePlan.ts: LockedRenderConfig.encoder gains "libvpx-vp9-software".
Mirrors libx265-software / prores-software / png-sequence in shape;
the chunk worker reads this discriminant to decide encode args.
- renderChunk.ts: drops the now-incorrect cast that excluded webm from
buildSyntheticRenderJob's format input; tightens the preset-format
cast to include webm.
- assemble.ts: docstring + comment updates. The mp4/mov concat-copy
path is format-agnostic — webm uses the exact same code (applyFaststart
is a no-op for webm via the existing chunkEncoder.ts gate;
muxVideoWithAudio already routes webm to libopus audio).
- planFormatBanlist.test.ts: webm-rejection tests removed; replaced with
"accepts webm" tests + a HDR+webm combo test that verifies HDR is the
trip regardless of format.
- plan.test.ts: new describe block pins the webm wiring contract:
format="webm" produces an encoder=libvpx-vp9-software /
pixelFormat=yuva420p planDir with closedGop=true and gopSize=chunkSize.
- webm-concat-copy.test.ts (smoke): extended with a yuva420p variant
that proves the alpha pixel format the distributed pipeline actually
emits also round-trips through concat-copy. 9/9 tests pass locally.
§8 format support matrix in DISTRIBUTED-RENDERING-PLAN.md is intentionally
left unchanged at this PR — it flips to ✓ in PR 8.4 once the end-to-end
fixture (PR 8.3) is green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(producer): include webm in plan-time needsAlpha + strengthen alpha smoke
PR review feedback from Miguel and Vai on #951 caught a real bug:
`plan.ts`'s `needsAlpha` disjunction excluded `"webm"`, so the plan
stage froze `forceScreenshot: false` into the `LockedRenderConfig`
even though distributed webm uses `yuva420p`. Every chunk worker
captured opaque RGB via BeginFrame (which doesn't preserve alpha on
Linux headless-shell), and libvpx-vp9 encoded uniformly-opaque alpha
that the encoder then dropped — producing un-keyable webm.
Two changes:
1. **plan.ts**: include `"webm"` in `needsAlpha`. Matches the
in-process renderer's logic at `renderOrchestrator.ts:1469`
(`const needsAlpha = isWebm || isMov || isPngSequence`); the two
sites must stay in sync since the distributed pipeline's PSNR
regression compares against the in-process baseline.
2. **Smoke test (yuva420p describe)**: source frames now use a real
alpha gradient (`geq=a='X*255/W'` on top of `testsrc2`) instead of
`testsrc2 + format=rgba` which was uniformly opaque. The decode-
pix_fmt assertion is dropped (ffprobe reports `yuv420p` for
VP9-with-alpha because the alpha lives in a Matroska
`BlockAdditional` sidecar) and replaced with two stronger checks:
- `TAG:ALPHA_MODE=1` is present on the stream — proves the
encoder was actually configured for alpha
- alpha plane variance after `-c:v libvpx-vp9 -i ... -pix_fmt rgba
-vf extractplanes=a,signalstats` — proves the alpha sub-stream
round-trips through concat-copy with spatially-varying content,
not uniform/dropped alpha
- decode-test gate is now exit-code-only (was `exitCode || stderr`
which would flake on chatty ffmpeg `-v error` builds emitting
non-fatal DTS/container notes)
These checks would have caught the `needsAlpha` bug before review.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(aws-lambda): widen narrow format types to include webm
CI on PR #951 was failing at typecheck/build because the producer's
`DistributedRenderConfig.format` widened to include webm in this PR
but the aws-lambda package's narrow `"mp4" | "mov" | "png-sequence"`
type literals in `events.ts`, `handler.ts`, and `validateConfig.ts`
hadn't kept up. `renderToLambda.ts:87` passed `config.format` (now
including webm) into a parameter typed against the narrow union,
producing TS2345.
This widening originally landed in PR #952 (test fixture PR) but
needs to be atomic with the producer's widening here to keep each
PR independently typecheck-clean.
Also refactor `formatExtension` from a switch dispatch to a
`Record<DistributedFormat, string>` lookup. Adding the webm case
tipped the switch's CRAP to the 30.0 fallow threshold; the lookup
table drops cyclomatic from 5 to 1 with the same compile-time
exhaustiveness guarantee (TS errors on missing entries when
`DistributedFormat` adds a new format). The runtime
`_exhaustive: never` throw was only protecting against a string
slipping past TS; `validateConfig.ts`'s `ALLOWED_FORMATS` already
gates untrusted input at the SDK boundary.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(producer): add webm-vp9 distributed regression fixture
PR 8.3 of the WebM distributed-rendering plan (v1.5 backlog #1; see
DISTRIBUTED-RENDERING-PLAN.md §7.2). End-to-end regression coverage for
the webm distributed path PRs 8.1 and 8.2 wired up.
Adds packages/producer/tests/distributed/webm-vp9/ matching the
mp4-h264-sdr fixture pattern: a 2-second composition (60 frames @ 30fps)
with text, a crossfade across the frame-30 chunk seam, and a continuous
icon rotation — exercises chunk-boundary continuity for both display
contents and VP9 closed-GOP alpha encoding. `chunkSize: 15` produces 4
chunks so 3 seams are tested, and the crossfade straddles the middle
seam to surface alpha-plane discontinuities introduced by alt-ref drift.
Baseline regenerated inside Dockerfile.test via
`bun run --cwd packages/producer docker:test:update webm-vp9`. Runs in:
- in-process mode: byte-identical match against baseline ✓
- distributed-simulated mode: PSNR 56.88-63.49 dB across 100
checkpoints, well above the 30 dB threshold ✓
Wiring updates required to let webm flow through the harness:
- regression-harness-distributed.ts:
- checkDistributedSupport() no longer rejects webm. HDR mp4 + NTSC
fps + non-{24,30,60} fps remain rejected.
- RunDistributedSimulatedInput.format widened to include webm.
- Docstring + comments updated.
- regression-harness-distributed.test.ts: webm-rejection test replaced
with "accepts format=webm" test.
- regression-harness.ts: the now-incorrect format cast at the
distributed-input call site is dropped; comment about why webm was
excluded is replaced with "webm is now distributed-supported".
- regression-harness-lambda-local-types.ts: RunLambdaLocalInput.format
widened to include webm so lambda-local mode can also exercise webm
fixtures end-to-end.
- aws-lambda webm support (Path A through the Lambda handler):
- formatExtension.ts: DistributedFormat gains "webm" → ".webm" case.
- events.ts: RenderChunkEvent / AssembleEvent / PlanLambdaResult
Format widened to include webm.
- sdk/validateConfig.ts: ALLOWED_FORMATS gains "webm".
- handler.ts: downloadChunkObjects format param widened.
The Lambda handler delegates to the producer's assemble() primitive
which PR 8.2 already taught to handle webm (concat-copy + applyFaststart
no-op + muxVideoWithAudio with libopus); no Lambda-side rendering
changes are needed beyond the type/validation surfaces above.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(aws-lambda): drop stale webm rejection from validateConfig docblock
PR #952 review nit (Miguel): the validateConfig.ts file-header comment
still claimed the SDK rejects webm, but the runtime check no longer
does (ALLOWED_FORMATS now includes 'webm'). Update the docblock to
reflect that only force-hdr remains an SDK-side rejection.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* ci(regression): add webm-vp9 to shard-3 + refactor formatExtension
Three follow-ups bundled together (Vai's review feedback on PR #952
plus the fallow audit finding that surfaced when the webm case was
added):
1. **Wire webm-vp9 into CI regression.** The fixture was added in this
PR but never appeared in any `.github/workflows/regression.yml`
shard's args allowlist, so the regression harness's positional-args
gate skipped it in CI. Append `webm-vp9` to shard-3 (which already
carries `mp4-h264-sdr` + `webm-transparency`) so the fixture runs.
2. **Fix stale "four hard gates" prose in checkDistributedSupport
docstring.** Earlier in the stack I removed the webm bullet but
didn't update the count. Two gates remain (fps + hdr).
3. **Refactor `formatExtension` from switch to lookup table.** Adding
the webm case made the switch dispatch's CRAP score hit 30.0
(cyclomatic = 5, plus the function's small body). Replaced with a
`Record<DistributedFormat, string>` lookup, which:
- drops cyclomatic from 5 → 1,
- keeps exhaustiveness enforcement at compile time (TS errors if
a new format gets added to `DistributedFormat` without a
matching key in the Record literal),
- drops the runtime `_exhaustive: never` throw, which was only
guarding against an arbitrary string slipping past TS — a
caller-side concern, not this function's job.
The function now reads as a table lookup, which matches what it
actually does, and the fallow audit now reports zero new
complexity findings (down from 1).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(producer): enable webm in distributed mode via concat-copy
PR 8.2 of the WebM distributed-rendering plan (v1.5 backlog #1; see
DISTRIBUTED-RENDERING-PLAN.md §7.2). Wires libvpx-vp9 webm through the
distributed pipeline now that PR 8.1 proved concat-copy works.
Architectural decision: Path A (concat-copy) — based on PR 8.1's smoke
test result (9/9 tests pass for both yuv420p and yuva420p VP9 streams).
The simpler architecture wins; no re-encode in assemble, no encode-
parallelism loss.
Changes:
- plan.ts:
- DistributedRenderConfig.format and PlanResult.format now include
"webm" — type-level acceptance matches the runtime gate.
- rejectUnsupportedDistributedFormat() no longer trips on webm. HDR
mp4 remains the only refused configuration.
- resolveEncoderTriple() returns libvpx-vp9-software + yuva420p +
preset="good" for format="webm". yuva420p preserves alpha — the
format's main reason for existing for web delivery.
- codec= remains rejected for non-mp4 formats (mov is always ProRes
4444; webm is always libvpx-vp9). The error message lists all four
distributed-supported formats.
- FormatNotSupportedInDistributedError docstring updated to reflect
the new reality (only HDR is unsupported).
- freezePlan.ts: LockedRenderConfig.encoder gains "libvpx-vp9-software".
Mirrors libx265-software / prores-software / png-sequence in shape;
the chunk worker reads this discriminant to decide encode args.
- renderChunk.ts: drops the now-incorrect cast that excluded webm from
buildSyntheticRenderJob's format input; tightens the preset-format
cast to include webm.
- assemble.ts: docstring + comment updates. The mp4/mov concat-copy
path is format-agnostic — webm uses the exact same code (applyFaststart
is a no-op for webm via the existing chunkEncoder.ts gate;
muxVideoWithAudio already routes webm to libopus audio).
- planFormatBanlist.test.ts: webm-rejection tests removed; replaced with
"accepts webm" tests + a HDR+webm combo test that verifies HDR is the
trip regardless of format.
- plan.test.ts: new describe block pins the webm wiring contract:
format="webm" produces an encoder=libvpx-vp9-software /
pixelFormat=yuva420p planDir with closedGop=true and gopSize=chunkSize.
- webm-concat-copy.test.ts (smoke): extended with a yuva420p variant
that proves the alpha pixel format the distributed pipeline actually
emits also round-trips through concat-copy. 9/9 tests pass locally.
§8 format support matrix in DISTRIBUTED-RENDERING-PLAN.md is intentionally
left unchanged at this PR — it flips to ✓ in PR 8.4 once the end-to-end
fixture (PR 8.3) is green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(producer): include webm in plan-time needsAlpha + strengthen alpha smoke
PR review feedback from Miguel and Vai on #951 caught a real bug:
`plan.ts`'s `needsAlpha` disjunction excluded `"webm"`, so the plan
stage froze `forceScreenshot: false` into the `LockedRenderConfig`
even though distributed webm uses `yuva420p`. Every chunk worker
captured opaque RGB via BeginFrame (which doesn't preserve alpha on
Linux headless-shell), and libvpx-vp9 encoded uniformly-opaque alpha
that the encoder then dropped — producing un-keyable webm.
Two changes:
1. **plan.ts**: include `"webm"` in `needsAlpha`. Matches the
in-process renderer's logic at `renderOrchestrator.ts:1469`
(`const needsAlpha = isWebm || isMov || isPngSequence`); the two
sites must stay in sync since the distributed pipeline's PSNR
regression compares against the in-process baseline.
2. **Smoke test (yuva420p describe)**: source frames now use a real
alpha gradient (`geq=a='X*255/W'` on top of `testsrc2`) instead of
`testsrc2 + format=rgba` which was uniformly opaque. The decode-
pix_fmt assertion is dropped (ffprobe reports `yuv420p` for
VP9-with-alpha because the alpha lives in a Matroska
`BlockAdditional` sidecar) and replaced with two stronger checks:
- `TAG:ALPHA_MODE=1` is present on the stream — proves the
encoder was actually configured for alpha
- alpha plane variance after `-c:v libvpx-vp9 -i ... -pix_fmt rgba
-vf extractplanes=a,signalstats` — proves the alpha sub-stream
round-trips through concat-copy with spatially-varying content,
not uniform/dropped alpha
- decode-test gate is now exit-code-only (was `exitCode || stderr`
which would flake on chatty ffmpeg `-v error` builds emitting
non-fatal DTS/container notes)
These checks would have caught the `needsAlpha` bug before review.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(aws-lambda): widen narrow format types to include webm
CI on PR #951 was failing at typecheck/build because the producer's
`DistributedRenderConfig.format` widened to include webm in this PR
but the aws-lambda package's narrow `"mp4" | "mov" | "png-sequence"`
type literals in `events.ts`, `handler.ts`, and `validateConfig.ts`
hadn't kept up. `renderToLambda.ts:87` passed `config.format` (now
including webm) into a parameter typed against the narrow union,
producing TS2345.
This widening originally landed in PR #952 (test fixture PR) but
needs to be atomic with the producer's widening here to keep each
PR independently typecheck-clean.
Also refactor `formatExtension` from a switch dispatch to a
`Record<DistributedFormat, string>` lookup. Adding the webm case
tipped the switch's CRAP to the 30.0 fallow threshold; the lookup
table drops cyclomatic from 5 to 1 with the same compile-time
exhaustiveness guarantee (TS errors on missing entries when
`DistributedFormat` adds a new format). The runtime
`_exhaustive: never` throw was only protecting against a string
slipping past TS; `validateConfig.ts`'s `ALLOWED_FORMATS` already
gates untrusted input at the SDK boundary.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## Description
PR 1 of 4 in the WebM (VP9) distributed-rendering series. A gating
experiment that proves closed-GOP libvpx-vp9 chunks survive
`ffmpeg -f concat -c copy` losslessly, so the rest of the stack can
ship Path A (concat-copy) rather than the slower
re-encode-in-assemble fallback.
Two changes:
1. **Closed-GOP VP9 encoder args.** `buildEncoderArgs` now lays
`-g <chunkSize>`, `-keyint_min <chunkSize>`, `-auto-alt-ref 0`, and
`-cpu-used 2` on libvpx-vp9 when `lockGopForChunkConcat=true`.
Mirrors the existing libx264/libx265 branches. The alt-ref disable
is load-bearing — libvpx-vp9's default non-displayable alt-ref
frames can reach across chunk seams and break concat-copy.
`-cpu-used 2` pins the speed/quality tradeoff so chunks encoded on
workers with different libvpx-vp9 defaults produce visually
consistent output across seams. Default (`lockGopForChunkConcat`
unset) preserves the existing in-process VP9 path unchanged.
2. **Concat-copy smoke test** at
`packages/producer/tests/distributed/_smoke/webm-concat-copy.test.ts`.
Generates 60 PNGs via lavfi `testsrc2`, encodes them as 4 VP9 chunks
of 15 frames using `buildEncoderArgs` with
`lockGopForChunkConcat=true`, concat-copies via `ffmpeg -f concat -c
copy`, then runs three independent verifications:
`ffprobe -show_streams`, `ffmpeg -f null -` decode test, and
`ffprobe -count_frames`. Each verification surfaces its failure
fingerprint in the error message.
Smoke test passes 6/6 locally → Path A works; the rest of the stack
takes it.
Also exports `buildEncoderArgs` from `@hyperframes/engine` so
adapters / tests can construct args without re-implementing the
contract.
## Testing
- [x] `bunx vitest run --root packages/engine src/services/chunkEncoder.test.ts` — 62/62 pass (new VP9 closed-GOP tests included)
- [x] `bun test packages/producer/tests/distributed/_smoke/webm-concat-copy.test.ts` — passes
- [x] `bunx oxlint` + `bunx oxfmt --check` on all changed files — clean
- [x] `bunx tsc --noEmit -p packages/engine/tsconfig.json` — clean
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Missed in the initial batch — 86/100 frames were failing. Regenerated
in Docker with the same pinned Chrome build. Now passes with 0 failures.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Sub-comp visibility fix (PR #918) changed rendered output for these two
tests but the baselines on main were stale. Regenerated inside
Dockerfile.test to match CI's Chrome + ffmpeg build.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Regenerated baselines for all regression tests with sub-compositions
in the cancelled shards: style-3-prod, style-5-prod, style-9-prod,
style-15-prod, style-16-prod, style-17-prod, style-18-prod,
sub-composition-video, many-cuts.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Sub-composition visibility fix changes output for compositions
with external sub-compositions. Baseline regenerated in Docker.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The sub-composition inlining now correctly preserves composition IDs
when the host data-composition-id differs from the inner root's
(e.g., host "captions-comp" with inner root "captions"). The captions
layer renders with proper scoping, changing visual output.
Baseline regenerated inside Docker per CLAUDE.md.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The sub-composition visibility fix (2b46565c) correctly holds external
compositions through their authored data-duration. This changes
style-12-prod output from t=8.26s onward: the mondrian-colors
sub-composition now stays visible instead of going black when its GSAP
timeline ends.
Baseline regenerated inside Docker per CLAUDE.md.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The producer source + docs referenced an internal coordination doc
(DISTRIBUTED-RENDERING-PLAN.md) that doesn't ship in the OSS repo,
leaving broken cross-links for adopters. Drops the references and the
bare section-number shorthand that depended on them; behavioural
content (hash contract, retry semantics, threshold rationale) is
preserved inline where it was previously offloaded to a section number.
* fix(engine): preserve video frame replacement geometry
* test(producer): cover video overlay stretch regression
* fix(engine): always pass clip to Page.captureScreenshot
Without an explicit clip, Chrome can resolve replaced-element sizing
differently at dpr=1 when full-bleed absolute videos interact with
overlay layers — producing anisotropic frame stretching on some
compositor paths. Always passing clip with scale=dpr (including 1)
ensures geometry is locked to the measured viewport dimensions.
Credit: brian-t-allen (#837)
* test(producer): regenerate style-9-prod baseline for always-clip capture path
The always-clip change in screenshotService.ts routes Chrome through a
different compositor capture path at dpr=1, producing different video
frame compression artifacts. Regenerated inside Dockerfile.test to match
CI environment.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Address @vanceingalls and @miguel-heygen review findings on #852:
1. Asymmetric soft-skip — only the N=1 plan+render+assemble call was
wrapped in the host-Chrome-failure catch; an SwiftShader / cold-Chrome
flake on the N=4 call would hard-fail instead of soft-skip. Factor a
local runRender() helper and wrap both calls.
2. Vacuously-passing length assertion — 'expect(framesOne.length).toBe(
framesFour.length)' passes when both runs produce 0 frames. Pin the
absolute count (EXPECTED_FRAME_COUNT = 60) so a regression that
identically truncates both renders shows red.
3. CDN version drift — anime-boundary loaded gsap@3.14.2 from jsdelivr
while every other boundary fixture loaded 3.12.2 from cdnjs. Unify on
cdnjs@3.12.2 so the next reader doesn't have to wonder why one fixture
diverges. (gsap is an empty duration-driver in all six fixtures so
the version was never load-bearing — but the divergence reads as
intentional and isn't.)
4. VIDEO_EXT type narrowing — the lookup is Record<"mp4"|"mov"|"webm">
but outputFormat includes "png-sequence". The isPngSequence ternary
short-circuits before png-sequence can reach the indexing site, but TS
can't narrow through that. Add an explicit cast at the indexing site
(not the lookup definition — over-widening to include "png-sequence":
undefined would defeat the existence guarantee).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Address @vanceingalls review on #851:
1. validateMetadata's codec/format check read 'rc.codec !== undefined &&
rc.format !== undefined && rc.format !== "mp4"'. The behavior was
correct (omitted format defaults to mp4 downstream so codec is legal)
but relied on the reader knowing that default. Normalize 'effectiveFormat
= rc.format ?? "mp4"' before the comparison so the intent reads
directly.
2. The mp4-h264-sdr sibling carries inline rationale for the no-audio
choice (AAC frame quantization extends container.duration past
nb_frames/fps and trips the harness PSNR sampler) and the chunk-seam
mapping (crossfade window 0.9-1.1s straddles frame 30). mp4-h265-sdr
stripped both. Carry them back so the two fixtures stay parallel.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Address @vanceingalls review on #848: the mp4-h264-sdr sibling fixture
explains the crossfade-straddles-frame-30 and continuous-rotation
chunk-seam design choices inline; mov-prores didn't. Add the parallel
comment so the next contributor reading either fixture finds the same
context. Notes specifically that ProRes is intra-only and therefore
exercises the QuickTime atom / -c copy contract rather than frame-level
state continuity.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Address @vanceingalls review on #847: the maxFrameFailures=0 byte-identity
threshold will fail when Chromium's CDP screenshot bytes or libpng's
deflate output shifts on a Docker image bump. Pin the recovery procedure
in the fixture's description so a future on-call sees 'regenerate
baselines' rather than spending time investigating a non-regression.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Miguel (approved) and Vai (commented) both flagged the same
PSNR-threshold doc/code mismatch; Vai additionally flagged a
path-anchoring bug in the projectDir-copy filter and a dishonest type
cast. Addressed all five findings:
PSNR threshold doc/code mismatch (important):
- Module docstring, `resolveMinPsnrForMode` JSDoc, and tests/README.md all
claimed distributed-simulated tightens to ≥50 dB. The actual code uses
`max(fixture.minPsnr, 10)` — 10 dB is a pathology floor, the per-test
gate is the fixture's authored `minPsnr`. Updated all three doc sites
to describe what the code does. The 50 dB target in §5.1 is a per-
render distributed-vs-in-process contract; against the frozen baseline
it's unreachable for either mode (shared encoder/JPEG jitter), so it
can't be a per-fixture gate.
`PLAN_PROJECT_DIR_COPY_SKIP` regex matched absolute paths (important):
- `cpSync` calls the filter with the absolute source path, so a
`projectDir` whose absolute path happens to contain a blocklisted
segment (`/home/user/work/output/comp/`, `~/projects/dist/foo/`, etc.)
caused the filter to return false for every descendant — empty
compiled directory, broken render. Now matches relative-to-projectDir
segments via `path.relative()` + `split(sep)`. Switched from a regex
to a Set for clarity. Harness fixtures don't hit this because they
live under `tests/<name>/src/`, but adapters call `plan()` with
caller-supplied paths.
Dishonest type cast in regression-harness.ts (important):
- `as "mp4" | "mov" | "png-sequence"` claimed reachability for formats
that `validateMetadata` doesn't accept (the schema is `"mp4" | "webm"`,
and webm is rejected by `checkDistributedSupport`). Narrowed to
hardcoded `format: "mp4"` with a comment naming the metadata-schema
invariant that lets us do that.
Renamed `chunkVideoInjectorFactory` (nit):
- The variable was invoked once and never used again — "factory" implied
repeated calls. Inlined as a plain `videoInjector: BeforeCaptureHook | null`
ternary.
Replaced tautology test (nit):
- `expect(DISTRIBUTED_SIMULATED_MIN_PSNR_DB).toBe(10)` was a value-pin
over an exported constant. The invariant the JSDoc actually asserts is
"10 dB is below any real fixture's authored minPsnr"; if someone lands
a permissive fixture (minPsnr: 5), the value-pin doesn't catch it.
Replaced with a test that walks `tests/*/meta.json` and asserts every
authored `minPsnr` is ≥ the floor.
Validated in `docker:test --mode=distributed-simulated`:
font-variant-numeric, many-cuts, gsap-letters-render-compat,
style-1-prod, sub-composition-video — all PASSED.
Unit tests: 15/15 pass (new fixture-scan test included).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
PR #755 added the typegpu-adapter regression test scaffolding (meta.json,
src/index.html, output/compiled.html) but left the output.mp4 golden
baseline ungenerated:
> Note: output.mp4 baseline needs to be generated in CI — the local …
Every \`regression-shards (fast)\` run since #755 merged has failed with
\`Snapshot not found: /app/packages/producer/tests/typegpu-adapter/output/output.mp4.
Run with --update to create it.\`
Generated via the canonical Docker path per CLAUDE.md:
bun run --cwd packages/producer docker:test \\
--update --suite typegpu-adapter
Stored via Git LFS (already configured for
\`packages/producer/tests/*/output/output.mp4\` in \`.gitattributes\`).
* feat(core): add TypeGPU/WebGPU runtime adapter
Adds a deterministic seek adapter for compositions that render with
TypeGPU or raw WebGPU. Follows the same push+poll pattern as the
Three.js adapter:
- Sets `window.__hfTypegpuTime` on every seek so render loops can
poll it instead of `performance.now()`.
- Dispatches a `"hf-seek"` CustomEvent on `window` so compositions
can imperatively re-render a single frame at the new seek position.
Compositions listen for the event and update their time uniform:
```js
window.addEventListener("hf-seek", (e) => render(e.detail.time));
```
Works with TypeGPU (docs.swmansion.com/TypeGPU) and raw WebGPU alike.
No assumptions are made about pipeline construction — multiple canvases
or renderers are supported by sharing the same event.
- 9 unit tests, all pass
- wired in init.ts adapter array
- `__hfTypegpuTime` declared in window.d.ts
* fix(core): deduplicate hf-seek dispatch across GPU adapters
Both three and typegpu adapters previously dispatched the same
"hf-seek" CustomEvent independently, causing any composition that
registered a listener to receive two events per seek tick — doubling
per-scrub GPU work even though the renders are idempotent.
Fix: extract a shared `dispatchSeekEvent` helper (seek-dispatch.ts)
that deduplicates by exact float equality within the same synchronous
call stack. Both adapters now call this helper instead of dispatching
directly.
Also adds:
- `resetSeekDispatchState()` export for test isolation
- `beforeEach` reset in three.test.ts and typegpu.test.ts
- New typegpu test: "duplicate seek to same time fires event only once"
- Docstring additions to typegpu.ts: render-mode determinism contract
(await device.queue.onSubmittedWorkDone()) and navigator.gpu feature
detection guidance for composition authors
* feat(core): video-texture render compat + TypeGPU skill
Adds the missing pieces for video-backed WebGPU effects in render mode:
- `video-texture-compat.ts`: monkey-patches `GPUQueue.copyExternalImageToTexture`
to detect the engine's injected `<img class="__render_frame__">` siblings and
transparently substitute them for `<video>` sources. Headless Chrome can't
supply decoded video frames to WebGPU, but the engine's pre-extracted frame
images work. Falls through to the original path in preview mode.
- `patchVideoTextureCompat()` wired in init.ts after adapter array creation.
- `skills/typegpu/SKILL.md`: full authoring guide for TypeGPU/WebGPU compositions
covering contract, timeline registration, video-backed effects, frosted blur
via downsample pass, WGSL patterns, and deterministic rendering.
* test(producer): add typegpu-adapter regression test
Self-contained WebGPU composition with:
- Procedural gradient background (no video dependency)
- Animated ring driven by hf-seek time uniform
- Pulsing center glow
- Two GSAP-driven captions testing adapter sync
Verifies the TypeGPU adapter's hf-seek → WebGPU render pipeline
produces deterministic frames. workers: 1 for consistency.
Note: output.mp4 baseline needs to be generated in CI — the local
Docker image can't launch Chrome (ARM/x86 mismatch on Mac).
Miguel Ángel