@hyperframes/studio 0.8.51 → 0.8.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.51",
+  "version": "0.8.52",
   "description": "",
   "repository": {
     "type": "git",
@@ -30,6 +30,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@base-ui/react": "1.7.0",
     "@codemirror/autocomplete": "^6.20.1",
     "@codemirror/commands": "^6.10.3",
     "@codemirror/lang-css": "^6.3.1",
@@ -45,14 +46,15 @@
     "@phosphor-icons/react": "^2.1.10",
     "@tanstack/react-virtual": "^3.14.6",
     "bpm-detective": "^2.0.5",
+    "cn": "0.2.4",
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.51",
-    "@hyperframes/player": "0.8.51",
-    "@hyperframes/studio-server": "0.8.51",
-    "@hyperframes/sdk": "0.8.51",
-    "@hyperframes/parsers": "0.8.51"
+    "@hyperframes/core": "0.8.52",
+    "@hyperframes/player": "0.8.52",
+    "@hyperframes/sdk": "0.8.52",
+    "@hyperframes/parsers": "0.8.52",
+    "@hyperframes/studio-server": "0.8.52"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -68,7 +70,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.51"
+    "@hyperframes/producer": "0.8.52"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -1,3 +1,4 @@
+import { useOwnPreviewIframe, usePreviewIframeStore } from "./player/store/previewIframeStore";
 import { buildProjectApiPath } from "./utils/projectRouting";
 import { useState, useCallback, useRef, useMemo, useLayoutEffect } from "react";
 import type { LeftSidebarHandle, SidebarTab } from "./components/sidebar/LeftSidebar";
@@ -68,7 +69,7 @@ export function StudioApp() {
   const initialUrlStateRef = useRef(readStudioUrlStateFromWindow());
   useStudioSessionStart(projectId, resolving, waitingForServer);
   const [compIdToSrc, setCompIdToSrc] = useState<Map<string, string>>(new Map());
-  const [previewIframe, setPreviewIframe] = useState<HTMLIFrameElement | null>(null);
+  const previewIframe = useOwnPreviewIframe();
   const [compositionLoading, setCompositionLoading] = useState(true);
   const [refreshKey, setRefreshKey] = useState(0);
   const [previewDocumentVersion, refreshPreviewDocumentVersion] = usePreviewDocumentVersion();
@@ -359,7 +360,7 @@ export function StudioApp() {
   const handlePreviewIframeRef = useCallback(
     (iframe: HTMLIFrameElement | null) => {
       previewIframeRef.current = iframe;
-      setPreviewIframe(iframe);
+      usePreviewIframeStore.getState().setIframe(iframe);
       appHotkeys.syncPreviewHotkeys(iframe);
       resetConsoleErrors();
       refreshPreviewDocumentVersion();

package/src/captions/components/CaptionOverlay.sender.test.tsx

@@ -4,6 +4,7 @@ import { createRoot } from "react-dom/client";
 import { expect, it, vi } from "vitest";
 import { CaptionOverlay } from "./CaptionOverlay";
 import { useCaptionStore } from "../store";
+import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
 
 Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
 
@@ -45,3 +46,54 @@ it("only schedules caption layout for messages from its preview", () => {
     vi.unstubAllGlobals();
   }
 });
+
+it("observes and accepts messages from the promoted iframe, not the old one", () => {
+  const host = document.createElement("div");
+  const a = document.createElement("iframe");
+  const b = document.createElement("iframe");
+  document.body.append(host, a, b);
+  const ref = { current: a };
+  const root = createRoot(host);
+  const schedule = vi.fn(() => 1);
+  const observed: Element[] = [];
+  vi.stubGlobal("requestAnimationFrame", schedule);
+  vi.stubGlobal("cancelAnimationFrame", vi.fn());
+  vi.stubGlobal(
+    "ResizeObserver",
+    class {
+      observe(el: Element) {
+        observed.push(el);
+      }
+      disconnect() {}
+    },
+  );
+  useCaptionStore.getState().setEditMode(true);
+  const send = (source: MessageEventSource | null) =>
+    act(() => {
+      window.dispatchEvent(new MessageEvent("message", { source, data: { source: "hf-preview" } }));
+    });
+  try {
+    act(() => usePreviewIframeStore.getState().setIframe(a));
+    act(() => root.render(<CaptionOverlay iframeRef={ref} />));
+    expect(observed).toContain(a);
+    expect(observed).not.toContain(b);
+    act(() => {
+      ref.current = b;
+      usePreviewIframeStore.getState().setIframe(b);
+    });
+    expect(observed).toContain(b);
+    schedule.mockClear();
+    send(a.contentWindow);
+    expect(schedule).not.toHaveBeenCalled();
+    send(b.contentWindow);
+    expect(schedule).toHaveBeenCalledOnce();
+  } finally {
+    act(() => root.unmount());
+    usePreviewIframeStore.setState({ iframe: null });
+    useCaptionStore.getState().reset();
+    host.remove();
+    a.remove();
+    b.remove();
+    vi.unstubAllGlobals();
+  }
+});

package/src/captions/components/CaptionOverlay.tsx

@@ -1,7 +1,7 @@
-import { memo, useState, useCallback, useRef } from "react";
+import { memo, useEffect, useState, useCallback, useRef } from "react";
+import { useLivePreviewIframe } from "../../player/store/previewIframeStore";
 import { useCaptionStore } from "../store";
 import { usePlayerStore } from "../../player";
-import { useMountEffect } from "../../hooks/useMountEffect";
 import { shouldHandleCaptionNudgeKey, isEditableEventTarget } from "../keyboard";
 import {
   readWordBoxes,
@@ -32,6 +32,7 @@ function syncToStore(segmentId: string, el: HTMLElement, iframeWin: Window) {
 
 export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: CaptionOverlayProps) {
   const isEditMode = useCaptionStore((s) => s.isEditMode);
+  const livePreviewIframe = useLivePreviewIframe();
   const model = useCaptionStore((s) => s.model);
   const selectedSegmentIds = useCaptionStore((s) => s.selectedSegmentIds);
   const selectSegment = useCaptionStore((s) => s.selectSegment);
@@ -81,7 +82,9 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
     | null
   >(null);
 
-  useMountEffect(() => {
+  // The observer and message filter bind to the live iframe element, which a promoted reload replaces.
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
     if (!isEditMode) return;
 
     // Let undo/redo (useAppHotkeys) reapply restored models to this iframe.
@@ -240,7 +243,8 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
       window.removeEventListener("keydown", handleKeyDown);
       cancelDragRef.current = null;
     };
-  });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [livePreviewIframe]);
 
   const getCssScale = useCallback(() => {
     const iframe = iframeRef.current;

package/src/components/EditorShell.tsx

@@ -65,6 +65,10 @@ export interface EditorShellProps extends TimelineEditCallbackDeps {
   isGestureRecording?: boolean;
   recordingState?: GestureRecordingState;
   onToggleRecording?: () => void;
+  /**
+   * Host layer over the preview, positioned with `usePreviewCompositionRect`. Hidden in
+   * fullscreen and during a block preview; below the selection overlay past z-index 10.
+   */
   gestureOverlay?: ReactNode;
 }
 

package/src/components/RightPanelTabs.test.tsx

@@ -0,0 +1,151 @@
+// @vitest-environment happy-dom
+
+/**
+ * The strip's keyboard behaviour, which tab reads as selected, and how the hotkey
+ * filters classify the elements (KTD13). The arrow-key tests are new behaviour, not a port.
+ */
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, expect, it, vi } from "vitest";
+import { RightPanelTabs, type RightPanelTabDescriptor } from "./RightPanelTabs";
+import { isTypingTarget } from "../utils/typingTarget";
+import { shouldIgnorePlaybackShortcutTarget } from "../player/lib/playbackShortcuts";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const IDS = ["design", "layers", "renders", "variables"];
+
+let mounted: { root: Root; host: HTMLElement } | null = null;
+
+afterEach(() => {
+  if (!mounted) return;
+  const { root, host } = mounted;
+  mounted = null;
+  act(() => root.unmount());
+  host.remove();
+});
+
+/** The harness owns the active state too, so a selection moves as it does in the real panel. */
+function mount(
+  initialActive: string[],
+  activateOnFocus = true,
+): {
+  host: HTMLElement;
+  selections: ReturnType<typeof vi.fn>;
+} {
+  const selections = vi.fn();
+
+  function Harness() {
+    const [active, setActive] = React.useState(initialActive);
+    const tabs: RightPanelTabDescriptor[] = IDS.map((id) => ({
+      id,
+      label: id,
+      tooltip: `${id} tooltip`,
+      active: active.includes(id),
+      onSelect: () => {
+        selections(id);
+        setActive([id]);
+      },
+    }));
+    return <RightPanelTabs tabs={tabs} activateOnFocus={activateOnFocus} />;
+  }
+
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  mounted = { root, host };
+  act(() => root.render(<Harness />));
+  return { host, selections };
+}
+
+function tab(host: HTMLElement, id: string): HTMLElement {
+  const el = host.querySelector<HTMLElement>(`[data-tab-id="${id}"]`);
+  if (!el) throw new Error(`no tab for ${id}`);
+  return el;
+}
+
+function selected(host: HTMLElement): string | null {
+  return (
+    host.querySelector('[role="tab"][aria-selected="true"]')?.getAttribute("data-tab-id") ?? null
+  );
+}
+
+/** Base UI moves the roving tabindex synchronously and the focus one task later. */
+async function arrow(key: string): Promise<void> {
+  const target = document.activeElement ?? document.body;
+  act(() => {
+    target.dispatchEvent(new KeyboardEvent("keydown", { key, bubbles: true, composed: true }));
+  });
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+}
+
+it("moves from Design to Layers with ArrowRight and asks the panel to switch", async () => {
+  const { host, selections } = mount(["design"]);
+  act(() => tab(host, "design").focus());
+
+  await arrow("ArrowRight");
+
+  expect(document.activeElement).toBe(tab(host, "layers"));
+  expect(selections).toHaveBeenCalledWith("layers");
+});
+
+it("only moves focus on an arrow key when selection would toggle a pane", async () => {
+  const { host, selections } = mount(["design"], false);
+  act(() => tab(host, "design").focus());
+
+  await arrow("ArrowRight");
+
+  expect(document.activeElement).toBe(tab(host, "layers"));
+  expect(selections).not.toHaveBeenCalled();
+});
+
+it("jumps to the first and last tab with Home and End", async () => {
+  const { host, selections } = mount(["design"]);
+  act(() => tab(host, "design").focus());
+
+  await arrow("End");
+  expect(document.activeElement).toBe(tab(host, "variables"));
+  expect(selections).toHaveBeenLastCalledWith("variables");
+
+  await arrow("Home");
+  expect(document.activeElement).toBe(tab(host, "design"));
+  expect(selections).toHaveBeenLastCalledWith("design");
+});
+
+it("selects the tab whose content is on screen", () => {
+  const { host } = mount(["renders"]);
+
+  expect(selected(host)).toBe("renders");
+});
+
+it("leaves every tab unselected when the panel shows something the strip has no tab for", () => {
+  // Block params take over the panel body without a tab of their own. The old
+  // buttons all read unpressed in that state; nothing should read selected now.
+  const { host } = mount([]);
+
+  expect(selected(host)).toBe(null);
+});
+
+it("keeps a second open pane looking open in the legacy split inspector", () => {
+  // Design and Layers render together there. Only one tab can carry
+  // aria-selected, so the other has to keep the selected look or the strip
+  // would claim a pane is closed while it is on screen.
+  const { host } = mount(["design", "layers"]);
+
+  expect(selected(host)).toBe("design");
+  expect(tab(host, "layers").className).toContain("bg-hover");
+});
+
+it("classifies its tabs for the hotkey filters exactly as the old buttons did (KTD13)", () => {
+  // The old strip rendered plain <button>s: not a typing target, and claimed by
+  // the playback filter through its `button` selector. Base UI's tab is a
+  // <button> too, so both verdicts have to be unchanged.
+  const { host } = mount(["design"]);
+  const el = tab(host, "design");
+
+  expect(el.tagName).toBe("BUTTON");
+  expect(isTypingTarget(el)).toBe(false);
+  expect(shouldIgnorePlaybackShortcutTarget(el)).toBe(true);
+});

package/src/components/RightPanelTabs.tsx

@@ -0,0 +1,59 @@
+/**
+ * The inspector tab strip on the shared Tabs primitive. The selected tab is derived from the
+ * panel's state; in the legacy split inspector two can be open, only one holds `aria-selected`.
+ */
+
+import { Tab, Tabs, TabsList, Tooltip, cn } from "./ui";
+
+export interface RightPanelTabDescriptor {
+  /** Stable id, also the `data-tab-id` attribute the strip is queried by. */
+  id: string;
+  label: string;
+  tooltip: string;
+  /** Whether this tab's content is on screen right now. */
+  active: boolean;
+  /** Run when the strip moves to this tab, by click or by arrow key. */
+  onSelect: () => void;
+}
+
+/** The look `aria-selected` gives the selected tab, for a second open pane. */
+const SELECTED_LOOK = "bg-hover text-text-0";
+
+export function RightPanelTabs({
+  tabs,
+  activateOnFocus = true,
+}: {
+  tabs: readonly RightPanelTabDescriptor[];
+  /** False when `onSelect` toggles a pane, so an arrow key only moves focus. */
+  activateOnFocus?: boolean;
+}) {
+  // `null` when the layout holds a tab this strip does not show (block params),
+  // which leaves every tab unselected, exactly as the old buttons did.
+  const value = tabs.find((tab) => tab.active)?.id ?? null;
+
+  return (
+    <Tabs
+      value={value}
+      onValueChange={(next) => {
+        tabs.find((tab) => tab.id === next)?.onSelect();
+      }}
+    >
+      <TabsList
+        aria-label="Inspector panels"
+        activateOnFocus={activateOnFocus}
+        className="flex min-w-0 items-center gap-1 overflow-hidden rounded-none border-b border-border-strong bg-transparent px-3 py-2"
+      >
+        {tabs.map((tab) => (
+          <Tooltip key={tab.id} label={tab.tooltip} side="bottom">
+            <Tab
+              value={tab.id}
+              className={cn("h-ctl-lg rounded-lg px-3 font-medium", tab.active && SELECTED_LOOK)}
+            >
+              {tab.label}
+            </Tab>
+          </Tooltip>
+        ))}
+      </TabsList>
+    </Tabs>
+  );
+}

package/src/components/StudioHeader.dom.test.tsx

@@ -0,0 +1,181 @@
+// @vitest-environment happy-dom
+
+/**
+ * The header on the shared primitives: Capture and Inspector grouped, Export separate,
+ * hotkey filters unchanged (KTD13). Contexts are mocked, not provided.
+ */
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { buttonSizes, buttonVariants } from "./ui";
+import { isTypingTarget } from "../utils/typingTarget";
+import { shouldIgnorePlaybackShortcutTarget } from "../player/lib/playbackShortcuts";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const editHistory = {
+  canUndo: false,
+  canRedo: false,
+  undoLabel: undefined as string | undefined,
+  redoLabel: undefined as string | undefined,
+};
+const renderQueue = { isRendering: false, ffmpegMissing: false };
+
+vi.mock("../contexts/StudioContext", () => ({
+  useStudioShellContext: () => ({
+    projectId: "demo",
+    editHistory,
+    handleUndo: vi.fn(),
+    handleRedo: vi.fn(),
+    renderQueue,
+  }),
+}));
+
+vi.mock("../contexts/PanelLayoutContext", () => ({
+  usePanelLayoutContext: () => ({
+    effectiveRightCollapsed: false,
+    setRightCollapsed: vi.fn(),
+    setRightPanelTab: vi.fn(),
+  }),
+}));
+
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+
+const { StudioHeader } = await import("./StudioHeader");
+
+let mounted: { root: Root; host: HTMLElement } | null = null;
+
+beforeEach(() => {
+  editHistory.canUndo = false;
+  editHistory.canRedo = false;
+  editHistory.undoLabel = undefined;
+  editHistory.redoLabel = undefined;
+  renderQueue.isRendering = false;
+});
+
+afterEach(() => {
+  if (!mounted) return;
+  const { root, host } = mounted;
+  mounted = null;
+  act(() => root.unmount());
+  host.remove();
+});
+
+function mount(props: { inspectorButtonActive?: boolean } = {}): HTMLElement {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  mounted = { root, host };
+  act(() =>
+    root.render(
+      <StudioHeader
+        captureFrameHref="blob:frame"
+        captureFrameFilename="frame.png"
+        handleCaptureFrameClick={vi.fn()}
+        refreshCaptureFrameTime={vi.fn()}
+        inspectorButtonActive={props.inspectorButtonActive ?? false}
+        inspectorPanelActive={false}
+      />,
+    ),
+  );
+  return host;
+}
+
+function query(host: HTMLElement, selector: string): HTMLElement {
+  const el = host.querySelector<HTMLElement>(selector);
+  if (!el) throw new Error(`not rendered: ${selector}`);
+  return el;
+}
+
+/** Every class the recipe asks for, on the element the header rendered. */
+function expectRecipe(el: HTMLElement, ...recipes: string[]): void {
+  const applied = new Set(el.className.split(/\s+/));
+  for (const recipe of recipes) {
+    for (const token of recipe.split(/\s+/)) {
+      expect(applied, `${token} missing from: ${el.className}`).toContain(token);
+    }
+  }
+}
+
+it("renders Export as the shared primary Button at the medium size", () => {
+  const host = mount();
+
+  expectRecipe(
+    query(host, '[data-testid="header-export"]'),
+    buttonVariants.primary,
+    buttonSizes.md,
+  );
+});
+
+it("no longer renders Undo or Redo in the header", () => {
+  const host = mount();
+
+  expect(host.querySelector('[aria-label="Undo"]')).toBeNull();
+  expect(host.querySelector('[aria-label="Redo"]')).toBeNull();
+});
+
+it("groups Capture and Inspector in one bordered segment, Export outside it", () => {
+  const host = mount();
+  const group = query(host, '[aria-label="Capture current frame"]').closest(".divide-x");
+
+  expect(group?.contains(query(host, '[aria-label="Inspector"]'))).toBe(true);
+  expect(group?.contains(query(host, '[data-testid="header-export"]'))).toBe(false);
+  expect(group).not.toBeNull();
+});
+
+it("drops the Capture label below 1000px but keeps its accessible name", () => {
+  const host = mount();
+  const capture = query(host, '[aria-label="Capture current frame"]');
+
+  expect(query(capture, "span").className).toContain("max-[1000px]:hidden");
+});
+
+/** The bare token, not a `hover:`/`data-[…]:`-prefixed variant of it. */
+function hasToken(className: string, token: string): boolean {
+  return className.split(/\s+/).includes(token);
+}
+
+it("shows Inspector pressed and filled only when on", () => {
+  const host = mount({ inspectorButtonActive: true });
+  const on = query(host, '[aria-label="Inspector"]');
+  expect(on.getAttribute("aria-pressed")).toBe("true");
+  expect(hasToken(on.className, "text-accent")).toBe(true);
+  expect(hasToken(on.className, "bg-hover")).toBe(true);
+  act(() => mounted?.root.unmount());
+  mounted?.host.remove();
+  mounted = null;
+
+  const off = query(mount(), '[aria-label="Inspector"]');
+  expect(off.getAttribute("aria-pressed")).toBe("false");
+  expect(hasToken(off.className, "text-accent")).toBe(false);
+  expect(hasToken(off.className, "bg-hover")).toBe(false);
+});
+
+it("keeps Capture a real download link rather than a button", () => {
+  // `download` is what saves the frame. A Button here would render a <button>
+  // and the control would quietly stop downloading anything.
+  const host = mount();
+  const capture = query(host, '[aria-label="Capture current frame"]');
+
+  expect(capture.tagName).toBe("A");
+  expect(capture.getAttribute("download")).toBe("frame.png");
+  // h-full replaces the md height: the group's own h-ctl sets the shared control height.
+  expectRecipe(capture, "px-3", "text-step-12");
+});
+
+it("classifies the new header controls for the hotkey filters as the old ones were (KTD13)", () => {
+  // Every one of these was a <button> or an <a href> before the sweep: never a
+  // typing target, always claimed by the playback filter. A primitive that
+  // rendered a different element would leak or swallow hotkeys in silence.
+  const host = mount();
+  const controls = [
+    query(host, '[data-testid="header-export"]'),
+    query(host, '[aria-label="Inspector"]'),
+    query(host, '[aria-label="Capture current frame"]'),
+  ];
+
+  for (const el of controls) {
+    expect(isTypingTarget(el), el.getAttribute("aria-label") ?? el.tagName).toBe(false);
+    expect(shouldIgnorePlaybackShortcutTarget(el), el.tagName).toBe(true);
+  }
+});