@hyperframes/studio 0.8.49 → 0.8.50

package/src/player/components/timelineTrackPersistPipeline.test.ts

@@ -2,7 +2,6 @@ import { describe, expect, it, vi } from "vitest";
 import type { TimelineElement } from "../store/playerStore";
 import type { ClipManifestClip } from "../lib/playbackTypes";
 import { createTimelineElementFromManifestClip } from "../lib/timelineDOM";
-import { buildExpandedElements } from "../hooks/useExpandedTimelineElements";
 import { normalizeToZones } from "./timelineZones";
 import { commitDraggedClipMove, type TimelineMoveEdit } from "./timelineClipDragCommit";
 import type { DraggedClipState } from "./useTimelineClipDrag";
@@ -113,56 +112,4 @@ describe("track persist pipeline (manifest → factory → lanes → drag commit
     const up = commitLaneChange(byId.get("g")!, 0, elements, [0, 1, 2]);
     expect(up[0].updates.track).toBe(3); // authored, NOT display lane 0
   });
-
-  it("an expanded sub-comp child's lane change persists the sibling's authored track from ITS file", () => {
-    // Host timeline: the sub-comp host plus a root clip, discovered through the
-    // factory and lane-normalized like the store does.
-    const hostManifest = [
-      manifestClip({
-        id: "scene",
-        kind: "composition",
-        tagName: "div",
-        track: 0,
-        start: 0,
-        duration: 10,
-        compositionId: "scene",
-        compositionSrc: "scene.html",
-      }),
-      manifestClip({ id: "root-clip", kind: "video", tagName: "video", track: 1, start: 0 }),
-    ];
-    // scene.html has SPARSE authored tracks 3 and 7.
-    const childClips = [
-      manifestClip({ id: "c3", track: 3, start: 1, duration: 2, parentCompositionId: "scene" }),
-      manifestClip({ id: "c7", track: 7, start: 4, duration: 2, parentCompositionId: "scene" }),
-    ];
-    const storeElements = normalizeToZones(fromManifest(hostManifest));
-    const parentMap = new Map([
-      ["c3", "scene"],
-      ["c7", "scene"],
-    ]);
-    const expanded = buildExpandedElements(
-      storeElements,
-      [...hostManifest, ...childClips],
-      parentMap,
-      "scene",
-      "scene",
-    );
-
-    // The children replaced the host row: synthetic display lanes, but the
-    // authored track (in scene.html's coordinate space) survived the expansion.
-    const c3 = expanded.find((e) => e.domId === "c3")!;
-    const c7 = expanded.find((e) => e.domId === "c7")!;
-    expect(c3).toMatchObject({ authoredTrack: 3, sourceFile: "scene.html" });
-    expect(c7).toMatchObject({ authoredTrack: 7, sourceFile: "scene.html" });
-    expect(c3.stackingContextId).toBe("root");
-    expect(c3.track).not.toBe(3); // display row is synthetic
-
-    // Drag c3 onto c7's display lane: the persist target is c3's OWN file, so
-    // the written track must be c7's authored 7 — not the display-lane integer.
-    const trackOrder = [...new Set(expanded.map((e) => e.track))].sort((a, b) => a - b);
-    const edits = commitLaneChange(c3, c7.track, expanded, trackOrder);
-    expect(edits).toHaveLength(1);
-    expect(edits[0].updates.track).toBe(7);
-    expect(edits[0].updates.track).not.toBe(c7.track);
-  });
 });

package/src/player/components/useTimelineClipContextMenu.ts

@@ -0,0 +1,32 @@
+import { useCallback } from "react";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import type { ClipContextMenuState } from "./TimelineOverlays";
+
+/** A clicked member of an active multi-selection keeps the whole group
+ *  selected, so the context menu it opens acts on all of it. */
+export function useClipContextMenu(
+  onSelectElement: ((element: TimelineElement | null) => void) | undefined,
+  dismissGapMenu: () => void,
+  setClipContextMenu: (state: ClipContextMenuState | null) => void,
+) {
+  const selectedElementIds = usePlayerStore((s) => s.selectedElementIds);
+  const setSelectedElementId = usePlayerStore((s) => s.setSelectedElementId);
+  return useCallback(
+    (e: React.MouseEvent, el: TimelineElement) => {
+      e.preventDefault();
+      const id = el.key ?? el.id;
+      if (!(selectedElementIds.size > 1 && selectedElementIds.has(id))) {
+        setSelectedElementId(id);
+        onSelectElement?.(el);
+      }
+      dismissGapMenu();
+      setClipContextMenu({
+        x: e.clientX,
+        y: e.clientY,
+        element: el,
+        sessionEpoch: usePlayerStore.getState().timelineSessionEpoch,
+      });
+    },
+    [selectedElementIds, setSelectedElementId, onSelectElement, dismissGapMenu, setClipContextMenu],
+  );
+}

package/src/player/components/useTimelineTrackDerivations.ts

@@ -98,7 +98,7 @@ function buildGroupInfo(
     id: groupId,
     label: membership.labelByGroup.get(groupId) ?? groupId,
     // Exactly x.5, which sub-composition child rows are now kept strictly below
-    // (`useExpandedTimelineElements`) — they used to be able to land here and
+    // (`useTimelineRowElements`) — they used to be able to land here and
     // collide, duplicating the group header.
     anchorKey: (memberTracks[0] ?? fallbackTrackNum) - 0.5,
     memberTracks,

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

@@ -73,9 +73,6 @@ describe("live DOM manifest hydration", () => {
       canTrimEnd: true,
     });
     expect(getTimelineEditCapabilities({ ...input, timelineLocked: true }).canMove).toBe(false);
-    expect(getTimelineEditCapabilities({ ...input, timingSource: "implicit" }).canTrimEnd).toBe(
-      false,
-    );
   });
   it("uses at most one fallback candidate snapshot per hydration pass", () => {
     const doc = documentWith(

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

@@ -3,6 +3,7 @@
 import { describe, expect, it } from "vitest";
 import {
   collectSubCompositionDomChildren,
+  collectTopLevelElementIds,
   collectSubCompositionHostState,
 } from "./timelineSyncHydration";
 import type { ClipManifestClip } from "../lib/playbackTypes";
@@ -94,3 +95,20 @@ describe("collectSubCompositionHostState", () => {
     expect(state.size).toBe(0);
   });
 });
+
+describe("collectTopLevelElementIds", () => {
+  const docOf = (html: string) => new DOMParser().parseFromString(html, "text/html");
+
+  it("names the sub-composition host and a timed element, not what is nested inside them", () => {
+    const doc = docOf(`<div data-composition-id="root">
+      <div id="wrap"><div id="a" data-start="0" data-duration="2"><div id="inner" data-start="0"></div></div></div>
+      <div id="scene" data-composition-id="scene" data-composition-src="scene.html"><div id="box" data-start="0"></div></div>
+    </div>`);
+    expect([...collectTopLevelElementIds(doc)!].sort()).toEqual(["a", "scene"]);
+  });
+
+  it("is null when the document has no composition root", () => {
+    expect(collectTopLevelElementIds(docOf("<p>hi</p>"))).toBeNull();
+    expect(collectTopLevelElementIds(null)).toBeNull();
+  });
+});

package/src/player/hooks/timelineSyncHydration.ts

@@ -14,12 +14,12 @@ import { usePlayerStore } from "../store/playerStore";
 import type { TimelineElement, DomClipChild, SubCompositionHostState } from "../store/playerStore";
 import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";
 import type { ClipTree } from "@hyperframes/core/runtime/clipTree";
+import { topLevelElements, type StructureNode } from "@hyperframes/parsers/top-level-elements";
 import { HF_AUDIO_GROUP_ATTR } from "@hyperframes/core/audio-groups";
 import { groupInfoFor } from "../lib/timelineGroupInfo";
 import type { PlaybackAdapter, ClipManifestClip, IframeWindow } from "../lib/playbackTypes";
 import {
   buildStandaloneRootTimelineElement,
-  createImplicitTimelineLayersFromDOM,
   createTimelineElementFromManifestClip,
   getTimelineElementSelector,
   parseTimelineFromDOM,
@@ -137,6 +137,28 @@ export function collectSubCompositionDomChildren(
   return out;
 }
 
+interface DomStructureNode extends StructureNode<DomStructureNode> {
+  id: string;
+}
+
+function toStructureNode(el: Element): DomStructureNode {
+  const attrs: Record<string, string> = {};
+  for (const attr of Array.from(el.attributes)) attrs[attr.name] = attr.value;
+  return {
+    tag: el.tagName,
+    attrs,
+    id: el.id,
+    children: Array.from(el.children).map(toStructureNode),
+  };
+}
+
+/** DOM ids of the timeline's rows, by the definition the structure lint shares; null when there is no readable root. */
+export function collectTopLevelElementIds(doc: Document | null): Set<string> | null {
+  const root = doc?.querySelector("[data-composition-id]");
+  if (!root) return null;
+  return new Set(topLevelElements(toStructureNode(root)).flatMap((n) => (n.id ? [n.id] : [])));
+}
+
 /** The host-element `data-*` state one element carries, or null when it has none. */
 function readSubCompositionHostState(el: Element): SubCompositionHostState | null {
   const state: SubCompositionHostState = {};
@@ -214,28 +236,25 @@ export function buildTimelineElementsFromClips(
   });
 }
 
-/**
- * The clamped manifest elements plus the layers that exist only in the DOM.
- * Both halves need the same resolved duration, which is why they land together.
- */
-export function withImplicitDomLayers(
-  els: readonly TimelineElement[],
-  iframeDoc: Document | null,
-  effectiveDuration: number,
-): TimelineElement[] {
-  const clamped = clampElementsToDuration(els, effectiveDuration);
-  if (!iframeDoc || effectiveDuration <= 0) return clamped;
-  return [
-    ...clamped,
-    ...createImplicitTimelineLayersFromDOM(iframeDoc, effectiveDuration, clamped),
-  ];
-}
-
 /**
  * Drop elements that start past the composition's end and trim the ones that
  * straddle it. A non-positive duration means "not known yet" — pass through
  * untouched rather than clamping everything to nothing.
  */
+/** Commits the manifest elements, including none. An empty manifest carries a 1s floor, not a duration. */
+export function syncManifestTimeline(
+  els: readonly TimelineElement[],
+  manifestDuration: number,
+  storeDuration: number,
+  sync: (els: TimelineElement[], duration?: number) => void,
+): void {
+  const hasDuration = manifestDuration > 0 && els.length > 0;
+  sync(
+    clampElementsToDuration(els, hasDuration ? manifestDuration : storeDuration),
+    hasDuration ? manifestDuration : undefined,
+  );
+}
+
 function clampElementsToDuration(
   els: readonly TimelineElement[],
   effectiveDuration: number,

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

@@ -330,34 +330,17 @@ describe("findTimelineDomNodeForClip", () => {
 });
 
 describe("anonymous timeline identity", () => {
-  it("adds root-level untimed DOM layers as implicit full-duration layers", () => {
+  it("does not invent rows for root-level untimed wrappers", () => {
     const doc = createDocument(`
       <div data-composition-id="compare" data-start="0" data-duration="18">
-        <link rel="stylesheet" href="styles.css" />
-        <div class="scene-shell">
-          <div class="topline">Title</div>
-        </div>
+        <div class="scene-shell"><div class="topline">Title</div></div>
         <video id="main-video" class="clip main-video" data-start="0" data-duration="18" data-track-index="1"></video>
-        <script></script>
       </div>
     `);
 
     const elements = parseTimelineFromDOM(doc, 18);
 
-    expect(elements).toEqual(
-      expect.arrayContaining([
-        expect.objectContaining({
-          duration: 18,
-          label: "Scene Shell",
-          selector: ".scene-shell",
-          start: 0,
-          tag: "div",
-          timingSource: "implicit",
-        }),
-      ]),
-    );
-    expect(elements.find((element) => element.tag === "link")).toBeUndefined();
-    expect(elements.find((element) => element.tag === "script")).toBeUndefined();
+    expect(elements.map((element) => element.tag)).toEqual(["video"]);
   });
 
   it("keeps fallback-parsed anonymous clips distinct when labels match", () => {

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

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { selectTimelineRowElements } from "./useTimelineRowElements";
+
+const el = (id: string, domId?: string): TimelineElement => ({
+  id,
+  domId,
+  start: 0,
+  duration: 1,
+  track: 0,
+  tag: "div",
+});
+
+describe("selectTimelineRowElements", () => {
+  it("drops an element the shared definition does not call top-level", () => {
+    const rows = selectTimelineRowElements([el("a", "a"), el("b", "b")], new Set(["a"]));
+    expect(rows.map((r) => r.id)).toEqual(["a"]);
+  });
+
+  it("keeps everything until the document has been read", () => {
+    const all = [el("a", "a"), el("b", "b")];
+    expect(selectTimelineRowElements(all, null)).toBe(all);
+  });
+
+  it("keeps an element with no DOM id", () => {
+    expect(selectTimelineRowElements([el("k")], new Set())).toHaveLength(1);
+  });
+});

package/src/player/hooks/useTimelineRowElements.ts

@@ -0,0 +1,17 @@
+import { useMemo } from "react";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+
+/** Rows are the ids `topLevelElements` names, as the lint does; id-less ones are kept. */
+export function selectTimelineRowElements(
+  elements: TimelineElement[],
+  topLevelIds: ReadonlySet<string> | null,
+): TimelineElement[] {
+  if (!topLevelIds) return elements;
+  return elements.filter((el) => el.domId === undefined || topLevelIds.has(el.domId));
+}
+
+export function useTimelineRowElements(): TimelineElement[] {
+  const elements = usePlayerStore((s) => s.elements);
+  const topLevelIds = usePlayerStore((s) => s.topLevelIds);
+  return useMemo(() => selectTimelineRowElements(elements, topLevelIds), [elements, topLevelIds]);
+}

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