@hyperframes/studio 0.8.105 → 0.8.107

package/src/player/components/timelineLayout.ts

@@ -506,34 +506,6 @@ export function shouldShowTimelineShortcutHint(
   return scrollHeight - clientHeight <= 1;
 }
 
-export function shouldHandleTimelineDeleteKey(input: {
-  key: string;
-  metaKey?: boolean;
-  ctrlKey?: boolean;
-  altKey?: boolean;
-  target?: EventTarget | null;
-}): boolean {
-  if (input.key !== "Delete" && input.key !== "Backspace") return false;
-  if (input.metaKey || input.ctrlKey || input.altKey) return false;
-  const target =
-    input.target && typeof input.target === "object"
-      ? (input.target as {
-          tagName?: string;
-          isContentEditable?: boolean;
-          closest?: (selector: string) => Element | null;
-        })
-      : null;
-  if (target) {
-    const tag = target.tagName?.toLowerCase() ?? "";
-    if (target.isContentEditable) return false;
-    if (["input", "textarea", "select"].includes(tag)) return false;
-    if (typeof target.closest === "function" && target.closest("[contenteditable='true']")) {
-      return false;
-    }
-  }
-  return true;
-}
-
 /* ── Asset drop ───────────────────────────────────────────────────── */
 export function getDefaultDroppedTrack(trackOrder: number[], rowIndex?: number): number {
   if (trackOrder.length === 0) return 0;

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/usePlaybackKeyboard.test.ts

@@ -261,3 +261,46 @@ describe("usePlaybackKeyboard — mute & loop shortcuts (#905)", () => {
     expect(usePlayerStore.getState().loopEnabled).toBe(false);
   });
 });
+
+describe("usePlaybackKeyboard — a focused native player owns its keys", () => {
+  const KEYS = [
+    { code: "ArrowLeft", key: "ArrowLeft" },
+    { code: "ArrowRight", key: "ArrowRight" },
+    { code: "Space", key: " " },
+    { code: "KeyJ", key: "j" },
+    { code: "KeyK", key: "k" },
+    { code: "KeyL", key: "l" },
+  ];
+
+  it.each(["video", "audio"])(
+    "leaves the timeline alone while a <%s controls> has focus",
+    (tag) => {
+      const { dispatch, spies } = setupHook();
+      const player = document.createElement(tag);
+      player.setAttribute("controls", "");
+      document.body.append(player);
+      const before = usePlayerStore.getState().currentTime;
+      for (const init of KEYS) {
+        const event = keydown(init);
+        Object.defineProperty(event, "target", { value: player });
+        dispatch(event);
+        expect(event.defaultPrevented, init.code).toBe(false);
+      }
+      expect(spies.seek).not.toHaveBeenCalled();
+      expect(spies.play).not.toHaveBeenCalled();
+      expect(spies.playBackward).not.toHaveBeenCalled();
+      expect(spies.pause).not.toHaveBeenCalled();
+      expect(usePlayerStore.getState().currentTime).toBe(before);
+    },
+  );
+
+  it("still steps the timeline from a player without controls", () => {
+    const { dispatch } = setupHook();
+    const video = document.createElement("video");
+    document.body.append(video);
+    const event = keydown({ code: "ArrowRight", key: "ArrowRight" });
+    Object.defineProperty(event, "target", { value: video });
+    dispatch(event);
+    expect(event.defaultPrevented).toBe(true);
+  });
+});

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

@@ -6,7 +6,7 @@
  * is active and the user is navigating caption segments).
  */
 
-import { isTypingTarget } from "../../utils/typingTarget";
+import { ownsPlainKeys } from "../../utils/typingTarget";
 
 const PLAYBACK_FRAME_STEP_CODES = new Set(["ArrowLeft", "ArrowRight"]);
 
@@ -15,21 +15,17 @@ const PLAYBACK_SHORTCUT_IGNORED_SELECTOR = [
   "a[href]",
   "[role='button']",
   "[role='checkbox']",
-  "[role='combobox']",
   "[role='menuitem']",
   // Base UI's menu radio item is a `<div>`, so `button` above no longer catches it.
   "[role='menuitemradio']",
   "[role='radio']",
-  "[role='slider']",
   "[role='spinbutton']",
-  "[role='switch']",
-  "[role='textbox']",
 ].join(",");
 
 export function shouldIgnorePlaybackShortcutTarget(target: EventTarget | null): boolean {
   // Anything the user is typing into owns its keys outright, editable elements
-  // included: a letter claimed here never reaches the text.
-  if (isTypingTarget(target)) return true;
+  // included: a letter claimed here never reaches the text. So does a native player.
+  if (ownsPlainKeys(target)) return true;
   if (!target || typeof target !== "object") return false;
   const candidate = target as { closest?: unknown };
   if (typeof candidate.closest !== "function") return false;

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

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { isVideoAudible } from "./timelineElementHelpers";
+
+describe("isVideoAudible — the compiler's data-has-audio rule", () => {
+  it("explicit data-has-audio wins", () => {
+    expect(isVideoAudible({ tag: "video", hasAudioAttr: "true", muted: false })).toBe(true);
+    expect(isVideoAudible({ tag: "video", hasAudioAttr: "false", muted: false })).toBe(false);
+  });
+  it("no attribute: an unmuted video is audible, a muted one is not", () => {
+    expect(isVideoAudible({ tag: "video", hasAudioAttr: null, muted: false })).toBe(true);
+    expect(isVideoAudible({ tag: "video", hasAudioAttr: undefined, muted: true })).toBe(false);
+  });
+  it("never true for non-video without the attribute", () => {
+    expect(isVideoAudible({ tag: "img", hasAudioAttr: null, muted: false })).toBe(false);
+  });
+});

package/src/player/lib/timelineElementHelpers.ts

@@ -220,12 +220,26 @@ function readVolume(el: Element, media: Element): number | undefined {
   return Number.isFinite(volume) ? volume : undefined;
 }
 
+/** The compiler's rule (timingCompiler): explicit data-has-audio wins; otherwise an unmuted <video> is audible. */
+export function isVideoAudible(opts: {
+  tag: string;
+  hasAudioAttr: string | null | undefined;
+  muted: boolean;
+}): boolean {
+  if (opts.hasAudioAttr === "true") return true;
+  if (opts.hasAudioAttr === "false" || opts.hasAudioAttr === "") return false;
+  return opts.tag.toLowerCase() === "video" && !opts.muted;
+}
+
 /** What the mixer gets: the compiler's `data-has-audio` rule, muted and volume. */
 function applyAudioMetadataFromElement(entry: TimelineElement, el: Element): void {
   const media = resolveMediaElement(el) ?? el;
   const muted = el.hasAttribute("muted") || media.hasAttribute("muted");
-  const hasAudio = el.getAttribute("data-has-audio");
-  const sound = hasAudio === null ? el.tagName === "VIDEO" && !muted : hasAudio === "true";
+  const sound = isVideoAudible({
+    tag: el.tagName,
+    hasAudioAttr: el.getAttribute("data-has-audio"),
+    muted,
+  });
   setOptional(entry, "hasAudio", sound ? true : undefined);
   setOptional(entry, "muted", muted ? true : undefined);
   setOptional(entry, "volume", readVolume(el, media));

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

@@ -19,6 +19,8 @@ describe("timeline viewport budgets", () => {
       interactionP95Ms: 50,
       constrainedInteractionP95Ms: 75,
       constrainedFrameIntervalP95Ms: 75,
+      ciVirtualizedInteractionP95Ms: 58.3,
+      ciVirtualizedFrameIntervalP95Ms: 25,
       longTaskLimitMs: 50,
       constrainedLongTaskLimitMs: 300,
       posterCoverageRatio: 0.9,

package/src/player/lib/timelineViewportBudgets.ts

@@ -28,6 +28,8 @@ export interface TimelineViewportBudgets {
   frameIntervalP95Ms: number;
   constrainedInteractionP95Ms: number;
   constrainedFrameIntervalP95Ms: number;
+  ciVirtualizedInteractionP95Ms: number;
+  ciVirtualizedFrameIntervalP95Ms: number;
   longTaskLimitMs: number;
   constrainedLongTaskLimitMs: number;
   memoryReturnToleranceRatio: number;
@@ -86,6 +88,8 @@ export const TIMELINE_VIEWPORT_BUDGETS: Readonly<TimelineViewportBudgets> = Obje
   frameIntervalP95Ms: 33.3,
   constrainedInteractionP95Ms: 75,
   constrainedFrameIntervalP95Ms: 75,
+  ciVirtualizedInteractionP95Ms: 58.3,
+  ciVirtualizedFrameIntervalP95Ms: 25,
   longTaskLimitMs: 50,
   constrainedLongTaskLimitMs: 300,
   memoryReturnToleranceRatio: 0.15,

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"]');

package/src/styles/components.css

@@ -253,6 +253,32 @@
   border-radius: var(--timeline-clip-audio-radius);
 }
 
+.timeline-fade-tab {
+  position: absolute;
+  border-radius: 2px;
+  background: var(--timeline-fade-dot);
+  box-shadow:
+    0 0 0 1px var(--timeline-fade-dot-ring),
+    0 1px 3px var(--timeline-fade-dot-ring);
+  transition: transform 140ms cubic-bezier(0.23, 1, 0.32, 1);
+}
+
+.timeline-fade-handle:hover .timeline-fade-tab,
+.timeline-fade-handle[data-dragging] .timeline-fade-tab {
+  transform: scaleY(1.2);
+}
+
+.timeline-fade-handle:focus-visible .timeline-fade-tab {
+  outline: 2px solid var(--timeline-accent);
+  outline-offset: 2px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .timeline-fade-tab {
+    transition: none;
+  }
+}
+
 .timeline-clip.is-audio.is-hovered {
   background-color: var(--timeline-clip-audio-bg-hover);
 }

package/src/styles/studio.css

@@ -16,6 +16,12 @@
   }
 }
 
+[data-theme-reveal]::view-transition-old(root),
+[data-theme-reveal]::view-transition-new(root) {
+  animation: none;
+  mix-blend-mode: normal;
+}
+
 body {
   margin: 0;
   padding: 0;

package/src/styles/theme.css

@@ -77,6 +77,16 @@
   --color-media: light-dark(oklch(0.5 0.1 215), #00e3ff);
   --color-container: light-dark(oklch(0.55 0.13 70), #f5a623);
 
+  /* Code editor syntax: One Light and One Dark hues, held at 4.5:1 on a line, the active line and a selection on it. */
+  --color-code-keyword: light-dark(oklch(0.509 0.211 329), oklch(0.829 0.164 318));
+  --color-code-name: light-dark(oklch(0.504 0.179 28), oklch(0.856 0.145 17));
+  --color-code-function: light-dark(oklch(0.492 0.193 263), oklch(0.805 0.121 245));
+  --color-code-constant: light-dark(oklch(0.495 0.13 50), oklch(0.815 0.11 50));
+  --color-code-type: light-dark(oklch(0.48 0.12 92), oklch(0.805 0.1 92));
+  --color-code-operator: light-dark(oklch(0.471 0.127 237), oklch(0.793 0.092 206));
+  --color-code-comment: light-dark(oklch(0.48 0.009 279), oklch(0.806 0.03 262));
+  --color-code-string: light-dark(oklch(0.468 0.142 143), oklch(0.793 0.11 133));
+
   /* The two stops of the HeyGen brand gradient, worn by the header logo. Fixed brand values
    * rather than roles, so they are not reachable as a background or text colour by mistake. */
   --color-brand-gradient-from: #06e3fa;

package/src/utils/clipboardPayload.ts

@@ -17,6 +17,7 @@ export type ClipboardPayload =
       clips: TimelineClipboardClip[];
       sourceFile: string;
       projectId?: string;
+      copiedInComposition?: string;
     }
   | {
       kind: "dom-element";
@@ -63,7 +64,15 @@ export function deserializeClipboardPayload(json: string): ClipboardPayload | nu
     });
     if (clips.length === 0) return null;
     const projectId = typeof obj.projectId === "string" ? obj.projectId : undefined;
-    return { kind: "timeline-clip", clips, sourceFile: obj.sourceFile, projectId };
+    const copiedInComposition =
+      typeof obj.copiedInComposition === "string" ? obj.copiedInComposition : undefined;
+    return {
+      kind: "timeline-clip",
+      clips,
+      sourceFile: obj.sourceFile,
+      projectId,
+      copiedInComposition,
+    };
   }
   if (obj.kind === "dom-element") {
     if (typeof obj.html !== "string") return null;

package/src/utils/gsapSoftReload.ts

@@ -195,6 +195,7 @@ export interface SoftReloadOptions {
   currentTimeOverride?: number;
   /** After-write file HTML — the primary source for the authored opacity and transform restore. */
   authoredHtml?: string;
+  reparse?: Element[];
 }
 
 /**
@@ -251,7 +252,7 @@ export function applySoftReload(
   scriptText: string,
   options: SoftReloadOptions = {},
 ): SoftReloadResult {
-  const { onAsyncFailure, currentTimeOverride, authoredHtml } = options;
+  const { onAsyncFailure, currentTimeOverride, authoredHtml, reparse = [] } = options;
   if (!iframe || !scriptText) return "cannot-soft-reload";
 
   const win = iframe.contentWindow as IframeWindow | null;
@@ -329,7 +330,7 @@ export function applySoftReload(
   // fallow-ignore-next-line complexity
   const doReload = () => {
     const timelines = win.__timelines;
-    const allTargets: Element[] = [];
+    const allTargets: Element[] = [...reparse];
 
     // Kill ONLY the target composition's timeline(s) — leaving every other
     // composition's timeline (and its children on the global timeline) intact.