@hyperframes/studio 0.8.105 → 0.8.107

package/src/utils/studioPendingEdits.ts

@@ -1,4 +1,5 @@
 import { StudioFileConflictError, type StudioSaveDrainResult } from "./studioSaveDiagnostics";
+import { isTypingTarget } from "./typingTarget";
 
 const STUDIO_FLUSH_PENDING_EDITS_EVENT = "hf-studio-flush-pending-edits";
 
@@ -29,16 +30,34 @@ function inspectDrainFailures(results: PromiseSettledResult<unknown>[]): {
 
 function focusedField(): HTMLElement | null {
   const active = document.activeElement;
-  return active instanceof HTMLElement &&
-    active.matches('input, textarea, select, [contenteditable="true"], [role="textbox"]')
-    ? active
-    : null;
+  return active instanceof HTMLElement && isTypingTarget(active) ? active : null;
 }
 
 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 {
@@ -52,6 +71,16 @@ export function trackStudioPendingEdit(
   return promise;
 }
 
+export function trackedStudioEdit<Args extends unknown[], R>(
+  edit: (...args: Args) => R,
+): (...args: Args) => R {
+  return (...args) => {
+    const result = edit(...args);
+    if (result instanceof Promise) trackStudioPendingEdit(result);
+    return result;
+  };
+}
+
 export async function flushStudioPendingEdits(): Promise<StudioPendingEditsDrainResult> {
   const active = focusedField();
   if (active) {
@@ -65,15 +94,16 @@ export async function flushStudioPendingEdits(): Promise<StudioPendingEditsDrain
   window.dispatchEvent(
     new CustomEvent<StudioFlushPendingEditsDetail>(STUDIO_FLUSH_PENDING_EDITS_EVENT, { detail }),
   );
+  let conflict: StudioFileConflictError | undefined;
   let firstFailure: PromiseRejectedResult | undefined;
   while (detail.promises.length > 0 || pendingEditPromises.size > 0) {
     const promises = [...detail.promises, ...pendingEditPromises];
     detail.promises = [];
-    const results = await Promise.allSettled(promises);
-    const batchFailures = inspectDrainFailures(results);
-    if (batchFailures.conflict) return { status: "conflict", error: batchFailures.conflict };
+    const batchFailures = inspectDrainFailures(await Promise.allSettled(promises));
+    conflict ??= batchFailures.conflict;
     firstFailure ??= batchFailures.firstFailure;
   }
+  if (conflict) return { status: "conflict", error: conflict };
   return firstFailure ? { status: "failed", error: firstFailure.reason } : { status: "clean" };
 }
 

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;
     }

package/src/utils/typingTarget.test.ts

@@ -1,7 +1,7 @@
 // @vitest-environment happy-dom
 
 import { afterEach, describe, expect, it } from "vitest";
-import { isTypingTarget } from "./typingTarget";
+import { isTypingTarget, ownsPlainKeys } from "./typingTarget";
 import { isEditableTarget } from "./timelineDiscovery";
 
 afterEach(() => {
@@ -41,6 +41,13 @@ describe("isTypingTarget", () => {
     expect(isTypingTarget(mount('<div role="combobox"></div>'))).toBe(true);
   });
 
+  it("gives a focused slider its plain keys but leaves Cmd shortcuts to the app", () => {
+    const slider = mount('<div role="slider" tabindex="0"></div>');
+    expect(ownsPlainKeys(slider)).toBe(true);
+    // Undo, copy and group still reach the app while a slider has focus.
+    expect(isTypingTarget(slider)).toBe(false);
+  });
+
   it("leaves the keys alone for anything that is not being typed into", () => {
     expect(isTypingTarget(mount("<div>plain</div>"))).toBe(false);
     expect(isTypingTarget(mount("<button>press</button>"))).toBe(false);
@@ -52,3 +59,16 @@ describe("isTypingTarget", () => {
     expect(isTypingTarget({} as EventTarget)).toBe(false);
   });
 });
+
+describe("ownsPlainKeys", () => {
+  it("is true for a native player with controls and for anything typing claims", () => {
+    expect(ownsPlainKeys(mount("<video controls></video>"))).toBe(true);
+    expect(ownsPlainKeys(mount("<audio controls></audio>"))).toBe(true);
+    expect(ownsPlainKeys(mount("<input />"))).toBe(true);
+  });
+
+  it("is false for a player without controls and for plain elements", () => {
+    expect(ownsPlainKeys(mount("<video></video>"))).toBe(false);
+    expect(ownsPlainKeys(mount("<div></div>"))).toBe(false);
+  });
+});

package/src/utils/typingTarget.ts

@@ -21,6 +21,14 @@ export function isTypingTarget(target: EventTarget | null): boolean {
   return element.closest(TYPING_SELECTOR) !== null;
 }
 
+/** Plain keys (arrows, Space, Delete) also belong to a focused slider or player; Cmd shortcuts still do not. */
+export function ownsPlainKeys(target: EventTarget | null): boolean {
+  return isTypingTarget(target) || asElement(target)?.closest(KEY_OWNING_CONTROLS) != null;
+}
+
+// A slider steps and a native player seeks and plays with these keys themselves.
+const KEY_OWNING_CONTROLS = "[role='slider'],video[controls],audio[controls]";
+
 /**
  * Things a keystroke belongs to rather than to a shortcut. `contenteditable` is
  * matched by value as well, for a host whose own property is not yet true.

package/src/webmcp/useStudioAgentTools.ts

@@ -111,7 +111,9 @@ export interface StudioAgentToolsDeps
  * a snapshot, which is what lets the list be built once and still see live
  * state. That is the whole point of the ref: see the registration note below.
  */
-function buildStudioTools(depsRef: { readonly current: StudioAgentToolsDeps }): ModelContextTool[] {
+export function buildStudioTools(depsRef: {
+  readonly current: StudioAgentToolsDeps;
+}): ModelContextTool[] {
   /**
    * `execute` for a tool whose handler takes the caller's abort signal.
    *