* perf(engine): superset extraction for overlapping trims of one source
Cache-missing trims of the same source that are frame-aligned and
overlapping decode their union window in ONE ffmpeg pass; each trim's
frames are materialized by hardlinking the superset frames with
renumbered names (copy fallback on EXDEV). Byte-identical to per-trim
extraction on CFR sources (verified by content hash in the A/B run),
~2x less decode+encode work for typical overlapping trims, and
sparse-keyframe sources pay the keyframe seek once instead of once per
trim. Disjoint or misaligned trims keep the direct path; any union
failure falls back to per-trim extraction.
Also: warm renders (zero cache misses) skip the extraction-cache GC
sweep instead of paying a full cache size scan.
* fix(engine): superset review hardening - clustering, abort, cache-fs temp, gc staleness
- Partition each source's trims into overlap-connected components before
the union check, so one disjoint outlier no longer collapses the whole
bucket to direct extraction (pinned by a 3-of-4-overlap test).
- On abort, the superset fallback no longer re-runs every member through
direct extraction (N doomed ffmpeg spawns); the cancellation surfaces
per member instead.
- The superset temp dir moves onto the cache filesystem when the cache
is active so member hardlinks into partial dirs cannot EXDEV-copy and
silently multiply disk usage; its .partial- name puts crashed
leftovers under the GC's aged-partial sweep.
- GC staleness fallback: a .hf-last-gc marker is stamped per sweep and
all-hit renders sweep anyway once it is older than 24h, so 100%-warm
workloads still reclaim space (pinned by a stale-marker test).
* perf(engine): one-pass SDR-to-HDR extraction with cache-key transform
Mixed-HDR compositions converted each SDR source with a full libx264
re-encode (convertSdrToHdr) before extraction. The BT.709 to BT.2020
colorspace remap now runs as a filter inside the extraction pass
itself; convertSdrToHdr and the _hdr_normalized intermediate are
deleted. Same shape as the earlier one-pass VFR change.
Also fixes a cache-poisoning bug this exposed: the HDR preflight
rewrote entry.videoPath AFTER the cache-key snapshot, so a mixed-HDR
render cached converted frames under the plain source key and a later
SDR render of the same trim would have served HDR-tinted frames. The
cache key now carries an optional transform discriminator; keys
without a transform stay byte-compatible with existing entries.
* fix(engine): attribute SDR-to-HDR extract failures, pin filter-order intent
Review hardening for one-pass SDR-to-HDR:
- ffmpeg failures now carry an 'SDR→HDR conversion failed (colorspace
filter in extract pass)' prefix when the remap is in the chain, so a
filter-less ffmpeg build fails loudly with attribution instead of a
generic extract error.
- Comments pin the fps-before-colorspace ordering intent and mark
sdrToHdrTransfers as the canonical read for both the cache key and
extraction options.
- Cross-render cache-poisoning regression test now compares frame
BYTES across the cache boundary: mixed-HDR render then plain-SDR
render of the same trim must produce different pixels, and a repeat
plain render must hit the plain entry with byte-identical frames.
## What
Foundations of the `@hyperframes/core/figma` module — the pure, transport-agnostic layer every later phase builds on:
- **`types.ts`** — `FigmaRef`, `FigmaProvenance`, `FigmaManifestRecord`, and the Motion model (`MotionDoc`/`MotionTrack`/`TimelineSpec`/`GsapTween`) shared across the stack.
- **`parseFigmaRef`** — normalizes any user input (full `/design|/file|/proto` URLs with `?node-id=1-2`, `fileKey:nodeId` shorthand, bare `fileKey`) into `{ fileKey, nodeId }`, including the URL-dash → API-colon node-id conversion.
- **`freeze.ts`** — `freezeBytes`/`freezeUrl`/`freezeLocalFile` with a 256 MB cap; every Figma asset is frozen to a local file before it can reach a composition (determinism: no render-time network).
- **`manifest.ts`** — the `.media/manifest.jsonl` ledger (same layout `media-use` writes, so a project has one shared media inventory without either skill depending on the other): append/read/find-by-node/next-id, with a pure type-guard (`isFigmaManifestRecord`) instead of `as`-casts.
- **`assetSnippet.ts`** — manifest record → composition `<img>` snippet with escaped attrs + `data-figma-id`.
- **publishConfig fix** — `./figma` added to `packages/core` `publishConfig.exports` (the packed-manifest CI gate requires every source export to have a dist mapping).
## Why
Design spec: `docs/superpowers/specs/2026-06-30-figma-asset-integration-design.md`. These functions are deliberately transport-agnostic — when the project reversed from MCP-first to a REST/MCP split (spec §2), nothing in this layer changed. That was the point.
## Tests
Unit tests per module (URL variants, freeze cap edges, manifest round-trip/malformed-line tolerance, snippet escaping). All colocated `*.test.ts`, vitest, no network.
---
Stack (1/6): this PR → #1869 → #1870 → #1871 → #1872 → #1873🤖 Generated with [Claude Code](https://claude.com/claude-code)
* perf(engine): extraction cache on by default with atomic publish and LRU gc
Warm re-renders now skip source-video frame extraction entirely
(video_extract 400ms -> 13ms on a 4-video composition; outputs are
pixel-identical, PSNR inf). What made default-on safe:
- Atomic entry publish: frames extract into a unique .partial-<pid>-<uuid>
dir, the completion sentinel is written there, and the dir is renamed
into the final key atomically. Concurrent renders sharing a cache can
duplicate work but can never serve a torn entry (previously documented
as single-writer only).
- Size-capped LRU gc: best-effort sweep after extraction evicts
oldest-used entries past a 2 GiB default budget
(HYPERFRAMES_EXTRACT_CACHE_MAX_MB) and clears crashed writers'
partials. Entries younger than 60 min are never evicted so live
renders keep their frames.
- Default cache dir: <tmpdir>/hyperframes-extract-cache-<uid>. Opt out
with HYPERFRAMES_EXTRACT_CACHE_DIR=off (or none/false/0); a
non-writable dir degrades to uncached with a single warning instead
of failing the render.
* fix(engine): harden extraction cache publish and surface cache ops signals
Review hardening for the default-on extraction cache:
- Bypass the cache for HDR-converted intermediates: the key snapshot
describes the original source, so publishing converted frames under
it would poison later plain-SDR renders of the same trim. (The
follow-up transform-keyed change re-enables caching for these.)
- publishCacheEntry TOCTOU: adopt a concurrent writer's completed
entry both before removing an apparently-stale dir and after a
failed retry rename, so a winner's publish is never destroyed or
reported as a failure.
- Observability for the failure paths: cachePublishFailures,
cacheGcEvictions, cacheGcBytesFreed, and cacheAgedPartialsCleared on
ExtractionPhaseBreakdown; gcExtractionCache now returns sweep stats.
* fix(engine): sweep superseded cache generations in gc
After a SCHEMA_PREFIX bump, old-generation entries (hfcache-v2-*)
no longer matched the sweep's prefix filter and would orphan their
disk forever. The gc now matches any hfcache-v* generation; superseded
entries never receive sentinel touches, so the LRU evicts them first.
* perf(engine): write PNG frames at compression_level 1
Extracted video frames are render-scoped temp files read once during
capture, so zlib effort above level 1 buys nothing. Measured 3.3x
faster on 60s of 1080p H.264 to PNG (11.4s to 3.5s) and 5.4x on a 20s
vp9-alpha webm (4.3s to 0.79s), for ~14% larger temp files.
* perf(engine): one-pass VFR extraction with -fps_mode cfr
VFR sources (screen recordings, phone videos) were re-encoded to CFR
with libx264 and then extracted in a second ffmpeg pass. Extraction now
runs a single pass with -fps_mode cfr -r <fps>. Same frame counts on
the VFR regression fixtures (120/120 mid-seek, 297-303 full file), one
less x264 generation of quality loss, ~3.4x faster on VFR inputs.
convertVfrToCfr and the _vfr_normalized intermediate are deleted.
The full-VFR test's byte-identical duplicate-frame cap is retired with
cause: the fixture has no source frames for 40% of its timeline, so
held frames are correct; the two-pass path only scored under it because
x264 encoder noise made frozen frames hash differently. The freeze
regression (missing frames) stays pinned by the frame-count windows.
* docs(engine): pin vfrPreflightMs definition change after one-pass VFR
vfrPreflightMs used to time a per-source VFR-to-CFR re-encode; it now
times only the cached classification probe and collapses to ~0. Call
that out on ExtractionPhaseBreakdown so dashboards keyed on the old
threshold semantics migrate to vfrPreflightCount / extractMs.
* fix(engine): bump extraction cache schema to v3 for one-pass VFR frames
One-pass VFR extraction changes frame CONTENTS for VFR sources while
the cache key tuple (path, mtime, size, trim, fps, format) is
unchanged, so warm v2 entries holding two-pass frames would keep being
served across the deploy boundary. Bumping the schema prefix makes v2
entries inert; affected sources re-extract once.
* perf(engine): dedupe identical extractions within one render
N <video> elements sharing (resolved path, mediaStart, duration, fps,
format) extracted N times; they now share one extraction via an
in-flight promise map keyed on that tuple. Duplicate elements receive
the shared frame set under their own videoId. This also removes a race
where two identical clips on a cache miss wrote the same
extraction-cache entry dir concurrently. 3x duplicated 60s 1080p video:
4426ms to 1521ms in the A/B benchmark, one frame set on disk.
* fix(engine): attribute shared-extraction failures to the dedupe leader
When a deduped extraction fails, every follower reported the leader's
error verbatim under its own videoId, reading as N independent
failures in traces. Follower errors now carry a
'[shared extraction, leader <id>]' prefix so the fan-out is traceable
to one root failure.
* perf(engine): write PNG frames at compression_level 1
Extracted video frames are render-scoped temp files read once during
capture, so zlib effort above level 1 buys nothing. Measured 3.3x
faster on 60s of 1080p H.264 to PNG (11.4s to 3.5s) and 5.4x on a 20s
vp9-alpha webm (4.3s to 0.79s), for ~14% larger temp files.
* perf(engine): one-pass VFR extraction with -fps_mode cfr
VFR sources (screen recordings, phone videos) were re-encoded to CFR
with libx264 and then extracted in a second ffmpeg pass. Extraction now
runs a single pass with -fps_mode cfr -r <fps>. Same frame counts on
the VFR regression fixtures (120/120 mid-seek, 297-303 full file), one
less x264 generation of quality loss, ~3.4x faster on VFR inputs.
convertVfrToCfr and the _vfr_normalized intermediate are deleted.
The full-VFR test's byte-identical duplicate-frame cap is retired with
cause: the fixture has no source frames for 40% of its timeline, so
held frames are correct; the two-pass path only scored under it because
x264 encoder noise made frozen frames hash differently. The freeze
regression (missing frames) stays pinned by the frame-count windows.
* docs(engine): pin vfrPreflightMs definition change after one-pass VFR
vfrPreflightMs used to time a per-source VFR-to-CFR re-encode; it now
times only the cached classification probe and collapses to ~0. Call
that out on ExtractionPhaseBreakdown so dashboards keyed on the old
threshold semantics migrate to vfrPreflightCount / extractMs.
* fix(engine): bump extraction cache schema to v3 for one-pass VFR frames
One-pass VFR extraction changes frame CONTENTS for VFR sources while
the cache key tuple (path, mtime, size, trim, fps, format) is
unchanged, so warm v2 entries holding two-pass frames would keep being
served across the deploy boundary. Bumping the schema prefix makes v2
entries inert; affected sources re-extract once.
Extracted video frames are render-scoped temp files read once during
capture, so zlib effort above level 1 buys nothing. Measured 3.3x
faster on 60s of 1080p H.264 to PNG (11.4s to 3.5s) and 5.4x on a 20s
vp9-alpha webm (4.3s to 0.79s), for ~14% larger temp files.
* fix(engine): scale static-dedup verification density with run length
Reported symptom: a 10-scene template composition (shared card layout,
per-scene text/progress-bar content) rendered scene 1 correctly, but
every scene after that had its text/progress-bar card missing from
the final MP4 -- even though snapshot and validate showed correct
per-scene content when seeking directly to those timestamps. Setting
HF_STATIC_DEDUP=false fixed every scene. Render log showed a large,
mostly-reusable static-frame run engaging (2430 frames, 34% reusable).
verifyStaticFramesSafe already does a real, pixel-exact comparison
(anchor vs. candidate screenshot) before trusting a predicted-static
run -- the reuse mechanism itself is correct and already regression-
locked (frameCapture-staticDedupIndex.test.ts). The gap was sample
density: interior checks per run were capped at a flat
min(sampleCount, 8) points, so the stride between checks grew with
the run's span. A 2000+ frame run (plausible for a 10-scene comp
where computeStaticFrameSet's GSAP-tween-only interval walk can't see
whatever mechanism swaps each scene's text) could space checks ~285
frames apart, letting a real content change hide between two verified
points and get the whole run wrongly trusted as static.
Fix: extract the point-selection into a pure, exported
computeStaticVerificationPoints(a, b, sampleCount), and bound the
STRIDE by sampleCount (HF_STATIC_DEDUP_SAMPLES) instead of just the
point count, so density scales with run length. Short/typical runs
are unaffected (the two formulas agree there); long runs get
proportionally denser checks. The existing hardCap safety valve is
untouched -- if this makes verification too expensive for a
pathological composition, dedup still disarms entirely rather than
trusting a sparsely-checked set.
Test: new frameCapture-staticDedupVerifyDensity.test.ts asserts the
max gap between consecutive verification points never exceeds
sampleCount on long runs (would fail pre-fix at span=2000/10000),
matches the prior stride on short runs, and always includes both
run endpoints. Full engine suite (845 tests) passes.
* fix(engine): decouple verification density scaling from sampleCount polarity
Addresses review feedback on the static-dedup density fix (PR #1903):
1. The prior revision bounded the interior-check STRIDE by sampleCount
directly, which inverted HF_STATIC_DEDUP_SAMPLES' polarity: raising
it widened the allowed gap between checks instead of narrowing it,
and the "raise HF_STATIC_DEDUP_SAMPLES to verify more" log guidance
became backwards for exactly the long runs it's meant to help.
Fix: introduce a fixed STATIC_VERIFY_REFERENCE_STRIDE (24 frames,
independent of sampleCount) that drives the length-scaling behavior
-- this alone fixes the original bug (long runs going nearly
unverified) regardless of how sampleCount is configured. sampleCount
is now purely a per-run point-count FLOOR: raising it only ever
increases density, restoring correct, monotonic polarity.
2. hardCap wasn't re-tuned for the new cost model. The old flat 8-point
cap cost ~8 checks/run; the new density costs ~span/24 checks/run --
~103 for the reported 2430-frame run, ~417 for a 10k-frame run.
Sizing the budget only off sampleCount (which no longer drives
density for long runs) would make a genuinely-static long
composition spuriously disarm under the new, more thorough checking.
hardCap now also scales with the total predicted-static frame count,
with a 3x margin over the expected minimum verification cost.
Softened the budget-exhausted log message accordingly -- it no
longer prescribes raising sampleCount, which would often just add
cost without proportionally raising the now length-driven budget.
3. The 5 existing tests only asserted sample-point geometry (gaps,
endpoints, stride shape), not the actual point of the fix -- that a
real content change hiding between the OLD sample gaps now gets
caught. Added a behavior-level test: mocks pageScreenshotCapture to
simulate a transient content change at a frame the pre-fix formula
would have skipped (reconstructed locally in the test, commented as
historical-only) but the new formula samples, and asserts the real
verifyStaticFramesSafe (now exported) detects it via the real
computeStaticVerificationPoints -- not a reimplementation. Also
added a direct polarity regression test (raising sampleCount past
the length-scaled floor must strictly tighten the gap) and reworded
the short-run test to reflect the corrected formula.
Full engine suite (847 tests) passes.
Fixes#1847
The producer's render path stripped a sub-composition's authored root element and inlined only its children, so any CSS anchored on that root (its id or classes) matched nothing in the compiled HTML even though it resolved fine in Studio preview.
Changes:
- Wire flattenInnerRoot into the producer's sub-composition inliner (packages/producer/src/services/htmlCompiler.ts) so its render-time DOM shape matches the preview bundler's.
- Rewrite a bare root [data-composition-id="X"] box selector to a :has()/:not() pair that lands on exactly one of the host or the flattened wrapper (packages/core/src/compiler/compositionScoping.ts), avoiding double-applying additive properties like padding.
- Restore the composition's own id onto the flattened wrapper when the host has no id of its own, an "anonymous" host (packages/core/src/compiler/inlineSubCompositions.ts).
- Fix the runtime's startResolver to find a composition's start time through the post-inlining data-composition-file marker, not just data-composition-src or data-composition-id (packages/core/src/runtime/startResolver.ts).
Also adds regression coverage for the literal issue #1847 repro (a class, not just an id, on the authored root, styled via a descendant selector), a test proving the runtime compositionLoader's anonymous-host path doesn't share this bug, and fixes stale test documentation and a misattributed code comment surfaced during review.
Verified: 29-fixture Docker regression sweep on linux/amd64 (matching CI) run 3x clean, 967/967 core unit tests, full CI green.
The design-style extractor now captures a site's signature color grounds
and materials that a flat background-color misses:
- Capture gradient background-image + backdrop-filter on buttons/cards/nav.
- backgrounds[]: dominant gradient / mesh washes ranked by on-screen area
(includes ::before/::after glow orbs), chroma-weighted so a small vivid
brand wash outranks a large neutral scrim.
- glass[]: frosted-glass panels (backdrop-filter blur) with their raw
translucent fill, border, radius, shadow — ranked by area.
- nav CTA capture: keep filled buttons inside <nav> (a page's primary
"Sign up" / "Start for free" CTA that the old nav-drop lost), including
gradient-filled CTAs whose background-COLOR is transparent.
- Dedup keys for buttons/cards now include gradient + glass so a
gradient/frosted variant is not collapsed into its flat sibling.
- Fix: a fully-transparent fill rgba(...,0) now reports "transparent"
instead of #000000 — the old bug turned every transparent wrapper into a
phantom black button/card.
types: ComponentStyle gains backgroundImage/backdropFilter; DesignStyles
gains backgrounds[] and glass[].
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* fix(hyperframes-media): npx spawn without shell:true fails silently on Windows
Two independent user reports of Kokoro TTS silently failing on Windows,
both naming the same site: lib/tts.mjs synthesizeOne() spawns "npx" via
plain spawn(cmd, args). On Windows npx resolves to npx.cmd, which Node's
spawn() cannot exec without shell:true — it fails ENOENT, and spawnP's
"error" listener turns that into a plain ok:false ("TTS failed") with no
indication of the real cause.
Scope the fix to the npx call specifically (python3/ffmpeg are real
binaries and don't need it), with the platform/spawn function injectable
so the win32 branch is testable without mocking node:child_process (its
ESM exports are non-configurable, so mock.method can't patch it) or the
real process.platform.
* fix(hyperframes-media): avoid shell true for windows npx
* fix(hyperframes-media): fall back to ffmpeg when ffprobe is missing
ffprobeDuration() returned NaN whenever the ffprobe spawn failed for any
reason, conflating "ffprobe binary not installed" with "file is corrupt".
Some ffmpeg-only distributions (common in curated Windows installs) ship
ffmpeg.exe without ffprobe.exe, so every TTS line hit the missing-binary
case and audio.mjs read the NaN as a bad WAV, silently dropping an already
successfully synthesized line. Now falls back to parsing ffmpeg's own
`Duration:` stderr banner when ffprobe specifically ENOENTs, and only
returns NaN when the file itself can't be probed by either tool.
* fix(hyperframes-media): update skills manifest for ffprobe fallback
Two independent post-release feedback reports of the same mechanism from
two different skills (both delegate to this one shared engine): audio.mjs
fired every line's Kokoro TTS + whisper-transcribe subprocess concurrently
via a bare Promise.all with no cap.
- One OOM'd 12/13 lines on a resource-constrained laptop (32GB total, ~7GB
free), requiring a manual patch to a sequential for-loop.
- The other saw 7/8 lines fail on first run, then pass on retry once the
model was cached — concurrent cold-start model loads overwhelming the
machine, not a real synthesis failure.
Kokoro/Whisper each load their own local model per subprocess, so firing
every line at once multiplies that cost by the line count. Extracted the
concurrency cap into lib/concurrency.mjs (audio.mjs is a script — it runs
CLI/exit side effects on import, so it can't be unit-tested directly;
the cap is small enough to pull out and test in isolation). Default 4,
overridable via HYPERFRAMES_TTS_CONCURRENCY, floored at 1 (matching one
report's own manual workaround).
hyperframes-media/scripts/audio.mjs is the single canonical engine per its
own header comment; product-launch-video, faceless-explainer, and
pr-to-video each carry a thin wrapper that spawns this file as a
subprocess (confirmed via their DEFAULT_ENGINE path), so this one fix
covers all four skills without touching the other three.
Tests: 4 new cases for mapWithConcurrency (order preserved regardless of
completion order, cap actually enforced, limit > item count doesn't hang,
empty input). Full skills test suite (514 tests) shows no new failures —
the 444 pre-existing failures are environment-dependent and reproduce
identically on unmodified main.
At least 4 independent post-release feedback reports of a render completing
successfully (exit 0) with audio elements correctly authored and detected at
compile time (audioCount > 0), but the final MP4 having no audio track —
discovered only via ffprobe or manual playback, with the CLI giving no
indication anything went wrong. Users worked around it by muxing the
generated audio in manually with ffmpeg.
Root cause: runAudioStage sets hasAudio from processCompositionAudio's
success flag, but discarded its error field — the actual reason a per-element
audio prep step or the final mix failed (source not found, extract failed,
ffmpeg error) was computed and then thrown away. A real audio-mix failure was
therefore indistinguishable from "no audio was authored": both just produced
hasAudio: false with zero diagnostic output.
Thread the mixer's error through as audioError (only set when audios.length
> 0 but the mix failed) and log.warn it from both call sites (the main
render path in renderOrchestrator.ts and the distributed plan() path) so a
real failure is loud instead of silently downgrading to a video-only render.
Tests: 4 new cases for runAudioStage (mixer error surfaced, generic fallback
message when the mixer doesn't provide one, no audioError on success, no
audioError when there's no audio to mix). renderOrchestrator.test.ts (68
tests) unaffected. plan.test.ts's one failure (an audio-bearing planHash
determinism test timing out at 30s) is pre-existing — reproduces identically
on unmodified main with these changes stashed.
* fix(cli): lock chrome-headless-shell install against concurrent extraction races
A detailed post-release feedback report of `render` producing a fully
black 15s MP4 despite lint/validate/inspect/snapshot all passing and
Studio preview playing correctly. Root cause traced by the reporter:
chrome-headless-shell had been manually re-extracted after `browser
ensure`'s own download got stuck mid-extraction when two concurrent
invocations raced on the same cache dir. The manual extraction lost a
macOS Gatekeeper/quarantine or GPU/Metal entitlement bit that a clean
install sets, so headless GPU frame capture silently returned all-black
frames — invisible to every existing health check, since they only
confirm the binary *exists*, not that it captures real pixels.
`--no-browser-gpu` fixed it completely, confirming the GPU-capture path
specifically. A related, vaguer report of the same race the prior loop
run ("'browser ensure' hung mid-extraction after a race from two
concurrent invocations") was deferred pending a clearer repro; this
report supplied one.
@puppeteer/browsers' install() has no concurrency guard of its own —
confirmed by reading its source: two concurrent installs for the same
browser/buildId both proceed straight to download+unpack with no
existing-install check, no lock. Two ensureBrowser()/findBrowser() calls
that both miss the cache at the same time (the common case on a fresh
machine, or right after `browser clear`) race on the same extract target.
Fix: mkdirSync as an atomic cross-process mutex around the download —
recursive:false makes it throw EEXIST when another process already holds
it (that's load-bearing: recursive:true would silently no-op instead).
Zero new dependencies. A concurrent caller polls until the lock releases,
then re-checks the cache before deciding whether to download at all — the
common case (loser waits, then reuses the winner's completed install)
never re-downloads. A lock held past a generous timeout is reclaimed
rather than left to wedge every future render if the holder crashed
mid-extraction. Applied to both call sites that reach the racy
downloadBrowser() (ensureBrowser's two paths, and findBrowser's stale-
cache re-download — the file already carries a code-duplication
suppression between these two near-identical functions).
Not doing (out of scope for this fix): the reporter's second suggestion,
a deeper `doctor` check that actually captures a test frame rather than
checking binary existence. That's a real gap but a separate, larger
feature — this fix prevents the corruption that caused it, which matters
more than detecting it after the fact.
Tests: two new cases (lock releases after a successful download; a lock
held past its timeout is reclaimed rather than hanging — exercised via
withInstallLock's injectable timeoutMs/pollMs with tiny real waits,
avoiding fake-timer mocking through the full async ensureBrowser call
graph). All 13 tests in manager.test.ts, 22 across packages/cli/src/browser,
and the full CLI suite (1115 tests) pass.
* test(cli): isolate browser install lock test from system chrome
* fix(cli): guard stale browser lock reclaim
Two independent post-release feedback reports of validate warning about
audio duration despite an explicit, correct data-duration slot, one of
them naming a timeout explicitly.
Root cause: auditClipDurations reads each <video>/<audio> element's
intrinsic .duration via a single page.evaluate() snapshot taken after a
flat, unconditional page-settle sleep (opts.timeout ?? 3000ms, shared with
other audits). Per the HTML spec, HTMLMediaElement.duration is NaN until
metadata loads. A slow-loading audio file (large narration WAV, remote
source) can still be mid-fetch when that sleep elapses — el.duration is
NaN at that exact instant, which the audit permanently records as
"could not read the duration" even though the render pipeline (which
properly awaits media readiness) handles the same file fine.
Fix: race each not-yet-ready element's loadedmetadata/error event against
a deadline instead of taking one fixed-time snapshot. Elements already
ready resolve immediately (no added latency in the common case); only
genuinely slow elements get a real second chance before the warning fires.
The race/cleanup wiring lives twice by necessity — once inline inside the
page.evaluate() closure (Puppeteer serializes and re-runs that closure in
an isolated browser realm with no access to this module), and once as the
exported, duck-typed raceMediaReady for a real, deterministic unit test
via Node's built-in EventTarget (no browser or DOM library needed). The
comment on raceMediaReady flags that both copies must move together.
Two independent post-release feedback reports of hitting
ffmpegEncodeTimeout (600000ms default) on long or high-frame-count
renders, both resolved by setting FFMPEG_ENCODE_TIMEOUT_MS to a higher
value and/or PRODUCER_ENABLE_CHUNKED_ENCODE=true — env vars that already
exist and already solve this, but that neither user found from the error
message itself.
appendEncodeTimeoutMessage only stated what happened ("FFmpeg killed after
exceeding ffmpegEncodeTimeout"), not what to do about it. Name both
existing knobs in the message so the fix is immediately visible at the
point of failure instead of requiring a source dive.
One function, six call sites, all fixed at once. Existing tests assert
with toContain, so the appended text doesn't break them; added two
assertions confirming both env var names appear in the message.
Two independent post-release feedback reports of the same contradiction:
scene_layer_missing_visibility_kill / gsap_exit_missing_hard_kill tell you to
add `tl.set(selector, { visibility: "hidden" }, t)` on an exiting scene
element, but when that element is also class="clip", the exact tl.set they
recommend is then flagged by gsap_animates_clip_element (the framework
already owns visibility/display on clip elements). One report worked around
it by wrapping the scene's content in an inner non-clip div and asked that
the fix hint mention that pattern.
Both rules now detect when the exiting/flagged selector is a clip element
(scene_layer_missing_visibility_kill checks the tag's class list directly;
gsap_exit_missing_hard_kill reuses the clipIds/clipClasses maps already built
in its enclosing rule) and, only in that case, point at the inner-wrapper
pattern instead of a tl.set on the clip element itself. Non-clip targets are
unaffected — same fix hint as before.
Two independent post-release feedback reports of the same mechanism: a
leading <svg> block (icon/gradient/filter <defs>, referenced by url(#id)
elsewhere in the document) placed before the real [data-composition-id]
root manufactures root_missing_composition_id + root_missing_dimensions
on an otherwise-correct composition. Moving the <svg> after the root
cleared both findings for each reporter.
findRootTag returned the first body child that wasn't script/style/meta/
link/title, unconditionally — <svg> was never in that skip list, so a
leading defs-only <svg> got treated as the root.
Fix: skip a leading <svg> when it carries none of the composition markers
itself (data-composition-id/data-width/data-height), so an intentionally
SVG-rooted composition is still eligible as the root. The first attempt at
this only skipped the <svg> open tag, which surfaced a second bug:
extractOpenTags is a flat, nesting-unaware scan, so the very next tag it
returns after skipping <svg> is the svg's own nested child (<defs>,
<filter>, ...), not the sibling after </svg>. Track the svg's closing tag
position and skip every tag before it, not just the <svg> tag itself.
Tests: skips a leading svg defs block (no false root findings); still
treats an <svg> as the root when data-composition-id/data-width/
data-height are declared directly on it. Full lint suite (308 tests) passes.
WINDOW_TIMELINE_ASSIGN_PATTERN only matched window.__timelines["literal"]
or window.__timelines.prop, so registrations via a computed key like
window.__timelines[spec.id] (used by the code-particle-assemble and
code-3d-extrude registry blocks) went undetected. That made
gsap_timeline_not_registered false-fire on correctly registered timelines,
and let root_composition_missing_duration_source wrongly demand an
explicit data-duration on compositions that already have one.
Two independent post-release feedback reports of this rule hard-erroring
on OS system fonts (Hiragino Sans, Microsoft YaHei) that have no
downloadable file. Both asked for the same thing, in slightly different
words: a documented way to satisfy the check for a font that's genuinely
OS-bundled, not missing.
That way already exists and already works — extractFontFaceFamilies only
looks at the font-family declaration inside @font-face, never the src
value, so `@font-face { font-family: 'X'; src: local('X'); }` already
passes. One report found this themselves; the other didn't. The gap was
discoverability: the fixHint only described bundling a real font file, so
nobody would think to try `local()` unless they already knew about it.
Considered and rejected a broader fix: adding CJK system-font names to the
shared FONT_ALIAS_MAP (the mechanism that already exempts Latin system
fonts like Segoe UI/Verdana by aliasing them to a bundled fallback font).
That map has no CJK-equivalent bundled font to alias to (only Japanese has
one, noto-sans-jp) — aliasing "Microsoft YaHei" (Simplified Chinese) to a
Japanese font would silently swap in the wrong glyph shapes for shared Han
characters, and would specifically break distributed/Lambda rendering
(where system-font capture is disabled, per system_font_will_alias's own
comment) by removing the warning that currently prompts a real fix. The
local() message fix has none of that risk: it changes no detection logic,
only points at an already-correct existing escape hatch.
Tests: local() font-face no longer flags (proves the advice is accurate,
not just documented); fixHint contains "local(". 308 lint tests pass.
* chore(cli): regenerate cloud client for createAssetUpload + completeAssetUpload
Regenerated from experiment-framework `master` at commit `e74815f7af` (the
merge of EF#41085, which added `/v3/assets/direct-uploads` +
`/v3/assets/{asset_id}/complete` to the `TARGET_ENDPOINTS` allowlist in
`scripts/generate_hyperframes_cli_client.py`).
The `sync-hyperframes-codegen.yml` workflow that normally auto-opens this
PR failed with a `gh: Not Found (HTTP 404)` on the PR-creation step (run
28556975483); regenerated manually with:
cd experiment-framework
PYTHONPATH=. python3 scripts/generate_hyperframes_cli_client.py \\
--out /path/to/hyperframes-oss
This commit is codegen-only — no hand edits. The direct-upload wire-up
that consumes the new `createAssetUpload` + `completeAssetUpload` methods
lands in the follow-up commit.
— Jerrai
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* feat(cli): migrate cloud-render upload to /v3/assets/direct-uploads (200MB)
Replaces the legacy `client.uploadAsset(...)` multipart POST to
`/v3/assets` (32 MB in-memory proxy path) with the three-step direct-to-
S3 flow that lifts the practical per-project ceiling to 200 MB:
1. `POST /v3/assets/direct-uploads` — declares filename, content-type,
size, and SHA256 checksum; returns `asset_id`, presigned
`upload_url`, and required `upload_headers`.
2. Raw `PUT` to `upload_url` with the zip bytes + `upload_headers`
verbatim. No CLI auth attached — the presigned URL signature carries
authorization, and any extra headers would break the signature.
3. `POST /v3/assets/{asset_id}/complete` — finalizes into a reusable
asset. Retried up to 5x on 409 ("Uploaded object not found yet"), a
documented race between S3 write consistency and the finalize check.
The returned `asset_id` is the same namespace the legacy path produced
(both write into `movio_asset`), so the downstream render submission at
`createRender({project: {type: "asset_id", asset_id}})` is unchanged.
Server-side context (EF#41085): the direct-upload endpoint now accepts
`application/zip` via a scoped `_ZIP_MIME_TO_EXT` map — the shared media/
PDF allowlist stays zip-free. The exact-MIME cross-check at the sniff
step guards against zip<->PDF confusion under the shared 'document'
category. Canonical S3 key layout matches the legacy proxy path
(`document/{asset_id}/original.zip`), so the render-side head_object
gate is transparent to which upload path produced the asset.
The prior codegen commit added the generated createAssetUpload +
completeAssetUpload methods this commit consumes.
— Jerrai
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Fix slideshow presenter mode for screen-share workflows by opening the audience view as a regular noopener tab, preserving audience query construction across fragments, and keeping iframe keyboard forwarding diagnosable.
* ci: sync changed skills to ClawHub on push to main
Add a GitHub Actions workflow that runs `clawhub sync` whenever skills/**
changes on main, publishing only changed skills to ClawHub
(https://clawhub.ai/heygen-com) under the heygen-com publisher and
auto-bumping the patch version. Unchanged skills are a no-op, so it is
safe to run on every push. Requires the CLAWHUB_TOKEN repo secret.
* ci: use Node 22 to match the CI fleet's LTS
Address review on #1835 (Miga): the rest of the CI fleet (ci.yml,
windows-render, player-perf, preview-regression, docs, catalog-previews)
pins setup-node to Node 22 LTS. Node 24 is current, not LTS, and could
introduce subtle differences. Align this workflow to 22.
The P1-3 aspect/alpha/HDR pre-flight (#1843) aborts an incompatible render before any browser/ffmpeg work, but that "save" was invisible on dashboard 1783183 — indistinguishable from a deep failure or a user giving up.
checkRenderResolutionPreflight now returns { message, kind } (kind = the existing low-cardinality OutputResolutionIssueKind), and the render command emits render_preflight_rejected { kind } before exiting. No parsers change — the helper already carried kind. trackRenderPreflightRejected is typed to the union so the metric can't carry free text.
Tests: preflight tests assert kind for all five kinds; an events test locks the emit.
Further follow-up (still log-only): encoder-frame-0-exit counter and a P1-4 doctor cli_env_check event.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The CLI Test job (bun run --filter '!@hyperframes/producer' test) intermittently failed unrelated PRs (#1843, #1850) with `Test timed out in 5000ms` / `Hook timed out in 10000ms`. Root cause: multiple CLI tests cold-import a heavy command module graph via dynamic import() (render.js, auth/status.js, telemetry/system.js), which under the full parallel monorepo run contends for CPU and blows vitest's 5s/10s defaults on constrained runners. Not a product bug.
Fix at the right altitude: set testTimeout 20s + hookTimeout 30s once in packages/cli/vitest.config.ts instead of per-test/per-hook bandaids, and remove the now-redundant explicit 30s beforeAll timeouts added in #1843.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
commitWholePropertyOffset reduced the tween's keyframe list to find the
"nearest" stop without an initial value. When a to()/from() tween had been
collapsed to a zero-duration immediateRender hold (what removeAllKeyframes
leaves behind), synthesizeFlatTweenKeyframes correctly treats it as a
static hold and returns null, leaving an empty keyframe list — so the
reduce threw "Reduce of empty array with no initial value". Reachable by
resizing such an element with auto-keyframe recording off.
With no keyframe shape to preserve, persist the flat value directly via an
update-properties mutation instead.
Dragging a motion-path keyframe node committed correctly, but the soft
reload that refreshes the preview re-seeked the freshly rebuilt GSAP
timeline using the iframe's raw __player.getTime(), which can lag the
studio's authoritative currentTime right after a keyframe drag parks the
playhead. The stale seek left the element (and its selection/motion-path
overlay) rendered at an unrelated position after the edit.
applySoftReload now takes the caller's currentTime instead of trusting the
iframe's own clock, and the re-seek runs before __hfForceTimelineRebind so
its internal force-render picks up the correct time.
Follow-up to the render-reliability batch (#1841/#1842/#1843). Threads two capture-reliability counters through the existing observability → CLI-telemetry pipeline (no new PostHog wiring) so #1842's hardening is measurable on dashboard 1783183:
- transient-retry burn (CaptureAttemptSummary.reason gains "transient-retry"; counted into RenderCaptureObservability.transientRetries on BOTH the recovered and the still-failed paths via a shared helper).
- OOM classification (memoryExhaustionDetected set when describeMemoryExhaustion classifies the failure).
Surfaced as capture_transient_retries + capture_memory_exhaustion_detected render-event props. Tests cover the attempt tagging and the payload mapping.
Further follow-up (different subsystems): encoder-frame-0-exit signal, and P1-3 pre-flight-rejection / P1-4 cli_env_check counters.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
parseFloat('0.1') + parseFloat('0.2') = 0.30000000000000004, so authored
adjacencies whose sum is exact in decimal drift a few ulps and fire the
overlap rule under the strict compare.
Compare on end - start > 1e-6 instead — 11 orders above the worst observed
drift, 4 below one 60fps frame.
Renames the motion-surfacing tool from `hyperframes keyframes` to `hyperframes motion`,
renames the implementation from keyframes*.ts to motion*.ts (keeping the keyframe data
model name where still accurate), and renames the shipped skill from
hyperframes-keyframes to hyperframes-motion. Expands the skill from a command
reference into a full motion-design workflow: reading motion, 3D angle verification,
layered GSAP motion, one-shot reference reproduction, diagnostic checks, and
eval-derived craft guidance.
Reuses the same diamond outline as the Add-keyframe icon next to it, with a
small dot inside carrying the on/off state (filled = auto-recording, hollow
= manual edits won't be keyframed) — pairs the two icons visually instead of
an unrelated circle/slash glyph.
Users pick an --resolution preset whose orientation/aspect ratio (or alpha/HDR mode) conflicts with the composition; the render fails deep in the compiler with a cryptic message. ~8K err / ~1K users.
- New shared pure helper checkOutputResolutionCompatibility in @hyperframes/parsers — single source of truth for aspect/alpha/HDR/downsample/non-integer-scale constraints; suggests the matching-orientation, tier-preserving preset.
- CLI render pre-flight aborts early (before browser/ffmpeg) with an actionable, fix-suggesting message; resolveDeviceScaleFactor delegates to the same helper for identical defense-in-depth messages.
- Suggest (not auto-select); defers when dims can't be determined rather than guessing.
- suggestMatchingPreset keys tier off the -4k suffix so square-family swaps (square + landscape-4k -> square-4k) aren't downgraded to HD.
- render.js DOM polyfill made a lazy import; render.test cold-import beforeAll hooks given a 30s timeout to absorb CI contention.
Render-reliability workstream P1-3. Success measured on PostHog dashboard 1783183.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds a control-bar toggle (next to the Add Keyframe diamond) that, when off,
makes a manual drag/resize/rotate/panel edit on an already-keyframed element
shift the whole tween by the edit's delta instead of inserting or updating a
keyframe at the playhead. The animation's shape is preserved, just moved.
Wired into every path that can auto-record a keyframe:
- canvas drag-to-move (tryGsapDragIntercept, reuses the existing Alt-drag
"shift whole path" behavior)
- canvas resize/rotate (tryGsapResizeIntercept, tryGsapRotationIntercept)
- design-panel property edits (useAnimatedPropertyCommit)
- motion-path keyframe-node dragging (MotionPathOverlay), the path a plain
click-drag on a keyframed element's canvas shape actually takes, since the
element renders exactly at its current keyframe's position
The shared shift helper reuses synthesizeFlatTweenKeyframes for materializing
a flat tween instead of hand-rolling it, and lives in its own file
(gsapWholePropertyOffsetCommit.ts) to keep gsapDragCommit.ts under the
600-line cap, mirroring the existing gsapDragPositionCommit.ts split.
Fixes#1808
Four independent capture-infra hardening changes for the P2-5 failure bucket (~15K err / ~7K users):
- protocolTimeout auto-scales by device-scaled output area (applied before probe launch, since it's immutable post ppt.launch()).
- Single bounded transient retry (MAX_TRANSIENT_CAPTURE_RETRIES=1) on Target closed / Page crashed in the parallel disk-capture path; abort short-circuits before retry.
- Narrow OOM classification (Set maximum size exceeded etc., disjoint from transient) → actionable guidance naming output dims.
- StreamingEncoder.getExitError() threads FFmpeg's real exit reason into frame-0 encoder-death errors.
Render-reliability workstream P2-5. Success measured on PostHog dashboard 1783183.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
WSL first-render success (34.7%) is dominated by a downloaded chrome-headless-shell that launches into `libnss3.so: cannot open shared object file` — doctor/preflight only checked the binary exists, never that it can load its libraries.
- New linuxDeps.ts: /etc/os-release distro detection (Debian/Fedora/Arch/Alpine) + WSL detection, per-distro Chrome dep set, ldd-based shared-lib probe.
- preflight.checkChrome downgrades a found-but-unlaunchable Chrome to a render-blocking error with the exact per-distro install command.
- Distro-aware ffmpeg hints; launch failures converted to actionable guidance pointing at `hyperframes doctor` (skipped on ARM64).
- Detect + print remediation (no auto-install).
Render-reliability workstream P1-4. Success measured on PostHog dashboard 1783183.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- fs.watch's async 'error' event had no listener, crashing the preview
server on EMFILE (exhausted OS watch handles)
- moveKeyframeInScript/resizeKeyframedTweenInScript/removeAllKeyframesFromScript
required object-form keyframes: {"0%": {...}}, silently no-opping on
array-form keyframes: [{...}, {...}]
- a keyframe diamond click's auto-synthesized native click event bubbled
to the ancestor clip's onClick, which toggles selection off when the
clip is already selected (the state every diamond click happens in)
- the clip's trim-resize handles (z-index 4) visually and functionally
covered any keyframe diamond within their 14px edge strip
- synthesizeFlatTweenKeyframes didn't recognize a collapsed
duration:0 + immediateRender static hold (what remove-all-keyframes
produces) as non-animated, so it kept showing a phantom diamond after
Delete All Keyframes
- resolveMediaStartSeconds's fast path for elements with their own
data-start discarded the host composition's inherited start offset,
so a video nested inside a sub-composition played from the root
timeline's time instead of holding until its parent scene began
Fixes#1838
onRuntimeTimelineReady (the cross-origin ready signal for signed CDN
composition URLs) never called _rescale(), leaving the iframe unscaled
and untransformed if the runtime's stage-size postMessage was ever
skipped. Also adds a one-shot diagnostic warning when a rescale keeps
no-oping after ready, latched so a legitimately hidden/zero-size player
doesn't spam the console.
Miguel Ángel