@hyperframes/studio 0.8.104 → 0.8.106

package/src/player/components/TimelineEmptyState.tsx

@@ -63,13 +63,13 @@ export function TimelineEmptyState({
                 strokeWidth="1.5"
                 strokeLinecap="round"
                 strokeLinejoin="round"
-                className="text-studio-accent shrink-0"
+                className="text-accent-ink shrink-0"
               >
                 <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
                 <polyline points="7 10 12 15 17 10" />
                 <line x1="12" y1="15" x2="12" y2="3" />
               </svg>
-              <span className="text-[13px] text-studio-accent">Drop media files to import</span>
+              <span className="text-[13px] text-accent-ink">Drop media files to import</span>
             </>
           ) : (
             <>

package/src/player/components/TimelineLanes.tsx

@@ -353,7 +353,6 @@ export function TimelineLanes({
                       fontSize: 11,
                       letterSpacing: "0.06em",
                       textTransform: "uppercase",
-                      opacity: 0.5,
                     }}
                   >
                     New track

package/src/player/components/TrackClipCount.tsx

@@ -9,7 +9,7 @@ export function TrackClipCount({ clipCount }: { clipCount: number }) {
     <span
       aria-label={`${clipCount} clips`}
       title={`${clipCount} clips`}
-      className="shrink-0 rounded-full bg-white/10 px-1 text-[9px] leading-[14px] tabular-nums text-white/55"
+      className="shrink-0 rounded-full bg-hover px-1 text-[9px] leading-[14px] tabular-nums text-text-muted"
     >
       {clipCount}
     </span>

package/src/player/components/VolumeControl.tsx

@@ -93,7 +93,7 @@ export const VolumeControl = memo(function VolumeControl({
           aria-label={muteLabel}
           aria-pressed={silent}
           className={`flex h-7 w-7 shrink-0 items-center justify-center rounded-md transition-colors disabled:pointer-events-none disabled:opacity-30 ${
-            silent ? "text-studio-accent" : "text-neutral-500 hover:text-neutral-200"
+            silent ? "text-accent-ink" : "text-neutral-500 hover:text-neutral-200"
           }`}
         >
           <VolumeIcon muted={audioMuted} volume={audioVolume} />

package/src/player/components/timelineClipChildren.tsx

@@ -22,7 +22,7 @@ function ClipLintDot({ element }: { element: TimelineElement }) {
   if (!lint || lint.count === 0) return null;
   return (
     <span
-      className="absolute w-1.5 h-1.5 rounded-full bg-amber-400"
+      className="absolute w-1.5 h-1.5 rounded-full bg-warning-ink"
       style={{ top: 7, right: 7 }}
       title={lint.messages.join("\n")}
     />

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

@@ -39,18 +39,15 @@ function themeTokenValue(token: string): string {
 
 describe("timeline motion styles", () => {
   it.each([
-    ["--timeline-track-label", "rgba(255, 255, 255, 0.5)"],
-    ["--timeline-tick-text", "rgba(255, 255, 255, 0.34)"],
-    ["--timeline-border-strong", "rgba(255, 255, 255, 0.2)"],
-    ["--timeline-group-member-tint", "rgba(255, 255, 255, 0.035)"],
-    ["--timeline-overlay-text", "rgba(255, 255, 255, 0.8)"],
-    ["--timeline-clip-shadow-dragging", "rgba(0, 0, 0, 0.4)"],
-    ["--timeline-playhead-glow", "rgba(60, 230, 172, 0.14)"],
-    ["--timeline-playhead-shadow", "rgba(0, 0, 0, 0.55)"],
+    ["--timeline-track-label", "var(--color-text-muted)"],
+    ["--timeline-tick-text", "var(--color-text-2)"],
+    ["--timeline-border-strong", "color-mix(in oklab, var(--color-text-0) 20%, transparent)"],
+    ["--timeline-group-member-tint", "color-mix(in oklab, var(--color-text-0) 3.5%, transparent)"],
+    ["--timeline-overlay-text", "var(--color-text-2)"],
+    ["--timeline-playhead-glow", "color-mix(in oklab, var(--color-accent) 14%, transparent)"],
   ])("keeps the migrated default for %s", (token, expected) => {
     expect(themeTokenValue(token)).toBe(expected);
   });
-
   it("keeps clip motion reduced-motion gated and layout safe", () => {
     const mediaStart = studioCss.indexOf("@media (prefers-reduced-motion: no-preference)");
     expect(mediaStart).toBeGreaterThanOrEqual(0);
@@ -93,13 +90,7 @@ describe("timeline motion styles", () => {
     expect(timelineClipLabelRule).toContain("text-overflow: ellipsis");
     expect(timelineClipLabelRule).toContain("max-width: calc(100% - 22px)");
     expect(timelineClipTimecodeRule).toContain("color: var(--timeline-tick-text)");
-    expect(themeCss).toContain("--timeline-clip-bg: rgba(255, 255, 255, 0.12)");
-    expect(themeCss).toContain("--timeline-clip-border: rgba(255, 255, 255, 0.22)");
-    expect(themeCss).toContain("--timeline-track-label: rgba(255, 255, 255, 0.5)");
-    expect(themeCss).toContain("--timeline-tick-text: rgba(255, 255, 255, 0.34)");
-    expect(themeCss).toContain("--timeline-clip-label-active: rgba(232, 255, 247, 0.95)");
     expect(themeCss).toContain("--timeline-clip-label-shadow: 0 1px 2px rgba(0, 0, 0, 0.85)");
-    expect(themeCss).toContain("--timeline-clip-selection: rgba(255, 255, 255, 0.85)");
     expect(themeCss).toContain("--timeline-clip-selection-highlight: rgb(255 255 255 / 0.55)");
     expect(themeCss).toContain("--timeline-clip-radius: 8px");
     expect(themeCss).toContain("--timeline-clip-audio-radius: 21px");
@@ -108,18 +99,11 @@ describe("timeline motion styles", () => {
     expect(themeCss).toContain("--timeline-clip-chip-bg: rgba(15, 22, 18, 0.73)");
     expect(themeCss).toContain("--timeline-clip-chip-audio-bg: rgba(25, 16, 38, 0.7)");
     expect(themeCss).toContain("--timeline-clip-chip-text: #ffffff");
-    expect(themeCss).toContain("--timeline-row-bg: #edf0ed");
     expect(themeCss).toContain("--timeline-clip-shadow: 0 2px 6px rgb(0 0 0 / 0.12)");
-    expect(themeCss).toContain("--timeline-clip-selection: #0f766e");
-    expect(themeCss).toContain("--timeline-clip-audio-bg: rgba(167, 139, 250, 0.16)");
-    expect(themeCss).toContain("--timeline-clip-audio-border: rgba(167, 139, 250, 0.4)");
-    expect(themeCss).toContain("--timeline-clip-audio-bg-hover: rgba(167, 139, 250, 0.24)");
-    expect(themeCss).toContain("--timeline-clip-audio-bg-dragging: rgba(60, 52, 84, 0.96)");
     expect(audioClipRule).toContain("background-color: var(--timeline-clip-audio-bg)");
     expect(audioClipRule).toContain("border-color: var(--timeline-clip-audio-border)");
     expect(audioClipHoverRule).toContain("background-color: var(--timeline-clip-audio-bg-hover)");
     expect(audioClipDraggingRule).toContain("var(--timeline-clip-audio-bg-dragging)");
-    expect(themeCss).toContain("--timeline-clip-selection: rgba(255, 255, 255, 0.85)");
     expect(selectedTimelineClipRule).toContain(
       "outline: 1.5px solid var(--timeline-clip-selection)",
     );

package/src/player/components/trackHeaderLabelRows.tsx

@@ -38,8 +38,8 @@ function PropertyGroupNavigation({
   // target is met with a centered transparent ::before overlay instead of a
   // bigger box; focus-visible matches every other control in this header.
   const CHEVRON_BUTTON_CLASS =
-    "relative h-5 w-3 border-0 bg-transparent p-0 text-white/55 hover:text-white disabled:text-white/15 " +
-    "focus-visible:outline-solid focus-visible:outline-1 focus-visible:outline-[#3CE6AC] " +
+    "relative h-5 w-3 border-0 bg-transparent p-0 text-text-2 hover:text-text-0 disabled:text-text-off " +
+    "focus-visible:outline-solid focus-visible:outline-1 focus-visible:outline-ring " +
     "before:absolute before:left-1/2 before:top-1/2 before:h-6 before:w-6 " +
     "before:-translate-x-1/2 before:-translate-y-1/2 before:content-['']";
   const seekTo = (keyframe: { percentage: number } | null) => {
@@ -120,7 +120,7 @@ export function PropertyGroupHeaderRow({
       tabIndex={rovingTargetId === timelinePropertyRowId(elementId, lane.group) ? 0 : -1}
       data-property-group={lane.group}
       data-timeline-lane-top={getTimelineLaneTop(laneIndex)}
-      className="absolute left-0 flex items-center gap-1 overflow-hidden px-1.5 text-[10px] text-white/65"
+      className="absolute left-0 flex items-center gap-1 overflow-hidden px-1.5 text-[10px] text-text-2"
       style={{
         top: getTimelineLaneTop(laneIndex),
         // The header column narrows to contentOrigin whenever that is under
@@ -134,12 +134,12 @@ export function PropertyGroupHeaderRow({
       {/* Tree connector: vertical spine (top-half on the last lane) + branch tick. */}
       <span className="relative h-full w-3 shrink-0" aria-hidden="true">
         <span
-          className="absolute left-1.5 top-0 w-px bg-white/15"
+          className="absolute left-1.5 top-0 w-px bg-text-0/15"
           style={{ height: isLastLane ? "50%" : "100%" }}
         />
-        <span className="absolute left-1.5 top-1/2 h-px w-1.5 bg-white/15" />
+        <span className="absolute left-1.5 top-1/2 h-px w-1.5 bg-text-0/15" />
       </span>
-      <span className="w-[46px] shrink-0 truncate text-white" title={label}>
+      <span className="w-[46px] shrink-0 truncate text-text-0" title={label}>
         {label}
       </span>
       <PropertyGroupNavigation
@@ -154,7 +154,7 @@ export function PropertyGroupHeaderRow({
           aria-label={`${navigation.currentKeyframe ? "Remove" : "Add"} ${label} keyframe`}
           title={`${navigation.currentKeyframe ? "Remove" : "Add"} ${label} keyframe`}
           // h-6 w-6 = the 24x24 WCAG 2.2 minimum target; the ◆ glyph stays 11px.
-          className="flex h-6 w-6 shrink-0 items-center justify-center border-0 bg-transparent p-0 text-[11px] text-[#3CE6AC] focus-visible:outline-solid focus-visible:outline-1 focus-visible:outline-[#3CE6AC]"
+          className="flex h-6 w-6 shrink-0 items-center justify-center border-0 bg-transparent p-0 text-[11px] text-accent-ink focus-visible:outline-solid focus-visible:outline-1 focus-visible:outline-ring"
           onClick={(event) => {
             // Same as the disclosure caret and the eye: a control in the label
             // column owns its click, it does not also hit the track row behind it.
@@ -168,7 +168,7 @@ export function PropertyGroupHeaderRow({
         </button>
       </PropertyGroupNavigation>
       <span
-        className="min-w-0 flex-1 truncate text-right tabular-nums text-white/45"
+        className="min-w-0 flex-1 truncate text-right tabular-nums text-text-muted"
         title={valueReadout(lane.group, values)}
       >
         {valueReadout(lane.group, values)}
@@ -231,7 +231,7 @@ export function AutomationLaneHeaderRow({
     <div
       data-automation-lane-label={label}
       data-timeline-lane-top={top}
-      className="absolute left-0 flex items-center gap-1 overflow-hidden px-1.5 text-[10px] text-white/65"
+      className="absolute left-0 flex items-center gap-1 overflow-hidden px-1.5 text-[10px] text-text-2"
       style={{
         top,
         width: columnWidth,
@@ -243,10 +243,10 @@ export function AutomationLaneHeaderRow({
           tick at the name's own height. */}
       <span className="relative h-full w-3 shrink-0" aria-hidden="true">
         <span
-          className="absolute left-1.5 top-0 w-px bg-white/15"
+          className="absolute left-1.5 top-0 w-px bg-text-0/15"
           style={{ height: isLastLane ? "50%" : "100%" }}
         />
-        <span className="absolute left-1.5 top-1/2 h-px w-1.5 bg-white/15" />
+        <span className="absolute left-1.5 top-1/2 h-px w-1.5 bg-text-0/15" />
       </span>
       {/* Two lines: what the effect is, then which knob the envelope drives. On
           one line a band's own name was the first thing truncated in a column this
@@ -262,7 +262,7 @@ export function AutomationLaneHeaderRow({
         aria-label={onReveal ? `Show ${label} in the effect rack` : undefined}
         title={onReveal ? `Show ${label} in the effect rack` : label}
         disabled={!onReveal}
-        className="flex min-w-0 flex-1 flex-col justify-center rounded-sm border-0 bg-transparent p-0 text-left leading-tight enabled:hover:text-white focus-visible:outline-solid focus-visible:outline-1 focus-visible:outline-[#3CE6AC]"
+        className="flex min-w-0 flex-1 flex-col justify-center rounded-sm border-0 bg-transparent p-0 text-left leading-tight enabled:hover:text-text-0 focus-visible:outline-solid focus-visible:outline-1 focus-visible:outline-ring"
         onPointerDown={(event) => event.stopPropagation()}
         onClick={(event) => {
           // The label column owns its click; it does not also fall through to
@@ -271,13 +271,13 @@ export function AutomationLaneHeaderRow({
           onReveal?.();
         }}
       >
-        <span data-automation-lane-name="" className="truncate font-mono text-[9px] text-white/70">
+        <span data-automation-lane-name="" className="truncate font-mono text-[9px] text-text-2">
           {name}
         </span>
         {param ? (
           <span
             data-automation-lane-param=""
-            className="truncate font-mono text-[9px] text-white/40"
+            className="truncate font-mono text-[9px] text-text-muted"
           >
             {param}
           </span>
@@ -285,7 +285,7 @@ export function AutomationLaneHeaderRow({
         {alsoAutomatedBy ? (
           <span
             data-automation-lane-also=""
-            className="truncate text-[9px] text-[#F5C542]/80"
+            className="truncate text-[9px] text-warning-ink"
             title={`${alsoAutomatedBy} is also fading this — the two multiply.`}
           >
             {alsoAutomatedBy} is also fading this.
@@ -311,7 +311,7 @@ export function AutomationLaneHeaderRow({
           aria-label={`Remove ${label} automation`}
           title={`Remove ${label} automation`}
           // h-6 w-6 is the 24x24 WCAG 2.2 target; the glyph stays small.
-          className="flex h-6 w-6 shrink-0 items-center justify-center border-0 bg-transparent p-0 text-[11px] text-white/35 hover:text-white focus-visible:outline-solid focus-visible:outline-1 focus-visible:outline-[#3CE6AC]"
+          className="flex h-6 w-6 shrink-0 items-center justify-center border-0 bg-transparent p-0 text-[11px] text-text-muted hover:text-text-0 focus-visible:outline-solid focus-visible:outline-1 focus-visible:outline-ring"
           onPointerDown={(event) => event.stopPropagation()}
           onClick={(event) => {
             // A control in the label column owns its click; it does not also hit

package/src/player/components/useTimelineKeyboardActor.ts

@@ -22,7 +22,7 @@ function eventTarget(event: FocusEvent | KeyboardEvent): HTMLElement | null {
   // Header actions stay native Tab stops because they have no row-level shortcut.
   // The nearest interactive ancestor wins so their events never masquerade as row events.
   const target = event.target.closest<HTMLElement>(
-    "button, input, select, textarea, a[href], [contenteditable], [data-timeline-focus-id]",
+    "button, input, select, textarea, a[href], [contenteditable], [role='slider'], [data-timeline-focus-id]",
   );
   return target?.dataset.timelineFocusId && event.currentTarget.contains(target) ? target : null;
 }

package/src/player/hooks/timelinePlayerTestHarness.ts

@@ -118,3 +118,30 @@ export function attachIframeAdapter(
   attachIframeWindow(api, win);
   return adapter;
 }
+
+export function makePreview(body: string, query = ""): HTMLIFrameElement {
+  const iframe = makeFakeIframe(makeAdapterWindow().win);
+  iframe.src = `http://localhost/api/projects/demo/preview${query}`;
+  iframe.contentDocument!.body.innerHTML = body;
+  return iframe;
+}
+
+export function mountPlayerWithPreview(live: HTMLIFrameElement) {
+  const harness = renderTimelinePlayerHarness();
+  act(() => {
+    harness.getApi().iframeRef.current = live;
+    harness.getApi().onIframeLoad();
+  });
+  return harness;
+}
+
+export async function paintShadow(getApi: () => TimelinePlayerApi, shadow: HTMLIFrameElement) {
+  const slot = getApi().previewSlots.find((s) => s.role === "shadow");
+  if (!slot) throw new Error("no shadow reload is pending");
+  act(() => getApi().setShadowIframeNode(shadow));
+  await act(async () => {
+    getApi().onShadowIframeLoad(slot.gen);
+    getApi().onShadowReadyChange(slot.gen, true);
+  });
+  return slot.gen;
+}

package/src/player/hooks/useShadowPreviewReload.ts

@@ -3,6 +3,11 @@
 
 import { useCallback, useRef, useState } from "react";
 import { useMountEffect } from "../../hooks/useMountEffect";
+import {
+  afterStudioManualEditGestures,
+  isStudioManualEditGestureLiveIn,
+  studioManualEditSavesIn,
+} from "../../components/editor/manualEditsDom";
 import { logReload } from "../../utils/reloadDebug";
 import {
   useTimelineSyncCallbacks,
@@ -14,6 +19,8 @@ import {
 } from "./useTimelineSyncCallbacks";
 import type { IframeWindow, PlaybackAdapter } from "../lib/playbackTypes";
 import { thumbnailScheduler } from "../lib/thumbnailScheduler";
+import { announcePreviewPromoted } from "../sceneSwap";
+import { afterStudioPendingEdits, isStudioEditSaving } from "../../utils/studioPendingEdits";
 import { usePlayerStore } from "../store/playerStore";
 
 // One wait budget for a shadow: the player's 8s asset cap plus its 0.42s loader fade
@@ -78,12 +85,18 @@ export function useShadowPreviewReload({
   // The shadow still owed a wait budget, so a hidden tab can resume it when it becomes visible.
   const budgetGenRef = useRef<number | null>(null);
   const cancelPendingLoadRef = useRef<() => void>(() => {});
+  const stopHoldRef = useRef<() => void>(() => {});
+  const shadowUrlRef = useRef("");
+  const savesAtRequestRef = useRef(0);
+  const beginShadowReloadRef = useRef<(url: string) => void>(() => {});
+  const promoteWhenReadyRef = useRef<(gen: number) => void>(() => {});
   const [previewSlots, setPreviewSlots] = useState<PreviewIframeSlot[]>([{ gen: 0, role: "live" }]);
 
   const stopPendingShadow = useCallback(() => {
     clearTimeout(readyTimerRef.current);
     budgetGenRef.current = null;
     cancelPendingLoadRef.current();
+    stopHoldRef.current();
     pendingCommitRef.current = null;
     visuallyReadyGenRef.current = null;
   }, []);
@@ -106,12 +119,58 @@ export function useShadowPreviewReload({
     [stopPendingShadow, isRefreshingRef, pendingSeekRef],
   );
 
+  const gestureSavesOnScreen = useCallback(() => {
+    const liveDoc = iframeRef.current?.contentDocument;
+    return liveDoc ? studioManualEditSavesIn(liveDoc) : 0;
+  }, [iframeRef]);
+
+  const waitThenRetry = useCallback(
+    (gen: number, why: string, wait: (retry: () => void) => () => void) => {
+      clearTimeout(readyTimerRef.current);
+      budgetGenRef.current = null;
+      stopHoldRef.current();
+      logReload("shadow-held", { gen, why });
+      stopHoldRef.current = wait(() => {
+        logReload("shadow-hold-ended", { gen, why });
+        promoteWhenReadyRef.current(gen);
+      });
+      return true;
+    },
+    [],
+  );
+
+  // Nothing replaces the preview under a gesture, and a shadow requested before a gesture's save
+  // shows the file before it: once that save has landed, a fresh one loads instead.
+  const heldOrStale = useCallback(
+    (gen: number) => {
+      const liveDoc = iframeRef.current?.contentDocument;
+      if (liveDoc && isStudioManualEditGestureLiveIn(liveDoc))
+        return waitThenRetry(gen, "gesture", (retry) =>
+          afterStudioManualEditGestures(liveDoc, retry),
+        );
+      if (gestureSavesOnScreen() === savesAtRequestRef.current) return false;
+      if (isStudioEditSaving()) return waitThenRetry(gen, "save", afterStudioPendingEdits);
+      logReload("shadow-reloaded-after-gesture-save", { gen });
+      const url = new URL(shadowUrlRef.current, window.location.origin);
+      url.searchParams.set("_t", String(Date.now()));
+      beginShadowReloadRef.current(url.toString());
+      return true;
+    },
+    [iframeRef, gestureSavesOnScreen, waitThenRetry],
+  );
+
+  const shadowReadyToPromote = useCallback((gen: number) => {
+    const shadow = shadowIframeRef.current;
+    const pending = pendingCommitRef.current;
+    const ready = pending?.gen === gen && visuallyReadyGenRef.current === gen;
+    return shadow && pending && ready && gen === shadowGenRef.current ? { shadow, pending } : null;
+  }, []);
+
   const promoteWhenReady = useCallback(
     (gen: number) => {
-      const shadow = shadowIframeRef.current;
-      const pending = pendingCommitRef.current;
-      const ready = pending?.gen === gen && visuallyReadyGenRef.current === gen;
-      if (!shadow || !pending || !ready || gen !== shadowGenRef.current) return;
+      const promotable = shadowReadyToPromote(gen);
+      if (!promotable || heldOrStale(gen)) return;
+      const { shadow, pending } = promotable;
       stopPendingShadow();
       // The live frame kept playing, stopped at the end or was seeked while the shadow loaded.
       const live = getAdapter();
@@ -119,6 +178,7 @@ export function useShadowPreviewReload({
       const playing = usePlayerStore.getState().isPlaying;
       live?.pause();
       // The store takes the new document's timeline only now that it is the one on screen, and reads it there.
+      const retired = iframeRef.current;
       iframeRef.current = shadow;
       pending.commit();
       shadowIframeRef.current = null;
@@ -126,17 +186,21 @@ export function useShadowPreviewReload({
       applyPreviewAudioState();
       setPreviewSlots((prev) => planShadowPromotion(prev, gen));
       if (liveTime != null) handOverPlaybackRef.current(liveTime, playing);
+      announcePreviewPromoted({ retired, live: shadow });
       onPromotedRef.current?.();
       thumbnailScheduler.setPreviewReloading(false);
     },
     [
       stopPendingShadow,
+      shadowReadyToPromote,
+      heldOrStale,
       getAdapter,
       iframeRef,
       attachIframeShortcutListeners,
       applyPreviewAudioState,
     ],
   );
+  promoteWhenReadyRef.current = promoteWhenReady;
 
   const getShadowAdapter = useCallback(() => getAdapter(shadowIframeRef.current), [getAdapter]);
   const isCurrentShadow = useCallback((gen?: number) => gen === shadowGenRef.current, []);
@@ -216,13 +280,16 @@ export function useShadowPreviewReload({
       stopPendingShadow();
       budgetGenRef.current = gen;
       budgetsSpentRef.current = 0;
+      shadowUrlRef.current = url;
+      savesAtRequestRef.current = gestureSavesOnScreen();
       armReadyTimer(gen);
       setPreviewSlots((prev) => planShadowReload(prev, gen, url));
       // Thumbnails of the edit wait for the new preview instead of competing with it.
       thumbnailScheduler.setPreviewReloading(true);
     },
-    [stopPendingShadow, armReadyTimer],
+    [stopPendingShadow, armReadyTimer, gestureSavesOnScreen],
   );
+  beginShadowReloadRef.current = beginShadowReload;
 
   // Composition switch (not an edit reload): drop any in-flight shadow.
   const resetPreviewSlots = useCallback(() => {

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

@@ -1,6 +1,6 @@
 // @vitest-environment happy-dom
 import { beforeEach, describe, expect, it } from "vitest";
-import { syncStoredAutomationFromPreview } from "./automationStoreSync";
+import { syncStoredAutomationFromPreview, syncStoredElementAttribute } from "./automationStoreSync";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 
 const TWO_POINTS = '{"version":1,"lanes":[{"target":"volume","points":[{"t":0,"v":1}]}]}';
@@ -32,7 +32,24 @@ beforeEach(() => {
   usePlayerStore.getState().reset();
 });
 
+describe("syncStoredElementAttribute", () => {
+  it("records a saved fade on the stored clip, so the timeline draws what the file holds", () => {
+    usePlayerStore.setState({ elements: [el({ fadeIn: 1 })] });
+    syncStoredElementAttribute(el(), "data-fade-in", "2.5");
+    expect(usePlayerStore.getState().elements[0]?.fadeIn).toBe(2.5);
+    syncStoredElementAttribute(el(), "data-fade-in", null);
+    expect(usePlayerStore.getState().elements[0]?.fadeIn).toBeUndefined();
+  });
+});
+
 describe("syncStoredAutomationFromPreview", () => {
+  it("reads back a fade an undo restored on the preview", () => {
+    usePlayerStore.setState({ elements: [el({ fadeOut: 2 })] });
+    syncStoredAutomationFromPreview(previewWith({ "data-fade-in": "0.6" }));
+    const stored = usePlayerStore.getState().elements[0];
+    expect([stored?.fadeIn, stored?.fadeOut]).toEqual([0.6, undefined]);
+  });
+
   it("reads the element the timeline bound, not an earlier same-id copy in a sub-composition", () => {
     usePlayerStore.setState({ elements: [el({ hfId: "hf-root" })] });
     const doc = document.implementation.createHTMLDocument("preview");

package/src/player/lib/automationStoreSync.ts

@@ -16,12 +16,18 @@
 
 import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";
 import { HF_AUDIO_FX_ATTR } from "@hyperframes/core/audio-fx";
+import {
+  HF_AUDIO_FADE_IN_ATTR,
+  HF_AUDIO_FADE_OUT_ATTR,
+  readElementFades,
+  readFadeSeconds,
+} from "@hyperframes/core/audio-fade";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import { groupInfoFor } from "./timelineGroupInfo";
 import { getTimelineElementIdentity, previewElementFinder } from "./timelineElementHelpers";
 
 /**
- * Re-read every element's automation and FX-chain attributes from the preview
+ * Re-read every element's automation, FX-chain and fade attributes from the preview
  * document, for a change that reached the DOM without going through this store.
  *
  * That is undo and redo. A soft restore patches the reverted attributes onto the
@@ -34,21 +40,21 @@ import { getTimelineElementIdentity, previewElementFinder } from "./timelineElem
  * reverted is only known by looking.
  */
 /**
- * What an element's four synced fields SHOULD read, given the preview.
+ * What an element's six synced fields SHOULD read, given the preview.
  *
- * Its own two come off its node; the other two are its copy of what its group
+ * Its own four come off its node; the other two are its copy of what its group
  * carries. The timeline derives a group's lanes and chain from these mirrors,
- * never from the group element — and the FX rack is not group-aware: selecting
- * a group and automating one of its parameters writes `data-automation` on the
- * group node through the ordinary element path, which used to refresh an
- * element's own two fields and nothing else. So the group's row went on reading
- * the value it was born with, and its `∿` never appeared.
+ * never from the group element, and automating a group writes `data-automation`
+ * on the group node through the ordinary element path, so both halves are re-read.
  */
 function syncedFields(doc: Document, element: TimelineElement, node: Element) {
   const group = element.audioGroup ? groupInfoFor(doc, element.audioGroup) : null;
+  const fades = readElementFades(node);
   return {
     automation: node.getAttribute(HF_AUDIO_AUTOMATION_ATTR) ?? undefined,
     fxChain: node.getAttribute(HF_AUDIO_FX_ATTR) ?? undefined,
+    fadeIn: storedFade(fades.fadeIn),
+    fadeOut: storedFade(fades.fadeOut),
     audioGroupAutomation: group?.automation,
     audioGroupFxChain: group?.fxChain,
   };
@@ -74,27 +80,33 @@ export function syncStoredAutomationFromPreview(doc: Document | null | undefined
   });
 }
 
-const STORED_FIELD: Record<string, "automation" | "fxChain"> = {
-  [HF_AUDIO_AUTOMATION_ATTR]: "automation",
-  [HF_AUDIO_FX_ATTR]: "fxChain",
+/** Discovery's rule (applyFadeMetadataFromElement): a fade of 0 is no fade. */
+const storedFade = (seconds: number) => (seconds > 0 ? seconds : undefined);
+
+const STORED_FIELD: Record<string, (value: string | null) => Partial<TimelineElement>> = {
+  [HF_AUDIO_AUTOMATION_ATTR]: (value) => ({ automation: value ?? undefined }),
+  [HF_AUDIO_FX_ATTR]: (value) => ({ fxChain: value ?? undefined }),
+  [HF_AUDIO_FADE_IN_ATTR]: (value) => ({ fadeIn: storedFade(readFadeSeconds(value)) }),
+  [HF_AUDIO_FADE_OUT_ATTR]: (value) => ({ fadeOut: storedFade(readFadeSeconds(value)) }),
 };
 
-/** Record a saved automation or FX-chain value on one element's stored copy. */
+/** Record a saved automation, FX-chain or fade value on one element's stored copy. */
 export function syncStoredElementAttribute(
   target: TimelineElement,
   attr: string,
   value: string | null,
 ): void {
-  const field = STORED_FIELD[attr];
-  if (!field) return;
+  const fields = STORED_FIELD[attr]?.(value);
+  if (!fields) return;
   const key = getTimelineElementIdentity(target);
-  const next = value ?? undefined;
+  const same = (element: TimelineElement) =>
+    (Object.keys(fields) as (keyof TimelineElement)[]).every((k) => element[k] === fields[k]);
   usePlayerStore.setState((state) => {
     let changed = false;
     const elements = state.elements.map((element) => {
-      if (getTimelineElementIdentity(element) !== key || element[field] === next) return element;
+      if (getTimelineElementIdentity(element) !== key || same(element)) return element;
       changed = true;
-      return { ...element, [field]: next };
+      return { ...element, ...fields };
     });
     return changed ? { elements } : {};
   });

package/src/player/lib/thumbnailScheduler.ts

@@ -23,6 +23,8 @@ export interface ThumbnailRequest {
   priority: ThumbnailPriority;
   /** Rich work is paused while the timeline is fast-scrolling. */
   rich?: boolean;
+  /** For work whose result nobody reads: it is dropped, not cached, once its last lease ends. */
+  discardWhenReleased?: boolean;
   load: (signal: AbortSignal) => Promise<ThumbnailLoadedResult>;
 }
 
@@ -214,10 +216,7 @@ export class ThumbnailScheduler {
     if (!scrolling) this.pump();
   }
 
-  /**
-   * Hold server-rendered composition thumbnails while the preview loads a new document: both
-   * are served by the same Studio server, and the preview is what the person is waiting for.
-   */
+  /** Holds composition renders while the preview loads: same server, and the preview is what the person awaits. */
   setPreviewReloading(reloading: boolean): void {
     if (this.previewReloading === reloading) return;
     this.previewReloading = reloading;
@@ -362,7 +361,7 @@ export class ThumbnailScheduler {
     const byteBudget = isWaveform
       ? this.budgets.waveformCacheBytes
       : this.budgets.thumbnailCacheBytes;
-    entry.cached = entry.weight <= byteBudget;
+    entry.cached = !entry.request.discardWhenReleased && entry.weight <= byteBudget;
     if (!entry.cached) return;
     if (isWaveform) this.waveformCacheBytes += entry.weight;
     else this.cacheBytes += entry.weight;

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

@@ -23,7 +23,7 @@ describe("timeline viewport budgets", () => {
       constrainedLongTaskLimitMs: 300,
       posterCoverageRatio: 0.9,
       supportedFixtureFallbackRatio: 0.02,
-      scrollSamplesPerRun: 21,
+      scrollSamplesPerRun: 63,
       warmupRuns: 3,
       measuredRuns: 5,
       requiredPassingRuns: 4,

package/src/player/lib/timelineViewportBudgets.ts

@@ -99,7 +99,7 @@ export const TIMELINE_VIEWPORT_BUDGETS: Readonly<TimelineViewportBudgets> = Obje
   richPreviewP95Ms: 750,
   constrainedRichPreviewP95Ms: 1_200,
   supportedFixtureFallbackRatio: 0.02,
-  scrollSamplesPerRun: 21,
+  scrollSamplesPerRun: 63,
   warmupRuns: 3,
   measuredRuns: 5,
   requiredPassingRuns: 4,

package/src/player/sceneSwap.ts

@@ -17,6 +17,24 @@ export function onPreviewContentReplaced(
   };
 }
 
+const PREVIEW_PROMOTED = "hf-preview-promoted";
+export type PreviewPromotion = { retired: HTMLIFrameElement | null; live: HTMLIFrameElement };
+
+export function announcePreviewPromoted(promotion: PreviewPromotion): void {
+  promotion.live.ownerDocument.dispatchEvent(
+    new CustomEvent(PREVIEW_PROMOTED, { detail: promotion }),
+  );
+}
+
+export function onPreviewPromoted(
+  doc: Document,
+  listener: (promotion: PreviewPromotion) => void,
+): () => void {
+  const handle = (event: Event) => listener((event as CustomEvent<PreviewPromotion>).detail);
+  doc.addEventListener(PREVIEW_PROMOTED, handle);
+  return () => doc.removeEventListener(PREVIEW_PROMOTED, handle);
+}
+
 export function markScenesStale(iframe: HTMLIFrameElement | null, files: readonly string[]): void {
   const doc = iframe?.contentDocument;
   const meta = doc?.querySelector<HTMLMetaElement>('meta[name="hf-scene-parts"]');