fix(studio): break all 7 circular dependency cycles and fix rules-of-hooks violation

Author: miguel-heygen

.github/workflows/ci.yml

@@ -265,26 +265,36 @@ jobs:
       - uses: ./.github/actions/prepare-ffmpeg-bin
       - run: bun install --frozen-lockfile
       - run: bun run --cwd packages/core build:hyperframes-runtime
-      - name: Start studio and check for runtime errors
+      - run: bun run build
+      - name: Start studio with project and check for runtime errors
         run: |
-          # Start the studio dev server in the background
-          bun run --filter '@hyperframes/studio' dev -- --port 5199 &
+          # Create a minimal project so the studio boots fully (not just splash)
+          mkdir -p /tmp/smoke-project
+          cat > /tmp/smoke-project/index.html <<'PROJHTML'
+          <div data-composition-id="root" data-width="1920" data-height="1080" data-duration="1" data-start="0">
+            <div class="clip" id="smoke-el" data-start="0" data-duration="1" style="color:white;font-size:48px;">Smoke</div>
+          </div>
+          PROJHTML
+
+          # Start the preview server from inside the project dir
+          cd /tmp/smoke-project
+          npx tsx $GITHUB_WORKSPACE/packages/cli/src/cli.ts preview --port 5199 --no-open &
           SERVER_PID=$!
+          cd $GITHUB_WORKSPACE
 
-          # Wait for the server to be ready (up to 20s)
-          for i in $(seq 1 40); do
+          # Wait for the server to be ready (up to 60s)
+          for i in $(seq 1 120); do
             if curl -sf http://localhost:5199/ >/dev/null 2>&1; then break; fi
             sleep 0.5
           done
 
           if ! curl -sf http://localhost:5199/ >/dev/null 2>&1; then
-            echo "FAIL: studio dev server did not start"
+            echo "FAIL: studio preview server did not start"
             kill $SERVER_PID 2>/dev/null || true
             exit 1
           fi
 
-          # Load the studio in headless Chrome and capture console errors
-          # puppeteer is a dependency of @hyperframes/producer; resolve from there
+          # Load the studio in headless Chrome — tests the full boot path
           cd packages/producer
           node --input-type=module <<'SMOKE_EOF'
           import puppeteer from "puppeteer";
@@ -299,17 +309,27 @@ jobs:
             if (msg.type() === "error") errors.push(msg.text());
           });
           await page.goto("http://localhost:5199/", { waitUntil: "networkidle0", timeout: 30000 });
-          await new Promise((r) => setTimeout(r, 3000));
+          // Wait for the studio to fully transition past splash
+          await new Promise((r) => setTimeout(r, 5000));
+          // Check for React error boundary (catches hooks violations, render crashes)
+          const errorBoundary = await page.evaluate(() => {
+            const text = document.body.innerText;
+            if (text.includes("Something went wrong")) return text;
+            return null;
+          });
+          if (errorBoundary) {
+            errors.push("React error boundary triggered: " + errorBoundary);
+          }
           await browser.close();
           const fatal = errors.filter(
             (e) => !e.includes("favicon") && !e.includes("ERR_CONNECTION_REFUSED"),
           );
           if (fatal.length > 0) {
-            console.error("FAIL: studio had runtime errors on load:");
+            console.error("FAIL: studio had runtime errors:");
             for (const e of fatal) console.error("  •", e);
             process.exit(1);
           }
-          console.log("PASS: studio loaded without runtime errors");
+          console.log("PASS: studio loaded and transitioned without runtime errors");
           SMOKE_EOF
 
           kill $SERVER_PID 2>/dev/null || true

packages/producer/tests/webm-transparency/output/output.webm

@@ -452,8 +452,6 @@ export function StudioApp() {
     timelineVisible,
     toggleTimelineVisibility,
   });
-  if (resolving || waitingForServer || !projectId)
-    return <StudioSplash waiting={waitingForServer} />;
   const timelineToolbar = useMemo(
     () => (
       <TimelineToolbar
@@ -464,6 +462,8 @@ export function StudioApp() {
     ),
     [toggleTimelineVisibility, domEditSession, timelineEditing.handleTimelineElementSplit],
   );
+  if (resolving || waitingForServer || !projectId)
+    return <StudioSplash waiting={waitingForServer} />;
   return (
     <StudioShellProvider value={studioCtxValue}>
       <StudioPlaybackProvider value={studioCtxValue}>

packages/studio/src/App.tsx

@@ -4,6 +4,7 @@ import { type DomEditSelection } from "./domEditing";
 import { resolveDomEditGroupOverlayRect } from "./domEditOverlayGeometry";
 import {
   type BlockedMoveState,
+  type DomEditGroupPathOffsetCommit,
   type FocusableDomEditOverlay,
   type GestureState,
   type GroupGestureState,
@@ -27,11 +28,7 @@ export {
   resolveDomEditResizeGesture,
   resolveDomEditRotationGesture,
 } from "./domEditOverlayGestures";
-
-export interface DomEditGroupPathOffsetCommit {
-  selection: DomEditSelection;
-  next: { x: number; y: number };
-}
+export type { DomEditGroupPathOffsetCommit } from "./domEditOverlayGestures";
 
 interface DomEditOverlayProps {
   iframeRef: RefObject<HTMLIFrameElement | null>;

packages/studio/src/components/editor/DomEditOverlay.tsx

@@ -1,12 +1,14 @@
+import type { RefObject } from "react";
 import type { DomEditSelection } from "./domEditing";
 import type {
   StudioBoxSizeSnapshot,
   StudioPathOffsetSnapshot,
   StudioRotationSnapshot,
 } from "./manualEdits";
 import type { ManualOffsetDragMember } from "./manualOffsetDrag";
-import type { GroupOverlayItem } from "./domEditOverlayGeometry";
+import type { GroupOverlayItem, OverlayRect } from "./domEditOverlayGeometry";
 import type { SnapContext } from "./snapTargetCollection";
+import type { SnapGuidesState } from "./SnapGuideOverlay";
 
 export type GestureKind = "drag" | "resize" | "rotate";
 
@@ -143,3 +145,54 @@ export function resolveDomEditRotationGesture(input: {
 export function hasDomEditRotationChanged(initialAngle: number, nextAngle: number): boolean {
   return Math.abs(nextAngle - initialAngle) >= ROTATION_COMMIT_EPSILON_DEGREES;
 }
+
+// ── Shared types for DomEditOverlay gesture wiring ──
+// These live here (rather than in DomEditOverlay.tsx or useDomEditOverlayGestures.ts)
+// to break circular imports between those files.
+
+export interface DomEditGroupPathOffsetCommit {
+  selection: DomEditSelection;
+  next: { x: number; y: number };
+}
+
+// Refs are stable across renders; values are read via .current.
+export type UseDomEditOverlayGesturesOptions = {
+  overlayRef: RefObject<HTMLDivElement | null>;
+  iframeRef: RefObject<HTMLIFrameElement | null>;
+  boxRef: RefObject<HTMLDivElement | null>;
+  selectionRef: RefObject<DomEditSelection | null>;
+  overlayRectRef: RefObject<OverlayRect | null>;
+  groupOverlayItemsRef: RefObject<GroupOverlayItem[]>;
+  gestureRef: RefObject<GestureState | null>;
+  groupGestureRef: RefObject<GroupGestureState | null>;
+  blockedMoveRef: RefObject<BlockedMoveState | null>;
+  rafPausedRef: RefObject<boolean>;
+  suppressNextBoxClickRef: RefObject<boolean>;
+  setOverlayRect: (next: OverlayRect | null) => void;
+  setGroupOverlayItems: (next: GroupOverlayItem[]) => void;
+  onBlockedMoveRef: RefObject<(selection: DomEditSelection) => void>;
+  onManualDragStartRef: RefObject<(() => void) | undefined>;
+  onPathOffsetCommitRef: RefObject<
+    (s: DomEditSelection, n: { x: number; y: number }) => Promise<void> | void
+  >;
+  onGroupPathOffsetCommitRef: RefObject<
+    (updates: DomEditGroupPathOffsetCommit[]) => Promise<void> | void
+  >;
+  onBoxSizeCommitRef: RefObject<
+    (s: DomEditSelection, n: { width: number; height: number }) => Promise<void> | void
+  >;
+  onRotationCommitRef: RefObject<
+    (s: DomEditSelection, n: { angle: number }) => Promise<void> | void
+  >;
+  onCanvasPointerMoveRef: RefObject<
+    (
+      e: React.PointerEvent<HTMLDivElement>,
+      o?: { preferClipAncestor?: boolean },
+    ) => Promise<DomEditSelection | null>
+  >;
+  onCanvasMouseDown: (
+    e: React.MouseEvent<HTMLDivElement>,
+    o?: { preferClipAncestor?: boolean },
+  ) => void;
+  snapGuidesRef: RefObject<SnapGuidesState | null>;
+};

packages/studio/src/components/editor/domEditOverlayGestures.ts

@@ -21,8 +21,11 @@ import {
   filterNestedDomEditGroupItems,
   selectionCacheKey,
 } from "./domEditOverlayGeometry";
-import { type GestureKind, type GestureState } from "./domEditOverlayGestures";
-import type { UseDomEditOverlayGesturesOptions } from "./useDomEditOverlayGestures";
+import {
+  type GestureKind,
+  type GestureState,
+  type UseDomEditOverlayGesturesOptions,
+} from "./domEditOverlayGestures";
 import { collectSnapContext, buildExcludeElements } from "./snapTargetCollection";
 
 export function startGroupDrag(

packages/studio/src/components/editor/domEditOverlayStartGesture.ts

@@ -33,15 +33,14 @@ import {
 } from "./domEditOverlayGeometry";
 import {
   BLOCKED_MOVE_THRESHOLD_PX,
-  type BlockedMoveState,
   type GestureKind,
   type GestureState,
   type GroupGestureState,
+  type UseDomEditOverlayGesturesOptions,
   hasDomEditRotationChanged,
   resolveDomEditResizeGesture,
   resolveDomEditRotationGesture,
 } from "./domEditOverlayGestures";
-import type { DomEditGroupPathOffsetCommit } from "./DomEditOverlay";
 import {
   startGesture as _startGesture,
   startGroupDrag as _startGroupDrag,
@@ -52,50 +51,6 @@ import {
   resolveEquidistanceGuides,
   SNAP_THRESHOLD_PX,
 } from "./snapEngine";
-import type { SnapGuidesState } from "./SnapGuideOverlay";
-
-// Refs are stable across renders; values are read via .current.
-export type UseDomEditOverlayGesturesOptions = {
-  overlayRef: RefObject<HTMLDivElement | null>;
-  iframeRef: RefObject<HTMLIFrameElement | null>;
-  boxRef: RefObject<HTMLDivElement | null>;
-  selectionRef: RefObject<DomEditSelection | null>;
-  overlayRectRef: RefObject<OverlayRect | null>;
-  groupOverlayItemsRef: RefObject<GroupOverlayItem[]>;
-  gestureRef: RefObject<GestureState | null>;
-  groupGestureRef: RefObject<GroupGestureState | null>;
-  blockedMoveRef: RefObject<BlockedMoveState | null>;
-  rafPausedRef: RefObject<boolean>;
-  suppressNextBoxClickRef: RefObject<boolean>;
-  setOverlayRect: (next: OverlayRect | null) => void;
-  setGroupOverlayItems: (next: GroupOverlayItem[]) => void;
-  onBlockedMoveRef: RefObject<(selection: DomEditSelection) => void>;
-  onManualDragStartRef: RefObject<(() => void) | undefined>;
-  onPathOffsetCommitRef: RefObject<
-    (s: DomEditSelection, n: { x: number; y: number }) => Promise<void> | void
-  >;
-  onGroupPathOffsetCommitRef: RefObject<
-    (updates: DomEditGroupPathOffsetCommit[]) => Promise<void> | void
-  >;
-  onBoxSizeCommitRef: RefObject<
-    (s: DomEditSelection, n: { width: number; height: number }) => Promise<void> | void
-  >;
-  onRotationCommitRef: RefObject<
-    (s: DomEditSelection, n: { angle: number }) => Promise<void> | void
-  >;
-  onCanvasPointerMoveRef: RefObject<
-    (
-      e: React.PointerEvent<HTMLDivElement>,
-      o?: { preferClipAncestor?: boolean },
-    ) => Promise<DomEditSelection | null>
-  >;
-  onCanvasMouseDown: (
-    e: React.MouseEvent<HTMLDivElement>,
-    o?: { preferClipAncestor?: boolean },
-  ) => void;
-  snapGuidesRef: RefObject<SnapGuidesState | null>;
-};
-
 export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGesturesOptions) {
   const setDraftOverlayRect = (next: OverlayRect) => {
     opts.setOverlayRect(next);

packages/studio/src/components/editor/useDomEditOverlayGestures.ts

@@ -0,0 +1,14 @@
+import type { DomEditSelection } from "../components/editor/domEditing";
+import type { PatchOperation } from "../utils/sourcePatcher";
+
+export type PersistDomEditOperations = (
+  selection: DomEditSelection,
+  operations: PatchOperation[],
+  options?: {
+    label?: string;
+    coalesceKey?: string;
+    skipRefresh?: boolean;
+    prepareContent?: (html: string, sourceFile: string) => string;
+    shouldSave?: () => boolean;
+  },
+) => Promise<void>;

packages/studio/src/hooks/domEditCommitTypes.ts

@@ -1,12 +1,12 @@
-import type { TimelineElement } from "../player";
+import type { TimelineElement } from "../player/store/playerStore";
 import { applyPatchByTarget, readAttributeByTarget } from "../utils/sourcePatcher";
 import { formatTimelineAttributeNumber } from "../player/components/timelineEditing";
 import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
 import type { EditHistoryKind } from "../utils/editHistory";
 
 // ── Types ──
 
-interface RecordEditInput {
+export interface RecordEditInput {
   label: string;
   kind: EditHistoryKind;
   coalesceKey?: string;

packages/studio/src/hooks/timelineEditingHelpers.ts

@@ -1,13 +1,14 @@
 import { useCallback, useRef } from "react";
 import { findUnsafeDomPatchValues } from "@hyperframes/core/studio-api/finite-mutation";
 import { FONT_EXT } from "../utils/mediaTypes";
-import type { PatchOperation } from "../utils/sourcePatcher";
+
 import { trackStudioEvent } from "../utils/studioTelemetry";
 import { primaryFontFamilyValue } from "../utils/studioFontHelpers";
 import { createStudioSaveHttpError } from "../utils/studioSaveDiagnostics";
 import { buildDomEditPatchTarget, type DomEditSelection } from "../components/editor/domEditing";
 import { fontFamilyFromAssetPath, type ImportedFontAsset } from "../components/editor/fontAssets";
 import type { EditHistoryKind } from "../utils/editHistory";
+import type { PersistDomEditOperations } from "./domEditCommitTypes";
 import { useDomEditPositionPatchCommit } from "./useDomEditPositionPatchCommit";
 import { useDomEditTextCommits } from "./useDomEditTextCommits";
 import { useDomGeometryCommits } from "./useDomGeometryCommits";
@@ -48,17 +49,7 @@ interface RecordEditInput {
   files: Record<string, { before: string; after: string }>;
 }
 
-export type PersistDomEditOperations = (
-  selection: DomEditSelection,
-  operations: PatchOperation[],
-  options?: {
-    label?: string;
-    coalesceKey?: string;
-    skipRefresh?: boolean;
-    prepareContent?: (html: string, sourceFile: string) => string;
-    shouldSave?: () => boolean;
-  },
-) => Promise<void>;
+export type { PersistDomEditOperations } from "./domEditCommitTypes";
 
 export interface UseDomEditCommitsParams {
   activeCompPath: string | null;