@hyperframes/studio 0.7.107 → 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/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);
+  });
+});

package/src/components/editor/useVolumeAutomation.ts

@@ -0,0 +1,54 @@
+/**
+ * The volume lane's state and edits for the media section.
+ *
+ * Volume lives in a different panel section from the FX chain, but is automated
+ * the same way, so it reads and writes through the same helper the FX group uses
+ * rather than a second interpretation of the attribute.
+ */
+
+import { HF_AUDIO_AUTOMATION_DATA_KEY, VOLUME_TARGET } from "@hyperframes/core/audio-automation";
+import type { DomEditSelection } from "./domEditingTypes";
+import {
+  automationAttrValue,
+  HF_AUDIO_AUTOMATION_ATTR,
+  readPanelAutomation,
+  withoutLane,
+  withSeededLane,
+} from "./propertyPanelAutomation";
+
+export interface VolumeAutomationBinding {
+  volumeAutomated: boolean;
+  onAutomateVolume: () => void;
+  onRemoveVolumeAutomation: () => void;
+}
+
+export function useVolumeAutomation(
+  element: DomEditSelection,
+  onSetAttributeQuiet: (attr: string, value: string | null) => void | Promise<void>,
+): VolumeAutomationBinding {
+  // The chain is not needed to resolve a volume lane — volume is always a valid
+  // target — so this deliberately does not parse it.
+  const automation = readPanelAutomation(
+    element.dataAttributes?.[HF_AUDIO_AUTOMATION_DATA_KEY],
+    undefined,
+  );
+  const write = (next: Parameters<typeof automationAttrValue>[0]): void => {
+    // Quiet: clicking the toggle used to reload the preview and restart every
+    // playing track, while the same click on an effect parameter did not.
+    void onSetAttributeQuiet(HF_AUDIO_AUTOMATION_ATTR, automationAttrValue(next) || null);
+  };
+  // `??` alone would let an empty `data-volume` through as Number("") === 0, so
+  // automating the track would seed its lane at silence. The engine reads the same
+  // empty value as unity.
+  const raw = element.dataAttributes?.["volume"];
+  const parsed = raw ? Number(raw) : 1;
+  const current = Number.isFinite(parsed) ? parsed : 1;
+  return {
+    volumeAutomated: automation.lanes.some((lane) => lane.target === VOLUME_TARGET),
+    // Seeded at the level the slider already shows, so automating the track does
+    // not change how loud it is.
+    onAutomateVolume: () =>
+      write(withSeededLane(automation, VOLUME_TARGET, Number.isFinite(current) ? current : 1)),
+    onRemoveVolumeAutomation: () => write(withoutLane(automation, VOLUME_TARGET)),
+  };
+}

package/src/contexts/DomEditContext.tsx

@@ -15,6 +15,7 @@ export interface DomEditActionsValue extends Pick<
   | "handleDomStyleCommit"
   | "handleDomAttributeCommit"
   | "handleDomAttributeLiveCommit"
+  | "handleDomAttributeQuietCommit"
   | "handleDomHtmlAttributeCommit"
   | "handleDomAttributesCommit"
   | "handleDomPathOffsetCommit"
@@ -116,6 +117,13 @@ export function useDomEditSelectionContext(): DomEditSelectionValue {
   return ctx;
 }
 
+/** Optional counterpart to useDomEditActionsContextOptional — same reason: the
+ *  player package's own components mount outside a provider in standalone and
+ *  test trees, where "no dom-edit selection" is the correct answer. */
+export function useDomEditSelectionContextOptional(): DomEditSelectionValue | null {
+  return useContext(DomEditSelectionContext);
+}
+
 /** @deprecated Prefer useDomEditActionsContext or useDomEditSelectionContext. */
 export function useDomEditContext(): DomEditValue {
   return { ...useDomEditActionsContext(), ...useDomEditSelectionContext() };
@@ -140,6 +148,7 @@ export function DomEditProvider({
     handleDomStyleCommit,
     handleDomAttributeCommit,
     handleDomAttributeLiveCommit,
+    handleDomAttributeQuietCommit,
     handleDomHtmlAttributeCommit,
     handleDomAttributesCommit,
     handleDomPathOffsetCommit,
@@ -229,6 +238,7 @@ export function DomEditProvider({
       handleDomStyleCommit,
       handleDomAttributeCommit,
       handleDomAttributeLiveCommit,
+      handleDomAttributeQuietCommit,
       handleDomHtmlAttributeCommit,
       handleDomAttributesCommit,
       handleDomPathOffsetCommit,
@@ -299,6 +309,7 @@ export function DomEditProvider({
       handleDomStyleCommit,
       handleDomAttributeCommit,
       handleDomAttributeLiveCommit,
+      handleDomAttributeQuietCommit,
       handleDomHtmlAttributeCommit,
       handleDomAttributesCommit,
       handleDomPathOffsetCommit,