@hyperframes/studio 0.7.38 → 0.7.40

package/src/hooks/timelineTrackVisibility.test.ts

@@ -0,0 +1,202 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore, type TimelineElement } from "../player";
+import { toggleTimelineElementHidden, toggleTimelineTrackHidden } from "./timelineTrackVisibility";
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  vi.unstubAllGlobals();
+  usePlayerStore.getState().reset();
+});
+
+function element(overrides: Partial<TimelineElement>): TimelineElement {
+  return {
+    id: "clip",
+    tag: "div",
+    start: 0,
+    duration: 2,
+    track: 0,
+    ...overrides,
+  };
+}
+
+function stubProjectFiles(files: Map<string, string>) {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      const encodedPath = url.slice(url.lastIndexOf("/") + 1);
+      const path = decodeURIComponent(encodedPath);
+      const content = files.get(path);
+      return new Response(JSON.stringify({ content }), {
+        status: content === undefined ? 404 : 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }),
+  );
+}
+
+describe("toggleTimelineTrackHidden", () => {
+  it("patches iframe DOM and persists all track elements as one edit-history entry", async () => {
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    if (iframe.contentDocument) {
+      iframe.contentDocument.body.innerHTML = `
+        <div id="hero"></div>
+        <div id="subtitle"></div>
+      `;
+    }
+
+    const files = new Map([
+      [
+        "index.html",
+        `<div id="hero" data-start="0" data-duration="2"></div>
+<div id="skip" data-start="0" data-duration="2"></div>`,
+      ],
+      ["scene.html", `<div id="subtitle" data-start="1" data-duration="2"></div>`],
+    ]);
+    stubProjectFiles(files);
+
+    const writes = new Map<string, string>();
+    const recordEdit = vi.fn();
+    const timestampRef = { current: 0 };
+    const pendingRef = { current: new Set<string>() };
+
+    await toggleTimelineTrackHidden({
+      projectId: "project-1",
+      activeCompPath: "index.html",
+      timelineElements: [
+        element({ id: "hero", domId: "hero", track: 0 }),
+        element({ id: "skip", domId: "skip", track: 1 }),
+        element({ id: "subtitle", domId: "subtitle", track: 0, sourceFile: "scene.html" }),
+      ],
+      track: 0,
+      hidden: true,
+      previewIframe: iframe,
+      writeProjectFile: async (path, content) => {
+        writes.set(path, content);
+      },
+      recordEdit,
+      domEditSaveTimestampRef: timestampRef,
+      pendingTimelineEditPathRef: pendingRef,
+    });
+
+    expect(iframe.contentDocument?.getElementById("hero")?.hasAttribute("data-hidden")).toBe(true);
+    expect(iframe.contentDocument?.getElementById("subtitle")?.hasAttribute("data-hidden")).toBe(
+      true,
+    );
+    expect(writes.get("index.html")).toContain('id="hero" data-start="0" data-duration="2"');
+    expect(writes.get("index.html")).toContain('data-hidden=""');
+    expect(writes.get("index.html")).toContain('id="skip" data-start="0" data-duration="2"');
+    expect(writes.get("scene.html")).toContain('data-hidden=""');
+    expect(pendingRef.current).toEqual(new Set(["index.html", "scene.html"]));
+    expect(timestampRef.current).toBeGreaterThan(0);
+    expect(recordEdit).toHaveBeenCalledTimes(1);
+    expect(recordEdit.mock.calls[0]?.[0]?.label).toBe("Hide track 0");
+    expect(Object.keys(recordEdit.mock.calls[0]?.[0]?.files ?? {}).sort()).toEqual([
+      "index.html",
+      "scene.html",
+    ]);
+  });
+
+  it("removes data-hidden from every element on the track", async () => {
+    const files = new Map([
+      [
+        "index.html",
+        `<div id="hero" data-start="0" data-duration="2" data-hidden=""></div>
+<div id="caption" data-start="2" data-duration="2" data-hidden=""></div>`,
+      ],
+    ]);
+    stubProjectFiles(files);
+
+    const writes = new Map<string, string>();
+
+    await toggleTimelineTrackHidden({
+      projectId: "project-1",
+      activeCompPath: "index.html",
+      timelineElements: [
+        element({ id: "hero", domId: "hero", track: 0, hidden: true }),
+        element({ id: "caption", domId: "caption", track: 0, hidden: true }),
+      ],
+      track: 0,
+      hidden: false,
+      previewIframe: null,
+      writeProjectFile: async (path, content) => {
+        writes.set(path, content);
+      },
+      recordEdit: vi.fn(),
+      domEditSaveTimestampRef: { current: 0 },
+      pendingTimelineEditPathRef: { current: new Set() },
+    });
+
+    expect(writes.get("index.html")).not.toContain("data-hidden");
+  });
+});
+
+describe("toggleTimelineElementHidden", () => {
+  it("persists data-hidden for only the selected element and updates the player store", async () => {
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    const seek = vi.fn();
+    const win = iframe.contentWindow;
+    if (!win) throw new Error("Expected iframe contentWindow");
+    const playerWindow: Window & { __player?: { seek?: (time: number) => void } } = win;
+    playerWindow.__player = { seek };
+
+    const files = new Map([
+      [
+        "index.html",
+        `<div id="hero" data-start="0" data-duration="2"></div>
+<div id="track-mate" data-start="1" data-duration="2"></div>`,
+      ],
+    ]);
+    stubProjectFiles(files);
+
+    const hero = element({ id: "hero", key: "index.html:#hero", domId: "hero", track: 0 });
+    const trackMate = element({
+      id: "track-mate",
+      key: "index.html:#track-mate",
+      domId: "track-mate",
+      track: 0,
+    });
+    usePlayerStore.getState().setElements([hero, trackMate]);
+    usePlayerStore.getState().setCurrentTime(1.25);
+
+    const writes = new Map<string, string>();
+    const recordEdit = vi.fn();
+
+    const changedPaths = await toggleTimelineElementHidden({
+      projectId: "project-1",
+      activeCompPath: "index.html",
+      timelineElements: [hero, trackMate],
+      elementKey: "index.html:#hero",
+      hidden: true,
+      previewIframe: iframe,
+      writeProjectFile: async (path, content) => {
+        writes.set(path, content);
+      },
+      recordEdit,
+      domEditSaveTimestampRef: { current: 0 },
+      pendingTimelineEditPathRef: { current: new Set() },
+    });
+
+    expect(changedPaths).toEqual(["index.html"]);
+    expect(writes.get("index.html")).toContain('id="hero" data-start="0" data-duration="2"');
+    expect(writes.get("index.html")).toContain(
+      'id="hero" data-start="0" data-duration="2" data-hidden=""',
+    );
+    expect(writes.get("index.html")).toContain(
+      'id="track-mate" data-start="1" data-duration="2"></div>',
+    );
+    expect(recordEdit).toHaveBeenCalledTimes(1);
+    expect(recordEdit.mock.calls[0]?.[0]?.label).toBe("Hide element");
+    expect(seek).toHaveBeenCalledWith(1.25);
+    expect(
+      usePlayerStore.getState().elements.find((el) => el.key === "index.html:#hero")?.hidden,
+    ).toBe(true);
+    expect(
+      usePlayerStore.getState().elements.find((el) => el.key === "index.html:#track-mate")?.hidden,
+    ).toBeUndefined();
+  });
+});

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/useCropMode.ts

@@ -0,0 +1,91 @@
+import { useEffect, useMemo, useReducer } from "react";
+import { usePlayerStore } from "../player";
+
+export interface CropModeProps {
+  cropMode: boolean;
+  onCropModeChange: (active: boolean) => void;
+}
+
+/** Crop mode lives in the player store so the canvas toolbar, the Clip panel,
+ *  and the overlay all share one switch without prop threading. */
+export function useCropModeProps(): CropModeProps {
+  const cropMode = usePlayerStore((s) => s.cropMode);
+  const setCropMode = usePlayerStore((s) => s.setCropMode);
+  return useMemo(
+    () => ({
+      cropMode,
+      onCropModeChange: setCropMode,
+    }),
+    [cropMode, setCropMode],
+  );
+}
+
+import type { OverlayRect } from "../components/editor/domEditOverlayGeometry";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import { readElementCropInsets } from "../components/editor/domEditOverlayCrop";
+
+/** Overlay-side crop state: Escape-to-exit, toolbar availability publishing,
+ *  and the box clip that makes the selection outline hug the cropped region.
+ *  The box div itself always sits at the FULL element bounds — gestures write
+ *  its position directly during drags, so moving/resizing it in React would
+ *  fight them. The hug is purely visual: the element's inset clip-path scaled
+ *  into overlay space and applied to the box. */
+export function useCropOverlay(params: {
+  selection: DomEditSelection | null;
+  groupCount: number;
+  cropMode: boolean;
+  onCropModeChange?: (active: boolean) => void;
+  overlayRect: OverlayRect | null;
+}) {
+  const { selection, groupCount, cropMode, onCropModeChange, overlayRect } = params;
+
+  useEffect(() => {
+    if (!cropMode || !onCropModeChange) return;
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") onCropModeChange(false);
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [cropMode, onCropModeChange]);
+
+  // Publish availability so the canvas toolbar shows the Crop button only
+  // when the selection can take a clip-path crop.
+  const setCropAvailable = usePlayerStore((s) => s.setCropAvailable);
+  const cropAvailable = Boolean(selection && groupCount <= 1 && selection.capabilities.canCrop);
+  useEffect(() => {
+    setCropAvailable(cropAvailable);
+    return () => setCropAvailable(false);
+  }, [cropAvailable, setCropAvailable]);
+
+  // Crop-mode exit restores the element's clip in an effect cleanup — after
+  // this hook already read it. One forced re-render picks up the fresh insets
+  // so the selection box hugs the crop immediately.
+  const [, bumpAfterExit] = useReducer((x: number) => x + 1, 0);
+  useEffect(() => {
+    if (!cropMode) bumpAfterExit();
+  }, [cropMode]);
+
+  const cropInsets = selection ? readElementCropInsets(selection.element) : null;
+  const hasCropInsets = Boolean(
+    cropInsets &&
+    (cropInsets.top > 0 || cropInsets.right > 0 || cropInsets.bottom > 0 || cropInsets.left > 0),
+  );
+
+  // Scaled insets for the crop outline child + the resize-handle shift. The
+  // box div itself stays border-less at full bounds; a child draws the
+  // outline ON the crop boundary (a clip on the box would swallow the
+  // border everywhere the crop edge doesn't touch the element edge).
+  const sx = overlayRect && overlayRect.editScaleX > 0 ? overlayRect.editScaleX : 1;
+  const sy = overlayRect && overlayRect.editScaleY > 0 ? overlayRect.editScaleY : 1;
+  const cropOutlineInsetPx =
+    cropInsets && hasCropInsets && !cropMode
+      ? {
+          top: cropInsets.top * sy,
+          right: cropInsets.right * sx,
+          bottom: cropInsets.bottom * sy,
+          left: cropInsets.left * sx,
+        }
+      : undefined;
+
+  return { hasCropInsets, cropOutlineInsetPx };
+}

package/src/hooks/useDomEditCommits.test.tsx

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication
 // @vitest-environment happy-dom
 import { act, createElement } from "react";
 import { createRoot, type Root } from "react-dom/client";
@@ -183,6 +184,7 @@ function createSelection(
     capabilities: {
       canSelect: true,
       canEditStyles: true,
+      canCrop: true,
       canMove: true,
       canResize: true,
       canApplyManualOffset: true,