@hyperframes/studio 0.7.93 → 0.7.95

package/package.json

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

package/src/components/EditorShell.selectionSync.test.tsx

@@ -0,0 +1,109 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { EditorShell } from "./EditorShell";
+
+const hookMocks = vi.hoisted(() => ({
+  useTimelineSelectionPreviewSync: vi.fn(),
+}));
+
+vi.mock("../hooks/useTimelineSelectionPreviewSync", () => hookMocks);
+vi.mock("../contexts/StudioContext", () => ({
+  useStudioPlaybackContext: () => ({
+    captionEditMode: false,
+    refreshKey: 0,
+    refreshPreviewDocumentVersion: vi.fn(),
+    timelineElements: [],
+  }),
+  useStudioShellContext: () => ({
+    projectId: "project-1",
+    activeCompPath: "index.html",
+    setActiveCompPath: vi.fn(),
+    handlePreviewIframeRef: vi.fn(),
+    showToast: vi.fn(),
+  }),
+}));
+vi.mock("../contexts/DomEditContext", () => ({
+  useDomEditActionsContext: () => ({
+    handleTimelineElementSelect: vi.fn(),
+    buildDomSelectionForTimelineElement: vi.fn(),
+    applyDomSelection: vi.fn(),
+    applyMarqueeSelection: vi.fn(),
+  }),
+  useDomEditSelectionContext: () => ({
+    domEditSelection: null,
+    domEditGroupSelections: [],
+  }),
+}));
+vi.mock("./nle/NLEContext", () => ({
+  NLEProvider: ({ children }: { children: React.ReactNode }) => children,
+  useNLEContext: () => ({
+    compositionStack: [],
+    updateCompositionStack: vi.fn(),
+    containerRef: { current: null },
+  }),
+}));
+vi.mock("./nle/useTimelineEditCallbacks", () => ({
+  useTimelineEditCallbacks: () => ({}),
+}));
+vi.mock("./nle/PreviewPane", () => ({ PreviewPane: () => null }));
+vi.mock("./nle/PreviewOverlays", () => ({ PreviewOverlays: () => null }));
+vi.mock("./nle/TimelinePane", () => ({ TimelinePane: () => null }));
+vi.mock("../captions/components/CaptionTimeline", () => ({ CaptionTimeline: () => null }));
+vi.mock("./StudioFeedbackBar", () => ({ StudioFeedbackBar: () => null }));
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  hookMocks.useTimelineSelectionPreviewSync.mockClear();
+});
+
+describe("EditorShell timeline selection sync", () => {
+  it("keeps the timeline store mirrored into the preview selection", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+
+    act(() => {
+      root.render(
+        <EditorShell
+          left={null}
+          right={null}
+          timelineToolbar={null}
+          renderClipContent={() => null}
+          handleTimelineElementDelete={vi.fn()}
+          handleTimelineAssetDrop={vi.fn()}
+          handleTimelineFileDrop={vi.fn()}
+          handleTimelineElementMove={vi.fn()}
+          handleTimelineElementsMove={vi.fn()}
+          handleTimelineElementResize={vi.fn()}
+          handleTimelineGroupResize={vi.fn()}
+          handleToggleTrackHidden={vi.fn()}
+          handleBlockedTimelineEdit={vi.fn()}
+          handleTimelineElementSplit={vi.fn()}
+          handleRazorSplit={vi.fn()}
+          handleRazorSplitAll={vi.fn()}
+          setCompIdToSrc={vi.fn()}
+          setCompositionLoading={vi.fn()}
+          shouldShowMotionPath={false}
+          shouldShowSelectedDomBounds={false}
+        />,
+      );
+    });
+
+    expect(hookMocks.useTimelineSelectionPreviewSync).toHaveBeenCalledOnce();
+    expect(hookMocks.useTimelineSelectionPreviewSync).toHaveBeenCalledWith(
+      expect.objectContaining({
+        activeCompPath: "index.html",
+        timelineElements: [],
+        domEditSelection: null,
+        domEditGroupSelections: [],
+      }),
+    );
+
+    act(() => root.unmount());
+  });
+});

package/src/components/EditorShell.tsx

@@ -10,11 +10,12 @@ import { NLEProvider, useNLEContext } from "./nle/NLEContext";
 import { CaptionTimeline } from "../captions/components/CaptionTimeline";
 import { StudioFeedbackBar } from "./StudioFeedbackBar";
 import { useStudioPlaybackContext, useStudioShellContext } from "../contexts/StudioContext";
-import { useDomEditActionsContext } from "../contexts/DomEditContext";
+import { useDomEditActionsContext, useDomEditSelectionContext } from "../contexts/DomEditContext";
 import { TimelineEditProvider } from "../contexts/TimelineEditContext";
-import type { TimelineElement } from "../player";
+import { usePlayerStore, type TimelineElement } from "../player";
 import type { BlockPreviewInfo } from "./sidebar/BlocksTab";
 import type { GestureRecordingState } from "./editor/GestureRecordControl";
+import { useTimelineSelectionPreviewSync } from "../hooks/useTimelineSelectionPreviewSync";
 
 type RenderClipContent = (
   element: TimelineElement,
@@ -99,10 +100,35 @@ export function EditorShell({
   blockPreview,
   gestureOverlay,
 }: EditorShellProps) {
-  const { projectId, activeCompPath, setActiveCompPath, handlePreviewIframeRef } =
+  const { projectId, activeCompPath, setActiveCompPath, handlePreviewIframeRef, showToast } =
     useStudioShellContext();
-  const { refreshKey, captionEditMode, refreshPreviewDocumentVersion } = useStudioPlaybackContext();
-  const { handleTimelineElementSelect } = useDomEditActionsContext();
+  const { refreshKey, captionEditMode, refreshPreviewDocumentVersion, timelineElements } =
+    useStudioPlaybackContext();
+  const {
+    handleTimelineElementSelect,
+    buildDomSelectionForTimelineElement,
+    applyDomSelection,
+    applyMarqueeSelection,
+  } = useDomEditActionsContext();
+  const { domEditSelection, domEditGroupSelections } = useDomEditSelectionContext();
+  const selectedElementId = usePlayerStore((state) => state.selectedElementId);
+  const selectedElementIds = usePlayerStore((state) => state.selectedElementIds);
+  const reportTimelineSelectionNotFound = useCallback(() => {
+    showToast("The selected clip is not available in the preview yet.", "info");
+  }, [showToast]);
+
+  useTimelineSelectionPreviewSync({
+    selectedElementId,
+    selectedElementIds,
+    timelineElements,
+    domEditSelection,
+    domEditGroupSelections,
+    activeCompPath,
+    buildDomSelectionForTimelineElement,
+    applyDomSelection,
+    applyMarqueeSelection,
+    onSelectionNotFound: reportTimelineSelectionNotFound,
+  });
 
   const timelineEditCallbacks = useTimelineEditCallbacks({
     handleTimelineElementMove,

package/src/components/TimelineToolbar.test.tsx

@@ -12,7 +12,7 @@ import { TimelineToolbar } from "./TimelineToolbar";
 
 afterEach(() => {
   document.body.innerHTML = "";
-  usePlayerStore.setState({ autoKeyframeEnabled: true });
+  usePlayerStore.setState({ autoKeyframeEnabled: true, thumbnailMode: "adaptive" });
 });
 
 function renderToolbar(
@@ -58,6 +58,25 @@ describe("TimelineToolbar — auto-keyframe toggle (#1808)", () => {
     act(() => root.unmount());
   });
 });
+
+describe("TimelineToolbar — adaptive thumbnails", () => {
+  it("keeps a user-controlled hidden mode as the rollback path", () => {
+    const { host, root } = renderToolbar();
+    const button = host.querySelector<HTMLButtonElement>(
+      'button[aria-label="Hide thumbnails — labels only"]',
+    );
+    if (!button) throw new Error("thumbnail toggle not rendered");
+
+    act(() => button.click());
+
+    expect(usePlayerStore.getState().thumbnailMode).toBe("hidden");
+    expect(button.getAttribute("aria-label")).toBe(
+      "Show thumbnails — posters stay visible; richer previews appear on interaction",
+    );
+    act(() => root.unmount());
+  });
+});
+
 describe("TimelineToolbar — motion path endpoints", () => {
   it("does not advertise a destructive keyframe toggle for a required endpoint", () => {
     usePlayerStore.setState({ currentTime: 10 });

package/src/components/TimelineToolbar.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useRef } from "react";
-import { Magnet, MagnifyingGlassMinus, MagnifyingGlassPlus } from "@phosphor-icons/react";
+import { Image, Magnet, MagnifyingGlassMinus, MagnifyingGlassPlus } from "@phosphor-icons/react";
 import {
   useEnableKeyframes,
   isPlayheadWithinTween,
@@ -111,6 +111,9 @@ export function TimelineToolbar({ domEditSession, onSplitElement }: TimelineTool
   const setTimelineSnapEnabled = usePlayerStore((s) => s.setTimelineSnapEnabled);
   const autoKeyframeEnabled = usePlayerStore((s) => s.autoKeyframeEnabled);
   const setAutoKeyframeEnabled = usePlayerStore((s) => s.setAutoKeyframeEnabled);
+  const thumbnailMode = usePlayerStore((s) => s.thumbnailMode);
+  const setThumbnailMode = usePlayerStore((s) => s.setThumbnailMode);
+  const thumbnailsVisible = thumbnailMode === "adaptive";
   // Subscribe so the add-beat button reacts to playhead movement and analysis load.
   const currentTime = usePlayerStore((s) => s.currentTime);
   const beatAnalysisReady = usePlayerStore((s) => s.beatAnalysis !== null);
@@ -403,6 +406,31 @@ export function TimelineToolbar({ domEditSession, onSplitElement }: TimelineTool
           })()}
         </div>
         <div className="flex items-center gap-0.5">
+          <Tooltip
+            label={
+              thumbnailsVisible
+                ? "Hide thumbnails — labels only"
+                : "Show thumbnails — posters stay visible; richer previews appear on interaction"
+            }
+          >
+            <button
+              type="button"
+              aria-label={
+                thumbnailsVisible
+                  ? "Hide thumbnails — labels only"
+                  : "Show thumbnails — posters stay visible; richer previews appear on interaction"
+              }
+              aria-pressed={thumbnailsVisible}
+              onClick={() => setThumbnailMode(thumbnailsVisible ? "hidden" : "adaptive")}
+              className={`h-7 px-2 rounded-md text-[11px] font-medium transition-colors ${
+                thumbnailsVisible
+                  ? "bg-studio-accent/10 text-studio-accent"
+                  : "text-neutral-400 hover:bg-white/[0.06] hover:text-neutral-200"
+              }`}
+            >
+              <Image size={16} aria-hidden="true" />
+            </button>
+          </Tooltip>
           <Tooltip label="Fit timeline to width">
             <button
               type="button"

package/src/hooks/useRenderClipContent.test.ts

@@ -5,13 +5,15 @@ import { createRoot } from "react-dom/client";
 import { afterEach, describe, expect, it } from "vitest";
 import { CompositionThumbnail, VideoThumbnail } from "../player";
 import { AudioWaveform } from "../player/components/AudioWaveform";
-import type { TimelineElement } from "../player/store/playerStore";
+import type { TimelineClipRenderContext } from "../player/components/TimelineTypes";
+import { usePlayerStore, type TimelineElement } from "../player/store/playerStore";
 import { normalizeCompositionSrc } from "./useRenderClipContent";
 import { useRenderClipContent } from "./useRenderClipContent";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
 afterEach(() => {
+  usePlayerStore.setState({ thumbnailMode: "hidden" });
   document.body.innerHTML = "";
 });
 
@@ -67,6 +69,7 @@ describe("useRenderClipContent", () => {
   function renderClipContent(
     el: TimelineElement,
     activePreviewUrl: string | null = "/api/projects/my-project/preview",
+    context?: TimelineClipRenderContext,
   ): ReactNode {
     const host = document.createElement("div");
     document.body.append(host);
@@ -80,7 +83,7 @@ describe("useRenderClipContent", () => {
         activePreviewUrl,
         effectiveTimelineDuration: 12,
       });
-      content = render(el, { clip: "#222", label: "#fff" });
+      content = render(el, { clip: "#222", label: "#fff" }, context);
       return null;
     }
 
@@ -105,7 +108,45 @@ describe("useRenderClipContent", () => {
     if (isValidElement(content)) expect(content.type).toBe(AudioWaveform);
   });
 
+  it("routes root-relative iframe media back through the active project", () => {
+    usePlayerStore.setState({ thumbnailMode: "adaptive" });
+    const resolvedRootMedia = `${window.location.origin}/assets/clip.mp4`;
+    const video = renderClipContent(
+      {
+        id: "video",
+        tag: "video",
+        start: 0,
+        duration: 4,
+        track: 0,
+        src: resolvedRootMedia,
+      },
+      null,
+    );
+    const audio = renderClipContent({
+      id: "audio",
+      tag: "audio",
+      start: 0,
+      duration: 4,
+      track: 1,
+      src: resolvedRootMedia,
+    });
+
+    expect(isValidElement<{ videoSrc: string }>(video)).toBe(true);
+    expect(isValidElement<{ audioUrl: string; waveformUrl: string }>(audio)).toBe(true);
+    if (isValidElement<{ videoSrc: string }>(video)) {
+      expect(video.props.videoSrc).toBe("/api/projects/my-project/preview/assets/clip.mp4");
+    }
+    if (isValidElement<{ audioUrl: string; waveformUrl: string }>(audio)) {
+      expect(audio.props).toMatchObject({
+        audioUrl: "/api/projects/my-project/preview/assets/clip.mp4",
+        waveformUrl: "/api/projects/my-project/waveform/assets/clip.mp4",
+      });
+    }
+  });
+
   it("passes empty labels to thumbnail content so TimelineClip owns clip names", () => {
+    usePlayerStore.setState({ thumbnailMode: "adaptive" });
+
     const cases: Array<{ content: ReactNode; type: unknown }> = [
       {
         content: renderClipContent({
@@ -166,4 +207,38 @@ describe("useRenderClipContent", () => {
       }
     }
   });
+
+  it("forwards the viewport priority and interaction detail to media work", () => {
+    usePlayerStore.setState({ thumbnailMode: "adaptive", timelineSessionEpoch: 7 });
+
+    const content = renderClipContent(
+      {
+        id: "clip-video",
+        tag: "video",
+        start: 0,
+        duration: 4,
+        track: 0,
+        src: "assets/clip.mp4",
+      },
+      null,
+      { priority: "interaction", rich: true },
+    );
+
+    expect(
+      isValidElement<{
+        projectId: string;
+        sessionEpoch: number;
+        priority: string;
+        rich: boolean;
+      }>(content),
+    ).toBe(true);
+    if (isValidElement(content)) {
+      expect(content.props).toMatchObject({
+        projectId: "my-project",
+        sessionEpoch: 7,
+        priority: "interaction",
+        rich: true,
+      });
+    }
+  });
 });

package/src/hooks/useRenderClipContent.ts

@@ -2,9 +2,12 @@ import { useCallback, type ReactNode } from "react";
 import { createElement } from "react";
 import { CompositionThumbnail, VideoThumbnail } from "../player";
 import type { TimelineElement } from "../player";
+import type { TimelineClipRenderContext } from "../player/components/TimelineTypes";
 import { AudioWaveform } from "../player/components/AudioWaveform";
 import { ImageThumbnail } from "../player/components/ImageThumbnail";
 import { encodePreviewPath, resolveMediaPreviewUrl } from "../player/components/thumbnailUtils";
+import { usePlayerStore } from "../player/store/playerStore";
+import { effectiveThumbnailMode } from "../player/lib/thumbnailPolicy";
 
 export function normalizeCompositionSrc(
   compSrc: string,
@@ -24,12 +27,21 @@ export function normalizeCompositionSrc(
 }
 
 /** Resolve a media src to its project-relative preview path, or null. */
-function resolvePreviewRelative(src: string | undefined, pid: string): string | null {
+function resolvePreviewRelative(
+  src: string | undefined,
+  pid: string,
+  origin: string,
+): string | null {
   if (!src) return null;
-  if (!src.startsWith("http")) return src;
-  const base = `/api/projects/${pid}/preview/`;
-  const idx = src.indexOf(base);
-  return idx !== -1 ? decodeURIComponent(src.slice(idx + base.length)) : null;
+  try {
+    const parsed = new URL(src, origin);
+    const base = new URL(`/api/projects/${pid}/preview/`, origin).pathname;
+    return parsed.pathname.startsWith(base)
+      ? decodeURIComponent(parsed.pathname.slice(base.length))
+      : null;
+  } catch {
+    return null;
+  }
 }
 
 /**
@@ -51,15 +63,19 @@ function trimFractions(el: TimelineElement): { start?: number; end?: number } {
  * Build the waveform element for an audio clip, windowing the rendered peaks to
  * the trimmed source slice so the bars track the clip edges.
  */
-function renderAudioClip(el: TimelineElement, pid: string, labelColor: string): ReactNode {
-  const srcRelative = resolvePreviewRelative(el.src, pid);
+function renderAudioClip(
+  el: TimelineElement,
+  pid: string,
+  sessionEpoch: number,
+  labelColor: string,
+  context: TimelineClipRenderContext,
+): ReactNode {
+  const audioUrl = resolveMediaPreviewUrl(el.src ?? "", pid, window.location.origin);
+  const srcRelative = resolvePreviewRelative(audioUrl, pid, window.location.origin);
   // Encode each path segment (spaces, parens, U+202F, unicode) so the URL matches
   // what the assets panel loads — a raw segment 404s. resolvePreviewRelative
   // returns the DECODED path, so it must be re-encoded here.
   const encodedRelative = srcRelative ? encodePreviewPath(srcRelative) : null;
-  const audioUrl = encodedRelative
-    ? `/api/projects/${pid}/preview/${encodedRelative}`
-    : (el.src ?? "");
   const waveformUrl = encodedRelative
     ? `/api/projects/${pid}/waveform/${encodedRelative}`
     : undefined;
@@ -71,6 +87,9 @@ function renderAudioClip(el: TimelineElement, pid: string, labelColor: string):
     labelColor,
     trimStartFraction: start,
     trimEndFraction: end,
+    projectId: pid,
+    sessionEpoch,
+    priority: context.priority,
   });
 }
 
@@ -87,13 +106,29 @@ export function useRenderClipContent({
   activePreviewUrl,
   effectiveTimelineDuration,
 }: UseRenderClipContentOptions) {
+  // Self-sourced so the adaptive policy gates thumbnail generation without App plumbing.
+  const thumbnailMode = usePlayerStore((s) => s.thumbnailMode);
+  const effectiveMode = effectiveThumbnailMode(thumbnailMode);
+  const sessionEpoch = usePlayerStore((s) => s.timelineSessionEpoch);
   return useCallback(
     // Pre-existing clip-content dispatcher; reduced by extracting renderAudioClip.
     // fallow-ignore-next-line complexity
-    (el: TimelineElement, style: { clip: string; label: string }): ReactNode => {
+    (
+      el: TimelineElement,
+      style: { clip: string; label: string },
+      context: TimelineClipRenderContext = { priority: "visible", rich: false },
+    ): ReactNode => {
       const pid = projectIdRef.current;
       if (!pid) return null;
 
+      // Thumbnail generation disabled (perf) -> plain clip bars. Audio still shows
+      // its waveform (cheap, not a frame thumbnail). Toggle: timeline toolbar.
+      if (effectiveMode === "hidden") {
+        return el.tag === "audio"
+          ? renderAudioClip(el, pid, sessionEpoch, style.label, context)
+          : null;
+      }
+
       let compSrc = el.compositionSrc;
       if (compSrc) {
         compSrc = normalizeCompositionSrc(compSrc, pid, window.location.origin);
@@ -116,6 +151,10 @@ export function useRenderClipContent({
 
           seekTime: 0,
           duration: el.duration,
+          projectId: pid,
+          sessionEpoch,
+          priority: context.priority,
+          rich: context.rich,
         });
       }
 
@@ -123,7 +162,7 @@ export function useRenderClipContent({
       // activePreviewUrl thumbnail branch; audio rows need waveform data, not a
       // captured frame from the currently drilled composition preview.
       if (el.tag === "audio") {
-        return renderAudioClip(el, pid, style.label);
+        return renderAudioClip(el, pid, sessionEpoch, style.label, context);
       }
 
       // When drilled into a composition, render all inner elements via
@@ -138,6 +177,10 @@ export function useRenderClipContent({
           selectorIndex: el.selectorIndex,
           seekTime: el.start,
           duration: el.duration,
+          projectId: pid,
+          sessionEpoch,
+          priority: context.priority,
+          rich: context.rich,
         });
       }
 
@@ -148,7 +191,7 @@ export function useRenderClipContent({
         !/(backdrop|background|overlay|scrim|mask)/i.test(el.id);
 
       if ((el.tag === "video" || el.tag === "img") && el.src) {
-        const mediaSrc = resolveMediaPreviewUrl(el.src, pid);
+        const mediaSrc = resolveMediaPreviewUrl(el.src, pid, window.location.origin);
         // Still images can't be decoded by VideoThumbnail's <video> extractor
         // (the error event fires and the shimmer never resolves) — render the
         // image itself as the strip.
@@ -157,6 +200,10 @@ export function useRenderClipContent({
             imageSrc: mediaSrc,
             label: "",
             labelColor: style.label,
+            projectId: pid,
+            sessionEpoch,
+            priority: context.priority,
+            rich: context.rich,
           });
         }
         return createElement(VideoThumbnail, {
@@ -164,6 +211,12 @@ export function useRenderClipContent({
           label: "",
           labelColor: style.label,
           duration: el.duration,
+          sourceStart: el.playbackStart,
+          sourceRangeDuration: el.duration * (el.playbackRate ?? 1),
+          projectId: pid,
+          sessionEpoch,
+          priority: context.priority,
+          rich: context.rich,
         });
       }
 
@@ -177,11 +230,22 @@ export function useRenderClipContent({
           selectorIndex: el.selectorIndex,
           seekTime: el.start,
           duration: el.duration,
+          projectId: pid,
+          sessionEpoch,
+          priority: context.priority,
+          rich: context.rich,
         });
       }
 
       return null;
     },
-    [projectIdRef, compIdToSrc, activePreviewUrl, effectiveTimelineDuration],
+    [
+      projectIdRef,
+      compIdToSrc,
+      activePreviewUrl,
+      effectiveTimelineDuration,
+      effectiveMode,
+      sessionEpoch,
+    ],
   );
 }