feat(studio): storyboard view-mode toggle and shell (#1529)

Second PR in the Studio storyboarding stack. Adds the top-level toggle
between the storyboard and the timeline/preview stage, behind the flag.

- STUDIO_STORYBOARD_ENABLED flag (VITE_STUDIO_ENABLE_STORYBOARD, default
  off) now gates the UI.
- ViewModeContext: timeline|storyboard state mirrored to the ?view= query
  param, so it survives reloads and an agent can deep-link ?view=storyboard.
- Segmented Storyboard|Preview control in StudioHeader (flag-gated).
- StudioApp swaps the whole center stage for a full-width StoryboardView
  when storyboard mode is active.
- useStoryboard hook + StoryboardView shell: global-direction header,
  loading/error/empty states. The frame contact-sheet grid lands in PR3.
- Extract StudioOverlays from App.tsx to stay within the 600-line studio
  decomposition budget.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
James Russo
2026-06-17 13:06:49 -07:00
committed by GitHub
co-authored by Claude Opus 4.8
parent 8a13a07074
commit 195d7aa7bd
8 changed files with 526 additions and 123 deletions
+115 -123
View File
@@ -2,7 +2,7 @@ import { useState, useCallback, useRef, useMemo, useEffect, useLayoutEffect } fr
import type { LeftSidebarHandle, SidebarTab } from "./components/sidebar/LeftSidebar";
import { useRenderQueue } from "./components/renders/useRenderQueue";
import { usePlayerStore } from "./player";
import { LintModal } from "./components/LintModal";
import { StudioOverlays } from "./components/StudioOverlays";
import { SaveQueuePausedBanner } from "./components/SaveQueuePausedBanner";
import { useCaptionStore } from "./captions/store";
import { useCaptionSync } from "./captions/hooks/useCaptionSync";
@@ -33,13 +33,13 @@ import {
useDragOverlay,
useInspectorState,
} from "./hooks/useStudioContextValue";
import { buildAgentContextPreview } from "./components/editor/domEditingAgentPrompt";
import type { DomEditSelection } from "./components/editor/domEditing";
import { AskAgentModal } from "./components/AskAgentModal";
import { StudioGlobalDragOverlay } from "./components/StudioGlobalDragOverlay";
import { StudioHeader } from "./components/StudioHeader";
import { useGestureCommit } from "./hooks/useGestureCommit";
import { STUDIO_KEYFRAMES_ENABLED } from "./components/editor/manualEditingAvailability";
import {
STUDIO_KEYFRAMES_ENABLED,
STUDIO_STORYBOARD_ENABLED,
} from "./components/editor/manualEditingAvailability";
import { GestureTrailOverlay } from "./components/editor/GestureTrailOverlay";
import { StudioLeftSidebar } from "./components/StudioLeftSidebar";
import { StudioPreviewArea } from "./components/StudioPreviewArea";
@@ -47,10 +47,11 @@ import { StudioRightPanel } from "./components/StudioRightPanel";
import { TimelineToolbar } from "./components/TimelineToolbar";
import { StudioPlaybackProvider, StudioShellProvider } from "./contexts/StudioContext";
import { PanelLayoutProvider } from "./contexts/PanelLayoutContext";
import { ViewModeProvider, useViewModeState } from "./contexts/ViewModeContext";
import { StoryboardView } from "./components/storyboard/StoryboardView";
import { FileManagerProvider } from "./contexts/FileManagerContext";
import { DomEditProvider } from "./contexts/DomEditContext";
import { StudioSplash } from "./components/StudioSplash";
import { StudioToast } from "./components/StudioToast";
import { useServerConnection } from "./hooks/useServerConnection";
import {
normalizeStudioCompositionPath,
@@ -64,6 +65,7 @@ type CanvasRect = { left: number; top: number; width: number; height: number };
export function StudioApp() {
const { projectId, resolving, waitingForServer } = useServerConnection();
const initialUrlStateRef = useRef(readStudioUrlStateFromWindow());
const viewModeValue = useViewModeState(STUDIO_STORYBOARD_ENABLED);
// sessionStorage-backed: fires once per tab, survives HMR remounts
useEffect(() => {
@@ -469,131 +471,121 @@ export function StudioApp() {
return (
<StudioShellProvider value={studioCtxValue}>
<StudioPlaybackProvider value={studioCtxValue}>
<PanelLayoutProvider value={panelLayout}>
<FileManagerProvider value={fileManager}>
<DomEditProvider value={domEditSession}>
<div
className="flex flex-col h-full w-full bg-neutral-950 relative"
onDragOver={dragOverlay.onDragOver}
onDragEnter={dragOverlay.onDragEnter}
onDragLeave={dragOverlay.onDragLeave}
onDrop={dragOverlay.onDrop}
>
<StudioHeader
captureFrameHref={frameCapture.captureFrameHref}
captureFrameFilename={frameCapture.captureFrameFilename}
handleCaptureFrameClick={frameCapture.handleCaptureFrameClick}
refreshCaptureFrameTime={frameCapture.refreshCaptureFrameTime}
inspectorButtonActive={inspectorButtonActive}
inspectorPanelActive={inspectorPanelActive}
onExport={() => void renderQueue.startRender(undefined)}
/>
{previewPersistence.domEditSaveQueuePaused && (
<SaveQueuePausedBanner
message={previewPersistence.domEditSaveQueuePaused}
onDismiss={previewPersistence.resetDomEditSaveQueueBreaker}
<ViewModeProvider value={viewModeValue}>
<PanelLayoutProvider value={panelLayout}>
<FileManagerProvider value={fileManager}>
<DomEditProvider value={domEditSession}>
<div
className="flex flex-col h-full w-full bg-neutral-950 relative"
onDragOver={dragOverlay.onDragOver}
onDragEnter={dragOverlay.onDragEnter}
onDragLeave={dragOverlay.onDragLeave}
onDrop={dragOverlay.onDrop}
>
<StudioHeader
captureFrameHref={frameCapture.captureFrameHref}
captureFrameFilename={frameCapture.captureFrameFilename}
handleCaptureFrameClick={frameCapture.handleCaptureFrameClick}
refreshCaptureFrameTime={frameCapture.refreshCaptureFrameTime}
inspectorButtonActive={inspectorButtonActive}
inspectorPanelActive={inspectorPanelActive}
onExport={() => void renderQueue.startRender(undefined)}
/>
)}
<div className="flex flex-1 min-h-0">
<StudioLeftSidebar
leftSidebarRef={leftSidebarRef}
onSelectComposition={handleSelectComposition}
onAddBlock={handleAddBlock}
onPreviewBlock={setBlockPreview}
onLint={handleLint}
linting={linting}
lintFindingCount={lintModal?.length ?? findingsByFile.size}
lintFindingsByFile={findingsByFile}
/>
<StudioPreviewArea
timelineToolbar={timelineToolbar}
renderClipContent={renderClipContent}
handleTimelineElementDelete={timelineEditing.handleTimelineElementDelete}
handleTimelineAssetDrop={timelineEditing.handleTimelineAssetDrop}
handleTimelineBlockDrop={handleTimelineBlockDrop}
handlePreviewBlockDrop={handlePreviewBlockDrop}
handleTimelineFileDrop={timelineEditing.handleTimelineFileDrop}
handleTimelineElementMove={timelineEditing.handleTimelineElementMove}
handleTimelineElementResize={timelineEditing.handleTimelineElementResize}
handleBlockedTimelineEdit={timelineEditing.handleBlockedTimelineEdit}
handleTimelineElementSplit={timelineEditing.handleTimelineElementSplit}
handleRazorSplit={timelineEditing.handleRazorSplit}
handleRazorSplitAll={timelineEditing.handleRazorSplitAll}
setCompIdToSrc={setCompIdToSrc}
setCompositionLoading={setCompositionLoading}
shouldShowSelectedDomBounds={shouldShowSelectedDomBounds}
isGestureRecording={gestureState === "recording"}
recordingState={gestureState}
onToggleRecording={STUDIO_KEYFRAMES_ENABLED ? handleToggleRecording : undefined}
blockPreview={blockPreview}
gestureOverlay={
gestureState === "recording" && previewIframe ? (
<GestureTrailOverlay
samples={gestureRecording.samplesRef.current}
sampleCount={gestureRecording.samplesRef.current.length}
trail={gestureRecording.trailRef.current}
canvasRect={canvasRectRef.current!}
compositionSize={compositionDimensions ?? undefined}
mode="recording"
/>
) : undefined
}
/>
{!panelLayout.rightCollapsed && (
<StudioRightPanel
designPanelActive={designPanelActive}
activeBlockParams={activeBlockParams}
onCloseBlockParams={() => {
setActiveBlockParams(null);
panelLayout.setRightPanelTab("design");
}}
{previewPersistence.domEditSaveQueuePaused && (
<SaveQueuePausedBanner
message={previewPersistence.domEditSaveQueuePaused}
onDismiss={previewPersistence.resetDomEditSaveQueueBreaker}
/>
)}
{viewModeValue.viewMode === "storyboard" && (
<StoryboardView projectId={projectId} />
)}
{/* 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" : ""
}`}
>
<StudioLeftSidebar
leftSidebarRef={leftSidebarRef}
onSelectComposition={handleSelectComposition}
onAddBlock={handleAddBlock}
onPreviewBlock={setBlockPreview}
onLint={handleLint}
linting={linting}
lintFindingCount={lintModal?.length ?? findingsByFile.size}
lintFindingsByFile={findingsByFile}
/>
<StudioPreviewArea
timelineToolbar={timelineToolbar}
renderClipContent={renderClipContent}
handleTimelineElementDelete={timelineEditing.handleTimelineElementDelete}
handleTimelineAssetDrop={timelineEditing.handleTimelineAssetDrop}
handleTimelineBlockDrop={handleTimelineBlockDrop}
handlePreviewBlockDrop={handlePreviewBlockDrop}
handleTimelineFileDrop={timelineEditing.handleTimelineFileDrop}
handleTimelineElementMove={timelineEditing.handleTimelineElementMove}
handleTimelineElementResize={timelineEditing.handleTimelineElementResize}
handleBlockedTimelineEdit={timelineEditing.handleBlockedTimelineEdit}
handleTimelineElementSplit={timelineEditing.handleTimelineElementSplit}
handleRazorSplit={timelineEditing.handleRazorSplit}
handleRazorSplitAll={timelineEditing.handleRazorSplitAll}
setCompIdToSrc={setCompIdToSrc}
setCompositionLoading={setCompositionLoading}
shouldShowSelectedDomBounds={shouldShowSelectedDomBounds}
isGestureRecording={gestureState === "recording"}
recordingState={gestureState}
recordingDuration={gestureRecording.recordingDuration}
onToggleRecording={
STUDIO_KEYFRAMES_ENABLED ? handleToggleRecording : undefined
}
blockPreview={blockPreview}
gestureOverlay={
gestureState === "recording" && previewIframe ? (
<GestureTrailOverlay
samples={gestureRecording.samplesRef.current}
sampleCount={gestureRecording.samplesRef.current.length}
trail={gestureRecording.trailRef.current}
canvasRect={canvasRectRef.current!}
compositionSize={compositionDimensions ?? undefined}
mode="recording"
/>
) : undefined
}
/>
)}
</div>
{lintModal !== null && (
<LintModal findings={lintModal} projectId={projectId} onClose={closeLintModal} />
)}
{consoleErrors !== null && consoleErrors.length > 0 && (
<LintModal
findings={consoleErrors}
projectId={projectId}
onClose={() => setConsoleErrors(null)}
/>
)}
{domEditSession.agentModalOpen && domEditSession.domEditSelection && (
<AskAgentModal
selectionLabel={domEditSession.domEditSelection.label}
contextPreview={buildAgentContextPreview(
domEditSession.domEditSelection,
activeCompPath,
{!panelLayout.rightCollapsed && (
<StudioRightPanel
designPanelActive={designPanelActive}
activeBlockParams={activeBlockParams}
onCloseBlockParams={() => {
setActiveBlockParams(null);
panelLayout.setRightPanelTab("design");
}}
recordingState={gestureState}
recordingDuration={gestureRecording.recordingDuration}
onToggleRecording={
STUDIO_KEYFRAMES_ENABLED ? handleToggleRecording : undefined
}
/>
)}
anchorPoint={domEditSession.agentModalAnchorPoint}
onSubmit={domEditSession.handleAgentModalSubmit}
onClose={() => {
domEditSession.setAgentModalOpen(false);
domEditSession.setAgentPromptSelectionContext(undefined);
domEditSession.setAgentModalAnchorPoint(null);
}}
</div>
<StudioOverlays
projectId={projectId}
lintModal={lintModal}
closeLintModal={closeLintModal}
consoleErrors={consoleErrors}
clearConsoleErrors={() => setConsoleErrors(null)}
domEditSession={domEditSession}
activeCompPath={activeCompPath}
dragOverlayActive={dragOverlay.active}
appToast={appToast}
dismissToast={dismissToast}
/>
)}
{dragOverlay.active && <StudioGlobalDragOverlay />}
{appToast && (
<StudioToast
message={appToast.message}
tone={appToast.tone}
onDismiss={dismissToast}
/>
)}
</div>
</DomEditProvider>
</FileManagerProvider>
</PanelLayoutProvider>
</div>
</DomEditProvider>
</FileManagerProvider>
</PanelLayoutProvider>
</ViewModeProvider>
</StudioPlaybackProvider>
</StudioShellProvider>
);
@@ -3,11 +3,13 @@ import { RotateCcw, RotateCw, Camera } from "../icons/SystemIcons";
import {
STUDIO_INSPECTOR_PANELS_ENABLED,
STUDIO_MANUAL_EDITING_DISABLED_TITLE,
STUDIO_STORYBOARD_ENABLED,
} from "./editor/manualEditingAvailability";
import { getHistoryShortcutLabel } from "../utils/studioHelpers";
import { useStudioShellContext } from "../contexts/StudioContext";
import { usePanelLayoutContext } from "../contexts/PanelLayoutContext";
import { useDomEditActionsContext } from "../contexts/DomEditContext";
import { useViewMode, type StudioViewMode } from "../contexts/ViewModeContext";
import { trackStudioEvent } from "../utils/studioTelemetry";
export interface StudioHeaderProps {
@@ -141,6 +143,46 @@ function HyperframesLogo() {
);
}
const VIEW_MODE_OPTIONS: Array<{ mode: StudioViewMode; label: string }> = [
{ mode: "storyboard", label: "Storyboard" },
{ mode: "timeline", label: "Preview" },
];
/** Segmented control switching the main stage between storyboard and preview. */
function ViewModeToggle() {
const { viewMode, setViewMode } = useViewMode();
return (
<div
className="flex items-center gap-0.5 rounded-md bg-neutral-800 p-0.5"
role="tablist"
aria-label="Studio view"
>
{VIEW_MODE_OPTIONS.map(({ mode, label }) => {
const active = viewMode === mode;
return (
<button
key={mode}
type="button"
role="tab"
aria-selected={active}
onClick={() => {
if (active) return;
trackStudioEvent("view_mode_toggle", { mode });
setViewMode(mode);
}}
className={`rounded px-3 py-1 text-[11px] font-medium transition-colors ${
active ? "bg-neutral-200 text-neutral-900" : "text-neutral-400 hover:text-neutral-200"
}`}
>
{label}
</button>
);
})}
</div>
);
}
// fallow-ignore-next-line complexity
export function StudioHeader({
captureFrameHref,
captureFrameFilename,
@@ -164,6 +206,8 @@ export function StudioHeader({
</span>
<span className="text-[11px] font-medium text-neutral-300">{projectId}</span>
</div>
{/* Center: storyboard / preview toggle (flag-gated) */}
{STUDIO_STORYBOARD_ENABLED && <ViewModeToggle />}
{/* Right: toolbar buttons */}
<div className="flex items-center gap-1.5">
<button
@@ -0,0 +1,70 @@
import type { ComponentProps } from "react";
import { LintModal } from "./LintModal";
import { AskAgentModal } from "./AskAgentModal";
import { StudioGlobalDragOverlay } from "./StudioGlobalDragOverlay";
import { StudioToast } from "./StudioToast";
import { buildAgentContextPreview } from "./editor/domEditingAgentPrompt";
import type { useDomEditSession } from "../hooks/useDomEditSession";
import type { useToast } from "../hooks/useToast";
type LintFindings = ComponentProps<typeof LintModal>["findings"];
export interface StudioOverlaysProps {
projectId: string;
lintModal: LintFindings | null;
closeLintModal: () => void;
consoleErrors: LintFindings | null;
clearConsoleErrors: () => void;
domEditSession: ReturnType<typeof useDomEditSession>;
activeCompPath: string | null;
dragOverlayActive: boolean;
appToast: ReturnType<typeof useToast>["appToast"];
dismissToast: () => void;
}
/**
* Floating overlays for the studio shell: lint / console-error modals, the
* ask-agent modal, the global drag overlay, and the toast. Extracted from
* `App.tsx` to keep the shell within the studio's 600-line decomposition budget.
*/
// fallow-ignore-next-line complexity
export function StudioOverlays({
projectId,
lintModal,
closeLintModal,
consoleErrors,
clearConsoleErrors,
domEditSession,
activeCompPath,
dragOverlayActive,
appToast,
dismissToast,
}: StudioOverlaysProps) {
return (
<>
{lintModal !== null && (
<LintModal findings={lintModal} projectId={projectId} onClose={closeLintModal} />
)}
{consoleErrors !== null && consoleErrors.length > 0 && (
<LintModal findings={consoleErrors} projectId={projectId} onClose={clearConsoleErrors} />
)}
{domEditSession.agentModalOpen && domEditSession.domEditSelection && (
<AskAgentModal
selectionLabel={domEditSession.domEditSelection.label}
contextPreview={buildAgentContextPreview(domEditSession.domEditSelection, activeCompPath)}
anchorPoint={domEditSession.agentModalAnchorPoint}
onSubmit={domEditSession.handleAgentModalSubmit}
onClose={() => {
domEditSession.setAgentModalOpen(false);
domEditSession.setAgentPromptSelectionContext(undefined);
domEditSession.setAgentModalAnchorPoint(null);
}}
/>
)}
{dragOverlayActive && <StudioGlobalDragOverlay />}
{appToast && (
<StudioToast message={appToast.message} tone={appToast.tone} onDismiss={dismissToast} />
)}
</>
);
}
@@ -82,6 +82,16 @@ export const STUDIO_RAZOR_TOOL_ENABLED = resolveStudioBooleanEnvFlag(
true,
);
// Storyboard view: a top-level, toggleable view that renders STORYBOARD.md as a
// contact sheet of live HTML frame tiles, replacing the timeline/preview stage.
// Opt-in / off by default until the experience is ready for broad exposure.
// VITE_STUDIO_ENABLE_STORYBOARD=1 npx hyperframes preview
export const STUDIO_STORYBOARD_ENABLED = resolveStudioBooleanEnvFlag(
env,
["VITE_STUDIO_ENABLE_STORYBOARD", "VITE_STUDIO_STORYBOARD_ENABLED"],
false,
);
// When disabled (the default), drag/resize/rotate commits always take the CSS
// persist path instead of being intercepted into GSAP script keyframe
// mutations. The keyframe intercept rewrites timeline tweens from drag
@@ -0,0 +1,44 @@
import type { StoryboardGlobals } from "@hyperframes/core/storyboard";
export interface StoryboardDirectionProps {
globals: StoryboardGlobals;
frameCount: number;
}
/**
* Global direction header: the message/thesis plus arc, audience, and format.
* This is the storyboard's "north star" pulled from the manifest frontmatter.
*/
export function StoryboardDirection({ globals, frameCount }: StoryboardDirectionProps) {
const meta = [
{ label: "Arc", value: globals.arc },
{ label: "Audience", value: globals.audience },
{ label: "Format", value: globals.format },
{ label: "Frames", value: String(frameCount) },
].filter((item): item is { label: string; value: string } => Boolean(item.value));
return (
<header className="border-b border-neutral-800 pb-5">
<div className="text-[11px] font-medium uppercase tracking-wider text-neutral-500">
Storyboard
</div>
{globals.message ? (
<h1 className="mt-1 text-2xl font-semibold leading-tight text-neutral-100">
{globals.message}
</h1>
) : (
<h1 className="mt-1 text-2xl font-semibold leading-tight text-neutral-400">
Untitled storyboard
</h1>
)}
<dl className="mt-4 flex flex-wrap gap-x-8 gap-y-2">
{meta.map((item) => (
<div key={item.label} className="flex items-baseline gap-2">
<dt className="text-[11px] uppercase tracking-wider text-neutral-500">{item.label}</dt>
<dd className="text-sm text-neutral-300">{item.value}</dd>
</div>
))}
</dl>
</header>
);
}
@@ -0,0 +1,78 @@
import type { ReactNode } from "react";
import { useStoryboard } from "../../hooks/useStoryboard";
import { StoryboardDirection } from "./StoryboardDirection";
export interface StoryboardViewProps {
projectId: string;
}
/**
* Top-level storyboard stage. Replaces the timeline/preview when the view mode
* is `storyboard`. PR2 lands the shell (global direction + states); the frame
* contact-sheet grid arrives in PR3.
*/
// fallow-ignore-next-line complexity
export function StoryboardView({ projectId }: StoryboardViewProps) {
const { data, loading, error } = useStoryboard(projectId);
if (loading) return <StoryboardFrame>{<Message>Loading storyboard…</Message>}</StoryboardFrame>;
if (error) {
return (
<StoryboardFrame>
<Message tone="error">Couldn’t load the storyboard: {error}</Message>
</StoryboardFrame>
);
}
if (!data) return <StoryboardFrame>{null}</StoryboardFrame>;
if (!data.exists) {
return (
<StoryboardFrame>
<EmptyState path={data.path} />
</StoryboardFrame>
);
}
return (
<StoryboardFrame>
<StoryboardDirection globals={data.globals} frameCount={data.frames.length} />
{/* PR3: frame contact-sheet grid renders here. */}
<div className="mt-8 rounded-lg border border-dashed border-neutral-800 px-6 py-12 text-center text-sm text-neutral-500">
{data.frames.length} frame{data.frames.length === 1 ? "" : "s"} parsed — the contact sheet
renders here next.
</div>
</StoryboardFrame>
);
}
function StoryboardFrame({ children }: { children: ReactNode }) {
return (
<div className="flex-1 min-h-0 overflow-auto bg-neutral-950 text-neutral-200">
<div className="mx-auto max-w-[1400px] px-8 py-8">{children}</div>
</div>
);
}
function Message({ children, tone = "muted" }: { children: ReactNode; tone?: "muted" | "error" }) {
return (
<div
className={`px-6 py-12 text-center text-sm ${
tone === "error" ? "text-red-400" : "text-neutral-500"
}`}
>
{children}
</div>
);
}
function EmptyState({ path }: { path: string }) {
return (
<div className="rounded-lg border border-dashed border-neutral-800 px-6 py-16 text-center">
<h2 className="text-base font-semibold text-neutral-300">No storyboard yet</h2>
<p className="mx-auto mt-2 max-w-md text-sm text-neutral-500">
Add a <code className="rounded bg-neutral-900 px-1 py-0.5 text-neutral-400">{path}</code> at
the project root to plan this video frame by frame. Your agent can create and iterate on it
for you.
</p>
</div>
);
}
@@ -0,0 +1,93 @@
import {
createContext,
useCallback,
useContext,
useEffect,
useMemo,
useState,
type ReactNode,
} from "react";
/**
* Top-level Studio view mode.
*
* `timeline` is the existing NLE/preview stage. `storyboard` replaces that stage
* with the storyboard contact sheet. The mode is mirrored to the `?view=` query
* param so it survives reloads and — importantly — so an agent can deep-link the
* user straight into the storyboard by navigating the tab to `?view=storyboard`.
*/
export type StudioViewMode = "timeline" | "storyboard";
const VIEW_QUERY_PARAM = "view";
function readViewModeFromUrl(): StudioViewMode {
if (typeof window === "undefined") return "timeline";
return new URLSearchParams(window.location.search).get(VIEW_QUERY_PARAM) === "storyboard"
? "storyboard"
: "timeline";
}
function writeViewModeToUrl(mode: StudioViewMode): void {
if (typeof window === "undefined") return;
const url = new URL(window.location.href);
if (mode === "storyboard") {
url.searchParams.set(VIEW_QUERY_PARAM, "storyboard");
} else {
url.searchParams.delete(VIEW_QUERY_PARAM);
}
window.history.replaceState(window.history.state, "", url);
}
export interface ViewModeValue {
viewMode: StudioViewMode;
setViewMode: (mode: StudioViewMode) => void;
}
/**
* Owns the view-mode state. When `enabled` is false (storyboard flag off) the
* mode is pinned to `timeline` and the URL is left untouched, so the feature is
* fully inert until the flag is on.
*/
export function useViewModeState(enabled: boolean): ViewModeValue {
const [viewMode, setMode] = useState<StudioViewMode>(() =>
enabled ? readViewModeFromUrl() : "timeline",
);
// Reflect back/forward navigation and agent-driven URL changes.
useEffect(() => {
if (!enabled) return;
const onPopState = () => setMode(readViewModeFromUrl());
window.addEventListener("popstate", onPopState);
return () => window.removeEventListener("popstate", onPopState);
}, [enabled]);
const setViewMode = useCallback(
(mode: StudioViewMode) => {
if (!enabled) return;
setMode(mode);
writeViewModeToUrl(mode);
},
[enabled],
);
const effectiveMode = enabled ? viewMode : "timeline";
return useMemo(() => ({ viewMode: effectiveMode, setViewMode }), [effectiveMode, setViewMode]);
}
const ViewModeContext = createContext<ViewModeValue | null>(null);
export function useViewMode(): ViewModeValue {
const ctx = useContext(ViewModeContext);
if (!ctx) throw new Error("useViewMode must be used within ViewModeProvider");
return ctx;
}
export function ViewModeProvider({
value,
children,
}: {
value: ViewModeValue;
children: ReactNode;
}) {
return <ViewModeContext value={value}>{children}</ViewModeContext>;
}
@@ -0,0 +1,72 @@
import { useCallback, useEffect, useState } from "react";
import type {
StoryboardFrame,
StoryboardGlobals,
StoryboardWarning,
} from "@hyperframes/core/storyboard";
import { buildProjectApiPath } from "../utils/projectRouting";
/** A frame as returned by the API: parsed frame + disk-resolution info. */
export interface StoryboardFrameView extends StoryboardFrame {
/** Whether `src` resolves to an existing file inside the project. */
srcExists: boolean;
}
/** Shape of `GET /api/projects/:id/storyboard`. */
export interface StoryboardResponse {
exists: boolean;
path: string;
globals: StoryboardGlobals;
frames: StoryboardFrameView[];
warnings: StoryboardWarning[];
}
export interface UseStoryboardResult {
data: StoryboardResponse | null;
loading: boolean;
error: string | null;
reload: () => void;
}
/**
* Load the parsed storyboard manifest for a project. Markdown stays canonical on
* disk; this fetches the server-derived JSON the storyboard view renders.
*/
export function useStoryboard(projectId: string | null): UseStoryboardResult {
const [data, setData] = useState<StoryboardResponse | null>(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
const [reloadKey, setReloadKey] = useState(0);
const reload = useCallback(() => setReloadKey((k) => k + 1), []);
useEffect(() => {
if (!projectId) return;
let cancelled = false;
setLoading(true);
setError(null);
// Route through buildProjectApiPath so the (URL-derived) projectId is encoded
// into the path rather than interpolated raw (CodeQL js/client-side-request-forgery).
fetch(buildProjectApiPath(projectId, "/storyboard"))
.then((res) => {
if (!res.ok) throw new Error(`storyboard request failed: ${res.status}`);
return res.json() as Promise<StoryboardResponse>;
})
.then((json) => {
if (!cancelled) setData(json);
})
.catch((err: unknown) => {
if (!cancelled) setError(err instanceof Error ? err.message : "failed to load storyboard");
})
.finally(() => {
if (!cancelled) setLoading(false);
});
return () => {
cancelled = true;
};
}, [projectId, reloadKey]);
return { data, loading, error, reload };
}