@hyperframes/studio 0.6.109 → 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/gsapAnimationConstants.ts

@@ -20,6 +20,12 @@ export const PROP_LABELS: Record<string, string> = {
   width: "Width",
   height: "Height",
   rotation: "Rotate",
+  z: "Move Z",
+  rotationX: "Rotate X",
+  rotationY: "Rotate Y",
+  rotationZ: "Rotate Z",
+  perspective: "Perspective",
+  transformOrigin: "Transform Origin",
   opacity: "Opacity",
   scale: "Scale",
   scaleX: "Scale X",
@@ -46,6 +52,12 @@ export const PROP_UNITS: Record<string, string> = {
   width: "px",
   height: "px",
   rotation: "°",
+  z: "px",
+  rotationX: "°",
+  rotationY: "°",
+  rotationZ: "°",
+  perspective: "px",
+  transformOrigin: "",
   opacity: "%",
   scale: "×",
   scaleX: "×",
@@ -62,6 +74,13 @@ export const PROP_TOOLTIPS: Record<string, string> = {
   scaleX: "Horizontal stretch (1 = normal)",
   scaleY: "Vertical stretch (1 = normal)",
   rotation: "Spin angle (360 = full rotation)",
+  z: "Move forward/back along the Z axis",
+  rotationX: "Rotate around the horizontal X axis",
+  rotationY: "Rotate around the vertical Y axis",
+  rotationZ: "Rotate around the screen-facing Z axis",
+  perspective:
+    "3D depth context for child elements; set it on a parent when rotating children in 3D",
+  transformOrigin: "Pivot point for transforms, for example center center or 50% 50%",
   width: "Element width",
   height: "Element height",
   autoAlpha: "Like opacity but hides element completely at 0",
@@ -147,6 +166,11 @@ export const PROP_CONSTRAINTS: Record<string, { min?: number; max?: number; step
   scaleX: { min: -10, max: 10, step: 0.01 },
   scaleY: { min: -10, max: 10, step: 0.01 },
   rotation: { step: 1 },
+  z: { step: 1 },
+  rotationX: { step: 1 },
+  rotationY: { step: 1 },
+  rotationZ: { step: 1 },
+  perspective: { min: 0, step: 1 },
   skewX: { min: -90, max: 90, step: 1 },
   skewY: { min: -90, max: 90, step: 1 },
   width: { min: 0, step: 1 },

package/src/components/editor/gsapAnimationHelpers.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, it } from "vitest";
+import { SUPPORTED_PROPS } from "@hyperframes/core/gsap-constants";
 import { buildTweenSummary } from "./gsapAnimationHelpers";
+import { PROP_LABELS } from "./gsapAnimationConstants";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 
 function anim(overrides: Partial<GsapAnimation>): GsapAnimation {
@@ -23,6 +25,27 @@ describe("buildTweenSummary", () => {
     expect(s).toContain("move x");
   });
 
+  it("describes 3D transform tweens with labels and units", () => {
+    const s = buildTweenSummary(
+      anim({
+        properties: {
+          z: 120,
+          rotationX: 45,
+          rotationY: -30,
+          rotationZ: 90,
+          perspective: 800,
+          transformOrigin: "50% 50%",
+        },
+      }),
+    );
+    expect(s).toContain("move z to 120px");
+    expect(s).toContain("rotate x to 45°");
+    expect(s).toContain("rotate y to -30°");
+    expect(s).toContain("rotate z to 90°");
+    expect(s).toContain("perspective to 800px");
+    expect(s).toContain("transform origin to 50% 50%");
+  });
+
   it("describes a from tween", () => {
     const s = buildTweenSummary(anim({ method: "from", properties: { opacity: 0 } }));
     expect(s).toContain("enters from");
@@ -65,3 +88,9 @@ describe("buildTweenSummary", () => {
     expect(s).toContain("no properties yet");
   });
 });
+
+describe("PROP_LABELS", () => {
+  it("provides labels for every inspector-supported GSAP property", () => {
+    expect(SUPPORTED_PROPS.filter((prop) => !PROP_LABELS[prop])).toEqual([]);
+  });
+});

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