* fix(studio): text in Studio reads without em or en dashes
* fix(studio): the dash check also catches HTML entities, and peak reads Unavailable
* test(studio): the dash check test covers every entity form
* fix(studio): messages Studio shows from lint, sdk, core and the renderer drop dashes too
* fix(producer): the gate check stops early on the engine's new fallback wording
* feat(core): add a lookahead true-peak limiter FX (truepeak)
The existing limiter is an envelope follower with no lookahead and no
inter-sample detection, so a -14 dB ceiling can leave the true peak several dB
over. truepeak estimates the true peak on a 4x polyphase interpolator, takes the
minimum required gain over a lookahead window and smooths it with a boxcar of
the same length, so the gain is already down when the peak leaves the delay
line. Release is exponential and can only lower the gain further; channels
share one gain.
The offline render lengthens the OfflineAudioContext by the chain's latency and
drops the lead-in, so a limited clip stays sample-aligned with its source.
Preview plays the lookahead (about 3.3 ms at the default).
— Jerrai
* docs(audio): truepeak ceiling is a 4x estimate; measure it with an ideal interpolator
The unit test's meter was a 96-tap Kaiser sinc, which rolls off near Nyquist and
reads full-band noise about 0.5 dB low, so the PR reported a 0.3 dB broadband
overshoot. Against an ideal 16x interpolation (zero-padded FFT, cross-checked with
a 16x soxr resample) hot full-band white noise ends 1.2 to 1.7 dB over the ceiling
(median 1.4 over 28 runs of 10 to 30 s). ffmpeg's ebur128 true peak is also a 4x
meter and reads the same files 0.1 dB over.
- The test meter is now the FFT interpolation. Tolerances are what it measures on
each fixed signal: tones 0.01 dB (they land on the ceiling), the dense program
0.5 dB (reads 0.445, the old 0.4 passed only because the meter read low), and a
new full-band noise case at -1, -6 and -14 dBTP with 1.35 dB (reads 1.09 to 1.31).
- audio-effects.mdx and the hyperframes-audio skill say the ceiling is a 4x
estimate, give the measured overshoot and recommend a 2 dB margin under a hard
delivery limit.
- skills-manifest.json regenerated.
— Jerrai
* fix(core): truepeak UI copy no longer promises a hard ceiling
The registry description and the rack summary said the true peak is never above
the ceiling. The limiter holds a 4x estimate, and full-band noise can land up to
about 1.7 dB above it, as the docs now say. The summary reads "held near", the
description names the estimate and the overshoot, and the rack blurb says "holds
... to a ceiling". No skill file changed, so the skills manifest is unchanged.
— Jerrai
* fix(core): Studio truepeak copy states the 4x-estimate margin
The ceiling control was labelled "Never exceed" and the module said the mix
"must not clip", so a Studio user never saw that dense full-band content can end
up to about 1.7 dB above the ceiling. The label is now "Target ceiling" with a
hint that names the 4x estimate and the headroom to leave, the blurb says
"toward a target ceiling", the rack summary says peaks are pulled down toward the
value, and the registry hint no longer says "highest true peak allowed". The
audio skill's "hard dBTP ceiling" wording is gone and the skills manifest is
regenerated. A copy test keeps the promise out.
— Jerrai
* fix(core): truepeak clears on a seek, and the review nits (fallow, comments)
- Unexport TRUE_PEAK_OVERSAMPLE, TRUE_PEAK_DETECTOR_DELAY and
truePeakLookaheadSamples: nothing imports them (Fallow audit).
- A persistent group bus keeps its chain across a seek, so the limiter's
delay line and held gain carried over. The worklet takes __hfReset, the
graph exposes FxChainHandle.reset(), and reanchor() calls it.
- The processor-loading harness is shared by the truepeak and worklet tests
(it was a 12-line clone); the test FFT no longer repeats audioCarve's
bit-reversal; two test bodies are under the CRAP threshold.
- Comment blocks cut to four lines or fewer (Comments check).
- Docs state the preview delay in ms.
— Jerrai
* fix(engine): copy border-width/style/color onto the replacement video frame
injectVideoFramesBatch substitutes each <video> with a sibling <img> holding
an extracted still frame, copying an allow-listed set of CSS properties from
the video's computed style onto the img. border-width/border-style/
border-color were absent from that allow-list, so any border authored
directly on a <video> never reached the replacement image and disappeared
from render/snapshot output. border-radius and clip-path were already on the
list and already clip a replaced element's content correctly without
needing overflow:hidden, confirmed by a real-Chromium test that exercises
the actual capture path and reads real screenshot pixels.
Also corrected a stale comment in frameCapture.ts claiming
detectCssEffectRisk can return "clip-path" as a risk value -- it can't; that
string only ever comes from a separate, animation-only at-risk-props gate
further down the same file.
Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>
* test(producer): regenerate style-9-prod golden for the border fix
style-9-prod's video has an authored 8px border + 16px border-radius
(design_review.md calls out the "floating" look) that never rendered before
this fix, so its committed golden baked in the pre-fix (borderless) output.
Regenerated via `tsx src/regression-harness.ts style-9-prod --update`;
verified the diff is exactly the border/radius becoming visible (extracted
frames before/after) and the fixture passes its own visual/audio checks
again (100/100 checkpoints, correlation 1.000).
Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>
* fix(engine): measure the video's box before styling its replacement frame
injectVideoFramesBatch measured the video's used box (offsetLeft/Top/
Width/Height) after creating, inserting, and styling the replacement
<img> sibling -- once that copy loop started carrying border-width
(added for the border-visibility fix), the freshly-inserted, still
in-flow, now-bordered <img> competed for space in a flex row before
the video's own box was ever read. In a flex-centered layout (video
width:100%, sharing a row with the img sibling), that shrank the
measured video box by the exact width of the border, so the img ended
up sized from the video's post-shrink box instead of its authored one.
Moved the measurement to before the <img> is created/inserted/styled
at all, and set img.style.boxSizing = "border-box" explicitly after
the style-copy loop, since offsetWidth/offsetHeight (and the
getBoundingClientRect fallback) are always a border-box measurement
regardless of what box-sizing value that loop copies from the video's
own computed style.
Added a flex-centered regression test asserting the replacement img's
box stays identical to the video's box; confirmed it fails with the
old measurement order (a 16px border shrinks a 500px box to 484px) and
passes with the fix. Regenerated the one fixture (style-9-prod) whose
committed golden had baked in the shrunk-frame geometry.
Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>
* refactor(engine): consolidate video-box measurement into one object
Follow-up to c88890357: group the four measurement locals into a
single videoBox object instead of four loose consts, and trim the
surrounding comments down to their load-bearing content. No behavior
change -- same measurement order, same fallback conditions, same
applied style values; re-verified red (reverting the measurement order
still reproduces the 500px -> 484px shrink) and green.
Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>
* refactor(engine): trim the border-fix comments to the invariant
* test(producer): keep main's style-9-prod compiled.html; timings are unchanged
* test(producer): repin the classification source hash for test reachability
* fix(core): a color-graded bordered source keeps its canvas inside its border box
* fix(core): a graded source with an empty content box still shows its border
* fix(core): a border-only graded canvas stays hidden until the source has drawn
* fix(core): border-only graded canvas shows only while grading hides the source
* test(core): pin the border-only canvas hide after a context loss
* fix(core): grading canvas carries no border, so a graded source never paints it twice
* fix(core): graded injected frame drops its border once grading draws over it
* fix(core): a released grading entry gives the injected frame its border back
* fix(core): a released injected frame takes the video's current border style
---------
Co-authored-by: Miguel Ángel <miguel.sierra@heygen.com>
* perf(packages): ship npm packages without source maps and guard their size in CI
No package or consumer reads the published source maps, so they are no
longer built. The CLI copies only the studio app it serves instead of the
whole studio dist. verify:packed-manifests now holds every published package
to a size budget that ratchets down, and CI rejects pull requests that add a
large binary outside LFS.
* fix(ci): large-binary check reads every filename and fails on git errors
* ci: run only Build when a skill bundled into the CLI changes
* fix(ci): size guards also catch type changes, odd file names, unreadable blobs and bad budgets
* fix(ci): large-binary check reads blobs by id and skips submodules
* fix(ci): exempt only exact registry copies under docs/public/catalog
* test(ci): cover the staged catalog-copy exemption; drop the local-only override hint in CI
* fix(ci): producer budget follows its slimmed package; size checks name their real cause
* perf(engine): re-renders reuse the extracted frames of remote videos
A remote video is downloaded into the render's own work dir, so its path and
mtime are new on every render. The extraction cache keyed on both, so a
re-render of a composition with a remote video never hit the cache and ran
ffmpeg over the whole clip again. Key a downloaded source on the SHA-256 of
its bytes instead. Keys of local sources are unchanged.
* fix(engine): key the video copies a render writes itself by content
The producer downloads a remote video at compile time and copies it into the
render's compiled dir, so the extractor never sees the https src. Key any
source inside the compiled dir or the extractor's own output dir by content,
and skip the cache for one that cannot be read.
* perf(engine): hash a render-written video only when its cache lookup runs
Distributed planning copies the whole project into the compiled dir and defers
long video extractions, which never look up the cache. Hash render-written
sources just before the lookup, once per file, so deferred ranges and repeated
sources are not hashed.
* fix(engine): cache only downloaded media by content, not distributed project copies
A distributed plan copies the whole project into the compiled dir, so keying
everything there by content would hash every project video on the planner.
Content-key the extractor's own downloads and the dirs the caller names; the
producer names its remote media dir. Hashing stops on abort, and a source
with no hash skips the cache.
* style(engine): keep the extraction cache's comment share at its base
* test(engine): pin no hashing with the cache off and the producer's remote-media dir
* test(engine): run the cache-off case through the shared render helper
* fix(cli): list valid families when media-treatment gets an unknown capability
* test(cli): the capability list test typechecks under strict index access
* fix(cli): the unknown capability error calls its list areas and claims only what holds
* fix(cli): the unknown capability error lists only the areas it accepts
* fix(producer): the npm package ships only producer's own code, without source maps
* fix(cli): the npm package leaves out Studio's source maps, like its own
* fix(producer): the published package finds its workers and pins its own packages exactly
* fix(examples): the k8s chunk-runner image installs and loads the producer again
* fix(examples): the k8s chunk-runner image builds the packages Node resolves through dist
* fix(examples): k8s image keeps bun to run the producer, as the Cloud Run image does
* docs(examples): k8s image size matches a clean build
* fix(examples): k8s image builds only core, the one package bun cannot run from source
* docs(examples): k8s image size matches the core-only build
* fix(examples): k8s image renders video and CJK like the Cloud Run image, without test fixtures
* docs(examples): k8s image size with the full font set
* fix(studio-server): the public proxy cache path names boxed preview copies too
* fix(studio-server): keep the proxy cache path docs within the comment budget
* fix(cli): keyframes --shot on a compositions/ file mounts the scene in its project
* refactor(core): render and the bundler share one template-entry check
* fix(core): a scene's standalone page keeps the index's body library scripts
* fix(skills): skill scripts run when the skills dir is a symlink
* test(skills): plugin launcher fixture ships the shared main-module helper like an install
* fix(skills): the CLI's cube validator runs through a symlink too, and the guard check is stricter
* docs(skills): long agent-started renders run detached in their own process group
* docs(cli): detached renders start in their own process group, on macOS too
* docs(cli): the detached render recipe never waits on terminal input
* feat(studio): export can encode on the GPU, like render --gpu
* test(studio): the 4K export assertion carries the GPU flag
* refactor(studio): the GPU flag needs no comment beyond its name
* fix(studio-server): only MP4 exports encode on the GPU, and render errors report it
* fix(studio): the disabled GPU option dims like the other export controls
* fix(runtime): graded and snapshotted pictures stay readable in sandboxed players
* refactor(shader-transitions): keep the picture cache private
* fix(runtime): drop the snapshot picture cache, html2canvas cannot run in a sandboxed page
* fix(runtime): a CORS copy redraws every grading waiting on it
* fix(runtime): a loading CORS copy redraws each waiting grading once
* fix(engine): long exports with many clips no longer stall at 90% or hide a timeout
* fix(engine): stop queued frame extractions on cancel and time out distributed assembly
* refactor(engine): simplify the extraction slot check and its concurrency test
* test(engine): prove a cancelled extraction leaves the queue, skip the shell shim on Windows
* test(engine): wait for the held extraction's own record before cancelling the queued one
* fix(studio): a stalled font or asset no longer leaves the preview empty or drops reloads
* fix(studio): a page's own late load no longer counts as replaced content
* refactor(studio): one announcement owns when a preview page has loaded
* fix(studio): let hosts with their own player announce a new preview page
* fix(studio): a late ready from the replaced preview page no longer claims the new page
* refactor(studio): keep the Player doc comment on Player
* fix(studio-server): a failed save reports its real error when a later file was never written
* refactor(studio-server): share the file writer type and harden rollback test cleanup
* fix(cli): check passes a still title card whose timeline follows the seek
* fix(cli): check warns on a still frame and fails only when an animation is stuck
* fix(cli): count a seek clock once per sample and point the error at the registered timeline
* fix(cli): judge a finished animation by its own completion state, not its end time
* test(cli): pin a Web Animation paused at its end as finished
* fix(cli): judge a reversed animation's end in its own direction, and read plain timelines
* test(cli): pin a plain timeline held at its end as finished
* test(cli): keep an unfinished plain timeline beside the finished one
* fix(cli): skip a timeline whose time cannot be read instead of calling it stuck
* fix(cli): skip an animation whose time is not a plain number, such as a scroll-driven one
* fix(cli): a partial timeline with plain values no longer stops the browser checks
* fix(cli): snapshot, check, layout and thumbnails honour software WebGPU like render
* test(cli): stub the local WebGPU helper in the studio server tests
* fix(engine): webgpu compositions are recognised after the bundled runtime script
* fix(engine): a hung GPU probe falls back to software in 15 s instead of 120 s
* fix(engine): the GPU probe keeps the configured launch timeout and bounds only its page
* build(parsers): declare the html-attribute-spans subpath in its descriptor
* build(gcp-cloud-run): the BeginFrame contract stage copies parsers, which the engine now imports
* test(cli): the screenshot launch pin follows the shared local WebGPU helper
* fix(engine): the GPU probe's wait for Chrome's first page falls inside its 15 s limit
* fix(player): render the preview at its shown size so heavy compositions stop dropping layers
* test(player): check a small preview rasters its will-change layers at the shown size
* fix(player): accept device-pixel snapping in the zoom probe
* fix(player): probe the initial frame and preserve editing coordinates
* fix(player): defer every initial source reload until setup
* fix(studio): convert measured frame coordinates once
* test(studio): bank reduced preview opening work
* fix(core): keep centered layers exact when the preview is zoomed
GSAP infers a -50% CSS translate from the rendered pixel matrix. At a
fractional preview zoom that matrix is snapped, so a centered layer lost
its percentage and shifted by half its height after reload, render and
redo. The runtime now restores the authored percentage before GSAP's
first transform parse. Also restores the original thumbnail ceilings.
* test(studio): bank the two resize cases that now pass edit accuracy
resize-scale-px-r30-{root,nested}-z50-after measured 0.53 px tracking on
main and 0.49 px here. Also drops a comment line the runtime name covers.
* fix(core): keep stylesheet-centered layers exact under preview zoom
The centering repair now also reads percentages from a stylesheet
transform (the common translate(-50%, -50%) pattern), runs for every
property that makes GSAP parse a transform (transformOrigin first, too),
resolves against the border box, and leaves elements without a layout
box alone instead of throwing. The browser check now runs zoomed.
* fix(core): restore only centering, the one percentage GSAP infers
GSAP folds every other CSS percentage translate into pixels, and
compositions rely on that (a translateX(-100%) title tweened to x: 0
slides in). The repair now gives back only a -50% that zoom snapping
lost, and treats a size that is not in px (a hidden element sized in
percent) as no box.
* fix(core): restore centering only where GSAP would infer it
A pixel part in the translate means GSAP never infers -50%, so the
repair leaves it alone, and a layer without a layout box is left to
GSAP whatever size its computed style reports (that differs by Chrome
build for hidden percent-sized layers).
* fix(player): fit the preview before the composition starts loading
The zoom was applied on the first resize callback, after the source was
assigned, so a fast-loading composition could run its scripts and lay
out unzoomed and then reflow. Fitting on connect, before any source,
makes the first layout use the preview zoom.
* test(player): pin the first fit before the composition source
* revert(player): drop the zoom fit so the preview keeps the export's layout
CSS zoom shaped text at the zoomed size, so paragraph heights in the
preview differed from the render by up to a line. The transform fit
stays; the centering adapter and zoom-only bench changes go with it.
* fix(core): raster a small preview at the size it is shown
Chromium never rasters a will-change: transform layer below device
scale, so a preview shown at a quarter size rastered every hinted layer
at full size and could run out of tile memory, dropping layers. While
the player shows the composition below 1x, the runtime swaps the hint
for an identity filter, which keeps its stacking context and
containing block; preserve-3d containers keep the hint.
* fix(core): keep a small preview's raster swap out of filters edits can save
The identity filter that replaced will-change: transform showed up in computed filter, so
Studio's blur slider saved it, GSAP filter tweens and clearProps picked it up, and it cut
backdrop-filter off from what is behind it. A far perspective keeps the same stacking context
and containing block, is never composited for flat content, and nothing reads or writes it.
Also: the runtime guard lint (realm-safe element checks), a class change that drops the hint
undoes the swap, and the browser check measures raster scale with the swap off and on at one
shown size and compares frosted glass and 3D pixels.
* fix(core): drop preview raster hints only where nothing depends on them
The perspective that stood in for will-change: transform could still reach a saved project:
Studio records perspective keyframes from GSAP's computed value, and copying a generated
element serialised its inline styles. It also went stale when a parent class or a later
stylesheet changed the element.
Now the runtime writes no inline style. It marks a hinted layer with a preview attribute
and one injected rule sets its will-change to auto. Only layers whose hint changes nothing
are marked: positioned, with no fixed descendants, and no z-indexed or blending descendants
unless the layer has its own z-index. Every class or tree change re-checks the whole page.
Studio strips the mark from copied markup, as it does the other preview marks.
* fix(core): keep raster hints that pseudo-elements, other hints or inline styles need
A layer's ::before or ::after can sit behind it, blend with it or be fixed to it, so those count
like children. A layer that also hints opacity or filter keeps every hint, since those make their
own boundaries. Inline style changes, which scripts make every frame, are watched cheaply: they
only give the hint back to the layers holding an element that now depends on it, or to a layer
that turned static or changed its z-index. Text changes no longer trigger a full pass; a new
stylesheet still does.
* fix(core): re-read a marked layer's own hints and follow any attribute or late sheet
A marked layer now has its mark lifted while its hints are read, so a class or inline value
that adds opacity or filter gives every hint back. Any attribute change re-checks its subtree,
so attribute selectors are followed, and a linked stylesheet re-runs the pass once it loads.
* perf(core): only lift a raster mark on the element that changed
Lifting a mark to read a layer's own hints repaints it, and a change on a scene container lifted
every marked layer under it (about 6 ms and a re-raster per event). Now only the changed element
is lifted, and a full pass clears all marks at once so the page restyles a single time. Tests
cover leaving marked layers alone, ignoring our own marks, and the linked-sheet load pass.
* fix(core): decide raster marks before writing them in a full pass
A full pass re-marked layers one at a time, so each read restyled the page again. Every mark is
now decided first and written after. The browser check holds off the player's own scale
messages while it turns the swap off and on, since a late resize tick could turn it back on.
* test(player): hold the player's own scale while the raster check turns the swap off
Turning the swap off restyles the page, and the player answers by resending its real scale,
which turned the swap back on within milliseconds, so the off half compared the swapped page
with itself. The check now holds the player's sends on the host page, asserts the swap is off
before the native shots, and removes the layers that keep their hint before either trace.
* test(player): give the raster check's 3D probe a solid fill
Stripes a few pixels wide alias differently at each raster scale, so the probe measured texture
resampling rather than the 3D shape it is there for. A solid fill keeps the shape and position.
* fix(studio): keep the preview raster mark out of stacking and saved text edits
Studio's stacking model read a marked layer's will-change as auto, so a timeline drag could
write a z-index that does nothing in the render; a marked element now still counts as a stacking
context. A text edit copied every live attribute but style, so it could save the mark; the
preview-only attributes are now one list, used by both the copy and the text-edit paths.
* fix(core): keep a marked video through a scene swap
The runtime keeps a video across a scene swap only when its live attributes match the fresh
import, and the preview raster mark made them differ, so a hinted video in a small preview was
rebuilt on every edit. The comparison now ignores every preview-only attribute, which also
fixes the same rebuild for data-hf-upcoming. The shared list is renamed PREVIEW_ONLY_ATTRS, and
the lazy-image strip in copied markup gets a test.
* test(engine): real-ffmpeg HLS tests get the 30 s budget other real-ffmpeg tests use
* test(engine): real-ffmpeg fixture cleanup gets the 30 s its setup already has
* feat(cli): let transcribe --to write srt or vtt straight from a media file
* fix(cli): fail a missing transcribe --output folder before decoding
* fix(cli): reject a transcribe --output that names a folder
* test(cli): check CJK caption grouping on the parsed cues
* fix(cli): keep transcribe --output from overwriting the media or its transcript
- Refuse an --output that resolves to the input file or the transcript.json the run writes,
before the engine starts.
- When the caption file cannot be written after transcribing, say the transcript was saved
and name the caption path and reason, instead of reporting a failed transcription.
- Docs: a one-run export groups cues for languages without spaces; exporting the saved
transcript later may split them differently.
* fix(cli): refuse caption paths that alias the media or transcript
- The overwrite check compares files, not path text: an existing target is matched by device
and inode, a new one by its real folder and its name ignoring letter case. Links, folder
aliases such as /var and /private/var, and other letter case are all refused.
- The check also covers the default caption path, so exporting transcript.srt to srt no
longer rewrites its own input.
- A trailing -o with no path fails before transcribing.
- One constant names transcript.json for the engines, the import and the check.
* fix(cli): refuse caption links to the transcript before it exists
- A caption path that is a link is followed to where the write would land, so a link to the
transcript.json the run is about to create is refused before transcribing.
- A test pins the folder letter-case check on a case-insensitive disk, and says which branch ran.
* fix(cli): check the caption file against the transcript right before writing it
- Right before the caption write, by when the transcript exists, a destination that is the
same file as the input or transcript.json is refused. The OS resolves every link, relative
link and alias, so the hand-written link following is gone.
- The run keeps the transcript and says the caption file could not be written and why.
An export whose caption write fails now says so too, instead of crashing.
- The check before transcribing stays as an early refusal for the common cases.
* fix(cli): compare caption paths by name when the disk reports no inode
- Some network shares report inode 0 for every file; such a pair is compared by folder and
name instead of being called the same file. The check before transcribing and the one at
write time now share one comparison.
- The link-through-a-file tests accept ENOENT as well as ENOTDIR, the code Windows reports.
* fix(cli): resolve both caption paths fully when the disk reports inode 0
- When either file reports inode 0 and both exist, compare their fully resolved real paths,
so a link to the media or the transcript is still refused. The folder and name compare
stays for a path that does not exist yet.
- Tests zero the inode on every path, on the caption path only, or on the protected file only.
* test(cli): say plainly why the caption-write test accepts two error codes
* fix(studio): the timeline viewport gate gives the same verdict on the same code
Steps are timed from the frame the jump is made in, so each is a whole number of frames and the
3.5-frame budget no longer cuts through one cluster of samples. When the head still misses a budget,
it is measured against its base in alternating blocks on the same runner and fails only when it
misses on more steps than the base beyond chance.
* style(studio): format the viewport gate verdict tests
* fix(studio): a head slower than its base fails the viewport gate comparison
* fix(studio): the viewport gate opens head and base fresh before comparing them
* fix(studio): each viewport gate comparison block runs alone in a fresh Chrome
* fix(studio): the viewport gate comparison also fails a head that makes late steps later
* fix(studio): the viewport gate summary names every count behind a comparison verdict
* fix(studio): label the viewport gate frame-gap counts by threshold
* fix(studio): a runner stall cannot fail identical builds in the viewport gate comparison
* fix(studio): the viewport gate serves its base the same projects as the head
* fix(ci): keep the catalog publish PR when main changes nothing it generates
The bot compared the whole branch tree with main, so every main push rewrote
the standing PR and dismissed its approval. It now compares only generated
catalog files, with search vectors judged by the drift check's cosine rule.
* fix(ci): republish when main edits generated files or the branch carries others
* docs(registry): motion-blur copies explain their inline styles in three lines
* refactor(ci): split the kept-snapshot check into named conditions
* fix(engine): recover audio duration from packet timestamps before clamping
An authored `data-duration` on an <audio> element could be silently
shortened when a source file's container-summary duration (mvhd/tkhd/mdhd)
undercounts the real audio length while the packet stream itself is
intact. Add `probeAudioDurationFromPackets()`, which re-derives the true
duration from the last packet's own pts_time + duration_time — figures
ffprobe computes from the stream's own timestamps, not the container's
summary header — and wire it into the compiler's existing clamp check as a
rescue attempt before accepting a shorter value. Works regardless of
codec/profile; verified against real HE-AAC/SBR fixtures and a
binary-patched "lying container" MP4 built for the regression test.
The rescue only fires for candidates the existing clamp predicate already
flagged (no added cost on the common path), runs in parallel across
candidates rather than serially, and requires the recovered duration to
exceed the existing clamp epsilon (absorbing the few milliseconds of
priming-delay drift raw packet timestamps carry relative to an
edit-list-corrected container duration) before overriding the shorter
value.
Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>
* fix(engine): move audio duration correction into extractAudioMetadata
The previous approach compared the compiler's own packet-scan probe
against the already-corrected duration returned by extractAudioMetadata,
which meant the correction only applied to one caller and the regression
fixture happened to exercise a pre-existing AAC-LC-specific refinement
instead of the new code path.
Move the fix to the single canonical place duration is derived: replace
the old AAC-LC-only packet-count refinement (a profile allowlist assuming
a fixed 1024-samples-per-frame constant) with a codec-agnostic mechanism
that decodes the final audio frame and reads its own timestamp plus real
sample count. This has no per-codec assumption, so it applies uniformly
regardless of codec or profile, and every caller of extractAudioMetadata
benefits automatically. The compiler's own clamp logic is now unchanged
from its pre-existing form.
Verified against a real, previously-untouched case: a FLAC-in-MP4 file
(a codec the old AAC-LC-only path never corrected) with its mvhd/tkhd/mdhd
duration atoms binary-patched to half their true value while every real
frame stays intact. Confirmed this reproduces on the prior code (by
literally substituting its actual content) and is fixed by the new code.
The decode probe reads CSV output (each line stands alone) rather than
JSON (a single top-level array), and retains only the output tail under a
small cap — a lying container's true duration can be arbitrarily larger
than its declared one, and JSON truncated from the front isn't valid JSON,
so an unbounded scan of a long file silently fell back to the wrong
duration once ffprobe's stdout cap was hit.
Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>
* test(producer): update style-7-prod golden for corrected AAC duration probe
The deleted AAC-LC packet-count refinement assumed every demuxed packet
decodes to exactly 1024 samples. For this suite's real audio fixture
(a 48kHz stereo AAC-LC MP4), that assumption overcounts: ffprobe reports
753 demuxed packets, but only 752 of them actually decode into a real
audio frame (verified via raw PCM sample count: 770048 samples / 48000Hz
= 16.0426666...s). The old mechanism's 753 * 1024 / 48000 = 16.064s was
therefore wrong; the new decode-based probe correctly derives ~16.043s
from the real final frame.
Regression-shards caught this as a compilation mismatch on the previous
commit. Verified the corrected golden against the real source: full
compilation, visual (0 failed frames), and audio (correlation 0.966)
checks all pass locally with the actual LFS-hosted golden video, and a
standalone compileForRender() check confirms all other audio-bearing
fixture suites in the repo are unaffected.
Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>
* perf(engine): seek the audio decode probe instead of scanning the whole file
probeDecodedAudioDuration ran a full, single-threaded decode of the
entire audio stream on every extractAudioMetadata call (once per audio
element in the HTML compiler, plus audio mixing/padding/encoding
steps). On real 30-minute files this took over a second, and could
approach ffprobe's 30s deadline on multi-hour files while holding a
shared probe slot the whole time.
Add -read_intervals so the probe seeks to ~1 second before the
container's already-known claimed duration and decodes only that
tail. This is safe because the correction only ever raises the
duration: an honest or over-claiming container's seek lands at or past
the real end and finds nothing extra, while an under-claiming
container (the only case this exists to fix) still has real frames
past the seek point. If the tail read finds nothing at all, fall back
to a full unseeked decode before giving up, protecting files whose
seek index is unreliable (an index-less or non-seekably-sourced
container) from silently missing a real correction — mirroring the
existing seek-then-fallback pattern already used by the sibling
final-video-frame probe in this file.
Also replaces the real-file regression test's runtime ffmpeg-spawning
fixture generation with two small, committed binary fixtures (an
honest FLAC-in-MP4 file and a copy with its container duration atoms
halved) plus the ffprobe-static package, so this test's real-file
proof actually runs in CI instead of being silently skipped when no
system ffmpeg is on PATH.
Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>
* refactor(engine): trim the audio duration probe comments to the invariant
* test(engine): cache tests queue the decode probe and count metadata probes only
* test(engine): probe for ffprobe with a literal argv so the argv contract classifies it
* test(producer): regenerate the speed-ramp golden for the single-encode mix
The audio probe now reads the mixed AAC as exactly 4.000 s instead of the
packet-count 4.032 s (which counted the priming frame), so the final mix
is stream-copied instead of re-encoded once more. Same waveform (sample
correlation 0.9996 vs the old golden), 3.1 dB less true-peak attenuation;
video frames are byte-identical.
* fix(engine): measure decoded audio from the stream start and trust it for raw ADTS
The decoded last-frame end is an absolute timestamp, so subtract the audio stream's start time
(format start as fallback) before comparing it with the start-relative container duration, and
start the tail read at start + duration - 1 s. MPEG-TS audio (1.4 s default start) and offset
MP4s were over-extended by their start time.
Raw ADTS (format aac) has no duration field; ffprobe estimates it from the opening bitrate and
overclaims after a quiet opening. Its decoded timestamps are sample-counted, so for raw ADTS the
decoded end now wins in both directions beyond the margin. Other containers stay upward-only so
an MP4 edit list is never extended.
---------
Co-authored-by: Miguel Ángel <miguel.sierra@heygen.com>
* fix(cli): reject a swallowed --json when catalog's string flags have no value
catalog --query --json (missing --query value) parsed as query="--json",
json=false, since citty's parser (node:util.parseArgs, strict: false)
unconditionally consumes the next token as a string arg's value with no
guard against it being another flag -- JSON-mode consumers silently got
human-readable stdout instead of a clear error.
Added an opt-in rejectSwallowedFlagValues() check (packages/cli/src/utils/
reject-unknown-flags.ts), called from catalog's own run() for its
query/type/tag string args. Kept it opt-in rather than wiring it into the
global assertKnownFlags pre-parse gate every command goes through: check.ts's
--frame-check is a string flag that's documented and tested to work bare or
immediately followed by another flag, handled by that command's own raw-args
preprocessing before citty parses it -- a blanket pre-parse check can't tell
that case apart from this bug, so review caught it as a real regression
before it shipped.
Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>
* fix(cli): unify swallowed-flag-value handling into one raw-args gate
catalog --query --json (round 1's fix) turned out to be one instance of a
codebase-wide gap: any command with a type:"string"|"enum" flag followed by
--json (or any other declared flag) has its value swallowed by citty's parser
(node:util.parseArgs, strict: false unconditionally consumes the next token),
confirmed still reproducing on check --layout --json. Round 1's post-parse,
catalog-only check also duplicated check.ts's own existing --frame-check
raw-args mechanism instead of replacing it, and couldn't distinguish the
always-legitimate --query=--json (equals form) from the actual --query --json
swallow, since node:util.parseArgs parses both to the same object.
Replaced with a single raw-args scan (guardSwallowedFlagValues), wired into
the global wrapCommand gate next to assertKnownFlags so every command is
covered. Default: throw CliUsageError. Two narrow per-command opt-outs where a
command already has its own bespoke handling for this exact bug shape:
check's --frame-check (rewritten to --flag=, folding in and removing check.ts's
own normalizeFrameCheckRawArgs/swallowedOptionError) and upgrade's --project
(left untouched, since it already recovers the swallowed value itself). A
third, previously-undiscovered collision surfaced during testing: init.ts had
its own bespoke --example dash-value guard that the new global gate now
preempts; folded that in too and updated its one affected test's expectation.
Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>
* fix(cli): stop the swallowed-flag usage error from leaking to stdout
Round 2's guardSwallowedFlagValues threw CliUsageError without
presented:true, the first non-presented CliUsageError construction in the
CLI -- executeCli's dead stdout-usage-dump branch (every other CliUsageError
goes through failUsage(), which always sets presented:true) fired for the
first time, leaking 1.4-5.7KB of ANSI usage text onto stdout on top of the
correct stderr message, breaking --json callers' clean-stdout contract on
exactly the class of error this ticket exists to fix.
Split into two functions instead of one, since the two throw sites have
genuinely different reach: throwSwallowedFlagError (used by
guardSwallowedFlagValues, thrown before any command's own run() executes)
prints the message itself and sets presented:true, matching every other
print-then-failUsage() usage-error site in this codebase. swallowedFlagUsageError
(used by check.ts's parseFrameCheck) is a plain, side-effect-free CliUsageError
factory, because that throw is always caught by check.ts's own run() try/catch,
which already prints and presents every error uniformly -- using the printing
variant there instead produced a real, verified regression (a doubled stderr
line in non-JSON mode, an extra stderr line even in --json mode), caught by
adversarial review before it shipped.
Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>
* test(cli): assert literal stdout bytes stay empty for the swallowed-flag error
The prior test for this only asserted the internal presented:true flag, with
a comment noting the actual 0-byte-stdout behavior was checked by hand
against the built CLI. Added an automated spawn-based test (same pattern as
init.test.ts's runInit) that runs the real CLI and asserts stdout is
literally empty, not just that the presented mechanism is engaged.
Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>
* refactor(cli): split the swallow guard into small helpers to clear the audit gate
Moves the leaf flag checks out of the wrapCommand run arrow, drops ignored args
from the owner map, and pulls the per-token decision out of the guard loop.
Trims two comments to keep check.ts under its comment share. No behaviour change.
* fix(cli): swallow guard hints a value and lets --no- negations through
* fix(cli): swallow guard looks past --no- negations that citty drops
---------
Co-authored-by: Miguel Ángel <miguel.sierra@heygen.com>
* fix(core): a data script in a sub-composition no longer stops every timeline
A sub-composition's <script type="application/json"> was wrapped and run as
JavaScript, and because the bundle merges every composition script into one,
its parse error stopped every scene's timeline. Data scripts now stay in the
DOM as authored, and a script run that does not parse is left unmerged so a
bad script fails alone.
* fix(core): render and preview keep a broken composition script from stopping the rest
The render path's script merge had the same gap as the bundler: one script
that does not parse stopped every timeline. Both now share one parse check.
A run left unmerged, and every scene-part script, is still escaped, so a
string holding "</script>" can no longer end the script early in preview.
* refactor(core): carry the bundler's script-merge reasons in names, not comments
* fix(core): every composition path runs only the scripts a browser would
A script check now matches the browser (esbuild accepted export and top-level
await), so such a script can no longer stop every timeline. Inline template
compositions keep data scripts and run module and import map scripts as such.
A data script beside the composition root is mounted next to it, a nomodule
script never runs, and the render path merges scripts on a page with no head.
* fix(core): keep inline-template data scripts and run a script with a top-level return alone
- parsesAsScript compiles with vm.Script, so a top-level return or new.target
no longer passes as mergeable and stops every timeline.
- The bundler's inline <template id="X-template"> path asks the shared
assembly plan for its root and mounts the inert scripts authored beside it.
- nomodule only stops classic scripts; type="module" nomodule runs, as in
browsers.
* refactor(core): the inline template path reads its root id from the shared assembly plan
* fix(core): a broken composition script stays apart under Bun as well as Node
parsesAsScript now parses with acorn in script mode instead of vm.Script.
Bun 1.3's vm.Script compiles lazily and accepted any text, so the Studio dev
server merged a broken script with the rest and every timeline stopped.
acorn is already locked for parsers and lint; core now declares it.
* test(core): name the parse-check test for what it pins
* style(core): wrap the data-block comment under the line limit
* fix(lint): check passes valid sub-compositions and scene-relative asset paths
* fix(lint): keep the browser lint build free of node modules
* refactor(lint): tidy sub-composition lint helpers and guard bare node imports
* fix(lint): resolve stylesheet asset paths from the stylesheet's own folder
* fix(lint): catch every written form of a path that climbs out of the project
* fix(parsers): sub-composition asset paths written with backslashes load in preview
* fix(parsers): an encoded backslash stays in the file name and a leading backslash stays absolute
* fix(lint): an encoded %2f counts as a separator when checking for a climb out of the project
* fix(cli): renders on Windows stop cancelling when an old parent's pid is reused
* test(cli): a Windows parent created in the same tick as its child stays an ancestor
* fix(studio): a resized corner stays on the pointer when the size rounds to whole pixels
Resized sizes stay on whole CSS pixels (GSAP centres a -50% translate from the
integer offset size), so the centre-anchored resize left the grabbed corner up to
a third of a pixel times the element's scale off the pointer: 0.53 px on a 1.5x
scaled layer. The centre pin now takes half the rounding remainder along the
element's rendered edges, so the grabbed corner lands where the wanted size puts
it while the written size stays whole.
* fix(studio): a scale resize saves the box exactly where it was dropped
finalizeScaleResizeCommit skipped its position correction whenever the box sat
within 0.5 px of the drop point on each axis, so a sub-pixel drop (now the
norm, with the grabbed corner on the pointer) saved up to half a pixel off.
It now skips only when the correction rounds to nothing at the precision the
file is written in.
* fix(studio): a scale resize lands centred on the box that was dropped
finalizeScaleResizeCommit lined the committed box up with the drop by its
top-left corner. When one scale cannot reproduce the dragged width and height
(the draft rounds each to whole pixels), that put the whole gap on the far
edges, up to half a pixel. The resize is centre-anchored, so it now lines up
centres and the gap splits evenly.
* chore(studio): keep the complexity note on the resize intercept, not the new helper
* test(studio): bank the two scaled resize cases that now pass the edit accuracy bench
* fix(studio): a scale resize leaves animated positions alone and mirrored corners track
* test(studio): bank only the two newly passing scaled resize cases
* fix(studio): a mirrored or parent-rotated layer's resize corner tracks the pointer
* fix(studio): a resize corner on a skewed layer picks its side from the box's own edges
* fix(studio): resizing a layer that renders with no area moves nothing
* fix(cli): name the unzip errors when every Windows unzip tool fails
* fix(cli): a cached empty or folder Chrome counts as missing, not found
* fix(engine): skip an empty cached Chrome the same way the CLI does
* fix(engine): keep scanning the Chrome cache past a build it cannot read
* test(engine): a folder at the cached Chrome path is skipped
* fix(studio-server): the preview's proxy copy jumps queued thumbnails, and abandoned copies drop
* fix(studio-server): a re-ask right after a dropped proxy copy gets a fresh copy
* fix(studio-server): leave Studio's preview route on the normal proxy queue
* docs(studio-server): shorten the proxy transcoder's detachment note
* fix(studio-server): a refused proxy copy still invalidates thumbnail captures
* fix(catalog): compare search vectors by direction so the publish PR can pass
* test(catalog): pin the vector tolerance between machine noise and different items
* refactor(catalog): split the per-row cosine out of the vector comparison
* fix(cli): preserve subtitle cues across line endings
* refactor(cli): preserve newline handling while reconciling subtitle tests
* refactor(cli): normalize WebVTT line endings at the parser
* style(cli): format the retained subtitle test block
* docs: clarify async font measurement and timeline registration
* chore: align skill manifest with main before regeneration
* chore: regenerate animation skill manifest
* fix(studio): clip strips resize on the next frame, ending ResizeObserver loop errors
* test(studio): verify strip resize frame scheduling deterministically
* fix(studio): a menu set to render inline opens beside its trigger
* fix(studio): a popover set to render inline opens beside its trigger
* fix(studio): a remounted clip strip keeps its own size instead of a queued one
* test(studio): zoom thumbnail tests run resize frames on fake timers
* test(studio): zoom preview test runs the resize frame it guards
* fix(core): preview stops at the film's end when a scene loops forever
* refactor(core): the loop length threshold lives with the composition length
* test(core): pin the endless-loop length at the boundary and through the runtime
* style(core): keep composition length comments under the file's share
* refactor(studio): preview duration guard reads the core loop length limit
* docs(core): length doc says a loop yields only to a floor or fallback
* perf(engine): wait for a missing composition timeline once per render, not once per browser
A composition host that never registers a timeline (CSS, canvas or rAF animation
without data-no-timeline) made every capture session of a render wait the full
player-ready timeout: calibration, then the workers, then each static-frame check
page. The first session that times out now records the host ids in a memo shared
by the render's sessions; later sessions report the same timeout warning without
waiting again.
* perf(engine): the static-frame check page stops on a failed script and chunks share one memo
The verification page now gets the session's failed-script list, so it bails after
the short grace like the main page instead of waiting the full timeout. Distributed
chunks share one timeline-wait memo across their sessions. The poll takes an
options object instead of eight positional parameters.
* fix(engine): replay only a clean timeline timeout so a script failure still fails the render
A session that skipped the wait classified it at once, before a late page error
could arrive, so a render that used to stop on a script failure could ship. The
memo is now written only by a wait that ran its full length with no page errors
and no failed script loads; a replaying session that already sees a failed script
load reports a script failure.
* fix(cli): browser ensure fails when the unzip leaves no Chrome executable
* refactor(cli): keep install debug output and report only the last unzip attempt
* fix(cli): browser ensure exits after a failure or a --force download
* fix(cli): browser checks name why Chrome could not be installed
* fix(cli): render shows why its setup step failed instead of a crash dump
* refactor(cli): build the browser download label and staged test path once
* refactor(cli): one owner for the render setup result line
* fix(cli): render setup failures report through one error line
* refactor(cli): one reader and writer for both render setup lines
* feat(registry): eight more WebGPU shader backgrounds and a bundle with thirty new shaders
* refactor(registry): simpler bundle copy step in the shader build
* test(registry): every shader block ships the same bundle and names a shader in it
* refactor(registry): one block loader for the shader block tests
* test(registry): name the stale block and match only shader names
* feat(registry): eight more WebGPU shader backgrounds, from blob to fractal noise
* chore(registry): shorter licence line at the top of the shader bundle
* chore(registry): bring in the latest shader bundle branch
* chore(registry): shorter licence line at the top of the shader bundle
* test(registry): every shader block installs the bundle's licences
Miguel Ángel