@hyperframes/studio 0.8.10 → 0.8.12

package/src/components/editor/propertyPanelFxSection.tsx

@@ -5,7 +5,8 @@
  * is not an entry in the chain.
  */
 
-import { useCallback, useMemo, useState, type KeyboardEvent } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, type KeyboardEvent } from "react";
+import { audioFxRevealTarget, scrollRevealedRowIntoView } from "./audioFxRevealTarget.js";
 import {
   defaultAudioFxParams,
   mintAudioFxNodeId,
@@ -25,6 +26,7 @@ import { applyAudioFxProfile, getAudioFxProfile } from "@hyperframes/core/audio-
 import { audioFxJobNode, type HfAudioFxJob } from "@hyperframes/core/audio-fx-jobs";
 import { FxPresetMenu } from "./propertyPanelFxPresetMenu.js";
 import { FxRackChain } from "./propertyPanelFxRackChain.js";
+import { CLIP_SIGNAL_PATH } from "./audioFxSignalPath.js";
 import { FxAddMenu } from "./propertyPanelFxAddMenu.js";
 import { useFxAudition } from "./useFxAudition.js";
 import {
@@ -103,6 +105,9 @@ export function FxSection({
   onRemovePresetAutomation,
   automatedPresets,
   onAuditionTransport,
+  signalPath,
+  revealTarget,
+  revealNonce,
 }: FxSectionProps) {
   const presetAutomated = automatedPresets ?? new Set<string>();
   // Falls back to the persisting write when no preview handler is supplied, which
@@ -134,11 +139,18 @@ export function FxSection({
     [chain, onChainPreview],
   );
 
-  const { audition, clearAudition } = useFxAudition(chain, onChainPreview, onAuditionTransport);
+  const { audition, clearAudition, storedChain } = useFxAudition(
+    chain,
+    onChainPreview,
+    onAuditionTransport,
+  );
 
   const applyPreset = useCallback(
     (id: string) => {
-      const next = applyPresetToChain(chain, id, trackKind);
+      // The stored chain, not whatever is being auditioned on top of it — see
+      // `storedChain`. Clicking preset B while hovering preset A used to save
+      // both, which is heard as the effect running twice.
+      const next = applyPresetToChain(storedChain(), id, trackKind);
       if (!next) return;
       // The audition WAS this, so there is nothing to put back — and putting the
       // old chain back over the write that just landed is a race the author
@@ -150,7 +162,7 @@ export function FxSection({
       setOpenNode(next.nodes.findIndex((n) => n.fromPreset === id));
       setPicking(false);
     },
-    [chain, mutate, clearAudition, trackKind],
+    [storedChain, mutate, clearAudition, trackKind],
   );
 
   const addJob = useCallback(
@@ -311,6 +323,51 @@ export function FxSection({
   }, [handBuilt, eqIds.length, showCarve]);
   const [openEq, setOpenEq] = useState<string | null>(null);
 
+  /** The reveal request held until its row is mounted and scrolled. */
+  const [consumedRevealNonce, setConsumedRevealNonce] = useState<number | null>(null);
+  const [pendingReveal, setPendingReveal] = useState<{
+    nonce: number;
+    target: string;
+  } | null>(null);
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  if (revealNonce != null && revealNonce !== consumedRevealNonce) {
+    setConsumedRevealNonce(revealNonce);
+    const where = revealTarget ? audioFxRevealTarget(revealTarget, chain) : null;
+    if (where) {
+      // Each surface has its own open-state; the resolver says which one owns
+      // this parameter. Opening the wrong one leaves the click looking dead.
+      if (where.kind === "node") setOpenNode(where.index);
+      if (where.kind === "eq") setOpenEq(where.eqId);
+      if (where.kind === "carve") setCarveOpen(true);
+      if (where.kind === "preset") {
+        setCollapsedRuns((was) => {
+          if (!was.has(where.runKey)) return was;
+          const next = new Set(was);
+          next.delete(where.runKey);
+          return next;
+        });
+      }
+    }
+    setPendingReveal(where && revealTarget ? { nonce: revealNonce, target: revealTarget } : null);
+  }
+
+  /**
+   * Scroll the revealed parameter into view once its row has actually mounted.
+   *
+   * The request itself is a dependency so a second click on an already-open
+   * surface still scrolls. It is cleared once used, so a later unrelated
+   * re-render does not yank the panel back to an old parameter.
+   */
+  useEffect(() => {
+    const target = pendingReveal?.target;
+    if (target && scrollRevealedRowIntoView(rootRef.current, target, chain)) {
+      setPendingReveal(null);
+    }
+    // `chain` is deliberately not a dependency: it changes on every knob edit,
+    // and re-running then would scroll the panel while the author is dragging.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [openNode, openEq, carveOpen, collapsedRuns, pendingReveal]);
+
   const addEq = useCallback(() => {
     clearAudition();
     const { chain: next, eqId } = addAudioEq(chain);
@@ -404,12 +461,14 @@ export function FxSection({
 
   return (
     <div
+      ref={rootRef}
       className="hf-fx-section space-y-2"
       // Focus lives on the buttons and menu items inside, so the keystroke
       // bubbles to here without the section needing focus of its own.
       onKeyDown={closeMenus}
     >
       <FxRackChain
+        signalPath={signalPath ?? CLIP_SIGNAL_PATH}
         chain={chain}
         showCarve={showCarve}
         carveNodes={carveNodes}

package/src/components/editor/propertyPanelFxSectionTypes.ts

@@ -6,8 +6,27 @@
 import type { HfAudioFxChain } from "@hyperframes/core/audio-fx";
 import type { HfAudioNameKind, HfCarveSettings } from "@hyperframes/core/audio-carve";
 import type { AudioTrackOption } from "./propertyPanelFxCarveModule.js";
+import type { AudioFxSignalPath } from "./audioFxSignalPath.js";
 
 export interface FxSectionProps {
+  /**
+   * An automation lane asked to be shown: its `fx.<node>.<param>` / `volume`
+   * target. The section opens whichever surface owns that parameter — a node
+   * row, an EQ module, a preset run, or the carve — and scrolls to it.
+   */
+  revealTarget?: string | null;
+  /**
+   * The reveal request's nonce. Consumption keys on THIS, not on
+   * `revealTarget`: clicking a lane selects the clip first, which remounts this
+   * section, so a `!==` against the previous VALUE initialises to the
+   * already-set request and never fires — and a second click on the same lane
+   * would be byte-identical and inert. Same reason `PropertyPanelFlat` keys its
+   * own consumption on the nonce.
+   */
+  revealNonce?: number | null;
+  /** What the rack's `In`/`Out` lines name — see `audioFxSignalPath`. Absent
+   *  means an ungrouped clip, which is what those lines said before groups. */
+  signalPath?: AudioFxSignalPath;
   chain: HfAudioFxChain;
   /** Targets this track already automates, as `fx.<nodeId>.<param>` strings. */
   automatedTargets?: ReadonlySet<string>;

package/src/components/editor/useAudioFxRevealSection.ts

@@ -0,0 +1,64 @@
+/**
+ * Opening the Audio FX section for a lane's reveal request.
+ *
+ * Split out of `PropertyPanelFlat.tsx` to keep it under the studio's 600-line
+ * cap. All three of the request's hazards live here rather than being restated
+ * at the call site: it must be current, it is consumed by NONCE, and it is
+ * retired when the panel goes away.
+ */
+
+import { useEffect, useState } from "react";
+import { usePlayerStore } from "../../player";
+import { isRevealedAudioFxRequestCurrent } from "../../player/store/keyframeSlice";
+
+export interface AudioFxRevealSectionInput {
+  /** The element the panel is showing, or null. */
+  elementId: string | null | undefined;
+  /** False when the panel does not render an Audio FX section at all. */
+  hasAudioFxSection: boolean;
+}
+
+/**
+ * The nonce this panel should act on, or null.
+ *
+ * Consumption is keyed on the NONCE, not the request object: clicking a lane
+ * selects the clip first, which REMOUNTS this panel, so a `!==` against the
+ * previous value would initialise to the already-set request and never fire.
+ * The nonce also makes a second click on the same lane a new request.
+ */
+export function useAudioFxRevealSection(input: AudioFxRevealSectionInput): {
+  /** Non-null exactly once per request: open the section on this commit. */
+  revealNonce: number | null;
+  consume: (nonce: number) => void;
+} {
+  const revealedAudioFxTarget = usePlayerStore((s) => s.revealedAudioFxTarget);
+  const timelineProjectId = usePlayerStore((s) => s.timelineProjectId);
+  const timelineSessionEpoch = usePlayerStore((s) => s.timelineSessionEpoch);
+  const clearRevealedAudioFxTarget = usePlayerStore((s) => s.clearRevealedAudioFxTarget);
+  const [consumed, setConsumed] = useState<number | null>(null);
+
+  // Retire the request once this panel is gone. Consumption is nonce-guarded so
+  // a stale request was already harmless — but it sat in the store until the
+  // next click, and a request nobody will ever consume is state every reader
+  // then has to reason about.
+  useEffect(() => {
+    if (consumed === null) return;
+    return () => clearRevealedAudioFxTarget(consumed);
+  }, [consumed, clearRevealedAudioFxTarget]);
+
+  const forThisPanel =
+    revealedAudioFxTarget !== null &&
+    revealedAudioFxTarget.elementKey === input.elementId &&
+    isRevealedAudioFxRequestCurrent(revealedAudioFxTarget, {
+      timelineProjectId,
+      timelineSessionEpoch,
+    }) &&
+    input.hasAudioFxSection
+      ? revealedAudioFxTarget.nonce
+      : null;
+
+  return {
+    revealNonce: forThisPanel !== null && forThisPanel !== consumed ? forThisPanel : null,
+    consume: setConsumed,
+  };
+}

package/src/components/editor/useAuditionTransport.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { auditionStart } from "./useAuditionTransport";
+
+const SPANS = [
+  { start: 2, duration: 7 },
+  { start: 18, duration: 7 },
+];
+
+describe("auditionStart", () => {
+  // Nothing to aim at — a caller with no spans keeps the old behaviour: play
+  // from wherever the author left the playhead.
+  it("stays put when there are no spans", () => {
+    expect(auditionStart(undefined, 0)).toBeNull();
+    expect(auditionStart([], 0)).toBeNull();
+  });
+
+  // Already inside the clip: moving the playhead here would be the UI taking a
+  // decision it was not asked for, and it would cost the author their place for
+  // no gain.
+  it("stays put when the playhead is already inside a span", () => {
+    expect(auditionStart(SPANS, 2)).toBeNull();
+    expect(auditionStart(SPANS, 8.9)).toBeNull();
+  });
+
+  // The bug this exists for: hovering a preset at 0:00 on a group whose members
+  // start at 0:02 played silence under the effect.
+  it("jumps to the next span when the playhead is before or between them", () => {
+    expect(auditionStart(SPANS, 0)).toBe(2);
+    expect(auditionStart(SPANS, 9)).toBe(18);
+  });
+
+  // Past everything, wrap to the first rather than play out the tail in silence.
+  it("wraps to the first span when the playhead is past them all", () => {
+    expect(auditionStart(SPANS, 40)).toBe(2);
+  });
+});

package/src/components/editor/useAuditionTransport.ts

@@ -0,0 +1,78 @@
+/**
+ * Start playback for an audition, and put the playhead back on the way out.
+ *
+ * An audition writes the hovered 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 affordance only worked mid-playback. Extracted from
+ * `useFxLevelling`, where the property panel's rack owned it privately, because
+ * the timeline's FX popover must render the preset shelf "exactly as FxSection
+ * renders it — same props" (runbook C1 §2) and was passing no transport at all.
+ */
+
+import { useRef } from "react";
+// The store's own module, not the `player` barrel: the barrel pulls the whole
+// timeline in, and the timeline's FX button imports this hook — a cycle.
+import { usePlayerStore } from "../../player/store/playerStore";
+
+/** A clip the audition is meant to be heard through. */
+export interface AuditionSpan {
+  start: number;
+  duration: number;
+}
+
+/**
+ * Where to start playing so the audition is actually audible, or null to stay.
+ *
+ * Playing "from the playhead" only works when the thing being auditioned is
+ * sounding there. A group whose members start at 0:02, hovered with the
+ * playhead at 0:00, plays the rest of the mix unchanged — the transport runs,
+ * the chain is in the graph, and the author hears nothing of the preset. So:
+ * inside a span, stay; otherwise jump to the next one, wrapping to the first
+ * when the playhead is past them all.
+ *
+ * Shared rather than the popover's own, which is where it went wrong the first
+ * time: the property panel's rack has the identical hole, and giving the two
+ * surfaces different audition behaviour is exactly what runbook C1 §2 forbids
+ * when it says the shelf renders "exactly as FxSection renders it".
+ */
+export function auditionStart(
+  spans: readonly AuditionSpan[] | undefined,
+  at: number,
+): number | null {
+  if (!spans || spans.length === 0) return null;
+  if (spans.some((span) => at >= span.start && at < span.start + span.duration)) return null;
+  const starts = spans.map((span) => span.start).sort((a, b) => a - b);
+  return starts.find((start) => start > at) ?? starts[0] ?? null;
+}
+
+export function useAuditionTransport(): (on: boolean, spans?: readonly AuditionSpan[]) => void {
+  /**
+   * 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);
+
+  /**
+   * 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 UI taking a decision that was not offered to it.
+   */
+  return (on: boolean, spans?: readonly AuditionSpan[]): void => {
+    const store = usePlayerStore.getState();
+    if (on) {
+      if (store.isPlaying || auditionReturn.current !== null) return;
+      // Recorded BEFORE the seek, so leaving returns the author to where they
+      // actually were rather than to the clip this jumped to.
+      auditionReturn.current = store.currentTime;
+      const from = auditionStart(spans, store.currentTime);
+      if (from !== null) store.requestSeek(from);
+      store.requestPlayback(true);
+      return;
+    }
+    const returnTo = auditionReturn.current;
+    if (returnTo === null) return;
+    auditionReturn.current = null;
+    store.requestPlayback(false, returnTo);
+  };
+}

package/src/components/editor/useFxAudition.ts

@@ -52,6 +52,17 @@ export function useFxAudition(
     [chain, onChainPreview, onAuditionTransport],
   );
 
+  /**
+   * The chain as the DOCUMENT has it, ignoring whatever is being auditioned.
+   *
+   * An audition writes through the preview channel, and the `chain` prop is
+   * read back from that same live attribute — so mid-hover it is the hovered
+   * preset, not the stored chain. Applying on top of it stacked the auditioned
+   * preset into the saved chain: hover a reverb, click a different preset, and
+   * both were persisted, which is heard as the effect running twice.
+   */
+  const storedChain = useCallback(() => auditionBase.current ?? chain, [chain]);
+
   /**
    * Drop whatever is being auditioned WITHOUT reverting the preview, for a
    * caller that is about to mutate the real chain anyway — reverting first
@@ -91,5 +102,5 @@ export function useFxAudition(
     [],
   );
 
-  return { audition, clearAudition };
+  return { audition, clearAudition, storedChain };
 }

package/src/components/editor/useFxCarveGrouping.test.ts

@@ -0,0 +1,118 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from "vitest";
+import { carveBedRoles, carverAgainst, collectCarveCandidates } from "./useFxCarveGrouping";
+
+function previewDoc(html: string): Document {
+  const doc = document.implementation.createHTMLDocument("preview");
+  doc.body.innerHTML = html;
+  return doc;
+}
+
+/** What the panel would offer as sources for `bedId`, the way useFxCarve asks. */
+function candidatesFor(doc: Document, bedId: string) {
+  const others = Array.from(doc.querySelectorAll<HTMLAudioElement>("audio[id]")).filter(
+    (a) => a.id !== bedId,
+  );
+  return collectCarveCandidates(doc, others, () => true, bedId).map((c) => c.id);
+}
+
+const GROUPED_VOICES = `
+  <hf-audio-group id="voiceover" data-label="Voiceover"></hf-audio-group>
+  <audio id="vo-1" data-audio-group="voiceover"></audio>
+  <audio id="vo-2" data-audio-group="voiceover"></audio>
+  <audio id="music-bed"></audio>
+`;
+
+describe("collectCarveCandidates", () => {
+  // The observed bug: selecting vo-2 offered "Voiceover (2)" — the group vo-2 is
+  // itself a member of. The caller filters out the bed element, but vo-1 survives
+  // that filter and rolls up into exactly that group. Being the only candidate, it
+  // was then applied without the author asking: a member ducking the bus it feeds.
+  it("never offers a member the group it belongs to", () => {
+    expect(candidatesFor(previewDoc(GROUPED_VOICES), "vo-2")).toEqual(["music-bed"]);
+  });
+
+  // And the mirror: a group bed's own id matches no <audio> id, so nothing
+  // excluded it. Its members rolled up and handed the group back to itself.
+  it("never offers a group itself", () => {
+    const doc = previewDoc(GROUPED_VOICES);
+    expect(candidatesFor(doc, "voiceover")).toEqual(["music-bed"]);
+  });
+
+  it("still offers a group the bed has nothing to do with", () => {
+    const doc = previewDoc(`
+      ${GROUPED_VOICES}
+      <hf-audio-group id="sfx" data-label="SFX"></hf-audio-group>
+      <audio id="sfx-click" data-audio-group="sfx"></audio>
+    `);
+    expect(candidatesFor(doc, "music-bed")).toEqual(["voiceover", "sfx"]);
+  });
+
+  it("leaves an ungrouped bed's candidates alone", () => {
+    const doc = previewDoc(`<audio id="music-bed"></audio><audio id="vo-1"></audio>`);
+    expect(candidatesFor(doc, "music-bed")).toEqual(["vo-1"]);
+  });
+});
+
+describe("carverAgainst", () => {
+  // The far-end guard has to see through a GROUP source. A plural carve names a
+  // group — that is what the lint rule pushes authors toward — so matching raw
+  // ids never found the member, the carve module was offered on a voice already
+  // being ducked against, and switching it on wrote a reciprocal carve.
+  it("finds the bed carving a voice through its group", () => {
+    const doc = previewDoc(`
+      ${GROUPED_VOICES}
+      <audio id="bed" data-fx-carve='{"enabled":true,"sources":["voiceover"],"strength":0.3}'></audio>
+    `);
+    expect(carverAgainst(doc, "vo-1")).toBe("bed");
+    expect(carverAgainst(doc, "vo-2")).toBe("bed");
+  });
+
+  it("still finds a carve that names the clip directly", () => {
+    const doc = previewDoc(`
+      ${GROUPED_VOICES}
+      <audio id="bed" data-fx-carve='{"enabled":true,"sources":["vo-1"],"strength":0.3}'></audio>
+    `);
+    expect(carverAgainst(doc, "vo-1")).toBe("bed");
+    expect(carverAgainst(doc, "vo-2")).toBeNull();
+  });
+
+  it("is null for a track nobody carves against", () => {
+    const doc = previewDoc(GROUPED_VOICES);
+    expect(carverAgainst(doc, "vo-1")).toBeNull();
+  });
+});
+
+describe("carveBedRoles", () => {
+  const roles = (html: string, id: string) => {
+    const doc = previewDoc(html);
+    return carveBedRoles(id, doc.getElementById(id));
+  };
+
+  // The observed bug: the bus labelled "Music bed" classified as music, so it
+  // auto-carved against the same voiceover its own member clip had already
+  // carved against — the bed ran through both chains. A bus is never a bed, and
+  // `autoBed` matters as much as `couldBeBed`: that is the half that wrote one
+  // without being asked.
+  it("never makes a bus a bed, however it is labelled", () => {
+    expect(
+      roles(`<hf-audio-group id="music" data-label="Music bed"></hf-audio-group>`, "music"),
+    ).toEqual({ couldBeBed: false, autoBed: false });
+    expect(
+      roles(`<hf-audio-group id="sfx" data-label="Sound FX"></hf-audio-group>`, "sfx"),
+    ).toEqual({ couldBeBed: false, autoBed: false });
+  });
+
+  it("still reads a clip's label, id and src", () => {
+    expect(roles(`<audio id="a1" data-label="Music bed"></audio>`, "a1")).toEqual({
+      couldBeBed: true,
+      autoBed: true,
+    });
+    // A name that says nothing may be offered the control but never carves itself.
+    expect(roles(`<audio id="a1"></audio>`, "a1")).toEqual({ couldBeBed: true, autoBed: false });
+    expect(roles(`<audio id="vo-2"></audio>`, "vo-2")).toEqual({
+      couldBeBed: false,
+      autoBed: false,
+    });
+  });
+});

package/src/components/editor/useFxCarveGrouping.ts

@@ -7,8 +7,19 @@
  * `propertyPanelAudioFxGroup.tsx`.
  */
 
-import { classifyAudioName, type HfCarveSettings } from "@hyperframes/core/audio-carve";
-import { resolveAudioGroups } from "@hyperframes/core/audio-groups";
+import {
+  classifyAudioName,
+  HF_AUDIO_CARVE_ATTR,
+  normalizeCarveSettings,
+  couldBeCarveBed,
+  isNamedCarveBed,
+  type HfCarveSettings,
+} from "@hyperframes/core/audio-carve";
+import {
+  HF_AUDIO_GROUP_TAG,
+  resolveAudioGroups,
+  resolveCarveSourceIds,
+} from "@hyperframes/core/audio-groups";
 
 /**
  * An id for a new voiceover group, de-duped against every id already in the
@@ -30,6 +41,12 @@ export function isPromiseLike<T>(value: T | Promise<T>): value is Promise<T> {
   return typeof (value as { then?: unknown })?.then === "function";
 }
 
+/**
+ * "The auto-group failed, do not persist this carve" — distinct from a
+ * legitimate `null`, which means the carve was deliberately cleared.
+ */
+export const CARVE_ABORTED = Symbol("carve-aborted");
+
 /**
  * Plural voiceover carve, always against a group — normative, not a
  * suggestion (groups doc §1.6). Picking a second ungrouped voice clip mints a
@@ -71,8 +88,16 @@ export function resolveNextCarveSettings(
   nextRaw: HfCarveSettings | null,
   doc: Document | undefined,
   assignGroup: ((clipIds: readonly string[], groupId: string) => Promise<void>) | undefined,
-): HfCarveSettings | Promise<HfCarveSettings> | null {
-  return nextRaw && doc ? withAutoGroupedSources(doc, nextRaw, assignGroup) : nextRaw;
+): HfCarveSettings | Promise<HfCarveSettings | typeof CARVE_ABORTED> | null {
+  const resolved = nextRaw && doc ? withAutoGroupedSources(doc, nextRaw, assignGroup) : nextRaw;
+  // A failed auto-group resolves to the sentinel rather than rejecting: the
+  // write has already toasted, and the caller's job is simply not to persist a
+  // carve whose `sources` name a group that was never written — which reads, at
+  // playback, as a carve that silently stops ducking. Caught here rather than
+  // in the caller so the synchronous branch above stays synchronous.
+  return isPromiseLike(resolved)
+    ? resolved.catch((): typeof CARVE_ABORTED => CARVE_ABORTED)
+    : resolved;
 }
 
 export interface CarveCandidate {
@@ -87,18 +112,38 @@ export interface CarveCandidate {
  * the whole timeline is relevant even if each of its segments only overlaps
  * part of the bed). Grouped members never appear individually.
  */
+/**
+ * The ids a carve may never name, for a bed of this id.
+ *
+ * A carve names what the bed ducks UNDER, so the bed can never be on that
+ * list — directly or through the bus it plays into. The caller filters the bed
+ * element out of `others`, but that only removes the bed itself: its siblings
+ * survive and roll up into the very group the bed is a member of, which came
+ * back as a candidate and, being the only one, was applied unprompted. And a
+ * group bed's own id never matches any <audio> id at all, so nothing stopped a
+ * group carving against itself.
+ */
+function excludedFor(groupByMember: Map<string, { id: string }>, bedId?: string): Set<string> {
+  const selfGroupId = bedId ? groupByMember.get(bedId)?.id : undefined;
+  return new Set([bedId, selfGroupId].filter((id): id is string => !!id));
+}
+
 export function collectCarveCandidates(
   doc: Document,
   others: readonly HTMLAudioElement[],
   overlapsBed: (a: Element) => boolean,
+  /** The bed's own id, so neither it nor the group it belongs to is offered. */
+  bedId?: string,
 ): CarveCandidate[] {
   const groupByMember = new Map(
     resolveAudioGroups(doc).flatMap((group) => group.memberIds.map((id) => [id, group] as const)),
   );
+  const excluded = excludedFor(groupByMember, bedId);
   const offeredGroupIds = new Set<string>();
   const described: CarveCandidate[] = [];
   for (const a of others) {
     const group = groupByMember.get(a.id);
+    if (excluded.has(a.id) || (group && excluded.has(group.id))) continue;
     if (!group) {
       if (overlapsBed(a)) {
         described.push({
@@ -130,3 +175,93 @@ export function collectCarveCandidates(
   }
   return described;
 }
+
+/**
+ * The two near-end questions about a track, asked of its name.
+ *
+ * `couldBeBed` — may a carve be written onto this at all? A carve makes room in
+ * a bed for a voice, so a voice track is the one thing that can never be the
+ * bed. The far-end rule (`couldBeCarveSource` — music and sfx are out) has
+ * existed since it was written and had no caller; this is the half nothing
+ * asked, and without it a narration clip was offered the control and, finding
+ * exactly one candidate, had a carve applied against the group it belonged to.
+ *
+ * `autoBed` — may one be applied WITHOUT the author asking? Stricter. Showing
+ * the module on a track named `a1` is a suggestion; writing `data-fx-carve`
+ * onto it is a decision, and a decision taken off a name that said nothing is
+ * how a carve turns up that nobody remembers configuring. The same split the
+ * source side already makes between what the picker may show (`sourceOptions`)
+ * and what it may choose unprompted (`autoSourceIds`).
+ *
+ * Reads the element's `data-label` as well as its id and `src`, because a clip's
+ * display name is a hint its filename may not carry. A BUS is excluded outright
+ * — see the first branch.
+ */
+export function carveBedRoles(
+  id: string | null | undefined,
+  node: Element | null | undefined,
+): { couldBeBed: boolean; autoBed: boolean } {
+  // A BUS is never a bed, whatever it is called. Its rack reaches `useFxCarve`
+  // too, and reading `data-label` — which is what lets a group be classified at
+  // all — made a bus labelled "Music bed" read as music: it then auto-carved
+  // against the same voice its own member clip had already auto-carved against,
+  // and the bed ran through both sets of filters. Nothing caught that, because
+  // the only guard (`carverAgainst`) asks "is somebody naming ME as a source",
+  // never "is my own bus, or my own member, already carved".
+  //
+  // A bus could not do the whole job anyway: the level half of the carve reads
+  // the bed's own `src` to measure how far over the voice it sits, and a bus has
+  // no `src` — so a bus carve was always the spectral half alone, filters with
+  // no level match. `data-fx-carve` is a clip attribute; the skill has said so
+  // ("A carve stays on the clip") since the bus was documented.
+  //
+  // Not `couldBeBed: false` alone: that leaves `autoBed` free to fire from a
+  // name, which is the half that wrote these unasked.
+  if (node?.tagName?.toLowerCase() === HF_AUDIO_GROUP_TAG) {
+    return { couldBeBed: false, autoBed: false };
+  }
+  const parts = [id, node?.getAttribute("src"), node?.getAttribute("data-label")];
+  return { couldBeBed: couldBeCarveBed(...parts), autoBed: isNamedCarveBed(...parts) };
+}
+
+/**
+ * Whether some element's own carve attribute names `targetId` as a source.
+ *
+ * Sources are EXPANDED first. A plural carve now names a group rather than a
+ * clip list — that is what `audio_carve_ungrouped_sources` exists to push
+ * authors toward — so a raw `.includes(targetId)` never matched a member again,
+ * and the far-end guard this feeds was silently defeated by the very shape the
+ * lint rule asks for. The result: the carve module was offered on a voice clip
+ * a bed is already ducking against, and switching it on wrote a reciprocal
+ * carve — each side measuring audio the other is already attenuating.
+ */
+function carvesAgainst(doc: Document, other: HTMLElement, targetId: string): boolean {
+  try {
+    const raw = other.getAttribute(HF_AUDIO_CARVE_ATTR);
+    if (!raw) return false;
+    const sources = normalizeCarveSettings(JSON.parse(raw)).sources;
+    return resolveCarveSourceIds(doc, sources).includes(targetId);
+  } catch {
+    // An unreadable carve on some other element says nothing about this one.
+    return false;
+  }
+}
+
+/**
+ * Is some other track carving against this one, and which?
+ *
+ * A carve is a relationship — a bed is carved against a voice — and the voice is
+ * the far end of it. Offering the same control there offers to carve a track
+ * against itself by proxy, and switching it on left a setting with no source it
+ * could legally name. Read off the other elements' own carve attributes, because
+ * that is where the relationship is recorded.
+ */
+export function carverAgainst(
+  doc: Document | undefined,
+  id: string | null | undefined,
+): string | null {
+  if (!doc || !id) return null;
+  const others = Array.from(doc.querySelectorAll<HTMLElement>(`[${HF_AUDIO_CARVE_ATTR}]`));
+  const carver = others.find((other) => other.id !== id && carvesAgainst(doc, other, id));
+  return carver ? carver.id || "another track" : null;
+}