* fix(cli): preserve video frames when scenes reuse element IDs
* chore(core): keep media identity comments within the ratchet
* test(core): update page-build goldens for distinct media ids across repeated scenes
* fix(audio): fit PCM to video frames before AAC delivery
* fix(audio): migrate the CLI diagnostic stage fixture
* fix(test): measure the whole unscaled audio residual
* test(audio): refresh the speed-ramp delivery golden
* feat(cli): open scaffolded agent instructions with what hyperframes is
Agents asked to make a video choose from what is on disk. The AGENTS.md and
CLAUDE.md that init writes now open with a plain statement of what the project
is and that `hyperframes render` replaces a hand-built headless-browser and
ffmpeg pipeline, and list `snapshot` beside preview, check, render and docs.
A test pins that init writes both files from the template, and the CLI docs
now say init creates them.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* chore: describe the npm packages in plain words
npm search ranks on description and keywords. The hyperframes package now says
what it does ("Make videos with code and AI agents: write HTML, render MP4.
Open source.") and lists the words people and agents search for. Core and
studio had empty descriptions; producer and player gain keywords too.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(readme): give coding agents a one-line start
The opening paragraph said what HyperFrames is but not how an agent starts.
Add one line: install the skills, then ask the agent for a video.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cli): keep the scaffolded agent intro to what the folder is
Inside a scaffolded project the agent already uses the CLI, so telling it not to build its own
capture pipeline there adds nothing. The intro now only says what the folder is.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* chore: keep npm metadata to the CLI package
Internal packages are not searched on npm, and the init test only
re-checked the template's own text.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* chore: context7.json so agents get the docs and the composition rules
Indexes docs, skills, registry and examples only (no test fixtures),
and hands agents five rules from AGENTS.md.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cli): history lists its entries even when this run cannot write the history
history --json, show and the other read-only subcommands open the history as
its owner, which writes a lock and files pending changes. On a full disk or an
unwritable cache folder that write failed the whole read. A read now falls back
to the history as last recorded and says why on stderr; undo, restore and other
writes still fail.
* fix(cli): history falls back only when it could not write, not when it could not read
* fix(cli): history reads past a log it may read but not append to
* fix(cli): a portrait clip passed to init --video makes a portrait project
* fix(cli): keep init's comment share and the skill's citations within the checks
* feat(cli): init --video snaps the frame to 9:16, 4:5 or 1:1 so a phone clip shows whole
* fix(cli): init --video frames a non-square-pixel clip by the shape it plays at
* fix(cli): init --video frames the project to the clip's own shape, so the whole picture shows
* fix(cli): keep init's comment share at its base
* test(cli): drop the ratio check of the retired talking-head skill
* fix(cli): a check that runs out of time says which step it was in and how long each took
When check hits its 120 s deadline, the error now names the step it was in
(loading the page, waiting for it to be ready, checking samples, the overlap
pass, finding crops) and the seconds each step took, including the video
copies and Chrome start that happen before the deadline starts.
* fix(cli): drop two comments the names already say
* feat(cli): read a whole recording as voice, effect and music lines
`hyperframes audio <file> --read` turns an episode or reference video into
time-stamped lines an agent can read or grep: sentences with rate, pitch and
ending; pauses; sound effects grouped by identical sound, with band, attack,
tail and level over the music; and the music bed split at its cut-outs into
pieces that start, resume, return or are new.
Effects and music come from stems separated by the service at
HYPERFRAMES_AUDIO_STEMS_URL (vocals, drums, bass, guitar, piano, other).
Without stems, effects are read from the mix outside speech; with neither
stems nor a transcript, voice and effects are not read, and each case is
reported in a warning. Results are cached per file content.
* refactor(cli): name the service error parse instead of commenting it
* fix(cli): call HeyGen's audio services with the CLI's HeyGen credential
Stems for `audio --read` and the `api` analysis provider only ran when
HYPERFRAMES_AUDIO_STEMS_URL / HYPERFRAMES_AUDIO_API_URL and
HYPERFRAMES_AUDIO_API_KEY were set, so someone with HEYGEN_API_KEY or a saved
`hyperframes auth login --api-key` still got "not set" and had to know the
internal route.
Both now default to /v3/audio/stems and /v3/audio/analysis on the HeyGen API
(HEYGEN_API_URL when set) with the credential the other HeyGen commands use.
The URL variables still point at another service, which then needs its own
HYPERFRAMES_AUDIO_API_KEY, so the HeyGen credential never goes to a host it was
not issued for.
* fix(cli): keep audio on the machine unless --quality best is asked for
`hyperframes audio` defaulted to --quality best, so anyone with a HeyGen
credential uploaded their audio, and could be billed, for an ordinary beats or
--read run. tts, transcribe and remove-background never leave the machine
unasked.
The default is now local for both measuring and --read. best is unchanged and
still uploads to /v3/audio/analysis and /v3/audio/stems. When a capability goes
unanswered because a service was left out, or --read reads without stems, the
warning says --quality best would add it.
* fix(cli): bound stem transfers and preserve recording timestamps
* fix(cli): an empty audio service URL keeps the service off
HyperFrames Desktop blanks HYPERFRAMES_AUDIO_API_URL and its key while
the analysis route is behind a flag, but gives runs HEYGEN_API_KEY and
HEYGEN_API_URL for its gateway. Falling back to that credential would let a
run that passes --quality best reach the route anyway. An empty URL now turns
the service off, whatever credential is present.
* fix(ci): capture package name in release-age exclusion
(cherry picked from commit f9c6ba3573)
* fix(cli): resend the stems request with its key until the service answers
The stems service answers once the stems are made, which can outlast the
connection, and answers 409 request_in_progress to a resend while the first
request runs. A failed job's reason is failure_message.
* fix(cli): retry incomplete stem separations
* test: validate audio mock route handlers before dispatch
* test: trace premature Windows CLI runner exits
* test: remove temporary Windows runner diagnostics
* fix(cli): keep whisper CJK tokens as separate timed words
whisper.cpp marks word boundaries with a leading space, but Chinese and
Japanese tokens never carry one, so parseWhisperCpp merged every CJK token
into the previous word, across segments too. A 9.5-minute Mandarin episode
came out as two "words" of about 280 s each, leaving captions and
sentence-building nothing to split.
A token now starts its own word when it crosses a CJK boundary, full-width
punctuation still attaches to the word before it, and cues end at 。！？.
* fix(ci): capture package name in release-age exclusion
Blur that turns itself off is silent in the output, so an author who asked for
data-motion-blur="on" cannot tell. Have hyperframes check read the runtime's
decision through probe() and the reason codes from the previous change.
check reports motion_blur_off as a warning with a fix hint for a root that
asked for blur and got none (an iframe in the root gets its own hint),
motion_blur_no_movers when nothing moves enough to blur, and
motion_blur_unverified when the check browser has no html-in-canvas to decide
with. The console echo of the same message is dropped so a finding is not
shown twice.
check asks the runtime which root wants blur instead of reading attributes
itself, so data-root="true" is honoured, and after probing it suspends blur
painting for the rest of the session: its audits read plain DOM, which removes
the roughly 10x slowdown of auditing a wrapped composition. It never sets the
page's off switch, which would change the probe's answer.
Tests drive a finding from the page to the check output, with its fix and
without its echo.
Folded review fixes: R9 (check hint), R12, R13 (check half), T6.
Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
Carry the runtime's blur through the render pipeline and the Studio render
panel.
- engine: installPageMotionBlur sets the page-side off switch and the render's
device scale before any author script runs; CaptureOptions.pageMotionBlur
lets a caller stand the page blur down.
- producer: a composition that asks for data-motion-blur on the root the
runtime would pick forces screenshot capture, because html-in-canvas needs
a real paint; the probe session carries the request's pageMotionBlur like
every other session.
- studio-server and Studio: the render panel sends previewMotionBlur, the
render route turns "off" into pageMotionBlur once, and the Studio dev server
and the CLI server both receive the final value.
- mover scan: a large element that is see-through while it moves (a sweep, a
light leak) is no mover, including a large image or canvas with alpha; the
scan skips elements moved by a 3D individual transform property.
- cli snapshot injects video frames before the seek settles, matching the
engine's order.
Folded review fixes: R1, R2, R3 (scan half), R7, R16, R18, T3 (render
adapters).
Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
* 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>
* feat(cli): cloud render uploads heavy media as HeyGen assets
Media of 5 MB or more leaves the project zip: it uploads through the
direct-upload flow as a HeyGen asset and the zip's HTML and CSS point at
the asset URL. Uploads are cached by content hash and re-checked before
reuse. Media the asset API refuses or caps is re-encoded at visually
lossless quality first. The zip must end under 200 MB or the command
stops and names the largest files left.
* feat(cli): cloud render offloads GIFs, still images and script-referenced media
Animated GIFs in the entry composition go through the renderer's own GIF
preparation and upload as the resulting video. Still AVIF, GIF, BMP and
TIFF images convert to PNG. Plain string literals in scripts and JSON that
name offloaded media point at the asset URL. ffprobe calls end their
options with "--", and two comment lines are trimmed for the ratchet.
* feat(cli): cloud render uploads only the parts of long media a composition plays
A video or audio file that has to be re-encoded is cut to the union of the
windows its clips play, with half a second of margin on the source's frame
grid, and the staged composition's media starts shift to match. Clips in
sub-compositions, looping clips, speed ramps and files a script names keep
the full file.
* fix(cli): cloud render no longer decodes media files as text when rewriting references
* fix(cli): cloud render keeps media chosen at render time and encodes the staged bytes
Only media a reference points at is offloaded, so a file picked through
--variables or built by a script stays in the zip. Variable-bound clips and
clips with a media fragment keep their full length. Entry GIFs resolve the way
the renderer rebases a nested entry and are prepared only from 5 MB, and every
encode reads the staged bytes its cache key hashes. Query strings and media
fragments survive the rewrite, a null cache file reads as empty, and the docs
say asset URLs are public and unsigned.
* fix(cli): cloud render comments cite only what this repo holds
* fix(cli): cloud render handles media over 2 GiB and explains a too-large upload
Media of 5 MB or more stays on disk until it is used: it is hashed and uploaded
as a stream, and a file edited after staging stops the run instead of caching
the wrong upload. Files left in the zip are sized before any is read, so a
4 GB file reports "too large" instead of crashing.
The asset API rejects an over-limit upload as invalid_parameter with "File too
large"; that now gets the dry-run hint instead of the --help one.
* fix(cli): cloud render checks and reads each staged file through one handle
Staging, the on-disk staged read and the re-encoded output read each opened the
path twice: once to stat, once to read. A file swapped or edited between the two
could be read without the size or change check seeing it. Each now opens once,
checks the open file's stat before and after the read, and reads from it.
* test(cli): a heavy file a script builds from split strings stays in the cloud render zip
* fix(cli): cloud render keeps media scripts may reach and never trims clips scripts retime
- An offloaded file keeps its zip copy when script code holds both its stem and
extension, so a path joined at runtime still loads.
- Entry GIFs are prepared from a private copy checked against the staged file,
so the GIF cache never stores a later edit.
- No cut when any script can write a clip's timing attributes, dataset,
currentTime, playbackRate, src or loop.
* test(cli): drop the orphan cleanup tests that read the runner's live process table
* fix(cli): a preview refused inside a host app no longer kills orphaned Chrome
* 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
* chore: release v0.8.182
* chore: list #5953 in the v0.8.182 notes
* chore: add #5843, #5932 and #5945 to the v0.8.182 notes
* chore: add #5923, #5943, #5956, #5960, #5961, #5963, #5964 and #5966 to the v0.8.182 notes
* chore: add #5972, #5977, #5981 and #5982 to the v0.8.182 notes
* chore: add the 13 PRs merged since the last refresh to the v0.8.182 notes
* chore: add #6003, #6005 and #5579 to the v0.8.182 notes
* chore: add #6006 to the v0.8.182 notes
* 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
* fix(lint): place each scene's audio at its host's start in the audio overlap check
* fix(lint): drop internal tags from two comments
* fix(lint): check audio in scenes chained by a reference start
* fix(cli): a finished capture exits even when a site's DNS never answers
Capture resolved every page request with the system lookup and gave up after
10 s, but a system lookup cannot be cancelled: the abandoned one kept the
process alive until the OS resolver timed out, so a capture that had printed
its result could run past the app's 5-minute cap and lose its folder.
Resolve through c-ares instead, as hostAnswers does, and cancel it at the
same 10 s deadline.
* test(cli): a capture lookup that answers must exit right after too
Dropping the timer cleanup kept every successful lookup alive 10 s and no test noticed.
* fix(cli): capture falls back to the system lookup and exits once its result is out
c-ares answers first. When it has no answer, the system lookup (hosts file, OS-only DNS)
runs in a child process killed at the 10 s deadline, cached per host, because Node waits
for an in-process system lookup even in process.exit. Capture then asks the CLI to exit
100 ms after printing its result, as render does.
* fix(cli): capture reads the hosts file first and kills its lookup child on exit
The hosts file answers before DNS, as the system lookup does (overrides and 0.0.0.0
blocks keep working). A host whose system answer is cached skips c-ares, a caller that
joins a running lookup keeps its own deadline, and a pending lookup child is killed when
the CLI exits.
* fix(cli): capture's forced exit waits until a slow reader has the whole result
The root exit now waits for stdout and stderr to hand over what is already
written before it calls process.exit, so a large JSON result on a slow pipe
arrives complete. A hostname listed several times in the hosts file now has
every address checked, not only the first.
* fix(cli): keep process exit in the CLI root and let test fixtures exit
The output wait is now a helper that only waits; cli.ts still owns the
process.exit. The process-ownership check treats test fixtures like tests,
since each one runs as its own process.
* chore(cli): run the process-ownership check before every commit
A process.exit outside a process root used to pass the local hooks and fail
only in CI's Preflight.
* 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
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.
* 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
* 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.
The root (and propagated body) background paints the page canvas whatever its
visibility, so an animated page background could make a still scope read as
moving. Scoped captures now clear those backgrounds and keep the resulting
transparency, and the frame comparison reads alpha, so dark paint revealed on
the cleared page still counts.
* fix(cli): check no longer calls films moved by SVG masks, strokes or canvas static
The frozen-sweep guard compared DOM-channel fingerprints only, which never see
SVG mask and clip contents, stroke dashes, or canvas and WebGL pixels. Before
reporting sweep_static, check now compares the rendered frames at the same
sample times; a still verdict stands only when every frame is identical.
* fix(cli): keepsMoving also trusts rendered frames, compared above render noise
keepsMoving read the same DOM liveness channels as the sweep guard, so mask,
stroke and canvas motion failed it as frozen. A span it calls frozen now gets
a frame capture every half maxStaticSec, and spans split where the frames
change. Frames are compared in the page, decoded like the contrast pass, and
count as moved only when at least 16 pixels change by more than 24/255, so
antialiasing and dither noise cannot make a still film pass.
* fix(cli): scoped frame checks see only the scope's own paint
A keepsMoving scope's capture now hides every box outside the scope's subtree,
so a still title over a moving background stays frozen. A span marks only the
frames that still hold its signature, so a span that starts at a cut keeps its
first frame. A scope that matched nothing stays motion_selector_missing. The
sweep counts a frame change only if the first sample time still renders its
first frame, so wall-clock paint is not read as motion under seek.
Color grading paints a video or image into a canvas the runtime inserts right
after it. The layout audit treated that canvas as authored canvas art: the
video's data-layout-* opt-outs never reached it, and canvas_content_at_edge
read full-bleed footage as drawn content cut by the frame. Opt-out lookups now
resolve a grading canvas to its source element, and the edge rule leaves
grading canvases alone, as it does the ungraded video.
* fix(cli): check, snapshot and Studio read project text as UTF-8
The preview servers sent HTML, CSS, JS and JSON with no charset, so Chrome
read a page without <meta charset> as windows-1252 and stills showed garbled
non-Latin text while the render, whose file server already sends utf-8,
was correct. The shared MIME table now carries charset=utf-8 for text types,
and the two hard-coded headers use it.
* fix(cli): snapshot shows accented text when the page's meta charset sits outside its head
A <meta charset> past Chrome's first 1024 bytes and outside <head> is ignored, so with no
charset in the header the page decoded as windows-1252. The browser test serves such a page
through the static server snapshot uses. play compares the media type without its charset,
so JSON assets keep their content-hash revalidation.
A check on a project whose videos Chrome cannot decode (HEVC, HDR) first transcodes each
of them, which on phone footage takes minutes and printed nothing until it was done.
* perf(cli): commands run without esbuild, puppeteer-core or sharp until they need them
A host that bundles the CLI can now leave these packages out: each command
loads them only where it uses them, and sharp installs once on first use when
it is missing. The build check fails on any static import of them again.
* fix(cli): use a host's sharp from NODE_PATH and let hosts turn first-use installs off
* fix(cli): capture fails when sharp is missing, and one install serves every caller
A missing sharp now stops the asset download up front instead of counting every
image as unavailable. Concurrent first uses share one install, a failed install
is not retried in the same run, and preview thumbnails report why. Hosts can turn
off installs for a list of packages, e.g. HYPERFRAMES_NO_OPTIONAL_INSTALL=sharp.
* fix(cli): snapshot --describe still works without sharp, resizing only when it is installed
* style(cli): format the sharp loader and its tests
* build(cli): sharp is an optional dependency, so a host can ship the CLI without it
* build(studio-server): keep sharp out of the bundle now that it is optional
* test: queue runs on slow windows runners stop failing four timing tests
* test(cli): the keepalive process test budgets for a cold start on a slow runner
* fix(cli): wait for consent navigation before cataloging assets
A consent click can reload the page (some CMPs reload once consent is
stored). The post-click DOM reads then raced the navigation: the overlay
sweep and scrollHeight probe ran against a torn-down or still-parsing
document, scroll screenshots degraded to a handful of shots, and the
asset catalog observed an empty body (0 assets).
Add waitForPageReady: wait for network idle, then poll document.readyState
so a committed-but-still-parsing reload is also waited out — network-idle
alone stops counting a request once its response headers arrive, and
waitForNavigation deadlocks when armed after the commit. The overlay
sweep now runs on the settled document instead of the pre-reload one,
and the same settle guards the asset catalog boundary.
Fixes#4923
* fix(cli): bound consent-click settle by wall clock and skip it on banner-free pages
waitForPageReady now shares one deadline (timeoutMs, capped by the
remaining capture budget) across its network-idle waits and readyState
poll, uses waitForNetworkIdle concurrency: 2 (the networkidle2 semantic
navigation already uses), races each readyState evaluate against the
deadline, and rethrows degradable evaluate timeouts so the stage can
degrade. captureScrollScreenshots only pays the settle when the consent
sweep clicked a control or performance.timeOrigin shows the document was
swapped; the catalog boundary call degrades to a budget-bounded
readyState check (networkIdle: after-load).
* fix(cli): drop added comments to keep comment share at merge-base
* fix(cli): adapt consent-settle tests to ScreenshotCaptureResult and keep comment share flat
* fix(cli): tolerate missing waitForNetworkIdle in consent settle
waitForPageReady called page.waitForNetworkIdle unconditionally; a
Page-shaped double without it throws a synchronous TypeError that
captureScrollScreenshots' catch-all reports as internal-error with
zero screenshots, breaking the partial-budget contract upstream's
coreExtractionPhase.test.ts exercises with a thin mock page. The idle
wait is best-effort, so make the hook optional and swallow its
failures; also only keep the readyState poll alive while the page
affirmatively reports "loading" so a non-boolean result cannot burn
the settle deadline.
* perf(cli): check splits its samples over a second Chrome when a core and memory are spare
* fix(cli): check keeps its result when the second Chrome fails, and counts container memory
* fix(cli): check's helper Chrome code keeps the files' comment share
* fix(cli): check's sampling comment fits the line limit
* chore: release v0.8.180
* docs(release): describe chunk sub-ranges as groundwork for split retries
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* chore: release v0.8.180 notes list the empty-frame fix
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: Miguel Ángel <miguel.sierra@heygen.com>
* perf(cli): snapshot decodes phone video frames at their on-screen size, several at once
* perf(cli): snapshot decodes phone video frames at their on-screen size, several at once
* test(cli): type the displayed-size snapshot cases instead of splitting strings
* feat(cli): lambda deploy works from the npm install, no repo checkout
Each release builds the Lambda handler zip on Linux, attaches it to the
GitHub release, and pins its URL and sha256 (plus the SAM template) in
@hyperframes/aws-lambda before npm publish. Outside a checkout, lambda
deploy downloads that zip, refuses it on a sha256 mismatch, and deploys
it with the packaged template. With neither a checkout nor a pinned zip
it fails up front with one message naming every way out.
* fix(cli): lambda deploy test mocks the pinned-handler reader, comments fit the checks
* test(cli): sam tests deploy from a SAM directory, not the repo root
* chore(aws-lambda): raise the package size budget for the pinned handler template
Measured with pnpm@10.17.1 pack on Linux. Release state (prebuilt/ written by pin-handler-zip): 77,307 packed / 285,654 unpacked. CI state (no prebuilt/): 70,104 / 253,390. Packed is the check's 5% headroom over the release size. Unpacked is 292,000 (2.2% over release) because a 5% budget would put the CI pack under the 85% ratchet.
* test(cli): anchor the docs link check in the lambda deploy fallback test
* fix(cli): lambda deploy logs the verified handler sha256 and keeps a presigned query out of errors
* fix(cli): a redirect-limit download error keeps a signed query out of its message
* test(cli): the redirect-limit leak test types its rejection
* docs(aws-lambda): header comments cut to what the code cannot say
* chore(aws-lambda): size budget fits both the CI and the release package
* fix(aws-lambda): old stacks are refused before any upload; stale local copies never re-upload
* docs(aws-lambda): where the CLI keeps a deployed stack's state
Miguel Ángel