@hyperframes/studio 0.7.60 → 0.7.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.7.60",
+  "version": "0.7.62",
   "description": "",
   "repository": {
     "type": "git",
@@ -46,11 +46,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.7.60",
-    "@hyperframes/player": "0.7.60",
-    "@hyperframes/sdk": "0.7.60",
-    "@hyperframes/parsers": "0.7.60",
-    "@hyperframes/studio-server": "0.7.60"
+    "@hyperframes/core": "0.7.62",
+    "@hyperframes/player": "0.7.62",
+    "@hyperframes/studio-server": "0.7.62",
+    "@hyperframes/parsers": "0.7.62",
+    "@hyperframes/sdk": "0.7.62"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -65,7 +65,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.7.60"
+    "@hyperframes/producer": "0.7.62"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -57,6 +57,7 @@ import { FileManagerProvider } from "./contexts/FileManagerContext";
 import { DomEditProvider } from "./contexts/DomEditContext";
 import { StudioSplash } from "./components/StudioSplash";
 import { useServerConnection } from "./hooks/useServerConnection";
+import { useTimelineAddAtPlayhead } from "./hooks/useTimelineAddAtPlayhead";
 import {
   normalizeStudioCompositionPath,
   readStudioUrlStateFromWindow,
@@ -64,7 +65,6 @@ import {
 } from "./utils/studioUrlState";
 import { trackStudioSessionStart } from "./telemetry/events";
 import { hasFiredSessionStart, markSessionStartFired } from "./telemetry/config";
-type CanvasRect = { left: number; top: number; width: number; height: number };
 // fallow-ignore-next-line complexity
 export function StudioApp() {
   const { projectId, resolving, waitingForServer } = useServerConnection();
@@ -99,9 +99,6 @@ export function StudioApp() {
   const timelineDuration = usePlayerStore((s) => s.duration);
   const isPlaying = usePlayerStore((s) => s.isPlaying);
   const isMasterView = !activeCompPath || activeCompPath === "index.html";
-  const activePreviewUrl = activeCompPath
-    ? `/api/projects/${projectId}/preview/comp/${activeCompPath}`
-    : null;
   const effectiveTimelineDuration = useMemo(() => {
     const maxEnd =
       timelineElements.length > 0
@@ -195,13 +192,12 @@ export function StudioApp() {
     },
     [timelineEditing.handleTimelineGroupMove],
   );
-  const handleAddAssetAtPlayhead = useCallback(
-    (assetPath: string) =>
-      timelineEditing.handleTimelineAssetDrop(assetPath, {
-        start: usePlayerStore.getState().currentTime,
-        track: 0,
-      }),
-    [timelineEditing],
+  const {
+    addAssetAtPlayhead: handleAddAssetAtPlayhead,
+    addCompositionAtPlayhead: handleAddCompositionAtPlayhead,
+  } = useTimelineAddAtPlayhead(
+    timelineEditing.handleTimelineAssetDrop,
+    timelineEditing.handleTimelineCompositionDrop,
   );
   const {
     activeBlockParams,
@@ -344,7 +340,9 @@ export function StudioApp() {
   const renderClipContent = useRenderClipContent({
     projectIdRef: fileManager.projectIdRef,
     compIdToSrc,
-    activePreviewUrl,
+    activePreviewUrl: activeCompPath
+      ? `/api/projects/${projectId}/preview/comp/${activeCompPath}`
+      : null,
     effectiveTimelineDuration,
   });
   const compositionDimensions = useCompositionDimensions();
@@ -375,14 +373,13 @@ export function StudioApp() {
   });
   handleToggleRecordingRef.current = handleToggleRecording;
   const recordingToggle = STUDIO_KEYFRAMES_ENABLED ? handleToggleRecording : undefined;
-  const canvasRectRef = useRef<CanvasRect | null>(null);
+  const canvasRectRef = useRef<DOMRect | null>(null);
   useLayoutEffect(() => {
     if (gestureState !== "recording" || !previewIframe) {
       canvasRectRef.current = null;
       return;
     }
-    const r = previewIframe.getBoundingClientRect();
-    canvasRectRef.current = { left: r.left, top: r.top, width: r.width, height: r.height };
+    canvasRectRef.current = previewIframe.getBoundingClientRect();
   }, [gestureState, previewIframe]);
   const handlePreviewIframeRef = useCallback(
     (iframe: HTMLIFrameElement | null) => {
@@ -517,6 +514,7 @@ export function StudioApp() {
                         lintFindingCount={lintModal?.length ?? findingsByFile.size}
                         lintFindingsByFile={findingsByFile}
                         onAddAssetToTimeline={handleAddAssetAtPlayhead}
+                        onAddCompositionToTimeline={handleAddCompositionAtPlayhead}
                       />
                     }
                     right={
@@ -533,6 +531,7 @@ export function StudioApp() {
                           onToggleRecording={recordingToggle}
                           sdkSession={sdkHandle.session}
                           publishSdkSession={sdkHandle.publish}
+                          forceReloadSdkSession={sdkHandle.forceReload}
                           reloadPreview={reloadPreview}
                           domEditSaveTimestampRef={domEditSaveTimestampRef}
                           recordEdit={editHistory.recordEdit}
@@ -545,6 +544,7 @@ export function StudioApp() {
                     handleTimelineElementDelete={timelineEditing.handleTimelineElementDelete}
                     handleTimelineAssetDrop={timelineEditing.handleTimelineAssetDrop}
                     handleTimelineBlockDrop={handleTimelineBlockDrop}
+                    handleTimelineCompositionDrop={timelineEditing.handleTimelineCompositionDrop}
                     handlePreviewBlockDrop={handlePreviewBlockDrop}
                     handleTimelineFileDrop={timelineEditing.handleTimelineFileDrop}
                     handleTimelineElementMove={timelineEditing.handleTimelineElementMove}

package/src/components/DesignPanelPromoteProvider.tsx

@@ -10,6 +10,7 @@
  */
 
 import { useCallback, type ReactNode } from "react";
+import type { Composition } from "@hyperframes/sdk";
 import type { DomEditSelection } from "./editor/domEditingTypes";
 import { useSdkSession } from "../hooks/useSdkSession";
 import { useVariablesPersist, type UseVariablesPersistParams } from "../hooks/useVariablesPersist";
@@ -24,6 +25,7 @@ export function DesignPanelPromoteProvider({
   projectId,
   activeCompPath,
   showToast,
+  forceReloadSharedSdkSession,
   children,
   ...persistDeps
 }: PersistDeps & {
@@ -31,16 +33,40 @@ export function DesignPanelPromoteProvider({
   projectId: string | null;
   activeCompPath: string | null;
   showToast: (message: string, tone?: "error" | "info") => void;
+  /**
+   * Forces the app's SHARED SDK session (Variables tab, Slideshow, etc.) to
+   * re-open from disk. This provider opens its OWN session, separate from
+   * that shared one, so a persist through it never fires the shared session's
+   * own "change" event. When the target happens to be the same file the
+   * shared session already has open, that session is left holding stale
+   * in-memory content after a successful persist — worse, the self-write-echo
+   * registry that would normally reload it on the next file-change
+   * notification is keyed by file path only (not by session instance), so it
+   * mistakes this provider's write for its own echo and stays stale
+   * indefinitely. Called unconditionally (not gated on targetPath matching
+   * activeCompPath): re-opening a file that didn't change is a harmless
+   * no-op re-parse, cheaper than the bug class a subtly-wrong path guard
+   * could reintroduce.
+   */
+  forceReloadSharedSdkSession?: () => void;
   children: ReactNode;
 }) {
   const targetPath = selection?.sourceFile || activeCompPath || "index.html";
   const handle = useSdkSession(projectId, targetPath, persistDeps.domEditSaveTimestampRef);
-  const persist = useVariablesPersist({
+  const rawPersist = useVariablesPersist({
     ...persistDeps,
     sdkSession: handle.session,
     publishSdkSession: handle.publish,
     activeCompPath: targetPath,
   });
+  const persist = useCallback(
+    async (label: string, mutate: (session: Composition) => void) => {
+      const committed = await rawPersist(label, mutate);
+      if (committed) forceReloadSharedSdkSession?.();
+      return committed;
+    },
+    [rawPersist, forceReloadSharedSdkSession],
+  );
   const handlePersistError = useCallback(
     (error: unknown) => showToast(getStudioSaveErrorMessage(error), "error"),
     [showToast],

package/src/components/EditorShell.tsx

@@ -42,6 +42,10 @@ export interface EditorShellProps extends TimelineEditCallbackDeps {
     blockName: string,
     placement: TimelineDropPlacement,
   ) => Promise<void> | void;
+  handleTimelineCompositionDrop?: (
+    sourcePath: string,
+    placement: TimelineDropPlacement,
+  ) => Promise<void> | void;
   handlePreviewBlockDrop?: (
     blockName: string,
     position: { left: number; top: number },
@@ -72,6 +76,7 @@ export function EditorShell({
   handleTimelineElementDelete,
   handleTimelineAssetDrop,
   handleTimelineBlockDrop,
+  handleTimelineCompositionDrop,
   handlePreviewBlockDrop,
   handleTimelineFileDrop,
   handleTimelineElementMove,
@@ -140,6 +145,7 @@ export function EditorShell({
             onFileDrop={handleTimelineFileDrop}
             onAssetDrop={handleTimelineAssetDrop}
             onBlockDrop={handleTimelineBlockDrop}
+            onCompositionDrop={handleTimelineCompositionDrop}
             onDeleteElement={handleTimelineElementDelete}
             previewOverlay={
               <PreviewOverlays
@@ -174,6 +180,10 @@ interface EditorShellBodyProps {
   onFileDrop: (files: File[], placement?: TimelineDropPlacement) => Promise<void> | void;
   onAssetDrop: (assetPath: string, placement: TimelineDropPlacement) => Promise<void> | void;
   onBlockDrop?: (blockName: string, placement: TimelineDropPlacement) => Promise<void> | void;
+  onCompositionDrop?: (
+    sourcePath: string,
+    placement: TimelineDropPlacement,
+  ) => Promise<void> | void;
   onDeleteElement: (element: TimelineElement) => Promise<void> | void;
 }
 
@@ -189,6 +199,7 @@ function EditorShellBody({
   onFileDrop,
   onAssetDrop,
   onBlockDrop,
+  onCompositionDrop,
   onDeleteElement,
 }: EditorShellBodyProps) {
   const { compositionStack, updateCompositionStack, containerRef } = useNLEContext();
@@ -233,6 +244,7 @@ function EditorShellBody({
         onFileDrop={onFileDrop}
         onAssetDrop={onAssetDrop}
         onBlockDrop={onBlockDrop}
+        onCompositionDrop={onCompositionDrop}
         onDeleteElement={onDeleteElement}
         onSelectTimelineElement={onSelectTimelineElement}
         timelineFooter={

package/src/components/StudioHeader.tsx

@@ -149,14 +149,13 @@ const VIEW_MODE_OPTIONS: Array<{ mode: StudioViewMode; label: string }> = [
 ];
 
 /** Segmented control switching the main stage between storyboard and preview. */
-function ViewModeToggle() {
+export function ViewModeToggle() {
   const { viewMode, setViewMode } = useViewMode();
   const tabRefs = useRef<Array<HTMLButtonElement | null>>([]);
 
   const selectMode = (mode: StudioViewMode) => {
     if (mode === viewMode) return;
-    trackStudioEvent("view_mode_toggle", { mode });
-    setViewMode(mode);
+    if (setViewMode(mode)) trackStudioEvent("view_mode_toggle", { mode });
   };
 
   // Complete APG tabs pattern: roving tabIndex + arrow-key navigation.

package/src/components/StudioLeftSidebar.tsx

@@ -19,6 +19,7 @@ export interface StudioLeftSidebarProps {
   lintFindingCount?: number;
   lintFindingsByFile?: Map<string, { count: number; messages: string[] }>;
   onAddAssetToTimeline?: (path: string) => void;
+  onAddCompositionToTimeline?: (path: string) => void;
 }
 
 // fallow-ignore-next-line complexity
@@ -32,6 +33,7 @@ export function StudioLeftSidebar({
   lintFindingCount,
   lintFindingsByFile,
   onAddAssetToTimeline,
+  onAddCompositionToTimeline,
 }: StudioLeftSidebarProps) {
   const {
     leftCollapsed,
@@ -150,6 +152,7 @@ export function StudioLeftSidebar({
         onAddBlock={onAddBlock}
         onPreviewBlock={onPreviewBlock}
         onAddAssetToTimeline={onAddAssetToTimeline}
+        onAddCompositionToTimeline={onAddCompositionToTimeline}
       />
       {/* Vertical resize divider: 3px visible seam, 8px pointer-capture zone via
           the absolutely-positioned inner hit area. The outer element is w-[3px] so

package/src/components/StudioRightPanel.tsx

@@ -1,17 +1,15 @@
-import { useCallback, useEffect, useMemo, useRef, type MutableRefObject } from "react";
+import { useCallback, useEffect, useRef, type MutableRefObject } from "react";
 import { PropertyPanel } from "./editor/PropertyPanel";
 import { LayersPanel } from "./editor/LayersPanel";
 import { CaptionPropertyPanel } from "../captions/components/CaptionPropertyPanel";
 import { BlockParamsPanel } from "./editor/BlockParamsPanel";
 import { RenderQueue } from "./renders/RenderQueue";
 import { SlideshowPanel } from "./panels/SlideshowPanel";
-import type { SceneInfo } from "./panels/SlideshowPanel";
 import { VariablesPanel } from "./panels/VariablesPanel";
 import { PanelTabButton } from "./PanelTabButton";
 import { usePreviewVariablesStore } from "../hooks/previewVariablesStore";
 import type { RenderJob } from "./renders/useRenderQueue";
 import type { BlockParam } from "@hyperframes/core/registry";
-import type { IframeWindow } from "../player/lib/playbackTypes";
 import {
   STUDIO_FLAT_INSPECTOR_ENABLED,
   STUDIO_INSPECTOR_PANELS_ENABLED,
@@ -19,6 +17,7 @@ import {
 import type { Composition } from "@hyperframes/sdk";
 import type { EditHistoryKind } from "../utils/editHistory";
 import { useSlideshowPersist, type UseSlideshowPersistParams } from "../hooks/useSlideshowPersist";
+import { useSlideshowTabState } from "../hooks/useSlideshowTabState";
 import { DesignPanelPromoteProvider } from "./DesignPanelPromoteProvider";
 
 import { useStudioPlaybackContext, useStudioShellContext } from "../contexts/StudioContext";
@@ -51,6 +50,19 @@ export interface StudioRightPanelProps {
   /** Dependencies for the Slideshow persist callback, threaded from App.tsx. */
   sdkSession: Composition | null;
   publishSdkSession: NonNullable<UseSlideshowPersistParams["publishSdkSession"]>;
+  /**
+   * Forces THIS `sdkSession` to re-open from disk. DesignPanelPromoteProvider
+   * opens its own separate SDK session scoped to the selected element's own
+   * file (needed so promoting inside a sub-composition binds a variable there,
+   * not on the host) — for a top-level selection that's the SAME file this
+   * session already has open, so a write through that other session leaves
+   * this one holding stale in-memory content. The self-write-echo registry
+   * that normally suppresses redundant reloads is keyed by file path only, not
+   * by session instance, so it wrongly treats the sibling session's write as
+   * "our own echo" and never reloads on its own — this must be called
+   * explicitly after such a write.
+   */
+  forceReloadSdkSession?: () => void;
   reloadPreview: () => void;
   domEditSaveTimestampRef: MutableRefObject<number>;
   recordEdit: (entry: {
@@ -71,6 +83,7 @@ export function StudioRightPanel({
   onToggleRecording,
   sdkSession,
   publishSdkSession,
+  forceReloadSdkSession,
   reloadPreview,
   domEditSaveTimestampRef,
   recordEdit,
@@ -154,6 +167,7 @@ export function StudioRightPanel({
     readProjectFile,
     writeProjectFile,
     fileTree,
+    editingFile,
   } = useFileManagerContext();
 
   // Discrete ops (toggle, reorder, add/delete, hotspot): persist immediately,
@@ -202,22 +216,13 @@ export function StudioRightPanel({
   const renderJobs = renderQueue.jobs as RenderJob[];
   const inspectorTabActive = rightPanelTab === "design" || rightPanelTab === "layers";
 
-  // Derive scene list from the live clip manifest in the preview iframe.
-  // fallow-ignore-next-line complexity
-  const slideshowScenes = useMemo<SceneInfo[]>(() => {
-    try {
-      const win = previewIframeRef.current?.contentWindow as IframeWindow | null;
-      return (win?.__clipManifest?.scenes ?? []).map((s) => ({
-        id: s.id,
-        label: s.label,
-        start: s.start,
-        duration: s.duration,
-      }));
-    } catch {
-      return [];
-    }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [previewIframeRef, rightPanelTab, refreshKey]);
+  const { isSlideshowComposition, slideshowScenes } = useSlideshowTabState({
+    editingFileContent: editingFile?.content,
+    previewIframeRef,
+    refreshKey,
+    rightPanelTab,
+    setRightPanelTab,
+  });
   const designPaneOpen = inspectorTabActive && rightInspectorPanes.design && designPanelActive;
   const layersPaneOpen =
     inspectorTabActive && rightInspectorPanes.layers && STUDIO_INSPECTOR_PANELS_ENABLED;
@@ -336,6 +341,7 @@ export function StudioRightPanel({
       recordEdit={recordEdit}
       reloadPreview={reloadPreview}
       domEditSaveTimestampRef={domEditSaveTimestampRef}
+      forceReloadSharedSdkSession={forceReloadSdkSession}
     >
       <PropertyPanel
         projectId={projectId}
@@ -491,12 +497,14 @@ export function StudioRightPanel({
                 active={rightPanelTab === "renders"}
                 onClick={() => setRightPanelTab("renders")}
               />
-              <PanelTabButton
-                label="Slideshow"
-                tooltip="Slideshow branching editor"
-                active={rightPanelTab === "slideshow"}
-                onClick={() => setRightPanelTab("slideshow")}
-              />
+              {isSlideshowComposition && (
+                <PanelTabButton
+                  label="Slideshow"
+                  tooltip="Slideshow branching editor"
+                  active={rightPanelTab === "slideshow"}
+                  onClick={() => setRightPanelTab("slideshow")}
+                />
+              )}
               <PanelTabButton
                 label="Variables"
                 tooltip="Template variables — declare, preview with values"
@@ -513,7 +521,7 @@ export function StudioRightPanel({
                   compositionPath={activeBlockParams.compositionPath}
                   onClose={onCloseBlockParams ?? (() => {})}
                 />
-              ) : rightPanelTab === "slideshow" ? (
+              ) : rightPanelTab === "slideshow" && isSlideshowComposition ? (
                 <SlideshowPanel
                   scenes={slideshowScenes}
                   onPersist={onPersistSlideshow}

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

@@ -9,6 +9,57 @@ import { DomEditSelectionChrome } from "./DomEditSelectionChrome";
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
 describe("DomEditSelectionChrome crop composition", () => {
+  it("renders overlay-only transparent chrome at headline geometry without changing composition bytes", () => {
+    const composition = document.implementation.createHTMLDocument();
+    composition.body.innerHTML = `
+      <section class="hl-block"><div class="hl-mask" style="overflow:hidden;background:transparent">
+        <h1 class="hl-text">Launch title</h1>
+      </div></section>
+    `;
+    const headline = composition.querySelector<HTMLElement>(".hl-text")!;
+    const before = composition.documentElement.outerHTML;
+    const selection = {
+      element: headline,
+      selector: ".hl-text",
+      capabilities: {
+        canCrop: false,
+        canApplyManualOffset: false,
+        canApplyManualSize: false,
+        canApplyManualRotation: false,
+      },
+    } as unknown as DomEditSelection;
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    act(() => {
+      root.render(
+        <DomEditSelectionChrome
+          selection={selection}
+          overlayRect={{ left: 44, top: 52, width: 220, height: 48, editScaleX: 1, editScaleY: 1 }}
+          allowCanvasMovement={false}
+          boxRef={createRef()}
+          boxChromeClass="border border-studio-accent/80"
+          boxClipPath={undefined}
+          selectionKey="headline"
+          groupSelectionCount={0}
+          blockedMoveRef={createRef()}
+          gestures={{ startGesture: vi.fn() } as never}
+          onStyleCommit={vi.fn()}
+          onBoxMouseDown={vi.fn()}
+          onBoxClick={vi.fn()}
+        />,
+      );
+    });
+    const chrome = host.querySelector<HTMLElement>('[data-dom-edit-selection-box="true"]')!;
+    expect(chrome.style.cssText).toContain("left: 44px");
+    expect(chrome.style.cssText).toContain("width: 220px");
+    expect(chrome.style.background).toBe("");
+    expect(chrome.className).not.toMatch(/bg-/);
+    expect(composition.documentElement.outerHTML).toBe(before);
+    act(() => root.unmount());
+    host.remove();
+  });
+
   it("places rotated crop UI in exactly one oriented coordinate plane", () => {
     const element = document.createElement("div");
     element.id = "clip";

package/src/components/editor/PromotableControl.tsx

@@ -81,7 +81,9 @@ export function PromotableControl({
       {rendered}
       {bound && (
         <span
-          className="pointer-events-none absolute right-1.5 top-0 z-10 inline-flex max-w-[60%] items-center gap-1 truncate rounded bg-studio-accent/20 px-1 py-px font-mono text-[8px] font-medium text-studio-accent"
+          // Sits above the row (not on top of top-0) so it clears a value that
+          // renders flush to the row's right edge, e.g. flat Font/Color rows.
+          className="pointer-events-none absolute -top-2 right-1.5 z-10 inline-flex max-w-[60%] items-center gap-1 truncate rounded bg-studio-accent/20 px-1 py-px font-mono text-[8px] font-medium text-studio-accent"
           title={`Bound to variable "${promote.boundId}"`}
         >
           ◆ {promote.boundId}
@@ -95,7 +97,7 @@ export function PromotableControl({
             e.stopPropagation();
             promote.promote();
           }}
-          className="absolute right-1.5 top-0 z-10 inline-flex items-center gap-1 rounded bg-neutral-800/80 px-1 py-px font-mono text-[8px] font-medium text-neutral-400 opacity-70 transition-colors hover:bg-studio-accent/20 hover:text-studio-accent hover:opacity-100"
+          className="absolute -top-2 right-1.5 z-10 inline-flex items-center gap-1 rounded bg-neutral-800/80 px-1 py-px font-mono text-[8px] font-medium text-neutral-400 opacity-70 transition-colors hover:bg-studio-accent/20 hover:text-studio-accent hover:opacity-100"
         >
           ◇ var
         </button>