@hyperframes/studio 0.7.56 → 0.7.57

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

@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  acceptStudioRuntimeMessage,
+  acceptedRuntimeMessageFps,
+  createRuntimeControlMessage,
+  inspectStudioRuntimeMessage,
+  postRuntimeControlMessage,
+} from "./runtimeProtocol";
+
+describe("Studio runtime protocol", () => {
+  it("versions every control message and declares rational fps", () => {
+    expect(createRuntimeControlMessage("seek", { timeSeconds: 1.25 }, 60)).toEqual({
+      source: "hf-parent",
+      type: "control",
+      action: "seek",
+      protocolVersion: 1,
+      capabilities: ["seconds-time", "rational-fps", "seek-keep-playing"],
+      fps: { numerator: 60, denominator: 1 },
+      timeSeconds: 1.25,
+    });
+  });
+
+  it("posts the typed message to the target window", () => {
+    const target = { postMessage: vi.fn() };
+    postRuntimeControlMessage(target as unknown as Window, "pause");
+    expect(target.postMessage).toHaveBeenCalledWith(
+      expect.objectContaining({ action: "pause", protocolVersion: 1 }),
+      "*",
+    );
+  });
+
+  it("preserves legacy 30fps messages and rejects unknown majors", () => {
+    expect(inspectStudioRuntimeMessage({ source: "hf-preview" })).toEqual({
+      status: "legacy",
+      fps: 30,
+    });
+    expect(inspectStudioRuntimeMessage({ protocolVersion: 2 })).toMatchObject({
+      status: "unsupported",
+      code: "unsupported_protocol_version",
+    });
+  });
+
+  it("reads explicit fps for accepted timeline messages", () => {
+    const message = createRuntimeControlMessage("pause", {}, 60);
+    expect(acceptedRuntimeMessageFps(message)).toBe(60);
+    expect(acceptStudioRuntimeMessage(message)).toMatchObject({ status: "supported", fps: 60 });
+  });
+});

package/src/player/lib/runtimeProtocol.ts

@@ -0,0 +1,65 @@
+import {
+  inspectRuntimeProtocol,
+  runtimeProtocolMetadata,
+  type RuntimeProtocolInspection,
+} from "@hyperframes/core/runtime/protocol";
+
+export type RuntimeControlMessage = {
+  source: "hf-parent";
+  type: "control";
+  action: string;
+} & ReturnType<typeof runtimeProtocolMetadata> &
+  Record<string, unknown>;
+
+export function createRuntimeControlMessage(
+  action: string,
+  payload: Record<string, unknown> = {},
+  fps = 30,
+): RuntimeControlMessage {
+  return {
+    ...payload,
+    source: "hf-parent",
+    type: "control",
+    action,
+    ...runtimeProtocolMetadata(fps),
+  };
+}
+
+export function postRuntimeControlMessage(
+  target: Pick<Window, "postMessage"> | null | undefined,
+  action: string,
+  payload: Record<string, unknown> = {},
+  fps = 30,
+): void {
+  target?.postMessage(createRuntimeControlMessage(action, payload, fps), "*");
+}
+
+export function inspectStudioRuntimeMessage(value: unknown): RuntimeProtocolInspection {
+  return inspectRuntimeProtocol(value, 30);
+}
+
+function dispatchRuntimeProtocolError(inspection: RuntimeProtocolInspection): void {
+  if (inspection.status !== "unsupported") return;
+  window.dispatchEvent(
+    new CustomEvent("runtimeprotocolerror", {
+      detail: {
+        code: inspection.code,
+        receivedVersion: inspection.receivedVersion,
+      },
+    }),
+  );
+}
+
+export function acceptStudioRuntimeMessage(
+  value: unknown,
+): Exclude<RuntimeProtocolInspection, { status: "unsupported" }> | null {
+  const inspection = inspectStudioRuntimeMessage(value);
+  if (inspection.status !== "unsupported") return inspection;
+  dispatchRuntimeProtocolError(inspection);
+  return null;
+}
+
+export function acceptedRuntimeMessageFps(value: unknown): number {
+  const inspection = inspectStudioRuntimeMessage(value);
+  return inspection.status === "supported" ? inspection.fps : 30;
+}

package/src/player/lib/timelineDOM.ts

@@ -113,6 +113,15 @@ export function createTimelineElementFromManifestClip(params: {
     start: clip.start,
     duration: clip.duration,
     track: clip.track,
+    // clip.track IS the authored data-track-index verbatim (the runtime honors
+    // it; see parseAuthoredTrack in core/runtime/timeline.ts). Record it at this
+    // translation boundary so later display-lane remaps (normalizeToZones,
+    // expanded-child rows) can persist in AUTHORED space instead of
+    // reconstructing it from lane occupants.
+    authoredTrack: clip.track,
+    // Runtime-computed stacking context — authoritative; helpers read it, never
+    // re-derive it.
+    stackingContextId: clip.stackingContextId ?? null,
     domId,
     hfId,
     selector,

package/src/player/lib/timelineElementHelpers.ts

@@ -298,6 +298,25 @@ export function getTimelineElementIdentity(element: { key?: string | null; id: s
   return element.key ?? element.id;
 }
 
+/**
+ * Timeline store key for a z-reorder entry built OUTSIDE the timeline
+ * expansion (canvas context menu / LayersPanel), so the reorder commit can
+ * update the store's zIndex synchronously. Matches buildTimelineElementKey's
+ * stable branches (`sourceFile#domId`, else the selector-based key). Undefined
+ * when the element has neither a DOM id nor a selector — the timeline's
+ * fallback branch needs its own fallbackIndex, which these callers don't have,
+ * so such an entry simply skips the synchronous store update.
+ */
+export function deriveTimelineStoreKey(params: {
+  domId?: string;
+  selector?: string;
+  selectorIndex?: number;
+  sourceFile?: string;
+}): string | undefined {
+  if (!params.domId && !params.selector) return undefined;
+  return buildTimelineElementKey({ id: "", fallbackIndex: 0, ...params });
+}
+
 // ---------------------------------------------------------------------------
 // DOM node querying
 // ---------------------------------------------------------------------------

package/src/player/lib/timelineIframeHelpers.ts

@@ -20,6 +20,7 @@ import {
   buildTimelineElementIdentity,
   readTimelineElementZIndex,
 } from "./timelineElementHelpers";
+import { postRuntimeControlMessage } from "./runtimeProtocol";
 
 // ---------------------------------------------------------------------------
 // Viewport / DOM normalisation
@@ -103,10 +104,7 @@ function postPreviewControl(
   action: string,
   payload: Record<string, unknown>,
 ): void {
-  iframe.contentWindow?.postMessage(
-    { source: "hf-parent", type: "control", action, ...payload },
-    "*",
-  );
+  postRuntimeControlMessage(iframe.contentWindow, action, payload);
 }
 
 export function shouldMutePreviewAudio(audioMuted: boolean, playbackRate: number): boolean {

package/src/player/store/playerStore.test.ts

@@ -1,6 +1,16 @@
 import { describe, it, expect, beforeEach, vi } from "vitest";
 import { usePlayerStore, liveTime, type TimelineElement } from "./playerStore";
 
+/** The playback/selection state `reset()` restores (persistent prefs asserted separately). */
+function expectResettableDefaults(state: ReturnType<typeof usePlayerStore.getState>): void {
+  expect(state.isPlaying).toBe(false);
+  expect(state.currentTime).toBe(0);
+  expect(state.duration).toBe(0);
+  expect(state.timelineReady).toBe(false);
+  expect(state.elements).toEqual([]);
+  expect(state.selectedElementId).toBeNull();
+}
+
 describe("usePlayerStore", () => {
   beforeEach(() => {
     usePlayerStore.getState().reset();
@@ -9,12 +19,7 @@ describe("usePlayerStore", () => {
   describe("initial state", () => {
     it("has correct defaults", () => {
       const state = usePlayerStore.getState();
-      expect(state.isPlaying).toBe(false);
-      expect(state.currentTime).toBe(0);
-      expect(state.duration).toBe(0);
-      expect(state.timelineReady).toBe(false);
-      expect(state.elements).toEqual([]);
-      expect(state.selectedElementId).toBeNull();
+      expectResettableDefaults(state);
       expect(state.playbackRate).toBe(1);
       expect(state.audioMuted).toBe(false);
       expect(state.loopEnabled).toBe(false);
@@ -384,6 +389,32 @@ describe("usePlayerStore", () => {
     });
   });
 
+  describe("clipRevealRequest", () => {
+    it("starts null and carries the requested element id", () => {
+      expect(usePlayerStore.getState().clipRevealRequest).toBeNull();
+      usePlayerStore.getState().requestClipReveal("el-1");
+      expect(usePlayerStore.getState().clipRevealRequest?.elementId).toBe("el-1");
+    });
+
+    it("bumps the nonce on repeat requests for the same clip", () => {
+      usePlayerStore.getState().requestClipReveal("el-1");
+      const first = usePlayerStore.getState().clipRevealRequest;
+      usePlayerStore.getState().requestClipReveal("el-1");
+      const second = usePlayerStore.getState().clipRevealRequest;
+      expect(second?.nonce).not.toBe(first?.nonce);
+    });
+
+    it("clears via clearClipRevealRequest and on reset", () => {
+      usePlayerStore.getState().requestClipReveal("el-1");
+      usePlayerStore.getState().clearClipRevealRequest();
+      expect(usePlayerStore.getState().clipRevealRequest).toBeNull();
+
+      usePlayerStore.getState().requestClipReveal("el-2");
+      usePlayerStore.getState().reset();
+      expect(usePlayerStore.getState().clipRevealRequest).toBeNull();
+    });
+  });
+
   describe("reset", () => {
     it("resets all state to defaults", () => {
       // Mutate everything
@@ -398,13 +429,7 @@ describe("usePlayerStore", () => {
       // Reset
       usePlayerStore.getState().reset();
 
-      const state = usePlayerStore.getState();
-      expect(state.isPlaying).toBe(false);
-      expect(state.currentTime).toBe(0);
-      expect(state.duration).toBe(0);
-      expect(state.timelineReady).toBe(false);
-      expect(state.elements).toEqual([]);
-      expect(state.selectedElementId).toBeNull();
+      expectResettableDefaults(usePlayerStore.getState());
     });
 
     it("does not reset playbackRate, audioMuted, loopEnabled, zoomMode, or manualZoomPercent", () => {

package/src/player/store/playerStore.ts

@@ -29,6 +29,17 @@ export interface TimelineElement {
   start: number;
   duration: number;
   track: number;
+  /**
+   * The data-track-index as written in the source file. Set at the manifest
+   * translation boundary (createTimelineElementFromManifestClip) from the
+   * runtime clip's verbatim track, and preserved through display-lane remaps
+   * (normalizeToZones packs sparse authored tracks onto contiguous display
+   * lanes; expanded sub-comp children get synthetic display rows). Lane edits
+   * must persist THIS space — writing a display-lane number into a sparse file
+   * re-targets the wrong track. For an expanded child the value is in its OWN
+   * source file's coordinate space, not the host timeline's.
+   */
+  authoredTrack?: number;
   /** Resolved z-index for stacking-aware timeline ordering. */
   zIndex?: number;
   /** True when the effective z-index was authored inline or through CSS, not auto. */
@@ -153,6 +164,9 @@ interface PlayerState {
   /** Timeline magnet toggle — when false, clip drags/trims/drops never snap. */
   timelineSnapEnabled: boolean;
   setTimelineSnapEnabled: (enabled: boolean) => void;
+  /** Transport + ruler readout: timecode ("time") or frame number ("frame"). */
+  timeDisplayMode: "time" | "frame";
+  setTimeDisplayMode: (mode: "time" | "frame") => void;
   /**
    * Pin the timeline zoom to its current visual scale before a duration-changing
    * edit, so a subsequent duration change (which recomputes fit-pps) stops
@@ -210,6 +224,16 @@ interface PlayerState {
   requestSeek: (time: number) => void;
   clearSeekRequest: () => void;
 
+  /**
+   * Request the timeline to scroll a clip into view (e.g. clicking an
+   * already-added asset card in the sidebar). Consumed and cleared by
+   * useTimelineRevealClip. The nonce makes repeat requests for the same
+   * clip observable so a second click re-reveals after the user scrolls away.
+   */
+  clipRevealRequest: { elementId: string; nonce: number } | null;
+  requestClipReveal: (elementId: string) => void;
+  clearClipRevealRequest: () => void;
+
   lintFindingsByElement: Map<string, { count: number; messages: string[] }>;
   setLintFindingsByElement: (map: Map<string, { count: number; messages: string[] }>) => void;
 
@@ -341,6 +365,13 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   requestSeek: (time) => set({ requestedSeekTime: time }),
   clearSeekRequest: () => set({ requestedSeekTime: null }),
 
+  clipRevealRequest: null,
+  requestClipReveal: (elementId) =>
+    set((s) => ({
+      clipRevealRequest: { elementId, nonce: (s.clipRevealRequest?.nonce ?? 0) + 1 },
+    })),
+  clearClipRevealRequest: () => set({ clipRevealRequest: null }),
+
   lintFindingsByElement: new Map(),
   setLintFindingsByElement: (map) => set({ lintFindingsByElement: map }),
 
@@ -416,6 +447,11 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
     writeStudioUiPreferences({ timelineSnapEnabled: enabled });
     set({ timelineSnapEnabled: enabled });
   },
+  timeDisplayMode: readStudioUiPreferences().timeDisplayMode ?? "time",
+  setTimeDisplayMode: (mode) => {
+    writeStudioUiPreferences({ timeDisplayMode: mode });
+    set({ timeDisplayMode: mode });
+  },
   pinTimelineZoom: (currentPixelsPerSecond, fitPixelsPerSecond) =>
     set((s) => {
       // Already pinned (or the user manually zoomed) — never clobber that.
@@ -522,6 +558,7 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
       activeTool: "select",
       selectedKeyframes: new Set(),
       selectedElementIds: new Set(),
+      clipRevealRequest: null,
       keyframeCache: new Map(),
       beatAnalysis: null,
       beatEdits: null,

package/src/utils/assetPreviewDismiss.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { shouldDismissAssetPreview } from "./assetPreviewDismiss";
+
+describe("shouldDismissAssetPreview", () => {
+  const idle = { isPlaying: false, currentTime: 3.5, requestedSeekTime: null };
+
+  it("keeps the preview open while nothing moves", () => {
+    expect(shouldDismissAssetPreview(3.5, idle)).toBe(false);
+  });
+
+  it("tolerates sub-epsilon float noise in currentTime echoes", () => {
+    expect(shouldDismissAssetPreview(3.5, { ...idle, currentTime: 3.5 + 1e-9 })).toBe(false);
+  });
+
+  it("dismisses when playback starts", () => {
+    expect(shouldDismissAssetPreview(3.5, { ...idle, isPlaying: true })).toBe(true);
+  });
+
+  it("dismisses when the playhead is scrubbed/seeked to a new time", () => {
+    expect(shouldDismissAssetPreview(3.5, { ...idle, currentTime: 4.2 })).toBe(true);
+    expect(shouldDismissAssetPreview(3.5, { ...idle, currentTime: 0 })).toBe(true);
+  });
+
+  it("dismisses on a pending out-of-loop seek request", () => {
+    expect(shouldDismissAssetPreview(3.5, { ...idle, requestedSeekTime: 3.5 })).toBe(true);
+  });
+});

package/src/utils/assetPreviewDismiss.ts

@@ -0,0 +1,29 @@
+/**
+ * Dismissal rule for the sidebar asset preview overlay (AssetPreviewOverlay):
+ * the preview is a transient "look at this asset" state, so any playhead
+ * activity — starting playback, or seeking/scrubbing away from where the
+ * playhead sat when the preview opened — hands focus back to the canvas and
+ * closes it.
+ *
+ * Pure — unit-tested. The overlay captures `openedTime` when the preview
+ * opens and feeds every subsequent player-store snapshot through this.
+ */
+
+export interface AssetPreviewDismissSnapshot {
+  isPlaying: boolean;
+  currentTime: number;
+  /** Pending out-of-loop seek request (playerStore.requestedSeekTime). */
+  requestedSeekTime: number | null;
+}
+
+/** Tolerance for float noise in currentTime echoes (well under one frame). */
+const TIME_EPSILON_S = 1e-6;
+
+export function shouldDismissAssetPreview(
+  openedTime: number,
+  snapshot: AssetPreviewDismissSnapshot,
+): boolean {
+  if (snapshot.isPlaying) return true;
+  if (snapshot.requestedSeekTime !== null) return true;
+  return Math.abs(snapshot.currentTime - openedTime) > TIME_EPSILON_S;
+}

package/src/utils/timelineAssetDrop.test.ts

@@ -1,13 +1,80 @@
+// @vitest-environment jsdom
 import { describe, expect, it } from "vitest";
 import {
   buildTimelineFileDropPlacements,
   buildTimelineAssetInsertHtml,
+  extendCompositionDurationIfNeeded,
+  fitTimelineAssetGeometry,
   getTimelineAssetKind,
   insertTimelineAssetIntoSource,
-  resolveTimelineAssetInitialGeometry,
+  resolveTimelineAssetCompositionSize,
   resolveTimelineAssetSrc,
+  setCompositionDurationToContent,
 } from "./timelineAssetDrop";
 
+describe("setCompositionDurationToContent", () => {
+  const src = (dur: number) =>
+    `<div id="root" data-composition-id="c" data-duration="${dur}">x</div>`;
+
+  it("shrinks the root duration to the content end", () => {
+    expect(setCompositionDurationToContent(src(20), 8)).toContain('data-duration="8"');
+  });
+
+  it("grows the root duration to the content end", () => {
+    expect(setCompositionDurationToContent(src(5), 12)).toContain('data-duration="12"');
+  });
+
+  it("is a no-op when content end is 0 (empty timeline keeps its declared length)", () => {
+    expect(setCompositionDurationToContent(src(12), 0)).toBe(src(12));
+  });
+
+  it("is a no-op when already equal", () => {
+    expect(setCompositionDurationToContent(src(9), 9)).toBe(src(9));
+  });
+
+  // Reviewer round-2 finding #3: attribute-order and single-quote variants that
+  // the old order-dependent, double-quotes-only regex silently ignored.
+  it("patches when data-duration precedes data-composition-id", () => {
+    const source = `<div data-duration="20" data-composition-id="c">x</div>`;
+    expect(setCompositionDurationToContent(source, 8)).toBe(
+      `<div data-duration="8" data-composition-id="c">x</div>`,
+    );
+  });
+
+  it("patches single-quoted attributes and keeps the quote style", () => {
+    const source = `<div data-composition-id='c' data-duration='20'>x</div>`;
+    expect(setCompositionDurationToContent(source, 8)).toBe(
+      `<div data-composition-id='c' data-duration='8'>x</div>`,
+    );
+  });
+});
+
+describe("extendCompositionDurationIfNeeded", () => {
+  it("grows the root duration when a clip lands past the end", () => {
+    const source = `<div data-composition-id="c" data-duration="5">x</div>`;
+    expect(extendCompositionDurationIfNeeded(source, 8)).toBe(
+      `<div data-composition-id="c" data-duration="8">x</div>`,
+    );
+  });
+
+  it("is a no-op when the required end fits within the current duration", () => {
+    const source = `<div data-composition-id="c" data-duration="10">x</div>`;
+    expect(extendCompositionDurationIfNeeded(source, 8)).toBe(source);
+  });
+
+  it("grows even when the attribute order is swapped and quotes are single", () => {
+    const source = `<div data-duration='5' data-composition-id='c'>x</div>`;
+    expect(extendCompositionDurationIfNeeded(source, 8)).toBe(
+      `<div data-duration='8' data-composition-id='c'>x</div>`,
+    );
+  });
+
+  it("is a no-op when there is no composition root", () => {
+    const source = `<div data-duration="5">x</div>`;
+    expect(extendCompositionDurationIfNeeded(source, 8)).toBe(source);
+  });
+});
+
 describe("getTimelineAssetKind", () => {
   it("detects image, video, and audio assets", () => {
     expect(getTimelineAssetKind("assets/photo.png")).toBe("image");
@@ -16,12 +83,28 @@ describe("getTimelineAssetKind", () => {
     expect(getTimelineAssetKind("assets/music.mp3")).toBe("audio");
     expect(getTimelineAssetKind("assets/music.wav")).toBe("audio");
   });
+
+  it("classifies svg as image", () => {
+    expect(getTimelineAssetKind("assets/logo.svg")).toBe("image");
+    expect(getTimelineAssetKind("assets/ICON.SVG")).toBe("image");
+  });
+
+  it("classifies avif and webp as image", () => {
+    expect(getTimelineAssetKind("assets/photo.avif")).toBe("image");
+    expect(getTimelineAssetKind("assets/photo.webp")).toBe("image");
+  });
+
+  it("returns null for unknown extensions", () => {
+    expect(getTimelineAssetKind("assets/data.json")).toBeNull();
+    expect(getTimelineAssetKind("assets/font.woff2")).toBeNull();
+  });
 });
 
 describe("buildTimelineAssetInsertHtml", () => {
   it("builds an image clip with explicit timing and track", () => {
     const html = buildTimelineAssetInsertHtml({
       id: "photo_asset",
+      hfId: "hf-abc123",
       assetPath: "assets/photo.png",
       kind: "image",
       start: 1.25,
@@ -40,6 +123,7 @@ describe("buildTimelineAssetInsertHtml", () => {
   it("builds an audio clip without visual layout styles", () => {
     const html = buildTimelineAssetInsertHtml({
       id: "music_asset",
+      hfId: "hf-xyz789",
       assetPath: "assets/music.wav",
       kind: "audio",
       start: 0.5,
@@ -52,15 +136,13 @@ describe("buildTimelineAssetInsertHtml", () => {
   });
 });
 
-describe("resolveTimelineAssetInitialGeometry", () => {
+describe("resolveTimelineAssetCompositionSize", () => {
   it("uses the target composition dimensions for visual media", () => {
     expect(
-      resolveTimelineAssetInitialGeometry(
+      resolveTimelineAssetCompositionSize(
         `<div data-composition-id="main" data-width="330" data-height="228"></div>`,
       ),
     ).toEqual({
-      left: 0,
-      top: 0,
       width: 330,
       height: 228,
     });
@@ -84,7 +166,9 @@ describe("buildTimelineFileDropPlacements", () => {
     expect(buildTimelineFileDropPlacements({ start: 1.5, track: 2 }, [])).toEqual([]);
   });
 
-  it("uses the dropped start and spaces multiple files by duration on the same track", () => {
+  it("spaces multiple files by duration and keeps every one on the dropped track", () => {
+    // A clip placed onto an occupied track stays there (overlap is allowed); it is
+    // NOT bumped to a new track — that produced surprise empty tracks for users.
     expect(buildTimelineFileDropPlacements({ start: 1.5, track: 2 }, [1.2, 1.6, 1.1])).toEqual([
       { start: 1.5, track: 2 },
       { start: 2.7, track: 2 },
@@ -99,52 +183,6 @@ describe("buildTimelineFileDropPlacements", () => {
       { start: 7.7, track: 2 },
     ]);
   });
-
-  it("moves the spaced sequence to a clear track when the dropped row is occupied", () => {
-    expect(
-      buildTimelineFileDropPlacements(
-        { start: 1.5, track: 2 },
-        [1.2, 1.6, 1.1],
-        [
-          { start: 0, duration: 8, track: 2 },
-          { start: 0, duration: 4, track: 5 },
-        ],
-      ),
-    ).toEqual([
-      { start: 1.5, track: 6 },
-      { start: 2.7, track: 6 },
-      { start: 4.3, track: 6 },
-    ]);
-  });
-
-  it("keeps a requested track above occupied rows when that track is clear", () => {
-    expect(
-      buildTimelineFileDropPlacements(
-        { start: 1.5, track: 8 },
-        [1.2, 1.6],
-        [
-          { start: 0, duration: 8, track: 2 },
-          { start: 0, duration: 4, track: 5 },
-        ],
-      ),
-    ).toEqual([
-      { start: 1.5, track: 8 },
-      { start: 2.7, track: 8 },
-    ]);
-  });
-
-  it("moves a default-track drop to a clear row when track 0 is occupied at time 0", () => {
-    expect(
-      buildTimelineFileDropPlacements(
-        { start: 0, track: 0 },
-        [1.2, 1.6],
-        [{ start: 0, duration: 8, track: 0 }],
-      ),
-    ).toEqual([
-      { start: 0, track: 1 },
-      { start: 1.2, track: 1 },
-    ]);
-  });
 });
 
 describe("insertTimelineAssetIntoSource", () => {
@@ -159,3 +197,57 @@ describe("insertTimelineAssetIntoSource", () => {
     expect(html).toContain('<img id="photo_asset" data-start="0" data-duration="3" />');
   });
 });
+
+describe("buildTimelineAssetInsertHtml markup quality", () => {
+  const base = {
+    id: "clip_1",
+    hfId: "hf-test-1",
+    assetPath: "assets/a.mp4",
+    start: 1,
+    duration: 4,
+    track: 2,
+    zIndex: 3,
+  };
+
+  it("stamps data-hf-id on all kinds", () => {
+    for (const kind of ["image", "video", "audio"] as const) {
+      expect(buildTimelineAssetInsertHtml({ ...base, kind })).toContain('data-hf-id="hf-test-1"');
+    }
+  });
+
+  it("audio gets an explicit data-volume", () => {
+    expect(buildTimelineAssetInsertHtml({ ...base, kind: "audio" })).toContain('data-volume="1"');
+  });
+});
+
+describe("fitTimelineAssetGeometry", () => {
+  const comp = { width: 1920, height: 1080 };
+
+  it("centers a smaller-than-comp asset at natural size", () => {
+    expect(fitTimelineAssetGeometry({ width: 640, height: 360 }, comp)).toEqual({
+      left: 640,
+      top: 360,
+      width: 640,
+      height: 360,
+    });
+  });
+
+  it("scales an oversized asset down to fit, preserving aspect, centered", () => {
+    // 4000x1000 → capped to 1920 wide → 1920x480, centered vertically
+    expect(fitTimelineAssetGeometry({ width: 4000, height: 1000 }, comp)).toEqual({
+      left: 0,
+      top: 300,
+      width: 1920,
+      height: 480,
+    });
+  });
+
+  it("falls back to full-frame when natural size is unknown", () => {
+    expect(fitTimelineAssetGeometry(null, comp)).toEqual({
+      left: 0,
+      top: 0,
+      width: 1920,
+      height: 1080,
+    });
+  });
+});