Commit Graph
103 Commits
Author SHA1 Message Date
Miguel Ángel 2372fc34a1 fix(cli): a browser install goes on when Windows holds a file for a moment (#7194)
* fix(cli): a browser install goes on when Windows holds a file for a moment

* chore(cli): shorten the lock-retry comment

* fix(cli): keep the lock check private

* chore(cli): wrap the lock-check comment
2026-11-05 01:50:43 +00:00
Miguel Ángel 482bcd73ed fix(cli): the FFmpeg cannot-start error names the OS error code or signal (#7115)
* fix(cli): the FFmpeg cannot-start error names the OS error code or signal

* fix(cli): drop a comment the check counts

* test(cli): a timed-out FFmpeg reads as the timeout, not its kill signal
2026-11-03 23:29:40 +00:00
Miguel Ángel 7c5c1ce849 fix(cli): the browser install hint names only a Chrome that exists (#6954) 2026-11-01 23:54:29 +00:00
Miguel Ángel de6ec3811e fix: cache paths follow HYPERFRAMES_CACHE_DIR (#6716)
* fix: cache paths follow HYPERFRAMES_CACHE_DIR

Every place HyperFrames keeps downloaded or built files now takes its
folder from one helper, hyperframesCacheDir() in @hyperframes/core. The
default stays ~/.cache/hyperframes; HYPERFRAMES_CACHE_DIR moves it.

* fix: register the cache-dir subpath for bun and node, and build inspector from core source

* test: the cache-dir override test uses a folder that is absolute on every platform

* fix: the opencv cache follows HYPERFRAMES_CACHE_DIR

* fix(cli): npm installs run in their staging dir, so no cache path reaches a command line

* fix(cli): whisper.cpp is cloned inside its build dir, so no cache path is a git argument

* test(cli): the whisper clone test finds no system whisper on Windows either
2026-11-01 22:44:11 +00:00
Miguel Ángel 315969cda0 fix(cli): render names the FFmpeg that has no libx264 and how to point at another (#6819) 2026-10-30 10:52:46 +00:00
Miguel Ángel 71b668010f fix(cli): the ignored-binary note names only the missing binary, and covers .hyperframes/bin (#6807) 2026-10-30 08:38:05 +00:00
Miguel Ángel 0a18d8c350 fix(cli): browser clear reports a browser folder Windows still holds (#6776)
* fix(cli): browser clear still reports a folder Windows holds, and the EBUSY test covers EPERM

* fix(cli): browser clear reports a locked browser folder, with a test that fails if it does not
2026-10-30 02:38:16 +00:00
Miguel Ángel 6874cc2890 fix(cli): a locked Chrome debug.log on Windows no longer fails check, snapshot or render (#6771) 2026-10-30 01:27:29 +00:00
Miguel Ángel d81099b1ff fix(cli): Apple Silicon skips an ffprobe or ffmpeg that cannot run and names it (#6760)
* fix(cli): Apple Silicon Macs without ffmpeg get working arm64 ffprobe and ffmpeg

* fix(cli): drop the bundled ffmpeg installers, name the x86-only binary it skipped
2026-10-29 23:20:11 +00:00
Miguel Ángel 8e63faf846 perf(engine): a --gpu render probes the GPU encoders once, not twice (#6638)
* perf(engine,cli): a machine's GPU encoder probe runs once, not on every render

* refactor(engine): one shared probe per process, no answer kept on disk
2026-10-28 08:44:28 +00:00
Miguel Ángel 439d685678 fix(cli): a page whose renderer crashes fails at once, named as the crash (#6598)
* fix(cli): a page whose renderer crashes fails at once, named as the crash

* fix(cli): keep the crash naming inside the shared error formatter
2026-10-27 23:22:08 +00:00
Miguel Ángel 4416a41cba fix(cli): every managed browser closes within a second even if Chrome never exits (#6553)
* fix(cli): every managed browser closes within a second even if Chrome never exits

Commands called browser.close() directly, which waits for the Chrome process to exit without a limit. A headless shell that acknowledged Browser.close and then stayed alive left the CLI hanging after its work was done. The managed browser's close() is now the bounded close that kills a browser that has not exited.

* test(cli): browser stand-ins carry the close() a real browser has
2026-10-27 13:29:56 +00:00
Miguel Ángel c1da4a760e fix(engine): audio effects launch Chrome like every other render, sandbox retry included (#6550)
Audio effects launched Chrome with its own two flags and no retry, so inside
an agent's macOS seatbelt Chrome died at startup with "Target closed" while
the CLI's own browser launch recovered. The sandbox launch policy now lives
in the engine; the engine's Chrome launch retries once in one process over a
pipe when the sandbox refuses it, and audio effects use the shared Chrome
flags in software GPU mode. The CLI imports the same policy from the engine.
2026-10-27 13:26:01 +00:00
Miguel Ángel 4f1e66d2d0 fix(cli): orphaned Chrome helpers no longer keep a finished snapshot from exiting (#6545)
* fix(cli): a browser's orphaned helpers no longer keep a finished snapshot from exiting

The CDP pipe sockets stayed open after Chrome exited whenever a helper process outlived it, so the CLI never reached natural exit. Destroy them when the browser process exits.

* refactor(cli): name the pipe close so launch.ts carries no new comment

* fix(cli): a browser stand-in without stdio no longer throws from the exit listener

* fix(cli): close every pipe of an exited browser, not only the CDP pair
2026-10-27 11:08:59 +00:00
Miguel Ángel b428ea92be fix(cli): closing the managed Chrome also ends the helper processes it leaves behind (#6542)
* fix(cli): closing the managed Chrome also ends the helper processes it leaves behind

The close waited a second for Chrome to exit and then killed only Chrome's own process.
Under load that second is often not enough, and the helpers (the GPU and renderer
processes, crashpad_handler) were reparented to init and kept running after a finished
run. The close now records the processes under Chrome before it starts, and ends any of
them still running (under the same command) once Chrome is gone.

* test(cli): the helper-reaping test polls for the helper's exit instead of waiting 200 ms

* fix(cli): the Chrome process listing is bounded and no longer runs at import

The ps call that records Chrome's helpers ran with no time limit before the
bounded browser close, so a stalled ps made the close unbounded. It now has a
2 s limit, and a timeout records no helpers.

execFile is resolved when ps runs, not when the module loads, so tests that
mock node:child_process without execFile import it again.
2026-10-27 11:08:53 +00:00
Miguel Ángel 9e5da67409 fix(cli): a Chrome that fails to start says how it ended, and a slow start says so (#6516)
* fix(cli): a Chrome that fails to start says how it ended, and a slow start says so

A failed launch only reported "Protocol error (Target.setDiscoverTargets): Target closed". It now
runs the browser once more on its own with the same flags and reports its exit code (Windows
codes named: missing runtime, out of memory, security software), its last stderr lines, or that
it stayed up. The CLI and the engine's render launch both use it. A start slower than 5 s prints
"Chrome is still starting...", and a --timeout that looks like seconds says it is milliseconds.

* chore(cli): cut the Chrome launch diagnosis comments to the comment limit

* fix(cli): the Chrome startup check runs Chrome as puppeteer does and can be cancelled

The check started the browser with only the caller's flags, so a full Chrome ran headful and
was blamed for a missing X server. It now uses puppeteer's default arguments (headless
included). The check is stopped when the CLI is stopped, and the GPU probe, whose failure
falls back to software anyway, skips it.

* fix(cli): a Chrome launch error is never replaced by a failure to explain it

The startup diagnosis asks puppeteer for its default arguments before re-running
Chrome. If that call fails, its error used to replace the launch error the caller
needed. The launch error is now reported as it was. The core package size budget
rises to cover the new chromeStartup module (about 4.7 KB unpacked).

* refactor(engine): the Chrome startup diagnosis lives in the engine, not core

Both callers launch Chrome through the engine (the CLI already imports it), so the
engine owns the diagnosis. Core's package size budget is back to its old value.
2026-10-27 07:49:04 +00:00
Miguel Ángel 63d9435625 test(cli): install-lock concurrency test uses fake timers (#6504) 2026-10-27 01:48:48 +00:00
Miguel Ángel 6b7d6dfb2e test(cli): the mid-render orphan test waits for three Chrome processes alive at once (#6489) 2026-10-26 22:53:12 +00:00
Miguel Ángel 59d5e4fec8 fix(cli): check and snapshot fail fast on a missing browser path and say while Chrome downloads (#6479)
* fix(cli): check and snapshot fail fast on a missing browser path and say while Chrome downloads

* fix(cli): a non-interactive Chrome download gives up after one stall, naming the env var and doctor
2026-10-26 21:28:41 +00:00
Miguel Ángel 8f618c5ffe fix(cli): the Windows Chrome check reads the file version, not chrome.exe --version (#6459)
* fix(cli): the Windows Chrome check launches Chrome instead of trusting chrome.exe --version

* refactor(cli): shorten the Windows Chrome version comment to fit the comment ratchet

* test(cli): pin the platform in the Unix Chrome preflight tests so Windows runs them as written

* fix(cli): the Windows Chrome check reads the file version, not chrome.exe --version
2026-10-26 15:39:09 -04:00
Miguel Ángel 5148326fd6 fix(cli): a killed CLI no longer leaves its child processes running (#6431)
* fix(cli): a killed CLI no longer leaves its child processes running

* test(cli): shorten the reaper fixture comment to fit the comment ratchet
2026-10-26 17:28:50 +00:00
Miguel Ángel 4d154c6a23 test: two flaky queue tests no longer race real time or the first copy's start (#6283) 2026-10-25 07:13:22 +00:00
Miguel Ángel 1f740ca21a fix(cli): a check that is stopped by a signal prints the report it has so far (#6282)
* 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.
2026-10-25 07:13:09 +00:00
James RussoandClaude Opus 5.5 f180ffca64 fix(cli): reap only orphaned browsers HyperFrames launched (#6251)
* 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>
2026-10-24 23:09:57 +00:00
Miguel Ángel fcec26ed5f fix(cli): a Chrome download that stops sending is abandoned, retried, and releases the lock (#6222)
* 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
2026-10-24 17:53:54 +00:00
WaterrrForeverandClaude Opus 5.5 688229314f feat(skills)!: publish seven knowledge skills aligned with Studio and retire the workflow skills (#5651)
* refactor(skills): fold six domain skills into hyperframes and media-use guides

hyperframes-core, -animation, -keyframes, -creative and -studio move to
skills/hyperframes/{core,animation,keyframes,creative,studio}/, and
hyperframes-audio moves to skills/media-use/mix/. Each moved SKILL.md becomes
a frontmatter-free GUIDE.md so installers that scan recursively for SKILL.md
no longer see them as skills; the published list goes from 21 to 15.

Relative links, code paths and skill-name mentions are rewritten to the new
locations, the catalog surfaces, marketplace core-skills list, fallback core
set, module-copy targets and skills-manifest.json follow, and
`hyperframes skills update` now removes the retired skills (RETIRED_SKILLS)
when they are still installed.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(skills): slim the core entries and give media-use a HeyGen and a free path

The four entries every run opens are rewritten to what an agent cannot infer:
hyperframes 21.8 KB to 7.7 KB, hyperframes-cli 24.8 KB to 6.9 KB,
hyperframes-registry 9.9 KB to 4.3 KB, media-use 9.7 KB to 4.9 KB. Detail moved
whole into references (routing close calls and creator edits, CLI pin upgrades,
catalog search tiers, CLI conventions and feedback reports).

- hyperframes: state table, routing, the render contract, a terminal work loop
  (check, snapshot, preview before render), the desktop-app hand-off, and a
  table of the folded guides.
- media-use: one table of HeyGen versus free local tools per need; HeyGen
  sign-in, credits and the CLI's video-agent, avatar, clone, lipsync, translate
  and clipping commands; every free path works with no account.
- scripts/check-core-skills.mjs holds entries and descriptions to budget and
  checks every taught `npx hyperframes` command and path; runs in lint.
- Core entries are exempt from the formatter: its table padding cost ~1.5 KB
  per entry on every run.
- Content tests follow the text to its new home.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): plugin runs skip skills update; media-use explains HeyGen sign-in and TTS setup

The smoke eval showed a presenter request never reaching media-use and the
free voiceover failing on a missing kokoro-onnx; plugin runs also ran the
skills update the plugin rules forbid.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* chore(skills): drop a committed Python bytecode file and ignore bytecode

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(skills): align the entry with the Studio skills and keep the workflows' measured facts

The entry drops routing and the intent interview and carries the contract, the
editable-project rules and the work loop. Studio's format, runtimes, motion,
look and captions references come over for terminal use, frame presets move to
assets/, media-use gains Studio's mixing and local-command references, and
film.md and overlays.md keep what the workflow skills measured.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(skills)!: retire the workflow skills and folded guides; publish seven knowledge skills

The skill pack now publishes exactly seven skills - hyperframes,
hyperframes-cli, hyperframes-registry, media-use, figma, slideshow and
remotion-to-hyperframes - carrying knowledge, not process. The eight
workflow skills, the folded domain guides and the routing/interview
references are deleted; their measured facts already live in the
hyperframes references (format, runtimes, motion, look, captions, film,
overlays) and media-use's mixing reference.

- bake-basemap.mjs and locate.mjs move to skills/hyperframes/scripts/
  (bake-basemap gains --help); extract-audio-data.py moves to
  media-use/audio/scripts/ for the caption motion reference.
- skills update: the eight workflows join RETIRED_SKILLS so existing
  installs prune them (by lock attribution only, since their names are
  generic); naming a retired skill reports where its knowledge went and
  succeeds instead of failing as unknown.
- Capture prompts point at the hyperframes skill's references/film.md;
  the live-map warning names the new bake-basemap path.
- Content tests that pinned knowledge are retargeted to the kept
  references; tests of deleted workflows, scripts and process go.
- Catalog surfaces, templates and docs describe the seven skills.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): resolve the local.md captions link and allow capture's output files in citations

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): regenerate the skills manifest from tracked files only

The committed media-use hash included an ignored __pycache__ bytecode file present
in the local checkout, so CI's clean checkout hashed differently.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(docs): restore generated catalog pages and docs navigation to main

Catalog PRs commit item sources only; CI regenerates the pages from the edited
registry sources. docs/docs.json is catalog navigation, so its Workflows group
rename is left for a non-catalog PR.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* build(cli): raise the CLI size budget for the skill references it bundles

The CLI bundles skills/hyperframes, which now carries the folded domain guides and
frame presets (155 KB to 1.08 MB in git). Budgets are the CI-measured size plus 5%:
packed 7526634, unpacked 22593213.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test: keep repo-sweep guards meaningful after the workflow skills left

The last shell ffprobe caller and most root index.html examples lived in retired
skills. The shell detector is now pinned on a literal command line, and the
structure-rule sweep needs more than 5 roots (11 remain) rather than 30.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(skills): slim figma, slideshow and remotion to the Studio shape; restore the storyboard board

slideshow 33.5 KB to 4.9, figma 18.2 to 6.2, remotion-to-hyperframes 11.0 to
4.9, each keeping the facts only it holds (the figma motion helpers, verify gate,
storyboard decoding and usage beacons; present and hand-off; the Remotion lint,
SSIM check and API map). The board page format from the storyboard recipe comes
back as hyperframes/references/storyboard.md: the desktop app's Storyboard tab
reads boards/storyboard.html by its frame, title and time classes. The entry and
the init template now say to snapshot the moments an edit changed before
replying, which the terminal eval found skipped in 22 of 38 runs.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): manifest without local bytecode; Studio's edit prompt names kept files

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): render when the person asks for the file or for no stops, not only after approval

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): keep the voiceover carve in media-use; presets stage their own fonts

Review follow-ups on #5651:
- carve.mjs and its tests move to skills/media-use/audio/scripts; the audio
  docs, mixing.md and two Studio comments point there.
- code-editorial's FRAME.md says to copy its bundled WOFF2s and add the
  @font-face blocks, instead of promising the retired build-frame.mjs.
- media-use states the host rule before the HeyGen sign-in steps.
- storyboard-format marks transition_in as a note the agent builds itself.
- Two stale citations (creator-editing-recipes.md, sub-compositions.md).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* chore(skills): regenerate the manifest without local bytecode

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): the CLI render step follows step 4's rule, not approval alone

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(ci): run the core-skills check from lint again after the main merge

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(skills): films that tell a story start from three storylines; maps use real imagery

Opus 5.5 arm D read motion.md and applied it, but its launch film was a
feature list (pain, three feature cards, proof, logo): film.md left story
to the model. And the map case never opened film.md, so it drew Natural
Earth outlines instead of baking satellite tiles.

- references/story.md: the generic half of Studio's moment-film story and
  craft (one thing, three storylines with world and device, the hook,
  beats, worlds, copy, brand, tells of a generated film). The person picks
  a storyline, or the agent takes its recommendation when asked for the
  file or for no stops.
- The entry's work loop names the storyline step for films over ~15 s; the
  references table routes stories to story.md and maps to film.md.
- film.md points at story.md and gives maps and real places a section.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): story.md follows the entry: no voiceover unless asked

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): bake-basemap starts from a globe and stops waiting out its idle timeout

The Opus 5.5 map run spent 13 of its 38 minutes on parallel bakes that
stalled and 15 more recording 300 frames, after rewriting the script because
it could only start on a flat map.

- PROJECTION=globe with a seeded starfield and atmosphere, and FROM/PAN to
  turn the globe to CENTER before the dive.
- Each frame polls for loaded tiles instead of waiting for an "idle" event
  that had often already fired: 30 frames went from 198-219 s to 10-13 s
  locally with byte-identical frames.
- Progress prints seconds a frame and minutes left; film.md shows the globe
  call and says to run one bake at a time.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): render in the foreground; wait on a detached render's log, never pgrep -f

Both Opus 5.5 explainer runs started a detached render, then waited with
`until ! pgrep -f "hyperframes render"`, which matches its own loop: each
render took 88-117 s and the wait sat for the tool's full 10 minutes.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(skills): route each kind of film; storylines carry look and sound; add review and sound

The entry routes by request (launch, explainer, music, data, vertical, 3D,
character) to a self-contained file under references/types/, and a film
over ~15 s now gets music and sounds on its visible actions unless the
person asked for silence. Each storyline names its look and its sound, so
picking one picks both; STORYBOARD.md frames carry `reads` and `sound`.

review.md is the whole-film pass: the check warnings, the review sheets,
seven questions to look for, P0/P1/P2 notes and REVIEW.md. motion.md gains
eases by role, six title entrances, a reading-time rule and nine measured
transitions; look.md a design plan before the first scene, with presets
kept for decks and named picks. story.md adds the second default that
generated design falls into, with what to do instead.

The blank template and format.md no longer teach the fade-and-slide-up
entrance on a dark canvas.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(cli): check warns on unread lines, dead stretches, small type, empty frame 0 and silence

A coding agent cannot watch its film, so check now measures what a viewer
notices over time. A new `craft` section holds warnings only (exit 0
unless --strict), sampled on the dense 8 fps grid the overlap pass
already seeks, skipped for --range checks:

- line_unread: a reading-size line (>= 30 px tall at 1080) on screen
  under 0.4 s for 1-2 words, else under 3/4 of 0.5 s + 0.3 s a word;
  the film's last line needs 2 s. Short lines are re-measured between
  samples to ~0.01 s before judging. Captions-track and
  data-layout-ignore text are exempt.
- dead_stretch: more than 3 s where the keepsMoving liveness signature
  does not change, outside the final 3 s and any data-hold element;
  quiet when sweep_static fires or a whole-composition keepsMoving
  assertion owns the limit.
- text_below_floor: text under 2.6% of the short side (28 px on 1080)
  held 0.5 s, one finding per file listing every element.
- first_frame_empty: frame 0 paints only the background.
- film_silent: over 15 s with no unmuted audio or audible video.

Each message names the fix and the skill reference to read. keepsMoving
now also leaves the film's last 3 s (a still end card) out of its
static runs, so the two agree.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(cli): snapshot --review captures a beat sheet, seam strips and a phone sheet

snapshot --review picks the frames that show a film over time instead of
evenly spaced ones, in the same single browser session:

- review-beats.jpg: one settled frame per scene at its start + 0.3 s,
  plus one per timed data-beat="name" element, labelled time and id.
  Scenes are the composition's top-level timed clips and sub-composition
  hosts, read like `timeline` reads rows (captions and audio excluded)
  and timed by the runtime's start resolver over the live page.
- review-seam-NN.jpg: frames at -0.2, -0.1, 0, +0.1, +0.2 s around
  every cut (each scene start, and any scene end no scene starts at).
- review-phone.jpg: the beat frames at 360 px wide.

--composition scopes the review to one sub-composition; with fewer than
two scenes the beats spread evenly and a note says so. snapshot also
gains --json: one envelope with every frame's path and time and, under
--review, the scenes, beats and seams behind the sheets; progress moves
to stderr.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(cli): craft warnings stay out of --strict; a hold gets a real next action, not a caret

Craft findings (unread lines, dead stretches, small type, an empty first
frame, silence) are judgment calls a film may break on purpose, so
--strict keeps gating defects only. The check reference no longer
suggests a blinking caret to keep a still frame moving.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(cli): review spreads beats when every scene starts together; map credits skip the type floor

A map film whose basemap and overlay both start at 0 s got one beat
frame; the even spread now keys on distinct scene starts. film.md tells
agents to mark the imagery credit data-layout-ignore and back it, since
the new type floor flagged it on the first real run.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(cli): review frames each scene at its middle too, not only 0.3 s in

On the first real explainer, 0.3 s into a scene showed a bare colour
field before its title entered. Each scene longer than about a second
and a half now adds a frame at its middle, so the sheet shows what the
scene builds.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(skills): a film is built from a numeric SPEC.md, with defaults banned by name and a look test

Studied in full: flxrnc's Motion Lab (vague vs directed prompt), 0xMovez's
course, EianLu's riso skill, agentchengfeng's style samples and the two
Opus 5.5 guides. Their common point: adjectives are where the default look
lives, so the agent now writes SPEC.md before any scene (GOAL, OUTPUT,
TIME, LOOK, MOTION, SHOTS, BANNED, QA), with a number for every adjective.

spec.md bans the defaults by name, unless the brand or reference uses
them (a dark void with small things floating, glow and particles, the
cream-serif-mono-label look, fade-and-slide-up, corner brackets), and
grows that list after the first render. Each storyline gets a 3 s test of
its hero shot before the pick; a look is written as the rules of one
medium. Composition numbers: the hero fills 40% of the frame, one hero
move per shot, the shot's information in within 2.5 s then a held poster.

motion.md adds springs by damping ratio, shorter exits, overlap, stagger
and the beat grid; review.md reviews as a harsh director and grows BANNED;
vertical.md takes the riso skill's measured safe band; explainer.md the
shapes of information.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): story before look; every object reads as itself; posters only for info cards

The first spec-driven C02 swapped the dark default for a flat Swiss
poster, and the story went with it: two black bars nobody read as mirrors,
slogans instead of cause and effect, a storyline picked for its picture.

The spec now serves the story: a storyline is picked for the story a
stranger would follow, the look test asks first whether a stranger
understands what they see, and SPEC.md gains an OBJECTS line giving each
thing the material and details that make it read without a label. The
2.5 s held-poster rule is limited to information cards; in a story film
every shot causes the next. Explainers start from a person or situation
the viewer knows. Review names every object as a stranger would and
treats one that needs explaining as a P0.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): storylines are three films in words, each with a device and a form

The three storylines are pitched as text and the person picks from them;
nothing is built for a storyline before the pick, so the 3 s hero-shot
look test is gone. Ideas pair a device with a form, five or more first,
keeping the three that differ most, and the one stop states the rest in
an assumption line that names every paid item beside its free option.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* ci: list main's new embedded-captions hf-cli test among the retired workflow files

The merge with main removed it with the rest of the retired skill, and the
deletion guard rejects any removal it has not been told about.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(core): keep the audio preset comment within core's size budget

The comment's new citation to media-use's mixing reference made the published
package 14 bytes larger than its budget, which sits at main's exact size.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(cli): craft keeps its own 8 fps grid; comments back within the checks

Review on #5651 found that the merge moved craft onto the overlap pass's
times, which main caps at 180, so a brief line in a long film fell between
samples and line_unread missed it. Craft now builds its own grid at 8 fps up to
600 samples, as before the merge, and a 60 s film with a line shown for 0.2 s
pins it.

The Comments check passes again: REVIEW.md and STORYLINES.md join the files a
skill writes into a project, the comment lines this branch added come back
under each file's share at the merge-base, and the audio preset comment drops
a word the check reads as history.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-21 19:19:31 +00:00
Miguel Ángel 84f7965492 fix(cli): a disk that fills mid-unzip fails the browser install at once instead of hanging (#6013)
* fix(cli): a disk that fills mid-unzip fails the browser install at once instead of hanging

* test(cli): the unzip tests hold on Windows, and a cancel stops unzip
2026-10-21 09:45:18 +00:00
Miguel Ángel 6cb9ce096f fix(cli): a first render on a nearly full disk refuses at once instead of hanging (#6006)
* fix(cli): a first render on a nearly full disk refuses at once instead of hanging

* fix(cli): name the low-disk guards instead of commenting them

* fix(cli): a killed install's leftovers never count against the free-space check

* test(cli): the render command's mocks carry the disk check it now runs first
2026-10-21 07:10:42 +00:00
Miguel Ángel 0260c40e56 fix(engine): renders use the browser the CLI picked; Linux system Chrome is not beginframe (#5987)
* fix(engine): renders use the browser the CLI picked; Linux system Chrome is not beginframe

* fix(cli): state the browser env rule without its history

* fix(engine): renders from the CLI launch the browser it picked, not the engine config's
2026-10-21 01:56:34 +00:00
Miguel Ángel 00d55a7f1d test(cli): the Chrome orphan check waits for Chrome to exit instead of 5 s (#5986)
After SIGKILL the test slept a fixed 5 s, then required every Chrome process
gone. On a loaded Windows runner the watchdog took longer and two processes
were still exiting. It now waits up to 30 s for none to be alive, so a real
orphan still fails.
2026-10-21 00:59:46 +00:00
Miguel Ángel f440db9019 fix(cli): check waits for late images and runs its browser pass in unnamed macOS sandboxes (#5977)
* fix(cli): snapshots, compare and check wait for late images the way render does

* fix(cli): check runs its browser pass inside a macOS sandbox that does not name itself

Every CLI Chrome launch has used a pipe since the warm-check change. A pipe
launch that a seatbelt kills fails with only "Protocol error
(Target.setDiscoverTargets): Target closed". The one-process fallback keyed
on Chrome's bootstrap_check_in stderr, which a pipe launch failure never
carries, so it never fired. On macOS a pipe launch that fails at the
protocol level now relaunches as one process over the pipe.

* fix(cli): retry only a pipe launch whose connection closed, and keep puppeteer lazy
2026-10-20 22:54:45 +00:00
Miguel Ángel 434ad8c41c perf(cli): a repeat check starts with the CLI and Chrome already up (#5943)
* fix(cli): the browser the CLI launches exits with it, even on kill -9

* fix(build): the root build runs on Windows

* perf(cli): a repeat check runs in a process that already has the CLI and Chrome up

* fix(cli): a warm check delivers all its output before it exits

* fix(cli): the warm check only talks to a server that proves it is the user's

The warm socket now lives in a private, owner-verified directory (XDG_RUNTIME_DIR,
~/.cache or LOCALAPPDATA) next to a 0600 token. Client and server prove the token to
each other over fresh nonces before any request is sent, the request carries an
HMAC of the environment instead of the environment itself, and frames are capped.

* fix(cli): a warm check prints its stdout even after something went to stderr

The client stopped writing frames once any frame had been written, so a check that
printed a notice to stderr first lost its JSON report.

* test(cli): list the warm-check client fixture as a fallow entry instead of an inline ignore

* fix(cli): a check started while a warm one is busy runs cold at once on Windows

The warm server stopped listening when it accepted a client. On Windows the pipe name stays alive through the served connection, so a second client's connect saw a busy pipe and waited 30 s for a free instance before running cold. It now keeps listening while serving (accept already declines anyone else) and stops when the served check finishes.

* test(cli): the orphan test reads the check's own Chrome and watchdog instead of racing a poll

On Windows each process listing is a PowerShell call of about a second, so a check that finishes quickly could start and close Chrome between two polls, and the test failed its own 'Chrome was seen' precondition. A fixture now records the Chrome tree and the watchdog from inside the check when its first page opens.
2026-10-20 19:09:11 +00:00
Miguel Ángel 50e7a59aef fix: check, snapshot and renders use the pinned Chrome, not an older one another tool cached (#5900)
* fix(cli): check and snapshot use the pinned Chrome, not an older one another tool cached

* fix(cli): keep the browser-order comment within the line limit

* fix(engine): renders that resolve their own browser follow the same pinned-first rule

* fix(engine): keep the browser rule's reasoning in the PR, not new comments

* fix: a shared-cache shell is used only if it starts, after the pinned build

* fix(engine): import the shared-shell pick, and probe shells with a blank page

* fix(skills): caption scripts launch the browser the CLI chooses

* chore(skills): regenerate the skills manifest for the caption scripts
2026-10-19 20:00:25 +00:00
Miguel Ángel 44bbc5885f perf(core): a color grade compiles only the effects it turns on (#5889) 2026-10-19 17:42:12 +00:00
Miguel Ángel 7917f7fe05 perf(cli): check skips contrast screenshots it can compute from styles (#5871)
* perf(cli): check reads a solid text backdrop from styles instead of a screenshot

* perf(cli): check starts Chrome while lint and bundling run

* perf(cli): the CLI reuses compiled bytecode between runs

* test(cli): browser shutdown tests stop their Chrome when a case fails
2026-10-19 16:15:24 +00:00
Miguel Ángel 9fd5e4ae2d fix(cli): a render no FFmpeg encoder can finish stops before capture, not after it (#5831) 2026-10-18 22:13:26 +00:00
Miguel Ángel dc0e80e73a fix(cli): capture works inside an agent's macOS sandbox (#5840)
The seatbelt launch runs Chrome as one process, where there is no GPU process
to composite. Capture's flags left GPU compositing on, so every screenshot
failed and heavier pages stalled until the protocol timeout. The one-process
launch now also disables GPU compositing, as software capture already does.
2026-10-18 10:07:56 +00:00
Miguel Ángel 834e90a779 fix(cli): check never hangs inside an agent's macOS sandbox (#5836)
Inside Codex's seatbelt the GPU probe's Metal Chrome is always killed, and
when it dies after puppeteer's setAutoAttach is answered, puppeteer waits
forever for its initial targets. The probe now answers software in a named
seatbelt without starting Chrome, and every CLI browser launch is bounded
by its timeout, so a stuck launch rejects and a signal can end the command.
2026-10-18 09:01:26 +00:00
Miguel Ángel 5e7ba0be94 fix(cli): Chrome starts inside an agent's macOS sandbox as one process over a pipe (#5781) 2026-10-17 15:01:31 +00:00
Miguel Ángel fa93669156 fix(cli): a browser a sandbox refuses says to rerun the command with escalation (#5734) 2026-10-17 07:36:52 +00:00
Miguel Ángel 8be76fc86c fix(cli): pin website capture connections to public peers (#5668)
* fix(cli): pin website capture connections to public peers

* style(cli): keep capture policy explanations within comment limits

* test(cli): separate case-sensitive dotenv assertions

* fix(cli): honor capture deadlines and bootstrap isolation

* chore: trim redundant capture dotenv comments

* fix(capture): join signal cleanup and guard leading options

* docs(capture): trim redundant cleanup comment
2026-10-16 02:37:14 +00:00
Miguel Ángel 03a9fab9a7 fix(cli): first render on Windows no longer fails while a new browser or ffmpeg is scanned (#5625) 2026-10-15 00:56:06 +00:00
Miguel Ángel 6c89decb0d fix(cli): the GPU probe uses the pipe too, so a sandboxed check doesn't wait 120 s (#5622)
* fix(cli): the GPU probe uses the pipe too, so a sandboxed check doesn't wait 120 s

* fix(cli): name, not comment, says the probe can't listen
2026-10-14 20:26:09 +00:00
Miguel Ángel fe29f157f9 fix(cli): a killed browser on a busy Windows machine no longer fails check (#5607) 2026-10-14 16:59:25 +00:00
James RussoandClaude Opus 5.5 692b89b6e5 chore(docker): pin FFmpeg 8.0.1 in the Docker images and host CI (#5576)
* chore(docker): pin FFmpeg 8.0.1 in the Docker images and host CI

Install one pinned static BtbN build (n8.0.1-66, month-end release) in
Dockerfile.test, the CLI render image, the Cloud Run image and the k8s
example, and bump the host CI install-ffmpeg-linux action from 7.1.3 to
the same build. Regression baselines and the shipped images now use the
same FFmpeg version instead of Debian's apt ffmpeg 5.1.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(producer): regenerate six regression baselines on FFmpeg 8.0.1

The Docker test image now renders with FFmpeg 8.0.1 instead of Debian's
5.1. Six fixtures fail against the 5.1 baselines; everything else passes
unchanged, including vfr-screen-recording.

- style-2-prod, style-10-prod: FFmpeg 8 honors the MP3 gapless header,
  so the probed SFX duration is 1.0s instead of 1.044898s. Regenerate
  output.mp4 and compiled.html.
- vignelli-stacking: one checkpoint (8.06s) now shows source frame 201
  of the 25fps a-roll, which is the right frame for that time; the old
  baseline showed frame 202.
- missing-host-comp-id, variables-prod, speed-ramp: AAC encoder output
  differs enough to drop the RMS-envelope correlation on flat signals
  below 0.9. Sample correlation against the source stays at 0.9999.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(cli): read the ffmpeg version from n-prefixed release builds

Release-branch ffmpeg builds, including the BtbN build now pinned in CI,
print "ffmpeg version n8.0.1-66-...". extractMajorVersion skipped the
"n8" token and returned 0 (and 1 for n7.1.3), so the CLI telemetry
smoke check failed. parseToolVersion fell back to the whole banner line.
Accept an optional "n" before the version number in both.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(cli): keep the preflight comment share flat

Fold the n-prefix note into the existing doc line instead of adding new
comment lines, which the comment ratchet rejects.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(docker): pick the FFmpeg build per arch and fail on a bad binary

Dockerfile.test, the k8s example and the Cloud Run image always extracted the
amd64 archive on multiarch bases, and the piped version check passed even when
the binary could not run. All four images now pick linux64 or linuxarm64 by
TARGETARCH, fail on any other arch, and grep both ffmpeg and ffprobe for the
pinned version.

style-2-prod and style-10-prod compiled.html go back to the previous golden
with only the SFX data-duration/data-end changed, instead of a full
recompile that also picked up unrelated compiler output.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-14 05:37:15 +00:00
Miguel Ángel c96099d39a fix(cli): bound checks of non-finishing compositions (#5537)
* fix(cli): bound checks of non-finishing compositions

* fix(cli): account for cold startup in deadline witness

* fix(cli): wait for profile owners before test cleanup

* test(cli): separate portable deadline and Linux process witnesses

* test(cli): preserve per-launch browser profile ownership

* fix(cli): start check deadline after browser readiness
2026-10-13 13:49:05 +00:00
Miguel Ángel 9e9b613ccf fix(cli): the browser download unpacks on machines without an unzip command (#5433)
* fix(cli): the browser download unpacks on machines without an unzip command

* fix(cli): a corrupt browser download on the yauzl path is retried and named

* revert(cli): drop the cause-chain reader; @puppeteer/browsers never passes the cause through
2026-10-11 02:13:54 +00:00
Miguel Ángel f85614ecb2 fix(cli): WebGPU compositions work in snapshot, check and layout like render (#5354)
* 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
2026-10-10 00:08:07 +00:00
Miguel Ángel 0241078560 fix(cli): name the unzip errors when every Windows unzip tool fails (#5355)
* 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
2026-10-09 19:18:27 +00:00
Miguel Ángel 577bdf6701 fix(cli): browser ensure fails when the unzip leaves no Chrome executable (#5329)
* 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
2026-10-09 16:21:46 +00:00