fix(studio): shell UX — data-loss guards, error surfacing, dialog contracts, toasts

Author: vanceingalls

packages/studio/src/App.tsx

@@ -27,6 +27,7 @@ import { useFrameCapture } from "./hooks/useFrameCapture";
 import { useLintModal } from "./hooks/useLintModal";
 import { useCompositionDimensions } from "./hooks/useCompositionDimensions";
 import { useToast } from "./hooks/useToast";
+import { useCompositionContentLoader } from "./hooks/useCompositionContentLoader";
 import { useStudioUrlState } from "./hooks/useStudioUrlState";
 import {
   buildStudioContextValue,
@@ -133,7 +134,7 @@ export function StudioApp() {
       return !v;
     });
   }, []);
-  const { appToast, showToast, dismissToast } = useToast();
+  const { toasts, showToast, dismissToast } = useToast();
   const panelLayout = usePanelLayout({
     rightCollapsed: initialUrlStateRef.current.rightCollapsed,
     rightPanelTab: initialUrlStateRef.current.rightPanelTab,
@@ -390,17 +391,13 @@ export function StudioApp() {
     },
     [appHotkeys, resetConsoleErrors, refreshPreviewDocumentVersion],
   );
-  const handleSelectComposition = useCallback(
-    (comp: string) => {
-      setActiveCompPath(comp.endsWith(".html") ? comp : null);
-      fileManager.setEditingFile({ path: comp, content: null });
-      fetch(`/api/projects/${projectId}/files/${comp}`)
-        .then((r) => r.json())
-        .then((data) => fileManager.setEditingFile({ path: comp, content: data.content }))
-        .catch(() => {});
-    },
-    [projectId, fileManager],
-  );
+  const { setEditingFile } = fileManager;
+  const handleSelectComposition = useCompositionContentLoader({
+    projectId,
+    setEditingFile,
+    setActiveCompPath,
+    showToast,
+  });
   const {
     designPanelActive,
     inspectorPanelActive,
@@ -485,14 +482,15 @@ export function StudioApp() {
                     captureFrameFilename={frameCapture.captureFrameFilename}
                     handleCaptureFrameClick={frameCapture.handleCaptureFrameClick}
                     refreshCaptureFrameTime={frameCapture.refreshCaptureFrameTime}
+                    capturing={frameCapture.capturing}
                     inspectorButtonActive={inspectorButtonActive}
                     inspectorPanelActive={inspectorPanelActive}
                     onExport={() => void renderQueue.startRender(undefined)}
                   />
                   {previewPersistence.domEditSaveQueuePaused && (
                     <SaveQueuePausedBanner
                       message={previewPersistence.domEditSaveQueuePaused}
-                      onDismiss={previewPersistence.resetDomEditSaveQueueBreaker}
+                      onRetry={previewPersistence.resetDomEditSaveQueueBreaker}
                     />
                   )}
                   {viewModeValue.viewMode === "storyboard" && (
@@ -576,14 +574,15 @@ export function StudioApp() {
                   </div>
                   <StudioOverlays
                     projectId={projectId}
+                    projectDir={fileManager.projectDir}
                     lintModal={lintModal}
                     closeLintModal={closeLintModal}
                     consoleErrors={consoleErrors}
                     clearConsoleErrors={() => setConsoleErrors(null)}
                     domEditSession={domEditSession}
                     activeCompPath={activeCompPath}
                     dragOverlayActive={dragOverlay.active}
-                    appToast={appToast}
+                    toasts={toasts}
                     dismissToast={dismissToast}
                   />
                 </div>

packages/studio/src/components/AskAgentModal.tsx

@@ -1,6 +1,7 @@
 import { useState, useRef, type CSSProperties } from "react";
 import { useMountEffect } from "../hooks/useMountEffect";
 import { type AgentModalAnchorPoint, clampNumber } from "../utils/studioHelpers";
+import { useDialogBehavior } from "./ui/useDialogBehavior";
 
 function getAgentModalPositionStyle(
   anchorPoint: AgentModalAnchorPoint | null,
@@ -39,7 +40,16 @@ export function AskAgentModal({
 }) {
   const [value, setValue] = useState("");
   const inputRef = useRef<HTMLTextAreaElement>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
   const modalPositionStyle = getAgentModalPositionStyle(anchorPoint);
+  // A dirty draft vetoes Escape/backdrop closes — a stray click must not
+  // discard typed instructions. The X button and Copy still close directly.
+  const { requestClose } = useDialogBehavior({
+    open: true,
+    onClose,
+    containerRef,
+    canClose: () => !value.trim(),
+  });
 
   useMountEffect(() => {
     requestAnimationFrame(() => inputRef.current?.focus());
@@ -54,13 +64,18 @@ export function AskAgentModal({
     <div
       className={
         anchorPoint
-          ? "fixed inset-0 z-[100] bg-black/60 backdrop-blur-sm"
-          : "fixed inset-0 z-[100] flex items-center justify-center bg-black/60 backdrop-blur-sm"
+          ? "hf-backdrop-in fixed inset-0 z-[100] bg-black/60 backdrop-blur-sm"
+          : "hf-backdrop-in fixed inset-0 z-[100] flex items-center justify-center bg-black/60 backdrop-blur-sm"
       }
-      onClick={onClose}
+      onClick={requestClose}
     >
       <div
-        className={`w-[480px] rounded-2xl border border-neutral-800 bg-neutral-950 shadow-2xl ${
+        ref={containerRef}
+        role="dialog"
+        aria-modal="true"
+        aria-label="Copy prompt to AI agent"
+        tabIndex={-1}
+        className={`w-[480px] rounded-2xl border border-neutral-800 bg-neutral-950 shadow-2xl outline-none ${
           anchorPoint ? "fixed" : ""
         }`}
         style={modalPositionStyle}
@@ -74,8 +89,9 @@ export function AskAgentModal({
             </p>
           </div>
           <button
-            className="p-1 rounded-md text-neutral-500 hover:text-neutral-300 hover:bg-neutral-800/50"
+            className="p-1 rounded-md text-neutral-500 hover:text-neutral-300 hover:bg-neutral-800/50 active:scale-[0.98]"
             onClick={onClose}
+            aria-label="Close"
           >
             <svg
               width="14"
@@ -100,7 +116,8 @@ export function AskAgentModal({
             onChange={(e) => setValue(e.target.value)}
             onKeyDown={(e) => {
               if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) handleSubmit();
-              if (e.key === "Escape") onClose();
+              // Escape is handled at the document level by useDialogBehavior,
+              // guarded against discarding a dirty draft.
             }}
           />
           {contextPreview && (

packages/studio/src/components/LintModal.tsx

@@ -1,6 +1,7 @@
-import { useState } from "react";
+import { useRef, useState } from "react";
 import { XIcon, WarningIcon, CheckCircleIcon, CaretRightIcon } from "@phosphor-icons/react";
 import { copyTextToClipboard } from "../utils/clipboard";
+import { useDialogBehavior } from "./ui/useDialogBehavior";
 
 export interface LintFinding {
   severity: "error" | "warning";
@@ -12,16 +13,28 @@ export interface LintFinding {
 export function LintModal({
   findings,
   projectId,
+  projectDir,
+  title = "HyperFrame Lint Results",
+  promptIntro = "Fix these HyperFrames lint issues",
   onClose,
 }: {
   findings: LintFinding[];
   projectId: string;
+  /** Real on-disk project directory for the agent prompt (not the browser URL). */
+  projectDir?: string | null;
+  /** Header subtitle — parameterize so console errors don't masquerade as lint results. */
+  title?: string;
+  /** First line of the copied agent prompt. */
+  promptIntro?: string;
   onClose: () => void;
 }) {
   const errors = findings.filter((f) => f.severity === "error");
   const warnings = findings.filter((f) => f.severity === "warning");
   const hasIssues = findings.length > 0;
   const [copied, setCopied] = useState(false);
+  const [copyFailed, setCopyFailed] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const { requestClose } = useDialogBehavior({ open: true, onClose, containerRef });
 
   const handleCopyToAgent = async () => {
     const lines = findings.map((f) => {
@@ -30,21 +43,31 @@ export function LintModal({
       if (f.fixHint) line += `\n  Fix: ${f.fixHint}`;
       return line;
     });
-    const text = `Fix these HyperFrames lint issues for project "${projectId}":\n\nProject path: ${window.location.href}\n\n${lines.join("\n\n")}`;
+    const pathLine = projectDir ? `Project path: ${projectDir}\n\n` : "";
+    const text = `${promptIntro} for project "${projectId}":\n\n${pathLine}${lines.join("\n\n")}`;
     const copiedText = await copyTextToClipboard(text);
     if (copiedText) {
       setCopied(true);
+      setCopyFailed(false);
       setTimeout(() => setCopied(false), 2000);
+    } else {
+      setCopyFailed(true);
+      setTimeout(() => setCopyFailed(false), 3000);
     }
   };
 
   return (
     <div
-      className="fixed inset-0 z-[100] flex items-center justify-center bg-black/60 backdrop-blur-sm"
-      onClick={onClose}
+      className="hf-backdrop-in fixed inset-0 z-[100] flex items-center justify-center bg-black/60 backdrop-blur-sm"
+      onClick={requestClose}
     >
       <div
-        className="bg-neutral-950 border border-neutral-800 rounded-xl shadow-2xl w-full max-w-xl max-h-[80vh] flex flex-col overflow-hidden"
+        ref={containerRef}
+        role="dialog"
+        aria-modal="true"
+        aria-label={title}
+        tabIndex={-1}
+        className="bg-neutral-950 border border-neutral-800 rounded-xl shadow-2xl w-full max-w-xl max-h-[80vh] flex flex-col overflow-hidden outline-none"
         onClick={(e) => e.stopPropagation()}
       >
         {/* Header */}
@@ -65,12 +88,13 @@ export function LintModal({
                   ? `${errors.length} error${errors.length !== 1 ? "s" : ""}, ${warnings.length} warning${warnings.length !== 1 ? "s" : ""}`
                   : "All checks passed"}
               </h2>
-              <p className="text-xs text-neutral-500">HyperFrame Lint Results</p>
+              <p className="text-xs text-neutral-500">{title}</p>
             </div>
           </div>
           <button
             onClick={onClose}
-            className="p-1.5 rounded-lg text-neutral-500 hover:text-neutral-200 hover:bg-neutral-800 transition-colors"
+            aria-label="Close"
+            className="p-1.5 rounded-lg text-neutral-500 hover:text-neutral-200 hover:bg-neutral-800 transition-colors active:scale-[0.98]"
           >
             <XIcon size={16} />
           </button>
@@ -81,13 +105,19 @@ export function LintModal({
           <div className="flex items-center justify-end px-5 py-2 border-b border-neutral-800/50">
             <button
               onClick={handleCopyToAgent}
-              className={`px-3 py-1 text-xs font-medium rounded-lg transition-colors ${
+              className={`px-3 py-1 text-xs font-medium rounded-lg transition-colors active:scale-[0.98] ${
                 copied
                   ? "bg-green-600 text-white"
-                  : "bg-studio-accent hover:bg-studio-accent/80 text-white"
+                  : copyFailed
+                    ? "bg-red-600 text-white"
+                    : "bg-studio-accent hover:bg-studio-accent/80 text-white"
               }`}
             >
-              {copied ? "Copied!" : "Copy to Agent"}
+              {copied
+                ? "Copied!"
+                : copyFailed
+                  ? "Copy failed — check permissions"
+                  : "Copy to Agent"}
             </button>
           </div>
         )}

packages/studio/src/components/MediaPreview.tsx

@@ -1,15 +1,49 @@
+import { useState } from "react";
 import { IMAGE_EXT, VIDEO_EXT, AUDIO_EXT } from "../utils/mediaTypes";
 
+function MediaErrorPanel({ name, filePath }: { name: string; filePath: string }) {
+  return (
+    <div className="flex flex-col items-center justify-center h-full p-4 bg-neutral-950 gap-2">
+      <svg
+        width="40"
+        height="40"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        className="text-neutral-600"
+        aria-hidden="true"
+      >
+        <circle cx="12" cy="12" r="10" />
+        <line x1="12" y1="8" x2="12" y2="12" strokeLinecap="round" />
+        <line x1="12" y1="16" x2="12.01" y2="16" strokeLinecap="round" />
+      </svg>
+      <span className="text-sm text-neutral-400 font-medium">{name}</span>
+      <span className="text-[11px] text-neutral-600 font-mono">{filePath}</span>
+      <span className="text-[10px] text-neutral-500">
+        Couldn't load this file — it may be missing or corrupt
+      </span>
+    </div>
+  );
+}
+
 export function MediaPreview({ projectId, filePath }: { projectId: string; filePath: string }) {
   const serveUrl = `/api/projects/${projectId}/preview/${filePath}`;
   const name = filePath.split("/").pop() ?? filePath;
+  // Keyed by path so switching to another file clears a previous failure.
+  const [failedPath, setFailedPath] = useState<string | null>(null);
+  const failed = failedPath === filePath;
+  const setFailed = () => setFailedPath(filePath);
+
+  if (failed) return <MediaErrorPanel name={name} filePath={filePath} />;
 
   if (IMAGE_EXT.test(filePath)) {
     return (
       <div className="flex flex-col items-center justify-center h-full p-4 bg-neutral-950">
         <img
           src={serveUrl}
           alt={name}
+          onError={setFailed}
           className="max-w-full max-h-[70%] object-contain rounded border border-neutral-800"
         />
         <span className="mt-3 text-[11px] text-neutral-500 font-mono">{filePath}</span>
@@ -23,6 +57,7 @@ export function MediaPreview({ projectId, filePath }: { projectId: string; fileP
         <video
           src={serveUrl}
           controls
+          onError={setFailed}
           className="max-w-full max-h-[70%] rounded border border-neutral-800"
         />
         <span className="mt-3 text-[11px] text-neutral-500 font-mono">{filePath}</span>
@@ -46,7 +81,7 @@ export function MediaPreview({ projectId, filePath }: { projectId: string; fileP
           <circle cx="6" cy="18" r="3" />
           <circle cx="18" cy="16" r="3" />
         </svg>
-        <audio src={serveUrl} controls className="w-full max-w-[280px]" />
+        <audio src={serveUrl} controls onError={setFailed} className="w-full max-w-[280px]" />
         <span className="text-[11px] text-neutral-500 font-mono">{filePath}</span>
       </div>
     );

packages/studio/src/components/SaveQueuePausedBanner.tsx

@@ -1,22 +1,23 @@
 interface SaveQueuePausedBannerProps {
   message: string;
-  onDismiss: () => void;
+  /** Resets the save-queue circuit breaker so persistence resumes. */
+  onRetry: () => void;
 }
 
 /** Alert shown when the DOM-edit save queue circuit breaker pauses persistence. */
-export function SaveQueuePausedBanner({ message, onDismiss }: SaveQueuePausedBannerProps) {
+export function SaveQueuePausedBanner({ message, onRetry }: SaveQueuePausedBannerProps) {
   return (
     <div
-      className="absolute left-1/2 top-14 z-[92] flex max-w-[calc(100vw-32px)] -translate-x-1/2 items-center gap-3 rounded-md border border-red-500/30 bg-red-950/85 px-4 py-2 text-[12px] font-medium text-red-100 shadow-lg shadow-black/30"
+      className="hf-backdrop-in absolute left-1/2 top-14 z-[92] flex max-w-[calc(100vw-32px)] -translate-x-1/2 items-center gap-3 rounded-md border border-red-500/30 bg-red-950/85 px-4 py-2 text-[12px] font-medium text-red-100 shadow-lg shadow-black/30"
       role="alert"
     >
       <span>{message}</span>
       <button
         type="button"
-        onClick={onDismiss}
-        className="rounded border border-red-300/20 px-2 py-1 text-[11px] text-red-100 transition-colors hover:bg-red-400/10"
+        onClick={onRetry}
+        className="rounded border border-red-300/20 px-2 py-1 text-[11px] text-red-100 transition-colors hover:bg-red-400/10 active:scale-[0.98]"
       >
-        Dismiss
+        Retry saving
       </button>
     </div>
   );