Commit Graph
132 Commits
Author SHA1 Message Date
Michael WangandClaude Opus 5.5 ac02474105 fix(cli): play and present check the Host like preview; local render leaves out outside files for a received composition (#7792)
* fix(cli): a subfolder of an imported project keeps its received-files record

Publish, cloud render and feedback now read the received-files record at
the nearest folder at or above the one they stage, so staging a subfolder
of an imported project still leaves out the outside files its received
files reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): a received file counts under any spelling of the same file on disk

The received-files lookup now also matches a project file that is the
same file on disk as a listed path, so a name respelled in letter case on
a case-insensitive disk keeps its received status.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): cloud render prepares only the GIFs staging kept

The entry GIF prep before a cloud render upload now reads only the staged
copies it is handed. An image whose source staging left out keeps its
reference as written and is never read from disk.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli,studio-server): never hand a playlist named as media to ffmpeg

A media file whose first bytes are an HLS playlist, an XML manifest or a
concat script now stays out of ffprobe and ffmpeg: cloud render leaves it
in the zip as authored, the media probe reports it as not media, and the
proxy copy refuses it. Real media never starts with these bytes, so it
probes and transcodes as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(studio-server): catch playlists with control bytes, and keep them from stills and audio probes

A text playlist or concat script is detected whatever bytes follow its
first line; only markup must be all text. A still frame and the audio
probe behind waveforms, peaks and loudness now refuse a file the probe
reads as not media, as the proxy copy already does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): a parent folder's state the CLI cannot read never marks a project received

The walk up for a received-files record now skips a parent whose record
cannot be reached. Only a record file that is there but cannot be read
or parsed counts every file as received.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): a drive that reports no file ids matches no received file by identity

Some network and virtual drives report a file id of 0 for every file, so
the same-file match now gives such a file no identity instead of
matching it to every listed file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(studio-server): read a media file's first bytes with a read stream

The playlist check reads the first 64 bytes through a bounded read
stream instead of a raw file descriptor, and the audio-track probe's doc
comment sits on its function again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(studio-server): raise the packed size budget for the media playlist check

Main packs @hyperframes/studio-server close to the 1% tolerance on the
168500 budget, and the playlist check adds about 320 bytes, which put
the Build over. Set the budget to 172000.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli,studio-server): open media only through self-contained media demuxers

Every ffprobe and ffmpeg input that cloud render offload, the publish
proxy bake and Studio's media helpers open now carries a demuxer
whitelist built from the supported media extensions: MP4/MOV/M4A/AVIF,
Matroska/WebM, MXF, AVI, MPEG-PS/TS, FLV, ASF, Ogg, WAV, MP3, AAC, FLAC,
AIFF and the still-image formats. Playlist, manifest and concat demuxers
can no longer open, whatever a file's bytes say. The proxy's own concat
step is left as it is.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli,studio-server): keep media probe argv flat, and expect the demuxer list in loudness args

Two probe argv literals built from nested spreads are flat again, so
"--" stays the visible second-to-last entry the argv contract checks.
The normalize-audio test expects the demuxer list before the input.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): play and present answer only local host names and allowed hosts

play and present listen on every interface. Each request now passes the
same Host check preview uses: localhost, loopback addresses and this
machine's own addresses and names are answered, and any other host name
gets a 403 naming HYPERFRAMES_PREVIEW_ALLOWED_HOSTS until it is listed
there. Phones and other machines on the network still open them by LAN
address or .local name.

* fix(cli): a local render of a received composition leaves out files outside the project

When the composition a local render opens is listed in the project's
received-files record, hyperframes render (full and range) no longer
brings in files outside the project. It prints one line naming the
references it leaves out and why. An unreadable record counts as
received. A project whose entry is the person's own, or that has no
record, renders exactly as before.

* fix(cli): received-render scan reads safely and treats an unreadable record as unknown

The scan behind the received-composition notice skips a file it cannot
read, finds url() references with a linear forward scan, and reads at
most 2 MB of each file. An unreadable received-files record no longer
counts as everything received for local render: the render keeps
outside files and names the record it could not read. Publish and cloud
upload still treat it as received. The notice now says the render stops
on a sub-composition outside the project rather than leaving it out.

* fix(cli): the studio render of a received composition leaves out files outside the project

The Studio render route applies the same rule as hyperframes render:
when the composition it renders is listed in the received-files record,
the job does not bring in files outside the project, and the server log
names the references it refuses.

* chore(cli): name the unreadable received-files record helper without a comment

* fix(cli): local render refuses outside files when any composition it plays was received

The received-file rule for local render (CLI and Studio) now checks
every page and stylesheet the render pulls in, not only the entry, so
an own index.html that plays a received scene also reads nothing
outside the project, and the notice names the received file. An
unreadable, truncated or empty received-files record refuses outside
files too, as publish and cloud upload do, and the notice names the
record it could not read.

* fix(cli): decide a received render from the files the compiler reads

Local render (CLI and Studio) now leaves outside-file handling as it is
for a project with no received-files record or an empty one, without
scanning anything. When the record lists files, the compiler's own read
list for the composition decides: the bundler runs out of process with a
deadline and reports every project file it reads, so stylesheet imports
and files past any scan limit count. A received file in that list, a
build that fails or runs past its deadline, or an unreadable record
refuses outside files. The scan that names refused references in the
notice is advisory only: it guards every file system call, tracks visited
files by real path, and caps the files and bytes it reads.

* fix(cli,producer): decide a received render with the render compiler's own composition traversal

The producer exports renderCompositionFiles, which walks
data-composition-src with the same resolution, normalization and private
file rules the render's sub-composition pass uses; that pass now calls
the same helper. The received-render decision adds those files to the
bundler's read list, so leading-slash and percent-encoded references the
render reads count. The advisory scan resolves compositions the same way
and reads template contents.

* fix(cli): refuse outside files in a local render whenever the project has received files

A local render (CLI and Studio) reads nothing outside the project when
the project's received-files record lists any file, or cannot be read.
No static list matches what a render consumes: the page loads its
stylesheets and scripts through the browser at capture time, and
scripts can load more, so the decision no longer depends on one. The
reference scan stays only to name what the notice says is left out. This
drops the out-of-process bundler read list and the producer composition
walk added for that decision.

* fix(cli): refuse outside files only when a received file can load other files

A local render (CLI and Studio) reads nothing outside the project when
the received-files record cannot be read, or lists a received file that
can reference others: an .html, .htm, .css, .js, .mjs, .cjs or .svg
name, or content that reads as HTML, SVG or CSS. A project that only
received images, video, audio or fonts keeps bringing in outside files
as before.

* fix(cli): keep outside files only when every received file is positively media, a font or an image

A local render keeps bringing in outside files only when each file the
received-files record lists has a known media, font or image extension
and starts with that type's signature bytes. Any other received file, a
listed file that is missing or unreadable, or a mismatch between name
and content refuses outside files. An ancestor record's entries now
match a subfolder whose name is spelled in another Unicode form; the
entry keeps its own spelling on disk.

* fix(producer,core): a sub-composition must be an .html file

The render compiler and the runtime load a data-composition-src only
when it names an .html or .htm file. Any other file, such as an image or
video, is refused as a page: render stops naming it, and the runtime
reports the load failure without fetching it.

* fix(producer,cli): the render and static file servers forbid type sniffing

Both servers send X-Content-Type-Options: nosniff with every response,
so the browser loads a file only as the type its extension names: an
image or video cannot run as a script or apply as a stylesheet. .cjs is
served as JavaScript.

* test(cli): a received media file in a composition slot is refused as a page

* test(cli): an empty nested received-files record cannot hide an outer record's received page

* fix(cli): a received media file reached under another name refuses outside files

The received-render decision now compares file identities, not names.
It walks the project once, bounded by entry count and time, and refuses
outside files when a hardlink or a symlink with a name that is not
media reaches a received file, or when the walk cannot finish. A
received file with no identity matches nothing, as in the received
files check.

* fix(cli): compare received files by link target and keep outside files for an empty record

A received media file and every other project name are now compared by the
identity of the file they reach with links followed. A linked folder that
leads outside the project, or a file whose identity cannot be read, counts as
unchecked and refuses outside files. An empty received-files record keeps
outside files without walking the project.

* chore: raise the producer unpacked size budget for the composition file checks

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 09:48:01 +00:00
James RussoandClaude Opus 5.5 03ddfb189f fix(producer): render servers only load assets from inside the project (#7579)
* fix(producer): render servers only load assets from inside the project

The HTTP render handlers and the distributed planner now compile with
outside-project imports off: markup that reaches a file beyond the project
directory (through ../, an absolute path, a file: URL or a symlink) is no
longer copied into the compiled directory, served to the page, probed or
extracted. Local `hyperframes render`, `--start/--end` range renders,
`hyperframes benchmark` and Studio renders pass allowOutsideProjectAssets
and keep importing outside files exactly as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(producer): render the symlinked-assets fixture as a trusted local render

The render-symlinked-assets fixture links src/shared to a sibling folder
outside the project to keep local renders working like preview. The
regression harness now reads renderConfig.allowOutsideProjectAssets from a
fixture's meta.json and passes it to the in-process and
distributed-simulated renders, and this fixture sets it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(producer): render servers read compositions and media only from inside the project

Without the trusted-local opt-in, a sub-composition or entry file that
leads outside the project once symlinks resolve is refused, the same as a
../ sub-composition already is. Local media that resolves outside the
project, compiled and download folders, including absolute paths, file:
URLs and percent-encoded ../ paths, is reported as a missing source and
never probed or extracted. Remote media fetched during the render keeps
working. A missing file is no longer probed for the compile-time advice.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(producer): raise the unpacked size budget for the project-folder checks

The producer tarball grows by about 12.5 KB unpacked: the new checks live
in the compiler and render stages, which the index, public-server and
distributed bundles each include. No test files ship in the package.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 02:31:36 +00:00
James RussoandClaude Opus 5.5 80cda85d76 fix(studio-server): run thumbnail captures in an opaque origin (#7528)
* fix(studio-server): run thumbnail captures in an opaque origin

The thumbnail renderer loads each composition as a top-level page, so its
scripts ran on the Studio's origin. The capture document (`?hf-capture`) now
carries `Content-Security-Policy: sandbox allow-scripts`, so those scripts get
an opaque origin.

An opaque page's CORS-mode loads fail without a CORS header. The renderer that
opened the page is trusted, so it adds `Access-Control-Allow-Origin: null`
itself, over that page's own DevTools session, to the loads a frame needs:
- fonts, module scripts and images;
- the `.html` scenes, `.json` and `.cube` files the runtime fetches.
Only GETs of the project's preview files qualify, matched by file type. Both
thumbnail renderers do this: the CLI's and the Vite dev server's.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(studio-server): let an opaque capture wait for a video's preview copy

A video the browser cannot decode is drawn from its `?hf-proxy=` copy. The
runtime waits for that copy with a ranged fetch, preflighted when it carries
the priority header. In the opaque capture page both failed, so each such
thumbnail fell back to a still after about five seconds of retries.

The renderer now answers that preflight itself. It also exposes the copy's
status headers to the wait, for video files under the preview path only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(studio-server): keep capture-load comments within the package share

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(studio-server): keep video pixels and project fetches in opaque thumbnail captures

- Media loads: the renderer now grants them, and a capture document loads the
  project's own videos with `crossorigin="anonymous"`. Color grading and shader
  textures can then read their pixels.
- Fetches: every GET of the project's preview files is granted, except a dotfile
  or dot-folder path such as `.env` or `.git/`. This covers the models and fonts
  that registry blocks fetch at runtime.
- Opt-in: the capture sandbox is now a `createStudioApi` option,
  `sandboxThumbnailCaptures`, off by default. The CLI Studio server and the Vite
  dev server turn it on, because their thumbnail renderers install the grant.
  Another app keeps its current capture documents until its renderer does the
  same.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(shader-transitions): prepare transitions when IndexedDB is denied

An opaque-origin document, such as a sandboxed preview or thumbnail capture,
has no IndexedDB, and opening it throws. The snapshot cache now treats that
as no cache, so the transitions still prepare and draw.

Thumbnail captures also grant a CORS read of a missing preview file, so a
fetch() sees its status as a same-origin page would.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(studio-server): leave a video with another host's <source> out of capture CORS

A video whose <source> child points to another host now keeps its plain
load in a thumbnail capture. Adding crossorigin to it would make a CDN
that sends no CORS headers refuse the video, leaving the clip blank.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 07:50:59 +00:00
terencecho 04947d99f7 feat(cli): share rendered videos through unified reviews (#7135)
* feat(cli): share rendered videos through unified reviews (#7135)

* feat(share): attach editable project sources to reviews (#7137)

* feat(share): measure local sharing outcomes (#7138)

* feat(cli): stage the sixty-day publish transition (#7136)

* feat(studio): share review pages from local preview (#7140)

Advertise the CLI sharing bridge before bootstrapping it so standalone Studio does not
request unsupported routes. Preserve origin and session checks.

Budget the intended sharing artifact: clean main packs at 8,060,519 bytes versus
8,162,979 with sharing (8,169,168 in CI). Required policy and Unicode tables, bundled
sharing code, and Studio controls account for the growth. Set the packed-only budget
to 8,577,627, following the 5% headroom convention; retain the unpacked cap and all
package checks.

* fix(share): persist refusals and improve CLI retry feedback

* fix(ci): restore render diagnostics and include sharing workspace

* fix(cli): keep sharing owner error codes stable

* fix(share): clarify update feedback and align audience changes

* fix(share): clarify updates and avoid scratch-file rerenders

* fix(cli): report active shares and preserve update channels

* fix(cli): resolve update channel when checking registry

* fix(ci): refresh sharing package budgets after rebase

* fix(share): require consent before uploading project files
2026-11-11 06:26:24 +00:00
Michael WangandClaude Opus 5.5 b8bb491900 fix(studio-server): harden preview paths, cache folders and local servers (#7510)
* fix(studio-server): keep cache writes inside the project and canonicalize preview paths

- The tool's own folders (.hyperframes records, backups, preview documents,
  .thumbnails, .transcode-cache) are no longer written, pruned or emptied
  through a link that points outside the project. Thumbnails are still
  served when their cache folder is a link; they are just not cached.
- The hf-id stamp record and the history id are replaced atomically instead
  of written through an existing link.
- Sub-composition previews and thumbnails use the composition's canonical
  project-relative path, and the path is attribute-encoded in the document.
- Thumbnail requests from another site are refused before any capture.
- Saved GSAP scripts escape a `</script` sequence so the script element
  keeps its contents.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(core): refuse a UNC or device path on another root before any disk access

isSafePath now rejects a target whose root is a UNC or device root other than
the project's own before it calls realpath or lstat. Projects on a share keep working.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(studio): answer WebMCP clients only from Studio's own page

The polyfill now starts with its tab transport limited to Studio's origin and
its frame transport off, so a page that frames Studio cannot list or call its tools.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(inspector): check Host on the per-session preview server

The preview page server applies the inspector API's loopback Host rule, so a
rebound DNS name cannot read the bundled composition or project files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* revert(studio-server): keep writing media proxies through a linked .transcode-cache

Refusing the folder made every proxied video in such a project answer 502.
A linked cache folder now receives copies again; it is still never swept,
so nothing already in the folder it points at is removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(studio-server): drop a comment the comment ratchet refuses

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): skip HEIF and GIF preview prep when .hyperframes/prepared-assets is a link

The preview transform wrote converted images into .hyperframes/prepared-assets
through a link, so a project shipping .hyperframes as a link to another folder
had files written there. Such a project now gets its preview with the images
as written in the composition, unconverted, and nothing is written.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(studio-server): never sweep a linked .transcode-cache, from Studio or hyperframes clean

The link check moves into cleanupProxyCache, which both Studio's cache
maintenance and `hyperframes clean` call, so neither removes files from the
folder a linked .transcode-cache points at.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 20:26:12 +00:00
James RussoandClaude Opus 5.5 983e865ad7 fix(studio-server): thumbnail origin from the server, sandbox previews from other sites (#7492)
* fix(studio-server): thumbnail origin from the server, sandbox previews from other sites

The thumbnail route builds the headless browser's URL from the server's own
listening origin (a new optional `serverOrigin` on the adapter, wired in the CLI
preview server and the Vite dev host) instead of the request's Host header.
Hosts that report no origin fall back to a loopback Host only.

Preview responses (bundled, sub-composition and project files) opened from
another site carry `Content-Security-Policy: sandbox allow-scripts` and
`Vary: Sec-Fetch-Site`. Studio's same-origin iframe, browser automation and
non-browser clients are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(studio): build the thumbnail origin from a hostname bind name

With HYPERFRAMES_PREVIEW_HOST set to a hostname, the listening address is
the IP it resolved to, and the Host check accepts the bind name, not that
IP. The thumbnail browser then loaded a 403 page. Use the bind name when it
is a hostname; IP and wildcard binds keep the listening address.

— Rames Jusso

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* style(studio): drop the serverOrigin comment that put it over the package's comment share

The hostname-bind rule is stated by its test name in serverOrigin.test.ts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 14:30:10 +00:00
f318d3d08a fix(studio-server): refuse cross-origin writes and unknown hosts on the preview server (#7490)
* 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>
2026-11-10 10:14:23 +00:00
Miguel Ángel 4b3f70fb1b fix(cli): Studio renders take the same one-render-slot lock as the CLI (#7459)
* fix(cli): Studio renders take the same one-render-slot lock as the CLI

* fix(cli): a Studio render stops saying it waits once it has the slot
2026-11-09 21:18:29 +00:00
Miguel Ángel 72326a3ac7 fix(cli): a render's lint runs at normal priority, so a busy Windows PC no longer stalls it (#7268) 2026-11-05 23:09:58 +00:00
WaterrrForeverandClaude Opus 5.5 fb738015a0 fix(cli): bug-bash fixes for pull, offline, preview, check, cloud aspect, sfx search, and media-use avatars (#7170)
* fix(cli): an interrupted templates pull leaves no partial folder

Unpacking now runs tar asynchronously and removes its .part folder on
SIGINT/SIGTERM/SIGHUP before re-raising the signal. Part folders carry the
owning pid, and the next pull clears any whose process is gone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): auth status and templates pull say when HeyGen cannot be reached

Offline, both commands waited on unbounded requests and then printed only
undici's 'fetch failed'. A new networkFailure helper names the host, the
reason (DNS lookup, no route, refused, no answer in time, dropped) and the
next step. The account and token-refresh requests now time out after 15 s,
the template link after 15 s, and auth status reports an offline refresh at
once instead of retrying with the stale token. describeCauseChain moves into
the helper so the registry and auth share it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): preview leaves the project's HTML files as they are

Opening a project in preview stamped data-hf-id into every composition on
disk. The preview route and every source mutation already mint the same
content-keyed ids in memory, so the startup pass is dropped: files gain ids
only when an edit to them is saved. The .hyperframes folder is still made
before the watcher starts, so the preview cache creating it is not reported
to Studio as a manifest change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): check runs the browser audits past a lint error

A lint error made check skip runtime, layout, motion and contrast, so one
known lint error hid every browser finding. The browser pass now runs
whenever there is a composition to load, and the lint error still fails the
check. Only a root with no data-composition-id skips it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): no desktop-app line for CI or a script reading render output

The 'Keep editing by chatting with Framey' line printed on every render and
preview, including CI and piped runs where nobody can open the app. It now
prints for a person at a terminal, and for a coding agent, which the
hyperframes skill tells to pass the line on; CI and other non-TTY runs get
nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): cloud render takes a composition at any aspect ratio

A 1920x960 composition got 'server will default aspect_ratio to 16:9'
although the render kept 1920x960: at 1080p the cloud renders at the
composition's own size and aspect_ratio only picks a 4K preset. The CLI now
names the detected ratio (2:1) and says the size is kept, takes
--aspect-ratio as any W:H checked against the composition, sends only the
16:9, 9:16 and 1:1 the API accepts, and refuses a 4K render of any other
ratio before upload, where no preset fits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(media-use): a weak sound-effect match says so instead of passing silently

resolve --type sfx returned a HeyGen sound at any score down to 0.4, and a
project file that shared one word of its name with the intent, with nothing
to tell them from a real match. Such a result now carries a match object in
the JSON ({score, min_score, low_confidence} or the matched words and the
intent the file was resolved for) and a low-confidence line on stderr. A
HeyGen search with no hit says so with the min score it used, and a sound
effect nothing matches fails with 'no sound effect matched'.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(cli): media-use avatars lists the film account's avatar looks

Templates had to reach for 'heygen avatar list', a separate sign-in that can
be another account. 'media-use avatars' lists the private looks on the
HyperFrames account making the film (GET /v3/avatars/looks?ownership=private,
following next_token up to --limit) as {avatars: [{avatar_id, name, ...}]},
the id that 'generate --type avatar --avatar' takes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(skills): leave style-sampling's avatar line to #7164, which owns that skill

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): templates pull removes only the part folders it marked as its own

The abandoned-part cleanup deleted any sibling named '<slug>.part-*' whose
next token was not a live pid, so a person's own 'sample.part-notes/',
'sample.part-reference.txt' or a symlink went with it. A pull now writes an
ownership marker (owner tag + pid) into its part folder, and the cleanup
removes only a real directory with the generated '<slug>.part-<pid>-XXXXXX'
name whose marker names a dead pid. Files, symlinks, unmarked folders and
older unmarked parts are left alone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): media-use avatars says it is offline when the login refresh cannot reach HeyGen

A network failure while refreshing the stored login was reported as 'no
HeyGen sign-in' with 'auth login' as the fix, though the login was still
there. It now keeps the network failure's message and next step.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(media-use): a reused weak sound keeps its low-confidence advisory

The first resolve of a weak HeyGen sound or a name-matched project file
flagged it, but an identical second resolve hit the project manifest and
returned it with no match object. The advisory is now rebuilt from the
record's provenance (the stored score, or the adopted file's name) on reuse.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(cli): keep the comment share of files this branch touched from rising

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): no check-then-use on pull markers, and the download is never written to disk

CodeQL flagged the downloaded bundle written to a file before tar read it,
and a stat-then-read in the preview test. The verified archive now streams
into tar's stdin, so no network bytes reach a file the CLI writes. The
abandoned-part scan takes the entry type from readdir instead of an lstat,
reads the ownership marker through one O_NOFOLLOW descriptor it fstats, and
the preview test reads each file once instead of stat-checking it first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(ci): raise the CLI's unpacked size budget to 5% over its measured size

main's @hyperframes/cli was already about 0.99% over its 23722874-byte
unpacked budget, so this branch's additions (networkFailure, the avatars
command, the larger skill references) tip it past the 1% tolerance. This is
the same value #7169 sets, 25159107 bytes (5% headroom over the measured
size), so the two PRs merge cleanly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(cli): split the pull-marker check and share the token-endpoint POST

Fallow flagged pullOwner (CRAP 49.5, cyclomatic 13) and a 28-line clone
between refreshOnce and exchangeCodeForTokens. pullOwner is now the name
match, the O_NOFOLLOW marker read and the marker check as three small
functions, with the same behaviour. Both token requests go through one
postToTokenEndpoint, which keeps the 15 s timeout and the named network
failure.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): a 4k cloud render checks the exact size against its preset before upload

The aspect detector matches a ratio within ±0.05, so at 4k a 1920x1055
composition was sent as 16:9 and 1000x980 as 1:1, and the producer then
refused both as an aspect mismatch. At 4k the matched ratio's preset
(landscape-4k, portrait-4k, square-4k, the ones the API maps it to) now goes
through the producer's own checkOutputResolutionCompatibility, and a
composition it does not fit is refused locally with the producer's reason
and the 1080p alternative. 1080p, where the render keeps the composition's
own size, is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 18:21:36 +00:00
Miguel Ángel 88d8e5b490 fix(cli): check and snapshot load GSAP from the bundled copy, not jsDelivr (#6824)
* fix(cli): check and snapshot load GSAP from the bundled copy, not jsDelivr

* test(cli): bundled GSAP loads on a page whose own requests interception answers
2026-10-30 12:54:06 +00:00
Miguel Ángel 3e795ece0f fix(cli): preview stops at once on Ctrl+C after Studio was open (#6782)
* fix(cli): preview stops at once on Ctrl+C while a Studio tab is open

* fix(cli): a closed Studio tab leaves no timer that holds a stopping preview open

* fix(cli): name the tab-closed wait instead of commenting it

* test(cli): the tab-disconnect test checks the route's own keep-alive timer, not every timer
2026-10-30 05:58:35 +00:00
Miguel Ángel c21a70915f fix(cli): a preview inside a host app's run no longer takes the project's history (#6493) 2026-10-27 00:33:12 +00:00
Miguel Ángel 54d0af57eb feat(engine): render sets a keyframe interval and a peak bitrate cap (#6444)
* feat(engine): encoders cap peak bitrate and place keyframes on a set interval

* style(engine): shorten the rate-cap comment

* style(engine): drop the doc lines the comment ratchet flagged

* feat(producer): mp4 renders honour a keyframe interval and a peak bitrate cap on every encoder path

* style(producer): shorten the delivery encoder file headers

* style(producer): drop a comment line from the segment manifest

* style(producer): shorten the integration test header

* test: delivery encoder tests follow the ffprobe argv contract and run in the integration lane

* feat: the render request, server and Lambda plan carry the keyframe interval and peak bitrate cap

* fix(studio): the Studio render route passes the keyframe interval and bitrate cap to the encoder

* chore(studio-server): drop a comment the helper's name already says

* feat(cli): render and lambda render take --keyframe-interval, --max-bitrate and --buffer-size
2026-10-27 00:29:06 +00:00
Miguel Ángel ad4d3fad13 fix(producer): convert HEIC images to JPEG at compile time (#6455)
* fix(producer): convert HEIC images to JPEG at compile time

Tiled HEIC photos probe as several video streams, so the media-type
preflight rejected them as image:video, and Chrome cannot decode HEIC.
Sniff the ftyp brands of every <img>, join and rotate the tile grid with
ffmpeg, verify the declared size, and swap in a cached JPEG.

* fix(producer): shorten the HEIC prep comments

* fix(producer): name host tool failures and keep a failed HEIC preview image as authored

Also: HEIC tests run in the integration lane; the primary grid is picked by default disposition.

* chore(producer): raise the package size budget for the HEIC prep
2026-10-26 13:56:13 -04:00
SophiaHuangCc 2d695a8436 feat(studio): support GIF export with loop count (#5593)
* feat(studio): support GIF export with loop count

* fix(studio): cap GIF exports at 30 fps

* fix(studio): complete GIF export review follow-ups
2026-10-26 14:57:55 +00:00
James RussoandClaude Opus 5.5 7f19f2335a feat(studio): load GSAP from the CLI's bundled copy by default (#6256)
* feat(studio): load GSAP from the CLI's bundled copy by default

Studio preview now loads the GSAP, CustomEase and MotionPathPlugin scripts
it adds from files the CLI ships and serves same-origin at /api/vendor/npm,
instead of jsDelivr. HYPERFRAMES_GSAP_BASE_URL still wins when set, and a
composition on another GSAP version gets its plugin from jsDelivr.

Renders now honor HYPERFRAMES_GSAP_BASE_URL when they replace a missing
local GSAP script, and the setting accepts plain http only for loopback
hosts.

Closes #6205

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

* refactor(studio): keep comment share flat for the GSAP local root

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

* fix(cli): find the installed gsap with node resolution when run from source

The Windows CI lane installs with the hoisted linker, so gsap is not under
packages/core/node_modules there.

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

* fix(producer): load a nested composition's missing GSAP from the mirror

A sub-composition's missing local gsap/dist script was hoisted into the
render unchanged, so HYPERFRAMES_GSAP_BASE_URL (and the jsDelivr fallback)
only reached the entry document. Run the same rewrite on every
sub-composition before it is compiled, resolving its path the way the
inliner will hoist it.

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-25 03:08:42 +00:00
Vance IngallsandClaude Sonnet 5.5 1f8ead7bde feat(producer,studio): wire capture motion blur into renders and Studio (#5969)
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>
2026-10-21 13:32:50 -07:00
Miguel Ángel 6d357ff0d8 fix(cli): check, snapshot and Studio read project text as UTF-8 (#5843)
* 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.
2026-10-20 13:52:43 +00:00
Miguel Ángel 5583ae4293 perf(cli): commands run without esbuild, puppeteer-core or sharp until they need them (#5930)
* 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
2026-10-20 09:12:47 +00:00
Miguel Ángel cadd7af2b5 fix(studio-server): send Studio's history edits to the process that owns the project's history (#5826)
* fix(studio-server): send Studio's history edits to the process that owns the project's history

* fix(studio-server): a forwarded history call gives up after 5 s, so a stopped owner cannot hang
2026-10-18 06:07:33 +00:00
Miguel Ángel 0e9f380c2e feat(cli): render telemetry reports how busy the machine's CPU was (#5646)
* feat(cli): render telemetry reports how busy the machine's CPU was

render_complete and render_error now carry system-wide CPU busy share (average
and busiest 2 s window), cores busy in that window, and the one-minute load
average at start and end, for CLI and Studio renders. Nothing is sampled when
telemetry is off.

* test(cli): render tests use a private project folder instead of /tmp/project
2026-10-15 16:08:52 +00:00
James RussoandClaude Opus 5.5 ab8a4da53f feat(studio-server): accept crf, videoBitrate, videoFrameFormat and hdrMode on the render route (#5549)
* feat(studio-server): accept a crf override on the render route

The Studio render route only forwarded draft/standard/high, so a Studio or
desktop export could not ask for a specific CRF the way `hyperframes render
--crf` can. Film-grain finishing passes need CRF 12 to keep the grain.

The route now takes an optional integer `crf` (0-51 for mp4, 0-63 for webm),
rejects an out-of-range value with 400 instead of dropping it, ignores it for
mov, and both Studio adapters pass it to the render job.

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

* chore(studio-server): keep the crf change free of new comment lines

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

* feat(studio-server): accept videoBitrate, videoFrameFormat and hdrMode on the render route

Same options `hyperframes render` already takes (--video-bitrate,
--video-frame-format, --sdr/--hdr), so Studio callers are not limited to
the quality presets. crf and videoBitrate are an either/or, matching the CLI;
an invalid value is a 400. Parsing moves to helpers/encoderOptions.ts.

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-13 20:09:58 +00:00
Miguel Ángel 91f9c9eb04 feat(studio): export can encode on the GPU, like render --gpu (#5397)
* feat(studio): export can encode on the GPU, like render --gpu

* test(studio): the 4K export assertion carries the GPU flag

* refactor(studio): the GPU flag needs no comment beyond its name

* fix(studio-server): only MP4 exports encode on the GPU, and render errors report it

* fix(studio): the disabled GPU option dims like the other export controls
2026-10-10 04:45:05 +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 5ec2dd2e12 fix(lint): check passes valid sub-compositions and scene-relative asset paths (#5337)
* fix(lint): check passes valid sub-compositions and scene-relative asset paths

* fix(lint): keep the browser lint build free of node modules

* refactor(lint): tidy sub-composition lint helpers and guard bare node imports

* fix(lint): resolve stylesheet asset paths from the stylesheet's own folder

* fix(lint): catch every written form of a path that climbs out of the project

* fix(parsers): sub-composition asset paths written with backslashes load in preview

* fix(parsers): an encoded backslash stays in the file name and a leading backslash stays absolute

* fix(lint): an encoded %2f counts as a separator when checking for a climb out of the project
2026-10-09 19:54:58 +00:00
Miguel Ángel dbb8222c8d fix(studio): catch up the preview after missed file changes (#5126)
* fix(studio): recover previews after missed file changes

* fix(studio): keep queued reloads with the current owner

* fix(studio): keep a queued outside change when switching compositions

* test(cli): the project watcher closes its parent folder's watch too

* fix(studio): keep the project-folder change out of the shared signature check

* fix(studio): keep the edited file's draft and reload every session after a reconnect

A reconnect or replaced folder is a project-wide change: every open SDK session reloads, a failed save is recorded against the file the draft belongs to, and two queued changes to different files merge into one project-wide reload.

* fix(studio): refresh the preview cache when the .hyperframes folder is replaced

* fix(cli): report the files of a folder moved into the project

Replacing a populated folder such as .hyperframes/ now reaches the signature cache through its files, so the shared signature rule stays as on main and Studio's own writes inside .hyperframes/ still invalidate nothing.

* refactor(studio): name the merged file-change payload and share the test sender

* fix(studio): keep a failed draft's recovery copy until that file itself saves

* style(studio): rewrap the merged payload line after the rename

* fix(studio): deliver a held change's full reload when its block clears

A clean save, Use external and Keep Studio now all deliver the merged scope a blocked change owes, and a moved-in .hyperframes folder reports its manifests so a dropped one still clears the cached signature.

* fix(studio): keep restored drafts out of the reload scope and clear the lint gates

* fix(studio): retain held reload scope before React renders
2026-10-07 07:32:16 +00:00
Miguel Ángel c6478e404c fix(studio): undo takes back the first edit of a film whose media is still being copied (#5043)
* fix(studio): undo takes back the first edit of a film whose media is still being copied

* fix(studio): the first undo of a film repaints the preview in place

* fix(studio): background media copies keep the media ledger and survive a history prune

* fix(studio): a busy project history never makes writes wait for its lock again

* refactor(studio): name the restore stamping instead of commenting it

* perf(studio): undo stamps only a restore side that has no stamps

* fix(studio): closing a project history finishes its media copy first

* fix(studio): media copies stay resumable until recorded and skip a replaced folder

* fix(studio): the history lock wait comes back after a successful open
2026-10-05 08:05:14 +00:00
Miguel Ángel b3d2b82fe9 feat(core): the renderer's font pipeline is importable from @hyperframes/core/fonts/embed (#5041)
* feat(core): the renderer's font pipeline is importable from @hyperframes/core/fonts/embed

* style(core): format the font pipeline and state the bundled-subset invariant

* test(producer): repin the test lane map after the font tests moved to core

* fix(core): images build fonts once, CLI bundles one pipeline, font tests pass on Windows

* test(core): font retry tests get a budget no slow machine can exhaust

* test(core): the Retry-After budget test fails when the budget is ignored
2026-10-05 04:54:53 +00:00
WaterrrForever bd0dc8c3ae feat(studio,cli): add an Edit with Framey button and hyperframes open for HyperFrames Studio (#4951)
* feat(studio,cli): add an Edit with Framey button and `hyperframes open` for HyperFrames Studio

Point people from the CLI and the Studio preview to HyperFrames Studio, the desktop app.

- Studio header: an "Edit with Framey" button with Framey, the app's cursor mascot (the eye
  follows the pointer, a wiggle on hover, honours reduced motion). Until the app opens
  handed-over projects (HANDOFF_READY), a press shows a "Meet Framey" card with the download.
  The button shows only where the preview server answers GET /api/open-in-desktop on macOS,
  so the desktop app's own embedded Studio never shows it.
- `hyperframes open [dir]`: hands the project folder to the app with `open -b` (released app,
  then Canary) and points to the download when neither is installed. When run by Claude Code
  or Codex it leaves .hyperframes/agent-handoff.json (CLAUDE_CODE_SESSION_ID / CODEX_THREAD_ID)
  so the app's first chat can pick up that conversation.
- render and preview print one line about the app: the download until HANDOFF_READY, then
  `hyperframes open` when the app is installed. Nothing for a draft render, a batch row, or a
  run inside the app (HYPERFRAMES_DESKTOP_PROJECT).

* fix(studio,cli): gate `hyperframes open` too, guard the open-in-desktop POST, keep one gate

Review of #4951 at 58934a34.

- One gate: HANDOFF_READY lives only in the CLI. `GET /api/open-in-desktop` now says
  `handoff`, and Studio's button reads it, so the gate cannot be half-flipped.
- While gated nothing opens and nothing is written: `openInDesktop` returns
  `handoff-unavailable` (so `hyperframes open` prints the download line and the POST route
  answers with it), and no `.hyperframes/agent-handoff.json` can sit waiting for a later release.
- The POST answers only Studio's own same-origin request (loopback Host, matching Origin,
  Sec-Fetch-Site same-origin); a cross-site or rebound-host POST gets 403. Routes moved to
  server/desktopRoutes.ts with their own tests.
- `hyperframes open`: exits 1 when nothing opened, answers in JSON under --json for a bad
  directory, and tells a missing app from one macOS could not open (`open-failed`). A project
  that cannot be written still opens, with nothing handed over.
- Tests drive the live path through `ready`, are path-portable for Windows, and cover the draft
  and batch-row hint skips (`wantsDesktopHint`, `batchRowRenderOptions`).
- The load smoke mocks the route.

* fix(studio): the edit-with-framey button asks its route through studioApiFetch
2026-10-04 10:52:23 +00:00
Miguel Ángel ada4e0d289 fix(studio): show each timeline row its own layer instead of a flat bar (#4917)
* fix(studio): show each timeline row its own layer instead of a grey bar

A row got a frame only if it spanned under 92% of the film and its id did not
look like a backdrop; every other row drew a plain grey bar. Every element row
now gets its frame, and the capture fades the row element's siblings first, so
the frame shows that layer and not the whole film. Studio's dev server and the
CLI share one capture helper; Studio's own copy is gone.

* fix(studio): read timeline rows from any realm so each keeps its selector

* refactor(studio-server): always isolate the element in a thumbnail clip

* fix(cli): undo a thumbnail's isolation before its page takes the next capture

* chore(core): generate the dom-realm export and trim thumbnail clip comments

* fix(studio-server): restore sibling opacity after a clip, hash selectors in cache keys

* fix(studio-server): keep faded siblings in a page-owned list so restore is exact

* feat(studio): draw a text layer row as its own live text instead of a captured picture

* refactor(studio): move timeline text reading into its own module

* fix(studio): keep text rows readable and current, and leave painted layers as pictures

* fix(studio): refresh a canvas-edited text row by its own identity and source file

* fix(studio): refresh a canvas-edited text row known only by its data-hf-id
2026-10-03 00:22:49 +00:00
Vance IngallsandClaude Opus 5.5 9244c47328 feat(studio): normalize loudness and duck under voice, with a limiter report (4/8) (#4816)
* feat(studio-server): share loudness measurement with an absolute target and video support

normalize-audio moves its measure/plan code into @hyperframes/studio-server/loudness,
gains an absolute mode (--lufs, default -16, clamped at +12 dB and -1.5 dBTP) and
accepts <video> clips with sound. Adds the @hyperframes/core/audible-video subpath.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(studio-server): add a measure-only loudness normalize endpoint

POST /projects/:id/loudness/normalize measures a clip's played window (audio or
video) and answers the -16 LUFS data-volume plan; Studio writes the attribute.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore: register the loudness and audible-video subpaths in their descriptors

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* style: format the loudness and audible-video subpath descriptors

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(studio): add Normalize loudness and Duck under voice to the clip menu

Normalize measures the clip on studio-server and writes data-volume as one undoable
edit; Duck toggles a carve against every overlapping voice (audio or video with
sound) at the default strength. Both live in clipMenuAudioItems with one hook-in.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(studio): tighten carveOutput docs to the package comment share

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(producer): report how far the true-peak limiter lowered the export

The AAC true-peak pass now returns its attenuation; the render logs "Audio lowered
by X.X dB to stay under -1 dBTP" and sets RenderJob.audioLoweredDb, which Studio
servers carry in the complete SSE event and the /renders record. Also exports
useAudioMetersVisible from @hyperframes/studio for hosts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(studio-server): scan HTML start tags without a backtracking regex

The start-tag regex backtracked quadratically on '<' followed by many spaces
(CodeQL js/polynomial-redos). A linear character scan reads the same name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(studio): refuse to normalize a volume-automated clip and honour save outcomes

A volume lane owns the clip's gain in preview and render, so writing
data-volume changed nothing while the toast claimed success; Normalize now
refuses with a clear message. Normalize and Duck also check each quiet-save
outcome, stop at the first failed or refused write and report it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(core): drop the duplicate audible-video subpath descriptor

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-02 03:51:34 +00:00
Miguel Ángel 567525a8c2 fix: readers never see an empty or half-written project file (#4777)
* fix: readers never see an empty or half-written project file

* test: pin the create routes and block install to whole-file writes

* fix(sdk): a write through a link to a missing file creates that file

* fix: saves through a linked folder reach the real file, atomic writes handle long names

* test(sdk): check for the stray file, not the folder listing

* fix(core): creates work on Windows FAT drives, and links through folders resolve as the system does

* fix: agree the helper move in the deletion check, and match temp paths without a path regex

* test: check POSIX file modes only off Windows
2026-09-30 19:17:59 +00:00
Miguel Ángel 9e1dbca7a2 fix(studio): undo and redo update the preview in place instead of reloading it (#4718)
* fix(studio): undo and redo swap the restored scene in place instead of reloading

* fix(studio-server): a preview asked for right after an undo shows the undone state

* fix(studio): an undo that restores a page outside every scene still reloads in full

* fix(studio-server): a preview built across a write is not cached under the old signature

* test(studio): a soft undo keeps the scene hashes so the next edit still swaps
2026-09-29 02:03:56 +00:00
Miguel Ángel 26bfd38136 fix(studio-server): a save never recreates a project folder renamed away (#4602)
* fix(studio-server): a save never recreates a project folder renamed away

* style(cli): wrap imports after merging main

* fix(studio-server): proxy and upload answer that the project folder is gone instead of 502 or an empty 201

* test(studio-server): rename the project folder while an upload is being read

* fix(studio-server): a proxy or backup answers that a vanished project folder is gone

* test(studio-server): clean up the renamed folder after the proxy test

* refactor(studio-server): drop an unused re-export and share the folder-gone test setup

* fix(core): no folder outside a project is created once the project folder is gone

* test(studio-server): a refused render leaves no outside renders folder behind

* docs(core): wrap the mkdirWithinProject comment under the line limit

* test(studio-server): pass the project folder to the preview document store
2026-09-28 09:48:22 +00:00
Miguel Ángel 59e3850f6a fix(studio-server): a write through a link lands on the file the system resolves (#4589)
* fix(studio-server): a write through a link lands on the file the system resolves

* fix(cli): resolve catalog install paths as the system does, matching the install root

* fix(cli): list installed files relative to the real project folder
2026-09-27 12:30:17 +00:00
Miguel Ángel e00baefb5c fix(studio): reload the preview only when a file it loaded changes (#4570)
* fix(studio): reload the preview only when a file it loaded changes

* test(studio): read the owner id from the new change-owner shape

* refactor(studio): drop a comment the parser name already says

* fix(studio): keep reloading until the preview is built, and count what its document names

* style(studio): format the reference pattern and name the kept reload

* fix(studio-server): scan preview references in linear time and refresh all thumbnails on a merged reload

* fix(studio): keep a waiting film change when a file the preview never loaded arrives behind it

* test(studio): name the preview ownership test for what it checks

* chore(ci): allow the watchIgnore removals and trim the new comments

* fix(studio-server): reload the preview when a folder holding a file it loaded moves in or out

* perf(studio-server): check a changed folder in one lookup and cover every reference form

* fix(studio-server): record read folders for a project at the filesystem root

* fix(studio-server): reload the preview when the file a symlinked asset points at changes

* fix(studio-server): resolve symlinks on every preview read and key projects by their real folder

* fix(studio-server): record every link a preview read passes through, resolved as the system does
2026-09-27 10:05:53 +00:00
Miguel Ángel 4984a268f7 fix(cli): Studio's catalog install records the item and honours paths, as add does (#4573)
* fix(cli): Studio's catalog install goes through add, so it records the item and honours paths

* fix(cli): Studio's catalog lists the project's registry and install paths survive symlinks

* refactor(cli): name the Studio catalog's registry option plainly

* feat(cli): registry_item_added says whether add or Studio installed the item

* fix(cli): dropping the same catalog block in Studio twice installs it again

* chore(cli): drop a comment that restates add's source option

* fix(cli): Studio's re-record finds lock entries by their resolved path

* test(cli): the symlinked-folder install test checks the resize happened

* fix(cli): Studio mounts the installed item's own file by the path add recorded

* fix(cli): Studio's install never hands back a file the project kept for its own edit
2026-09-27 09:06:15 +00:00
James Russo 31c00d2f0e fix(studio): avoid preview reloads for temporary and excluded files (#4553)
* fix(studio): avoid preview reloads for temporary and excluded files

* docs: capture public preview reload reproduction

* fix(studio-server): normalize watch paths in linear time

* fix(studio): register dynamically opened preview projects
2026-09-27 02:23:25 +00:00
Miguel Ángel 7eb6430e4e fix(studio-server): history refuses once closed and reopens when a new project takes its folder (#4537) 2026-09-26 19:01:05 +00:00
Miguel Ángel 31441701fc fix(studio-server): one process at a time keeps a project's history open (#4448)
* fix(studio-server): one process at a time keeps a project's history open

* fix(studio-server): taking over a dead history owner never removes a live owner's lock

Two processes that both found the owner dead could each take the lock,
the second removing the first's. Eviction now happens under its own lock
with a re-read, a close removes the lock only while it names the closer,
and a lock file holding no pid counts as dead.

* fix(studio-server): a history lock that cannot be read fails the open instead of spinning
2026-09-25 11:52:46 +00:00
Miguel Ángel 11ac9bce69 fix(studio-server): previewing a project never rewrites its files (#4480)
* fix(studio-server): previewing a project never rewrites its files

* fix(studio-server): a GSAP save on a served id writes that id to the file too
2026-09-25 10:04:38 +00:00
Miguel Ángel 36f8bd0e91 feat(studio): undo and redo step through the project history, whoever made the change (#4456)
* feat(studio-server): an undo taken from Studio is not mistaken for an outside edit

* feat(studio): undo and redo step through the project history, whoever made the change

* feat(studio): the dev server keeps each project history, in the same folder as preview

* fix(studio-server): an undo that deletes a file reads as Studio's, and dev histories close

* fix(studio-server): a claim keeps an agent's earlier write the agent's and takes back Studio's own

* chore: allow the removal of Studio's browser edit history files

* test(studio): mock the project history in the runtime smoke

* fix(studio): step past a jammed undo and say why a step fails

* fix(studio-server): an agent turn cut by a claim commits its part before the claim

* fix(studio-server): a claim's cut ends a held drag and takes only the cut files out of a turn

* fix(studio-server): a held drag ends when someone else changed a file it already holds
2026-09-25 08:43:04 +00:00
Miguel Ángel f873734cc4 perf(studio): open a large film ready to play in about 4 s instead of 32 s (#4401)
* perf(studio): keep lint off the preview open path

The bundler linted every build only to print a StaticGuard warning; a preview bundle now
skips it through a staticGuard option, since Studio lints on its own route. That route now
lints in the CLI child-process worker the render path already uses, so seconds of parsing
no longer stall the preview and every other Studio request on the server event loop.

* perf(parsers): parse identical GSAP source once

Studio re-requests the parsed animations of unchanged source on every open, and several lint
rules parse the same script in one run. A small memo keyed by the script text serves repeats;
each caller gets its own copy.

* perf(studio): build each preview document once per content version

The preview route rebuilt the document for every browser without a cached copy. It now serves
one build per ETag from memory, and the CLI keeps the last build on disk salted with its own
file, so a restarted server serves the previous document without stale code.

* perf(studio): build the opening film's preview while the browser starts

The preview server built the document only when the player asked for it, after
Studio had booted, so a first open waited about a second of idle server time.
The CLI now requests the opening project's preview right after listening, and
requests that arrive while a build runs share it instead of starting another.

* perf(studio): request the preview document at page load

Studio asked for the preview only once the player mounted, about 640 ms into a
first open. It now requests it the moment the page loads, and again when the
hash names another project, so the build or cache read overlaps Studio's boot.

* feat(studio): show the cached frame 0 while the live preview boots

Studio covers the live preview with frame 0 as the thumbnail route last rendered it, sized
from the image so the stage does not shift, and removes it when the live frame is ready to
show. The request is cache-only, so a miss never starts a render on the open path; the
missing poster is rendered after the live frame shows, for the next open.

* perf(cli): start Studio before the startup lint finishes

hyperframes preview linted the whole project before it listened, 4 to 6 s on a large film, and
did so in --json mode where the result is discarded. The lint now runs in the CLI worker while
Studio starts and prints its summary when done; --json skips it.

* perf(studio): render thumbnails from one loaded page, after the preview boots

Every thumbnail opened a page and loaded the whole composition to shoot one frame, and the
Compositions card asked for one while the live preview was still booting. The server now keeps
one loaded page per preview document and seeks it per frame, reloading only when the project
changes; card thumbnails wait for the project first ready preview.

* perf(studio): parse GSAP animations after the preview boots

Studio asked the server to parse the composition animations while the preview was opening; on
a fresh server that cold parse ran on the event loop ahead of the preview build. The request
now waits for the live preview to boot, or to fail loading, since only keyframes need it.

* perf(cli): find orphaned browsers with one process-table read

preview ran pgrep three times and then ps once per matching browser, all
synchronously before listening: about half a second on a machine running
other headless Chrome. One ps listing now finds every orphan in ~20 ms.

* perf(studio): keep lint off the boot

Opening a project started two lint processes while Studio booted: the
terminal's startup lint and Studio's background lint, ~4 s of CPU next to the
boot. Studio's background lint now waits until the live preview has booted,
and lint processes run at the lowest CPU priority so they only take idle CPU.

* perf(studio): open the editing session after the preview boots

Opening a project read the composition source and parsed it for the editing
session (linkedom plus hf-id assignment) on the main thread while the live
preview was booting on the same thread: ~300 ms on a large film. The session
now opens once the preview has booted; nothing the first frame shows needs it.

* perf(studio): park the editor overlays until the preview boots

The overlay frame loop polled preview geometry and off-canvas indicators from
the first frame, forcing layout on a preview document that was still loading,
on the thread its boot runs on: ~200 ms before the first frame on a large film.
The loop now skips its subscribers until the preview has booted, then wakes.

* perf(studio): treat the preview as booted once it can play

Work deferred until the boot (editing session, lint, overlays, GSAP parse,
card thumbnails) started at timeline-ready, which fires before the asset gate,
so the editing-session parse ran inside the wait for play. The Player now
latches the boot when the preview can show and play, or fails to load.

* fix(studio): keep a left project's deferred work out of the one now open

Deferred open-time work (source parse, background lint, editing session) waited on one global
boot flag, so leaving a project before its preview booted let the next project's boot run the
old project's work and write its results. The wait is now per project and resolves false once
another project opens. A preview stuck without an error stops deferring that work after 5 s.

* perf(cli): let the play page revalidate instead of refetching

hyperframes play served the composition, its assets, the player and the runtime with no
validator, so every reload refetched everything, the mp4 in full three times. They now carry
an ETag and stay no-cache, so unchanged bytes cost a 304 and an edit is still seen.

* fix(cli): serve an edited text asset even when its size and mtime match

The play page tagged every asset by mtime and size, so a same-size rewrite within one
filesystem tick kept the old tag and the browser kept stale bytes. Text assets now get a
content-hash tag; media keeps the mtime and size tag Studio already uses.

* fix(studio): close idle thumbnail pages so an idle Studio runs no composition

Kept-loaded thumbnail pages stayed open for the life of the server, each running a live composition,
so an idle Studio cost server CPU and memory that main does not. A page now closes after 10 s unused,
and a page is closed only after the frame still running on it finishes.

* fix(studio): stop a first open from reloading the preview once per scene file

Studio stamped hf-ids into a composition the first time that composition was served, so opening a
film of external scenes wrote to index.html and every scene file mid-session. Each write reached
Studio as an outside edit and reloaded the preview, which failed for a large film. The server now
stamps every composition once before it starts watching the project.

* fix(studio): ignore play until the preview can play, so it is never undone

Space (and any play() caller) could start playback before the preview frame finished loading. Its
load step then paused and rewound to the restore point, so the play was silently lost. play() now
waits for timelineReady, the same gate the Play button already uses.

* fix(studio): hold play on a composition switch until the new preview loads

Readiness was reset only when the project changed. Drilling into another composition kept the
old ready flag while the new preview loaded, so Play or Space could start a play that its load
step then undid.

* refactor(studio): split background lint and thumbnail page reuse into single-purpose steps

Keeps the boot wait in the background lint only, moves page lookup and idle close out of
withPage, and drops a suppression the startup worker no longer needs. Behaviour unchanged.

* chore(cli): declare the render-setup worker as a fallow entry

It is spawned by path from cancellableProcess.ts, so it has no import-graph referrer; the entry list
is where the repo records that, replacing the per-file ignore removed in the previous commit.

* fix(cli): close a thumbnail page whose load fails

The page never leaves the promise that loads it, so when the load throws (a WebGPU composition with
no adapter, or the navigation timeout on a big film) nothing could close it.

* fix(cli): match text assets by exact type and keep Range on them

The pattern anchored only its first alternative, and text assets skipped buildRangeResponse, so a
ranged request for a stylesheet or SVG got a full 200.

* test: open the next project as Studio does, and read the stamped file once

The absent-read guard test switched project without beginning its timeline session, so the
per-project boot wait held the read. The stamp test checked then read the same file.

* test(cli): rewrite the scene file without opening it first

Opening the file by path counted as a check before the later read of the same path.

* perf(cli): take a thumbnail's version from the cached project signature

Each thumbnail walked the project and hashed every text file for its page version; the adapter
already caches that signature and clears it from the watcher. An aborted request now also stops
before its screenshot.

* fix(studio): keep Play off until the preview's load step has run

Play could enable before the preview document's load event, from the runtime's timeline message
or from the blank page's load step settling on the preview's first message. The load step then
paused and rewound the preview, so a Play pressed in between did nothing; a film with large
images loads late enough for this to hit a cold open. Readiness now waits for the document's load
step, whichever path asks for it.

* refactor(studio): move the preview poster's state into usePreviewPoster

NLEPreview.tsx passed the 600-line limit once main grew it; the poster's state and callbacks belong
beside PreviewPoster. No behaviour change.

* fix(cli): take an earlier thumbnail on a fresh page

A composition need not draw the same frame when seeked back, so a kept page that had shown 20 s
drew a different 10 s thumbnail than a fresh load. A kept page now only seeks forward, as a render
does; an earlier time loads a fresh page.

* perf(cli): close a kept thumbnail page a second after its last frame

Held for 10 s, the page went on running its composition after the open's thumbnail
burst, about 5 % of a core in the thumbnail browser while Studio sat idle. A burst's
requests arrive back to back, so it still loads the page once.

* fix(studio): count the preview as booted at its first frame

The boot waited for every video and audio in the preview to finish buffering, which on a
project with media took until the 5 s fallback. The thumbnails, editing session and lint
that wait for the boot then started seconds late and kept an idle Studio busy. They now
start once the first frame is up; media finishes buffering alongside.

* perf(studio): render one thumbnail per composition for its card and clip

A composition's sidebar card asked for its frame at 3.00 s and its timeline clip for the
clip's midpoint, so opening a project rendered every scene twice. The clip now asks for the
card's frame (the midpoint still, for compositions under 3 s), and the thumbnail cache
serves both from one render: 20 scene renders drop to 12 on a 12-scene project.

* chore: keep each changed file's comment share at or under main's

The comment ratchet counts the comment lines this branch added. Each is cut, or kept as one
line where it states an invariant (the GSAP parse cache returns copies; the boot starts waiting
work at the first frame). The orphan-cleanup docblock is condensed and now names the process-table
read it uses instead of the pgrep scan it replaced. No code line changed.

* fix(studio): keep a 3 s clip off its end frame and give card and clip one encoded URL

A composition exactly 3 s long asked for its thumbnail at 3.00 s, its end instant, which after a
fade-out is an empty frame; compositions of 3 s or less now use their midpoint. The card built its
thumbnail URL from the raw path while the clip encoded it, so names with & + [ or % asked for two
different URLs, and a % in the name made the card's request fail on the server; both now encode.
The readiness comment says the boot latches at the first frame, as it has since the boot moved.

* fix(studio): encode the card's live preview URL too, and document the bundler's static guard

The card's hover preview built its URL from the raw composition path, so a % in the file name made
the preview route fail to decode it. The card now builds its composition URL in one place, encoded,
for both its thumbnail and its hover preview. The static-guard bundle option keeps a one-line doc
(its default and what it warns about); a neighbouring docblock is rewrapped to keep the comment
share.

* test(cli): mock studio-server once so the signature spy and the history hook both apply

The main merge brought a second vi.mock of @hyperframes/studio-server into studioServer.test.ts;
the later one replaced the first, so createProjectSignature was no longer a spy and the cached
signature test read .mock of undefined. One mock now carries both overrides.
2026-09-25 04:56:55 +00:00
Miguel Ángel 177464b4c1 feat(cli): preview keeps project history, and Studio can claim its own edits (#4437)
* feat(studio-server): preview keeps a project history and names the next undo and redo

The history engine now reaches `hyperframes preview`, and its routes tell
Studio what Cmd+Z and Cmd+Shift+Z would revert next.

- The CLI preview server gives the shared API a project history, opened
  on first use under ~/.cache/hyperframes/history (overridable with
  historyRoot), and its file watcher feeds every change it sees to it.
  Shutdown closes it, so open windows are committed, within the same
  bounded wait as renders, so a history still opening cannot hold exit.
- GET /projects/:id/history also returns `back` and `forward`: the entry
  each step would revert, with its label, for the Undo and Redo buttons.
- POST /projects/:id/history/window takes an optional idleMs, so a drag's
  burst of writes can share one window that ends by itself (capped at
  10 minutes, below where a timer overflows).

Nothing in Studio calls these yet.

* feat(studio-server): a writer that records after writing can claim its writes

Studio records an edit after writing it, and many of its writes are
server mutations deep in its save paths, so opening a window before each
write would restructure them. claim() fits that order instead.

- ProjectHistory.claim(who, label, paths, { coalesceKey?, idleMs? })
  sweeps now and moves the not yet committed outside changes to `paths`
  into one entry of who's, under the edit's label. Other outside writes
  stay outside.
- Claims with one coalesceKey merge into one entry (a drag's burst) until
  a claim with another key, idleMs (default quietMs) without one, or any
  operation; Cmd+Z right after a drag undoes all of it.
- The ceiling is named where it lives: another writer's write to a
  claimed file between Studio's write and its claim folds into Studio's
  entry, and a write filed to another writer's open window stays there.
- Route: POST /projects/:id/history/claim { label, paths, coalesceKey?,
  idleMs? } -> { claimed: { id } | null }.

* fix(studio-server): a drag back to its start claims nothing, and next steps name their files
2026-09-24 20:55:58 -04:00
Miguel Ángel 86fa10ced4 perf(studio): show a film's first frame sooner by loading preview assets by URL (#4357)
* fix(studio): serve preview assets by URL instead of inlining them as base64

The Studio preview route serves project files under a base href, but both preview adapters
called the bundler with its self-contained defaults, so every image and font was inlined
once per reference. One exported option set now owns how a preview bundle is built.

* test(studio): cover poster, srcset and sub-composition preview asset URLs

Also types the Vite adapter bundler with BundleOptions, so the shared preview options are
checked against the real option set.

* fix(studio): tag a preview asset for revalidation only once it has settled

Preview assets are now served by URL, so the asset route serves every image and video. It tagged
them by mtime and size; two same-size writes inside one filesystem tick share an mtime, and copy
tools (cp -p, rsync) set mtime back, so a browser could keep stale bytes after an edit. The route now
tags a file by inode, change time and size, and only once its last change is three seconds old; a
younger file is served without a tag and refetched.
2026-09-23 21:08:56 -04:00
Miguel Ángel 8cb7d06db6 perf(studio): re-render only the edited scene's thumbnails after an edit (#4315)
* perf(studio): refresh only the edited scene's thumbnails and let the preview load first

One scene edit regenerated every sidebar and timeline thumbnail, and those renders starved the new preview's requests on the Studio server. The thumbnail cache now keys on what a composition renders from, the server names the compositions a write affects, only those thumbnails refresh, and composition thumbnails wait while a shadow preview reload is in flight.

* test(studio): pin scene-scoped thumbnail reuse and the preview-reload hold

Memoizes the scoped thumbnail signature on the project signature so requests keep reusing the adapter's cached one, keeps the fresh-signature check that catches a write the watcher has not reported yet, and adds tests for sibling-scene reuse, root-head invalidation, the affected-composition set, per-path revisions and the scheduler hold.

* refactor(studio): share the file-change payload guard

* fix(studio): match thumbnail revisions for scenes mounted with a ./ path

* perf(studio): keep signature cache keys constant-size

* style(studio): format thumbnail-scope changes

* docs(studio): trim thumbnail input comments
2026-09-23 10:29:01 -04:00
Miguel Ángel 1b8f8a43d4 fix(cli): stopping the preview server no longer leaves a Chrome running (#4183)
* fix(cli): stop the preview server's browser when the server exits

Cancel in-flight renders and thumbnail launches before draining the
browser pool on shutdown, instead of only closing whatever browser was
already registered. A render whose Chrome died from the shutdown signal
itself was being misclassified as a transient failure and retried with a
fresh, untracked browser that outlived the process. Reject new render and
thumbnail requests once shutdown has begun, and await an in-flight
thumbnail launch before closing it.

* fix(cli): close preview browsers before a hung render, keep SIGINT armed

shutdown() awaited renders before closing browsers, so a render slower
than preview.ts 3s exit watchdog left Chrome running when it fired.
Close the thumbnail browser and drain the pool concurrently with, not
after, the render wait, and bound the wait under that watchdog.

A second Ctrl+C/SIGTERM during shutdown removed the one-shot signal
handlers, so it hit the OS default and killed the process before
cleanup ran. Use persistent handlers guarded by the existing
shuttingDown flag instead.

Also: getThumbnailBrowser could still hand a live lease to a request
that lands after shuttingDown flips true; trim a comment over budget;
replace a fixed-sleep test race with a drain-signal barrier.

* fix(engine): make browser pool shutdown terminal, not just draining

drain() resets its drainPromise to null once it settles, so acquire()
only waits for an in-flight drain -- a render still unwinding after
shutdown could relaunch Chrome the instant that drain resolved
(probeStage.ts:449-465 has exactly this gap between an abort check
and a later acquireBrowser call). No non-shutdown caller reuses the
pool after draining it (checked every drainBrowserPool()/drain()
call site), but added a separate terminal close() rather than
changing drain()'s own semantics, so a future reuse caller stays
safe by default.

BrowserLeasePool.close() sets a permanent closed flag before
draining, and acquire() checks it both before and after its one
await point, so a request already mid-await when close() lands still
sees it once that await resolves. studioServer's shutdown() now
calls the new closeBrowserPool() instead of drainBrowserPool().

Also bounds drain()'s own wait: a close() that hangs past 1s now
gets escalated to a force-close instead of blocking the caller
indefinitely, keeping total shutdown time under preview.ts's 3s exit
watchdog alongside the existing render-wait bound.

* fix(engine): trim closeBrowserPool JSDoc to house comment length
2026-09-22 22:49:44 -04:00
cc19b8c812 fix(server): contain static file requests within their served roots (#4217)
* fix(server): contain static file requests within their served roots

Static asset handlers joined the raw request path onto their root
directory without checking where it landed. Hono decodes percent
escapes while routing, so an encoded backslash (%5c) arrives as a real
separator on Windows and dot segments arrive already collapsed —
"/assets/..%5c..%5csecret" and "/%2e%2e%2fsecret" could read files
above the studio bundle root (embedded Studio server) and above
compiledDir/projectDir (engine render file server). Browsers never
request those shapes, but anything that can reach the bound port can:
raw local clients, LAN peers when the preview binds 0.0.0.0, and a
shared-machine process hitting the render server.

Both handlers now resolve the request path first and refuse anything
that collapses outside its root, using the same lexical containment
the preview asset route already applies — bundle/project assets behind
symlinked directories keep being served, only dot-segment escapes are
rejected. Route-level pathSafety tests pin the behavior in both
packages, including the Windows backslash shape and the
symlinked-asset cases from the descriptor-pinning regressions.

Validated: new containment suites fail on the prior handlers (200 +
marker file content served from outside the root) and pass with the
guards; cli server (140), engine services (1024+, matching the main
baseline incl. pre-existing browserManager failures), typecheck,
oxlint, oxfmt and the full workspace build all clean.

* fix: close fallow audit findings, prove containment cross-platform

Fallow audit (health/complexity): createFileServer's request handler
exceeded the CRAP-score threshold once the new containment checks were
added. Extracted resolveContainedPaths, a small pure function that
resolves and validates both roots, cutting the handler's own branching
back down.

Fallow audit (duplication): the new pathSafety test files copied their
temp-root/studioDir setup and teardown from the existing staticAssets
test wholesale. Extracted the shared parts into
studioServerTestFixture.ts (makeStudioServerRoot, writeStudioIndexHtml,
cleanupStudioServerRoot); only the per-file vi.mock("node:path", ...)
call stays duplicated, since Vitest requires it declared statically in
each test file and it cannot be moved behind a shared function -- that
one block keeps a narrow, targeted ignore comment instead of a
file-wide one.

Security claim: isWithinProjectRoot's %5c-decoded-backslash escape is
real, but only on Windows -- POSIX never treats a literal backslash as
a separator, and Hono leaves %2f undecoded in c.req.path, so none of
the new tests' encoded-traversal payloads produce an actual escape on
Linux (verified empirically: they pass identically with the fix
reverted). isWithinProjectRoot now takes an optional path-module
override (defaulting to the host's native node:path, so every existing
caller is unchanged) so its win32 and posix branches can be unit
tested directly from one OS, the same pattern already used by
producer/fileServer.ts's isPathInside. New tests cover a backslash
traversal, a mixed backslash/forward-slash traversal, and a
drive-letter path escaping the root under path.win32, plus the
existing posix case -- confirmed each one fails when the check is
removed. The HTTP-level tests stay as-is: real regression coverage for
them comes from the windows-latest CI job, which runs both new
pathSafety suites unfiltered.

---------

Co-authored-by: Miguel Ángel <miguel.sierra@heygen.com>
Co-authored-by: orphan4183 <kingenmaww@gmail.com>
2026-09-22 22:18:56 -04:00
Vance IngallsandClaude Sonnet 5 24c3e197ef fix(studio): cutover gate classification, SSE cross-project bleed, benign races (#4269)
Implements the fixes from the 2026-09-21 cutover dashboard read
(plans/sdk/2026-09-21-cutover-dashboard-fixes-plan.md):

- sdk_cutover_failed now carries `family` and `error_kind`
  (network/conflict/http/sdk). The one production gate event was a raw
  `TypeError: Failed to fetch` from an unwrapped fetch (readProjectFile /
  writeProjectFile's preflight), which an instanceof-only classifier would
  still file as "sdk" and trip the rollback gate — added a message-based
  fallback for the browser's fetch-rejection strings.

- studio:sdk_session_unavailable's `network` reason now carries `elapsed_ms`
  and `hidden` (document.visibilityState at rejection), separating a
  near-instant policy block (CSP/PNA/extension) from a dropped connection
  the tab or server going away mid-flight.

- The ownership-race branch in useSdkSession's open effect now emits
  sdk_session_superseded instead of sdk_session_unavailable{stage:ownership}
  — it's a benign race (identity moved on mid-open), not a broken
  precondition, and was being counted as one on the dashboard.

- Root-caused and fixed the read-404 "storm": /api/events (CLI host) and
  the vite-dev hot-reload channel are one connection per SERVER, not per
  project. A stale tab left open after `hyperframes preview` restarts on a
  different folder (same port) received every save the CURRENT project
  made, reloading its preview (which then 404s) and re-reading its own
  composition on each one. Both transports now carry `projectId`; the
  client-side coordinator drops a delivery whose projectId doesn't match
  the tab's (absent field still passes, for one release of skew).

- studio-server's file routes report `why` on 403/404: `project_dir_missing`
  (new — the CLI host's static resolveProject kept answering for a project
  whose folder was renamed/deleted under a running server, which used to
  fail closed as an indistinguishable path-traversal 403) vs `nul` vs
  `outside_project`.

- absent_or_empty reads now carry `path_in_tree` (against the caller's
  loaded file tree). Instrumentation only, per the graveyard page
  (clearing-activecomppath-on-tree-absence) that refuted the "clear
  activeCompPath" fix this was the proposed next step for.

Tests: unit coverage added for every change (sdkCutover.test.ts,
useSdkSession.lifecycle.test.tsx, useExternalFileChangeCoordinator.test.tsx,
studioServer.test.ts, files.pathSafety.test.ts). oxlint/oxfmt clean,
tsc --noEmit clean on studio/studio-server/cli.

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-22 01:40:47 -07:00