@hyperframes/studio 0.7.55 → 0.7.57

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

@@ -3,6 +3,7 @@ import type { MusicBeatAnalysis } from "@hyperframes/core/beats";
 import type { BeatEditState } from "../../utils/beatEditing";
 import type { ClipManifestClip } from "../lib/playbackTypes";
 import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
+import { computePinnedZoomPercent } from "../components/timelineZoom";
 
 /** Minimal keyframe cache types — mirrors GsapKeyframesData without pulling in Node-only gsap-parser. */
 export interface KeyframeCacheEntry {
@@ -28,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. */
@@ -75,6 +87,10 @@ export interface TimelineElement {
 export type ZoomMode = "fit" | "manual";
 type TimelineTool = "select" | "razor";
 
+export interface SelectElementOptions {
+  preserveSet?: boolean;
+}
+
 function resolveElementSelection(
   ids: Iterable<string>,
   anchor?: string | null,
@@ -142,6 +158,28 @@ interface PlayerState {
 
   /** Multi-select: additional selected elements beyond selectedElementId. */
   selectedElementIds: Set<string>;
+  clearSelectedElementIds: () => void;
+  /** Replace the whole multi-selection at once (marquee live updates). */
+  setSelectedElementIds: (ids: Set<string>) => void;
+  /** 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
+   * 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).
+   */
+  timelinePps: number;
+  timelineFitPps: number;
+  setTimelineScale: (pps: number, fitPps: number) => void;
   setSelection: (ids: Iterable<string>, anchor?: string | null) => void;
   addSelectedElementId: (id: string) => void;
   toggleSelectedElementId: (id: string) => void;
@@ -160,7 +198,7 @@ interface PlayerState {
   setTimelineReady: (ready: boolean) => void;
   setBeatDragging: (dragging: boolean) => void;
   setElements: (elements: TimelineElement[]) => void;
-  setSelectedElementId: (id: string | null) => void;
+  setSelectedElementId: (id: string | null, options?: SelectElementOptions) => void;
   /** Move the selection anchor within an active multi-selection without collapsing it. */
   setSelectionAnchor: (id: string | null) => void;
   updateElement: (
@@ -186,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;
 
@@ -260,6 +308,8 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   loopEnabled: false,
   zoomMode: "fit",
   manualZoomPercent: 100,
+  timelinePps: 100,
+  timelineFitPps: 100,
   inPoint: null,
   outPoint: null,
 
@@ -315,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 }),
 
@@ -383,6 +440,37 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   },
   setLoopEnabled: (enabled) => set({ loopEnabled: enabled }),
   setZoomMode: (mode) => set({ zoomMode: mode }),
+  clearSelectedElementIds: () => set({ selectedElementIds: new Set() }),
+  setSelectedElementIds: (ids: Set<string>) => set({ selectedElementIds: new Set(ids) }),
+  timelineSnapEnabled: readStudioUiPreferences().timelineSnapEnabled ?? true,
+  setTimelineSnapEnabled: (enabled) => {
+    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.
+      if (s.zoomMode === "manual") return {};
+      const percent = computePinnedZoomPercent(currentPixelsPerSecond, fitPixelsPerSecond);
+      writeStudioUiPreferences({
+        timelineZoomMode: "manual",
+        timelineManualZoomPercent: percent,
+      });
+      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;
+  },
   setInPoint: (time) =>
     set((state) => {
       const t = time !== null && Number.isFinite(time) ? time : null;
@@ -414,9 +502,16 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   // A genuine single selection: always collapse the set to just this element. User
   // intent (timeline click, preview click via applyDomSelection) flows here; DOM sync
   // echoes that must preserve a group go through setSelectionAnchor instead.
-  setSelectedElementId: (id) =>
+  setSelectedElementId: (id, options) =>
     set((s) => {
-      const selectedElementIds = id ? new Set([id]) : new Set<string>();
+      const preserveSet = Boolean(options?.preserveSet && id && s.selectedElementIds.has(id));
+      const selectedElementIds = preserveSet
+        ? new Set(s.selectedElementIds)
+        : options?.preserveSet
+          ? new Set<string>()
+          : id
+            ? new Set([id])
+            : new Set<string>();
       // Selecting a different element drops any active keyframe selection — otherwise
       // a stale activeKeyframePct from a prior diamond click would force the next drag
       // to "modify" a keyframe on the new element. A diamond click sets the pct AFTER
@@ -463,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/styles/studio.css

@@ -141,6 +141,22 @@ body {
   opacity: 1;
 }
 
+/* Audio clips read as a distinct kind — a persistent violet tint vs the teal-
+   accented visual clips — so the audio zone at the bottom is visually separate
+   at a glance (the timeline's kinds: visual on top, audio below). */
+.timeline-clip.is-audio {
+  background-color: rgba(167, 139, 250, 0.16);
+  border-color: rgba(167, 139, 250, 0.4);
+}
+
+.timeline-clip.is-audio.is-hovered {
+  background-color: rgba(167, 139, 250, 0.24);
+}
+
+.timeline-clip.is-audio.is-dragging {
+  background-color: rgba(60, 52, 84, 0.96);
+}
+
 .timeline-clip.is-hovered {
   background-color: rgba(255, 255, 255, 0.09);
 }
@@ -158,9 +174,20 @@ body {
 }
 
 .timeline-clip.is-dragging {
+  /* Solid background so the picked-up clip reads clearly while dragging — audio
+     clips (waveform drawn on a separate layer) would otherwise look transparent. */
+  background-color: rgba(38, 42, 52, 0.96);
   box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
 }
 
+/* Keep the white selection outline while dragging (a plain box-shadow alone gets
+   overridden by .is-dragging's drop shadow, so re-state both together). */
+.timeline-clip.is-selected.is-dragging {
+  box-shadow:
+    0 0 0 1.5px rgba(255, 255, 255, 0.85),
+    0 8px 24px rgba(0, 0, 0, 0.4);
+}
+
 .timeline-clip[data-active].is-selected.is-dragging {
   box-shadow:
     0 0 0 1.5px rgba(255, 255, 255, 0.85),

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/assetPreviewStore.ts

@@ -0,0 +1,33 @@
+/**
+ * Tiny Zustand slice that carries the "asset preview overlay" state.
+ *
+ * When a user clicks an asset card that has NOT yet been added to the
+ * timeline the overlay fires up: a dark scrim + centered media element
+ * (img / video / audio) + filename label rendered inside PreviewPane.
+ *
+ * State lives here so AssetsTab (sidebar) and PreviewPane (preview column)
+ * can communicate without prop-drilling through the multi-layer EditorShell
+ * tree. The store is project-scoped: NLEProvider (NLEContext.tsx) clears it
+ * whenever `projectId` changes, so a preview opened in one project can't
+ * bleed into another (the overlay itself stays mounted across project
+ * switches — EditorShell isn't keyed by projectId).
+ */
+import { create } from "zustand";
+
+interface AssetPreviewState {
+  /** Project-relative asset path currently being previewed, or null. */
+  previewAsset: string | null;
+  /** projectId for which the preview was opened (used to build the serve URL). */
+  previewProjectId: string | null;
+  /** Open a media preview for the given asset. */
+  setPreviewAsset: (asset: string, projectId: string) => void;
+  /** Close the preview overlay. */
+  clearPreviewAsset: () => void;
+}
+
+export const useAssetPreviewStore = create<AssetPreviewState>((set) => ({
+  previewAsset: null,
+  previewProjectId: null,
+  setPreviewAsset: (asset, projectId) => set({ previewAsset: asset, previewProjectId: projectId }),
+  clearPreviewAsset: () => set({ previewAsset: null, previewProjectId: null }),
+}));

package/src/utils/blockInstaller.ts

@@ -2,9 +2,10 @@ import type { RegistryItem } from "@hyperframes/core/registry";
 import type { TimelineElement } from "../player";
 import {
   insertTimelineAssetIntoSource,
-  resolveTimelineAssetInitialGeometry,
+  resolveTimelineAssetCompositionSize,
 } from "./timelineAssetDrop";
 import { collectHtmlIds } from "./studioHelpers";
+import { generateId } from "./generateId";
 import { formatTimelineAttributeNumber } from "../player/components/timelineEditing";
 import { saveProjectFilesWithHistory } from "./studioFileHistory";
 import type { EditHistoryKind } from "./editHistory";
@@ -120,7 +121,9 @@ export async function addBlockToProject(
       );
 
       const isBlock = block.type === "hyperframes:block";
-      const hostDims = resolveTimelineAssetInitialGeometry(originalContent);
+      const { width: hostWidth, height: hostHeight } =
+        resolveTimelineAssetCompositionSize(originalContent);
+      const hostDims = { left: 0, top: 0, width: hostWidth, height: hostHeight };
 
       const currentTime = opts.currentTime ?? 0;
       const start = placement
@@ -152,6 +155,11 @@ export async function addBlockToProject(
 
       const subCompHtml = [
         `<div`,
+        // A stable id (+ hf-id) is what authored sub-comps carry; without it the
+        // timeline can't dedup the host and renders duplicate clips that multiply
+        // on every interaction. Matches the authored-comp shape.
+        `  id="${compId}"`,
+        `  data-hf-id="hf-${generateId()}"`,
         `  data-composition-id="${compId}"`,
         `  data-composition-src="${compositionFile}"`,
         `  data-start="${formatTimelineAttributeNumber(start)}"`,

package/src/utils/editHistory.test.ts

@@ -209,6 +209,41 @@ describe("edit history", () => {
     expect(state.undo[0].files["index.html"].after).toBe("c");
   });
 
+  it("merges a lane-change move with its z-reorder past the default window via entry coalesceMs", () => {
+    // The z entry records only after the move persist's round-trip — often >300ms.
+    // Both sides pass coalesceMs: 5000 with the shared gesture key so the pair
+    // still folds into ONE undo step.
+    const move = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Move timeline clips",
+      kind: "timeline",
+      coalesceKey: "clip-lane-move:1",
+      coalesceMs: 5000,
+      files: { "index.html": { before: "a", after: "b" } },
+      now: 100,
+      id: "move-entry",
+    });
+    const zReorder = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Reorder layers",
+      kind: "manual",
+      coalesceKey: "clip-lane-move:1",
+      coalesceMs: 5000,
+      files: { "index.html": { before: "b", after: "c" } },
+      now: 500,
+      id: "z-entry",
+    });
+
+    const state = pushEditHistoryEntry(
+      pushEditHistoryEntry(createEmptyEditHistory(), move),
+      zReorder,
+    );
+
+    expect(state.undo).toHaveLength(1);
+    expect(state.undo[0].files["index.html"].before).toBe("a");
+    expect(state.undo[0].files["index.html"].after).toBe("c");
+  });
+
   it("folds a slow GSAP follow-up into the timing edit via a per-entry coalesceMs override", () => {
     const timing = buildEditHistoryEntry({
       projectId: "project-1",

package/src/utils/gsapSoftReload.test.ts

@@ -1,7 +1,12 @@
 // @vitest-environment happy-dom
 
 import { describe, it, expect, vi } from "vitest";
-import { applySoftReload, ensureMotionPathPluginLoaded } from "./gsapSoftReload";
+import {
+  applySoftReload,
+  ensureMotionPathPluginLoaded,
+  diffSoftReloadableRestore,
+  applyUndoRestoreToPreview,
+} from "./gsapSoftReload";
 
 const SCRIPT_TEXT = `
 window.__timelines = window.__timelines || {};
@@ -447,3 +452,116 @@ describe("applySoftReload authored-opacity restore", () => {
     expect(restoreOpacity(el)).toBe("");
   });
 });
+
+// ── Bug 2: undo/redo restore soft-apply ──────────────────────────────────────
+
+const wrap = (body: string) => `<html><body>${body}</body></html>`;
+
+describe("diffSoftReloadableRestore", () => {
+  it("reports the changed id for an attribute/inline-style-only diff", () => {
+    const prev = wrap(`<div id="a" style="translate: 10px 10px">t</div>`);
+    const next = wrap(`<div id="a" style="translate: 0px 0px">t</div>`);
+    expect(diffSoftReloadableRestore(prev, next)).toEqual({ changedElementIds: ["a"] });
+  });
+
+  it("treats a structural change (added element) as NOT soft-reloadable", () => {
+    const prev = wrap(`<div id="a">t</div>`);
+    const next = wrap(`<div id="a">t</div><div id="a-split">t</div>`);
+    expect(diffSoftReloadableRestore(prev, next)).toBeNull();
+  });
+
+  it("treats an element text/child change as NOT soft-reloadable", () => {
+    const prev = wrap(`<div id="a">one</div>`);
+    const next = wrap(`<div id="a">two</div>`);
+    expect(diffSoftReloadableRestore(prev, next)).toBeNull();
+  });
+
+  it("allows a GSAP-script-only change (no id'd-attribute diff)", () => {
+    const prev = wrap(
+      `<div id="a">t</div><script>window.__timelines["root"]=gsap.timeline().to("#a",{x:1});</script>`,
+    );
+    const next = wrap(
+      `<div id="a">t</div><script>window.__timelines["root"]=gsap.timeline().to("#a",{x:9});</script>`,
+    );
+    expect(diffSoftReloadableRestore(prev, next)).toEqual({ changedElementIds: [] });
+  });
+});
+
+function buildLiveIframe(bodyHtml: string) {
+  const doc = document.implementation.createHTMLDocument("");
+  doc.body.innerHTML = bodyHtml;
+  const contentWindow = {
+    gsap: { timeline: () => {} },
+    __hfForceTimelineRebind: () => {},
+    __timelines: {} as Record<string, unknown>,
+    __player: { getTime: () => 3, seek: vi.fn() },
+    __hfStudioManualEditsApply: vi.fn(),
+  };
+  return {
+    iframe: { contentWindow, contentDocument: doc } as unknown as HTMLIFrameElement,
+    contentWindow,
+    doc,
+  };
+}
+
+describe("applyUndoRestoreToPreview", () => {
+  const ROOT = "index.html";
+
+  it("soft-applies an attribute/style-only restore: syncs the live element, no full reload", () => {
+    const { iframe, contentWindow, doc } = buildLiveIframe(
+      `<div id="a" style="translate: 10px 10px" data-hf-path-offset="true">t</div>`,
+    );
+    const reloadPreview = vi.fn();
+    const files = {
+      [ROOT]: {
+        previous: wrap(
+          `<div id="a" style="translate: 10px 10px" data-hf-path-offset="true">t</div>`,
+        ),
+        restored: wrap(`<div id="a" style="translate: 0px 0px" data-hf-path-offset="true">t</div>`),
+      },
+    };
+    const outcome = applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview);
+    expect(outcome).toBe("soft");
+    expect(reloadPreview).not.toHaveBeenCalled();
+    // Live element reverted to the restored inline style.
+    expect(doc.getElementById("a")!.getAttribute("style")).toBe("translate: 0px 0px");
+    // No GSAP script in the restore → the manual-edit reapply runs, playhead held.
+    expect(contentWindow.__player.seek).toHaveBeenCalledWith(3);
+    expect(contentWindow.__hfStudioManualEditsApply).toHaveBeenCalled();
+  });
+
+  it("full-reloads a multi-file restore", () => {
+    const { iframe } = buildLiveIframe(`<div id="a">t</div>`);
+    const reloadPreview = vi.fn();
+    const files = {
+      [ROOT]: {
+        previous: wrap(`<div id="a" style="x">t</div>`),
+        restored: wrap(`<div id="a">t</div>`),
+      },
+      "scenes/intro.html": { previous: "a", restored: "b" },
+    };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+  });
+
+  it("full-reloads a structural restore (split/delete undo)", () => {
+    const { iframe } = buildLiveIframe(`<div id="a">t</div><div id="a-split">t</div>`);
+    const reloadPreview = vi.fn();
+    const files = {
+      [ROOT]: {
+        previous: wrap(`<div id="a">t</div><div id="a-split">t</div>`),
+        restored: wrap(`<div id="a">t</div>`),
+      },
+    };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+  });
+
+  it("full-reloads when the restore touches a sub-comp, not the active comp", () => {
+    const { iframe } = buildLiveIframe(`<div id="a">t</div>`);
+    const reloadPreview = vi.fn();
+    const files = { "scenes/intro.html": { previous: "a", restored: "b" } };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+  });
+});