@hyperframes/studio 0.8.11 → 0.8.12

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

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

package/src/player/lib/timelineGroupInfo.ts

@@ -0,0 +1,134 @@
+/**
+ * The audio-group scan cached per preview document, and the mechanism that
+ * keeps it honest.
+ *
+ * Split out of `timelineDOM.ts` (600-line studio ceiling). Self-contained: the
+ * cache, its revision counter, the observer that bumps it, and the one reader.
+ */
+
+import {
+  HF_AUDIO_GROUP_ATTR,
+  HF_AUDIO_GROUP_TAG,
+  resolveAudioGroups,
+} from "@hyperframes/core/audio-groups";
+import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";
+import { HF_AUDIO_FX_ATTR } from "@hyperframes/core/audio-fx";
+
+// 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;
+  automation?: string;
+}
+
+/**
+ * The cached scan, plus the DOM revision it was taken at.
+ *
+ * Keeping the revision beside the entry is what makes staleness *detectable*
+ * rather than a documented obligation. The cache is keyed on the document, and
+ * group edits are applied as live patches precisely so the iframe never
+ * reloads, so the key alone never changes: an explicit "remember to invalidate"
+ * contract silently rots the first time a new writer forgets — which is exactly
+ * what happened with the FX rack, whose group writes go through the DOM editor
+ * rather than the timeline's own writers.
+ */
+const groupInfoCache = new WeakMap<
+  Document,
+  { revision: number; entries: Map<string, GroupInfo> }
+>();
+
+/** Bumped by every observed mutation to group state in a document. */
+const groupRevisions = new WeakMap<Document, number>();
+const groupObservers = new WeakSet<Document>();
+
+/**
+ * Watch a document for any change to group state, so the cache expires itself.
+ *
+ * One observer per document, attached the first time a group is read from it.
+ * It watches the attributes a group's identity is made of, anywhere in the
+ * tree, plus added/removed nodes — which covers a group element appearing, a
+ * member joining or leaving, and any group attribute being edited, by any
+ * writer, without that writer having to know this cache exists.
+ */
+function observeGroupState(doc: Document): void {
+  if (groupObservers.has(doc) || typeof MutationObserver === "undefined" || !doc.body) return;
+  groupObservers.add(doc);
+  const observer = new MutationObserver((records) => {
+    // `childList` fires for EVERY node added or removed anywhere in the live
+    // preview, which on a composition that churns nodes during playback
+    // (SplitText, a typewriter, anything runtime-inserted) would expire this
+    // cache permanently and put it back to one whole-tree scan per parse. Only
+    // a group ELEMENT appearing or leaving actually changes the answer, so
+    // childList records are filtered rather than trusted; attribute records
+    // always count, because the filter below already narrowed them.
+    const relevant = records.some(
+      (record) =>
+        record.type !== "childList" ||
+        [...record.addedNodes, ...record.removedNodes].some(
+          (node) =>
+            node instanceof Element &&
+            (node.tagName.toLowerCase() === HF_AUDIO_GROUP_TAG ||
+              node.hasAttribute(HF_AUDIO_GROUP_ATTR) ||
+              node.querySelector?.(`${HF_AUDIO_GROUP_TAG},[${HF_AUDIO_GROUP_ATTR}]`) != null),
+        ),
+    );
+    if (relevant) groupRevisions.set(doc, (groupRevisions.get(doc) ?? 0) + 1);
+  });
+  observer.observe(doc.body, {
+    subtree: true,
+    childList: true,
+    attributes: true,
+    // Every attribute `resolveAudioGroups`/`buildGroup` reads, including
+    // `data-automation` — which `GroupInfo` does not cache TODAY, so omitting it
+    // was inert, but group automation lanes already exist and the first person
+    // to cache one would have got a silently never-firing observer. That is the
+    // precise rot this observer replaced.
+    attributeFilter: [
+      HF_AUDIO_GROUP_ATTR,
+      HF_AUDIO_FX_ATTR,
+      HF_AUDIO_AUTOMATION_ATTR,
+      "data-label",
+      "data-volume",
+      "data-hidden",
+      "id",
+    ],
+  });
+}
+
+/**
+ * Drop the cached group scan for a document.
+ *
+ * Belt to the observer's braces: a caller that has just written and wants the
+ * very next read to be honest cannot wait for the observer's microtask. Callers
+ * that forget are no longer punished — the revision check catches them.
+ */
+export function invalidateGroupInfoCache(doc: Document | null | undefined): void {
+  if (doc) groupInfoCache.delete(doc);
+}
+
+export function groupInfoFor(doc: Document | null | undefined, groupId: string): GroupInfo {
+  if (!doc) return { label: groupId, volume: 1, hidden: false };
+  observeGroupState(doc);
+  const revision = groupRevisions.get(doc) ?? 0;
+  const cached = groupInfoCache.get(doc);
+  let info = cached && cached.revision === revision ? cached.entries : undefined;
+  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 } : {}),
+          ...(group.automation ? { automation: group.automation } : {}),
+        },
+      ]),
+    );
+    groupInfoCache.set(doc, { revision, entries: info });
+  }
+  return info.get(groupId) ?? { label: groupId, volume: 1, hidden: false };
+}

package/src/player/lib/timelineIframeHelpers.test.ts

@@ -1,6 +1,7 @@
 // @vitest-environment jsdom
 import { describe, expect, it, vi } from "vitest";
 import {
+  applyPreviewAudioFlags,
   buildMissingCompositionElements,
   scrubPreviewAudio,
   setPreviewMediaVolume,
@@ -87,3 +88,23 @@ describe("scrubPreviewAudio", () => {
     stopScrubPreviewAudio();
   });
 });
+
+describe("applyPreviewAudioFlags", () => {
+  // Everything pushed here is state the runtime loses on reload and nothing else
+  // re-sends, so the push has to carry all of it every time. Volume in
+  // particular: the transport comes back at unity, so a preview the author had
+  // turned down came back loud.
+  it("re-pushes mute and volume together", () => {
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    const postMessage = vi.spyOn(iframe.contentWindow!, "postMessage");
+
+    applyPreviewAudioFlags(iframe, true, 0.4);
+
+    const actions = postMessage.mock.calls.map(
+      (call) => (call[0] as { action?: string }).action ?? "",
+    );
+    expect(actions).toContain("set-muted");
+    expect(actions).toContain("set-volume");
+  });
+});

package/src/player/lib/timelineIframeHelpers.ts

@@ -142,6 +142,23 @@ export function setPreviewMediaVolume(iframe: HTMLIFrameElement | null, volume:
   } catch {}
 }
 
+/**
+ * Everything the preview runtime has to be told about audio after it loads.
+ * Called from `applyPreviewAudioState`, which is the path that re-runs after a
+ * preview reload — the runtime comes back with the transport at its defaults
+ * and nothing else pushes them again.
+ */
+export function applyPreviewAudioFlags(
+  iframe: HTMLIFrameElement | null,
+  muted: boolean,
+  volume: number,
+): void {
+  setPreviewMediaMuted(iframe, muted);
+  // Volume too: the transport comes back at unity after a reload, so a preview
+  // the author had turned down came back loud.
+  setPreviewMediaVolume(iframe, volume);
+}
+
 export function setPreviewPlaybackRate(
   iframe: HTMLIFrameElement | null,
   playbackRate: number,

package/src/player/store/keyframeSlice.ts

@@ -34,6 +34,38 @@ export interface FocusedEaseSegment {
 
 type FocusedEaseSegmentTarget = Omit<FocusedEaseSegment, "projectId" | "sessionEpoch" | "nonce">;
 
+/**
+ * A request to reveal one automated parameter in the audio FX rack.
+ *
+ * `elementKey` is the timeline element whose rack it belongs to — a group's own
+ * id for a group lane, the clip's key otherwise — so the panel can refuse a
+ * request aimed at something it is not showing.
+ */
+export interface RevealedAudioFxTarget {
+  elementKey: string;
+  /** The lane's own `fx.<node>.<param>` / `volume` target. */
+  automationTarget: string;
+  projectId: string | null;
+  sessionEpoch: number;
+  nonce: number;
+}
+
+export type RevealedAudioFxTargetRequest = Omit<
+  RevealedAudioFxTarget,
+  "projectId" | "sessionEpoch" | "nonce"
+>;
+
+/** Whether a reveal request still belongs to what is on screen. */
+export function isRevealedAudioFxRequestCurrent(
+  request: RevealedAudioFxTarget,
+  state: TimelineSessionIdentity,
+): boolean {
+  return (
+    request.projectId === state.timelineProjectId &&
+    request.sessionEpoch === state.timelineSessionEpoch
+  );
+}
+
 interface TimelineSessionIdentity {
   timelineProjectId: string | null;
   timelineSessionEpoch: number;
@@ -63,8 +95,16 @@ export interface KeyframeSlice {
   /** Union-expand clips (keyframed clips are expanded by default on load). */
   expandClips: (ids: readonly string[]) => void;
 
-  /** Groups whose member rows the caret has shown (structural, not lanes). */
-  expandedGroupIds: Set<string>;
+  /**
+   * Groups whose member rows the caret has HIDDEN (structural, not lanes).
+   *
+   * Inverted deliberately. As an expanded-set, "not in the set" could not tell
+   * never-touched from deliberately-collapsed, so every group defaulted to
+   * collapsed — and since nothing seeds the set on create, grouping three
+   * tracks made all three vanish behind a header the user had not yet learned
+   * to open. Groups are expanded until someone closes one.
+   */
+  collapsedGroupIds: Set<string>;
   toggleGroupExpanded: (id: string) => void;
 
   /** Rows (clip id or group id) whose automation-lane rows the `∿` button opened. */
@@ -80,6 +120,19 @@ export interface KeyframeSlice {
   setFocusedEaseSegment: (target: FocusedEaseSegmentTarget) => void;
   clearFocusedEaseSegment: (nonce: number) => void;
 
+  /**
+   * "Show me this automated parameter in the rack" — raised by clicking an
+   * automation lane's label in the timeline, consumed by the property panel.
+   *
+   * Session-stamped and nonce-guarded exactly like `focusedEaseSegment`: a
+   * request outlives the click, so one made against a different project or
+   * before a reload must not reopen a rack on whatever is mounted later.
+   */
+  revealedAudioFxTarget: RevealedAudioFxTarget | null;
+  revealedAudioFxNonce: number;
+  setRevealedAudioFxTarget: (target: RevealedAudioFxTargetRequest) => void;
+  clearRevealedAudioFxTarget: (nonce: number) => void;
+
   /** Keyframe data per element id, populated from parsed GSAP animations. */
   keyframeCache: Map<string, KeyframeCacheEntry>;
   /** Unmerged source tweens per element; expanded property lanes read this, never keyframeCache. */
@@ -127,13 +180,13 @@ export function createKeyframeSlice(
         return { expandedClipIds: next };
       }),
 
-    expandedGroupIds: new Set(),
+    collapsedGroupIds: new Set(),
     toggleGroupExpanded: (id) =>
       set((state) => {
-        const next = new Set(state.expandedGroupIds);
+        const next = new Set(state.collapsedGroupIds);
         if (next.has(id)) next.delete(id);
         else next.add(id);
-        return { expandedGroupIds: next };
+        return { collapsedGroupIds: next };
       }),
 
     expandedLaneOwnerIds: new Set(),
@@ -166,6 +219,27 @@ export function createKeyframeSlice(
         state.focusedEaseSegment?.nonce === nonce ? { focusedEaseSegment: null } : state,
       ),
 
+    revealedAudioFxTarget: null,
+    revealedAudioFxNonce: 0,
+    setRevealedAudioFxTarget: (target) =>
+      set((state) => {
+        const nonce = state.revealedAudioFxNonce + 1;
+        const { timelineProjectId, timelineSessionEpoch } = getTimelineSessionIdentity();
+        return {
+          revealedAudioFxNonce: nonce,
+          revealedAudioFxTarget: {
+            ...target,
+            projectId: timelineProjectId,
+            sessionEpoch: timelineSessionEpoch,
+            nonce,
+          },
+        };
+      }),
+    clearRevealedAudioFxTarget: (nonce) =>
+      set((state) =>
+        state.revealedAudioFxTarget?.nonce === nonce ? { revealedAudioFxTarget: null } : state,
+      ),
+
     keyframeCache: new Map(),
     setKeyframeCache: (elementId, data) =>
       set((state) => {

package/src/player/store/playerStore.ts

@@ -1,4 +1,6 @@
 import { create } from "zustand";
+import { attachPlayerStoreDevHandle } from "./playerStoreDevHandle";
+import { nextSelectionSet, revealTargetsSelection } from "./playerStoreSelection";
 import type { MusicBeatAnalysis } from "@hyperframes/core/beats";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { BeatEditState } from "../../utils/beatEditing";
@@ -14,15 +16,14 @@ import {
   createAutomationSelectionSlice,
   type AutomationSelectionSlice,
 } from "./automationSelectionSlice";
+import { createEditingModeSlice, type EditingModeSlice } from "./editingModeSlice";
 import { createTimelineFocusRequest, type TimelineFocusRequest } from "./timelineFocusState";
 import { createThumbnailSlice, type ThumbnailSlice } from "./thumbnailSlice";
-import { createAudioSoloSlice, type AudioSoloSlice } from "./audioSoloSlice";
-import { createEditingModeSlice, type EditingModeSlice } from "./editingModeSlice";
 
 export type { KeyframeCacheEntry } from "./keyframeSlice";
 export { liveTime } from "./liveTime";
 
-import type { TimelineElement } from "./timelineElement";
+import type { TimelineElement, TimelineElementPatch } from "./timelineElement";
 
 export type { TimelineElement };
 export type ZoomMode = "fit" | "manual";
@@ -50,12 +51,7 @@ function resolveElementSelection(
 }
 
 interface PlayerState
-  extends
-    KeyframeSlice,
-    AutomationSelectionSlice,
-    ThumbnailSlice,
-    AudioSoloSlice,
-    EditingModeSlice {
+  extends KeyframeSlice, AutomationSelectionSlice, ThumbnailSlice, EditingModeSlice {
   isPlaying: boolean;
   currentTime: number;
   duration: number;
@@ -135,22 +131,7 @@ interface PlayerState
   setSelectedElementId: (id: string | null, options?: SelectElementOptions) => void;
   /** Move the selection anchor within an active multi-selection without collapsing it. */
   setSelectionAnchor: (id: string | null) => void;
-  updateElement: (
-    elementId: string,
-    updates: Partial<
-      Pick<
-        TimelineElement,
-        | "start"
-        | "duration"
-        | "track"
-        | "zIndex"
-        | "hasExplicitZIndex"
-        | "playbackStart"
-        | "hidden"
-        | "audioGroup"
-      >
-    >,
-  ) => void;
+  updateElement: (elementId: string, updates: TimelineElementPatch) => void;
   setZoomMode: (mode: ZoomMode) => void;
   setManualZoomPercent: (percent: number) => void;
   bumpZEditVersion: () => void;
@@ -241,6 +222,19 @@ export interface DomClipChild {
   hostId: string;
   label: string;
   stackingContextId: string;
+  /**
+   * The child's audio-group state, read off its live element during the DOM
+   * walk — the only place that sees it. A sub-composition can declare a group
+   * and its members entirely within itself, and those members never reach the
+   * flat store, so an expanded child has no twin to inherit membership from.
+   */
+  audioGroup?: string;
+  audioGroupLabel?: string;
+  audioGroupVolume?: number;
+  audioGroupHidden?: boolean;
+  audioGroupFxChain?: string;
+  /** The group element's `data-automation`, mirrored the same way. */
+  audioGroupAutomation?: string;
 }
 
 interface BeatHistoryEntry {
@@ -271,9 +265,11 @@ export function createTimelineResetState() {
     // paste through `sel.elementKey === paste.elementKey` to a stale t0.
     automationSelection: null,
     expandedClipIds: new Set<string>(),
-    expandedGroupIds: new Set<string>(),
+    // Per-composition: ids from comp A match nothing in B, silencing all of it.
+    collapsedGroupIds: new Set<string>(),
     expandedLaneOwnerIds: new Set<string>(),
     focusedEaseSegment: null,
+    revealedAudioFxTarget: null,
     selectedElementIds: new Set<string>(),
     requestedSeekTime: null,
     lintFindingsByElement: new Map<string, { count: number; messages: string[] }>(),
@@ -323,7 +319,6 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   ...createThumbnailSlice(set),
 
   ...createAutomationSelectionSlice(set),
-  ...createAudioSoloSlice(set, get),
   ...createEditingModeSlice(set),
 
   activeKeyframePct: null,
@@ -519,18 +514,23 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   // echoes that must preserve a group go through setSelectionAnchor instead.
   setSelectedElementId: (id, options) =>
     set((s) => {
-      const preserveSet = Boolean(options?.preserveSet && id && s.selectedElementIds.has(id));
-      const selectedElementIds = preserveSet
-        ? new Set(s.selectedElementIds)
-        : options?.preserveSet
-          ? new Set<string>()
-          : id
-            ? new Set([id])
-            : new Set<string>();
+      const selectedElementIds = nextSelectionSet(s.selectedElementIds, id, options?.preserveSet);
       // Selecting a different element drops any active keyframe selection — otherwise
       // a stale activeKeyframePct from a prior diamond click would force the next drag
       // to "modify" a keyframe on the new element. A diamond click sets the pct AFTER
       // calling setSelectedElementId, so this never clobbers a genuine keyframe select.
+      // A reveal request survives the selection it is FOR. `openClipFxRack`
+      // raises the request and then selects the clip asynchronously, so the
+      // selection lands afterwards and used to clear the very request that
+      // caused it — the panel then read null and the section never opened.
+      // Any OTHER selection still drops it: a request aimed elsewhere is stale.
+      //
+      // Compared across the ID-SPACE BOUNDARY, which is why this needs saying:
+      // a request carries the BARE dom id (`runtimeAudioId`, because the panel
+      // and the runtime speak that), while this store's ids are
+      // `sourceFile#domId`. A direct `===` was silently never true — the exact
+      // shape of failure the id-space split produces.
+      const revealSurvives = revealTargetsSelection(s.revealedAudioFxTarget, id);
       return id !== s.selectedElementId
         ? {
             selectedElementId: id,
@@ -538,6 +538,7 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
             activeKeyframePct: null,
             motionPathArmed: false,
             focusedEaseSegment: null,
+            ...(revealSurvives ? {} : { revealedAudioFxTarget: null }),
           }
         : { selectedElementId: id, selectedElementIds };
     }),
@@ -579,15 +580,4 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   reset: () => set(createTimelineResetState()),
 }));
 
-function isDevBuild(): boolean {
-  try {
-    return import.meta.env.DEV === true;
-  } catch {
-    // Turbopack and other non-Vite bundlers may not provide import.meta.env.
-    return false;
-  }
-}
-if (isDevBuild() && typeof window !== "undefined") {
-  // Console handle for dumping live Studio state during bug-bash reproduction.
-  (window as unknown as { __playerStore?: typeof usePlayerStore }).__playerStore = usePlayerStore;
-}
+attachPlayerStoreDevHandle(usePlayerStore);

package/src/player/store/playerStoreDevHandle.ts

@@ -0,0 +1,22 @@
+/**
+ * A console handle on the live store, dev builds only.
+ *
+ * Split out of `playerStore.ts` to keep it under the studio's 600-line cap. The
+ * dev check is its own function because `import.meta.env` is absent under
+ * Turbopack and other non-Vite bundlers, where reading it throws.
+ */
+
+function isDevBuild(): boolean {
+  try {
+    return import.meta.env.DEV === true;
+  } catch {
+    return false;
+  }
+}
+
+/** Expose `store` as `window.__playerStore` for dumping live Studio state
+ *  during bug-bash reproduction. No-op outside a dev build or a browser. */
+export function attachPlayerStoreDevHandle(store: unknown): void {
+  if (!isDevBuild() || typeof window === "undefined") return;
+  (window as unknown as { __playerStore?: unknown }).__playerStore = store;
+}

package/src/player/store/playerStoreSelection.ts

@@ -0,0 +1,41 @@
+/**
+ * Selection-set arithmetic for the player store, and the reveal request's
+ * cross-id-space match.
+ *
+ * Its own module so `playerStore.ts` stays under the studio's 600-line cap.
+ */
+
+import { splitTimelineElementKey } from "../lib/timelineElementHelpers";
+
+/**
+ * The id set a selection change leaves behind.
+ *
+ * `preserveSet` means "keep the multi-selection if this id is already in it" —
+ * a DOM→store echo re-announcing a member must not collapse the set — and
+ * anything else is a genuine single selection.
+ */
+export function nextSelectionSet(
+  current: ReadonlySet<string>,
+  id: string | null,
+  preserveSet: boolean | undefined,
+): Set<string> {
+  if (preserveSet) return id && current.has(id) ? new Set(current) : new Set<string>();
+  return id ? new Set([id]) : new Set<string>();
+}
+
+/**
+ * Is a pending reveal request aimed at the element being selected?
+ *
+ * Compared across the ID-SPACE BOUNDARY, which is why it is a named function:
+ * a request carries the BARE dom id (`runtimeAudioId` — the panel and the
+ * runtime speak that), while the store's ids are `sourceFile#domId`. A direct
+ * `===` between the two is silently never true, which is the exact shape of
+ * failure the split produces and how the reveal came to be dead.
+ */
+export function revealTargetsSelection(
+  request: { elementKey: string } | null,
+  id: string | null,
+): boolean {
+  if (!request || id === null) return false;
+  return request.elementKey === splitTimelineElementKey(id).domId;
+}