@hyperframes/studio 0.8.48 → 0.8.50

package/src/player/hooks/useTimelineSyncCallbacks.emptyManifest.test.tsx

@@ -0,0 +1,41 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { useTimelineSyncCallbacks } from "./useTimelineSyncCallbacks";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+describe("processTimelineMessage with an empty manifest", () => {
+  it("commits zero rows without adopting the runtime 1s floor as the duration", () => {
+    const sync = vi.fn<(els: TimelineElement[], duration?: number) => void>();
+    let processTimelineMessage: ReturnType<
+      typeof useTimelineSyncCallbacks
+    >["processTimelineMessage"];
+    function Harness() {
+      ({ processTimelineMessage } = useTimelineSyncCallbacks({
+        iframeRef: { current: null },
+        probeIntervalRef: { current: undefined },
+        pendingSeekRef: { current: null },
+        isRefreshingRef: { current: false },
+        getAdapter: () => null,
+        syncTimelineElements: sync,
+        setDuration: () => {},
+        setCurrentTime: () => {},
+        requestTimelineReady: () => {},
+        setIsPlaying: () => {},
+        attachIframeShortcutListeners: () => {},
+        applyPreviewAudioState: () => {},
+      }));
+      return null;
+    }
+    const host = document.createElement("div");
+    act(() => createRoot(host).render(<Harness />));
+
+    processTimelineMessage!({ clips: [], durationInFrames: 30 });
+
+    expect(sync).toHaveBeenCalledWith([], undefined);
+  });
+});

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -17,7 +17,9 @@ import { buildMissingCompositionElements } from "../lib/timelineIframeHelpers";
 import { acceptedRuntimeMessageFps } from "../lib/runtimeProtocol";
 import {
   buildTimelineElementsFromClips,
+  syncManifestTimeline,
   clipTreeParentMap,
+  collectTopLevelElementIds,
   collectSubCompositionDomChildren,
   collectSubCompositionHostState,
   hydrateTimelineFromPreview,
@@ -26,7 +28,6 @@ import {
   sanitizeDurationSeconds,
   seekAdapterToRestorePoint,
   syncAdapterDuration,
-  withImplicitDomLayers,
   type RuntimeTimelineMessage,
 } from "./timelineSyncHydration";
 
@@ -114,9 +115,7 @@ export function useTimelineSyncCallbacks({
   // Convert a runtime timeline message (from iframe postMessage) into TimelineElements
   const processTimelineMessage = useCallback(
     (data: RuntimeTimelineMessage) => {
-      if (!data.clips || data.clips.length === 0) {
-        return;
-      }
+      if (!data.clips) return;
 
       usePlayerStore.getState().setClipManifest(data.clips);
 
@@ -131,11 +130,13 @@ export function useTimelineSyncCallbacks({
         const parentMap = clipTreeParentMap(iframeRef.current?.contentWindow ?? null);
         const domClipChildren = collectSubCompositionDomChildren(iframeDoc, data.clips, parentMap);
         usePlayerStore.getState().setClipParentMap(parentMap);
+        usePlayerStore.getState().setTopLevelIds(collectTopLevelElementIds(iframeDoc));
         usePlayerStore.getState().setDomClipChildren(domClipChildren);
         usePlayerStore
           .getState()
           .setSubCompositionHostState(collectSubCompositionHostState(iframeDoc, data.clips));
       } catch {
+        usePlayerStore.getState().setTopLevelIds(null);
         // cross-origin or __clipTree not available — maps stay empty
       }
 
@@ -150,14 +151,12 @@ export function useTimelineSyncCallbacks({
         manifestDurationSeconds: data.durationInFrames / acceptedRuntimeMessageFps(data),
         authoredRootDurationSeconds: readTimelineDurationFromDocument(iframeDoc),
       });
-      const timelineEls = withImplicitDomLayers(
+      syncManifestTimeline(
         els,
-        iframeDoc,
-        newDuration > 0 ? newDuration : usePlayerStore.getState().duration,
+        newDuration,
+        usePlayerStore.getState().duration,
+        syncTimelineElements,
       );
-      if (timelineEls.length > 0) {
-        syncTimelineElements(timelineEls, newDuration > 0 ? newDuration : undefined);
-      }
     },
     [iframeRef, syncTimelineElements],
   );

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

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/timelineElement";
+import { describeClips, formatTimelineBlock } from "./describeClips";
+
+function audio(id: string, start: number, duration: number, extra: Partial<TimelineElement> = {}) {
+  return {
+    id,
+    domId: id,
+    tag: "audio",
+    kind: "audio",
+    start,
+    duration,
+    track: 0,
+    ...extra,
+  } satisfies TimelineElement;
+}
+
+// Shaped like claude-paper-launch: two voiceovers, clicks, and dozens of keystroke sounds, each on its own track.
+function paperLaunchClips(): TimelineElement[] {
+  const clips = [
+    audio("vo", 29.6, 2.17, { src: "voiceover.mp3", authoredTrack: 8, volume: 0.009772 }),
+    audio("sfx-click-0", 1.6, 0.07, { src: "click.mp3", authoredTrack: 100, volume: 0.85 }),
+    audio("sfx-type-0", 7.8, 0.57, { src: "typenew.mp3", authoredTrack: 187, volume: 0.2 }),
+  ];
+  for (let i = 1; i <= 84; i++) {
+    clips.push(audio(`sfx-extra-${i}`, 8 + i * 0.1, 0.5, { authoredTrack: 200 + i, volume: 0.2 }));
+  }
+  return clips;
+}
+
+describe("formatTimelineBlock", () => {
+  it("lists every audio clip with its start and volume", () => {
+    const block = formatTimelineBlock(paperLaunchClips());
+    const audioLines = block.split("\n").filter((line) => line.startsWith("- audio "));
+    expect(audioLines).toHaveLength(87);
+    expect(
+      audioLines.every((line) => /start=[\d.]+/.test(line) && /volume=[\d.]+/.test(line)),
+    ).toBe(true);
+    expect(block).toContain(
+      '- audio "sfx-click-0" src=click.mp3 start=1.6 duration=0.07 end=1.67 track=100 volume=0.85',
+    );
+    expect(block).toContain(
+      '- audio "vo" src=voiceover.mp3 start=29.6 duration=2.17 end=31.77 track=8 volume=0.01',
+    );
+  });
+
+  it("orders clips by start time", () => {
+    const lines = formatTimelineBlock(paperLaunchClips()).split("\n");
+    expect(lines[1]).toContain('"sfx-click-0"');
+  });
+
+  it("prints volume automation points, rate and group", () => {
+    const block = formatTimelineBlock([
+      audio("bed", 8, 20, {
+        automation:
+          '{"version":1,"lanes":[{"target":"volume","points":[{"t":0,"v":0.1},{"t":10,"v":0.5}]}]}',
+        playbackRate: 0.5,
+        audioGroup: "music",
+        timelineRole: "music",
+      }),
+    ]);
+    expect(block).toContain("rate=0.5 group=music role=music volume-lane=[0:0.1, 10:0.5]");
+  });
+
+  it("prints volume 0 and a project-relative src, and omits rate at normal speed", () => {
+    const block = formatTimelineBlock([
+      audio("mute", 0, 1, {
+        src: "http://localhost:5190/api/projects/p1/preview/assets/a.mp3",
+        volume: 0,
+        playbackRate: 1,
+      }),
+    ]);
+    expect(block).toContain(
+      '- audio "mute" src=assets/a.mp3 start=0 duration=1 end=1 track=0 volume=0',
+    );
+    expect(block).not.toContain("rate=");
+  });
+
+  it("is empty for an empty timeline and caps long ones", () => {
+    expect(formatTimelineBlock([])).toBe("");
+    const many = Array.from({ length: 250 }, (_, i) => audio(`a${i}`, i, 1));
+    expect(formatTimelineBlock(many)).toContain("(50 more clips not listed)");
+  });
+});
+
+describe("describeClips", () => {
+  it("keeps 'not authored' distinct from zero for volume and rate", () => {
+    const [plain, silent] = describeClips([
+      audio("a", 0, 1),
+      audio("b", 1, 1, { volume: 0, playbackRate: 0 }),
+    ]);
+    expect([plain?.volume, plain?.playbackRate]).toEqual([null, null]);
+    expect([silent?.volume, silent?.playbackRate]).toEqual([0, 0]);
+  });
+});

package/src/player/lib/describeClips.ts

@@ -0,0 +1,103 @@
+/** Plain-field clip facts from the player store; feeds the Ask-agent prompt and `studio_look`. */
+import type { TimelineElement } from "../store/playerStore";
+import { elementAutomationLanes } from "../components/automationLaneData";
+import { roundTo3 } from "../../utils/rounding";
+
+export interface ClipLane {
+  /** `volume`, or `fx.<nodeId>.<param>`. */
+  target: string;
+  /** `t` is seconds from the start of the clip, not the composition. */
+  points: { t: number; v: number }[];
+}
+
+export interface ClipFact {
+  id: string;
+  label: string | null;
+  kind: string;
+  start: number;
+  duration: number;
+  end: number;
+  /** The `data-track-index` as written in the source file. */
+  trackIndex: number;
+  src: string | null;
+  sourceFile: string | null;
+  /** `null` when `data-volume` is not authored (the clip plays at 1). */
+  volume: number | null;
+  lanes: ClipLane[];
+  /** `null` at normal speed: not authored, or 1 (the manifest defaults it to 1). */
+  playbackRate: number | null;
+  audioGroup: string | null;
+  role: string | null;
+}
+
+/** The store holds preview URLs; the agent edits project files, so drop the origin and preview prefix. */
+function projectRelativeSrc(src: string): string {
+  return src.replace(/^https?:\/\/[^/]+/, "").replace(/^\/api\/projects\/[^/]+\/preview\//, "");
+}
+
+export function describeClip(element: TimelineElement): ClipFact {
+  return {
+    id: element.domId ?? element.id,
+    label: element.label ?? null,
+    kind: element.kind ?? element.tag.toLowerCase(),
+    start: element.start,
+    duration: element.duration,
+    end: element.start + element.duration,
+    trackIndex: element.authoredTrack ?? element.track,
+    src: element.src ? projectRelativeSrc(element.src) : null,
+    sourceFile: element.sourceFile ?? null,
+    volume: element.volume ?? null,
+    lanes: elementAutomationLanes(element).map((lane) => ({
+      target: lane.target,
+      points: lane.points.map(({ t, v }) => ({ t, v })),
+    })),
+    playbackRate: element.playbackRate === 1 ? null : (element.playbackRate ?? null),
+    audioGroup: element.audioGroup ?? null,
+    role: element.timelineRole ?? null,
+  };
+}
+
+export const byStart = (a: ClipFact, b: ClipFact) =>
+  a.start - b.start || a.trackIndex - b.trackIndex;
+
+export function describeClips(elements: readonly TimelineElement[]): ClipFact[] {
+  return elements.map(describeClip).sort(byStart);
+}
+
+const num = (n: number) => String(roundTo3(n));
+
+function formatClipLine(clip: ClipFact): string {
+  const parts = [
+    `${clip.kind} "${clip.id}"`,
+    clip.src && `src=${clip.src}`,
+    `start=${num(clip.start)}`,
+    `duration=${num(clip.duration)}`,
+    `end=${num(clip.end)}`,
+    `track=${clip.trackIndex}`,
+    clip.volume !== null && `volume=${num(clip.volume)}`,
+    clip.playbackRate !== null && `rate=${num(clip.playbackRate)}`,
+    clip.audioGroup && `group=${clip.audioGroup}`,
+    clip.role && `role=${clip.role}`,
+    clip.sourceFile && `file=${clip.sourceFile}`,
+    ...clip.lanes.map(
+      (lane) =>
+        `${lane.target}-lane=[${lane.points.map((p) => `${num(p.t)}:${num(p.v)}`).join(", ")}]`,
+    ),
+  ];
+  return `- ${parts.filter(Boolean).join(" ")}`;
+}
+
+const PROMPT_CLIP_CAP = 200;
+
+/** The Ask-agent prompt's Timeline block; empty when the timeline has no clips. */
+export function formatTimelineBlock(elements: readonly TimelineElement[]): string {
+  const clips = describeClips(elements);
+  if (clips.length === 0) return "";
+  const shown = clips.slice(0, PROMPT_CLIP_CAP).map(formatClipLine);
+  const more = clips.length - shown.length;
+  return [
+    "Timeline (composition seconds; lane points are seconds from the clip start):",
+    ...shown,
+    ...(more > 0 ? [`(${more} more clips not listed)`] : []),
+  ].join("\n");
+}

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

@@ -3,7 +3,6 @@ import { describe, expect, it } from "vitest";
 import {
   createTimelineElementFromManifestClip,
   parseTimelineFromDOM,
-  createImplicitTimelineLayersFromDOM,
   mergeTimelineElementsPreservingDowngrades,
 } from "./timelineDOM";
 import { isTimelineIgnoredElement } from "./timelineElementHelpers";
@@ -302,19 +301,6 @@ describe("createTimelineElementFromManifestClip — source-scoped selector ident
 // 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);
@@ -322,72 +308,6 @@ describe("<hf-audio-group> is not a timeline layer", () => {
   });
 });
 
-describe("createImplicitTimelineLayersFromDOM — hfId from data-hf-id", () => {
-  it("uses the runtime root paint scope for implicit siblings of manifest clips", () => {
-    const doc = makeDoc(`
-      <div data-composition-id="root">
-        <div id="timed" data-start="0" data-duration="5"></div>
-        <div id="implicit"></div>
-      </div>
-    `);
-    const timedHost = doc.getElementById("timed");
-    const timed = createTimelineElementFromManifestClip({
-      clip: {
-        id: "timed",
-        label: "Timed",
-        start: 0,
-        duration: 5,
-        track: 0,
-        stackingContextId: "css:root",
-        kind: "element",
-        tagName: "div",
-        compositionId: null,
-        parentCompositionId: null,
-        compositionSrc: null,
-        assetUrl: null,
-      },
-      fallbackIndex: 0,
-      doc,
-      hostEl: timedHost,
-    });
-    const implicit = createImplicitTimelineLayersFromDOM(doc, 5, [timed])[0];
-
-    expect(implicit?.stackingContextId).toBe("css:root");
-    expect(implicit?.stackingContextId).toBe(timed.stackingContextId);
-  });
-
-  it("harvests hfId from an implicit layer child that has data-hf-id", () => {
-    const doc = makeDoc(`
-      <div data-composition-id="root">
-        <div id="layer" class="clip" data-hf-id="hf-xyz789"></div>
-      </div>
-    `);
-
-    const layers = createImplicitTimelineLayersFromDOM(doc, 10);
-    const layer = layers.find((el) => el.domId === "layer");
-
-    expect(layer).toBeDefined();
-    expect(layer?.hfId).toBe("hf-xyz789");
-  });
-
-  it("ignores runtime-owned color grading canvases as implicit layers", () => {
-    const doc = makeDoc(`
-      <div data-composition-id="root" data-duration="5">
-        <img id="photo" class="clip" data-start="0" data-duration="5" />
-        <canvas
-          class="__hf_color_grading_canvas__"
-          data-hf-color-grading-canvas="true"
-          data-hyperframes-ignore
-        ></canvas>
-      </div>
-    `);
-
-    const layers = createImplicitTimelineLayersFromDOM(doc, 5);
-
-    expect(layers).toEqual([]);
-  });
-});
-
 describe("mergeTimelineElementsPreservingDowngrades — genuine removal vs transient downgrade", () => {
   it("drops a removed TOP-LEVEL element (undo of a split) instead of ghosting it", () => {
     const current = [el("a"), el("a-split")]; // post-split store: original + clone

package/src/player/lib/timelineDOM.ts

@@ -17,8 +17,6 @@ import {
   resolveMediaElement,
   applyMediaMetadataFromElement,
   getTimelineElementDisplayLabel,
-  getImplicitTimelineLayerLabel,
-  isImplicitTimelineLayerCandidate,
   getTimelineElementSelector,
   getTimelineElementSourceFile,
   getTimelineElementSelectorIndex,
@@ -203,63 +201,6 @@ export function createTimelineElementFromManifestClip(params: {
   return entry;
 }
 
-export function createImplicitTimelineLayersFromDOM(
-  doc: Document,
-  rootDuration: number,
-  existingElements: readonly TimelineElement[] = [],
-): TimelineElement[] {
-  if (!Number.isFinite(rootDuration) || rootDuration <= 0) return [];
-  const rootComp = doc.querySelector("[data-composition-id]");
-  if (!rootComp) return [];
-
-  const existingKeys = new Set(existingElements.map(getTimelineElementIdentity));
-  const maxTrack = existingElements.reduce(
-    (max, element) => Math.max(max, Number.isFinite(element.track) ? element.track : 0),
-    -1,
-  );
-  const layers: TimelineElement[] = [];
-
-  for (const child of Array.from(rootComp.children)) {
-    if (!isImplicitTimelineLayerCandidate(rootComp, child)) continue;
-
-    const selector = getTimelineElementSelector(child);
-    if (!selector) continue;
-    const selectorIndex = getTimelineElementSelectorIndex(doc, child, selector);
-    const sourceFile = getTimelineElementSourceFile(child);
-    const label = getImplicitTimelineLayerLabel(child);
-    const identity = buildTimelineElementIdentity({
-      preferredId: child.id || null,
-      label,
-      fallbackIndex: existingElements.length + layers.length,
-      domId: child.id || undefined,
-      selector,
-      selectorIndex,
-      sourceFile,
-    });
-    if (existingKeys.has(identity.key) || existingKeys.has(identity.id)) continue;
-
-    layers.push({
-      domId: child.id || undefined,
-      hfId: child.getAttribute("data-hf-id") || undefined,
-      zIndex: readTimelineElementZIndex(child),
-      duration: rootDuration,
-      id: identity.id,
-      key: identity.key,
-      label,
-      selector,
-      selectorIndex,
-      sourceFile,
-      stackingContextId: resolveCssStackingContextId(child),
-      start: 0,
-      tag: child.tagName.toLowerCase(),
-      timingSource: "implicit",
-      track: maxTrack + 1 + layers.length,
-    });
-  }
-
-  return layers;
-}
-
 /**
  * Parse [data-start] elements from a Document into TimelineElement[].
  * Shared helper — used by onIframeLoad fallback, handleMessage, and enrichMissingCompositions.
@@ -330,7 +271,6 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
       selectorIndex,
       sourceFile,
       stackingContextId: resolveCssStackingContextId(el),
-      timingSource: "authored",
       zIndex: readTimelineElementZIndex(el),
     };
 
@@ -399,7 +339,7 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
     els.push(entry);
   });
 
-  return [...els, ...createImplicitTimelineLayersFromDOM(doc, rootDuration, els)];
+  return els;
 }
 
 // ---------------------------------------------------------------------------

package/src/player/lib/timelineElementHelpers.ts

@@ -2,7 +2,7 @@
  * Low-level helpers for building and identifying TimelineElement objects.
  *
  * Covers: duration reading, media-element metadata extraction, selector/key/
- * identity builders, DOM node lookup, and implicit layer detection. These are
+ * identity builders, and DOM node lookup. These are
  * intentionally dependency-free (no store, no hooks) so they can be used in
  * both the React hook and test environments.
  */
@@ -82,13 +82,7 @@ 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.
+  // An `<hf-audio-group>` is a mixer bus with no timing of its own, drawn as a group row, never a clip.
   if (el.tagName.toLowerCase() === HF_AUDIO_GROUP_TAG) return true;
   return Boolean(
     el.closest(
@@ -223,37 +217,6 @@ export function getTimelineElementDisplayLabel(input: {
   return tag ? `${tag} clip` : "Timeline clip";
 }
 
-const IMPLICIT_TIMELINE_LAYER_SKIP_TAGS = new Set([
-  "base",
-  "link",
-  "meta",
-  "noscript",
-  "script",
-  "style",
-  "template",
-]);
-
-function humanizeTimelineIdentifier(value: string): string {
-  return value
-    .trim()
-    .replace(/[_-]+/g, " ")
-    .replace(/\s+/g, " ")
-    .replace(/\b\w/g, (match) => match.toUpperCase());
-}
-
-export function getImplicitTimelineLayerLabel(el: HTMLElement): string {
-  const explicitLabel =
-    el.getAttribute("data-timeline-label") ??
-    el.getAttribute("data-label") ??
-    el.getAttribute("aria-label");
-  if (explicitLabel?.trim()) return explicitLabel.trim();
-  if (el.id.trim()) return humanizeTimelineIdentifier(el.id);
-  const classes = el.className.split(/\s+/).filter(Boolean);
-  const className = classes.find((value) => value !== "clip") ?? classes[0];
-  if (className) return humanizeTimelineIdentifier(className);
-  return getTimelineElementDisplayLabel({ tag: el.tagName });
-}
-
 // ---------------------------------------------------------------------------
 // Selector / identity / key builders
 // ---------------------------------------------------------------------------
@@ -392,6 +355,14 @@ export function deriveTimelineStoreKey(params: {
   return buildTimelineElementKey({ id: "", fallbackIndex: 0, ...params });
 }
 
+/**
+ * {@link deriveTimelineStoreKey} for a caller that already has a DOM id in
+ * hand (e.g. one it just minted), so the undefined branch never applies.
+ */
+export function deriveTimelineStoreKeyForDomId(domId: string, sourceFile?: string): string {
+  return deriveTimelineStoreKey({ domId, sourceFile })!;
+}
+
 // ---------------------------------------------------------------------------
 // DOM node querying
 // ---------------------------------------------------------------------------
@@ -467,17 +438,3 @@ export function createTimelineDomNodeResolver(doc: Document) {
     return node;
   };
 }
-
-// ---------------------------------------------------------------------------
-// Implicit layer detection
-// ---------------------------------------------------------------------------
-
-export function isImplicitTimelineLayerCandidate(root: Element, el: Element): el is HTMLElement {
-  if (!isHtmlElement(el)) return false;
-  if (isTimelineIgnoredElement(el)) return false;
-  if (el.parentElement !== root) return false;
-  const tagName = el.tagName.toLowerCase();
-  if (IMPLICIT_TIMELINE_LAYER_SKIP_TAGS.has(tagName)) return false;
-  if (el.hasAttribute("data-start") || el.hasAttribute("data-track-index")) return false;
-  return Boolean(getTimelineElementSelector(el));
-}

package/src/player/store/playerStore.ts

@@ -200,6 +200,8 @@ interface PlayerState extends PlayerStoreSlices {
   clipManifest: ClipManifestClip[] | null;
   setClipManifest: (clips: ClipManifestClip[] | null) => void;
   clipParentMap: Map<string, string>;
+  topLevelIds: ReadonlySet<string> | null;
+  setTopLevelIds: (ids: ReadonlySet<string> | null) => void;
   setClipParentMap: (map: Map<string, string>) => void;
   /**
    * Sub-composition DOM descendants (groups + their children) that have no
@@ -288,6 +290,7 @@ export function createTimelineResetState() {
     beatPersist: null,
     clipManifest: null,
     clipParentMap: new Map<string, string>(),
+    topLevelIds: null,
     domClipChildren: [],
     subCompositionHostState: new Map<string, SubCompositionHostState>(),
   };
@@ -434,6 +437,8 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   setClipManifest: (clips) => set({ clipManifest: clips }),
   clipParentMap: new Map(),
   setClipParentMap: (map) => set({ clipParentMap: map }),
+  topLevelIds: null,
+  setTopLevelIds: (ids) => set({ topLevelIds: ids }),
   domClipChildren: [],
   setDomClipChildren: (children) => set({ domClipChildren: children }),
   subCompositionHostState: new Map(),

package/src/player/store/readinessSlice.ts

@@ -1,7 +1,8 @@
 /** Gates `timelineReady` on the composition's declared readiness inputs
- * (media, for now) instead of just a known duration. The generation counter
- * is module-scope, not store state: it guards an in-flight settlement, not
- * something a component reads, so bumping it shouldn't trigger a render. */
+ * (media, compute, and the paint-and-idle default) instead of just a known
+ * duration. The generation counter is module-scope, not store state: it
+ * guards an in-flight settlement, not something a component reads, so
+ * bumping it shouldn't trigger a render. */
 import type { StoreApi } from "zustand";
 import { settleCompositionReadiness } from "@hyperframes/core/composition-readiness";
 

package/src/player/store/timelineElement.ts

@@ -59,8 +59,6 @@ export interface TimelineElement {
   automation?: string;
   /** Path from data-composition-src — identifies sub-composition elements */
   compositionSrc?: string;
-  /** Whether this row came from authored clip timing or Studio's full-duration layer fallback. */
-  timingSource?: "authored" | "implicit";
   /** Set by data-timeline-locked on the host element — disables move and trim in Studio. */
   timelineLocked?: boolean;
   /** Set by data-hidden on the host element — hides the clip in preview and render. */
@@ -79,7 +77,7 @@ export interface TimelineElement {
   audioGroupFxChain?: string;
   audioGroupAutomation?: string;
   /**
-   * Set by useExpandedTimelineElements on an inline-expanded sub-composition
+   * Set by useTimelineRowElements on an inline-expanded sub-composition
    * child: the absolute master-timeline start of the sub-comp host the child
    * lives in. Presence marks the element as expanded; edits subtract it to get
    * the child's local (sourceFile-relative) time. Works at any nesting depth.