From dc01a12d71022b60ee0d12cad74c46a2e8753f81 Mon Sep 17 00:00:00 2001
From: Akshar Patel <123344143+AksharP5@users.noreply.github.com>
Date: Wed, 12 Aug 2026 23:49:13 -0400
Subject: [PATCH 1/7] fix(catalog): keep the typewriter preview inside the
frame (#3249)
---
docs/public/catalog/components/typewriter.json | 2 +-
registry/components/typewriter/demo.html | 4 ++--
2 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/public/catalog/components/typewriter.json b/docs/public/catalog/components/typewriter.json
index 8da43c237d..7cb5811e94 100644
--- a/docs/public/catalog/components/typewriter.json
+++ b/docs/public/catalog/components/typewriter.json
@@ -1 +1 @@
-{"html":"\n\n
\n \n \n Typewriter - Demo \n \n \n \n \n \n
\n
hyperframes add typewriter
\n
\n \n
\n \n\n"}
\ No newline at end of file
+{"html":"\n\n \n \n \n Typewriter - Demo \n \n \n \n \n \n
\n
hyperframes add typewriter
\n
\n \n
\n \n\n"}
\ No newline at end of file
diff --git a/registry/components/typewriter/demo.html b/registry/components/typewriter/demo.html
index 9940e99d69..6d2f1ee54e 100644
--- a/registry/components/typewriter/demo.html
+++ b/registry/components/typewriter/demo.html
@@ -31,7 +31,7 @@
min-height: 500px;
padding: 64px;
/* ponytail: scale-up only; GSAP targets .hf-remocn-typewriter with CSS vars, not transforms */
- transform: scale(2.8);
+ transform: scale(2);
}
.hf-remocn-typewriter {
color: #18181b;
@@ -44,7 +44,7 @@
align-items: center;
gap: 6px;
font:
- 800 52px/1 ui-monospace,
+ 800 52px/1.2 ui-monospace,
SFMono-Regular,
Menlo,
monospace;
From 158f15e8f0739c08d72eca46b34904285dae09c5 Mon Sep 17 00:00:00 2001
From: Akshar Patel <123344143+AksharP5@users.noreply.github.com>
Date: Wed, 12 Aug 2026 23:55:21 -0400
Subject: [PATCH 2/7] fix(catalog): keep the animated bar chart preview in
frame (#3254)
---
docs/public/catalog/components/animated-bar-chart.json | 2 +-
registry/components/animated-bar-chart/demo.html | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/public/catalog/components/animated-bar-chart.json b/docs/public/catalog/components/animated-bar-chart.json
index 0af415bf2d..d89caaec69 100644
--- a/docs/public/catalog/components/animated-bar-chart.json
+++ b/docs/public/catalog/components/animated-bar-chart.json
@@ -1 +1 @@
-{"html":"\n\n \n \n \n Animated Bar Chart - Demo \n \n \n \n \n \n \n\n"}
\ No newline at end of file
+{"html":"\n\n \n \n \n Animated Bar Chart - Demo \n \n \n \n \n \n \n\n"}
\ No newline at end of file
diff --git a/registry/components/animated-bar-chart/demo.html b/registry/components/animated-bar-chart/demo.html
index c5c35e736e..0a9429d89b 100644
--- a/registry/components/animated-bar-chart/demo.html
+++ b/registry/components/animated-bar-chart/demo.html
@@ -28,7 +28,7 @@
display: grid;
place-items: center;
padding: 52px;
- transform: scale(2.1);
+ transform: scale(1.6);
transform-origin: center center;
}
.hf-remocn-animated-bar-chart {
From a2109a863319e6c603b3d5758bc4a180c7cff064 Mon Sep 17 00:00:00 2001
From: Akshar Patel <123344143+AksharP5@users.noreply.github.com>
Date: Wed, 12 Aug 2026 23:55:25 -0400
Subject: [PATCH 3/7] fix(catalog): keep the text stagger preview inside the
frame (#3255)
---
docs/public/catalog/components/text-stagger.json | 2 +-
registry/components/text-stagger/demo.html | 6 +++---
2 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/docs/public/catalog/components/text-stagger.json b/docs/public/catalog/components/text-stagger.json
index ebe12b9a07..70eaae8c0a 100644
--- a/docs/public/catalog/components/text-stagger.json
+++ b/docs/public/catalog/components/text-stagger.json
@@ -1 +1 @@
-{"html":"\n\n \n \n \n Text Stagger - Demo \n \n \n \n \n \n
\n
text-stagger
\n
\n Build \n motion \n systems \n fast \n
\n
\n \n
\n \n\n"}
\ No newline at end of file
+{"html":"\n\n \n \n \n Text Stagger - Demo \n \n \n \n \n \n
\n
text-stagger
\n
\n Build \n motion \n systems \n fast \n
\n
\n \n
\n \n\n"}
\ No newline at end of file
diff --git a/registry/components/text-stagger/demo.html b/registry/components/text-stagger/demo.html
index 2309d4395a..330f11c8b8 100644
--- a/registry/components/text-stagger/demo.html
+++ b/registry/components/text-stagger/demo.html
@@ -28,8 +28,8 @@
display: grid;
place-items: center;
gap: 28px;
- /* ponytail: scale on non-GSAP wrapper; text was ~7% frame height, now fills ~55% */
- transform: scale(2.6);
+ /* Scale the non-GSAP wrapper while keeping the full phrase inside the frame. */
+ transform: scale(1.9);
transform-origin: center center;
}
.demo-label {
@@ -37,7 +37,7 @@
font-weight: 500;
letter-spacing: 0.12em;
text-transform: uppercase;
- color: #a1a1aa;
+ color: #737379;
}
.hf-transition-text-stagger {
display: flex;
From c71fab322e555463bde94953a006a1c46c0c2a12 Mon Sep 17 00:00:00 2001
From: Akshar Patel <123344143+AksharP5@users.noreply.github.com>
Date: Wed, 12 Aug 2026 23:55:29 -0400
Subject: [PATCH 4/7] fix(catalog): center the menu morph preview (#3256)
---
docs/public/catalog/components/menu-morph.json | 2 +-
registry/components/menu-morph/demo.html | 4 ++--
2 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/public/catalog/components/menu-morph.json b/docs/public/catalog/components/menu-morph.json
index aa650c84f5..1d3244b1f4 100644
--- a/docs/public/catalog/components/menu-morph.json
+++ b/docs/public/catalog/components/menu-morph.json
@@ -1 +1 @@
-{"html":"\n\n \n \n \n Menu Morph - Demo \n \n \n \n \n \n \n\n"}
\ No newline at end of file
+{"html":"\n\n \n \n \n Menu Morph - Demo \n \n \n \n \n \n \n\n"}
\ No newline at end of file
diff --git a/registry/components/menu-morph/demo.html b/registry/components/menu-morph/demo.html
index 591cbf1d77..b284d2a2f9 100644
--- a/registry/components/menu-morph/demo.html
+++ b/registry/components/menu-morph/demo.html
@@ -30,8 +30,8 @@
min-width: 760px;
min-height: 480px;
padding: 56px;
- /* ponytail: zoom on the wrapper — GSAP animates children, not this element */
- zoom: 3.4;
+ /* ponytail: scale the wrapper — GSAP animates children, not this element */
+ transform: scale(3.4);
}
.hf-transition-menu-morph {
position: relative;
From cbd38b32f7a1cc38964e898991b8767d3a05506c Mon Sep 17 00:00:00 2001
From: Akshar Patel <123344143+AksharP5@users.noreply.github.com>
Date: Thu, 13 Aug 2026 00:38:47 -0400
Subject: [PATCH 5/7] fix(catalog): restore the caption texture preview (#3258)
---
docs/public/catalog/components/caption-texture.json | 2 +-
registry/components/caption-texture/demo.html | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/public/catalog/components/caption-texture.json b/docs/public/catalog/components/caption-texture.json
index 0ea90d3194..c68103dfce 100644
--- a/docs/public/catalog/components/caption-texture.json
+++ b/docs/public/catalog/components/caption-texture.json
@@ -1 +1 @@
-{"html":"\n\n \n \n \n Texture \n \n \n \n \n \n \n \n \n\n \n \n\n"}
\ No newline at end of file
+{"html":"\n\n \n \n \n Texture \n \n \n \n \n \n \n \n \n\n \n \n\n"}
\ No newline at end of file
diff --git a/registry/components/caption-texture/demo.html b/registry/components/caption-texture/demo.html
index 60e73207ae..1ab6847445 100644
--- a/registry/components/caption-texture/demo.html
+++ b/registry/components/caption-texture/demo.html
@@ -109,7 +109,7 @@
? window.__hyperframes.getVariables()
: {};
var TEXTURE = vars.texture || "lava";
- var TEXTURE_URL = "compositions/components/" + TEXTURE + ".png";
+ var TEXTURE_URL = TEXTURE + ".png";
var _fitCanvas = document.createElement("canvas");
var _fitCtx = _fitCanvas.getContext("2d");
From 64a85e775a2259938e24d2fc7dc279c402397761 Mon Sep 17 00:00:00 2001
From: Vance Ingalls
Date: Wed, 12 Aug 2026 22:07:17 -0700
Subject: [PATCH 6/7] feat(studio): shape and simplify an automation selection
(#3055)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
* feat(core): audio FX registry
One declarative description of every effect that can be applied to an audio
track: fourteen across filters, dynamics, non-linear and time, each exposing
its full parameter surface rather than a curated subset.
Parameters carry the range, step, unit and scale a control needs, so a panel
can generate its UI from this rather than hard-coding a form per effect, and a
value that survives `normalizeAudioFxParams` is always safe to realise.
Everything is declared in the units a person thinks in — dB, ms, Hz.
Parsing rejects an unknown effect id rather than skipping the node. A chain
that quietly loses an effect renders something other than what was authored,
which is worse than refusing to load it.
Data only: no audio is produced here. The graph that realises each effect is
referenced by the `web` id and lands in the next change, which keeps this
module free of browser globals so the engine and the linter can import it.
* fix(core): stop declaring knobs that move nothing
Three parameters were declared with ranges, defaults and hints, and read by no
builder — dials an author could turn with no audible result.
- `chorus.decay` and `bitcrush.aa`: removed. FFmpeg's chorus feeds a decay back
into its delay line and a bitcrusher's anti-alias needs a real filter; adding
either is new DSP, not a fix, so the honest move is to stop advertising them.
- `lowshelf.q` / `highshelf.q`: removed. The Web Audio spec leaves Q unused for
shelving filters, so the control moved nothing — and because the shared Q
helper marks it automatable, an author could draw an envelope on it and hear
nothing at all.
`phaser.decay` and `gate.knee` stay: the first drives the sweep depth, and the
second is now read by the gate's processor.
A test asserts each of these directly, since the existing exposure invariant only
checks that a flagged parameter reaches an AudioParam — a parameter the node then
ignores passes it.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(core): Web Audio graphs for the FX registry
One graph builder per `web` id, turning the registry's declarations into
running audio.
Every node exposes `update`, so turning a dial re-parameterises the live graph
rather than rebuilding it: an AudioParam change lands on the next 128-sample
quantum, about 2.7 ms at 48 kHz. `buildFxChain` reports whether an update could
be applied in place — adding or bypassing an effect, or switching a filter
between one and two poles (which changes the node type from BiquadFilterNode to
IIRFilterNode), changes the graph's shape and returns false so the caller
rebuilds.
Four effects have no native node and run as AudioWorklet processors:
compressor, limiter, gate and bitcrush. The module is registered from a data:
URL rather than a blob:, because a blob inherits the page origin and is opaque
on a file:// page, where it fails with an unhelpful AbortError.
Reverb has no single node either. `synthesizeReverbImpulse` generates a tail
from the room parameters, seeded so the same room sounds the same on every
machine, and the ConvolverNode uses it.
Tests cover the wiring — which nodes get built, how they connect, parameter
application and clamping, in-place update versus rebuild, disposal — against a
fake AudioContext, since happy-dom has no Web Audio.
* fix(core): reverb level, phaser wiring, per-channel dynamics, one-pole rebuild
Four defects in the graph builders, all found by review rather than by ear.
**Reverb was unusable at its own defaults.** A ConvolverNode applies the
impulse's gain whole — the graph sets `normalize = false` so a room is
deterministic rather than browser-defined — but the impulse was raw decaying
noise. Measured L2 at the registry default (size 0.7 / damping 0.5): 46.4, or
+33.3 dB, putting the wet path ~24 dB over dry at the default `wet: 0.35`. It is
now normalised to unit energy, so the wet knob means what it says. Preview and
render both convolve this buffer, so they stayed identical throughout — equally
deafening before, equally correct now.
**Phaser in_gain/out_gain trim the signal entering and leaving the effect**, not
a wet/dry pair. Wired to the wet and dry legs, "Input" muted the dry path and
the two defaults summed to 1.14, so inserting a phaser raised the track level.
They are now input and output trims with the legs summed at unity. Its declared
waveform is also honoured: `lfo.type` was never assigned, so the default
"Triangular" was silently a sine.
**The dynamics worklets held one envelope across a channel-major loop.** The
followers advance per sample, so on stereo a 20 ms attack behaved as 10 ms, and
the right channel's gain came from an envelope that had already traversed the
left — the two ducked differently from the same input and the image pumped.
State is now per channel, as is the gate's smoothed gain and bitcrush's
sample-hold counter, which previously advanced only on the last channel and left
every earlier one frozen for a whole quantum. The gate also honours the knee it
declares instead of chattering on material sitting at the threshold.
**A one-pole filter's cutoff was swallowed in preview.** Its coefficients are
fixed at construction, so `update` cannot push a new frequency — but the shape
signature carried only type and pole count, so a cutoff change looked like a
values-only edit and went into a no-op updater. Preview kept filtering at the
old frequency while the render used the new one: a preview/render divergence in
exactly the two effects that do not use a BiquadFilterNode.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(engine): render audio FX in an OfflineAudioContext
Reads `data-fx-chain` off an audio element and runs the chain over the trimmed
WAV before volume automation is baked in — effects should see the raw signal,
and the envelope belongs on their output.
The processing happens in an OfflineAudioContext inside the headless browser
the engine already drives, running the same graph builders the studio previews
with. That is the point of the approach: one implementation per effect, so the
render agreeing with the preview is a property of the architecture rather than
a tolerance to police. Reimplementing each effect as an FFmpeg filter would
mean two implementations to keep in step, and for the dynamics processors and
modulated delays there is no filter that behaves the same way.
`build:audio-fx-runtime` bundles the graph builders into an injectable IIFE,
following the same pattern as the existing runtime artifacts, so the browser
runs exactly the code the studio does.
The page loads from a file:// URL rather than about:blank because AudioWorklet
is only exposed in a secure context — the compressor, limiter, gate and
bitcrush processors would otherwise fail to register with an opaque error.
file:// qualifies and needs no listening socket.
The chain is serialised into the attribute the way colour grading carries its
config, so there is no side-car file to resolve or lose.
An FX failure is fatal for the whole mix rather than a per-track soft failure.
Every other audio failure mode degrades gracefully — the track drops, siblings
continue — but substituting the dry signal for a processed one ships a render
that sounds plausible and is not what the author set up. Since the per-element
work races under Promise.all, an internal AbortController chained off the
caller's signal aborts in-flight siblings before workDir is removed.
* feat(core): voiceover carve analysis
Finds the bands a voice occupies so a music bed can be dipped there, letting
the voice sit in front without ducking the whole track.
Carve is a relationship between two tracks rather than an effect on one, so it
stays out of the FX chain. What it emits is an ordinary chain of peaking
filters, so a carve composes with whatever else is on the track and needs no
separate rendering path.
Selection is weighted toward intelligibility rather than raw voice energy.
Ranking purely by power lands on the fundamental almost every time, because
that is where a voice is loudest — but the masking that actually hurts a
voiceover happens higher up, and dipping 160 Hz mostly just thins the bed. The
bias is a control, not a constant: at 0 it follows raw energy, at 1 it weights
toward 1-3 kHz.
Ranking happens in dB, which matters more than it looks. Speech spreads 20-30 dB
across these bands — it falls off roughly 6 dB per octave above the fundamental
— so a weighting has to be on that scale to move anything at all. A
multiplicative weight of `1 - bias + bias * shaped` is bounded below by
`1 - bias`, capping its influence at 10*log10(1/(1 - bias)): 5.2 dB at the 0.7
default, 3 dB at 0.5. That is no influence against a real voice — every bias
short of ~0.95 would rank exactly like bias 0 and carve the fundamental, the
outcome the bias exists to prevent, while looking decisive against a fixture
whose bands sit 2 dB apart. So the bias is a dB penalty, zero at 2 kHz and worth
up to 30 dB at full strength, and relative cut depths come from a dB difference
rather than a ratio of weighted linear powers.
The bias reweights ranking without overriding the spectrum — a band the voice
has no energy in is not worth carving, and scores -Infinity rather than
competing — so a strongly low-pitched voice can still select low at full bias.
What the tests hold is that biasing never selects lower than the unbiased
ranking, that the DEFAULT bias reaches the presence region on a voice with a
realistic tilt, and that bias 0 still follows raw power exactly.
Includes a radix-2 FFT rather than a dependency; one Welch-style averaged
spectrum over third-octave bands does not justify pulling in a DSP library.
* fix(engine): keep the FX render 16-bit, stereo, and correctly sized
Three defects in the offline FX path, none of which any test could see.
**Float output silently disabled sample-accurate volume automation.** The writer
emitted 32-bit IEEE float; the very next mixer step bakes the volume envelope
into the samples and accepts only 16-bit PCM, returning null otherwise. So
enabling any effect downgraded that track to the ffmpeg expression path — capped
at 32 straight segments, quantising a curved envelope, and on a dense one falling
back to base volume. It now writes 16-bit PCM, clamped rather than wrapped so a
limiter at 0 dB or a resonant filter cannot turn overshoot into a click. A test
asserts the baker accepts the writer's own output and actually fades it.
**Everything was folded to mono.** `prepareAudioTrack` goes out of its way to
emit stereo — its pan filter exists to dodge ffmpeg's 3 dB mono-to-stereo
rematrix — and this folded it, then wrote one channel. So adding a single peaking
EQ collapsed a bed's width and cost ~3 dB in the render, while preview stayed
stereo. Channels now travel as one plane each, through an OfflineAudioContext of
the same width, and come back interleaved.
**Small results decoded the wrong length.** `new Float32Array(buf.buffer)`
discards byteOffset and byteLength, and Node pools small allocations: a 400-byte
payload sits at offset 8 inside an 8 KiB pool, so a clip under ~1024 samples
decoded as 2048 samples of unrelated memory — and the empty-result guard could
not see it. The reader has the mirror-image fix: a float data chunk on an odd
boundary (ffmpeg's pcm_f32le writes fmt(18) + fact, landing `data` at 58) now
copies instead of throwing RangeError on an unaligned view.
The tail limitation is now stated rather than mis-stated: the context is exactly
as long as the input, so a reverb or delay still ringing is cut there. The old
comment claimed the opposite. How far a tail may run past a clip's end changes
the clip's length in the mix, so it is a product decision, not one to make here.
Co-Authored-By: Claude Opus 5 (1M context)
* fix(producer): report an FX render failure as an audio error
`processCompositionAudio` reports per-track failures in its result, but an FX
failure it cannot degrade past — a browser that will not launch, a chain that
will not build — rejects instead. `runAudioStage` had no try, so that rejection
escaped to the orchestrator as an unclassified pipeline exception, losing the
stage/owner/retryable classification this stage exists to attach, and skipping
its abort check on the way out.
It now lands in `audioError` alongside every other cause, while an abort still
keeps its own shape rather than being reported as an audio problem.
Not done here: committing the generated `audio-fx-runtime-inline.ts` so a fresh
clone typechecks packages/engine without building first. The bundle is built from
the stub, and the stub changes three times across this stack — so the artifact
differs per branch and would conflict on every restack. Its model,
position-edits-render-inline.ts, is committed only because it is stable. Building
before testing is this monorepo's existing contract (studio's tests need core's
dist too), so the gap is not specific to audio FX and is better closed by a build
ordering gate than by committing a per-branch artifact.
Co-Authored-By: Claude Opus 5 (1M context)
* test(engine): skip the browser FX render cases when there is no browser
CI's `Test` job was red on this PR with four failures, all the same cause:
Failed to launch the browser process: spawn
/home/runner/.cache/hyperframes/chrome/chrome-headless-shell
The job installs ffmpeg and no browser, deliberately — every other suite
that needs an external binary already guards on it
(`describe.skipIf(!HAS_FFMPEG)`). These cases were the only ones assuming
a Chrome, so they failed on an absent dependency rather than on anything
about the code.
Guards on `resolveHeadlessShellPath()` — the same resolver
`acquireBrowser` launches through, so the check cannot drift from the
thing it guards the way a hard-coded cache path would. A configured path
that does not exist throws; that is caught and read as "cannot run here".
Checked both directions rather than just the green one: with a browser all
11 cases run and pass, and with `HYPERFRAMES_BROWSER_PATH` pointed at a
missing binary exactly 3 skip and the other 8 still run. A guard that
silently skipped everything would have looked identical in CI.
They keep their value where it exists — every developer machine, and any
job that has run `hyperframes browser ensure`.
Not touched: the CodeQL failure on this PR is a run from 2026-08-07, five
days and several force-pushes stale. None of the 17 open repo alerts are
in files this PR changes; it re-runs on this push.
* chore(engine): suppress the temp-file alert with the reason it is safe
CodeQL flags `writeWav`'s `writeFileSync` as js/insecure-temporary-file
(high) — the one new alert on #3021, and the reason its CodeQL check is
red.
It is a false positive, and the comment says why rather than just silencing
it: `path` is always inside a directory made by `mkdtempSync`, never a
name assembled directly under `tmpdir()`. Both callers are covered — the
browser host page writes into `mkdtempSync(join(tmpdir(), "hf-fx-host-"))`,
and the render output goes to the producer work dir, itself
`mkdtempSync(join(tempRoot, "producer-project-"))`. mkdtemp picks the
random suffix and creates the directory 0700 in one syscall, so the
predictable filename inside it cannot be pre-created or symlinked by
another user, which is the attack the rule is about. The analyzer sees the
dataflow reach `tmpdir()` and not the mkdtemp in between.
Suppressed inline rather than dismissed in the UI, so the justification
lives next to the code and the rule stays live for anything added later in
this file. Matches the repo's existing convention — `planV2.ts:222`
carries an `lgtm[js/insecure-temporary-file]` for a different reason on
the same rule.
Correcting myself: I first reported this alert as not real, having
intersected the PR's files against the default-branch alert list, which
does not contain PR-ref alerts. Querying ?ref=refs/pull/3021/merge returns
it straight away.
* feat(core): register the audio-fx-rack canary at 0%
Lands the rollout switch dark, per the registry's own procedure: "Start at
percentage: 0 and merge that — a canary at 0 is dead code you can land
safely and ramp without a code review."
Declared at the bottom of the stack so every branch above can read it. The
gate itself goes in at wa-4-fx-panel, where the rack first appears.
Scope is deliberate and stated in the description: it gates the AUTHORING
surface only. A composition that already carries `data-fx-chain` still
plays and renders it. A canary should stage who can REACH a feature, not
make an attribute somebody already wrote silently inert — an agent that
writes a chain through the skill would otherwise produce a file whose audio
processing vanishes with no error.
* feat(studio): audio FX panel generated from the registry
Controls for the whole chain: add, remove, reorder, bypass, and every knob each
effect declares.
Nothing in the panel knows what a compressor is. The registry supplies each
parameter's range, step, unit and scale and the panel renders what it finds, so
adding an effect or a knob upstream needs no change here, and the panel cannot
offer a value the renderer would reject — a typed-in figure is clamped into the
declared range on the way through.
Frequency and time controls span three or four decades, so those declare a log
scale and the slider maps exponentially; a linear slider would spend most of
its travel somewhere useless.
Reorder is a first-class control because chain order changes the sound: a
reverb before a compressor is not the same as after.
Carve gets its own block rather than an entry in the add menu, with a picker
for the voice track to listen to. It processes this track based on another one,
which is how a sidechain control works — it lives on the track that changes,
and names the source.
* feat(studio): show the Audio FX section on audio tracks
Adds `audioFx` to the editing-affordances contract and renders the FX panel in
the inspector when an `` element is selected.
The section is audio-only. A `` carries its sound on a separate
`` element, so an FX chain on the video would have nothing to process.
Chain and carve settings are written straight back onto the element as
serialised attributes, the way colour grading carries its config, so
persistence is an ordinary attribute write and needs no new server route. A
chain that cannot be parsed renders as empty rather than breaking the panel,
and the attribute is left untouched until the user changes something.
The collapsed group summarises what is on the track ("2 effects + carve") so
the state is visible without expanding it.
Wired into PropertyPanelFlat rather than PropertyPanel: STUDIO_FLAT_INSPECTOR_ENABLED
defaults to true, so the flat inspector is what actually renders.
* refactor(studio): lift audioFxSummary out of PropertyPanelFlat
`PropertyPanelFlat.tsx` is 612 lines here against the repo's 600-line cap,
so the required File size check is red — the sole reason this PR is
blocked. The review says as much: "mechanical fix (~5 min), not a design
problem. Code itself is LGTM."
Moves `audioFxSummary` to `audioFxSummary.ts`, the same file a later
branch creates for it. Deliberately the smallest cut that clears the cap
rather than the whole `AudioFxGroup` extraction: every later commit in the
stack edits AudioFxGroup, so moving it here would collide with each of
them, while almost nothing touches this function.
595 lines.
* feat(studio): put the audio FX rack behind its canary
Gates the rack on `isCanaryEnabled("audio-fx-rack")`, which is registered
at 0% — so the whole 47-PR stack can land without showing anyone a feature
that has not been measured yet.
The gate sits on the AUTHORING surface and nowhere else. The runtime and
the render still honour a `data-fx-chain` already on an element, so a
composition written through the skill or by `carve.mjs` keeps its
processing rather than going silently dry for anyone outside the cohort. A
canary should stage who can REACH a feature, not make an attribute somebody
already wrote stop working with no error.
Gated at the panel rather than in `resolveEditingSections`: the affordance
resolver is a pure function in core describing what an element CAN support,
and rollout state is not a property of an `` tag.
Pinned the 0% with a test, and checked it fails at 25 — a ramp should have
to break something that says "this ships dark" out loud.
One gap, stated rather than papered over: the gate itself has no unit test.
I wrote one and deleted it, because `PropertyPanel.test.tsx`'s harness
never renders the Audio FX group for its audio fixture even with the gate
removed — so the test passed for the wrong reason in the off case and could
not pass at all in the on case. A test that cannot fail for the right
reason is worse than none. Verifying the gate needs the panel harness to
mount that section first, which is its own change.
* feat(core,studio): hear the FX chain in preview, and run the carve analysis
Splices an element's FX chain into the playback graph so preview stops being
silent about effects, and wires the carve button that was previously inert.
The chain goes between the decoded source and its gain stage: effects see the
raw signal and volume automation rides on their output, matching the order the
offline render uses. Since preview and render call the same graph builders,
what is heard while scrubbing is what gets written.
The splice lives in the transport rather than on the `` element. The
transport plays each track from a decoded AudioBuffer and mutes the element to
avoid doubling, so capturing the element with createMediaElementSource would
have processed a stream nothing is listening to — it looked like it worked
because the call succeeded, and the audio was unchanged.
A chain that cannot be built plays dry rather than silencing the track, which
is the right failure in preview: the author keeps working and hears the source.
The render still refuses, because shipping the dry signal there would be wrong.
Carve now analyses for real: it decodes the chosen voice track, ranks its bands
and writes the resulting peaking filters onto this track. Generated nodes are
tagged `fromCarve`, so re-running replaces the previous carve instead of
stacking another set on top of hand-added effects.
Known limitation: the graph is built when a source is scheduled, so a knob
turned mid-playback takes effect on the next play or seek rather than
immediately. Live re-parameterisation needs the transport to hold the handle
and forward updates.
* fix(studio,core): stop parameter drags from restarting playback
Dragging a knob wrote the chain through the persisting attribute path on every
input event. That path refreshes the preview, which reloads the composition and
reschedules audio — so a single drag reloaded dozens of times and playback
stuttered the whole way.
Drags now go through `onSetAttributeLive`, the same path colour grading uses for
scrubs: it coalesces undo entries and sets `skipRefresh`, so no reload happens.
The persisting write fires once, when the gesture ends — pointer-up or blur for
a slider, Enter or blur for a typed value. A select commits immediately since
there is no drag to wait for.
While dragging, the control is driven from local state. Waiting for the value to
round-trip through the element attribute made the knob lag behind the pointer.
For the change to be audible without a reload, the graph now follows the
attribute: the chain installed by the transport observes the element and
re-parameterises itself in place, so a value change lands on the next
128-sample quantum. A shape change (effect added, bypassed, pole count) cannot
be patched into a running graph, so it still waits for the next schedule rather
than cutting the audio mid-play.
The regression test drags a slider through several values and asserts the
persisting handler is untouched until release.
* fix(core): register FX worklets before building nodes that need them
An AudioWorkletNode cannot be constructed before its processor is registered —
it throws, and the surrounding chain is lost with it. `attachElementFxChain`
built the chain first and only then called `ensureAudioFxWorklets`, so every
worklet-backed effect (compressor, limiter, gate, bitcrush) threw on
construction and the track fell back to dry. Instrumenting the preview showed
`hf-compressor: InvalidStateError` with addModule never called at all.
When the module has not landed yet the track now plays dry and the graph is
swapped in once registration resolves, so the effect arrives a moment late
instead of never.
Registration is also tracked per context rather than in one module-level
promise. A processor registered on one AudioContext does not exist on another,
so the shared promise made every context after the first believe it was ready
when it was not — the studio's transport owns its own context, which is exactly
that case.
With the worklets actually running, the compressor's per-sample log10 and pow
became real audio-thread work. Samples below the knee have a gain of exactly
unity and need neither, so the envelope is now compared in the linear domain
and the transcendentals only run for samples that are actually being
compressed.
* refactor(studio): split the FX node row out of FxSection
Clears the health findings the FX stack left behind: the chain-node render
callback was a 70-line closure over half of FxSection's state, and the two
reorder arrows were the same button written twice.
Also drops two exports with no consumers, and registers the audio FX runtime
stub as an entry point — it is bundled by file path, so nothing imports it.
Co-Authored-By: Claude Opus 5 (1M context)
* refactor(studio): lift the audio FX group out of PropertyPanelFlat
`PropertyPanelFlat.tsx` was 672 lines against the repo's 600-line cap, so
the required File size check was red — the sole reason #3014 and #3022 are
blocked. Both reviews say the same thing: "mechanical fix, not a design
problem. Code itself is LGTM."
Moves `AudioFxGroup` and `audioFxSummary` into
`propertyPanelAudioFxGroup.tsx`, which is where a later branch puts them
anyway — done here so the file is under the cap from the point it first
crosses it, rather than ten branches later.
533 lines now. The four audio imports it no longer needs go with it.
Not fixed here: three `FxSection carve` tests fail on this branch with
"Cannot read properties of undefined (reading 'toFixed')". Confirmed
pre-existing by stashing this change and re-running — that is the separate
`Test` failure the review also flags.
* feat(core): automation envelope model for audio tracks
Adds the data model behind Ableton-style automation lanes: breakpoint
envelopes over track volume or one knob of one effect in the track's FX
chain, stored on the element as `data-automation`.
Times are clip-local, so an envelope travels with the clip when it moves —
the clip-envelope model rather than arrangement automation.
`sampleAutomationLane` is the single interpolator. The lane drawing, the
preview scheduler and the render bake all call it, so the picture and the
sound cannot disagree about the curve. Log-scaled parameters interpolate in
log space, matching what their own knob already promises.
FX nodes gain a stable `id`, minted by count rather than randomly so the
document is the same on every machine. Lanes address nodes by id, so
reordering a chain never re-points a lane at a different effect, and a lane
whose effect was deleted is dropped rather than left to reattach.
Also warns when a track carries both a volume lane and a GSAP volume tween,
since only the lane is heard and the tween silently does nothing.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(core): expose the AudioParams behind automatable FX knobs
Marks the knobs an automation lane can drive and has each graph builder hand
back the AudioParam behind them, so a scheduler can write to a running effect
without knowing what the effect is.
A knob is not always one AudioParam. A wet/dry mix is two gains moving in
opposition, and a knob in milliseconds drives a delay time in seconds, so
each target carries the mapping out of the knob's own declared unit.
What stays unautomatable is stated where it is decided: a WaveShaper curve, a
convolution impulse and a one-pole filter's coefficients are all rebuilt
wholesale rather than scheduled, and the four worklet effects take values by
postMessage rather than through AudioParams.
The registry flag is written by hand, so a test builds every effect and
checks the exposure both ways — nothing flagged is missing, nothing exposed
is unflagged. A flag that lied would offer a lane that silently did nothing.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(core): play automation envelopes in preview
Schedules each lane onto the AudioParams behind its knob using native ramps
and value curves. Nothing evaluates the envelope per frame: it is handed to
the audio thread once, so it stays sample-accurate however busy the main
thread is, and the offline render will schedule it the same way.
Timing comes from the transport, so an envelope survives seeking into the
middle of a clip, a clip that has not started yet, and a playback rate that
compresses clip seconds into context seconds.
A straight line is only scheduled as a ramp when nothing bends it — no
curvature, a linear parameter scale, and no unit mapping. Log-scaled
parameters and mapped ones are sampled instead, since a delay knob in
milliseconds and a wet/dry pair moving in opposition are not linear in the
parameter they drive.
Lanes with nowhere to write are skipped rather than reported: a one-pole
filter exposes no frequency param, and the worklet effects expose none at
all. Editing an envelope mid-playback re-aims it at the live playhead rather
than restarting the track.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(engine): bake automation envelopes into the render
The offline render schedules FX lanes with the same scheduler preview uses,
inside the OfflineAudioContext that already runs the same graph builders. The
input WAV is the clip's own audio from its first sample, so clip-local time
is offline time and the envelope needs no offset.
Volume lanes take the existing PCM bake rather than a second mechanism: the
lane is converted to keyframes, so a straight fade stays two of them and only
a bent segment is sampled — the baker interpolates linearly and would
otherwise quietly straighten the curve. A volume lane supersedes keyframes
probed from the timeline, which `lint` already warns about.
A browser test sweeps a lowpass from below a 2 kHz tone to well above it and
measures both ends. Parsing the envelope is not the same as scheduling it,
and only running the real thing tells the two apart.
Co-Authored-By: Claude Opus 5 (1M context)
* fix(core): make the volume lane audible in preview
The envelope was scheduled onto the transport's gain AudioParam, but the
runtime rewrites that gain every tick from `data-volume` and the GSAP-seeked
value — so it was erased within a frame. Volume automation was correct in the
render and inaudible while previewing.
The lane now feeds the per-tick path where the probed volume keyframes already
sit, checked ahead of them so the two cannot fight, and the transport no
longer schedules volume at all: one mechanism instead of two racing.
The cost is honest — in preview the level steps per tick rather than per
sample, exactly as the existing keyframe path does. The render still bakes it
into the PCM sample-accurately, and FX parameters are still scheduled on their
own AudioParams, since nothing rewrites those.
Parsed lanes are cached by attribute text: the runtime asks once per tick per
track, and parsing there would run the JSON parser 60 times a second for a
value that only changes on an edit.
Co-Authored-By: Claude Opus 5 (1M context)
* fix(core): apply chain edits to the running graph
A structural edit — an effect added, removed, bypassed, or a filter's pole
count switched — was dropped. `buildFxChain`'s update reports false when the
change is not merely new values, and the attribute observer ignored that, so
the edit only took hold when the persisting write reloaded the composition.
That reload restarted every playing track, which is what was heard as the
audio chopping.
The graph is now swapped in place: the old effects are detached, the new ones
built and connected between the same source and gain, and any lanes
re-scheduled onto the new nodes. The source node is never touched, so playback
does not restart.
A track with no chain is watched too, rather than wired through and forgotten,
so adding its first effect is heard the same way. That means the function
always returns a disposer instead of null for the empty case.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(studio): the geometry and plumbing behind automation lanes
Everything an automation lane needs before there is a lane to look at, kept
apart from the component so the maths can be read and tested without a pointer.
`automationLaneGeometry` is pure: which parameters a clip can automate (its
fader, then each automatable knob of each effect that carries a node id), how a
value maps to a position in the lane, and how a lane is edited. Two decisions
live here and are worth review:
- A log-read knob maps on its own log scale, so the middle of a 100 Hz–20 kHz
lane is the geometric mean. Dragging and drawing then agree with what the
knob's own scale already promises.
- `withLane` replaces a lane in place rather than appending. A lane with no
explicitly chosen parameter shows whichever comes first, so moving the edited
one to the end would switch the lane out from under the pointer on the first
edit.
`automationLaneData` parses the two attributes, cached by their text so the
identity only changes when the text does — the lane holds an optimistic draft
while a point is dragged and compares against that identity, and a fresh object
on every playhead tick would throw the drag away. It binds automation to the
chain the way preview and the render bind it, so a lane whose effect was deleted
is dropped rather than drawn against the wrong axis.
`useAutomationLanes` routes edits through the DOM edit session, targeting the
selected element because that is what the attribute commit path writes to.
Row height reserves each lane at its own height rather than counting it as
another keyframe lane, and `TimelinePropertyLanes` gains a footer slot so the
lanes share the keyframe disclosure — and its `aria-controls`.
`TimelineElement` moves to its own module: playerStore had reached the 600-line
studio ceiling exactly and could not carry another field. It is re-exported from
there, so no importer changes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
* fix(studio): make automationLaneData reviewable, and evict one entry not all
The cache key held a literal NUL byte instead of its escape, so git classified
the whole module as binary: it landed as `Bin 0 -> 2677 bytes` with zero
diffable lines, invisible to review, to grep, and to any textual merge. The
escape is behaviour-identical.
With the file readable, two things in it needed fixing.
Eviction cleared the entire map. Clearing changes the identity of every lane's
automation at once, and a lane compares its drag draft against that identity —
so one unrelated element arriving at the limit would release an in-progress drag
and snap the point back. It now drops the oldest entry, and a hit is re-inserted
so it counts as recently used.
Nothing tested this module, which is what let the binary blob through. Now
covered: identity stability, re-parsing when the chain changes but the
automation text does not, a hot entry surviving 40 evictions, and an unreadable
attribute reading as nothing.
The geometry module's exports are ignored for dead-code while its consumer sits
one PR upstack, following the convention already used for the fast-capture
stack.
Co-Authored-By: Claude Opus 5 (1M context)
* fix(studio): carry the audio FX attributes onto every timeline row
Both element builders read `data-fx-chain` and `data-automation` off the host
element, and an expanded sub-composition child is built without one — so an audio
track inside a sub-composition reserved no automation height and drew no lanes,
while the property panel, which reads the live DOM selection rather than the row,
still showed its chain and its toggles. `hostElementState` exists to re-inherit
exactly this class of host-only field; it now covers these two alongside
`hidden`, `timelineLocked` and `timelineRole`.
`parseTimelineFromDOM` had the same gap and now reads both directly.
Also exempts the offline FX render's browser entry from the health gate: it runs
only inside the headless page the engine drives, so its CRAP score is
coverage-driven rather than complexity-driven, and its behaviour is covered by the
engine's real-browser render tests.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(studio): the automation lane itself
Draws each automated parameter as its own lane under the audio clip, on the same
disclosure caret the keyframe lanes use — that caret is the DAW automation
triangle. One lane per parameter rather than a selector to swap between them, so
two envelopes can be read and edited without hiding either.
Double-click the line to add a point, drag to shape it, right-click a point to
remove it.
Three things here took more than one attempt, and the comments say why:
- **A dragged point did not move.** The live write deliberately skips the preview
refresh — that is what keeps dragging from restarting playback — so the stored
value does not move under the pointer. The lane keeps a local draft.
- **Releasing snapped it back.** The draft was dropped when the drag ended, which
is before the persisted write comes around; it now lives until the automation
it was drawn over actually changes.
- **A press was eaten.** Not stopping propagation let the timeline start its own
gesture and swallow the second half of a double-click. The lane owns the press
once it is live — and when it is not, it selects its clip instead, since lanes
sit below the clip bar where the timeline's own selection handler never sees
them.
The envelope is inset by the grab radius so a point at the clip's first or last
frame is drawn whole rather than half outside the lane, and clip time still lines
up with screen position because the inset and the offset cancel.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
* fix(studio): let a track disclose its automation without a tween
The lane was mounted inside the property-lanes wrapper, which renders only for a
track's GSAP keyframe clip — so an audio clip with no tween resolved to nothing:
no disclosure caret, no reserved height, no lanes. Verified on a composition with
one ``, an envelope, and no tweens anywhere: 0 carets, 0 lanes. The
attribute still wrote and the render still baked it, so the feature failed
silently for exactly the tracks it exists for. Same composition now: 1 caret, and
expanding it draws the Volume lane.
Automation counts as something to disclose. `resolveTrackKeyframeClip` takes a
counter alongside the keyframe lane counts and qualifies a clip on either; the
header asks the same counter about the clip it already holds. A function rather
than another map threaded through the props: every caller then reads one cached
parse, so the height a row reserves and the lanes drawn in it cannot drift apart.
That drift is also fixed for the lane's own offset, which passed the raw tween
count where every other consumer uses distinct property groups. Two tweens on one
property drew one keyframe lane but pushed the automation lane down by two,
spilling into the next track; one tween on two properties did the inverse and
drew it over a diamond lane, stealing its pointer events. It now reads the same
`laneCounts` map the reserved height and the drawn lanes use.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(studio): automate a parameter without reloading the preview
The write path and the volume half of the panel surface.
**A commit that persists without reloading.** For attributes the runtime applies
to the live graph itself — an FX chain, its automation — a reload would only
interrupt playback to reach the state the preview already has. `skipRefresh` and
`refreshAfter` were already independent options; this exposes the combination
that skips the reload but still re-reads the selection.
Both halves are needed, and they were fighting each other. Without the reload,
audio no longer chops on an edit. Without the resync, the panel keeps reading the
selection snapshot it was built with, so a second edit computes from a pre-edit
value and appears to do nothing — deleting one effect made every later delete a
no-op. `handleDomAttributeLiveCommit` is untouched and still used for knob
dragging, where a per-move re-render is exactly what you do not want.
**Volume.** An automated track's slider is disabled, since a level set there
would be overwritten by the envelope on the next tick, and the toggle beside it
adds or deletes the lane. Adding seeds it with a single point at the level the
slider already shows, so automating a track never changes how loud it is.
**One shared reader** for both panel sections, which is what surfaced that
resolving against an absent chain would have deleted every FX lane the moment
someone automated a volume: the volume section does not parse the chain, so
"no chain" now means "do not resolve" rather than "drop what cannot be resolved".
The toggle itself lives with the FX controls it is shared with, and says
`Automated` / `Automate` through the studio's own Tooltip rather than a native
browser hover.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
* fix(studio): stop the last two automation writes reloading the preview
The quiet commit added here was only used by the FX group. Two writers still went
through the refreshing one, so they reloaded the preview and restarted every
playing track — the exact chop the live write during a drag exists to avoid:
- releasing a dragged breakpoint, so the audio hitched at the end of every point
you moved;
- clicking the volume toggle, while the same click on an effect parameter was
already silent.
Both are quiet now: still persisted, still resyncing the selection so a following
edit computes from the value just written.
Also fixes the seeded volume. `Number(dataAttributes.volume ?? "1")` is 0 for an
attribute that is present but empty, so automating such a track started its lane
at silence while the engine read the same empty value as unity.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(studio): automate and un-automate each effect parameter
The per-parameter surface in the FX panel.
An automated parameter's control is disabled — a value typed there would be
overwritten by the envelope on the next tick, so the lane is the value now — and
the toggle beside it adds or deletes that parameter's lane. Adding seeds the lane
with a single point at the value the control already holds, so switching to an
envelope never changes the sound, only where the value comes from.
Parameters no envelope can drive have no toggle at all: the worklet-backed
dynamics expose no AudioParams, a WaveShaper's curve and a convolution impulse
are rebuilt wholesale rather than scheduled. Neither does a chain node with no
id, since a lane addresses nodes by id — so adding an effect now mints one.
Carve moves onto the same non-reloading write, and decodes its source in an
`OfflineAudioContext`: opening a second output device mid-playback makes the
running track glitch while the hardware is reconfigured. Turning carve off now
also drops the filters it generated, which otherwise kept dipping the bed with
nothing in the panel to explain it.
`AudioFxGroup` moves into its own module — PropertyPanelFlat was at its size
budget — which also gave the panel's write behaviour somewhere to be tested: what
it writes, seeded at the current value, preserving the lanes it is not touching,
and clearing the attribute when the last one goes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
* feat(studio): only offer voiceover carve when there is a voice to carve against
Carve is a relationship between two tracks — it analyses another track's voice
and dips this bed where that voice sits. In a composition with a single audio
track there is nothing to listen to, so the block offered an empty source picker
and an Analyse button that could never do anything.
It is now shown only when the composition holds another audio track, and still
shown when carve is already configured: hiding a live setting because its voice
track was removed would leave the bed being dipped from out of sight.
Co-Authored-By: Claude Opus 5 (1M context)
* test(studio): cover carve visibility through the real element
The panel derives carve's source list from the selected element's document, so
a selection with no element has no sources — which the new visibility rule
correctly reads as 'nothing to carve against'. The suite mounted exactly that,
so it was asserting on a hidden block.
Selections now carry a real with a sibling track, and the two cases the
rule exists for are pinned directly.
Co-Authored-By: Claude Opus 5 (1M context)
* fix(studio): keep FX panel writes from clobbering each other
Three writes in the audio panel each read the source file, mutate one
attribute and write it back. Fired without ordering they read the same
content and the last one lands, dropping the others.
- Deleting an effect left its automation lanes in the attribute. Ids are
minted lowest-free, so the next effect added took the same id and
inherited the dead envelope: disabled and "Automated" without the
author ever automating it, and baked into the render.
- Switching carve off wrote the chain (dropping the filters it generated)
and the carve settings at once, so either the filters stayed with no
carve to explain them or the settings survived with no filters.
- The three carve dials committed per input event, patching the source
and resyncing the selection dozens of times per drag. They now preview
live and persist on release, like the FX knobs already do.
Volume automation reads through the quiet commit too, so removing a lane
resyncs the panel instead of leaving the slider disabled.
* feat(engine): let an FX tail decay instead of cutting it at the clip
The offline render ended at the last input sample, so a reverb or a delay
was still ringing when the context stopped. Measured on a 1.5 s tone
through a default reverb, the render cut at 1.524 s while the tail was
still at -29.7 dB — an audible chop, and the one place the render did not
match preview.
The length does not have to be guessed. Every tail here follows from its
own settings: a convolution is exactly as long as its impulse, and
`synthesizeReverbImpulse` derives that from room size; a delay's repeats
fall by `feedback` every `time`, so the count down to -60 dB is a log.
Everything else settles with its input — an all-pass chain has group
delay, not a tail, and a 9-second compressor release has no signal to
release once the clip stops.
`chainTailSeconds` sums them (the chain is serial, so a delay in front of
a reverb hands each repeat to the room), reads a lane's maximum rather
than the static knob where one is automated, and caps at 5 s — 5 s
between repeats at 0.95 feedback is eleven minutes of decay, and the
panel can dial exactly that.
The mixer's per-track atrim now allows the clip plus its tail; the atrim
after apad still holds every track to the composition's length, so a tail
can run over what follows but never extends the video.
Same fixture after: a smooth decay to -72 dB, last non-zero sample at
3.306 s against the 3.4 s the settings predict.
* feat(studio): curve, snap and type a value in an automation lane
Four gestures from Ableton's envelope editor, which is the muscle memory
an automation lane inherits.
Alt-drag the line between two breakpoints to bend it, Alt-double-click to
straighten. `curve` was already honoured everywhere it is read — drawn in
the lane, sampled in preview, baked into the render through
setValueCurveAtTime — with no gesture anywhere that could set it, so every
envelope anyone could draw was linear in practice. The curve is solved,
not accumulated (x^e = f, so e = ln f / ln x), which keeps the segment
under the pointer instead of drifting away over a long drag; the test
asserts that by sampling with the renderer's own sampler.
Shift locks a drag to one axis and fines the vertical travel to a quarter.
Which axis won is decided in pixels — seconds and dB are not comparable
numbers, and comparing them would make the lock depend on the zoom.
A dragged point snaps to the beat grid and to its neighbouring points,
with Alt to ignore it. The radius is tight on purpose: a lane is often a
few seconds wide, where a generous radius makes a point unplaceable
between two beats.
Double-click a point to type its value. -6.0 dB is not a pixel you can
find, and there was no way to enter one.
The gesture layer moves to useAutomationLaneGestures and the path builder
to envelopePath: the component was at the studio's 600-line ceiling, and
both are worth testing without a render. trackShowsBeatStrip comes out of
TimelineLanes for the same reason.
* feat(studio): pure range ops for automation lane selections
Add pointsIn() and replaceRange() functions for managing automation envelope
edits within a time range. The key invariant: envelope values outside the
selection never move. Implemented by anchoring the boundaries at t0 and t1
by sampling the original lane, so cutting middle sections cannot reshape
the rest. Inner points from shape generators can suppress redundant anchors
at merge distance.
* fix(studio): budget replaceRange's inner points before capping, not after
* feat(studio): automation selection slice
* feat(studio): drag-select a time range on an automation lane
Dragging on an automation lane's empty background now arms a range
selection, snapped to the beat grid and clamped to the lane duration; a
sub-3px drag counts as a click and clears instead. Point drags and
Alt-drag segment bends still take priority, since the range arm only
runs where the existing point/segment hit-test already returned null.
useAutomationLanes binds the selection slice per element/lane so the
rect renders from the store, matching the read pattern the writes
already use.
* feat(studio): delete an automation selection from the keyboard
Escape clears the active automation-lane time selection; Delete/Backspace
empties it via replaceRange(..., inner: []), which pins anchor points at
both edges and leaves the envelope outside the selection untouched. Mounted
in TimelineLanes.tsx next to the useAutomationLanes() call that already
lives there. Also adds a stale-selection guard in TimelineAutomationLaneSlot
that clears the selection if its lane's target stops existing on the bound
element's automation (e.g. the automated effect was deleted).
* test(studio): cover the automation selection stale-target guard
* feat(studio): ramp, swell and dip generators for automation selections
* fix(studio): let an automation range keep Delete from the clip
useAppHotkeys listens on window/capture, so it runs before
useAutomationSelectionKeyboard's document/capture handler. With a range
selected, Delete fell straight through to the clip-delete branch and
destroyed the whole audio clip the lane belongs to; Backspace hit the
reset-keyframes branch on the way and wiped the clip's keyframes.
Guard both by returning early when automationSelection is set, mirroring
the selectedKeyframes precedent six lines above. No preventDefault: the
downstream handler still needs the key.
dispatchPlainKey is exported so the arbitration between keyframes, an
automation range and the clip can be pinned without standing up the hook.
Co-Authored-By: Claude Opus 5 (1M context)
* chore: suppress unused export for automationShapes (consumed upstack)
* feat(studio): simplify dense automation runs
Implements Ramer-Douglas-Peucker point-thinning for audio automation
lane breakpoints, working in unit space for correct log-scaled
parameter handling.
Co-Authored-By: Claude Sonnet 5
* chore: add automationSimplify to fallow complexity ignore
The Ramer-Douglas-Peucker algorithm in automationSimplify.ts has
inherent complexity (12 cyclomatic / 20 cognitive) that is by design
and not refactorable. Added to health.ignore list and ignoreExports
list since it's consumed by the UI layer one PR upstack.
Co-Authored-By: Claude Sonnet 5
* feat(studio): shape and simplify menu on an automation selection
Right-click inside an active time-selection rectangle on an automation
lane now opens a menu offering the four utility shapes (Ramp up, Ramp
down, Swell, Dip) and Simplify, composing generateShape/simplifyPoints
with pointsIn/replaceRange from the prior selection tasks. A point's own
right-click still stops propagation and deletes it, unaffected.
* feat(engine): render audio FX in an OfflineAudioContext
Reads `data-fx-chain` off an audio element and runs the chain over the trimmed
WAV before volume automation is baked in — effects should see the raw signal,
and the envelope belongs on their output.
The processing happens in an OfflineAudioContext inside the headless browser
the engine already drives, running the same graph builders the studio previews
with. That is the point of the approach: one implementation per effect, so the
render agreeing with the preview is a property of the architecture rather than
a tolerance to police. Reimplementing each effect as an FFmpeg filter would
mean two implementations to keep in step, and for the dynamics processors and
modulated delays there is no filter that behaves the same way.
`build:audio-fx-runtime` bundles the graph builders into an injectable IIFE,
following the same pattern as the existing runtime artifacts, so the browser
runs exactly the code the studio does.
The page loads from a file:// URL rather than about:blank because AudioWorklet
is only exposed in a secure context — the compressor, limiter, gate and
bitcrush processors would otherwise fail to register with an opaque error.
file:// qualifies and needs no listening socket.
The chain is serialised into the attribute the way colour grading carries its
config, so there is no side-car file to resolve or lose.
An FX failure is fatal for the whole mix rather than a per-track soft failure.
Every other audio failure mode degrades gracefully — the track drops, siblings
continue — but substituting the dry signal for a processed one ships a render
that sounds plausible and is not what the author set up. Since the per-element
work races under Promise.all, an internal AbortController chained off the
caller's signal aborts in-flight siblings before workDir is removed.
* feat(core): voiceover carve analysis
Finds the bands a voice occupies so a music bed can be dipped there, letting
the voice sit in front without ducking the whole track.
Carve is a relationship between two tracks rather than an effect on one, so it
stays out of the FX chain. What it emits is an ordinary chain of peaking
filters, so a carve composes with whatever else is on the track and needs no
separate rendering path.
Selection is weighted toward intelligibility rather than raw voice energy.
Ranking purely by power lands on the fundamental almost every time, because
that is where a voice is loudest — but the masking that actually hurts a
voiceover happens higher up, and dipping 160 Hz mostly just thins the bed. The
bias is a control, not a constant: at 0 it follows raw energy, at 1 it weights
toward 1-3 kHz.
Ranking happens in dB, which matters more than it looks. Speech spreads 20-30 dB
across these bands — it falls off roughly 6 dB per octave above the fundamental
— so a weighting has to be on that scale to move anything at all. A
multiplicative weight of `1 - bias + bias * shaped` is bounded below by
`1 - bias`, capping its influence at 10*log10(1/(1 - bias)): 5.2 dB at the 0.7
default, 3 dB at 0.5. That is no influence against a real voice — every bias
short of ~0.95 would rank exactly like bias 0 and carve the fundamental, the
outcome the bias exists to prevent, while looking decisive against a fixture
whose bands sit 2 dB apart. So the bias is a dB penalty, zero at 2 kHz and worth
up to 30 dB at full strength, and relative cut depths come from a dB difference
rather than a ratio of weighted linear powers.
The bias reweights ranking without overriding the spectrum — a band the voice
has no energy in is not worth carving, and scores -Infinity rather than
competing — so a strongly low-pitched voice can still select low at full bias.
What the tests hold is that biasing never selects lower than the unbiased
ranking, that the DEFAULT bias reaches the presence region on a voice with a
realistic tilt, and that bias 0 still follows raw power exactly.
Includes a radix-2 FFT rather than a dependency; one Welch-style averaged
spectrum over third-octave bands does not justify pulling in a DSP library.
* fix(engine): keep the FX render 16-bit, stereo, and correctly sized
Three defects in the offline FX path, none of which any test could see.
**Float output silently disabled sample-accurate volume automation.** The writer
emitted 32-bit IEEE float; the very next mixer step bakes the volume envelope
into the samples and accepts only 16-bit PCM, returning null otherwise. So
enabling any effect downgraded that track to the ffmpeg expression path — capped
at 32 straight segments, quantising a curved envelope, and on a dense one falling
back to base volume. It now writes 16-bit PCM, clamped rather than wrapped so a
limiter at 0 dB or a resonant filter cannot turn overshoot into a click. A test
asserts the baker accepts the writer's own output and actually fades it.
**Everything was folded to mono.** `prepareAudioTrack` goes out of its way to
emit stereo — its pan filter exists to dodge ffmpeg's 3 dB mono-to-stereo
rematrix — and this folded it, then wrote one channel. So adding a single peaking
EQ collapsed a bed's width and cost ~3 dB in the render, while preview stayed
stereo. Channels now travel as one plane each, through an OfflineAudioContext of
the same width, and come back interleaved.
**Small results decoded the wrong length.** `new Float32Array(buf.buffer)`
discards byteOffset and byteLength, and Node pools small allocations: a 400-byte
payload sits at offset 8 inside an 8 KiB pool, so a clip under ~1024 samples
decoded as 2048 samples of unrelated memory — and the empty-result guard could
not see it. The reader has the mirror-image fix: a float data chunk on an odd
boundary (ffmpeg's pcm_f32le writes fmt(18) + fact, landing `data` at 58) now
copies instead of throwing RangeError on an unaligned view.
The tail limitation is now stated rather than mis-stated: the context is exactly
as long as the input, so a reverb or delay still ringing is cut there. The old
comment claimed the opposite. How far a tail may run past a clip's end changes
the clip's length in the mix, so it is a product decision, not one to make here.
Co-Authored-By: Claude Opus 5 (1M context)
* fix(producer): report an FX render failure as an audio error
`processCompositionAudio` reports per-track failures in its result, but an FX
failure it cannot degrade past — a browser that will not launch, a chain that
will not build — rejects instead. `runAudioStage` had no try, so that rejection
escaped to the orchestrator as an unclassified pipeline exception, losing the
stage/owner/retryable classification this stage exists to attach, and skipping
its abort check on the way out.
It now lands in `audioError` alongside every other cause, while an abort still
keeps its own shape rather than being reported as an audio problem.
Not done here: committing the generated `audio-fx-runtime-inline.ts` so a fresh
clone typechecks packages/engine without building first. The bundle is built from
the stub, and the stub changes three times across this stack — so the artifact
differs per branch and would conflict on every restack. Its model,
position-edits-render-inline.ts, is committed only because it is stable. Building
before testing is this monorepo's existing contract (studio's tests need core's
dist too), so the gap is not specific to audio FX and is better closed by a build
ordering gate than by committing a per-branch artifact.
Co-Authored-By: Claude Opus 5 (1M context)
* test(engine): skip the browser FX render cases when there is no browser
CI's `Test` job was red on this PR with four failures, all the same cause:
Failed to launch the browser process: spawn
/home/runner/.cache/hyperframes/chrome/chrome-headless-shell
The job installs ffmpeg and no browser, deliberately — every other suite
that needs an external binary already guards on it
(`describe.skipIf(!HAS_FFMPEG)`). These cases were the only ones assuming
a Chrome, so they failed on an absent dependency rather than on anything
about the code.
Guards on `resolveHeadlessShellPath()` — the same resolver
`acquireBrowser` launches through, so the check cannot drift from the
thing it guards the way a hard-coded cache path would. A configured path
that does not exist throws; that is caught and read as "cannot run here".
Checked both directions rather than just the green one: with a browser all
11 cases run and pass, and with `HYPERFRAMES_BROWSER_PATH` pointed at a
missing binary exactly 3 skip and the other 8 still run. A guard that
silently skipped everything would have looked identical in CI.
They keep their value where it exists — every developer machine, and any
job that has run `hyperframes browser ensure`.
Not touched: the CodeQL failure on this PR is a run from 2026-08-07, five
days and several force-pushes stale. None of the 17 open repo alerts are
in files this PR changes; it re-runs on this push.
* chore(engine): suppress the temp-file alert with the reason it is safe
CodeQL flags `writeWav`'s `writeFileSync` as js/insecure-temporary-file
(high) — the one new alert on #3021, and the reason its CodeQL check is
red.
It is a false positive, and the comment says why rather than just silencing
it: `path` is always inside a directory made by `mkdtempSync`, never a
name assembled directly under `tmpdir()`. Both callers are covered — the
browser host page writes into `mkdtempSync(join(tmpdir(), "hf-fx-host-"))`,
and the render output goes to the producer work dir, itself
`mkdtempSync(join(tempRoot, "producer-project-"))`. mkdtemp picks the
random suffix and creates the directory 0700 in one syscall, so the
predictable filename inside it cannot be pre-created or symlinked by
another user, which is the attack the rule is about. The analyzer sees the
dataflow reach `tmpdir()` and not the mkdtemp in between.
Suppressed inline rather than dismissed in the UI, so the justification
lives next to the code and the rule stays live for anything added later in
this file. Matches the repo's existing convention — `planV2.ts:222`
carries an `lgtm[js/insecure-temporary-file]` for a different reason on
the same rule.
Correcting myself: I first reported this alert as not real, having
intersected the PR's files against the default-branch alert list, which
does not contain PR-ref alerts. Querying ?ref=refs/pull/3021/merge returns
it straight away.
* test(engine): probe ffmpeg and Chrome instead of assuming them
Two failures on #3021's Test job, both about the environment rather than
the code under test.
**Bare `ffmpeg` is not on PATH in CI.** The 16-bit fixture shelled out to
`execFileSync("ffmpeg", ...)` and died with ENOENT. The job does provide
ffmpeg, through `prepare-ffmpeg-bin`, which is what `getFfmpegBinary()`
resolves — every other ffmpeg-dependent suite in this package already goes
through it. Now this one does too, and the case is `skipIf(!HAS_FFMPEG)`
so a contributor without ffmpeg skips rather than fails.
**The browser guard trusted the wrong thing.** It asked
`resolveHeadlessShellPath()` and treated a returned path as "a browser is
here". CI's cache holds a chrome-headless-shell that resolves and then
fails to spawn — a partial download is indistinguishable from a working
one by `existsSync`, which is all that resolver checks. So the three
browser cases ran anyway and failed on the launch.
It now runs `--version` and requires exit 0, which is the same probe the
ffmpeg suites use: ask the binary, do not infer from the filesystem.
Checked both directions rather than just the green one. With a working
browser all 11 cases run and pass; with `HYPERFRAMES_BROWSER_PATH` pointed
at a binary that exits non-zero — CI's exact situation — exactly 3 skip
and the other 8 still run. A guard that quietly skipped everything would
have looked identical on the CI summary.
* feat(core): register the audio-fx-rack canary at 0%
Lands the rollout switch dark, per the registry's own procedure: "Start at
percentage: 0 and merge that — a canary at 0 is dead code you can land
safely and ramp without a code review."
Declared at the bottom of the stack so every branch above can read it. The
gate itself goes in at wa-4-fx-panel, where the rack first appears.
Scope is deliberate and stated in the description: it gates the AUTHORING
surface only. A composition that already carries `data-fx-chain` still
plays and renders it. A canary should stage who can REACH a feature, not
make an attribute somebody already wrote silently inert — an agent that
writes a chain through the skill would otherwise produce a file whose audio
processing vanishes with no error.
* feat(studio): audio FX panel generated from the registry
Controls for the whole chain: add, remove, reorder, bypass, and every knob each
effect declares.
Nothing in the panel knows what a compressor is. The registry supplies each
parameter's range, step, unit and scale and the panel renders what it finds, so
adding an effect or a knob upstream needs no change here, and the panel cannot
offer a value the renderer would reject — a typed-in figure is clamped into the
declared range on the way through.
Frequency and time controls span three or four decades, so those declare a log
scale and the slider maps exponentially; a linear slider would spend most of
its travel somewhere useless.
Reorder is a first-class control because chain order changes the sound: a
reverb before a compressor is not the same as after.
Carve gets its own block rather than an entry in the add menu, with a picker
for the voice track to listen to. It processes this track based on another one,
which is how a sidechain control works — it lives on the track that changes,
and names the source.
* feat(studio): show the Audio FX section on audio tracks
Adds `audioFx` to the editing-affordances contract and renders the FX panel in
the inspector when an `` element is selected.
The section is audio-only. A `` carries its sound on a separate
`` element, so an FX chain on the video would have nothing to process.
Chain and carve settings are written straight back onto the element as
serialised attributes, the way colour grading carries its config, so
persistence is an ordinary attribute write and needs no new server route. A
chain that cannot be parsed renders as empty rather than breaking the panel,
and the attribute is left untouched until the user changes something.
The collapsed group summarises what is on the track ("2 effects + carve") so
the state is visible without expanding it.
Wired into PropertyPanelFlat rather than PropertyPanel: STUDIO_FLAT_INSPECTOR_ENABLED
defaults to true, so the flat inspector is what actually renders.
* refactor(studio): lift audioFxSummary out of PropertyPanelFlat
`PropertyPanelFlat.tsx` is 612 lines here against the repo's 600-line cap,
so the required File size check is red — the sole reason this PR is
blocked. The review says as much: "mechanical fix (~5 min), not a design
problem. Code itself is LGTM."
Moves `audioFxSummary` to `audioFxSummary.ts`, the same file a later
branch creates for it. Deliberately the smallest cut that clears the cap
rather than the whole `AudioFxGroup` extraction: every later commit in the
stack edits AudioFxGroup, so moving it here would collide with each of
them, while almost nothing touches this function.
595 lines.
* feat(core,studio): hear the FX chain in preview, and run the carve analysis
Splices an element's FX chain into the playback graph so preview stops being
silent about effects, and wires the carve button that was previously inert.
The chain goes between the decoded source and its gain stage: effects see the
raw signal and volume automation rides on their output, matching the order the
offline render uses. Since preview and render call the same graph builders,
what is heard while scrubbing is what gets written.
The splice lives in the transport rather than on the `` element. The
transport plays each track from a decoded AudioBuffer and mutes the element to
avoid doubling, so capturing the element with createMediaElementSource would
have processed a stream nothing is listening to — it looked like it worked
because the call succeeded, and the audio was unchanged.
A chain that cannot be built plays dry rather than silencing the track, which
is the right failure in preview: the author keeps working and hears the source.
The render still refuses, because shipping the dry signal there would be wrong.
Carve now analyses for real: it decodes the chosen voice track, ranks its bands
and writes the resulting peaking filters onto this track. Generated nodes are
tagged `fromCarve`, so re-running replaces the previous carve instead of
stacking another set on top of hand-added effects.
Known limitation: the graph is built when a source is scheduled, so a knob
turned mid-playback takes effect on the next play or seek rather than
immediately. Live re-parameterisation needs the transport to hold the handle
and forward updates.
* fix(studio,core): stop parameter drags from restarting playback
Dragging a knob wrote the chain through the persisting attribute path on every
input event. That path refreshes the preview, which reloads the composition and
reschedules audio — so a single drag reloaded dozens of times and playback
stuttered the whole way.
Drags now go through `onSetAttributeLive`, the same path colour grading uses for
scrubs: it coalesces undo entries and sets `skipRefresh`, so no reload happens.
The persisting write fires once, when the gesture ends — pointer-up or blur for
a slider, Enter or blur for a typed value. A select commits immediately since
there is no drag to wait for.
While dragging, the control is driven from local state. Waiting for the value to
round-trip through the element attribute made the knob lag behind the pointer.
For the change to be audible without a reload, the graph now follows the
attribute: the chain installed by the transport observes the element and
re-parameterises itself in place, so a value change lands on the next
128-sample quantum. A shape change (effect added, bypassed, pole count) cannot
be patched into a running graph, so it still waits for the next schedule rather
than cutting the audio mid-play.
The regression test drags a slider through several values and asserts the
persisting handler is untouched until release.
* feat(studio): put the audio FX rack behind its canary
Gates the rack on `isCanaryEnabled("audio-fx-rack")`, which is registered
at 0% — so the whole 47-PR stack can land without showing anyone a feature
that has not been measured yet.
The gate sits on the AUTHORING surface and nowhere else. The runtime and
the render still honour a `data-fx-chain` already on an element, so a
composition written through the skill or by `carve.mjs` keeps its
processing rather than going silently dry for anyone outside the cohort. A
canary should stage who can REACH a feature, not make an attribute somebody
already wrote stop working with no error.
Gated at the panel rather than in `resolveEditingSections`: the affordance
resolver is a pure function in core describing what an element CAN support,
and rollout state is not a property of an `` tag.
Pinned the 0% with a test, and checked it fails at 25 — a ramp should have
to break something that says "this ships dark" out loud.
One gap, stated rather than papered over: the gate itself has no unit test.
I wrote one and deleted it, because `PropertyPanel.test.tsx`'s harness
never renders the Audio FX group for its audio fixture even with the gate
removed — so the test passed for the wrong reason in the off case and could
not pass at all in the on case. A test that cannot fail for the right
reason is worse than none. Verifying the gate needs the panel harness to
mount that section first, which is its own change.
* fix(core): register FX worklets before building nodes that need them
An AudioWorkletNode cannot be constructed before its processor is registered —
it throws, and the surrounding chain is lost with it. `attachElementFxChain`
built the chain first and only then called `ensureAudioFxWorklets`, so every
worklet-backed effect (compressor, limiter, gate, bitcrush) threw on
construction and the track fell back to dry. Instrumenting the preview showed
`hf-compressor: InvalidStateError` with addModule never called at all.
When the module has not landed yet the track now plays dry and the graph is
swapped in once registration resolves, so the effect arrives a moment late
instead of never.
Registration is also tracked per context rather than in one module-level
promise. A processor registered on one AudioContext does not exist on another,
so the shared promise made every context after the first believe it was ready
when it was not — the studio's transport owns its own context, which is exactly
that case.
With the worklets actually running, the compressor's per-sample log10 and pow
became real audio-thread work. Samples below the knee have a gain of exactly
unity and need neither, so the envelope is now compared in the linear domain
and the transcendentals only run for samples that are actually being
compressed.
* refactor(studio): split the FX node row out of FxSection
Clears the health findings the FX stack left behind: the chain-node render
callback was a 70-line closure over half of FxSection's state, and the two
reorder arrows were the same button written twice.
Also drops two exports with no consumers, and registers the audio FX runtime
stub as an entry point — it is bundled by file path, so nothing imports it.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(core): automation envelope model for audio tracks
Adds the data model behind Ableton-style automation lanes: breakpoint
envelopes over track volume or one knob of one effect in the track's FX
chain, stored on the element as `data-automation`.
Times are clip-local, so an envelope travels with the clip when it moves —
the clip-envelope model rather than arrangement automation.
`sampleAutomationLane` is the single interpolator. The lane drawing, the
preview scheduler and the render bake all call it, so the picture and the
sound cannot disagree about the curve. Log-scaled parameters interpolate in
log space, matching what their own knob already promises.
FX nodes gain a stable `id`, minted by count rather than randomly so the
document is the same on every machine. Lanes address nodes by id, so
reordering a chain never re-points a lane at a different effect, and a lane
whose effect was deleted is dropped rather than left to reattach.
Also warns when a track carries both a volume lane and a GSAP volume tween,
since only the lane is heard and the tween silently does nothing.
Co-Authored-By: Claude Opus 5 (1M context)
* refactor(studio): lift the audio FX group out of PropertyPanelFlat
`PropertyPanelFlat.tsx` was 672 lines against the repo's 600-line cap, so
the required File size check was red — the sole reason #3014 and #3022 are
blocked. Both reviews say the same thing: "mechanical fix, not a design
problem. Code itself is LGTM."
Moves `AudioFxGroup` and `audioFxSummary` into
`propertyPanelAudioFxGroup.tsx`, which is where a later branch puts them
anyway — done here so the file is under the cap from the point it first
crosses it, rather than ten branches later.
533 lines now. The four audio imports it no longer needs go with it.
Not fixed here: three `FxSection carve` tests fail on this branch with
"Cannot read properties of undefined (reading 'toFixed')". Confirmed
pre-existing by stashing this change and re-running — that is the separate
`Test` failure the review also flags.
* feat(core): expose the AudioParams behind automatable FX knobs
Marks the knobs an automation lane can drive and has each graph builder hand
back the AudioParam behind them, so a scheduler can write to a running effect
without knowing what the effect is.
A knob is not always one AudioParam. A wet/dry mix is two gains moving in
opposition, and a knob in milliseconds drives a delay time in seconds, so
each target carries the mapping out of the knob's own declared unit.
What stays unautomatable is stated where it is decided: a WaveShaper curve, a
convolution impulse and a one-pole filter's coefficients are all rebuilt
wholesale rather than scheduled, and the four worklet effects take values by
postMessage rather than through AudioParams.
The registry flag is written by hand, so a test builds every effect and
checks the exposure both ways — nothing flagged is missing, nothing exposed
is unflagged. A flag that lied would offer a lane that silently did nothing.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(core): play automation envelopes in preview
Schedules each lane onto the AudioParams behind its knob using native ramps
and value curves. Nothing evaluates the envelope per frame: it is handed to
the audio thread once, so it stays sample-accurate however busy the main
thread is, and the offline render will schedule it the same way.
Timing comes from the transport, so an envelope survives seeking into the
middle of a clip, a clip that has not started yet, and a playback rate that
compresses clip seconds into context seconds.
A straight line is only scheduled as a ramp when nothing bends it — no
curvature, a linear parameter scale, and no unit mapping. Log-scaled
parameters and mapped ones are sampled instead, since a delay knob in
milliseconds and a wet/dry pair moving in opposition are not linear in the
parameter they drive.
Lanes with nowhere to write are skipped rather than reported: a one-pole
filter exposes no frequency param, and the worklet effects expose none at
all. Editing an envelope mid-playback re-aims it at the live playhead rather
than restarting the track.
Co-Authored-By: Claude Opus 5 (1M context)
* fix(core): make the volume lane audible in preview
The envelope was scheduled onto the transport's gain AudioParam, but the
runtime rewrites that gain every tick from `data-volume` and the GSAP-seeked
value — so it was erased within a frame. Volume automation was correct in the
render and inaudible while previewing.
The lane now feeds the per-tick path where the probed volume keyframes already
sit, checked ahead of them so the two cannot fight, and the transport no
longer schedules volume at all: one mechanism instead of two racing.
The cost is honest — in preview the level steps per tick rather than per
sample, exactly as the existing keyframe path does. The render still bakes it
into the PCM sample-accurately, and FX parameters are still scheduled on their
own AudioParams, since nothing rewrites those.
Parsed lanes are cached by attribute text: the runtime asks once per tick per
track, and parsing there would run the JSON parser 60 times a second for a
value that only changes on an edit.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(engine): bake automation envelopes into the render
The offline render schedules FX lanes with the same scheduler preview uses,
inside the OfflineAudioContext that already runs the same graph builders. The
input WAV is the clip's own audio from its first sample, so clip-local time
is offline time and the envelope needs no offset.
Volume lanes take the existing PCM bake rather than a second mechanism: the
lane is converted to keyframes, so a straight fade stays two of them and only
a bent segment is sampled — the baker interpolates linearly and would
otherwise quietly straighten the curve. A volume lane supersedes keyframes
probed from the timeline, which `lint` already warns about.
A browser test sweeps a lowpass from below a 2 kHz tone to well above it and
measures both ends. Parsing the envelope is not the same as scheduling it,
and only running the real thing tells the two apart.
Co-Authored-By: Claude Opus 5 (1M context)
* fix(core): apply chain edits to the running graph
A structural edit — an effect added, removed, bypassed, or a filter's pole
count switched — was dropped. `buildFxChain`'s update reports false when the
change is not merely new values, and the attribute observer ignored that, so
the edit only took hold when the persisting write reloaded the composition.
That reload restarted every playing track, which is what was heard as the
audio chopping.
The graph is now swapped in place: the old effects are detached, the new ones
built and connected between the same source and gain, and any lanes
re-scheduled onto the new nodes. The source node is never touched, so playback
does not restart.
A track with no chain is watched too, rather than wired through and forgotten,
so adding its first effect is heard the same way. That means the function
always returns a disposer instead of null for the empty case.
Co-Authored-By: Claude Opus 5 (1M context)
* fix(studio): drop the FX panel's dead __testables export
Fallow audit flagged it — no test imports the module.
* fix(core,studio): clear the remaining Fallow audit findings on the FX panel
- Split FxSection's per-node row into FxNodeRow + FxNodeControls so the
CRAP score (31.6, threshold 30) splits across two smaller units instead
of moving wholesale with one extraction.
- Dedupe the repeated "open the add menu, read its items" block in
propertyPanelFxSection.test.tsx into openAddMenuItems().
- Merge build-audio-fx-runtime.ts and build-position-edits-render.ts into
one build-inline-artifact.ts, config-selected by CLI arg — the two
scripts were a byte-for-byte clone save for names.
- Exempt canary.test.ts's rawFnv (a deliberate independent
reimplementation used to cross-check canaryBucket, per its own
docstring) and the property-panel test files' shared renderInto/mount
scaffolding (pre-existing across 9 files, 2 outside this stack) in
.fallowrc.jsonc, consistent with this file's existing exemptions for
the same class of intentional/pre-existing duplication.
* fix(ci): allowlist the build-script consolidation in the no-main-deletions guard
build-audio-fx-runtime.ts and build-position-edits-render.ts were merged into
build-inline-artifact.ts to kill a fallow duplication finding; the deletion
guard flagged that as an accidental loss since main still has both originals.
* fix(core): dedupe the wet/dry mix math between delayFeedback and chorusLfo
Both effect builders set wet.gain to the mix and dry.gain to its complement
in identical two-line blocks; fallow kept re-flagging it as a 10-line clone
on every unrelated change. Extracted setWetDryMix.
* fix(core): remove the build-audio-fx-runtime.ts stray resurrected by a main merge
An earlier merge with main brought this deleted file back (git's merge/delete
handling on an unchanged-on-one-side file); package.json already points at
build-inline-artifact.ts, so it sat unreachable and duplicating that file's
config, both of which fallow flagged.
* fix(studio): pull TimelineLanes under the 600-line cap
TimelineLanes.tsx hit 620 lines. Extracted the three per-clip pointer
gestures (resize-start, pointer-down move-arm, click/razor-split) into
createClipGestureHandlers — one factory call per rendered clip instead of
~120 lines of inline handler bodies in the render loop. 529 lines now.
* fix(studio): split the extracted pointerdown handler under the CRAP threshold
Moving the ~120-line gesture logic into timelineClipGestureHandlers.ts
concentrated it into two functions fallow flagged (onPointerDown at CRAP
63.6, onResizeStart at 31.6). Split the decision logic (which gesture a
pointerdown implies) into a pure resolvePointerDownAction, then split
its own intent-blocking check into isIntentBlocked. onResizeStart's guard
moved into canStartResize. Every function now scores under 30.
* fix(studio): drop the unused DomEditSelection import in PropertyPanelFlat
CI caught it on PR #3026 (wa-12-panel-params); a later refactor in the
stack removed the last use of the type here without removing the import.
---------
Co-authored-by: Claude Opus 5 (1M context)
---
.fallowrc.jsonc | 21 +++++
.../components/AutomationSelectionMenu.tsx | 68 +++++++++++++++
.../TimelineAutomationLane.test.tsx | 37 +++++++++
.../components/TimelineAutomationLane.tsx | 63 +++++++++++++-
.../components/automationShapes.test.ts | 82 +++++++++++++++++++
.../src/player/components/automationShapes.ts | 70 ++++++++++++++++
.../components/automationSimplify.test.ts | 48 +++++++++++
.../player/components/automationSimplify.ts | 51 ++++++++++++
8 files changed, 439 insertions(+), 1 deletion(-)
create mode 100644 packages/studio/src/player/components/AutomationSelectionMenu.tsx
create mode 100644 packages/studio/src/player/components/automationShapes.test.ts
create mode 100644 packages/studio/src/player/components/automationShapes.ts
create mode 100644 packages/studio/src/player/components/automationSimplify.test.ts
create mode 100644 packages/studio/src/player/components/automationSimplify.ts
diff --git a/.fallowrc.jsonc b/.fallowrc.jsonc
index e63222559e..3a29f215bf 100644
--- a/.fallowrc.jsonc
+++ b/.fallowrc.jsonc
@@ -176,6 +176,22 @@
"withLane",
],
},
+ // automationShapes is part of the audio-automation stack: its consumer is
+ // the UI layer that uses shape generators one PR upstack, so a per-PR audit
+ // diffing against the merge base sees these as unused. Consumed for real once
+ // the stack merges; safe to drop this entry then.
+ {
+ "file": "packages/studio/src/player/components/automationShapes.ts",
+ "exports": ["AUTOMATION_SHAPES"],
+ },
+ // automationSimplify is part of the audio-automation stack: its consumer is
+ // the UI layer one PR upstack, so a per-PR audit diffing against the merge
+ // base sees these as unused. Consumed for real once the stack merges; safe
+ // to drop this entry then.
+ {
+ "file": "packages/studio/src/player/components/automationSimplify.ts",
+ "exports": ["simplifyPoints"],
+ },
// propertyPanelAutomation is the shared reader for both panel sections; the
// FX group that consumes these two lands one PR upstack, so a per-PR audit
// against the merge base sees them as unused.
@@ -747,6 +763,11 @@
"packages/parsers/src/gsapParser.ts",
// htmlParser.ts has pre-existing complexity (moved from packages/core).
"packages/parsers/src/htmlParser.ts",
+ // automationSimplify.ts: Ramer–Douglas–Peucker algorithm inherently requires
+ // nested loops and stack-based control flow (12 cyclomatic / 20 cognitive);
+ // this complexity is by design and not refactorable. Consumed by the UI
+ // layer one PR upstack in the audio-automation feature stack.
+ "packages/studio/src/player/components/automationSimplify.ts",
// studio-server files: pre-existing complexity (moved from packages/core/src/studio-api/).
// files.ts: executeGsapMutationRecast/Acorn are CRITICAL; excluded as files.ts
// was already in health.ignore at the old path (packages/core/src/studio-api/routes/files.ts).
diff --git a/packages/studio/src/player/components/AutomationSelectionMenu.tsx b/packages/studio/src/player/components/AutomationSelectionMenu.tsx
new file mode 100644
index 0000000000..4a2bd0d057
--- /dev/null
+++ b/packages/studio/src/player/components/AutomationSelectionMenu.tsx
@@ -0,0 +1,68 @@
+/**
+ * Context menu for a right-click inside an automation time selection: the four
+ * utility shapes, then Simplify. Portal + dismiss handling mirror
+ * TrackGapContextMenu; rows never vanish — an inapplicable Simplify dims with
+ * a reason instead of leaving a shorter menu.
+ */
+import { memo } from "react";
+import { createPortal } from "react-dom";
+import { useContextMenuDismiss } from "../../hooks/useContextMenuDismiss";
+import { AUTOMATION_SHAPES, type AutomationShapeId } from "./automationShapes";
+
+interface AutomationSelectionMenuProps {
+ x: number;
+ y: number;
+ onClose(): void;
+ onInsertShape(shape: AutomationShapeId): void;
+ onSimplify(): void;
+ /** At least three points in the range — fewer has nothing to thin. */
+ canSimplify: boolean;
+}
+
+export const AutomationSelectionMenu = memo(function AutomationSelectionMenu({
+ x,
+ y,
+ onClose,
+ onInsertShape,
+ onSimplify,
+ canSimplify,
+}: AutomationSelectionMenuProps) {
+ const menuRef = useContextMenuDismiss(onClose);
+ const row =
+ "block w-full px-2 py-1 text-left text-[11px] text-panel-text-1 hover:bg-panel-bg-3 disabled:opacity-40";
+ return createPortal(
+
+ {AUTOMATION_SHAPES.map((shape) => (
+
{
+ onInsertShape(shape.id);
+ onClose();
+ }}
+ >
+ {shape.label}
+
+ ))}
+
+
{
+ onSimplify();
+ onClose();
+ }}
+ >
+ Simplify
+
+
,
+ document.body,
+ );
+});
diff --git a/packages/studio/src/player/components/TimelineAutomationLane.test.tsx b/packages/studio/src/player/components/TimelineAutomationLane.test.tsx
index 1ae4bca663..c84a019201 100644
--- a/packages/studio/src/player/components/TimelineAutomationLane.test.tsx
+++ b/packages/studio/src/player/components/TimelineAutomationLane.test.tsx
@@ -649,3 +649,40 @@ describe("TimelineAutomationLane range selection", () => {
expect(props.onCommit).toHaveBeenCalled();
});
});
+
+describe("TimelineAutomationLane selection menu", () => {
+ it("right-click inside the selection opens the shape menu", () => {
+ const { container, svg } = mount(ramp, { rangeSelection: { t0: 1, t1: 3 } });
+ fire(svg, "contextmenu", at(2, 0.5));
+ expect(document.querySelector(".hf-automation-menu")).not.toBeNull();
+ // The menu portals to document.body, outside `container` — dismiss it via
+ // Escape before tearing down, or it leaks into the next test's DOM query.
+ const escape = new Event("keydown", { bubbles: true, cancelable: true });
+ Object.assign(escape, { key: "Escape" });
+ act(() => {
+ document.dispatchEvent(escape);
+ });
+ expect(document.querySelector(".hf-automation-menu")).toBeNull();
+ act(() => container.remove());
+ });
+
+ it("inserting a swell replaces the range and commits once", () => {
+ const { svg, props } = mount(ramp, { rangeSelection: { t0: 1, t1: 3 } });
+ fire(svg, "contextmenu", at(2, 0.5));
+ const swell = Array.from(
+ document.querySelectorAll(".hf-automation-menu button"),
+ ).find((b) => b.textContent === "Swell");
+ expect(swell).toBeTruthy();
+ act(() => swell?.click());
+ expect(props.onCommit).toHaveBeenCalledTimes(1);
+ const points =
+ (props.onCommit.mock.calls.at(-1)?.[0] as HfAutomation | undefined)?.lanes[0]?.points ?? [];
+ expect(points.some((p) => p.t === 2 && p.v === 1)).toBe(true); // peak at range.max
+ });
+
+ it("right-click outside the selection does not open it", () => {
+ const { svg } = mount(ramp, { rangeSelection: { t0: 1, t1: 3 } });
+ fire(svg, "contextmenu", at(3.8, 0.5));
+ expect(document.querySelector(".hf-automation-menu")).toBeNull();
+ });
+});
diff --git a/packages/studio/src/player/components/TimelineAutomationLane.tsx b/packages/studio/src/player/components/TimelineAutomationLane.tsx
index eeaf53895e..835c8111c5 100644
--- a/packages/studio/src/player/components/TimelineAutomationLane.tsx
+++ b/packages/studio/src/player/components/TimelineAutomationLane.tsx
@@ -14,7 +14,14 @@
* same principle the property panel's controls follow.
*/
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+ useCallback,
+ useEffect,
+ useMemo,
+ useRef,
+ useState,
+ type MouseEvent as ReactMouseEvent,
+} from "react";
import {
resolveAutomationRange,
sampleAutomationLane,
@@ -34,7 +41,11 @@ import {
} from "./automationLaneGeometry";
import { useAutomationLaneGestures } from "./useAutomationLaneGestures";
import { AutomationValueInput } from "./AutomationValueInput";
+import { AutomationSelectionMenu } from "./AutomationSelectionMenu";
import { AUTOMATION_LANE_H } from "./automationLaneHeight";
+import { generateShape, type AutomationShapeId } from "./automationShapes";
+import { simplifyPoints } from "./automationSimplify";
+import { pointsIn, replaceRange } from "./automationLaneSelection";
import { getTimelineLaneTop } from "./timelineLayout";
import type { TimelineElement } from "../store/playerStore";
import type { UseAutomationLanesResult } from "./useAutomationLanes";
@@ -207,6 +218,44 @@ export function TimelineAutomationLane({
[lane, commitPoints, readOnly],
);
+ /** Client-coordinate position of an open selection menu, or null when closed. */
+ const [menuAt, setMenuAt] = useState<{ x: number; y: number } | null>(null);
+
+ const insertShape = useCallback(
+ (shape: AutomationShapeId): void => {
+ if (!rangeSelection) return;
+ const inner = generateShape({
+ shape,
+ lane,
+ range,
+ t0: rangeSelection.t0,
+ t1: rangeSelection.t1,
+ });
+ commitPoints(replaceRange({ lane, range, ...rangeSelection, inner }), true);
+ },
+ [rangeSelection, lane, range, commitPoints],
+ );
+
+ const simplifySelection = useCallback((): void => {
+ if (!rangeSelection) return;
+ const inner = simplifyPoints(pointsIn(lane, rangeSelection.t0, rangeSelection.t1), range);
+ commitPoints(replaceRange({ lane, range, ...rangeSelection, inner }), true);
+ }, [rangeSelection, lane, range, commitPoints]);
+
+ // A point's own right-click already stops propagation and still deletes;
+ // this only fires when the press lands on the background inside the
+ // active selection.
+ const onSvgContextMenu = useCallback(
+ (e: ReactMouseEvent): void => {
+ if (readOnly || !rangeSelection) return;
+ const { t } = pointAt(e.clientX, e.clientY);
+ if (t < rangeSelection.t0 || t > rangeSelection.t1) return;
+ e.preventDefault();
+ setMenuAt({ x: e.clientX, y: e.clientY });
+ },
+ [readOnly, rangeSelection, pointAt],
+ );
+
const currentValue =
lane.points.length > 0 && playheadSec !== null
? sampleAutomationLane(lane, playheadSec, range.scale)
@@ -247,6 +296,7 @@ export function TimelineAutomationLane({
onPointerUp={gestures.endDrag}
onPointerCancel={gestures.endDrag}
onDoubleClick={gestures.onDoubleClick}
+ onContextMenu={onSvgContextMenu}
role="group"
aria-label={`${range.label} automation`}
>
@@ -347,6 +397,17 @@ export function TimelineAutomationLane({
{hint}
) : null}
+
+ {menuAt && rangeSelection ? (
+ setMenuAt(null)}
+ onInsertShape={insertShape}
+ onSimplify={simplifySelection}
+ canSimplify={pointsIn(lane, rangeSelection.t0, rangeSelection.t1).length >= 3}
+ />
+ ) : null}
);
}
diff --git a/packages/studio/src/player/components/automationShapes.test.ts b/packages/studio/src/player/components/automationShapes.test.ts
new file mode 100644
index 0000000000..398fd95625
--- /dev/null
+++ b/packages/studio/src/player/components/automationShapes.test.ts
@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import { generateShape } from "./automationShapes";
+import { resolveAutomationRange, VOLUME_RANGE } from "@hyperframes/core/audio-automation";
+import type { HfAutomationLane } from "@hyperframes/core/audio-automation";
+
+const flat: HfAutomationLane = {
+ target: "volume",
+ points: [
+ { t: 0, v: 0.8 },
+ { t: 6, v: 0.8 },
+ ],
+};
+
+describe("generateShape", () => {
+ it("ramp-up fades in from the floor to the envelope's own value", () => {
+ const pts = generateShape({ shape: "ramp-up", lane: flat, range: VOLUME_RANGE, t0: 1, t1: 3 });
+ expect(pts).toEqual([
+ { t: 1, v: VOLUME_RANGE.min },
+ { t: 3, v: 0.8 },
+ ]);
+ });
+
+ it("ramp-down fades out from the envelope's own value", () => {
+ const pts = generateShape({
+ shape: "ramp-down",
+ lane: flat,
+ range: VOLUME_RANGE,
+ t0: 1,
+ t1: 3,
+ });
+ expect(pts).toEqual([
+ { t: 1, v: 0.8 },
+ { t: 3, v: VOLUME_RANGE.min },
+ ]);
+ });
+
+ it("swell peaks at range max mid-selection, smoothed", () => {
+ const pts = generateShape({ shape: "swell", lane: flat, range: VOLUME_RANGE, t0: 1, t1: 3 });
+ expect(pts).toHaveLength(3);
+ expect(pts[1]).toMatchObject({ t: 2, v: VOLUME_RANGE.max });
+ expect(pts[0]?.curve).toBeDefined(); // eased, not a triangle
+ });
+
+ it("dip ducks to a quarter of the edge value in unit space", () => {
+ const pts = generateShape({ shape: "dip", lane: flat, range: VOLUME_RANGE, t0: 1, t1: 3 });
+ // volume is linear 0..1: unit(0.8) = 0.8, floor = 0.2
+ expect(pts[1]?.v).toBeCloseTo(0.2, 5);
+ });
+
+ it("computes in unit space on a log lane", () => {
+ const range = resolveAutomationRange("fx.n1.frequency", {
+ version: 1,
+ nodes: [{ type: "lowpass", id: "n1", params: {} }],
+ });
+ expect(range?.scale).toBe("log");
+ if (!range) return;
+ const lane: HfAutomationLane = {
+ target: "fx.n1.frequency",
+ points: [
+ { t: 0, v: 2000 },
+ { t: 6, v: 2000 },
+ ],
+ };
+ const pts = generateShape({ shape: "dip", lane, range, t0: 1, t1: 3 });
+ const floor = pts[1]?.v ?? 0;
+ // A quarter of the way up the LOG axis, not 500 Hz.
+ expect(floor).toBeGreaterThan(range.min);
+ expect(floor).toBeLessThan(2000 * 0.25);
+ });
+
+ it("uses the range default when the lane is empty", () => {
+ const empty: HfAutomationLane = { target: "volume", points: [] };
+ const pts = generateShape({
+ shape: "ramp-down",
+ lane: empty,
+ range: VOLUME_RANGE,
+ t0: 1,
+ t1: 3,
+ });
+ expect(pts[0]?.v).toBe(VOLUME_RANGE.default);
+ });
+});
diff --git a/packages/studio/src/player/components/automationShapes.ts b/packages/studio/src/player/components/automationShapes.ts
new file mode 100644
index 0000000000..53904e7181
--- /dev/null
+++ b/packages/studio/src/player/components/automationShapes.ts
@@ -0,0 +1,70 @@
+/**
+ * The utility shapes a video author reaches for: fade in, fade out, swell,
+ * duck. One shape scaled to the selection — this is not a DAW, nobody needs a
+ * tempo-synced LFO. Edge values come from the envelope itself so a shape
+ * splices into whatever is already there; vertical maths runs in unit space so
+ * a log knob (frequency) behaves like the lane that draws it.
+ */
+import {
+ sampleAutomationLane,
+ type AutomationRange,
+ type HfAutomationLane,
+ type HfAutomationPoint,
+} from "@hyperframes/core/audio-automation";
+import { fromUnit, toUnit } from "./automationLaneGeometry";
+
+export type AutomationShapeId = "ramp-up" | "ramp-down" | "swell" | "dip";
+
+export const AUTOMATION_SHAPES: ReadonlyArray<{ id: AutomationShapeId; label: string }> = [
+ { id: "ramp-up", label: "Ramp up" },
+ { id: "ramp-down", label: "Ramp down" },
+ { id: "swell", label: "Swell" },
+ { id: "dip", label: "Dip" },
+];
+
+/** Ease used on the segments entering/leaving a swell or dip midpoint. */
+const SMOOTH = 0.4;
+/** A dip ducks to this fraction of the edge value, in unit space. */
+const DIP_FLOOR = 0.25;
+
+function edgeValue(lane: HfAutomationLane, range: AutomationRange, t: number): number {
+ if (lane.points.length === 0) return range.default ?? (range.min + range.max) / 2;
+ return sampleAutomationLane(lane, t, range.scale);
+}
+
+export function generateShape(input: {
+ shape: AutomationShapeId;
+ lane: HfAutomationLane;
+ range: AutomationRange;
+ t0: number;
+ t1: number;
+}): HfAutomationPoint[] {
+ const { shape, lane, range, t0, t1 } = input;
+ const v0 = edgeValue(lane, range, t0);
+ const v1 = edgeValue(lane, range, t1);
+ const mid = (t0 + t1) / 2;
+ switch (shape) {
+ case "ramp-up":
+ return [
+ { t: t0, v: range.min },
+ { t: t1, v: v1 },
+ ];
+ case "ramp-down":
+ return [
+ { t: t0, v: v0 },
+ { t: t1, v: range.min },
+ ];
+ case "swell":
+ return [
+ { t: t0, v: v0, curve: SMOOTH },
+ { t: mid, v: range.max, curve: -SMOOTH },
+ { t: t1, v: v1 },
+ ];
+ case "dip":
+ return [
+ { t: t0, v: v0, curve: -SMOOTH },
+ { t: mid, v: fromUnit(range, toUnit(range, v0) * DIP_FLOOR), curve: SMOOTH },
+ { t: t1, v: v1 },
+ ];
+ }
+}
diff --git a/packages/studio/src/player/components/automationSimplify.test.ts b/packages/studio/src/player/components/automationSimplify.test.ts
new file mode 100644
index 0000000000..31878b19e0
--- /dev/null
+++ b/packages/studio/src/player/components/automationSimplify.test.ts
@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { simplifyPoints } from "./automationSimplify";
+import { VOLUME_RANGE } from "@hyperframes/core/audio-automation";
+import { toUnit } from "./automationLaneGeometry";
+import type { HfAutomationPoint } from "@hyperframes/core/audio-automation";
+
+describe("simplifyPoints", () => {
+ it("collapses collinear runs to their endpoints", () => {
+ const line: HfAutomationPoint[] = Array.from({ length: 50 }, (_, i) => ({
+ t: i * 0.1,
+ v: 1 - i * 0.01,
+ }));
+ const out = simplifyPoints(line, VOLUME_RANGE);
+ expect(out).toHaveLength(2);
+ expect(out[0]).toEqual(line[0]);
+ expect(out[out.length - 1]).toEqual(line[line.length - 1]);
+ });
+
+ it("keeps every survivor within epsilon of the original", () => {
+ const wave: HfAutomationPoint[] = Array.from({ length: 100 }, (_, i) => ({
+ t: i * 0.05,
+ v: 0.5 + 0.4 * Math.sin(i * 0.2),
+ }));
+ const out = simplifyPoints(wave, VOLUME_RANGE, 0.02);
+ expect(out.length).toBeLessThan(wave.length / 2);
+ // Every dropped point must sit within epsilon (unit space) of the
+ // simplified polyline — check by linear interpolation between survivors.
+ for (const p of wave) {
+ const rIdx = out.findIndex((q) => q.t >= p.t);
+ const b = out[rIdx] ?? out[out.length - 1];
+ const a = out[rIdx - 1] ?? b;
+ if (!a || !b) continue;
+ const span = b.t - a.t;
+ const f = span > 0 ? (p.t - a.t) / span : 0;
+ const approx =
+ toUnit(VOLUME_RANGE, a.v) + f * (toUnit(VOLUME_RANGE, b.v) - toUnit(VOLUME_RANGE, a.v));
+ expect(Math.abs(approx - toUnit(VOLUME_RANGE, p.v))).toBeLessThanOrEqual(0.021);
+ }
+ });
+
+ it("returns short inputs untouched", () => {
+ const two: HfAutomationPoint[] = [
+ { t: 0, v: 1 },
+ { t: 1, v: 0 },
+ ];
+ expect(simplifyPoints(two, VOLUME_RANGE)).toEqual(two);
+ });
+});
diff --git a/packages/studio/src/player/components/automationSimplify.ts b/packages/studio/src/player/components/automationSimplify.ts
new file mode 100644
index 0000000000..7a9ea99e32
--- /dev/null
+++ b/packages/studio/src/player/components/automationSimplify.ts
@@ -0,0 +1,51 @@
+/**
+ * Ramer–Douglas–Peucker over an envelope's points, deviation measured
+ * VERTICALLY in unit space. Vertical (not perpendicular) because an envelope
+ * is a function of time — what matters is how far the value strays, and it
+ * keeps the metric independent of the time axis' units. Exists for dense
+ * producers: carve output and heavy hand edits.
+ */
+import type { AutomationRange, HfAutomationPoint } from "@hyperframes/core/audio-automation";
+import { toUnit } from "./automationLaneGeometry";
+
+export function simplifyPoints(
+ points: HfAutomationPoint[],
+ range: AutomationRange,
+ epsilon = 0.02,
+): HfAutomationPoint[] {
+ if (points.length <= 2) return points;
+ const keep = new Array(points.length).fill(false);
+ const last = keep.length - 1;
+ keep[0] = true;
+ keep[last] = true;
+
+ const stack: Array<[number, number]> = [[0, last]];
+ while (stack.length > 0) {
+ const seg = stack.pop();
+ if (!seg) break;
+ const [a, b] = seg;
+ const pa = points[a];
+ const pb = points[b];
+ if (!pa || !pb || b - a < 2) continue;
+ const ua = toUnit(range, pa.v);
+ const ub = toUnit(range, pb.v);
+ const span = pb.t - pa.t;
+ let worst = -1;
+ let worstDev = epsilon;
+ for (let i = a + 1; i < b; i += 1) {
+ const p = points[i];
+ if (!p) continue;
+ const f = span > 0 ? (p.t - pa.t) / span : 0;
+ const dev = Math.abs(toUnit(range, p.v) - (ua + f * (ub - ua)));
+ if (dev > worstDev) {
+ worstDev = dev;
+ worst = i;
+ }
+ }
+ if (worst >= 0) {
+ keep[worst] = true;
+ stack.push([a, worst], [worst, b]);
+ }
+ }
+ return points.filter((_, i) => keep[i]);
+}
From c7c95e2f018efa961b7a5e06fb142a98fd14ecc9 Mon Sep 17 00:00:00 2001
From: Vance Ingalls
Date: Wed, 12 Aug 2026 22:09:41 -0700
Subject: [PATCH 7/7] feat(studio): copy and paste automation ranges across
lanes (#3056)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
* feat(core): audio FX registry
One declarative description of every effect that can be applied to an audio
track: fourteen across filters, dynamics, non-linear and time, each exposing
its full parameter surface rather than a curated subset.
Parameters carry the range, step, unit and scale a control needs, so a panel
can generate its UI from this rather than hard-coding a form per effect, and a
value that survives `normalizeAudioFxParams` is always safe to realise.
Everything is declared in the units a person thinks in — dB, ms, Hz.
Parsing rejects an unknown effect id rather than skipping the node. A chain
that quietly loses an effect renders something other than what was authored,
which is worse than refusing to load it.
Data only: no audio is produced here. The graph that realises each effect is
referenced by the `web` id and lands in the next change, which keeps this
module free of browser globals so the engine and the linter can import it.
* fix(core): stop declaring knobs that move nothing
Three parameters were declared with ranges, defaults and hints, and read by no
builder — dials an author could turn with no audible result.
- `chorus.decay` and `bitcrush.aa`: removed. FFmpeg's chorus feeds a decay back
into its delay line and a bitcrusher's anti-alias needs a real filter; adding
either is new DSP, not a fix, so the honest move is to stop advertising them.
- `lowshelf.q` / `highshelf.q`: removed. The Web Audio spec leaves Q unused for
shelving filters, so the control moved nothing — and because the shared Q
helper marks it automatable, an author could draw an envelope on it and hear
nothing at all.
`phaser.decay` and `gate.knee` stay: the first drives the sweep depth, and the
second is now read by the gate's processor.
A test asserts each of these directly, since the existing exposure invariant only
checks that a flagged parameter reaches an AudioParam — a parameter the node then
ignores passes it.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(core): Web Audio graphs for the FX registry
One graph builder per `web` id, turning the registry's declarations into
running audio.
Every node exposes `update`, so turning a dial re-parameterises the live graph
rather than rebuilding it: an AudioParam change lands on the next 128-sample
quantum, about 2.7 ms at 48 kHz. `buildFxChain` reports whether an update could
be applied in place — adding or bypassing an effect, or switching a filter
between one and two poles (which changes the node type from BiquadFilterNode to
IIRFilterNode), changes the graph's shape and returns false so the caller
rebuilds.
Four effects have no native node and run as AudioWorklet processors:
compressor, limiter, gate and bitcrush. The module is registered from a data:
URL rather than a blob:, because a blob inherits the page origin and is opaque
on a file:// page, where it fails with an unhelpful AbortError.
Reverb has no single node either. `synthesizeReverbImpulse` generates a tail
from the room parameters, seeded so the same room sounds the same on every
machine, and the ConvolverNode uses it.
Tests cover the wiring — which nodes get built, how they connect, parameter
application and clamping, in-place update versus rebuild, disposal — against a
fake AudioContext, since happy-dom has no Web Audio.
* fix(core): reverb level, phaser wiring, per-channel dynamics, one-pole rebuild
Four defects in the graph builders, all found by review rather than by ear.
**Reverb was unusable at its own defaults.** A ConvolverNode applies the
impulse's gain whole — the graph sets `normalize = false` so a room is
deterministic rather than browser-defined — but the impulse was raw decaying
noise. Measured L2 at the registry default (size 0.7 / damping 0.5): 46.4, or
+33.3 dB, putting the wet path ~24 dB over dry at the default `wet: 0.35`. It is
now normalised to unit energy, so the wet knob means what it says. Preview and
render both convolve this buffer, so they stayed identical throughout — equally
deafening before, equally correct now.
**Phaser in_gain/out_gain trim the signal entering and leaving the effect**, not
a wet/dry pair. Wired to the wet and dry legs, "Input" muted the dry path and
the two defaults summed to 1.14, so inserting a phaser raised the track level.
They are now input and output trims with the legs summed at unity. Its declared
waveform is also honoured: `lfo.type` was never assigned, so the default
"Triangular" was silently a sine.
**The dynamics worklets held one envelope across a channel-major loop.** The
followers advance per sample, so on stereo a 20 ms attack behaved as 10 ms, and
the right channel's gain came from an envelope that had already traversed the
left — the two ducked differently from the same input and the image pumped.
State is now per channel, as is the gate's smoothed gain and bitcrush's
sample-hold counter, which previously advanced only on the last channel and left
every earlier one frozen for a whole quantum. The gate also honours the knee it
declares instead of chattering on material sitting at the threshold.
**A one-pole filter's cutoff was swallowed in preview.** Its coefficients are
fixed at construction, so `update` cannot push a new frequency — but the shape
signature carried only type and pole count, so a cutoff change looked like a
values-only edit and went into a no-op updater. Preview kept filtering at the
old frequency while the render used the new one: a preview/render divergence in
exactly the two effects that do not use a BiquadFilterNode.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(engine): render audio FX in an OfflineAudioContext
Reads `data-fx-chain` off an audio element and runs the chain over the trimmed
WAV before volume automation is baked in — effects should see the raw signal,
and the envelope belongs on their output.
The processing happens in an OfflineAudioContext inside the headless browser
the engine already drives, running the same graph builders the studio previews
with. That is the point of the approach: one implementation per effect, so the
render agreeing with the preview is a property of the architecture rather than
a tolerance to police. Reimplementing each effect as an FFmpeg filter would
mean two implementations to keep in step, and for the dynamics processors and
modulated delays there is no filter that behaves the same way.
`build:audio-fx-runtime` bundles the graph builders into an injectable IIFE,
following the same pattern as the existing runtime artifacts, so the browser
runs exactly the code the studio does.
The page loads from a file:// URL rather than about:blank because AudioWorklet
is only exposed in a secure context — the compressor, limiter, gate and
bitcrush processors would otherwise fail to register with an opaque error.
file:// qualifies and needs no listening socket.
The chain is serialised into the attribute the way colour grading carries its
config, so there is no side-car file to resolve or lose.
An FX failure is fatal for the whole mix rather than a per-track soft failure.
Every other audio failure mode degrades gracefully — the track drops, siblings
continue — but substituting the dry signal for a processed one ships a render
that sounds plausible and is not what the author set up. Since the per-element
work races under Promise.all, an internal AbortController chained off the
caller's signal aborts in-flight siblings before workDir is removed.
* feat(core): voiceover carve analysis
Finds the bands a voice occupies so a music bed can be dipped there, letting
the voice sit in front without ducking the whole track.
Carve is a relationship between two tracks rather than an effect on one, so it
stays out of the FX chain. What it emits is an ordinary chain of peaking
filters, so a carve composes with whatever else is on the track and needs no
separate rendering path.
Selection is weighted toward intelligibility rather than raw voice energy.
Ranking purely by power lands on the fundamental almost every time, because
that is where a voice is loudest — but the masking that actually hurts a
voiceover happens higher up, and dipping 160 Hz mostly just thins the bed. The
bias is a control, not a constant: at 0 it follows raw energy, at 1 it weights
toward 1-3 kHz.
Ranking happens in dB, which matters more than it looks. Speech spreads 20-30 dB
across these bands — it falls off roughly 6 dB per octave above the fundamental
— so a weighting has to be on that scale to move anything at all. A
multiplicative weight of `1 - bias + bias * shaped` is bounded below by
`1 - bias`, capping its influence at 10*log10(1/(1 - bias)): 5.2 dB at the 0.7
default, 3 dB at 0.5. That is no influence against a real voice — every bias
short of ~0.95 would rank exactly like bias 0 and carve the fundamental, the
outcome the bias exists to prevent, while looking decisive against a fixture
whose bands sit 2 dB apart. So the bias is a dB penalty, zero at 2 kHz and worth
up to 30 dB at full strength, and relative cut depths come from a dB difference
rather than a ratio of weighted linear powers.
The bias reweights ranking without overriding the spectrum — a band the voice
has no energy in is not worth carving, and scores -Infinity rather than
competing — so a strongly low-pitched voice can still select low at full bias.
What the tests hold is that biasing never selects lower than the unbiased
ranking, that the DEFAULT bias reaches the presence region on a voice with a
realistic tilt, and that bias 0 still follows raw power exactly.
Includes a radix-2 FFT rather than a dependency; one Welch-style averaged
spectrum over third-octave bands does not justify pulling in a DSP library.
* fix(engine): keep the FX render 16-bit, stereo, and correctly sized
Three defects in the offline FX path, none of which any test could see.
**Float output silently disabled sample-accurate volume automation.** The writer
emitted 32-bit IEEE float; the very next mixer step bakes the volume envelope
into the samples and accepts only 16-bit PCM, returning null otherwise. So
enabling any effect downgraded that track to the ffmpeg expression path — capped
at 32 straight segments, quantising a curved envelope, and on a dense one falling
back to base volume. It now writes 16-bit PCM, clamped rather than wrapped so a
limiter at 0 dB or a resonant filter cannot turn overshoot into a click. A test
asserts the baker accepts the writer's own output and actually fades it.
**Everything was folded to mono.** `prepareAudioTrack` goes out of its way to
emit stereo — its pan filter exists to dodge ffmpeg's 3 dB mono-to-stereo
rematrix — and this folded it, then wrote one channel. So adding a single peaking
EQ collapsed a bed's width and cost ~3 dB in the render, while preview stayed
stereo. Channels now travel as one plane each, through an OfflineAudioContext of
the same width, and come back interleaved.
**Small results decoded the wrong length.** `new Float32Array(buf.buffer)`
discards byteOffset and byteLength, and Node pools small allocations: a 400-byte
payload sits at offset 8 inside an 8 KiB pool, so a clip under ~1024 samples
decoded as 2048 samples of unrelated memory — and the empty-result guard could
not see it. The reader has the mirror-image fix: a float data chunk on an odd
boundary (ffmpeg's pcm_f32le writes fmt(18) + fact, landing `data` at 58) now
copies instead of throwing RangeError on an unaligned view.
The tail limitation is now stated rather than mis-stated: the context is exactly
as long as the input, so a reverb or delay still ringing is cut there. The old
comment claimed the opposite. How far a tail may run past a clip's end changes
the clip's length in the mix, so it is a product decision, not one to make here.
Co-Authored-By: Claude Opus 5 (1M context)
* fix(producer): report an FX render failure as an audio error
`processCompositionAudio` reports per-track failures in its result, but an FX
failure it cannot degrade past — a browser that will not launch, a chain that
will not build — rejects instead. `runAudioStage` had no try, so that rejection
escaped to the orchestrator as an unclassified pipeline exception, losing the
stage/owner/retryable classification this stage exists to attach, and skipping
its abort check on the way out.
It now lands in `audioError` alongside every other cause, while an abort still
keeps its own shape rather than being reported as an audio problem.
Not done here: committing the generated `audio-fx-runtime-inline.ts` so a fresh
clone typechecks packages/engine without building first. The bundle is built from
the stub, and the stub changes three times across this stack — so the artifact
differs per branch and would conflict on every restack. Its model,
position-edits-render-inline.ts, is committed only because it is stable. Building
before testing is this monorepo's existing contract (studio's tests need core's
dist too), so the gap is not specific to audio FX and is better closed by a build
ordering gate than by committing a per-branch artifact.
Co-Authored-By: Claude Opus 5 (1M context)
* test(engine): skip the browser FX render cases when there is no browser
CI's `Test` job was red on this PR with four failures, all the same cause:
Failed to launch the browser process: spawn
/home/runner/.cache/hyperframes/chrome/chrome-headless-shell
The job installs ffmpeg and no browser, deliberately — every other suite
that needs an external binary already guards on it
(`describe.skipIf(!HAS_FFMPEG)`). These cases were the only ones assuming
a Chrome, so they failed on an absent dependency rather than on anything
about the code.
Guards on `resolveHeadlessShellPath()` — the same resolver
`acquireBrowser` launches through, so the check cannot drift from the
thing it guards the way a hard-coded cache path would. A configured path
that does not exist throws; that is caught and read as "cannot run here".
Checked both directions rather than just the green one: with a browser all
11 cases run and pass, and with `HYPERFRAMES_BROWSER_PATH` pointed at a
missing binary exactly 3 skip and the other 8 still run. A guard that
silently skipped everything would have looked identical in CI.
They keep their value where it exists — every developer machine, and any
job that has run `hyperframes browser ensure`.
Not touched: the CodeQL failure on this PR is a run from 2026-08-07, five
days and several force-pushes stale. None of the 17 open repo alerts are
in files this PR changes; it re-runs on this push.
* chore(engine): suppress the temp-file alert with the reason it is safe
CodeQL flags `writeWav`'s `writeFileSync` as js/insecure-temporary-file
(high) — the one new alert on #3021, and the reason its CodeQL check is
red.
It is a false positive, and the comment says why rather than just silencing
it: `path` is always inside a directory made by `mkdtempSync`, never a
name assembled directly under `tmpdir()`. Both callers are covered — the
browser host page writes into `mkdtempSync(join(tmpdir(), "hf-fx-host-"))`,
and the render output goes to the producer work dir, itself
`mkdtempSync(join(tempRoot, "producer-project-"))`. mkdtemp picks the
random suffix and creates the directory 0700 in one syscall, so the
predictable filename inside it cannot be pre-created or symlinked by
another user, which is the attack the rule is about. The analyzer sees the
dataflow reach `tmpdir()` and not the mkdtemp in between.
Suppressed inline rather than dismissed in the UI, so the justification
lives next to the code and the rule stays live for anything added later in
this file. Matches the repo's existing convention — `planV2.ts:222`
carries an `lgtm[js/insecure-temporary-file]` for a different reason on
the same rule.
Correcting myself: I first reported this alert as not real, having
intersected the PR's files against the default-branch alert list, which
does not contain PR-ref alerts. Querying ?ref=refs/pull/3021/merge returns
it straight away.
* feat(core): register the audio-fx-rack canary at 0%
Lands the rollout switch dark, per the registry's own procedure: "Start at
percentage: 0 and merge that — a canary at 0 is dead code you can land
safely and ramp without a code review."
Declared at the bottom of the stack so every branch above can read it. The
gate itself goes in at wa-4-fx-panel, where the rack first appears.
Scope is deliberate and stated in the description: it gates the AUTHORING
surface only. A composition that already carries `data-fx-chain` still
plays and renders it. A canary should stage who can REACH a feature, not
make an attribute somebody already wrote silently inert — an agent that
writes a chain through the skill would otherwise produce a file whose audio
processing vanishes with no error.
* feat(studio): audio FX panel generated from the registry
Controls for the whole chain: add, remove, reorder, bypass, and every knob each
effect declares.
Nothing in the panel knows what a compressor is. The registry supplies each
parameter's range, step, unit and scale and the panel renders what it finds, so
adding an effect or a knob upstream needs no change here, and the panel cannot
offer a value the renderer would reject — a typed-in figure is clamped into the
declared range on the way through.
Frequency and time controls span three or four decades, so those declare a log
scale and the slider maps exponentially; a linear slider would spend most of
its travel somewhere useless.
Reorder is a first-class control because chain order changes the sound: a
reverb before a compressor is not the same as after.
Carve gets its own block rather than an entry in the add menu, with a picker
for the voice track to listen to. It processes this track based on another one,
which is how a sidechain control works — it lives on the track that changes,
and names the source.
* feat(studio): show the Audio FX section on audio tracks
Adds `audioFx` to the editing-affordances contract and renders the FX panel in
the inspector when an `` element is selected.
The section is audio-only. A `` carries its sound on a separate
`` element, so an FX chain on the video would have nothing to process.
Chain and carve settings are written straight back onto the element as
serialised attributes, the way colour grading carries its config, so
persistence is an ordinary attribute write and needs no new server route. A
chain that cannot be parsed renders as empty rather than breaking the panel,
and the attribute is left untouched until the user changes something.
The collapsed group summarises what is on the track ("2 effects + carve") so
the state is visible without expanding it.
Wired into PropertyPanelFlat rather than PropertyPanel: STUDIO_FLAT_INSPECTOR_ENABLED
defaults to true, so the flat inspector is what actually renders.
* refactor(studio): lift audioFxSummary out of PropertyPanelFlat
`PropertyPanelFlat.tsx` is 612 lines here against the repo's 600-line cap,
so the required File size check is red — the sole reason this PR is
blocked. The review says as much: "mechanical fix (~5 min), not a design
problem. Code itself is LGTM."
Moves `audioFxSummary` to `audioFxSummary.ts`, the same file a later
branch creates for it. Deliberately the smallest cut that clears the cap
rather than the whole `AudioFxGroup` extraction: every later commit in the
stack edits AudioFxGroup, so moving it here would collide with each of
them, while almost nothing touches this function.
595 lines.
* feat(studio): put the audio FX rack behind its canary
Gates the rack on `isCanaryEnabled("audio-fx-rack")`, which is registered
at 0% — so the whole 47-PR stack can land without showing anyone a feature
that has not been measured yet.
The gate sits on the AUTHORING surface and nowhere else. The runtime and
the render still honour a `data-fx-chain` already on an element, so a
composition written through the skill or by `carve.mjs` keeps its
processing rather than going silently dry for anyone outside the cohort. A
canary should stage who can REACH a feature, not make an attribute somebody
already wrote stop working with no error.
Gated at the panel rather than in `resolveEditingSections`: the affordance
resolver is a pure function in core describing what an element CAN support,
and rollout state is not a property of an `` tag.
Pinned the 0% with a test, and checked it fails at 25 — a ramp should have
to break something that says "this ships dark" out loud.
One gap, stated rather than papered over: the gate itself has no unit test.
I wrote one and deleted it, because `PropertyPanel.test.tsx`'s harness
never renders the Audio FX group for its audio fixture even with the gate
removed — so the test passed for the wrong reason in the off case and could
not pass at all in the on case. A test that cannot fail for the right
reason is worse than none. Verifying the gate needs the panel harness to
mount that section first, which is its own change.
* feat(core,studio): hear the FX chain in preview, and run the carve analysis
Splices an element's FX chain into the playback graph so preview stops being
silent about effects, and wires the carve button that was previously inert.
The chain goes between the decoded source and its gain stage: effects see the
raw signal and volume automation rides on their output, matching the order the
offline render uses. Since preview and render call the same graph builders,
what is heard while scrubbing is what gets written.
The splice lives in the transport rather than on the `` element. The
transport plays each track from a decoded AudioBuffer and mutes the element to
avoid doubling, so capturing the element with createMediaElementSource would
have processed a stream nothing is listening to — it looked like it worked
because the call succeeded, and the audio was unchanged.
A chain that cannot be built plays dry rather than silencing the track, which
is the right failure in preview: the author keeps working and hears the source.
The render still refuses, because shipping the dry signal there would be wrong.
Carve now analyses for real: it decodes the chosen voice track, ranks its bands
and writes the resulting peaking filters onto this track. Generated nodes are
tagged `fromCarve`, so re-running replaces the previous carve instead of
stacking another set on top of hand-added effects.
Known limitation: the graph is built when a source is scheduled, so a knob
turned mid-playback takes effect on the next play or seek rather than
immediately. Live re-parameterisation needs the transport to hold the handle
and forward updates.
* fix(studio,core): stop parameter drags from restarting playback
Dragging a knob wrote the chain through the persisting attribute path on every
input event. That path refreshes the preview, which reloads the composition and
reschedules audio — so a single drag reloaded dozens of times and playback
stuttered the whole way.
Drags now go through `onSetAttributeLive`, the same path colour grading uses for
scrubs: it coalesces undo entries and sets `skipRefresh`, so no reload happens.
The persisting write fires once, when the gesture ends — pointer-up or blur for
a slider, Enter or blur for a typed value. A select commits immediately since
there is no drag to wait for.
While dragging, the control is driven from local state. Waiting for the value to
round-trip through the element attribute made the knob lag behind the pointer.
For the change to be audible without a reload, the graph now follows the
attribute: the chain installed by the transport observes the element and
re-parameterises itself in place, so a value change lands on the next
128-sample quantum. A shape change (effect added, bypassed, pole count) cannot
be patched into a running graph, so it still waits for the next schedule rather
than cutting the audio mid-play.
The regression test drags a slider through several values and asserts the
persisting handler is untouched until release.
* fix(core): register FX worklets before building nodes that need them
An AudioWorkletNode cannot be constructed before its processor is registered —
it throws, and the surrounding chain is lost with it. `attachElementFxChain`
built the chain first and only then called `ensureAudioFxWorklets`, so every
worklet-backed effect (compressor, limiter, gate, bitcrush) threw on
construction and the track fell back to dry. Instrumenting the preview showed
`hf-compressor: InvalidStateError` with addModule never called at all.
When the module has not landed yet the track now plays dry and the graph is
swapped in once registration resolves, so the effect arrives a moment late
instead of never.
Registration is also tracked per context rather than in one module-level
promise. A processor registered on one AudioContext does not exist on another,
so the shared promise made every context after the first believe it was ready
when it was not — the studio's transport owns its own context, which is exactly
that case.
With the worklets actually running, the compressor's per-sample log10 and pow
became real audio-thread work. Samples below the knee have a gain of exactly
unity and need neither, so the envelope is now compared in the linear domain
and the transcendentals only run for samples that are actually being
compressed.
* refactor(studio): split the FX node row out of FxSection
Clears the health findings the FX stack left behind: the chain-node render
callback was a 70-line closure over half of FxSection's state, and the two
reorder arrows were the same button written twice.
Also drops two exports with no consumers, and registers the audio FX runtime
stub as an entry point — it is bundled by file path, so nothing imports it.
Co-Authored-By: Claude Opus 5 (1M context)
* refactor(studio): lift the audio FX group out of PropertyPanelFlat
`PropertyPanelFlat.tsx` was 672 lines against the repo's 600-line cap, so
the required File size check was red — the sole reason #3014 and #3022 are
blocked. Both reviews say the same thing: "mechanical fix, not a design
problem. Code itself is LGTM."
Moves `AudioFxGroup` and `audioFxSummary` into
`propertyPanelAudioFxGroup.tsx`, which is where a later branch puts them
anyway — done here so the file is under the cap from the point it first
crosses it, rather than ten branches later.
533 lines now. The four audio imports it no longer needs go with it.
Not fixed here: three `FxSection carve` tests fail on this branch with
"Cannot read properties of undefined (reading 'toFixed')". Confirmed
pre-existing by stashing this change and re-running — that is the separate
`Test` failure the review also flags.
* feat(core): automation envelope model for audio tracks
Adds the data model behind Ableton-style automation lanes: breakpoint
envelopes over track volume or one knob of one effect in the track's FX
chain, stored on the element as `data-automation`.
Times are clip-local, so an envelope travels with the clip when it moves —
the clip-envelope model rather than arrangement automation.
`sampleAutomationLane` is the single interpolator. The lane drawing, the
preview scheduler and the render bake all call it, so the picture and the
sound cannot disagree about the curve. Log-scaled parameters interpolate in
log space, matching what their own knob already promises.
FX nodes gain a stable `id`, minted by count rather than randomly so the
document is the same on every machine. Lanes address nodes by id, so
reordering a chain never re-points a lane at a different effect, and a lane
whose effect was deleted is dropped rather than left to reattach.
Also warns when a track carries both a volume lane and a GSAP volume tween,
since only the lane is heard and the tween silently does nothing.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(core): expose the AudioParams behind automatable FX knobs
Marks the knobs an automation lane can drive and has each graph builder hand
back the AudioParam behind them, so a scheduler can write to a running effect
without knowing what the effect is.
A knob is not always one AudioParam. A wet/dry mix is two gains moving in
opposition, and a knob in milliseconds drives a delay time in seconds, so
each target carries the mapping out of the knob's own declared unit.
What stays unautomatable is stated where it is decided: a WaveShaper curve, a
convolution impulse and a one-pole filter's coefficients are all rebuilt
wholesale rather than scheduled, and the four worklet effects take values by
postMessage rather than through AudioParams.
The registry flag is written by hand, so a test builds every effect and
checks the exposure both ways — nothing flagged is missing, nothing exposed
is unflagged. A flag that lied would offer a lane that silently did nothing.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(core): play automation envelopes in preview
Schedules each lane onto the AudioParams behind its knob using native ramps
and value curves. Nothing evaluates the envelope per frame: it is handed to
the audio thread once, so it stays sample-accurate however busy the main
thread is, and the offline render will schedule it the same way.
Timing comes from the transport, so an envelope survives seeking into the
middle of a clip, a clip that has not started yet, and a playback rate that
compresses clip seconds into context seconds.
A straight line is only scheduled as a ramp when nothing bends it — no
curvature, a linear parameter scale, and no unit mapping. Log-scaled
parameters and mapped ones are sampled instead, since a delay knob in
milliseconds and a wet/dry pair moving in opposition are not linear in the
parameter they drive.
Lanes with nowhere to write are skipped rather than reported: a one-pole
filter exposes no frequency param, and the worklet effects expose none at
all. Editing an envelope mid-playback re-aims it at the live playhead rather
than restarting the track.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(engine): bake automation envelopes into the render
The offline render schedules FX lanes with the same scheduler preview uses,
inside the OfflineAudioContext that already runs the same graph builders. The
input WAV is the clip's own audio from its first sample, so clip-local time
is offline time and the envelope needs no offset.
Volume lanes take the existing PCM bake rather than a second mechanism: the
lane is converted to keyframes, so a straight fade stays two of them and only
a bent segment is sampled — the baker interpolates linearly and would
otherwise quietly straighten the curve. A volume lane supersedes keyframes
probed from the timeline, which `lint` already warns about.
A browser test sweeps a lowpass from below a 2 kHz tone to well above it and
measures both ends. Parsing the envelope is not the same as scheduling it,
and only running the real thing tells the two apart.
Co-Authored-By: Claude Opus 5 (1M context)
* fix(core): make the volume lane audible in preview
The envelope was scheduled onto the transport's gain AudioParam, but the
runtime rewrites that gain every tick from `data-volume` and the GSAP-seeked
value — so it was erased within a frame. Volume automation was correct in the
render and inaudible while previewing.
The lane now feeds the per-tick path where the probed volume keyframes already
sit, checked ahead of them so the two cannot fight, and the transport no
longer schedules volume at all: one mechanism instead of two racing.
The cost is honest — in preview the level steps per tick rather than per
sample, exactly as the existing keyframe path does. The render still bakes it
into the PCM sample-accurately, and FX parameters are still scheduled on their
own AudioParams, since nothing rewrites those.
Parsed lanes are cached by attribute text: the runtime asks once per tick per
track, and parsing there would run the JSON parser 60 times a second for a
value that only changes on an edit.
Co-Authored-By: Claude Opus 5 (1M context)
* fix(core): apply chain edits to the running graph
A structural edit — an effect added, removed, bypassed, or a filter's pole
count switched — was dropped. `buildFxChain`'s update reports false when the
change is not merely new values, and the attribute observer ignored that, so
the edit only took hold when the persisting write reloaded the composition.
That reload restarted every playing track, which is what was heard as the
audio chopping.
The graph is now swapped in place: the old effects are detached, the new ones
built and connected between the same source and gain, and any lanes
re-scheduled onto the new nodes. The source node is never touched, so playback
does not restart.
A track with no chain is watched too, rather than wired through and forgotten,
so adding its first effect is heard the same way. That means the function
always returns a disposer instead of null for the empty case.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(studio): the geometry and plumbing behind automation lanes
Everything an automation lane needs before there is a lane to look at, kept
apart from the component so the maths can be read and tested without a pointer.
`automationLaneGeometry` is pure: which parameters a clip can automate (its
fader, then each automatable knob of each effect that carries a node id), how a
value maps to a position in the lane, and how a lane is edited. Two decisions
live here and are worth review:
- A log-read knob maps on its own log scale, so the middle of a 100 Hz–20 kHz
lane is the geometric mean. Dragging and drawing then agree with what the
knob's own scale already promises.
- `withLane` replaces a lane in place rather than appending. A lane with no
explicitly chosen parameter shows whichever comes first, so moving the edited
one to the end would switch the lane out from under the pointer on the first
edit.
`automationLaneData` parses the two attributes, cached by their text so the
identity only changes when the text does — the lane holds an optimistic draft
while a point is dragged and compares against that identity, and a fresh object
on every playhead tick would throw the drag away. It binds automation to the
chain the way preview and the render bind it, so a lane whose effect was deleted
is dropped rather than drawn against the wrong axis.
`useAutomationLanes` routes edits through the DOM edit session, targeting the
selected element because that is what the attribute commit path writes to.
Row height reserves each lane at its own height rather than counting it as
another keyframe lane, and `TimelinePropertyLanes` gains a footer slot so the
lanes share the keyframe disclosure — and its `aria-controls`.
`TimelineElement` moves to its own module: playerStore had reached the 600-line
studio ceiling exactly and could not carry another field. It is re-exported from
there, so no importer changes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
* fix(studio): make automationLaneData reviewable, and evict one entry not all
The cache key held a literal NUL byte instead of its escape, so git classified
the whole module as binary: it landed as `Bin 0 -> 2677 bytes` with zero
diffable lines, invisible to review, to grep, and to any textual merge. The
escape is behaviour-identical.
With the file readable, two things in it needed fixing.
Eviction cleared the entire map. Clearing changes the identity of every lane's
automation at once, and a lane compares its drag draft against that identity —
so one unrelated element arriving at the limit would release an in-progress drag
and snap the point back. It now drops the oldest entry, and a hit is re-inserted
so it counts as recently used.
Nothing tested this module, which is what let the binary blob through. Now
covered: identity stability, re-parsing when the chain changes but the
automation text does not, a hot entry surviving 40 evictions, and an unreadable
attribute reading as nothing.
The geometry module's exports are ignored for dead-code while its consumer sits
one PR upstack, following the convention already used for the fast-capture
stack.
Co-Authored-By: Claude Opus 5 (1M context)
* fix(studio): carry the audio FX attributes onto every timeline row
Both element builders read `data-fx-chain` and `data-automation` off the host
element, and an expanded sub-composition child is built without one — so an audio
track inside a sub-composition reserved no automation height and drew no lanes,
while the property panel, which reads the live DOM selection rather than the row,
still showed its chain and its toggles. `hostElementState` exists to re-inherit
exactly this class of host-only field; it now covers these two alongside
`hidden`, `timelineLocked` and `timelineRole`.
`parseTimelineFromDOM` had the same gap and now reads both directly.
Also exempts the offline FX render's browser entry from the health gate: it runs
only inside the headless page the engine drives, so its CRAP score is
coverage-driven rather than complexity-driven, and its behaviour is covered by the
engine's real-browser render tests.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(studio): the automation lane itself
Draws each automated parameter as its own lane under the audio clip, on the same
disclosure caret the keyframe lanes use — that caret is the DAW automation
triangle. One lane per parameter rather than a selector to swap between them, so
two envelopes can be read and edited without hiding either.
Double-click the line to add a point, drag to shape it, right-click a point to
remove it.
Three things here took more than one attempt, and the comments say why:
- **A dragged point did not move.** The live write deliberately skips the preview
refresh — that is what keeps dragging from restarting playback — so the stored
value does not move under the pointer. The lane keeps a local draft.
- **Releasing snapped it back.** The draft was dropped when the drag ended, which
is before the persisted write comes around; it now lives until the automation
it was drawn over actually changes.
- **A press was eaten.** Not stopping propagation let the timeline start its own
gesture and swallow the second half of a double-click. The lane owns the press
once it is live — and when it is not, it selects its clip instead, since lanes
sit below the clip bar where the timeline's own selection handler never sees
them.
The envelope is inset by the grab radius so a point at the clip's first or last
frame is drawn whole rather than half outside the lane, and clip time still lines
up with screen position because the inset and the offset cancel.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
* fix(studio): let a track disclose its automation without a tween
The lane was mounted inside the property-lanes wrapper, which renders only for a
track's GSAP keyframe clip — so an audio clip with no tween resolved to nothing:
no disclosure caret, no reserved height, no lanes. Verified on a composition with
one ``, an envelope, and no tweens anywhere: 0 carets, 0 lanes. The
attribute still wrote and the render still baked it, so the feature failed
silently for exactly the tracks it exists for. Same composition now: 1 caret, and
expanding it draws the Volume lane.
Automation counts as something to disclose. `resolveTrackKeyframeClip` takes a
counter alongside the keyframe lane counts and qualifies a clip on either; the
header asks the same counter about the clip it already holds. A function rather
than another map threaded through the props: every caller then reads one cached
parse, so the height a row reserves and the lanes drawn in it cannot drift apart.
That drift is also fixed for the lane's own offset, which passed the raw tween
count where every other consumer uses distinct property groups. Two tweens on one
property drew one keyframe lane but pushed the automation lane down by two,
spilling into the next track; one tween on two properties did the inverse and
drew it over a diamond lane, stealing its pointer events. It now reads the same
`laneCounts` map the reserved height and the drawn lanes use.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(studio): automate a parameter without reloading the preview
The write path and the volume half of the panel surface.
**A commit that persists without reloading.** For attributes the runtime applies
to the live graph itself — an FX chain, its automation — a reload would only
interrupt playback to reach the state the preview already has. `skipRefresh` and
`refreshAfter` were already independent options; this exposes the combination
that skips the reload but still re-reads the selection.
Both halves are needed, and they were fighting each other. Without the reload,
audio no longer chops on an edit. Without the resync, the panel keeps reading the
selection snapshot it was built with, so a second edit computes from a pre-edit
value and appears to do nothing — deleting one effect made every later delete a
no-op. `handleDomAttributeLiveCommit` is untouched and still used for knob
dragging, where a per-move re-render is exactly what you do not want.
**Volume.** An automated track's slider is disabled, since a level set there
would be overwritten by the envelope on the next tick, and the toggle beside it
adds or deletes the lane. Adding seeds it with a single point at the level the
slider already shows, so automating a track never changes how loud it is.
**One shared reader** for both panel sections, which is what surfaced that
resolving against an absent chain would have deleted every FX lane the moment
someone automated a volume: the volume section does not parse the chain, so
"no chain" now means "do not resolve" rather than "drop what cannot be resolved".
The toggle itself lives with the FX controls it is shared with, and says
`Automated` / `Automate` through the studio's own Tooltip rather than a native
browser hover.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
* fix(studio): stop the last two automation writes reloading the preview
The quiet commit added here was only used by the FX group. Two writers still went
through the refreshing one, so they reloaded the preview and restarted every
playing track — the exact chop the live write during a drag exists to avoid:
- releasing a dragged breakpoint, so the audio hitched at the end of every point
you moved;
- clicking the volume toggle, while the same click on an effect parameter was
already silent.
Both are quiet now: still persisted, still resyncing the selection so a following
edit computes from the value just written.
Also fixes the seeded volume. `Number(dataAttributes.volume ?? "1")` is 0 for an
attribute that is present but empty, so automating such a track started its lane
at silence while the engine read the same empty value as unity.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(studio): automate and un-automate each effect parameter
The per-parameter surface in the FX panel.
An automated parameter's control is disabled — a value typed there would be
overwritten by the envelope on the next tick, so the lane is the value now — and
the toggle beside it adds or deletes that parameter's lane. Adding seeds the lane
with a single point at the value the control already holds, so switching to an
envelope never changes the sound, only where the value comes from.
Parameters no envelope can drive have no toggle at all: the worklet-backed
dynamics expose no AudioParams, a WaveShaper's curve and a convolution impulse
are rebuilt wholesale rather than scheduled. Neither does a chain node with no
id, since a lane addresses nodes by id — so adding an effect now mints one.
Carve moves onto the same non-reloading write, and decodes its source in an
`OfflineAudioContext`: opening a second output device mid-playback makes the
running track glitch while the hardware is reconfigured. Turning carve off now
also drops the filters it generated, which otherwise kept dipping the bed with
nothing in the panel to explain it.
`AudioFxGroup` moves into its own module — PropertyPanelFlat was at its size
budget — which also gave the panel's write behaviour somewhere to be tested: what
it writes, seeded at the current value, preserving the lanes it is not touching,
and clearing the attribute when the last one goes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
* feat(studio): only offer voiceover carve when there is a voice to carve against
Carve is a relationship between two tracks — it analyses another track's voice
and dips this bed where that voice sits. In a composition with a single audio
track there is nothing to listen to, so the block offered an empty source picker
and an Analyse button that could never do anything.
It is now shown only when the composition holds another audio track, and still
shown when carve is already configured: hiding a live setting because its voice
track was removed would leave the bed being dipped from out of sight.
Co-Authored-By: Claude Opus 5 (1M context)
* test(studio): cover carve visibility through the real element
The panel derives carve's source list from the selected element's document, so
a selection with no element has no sources — which the new visibility rule
correctly reads as 'nothing to carve against'. The suite mounted exactly that,
so it was asserting on a hidden block.
Selections now carry a real with a sibling track, and the two cases the
rule exists for are pinned directly.
Co-Authored-By: Claude Opus 5 (1M context)
* fix(studio): keep FX panel writes from clobbering each other
Three writes in the audio panel each read the source file, mutate one
attribute and write it back. Fired without ordering they read the same
content and the last one lands, dropping the others.
- Deleting an effect left its automation lanes in the attribute. Ids are
minted lowest-free, so the next effect added took the same id and
inherited the dead envelope: disabled and "Automated" without the
author ever automating it, and baked into the render.
- Switching carve off wrote the chain (dropping the filters it generated)
and the carve settings at once, so either the filters stayed with no
carve to explain them or the settings survived with no filters.
- The three carve dials committed per input event, patching the source
and resyncing the selection dozens of times per drag. They now preview
live and persist on release, like the FX knobs already do.
Volume automation reads through the quiet commit too, so removing a lane
resyncs the panel instead of leaving the slider disabled.
* feat(engine): let an FX tail decay instead of cutting it at the clip
The offline render ended at the last input sample, so a reverb or a delay
was still ringing when the context stopped. Measured on a 1.5 s tone
through a default reverb, the render cut at 1.524 s while the tail was
still at -29.7 dB — an audible chop, and the one place the render did not
match preview.
The length does not have to be guessed. Every tail here follows from its
own settings: a convolution is exactly as long as its impulse, and
`synthesizeReverbImpulse` derives that from room size; a delay's repeats
fall by `feedback` every `time`, so the count down to -60 dB is a log.
Everything else settles with its input — an all-pass chain has group
delay, not a tail, and a 9-second compressor release has no signal to
release once the clip stops.
`chainTailSeconds` sums them (the chain is serial, so a delay in front of
a reverb hands each repeat to the room), reads a lane's maximum rather
than the static knob where one is automated, and caps at 5 s — 5 s
between repeats at 0.95 feedback is eleven minutes of decay, and the
panel can dial exactly that.
The mixer's per-track atrim now allows the clip plus its tail; the atrim
after apad still holds every track to the composition's length, so a tail
can run over what follows but never extends the video.
Same fixture after: a smooth decay to -72 dB, last non-zero sample at
3.306 s against the 3.4 s the settings predict.
* feat(studio): curve, snap and type a value in an automation lane
Four gestures from Ableton's envelope editor, which is the muscle memory
an automation lane inherits.
Alt-drag the line between two breakpoints to bend it, Alt-double-click to
straighten. `curve` was already honoured everywhere it is read — drawn in
the lane, sampled in preview, baked into the render through
setValueCurveAtTime — with no gesture anywhere that could set it, so every
envelope anyone could draw was linear in practice. The curve is solved,
not accumulated (x^e = f, so e = ln f / ln x), which keeps the segment
under the pointer instead of drifting away over a long drag; the test
asserts that by sampling with the renderer's own sampler.
Shift locks a drag to one axis and fines the vertical travel to a quarter.
Which axis won is decided in pixels — seconds and dB are not comparable
numbers, and comparing them would make the lock depend on the zoom.
A dragged point snaps to the beat grid and to its neighbouring points,
with Alt to ignore it. The radius is tight on purpose: a lane is often a
few seconds wide, where a generous radius makes a point unplaceable
between two beats.
Double-click a point to type its value. -6.0 dB is not a pixel you can
find, and there was no way to enter one.
The gesture layer moves to useAutomationLaneGestures and the path builder
to envelopePath: the component was at the studio's 600-line ceiling, and
both are worth testing without a render. trackShowsBeatStrip comes out of
TimelineLanes for the same reason.
* feat(studio): pure range ops for automation lane selections
Add pointsIn() and replaceRange() functions for managing automation envelope
edits within a time range. The key invariant: envelope values outside the
selection never move. Implemented by anchoring the boundaries at t0 and t1
by sampling the original lane, so cutting middle sections cannot reshape
the rest. Inner points from shape generators can suppress redundant anchors
at merge distance.
* fix(studio): budget replaceRange's inner points before capping, not after
* feat(studio): automation selection slice
* feat(studio): drag-select a time range on an automation lane
Dragging on an automation lane's empty background now arms a range
selection, snapped to the beat grid and clamped to the lane duration; a
sub-3px drag counts as a click and clears instead. Point drags and
Alt-drag segment bends still take priority, since the range arm only
runs where the existing point/segment hit-test already returned null.
useAutomationLanes binds the selection slice per element/lane so the
rect renders from the store, matching the read pattern the writes
already use.
* feat(studio): delete an automation selection from the keyboard
Escape clears the active automation-lane time selection; Delete/Backspace
empties it via replaceRange(..., inner: []), which pins anchor points at
both edges and leaves the envelope outside the selection untouched. Mounted
in TimelineLanes.tsx next to the useAutomationLanes() call that already
lives there. Also adds a stale-selection guard in TimelineAutomationLaneSlot
that clears the selection if its lane's target stops existing on the bound
element's automation (e.g. the automated effect was deleted).
* test(studio): cover the automation selection stale-target guard
* feat(studio): ramp, swell and dip generators for automation selections
* fix(studio): let an automation range keep Delete from the clip
useAppHotkeys listens on window/capture, so it runs before
useAutomationSelectionKeyboard's document/capture handler. With a range
selected, Delete fell straight through to the clip-delete branch and
destroyed the whole audio clip the lane belongs to; Backspace hit the
reset-keyframes branch on the way and wiped the clip's keyframes.
Guard both by returning early when automationSelection is set, mirroring
the selectedKeyframes precedent six lines above. No preventDefault: the
downstream handler still needs the key.
dispatchPlainKey is exported so the arbitration between keyframes, an
automation range and the clip can be pinned without standing up the hook.
Co-Authored-By: Claude Opus 5 (1M context)
* chore: suppress unused export for automationShapes (consumed upstack)
* feat(studio): simplify dense automation runs
Implements Ramer-Douglas-Peucker point-thinning for audio automation
lane breakpoints, working in unit space for correct log-scaled
parameter handling.
Co-Authored-By: Claude Sonnet 5
* chore: add automationSimplify to fallow complexity ignore
The Ramer-Douglas-Peucker algorithm in automationSimplify.ts has
inherent complexity (12 cyclomatic / 20 cognitive) that is by design
and not refactorable. Added to health.ignore list and ignoreExports
list since it's consumed by the UI layer one PR upstack.
Co-Authored-By: Claude Sonnet 5
* feat(studio): internal clipboard for automation ranges
* feat(studio): copy and paste automation ranges across lanes
Extends the automation-selection keyboard hook with Cmd/Ctrl+C (copy the
active range) and Cmd/Ctrl+V (paste onto the selected clip's lane, at the
selection's start or the playhead, chaining the selection to the pasted
span so a second paste lands right after the first). Paste falls through
untouched when no target lane resolves, so clip-level paste keeps working.
Also fixes a latent test-isolation bug: setup() never unmounted the
previous test's Host, so document keydown listeners leaked across tests
and could consume later events before the current test's own listener ran.
* feat(studio): shape and simplify menu on an automation selection
Right-click inside an active time-selection rectangle on an automation
lane now opens a menu offering the four utility shapes (Ramp up, Ramp
down, Swell, Dip) and Simplify, composing generateShape/simplifyPoints
with pointsIn/replaceRange from the prior selection tasks. A point's own
right-click still stops propagation and deletes it, unaffected.
* fix(studio): repair the automation paste path and finish the key arbitration
Paste was the least safe path in this feature: it resolved its target from
the player store but committed through a different, asynchronously-lagging
channel. Six review findings against this branch, plus the Cmd+C/Cmd+V half
of the arbitration wa-15 started for Delete.
- Write channel: resolvePasteTarget bails unless the binding's
commitTargetKey equals the element it resolved. useAutomationLanes exposes
that key, resolved through resolveTimelineIdForSelection — the same
resolver applyDomSelection uses — and read in the same render as the
commit handlers, so a handler and the key cannot describe different
moments. Before this, clicking clip B then immediately pasting serialized
B's automation onto A and left B untouched.
- Chaining: the paste anchor comes from sel.t1, not sel.t0, so a second
Cmd+V lands after the first instead of on top of it. The old comment
claimed the new behaviour while the code did the opposite, and no test
pressed Cmd+V twice.
- Empty copy: copyRange returns false rather than arming a clipboard whose
every paste is a destructive flatten, and samples the range's edges so
copying a smooth stretch yields a real segment instead of no points.
- Playhead: the playhead branch requires the playhead to be inside the clip
rather than silently clamping an out-of-clip playhead to the clip's start.
- Keys: one chord helper normalizes with toLowerCase() and gates on
!shiftKey && !altKey, matching useAppHotkeys. CapsLock no longer kills the
shortcut and Ctrl+Alt+V no longer pastes where the app declines.
- Arbitration: useAppHotkeys consults automationOwnsKey before its c/v
branch, so an active range keeps Cmd+C/Cmd+V from the clip clipboard the
same way it keeps Delete. Without it Cmd+V duplicated the clip while the
automation paste wrote the same file, and Cmd+C armed both clipboards.
It returns without preventDefault — the downstream handler needs the key —
and declines when the automation clipboard is empty so clip paste still
works. dispatchModifierKey is exported to pin this, like dispatchPlainKey.
- Double-action: the hook now returns early on e.defaultPrevented.
useAppHotkeys is on window/capture and deliberately lets a keyframe
selection outrank a range on Delete; without this that press deleted the
keyframes there AND emptied the range here.
- Project scoping: the clipboard scopes itself. Every entry point carries the
project it speaks for and a mismatch empties the module, the shape
keyframeSlice already uses to discard a request from a previous session.
Scoping it inside the module rather than clearing it from the session seam
is deliberate: the failure is silent and destructive — a range copied in
project A pasted into B is remapped through A's captured sourceRange for an
FX node B may not have, and the keystroke is consumed so clip paste never
runs — so no future caller should be able to forget the guard. The mark
isLastPasteSpan reads is scoped transitively, through the same check.
- Session reset: createTimelineResetState clears automationSelection. It is
as ephemeral as selectedKeyframes, and a range surviving a project switch
can match a same-keyed clip in the new project and redirect a paste through
sel.elementKey === paste.elementKey to a stale t0.
Five of the six paste fixes above shipped without a test that fails without
them, which is how the branch reached review with a comment describing
chaining that the code did not do. Each now has one: a second Cmd+V landing
after the first, a commit-target mismatch declining, an out-of-clip playhead
declining, an empty-lane copy leaving an earlier clipboard intact, and Cmd+V
with CapsLock on. All five fail against this branch's parent.
* feat(engine): render audio FX in an OfflineAudioContext
Reads `data-fx-chain` off an audio element and runs the chain over the trimmed
WAV before volume automation is baked in — effects should see the raw signal,
and the envelope belongs on their output.
The processing happens in an OfflineAudioContext inside the headless browser
the engine already drives, running the same graph builders the studio previews
with. That is the point of the approach: one implementation per effect, so the
render agreeing with the preview is a property of the architecture rather than
a tolerance to police. Reimplementing each effect as an FFmpeg filter would
mean two implementations to keep in step, and for the dynamics processors and
modulated delays there is no filter that behaves the same way.
`build:audio-fx-runtime` bundles the graph builders into an injectable IIFE,
following the same pattern as the existing runtime artifacts, so the browser
runs exactly the code the studio does.
The page loads from a file:// URL rather than about:blank because AudioWorklet
is only exposed in a secure context — the compressor, limiter, gate and
bitcrush processors would otherwise fail to register with an opaque error.
file:// qualifies and needs no listening socket.
The chain is serialised into the attribute the way colour grading carries its
config, so there is no side-car file to resolve or lose.
An FX failure is fatal for the whole mix rather than a per-track soft failure.
Every other audio failure mode degrades gracefully — the track drops, siblings
continue — but substituting the dry signal for a processed one ships a render
that sounds plausible and is not what the author set up. Since the per-element
work races under Promise.all, an internal AbortController chained off the
caller's signal aborts in-flight siblings before workDir is removed.
* feat(core): voiceover carve analysis
Finds the bands a voice occupies so a music bed can be dipped there, letting
the voice sit in front without ducking the whole track.
Carve is a relationship between two tracks rather than an effect on one, so it
stays out of the FX chain. What it emits is an ordinary chain of peaking
filters, so a carve composes with whatever else is on the track and needs no
separate rendering path.
Selection is weighted toward intelligibility rather than raw voice energy.
Ranking purely by power lands on the fundamental almost every time, because
that is where a voice is loudest — but the masking that actually hurts a
voiceover happens higher up, and dipping 160 Hz mostly just thins the bed. The
bias is a control, not a constant: at 0 it follows raw energy, at 1 it weights
toward 1-3 kHz.
Ranking happens in dB, which matters more than it looks. Speech spreads 20-30 dB
across these bands — it falls off roughly 6 dB per octave above the fundamental
— so a weighting has to be on that scale to move anything at all. A
multiplicative weight of `1 - bias + bias * shaped` is bounded below by
`1 - bias`, capping its influence at 10*log10(1/(1 - bias)): 5.2 dB at the 0.7
default, 3 dB at 0.5. That is no influence against a real voice — every bias
short of ~0.95 would rank exactly like bias 0 and carve the fundamental, the
outcome the bias exists to prevent, while looking decisive against a fixture
whose bands sit 2 dB apart. So the bias is a dB penalty, zero at 2 kHz and worth
up to 30 dB at full strength, and relative cut depths come from a dB difference
rather than a ratio of weighted linear powers.
The bias reweights ranking without overriding the spectrum — a band the voice
has no energy in is not worth carving, and scores -Infinity rather than
competing — so a strongly low-pitched voice can still select low at full bias.
What the tests hold is that biasing never selects lower than the unbiased
ranking, that the DEFAULT bias reaches the presence region on a voice with a
realistic tilt, and that bias 0 still follows raw power exactly.
Includes a radix-2 FFT rather than a dependency; one Welch-style averaged
spectrum over third-octave bands does not justify pulling in a DSP library.
* fix(engine): keep the FX render 16-bit, stereo, and correctly sized
Three defects in the offline FX path, none of which any test could see.
**Float output silently disabled sample-accurate volume automation.** The writer
emitted 32-bit IEEE float; the very next mixer step bakes the volume envelope
into the samples and accepts only 16-bit PCM, returning null otherwise. So
enabling any effect downgraded that track to the ffmpeg expression path — capped
at 32 straight segments, quantising a curved envelope, and on a dense one falling
back to base volume. It now writes 16-bit PCM, clamped rather than wrapped so a
limiter at 0 dB or a resonant filter cannot turn overshoot into a click. A test
asserts the baker accepts the writer's own output and actually fades it.
**Everything was folded to mono.** `prepareAudioTrack` goes out of its way to
emit stereo — its pan filter exists to dodge ffmpeg's 3 dB mono-to-stereo
rematrix — and this folded it, then wrote one channel. So adding a single peaking
EQ collapsed a bed's width and cost ~3 dB in the render, while preview stayed
stereo. Channels now travel as one plane each, through an OfflineAudioContext of
the same width, and come back interleaved.
**Small results decoded the wrong length.** `new Float32Array(buf.buffer)`
discards byteOffset and byteLength, and Node pools small allocations: a 400-byte
payload sits at offset 8 inside an 8 KiB pool, so a clip under ~1024 samples
decoded as 2048 samples of unrelated memory — and the empty-result guard could
not see it. The reader has the mirror-image fix: a float data chunk on an odd
boundary (ffmpeg's pcm_f32le writes fmt(18) + fact, landing `data` at 58) now
copies instead of throwing RangeError on an unaligned view.
The tail limitation is now stated rather than mis-stated: the context is exactly
as long as the input, so a reverb or delay still ringing is cut there. The old
comment claimed the opposite. How far a tail may run past a clip's end changes
the clip's length in the mix, so it is a product decision, not one to make here.
Co-Authored-By: Claude Opus 5 (1M context)
* fix(producer): report an FX render failure as an audio error
`processCompositionAudio` reports per-track failures in its result, but an FX
failure it cannot degrade past — a browser that will not launch, a chain that
will not build — rejects instead. `runAudioStage` had no try, so that rejection
escaped to the orchestrator as an unclassified pipeline exception, losing the
stage/owner/retryable classification this stage exists to attach, and skipping
its abort check on the way out.
It now lands in `audioError` alongside every other cause, while an abort still
keeps its own shape rather than being reported as an audio problem.
Not done here: committing the generated `audio-fx-runtime-inline.ts` so a fresh
clone typechecks packages/engine without building first. The bundle is built from
the stub, and the stub changes three times across this stack — so the artifact
differs per branch and would conflict on every restack. Its model,
position-edits-render-inline.ts, is committed only because it is stable. Building
before testing is this monorepo's existing contract (studio's tests need core's
dist too), so the gap is not specific to audio FX and is better closed by a build
ordering gate than by committing a per-branch artifact.
Co-Authored-By: Claude Opus 5 (1M context)
* test(engine): skip the browser FX render cases when there is no browser
CI's `Test` job was red on this PR with four failures, all the same cause:
Failed to launch the browser process: spawn
/home/runner/.cache/hyperframes/chrome/chrome-headless-shell
The job installs ffmpeg and no browser, deliberately — every other suite
that needs an external binary already guards on it
(`describe.skipIf(!HAS_FFMPEG)`). These cases were the only ones assuming
a Chrome, so they failed on an absent dependency rather than on anything
about the code.
Guards on `resolveHeadlessShellPath()` — the same resolver
`acquireBrowser` launches through, so the check cannot drift from the
thing it guards the way a hard-coded cache path would. A configured path
that does not exist throws; that is caught and read as "cannot run here".
Checked both directions rather than just the green one: with a browser all
11 cases run and pass, and with `HYPERFRAMES_BROWSER_PATH` pointed at a
missing binary exactly 3 skip and the other 8 still run. A guard that
silently skipped everything would have looked identical in CI.
They keep their value where it exists — every developer machine, and any
job that has run `hyperframes browser ensure`.
Not touched: the CodeQL failure on this PR is a run from 2026-08-07, five
days and several force-pushes stale. None of the 17 open repo alerts are
in files this PR changes; it re-runs on this push.
* chore(engine): suppress the temp-file alert with the reason it is safe
CodeQL flags `writeWav`'s `writeFileSync` as js/insecure-temporary-file
(high) — the one new alert on #3021, and the reason its CodeQL check is
red.
It is a false positive, and the comment says why rather than just silencing
it: `path` is always inside a directory made by `mkdtempSync`, never a
name assembled directly under `tmpdir()`. Both callers are covered — the
browser host page writes into `mkdtempSync(join(tmpdir(), "hf-fx-host-"))`,
and the render output goes to the producer work dir, itself
`mkdtempSync(join(tempRoot, "producer-project-"))`. mkdtemp picks the
random suffix and creates the directory 0700 in one syscall, so the
predictable filename inside it cannot be pre-created or symlinked by
another user, which is the attack the rule is about. The analyzer sees the
dataflow reach `tmpdir()` and not the mkdtemp in between.
Suppressed inline rather than dismissed in the UI, so the justification
lives next to the code and the rule stays live for anything added later in
this file. Matches the repo's existing convention — `planV2.ts:222`
carries an `lgtm[js/insecure-temporary-file]` for a different reason on
the same rule.
Correcting myself: I first reported this alert as not real, having
intersected the PR's files against the default-branch alert list, which
does not contain PR-ref alerts. Querying ?ref=refs/pull/3021/merge returns
it straight away.
* test(engine): probe ffmpeg and Chrome instead of assuming them
Two failures on #3021's Test job, both about the environment rather than
the code under test.
**Bare `ffmpeg` is not on PATH in CI.** The 16-bit fixture shelled out to
`execFileSync("ffmpeg", ...)` and died with ENOENT. The job does provide
ffmpeg, through `prepare-ffmpeg-bin`, which is what `getFfmpegBinary()`
resolves — every other ffmpeg-dependent suite in this package already goes
through it. Now this one does too, and the case is `skipIf(!HAS_FFMPEG)`
so a contributor without ffmpeg skips rather than fails.
**The browser guard trusted the wrong thing.** It asked
`resolveHeadlessShellPath()` and treated a returned path as "a browser is
here". CI's cache holds a chrome-headless-shell that resolves and then
fails to spawn — a partial download is indistinguishable from a working
one by `existsSync`, which is all that resolver checks. So the three
browser cases ran anyway and failed on the launch.
It now runs `--version` and requires exit 0, which is the same probe the
ffmpeg suites use: ask the binary, do not infer from the filesystem.
Checked both directions rather than just the green one. With a working
browser all 11 cases run and pass; with `HYPERFRAMES_BROWSER_PATH` pointed
at a binary that exits non-zero — CI's exact situation — exactly 3 skip
and the other 8 still run. A guard that quietly skipped everything would
have looked identical on the CI summary.
* feat(core): register the audio-fx-rack canary at 0%
Lands the rollout switch dark, per the registry's own procedure: "Start at
percentage: 0 and merge that — a canary at 0 is dead code you can land
safely and ramp without a code review."
Declared at the bottom of the stack so every branch above can read it. The
gate itself goes in at wa-4-fx-panel, where the rack first appears.
Scope is deliberate and stated in the description: it gates the AUTHORING
surface only. A composition that already carries `data-fx-chain` still
plays and renders it. A canary should stage who can REACH a feature, not
make an attribute somebody already wrote silently inert — an agent that
writes a chain through the skill would otherwise produce a file whose audio
processing vanishes with no error.
* feat(studio): audio FX panel generated from the registry
Controls for the whole chain: add, remove, reorder, bypass, and every knob each
effect declares.
Nothing in the panel knows what a compressor is. The registry supplies each
parameter's range, step, unit and scale and the panel renders what it finds, so
adding an effect or a knob upstream needs no change here, and the panel cannot
offer a value the renderer would reject — a typed-in figure is clamped into the
declared range on the way through.
Frequency and time controls span three or four decades, so those declare a log
scale and the slider maps exponentially; a linear slider would spend most of
its travel somewhere useless.
Reorder is a first-class control because chain order changes the sound: a
reverb before a compressor is not the same as after.
Carve gets its own block rather than an entry in the add menu, with a picker
for the voice track to listen to. It processes this track based on another one,
which is how a sidechain control works — it lives on the track that changes,
and names the source.
* feat(studio): show the Audio FX section on audio tracks
Adds `audioFx` to the editing-affordances contract and renders the FX panel in
the inspector when an `` element is selected.
The section is audio-only. A `` carries its sound on a separate
`` element, so an FX chain on the video would have nothing to process.
Chain and carve settings are written straight back onto the element as
serialised attributes, the way colour grading carries its config, so
persistence is an ordinary attribute write and needs no new server route. A
chain that cannot be parsed renders as empty rather than breaking the panel,
and the attribute is left untouched until the user changes something.
The collapsed group summarises what is on the track ("2 effects + carve") so
the state is visible without expanding it.
Wired into PropertyPanelFlat rather than PropertyPanel: STUDIO_FLAT_INSPECTOR_ENABLED
defaults to true, so the flat inspector is what actually renders.
* refactor(studio): lift audioFxSummary out of PropertyPanelFlat
`PropertyPanelFlat.tsx` is 612 lines here against the repo's 600-line cap,
so the required File size check is red — the sole reason this PR is
blocked. The review says as much: "mechanical fix (~5 min), not a design
problem. Code itself is LGTM."
Moves `audioFxSummary` to `audioFxSummary.ts`, the same file a later
branch creates for it. Deliberately the smallest cut that clears the cap
rather than the whole `AudioFxGroup` extraction: every later commit in the
stack edits AudioFxGroup, so moving it here would collide with each of
them, while almost nothing touches this function.
595 lines.
* feat(core,studio): hear the FX chain in preview, and run the carve analysis
Splices an element's FX chain into the playback graph so preview stops being
silent about effects, and wires the carve button that was previously inert.
The chain goes between the decoded source and its gain stage: effects see the
raw signal and volume automation rides on their output, matching the order the
offline render uses. Since preview and render call the same graph builders,
what is heard while scrubbing is what gets written.
The splice lives in the transport rather than on the `` element. The
transport plays each track from a decoded AudioBuffer and mutes the element to
avoid doubling, so capturing the element with createMediaElementSource would
have processed a stream nothing is listening to — it looked like it worked
because the call succeeded, and the audio was unchanged.
A chain that cannot be built plays dry rather than silencing the track, which
is the right failure in preview: the author keeps working and hears the source.
The render still refuses, because shipping the dry signal there would be wrong.
Carve now analyses for real: it decodes the chosen voice track, ranks its bands
and writes the resulting peaking filters onto this track. Generated nodes are
tagged `fromCarve`, so re-running replaces the previous carve instead of
stacking another set on top of hand-added effects.
Known limitation: the graph is built when a source is scheduled, so a knob
turned mid-playback takes effect on the next play or seek rather than
immediately. Live re-parameterisation needs the transport to hold the handle
and forward updates.
* fix(studio,core): stop parameter drags from restarting playback
Dragging a knob wrote the chain through the persisting attribute path on every
input event. That path refreshes the preview, which reloads the composition and
reschedules audio — so a single drag reloaded dozens of times and playback
stuttered the whole way.
Drags now go through `onSetAttributeLive`, the same path colour grading uses for
scrubs: it coalesces undo entries and sets `skipRefresh`, so no reload happens.
The persisting write fires once, when the gesture ends — pointer-up or blur for
a slider, Enter or blur for a typed value. A select commits immediately since
there is no drag to wait for.
While dragging, the control is driven from local state. Waiting for the value to
round-trip through the element attribute made the knob lag behind the pointer.
For the change to be audible without a reload, the graph now follows the
attribute: the chain installed by the transport observes the element and
re-parameterises itself in place, so a value change lands on the next
128-sample quantum. A shape change (effect added, bypassed, pole count) cannot
be patched into a running graph, so it still waits for the next schedule rather
than cutting the audio mid-play.
The regression test drags a slider through several values and asserts the
persisting handler is untouched until release.
* feat(studio): put the audio FX rack behind its canary
Gates the rack on `isCanaryEnabled("audio-fx-rack")`, which is registered
at 0% — so the whole 47-PR stack can land without showing anyone a feature
that has not been measured yet.
The gate sits on the AUTHORING surface and nowhere else. The runtime and
the render still honour a `data-fx-chain` already on an element, so a
composition written through the skill or by `carve.mjs` keeps its
processing rather than going silently dry for anyone outside the cohort. A
canary should stage who can REACH a feature, not make an attribute somebody
already wrote stop working with no error.
Gated at the panel rather than in `resolveEditingSections`: the affordance
resolver is a pure function in core describing what an element CAN support,
and rollout state is not a property of an `` tag.
Pinned the 0% with a test, and checked it fails at 25 — a ramp should have
to break something that says "this ships dark" out loud.
One gap, stated rather than papered over: the gate itself has no unit test.
I wrote one and deleted it, because `PropertyPanel.test.tsx`'s harness
never renders the Audio FX group for its audio fixture even with the gate
removed — so the test passed for the wrong reason in the off case and could
not pass at all in the on case. A test that cannot fail for the right
reason is worse than none. Verifying the gate needs the panel harness to
mount that section first, which is its own change.
* fix(core): register FX worklets before building nodes that need them
An AudioWorkletNode cannot be constructed before its processor is registered —
it throws, and the surrounding chain is lost with it. `attachElementFxChain`
built the chain first and only then called `ensureAudioFxWorklets`, so every
worklet-backed effect (compressor, limiter, gate, bitcrush) threw on
construction and the track fell back to dry. Instrumenting the preview showed
`hf-compressor: InvalidStateError` with addModule never called at all.
When the module has not landed yet the track now plays dry and the graph is
swapped in once registration resolves, so the effect arrives a moment late
instead of never.
Registration is also tracked per context rather than in one module-level
promise. A processor registered on one AudioContext does not exist on another,
so the shared promise made every context after the first believe it was ready
when it was not — the studio's transport owns its own context, which is exactly
that case.
With the worklets actually running, the compressor's per-sample log10 and pow
became real audio-thread work. Samples below the knee have a gain of exactly
unity and need neither, so the envelope is now compared in the linear domain
and the transcendentals only run for samples that are actually being
compressed.
* refactor(studio): split the FX node row out of FxSection
Clears the health findings the FX stack left behind: the chain-node render
callback was a 70-line closure over half of FxSection's state, and the two
reorder arrows were the same button written twice.
Also drops two exports with no consumers, and registers the audio FX runtime
stub as an entry point — it is bundled by file path, so nothing imports it.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(core): automation envelope model for audio tracks
Adds the data model behind Ableton-style automation lanes: breakpoint
envelopes over track volume or one knob of one effect in the track's FX
chain, stored on the element as `data-automation`.
Times are clip-local, so an envelope travels with the clip when it moves —
the clip-envelope model rather than arrangement automation.
`sampleAutomationLane` is the single interpolator. The lane drawing, the
preview scheduler and the render bake all call it, so the picture and the
sound cannot disagree about the curve. Log-scaled parameters interpolate in
log space, matching what their own knob already promises.
FX nodes gain a stable `id`, minted by count rather than randomly so the
document is the same on every machine. Lanes address nodes by id, so
reordering a chain never re-points a lane at a different effect, and a lane
whose effect was deleted is dropped rather than left to reattach.
Also warns when a track carries both a volume lane and a GSAP volume tween,
since only the lane is heard and the tween silently does nothing.
Co-Authored-By: Claude Opus 5 (1M context)
* refactor(studio): lift the audio FX group out of PropertyPanelFlat
`PropertyPanelFlat.tsx` was 672 lines against the repo's 600-line cap, so
the required File size check was red — the sole reason #3014 and #3022 are
blocked. Both reviews say the same thing: "mechanical fix, not a design
problem. Code itself is LGTM."
Moves `AudioFxGroup` and `audioFxSummary` into
`propertyPanelAudioFxGroup.tsx`, which is where a later branch puts them
anyway — done here so the file is under the cap from the point it first
crosses it, rather than ten branches later.
533 lines now. The four audio imports it no longer needs go with it.
Not fixed here: three `FxSection carve` tests fail on this branch with
"Cannot read properties of undefined (reading 'toFixed')". Confirmed
pre-existing by stashing this change and re-running — that is the separate
`Test` failure the review also flags.
* feat(core): expose the AudioParams behind automatable FX knobs
Marks the knobs an automation lane can drive and has each graph builder hand
back the AudioParam behind them, so a scheduler can write to a running effect
without knowing what the effect is.
A knob is not always one AudioParam. A wet/dry mix is two gains moving in
opposition, and a knob in milliseconds drives a delay time in seconds, so
each target carries the mapping out of the knob's own declared unit.
What stays unautomatable is stated where it is decided: a WaveShaper curve, a
convolution impulse and a one-pole filter's coefficients are all rebuilt
wholesale rather than scheduled, and the four worklet effects take values by
postMessage rather than through AudioParams.
The registry flag is written by hand, so a test builds every effect and
checks the exposure both ways — nothing flagged is missing, nothing exposed
is unflagged. A flag that lied would offer a lane that silently did nothing.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(core): play automation envelopes in preview
Schedules each lane onto the AudioParams behind its knob using native ramps
and value curves. Nothing evaluates the envelope per frame: it is handed to
the audio thread once, so it stays sample-accurate however busy the main
thread is, and the offline render will schedule it the same way.
Timing comes from the transport, so an envelope survives seeking into the
middle of a clip, a clip that has not started yet, and a playback rate that
compresses clip seconds into context seconds.
A straight line is only scheduled as a ramp when nothing bends it — no
curvature, a linear parameter scale, and no unit mapping. Log-scaled
parameters and mapped ones are sampled instead, since a delay knob in
milliseconds and a wet/dry pair moving in opposition are not linear in the
parameter they drive.
Lanes with nowhere to write are skipped rather than reported: a one-pole
filter exposes no frequency param, and the worklet effects expose none at
all. Editing an envelope mid-playback re-aims it at the live playhead rather
than restarting the track.
Co-Authored-By: Claude Opus 5 (1M context)
* fix(core): make the volume lane audible in preview
The envelope was scheduled onto the transport's gain AudioParam, but the
runtime rewrites that gain every tick from `data-volume` and the GSAP-seeked
value — so it was erased within a frame. Volume automation was correct in the
render and inaudible while previewing.
The lane now feeds the per-tick path where the probed volume keyframes already
sit, checked ahead of them so the two cannot fight, and the transport no
longer schedules volume at all: one mechanism instead of two racing.
The cost is honest — in preview the level steps per tick rather than per
sample, exactly as the existing keyframe path does. The render still bakes it
into the PCM sample-accurately, and FX parameters are still scheduled on their
own AudioParams, since nothing rewrites those.
Parsed lanes are cached by attribute text: the runtime asks once per tick per
track, and parsing there would run the JSON parser 60 times a second for a
value that only changes on an edit.
Co-Authored-By: Claude Opus 5 (1M context)
* feat(engine): bake automation envelopes into the render
The offline render schedules FX lanes with the same scheduler preview uses,
inside the OfflineAudioContext that already runs the same graph builders. The
input WAV is the clip's own audio from its first sample, so clip-local time
is offline time and the envelope needs no offset.
Volume lanes take the existing PCM bake rather than a second mechanism: the
lane is converted to keyframes, so a straight fade stays two of them and only
a bent segment is sampled — the baker interpolates linearly and would
otherwise quietly straighten the curve. A volume lane supersedes keyframes
probed from the timeline, which `lint` already warns about.
A browser test sweeps a lowpass from below a 2 kHz tone to well above it and
measures both ends. Parsing the envelope is not the same as scheduling it,
and only running the real thing tells the two apart.
Co-Authored-By: Claude Opus 5 (1M context)
* fix(core): apply chain edits to the running graph
A structural edit — an effect added, removed, bypassed, or a filter's pole
count switched — was dropped. `buildFxChain`'s update reports false when the
change is not merely new values, and the attribute observer ignored that, so
the edit only took hold when the persisting write reloaded the composition.
That reload restarted every playing track, which is what was heard as the
audio chopping.
The graph is now swapped in place: the old effects are detached, the new ones
built and connected between the same source and gain, and any lanes
re-scheduled onto the new nodes. The source node is never touched, so playback
does not restart.
A track with no chain is watched too, rather than wired through and forgotten,
so adding its first effect is heard the same way. That means the function
always returns a disposer instead of null for the empty case.
Co-Authored-By: Claude Opus 5 (1M context)
* fix(studio): drop the FX panel's dead __testables export
Fallow audit flagged it — no test imports the module.
* fix(core,studio): clear the remaining Fallow audit findings on the FX panel
- Split FxSection's per-node row into FxNodeRow + FxNodeControls so the
CRAP score (31.6, threshold 30) splits across two smaller units instead
of moving wholesale with one extraction.
- Dedupe the repeated "open the add menu, read its items" block in
propertyPanelFxSection.test.tsx into openAddMenuItems().
- Merge build-audio-fx-runtime.ts and build-position-edits-render.ts into
one build-inline-artifact.ts, config-selected by CLI arg — the two
scripts were a byte-for-byte clone save for names.
- Exempt canary.test.ts's rawFnv (a deliberate independent
reimplementation used to cross-check canaryBucket, per its own
docstring) and the property-panel test files' shared renderInto/mount
scaffolding (pre-existing across 9 files, 2 outside this stack) in
.fallowrc.jsonc, consistent with this file's existing exemptions for
the same class of intentional/pre-existing duplication.
* fix(ci): allowlist the build-script consolidation in the no-main-deletions guard
build-audio-fx-runtime.ts and build-position-edits-render.ts were merged into
build-inline-artifact.ts to kill a fallow duplication finding; the deletion
guard flagged that as an accidental loss since main still has both originals.
* fix(core): dedupe the wet/dry mix math between delayFeedback and chorusLfo
Both effect builders set wet.gain to the mix and dry.gain to its complement
in identical two-line blocks; fallow kept re-flagging it as a 10-line clone
on every unrelated change. Extracted setWetDryMix.
* fix(core): remove the build-audio-fx-runtime.ts stray resurrected by a main merge
An earlier merge with main brought this deleted file back (git's merge/delete
handling on an unchanged-on-one-side file); package.json already points at
build-inline-artifact.ts, so it sat unreachable and duplicating that file's
config, both of which fallow flagged.
* fix(studio): pull TimelineLanes under the 600-line cap
TimelineLanes.tsx hit 620 lines. Extracted the three per-clip pointer
gestures (resize-start, pointer-down move-arm, click/razor-split) into
createClipGestureHandlers — one factory call per rendered clip instead of
~120 lines of inline handler bodies in the render loop. 529 lines now.
* fix(studio): split the extracted pointerdown handler under the CRAP threshold
Moving the ~120-line gesture logic into timelineClipGestureHandlers.ts
concentrated it into two functions fallow flagged (onPointerDown at CRAP
63.6, onResizeStart at 31.6). Split the decision logic (which gesture a
pointerdown implies) into a pure resolvePointerDownAction, then split
its own intent-blocking check into isIntentBlocked. onResizeStart's guard
moved into canStartResize. Every function now scores under 30.
* fix(studio): drop the unused DomEditSelection import in PropertyPanelFlat
CI caught it on PR #3026 (wa-12-panel-params); a later refactor in the
stack removed the last use of the type here without removing the import.
---------
Co-authored-by: Claude Opus 5 (1M context)
---
.../studio/src/contexts/DomEditContext.tsx | 7 +
.../studio/src/hooks/useAppHotkeys.test.ts | 87 ++++-
packages/studio/src/hooks/useAppHotkeys.ts | 21 +-
.../useAutomationSelectionKeyboard.test.tsx | 236 ++++++++++++-
.../hooks/useAutomationSelectionKeyboard.ts | 326 ++++++++++++++++--
.../TimelineAutomationLaneSlot.test.tsx | 1 +
.../components/automationClipboard.test.ts | 79 +++++
.../player/components/automationClipboard.ts | 136 ++++++++
.../player/components/useAutomationLanes.ts | 37 +-
.../src/player/store/playerStore.test.ts | 15 +
.../studio/src/player/store/playerStore.ts | 4 +
11 files changed, 901 insertions(+), 48 deletions(-)
create mode 100644 packages/studio/src/player/components/automationClipboard.test.ts
create mode 100644 packages/studio/src/player/components/automationClipboard.ts
diff --git a/packages/studio/src/contexts/DomEditContext.tsx b/packages/studio/src/contexts/DomEditContext.tsx
index 1ab9230fe8..365504b8d0 100644
--- a/packages/studio/src/contexts/DomEditContext.tsx
+++ b/packages/studio/src/contexts/DomEditContext.tsx
@@ -117,6 +117,13 @@ export function useDomEditSelectionContext(): DomEditSelectionValue {
return ctx;
}
+/** Optional counterpart to useDomEditActionsContextOptional — same reason: the
+ * player package's own components mount outside a provider in standalone and
+ * test trees, where "no dom-edit selection" is the correct answer. */
+export function useDomEditSelectionContextOptional(): DomEditSelectionValue | null {
+ return useContext(DomEditSelectionContext);
+}
+
/** @deprecated Prefer useDomEditActionsContext or useDomEditSelectionContext. */
export function useDomEditContext(): DomEditValue {
return { ...useDomEditActionsContext(), ...useDomEditSelectionContext() };
diff --git a/packages/studio/src/hooks/useAppHotkeys.test.ts b/packages/studio/src/hooks/useAppHotkeys.test.ts
index 7d7d88fc1d..2920d0f309 100644
--- a/packages/studio/src/hooks/useAppHotkeys.test.ts
+++ b/packages/studio/src/hooks/useAppHotkeys.test.ts
@@ -1,7 +1,9 @@
// @vitest-environment happy-dom
import { afterEach, describe, expect, it, vi } from "vitest";
-import { dispatchPlainKey } from "./useAppHotkeys";
+import { dispatchModifierKey, dispatchPlainKey } from "./useAppHotkeys";
import { usePlayerStore } from "../player/store/playerStore";
+import { clearAutomationClipboard, copyRange } from "../player/components/automationClipboard";
+import { VOLUME_RANGE } from "@hyperframes/core/audio-automation";
import type { TimelineElement } from "../player/store/timelineElement";
/** Minimal valid fixture — TimelineElement only requires these five fields. */
@@ -38,7 +40,11 @@ function callbacks() {
const press = (key: string) =>
new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true });
+const chord = (key: string) =>
+ new KeyboardEvent("keydown", { key, metaKey: true, bubbles: true, cancelable: true });
+
afterEach(() => {
+ clearAutomationClipboard();
usePlayerStore.getState().clearAutomationSelection();
usePlayerStore.setState({
elements: [],
@@ -111,3 +117,82 @@ describe("dispatchPlainKey — Delete arbitration", () => {
expect(e.defaultPrevented).toBe(true);
});
});
+
+describe("dispatchModifierKey — Cmd+C/Cmd+V arbitration", () => {
+ const clip: TimelineElement = {
+ id: "bgm",
+ key: "bgm",
+ tag: "audio",
+ start: 0,
+ duration: 6,
+ track: 0,
+ };
+
+ it("lets the clip clipboard have Cmd+C when no automation range is active", () => {
+ usePlayerStore.setState({ elements: [clip], selectedElementId: "bgm" });
+ const cb = callbacks();
+ dispatchModifierKey(chord("c"), "c", cb);
+ expect(cb.handleCopy).toHaveBeenCalled();
+ });
+
+ it("keeps Cmd+C from the clip clipboard when an automation range is active", () => {
+ // Both clipboards arming on one press double-wrote and toasted "Copied clip".
+ usePlayerStore.setState({ elements: [clip], selectedElementId: "bgm" });
+ usePlayerStore.getState().setAutomationSelection({
+ elementKey: "bgm",
+ target: "volume",
+ t0: 1,
+ t1: 3,
+ });
+ const cb = callbacks();
+ const e = chord("c");
+ expect(dispatchModifierKey(e, "c", cb)).toBe(true);
+ expect(cb.handleCopy).not.toHaveBeenCalled();
+ // No preventDefault: the automation handler downstream still needs the key.
+ expect(e.defaultPrevented).toBe(false);
+ });
+
+ it("lets the clip clipboard have Cmd+V when the automation clipboard is empty", () => {
+ // Nothing to paste means nothing to claim — the clip paste should still run.
+ clearAutomationClipboard();
+ usePlayerStore.setState({ elements: [clip], selectedElementId: "bgm" });
+ usePlayerStore.getState().setAutomationSelection({
+ elementKey: "bgm",
+ target: "volume",
+ t0: 1,
+ t1: 3,
+ });
+ const cb = callbacks();
+ dispatchModifierKey(chord("v"), "v", cb);
+ expect(cb.handlePaste).toHaveBeenCalled();
+ });
+
+ it("keeps Cmd+V from duplicating the clip while an automation paste is pending", () => {
+ clearAutomationClipboard();
+ copyRange(
+ null,
+ {
+ target: "volume",
+ points: [
+ { t: 1, v: 1 },
+ { t: 3, v: 0.25 },
+ ],
+ },
+ VOLUME_RANGE,
+ 1,
+ 3,
+ );
+ usePlayerStore.setState({ elements: [clip], selectedElementId: "bgm" });
+ usePlayerStore.getState().setAutomationSelection({
+ elementKey: "bgm",
+ target: "volume",
+ t0: 1,
+ t1: 3,
+ });
+ const cb = callbacks();
+ const e = chord("v");
+ dispatchModifierKey(e, "v", cb);
+ expect(cb.handlePaste).not.toHaveBeenCalled();
+ expect(e.defaultPrevented).toBe(false);
+ });
+});
diff --git a/packages/studio/src/hooks/useAppHotkeys.ts b/packages/studio/src/hooks/useAppHotkeys.ts
index da12f3f2d4..3ae69a7e0d 100644
--- a/packages/studio/src/hooks/useAppHotkeys.ts
+++ b/packages/studio/src/hooks/useAppHotkeys.ts
@@ -1,10 +1,12 @@
import { useCallback, useEffect, useRef } from "react";
+import { automationOwnsKey } from "./useAutomationSelectionKeyboard";
import { usePlayerStore } from "../player";
import type { TimelineElement } from "../player";
import type { DomEditSelection } from "../components/editor/domEditing";
import type { LeftSidebarHandle } from "../components/sidebar/LeftSidebar";
import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";
import { isTypingTarget } from "../utils/typingTarget";
+import { isEditableTarget } from "../utils/timelineDiscovery";
import { shouldIgnoreHistoryShortcut } from "../utils/studioHelpers";
import { canSplitElement } from "../utils/timelineElementSplit";
import { trackStudioEvent } from "../utils/studioTelemetry";
@@ -158,7 +160,14 @@ interface HotkeyCallbacks {
showToast: (message: string, tone?: "error" | "info") => void;
}
-function dispatchModifierKey(event: KeyboardEvent, key: string, cb: HotkeyCallbacks): boolean {
+/** Exported for tests, like dispatchPlainKey below: lets the Cmd+C/Cmd+V
+ * arbitration between an automation range and the clip clipboard be asserted
+ * without standing up the whole hook. */
+export function dispatchModifierKey(
+ event: KeyboardEvent,
+ key: string,
+ cb: HotkeyCallbacks,
+): boolean {
if (
!shouldIgnoreHistoryShortcut(event.target) &&
handleUndoRedoKey(
@@ -195,7 +204,15 @@ function dispatchModifierKey(event: KeyboardEvent, key: string, cb: HotkeyCallba
return true;
}
- if (!event.shiftKey && !event.altKey && !isTypingTarget(event.target)) {
+ if (!event.shiftKey && !event.altKey && !isEditableTarget(event.target)) {
+ // An active automation range owns Cmd+C/Cmd+V, the same way it owns Delete
+ // below. This listener is on window/capture and runs before
+ // useAutomationSelectionKeyboard's document/capture handler, so without
+ // this the clip clipboard also claimed the key: Cmd+V duplicated the clip
+ // while the automation paste wrote the same file, and Cmd+C armed both
+ // clipboards and toasted "Copied clip". Return without preventDefault so
+ // the downstream handler still sees the key.
+ if (automationOwnsKey(event)) return true;
if (key === "c") {
if (cb.handleCopy()) {
event.preventDefault();
diff --git a/packages/studio/src/hooks/useAutomationSelectionKeyboard.test.tsx b/packages/studio/src/hooks/useAutomationSelectionKeyboard.test.tsx
index fd24507356..a7f57d4b68 100644
--- a/packages/studio/src/hooks/useAutomationSelectionKeyboard.test.tsx
+++ b/packages/studio/src/hooks/useAutomationSelectionKeyboard.test.tsx
@@ -1,9 +1,15 @@
// @vitest-environment happy-dom
import { act } from "react";
-import { describe, expect, it, vi } from "vitest";
-import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createRoot, type Root } from "react-dom/client";
import { usePlayerStore } from "../player/store/playerStore";
import { useAutomationSelectionKeyboard } from "./useAutomationSelectionKeyboard";
+import {
+ clearAutomationClipboard,
+ copyRange,
+ readClipboard,
+} from "../player/components/automationClipboard";
+import { VOLUME_RANGE } from "@hyperframes/core/audio-automation";
import type {
AutomationLaneBinding,
UseAutomationLanesResult,
@@ -32,30 +38,60 @@ const key = (k: string) => {
act(() => void document.dispatchEvent(e));
};
+/** Cmd/Ctrl-modified key combo, returning the event so tests can inspect
+ * `defaultPrevented` for the "falls through" cases. */
+const combo = (k: string) => {
+ const e = new KeyboardEvent("keydown", {
+ key: k,
+ metaKey: true,
+ bubbles: true,
+ cancelable: true,
+ });
+ act(() => void document.dispatchEvent(e));
+ return e;
+};
+
describe("useAutomationSelectionKeyboard", () => {
+ // Each setup() mounts a Host whose effect adds a document-level keydown
+ // listener. Without unmounting the previous one, listeners from earlier
+ // tests linger and can consume later tests' events first (stopping
+ // propagation before the current test's own listener ever runs) — so this
+ // must run before every test, not just the ones that call setup() twice.
+ let mountedRoot: { root: Root; host: HTMLElement } | null = null;
+ afterEach(() => {
+ if (!mountedRoot) return;
+ act(() => mountedRoot?.root.unmount());
+ mountedRoot.host.remove();
+ mountedRoot = null;
+ });
+
const setup = (binding: Partial) => {
const onCommit = vi.fn();
- const lanes: UseAutomationLanesResult = {
- bind: () => ({
- automation: {
- version: 1,
- lanes: [
- {
- target: "volume",
- points: [
- { t: 0, v: 1 },
- { t: 2, v: 0.5 },
- { t: 4, v: 0 },
- ],
- },
+ const automation = {
+ version: 1,
+ lanes: [
+ {
+ target: "volume",
+ points: [
+ { t: 0, v: 1 },
+ { t: 2, v: 0.5 },
+ { t: 4, v: 0 },
],
},
- lanes: [],
+ ],
+ };
+ const lanes: UseAutomationLanesResult = {
+ bind: () => ({
+ automation,
+ // Same list as `automation.lanes`, matching useAutomationLanes' real
+ // binding — the paste fallback (no active selection) reads this.
+ lanes: automation.lanes,
chain: null,
onPreview: vi.fn(),
onCommit,
onSelect: vi.fn(),
readOnly: false,
+ commitTargetKey: "bgm",
selection: null,
onRangeSelect: vi.fn(),
onRangeClear: vi.fn(),
@@ -64,7 +100,9 @@ describe("useAutomationSelectionKeyboard", () => {
};
const host = document.createElement("div");
document.body.append(host);
- act(() => createRoot(host).render( ));
+ const root = createRoot(host);
+ act(() => root.render( ));
+ mountedRoot = { root, host };
return { onCommit };
};
@@ -101,4 +139,168 @@ describe("useAutomationSelectionKeyboard", () => {
expect(onCommit).not.toHaveBeenCalled();
input.remove();
});
+
+ it("Cmd+C copies the active selection", () => {
+ clearAutomationClipboard();
+ usePlayerStore.setState({ elements: [bgmElement], selectedElementId: "bgm" });
+ usePlayerStore
+ .getState()
+ .setAutomationSelection({ elementKey: "bgm", target: "volume", t0: 2, t1: 4 });
+ setup({});
+ combo("c");
+ const entry = readClipboard(null);
+ expect(entry?.span).toBe(2);
+ expect(entry?.points.map((p) => p.t)).toEqual([0, 2]);
+ });
+
+ it("Cmd+V with no selection pastes at the playhead and selects the pasted span", () => {
+ clearAutomationClipboard();
+ // Duration wide enough that the playhead (5s) is not clamped down by the
+ // 0..duration-span bound — this is a paste-at-playhead test, not a
+ // clamp-boundary test.
+ usePlayerStore.setState({
+ elements: [{ ...bgmElement, duration: 10 }],
+ selectedElementId: "bgm",
+ currentTime: 5,
+ });
+ usePlayerStore
+ .getState()
+ .setAutomationSelection({ elementKey: "bgm", target: "volume", t0: 2, t1: 4 });
+ const { onCommit } = setup({});
+ combo("c");
+ expect(readClipboard(null)?.span).toBe(2);
+ usePlayerStore.getState().clearAutomationSelection();
+
+ combo("v");
+ const written = onCommit.mock.calls.at(-1)?.[0];
+ const times = (written?.lanes?.[0]?.points ?? []).map((p: { t: number }) => p.t);
+ expect(times).toContain(5); // playhead 5s − element start 0
+ expect(times).toContain(7); // + clipboard span 2
+
+ // Pasting again immediately should land right after the first paste.
+ expect(usePlayerStore.getState().automationSelection).toEqual({
+ elementKey: "bgm",
+ target: "volume",
+ t0: 5,
+ t1: 7,
+ });
+ });
+
+ it("chains a second Cmd+V after the first instead of overwriting it", () => {
+ // The regression this pins: paste leaves its own span selected, so anchoring
+ // at sel.t0 unconditionally made every later press recompute the same atT.
+ clearAutomationClipboard();
+ usePlayerStore.setState({
+ elements: [{ ...bgmElement, duration: 10 }],
+ selectedElementId: "bgm",
+ });
+ usePlayerStore
+ .getState()
+ .setAutomationSelection({ elementKey: "bgm", target: "volume", t0: 2, t1: 4 });
+ const { onCommit } = setup({});
+ combo("c");
+
+ combo("v");
+ const first = (onCommit.mock.calls.at(-1)?.[0]?.lanes?.[0]?.points ?? []).map(
+ (p: { t: number }) => p.t,
+ );
+ expect(first).toContain(2);
+ expect(first).toContain(4);
+
+ combo("v");
+ const second = (onCommit.mock.calls.at(-1)?.[0]?.lanes?.[0]?.points ?? []).map(
+ (p: { t: number }) => p.t,
+ );
+ expect(second).toContain(4);
+ expect(second).toContain(6);
+ expect(usePlayerStore.getState().automationSelection).toEqual({
+ elementKey: "bgm",
+ target: "volume",
+ t0: 4,
+ t1: 6,
+ });
+ });
+
+ it("refuses to paste when the dom-edit layer would write to a different clip", () => {
+ // selectedElementId says "bgm" but the commit channel is still on the
+ // previously selected clip — writing here would serialize bgm's automation
+ // onto that other clip and leave bgm untouched.
+ clearAutomationClipboard();
+ copyRange(null, { target: "volume", points: [{ t: 0, v: 0.5 }] }, VOLUME_RANGE, 0, 2);
+ usePlayerStore.setState({ elements: [bgmElement], selectedElementId: "bgm" });
+ usePlayerStore
+ .getState()
+ .setAutomationSelection({ elementKey: "bgm", target: "volume", t0: 2, t1: 4 });
+ const { onCommit } = setup({ commitTargetKey: "some-other-clip" });
+ const e = combo("v");
+ expect(e.defaultPrevented).toBe(false);
+ expect(onCommit).not.toHaveBeenCalled();
+ });
+
+ it("does not paste from a playhead outside the clip", () => {
+ // No selection on this clip, and the playhead is past its end — there is no
+ // anchor. This used to collapse to the clip's own t=0.
+ clearAutomationClipboard();
+ usePlayerStore.setState({
+ elements: [bgmElement],
+ selectedElementId: "bgm",
+ currentTime: 2,
+ });
+ usePlayerStore
+ .getState()
+ .setAutomationSelection({ elementKey: "bgm", target: "volume", t0: 2, t1: 4 });
+ const { onCommit } = setup({});
+ combo("c");
+ usePlayerStore.getState().clearAutomationSelection();
+ usePlayerStore.setState({ currentTime: 50 });
+ onCommit.mockClear();
+
+ const e = combo("v");
+ expect(e.defaultPrevented).toBe(false);
+ expect(onCommit).not.toHaveBeenCalled();
+ });
+
+ it("Cmd+C over an empty lane leaves an earlier clipboard alone", () => {
+ // An empty capture is byte-identical to the Delete payload, so arming the
+ // clipboard with it turns every later Cmd+V into a destructive flatten.
+ clearAutomationClipboard();
+ copyRange(null, { target: "volume", points: [{ t: 0, v: 0.5 }] }, VOLUME_RANGE, 0, 3);
+ usePlayerStore.setState({ elements: [bgmElement], selectedElementId: "bgm" });
+ usePlayerStore
+ .getState()
+ .setAutomationSelection({ elementKey: "bgm", target: "volume", t0: 1, t1: 2 });
+ setup({ automation: { version: 1, lanes: [{ target: "volume", points: [] }] } });
+
+ const e = combo("c");
+ expect(e.defaultPrevented).toBe(false);
+ expect(readClipboard(null)?.span).toBe(3);
+ });
+
+ it("pastes with CapsLock on, where e.key is an uppercase V", () => {
+ clearAutomationClipboard();
+ usePlayerStore.setState({ elements: [bgmElement], selectedElementId: "bgm" });
+ usePlayerStore
+ .getState()
+ .setAutomationSelection({ elementKey: "bgm", target: "volume", t0: 2, t1: 4 });
+ const { onCommit } = setup({});
+ combo("C");
+ expect(readClipboard(null)?.span).toBe(2);
+
+ onCommit.mockClear();
+ const e = combo("V");
+ expect(e.defaultPrevented).toBe(true);
+ expect(onCommit).toHaveBeenCalled();
+ });
+
+ it("Cmd+V with clipboard content but no resolvable element falls through", () => {
+ clearAutomationClipboard();
+ copyRange(null, { target: "volume", points: [{ t: 0, v: 1 }] }, VOLUME_RANGE, 0, 1);
+ expect(readClipboard(null)).not.toBeNull();
+ usePlayerStore.setState({ elements: [bgmElement], selectedElementId: null });
+ usePlayerStore.getState().clearAutomationSelection();
+ const { onCommit } = setup({});
+ const e = combo("v");
+ expect(e.defaultPrevented).toBe(false);
+ expect(onCommit).not.toHaveBeenCalled();
+ });
});
diff --git a/packages/studio/src/hooks/useAutomationSelectionKeyboard.ts b/packages/studio/src/hooks/useAutomationSelectionKeyboard.ts
index 786a0c683e..354fd7342b 100644
--- a/packages/studio/src/hooks/useAutomationSelectionKeyboard.ts
+++ b/packages/studio/src/hooks/useAutomationSelectionKeyboard.ts
@@ -1,18 +1,43 @@
/**
* Keyboard surface for the active automation selection: Escape clears,
* Delete/Backspace empties the range (anchors pinned, envelope outside
- * untouched). Sibling of useKeyframeKeyboard and copies its contract:
- * capture phase so playback shortcuts cannot swallow keys we act on, inert
- * while any text input has focus, and a key is only consumed when it does
- * something.
+ * untouched), Cmd/Ctrl+C copies it, Cmd/Ctrl+V pastes at the selection's
+ * start (or the playhead) onto the selected clip's lane. Sibling of
+ * useKeyframeKeyboard and copies its contract: capture phase so playback
+ * shortcuts cannot swallow keys we act on, inert while any text input has
+ * focus, and a key is only consumed when it does something.
+ *
+ * Falling through is NOT enough to keep clip-level copy/paste working:
+ * useAppHotkeys listens on `window` with capture, so it always runs before this
+ * document-level listener and `stopImmediatePropagation` here comes too late.
+ * `automationOwnsKey` below is the arbitration that actually works — the
+ * central dispatcher asks it first and stands down.
*/
import { useEffect } from "react";
import { usePlayerStore, type TimelineElement } from "../player/store/playerStore";
import { laneFor, withLane } from "../player/components/automationLaneGeometry";
import { replaceRange } from "../player/components/automationLaneSelection";
-import { resolveAutomationRange, type HfAutomation } from "@hyperframes/core/audio-automation";
+import {
+ copyRange,
+ isLastPasteSpan,
+ markLastPaste,
+ pastePoints,
+ readClipboard,
+} from "../player/components/automationClipboard";
+import {
+ resolveAutomationRange,
+ type AutomationRange,
+ type HfAutomation,
+ type HfAutomationLane,
+} from "@hyperframes/core/audio-automation";
+import { clampNumber } from "../utils/studioHelpers";
import type { AutomationSelection } from "../player/store/automationSelectionSlice";
-import type { UseAutomationLanesResult } from "../player/components/useAutomationLanes";
+import type {
+ AutomationLaneBinding,
+ UseAutomationLanesResult,
+} from "../player/components/useAutomationLanes";
+
+type PlayerState = ReturnType;
function isTextInput(el: Element | null): boolean {
if (!el) return false;
@@ -21,6 +46,46 @@ function isTextInput(el: Element | null): boolean {
return el instanceof HTMLElement && el.isContentEditable;
}
+/**
+ * A Cmd/Ctrl+ chord. `e.key` is normalised because CapsLock makes it
+ * "V"/"C", and useAppHotkeys already lowercases — a raw `e.key === "v"` test
+ * would silently drop the keystroke here while that dispatcher still acted on
+ * it. Shift and Alt are excluded for the same parity reason (useAppHotkeys
+ * gates its own copy/paste on `!shiftKey && !altKey`).
+ */
+function isChord(e: KeyboardEvent, letter: string): boolean {
+ return (e.metaKey || e.ctrlKey) && !e.shiftKey && !e.altKey && e.key.toLowerCase() === letter;
+}
+
+/** A `TimelineElement`'s identity as the selection and lane bindings key by. */
+function elementKeyOf(element: TimelineElement): string {
+ return element.key ?? element.id;
+}
+
+function findElement(elements: TimelineElement[], key: string | null): TimelineElement | null {
+ if (!key) return null;
+ return elements.find((el) => elementKeyOf(el) === key) ?? null;
+}
+
+/**
+ * A selection's element, binding, lane and range — the resolution Delete and
+ * copy both need. Null when the clip is gone, its lane is read-only, or the
+ * target no longer resolves to a range.
+ */
+function resolveSelectionContext(
+ state: PlayerState,
+ lanes: UseAutomationLanesResult,
+ sel: AutomationSelection,
+): { binding: AutomationLaneBinding; lane: HfAutomationLane; range: AutomationRange } | null {
+ const element = findElement(state.elements, sel.elementKey);
+ if (!element) return null;
+ const binding = lanes.bind(element, sel.elementKey === state.selectedElementId);
+ if (binding.readOnly) return null;
+ const range = resolveAutomationRange(sel.target, binding.chain ?? undefined);
+ if (!range) return null;
+ return { binding, lane: laneFor(binding.automation, sel.target), range };
+}
+
/**
* The write that empties the active selection, or null when there is nothing
* to do: the clip is gone, its lane is read-only, the target no longer
@@ -29,24 +94,231 @@ function isTextInput(el: Element | null): boolean {
* keyboard dispatch should carry.
*/
function resolveDeleteWrite(
- state: { elements: TimelineElement[]; selectedElementId: string | null },
+ state: PlayerState,
lanes: UseAutomationLanesResult,
sel: AutomationSelection,
): { onCommit(next: HfAutomation): void; next: HfAutomation } | null {
- const element = state.elements.find((el) => (el.key ?? el.id) === sel.elementKey);
- if (!element) return null;
- const binding = lanes.bind(element, sel.elementKey === state.selectedElementId);
- if (binding.readOnly) return null;
- const lane = laneFor(binding.automation, sel.target);
- const range = resolveAutomationRange(sel.target, binding.chain ?? undefined);
- if (!range || lane.points.length === 0) return null;
- const points = replaceRange({ lane, range, t0: sel.t0, t1: sel.t1, inner: [] });
+ const ctx = resolveSelectionContext(state, lanes, sel);
+ if (!ctx || ctx.lane.points.length === 0) return null;
+ const points = replaceRange({
+ lane: ctx.lane,
+ range: ctx.range,
+ t0: sel.t0,
+ t1: sel.t1,
+ inner: [],
+ });
return {
- onCommit: binding.onCommit,
- next: withLane(binding.automation, { target: sel.target, points }),
+ onCommit: ctx.binding.onCommit,
+ next: withLane(ctx.binding.automation, { target: sel.target, points }),
};
}
+/**
+ * The lane target Cmd+V writes to: the active selection's, when the
+ * selection belongs to the same clip the paste is landing on, else the
+ * clip's first automation lane. A selection left over on a different clip
+ * does not redirect the paste.
+ */
+function pasteTargetName(
+ binding: AutomationLaneBinding,
+ elementKey: string,
+ sel: AutomationSelection | null,
+): string | undefined {
+ if (sel && sel.elementKey === elementKey) return sel.target;
+ return binding.lanes[0]?.target;
+}
+
+/**
+ * Where Cmd+V lands, or null when nothing is selected, the clip's lanes are
+ * read-only, it has no automation lane to fall back to, or the dom-edit layer
+ * would write the result to a DIFFERENT clip.
+ *
+ * That last guard is the one with teeth. `binding.onCommit` persists through
+ * handleDomAttributeQuietCommit, which targets whatever the dom-edit layer
+ * currently has selected — not the element `bind()` was handed (see the
+ * doc-comment on `onSelect` in useAutomationLanes). Selecting a clip in the
+ * timeline sets `selectedElementId` synchronously but resolves the dom-edit
+ * selection asynchronously, so clicking clip B and immediately pressing Cmd+V
+ * would serialize B's automation onto A. Every other lane path is a pointer
+ * gesture on the lane itself, which cannot run before the selection lands;
+ * paste is the only one that can, so it refuses rather than write blind.
+ */
+function resolvePasteTarget(
+ state: PlayerState,
+ lanes: UseAutomationLanesResult,
+ sel: AutomationSelection | null,
+): {
+ elementKey: string;
+ element: TimelineElement;
+ target: string;
+ binding: AutomationLaneBinding;
+ lane: HfAutomationLane;
+ range: AutomationRange;
+} | null {
+ const element = findElement(state.elements, state.selectedElementId);
+ if (!element) return null;
+ const elementKey = elementKeyOf(element);
+ const binding = lanes.bind(element, true);
+ if (binding.readOnly) return null;
+ if (binding.commitTargetKey !== elementKey) return null;
+ const target = pasteTargetName(binding, elementKey, sel);
+ if (!target) return null;
+ const range = resolveAutomationRange(target, binding.chain ?? undefined);
+ if (!range) return null;
+ return { elementKey, element, target, binding, lane: laneFor(binding.automation, target), range };
+}
+
+/** Is the playhead over this clip? Mirrors TimelineAutomationLaneSlot's own
+ * in-clip test, which is what decides a lane draws a playhead at all. */
+function playheadInClip(state: PlayerState, element: TimelineElement): boolean {
+ return (
+ state.currentTime >= element.start && state.currentTime <= element.start + element.duration
+ );
+}
+
+/**
+ * Clip-local seconds a `span`-wide paste should start at, or null when nothing
+ * can anchor it.
+ *
+ * Three refusals, all of which used to be silent mispastes:
+ * - A span wider than the clip has nowhere to go. Clamping the start to 0 still
+ * writes breakpoints past the clip's end and leaves a selection whose far
+ * edge can never be grabbed again.
+ * - A playhead outside the clip is not an anchor. It used to collapse to the
+ * clip's own t=0, so a playhead at 0:00 pasted into the head of a clip
+ * starting at 0:30.
+ * - No selection on this clip and no in-clip playhead means no anchor at all.
+ *
+ * A repeated Cmd+V chains. Paste leaves its own span selected (the user's only
+ * feedback that it landed), so anchoring at `sel.t0` unconditionally made the
+ * second press overwrite the first. When the live selection is exactly the mark
+ * the last paste left, anchor at its END; a selection the user drew themselves
+ * still pastes at its start.
+ */
+function pasteAnchor(
+ state: PlayerState,
+ element: TimelineElement,
+ span: number,
+ sel: AutomationSelection | null,
+): number | null {
+ if (span > element.duration) return null;
+ const onThisElement = sel !== null && sel.elementKey === elementKeyOf(element);
+ const raw = onThisElement
+ ? isLastPasteSpan(sel)
+ ? sel.t1
+ : sel.t0
+ : playheadInClip(state, element)
+ ? state.currentTime - element.start
+ : null;
+ if (raw === null) return null;
+ // Keeps the whole pasted span inside the clip — including a chain that has
+ // walked to the end — so its own selection stays grabbable.
+ return clampNumber(raw, 0, element.duration - span);
+}
+
+/**
+ * Cmd/Ctrl+V: paste the clipboard onto the selected clip's lane, at the active
+ * selection or the playhead. Returns false (untouched event) when the chord
+ * doesn't match, there is nothing to paste, or no lane can take it.
+ * Checked ahead of the "no selection" guard in the handler below: paste must
+ * work from the playhead with no active selection at all.
+ */
+function handlePaste(
+ e: KeyboardEvent,
+ state: PlayerState,
+ lanes: UseAutomationLanesResult,
+): boolean {
+ if (!isChord(e, "v")) return false;
+ const clip = readClipboard(state.timelineProjectId);
+ if (!clip) return false;
+ const sel = state.automationSelection;
+ const paste = resolvePasteTarget(state, lanes, sel);
+ if (!paste) return false;
+ const atT = pasteAnchor(state, paste.element, clip.span, sel);
+ if (atT === null) return false;
+
+ const t1 = atT + clip.span;
+ const inner = pastePoints(clip, paste.range, atT);
+ const points = replaceRange({ lane: paste.lane, range: paste.range, t0: atT, t1, inner });
+
+ e.preventDefault();
+ e.stopImmediatePropagation();
+ paste.binding.onCommit(withLane(paste.binding.automation, { target: paste.target, points }));
+ // Select the pasted span — the only feedback that it landed — and mark it, so
+ // an immediate second Cmd+V recognises this selection as the paste's own and
+ // chains right after it instead of overwriting it.
+ const mark = { elementKey: paste.elementKey, target: paste.target, t0: atT, t1 };
+ state.setAutomationSelection(mark);
+ markLastPaste(mark);
+ return true;
+}
+
+/** Cmd/Ctrl+C on the active selection. Returns false when the chord doesn't
+ * match, the selection no longer resolves to a copyable lane, or the lane is
+ * empty so there is no shape to capture. */
+function handleCopy(
+ e: KeyboardEvent,
+ state: PlayerState,
+ lanes: UseAutomationLanesResult,
+ sel: AutomationSelection,
+): boolean {
+ if (!isChord(e, "c")) return false;
+ const ctx = resolveSelectionContext(state, lanes, sel);
+ if (!ctx) return false;
+ if (!copyRange(state.timelineProjectId, ctx.lane, ctx.range, sel.t0, sel.t1)) return false;
+ e.preventDefault();
+ e.stopImmediatePropagation();
+ return true;
+}
+
+/**
+ * Will an automation range claim this keystroke? Asked by useAppHotkeys, which
+ * listens on `window` with capture and therefore always runs BEFORE this
+ * hook's document listener — so `stopImmediatePropagation` cannot arbitrate and
+ * the dispatcher has to stand down of its own accord. Without it Cmd+C armed
+ * both clipboards and Cmd+V ran the whole clip-duplication path (read file →
+ * insert → save with history → reload preview) alongside the automation write:
+ * two async read-modify-writes of one file from one keypress.
+ *
+ * Store and clipboard only, no lane binding, so the dispatcher can call it
+ * without holding the binding factory. That leaves one accepted residual: the
+ * predicate cannot see a read-only lane, an unresolvable target, or the
+ * dom-edit target mismatch `resolvePasteTarget` guards, so in those rare cases
+ * the keystroke is a no-op instead of falling through to clip copy/paste. A
+ * dead key beats today's double write.
+ */
+export function automationOwnsKey(e: KeyboardEvent): boolean {
+ if (isTextInput(document.activeElement)) return false;
+ const state = usePlayerStore.getState();
+ if (isChord(e, "c")) return state.automationSelection !== null;
+ if (!isChord(e, "v")) return false;
+ const clip = readClipboard(state.timelineProjectId);
+ if (!clip) return false;
+ const element = findElement(state.elements, state.selectedElementId);
+ if (!element) return false;
+ // Same anchor resolution the handler uses, so predicate and handler cannot
+ // disagree about whether the paste has somewhere to land.
+ return pasteAnchor(state, element, clip.span, state.automationSelection) !== null;
+}
+
+/** Delete/Backspace on the active selection. Returns false when the key
+ * doesn't match or there is nothing to empty. */
+function handleDelete(
+ e: KeyboardEvent,
+ state: PlayerState,
+ lanes: UseAutomationLanesResult,
+ sel: AutomationSelection,
+): boolean {
+ const isDeleteKey = e.key === "Delete" || e.key === "Backspace";
+ if (!isDeleteKey || e.metaKey || e.ctrlKey) return false;
+ const write = resolveDeleteWrite(state, lanes, sel);
+ if (!write) return false;
+ e.preventDefault();
+ e.stopImmediatePropagation();
+ write.onCommit(write.next);
+ return true;
+}
+
export function useAutomationSelectionKeyboard({
lanes,
}: {
@@ -55,7 +327,16 @@ export function useAutomationSelectionKeyboard({
useEffect(() => {
const handler = (e: KeyboardEvent): void => {
if (isTextInput(document.activeElement)) return;
+ // Somebody upstream already claimed this key. useAppHotkeys is on
+ // window/capture so it always runs first, and it deliberately lets a
+ // keyframe selection outrank an automation range on Delete — without
+ // this, that keystroke deleted the keyframes there AND emptied the range
+ // here, two edits from one press. preventDefault does not stop
+ // propagation, so the claim has to be read, not assumed.
+ if (e.defaultPrevented) return;
const state = usePlayerStore.getState();
+ if (handlePaste(e, state, lanes)) return;
+
const sel = state.automationSelection;
if (!sel) return;
@@ -63,15 +344,8 @@ export function useAutomationSelectionKeyboard({
state.clearAutomationSelection();
return;
}
- const isDeleteKey = e.key === "Delete" || e.key === "Backspace";
- if (!isDeleteKey || e.metaKey || e.ctrlKey) return;
-
- const write = resolveDeleteWrite(state, lanes, sel);
- if (!write) return;
-
- e.preventDefault();
- e.stopImmediatePropagation();
- write.onCommit(write.next);
+ if (handleCopy(e, state, lanes, sel)) return;
+ handleDelete(e, state, lanes, sel);
};
document.addEventListener("keydown", handler, true);
return () => document.removeEventListener("keydown", handler, true);
diff --git a/packages/studio/src/player/components/TimelineAutomationLaneSlot.test.tsx b/packages/studio/src/player/components/TimelineAutomationLaneSlot.test.tsx
index c08f25af44..3684a85524 100644
--- a/packages/studio/src/player/components/TimelineAutomationLaneSlot.test.tsx
+++ b/packages/studio/src/player/components/TimelineAutomationLaneSlot.test.tsx
@@ -28,6 +28,7 @@ function mountSlot(binding: Partial) {
onCommit: vi.fn(),
onSelect: vi.fn(),
readOnly: false,
+ commitTargetKey: "bgm",
selection: null,
onRangeSelect: vi.fn(),
onRangeClear,
diff --git a/packages/studio/src/player/components/automationClipboard.test.ts b/packages/studio/src/player/components/automationClipboard.test.ts
new file mode 100644
index 0000000000..38527a5ebf
--- /dev/null
+++ b/packages/studio/src/player/components/automationClipboard.test.ts
@@ -0,0 +1,79 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+ clearAutomationClipboard,
+ copyRange,
+ pastePoints,
+ readClipboard,
+} from "./automationClipboard";
+import { resolveAutomationRange, VOLUME_RANGE } from "@hyperframes/core/audio-automation";
+import type { HfAutomationLane } from "@hyperframes/core/audio-automation";
+
+const duck: HfAutomationLane = {
+ target: "volume",
+ points: [
+ { t: 2, v: 1, curve: -0.4 },
+ { t: 3, v: 0.25 },
+ { t: 4, v: 1 },
+ ],
+};
+
+beforeEach(clearAutomationClipboard);
+
+describe("automation clipboard", () => {
+ it("copies the range rebased to zero", () => {
+ copyRange("project-a", duck, VOLUME_RANGE, 2, 4);
+ const entry = readClipboard("project-a");
+ expect(entry?.span).toBe(2);
+ expect(entry?.points.map((p) => p.t)).toEqual([0, 1, 2]);
+ expect(entry?.points[0]?.curve).toBe(-0.4);
+ });
+
+ it("pastes at a new time on the same axis unchanged", () => {
+ copyRange("project-a", duck, VOLUME_RANGE, 2, 4);
+ const entry = readClipboard("project-a");
+ expect(entry).not.toBeNull();
+ if (!entry) return;
+ const pts = pastePoints(entry, VOLUME_RANGE, 10);
+ expect(pts.map((p) => p.t)).toEqual([10, 11, 12]);
+ expect(pts.map((p) => p.v)).toEqual([1, 0.25, 1]);
+ });
+
+ it("maps values through unit space onto a different parameter", () => {
+ const wet = resolveAutomationRange("fx.r.wet", {
+ version: 1,
+ nodes: [{ type: "reverb", id: "r", params: {} }],
+ });
+ expect(wet).toBeTruthy();
+ if (!wet) return;
+ copyRange("project-a", duck, VOLUME_RANGE, 2, 4);
+ const entry = readClipboard("project-a");
+ if (!entry) return;
+ const pts = pastePoints(entry, wet, 0);
+ // volume 1 (unit 1) → wet max; volume 0.25 (unit 0.25) → a quarter up wet's axis
+ expect(pts[0]?.v).toBeCloseTo(wet.max, 5);
+ expect(pts[1]?.v).toBeCloseTo(wet.min + 0.25 * (wet.max - wet.min), 5);
+ });
+
+ it("reads null when nothing was copied", () => {
+ expect(readClipboard("project-a")).toBeNull();
+ });
+
+ it("does not hand a range copied in one project to another", () => {
+ copyRange("project-a", duck, VOLUME_RANGE, 2, 4);
+ expect(readClipboard("project-b")).toBeNull();
+ });
+
+ it("drops the entry for good once another project has read past it", () => {
+ copyRange("project-a", duck, VOLUME_RANGE, 2, 4);
+ readClipboard("project-b");
+ // Not merely hidden from B: switching back must not resurrect a shape whose
+ // source clip may have been edited or deleted while the project was closed.
+ expect(readClipboard("project-a")).toBeNull();
+ });
+
+ it("keeps serving the entry inside its own project", () => {
+ copyRange("project-a", duck, VOLUME_RANGE, 2, 4);
+ expect(readClipboard("project-a")?.span).toBe(2);
+ expect(readClipboard("project-a")?.span).toBe(2);
+ });
+});
diff --git a/packages/studio/src/player/components/automationClipboard.ts b/packages/studio/src/player/components/automationClipboard.ts
new file mode 100644
index 0000000000..37bd71a198
--- /dev/null
+++ b/packages/studio/src/player/components/automationClipboard.ts
@@ -0,0 +1,136 @@
+/**
+ * Internal clipboard for automation ranges. Module-level, not the OS
+ * clipboard — points are not text, and useClipboard is already the DOM-element
+ * channel. Values cross parameters through unit space, so a volume duck
+ * pasted onto a log-scaled wet knob lands proportionally, not literally.
+ *
+ * Project-scoped by itself rather than by a caller, because the failure is
+ * destructive and silent: a range copied in project A pasted into B is remapped
+ * through A's captured `sourceRange` for an FX node B may not even have, and the
+ * keystroke is consumed so clip paste never runs. Every entry point carries the
+ * project it is speaking for and a mismatch empties the module, so no future
+ * caller can forget the guard — the same shape `keyframeSlice` uses to discard a
+ * request from a previous session.
+ */
+import {
+ sampleAutomationLane,
+ type AutomationRange,
+ type HfAutomationLane,
+ type HfAutomationPoint,
+} from "@hyperframes/core/audio-automation";
+import { fromUnit, toUnit } from "./automationLaneGeometry";
+import { pointsIn } from "./automationLaneSelection";
+
+export interface AutomationClipboardEntry {
+ sourceRange: AutomationRange;
+ span: number;
+ points: HfAutomationPoint[];
+}
+
+/** The span one paste covered, in the same shape as the selection it left. */
+export interface AutomationPasteMark {
+ elementKey: string;
+ target: string;
+ t0: number;
+ t1: number;
+}
+
+let ownerProjectId: string | null = null;
+let entry: AutomationClipboardEntry | null = null;
+let lastPaste: AutomationPasteMark | null = null;
+
+/**
+ * Rebind the module to `projectId`, discarding anything captured under a
+ * different one. Called by both entry points, so the mark is scoped
+ * transitively: `isLastPasteSpan` can only ever see a mark left by a paste in
+ * the project that most recently read the clipboard.
+ *
+ * `null` (no timeline session yet) is a project id like any other — it can hold
+ * an entry, and the first real session id evicts it.
+ */
+function useProject(projectId: string | null): void {
+ if (projectId === ownerProjectId) return;
+ ownerProjectId = projectId;
+ entry = null;
+ lastPaste = null;
+}
+
+/**
+ * Capture `[t0, t1]` rebased to zero. Returns false — leaving the clipboard as
+ * it was — when the lane has nothing to capture.
+ *
+ * `pointsIn` reports only explicit breakpoints, so a range drawn over a smooth
+ * stretch of envelope has none. Storing that as `points: []` would arm a
+ * clipboard whose paste is byte-identical to the Delete write, so every later
+ * Cmd+V would erase its destination instead of reproducing the copied shape.
+ * Over a lane that HAS an envelope the range is a real flat or sloped segment,
+ * captured by sampling both edges (what `replaceRange`'s own anchors do). Over
+ * an entirely empty lane there is no shape at all, so nothing is stored — a
+ * failed copy leaves an earlier clipboard alone rather than destroying it.
+ */
+export function copyRange(
+ projectId: string | null,
+ lane: HfAutomationLane,
+ range: AutomationRange,
+ t0: number,
+ t1: number,
+): boolean {
+ const inner = pointsIn(lane, t0, t1).map((p) => ({ ...p, t: p.t - t0 }));
+ if (inner.length === 0 && lane.points.length === 0) return false;
+ useProject(projectId);
+ entry = {
+ sourceRange: range,
+ span: t1 - t0,
+ points:
+ inner.length > 0
+ ? inner
+ : [
+ { t: 0, v: sampleAutomationLane(lane, t0, range.scale) },
+ { t: t1 - t0, v: sampleAutomationLane(lane, t1, range.scale) },
+ ],
+ };
+ return true;
+}
+
+export function readClipboard(projectId: string | null): AutomationClipboardEntry | null {
+ useProject(projectId);
+ return entry;
+}
+
+export function pastePoints(
+ from: AutomationClipboardEntry,
+ target: AutomationRange,
+ atT: number,
+): HfAutomationPoint[] {
+ return from.points.map((p) => ({
+ ...p,
+ t: atT + p.t,
+ v: fromUnit(target, toUnit(from.sourceRange, p.v)),
+ }));
+}
+
+/**
+ * Remember the span a paste just covered and left selected, so the next Cmd+V
+ * can tell that selection apart from one the user drew and chain after it
+ * instead of overwriting it.
+ */
+export function markLastPaste(mark: AutomationPasteMark): void {
+ lastPaste = { ...mark };
+}
+
+/** True when `mark` is exactly the span the last paste left selected. */
+export function isLastPasteSpan(mark: AutomationPasteMark): boolean {
+ if (!lastPaste) return false;
+ return (
+ lastPaste.elementKey === mark.elementKey &&
+ lastPaste.target === mark.target &&
+ lastPaste.t0 === mark.t0 &&
+ lastPaste.t1 === mark.t1
+ );
+}
+
+export function clearAutomationClipboard(): void {
+ ownerProjectId = null;
+ entry = null;
+ lastPaste = null;
+}
diff --git a/packages/studio/src/player/components/useAutomationLanes.ts b/packages/studio/src/player/components/useAutomationLanes.ts
index 1274b12499..1862d4d33c 100644
--- a/packages/studio/src/player/components/useAutomationLanes.ts
+++ b/packages/studio/src/player/components/useAutomationLanes.ts
@@ -18,7 +18,11 @@ import {
type HfAutomationLane,
} from "@hyperframes/core/audio-automation";
import type { HfAudioFxChain } from "@hyperframes/core/audio-fx";
-import { useDomEditActionsContextOptional } from "../../contexts/DomEditContext";
+import {
+ useDomEditActionsContextOptional,
+ useDomEditSelectionContextOptional,
+} from "../../contexts/DomEditContext";
+import { resolveTimelineIdForSelection } from "../../utils/studioHelpers";
import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
import { usePlayerStore, type TimelineElement } from "../store/playerStore";
import type { AutomationSelection } from "../store/automationSelectionSlice";
@@ -41,6 +45,15 @@ export interface AutomationLaneBinding {
*/
onSelect(): void;
readOnly: boolean;
+ /**
+ * The timeline clip `onCommit`/`onPreview` will ACTUALLY persist to, which is
+ * whatever the dom-edit layer has selected — not necessarily the element this
+ * binding was made for (see `onSelect` below). Null outside an edit session or
+ * when the dom-edit selection maps to no clip. Resolved exactly the way
+ * applyDomSelection resolves it, so in a settled selection it equals the bound
+ * element's key; it lags only in the window a non-gesture caller can hit.
+ */
+ commitTargetKey: string | null;
/** This element's active time selection, or null if none / it belongs to a
* different element. */
selection: AutomationSelection | null;
@@ -58,10 +71,23 @@ export function useAutomationLanes(): UseAutomationLanesResult {
// Optional: the player also runs outside Studio, where there is no edit
// session. There the lanes render read-only, which is the right fallback.
const domEdit = useDomEditActionsContextOptional();
+ const domEditSelection = useDomEditSelectionContextOptional()?.domEditSelection ?? null;
+ const elements = usePlayerStore((s) => s.elements);
const automationSelection = usePlayerStore((s) => s.automationSelection);
const setAutomationSelection = usePlayerStore((s) => s.setAutomationSelection);
const clearAutomationSelection = usePlayerStore((s) => s.clearAutomationSelection);
+ // Read from the SAME render as the commit handlers below: both contexts update
+ // in one commit, so a handler and this key can never describe different
+ // moments. activeCompPath is not needed — resolveTimelineIdForSelection only
+ // uses it as a fallback for a selection with no sourceFile of its own, and
+ // DomEditSelection always carries one.
+ const commitTargetKey = useMemo(
+ () =>
+ domEditSelection ? resolveTimelineIdForSelection(domEditSelection, elements, null) : null,
+ [domEditSelection, elements],
+ );
+
const bind = useCallback(
(element: TimelineElement, isSelected: boolean): AutomationLaneBinding => {
const chain = elementFxChain(element);
@@ -93,6 +119,7 @@ export function useAutomationLanes(): UseAutomationLanesResult {
// Selecting is its own gesture; the lane goes live after it.
onSelect: () => void domEdit?.handleTimelineElementSelect(element),
readOnly: !domEdit || !isSelected,
+ commitTargetKey: domEdit ? commitTargetKey : null,
selection: automationSelection?.elementKey === elementKey ? automationSelection : null,
onRangeSelect: (target, t0, t1) => {
if (!domEdit || !isSelected) return;
@@ -101,7 +128,13 @@ export function useAutomationLanes(): UseAutomationLanesResult {
onRangeClear: () => clearAutomationSelection(),
};
},
- [domEdit, automationSelection, setAutomationSelection, clearAutomationSelection],
+ [
+ domEdit,
+ commitTargetKey,
+ automationSelection,
+ setAutomationSelection,
+ clearAutomationSelection,
+ ],
);
return useMemo(() => ({ bind }), [bind]);
diff --git a/packages/studio/src/player/store/playerStore.test.ts b/packages/studio/src/player/store/playerStore.test.ts
index d03b4238cf..6d0d9d24b1 100644
--- a/packages/studio/src/player/store/playerStore.test.ts
+++ b/packages/studio/src/player/store/playerStore.test.ts
@@ -557,6 +557,21 @@ describe("usePlayerStore", () => {
expectResettableDefaults(usePlayerStore.getState());
});
+ it("drops an automation time selection on reset and on a project switch", () => {
+ const sel = { elementKey: "bgm", target: "volume", t0: 1, t1: 2 };
+
+ usePlayerStore.getState().setAutomationSelection(sel);
+ usePlayerStore.getState().reset();
+ expect(usePlayerStore.getState().automationSelection).toBeNull();
+
+ // The switch matters more than reset(): a stale elementKey can match a
+ // same-keyed clip in the new project and redirect a paste to its old t0.
+ usePlayerStore.getState().beginTimelineSession("project-a");
+ usePlayerStore.getState().setAutomationSelection(sel);
+ usePlayerStore.getState().beginTimelineSession("project-b");
+ expect(usePlayerStore.getState().automationSelection).toBeNull();
+ });
+
it("does not reset playbackRate, audioMuted, loopEnabled, zoomMode, or manualZoomPercent", () => {
const store = usePlayerStore.getState();
store.setPlaybackRate(2);
diff --git a/packages/studio/src/player/store/playerStore.ts b/packages/studio/src/player/store/playerStore.ts
index ef60fb1e8a..4523d85771 100644
--- a/packages/studio/src/player/store/playerStore.ts
+++ b/packages/studio/src/player/store/playerStore.ts
@@ -237,6 +237,10 @@ export function createTimelineResetState() {
motionPathArmed: false,
motionPathCreateAvailable: false,
selectedKeyframes: new Set(),
+ // Ephemeral like every other selection here. A range surviving a project
+ // switch can match a same-keyed clip in the new project and redirect a
+ // paste through `sel.elementKey === paste.elementKey` to a stale t0.
+ automationSelection: null,
expandedClipIds: new Set(),
focusedEaseSegment: null,
selectedElementIds: new Set(),