* fix(studio-server): reject cross-origin state-changing requests
Non-GET routes in createStudioApi answer 403 unless the shared
sameOriginPost predicate (lifted into studio-server's ./request-identity
subpath) accepts the request: the Host must be a server identity, a
present Sec-Fetch-Site must be same-origin, and a present Origin must
match the effective host and scheme. Hosts behind Codespaces or tunnels
allow their public name with HYPERFRAMES_PREVIEW_ALLOWED_HOSTS, read by
`hyperframes preview` and the Studio dev server.
Squashed from #6128 (42574a7, 110a300, 89011e1, 41c6626, 27193bb) onto
current main.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cli): the preview server answers only the hosts it is reached by
Every route of `hyperframes preview` (the forwarded studio API, the SSE
stream, /__hyperframes_config and the Studio page) now answers only
loopback names, the HYPERFRAMES_PREVIEW_HOST bind, or a host listed in
HYPERFRAMES_PREVIEW_ALLOWED_HOSTS, the same list the write guard uses.
Only the Host header counts here, since a page can set X-Forwarded-Host
on its own requests and a read carries no Origin to compare it with.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Dextheking1 <Dextheking1@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* docs(studio-app): the Reference read is paid by Pro or a saved HeyGen API key
ReferenceAnalysis readGate: a saved usable key pays the read; without one
the plan gate opens the plans page (feature video_analysis). The page said
only the API key paid.
* docs(studio-app): a saved key comes first, and a used-up pro allowance opens plan and usage
* docs(studio-app): pro credits pay for the reference read first, a saved key when the plan can't
* docs(studio-app): cloud exports come with the plan, not only an api key
The export page said cloud renders are always paid per minute from a HeyGen API balance. The app
now includes 5 cloud exports a month on Free and unlimited on Pro (plans.ts, cloudFit.mjs).
* docs(studio-app): export destination and api-key billing wording
* docs(mcp): current ChatGPT setup steps, and the hosted render's real output
OpenAI moved custom MCP servers to Plugins > + > Add custom MCP server,
on Business, Enterprise and Edu only. The hosted render takes no format
or fps (render_video has a TODO to expose them), so the page no longer
suggests asking for 30 fps, WebM or MOV there.
* docs(mcp): connect from the claude directory, and name hyperframes in the first prompt
HyperFrames by HeyGen is listed in Claude's connector directory. In a Claude.ai test on 6 Nov
2026, a request without "Use HyperFrames" made Claude write its own video code instead of
calling the connector.
* docs(mcp): where to switch the connector on in a chat
* docs(changelog): weekly digest 2026-11-02-2026-11-09
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* docs(changelog): embed the Nov 2-9 weekly video
* docs(changelog): drop the 2k alias and name fixes as described above
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Follow-ups from review on #7443 and #7444:
- The quote hint returned the first run of words that existed, so a
"Final Cut/" folder hid "Final Cut export.mp4". It now names the longest.
- "--compare=my clip.mp4" got no hint; the value after = now starts a run.
- The telemetry section lists the skill a reverse or templates command ran
for, and the HeyGen session id a recorded reverse run carries.
* fix(core): detect template entries structurally
isTemplateEntry only matched a raw file that starts with <template>, so the
full-document sub-composition shape (<!doctype html><html><body><template>
<div data-composition-id>...</template></body></html>) was not recognised and
resolveEntryHtmlPath compiled the raw file, whose root sits in an inert
template: no timeline, no duration, "Composition has zero duration".
A template entry is now a document whose <template> holds the composition
root with no live composition root outside it. Detection and extraction share
one lookup (locateSceneRoot), the same one readSceneRoot uses.
— Jerrai
* fix(core): drop comments from the template lookup
The comment ratchet allows no net rise in a file's comment share; the PR
description carries the explanation.
— Jerrai
* fix(core): find the scene template among several templates
locateSceneRoot read only the first <template>, so a scene template that
follows another template was treated as not a template entry. Scan every
template and take the first whose content holds a composition root.
* fix(core): drop the added comment (comment ratchet)
* chore: raise the inspector unpacked size budget by 0.5%
The inspector bundles core; the multi-template scene lookup added a few
hundred bytes and put it 10 bytes over the 1% tolerance.
* fix(core): refuse a file with several scene templates, naming them
* chore: trim the inspector size budget bump to what is needed
* fix(core): render the first scene template and lint the ambiguity instead of failing
A file with several scene templates and no live root rendered its first one
before; locateSceneRoot threw and stopped such projects rendering. It returns
the first again, and the multiple_scene_templates lint warning names each.
Co-authored-by: Jerrai <jerrai@heygen.com>
* chore(core): drop the locateSceneRoot comment line the comment ratchet counts
Co-authored-by: Jerrai <jerrai@heygen.com>
* fix(core): one shared scene-template pick for the compiler, the inliner and the loader
A scene template after a card template was detected by locateSceneRoot but
mounted from the first template of any kind, so it rendered blank.
findSceneTemplate picks the first template holding a composition root and
locateSceneRoot, resolveSubCompositionContent and the loader all use it.
Co-authored-by: Jerrai <jerrai@heygen.com>
* feat(cli): reverse and templates report their own runs; commands say which skills are installed
Gaps in what skill telemetry can answer for /reverse-any-video and
/style-sampling:
- The skill's beacon fires only when the agent runs it, and agents often
skip it. `reverse start` and `templates pull` now send `skill_invoked`
with `source: command`; beacons carry `source: beacon`. A person counts
once.
- style-sampling renders were never tagged. A pull marks the project the
episode is built in (only a folder that is already a project).
- Installs of an on-demand skill were invisible. `cli_command` carries
`skills_installed` and `skills_outdated`, the names from the cached
background skills check, so "never triggered" and "not installed" can
be told apart.
- `auth status` signed out exits 1 with a bare "Command failed", which
reads like a login failure. It now carries `NotSignedIn`, and an auth
error its own cause.
And a step that gets lost: a reverse started signed out often goes on
without ever trying to sign in. `reverse start` signed out now prints
`login_command` and a `next` line in the JSON the agent reads, not only
in the skill's reference.
* refactor(cli): keep comment share at the base in the reverse telemetry files
* fix(cli): command runs get their own event, counted once per piece of work
Review on the first cut: `skill_invoked` from the commands doubled the
#7176 beacon's single observation, and it fired before any work.
- `reverse start` and `templates pull` send `skill_command_ran`, not
`skill_invoked`; the beacon is back to its #7176 shape.
- `reverse start` sends it after the probe, with `signed_in` and the
reverse `session_id` that keys a retry; a video it cannot probe sends
nothing.
- `templates pull` sends it only when it downloads; a re-pull or a
refused pull sends nothing.
- A skills check that finds no install forgets the installed names.
- `auth status` failures carry only a code, never the auth error's text.
* feat(skills): reverse-any-video and style-sampling install with the core set
A skill only triggers when it is installed. On demand these two rarely
were, so a request to copy a video or make an episode in a proven style
seldom reached them, and the entry skill named only one of them, in its
closing line.
- isCoreSkill, FALLBACK_CORE_SKILLS and the marketplace `core-skills`
entry include both, so `init` and `skills update` install them. The
`hyperframes` plugin already bundled every skill.
- `/hyperframes` routes to both from the top of its table: a video to
copy or remake, and an episode in a proven style. Its budget takes
+64 B for those two rows.
- `/reverse-any-video` triggers on "remake" and on 「复刻这个视频」
「照着做一个」, inside the 320 B description cap.
- Every catalog surface lists both in the core group: CLAUDE.md,
AGENTS.md, README, the skills guide, skill-lifecycle and the two init
templates (still byte-identical).
* refactor(cli): keep comment share at the base in skillsManifest
* feat(producer): distributed and range renders honour page motion blur
A film with data-motion-blur="on" blurs the same way however it is rendered. plan() no longer
forces the synthetic job to pageMotionBlur "off", so the plan locks screenshot capture for a
blurred film as a whole render does, and renderChunk() no longer defaults the page's off switch
to "distributed-render". An explicit pageMotionBlur "off" in the config still stands the page down.
Hosted renders pick this up after the next OSS release and a producer pin bump; a render of a
blur-on film that goes distributed changes output then.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* test(producer): the default tier blurs the same in chunks; docs agree distributed renders blur
Two files compare plan -> renderChunk -> assemble with the tier attribute removed, so `auto`
(the filter tier) decides, against a whole render: held-card and callbacks (the muted-callback
path). The skill's motion reference no longer says distributed renders are off. The rewritten
R19 plan test gets 60 s for its three plan() calls.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
* feat(cli): add 1440p resolution presets to --resolution
Adds landscape-1440p (2560x1440), portrait-1440p (1440x2560) and
square-1440p (1440x1440) next to the existing 4K, 720p and 480p tiers,
with the aliases 1440p, 2k and qhd plus 1440p-portrait and 1440p-square.
1440p joins the aspect-agnostic aliases, like 720p and 480p.
Every validator derives from CANVAS_DIMENSIONS, so no logic changes: a 4K
composition renders down to 1440p through the existing smaller-preset
path, and a 1280x720 composition supersamples to 1440p at an exact 2x.
A 1920x1080 composition is still refused by the non-integer-scale check
(4/3); fractional scale factors are not part of this change.
Refs #6309
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* fix(cli): clarify 1440p aliases and repair skill validation
---------
Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-authored-by: James <james.russo@heygen.com>
* feat(cli): check returns an unchanged project's last pass in about a second
* fix(cli): the check cache hashes files without a stat race and its tests run before the signal test
* test(cli): the warm check test compares two real runs, not a run and its cached pass
* feat(cli): check --no-craft skips the craft pass for a render preflight
* fix(cli): the check cache keys on timeout, env and large files and never replays a moved tree
* style(cli): format the check cache
* fix(cli): the large-file cache test waits for the clock tick it depends on
* fix(cli): the check cache keys on the browser and on scripts under .hyperframes
* fix(cli): the check cache ignores the video copies the check itself touches
* fix(check): lint and check skip compositions the project never mounts
* refactor(lint): let two new names stand without doc comments
* test(cli): lint tests that lint unmounted files say so
* fix(check): masked or clipped-away text no longer counts as overlapping
* test(check): name the masked-overlap fixture's headings in plain words
* test(check): word a gradient-stop comment without an acronym
* fix(check): a moved or content-box mask keeps today's overlap verdict
The desktop app can't run an edit while a preview of the project is
running, because the preview holds the project's history lock. Following
the hint that `preview --background` prints therefore left the app's edit
waiting until someone stopped the preview by hand.
`hyperframes open` now stops a background preview of the same project
before handing it to the app, and prints one line saying so. It only
stops a preview it can prove it started (a saved session whose wrapper
process still owns the server). Any other preview is left running, and
`open` prints the exact `preview --stop --port N` command instead. With
--json the result carries a `preview` field.
The hint that `preview` prints now says that `open` stops a background
preview, or that a foreground one must be stopped first. The project
template and the CLI skill's preview reference say the same.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(check): a Chrome that never becomes ready ends the check with a named error
* fix(check): name the Chrome start window in code instead of comments
* feat(cli): audio --read --layer music|sfx|voice reads a one-layer file whole
A caller that knows a file holds a single layer can declare it: the file is
read whole as that layer with no stem separation and nothing uploaded.
Without the flag the read is unchanged. An unknown layer is rejected.
Consumer: heygen-com/experiment-framework#66322. Proposal OK'd by Rory
(C0BEH487Q7R, 2026-11-07).
Co-Authored-By: Jerrai
* chore(cli): drop added comments from audio read layer
Co-Authored-By: Jerrai
* feat(core): motion blur reports what a composition holds, as counts
The runtime scans a composition once per blur scan, on both tiers, and reports
counts of what it holds (canvases, video, frames, custom elements, clips, masks,
scroll containers, 3D, blend modes, and movers that overflow, sit under other
content, hold fixed children or carry pseudo-elements outside their box), plus
whether pose reads need callbacks. Counts only: no ids, classes, text or URLs.
The engine puts the non-zero counts on its [motion-blur] line and hands the
parsed report to the perf summary; the producer aggregates workers (first report
wins, failed frames sum) and the CLI sends motion_blur_* properties on
render_complete, from the CLI and from Studio renders.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* fix(cli): disclose blur counts in telemetry docs, raise inspector budget
The runtime fingerprint code is bundled into @hyperframes/inspector, which
puts its unpacked size 2.2 KB past the 1% tolerance. The telemetry docs now
list the composition counts the CLI sends with a blur render.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
* feat(core): auto motion blur draws with the filter tier
Capture stays available as data-motion-blur-tier="capture". auto now draws with the
filter tier (reasonCode tier-auto), so the capture-only defects leave the default path.
Removes the translation-only hand-off and its Discovery field, adds a filter arm to the
differential, and updates the check, guide, skill and Blur panel label.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* docs(core): measured cost and known limits of the filter tier, the new auto default
spacex-launch (77 movers) takes 2.9x the CPU of no blur on the filter tier and 1.7x on
capture; say so, and list the filter tier's measured limits (sweep D, E, F, I, O, B).
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* docs(core): word the filter tier's cost and limits as measured, not as mechanism
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* docs(core): do not say every filter-tier limit is pinned by a sweep test
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* test(engine): split the blur differential so each file fits the flake gate's 120 s run
The filter arm moves to its own file and skips fixtures that already draw with the filter
tier; inside cases get their own file; a fixture's blur-off page is opened once per file.
Shared helpers live in __fixtures__/motionBlur/differentialPage.ts.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
* chore: release v0.9.17
* chore(producer): raise the unpacked size budget for windowed video frames
The new modules and this version bump put the unpacked package 49 bytes
past the 1% tolerance. No tests or source maps are in the tarball.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* feat(producer): render long videos with windowed source frames, behind HF_VIDEO_FRAME_WINDOW
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(producer): windowed calibration sees real frames, and the late full extraction reports itself
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(producer): windowed frames match a full extraction, frame for frame
Renders ten compositions twice on the segmented route, with and without
HF_VIDEO_FRAME_WINDOW, and compares FFmpeg framemd5 of the two outputs: a
mid-clip start, NTSC 24000/1001, a loop crossing a slice edge, a playback-rate
ramp, a held tail, two clips of one file, a VFR source beside a CFR one, two
workers, auto workers (capture calibration runs), and motion blur, which
declines the window. Each pair must also report the same capture mode.
A separate test samples segment-frames during a four-segment, two-worker
render and holds its peak under workers x segment frames x the largest frame
file x 1.2, and checks the folder is empty once the render closes.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* test(producer): windowed frames test finds its own work dir and asserts what it claims
Find the render's work dir with resolveRenderWorkDirPrefix and the owner record's pid, so
the peak test works on Linux and never samples or deletes a concurrent render's dir.
Assert the measured worker count, calibration, and the exact up-front frame count of the
VFR video. Retry a dead Chrome only with HF_TEST_RETRY_BROWSER_STALL=1, and fail a case
whose windowed render alone needed it.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* fix(producer): windowed segments honour keep-segments and cleanup never fails a render
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* refactor(producer): trim the comments the windowed frames route added
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(producer): the VFR-beside-CFR extraction test moves to the integration lane
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* chore(producer): raise the package size budget for windowed video frames
The new segment frame modules add about 9 KB to the packed producer package.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(producer): windowed frames header says what the real runs measured
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cli): normalize-audio --reference stops short of the peak ceiling instead of refusing
* docs(cli): the README says normalize-audio stops short of the ceilings instead of refusing
* feat(cli): check --budget stops the whole check in time and reports what it found
* fix(cli): keep check's comment share where it was
* fix(cli): a --budget that runs out before any check step is waiting is not an unhandled rejection
* feat(cli): info --media lists every clip the render hears, on the film's clock
* fix(cli): info --media leaves out a clip that starts past its media's end
* fix(cli): keep the heard-clips doc line within 120 characters
* fix(cli): every settings file follows HYPERFRAMES_CONFIG_DIR
* fix(cli): the media-use skill copy reads its config from HYPERFRAMES_CONFIG_DIR too
* test(cli): expect the config folder as a normalized path on every platform
* chore(skills): refresh the media-use manifest hash
* fix(cli): a moved settings folder starts from ~/.hyperframes, keeping an opt-out
* fix(cli): drop the updater's unused path import
* style(cli): keep the settings-seed comment under 120 characters
* fix(cli): a preview's session follows HYPERFRAMES_CACHE_DIR when it is set
* docs(cli): background previews follow HYPERFRAMES_CACHE_DIR
* test(cli): unstub the preview test's env in a block body
* test(cli): clear HYPERFRAMES_CACHE_DIR in the CLI's test home
* fix(cli): registry cache, search model, catalog and catch-up follow HYPERFRAMES_CACHE_DIR
* style(cli): format the media search cache test
* test(cli): compare the model path against an absolute cache folder on Windows too
* fix(cli): both catalog readers treat an empty HYPERFRAMES_CATALOG_ARTIFACT_DIR as unset
* feat(registry): add path-traced-3d example with raster preview and path-traced export
An opt-in Three.js starter: previews with raster rendering and exports with
three-gpu-pathtracer, from one scene file. three 0.180.0, three-gpu-pathtracer
0.0.24 and three-mesh-bvh 0.9.5 ship as one local, pinned ES module with their
licences and a rebuild recipe, so renders make no network requests and 2D
projects never load the tracer.
Setup is one buildReady promise that awaits library readiness promises only
and ends with a throwaway frame and a one-pixel readback. Frames are drawn in
the hf-seek listener through waitUntil, each time from zero with a fixed
sample count. Math.random is seeded while the scene and tracer are built,
because object ids order light sampling and the tracer's noise textures come
from it.
Adds a skill reference and a docs guide for the setup and seek contract, the
frozen clock, why scheduler.yield() waits hang, and sample/bounce cost.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(registry): list path-traced-3d in CLI docs and tighten its notes
Add the example's section to the CLI examples doc, which docs.test.ts
requires for every registry example. Throw if the tracer reports compiling
but exposes no compile promise, instead of spinning renderSample(). Say that
three's object uuids set the tracer's sort order, that later-created objects
need the seed too, and that Date and performance.now read the current seek
time during a render rather than staying at 0.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(cli): reverse start makes its --dir project, and init takes the video already in it
Bug bash: production has no reverse/start route yet, so every run came back unrecorded,
and reverse start then made no folder and no hyperframes.json. The agent downloaded the
video into the folder it named, and init refused it as not empty, so agents moved files
around. reverse start now makes --dir and stamps it with the skill when no session is
recorded, and init accepts a folder whose only other files are its --video or --audio.
* refactor(cli): say in names what the comments said, so the comment share holds
* fix(cli): init keeps an in-folder source safe, and saved_to only names a stamped config
- Only an audio or video file in the folder counts as the source; a file named
index.html, meta.json or AGENTS.md is refused, so the scaffold never writes over it.
- An in-folder .mp4 that needs transcoding goes to <name>.h264.mp4 beside it,
instead of being both ffmpeg's input and output.
- reverse start names saved_to only when hyperframes.json now holds the skill;
a broken config is left as it was and saved_to is null.
* fix(cli): init transcodes an in-folder .MP4 beside it on case-insensitive disks too
original.MP4 and original.mp4 are one file on macOS and Windows, so the
same-file check now ignores case. The test's ffprobe call gets its --.
* fix(cli): init tells the source in the folder by the file, not its spelling
On a case-blind disk --video original.mp4 names Original.MP4, so the folder
check and the copy now compare device and inode; a source named in another
case is accepted and never copied onto itself.
* fix(cli): init transcodes only to a name with nothing at it, so a linked alias is never the output
The folder guard admits every alias of the source by file identity, but the
transcode output was chosen by path spelling. A hard link or symlink at
name.mp4 or name.h264.mp4, or a source named through a linked folder, made
FFmpeg (-y) rewrite the original. The output is now the first of name.mp4,
name.h264.mp4, name.h264-2.mp4, ... with nothing at its path (lstat, so a link
counts), which also covers a case-only spelling on a case-blind disk.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HebQXN7wsMK6GqT3MNtqXw
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>