@hyperframes/studio 0.8.85 → 0.8.87

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.85",
+  "version": "0.8.87",
   "description": "",
   "repository": {
     "type": "git",
@@ -60,12 +60,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.85",
-    "@hyperframes/player": "0.8.85",
-    "@hyperframes/parsers": "0.8.85",
-    "@hyperframes/shader-transitions": "0.8.85",
-    "@hyperframes/studio-server": "0.8.85",
-    "@hyperframes/sdk": "0.8.85"
+    "@hyperframes/core": "0.8.87",
+    "@hyperframes/parsers": "0.8.87",
+    "@hyperframes/player": "0.8.87",
+    "@hyperframes/shader-transitions": "0.8.87",
+    "@hyperframes/studio-server": "0.8.87",
+    "@hyperframes/sdk": "0.8.87"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -81,7 +81,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.85"
+    "@hyperframes/producer": "0.8.87"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/TimelineToolbar.test.tsx

@@ -24,17 +24,22 @@ vi.mock("../contexts/StudioContext", () => ({
 
 afterEach(() => {
   document.body.innerHTML = "";
-  usePlayerStore.setState({ autoKeyframeEnabled: true, thumbnailMode: "adaptive" });
+  usePlayerStore.setState({
+    autoKeyframeEnabled: true,
+    thumbnailMode: "adaptive",
+    zoomMode: "fit",
+  });
 });
 
 function renderToolbar(
   domEditSession?: React.ComponentProps<typeof TimelineToolbar>["domEditSession"],
+  props: Partial<React.ComponentProps<typeof TimelineToolbar>> = {},
 ) {
   const host = document.createElement("div");
   document.body.append(host);
   const root = createRoot(host);
   act(() => {
-    root.render(<TimelineToolbar domEditSession={domEditSession} />);
+    root.render(<TimelineToolbar domEditSession={domEditSession} {...props} />);
   });
   return { host, root };
 }
@@ -175,6 +180,52 @@ describe("TimelineToolbar — keyframes on audio tracks", () => {
     expect(button?.disabled).toBe(false);
     act(() => root.unmount());
   });
+
+  const keyframeControls = (host: HTMLElement) => [
+    host.querySelector('button[aria-label="Add keyframe at playhead"]'),
+    host.querySelector('button[aria-label="Auto-record manual edits as keyframes"]'),
+  ];
+  /** True when the keyframe shortcut claimed K, so playback never saw it. */
+  const pressK = () => {
+    const event = new KeyboardEvent("keydown", { key: "k", bubbles: true, cancelable: true });
+    act(() => {
+      window.dispatchEvent(event);
+    });
+    return event.defaultPrevented;
+  };
+
+  it("shows Add keyframe and auto-record, and K adds a keyframe, by default", () => {
+    const { host, root } = renderToolbar(sessionFor("div"));
+    expect(keyframeControls(host).every(Boolean)).toBe(true);
+    expect(pressK()).toBe(true);
+    act(() => root.unmount());
+  });
+
+  it("hides both controls for a host without keyframes, turns auto-record off and leaves K alone", () => {
+    const { host, root } = renderToolbar(sessionFor("div"), { showKeyframes: false });
+    expect(keyframeControls(host)).toEqual([null, null]);
+    expect(usePlayerStore.getState().autoKeyframeEnabled).toBe(false);
+    expect(pressK()).toBe(false);
+    act(() => root.unmount());
+  });
+});
+
+describe("TimelineToolbar Fit", () => {
+  it("shows Fit as a named icon and says whether fit is on", () => {
+    const { host, root } = renderToolbar();
+    const fit = () => host.querySelector('button[aria-label="Fit timeline to width"]');
+    expect(fit()?.textContent).toBe("");
+    expect(fit()?.querySelector("svg")).not.toBeNull();
+    act(() => fit()?.dispatchEvent(new MouseEvent("click", { bubbles: true })));
+    expect(fit()?.getAttribute("aria-pressed")).toBe("true");
+    act(() =>
+      host
+        .querySelector('button[aria-label="Zoom in"]')
+        ?.dispatchEvent(new MouseEvent("click", { bubbles: true })),
+    );
+    expect(fit()?.getAttribute("aria-pressed")).toBe("false");
+    act(() => root.unmount());
+  });
 });
 
 describe("TimelineToolbar audio meters", () => {

package/src/components/TimelineToolbar.tsx

@@ -1,5 +1,11 @@
 import { useEffect, useRef } from "react";
-import { Image, Magnet, MagnifyingGlassMinus, MagnifyingGlassPlus } from "@phosphor-icons/react";
+import {
+  ArrowsOutLineHorizontal,
+  Image,
+  Magnet,
+  MagnifyingGlassMinus,
+  MagnifyingGlassPlus,
+} from "@phosphor-icons/react";
 import {
   useEnableKeyframes,
   isPlayheadWithinTween,
@@ -38,6 +44,8 @@ export interface TimelineToolbarProps {
   onSplitElement?: (element: TimelineElement, splitTime: number) => void;
   history?: TimelineHistoryButtonsProps;
   showAddBeat?: boolean;
+  /** Hides Add keyframe and auto-record, and turns off auto-record and the K shortcut with them. */
+  showKeyframes?: boolean;
 }
 
 interface KeyframeToggleState {
@@ -134,6 +142,7 @@ export function TimelineToolbar({
   onSplitElement,
   history,
   showAddBeat = true,
+  showKeyframes = true,
 }: TimelineToolbarProps) {
   const activeTool = usePlayerStore((s) => s.activeTool);
   const setActiveTool = usePlayerStore((s) => s.setActiveTool);
@@ -174,10 +183,14 @@ export function TimelineToolbar({
   // Wire the "Add keyframe (K)" shortcut the toolbar advertises. Active only when
   // there's a keyframeable selection; otherwise K stays JKL-pause in playback.
   useKeyframeKeyboard({
-    enabled: Boolean(onToggleKeyframe),
+    enabled: showKeyframes && Boolean(onToggleKeyframe),
     onAddKeyframe: onToggleKeyframe,
   });
 
+  useEffect(() => {
+    if (!showKeyframes) setAutoKeyframeEnabled(false);
+  }, [showKeyframes, setAutoKeyframeEnabled]);
+
   // "N" toggles timeline snapping (industry convention: Resolve/FCP).
   // Skip when typing in an input/contenteditable.
   useEffect(() => {
@@ -270,107 +283,110 @@ export function TimelineToolbar({
               </button>
             </Tooltip>
           )}
-          {/* Always rendered (CapCut-style): with no keyframeable selection the
-              button fades to a disabled state instead of unmounting, so the
-              toolbar layout never shifts. */}
-          <Tooltip
-            label={
-              keyframePathEndpoint
-                ? "Motion path endpoints cannot be removed"
-                : !onToggleKeyframe
-                  ? "Select an animated element to add keyframes"
-                  : keyframeIsMotionPath
-                    ? keyframeWillExtend
-                      ? "Extend motion path to playhead (K)"
-                      : keyframeState === "active"
-                        ? "Remove waypoint from motion path (K)"
-                        : "Add waypoint to motion path (K)"
-                    : keyframeState === "active"
-                      ? "Remove keyframe at playhead (K)"
-                      : keyframeState === "inactive"
+          {showKeyframes && (
+            <>
+              {/* With no keyframeable selection the button fades to disabled instead of
+              unmounting, so the toolbar layout never shifts (CapCut-style). */}
+              <Tooltip
+                label={
+                  keyframePathEndpoint
+                    ? "Motion path endpoints cannot be removed"
+                    : !onToggleKeyframe
+                      ? "Select an animated element to add keyframes"
+                      : keyframeIsMotionPath
                         ? keyframeWillExtend
-                          ? "Add keyframe at playhead, extends animation (K)"
-                          : "Add keyframe at playhead (K)"
-                        : "Add keyframe (K)"
-            }
-          >
-            <button
-              type="button"
-              disabled={!onToggleKeyframe}
-              onClick={onToggleKeyframe}
-              aria-label={
-                keyframePathEndpoint
-                  ? "Motion path endpoint"
-                  : keyframeIsMotionPath
-                    ? keyframeState === "active"
-                      ? "Remove motion path waypoint"
-                      : keyframeWillExtend
-                        ? "Extend motion path to playhead"
-                        : "Add motion path waypoint"
-                    : keyframeState === "active"
-                      ? "Remove keyframe at playhead"
-                      : "Add keyframe at playhead"
-              }
-              className={
-                !onToggleKeyframe
-                  ? flatDisabled
-                  : `${flatBtn} active:scale-[0.98] hover:bg-white/6 ${
-                      keyframeState === "active"
-                        ? "text-studio-accent"
-                        : keyframeState === "inactive"
-                          ? "text-neutral-400 hover:text-studio-accent"
-                          : "text-neutral-600 hover:text-neutral-400"
-                    }`
-              }
-            >
-              <svg width="16" height="16" viewBox="0 0 10 10" fill="currentColor">
-                {keyframeState === "active" ? (
-                  <path d="M5 0.5L9.5 5L5 9.5L0.5 5Z" />
-                ) : (
-                  <path
-                    d="M5 1.2L8.8 5L5 8.8L1.2 5Z"
-                    fill="none"
-                    stroke="currentColor"
-                    strokeWidth="1.2"
-                  />
-                )}
-              </svg>
-            </button>
-          </Tooltip>
-          <Tooltip
-            label={
-              autoKeyframeEnabled
-                ? "Auto-record manual edits as keyframes (click to turn off)"
-                : "Manual edits will not be recorded as keyframes (click to turn on)"
-            }
-          >
-            <button
-              type="button"
-              onClick={() => setAutoKeyframeEnabled(!autoKeyframeEnabled)}
-              aria-label="Auto-record manual edits as keyframes"
-              aria-pressed={autoKeyframeEnabled}
-              className={`${flatBtn} active:scale-[0.98] hover:bg-white/6 ${
-                autoKeyframeEnabled
-                  ? "text-red-400 hover:text-red-300"
-                  : "text-neutral-600 hover:text-neutral-400"
-              }`}
-            >
-              <svg width="16" height="16" viewBox="0 0 10 10" fill="none">
-                {/* Same diamond outline as the Add-keyframe icon, with a
+                          ? "Extend motion path to playhead (K)"
+                          : keyframeState === "active"
+                            ? "Remove waypoint from motion path (K)"
+                            : "Add waypoint to motion path (K)"
+                        : keyframeState === "active"
+                          ? "Remove keyframe at playhead (K)"
+                          : keyframeState === "inactive"
+                            ? keyframeWillExtend
+                              ? "Add keyframe at playhead, extends animation (K)"
+                              : "Add keyframe at playhead (K)"
+                            : "Add keyframe (K)"
+                }
+              >
+                <button
+                  type="button"
+                  disabled={!onToggleKeyframe}
+                  onClick={onToggleKeyframe}
+                  aria-label={
+                    keyframePathEndpoint
+                      ? "Motion path endpoint"
+                      : keyframeIsMotionPath
+                        ? keyframeState === "active"
+                          ? "Remove motion path waypoint"
+                          : keyframeWillExtend
+                            ? "Extend motion path to playhead"
+                            : "Add motion path waypoint"
+                        : keyframeState === "active"
+                          ? "Remove keyframe at playhead"
+                          : "Add keyframe at playhead"
+                  }
+                  className={
+                    !onToggleKeyframe
+                      ? flatDisabled
+                      : `${flatBtn} active:scale-[0.98] hover:bg-white/6 ${
+                          keyframeState === "active"
+                            ? "text-studio-accent"
+                            : keyframeState === "inactive"
+                              ? "text-neutral-400 hover:text-studio-accent"
+                              : "text-neutral-600 hover:text-neutral-400"
+                        }`
+                  }
+                >
+                  <svg width="16" height="16" viewBox="0 0 10 10" fill="currentColor">
+                    {keyframeState === "active" ? (
+                      <path d="M5 0.5L9.5 5L5 9.5L0.5 5Z" />
+                    ) : (
+                      <path
+                        d="M5 1.2L8.8 5L5 8.8L1.2 5Z"
+                        fill="none"
+                        stroke="currentColor"
+                        strokeWidth="1.2"
+                      />
+                    )}
+                  </svg>
+                </button>
+              </Tooltip>
+              <Tooltip
+                label={
+                  autoKeyframeEnabled
+                    ? "Auto-record manual edits as keyframes (click to turn off)"
+                    : "Manual edits will not be recorded as keyframes (click to turn on)"
+                }
+              >
+                <button
+                  type="button"
+                  onClick={() => setAutoKeyframeEnabled(!autoKeyframeEnabled)}
+                  aria-label="Auto-record manual edits as keyframes"
+                  aria-pressed={autoKeyframeEnabled}
+                  className={`${flatBtn} active:scale-[0.98] hover:bg-white/6 ${
+                    autoKeyframeEnabled
+                      ? "text-red-400 hover:text-red-300"
+                      : "text-neutral-600 hover:text-neutral-400"
+                  }`}
+                >
+                  <svg width="16" height="16" viewBox="0 0 10 10" fill="none">
+                    {/* Same diamond outline as the Add-keyframe icon, with a
                       record-style dot inside: filled = auto-recording,
                       hollow = manual edits won't be keyframed. */}
-                <path d="M5 0.7L9.3 5L5 9.3L0.7 5Z" stroke="currentColor" strokeWidth="1" />
-                <circle
-                  cx="5"
-                  cy="5"
-                  r="1.8"
-                  fill={autoKeyframeEnabled ? "currentColor" : "none"}
-                  stroke="currentColor"
-                  strokeWidth="1"
-                />
-              </svg>
-            </button>
-          </Tooltip>
+                    <path d="M5 0.7L9.3 5L5 9.3L0.7 5Z" stroke="currentColor" strokeWidth="1" />
+                    <circle
+                      cx="5"
+                      cy="5"
+                      r="1.8"
+                      fill={autoKeyframeEnabled ? "currentColor" : "none"}
+                      stroke="currentColor"
+                      strokeWidth="1"
+                    />
+                  </svg>
+                </button>
+              </Tooltip>
+            </>
+          )}
           {onSplitElement &&
             (() => {
               // Render the button unconditionally (disabled when unusable):
@@ -495,13 +511,15 @@ export function TimelineToolbar({
             <button
               type="button"
               onClick={() => setZoomMode("fit")}
+              aria-label="Fit timeline to width"
+              aria-pressed={zoomMode === "fit"}
               className={`h-7 px-2 rounded-md text-[11px] font-medium transition-colors ${
                 zoomMode === "fit"
                   ? "bg-studio-accent/10 text-studio-accent"
                   : "text-neutral-400 hover:bg-white/6 hover:text-neutral-200"
               }`}
             >
-              Fit
+              <ArrowsOutLineHorizontal size={16} aria-hidden="true" />
             </button>
           </Tooltip>
           <Tooltip label="Zoom out">

package/src/components/editor/DomEditOverlay.tsx

@@ -47,7 +47,7 @@ export {
 } from "./domEditOverlayGestures";
 export type { DomEditGroupPathOffsetCommit } from "./domEditOverlayGestures";
 
-interface DomEditOverlayProps {
+export interface DomEditOverlayProps {
   iframeRef: RefObject<HTMLIFrameElement | null>;
   activeCompositionPath: string | null;
   selection: DomEditSelection | null;
@@ -518,7 +518,6 @@ export const DomEditOverlay = memo(function DomEditOverlay({
           boxClipPath={boxClipPath}
           selectionKey={selectionKey}
           groupSelectionCount={groupSelections.length}
-          blockedMoveRef={blockedMoveRef}
           gestures={gestures}
           onStyleCommit={onStyleCommitRef.current}
           onBoxMouseDown={suppressBoxMouseDown}

package/src/components/editor/DomEditOverlayHover.test.tsx

@@ -6,6 +6,7 @@ import { expect, it, vi } from "vitest";
 import type { DomEditSelection } from "./domEditing";
 import "./domEditOverlayTestMocks";
 import { DomEditOverlay } from "./DomEditOverlay";
+import { DomEditOverlay as PackageDomEditOverlay } from "../../index";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -74,3 +75,7 @@ it("rotates the hover box with the element", () => {
 it("leaves the hover box untransformed at angle zero", () => {
   expect(renderHover(0)).toBe("");
 });
+
+it("is exported from the package entry, so a host can mount it with its own commits", () => {
+  expect(PackageDomEditOverlay).toBe(DomEditOverlay);
+});

package/src/components/editor/DomEditSelectionChrome.test.tsx

@@ -53,7 +53,6 @@ describe("DomEditSelectionChrome crop composition", () => {
           boxClipPath={undefined}
           selectionKey="headline"
           groupSelectionCount={0}
-          blockedMoveRef={createRef()}
           gestures={{ startGesture: vi.fn() } as never}
           onStyleCommit={vi.fn()}
           onBoxMouseDown={vi.fn()}
@@ -109,7 +108,6 @@ describe("DomEditSelectionChrome crop composition", () => {
           boxClipPath={undefined}
           selectionKey="clip"
           groupSelectionCount={0}
-          blockedMoveRef={createRef()}
           gestures={{ startGesture: vi.fn() } as never}
           onStyleCommit={vi.fn()}
           onBoxMouseDown={vi.fn()}
@@ -170,7 +168,6 @@ describe("DomEditSelectionChrome while editing text", () => {
           boxClipPath={undefined}
           selectionKey="copy"
           groupSelectionCount={0}
-          blockedMoveRef={createRef()}
           gestures={{ startGesture: vi.fn() } as never}
           onStyleCommit={vi.fn()}
           onBoxMouseDown={vi.fn()}

package/src/components/editor/DomEditSelectionChrome.tsx

@@ -1,7 +1,7 @@
 import type { RefObject } from "react";
 import { type DomEditSelection } from "./domEditing";
 import type { GroupOverlayItem, OverlayRect } from "./domEditOverlayGeometry";
-import type { BlockedMoveState, ResizeHandle } from "./domEditOverlayGestures";
+import type { ResizeHandle } from "./domEditOverlayGestures";
 import type { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGestures";
 import { DomEditCropHandles } from "./DomEditCropHandles";
 import { DomEditRotateHandle } from "./DomEditRotateHandle";
@@ -103,7 +103,7 @@ export function DomEditGroupChrome({
           cursor: canManipulate && groupCanMove ? "move" : "default",
         }}
         onPointerDown={(e) => {
-          if (!canManipulate || !groupCanMove || e.shiftKey) return;
+          if (!canManipulate || e.shiftKey) return;
           gestures.startGroupDrag(e);
         }}
         onMouseDown={onBoxMouseDown}
@@ -123,7 +123,6 @@ interface DomEditSelectionChromeProps {
   boxClipPath: string | undefined;
   selectionKey: string;
   groupSelectionCount: number;
-  blockedMoveRef: RefObject<BlockedMoveState | null>;
   gestures: GestureHandlers;
   onStyleCommit?: (property: string, value: string) => Promise<unknown> | void;
   onBoxMouseDown: (e: React.MouseEvent) => void;
@@ -152,7 +151,6 @@ export function DomEditSelectionChrome({
   boxClipPath,
   selectionKey,
   groupSelectionCount,
-  blockedMoveRef,
   gestures,
   onStyleCommit,
   onBoxMouseDown,
@@ -218,15 +216,7 @@ export function DomEditSelectionChrome({
               gestures.startGesture("drag", e);
               return;
             }
-            e.preventDefault();
-            e.stopPropagation();
-            e.currentTarget.setPointerCapture(e.pointerId);
-            blockedMoveRef.current = {
-              pointerId: e.pointerId,
-              startX: e.clientX,
-              startY: e.clientY,
-              notified: false,
-            };
+            gestures.startBlockedMove(e, selection);
           }}
           onMouseDown={onBoxMouseDown}
           onClick={onBoxClick}

package/src/components/editor/LayersPanel.test.ts

@@ -9,6 +9,7 @@ import type { DomEditLayerItem } from "./domEditingTypes";
 import { createRafThrottle, LayersPanel, sortLayersByZIndex } from "./LayersPanel";
 import { isLayerDraggable } from "./useLayerDrag";
 import { liveTime } from "../../player";
+import { sceneSwapFor } from "../../player/sceneSwap";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -292,4 +293,17 @@ describe("LayersPanel preview promotion", () => {
     });
     expect(collectedRootIds()).toEqual(["b"]);
   });
+  it("recollects layers when edited scenes are swapped into the live document", async () => {
+    const a = makeIframe("a");
+    Object.defineProperty(a, "contentWindow", { value: { __hfSwapScenes: async () => {} } });
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("<html></html>"));
+    mocks.previewIframeRef.current = a;
+    usePreviewIframeStore.setState({ iframe: a });
+    act(() => root.render(createElement(LayersPanel)));
+    mocks.collect.mockClear();
+
+    await act(() => sceneSwapFor(a)!("/preview", () => true));
+    expect(collectedRootIds()).toEqual(["a"]);
+    fetchSpy.mockRestore();
+  });
 });

package/src/components/editor/LayersPanel.tsx

@@ -1,4 +1,5 @@
 import { useLivePreviewIframe } from "../../player/store/previewIframeStore";
+import { onPreviewContentReplaced } from "../../player/sceneSwap";
 import { memo, useState, useCallback, useEffect, useRef } from "react";
 import {
   collectDomEditLayerItems,
@@ -164,8 +165,7 @@ export const LayersPanel = memo(function LayersPanel() {
       prevDocVersionRef.current += 1;
       collectLayers();
     };
-    iframe.addEventListener("load", handleLoad);
-    return () => iframe.removeEventListener("load", handleLoad);
+    return onPreviewContentReplaced(iframe, handleLoad);
   }, [previewIframeRef, livePreviewIframe, collectLayers]);
 
   useEffect(() => {

package/src/components/editor/TopologyLens.tsx

@@ -1,4 +1,5 @@
 import { useLivePreviewIframe } from "../../player/store/previewIframeStore";
+import { onPreviewContentReplaced } from "../../player/sceneSwap";
 import {
   useEffect,
   useLayoutEffect,
@@ -119,8 +120,7 @@ export function TopologyLens({ iframeRef, activeCompositionPath }: TopologyLensP
     const iframe = iframeRef.current;
     if (!iframe || !callId) return;
     const dismiss = () => studioEditLifecycle.dismiss(callId);
-    iframe.addEventListener("load", dismiss);
-    return () => iframe.removeEventListener("load", dismiss);
+    return onPreviewContentReplaced(iframe, dismiss);
   }, [callId, iframeRef, livePreviewIframe]);
 
   useEffect(() => {