* fix(cli): a project .env provider key prints a note when it is used
A provider key from a project .env is still used when no own credential
competes. Capture vision (OpenRouter, Gemini, Google and both Vertex parts),
snapshot --describe, Gemini speech and Lyria music now print one note per key
before it is first used, naming the variable and the escaped .env path, as
the ElevenLabs note does. The ignoring notes escape the path too, and the
media-use skill gets a generated copy of the CLI's terminal-text helper.
* fix(media-use): the audio scripts read a received .env by the CLI's full rule
The audio scripts judged a project .env as received only from
received-files.json at or above it. They now use a generated copy of the
CLI's rule, which also reads the host's received-state file, nested records
and the received content hashes, and treats an unreadable one as received.
A parity test runs the CLI and the copy over the same projects.
A key the CLI unset from a .env is now passed to the scripts it launches,
so they do not load it again from the same file.
* fix(media-use): match the CLI's folder walk and judge a parent .env by itself
The received-rule copy now skips folders by the CLI's exact private-path rule,
so a hidden Studio folder with an asset-like name is walked as the CLI walks
it. A .env the scripts find in a folder above the working one is judged only
by records and host state at or above that folder, so a received sibling or
a large parent folder cannot flip the person's own key. Keys the CLI unset
are matched by the folder's real path.
* fix(media-use): match the received rule's narrowed private-file check
The CLI's private-file rule now treats a hidden file as private whatever its type,
and framework build-output folders and service-account key names as private.
The media-use copy of the rule follows it, so the parity cases for hidden
asset-named Studio folders agree again.
* fix(cli): keep files received that a host's kept record still lists
When the received-state file names a project as expected and the host
keeps its own copy of that project's record beside the state file, the
received-file checks read the record together with each entry that copy
lists whose path still holds something. A record shortened or emptied
outside the host no longer makes those files read as the person's own.
A kept copy with no list, a doubted one, a link or one that cannot be
read counts every file as received; with no kept copy, nothing changes.
* fix(cli): keep a record's own lines when the host's kept copy cannot be read
A kept copy with no list, or one that cannot be read, now counts every
file as received through its own entry, named by the kept copy's path,
instead of hiding the record's lines from Studio's rename and move
tracking. A copy found only by folder identity counts only when its
identity matches the folder, and a copy that disappears mid-read counts
as no copy.
* docs(cli): say a kept entry whose file is gone is not added back
* fix(cli): say a listed received file is gone, and drop a media file's line on rename
Follow-up to the change that keeps a deleted received page listed.
- The render warning for a listed file that no longer exists now says it
is gone and how to clear it.
- A listed file whose name was already a media name drops its old line
when renamed to another media name, so repeated renames leave no
dead lines.
- The docs say that any listed file that is not media by its first bytes
stays listed after a delete, and that the line can sit in a record
above or inside the project.
- A test restores content after a plain Studio delete and checks that
outside files stay refused.
* test(cli): match the gone-file warning without a POSIX path, for Windows
A Studio delete took a received page's line off the record, and files
created afterwards were not followed. A script in the preview could
delete every received page and create it again with new bytes, so the
project no longer counted as received and outside files were read.
A deleted page, stylesheet or script now stays listed, so whatever is
written in its place counts as received. A received page renamed to a
media name keeps its old line too. Deleted or renamed media, fonts and
images still drop off, so a media-only project keeps working.
* feat(cli): check reports text drawn over a face in a video
The layout audit reports text painted in front of an opaque video with its
word boxes and where the video's frame lands; Node finds the faces in the
video file with the detector `measure face` uses and adds a `text_over_face`
finding (info from 5% of the face covered, warning from 30%) with
`coveredFraction` and `faceRect`. `layout.faceCheck` in the report says
whether the pass looked. `data-layout-allow-on-face` waives it.
Also reads a two-token `object-position` whose first token is "50%" as the
horizontal one.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
* feat(cli): measure cuts names the shot a take resumes
A shot that returns to an earlier camera setup after at least one other
shot (a wide take, a close-up cut into it, the wide take again) carries
`continues`: the index in `shots` of the shot it resumes. It is read from
the signatures `cuts` already decodes, by the scene's edges, so a person
who has moved or an exposure that drifted does not hide the match.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
* feat(cli): measure hands follows a hand through a clip
`measure hands <video>` reports where a hand's palm (with the hand's
size), index fingertip or pinch is in each sampled frame of a stretch of
up to 15 s, from MediaPipe's hand landmarker. A frame with no such hand
is null, never filled in. The landmarker runs in the CLI's headless
Chrome on a page answered from disk; its code and model are not shipped
and are downloaded on first use, pinned by size and sha256, into the
trusted cache.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
* fix(cli): text_over_face is info only, and a stalled OpenCV download no longer stalls check
The face detector can take texture for a face, so text_over_face is
reported as info however much of the face is covered and never fails
--strict.
check passes its deadline and a 30 s limit into the detector's first-use
OpenCV download. A download that does not answer costs the face pass
only: faceCheck is { ran: false, reason }, the other findings are kept
and the process exits.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
A provider key from a project .env is still used when no own credential
competes. Capture vision (OpenRouter, Gemini, Google and both Vertex parts),
snapshot --describe, Gemini speech and Lyria music now print one note per key
before it is first used, naming the variable and the escaped .env path, as
the ElevenLabs note does. The ignoring notes escape the path too, and the
media-use skill gets a generated copy of the CLI's terminal-text helper.
A media-proxy request with neither Sec-Fetch-Site nor a Referer naming the
host was treated as same-site. Play, the static project server and Studio now
require a positive signal and refuse the request otherwise. The check
command's own re-request of failed media sends a Referer for its origin so it
keeps working.
— Rames
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(studio): a service worker a project left behind is gone before a preview frame loads
* fix(cli): the player page's inlined script list is escaped for a script tag
A `?hf-proxy=` request makes this machine run ffmpeg. Studio already refuses
one that comes from another site; the `play` composition route and the static
project server (used by check, snapshot and capture) still served it. Both now
answer 403 to a cross-site or same-site `?hf-proxy=` request before any probe
or transcode starts. Their own pages and plain asset requests are unchanged.
— Rames
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cli): leave files from outside the project out of Lambda and Cloud Run site uploads
A site upload for `lambda` or `cloudrun` followed every symlink in the project and
shipped what it pointed at, wherever that was on the machine. `publish` and `cloud
render` already ask first. Site uploads now leave a file or folder linked in from
outside the project out and name each one; `--include-outside-files` (or
`includeOutsideFiles` in the SDK's deploySite, renderToLambda and renderToCloudRun)
uploads them. publishProjectArchive called without a prepared archive now leaves
outside files out too, since nothing approved them.
— Rames
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(producer): drop the new option comments the comment ratchet refuses
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cli): a host can name projects whose received files are expected or all received
HYPERFRAMES_RECEIVED_STATE_FILE points at a JSON file a host app keeps,
listing project folders (by path, and optionally by device and inode) as
"expected" or "all". For an expected project, a missing received-files
record counts every file as received and is not started afresh; for an
all project, every file counts as received whatever the record lists. A
state file that is named but cannot be read counts every file as received.
A record lock dated in the future is taken over like a stale one.
* fix(cli): read host provenance state through one file handle
* fix(cli): canonicalize host state paths like record writes
* test(cli): expect canonical received warning paths
* fix(cli): a project .env provider key gives way to the person's own credential
A project .env could set OPENROUTER_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY,
the Vertex settings or ELEVENLABS_API_KEY and outrank a credential the person
set in their shell or saved settings. The earlier rule covered only received
projects; a cloned or downloaded project still won.
Now every project .env provider key is unset, with a note naming the file,
when a competing provider has a credential from a surer source: the shell or
saved settings first, then the person's own project .env, then a received
one. A project key with no competing credential is still used, model and
timeout settings still apply, and the media-use scripts note an ElevenLabs
key from any project .env before speech starts.
In the CLI process an own-project key yields only within the vision choice;
the media-use scripts remake the Gemini audio choice from the passed key
origins.
* fix(cli): weigh an own project's provider key only against credentials its feature can use
Review found that the global yield removed a person's own project keys where
the shell credential could not do the job: snapshot's Gemini key next to a
shell OpenRouter key, and a Gemini key that music needs next to a shell
service account.
- Startup keeps the received-project rule only.
- Capture drops a project .env vision key only when the shell or settings
hold another complete vision credential; the two Vertex parts are one
credential and are not weighed against each other.
- A key dropped once is not brought back when capture re-reads the same .env,
so its note prints once.
- In the audio scripts, an own project's Gemini key gives way only to the
other Gemini API key, which speech and music both accept, and an own
ElevenLabs key stays for an explicit provider choice.
* fix(cli): audio and media-use print control characters from project files as visible escapes
hyperframes audio, audio --read and media-use resolve (including
--candidates) printed file names, element ids, transcript words, model
descriptions and media manifest fields as they were. They now pass
through terminalText, so a control character shows as a visible \xNN
escape. The media-use engine runs without the CLI's packages, so it
carries a small copy of the helper. --json output is unchanged.
* fix(engine): playlist check refuses drive-relative and other colon-prefixed entries
ffmpeg reads an HLS or ffconcat entry with a colon before its first
separator as a URL or a drive, and opens it apart from the list's
folder. The folder check read entries such as C:Videos\a.mp4 or c:x.mp4
as names inside the folder and approved them. It now refuses any entry,
raw or percent-decoded, whose colon comes before its first /, \, ? or #,
as it already refuses absolute and parent-folder paths. http and https
segments are still kept.
* fix(cli): background-removal and Kokoro TTS model files are pinned to a sha256
The u2net_human_seg weights and the Kokoro model and voices files were
downloaded from release URLs and used whatever bytes arrived, and any
cached copy was trusted because it existed. Each file now has a pinned
size and sha256. A cached copy is checked before it is loaded and
downloaded again when it does not match. A download that does not
match is discarded with a message that names the file.
* fix(engine): playlist check reads entries from the folder ffmpeg uses
ffmpeg resolves a list's entries against its path cut at the first ? or
#. A list at proj/h#z/list.m3u8 naming ../h#z/x.ts was judged against
proj/h#z and approved, while ffmpeg opened proj/../h#z/x.ts. Entries are
now judged against the same cut folder. A list in a folder such as
"Take #2" still passes when its entries resolve inside that folder.
* fix(cli): a pinned model's cached copy is checked and removed under the download lock
ensurePinnedFile removed a cached copy that failed its check before the
download lock was taken, so a concurrent run could delete a file another
run had just published. downloadFile now takes a keepExisting check and
runs it under the lock: a copy that passes is kept, one that fails is
removed and downloaded again. The mismatch error now says the file does
not match its expected checksum, and that a retry helps only if the
download was interrupted or corrupted.
* fix(cli): audio escapes each field's line breaks, and media-use escapes recipe and stats output
The audio formatters escaped their output line by line, so a newline
inside a src, warning or transcript still printed as a real line break.
Each output line is now escaped whole with terminalText, which shows a
newline inside a field as \x0a. media-use resolve also escapes its
recipe lines and its --stats lines, which print recipe names, paths and
missed intents.
* fix(cli): media-use error messages show control characters as visible escapes
resolve printed error messages as they were, and some name project or
cache data, such as the known recipe names when a recipe is not found.
Every error: line now passes through terminalText, as the success lines
already do.
* ci: the edit accuracy filter includes the CLI model file check
The CLI's pinned model download now imports whisper/modelFile.ts, so a
change to it must run the edit accuracy bench too.
* test(cli): pinned model tests use private temp folders and rename like downloadFile
The tests wrote fixtures under fixed names in the shared temp folder,
and their download stand-in checked for a file before replacing it.
Each test now works in its own mkdtemp folder, and the stand-in asks
keepExisting directly and renames the part file into place, as
downloadFile does.
* test(cli): the media-use terminalText copy is checked against core's
The media-use engine keeps its own copy of terminalText. A CLI test now
compares the two over U+0000 to U+00A0, so a change to either fails
until both match. keepsDest moves above downloadFile's doc comment,
which belongs to downloadFile.
* fix(cli): a received folder's record is read wherever Studio moves it
The search for received-files records now walks every folder a render,
preview or publish can load files from, including renders/, dist/, .next/,
coverage/ and Studio's own folders in the project's .hyperframes/. A
received folder moved there by Studio keeps its files received.
Studio's folder delete and move also refuse a folder holding a
received-files record that lists a file outside its own folder, since
that file would stay behind with no record. A received folder whose
record lists only its own files can still be deleted or moved.
* fix(cli): a renamed or moved received file stays listed under its new name
The CLI-hosted Studio now follows every rename, move or delete it
completes in the received-files records, whichever client sent it. A
renamed file, or every file in a moved folder, stays listed under its
new path; a file moved out of a received folder is listed in the
project's own record. Changes are made under the record's lock, and a
record that cannot be changed is left as it was.
The per-file readers used by publish, cloud render, feedback and add now
count every file as received when a record lists a file that is no
longer on disk, since that file may be there under another name. This
matches the local render check. Projects with no record are unaffected.
* fix(cli): received content that leaves the record still counts as received
When a Studio rename, move or delete takes a received file off a listed
path, the sha256 of its content is kept in .hyperframes/received-content.json,
the file and format the desktop app uses; other keys in it are kept. A
file holding the same bytes counts as received for publish, cloud render,
feedback, add and the local render check, so content brought back by undo
or renamed outside Studio stays received. Studio's own backups do not count.
A listed file that is gone from disk now makes only pages, stylesheets,
scripts, SVG and links out of the project count as received, and the
upload warning names the gone file.
The record follows a request spelled in another letter case or Unicode
form by matching the name the disk holds, and waits for the record's lock
without blocking the server. Studio's folder delete and move no longer
refuse a folder whose record lists a file outside it; that file's content
is kept as received instead.
* fix(cli): a folder delete or move keeps what a record inside it lists elsewhere
Before Studio deletes or moves a folder, every file that a received-files
record inside the folder lists outside it is listed in the project's own
record by its path from the project folder. Such a file stays received
after it is edited, and a listed link stays received too. When the
project's record cannot be written, the delete or move is refused.
Received content that cannot be read is never written over, so the
desktop app's keys in it are kept. The warning about a listed file that is
gone now says how to clear it.
* fix(cli): received-content checks skip large non-code files and name a skipped search
A file larger than 16 MB that is not a page, stylesheet, script or SVG is
no longer read to compare its content with received content, so a large
archive is not read on every check. When the project has too many folders
to search for received-files records, the upload warning now says so.
The case-matching publish test now expects the gone-file rule on a disk
that tells letter case apart, and a comment no longer names a file path.
* fix(cli): name a gone received file from the project folder on every system
The gone-file note now names the file from the same project path the
record search starts at. On Windows, a short (8.3) folder name in the
temp path made the two spellings differ, so the note showed a long
relative path instead of the file's name.
Content hashing opens a file once, checks it through that handle and
reads from the same handle, and the received-content file is read before
it is classified, so nothing is checked by path and then used by path.
* fix(cli): received files stay received through undo, saves, and partial folder deletes
An undo, redo or restore lists again every file it writes that holds received
content, and a Studio save lists such a file before it changes it. So a Studio
delete followed by an undo and an edit leaves the file received.
A Studio rename, move or delete now records the received side first, under the
record's lock, and is refused when that fails: the content leaving listed paths
is kept, a renamed file is listed under its new path, and every line of a
record inside a moved or deleted folder is copied into the project's record.
Once the files have moved, only lines whose file was there and whose content
was kept are taken off. Lines at a rename's destination and lines whose file was
already gone stay. The search for records inside the folder has no size limit,
and nothing is locked when nothing is listed.
* fix(cli): unreadable received content counts every file as received
The readers treat a received-content file they cannot read the way they treat
an unreadable received-files record: every file counts as received, and the
local render check names the file it could not read.
A record line that points outside the project is ignored, so a record in a
received folder cannot make the readers look at or report files outside the
project.
* fix(cli): the CLI's own history undo and restore keep received files listed
`hyperframes history undo` and `restore` with no Studio running now list again
every file they write that holds received content, the same way Studio's
history routes do. A delete in Studio, then an undo or restore from the CLI,
then an edit, leaves the file received.
A Studio edit that names its file in the request body, such as a freeze-frame
edit, now lists that file first when it holds received content.
* test(studio-server): a loopback page with no fetch metadata is marked unless it is the app's own
* fix(studio-server): a loopback page with no fetch metadata is marked unless the app framed it
* test(studio-server): a page marked by its Referer names Referer in Vary
* fix(studio-server): a page marked by its Referer tells caches it varies by Referer
* fix(studio): dev Studio renders apply the received-project rule for outside files
The Vite Studio adapter started every render with files from outside the
project allowed. It now asks the CLI's outsideAssetsAllowed, the same check
the CLI's embedded Studio, hyperframes render and benchmark use. A project
whose received-files record lists code files, or cannot be read, renders
without files from outside the project, and the reason prints with a
[studio] prefix.
The adapter loads the rule from the CLI source through the dev server, as it
already does for background removal. It runs only from a source checkout, so
studio takes no package dependency on the CLI.
* fix(cli): a received project's .env provider key never replaces your own credential
A received project's .env could set OPENROUTER_API_KEY, GEMINI_API_KEY,
GOOGLE_API_KEY or Vertex settings that outranked a vision or Gemini
credential the person set in the shell, so capture, snapshot describe and
media-use speech and music could send content to another account.
After the CLI and capture load a project .env, each provider key it set is
unset when that .env came with a received project (a received-files record
lists it, or a record cannot be read) and the person has their own
credential for a competing provider. One stderr line names the key, the
.env file and the credential used instead.
A person's own project .env keeps its keys and its current precedence, so
an OPENROUTER_API_KEY in a project .env still wins over a Gemini key in the
shell, as the docs describe. Voice needs no change: the person's HeyGen
credential already ranks above ElevenLabs.
* fix(cli,media-use): media-use scripts apply the received .env rule, ElevenLabs included
The media-use audio scripts read the project .env again, so a Gemini key the
CLI had left out came back. They now apply the same rule after loading: a
key from a received project's .env gives way to the person's own credential
for a competing provider. GEMINI_API_KEY and GOOGLE_API_KEY give way to the
person's Gemini key or service account. ELEVENLABS_API_KEY gives way to the
person's HeyGen sign-in, saved key or shell key. A dropped key gets one
stderr line that names the file and the credential used instead.
A received ElevenLabs key that is still used, because the person has no
competing credential, gets one stderr line naming the .env before speech
starts. hyperframes media-use tells the engine which keys it took from a
project .env (HYPERFRAMES_PROJECT_ENV_ORIGINS), so a key the CLI loaded is
not mistaken for the shell's.
When the project's folders are too many to scan for received-files
records, the CLI's note now says the project's origin could not be
checked, instead of calling it a received project.
* refactor(studio): check the shape of the CLI's outside-files rule before calling it
The Vite adapter loads outsideAssetsAllowed from the CLI source at run time.
It now checks that the export is a function and treats only a true result
as allowed, instead of casting the module's export.
* docs(auth): a received project's ElevenLabs key gives way to your HeyGen credential
* test(studio): load the received-project rule before render waits start
* fix(producer): trusted renders refuse outside-linked compositions unless --include-outside-files
A sub-composition or entry file whose real file is outside the project is
inlined into the render page, so its scripts run even though outside .js files
are left out without the flag. The pre-flight now refuses it with a message
naming --include-outside-files.
— Rames
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(cli): read the linked outside scene with --include-outside-files in the received-render parity test
The parity test checks that the render compiler reaches an outside file through a
scene in a linked folder outside the project. Trusted renders now refuse that scene
unless --include-outside-files is passed, so the helper passes it.
— Rames
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cli): render --docker applies the received-files rule decided on the host
The container mounts only the project, so it cannot see a received-files record
in a folder above it. The host now makes that check for single and batch Docker
renders and passes --refuse-outside-files into the container when it refuses
outside files.
* fix(cli): a Docker batch decides the received-files rule once
A batch render now applies the received-files rule once and hands the result to
every row, so it warns once instead of once per row. A test now drives renderDocker
itself and checks the docker run arguments it starts.
* fix(cli): files from outside the project are uploaded only once approved
publish, cloud render and feedback --file-issue copied every image, video, audio,
font and CSS file a composition named from outside the project folder, and every
project file that links outside it, and only listed them. A project that came from
someone else could pull a file from anywhere on the uploader's disk into an upload.
Now each such file needs approval. In a terminal the command lists them and asks,
defaulting to no; a yes is remembered per project in the CLI's config folder
(~/.hyperframes/outside-files.json), never in the project. --yes, --json, --dry-run
and unattended runs leave them out with a warning naming each file and saying how
to include it. --include-outside-files uploads them without asking.
— Rames
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(cli): check the approvals file mode only where files have POSIX modes
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cli): compare and keyframes --shot serve only the files a bare HTML file names
A bare .html file given to compare or keyframes --shot is staged with
only the files its markup, stylesheets and sub-compositions name inside
its own folder, and only types a composition loads. Private files stay
out. A scene its project's index.html mounts is staged from the
project, so it keeps its shell.
* fix(cli): stage root-relative names, string imports, SVG links and grading tables
A bare HTML file's staging now also copies the files named by a
leading-slash URL (resolved against the staged folder), a string-form
CSS @import, an SVG xlink:href and the LUT of data-color-grading.
compare and keyframes --shot print one line naming any file they left
out. The CLI docs describe the single-file rule.
A local render brought in .js and .mjs files that markup or a project link
reached outside the project, so an imported composition could copy a script
from elsewhere on disk into the page it runs and read it. Images, video,
audio, fonts and CSS still come in. Scripts are left out with a warning that
names each one and how to include it: move it into the project, or pass the
new --include-outside-files to hyperframes render.
The policy covers the compiler's outside-asset copy, the file server's
linked files and the distributed plan's project copy.
— Rames
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* test(cli): error boxes and diff's failure line print control characters as escapes
* fix(cli): error boxes and command failure lines print control characters as visible escapes
* style(cli): format the escaped error lines
* fix(cli): cache installs only use folders the current user owns
Code the CLI downloads or builds into its cache (Chrome, the TTS script,
audio helpers, whisper.cpp, OpenCV, the Lambda handler, optional packages)
now goes into folders created by the current user with owner-only write,
and each installed file is checked again before it is returned.
- A cache root that other accounts can add entries to, sticky or not, is
no longer used for code; the per-user cache is used instead.
- The ownership check reads links rather than following them, and a link
that leads out of the cache root is not trusted.
* fix(cli): validate cache ancestry before filesystem side effects
* fix(core): check links before parent path segments
* fix(cli): validate cached libraries and clarify private parent requirements
* fix(cli): use the shared staging directory helper for Apple builds
* fix: hidden and credential files stay out of Studio, history and lint
- The private-file rule now refuses every hidden file or folder in a project,
except Studio's own files, the root .media folder, and pictures, video,
sound, fonts, stylesheets and scripts a page can load. It also refuses
Terraform state and variable files and more key-store types.
- Project history never tracks, lists or serves a private file, and the blob
route serves only bytes a listed file had, so copies kept by an older
version are no longer readable.
- Lint reads a linked stylesheet, script, import map or sub-composition only
when the private-file rule allows it and the file is the kind its link
names, so no finding quotes a private file.
- The rule moves to @hyperframes/parsers/private-path so lint can use it;
@hyperframes/core/safe-path re-exports it unchanged.
* fix(studio-server): a refused history blob reads as not a history blob
* fix(core): keep realpath in core, so its file-system callers and tests see one module
* fix(cli): text from projects, pages and registries prints control characters as visible escapes
catch-up, capture, figma component, timeline, keyframes, layout/inspect,
catalog and add printed strings that come from a project folder, a captured
web page or a registry manifest straight to the terminal. A crafted value
could move the cursor, rewrite earlier lines, set the window title or write
the clipboard. Those values now go through terminalText(), the same helper
lint, check and snapshot already use. The CLI's own colours stay, and --json
output is unchanged.
layout/inspect also keeps only well-formed issues with a known code from the
page, the way check already does, by reusing check's parseLayoutIssue. The
browser-script loader moves to its own module so layout and check can share
the parser without importing each other.
* test(cli): catch-up test names files with control characters only where the OS allows it
* fix(cli): import terminalText from core after main moved it
* fix(cli): escape layout banner and failure, top-level errors and installed paths; keep line breaks
* fix(lint): run Studio and producer lint off the host's own thread
A composition that sends the linter's parser into a runaway froze or
crashed the long-lived hosts that lint it in their own process.
CLI Studio's single-page lint now runs in a child process with a heap
cap and a 15 s limit. Producer /lint (runHyperframeLint) runs on a
worker thread with the same limits. A page that times out, runs out of
memory, or whose child or thread ends without an answer gets one
lint_aborted error finding and is never linted in the host process.
Studio's project lint keeps its timeout and gains a heap cap.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* fix(producer): cap concurrent /lint workers at two
Each lint worker can hold up to 512 MB, so parallel /lint requests
multiplied that without bound. At most two run at once; the rest wait
in order, and a request still waiting when its own 15 s runs out gets
the lint_aborted result.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
* fix(cli): render --json gives each missing tool, a held slot and an old Node its own code
Every failed `render --json` answered with `error.code: "runtime_error"`, so a
script could only tell a missing FFmpeg from a busy render slot by matching the
human message. A CliRuntimeError now carries a code, as CliUsageError does, and
the envelope reports it: chrome_not_found, ffmpeg_not_found, ffprobe_not_found,
render_locked. A Node older than 22 prints the envelope too
(node_version_unsupported) when the run asked for --json. Other failures keep
runtime_error.
Refs #7408
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
* test(cli): give the bin entry test's runtimeVersion stub the new JSON export
bin/hyperframes.mjs now imports runtimeVersionJson, so the stub dist file
binEntry.test.ts writes must export it too, or the bin fails to load.
---------
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
* fix(cli): own render-slot lock dir; refuse cache files other accounts can write
Sharing one render slot across accounts no longer means sharing HYPERFRAMES_CACHE_DIR,
which holds the browser, packages and helpers each account runs.
HYPERFRAMES_RENDER_LOCK_DIR names a folder of lock records only, created sticky and
writable by all (1777); the per-user lock folder is created 0700. Help text, errors and
docs no longer suggest sharing the cache or chmod 777.
foreignWritablePath (core/cache-dir) refuses a cached file whose path up to the cache
root is owned by another account or is group/world-writable. Chrome (CLI, engine,
inspector), optional packages (incl. the Sherpa runtime), the whisper.cpp build, the TTS
script, the Apple audio helpers, opencv.js and the Lambda handler reinstall or rebuild
instead of running such a file, and trustedCacheRoot moves their installs to
~/.cache/hyperframes when another account can write HYPERFRAMES_CACHE_DIR.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cli): seal own cache installs against umask 002 and repair old lock folder modes
sealCacheInstall (core/cache-dir) takes group and world write off what this account just
installed and the folders above it up to the cache root, so an install made under umask
002 passes foreignWritablePath on the next run instead of being refused and fetched again.
Chrome, optional packages, the whisper.cpp build, opencv.js, the TTS script, the Apple
audio helpers and the Lambda handler call it after installing.
ensureLockDir makes an existing per-user lock folder 0700 again when an older release left
it open, and adds the sticky bit to an existing HYPERFRAMES_RENDER_LOCK_DIR folder, warning
once with the folder's name when it cannot.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* refactor(cli): drop added comments to pass the comment ratchet
The explanations move into names: the mode bits in core/cache-dir are GROUP_OR_WORLD_WRITE
and WITHOUT_GROUP_OR_WORLD_WRITE, and the owner check is anotherAccountCanWrite. No change
in behaviour.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cli): verify the lock folder through a no-follow handle and stage installs owner-only
The render lock folder is opened with O_NOFOLLOW | O_DIRECTORY and checked and chmod-ed
through that descriptor: a link, or a folder another account owns (root may own a shared
one), is refused with RenderLockFolderRefused instead of being made world-writable or
used as is.
Chrome staging, the optional-package staging folder, the whisper.cpp build folder and the
opencv, TTS, Apple helper and Lambda handler folders are created 0700, and Chrome's staged
tree is sealed before it leaves staging, so nothing is group-writable while it installs.
foreignWritablePath accepts a sticky folder owned by this account or root, as /tmp is, and
tolerates a statSync without options; tests whose cache sat directly in /tmp, and tests
that mock statSync, failed on both. Docs note that a record naming a live process of
another account holds the shared slot.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(cli): skip the uid-based Chrome cache refusal cases where there is no uid
Windows has no process.getuid, so the ownership check never runs there and the two cases
that expect a refusal cannot hold.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* chore(core): raise the unpacked size budget for the cache ownership checks
core grew to 4418013 bytes unpacked with foreignWritablePath, sealCacheInstall
and trustedCacheRoot; the budget follows the usual 5% headroom over that size.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cli): never write project records through symlinks under .hyperframes
The committed team descriptor (.hyperframes/project.json) and the HeyGen job
log (.hyperframes/heygen-jobs.jsonl) were written with path-based mkdir/write/
append calls that follow links, so a cloned project could point either file,
or .hyperframes itself, at a file outside the project and have publish or a
paid HeyGen job overwrite or append to it.
- projectRecords: add appendRecord (O_NOFOLLOW open, same plain file checked
by fstat/lstat, real folders from .hyperframes) and recordKind.
- writeTeamProject goes through writeRecord (exclusive temp + rename), so a
link at project.json is replaced, never written through, and a linked
.hyperframes is refused.
- readTeamProject refuses a linked or non-plain descriptor (or a linked
.hyperframes) instead of reading it as absent, which stops publish before it
would write one.
- The job log and project voice picks go through appendRecord and fail with
a Fix when refused.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cli): route every remaining .hyperframes write through link-refusing helpers
Writers that still made or wrote into a project's .hyperframes with
path-based mkdir/write calls now refuse a linked or non-folder .hyperframes
and never write through a link:
- project lock: folder via recordFolder (the exclusive lock create stays)
- lambda stack state: writeRecord
- received-files record: recordFolder + writeRecord, so a link to another
project file is replaced instead of overwritten
- check reports: folder via recordFolder (the wx create stays)
- check and snapshot frame folders: new projectFolder, which holds a folder
inside .hyperframes to recordFolder and makes one elsewhere as asked
- template pull staging: recordFolder
- share render record: writeRecord
- studio server state folder: recordFolder
- share storage: the atomic JSON temp file is opened with wx
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* chore(cli): drop doc comments the comment ratchet counts
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cli): refuse to append to a project record with more than one hard link
A hard link at .hyperframes/heygen-jobs.jsonl names an outside file as a
plain file, so the O_NOFOLLOW open and the same-file check let the job log
append to it. The append now refuses a file whose link count is above one.
Whole-file record writes go through a temp file renamed into place, which
replaces the name rather than writing to a linked inode.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cli): check and info --media leave remote media sources unprobed
mediaPath handed an http(s) src to ffprobe, so check's HDR and sound
probes and info --media's clip lengths opened composition URLs from the
CLI process. Remote sources are now left unprobed, as timeline and
check's clip audit already do. check's report lists the remote video
and image sources HDR inspection skipped under hdr.remoteNotInspected,
and a remote video that may carry sound keeps the film from being
reported as silent.
* fix(cli): drop credentials from remoteNotInspected and document unprobed remote media
* fix(cli): open starts the desktop app in the home folder, not the folder it runs in
* style(cli): keep launchApp's note on one comment line
* fix(cli): open starts the desktop app without the project's .env values
* fix(engine,producer): render media readers treat private project files as missing
A video, audio, GIF or HEIC src that names a file the file servers refuse
(git metadata, env, credentials, tool state, app records), as written or
through a link, is now treated as missing by every render-time reader:
the compile-time duration probe and keyframe advisory, GIF and HEIC prep,
the media drop step, the HDR probe, frame extraction and the audio mixer.
The engine's isPrivateUnderAssetRoots judges a path from every asset root
that holds it, so a render's own work folder inside the project's
.hyperframes/ keeps its downloaded and prepared files.
* fix(engine): probe refuses a text file that ffmpeg reads as text-art video
ffmpeg's tty and bintext demuxers turn a text file (such as .asc or .nfo)
into a video stream that draws the text into frames. Every probe now
refuses an input whose container is tty or whose video codec is ansi,
bintext, xbin or idf, as not media. Probing, frame extraction and audio
reads all go through the same probe, on every render. No demuxer for real
video or audio produces these, so local renders keep every other format.
* fix(engine,producer,cli): playlist entries and check probes skip private files
- A media playlist (HLS segment, key or map URI, ffconcat file) that names a
private file inside its own folder is refused as not media, like one that
names a file outside it.
- `hyperframes check` no longer probes a media source outside the project or
private in it: mediaPath returns null for such a file and the audio,
heard-clip and HDR checks skip it.
- The compiler's duration probe and keyframe check judge privacy from every
asset root, as the render-time readers do.
* fix: warnings that name project files print control characters as visible escapes
The CLI already escaped control characters in the text its own commands
print, but warnings from core, producer and engine went to the terminal
raw. A composition whose sub-composition path held ESC or BEL still
drove the terminal through the bundler's "Skipping sub-composition"
warning in `info --media` and `snapshot`.
terminalText moves to core so there is one sanitiser, the CLI imports it
from there, and the library warnings that carry project text (the
bundler, the producer logger, the file server, render path skips, asset
load failures, FrameCapture, the import map, fonts, figma and atomic
file warnings) pass that text through it.
* fix: every library warning that carries project text escapes control characters
* fix(cli): the CLI trusts a preview only once it proves this user started it
* test(cli): a listener that cannot prove it is the user's preview is never trusted
* test(cli): stand-in previews answer the challenge as the user's own do
* style(cli): format the preview proof changes
* fix(cli): a preview's proof names its own endpoint and config, and the token file must be private
* style(cli): format the proof changes
* test(studio): the fake request in the host check has a socket, as every real one does
* fix(studio): a Studio started by hand proves it is the user's, so the CLI still finds it
* fix(cli): the challenge travels in a header, so Studio's routes keep their exact paths
* style(studio): keep the config producer compact
* fix(cli): fixed-name outputs and history turn records replace a link, never write through it
transcript.json, hyperframes.json patches, the grade-compare sheet, the batch manifest, diff and
measure outputs, lambda stack state and the history turn records are written through a temp file
renamed into place. A linked hyperframes.json is left alone, and the default .hyperframes/<tool>
output folder is used only when every folder on the way is real.
* fix(cli): measure and diff pictures and sbs.mp4 replace a link, never write through it
writeImage and the diff side-by-side now have ffmpeg write into a new private folder beside the
output, then rename the file over its name. measure frames already staged and renamed its PNGs.
* wip: partial security fix, paused before tests finished
* fix(cli): a received-files record in a folder under the project counts for a render
The received-files lookup now also walks the project's folders for records,
skipping tool and output folders and never following links. A nested
record's entries are received files named from the project folder, so a
received scene copied in with its own record makes the render leave out
outside files, as a record at or above the project does. A walk that cannot
list every folder fails closed.
* wip: paused before review
* test: cover credential files on the preview routes and the deploy notice
* refactor: name the inspector's file lookup for what it serves
* fix(cli): a link to a private file outside the project keeps its own left-out reason
* fix: escape the upload notice and skip private files from old manifests
* fix(cli): history turn ids from the project folder are checked and sent encoded
* test(cli): history turn fixtures use the id shape the CLI mints
* fix(cli): a turn's label and agent name are kept as written; only ids are checked
* style(cli): format the turn reader
* refactor(cli): the turn reader checks a marker through small predicates
* fix(studio): the preview reads hf-preview messages only from its own frame
The preview message router acted on a message with no sender window, and on
any message that arrived before the preview frame existed. It now takes an
hf-preview message only when the preview frame exists, the message comes from
that frame's window, and its origin is one the frame can have: the page's own
origin, or "null" for a sealed frame. The element picker checks the same.
* fix(cli): present sandboxes deck pages another site loads and refuses framing by other sites
present now applies the same another-site decision as play to its
/composition/* route: a load by another site gets a sandbox CSP, its
validators are dropped, and the document is marked so its runtime offers
that site no editing port. Every present response also sends
frame-ancestors 'self' and X-Frame-Options SAMEORIGIN, so only the
presenter page itself can frame the deck. The route setup moves into
buildPresentApp so tests exercise the server as run() builds it.
* fix(cli): catch-up lists only history lines appended after the hand-off
The seen record now marks the history file (its identity and length) at
the hand-off, and catch-up and the end-of-command notice read only whole
lines appended past that mark. Lines a project already carried are never
shown, whatever dates they claim. After the app trims the history, the
place is found again by the digest of the last line shown; a history the
app set aside and restarted is read from its start; a history replaced or
cut short shows nothing until the next hand-off marks it again. Records
written before the mark keep the dated filter once, then switch to it.
* fix(cli): catch-up notes the history's lines at hand-off instead of a file position
The hand-off now stores short digests of every whole line the history
holds, and catch-up and the notice show lines not among them nor shown
before, in file order. The person's turns keep showing after the app
trims the history or a sync rewrites it, and lines a project came with
never show. A hand-off over an older seen record always notes the
lines; such a record shows dated turns only when all are dated after it.
* fix(cli): catch-up shows nothing for another project now at the same path
The hand-off also notes the project folder's identity (device, inode and
birth time). When a different folder sits at the path, the seen record
counts as no hand-off: catch-up and the notice say nothing, and the next
hand-off notes that project's lines afresh.
* fix(cli): one trusted PATH rule for the engine and CLI; say why a project copy was skipped
The Windows PATH rules (quoted entries, the %SystemRoot% folders) now live in
the parsers' trustedPathDirs, so engine helper lookups and the CLI's PATH
rewrite apply the same rule.
When sam, aws, gcloud, docker, git or npx is not found but a copy sits in a
project folder the rule skipped, the message names that copy by its path
relative to the project and says why it was not used. cloudrun now reports a
missing gcloud or docker as not found instead of "exited with null".
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(cli): join a simulated Windows PATH with the Windows separator
The shared trusted-folder rule now splits PATH on ';' whenever the platform
is win32, as Windows does. Two tests that pretend to be Windows on Linux
built PATH with ':', so the rule saw one folder instead of two.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cli): name skipped copies above the working folder; pin Windows PATH to the shared rule
The not-found hint now names any copy the trusted PATH rule skipped,
relative to the working folder, including ../node_modules/.bin when an
npm or pnpm script runs from a subfolder. A Windows test pins that quoted
PATH entries still go through the shared rule, so the project root's and
ancestors' node_modules/.bin stay skipped.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* chore(cli): trim projectCopyHint comments to the package's comment share
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cli): cloud render sends one zip when it fits and uploads only the largest media
* fix(cli): cloud render leaves unused media out only when the zip is over the limit
* test(cli): eight-at-once upload test waits for eight in flight, never a timer
* test(cli): eight-at-once upload test also fails when more than eight run
* fix(cli): upload archives never include credential or agent-state files
Publish, cloud render and feedback stage the project through one path.
It now always leaves out package-manager and Git credentials (.npmrc,
.yarnrc, .pypirc, pip.conf, .netrc, .git-credentials, .gitconfig), key
files (id_rsa*, id_ed25519*, *.pem, *.key, *.p12, *.pfx), .ssh, .aws,
.gnupg, .docker, .kube, .azure, .config/gcloud and .config/gh, agent and
editor folders (.claude, .codex, .cursor, .agents, .gemini, .vscode,
.idea) and .mcp.json, at any depth and in any letter case. This holds
whatever .hyperframesignore says and whatever the HTML or CSS references.
A reference can bring back a file the ignore rules skipped only when it
is an image, video, audio, font, CSS or JS file, or when it is not in a
hidden folder. Every file left out this way is reported, and a file the
folder walk already reported is not reported again for each reference.
* fix(cli): anchor both alternatives of the key-file pattern
* fix(cli): a page's own scripts in a hidden folder still upload
* fix(cli): the static project server answers only loopback and marks pages another site loads
check, snapshot, validate, layout, compare, grade-compare and motion-shot serve the
project from a loopback server. It now refuses any Host other than loopback or its
in-process name before reading a file. A page or file that another site loads comes
back sandboxed, and its documents carry the another-site mark, so the runtime offers
that site no editing port. The capture browser's own loads are unchanged.
* fix(producer): the render file server answers only loopback and offers no editing port
The render file server now refuses any Host other than loopback before it opens a
file; the capture browser asks for localhost. Every HTML page it serves carries the
another-site mark, so its runtime answers no editing connect. A render never sends
one, so capture is unchanged.
* fix(engine): the exported file server answers only its own host and offers no editing port
createFileServer from @hyperframes/engine now refuses any Host other than loopback or
the hostname it was bound to (on a wildcard bind, this machine's own addresses too)
before it reads a file. Every HTML page it serves carries the another-site mark, so
its runtime answers no editing connect.
* fix(cli): never open another computer's share while staging an upload
publish and cloud render now leave out a reference to another computer's
network share or a Windows device path before any file-system call on it,
and report it as left out with the network_share reason. A page that came
in with an imported project has its outside references left out before the
files they name are checked.
* test(cli): the Windows staging test's lstat mock honours throwIfNoEntry