fix(studio): unify audio IDs and group state (#3448)

* fix(core): harden audio FX and group identity

* fix(core): address audio group review feedback

* fix(core): align preview transport with grouped audio

* test(core): pin audio group gain ceiling

* fix(core): preserve solo bridge through stack

* fix(engine): harden grouped audio rendering

* docs(engine): explain grouped mix fallback invariant

* test(engine): allow grouped mixes to finish on Windows

* feat(lint): validate audio group membership and timing

* test(lint): pin audio group membership guards

* fix(studio): unify audio IDs and group state

Author: vanceingalls

packages/studio/src/player/lib/automationStoreSync.test.ts

@@ -80,4 +80,30 @@ describe("syncStoredAutomationFromPreview", () => {
     syncStoredAutomationFromPreview(null);
     expect(usePlayerStore.getState().elements[0]?.automation).toBe(TWO_POINTS);
   });
+  // The reported symptom: automate a parameter on a GROUP from the FX rack and
+  // the group's row shows no automation. The rack is not group-aware — it
+  // writes the attribute on the group node through the ordinary element path —
+  // and the timeline reads a group's lanes from the mirrors its MEMBERS carry,
+  // which that path used to leave untouched.
+  it("re-reads what the group carries onto every member that belongs to it", () => {
+    const chain = '{"version":1,"nodes":[{"type":"gain","id":"n1","params":{"gain":0}}]}';
+    const groupAutomation =
+      '{"version":1,"lanes":[{"target":"fx.n1.gain","points":[{"t":0,"v":0}]}]}';
+    const doc = document.implementation.createHTMLDocument("preview");
+    const group = doc.createElement("hf-audio-group");
+    group.id = "voiceover";
+    group.setAttribute("data-fx-chain", chain);
+    group.setAttribute("data-automation", groupAutomation);
+    const audio = doc.createElement("audio");
+    audio.id = "bgm";
+    audio.setAttribute("data-audio-group", "voiceover");
+    doc.body.append(group, audio);
+
+    usePlayerStore.setState({ elements: [el({ audioGroup: "voiceover" })] });
+    syncStoredAutomationFromPreview(doc);
+
+    const stored = usePlayerStore.getState().elements[0];
+    expect(stored?.audioGroupAutomation).toBe(groupAutomation);
+    expect(stored?.audioGroupFxChain).toBe(chain);
+  });
 });

packages/studio/src/player/lib/automationStoreSync.ts

@@ -16,6 +16,7 @@
 import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";
 import { HF_AUDIO_FX_ATTR } from "@hyperframes/core/audio-fx";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { groupInfoFor } from "./timelineGroupInfo";
 
 /** The preview node an element stands for, by dom id and then by `data-hf-id`. */
 function previewNodeFor(doc: Document, element: TimelineElement): Element | null {
@@ -38,18 +39,41 @@ function previewNodeFor(doc: Document, element: TimelineElement): Element | null
  * Reads rather than being told: an undo restores whole files, so the attribute it
  * reverted is only known by looking.
  */
+/**
+ * What an element's four synced fields SHOULD read, given the preview.
+ *
+ * Its own two come off its node; the other two are its copy of what its group
+ * carries. The timeline derives a group's lanes and chain from these mirrors,
+ * never from the group element — and the FX rack is not group-aware: selecting
+ * a group and automating one of its parameters writes `data-automation` on the
+ * group node through the ordinary element path, which used to refresh an
+ * element's own two fields and nothing else. So the group's row went on reading
+ * the value it was born with, and its `∿` never appeared.
+ */
+function syncedFields(doc: Document, element: TimelineElement, node: Element) {
+  const group = element.audioGroup ? groupInfoFor(doc, element.audioGroup) : null;
+  return {
+    automation: node.getAttribute(HF_AUDIO_AUTOMATION_ATTR) ?? undefined,
+    fxChain: node.getAttribute(HF_AUDIO_FX_ATTR) ?? undefined,
+    audioGroupAutomation: group?.automation,
+    audioGroupFxChain: group?.fxChain,
+  };
+}
+
 export function syncStoredAutomationFromPreview(doc: Document | null | undefined): void {
   if (!doc) return;
   usePlayerStore.setState((state) => {
     let changed = false;
     const elements = state.elements.map((element) => {
       const node = previewNodeFor(doc, element);
       if (!node) return element;
-      const automation = node.getAttribute(HF_AUDIO_AUTOMATION_ATTR) ?? undefined;
-      const fxChain = node.getAttribute(HF_AUDIO_FX_ATTR) ?? undefined;
-      if (automation === element.automation && fxChain === element.fxChain) return element;
+      const fields = syncedFields(doc, element, node);
+      // Same array back when nothing moved: `elements` keys memos all over the
+      // timeline, and a fresh object per sync would re-render every one.
+      const keys = Object.keys(fields) as (keyof typeof fields)[];
+      if (keys.every((key) => fields[key] === element[key])) return element;
       changed = true;
-      return { ...element, automation, fxChain };
+      return { ...element, ...fields };
     });
     return changed ? { elements } : {};
   });

packages/studio/src/player/lib/runtimeAudioId.test.ts

@@ -0,0 +1,58 @@
+// @vitest-environment jsdom
+
+/**
+ * The studio → runtime boundary, which nothing else crosses.
+ *
+ * Studio addresses rows by `buildTimelineElementKey`'s composite
+ * `<sourceFile>#<domId>`; every audio predicate in `@hyperframes/core` keys off
+ * the live document instead. Both halves have their own passing tests — one
+ * with composite keys, one with bare ids — and the mismatch between them lived
+ * in the gap. These parse a real document, take the ids the way the UI does,
+ * and hand them to the real core predicates.
+ */
+
+import { describe, expect, it } from "vitest";
+import { resolveAudioGroups } from "@hyperframes/core/audio-groups";
+import { parseTimelineFromDOM } from "./timelineDOM";
+import { runtimeAudioId } from "./timelineElementHelpers";
+
+function docWith(body: string): Document {
+  const doc = document.implementation.createHTMLDocument("comp");
+  doc.body.innerHTML = body;
+  return doc;
+}
+
+const COMPOSITION = `
+  <div data-composition-id="root" data-duration="30"></div>
+  <audio id="voice-1" data-start="0" data-duration="10" data-audio-group="voiceover"></audio>
+  <audio id="voice-2" data-start="10" data-duration="10" data-audio-group="voiceover"></audio>
+  <audio id="music-bed" data-start="0" data-duration="30"></audio>
+  <hf-audio-group id="voiceover"></hf-audio-group>
+`;
+
+describe("group membership ids cross into the runtime", () => {
+  it("the ids the timeline hands to onGroupClips are the ids resolveAudioGroups reads back", () => {
+    const doc = docWith(COMPOSITION);
+    const trackElements = parseTimelineFromDOM(doc, 30).filter(
+      (el) => el.tag.toLowerCase() === "audio",
+    );
+    const clipIds = trackElements.map(runtimeAudioId).filter((id): id is string => id !== null);
+    expect(clipIds).toEqual(["voice-1", "voice-2", "music-bed"]);
+
+    // Same space membership is read back in — a composite key here produces a
+    // group whose members nothing can find.
+    const memberIds = resolveAudioGroups(doc).flatMap((g) => g.memberIds);
+    expect(memberIds.every((id) => doc.getElementById(id) !== null)).toBe(true);
+    for (const id of memberIds) expect(clipIds).toContain(id);
+  });
+
+  it("an element with no DOM id is not groupable", () => {
+    const doc = docWith(`
+      <div data-composition-id="root" data-duration="10"></div>
+      <audio data-start="0" data-duration="5"></audio>
+    `);
+    const [clip] = parseTimelineFromDOM(doc, 10);
+    expect(clip).toBeDefined();
+    expect(runtimeAudioId(clip)).toBeNull();
+  });
+});

packages/studio/src/player/lib/timelineDOM.test.ts

@@ -6,6 +6,8 @@ import {
   createImplicitTimelineLayersFromDOM,
   mergeTimelineElementsPreservingDowngrades,
 } from "./timelineDOM";
+import { isTimelineIgnoredElement } from "./timelineElementHelpers";
+import { invalidateGroupInfoCache } from "./timelineGroupInfo";
 import type { TimelineElement } from "../store/playerStore";
 
 function el(id: string, extra: Partial<TimelineElement> = {}): TimelineElement {
@@ -110,6 +112,92 @@ describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
   });
 });
 
+describe("group info cache", () => {
+  const parseMember = (doc: Document) =>
+    createTimelineElementFromManifestClip({
+      clip: {
+        id: "voice-1",
+        label: "voice-1",
+        kind: "element",
+        tagName: "audio",
+        start: 0,
+        duration: 5,
+        track: 0,
+        compositionId: null,
+        parentCompositionId: null,
+        compositionSrc: null,
+        assetUrl: null,
+      },
+      fallbackIndex: 0,
+      doc,
+      hostEl: doc.getElementById("voice-1"),
+    });
+
+  // Group edits are applied as LIVE patches so the preview iframe never
+  // reloads, which means the document identity this cache is keyed on never
+  // changes either. Without an explicit drop, a muted group could never be
+  // unmuted: the header kept reading the cached `hidden: false` and re-wrote
+  // `data-hidden` forever.
+  it("re-reads group state after an invalidation", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root">
+        <audio id="voice-1" data-start="0" data-duration="5" data-audio-group="voiceover"></audio>
+        <hf-audio-group id="voiceover" data-label="Voices"></hf-audio-group>
+      </div>
+    `);
+
+    expect(parseMember(doc).audioGroupHidden).toBe(false);
+
+    doc.getElementById("voiceover")?.setAttribute("data-hidden", "");
+    expect(parseMember(doc).audioGroupHidden).toBe(false); // still the cached scan
+
+    invalidateGroupInfoCache(doc);
+    expect(parseMember(doc).audioGroupHidden).toBe(true);
+
+    doc.getElementById("voiceover")?.removeAttribute("data-hidden");
+    invalidateGroupInfoCache(doc);
+    expect(parseMember(doc).audioGroupHidden).toBe(false);
+  });
+
+  // The explicit invalidator is a convenience, not the contract. A cache whose
+  // only defence is "every writer must remember to call this" rots the first
+  // time a writer does not know it exists — which is precisely what happened
+  // with the FX rack, whose group writes go through the DOM editor rather than
+  // the timeline's own writers. The scan carries the DOM revision it was taken
+  // at, so a forgotten call costs a re-scan rather than a wrong answer.
+  it("expires itself on a group edit nobody announced", async () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root">
+        <audio id="voice-1" data-start="0" data-duration="5" data-audio-group="voiceover"></audio>
+        <hf-audio-group id="voiceover" data-label="Voices"></hf-audio-group>
+      </div>
+    `);
+
+    expect(parseMember(doc).audioGroupHidden).toBe(false);
+
+    // No invalidateGroupInfoCache call anywhere in this test.
+    doc.getElementById("voiceover")?.setAttribute("data-hidden", "");
+    await new Promise((resolve) => setTimeout(resolve, 0)); // observer microtask
+
+    expect(parseMember(doc).audioGroupHidden).toBe(true);
+  });
+
+  it("notices a member joining the group, not just an attribute edit", async () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root">
+        <audio id="voice-1" data-start="0" data-duration="5" data-audio-group="voiceover"></audio>
+        <hf-audio-group id="voiceover" data-label="Voices"></hf-audio-group>
+      </div>
+    `);
+    expect(parseMember(doc).audioGroupLabel).toBe("Voices");
+
+    doc.getElementById("voiceover")?.setAttribute("data-label", "Narration");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(parseMember(doc).audioGroupLabel).toBe("Narration");
+  });
+});
+
 describe("parseTimelineFromDOM — canonical playback rate", () => {
   it.each([
     ["10", 5],
@@ -207,6 +295,33 @@ describe("createTimelineElementFromManifestClip — source-scoped selector ident
   });
 });
 
+// Caught by looking at the studio, not by reading: a grouped composition drew
+// "Voiceover • 0.0s – 12.0s" as a full-duration clip row directly above its own
+// group header. `<hf-audio-group>` is a mixer bus — no timing, drawn as a group
+// row by the group derivation — but it is still a body child with an id, so the
+// implicit-layer fallback happily gave it a track. Draggable and trimmable, and
+// writing timing onto a bus means nothing.
+describe("<hf-audio-group> is not a timeline layer", () => {
+  it("gets no implicit row of its own", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root">
+        <audio id="voice-1" data-start="0" data-duration="6" data-audio-group="voiceover"></audio>
+        <hf-audio-group id="voiceover" data-label="Voiceover"></hf-audio-group>
+      </div>
+    `);
+
+    const implicit = createImplicitTimelineLayersFromDOM(doc, 12, []);
+
+    expect(implicit.map((el) => el.domId)).not.toContain("voiceover");
+  });
+
+  it("is excluded by the shared ignore predicate", () => {
+    const doc = makeDoc(`<hf-audio-group id="vo"></hf-audio-group><div id="panel"></div>`);
+    expect(isTimelineIgnoredElement(doc.getElementById("vo") as Element)).toBe(true);
+    expect(isTimelineIgnoredElement(doc.getElementById("panel") as Element)).toBe(false);
+  });
+});
+
 describe("createImplicitTimelineLayersFromDOM — hfId from data-hf-id", () => {
   it("uses the runtime root paint scope for implicit siblings of manifest clips", () => {
     const doc = makeDoc(`

packages/studio/src/player/lib/timelineDOM.ts

@@ -12,7 +12,7 @@ import type { TimelineElement } from "../store/playerStore";
 import type { ClipManifestClip } from "./playbackTypes";
 import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";
 import { readClipTiming } from "@hyperframes/core/composition-contract";
-import { resolveAudioGroups } from "@hyperframes/core/audio-groups";
+import { groupInfoFor } from "./timelineGroupInfo";
 import {
   resolveMediaElement,
   applyMediaMetadataFromElement,
@@ -68,37 +68,6 @@ function resolveClipTag(clip: ClipManifestClip): string {
   return clip.tagName || clip.kind || "div";
 }
 
-// One `<hf-audio-group>` scan per document, not per clip — resolveAudioGroups
-// walks the whole tree, and a parse touches every clip in it.
-interface GroupInfo {
-  label: string;
-  volume: number;
-  hidden: boolean;
-  fxChain?: string;
-}
-
-const groupInfoCache = new WeakMap<Document, Map<string, GroupInfo>>();
-
-function groupInfoFor(doc: Document | null | undefined, groupId: string): GroupInfo {
-  if (!doc) return { label: groupId, volume: 1, hidden: false };
-  let info = groupInfoCache.get(doc);
-  if (!info) {
-    info = new Map(
-      resolveAudioGroups(doc).map((group) => [
-        group.id,
-        {
-          label: group.label,
-          volume: group.volume,
-          hidden: group.hidden,
-          ...(group.fxChain ? { fxChain: group.fxChain } : {}),
-        },
-      ]),
-    );
-    groupInfoCache.set(doc, info);
-  }
-  return info.get(groupId) ?? { label: groupId, volume: 1, hidden: false };
-}
-
 // fallow-ignore-next-line complexity
 export function createTimelineElementFromManifestClip(params: {
   clip: ClipManifestClip;
@@ -178,6 +147,7 @@ export function createTimelineElementFromManifestClip(params: {
       entry.audioGroupVolume = info.volume;
       entry.audioGroupHidden = info.hidden;
       if (info.fxChain) entry.audioGroupFxChain = info.fxChain;
+      if (info.automation) entry.audioGroupAutomation = info.automation;
     }
     const fxChain = hostEl.getAttribute("data-fx-chain");
     if (fxChain) entry.fxChain = fxChain;
@@ -405,6 +375,7 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
       entry.audioGroupVolume = domGroupInfo.volume;
       entry.audioGroupHidden = domGroupInfo.hidden;
       if (domGroupInfo.fxChain) entry.audioGroupFxChain = domGroupInfo.fxChain;
+      if (domGroupInfo.automation) entry.audioGroupAutomation = domGroupInfo.automation;
     }
 
     // Sub-compositions

packages/studio/src/player/lib/timelineElementHelpers.ts

@@ -11,6 +11,7 @@ import type { TimelineElement } from "../store/playerStore";
 import type { ClipManifestClip } from "./playbackTypes";
 import { isFinitePositive } from "./playbackAdapter";
 import { getSourceScopedSelectorIndex } from "../../utils/sourceScopedSelectorIndex";
+import { HF_AUDIO_GROUP_TAG } from "@hyperframes/core/audio-groups";
 
 // ---------------------------------------------------------------------------
 // Layer-reveal lift transparency
@@ -81,6 +82,14 @@ function normalizePlaybackRate(raw: number): number {
 }
 
 export function isTimelineIgnoredElement(el: Element): boolean {
+  // An `<hf-audio-group>` is a mixer bus, not a clip: it carries the group's
+  // label, fader, mute and FX chain, has no timing of its own, and is drawn as
+  // a GROUP ROW by the group derivation. Left in, the implicit-layer fallback
+  // also gave it an ordinary full-duration track — so a grouped composition
+  // showed "Voiceover • 0.0s – 12.0s" as a phantom clip directly above the real
+  // group header. Harmless-looking, but that row is draggable and trimmable,
+  // and writing timing onto the bus is meaningless.
+  if (el.tagName.toLowerCase() === HF_AUDIO_GROUP_TAG) return true;
   return Boolean(
     el.closest(
       [
@@ -346,6 +355,24 @@ export function getTimelineElementIdentity(element: { key?: string | null; id: s
   return element.key ?? element.id;
 }
 
+/**
+ * The id space the RUNTIME matches on — a bare DOM id, never a store key.
+ *
+ * Studio addresses rows by `buildTimelineElementKey`'s composite
+ * `<sourceFile>#<domId>`, but everything audio in `@hyperframes/core` keys off
+ * the live document: `resolveAudioGroups` collects `member.id`,
+ * `resolveCarveSourceIds` goes through `getElementById`. Anything crossing into
+ * that space — a group membership list, a carve source — has to be
+ * converted here first; a composite key silently matches nothing.
+ *
+ * `null` for a row with no DOM id at all (selector-addressed elements): such an
+ * element cannot be grouped, because `resolveAudioGroups` skips
+ * members without an `id` and would build a group that is half there.
+ */
+export function runtimeAudioId(element: { domId?: string | null }): string | null {
+  return element.domId || null;
+}
+
 /**
  * Timeline store key for a z-reorder entry built OUTSIDE the timeline
  * expansion (canvas context menu / LayersPanel), so the reorder commit can