* fix: refuse media paths that ffmpeg's image2 demuxer would read as a pattern
ffmpeg's image2 demuxer reads %d, %03d, %% and a % before a wildcard in an
input path as a pattern of other files, folders included. Every project,
private-file and received-file check approves the literal path, so a
composition could name a placeholder whose pattern reaches images outside
the project and get them back as video frames.
Every ffmpeg and ffprobe input built from a project file now goes through
assertLiteralMediaInput, which refuses such a local path before ffmpeg runs.
The engine's urlInputArgs, the parsers' mediaInputFormatArgs and the
studio-server's new mediaInputArgs all take the input path, so the CLI
snapshot and cloud offload, lint, core grade analysis and studio-server
callers are covered too. URLs and other percent signs, such as %20, are
read as before.
* build(parsers): declare the literal-media-input subpath
* build: raise the parsers packed-size budget for the literal-media-input subpath
The new subpath adds its own built entry, type file and export map rows,
about 2.7 KB packed. It is a separate module so test suites that mock
ff-binaries still run the real path check.
* test(parsers): a harmless name shaped like a pattern is refused too
* fix(studio-server): cache reads never follow a link the project ships
The waveform and peaks caches, the thumbnail cache, the stored preview
documents and the preview proxy copies all live in folders inside the
project, which its author controls. Their reads opened entries with
link-following calls, so a project could ship a link at a predictable cache
name and have Studio return the file it pointed at.
Each of these reads now goes through readProjectCacheFile or
isProjectCacheFile: the entry must be a plain file, reached with no link
from the project folder down, and is opened without following links.
Anything else is a miss, and the entry is rebuilt.
- Waveform and peaks entries must also parse as an array of numbers.
- A proxy copy, its fast and content index files, and the pieces of a
chunked copy count only as plain files.
- Stored preview documents carry an HMAC under the user's private preview
token, so a document the project shipped is never served. Without a
token, nothing is stored.
* fix(studio-server): the proxy copy lock treats a link at the copy name as not made
The copy lock tested "the copy already exists" with a link-following check,
and the transcoder returned the copy path unchecked when the lock said
another process had made it. A link at the copy name was then served.
- acquireCopyLock takes the caller's "copy made" test; the transcoder
passes isProjectCacheFile and re-checks the path before returning it.
- Copy index files are written by rename, so a link at an index name is
replaced instead of written through.
- Chunk pieces are checked from the project folder down, like every other
cache entry.
- A cache entry with more than one name (a hard link) is a miss.
* fix(studio-server): bound preview stills and keep proxy work to the Studio's own pages
- Queue at most 16 stills behind the 4 being made; past that, answer 503 with Retry-After.
- Refuse a still past the end of the source before starting ffmpeg (404).
- Refuse a ?hf-proxy request on a plain preview path when another site asks for it. The
Studio's own opaque frames already load through the frame-token path, and sandboxed
thumbnail captures now do too.
— Rames
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* chore(studio-server): raise packed size budget for the still-queue and cross-site checks
The bounded still queue, the past-end refusal and the cross-site proxy
check add about 2.2 KB to the packed studio-server (180252 bytes in CI).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cli): snapshot shows control characters in composition text as escapes
* fix(studio-server): making or serving a still sweeps the transcode cache
* fix(cli): batch render outputs stay inside the --output folder
A row value may still name a subfolder of the folder written before the
template's first placeholder, but a value that resolves outside it stops
the batch before any folder is made or file is written.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cli): project text shows control characters as visible escapes
compositions, lint, snapshot and info --media print composition ids, sources,
element ids, lint messages and media paths through one helper that writes
C0, DEL and C1 control characters out as \xNN, so they reach the terminal as
text. The CLI's own colors are unchanged.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(studio-server): waveform and peaks key one cache entry per file and refuse other sites
Both caches are keyed on the resolved project-relative path, so another
spelling of the same file (a doubled or trailing slash) reads the cached
peaks instead of decoding again. Waveform and peaks requests that another
site makes are refused the way thumbnail requests already are; the Studio
page asks for both as itself.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(studio-server): preview stills run at most four at a time
A video's stand-in still is made through a small job queue: four at once,
32 more waiting, and a 503 with Retry-After beyond that. A waiting request
whose client goes away leaves the queue without starting ffmpeg.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cli): batch output folder check keeps backslash names and row-named paths
A trailing backslash counts as a separator only where it is one, and the
check compares path segments. A template that starts with a placeholder names
no folder, so each row's value is the whole output path as before.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cli): lint header shows control characters in file names as escapes
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(studio-server): a finished or in-progress still never waits for a still slot
Only a still that is neither on disk nor already being made takes one of
the four slots, through a hook resolveStill gives the route. Waiters queue
without a cap and nothing answers 503, since a poster is never asked for
again. A waiter whose client leaves still never starts ffmpeg; a request
that shared that waiter's still tries again on its own.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* chore: raise the studio-server packed budget to 172000
main already packs about 170 KB against a 168500 budget; the request guards,
still slots and cache-key change here add about 550 bytes.
* fix(core,studio-server): a preview served to another site offers no editing port
When the Studio server answers a preview document to another site's
request, it now marks the document, and the runtime's editing agent
ignores every connect in a marked document. The Studio's own frames,
which load the preview from the same origin, keep the editing port.
The marked copy carries no ETag, so it is never revalidated in place of
the unmarked one.
* fix(studio-server): a media still stops when no request waits on it
Each still job now counts the requests waiting on it. A request whose
connection closes leaves the job, and when the last one leaves, the
job's ffmpeg is killed and the job is forgotten, so the next request
starts afresh. A caller that passes no signal keeps the job running,
and a request that has already closed starts nothing.
* test(studio-server): group the still cancellation tests after the real-ffmpeg still test
* fix(studio-server): a preview framed by another site is never revalidated
A frame load of a preview from another site now drops If-None-Match and
If-Modified-Since before the route answers, so it always gets a fresh,
marked document instead of a 304 that could reuse the unmarked copy a
browser cached for the Studio's own page on the same site. Subresource
loads keep their validators.
* fix(cli): check findings and keyframes headers show control characters as escapes
check prints each finding's message, source file, selector and fix hint, and
keyframes prints each composition's name and source, through terminalText.
* test(studio-server): a request sharing an abandoned still waiter gets its still
* chore(studio-server): raise the unpacked size budget for the still job slots and cross-site guards
* fix(cli): layout and contrast lines in check show control characters as escapes
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* 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>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(core): hlg footage tone-maps to sdr at the bt.2408 reference white
* fix(core): an HLG clip whose stream leaves its transfer unset keeps HLG's white
An SPS with an unspecified transfer takes the stream's tag, as its frames do; a failed keyframe read is not cached; the grey test needs ffmpeg 8.
* fix(cli): check stops after 2 minutes of video copies and says how to finish
* fix(cli): check copies only the stretch of a video the composition plays
* docs(cli): check copies only the played stretch of a long video
* docs(cli): shorten two comments on the copy window
* fix(cli): finding crops and frames get the same copy windows as the check
* fix(cli): drop a comment the ratchet counts
* refactor(studio-server): keep runFfmpeg under the complexity gate
* feat(preview): an unplayable video shows its own frame while its copy is made
* fix(preview): drop the comment on the copy's light flag
* fix(preview): shorten the still helper's doc comment
* test(preview): each proxy-wait test starts with no copy report left over
* fix(preview): cached still frames are swept with the proxy copies
* feat(core): make a heavy clip's lighter copy ahead of time when the host asks
* feat(core): keep the comment share of the proxy transcoder where it was
* feat(core): split the copy-ahead choice so each part stays simple
* feat(core): the preview route passes the copy's urgency as the proxy options expect
* fix(studio-server): a copy another process holds without progress ends in a named error
* fix(studio-server): a long source's in-progress piece counts as the owner's progress
* fix(preview): the proxy copy for the video at the playhead is made ahead of the rest
* test(preview): the resolveProxy assertions carry the priority option
* fix(preview): the proxy copy asked for last goes first, and a repeat ask moves it to the front
* refactor(preview): the proxy wait loop moves its header and progress handling into helpers
* fix: phone videos with an undecodable first audio track check, preview and render
* fix(engine): a rate-lane clip bakes its ramp from the decodable audio track
* test: phone-clip tests end ffprobe options before the input
* fix(studio-server): an HDR clip previews and snapshots the way the SDR export renders it
Footage tagged HLG or PQ played raw in the preview, where the browser tone-maps it its
own way, while the SDR export tone-maps it with zscale and hable: the same clip came
out lighter and with different reds and blues. HDR video now takes the tone-mapped
preview copy (the filter the export uses), and a snapshot still of HDR footage runs
the same tone map. Without an ffmpeg that has zscale and tonemap the clip plays
natively, with a warning that names the missing library.
* fix(studio-server): an HDR clip is never playable for preview, whatever its codec
Only HDR H.264 and ProRes took the tone-mapped copy: an HDR HEVC, VP9 or AV1 clip kept
its codec's test type, so a browser that can decode it was judged able to play it and
the original played with the browser's own mapping. An HDR clip now has no test type, so
the swap always fires. The missing-library warning no longer names the file.
* test(cli): the HDR still test ends ffprobe's options before its input
The repo's ffprobe argv contract requires "--" immediately before the input path; the new
test passed the still's path without it.
* fix(studio-server): a failed preview copy says why its output could not open
* fix(studio-server): a failed preview copy reports its causes and what its source is
* fix(studio-server): failure reports hide spaced paths and survive a vanished source
* refactor(studio-server): read a probe's result in its own function for the complexity gate
* fix(studio-server): close the source facts function the rebase left open
* fix(studio-server): a failure report reads the source size through one open descriptor
* feat(studio-server): a copy being made says how far it has got, and can be retried
* feat(core): the preview reports its lighter copies' progress and retries failed ones
* feat(studio): the preview quality and its lighter copies' progress live in the player store
* feat(studio): every host forwards the preview quality, and the choice is kept per computer
* feat(studio): the preview quality knows if a person or the app chose it
* fix(core): the first report of the lighter copies is not held back by the throttle
* test(studio): the preview quality preference test writes under the real key
* fix(core): a quality change reports its copies at once, not after the throttle
* style: format the preview quality files
* feat(core): report how playback is going, and what the preview holds, to the host
* fix(studio): the preview quality levels come from a browser-safe core entry
* style: format the new entry's files
* style: drop two comments the file's ratchet and the citation check refuse
* feat(core): tell which lower levels would give a video a lighter copy
* fix(studio): drop the old level's playback health when the level changes
* feat(studio-server): preview facts carry the probed codec of every video
* refactor(studio): route the preview's reports through a table for the complexity gate
* fix(core): a copy's retry flag is sent on the first ask only, not on every poll
* fix(core): type the health report and restore the player hook's complexity directive
* style: cut four comments the comment ratchet refuses
* fix(studio): keep playerStore.ts within its 600-line cap
* fix(core): a scene mounting does not restart the playback health window
* fix(core): the playback health window restarts only when the display scale changes
* fix(core): a repeated display scale no longer restarts the playback health window
* fix(studio): route the preview's reports by an explicit list of message types
* perf(studio-server): a preview copy is keyed by the file's content, so copied projects reuse it
* fix(studio-server): copies are keyed by content and made by one process at a time
* docs(studio-server): shorten the copy lock comment
* fix(studio-server): find a copy by place and time first, by whole-file content when that misses
* fix(studio-server): hash small sources in one read; wait longer in tests for the hash
* test(studio-server): cache folder listings ignore the copy index files
* style(studio-server): format the copy lookup files
* docs(studio-server): shorten the copy lookup comment
* fix(studio-server): hash a source through one open handle, not a check then a read
* fix(studio-server): hash through one descriptor, keeping the small-file path synchronous
* style(studio-server): format the cache key file
* feat(core): tell which video files deserve a lighter preview copy, and at which size
* feat(studio-server): serve lighter copies of heavy playable files, a keyframe every second
* feat(core): the preview plays lighter copies of heavy videos below full quality
* style: shorten two comments
* style: shorten a comment
* style: shorten a comment
* fix(core): format the preview quality files and split the copy sizing for the complexity gate
* style: format the studio-server preview files
* fix(core): type the copy job's level as a preview quality
* chore(producer): raise the package size budget for the preview runtime growth
* perf(studio-server): the browser-playable copy of an alpha video encodes on four threads
libvpx runs on one thread unless told, so the alpha copy of a 4K video took several times its length on a small machine.
* docs(studio-server): drop a comment line the name already carries
* fix(cli): a long video copy reports progress, resumes in 15 s pieces and stops only when stalled
* perf(core): a video copy's size box follows the stage within a fifth, not a half
* docs(cli): shorten two comments to the line limit
* fix(cli): the copy heartbeat drops a finished copy; size budgets follow the stall and progress code
* chore: size budgets rise by this change's measured bytes
* fix(cli): check copies hostile videos at the composition size, not the source size
* fix(cli): the check server serves the copy the page names with hf-proxy-box
* feat(cli): check --prepare-media makes the video copies alone, and a stopped copy resumes
A long source is copied in one-minute pieces that stay in the cache, so a copy
that is killed or runs out of time continues from its finished pieces.
check --prepare-media runs only that step: no browser, no report, a per-file
result as JSON, and exit 1 when a copy failed.
* fix(studio-server): keep finished copy pieces while their copy runs
The short limit for dead partial copies would delete the first pieces of a
long copy that is still encoding. Finished pieces now follow their own
one-hour limit and are never swept while their copy is in flight.
* refactor(studio-server): shorten two comments
The comment gate limits a comment line to 120 characters and a run to four lines.
* refactor(studio-server): drop comments the names already carry
The comment ratchet lets a file's comment share only go down.
* fix(cli): the check server pre-warms the copy the page asks for, not the source-size one
The server started a source-size copy of every hostile video next to Chrome on
each check, because its pre-warm passed no box while the page and the up-front
copy use the composition's box. The pre-warm now takes the same box, found by
the one helper the up-front copy uses.
* fix(cli): end a check on no progress, not on a 120 s wall clock
The check ended 120 s after Chrome was ready no matter what it was doing, so a
long project whose sampling and overlap pass each kept working still failed
(the overlap pass was one page call that reported nothing for its whole run).
The deadline is now an idle clock: every phase entered, every sample finished,
every overlap batch of eight times and every operation that settles restarts it,
and the check ends only after 120 s with none. The overlap grid is asked for in
batches so it can report between them.
* refactor(cli): shorten the idle deadline comment
The comment gate allows 120 characters on a comment line.
* test(cli): check's overlap grid runs in page tasks of at most 8 samples
* fix(cli): check test types for the cli lib, studio-server size budget for resumable copies
* fix(studio-server): keep transparency in proxies of VP8/VP9 alpha webm
A webm whose alpha lives in the VP8/VP9 side channel (alpha_mode=1,
pix_fmt yuv420p) was proxied to opaque H.264, and the VP8 proxy path
decoded it with ffmpeg's native decoder, which drops alpha. The alpha
rule and the alpha-reading decoder now live once in
@hyperframes/parsers/media-alpha, used by engine and studio-server.
* build(parsers): raise the packed size budget for the media-alpha subpath
parsers already sat at its packed budget on main; the shared alpha rule
adds 676 B of JS and 803 B of declarations (190958 B packed in CI).
A check on a project whose videos Chrome cannot decode (HEVC, HDR) first transcodes each
of them, which on phone footage takes minutes and printed nothing until it was done.
Closing the page server now stops the media proxy copies it started (pre-warms and the page's own asks). A copy whose last caller leaves is now stopped even after its ffmpeg started; callers without a signal still always get their copy.
* fix(cli): check warns when a video's browser-playable copy cannot be made
* fix(cli): big projects stop failing proxy prep, and a failed copy is reported once
* fix(cli): proxy failures name the real ffmpeg error, and a broken ffmpeg is reported once
* chore(studio-server): shorten the batch proxy resolver doc comment
* fix(studio-server): the public proxy cache path names boxed preview copies too
* fix(studio-server): keep the proxy cache path docs within the comment budget
* fix(studio-server): the preview's proxy copy jumps queued thumbnails, and abandoned copies drop
* fix(studio-server): a re-ask right after a dropped proxy copy gets a fresh copy
* fix(studio-server): leave Studio's preview route on the normal proxy queue
* docs(studio-server): shorten the proxy transcoder's detachment note
* fix(studio-server): a refused proxy copy still invalidates thumbnail captures
* perf(studio): preview decodes hard-to-play videos at the size they are shown
Studio's copy of an HEVC or ProRes clip was made at the source's full size, so a 4K clip was decoded at 4K inside a preview a few hundred pixels wide, and back-to-back 4K clips flashed the background at their cuts. The player now reports how large it shows the composition, the runtime asks for a copy sized to the shown video (on a ladder of sizes, never above the source), and Studio stops pre-warming source-size copies. CLI play, static serving, publish and renders keep the source-size copy.
* fix(studio): sized preview copies follow zoom, hover previews and the newest size
Studio reports the preview's on-screen scale when a zoom settles and for composition hover previews, which no player measures. The runtime loads only the newest size asked for, regrows a first copy made while the frame grew, and never replaces a copy with one smaller on either side. The player's scale is measured against the frame's own layout width.
* fix(studio): keep comment shares and file sizes within the repo ratchets
* test(studio-server): end the sizing test's ffprobe options before its input
* fix(studio): hover previews report their size once their runtime is ready
* feat(cli): add hyperframes clean to find and remove what HyperFrames left on disk
`hyperframes clean` lists leftover render work dirs, debug renders, the history of projects
that no longer exist, idle video proxies and extracted video frames, with sizes, and removes
them. `--dry-run` removes nothing, `--json` is for agents, `--snapshots` also removes
snapshot folders (otherwise listed as reclaimable). It never touches outputs, sources or
anything a running render or preview still owns.
* docs(cli): say that clean does not search a project's subfolders
* fix(cli): clean test compares folder names on Windows and the skills manifest is regenerated
* fix(studio-server): the proxy cache sweep removes only files the transcoder named
It removed any idle .mp4 or .webm in .transcode-cache, so a user file placed there, or reached through
a symlinked cache folder, could go. Proxies are always <sha256>.<ext> and their temp files
.tmp-<uuid>-<proxy name>; nothing else is swept.
* style(producer): keep a renderDirOwner doc comment within 120 columns
* fix(studio-server): a cold proxy copy answers 202 at once and the preview retries until it lands
* fix(studio): timeline filmstrips wait for a clip's proxy copy instead of failing on the 202
* fix(studio-server): a copy that cannot be made reports its failure instead of answering 202 forever
* test(studio-server): pin that a full queue is not remembered and a reset probe stops waiting
* test(studio-server): pin that a failure outside ffmpeg is remembered too
* style(studio-server): keep comment share at base in the transcoder and decoder
* fix(core): a clip's proxy URL goes on the video only once the copy is served, so every reader of it works
* fix(player): the parent media mirror follows a clip's src, so it plays the preview copy once it lands
* perf(player): the mirror re-points a clip only when the parent takes over playback
* style(core): shorten the sync-state comment in the proxy swap
* fix(studio): the timeline follows a clip re-pointed at its preview copy
* fix(core): a failed readiness check is retried instead of leaving a clip on its original
* fix(studio-server): a composition card rendered while preview copies are made is not cached
* fix(core): frame captures wait for a pending preview copy as long as for a loading video
* fix(studio-server): the preview-copy check uses the shared realpath from main
* fix(player): re-pointing a clip onto another clip's file no longer plays that file twice
* fix(player): a clip that replaces another on the same file keeps its sound
* 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
* 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
Rebase #3529 onto current main. Preserve all 16 issue-scoped Studio server, lint, and CLI child-process windowsHide options, including main's PowerShell null guards and stderr suppression in orphanCleanup.
Regression tests continue to assert windowsHide at each scoped spawn site. #3476 and #3430 remain out of scope.
Co-authored-by: heygengenesis[bot] <262951085+heygengenesis[bot]@users.noreply.github.com>
Co-authored-by: miguel.sierra <229591595+miguel-heygen@users.noreply.github.com>
## What
Allow Studio Preview to serve an asset reached through a project-local symlink whose target is in a shared directory outside the project, including browser-hostile video assets that need an authoring proxy.
## Why
Preview rejected these assets with a 404 while the renderer accepted the same path. The initial static-route fix still failed for HEVC, ProRes, AV1, and VP9 assets because the proxy transcoder rejected the external target.
## How
Use lexical project-root containment for the read-only static asset route and proxy source request. The transcoder canonicalizes the target for ffmpeg and includes that identity in its cache key, while keeping the proxy cache inside the project. Composition source paths retain canonical containment because preview can persist their data-hf-id values.
## Test plan
- [x] Unit tests added/updated
- [x] `bun run --cwd packages/studio-server test` (397 tests)
- [x] Studio Server typecheck, oxlint, and oxfmt
- [x] External-symlinked hostile-video proxy route regression
- [x] Static-route traversal regression
- [ ] Documentation updated (not applicable)
* feat(media): alpha-capable authoring proxies
Alpha sources were refused a proxy before the codec map ever asked whether the
browser could decode them, so a ProRes 4444 alpha file (which no browser
previews at all) rendered black forever, while an alpha WebM (which previews
fine) was already covered by the browser-safe check on the next line. The alpha
veto earned nothing and cost the one case that needed help.
Alpha is now a target-codec choice rather than a veto: alpha sources transcode
to VP9 + yuva420p in WebM, everything else keeps the existing H.264/MP4 path
byte for byte. Only files no browser can preview are proxied, which is the rule
the runtime already followed everywhere else.
WebM cannot carry AAC, so the VP9 path uses Opus and drops the MP4-only
faststart flag. PROXY_PARAMS_VERSION moves to v3 so clients stop serving the
previously cached proxies.
Safari does not decode VP9 alpha and still shows black for alpha sources, as it
does today: this is better on Chromium and Firefox and no worse anywhere.
* fix(media): infer proxy variant for rescue
* fix(media): preserve alpha proxy hardening after restack
* feat(studio-server): bound the proxy cache with LRU accounting
Adds cache accounting and bounded cleanup for transcoded proxies, and keeps
.transcode-cache out of git. Standalone: the transcoder consumes it next.
* feat(studio-server): transcode bounded H.264 proxies on demand
Adds the proxy transcoder: a bounded work queue with per-key dedupe, a hard
kill ceiling, TTL'd failure memory so a broken asset is not retried forever,
and pixel/color normalization for browser playback. Writes through a temp name
and renames on success, so a cache entry is never partial.
Carries a TEMP fallow ignoreExports entry: this module lands below its
consumers, so a per-PR audit sees its exports as unused until the preview weld
arrives. The entry is dropped there.