studio-dev

Studio development

Apply these principles when implementing or reviewing Studio itself. They cover the regular Studio and Browser Studio at remotion.new.

Optimistic operations

Every operation must have an optimistic update. Reflect the user's intent immediately instead of waiting for a server request, filesystem write, codemod, or hot reload. For work whose result is not yet known, show its pending state immediately without claiming completion.

Reconcile the optimistic state with the persisted result. Preserve it until the updated source/configuration arrives through HMR, and handle failures with a rollback and visible error. A late response or rollback must not overwrite a newer edit or undo. Use the existing mutation queue and history mechanisms; see enqueueStudioSourceMutation and optimistic composition metadata.

Agent, interactive, and code parity

• Every state and action must be available to an agent through project code or WebMCP. Anything already editable in project source satisfies this requirement. Moving or trimming a sequence, for example, does not need a WebMCP tool. Do not add redundant tools solely to mirror source-backed editing actions.
• Expose transient Studio state and actions through WebMCP when project source cannot represent them, such as playback, selection, pending render jobs, and render cancellation. Follow the existing registrations in WebMcp.tsx and the relevant feature's tools.
• Document every new WebMCP tool and changes to its inputs or outputs in the WebMCP documentation, including pending state, results, and mode availability.
• Every source-backed edit must work interactively and by editing project code, which also provides agentic access. Direct code changes must appear correctly after hot reload. Where a WebMCP editing tool exists, it must use the same source mutation/history path as the UI. Avoid separate sources of truth.
• Keep validation, optimistic behavior, undo/redo, errors, and mode restrictions consistent across interactive and WebMCP entry points. Read current state when a tool executes instead of capturing a stale snapshot at registration time.

Consider all four Studio modes

Read studio-mode when deciding availability. Check each new action and its WebMCP entry point against all four modes:

Mode	Capabilities to consider
Regular interactive Studio	Attached Studio server; source edits, codemods, dependency installation, server rendering, and supported “Open in” actions.
Regular Studio with preview server detached	previewServerConnected is false; effectively read-only, with client-side rendering still available.
Read-only deployed Studio	No attached server; hide or disable server-dependent actions. GitHub is the only supported “Open in” action.
Browser Studio (remotion.new)	Runs in an iframe with a virtual filesystem hidden from the user; supports codemods and dependency installation, but no “Open in” actions.

Use existing capability checks. A deployed Studio is not necessarily read-only: Browser Studio has its own mutation capabilities. Hide or disable unsupported UI actions and enforce the same restrictions when invoked agentically.

Prevent the iframe hover bug

The hover bug is stale hover state after the pointer leaves Studio's iframe. Browsers can miss pointerleave/mouse leave events, leaving event-driven React hover state stuck: buttons and menu rows stay highlighted, or tooltips remain visible after the pointer has gone. See issue #9886 and the tooltip and hover fix.

• Drive purely visual hover styling with CSS :hover, using HOVERABLE_CLASS_NAME and hoverableStyle() from hoverable.ts. Use the existing hover-group classes to reveal row actions. Do not introduce React hover state just to change colors, backgrounds, or visibility.
• When JavaScript behavior depends on hover, such as a delayed menu or tooltip, use observeHover(). It handles recovery from missed leave events, window blur, visibility changes, and Browser Studio's forwarded remotion-browser-studio-pointerleave event. Dispose the observer and cancel pending timers during cleanup and dismissal.
• Preserve intentional selected, keyboard-focused, and open-menu states. Nested actions must not appear hovered just because their parent row is hovered. Keep actions usable with keyboard and touch.
• Verify in an iframe as well as regular Studio: hover, leave the frame, re-enter, and switch window focus. Highlights and pending/visible tooltips must clear correctly. The existing regression in browser-studio.test.ts, clears hover backgrounds even if pointer leave events are lost, deliberately suppresses leave events to exercise this failure.

Follow the Studio design and CSS reset

Read studio-css-reset and no-pointer when adding or changing UI.

• Reuse the closest existing Studio controls, layouts, and interaction patterns. Match their colors, fonts, font sizes, control sizes, spacing, borders, icons, and hover, focus, selected, and disabled traits. Use shared tokens from colors.ts and existing component styles instead of introducing a separate visual language.
• The .css-reset, .css-reset * rule applies to every descendant in a reset container, not just the parent. It resets font size, line height, color, font family, background, and box sizing. Parent text styles alone do not override each child's reset. Style the element that paints the text or SVG, or use an appropriate descendant selector. Check computed styles, including nested labels and icons.
• Never add a DOM title attribute for a tooltip, including title="". Use a tooltip component: the existing Studio implementation exposes ActionTooltip and ClippedTextTooltip in ActionTooltip.tsx. Preserve accessible labels and keyboard focus behavior.
• Never use cursor: 'pointer' for Studio controls or links. Use cursor: 'default'. Follow the shared hover and :focus-visible conventions; keep a visible keyboard focus indicator.

Performance must not regress

Read studio-perf. Prefer consuming context through an existing stable ref or imperative getter when the value is needed only during an action. Copying a reactive context value into a ref after subscribing does not avoid the subscription's re-renders.

For example, read getCurrentFrame() from imperative-state.ts inside event handlers and WebMCP tools instead of importing Internals.Timeline.useTimelinePosition() into their owning component. Subscribe to the frame only in the smallest leaf whose visible output must change on every frame. Keep props and context values stable across memoized boundaries.

Test performance when adding features; source inspection is not enough. Capture a baseline and repeat the same representative interaction after the change, including playback/scrubbing when the feature participates in frame updates. Use react-scan for render/commit measurements and browser profiling for non-React work. Keep the composition, viewport, and repetitions comparable. Check unnecessary renders, commit duration, interaction latency, and playback smoothness as relevant, and resolve regressions before finishing. Report the measured result and any verification limits.

Verify the feature

Exercise source-backed edits through the UI and direct code changes. Exercise WebMCP where a tool is provided or needed for transient Studio state and actions. Check immediate feedback, persistence after HMR, failure recovery, and undo/redo for edits that participate in history. Check availability in each mode and the relevant hover, focus, cursor, and CSS-reset behavior above.

For Studio code changes, run the package build and relevant existing checks:

bunx turbo run make --filter='@remotion/studio'
bunx turbo run lint test --filter='@remotion/studio'

Include affected packages and existing browser regression tests when the change crosses those boundaries. Follow writing-tests when adding or changing tests.