@hyperframes/studio 0.1.0

package/src/index.ts

@@ -0,0 +1,31 @@
+// NLE Layout
+export { NLELayout } from "./components/nle/NLELayout";
+export { NLEPreview } from "./components/nle/NLEPreview";
+export { CompositionBreadcrumb } from "./components/nle/CompositionBreadcrumb";
+export type { CompositionLevel } from "./components/nle/CompositionBreadcrumb";
+
+// Player (preview, timeline, playback controls)
+export {
+  Player,
+  PlayerControls,
+  Timeline,
+  PreviewPanel,
+  AgentActivityTrack,
+  useTimelinePlayer,
+  usePlayerStore,
+  liveTime,
+  formatTime,
+} from "./player";
+export type { AgentActivity, TimelineElement, ActiveEdits } from "./player";
+
+// Editor
+export { SourceEditor } from "./components/editor/SourceEditor";
+export { PropertyPanel } from "./components/editor/PropertyPanel";
+export { FileTree } from "./components/editor/FileTree";
+
+// App
+export { StudioApp } from "./App";
+
+// Hooks
+export { useCodeEditor } from "./hooks/useCodeEditor";
+export { useElementPicker } from "./hooks/useElementPicker";

package/src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { StudioApp } from "./App";
+import "./styles/studio.css";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <StudioApp />
+  </StrictMode>,
+);

package/src/player/components/AgentActivityTrack.tsx

@@ -0,0 +1,98 @@
+import { memo } from "react";
+
+const TRACK_H = 20;
+const GUTTER = 32;
+
+export interface AgentActivity {
+  agentId: string;
+  name: string;
+  color: string;
+  /** Active work periods mapped to VIDEO time (not wall clock) */
+  periods: Array<{ start: number; end: number }>;
+  /** Element creation events at specific video times */
+  events: Array<{ time: number; type: "create" | "modify" }>;
+}
+
+interface AgentActivityTrackProps {
+  agents: AgentActivity[];
+  duration: number;
+}
+
+export const AgentActivityTrack = memo(function AgentActivityTrack({ agents, duration }: AgentActivityTrackProps) {
+  if (agents.length === 0 || duration <= 0) return null;
+
+  return (
+    <div className="border-t border-neutral-800/30">
+      {/* Section header */}
+      <div className="flex items-center gap-1.5 px-2 py-1 text-[9px] text-neutral-600 font-medium uppercase tracking-wider">
+        <svg width="10" height="10" viewBox="0 0 24 24" fill="currentColor"><circle cx="12" cy="12" r="4" /></svg>
+        Agent Activity
+      </div>
+
+      {agents.map((agent) => (
+        <div
+          key={agent.agentId}
+          className="relative flex"
+          style={{ height: TRACK_H }}
+        >
+          {/* Gutter: agent name */}
+          <div
+            className="flex-shrink-0 flex items-center justify-center"
+            style={{ width: GUTTER }}
+            title={agent.name}
+          >
+            <div
+              className="w-2 h-2 rounded-full"
+              style={{ backgroundColor: agent.color }}
+            />
+          </div>
+
+          {/* Lane */}
+          <div className="flex-1 relative" style={{ backgroundColor: `${agent.color}06` }}>
+            {/* Active work periods */}
+            {agent.periods.map((period, i) => {
+              const leftPct = (period.start / duration) * 100;
+              const widthPct = ((period.end - period.start) / duration) * 100;
+              return (
+                <div
+                  key={`period-${i}`}
+                  className="absolute top-1 bottom-1 rounded-sm"
+                  style={{
+                    left: `${leftPct}%`,
+                    width: `${Math.max(widthPct, 0.5)}%`,
+                    backgroundColor: `${agent.color}30`,
+                    border: `1px solid ${agent.color}20`,
+                  }}
+                />
+              );
+            })}
+
+            {/* Events: diamonds for create, circles for modify */}
+            {agent.events.map((event, i) => {
+              const leftPct = (event.time / duration) * 100;
+              return (
+                <div
+                  key={`event-${i}`}
+                  className="absolute top-1/2 -translate-y-1/2 -translate-x-1/2"
+                  style={{ left: `${leftPct}%` }}
+                >
+                  {event.type === "create" ? (
+                    <div
+                      className="w-2 h-2 rotate-45"
+                      style={{ backgroundColor: agent.color }}
+                    />
+                  ) : (
+                    <div
+                      className="w-1.5 h-1.5 rounded-full"
+                      style={{ backgroundColor: agent.color }}
+                    />
+                  )}
+                </div>
+              );
+            })}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+});

package/src/player/components/Player.tsx

@@ -0,0 +1,120 @@
+import { forwardRef, useRef, useState, useCallback } from "react";
+import { useMountEffect } from "../lib/useMountEffect";
+
+const NATIVE_W = 1920;
+const NATIVE_H = 1080;
+
+interface PlayerProps {
+  projectId?: string;
+  directUrl?: string;
+  onLoad: () => void;
+  portrait?: boolean;
+}
+
+export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(({ projectId, directUrl, onLoad, portrait }, ref) => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [scale, setScale] = useState(1);
+  const dimsRef = useRef({ w: portrait ? NATIVE_H : NATIVE_W, h: portrait ? NATIVE_W : NATIVE_H });
+  const [dims, setDims] = useState(dimsRef.current);
+  const loadCountRef = useRef(0);
+
+  const updateScale = useCallback(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const rect = el.getBoundingClientRect();
+    const d = dimsRef.current;
+    setScale(Math.min(rect.width / d.w, rect.height / d.h));
+  }, []);
+
+  useMountEffect(() => {
+    updateScale();
+    const ro = new ResizeObserver(updateScale);
+    if (containerRef.current) ro.observe(containerRef.current);
+
+    // Listen for stage-size messages from the runtime
+    const handleMessage = (e: MessageEvent) => {
+      const data = e.data;
+      if ((data?.source === "hf-preview" || data?.source === "hf-preview") && data?.type === "stage-size" && data.width > 0 && data.height > 0) {
+        if (dimsRef.current.w !== data.width || dimsRef.current.h !== data.height) {
+          dimsRef.current = { w: data.width, h: data.height };
+          setDims(dimsRef.current);
+          updateScale();
+        }
+      }
+    };
+    window.addEventListener("message", handleMessage);
+
+    return () => {
+      ro.disconnect();
+      window.removeEventListener("message", handleMessage);
+    };
+  });
+
+  const handleLoad = useCallback(() => {
+    loadCountRef.current++;
+
+    // Auto-detect dimensions from the composition's data-width/data-height
+    try {
+      const iframeEl = typeof ref === "function" ? null : ref?.current;
+      const doc = iframeEl?.contentDocument;
+      if (doc) {
+        const root = doc.querySelector("[data-composition-id]");
+        if (root) {
+          const dw = parseInt(root.getAttribute("data-width") || "0", 10);
+          const dh = parseInt(root.getAttribute("data-height") || "0", 10);
+          if (dw > 0 && dh > 0 && (dw !== dimsRef.current.w || dh !== dimsRef.current.h)) {
+            dimsRef.current = { w: dw, h: dh };
+            setDims(dimsRef.current);
+            // Recalc scale with new dims
+            const el = containerRef.current;
+            if (el) {
+              const rect = el.getBoundingClientRect();
+              setScale(Math.min(rect.width / dw, rect.height / dh));
+            }
+          }
+        }
+      }
+    } catch {
+      // Cross-origin
+    }
+
+    if (loadCountRef.current > 1) {
+      const el = containerRef.current;
+      if (el) {
+        el.classList.remove("preview-revealing");
+        void el.offsetWidth;
+        el.classList.add("preview-revealing");
+        const onEnd = () => el.classList.remove("preview-revealing");
+        el.addEventListener("animationend", onEnd, { once: true });
+      }
+    }
+    onLoad();
+  }, [onLoad, ref]);
+
+  return (
+    <div
+      ref={containerRef}
+      className="w-full h-full max-w-full max-h-full overflow-hidden shadow-float border border-neutral-800 bg-black flex items-center justify-center rounded-card-inner"
+    >
+      <iframe
+        ref={ref}
+        src={directUrl || `/api/projects/${projectId}/preview`}
+        onLoad={handleLoad}
+        sandbox="allow-scripts allow-same-origin"
+        allow="autoplay; fullscreen"
+        referrerPolicy="no-referrer"
+        title="Project Preview"
+        style={{
+          width: dims.w,
+          height: dims.h,
+          border: "none",
+          transform: `scale(${scale})`,
+          transformOrigin: "center center",
+          flexShrink: 0,
+        }}
+      />
+    </div>
+  );
+});
+
+Player.displayName = "Player";

package/src/player/components/PlayerControls.tsx

@@ -0,0 +1,181 @@
+import { useRef, useState, useCallback, memo } from "react";
+import { formatTime } from "../lib/time";
+import { usePlayerStore, liveTime } from "../store/playerStore";
+import { useMountEffect } from "../lib/useMountEffect";
+
+const SPEED_OPTIONS = [0.25, 0.5, 1, 1.5, 2] as const;
+
+interface PlayerControlsProps {
+  /** @deprecated Pass via store — kept for backwards compat */
+  isPlaying?: boolean;
+  /** @deprecated Pass via store — kept for backwards compat */
+  duration?: number;
+  /** @deprecated Pass via store — kept for backwards compat */
+  timelineReady?: boolean;
+  onTogglePlay: () => void;
+  onSeek: (time: number) => void;
+}
+
+export const PlayerControls = memo(function PlayerControls({ onTogglePlay, onSeek, ...overrides }: PlayerControlsProps) {
+  // Subscribe to only the fields we render — each selector prevents cascading re-renders
+  const storeIsPlaying = usePlayerStore((s) => s.isPlaying);
+  const storeDuration = usePlayerStore((s) => s.duration);
+  const storeTimelineReady = usePlayerStore((s) => s.timelineReady);
+  const playbackRate = usePlayerStore((s) => s.playbackRate);
+  const setPlaybackRate = usePlayerStore.getState().setPlaybackRate;
+  const [showSpeedMenu, setShowSpeedMenu] = useState(false);
+
+  const isPlaying = overrides.isPlaying ?? storeIsPlaying;
+  const duration = overrides.duration ?? storeDuration;
+  const timelineReady = overrides.timelineReady ?? storeTimelineReady;
+
+  const progressFillRef = useRef<HTMLDivElement>(null);
+  const progressThumbRef = useRef<HTMLDivElement>(null);
+  const timeDisplayRef = useRef<HTMLSpanElement>(null);
+  const seekBarRef = useRef<HTMLDivElement>(null);
+  const isDraggingRef = useRef(false);
+  const currentTimeRef = useRef(0);
+
+  const durationRef = useRef(duration);
+  durationRef.current = duration;
+  useMountEffect(() => {
+    const unsub = liveTime.subscribe((t) => {
+      currentTimeRef.current = t;
+      const dur = durationRef.current;
+      const pct = dur > 0 ? (t / dur) * 100 : 0;
+      if (progressFillRef.current) progressFillRef.current.style.width = `${pct}%`;
+      if (progressThumbRef.current) progressThumbRef.current.style.left = `${pct}%`;
+      if (timeDisplayRef.current) timeDisplayRef.current.textContent = formatTime(t);
+    });
+    return unsub;
+  });
+
+  const seekFromClientX = useCallback(
+    (clientX: number) => {
+      const bar = seekBarRef.current;
+      if (!bar || duration <= 0) return;
+      const rect = bar.getBoundingClientRect();
+      const percent = Math.max(0, Math.min(1, (clientX - rect.left) / rect.width));
+      onSeek(percent * duration);
+    },
+    [duration, onSeek],
+  );
+
+  const handleMouseDown = useCallback(
+    (e: React.MouseEvent) => {
+      e.preventDefault();
+      isDraggingRef.current = true;
+      seekFromClientX(e.clientX);
+
+      const onMouseMove = (me: MouseEvent) => {
+        if (isDraggingRef.current) seekFromClientX(me.clientX);
+      };
+      const onMouseUp = () => {
+        isDraggingRef.current = false;
+        window.removeEventListener("mousemove", onMouseMove);
+        window.removeEventListener("mouseup", onMouseUp);
+      };
+
+      window.addEventListener("mousemove", onMouseMove);
+      window.addEventListener("mouseup", onMouseUp);
+    },
+    [seekFromClientX],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (!timelineReady || duration <= 0) return;
+      const step = e.shiftKey ? 5 : 1;
+      if (e.key === "ArrowLeft") {
+        e.preventDefault();
+        onSeek(Math.max(0, currentTimeRef.current - step));
+      } else if (e.key === "ArrowRight") {
+        e.preventDefault();
+        onSeek(Math.min(duration, currentTimeRef.current + step));
+      }
+    },
+    [timelineReady, duration, onSeek],
+  );
+
+  return (
+    <div className="px-3 py-2 flex items-center gap-3">
+      <button
+        type="button"
+        aria-label={isPlaying ? "Pause" : "Play"}
+        onClick={onTogglePlay}
+        disabled={!timelineReady}
+        className="flex-shrink-0 w-7 h-7 flex items-center justify-center rounded-md text-neutral-300 hover:text-white hover:bg-neutral-800 disabled:opacity-40 disabled:pointer-events-none transition-colors"
+      >
+        {isPlaying ? (
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+            <rect x="6" y="4" width="4" height="16" rx="1" />
+            <rect x="14" y="4" width="4" height="16" rx="1" />
+          </svg>
+        ) : (
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+            <path d="M8 5v14l11-7z" />
+          </svg>
+        )}
+      </button>
+
+      <span className="text-neutral-500 font-mono text-xs tabular-nums flex-shrink-0 min-w-[80px]">
+        <span ref={timeDisplayRef}>{formatTime(0)}</span>
+        <span className="text-neutral-700 mx-0.5">/</span>
+        <span className="text-neutral-600">{formatTime(duration)}</span>
+      </span>
+
+      <div
+        ref={seekBarRef}
+        role="slider"
+        tabIndex={0}
+        aria-label="Seek"
+        aria-valuemin={0}
+        aria-valuemax={Math.round(duration)}
+        aria-valuenow={0}
+        className="flex-1 h-6 flex items-center cursor-pointer group"
+        style={{ touchAction: "manipulation" }}
+        onMouseDown={handleMouseDown}
+        onKeyDown={handleKeyDown}
+      >
+        <div className="w-full h-[3px] bg-neutral-800 rounded-full relative">
+          <div
+            ref={progressFillRef}
+            className="absolute inset-y-0 left-0 bg-white/80 rounded-full"
+            style={{ width: 0 }}
+          />
+          <div
+            ref={progressThumbRef}
+            className="absolute top-1/2 w-2 h-2 bg-white rounded-full -translate-y-1/2 -translate-x-1/2 opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 transition-opacity"
+            style={{ left: 0 }}
+          />
+        </div>
+      </div>
+
+      {/* Speed control */}
+      <div className="relative flex-shrink-0">
+        <button
+          type="button"
+          onClick={() => setShowSpeedMenu((v) => !v)}
+          className="px-1.5 py-0.5 rounded text-[11px] font-mono tabular-nums text-neutral-500 hover:text-neutral-200 hover:bg-neutral-800 transition-colors"
+        >
+          {playbackRate === 1 ? "1x" : `${playbackRate}x`}
+        </button>
+        {showSpeedMenu && (
+          <div className="absolute bottom-full right-0 mb-1 py-1 bg-neutral-900 border border-neutral-700 rounded-lg shadow-xl z-50 min-w-[60px]">
+            {SPEED_OPTIONS.map((rate) => (
+              <button
+                key={rate}
+                onClick={() => { setPlaybackRate(rate); setShowSpeedMenu(false); }}
+                className={`block w-full px-3 py-1 text-xs text-left font-mono tabular-nums transition-colors ${
+                  rate === playbackRate ? "text-white bg-neutral-800" : "text-neutral-400 hover:text-white hover:bg-neutral-800"
+                }`}
+              >
+                {rate}x
+              </button>
+            ))}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+});

package/src/player/components/PreviewPanel.tsx

@@ -0,0 +1,149 @@
+import type { ReactNode, Ref } from "react";
+import { Player } from "./Player";
+import { PlayerControls } from "./PlayerControls";
+import { Timeline } from "./Timeline";
+
+interface RenderStatus {
+  state: "idle" | "rendering" | "complete" | "error";
+  stage?: string;
+  progress?: number;
+  error?: string;
+  onRender?: () => void;
+}
+
+interface PreviewPanelProps {
+  projectId: string | null;
+  hasProject: boolean;
+  portrait: boolean;
+  iframeRef: Ref<HTMLIFrameElement>;
+  onIframeLoad: () => void;
+  onTogglePlay: () => void;
+  onSeek: (t: number) => void;
+  /** Optional render status — pass to show rendering progress/state */
+  renderStatus?: RenderStatus;
+  /** Optional slot for custom content below the timeline */
+  children?: ReactNode;
+}
+
+export function PreviewPanel({
+  projectId,
+  hasProject,
+  portrait,
+  iframeRef,
+  onIframeLoad,
+  onTogglePlay,
+  onSeek,
+  renderStatus,
+  children,
+}: PreviewPanelProps) {
+
+  const renderState = renderStatus?.state ?? "idle";
+
+  return (
+    <div
+      className="min-w-0 overflow-hidden"
+      style={{
+        display: "grid",
+        gridTemplateRows: hasProject && projectId ? "1fr auto auto auto" : "1fr",
+        height: "100%",
+        minHeight: 0,
+      }}
+    >
+      {hasProject && projectId ? (
+        <>
+          {/* Player — takes all remaining space, constrained for portrait */}
+          <div className="flex items-center justify-center p-2 overflow-hidden" style={{ minHeight: 0, minWidth: 0 }}>
+            <Player ref={iframeRef} projectId={projectId} onLoad={onIframeLoad} portrait={portrait} />
+          </div>
+
+          {/* Controls — fixed height */}
+          <div className="bg-neutral-950 border-t border-neutral-800 flex-shrink-0">
+            <PlayerControls
+              onTogglePlay={onTogglePlay}
+              onSeek={onSeek}
+            />
+          </div>
+
+          {/* Timeline — capped height, internal scroll */}
+          <div className="bg-neutral-950 flex-shrink-0 overflow-y-auto" style={{ maxHeight: "100px" }}>
+            <Timeline onSeek={onSeek} />
+          </div>
+
+          {/* Render status — only shown when actively rendering, complete, or error */}
+          {renderStatus && (renderState === "rendering" || renderState === "complete" || renderState === "error") && (
+            <div className="bg-neutral-950 border-t border-neutral-800 px-4 py-2 flex items-center justify-end gap-2 flex-shrink-0">
+              {renderState === "rendering" && (
+                <div className="flex-1">
+                  <div className="flex items-center gap-2">
+                    <div className="flex-1 h-1.5 bg-neutral-800 rounded-full overflow-hidden">
+                      <div
+                        className="h-full bg-blue-500 rounded-full transition-[width] duration-200"
+                        style={{ width: `${renderStatus.progress ?? 0}%` }}
+                      />
+                    </div>
+                    <span className="text-xs text-neutral-400 flex-shrink-0">
+                      {renderStatus.stage || "Rendering..."}
+                    </span>
+                  </div>
+                </div>
+              )}
+              {renderState === "complete" && (
+                <div className="flex items-center gap-1.5 text-xs text-green-400">
+                  <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+                    <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14" />
+                    <polyline points="22 4 12 14.01 9 11.01" />
+                  </svg>
+                  <span>Complete</span>
+                </div>
+              )}
+              {renderState === "error" && (
+                <div className="flex items-center gap-2 text-xs text-red-400">
+                  <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+                    <circle cx="12" cy="12" r="10" />
+                    <line x1="12" y1="8" x2="12" y2="12" />
+                    <line x1="12" y1="16" x2="12.01" y2="16" />
+                  </svg>
+                  <span className="truncate">{renderStatus.error}</span>
+                  {renderStatus.onRender && (
+                    <button
+                      type="button"
+                      onClick={renderStatus.onRender}
+                      className="flex-shrink-0 px-2 py-0.5 text-xs text-neutral-300 hover:text-white hover:bg-neutral-800 rounded transition-colors"
+                    >
+                      Retry
+                    </button>
+                  )}
+                </div>
+              )}
+            </div>
+          )}
+
+          {/* Optional custom slot */}
+          {children}
+        </>
+      ) : (
+        <div className="flex items-center justify-center w-full min-w-0">
+          <div className="text-center w-full">
+            <div className="w-16 h-16 mx-auto mb-4 rounded-card bg-neutral-900 flex items-center justify-center">
+              <svg
+                width="24"
+                height="24"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="1.5"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                className="text-neutral-600"
+              >
+                <polygon points="5 3 19 12 5 21 5 3" />
+              </svg>
+            </div>
+            <p className="text-sm text-neutral-600">Preview will appear here</p>
+            <p className="text-xs text-neutral-700 mt-1">Send a message to generate a video composition</p>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}