@hyperframes/studio 0.5.0-alpha.10 → 0.5.0-alpha.12

package/src/hooks/usePersistentEditHistory.ts

@@ -0,0 +1,336 @@
+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;
+}
+
+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 },
+        };
+      });
+    },
+    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 },
+        };
+      });
+    },
+  };
+}
+
+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

@@ -53,6 +53,8 @@ import {
   CaretRight,
   ClipboardText,
   ArrowCounterClockwise,
+  Camera as PhCamera,
+  ArrowClockwise,
   Gear,
 } from "@phosphor-icons/react";
 import type { Icon as PhosphorIcon, IconProps as PhosphorIconProps } from "@phosphor-icons/react";
@@ -127,4 +129,6 @@ export const ChevronDown = makeIcon(CaretDown);
 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/PlayerControls.tsx

@@ -1,10 +1,6 @@
 import { useRef, useState, useCallback, useEffect, memo } from "react";
 import { useMountEffect } from "../../hooks/useMountEffect";
-import {
-  TIMELINE_TOGGLE_SHORTCUT_LABEL,
-  getTimelineToggleTitle,
-} from "../../utils/timelineDiscovery";
-import { formatFrameTime, frameToSeconds, formatTime } from "../lib/time";
+import { formatFrameTime, frameToSeconds, stepFrameTime, formatTime } from "../lib/time";
 import { usePlayerStore, liveTime } from "../store/playerStore";
 
 const SPEED_OPTIONS = [0.25, 0.5, 1, 1.5, 2] as const;
@@ -30,15 +26,11 @@ export function resolveSeekPercent(clientX: number, rectLeft: number, rectWidth:
 interface PlayerControlsProps {
   onTogglePlay: () => void;
   onSeek: (time: number) => void;
-  timelineVisible?: boolean;
-  onToggleTimeline?: () => void;
 }
 
 export const PlayerControls = memo(function PlayerControls({
   onTogglePlay,
   onSeek,
-  timelineVisible,
-  onToggleTimeline,
 }: PlayerControlsProps) {
   // Subscribe to only the fields we render — each selector prevents cascading re-renders
   const isPlaying = usePlayerStore((s) => s.isPlaying);
@@ -216,10 +208,10 @@ export const PlayerControls = memo(function PlayerControls({
       const step = e.shiftKey ? 10 : 1;
       if (e.key === "ArrowLeft") {
         e.preventDefault();
-        onSeek(Math.max(0, currentTimeRef.current - frameToSeconds(step)));
+        onSeek(stepFrameTime(currentTimeRef.current, -step));
       } else if (e.key === "ArrowRight") {
         e.preventDefault();
-        onSeek(Math.min(duration, currentTimeRef.current + frameToSeconds(step)));
+        onSeek(Math.min(duration, stepFrameTime(currentTimeRef.current, step)));
       }
     },
     [timelineReady, duration, onSeek],
@@ -437,39 +429,6 @@ export const PlayerControls = memo(function PlayerControls({
           </span>
         ))}
       </div>
-
-      {/* Timeline toggle */}
-      {onToggleTimeline !== undefined && (
-        <button
-          type="button"
-          onClick={onToggleTimeline}
-          className={`h-7 flex items-center gap-1.5 rounded-md border px-2.5 text-[11px] font-medium transition-colors ${
-            timelineVisible
-              ? "text-studio-accent bg-studio-accent/10 border-studio-accent/30"
-              : "border-neutral-700 text-neutral-300 hover:border-neutral-500 hover:bg-neutral-800"
-          }`}
-          title={getTimelineToggleTitle(Boolean(timelineVisible))}
-          aria-label={timelineVisible ? "Hide timeline editor" : "Show timeline editor"}
-        >
-          <svg
-            width="13"
-            height="13"
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            strokeWidth="2"
-            strokeLinecap="round"
-          >
-            <rect x="3" y="13" width="18" height="8" rx="1" />
-            <line x1="3" y1="9" x2="21" y2="9" />
-            <line x1="3" y1="5" x2="21" y2="5" />
-          </svg>
-          <span>Timeline</span>
-          <span className="hidden md:inline rounded bg-black/20 px-1 py-0.5 text-[9px] font-mono opacity-70">
-            {TIMELINE_TOGGLE_SHORTCUT_LABEL}
-          </span>
-        </button>
-      )}
     </div>
   );
 });

package/src/player/components/Timeline.tsx

@@ -1046,7 +1046,10 @@ export const Timeline = memo(function Timeline({
 
   const getPreviewElement = useCallback(
     (element: TimelineElement): TimelineElement => {
-      if (resizingClip?.element.id === element.id) {
+      if (
+        resizingClip &&
+        (resizingClip.element.key ?? resizingClip.element.id) === (element.key ?? element.id)
+      ) {
         return {
           ...element,
           start: resizingClip.previewStart,
@@ -1273,7 +1276,7 @@ export const Timeline = memo(function Timeline({
     draggedClip?.started === true && draggedElement
       ? getRenderedTimelineElement({
           element: draggedElement,
-          draggedElementId: draggedElement.id,
+          draggedElementId: draggedElement.key ?? draggedElement.id,
           previewStart: draggedClip.previewStart,
           previewTrack: draggedClip.previewTrack,
         })

package/src/player/components/TimelineClip.tsx

@@ -61,6 +61,7 @@ export const TimelineClip = memo(function TimelineClip({
         ? theme.clipShadowHover
         : theme.clipShadow;
   const capabilities = getTimelineEditCapabilities(el);
+  const displayLabel = el.label || el.id || el.tag;
   const showHandles = handleOpacity > 0.01;
   const baseBackgroundImage = isSelected ? theme.clipBackgroundActive : theme.clipBackground;
   const glossBackgroundImage = isSelected
@@ -106,7 +107,7 @@ export const TimelineClip = memo(function TimelineClip({
       title={
         isComposition
           ? `${el.compositionSrc} \u2022 Double-click to open`
-          : `${el.id || el.tag} \u2022 ${el.start.toFixed(1)}s \u2013 ${(el.start + el.duration).toFixed(1)}s`
+          : `${displayLabel} \u2022 ${el.start.toFixed(1)}s \u2013 ${(el.start + el.duration).toFixed(1)}s`
       }
       onPointerEnter={onHoverStart}
       onPointerLeave={onHoverEnd}

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

@@ -53,4 +53,23 @@ describe("getRenderedTimelineElement", () => {
       }),
     ).toEqual({ ...element, start: 2.4, track: 3 });
   });
+
+  it("uses key before id when matching the dragged clip", () => {
+    const element = {
+      id: "Card",
+      key: "index.html:.card:1",
+      tag: "div",
+      start: 1,
+      duration: 2,
+      track: 0,
+    };
+    expect(
+      getRenderedTimelineElement({
+        element,
+        draggedElementId: "index.html:.card:1",
+        previewStart: 2.4,
+        previewTrack: 3,
+      }),
+    ).toEqual({ ...element, start: 2.4, track: 3 });
+  });
 });

package/src/player/components/timelineTheme.ts

@@ -63,12 +63,12 @@ const TRACK_STYLES: Record<string, TimelineTrackStyle> = {
 const DEFAULT_TRACK_STYLE: TimelineTrackStyle = createTrackStyle();
 
 export const defaultTimelineTheme: TimelineTheme = {
-  shellBackground: "#0A0E15",
+  shellBackground: "#0A0A0B",
   shellBorder: "rgba(255,255,255,0.05)",
   rulerBorder: "rgba(255,255,255,0.045)",
-  rowBackground: "#0A0E15",
+  rowBackground: "#0A0A0B",
   rowBorder: "rgba(255,255,255,0.05)",
-  gutterBackground: "#0D121B",
+  gutterBackground: "#0A0A0B",
   gutterBorder: "rgba(255,255,255,0.05)",
   textPrimary: "#E8EDF5",
   textSecondary: "#8391A8",
@@ -130,7 +130,11 @@ export function getRenderedTimelineElement({
   previewStart: number | null;
   previewTrack: number | null;
 }): TimelineElement {
-  if (element.id !== draggedElementId || previewStart === null || previewTrack === null) {
+  if (
+    (element.key ?? element.id) !== draggedElementId ||
+    previewStart === null ||
+    previewTrack === null
+  ) {
     return element;
   }
   return {

package/src/player/hooks/useTimelinePlayer.test.ts

@@ -2,8 +2,10 @@ import { describe, expect, it } from "vitest";
 import { Window } from "happy-dom";
 import {
   buildStandaloneRootTimelineElement,
+  createTimelineElementFromManifestClip,
   findTimelineDomNodeForClip,
   getTimelineElementSelector,
+  parseTimelineFromDOM,
   type ClipManifestClip,
   mergeTimelineElementsPreservingDowngrades,
   resolveStandaloneRootCompositionSrc,
@@ -66,6 +68,7 @@ describe("buildStandaloneRootTimelineElement", () => {
       }),
     ).toEqual({
       id: "hero",
+      label: "hero",
       key: 'scenes/hero.html:[data-composition-id="hero"]:0',
       tag: "div",
       start: 0,
@@ -146,6 +149,83 @@ describe("findTimelineDomNodeForClip", () => {
   });
 });
 
+describe("anonymous timeline identity", () => {
+  it("keeps fallback-parsed anonymous clips distinct when labels match", () => {
+    const doc = createDocument(`
+      <div data-composition-id="main" data-start="0" data-duration="8">
+        <div class="clip card" data-label="Card" data-start="0" data-duration="3" data-track-index="0"></div>
+        <div class="clip card" data-label="Card" data-start="3" data-duration="3" data-track-index="1"></div>
+      </div>
+    `);
+
+    const elements = parseTimelineFromDOM(doc, 8);
+
+    expect(elements).toHaveLength(2);
+    expect(elements.map((element) => element.label)).toEqual(["Card", "Card"]);
+    expect(new Set(elements.map((element) => element.id)).size).toBe(2);
+    expect(new Set(elements.map((element) => element.key)).size).toBe(2);
+    expect(elements.map((element) => element.selectorIndex)).toEqual([0, 1]);
+  });
+
+  it("keeps runtime-manifest anonymous clips distinct when labels match", () => {
+    const doc = createDocument(`
+      <div data-composition-id="main" data-start="0" data-duration="8">
+        <div class="clip card" data-start="0" data-duration="3" data-track-index="0"></div>
+        <div class="clip card" data-start="3" data-duration="3" data-track-index="1"></div>
+      </div>
+    `);
+    const clips = [
+      createClip({ id: null, label: "Card", start: 0, duration: 3, track: 0 }),
+      createClip({ id: null, label: "Card", start: 3, duration: 3, track: 1 }),
+    ];
+    const used = new Set<Element>();
+    const elements = clips.map((clip, index) => {
+      const hostEl = findTimelineDomNodeForClip(doc, clip, index, used);
+      if (hostEl) used.add(hostEl);
+      return createTimelineElementFromManifestClip({
+        clip,
+        fallbackIndex: index,
+        doc,
+        hostEl,
+      });
+    });
+
+    expect(elements.map((element) => element.label)).toEqual(["Card", "Card"]);
+    expect(new Set(elements.map((element) => element.id)).size).toBe(2);
+    expect(new Set(elements.map((element) => element.key)).size).toBe(2);
+    expect(elements.map((element) => element.selectorIndex)).toEqual([0, 1]);
+  });
+
+  it("reads media metadata from owner-window media elements", () => {
+    const doc = createDocument(`
+      <div data-composition-id="main" data-start="0" data-duration="8">
+        <div class="clip video-card" data-start="0" data-duration="3" data-track-index="0">
+          <video src="/clip.mp4" data-source-duration="12"></video>
+        </div>
+      </div>
+    `);
+    const hostEl = doc.querySelector(".video-card");
+    const video = hostEl?.querySelector("video");
+    if (!hostEl || !video) throw new Error("missing video test fixture");
+    Object.defineProperty(video, "defaultPlaybackRate", {
+      value: 1.5,
+      configurable: true,
+    });
+
+    const element = createTimelineElementFromManifestClip({
+      clip: createClip({ kind: "video", tagName: "div" }),
+      fallbackIndex: 0,
+      doc,
+      hostEl,
+    });
+
+    expect(element.tag).toBe("video");
+    expect(element.src).toBe("/clip.mp4");
+    expect(element.sourceDuration).toBe(12);
+    expect(element.playbackRate).toBe(1.5);
+  });
+});
+
 describe("mergeTimelineElementsPreservingDowngrades", () => {
   it("preserves missing current elements when a shorter manifest arrives", () => {
     expect(
@@ -174,6 +254,65 @@ describe("mergeTimelineElementsPreservingDowngrades", () => {
       ),
     ).toEqual([{ id: "hero", tag: "div", start: 0, duration: 4, track: 0 }]);
   });
+
+  it("preserves distinct anonymous clips that share the same friendly id label", () => {
+    expect(
+      mergeTimelineElementsPreservingDowngrades(
+        [
+          {
+            id: "Card",
+            key: "index.html:.card:0",
+            label: "Card",
+            tag: "div",
+            start: 0,
+            duration: 3,
+            track: 0,
+          },
+          {
+            id: "Card",
+            key: "index.html:.card:1",
+            label: "Card",
+            tag: "div",
+            start: 3,
+            duration: 3,
+            track: 1,
+          },
+        ],
+        [
+          {
+            id: "Card",
+            key: "index.html:.card:0",
+            label: "Card",
+            tag: "div",
+            start: 0,
+            duration: 3,
+            track: 0,
+          },
+        ],
+        8,
+        8,
+      ),
+    ).toEqual([
+      {
+        id: "Card",
+        key: "index.html:.card:0",
+        label: "Card",
+        tag: "div",
+        start: 0,
+        duration: 3,
+        track: 0,
+      },
+      {
+        id: "Card",
+        key: "index.html:.card:1",
+        label: "Card",
+        tag: "div",
+        start: 3,
+        duration: 3,
+        track: 1,
+      },
+    ]);
+  });
 });
 
 describe("shouldIgnorePlaybackShortcutTarget", () => {