check gave a scene 3 s to signal it was ready, then warned "checking the current page
state" and sampled whatever was on screen. Scenes that build procedural textures or
WebGL canvases routinely need longer, so a pass could miss late content with a warning
nobody could act on. The default wait is now 10 s (it ends the moment the page is
ready), the warning says the scene may still be building and to raise --timeout, and
check_report records render_ready_timed_out so the cases can be counted.
* fix(cli): a check or snapshot that times out says which step it was on
check's idle deadline named only the phase ("while checking samples") and snapshot's
CDP timeout named nothing. check now adds the sample, craft frame or overlap probe it
was on, and snapshot adds the seek or capture of the frame it was on, with its time.
* fix(cli): a snapshot timeout no longer tells the user to raise a setting they do not have
Puppeteer's protocol timeout message ends "Increase the 'protocolTimeout' setting in
launch/connect calls". snapshot has no such option, so the step it was on is now the
last thing the message says.
* feat(cli): check reports where its seek loop spends its time
check_report carried one seek_loop_ms, which lumps the layout grid, the craft pass
(up to 600 frames) and the overlap pass with its hold probes. It now also carries
grid_ms, craft_ms, overlap_ms and composition_s, so a slow check can be tied to a
pass. Nothing about what check does or prints changes.
* chore(cli): drop the pass-timings doc comment so the comment share does not rise
* fix(cli): check stops making video copies after 10 minutes, and --timeout takes units
The copy phase of check had no overall limit: a source that kept moving was never
stopped, and stdout stays silent the whole time. It now ends after 10 minutes with
an error naming the files still unfinished and the elapsed seconds; finished copies
are reused on the next run. The stderr progress lines are unchanged.
--timeout on check and snapshot is milliseconds, so "--timeout 45" waited 45 ms.
It now accepts 45s, 2m and 45000ms, and a bare number under 1000 warns on stderr
that it is milliseconds. Output on stdout is unchanged.
* chore(cli): cut the --timeout parser comment to the comment limit
* fix(cli): drop the 10 minute wall clock on check's video copies
A copy that keeps making progress must not be cut by a clock, and a re-run would
only start it over. The copy already ends when ffmpeg stops reporting progress
for 3 minutes (finished pieces are kept for the next run), so the phase is
bounded on no progress. The --timeout warning now names the value actually used
when check raises a small value to its 500 ms floor.
* fix(cli): take JSON flags from a file or stdin so PowerShell can pass them
* fix(cli): read BOM-prefixed and UTF-16 JSON from a file or stdin
* style(cli): format the JSON flag reader
* test(cli): feed the bytes PowerShell pipes to the JSON reader
* style(cli): shorten the JSON flag reader's comments
* style(cli): one line for the JSON flag reader's comment
render, check and snapshot open project history, which looks for a running
preview by probing 100 loopback ports and 5190. Behind an egress fence every
probe is refused and reported. Setting HYPERFRAMES_NO_PREVIEW_DISCOVERY=1 makes
historyDeps.findServer return null without a request, so history opens directly.
Refs #6204
* fix(cli): history show --diff works without git on PATH
* fix(cli): unifiedDiff passes lint and fallow: blocks, shared direction rule, split test
* refactor(cli): split the diff walk and its backtrack into small steps
* feat(engine): encoders cap peak bitrate and place keyframes on a set interval
* style(engine): shorten the rate-cap comment
* style(engine): drop the doc lines the comment ratchet flagged
* feat(producer): mp4 renders honour a keyframe interval and a peak bitrate cap on every encoder path
* style(producer): shorten the delivery encoder file headers
* style(producer): drop a comment line from the segment manifest
* style(producer): shorten the integration test header
* test: delivery encoder tests follow the ffprobe argv contract and run in the integration lane
* feat: the render request, server and Lambda plan carry the keyframe interval and peak bitrate cap
* fix(studio): the Studio render route passes the keyframe interval and bitrate cap to the encoder
* chore(studio-server): drop a comment the helper's name already says
* feat(cli): render and lambda render take --keyframe-interval, --max-bitrate and --buffer-size
* chore(cli): tag the studio download link with where it was shown
The terminal hint, hyperframes open and the browser editor button now add
src=cli or src=browser-editor to the download link. The download route
already records src, so these downloads stop landing in no source.
* chore(cli): drop the DownloadSource doc comment the type name already says
* chore(cli): leave the no-build fallback link untagged, since only the download route reads src
* fix(cli): Windows preview and catch-up records move to LOCALAPPDATA, a refused log no longer blocks
* fix(cli): a refused preview log falls back to the null device and drops the extra comments
* fix(cli): Windows catch-up record goes under LOCALAPPDATA/hyperframes like the other records
* fix(cli): the check and snapshot project lock works where hard links are refused
* refactor(cli): drop the project lock comment to fit the comment ratchet
* fix(render): a PNG's colour tags no longer change its pixels in preview, check, snapshot or render
* fix(render): the play and present server also serves a PNG without its colour tags
* fix(render): bundled pages inline a PNG without its colour tags too
* feat(cli): check catches audio the render would lose or play as silence
check gains an Audio section, read from the media list the render mixes:
- error: a clip's source has no audio the render can read (its mix fails,
the film ships without sound)
- warning: a clip starts past the end of its file, or the part it plays
is silent
- info: the film has no sound at all
The bundle and media list are now built once and shared with the HDR
inspection; the audio pass runs while the browser pass does.
Fixes#2775
* fix(cli): check reports an unreadable audio source the way render handles it
A source with no audio track is refused by render's own media-type rule, now exported from the producer and called by check; a source that does not decode as audio fails the mix and stops the render.
* perf(cli): check samples a long clip at a few spots before reading all of it for silence
Sound at any spot ends the decode; a clip is only called silent after its whole played part is read.
* chore(cli): drop a comment the shared finding helper's name already says
* feat(cli): hyperframes <dir> opens the project in the app
* refactor(cli): one command-word lookup and one rewritten command line for the folder shortcut
* refactor(cli): shorten the folder shortcut comments to fit the comment ratchet
* fix(cli): preserve UTF-8 across subprocess output chunks
* chore: prepare conflict resolution against current main
* fix(cli): retain UTF-8 output handling with current main
* chore: prepare conflict resolution against current main
* fix(cli): retain UTF-8 decoding with process teardown updates
* chore: prepare conflict resolution against current main
* fix(cli): preserve decoded subprocess progress on current main
* docs(cli): scope Unicode output guarantees to cancellable workers
* docs(cli): name commands with Unicode-safe diagnostics
* feat(cli): skipContrastInMotion moves to HF_TOOL_CONTEXT check-review
The --skip-contrast-in-motion flag and HYPERFRAMES_CHECK_SKIP_CONTRAST_IN_MOTION
env give way to a check-review capability in HF_TOOL_CONTEXT, so only a harness
turns it on. The skill text and manifest go back to main.
* feat(cli): check-review findingFrames saves one plain frame per finding time
With HF_TOOL_CONTEXT check-review.findingFrames, every error/warning finding in
layout or contrast with a real bbox gets frameTime (the middle sample of its
longest held run, by the heldMs gap rule) and frame (the absolute path of an
unannotated full frame shared by every finding at that time). One seek and
screenshot per distinct time, capped at 60 times with errors first, into the
run's snapshot folder; not listed in snapshots, history or events. Without the
capability, output is unchanged.
* docs(cli): finding-frame comments name the check-review capability, not a flag
* fix(cli): validate finding frame times and preserve cancellation
* fix(cli): count finding frame progress toward the check deadline
* feat(cli): check-review inspect attaches the inspector's report to each framed finding
With findingFrames on, the finding-frames page is served with the
inspector's GSAP hooks. After each frame is captured, every finding framed
at that time is inspected by its data-hf-id, else its selector, and the
inspector's own report is attached as the finding's inspect field. A failed
inspection becomes that finding's { error } and never fails the check.
Without the capability nothing changes.
Drops the unused @types/mime-types devDependency that the dependency audit
flags once packages/cli/package.json is touched.
* fix(cli): stop finding inspections after cancellation
* fix(cli): reject ambiguous finding inspection targets
* fix(ci): build inspector before Windows CLI smoke
* fix(cli): parse viewport HTML with explicit server parser
* feat(cli): skipContrastInMotion moves to HF_TOOL_CONTEXT check-review
The --skip-contrast-in-motion flag and HYPERFRAMES_CHECK_SKIP_CONTRAST_IN_MOTION
env give way to a check-review capability in HF_TOOL_CONTEXT, so only a harness
turns it on. The skill text and manifest go back to main.
* feat(cli): check-review findingFrames saves one plain frame per finding time
With HF_TOOL_CONTEXT check-review.findingFrames, every error/warning finding in
layout or contrast with a real bbox gets frameTime (the middle sample of its
longest held run, by the heldMs gap rule) and frame (the absolute path of an
unannotated full frame shared by every finding at that time). One seek and
screenshot per distinct time, capped at 60 times with errors first, into the
run's snapshot folder; not listed in snapshots, history or events. Without the
capability, output is unchanged.
* docs(cli): finding-frame comments name the check-review capability, not a flag
* fix(cli): validate finding frame times and preserve cancellation
* fix(cli): count finding frame progress toward the check deadline
* feat(cli): skipContrastInMotion moves to HF_TOOL_CONTEXT check-review
The --skip-contrast-in-motion flag and HYPERFRAMES_CHECK_SKIP_CONTRAST_IN_MOTION
env give way to a check-review capability in HF_TOOL_CONTEXT, so only a harness
turns it on. The skill text and manifest go back to main.
* fix(cli): satisfy comment ratchet for check capability
* feat(cli): opt-in check flag that leaves out contrast measured mid-animation
`hyperframes check --skip-contrast-in-motion`, or
HYPERFRAMES_CHECK_SKIP_CONTRAST_IN_MOTION=1, leaves out a contrast failure
measured while a GSAP tween on the text or an ancestor is running, or while
the text's cumulative opacity is below 1. Repeating tweens and tweens of 4 s
or longer (camera drifts) do not count as motion. Text no GSAP tween targets
is reported as before. With neither set, check is unchanged.
The motion state is read at the same contrast sample, with no extra seek or
screenshot.
* fix(cli): read contrast motion on current GSAP clocks
* fix(cli): keep infinite timeline motion ambient
* fix(cli): preserve quoted multiline .env values
applyDotEnv parsed .env content line by line: a quoted value's closing
quote was only ever looked for on the same physical line, so a value
like HYPERFRAMES_VERTEX_SERVICE_ACCOUNT='{...}' spread across several
lines got truncated to the leftover text on its opening line, and the
continuation lines were silently dropped (no "=" to parse as entries).
Join physical lines into logical ones before parsing: when a line
opens a quote that isn't closed on that same line, keep appending
following lines until one contains the closing quote character. This
matches how Node's util.parseEnv treats quoted multiline values.
Fixes#6075
* fix(cli): do not let a commented or unclosed quote swallow later .env lines
logicalLines looked for an open quote on every physical line before
entryOf had a chance to classify it as blank or a comment, so a
commented-out example like `# KEY="sk-old` (an unclosed quote inside
a comment) opened a quote that never closed, joining every line below
it into one value and dropping the real keys that followed.
A genuinely stray unclosed quote with no later closing line had the
same failure mode: the join ran to EOF and swallowed the rest of the
file instead of leaving the malformed line on its own, so a later
file like A='x / B=2 lost B entirely.
Skip blank/comment lines before checking for an open quote (matching
entryOf's own skip), and if the closing-quote search reaches EOF
without finding one, fall back to the opening line on its own and
resume parsing from the next line. Also strip a trailing \r per line
so a CRLF multiline value doesn't carry it into the joined string.
* fix(cli): trim comments on dotEnv.ts to stay within the comment-ratchet budget
Dropped the comments on openQuoteOf and closingLineIndex (their names
already say what they do) and cut the logicalLines comment down to
two lines, bringing the file back to 6/93 comment lines against the
base's 4/57.
* fix(cli): media-treatment and normalize-audio find clips inside mounted scenes
* fix(cli): report the scene file with forward slashes and drop added comments
* fix(cli): normalize-audio reads a scene's audio relative to the scene file
WORD_RUNS split at apostrophes, so "can't" counted as two words and a line with contractions got a longer hold floor than its real word count.
Refs #6338
On Windows 11 with Smart App Control on, Code Integrity refuses sharp's
unsigned libvips DLL. With `--against`, the per-frame render | reference
pair sheet called sharp unguarded, so a blocked sharp failed the whole
snapshot with sharp's multi-line error dump, after the first frame.
Guard the pair sheet: a sharp load failure prints one warning, later
frames skip their pair sheet without retrying, and every frame and
reference frame is still written. Any other pair-sheet error still fails
the snapshot. captureSnapshots reports the skip, so the summary lists
only ref-*.png when no pair sheets were made.
describeSharpLoadFailure turns sharp's load error into one line and names
Windows App Control for Win32 error 4551 ("An Application Control policy
has blocked this file"). The contact-sheet warning keeps warning on every
failure and uses it to shorten sharp's message, and --describe no longer
tells the user to install a sharp that is installed but blocked.
Refs #4845
Claude-Session: https://claude.ai/code/session_01JSZqP4FbpqviXu9v2LjBwE
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
The skills check resolves main's HEAD with `git ls-remote`. A private or
missing repo answers with an auth challenge, and GIT_TERMINAL_PROMPT=0 only
covers git's own terminal prompt: credential helpers and askpass still run,
and Git Credential Manager (the Git for Windows default helper) opens a
sign-in window that blocks the check until it is closed.
Run ls-remote with credential helpers and askpass disabled
(`-c credential.helper=`, GIT_ASKPASS="", GCM_INTERACTIVE=never). Also skip
git for a slug that does not look like `owner/repo`; such a slug gets a
plain 403 rather than an auth challenge, so this check is defensive. The
repos read here are public, so no credentials are lost.
Fixes#4702
Claude-Session: https://claude.ai/code/session_01JSZqP4FbpqviXu9v2LjBwE
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* test(cli): check the browser that ran the hanging script, and that every browser it started is gone
* test(cli): type the launch recorder's pid file and drop the added comment
* fix(cli): a long video copy reports progress, resumes in 15 s pieces and stops only when stalled
* perf(core): a video copy's size box follows the stage within a fifth, not a half
* docs(cli): shorten two comments to the line limit
* fix(cli): the copy heartbeat drops a finished copy; size budgets follow the stall and progress code
* chore: size budgets rise by this change's measured bytes
* fix(cli): drop added comments, the names carry the meaning
* fix(cli): a check that is stopped by a signal prints the report it has so far
Killed by SIGTERM or SIGINT, check closed Chrome and exited 143 or 130 with
nothing on stdout, so a caller that stops a long check got no result at all.
The signal now ends the check the way an expired deadline does: findings
already made are kept, one finding says the check stopped before finishing,
and the report is printed before the process exits with the signal's code.
* fix(cli): stop 'hyperframes add' hanging when a desktop clipboard is available
* test(cli): assert the clipboard copy options instead of waiting on real time
* fix(cli): check finishes on long projects with many video clips
check loaded every video in the project at once. On a 500 s project with 137
clips of one 1440p source a single renderer reached 6.4 GB, the second sampling
Chrome crashed, and a crashed puppeteer page never settles its calls, so the
run sat until the 120 s deadline.
- Load the check page in Studio's capture mode so only media near the
playhead loads (peak renderer memory 15.75 GB -> 1.77 GB).
- Read audio durations for the clip-fit audit from a detached element when the
page has not loaded the one in the composition.
- Settle every driver call with the page's crash or close, so a dead helper
hands its samples back and a dead main page fails at once.
* fix(cli): shorten a comment to the line limit
* fix(cli): include external video posters in project archives
* chore: prepare conflict resolution against current main
* fix(cli): retain poster localization with shared archive resolvers
* fix(cli): reap only orphaned browsers HyperFrames launched
Orphan cleanup on preview and render killed every PPID-1 process of the
current user whose args named chrome-headless-shell or a Puppeteer temp
profile, which included detached browsers started by other tools.
Every HyperFrames Chrome launch now passes an inert
--hyperframes-owned-browser switch, and the reaper only kills PPID-1
processes that carry it as a whole argument.
Fixes#6203
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(core): serve the browser marker from its own subpath
The GCP image's BeginFrame contract step imports the engine's
browserManager straight from source before core's generated runtime
exists, so pulling the marker from the core root entry broke it.
A dependency-free @hyperframes/core/browser-marker subpath keeps that
import chain as light as it was.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(cli): expect the browser marker in the capture fallback launches
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* docs(cli): say orphan cleanup runs before preview and render
The cleanup only stops browsers HyperFrames launched, so the opt-out is
no longer needed to protect other tools' browsers.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(cli): a Chrome download that stops sending is abandoned, retried, and releases the lock
* fix(cli): a stalled Chrome download is aborted at the socket so the process can exit
* fix(cli): the Chrome download runs in its own process and is killed when it stalls
* test(cli): ignore the expected socket reset in the download stall test on Windows
A CLI killed by a signal never runs its exit listener, so its file in
~/.hyperframes/running stays. Only the background installer swept those
files, and it never runs for an install layout it skips ("Unknown install
layout", e.g. a CLI bundled inside another tool), so the folder only grew:
185 markers since 2026-10-05 on one machine, none of them a live CLI.
registerRunningCli now removes, besides its own file, every file whose pid
is gone, whose name is not a pid, or whose heartbeat is older than
RUNNING_STALE_MS (a reused pid) — the installer's own criterion. The sweep
never throws, so a failure cannot skip the heartbeat or the exit listener.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The test reads the running folder's listing instead of checking each path, so no
existence check precedes a write to the same path (CodeQL, file system race).