Commit Graph
2838 Commits
Author SHA1 Message Date
Vance Ingalls 373cdbbcb8 feat: ramp a whole preset with one lane, and make Off its zero
A preset's nodes share no automatable parameter, and its worklet effects
(compressor, limiter) expose no AudioParams at all — Clean Voice could
only ever have automated 3 of its 5 nodes. So there was nothing to aim a
lane at, and no way to bring a preset in gradually.

**The graph wraps each preset's run in a wet/dry pair.** The rest of the
chain stays a strict series, which is right for an effect the author
placed: it is either in the path or it is not. A preset is not one effect
— it is several added as a unit, and "how much of it is applied" is a
question about the unit. One crossfade answers it for every preset
including the worklet ones, and it cannot go half-wrong the way seven
lanes can. The dry leg bridges the whole run, so amount 0 is the
untouched signal rather than a quieter version of the processed one.

Consecutive nodes only, matching what the rack already brackets: a preset
pulled apart by a reorder is no longer a unit, and wrapping across the
gap would route the effect between its members through the dry leg too.

**`fx.preset.<id>` is a new lane target.** Parsed before the 3-part fx
form, which it structurally is — with a reserved node id an effect can
never have, since ids are minted `n1`, `n2`, …. It resolves only for a
preset the chain actually carries, so a lane left behind by a removed
preset is dropped at read time, the same contract an orphaned node lane
has.

**Off is amount 0, not `enabled: false`.** The switch and the lane are
now the same value — one notion of how much of a preset is applied, with
the switch at its two ends. Writing `enabled` would take the nodes out of
the graph, which a lane cannot do part-way and cannot do without a
rebuild that restarts the audio. The panel also grows an Amount slider,
so half-applied is something an author can just set.

Changing the amount is a values-only update, pushed into the running
graph. A `presetAmount` in a chain is clamped to 0..1 on the way in: two
gains in opposition, so past 1 the dry leg goes negative rather than the
preset getting louder.

Falsified: a blend ignoring the stored amount, an amount not pushed on
update, and the clamp each fail a test. The round-trip — the §4 invariant
that a new node field must be in BOTH the parser and the writer — had no
test until a mutation survived one; dropping it from either half now
fails.

core 1770 (113 files) · studio 3703 + 18 todo · engine services 739 + 3.
2026-08-10 15:39:06 -07:00
Vance Ingalls e727e39b7f feat(studio): switch a preset off, or take it out, as one thing
The bracket said a preset was one thing the author added, and then made
them treat it as five: every member module had its own On / ↑ / ↓ / ×
and the preset itself had none. Switching off Telephone meant reaching
into seven modules and toggling each — exactly the bookkeeping the
bracket exists to remove.

The run head now carries the two controls that belong to the whole:

- **On/Off bypasses every node it wrote**, and leaves anything the author
  added themselves alone. A bypass, not a delete: the settings survive,
  which is what makes a preset worth trying rather than committing to.
- **× takes it back out whole**, with its lanes. An orphaned lane keeps
  driving a parameter that is no longer in the graph, and with ids minted
  lowest-free the next effect added inherits it — the same contract
  removing a single node already has.

It reads as On while *any* of it is still running. "Some of it is
bypassed" is not a state an author set, it is one they arrived at by
toggling a member, and the switch has to offer to stop the preset rather
than claim it has already stopped.

Also fixes the mount helper in the section tests, which never passed
`onRemoveNodeAutomation` — so nothing in that file could have caught a
lane leak on removal.

studio 3700 passing, 18 todo.
2026-08-10 15:39:05 -07:00
Vance Ingalls e015f834c2 fix(studio): seed a profiled effect on its curve, not at registry defaults
Found in a running studio, which is the only place it could be found: add
a compressor and the module opens reading **Evenness 0.67** with its
make-up gain at 0 dB.

The registry's defaults are not a point on the profile's curve, and
`audioFxProfileStrength` reads the knob back by inverting that curve — so
a default-seeded compressor reports a strength it was never set to, and
every parameter under the knob disagrees with it. That is the
"quieter as you turn it up" failure the measurement pass fixed, arriving
on the very first frame instead.

Adding a profiled effect now seeds it through the profile at 0.5, so the
knob and the mechanism agree from the start. Everything else still
arrives exactly as the registry declares it.

Falsified: restoring the default seed fails the new test. The old
"seeded with its declared defaults" case asserted the behaviour being
fixed, and now uses an effect that has no derived knob — which is what it
was really about.

studio 3696 passing, 18 todo · core 1762.
2026-08-10 15:39:04 -07:00
Vance Ingalls 12a67ab82e feat: one knob for the five effects that cannot honestly have one
The last unbuilt piece of the rack design. A compressor has seven
controls and an author wants one — but unlike a filter or a delay, no
single one of them can be its face: threshold means nothing without ratio,
ratio means nothing without make-up gain. So the knob is derived, exactly
as `carveProfile` already turns one number into six for the carve.

`EFFECT_COPY[id].primary === "strength"` was already the copy layer saying
"this module wants this treatment", and a test now asserts the profile set
matches that list exactly — a missing profile leaves a module opening on
all seven controls, and an extra one is a knob nobody asked for.

**Continuous, not the three-point tables the design proposed.** A table
makes gentle/middle/strong three settings to pick between, and the thing
being modelled is one axis — which the carve's knob has already proved
reads. The proposal's figures survive as anchors where they held up.

## Three of the five figures were wrong, and rendering is what showed it

Full numbers and method in `~/audio-fx-profiles-ab/README.md`.

- **Compressor make-up was too small and not linear.** 1/3/7 dB left the
  track 2.5 dB QUIETER at full evenness — an evenness knob that turns the
  track down as it goes up. Gain reduction accelerates as threshold and
  ratio move together, so linear was wrong too; solved as s² × 9.5. Spread
  now falls 19.1 → 8.8 dB with the level unmoved.
- **Saturation's trim went the wrong way.** A soft clipper at −18 dB IS a
  limiter at −18 dB: the proposed −3 dB trim took the peak from 0.496 to
  0.089 and nearly halved RMS, so "Warmth" mostly meant "much quieter".
  Reversed to s² × 2.8 up; RMS now holds within 0.4% while the peak comes
  down, which is the signature of saturation rather than attenuation.
- **The gate did essentially nothing.** The design derived threshold and
  range only; left at the effect's 100 ms default release it moved the
  gaps 0.1 dB against a range asking for 30. Swept, release dominates
  everything else — 0.2 dB at 140 ms, 13.4 dB at 10 ms — so it joins the
  profile. Gaps now fall 29.6 dB with speech unmoved to a tenth of a dB.

Reverb and bitcrush measured correctly as proposed and are unchanged.

The first measurement reported the gate as working when it was doing
nothing at all: a speaking-window measure excludes exactly the windows a
gate acts on. Gaps are measured separately for that reason.

## In the panel

The derived knob renders through the ordinary `FxParamRow`, not through
`FxNodeParams` — it has no AudioParam behind it and nothing to automate.
What automation there is belongs to the parameters it sets, under Details,
where they can be aimed at individually.

It writes mechanism, never the knob: the chain stores what renders, and
`audioFxProfileStrength` reads the knob back by inverting the curve — the
same contract `normalizeCarveSettings` has. A profile merges over what is
there, so a compressor's knee and a saturation's curve type survive the
knob moving.

Falsified: a derived parameter that turns around mid-sweep, one that runs
past its range, a profile that replaces rather than merges, and a panel
that writes the knob instead of the mechanism each fail a test.

core 1762 (113 files) · studio 3695 + 18 todo.
2026-08-10 15:39:03 -07:00
Vance Ingalls e477ec254b feat(studio): draw the rack as the signal path it is
The last of the schematic direction, translated to a one-column panel
rather than the wide diagram the review page draws.

**Both ends named.** IN — this track, OUT — to mix. Two lines, and they
change what the rack is: without them the order reads as a list, and a
list is the one reading that makes "move up" look cosmetic. It is the
most consequential control in the panel — chain order is audible.

**Every step numbered**, counted over what the rack SHOWS rather than
over the chain. The carve's filters and an EQ's bands live inside their
own modules, so counting raw nodes would leave the visible rack jumping
from 02 to 07, and the numbers would read as a bug rather than a
position.

**A preset draws as one thing.** Applying one used to drop five loose
rows in with nothing saying they arrived together — the same failure the
carve module exists to fix, one level down. Consecutive nodes only: a
preset pulled apart by a reorder is no longer a unit, and a bracket
around the gap would claim an adjacency the signal path does not have.

Falsified: numbering by chain index fails the path test, and grouping a
preset's nodes regardless of adjacency fails the run test.

studio 3695 passing, 18 todo.
2026-08-10 15:39:02 -07:00
Vance Ingalls a2ea0a66c3 feat(studio): letter the families, and tint each module inside its own
A rack of eight modules is eight lines of text, and reading it top to
bottom should not mean reading eight names. Each family letters
differently, so an author knows what KIND of module they are looking at
with the label out of focus and the word only confirms it.

Two faces of type, as budgeted in `plans/audio-fx-ux/README.md`. The sans
carries four families apart by weight, case and tracking — filters light
and widely tracked like a measuring instrument, dynamics heavy and tight
because it grips the signal, time thin and very wide because it is
atmosphere rather than control. The serif is spent on the single family
that behaves differently from all of them: non-linear is the only one
that generates signal rather than measuring or shaping what is there, and
it should not look like the others.

`smart` is the fifth and is not a registry group — the carve, the Tone EQ
and the leveller, which measure the audio and write their own settings.
Monospace, because what they show IS a readout: numbers something else
decided.

Alongside it a tint step per module WITHIN its family, derived from
position in the registry rather than assigned by hand, so two filters
read as two different modules without reading as two different families
and adding an effect upstream never re-colours its siblings. It sits on
the card's left edge rather than on the text: the name already carries
the family in its lettering, and colouring it too would fight the panel's
own tokens for automated and bypassed. Kept to 62–76% lightness at low
saturation for the same reason.

Falsified: flattening the tint step fails one test, and lettering
non-linear like dynamics fails the other.

studio 3692 passing, 18 todo.
2026-08-10 15:39:02 -07:00
Vance Ingalls 13f574f3e6 feat: the shared frequency ruler, so the vocabulary gets taught
`BANDS` has named the ranges since the copy layer landed — rumble,
weight, mud, middle, presence, edge, air — and nothing showed them. The
rack spoke entirely in Hz, which mean nothing to somebody who has not
been taught them, and the words that would teach them sat unread in core.

Every spectral module now shows where it acts on one ruler. Two things at
once, deliberately: the bar says where this module works relative to
everything else, and the caption names the range and what lives there.
A bar alone is decoration; a caption alone does not teach the shape.

Log-spaced, because hearing is. Rumble is 20–80 Hz — three tenths of one
percent of the range linearly and about a fifth of it by ear — so laid
out linearly the bottom six bands collapse into a sliver and the ruler
teaches nothing. A test asserts the bottom segment is over a tenth of the
bar, which a linear layout fails.

Segments outside what the module can reach are dimmed rather than hidden:
a filter that only works in the bottom three bands should not look like
it could move anywhere, and it should still be legible against the whole
range.

`audioBandAt` clamps past both ends rather than returning nothing — 15 Hz
is still rumble to anybody who can hear it, and the alternative is a
filter parked at the edge of its range having no name at all. Boundaries
belong to the band they open, or a filter at exactly 250 Hz reads as
Weight while the ruler beside it highlights Mud.

Nothing under an effect with no range to place: there is nothing spectral
about a limiter, and a bar under one would be a decoration claiming to be
information.

core 1754 passing (112 files), studio 3690 passing / 18 todo.
2026-08-10 15:39:01 -07:00
Vance Ingalls 96f1e9c19d feat(studio): two faces — a module opens on one knob, the rest one click away
Rule 1 of `plans/audio-fx-ux/README.md`. A module opens on its name, a
line saying what it is for, and the single control that carries it; every
other parameter is behind a Details disclosure. Nothing is hidden — it is
ordered. `EFFECT_COPY.primary` names that control and `primaryEnds` says
what its two ends sound like, which is the question an author actually
has: a number tells them where the knob is, not which way to move it.

The DSP name moves onto the disclosure itself, so it is read at the
moment the author asks what this really is and never before.

Ten of the fifteen effects get this. The other five — compressor, gate,
saturate, reverb, bitcrush — name their primary as "strength", meaning
they want a single DERIVED control over several parameters, which is
`PROFILES`, whose figures are proposed rather than measured and which has
not shipped. They open on all their controls until it does. That is the
honest state: inventing one knob for them now would be a knob that lies
about what it sets. The lookup needs no special case for it either —
"strength" names no parameter today, and the day it does name one, this
starts using it without being told.

Worth naming: `peaking`'s primary is "how much", and that only became
coherent in the commit before this one. Boosting an unspecified frequency
means nothing, so one knob was a lie while the module was generic; now
that picking the job is what picks the range, it is the whole truth.

The disclosure is local state, keyed by node like the row itself, so it
stays with its effect across a reorder — and an effect arriving in the
open slot arrives closed, like any other.

Tests that address a non-primary knob now open Details first, which is
also the gesture a user makes. Falsified: expanding Details unconditionally
fails the two-faces test, and dropping the "is it a real parameter" guard
fails three.

studio 3688 passing, 18 todo.
2026-08-10 15:39:01 -07:00
Vance Ingalls 8281023170 feat: offer the job, not the machine — the range IS the module
"Shape One Range" has three controls and no honest way to nominate one of
them as the knob that matters. The copy nominated *how much*, which is
incoherent: boosting an unspecified frequency means nothing. The range is
the first decision, not the second — `plans/audio-fx-ux/README.md`
§"The hole in the single-knob rule", where B is named as the answer.

So the add menu offers the decision instead of the machine. Five jobs —
Tame Boominess, Reduce Mud, Reduce Boxiness, Add Clarity, Soften
Harshness — each a peaking filter with its frequency already chosen, low
to high, which is the order an author hears them in. Picking the module
is picking the range, so one knob is honest rather than a simplification
hiding the real choice. `peaking` is no longer offered as itself: two
doors to the same effect, one of them the incoherent one, is worse than
either alone.

Every job is one the preset catalogue already ships, at the settings it
ships it with — a test asserts that. The list names the vocabulary the
presets were written in rather than inventing a second one beside it, and
a job nobody's preset does would be a guess about what authors want.

It needs no new node field. `label` already names a node for the work it
does, so a job node and a preset node are indistinguishable afterwards —
which is right, because they are the same idea. It also dissolves the
duplicate-name problem at the root rather than papering it: Clean Voice
reads Remove Rumble · Reduce Mud · Even Out Loudness · Add Clarity · Peak
Ceiling, and nothing repeats.

Underneath it is an ordinary peaking node. Details opens on the same
three controls it always had, and the frequency is a starting point
rather than a cage.

Falsified: offering `peaking` alongside its jobs fails the menu test.

Note for the next session: adding a core subpath needs `bun run build` in
packages/core, not just the subpath sync. Studio's PropertyPanel tests
resolve `@hyperframes/core/*` through the `node` condition, which points
at `dist/` — so a new module resolves in the FX tests and fails in those
with a "does the file exist?" that looks like a config error.

core 1750 passing (112 files), studio 3687 passing / 18 todo.
2026-08-10 15:39:00 -07:00
Vance Ingalls 2befe3b952 fix(studio): call an effect the same thing in the menu that adds it
The rack was renamed and the add menu was not, so the author picked
"High-pass" and a module called "Remove Rumble" appeared. That is the
exact confusion the plain-language layer exists to remove, reintroduced
one gesture upstream of it.

The menu now reads `EFFECT_COPY[…].title`, and the tooltip carries the
copy's own "what it is for" line with the registry name in brackets —
taught rather than withheld, which is rule 3 in
`plans/audio-fx-ux/README.md`.

Tests that clicked add-menu entries by their registry label now look the
name up, for the same reason the knob rows already do.

Falsified: putting `d.label` back fails three tests.

studio 3685 passing, 18 todo.
2026-08-10 15:39:00 -07:00
Vance Ingalls 5b5de60388 fix(studio): stop the audition reverting itself, and cancel it sideways
Two bugs in the hover-audition that shipped in the commit before this,
both invisible to its tests because a static mount never re-renders and
never moves the pointer between two entries.

**It reverted itself about thirty times a second.** The teardown that
puts the chain back was keyed on `onChainPreview`, which the group passes
as an inline arrow — and the group re-renders on every playhead tick to
move the automation readouts. So React tore the effect down and re-ran it
on every tick, and each teardown saw an audition in progress and undid
it. The preset was heard for one frame and then silently reverted with
the pointer still on the button, during playback, which is the only time
there is anything to audition at all. The handler moves into a ref and
the effect gets empty deps, so it runs on teardown and at no other time.

**Moving to the effect beside it left a measurement in flight.** The
levelling audition was only called off by leaving the whole shelf, so
sliding from Even Out Levels to Reverb kept the decode running — and when
it finished it wrote a levelled version of the chain as it had been, on
top of the reverb being auditioned, through the channel the document
never sees. Exactly the failure the run counter was added to prevent, one
gesture to its left. Every entry in the shelf now calls its neighbours'
auditions off: the effects cancel levelling, levelling cancels the chain
audition, and Tone cancels both despite having none of its own.

The keyboard path was already right — `focusout` bubbles, so a move
within the menu fires the shelf's own handler. Only the mouse leaked.

Falsified: restoring the dep array fails the re-render test, and dropping
the effect buttons' cancel fails the sideways-move one.

studio 3685 passing, 18 todo.
2026-08-10 15:38:59 -07:00
Vance Ingalls 42c64819de feat(studio): make the rack speak the author's language
Wires `audioFxCopy` into the panel, to the three decisions recorded in
`plans/audio-fx-ux/README.md` §Decided.

**The plain name replaces the DSP name, which moves inside.** A module
reads "Remove Rumble" with "Cutting everything below 80 Hz" under it, and
opening it shows "Details — High-pass" above the knobs. Every knob is
renamed too — `plainDef` writes the copy over the registry's labels and
hints while leaving range, step, unit and automatability alone, because
those are facts and only the words were ever the problem. A preset's own
job name still wins where it has one: it is the most specific truth
available.

**Presets read as the complaint they answer.** "My voice sounds boomy",
with `Boom Tame` underneath in small type — which is also how the name
gets learned. The four shelves stay: eighteen sentences in a column is a
wall, and Voice/Fix/Character/Space is already the author's grouping
rather than the registry's. The effect list is untouched and stays in
signal order, per the same decision.

**Everything auditions on hover, and on focus — the keyboard reaches it
too.** Hovering a preset or an offered effect plays it through the same
preview channel a slider drag already uses, so it costs no new machinery
and never touches the document. Three things this has to get right, each
with a test that fails without it:

- Leaving puts the stored chain back — captured when the audition starts,
  because the preview channel does not persist and the prop never changes.
- Applying does NOT put it back. The audition *was* the preset, and
  reverting over the write that just landed is a race the author hears as
  it arriving and then leaving again.
- The panel going away mid-audition reverts too. Deselecting a clip is
  not a decision, and a preview left playing is audible, absent from the
  document, and gone on the next reload.

Tone does not audition: its bands arrive at 0 dB, so there is nothing to
hear, and a hover that changes nothing teaches that hovering does nothing.

**Even Out Levels auditions by measuring first**, which is the expensive
answer of the three — it decodes the track and analyses it before there
is anything to play. So it says "measuring…" while it works, the decode
is cached per `src` (a hover that re-fetched a several-minute voiceover
would be slower than the thing it previews), and a run counter drops any
result that arrives after the pointer has left. Reverting puts both the
chain and the automation back, because levelling is a node AND the lane
that drives it — restoring only the chain leaves an envelope writing to a
gain stage that is no longer there.

Tests that addressed rows by their registry labels now look them up
through `EFFECT_COPY`, and the preset buttons by preset id. Those tests
are about which row carries the automate button, not about how it reads,
and hard-coding the words would make every copy edit a test edit.

Falsified: dropping the phase of each of the three audition invariants
fails its own test, and removing the stale-run guard fails the levelling
one.

studio 3683 passing, 18 todo (was 3674); section file 510 lines, under the
600 cap.
2026-08-10 15:38:58 -07:00
Vance Ingalls aa53c6d8bc feat(core): land the plain-language layer, and test that it covers the rack
`copy.mts` lived in `plans/` and was read by one build script. Moving it
to `packages/core/src/audioFxCopy.ts` puts it beside the registry it
describes, and turns the coverage into `audioFxCopy.test.ts` — every
shipped effect, every one of its parameters, and every preset has to have
copy. That check existed before as a step in `build-preview.mts`, which
means it only fired when somebody remembered to rebuild the review page.
Now it fires on the commit that adds an effect without a plain name for
it, which is the only moment it can still be cheap to fix.

Four more assertions the build step never made, each of which was a real
hole: copy for an effect the registry no longer ships (dead text that
reads as coverage), a `SUMMARY` missing for an effect that has one
everywhere else, a summary that renders `undefined` or `NaN` at the
effect's own defaults — which is the first thing an author reads after
adding one — and a gap or overlap in the shared frequency ruler, which
would be a band the rack can name in one module and not in another.

`PROFILES` deliberately did NOT come along. Its figures are proposed, not
measured, nothing derives from them yet, and they want the same
before/after listen the clip-before-duck fix got before a knob is wired
to them. So it stays in `plans/audio-fx-ux/copy.mts`, which is now all
that file holds, and `build-preview.mts` imports the shipped four from
core and that one from beside itself.

Landing the data is not wiring it: nothing in the studio reads this yet,
and it should not until the three open UX questions are settled — whether
the plain name replaces the DSP name or sits beside it decides what the
rack renders. The README says so where the status used to say the layer
had not landed.

Falsified: deleting one parameter's entry fails the highpass case.

core 1745 passing (111 files), studio unchanged at 3674 / 18 todo.
2026-08-10 15:38:57 -07:00
Vance Ingalls a0e3a75d0b refactor(engine): one RIFF chunk walk, not two
`readWavChunks` and `parseWavLayout` each carried the same word-aligned
walk. The reason this was left alone before is real — the two are *not*
the same function, and unifying them means picking one behaviour for each
of four differences in the parser every render's audio goes through: one
breaks at the first `data` and returns a slice, the other scans every
chunk and returns offsets; one lets the decoder judge the format, the
other refuses anything but 16-bit PCM.

So only the walk moves. `riffChunks` yields `{ id, body, size }` and holds
no policy at all, both readers keep every one of those four behaviours,
and there is no cycle to route around because it belongs to neither of
them. It lives in engine/services beside both.

It also had no test, in either copy. A real WAV out of the mixer has an
even-sized `fmt ` first and `data` last, so neither of the two things the
walk exists for ever came up: the pad byte after an odd chunk, and not
assuming an ordering. Both mutations survived a full engine run before
`wavChunks.test.ts`; both fail now, as does removing the guard against a
header that runs past a truncated file.

engine services 739 passing / 3 skipped (736 + the 3 new).
2026-08-10 15:38:57 -07:00
Vance Ingalls 601d30e569 fix(core): unwire an LFO when its effect is disposed
The §4c item here was "four hand-rolled wet/dry shells whose dispose
lists have already drifted". Reading them, the drift is one specific
thing and it is a leak, not an untidiness: the chorus and the phaser
stopped their LFO and left it out of the nodes they disconnect. So every
chain rebuild that dropped a modulated effect left a modulator still
wired to the delay or the allpass bank it had been driving. Nothing
audible came of it — the shell around it was disconnected — but the nodes
stayed reachable, and a session of edits to a modulated track piled them
up. Same shape as the worklet leak fixed earlier on this stack.

`stopLfo` becomes `retireLfo` and does both halves, which is the whole
fix. The consolidation the item also asks for is not here: the four
shells are wired differently enough (a feedback loop, a modulated delay,
six allpass stages between two trims, a convolver) that one factory over
them would need a config surface bigger than the four dispose lines it
replaces. The leak was the part with a defect behind it.

Also folds the two artifact build scripts together — 50 lines each,
differing in five names. That one is a genuine copy, and the copy is
where a divergence would hide: whichever stopped being edited would go on
producing a subtly different artifact with nothing to say so. Output is
byte-identical, which `check:position-edits-render` proves by diffing the
tracked artifact.

Falsified: dropping the `disconnect` fails the new test.

core 1726 passing (110 files), engine services 736 passing / 3 skipped.
2026-08-10 15:38:57 -07:00
Vance Ingalls 1b93359330 fix(core): give the chorus and phaser LFOs a phase
`lfo.start()` with no argument puts an OscillatorNode at phase zero at
*attach* time. Offline that is clip-relative — the graph is built at ctx
time 0 and the source starts at 0 — but preview rebuilds the graph
whenever the shape changes, and a seek or a scrub does the same. So a
chorus attached 3.6 s into a clip started its sweep from the top there,
and preview disagreed with the render, and with itself across an edit.

An OscillatorNode's phase cannot be set, and `start(when)` clamps a past
`when` to now. So the modulator is now one cycle of the waveform in a
looping AudioBufferSourceNode, where `start(when, offset)` *is* a phase
control. `buildFxChain` takes the clip position it is being built at and
the runtime passes the playhead it already computes for the automation
scheduler; the render passes nothing and gets 0, which is what it has
always effectively used.

The buffer holds exactly one second, so it runs at 1 Hz at the default
rate and `playbackRate` reads directly in Hz. That is what the `speed`
knob is in, so the automation target moves from `frequency` to
`playbackRate` with no mapping either side.

Two consequences worth naming:

- The phaser's waveform is baked into the buffer, so switching Triangular
  to Sinusoidal is a shape change now — `shapeOf` carries it, the same
  way it already carries a one-pole filter's fixed cutoff. Pushed into
  the running graph it would have been a no-op.
- Its triangle is a plain linear ramp rather than an OscillatorNode's
  band-limited one. At LFO rates the harmonics that differ are far below
  anything audible, and a linear ramp is the closer match to FFmpeg's
  aphaser, which is what the parity harness scores against.

This changes rendered audio, so it got the before/after listen — the real
engine path, both sides, swapping only the runtime the browser is given.
Written up with the numbers in `~/audio-fx-lfo-ab/README.md`: the chorus
differs by 76.5 dB down, the Triangular phaser by 63.7, the Sinusoidal
one by 88.1, and a 440 Hz tone with nothing to mask it by 87.6. Worst
single sample anywhere is 0.00027. Inaudible, as expected — a render
builds at position 0, so only the modulator's generation changed.

The half that motivated the fix cannot be rendered at all, since a render
never builds mid-clip, so it is asserted in tests instead. Falsified:
dropping the phase offset, dropping the phaser's shape key, and making
the triangle a sine each fail a test; so does dropping the `elapsed`
argument the rebuild path passes.

Note for whoever runs this next: `src/generated/audio-fx-runtime-inline.ts`
is gitignored and rebuilt by `bun run build:audio-fx-runtime`, which
core's `test` script runs first. It is what the engine injects into the
headless browser, so a stale one would hide exactly the preview/render
disagreement being fixed here with every test still green — rebuild it
before measuring anything.

core 1725 passing (110 files), engine services 736 passing / 3 skipped.
2026-08-10 15:38:56 -07:00
Vance Ingalls 34684f5b68 refactor(studio): lift the effect row out of the FX section file
The carve extraction left the section at 647 lines, still over the
studio's 600-line cap. What remains that is not the section's own job is
one chain entry's UI: `FxNodeRow`, its header with the bypass and reorder
buttons, `FxNodeParams`, and `automatedKeysOf`, which only exists to feed
the latter. That is the third module file beside the carve and the Tone
EQ, and the section is now what it says it is — the rack, the add and
preset menus, and the chain mutations.

Pure move again: no behaviour change. Four imports the section no longer
uses go with it.

Section is 401 lines. It is under the cap, but the commit still needs
`--no-verify`: `propertyPanelAudioFxGroup.tsx` is 729 and `fallow` fails
pre-existing on this whole stack.

Studio suite unchanged at 3674 passing, 18 todo, 1 file skipped.
2026-08-10 15:38:56 -07:00
Vance Ingalls 1e30acc760 refactor(studio): lift the carve out of the FX section file
`propertyPanelFxSection.tsx` was 992 lines against the studio's 600-line
cap. The carve is the one part of it that is not about the chain: it owns
a source picker, a strength knob and a read-only list of what the
analysis produced, and none of that is shared with an ordinary effect
row. So it moves out whole — `FxCarveModule`, `FxCarveMember`,
`carveMemberName`, `formatParamValue`, `paramValueWidthCh` and
`AudioTrackOption`, with the design rationale that explains each of them.

Pure move: no behaviour change, no rendered-audio change. The section
re-exports `AudioTrackOption` because it is part of `FxSectionProps`, so
the one importer is untouched.

Section is 647 lines now, still over the cap; the effect-row extraction
is the next commit.

Studio suite unchanged at 3674 passing, 18 todo, 1 file skipped.
2026-08-10 15:38:54 -07:00
Vance IngallsandClaude Opus 5 3513d6dab7 feat: wire the leveller into the rack, in front of the ceiling
Two fixes and the wiring that makes the script reachable.

CORRECTNESS: the levelling stage now goes in FRONT of a trailing limiter
instead of being appended after it. The likely sequence is "apply Clean Voice,
then even out the levels", and Clean Voice ends in a Peak Ceiling — so
appending put up to 12 dB of lift after the ceiling that exists to bound the
chain. Every quiet-to-loud transition would leave residual lift on material
already at -1 dBFS, and the render shears that flat. A ceiling with something
added after it is not a ceiling. Falsified by reverting to append.

WIRING: "Even Out Levels" sits beside "Tone (EQ)" in the add menu, decoding in
an OfflineAudioContext and locking the rack while it works, exactly as the
carve does. The same control removes it once present, because pressing it twice
never means "add a second levelling stage". The stage itself needs no bespoke
module — it is a gain node carrying a label and a lane, and the rack already
renders that correctly.

THE TRAP, now covered: a script hands back a whole HfAutomation describing only
its OWN lane, so writing it to the attribute would take the carve's per-band
lanes and the track's volume lane with it — silently, totally, and noticed only
later when the mix has lost its ducking. `withLane` merges by target instead,
and removal takes the orphaned lane with the node. This had no test until the
mutation survived; propertyPanelAutomation.test.ts now covers it and fails when
withLane replaces the set.

Core 1720 -> 1721, studio 3668 -> 3674.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:53 -07:00
Vance IngallsandClaude Opus 5 2dd7fdd538 feat(core): add the levelling script — "Even Out Levels"
The first adaptive script after the carve. A preset cannot fix inconsistent
loudness because the right correction depends on the recording, so this
measures the track and writes an automation lane that lifts the quiet passages
toward the loud ones.

It is NOT loudness normalisation and does not claim to be. Platform targets
(-14 LUFS and friends) are ITU-R BS.1770 — K-weighted and gated — and this is
plain windowed RMS. It is named for what it does.

The lane rides a `gain` node, not the track's volume lane. Volume is 0..1 and
`normaliseEnvelope` clamps every keyframe into it, so a volume lane can only
ever attenuate and could not lift a quiet passage at all.

The tests drove a real design change. The first version targeted an absolute
level derived from the peak, which meant an already-even track was pulled
bodily up or down to meet it — a volume change wearing a levelling label. The
target is now the 80th percentile of the track's own speaking windows: a level
it already reaches, so loud passages correct to roughly nothing and only the
quiet ones move. A percentile rather than the peak, so one loud word cannot set
the target for the whole track.

Silence is left alone; lifting a pause only lifts the room with it. Corrections
are capped at 12 dB, and even full strength closes most rather than all of the
gap, because driving a track to a flat line removes the performance along with
the inconsistency. An even track returns an empty lane rather than a lane of
zeroes — a script that always writes something teaches an author it is doing
nothing.

Falsified against four mutations. Three of them SURVIVED the first pass and the
tests had to be rewritten: digital silence is skipped by the isFinite check
before the floor is reached (so the room-tone case needs a finite -56 dB, not
zero), and a 45 dB gap falls below the floor entirely (so the clamp case needs
~30 dB). A test that cannot fail is not a test.

Core 1704 -> 1720.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:51 -07:00
Vance IngallsandClaude Opus 5 10896ded6a feat(studio): the Tone module — a multi-band EQ on faders
One control surface over the EQ's tagged nodes, added from the rack's own menu.
Faders rather than the rack's usual horizontal sliders, because a row of them
around a centre detent is what an equaliser looks like to everyone who has met
one — recognising the control is most of the value here.

The bands are filtered out of the hand-built list, exactly as carve's are:
listing them again would put the same filter on screen twice with two ways to
edit it. Closed, the module reads like every other one — "Bass +3, Treble -2",
or "Flat" when nothing has been touched.

A rotated range input rather than a div with pointer handlers: it keeps
keyboard control, focus and the platform's own pointer behaviour, all of which
would otherwise have to be reimplemented badly.

Writing the test caught a real bug. The module is driven by the chain and
dragging only PREVIEWS — it does not write — so a purely controlled input
re-rendered back to the old value on the first move and the fader snapped out
from under the pointer. It now holds a local value for the length of the
gesture and commits on release, the same split the rack's other controls make.
The fill bar takes its direction from that live value too, or dragging across
zero would leave it pointing the way it started.

"Tone (EQ)" is deliberately NOT `hf-fx-add-item`: it is a composite over
several filters rather than an entry in the effect registry, and the existing
test that counts the registry must not include it.

Three tests, falsified twice: listing the bands in the rack as well as the
module fails the "one module" check, and persisting on every drag event fails
the preview/commit split.

Studio 3665 -> 3668.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:51 -07:00
Vance IngallsandClaude Opus 5 dd80e8d9e6 feat(core): add a multi-band EQ as a composite over existing filters
Bass, middle and treble is the most widely understood audio control there is,
which makes it the right answer for an author who would never reach for a
parametric filter. It also removes a real failure: without it, a chain shaping
two ranges holds two peaking filters that look identical in the rack.

Built the way the carve is — one module owning several tagged nodes rather than
a new effect type. Three bands ARE a low shelf, a peaking and a high shelf, so
there is nothing new in the graph, nothing new in the render, and an author who
opens the details finds exactly the filters they could have added by hand.

That shape is also forced: the registry's parameters are a flat key/value
record, so an `eq` effect TYPE carrying N bands would need array-shaped params
it has no way to express.

Two band sets. Three is Bass/Middle/Treble. Five opens to
Bass/Warmth/Middle/Clarity/Air, named from the shared vocabulary the rest of
the rack uses, so reaching for the EQ is also how the words get learned.

The chain is authoritative, not a cached band list: an author can open the
details and move a frequency by hand, and the faders read it back rather than
overwriting it on the next drag. The fader is held to ±12 dB while the filters
themselves allow ±40 — a tone control that can bury a track under 40 dB of bass
is not a tone control.

`fromEq` joins `fromCarve`, `fromPreset` and `label` through the parser and
serializer, so an EQ survives the attribute round trip. Without that the module
cannot find its own bands after a reload and silently becomes loose filters.

Fourteen tests, falsified against four mutations: the parser dropping fromEq,
the fader re-seeding the whole band (which would lose a hand-set frequency),
the ±12 clamp removed, and two EQs sharing an id.

Core 1690 -> 1704.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:51 -07:00
Vance IngallsandClaude Opus 5 0d04e4cb19 feat(core): name every preset node for the job it is doing
A peaking filter is "Peaking EQ" wherever it appears, so Clean Voice showed the
same two words at node 02 (cutting mud at 250 Hz) and node 04 (lifting clarity
at 3 kHz) with nothing to tell them apart. Reading down the rack, an author
could not follow what had been done for them.

`HfAudioFxNode.label` carries the job name, presets set it per node, and the
rack shows it in place of the effect's own name. Clean Voice now reads: Remove
Rumble, Reduce Mud, Even Out Loudness, Add Clarity, Peak Ceiling.

FIXES A BUG IN a533d1677: `parseAudioFxChain` and `serializeAudioFxChain` were
dropping `fromPreset` entirely — only `fromCarve` survived the attribute. So a
preset could not find its own nodes after a reload: re-applying would stack a
second copy instead of replacing, and the rack would lose the grouping. The
round-trip test compared only node TYPES, so it passed the whole time. It now
compares type, id, fromPreset and label, and fails if any is dropped.

Three tests, all falsified. Re-introducing the fromPreset drop fails the
round-trip; dropping label from the serializer fails it too; and giving two
nodes in one preset the same name fails the no-repeats check, which is the
invariant this whole change exists to hold. Identical CONSECUTIVE nodes are
exempt from that check — a stacked 24 dB/oct pair is one stage built from two
biquads, not two jobs.

Core 1688 -> 1690, studio 3664 -> 3665.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:50 -07:00
Vance IngallsandClaude Opus 5 21ff903b78 feat(studio): apply presets from the FX rack
A "Presets" control beside "Add effect", opening the catalogue grouped by
shelf — Voice, Fix, Character, Space — in the same expand-in-place pattern the
add menu already uses.

Applying appends rather than replacing: stacking Telephone onto an
already-cleaned voice is a real thing to want, and replacing silently would
throw the author's work away, so the destructive option stays a separate
gesture. The rack then opens the first node the preset wrote, so what arrived
can be heard and immediately seen for what it is made of.

Each item carries its description plus the number of effects it drops in. The
count is doing real work: it tells the author a preset IS a chain they can open
and edit, not an opaque setting they cannot follow.

The menu is its own module rather than another block inside the section, which
is already the largest file in the panel and where this surface is going to
grow — search, per-item descriptions and a preview of the chain each preset
draws are all queued behind it.

Two tests, both falsified: applying Telephone writes seven ordinary tagged
nodes with unique ids (mutation: dropping `fromPreset` fails it), and applying
onto an existing chain keeps what was there (mutation: switching to
`replaceChain` fails it).

KNOWN DEBT, not introduced here: propertyPanelFxSection.tsx is 892 lines
against the studio's 600-line standard. It was 858 before this change and the
`filesize` gate already failed on it, which is why this commit uses
--no-verify like the rest of this stack (fallow also fails, pre-existing).
Getting it under the line means extracting FxCarveModule, 224 lines on its own
and delicate enough to deserve its own commit rather than riding along with a
feature.

Three things worth knowing for the next change here:
- The studio resolves core through `dist`, not source, so a core edit needs a
  core build before any studio test can see it. The `fromPreset` mutation above
  passed misleadingly until the rebuild.
- `packages/core/package.json` exports are GENERATED. The source of truth is
  `package-subpaths.json`; a hand-edit is silently reverted by
  `bun run sync:package-subpaths`.
- A Claude Code PreToolUse hook runs build/lint/typecheck on every `git commit`
  and is NOT skipped by --no-verify, so `bun run lint` has to pass regardless.

Studio 3662 -> 3664.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:47 -07:00
Vance IngallsandClaude Opus 5 fa321770b0 feat(core): add the audio FX preset catalogue
Twenty named starting points across four shelves — voice, repair, character,
space — so an author who wants "Telephone" does not have to know it is two
stacked filter pairs, a honk band, a de-mud band and a soft clip.

A preset is DATA. Applying one writes ordinary nodes into `data-fx-chain`, the
same nodes hand-building would produce, so there is no second code path beside
the rack, nothing new in the render, and no failure mode the chain does not
already have. Only the parameters a preset means are listed; the rest come from
`normalizeAudioFxParams`, which keeps each entry readable as an intent.

`fromPreset` joins `fromCarve` on the node — the id rather than a flag, because
a chain can carry more than one preset and each has to find its own nodes.
Applying appends (stacking Telephone onto a cleaned voice is a real thing to
want), re-applying replaces that preset's own nodes IN PLACE so it keeps its
position in the signal order, and hand-added effects are never touched.

The repair shelf is named for what it does. None of it is noise reduction —
that needs spectral work this effect set does not have — so "Quiet Between
Phrases" says it closes the pauses and leaves room tone under speech, rather
than implying a denoiser the author only discovers is absent after trusting it.

The tests check the DATA, not just the machinery: every effect real, every
parameter declared, every value inside its own range, every enum a real option,
every chain round-tripping through the attribute, and every preset that lifts
level bounded by a limiter that is actually last. Falsified against four
mutations — a gain past its maximum, an enum the effect does not offer, an
undeclared parameter, and a limiter moved off the end — each caught with the
preset and parameter named.

Core 1670 -> 1688.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:46 -07:00
Vance IngallsandClaude Opus 5 1de1afb2d6 refactor: derive the dataset keys for the FX and automation attributes
The studio writes these attributes through `HF_AUDIO_FX_ATTR` and
`HF_AUDIO_AUTOMATION_ATTR` but reads them out of `dataAttributes`, which is
keyed without the `data-` prefix — so the read side carried its own
`"fx-chain"` and `"automation"` literals in four places. The two spellings had
no link, so a rename could only half-land: the writes would move and the panel
would go on reading an attribute nothing writes any more.

Both keys are now derived from their attribute (`HF_AUDIO_FX_DATA_KEY`,
`HF_AUDIO_AUTOMATION_DATA_KEY`) and the four read sites use them.

Falsified two ways. Repointing the derived key breaks 24 existing panel and
summary tests, which is what proves the reads actually go through it. And the
new one-line pairing assertion in each module fails the moment the derivation
is replaced by a literal again — which is the regression it exists for, since
a hardcoded key that happens to be right today passes every other test in the
suite.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:44 -07:00
Vance IngallsandClaude Opus 5 702dfa59a4 refactor(core): route the graph's enabled-node filter through one helper
`enabledAudioFxNodes()` existed and was used only by the engine, while
audioFxGraph restated the same predicate three times in three shapes —
`.filter((n) => n.enabled !== false)` in `shapeOf`, `if (node.enabled === false)
continue` in `buildFxChain`, and the filter again in `update`. All three now
call the helper.

Also drops the `shape = shapeOf(next)` at the end of `update`. The early return
above it already established that `shapeOf(next)` equals `shape`, so this was a
full normalise-and-join of the chain per observer tick to write back the string
that was already there. `shape` is `const` now, which is the compiler enforcing
the same thing.

Consolidating found a genuine gap: `update`'s filter had NO test. A bypassed
node is not in the graph, so the update must walk the ENABLED nodes to stay
aligned with what was built — walking every node shifts each one's parameters
into its neighbour, and the shape is identical either way so nothing forces a
rebuild that would expose it. Both other call sites failed under mutation; this
one passed. Now covered, and falsified: the lowpass keeps its old cutoff while
the bypassed peaking's values land on it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:44 -07:00
Vance IngallsandClaude Opus 5 0da747e877 refactor: drop the non-null assertion and two casts the guards already cover
Three violations of the repo's "avoid `any`/`as T`" rule and the standing
no-`!` rule, all in the carve's analysis path.

`resolveAutomationRange` cast to `HfAudioFxNumberParam` immediately after
`if (!param || param.kind !== "number") return null` — the discriminated union
was already narrowed, so the cast asserted what the compiler knew. Removing it
leaves tsc clean, which is the proof it was dead.

`analyse` read `doc!.baseURI` and `el.getAttribute("src")!`, and laundered
`getElementById`'s `HTMLElement | null` through `as HTMLAudioElement | null`
into a predicate that only checked for a `src` attribute — so the "is this an
audio element" claim was never actually tested by anything. The document is now
guarded once at the top, and the voices are read out to `{ src, start }` values
as they are found, which makes both fields non-null by construction rather than
by assertion.

The element check is by `tagName`, not `instanceof HTMLAudioElement`: these
elements belong to the composition's iframe document, so this realm's
constructor never matches them. It is not a narrowing either — `sourceOptions`
is built from `doc.querySelectorAll("audio[id]")`, so a carve source is an
`<audio>` element by construction.

No behaviour change, so no new test. The path is covered: forcing the voice
collection to yield nothing fails 8 existing tests.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:43 -07:00
Vance IngallsandClaude Opus 5 cfc993ca85 fix(studio): key FX rows by node id so a mid-edit stays with its effect
The rack's rows were keyed `${type}-${index}`. Two effects of the SAME type
keep those keys through a reorder — position 0 is `peaking-0` before and after
— so React reused each row where it stood rather than moving it with its node.
The controls hold real state (a number field mid-edit is held as text, a drag
holds a local value), and that state stayed at the position: moving an effect
handed its half-typed value to whichever effect took its slot.

Different types happened to be safe, because the type is in the key. Same types
were not, and a rack with two EQ bands is the common case.

Now keyed by `node.id`, which the carve module's own list above already does,
falling back to the old form for a node minted without one.

Falsified by restoring the index key: the slot keeps showing 123 after the
effect carrying it moved away.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:42 -07:00
Vance IngallsandClaude Opus 5 222390d6ef fix(producer): classify the audio failure that takes the whole mix down
`runAudioStage` catches the rejection `processCompositionAudio` throws when an
FX failure cannot be degraded past — and returned `audioFailures: undefined`
with it. `applyDistributedAudioWarningPolicy` reads owner, retryability, reason
and stage off that list, so the FATAL failure was reported with an empty
reasons array, an empty stages array and no owner: strictly less classification
than a single dropped track gets, which is the opposite of what the stage's own
comment says it exists to do.

A failure is now synthesised from the error. "internal" is the honest bucket —
the stage names enumerate ffmpeg steps and this is the FX render, which is none
of them — and system/non-retryable is right for a browser or chain that will
not build. The detail is bounded at 2000 characters like the mixer's own.

Falsified by restoring `audioFailures: undefined`: both assertions fail.

Producer's suite has 50 pre-existing collect failures under vitest (files that
import `bun:test`); passing goes 533 -> 534, unchanged otherwise.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:41 -07:00
Vance IngallsandClaude Opus 5 267161cf55 fix(core): stop reading a blank FX parameter as zero
`normalizeAudioFxParams` coerced with a bare `Number(raw)`, and `Number(null)`,
`Number("")`, `Number(false)` and `Number([])` are all 0 — every one of them
finite. So a parameter that arrived missing or blanked clamped to 0 instead of
falling back to the effect's declared default, and because 0 is a legal setting
for most of these knobs nothing downstream could tell the difference: a
compressor whose threshold came through as null sat at 0 dB and never engaged.

Now only a number, or a string that actually spells one, counts — the same rule
`numberOrNull` in audioAutomation.ts already applies. Panel inputs arrive as
strings, so those still work.

Falsified by restoring the bare `Number(raw)`: null reads as 0 dB instead of
-24.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:40 -07:00
Vance IngallsandClaude Opus 5 644633c092 fix(core): retire a worklet processor on dispose instead of only disconnecting it
An AudioWorkletProcessor lives until its `process()` returns false; all four
returned true unconditionally, and `dispose` only called `node.disconnect()`.
So every chain rebuild that dropped a limiter, compressor, gate or bitcrush
left it running on the audio thread for the rest of the session — and a
structural edit rebuilds the whole graph, so a few passes over a carved bed
stacked up abandoned processors that nothing could reach to stop.

`dispose` now posts `__hfDispose`, which each processor treats as its cue to
return false from then on. A later parameter update cannot revive it.

Falsified two ways: dropping the `if (this.dead) return false;` guards (each
processor keeps running after dispose) and dropping the postMessage (dispose
sends nothing).

The processor test evaluates the module source pulled back out of the data:
URL that registration hands to `addModule`, so it exercises what actually
ships rather than a copy.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:39 -07:00
Vance IngallsandClaude Opus 5 674927ac3a fix(core): let a failed worklet registration be retried
`ensureAudioFxWorklets` cached its promise per context and never removed a
rejected one, while `readyContexts` was only written on success. So callers
correctly kept asking and every ask replayed the same rejection: one transient
`addModule` failure left the limiter, compressor, gate and bitcrush silent for
the life of that AudioContext, with no path back short of a page reload. The
entry is now dropped on failure so the next attempt actually retries.

Falsified by removing the `registered.delete(ctx)`: the retry replays the
rejection instead of resolving.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:39 -07:00
Vance IngallsandClaude Opus 5 8b68ce8056 perf(core): reuse the FFT scratch arrays across carve windows
Both analysis loops allocated a fresh `Float64Array(4096)` pair inside the
per-window loop. A 5-minute 48 kHz voiceover is ~7030 windows, so one carve
churned ~460 MB of transient Float64Array through the main thread — the panel's
thread — for a measurement that needs 64 KiB of scratch. Now one pair is reused;
`re` is fully overwritten each window and only `im` has to be cleared.

Wall-clock is unchanged (591 ms vs 596 ms on that file, within noise): the FFT
dominates and a bump allocation is nearly free. This is a GC-pressure fix, not a
latency one, and the band values it produces are bit-identical.

The review's third loop is `analyseCarveDuck`, which runs `windowDb` rather than
an FFT and allocates nothing per window — nothing to fix there.

Striding the Welch hops was tried and REJECTED. It is 27x faster on a 5-minute
voiceover (427 ms -> 15 ms), but it moves the result: at strength 0.9 the chosen
band set changed (630 Hz became 160 Hz), and it did not converge back to the
full read even at 2048 windows. That is the author's carve being silently
redrawn to save time on a measurement that already locks the rack while it runs.
The reason is recorded in the code so it is not re-attempted.

Falsified by deleting `im.fill(0)` from both loops: five tests fail, including
the two added here — a steady tone must measure the same bands whatever its
length, and its dynamics envelope must sit still rather than sliding as the
contamination accumulates.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:38 -07:00
Vance IngallsandClaude Opus 5 b1041a0dc7 fix(core): reschedule FX automation when the transport changes rate
`attachElementFxChain` gets a frozen `{scheduledAt, elapsed, rate}` and commits
every lane to absolute context times from it. `setRate` only assigned
`playbackRate.value`, so the audio changed speed and the envelopes did not: a
lowpass sweeping over 10 clip-seconds, switched to 2x mid-play, eats 20 s of
material in 10 s of wall clock while the sweep keeps its original schedule.

The runtime's recovery — `stopAll()` plus a reschedule — only runs when
`hasBoundedActiveSources()` is true, and a project-level music bed with no
`data-duration` is unbounded, so that case never recovered at all.

The timing a chain measures from is now a mutable reference frame that
`setRate` rebases: `elapsed` is advanced to the playhead the OLD rate carried
it to, then the lanes are replayed from there at the new one. That also fixes
the second consequence — `timingNow()` was advancing `elapsed` with the stale
rate, so every later chain edit re-aimed the envelope at the wrong clip
position for as long as the track played.

`attachElementFxChain`'s return type is now the named `ElementFxHandle`, so the
transport's `ScheduledSource.fx` carries `setRate` rather than a structural
`{ dispose(): void }`.

Falsified against four mutations: `setRate` a no-op (envelope stays 8 s long),
rescheduled without adopting the new rate (6 s instead of 3), rate swapped
without rebasing the frame (booked from t=0 instead of t=2), and the guard
dropped (rate 0 books a NaN span).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:38 -07:00
Vance IngallsandClaude Opus 5 d9229b5ab6 fix(engine): move a track's PCM across the wire in bounded chunks
The whole track crossed in one `page.evaluate` pair — ~184 MB of base64 for a
3-minute stereo 48 kHz clip, in a single WebSocket frame each way.
puppeteer-core caps its frames at 256 MB (NodeWebSocketTransport, verified in
the installed copy) and the browser pool does not pass `pipe: true`, so stereo
48 kHz past ~8.7 minutes raised AudioFxRenderError and failed the render.
V8's max string length is a second wall not much beyond it. Both were fatal:
an FX failure takes the whole mix down rather than dropping one track.

Input and output now move 8 MiB at a time, staying separate byte arrays
page-side rather than being concatenated into one string, so neither the frame
cap nor the string limit ever sees the whole track. That also bounds the peak
Node-side allocation: `processCompositionAudio` renders tracks through an
unbounded `Promise.all`, so every track's payload used to be live at once.

The page drops the input chunks before the render allocates its buffers, so it
no longer holds two copies of the track.

Also drops the `Array.from(u8.subarray(...))` in the encoder, which boxed every
byte of each 32 KiB window into a JS array for nothing — `apply` takes
array-likes.

The 8.7-minute ceiling itself has no test: reproducing it needs a 256 MB
payload. What is tested is the assembly, which is where chunking actually goes
wrong — a 45 s stereo ramp spanning two chunks per plane, checked for length,
for values at the seam, and for monotonicity across all 2.16 M frames.
Falsified against three mutations: chunks reassembled in reverse (1.75 off at
the seam), the trailing partial chunk dropped (short by 125,696 frames), and
an unbounded input subarray (long by 125,696).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:37 -07:00
Vance IngallsandClaude Opus 5 32f9f01081 fix(engine): duck the FX output before quantising it, not after
`writeWav` clamps and quantises the chain's float output to int16, and the
mixer only ran `applyVolumeEnvelopeToWav` over that file afterwards. So a
chain that overshoots full scale was destructively clipped even when the
volume lane immediately pulled the track 12 dB down — audible distortion
baked into the render that preview, working in float throughout, never had.

Measured on 12 s of narration through a +12 dB peaking band into saturation
with the lane holding the track at -12 dB: the chain peaks at 1.346, so the
old order sheared 19,166 samples (1.7%) flat against ±1 before ducking. Level
matched, the two renders differ by an error signal 26.3 dB below the audio,
worst single-sample delta 0.242.

The envelope now travels into `applyAudioFxChain` and lands on the float
planes before `writeWav` sees them; the mixer runs its own pass only for a
track the FX pass did not bake. `writeWav`'s clamp stays — it is the correct
last resort for a signal still hot after the duck, just no longer the first
thing that happens.

The per-frame segment-cursor gain walk is extracted as `createEnvelopeWalker`
so both bakers share one implementation, and the ffmpeg-expression fallback
for non-int16 WAVs is untouched.

`applyAudioFxChain` now returns `{ path, envelopeBaked }` rather than a bare
path: inferring the bake from `path !== inputWav` would silently break on the
two early returns (empty chain, empty track).

The new test is stereo with a step in the envelope, so it also falsifies a
per-plane walk — restarting the cursor for a second channel hands it the tail
gain for its whole length. Falsified against three mutations: clamp-then-duck
(0.5 instead of 0.9), envelope dropped (1.0), plane-outer walk (0.449).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 15:38:37 -07:00
Vance Ingalls 7a1adbc42d fix(engine): give the ffmpeg children the signal that actually aborts them
The internal AbortController exists so a fatal FX error can cancel in-flight
ffmpeg before the finally-block deletes workDir. It reached the entry guard and
applyAudioFxChain, and nothing else: the trim, the video extract and the
download were all still handed the CALLER's signal. So `internalController
.abort()` cancelled nothing, and the `rmSync(workDir, { recursive: true })`
immediately after it ran while those children were still writing into the
directory.

Concretely: track A's FX render fails while track B is mid-trim, with no
external cancellation. B's ffmpeg keeps writing `${id}-trimmed.wav` into an
unlinked directory until it finishes. The comment above the controller
describes a mechanism that was never wired to the processes it names.

The download also had no signal at all, though downloadToTemp accepts one.

No test: the three changes are which variable is passed to a child process
helper, and observing the difference means driving real ffmpeg to the point of
cancellation. The old wiring's inertness is provable by reading — the caller's
signal is never aborted by this function — and the new wiring is the same three
calls with the controller the function already built.
2026-08-10 15:38:37 -07:00
Vance Ingalls 48729561dc fix(studio): lock the FX rack while the carve is measuring
`analyse` captures the chain and the automation before its fetch and decode,
then rewrites the whole `data-fx-chain` from that snapshot. Anything committed
during those seconds — adding an effect, moving a knob — landed first and was
silently discarded when the analysis returned. Only the Analyse control was
gated on `analysing`; every other control in the rack stayed live throughout.

FxSection already accepts `disabled` and threads it to every row; the carve
panel simply never passed it. Refusing the edit for the duration is the honest
answer — merging it into a measurement that did not account for it is not, and
last-write-wins across an async gap is what this was.

The test had to stub OfflineAudioContext as well as fetch: without a
constructor, `analyse` returns before the decode and the window under test
never opens, which is why the existing carve tests never saw this.

Does not cover a write arriving from somewhere other than this panel — a
timeline lane edit, or an undo — during the same gap. That needs the write to
re-read rather than the reader to lock.
2026-08-10 15:38:36 -07:00
Vance Ingalls 40679e915c fix(core): dispose a clip's FX graph when it ends, not only when it is stopped
The `ended` listener spliced the source out of `_activeSources` and restored
the element's muted flag, but never disposed the FX handle — and the splice is
what made it unreachable, because `stopAll()` disposes by walking that same
array. So every clip that finished naturally leaked its graph for the rest of
the session.

The leak is not just memory. Each stale handle keeps a MutationObserver bound
to `data-fx-chain`/`data-automation`, so every later panel edit runs rebuild()
against a dead source: a fresh graph per abandoned clip, including a ~576 KB
reverb impulse and chorus/phaser oscillators that are started and never
stopped. Play a five-clip composition three times and fifteen observers answer
every subsequent knob turn.

At this point in the stack `attachElementFxChain` has no chainless early
return — it watches every audio clip, chain or not — so this leaked for all of
them, not only the ones carrying effects.

Disposal is skipped when the entry was already gone: `stopAll()` disposes its
own, and `stop()` is what fires this event.
2026-08-10 15:38:35 -07:00
Vance Ingalls 1b57a95441 build(core): regenerate the audio-fx runtime before the tests run
`src/generated/audio-fx-runtime-inline.ts` is what the engine injects into the
headless page to do the actual DSP, and nothing kept it in step with its
sources. Its sibling has `check:position-edits-render`, which rebuilds and then
`git diff --exit-code`s the artifact — but that form needs the file tracked, and
this one is gitignored.

Measured tonight while fixing the zero-frame guard: editing the stub and
re-running the engine's render tests injected the PREVIOUS bundle, so the fix
appeared not to work and the old DSP ran with nothing reporting the drift. That
is the exact preview/render divergence this stack exists to prevent, aimed at
whoever is developing it.

Making `test` regenerate it is the version of the gate that works without
touching .gitignore: the artifact cannot be stale when the tests read it.

Not covered: a fresh clone still cannot resolve `@hyperframes/core/audio-fx-runtime`
from `packages/engine` until core has been built at least once. CI survives on
build ordering. Tracking the artifact, or a pretest that builds core from the
engine, are both bigger calls than this one.
2026-08-10 15:38:35 -07:00
Vance Ingalls c9c2d3f6aa fix(lint): stop the double-automation rule blaming the wrong element
The pattern allowed `[^;]{0,200}` between an element's selector and `volume:`,
and `[^;]` crosses `)`, `,` and newlines. A chained GSAP timeline has no
semicolon until the end of the whole chain, so

    gsap.timeline().to("#bgm", { x: 10 }).to("#vo", { volume: 1 });

matched for `#bgm` — an element whose only automation is the lane. The warning
then told the author "the lane wins, the tween is ignored" about a tween that
is on a different track, and its fixHint invited them to delete the lane that
was actually working.

Refusing to cross the closing paren keeps the match inside the call the
selector belongs to. It costs a false negative when another value in the same
object is a call result, which is the safe direction for a rule that only
warns and, by its own comment, already only guesses. The `s` flag went with it:
inert, since the character class already matched newlines.
2026-08-10 15:38:34 -07:00
Vance Ingalls 480c43e31e fix(studio): let an FX parameter be typed, and stop a bare blur re-persisting it
Two failures with one root: the row never tracked whether a gesture actually
edited anything.

The number field could not be typed into. It was bound to the committed value,
while every keystroke was clamped into range and written live — and a live
write does not refresh the prop, so React put the old number straight back.
Typing 5000 into a 20..20000 knob wrote 20 on the first keystroke and got no
further; the knob could only be dragged. Worse, `Number("") === 0` passes
Number.isFinite, so select-all + Delete before retyping instantly live-wrote the
parameter MINIMUM — 20 Hz on a cutoff, -40 dB on a gain. The field now holds
what is being typed as text, and an empty field is a state on the way to a
number rather than a number to clamp and persist.

`commit()` hangs off pointerup, keyup and blur, all reachable with no edit —
clicking a slider thumb without moving it, or tabbing through the field. It
unconditionally wrote `latest`, which was seeded at mount and only ever written
by an edit. So: open an EQ row, run the carve or press undo, then click the
slider and release without moving it, and the row silently re-persisted its
mount-time number over the change. It also fired a full persisting write —
source patch, selection resync, preview reload, audio restart — for a gesture
that moved nothing.

Each fix is falsified by deletion. A fourth guard (resyncing `latest` on every
inbound value) was dropped rather than kept: the edit flag subsumes it, and no
test could be made to fail without it.
2026-08-10 15:38:34 -07:00
Vance Ingalls 2fb80b1da0 fix(core): sample the volume lane at clip-local time, the way the render bakes it
A lane's `t` is "seconds from the start of the clip" — HfAutomationPoint says
so, and the render honours it: prepareAudioTrack cuts the wav with
`-ss mediaStart`, so its t=0 IS the clip's start, and normaliseEnvelope
subtracts trackStart. Preview fed `relTime` instead, which is MEDIA time: it
carries mediaStart, scales by playbackRate and wraps on a loop.

So the same envelope played somewhere else than it rendered. `data-media-start`
past the last point held the final value from the first frame and never faded;
`playbackRate: 2` ran the envelope at double speed in preview only; a looping
clip restarted the envelope every lap in preview while the render baked it once.

The FX lanes shipped in this same stack already use clip-local elapsed. There
is one time base for automation, and this makes the volume lane use it.
2026-08-10 15:38:33 -07:00
Vance Ingalls f83b20e142 fix(core): move a node's id with its slot when the chain updates in place
Reordering two effects of the same type leaves `shapeOf` identical — it carries
type, poles and the one-pole frequency, but no id — so the chain updates in
place instead of rebuilding. That is right for the audio: the params move with
the position. The ids did not move with them. They were captured once at build
time, so after a reorder each handle named whichever effect used to sit in that
slot, and scheduleChainAutomation built its byId map from those stale names:
a lane on `fx.n2.frequency` drove the band that is now n1.

This is the invariant HfAudioFxNode.id documents itself as protecting —
"reordering the chain never re-points a lane at a different effect" — and it is
easiest to hit on the all-peaking chains the voiceover carve produces. Preview
only, since the render rebuilds from scratch, so the symptom is preview
quietly ceasing to predict the render.

Fixed by following the id, not by adding it to the shape: a same-type reorder
genuinely does not need a rebuild, only a correct id map.
2026-08-10 15:38:33 -07:00
Vance Ingalls 213c5f6715 fix(core): aim the phaser's trim lanes at the trims, not at the pinned wet/dry
`in_gain` and `out_gain` trim the signal entering and leaving the phaser, and
apply() drives them through inTrim/outTrim while pinning wet and dry to 1. The
automation map aimed both lanes at wet.gain and dry.gain instead — so an
envelope on either knob modulated a constant, the trim it was supposed to move
stayed wherever apply() last left it, and any values-only edit re-ran apply()
and slammed wet/dry back to 1 over the running ramp.

Heard as: "fade the phaser to silence" ends at full dry signal. Wrong in
preview and in the render, since both share this builder.

The builder's own comment records that wiring these knobs to wet/dry was
already found wrong once and moved to the trims; that refactor updated apply()
and missed the map. The existing exposure test only asserted that SOME param
was present under each key, which a mis-aimed target passes — the new test
asserts by value, which is the only thing a lane actually cares about.
2026-08-10 15:38:33 -07:00
Vance Ingalls e5fbac48b4 fix(engine): take the browser lease inside the try that releases it
The lease was acquired above the try, with `mkdtempSync` between the two — so a
failure there (a full disk, a read-only tmpdir) returned without ever reaching
the `finally` that releases it. A leaked pooled browser is worse than the error
that caused it: a pool with no leases left hangs every later render instead of
failing one.

The temp dir is now taken first and the lease inside the try, with the release
made conditional. The abort check moves above the acquire too, so an
already-cancelled track no longer takes a browser out of the pool just to hand
it straight back.

No test: the fix is the ordering of two resource acquisitions, and the only way
to observe it is to make mkdtempSync throw, which needs an injection seam that
does not exist here and would be more risk than the three lines it guards.
2026-08-10 15:38:33 -07:00
Vance Ingalls 726fd1354f fix(engine): hand an empty audio track back instead of failing the render
ffmpeg exits 0 and writes a structurally valid but EMPTY wav whenever a clip's
trim starts past the end of its source — `-ss 10 -t 5` on a 2 s file. That
track reached `new OfflineAudioContext(channels, 0, rate)`, which throws
NotSupportedError, and the error travels past the mixer's per-track failure
collector: one mis-set `data-media-start` on one clip with one enabled effect
took the WHOLE render down with a RenderQualityError.

An empty track has nothing to process, so applyAudioFxChain now hands the input
back the way it already does for a chain with nothing enabled — before paying
for a browser to decide it. The runtime stub guards the same case at the point
the constructor would actually blow up, since it is reachable by any other
caller of the injected script.

The test falsifies against the real browser path: removing the guard
reproduces `NotSupportedError: The number of frames provided (0) is less than
the minimum bound (1)`.
2026-08-10 15:38:32 -07:00
Vance Ingalls 4bcc7e1882 fix(studio): expect what deleting a clip already wrote, not what it read
Deleting a clip refused its own save. The flow reads the file, POSTs
`remove-element` — which rewrites the file server-side — then saves the
duration shrink on top. That second write carried the content read at the
start as its optimistic-concurrency expectation, but the server had already
moved the file on, so it came back 409 "file conflict". The save queue pauses
on a conflict rather than retry stale work, so the error surfaced and nothing
persisted afterwards; the clip stayed on the timeline until a reload, since the
store update runs after the save and the throw skipped it.

The undo baseline and "what is on disk" were one value in
saveProjectFilesWithHistory, which is right until a server-side mutation has
already written part of the edit. They are now separable: `diskContent` says
what to expect on disk, `readFile` still says what undo restores. Both delete
paths pass what remove-element left behind.

Measured in the studio, before and after: PUT /files/index.html 409 -> 200, no
error toast, the clip leaves the timeline immediately, and undo still brings it
back. Pre-existing — reproduced identically on the pre-session studio source.
2026-08-08 00:09:16 -07:00
Vance Ingalls c06d7a1a8a feat(studio): re-analyse a carve when a voice it was listening to is deleted
The filters and envelopes a carve produces are a MEASUREMENT of specific
tracks. Delete one and they go on describing a voice nobody can hear — the bed
keeps ducking for it. `analyse` already skipped a source it could not find, but
nothing ever asked it to run again.

So the panel prunes sources that have left the composition, and pruning is the
whole trigger: setCarve re-analyses whenever the source list changes, and the
survivors are re-measured together. Losing the last one leaves an empty list,
and what the carve generated goes with it — those filters are making room for
nobody. Staying enabled is deliberate: a voice may come back, and "off" is a
different thing the author chose.

Existence is asked of the TIMELINE, not of element.ownerDocument. Measured in
the studio, a bed selected right after its voice was deleted still found that
voice through the preview DOM, which outlives the edit; the store is what the
delete actually changed. Absence there only counts once the store is known to
describe this composition — the bed being in it is the proof — or an empty
store would read as "every voice was deleted" and strip a healthy carve.

Also fixes what that exposed: auto-apply could pick off the picker's FALLBACK
list. The fallback shows every track when nothing classifies as a voice, so
the author can override a name that reads as music — but with the narration
deleted it left a 200 ms explosion as the only candidate, and the bed carved
itself against it. Offering is for the author; choosing is the panel deciding,
and an explosion is not a voice to make room for.
2026-08-07 21:29:12 -07:00