@hyperframes/studio 0.5.5 → 0.6.0-alpha.2

package/src/hooks/usePersistentEditHistory.ts

@@ -0,0 +1,337 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  buildEditHistoryEntry,
+  createEmptyEditHistory,
+  hashEditHistoryContent,
+  pushEditHistoryEntry,
+  redoEditHistory,
+  undoEditHistory,
+  type BuildEditHistoryEntryInput,
+  type EditHistoryKind,
+  type EditHistoryState,
+} from "../utils/editHistory";
+import {
+  createIndexedDbEditHistoryStorage,
+  loadEditHistoryState,
+  saveEditHistoryState,
+  type EditHistoryStorageAdapter,
+} from "../utils/editHistoryStorage";
+
+interface RecordEditInput {
+  label: string;
+  kind: EditHistoryKind;
+  coalesceKey?: string;
+  files: BuildEditHistoryEntryInput["files"];
+}
+
+interface ApplyCallbacks {
+  readFile: (path: string) => Promise<string>;
+  writeFile: (path: string, content: string) => Promise<void>;
+}
+
+interface UsePersistentEditHistoryOptions {
+  projectId: string | null;
+  storage?: EditHistoryStorageAdapter;
+  now?: () => number;
+}
+
+interface ApplyResult {
+  ok: boolean;
+  reason?: "empty" | "content-mismatch";
+  label?: string;
+  paths?: string[];
+}
+
+interface PersistentEditHistoryStoreOptions {
+  projectId: string;
+  storage: EditHistoryStorageAdapter;
+  initialState: EditHistoryState;
+  now?: () => number;
+  onChange: (state: EditHistoryState) => void;
+}
+
+type EditHistoryMutation<T> = (state: EditHistoryState) => Promise<{
+  state: EditHistoryState;
+  result: T;
+}>;
+
+function createEntryId(now: number): string {
+  return `edit-${now.toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function snapshotEditHistoryState(state: EditHistoryState) {
+  const undoEntry = state.undo[state.undo.length - 1] ?? null;
+  const redoEntry = state.redo[state.redo.length - 1] ?? null;
+  return {
+    canUndo: Boolean(undoEntry),
+    canRedo: Boolean(redoEntry),
+    undoLabel: undoEntry?.label ?? null,
+    redoLabel: redoEntry?.label ?? null,
+    undoPaths: undoEntry ? Object.keys(undoEntry.files) : [],
+    redoPaths: redoEntry ? Object.keys(redoEntry.files) : [],
+    state,
+  };
+}
+
+async function readCurrentFileHashes(
+  paths: string[],
+  readFile: (path: string) => Promise<string>,
+): Promise<{
+  currentFiles: Record<string, string>;
+  currentHashes: Record<string, string>;
+}> {
+  const currentFiles: Record<string, string> = {};
+  const currentHashes: Record<string, string> = {};
+  for (const path of paths) {
+    const content = await readFile(path);
+    currentFiles[path] = content;
+    currentHashes[path] = hashEditHistoryContent(content);
+  }
+  return { currentFiles, currentHashes };
+}
+
+async function writeFilesWithRollback({
+  files,
+  rollbackFiles,
+  writeFile,
+}: {
+  files: Record<string, string>;
+  rollbackFiles: Record<string, string>;
+  writeFile: (path: string, content: string) => Promise<void>;
+}): Promise<void> {
+  const writtenPaths: string[] = [];
+  try {
+    for (const [path, content] of Object.entries(files)) {
+      await writeFile(path, content);
+      writtenPaths.push(path);
+    }
+  } catch (error) {
+    try {
+      for (const path of writtenPaths.reverse()) {
+        await writeFile(path, rollbackFiles[path]);
+      }
+    } catch (rollbackError) {
+      throw new AggregateError(
+        [error, rollbackError],
+        "Failed to apply edit history and rollback did not complete",
+      );
+    }
+    throw error;
+  }
+}
+
+export function createPersistentEditHistoryStore({
+  projectId,
+  storage,
+  initialState,
+  now = Date.now,
+  onChange,
+}: PersistentEditHistoryStoreOptions) {
+  let state = initialState;
+  let queue = Promise.resolve();
+
+  const save = async (nextState: EditHistoryState) => {
+    state = nextState;
+    onChange(nextState);
+    try {
+      await saveEditHistoryState(storage, projectId, nextState);
+    } catch {
+      // Keep in-memory history usable when IndexedDB is unavailable.
+    }
+  };
+
+  const mutate = async <T>(mutation: EditHistoryMutation<T>): Promise<T> => {
+    const run = queue.then(async () => {
+      const { state: nextState, result } = await mutation(state);
+      if (nextState !== state) await save(nextState);
+      return result;
+    });
+    queue = run.then(
+      () => undefined,
+      () => undefined,
+    );
+    return run;
+  };
+
+  return {
+    snapshot: () => snapshotEditHistoryState(state),
+    async recordEdit(input: RecordEditInput) {
+      await mutate<void>(async (currentState) => {
+        const timestamp = now();
+        const entry = buildEditHistoryEntry({
+          ...input,
+          id: createEntryId(timestamp),
+          projectId,
+          now: timestamp,
+        });
+        return {
+          state: pushEditHistoryEntry(currentState, entry),
+          result: undefined,
+        };
+      });
+    },
+    async undo(callbacks: ApplyCallbacks): Promise<ApplyResult> {
+      return mutate<ApplyResult>(async (currentState) => {
+        const entry = currentState.undo[currentState.undo.length - 1];
+        if (!entry) {
+          return {
+            state: currentState,
+            result: { ok: false, reason: "empty" },
+          };
+        }
+        const { currentFiles, currentHashes } = await readCurrentFileHashes(
+          Object.keys(entry.files),
+          callbacks.readFile,
+        );
+        const result = undoEditHistory(currentState, currentHashes, now());
+        if (!result.ok) {
+          return {
+            state: currentState,
+            result: { ok: false, reason: result.reason },
+          };
+        }
+        await writeFilesWithRollback({
+          files: result.filesToWrite,
+          rollbackFiles: currentFiles,
+          writeFile: callbacks.writeFile,
+        });
+        return {
+          state: result.state,
+          result: { ok: true, label: result.entry.label, paths: Object.keys(result.entry.files) },
+        };
+      });
+    },
+    async redo(callbacks: ApplyCallbacks): Promise<ApplyResult> {
+      return mutate<ApplyResult>(async (currentState) => {
+        const entry = currentState.redo[currentState.redo.length - 1];
+        if (!entry) {
+          return {
+            state: currentState,
+            result: { ok: false, reason: "empty" },
+          };
+        }
+        const { currentFiles, currentHashes } = await readCurrentFileHashes(
+          Object.keys(entry.files),
+          callbacks.readFile,
+        );
+        const result = redoEditHistory(currentState, currentHashes, now());
+        if (!result.ok) {
+          return {
+            state: currentState,
+            result: { ok: false, reason: result.reason },
+          };
+        }
+        await writeFilesWithRollback({
+          files: result.filesToWrite,
+          rollbackFiles: currentFiles,
+          writeFile: callbacks.writeFile,
+        });
+        return {
+          state: result.state,
+          result: { ok: true, label: result.entry.label, paths: Object.keys(result.entry.files) },
+        };
+      });
+    },
+  };
+}
+
+export async function createPersistentEditHistoryController({
+  projectId,
+  storage,
+  now = Date.now,
+  onChange,
+}: {
+  projectId: string;
+  storage: EditHistoryStorageAdapter;
+  now?: () => number;
+  onChange: (state: EditHistoryState) => void;
+}) {
+  let state = await loadEditHistoryState(storage, projectId);
+  const store = createPersistentEditHistoryStore({
+    projectId,
+    storage,
+    initialState: state,
+    now,
+    onChange: (nextState) => {
+      state = nextState;
+      onChange(nextState);
+    },
+  });
+
+  return store;
+}
+
+export function usePersistentEditHistory(options: UsePersistentEditHistoryOptions) {
+  const storage = useMemo(
+    () => options.storage ?? createIndexedDbEditHistoryStorage(),
+    [options.storage],
+  );
+  const now = options.now ?? Date.now;
+  const [state, setState] = useState<EditHistoryState>(() => createEmptyEditHistory());
+  const [loaded, setLoaded] = useState(false);
+  const projectId = options.projectId;
+  const storeRef = useRef<ReturnType<typeof createPersistentEditHistoryStore> | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    const emptyState = createEmptyEditHistory();
+    storeRef.current = null;
+    setState(emptyState);
+    setLoaded(false);
+    if (!projectId) {
+      setLoaded(true);
+      return;
+    }
+
+    loadEditHistoryState(storage, projectId)
+      .then((loadedState) => {
+        if (cancelled) return;
+        storeRef.current = createPersistentEditHistoryStore({
+          projectId,
+          storage,
+          initialState: loadedState,
+          now,
+          onChange: setState,
+        });
+        setState(loadedState);
+      })
+      .catch(() => {
+        if (cancelled) return;
+        storeRef.current = createPersistentEditHistoryStore({
+          projectId,
+          storage,
+          initialState: emptyState,
+          now,
+          onChange: setState,
+        });
+        setState(emptyState);
+      })
+      .finally(() => {
+        if (!cancelled) setLoaded(true);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [now, projectId, storage]);
+
+  const recordEdit = useCallback(async (input: RecordEditInput) => {
+    await storeRef.current?.recordEdit(input);
+  }, []);
+
+  const undo = useCallback(async (callbacks: ApplyCallbacks): Promise<ApplyResult> => {
+    return storeRef.current?.undo(callbacks) ?? { ok: false, reason: "empty" };
+  }, []);
+
+  const redo = useCallback(async (callbacks: ApplyCallbacks): Promise<ApplyResult> => {
+    return storeRef.current?.redo(callbacks) ?? { ok: false, reason: "empty" };
+  }, []);
+
+  return {
+    loaded,
+    ...snapshotEditHistoryState(state),
+    recordEdit,
+    undo,
+    redo,
+  };
+}

package/src/icons/SystemIcons.tsx

@@ -54,6 +54,7 @@ import {
   ClipboardText,
   ArrowCounterClockwise,
   Camera as PhCamera,
+  ArrowClockwise,
   Gear,
 } from "@phosphor-icons/react";
 import type { Icon as PhosphorIcon, IconProps as PhosphorIconProps } from "@phosphor-icons/react";
@@ -129,4 +130,5 @@ export const ChevronRight = makeIcon(CaretRight);
 export const ClipboardList = makeIcon(ClipboardText);
 export const RotateCcw = makeIcon(ArrowCounterClockwise);
 export const Camera = makeIcon(PhCamera);
+export const RotateCw = makeIcon(ArrowClockwise);
 export const Settings = makeIcon(Gear);

package/src/player/components/CompositionThumbnail.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { buildCompositionThumbnailUrl } from "./CompositionThumbnail";
+
+describe("buildCompositionThumbnailUrl", () => {
+  it("includes selector and occurrence index for precise element thumbnails", () => {
+    expect(
+      buildCompositionThumbnailUrl({
+        previewUrl: "/api/projects/demo/preview",
+        seekTime: 1,
+        duration: 2,
+        selector: ".card",
+        selectorIndex: 2,
+        origin: "http://localhost:3000",
+      }),
+    ).toBe(
+      "http://localhost:3000/api/projects/demo/thumbnail/index.html?t=2.00&v=v3&selector=.card&selectorIndex=2",
+    );
+  });
+});

package/src/player/components/CompositionThumbnail.tsx

@@ -7,6 +7,7 @@ interface CompositionThumbnailProps {
   labelColor: string;
   accentColor?: string;
   selector?: string;
+  selectorIndex?: number;
   seekTime?: number;
   duration?: number;
   width?: number;
@@ -14,7 +15,39 @@ interface CompositionThumbnailProps {
 }
 
 const CLIP_HEIGHT = 66;
-const THUMBNAIL_URL_VERSION = "v2";
+const THUMBNAIL_URL_VERSION = "v3";
+export const COMPOSITION_THUMBNAIL_LABEL_Z_INDEX = 10;
+
+export function buildCompositionThumbnailUrl({
+  previewUrl,
+  seekTime = 2,
+  duration = 5,
+  selector,
+  selectorIndex,
+  origin,
+}: {
+  previewUrl: string;
+  seekTime?: number;
+  duration?: number;
+  selector?: string;
+  selectorIndex?: number;
+  origin: string;
+}): string {
+  const thumbnailBase = previewUrl
+    .replace("/preview/comp/", "/thumbnail/")
+    .replace(/\/preview$/, "/thumbnail/index.html");
+  const midTime = seekTime + duration / 2;
+  const thumbnailUrl = new URL(thumbnailBase, origin);
+  thumbnailUrl.searchParams.set("t", midTime.toFixed(2));
+  thumbnailUrl.searchParams.set("v", THUMBNAIL_URL_VERSION);
+  if (selector) {
+    thumbnailUrl.searchParams.set("selector", selector);
+    if (selectorIndex != null && selectorIndex > 0) {
+      thumbnailUrl.searchParams.set("selectorIndex", String(selectorIndex));
+    }
+  }
+  return thumbnailUrl.toString();
+}
 
 export const CompositionThumbnail = memo(function CompositionThumbnail({
   previewUrl,
@@ -22,6 +55,7 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
   labelColor,
   accentColor = "#6B7280",
   selector,
+  selectorIndex,
   seekTime = 2,
   duration = 5,
 }: CompositionThumbnailProps) {
@@ -48,15 +82,14 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
     roRef.current?.disconnect();
   });
 
-  const thumbnailBase = previewUrl
-    .replace("/preview/comp/", "/thumbnail/")
-    .replace(/\/preview$/, "/thumbnail/index.html");
-  const midTime = seekTime + duration / 2;
-  const thumbnailUrl = new URL(thumbnailBase, window.location.origin);
-  thumbnailUrl.searchParams.set("t", midTime.toFixed(2));
-  thumbnailUrl.searchParams.set("v", THUMBNAIL_URL_VERSION);
-  if (selector) thumbnailUrl.searchParams.set("selector", selector);
-  const url = thumbnailUrl.toString();
+  const url = buildCompositionThumbnailUrl({
+    previewUrl,
+    seekTime,
+    duration,
+    selector,
+    selectorIndex,
+    origin: window.location.origin,
+  });
   const frameW = Math.max(48, Math.round(CLIP_HEIGHT * aspect));
   const frameCount = containerWidth > 0 ? Math.max(1, Math.ceil(containerWidth / frameW)) : 1;
 
@@ -66,7 +99,7 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
         src={url}
         alt=""
         draggable={false}
-        loading="lazy"
+        loading="eager"
         onLoad={(e) => {
           const img = e.currentTarget;
           if (img.naturalWidth > 0 && img.naturalHeight > 0) {
@@ -111,7 +144,10 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
         }}
       />
 
-      <div className="absolute left-2 top-2 z-10">
+      <div
+        className="absolute left-2 top-2"
+        style={{ zIndex: COMPOSITION_THUMBNAIL_LABEL_Z_INDEX }}
+      >
         <span
           className="block max-w-full truncate rounded-md px-1.5 py-0.5 text-[9px] font-semibold uppercase leading-none"
           style={{
@@ -125,8 +161,9 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
       </div>
 
       <div
-        className="absolute bottom-0 left-0 right-0 z-10 px-1.5 pb-0.5 pt-3"
+        className="absolute bottom-0 left-0 right-0 px-1.5 pb-0.5 pt-3"
         style={{
+          zIndex: COMPOSITION_THUMBNAIL_LABEL_Z_INDEX,
           background:
             "linear-gradient(to top, rgba(0,0,0,0.85) 0%, rgba(0,0,0,0.4) 60%, transparent 100%)",
         }}

package/src/player/components/EditModal.tsx

@@ -3,6 +3,7 @@ import { useMountEffect } from "../../hooks/useMountEffect";
 import { usePlayerStore } from "../store/playerStore";
 import { formatTime } from "../lib/time";
 import { buildPromptCopyText, buildTimelineAgentPrompt } from "./timelineEditing";
+import { copyTextToClipboard } from "../../utils/clipboard";
 
 interface EditPopoverProps {
   rangeStart: number;
@@ -62,16 +63,8 @@ export function EditPopover({ rangeStart, rangeEnd, anchorX, anchorY, onClose }:
   }, [start, end, elementsInRange, prompt]);
 
   const handleCopy = useCallback(async () => {
-    try {
-      await navigator.clipboard.writeText(buildClipboardText());
-    } catch {
-      const ta = document.createElement("textarea");
-      ta.value = buildClipboardText();
-      document.body.appendChild(ta);
-      ta.select();
-      document.execCommand("copy");
-      document.body.removeChild(ta);
-    }
+    const copied = await copyTextToClipboard(buildClipboardText());
+    if (!copied) return;
     setCopiedAgentPrompt(true);
     setTimeout(() => {
       setCopiedAgentPrompt(false);
@@ -82,16 +75,8 @@ export function EditPopover({ rangeStart, rangeEnd, anchorX, anchorY, onClose }:
   const handleCopyPrompt = useCallback(async () => {
     const promptText = buildPromptCopyText(prompt);
     if (!promptText) return;
-    try {
-      await navigator.clipboard.writeText(promptText);
-    } catch {
-      const ta = document.createElement("textarea");
-      ta.value = promptText;
-      document.body.appendChild(ta);
-      ta.select();
-      document.execCommand("copy");
-      document.body.removeChild(ta);
-    }
+    const copied = await copyTextToClipboard(promptText);
+    if (!copied) return;
     setCopiedPromptOnly(true);
     setTimeout(() => {
       setCopiedPromptOnly(false);

package/src/player/components/Player.tsx

@@ -11,6 +11,7 @@ interface PlayerProps {
   directUrl?: string;
   onLoad: () => void;
   portrait?: boolean;
+  style?: React.CSSProperties;
 }
 
 interface HyperframesPlayerElement extends HTMLElement {
@@ -30,6 +31,17 @@ function getShaderTransitionLoading(event: Event): boolean | null {
   return state.loading === true && state.ready !== true;
 }
 
+function enableInteractiveIframe(player: HyperframesPlayerElement): void {
+  const root = player.shadowRoot;
+  if (!root) return;
+
+  const container = root.querySelector<HTMLElement>(".hfp-container");
+  const iframe = root.querySelector<HTMLIFrameElement>(".hfp-iframe");
+
+  container?.style.setProperty("pointer-events", "auto");
+  iframe?.style.setProperty("pointer-events", "auto");
+}
+
 // Assets are considered ready when every `<video>`/`<audio>` has enough data
 // to play through without buffering, and every registered Lottie animation has
 // finished loading.
@@ -72,7 +84,7 @@ function hasUnloadedAssets(iframe: HTMLIFrameElement, lastResult: boolean): bool
  * timeline probing, and DOM inspection.
  */
 export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
-  ({ projectId, directUrl, onLoad, portrait }, ref) => {
+  ({ projectId, directUrl, onLoad, portrait, style }, ref) => {
     const containerRef = useRef<HTMLDivElement>(null);
     const loadCountRef = useRef(0);
     const assetPollRef = useRef<ReturnType<typeof setInterval> | null>(null);
@@ -105,6 +117,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
         player.style.height = "100%";
         player.style.display = "block";
         container.appendChild(player);
+        enableInteractiveIframe(player);
 
         // Bridge the inner iframe to the forwarded ref for useTimelinePlayer.
         const iframe = player.iframeElement;
@@ -227,7 +240,10 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
     const showAssetOverlay = assetOverlayVisible && !shaderTransitionLoading;
 
     return (
-      <div className="relative w-full h-full max-w-full max-h-full overflow-hidden bg-black flex items-center justify-center">
+      <div
+        className="relative w-full h-full max-w-full max-h-full overflow-hidden bg-black flex items-center justify-center"
+        style={style}
+      >
         <div ref={containerRef} className="w-full h-full" />
         {showAssetOverlay && (
           <div

package/src/player/components/Timeline.test.ts

@@ -8,9 +8,12 @@ import {
   getTimelinePlayheadLeft,
   getTimelineScrollLeftForZoomAnchor,
   getTimelineScrollLeftForZoomTransition,
+  shouldShowTimelineShortcutHint,
   shouldHandleTimelineDeleteKey,
   shouldAutoScrollTimeline,
 } from "./Timeline";
+import { TIMELINE_CLIP_CONTROL_Z_INDEX } from "./TimelineClip";
+import { COMPOSITION_THUMBNAIL_LABEL_Z_INDEX } from "./CompositionThumbnail";
 import { formatTime } from "../lib/time";
 
 describe("generateTicks", () => {
@@ -163,6 +166,12 @@ describe("shouldAutoScrollTimeline", () => {
   });
 });
 
+describe("timeline clip controls", () => {
+  it("renders layer controls above composition thumbnail chrome", () => {
+    expect(TIMELINE_CLIP_CONTROL_Z_INDEX).toBeGreaterThan(COMPOSITION_THUMBNAIL_LABEL_Z_INDEX);
+  });
+});
+
 describe("getTimelineScrollLeftForZoomTransition", () => {
   it("resets horizontal scroll when switching from manual zoom back to fit", () => {
     expect(getTimelineScrollLeftForZoomTransition("manual", "fit", 480)).toBe(0);
@@ -237,6 +246,17 @@ describe("getTimelineCanvasHeight", () => {
   });
 });
 
+describe("shouldShowTimelineShortcutHint", () => {
+  it("shows the hint when the timeline does not vertically overflow", () => {
+    expect(shouldShowTimelineShortcutHint(220, 220)).toBe(true);
+    expect(shouldShowTimelineShortcutHint(220.5, 220)).toBe(true);
+  });
+
+  it("hides the hint when timeline tracks need vertical scrolling", () => {
+    expect(shouldShowTimelineShortcutHint(221.5, 220)).toBe(false);
+  });
+});
+
 describe("shouldHandleTimelineDeleteKey", () => {
   it("handles Delete and Backspace when focus is not in an editor", () => {
     expect(shouldHandleTimelineDeleteKey({ key: "Delete" })).toBe(true);