Commit Graph
595 Commits
Author SHA1 Message Date
Miguel Ángel a519927436 fix(studio): an escape cancels a preview marquee band and stops there (#4703)
* fix(studio): an escape cancels a preview marquee band and stops there

* fix(studio): name the band escape handler instead of commenting it

* test(studio): check the band is gone before the pointer is released
2026-09-28 22:24:32 +00:00
Miguel Ángel a0c72ad64a fix(studio): drilling in opens the composition's full project path (#4689)
* fix(studio): drilling in opens the composition's full project path

* fix(studio): keep the shared source-path helper as is and trim ./ only for the drill path

* fix(studio): a project folder named preview keeps its path
2026-09-28 21:04:10 +00:00
Miguel Ángel 303c8e922f perf(studio): swap an edited scene into the live preview instead of reloading (#4499)
* perf(studio): swap an edited scene into the live preview instead of reloading

On a preview reload, Studio fetches the rebuilt preview document and asks the preview to swap
in only the scenes that changed. When the preview cannot or will not swap (it predates the
swap, a full reload is already running, or the document changed outside its scenes), Studio
does the full shadow reload as before. A document from an older reload is never swapped in.

* fix(studio): re-sync selection and layers after a scene swap

A swap replaces scene DOM without a load event, so selection, manual
edits, the Layers panel and the edit callout kept pointing at the
replaced nodes. They now listen for either a load or a swap.

* fix(studio): drop a stale scene swap once the preview is replaced

A swap still pending when the preview reloaded or switched composition
could fall back to reloading the old one. Color grading and its compare
view are also re-sent after a swap.

* docs(studio): say exactly when the preview generation changes

* refactor(studio): cut scene swap comments to what names and types do not say

* fix(studio): fall back to a full reload when a scene swap download stalls

* fix(studio): give up on a scene swap that stalls at any step, not only the download

* fix(runtime): a scene swap refuses when an animation outside the scene moves its elements

* test(runtime): pin the scene swap volume re-probe, host CSS variables and diagnostics-free swap

* fix(runtime): a scene swap keeps a video its scene script animates instead of reloading it

* fix(runtime): a scene swap stops every animation the old scene script started

* fix(runtime): record scene script animations only on pages a scene swap can act on

* docs(core): reword the scene animation recording comment

* fix(runtime): watch media as the page parses only on pages a scene swap can act on

* perf(runtime): a scene swap checks for outside tweens in one pass over the film's tweens

* test(runtime): pin the single revert and the cleared animation record of a scene swap

* test(studio): pin that a playing film keeps playing through a scene swap

* fix(runtime): a scene swap rebuilds media when the edit changes the scene script

* fix(runtime): a scene swap undoes the sets a scene script made

* fix(runtime): a scene swap rechecks outside tweens and runs new scripts after every host

* test(runtime): pin that a tween started during the caption wait leaves the page untouched

* fix(runtime): a scene swap refuses when its script set a value on an element the swap keeps

* docs(core): say the scene recording drops a finished tween that the timeline would keep when paused

* fix(runtime): a scene swap refuses when two of its animations write to an element it keeps

* fix(runtime): a scene swap resets kept media and refuses animations outside the scene

* fix(runtime): a scene swap keeps a moved video in place and swaps tweens on plain objects

* chore(core): regenerate the inlined position-edits script for the kept-video move reapply

* fix(runtime): a scene swap checks the timeline registry as it is after the caption wait

* fix(runtime): a scene swap refuses when a scene changed during the wait or a revert re-registers

* fix(runtime): a scene swap stops every animation a revert chain registers and rechecks its hosts

* fix(runtime): a scene swap refuses a moved host or a cancelled swap and stops at a shortened end

* fix(studio): a scene swap that times out is cancelled before the reload starts

* fix(runtime): a scene swap refuses when a scene leaves its place or the film during the wait

* fix(studio): a newer edit cancels an older scene swap still waiting

* fix(runtime): a scene swap checks only its host's place, so a later body append does not refuse it

* fix(studio): a scene swap cancelled before it starts does not run

* fix(runtime): a scene swap refuses when the film's scene layout changed during the wait

* fix(runtime): a scene swap refuses when the order around a scene changed during the wait

* test(runtime): pin that a scene swap checks the film root order when every scene is wrapped

* fix(runtime): a scene swap gives kept media the mute, rate and loop a fresh load gives it

* fix(runtime): a scene swap rebuilds media a script wrote attributes on, keeping the rest

* fix(runtime): a scene swap keeps media carrying the runtime classes or reordered attributes

* fix(runtime): a scene swap resets a kept video's volume as a load does, not through the volume probe
2026-09-28 20:44:30 +00:00
Miguel Ángel a3b6eec97e fix(studio): timeline Fit fills the width with the film, and a host can hide keyframe controls (#4680)
* fix(studio): timeline Fit fills the width with the film, and a host can hide keyframe controls

* fix(studio): keyframe tests read the claimed K press, and the fit span stays private

* fix(studio): an edit that changes the film's length keeps the timeline scale, and Fit is an icon

* fix(studio): manual zoom keeps its scale whenever only the film's length changes

* fix(studio): drop the width check the kept scale never needed

* fix(studio): a composition switch refits, and the kept scale clamps against the new fit

* test(studio): a project reset refits the manual zoom
2026-09-28 20:03:33 +00:00
Miguel Ángel 73d26a5187 fix(studio): back to the master after a nested drill restores the master playhead (#4678)
* fix(studio): back to the master after a nested drill restores the master playhead

* fix(studio): every way back to the master restores its playhead, 0 included

* fix(studio): the timeline playhead follows the restored master time

The timeline canvas unmounts while a composition level loads and remounts
with its playhead drawn at 0. The playhead effect only re-ran on a time or
zoom change, so a level switch that kept the time left the needle at 0 while
the readout showed the real time. It now also re-runs when the canvas remounts.

Drilling in during playback saved the store time, which playback does not
update per frame; the save now reads the live playhead.
2026-09-28 19:47:55 +00:00
Miguel Ángel af7ff3b0a1 feat(studio): enter a sub-composition from the keyboard and host its navigation (#4672)
* feat(studio): enter a sub-composition from the keyboard and host its navigation

* fix(studio): drop a comment the element field already says
2026-09-28 17:19:03 +00:00
Miguel Ángel 42f6a3a27e fix(studio): unmounting mid-edit saves the typed words, as blur does (#4651)
* fix(studio): unmounting mid-edit saves the typed words, as blur does

* fix(studio): in-place text is not saved once the preview turns read-only
2026-09-28 16:16:02 +00:00
Miguel Ángel 7fae35f36e fix(studio): carve and duck follow each clip's trim and speed (#4661)
* fix(studio): read and write a clip's in-point the way playback does

* fix(studio): a group head trim keeps the minimum clip length off the grid

* fix(studio): a group head trim stops where a single-clip trim does and never goes below zero

* fix(studio): group members on the grid move together when a trim stops at its limit

* fix(studio): level-out measures and places its lift on the clip clock at any speed

* fix(studio): round level-out lane times and tighten the half-speed test

* fix(studio): carve and duck follow each clip's trim and speed

* fix(studio): carve ignores speech after the bed stops playing

* test(studio): carve ignores speech past a bed that ducks and has no duration

* fix(studio): carve cuts speech past the bed's end at every strength
2026-09-28 15:48:26 +00:00
Miguel Ángel d2f0bc7f34 perf(studio): a host's first screen can import Studio's UI and Player without the editor (#4650)
* perf(studio): light ui and player entries for a host's first screen

* perf(studio): the ui entry's logo no longer loads the studio header

* test(studio): refuse only packages studio itself depends on

* test(studio): the light entries also refuse the hf-ids parser
2026-09-28 15:15:00 +00:00
Miguel Ángel 2251e5fad0 feat(studio): export DOM editing for a host outside EditorShell (#4640)
* feat(studio): export DOM editing for a host outside EditorShell

* fix(studio): host hears only single-box clicks, and a handle release no longer eats the next one

* refactor(studio): cut the sibling z-order comment to one line
2026-09-28 15:14:32 +00:00
Miguel Ángel 5eec513281 fix(studio): the timeline takes m4v video and flac audio (#4649)
* fix(studio): the timeline takes m4v video and flac audio

* fix(studio-server): check and label flac uploads as audio
2026-09-28 08:49:57 +00:00
Miguel Ángel 4aa6b168fe feat(studio): a host app can reuse Studio's snapping and marquee selection in its own preview (#4635)
* feat(studio): export snapping, the marquee and picker describe for a host's own preview

* fix(studio): a host pick type must bring its own marquee resolver
2026-09-28 08:23:11 +00:00
Miguel Ángel ea494b4672 fix(studio): even out levels lifts the right part of a sped-up or slowed clip (#4636)
* fix(studio): read and write a clip's in-point the way playback does

* fix(studio): a group head trim keeps the minimum clip length off the grid

* fix(studio): a group head trim stops where a single-clip trim does and never goes below zero

* fix(studio): group members on the grid move together when a trim stops at its limit

* fix(studio): level-out measures and places its lift on the clip clock at any speed

* fix(studio): round level-out lane times and tighten the half-speed test
2026-09-28 06:09:11 +00:00
Miguel Ángel e1e2b16e21 perf(studio): a film with no manual edits skips the edit reapply on each seek (#4592)
* perf(studio): a film with no manual edits skips the edit reapply on each seek

The reapply runs after every timeline seek, so on every playback frame, and
ran six document queries plus the motion rebuild even when Studio had never
edited the film. One combined query now answers "any edits?" first.

* test(studio): the seek skip still clears a motion timeline after an undo

An undo removes a motion edit's marks while its timeline stays registered,
and the reapply is what kills it. A test now fails if the skip stops
treating that timeline as an edit. The moved comments are cut to three
lines and lose an all-caps word.

* perf(studio): the per-seek edit check no longer walks large films or adds a lookup with edits

The combined comma selector took Chrome off its lone-attribute fast path: about 150 us per
seek on a 1.5k-element film, against 6 us for the whole reapply on main. The check now uses
one selector per mark and caches its answer per document, rescanning only after a
MutationObserver sees a mark attribute or the tree change.

* test(studio): the seek edit cache sees inserted edits and ignores style writes

Covers the two observer settings the cache depends on: a node inserted with its edit mark
after a seek is reapplied on the next seek, and a style write between seeks causes no rescan.
2026-09-28 04:17:27 +00:00
Miguel Ángel 078c493448 perf: the preview loads and decodes only the images of scenes on screen or due next (#4578)
* perf(core): skip hidden clips' content so the browser stops decoding their images

Hidden timed clips get content-visibility:hidden while their inline visibility is hidden,
from script evaluation on. A clip due within the look-ahead (2 s by default) keeps its
content live, so its images load before it shows.

* perf(studio-server): load preview images lazily so hidden scenes fetch nothing

* fix(core): stop the readiness scan waiting on and decoding later scenes' images

* perf(studio-server): keep first-frame images eager so the preview opens as fast as before

Only images inside a clip with a numeric start after 0 go lazy; a start the route
cannot read stays eager.

* perf(core): keep clips that start at 0 laid out before the first pass so the first frame is on time

* perf(core): open the preview on time by hiding only lazy images before the first pass

GSAP reads the computed style of the elements it animates while timelines build. Inside a
content-skipped clip every read forces a style update, which cost about 65 ms at open on the
bench composition. Before the first pass the rule now takes only lazy images out of layout, so
hidden later scenes still do not load theirs; after it, the skip rule keeps their content skipped.

* fix(core): hold a paused jump on the previous picture until the next scene's images decode

* fix(studio): swap in a reloaded preview only after its restore seek has painted

* fix(core): apply a held paused jump after 1 s when an image never decodes

* fix(core): keep hidden-scene image skipping and held jumps to Studio's preview, never renders

* fix(studio): reapply manual edits once a held paused jump lands

* fix(studio): copy a clip without the preview's lazy-loading marks

* fix(studio-server): mark preview images lazy without re-encoding the document's entities

* fix(core): share one preview-mark constant between the runtime and the preview route

* fix(studio): reapply manual edits a second time only after a seek that was held

* refactor(core): share the hidden-ancestor walk between clip visibility and image holds

* fix(core): import the studio preview mark from its own subpath

* fix(studio-server): find preview images with the linear html scanner

* chore(core): drop two doc comments the scanner's names already carry

* fix(studio-server): serve the preview mark as its own meta, apart from the GSAP fallback script

* fix(studio-server): capture thumbnails and frames from the preview without lazy images or the mark

* fix(core): let the full readiness scan wait on every image except lazy ones off the first frame

* fix(studio-server): keep an authored loading attribute in any letter case on preview images

* fix(core): leave template content out of findStartTags so preview images match the DOM

* fix(studio): send Ask agent the live markup without the preview loading marks

* chore(core): drop the template note from findStartTags, its test carries it

* perf(studio-server): splice lazy attributes into the preview in one pass

* fix(studio): keep authored image loading on copy and Ask agent by marking preview-made lazy images

* test(studio-server): follow the capture preview URL back to its sub-composition for every project id

* refactor: name the upcoming-clip and GSAP fallback marks once

* fix(studio-server): keep capture builds out of the on-disk preview store
2026-09-28 04:03:36 +00:00
Miguel Ángel bc73c411f0 feat(studio): let a host app mount the timeline toolbar, undo buttons, meters and clipboard (#4629)
* feat(studio): let a host app mount the timeline toolbar, undo buttons, meters and clipboard

* test(studio): lock in history button rules and trim duplicate export tests
2026-09-28 03:37:32 +00:00
Miguel Ángel 2ebfcc04a3 fix(studio): read and write a clip's in-point the way playback does (#4624)
* fix(studio): read and write a clip's in-point the way playback does

* fix(studio): a group head trim keeps the minimum clip length off the grid

* fix(studio): a group head trim stops where a single-clip trim does and never goes below zero

* fix(studio): group members on the grid move together when a trim stops at its limit
2026-09-28 03:08:13 +00:00
Miguel Ángel d4801086c4 fix(studio): quick saves no longer refuse each other as outside changes (#4612)
* fix(studio): quick timeline saves no longer refuse each other as outside changes

* fix(studio): canvas edits and block writes wait their turn in the file queue

* fix(studio): animated clip moves and the last direct writes wait their turn in the file queue
2026-09-27 22:27:40 +00:00
Miguel Ángel d6e8542a38 perf(studio): the lint error badge pulses three times, then holds (#4594)
* perf(studio): the lint error badge stops pulsing after three beats

The badge pulsed forever, so a Studio with a lint error painted a frame on
every display refresh, idle or paused. It now pulses three times and holds.

* fix(studio): the lint badge counts findings, never files

The badge showed the manual result's finding count while its dialog was open
and the number of files with findings once it closed, while its screen-reader
label always said findings. The hook now owns one count, the findings in the
list the error pulse also reads, and the badge shows it in both states.

* fix(studio): the lint badge pulses again when its finding count changes

A CSS animation does not restart on a text change, so after its three
pulses a background lint that found more problems left the badge still.
The badge is keyed on its count, so a new count mounts a new element and
pulses three more times.

* refactor(studio): the lint badge names its pulse count, and App reads the hook as one object

The pulse count moves from a comment into a constant name, so the file's
comment share does not rise. App takes useLintModal as one object instead
of a nine-line destructure, which keeps App.tsx under 600 lines once
merged with main.
2026-09-27 15:06:46 +00:00
Miguel Ángel 3855623dd9 fix(studio): list and grade only real compositions, not generated preview files (#4590)
* fix(studio): list only real compositions under Variables, not generated preview files

* fix(studio): project color grading edits only real compositions, not generated preview files
2026-09-27 12:30:31 +00:00
Miguel Ángel e00baefb5c fix(studio): reload the preview only when a file it loaded changes (#4570)
* fix(studio): reload the preview only when a file it loaded changes

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

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

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

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

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

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

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

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

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

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

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

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

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

* fix(studio-server): record every link a preview read passes through, resolved as the system does
2026-09-27 10:05:53 +00:00
Miguel Ángel 1a53681de1 fix(studio): an automation lane edit is refused on a locked clip and reports how it saved (#4533)
* fix(studio): an automation lane edit is refused on a locked clip and reports how it saved

Lane drags, Delete and paste save through the timeline's gated clip or group
save instead of the property panel's commit, so the host's canEdit applies and
the commit resolves saved, refused or failed. A landed save refreshes the lane
store and the panel's selection, as the panel's commit did.

* fix(studio): a refused automation save puts the preview and the lane back

A save that does not land (recording, no id, a failed write) reverts the live
preview it was given, the lane drops a draft whose save came back refused or
failed, the no-id and no-project failures toast like the others, and the panel
refresh reads the current selection. The panel commit's unused coalesce option
goes, and the lane value reuses automationAttrValue.

* fix(studio): a failed save restores the preview it was given, not an older one

Each timeline save claims the preview's before-value when it starts, so a
gesture begun while it is in flight records its own and a later failed save
cannot put back a value from before an earlier save landed.

* chore(repo): allow the automation gesture key files this branch removes

* fix(studio): a refused automation save leaves the lane store and paste mark as saved

Reverting a live value re-syncs the lane store from the restored preview, so
an overlapping save that landed first cannot leave the store holding a later
value that failed. A paste whose save is refused or fails gives back the
selection and paste chain it replaced.

* fix(studio): a failed save settles on what the file holds and a refused paste marks nothing

A save that does not land settles the preview and store on the file's value
(the claimed before-value only when the file cannot be read), and leaves a
gesture begun meanwhile alone apart from correcting its before-value, so two
overlapping failed saves cannot leave either on a value that never landed. A
paste selects and marks its span only once it lands and only over the
selection it was pasted at.

* fix(studio): a failed save reads the file only after writes queued to it land

The settle read goes through the same per-path queue as the writes, so a save
that fails while another is queued settles the preview, the store and any
newer gesture's before-value on what that queued save wrote.

* fix(studio): an older failed save never settles over a newer edit on the same lane

Live-preview bookkeeping moves to createLiveLanes, one owner for both timeline
saves: each lane key carries a generation that every live write and save start
advances, and a save settles the preview and store (on its landed value, or on
the file after a failure) only while it is still the newest. A paste marks its
span only if it is still the latest paste.

* test(studio): a newer live drag keeps its preview when an older save recovers

* fix(studio): every finished save records what the file holds, even under a newer edit

A save's settle now always writes the file's value (landed, or read back after
a failure) into the lane store and a live gesture's before-value, and moves the
preview only while nothing newer has touched the lane. The clip store is set
from that value rather than copied from the preview. A paste marks its span
only while its clip is still the selected one.

* fix(studio): an older automation save never overrides a newer gesture on its lane

A failed save's recovery read could settle after a newer save started, and the
save's own optimistic preview patch and failure unwind ran over a newer drag.
Every preview write a save makes now goes through the lane's ownership check,
only the newest save records its value, and a refused drag hands the lane back
to the newest pending save.

* fix(studio): timeline attribute saves land in the order they start

An attribute save read the file before joining its write queue, so an older
save with a slow read could land after a newer one, overwrite it on disk and
leave the lane showing the newer value. The save now joins the queue first and
reads, patches and writes inside it. A save moves the preview only while it is
the newest save and no drag is live, which replaces the per-lane generation.

* refactor(studio): name the in-queue history write for the queue it needs

* test(studio): pin save start order and a newer release's preview mid-flight

* fix(studio): a drag keeps its points when an older save lands under it

An older save that landed mid-drag wrote the lane store, the lane dropped its
draft, and the release committed the older points. The lane now keeps its draft
while a gesture is live. A save that cannot read the file back settles on the
last value read or saved on its lane, never on an unsaved one, and an older save
that lands records its value there even when a newer save is pending.

* fix(studio): a lane's first failed save still puts its drag back

With the claimed-value fallback gone, a first save on a lane that failed and
could not read the file back settled on nothing, leaving the drag playing. A
save begun with no other save pending now records the value under its drag as
verified, since that is what the file last settled on.

* fix(studio): only a before-value read with no save pending counts as saved

The value under a drag was trusted when its save started with nothing pending,
but it was read when the drag began, possibly over a paste that later failed.
A lane now marks a before-value clean only when no save was pending as the drag
began. A group lane's preview carries its store mirror, as its live writes do.

* fix(studio): a lane's saved value never crosses into another project

The lane bookkeeping outlives a project switch and its keys had no project, so
a value saved in one project could settle into another project's clip with the
same key when a save there failed and could not read the file back. Lane keys
now carry the open project, and a save moves the preview or store only while
the project it was made in is still open.

* fix(studio): a failed save reads its file back from its own project

A save that failed after a project switch read its recovery from the newly
opened project and recorded that project's value as its own. Each save now
captures its project when it starts and reads back from it.

* fix(studio): a failed save never brings back a value an undo removed

A lane kept its last verified value after its saves settled, so after an undo a
save that failed and could not read the file back settled on the removed value.
The value now lives only while a save on the lane is in flight, and each save
records what its own in-queue file read found. The group preview's store mirror
is no longer needed and is gone.

* test(studio): pass the file-read callback in the direct attribute-save tests

* fix(studio): a drag whose before-value a save settled counts as clean

When a settle rewrites a live drag's before-value to a verified value, that
value is known saved, so the drag's own save can fall back on it even when its
read and read-back both fail. Adds a test for a failed save reading back from
its own project while another save is in flight across a switch.

* fix(studio): a save started in one composition never lands in another of the same project

Live lanes were scoped to the project only, so a save held across a switch
to another composition of that project settled its value into the new
composition's preview (clip and group lanes) and store (group lane).
Lanes are now scoped to the project and the composition open when the save
starts. createLiveLanes moves to its own module for the 600-line cap.

* fix(studio): an undo during or after a lane gesture stays undone when the next save fails

A live gesture records the lane's value before it starts, and a later save
that cannot read the file settles on that value. An undo mid-drag, or after a
gesture that ended without saving, left that value stale, so the save brought
back what the undo removed. Every undo and redo now re-reads each open lane's
value from the files it restored.

* fix(studio): undoing group automation clears it from the members' lanes at once

The group-info cache only noticed a change when its MutationObserver callback
ran, so the soft restore's store sync, which reads it synchronously, mirrored
the pre-undo group automation onto the members. A read now counts mutations
the observer has not delivered yet.

* fix(studio): an undo reaches every lane and pending save it rewrote, in any composition

The undo re-read only covered lanes in the open composition and live gestures.
History is project-wide, so undoing from another composition left the
rewritten composition's lanes on the pre-undo value, and a save released while
the undo was in flight kept that value as its fallback. The re-read now covers
every lane of the project on a restored path, including saves still pending,
and an undone file it cannot read makes the value untrusted instead of dropped.
A missing element reads as unreadable, the same as a save's read-back.

* fix(studio): a cancelled fade, stretch or preset audition leaves no stale lane value behind

A cancel put the gesture's start back through a live write, which left the
lane's before-value in place until the next save trusted it, even after the
property panel, the source editor or an agent had changed the file. The fade
cancel, the edge-stretch cancel and leaving a preset audition now end through
the lanes' revert, so a before-value exists only during a live gesture.

* test(studio): pin that a group write is read back fresh in the same task

* style(studio): drop two comments the names already carry

* fix(studio): a failed group save reads its own file back; fade cancels work without revert

- The group save's failure read-back used the file of whatever composition was
  loaded when the write failed. It now reads the file captured when the save
  started, as the clip save does.
- A fade cancel writes its start back live before it reverts, like the other
  cancel sites, so a host without the optional revert callback still puts the
  fade back.
- The edge-stretch cancel comment says what the code now does.
- The save test harness passes the revert callbacks, as the app does; without
  them the cancelled-gesture tests exercised a host that lacks them.

* refactor(studio): trim three long comments on live automation saves
2026-09-27 09:05:54 +00:00
Miguel Ángel 5b034cab74 fix(studio): an effect save resolves with whether it landed, was refused or failed (#4531)
* fix(studio): an effect save resolves with whether it landed, was refused or failed

setElementFxAttribute.setQuiet and setAudioGroupAttribute.setQuiet, which
every timeline effect save goes through, resolved the same way whether the
write landed, the host's canEdit refused it, recording blocked it, or the
write failed; only Studio's toast told them apart. They now resolve with a
TimelineEditOutcome: saved, refused with the reason, or failed with the
error. The lock guard resolves with the refusal handler's result, and a
clip that cannot be addressed in its file reports failed instead of saved.

* fix(studio): the lock guard hands its reason to the refused effect save

The refusal reason comes from the gate's own canEdit pass instead of a
second call, a group save with nothing to address reports failed like the
clip save, and the failure message says the clip has no id to save it by.
2026-09-26 09:22:39 +00:00
Miguel Ángel 4dc1bee9c2 fix(studio): preview lookups use the right element when an id repeats across files (#4486)
* fix(studio): preview lookups find the element the timeline bound when an id repeats

* fix(studio): preview lookups prefer the element's own file, and a pasted element gets its own hf-id

* fix(studio): scrub audio, panel reads and gestures act on the bound element, one scan per pass

* refactor(studio): one owner for the selected node lookup, and scrub indexes only audio

* fix(studio): the panel's tween list matches class tweens against the selected element itself
2026-09-25 11:42:10 +00:00
Miguel Ángel 224388ad29 fix(studio): every project opens its preview at Fit, and a zoom says so (#4473)
* fix(studio): every project opens its preview at Fit, and a zoom says so

Preview zoom was one saved value for every project, so a single pinch
made each project open at 245%. It now lasts only while the project is
open. While the preview is not at Fit, a chip at the top says how far it
is zoomed with a Fit button, and a navigator shows the visible part.

* fix(studio): Fit keeps the selection, and the zoom chip and navigator follow review

A click on Fit no longer reaches the pane that clears the timeline
selection, focus returns to the preview, one rule decides at-Fit, and a
project switch resets the zoom before paint.

* chore(studio): the zoom change keeps each file's comment share at or under main's

* refactor(studio): the zoom chip and navigator live beside the preview, under the file size cap
2026-09-25 11:36:44 +00:00
Miguel Ángel 828c434f76 refactor(studio): drop recordEdit's kind, which the project history never read (#4474) 2026-09-25 10:48:46 +00:00
Miguel Ángel 93df8a814d fix(studio): a timeline row binds to its own composition's element when an id repeats (#4481)
* fix(studio): a timeline row binds to its own composition's element when an id repeats

* fix(studio): keep the scoped lookup's comments within the file's comment share

* fix(studio): a unique id stays bound through a healed host, and Layers re-finds in its own file

* fix(studio): try every lookup in the clip's composition before a lone match

* perf(studio): skip the id selector when the id is not in the document
2026-09-25 09:36:15 +00:00
Miguel Ángel 36f8bd0e91 feat(studio): undo and redo step through the project history, whoever made the change (#4456)
* feat(studio-server): an undo taken from Studio is not mistaken for an outside edit

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

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

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

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

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

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

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

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

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

* fix(studio-server): a held drag ends when someone else changed a file it already holds
2026-09-25 08:43:04 +00:00
Miguel Ángel 4064b183e6 fix(studio): render a missing preview poster in either order and bank the open counts (#4479)
* ci(studio): bank the open-journey counts after #4401 and allow a reasoned raise

* fix(studio): render a missing preview poster whichever of the 404 and the live frame comes first
2026-09-25 08:39:46 +00:00
Miguel Ángel f873734cc4 perf(studio): open a large film ready to play in about 4 s instead of 32 s (#4401)
* perf(studio): keep lint off the preview open path

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

* perf(parsers): parse identical GSAP source once

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* perf(studio): keep lint off the boot

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The main merge brought a second vi.mock of @hyperframes/studio-server into studioServer.test.ts;
the later one replaced the first, so createProjectSignature was no longer a spy and the cached
signature test read .mock of undefined. One mock now carries both overrides.
2026-09-25 04:56:55 +00:00
Miguel Ángel 2623b666c2 test(studio): wait for the off-canvas indicator instead of a fixed number of frames (#4458) 2026-09-24 22:45:17 -04:00
Miguel Ángel 326df8def0 feat(studio): let an embedder draw the preview edge to edge with fillBox (#4408)
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.
2026-09-24 07:22:26 -04:00
Vance IngallsandClaude Sonnet 5 c59326d72e fix(studio): refresh the file tree on external change, and say when a composition is gone (#4370)
The fix the cutover-dashboard investigation this week was building toward.
Proven 2026-09-23: `refreshFileTree` (useFileTree) is only ever called from
Studio's OWN file operations (create/delete/rename/upload/block install) —
never on an external change. An agent removing or replacing a composition
updates the preview and the SDK session (useExternalFileChangeCoordinator
already reloads both) but never the tree, so the file stays listed and
clickable forever. Opening it opens a session that can never resolve
(`reason: "absent"`), every edit through it silently takes the (also
failing) server path, and nothing tells the user why.

Two refresh triggers, belt and braces:

- `useExternalFileChangeCoordinator` gains an optional `refreshFileTree`
  collaborator, called alongside `reloadPreview`/`reloadSdkSession` on
  every accepted external change — closes staleness at the source, for
  every consumer of the tree, not just the SDK read. Wired through
  `useStudioExternalFileChanges` from `fileManager.refreshFileTree`
  (already in scope there).

- `useSdkSession` gains `onAbsentRead`, called once per (projectId, path)
  when a read reports `reason: "absent"` — the fallback for a change the
  SSE never delivered (server restart, a missed watcher event). Guarded by
  a ref-tracked set so a genuinely-gone file can't loop, cleared on
  project change so a different project's identical path can still fire.

New: `sdkHandle.compositionMissing`, true for exactly that read result on
the currently active path, and `CompositionMissingBanner` — sibling of
`ProjectUnreachableBanner` (that one fires when the whole PROJECT is
unreachable; this one when the project is fine and this one file inside
it is not) — shown in App.tsx alongside it. The read failure alone is
silent; this is what tells the user their edits stopped landing.

Deliberately not touched: `activeCompPath` is never cleared when the path
leaves the tree — the graveyard page (`clearing-activecomppath-on-tree-
absence`) is binding, and its reasons still hold (`useAutoOpenRootComposition`
latches once; a null path never recovers).

Tests: coordinator refresh fires once per accepted change, not for a
self-write echo, and no-ops when the collaborator is absent (4 new).
useSdkSession: compositionMissing set/cleared, onAbsentRead once per path,
fires again for a different path, guard resets on project change, no-ops
without the collaborator (5 new). Banner render test (1 new). 25/25 in the
touched suites; 2830/2831 across studio hooks+components overall (the one
failure is a pre-existing happy-dom `window.confirm` gap in
ExternalFileConflictBanner.test.tsx, confirmed unrelated via git stash).
oxlint, oxfmt, tsc --noEmit clean.

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-23 20:13:21 -07:00
Miguel Ángel a57e095468 feat(studio): panel tabs take the decided Current design (#4266)
Studio's panels become cards on a dark shell, and each panel's tabs take the "Current" design: the open tab is a fill in the card's colour that slides to the tab you pick, only the open tab shows its icon and close glyph, and a strip that is too narrow scrolls with a soft edge instead of hiding tabs behind a menu. This replaces the pill, underline and close treatment that was on this PR before.

## Before

![Before 2x: main, dark](https://github.com/user-attachments/assets/00ec6f33-082a-4209-917d-dea3c73c5b3d)

![Before 2x: main, paper theme](https://github.com/user-attachments/assets/09b01028-fa94-4946-bc47-a9abe7111a2f)

## After

![After 2x: dark](https://github.com/user-attachments/assets/041dfebf-c2cd-48bb-9ad4-5200d9f2ef9a)

![After 2x: paper theme](https://github.com/user-attachments/assets/d901bda4-ed7a-462f-8b83-0a7e3d4a7eff)

Switching tabs (the fill slides in about 140 ms and the new icon fades in over 80 ms; the panel body switches at once):

https://github.com/user-attachments/assets/8d359ada-c9e1-4425-9c95-61d5d4f5271b

### Every label whole, and the tabs use the whole strip (2x)

An earlier head clipped the left strip's fourth tab next to empty strip space. That space was a 72 px slot (plus 4 px) held on every strip for the strip actions, even on strips whose panel is not focused and so draws no actions. Dockview sizes that slot by its content; this PR had pinned it. Now the slot takes room only where the actions are drawn, so an unfocused strip gives its tabs the whole width. Tab padding is 6 px with no gap between tabs, so the tabs also fit next to the actions. Labels, icons and close glyphs sit on the tab's centre in every strip.

Left strip at 1440 x 900, tabs width against the room before the action slot:

| | macOS | Linux (these captures) |
|---|---|---|
| Earlier head | 322 in 280, clipped | 312 in 280, clipped |
| Now, panel unfocused | 278 in 358 | 268 in 358 |
| Now, panel focused (actions shown) | 278 in 282 | 268 in 282 |

![Left strip 2x at 1440, earlier head: Catalog clipped](https://github.com/user-attachments/assets/42d8eae9-67f5-49b6-b581-19c5185a4bdc)

![Left strip 2x at 1440, now: every label whole](https://github.com/user-attachments/assets/fc5d9137-1cfe-42eb-a6cd-f8bd90c19b4d)

![Left strip 2x at 1440, panel focused: actions shown, labels still whole](https://github.com/user-attachments/assets/66ce47c2-5bd9-47ca-870e-9c3acf6001fc)

At 1280 x 800 the left column is narrower, and the pinned slot clipped Catalog next to the empty space. Room for the tabs there went from 241 px to 317 px:

![Left strip 2x at 1280, earlier head: Catalog clipped next to the empty action slot](https://github.com/user-attachments/assets/b0603454-7c2f-4a4c-98b4-9028bc9c0d31)

![Left strip 2x at 1280, now: the tabs use the whole strip](https://github.com/user-attachments/assets/f3dfb3ce-ccb8-4221-8339-e481ff31df7f)

Captured at the PR head (5fd6c7bd) from a fixture project (the `warm-grain` registry example) in headless Chrome on Linux, 2x, each state loaded fresh so Studio builds its default layout for that window. Before is `main`; the strip Befores use the earlier heads' `dock.css` (8079c635 at 1440, 8ed7ab69 at 1280) on the same build. The macOS column was measured live in Chrome on macOS. The paper theme only re-themes the timeline today, so the panels look the same in both themes.

## What changed

- **Cards on the shell.** Each dock group is a card with the only 1 px border (radius 10) and a 6 px gutter to its neighbours. The preview and timeline no longer draw a second rounded border inside it; the preview stage is an inset well. Dockview's tab dividers and separators are gone.
- **Tabs.** Tabs use the whole strip unless the panel shows its actions. Every label is whole at the default 1440 x 900 layout (6 px side padding, no gap between tabs), and labels and icons are centred in the tab. The open tab is a fill with rounded top corners, flush with the card body. Only the open tab shows its type icon and close glyph (the glyph appears on hover or keyboard focus, and its space is kept so the label never moves). Other tabs are labels.
- **One sliding fill per strip.** One element slides (transform and width, 140 ms ease-out) under the open tab. Reduced motion turns the slide and the icon fade off. Hover is instant.
- **Strip actions** (panel menu, maximise or restore, close group) sit on the active group only, at half opacity while the pointer is in the panel and full on hover or focus. They take room only on the strip that draws them, so the other strips give their tabs the whole width. The panel menu lists that side's panels as checkboxes, plus Reset layout.
- **Narrow strips** scroll sideways with a 12 px fade on the clipped edge. Dockview's overflow dropdown is off.
- Tokens: `--panel-shell-bg`, `--panel-card-bg`, `--panel-card-border`, `--panel-strip-bg`, `--panel-tab-bg-hover`, with contrast pairs registered.

## Timeline viewport gate

The first head of this rebuild (b20ff32a4) cost the timeline gate one frame on CI: interaction p95 33 ms on every run (first attempt 100 ms on three runs), against main's 20 ms. Main-thread traces were identical; the extra cost was compositing, from a fade mask on every tab strip. Masking only a strip that is actually clipped brought it back:

| Head | Interaction p95 per run (ms) | Frame p95 (ms) | Runs passing |
|---|---|---|---|
| main | 20, 20, 19, 20, 18 | 34 | 5/5 |
| b20ff32a4 (rerun) | 33, 33, 33, 33, 33 | 33 | 5/5 |
| 41302773 | 18, 20, 19, 20, 17 | 33 | 5/5 |
| eefaa839 | 18, 20, 18, 18, 20 | 17 | 5/5 |
| af4f2b9b (tab spacing), first attempt | 18, 79, 18, 116, 19 | 100 | 3/5 |
| af4f2b9b, rerun | 18, 16, 20, 18, 18 | 33 | 5/5 |
| 8ed7ab69 | 17, 16, 19, 24, 20 | 33 | 5/5 |
| 6a5edd89 | 33, 33, 33, 33, 33 | 17 | 5/5 |

From about 14:30Z `main` itself reads 33 ms on every run (three consecutive `main` CI runs), and CI tests this PR merged with the current `main`, so the 6a5edd89 row matches `main`'s level at that time.

The af4f2b9b first attempt had three runs at main's level and two single-run spikes; the same commit's rerun passed 5/5, and the change is tab spacing only.

## Tests

Each rule that could regress without anyone noticing has a test, and each test was proved by breaking the code once:

| Rule | Test | Break | Result |
|---|---|---|---|
| Icon and close glyph on the open tab only | `DockTabs.test.tsx` (dock.css applied, computed display) | delete the hide rule | 2 red |
| Actions on the active group only | `DockTabs.test.tsx` | drop the active-group check | 1 red |
| One fill per strip, following the open tab | `DockTabs.test.tsx` | fill stays at 0 / a second fill | 1 red each |
| One border per surface | `dockTabs.contract.test.ts` | add a strip border | 1 red |
| Only the slide and icon fade animate | `dockTabs.contract.test.ts` | add a hover transition | 1 red |
| Reduced motion turns them off | `dockTabs.contract.test.ts` | remove the reduced-motion rule | 1 red |
| Label and icon centred in the tab | `dockTabs.contract.test.ts` | drop the full-height rule | 1 red |
| Every tab label whole at 1440 x 900 on each strip while its panel is focused (the least room it gets), with 10 px for macOS's wider system font (CI renders a Linux fallback) | `scripts/studio-runtime-smoke.mjs` (CI "Studio: load smoke", real Chrome) | the "Ca" head's spacing; a spacing that fits on Linux but clips on macOS | red on both ("312px of tabs in 280px", "276px of tabs in 280px"); green on main and this head |
| Unfocused strips hold no room for actions they do not draw | `scripts/studio-runtime-smoke.mjs` | pin the action slot at 72 px again | red: "3 inactive dock strips hold width for actions they do not draw" |
| The shown tab stays whole when its strip narrows (its panel gains focus and the actions appear), comes back narrower than it was before it was hidden, or when a neighbouring tab closes and it moves | `DockTabs.test.tsx` | ignore each of those changes in turn | 1 red each; checked live at 1280 x 800: clicking into the left panel's body used to leave Catalog 37 px hidden, now it is whole |
| A strip the user scrolled by hand stays put when something else in the dock changes, when it widens, and through another panel's maximise and restore | `DockTabs.test.tsx` | reveal on every pass; on any width change; after a hidden spell | red each; checked live: a hand scroll of 20 px is still 20 px after a maximise and restore |

Run alone, each exits 0: `DockTabs.test.tsx` 5, `dockTabs.contract.test.ts` 5, `Dock.test.tsx` 14, `dockAccessibility.test.ts` 10, `PreviewPane.test.tsx` 1, `Menu.test.tsx` 10, `scripts/contrastRatchet.test.ts` passing.

## Independent review

An adversarial review (separate agent, mandate to refute) at 41302773, eefaa839, 8079c635, af4f2b9b and 8ed7ab69: **no blockers; one major, fixed.**

- MAJOR (af4f2b9b), fixed in 8ed7ab69: CI renders Studio's system font stack with a narrower Linux fallback, so the clip check could pass while a Mac clips. The check now keeps 10 px of room for the macOS font, and a spacing that fits on Linux but clips on macOS turns it red. The 8ed7ab69 review asked whether 10 px holds for every strip, not just the left one it was measured on. Measured macOS minus Linux tab width at 1440 x 900: left 10 px, right 6 px, Preview and Timeline 2 px each, so the left strip is the widest gap and 10 px covers all four.
- MINOR, left as is: the room check has no unit test of its own; it runs only in a real browser, and the smoke is its test (red on both broken spacings above).

- MINOR: a panel cannot be closed from the focused tab itself by keyboard. The keyboard path is focused tab, Tab to "Panel menu", Enter, uncheck the panel (checked live: closes that one panel; checking it again reopens it). The tab's close glyph is not focusable, the same as dockview's stock tab on main, because a tab cannot hold a focusable button.
- MINOR: the open tab is 16 px wider than on the design page (the close glyph's space is kept; see For Miguel).
- Resolved: a contrast pair cited stale line numbers.

## UX checklist

**Job:** someone editing a video moves between panels (Compositions, Assets, Code, Catalog; Design, Layers, Renders, Variables) many times an hour and needs to see which one is open and reach the next without hunting.
**One action:** click the tab of the panel you want.

| # | Question | Y/N | Evidence |
|---|---|---|---|
| 1 | First-time user knows what to do | Y | Tabs keep their labels; the open tab is joined to the body it controls (After captures) |
| 2 | Interactive things look interactive | N | Strip actions are hidden until the pointer is in the panel (Miguel's decision; see Traded off) |
| 3 | User's words, no internal ids | Y | Titles unchanged; controls named "Close Design", "Panel menu", "Maximize panel", "Close group" |
| 4 | Works like other tools | Y | Editor-style tabs with maximise and a panel menu |
| 5 | Guidance at the control | N | The three icon buttons have accessible names but no visible tooltip |
| 6 | Primary action reachable without reading | Y | The tabs are the strip |
| 7 | Exactly one primary action | Y | Tabs; actions are secondary and quiet |
| 8 | Counts match data | Y | Titles come from each panel through `Dock.Panel` (`Dock.tsx` setTitle) |
| 9 | Excluded items announce themselves | Y | Every label is whole at the default width (the load smoke checks it); a narrowed strip scrolls with an edge fade, and the panel menu lists every panel |
| 10 | Long names recoverable | Y | Tabs never truncate; the strip scrolls |
| 11 | Keyboard path | Y | Arrow keys move and activate tabs (existing); strip actions are buttons and show on focus |
| 12 | Nothing hover-only that must be acted on | N | Same as 2 |
| 13 | Refusals say what next | n/a | No refusals here |
| 14 | Refusal next to the thing | n/a | |
| 15 | Error prevented | n/a | |
| 16 | Can leave any state without losing work | Y | Closed panels reopen from Window or the panel menu; Reset layout restores the default |
| 17 | Destructive looks different | N | "Close group" uses the same x as a tab's close; it loses no work, and the Window menu reopens the panels |
| 18 | Empty state names what is empty | n/a | |
| 19 | Feedback within 400 ms | Y | The tab state and icon change in the same frame as the click; the fill arrives in 140 ms |
| 20 | Progress on waits | n/a | |
| 21 | Hand-built state survives reload | Y | Layout, open tab and maximised group persist per project (existing dock persistence) |

**Choice:** four tabs per side, one click each. **The end:** the panel body appears at once and the fill settles under the tab you picked.
**Not exercised:** a screen reader pass; touch input.
**Traded off:** hover-only strip actions (rows 2 and 12) and scroll-plus-fade instead of an overflow menu when a strip is narrowed are Miguel's decided design.

## For Miguel

- **Paper (light) theme:** Studio's paper block only re-themes the timeline today, so the panels are dark in both the Before and After paper shots. Panel paper values are Desktop's to set (design principles, section 7); this PR adds the token names Desktop can override.
- **Action slot:** the design review asked for the action slot to be reserved on every strip, so tabs never move when focus changes panel. That reservation is what clipped "Ca" next to empty space, so it now holds room only on the focused panel. The cost: when a strip that is already too narrow gains focus, its actions take 76 px. The strip then scrolls so the shown tab stays whole, and a neighbouring tab can go under the edge fade. At the default 1440 x 900 nothing clips either way.
- **Tab spacing:** side padding is 6 px (10 on the design page) and tabs have no gap. The design's 10 px would need 322 px on macOS; the left strip has 282 px beside its actions at 1440. A wider default left column would allow the design padding again. A narrower window scrolls the strip with the edge fade; per the decision there is no overflow chevron.
- **Close glyph space:** the open tab keeps its close glyph's space at rest, so it is 16 px wider than on the design page, where the label shifts on hover.
- **Not in this PR:** inspector section headers and the focused-card border step (later build steps).
2026-09-23 14:34:10 -04:00
Miguel Ángel df97c599ee perf(studio): stop the manual-edit loop from running while the preview is paused (#4333)
* perf(studio): stop the manual-edit reapply loop from running while paused

* fix(studio): judge nested timelines by their parent, not the player alone

* fix(studio): bound the paused-ancestor walk and ignore unknown parents

* style(studio): format the manual-edit tests
2026-09-23 11:10:11 -04:00
Miguel Ángel 8cb7d06db6 perf(studio): re-render only the edited scene's thumbnails after an edit (#4315)
* perf(studio): refresh only the edited scene's thumbnails and let the preview load first

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

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

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

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

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

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

* style(studio): format thumbnail-scope changes

* docs(studio): trim thumbnail input comments
2026-09-23 10:29:01 -04:00
Miguel Ángel b73df3549e refactor(studio): remove unreachable expanded-child timeline code (#4219)
* refactor(studio): keep legacy fixture state out of rendered rows

* fix(studio): keep timeline keyboard actor mounted

* refactor(studio): remove expansion telemetry and prove stable nested rows

* test(studio): type nested timeline fixture broadly

* test(studio): remove expansion lane assertions

* test(studio): assert nested row identity by key

* fix(studio): satisfy removal and format guards

* fix(studio): clear fallow findings in timeline cleanup

* test(studio): update timeline removal expectations

* fix(studio): remove stale timeline test helpers

* fix(studio): keep automation lanes mounted without disclosure

* refactor(studio): keep audio lanes while removing clip expansion

* fix(studio): restore audio disclosure state

* test(studio): remove obsolete expanded fixture assertions

* fix(studio): resolve provider rebase without clip auto expansion

* fix(studio): remove inline keyframe expansion rows

* fix(studio): restore automation disclosure state

* fix(studio): remove stale timeline model inputs

* fix(studio): pass animation state to timeline layout

* fix(studio): remove stale expansion tests and helpers

* test(studio): cover shared audio lane labels

* fix(studio): remove unused keyframe callback plumbing

* fix(studio): clear rebase lint leftovers

* fix(studio): remove unused timeline header export

* style(studio): format timeline cleanup

* fix(studio): restore composable timeline exports

* fix(studio): keep audio lanes open across selection

* fix(studio): align timeline lane test contract

* fix(studio): remove stale lane test import

* fix(studio): align track header test callback

* fix(studio): remove stale track header test prop

* test(studio): preserve ruler half pixel alignment

* test(studio): keep audio lane fixtures drawable

* test(studio): assert shared lane owner label

* fix(studio): align audio lane expansion with layout state

* test(studio): use the audio lane owner label

* fix(studio): unify audio lane expansion state

* fix(studio): align automation lane labels

* fix(studio): remove stale lane height import

* test(studio): assert automation labels against the real curve, not a formula

The previous test recomputed the expected top with the same formula
the fix uses, so a regression in TimelineAutomationLaneSlot's own
offset would still read green. Moved it to TimelineLanes.test.tsx,
which mounts both the header and the canvas, and compares their
rendered [data-automation-lane-label]/[data-automation-lane] tops
directly.

* revert(studio): restore the keyframe-row feature from main

Miguel: keep the per-property keyframe rows (diamonds, prev/next
arrows, disclosure, auto-open) exactly as main. This PR's real scope
is removing dead expandedParentStart consumers, not the keyframe-row
UX.

* refactor(studio): remove dead expanded-child timeline code

expandedParentStart is never set anywhere on main (the inline
sub-composition child-row expansion that produced it was already
removed in #4132/7797c5ead). Delete its now-dead consumers: the
TimelinePane move/resize/delete/split rebase wrappers, the ZMirror
call site that routed through them, the timelineDragLanding topology
guards, isMainTrackElement's expanded-child exclusion, laneGapFloor's
host-window-start math, and the paired expanded-clip-edit telemetry.
Keeps every keyframe-row feature (diamonds, prev/next arrows,
disclosure, auto-open, telemetry) untouched.
2026-09-23 01:38:50 -04:00
CasbaLandCasbaL e5eeeef972 fix(studio): stop VideoFrameThumbnail error→cleanup infinite loop (#4037)
The error handler called cleanup(), which sets video.src = "" and calls
load(). Clearing src itself fires another error event, re-entering the
handler at event-loop speed — every pass allocating a React update via
setFailed(true). The seeked path triggers the same loop: its cleanup
provokes the synthetic error right after a successful frame extract.

Detach the error listener inside cleanup() and ignore the synthetic
empty-src error. Instrumentation on a real session measured ~475k src
assignments/second and ~8.6 MB/s of update allocations before the fix.

Fixes #4036

Co-authored-by: CasbaL <26603379+CasbaL@users.noreply.github.com>
2026-09-23 01:00:15 -04:00
Miguel Ángel 867787b2f9 feat(studio): menus and popovers paint instantly (#4268)
* feat(studio): menus and popovers paint instantly

Menus and popovers open and close with no fade. Hover colour is unchanged.

* fix(studio): fade menus in from a visible shape

Menus, popovers, and dropdowns start at opacity 0.8 and scale 0.97, then settle in 120ms. They close in 90ms. Tooltips use the same shape in 100ms.
2026-09-22 01:05:00 -04:00
Miguel Ángel 2cc384f1fe feat(studio): draw icons that say what the feature does (#4262) 2026-09-21 21:05:20 -04:00
Miguel Ángel 1efe02a346 feat(studio): draw the audio meters toggle as a level meter (#4254) 2026-09-21 20:06:54 -04:00
Miguel Ángel 6f6d24248c feat(studio): audio meter faders for groups and master (#4203)
* feat(studio): audio meter faders for groups and master

* fix(studio): meter's mid band uses amber-500, the theme's actual token

yellow-500 was reset to nothing by palette-reset.css (--color-*: initial)
and never redefined in theme.css, so the mask never revealed any color
for -6 to -3dB; the token gate test already catches this and was red.

* refactor(studio): rename YELLOW_AT to AMBER_AT to match the amber token

* fix(studio): fader nudge and aria-valuenow match the visual dB position

* refactor(studio): use core StereoLevel for meter channel shape

* fix(core): emit levelTap in the packed core build

* fix(studio): name the preview fader Monitor and share clampNumber

* fix(studio): split the meter rAF tick and cover its branches

* style(studio): oxfmt AudioMeterStrip tests

* fix(studio): preserve authored gain in audio meter faders

* fix(studio): make timeline audio meters opt-in
2026-09-21 19:25:04 -04:00
839ae426dd feat(studio): typed audio values, clip fades, audible video drops (#4250)
* feat(studio): typed audio values, clip fades, audible video drops

Audio rows in the media inspector (Volume, Speed, Media start) take a
typed value: click the readout, type "-6 dB", "1.5x" or "2.5s", Enter.
Speed presets are hidden on <audio> clips.

Clip-edge fades: data-fade-in / data-fade-out in seconds, honoured by the
preview runtime (per-tick gain), the render mixer (afade after volume) and
Studio (Fade in / Fade out rows, and drag dots at the top corners of audio
clips and audible videos). Linear on both sides so preview and render
agree; fades that outrun the clip scale to meet inside it.

Dropped videos with an audio stream now land with data-has-audio="true"
instead of muted, so the mixer keeps their sound. The media metadata
endpoint reports hasAudio from the ffprobe call it already makes.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* fix(audio): one owner for fades, dB, and afade-after-volume

Illegal fade values become no-fade at fadeGain; typed inspector input
still returns null so the readout stays red. Master and group mixes
share one filter chain with volume then afade. Fade-out stays anchored
to the trimmed clip end.

* fix(studio): share audio helpers and bound typed media values

* fix(studio): reserve sibling fade duration when editing

---------

Co-authored-by: Jake Moran <jakemoran2011@gmail.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
2026-09-21 18:45:08 -04:00
Miguel Ángel 97420736d5 feat(studio): audio level meters at the timeline's right edge (#4193)
* feat(studio): audio level meters at the timeline's right edge

* test(core): cover metering started before the audio context finishes init

* fix(studio): keep meter follow after a dead preview and start bars at silence

* fix(studio): keep the 0 dB peak tick inside the meter

* fix(studio): keep the 0 dB peak tick visible without calc()

* fix(core): tap meters on the program bus, mute on a monitor gain

* style(core): wrap applyMasterGain to satisfy oxfmt
2026-09-21 16:19:30 -04:00
Miguel Ángel 4ff4435e1d feat(studio): export player handle for hosts (#4227) 2026-09-20 17:47:35 -04:00
Miguel Ángel 2fb6f6987e test(studio): close shadow reload regression gaps (#4223)
* test(studio): close shadow reload regression gaps

* chore: refresh follow-up checks

* test: keep follow-up free of unused exports

* test(studio): distinguish root timeline selection
2026-09-20 17:15:29 -04:00
Miguel Ángel e48eac7f5e feat(studio): track preview time to first frame (#4226) 2026-09-20 17:10:41 -04:00
Vance IngallsandClaude Code f476e78cc8 feat(studio): say which project this Studio is serving when a read 404s (#4228)
A tab whose project the running Studio cannot resolve failed every composition
read with a 404 and said nothing. `useSdkSession` recorded the failure to
telemetry and returned, so the editor looked normal while every edit silently
took the server path instead of the SDK — nothing landed, and nothing said
why. The `out-fb1` timeline sat in that state for an hour and a half, through
a reload that passed mount validation.

The banner names both sides: "This Studio is serving X. This tab was opened
for Y." That is the whole truth in the host that produces these 404s. The
CLI-embedded Studio serves exactly one project, and `hyperframes preview`
reuses port 3002 when the folder matches, so starting it on a different
folder takes the port out from under an open tab — and the project the old
tab was pointed at is untouched on disk. "No longer available" would be
false: nothing was lost, and the same timeline shows the project return.

With several projects served (the Vite host) a rename cannot be told from a
deletion, so that wording claims no cause.

`reportReadFailure` answers which project a failed read identifies. Only a 404
does; a 5xx, a dropped request, an unexpected body or an empty file say nothing
about which project the server serves, so none of them claim it.

Also fixes a smaller lie on the same path: `useFileTree` parsed the 404's JSON
body without checking `r.ok`, so the failure took the success branch and
recorded an empty tree — and an empty provenance snapshot for a project that
was never read — which then travelled out in bug reports.

The 404s continue; this ends the silent part, not the failure.

Co-authored-by: Claude Code <noreply@anthropic.com>
2026-09-20 13:53:52 -07:00
Miguel Ángel 243ecd1d10 feat(studio): compose preview overlay guides (#4220)
* feat(studio): compose preview overlay guides

* fix(studio): sync late preview iframe mounts

* fix(studio): make preview iframe ownership explicit
2026-09-20 14:37:50 -04:00
Miguel Ángel 85a1a8f789 fix(studio): swap the preview via a shadow iframe instead of blanking on reload (#4207)
* fix(studio): reloading the preview swaps in a ready copy instead of blanking

* fix(player): report painted once assets are ready and the loader has faded out

assetsready fires when the loader fade starts, so a consumer promoting on it can
expose a raised or fading panel. painted fires once per document load after the
fade completes, with a getter for late listeners; it resets on each load.

* fix(studio): promote the shadow preview only when painted, under one wait budget

Studio waited for ready plus two frames, which can land while the player's loader
panel is still up or fading. It now also waits for the player's painted event.
The shadow no longer arms the 5s adapter give-up, so a slow but live load fails
only at the single 15s budget. Set-destination availability follows the live
iframe across a swap.
2026-09-20 13:04:23 -04:00