@hyperframes/studio 0.5.0-alpha.9 → 0.5.0

package/src/components/nle/NLELayout.tsx

@@ -5,6 +5,10 @@ import type { TimelineElement } from "../../player";
 import type { BlockedTimelineEditIntent } from "../../player/components/timelineEditing";
 import { NLEPreview } from "./NLEPreview";
 import { CompositionBreadcrumb, type CompositionLevel } from "./CompositionBreadcrumb";
+import {
+  TIMELINE_TOGGLE_SHORTCUT_LABEL,
+  getTimelineToggleTitle,
+} from "../../utils/timelineDiscovery";
 
 interface NLELayoutProps {
   projectId: string;
@@ -85,6 +89,7 @@ export const NLELayout = memo(function NLELayout({
     togglePlay,
     seek,
     onIframeLoad: baseOnIframeLoad,
+    refreshPlayer,
     saveSeekPosition,
   } = useTimelinePlayer();
 
@@ -98,15 +103,13 @@ export const NLELayout = memo(function NLELayout({
     usePlayerStore.getState().reset();
   }
 
-  // Save seek position before the Player component creates a new player
-  // on refreshKey change. The Player handles the actual reload via the
-  // dual-player crossfade; we just need to persist the current time.
+  // Refresh the existing iframe in place when source files change.
   const prevRefreshKeyRef = useRef(refreshKey);
   useEffect(() => {
     if (refreshKey === prevRefreshKeyRef.current) return;
     prevRefreshKeyRef.current = refreshKey;
-    saveSeekPosition();
-  }, [refreshKey, saveSeekPosition]);
+    refreshPlayer();
+  }, [refreshKey, refreshPlayer]);
 
   // Wrap onIframeLoad to also notify parent of iframe ref
   const onIframeLoad = useCallback(() => {
@@ -198,6 +201,7 @@ export const NLELayout = memo(function NLELayout({
 
   // Resizable timeline height
   const [timelineH, setTimelineH] = useState(DEFAULT_TIMELINE_H);
+  const isTimelineVisible = timelineVisible ?? true;
   const isDragging = useRef(false);
   const containerRef = useRef<HTMLDivElement>(null);
 
@@ -205,10 +209,6 @@ export const NLELayout = memo(function NLELayout({
   const currentLevel = compositionStack[compositionStack.length - 1];
   const directUrl = compositionStack.length > 1 ? currentLevel.previewUrl : undefined;
 
-  useEffect(() => {
-    onIframeRef?.(iframeRef.current);
-  }, [compositionStack.length, onIframeRef, refreshKey, iframeRef]);
-
   // Save master seek position before drilling down so we can restore it on back-navigation.
   // saveSeekPosition() sets pendingSeekRef in useTimelinePlayer which onIframeLoad reads.
   const masterSeekRef = useRef(0);
@@ -371,16 +371,11 @@ export const NLELayout = memo(function NLELayout({
               onNavigate={handleNavigateComposition}
             />
           )}
-          <PlayerControls
-            onTogglePlay={togglePlay}
-            onSeek={seek}
-            timelineVisible={timelineVisible ?? true}
-            onToggleTimeline={onToggleTimeline}
-          />
+          <PlayerControls onTogglePlay={togglePlay} onSeek={seek} />
         </div>
       </div>
 
-      {(timelineVisible ?? true) && (
+      {isTimelineVisible ? (
         <>
           {/* Resize divider */}
           <div
@@ -422,7 +417,42 @@ export const NLELayout = memo(function NLELayout({
             {timelineFooter && <div className="flex-shrink-0">{timelineFooter}</div>}
           </div>
         </>
-      )}
+      ) : onToggleTimeline ? (
+        <div className="flex-shrink-0 border-t border-neutral-800/50 bg-neutral-950/96">
+          <div className="flex h-10 items-center justify-between px-3">
+            <div className="text-[10px] font-medium uppercase tracking-[0.16em] text-neutral-500">
+              Timeline
+            </div>
+            <button
+              type="button"
+              onClick={onToggleTimeline}
+              className="flex h-7 items-center gap-1.5 rounded-md border border-neutral-800 px-2.5 text-[11px] font-medium text-neutral-300 transition-colors hover:border-neutral-700 hover:bg-neutral-900 hover:text-neutral-100"
+              title={getTimelineToggleTitle(false)}
+              aria-label="Show timeline editor"
+            >
+              <svg
+                width="13"
+                height="13"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="1.7"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                aria-hidden="true"
+              >
+                <rect x="3" y="13" width="18" height="8" rx="1" />
+                <path d="M7 9h10" />
+                <path d="M8 5h8" />
+              </svg>
+              <span>Show</span>
+              <span className="hidden rounded bg-white/5 px-1 py-0.5 font-mono text-[9px] text-neutral-500 sm:inline">
+                {TIMELINE_TOGGLE_SHORTCUT_LABEL}
+              </span>
+            </button>
+          </div>
+        </div>
+      ) : null}
     </div>
   );
 });

package/src/components/nle/NLEPreview.tsx

@@ -1,4 +1,4 @@
-import { memo, useRef, useState, type Ref } from "react";
+import { memo, type Ref } from "react";
 import { Player } from "../../player";
 
 interface NLEPreviewProps {
@@ -21,17 +21,6 @@ export function getPreviewPlayerKey({
   return directUrl ?? projectId;
 }
 
-/**
- * Manages the composition preview with crossfade on reload.
- *
- * When refreshKey changes, a new Player is mounted alongside the old one.
- * The old Player stays visible (opacity 1) until the new one fires onLoad,
- * at which point the old is removed. This avoids the flash that a simple
- * key-swap remount would cause.
- *
- * Uses the render-time state adjustment pattern (React-sanctioned) to detect
- * refreshKey changes — no useEffect needed.
- */
 export const NLEPreview = memo(function NLEPreview({
   projectId,
   iframeRef,
@@ -40,56 +29,22 @@ export const NLEPreview = memo(function NLEPreview({
   directUrl,
   refreshKey,
 }: NLEPreviewProps) {
-  const baseKey = getPreviewPlayerKey({ projectId, directUrl, refreshKey });
-  const prevRefreshKeyRef = useRef(refreshKey);
-  const [retiringKey, setRetiringKey] = useState<string | null>(null);
-  const retiringTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  // Detect refreshKey change during render (React-sanctioned derived state pattern).
-  // When the key changes, the current active player becomes the retiring player
-  // and a new active player is mounted alongside it.
-  if (refreshKey !== prevRefreshKeyRef.current) {
-    const oldKey = `${baseKey}:${prevRefreshKeyRef.current ?? 0}`;
-    prevRefreshKeyRef.current = refreshKey;
-    setRetiringKey(oldKey);
-  }
-
-  const activeKey = `${baseKey}:${refreshKey ?? 0}`;
-
-  const handleNewPlayerLoad = () => {
-    onIframeLoad();
-    if (retiringTimerRef.current) clearTimeout(retiringTimerRef.current);
-    retiringTimerRef.current = setTimeout(() => {
-      setRetiringKey(null);
-      retiringTimerRef.current = null;
-    }, 160);
-  };
+  const playerKey = getPreviewPlayerKey({ projectId, directUrl, refreshKey });
 
   return (
     <div className="flex flex-col h-full min-h-0">
       <div
-        className="relative flex-1 flex items-center justify-center p-2 overflow-hidden min-h-0 outline-none focus:ring-1 focus:ring-studio-accent/40"
+        className="flex-1 flex items-center justify-center p-2 overflow-hidden min-h-0 outline-none focus:ring-1 focus:ring-studio-accent/40"
         tabIndex={0}
         aria-label="Composition preview"
       >
-        {retiringKey && (
-          <Player
-            key={retiringKey}
-            projectId={directUrl ? undefined : projectId}
-            directUrl={directUrl}
-            onLoad={() => {}}
-            portrait={portrait}
-            style={{ position: "absolute", inset: 0, zIndex: 0, opacity: 1 }}
-          />
-        )}
         <Player
-          key={activeKey}
+          key={playerKey}
           ref={iframeRef}
           projectId={directUrl ? undefined : projectId}
           directUrl={directUrl}
-          onLoad={retiringKey ? handleNewPlayerLoad : onIframeLoad}
+          onLoad={onIframeLoad}
           portrait={portrait}
-          style={retiringKey ? { position: "absolute", inset: 0, zIndex: 1 } : undefined}
         />
       </div>
     </div>

package/src/components/sidebar/AssetsTab.tsx

@@ -2,7 +2,6 @@ import { memo, useState, useCallback, useRef } from "react";
 import { VideoFrameThumbnail } from "../ui/VideoFrameThumbnail";
 import { MEDIA_EXT, IMAGE_EXT, VIDEO_EXT, AUDIO_EXT } from "../../utils/mediaTypes";
 import { TIMELINE_ASSET_MIME } from "../../utils/timelineAssetDrop";
-import { copyTextToClipboard } from "../../utils/clipboard";
 
 interface AssetsTabProps {
   projectId: string;
@@ -299,10 +298,12 @@ export const AssetsTab = memo(function AssetsTab({
   );
 
   const handleCopyPath = useCallback(async (path: string) => {
-    const copied = await copyTextToClipboard(path);
-    if (copied) {
+    try {
+      await navigator.clipboard.writeText(path);
       setCopiedPath(path);
       setTimeout(() => setCopiedPath(null), 1500);
+    } catch {
+      // ignore
     }
   }, []);
 

package/src/components/sidebar/CompositionsTab.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { resolveCompositionPreviewScale, resolveThumbnailSeekTime } from "./CompositionsTab";
+import { resolveCompositionPreviewScale } from "./CompositionsTab";
 
 describe("resolveCompositionPreviewScale", () => {
   it("scales a 16:9 stage to fit the composition card", () => {
@@ -35,18 +35,3 @@ describe("resolveCompositionPreviewScale", () => {
     ).toBeCloseTo(80 / 1920);
   });
 });
-
-describe("resolveThumbnailSeekTime", () => {
-  it("uses the default 3s frame for compositions longer than 3s", () => {
-    expect(resolveThumbnailSeekTime(6)).toBe(3);
-  });
-
-  it("uses the midpoint for compositions shorter than 3s", () => {
-    expect(resolveThumbnailSeekTime(2)).toBe(1);
-  });
-
-  it("falls back to the default 3s frame when duration is unknown", () => {
-    expect(resolveThumbnailSeekTime(null)).toBe(3);
-    expect(resolveThumbnailSeekTime(Number.NaN)).toBe(3);
-  });
-});

package/src/components/sidebar/CompositionsTab.tsx

@@ -1,4 +1,4 @@
-import { memo, useCallback, useEffect, useRef, useState } from "react";
+import { memo, useRef, useState } from "react";
 
 interface CompositionsTabProps {
   projectId: string;
@@ -8,17 +8,6 @@ interface CompositionsTabProps {
 }
 
 const DEFAULT_PREVIEW_STAGE = { width: 1920, height: 1080 };
-const THUMBNAIL_SEEK_TIME_SECONDS = 3;
-const THUMBNAIL_PLAYBACK_SYNC_ATTEMPTS = 10;
-
-type PreviewWindow = Window & {
-  __player?: {
-    play?: () => void;
-    pause?: () => void;
-    seek?: (time: number) => void;
-    getDuration?: () => number;
-  };
-};
 
 export function resolveCompositionPreviewScale(input: {
   cardWidth: number;
@@ -39,54 +28,6 @@ export function resolveCompositionPreviewScale(input: {
   return Math.min(scaleX, scaleY);
 }
 
-export function resolveThumbnailSeekTime(durationSeconds: number | null | undefined): number {
-  if (
-    Number.isFinite(durationSeconds) &&
-    durationSeconds != null &&
-    durationSeconds > 0 &&
-    durationSeconds < THUMBNAIL_SEEK_TIME_SECONDS
-  ) {
-    return durationSeconds / 2;
-  }
-
-  return THUMBNAIL_SEEK_TIME_SECONDS;
-}
-
-function parsePositiveNumber(value: string | null): number | null {
-  if (value == null) return null;
-  const parsed = Number.parseFloat(value);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
-}
-
-function resolveIframeDuration(iframe: HTMLIFrameElement | null): number | null {
-  const win = iframe?.contentWindow as PreviewWindow | null;
-  const playerDuration = win?.__player?.getDuration?.();
-  if (Number.isFinite(playerDuration) && playerDuration != null && playerDuration > 0) {
-    return playerDuration;
-  }
-
-  const doc = iframe?.contentDocument;
-  const root = doc?.querySelector("[data-composition-id]") ?? doc?.documentElement ?? null;
-  return (
-    parsePositiveNumber(root?.getAttribute("data-composition-duration") ?? null) ??
-    parsePositiveNumber(root?.getAttribute("data-duration") ?? null)
-  );
-}
-
-function syncIframePlayback(iframe: HTMLIFrameElement | null, shouldPlay: boolean): boolean {
-  const player = (iframe?.contentWindow as PreviewWindow | null)?.__player;
-  if (!player) return false;
-
-  if (shouldPlay) {
-    player.play?.();
-    return true;
-  }
-
-  player.pause?.();
-  player.seek?.(resolveThumbnailSeekTime(resolveIframeDuration(iframe)));
-  return true;
-}
-
 function CompCard({
   projectId,
   comp,
@@ -100,25 +41,7 @@ function CompCard({
 }) {
   const [hovered, setHovered] = useState(false);
   const [stageSize, setStageSize] = useState(DEFAULT_PREVIEW_STAGE);
-  const iframeRef = useRef<HTMLIFrameElement | null>(null);
   const hoverTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const syncTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  const requestIframePlaybackSync = useCallback((shouldPlay: boolean) => {
-    if (syncTimer.current) {
-      clearTimeout(syncTimer.current);
-      syncTimer.current = null;
-    }
-
-    const sync = (remainingAttempts: number) => {
-      if (syncIframePlayback(iframeRef.current, shouldPlay) || remainingAttempts <= 0) return;
-
-      syncTimer.current = setTimeout(() => sync(remainingAttempts - 1), 100);
-    };
-
-    sync(THUMBNAIL_PLAYBACK_SYNC_ATTEMPTS);
-  }, []);
-
   const handleEnter = () => {
     hoverTimer.current = setTimeout(() => setHovered(true), 300);
   };
@@ -130,6 +53,7 @@ function CompCard({
     setHovered(false);
   };
   const name = comp.replace(/^compositions\//, "").replace(/\.html$/, "");
+  const thumbnailUrl = `/api/projects/${projectId}/thumbnail/${comp}?t=2`;
   const previewUrl = `/api/projects/${projectId}/preview/comp/${comp}`;
   const previewScale = resolveCompositionPreviewScale({
     cardWidth: 80,
@@ -138,17 +62,6 @@ function CompCard({
     stageHeight: stageSize.height,
   });
 
-  useEffect(() => {
-    requestIframePlaybackSync(hovered);
-  }, [hovered, requestIframePlaybackSync]);
-
-  useEffect(() => {
-    return () => {
-      if (hoverTimer.current) clearTimeout(hoverTimer.current);
-      if (syncTimer.current) clearTimeout(syncTimer.current);
-    };
-  }, []);
-
   return (
     <div
       onClick={onSelect}
@@ -161,34 +74,49 @@ function CompCard({
       }`}
     >
       <div className="w-20 h-[45px] rounded overflow-hidden bg-neutral-900 flex-shrink-0 relative">
-        <iframe
-          ref={iframeRef}
-          src={previewUrl}
-          sandbox="allow-scripts allow-same-origin"
-          loading="lazy"
-          className="absolute left-0 top-0 border-none pointer-events-none"
-          style={{
-            transformOrigin: "0 0",
-            width: stageSize.width,
-            height: stageSize.height,
-            transform: `scale(${previewScale})`,
-          }}
-          onLoad={(e) => {
-            try {
-              const iframe = e.currentTarget;
-              const root = iframe.contentDocument?.querySelector("[data-composition-id]");
-              const width = Number(root?.getAttribute("data-width")) || DEFAULT_PREVIEW_STAGE.width;
-              const height =
-                Number(root?.getAttribute("data-height")) || DEFAULT_PREVIEW_STAGE.height;
-              setStageSize({ width, height });
-              requestIframePlaybackSync(hovered);
-            } catch {
-              setStageSize(DEFAULT_PREVIEW_STAGE);
-            }
-          }}
-          title={`${name} preview`}
-          tabIndex={-1}
-        />
+        {/* Live iframe preview on hover */}
+        {hovered && (
+          <iframe
+            src={previewUrl}
+            sandbox="allow-scripts allow-same-origin"
+            className="absolute left-0 top-0 border-none pointer-events-none"
+            style={{
+              transformOrigin: "0 0",
+              width: stageSize.width,
+              height: stageSize.height,
+              transform: `scale(${previewScale})`,
+            }}
+            onLoad={(e) => {
+              try {
+                const iframe = e.currentTarget;
+                const root = iframe.contentDocument?.querySelector("[data-composition-id]");
+                const width =
+                  Number(root?.getAttribute("data-width")) || DEFAULT_PREVIEW_STAGE.width;
+                const height =
+                  Number(root?.getAttribute("data-height")) || DEFAULT_PREVIEW_STAGE.height;
+                setStageSize({ width, height });
+              } catch {
+                setStageSize(DEFAULT_PREVIEW_STAGE);
+              }
+            }}
+            tabIndex={-1}
+          />
+        )}
+        {/* Static thumbnail — hidden while hovering */}
+        <div
+          className="absolute inset-0 transition-opacity duration-150"
+          style={{ opacity: hovered ? 0 : 1 }}
+        >
+          <img
+            src={thumbnailUrl}
+            alt={name}
+            loading="lazy"
+            className="w-full h-full object-contain"
+            onError={(e) => {
+              (e.target as HTMLImageElement).style.display = "none";
+            }}
+          />
+        </div>
       </div>
       <div className="min-w-0 flex-1">
         <span className="text-[11px] font-medium text-neutral-300 truncate block">{name}</span>

package/src/components/sidebar/LeftSidebar.tsx

@@ -35,6 +35,7 @@ interface LeftSidebarProps {
   codeChildren?: ReactNode;
   onLint?: () => void;
   linting?: boolean;
+  onToggleCollapse?: () => void;
 }
 
 export const LeftSidebar = memo(function LeftSidebar({
@@ -57,6 +58,7 @@ export const LeftSidebar = memo(function LeftSidebar({
   codeChildren,
   onLint,
   linting,
+  onToggleCollapse,
 }: LeftSidebarProps) {
   const [tab, setTab] = useState<SidebarTab>(getPersistedTab);
 
@@ -88,45 +90,64 @@ export const LeftSidebar = memo(function LeftSidebar({
       style={{ width }}
     >
       {/* Tabs — Code first */}
-      <div className="border-b border-neutral-800/50 px-3 py-3 flex-shrink-0">
-        <div
-          className="grid gap-1 rounded-[18px] bg-neutral-900 p-1 shadow-[inset_0_1px_0_rgba(255,255,255,0.03)]"
-          style={{ gridTemplateColumns: "0.9fr 1.25fr 0.9fr" }}
+      <div className="flex border-b border-neutral-800/50 flex-shrink-0">
+        <button
+          type="button"
+          onClick={() => selectTab("code")}
+          className={`flex-1 py-2 text-[11px] font-medium transition-colors ${
+            tab === "code"
+              ? "text-neutral-200 border-b-2 border-studio-accent"
+              : "text-neutral-500 hover:text-neutral-400"
+          }`}
         >
+          Code
+        </button>
+        <button
+          type="button"
+          onClick={() => selectTab("compositions")}
+          className={`flex-1 py-2 text-[11px] font-medium transition-colors ${
+            tab === "compositions"
+              ? "text-neutral-200 border-b-2 border-studio-accent"
+              : "text-neutral-500 hover:text-neutral-400"
+          }`}
+        >
+          Compositions
+        </button>
+        <button
+          type="button"
+          onClick={() => selectTab("assets")}
+          className={`flex-1 py-2 text-[11px] font-medium transition-colors ${
+            tab === "assets"
+              ? "text-neutral-200 border-b-2 border-studio-accent"
+              : "text-neutral-500 hover:text-neutral-400"
+          }`}
+        >
+          Assets
+        </button>
+        {onToggleCollapse && (
           <button
             type="button"
-            onClick={() => selectTab("code")}
-            className={`rounded-[14px] px-2.5 py-2 text-[10px] font-semibold transition-all ${
-              tab === "code"
-                ? "bg-neutral-800 text-white"
-                : "text-neutral-500 hover:text-neutral-200"
-            }`}
-          >
-            Code
-          </button>
-          <button
-            type="button"
-            onClick={() => selectTab("compositions")}
-            className={`rounded-[14px] px-2.5 py-2 text-[10px] font-semibold transition-all ${
-              tab === "compositions"
-                ? "bg-neutral-800 text-white"
-                : "text-neutral-500 hover:text-neutral-200"
-            }`}
-          >
-            Compositions
-          </button>
-          <button
-            type="button"
-            onClick={() => selectTab("assets")}
-            className={`rounded-[14px] px-2.5 py-2 text-[10px] font-semibold transition-all ${
-              tab === "assets"
-                ? "bg-neutral-800 text-white"
-                : "text-neutral-500 hover:text-neutral-200"
-            }`}
+            onClick={onToggleCollapse}
+            className="mx-1 my-1 flex h-7 w-7 flex-shrink-0 items-center justify-center rounded-md border border-transparent text-neutral-500 transition-colors hover:border-neutral-800 hover:bg-neutral-900 hover:text-neutral-300"
+            title="Hide sidebar"
+            aria-label="Hide sidebar"
           >
-            Assets
+            <svg
+              width="14"
+              height="14"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="1.5"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              aria-hidden="true"
+            >
+              <path d="m14 7-5 5 5 5" />
+              <path d="M19 4v16" />
+            </svg>
           </button>
-        </div>
+        )}
       </div>
 
       {/* Tab content */}

package/src/components/ui/HyperframesLoader.tsx

@@ -0,0 +1,104 @@
+export interface HyperframesLoaderProps {
+  /** Status text shown below the mark. */
+  title: string;
+  /** Optional secondary detail line. */
+  detail?: string;
+  /** Optional monospace third line for IDs, counts, or percentages. */
+  mono?: string;
+  /** Pixel size of the mark itself; status text scales independently. */
+  size?: number;
+  /** Optional normalized progress value from 0 to 1. */
+  progress?: number;
+}
+
+export function HyperframesLoader({
+  title,
+  detail,
+  mono,
+  size = 64,
+  progress,
+}: HyperframesLoaderProps) {
+  const boundedProgress =
+    typeof progress === "number" && Number.isFinite(progress)
+      ? Math.min(1, Math.max(0, progress))
+      : undefined;
+  const markFrameSize = Math.round(size * 1.16);
+
+  return (
+    <div className="hf-loader" draggable={false}>
+      <div
+        className="hf-loader-mark-frame"
+        style={{ width: markFrameSize, height: markFrameSize }}
+        draggable={false}
+      >
+        <svg
+          className="hf-loader-mark"
+          width={size}
+          height={size}
+          viewBox="0 0 100 100"
+          fill="none"
+          xmlns="http://www.w3.org/2000/svg"
+          aria-hidden="true"
+        >
+          <g className="hf-loader-mark__mark" transform="translate(50 50)">
+            <g className="hf-loader-mark__core" transform="scale(1)" opacity=".92">
+              <g transform="translate(-50 -50)">
+                <path
+                  d="M10.1851 57.8021L33.1145 73.8313C36.2202 75.9978 41.5173 73.5433 42.4816 69.4984L51.7611 30.4271C52.7253 26.3822 48.5802 23.9277 44.4602 26.0942L13.917 42.1235C6.96677 45.7676 4.97564 54.1579 10.1851 57.8021Z"
+                  fill="url(#hf-loader-grad-left)"
+                />
+                <path
+                  d="M87.5129 57.5141L56.9696 73.5433C52.8371 75.7098 48.7046 73.2553 49.6688 69.2104L58.9483 30.1391C59.9125 26.0942 65.2097 23.6397 68.3154 25.8062L91.2447 41.8354C96.4668 45.4796 94.4631 53.8699 87.5129 57.5141Z"
+                  fill="url(#hf-loader-grad-right)"
+                />
+              </g>
+            </g>
+          </g>
+          <defs>
+            <linearGradient
+              id="hf-loader-grad-left"
+              x1="48.5676"
+              y1="25"
+              x2="44.7804"
+              y2="71.9384"
+              gradientUnits="userSpaceOnUse"
+            >
+              <stop stopColor="#06E3FA" />
+              <stop offset="1" stopColor="#4FDB5E" />
+            </linearGradient>
+            <linearGradient
+              id="hf-loader-grad-right"
+              x1="54.8282"
+              y1="73.8392"
+              x2="72.0989"
+              y2="32.8932"
+              gradientUnits="userSpaceOnUse"
+            >
+              <stop stopColor="#06E3FA" />
+              <stop offset="1" stopColor="#4FDB5E" />
+            </linearGradient>
+          </defs>
+        </svg>
+      </div>
+      <div className="hf-loader-title">{title}</div>
+      {detail && <div className="hf-loader-detail">{detail}</div>}
+      {boundedProgress !== undefined && (
+        <div className="hf-loader-progress" aria-hidden="true">
+          <div
+            className="hf-loader-progress__fill"
+            style={{ transform: `scaleX(${boundedProgress})` }}
+          />
+        </div>
+      )}
+      {mono && <div className="hf-loader-mono">{mono}</div>}
+    </div>
+  );
+}
+
+export function StatusFrame(props: HyperframesLoaderProps) {
+  return (
+    <div className="hf-frame">
+      <HyperframesLoader {...props} />
+    </div>
+  );
+}

package/src/components/ui/index.ts

@@ -1,2 +1,4 @@
 // Minimal UI primitives for studio canvas components
 export { Button, IconButton } from "./Button";
+export { HyperframesLoader, StatusFrame } from "./HyperframesLoader";
+export type { HyperframesLoaderProps } from "./HyperframesLoader";