@hyperframes/studio 0.6.110 → 0.6.111

package/src/components/StudioHeader.tsx

@@ -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

package/src/components/StudioOverlays.tsx

@@ -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} />
+      )}
+    </>
+  );
+}

package/src/components/editor/SourceEditor.tsx

@@ -12,26 +12,26 @@ import { bracketMatching, foldGutter, indentOnInput } from "@codemirror/language
 import { closeBrackets, closeBracketsKeymap } from "@codemirror/autocomplete";
 import { highlightSelectionMatches, searchKeymap } from "@codemirror/search";
 import { oneDark } from "@codemirror/theme-one-dark";
+import type { Extension } from "@codemirror/state";
 import { html } from "@codemirror/lang-html";
 import { css } from "@codemirror/lang-css";
 import { javascript } from "@codemirror/lang-javascript";
+import { markdown } from "@codemirror/lang-markdown";
 
-function getLanguageExtension(language: string) {
-  switch (language) {
-    case "html":
-      return html();
-    case "css":
-      return css();
-    case "javascript":
-    case "js":
-    case "typescript":
-    case "ts":
-      return javascript({
-        typescript: language === "typescript" || language === "ts",
-      });
-    default:
-      return html();
-  }
+const LANGUAGE_EXTENSIONS: Record<string, () => Extension> = {
+  html: () => html(),
+  css: () => css(),
+  markdown: () => markdown(),
+  md: () => markdown(),
+  javascript: () => javascript(),
+  js: () => javascript(),
+  typescript: () => javascript({ typescript: true }),
+  ts: () => javascript({ typescript: true }),
+};
+
+function getLanguageExtension(language: string): Extension {
+  const factory = LANGUAGE_EXTENSIONS[language] ?? html;
+  return factory();
 }
 
 function detectLanguage(filePath: string): string {
@@ -45,6 +45,8 @@ function detectLanguage(filePath: string): string {
     jsx: "javascript",
     tsx: "typescript",
     json: "javascript",
+    md: "markdown",
+    markdown: "markdown",
   };
   return map[ext] ?? "html";
 }
@@ -74,6 +76,7 @@ export const SourceEditor = memo(function SourceEditor({
   const contentRef = useRef(content);
   contentRef.current = content;
 
+  // fallow-ignore-next-line complexity
   const mountEditor = useCallback(
     (node: HTMLDivElement | null) => {
       if (editorRef.current) {

package/src/components/editor/manualEditingAvailability.ts

@@ -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
@@ -94,14 +104,22 @@ export const STUDIO_GSAP_DRAG_INTERCEPT_ENABLED = resolveStudioBooleanEnvFlag(
 
 export const STUDIO_PREVIEW_SELECTION_ENABLED = STUDIO_INSPECTOR_PANELS_ENABLED;
 
-// Stage 7 Step 3b: shadow dispatch parity mode — dispatches ops to the SDK
-// session alongside the server patch path and logs mismatches via telemetry.
-// Default on: server stays authoritative (no user-visible change), so we want
-// the sdk_shadow_dispatch parity signal from all traffic. Disable via
-// VITE_STUDIO_SDK_SHADOW_ENABLED=false.
-export const STUDIO_SDK_SHADOW_ENABLED = resolveStudioBooleanEnvFlag(
+// Stage 7 Step 3c: SDK cutover — routes inline-style ops through SDK dispatch
+// instead of the server patch-element API. Default false; enable via
+// VITE_STUDIO_SDK_CUTOVER_ENABLED=true. Requires SDK session to be open.
+export const STUDIO_SDK_CUTOVER_ENABLED = resolveStudioBooleanEnvFlag(
+  env,
+  ["VITE_STUDIO_SDK_CUTOVER_ENABLED"],
+  false,
+);
+
+// Resolver-parity tripwire (telemetry-only, decoupled from cutover).
+// Runs the SDK resolver alongside any edit and emits sdk_resolver_shadow on
+// divergence. Default true; disable via VITE_STUDIO_SDK_RESOLVER_SHADOW_ENABLED=false.
+// Soak gate: retire once zero element_not_found divergences over a clean window.
+export const STUDIO_SDK_RESOLVER_SHADOW_ENABLED = resolveStudioBooleanEnvFlag(
   env,
-  ["VITE_STUDIO_SDK_SHADOW_ENABLED"],
+  ["VITE_STUDIO_SDK_RESOLVER_SHADOW_ENABLED"],
   true,
 );
 

package/src/components/storyboard/FramePoster.tsx

@@ -0,0 +1,56 @@
+import { useEffect, useState } from "react";
+import { buildCompositionThumbnailUrl } from "../../player/components/CompositionThumbnail";
+
+export interface FramePosterProps {
+  projectId: string;
+  /** Project-relative path to the frame's HTML sub-composition. */
+  src: string;
+  /** Time (seconds) to seek to for the poster. */
+  seconds: number;
+  title: string;
+  /** `cover` fills+crops (contact-sheet tile); `contain` letterboxes (focus hero). */
+  fit?: "cover" | "contain";
+}
+
+/**
+ * Server-rendered poster for a frame. The thumbnail route seeks the composition
+ * by time (at its real fps) and caches the result, so there's no live iframe,
+ * no postMessage seek, and no client-side fps assumption. Shared by the
+ * contact-sheet tile and the frame-focus view.
+ */
+export function FramePoster({ projectId, src, seconds, title, fit = "cover" }: FramePosterProps) {
+  const [failed, setFailed] = useState(false);
+  // The <img> is reused (no key) when a tile/hero swaps to a different frame, so a
+  // prior load error would stick. Reset when the poster target changes.
+  useEffect(() => setFailed(false), [src, seconds]);
+  if (failed) {
+    return (
+      <div className="flex h-full w-full items-center justify-center text-[11px] text-neutral-600">
+        Preview unavailable
+      </div>
+    );
+  }
+  const url = buildCompositionThumbnailUrl({
+    previewUrl: `/api/projects/${projectId}/preview/comp/${src}`,
+    seekTime: seconds,
+    duration: 0,
+    origin: window.location.origin,
+  });
+  return (
+    <img
+      src={url}
+      alt={title}
+      draggable={false}
+      loading="lazy"
+      onError={() => setFailed(true)}
+      className={`h-full w-full ${fit === "contain" ? "object-contain" : "object-cover"}`}
+    />
+  );
+}
+
+/** Time (seconds) to show a frame at — past the intro so the key moment is visible. */
+export function posterTime(frame: { poster?: number; durationSeconds?: number }): number {
+  if (frame.poster != null) return frame.poster;
+  if (frame.durationSeconds != null) return frame.durationSeconds * 0.66;
+  return 1.5;
+}

package/src/components/storyboard/StoryboardDirection.tsx

@@ -0,0 +1,45 @@
+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: "Voice", value: globals.extra.voice },
+    { 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>
+  );
+}

package/src/components/storyboard/StoryboardFrameFocus.tsx

@@ -0,0 +1,262 @@
+import { useCallback, useEffect, useState } from "react";
+import { setFrameStatus, setFrameVoiceover, type FrameStatus } from "@hyperframes/core/storyboard";
+import type { StoryboardFrameView } from "../../hooks/useStoryboard";
+import { useFileManagerContext } from "../../contexts/FileManagerContext";
+import { useViewMode } from "../../contexts/ViewModeContext";
+import { FramePoster, posterTime } from "./FramePoster";
+import { FRAME_STATUS_META, FRAME_STATUS_ORDER } from "./frameStatus";
+
+export interface StoryboardFrameFocusProps {
+  projectId: string;
+  /** Path to STORYBOARD.md (edits are written here). */
+  storyboardPath: string;
+  frame: StoryboardFrameView;
+  frameCount: number;
+  onBack: () => void;
+  onNavigate: (delta: number) => void;
+  /** Re-parse the manifest after an edit is saved. */
+  onSaved: () => void;
+  /** Select a composition in the timeline (sets active comp + editing file + sidebar highlight). */
+  onSelectComposition: (path: string) => void;
+}
+
+/**
+ * Full-area focus on a single frame: large poster, editable voiceover guide,
+ * status advancement, full narrative, and a jump into the live preview. Edits
+ * are written back to STORYBOARD.md in place (markdown stays canonical).
+ *
+ * Mounted with a `key` per frame, so `draft` initializes from the frame and a
+ * save-triggered reload never clobbers in-progress typing.
+ */
+// fallow-ignore-next-line complexity
+export function StoryboardFrameFocus({
+  projectId,
+  storyboardPath,
+  frame,
+  frameCount,
+  onBack,
+  onNavigate,
+  onSaved,
+  onSelectComposition,
+}: StoryboardFrameFocusProps) {
+  const { readProjectFile, writeProjectFile } = useFileManagerContext();
+  const { setViewMode } = useViewMode();
+  const [draft, setDraft] = useState(frame.voiceover ?? "");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const applyEdit = useCallback(
+    async (edit: (source: string) => string) => {
+      if (busy) return; // one read-modify-write at a time; avoids a lost update
+      setBusy(true);
+      setError(null);
+      try {
+        const source = await readProjectFile(storyboardPath);
+        await writeProjectFile(storyboardPath, edit(source));
+        onSaved();
+      } catch (err: unknown) {
+        setError(err instanceof Error ? err.message : "failed to save");
+      } finally {
+        setBusy(false);
+      }
+    },
+    [readProjectFile, writeProjectFile, storyboardPath, onSaved, busy],
+  );
+
+  const title = frame.title ?? `Frame ${frame.index}`;
+  const dirty = draft !== (frame.voiceover ?? "");
+  const canOpenPreview = frame.srcExists && Boolean(frame.src);
+
+  // Leaving the frame drops the in-memory voiceover draft; confirm when it's dirty.
+  const confirmLeave = () => !dirty || window.confirm("Discard unsaved voiceover changes?");
+  const handleBack = () => {
+    if (confirmLeave()) onBack();
+  };
+  const handleNavigate = (delta: number) => {
+    if (confirmLeave()) onNavigate(delta);
+  };
+
+  // ←/→ navigate frames, Esc returns to the Board — but never while typing in a field.
+  useEffect(() => {
+    // fallow-ignore-next-line complexity
+    const onKey = (e: KeyboardEvent) => {
+      const el = document.activeElement;
+      if (el instanceof HTMLTextAreaElement || el instanceof HTMLInputElement) return;
+      if (e.key === "Escape") handleBack();
+      else if (e.key === "ArrowLeft" && frame.index > 1) handleNavigate(-1);
+      else if (e.key === "ArrowRight" && frame.index < frameCount) handleNavigate(1);
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  });
+
+  const openInPreview = () => {
+    if (frame.src) onSelectComposition(frame.src);
+    setViewMode("timeline");
+  };
+
+  return (
+    <div className="flex flex-1 min-h-0 flex-col bg-neutral-950 text-neutral-200">
+      <div className="flex items-center gap-3 border-b border-neutral-800 px-4 py-2">
+        <button
+          type="button"
+          onClick={handleBack}
+          className="rounded px-2 py-1 text-xs font-medium text-neutral-300 hover:bg-neutral-800"
+        >
+          ← Board
+        </button>
+        <span className="text-sm font-medium text-neutral-200">
+          Frame {frame.number ?? frame.index} — {title}
+        </span>
+        <div className="ml-auto flex items-center gap-1">
+          <NavButton
+            label="‹ Prev"
+            disabled={frame.index <= 1}
+            onClick={() => handleNavigate(-1)}
+          />
+          <NavButton
+            label="Next ›"
+            disabled={frame.index >= frameCount}
+            onClick={() => handleNavigate(1)}
+          />
+        </div>
+      </div>
+
+      <div className="flex flex-1 min-h-0">
+        <div className="flex w-3/5 min-w-0 items-center justify-center bg-neutral-900/40 p-8">
+          <div className="aspect-video w-full max-w-[900px] overflow-hidden rounded-lg border border-neutral-800 bg-neutral-900">
+            {canOpenPreview && frame.src ? (
+              <FramePoster
+                projectId={projectId}
+                src={frame.src}
+                seconds={posterTime(frame)}
+                title={title}
+                fit="contain"
+              />
+            ) : (
+              <div className="flex h-full w-full items-center justify-center text-sm text-neutral-600">
+                {frame.status === "outline" ? "Not built yet" : "No preview"}
+              </div>
+            )}
+          </div>
+        </div>
+
+        <div className="w-2/5 min-w-0 space-y-6 overflow-auto border-l border-neutral-800 px-6 py-5">
+          <StatusRow
+            status={frame.status}
+            busy={busy}
+            onSet={(s) => applyEdit((src) => setFrameStatus(src, frame.index, s))}
+          />
+
+          <div className="flex flex-wrap gap-x-6 gap-y-1 text-[11px] text-neutral-500">
+            {frame.duration && <span>Duration {frame.duration}</span>}
+            {frame.transitionIn && <span>Transition {frame.transitionIn}</span>}
+          </div>
+
+          <section>
+            <div className="mb-1 flex items-center justify-between">
+              <h3 className="text-xs font-semibold uppercase tracking-wider text-neutral-400">
+                🎙 Voiceover <span className="font-normal normal-case text-neutral-600">guide</span>
+              </h3>
+              <button
+                type="button"
+                onClick={() => applyEdit((src) => setFrameVoiceover(src, frame.index, draft))}
+                disabled={!dirty || busy}
+                className="rounded bg-emerald-600 px-2.5 py-1 text-xs font-medium text-white disabled:opacity-40"
+              >
+                Save
+              </button>
+            </div>
+            <textarea
+              value={draft}
+              onChange={(e) => setDraft(e.target.value)}
+              rows={3}
+              placeholder="What the narrator says over this frame…"
+              className="w-full resize-y rounded border border-neutral-800 bg-neutral-900 p-2 text-sm text-neutral-200 outline-none focus:border-neutral-600"
+            />
+            <p className="mt-1 text-[11px] text-neutral-600">
+              A draft guide. SCRIPT.md locks the final narration that drives TTS.
+            </p>
+            {error && <p className="mt-1 text-[11px] text-red-400">{error}</p>}
+          </section>
+
+          {frame.narrative && (
+            <section>
+              <h3 className="mb-1 text-xs font-semibold uppercase tracking-wider text-neutral-400">
+                Narrative
+              </h3>
+              <p className="whitespace-pre-wrap text-sm text-neutral-300">{frame.narrative}</p>
+            </section>
+          )}
+
+          <button
+            type="button"
+            onClick={openInPreview}
+            disabled={!canOpenPreview}
+            className="rounded border border-neutral-700 px-3 py-1.5 text-xs font-medium text-neutral-200 hover:bg-neutral-800 disabled:opacity-40"
+          >
+            Open in Preview →
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function NavButton({
+  label,
+  disabled,
+  onClick,
+}: {
+  label: string;
+  disabled: boolean;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      className="rounded px-2 py-1 text-xs font-medium text-neutral-300 hover:bg-neutral-800 disabled:opacity-30"
+    >
+      {label}
+    </button>
+  );
+}
+
+function StatusRow({
+  status,
+  busy,
+  onSet,
+}: {
+  status: FrameStatus;
+  busy: boolean;
+  onSet: (next: FrameStatus) => void;
+}) {
+  return (
+    <div className="flex items-center gap-2">
+      <span className="text-xs font-semibold uppercase tracking-wider text-neutral-500">
+        Status
+      </span>
+      <div className="flex items-center gap-0.5 rounded-md bg-neutral-900 p-0.5">
+        {FRAME_STATUS_ORDER.map((option) => (
+          <button
+            key={option}
+            type="button"
+            disabled={busy}
+            aria-pressed={status === option}
+            title={FRAME_STATUS_META[option].tooltip}
+            onClick={() => onSet(option)}
+            className={`rounded px-2.5 py-1 text-xs font-medium transition-colors disabled:opacity-50 ${
+              status === option
+                ? "bg-neutral-700 text-neutral-100"
+                : "text-neutral-400 hover:text-neutral-200"
+            }`}
+          >
+            {FRAME_STATUS_META[option].label}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}