@hyperframes/studio 0.7.86 → 0.7.87

package/src/player/lib/timelinePerformanceFixture.ts

@@ -0,0 +1,167 @@
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { KeyframeCacheEntry, TimelineElement } from "../store/playerStore";
+
+export type TimelinePerformanceFixtureProfile =
+  | "dense-short"
+  | "long-overlap"
+  | "keyframe-heavy-expanded"
+  | "composition-heavy"
+  | "remote-unsupported";
+
+export interface TimelinePerformanceFixtureSpec {
+  elementCount: 1_000 | 50_000;
+  profile: TimelinePerformanceFixtureProfile;
+}
+
+export interface TimelinePerformanceFixtureSummary extends TimelinePerformanceFixtureSpec {
+  duration: number;
+  trackCount: number;
+  keyframedElementCount: number;
+  expandedElementCount: number;
+}
+
+export interface TimelinePerformanceFixture {
+  summary: Readonly<TimelinePerformanceFixtureSummary>;
+  elements: TimelineElement[];
+  keyframeCache: Map<string, KeyframeCacheEntry>;
+  gsapAnimations: Map<string, GsapAnimation[]>;
+  expandedClipIds: Set<string>;
+}
+
+const TRACK_COUNT = 1_000;
+let fixtureLeaseActive = false;
+const PROFILE_GEOMETRY: Readonly<
+  Record<TimelinePerformanceFixtureProfile, { duration: number; clipDuration: number }>
+> = Object.freeze({
+  "dense-short": { duration: 120, clipDuration: 1.5 },
+  "long-overlap": { duration: 7_200, clipDuration: 120 },
+  "keyframe-heavy-expanded": { duration: 600, clipDuration: 8 },
+  "composition-heavy": { duration: 900, clipDuration: 12 },
+  "remote-unsupported": { duration: 900, clipDuration: 12 },
+});
+
+/** Prevent live iframe discovery from replacing an explicitly loaded dev fixture. */
+export function setTimelinePerformanceFixtureLease(active: boolean): void {
+  fixtureLeaseActive = active;
+}
+
+export function hasTimelinePerformanceFixtureLease(): boolean {
+  return fixtureLeaseActive;
+}
+
+function validateFixtureSpec(spec: TimelinePerformanceFixtureSpec) {
+  if (spec.elementCount !== 1_000 && spec.elementCount !== 50_000) {
+    throw new RangeError("Timeline performance fixture elementCount must be 1000 or 50000");
+  }
+  if (!Object.hasOwn(PROFILE_GEOMETRY, spec.profile)) {
+    throw new RangeError(`Unknown timeline performance fixture profile: ${spec.profile}`);
+  }
+  const geometry = PROFILE_GEOMETRY[spec.profile];
+  return geometry;
+}
+
+function fixtureTrack(index: number, spec: TimelinePerformanceFixtureSpec): number {
+  if (index < TRACK_COUNT) return index;
+  if (spec.profile !== "dense-short") return index % TRACK_COUNT;
+  // Keep the dense profile inside the declared 128-roots-per-row envelope while
+  // still representing every one of the 1,000 logical tracks.
+  const denseTrackCount = Math.ceil((spec.elementCount - TRACK_COUNT) / 127);
+  return (index - TRACK_COUNT) % Math.max(1, denseTrackCount);
+}
+
+function fixtureStart(
+  index: number,
+  profile: TimelinePerformanceFixtureProfile,
+  duration: number,
+  clipDuration: number,
+): number {
+  const available = Math.max(0, duration - clipDuration);
+  if (profile === "dense-short") return (index % 128) * 0.5;
+  if (profile === "long-overlap") return (index * 37) % Math.max(1, available);
+  return (index * 17) % Math.max(1, available);
+}
+
+function keyframeData(): KeyframeCacheEntry {
+  return {
+    format: "percentage",
+    keyframes: [0, 33, 66, 100].map((percentage) => ({
+      percentage,
+      propertyGroup: "position",
+      properties: { x: percentage },
+      ease: "power2.inOut",
+    })),
+  };
+}
+
+function fixtureAnimation(id: string, start: number, duration: number): GsapAnimation {
+  return {
+    id: `animation-${id}`,
+    targetSelector: `#${id}`,
+    method: "to",
+    position: start,
+    resolvedStart: start,
+    duration,
+    propertyGroup: "position",
+    fromProperties: { x: 0 },
+    properties: { x: 100 },
+    ease: "power2.inOut",
+  };
+}
+
+/** Pure deterministic generator; the dev test hook performs the one store mutation. */
+export function createTimelinePerformanceFixture(
+  spec: TimelinePerformanceFixtureSpec,
+): TimelinePerformanceFixture {
+  const geometry = validateFixtureSpec(spec);
+  const elements: TimelineElement[] = [];
+  const keyframeCache = new Map<string, KeyframeCacheEntry>();
+  const gsapAnimations = new Map<string, GsapAnimation[]>();
+  const expandedClipIds = new Set<string>();
+
+  for (let index = 0; index < spec.elementCount; index += 1) {
+    const id = `perf-${spec.profile}-${spec.elementCount}-${index}`;
+    const start = fixtureStart(index, spec.profile, geometry.duration, geometry.clipDuration);
+    const track = fixtureTrack(index, spec);
+    const element: TimelineElement = {
+      id,
+      key: id,
+      domId: id,
+      selector: `#${id}`,
+      label: `Fixture ${index + 1}`,
+      tag: spec.profile === "remote-unsupported" && index % 2 === 0 ? "video" : "div",
+      start,
+      duration: geometry.clipDuration,
+      track,
+      authoredTrack: track,
+    };
+
+    if (spec.profile === "composition-heavy") {
+      element.compositionSrc = `compositions/perf-${index % 32}.html`;
+    } else if (spec.profile === "remote-unsupported") {
+      element.src =
+        index % 2 === 0
+          ? `https://media.invalid/perf-${index % 32}.mp4`
+          : `assets/perf-${index % 32}.unsupported`;
+    }
+    if (spec.profile === "keyframe-heavy-expanded") {
+      keyframeCache.set(id, keyframeData());
+      gsapAnimations.set(id, [fixtureAnimation(id, start, geometry.clipDuration)]);
+      expandedClipIds.add(id);
+    }
+    elements.push(element);
+  }
+
+  return {
+    summary: Object.freeze({
+      ...spec,
+      duration: geometry.duration,
+      trackCount: TRACK_COUNT,
+      keyframedElementCount: keyframeCache.size,
+      expandedElementCount: expandedClipIds.size,
+    }),
+    elements,
+    keyframeCache,
+    gsapAnimations,
+    expandedClipIds,
+  };
+}

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

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import {
+  TIMELINE_VIEWPORT_BUDGETS,
+  resolveTimelineViewportBudgets,
+} from "./timelineViewportBudgets";
+
+describe("timeline viewport budgets", () => {
+  it("owns the agreed direct-scroll, DOM, media, and measurement ceilings", () => {
+    expect(TIMELINE_VIEWPORT_BUDGETS).toMatchObject({
+      directScrollSafetyPx: 8_000_000,
+      rowOverscanPerSide: 2,
+      timeOverscanViewportRatio: 0.25,
+      maxMountedRows: 64,
+      maxMountedClipRoots: 512,
+      maxMountedClipRootsPerRow: 128,
+      maxMountedTimelineDescendants: 5_000,
+      thumbnailCacheBytes: 64 * 1024 * 1024,
+      waveformCacheBytes: 16 * 1024 * 1024,
+      interactionP95Ms: 50,
+      constrainedInteractionP95Ms: 75,
+      constrainedFrameIntervalP95Ms: 75,
+      longTaskLimitMs: 50,
+      constrainedLongTaskLimitMs: 300,
+      posterCoverageRatio: 0.9,
+      supportedFixtureFallbackRatio: 0.02,
+      scrollSamplesPerRun: 21,
+      warmupRuns: 3,
+      measuredRuns: 5,
+      requiredPassingRuns: 4,
+    });
+    expect(Object.isFrozen(TIMELINE_VIEWPORT_BUDGETS)).toBe(true);
+  });
+
+  it("creates an immutable test override without changing production defaults", () => {
+    const resolved = resolveTimelineViewportBudgets({
+      directScrollSafetyPx: 256,
+      measuredRuns: 1,
+      requiredPassingRuns: 1,
+    });
+
+    expect(resolved.directScrollSafetyPx).toBe(256);
+    expect(resolved.maxMountedClipRoots).toBe(512);
+    expect(TIMELINE_VIEWPORT_BUDGETS.directScrollSafetyPx).toBe(8_000_000);
+    expect(Object.isFrozen(resolved)).toBe(true);
+  });
+
+  it.each([
+    [{ maxMountedClipRoots: -1 }, "maxMountedClipRoots"],
+    [{ frameIntervalP95Ms: Number.NaN }, "frameIntervalP95Ms"],
+    [{ warmupRuns: 0.5 }, "warmupRuns"],
+    [{ measuredRuns: 0 }, "measuredRuns"],
+    [{ requiredPassingRuns: 0 }, "requiredPassingRuns"],
+    [{ measuredRuns: 1.5, requiredPassingRuns: 1 }, "measuredRuns"],
+    [{ measuredRuns: 4, requiredPassingRuns: 5 }, "requiredPassingRuns"],
+    [{ scrollSamplesPerRun: 19 }, "scrollSamplesPerRun"],
+    [{ posterCoverageRatio: 1.1 }, "posterCoverageRatio"],
+  ] as const)("rejects an invalid override %#", (overrides, message) => {
+    expect(() => resolveTimelineViewportBudgets(overrides)).toThrow(message);
+  });
+});

package/src/player/lib/timelineViewportBudgets.ts

@@ -0,0 +1,151 @@
+export interface TimelineViewportBudgets {
+  directScrollSafetyPx: number;
+  rowOverscanPerSide: number;
+  timeOverscanViewportRatio: number;
+  maxMountedRows: number;
+  maxMountedClipRoots: number;
+  maxMountedClipRootsPerRow: number;
+  maxMountedTimelineDescendants: number;
+  posterMaxPhysicalWidth: number;
+  posterMaxPhysicalHeight: number;
+  posterDprCap: number;
+  richPreviewFrameCount: number;
+  concurrentVideoDecodes: number;
+  concurrentMetadataJobs: number;
+  concurrentCompositionFetches: number;
+  concurrentServerPages: number;
+  thumbnailCacheBytes: number;
+  thumbnailCacheEntries: number;
+  thumbnailCacheEntriesPerProject: number;
+  metadataRegistryEntries: number;
+  metadataFailureTtlMs: number;
+  waveformCacheBytes: number;
+  waveformCacheEntries: number;
+  compositionDiskCacheBytes: number;
+  compositionDiskCacheMaxAgeMs: number;
+  interactionP95Ms: number;
+  frameIntervalP95Ms: number;
+  constrainedInteractionP95Ms: number;
+  constrainedFrameIntervalP95Ms: number;
+  longTaskLimitMs: number;
+  constrainedLongTaskLimitMs: number;
+  memoryReturnToleranceRatio: number;
+  posterColdP95Ms: number;
+  posterCachedP95Ms: number;
+  constrainedPosterColdP95Ms: number;
+  constrainedPosterCachedP95Ms: number;
+  posterCoverageRatio: number;
+  posterCoverageSettleMs: number;
+  constrainedPosterCoverageSettleMs: number;
+  richPreviewP95Ms: number;
+  constrainedRichPreviewP95Ms: number;
+  supportedFixtureFallbackRatio: number;
+  scrollSamplesPerRun: number;
+  warmupRuns: number;
+  measuredRuns: number;
+  requiredPassingRuns: number;
+}
+
+const MEBIBYTE = 1024 * 1024;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * The sole default budget owner for timeline viewport and media virtualization.
+ * Consumers may resolve an immutable per-test override; production defaults are
+ * never mutated globally.
+ */
+export const TIMELINE_VIEWPORT_BUDGETS: Readonly<TimelineViewportBudgets> = Object.freeze({
+  directScrollSafetyPx: 8_000_000,
+  rowOverscanPerSide: 2,
+  timeOverscanViewportRatio: 0.25,
+  maxMountedRows: 64,
+  maxMountedClipRoots: 512,
+  maxMountedClipRootsPerRow: 128,
+  maxMountedTimelineDescendants: 5_000,
+  posterMaxPhysicalWidth: 240,
+  posterMaxPhysicalHeight: 135,
+  posterDprCap: 1.5,
+  richPreviewFrameCount: 6,
+  concurrentVideoDecodes: 2,
+  concurrentMetadataJobs: 4,
+  concurrentCompositionFetches: 2,
+  concurrentServerPages: 1,
+  thumbnailCacheBytes: 64 * MEBIBYTE,
+  thumbnailCacheEntries: 256,
+  thumbnailCacheEntriesPerProject: 96,
+  metadataRegistryEntries: 512,
+  metadataFailureTtlMs: 30_000,
+  waveformCacheBytes: 16 * MEBIBYTE,
+  waveformCacheEntries: 256,
+  compositionDiskCacheBytes: 512 * MEBIBYTE,
+  compositionDiskCacheMaxAgeMs: 14 * DAY_MS,
+  interactionP95Ms: 50,
+  frameIntervalP95Ms: 33.3,
+  constrainedInteractionP95Ms: 75,
+  constrainedFrameIntervalP95Ms: 75,
+  longTaskLimitMs: 50,
+  constrainedLongTaskLimitMs: 300,
+  memoryReturnToleranceRatio: 0.15,
+  posterColdP95Ms: 750,
+  posterCachedP95Ms: 250,
+  constrainedPosterColdP95Ms: 1_200,
+  constrainedPosterCachedP95Ms: 400,
+  posterCoverageRatio: 0.9,
+  posterCoverageSettleMs: 1_500,
+  constrainedPosterCoverageSettleMs: 2_500,
+  richPreviewP95Ms: 750,
+  constrainedRichPreviewP95Ms: 1_200,
+  supportedFixtureFallbackRatio: 0.02,
+  scrollSamplesPerRun: 21,
+  warmupRuns: 3,
+  measuredRuns: 5,
+  requiredPassingRuns: 4,
+});
+
+function assertValidBudget(name: keyof TimelineViewportBudgets, value: number): void {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(`Timeline viewport budget ${name} must be a finite non-negative number`);
+  }
+}
+
+export function resolveTimelineViewportBudgets(
+  overrides: Partial<TimelineViewportBudgets> = {},
+): Readonly<TimelineViewportBudgets> {
+  for (const [name, value] of Object.entries(overrides)) {
+    assertValidBudget(name as keyof TimelineViewportBudgets, value);
+  }
+  const resolved = { ...TIMELINE_VIEWPORT_BUDGETS, ...overrides };
+  for (const name of [
+    "scrollSamplesPerRun",
+    "warmupRuns",
+    "measuredRuns",
+    "requiredPassingRuns",
+  ] as const) {
+    if (!Number.isInteger(resolved[name])) {
+      throw new RangeError(`Timeline viewport budget ${name} must be an integer`);
+    }
+  }
+  if (resolved.scrollSamplesPerRun < 20) {
+    throw new RangeError(
+      "Timeline viewport budget scrollSamplesPerRun must be at least 20 for p95",
+    );
+  }
+  if (resolved.measuredRuns === 0 || resolved.requiredPassingRuns === 0) {
+    throw new RangeError(
+      "Timeline viewport budget measuredRuns and requiredPassingRuns must be greater than zero",
+    );
+  }
+  if (resolved.requiredPassingRuns > resolved.measuredRuns) {
+    throw new RangeError("Timeline viewport budget requiredPassingRuns cannot exceed measuredRuns");
+  }
+  for (const name of [
+    "memoryReturnToleranceRatio",
+    "posterCoverageRatio",
+    "supportedFixtureFallbackRatio",
+  ] as const) {
+    if (resolved[name] > 1) {
+      throw new RangeError(`Timeline viewport budget ${name} cannot exceed 1`);
+    }
+  }
+  return Object.freeze(resolved);
+}

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

@@ -408,9 +408,11 @@ describe("usePlayerStore", () => {
       expect(usePlayerStore.getState().manualZoomPercent).toBe(10);
     });
 
-    it("clamps to the maximum supported zoom percent", () => {
-      usePlayerStore.getState().setManualZoomPercent(5000);
-      expect(usePlayerStore.getState().manualZoomPercent).toBe(2000);
+    it("clamps to the frame-level zoom for the current fit scale", () => {
+      usePlayerStore.getState().setTimelineScale(12, 12);
+      usePlayerStore.getState().setManualZoomPercent(100_000);
+      expect(usePlayerStore.getState().manualZoomPercent).toBe(12_000);
+      usePlayerStore.getState().setTimelineScale(100, 100);
     });
   });
 
@@ -441,6 +443,21 @@ describe("usePlayerStore", () => {
   });
 
   describe("reset", () => {
+    it("increments the session epoch only for a hard project switch", () => {
+      usePlayerStore.getState().beginTimelineSession("project-a");
+      const firstEpoch = usePlayerStore.getState().timelineSessionEpoch;
+
+      usePlayerStore.getState().reset();
+      expect(usePlayerStore.getState().timelineSessionEpoch).toBe(firstEpoch);
+
+      usePlayerStore.getState().beginTimelineSession("project-a");
+      expect(usePlayerStore.getState().timelineSessionEpoch).toBe(firstEpoch);
+
+      usePlayerStore.getState().beginTimelineSession("project-b");
+      expect(usePlayerStore.getState().timelineSessionEpoch).toBe(firstEpoch + 1);
+      expect(usePlayerStore.getState().timelineProjectId).toBe("project-b");
+    });
+
     it("resets all state to defaults", () => {
       // Mutate everything
       const store = usePlayerStore.getState();

package/src/player/store/playerStore.ts

@@ -1,10 +1,15 @@
 import { create } from "zustand";
 import type { MusicBeatAnalysis } from "@hyperframes/core/beats";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { BeatEditState } from "../../utils/beatEditing";
 import type { ClipManifestClip } from "../lib/playbackTypes";
-import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
-import { computePinnedZoomPercent } from "../components/timelineZoom";
-import { createKeyframeSlice, type KeyframeSlice } from "./keyframeSlice";
+import {
+  readStudioUiPreferences,
+  writeStudioUiPreferences,
+  type TimelineTimeDisplayMode,
+} from "../../utils/studioUiPreferences";
+import { clampTimelineZoomPercent, computePinnedZoomPercent } from "../components/timelineZoom";
+import { createKeyframeSlice, type KeyframeCacheEntry, type KeyframeSlice } from "./keyframeSlice";
 
 export type { KeyframeCacheEntry } from "./keyframeSlice";
 
@@ -101,6 +106,10 @@ interface PlayerState extends KeyframeSlice {
   currentTime: number;
   duration: number;
   timelineReady: boolean;
+  /** Increments exactly once when the Studio switches to a different project. */
+  timelineSessionEpoch: number;
+  /** Project owning the current timeline session; null outside a project-scoped reset. */
+  timelineProjectId: string | null;
   /** True while a beat dot is being dragged — hides the playhead guideline. */
   beatDragging: boolean;
   elements: TimelineElement[];
@@ -155,18 +164,15 @@ interface PlayerState extends KeyframeSlice {
   timelineSnapEnabled: boolean;
   setTimelineSnapEnabled: (enabled: boolean) => void;
   /** Transport + ruler readout: timecode ("time") or frame number ("frame"). */
-  timeDisplayMode: "time" | "frame";
-  setTimeDisplayMode: (mode: "time" | "frame") => void;
+  timeDisplayMode: TimelineTimeDisplayMode;
+  setTimeDisplayMode: (mode: TimelineTimeDisplayMode) => 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
    * rescaling every clip. No-op once already pinned (mode is "manual").
    */
   pinTimelineZoom: (currentPixelsPerSecond: number, fitPixelsPerSecond: number) => void;
-  /**
-   * The timeline's live pixels-per-second + fit basis, published by <Timeline> on
-   * every render. Non-reactive scratch state (never read as a render input).
-   */
+  /** The timeline's live pixels-per-second + fit basis, published by <Timeline>. */
   timelinePps: number;
   timelineFitPps: number;
   setTimelineScale: (pps: number, fitPps: number) => void;
@@ -201,6 +207,9 @@ interface PlayerState extends KeyframeSlice {
   bumpZEditVersion: () => void;
   setInPoint: (time: number | null) => void;
   setOutPoint: (time: number | null) => void;
+  /** Owns the hard project boundary; repeated calls for one project are no-ops. */
+  beginTimelineSession: (projectId: string) => void;
+  /** Clears project data without creating a new hard-project session. */
   reset: () => void;
 
   /**
@@ -283,11 +292,49 @@ export const liveTime = {
   },
 };
 
+export function createTimelineResetState() {
+  return {
+    isPlaying: false,
+    currentTime: 0,
+    duration: 0,
+    timelineReady: false,
+    beatDragging: false,
+    elements: [],
+    selectedElementId: null,
+    zEditVersion: 0,
+    inPoint: null,
+    outPoint: null,
+    activeTool: "select" as const,
+    activeKeyframePct: null,
+    motionPathArmed: false,
+    motionPathCreateAvailable: false,
+    selectedKeyframes: new Set<string>(),
+    expandedClipIds: new Set<string>(),
+    focusedEaseSegment: null,
+    selectedElementIds: new Set<string>(),
+    requestedSeekTime: null,
+    clipRevealRequest: null,
+    lintFindingsByElement: new Map<string, { count: number; messages: string[] }>(),
+    keyframeCache: new Map<string, KeyframeCacheEntry>(),
+    gsapAnimations: new Map<string, GsapAnimation[]>(),
+    beatAnalysis: null,
+    beatEdits: null,
+    beatUndo: [],
+    beatRedo: [],
+    beatPersist: null,
+    clipManifest: null,
+    clipParentMap: new Map<string, string>(),
+    domClipChildren: [],
+  };
+}
+
 export const usePlayerStore = create<PlayerState>((set, get) => ({
   isPlaying: false,
   currentTime: 0,
   duration: 0,
   timelineReady: false,
+  timelineSessionEpoch: 0,
+  timelineProjectId: null,
   beatDragging: false,
   elements: [],
   selectedElementId: null,
@@ -436,12 +483,9 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
       return { zoomMode: "manual", manualZoomPercent: percent };
     }),
   setTimelineScale: (pps, fitPps) => {
-    // Non-reactive publish: mutate in place + reuse the same object identity so no
-    // subscriber re-renders (these fields are never a render input, only read
-    // imperatively before pinning).
     const state = get();
-    state.timelinePps = pps;
-    state.timelineFitPps = fitPps;
+    if (state.timelinePps === pps && state.timelineFitPps === fitPps) return;
+    set({ timelinePps: pps, timelineFitPps: fitPps });
   },
   setInPoint: (time) =>
     set((state) => {
@@ -465,7 +509,9 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
       };
     }),
   setManualZoomPercent: (percent) =>
-    set({ manualZoomPercent: Math.max(10, Math.min(2000, Math.round(percent))) }),
+    set((state) => ({
+      manualZoomPercent: clampTimelineZoomPercent(percent, state.timelineFitPps),
+    })),
   bumpZEditVersion: () => set((state) => ({ zEditVersion: state.zEditVersion + 1 })),
   setCurrentTime: (time) => set({ currentTime: Number.isFinite(time) ? time : 0 }),
   setDuration: (duration) => set({ duration: Number.isFinite(duration) ? duration : 0 }),
@@ -514,37 +560,19 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
         (el.key ?? el.id) === elementId ? { ...el, ...updates } : el,
       ),
     })),
-  // Resets project-specific state when switching compositions.
-  // playbackRate, audioMuted, loopEnabled, zoomMode, and manualZoomPercent are intentionally preserved
-  // because they are user preferences that should survive project switches.
-  reset: () =>
-    set({
-      isPlaying: false,
-      currentTime: 0,
-      duration: 0,
-      timelineReady: false,
-      beatDragging: false,
-      elements: [],
-      selectedElementId: null,
-      inPoint: null,
-      outPoint: null,
-      activeTool: "select",
-      selectedKeyframes: new Set(),
-      expandedClipIds: new Set(),
-      focusedEaseSegment: null,
-      selectedElementIds: new Set(),
-      clipRevealRequest: null,
-      keyframeCache: new Map(),
-      gsapAnimations: new Map(),
-      beatAnalysis: null,
-      beatEdits: null,
-      beatUndo: [],
-      beatRedo: [],
-      beatPersist: null,
-      clipManifest: null,
-      clipParentMap: new Map(),
-      domClipChildren: [],
+  // playbackRate, audioMuted, loopEnabled, zoomMode, and manualZoomPercent are
+  // intentionally absent from createTimelineResetState because they are user
+  // preferences that survive both source refreshes and project switches.
+  beginTimelineSession: (projectId) =>
+    set((state) => {
+      if (state.timelineProjectId === projectId) return state;
+      return {
+        ...createTimelineResetState(),
+        timelineSessionEpoch: state.timelineSessionEpoch + 1,
+        timelineProjectId: projectId,
+      };
     }),
+  reset: () => set(createTimelineResetState()),
 }));
 
 // Bug-bash aid: expose the store so a reproduction can dump live state from the

package/src/utils/studioHelpers.test.ts

@@ -1,13 +1,20 @@
 // @vitest-environment happy-dom
 
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   findMatchingTimelineElementId,
   findTimelineIdByAncestor,
+  resolveDroppedAssetDimensions,
   resolveTimelineIdForSelection,
   resolveTimelineSelectionSeekTime,
 } from "./studioHelpers";
 
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
 describe("resolveTimelineSelectionSeekTime", () => {
   it("keeps the current time when it is already inside the clip range", () => {
     expect(resolveTimelineSelectionSeekTime(3, { start: 0, duration: 5 })).toBe(3);
@@ -148,3 +155,43 @@ describe("resolveTimelineIdForSelection", () => {
     expect(resolveTimelineIdForSelection(selection, els, null)).toBe(null);
   });
 });
+
+describe("resolveDroppedAssetDimensions", () => {
+  it("aborts an image probe when metadata times out", async () => {
+    vi.useFakeTimers();
+    const probe = {
+      addEventListener: vi.fn(),
+      naturalHeight: 0,
+      naturalWidth: 0,
+      src: "",
+    };
+    vi.stubGlobal(
+      "Image",
+      vi.fn(() => probe),
+    );
+
+    const result = resolveDroppedAssetDimensions("demo", "assets/hung.png", "image");
+    await vi.advanceTimersByTimeAsync(3000);
+
+    await expect(result).resolves.toBeNull();
+    expect(probe.src).toBe("");
+  });
+
+  it("aborts a video probe when metadata times out", async () => {
+    vi.useFakeTimers();
+    const video = document.createElement("video");
+    const load = vi.fn();
+    Object.defineProperty(video, "load", { configurable: true, value: load });
+    const createElement = document.createElement.bind(document);
+    vi.spyOn(document, "createElement").mockImplementation((tagName, options) =>
+      tagName === "video" ? video : createElement(tagName, options),
+    );
+
+    const result = resolveDroppedAssetDimensions("demo", "assets/hung.mp4", "video");
+    await vi.advanceTimersByTimeAsync(3000);
+
+    await expect(result).resolves.toBeNull();
+    expect(video.getAttribute("src")).toBe("");
+    expect(load).toHaveBeenCalledOnce();
+  });
+});