@hyperframes/studio 0.7.39 → 0.7.40

package/src/hooks/timelineTrackVisibility.ts

@@ -0,0 +1,371 @@
+import { useCallback } from "react";
+import { usePlayerStore, type TimelineElement } from "../player";
+import { useExpandedTimelineElements } from "../player/hooks/useExpandedTimelineElements";
+import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
+import { readTagSnippetByTarget, type PatchOperation } from "../utils/sourcePatcher";
+import {
+  applyPatchByTarget,
+  buildPatchTarget,
+  findTimelineElementInIframe,
+  readFileContent,
+  type RecordEditInput,
+} from "./timelineEditingHelpers";
+
+interface MutableRef<T> {
+  current: T;
+}
+
+interface ReadonlyRef<T> {
+  readonly current: T;
+}
+
+interface ToggleTimelineTrackHiddenInput {
+  projectId: string;
+  activeCompPath: string | null;
+  timelineElements: readonly TimelineElement[];
+  track: number;
+  hidden: boolean;
+  previewIframe: HTMLIFrameElement | null;
+  writeProjectFile: (path: string, content: string) => Promise<void>;
+  recordEdit: (input: RecordEditInput) => Promise<void>;
+  domEditSaveTimestampRef: MutableRef<number>;
+  pendingTimelineEditPathRef: MutableRef<Set<string>>;
+}
+
+interface ToggleTimelineElementHiddenInput extends Omit<ToggleTimelineTrackHiddenInput, "track"> {
+  elementKey: string;
+}
+
+interface SetElementsHiddenInput {
+  projectId: string;
+  activeCompPath: string | null;
+  elements: readonly TimelineElement[];
+  hidden: boolean;
+  label: string;
+  previewIframe: HTMLIFrameElement | null;
+  writeProjectFile: (path: string, content: string) => Promise<void>;
+  recordEdit: (input: RecordEditInput) => Promise<void>;
+  domEditSaveTimestampRef: MutableRef<number>;
+  pendingTimelineEditPathRef: MutableRef<Set<string>>;
+}
+
+interface UseTimelineTrackVisibilityEditingInput extends Omit<
+  ToggleTimelineTrackHiddenInput,
+  "projectId" | "track" | "hidden" | "previewIframe"
+> {
+  projectIdRef: ReadonlyRef<string | null>;
+  previewIframeRef: ReadonlyRef<HTMLIFrameElement | null>;
+  showToast: (message: string, tone?: "error" | "info") => void;
+  isRecordingRef?: ReadonlyRef<boolean>;
+  forceReloadSdkSession?: () => void;
+}
+
+interface UseTimelineElementVisibilityEditingInput extends Omit<
+  ToggleTimelineElementHiddenInput,
+  "projectId" | "elementKey" | "hidden" | "previewIframe"
+> {
+  projectIdRef: ReadonlyRef<string | null>;
+  previewIframeRef: ReadonlyRef<HTMLIFrameElement | null>;
+  showToast: (message: string, tone?: "error" | "info") => void;
+  isRecordingRef?: ReadonlyRef<boolean>;
+  forceReloadSdkSession?: () => void;
+}
+
+function getTimelineElementTargetPath(
+  element: TimelineElement,
+  activeCompPath: string | null,
+): string {
+  return element.sourceFile || activeCompPath || "index.html";
+}
+
+function patchLiveHiddenState(
+  iframe: HTMLIFrameElement | null,
+  elements: readonly TimelineElement[],
+  hidden: boolean,
+): void {
+  for (const element of elements) {
+    const target = findTimelineElementInIframe(iframe, element);
+    if (!target) continue;
+    if (hidden) {
+      target.setAttribute("data-hidden", "");
+    } else {
+      target.removeAttribute("data-hidden");
+    }
+  }
+}
+
+function reseekPreviewRuntime(iframe: HTMLIFrameElement | null): void {
+  try {
+    const win: (Window & { __player?: { seek?: (time: number) => void } }) | null =
+      iframe?.contentWindow ?? null;
+    win?.__player?.seek?.(usePlayerStore.getState().currentTime);
+  } catch {}
+}
+
+function groupElementsByTargetPath(
+  elements: readonly TimelineElement[],
+  activeCompPath: string | null,
+): Map<string, TimelineElement[]> {
+  const byPath = new Map<string, TimelineElement[]>();
+  for (const element of elements) {
+    const targetPath = getTimelineElementTargetPath(element, activeCompPath);
+    const existing = byPath.get(targetPath);
+    if (existing) {
+      existing.push(element);
+    } else {
+      byPath.set(targetPath, [element]);
+    }
+  }
+  return byPath;
+}
+
+// fallow-ignore-next-line complexity
+async function setElementsHidden({
+  projectId,
+  activeCompPath,
+  elements,
+  hidden,
+  label,
+  previewIframe,
+  writeProjectFile,
+  recordEdit,
+  domEditSaveTimestampRef,
+  pendingTimelineEditPathRef,
+}: SetElementsHiddenInput): Promise<string[]> {
+  if (elements.length === 0) return [];
+
+  patchLiveHiddenState(previewIframe, elements, hidden);
+  reseekPreviewRuntime(previewIframe);
+
+  const hiddenOperation: PatchOperation = {
+    type: "attribute",
+    property: "hidden",
+    value: hidden ? "" : null,
+  };
+  const originalByPath = new Map<string, string>();
+  const files: Record<string, string> = {};
+
+  try {
+    for (const [targetPath, fileElements] of groupElementsByTargetPath(elements, activeCompPath)) {
+      let patchedContent = await readFileContent(projectId, targetPath);
+      originalByPath.set(targetPath, patchedContent);
+
+      for (const element of fileElements) {
+        const patchTarget = buildPatchTarget(element);
+        if (!patchTarget) {
+          throw new Error(`Timeline element ${element.id} is missing a patchable target`);
+        }
+        if (readTagSnippetByTarget(patchedContent, patchTarget) === undefined) {
+          throw new Error(`Unable to patch timeline element ${element.id} in ${targetPath}`);
+        }
+        patchedContent = applyPatchByTarget(patchedContent, patchTarget, hiddenOperation);
+      }
+
+      files[targetPath] = patchedContent;
+      pendingTimelineEditPathRef.current.add(targetPath);
+    }
+
+    domEditSaveTimestampRef.current = Date.now();
+    const changedPaths = await saveProjectFilesWithHistory({
+      projectId,
+      label,
+      kind: "timeline",
+      files,
+      readFile: async (path) => {
+        const original = originalByPath.get(path);
+        if (original !== undefined) return original;
+        return readFileContent(projectId, path);
+      },
+      writeFile: writeProjectFile,
+      recordEdit,
+    });
+    domEditSaveTimestampRef.current = Date.now();
+    for (const element of elements) {
+      usePlayerStore.getState().updateElement(element.key ?? element.id, { hidden });
+    }
+    return changedPaths;
+  } catch (error) {
+    // The optimistic live patch already ran; a patch-target/save failure here would
+    // otherwise leave the preview showing the wrong visibility until a reload. Revert
+    // the live DOM to the prior state so what's on screen matches what persisted.
+    patchLiveHiddenState(previewIframe, elements, !hidden);
+    reseekPreviewRuntime(previewIframe);
+    throw error;
+  }
+}
+
+export async function toggleTimelineTrackHidden({
+  projectId,
+  activeCompPath,
+  timelineElements,
+  track,
+  hidden,
+  previewIframe,
+  writeProjectFile,
+  recordEdit,
+  domEditSaveTimestampRef,
+  pendingTimelineEditPathRef,
+}: ToggleTimelineTrackHiddenInput): Promise<string[]> {
+  return setElementsHidden({
+    projectId,
+    activeCompPath,
+    elements: timelineElements.filter((element) => element.track === track),
+    hidden,
+    label: hidden ? `Hide track ${track}` : `Show track ${track}`,
+    previewIframe,
+    writeProjectFile,
+    recordEdit,
+    domEditSaveTimestampRef,
+    pendingTimelineEditPathRef,
+  });
+}
+
+export async function toggleTimelineElementHidden({
+  projectId,
+  activeCompPath,
+  timelineElements,
+  elementKey,
+  hidden,
+  previewIframe,
+  writeProjectFile,
+  recordEdit,
+  domEditSaveTimestampRef,
+  pendingTimelineEditPathRef,
+}: ToggleTimelineElementHiddenInput): Promise<string[]> {
+  const element = timelineElements.find((item) => (item.key ?? item.id) === elementKey);
+  return setElementsHidden({
+    projectId,
+    activeCompPath,
+    elements: element ? [element] : [],
+    hidden,
+    label: hidden ? "Hide element" : "Show element",
+    previewIframe,
+    writeProjectFile,
+    recordEdit,
+    domEditSaveTimestampRef,
+    pendingTimelineEditPathRef,
+  });
+}
+
+export function useTimelineTrackVisibilityEditing({
+  projectIdRef,
+  activeCompPath,
+  showToast,
+  writeProjectFile,
+  recordEdit,
+  domEditSaveTimestampRef,
+  previewIframeRef,
+  pendingTimelineEditPathRef,
+  isRecordingRef,
+  forceReloadSdkSession,
+}: UseTimelineTrackVisibilityEditingInput): (track: number, hidden: boolean) => Promise<void> {
+  // Resolve the eye toggle against the EXPANDED rows the canvas actually renders:
+  // virtual sub-comp children carry their own (display.track + idx) track numbers,
+  // so filtering the raw store list by a virtual track number would hide the wrong
+  // outer-scene sibling sharing that index.
+  const expandedElements = useExpandedTimelineElements();
+  return useCallback(
+    async (track: number, hidden: boolean) => {
+      if (isRecordingRef?.current) {
+        showToast("Cannot edit timeline while recording", "error");
+        return;
+      }
+      const pid = projectIdRef.current;
+      if (!pid) return;
+      try {
+        await toggleTimelineTrackHidden({
+          projectId: pid,
+          activeCompPath,
+          timelineElements: expandedElements,
+          track,
+          hidden,
+          previewIframe: previewIframeRef.current,
+          writeProjectFile,
+          recordEdit,
+          domEditSaveTimestampRef,
+          pendingTimelineEditPathRef,
+        });
+        forceReloadSdkSession?.();
+      } catch (error) {
+        console.error("[Timeline] Failed to toggle track visibility", error);
+        const message =
+          error instanceof Error ? error.message : "Failed to toggle track visibility";
+        showToast(message);
+      }
+    },
+    [
+      activeCompPath,
+      expandedElements,
+      previewIframeRef,
+      writeProjectFile,
+      recordEdit,
+      domEditSaveTimestampRef,
+      pendingTimelineEditPathRef,
+      isRecordingRef,
+      showToast,
+      forceReloadSdkSession,
+      projectIdRef,
+    ],
+  );
+}
+
+export function useTimelineElementVisibilityEditing({
+  projectIdRef,
+  activeCompPath,
+  timelineElements,
+  showToast,
+  writeProjectFile,
+  recordEdit,
+  domEditSaveTimestampRef,
+  previewIframeRef,
+  pendingTimelineEditPathRef,
+  isRecordingRef,
+  forceReloadSdkSession,
+}: UseTimelineElementVisibilityEditingInput): (
+  elementKey: string,
+  hidden: boolean,
+) => Promise<void> {
+  return useCallback(
+    async (elementKey: string, hidden: boolean) => {
+      if (isRecordingRef?.current) {
+        showToast("Cannot edit timeline while recording", "error");
+        return;
+      }
+      const pid = projectIdRef.current;
+      if (!pid) return;
+      try {
+        await toggleTimelineElementHidden({
+          projectId: pid,
+          activeCompPath,
+          timelineElements,
+          elementKey,
+          hidden,
+          previewIframe: previewIframeRef.current,
+          writeProjectFile,
+          recordEdit,
+          domEditSaveTimestampRef,
+          pendingTimelineEditPathRef,
+        });
+        forceReloadSdkSession?.();
+      } catch (error) {
+        console.error("[Timeline] Failed to toggle element visibility", error);
+        const message =
+          error instanceof Error ? error.message : "Failed to toggle element visibility";
+        showToast(message);
+      }
+    },
+    [
+      activeCompPath,
+      timelineElements,
+      previewIframeRef,
+      writeProjectFile,
+      recordEdit,
+      domEditSaveTimestampRef,
+      pendingTimelineEditPathRef,
+      isRecordingRef,
+      showToast,
+      forceReloadSdkSession,
+      projectIdRef,
+    ],
+  );
+}

package/src/hooks/useRenderClipContent.test.ts

@@ -3,6 +3,7 @@
 import React, { act, isValidElement, type ReactNode } from "react";
 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 { normalizeCompositionSrc } from "./useRenderClipContent";
@@ -63,7 +64,10 @@ describe("normalizeCompositionSrc", () => {
 });
 
 describe("useRenderClipContent", () => {
-  function renderClipContent(el: TimelineElement): ReactNode {
+  function renderClipContent(
+    el: TimelineElement,
+    activePreviewUrl: string | null = "/api/projects/my-project/preview",
+  ): ReactNode {
     const host = document.createElement("div");
     document.body.append(host);
     const root = createRoot(host);
@@ -73,7 +77,7 @@ describe("useRenderClipContent", () => {
       const render = useRenderClipContent({
         projectIdRef: { current: "my-project" },
         compIdToSrc: new Map(),
-        activePreviewUrl: "/api/projects/my-project/preview",
+        activePreviewUrl,
         effectiveTimelineDuration: 12,
       });
       content = render(el, { clip: "#222", label: "#fff" });
@@ -100,4 +104,66 @@ describe("useRenderClipContent", () => {
     expect(isValidElement(content)).toBe(true);
     if (isValidElement(content)) expect(content.type).toBe(AudioWaveform);
   });
+
+  it("passes empty labels to thumbnail content so TimelineClip owns clip names", () => {
+    const cases: Array<{ content: ReactNode; type: unknown }> = [
+      {
+        content: renderClipContent({
+          id: "voiceover",
+          tag: "audio",
+          start: 1,
+          duration: 4,
+          track: 1,
+          src: "assets/voiceover.mp3",
+        }),
+        type: AudioWaveform,
+      },
+      {
+        content: renderClipContent({
+          id: "nested",
+          tag: "div",
+          start: 0,
+          duration: 4,
+          track: 0,
+          compositionSrc: "compositions/nested.html",
+        }),
+        type: CompositionThumbnail,
+      },
+      {
+        content: renderClipContent(
+          {
+            id: "clip-video",
+            tag: "video",
+            start: 0,
+            duration: 4,
+            track: 0,
+            src: "assets/clip.mp4",
+          },
+          null,
+        ),
+        type: VideoThumbnail,
+      },
+      {
+        content: renderClipContent(
+          {
+            id: "headline",
+            tag: "div",
+            start: 1,
+            duration: 4,
+            track: 0,
+          },
+          null,
+        ),
+        type: CompositionThumbnail,
+      },
+    ];
+
+    for (const item of cases) {
+      expect(isValidElement<{ label: string }>(item.content)).toBe(true);
+      if (isValidElement<{ label: string }>(item.content)) {
+        expect(item.content.type).toBe(item.type);
+        expect(item.content.props.label).toBe("");
+      }
+    }
+  });
 });

package/src/hooks/useRenderClipContent.ts

@@ -3,7 +3,6 @@ import { createElement } from "react";
 import { CompositionThumbnail, VideoThumbnail } from "../player";
 import type { TimelineElement } from "../player";
 import { AudioWaveform } from "../player/components/AudioWaveform";
-import { getTimelineElementLabel } from "../utils/studioHelpers";
 
 export function normalizeCompositionSrc(
   compSrc: string,
@@ -58,7 +57,7 @@ function renderAudioClip(el: TimelineElement, pid: string, labelColor: string):
   return createElement(AudioWaveform, {
     audioUrl,
     waveformUrl,
-    label: getTimelineElementLabel(el),
+    label: "",
     labelColor,
     trimStartFraction: start,
     trimEndFraction: end,
@@ -102,7 +101,7 @@ export function useRenderClipContent({
       if (compSrc) {
         return createElement(CompositionThumbnail, {
           previewUrl: `/api/projects/${pid}/preview/comp/${compSrc}`,
-          label: getTimelineElementLabel(el),
+          label: "",
           labelColor: style.label,
 
           seekTime: 0,
@@ -122,7 +121,7 @@ export function useRenderClipContent({
       if (activePreviewUrl && el.duration > 0) {
         return createElement(CompositionThumbnail, {
           previewUrl: activePreviewUrl,
-          label: getTimelineElementLabel(el),
+          label: "",
           labelColor: style.label,
 
           selector: el.selector,
@@ -144,7 +143,7 @@ export function useRenderClipContent({
           : `/api/projects/${pid}/preview/${el.src}`;
         return createElement(VideoThumbnail, {
           videoSrc: mediaSrc,
-          label: getTimelineElementLabel(el),
+          label: "",
           labelColor: style.label,
           duration: el.duration,
         });
@@ -153,7 +152,7 @@ export function useRenderClipContent({
       if (htmlPreviewEligible) {
         return createElement(CompositionThumbnail, {
           previewUrl: `/api/projects/${pid}/preview`,
-          label: getTimelineElementLabel(el),
+          label: "",
           labelColor: style.label,
 
           selector: el.selector,

package/src/hooks/useTimelineEditing.ts

@@ -20,7 +20,6 @@ import {
   collectHtmlIds,
   resolveDroppedAssetDuration,
 } from "../utils/studioHelpers";
-import type { EditHistoryKind } from "../utils/editHistory";
 import {
   buildPatchTarget,
   patchIframeDomTiming,
@@ -33,36 +32,12 @@ import {
   scaleGsapPositions,
 } from "./timelineEditingHelpers";
 import type { PersistTimelineEditInput } from "./timelineEditingHelpers";
+import {
+  useTimelineElementVisibilityEditing,
+  useTimelineTrackVisibilityEditing,
+} from "./timelineTrackVisibility";
 import { sdkTimingPersist } from "../utils/sdkCutover";
-import type { Composition } from "@hyperframes/sdk";
-
-// ── Types ──
-
-interface RecordEditInput {
-  label: string;
-  kind: EditHistoryKind;
-  coalesceKey?: string;
-  files: Record<string, { before: string; after: string }>;
-}
-
-interface UseTimelineEditingOptions {
-  projectId: string | null;
-  activeCompPath: string | null;
-  timelineElements: TimelineElement[];
-  showToast: (message: string, tone?: "error" | "info") => void;
-  writeProjectFile: (path: string, content: string) => Promise<void>;
-  recordEdit: (input: RecordEditInput) => Promise<void>;
-  domEditSaveTimestampRef: React.MutableRefObject<number>;
-  reloadPreview: () => void;
-  previewIframeRef: React.RefObject<HTMLIFrameElement | null>;
-  pendingTimelineEditPathRef: React.MutableRefObject<Set<string>>;
-  uploadProjectFiles: (files: Iterable<File>, dir?: string) => Promise<string[]>;
-  isRecordingRef?: React.RefObject<boolean>;
-  /** Stage 7 §3.2: SDK session for routing timing ops through setTiming. */
-  sdkSession?: Composition | null;
-  /** Resync the SDK session after a server-authoritative timeline write. */
-  forceReloadSdkSession?: () => void;
-}
+import type { UseTimelineEditingOptions } from "./useTimelineEditingTypes";
 
 // ── Hook ──
 
@@ -323,6 +298,34 @@ export function useTimelineEditing({
     ],
   );
 
+  const handleToggleTrackHidden = useTimelineTrackVisibilityEditing({
+    projectIdRef,
+    activeCompPath,
+    timelineElements,
+    showToast,
+    writeProjectFile,
+    recordEdit,
+    domEditSaveTimestampRef,
+    previewIframeRef,
+    pendingTimelineEditPathRef,
+    isRecordingRef,
+    forceReloadSdkSession,
+  });
+
+  const handleToggleElementHidden = useTimelineElementVisibilityEditing({
+    projectIdRef,
+    activeCompPath,
+    timelineElements,
+    showToast,
+    writeProjectFile,
+    recordEdit,
+    domEditSaveTimestampRef,
+    previewIframeRef,
+    pendingTimelineEditPathRef,
+    isRecordingRef,
+    forceReloadSdkSession,
+  });
+
   // fallow-ignore-next-line complexity
   const handleTimelineElementDelete = useCallback(
     // fallow-ignore-next-line complexity
@@ -562,6 +565,8 @@ export function useTimelineEditing({
   return {
     handleTimelineElementMove,
     handleTimelineElementResize,
+    handleToggleTrackHidden,
+    handleToggleElementHidden,
     handleTimelineElementDelete,
     handleTimelineElementSplit: handleRazorSplit,
     handleRazorSplit,

package/src/hooks/useTimelineEditingTypes.ts

@@ -0,0 +1,30 @@
+import type { MutableRefObject, RefObject } from "react";
+import type { Composition } from "@hyperframes/sdk";
+import type { TimelineElement } from "../player";
+import type { EditHistoryKind } from "../utils/editHistory";
+
+interface RecordEditInput {
+  label: string;
+  kind: EditHistoryKind;
+  coalesceKey?: string;
+  files: Record<string, { before: string; after: string }>;
+}
+
+export interface UseTimelineEditingOptions {
+  projectId: string | null;
+  activeCompPath: string | null;
+  timelineElements: TimelineElement[];
+  showToast: (message: string, tone?: "error" | "info") => void;
+  writeProjectFile: (path: string, content: string) => Promise<void>;
+  recordEdit: (input: RecordEditInput) => Promise<void>;
+  domEditSaveTimestampRef: MutableRefObject<number>;
+  reloadPreview: () => void;
+  previewIframeRef: RefObject<HTMLIFrameElement | null>;
+  pendingTimelineEditPathRef: MutableRefObject<Set<string>>;
+  uploadProjectFiles: (files: Iterable<File>, dir?: string) => Promise<string[]>;
+  isRecordingRef?: RefObject<boolean>;
+  /** Stage 7 §3.2: SDK session for routing timing ops through setTiming. */
+  sdkSession?: Composition | null;
+  /** Resync the SDK session after a server-authoritative timeline write. */
+  forceReloadSdkSession?: () => void;
+}

package/src/icons/SystemIcons.tsx

@@ -4,7 +4,6 @@ import {
   Eye as PhEye,
   FilmStrip,
   Stack,
-  ChatCenteredText,
   ArrowsOutCardinal,
   MusicNote,
   Palette as PhPalette,
@@ -15,7 +14,6 @@ import {
   TextT,
   X as PhX,
   Lightning,
-  CaretDown,
   CaretRight,
   ClipboardText,
   ArrowCounterClockwise,
@@ -41,7 +39,6 @@ export const Clock = makeIcon(PhClock);
 export const Eye = makeIcon(PhEye);
 export const Film = makeIcon(FilmStrip);
 export const Layers = makeIcon(Stack);
-export const MessageSquare = makeIcon(ChatCenteredText);
 export const Move = makeIcon(ArrowsOutCardinal);
 export const Music = makeIcon(MusicNote);
 export const Palette = makeIcon(PhPalette);
@@ -53,7 +50,18 @@ export const Type = makeIcon(TextT);
 export const X = makeIcon(PhX);
 export const Zap = makeIcon(Lightning);
 // Extra icons used in this project (not in lucide's default mapping above)
-export const ChevronDown = makeIcon(CaretDown);
+export const ChevronDown = ({ title, style, ...props }: IconProps) => {
+  const transform = style?.transform ? `${style.transform} rotate(90deg)` : "rotate(90deg)";
+  return (
+    <CaretRight
+      alt={title}
+      aria-label={title}
+      aria-hidden={title ? undefined : true}
+      style={{ ...style, transform }}
+      {...props}
+    />
+  );
+};
 export const ChevronRight = makeIcon(CaretRight);
 export const ClipboardList = makeIcon(ClipboardText);
 export const RotateCcw = makeIcon(ArrowCounterClockwise);