@hyperframes/studio 0.6.0-alpha.1 → 0.6.0-alpha.10

package/src/App.tsx

@@ -4,13 +4,14 @@ import {
   useRef,
   useEffect,
   useMemo,
+  type CSSProperties,
   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 { LeftSidebar, type LeftSidebarHandle } from "./components/sidebar/LeftSidebar";
 import { RenderQueue } from "./components/renders/RenderQueue";
 import { useRenderQueue } from "./components/renders/useRenderQueue";
 import { CompositionThumbnail, VideoThumbnail, liveTime, usePlayerStore } from "./player";
@@ -55,6 +56,7 @@ import {
 } from "./player/components/timelineZoom";
 import {
   getTimelineToggleTitle,
+  isEditableTarget,
   shouldHandleTimelineToggleHotkey,
 } from "./utils/timelineDiscovery";
 import { buildFrameCaptureFilename, buildFrameCaptureUrl } from "./utils/frameCapture";
@@ -78,10 +80,10 @@ import {
   STUDIO_MANUAL_EDITING_DISABLED_TITLE,
   STUDIO_MOTION_PANEL_ENABLED,
   STUDIO_PREVIEW_MANUAL_EDITING_ENABLED,
+  STUDIO_PREVIEW_SELECTION_ENABLED,
   STUDIO_TIMELINE_LAYER_INSPECTOR_ENABLED,
 } from "./components/editor/manualEditingAvailability";
 import {
-  buildDefaultDomEditTextField,
   buildDomEditStylePatchOperation,
   buildDomEditTextPatchOperation,
   buildElementAgentPrompt,
@@ -91,12 +93,16 @@ import {
   findElementForTimelineElement,
   getDomEditLayerKey,
   getDomEditTargetKey,
+  isLargeRasterDomEditSelection,
   isTextEditableSelection,
+  resolveVisualDomEditSelectionTarget,
   serializeDomEditTextFields,
   resolveDomEditSelection,
+  type DomEditViewport,
   type DomEditLayerItem,
   type DomEditTextField,
   type DomEditSelection,
+  buildDefaultDomEditTextField,
 } from "./components/editor/domEditing";
 import {
   STUDIO_MANUAL_EDITS_PATH,
@@ -358,10 +364,64 @@ function isManualGeometryStyleProperty(property: string): boolean {
   return property === "left" || property === "top" || property === "width" || property === "height";
 }
 
+interface PreviewLocalPointer {
+  x: number;
+  y: number;
+  viewport: DomEditViewport;
+}
+
+interface AgentModalAnchorPoint {
+  x: number;
+  y: number;
+}
+
+function resolvePreviewLocalPointer(
+  iframe: HTMLIFrameElement,
+  doc: Document,
+  win: Window,
+  clientX: number,
+  clientY: number,
+): PreviewLocalPointer | null {
+  const iframeRect = iframe.getBoundingClientRect();
+  const root =
+    doc.querySelector<HTMLElement>("[data-composition-id]") ?? doc.documentElement ?? null;
+  const rootRect = root?.getBoundingClientRect();
+  const rootWidth = rootRect?.width || win.innerWidth;
+  const rootHeight = rootRect?.height || win.innerHeight;
+  if (!rootWidth || !rootHeight) return null;
+
+  const scaleX = iframeRect.width / rootWidth;
+  const scaleY = iframeRect.height / rootHeight;
+  return {
+    x: (clientX - iframeRect.left) / scaleX,
+    y: (clientY - iframeRect.top) / scaleY,
+    viewport: { width: rootWidth, height: rootHeight },
+  };
+}
+
+function getPreviewLocalPointer(
+  iframe: HTMLIFrameElement,
+  clientX: number,
+  clientY: number,
+): PreviewLocalPointer | null {
+  let doc: Document | null = null;
+  let win: Window | null = null;
+  try {
+    doc = iframe.contentDocument;
+    win = iframe.contentWindow;
+  } catch {
+    return null;
+  }
+  if (!doc || !win) return null;
+
+  return resolvePreviewLocalPointer(iframe, doc, win, clientX, clientY);
+}
+
 function getPreviewTargetFromPointer(
   iframe: HTMLIFrameElement,
   clientX: number,
   clientY: number,
+  activeCompositionPath: string | null,
 ): HTMLElement | null {
   let doc: Document | null = null;
   let win: Window | null = null;
@@ -373,20 +433,35 @@ function getPreviewTargetFromPointer(
   }
   if (!doc || !win) return null;
 
-  const iframeRect = iframe.getBoundingClientRect();
-  const root =
-    doc.querySelector<HTMLElement>("[data-composition-id]") ?? doc.documentElement ?? null;
-  const rootRect = root?.getBoundingClientRect();
-  const rootWidth = rootRect?.width || win.innerWidth;
-  const rootHeight = rootRect?.height || win.innerHeight;
-  if (!rootWidth || !rootHeight) return null;
+  const localPointer = resolvePreviewLocalPointer(iframe, doc, win, clientX, clientY);
+  if (!localPointer) return null;
 
-  const scaleX = iframeRect.width / rootWidth;
-  const scaleY = iframeRect.height / rootHeight;
-  const localX = (clientX - iframeRect.left) / scaleX;
-  const localY = (clientY - iframeRect.top) / scaleY;
+  if (typeof doc.elementsFromPoint === "function") {
+    const visualTarget = resolveVisualDomEditSelectionTarget(
+      doc.elementsFromPoint(localPointer.x, localPointer.y),
+      {
+        activeCompositionPath,
+      },
+    );
+    if (visualTarget) return visualTarget;
+  }
+
+  return getEventTargetElement(doc.elementFromPoint(localPointer.x, localPointer.y));
+}
 
-  return getEventTargetElement(doc.elementFromPoint(localX, localY));
+function buildRasterClickSelectionContext(
+  selection: DomEditSelection,
+  localPointer: PreviewLocalPointer,
+): string {
+  return [
+    "The user clicked a large raster/background element in the Studio preview.",
+    `Preview click: x=${Math.round(localPointer.x)}px, y=${Math.round(localPointer.y)}px in a ${Math.round(
+      localPointer.viewport.width,
+    )}x${Math.round(localPointer.viewport.height)} composition.`,
+    `Selected target: <${selection.tagName}> ${selection.selector ?? selection.id ?? selection.label}.`,
+    "Visible copy or artwork at that point may be baked into the selected image/background rather than a selectable DOM text layer.",
+    "If the request mentions text seen at the click location, inspect or replace the image asset, or recreate that visible copy as editable DOM.",
+  ].join("\n");
 }
 
 function domEditSelectionsTargetSame(
@@ -592,17 +667,47 @@ function pauseStudioPreviewPlayback(iframe: HTMLIFrameElement | null): number |
 
 // ── Ask Agent Modal ──
 
+function clampNumber(value: number, min: number, max: number): number {
+  if (max < min) return min;
+  return Math.min(Math.max(value, min), max);
+}
+
+function getAgentModalPositionStyle(
+  anchorPoint: AgentModalAnchorPoint | null,
+): CSSProperties | undefined {
+  if (!anchorPoint || typeof window === "undefined") return undefined;
+
+  const modalWidth = 480;
+  const estimatedModalHeight = 270;
+  const margin = 16;
+  const left = clampNumber(
+    anchorPoint.x,
+    margin + modalWidth / 2,
+    window.innerWidth - margin - modalWidth / 2,
+  );
+  const top = clampNumber(
+    anchorPoint.y + 12,
+    margin,
+    window.innerHeight - margin - estimatedModalHeight,
+  );
+
+  return { left, top, transform: "translateX(-50%)" };
+}
+
 function AskAgentModal({
   selectionLabel,
+  anchorPoint = null,
   onSubmit,
   onClose,
 }: {
   selectionLabel: string;
+  anchorPoint?: AgentModalAnchorPoint | null;
   onSubmit: (instruction: string) => void;
   onClose: () => void;
 }) {
   const [value, setValue] = useState("");
   const inputRef = useRef<HTMLTextAreaElement>(null);
+  const modalPositionStyle = getAgentModalPositionStyle(anchorPoint);
 
   useMountEffect(() => {
     requestAnimationFrame(() => inputRef.current?.focus());
@@ -615,11 +720,18 @@ function AskAgentModal({
 
   return (
     <div
-      className="fixed inset-0 z-[100] flex items-center justify-center bg-black/60 backdrop-blur-sm"
+      className={
+        anchorPoint
+          ? "fixed inset-0 z-[100] bg-black/60 backdrop-blur-sm"
+          : "fixed inset-0 z-[100] flex items-center justify-center bg-black/60 backdrop-blur-sm"
+      }
       onClick={onClose}
     >
       <div
-        className="w-[480px] rounded-2xl border border-neutral-800 bg-neutral-950 shadow-2xl"
+        className={`w-[480px] rounded-2xl border border-neutral-800 bg-neutral-950 shadow-2xl ${
+          anchorPoint ? "fixed" : ""
+        }`}
+        style={modalPositionStyle}
         onClick={(e) => e.stopPropagation()}
       >
         <div className="flex items-center justify-between px-5 py-4 border-b border-neutral-800/60">
@@ -774,13 +886,17 @@ export function StudioApp() {
   const [domEditGroupSelections, setDomEditGroupSelections] = useState<DomEditSelection[]>([]);
   const [domEditHoverSelection, setDomEditHoverSelection] = useState<DomEditSelection | null>(null);
   const [agentPromptTagSnippet, setAgentPromptTagSnippet] = useState<string | undefined>();
+  const [agentPromptSelectionContext, setAgentPromptSelectionContext] = useState<
+    string | undefined
+  >();
+  const [agentModalAnchorPoint, setAgentModalAnchorPoint] = useState<AgentModalAnchorPoint | null>(
+    null,
+  );
   const [copiedAgentPrompt, setCopiedAgentPrompt] = useState(false);
   const [agentModalOpen, setAgentModalOpen] = useState(false);
   const [previewIframe, setPreviewIframe] = useState<HTMLIFrameElement | null>(null);
   const [inspectedTimelineElementId, setInspectedTimelineElementId] = useState<string | null>(null);
-  const [thumbnailedTimelineElementIds, setThumbnailedTimelineElementIds] = useState<
-    ReadonlySet<string>
-  >(() => new Set());
+  const [compositionLoading, setCompositionLoading] = useState(true);
   const [previewDocumentVersion, setPreviewDocumentVersion] = useState(0);
   const refreshPreviewDocumentVersion = useCallback(() => {
     setPreviewDocumentVersion((version) => version + 1);
@@ -916,6 +1032,8 @@ export function StudioApp() {
   const lastBlockedDomMoveToastAtRef = useRef(0);
   const importedFontAssetsRef = useRef<ImportedFontAsset[]>([]);
   const previewHotkeyWindowRef = useRef<Window | null>(null);
+  const handleAppKeyDownRef = useRef<((event: KeyboardEvent) => void) | undefined>(undefined);
+  const leftSidebarRef = useRef<LeftSidebarHandle>(null);
   const previewHistoryHotkeyCleanupRef = useRef<(() => void) | null>(null);
   const panelDragRef = useRef<{
     side: "left" | "right";
@@ -983,34 +1101,31 @@ export function StudioApp() {
     [toggleTimelineVisibility],
   );
 
-  useMountEffect(() => {
-    window.addEventListener("keydown", handleTimelineToggleHotkey);
-    return () => {
-      window.removeEventListener("keydown", handleTimelineToggleHotkey);
-    };
-  });
+  const previewAppKeyDownHandler = useCallback((event: KeyboardEvent) => {
+    handleAppKeyDownRef.current?.(event);
+  }, []);
 
   const syncPreviewTimelineHotkey = useCallback(
     (iframe: HTMLIFrameElement | null) => {
       const nextWindow = iframe?.contentWindow ?? null;
       if (previewHotkeyWindowRef.current === nextWindow) return;
       if (previewHotkeyWindowRef.current) {
-        previewHotkeyWindowRef.current.removeEventListener("keydown", handleTimelineToggleHotkey);
+        previewHotkeyWindowRef.current.removeEventListener("keydown", previewAppKeyDownHandler);
       }
       previewHotkeyWindowRef.current = nextWindow;
-      nextWindow?.addEventListener("keydown", handleTimelineToggleHotkey);
+      nextWindow?.addEventListener("keydown", previewAppKeyDownHandler, true);
     },
-    [handleTimelineToggleHotkey],
+    [previewAppKeyDownHandler],
   );
 
   useEffect(
     () => () => {
       if (previewHotkeyWindowRef.current) {
-        previewHotkeyWindowRef.current.removeEventListener("keydown", handleTimelineToggleHotkey);
+        previewHotkeyWindowRef.current.removeEventListener("keydown", previewAppKeyDownHandler);
         previewHotkeyWindowRef.current = null;
       }
     },
-    [handleTimelineToggleHotkey],
+    [previewAppKeyDownHandler],
   );
 
   const renderClipContent = useCallback(
@@ -1393,6 +1508,10 @@ export function StudioApp() {
       // Debounce the server write (600ms)
       if (saveTimerRef.current) clearTimeout(saveTimerRef.current);
       saveTimerRef.current = setTimeout(() => {
+        // Suppress the file-change watcher echo — the save callback triggers
+        // its own refresh, so a second one from the watcher causes a double-reload
+        // race that can leave the player in a non-playable state.
+        domEditSaveTimestampRef.current = Date.now();
         saveProjectFilesWithHistory({
           projectId: pid,
           label: "Edit source",
@@ -1491,6 +1610,7 @@ export function StudioApp() {
         throw new Error(`Unable to patch timeline element ${element.id} in ${targetPath}`);
       }
 
+      domEditSaveTimestampRef.current = Date.now();
       await saveProjectFilesWithHistory({
         projectId: pid,
         label: "Move timeline clip",
@@ -1575,6 +1695,7 @@ export function StudioApp() {
         throw new Error(`Unable to patch timeline element ${element.id} in ${targetPath}`);
       }
 
+      domEditSaveTimestampRef.current = Date.now();
       await saveProjectFilesWithHistory({
         projectId: pid,
         label: "Resize timeline clip",
@@ -1713,6 +1834,7 @@ export function StudioApp() {
           });
         }
 
+        domEditSaveTimestampRef.current = Date.now();
         await saveProjectFilesWithHistory({
           projectId: pid,
           label: "Delete timeline clip",
@@ -1741,6 +1863,155 @@ export function StudioApp() {
     [activeCompPath, editHistory.recordEdit, showToast, timelineElements, writeProjectFile],
   );
 
+  const handleDomEditElementDelete = 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) throw new Error(`Failed to read ${targetPath}`);
+
+        const data = (await response.json()) as { content?: string };
+        const originalContent = data.content;
+        if (typeof originalContent !== "string")
+          throw new Error(`Missing file contents for ${targetPath}`);
+
+        const patchTarget: { id?: string; selector?: string; selectorIndex?: number } = selection.id
+          ? {
+              id: selection.id,
+              selector: selection.selector,
+              selectorIndex: selection.selectorIndex,
+            }
+          : selection.selector
+            ? { selector: selection.selector, selectorIndex: selection.selectorIndex }
+            : ({} as never);
+        if (!patchTarget.id && !patchTarget.selector) {
+          throw new Error("Selected element has no patchable target");
+        }
+
+        const removeResponse = await fetch(
+          `/api/projects/${pid}/file-mutations/remove-element/${encodeURIComponent(targetPath)}`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ target: patchTarget }),
+          },
+        );
+        if (!removeResponse.ok) throw new Error(`Failed to delete element from ${targetPath}`);
+
+        const removeData = (await removeResponse.json()) as { changed?: boolean; content?: string };
+        const patchedContent =
+          typeof removeData.content === "string" ? removeData.content : originalContent;
+
+        domEditSaveTimestampRef.current = Date.now();
+        await saveProjectFilesWithHistory({
+          projectId: pid,
+          label: "Delete element",
+          kind: "timeline",
+          files: { [targetPath]: patchedContent },
+          readFile: async () => originalContent,
+          writeFile: writeProjectFile,
+          recordEdit: editHistory.recordEdit,
+        });
+
+        domEditSelectionRef.current = null;
+        domEditGroupSelectionsRef.current = [];
+        setDomEditSelection(null);
+        setDomEditGroupSelections([]);
+        usePlayerStore.getState().setSelectedElementId(null);
+        setRefreshKey((k) => k + 1);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Failed to delete element";
+        showToast(message);
+      }
+    },
+    [activeCompPath, editHistory.recordEdit, showToast, writeProjectFile],
+  );
+
+  // ── Consolidated keyboard shortcuts ────────────────────────────────
+  // All app-level window keydown handlers live here.
+  // Component-scoped shortcuts (playback J/K/L/Space, caption nudge)
+  // stay in their respective hooks.
+  const handleToggleRef = useRef(handleTimelineToggleHotkey);
+  handleToggleRef.current = handleTimelineToggleHotkey;
+  const handleDeleteRef = useRef(handleTimelineElementDelete);
+  handleDeleteRef.current = handleTimelineElementDelete;
+  const handleDomEditDeleteRef = useRef(handleDomEditElementDelete);
+  handleDomEditDeleteRef.current = handleDomEditElementDelete;
+
+  handleAppKeyDownRef.current = (event: KeyboardEvent) => {
+    // Shift+T — toggle timeline
+    handleToggleRef.current(event);
+
+    // Cmd/Ctrl+Z — undo, Cmd/Ctrl+Shift+Z or Ctrl+Y — redo
+    if (event.metaKey || event.ctrlKey) {
+      if (!shouldIgnoreHistoryShortcut(event.target)) {
+        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();
+          return;
+        }
+      }
+
+      // Cmd/Ctrl+1 — sidebar: Compositions tab
+      if (event.key === "1") {
+        event.preventDefault();
+        leftSidebarRef.current?.selectTab("compositions");
+        return;
+      }
+
+      // Cmd/Ctrl+2 — sidebar: Assets tab
+      if (event.key === "2") {
+        event.preventDefault();
+        leftSidebarRef.current?.selectTab("assets");
+        return;
+      }
+    }
+
+    // Delete / Backspace — remove selected element (timeline clip or preview selection)
+    if (
+      (event.key === "Delete" || event.key === "Backspace") &&
+      !event.metaKey &&
+      !event.ctrlKey &&
+      !event.altKey &&
+      !isEditableTarget(event.target)
+    ) {
+      const { selectedElementId, elements } = usePlayerStore.getState();
+      if (selectedElementId) {
+        const element = elements.find((el) => (el.key ?? el.id) === selectedElementId);
+        if (element) {
+          event.preventDefault();
+          void handleDeleteRef.current(element);
+          return;
+        }
+      }
+      const domSelection = domEditSelectionRef.current;
+      if (domSelection) {
+        event.preventDefault();
+        void handleDomEditDeleteRef.current(domSelection);
+      }
+    }
+  };
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    function handleAppKeyDown(event: KeyboardEvent) {
+      handleAppKeyDownRef.current?.(event);
+    }
+    window.addEventListener("keydown", handleAppKeyDown, true);
+    return () => window.removeEventListener("keydown", handleAppKeyDown, true);
+  }, []);
+
   const handleBlockedTimelineEdit = useCallback(
     (_element: TimelineElement) => {
       const now = Date.now();
@@ -1771,6 +2042,8 @@ export function StudioApp() {
       options?: { revealPanel?: boolean; additive?: boolean; preserveGroup?: boolean },
     ) => {
       setAgentPromptTagSnippet(undefined);
+      setAgentPromptSelectionContext(undefined);
+      setAgentModalAnchorPoint(null);
       setCopiedAgentPrompt(false);
       if (!selection) {
         domEditSelectionRef.current = null;
@@ -2228,6 +2501,8 @@ export function StudioApp() {
   handleUndoRef.current = handleUndo;
   handleRedoRef.current = handleRedo;
 
+  // History hotkey — no longer has its own window listener (consolidated
+  // handler covers it), but kept as a named callback for iframe forwarding.
   const handleHistoryHotkey = useCallback((event: KeyboardEvent) => {
     if (!(event.metaKey || event.ctrlKey)) return;
     if (shouldIgnoreHistoryShortcut(event.target)) return;
@@ -2243,12 +2518,6 @@ export function StudioApp() {
     }
   }, []);
 
-  // eslint-disable-next-line no-restricted-syntax
-  useEffect(() => {
-    window.addEventListener("keydown", handleHistoryHotkey, true);
-    return () => window.removeEventListener("keydown", handleHistoryHotkey, true);
-  }, [handleHistoryHotkey]);
-
   const syncPreviewHistoryHotkey = useCallback(
     (iframe: HTMLIFrameElement | null) => {
       previewHistoryHotkeyCleanupRef.current?.();
@@ -2296,13 +2565,13 @@ export function StudioApp() {
     (clientX: number, clientY: number, options?: { preferClipAncestor?: boolean }) => {
       const iframe = previewIframeRef.current;
       if (!iframe || captionEditMode) return null;
-      const target = getPreviewTargetFromPointer(iframe, clientX, clientY);
+      const target = getPreviewTargetFromPointer(iframe, clientX, clientY, activeCompPath);
       if (!target) return null;
       return buildDomSelectionFromTarget(target, {
         preferClipAncestor: options?.preferClipAncestor,
       });
     },
-    [buildDomSelectionFromTarget, captionEditMode],
+    [activeCompPath, buildDomSelectionFromTarget, captionEditMode],
   );
 
   const updateDomEditHoverSelection = useCallback((selection: DomEditSelection | null) => {
@@ -2398,8 +2667,21 @@ export function StudioApp() {
 
       const selection = buildDomSelectionForTimelineElement(element);
       if (selection) applyDomSelection(selection);
+
+      const key = getTimelineElementKey(element);
+      if (STUDIO_TIMELINE_LAYER_INSPECTOR_ENABLED && key && canInspectTimelineElement(element)) {
+        setInspectedTimelineElementId(key);
+        setLeftCollapsed(false);
+
+        const iframe = previewIframeRef.current;
+        if (!shouldShowTimelineInspectorBounds(currentTime, element)) {
+          seekStudioPreview(iframe, element.start);
+        }
+      } else {
+        setInspectedTimelineElementId(null);
+      }
     },
-    [applyDomSelection, buildDomSelectionForTimelineElement],
+    [applyDomSelection, buildDomSelectionForTimelineElement, currentTime],
   );
 
   const handleTimelineElementInspect = useCallback(
@@ -2426,17 +2708,6 @@ export function StudioApp() {
     [applyDomSelection, buildDomSelectionForTimelineElement, currentTime, showToast],
   );
 
-  const handleToggleTimelineElementThumbnail = useCallback((element: TimelineElement) => {
-    const key = getTimelineElementKey(element);
-    if (!key) return;
-    setThumbnailedTimelineElementIds((current) => {
-      const next = new Set(current);
-      if (next.has(key)) next.delete(key);
-      else next.add(key);
-      return next;
-    });
-  }, []);
-
   const handleTimelineLayerSelect = useCallback(
     (layer: DomEditLayerItem) => {
       if (!STUDIO_INSPECTOR_PANELS_ENABLED) return;
@@ -2816,15 +3087,26 @@ export function StudioApp() {
           buildDomEditStylePatchOperation("background-size", "contain"),
         );
       }
-      await persistDomEditOperations(domEditSelection, operations, {
-        label: "Edit layer style",
-        skipRefresh: true,
-        prepareContent: importedFont
-          ? (html, sourceFile) => ensureImportedFontFace(html, importedFont, sourceFile)
-          : undefined,
-      });
+      try {
+        await persistDomEditOperations(domEditSelection, operations, {
+          label: "Edit layer style",
+          skipRefresh: true,
+          prepareContent: importedFont
+            ? (html, sourceFile) => ensureImportedFontFace(html, importedFont, sourceFile)
+            : undefined,
+        });
+      } catch (err) {
+        console.warn("[Studio] Style persist failed:", err instanceof Error ? err.message : err);
+      }
+      refreshDomEditSelectionFromPreview(domEditSelection);
     },
-    [activeCompPath, domEditSelection, persistDomEditOperations, resolveImportedFontAsset],
+    [
+      activeCompPath,
+      domEditSelection,
+      persistDomEditOperations,
+      refreshDomEditSelectionFromPreview,
+      resolveImportedFontAsset,
+    ],
   );
 
   const handleDomTextCommit = useCallback(
@@ -3023,6 +3305,8 @@ export function StudioApp() {
   const handleAskAgent = useCallback(() => {
     if (!domEditSelection) return;
     setAgentPromptTagSnippet(undefined);
+    setAgentPromptSelectionContext(undefined);
+    setAgentModalAnchorPoint(null);
     void preloadAgentPromptSnippet(domEditSelection);
     setAgentModalOpen(true);
   }, [domEditSelection, preloadAgentPromptSnippet]);
@@ -3037,6 +3321,7 @@ export function StudioApp() {
         selection: domEditSelection,
         currentTime,
         tagSnippet,
+        selectionContext: agentPromptSelectionContext,
         userInstruction,
         sourceFilePath: toProjectAbsolutePath(projectDir, targetPath),
       });
@@ -3048,11 +3333,21 @@ export function StudioApp() {
       }
 
       setAgentModalOpen(false);
+      setAgentPromptSelectionContext(undefined);
+      setAgentModalAnchorPoint(null);
       if (copiedAgentTimerRef.current) clearTimeout(copiedAgentTimerRef.current);
       setCopiedAgentPrompt(true);
       copiedAgentTimerRef.current = setTimeout(() => setCopiedAgentPrompt(false), 1600);
     },
-    [activeCompPath, agentPromptTagSnippet, currentTime, domEditSelection, projectDir, showToast],
+    [
+      activeCompPath,
+      agentPromptSelectionContext,
+      agentPromptTagSnippet,
+      currentTime,
+      domEditSelection,
+      projectDir,
+      showToast,
+    ],
   );
 
   const handlePreviewIframeRef = useCallback(
@@ -3070,9 +3365,9 @@ export function StudioApp() {
 
   const handlePreviewCanvasMouseDown = useCallback(
     (e: React.MouseEvent<HTMLDivElement>, options?: { preferClipAncestor?: boolean }) => {
-      if (!STUDIO_PREVIEW_MANUAL_EDITING_ENABLED || captionEditMode) return;
+      if (!STUDIO_PREVIEW_SELECTION_ENABLED || captionEditMode || compositionLoading) return;
       const nextSelection = resolveDomSelectionFromPreviewPoint(e.clientX, e.clientY, {
-        preferClipAncestor: options?.preferClipAncestor ?? true,
+        preferClipAncestor: options?.preferClipAncestor ?? false,
       });
       if (!nextSelection) {
         if (!e.shiftKey) applyDomSelection(null, { revealPanel: false });
@@ -3080,14 +3375,35 @@ export function StudioApp() {
       }
       e.preventDefault();
       e.stopPropagation();
+      const localPointer = previewIframeRef.current
+        ? getPreviewLocalPointer(previewIframeRef.current, e.clientX, e.clientY)
+        : null;
       applyDomSelection(nextSelection, { additive: e.shiftKey });
+      if (
+        !e.shiftKey &&
+        localPointer &&
+        isLargeRasterDomEditSelection(nextSelection, localPointer.viewport)
+      ) {
+        setAgentPromptSelectionContext(
+          buildRasterClickSelectionContext(nextSelection, localPointer),
+        );
+        setAgentModalAnchorPoint({ x: e.clientX, y: e.clientY });
+        void preloadAgentPromptSnippet(nextSelection);
+        setAgentModalOpen(true);
+      }
     },
-    [applyDomSelection, captionEditMode, resolveDomSelectionFromPreviewPoint],
+    [
+      applyDomSelection,
+      captionEditMode,
+      compositionLoading,
+      preloadAgentPromptSnippet,
+      resolveDomSelectionFromPreviewPoint,
+    ],
   );
 
   const handlePreviewCanvasPointerMove = useCallback(
     (e: React.PointerEvent<HTMLDivElement>, options?: { preferClipAncestor?: boolean }) => {
-      if (!STUDIO_PREVIEW_MANUAL_EDITING_ENABLED || captionEditMode) {
+      if (!STUDIO_PREVIEW_SELECTION_ENABLED || captionEditMode || compositionLoading) {
         updateDomEditHoverSelection(null);
         return null;
       }
@@ -3098,7 +3414,12 @@ export function StudioApp() {
       updateDomEditHoverSelection(nextSelection);
       return nextSelection;
     },
-    [captionEditMode, resolveDomSelectionFromPreviewPoint, updateDomEditHoverSelection],
+    [
+      captionEditMode,
+      compositionLoading,
+      resolveDomSelectionFromPreviewPoint,
+      updateDomEditHoverSelection,
+    ],
   );
 
   const handlePreviewCanvasPointerLeave = useCallback(() => {
@@ -3397,6 +3718,7 @@ export function StudioApp() {
           }),
         );
 
+        domEditSaveTimestampRef.current = Date.now();
         await saveProjectFilesWithHistory({
           projectId: pid,
           label: "Add timeline asset",
@@ -3884,6 +4206,7 @@ export function StudioApp() {
           </div>
         ) : (
           <LeftSidebar
+            ref={leftSidebarRef}
             width={leftWidth}
             projectId={projectId}
             compositions={compositions}
@@ -3965,9 +4288,8 @@ export function StudioApp() {
             onInspectTimelineElement={handleTimelineElementInspect}
             inspectedTimelineElementId={inspectedTimelineElementId}
             timelineLayerChildCounts={timelineLayerChildCounts}
-            thumbnailedTimelineElementIds={thumbnailedTimelineElementIds}
-            onToggleTimelineElementThumbnail={handleToggleTimelineElementThumbnail}
             onCompIdToSrcChange={setCompIdToSrc}
+            onCompositionLoadingChange={setCompositionLoading}
             onCompositionChange={(compPath) => {
               // Sync activeCompPath when user drills down via timeline double-click
               // or navigates back via breadcrumb — keeps sidebar + thumbnails in sync.
@@ -3984,7 +4306,7 @@ export function StudioApp() {
                   iframeRef={previewIframeRef}
                   activeCompositionPath={activeCompPath}
                   hoverSelection={
-                    STUDIO_PREVIEW_MANUAL_EDITING_ENABLED && !captionEditMode
+                    STUDIO_PREVIEW_SELECTION_ENABLED && !captionEditMode
                       ? domEditHoverSelection
                       : null
                   }
@@ -4093,6 +4415,7 @@ export function StudioApp() {
                         projectId={projectId}
                         assets={assets}
                         element={domEditGroupSelections.length > 1 ? null : domEditSelection}
+                        multiSelectCount={domEditGroupSelections.length}
                         copiedAgentPrompt={copiedAgentPrompt}
                         onClearSelection={clearDomSelection}
                         onSetStyle={handleDomStyleCommit}
@@ -4122,9 +4445,9 @@ export function StudioApp() {
                         projectId={projectId}
                         onDelete={renderQueue.deleteRender}
                         onClearCompleted={renderQueue.clearCompleted}
-                        onStartRender={async (format, quality) => {
+                        onStartRender={async (format, quality, resolution, fps) => {
                           await waitForPendingDomEditSaves();
-                          await renderQueue.startRender(30, quality, format);
+                          await renderQueue.startRender({ fps, quality, format, resolution });
                         }}
                         isRendering={renderQueue.isRendering}
                       />
@@ -4155,8 +4478,13 @@ export function StudioApp() {
       {agentModalOpen && domEditSelection && (
         <AskAgentModal
           selectionLabel={domEditSelection.label}
+          anchorPoint={agentModalAnchorPoint}
           onSubmit={handleAgentModalSubmit}
-          onClose={() => setAgentModalOpen(false)}
+          onClose={() => {
+            setAgentModalOpen(false);
+            setAgentPromptSelectionContext(undefined);
+            setAgentModalAnchorPoint(null);
+          }}
         />
       )}