@hyperframes/studio 0.5.0-alpha.1 → 0.5.0-alpha.11

package/src/App.tsx

@@ -1,16 +1,25 @@
-import { useState, useCallback, useRef, useEffect, useMemo, type ReactNode } from "react";
+import {
+  useState,
+  useCallback,
+  useRef,
+  useEffect,
+  useMemo,
+  type MouseEvent,
+  type ReactNode,
+} from "react";
 import { useMountEffect } from "./hooks/useMountEffect";
 import { NLELayout } from "./components/nle/NLELayout";
 import { SourceEditor } from "./components/editor/SourceEditor";
 import { LeftSidebar } from "./components/sidebar/LeftSidebar";
 import { RenderQueue } from "./components/renders/RenderQueue";
 import { useRenderQueue } from "./components/renders/useRenderQueue";
-import { CompositionThumbnail, VideoThumbnail, usePlayerStore } from "./player";
+import { CompositionThumbnail, VideoThumbnail, liveTime, usePlayerStore } from "./player";
 import { AudioWaveform } from "./player/components/AudioWaveform";
 import type { TimelineElement } from "./player";
 import { LintModal } from "./components/LintModal";
 import type { LintFinding } from "./components/LintModal";
 import { MediaPreview } from "./components/MediaPreview";
+import { RotateCcw, RotateCw } from "./icons/SystemIcons";
 import { FONT_EXT, isMediaFile } from "./utils/mediaTypes";
 import {
   buildTimelineAssetId,
@@ -28,6 +37,8 @@ import { CaptionTimeline } from "./captions/components/CaptionTimeline";
 import { useCaptionStore } from "./captions/store";
 import { useCaptionSync } from "./captions/hooks/useCaptionSync";
 import { parseCaptionComposition } from "./captions/parser";
+import { copyTextToClipboard } from "./utils/clipboard";
+import { usePersistentEditHistory } from "./hooks/usePersistentEditHistory";
 import {
   applyPatchByTarget,
   readAttributeByTarget,
@@ -49,6 +60,8 @@ import {
   setTimelineEditorHintDismissed,
   shouldHandleTimelineToggleHotkey,
 } from "./utils/timelineDiscovery";
+import { buildFrameCaptureFilename, buildFrameCaptureUrl } from "./utils/frameCapture";
+import { Camera } from "./icons/SystemIcons";
 import { PropertyPanel } from "./components/editor/PropertyPanel";
 import { googleFontStylesheetUrl } from "./components/editor/fontCatalog";
 import {
@@ -73,6 +86,7 @@ import {
   type DomEditTextField,
   type DomEditSelection,
 } from "./components/editor/domEditing";
+import { saveProjectFilesWithHistory } from "./utils/studioFileHistory";
 
 interface EditingFile {
   path: string;
@@ -166,6 +180,23 @@ function toRelativeProjectAssetPath(sourceFile: string, assetPath: string): stri
   return [...fromParts.map(() => ".."), ...targetParts].join("/") || assetPath;
 }
 
+function isAbsoluteFilePath(value: string): boolean {
+  return /^(?:\/|[A-Za-z]:[\\/]|\\\\)/.test(value);
+}
+
+function toProjectAbsolutePath(projectDir: string | null, sourceFile: string): string | undefined {
+  const trimmedSource = sourceFile.trim();
+  if (!trimmedSource) return undefined;
+
+  const normalizedSource = trimmedSource.replace(/\\/g, "/");
+  if (isAbsoluteFilePath(normalizedSource)) return normalizedSource;
+
+  const normalizedRoot = projectDir?.trim().replace(/\\/g, "/").replace(/\/+$/, "");
+  if (!normalizedRoot) return undefined;
+
+  return `${normalizedRoot}/${normalizedSource.replace(/^\.?\//, "")}`;
+}
+
 function ensureImportedFontFace(
   html: string,
   asset: ImportedFontAsset,
@@ -239,6 +270,29 @@ function getEventTargetElement(target: EventTarget | null): HTMLElement | null {
   return null;
 }
 
+function shouldIgnoreHistoryShortcut(target: EventTarget | null): boolean {
+  const el = getEventTargetElement(target);
+  if (!el) return false;
+  return Boolean(
+    el.closest("input, textarea, select, [contenteditable='true'], [role='textbox'], .cm-editor"),
+  );
+}
+
+function getHistoryShortcutLabel(action: "undo" | "redo"): string {
+  const isMac =
+    typeof navigator !== "undefined" && /Mac|iPhone|iPad|iPod/i.test(navigator.platform);
+  const modifier = isMac ? "Cmd" : "Ctrl";
+  return action === "undo" ? `${modifier}+Z` : `${modifier}+Shift+Z`;
+}
+
+function getDomEditCoalesceKey(
+  selection: Pick<DomEditSelection, "id" | "selector" | "sourceFile">,
+  action: "move" | "resize",
+): string {
+  const target = selection.id || selection.selector || "selection";
+  return `${action}:${selection.sourceFile || "index.html"}:${target}`;
+}
+
 function findMatchingTimelineElementId(
   selection: Pick<
     DomEditSelection,
@@ -574,6 +628,7 @@ export function StudioApp() {
   });
 
   const [editingFile, setEditingFile] = useState<EditingFile | null>(null);
+  const [projectDir, setProjectDir] = useState<string | null>(null);
   const [activeCompPath, setActiveCompPath] = useState<string | null>(null);
   const [fileTree, setFileTree] = useState<string[]>([]);
   const [compIdToSrc, setCompIdToSrc] = useState<Map<string, string>>(new Map());
@@ -589,6 +644,7 @@ export function StudioApp() {
   const [rightCollapsed, setRightCollapsed] = useState(true);
   const [rightPanelTab, setRightPanelTab] = useState<RightPanelTab>("renders");
   const [domEditSelection, setDomEditSelection] = useState<DomEditSelection | null>(null);
+  const [agentPromptTagSnippet, setAgentPromptTagSnippet] = useState<string | undefined>();
   const [copiedAgentPrompt, setCopiedAgentPrompt] = useState(false);
   const [agentModalOpen, setAgentModalOpen] = useState(false);
   const [previewIframe, setPreviewIframe] = useState<HTMLIFrameElement | null>(null);
@@ -714,6 +770,7 @@ export function StudioApp() {
   const [globalDragOver, setGlobalDragOver] = useState(false);
   const [appToast, setAppToast] = useState<AppToast | null>(null);
   const [timelineVisible, setTimelineVisible] = useState(true);
+  const [captureFrameTime, setCaptureFrameTime] = useState(0);
   const [timelineEditorHintDismissed, setTimelineEditorHintState] = useState(
     getTimelineEditorHintDismissed,
   );
@@ -756,6 +813,29 @@ export function StudioApp() {
   const toggleTimelineVisibility = useCallback(() => {
     setTimelineVisible((visible) => !visible);
   }, []);
+  const toggleLeftSidebar = useCallback(() => {
+    setLeftCollapsed((collapsed) => !collapsed);
+  }, []);
+  const refreshCaptureFrameTime = useCallback(() => {
+    setCaptureFrameTime(usePlayerStore.getState().currentTime);
+  }, []);
+
+  useMountEffect(() => {
+    setCaptureFrameTime(usePlayerStore.getState().currentTime);
+    return liveTime.subscribe(setCaptureFrameTime);
+  });
+
+  const captureFrameHref = projectId
+    ? buildFrameCaptureUrl({
+        projectId,
+        compositionPath: activeCompPath,
+        currentTime: captureFrameTime,
+      })
+    : "#";
+  const captureFrameFilename = buildFrameCaptureFilename(activeCompPath, captureFrameTime);
+  useMountEffect(() => () => {
+    if (toastTimerRef.current) clearTimeout(toastTimerRef.current);
+  });
   const dismissTimelineEditorHint = useCallback(() => {
     setTimelineEditorHintState(true);
     setTimelineEditorHintDismissed(true);
@@ -838,6 +918,8 @@ export function StudioApp() {
             label={el.id || el.tag}
             labelColor={style.label}
             accentColor={style.clip}
+            selector={el.selector}
+            selectorIndex={el.selectorIndex}
             seekTime={el.start}
             duration={el.duration}
           />
@@ -852,13 +934,28 @@ export function StudioApp() {
 
       // Audio clips — waveform visualization
       if (el.tag === "audio") {
-        const audioUrl = el.src
-          ? el.src.startsWith("http")
-            ? el.src
-            : `/api/projects/${pid}/preview/${el.src}`
-          : "";
+        const previewBase = `/api/projects/${pid}/preview/`;
+        const previewIdx = el.src?.startsWith("http") ? el.src.indexOf(previewBase) : -1;
+        const srcRelative = el.src
+          ? previewIdx !== -1
+            ? decodeURIComponent(el.src.slice(previewIdx + previewBase.length))
+            : el.src.startsWith("http")
+              ? null
+              : el.src
+          : null;
+        const audioUrl = srcRelative
+          ? `/api/projects/${pid}/preview/${srcRelative}`
+          : (el.src ?? "");
+        const waveformUrl = srcRelative
+          ? `/api/projects/${pid}/waveform/${srcRelative}`
+          : undefined;
         return (
-          <AudioWaveform audioUrl={audioUrl} label={el.id || el.tag} labelColor={style.label} />
+          <AudioWaveform
+            audioUrl={audioUrl}
+            waveformUrl={waveformUrl}
+            label={el.id || el.tag}
+            labelColor={style.label}
+          />
         );
       }
 
@@ -883,6 +980,8 @@ export function StudioApp() {
             label={el.id || el.tag}
             labelColor={style.label}
             accentColor={style.clip}
+            selector={el.selector}
+            selectorIndex={el.selectorIndex}
             seekTime={el.start}
             duration={el.duration}
           />
@@ -962,6 +1061,28 @@ export function StudioApp() {
           >
             +
           </button>
+          <button
+            type="button"
+            onClick={toggleTimelineVisibility}
+            className="ml-1 flex h-7 w-7 items-center justify-center rounded-md text-neutral-500 transition-colors hover:bg-neutral-900 hover:text-neutral-200"
+            title={getTimelineToggleTitle(true)}
+            aria-label="Hide timeline editor"
+          >
+            <svg
+              width="14"
+              height="14"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="1.8"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              aria-hidden="true"
+            >
+              <path d="M5 7h14" />
+              <path d="m8 11 4 4 4-4" />
+            </svg>
+          </button>
         </div>
       </div>
     </div>
@@ -1014,10 +1135,13 @@ export function StudioApp() {
     let cancelled = false;
     fetch(`/api/projects/${projectId}`)
       .then((r) => r.json())
-      .then((data: { files?: string[] }) => {
+      .then((data: { files?: string[]; dir?: string }) => {
         if (!cancelled && data.files) setFileTree(data.files);
+        if (!cancelled) setProjectDir(typeof data.dir === "string" ? data.dir : null);
       })
-      .catch(() => {});
+      .catch(() => {
+        if (!cancelled) setProjectDir(null);
+      });
     return () => {
       cancelled = true;
     };
@@ -1045,29 +1169,62 @@ export function StudioApp() {
 
   const editingPathRef = useRef(editingFile?.path);
   editingPathRef.current = editingFile?.path;
+  const editHistory = usePersistentEditHistory({ projectId });
 
-  const handleContentChange = useCallback((content: string) => {
+  const readProjectFile = useCallback(async (path: string): Promise<string> => {
     const pid = projectIdRef.current;
-    if (!pid) return;
-    const path = editingPathRef.current;
-    if (!path) return;
-
-    // Debounce the server write (600ms)
-    if (saveTimerRef.current) clearTimeout(saveTimerRef.current);
-    saveTimerRef.current = setTimeout(() => {
-      fetch(`/api/projects/${pid}/files/${encodeURIComponent(path)}`, {
-        method: "PUT",
-        headers: { "Content-Type": "text/plain" },
-        body: content,
-      })
-        .then(() => {
-          if (refreshTimerRef.current) clearTimeout(refreshTimerRef.current);
-          refreshTimerRef.current = setTimeout(() => setRefreshKey((k) => k + 1), 600);
-        })
-        .catch(() => {});
-    }, 600);
+    if (!pid) throw new Error("No active project");
+    const response = await fetch(`/api/projects/${pid}/files/${encodeURIComponent(path)}`);
+    if (!response.ok) throw new Error(`Failed to read ${path}`);
+    const data = (await response.json()) as { content?: string };
+    if (typeof data.content !== "string") throw new Error(`Missing file contents for ${path}`);
+    return data.content;
+  }, []);
+
+  const writeProjectFile = useCallback(async (path: string, content: string): Promise<void> => {
+    const pid = projectIdRef.current;
+    if (!pid) throw new Error("No active project");
+    const response = await fetch(`/api/projects/${pid}/files/${encodeURIComponent(path)}`, {
+      method: "PUT",
+      headers: { "Content-Type": "text/plain" },
+      body: content,
+    });
+    if (!response.ok) throw new Error(`Failed to save ${path}`);
+    if (editingPathRef.current === path) {
+      setEditingFile({ path, content });
+    }
   }, []);
 
+  const handleContentChange = useCallback(
+    (content: string) => {
+      const pid = projectIdRef.current;
+      if (!pid) return;
+      const path = editingPathRef.current;
+      if (!path) return;
+
+      // Debounce the server write (600ms)
+      if (saveTimerRef.current) clearTimeout(saveTimerRef.current);
+      saveTimerRef.current = setTimeout(() => {
+        saveProjectFilesWithHistory({
+          projectId: pid,
+          label: "Edit source",
+          kind: "source",
+          coalesceKey: `source:${path}`,
+          files: { [path]: content },
+          readFile: readProjectFile,
+          writeFile: writeProjectFile,
+          recordEdit: editHistory.recordEdit,
+        })
+          .then(() => {
+            if (refreshTimerRef.current) clearTimeout(refreshTimerRef.current);
+            refreshTimerRef.current = setTimeout(() => setRefreshKey((k) => k + 1), 600);
+          })
+          .catch(() => {});
+      }, 600);
+    },
+    [editHistory.recordEdit, readProjectFile, writeProjectFile],
+  );
+
   const handleTimelineElementMove = useCallback(
     async (element: TimelineElement, updates: Pick<TimelineElement, "start" | "track">) => {
       const pid = projectIdRef.current;
@@ -1146,25 +1303,19 @@ export function StudioApp() {
         throw new Error(`Unable to patch timeline element ${element.id} in ${targetPath}`);
       }
 
-      const saveResponse = await fetch(
-        `/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`,
-        {
-          method: "PUT",
-          headers: { "Content-Type": "text/plain" },
-          body: patchedContent,
-        },
-      );
-      if (!saveResponse.ok) {
-        throw new Error(`Failed to save ${targetPath}`);
-      }
-
-      if (editingPathRef.current === targetPath) {
-        setEditingFile({ path: targetPath, content: patchedContent });
-      }
+      await saveProjectFilesWithHistory({
+        projectId: pid,
+        label: "Move timeline clip",
+        kind: "timeline",
+        files: { [targetPath]: patchedContent },
+        readFile: async () => originalContent,
+        writeFile: writeProjectFile,
+        recordEdit: editHistory.recordEdit,
+      });
 
       setRefreshKey((k) => k + 1);
     },
-    [activeCompPath, timelineElements],
+    [activeCompPath, editHistory.recordEdit, timelineElements, writeProjectFile],
   );
 
   const handleTimelineElementResize = useCallback(
@@ -1236,25 +1387,19 @@ export function StudioApp() {
         throw new Error(`Unable to patch timeline element ${element.id} in ${targetPath}`);
       }
 
-      const saveResponse = await fetch(
-        `/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`,
-        {
-          method: "PUT",
-          headers: { "Content-Type": "text/plain" },
-          body: patchedContent,
-        },
-      );
-      if (!saveResponse.ok) {
-        throw new Error(`Failed to save ${targetPath}`);
-      }
-
-      if (editingPathRef.current === targetPath) {
-        setEditingFile({ path: targetPath, content: patchedContent });
-      }
+      await saveProjectFilesWithHistory({
+        projectId: pid,
+        label: "Resize timeline clip",
+        kind: "timeline",
+        files: { [targetPath]: patchedContent },
+        readFile: async () => originalContent,
+        writeFile: writeProjectFile,
+        recordEdit: editHistory.recordEdit,
+      });
 
       setRefreshKey((k) => k + 1);
     },
-    [activeCompPath],
+    [activeCompPath, editHistory.recordEdit, writeProjectFile],
   );
 
   const showToast = useCallback((message: string, tone: AppToast["tone"] = "error") => {
@@ -1263,6 +1408,42 @@ export function StudioApp() {
     toastTimerRef.current = setTimeout(() => setAppToast(null), 4000);
   }, []);
 
+  const handleCaptureFrameClick = useCallback(
+    async (event: MouseEvent<HTMLAnchorElement>) => {
+      if (!projectId) return;
+      event.preventDefault();
+
+      const currentTime = usePlayerStore.getState().currentTime;
+      setCaptureFrameTime(currentTime);
+      const href = buildFrameCaptureUrl({
+        projectId,
+        compositionPath: activeCompPath,
+        currentTime,
+      });
+      const filename = buildFrameCaptureFilename(activeCompPath, currentTime);
+
+      try {
+        const response = await fetch(href, { cache: "no-store" });
+        if (!response.ok) {
+          throw new Error(`Capture failed (${response.status})`);
+        }
+        const blob = await response.blob();
+        const blobUrl = URL.createObjectURL(blob);
+        const link = document.createElement("a");
+        link.href = blobUrl;
+        link.download = filename;
+        document.body.appendChild(link);
+        link.click();
+        link.remove();
+        setTimeout(() => URL.revokeObjectURL(blobUrl), 0);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Capture failed";
+        showToast(message);
+      }
+    },
+    [activeCompPath, projectId, showToast],
+  );
+
   const handleTimelineElementDelete = useCallback(
     async (element: TimelineElement) => {
       const pid = projectIdRef.current;
@@ -1343,21 +1524,15 @@ export function StudioApp() {
           });
         }
 
-        const saveResponse = await fetch(
-          `/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`,
-          {
-            method: "PUT",
-            headers: { "Content-Type": "text/plain" },
-            body: patchedContent,
-          },
-        );
-        if (!saveResponse.ok) {
-          throw new Error(`Failed to save ${targetPath}`);
-        }
-
-        if (editingPathRef.current === targetPath) {
-          setEditingFile({ path: targetPath, content: patchedContent });
-        }
+        await saveProjectFilesWithHistory({
+          projectId: pid,
+          label: "Delete timeline clip",
+          kind: "timeline",
+          files: { [targetPath]: patchedContent },
+          readFile: async () => originalContent,
+          writeFile: writeProjectFile,
+          recordEdit: editHistory.recordEdit,
+        });
 
         usePlayerStore
           .getState()
@@ -1374,7 +1549,7 @@ export function StudioApp() {
         showToast(message);
       }
     },
-    [activeCompPath, showToast, timelineElements],
+    [activeCompPath, editHistory.recordEdit, showToast, timelineElements, writeProjectFile],
   );
 
   const handleBlockedTimelineEdit = useCallback(
@@ -1406,6 +1581,7 @@ export function StudioApp() {
   const applyDomSelection = useCallback(
     (selection: DomEditSelection | null, options?: { revealPanel?: boolean }) => {
       setDomEditSelection(selection);
+      setAgentPromptTagSnippet(undefined);
       setCopiedAgentPrompt(false);
       if (selection) {
         if (options?.revealPanel !== false) {
@@ -1426,6 +1602,63 @@ export function StudioApp() {
     applyDomSelection(null, { revealPanel: false });
   }, [applyDomSelection]);
 
+  const handleUndo = useCallback(async () => {
+    const result = await editHistory.undo({
+      readFile: readProjectFile,
+      writeFile: writeProjectFile,
+    });
+    if (!result.ok && result.reason === "content-mismatch") {
+      showToast("File changed outside Studio. Undo history was not applied.", "info");
+      return;
+    }
+    if (result.ok && result.label) {
+      clearDomSelection();
+      setRefreshKey((key) => key + 1);
+      showToast(`Undid ${result.label}`, "info");
+    }
+  }, [clearDomSelection, editHistory, readProjectFile, showToast, writeProjectFile]);
+
+  const handleRedo = useCallback(async () => {
+    const result = await editHistory.redo({
+      readFile: readProjectFile,
+      writeFile: writeProjectFile,
+    });
+    if (!result.ok && result.reason === "content-mismatch") {
+      showToast("File changed outside Studio. Redo history was not applied.", "info");
+      return;
+    }
+    if (result.ok && result.label) {
+      clearDomSelection();
+      setRefreshKey((key) => key + 1);
+      showToast(`Redid ${result.label}`, "info");
+    }
+  }, [clearDomSelection, editHistory, readProjectFile, showToast, writeProjectFile]);
+
+  const handleUndoRef = useRef(handleUndo);
+  const handleRedoRef = useRef(handleRedo);
+  handleUndoRef.current = handleUndo;
+  handleRedoRef.current = handleRedo;
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    const handler = (event: KeyboardEvent) => {
+      if (!(event.metaKey || event.ctrlKey)) return;
+      if (shouldIgnoreHistoryShortcut(event.target)) return;
+      const key = event.key.toLowerCase();
+      if (key === "z" && !event.shiftKey) {
+        event.preventDefault();
+        void handleUndoRef.current();
+        return;
+      }
+      if ((key === "z" && event.shiftKey) || (event.ctrlKey && !event.metaKey && key === "y")) {
+        event.preventDefault();
+        void handleRedoRef.current();
+      }
+    };
+    window.addEventListener("keydown", handler);
+    return () => window.removeEventListener("keydown", handler);
+  }, []);
+
   const buildDomSelectionFromTarget = useCallback(
     (target: HTMLElement, options?: { preferClipAncestor?: boolean }) => {
       if (isMasterView) {
@@ -1468,6 +1701,34 @@ export function StudioApp() {
     [activeCompPath, compIdToSrc, fileTree, isMasterView, timelineElements],
   );
 
+  const preloadAgentPromptSnippet = useCallback(
+    async (selection: DomEditSelection) => {
+      const pid = projectIdRef.current;
+      if (!pid) return;
+
+      const targetPath = selection.sourceFile || activeCompPath || "index.html";
+      try {
+        const response = await fetch(
+          `/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`,
+        );
+        if (!response.ok) return;
+
+        const data = (await response.json()) as { content?: string };
+        const html = data.content;
+        const tagSnippet =
+          typeof html === "string" ? readTagSnippetByTarget(html, selection) : undefined;
+
+        setAgentPromptTagSnippet((current) => {
+          if (domEditSelectionRef.current !== selection) return current;
+          return tagSnippet;
+        });
+      } catch {
+        // Runtime outerHTML is still available as a synchronous copy fallback.
+      }
+    },
+    [activeCompPath],
+  );
+
   const resolveImportedFontAsset = useCallback(
     (fontFamilyValue: string): ImportedFontAsset | null => {
       const family = primaryFontFamilyValue(fontFamilyValue);
@@ -1496,6 +1757,8 @@ export function StudioApp() {
       selection: DomEditSelection,
       operations: Parameters<typeof applyPatchByTarget>[2][],
       options?: {
+        label?: string;
+        coalesceKey?: string;
         skipRefresh?: boolean;
         prepareContent?: (html: string, sourceFile: string) => string;
         shouldSave?: () => boolean;
@@ -1530,21 +1793,16 @@ export function StudioApp() {
         throw new Error(`Unable to patch ${selection.selector ?? selection.id ?? "selection"}`);
       }
 
-      const saveResponse = await fetch(
-        `/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`,
-        {
-          method: "PUT",
-          headers: { "Content-Type": "text/plain" },
-          body: patchedContent,
-        },
-      );
-      if (!saveResponse.ok) {
-        throw new Error(`Failed to save ${targetPath}`);
-      }
-
-      if (editingPathRef.current === targetPath) {
-        setEditingFile({ path: targetPath, content: patchedContent });
-      }
+      await saveProjectFilesWithHistory({
+        projectId: pid,
+        label: options?.label ?? "Edit layer",
+        kind: "manual",
+        coalesceKey: options?.coalesceKey,
+        files: { [targetPath]: patchedContent },
+        readFile: async () => originalContent,
+        writeFile: writeProjectFile,
+        recordEdit: editHistory.recordEdit,
+      });
 
       if (options?.skipRefresh) {
         domEditSaveTimestampRef.current = Date.now();
@@ -1552,7 +1810,7 @@ export function StudioApp() {
         setRefreshKey((k) => k + 1);
       }
     },
-    [activeCompPath],
+    [activeCompPath, editHistory.recordEdit, writeProjectFile],
   );
 
   const handleDomMoveCommit = useCallback(
@@ -1563,7 +1821,11 @@ export function StudioApp() {
           ...buildDomEditMovePatchOperations(next.left, next.top),
           ...buildOppositeEdgePatchOperations(selection, "both"),
         ],
-        { skipRefresh: true },
+        {
+          skipRefresh: true,
+          label: "Move layer",
+          coalesceKey: getDomEditCoalesceKey(selection, "move"),
+        },
       );
     },
     [persistDomEditOperations],
@@ -1581,7 +1843,11 @@ export function StudioApp() {
           ...buildDomEditResizePatchOperations(next.width, next.height),
           ...buildOppositeEdgePatchOperations(selection, "both"),
         ],
-        { skipRefresh: true },
+        {
+          skipRefresh: true,
+          label: "Resize layer",
+          coalesceKey: getDomEditCoalesceKey(selection, "resize"),
+        },
       );
     },
     [persistDomEditOperations],
@@ -1607,7 +1873,10 @@ export function StudioApp() {
       element.style.setProperty(operation.property, operation.value);
     }
 
-    await persistDomEditOperations(selection, operations, { skipRefresh: true });
+    await persistDomEditOperations(selection, operations, {
+      skipRefresh: true,
+      label: "Make layer movable",
+    });
 
     const refreshed = doc ? findElementForSelection(doc, selection, selection.sourceFile) : element;
     if (refreshed) {
@@ -1670,6 +1939,7 @@ export function StudioApp() {
         );
       }
       await persistDomEditOperations(domEditSelection, operations, {
+        label: "Edit layer style",
         skipRefresh: true,
         prepareContent: importedFont
           ? (html, sourceFile) => ensureImportedFontFace(html, importedFont, sourceFile)
@@ -1714,6 +1984,7 @@ export function StudioApp() {
         domEditSelection,
         [buildDomEditTextPatchOperation(nextContent)],
         {
+          label: "Edit text",
           skipRefresh: true,
           shouldSave: () => domTextCommitVersionRef.current === commitVersion,
         },
@@ -1766,6 +2037,7 @@ export function StudioApp() {
 
       const importedFont = options?.importedFont ?? null;
       await persistDomEditOperations(selection, [buildDomEditTextPatchOperation(nextContent)], {
+        label: "Edit text",
         skipRefresh: true,
         prepareContent: importedFont
           ? (html, sourceFile) => ensureImportedFontFace(html, importedFont, sourceFile)
@@ -1870,43 +2142,29 @@ export function StudioApp() {
 
   const handleAskAgent = useCallback(() => {
     if (!domEditSelection) return;
+    setAgentPromptTagSnippet(undefined);
+    void preloadAgentPromptSnippet(domEditSelection);
     setAgentModalOpen(true);
-  }, [domEditSelection]);
+  }, [domEditSelection, preloadAgentPromptSnippet]);
 
   const handleAgentModalSubmit = useCallback(
     async (userInstruction: string) => {
       if (!domEditSelection) return;
 
-      const pid = projectIdRef.current;
-      if (!pid) return;
-
       const targetPath = domEditSelection.sourceFile || activeCompPath || "index.html";
-      const response = await fetch(`/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`);
-      if (!response.ok) throw new Error(`Failed to read ${targetPath}`);
-
-      const data = (await response.json()) as { content?: string };
-      const html = data.content;
-      const tagSnippet =
-        typeof html === "string" ? readTagSnippetByTarget(html, domEditSelection) : undefined;
+      const tagSnippet = agentPromptTagSnippet ?? domEditSelection.element.outerHTML;
       const prompt = buildElementAgentPrompt({
         selection: domEditSelection,
         currentTime,
         tagSnippet,
         userInstruction,
+        sourceFilePath: toProjectAbsolutePath(projectDir, targetPath),
       });
 
-      try {
-        await navigator.clipboard.writeText(prompt);
-      } catch {
-        const textarea = document.createElement("textarea");
-        textarea.value = prompt;
-        textarea.setAttribute("readonly", "true");
-        textarea.style.position = "fixed";
-        textarea.style.opacity = "0";
-        document.body.appendChild(textarea);
-        textarea.select();
-        document.execCommand("copy");
-        document.body.removeChild(textarea);
+      const copied = await copyTextToClipboard(prompt);
+      if (!copied) {
+        showToast("Could not copy prompt to clipboard.", "error");
+        return;
       }
 
       setAgentModalOpen(false);
@@ -1914,7 +2172,7 @@ export function StudioApp() {
       setCopiedAgentPrompt(true);
       copiedAgentTimerRef.current = setTimeout(() => setCopiedAgentPrompt(false), 1600);
     },
-    [activeCompPath, currentTime, domEditSelection],
+    [activeCompPath, agentPromptTagSnippet, currentTime, domEditSelection, projectDir, showToast],
   );
 
   const handlePreviewIframeRef = useCallback(
@@ -1929,7 +2187,7 @@ export function StudioApp() {
   );
 
   const handlePreviewCanvasMouseDown = useCallback(
-    (e: React.MouseEvent<HTMLDivElement>) => {
+    (e: React.MouseEvent<HTMLDivElement>, options?: { preferClipAncestor?: boolean }) => {
       const iframe = previewIframeRef.current;
       if (!iframe || captionEditMode) return;
       const target = getPreviewTargetFromPointer(iframe, e.clientX, e.clientY);
@@ -1941,7 +2199,7 @@ export function StudioApp() {
       e.preventDefault();
       e.stopPropagation();
       const nextSelection = buildDomSelectionFromTarget(target, {
-        preferClipAncestor: true,
+        preferClipAncestor: options?.preferClipAncestor ?? true,
       });
       if (!nextSelection) {
         lastPreviewClickRef.current = null;
@@ -2139,7 +2397,11 @@ export function StudioApp() {
   );
 
   const handleTimelineAssetDrop = useCallback(
-    async (assetPath: string, placement: Pick<TimelineElement, "start" | "track">) => {
+    async (
+      assetPath: string,
+      placement: Pick<TimelineElement, "start" | "track">,
+      durationOverride?: number,
+    ) => {
       const pid = projectIdRef.current;
       if (!pid) throw new Error("No active project");
 
@@ -2165,9 +2427,11 @@ export function StudioApp() {
         }
 
         const normalizedStart = Number(formatTimelineAttributeNumber(placement.start));
-        const normalizedDuration = Number(
-          formatTimelineAttributeNumber(await resolveDroppedAssetDuration(pid, assetPath, kind)),
-        );
+        const duration =
+          Number.isFinite(durationOverride) && durationOverride != null && durationOverride > 0
+            ? durationOverride
+            : await resolveDroppedAssetDuration(pid, assetPath, kind);
+        const normalizedDuration = Number(formatTimelineAttributeNumber(duration));
         const newId = buildTimelineAssetId(assetPath, collectHtmlIds(originalContent));
         const resolvedAssetSrc = resolveTimelineAssetSrc(targetPath, assetPath);
 
@@ -2219,21 +2483,15 @@ export function StudioApp() {
           }),
         );
 
-        const saveResponse = await fetch(
-          `/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`,
-          {
-            method: "PUT",
-            headers: { "Content-Type": "text/plain" },
-            body: patchedContent,
-          },
-        );
-        if (!saveResponse.ok) {
-          throw new Error(`Failed to save ${targetPath}`);
-        }
-
-        if (editingPathRef.current === targetPath) {
-          setEditingFile({ path: targetPath, content: patchedContent });
-        }
+        await saveProjectFilesWithHistory({
+          projectId: pid,
+          label: "Add timeline asset",
+          kind: "timeline",
+          files: { [targetPath]: patchedContent },
+          readFile: async () => originalContent,
+          writeFile: writeProjectFile,
+          recordEdit: editHistory.recordEdit,
+        });
 
         setRefreshKey((k) => k + 1);
       } catch (error) {
@@ -2242,22 +2500,45 @@ export function StudioApp() {
         showToast(message);
       }
     },
-    [activeCompPath, showToast, timelineElements],
+    [activeCompPath, editHistory.recordEdit, showToast, timelineElements, writeProjectFile],
   );
 
   const handleTimelineFileDrop = useCallback(
     async (files: File[], placement?: Pick<TimelineElement, "start" | "track">) => {
+      const pid = projectIdRef.current;
+      if (!pid) return;
       const uploaded = await uploadProjectFiles(files);
       if (uploaded.length === 0) return;
+      const durations: number[] = [];
+      for (const assetPath of uploaded) {
+        const kind = getTimelineAssetKind(assetPath);
+        const duration = kind ? await resolveDroppedAssetDuration(pid, assetPath, kind) : 0;
+        durations.push(Number(formatTimelineAttributeNumber(duration)));
+      }
       const placements = buildTimelineFileDropPlacements(
         placement ?? { start: 0, track: 0 },
-        uploaded.length,
+        durations,
+        timelineElements
+          .filter(
+            (timelineElement) =>
+              (timelineElement.sourceFile || activeCompPath || "index.html") ===
+              (activeCompPath || "index.html"),
+          )
+          .map((timelineElement) => ({
+            start: timelineElement.start,
+            duration: timelineElement.duration,
+            track: timelineElement.track,
+          })),
       );
       for (const [index, assetPath] of uploaded.entries()) {
-        await handleTimelineAssetDrop(assetPath, placements[index] ?? placements[0]);
+        await handleTimelineAssetDrop(
+          assetPath,
+          placements[index] ?? placements[0],
+          durations[index],
+        );
       }
     },
-    [handleTimelineAssetDrop, uploadProjectFiles],
+    [activeCompPath, handleTimelineAssetDrop, timelineElements, uploadProjectFiles],
   );
 
   // ── File Management Handlers ──
@@ -2532,54 +2813,54 @@ export function StudioApp() {
         {/* Right: toolbar buttons */}
         <div className="flex items-center gap-1.5">
           <button
-            onClick={() => setLeftCollapsed((v) => !v)}
+            type="button"
+            onClick={() => void handleUndo()}
+            disabled={!editHistory.canUndo}
             className={`h-7 w-7 flex items-center justify-center rounded-md border transition-colors ${
-              !leftCollapsed
-                ? "text-studio-accent bg-studio-accent/10 border-studio-accent/30"
-                : "bg-transparent border-transparent text-neutral-500 hover:text-neutral-300 hover:bg-neutral-800"
+              editHistory.canUndo
+                ? "border-neutral-700 text-neutral-300 hover:border-neutral-500 hover:bg-neutral-800"
+                : "border-neutral-900 text-neutral-700"
             }`}
-            title={leftCollapsed ? "Show sidebar" : "Hide sidebar"}
+            title={
+              editHistory.undoLabel
+                ? `Undo ${editHistory.undoLabel} (${getHistoryShortcutLabel("undo")})`
+                : `Undo (${getHistoryShortcutLabel("undo")})`
+            }
+            aria-label="Undo"
           >
-            <svg
-              width="14"
-              height="14"
-              viewBox="0 0 24 24"
-              fill="none"
-              stroke="currentColor"
-              strokeWidth="1.5"
-              strokeLinecap="round"
-              strokeLinejoin="round"
-            >
-              <rect x="3" y="3" width="18" height="18" rx="2" />
-              <path d="M9 3v18" />
-            </svg>
+            <RotateCcw size={14} />
           </button>
           <button
             type="button"
-            onClick={toggleTimelineVisibility}
-            className={`h-7 flex items-center gap-1.5 px-2.5 rounded-md text-[11px] font-medium border transition-colors ${
-              timelineVisible
-                ? "text-studio-accent bg-studio-accent/10 border-studio-accent/30"
-                : "text-neutral-300 border-neutral-700 hover:border-neutral-500 hover:bg-neutral-800"
+            onClick={() => void handleRedo()}
+            disabled={!editHistory.canRedo}
+            className={`h-7 w-7 flex items-center justify-center rounded-md border transition-colors ${
+              editHistory.canRedo
+                ? "border-neutral-700 text-neutral-300 hover:border-neutral-500 hover:bg-neutral-800"
+                : "border-neutral-900 text-neutral-700"
             }`}
-            title={getTimelineToggleTitle(timelineVisible)}
-            aria-label={timelineVisible ? "Hide timeline editor" : "Show timeline editor"}
+            title={
+              editHistory.redoLabel
+                ? `Redo ${editHistory.redoLabel} (${getHistoryShortcutLabel("redo")})`
+                : `Redo (${getHistoryShortcutLabel("redo")})`
+            }
+            aria-label="Redo"
           >
-            <svg
-              width="14"
-              height="14"
-              viewBox="0 0 24 24"
-              fill="none"
-              stroke="currentColor"
-              strokeWidth="1.5"
-              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>
+            <RotateCw size={14} />
           </button>
+          <a
+            href={captureFrameHref}
+            download={captureFrameFilename}
+            onClick={handleCaptureFrameClick}
+            onFocus={refreshCaptureFrameTime}
+            onPointerDown={refreshCaptureFrameTime}
+            className="h-7 flex items-center gap-1.5 px-2.5 rounded-md text-[11px] font-medium border border-neutral-700 text-neutral-300 transition-colors hover:border-neutral-500 hover:bg-neutral-800"
+            title="Capture current frame"
+            aria-label="Capture current frame"
+          >
+            <Camera size={14} />
+            <span>Capture</span>
+          </a>
           <button
             onClick={() => {
               if (rightCollapsed || rightPanelTab !== "design") {
@@ -2615,7 +2896,32 @@ export function StudioApp() {
       {/* Main content: sidebar + preview + right panel */}
       <div className="flex flex-1 min-h-0">
         {/* Left sidebar: Compositions + Assets (resizable, collapsible) */}
-        {!leftCollapsed && (
+        {leftCollapsed ? (
+          <div className="flex w-10 flex-shrink-0 flex-col items-center border-r border-neutral-800/50 bg-neutral-950 pt-1">
+            <button
+              type="button"
+              onClick={toggleLeftSidebar}
+              className="flex h-8 w-8 items-center justify-center rounded-md border border-transparent text-neutral-500 transition-colors hover:border-neutral-800 hover:bg-neutral-900 hover:text-neutral-300"
+              title="Show sidebar"
+              aria-label="Show sidebar"
+            >
+              <svg
+                width="14"
+                height="14"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="1.5"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                aria-hidden="true"
+              >
+                <path d="M5 4v16" />
+                <path d="m10 7 5 5-5 5" />
+              </svg>
+            </button>
+          </div>
+        ) : (
           <LeftSidebar
             width={leftWidth}
             projectId={projectId}
@@ -2662,6 +2968,7 @@ export function StudioApp() {
             }
             onLint={handleLint}
             linting={linting}
+            onToggleCollapse={toggleLeftSidebar}
           />
         )}
 
@@ -2708,6 +3015,7 @@ export function StudioApp() {
                   selection={
                     !rightCollapsed && rightPanelTab === "design" ? domEditSelection : null
                   }
+                  allowCanvasMovement={false}
                   onCanvasMouseDown={handlePreviewCanvasMouseDown}
                   onCanvasDoubleClick={handlePreviewCanvasDoubleClick}
                   onSelectedDoubleClick={handleSelectedOverlayDoubleClick}
@@ -2802,6 +3110,7 @@ export function StudioApp() {
                         onImportAssets={handleImportFiles}
                         fontAssets={fontAssets}
                         onImportFonts={handleImportFonts}
+                        allowLayoutDetach={false}
                       />
                     ) : (
                       <RenderQueue