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>

Author: vanceingalls

packages/core/src/audioLeveller.test.ts

@@ -6,6 +6,7 @@ import {
   type HfAudioFxChain,
 } from "./audioFx.js";
 import { sampleAutomationLane } from "./audioAutomation.js";
+import { applyAudioFxPreset, getAudioFxPreset } from "./audioFxPresets.js";
 import {
   analyseLevelling,
   levellerProfile,
@@ -182,6 +183,28 @@ describe("what it writes", () => {
     expect(twice.chain.nodes[0]!.id).toBe(once.chain.nodes[0]!.id);
   });
 
+  it("goes in FRONT of a trailing limiter, never after it", () => {
+    // The likely sequence: apply Clean Voice, then even out the levels. Clean
+    // Voice ends in a Peak Ceiling, and up to 12 dB of lift landing after that
+    // ceiling means loud material at -1 dBFS goes over full scale and the
+    // render shears it flat. A ceiling with something after it is not a ceiling.
+    const voiced = applyAudioFxPreset(empty(), getAudioFxPreset("voice-clean")!);
+    expect(voiced.nodes[voiced.nodes.length - 1]!.type).toBe("limiter");
+
+    const result = levellingResult(
+      voiced,
+      uneven([
+        { seconds: 3, amp: 0.5 },
+        { seconds: 3, amp: 0.06 },
+      ]),
+      SR,
+    )!;
+    const types = result.chain.nodes.map((n) => n.type);
+    expect(types[types.length - 1]).toBe("limiter");
+    expect(types[types.length - 2]).toBe("gain");
+    expect(result.chain.nodes.find((n) => n.fromLeveller)).toBeTruthy();
+  });
+
   it("leaves hand-added effects alone", () => {
     const chain: HfAudioFxChain = {
       version: HF_AUDIO_FX_CHAIN_VERSION,

packages/core/src/audioLeveller.ts

@@ -193,12 +193,27 @@ export function levellingResult(
     params: normalizeAudioFxParams("gain", { gain: 0 }),
   };
 
+  /**
+   * In FRONT of a trailing limiter, not after it.
+   *
+   * The likely sequence is "apply Clean Voice, then even out the levels", and
+   * Clean Voice ends in a Peak Ceiling. Appending would put up to 12 dB of lift
+   * AFTER the ceiling that exists to bound the chain — so every quiet-to-loud
+   * transition leaves residual lift on loud material sitting at -1 dBFS, and
+   * the render shears it flat. A ceiling that something is added after is not
+   * a ceiling.
+   */
+  const insertAt =
+    !existing && chain.nodes[chain.nodes.length - 1]?.type === "limiter"
+      ? chain.nodes.length - 1
+      : chain.nodes.length;
+
   return {
     chain: {
       version: HF_AUDIO_FX_CHAIN_VERSION,
       nodes: existing
         ? chain.nodes.map((n) => (n.fromLeveller ? node : n))
-        : [...chain.nodes, node],
+        : [...chain.nodes.slice(0, insertAt), node, ...chain.nodes.slice(insertAt)],
     },
     automation: {
       version: 1,

packages/studio/src/components/editor/propertyPanelAudioFxGroup.tsx

@@ -41,13 +41,15 @@ import {
 import {
   automatedTargetsOf,
   automationAttrValue,
+  withLane,
   HF_AUDIO_AUTOMATION_ATTR,
   HF_AUDIO_AUTOMATION_DATA_KEY,
   readPanelAutomation,
   resolveAutomationRange,
   withoutLane,
   withSeededLane,
 } from "./propertyPanelAutomation";
+import { levellingResult, removeLevelling } from "@hyperframes/core/audio-leveller";
 import type { DomEditSelection } from "./domEditingTypes";
 import { useLivePlayheadTime } from "../../hooks/useLivePlayheadTime";
 import { usePlayerStore } from "../../player";
@@ -483,6 +485,63 @@ export function AudioFxGroup({
    * on this one. The bands replace any previous carve output but leave
    * hand-added effects alone, so re-analysing does not discard other work.
    */
+  /**
+   * Measure THIS track and write the levelling lane.
+   *
+   * Same shape as the carve below it — decode offline, lock the rack while it
+   * works, write once — but it listens to the track it is on rather than to a
+   * voice above it, so it needs no source picker.
+   */
+  const runLeveller = async (): Promise<void> => {
+    const el = element.element;
+    const src = el?.getAttribute("src");
+    const doc = el?.ownerDocument;
+    if (!src || !doc) return;
+    setAnalysing(true);
+    try {
+      const Ctor =
+        window.OfflineAudioContext ??
+        (window as unknown as { webkitOfflineAudioContext?: typeof OfflineAudioContext })
+          .webkitOfflineAudioContext;
+      if (!Ctor) return;
+      const res = await fetch(new URL(src, doc.baseURI).href);
+      const buffer = await new Ctor(1, 1, DECODE_SAMPLE_RATE).decodeAudioData(
+        await res.arrayBuffer(),
+      );
+      const result = levellingResult(chain, buffer.getChannelData(0), buffer.sampleRate);
+      if (!result) return;
+      await onSetAttributeQuiet(HF_AUDIO_FX_ATTR, serializeAudioFxChain(result.chain));
+      // Merged by target, never written wholesale: the script describes its own
+      // lane only, and replacing the attribute would take the carve's lanes and
+      // the volume lane with it.
+      const lane = result.automation.lanes[0];
+      if (lane) {
+        void onSetAttributeQuiet(
+          HF_AUDIO_AUTOMATION_ATTR,
+          automationAttrValue(withLane(automation, lane)) || null,
+        );
+      }
+    } catch {
+      // A track whose audio cannot be fetched or decoded simply gets no
+      // levelling, the same way an unreadable carve source is skipped.
+    } finally {
+      setAnalysing(false);
+    }
+  };
+
+  const removeLeveller = (): void => {
+    const { chain: next, removedTarget } = removeLevelling(chain);
+    void onSetAttributeQuiet(HF_AUDIO_FX_ATTR, serializeAudioFxChain(next));
+    // The lane goes with the node. An orphan keeps driving a parameter that is
+    // no longer in the graph.
+    if (removedTarget) {
+      void onSetAttributeQuiet(
+        HF_AUDIO_AUTOMATION_ATTR,
+        automationAttrValue(withoutLane(automation, removedTarget)) || null,
+      );
+    }
+  };
+
   const analyse = async (active: HfCarveSettings | null = carve): Promise<void> => {
     if (!active?.sources.length) return;
     const doc = element.element?.ownerDocument;
@@ -660,6 +719,9 @@ export function AudioFxGroup({
       onCarveChange={(next) => void setCarve(next)}
       onCarvePreview={(next) => onSetAttributeLive(HF_AUDIO_CARVE_ATTR, JSON.stringify(next))}
       sourceOptions={sourceOptions}
+      onLevel={() => void runLeveller()}
+      onRemoveLevel={removeLeveller}
+      levelled={chain.nodes.some((n) => n.fromLeveller)}
       carvedAgainstBy={carvedAgainstBy}
       analysing={analysing}
     />

packages/studio/src/components/editor/propertyPanelAutomation.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import type { HfAutomation } from "@hyperframes/core/audio-automation";
+import { automationAttrValue, withLane, withoutLane } from "./propertyPanelAutomation.js";
+
+const carved = (): HfAutomation => ({
+  version: 1,
+  lanes: [
+    { target: "fx.n1.gain", points: [{ t: 0, v: -6 }] },
+    { target: "fx.n2.gain", points: [{ t: 0, v: -9 }] },
+    { target: "volume", points: [{ t: 0, v: 0.8 }] },
+  ],
+});
+
+/**
+ * A script hands back a whole `HfAutomation` that describes only its OWN lane.
+ * Writing that to the attribute would take everything else with it — the
+ * carve's per-band lanes and the track's volume lane — which is silent, total,
+ * and only noticed later when the mix has quietly lost its ducking.
+ */
+describe("withLane", () => {
+  it("keeps every lane it was not asked about", () => {
+    const next = withLane(carved(), { target: "fx.n9.gain", points: [{ t: 0, v: 3 }] });
+    expect(next.lanes.map((l) => l.target).sort()).toEqual([
+      "fx.n1.gain",
+      "fx.n2.gain",
+      "fx.n9.gain",
+      "volume",
+    ]);
+    expect(next.lanes.find((l) => l.target === "volume")?.points).toEqual([{ t: 0, v: 0.8 }]);
+  });
+
+  it("replaces a lane rather than adding a second one for the same target", () => {
+    // Re-running a script must not leave two lanes fighting over one parameter.
+    const once = withLane(carved(), { target: "fx.n9.gain", points: [{ t: 0, v: 3 }] });
+    const twice = withLane(once, { target: "fx.n9.gain", points: [{ t: 0, v: 5 }] });
+    expect(twice.lanes.filter((l) => l.target === "fx.n9.gain")).toHaveLength(1);
+    expect(twice.lanes.find((l) => l.target === "fx.n9.gain")?.points).toEqual([{ t: 0, v: 5 }]);
+    expect(twice.lanes).toHaveLength(4);
+  });
+
+  it("does not mutate what it was given", () => {
+    const before = carved();
+    withLane(before, { target: "fx.n9.gain", points: [{ t: 0, v: 3 }] });
+    expect(before.lanes).toHaveLength(3);
+  });
+});
+
+describe("withoutLane", () => {
+  it("takes one lane and leaves the rest", () => {
+    // A node removed without its lane leaves an orphan driving a parameter that
+    // is no longer in the graph.
+    const next = withoutLane(carved(), "fx.n1.gain");
+    expect(next.lanes.map((l) => l.target)).toEqual(["fx.n2.gain", "volume"]);
+  });
+
+  it("empties the attribute when the last lane goes", () => {
+    const one: HfAutomation = { version: 1, lanes: [{ target: "fx.n1.gain", points: [] }] };
+    expect(automationAttrValue(withoutLane(one, "fx.n1.gain"))).toBe("");
+  });
+});

packages/studio/src/components/editor/propertyPanelAutomation.ts

@@ -6,6 +6,7 @@
  * attribute the same way.
  */
 
+import type { HfAutomationLane } from "@hyperframes/core/audio-automation";
 import {
   HF_AUDIO_AUTOMATION_ATTR,
   HF_AUDIO_AUTOMATION_DATA_KEY,
@@ -73,6 +74,21 @@ export function withoutLane(automation: HfAutomation, target: string): HfAutomat
   return { version: 1, lanes: automation.lanes.filter((lane) => lane.target !== target) };
 }
 
+/**
+ * Replace one lane, leaving every other lane alone.
+ *
+ * A script that hands back a whole `HfAutomation` describes only its OWN lane.
+ * Writing that wholesale would take the carve's lanes and the volume lane with
+ * it, so what the script produces has to be merged in by target rather than
+ * swapped for what is already there.
+ */
+export function withLane(automation: HfAutomation, lane: HfAutomationLane): HfAutomation {
+  return {
+    version: 1,
+    lanes: [...automation.lanes.filter((l) => l.target !== lane.target), lane],
+  };
+}
+
 /** The attribute value for an automation set; empty when nothing is automated. */
 export function automationAttrValue(automation: HfAutomation): string {
   return automation.lanes.length > 0 ? serializeAutomation(automation) : "";

packages/studio/src/components/editor/propertyPanelFxSection.test.tsx

@@ -69,6 +69,9 @@ function mount(overrides: Partial<Parameters<typeof FxSection>[0]> = {}) {
       automatedTargets={overrides.automatedTargets}
       onAutomateParam={overrides.onAutomateParam}
       onRemoveParamAutomation={overrides.onRemoveParamAutomation}
+      onLevel={overrides.onLevel}
+      onRemoveLevel={overrides.onRemoveLevel}
+      levelled={overrides.levelled}
     />,
   );
   return { host, onChainChange, onChainPreview, onCarveChange };
@@ -386,6 +389,22 @@ describe("FxSection chain", () => {
     expect(next.nodes.find((n) => n.label === "Middle")!.params!.gain).toBe(0);
   });
 
+  it("offers levelling, and offers to take it away once it is there", () => {
+    const onLevel = vi.fn();
+    const onRemoveLevel = vi.fn();
+    const { host } = mount({ onLevel, onRemoveLevel });
+    click(host.querySelector(".hf-fx-add"));
+    click(byText(host, ".hf-fx-add-composite", "Even Out Levels"));
+    expect(onLevel).toHaveBeenCalledTimes(1);
+
+    const already = mount({ onLevel, onRemoveLevel, levelled: true });
+    click(already.host.querySelector(".hf-fx-add"));
+    // The same control, because adding a second levelling stage is never what
+    // an author means by pressing it twice.
+    click(byText(already.host, ".hf-fx-add-composite", "Remove levelling"));
+    expect(onRemoveLevel).toHaveBeenCalledTimes(1);
+  });
+
   it("cannot move the ends past themselves", () => {
     const { host } = mount({ chain: chainOf("peaking", "reverb") });
     const ups = host.querySelectorAll('.hf-fx-move[title="Move up"]');

packages/studio/src/components/editor/propertyPanelFxSection.tsx

@@ -649,6 +649,12 @@ export interface FxSectionProps {
   onRemoveParamAutomation?(nodeId: string, paramKey: string): void;
   /** Delete every lane belonging to a node that is being removed. */
   onRemoveNodeAutomation?(nodeId: string): void;
+  /** Measure this track and write the levelling lane. Absent when unavailable. */
+  onLevel?(): void;
+  /** Take the levelling stage and its lane back out. */
+  onRemoveLevel?(): void;
+  /** Whether a levelling stage is already on the track. */
+  levelled?: boolean;
   /** Structural edits and gesture-end writes; this is the one that persists. */
   onChainChange(chain: HfAudioFxChain): void;
   /** Continuous updates while a control is being dragged. */
@@ -686,6 +692,9 @@ export function FxSection({
   sourceOptions,
   analysing,
   disabled,
+  onLevel,
+  onRemoveLevel,
+  levelled,
 }: FxSectionProps) {
   // Falls back to the persisting write when no preview handler is supplied, which
   // keeps the control working rather than going dead.
@@ -908,6 +917,21 @@ export function FxSection({
             <span className="hf-fx-add-group-label w-full font-mono text-[9px] uppercase tracking-wide text-panel-text-4">
               Tone
             </span>
+            {onLevel ? (
+              <button
+                type="button"
+                className="hf-fx-add-composite rounded-[3px] bg-panel-surface px-1.5 py-0.5 text-[10px] text-panel-text-1 hover:text-panel-text-0"
+                title="Listen to this track and even out its loud and quiet parts."
+                disabled={disabled || analysing}
+                onClick={() => {
+                  if (levelled) onRemoveLevel?.();
+                  else onLevel();
+                  setAdding(false);
+                }}
+              >
+                {levelled ? "Remove levelling" : "Even Out Levels"}
+              </button>
+            ) : null}
             <button
               type="button"
               // Not hf-fx-add-item: Tone is a composite over several filters,