@hyperframes/studio 0.7.106 → 0.7.108

package/src/components/editor/useFxAudition.ts

@@ -0,0 +1,95 @@
+/**
+ * Preview a hypothetical chain without committing to it, and put it back on
+ * the way out — the machinery behind hovering a preset or an add-menu item.
+ *
+ * Split out of `propertyPanelFxSection.tsx`, whose `audition` callback and its
+ * teardown effect this was.
+ */
+
+import { useCallback, useEffect, useRef } from "react";
+import type { HfAudioFxChain } from "@hyperframes/core/audio-fx";
+
+export function useFxAudition(
+  chain: HfAudioFxChain,
+  onChainPreview: ((chain: HfAudioFxChain) => void) | undefined,
+  onAuditionTransport: ((on: boolean) => void) | undefined,
+) {
+  /**
+   * The chain as it is really stored, captured when an audition starts.
+   *
+   * Auditioning writes through the preview channel, which does not persist and
+   * does not come back as a new `chain` prop — so reverting has to remember what
+   * was there rather than read it back. Null means nothing is being auditioned,
+   * which is also what makes a stray leave a no-op instead of a write.
+   */
+  const auditionBase = useRef<HfAudioFxChain | null>(null);
+
+  /**
+   * Play something without committing to it, and put it back on the way out.
+   *
+   * Hearing a preset before choosing it is the strongest affordance in this
+   * panel — see `plans/audio-fx-ux/README.md` §Decided. It costs nothing new:
+   * the preview channel a slider drag already uses rebuilds the running graph
+   * without touching the document.
+   */
+  const audition = useCallback(
+    (make: ((base: HfAudioFxChain) => HfAudioFxChain) | null) => {
+      if (!onChainPreview) return;
+      if (make) {
+        auditionBase.current ??= chain;
+        onChainPreview(make(auditionBase.current));
+        // After the chain is in the graph, not before: starting the transport
+        // first plays a moment of the un-auditioned mix.
+        onAuditionTransport?.(true);
+      } else if (auditionBase.current) {
+        // Stop before reverting, for the mirror of that reason — the last thing
+        // heard should be the preset, not a frame of the chain coming back.
+        onAuditionTransport?.(false);
+        onChainPreview(auditionBase.current);
+        auditionBase.current = null;
+      }
+    },
+    [chain, onChainPreview, onAuditionTransport],
+  );
+
+  /**
+   * Drop whatever is being auditioned WITHOUT reverting the preview, for a
+   * caller that is about to mutate the real chain anyway — reverting first
+   * would be a chain the document never sees, immediately overwritten.
+   */
+  const clearAudition = useCallback(() => {
+    auditionBase.current = null;
+    onAuditionTransport?.(false);
+  }, [onAuditionTransport]);
+
+  /**
+   * The preview handler as of the last render, held rather than closed over.
+   *
+   * The teardown below must run on teardown and at no other time, so its deps
+   * have to be empty — and `onChainPreview` is an inline arrow in the group,
+   * which re-renders on every playhead tick to move the automation readouts. A
+   * dep on it made React tear down and re-run the effect on every one of those
+   * ticks, so an audition reverted itself about 30 times a second while the
+   * pointer was still on the button: the preset was heard for a frame during
+   * playback, which is the exact case the whole affordance exists for.
+   */
+  const previewRef = useRef(onChainPreview);
+  previewRef.current = onChainPreview;
+
+  // Leaving by any route other than the pointer — the element deselected, the
+  // panel closed — would otherwise leave the audition playing over a chain the
+  // document does not have.
+  const transportRef = useRef(onAuditionTransport);
+  transportRef.current = onAuditionTransport;
+  useEffect(
+    () => () => {
+      if (auditionBase.current) {
+        transportRef.current?.(false);
+        previewRef.current?.(auditionBase.current);
+      }
+    },
+    [],
+  );
+
+  return { audition, clearAudition };
+}

package/src/components/editor/useFxChainObserved.ts

@@ -0,0 +1,83 @@
+/**
+ * Report the shape of a chain this panel did not write.
+ *
+ * Split out of `propertyPanelAudioFxGroup.tsx`, which owned this whole
+ * provenance mechanism before the file grew past a size where it was still
+ * one thing to read alongside the carve and the leveller.
+ */
+
+import { useEffect, useRef } from "react";
+import type { HfAudioFxChain } from "@hyperframes/core/audio-fx";
+import { classifyAudioName, type HfCarveSettings } from "@hyperframes/core/audio-carve";
+import type { HfAutomation } from "@hyperframes/core/audio-automation";
+import { trackChainObserved } from "./audioFxTelemetry.js";
+import type { DomEditSelection } from "./domEditingTypes";
+
+/**
+ * This is the only way agent-applied effects become visible. An agent asked to
+ * fix a mix does not drive this panel — it edits the composition HTML, or runs
+ * `scripts/carve.mjs`, and the rack simply finds the work already done. Not
+ * one of the panel's own events fires for any of it.
+ *
+ * So: watch the chain's shape, and report it when it changes without a panel
+ * edit behind it. `panelEdits` is the discriminator — this session's own
+ * writes bump it, so a chain that moved while the counter stood still moved
+ * because something outside the studio moved it.
+ *
+ * Keyed on the shape rather than fired once per mount: a soft reload after an
+ * agent edits the file re-mounts this component, and a mount-only event would
+ * either miss the change or double-count every HMR. Comparing the fingerprint
+ * reports real changes and stays quiet through both.
+ *
+ * Returns a wrapped `onSetAttributeQuiet` that every other write in the panel
+ * must go through instead of the raw prop: the count is only meaningful if it
+ * is exhaustive, and a write added later that forgot to route through here
+ * would silently start reporting the author's own edits as having come from
+ * outside.
+ */
+export function useFxChainObserved(
+  element: DomEditSelection,
+  chain: HfAudioFxChain,
+  carve: HfCarveSettings | null,
+  automation: HfAutomation,
+  onSetAttributeQuietRaw: (attr: string, value: string | null) => void | Promise<void>,
+): (attr: string, value: string | null) => void | Promise<void> {
+  const lastShape = useRef<string | null>(null);
+  const panelEdits = useRef(0);
+
+  const onSetAttributeQuiet = (attr: string, value: string | null): void | Promise<void> => {
+    panelEdits.current += 1;
+    return onSetAttributeQuietRaw(attr, value);
+  };
+
+  useEffect(() => {
+    const shape = JSON.stringify([
+      chain.nodes.map((n) => `${n.type}:${n.fromPreset ?? ""}:${n.fromCarve ? 1 : 0}`),
+      carve?.enabled ?? false,
+      automation.lanes.length,
+    ]);
+    if (lastShape.current === shape) return;
+    const firstSight = lastShape.current === null;
+    lastShape.current = shape;
+    // An empty chain on first sight is the ordinary case — nothing to report.
+    if (firstSight && chain.nodes.length === 0 && !carve) return;
+    trackChainObserved(
+      chain,
+      {
+        firstSight,
+        panelEdits: panelEdits.current,
+        hasCarve: Boolean(carve?.enabled),
+        hasAutomation: automation.lanes.length > 0,
+      },
+      {
+        trackKind: classifyAudioName(element.id, element.element?.getAttribute("src")) ?? undefined,
+      },
+    );
+    // Each observation is measured against the edits made SINCE the last one, so
+    // a session that edits, then receives an outside change, still reports that
+    // second change as unattributed.
+    panelEdits.current = 0;
+  });
+
+  return onSetAttributeQuiet;
+}

package/src/components/editor/useFxLevelling.ts

@@ -0,0 +1,235 @@
+/**
+ * The levelling script and its playhead-transport audition: measure this
+ * track, write the "Even Out Levels" node and lane, and preview the result
+ * before committing to it.
+ *
+ * Split out of `propertyPanelAudioFxGroup.tsx`, which owned all of this before
+ * the file grew past a size where "levelling" was still one thing to read.
+ */
+
+import { useRef, useState } from "react";
+import {
+  HF_AUDIO_FX_ATTR,
+  serializeAudioFxChain,
+  type HfAudioFxChain,
+} from "@hyperframes/core/audio-fx";
+import { levellingResult, removeLevelling } from "@hyperframes/core/audio-leveller";
+import type { HfAutomation } from "@hyperframes/core/audio-automation";
+import {
+  automationAttrValue,
+  HF_AUDIO_AUTOMATION_ATTR,
+  withLane,
+  withoutLane,
+} from "./propertyPanelAutomation";
+import { trackLeveller } from "./audioFxTelemetry.js";
+import type { DomEditSelection } from "./domEditingTypes";
+import { usePlayerStore } from "../../player";
+
+/**
+ * Rate the track is decoded at. Analysis is self-consistent because it reads
+ * the decoded buffer's own rate, so this only has to be a sane audio rate.
+ */
+const DECODE_SAMPLE_RATE = 48000;
+
+/** A parsed attribute, kept only when it is a usable positive number. */
+function positiveFinite(n: number): number | null {
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+export function useFxLevelling(
+  element: DomEditSelection,
+  chain: HfAudioFxChain,
+  automation: HfAutomation,
+  onSetAttributeQuiet: (attr: string, value: string | null) => void | Promise<void>,
+  onSetAttributeLive: (attr: string, value: string | null) => void | Promise<void>,
+  setAnalysing: (value: boolean) => void,
+) {
+  /**
+   * This track's audio, decoded once and kept.
+   *
+   * Levelling is measured from it, and hover-auditioning means measuring on every
+   * pass over the button — fetching and decoding a several-minute voiceover each
+   * time would make the audition slower than the thing it is previewing. Keyed by
+   * `src` so a track pointed at a different file re-decodes.
+   */
+  const decoded = useRef<{ src: string; samples: Float32Array; sampleRate: number } | null>(null);
+
+  const decodeTrack = async (): Promise<{ samples: Float32Array; sampleRate: number } | null> => {
+    const el = element.element;
+    const src = el?.getAttribute("src");
+    const doc = el?.ownerDocument;
+    if (!src || !doc) return null;
+    const cached = decoded.current;
+    if (cached?.src === src) return cached;
+    const Ctor =
+      window.OfflineAudioContext ??
+      (window as unknown as { webkitOfflineAudioContext?: typeof OfflineAudioContext })
+        .webkitOfflineAudioContext;
+    if (!Ctor) return null;
+    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 next = { src, samples: buffer.getChannelData(0), sampleRate: buffer.sampleRate };
+    decoded.current = next;
+    return next;
+  };
+
+  /**
+   * The part of the decoded file this clip actually plays.
+   *
+   * A lane's `t` is seconds from the start of the CLIP, but the decode is the
+   * whole file from its first sample — so measuring a trimmed clip produced an
+   * envelope offset by the trim, and every correction landed early by exactly
+   * `media-start`. Slicing here is what puts the two clocks back on the same
+   * zero.
+   */
+  const clipWindow = (audio: { samples: Float32Array; sampleRate: number }) => {
+    const mediaStart = positiveFinite(Number(element.dataAttributes?.["media-start"] ?? 0));
+    const duration = positiveFinite(Number(element.dataAttributes?.["duration"] ?? Number.NaN));
+    const from = mediaStart
+      ? Math.min(audio.samples.length, Math.floor(mediaStart * audio.sampleRate))
+      : 0;
+    const to = duration
+      ? Math.min(audio.samples.length, from + Math.ceil(duration * audio.sampleRate))
+      : audio.samples.length;
+    return from === 0 && to === audio.samples.length
+      ? audio.samples
+      : audio.samples.subarray(from, to);
+  };
+
+  const runLeveller = async (): Promise<void> => {
+    setAnalysing(true);
+    try {
+      const audio = await decodeTrack();
+      if (!audio) return;
+      const result = levellingResult(chain, clipWindow(audio), audio.sampleRate);
+      if (!result) return;
+      trackLeveller("run");
+      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);
+    }
+  };
+
+  /**
+   * Where the playhead was when an audition started the transport, so leaving
+   * can put it back. Null means this audition did not start playback — the
+   * transport was already running and must be left alone.
+   */
+  const auditionReturn = useRef<number | null>(null);
+
+  /**
+   * Start playback for an audition, and stop it again on the way out.
+   *
+   * An audition writes the preset to the running graph, which is silent while
+   * the transport is paused — so a paused author hovering a preset heard
+   * nothing at all, and the whole affordance only worked mid-playback. Hovering
+   * now plays from the playhead, and leaving stops and rewinds to exactly where
+   * it started: browsing the shelf must not cost the author their place.
+   *
+   * Already playing, this does nothing in either direction. The author started
+   * that, and stopping their transport because they passed over a preset would
+   * be the panel taking a decision that was not offered to it.
+   */
+  const auditionTransport = (on: boolean): void => {
+    const store = usePlayerStore.getState();
+    if (on) {
+      if (store.isPlaying || auditionReturn.current !== null) return;
+      auditionReturn.current = store.currentTime;
+      store.requestPlayback(true);
+      return;
+    }
+    const returnTo = auditionReturn.current;
+    if (returnTo === null) return;
+    auditionReturn.current = null;
+    store.requestPlayback(false, returnTo);
+  };
+
+  const [auditioningLevel, setAuditioningLevel] = useState(false);
+  /**
+   * Bumped on every enter and leave, so a measurement can tell whether the
+   * pointer is still on the button when it finishes.
+   *
+   * Decoding a long voiceover takes seconds, and a hover that takes seconds is
+   * one the author has usually already left. Applying the result then would put
+   * levelling on a track nobody asked to level, through a channel that does not
+   * persist — so it would be audible, invisible in the document, and gone on the
+   * next reload. This counter is what makes a late result a no-op.
+   */
+  const auditionRun = useRef(0);
+
+  /** Both attributes back to the stored chain, because levelling is a node AND the lane that drives it. */
+  const stopLevelAudition = (): void => {
+    setAuditioningLevel(false);
+    void onSetAttributeLive(
+      HF_AUDIO_FX_ATTR,
+      chain.nodes.length ? serializeAudioFxChain(chain) : null,
+    );
+    void onSetAttributeLive(HF_AUDIO_AUTOMATION_ATTR, automationAttrValue(automation) || null);
+  };
+
+  /** Measure this track and play the levelling without persisting it. */
+  const startLevelAudition = async (run: number): Promise<void> => {
+    setAuditioningLevel(true);
+    try {
+      const audio = await decodeTrack();
+      // Gone, or superseded by a later hover. Either way this result is stale.
+      if (!audio || run !== auditionRun.current) return;
+      const result = levellingResult(chain, clipWindow(audio), audio.sampleRate);
+      if (!result || run !== auditionRun.current) return;
+      void onSetAttributeLive(HF_AUDIO_FX_ATTR, serializeAudioFxChain(result.chain));
+      const lane = result.automation.lanes[0];
+      if (lane) {
+        void onSetAttributeLive(
+          HF_AUDIO_AUTOMATION_ATTR,
+          automationAttrValue(withLane(automation, lane)) || null,
+        );
+      }
+    } catch {
+      // Same as the real run: a track that cannot be decoded simply does not
+      // audition, rather than failing the panel.
+    } finally {
+      if (run === auditionRun.current) setAuditioningLevel(false);
+    }
+  };
+
+  /**
+   * `false` puts the stored chain and automation back; `true` measures and
+   * plays the result without persisting it.
+   */
+  const auditionLevel = async (on: boolean): Promise<void> => {
+    const run = ++auditionRun.current;
+    if (!on) return stopLevelAudition();
+    await startLevelAudition(run);
+  };
+
+  const removeLeveller = (): void => {
+    trackLeveller("removed");
+    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,
+      );
+    }
+  };
+
+  return { runLeveller, auditionTransport, auditioningLevel, auditionLevel, removeLeveller };
+}

package/src/components/editor/useInlineTextEditing.tsx

@@ -0,0 +1,119 @@
+import { useRef, type ReactNode, type RefObject } from "react";
+import { InlineTextToolbar } from "./InlineTextToolbar";
+import { useDomEditActionsContextOptional } from "../../contexts/DomEditContext";
+import { useInlineTextEdit } from "../../hooks/useInlineTextEdit";
+import { usePlayerStore } from "../../player/store/playerStore";
+import { getPreviewTargetFromPointer } from "../../utils/studioPreviewHelpers";
+import {
+  canEditElementTextInline,
+  canEditTextInline,
+  isDoublePress,
+  type PressMark,
+} from "./domEditInlineText";
+import type { DomEditSelection } from "./domEditingTypes";
+
+/**
+ * The canvas' side of editing text where it sits.
+ *
+ * Holds the session, decides which presses open one, and knows the two things
+ * the canvas has to do differently while one is open: stand aside so the caret
+ * underneath can be reached, and stop taking focus back.
+ *
+ * The actions context is read here rather than threaded through the overlay's
+ * props, the same way the agent surfaces in that overlay read it, and it is
+ * absent in standalone player mounts, which have no project to edit.
+ */
+export function useInlineTextEditing(selectionRef: RefObject<DomEditSelection | null>): {
+  editing: boolean;
+  /** Open an edit when this press pairs with the last one. */
+  startFromPress: (event: { clientX: number; clientY: number }) => boolean;
+  /** Handle a key on the canvas. Returns true when it opened an edit. */
+  handleKeyDown: (event: {
+    key: string;
+    shiftKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    altKey: boolean;
+  }) => boolean;
+  /**
+   * The styling controls for the current selection, for the caller to render.
+   *
+   * Handed back rather than mounted somewhere central because it belongs to the
+   * session this hook owns, and appears and disappears with it.
+   */
+  toolbar: ReactNode;
+} {
+  const actions = useDomEditActionsContextOptional();
+  const inlineText = useInlineTextEdit({
+    onCommit: (commit) => void actions?.handleDomRichTextCommit(commit),
+    onPause: () => usePlayerStore.getState().setIsPlaying(false),
+  });
+  const lastPressRef = useRef<PressMark | null>(null);
+
+  /**
+   * The element under this press, hit-tested now rather than read from state.
+   *
+   * Every cached answer in the overlay is React state that has not caught up
+   * with the press happening now: the hover is documented as an async cache,
+   * and the selection from the first press has not re-rendered. Reading either
+   * meant the first double press on any element opened nothing, which is every
+   * double press that matters.
+   */
+  const elementUnderPress = (event: { clientX: number; clientY: number }) => {
+    const iframe = actions?.previewIframeRef?.current;
+    if (!iframe) return null;
+    // Studio suppresses pointer events inside the composition so the canvas
+    // overlay can own input, which means a plain elementFromPoint only ever
+    // finds wrappers. This helper lifts that for the length of the hit test,
+    // and is the same one the canvas uses to decide what was clicked.
+    return getPreviewTargetFromPointer(
+      iframe,
+      event.clientX,
+      event.clientY,
+      selectionRef.current?.compositionPath ?? null,
+    );
+  };
+
+  /** A point on Studio's canvas, in the scaled composition's coordinates. */
+  const compositionPoint = (event: { clientX: number; clientY: number }) => {
+    const iframe = actions?.previewIframeRef?.current;
+    const view = iframe?.contentWindow;
+    if (!iframe || !view?.innerWidth) return undefined;
+    const box = iframe.getBoundingClientRect();
+    const scale = box.width / view.innerWidth || 1;
+    return { x: (event.clientX - box.left) / scale, y: (event.clientY - box.top) / scale };
+  };
+
+  return {
+    editing: inlineText.session !== null,
+    toolbar: (
+      <InlineTextToolbar
+        session={inlineText.session}
+        iframe={actions?.previewIframeRef?.current ?? null}
+      />
+    ),
+    // Enter opens the selected element's text, the way every design tool does,
+    // and is the dependable way in: a double press has to survive the canvas'
+    // gesture machinery, while this is one key on a selection that has settled.
+    handleKeyDown: (event) => {
+      if (event.key !== "Enter" || event.shiftKey || event.ctrlKey || event.metaKey || event.altKey)
+        return false;
+      const target = selectionRef.current;
+      if (inlineText.session || !target || !canEditTextInline(target)) return false;
+      return inlineText.start(target.element);
+    },
+    startFromPress: (event) => {
+      if (inlineText.session) return false;
+      const element = elementUnderPress(event);
+      const press = { x: event.clientX, y: event.clientY, at: Date.now(), element };
+      const paired = isDoublePress(lastPressRef.current, press);
+      lastPressRef.current = press;
+
+      if (!paired) return false;
+      if (!element || !canEditElementTextInline(element)) return false;
+      // The caret opens where the press landed, which means mapping the point
+      // out of Studio's coordinates and into the composition's own.
+      return inlineText.start(element, compositionPoint(event));
+    },
+  };
+}

package/src/components/editor/useVolumeAutomation.test.tsx

@@ -0,0 +1,122 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { createRoot } from "react-dom/client";
+import { useVolumeAutomation, type VolumeAutomationBinding } from "./useVolumeAutomation";
+import type { DomEditSelection } from "./domEditingTypes";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+function bind(dataAttributes: Record<string, string>) {
+  const onSetAttributeQuiet = vi.fn();
+  const captured: { current: VolumeAutomationBinding | null } = { current: null };
+  function Probe() {
+    captured.current = useVolumeAutomation(
+      { dataAttributes } as unknown as DomEditSelection,
+      onSetAttributeQuiet,
+    );
+    return null;
+  }
+  const host = document.createElement("div");
+  document.body.append(host);
+  act(() => {
+    createRoot(host).render(<Probe />);
+  });
+  if (!captured.current) throw new Error("hook never ran");
+  return { binding: captured.current, onSetAttributeQuiet };
+}
+
+const volumeLane = (v: number) =>
+  JSON.stringify({ version: 1, lanes: [{ target: "volume", points: [{ t: 0, v }] }] });
+
+describe("useVolumeAutomation", () => {
+  it("reports an unautomated track", () => {
+    expect(bind({ volume: "0.55" }).binding.volumeAutomated).toBe(false);
+  });
+
+  it("reports a track with a volume lane", () => {
+    expect(bind({ volume: "0.55", automation: volumeLane(0.2) }).binding.volumeAutomated).toBe(
+      true,
+    );
+  });
+
+  it("does not count an FX lane as automating the volume", () => {
+    const automation = JSON.stringify({
+      version: 1,
+      lanes: [{ target: "fx.n1.frequency", points: [{ t: 0, v: 400 }] }],
+    });
+    expect(bind({ volume: "0.55", automation }).binding.volumeAutomated).toBe(false);
+  });
+
+  it("seeds a new lane at the level the slider already shows", () => {
+    // Automating a track must not change how loud it is.
+    const { binding, onSetAttributeQuiet } = bind({ volume: "0.55" });
+    act(() => binding.onAutomateVolume());
+    expect(onSetAttributeQuiet).toHaveBeenCalledWith(
+      "data-automation",
+      JSON.stringify({ version: 1, lanes: [{ target: "volume", points: [{ t: 0, v: 0.55 }] }] }),
+    );
+  });
+
+  it("treats a missing data-volume as unity", () => {
+    const { binding, onSetAttributeQuiet } = bind({});
+    act(() => binding.onAutomateVolume());
+    expect(JSON.parse(String(onSetAttributeQuiet.mock.calls[0][1])).lanes[0].points[0].v).toBe(1);
+  });
+
+  it("keeps FX lanes when adding the volume one", () => {
+    const automation = JSON.stringify({
+      version: 1,
+      lanes: [{ target: "fx.n1.frequency", points: [{ t: 0, v: 400 }] }],
+    });
+    const { binding, onSetAttributeQuiet } = bind({ volume: "0.4", automation });
+    act(() => binding.onAutomateVolume());
+    expect(
+      JSON.parse(String(onSetAttributeQuiet.mock.calls[0][1])).lanes.map(
+        (l: { target: string }) => l.target,
+      ),
+    ).toEqual(["fx.n1.frequency", "volume"]);
+  });
+
+  it("deletes only the volume lane", () => {
+    const automation = JSON.stringify({
+      version: 1,
+      lanes: [
+        { target: "volume", points: [{ t: 0, v: 0.2 }] },
+        { target: "fx.n1.frequency", points: [{ t: 0, v: 400 }] },
+      ],
+    });
+    const { binding, onSetAttributeQuiet } = bind({ volume: "0.4", automation });
+    act(() => binding.onRemoveVolumeAutomation());
+    expect(
+      JSON.parse(String(onSetAttributeQuiet.mock.calls[0][1])).lanes.map(
+        (l: { target: string }) => l.target,
+      ),
+    ).toEqual(["fx.n1.frequency"]);
+  });
+
+  it("clears the attribute when the volume lane was the only one", () => {
+    const { binding, onSetAttributeQuiet } = bind({ volume: "0.4", automation: volumeLane(0.2) });
+    act(() => binding.onRemoveVolumeAutomation());
+    // Null, not "": the quiet path removes an attribute it is given null for.
+    expect(onSetAttributeQuiet).toHaveBeenCalledWith("data-automation", null);
+  });
+
+  it("reads an unreadable attribute as no automation", () => {
+    expect(bind({ volume: "0.55", automation: "{not json" }).binding.volumeAutomated).toBe(false);
+  });
+
+  it("seeds at unity when data-volume is present but empty", () => {
+    // Number("") is 0, so `?? "1"` alone seeded the lane at silence while the
+    // engine read the same empty attribute as unity.
+    const { binding, onSetAttributeQuiet } = bind({ volume: "" });
+    act(() => binding.onAutomateVolume());
+    expect(JSON.parse(String(onSetAttributeQuiet.mock.calls[0][1])).lanes[0].points[0].v).toBe(1);
+  });
+
+  it("seeds at unity when data-volume is not a number", () => {
+    const { binding, onSetAttributeQuiet } = bind({ volume: "loud" });
+    act(() => binding.onAutomateVolume());
+    expect(JSON.parse(String(onSetAttributeQuiet.mock.calls[0][1])).lanes[0].points[0].v).toBe(1);
+  });
+});