@hyperframes/studio 0.8.5 → 0.8.7

package/src/player/components/useTimelineTrackLayout.ts

@@ -7,12 +7,14 @@ import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import type { DraggedClipState } from "./timelineClipDragTypes";
 import { useTimelineTrackDerivations } from "./useTimelineTrackDerivations";
 import {
+  STRIP_H,
   TRACK_H,
   createTimelineRowGeometry,
   type TimelineRowGeometry,
   trackHeights,
   type TimelineTrackHeightClip,
 } from "./timelineLayout";
+import type { TimelineTrackGroupInfo } from "./useTimelineTrackDerivations";
 
 export { getTrackStyle } from "./timelineIcons";
 
@@ -127,13 +129,35 @@ function computeLaneCounts(
   return laneCounts;
 }
 
+/** Group anchor rows have no elements of their own (`groupTimelineTracks`
+ *  pushes them as `[anchorKey, []]`), so `trackHeights` — which only ever
+ *  looks at a row's clips — always gives them TRACK_H. Override those
+ *  specific rows post-hoc: TRACK_H while collapsed, +STRIP_H once the
+ *  group's own `∿` (bus strip) is open. */
+function applyGroupStripHeights(
+  tracks: readonly (readonly [number, readonly TimelineElement[]])[],
+  rowHeights: number[],
+  groups: readonly TimelineTrackGroupInfo[],
+  expandedLaneOwnerIds: ReadonlySet<string>,
+): number[] {
+  if (groups.length === 0) return rowHeights;
+  const groupByAnchor = new Map(groups.map((group) => [group.anchorKey, group]));
+  return tracks.map(([track], index) => {
+    const group = groupByAnchor.get(track);
+    if (!group || !expandedLaneOwnerIds.has(group.id)) return rowHeights[index] ?? TRACK_H;
+    return TRACK_H + STRIP_H;
+  });
+}
+
 function useTimelineRowHeights(
   tracks: [number, TimelineElement[]][],
   gsapAnimations: Map<string, GsapAnimation[]>,
   selectedElementId: string | null,
   selectedElementIds: ReadonlySet<string>,
+  groups: readonly TimelineTrackGroupInfo[],
 ) {
   const expandedClipIds = usePlayerStore((s) => s.expandedClipIds);
+  const expandedLaneOwnerIds = usePlayerStore((s) => s.expandedLaneOwnerIds);
   const { laneCounts, rowGeometry } = useMemo(() => {
     const laneCounts = computeLaneCounts(tracks, gsapAnimations);
     // Keyframe lanes follow only the active clip, so a track with several
@@ -163,7 +187,12 @@ function useTimelineRowHeights(
         },
       ];
     });
-    const rowHeights = trackHeights(heightTracks, expandedClipIds);
+    const rowHeights = applyGroupStripHeights(
+      tracks,
+      trackHeights(heightTracks, expandedClipIds),
+      groups,
+      expandedLaneOwnerIds,
+    );
     return {
       laneCounts,
       rowGeometry: createTimelineRowGeometry(
@@ -171,7 +200,15 @@ function useTimelineRowHeights(
         rowHeights,
       ),
     };
-  }, [expandedClipIds, gsapAnimations, tracks, selectedElementId, selectedElementIds]);
+  }, [
+    expandedClipIds,
+    expandedLaneOwnerIds,
+    gsapAnimations,
+    groups,
+    tracks,
+    selectedElementId,
+    selectedElementIds,
+  ]);
   const rowGeometryRef = useRef<TimelineRowGeometry>(rowGeometry);
   rowGeometryRef.current = rowGeometry;
   return {
@@ -188,7 +225,8 @@ export function useTimelineTrackLayout(
   selectedElementId: string | null,
   selectedElementIds: ReadonlySet<string>,
 ) {
-  const { tracks, trackStyles, trackOrder } = useTimelineTrackDerivations(expandedElements);
+  const { tracks, trackStyles, trackOrder, groups, trackGroupOf } =
+    useTimelineTrackDerivations(expandedElements);
   const trackOrderRef = useRef(trackOrder);
   trackOrderRef.current = trackOrder;
   const { laneCounts, rowGeometry, rowGeometryRef, rowHeights } = useTimelineRowHeights(
@@ -196,6 +234,7 @@ export function useTimelineTrackLayout(
     gsapAnimations,
     selectedElementId,
     selectedElementIds,
+    groups,
   );
 
   return {
@@ -207,6 +246,8 @@ export function useTimelineTrackLayout(
     rowGeometry,
     rowGeometryRef,
     rowHeights,
+    groups,
+    trackGroupOf,
   };
 }
 
@@ -227,7 +268,23 @@ function useDisplayRowHeights(
 function useDisplayTrackOrder(draggedClip: DraggedClipState | null, trackOrder: number[]) {
   return useMemo(() => {
     if (!draggedClip?.started || trackOrder.includes(draggedClip.previewTrack)) return trackOrder;
-    return [...trackOrder, draggedClip.previewTrack].sort((a, b) => a - b);
+    // A group's members sit out of raw numeric order (pulled under their
+    // anchor row), so a plain numeric sort here would undo that grouping the
+    // moment a clip drags onto a brand-new track. Insert the new preview
+    // track only relative to other REAL (integer) tracks, leaving any
+    // fractional group-anchor keys exactly where grouping placed them.
+    const preview = draggedClip.previewTrack;
+    const result: number[] = [];
+    let inserted = false;
+    for (const key of trackOrder) {
+      if (!inserted && Number.isInteger(key) && key > preview) {
+        result.push(preview);
+        inserted = true;
+      }
+      result.push(key);
+    }
+    if (!inserted) result.push(preview);
+    return result;
   }, [draggedClip, trackOrder]);
 }
 

package/src/player/hooks/previewMessageRouter.ts

@@ -0,0 +1,127 @@
+/**
+ * The `window.message` router for the preview iframe.
+ *
+ * Extracted from `useTimelinePlayer`, which had grown past the studio's 600-line
+ * file cap and carried a `fallow-ignore-next-line complexity` on this function
+ * admitting the same thing. Nothing here is new logic — it is the same four
+ * branches (accept-gate, group levels, state, timeline) against the same refs,
+ * with the suppression retired rather than moved.
+ */
+
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import type { ClipManifestClip, IframeWindow, PlaybackAdapter } from "../lib/playbackTypes";
+import { hasTimelinePerformanceFixtureLease } from "../lib/timelinePerformanceFixture";
+import { acceptStudioRuntimeMessage } from "../lib/runtimeProtocol";
+import { groupLevels, parseGroupLevelsMessage } from "../store/groupLevels";
+import { parseTimelineFromDOM } from "../lib/timelineDOM";
+
+/** What `processTimelineMessage` accepts — the clip-manifest postMessage. */
+export interface ClipManifestMessage {
+  clips: ClipManifestClip[];
+  durationInFrames: number;
+  scenes?: Array<{ id: string; label: string; start: number; duration: number }>;
+  protocolVersion?: unknown;
+  capabilities?: unknown;
+  fps?: unknown;
+}
+
+interface PreviewMessage {
+  source?: string;
+  type?: string;
+  clips?: unknown;
+}
+
+export interface PreviewMessageRouterDeps {
+  iframeRef: { current: HTMLIFrameElement | null };
+  /** Kept as refs by the caller so the listener can be registered once. */
+  processTimelineMessageRef: { current: (data: ClipManifestMessage) => void };
+  enrichMissingCompositionsRef: { current: () => void };
+  lastTimelineMessageRef: { current: number };
+  getAdapter: () => PlaybackAdapter | null;
+  syncTimelineElements: (elements: TimelineElement[]) => void;
+}
+
+/** True when the message did not come from OUR preview iframe. */
+function isForeignSource(e: MessageEvent, iframe: HTMLIFrameElement | null): boolean {
+  return Boolean(e.source && iframe && e.source !== iframe.contentWindow);
+}
+
+/** A preview message worth acting on, or null: the fixture lease, the sender
+ *  check and the protocol accept-gate collapsed into one answer so the listener
+ *  below stays a flat dispatch. */
+function acceptedPreviewMessage(
+  e: MessageEvent,
+  iframe: HTMLIFrameElement | null,
+): PreviewMessage | null {
+  if (hasTimelinePerformanceFixtureLease()) return null;
+  if (isForeignSource(e, iframe)) return null;
+  const data = e.data as PreviewMessage | null;
+  if (data?.source !== "hf-preview") return null;
+  return acceptStudioRuntimeMessage(data) ? data : null;
+}
+
+/** One meter reading per group with an active member. */
+function handleGroupLevelsMessage(data: PreviewMessage): void {
+  const levels = parseGroupLevelsMessage(data);
+  if (levels) groupLevels.notify(levels);
+}
+
+/**
+ * A `state` tick doubles as a recovery hook: if the store still has no
+ * elements, read the manifest straight off the iframe, and if no `timeline`
+ * message has arrived recently, re-run enrichment.
+ */
+function handleStateMessage(
+  deps: PreviewMessageRouterDeps,
+  iframe: HTMLIFrameElement | null,
+): void {
+  try {
+    if (usePlayerStore.getState().elements.length === 0) {
+      const manifest = (iframe?.contentWindow as IframeWindow | null)?.__clipManifest;
+      if (manifest && manifest.clips.length > 0) {
+        deps.processTimelineMessageRef.current(manifest);
+      }
+    }
+    if (Date.now() - deps.lastTimelineMessageRef.current > 500) {
+      deps.enrichMissingCompositionsRef.current();
+    }
+  } catch {}
+}
+
+/**
+ * The clip list. When it arrives empty-handed — the store still has nothing —
+ * fall back to parsing the live DOM, which is the only source left before the
+ * next tick.
+ */
+function handleTimelineMessage(
+  deps: PreviewMessageRouterDeps,
+  iframe: HTMLIFrameElement | null,
+  data: ClipManifestMessage,
+): void {
+  deps.lastTimelineMessageRef.current = Date.now();
+  deps.processTimelineMessageRef.current(data);
+  deps.enrichMissingCompositionsRef.current();
+  if (usePlayerStore.getState().elements.length > 0) return;
+  try {
+    const doc = iframe?.contentDocument;
+    const adapter = deps.getAdapter();
+    if (!doc || !adapter) return;
+    const els = parseTimelineFromDOM(doc, adapter.getDuration());
+    if (els.length > 0) deps.syncTimelineElements(els);
+  } catch {}
+}
+
+export function createPreviewMessageHandler(
+  deps: PreviewMessageRouterDeps,
+): (e: MessageEvent) => void {
+  return (e: MessageEvent) => {
+    const iframe = deps.iframeRef.current;
+    const data = acceptedPreviewMessage(e, iframe);
+    if (!data) return;
+    if (data.type === "group-levels") return handleGroupLevelsMessage(data);
+    if (data.type === "state") return handleStateMessage(deps, iframe);
+    if (data.type === "timeline" && Array.isArray(data.clips)) {
+      handleTimelineMessage(deps, iframe, data as unknown as ClipManifestMessage);
+    }
+  };
+}

package/src/player/hooks/useExpandedTimelineElements.test.ts

@@ -1,12 +1,19 @@
-import { describe, expect, it } from "vitest";
+// @vitest-environment happy-dom
+
+import React, { act, useEffect } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
 import {
   buildExpandedElements,
   resolveTimelineExpansionRawId,
+  useExpandedTimelineElements,
 } from "./useExpandedTimelineElements";
 import { buildTimelineElementKey } from "../lib/timelineElementHelpers";
-import type { TimelineElement } from "../store/playerStore";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import type { ClipManifestClip } from "../lib/playbackTypes";
 
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
 const clip = (over: Partial<ClipManifestClip>): ClipManifestClip => ({
   id: "x",
   label: "x",
@@ -31,6 +38,19 @@ const el = (over: Partial<TimelineElement>): TimelineElement => ({
   ...over,
 });
 
+function TimelineExpansionHarness({ onValue }: { onValue: (value: TimelineElement[]) => void }) {
+  const value = useExpandedTimelineElements();
+  useEffect(() => {
+    onValue(value);
+  }, [onValue, value]);
+  return null;
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  usePlayerStore.getState().reset();
+});
+
 describe("buildExpandedElements", () => {
   it("rebases a 1-level child onto its sub-comp host (start + sourceFile)", () => {
     // host s3 at absolute 16 → stats-panel.html; children live in that file.
@@ -357,7 +377,7 @@ describe("buildExpandedElements", () => {
   it("keeps the host row present at every playhead position (keyframe lane repro)", () => {
     // Live repro with no drag at all: seek 0 gave 3 diamonds, seek 7.68 gave 0,
     // seek 0.2 gave 3. Diamonds render per row from keyframeCache.get(elementKey),
-    // so the whole lane went with the host row whenever the paused drill-in
+    // so the whole lane went with the host row whenever the store-time drill-in
     // substituted it for its children.
     const elements = [
       el({ id: "scene", domId: "scene", key: "index.html#scene", start: 0, duration: 12 }),
@@ -371,7 +391,6 @@ describe("buildExpandedElements", () => {
     for (const currentTime of [0, 7.68, 0.2]) {
       const rawId = resolveTimelineExpansionRawId({
         selectedElementId: null,
-        isPlaying: false,
         currentTime,
         manifest,
         parentMap,
@@ -424,13 +443,12 @@ describe("buildExpandedElements", () => {
 });
 
 describe("resolveTimelineExpansionRawId", () => {
-  it("returns null when paused inside a childless top-level clip", () => {
+  it("returns null inside a childless top-level clip", () => {
     const manifest = [clip({ id: "title", start: 0, duration: 4 })];
 
     expect(
       resolveTimelineExpansionRawId({
         selectedElementId: null,
-        isPlaying: false,
         currentTime: 2,
         manifest,
         parentMap: new Map(),
@@ -438,7 +456,7 @@ describe("resolveTimelineExpansionRawId", () => {
     ).toBeNull();
   });
 
-  it("auto-expands an active composition with children when paused and nothing is selected", () => {
+  it("auto-expands an active composition with children when nothing is selected", () => {
     const manifest = [
       clip({ id: "scene", start: 1, duration: 5 }),
       clip({ id: "headline", start: 1.5, duration: 2 }),
@@ -448,7 +466,6 @@ describe("resolveTimelineExpansionRawId", () => {
     expect(
       resolveTimelineExpansionRawId({
         selectedElementId: null,
-        isPlaying: false,
         currentTime: 2,
         manifest,
         parentMap,
@@ -468,7 +485,6 @@ describe("resolveTimelineExpansionRawId", () => {
     expect(
       resolveTimelineExpansionRawId({
         selectedElementId: null,
-        isPlaying: false,
         currentTime: 12,
         manifest,
         parentMap,
@@ -491,7 +507,6 @@ describe("resolveTimelineExpansionRawId", () => {
     expect(
       resolveTimelineExpansionRawId({
         selectedElementId: null,
-        isPlaying: false,
         currentTime: 5,
         manifest,
         parentMap,
@@ -499,7 +514,7 @@ describe("resolveTimelineExpansionRawId", () => {
     ).toBe("second");
   });
 
-  it("auto-expands the innermost active nested composition when paused", () => {
+  it("auto-expands the innermost active nested composition", () => {
     const manifest = [
       clip({ id: "outer", start: 0, duration: 10 }),
       clip({ id: "inner", start: 2, duration: 5 }),
@@ -513,7 +528,6 @@ describe("resolveTimelineExpansionRawId", () => {
     expect(
       resolveTimelineExpansionRawId({
         selectedElementId: null,
-        isPlaying: false,
         currentTime: 3.5,
         manifest,
         parentMap,
@@ -521,7 +535,7 @@ describe("resolveTimelineExpansionRawId", () => {
     ).toBe("inner");
   });
 
-  it("does not auto-expand an active composition while playing", () => {
+  it("resolves an active composition from the current store time", () => {
     const manifest = [
       clip({ id: "scene", start: 0, duration: 5 }),
       clip({ id: "headline", start: 1, duration: 2 }),
@@ -531,15 +545,49 @@ describe("resolveTimelineExpansionRawId", () => {
     expect(
       resolveTimelineExpansionRawId({
         selectedElementId: null,
-        isPlaying: true,
         currentTime: 2,
         manifest,
         parentMap,
       }),
-    ).toBeNull();
+    ).toBe("scene");
+  });
+
+  it("keeps inline children visible when the master timeline is playing", () => {
+    const elements = [
+      el({ id: "scene", domId: "scene", key: "index.html#scene", start: 0, duration: 5 }),
+    ];
+    const manifest = [
+      clip({ id: "scene", start: 0, duration: 5, compositionSrc: "scene.html" }),
+      clip({ id: "headline", start: 1, duration: 2 }),
+    ];
+    const parentMap = new Map([["headline", "scene"]]);
+    let rows: TimelineElement[] | undefined;
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+
+    act(() => {
+      usePlayerStore.setState({
+        elements,
+        clipManifest: manifest,
+        clipParentMap: parentMap,
+        currentTime: 2,
+        isPlaying: true,
+      });
+      root.render(
+        React.createElement(TimelineExpansionHarness, {
+          onValue: (value) => (rows = value),
+        }),
+      );
+    });
+
+    expect(usePlayerStore.getState().isPlaying).toBe(true);
+    expect(rows?.map((row) => row.domId ?? row.id)).toEqual(["scene", "headline"]);
+
+    act(() => root.unmount());
   });
 
-  it("keeps selected elements ahead of paused active composition auto-expansion", () => {
+  it("keeps selected elements ahead of active composition auto-expansion", () => {
     const manifest = [
       clip({ id: "scene", start: 0, duration: 6 }),
       clip({ id: "headline", start: 1, duration: 2 }),
@@ -553,7 +601,6 @@ describe("resolveTimelineExpansionRawId", () => {
     expect(
       resolveTimelineExpansionRawId({
         selectedElementId: "caption",
-        isPlaying: false,
         currentTime: 1.5,
         manifest,
         parentMap,

package/src/player/hooks/useExpandedTimelineElements.ts

@@ -35,7 +35,6 @@ function resolveRawId(
 
 interface TimelineExpansionRawIdInput {
   selectedElementId: string | null;
-  isPlaying: boolean;
   currentTime: number;
   manifest: ClipManifestClip[];
   parentMap: Map<string, string>;
@@ -97,14 +96,12 @@ function findActiveExpandableCompositionId(
 
 export function resolveTimelineExpansionRawId({
   selectedElementId,
-  isPlaying,
   currentTime,
   manifest,
   parentMap,
 }: TimelineExpansionRawIdInput): string | null {
   const selectedRawId = resolveRawId(selectedElementId, manifest, parentMap);
   if (selectedRawId) return selectedRawId;
-  if (isPlaying) return null;
   return findActiveExpandableCompositionId(currentTime, manifest, parentMap);
 }
 
@@ -334,7 +331,7 @@ export function buildExpandedElements(
       : (el.key ?? el.id) === parentKey;
 
   // ADDITIVE drill-in: the host row stays and its children are appended under
-  // it. Expansion is also triggered by the playhead alone (paused auto-expand),
+  // it. Expansion is also triggered by the playhead alone (active auto-expand),
   // so substituting the host row made it vanish on an ordinary seek, and with
   // it the host's keyframe lane, since diamonds render per row from
   // `keyframeCache.get(elementKey)`. The synthetic fractional lanes above sit
@@ -356,13 +353,14 @@ export function useExpandedTimelineElements(): TimelineElement[] {
   const clipParentMap = usePlayerStore((s) => s.clipParentMap);
   const domClipChildren = usePlayerStore((s) => s.domClipChildren);
   const selectedElementId = usePlayerStore((s) => s.selectedElementId);
-  const isPlaying = usePlayerStore((s) => s.isPlaying);
   const currentTime = usePlayerStore((s) => s.currentTime);
 
-  // Resolve which raw clip drives expansion. This reads currentTime (for paused
-  // auto-expand) so it re-runs each scrub tick, but it's a cheap manifest scan and
-  // its RESULT only changes when the playhead crosses a composition boundary. Keying
-  // the expensive build below on these ids (not raw currentTime) avoids re-allocating
+  // Resolve which raw clip drives expansion from the store's committed playhead
+  // time. The RAF loop keeps live time out of React and Zustand during playback,
+  // so this target deliberately stays stable until the loop commits or a seek /
+  // pause updates the store. The scan re-runs on scrub ticks, but its RESULT only
+  // changes when the playhead crosses a composition boundary. Keying the expensive
+  // build below on these ids (not raw currentTime) avoids re-allocating
   // expandedElements — and cascading TimelineClip re-renders — on every tick.
   const { rawId, selectedRawId } = useMemo(() => {
     if (!clipManifest || clipManifest.length === 0 || clipParentMap.size === 0) {
@@ -371,14 +369,13 @@ export function useExpandedTimelineElements(): TimelineElement[] {
     return {
       rawId: resolveTimelineExpansionRawId({
         selectedElementId,
-        isPlaying,
         currentTime,
         manifest: clipManifest,
         parentMap: clipParentMap,
       }),
       selectedRawId: resolveRawId(selectedElementId, clipManifest, clipParentMap),
     };
-  }, [clipManifest, clipParentMap, selectedElementId, isPlaying, currentTime]);
+  }, [clipManifest, clipParentMap, selectedElementId, currentTime]);
 
   return useMemo(() => {
     if (!clipManifest || clipManifest.length === 0 || clipParentMap.size === 0) {

package/src/player/hooks/useTimelinePlayer.ts

@@ -35,7 +35,6 @@ import {
 import {
   readTimelineDurationFromDocument,
   mergeTimelineElementsPreservingDowngrades,
-  parseTimelineFromDOM,
 } from "../lib/timelineDOM";
 import { normalizeToZones } from "../components/timelineZones";
 import {
@@ -48,7 +47,7 @@ import { hasTimelinePerformanceFixtureLease } from "../lib/timelinePerformanceFi
 import { applyCachedSourceDurations, probeMissingSourceDurations } from "../lib/mediaProbe";
 import { shouldResumeForwardPlaybackAfterSeek, shouldStopAfterSeek } from "../lib/playbackSeek";
 import { applyPreviewVariablesToUrl } from "../../hooks/previewVariablesStore";
-import { acceptStudioRuntimeMessage } from "../lib/runtimeProtocol";
+import { createPreviewMessageHandler } from "./previewMessageRouter";
 import { timelineElementsChanged } from "./timelinePlayerSync";
 
 export function useTimelinePlayer() {
@@ -488,51 +487,14 @@ export function useTimelinePlayer() {
     const handleWindowKeyDown = (e: KeyboardEvent) => playbackKeyDownRef.current(e);
     const handleWindowKeyUp = (e: KeyboardEvent) => playbackKeyUpRef.current(e);
 
-    // Pre-existing message-router complexity — surfaced by line shifts, not new logic.
-    // fallow-ignore-next-line complexity
-    const handleMessage = (e: MessageEvent) => {
-      if (hasTimelinePerformanceFixtureLease()) return;
-      const data = e.data;
-      const ourIframe = iframeRef.current;
-      if (e.source && ourIframe && e.source !== ourIframe.contentWindow) {
-        return;
-      }
-      if (data?.source === "hf-preview") {
-        if (!acceptStudioRuntimeMessage(data)) return;
-      }
-      if (data?.source === "hf-preview" && data?.type === "state") {
-        try {
-          if (usePlayerStore.getState().elements.length === 0) {
-            const iframeWin = ourIframe?.contentWindow as IframeWindow | null;
-            const manifest = iframeWin?.__clipManifest;
-            if (manifest && manifest.clips.length > 0) {
-              processTimelineMessageRef.current(manifest);
-            }
-          }
-          const msSinceTimeline = Date.now() - lastTimelineMessageRef.current;
-          if (msSinceTimeline > 500) {
-            enrichMissingCompositionsRef.current();
-          }
-        } catch {}
-      }
-      if (data?.source === "hf-preview" && data?.type === "timeline" && Array.isArray(data.clips)) {
-        lastTimelineMessageRef.current = Date.now();
-        processTimelineMessageRef.current(data);
-        enrichMissingCompositionsRef.current();
-        if (usePlayerStore.getState().elements.length === 0) {
-          try {
-            const doc = ourIframe?.contentDocument;
-            const adapter = getAdapter();
-            if (doc && adapter) {
-              const els = parseTimelineFromDOM(doc, adapter.getDuration());
-              if (els.length > 0) {
-                syncTimelineElements(els);
-              }
-            }
-          } catch {}
-        }
-      }
-    };
+    const handleMessage = createPreviewMessageHandler({
+      iframeRef,
+      processTimelineMessageRef,
+      enrichMissingCompositionsRef,
+      lastTimelineMessageRef,
+      getAdapter,
+      syncTimelineElements,
+    });
 
     const handleVisibilityChange = () => {
       if (document.hidden && usePlayerStore.getState().isPlaying) {

package/src/player/lib/timelineDOM.ts

@@ -12,6 +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 {
   resolveMediaElement,
   applyMediaMetadataFromElement,
@@ -67,6 +68,37 @@ 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;
@@ -138,6 +170,15 @@ export function createTimelineElementFromManifestClip(params: {
     if (hostEl.hasAttribute("data-hidden")) entry.hidden = true;
     const timelineRole = hostEl.getAttribute("data-timeline-role");
     if (timelineRole) entry.timelineRole = timelineRole;
+    const audioGroup = hostEl.getAttribute("data-audio-group");
+    if (audioGroup) {
+      entry.audioGroup = audioGroup;
+      const info = groupInfoFor(doc ?? hostEl.ownerDocument, audioGroup);
+      entry.audioGroupLabel = info.label;
+      entry.audioGroupVolume = info.volume;
+      entry.audioGroupHidden = info.hidden;
+      if (info.fxChain) entry.audioGroupFxChain = info.fxChain;
+    }
     const fxChain = hostEl.getAttribute("data-fx-chain");
     if (fxChain) entry.fxChain = fxChain;
     const automation = hostEl.getAttribute("data-automation");
@@ -356,6 +397,16 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
     const timelineRole = el.getAttribute("data-timeline-role");
     if (timelineRole) entry.timelineRole = timelineRole;
 
+    const domAudioGroup = el.getAttribute("data-audio-group");
+    if (domAudioGroup) {
+      entry.audioGroup = domAudioGroup;
+      const domGroupInfo = groupInfoFor(doc, domAudioGroup);
+      entry.audioGroupLabel = domGroupInfo.label;
+      entry.audioGroupVolume = domGroupInfo.volume;
+      entry.audioGroupHidden = domGroupInfo.hidden;
+      if (domGroupInfo.fxChain) entry.audioGroupFxChain = domGroupInfo.fxChain;
+    }
+
     // Sub-compositions
     const compSrc =
       el.getAttribute("data-composition-src") || el.getAttribute("data-composition-file");