@hyperframes/studio 0.7.37 → 0.7.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.7.37",
+  "version": "0.7.38",
   "description": "",
   "repository": {
     "type": "git",
@@ -46,11 +46,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.7.37",
-    "@hyperframes/parsers": "0.7.37",
-    "@hyperframes/player": "0.7.37",
-    "@hyperframes/sdk": "0.7.37",
-    "@hyperframes/studio-server": "0.7.37"
+    "@hyperframes/core": "0.7.38",
+    "@hyperframes/parsers": "0.7.38",
+    "@hyperframes/sdk": "0.7.38",
+    "@hyperframes/studio-server": "0.7.38",
+    "@hyperframes/player": "0.7.38"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -65,7 +65,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.7.37"
+    "@hyperframes/producer": "0.7.38"
   },
   "peerDependencies": {
     "react": "19",

package/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,
@@ -64,7 +65,6 @@ export function StudioApp() {
   const initialUrlStateRef = useRef(readStudioUrlStateFromWindow());
   const viewModeValue = useViewModeState();
 
-  // sessionStorage-backed: fires once per tab, survives HMR remounts
   useEffect(() => {
     if (resolving || waitingForServer) return;
     if (hasFiredSessionStart()) return;
@@ -133,7 +133,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 +390,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 +481,20 @@ export function StudioApp() {
                     captureFrameFilename={frameCapture.captureFrameFilename}
                     handleCaptureFrameClick={frameCapture.handleCaptureFrameClick}
                     refreshCaptureFrameTime={frameCapture.refreshCaptureFrameTime}
+                    capturing={frameCapture.capturing}
                     inspectorButtonActive={inspectorButtonActive}
                     inspectorPanelActive={inspectorPanelActive}
-                    onExport={() => void renderQueue.startRender(undefined)}
+                    onExport={() => {
+                      void (async () => {
+                        await previewPersistence.waitForPendingDomEditSaves();
+                        await renderQueue.startRender(undefined);
+                      })();
+                    }}
                   />
                   {previewPersistence.domEditSaveQueuePaused && (
                     <SaveQueuePausedBanner
                       message={previewPersistence.domEditSaveQueuePaused}
-                      onDismiss={previewPersistence.resetDomEditSaveQueueBreaker}
+                      onRetry={previewPersistence.resetDomEditSaveQueueBreaker}
                     />
                   )}
                   {viewModeValue.viewMode === "storyboard" && (
@@ -501,8 +503,6 @@ export function StudioApp() {
                       onSelectComposition={handleSelectComposition}
                     />
                   )}
-                  {/* Timeline stage stays mounted (just hidden) in storyboard mode,
-                      so preview/player/gesture/render state survives the toggle. */}
                   <div
                     className={`flex flex-1 min-h-0${
                       viewModeValue.viewMode === "storyboard" ? " hidden" : ""
@@ -576,6 +576,7 @@ export function StudioApp() {
                   </div>
                   <StudioOverlays
                     projectId={projectId}
+                    projectDir={fileManager.projectDir}
                     lintModal={lintModal}
                     closeLintModal={closeLintModal}
                     consoleErrors={consoleErrors}
@@ -583,7 +584,7 @@ export function StudioApp() {
                     domEditSession={domEditSession}
                     activeCompPath={activeCompPath}
                     dragOverlayActive={dragOverlay.active}
-                    appToast={appToast}
+                    toasts={toasts}
                     dismissToast={dismissToast}
                   />
                 </div>

package/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 && (

package/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>
         )}

package/src/components/MediaPreview.tsx

@@ -1,8 +1,41 @@
+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 (
@@ -10,6 +43,7 @@ export function MediaPreview({ projectId, filePath }: { projectId: string; fileP
         <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>
     );

package/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>
   );

package/src/components/StudioErrorBoundary.tsx

@@ -30,39 +30,27 @@ export class StudioErrorBoundary extends Component<Props, State> {
     if (!this.state.error) return this.props.children;
 
     return (
-      <div
-        style={{
-          position: "fixed",
-          inset: 0,
-          display: "flex",
-          flexDirection: "column",
-          alignItems: "center",
-          justifyContent: "center",
-          background: "#0a0a0a",
-          color: "#e5e5e5",
-          fontFamily: "system-ui, -apple-system, sans-serif",
-          gap: 16,
-        }}
-      >
-        <div style={{ fontSize: 18, fontWeight: 600 }}>Something went wrong</div>
-        <div style={{ fontSize: 13, color: "#888", maxWidth: 480, textAlign: "center" }}>
+      <div className="fixed inset-0 flex flex-col items-center justify-center gap-4 bg-neutral-950 font-sans text-neutral-200">
+        <div className="text-lg font-semibold">Something went wrong</div>
+        <div className="max-w-[480px] text-center text-[13px] text-neutral-500">
           {this.state.error.message}
         </div>
-        <button
-          onClick={() => this.setState({ error: null })}
-          style={{
-            marginTop: 8,
-            padding: "8px 20px",
-            background: "#2563eb",
-            color: "#fff",
-            border: "none",
-            borderRadius: 6,
-            fontSize: 14,
-            cursor: "pointer",
-          }}
-        >
-          Try again
-        </button>
+        <div className="mt-2 flex items-center gap-2">
+          <button
+            onClick={() => this.setState({ error: null })}
+            className="rounded-md bg-studio-accent px-5 py-2 text-sm font-medium text-neutral-950 transition-[filter] hover:brightness-110 active:scale-[0.98]"
+          >
+            Try again
+          </button>
+          {/* If the error recurs immediately, "Try again" loops — a full reload
+              is the recovery path that always works. */}
+          <button
+            onClick={() => window.location.reload()}
+            className="rounded-md border border-neutral-700 px-5 py-2 text-sm font-medium text-neutral-300 transition-colors hover:bg-neutral-800 active:scale-[0.98]"
+          >
+            Reload Studio
+          </button>
+        </div>
       </div>
     );
   }

package/src/components/StudioFeedbackBar.tsx

@@ -69,6 +69,7 @@ function markPrompted(): void {
 // fallow-ignore-next-line complexity
 export const StudioFeedbackBar = memo(function StudioFeedbackBar() {
   const [visible, setVisible] = useState(false);
+  const [entered, setEntered] = useState(false);
   const [rating, setRating] = useState<number | null>(null);
   const [comment, setComment] = useState("");
   const [submitted, setSubmitted] = useState(false);
@@ -88,6 +89,14 @@ export const StudioFeedbackBar = memo(function StudioFeedbackBar() {
     return () => clearTimeout(showTimer);
   }, []);
 
+  // Animate height in on entrance — appearing 3s after load, an instant 32px
+  // bar shoves the whole preview stack up mid-task.
+  useEffect(() => {
+    if (!visible) return;
+    const raf = requestAnimationFrame(() => setEntered(true));
+    return () => cancelAnimationFrame(raf);
+  }, [visible]);
+
   // Auto-dismiss timer — reset when user interacts (sets rating)
   useEffect(() => {
     if (!visible || rating !== null || submitted) return;
@@ -141,8 +150,8 @@ export const StudioFeedbackBar = memo(function StudioFeedbackBar() {
   return (
     <div
       className={[
-        "flex items-center gap-3 px-4 h-8 border-t border-neutral-800/50 bg-neutral-900/80 text-[11px] transition-all duration-300",
-        exiting ? "opacity-0 translate-y-2" : "opacity-100 translate-y-0",
+        "flex items-center gap-3 px-4 overflow-hidden border-t border-neutral-800/50 bg-neutral-900/80 text-[11px] transition-all duration-300 motion-reduce:transition-none",
+        entered && !exiting ? "h-8 opacity-100" : "h-0 opacity-0 border-t-transparent",
       ].join(" ")}
     >
       {submitted ? (

package/src/components/StudioGlobalDragOverlay.tsx

@@ -1,6 +1,6 @@
 export function StudioGlobalDragOverlay() {
   return (
-    <div className="absolute inset-0 z-[90] flex items-center justify-center bg-black/50 backdrop-blur-sm pointer-events-none">
+    <div className="hf-backdrop-in absolute inset-0 z-[90] flex items-center justify-center bg-black/50 backdrop-blur-sm pointer-events-none">
       <div className="flex flex-col items-center gap-3 px-8 py-6 rounded-xl border-2 border-dashed border-studio-accent/60 bg-studio-accent/[0.06]">
         <svg
           width="32"