@hyperframes/studio 0.6.0-alpha.9 → 0.6.1

package/src/hooks/useAppHotkeys.ts

@@ -0,0 +1,326 @@
+import { useCallback, useEffect, useRef } from "react";
+import { usePlayerStore } from "../player";
+import type { TimelineElement } from "../player";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import type { LeftSidebarHandle } from "../components/sidebar/LeftSidebar";
+import { STUDIO_MANUAL_EDITS_PATH } from "../components/editor/manualEdits";
+import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";
+import { shouldHandleTimelineToggleHotkey, isEditableTarget } from "../utils/timelineDiscovery";
+import { shouldIgnoreHistoryShortcut } from "../utils/studioHelpers";
+
+// ── Types ──
+
+interface EditHistoryHandle {
+  undo: (callbacks: {
+    readFile: (path: string) => Promise<string>;
+    writeFile: (path: string, content: string) => Promise<void>;
+  }) => Promise<{
+    ok: boolean;
+    reason?: string;
+    label?: string;
+    paths?: string[];
+  }>;
+  redo: (callbacks: {
+    readFile: (path: string) => Promise<string>;
+    writeFile: (path: string, content: string) => Promise<void>;
+  }) => Promise<{
+    ok: boolean;
+    reason?: string;
+    label?: string;
+    paths?: string[];
+  }>;
+}
+
+interface UseAppHotkeysParams {
+  toggleTimelineVisibility: () => void;
+  handleTimelineElementDelete: (element: TimelineElement) => Promise<void>;
+  handleDomEditElementDelete: (selection: DomEditSelection) => Promise<void>;
+  domEditSelectionRef: React.MutableRefObject<DomEditSelection | null>;
+  clearDomSelectionRef: React.MutableRefObject<() => void>;
+  editHistory: EditHistoryHandle;
+  readOptionalProjectFile: (path: string) => Promise<string>;
+  readProjectFile: (path: string) => Promise<string>;
+  writeProjectFile: (path: string, content: string) => Promise<void>;
+  domEditSaveTimestampRef: React.MutableRefObject<number>;
+  showToast: (message: string, tone?: "error" | "info") => void;
+  syncHistoryPreviewAfterApply: (paths: string[] | undefined) => Promise<void>;
+  waitForPendingDomEditSaves: () => Promise<void>;
+  leftSidebarRef: React.RefObject<LeftSidebarHandle | null>;
+}
+
+// ── Hook ──
+
+export function useAppHotkeys({
+  toggleTimelineVisibility,
+  handleTimelineElementDelete,
+  handleDomEditElementDelete,
+  domEditSelectionRef,
+  clearDomSelectionRef,
+  editHistory,
+  readOptionalProjectFile,
+  readProjectFile,
+  writeProjectFile,
+  domEditSaveTimestampRef,
+  showToast,
+  syncHistoryPreviewAfterApply,
+  waitForPendingDomEditSaves,
+  leftSidebarRef,
+}: UseAppHotkeysParams) {
+  const previewHotkeyWindowRef = useRef<Window | null>(null);
+  const handleAppKeyDownRef = useRef<((event: KeyboardEvent) => void) | undefined>(undefined);
+  const previewHistoryHotkeyCleanupRef = useRef<(() => void) | null>(null);
+
+  // ── Timeline toggle hotkey ──
+
+  const handleTimelineToggleHotkey = useCallback(
+    (event: KeyboardEvent) => {
+      if (!shouldHandleTimelineToggleHotkey(event)) return;
+      event.preventDefault();
+      toggleTimelineVisibility();
+    },
+    [toggleTimelineVisibility],
+  );
+
+  // ── History file read/write helpers ──
+
+  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> => {
+      domEditSaveTimestampRef.current = Date.now();
+      await writeProjectFile(path, content);
+    },
+    [domEditSaveTimestampRef, writeProjectFile],
+  );
+
+  // ── Undo / Redo ──
+
+  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) {
+      clearDomSelectionRef.current();
+      await syncHistoryPreviewAfterApply(result.paths);
+      showToast(`Undid ${result.label}`, "info");
+    }
+  }, [
+    clearDomSelectionRef,
+    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) {
+      clearDomSelectionRef.current();
+      await syncHistoryPreviewAfterApply(result.paths);
+      showToast(`Redid ${result.label}`, "info");
+    }
+  }, [
+    clearDomSelectionRef,
+    editHistory,
+    readHistoryProjectFile,
+    showToast,
+    syncHistoryPreviewAfterApply,
+    waitForPendingDomEditSaves,
+    writeHistoryProjectFile,
+  ]);
+
+  // ── Stable refs for the consolidated keydown handler ──
+
+  const handleToggleRef = useRef(handleTimelineToggleHotkey);
+  handleToggleRef.current = handleTimelineToggleHotkey;
+  const handleDeleteRef = useRef(handleTimelineElementDelete);
+  handleDeleteRef.current = handleTimelineElementDelete;
+  const handleDomEditDeleteRef = useRef(handleDomEditElementDelete);
+  handleDomEditDeleteRef.current = handleDomEditElementDelete;
+  const handleUndoRef = useRef(handleUndo);
+  handleUndoRef.current = handleUndo;
+  const handleRedoRef = useRef(handleRedo);
+  handleRedoRef.current = handleRedo;
+
+  // ── Consolidated keydown handler ──
+
+  handleAppKeyDownRef.current = (event: KeyboardEvent) => {
+    // Shift+T — toggle timeline
+    handleToggleRef.current(event);
+
+    // Cmd/Ctrl+Z — undo, Cmd/Ctrl+Shift+Z or Ctrl+Y — redo
+    if (event.metaKey || event.ctrlKey) {
+      if (!shouldIgnoreHistoryShortcut(event.target)) {
+        const key = event.key.toLowerCase();
+        if (key === "z" && !event.shiftKey) {
+          event.preventDefault();
+          void handleUndoRef.current();
+          return;
+        }
+        if ((key === "z" && event.shiftKey) || (event.ctrlKey && !event.metaKey && key === "y")) {
+          event.preventDefault();
+          void handleRedoRef.current();
+          return;
+        }
+      }
+
+      // Cmd/Ctrl+1 — sidebar: Compositions tab
+      if (event.key === "1") {
+        event.preventDefault();
+        leftSidebarRef.current?.selectTab("compositions");
+        return;
+      }
+
+      // Cmd/Ctrl+2 — sidebar: Assets tab
+      if (event.key === "2") {
+        event.preventDefault();
+        leftSidebarRef.current?.selectTab("assets");
+        return;
+      }
+    }
+
+    // Delete / Backspace — remove selected element (timeline clip or preview selection)
+    if (
+      (event.key === "Delete" || event.key === "Backspace") &&
+      !event.metaKey &&
+      !event.ctrlKey &&
+      !event.altKey &&
+      !isEditableTarget(event.target)
+    ) {
+      const { selectedElementId, elements } = usePlayerStore.getState();
+      if (selectedElementId) {
+        const element = elements.find((el) => (el.key ?? el.id) === selectedElementId);
+        if (element) {
+          event.preventDefault();
+          void handleDeleteRef.current(element);
+          return;
+        }
+      }
+      const domSelection = domEditSelectionRef.current;
+      if (domSelection) {
+        event.preventDefault();
+        void handleDomEditDeleteRef.current(domSelection);
+      }
+    }
+  };
+
+  // ── Window keydown listener ──
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    function handleAppKeyDown(event: KeyboardEvent) {
+      handleAppKeyDownRef.current?.(event);
+    }
+    window.addEventListener("keydown", handleAppKeyDown, true);
+    return () => window.removeEventListener("keydown", handleAppKeyDown, true);
+  }, []);
+
+  // ── Preview iframe keydown forwarding ──
+
+  const previewAppKeyDownHandler = useCallback((event: KeyboardEvent) => {
+    handleAppKeyDownRef.current?.(event);
+  }, []);
+
+  const syncPreviewTimelineHotkey = useCallback(
+    (iframe: HTMLIFrameElement | null) => {
+      const nextWindow = iframe?.contentWindow ?? null;
+      if (previewHotkeyWindowRef.current === nextWindow) return;
+      if (previewHotkeyWindowRef.current) {
+        previewHotkeyWindowRef.current.removeEventListener("keydown", previewAppKeyDownHandler);
+      }
+      previewHotkeyWindowRef.current = nextWindow;
+      nextWindow?.addEventListener("keydown", previewAppKeyDownHandler, true);
+    },
+    [previewAppKeyDownHandler],
+  );
+
+  useEffect(
+    () => () => {
+      if (previewHotkeyWindowRef.current) {
+        previewHotkeyWindowRef.current.removeEventListener("keydown", previewAppKeyDownHandler);
+        previewHotkeyWindowRef.current = null;
+      }
+    },
+    [previewAppKeyDownHandler],
+  );
+
+  // ── History hotkey for iframe forwarding ──
+
+  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();
+    }
+  }, []);
+
+  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;
+    },
+    [],
+  );
+
+  return {
+    handleUndo,
+    handleRedo,
+    syncPreviewTimelineHotkey,
+    syncPreviewHistoryHotkey,
+    handleTimelineToggleHotkey,
+  };
+}

package/src/hooks/useAskAgentModal.ts

@@ -0,0 +1,162 @@
+import { useState, useCallback, useRef, useEffect } from "react";
+import { copyTextToClipboard } from "../utils/clipboard";
+import { readTagSnippetByTarget } from "../utils/sourcePatcher";
+import { toProjectAbsolutePath, type AgentModalAnchorPoint } from "../utils/studioHelpers";
+import { buildElementAgentPrompt, type DomEditSelection } from "../components/editor/domEditing";
+
+// ── Types ──
+
+export interface UseAskAgentModalParams {
+  projectId: string | null;
+  activeCompPath: string | null;
+  projectDir: string | null;
+  projectIdRef: React.MutableRefObject<string | null>;
+  currentTime: number;
+  showToast: (message: string, tone?: "error" | "info") => void;
+  domEditSelectionRef: React.MutableRefObject<DomEditSelection | null>;
+  domEditSelection: DomEditSelection | null;
+}
+
+// ── Hook ──
+
+export function useAskAgentModal({
+  activeCompPath,
+  projectDir,
+  projectIdRef,
+  currentTime,
+  showToast,
+  domEditSelectionRef,
+  domEditSelection,
+}: UseAskAgentModalParams) {
+  // ── State ──
+
+  const [agentPromptTagSnippet, setAgentPromptTagSnippet] = useState<string | undefined>();
+  const [agentPromptSelectionContext, setAgentPromptSelectionContext] = useState<
+    string | undefined
+  >();
+  const [agentModalAnchorPoint, setAgentModalAnchorPoint] = useState<AgentModalAnchorPoint | null>(
+    null,
+  );
+  const [copiedAgentPrompt, setCopiedAgentPrompt] = useState(false);
+  const [agentModalOpen, setAgentModalOpen] = useState(false);
+
+  // ── Refs ──
+
+  const copiedAgentTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // ── Callbacks ──
+
+  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, domEditSelectionRef, projectIdRef],
+  );
+
+  const handleAskAgent = useCallback(() => {
+    if (!domEditSelection) return;
+    setAgentPromptTagSnippet(undefined);
+    setAgentPromptSelectionContext(undefined);
+    setAgentModalAnchorPoint(null);
+    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,
+        selectionContext: agentPromptSelectionContext,
+        userInstruction,
+        sourceFilePath: toProjectAbsolutePath(projectDir, targetPath),
+      });
+
+      const copied = await copyTextToClipboard(prompt);
+      if (!copied) {
+        showToast("Could not copy prompt to clipboard.", "error");
+        return;
+      }
+
+      setAgentModalOpen(false);
+      setAgentPromptSelectionContext(undefined);
+      setAgentModalAnchorPoint(null);
+      if (copiedAgentTimerRef.current) clearTimeout(copiedAgentTimerRef.current);
+      setCopiedAgentPrompt(true);
+      copiedAgentTimerRef.current = setTimeout(() => setCopiedAgentPrompt(false), 1600);
+    },
+    [
+      activeCompPath,
+      agentPromptSelectionContext,
+      agentPromptTagSnippet,
+      currentTime,
+      domEditSelection,
+      projectDir,
+      showToast,
+    ],
+  );
+
+  // ── Effects ──
+
+  // Clear agent-prompt state when selection changes
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    setAgentPromptTagSnippet(undefined);
+    setAgentPromptSelectionContext(undefined);
+    setAgentModalAnchorPoint(null);
+    setCopiedAgentPrompt(false);
+  }, [domEditSelection]);
+
+  // Cleanup copiedAgentTimerRef
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(
+    () => () => {
+      if (copiedAgentTimerRef.current) clearTimeout(copiedAgentTimerRef.current);
+    },
+    [],
+  );
+
+  return {
+    // State
+    agentModalOpen,
+    agentModalAnchorPoint,
+    copiedAgentPrompt,
+    agentPromptSelectionContext,
+
+    // Setters (consumed by handlePreviewCanvasMouseDown and other callers)
+    setAgentModalOpen,
+    setAgentPromptSelectionContext,
+    setAgentModalAnchorPoint,
+
+    // Callbacks
+    preloadAgentPromptSnippet,
+    handleAskAgent,
+    handleAgentModalSubmit,
+  };
+}

package/src/hooks/useCaptionDetection.ts

@@ -0,0 +1,132 @@
+import { useEffect } from "react";
+import { useCaptionStore } from "../captions/store";
+import { useCaptionSync } from "../captions/hooks/useCaptionSync";
+import { parseCaptionComposition } from "../captions/parser";
+
+interface UseCaptionDetectionParams {
+  projectId: string | null;
+  activeCompPath: string | null;
+  compIdToSrc: Map<string, string>;
+  captionEditMode: boolean;
+  captionHasSelection: boolean;
+  previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
+  captionSync: ReturnType<typeof useCaptionSync>;
+  setRightCollapsed: (collapsed: boolean) => void;
+}
+
+export function useCaptionDetection({
+  projectId,
+  activeCompPath,
+  compIdToSrc,
+  captionEditMode,
+  captionHasSelection,
+  previewIframeRef,
+  captionSync,
+  setRightCollapsed,
+}: UseCaptionDetectionParams) {
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (!projectId) return;
+
+    let activating = false;
+
+    const tryActivateCaptions = () => {
+      if (useCaptionStore.getState().isEditMode || activating) {
+        return;
+      }
+
+      const iframe = previewIframeRef.current;
+      let doc: Document | null = null;
+      let win: Window | null = null;
+      try {
+        doc = iframe?.contentDocument ?? null;
+        win = iframe?.contentWindow ?? null;
+      } catch {
+        return;
+      }
+      if (!doc || !win) return;
+
+      const groups = doc.querySelectorAll(".caption-group");
+      if (groups.length === 0) return;
+
+      let captionSrcPath: string | null = null;
+
+      const compHosts = doc.querySelectorAll("[data-composition-src], [data-composition-file]");
+      for (const host of compHosts) {
+        const src =
+          host.getAttribute("data-composition-src") || host.getAttribute("data-composition-file");
+        if (src && src.includes("captions")) {
+          captionSrcPath = src;
+          break;
+        }
+      }
+
+      if (!captionSrcPath) {
+        for (const [id, src] of compIdToSrc) {
+          if (id.includes("caption") || src.includes("caption")) {
+            captionSrcPath = src;
+            break;
+          }
+        }
+      }
+
+      if (!captionSrcPath && activeCompPath?.includes("captions")) {
+        captionSrcPath = activeCompPath;
+      }
+
+      if (!captionSrcPath) {
+        const captionComp = doc.querySelector('[data-composition-id*="caption"]');
+        if (captionComp) {
+          const compId = captionComp.getAttribute("data-composition-id") || "";
+          captionSrcPath = compIdToSrc.get(compId) || null;
+        }
+      }
+
+      if (!captionSrcPath) return;
+
+      activating = true;
+      const srcPath = captionSrcPath;
+      fetch(`/api/projects/${projectId}/files/${encodeURIComponent(srcPath)}`)
+        .then((r) => r.json())
+        .then((data: { content?: string }) => {
+          if (!data.content || !doc || !win || useCaptionStore.getState().isEditMode) return;
+          const root = doc.querySelector("[data-composition-id]");
+          const w = parseInt(root?.getAttribute("data-width") ?? "1920", 10);
+          const h = parseInt(root?.getAttribute("data-height") ?? "1080", 10);
+          const dur = parseFloat(root?.getAttribute("data-duration") ?? "0");
+          const model = parseCaptionComposition(doc, win, data.content, w, h, dur);
+          if (!model) return;
+          const store = useCaptionStore.getState();
+          store.setModel(model);
+          store.setSourceFilePath(srcPath);
+          store.setEditMode(true);
+          captionSync.loadOverrides();
+        })
+        .catch(() => {})
+        .finally(() => {
+          activating = false;
+        });
+    };
+
+    const handleMessage = (e: MessageEvent) => {
+      const data = e.data;
+      if (data?.source === "hf-preview" && (data?.type === "state" || data?.type === "timeline")) {
+        tryActivateCaptions();
+      }
+    };
+
+    window.addEventListener("message", handleMessage);
+    tryActivateCaptions();
+
+    return () => {
+      window.removeEventListener("message", handleMessage);
+    };
+  }, [activeCompPath, projectId, compIdToSrc, captionSync, previewIframeRef]);
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (captionEditMode) {
+      setRightCollapsed(!captionHasSelection);
+    }
+  }, [captionHasSelection, captionEditMode, setRightCollapsed]);
+}

package/src/hooks/useCompositionDimensions.ts

@@ -0,0 +1,25 @@
+import { useState } from "react";
+import { useMountEffect } from "./useMountEffect";
+import type { CompositionDimensions } from "../components/renders/RenderQueue";
+
+export function useCompositionDimensions() {
+  const [compositionDimensions, setCompositionDimensions] = useState<CompositionDimensions | null>(
+    null,
+  );
+
+  useMountEffect(() => {
+    const handleMessage = (e: MessageEvent) => {
+      const data = e.data;
+      if (data?.source !== "hf-preview" || data?.type !== "stage-size") return;
+      const { width, height } = data as { width: number; height: number };
+      if (!(width > 0) || !(height > 0)) return;
+      setCompositionDimensions((prev) =>
+        prev && prev.width === width && prev.height === height ? prev : { width, height },
+      );
+    };
+    window.addEventListener("message", handleMessage);
+    return () => window.removeEventListener("message", handleMessage);
+  });
+
+  return compositionDimensions;
+}

package/src/hooks/useConsoleErrorCapture.ts

@@ -0,0 +1,60 @@
+import { useEffect, useRef, useState } from "react";
+import type { LintFinding } from "../components/LintModal";
+
+/**
+ * Captures `console.error` and `window.onerror` events from a preview iframe
+ * and exposes them as LintFinding[] for the console errors modal.
+ */
+export function useConsoleErrorCapture(previewIframe: HTMLIFrameElement | null) {
+  const [consoleErrors, setConsoleErrors] = useState<LintFinding[] | null>(null);
+  const consoleErrorsRef = useRef<LintFinding[]>([]);
+
+  const resetErrors = () => {
+    consoleErrorsRef.current = [];
+    setConsoleErrors(null);
+  };
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (!previewIframe) return;
+    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();
+    const handleLoad = () => {
+      consoleErrorsRef.current = [];
+      setConsoleErrors(null);
+      attachErrorCapture();
+    };
+    previewIframe.addEventListener("load", handleLoad);
+    return () => previewIframe.removeEventListener("load", handleLoad);
+  }, [previewIframe]);
+
+  return { consoleErrors, setConsoleErrors, resetErrors };
+}