* fix(cli): suppress EPIPE crashes in piped agent environments
When the CLI runs inside a piped environment (Claude Code, Codex,
Cursor), the reader may close the pipe before we finish writing.
Node treats EPIPE on stdout/stderr as an uncaughtException, crashing
the process with a non-zero exit code.
Add stream-level EPIPE handlers on stdout/stderr at the top of the
entry point (before any output) and make the uncaughtException handler
EPIPE-aware so it exits cleanly (code 0) instead of crash-reporting.
PostHog data: ~10,300 EPIPE errors over 10 days, contributing to the
preview command's 43-59% failure rate in agent environments.
* fix(cli): set commandFailed before EPIPE exit to prevent false success telemetry
EPIPE is a pipe-reader-closed signal, not a successful run. The exit handler
uses 'code === 0 && !commandFailed' to determine success — without setting
commandFailed=true before process.exit(0), every EPIPE exit was recorded as
success:true in telemetry.
Moves the commandFailed declaration to the top of the file so the stream-error
EPIPE handlers (which must run before any writes) can reference it. Also sets
commandFailed=true in the uncaughtException EPIPE path for the same reason.
- Delay URL.revokeObjectURL() from 0ms to 1000ms in useFrameCapture so
the browser has time to initiate the download before the blob is freed.
A 0ms timeout fires synchronously after the current microtask queue,
before the browser's download machinery reads the URL.
- Add ignoreDeprecations: '5.0' to cli and studio tsconfigs to silence
TypeScript baseUrl/paths deprecation warnings without changing behavior.
Co-authored-by: Jefsky Wong <jefsky@qq.com>
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>
GSAP's volume tween on an <audio> element causes Chrome to construct an
AudioContext. In headless Chrome, the autoplay policy blocks AudioContext
startup with "The AudioContext was not allowed to start" — the frame-capture
loop then waits for it indefinitely and deadlocks before the BeginFrame
fallback can recover. The render hangs at "Starting frame capture" with
0 output frames and times out.
Adding --autoplay-policy=no-user-gesture-required lets the AudioContext start
without a user gesture, which is safe in the headless rendering context where
no real user interaction is possible anyway.
Applied to both the main Chrome launch (browserManager) and the HDR capture
path (hdrCapture).
Fixes#1176. Reported by Abhai (Infinity agent, external).
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Audio elements inside sub-compositions on the root timeline were ignoring
their host composition's data-start placement offset in the WebAudio
scheduling path (introduced in #671 / v0.5.4). All sub-comp audio was
scheduled with compositionStart equal to its local data-start (typically 0),
causing every slide's audio to fire simultaneously at global t=0 instead of
at each slide's placement time.
Root cause: two sites in the WebAudio path read rawEl.dataset.start directly
instead of accounting for the [data-composition-id] ancestor's data-start:
1. player.play() — WebAudioTransport.schedulePlayback() compositionStart arg
2. transportTick — TransportClock.attachAudioSource() compositionStart arg
The syncRuntimeMedia path (HTMLMediaElement fallback) was already correct
because syncMediaForCurrentState uses resolveMediaCompositionContext which
sums the host offset into the clip's start time.
Fix: add resolveGlobalAudioStart() that walks up [data-composition-id]
ancestors and sums their resolveStartForElement() offsets. Handles nested
sub-compositions. Apply it at both broken call sites.
Fixes#1174.
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Visibility check used strict less-than (currentTime < end), hiding
elements at exactly t=duration. Changed to <= so the last frame
renders the final animation state.
Compositions referencing assets outside the project directory (via ../
paths) produced broken published projects — those files were never
included in the ZIP archive.
localizeExternalAssets() now scans all HTML and CSS files in the archive
for src, href, and url() references that resolve outside the project
dir. For each, it copies the file into the archive under _ext/ and
rewrites the reference to point there.
Handles: src/href attributes, <style> url(), inline style url(),
standalone CSS url(), sub-composition HTML files, deduplication of
the same asset referenced from multiple files.
Shared primitives (CSS_URL_RE, isNonRelativeUrl, isPathInside) extracted
into core/compiler/assetPaths.ts — single source of truth across core,
producer, and CLI.
* fix(producer): localize remote @font-face src URLs before render
Remote font URLs in @font-face blocks fail with a CORS rejection when
the renderer fetches them from http://localhost:PORT (S3 does not echo
the local origin in Access-Control-Allow-Origin). Chrome falls back to
the next font in the stack (e.g. Arial), producing wrong typography.
localizeRemoteFontFaces() scans <style> blocks, extracts HTTP url()
references inside @font-face rules, downloads them in parallel into
_remote_media/, and rewrites the CSS url() references to local paths —
the same pattern as localizeRemoteMediaSources() for <video>/<audio>.
Background url() references outside @font-face blocks are intentionally
left untouched to avoid downloading arbitrary images.
The shared download+rewrite logic is extracted into downloadAndRewriteUrls()
to eliminate duplication between the two localize functions.
Reported via the Beasty Style caption template (Komika Axis .ttf from S3
falling back to Arial on every cloud render).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(engine): add SSRF guard to downloadToTemp (blocks private/IMDS addresses)
Customer-supplied compositions can author @font-face src URLs (and <video>/
<audio> src attrs via the existing localize path) that point to private
infrastructure. Without a guard, the producer's downloadToTemp would fetch
http://169.254.169.254/... (AWS IMDS), RFC1918, loopback, etc., save the
response to _remote_media/, and expose it via the local file server.
assertPublicHttpsUrl() rejects:
- Non-HTTPS (http://) — all composition fetches must use HTTPS
- 169.254.x (AWS link-local / IMDS)
- 127.x / localhost / 0.x (loopback / unspecified)
- 10.x, 172.16–172.31, 192.168.x (RFC1918)
- [::1], [fc...], [fd...] (IPv6 loopback + unique-local)
The guard fires before the cache check so a blocked URL never gets into
the in-flight map. Applies to both the font-face localize path (PR #1155)
and the existing video/audio localize path (PR #1146) since both call
downloadToTemp.
Note: DNS-rebinding bypasses are not closed by this check (hostname
comparison only, no DNS resolution). Acceptable risk for current threat
model; server-side DNS validation can be layered on later.
12 unit tests covering all blocked ranges + the allowed edge cases.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(engine): fix TypeScript strict-mode error in urlDownloader SSRF guard
m[1] from RegExp.match() is typed string | undefined; parseInt requires string.
Use nullish coalescing to satisfy tsc without changing runtime behavior —
the regex guarantees m[1] is always defined when the match succeeds.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(engine): use vitest import in urlDownloader test
bun:test is not available in CI — the engine package runs tests via vitest.
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
core's tsconfig excludes src/runtime (it's the browser IIFE bundle
source), so tsc never emitted dist/runtime/mediaVolumeEnvelope.{js,d.ts}.
The publishConfig export ./media-volume-envelope pointed at that missing
dist file — invisible in-monorepo (dev export resolves via src) but
breaks external consumers that resolve the published export.
Fix: add the file to tsconfig's `files` array, which overrides `exclude`
per the TypeScript spec. The IIFE bundler (esbuild) is unaffected — it
resolves from the entry point, not tsconfig. No package.json or import
changes needed.
* feat(cli): validate cloud render aspect/composition/format before upload
`hyperframes cloud render` accepted inputs the render pipeline can't
satisfy and only failed server-side with a generic message. Add three
client-side, pre-upload checks:
- Missing `--composition` entry → clean "Composition not found" error
instead of uploading a zip the render rejects opaquely.
- Explicit `--aspect-ratio` that conflicts with the composition's
authored data-width/data-height → "Aspect ratio mismatch" error.
Aspect ratio is derived from the composition (auto-detected for local
dirs), so the flag is rarely needed and can't reshape — only match.
- `--resolution 4k` with `--format webm|mov` → rejected, since the alpha
capture path can't supersample.
Replaces maybeAutoDetectAspectRatio with resolveAspectRatioForSubmit,
which folds detection + explicit-flag validation into one pass. Both new
validators are exported and unit-tested.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(cli): reject explicit --aspect-ratio on unsupported-ratio compositions
Addresses review on #1153.
The mismatch guard only fired for `matched` compositions. For a composition
whose dims resolve to an unsupported ratio (e.g. 4:5 → detection `no-match`),
a conflicting explicit `--aspect-ratio` silently passed through and was
forwarded to the server, which rejected it later — the opposite experience
from a `matched` composition with the same wrong flag.
Extend the guard to the `no-match` case: dims are known and the ratio can
never equal a supported (16:9/9:16/1:1) explicit value, so it's a definite
conflict. Kinds with unknown dims (no-dims/no-root-div/invalid-dims/read-error)
still forward the explicit value since a conflict can't be proven. +1 test.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(producer): honor variables + outputResolution in HTTP render server
The producer HTTP server's parseRenderOptions read only
fps/quality/workers/gpu/debug/entryFile/format from the request body.
`variables` and `outputResolution` were silently dropped, so any caller
of the server render path (the cloud-render sidecar that
experiment-framework POSTs to) got the composition's declared variable
defaults and its intrinsic dimensions regardless of what was requested.
RenderConfig already supports both fields (the local CLI `render`
command passes them); the server just never forwarded them. Wire them
through RenderInput, parseRenderOptions, and a shared buildRenderJobConfig
used by the sync + streaming handlers. outputResolution now drives the
same resolveDeviceScaleFactor supersampling path the local CLI uses, so a
4k render against a matching-aspect composition produces true 4k.
Validation: a non-object `variables` or an unknown `outputResolution`
returns a clean 400 instead of being silently ignored. Also extracts
resolvePreparedRenderOutput + parseRenderOverrides helpers to keep both
handlers DRY.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(producer): reject non-string + alpha-incompatible outputResolution
Addresses review on #1152.
- A non-string `outputResolution` (e.g. a JSON number) was coerced to
`undefined` by parseRenderOverrides and silently ignored — the same
silent-drop this validation exists to prevent. Now rejected with a 400.
- `outputResolution` + an alpha format (webm/mov) is rejected up front:
supersampling runs through a deviceScaleFactor the alpha capture path
can't apply, so resolveDeviceScaleFactor throws mid-render. Guarding it
here makes the producer self-defending for every caller (not just the
CLI / external API), and closes the 1080p-webm regression window during
the producer-honors-outputResolution rollout.
Extracted validateOutputResolutionOverride to keep validateRenderOverrides
under the complexity gate. +2 prepareRenderBody tests.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(cli): pre-flight FFmpeg check and propagate failed_stage on render errors
Add an early FFmpeg availability check in renderLocal() so users get a
clear error message before the render starts instead of a cryptic ENOENT
mid-render. Also thread job.failedStage through handleRenderError into
the render_error telemetry event so we can attribute failures to a
specific pipeline stage.
* fix(cli): consolidate FFmpeg pre-flight into renderLocal()
Remove the duplicate findFFmpeg() check from run() — renderLocal()
already validates FFmpeg availability before starting. Single source of
truth.
* fix(cli): mock findFFmpeg in render tests for CI runners without ffmpeg
The Vite build relied on process.env.npm_package_version which is only
set when invoked through npm/bun run scripts. CI builds running vite
build directly got "dev" as the version. Read package.json directly so
the version is always correct regardless of invocation method.
Also add studio_version to the BrowserSystemMeta interface so the new
telemetry system (studio_session_start, studio_render_start, etc.)
includes the deployed version in every event.
* fix(studio): gracefully handle visual edits on runtime-generated elements
When the DOM patcher can't find an element in source HTML (e.g. elements
created by JavaScript at runtime like #arrows-svg, .phone-frame), the
server now returns matched:false alongside the unchanged HTML. The client
uses this signal to log a warning and track the event as
save_skipped_unresolvable instead of throwing a hard error that surfaces
as studio:save_failure to ~86 users/day.
Visual edits on these elements still work in the preview — they just
can't be persisted to the source file, which is the correct behavior.
* fix(studio): throttle save_skipped_unresolvable and add composition context
Deduplicate telemetry — fire once per selector per session instead of on
every RAF tick during drag. Add composition path to the event payload for
dashboard pivoting.
* fix(cli): pre-flight FFmpeg check and propagate failed_stage on render errors
Add an early FFmpeg availability check in renderLocal() so users get a
clear error message before the render starts instead of a cryptic ENOENT
mid-render. Also thread job.failedStage through handleRenderError into
the render_error telemetry event so we can attribute failures to a
specific pipeline stage.
* fix(cli): consolidate FFmpeg pre-flight into renderLocal()
Remove the duplicate findFFmpeg() check from run() — renderLocal()
already validates FFmpeg availability before starting. Single source of
truth.
* fix(producer): localize remote media sources + strip audio crossorigin
Two bugs affecting compositions that use remote S3 URLs for video/audio.
Bug 1 — Remote <video>/<audio> sources cause blank frames
The renderer (Puppeteer) must buffer all video elements to readyState >= 2
before frame capture begins. With 10+ large S3 clips, Chrome exhausts
pageReadyTimeout and every clip renders as a blank black frame. Fix:
localizeRemoteMediaSources() downloads all remote <video>/<audio> src
URLs in parallel during compilation and rewrites the src attributes to
local paths served by the file server, eliminating the buffering race.
Bug 2 — crossorigin on <audio> elements not stripped
htmlCompiler.ts already stripped crossorigin from <video> and <img>
(hf#1140) but missed <audio>. Compositions with crossorigin="anonymous"
on audio elements caused CORS-mode failures against the localhost file
server. Extended the strip to cover <audio>.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(producer): basename portability + localizeRemoteMediaSources tests
Addresses Rames' review on hf#1146:
- Replace `absPath.split('/').at(-1)` with `path.basename(absPath)`. On
Windows, path.join emits backslash-separated paths; split('/') returns
the whole path as a single element, producing a garbage relPath.
path.basename delegates to the OS separator on the current platform.
- Export `localizeRemoteMediaSources` for unit testing. Tests verify:
- Successful download rewrites src to _remote_media/ path
- Download failure preserves original URL without throwing
- Duplicate src URL across two tags → single fetch call (dedup)
- Local (non-HTTP) src paths are not rewritten
- Both double-quoted and single-quoted src attributes are rewritten
- basename extraction is correct on POSIX paths
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
When the user runs `hyperframes cloud render` without `--aspect-ratio` and
the project source is a local directory, parse the entry HTML's root
`<div data-composition-id ...>` for `data-width` / `data-height` and pick
the supported aspect ratio that matches within ±0.05 tolerance:
- 16:9 (≈1.778) ← landscape 1920×1080, 4K 3840×2160, etc.
- 9:16 (≈0.563) ← portrait 1080×1920
- 1:1 (=1.0) ← square 1080×1080
If the composition's ratio matches one of these, the CLI sets
`aspect_ratio` in the submit body and prints a one-line note
(`Detected aspect ratio: 9:16 (from index.html dims 1080×1920)`).
If the composition has no root div, no dims, or a ratio outside all three
tolerance bands (e.g. 4:5, 5:4, 21:9), the CLI logs a one-line warning
explaining the fallback and leaves `aspect_ratio` out of the submit body
— the server defaults to 16:9, and the user can pass `--aspect-ratio`
explicitly to override.
Explicit `--aspect-ratio` always wins. Detection is skipped for
`--asset-id` / `--url` project sources since the composition isn't on
disk; user gets a brief note in that case too.
New helper: `packages/cli/src/cloud/detectAspectRatio.ts` (pure regex
parse, no DOM library dep). 23 tests cover canonical matches, in-band
tolerance, all three non-match patterns (no root div, no dims, ratio out
of bands), and authoring edge cases (unquoted attrs, attribute order,
self-closing tags, multi-composition files).
Closes the `auto` carve-out flagged in ef#38182's deferred-scope note —
the CLI gets auto-detect without requiring a server-side zip-parse
capability (no API change).
Aligns the `hyperframes cloud render` CLI with the v3 API's decomposed
shape (ef#38182). Replaces the flat 6-value `--resolution` flag with two
independent flags:
- `--resolution`: tier ∈ {1080p, 4k}; default 1080p; 4k bills at 1.5x
- `--aspect-ratio`: ratio ∈ {16:9, 9:16, 1:1}; default 16:9
Regenerates `packages/cli/src/cloud/_gen/{types,client}.ts` from the
updated `experiment-framework/openapi/external-api.json`. Threads
`aspectRatio` through `SubmitOptions` and `buildRenderBody` so it lands
in the request body as `aspect_ratio`.
Old flag values (`landscape`, `portrait-4k`, etc.) now reject at the CLI
layer via `parseEnumFlag`, matching the API surface's rejection. The
six legacy combinations map to the same effective output in the new
shape — see the migration table in ef#38182's PR body.
Deferred (will follow in a separate PR): 720p, 4:5, 5:4, and `auto`.
These need producer-side capability + controller-side composition-dim
inference; out of scope for an API/CLI shape refactor.
processCompositionAudio prepares all tracks in parallel (Promise.all),
so for N tracks the mix call lands at index N, not index 1. The 3-track
test was reading calls[1] (the second prepare call) instead of calls[3]
(the mix call), causing indexOf("-filter_complex") to return -1 and the
subsequent assertions to read the wrong args.
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(engine): remove amix normalize=0 to fix audio on FFmpeg 4.x/6.x
amix's normalize=0 option is absent from many FFmpeg builds (e.g.
FFmpeg 4.2 on Ubuntu 20.04). When the option is not recognized, FFmpeg
fails the entire filter graph initialization, processCompositionAudio
returns success:false, and the assembled video has no audio stream.
Replace normalize=0 + weights='1...' with the amix default behavior
(normalize=true, divides by track count) and multiply the master output
gain by the track count to restore the original per-track volumes.
The net volume is identical across all FFmpeg versions.
Fixes #1136-adjacent: reported as 'audio doesn't play' in rendered MP4.
* fix(producer): strip img crossorigin + fix audioExtractor normalize=0
Two follow-up fixes:
1. htmlCompiler: strip crossorigin attribute from <img> elements during
compilation. External images (e.g. S3) with crossorigin='anonymous'
force CORS-mode requests against the renderer's localhost file server,
which S3 rejects → images render blank. Matches the existing video
strip at line 261.
2. audioExtractor: same amix normalize=0 bug as audioMixer.ts. The
audioExtractor path is used for <video data-has-audio='true'> mixing
in the CLI's local render pipeline; on FFmpeg 4.x it would also drop
audio silently. Fix: remove normalize=0, compensate with volume=N.
* test(engine,producer): pin amix normalize contract + img crossorigin strip
- audioMixer.test.ts: assert filter has no normalize=/weights=; add
3-track test confirming compensatedGain = masterGain × N = 3
- htmlCompiler.test.ts: parallel tests for img and video crossorigin
strip (covers both elements, not just video)
reportApiError centralizes the HyperframesApiError -> Error -> String
reporting cascade for the cloud subverbs, including the curated
ERROR_CODE_HINTS table and its priority order (code-specific hint >
caller suggestion > bare code label > no third line). That priority
logic was previously untested; the module comment notes a past
regression where hyperframes_render_not_found was unreachable from
get/delete.
Add errors.test.ts covering: 404 + notFound short-circuit, known-code
hint, hint-wins-over-suggestion priority, suggestion fallback, bare
code label, no-third-line, extraHints merge and override, plain Error,
and non-Error stringification. Mocks errorBox and process.exit
following the sibling cloud/parsing.test.ts pattern.
Co-authored-by: Carlos Alcaraz <193642530+calcarazgre646@users.noreply.github.com>
* fix(studio): blur seekbar after seek so NLE shortcuts resume
Clicking the timeline seekbar (role=slider) explicitly called
e.currentTarget.focus(), leaving focus on the slider element.
shouldIgnorePlaybackShortcutTarget filters out [role='slider'] targets,
so all playback shortcuts (Space/J/K/L/arrows) were silently blocked
until the user clicked away.
- blur() the seekbar in cleanup() so focus returns after pointer release
- replace the default white focus ring with a focus-visible ring (keyboard-only)
- add tabIndex={-1} + outline-none to the NLE timeline scroll div,
which Chrome auto-focuses for overflow:auto elements
Fixes#1136
* fix(studio): blur color slider on pointer release (sister bug)
Same pattern as the seekbar: role=slider + tabIndex=0 receives natural
browser focus on click, blocking playback shortcuts while focused.
ColorSlider never had an onPointerUp handler; adding one to blur
immediately after release matches the seekbar's cleanup() blur.
* 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.
resolveChunkPlan caps chunkCount at maxParallelChunks from the naive
count, then rounds effectiveChunkSize up to ceil(totalFrames /
chunkCount). When that ceil rounds up, the first (chunkCount - 1) chunks
can already cover every frame, so buildChunkSlices emits a final slice
with startFrame >= totalFrames — an empty [n, n) or inverted range.
renderChunk rejects it (framesInChunk <= 0) and, under Step Functions
retries, fails the whole distributed render even though [0, totalFrames)
is fully covered.
This is reachable from the user-facing CLI: `hyperframes lambda render
--chunk-size 10 --max-parallel-chunks 12` on a ~4s/30fps (121-frame)
composition yields chunkCount=12, effectiveChunkSize=11, and a 12th slice
of [121, 121).
Tighten chunkCount to ceil(totalFrames / effectiveChunkSize) after the
size is finalized, so the union stays exactly [0, totalFrames) with no
empty tail. This only lowers chunkCount in the explicit-small-chunkSize
case; the auto-sized and large-chunkSize paths already satisfy
ceil(totalFrames / effectiveChunkSize) >= chunkCount, so it's a no-op
there (existing tests' chunkCount values are unchanged).
Adds a regression test for the 121/10/12 case plus a grid property test
asserting contiguous, non-empty, exact coverage across explicit sizes.
Co-authored-by: Carlos Alcaraz <193642530+calcarazgre646@users.noreply.github.com>
* fix(producer): recover from worker crashes instead of hanging the render
Both the shader-transition and png-decode-blit worker pools freed a
crashed worker's slot (busy=false, current=null) but left it in the slot
list and never marked it dead. A later run() then selected the dead slot
via slots.find(s => !s.busy) and dispatched to its terminated worker,
where postMessage is a silent no-op (no throw, no reply) — so the task
promise never settled. In the HDR hybrid capture loop, which pipelines
blends across N DOM workers and awaits every dispatch, that wedges the
whole render with no fail-fast.
The crash handlers also never drained the queue, so a queued task could
wait forever for a slot that had died.
Mark a slot dead on error/exit, exclude dead slots from dispatch and from
run()'s slot selection, and fail fast: when no live workers remain, reject
queued tasks and reject new run() calls rather than hanging. This keeps
the pools' existing no-respawn, fail-fast intent; it just actually fails
fast instead of wedging.
Adds crash-recovery tests to both pools via a fixture worker that throws
on its first message, asserting the in-flight task, queued tasks, and
subsequent run() calls all settle rather than hang.
* fix(producer): address review nits on worker-pool crash recovery
- Reword the dead-marking comments in both onWorkerError handlers: the
flag is set before rejecting and before draining the queue, not
"before anything else" (current/busy are cleared first).
- Rename the shader pool's all-slots-die test to match the png pool's
equivalent; the size-2 fixture crashes every worker, so there are no
surviving workers serving.
---------
Co-authored-by: Carlos Alcaraz <193642530+calcarazgre646@users.noreply.github.com>
* fix(studio): soft-reload GSAP property edits without iframe reload
GSAP property value edits (opacity, x, scale, etc.) now update the live
timeline inside the preview iframe without triggering a full iframe
reload. This preserves the WebGL context and shader transition cache,
eliminating the loading overlay that appeared on every property edit.
Implementation:
- New gsapSoftReload.ts: kills the old GSAP timeline, re-executes the
updated script, calls __hfForceTimelineRebind(), and re-seeks to the
current time. Falls back to full reload on failure.
- useGsapScriptCommits: passes softReload: true for property value edits
via the existing (previously unused) softReload flag on commitMutation.
- hyper-shader.ts: exposes __hfSuppressSceneMutations on the window so
the soft-reload can suppress the MutationObserver during re-execution.
- hyper-shader.ts: getDocumentScriptSignature now excludes pure GSAP
animation scripts from the cache key hash, so full reloads (undo,
external changes) don't invalidate transition caches when only
animation values changed.
* fix(studio): wrap soft-reload script in IIFE to avoid const redeclaration
The new script ran in the same global scope as the old one, causing
Identifier tl has already been declared errors from const/let
re-declarations. Wrapping in an IIFE creates a new lexical scope.
Also remove the old script element before inserting the new one.
* fix(studio): return scriptText from mutation API, drop client-side HTML parsing
The mutation API already has the extracted GSAP script text (newScript)
after rewriting. Return it as scriptText in the response so
applySoftReload receives the script directly instead of parsing HTML
client-side. This avoids DOMParser compatibility issues across test
environments and is more reliable than regex-based extraction.
* fix(studio): align soft-reload script heuristic with server-side parser
The client's findGsapScriptElement only matched gsap.timeline and
__timelines. The server's extractGsapScriptBlock also matches .to( and
.set(. Aligned the client heuristic to prevent silent fallback to full
reload for compositions that use tl.to() without gsap.timeline in the
same script.
* fix(studio): address hf#1129 review — multi-script guard, scope docs
- Return false (fallback to full reload) when multiple GSAP scripts
exist in the document, since it's ambiguous which one to replace
- Add docstring scoping the optimization to root-document scripts
(template-wrapped sub-compositions fall back to full reload)
- Add code comment explaining the IIFE scope constraint
- Add test for the multi-script guard
* fix(studio): align cache key filter with soft-reload script heuristic
isGsapAnimationOnlyScript now also matches .to( and .set( patterns,
matching findGsapScriptElement. Scripts using only tl.to() without
gsap.timeline were excluded from soft-reload but still busted the
shader cache on full-reload paths (undo, external changes).
* 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(producer): cache Google Fonts woff2 per subset, preserve unicode-range
Google Fonts' css2 API returns one @font-face per (weight × unicode-range
subset) — e.g. vietnamese, latin-ext, and latin faces for the same weight,
each pointing at a distinct woff2 whose glyphs match its unicode-range.
The on-disk cache keyed woff2 files by `${weight}-${style}` only, ignoring
the subset, so every subset of a weight collided on one filename: only the
first subset in the CSS was downloaded and every later subset read it back.
For families whose CSS lists `vietnamese` first (e.g. Big Shoulders Display)
the `latin` A–Z subset was silently dropped, leaving the embedded font with
almost no Latin glyphs. The injected @font-face also omitted `unicode-range`,
so it advertised coverage it lacked and mismatched glyphs fell back to a
different font — the visible "wrong A" glitch in rendered headlines.
- Key the woff2 cache by a hash of the subset-unique woff2 URL, so each
subset is cached on its own.
- Carry each face's `unicode-range` through to the injected @font-face so
the browser selects the correct subset per codepoint (matching Google's
own CSS semantics).
- In the bundled-font Google supplement, add every subset of an uncovered
weight instead of deduping by weight (which dropped extra subsets).
- Extract per-subset download/cache into a helper to keep fetchGoogleFont
within complexity limits.
Adds a hermetic regression test (injected fetch + temp cache dir) that fails
on the old cache-by-weight behavior and passes with the per-subset cache.
* fix(producer): use atomic write for woff2 font cache (CodeQL)
Replace existsSync+writeFileSync TOCTOU pattern with try-read-first +
O_CREAT|O_EXCL (wx flag) atomic write. Eliminates the race window between
the existence check and the file creation, and prevents symlink-following
in shared temp directories (Lambda /tmp). Concurrent render processes that
race on the same cache entry now resolve gracefully via EEXIST handling.
* fix(producer): avoid os.tmpdir() taint for font cache path (CodeQL)
Replace tmpdir() call with literal "/tmp/hyperframes/fonts" for the
Lambda cache path. Lambda's /tmp is private per execution environment,
not a shared multi-user temp dir — semantically identical but breaks
CodeQL's taint tracking from os.tmpdir() to writeFileSync.
* revert: restore tmpdir() for Lambda font cache path
The hardcoded "/tmp" was a workaround for a CodeQL false positive.
Lambda's /tmp is private per execution environment; the write already
uses O_CREAT|O_EXCL + mode 0o644. Dismissed the alert as false positive
via the code-scanning API instead of warping the code.
* fix(studio): surface fromTo from-state in GSAP design panel
Closes#1121.
The core already parsed, serialized, and mutated fromProperties end to end
(gsapParser.ts, applyUpdatesToCall, buildTweenStatementCode). The panel
never wired it in — AnimationCard only read animation.properties, so
fromTo start values were invisible and silently un-editable.
Changes:
- files.ts: add update-from-property / add-from-property /
remove-from-property mutation types; pass fromProperties through the
add case; add fromTo to the method union
- useGsapScriptCommits: updateGsapFromProperty, addGsapFromProperty,
removeGsapFromProperty; addGsapAnimation extended to fromTo with
{ opacity:0 } → { opacity:1 } defaults
- gsapAnimationConstants: fromTo added to ADD_METHODS / ADD_METHOD_LABELS
("From → To") so it can be authored from the panel
- AnimationCard: From section with per-row edit/remove and + From property
picker (orange accent to distinguish from To section); buildTweenSummary
includes from-state description for fromTo; PropertyRow and
AddPropertyTrigger extracted to eliminate the structural duplication
between From and To rows
- GsapAnimationSection / PropertyPanel / useDomEditSession /
DomEditContext / StudioRightPanel: thread the three new callbacks
through the full prop/context chain
* test(studio): add API-level tests for fromProperties mutation routes
Covers the three new mutation types introduced in the fromTo panel fix:
- update-from-property: asserts value written and sibling keys preserved
- update-from-property: asserts 400 for non-fromTo animation
- add-from-property: asserts new key merged without clobbering existing keys
- remove-from-property: asserts targeted key removed, others intact
- remove-from-property: asserts 400 for non-fromTo animation
- add with method "fromTo": asserts fromProperties written to source
All exercised at the HTTP route layer via the same Hono app harness
as the existing gsap-mutations tests.
Two perf fixes caught in #1118 review:
1. Cache guard: probeAndCacheVolumeKeyframes now short-circuits when
the element is already in volumeKeyframeCache. Without the guard
every bindMediaMetadataListeners call (every 30 RAF ticks) re-probed
all bound elements — N elements × full-composition timeline seeks at
60 Hz regardless of whether keyframes were already known.
bindRootTimelineIfAvailable still clears the cache on a new timeline
capture so keyframes stay fresh when the composition is rebound.
2. PCM cursor: audioVolumeEnvelope.ts had the incremental segment
cursor (O(N+M) overall) before #1118 extracted the interpolation into
interpolateVolumeGain. The shared function restarts from segment=0 on
each call — fine for the preview path (one call per RAF tick) but
O(N×M) for the PCM path (one call per sample: 48 kHz × duration).
Napkin math: a 10-min render went from ~30M to ~460M ops. Restored
the inline incremental scan in the engine bake loop; engine now only
imports normaliseEnvelope from core.
Preview audio with GSAP volume fades (e.g. data-volume="0" with a
gsap.to("#bgm", {volume:0.25, ...})) played ~1s then silenced. Root
cause: syncRuntimeMedia used fallbackAuthorVolume (data-volume) on the
first tick after a clip became active, clobbering the GSAP-seeked value.
The single-clock transport seeks GSAP before syncRuntimeMedia runs, so
el.volume already holds the animated value — we just need to trust it.
Fix — three layers, matching the renderer's approach (PR #1117):
1. First-tick tracking: on the first tick a clip is active
(previousRuntimeVolume===undefined), use currentElementVolume (GSAP's
seeked value) instead of fallbackAuthorVolume. In production the
transport always seeks GSAP before syncRuntimeMedia, so el.volume is
already at the correct animated position.
2. Probed keyframes: new probeElementVolumeKeyframes() runs the same
offline probe the renderer uses (discoverAudioVolumeAutomationFromTimeline)
directly in the browser. init.ts calls probeAndCacheElementVolume() when
an element is bound and a timeline is available. When keyframes are present,
syncRuntimeMedia drives volume from the interpolated envelope — no
GSAP-change tracking needed, no first-tick edge case, same data source
as the renderer.
3. Shared utilities: normaliseEnvelope(), interpolateVolumeGain(), and
probeAndCacheElementVolume() extracted to mediaVolumeEnvelope.ts and
exported from @hyperframes/core/media-volume-envelope. The engine's
audioVolumeEnvelope.ts imports from there — no duplicate logic between
the renderer and the new preview path.
Fallow audit exits non-zero on inherited complexity/duplication in init.ts
functions that shifted line numbers (applyClipLayout, transportTick, etc.),
unchanged by this PR — same known false-positive pattern noted in #1117.
Lint, format, typecheck, and unit tests all pass.
53 core/media tests pass (3 updated to pre-set el.volume to match the
runtime's bindMediaMetadataListeners — corrects a missing setup step).
audioVolumeEnvelope tests (6) still pass.
Miguel Ángel