@hyperframes/studio 0.5.5 → 0.6.0-alpha.1

package/src/App.tsx

@@ -19,13 +19,15 @@ import type { TimelineElement } from "./player";
 import { LintModal } from "./components/LintModal";
 import type { LintFinding } from "./components/LintModal";
 import { MediaPreview } from "./components/MediaPreview";
-import { isMediaFile } from "./utils/mediaTypes";
+import { RotateCcw, RotateCw } from "./icons/SystemIcons";
+import { FONT_EXT, isMediaFile } from "./utils/mediaTypes";
 import {
   buildTimelineAssetId,
   buildTimelineAssetInsertHtml,
   buildTimelineFileDropPlacements,
   getTimelineAssetKind,
   insertTimelineAssetIntoSource,
+  resolveTimelineAssetInitialGeometry,
   resolveTimelineAssetSrc,
   type TimelineAssetKind,
 } from "./utils/timelineAssetDrop";
@@ -35,7 +37,14 @@ import { CaptionTimeline } from "./captions/components/CaptionTimeline";
 import { useCaptionStore } from "./captions/store";
 import { useCaptionSync } from "./captions/hooks/useCaptionSync";
 import { parseCaptionComposition } from "./captions/parser";
-import { applyPatchByTarget, readAttributeByTarget } from "./utils/sourcePatcher";
+import { copyTextToClipboard } from "./utils/clipboard";
+import { usePersistentEditHistory } from "./hooks/usePersistentEditHistory";
+import {
+  applyPatchByTarget,
+  readAttributeByTarget,
+  readTagSnippetByTarget,
+  type PatchOperation,
+} from "./utils/sourcePatcher";
 import {
   buildTrackZIndexMap,
   formatTimelineAttributeNumber,
@@ -51,6 +60,82 @@ import {
 import { buildFrameCaptureFilename, buildFrameCaptureUrl } from "./utils/frameCapture";
 import { buildProjectHash, parseProjectIdFromHash } from "./utils/projectRouting";
 import { Camera } from "./icons/SystemIcons";
+import { PropertyPanel } from "./components/editor/PropertyPanel";
+import { MotionPanel } from "./components/editor/MotionPanel";
+import { googleFontStylesheetUrl } from "./components/editor/fontCatalog";
+import {
+  fontFamilyFromAssetPath,
+  importedFontFaceCss,
+  type ImportedFontAsset,
+} from "./components/editor/fontAssets";
+import {
+  DomEditOverlay,
+  type DomEditGroupPathOffsetCommit,
+} from "./components/editor/DomEditOverlay";
+import { TimelineLayerPanel } from "./components/editor/TimelineLayerPanel";
+import {
+  STUDIO_INSPECTOR_PANELS_ENABLED,
+  STUDIO_MANUAL_EDITING_DISABLED_TITLE,
+  STUDIO_MOTION_PANEL_ENABLED,
+  STUDIO_PREVIEW_MANUAL_EDITING_ENABLED,
+  STUDIO_TIMELINE_LAYER_INSPECTOR_ENABLED,
+} from "./components/editor/manualEditingAvailability";
+import {
+  buildDefaultDomEditTextField,
+  buildDomEditStylePatchOperation,
+  buildDomEditTextPatchOperation,
+  buildElementAgentPrompt,
+  collectDomEditLayerItems,
+  countDomEditChildLayers,
+  findElementForSelection,
+  findElementForTimelineElement,
+  getDomEditLayerKey,
+  getDomEditTargetKey,
+  isTextEditableSelection,
+  serializeDomEditTextFields,
+  resolveDomEditSelection,
+  type DomEditLayerItem,
+  type DomEditTextField,
+  type DomEditSelection,
+} from "./components/editor/domEditing";
+import {
+  STUDIO_MANUAL_EDITS_PATH,
+  applyStudioManualEditManifest,
+  emptyStudioManualEditManifest,
+  installStudioManualEditSeekReapply,
+  isStudioManualEditManifestPath,
+  parseStudioManualEditManifest,
+  readStudioFileChangePath,
+  removeStudioManualEditsForSelection,
+  serializeStudioManualEditManifest,
+  type StudioManualEditManifest,
+  upsertStudioBoxSizeEdit,
+  upsertStudioPathOffsetEdit,
+  upsertStudioRotationEdit,
+} from "./components/editor/manualEdits";
+import {
+  STUDIO_MOTION_PATH,
+  applyStudioMotionManifest,
+  emptyStudioMotionManifest,
+  getStudioMotionForSelection,
+  installStudioMotionSeekReapply,
+  isStudioMotionManifestPath,
+  parseStudioMotionManifest,
+  removeStudioMotionForSelection,
+  serializeStudioMotionManifest,
+  type StudioGsapMotion,
+  type StudioMotionManifest,
+  upsertStudioGsapMotion,
+} from "./components/editor/studioMotion";
+import { saveProjectFilesWithHistory } from "./utils/studioFileHistory";
+import {
+  canInspectTimelineElement,
+  getTimelineElementKey,
+  getTimelineLayerVisibilityInPreview,
+  isTimelineElementActiveAtTime,
+  isTimelineLayerVisibleInPreview,
+  shouldShowTimelineInspectorBounds,
+} from "./utils/timelineInspector";
 
 interface EditingFile {
   path: string;
@@ -66,6 +151,532 @@ function getTimelineElementLabel(element: TimelineElement): string {
   return element.label || element.id || element.tag;
 }
 
+type RightPanelTab = "design" | "motion" | "renders";
+
+const GENERIC_FONT_FAMILIES = new Set([
+  "inherit",
+  "initial",
+  "revert",
+  "revert-layer",
+  "serif",
+  "sans-serif",
+  "monospace",
+  "cursive",
+  "fantasy",
+  "system-ui",
+  "ui-sans-serif",
+  "ui-serif",
+  "ui-monospace",
+  "ui-rounded",
+  "emoji",
+  "math",
+  "fangsong",
+]);
+
+function primaryFontFamilyFromCss(value: string): string {
+  const first = value.split(",")[0] ?? "";
+  return first.trim().replace(/^["']|["']$/g, "");
+}
+
+function injectPreviewGoogleFont(doc: Document, fontFamilyValue: string): void {
+  const family = primaryFontFamilyFromCss(fontFamilyValue);
+  if (!family || GENERIC_FONT_FAMILIES.has(family.toLowerCase())) return;
+
+  const id = `studio-preview-google-font-${family.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`;
+  if (doc.getElementById(id)) return;
+
+  const link = doc.createElement("link");
+  link.id = id;
+  link.rel = "stylesheet";
+  link.href = googleFontStylesheetUrl(family);
+  doc.head.appendChild(link);
+}
+
+function primaryFontFamilyValue(value: string): string {
+  return (
+    value
+      .split(",")[0]
+      ?.trim()
+      .replace(/^["']|["']$/g, "")
+      .trim() ?? ""
+  );
+}
+
+function injectPreviewImportedFont(doc: Document, asset: ImportedFontAsset): void {
+  const id = `studio-imported-font-${asset.family.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`;
+  if (doc.getElementById(id)) return;
+  const style = doc.createElement("style");
+  style.id = id;
+  style.textContent = importedFontFaceCss(asset);
+  doc.head.appendChild(style);
+}
+
+function normalizeProjectAssetPath(value: string): string {
+  const trimmed = value.trim();
+  const maybeUrl = /^[a-z]+:\/\//i.test(trimmed) ? new URL(trimmed).pathname : trimmed;
+  return decodeURIComponent(maybeUrl)
+    .replace(/\\/g, "/")
+    .replace(/^\.?\//, "");
+}
+
+function toRelativeProjectAssetPath(sourceFile: string, assetPath: string): string {
+  const fromParts = normalizeProjectAssetPath(sourceFile).split("/").filter(Boolean);
+  const targetParts = normalizeProjectAssetPath(assetPath).split("/").filter(Boolean);
+
+  fromParts.pop();
+
+  while (fromParts.length > 0 && targetParts.length > 0 && fromParts[0] === targetParts[0]) {
+    fromParts.shift();
+    targetParts.shift();
+  }
+
+  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,
+  sourceFile: string,
+): string {
+  const css = importedFontFaceCss(asset, toRelativeProjectAssetPath(sourceFile, asset.path));
+  if (html.includes(css)) return html;
+
+  const styleRe = /<style\b[^>]*data-hf-studio-fonts=(["'])true\1[^>]*>([\s\S]*?)<\/style>/i;
+  const styleMatch = styleRe.exec(html);
+  if (styleMatch) {
+    const nextCss = `${styleMatch[2].trim()}\n${css}`.trim();
+    return html.replace(styleMatch[0], `<style data-hf-studio-fonts="true">\n${nextCss}\n</style>`);
+  }
+
+  const styleTag = `<style data-hf-studio-fonts="true">\n${css}\n</style>`;
+  if (/<\/head>/i.test(html)) {
+    return html.replace(/<\/head>/i, `  ${styleTag}\n  </head>`);
+  }
+  return `${styleTag}\n${html}`;
+}
+function normalizeDomEditStyleValue(property: string, value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) return trimmed;
+
+  if (
+    ["border-radius", "border-width", "font-size", "letter-spacing"].includes(property) &&
+    /^-?\d+(\.\d+)?$/.test(trimmed)
+  ) {
+    return `${trimmed}px`;
+  }
+
+  return trimmed;
+}
+
+function isImageBackgroundValue(value: string): boolean {
+  return /^url\(/i.test(value.trim());
+}
+
+function getEventTargetElement(target: EventTarget | null): HTMLElement | null {
+  if (!target || typeof target !== "object") return null;
+  const maybeNode = target as {
+    nodeType?: number;
+    parentElement?: Element | null;
+  };
+  if (maybeNode.nodeType === 1) return target as HTMLElement;
+  if (maybeNode.nodeType === 3 && maybeNode.parentElement) {
+    return maybeNode.parentElement as HTMLElement;
+  }
+  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 findMatchingTimelineElementId(
+  selection: Pick<
+    DomEditSelection,
+    "id" | "selector" | "selectorIndex" | "sourceFile" | "compositionSrc" | "isCompositionHost"
+  >,
+  elements: TimelineElement[],
+): string | null {
+  const selectionSourceFile = selection.sourceFile || "index.html";
+  for (const element of elements) {
+    const elementSourceFile = element.sourceFile || "index.html";
+    if (
+      selection.id &&
+      element.domId === selection.id &&
+      elementSourceFile === selectionSourceFile
+    ) {
+      return element.key ?? element.id;
+    }
+    if (
+      selection.isCompositionHost &&
+      selection.compositionSrc &&
+      element.compositionSrc === selection.compositionSrc
+    ) {
+      return element.key ?? element.id;
+    }
+    if (
+      selection.selector &&
+      element.selector === selection.selector &&
+      (element.selectorIndex ?? 0) === (selection.selectorIndex ?? 0) &&
+      (element.sourceFile ?? "index.html") === selection.sourceFile
+    ) {
+      return element.key ?? element.id;
+    }
+  }
+
+  return null;
+}
+
+function isManualGeometryStyleProperty(property: string): boolean {
+  return property === "left" || property === "top" || property === "width" || property === "height";
+}
+
+function getPreviewTargetFromPointer(
+  iframe: HTMLIFrameElement,
+  clientX: number,
+  clientY: number,
+): HTMLElement | 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;
+
+  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;
+  const localX = (clientX - iframeRect.left) / scaleX;
+  const localY = (clientY - iframeRect.top) / scaleY;
+
+  return getEventTargetElement(doc.elementFromPoint(localX, localY));
+}
+
+function domEditSelectionsTargetSame(
+  a: DomEditSelection | null,
+  b: DomEditSelection | null,
+): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  return getDomEditTargetKey(a) === getDomEditTargetKey(b);
+}
+
+function domEditSelectionInGroup(
+  group: DomEditSelection[],
+  selection: DomEditSelection | null,
+): boolean {
+  if (!selection) return false;
+  return group.some((entry) => domEditSelectionsTargetSame(entry, selection));
+}
+
+function toggleDomEditGroupSelection(
+  group: DomEditSelection[],
+  selection: DomEditSelection,
+): DomEditSelection[] {
+  if (domEditSelectionInGroup(group, selection)) {
+    return group.filter((entry) => !domEditSelectionsTargetSame(entry, selection));
+  }
+  return [...group, selection];
+}
+
+function replaceDomEditGroupSelection(
+  group: DomEditSelection[],
+  selection: DomEditSelection,
+): DomEditSelection[] {
+  let replaced = false;
+  const nextGroup = group.map((entry) => {
+    if (!domEditSelectionsTargetSame(entry, selection)) return entry;
+    replaced = true;
+    return selection;
+  });
+  return replaced ? nextGroup : [...group, selection];
+}
+
+function seedDomEditGroupWithSelection(
+  group: DomEditSelection[],
+  selection: DomEditSelection | null,
+): DomEditSelection[] {
+  if (!selection || domEditSelectionInGroup(group, selection)) return group;
+  return [selection, ...group];
+}
+
+function objectLike(value: unknown): object | null {
+  return value && (typeof value === "object" || typeof value === "function") ? value : null;
+}
+
+function callPlaybackMethod(target: object | null, key: string): void {
+  const method = target ? Reflect.get(target, key) : null;
+  if (typeof method !== "function") return;
+  try {
+    method.call(target);
+  } catch {
+    // Best-effort playback freeze; drag should still work if playback control is unavailable.
+  }
+}
+
+function readPlaybackTime(target: object | null, key: string): number | null {
+  const method = target ? Reflect.get(target, key) : null;
+  if (typeof method !== "function") return null;
+  try {
+    const value = method.call(target);
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+interface PreviewPlayerCompat {
+  getTime: () => number;
+  renderSeek: (timeSeconds: number) => void;
+}
+
+function getPreviewPlayer(win: Window | null | undefined): PreviewPlayerCompat | null {
+  const player = objectLike(win ? Reflect.get(win, "__player") : null);
+  if (!player) return null;
+  const getTime = Reflect.get(player, "getTime");
+  const renderSeek = Reflect.get(player, "renderSeek");
+  if (typeof getTime !== "function" || typeof renderSeek !== "function") return null;
+  return {
+    getTime: () => {
+      const value = getTime.call(player);
+      return typeof value === "number" && Number.isFinite(value) ? value : 0;
+    },
+    renderSeek: (timeSeconds: number) => {
+      renderSeek.call(player, timeSeconds);
+    },
+  };
+}
+
+function seekStudioPreview(iframe: HTMLIFrameElement | null, timeSeconds: number): boolean {
+  const player = getPreviewPlayer(iframe?.contentWindow);
+  if (!player) return false;
+  const nextTime = Math.max(0, timeSeconds);
+  player.renderSeek(nextTime);
+  usePlayerStore.getState().setCurrentTime(nextTime);
+  liveTime.notify(nextTime);
+  return true;
+}
+
+function parseFiniteSeconds(value: string | null): number | null {
+  if (value == null || value.trim() === "") return null;
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function resolveLayerVisibleSeekTime(
+  layerElement: HTMLElement,
+  timelineElement: TimelineElement | null,
+  player: PreviewPlayerCompat | null,
+): number | null {
+  if (!timelineElement || !player) return null;
+  const originalTime = player.getTime();
+
+  const clipStart = Math.max(0, timelineElement.start);
+  const clipEnd = Math.max(clipStart, clipStart + Math.max(0, timelineElement.duration));
+  const authoredStart = parseFiniteSeconds(
+    layerElement.getAttribute("data-start") ??
+      layerElement.closest<HTMLElement>("[data-start]")?.getAttribute("data-start") ??
+      null,
+  );
+  const preferredTime =
+    authoredStart == null
+      ? clipStart
+      : Math.min(clipEnd, Math.max(clipStart, clipStart + authoredStart));
+  const candidates = [preferredTime, clipStart];
+  const duration = clipEnd - clipStart;
+  if (duration > 0) {
+    const maxSamples = 24;
+    const frameStep = 1 / 24;
+    const step = Math.max(frameStep, duration / maxSamples);
+    for (let time = clipStart; time <= clipEnd + 0.0001; time += step) {
+      candidates.push(Math.min(clipEnd, time));
+    }
+  }
+  candidates.push(clipEnd);
+
+  let lastTried = preferredTime;
+  let clearestVisibleTime: number | null = null;
+  let clearestVisibleOpacity = 0;
+  let resolvedTime: number | null = null;
+  const seen = new Set<string>();
+  try {
+    for (const candidate of candidates) {
+      const time = Math.min(clipEnd, Math.max(clipStart, candidate));
+      const key = time.toFixed(4);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      lastTried = time;
+      player.renderSeek(time);
+      const visibility = getTimelineLayerVisibilityInPreview(layerElement);
+      if (visibility.visible && visibility.compositeOpacity > clearestVisibleOpacity) {
+        clearestVisibleTime = time;
+        clearestVisibleOpacity = visibility.compositeOpacity;
+      }
+      if (isTimelineLayerVisibleInPreview(layerElement, { minCompositeOpacity: 0.9 })) {
+        resolvedTime = time;
+        break;
+      }
+    }
+  } finally {
+    player.renderSeek(originalTime);
+  }
+
+  return resolvedTime ?? clearestVisibleTime ?? lastTried;
+}
+
+function pauseStudioPreviewPlayback(iframe: HTMLIFrameElement | null): number | null {
+  const win = iframe?.contentWindow;
+  if (!win) return null;
+
+  try {
+    let pausedTime: number | null = null;
+    const player = objectLike(Reflect.get(win, "__player"));
+    pausedTime = readPlaybackTime(player, "getTime") ?? pausedTime;
+    callPlaybackMethod(player, "pause");
+
+    const timeline = objectLike(Reflect.get(win, "__timeline"));
+    pausedTime = pausedTime ?? readPlaybackTime(timeline, "time");
+    callPlaybackMethod(timeline, "pause");
+
+    const timelines = objectLike(Reflect.get(win, "__timelines"));
+    if (timelines) {
+      for (const value of Object.values(timelines)) {
+        const timelineRecord = objectLike(value);
+        pausedTime = pausedTime ?? readPlaybackTime(timelineRecord, "time");
+        callPlaybackMethod(timelineRecord, "pause");
+      }
+    }
+
+    return pausedTime;
+  } catch {
+    return null;
+  }
+}
+
+// ── Ask Agent Modal ──
+
+function AskAgentModal({
+  selectionLabel,
+  onSubmit,
+  onClose,
+}: {
+  selectionLabel: string;
+  onSubmit: (instruction: string) => void;
+  onClose: () => void;
+}) {
+  const [value, setValue] = useState("");
+  const inputRef = useRef<HTMLTextAreaElement>(null);
+
+  useMountEffect(() => {
+    requestAnimationFrame(() => inputRef.current?.focus());
+  });
+
+  const handleSubmit = () => {
+    if (!value.trim()) return;
+    onSubmit(value.trim());
+  };
+
+  return (
+    <div
+      className="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"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div className="flex items-center justify-between px-5 py-4 border-b border-neutral-800/60">
+          <div>
+            <h3 className="text-sm font-medium text-neutral-200">Ask agent</h3>
+            <p className="text-xs text-neutral-500 mt-0.5">
+              {selectionLabel.length > 50 ? `${selectionLabel.slice(0, 49)}…` : selectionLabel}
+            </p>
+          </div>
+          <button
+            className="p-1 rounded-md text-neutral-500 hover:text-neutral-300 hover:bg-neutral-800/50"
+            onClick={onClose}
+          >
+            <svg
+              width="14"
+              height="14"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+            >
+              <line x1="18" y1="6" x2="6" y2="18" />
+              <line x1="6" y1="6" x2="18" y2="18" />
+            </svg>
+          </button>
+        </div>
+        <div className="px-5 py-4">
+          <textarea
+            ref={inputRef}
+            className="w-full h-24 px-3 py-2 rounded-lg border border-neutral-800 bg-neutral-900/60 text-sm text-neutral-200 placeholder-neutral-600 resize-none focus:outline-none focus:border-studio-accent/60 focus:ring-1 focus:ring-studio-accent/30"
+            placeholder="Describe what you want to change…"
+            value={value}
+            onChange={(e) => setValue(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) handleSubmit();
+              if (e.key === "Escape") onClose();
+            }}
+          />
+        </div>
+        <div className="flex items-center justify-between px-5 py-3 border-t border-neutral-800/60">
+          <span className="text-[11px] text-neutral-600">
+            {navigator.platform.includes("Mac") ? "⌘" : "Ctrl"}+Enter to copy
+          </span>
+          <button
+            className="px-4 py-1.5 rounded-lg bg-studio-accent/90 text-xs font-medium text-neutral-950 hover:bg-studio-accent disabled:opacity-40 disabled:cursor-not-allowed"
+            disabled={!value.trim()}
+            onClick={handleSubmit}
+          >
+            Copy prompt
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
 const DEFAULT_TIMELINE_ASSET_DURATION: Record<TimelineAssetKind, number> = {
   image: 3,
   video: 5,
@@ -144,6 +755,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());
@@ -157,6 +769,24 @@ export function StudioApp() {
   const [rightWidth, setRightWidth] = useState(400);
   const [leftCollapsed, setLeftCollapsed] = useState(false);
   const [rightCollapsed, setRightCollapsed] = useState(true);
+  const [rightPanelTab, setRightPanelTab] = useState<RightPanelTab>("renders");
+  const [domEditSelection, setDomEditSelection] = useState<DomEditSelection | null>(null);
+  const [domEditGroupSelections, setDomEditGroupSelections] = useState<DomEditSelection[]>([]);
+  const [domEditHoverSelection, setDomEditHoverSelection] = 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);
+  const [inspectedTimelineElementId, setInspectedTimelineElementId] = useState<string | null>(null);
+  const [thumbnailedTimelineElementIds, setThumbnailedTimelineElementIds] = useState<
+    ReadonlySet<string>
+  >(() => new Set());
+  const [previewDocumentVersion, setPreviewDocumentVersion] = useState(0);
+  const refreshPreviewDocumentVersion = useCallback(() => {
+    setPreviewDocumentVersion((version) => version + 1);
+    window.setTimeout(() => setPreviewDocumentVersion((version) => version + 1), 80);
+    window.setTimeout(() => setPreviewDocumentVersion((version) => version + 1), 300);
+  }, []);
   // Auto-enter caption edit mode when the iframe contains .caption-group elements.
   // This is a subscription to external events (postMessage from runtime) — useEffect
   // is appropriate here. The runtime fires "state"/"timeline" messages after all
@@ -283,7 +913,10 @@ export function StudioApp() {
   const dragCounterRef = useRef(0);
   const toastTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const lastBlockedTimelineToastAtRef = useRef(0);
+  const lastBlockedDomMoveToastAtRef = useRef(0);
+  const importedFontAssetsRef = useRef<ImportedFontAsset[]>([]);
   const previewHotkeyWindowRef = useRef<Window | null>(null);
+  const previewHistoryHotkeyCleanupRef = useRef<(() => void) | null>(null);
   const panelDragRef = useRef<{
     side: "left" | "right";
     startX: number;
@@ -294,11 +927,15 @@ export function StudioApp() {
   const activePreviewUrl = activeCompPath
     ? `/api/projects/${projectId}/preview/comp/${activeCompPath}`
     : null;
+  const isMasterView = !activeCompPath || activeCompPath === "index.html";
   const zoomMode = usePlayerStore((s) => s.zoomMode);
   const manualZoomPercent = usePlayerStore((s) => s.manualZoomPercent);
   const setZoomMode = usePlayerStore((s) => s.setZoomMode);
   const setManualZoomPercent = usePlayerStore((s) => s.setManualZoomPercent);
+  const currentTime = usePlayerStore((s) => s.currentTime);
   const timelineElements = usePlayerStore((s) => s.elements);
+  const selectedTimelineElementId = usePlayerStore((s) => s.selectedElementId);
+  const setSelectedTimelineElementId = usePlayerStore((s) => s.setSelectedElementId);
   const timelineDuration = usePlayerStore((s) => s.duration);
   const effectiveTimelineDuration = useMemo(() => {
     const maxEnd =
@@ -400,7 +1037,6 @@ export function StudioApp() {
             label={getTimelineElementLabel(el)}
             labelColor={style.label}
             accentColor={style.clip}
-            selector={el.selector}
             seekTime={0}
             duration={el.duration}
           />
@@ -417,6 +1053,7 @@ export function StudioApp() {
             labelColor={style.label}
             accentColor={style.clip}
             selector={el.selector}
+            selectorIndex={el.selectorIndex}
             seekTime={el.start}
             duration={el.duration}
           />
@@ -478,6 +1115,7 @@ export function StudioApp() {
             labelColor={style.label}
             accentColor={style.clip}
             selector={el.selector}
+            selectorIndex={el.selectorIndex}
             seekTime={el.start}
             duration={el.duration}
           />
@@ -562,16 +1200,80 @@ export function StudioApp() {
   const [consoleErrors, setConsoleErrors] = useState<LintFinding[] | null>(null);
   const [linting, setLinting] = useState(false);
   const [refreshKey, setRefreshKey] = useState(0);
+  const [, setStudioMotionRevision] = useState(0);
   const refreshTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const saveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const projectIdRef = useRef(projectId);
   const previewIframeRef = useRef<HTMLIFrameElement | null>(null);
   const consoleErrorsRef = useRef<LintFinding[]>([]);
+  const copiedAgentTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const domEditSelectionRef = useRef<DomEditSelection | null>(domEditSelection);
+  const domEditGroupSelectionsRef = useRef<DomEditSelection[]>(domEditGroupSelections);
+  const domEditHoverSelectionRef = useRef<DomEditSelection | null>(domEditHoverSelection);
+  const domEditSaveTimestampRef = useRef(0);
+  const domTextCommitVersionRef = useRef(0);
+  const domEditSaveQueueRef = useRef(Promise.resolve());
+  const studioManualEditManifestRef = useRef<StudioManualEditManifest>(
+    emptyStudioManualEditManifest(),
+  );
+  const studioManualEditRevisionRef = useRef(0);
+  const studioMotionManifestRef = useRef<StudioMotionManifest>(emptyStudioMotionManifest());
+  const studioMotionRevisionRef = useRef(0);
+  const applyStudioManualEditsToPreviewRef = useRef<
+    (
+      iframe?: HTMLIFrameElement | null,
+      options?: { forceFromDisk?: boolean; readFromDiskFirst?: boolean },
+    ) => Promise<void>
+  >(async () => {});
+  const applyStudioMotionToPreviewRef = useRef<
+    (
+      iframe?: HTMLIFrameElement | null,
+      options?: { forceFromDisk?: boolean; readFromDiskFirst?: boolean },
+    ) => Promise<void>
+  >(async () => {});
+  const studioManualEditProjectRef = useRef<string | null>(projectId);
+  const activeCompPathRef = useRef(activeCompPath);
+  activeCompPathRef.current = activeCompPath;
+
+  const queueDomEditSave = useCallback((save: () => Promise<void>) => {
+    const queuedSave = domEditSaveQueueRef.current.catch(() => undefined).then(save);
+    domEditSaveQueueRef.current = queuedSave.then(
+      () => undefined,
+      () => undefined,
+    );
+    return queuedSave;
+  }, []);
+
+  const waitForPendingDomEditSaves = useCallback(async () => {
+    await domEditSaveQueueRef.current.catch(() => undefined);
+  }, []);
 
   // Listen for external file changes (user editing HTML outside the editor).
   // In dev: use Vite HMR. In embedded/production: use SSE from /api/events.
+  // Suppress file-change events that echo back from a recent DOM edit save —
+  // those changes are already applied to the iframe DOM and a full reload
+  // would flash the preview.
   useMountEffect(() => {
-    const handler = () => {
+    const handler = (payload?: unknown) => {
+      const changedPath = readStudioFileChangePath(payload);
+      const recentDomEditSave = Date.now() - domEditSaveTimestampRef.current < 1200;
+      if (isStudioManualEditManifestPath(changedPath)) {
+        if (!recentDomEditSave) {
+          void applyStudioManualEditsToPreviewRef.current(previewIframeRef.current, {
+            forceFromDisk: true,
+          });
+        }
+        return;
+      }
+      if (isStudioMotionManifestPath(changedPath)) {
+        if (!recentDomEditSave) {
+          void applyStudioMotionToPreviewRef.current(previewIframeRef.current, {
+            forceFromDisk: true,
+          });
+        }
+        return;
+      }
+      if (recentDomEditSave) return;
       if (refreshTimerRef.current) clearTimeout(refreshTimerRef.current);
       refreshTimerRef.current = setTimeout(() => setRefreshKey((k) => k + 1), 400);
     };
@@ -585,6 +1287,21 @@ export function StudioApp() {
     return () => es.close();
   });
   projectIdRef.current = projectId;
+  domEditSelectionRef.current = domEditSelection;
+  domEditGroupSelectionsRef.current = domEditGroupSelections;
+  domEditHoverSelectionRef.current = domEditHoverSelection;
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    const previousProjectId = studioManualEditProjectRef.current;
+    studioManualEditProjectRef.current = projectId;
+    if (!previousProjectId || previousProjectId === projectId) return;
+    studioManualEditManifestRef.current = emptyStudioManualEditManifest();
+    studioManualEditRevisionRef.current += 1;
+    studioMotionManifestRef.current = emptyStudioMotionManifest();
+    studioMotionRevisionRef.current += 1;
+    setStudioMotionRevision((revision) => revision + 1);
+  }, [projectId]);
 
   // Load file tree when projectId changes.
   // Note: This is one of the few places where useEffect with deps is acceptable —
@@ -596,10 +1313,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;
     };
@@ -627,29 +1347,72 @@ 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 readOptionalProjectFile = useCallback(async (path: string): Promise<string> => {
+    const pid = projectIdRef.current;
+    if (!pid) throw new Error("No active project");
+    const response = await fetch(`/api/projects/${pid}/files/${encodeURIComponent(path)}`);
+    if (response.status === 404) return "";
+    if (!response.ok) throw new Error(`Failed to read ${path}`);
+    const data = (await response.json()) as { content?: string };
+    return typeof data.content === "string" ? data.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;
@@ -728,25 +1491,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(
@@ -818,25 +1575,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") => {
@@ -852,6 +1603,7 @@ export function StudioApp() {
 
       const currentTime = usePlayerStore.getState().currentTime;
       setCaptureFrameTime(currentTime);
+      await waitForPendingDomEditSaves();
       const href = buildFrameCaptureUrl({
         projectId,
         compositionPath: activeCompPath,
@@ -878,7 +1630,7 @@ export function StudioApp() {
         showToast(message);
       }
     },
-    [activeCompPath, projectId, showToast],
+    [activeCompPath, projectId, showToast, waitForPendingDomEditSaves],
   );
 
   const handleTimelineElementDelete = useCallback(
@@ -961,21 +1713,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()
@@ -992,7 +1738,7 @@ export function StudioApp() {
         showToast(message);
       }
     },
-    [activeCompPath, showToast, timelineElements],
+    [activeCompPath, editHistory.recordEdit, showToast, timelineElements, writeProjectFile],
   );
 
   const handleBlockedTimelineEdit = useCallback(
@@ -1005,23 +1751,1532 @@ export function StudioApp() {
     [showToast],
   );
 
-  const refreshFileTree = useCallback(async () => {
-    const pid = projectIdRef.current;
-    if (!pid) return;
-    const res = await fetch(`/api/projects/${pid}`);
-    const data = await res.json();
-    if (data.files) setFileTree(data.files);
-  }, []);
+  const handleBlockedDomMove = useCallback(
+    (selection: DomEditSelection) => {
+      const now = Date.now();
+      if (now - lastBlockedDomMoveToastAtRef.current < 1500) return;
+      lastBlockedDomMoveToastAtRef.current = now;
+      showToast(
+        selection.capabilities.reasonIfDisabled ??
+          "This element can’t be adjusted directly from the preview.",
+        "info",
+      );
+    },
+    [showToast],
+  );
 
-  const uploadProjectFiles = useCallback(
-    async (files: Iterable<File>, dir?: string): Promise<string[]> => {
-      const pid = projectIdRef.current;
-      const fileList = Array.from(files);
-      if (!pid || fileList.length === 0) return [];
+  const applyDomSelection = useCallback(
+    (
+      selection: DomEditSelection | null,
+      options?: { revealPanel?: boolean; additive?: boolean; preserveGroup?: boolean },
+    ) => {
+      setAgentPromptTagSnippet(undefined);
+      setCopiedAgentPrompt(false);
+      if (!selection) {
+        domEditSelectionRef.current = null;
+        domEditGroupSelectionsRef.current = [];
+        setDomEditSelection(null);
+        setDomEditGroupSelections([]);
+        setSelectedTimelineElementId(null);
+        return;
+      }
+      if (!STUDIO_INSPECTOR_PANELS_ENABLED) {
+        domEditSelectionRef.current = null;
+        domEditGroupSelectionsRef.current = [];
+        setDomEditSelection(null);
+        setDomEditGroupSelections([]);
+        setSelectedTimelineElementId(null);
+        return;
+      }
 
-      const formData = new FormData();
-      for (const file of fileList) {
-        formData.append("file", file);
+      const isAdditiveSelection = Boolean(options?.additive);
+      const currentSelection = domEditSelectionRef.current;
+      const previousGroup = domEditGroupSelectionsRef.current;
+      const currentGroup = isAdditiveSelection
+        ? seedDomEditGroupWithSelection(previousGroup, currentSelection)
+        : previousGroup;
+      const wasInGroup = domEditSelectionInGroup(currentGroup, selection);
+      const nextGroup = options?.preserveGroup
+        ? replaceDomEditGroupSelection(currentGroup, selection)
+        : isAdditiveSelection
+          ? toggleDomEditGroupSelection(currentGroup, selection)
+          : [selection];
+      const nextSelection = options?.preserveGroup
+        ? selection
+        : isAdditiveSelection && wasInGroup
+          ? domEditSelectionsTargetSame(currentSelection, selection)
+            ? (nextGroup[0] ?? null)
+            : domEditSelectionInGroup(nextGroup, currentSelection)
+              ? currentSelection
+              : (nextGroup[0] ?? null)
+          : selection;
+
+      domEditSelectionRef.current = nextSelection;
+      domEditGroupSelectionsRef.current = nextGroup;
+      setDomEditSelection(nextSelection);
+      setDomEditGroupSelections(nextGroup);
+
+      if (nextSelection) {
+        if (options?.revealPanel !== false) {
+          setRightCollapsed(false);
+          setRightPanelTab("design");
+        }
+        const nextSelectedTimelineId = findMatchingTimelineElementId(
+          nextSelection,
+          timelineElements,
+        );
+        setSelectedTimelineElementId(nextSelectedTimelineId);
+        return;
+      }
+
+      setSelectedTimelineElementId(null);
+    },
+    [setSelectedTimelineElementId, timelineElements],
+  );
+
+  const clearDomSelection = useCallback(() => {
+    applyDomSelection(null, { revealPanel: false });
+  }, [applyDomSelection]);
+
+  const readHistoryProjectFile = useCallback(
+    async (path: string): Promise<string> => {
+      return path === STUDIO_MANUAL_EDITS_PATH || path === STUDIO_MOTION_PATH
+        ? readOptionalProjectFile(path)
+        : readProjectFile(path);
+    },
+    [readOptionalProjectFile, readProjectFile],
+  );
+
+  const writeHistoryProjectFile = useCallback(
+    async (path: string, content: string): Promise<void> => {
+      await writeProjectFile(path, content);
+      if (path === STUDIO_MANUAL_EDITS_PATH || path === STUDIO_MOTION_PATH) {
+        domEditSaveTimestampRef.current = Date.now();
+      }
+    },
+    [writeProjectFile],
+  );
+
+  const applyCurrentStudioManualEditsToPreview = useCallback(
+    (iframe: HTMLIFrameElement | null = previewIframeRef.current) => {
+      if (!iframe) return;
+      let doc: Document | null = null;
+      try {
+        doc = iframe.contentDocument;
+      } catch {
+        return;
+      }
+      if (!doc) return;
+      const previewDoc = doc;
+
+      const applyManifest = () => {
+        applyStudioManualEditManifest(
+          previewDoc,
+          studioManualEditManifestRef.current,
+          activeCompPathRef.current,
+        );
+      };
+      const applyAndInstallSeekHooks = () => {
+        applyManifest();
+        if (iframe.contentWindow) {
+          installStudioManualEditSeekReapply(iframe.contentWindow, applyManifest);
+        }
+      };
+
+      const win = iframe.contentWindow;
+      applyAndInstallSeekHooks();
+      win?.requestAnimationFrame?.(applyAndInstallSeekHooks);
+      win?.setTimeout?.(applyAndInstallSeekHooks, 80);
+      win?.setTimeout?.(applyAndInstallSeekHooks, 250);
+      win?.setTimeout?.(applyAndInstallSeekHooks, 500);
+      win?.setTimeout?.(applyAndInstallSeekHooks, 1000);
+      win?.setTimeout?.(applyAndInstallSeekHooks, 2000);
+    },
+    [],
+  );
+
+  const applyStudioManualEditsToPreview = useCallback(
+    async (
+      iframe: HTMLIFrameElement | null = previewIframeRef.current,
+      options?: { forceFromDisk?: boolean; readFromDiskFirst?: boolean },
+    ) => {
+      const readRevision = studioManualEditRevisionRef.current;
+      const readFromDiskFirst = Boolean(options?.forceFromDisk || options?.readFromDiskFirst);
+      if (!readFromDiskFirst) {
+        applyCurrentStudioManualEditsToPreview(iframe);
+      }
+      let content: string;
+      try {
+        content = await readOptionalProjectFile(STUDIO_MANUAL_EDITS_PATH);
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : "Failed to read manual edit manifest";
+        showToast(message);
+        if (readFromDiskFirst) {
+          applyCurrentStudioManualEditsToPreview(iframe);
+        }
+        return;
+      }
+      if (options?.forceFromDisk || readRevision === studioManualEditRevisionRef.current) {
+        studioManualEditManifestRef.current = parseStudioManualEditManifest(content);
+        if (options?.forceFromDisk) studioManualEditRevisionRef.current += 1;
+        applyCurrentStudioManualEditsToPreview(iframe);
+        return;
+      }
+      if (readFromDiskFirst) {
+        applyCurrentStudioManualEditsToPreview(iframe);
+      }
+    },
+    [applyCurrentStudioManualEditsToPreview, readOptionalProjectFile, showToast],
+  );
+  applyStudioManualEditsToPreviewRef.current = applyStudioManualEditsToPreview;
+
+  const applyStudioManualEditsToPreviewAfterRefresh = useCallback(
+    (iframe: HTMLIFrameElement | null = previewIframeRef.current) =>
+      applyStudioManualEditsToPreview(iframe, { readFromDiskFirst: true }),
+    [applyStudioManualEditsToPreview],
+  );
+
+  const applyCurrentStudioMotionToPreview = useCallback(
+    (iframe: HTMLIFrameElement | null = previewIframeRef.current) => {
+      if (!iframe) return;
+      let doc: Document | null = null;
+      try {
+        doc = iframe.contentDocument;
+      } catch {
+        return;
+      }
+      if (!doc) return;
+      const previewDoc = doc;
+
+      const applyManifest = () => {
+        applyStudioMotionManifest(
+          previewDoc,
+          studioMotionManifestRef.current,
+          activeCompPathRef.current,
+        );
+      };
+      const applyAndInstallSeekHooks = () => {
+        applyManifest();
+        if (iframe.contentWindow) {
+          installStudioMotionSeekReapply(iframe.contentWindow, applyManifest);
+        }
+      };
+
+      const win = iframe.contentWindow;
+      win?.requestAnimationFrame?.(applyAndInstallSeekHooks);
+      win?.setTimeout?.(applyAndInstallSeekHooks, 120);
+    },
+    [],
+  );
+
+  const applyStudioMotionToPreview = useCallback(
+    async (
+      iframe: HTMLIFrameElement | null = previewIframeRef.current,
+      options?: { forceFromDisk?: boolean; readFromDiskFirst?: boolean },
+    ) => {
+      const readRevision = studioMotionRevisionRef.current;
+      const readFromDiskFirst = Boolean(options?.forceFromDisk || options?.readFromDiskFirst);
+      if (!readFromDiskFirst) {
+        applyCurrentStudioMotionToPreview(iframe);
+      }
+      let content: string;
+      try {
+        content = await readOptionalProjectFile(STUDIO_MOTION_PATH);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Failed to read motion manifest";
+        showToast(message);
+        if (readFromDiskFirst) {
+          applyCurrentStudioMotionToPreview(iframe);
+        }
+        return;
+      }
+      if (options?.forceFromDisk || readRevision === studioMotionRevisionRef.current) {
+        studioMotionManifestRef.current = parseStudioMotionManifest(content);
+        if (options?.forceFromDisk) studioMotionRevisionRef.current += 1;
+        setStudioMotionRevision((revision) => revision + 1);
+        applyCurrentStudioMotionToPreview(iframe);
+        return;
+      }
+      if (readFromDiskFirst) {
+        applyCurrentStudioMotionToPreview(iframe);
+      }
+    },
+    [applyCurrentStudioMotionToPreview, readOptionalProjectFile, showToast],
+  );
+  applyStudioMotionToPreviewRef.current = applyStudioMotionToPreview;
+
+  const applyStudioMotionToPreviewAfterRefresh = useCallback(
+    (iframe: HTMLIFrameElement | null = previewIframeRef.current) =>
+      applyStudioMotionToPreview(iframe, { readFromDiskFirst: true }),
+    [applyStudioMotionToPreview],
+  );
+
+  const commitStudioManualEditManifestOptimistically = useCallback(
+    (
+      updateManifest: (manifest: StudioManualEditManifest) => StudioManualEditManifest,
+      options: { label: string; coalesceKey: string },
+    ) => {
+      const previousManifest = studioManualEditManifestRef.current;
+      const nextManifest = updateManifest(previousManifest);
+      const previousContent = serializeStudioManualEditManifest(previousManifest);
+      const nextContent = serializeStudioManualEditManifest(nextManifest);
+      if (nextContent === previousContent) {
+        return;
+      }
+
+      const revision = studioManualEditRevisionRef.current + 1;
+      studioManualEditRevisionRef.current = revision;
+      studioManualEditManifestRef.current = nextManifest;
+      applyCurrentStudioManualEditsToPreview(previewIframeRef.current);
+
+      const save = async () => {
+        const originalContent = await readOptionalProjectFile(STUDIO_MANUAL_EDITS_PATH);
+        const diskManifest = parseStudioManualEditManifest(originalContent);
+        const nextDiskManifest = updateManifest(diskManifest);
+        const nextDiskContent = serializeStudioManualEditManifest(nextDiskManifest);
+        if (nextDiskContent === originalContent) {
+          return;
+        }
+
+        const pid = projectIdRef.current;
+        if (!pid) throw new Error("No active project");
+        domEditSaveTimestampRef.current = Date.now();
+        await saveProjectFilesWithHistory({
+          projectId: pid,
+          label: options.label,
+          kind: "manual",
+          coalesceKey: options.coalesceKey,
+          files: { [STUDIO_MANUAL_EDITS_PATH]: nextDiskContent },
+          readFile: async () => originalContent,
+          writeFile: writeProjectFile,
+          recordEdit: editHistory.recordEdit,
+        });
+        domEditSaveTimestampRef.current = Date.now();
+
+        if (studioManualEditRevisionRef.current === revision) {
+          studioManualEditManifestRef.current = nextDiskManifest;
+          applyCurrentStudioManualEditsToPreview(previewIframeRef.current);
+        }
+      };
+
+      void queueDomEditSave(save).catch((error) => {
+        if (studioManualEditRevisionRef.current === revision) {
+          studioManualEditRevisionRef.current += 1;
+          studioManualEditManifestRef.current = previousManifest;
+          applyCurrentStudioManualEditsToPreview(previewIframeRef.current);
+        }
+        const message = error instanceof Error ? error.message : "Failed to save manual edit";
+        showToast(message);
+      });
+    },
+    [
+      applyCurrentStudioManualEditsToPreview,
+      editHistory.recordEdit,
+      queueDomEditSave,
+      readOptionalProjectFile,
+      showToast,
+      writeProjectFile,
+    ],
+  );
+
+  const commitStudioMotionManifestOptimistically = useCallback(
+    (
+      updateManifest: (manifest: StudioMotionManifest) => StudioMotionManifest,
+      options: { label: string; coalesceKey: string },
+    ) => {
+      const previousManifest = studioMotionManifestRef.current;
+      const nextManifest = updateManifest(previousManifest);
+      const previousContent = serializeStudioMotionManifest(previousManifest);
+      const nextContent = serializeStudioMotionManifest(nextManifest);
+      if (nextContent === previousContent) {
+        return;
+      }
+
+      const revision = studioMotionRevisionRef.current + 1;
+      studioMotionRevisionRef.current = revision;
+      studioMotionManifestRef.current = nextManifest;
+      setStudioMotionRevision((current) => current + 1);
+      applyCurrentStudioMotionToPreview(previewIframeRef.current);
+
+      const save = async () => {
+        const originalContent = await readOptionalProjectFile(STUDIO_MOTION_PATH);
+        const diskManifest = parseStudioMotionManifest(originalContent);
+        const nextDiskManifest = updateManifest(diskManifest);
+        const nextDiskContent = serializeStudioMotionManifest(nextDiskManifest);
+        if (nextDiskContent === originalContent) {
+          return;
+        }
+
+        const pid = projectIdRef.current;
+        if (!pid) throw new Error("No active project");
+        domEditSaveTimestampRef.current = Date.now();
+        await saveProjectFilesWithHistory({
+          projectId: pid,
+          label: options.label,
+          kind: "motion",
+          coalesceKey: options.coalesceKey,
+          files: { [STUDIO_MOTION_PATH]: nextDiskContent },
+          readFile: async () => originalContent,
+          writeFile: writeProjectFile,
+          recordEdit: editHistory.recordEdit,
+        });
+        domEditSaveTimestampRef.current = Date.now();
+
+        if (studioMotionRevisionRef.current === revision) {
+          studioMotionManifestRef.current = nextDiskManifest;
+          setStudioMotionRevision((current) => current + 1);
+          applyCurrentStudioMotionToPreview(previewIframeRef.current);
+        }
+      };
+
+      void queueDomEditSave(save).catch((error) => {
+        if (studioMotionRevisionRef.current === revision) {
+          studioMotionRevisionRef.current += 1;
+          studioMotionManifestRef.current = previousManifest;
+          setStudioMotionRevision((current) => current + 1);
+          applyCurrentStudioMotionToPreview(previewIframeRef.current);
+        }
+        const message = error instanceof Error ? error.message : "Failed to save motion edit";
+        showToast(message);
+      });
+    },
+    [
+      applyCurrentStudioMotionToPreview,
+      editHistory.recordEdit,
+      queueDomEditSave,
+      readOptionalProjectFile,
+      showToast,
+      writeProjectFile,
+    ],
+  );
+
+  const syncHistoryPreviewAfterApply = useCallback(
+    async (paths: string[] | undefined) => {
+      const changedPaths = paths ?? [];
+      const manualManifestOnly =
+        changedPaths.length > 0 && changedPaths.every((path) => path === STUDIO_MANUAL_EDITS_PATH);
+      const motionManifestOnly =
+        changedPaths.length > 0 && changedPaths.every((path) => path === STUDIO_MOTION_PATH);
+
+      if (manualManifestOnly) {
+        await applyStudioManualEditsToPreview(previewIframeRef.current, { forceFromDisk: true });
+        return;
+      }
+      if (motionManifestOnly) {
+        await applyStudioMotionToPreview(previewIframeRef.current, { forceFromDisk: true });
+        return;
+      }
+
+      setRefreshKey((key) => key + 1);
+    },
+    [applyStudioManualEditsToPreview, applyStudioMotionToPreview],
+  );
+
+  const handleUndo = useCallback(async () => {
+    await waitForPendingDomEditSaves();
+    const result = await editHistory.undo({
+      readFile: readHistoryProjectFile,
+      writeFile: writeHistoryProjectFile,
+    });
+    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();
+      await syncHistoryPreviewAfterApply(result.paths);
+      showToast(`Undid ${result.label}`, "info");
+    }
+  }, [
+    clearDomSelection,
+    editHistory,
+    readHistoryProjectFile,
+    showToast,
+    syncHistoryPreviewAfterApply,
+    waitForPendingDomEditSaves,
+    writeHistoryProjectFile,
+  ]);
+
+  const handleRedo = useCallback(async () => {
+    await waitForPendingDomEditSaves();
+    const result = await editHistory.redo({
+      readFile: readHistoryProjectFile,
+      writeFile: writeHistoryProjectFile,
+    });
+    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();
+      await syncHistoryPreviewAfterApply(result.paths);
+      showToast(`Redid ${result.label}`, "info");
+    }
+  }, [
+    clearDomSelection,
+    editHistory,
+    readHistoryProjectFile,
+    showToast,
+    syncHistoryPreviewAfterApply,
+    waitForPendingDomEditSaves,
+    writeHistoryProjectFile,
+  ]);
+
+  const handleUndoRef = useRef(handleUndo);
+  const handleRedoRef = useRef(handleRedo);
+  handleUndoRef.current = handleUndo;
+  handleRedoRef.current = handleRedo;
+
+  const handleHistoryHotkey = useCallback((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();
+    }
+  }, []);
+
+  // 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?.();
+      previewHistoryHotkeyCleanupRef.current = null;
+
+      const win = iframe?.contentWindow ?? null;
+      let doc: Document | null = null;
+      try {
+        doc = iframe?.contentDocument ?? null;
+      } catch {
+        doc = null;
+      }
+      if (!win && !doc) return;
+
+      win?.addEventListener("keydown", handleHistoryHotkey, true);
+      doc?.addEventListener("keydown", handleHistoryHotkey, true);
+      previewHistoryHotkeyCleanupRef.current = () => {
+        win?.removeEventListener("keydown", handleHistoryHotkey, true);
+        doc?.removeEventListener("keydown", handleHistoryHotkey, true);
+      };
+    },
+    [handleHistoryHotkey],
+  );
+
+  useEffect(
+    () => () => {
+      previewHistoryHotkeyCleanupRef.current?.();
+      previewHistoryHotkeyCleanupRef.current = null;
+    },
+    [],
+  );
+
+  const buildDomSelectionFromTarget = useCallback(
+    (target: HTMLElement, options?: { preferClipAncestor?: boolean }) => {
+      return resolveDomEditSelection(target, {
+        activeCompositionPath: activeCompPath,
+        isMasterView,
+        preferClipAncestor: options?.preferClipAncestor,
+      });
+    },
+    [activeCompPath, isMasterView],
+  );
+
+  const resolveDomSelectionFromPreviewPoint = useCallback(
+    (clientX: number, clientY: number, options?: { preferClipAncestor?: boolean }) => {
+      const iframe = previewIframeRef.current;
+      if (!iframe || captionEditMode) return null;
+      const target = getPreviewTargetFromPointer(iframe, clientX, clientY);
+      if (!target) return null;
+      return buildDomSelectionFromTarget(target, {
+        preferClipAncestor: options?.preferClipAncestor,
+      });
+    },
+    [buildDomSelectionFromTarget, captionEditMode],
+  );
+
+  const updateDomEditHoverSelection = useCallback((selection: DomEditSelection | null) => {
+    if (domEditSelectionsTargetSame(domEditHoverSelectionRef.current, selection)) return;
+    domEditHoverSelectionRef.current = selection;
+    setDomEditHoverSelection(selection);
+  }, []);
+
+  const buildDomSelectionForTimelineElement = useCallback(
+    (element: TimelineElement): DomEditSelection | null => {
+      const iframe = previewIframeRef.current;
+      let doc: Document | null = null;
+      try {
+        doc = iframe?.contentDocument ?? null;
+      } catch {
+        return null;
+      }
+      if (!doc) return null;
+
+      const targetElement = findElementForTimelineElement(doc, element, {
+        activeCompositionPath: activeCompPath,
+        compIdToSrc,
+        isMasterView,
+      });
+      return targetElement
+        ? buildDomSelectionFromTarget(targetElement, { preferClipAncestor: false })
+        : null;
+    },
+    [activeCompPath, buildDomSelectionFromTarget, compIdToSrc, isMasterView],
+  );
+
+  const inspectedTimelineElement = useMemo(
+    () =>
+      timelineElements.find(
+        (element) => getTimelineElementKey(element) === inspectedTimelineElementId,
+      ) ?? null,
+    [inspectedTimelineElementId, timelineElements],
+  );
+
+  const timelineLayerChildCounts = useMemo(() => {
+    void previewDocumentVersion;
+    const counts = new Map<string, number>();
+    if (!STUDIO_TIMELINE_LAYER_INSPECTOR_ENABLED || !inspectedTimelineElement) return counts;
+
+    const key = getTimelineElementKey(inspectedTimelineElement);
+    if (key) {
+      const selection = buildDomSelectionForTimelineElement(inspectedTimelineElement);
+      const count = countDomEditChildLayers(selection?.element, {
+        activeCompositionPath: activeCompPath,
+        isMasterView,
+      });
+      if (count > 0) counts.set(key, count);
+    }
+
+    return counts;
+  }, [
+    activeCompPath,
+    buildDomSelectionForTimelineElement,
+    inspectedTimelineElement,
+    isMasterView,
+    previewDocumentVersion,
+  ]);
+
+  const inspectedTimelineLayers = useMemo(() => {
+    void previewDocumentVersion;
+    if (!STUDIO_TIMELINE_LAYER_INSPECTOR_ENABLED || !inspectedTimelineElement) return [];
+    const selection = buildDomSelectionForTimelineElement(inspectedTimelineElement);
+    return collectDomEditLayerItems(selection?.element, {
+      activeCompositionPath: activeCompPath,
+      isMasterView,
+    });
+  }, [
+    activeCompPath,
+    buildDomSelectionForTimelineElement,
+    inspectedTimelineElement,
+    isMasterView,
+    previewDocumentVersion,
+  ]);
+
+  const selectedTimelineLayerKey = useMemo(
+    () => (domEditSelection ? getDomEditLayerKey(domEditSelection) : null),
+    [domEditSelection],
+  );
+
+  const handleTimelineElementSelect = useCallback(
+    (element: TimelineElement | null) => {
+      if (!STUDIO_INSPECTOR_PANELS_ENABLED) return;
+      if (!element) {
+        applyDomSelection(null, { revealPanel: false });
+        setInspectedTimelineElementId(null);
+        return;
+      }
+
+      const selection = buildDomSelectionForTimelineElement(element);
+      if (selection) applyDomSelection(selection);
+    },
+    [applyDomSelection, buildDomSelectionForTimelineElement],
+  );
+
+  const handleTimelineElementInspect = useCallback(
+    (element: TimelineElement) => {
+      if (!STUDIO_TIMELINE_LAYER_INSPECTOR_ENABLED || !STUDIO_INSPECTOR_PANELS_ENABLED) return;
+      if (!canInspectTimelineElement(element)) {
+        showToast("Audio clips do not have visual layers.", "info");
+        return;
+      }
+
+      const key = getTimelineElementKey(element);
+      if (!key) return;
+      setInspectedTimelineElementId((current) => (current === key ? null : key));
+      setLeftCollapsed(false);
+
+      const iframe = previewIframeRef.current;
+      if (!shouldShowTimelineInspectorBounds(currentTime, element)) {
+        seekStudioPreview(iframe, element.start);
+      }
+
+      const selection = buildDomSelectionForTimelineElement(element);
+      if (selection) applyDomSelection(selection);
+    },
+    [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;
+
+      const iframe = previewIframeRef.current;
+      const player = getPreviewPlayer(iframe?.contentWindow);
+      const visibleTime = resolveLayerVisibleSeekTime(
+        layer.element,
+        inspectedTimelineElement,
+        player,
+      );
+      if (visibleTime != null) {
+        seekStudioPreview(iframe, visibleTime);
+      }
+
+      const selection = buildDomSelectionFromTarget(layer.element, { preferClipAncestor: false });
+      if (!selection) {
+        showToast("Studio could not resolve this nested layer.", "error");
+        return;
+      }
+
+      applyDomSelection(selection);
+      requestAnimationFrame(refreshPreviewDocumentVersion);
+    },
+    [
+      applyDomSelection,
+      buildDomSelectionFromTarget,
+      inspectedTimelineElement,
+      refreshPreviewDocumentVersion,
+      showToast,
+    ],
+  );
+
+  const handleTimelineLayerPanelClose = useCallback(() => {
+    setInspectedTimelineElementId(null);
+  }, []);
+
+  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);
+      if (!family) return null;
+      const imported = importedFontAssetsRef.current.find(
+        (font) => font.family.toLowerCase() === family.toLowerCase(),
+      );
+      if (imported) return imported;
+      const asset = fileTree.find(
+        (path) =>
+          FONT_EXT.test(path) &&
+          fontFamilyFromAssetPath(path).toLowerCase() === family.toLowerCase(),
+      );
+      if (!asset) return null;
+      return {
+        family: fontFamilyFromAssetPath(asset),
+        path: asset,
+        url: `/api/projects/${projectId}/preview/${asset}`,
+      };
+    },
+    [fileTree, projectId],
+  );
+
+  const persistDomEditOperations = useCallback(
+    async (
+      selection: DomEditSelection,
+      operations: Parameters<typeof applyPatchByTarget>[2][],
+      options?: {
+        label?: string;
+        coalesceKey?: string;
+        skipRefresh?: boolean;
+        prepareContent?: (html: string, sourceFile: string) => string;
+        shouldSave?: () => boolean;
+      },
+    ) => {
+      const pid = projectIdRef.current;
+      if (!pid) throw new Error("No active project");
+      if (options?.shouldSave && !options.shouldSave()) return;
+
+      const targetPath = selection.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 originalContent = data.content;
+      if (typeof originalContent !== "string") {
+        throw new Error(`Missing file contents for ${targetPath}`);
+      }
+
+      let patchedContent = originalContent;
+      for (const operation of operations) {
+        patchedContent = applyPatchByTarget(patchedContent, selection, operation);
+      }
+      if (options?.prepareContent) {
+        patchedContent = options.prepareContent(patchedContent, targetPath);
+      }
+      if (options?.shouldSave && !options.shouldSave()) return;
+
+      if (patchedContent === originalContent) {
+        throw new Error(`Unable to patch ${selection.selector ?? selection.id ?? "selection"}`);
+      }
+
+      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();
+      } else {
+        setRefreshKey((k) => k + 1);
+      }
+    },
+    [activeCompPath, editHistory.recordEdit, writeProjectFile],
+  );
+
+  const refreshDomEditSelectionFromPreview = useCallback(
+    (selection: DomEditSelection) => {
+      const iframe = previewIframeRef.current;
+      let doc: Document | null = null;
+      try {
+        doc = iframe?.contentDocument ?? null;
+      } catch {
+        return;
+      }
+      if (!doc) return;
+
+      const element = findElementForSelection(doc, selection, activeCompPath);
+      if (!element) return;
+
+      const nextSelection = buildDomSelectionFromTarget(element);
+      if (nextSelection) {
+        applyDomSelection(nextSelection, { revealPanel: false, preserveGroup: true });
+      }
+    },
+    [activeCompPath, applyDomSelection, buildDomSelectionFromTarget],
+  );
+
+  const refreshDomEditGroupSelectionsFromPreview = useCallback(
+    (selections: DomEditSelection[]) => {
+      const iframe = previewIframeRef.current;
+      let doc: Document | null = null;
+      try {
+        doc = iframe?.contentDocument ?? null;
+      } catch {
+        return;
+      }
+      if (!doc) return;
+
+      const nextGroup: DomEditSelection[] = [];
+      for (const selection of selections) {
+        const element = findElementForSelection(doc, selection, activeCompPath);
+        if (!element) continue;
+        const nextSelection = buildDomSelectionFromTarget(element);
+        if (nextSelection) nextGroup.push(nextSelection);
+      }
+      if (nextGroup.length === 0) return;
+
+      const currentSelection = domEditSelectionRef.current;
+      const nextSelection =
+        nextGroup.find((selection) => domEditSelectionsTargetSame(selection, currentSelection)) ??
+        nextGroup[0] ??
+        null;
+
+      setAgentPromptTagSnippet(undefined);
+      setCopiedAgentPrompt(false);
+      domEditSelectionRef.current = nextSelection;
+      domEditGroupSelectionsRef.current = nextGroup;
+      setDomEditSelection(nextSelection);
+      setDomEditGroupSelections(nextGroup);
+
+      if (nextSelection) {
+        setSelectedTimelineElementId(
+          findMatchingTimelineElementId(nextSelection, timelineElements),
+        );
+      } else {
+        setSelectedTimelineElementId(null);
+      }
+    },
+    [activeCompPath, buildDomSelectionFromTarget, setSelectedTimelineElementId, timelineElements],
+  );
+
+  const handleDomManualDragStart = useCallback(() => {
+    const pausedTime = pauseStudioPreviewPlayback(previewIframeRef.current);
+    const playerStore = usePlayerStore.getState();
+    playerStore.setIsPlaying(false);
+    if (pausedTime != null) {
+      playerStore.setCurrentTime(pausedTime);
+      liveTime.notify(pausedTime);
+    }
+  }, []);
+
+  const handleDomPathOffsetCommit = useCallback(
+    (selection: DomEditSelection, next: { x: number; y: number }) => {
+      commitStudioManualEditManifestOptimistically(
+        (manifest) => upsertStudioPathOffsetEdit(manifest, selection, next),
+        {
+          label: "Move layer",
+          coalesceKey: `path-offset:${getDomEditTargetKey(selection)}`,
+        },
+      );
+      refreshDomEditSelectionFromPreview(selection);
+    },
+    [commitStudioManualEditManifestOptimistically, refreshDomEditSelectionFromPreview],
+  );
+
+  const handleDomGroupPathOffsetCommit = useCallback(
+    (updates: DomEditGroupPathOffsetCommit[]) => {
+      if (updates.length === 0) return;
+      const coalesceKey = updates
+        .map((update) => getDomEditTargetKey(update.selection))
+        .sort()
+        .join(":");
+      commitStudioManualEditManifestOptimistically(
+        (manifest) =>
+          updates.reduce(
+            (nextManifest, update) =>
+              upsertStudioPathOffsetEdit(nextManifest, update.selection, update.next),
+            manifest,
+          ),
+        {
+          label: `Move ${updates.length} layers`,
+          coalesceKey: `group-path-offset:${coalesceKey}`,
+        },
+      );
+      refreshDomEditGroupSelectionsFromPreview(domEditGroupSelectionsRef.current);
+    },
+    [commitStudioManualEditManifestOptimistically, refreshDomEditGroupSelectionsFromPreview],
+  );
+
+  const handleDomBoxSizeCommit = useCallback(
+    (selection: DomEditSelection, next: { width: number; height: number }) => {
+      commitStudioManualEditManifestOptimistically(
+        (manifest) => upsertStudioBoxSizeEdit(manifest, selection, next),
+        {
+          label: "Resize layer box",
+          coalesceKey: `box-size:${getDomEditTargetKey(selection)}`,
+        },
+      );
+      refreshDomEditSelectionFromPreview(selection);
+    },
+    [commitStudioManualEditManifestOptimistically, refreshDomEditSelectionFromPreview],
+  );
+
+  const handleDomRotationCommit = useCallback(
+    (selection: DomEditSelection, next: { angle: number }) => {
+      commitStudioManualEditManifestOptimistically(
+        (manifest) => upsertStudioRotationEdit(manifest, selection, next),
+        {
+          label: "Rotate layer",
+          coalesceKey: `rotation:${getDomEditTargetKey(selection)}`,
+        },
+      );
+      refreshDomEditSelectionFromPreview(selection);
+    },
+    [commitStudioManualEditManifestOptimistically, refreshDomEditSelectionFromPreview],
+  );
+
+  const handleDomManualEditsReset = useCallback(
+    (selection: DomEditSelection) => {
+      commitStudioManualEditManifestOptimistically(
+        (manifest) => removeStudioManualEditsForSelection(manifest, selection),
+        {
+          label: "Reset layer edits",
+          coalesceKey: `manual-reset:${getDomEditTargetKey(selection)}`,
+        },
+      );
+      applyCurrentStudioManualEditsToPreview(previewIframeRef.current);
+      refreshDomEditSelectionFromPreview(selection);
+    },
+    [
+      applyCurrentStudioManualEditsToPreview,
+      commitStudioManualEditManifestOptimistically,
+      refreshDomEditSelectionFromPreview,
+    ],
+  );
+
+  const handleDomMotionCommit = useCallback(
+    (
+      selection: DomEditSelection,
+      motion: Omit<StudioGsapMotion, "kind" | "target" | "updatedAt">,
+    ) => {
+      commitStudioMotionManifestOptimistically(
+        (manifest) => upsertStudioGsapMotion(manifest, selection, motion),
+        {
+          label: "Set GSAP motion",
+          coalesceKey: `motion:${getDomEditTargetKey(selection)}`,
+        },
+      );
+      refreshDomEditSelectionFromPreview(selection);
+    },
+    [commitStudioMotionManifestOptimistically, refreshDomEditSelectionFromPreview],
+  );
+
+  const handleDomMotionClear = useCallback(
+    (selection: DomEditSelection) => {
+      commitStudioMotionManifestOptimistically(
+        (manifest) => removeStudioMotionForSelection(manifest, selection),
+        {
+          label: "Clear GSAP motion",
+          coalesceKey: `motion:${getDomEditTargetKey(selection)}`,
+        },
+      );
+      applyCurrentStudioMotionToPreview(previewIframeRef.current);
+      refreshDomEditSelectionFromPreview(selection);
+    },
+    [
+      applyCurrentStudioMotionToPreview,
+      commitStudioMotionManifestOptimistically,
+      refreshDomEditSelectionFromPreview,
+    ],
+  );
+
+  const handleDomStyleCommit = useCallback(
+    async (property: string, value: string) => {
+      if (!domEditSelection) return;
+      if (isManualGeometryStyleProperty(property)) return;
+      if (!domEditSelection.capabilities.canEditStyles) return;
+      const importedFont = property === "font-family" ? resolveImportedFontAsset(value) : null;
+      const iframe = previewIframeRef.current;
+      const doc = iframe?.contentDocument;
+      if (doc) {
+        const el = findElementForSelection(doc, domEditSelection, activeCompPath);
+        if (el) {
+          el.style.setProperty(property, normalizeDomEditStyleValue(property, value));
+          if (property === "font-family") {
+            injectPreviewGoogleFont(doc, value);
+            if (importedFont) injectPreviewImportedFont(doc, importedFont);
+          }
+          if (property === "background-image" && isImageBackgroundValue(value)) {
+            el.style.setProperty("background-position", "center");
+            el.style.setProperty("background-repeat", "no-repeat");
+            el.style.setProperty("background-size", "contain");
+          }
+        }
+      }
+      const operations: PatchOperation[] = [
+        buildDomEditStylePatchOperation(property, normalizeDomEditStyleValue(property, value)),
+      ];
+      if (property === "background-image" && isImageBackgroundValue(value)) {
+        operations.push(
+          buildDomEditStylePatchOperation("background-position", "center"),
+          buildDomEditStylePatchOperation("background-repeat", "no-repeat"),
+          buildDomEditStylePatchOperation("background-size", "contain"),
+        );
+      }
+      await persistDomEditOperations(domEditSelection, operations, {
+        label: "Edit layer style",
+        skipRefresh: true,
+        prepareContent: importedFont
+          ? (html, sourceFile) => ensureImportedFontFace(html, importedFont, sourceFile)
+          : undefined,
+      });
+    },
+    [activeCompPath, domEditSelection, persistDomEditOperations, resolveImportedFontAsset],
+  );
+
+  const handleDomTextCommit = useCallback(
+    async (value: string, fieldKey?: string) => {
+      if (!domEditSelection) return;
+      if (!isTextEditableSelection(domEditSelection)) return;
+      const commitVersion = domTextCommitVersionRef.current + 1;
+      domTextCommitVersionRef.current = commitVersion;
+      const nextTextFields =
+        domEditSelection.textFields.length > 0
+          ? domEditSelection.textFields.map((field) =>
+              field.key === fieldKey ? { ...field, value } : field,
+            )
+          : [];
+      const nextContent =
+        nextTextFields.length > 1 || nextTextFields.some((field) => field.source === "child")
+          ? serializeDomEditTextFields(nextTextFields)
+          : value;
+      const iframe = previewIframeRef.current;
+      const doc = iframe?.contentDocument;
+      if (doc) {
+        const el = findElementForSelection(doc, domEditSelection, activeCompPath);
+        if (el) {
+          if (
+            nextTextFields.length > 1 ||
+            nextTextFields.some((field) => field.source === "child")
+          ) {
+            el.innerHTML = nextContent;
+          } else {
+            el.textContent = value;
+          }
+        }
+      }
+      await persistDomEditOperations(
+        domEditSelection,
+        [buildDomEditTextPatchOperation(nextContent)],
+        {
+          label: "Edit text",
+          skipRefresh: true,
+          shouldSave: () => domTextCommitVersionRef.current === commitVersion,
+        },
+      );
+      if (domTextCommitVersionRef.current !== commitVersion) return;
+
+      if (doc) {
+        const refreshed = findElementForSelection(doc, domEditSelection, activeCompPath);
+        if (refreshed) {
+          const nextSelection = buildDomSelectionFromTarget(refreshed);
+          if (nextSelection) {
+            applyDomSelection(nextSelection, { revealPanel: false, preserveGroup: true });
+          }
+        }
+      }
+    },
+    [
+      activeCompPath,
+      applyDomSelection,
+      buildDomSelectionFromTarget,
+      domEditSelection,
+      persistDomEditOperations,
+    ],
+  );
+
+  const commitDomTextFields = useCallback(
+    async (
+      selection: DomEditSelection,
+      nextTextFields: DomEditTextField[],
+      options?: { importedFont?: ImportedFontAsset | null },
+    ) => {
+      const nextContent =
+        nextTextFields.length > 1 || nextTextFields.some((field) => field.source === "child")
+          ? serializeDomEditTextFields(nextTextFields)
+          : (nextTextFields[0]?.value ?? "");
+
+      const iframe = previewIframeRef.current;
+      const doc = iframe?.contentDocument;
+      if (doc) {
+        const el = findElementForSelection(doc, selection, activeCompPath);
+        if (el) {
+          if (
+            nextTextFields.length > 1 ||
+            nextTextFields.some((field) => field.source === "child")
+          ) {
+            el.innerHTML = nextContent;
+          } else {
+            el.textContent = nextContent;
+          }
+        }
+      }
+
+      const importedFont = options?.importedFont ?? null;
+      await persistDomEditOperations(selection, [buildDomEditTextPatchOperation(nextContent)], {
+        label: "Edit text",
+        skipRefresh: true,
+        prepareContent: importedFont
+          ? (html, sourceFile) => ensureImportedFontFace(html, importedFont, sourceFile)
+          : undefined,
+      });
+
+      if (doc) {
+        const refreshed = findElementForSelection(doc, selection, activeCompPath);
+        if (refreshed) {
+          const nextSelection = buildDomSelectionFromTarget(refreshed);
+          if (nextSelection) {
+            applyDomSelection(nextSelection, { revealPanel: false, preserveGroup: true });
+          }
+        }
+      }
+    },
+    [activeCompPath, applyDomSelection, buildDomSelectionFromTarget, persistDomEditOperations],
+  );
+
+  const handleDomTextFieldStyleCommit = useCallback(
+    async (fieldKey: string, property: string, value: string) => {
+      if (!domEditSelection) return;
+      const field = domEditSelection.textFields.find((entry) => entry.key === fieldKey);
+      if (!field) return;
+
+      if (field.source === "self") {
+        await handleDomStyleCommit(property, value);
+        return;
+      }
+
+      const normalizedValue = normalizeDomEditStyleValue(property, value);
+      const importedFont = property === "font-family" ? resolveImportedFontAsset(value) : null;
+      if (property === "font-family") {
+        const doc = previewIframeRef.current?.contentDocument;
+        if (doc) {
+          injectPreviewGoogleFont(doc, normalizedValue);
+          if (importedFont) injectPreviewImportedFont(doc, importedFont);
+        }
+      }
+      const nextTextFields = domEditSelection.textFields.map((entry) =>
+        entry.key === fieldKey
+          ? {
+              ...entry,
+              inlineStyles: {
+                ...entry.inlineStyles,
+                [property]: normalizedValue,
+              },
+              computedStyles: {
+                ...entry.computedStyles,
+                [property]: normalizedValue,
+              },
+            }
+          : entry,
+      );
+
+      await commitDomTextFields(domEditSelection, nextTextFields, { importedFont });
+    },
+    [commitDomTextFields, domEditSelection, handleDomStyleCommit, resolveImportedFontAsset],
+  );
+
+  const handleDomAddTextField = useCallback(
+    async (afterFieldKey?: string) => {
+      if (!domEditSelection) return null;
+      if (!domEditSelection.textFields.some((field) => field.source === "child")) return null;
+
+      const insertionIndex = domEditSelection.textFields.findIndex(
+        (field) => field.key === afterFieldKey,
+      );
+      const baseField =
+        domEditSelection.textFields[insertionIndex >= 0 ? insertionIndex : 0] ??
+        domEditSelection.textFields[0];
+      const nextField = buildDefaultDomEditTextField(baseField);
+      const nextTextFields = [...domEditSelection.textFields];
+      nextTextFields.splice(
+        insertionIndex >= 0 ? insertionIndex + 1 : nextTextFields.length,
+        0,
+        nextField,
+      );
+
+      await commitDomTextFields(domEditSelection, nextTextFields);
+      return nextField.key;
+    },
+    [commitDomTextFields, domEditSelection],
+  );
+
+  const handleDomRemoveTextField = useCallback(
+    async (fieldKey: string) => {
+      if (!domEditSelection) return;
+      const field = domEditSelection.textFields.find((entry) => entry.key === fieldKey);
+      if (!field) return;
+
+      if (field.source === "self") {
+        await handleDomTextCommit("", fieldKey);
+        return;
+      }
+
+      const nextTextFields = domEditSelection.textFields.filter((entry) => entry.key !== fieldKey);
+      await commitDomTextFields(domEditSelection, nextTextFields);
+    },
+    [commitDomTextFields, domEditSelection, handleDomTextCommit],
+  );
+
+  const handleAskAgent = useCallback(() => {
+    if (!domEditSelection) return;
+    setAgentPromptTagSnippet(undefined);
+    void preloadAgentPromptSnippet(domEditSelection);
+    setAgentModalOpen(true);
+  }, [domEditSelection, preloadAgentPromptSnippet]);
+
+  const handleAgentModalSubmit = useCallback(
+    async (userInstruction: string) => {
+      if (!domEditSelection) return;
+
+      const targetPath = domEditSelection.sourceFile || activeCompPath || "index.html";
+      const tagSnippet = agentPromptTagSnippet ?? domEditSelection.element.outerHTML;
+      const prompt = buildElementAgentPrompt({
+        selection: domEditSelection,
+        currentTime,
+        tagSnippet,
+        userInstruction,
+        sourceFilePath: toProjectAbsolutePath(projectDir, targetPath),
+      });
+
+      const copied = await copyTextToClipboard(prompt);
+      if (!copied) {
+        showToast("Could not copy prompt to clipboard.", "error");
+        return;
+      }
+
+      setAgentModalOpen(false);
+      if (copiedAgentTimerRef.current) clearTimeout(copiedAgentTimerRef.current);
+      setCopiedAgentPrompt(true);
+      copiedAgentTimerRef.current = setTimeout(() => setCopiedAgentPrompt(false), 1600);
+    },
+    [activeCompPath, agentPromptTagSnippet, currentTime, domEditSelection, projectDir, showToast],
+  );
+
+  const handlePreviewIframeRef = useCallback(
+    (iframe: HTMLIFrameElement | null) => {
+      previewIframeRef.current = iframe;
+      setPreviewIframe(iframe);
+      syncPreviewTimelineHotkey(iframe);
+      syncPreviewHistoryHotkey(iframe);
+      consoleErrorsRef.current = [];
+      setConsoleErrors(null);
+      refreshPreviewDocumentVersion();
+    },
+    [refreshPreviewDocumentVersion, syncPreviewHistoryHotkey, syncPreviewTimelineHotkey],
+  );
+
+  const handlePreviewCanvasMouseDown = useCallback(
+    (e: React.MouseEvent<HTMLDivElement>, options?: { preferClipAncestor?: boolean }) => {
+      if (!STUDIO_PREVIEW_MANUAL_EDITING_ENABLED || captionEditMode) return;
+      const nextSelection = resolveDomSelectionFromPreviewPoint(e.clientX, e.clientY, {
+        preferClipAncestor: options?.preferClipAncestor ?? true,
+      });
+      if (!nextSelection) {
+        if (!e.shiftKey) applyDomSelection(null, { revealPanel: false });
+        return;
+      }
+      e.preventDefault();
+      e.stopPropagation();
+      applyDomSelection(nextSelection, { additive: e.shiftKey });
+    },
+    [applyDomSelection, captionEditMode, resolveDomSelectionFromPreviewPoint],
+  );
+
+  const handlePreviewCanvasPointerMove = useCallback(
+    (e: React.PointerEvent<HTMLDivElement>, options?: { preferClipAncestor?: boolean }) => {
+      if (!STUDIO_PREVIEW_MANUAL_EDITING_ENABLED || captionEditMode) {
+        updateDomEditHoverSelection(null);
+        return null;
+      }
+
+      const nextSelection = resolveDomSelectionFromPreviewPoint(e.clientX, e.clientY, {
+        preferClipAncestor: options?.preferClipAncestor ?? false,
+      });
+      updateDomEditHoverSelection(nextSelection);
+      return nextSelection;
+    },
+    [captionEditMode, resolveDomSelectionFromPreviewPoint, updateDomEditHoverSelection],
+  );
+
+  const handlePreviewCanvasPointerLeave = useCallback(() => {
+    updateDomEditHoverSelection(null);
+  }, [updateDomEditHoverSelection]);
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (captionEditMode) updateDomEditHoverSelection(null);
+  }, [captionEditMode, updateDomEditHoverSelection]);
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    updateDomEditHoverSelection(null);
+  }, [activeCompPath, projectId, previewIframe, refreshKey, updateDomEditHoverSelection]);
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (!domEditHoverSelection) return;
+    const hoverMatchesSelection = domEditSelectionsTargetSame(
+      domEditHoverSelection,
+      domEditSelection,
+    );
+    const hoverMatchesGroup = domEditSelectionInGroup(
+      domEditGroupSelections,
+      domEditHoverSelection,
+    );
+    if (!hoverMatchesSelection && !hoverMatchesGroup) return;
+    updateDomEditHoverSelection(null);
+  }, [
+    domEditGroupSelections,
+    domEditHoverSelection,
+    domEditSelection,
+    updateDomEditHoverSelection,
+  ]);
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (!domEditHoverSelection) return;
+    if (domEditHoverSelection.element.isConnected) return;
+    updateDomEditHoverSelection(null);
+  }, [domEditHoverSelection, updateDomEditHoverSelection]);
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (!previewIframe) return;
+
+    const syncSelectionFromDocument = () => {
+      if (!STUDIO_INSPECTOR_PANELS_ENABLED || captionEditMode) return;
+      const currentSelection = domEditSelectionRef.current;
+      if (!currentSelection) return;
+      let doc: Document | null = null;
+      try {
+        doc = previewIframe.contentDocument;
+      } catch {
+        return;
+      }
+      if (!doc) return;
+
+      const nextElement = findElementForSelection(doc, currentSelection, activeCompPath);
+      if (!nextElement) {
+        applyDomSelection(null, { revealPanel: false });
+        return;
+      }
+
+      const nextSelection = buildDomSelectionFromTarget(nextElement);
+      if (nextSelection) {
+        applyDomSelection(nextSelection, { revealPanel: false, preserveGroup: true });
+      }
+    };
+
+    const attachErrorCapture = () => {
+      try {
+        const win = previewIframe.contentWindow as (Window & typeof globalThis) | null;
+        if (!win) return;
+        if ((win as unknown as Record<string, unknown>).__hfErrorCapture) return;
+        (win as unknown as Record<string, unknown>).__hfErrorCapture = true;
+        const origError = win.console.error.bind(win.console);
+        win.console.error = function (...args: unknown[]) {
+          origError(...args);
+          const text = args.map((a) => (a instanceof Error ? a.message : String(a))).join(" ");
+          if (text.includes("favicon")) return;
+          consoleErrorsRef.current = [
+            ...consoleErrorsRef.current,
+            { severity: "error", message: text },
+          ];
+          setConsoleErrors([...consoleErrorsRef.current]);
+        };
+        win.addEventListener("error", (e: ErrorEvent) => {
+          const text = e.message || String(e);
+          consoleErrorsRef.current = [
+            ...consoleErrorsRef.current,
+            { severity: "error", message: text },
+          ];
+          setConsoleErrors([...consoleErrorsRef.current]);
+        });
+      } catch {
+        // same-origin only
+      }
+    };
+
+    attachErrorCapture();
+    syncPreviewHistoryHotkey(previewIframe);
+    void (async () => {
+      await applyStudioManualEditsToPreviewAfterRefresh(previewIframe);
+      await applyStudioMotionToPreviewAfterRefresh(previewIframe);
+    })();
+    syncSelectionFromDocument();
+    refreshPreviewDocumentVersion();
+
+    const handleLoad = () => {
+      consoleErrorsRef.current = [];
+      setConsoleErrors(null);
+      attachErrorCapture();
+      syncPreviewHistoryHotkey(previewIframe);
+      void (async () => {
+        await applyStudioManualEditsToPreviewAfterRefresh(previewIframe);
+        await applyStudioMotionToPreviewAfterRefresh(previewIframe);
+      })();
+      syncSelectionFromDocument();
+      refreshPreviewDocumentVersion();
+    };
+
+    previewIframe.addEventListener("load", handleLoad);
+    return () => {
+      previewIframe.removeEventListener("load", handleLoad);
+    };
+  }, [
+    activeCompPath,
+    applyDomSelection,
+    applyStudioManualEditsToPreviewAfterRefresh,
+    applyStudioMotionToPreviewAfterRefresh,
+    buildDomSelectionFromTarget,
+    captionEditMode,
+    previewIframe,
+    refreshPreviewDocumentVersion,
+    syncPreviewHistoryHotkey,
+  ]);
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (!captionEditMode) return;
+    applyDomSelection(null, { revealPanel: false });
+  }, [applyDomSelection, captionEditMode]);
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (STUDIO_INSPECTOR_PANELS_ENABLED) return;
+    updateDomEditHoverSelection(null);
+    applyDomSelection(null, { revealPanel: false });
+    if (rightPanelTab !== "renders") setRightPanelTab("renders");
+  }, [applyDomSelection, rightPanelTab, updateDomEditHoverSelection]);
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(
+    () => () => {
+      if (copiedAgentTimerRef.current) clearTimeout(copiedAgentTimerRef.current);
+    },
+    [],
+  );
+
+  const refreshFileTree = useCallback(async () => {
+    const pid = projectIdRef.current;
+    if (!pid) return;
+    const res = await fetch(`/api/projects/${pid}`);
+    const data = await res.json();
+    if (data.files) setFileTree(data.files);
+  }, []);
+
+  const uploadProjectFiles = useCallback(
+    async (files: Iterable<File>, dir?: string): Promise<string[]> => {
+      const pid = projectIdRef.current;
+      const fileList = Array.from(files);
+      if (!pid || fileList.length === 0) return [];
+
+      const formData = new FormData();
+      for (const file of fileList) {
+        formData.append("file", file);
       }
 
       const qs = dir ? `?dir=${encodeURIComponent(dir)}` : "";
@@ -1138,24 +3393,19 @@ export function StudioApp() {
             duration: normalizedDuration,
             track: placement.track,
             zIndex: trackZIndices.get(placement.track) ?? 1,
+            geometry: resolveTimelineAssetInitialGeometry(originalContent),
           }),
         );
 
-        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) {
@@ -1164,7 +3414,7 @@ export function StudioApp() {
         showToast(message);
       }
     },
-    [activeCompPath, showToast, timelineElements],
+    [activeCompPath, editHistory.recordEdit, showToast, timelineElements, writeProjectFile],
   );
 
   const handleTimelineFileDrop = useCallback(
@@ -1322,7 +3572,33 @@ export function StudioApp() {
 
   const handleImportFiles = useCallback(
     async (files: FileList | File[], dir?: string) => {
-      void uploadProjectFiles(Array.from(files), dir);
+      return uploadProjectFiles(Array.from(files), dir);
+    },
+    [uploadProjectFiles],
+  );
+
+  const handleImportFonts = useCallback(
+    async (files: FileList | File[]) => {
+      const uploaded = await uploadProjectFiles(
+        Array.from(files).filter((file) => FONT_EXT.test(file.name)),
+        "assets/fonts",
+      );
+      const pid = projectIdRef.current;
+      const imported = uploaded
+        .filter((asset) => FONT_EXT.test(asset))
+        .map((asset) => ({
+          family: fontFamilyFromAssetPath(asset),
+          path: asset,
+          url: `/api/projects/${pid}/preview/${asset}`,
+        }));
+      importedFontAssetsRef.current = [
+        ...imported,
+        ...importedFontAssetsRef.current.filter(
+          (existing) =>
+            !imported.some((font) => font.family.toLowerCase() === existing.family.toLowerCase()),
+        ),
+      ];
+      return imported;
     },
     [uploadProjectFiles],
   );
@@ -1394,6 +3670,53 @@ export function StudioApp() {
       fileTree.filter((f) => !f.endsWith(".html") && !f.endsWith(".md") && !f.endsWith(".json")),
     [fileTree],
   );
+  const fontAssets = useMemo<ImportedFontAsset[]>(
+    () =>
+      assets
+        .filter((asset) => FONT_EXT.test(asset))
+        .map((asset) => ({
+          family: fontFamilyFromAssetPath(asset),
+          path: asset,
+          url: `/api/projects/${projectId}/preview/${asset}`,
+        })),
+    [assets, projectId],
+  );
+  const selectedStudioMotion =
+    STUDIO_INSPECTOR_PANELS_ENABLED && domEditSelection
+      ? getStudioMotionForSelection(studioMotionManifestRef.current, domEditSelection)
+      : null;
+  const selectedTimelineElement = useMemo(
+    () =>
+      selectedTimelineElementId
+        ? (timelineElements.find(
+            (element) => getTimelineElementKey(element) === selectedTimelineElementId,
+          ) ?? null)
+        : null,
+    [selectedTimelineElementId, timelineElements],
+  );
+  const designPanelActive = STUDIO_INSPECTOR_PANELS_ENABLED && rightPanelTab === "design";
+  const motionPanelActive =
+    STUDIO_INSPECTOR_PANELS_ENABLED && STUDIO_MOTION_PANEL_ENABLED && rightPanelTab === "motion";
+  const inspectorPanelActive = designPanelActive || motionPanelActive;
+  const shouldShowSelectedDomBounds =
+    inspectorPanelActive &&
+    !rightCollapsed &&
+    (!selectedTimelineElement ||
+      isTimelineElementActiveAtTime(currentTime, selectedTimelineElement));
+  const inspectorButtonActive =
+    STUDIO_INSPECTOR_PANELS_ENABLED && !rightCollapsed && inspectorPanelActive;
+  const timelineLayerPanel =
+    STUDIO_TIMELINE_LAYER_INSPECTOR_ENABLED &&
+    inspectedTimelineElement &&
+    inspectedTimelineLayers.length > 0 ? (
+      <TimelineLayerPanel
+        clipLabel={getTimelineElementLabel(inspectedTimelineElement)}
+        layers={inspectedTimelineLayers}
+        selectedLayerKey={selectedTimelineLayerKey}
+        onSelectLayer={handleTimelineLayerSelect}
+        onClose={handleTimelineLayerPanelClose}
+      />
+    ) : null;
 
   if (resolving || !projectId) {
     return (
@@ -1439,6 +3762,42 @@ export function StudioApp() {
         </div>
         {/* Right: toolbar buttons */}
         <div className="flex items-center gap-1.5">
+          <button
+            type="button"
+            onClick={() => void handleUndo()}
+            disabled={!editHistory.canUndo}
+            className={`h-7 w-7 flex items-center justify-center rounded-md border transition-colors ${
+              editHistory.canUndo
+                ? "border-neutral-700 text-neutral-300 hover:border-neutral-500 hover:bg-neutral-800"
+                : "border-neutral-900 text-neutral-700"
+            }`}
+            title={
+              editHistory.undoLabel
+                ? `Undo ${editHistory.undoLabel} (${getHistoryShortcutLabel("undo")})`
+                : `Undo (${getHistoryShortcutLabel("undo")})`
+            }
+            aria-label="Undo"
+          >
+            <RotateCcw size={14} />
+          </button>
+          <button
+            type="button"
+            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={
+              editHistory.redoLabel
+                ? `Redo ${editHistory.redoLabel} (${getHistoryShortcutLabel("redo")})`
+                : `Redo (${getHistoryShortcutLabel("redo")})`
+            }
+            aria-label="Redo"
+          >
+            <RotateCw size={14} />
+          </button>
           <a
             href={captureFrameHref}
             download={captureFrameFilename}
@@ -1453,12 +3812,31 @@ export function StudioApp() {
             <span>Capture</span>
           </a>
           <button
-            onClick={() => setRightCollapsed((v) => !v)}
+            type="button"
+            onClick={() => {
+              if (!STUDIO_INSPECTOR_PANELS_ENABLED) return;
+              if (rightCollapsed || !inspectorPanelActive) {
+                setRightPanelTab("design");
+                setRightCollapsed(false);
+                return;
+              }
+              clearDomSelection();
+              setRightCollapsed(true);
+            }}
+            disabled={!STUDIO_INSPECTOR_PANELS_ENABLED}
             className={`h-7 flex items-center gap-1.5 px-2.5 rounded-md text-[11px] font-medium border transition-colors ${
-              !rightCollapsed
+              inspectorButtonActive
                 ? "text-studio-accent bg-studio-accent/10 border-studio-accent/30"
-                : "text-neutral-500 hover:text-neutral-300 hover:bg-neutral-800 border-transparent"
+                : STUDIO_INSPECTOR_PANELS_ENABLED
+                  ? "text-neutral-500 hover:text-neutral-300 hover:bg-neutral-800 border-transparent"
+                  : "cursor-not-allowed border-transparent text-neutral-700"
             }`}
+            title={
+              STUDIO_INSPECTOR_PANELS_ENABLED ? "Inspector" : STUDIO_MANUAL_EDITING_DISABLED_TITLE
+            }
+            aria-label={
+              STUDIO_INSPECTOR_PANELS_ENABLED ? "Inspector" : STUDIO_MANUAL_EDITING_DISABLED_TITLE
+            }
           >
             <svg
               width="12"
@@ -1471,8 +3849,7 @@ export function StudioApp() {
               <circle cx="12" cy="12" r="10" />
               <polygon points="10 8 16 12 10 16" fill="currentColor" stroke="none" />
             </svg>
-            Renders
-            {renderQueue.jobs.length > 0 ? ` (${renderQueue.jobs.length})` : ""}
+            Inspector
           </button>
         </div>
       </div>
@@ -1553,6 +3930,7 @@ export function StudioApp() {
             onLint={handleLint}
             linting={linting}
             onToggleCollapse={toggleLeftSidebar}
+            takeoverContent={timelineLayerPanel}
           />
         )}
 
@@ -1583,62 +3961,48 @@ export function StudioApp() {
             onMoveElement={handleTimelineElementMove}
             onResizeElement={handleTimelineElementResize}
             onBlockedEditAttempt={handleBlockedTimelineEdit}
+            onSelectTimelineElement={handleTimelineElementSelect}
+            onInspectTimelineElement={handleTimelineElementInspect}
+            inspectedTimelineElementId={inspectedTimelineElementId}
+            timelineLayerChildCounts={timelineLayerChildCounts}
+            thumbnailedTimelineElementIds={thumbnailedTimelineElementIds}
+            onToggleTimelineElementThumbnail={handleToggleTimelineElementThumbnail}
             onCompIdToSrcChange={setCompIdToSrc}
             onCompositionChange={(compPath) => {
               // Sync activeCompPath when user drills down via timeline double-click
               // or navigates back via breadcrumb — keeps sidebar + thumbnails in sync.
               setActiveCompPath(compPath);
+              setInspectedTimelineElementId(null);
+              refreshPreviewDocumentVersion();
             }}
-            onIframeRef={(iframe) => {
-              previewIframeRef.current = iframe;
-              syncPreviewTimelineHotkey(iframe);
-              consoleErrorsRef.current = [];
-              setConsoleErrors(null);
-              if (!iframe) return;
-
-              // Attach error capture after each iframe load (content resets on navigation)
-              const attachErrorCapture = () => {
-                try {
-                  const win = iframe.contentWindow as (Window & typeof globalThis) | null;
-                  if (!win) return;
-                  // Guard against double-patching
-                  if ((win as unknown as Record<string, unknown>).__hfErrorCapture) return;
-                  (win as unknown as Record<string, unknown>).__hfErrorCapture = true;
-                  const origError = win.console.error.bind(win.console);
-                  win.console.error = function (...args: unknown[]) {
-                    origError(...args);
-                    const text = args
-                      .map((a) => (a instanceof Error ? a.message : String(a)))
-                      .join(" ");
-                    if (text.includes("favicon")) return;
-                    consoleErrorsRef.current = [
-                      ...consoleErrorsRef.current,
-                      { severity: "error", message: text },
-                    ];
-                    setConsoleErrors([...consoleErrorsRef.current]);
-                  };
-                  win.addEventListener("error", (e: ErrorEvent) => {
-                    const text = e.message || String(e);
-                    consoleErrorsRef.current = [
-                      ...consoleErrorsRef.current,
-                      { severity: "error", message: text },
-                    ];
-                    setConsoleErrors([...consoleErrorsRef.current]);
-                  });
-                } catch {
-                  // cross-origin — can't attach
-                }
-              };
-              // Attach now (iframe may already be loaded) and on future loads
-              attachErrorCapture();
-              iframe.addEventListener("load", () => {
-                consoleErrorsRef.current = [];
-                setConsoleErrors(null);
-                attachErrorCapture();
-              });
-            }}
+            onIframeRef={handlePreviewIframeRef}
             previewOverlay={
-              captionEditMode ? <CaptionOverlay iframeRef={previewIframeRef} /> : undefined
+              captionEditMode ? (
+                <CaptionOverlay iframeRef={previewIframeRef} />
+              ) : STUDIO_INSPECTOR_PANELS_ENABLED ? (
+                <DomEditOverlay
+                  iframeRef={previewIframeRef}
+                  activeCompositionPath={activeCompPath}
+                  hoverSelection={
+                    STUDIO_PREVIEW_MANUAL_EDITING_ENABLED && !captionEditMode
+                      ? domEditHoverSelection
+                      : null
+                  }
+                  selection={shouldShowSelectedDomBounds ? domEditSelection : null}
+                  groupSelections={shouldShowSelectedDomBounds ? domEditGroupSelections : []}
+                  allowCanvasMovement={STUDIO_PREVIEW_MANUAL_EDITING_ENABLED}
+                  onCanvasMouseDown={handlePreviewCanvasMouseDown}
+                  onCanvasPointerMove={handlePreviewCanvasPointerMove}
+                  onCanvasPointerLeave={handlePreviewCanvasPointerLeave}
+                  onSelectionChange={applyDomSelection}
+                  onBlockedMove={handleBlockedDomMove}
+                  onManualDragStart={handleDomManualDragStart}
+                  onPathOffsetCommit={handleDomPathOffsetCommit}
+                  onGroupPathOffsetCommit={handleDomGroupPathOffsetCommit}
+                  onBoxSizeCommit={handleDomBoxSizeCommit}
+                  onRotationCommit={handleDomRotationCommit}
+                />
+              ) : null
             }
             timelineFooter={
               captionEditMode ? (
@@ -1679,16 +4043,94 @@ export function StudioApp() {
               {captionEditMode ? (
                 <CaptionPropertyPanel iframeRef={previewIframeRef} />
               ) : (
-                <RenderQueue
-                  jobs={renderQueue.jobs}
-                  projectId={projectId}
-                  onDelete={renderQueue.deleteRender}
-                  onClearCompleted={renderQueue.clearCompleted}
-                  onStartRender={(format, quality, resolution) =>
-                    renderQueue.startRender({ format, quality, resolution })
-                  }
-                  isRendering={renderQueue.isRendering}
-                />
+                <>
+                  <div className="flex items-center gap-1 border-b border-neutral-800 px-3 py-2">
+                    {STUDIO_INSPECTOR_PANELS_ENABLED && (
+                      <>
+                        <button
+                          type="button"
+                          onClick={() => setRightPanelTab("design")}
+                          className={`h-8 rounded-xl px-3 text-[11px] font-medium transition-colors ${
+                            rightPanelTab === "design"
+                              ? "bg-neutral-800 text-white"
+                              : "text-neutral-500 hover:bg-neutral-800/70 hover:text-neutral-200"
+                          }`}
+                        >
+                          Design
+                        </button>
+                        {STUDIO_MOTION_PANEL_ENABLED && (
+                          <button
+                            type="button"
+                            onClick={() => setRightPanelTab("motion")}
+                            className={`h-8 rounded-xl px-3 text-[11px] font-medium transition-colors ${
+                              rightPanelTab === "motion"
+                                ? "bg-neutral-800 text-white"
+                                : "text-neutral-500 hover:bg-neutral-800/70 hover:text-neutral-200"
+                            }`}
+                          >
+                            Motion
+                          </button>
+                        )}
+                      </>
+                    )}
+                    <button
+                      type="button"
+                      onClick={() => setRightPanelTab("renders")}
+                      className={`h-8 rounded-xl px-3 text-[11px] font-medium transition-colors ${
+                        rightPanelTab === "renders"
+                          ? "bg-neutral-800 text-white"
+                          : "text-neutral-500 hover:bg-neutral-800/70 hover:text-neutral-200"
+                      }`}
+                    >
+                      {renderQueue.jobs.length > 0
+                        ? `Renders (${renderQueue.jobs.length})`
+                        : "Renders"}
+                    </button>
+                  </div>
+                  <div className="min-h-0 flex-1">
+                    {designPanelActive ? (
+                      <PropertyPanel
+                        projectId={projectId}
+                        assets={assets}
+                        element={domEditGroupSelections.length > 1 ? null : domEditSelection}
+                        copiedAgentPrompt={copiedAgentPrompt}
+                        onClearSelection={clearDomSelection}
+                        onSetStyle={handleDomStyleCommit}
+                        onSetManualOffset={handleDomPathOffsetCommit}
+                        onSetManualSize={handleDomBoxSizeCommit}
+                        onSetText={handleDomTextCommit}
+                        onSetTextFieldStyle={handleDomTextFieldStyleCommit}
+                        onAddTextField={handleDomAddTextField}
+                        onRemoveTextField={handleDomRemoveTextField}
+                        onResetManualEdits={handleDomManualEditsReset}
+                        onAskAgent={handleAskAgent}
+                        onImportAssets={handleImportFiles}
+                        fontAssets={fontAssets}
+                        onImportFonts={handleImportFonts}
+                      />
+                    ) : motionPanelActive ? (
+                      <MotionPanel
+                        element={domEditGroupSelections.length > 1 ? null : domEditSelection}
+                        motion={selectedStudioMotion}
+                        onClearSelection={clearDomSelection}
+                        onSetMotion={handleDomMotionCommit}
+                        onClearMotion={handleDomMotionClear}
+                      />
+                    ) : (
+                      <RenderQueue
+                        jobs={renderQueue.jobs}
+                        projectId={projectId}
+                        onDelete={renderQueue.deleteRender}
+                        onClearCompleted={renderQueue.clearCompleted}
+                        onStartRender={async (format, quality) => {
+                          await waitForPendingDomEditSaves();
+                          await renderQueue.startRender(30, quality, format);
+                        }}
+                        isRendering={renderQueue.isRendering}
+                      />
+                    )}
+                  </div>
+                </>
               )}
             </div>
           </>
@@ -1709,6 +4151,15 @@ export function StudioApp() {
         />
       )}
 
+      {/* Ask agent modal */}
+      {agentModalOpen && domEditSelection && (
+        <AskAgentModal
+          selectionLabel={domEditSelection.label}
+          onSubmit={handleAgentModalSubmit}
+          onClose={() => setAgentModalOpen(false)}
+        />
+      )}
+
       {/* Global drag-drop overlay */}
       {globalDragOver && (
         <div className="absolute inset-0 z-[90] flex items-center justify-center bg-black/50 backdrop-blur-sm pointer-events-none">