@hyperframes/studio 0.8.10 → 0.8.12

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -10,24 +10,27 @@
 
 import { useCallback } from "react";
 import { liveTime, usePlayerStore } from "../store/playerStore";
-import type { TimelineElement, DomClipChild } from "../store/playerStore";
-import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";
-import type { PlaybackAdapter, ClipManifestClip, IframeWindow } from "../lib/playbackTypes";
+import type { TimelineElement } from "../store/playerStore";
+import type { PlaybackAdapter, IframeWindow } from "../lib/playbackTypes";
+import { readTimelineDurationFromDocument } from "../lib/timelineDOM";
+import { buildMissingCompositionElements } from "../lib/timelineIframeHelpers";
+import { acceptedRuntimeMessageFps } from "../lib/runtimeProtocol";
 import {
-  parseTimelineFromDOM,
-  createTimelineElementFromManifestClip,
-  findTimelineDomNodeForClip,
-  createImplicitTimelineLayersFromDOM,
-  buildStandaloneRootTimelineElement,
-  getTimelineElementSelector,
-  readTimelineDurationFromDocument,
-} from "../lib/timelineDOM";
-import {
-  normalizePreviewViewport,
-  autoHealMissingCompositionIds,
-  buildMissingCompositionElements,
-} from "../lib/timelineIframeHelpers";
-import { acceptedRuntimeMessageFps, inspectStudioRuntimeMessage } from "../lib/runtimeProtocol";
+  buildTimelineElementsFromClips,
+  clipTreeParentMap,
+  collectSubCompositionDomChildren,
+  hydrateTimelineFromPreview,
+  isPreviewReadinessMessage,
+  safeContentDocument,
+  sanitizeDurationSeconds,
+  seekAdapterToRestorePoint,
+  syncAdapterDuration,
+  withImplicitDomLayers,
+  type RuntimeTimelineMessage,
+} from "./timelineSyncHydration";
+
+// Re-exported for the tests and callers that have always imported it from here.
+export { resolveReloadSeekTime } from "./timelineSyncHydration";
 
 interface UseTimelineSyncCallbacksParams {
   iframeRef: React.RefObject<HTMLIFrameElement | null>;
@@ -70,27 +73,6 @@ export function revealIframe(iframe: HTMLIFrameElement | null): void {
   }
 }
 
-export function resolveReloadSeekTime(input: {
-  pendingSeek: number | null;
-  requestedSeek: number | null;
-  storeCurrentTime: number;
-  duration: number;
-}): number {
-  const target = input.pendingSeek ?? input.requestedSeek ?? input.storeCurrentTime;
-  if (!Number.isFinite(target) || target <= 0) return 0;
-  // Only clamp to duration when it's a usable positive number. A non-finite or
-  // non-positive duration (e.g. the adapter reports NaN mid-reload) would turn
-  // Math.min(target, NaN) into NaN and seek(NaN); return the guarded target
-  // unclamped instead so the playhead lands at the intended position.
-  if (!Number.isFinite(input.duration) || input.duration <= 0) return target;
-  return Math.min(target, input.duration);
-}
-
-/** Reject non-finite, non-positive, and absurdly large (loop-inflated) values. */
-function sanitizeDurationSeconds(value: number): number {
-  return Number.isFinite(value) && value > 0 && value < 7200 ? value : 0;
-}
-
 /**
  * The transport TOTAL a clip-manifest message should write to the store.
  *
@@ -130,14 +112,7 @@ export function useTimelineSyncCallbacks({
 }: UseTimelineSyncCallbacksParams) {
   // Convert a runtime timeline message (from iframe postMessage) into TimelineElements
   const processTimelineMessage = useCallback(
-    (data: {
-      clips: ClipManifestClip[];
-      durationInFrames: number;
-      scenes?: Array<{ id: string; label: string; start: number; duration: number }>;
-      protocolVersion?: unknown;
-      capabilities?: unknown;
-      fps?: unknown;
-    }) => {
+    (data: RuntimeTimelineMessage) => {
       if (!data.clips || data.clips.length === 0) {
         return;
       }
@@ -149,86 +124,18 @@ export function useTimelineSyncCallbacks({
       const filtered = data.clips.filter(
         (clip) => !clip.parentCompositionId || !clipCompositionIds.has(clip.parentCompositionId),
       );
-      let iframeDoc: Document | null = null;
-      try {
-        iframeDoc = iframeRef.current?.contentDocument ?? null;
-      } catch {
-        iframeDoc = null;
-      }
+      const iframeDoc = safeContentDocument(iframeRef.current);
 
       try {
-        const iframeWin = iframeRef.current?.contentWindow as
-          | (Window & { __clipTree?: import("@hyperframes/core/runtime/clipTree").ClipTree })
-          | null;
-        const clipTree = iframeWin?.__clipTree;
-        const parentMap = new Map<string, string>();
-        if (clipTree) {
-          const walk = (nodes: typeof clipTree.roots) => {
-            for (const node of nodes) {
-              if (node.id && node.parentId) parentMap.set(node.id, node.parentId);
-              if (node.children.length > 0) walk(node.children);
-            }
-          };
-          walk(clipTree.roots);
-        }
-
-        // Descend into each sub-composition host: its internal elements (group
-        // wrappers + their children) carry no `data-start`, so the clip
-        // tree/manifest never enumerate them. Surface them studio-side as DOM
-        // children + parent links so the timeline can expand a sub-comp/group
-        // row to show them. Manifest stays lean (timed clips only).
-        const domClipChildren: DomClipChild[] = [];
-        if (iframeDoc) {
-          for (const clip of data.clips) {
-            if (clip.kind !== "composition" || !clip.id) continue;
-            const hostEl = iframeDoc.getElementById(clip.id);
-            if (!hostEl) continue;
-            const hostId = clip.id;
-            const innerRoot = hostEl.querySelector("[data-hf-inner-root]") ?? hostEl;
-            // Collect the sub-comp's id'd descendants (grouped OR ungrouped) so they
-            // expand into timeline rows. Descends through id-less structural wrappers
-            // (the inlined sub-comp body), and one level into groups for drill-in.
-            const collect = (parentEl: Element, parentId: string) => {
-              for (const child of Array.from(parentEl.children)) {
-                if (!child.id) {
-                  collect(child, parentId); // unwrap id-less structural containers
-                  continue;
-                }
-                const isGroup = child.hasAttribute("data-hf-group");
-                domClipChildren.push({
-                  id: child.id,
-                  parentId,
-                  hostId,
-                  label: isGroup ? child.getAttribute("data-hf-group") || child.id : child.id,
-                  stackingContextId: resolveCssStackingContextId(child),
-                });
-                parentMap.set(child.id, parentId);
-                if (isGroup) collect(child, child.id);
-              }
-            };
-            collect(innerRoot, hostId);
-          }
-        }
+        const parentMap = clipTreeParentMap(iframeRef.current?.contentWindow ?? null);
+        const domClipChildren = collectSubCompositionDomChildren(iframeDoc, data.clips, parentMap);
         usePlayerStore.getState().setClipParentMap(parentMap);
         usePlayerStore.getState().setDomClipChildren(domClipChildren);
       } catch {
         // cross-origin or __clipTree not available — maps stay empty
       }
 
-      const usedHostEls = new Set<Element>();
-      const els: TimelineElement[] = filtered.map((clip, index) => {
-        const hostEl = iframeDoc
-          ? findTimelineDomNodeForClip(iframeDoc, clip, index, usedHostEls)
-          : null;
-        if (hostEl) usedHostEls.add(hostEl);
-        return createTimelineElementFromManifestClip({
-          clip,
-          fallbackIndex: index,
-          doc: iframeDoc,
-          hostEl,
-        });
-      });
-      const rawDuration = data.durationInFrames / acceptedRuntimeMessageFps(data);
+      const els = buildTimelineElementsFromClips(filtered, iframeDoc);
       // Clamp non-finite or absurdly large durations — the runtime can emit
       // Infinity when it detects a loop-inflated GSAP timeline without an
       // explicit data-duration on the root composition. Floor the manifest total
@@ -236,27 +143,14 @@ export function useTimelineSyncCallbacks({
       // furthest clip end (shorter than the authored window) can't leave a stale,
       // too-short total in the transport (the "0:44/0:40" bug).
       const newDuration = resolveTimelineTotalDuration({
-        manifestDurationSeconds: rawDuration,
+        manifestDurationSeconds: data.durationInFrames / acceptedRuntimeMessageFps(data),
         authoredRootDurationSeconds: readTimelineDurationFromDocument(iframeDoc),
       });
-      const effectiveDuration = newDuration > 0 ? newDuration : usePlayerStore.getState().duration;
-      const clampedEls =
-        effectiveDuration > 0
-          ? els
-              .filter((element) => element.start < effectiveDuration)
-              .map((element) => ({
-                ...element,
-                duration: Math.min(element.duration, effectiveDuration - element.start),
-              }))
-              .filter((element) => element.duration > 0)
-          : els;
-      const timelineEls =
-        iframeDoc && effectiveDuration > 0
-          ? [
-              ...clampedEls,
-              ...createImplicitTimelineLayersFromDOM(iframeDoc, effectiveDuration, clampedEls),
-            ]
-          : clampedEls;
+      const timelineEls = withImplicitDomLayers(
+        els,
+        iframeDoc,
+        newDuration > 0 ? newDuration : usePlayerStore.getState().duration,
+      );
       if (timelineEls.length > 0) {
         syncTimelineElements(timelineEls, newDuration > 0 ? newDuration : undefined);
       }
@@ -294,34 +188,7 @@ export function useTimelineSyncCallbacks({
     if (!adapter || adapter.getDuration() <= 0) return false;
 
     adapter.pause();
-    // Honor a seek requested before the adapter was ready. It may sit in either
-    // place: `pendingSeekRef` if the store subscription was mounted when requestSeek
-    // fired, or only in the store's `requestedSeekTime` if it fired earlier still
-    // (deep-link hydration runs before the player subscription mounts, so the request
-    // never reaches pendingSeekRef). Reconciling with the store here is what makes a
-    // deep-linked `?t=` land instead of starting at 0.
-    const storeSeek = usePlayerStore.getState().requestedSeekTime;
-    const startTime = resolveReloadSeekTime({
-      pendingSeek: pendingSeekRef.current,
-      requestedSeek: storeSeek,
-      storeCurrentTime: usePlayerStore.getState().currentTime,
-      duration: adapter.getDuration(),
-    });
-    pendingSeekRef.current = null;
-    if (storeSeek != null) usePlayerStore.getState().clearSeekRequest();
-
-    // Force a REAL render at startTime, not a no-op. After a post-edit reload the
-    // freshly rebuilt GSAP timeline can already report being at `startTime`
-    // internally (the reload restores the same playhead), so a single
-    // `adapter.seek(startTime)` is a GSAP no-op — `tl.seek(t)` at the current time
-    // doesn't re-evaluate. That's why a just-dropped clip stayed invisible until
-    // the user nudged the playhead: its element's state was never applied at the
-    // restore position. Seeking to a DIFFERENT guard value first (a hair off, or 0
-    // when startTime is already ~0) guarantees the follow-up seek to `startTime`
-    // crosses a time boundary and re-renders every clip — including the new one.
-    const guardTime = startTime > 0.001 ? Math.max(0, startTime - 0.001) : 0.001;
-    adapter.seek(guardTime);
-    adapter.seek(startTime);
+    const startTime = seekAdapterToRestorePoint(adapter, pendingSeekRef);
     // The correct frame is now rendered — reveal the iframe that refreshPlayer hid
     // for the reload, so the user sees the restored frame directly (never the raw
     // all-clips DOM). Cleared unconditionally: any later failure path must not leave
@@ -330,15 +197,7 @@ export function useTimelineSyncCallbacks({
     // Keep non-React listeners such as the capture link and time display in sync
     // with the initial adapter seek on iframe load.
     liveTime.notify(startTime);
-    const adapterDur = adapter.getDuration();
-    if (
-      Number.isFinite(adapterDur) &&
-      adapterDur > 0 &&
-      adapterDur < 7200 &&
-      adapterDur !== usePlayerStore.getState().duration
-    ) {
-      setDuration(adapterDur);
-    }
+    syncAdapterDuration(adapter, setDuration);
     setCurrentTime(startTime);
     if (!isRefreshingRef.current) {
       setTimelineReady(true);
@@ -346,42 +205,15 @@ export function useTimelineSyncCallbacks({
     isRefreshingRef.current = false;
     setIsPlaying(false);
 
-    try {
-      const iframe = iframeRef.current;
-      const doc = iframe?.contentDocument;
-      const iframeWin = iframe?.contentWindow as IframeWindow | null;
-      if (doc && iframeWin) {
-        normalizePreviewViewport(doc, iframeWin);
-        autoHealMissingCompositionIds(doc);
-        attachIframeShortcutListeners();
-      }
-
-      const manifest = iframeWin?.__clipManifest;
-      if (manifest && manifest.clips.length > 0) {
-        processTimelineMessage(manifest);
-      }
-      enrichMissingCompositions();
-      applyPreviewAudioState();
-
-      if (usePlayerStore.getState().elements.length === 0 && doc) {
-        const els = parseTimelineFromDOM(doc, adapter.getDuration());
-        if (els.length > 0) syncTimelineElements(els);
-      }
-      if (usePlayerStore.getState().elements.length === 0 && doc) {
-        const rootComp = doc.querySelector("[data-composition-id]");
-        const rootDuration = adapter.getDuration();
-        if (rootComp && rootDuration > 0) {
-          const fallbackElement = buildStandaloneRootTimelineElement({
-            compositionId: rootComp.getAttribute("data-composition-id") || "composition",
-            tagName: (rootComp as HTMLElement).tagName || "div",
-            rootDuration,
-            iframeSrc: iframe?.src || "",
-            selector: getTimelineElementSelector(rootComp),
-          });
-          if (fallbackElement) syncTimelineElements([fallbackElement]);
-        }
-      }
-    } catch {}
+    hydrateTimelineFromPreview({
+      iframe: iframeRef.current,
+      adapter,
+      processTimelineMessage,
+      enrichMissingCompositions,
+      applyPreviewAudioState,
+      attachIframeShortcutListeners,
+      syncTimelineElements,
+    });
     return true;
   }, [
     getAdapter,
@@ -421,15 +253,7 @@ export function useTimelineSyncCallbacks({
     };
 
     const onMessage = (e: MessageEvent) => {
-      if (e.source && iframe && e.source !== iframe.contentWindow) return;
-      const data = e.data;
-      if (data?.source === "hf-preview" && (data?.type === "state" || data?.type === "timeline")) {
-        // The main message handler owns protocol-error diagnostics. This readiness-only
-        // listener mirrors its acceptance gate without dispatching a duplicate event:
-        // an unsupported runtime must not make the iframe appear successfully settled.
-        if (inspectStudioRuntimeMessage(data).status === "unsupported") return;
-        trySettle();
-      }
+      if (isPreviewReadinessMessage(e, iframe)) trySettle();
     };
     window.addEventListener("message", onMessage);
 

package/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);
+  });
 });

package/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,6 +39,27 @@ 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) => {
@@ -45,11 +67,13 @@ export function syncStoredAutomationFromPreview(doc: Document | null | undefined
     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 } : {};
   });

package/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();
+  });
+});

package/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(`