@hyperframes/studio 0.8.105 → 0.8.106

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

@@ -39,6 +39,27 @@ export function hasStudioPendingEdits(): boolean {
   return pendingEditPromises.size > 0 || focusedField() !== null;
 }
 
+export function isStudioEditSaving(): boolean {
+  return pendingEditPromises.size > 0;
+}
+
+export function afterStudioPendingEdits(run: () => void): () => void {
+  let waiting = true;
+  const check = () => {
+    if (!waiting) return;
+    if (isStudioEditSaving()) {
+      void Promise.allSettled([...pendingEditPromises]).then(check);
+      return;
+    }
+    waiting = false;
+    run();
+  };
+  check();
+  return () => {
+    waiting = false;
+  };
+}
+
 export function trackStudioPendingEdit(
   result: Promise<unknown> | unknown,
 ): Promise<unknown> | undefined {

package/src/utils/studioTheme.test.tsx

@@ -0,0 +1,141 @@
+// @vitest-environment happy-dom
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ThemeToggle } from "../components/ThemeToggle";
+import { cleanupMounted, mountHost } from "../components/ui/mountHost.testHelpers";
+import { savedStudioTheme, shownStudioTheme } from "./studioTheme";
+
+const KEY = "hf-studio-ui-preferences";
+const page = new DOMParser().parseFromString(
+  readFileSync(path.join(__dirname, "../../index.html"), "utf8"),
+  "text/html",
+);
+const scripts = [...page.querySelectorAll("script")];
+const boot = scripts.find((script) => !script.type)?.textContent ?? "";
+
+function store(theme: unknown) {
+  localStorage.setItem(KEY, JSON.stringify({ theme }));
+}
+
+function boots(): "light" | "dark" {
+  new Function(boot)();
+  return shownStudioTheme();
+}
+
+afterEach(() => {
+  cleanupMounted();
+  localStorage.clear();
+  delete document.documentElement.dataset.theme;
+});
+
+describe("Studio's theme", () => {
+  it.each([["light"], ["dark"], [undefined], ["neon"]])(
+    "boots to the theme the owner picks (saved %s)",
+    (saved) => {
+      store(saved);
+      expect(boots()).toBe(savedStudioTheme());
+    },
+  );
+
+  it.each([["null"], ["{not json"], ['"dark"']])("boots to the owner's pick from %s", (raw) => {
+    localStorage.setItem(KEY, raw);
+    expect(boots()).toBe(savedStudioTheme());
+  });
+
+  it("opens light the first time", () => {
+    expect(boots()).toBe("light");
+    expect(savedStudioTheme()).toBe("light");
+  });
+
+  it("runs the boot script before the app's module", () => {
+    expect(boot).toContain(`"${KEY}"`);
+    expect(scripts.findIndex((script) => !script.type)).toBeLessThan(
+      scripts.findIndex((script) => script.type === "module"),
+    );
+  });
+
+  it("flips the document between light and dark and keeps the choice", async () => {
+    store("dark");
+    const host = mountHost(<ThemeToggle />);
+    const button = () => host.querySelector("button")!;
+    expect(button().getAttribute("aria-label")).toBe("Switch to light theme");
+
+    await act(async () => button().click());
+    expect(document.documentElement.dataset.theme).toBe("paper");
+    expect(JSON.parse(localStorage.getItem(KEY)!).theme).toBe("light");
+    expect(button().getAttribute("aria-label")).toBe("Switch to dark theme");
+
+    await act(async () => button().click());
+    expect(document.documentElement.dataset.theme).toBeUndefined();
+    expect(JSON.parse(localStorage.getItem(KEY)!).theme).toBe("dark");
+  });
+
+  it("follows the theme on screen, not only its own clicks", async () => {
+    store("light");
+    const host = mountHost(<ThemeToggle />);
+    expect(host.querySelector("button")!.getAttribute("aria-label")).toBe("Switch to light theme");
+    await act(async () => {
+      document.documentElement.dataset.theme = "paper";
+    });
+    expect(host.querySelector("button")!.getAttribute("aria-label")).toBe("Switch to dark theme");
+  });
+});
+
+describe("the reveal", () => {
+  function stubTransition() {
+    const animate = vi.fn();
+    Object.assign(document.documentElement, { animate });
+    const markers: (string | undefined)[] = [];
+    const finish: (() => void)[] = [];
+    const start = vi.fn((update: () => void) => {
+      markers.push(document.documentElement.dataset.themeReveal);
+      update();
+      return { ready: Promise.resolve(), finished: new Promise<void>((done) => finish.push(done)) };
+    });
+    Object.assign(document, { startViewTransition: start });
+    return { animate, start, markers, finish };
+  }
+
+  afterEach(() => {
+    Reflect.deleteProperty(document, "startViewTransition");
+    Reflect.deleteProperty(document.documentElement, "animate");
+    vi.unstubAllGlobals();
+  });
+
+  it("grows from the button's centre when the keyboard presses it, marked while it runs", async () => {
+    const { animate, markers, finish } = stubTransition();
+    vi.stubGlobal("innerWidth", 1000);
+    vi.stubGlobal("innerHeight", 500);
+    const button = mountHost(<ThemeToggle />).querySelector("button")!;
+    button.getBoundingClientRect = () => ({ left: 890, top: 10, width: 20, height: 20 }) as DOMRect;
+    await act(async () => {
+      button.dispatchEvent(new MouseEvent("click", { bubbles: true, detail: 0 }));
+    });
+    expect(markers).toEqual([""]);
+    expect(animate.mock.calls[0]![0].clipPath[1]).toMatch(/^circle\(129\.0\d*% at 90% 4%\)$/);
+    await act(async () => finish[0]!());
+    expect(document.documentElement.dataset.themeReveal).toBeUndefined();
+  });
+
+  it("keeps the marker for a second reveal that starts before the first ends", async () => {
+    const { finish } = stubTransition();
+    const button = mountHost(<ThemeToggle />).querySelector("button")!;
+    await act(async () => button.click());
+    await act(async () => button.click());
+    await act(async () => finish[0]!());
+    expect(document.documentElement.dataset.themeReveal).toBe("");
+    await act(async () => finish[1]!());
+    expect(document.documentElement.dataset.themeReveal).toBeUndefined();
+  });
+
+  it("switches without the reveal under reduced motion", async () => {
+    const { start } = stubTransition();
+    vi.stubGlobal("matchMedia", (query: string) => ({ matches: query.includes("reduce") }));
+    const button = mountHost(<ThemeToggle />).querySelector("button")!;
+    await act(async () => button.click());
+    expect(start).not.toHaveBeenCalled();
+    expect(document.documentElement.dataset.theme).toBe("paper");
+  });
+});

package/src/utils/studioTheme.ts

@@ -0,0 +1,34 @@
+// Studio's own app opens on the toggle's saved choice, else light. Light is `data-theme="paper"`
+// on the document element, the hook theme.css keys on; dark is no attribute. index.html applies
+// `savedStudioTheme` before the first paint; studioTheme.test.tsx holds the two together.
+import { useSyncExternalStore } from "react";
+import {
+  readStudioUiPreferences,
+  writeStudioUiPreferences,
+  type StudioTheme,
+} from "./studioUiPreferences";
+
+export function savedStudioTheme(): StudioTheme {
+  return readStudioUiPreferences().theme ?? "light";
+}
+
+export function shownStudioTheme(): StudioTheme {
+  return document.documentElement.dataset.theme === "paper" ? "light" : "dark";
+}
+
+export function setStudioTheme(theme: StudioTheme): void {
+  writeStudioUiPreferences({ theme });
+  const root = document.documentElement;
+  if (theme === "light") root.dataset.theme = "paper";
+  else delete root.dataset.theme;
+}
+
+function subscribe(listener: () => void): () => void {
+  const observer = new MutationObserver(listener);
+  observer.observe(document.documentElement, { attributeFilter: ["data-theme"] });
+  return () => observer.disconnect();
+}
+
+export function useShownStudioTheme(): StudioTheme {
+  return useSyncExternalStore(subscribe, shownStudioTheme);
+}

package/src/utils/studioUiPreferences.ts

@@ -2,6 +2,7 @@ import type { SerializedDockview } from "dockview-react";
 import { parseDockLayout } from "../components/dock/dockLayoutSchema";
 
 export type TimelineTimeDisplayMode = "time" | "frame";
+export type StudioTheme = "light" | "dark";
 
 export interface StudioUiPreferences {
   timelineVisible?: boolean;
@@ -41,6 +42,7 @@ export interface StudioUiPreferences {
    * intentionally scoped to one mount.
    */
   agentToolsEnabled?: boolean;
+  theme?: StudioTheme;
   /** The dock's serialized panel tree; parsed by `parseDockLayout` on read. */
   dockLayout?: SerializedDockview;
 }
@@ -128,6 +130,7 @@ function readStorage(storage: Storage | null, key: string): StudioUiPreferences
     if (typeof parsed.rippleEditEnabled === "boolean") {
       preferences.rippleEditEnabled = parsed.rippleEditEnabled;
     }
+    if (parsed.theme === "light" || parsed.theme === "dark") preferences.theme = parsed.theme;
     if (parsed.timeDisplayMode === "time" || parsed.timeDisplayMode === "frame") {
       preferences.timeDisplayMode = parsed.timeDisplayMode;
     }