* fix(producer): give each parallel segmented-capture worker its own browser
Segmented capture with two or more workers failed at the first frame with
"Invalid JPEG input at frame 0: empty frame". Every worker opened its page in
one pooled Chrome, and beginFrame capture does not survive a shared browser:
a worker's first beginFrame returned no screenshot. Fresh worker sessions now
follow shouldDisableBrowserPoolForParallelWorker, the rule the parallel disk
path already uses.
The default session factory was also built once per worker, so with a probe
session every worker reused that same page. It is now built once per run, so
only the first worker takes the probe.
Workers are now created inside the try, so when a later worker fails to
launch, the finally still closes the browsers opened before it.
* fix(producer): close a segmented worker session whose initialization fails
The default segmented session factory opened a fresh browser and then
initialized it with nothing owning it on failure, so a page-load or init
timeout leaked that Chrome. It now closes the session and rethrows, as the
streaming stage does.
* ci(studio): gate Studio open and timeline scroll on work counts that only go down
Beside the timeline viewport gate's ms budgets, count the work two Studio journeys do and hold
each count under a checked-in ceiling in perf-ceilings.json: thumbnail renders, page loads and
requests for opening a 12-scene film, and React commits, style recalcs and layouts per scroll
tick. Counts repeat exactly run to run, so a rise names the work that grew.
* ci(studio): hold style recalcs per scroll tick at the CI runner's count
* ci(studio): gate the median scroll run and list which thumbnails rendered
* ci(studio): set work-count ceilings from the CI runner's counts on main
* ci(studio): fail the open count loudly when Studio never starts
* ci(studio): fail a work-count gate that measured nothing
* ci(studio): a scroll counter missing from any measured run reads as not measured
* ci(studio): split the perf ratchet's CLI and page counters into small steps, and let its unit test count
* ci(studio): count scroll work in an untimed pass and commit the open fixture's scenes
* ci(studio): gate only the open journey's counts; scroll counts follow runner speed
* ci(studio): fail a dropped journey and an unreadable base in the work-count ratchet
* ci(studio): split the ratchet's checks into small functions
* docs(cli): explain how catalog search works and which model it downloads
* docs(cli): name the model catalog search was chosen against
* docs(cli): keep only live rules in the word-search header comment
* docs(cli): correct the hosted vector size in the local vector build comment
* 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.
* fix(sdk): read a composition's variables from its root when its html has none
* fix: composition metadata and lint also read variables declared on the root
* fix(sdk): keep root declarations on the root through undo and prefer them like the runtime
* fix(sdk): read variables from both <html> and the root, editing each where declared
* feat(core): a composition's script can load its own files with __hyperframes.assetUrl
* test(core): a template composition inside a mounted file resolves assets from that file
* docs: assetUrl is for paths beside the composition, not project-root paths
* docs: say assetUrl misses a project-root path
* fix(core): a mounted composition's import map and module scripts run as such
* refactor(core): scope a mounted module script under the same condition as a classic one
* fix(core): a mounted module script loaded by src stays a module
* fix(core): a mounted import map keeps the trailing slash of a prefix address
* chore(core): keep the module-script helpers' comment share at the base
* fix(core): paint no timed clip until the runtime decides its visibility
Until its first visibility pass, a paused page showed every timed clip at once: an embed without
a loader flashed a later scene before the first, and a player's hidden iframe still decoded every
scene's images. The runtime now hides timed non-media clips from the moment its script runs,
and the first pass that decides them removes that rule, so each clip is shown only by the pass.
* refactor(core): name media with the realm-safe helper in the first-pass check
* fix(core): share the first-pass hide across runtime copies and shader captures
A second evaluation of the runtime (a sub-composition carrying its own runtime tag, or a page that
includes it twice) added a hide rule nothing removed, so the film stayed invisible. The rule and its
flag now live on the page: a copy that finds either, or finds the runtime already initialised, adds
none, and the first pass removes every copy. HyperShader's capture clone forces its scene visible
with !important, so a transition captured before the first pass still shows the scene's clips.
The runtime test now also pins evaluation-time hiding, inline visibility, media, and two copies.
* fix(core): grade media inside a clip once the first pass shows it
Color grading registers only media it can see. Media with no timing of its own inside a timed clip
inherited the first-pass hide, so grading skipped it, and lifting the rule is not a body mutation,
so nothing registered it again: the image or video stayed ungraded. The pass now refreshes grading
when it lifts the rule. The second-copy test now asserts on a paused page, before any seek.
* chore(core): keep the comment share of the first-pass hide files at or under their base
The comment ratchet counts one added comment line each in entry.ts, init.ts and capture.ts, and a
new file above its package's share. The three lines are gone, and the one note that has to stay
(why the hide runs at script evaluation) now lives in the new module's shorter header.
* fix(studio): a playhead scrolled off to the left no longer draws over the track names
The playhead layer (z 100) drew over the sticky track headers when the timeline was scrolled past it. Once a scroll settles, its layer is clipped at the header edge, less the glow's half-width so 00:00 looks as before. The settle-time scroll subscription moves out of the ruler into useSettledScrollLeft, now shared by both.
* test(studio): find the timeline playhead through its layer, not its z-index
* feat(core): a composition's script can load its own files with __hyperframes.assetUrl
* test(core): a template composition inside a mounted file resolves assets from that file
* docs: assetUrl is for paths beside the composition, not project-root paths
* docs: say assetUrl misses a project-root path
* 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
Deleting a sub-composition clip left it drawn on the timeline indefinitely. The preview still held the removed host until its reload landed, composition enrichment re-read it from there and put it back, and the merge then kept it on every shorter scan. The delete now takes its clips out of the live preview at once, and updates the timeline right after its write instead of after the ripple finishes saving; a ripple that fails to save puts the gap back.
The catalog already loads every item's manifest, preview included, but the
--json rows dropped it, so an app listing the catalog had no way to show an
item before add downloads it. Rows now carry preview when the item has one.
An edit that reloads the preview used to stop playback: the reload saved the
time, paused the live frame and marked the player paused, and the promoted
document started paused. Now forward playback runs on in the live frame while
the new document loads. At promotion the new document takes the live frame's
time, so playback, a stop at the end or a seek made during the load carries
over, and it keeps playing if the live frame was, unless the edit cut the film short of that time. A paused film, a reverse
shuttle and a dropped reload behave as before.
* fix(cli): the snippet hyperframes add prints for a block passes hyperframes check
* fix(cli): the block snippet carries the id the block's own root declares
* fix(cli): warn when an added block declares no composition id for its snippet
* fix(cli): add <tag> --json reports each block's warnings
* feat(studio-server): every write to a project is kept in a history that can be undone or restored
* fix(studio-server): rewrite a history removed while open and report damaged log lines
* fix(studio-server): history ignores foreign ids, ends idle windows and budgets only past history
* feat(cli): warn when canvas content touches the frame edge
* test(cli): pin which frame edge the canvas warning reads
* test(cli): type the canvas edge stub like the file's other getContext stubs
Rebased onto main again now that #4413 has landed. No behaviour change.
`composition.ts` applied cleanly for the second time — the negative-z rule sits
at a different insertion point from both the zoom rule and the viewport-cap
rule. The collision is the test file only: all three describe blocks append at
the same position in the outer describe. Purely additive, so the resolution
keeps all three and edits none.
Verified against 9af8ec21, the head under review, diffed against ITS OWN parent
rather than the branch's original base:
79 lines this PR added to composition.ts -> 0 absent after the rebase
81 lines this PR added to composition.test.ts -> 0 absent after the rebase
every non-blank line of main -> 0 absent after the rebase
Both files parse with zero syntax errors and are oxfmt-clean.
The message under review is untouched: the mechanism stated as fact, the hiding
conditional on an opaque root background, and the transparent-root case named
explicitly.
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Rebased onto main now that #4412 has landed. No behaviour change.
The conflict was an append collision in both files: #4412's zoom rule and this
viewport-cap rule are appended at the same position in `compositionRules`, and
their test blocks at the same position in the outer describe. Both were purely
additive, so the resolution keeps both and changes neither.
Verified rather than asserted, against the approved head 75f9c993:
38 lines this PR added to composition.ts -> 0 absent after the rebase
35 lines this PR added to composition.test.ts -> 0 absent after the rebase
every non-blank line of main -> 0 absent after the rebase
So nothing of either side was dropped and nothing was edited; the rules only
moved. Both files parse with zero syntax errors and are oxfmt-clean.
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* feat(lint): flag a canvas-level CSS zoom that rescales a fixed frame
The capture frame is sized from the root's data-width/data-height, which are
layout pixels. CSS `zoom` on the canvas itself -- the composition root, or
html/body above it -- rescales the painted content inside that frame without
changing the frame, so the two disagree.
Measured at 0.8.71 on an 800x400 composition holding two 100x100 boxes at
left:100 and left:600, rendered to a PNG sequence with the boxes located by
colour:
root zoom:0.5 canvas stays 800x400; boxes paint at (50,25) and (300,25)
at 50x50 -- the composition occupies the top-left quarter
and the rest of every frame is dead space.
root zoom:2 canvas stays 800x400; the left:100 box paints at (200,100)
at 200x200, and the left:600 box renders ZERO PIXELS. It is
inside the declared composition and absent from the output,
and nothing in lint, check or the render log says so.
A `zoom` on a DESCENDANT is deliberately not flagged. Measured in the same
run: a child at left:100 with zoom:2 paints at (200,100) at 200x200, which is
exactly what CSS `zoom` specifies. It is honoured, not ignored, so flagging
every `zoom` would be flagging correct authoring.
The `(?<![\w-])` lookbehind on the declaration pattern is load-bearing:
`--zoom: 2` and `--panel-zoom: 0.5` are author variables, and a plain \b
boundary flags both.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* style(lint): format to the repo's 100-column width
`oxfmt --check` is a CI gate and these lines exceeded the repo's 100-column
printWidth. Formatting only: verified whitespace- and trailing-comma-identical
to the previous revision, with the comparison shown to detect a real change.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(lint): satisfy noUncheckedIndexedAccess in the zoom rule
Two strictness failures under the package's `noUncheckedIndexedAccess` +
`strict`, both mine, both breaking `@hyperframes/core`'s build (and every job
downstream of it):
- `hits[0]` is `T | undefined`, and a preceding `hits.length === 0` check does
not narrow it. Guard on the element instead of the length.
- The local `hits` type declared `snippet: string`, stricter than
`truncateSnippet`, which returns `string | undefined` — it returns undefined
for an empty normalised input, and `Finding.snippet` is optional for exactly
that reason. Mirrored that contract rather than coercing with `?? ""`, so an
absent snippet stays absent instead of becoming "".
Reproduced both in isolation against the real signatures before fixing, and
confirmed each mutation reproduces the original error verbatim.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* refactor(lint): split canvas-zoom collection by source
The `Fallow audit` gate flagged the rule's callback as critical:
`fallow/high-crap-score`, CRAP 116.3 against a threshold of 30, cyclomatic 21.
That is a fair reading — the callback collected hits from two unrelated sources
and then built the finding, all inline.
Split the collection into named functions by SOURCE (`inlineCanvasZoomHits`,
`stylesheetCanvasZoomHits`, composed by `canvasZoomHits`), leaving the callback
to resolve the first hit and word the finding. Decision points in the callback
go 21 -> 7.
Behaviour-preserving, and measured rather than asserted: both revisions were
executed against 16 inputs covering inline/<html>/<body>, stylesheet selectors,
comma lists, at-rules, comments, `!important`, class-matched roots, multiple
style blocks, and the inline-before-stylesheet precedence. Output is identical
on all 16, and the comparison was shown to detect a difference by swapping the
concatenation order, which diverges on exactly the precedence case.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* refactor(lint): split the stylesheet zoom walk into selector, rule, walk
The first split took `Fallow audit` from critical (CRAP 116.3, cyclomatic 21) to
minor (37.1, cyclomatic 11) — right direction, still over the threshold of 30.
CRAP weights complexity against COVERAGE, and I cannot measure coverage on this
machine, so rather than tune to the margin this splits the stylesheet walk into
the three things it was doing: find the first canvas-targeting selector in a
comma list (`firstCanvasSelector`), turn one CSS rule into at most one hit
(`canvasZoomInRule`), and walk the rules. No function in the rule now exceeds 6
decision points, which clears the threshold at any plausible coverage rather
than at the measured one.
`firstCanvasSelector` returning the first match preserves the previous `break`
exactly: one hit per rule, not one per selector.
Behaviour re-verified against the ORIGINAL revision of this branch — identical
on all 16 inputs, with the comparison shown to detect a real difference by
dropping the `targetsCanvasRoot` guard, which diverges on two cases.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(engine): name the data-no-timeline opt-out in the timeline-timeout warning
When the sub-composition timeline wait times out, two things are emitted:
the stderr line inside pollSubCompositionTimelines, which names the pending
composition ids and the data-no-timeline opt-out, and the structured warning
on the session, which said only "Sub-composition timelines did not become
ready within 45000ms".
The structured one is what a programmatic caller reads: render re-prints it
in the completed_with_warnings summary and returns it in the result's
`warnings` array, so a CI consumer or an SDK caller sees the symptom with no
remedy attached. It also reads as a fault to diagnose, when the commonest
cause is a composition that legitimately has no GSAP timeline -- CSS
animations or rAF -- and is paying the full playerReadyTimeout on every
render because nobody told the author the wait is theirs to switch off.
The message now says the wait can be intentional, names data-no-timeline as
the opt-out, and keeps the async-setup case as the other branch. The pending
composition ids were already computed for the stderr line and thrown away;
an optional onPending callback carries them to the session so the structured
warning and its details can name them too, matching the script-failure
branch, which already names its failed sources. The stderr text is unchanged.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(engine): normalise the pending-id result instead of casting it
The enumerate step cast `page.evaluate`'s result with `as string[]`, which is a
claim the call site cannot enforce: `evaluate` is loosely typed, and anything
that returns a non-array turned the cast into a TypeError thrown on the very
path that exists to REPORT a problem. Normalise the result instead.
`pendingCompositionIds` was also never declared on `CaptureWarning.details`,
whose type is closed, so the engine build failed and every downstream package
failed with it.
Adds coverage for the poll's own `onPending` handoff, which the existing tests
in this PR could not see: they exercised `recordSubTimelineWarning` (the
message text) and never `pollSubCompositionTimelines` (where the throw was).
The non-array case is the one that discriminates this fix from the tempting
alternative of leaving the cast and adjusting the stubs.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
readEngineVersion resolved ../../package.json relative to import.meta.url.
That path is correct from packages/engine/src/utils/ in the repo and
overshoots the package root from <pkg>/dist/ in the published CLI, which
bundles the engine. The require threw MODULE_NOT_FOUND, a bare catch
swallowed it, and every render stamped the 0.0.0-dev fallback.
No single relative literal is correct in both layouts, so resolve by walking
up to our own package root instead of by a fixed depth.
The name check is the fix, not a refinement. A bare "first package.json
found while walking up" resolves to whatever sits above in a hoisted install
and returns a confident wrong version - the same class of defect as the
sentinel, and harder to notice because the answer looks plausible. Only a
package.json whose own name is hyperframes or @hyperframes/* may answer.
A test pins this: removing the name check fails that case and only that case.
Also replaces the sentinel. 0.0.0-dev parses as a version, compares against
one, and sorts below every release, so a total resolution failure was
indistinguishable from a dev build - which is why it shipped unnoticed. The
fallback is now "unresolved", deliberately not semver-shaped, and every
failure path warns with the reason. A failed lookup still never breaks a
render.
The old comment claimed the engine ships as raw TS and exports
./package.json. The published package has no exports field and bundles the
engine, so that premise does not hold where the code runs; it is replaced
with the two layouts and why they conflict.
Refs #4365
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
The visibility pass ran only on seek, pause, play and during playback, and at init for video
and img alone, so a paused page published __renderReady with every caption and composition host
visible until someone seeked. Readiness now runs that pass for non-media timed elements; media
keeps its init pass and seeks, which own color grading and audio scheduling.
* fix(studio): a ruler label that slides under the track header is covered once the scroll settles
The track-header corner of the ruler is sticky and opaque and tick labels scroll natively under it, so the ruler could rest on a fragment ('0:05', '0'). A single mask subscribes to the viewport scroll with useSyncExternalStore, finds the one label the header slices, and covers it when the scroll settles. Moving it live on every tick crossing cost 2-3x the viewport gate's budget on a large unvirtualized timeline, so mid-scroll a fragment can still show.
* fix(studio): the ruler mask never stays off after its scroll listener is swapped
Unsubscribing mid-scroll left scrollingRef true, so the mask stayed hidden until the next scroll. Reset it with the settle timer.
* fix(studio-server): preview keeps its base URL when a script mentions a <base> tag
* test(studio-server): pin the sub-composition preview's base check
* fix(studio-server): find a <base> with the HTML parser, not a regex
* fix(registry): glass-shard-title renders when mounted, and 4 skipped blocks install again
* fix(registry): glass-shard-title loads in Studio and ?play, and its docs payload fails loudly
* test(scripts): pin the glass payload's hdr guard for any quote style
* fix(player): a play() made while the composition loads still plays
The iframe's own load event reset the asset wait, and that reset also cleared the queued play,
so a play() between the first ready and load was dropped with no error. Play intent now leaves
the asset-wait reset: only pause, seek, disconnect and a new src or srcdoc clear it.
Also adds assets-loading-ui (player | none): none never shows the loading-assets card, while
the assets-loading attribute and the assetsready and painted events still fire.
* fix(player): switching the loading card off keeps a shader load on screen
* fix(player): the loading card and a shader load no longer hide each other
A clip's source length came from the first video, audio or image found inside
its element. For a composition that is media on the scene's own timeline, so a
scene holding a 1.8 s video could not be longer than 1.8 s: trimming its end by
a few pixels collapsed it to that length. A composition host no longer lends its
inner media to the clip; a plain wrapper around one video still does. An inline
composition still shows its inner video or image as its thumbnail.
* test(engine): hold the download attempt deadline so slow runners cannot trip it
urlDownloader tests passed a real 1s deadline that a slow Windows attempt outlasted.
The deadline timer is now held; the one test that needs it fires it by hand.
* fix(engine): name the underlying error when a download fails, without its URL
* test(engine): fire the stalled-body deadlines by hand instead of racing a real 20 ms timer
* fix(studio-server): serve projects whose names contain @ % # & or ?
Five routes cut the decoded project id out of Hono's c.req.path, which leaves %40 %25 %23 %26 %3F
encoded, so the cut missed and files, preview assets, sub-compositions, thumbnails and waveforms
404ed or 403ed for those names. One helper now takes the sub-path by segment from the raw URL.
* fix(studio-server): thumbnails and waveforms stay inside the project for any name
The thumbnail route built its preview URL from the raw project id and path, so # ? and % broke it,
and neither route checked that the decoded path stays inside the project. Thumbnails now use the
composition guard and an encoded URL; waveforms use the read-only asset guard.
* fix(cli): play and present serve assets whose names contain @ % # & or ?
Both /composition/* routes cut a prefix out of Hono's c.req.path with no decode. They now share
studio-server's requestSubPath (renamed from projectSubPath and generalised to any route) with the
five studio-server routes, so one helper owns how a request path becomes a file path.
* fix(studio-server): a thumbnail request for the project folder answers 404
An empty thumbnail path resolved to the project directory and crashed reading it (500).
* fix(studio-server): read the thumbnail's composition with one open
Checking the path with stat and then reading it let the file change in between (CodeQL
js/file-system-race). One open now serves the type check, the mtime and the read; a missing file
still thumbnails from the preview as before, anything that is not a file answers 404.
A shadow reload that was not ready within one 15 s budget was discarded for
good: the stage kept the previous document, the edit never showed, and nothing
retried. On a busy machine that dropped deletes, trims and agent writes. The
shadow now keeps loading for up to three budgets before it is dropped, so a
slow load still lands and a load that never becomes ready still fails.
* fix(cli): stop check --at failing still frames as a frozen timeline
* fix(cli): warn when the running CLI is older than the project's pin
* fix(cli): keep judging spread samples when check --at is combined with other gates
* feat(studio): an embedder can change what the shortcuts panel lists
The panel read a private list, so an app that embeds PlayerControls could not drop a key Studio binds but it does not (bare S split). The list is now exported as DEFAULT_SHORTCUT_SECTIONS, PlayerControls takes shortcutSections, and the dispatcher names its bare F, S and R keys from the same module. Defaults unchanged.
* fix(studio): an embedder's shortcuts list may repeat a key or a section title
Rows were keyed by their key text and sections by title, so a relabelled list with a repeat hit React duplicate keys. The list is static, so rows and sections are keyed by position.
* fix(producer): report render progress from the first frame, at most four times a second
Capture loops reported every 30th (or 10th) frame, or every single frame, so a render sat silent through browser warm-up and the first 30 frames, then flooded on the sequential paths. One helper now owns the cadence for every capture stage: first frame, last frame, and every 250 ms in between. Browser GPU check, capture calibration and worker start-up each report their own step.
* fix(producer): always report the first captured frame and keep one telemetry code for browser start-up
The centre-anchor step ran on every scale change, including a window resize and a zoom set by a host, and from scroll 0 it always moved the view right, hiding 00:00 under the track header. A view at the start now stays there; a scrolled view still keeps its centre time.
NLEPreview always drew its picture 8px in from each side on a dark band, so an embedder that sizes the box to the film saw a smaller picture in a black frame. fillBox drops that inset from both the layout and the stage-size math. Default look is unchanged.
* fix(core): frame captures wait for a seeking video to land its frame
A paused seek set video.currentTime and returned; the seek-completion barrier resolved while the
video was still seeking, so a capture right after the first seek on a fresh preview painted the
previous frame. The media sync now joins each seeking video to that barrier until seeked, error,
emptied or abort.
* style(core): format the seek barrier test
* fix(core): a section whose root sets pointer-events:none stays pickable
* fix(core): the picker enables one sheet per hit test instead of mutating the DOM
* fix(core): the picker override lives in an adopted sheet, never in the saved document
* fix(core): the picker override wins over an author !important on a section root
* docs(core): name the picker override ceiling and why the fallback stays unlayered
* fix(core): a click-through overlay host keeps passing picks through
The override now targets section inner roots only, so a host the parent author set to pointer-events:none stays pass-through. Inner roots that were none before the override are never pick targets themselves, an inner root gets a unique selector instead of its bare tag, and a page with no pass-through root skips the override and its restyle.
* fix(core): picks reach content under a composition's own pointer-events:none root
* feat(runtime): data-vfx-chain backdrop capture and ref second sources
Interface v1.1's two remaining capture shapes, in the runtime.
`backdrop`: a host resolves its source from a sibling
`<canvas layoutsubtree class="hf-vfx-src" data-vfx-for="<host id>">`
before its own child wrapper, so the same kernel reads either its own
pixels or every layer below it — which element the wrapper holds is the
exporter's placement, not a def's declaration. `VfxEntry.capture` now
reports what was resolved rather than what the defs asked for.
The trap that shape creates: a `backdrop` wrapper lives OUTSIDE the host,
and children of a `layoutsubtree` canvas are never painted by the page
compositor. Skipping a hidden host the way a `self` host is skipped would
therefore delete every layer below the adjustment instead of passing it
through. A hidden backdrop host now still captures and KEEPS the bitmap,
painting no kernel.
`ref` params: a node's second source, captured into `u_src2` from the
wrapper the exporter emitted around the referenced element. Per node, not
per entry, and shared when two nodes name the same element. Every source
is drawn at the host's device size so `u_src`/`u_src2`/`.hf-vfx-out`
share one coordinate space, and each source's canvas gets its own
`paint` wait — paint records are per canvas. A source the clip runtime
has hidden captures EMPTY rather than waiting out a paint that cannot
come and then throwing "No cached paint record" every frame; an empty
matte is also what After Effects shows outside a matte layer's window.
Also: a `.hf-vfx-in` that measures 0×0 is now reported once instead of
capturing nothing in silence, and one that is not the canvas's immediate
child is refused at registration instead of throwing every frame. Both
are measured Chrome rules (vault `layoutsubtree-capture-rules`).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* feat(runtime): luma-matte and noise two-source vfx kernels
`luma-matte` is the first def with a `ref` param: `out = src · coverage(u_src2)`
with Alpha / Alpha Inverted / Luma / Luma Inverted coverage. It is not one
After Effects effect but the runtime form of all of them — unsupported
track-matte sources, stencils, silhouettes, Set Matte — which the exporter
distinguishes by choosing what the host wraps and what `matte` names. `src`
is premultiplied, so one scalar multiply covers all four channels, and Luma
reads the matte over black, which is what a premultiplied texel already holds.
`noise` ports `ADBE Noise` from `AEFX_Noise.metallib`: Bob Jenkins' 1997
integer mix over `(x, y, seed32)`, the two glibc-style LCG rounds, and the
`0x7F80`/`0xFF` byte the IR XORs out of them — no table, no state, so it is
seek-safe by construction. Reading the metallib's struct metadata rather
than the deep dive's prose settles two of its open questions:
`ADBE Noise-0002` is `inUseColorNoise` (a checkbox), not a Uniform/Gaussian
popup, and the mystery seed floats are `inRandomSeed_High`/`_Low`, the two
halves of one 32-bit seed. What the CPU puts in those halves per frame is
still unprobed (plan Task 4.3), so the kernel seeds the low half with the
frame index; the tests assert distribution and seek determinism, not parity.
The shader declares `precision highp int` — the whole port rests on 32-bit
wraparound and a fragment shader's integers default to mediump, which ESSL
guarantees only 16 bits of.
Both defs declare `capture: "self"`, which says a texture is needed and
nothing about whose: `noise` on an adjustment layer is the same kernel, and
the runtime reads the `backdrop` placement off the DOM.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* test(vfx): browser checks for backdrop capture, luma-matte and noise
Task 2.6 Step 5 and Task 2.7's owed browser checks, folded into the
existing puppeteer harness: an identity backdrop kernel composites two
stacked blocks captured through a data-vfx-for sibling wrapper back
over themselves (PSNR >= 40dB vs a plain-DOM control panel); a backdrop
host outside its own clip window still keeps those blocks on the
wrapper canvas's own bitmap via capturePassThrough; luma-matte's four
modes are checked against alpha- and luma-varying matte strips at four
sample points each; noise is checked for amount=0 identity, same-time
determinism, and a changed pattern when its only seed (seek time)
changes.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(runtime): external displacement maps and visible ref sources
Two gaps the exporter side found in the `ref` plumbing.
1. `displacement-map` had no `map` ref param, so the exporter's
`params.map = "<element id>"` was dropped by `normalizeVfxParams` (it
iterates the def) and the node silently self-displaced. `map` is now a
ref param, bound to `u_src2` and selected by a new `u_hasSrc2` uniform
the runtime sets from whether the ref resolved. Refs gain
`optional: true` — empty `map` is the self-referential form every
corpus instance uses, while an empty `matte` stays a loud failure — and
a ref naming its own host resolves to self rather than capturing the
same pixels twice (on a backdrop host it would otherwise have read the
layers below as the map).
2. Interface v1.1 assumed a ref source is invisible in After Effects.
retro-wave `Logo Anim` layer 5 is layer 4's displacement map AND an
enabled, opaque layer, and the runtime cleared its wrapper's bitmap
after the upload, deleting it from the frame. A wrapper marked
`data-vfx-ref-visible` now keeps its bitmap and is captured at the
REF's own box instead of the host's, so it paints at its own size and
resolution. The three capture shapes are one `{ upload, keepBitmap }`
mode: texture only, bitmap only (a backdrop pass-through), or both.
Sampling is unaffected by the box choice, and the browser test proves it
rather than assuming it: `drawElementImage` scales the element into the
whole canvas, so a 320px-wide matte's four strips still land as four
40px bands in a 160px host. The v1 rule — a ref is scaled into the host's
box, not placed in composition space — is unchanged.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(runtime): capture a visible ref while its host is hidden; review nits
Addresses PR #4330 review feedback (jrusso1020, CHANGES_REQUESTED).
Blocking: both the engine-mode and preview-mode capture paths treated
"host not paintable" as binary — a backdrop entry got a pass-through
capture, everything else was skipped outright, including a ref source
that lives on a different, independently-visible element (e.g.
retro-wave's Logo Anim layer, which is simultaneously layer 4's
displacement map and its own fully opaque visible layer). Adds
visibleRefSources()/captureVisibleRefsOnly() and a unified
FrameCaptureMode discriminator so a visible ref still gets captured
even while its own host is hidden, on both paths.
Non-blocking, addressed:
- luma-matte's mandatory ref that names its own host now resolves to
an explicit RefResolution {kind:"self"} and binds u_src2 to unit 0,
instead of relying on an unbound sampler's implicit default.
displacement-map's optional self-ref is unaffected (still folds into
{kind:"none"}, using its existing u_hasSrc2 shader branch).
- noise shader now enforces rgb<=a (valid premultiplied alpha) after
adding noise, independent of u_clipping — documented why u_clipping
is currently a permanent no-op on this runtime's 8-bit render
targets.
- added a hash-pinning test for hfJenkinsMix; documented, with a
brute-force proof, which one of the reviewer's suggested mutations
is unobservable within this fixture's reachable seed range.
- fixed two misplaced doc comments.
fallow flagged resolveVfxCapture/resolveRefSource as newly over the
complexity threshold after this diff; extracted resolveEmptyRefParam()
and captureHiddenEntry() to bring both back under.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(runtime): capture a visible ref while a hidden BACKDROP host passes through
Re-review of #4330 at b6d51bd9: the visible-ref-while-hidden fix only
covered non-backdrop hosts. captureHiddenEntry returned
capturePassThrough(entry) for a backdrop and never reached
captureVisibleRefsOnly; frameCaptureMode picked "passThrough" before
considering refs and sourcesForFrame("passThrough") was [entry.src]
alone. An adjustment layer whose displacement map is itself a visible
layer still lost that layer outside the adjustment's window.
- captureHiddenEntry runs the pass-through AND the visible-ref capture,
OR-ing the results.
- sourcesForFrame("passThrough") is the backdrop wrapper plus any
visible refs, and capturePaintedHost's pass-through branch also calls
captureVisibleRefsOnly.
- Tests for the backdrop+visible-ref shape in both engine and preview
modes (the reviewer's probe).
Also closes the non-blocking display:none item: isPaintableHost(src.inner)
missed a ref whose OWNING element is display:none, since display does not
inherit — the preview path waited out the 2 s ceiling, then failed with a
misleading 0×0 report. New isPaintableSource walks inner's ancestors for
display:none (visibility inherits, so one read suffices there); used at
both source-side sites. checkVisibility()/offsetParent are absent or
always-null in the unit harness's DOM. Test added; verified it fails on
the old inner-only check.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(studio): ship component styles as their own stylesheet for embedders
Studio's component rules (timeline clips, loaders, range inputs, toasts and
the rest) lived only in the app sheet, so a page that embeds Studio's
components with theme.css got unstyled clips and dark-on-dark labels. They
move unchanged into components.css, exported as
@hyperframes/studio/components.css; studio.css keeps the app shell and
imports it, so Studio's compiled CSS has the same rules.
* test(studio): read moved component rules from components.css
* test(studio): catch class rules nested in the app sheet's layers and media blocks
* fix(studio-server): stop mislabeling two more read-route failure shapes
Follow-up to the stale-tree investigation this week — two more cases
where the read route answers with the wrong shape for what happened.
A path a listing (`walkDir`) can show but this route cannot serve, now
correctly reported:
- **Replaced by a directory.** `existsSync` passes, `readFileSync` throws
`EISDIR`, and Hono answers plain-text "Internal Server Error" — not
JSON, and not a reason. `statSync(...).isFile()` after the exists check
turns this into `404 { why: "not_a_file" }`, same shape as any other
missing-file 404 the client already handles.
- **A dangling symlink.** `isSafePath`'s `realpathSync` throws on a link
whose target does not exist, and (by design — see its comment) that
fails closed as unsafe, same as a real traversal attempt. Correct for
containment, wrong for the response: a broken link scans as an attack
when it is broken plumbing. Added `isDanglingSymlink`, checked only
after `resolveWithinProject` has already refused the path, so nothing
about what is permitted changes — only which `why` a refusal carries.
A symlink resolving to something real outside the project is still
`outside_project` 403, unchanged; pinned by test so this can't
regress into loosening containment.
Tests: dir-in-place → `not_a_file`; dangling symlink → `dangling_symlink`;
symlink-to-outside-project still → `outside_project` 403 (the guard the
new branch must not weaken). 102/102 in the touched suite, 247 green
across studio-server routes overall. oxlint, oxfmt, tsc clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(studio-server): stop dangling_symlink from leaking outside-project existence
Review on #4363: `isDanglingSymlink` ran on the *lexical* path even when
`resolveWithinProject` had already failed — so a path reached via `../` that
happened to be a dangling symlink out there, or a leaf reached through an
escaping directory symlink, came back `404 dangling_symlink` instead of `403
outside_project`. Worse: an in-project symlink pointing outside the project
got `404` if the outside target was missing and `403` if it existed — a
small oracle for "does this path outside the sandbox exist."
`isDanglingSymlinkInProject` now requires containment on both ends: the
link's own directory must resolve inside the project (`isSafePath(dir,
dirname(lexicalPath))`), and its target, read via `readlinkSync` and
resolved against the link's directory, must also resolve inside the project.
Only then does "target exists nowhere" get the new label — anything that
touches outside the project keeps the plain `outside_project` 403, with no
distinction based on what's actually out there.
4 new regression tests: a dangling symlink reached by `..` (403, not 404),
a dangling leaf behind an escaping directory symlink (403, not 404), and a
same-status check across a missing vs. existing outside target (both
`outside_project`, not one of each). files.pathSafety.test.ts 25/25,
files.test.ts 80/80, oxlint/oxfmt/tsc clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(studio-server): close a TOCTOU CodeQL flagged on the not_a_file check
CodeQL (js/file-system-race, high severity) on #4363: the new `not_a_file`
check stat'd `res.absPath` by path, then a separate `readFileSync` reopened
the same path — a directory-for-file swap between those two calls could
land a stale answer. Opens the file once instead and checks/reads through
that single descriptor (`fstatSync(fd)` then `readFileSync(fd)`), so the
check and the read are provably on the same inode; a swap after open can't
affect either. `openSync` on a directory still succeeds (POSIX allows
O_RDONLY there), so the `not_a_file` 404 still fires the same way; opening
a genuinely missing path still throws and hits the existing "optional" vs.
plain 404 branch unchanged.
105/105 in files.pathSafety.test.ts + files.test.ts, oxlint/oxfmt/tsc clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>