From e1ee8242143f685497a8f447b3ac6804b6940bb0 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Thu, 1 Oct 2026 00:44:36 -0700
Subject: [PATCH 1/8] feat(studio): a light and dark theme toggle in the header
 that remembers the choice

The sun and moon button flips Studio between Graphite light and dark with a
circular reveal, saves the choice, and follows the system until one is made.
---
 packages/studio/index.html                    |  9 ++
 .../studio/src/components/StudioHeader.tsx    |  2 +
 .../studio/src/components/ThemeToggle.tsx     | 83 +++++++++++++++++++
 .../studio/src/utils/studioTheme.test.tsx     | 62 ++++++++++++++
 packages/studio/src/utils/studioTheme.ts      | 40 +++++++++
 .../studio/src/utils/studioUiPreferences.ts   |  4 +
 6 files changed, 200 insertions(+)
 create mode 100644 packages/studio/src/components/ThemeToggle.tsx
 create mode 100644 packages/studio/src/utils/studioTheme.test.tsx
 create mode 100644 packages/studio/src/utils/studioTheme.ts

diff --git a/packages/studio/index.html b/packages/studio/index.html
index b3659e0763..56074986aa 100644
--- a/packages/studio/index.html
+++ b/packages/studio/index.html
@@ -5,6 +5,15 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <title>HyperFrames Studio</title>
+    <script>
+      // Before the first paint: the theme the toggle saved, else the system's (owner: src/utils/studioTheme.ts).
+      try {
+        var theme = JSON.parse(localStorage.getItem("hf-studio-ui-preferences") || "{}").theme;
+        if (theme !== "light" && theme !== "dark")
+          theme = matchMedia("(prefers-color-scheme: dark)").matches === false ? "light" : "dark";
+        if (theme === "light") document.documentElement.dataset.theme = "paper";
+      } catch (e) {}
+    </script>
   </head>
   <body>
     <div data-hf-id="hf-aph5" id="root"></div>
diff --git a/packages/studio/src/components/StudioHeader.tsx b/packages/studio/src/components/StudioHeader.tsx
index a08acc5a49..b24209d5d3 100644
--- a/packages/studio/src/components/StudioHeader.tsx
+++ b/packages/studio/src/components/StudioHeader.tsx
@@ -7,6 +7,7 @@ import { Button, buttonBase, buttonSizes, buttonVariants, cn, Tooltip } from "./
 import { Dock } from "./dock/Dock";
 import { InspectorIcon } from "./icons/InspectorIcon";
 import { HyperframesLogo } from "./ui/HyperframesLogo";
+import { ThemeToggle } from "./ThemeToggle";
 
 export interface StudioHeaderProps {
   captureFrameHref: string;
@@ -147,6 +148,7 @@ export function StudioHeader({
             </Button>
           </Tooltip>
         </div>
+        <ThemeToggle />
         <Dock.WindowMenu />
         <Tooltip
           label={
diff --git a/packages/studio/src/components/ThemeToggle.tsx b/packages/studio/src/components/ThemeToggle.tsx
new file mode 100644
index 0000000000..124c335588
--- /dev/null
+++ b/packages/studio/src/components/ThemeToggle.tsx
@@ -0,0 +1,83 @@
+import { useCallback } from "react";
+import { setStudioTheme, useShownStudioTheme } from "../utils/studioTheme";
+
+// hyperframes.dev's theme toggle: the same sun and moon button, revealing the new theme in a circle
+// from the click. A page that paints no frame aborts the transition; the theme is applied by then.
+function reveal(transition: ViewTransition, at: string, radiusPct: number) {
+  void transition.ready.then(
+    () => {
+      document.documentElement.animate(
+        { clipPath: [`circle(0% ${at})`, `circle(${radiusPct}% ${at})`] },
+        { duration: 500, easing: "ease-in-out", pseudoElement: "::view-transition-new(root)" },
+      );
+    },
+    () => {},
+  );
+}
+
+export function ThemeToggle() {
+  const isDark = useShownStudioTheme() === "dark";
+
+  const toggle = useCallback(
+    (e: React.MouseEvent<HTMLButtonElement>) => {
+      const apply = () => setStudioTheme(isDark ? "light" : "dark");
+      if (!document.startViewTransition) return apply();
+      // The switch stays synchronous inside the callback: rendering is paused during it.
+      const { clientX: x, clientY: y } = e;
+      const w = window.innerWidth;
+      const h = window.innerHeight;
+      const maxRadius = Math.hypot(Math.max(x, w - x), Math.max(y, h - y));
+      const at = `at ${(x / w) * 100}% ${(y / h) * 100}%`;
+      const radiusPct = (maxRadius / (Math.hypot(w, h) / Math.SQRT2)) * 100;
+      reveal(document.startViewTransition(apply), at, radiusPct);
+    },
+    [isDark],
+  );
+
+  return (
+    <button
+      type="button"
+      onClick={toggle}
+      className="inline-flex min-h-7 min-w-7 items-center justify-center rounded-full text-text-2 transition-all duration-hover hover:bg-hover hover:text-text-0 active:scale-[0.95]"
+      aria-label={`Switch to ${isDark ? "light" : "dark"} theme`}
+    >
+      {isDark ? (
+        <svg
+          width="14"
+          height="14"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          aria-hidden="true"
+        >
+          <circle cx="12" cy="12" r="5" />
+          <line x1="12" y1="1" x2="12" y2="3" />
+          <line x1="12" y1="21" x2="12" y2="23" />
+          <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
+          <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
+          <line x1="1" y1="12" x2="3" y2="12" />
+          <line x1="21" y1="12" x2="23" y2="12" />
+          <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
+          <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
+        </svg>
+      ) : (
+        <svg
+          width="14"
+          height="14"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          aria-hidden="true"
+        >
+          <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
+        </svg>
+      )}
+    </button>
+  );
+}
diff --git a/packages/studio/src/utils/studioTheme.test.tsx b/packages/studio/src/utils/studioTheme.test.tsx
new file mode 100644
index 0000000000..b69c9e1887
--- /dev/null
+++ b/packages/studio/src/utils/studioTheme.test.tsx
@@ -0,0 +1,62 @@
+// @vitest-environment happy-dom
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { act } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+import { ThemeToggle } from "../components/ThemeToggle";
+import { cleanupMounted, mountHost } from "../components/ui/mountHost.testHelpers";
+import { shownStudioTheme } from "./studioTheme";
+
+const KEY = "hf-studio-ui-preferences";
+const html = readFileSync(path.join(__dirname, "../../index.html"), "utf8");
+const boot = html.match(/<script>([\s\S]*?)<\/script>/)?.[1] ?? "";
+
+function systemIs(dark: boolean) {
+  window.matchMedia = ((query: string) => ({ matches: dark && query.includes("dark") })) as never;
+}
+
+function store(theme: unknown) {
+  localStorage.setItem(KEY, JSON.stringify({ theme }));
+}
+
+afterEach(() => {
+  cleanupMounted();
+  localStorage.clear();
+  delete document.documentElement.dataset.theme;
+});
+
+describe("Studio's theme", () => {
+  it.each([
+    ["light", true],
+    ["dark", false],
+    [undefined, true],
+    [undefined, false],
+    ["neon", false],
+  ])("boots to the theme the owner shows (saved %s, system dark %s)", (saved, dark) => {
+    systemIs(dark);
+    store(saved);
+    new Function(boot)();
+    expect(document.documentElement.dataset.theme === "paper").toBe(shownStudioTheme() === "light");
+  });
+
+  it("runs the boot script before the app's module", () => {
+    expect(boot).toContain(`"${KEY}"`);
+    expect(html.indexOf("<script>")).toBeLessThan(html.indexOf('type="module"'));
+  });
+
+  it("flips the document between dark and light and keeps the choice", () => {
+    systemIs(true);
+    const host = mountHost(<ThemeToggle />);
+    const button = () => host.querySelector("button")!;
+    expect(button().getAttribute("aria-label")).toBe("Switch to light theme");
+
+    act(() => 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");
+
+    act(() => button().click());
+    expect(document.documentElement.dataset.theme).toBeUndefined();
+    expect(JSON.parse(localStorage.getItem(KEY)!).theme).toBe("dark");
+  });
+});
diff --git a/packages/studio/src/utils/studioTheme.ts b/packages/studio/src/utils/studioTheme.ts
new file mode 100644
index 0000000000..88755d4392
--- /dev/null
+++ b/packages/studio/src/utils/studioTheme.ts
@@ -0,0 +1,40 @@
+// The one owner of Studio's own theme: the toggle's saved choice, else the system's. Light is
+// `data-theme="paper"` on the document element, the hook theme.css keys on; dark is no attribute.
+// index.html repeats this rule before the first paint; studioTheme.test.ts holds the two together.
+import { useSyncExternalStore } from "react";
+import {
+  readStudioUiPreferences,
+  writeStudioUiPreferences,
+  type StudioTheme,
+} from "./studioUiPreferences";
+
+const SYSTEM_DARK = "(prefers-color-scheme: dark)";
+const listeners = new Set<() => void>();
+
+export function shownStudioTheme(): StudioTheme {
+  const systemLight = globalThis.window?.matchMedia?.(SYSTEM_DARK).matches === false;
+  return readStudioUiPreferences().theme ?? (systemLight ? "light" : "dark");
+}
+
+function apply(): void {
+  const root = document.documentElement;
+  if (shownStudioTheme() === "light") root.dataset.theme = "paper";
+  else delete root.dataset.theme;
+  for (const listener of listeners) listener();
+}
+
+// With no saved choice, the system's change is the theme's change.
+globalThis.window?.matchMedia?.(SYSTEM_DARK)?.addEventListener?.("change", apply);
+
+export function setStudioTheme(theme: StudioTheme): void {
+  writeStudioUiPreferences({ theme });
+  apply();
+}
+
+const subscribe = (listener: () => void) => {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+};
+
+export const useShownStudioTheme = (): StudioTheme =>
+  useSyncExternalStore(subscribe, shownStudioTheme);
diff --git a/packages/studio/src/utils/studioUiPreferences.ts b/packages/studio/src/utils/studioUiPreferences.ts
index 44a49faf6c..5ad9fcc463 100644
--- a/packages/studio/src/utils/studioUiPreferences.ts
+++ b/packages/studio/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,8 @@ export interface StudioUiPreferences {
    * intentionally scoped to one mount.
    */
   agentToolsEnabled?: boolean;
+  /** The theme the toggle picked; absent follows the system. */
+  theme?: StudioTheme;
   /** The dock's serialized panel tree; parsed by `parseDockLayout` on read. */
   dockLayout?: SerializedDockview;
 }
@@ -128,6 +131,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;
     }

From 45c2d7be9e6d11b92d36c94dde6ee0b6dc81cf97 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Thu, 1 Oct 2026 00:53:25 -0700
Subject: [PATCH 2/8] fix(studio): studio opens light the first time, then
 keeps the saved theme

---
 packages/studio/index.html                    | 10 +++---
 .../studio/src/utils/studioTheme.test.tsx     | 32 +++++++++----------
 packages/studio/src/utils/studioTheme.ts      | 11 ++-----
 .../studio/src/utils/studioUiPreferences.ts   |  2 +-
 4 files changed, 25 insertions(+), 30 deletions(-)

diff --git a/packages/studio/index.html b/packages/studio/index.html
index 56074986aa..e3b482fe2c 100644
--- a/packages/studio/index.html
+++ b/packages/studio/index.html
@@ -6,13 +6,13 @@
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <title>HyperFrames Studio</title>
     <script>
-      // Before the first paint: the theme the toggle saved, else the system's (owner: src/utils/studioTheme.ts).
+      // Before the first paint: the theme the toggle saved, else light (owner: src/utils/studioTheme.ts).
       try {
         var theme = JSON.parse(localStorage.getItem("hf-studio-ui-preferences") || "{}").theme;
-        if (theme !== "light" && theme !== "dark")
-          theme = matchMedia("(prefers-color-scheme: dark)").matches === false ? "light" : "dark";
-        if (theme === "light") document.documentElement.dataset.theme = "paper";
-      } catch (e) {}
+        if (theme !== "dark") document.documentElement.dataset.theme = "paper";
+      } catch (e) {
+        document.documentElement.dataset.theme = "paper";
+      }
     </script>
   </head>
   <body>
diff --git a/packages/studio/src/utils/studioTheme.test.tsx b/packages/studio/src/utils/studioTheme.test.tsx
index b69c9e1887..23bf1bc864 100644
--- a/packages/studio/src/utils/studioTheme.test.tsx
+++ b/packages/studio/src/utils/studioTheme.test.tsx
@@ -11,10 +11,6 @@ const KEY = "hf-studio-ui-preferences";
 const html = readFileSync(path.join(__dirname, "../../index.html"), "utf8");
 const boot = html.match(/<script>([\s\S]*?)<\/script>/)?.[1] ?? "";
 
-function systemIs(dark: boolean) {
-  window.matchMedia = ((query: string) => ({ matches: dark && query.includes("dark") })) as never;
-}
-
 function store(theme: unknown) {
   localStorage.setItem(KEY, JSON.stringify({ theme }));
 }
@@ -26,17 +22,21 @@ afterEach(() => {
 });
 
 describe("Studio's theme", () => {
-  it.each([
-    ["light", true],
-    ["dark", false],
-    [undefined, true],
-    [undefined, false],
-    ["neon", false],
-  ])("boots to the theme the owner shows (saved %s, system dark %s)", (saved, dark) => {
-    systemIs(dark);
-    store(saved);
+  it.each([["light"], ["dark"], [undefined], ["neon"]])(
+    "boots to the theme the owner shows (saved %s)",
+    (saved) => {
+      store(saved);
+      new Function(boot)();
+      expect(document.documentElement.dataset.theme === "paper").toBe(
+        shownStudioTheme() === "light",
+      );
+    },
+  );
+
+  it("opens light the first time", () => {
     new Function(boot)();
-    expect(document.documentElement.dataset.theme === "paper").toBe(shownStudioTheme() === "light");
+    expect(document.documentElement.dataset.theme).toBe("paper");
+    expect(shownStudioTheme()).toBe("light");
   });
 
   it("runs the boot script before the app's module", () => {
@@ -44,8 +44,8 @@ describe("Studio's theme", () => {
     expect(html.indexOf("<script>")).toBeLessThan(html.indexOf('type="module"'));
   });
 
-  it("flips the document between dark and light and keeps the choice", () => {
-    systemIs(true);
+  it("flips the document between light and dark and keeps the choice", () => {
+    store("dark");
     const host = mountHost(<ThemeToggle />);
     const button = () => host.querySelector("button")!;
     expect(button().getAttribute("aria-label")).toBe("Switch to light theme");
diff --git a/packages/studio/src/utils/studioTheme.ts b/packages/studio/src/utils/studioTheme.ts
index 88755d4392..e4f8ad5999 100644
--- a/packages/studio/src/utils/studioTheme.ts
+++ b/packages/studio/src/utils/studioTheme.ts
@@ -1,6 +1,6 @@
-// The one owner of Studio's own theme: the toggle's saved choice, else the system's. Light is
+// The one owner of Studio's own theme: 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 repeats this rule before the first paint; studioTheme.test.ts holds the two together.
+// index.html repeats this rule before the first paint; studioTheme.test.tsx holds the two together.
 import { useSyncExternalStore } from "react";
 import {
   readStudioUiPreferences,
@@ -8,12 +8,10 @@ import {
   type StudioTheme,
 } from "./studioUiPreferences";
 
-const SYSTEM_DARK = "(prefers-color-scheme: dark)";
 const listeners = new Set<() => void>();
 
 export function shownStudioTheme(): StudioTheme {
-  const systemLight = globalThis.window?.matchMedia?.(SYSTEM_DARK).matches === false;
-  return readStudioUiPreferences().theme ?? (systemLight ? "light" : "dark");
+  return readStudioUiPreferences().theme ?? "light";
 }
 
 function apply(): void {
@@ -23,9 +21,6 @@ function apply(): void {
   for (const listener of listeners) listener();
 }
 
-// With no saved choice, the system's change is the theme's change.
-globalThis.window?.matchMedia?.(SYSTEM_DARK)?.addEventListener?.("change", apply);
-
 export function setStudioTheme(theme: StudioTheme): void {
   writeStudioUiPreferences({ theme });
   apply();
diff --git a/packages/studio/src/utils/studioUiPreferences.ts b/packages/studio/src/utils/studioUiPreferences.ts
index 5ad9fcc463..060324638c 100644
--- a/packages/studio/src/utils/studioUiPreferences.ts
+++ b/packages/studio/src/utils/studioUiPreferences.ts
@@ -42,7 +42,7 @@ export interface StudioUiPreferences {
    * intentionally scoped to one mount.
    */
   agentToolsEnabled?: boolean;
-  /** The theme the toggle picked; absent follows the system. */
+  /** The theme the toggle picked; absent is light. */
   theme?: StudioTheme;
   /** The dock's serialized panel tree; parsed by `parseDockLayout` on read. */
   dockLayout?: SerializedDockview;

From 78ddef5ed59a41e8477b06942c25827749975494 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Thu, 1 Oct 2026 00:58:40 -0700
Subject: [PATCH 3/8] fix(studio): drop the theme field's comment, the theme
 owner states the rule

---
 packages/studio/src/utils/studioUiPreferences.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/studio/src/utils/studioUiPreferences.ts b/packages/studio/src/utils/studioUiPreferences.ts
index 060324638c..4e1fdc9f99 100644
--- a/packages/studio/src/utils/studioUiPreferences.ts
+++ b/packages/studio/src/utils/studioUiPreferences.ts
@@ -42,7 +42,6 @@ export interface StudioUiPreferences {
    * intentionally scoped to one mount.
    */
   agentToolsEnabled?: boolean;
-  /** The theme the toggle picked; absent is light. */
   theme?: StudioTheme;
   /** The dock's serialized panel tree; parsed by `parseDockLayout` on read. */
   dockLayout?: SerializedDockview;

From 89e19c6a4913dd4a45fb8b1111429ec36eca0915 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Thu, 1 Oct 2026 05:01:50 -0700
Subject: [PATCH 4/8] fix(studio): the theme toggle shows only in studio's own
 app and follows the theme on screen

A host that embeds StudioApp gets no toggle; the button reads the document's theme, the reveal drops the default crossfade, and reduced motion skips it.
---
 packages/studio/index.html                    |   4 +-
 packages/studio/src/App.tsx                   |   8 +-
 .../src/components/StudioHeader.dom.test.tsx  |  17 ++-
 .../studio/src/components/StudioHeader.tsx    |   4 +-
 .../studio/src/components/ThemeToggle.tsx     | 110 ++++++++++--------
 packages/studio/src/main.tsx                  |   2 +-
 packages/studio/src/styles/studio.css         |   6 +
 .../studio/src/utils/studioTheme.test.tsx     |  40 +++++--
 packages/studio/src/utils/studioTheme.ts      |  30 +++--
 9 files changed, 138 insertions(+), 83 deletions(-)

diff --git a/packages/studio/index.html b/packages/studio/index.html
index e3b482fe2c..321a34e105 100644
--- a/packages/studio/index.html
+++ b/packages/studio/index.html
@@ -8,8 +8,8 @@
     <script>
       // Before the first paint: the theme the toggle saved, else light (owner: src/utils/studioTheme.ts).
       try {
-        var theme = JSON.parse(localStorage.getItem("hf-studio-ui-preferences") || "{}").theme;
-        if (theme !== "dark") document.documentElement.dataset.theme = "paper";
+        if (JSON.parse(localStorage.getItem("hf-studio-ui-preferences") || "{}").theme !== "dark")
+          document.documentElement.dataset.theme = "paper";
       } catch (e) {
         document.documentElement.dataset.theme = "paper";
       }
diff --git a/packages/studio/src/App.tsx b/packages/studio/src/App.tsx
index 38d728b393..a31d86177e 100644
--- a/packages/studio/src/App.tsx
+++ b/packages/studio/src/App.tsx
@@ -71,10 +71,15 @@ export interface StudioAppProps {
   readOnlyPreview?: boolean;
   /** Short text shown on disabled hand-edit controls while `readOnlyPreview` is set. */
   readOnlyPreviewReason?: string;
+  themeToggle?: boolean;
 }
 
 // fallow-ignore-next-line complexity
-export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: StudioAppProps = {}) {
+export function StudioApp({
+  readOnlyPreview = false,
+  readOnlyPreviewReason,
+  themeToggle = false,
+}: StudioAppProps = {}) {
   const { projectId, resolving, waitingForServer } = useServerConnection();
   const initialUrlStateRef = useRef(readStudioUrlStateFromWindow());
   useStudioSessionStart(projectId, resolving, waitingForServer);
@@ -465,6 +470,7 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: St
                 onDrop={fileDrop.onDrop}
               >
                 <StudioHeader
+                  themeToggle={themeToggle}
                   captureFrameHref={frameCapture.captureFrameHref}
                   captureFrameFilename={frameCapture.captureFrameFilename}
                   handleCaptureFrameClick={frameCapture.handleCaptureFrameClick}
diff --git a/packages/studio/src/components/StudioHeader.dom.test.tsx b/packages/studio/src/components/StudioHeader.dom.test.tsx
index fe4d01f8b7..fd5af26df6 100644
--- a/packages/studio/src/components/StudioHeader.dom.test.tsx
+++ b/packages/studio/src/components/StudioHeader.dom.test.tsx
@@ -61,7 +61,9 @@ afterEach(() => {
   host.remove();
 });
 
-function mount(props: { inspectorButtonActive?: boolean } = {}): HTMLElement {
+function mount(
+  props: { inspectorButtonActive?: boolean; themeToggle?: boolean } = {},
+): HTMLElement {
   const host = document.createElement("div");
   document.body.append(host);
   const root = createRoot(host);
@@ -75,6 +77,7 @@ function mount(props: { inspectorButtonActive?: boolean } = {}): HTMLElement {
         refreshCaptureFrameTime={vi.fn()}
         inspectorButtonActive={props.inspectorButtonActive ?? false}
         inspectorPanelActive={false}
+        themeToggle={props.themeToggle}
       />,
     ),
   );
@@ -179,3 +182,15 @@ it("classifies the new header controls for the hotkey filters as the old ones we
     expect(shouldIgnorePlaybackShortcutTarget(el), el.tagName).toBe(true);
   }
 });
+
+it("shows no theme toggle and leaves the host's data-theme alone when embedded", () => {
+  document.documentElement.dataset.theme = "host";
+  const host = mount();
+  expect(host.querySelector('[aria-label^="Switch to"]')).toBeNull();
+  expect(document.documentElement.dataset.theme).toBe("host");
+  delete document.documentElement.dataset.theme;
+});
+
+it("shows the theme toggle in Studio's own app", () => {
+  expect(mount({ themeToggle: true }).querySelector('[aria-label^="Switch to"]')).not.toBeNull();
+});
diff --git a/packages/studio/src/components/StudioHeader.tsx b/packages/studio/src/components/StudioHeader.tsx
index b24209d5d3..e765b42720 100644
--- a/packages/studio/src/components/StudioHeader.tsx
+++ b/packages/studio/src/components/StudioHeader.tsx
@@ -18,6 +18,7 @@ export interface StudioHeaderProps {
   inspectorButtonActive: boolean;
   inspectorPanelActive: boolean;
   onExport?: () => void;
+  themeToggle?: boolean;
 }
 
 /**
@@ -36,6 +37,7 @@ export function shouldOpenInspector(
 
 // fallow-ignore-next-line complexity
 export function StudioHeader({
+  themeToggle = false,
   captureFrameHref,
   captureFrameFilename,
   handleCaptureFrameClick,
@@ -148,7 +150,7 @@ export function StudioHeader({
             </Button>
           </Tooltip>
         </div>
-        <ThemeToggle />
+        {themeToggle && <ThemeToggle />}
         <Dock.WindowMenu />
         <Tooltip
           label={
diff --git a/packages/studio/src/components/ThemeToggle.tsx b/packages/studio/src/components/ThemeToggle.tsx
index 124c335588..d8ad307a93 100644
--- a/packages/studio/src/components/ThemeToggle.tsx
+++ b/packages/studio/src/components/ThemeToggle.tsx
@@ -1,8 +1,9 @@
 import { useCallback } from "react";
 import { setStudioTheme, useShownStudioTheme } from "../utils/studioTheme";
+import { IconButton, Tooltip } from "./ui";
 
-// hyperframes.dev's theme toggle: the same sun and moon button, revealing the new theme in a circle
-// from the click. A page that paints no frame aborts the transition; the theme is applied by then.
+// hyperframes.dev's theme toggle: the same sun and moon, revealing the new theme in a circle from
+// the button. A page that paints no frame aborts the transition; the theme is applied by then.
 function reveal(transition: ViewTransition, at: string, radiusPct: number) {
   void transition.ready.then(
     () => {
@@ -15,69 +16,80 @@ function reveal(transition: ViewTransition, at: string, radiusPct: number) {
   );
 }
 
+function origin(e: React.MouseEvent<HTMLButtonElement>): [number, number] {
+  if (e.detail > 0) return [e.clientX, e.clientY];
+  const box = e.currentTarget.getBoundingClientRect();
+  return [box.left + box.width / 2, box.top + box.height / 2];
+}
+
+const still = () =>
+  !document.startViewTransition || window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+
 export function ThemeToggle() {
   const isDark = useShownStudioTheme() === "dark";
+  const label = `Switch to ${isDark ? "light" : "dark"} theme`;
 
   const toggle = useCallback(
     (e: React.MouseEvent<HTMLButtonElement>) => {
       const apply = () => setStudioTheme(isDark ? "light" : "dark");
-      if (!document.startViewTransition) return apply();
-      // The switch stays synchronous inside the callback: rendering is paused during it.
-      const { clientX: x, clientY: y } = e;
+      if (still()) return apply();
+      const [x, y] = origin(e);
       const w = window.innerWidth;
       const h = window.innerHeight;
       const maxRadius = Math.hypot(Math.max(x, w - x), Math.max(y, h - y));
       const at = `at ${(x / w) * 100}% ${(y / h) * 100}%`;
       const radiusPct = (maxRadius / (Math.hypot(w, h) / Math.SQRT2)) * 100;
+      // The switch stays synchronous inside the callback: rendering is paused during it.
       reveal(document.startViewTransition(apply), at, radiusPct);
     },
     [isDark],
   );
 
   return (
-    <button
-      type="button"
-      onClick={toggle}
-      className="inline-flex min-h-7 min-w-7 items-center justify-center rounded-full text-text-2 transition-all duration-hover hover:bg-hover hover:text-text-0 active:scale-[0.95]"
-      aria-label={`Switch to ${isDark ? "light" : "dark"} theme`}
-    >
-      {isDark ? (
-        <svg
-          width="14"
-          height="14"
-          viewBox="0 0 24 24"
-          fill="none"
-          stroke="currentColor"
-          strokeWidth="2"
-          strokeLinecap="round"
-          strokeLinejoin="round"
-          aria-hidden="true"
-        >
-          <circle cx="12" cy="12" r="5" />
-          <line x1="12" y1="1" x2="12" y2="3" />
-          <line x1="12" y1="21" x2="12" y2="23" />
-          <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
-          <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
-          <line x1="1" y1="12" x2="3" y2="12" />
-          <line x1="21" y1="12" x2="23" y2="12" />
-          <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
-          <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
-        </svg>
-      ) : (
-        <svg
-          width="14"
-          height="14"
-          viewBox="0 0 24 24"
-          fill="none"
-          stroke="currentColor"
-          strokeWidth="2"
-          strokeLinecap="round"
-          strokeLinejoin="round"
-          aria-hidden="true"
-        >
-          <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
-        </svg>
-      )}
-    </button>
+    <Tooltip label={label} side="bottom">
+      <IconButton
+        onClick={toggle}
+        aria-label={label}
+        icon={
+          isDark ? (
+            <svg
+              width="14"
+              height="14"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              aria-hidden="true"
+            >
+              <circle cx="12" cy="12" r="5" />
+              <line x1="12" y1="1" x2="12" y2="3" />
+              <line x1="12" y1="21" x2="12" y2="23" />
+              <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
+              <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
+              <line x1="1" y1="12" x2="3" y2="12" />
+              <line x1="21" y1="12" x2="23" y2="12" />
+              <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
+              <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
+            </svg>
+          ) : (
+            <svg
+              width="14"
+              height="14"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              aria-hidden="true"
+            >
+              <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
+            </svg>
+          )
+        }
+      />
+    </Tooltip>
   );
 }
diff --git a/packages/studio/src/main.tsx b/packages/studio/src/main.tsx
index 17d97def97..aaa15ef16e 100644
--- a/packages/studio/src/main.tsx
+++ b/packages/studio/src/main.tsx
@@ -128,7 +128,7 @@ createRoot(document.getElementById("root")!).render(
         Icons that pass their own size or weight still win. */}
     <IconContext.Provider value={readIconTokens()}>
       <StudioErrorBoundary>
-        <StudioApp />
+        <StudioApp themeToggle />
       </StudioErrorBoundary>
     </IconContext.Provider>
   </StrictMode>,
diff --git a/packages/studio/src/styles/studio.css b/packages/studio/src/styles/studio.css
index d6ea40bb99..ba57122036 100644
--- a/packages/studio/src/styles/studio.css
+++ b/packages/studio/src/styles/studio.css
@@ -16,6 +16,12 @@
   }
 }
 
+::view-transition-old(root),
+::view-transition-new(root) {
+  animation: none;
+  mix-blend-mode: normal;
+}
+
 body {
   margin: 0;
   padding: 0;
diff --git a/packages/studio/src/utils/studioTheme.test.tsx b/packages/studio/src/utils/studioTheme.test.tsx
index 23bf1bc864..be3cdb20dc 100644
--- a/packages/studio/src/utils/studioTheme.test.tsx
+++ b/packages/studio/src/utils/studioTheme.test.tsx
@@ -5,7 +5,7 @@ import { act } from "react";
 import { afterEach, describe, expect, it } from "vitest";
 import { ThemeToggle } from "../components/ThemeToggle";
 import { cleanupMounted, mountHost } from "../components/ui/mountHost.testHelpers";
-import { shownStudioTheme } from "./studioTheme";
+import { savedStudioTheme } from "./studioTheme";
 
 const KEY = "hf-studio-ui-preferences";
 const html = readFileSync(path.join(__dirname, "../../index.html"), "utf8");
@@ -15,6 +15,11 @@ function store(theme: unknown) {
   localStorage.setItem(KEY, JSON.stringify({ theme }));
 }
 
+function boots(): "light" | "dark" {
+  new Function(boot)();
+  return document.documentElement.dataset.theme === "paper" ? "light" : "dark";
+}
+
 afterEach(() => {
   cleanupMounted();
   localStorage.clear();
@@ -23,20 +28,21 @@ afterEach(() => {
 
 describe("Studio's theme", () => {
   it.each([["light"], ["dark"], [undefined], ["neon"]])(
-    "boots to the theme the owner shows (saved %s)",
+    "boots to the theme the owner picks (saved %s)",
     (saved) => {
       store(saved);
-      new Function(boot)();
-      expect(document.documentElement.dataset.theme === "paper").toBe(
-        shownStudioTheme() === "light",
-      );
+      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", () => {
-    new Function(boot)();
-    expect(document.documentElement.dataset.theme).toBe("paper");
-    expect(shownStudioTheme()).toBe("light");
+    expect(boots()).toBe("light");
+    expect(savedStudioTheme()).toBe("light");
   });
 
   it("runs the boot script before the app's module", () => {
@@ -44,19 +50,29 @@ describe("Studio's theme", () => {
     expect(html.indexOf("<script>")).toBeLessThan(html.indexOf('type="module"'));
   });
 
-  it("flips the document between light and dark and keeps the choice", () => {
+  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");
 
-    act(() => button().click());
+    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");
 
-    act(() => button().click());
+    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");
+  });
 });
diff --git a/packages/studio/src/utils/studioTheme.ts b/packages/studio/src/utils/studioTheme.ts
index e4f8ad5999..421ae8992f 100644
--- a/packages/studio/src/utils/studioTheme.ts
+++ b/packages/studio/src/utils/studioTheme.ts
@@ -1,6 +1,6 @@
-// The one owner of Studio's own theme: 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 repeats this rule before the first paint; studioTheme.test.tsx holds the two together.
+// 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,
@@ -8,28 +8,26 @@ import {
   type StudioTheme,
 } from "./studioUiPreferences";
 
-const listeners = new Set<() => void>();
-
-export function shownStudioTheme(): StudioTheme {
+export function savedStudioTheme(): StudioTheme {
   return readStudioUiPreferences().theme ?? "light";
 }
 
-function apply(): void {
-  const root = document.documentElement;
-  if (shownStudioTheme() === "light") root.dataset.theme = "paper";
-  else delete root.dataset.theme;
-  for (const listener of listeners) listener();
+export function shownStudioTheme(): StudioTheme {
+  return document.documentElement.dataset.theme === "paper" ? "light" : "dark";
 }
 
 export function setStudioTheme(theme: StudioTheme): void {
   writeStudioUiPreferences({ theme });
-  apply();
+  const root = document.documentElement;
+  if (theme === "light") root.dataset.theme = "paper";
+  else delete root.dataset.theme;
 }
 
-const subscribe = (listener: () => void) => {
-  listeners.add(listener);
-  return () => listeners.delete(listener);
-};
+function subscribe(listener: () => void): () => void {
+  const observer = new MutationObserver(listener);
+  observer.observe(document.documentElement, { attributeFilter: ["data-theme"] });
+  return () => observer.disconnect();
+}
 
 export const useShownStudioTheme = (): StudioTheme =>
   useSyncExternalStore(subscribe, shownStudioTheme);

From a9fcd7626f407337d5b42bfb46a80526c61d33ba Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Thu, 1 Oct 2026 05:50:48 -0700
Subject: [PATCH 5/8] fix(studio): the theme reveal leaves other view
 transitions alone; one default for the toggle

The crossfade rule applies only while the toggle's own transition runs, StudioApp passes the header's single default through, and the reveal's reduced-motion and keyboard paths are tested.
---
 packages/studio/src/App.tsx                   |  2 +-
 .../src/components/StudioHeader.dom.test.tsx  |  2 +-
 .../studio/src/components/ThemeToggle.tsx     |  3 ++
 packages/studio/src/styles/studio.css         |  4 +-
 .../studio/src/utils/studioTheme.test.tsx     | 43 ++++++++++++++++++-
 5 files changed, 49 insertions(+), 5 deletions(-)

diff --git a/packages/studio/src/App.tsx b/packages/studio/src/App.tsx
index a31d86177e..3a5cce6691 100644
--- a/packages/studio/src/App.tsx
+++ b/packages/studio/src/App.tsx
@@ -78,7 +78,7 @@ export interface StudioAppProps {
 export function StudioApp({
   readOnlyPreview = false,
   readOnlyPreviewReason,
-  themeToggle = false,
+  themeToggle,
 }: StudioAppProps = {}) {
   const { projectId, resolving, waitingForServer } = useServerConnection();
   const initialUrlStateRef = useRef(readStudioUrlStateFromWindow());
diff --git a/packages/studio/src/components/StudioHeader.dom.test.tsx b/packages/studio/src/components/StudioHeader.dom.test.tsx
index fd5af26df6..c79d881949 100644
--- a/packages/studio/src/components/StudioHeader.dom.test.tsx
+++ b/packages/studio/src/components/StudioHeader.dom.test.tsx
@@ -54,6 +54,7 @@ beforeEach(() => {
 });
 
 afterEach(() => {
+  delete document.documentElement.dataset.theme;
   if (!mounted) return;
   const { root, host } = mounted;
   mounted = null;
@@ -188,7 +189,6 @@ it("shows no theme toggle and leaves the host's data-theme alone when embedded",
   const host = mount();
   expect(host.querySelector('[aria-label^="Switch to"]')).toBeNull();
   expect(document.documentElement.dataset.theme).toBe("host");
-  delete document.documentElement.dataset.theme;
 });
 
 it("shows the theme toggle in Studio's own app", () => {
diff --git a/packages/studio/src/components/ThemeToggle.tsx b/packages/studio/src/components/ThemeToggle.tsx
index d8ad307a93..224fc832c4 100644
--- a/packages/studio/src/components/ThemeToggle.tsx
+++ b/packages/studio/src/components/ThemeToggle.tsx
@@ -5,6 +5,8 @@ import { IconButton, Tooltip } from "./ui";
 // hyperframes.dev's theme toggle: the same sun and moon, revealing the new theme in a circle from
 // the button. A page that paints no frame aborts the transition; the theme is applied by then.
 function reveal(transition: ViewTransition, at: string, radiusPct: number) {
+  const done = () => delete document.documentElement.dataset.themeReveal;
+  void transition.finished.then(done, done);
   void transition.ready.then(
     () => {
       document.documentElement.animate(
@@ -40,6 +42,7 @@ export function ThemeToggle() {
       const at = `at ${(x / w) * 100}% ${(y / h) * 100}%`;
       const radiusPct = (maxRadius / (Math.hypot(w, h) / Math.SQRT2)) * 100;
       // The switch stays synchronous inside the callback: rendering is paused during it.
+      document.documentElement.dataset.themeReveal = "";
       reveal(document.startViewTransition(apply), at, radiusPct);
     },
     [isDark],
diff --git a/packages/studio/src/styles/studio.css b/packages/studio/src/styles/studio.css
index ba57122036..f4abd78d97 100644
--- a/packages/studio/src/styles/studio.css
+++ b/packages/studio/src/styles/studio.css
@@ -16,8 +16,8 @@
   }
 }
 
-::view-transition-old(root),
-::view-transition-new(root) {
+[data-theme-reveal]::view-transition-old(root),
+[data-theme-reveal]::view-transition-new(root) {
   animation: none;
   mix-blend-mode: normal;
 }
diff --git a/packages/studio/src/utils/studioTheme.test.tsx b/packages/studio/src/utils/studioTheme.test.tsx
index be3cdb20dc..5445df2905 100644
--- a/packages/studio/src/utils/studioTheme.test.tsx
+++ b/packages/studio/src/utils/studioTheme.test.tsx
@@ -2,7 +2,7 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { act } from "react";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { ThemeToggle } from "../components/ThemeToggle";
 import { cleanupMounted, mountHost } from "../components/ui/mountHost.testHelpers";
 import { savedStudioTheme } from "./studioTheme";
@@ -76,3 +76,44 @@ describe("Studio's theme", () => {
     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 start = vi.fn((update: () => void) => {
+      update();
+      return { ready: Promise.resolve(), finished: Promise.resolve() };
+    });
+    Object.assign(document, { startViewTransition: start });
+    return { animate, start };
+  }
+
+  afterEach(() => {
+    Reflect.deleteProperty(document, "startViewTransition");
+    Reflect.deleteProperty(document.documentElement, "animate");
+    vi.unstubAllGlobals();
+  });
+
+  it("grows from the button's centre when the keyboard presses it, then clears its marker", async () => {
+    const { animate } = 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(animate.mock.calls[0]![0].clipPath[1]).toContain("at 90% 4%");
+    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");
+  });
+});

From e1f9b0367e5a4efaca36d7468ca971a22b2e3947 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Thu, 1 Oct 2026 06:08:37 -0700
Subject: [PATCH 6/8] fix(studio): a second theme click mid-reveal keeps the
 crossfade off

Only the latest reveal clears the document marker; tests pin the marker while a reveal runs and the circle's radius.
---
 .../studio/src/components/ThemeToggle.tsx     |  7 ++++-
 .../studio/src/utils/studioTheme.test.tsx     | 26 +++++++++++++++----
 2 files changed, 27 insertions(+), 6 deletions(-)

diff --git a/packages/studio/src/components/ThemeToggle.tsx b/packages/studio/src/components/ThemeToggle.tsx
index 224fc832c4..6ccc20b3b1 100644
--- a/packages/studio/src/components/ThemeToggle.tsx
+++ b/packages/studio/src/components/ThemeToggle.tsx
@@ -4,8 +4,13 @@ import { IconButton, Tooltip } from "./ui";
 
 // hyperframes.dev's theme toggle: the same sun and moon, revealing the new theme in a circle from
 // the button. A page that paints no frame aborts the transition; the theme is applied by then.
+let latest: ViewTransition | null = null;
+
 function reveal(transition: ViewTransition, at: string, radiusPct: number) {
-  const done = () => delete document.documentElement.dataset.themeReveal;
+  latest = transition;
+  const done = () => {
+    if (latest === transition) delete document.documentElement.dataset.themeReveal;
+  };
   void transition.finished.then(done, done);
   void transition.ready.then(
     () => {
diff --git a/packages/studio/src/utils/studioTheme.test.tsx b/packages/studio/src/utils/studioTheme.test.tsx
index 5445df2905..a6d425ef5c 100644
--- a/packages/studio/src/utils/studioTheme.test.tsx
+++ b/packages/studio/src/utils/studioTheme.test.tsx
@@ -81,12 +81,15 @@ 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: Promise.resolve() };
+      return { ready: Promise.resolve(), finished: new Promise<void>((done) => finish.push(done)) };
     });
     Object.assign(document, { startViewTransition: start });
-    return { animate, start };
+    return { animate, start, markers, finish };
   }
 
   afterEach(() => {
@@ -95,8 +98,8 @@ describe("the reveal", () => {
     vi.unstubAllGlobals();
   });
 
-  it("grows from the button's centre when the keyboard presses it, then clears its marker", async () => {
-    const { animate } = stubTransition();
+  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")!;
@@ -104,7 +107,20 @@ describe("the reveal", () => {
     await act(async () => {
       button.dispatchEvent(new MouseEvent("click", { bubbles: true, detail: 0 }));
     });
-    expect(animate.mock.calls[0]![0].clipPath[1]).toContain("at 90% 4%");
+    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();
   });
 

From c12954c79a9c03688b5fce34811395f14bde5262 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Thu, 1 Oct 2026 06:22:46 -0700
Subject: [PATCH 7/8] refactor(studio): the theme toggle shares its icon props
 and reads as plain functions

Simplify pass: one icon props object for the sun and moon, no useCallback around a handler nothing memoises, cannotReveal named for what it answers, the test reuses the theme reader.
---
 .../studio/src/components/ThemeToggle.tsx     | 74 +++++++++----------
 .../studio/src/utils/studioTheme.test.tsx     |  4 +-
 packages/studio/src/utils/studioTheme.ts      |  5 +-
 3 files changed, 38 insertions(+), 45 deletions(-)

diff --git a/packages/studio/src/components/ThemeToggle.tsx b/packages/studio/src/components/ThemeToggle.tsx
index 6ccc20b3b1..a81254cce4 100644
--- a/packages/studio/src/components/ThemeToggle.tsx
+++ b/packages/studio/src/components/ThemeToggle.tsx
@@ -1,4 +1,3 @@
-import { useCallback } from "react";
 import { setStudioTheme, useShownStudioTheme } from "../utils/studioTheme";
 import { IconButton, Tooltip } from "./ui";
 
@@ -29,29 +28,42 @@ function origin(e: React.MouseEvent<HTMLButtonElement>): [number, number] {
   return [box.left + box.width / 2, box.top + box.height / 2];
 }
 
-const still = () =>
-  !document.startViewTransition || window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+function cannotReveal(): boolean {
+  return (
+    !document.startViewTransition ||
+    window.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true
+  );
+}
+
+const iconProps = {
+  width: "14",
+  height: "14",
+  viewBox: "0 0 24 24",
+  fill: "none",
+  stroke: "currentColor",
+  strokeWidth: "2",
+  strokeLinecap: "round",
+  strokeLinejoin: "round",
+  "aria-hidden": true,
+} as const;
 
 export function ThemeToggle() {
   const isDark = useShownStudioTheme() === "dark";
   const label = `Switch to ${isDark ? "light" : "dark"} theme`;
 
-  const toggle = useCallback(
-    (e: React.MouseEvent<HTMLButtonElement>) => {
-      const apply = () => setStudioTheme(isDark ? "light" : "dark");
-      if (still()) return apply();
-      const [x, y] = origin(e);
-      const w = window.innerWidth;
-      const h = window.innerHeight;
-      const maxRadius = Math.hypot(Math.max(x, w - x), Math.max(y, h - y));
-      const at = `at ${(x / w) * 100}% ${(y / h) * 100}%`;
-      const radiusPct = (maxRadius / (Math.hypot(w, h) / Math.SQRT2)) * 100;
-      // The switch stays synchronous inside the callback: rendering is paused during it.
-      document.documentElement.dataset.themeReveal = "";
-      reveal(document.startViewTransition(apply), at, radiusPct);
-    },
-    [isDark],
-  );
+  function toggle(e: React.MouseEvent<HTMLButtonElement>) {
+    const apply = () => setStudioTheme(isDark ? "light" : "dark");
+    if (cannotReveal()) return apply();
+    const [x, y] = origin(e);
+    const w = window.innerWidth;
+    const h = window.innerHeight;
+    const maxRadius = Math.hypot(Math.max(x, w - x), Math.max(y, h - y));
+    const at = `at ${(x / w) * 100}% ${(y / h) * 100}%`;
+    const radiusPct = (maxRadius / (Math.hypot(w, h) / Math.SQRT2)) * 100;
+    // The switch stays synchronous inside the callback: rendering is paused during it.
+    document.documentElement.dataset.themeReveal = "";
+    reveal(document.startViewTransition(apply), at, radiusPct);
+  }
 
   return (
     <Tooltip label={label} side="bottom">
@@ -60,17 +72,7 @@ export function ThemeToggle() {
         aria-label={label}
         icon={
           isDark ? (
-            <svg
-              width="14"
-              height="14"
-              viewBox="0 0 24 24"
-              fill="none"
-              stroke="currentColor"
-              strokeWidth="2"
-              strokeLinecap="round"
-              strokeLinejoin="round"
-              aria-hidden="true"
-            >
+            <svg {...iconProps}>
               <circle cx="12" cy="12" r="5" />
               <line x1="12" y1="1" x2="12" y2="3" />
               <line x1="12" y1="21" x2="12" y2="23" />
@@ -82,17 +84,7 @@ export function ThemeToggle() {
               <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
             </svg>
           ) : (
-            <svg
-              width="14"
-              height="14"
-              viewBox="0 0 24 24"
-              fill="none"
-              stroke="currentColor"
-              strokeWidth="2"
-              strokeLinecap="round"
-              strokeLinejoin="round"
-              aria-hidden="true"
-            >
+            <svg {...iconProps}>
               <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
             </svg>
           )
diff --git a/packages/studio/src/utils/studioTheme.test.tsx b/packages/studio/src/utils/studioTheme.test.tsx
index a6d425ef5c..973cde403a 100644
--- a/packages/studio/src/utils/studioTheme.test.tsx
+++ b/packages/studio/src/utils/studioTheme.test.tsx
@@ -5,7 +5,7 @@ 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 } from "./studioTheme";
+import { savedStudioTheme, shownStudioTheme } from "./studioTheme";
 
 const KEY = "hf-studio-ui-preferences";
 const html = readFileSync(path.join(__dirname, "../../index.html"), "utf8");
@@ -17,7 +17,7 @@ function store(theme: unknown) {
 
 function boots(): "light" | "dark" {
   new Function(boot)();
-  return document.documentElement.dataset.theme === "paper" ? "light" : "dark";
+  return shownStudioTheme();
 }
 
 afterEach(() => {
diff --git a/packages/studio/src/utils/studioTheme.ts b/packages/studio/src/utils/studioTheme.ts
index 421ae8992f..7fabb66d14 100644
--- a/packages/studio/src/utils/studioTheme.ts
+++ b/packages/studio/src/utils/studioTheme.ts
@@ -29,5 +29,6 @@ function subscribe(listener: () => void): () => void {
   return () => observer.disconnect();
 }
 
-export const useShownStudioTheme = (): StudioTheme =>
-  useSyncExternalStore(subscribe, shownStudioTheme);
+export function useShownStudioTheme(): StudioTheme {
+  return useSyncExternalStore(subscribe, shownStudioTheme);
+}

From 1c4be8a803edd725da757fd79a2e30ad2a0c1528 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Thu, 1 Oct 2026 07:58:23 -0700
Subject: [PATCH 8/8] fix(studio): studio's own app turns the theme toggle on
 through context; tests parse index.html

App.tsx stays at main's size: main.tsx provides ShowThemeToggle and the header reads it, default off for hosts. The boot-script tests read index.html through DOMParser instead of an HTML regex.
---
 packages/studio/src/App.tsx                   |  8 +-----
 .../src/components/StudioHeader.dom.test.tsx  | 25 ++++++++++++-------
 .../studio/src/components/StudioHeader.tsx    |  9 +++----
 .../studio/src/components/ThemeToggle.tsx     |  4 +++
 packages/studio/src/main.tsx                  |  5 +++-
 .../studio/src/utils/studioTheme.test.tsx     | 12 ++++++---
 6 files changed, 38 insertions(+), 25 deletions(-)

diff --git a/packages/studio/src/App.tsx b/packages/studio/src/App.tsx
index 3a5cce6691..38d728b393 100644
--- a/packages/studio/src/App.tsx
+++ b/packages/studio/src/App.tsx
@@ -71,15 +71,10 @@ export interface StudioAppProps {
   readOnlyPreview?: boolean;
   /** Short text shown on disabled hand-edit controls while `readOnlyPreview` is set. */
   readOnlyPreviewReason?: string;
-  themeToggle?: boolean;
 }
 
 // fallow-ignore-next-line complexity
-export function StudioApp({
-  readOnlyPreview = false,
-  readOnlyPreviewReason,
-  themeToggle,
-}: StudioAppProps = {}) {
+export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: StudioAppProps = {}) {
   const { projectId, resolving, waitingForServer } = useServerConnection();
   const initialUrlStateRef = useRef(readStudioUrlStateFromWindow());
   useStudioSessionStart(projectId, resolving, waitingForServer);
@@ -470,7 +465,6 @@ export function StudioApp({
                 onDrop={fileDrop.onDrop}
               >
                 <StudioHeader
-                  themeToggle={themeToggle}
                   captureFrameHref={frameCapture.captureFrameHref}
                   captureFrameFilename={frameCapture.captureFrameFilename}
                   handleCaptureFrameClick={frameCapture.handleCaptureFrameClick}
diff --git a/packages/studio/src/components/StudioHeader.dom.test.tsx b/packages/studio/src/components/StudioHeader.dom.test.tsx
index c79d881949..263433c7a9 100644
--- a/packages/studio/src/components/StudioHeader.dom.test.tsx
+++ b/packages/studio/src/components/StudioHeader.dom.test.tsx
@@ -42,6 +42,7 @@ vi.mock("../contexts/PanelLayoutContext", () => ({
 vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
 
 const { StudioHeader } = await import("./StudioHeader");
+const { ShowThemeToggle } = await import("./ThemeToggle");
 
 let mounted: { root: Root; host: HTMLElement } | null = null;
 
@@ -69,17 +70,23 @@ function mount(
   document.body.append(host);
   const root = createRoot(host);
   mounted = { root, host };
+  const header = (
+    <StudioHeader
+      captureFrameHref="blob:frame"
+      captureFrameFilename="frame.png"
+      handleCaptureFrameClick={vi.fn()}
+      refreshCaptureFrameTime={vi.fn()}
+      inspectorButtonActive={props.inspectorButtonActive ?? false}
+      inspectorPanelActive={false}
+    />
+  );
   act(() =>
     root.render(
-      <StudioHeader
-        captureFrameHref="blob:frame"
-        captureFrameFilename="frame.png"
-        handleCaptureFrameClick={vi.fn()}
-        refreshCaptureFrameTime={vi.fn()}
-        inspectorButtonActive={props.inspectorButtonActive ?? false}
-        inspectorPanelActive={false}
-        themeToggle={props.themeToggle}
-      />,
+      props.themeToggle ? (
+        <ShowThemeToggle.Provider value>{header}</ShowThemeToggle.Provider>
+      ) : (
+        header
+      ),
     ),
   );
   return host;
diff --git a/packages/studio/src/components/StudioHeader.tsx b/packages/studio/src/components/StudioHeader.tsx
index e765b42720..8eff9c4e94 100644
--- a/packages/studio/src/components/StudioHeader.tsx
+++ b/packages/studio/src/components/StudioHeader.tsx
@@ -1,4 +1,4 @@
-import type { MouseEvent } from "react";
+import { useContext, type MouseEvent } from "react";
 import { Camera } from "../icons/SystemIcons";
 import { useStudioShellContext } from "../contexts/StudioContext";
 import { usePanelLayoutContext } from "../contexts/PanelLayoutContext";
@@ -7,7 +7,7 @@ import { Button, buttonBase, buttonSizes, buttonVariants, cn, Tooltip } from "./
 import { Dock } from "./dock/Dock";
 import { InspectorIcon } from "./icons/InspectorIcon";
 import { HyperframesLogo } from "./ui/HyperframesLogo";
-import { ThemeToggle } from "./ThemeToggle";
+import { ShowThemeToggle, ThemeToggle } from "./ThemeToggle";
 
 export interface StudioHeaderProps {
   captureFrameHref: string;
@@ -18,7 +18,6 @@ export interface StudioHeaderProps {
   inspectorButtonActive: boolean;
   inspectorPanelActive: boolean;
   onExport?: () => void;
-  themeToggle?: boolean;
 }
 
 /**
@@ -37,7 +36,6 @@ export function shouldOpenInspector(
 
 // fallow-ignore-next-line complexity
 export function StudioHeader({
-  themeToggle = false,
   captureFrameHref,
   captureFrameFilename,
   handleCaptureFrameClick,
@@ -47,6 +45,7 @@ export function StudioHeader({
   inspectorPanelActive,
   onExport,
 }: StudioHeaderProps) {
+  const showThemeToggle = useContext(ShowThemeToggle);
   const { projectId, renderQueue } = useStudioShellContext();
   const { rightCollapsed, setRightCollapsed, setRightPanelTab } = usePanelLayoutContext();
   const isRendering = renderQueue.isRendering;
@@ -150,7 +149,7 @@ export function StudioHeader({
             </Button>
           </Tooltip>
         </div>
-        {themeToggle && <ThemeToggle />}
+        {showThemeToggle && <ThemeToggle />}
         <Dock.WindowMenu />
         <Tooltip
           label={
diff --git a/packages/studio/src/components/ThemeToggle.tsx b/packages/studio/src/components/ThemeToggle.tsx
index a81254cce4..eaaddac457 100644
--- a/packages/studio/src/components/ThemeToggle.tsx
+++ b/packages/studio/src/components/ThemeToggle.tsx
@@ -1,3 +1,4 @@
+import { createContext } from "react";
 import { setStudioTheme, useShownStudioTheme } from "../utils/studioTheme";
 import { IconButton, Tooltip } from "./ui";
 
@@ -28,6 +29,9 @@ function origin(e: React.MouseEvent<HTMLButtonElement>): [number, number] {
   return [box.left + box.width / 2, box.top + box.height / 2];
 }
 
+/** On only in Studio's own app; a host that embeds Studio owns its theme. */
+export const ShowThemeToggle = createContext(false);
+
 function cannotReveal(): boolean {
   return (
     !document.startViewTransition ||
diff --git a/packages/studio/src/main.tsx b/packages/studio/src/main.tsx
index aaa15ef16e..7ee9e3953f 100644
--- a/packages/studio/src/main.tsx
+++ b/packages/studio/src/main.tsx
@@ -2,6 +2,7 @@ import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { IconContext } from "@phosphor-icons/react";
 import { StudioApp } from "./App";
+import { ShowThemeToggle } from "./components/ThemeToggle";
 import { StudioErrorBoundary } from "./components/StudioErrorBoundary";
 import { readIconTokens } from "./styles/iconTokens";
 import { trackStudioEvent } from "./utils/studioTelemetry";
@@ -128,7 +129,9 @@ createRoot(document.getElementById("root")!).render(
         Icons that pass their own size or weight still win. */}
     <IconContext.Provider value={readIconTokens()}>
       <StudioErrorBoundary>
-        <StudioApp themeToggle />
+        <ShowThemeToggle.Provider value>
+          <StudioApp />
+        </ShowThemeToggle.Provider>
       </StudioErrorBoundary>
     </IconContext.Provider>
   </StrictMode>,
diff --git a/packages/studio/src/utils/studioTheme.test.tsx b/packages/studio/src/utils/studioTheme.test.tsx
index 973cde403a..37dbca772e 100644
--- a/packages/studio/src/utils/studioTheme.test.tsx
+++ b/packages/studio/src/utils/studioTheme.test.tsx
@@ -8,8 +8,12 @@ import { cleanupMounted, mountHost } from "../components/ui/mountHost.testHelper
 import { savedStudioTheme, shownStudioTheme } from "./studioTheme";
 
 const KEY = "hf-studio-ui-preferences";
-const html = readFileSync(path.join(__dirname, "../../index.html"), "utf8");
-const boot = html.match(/<script>([\s\S]*?)<\/script>/)?.[1] ?? "";
+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 }));
@@ -47,7 +51,9 @@ describe("Studio's theme", () => {
 
   it("runs the boot script before the app's module", () => {
     expect(boot).toContain(`"${KEY}"`);
-    expect(html.indexOf("<script>")).toBeLessThan(html.indexOf('type="module"'));
+    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 () => {