@remotion/studio: Reload config changes in Studio

.agents/skills/add-cli-option/SKILL.md

@@ -72,6 +72,8 @@ const myFlag = myFlagOption.getValue({commandLine: parsedCli}).value;
 
 For Studio options, this is typically in `packages/cli/src/studio.ts`. For render options, in the relevant render command file.
 
+If the option is consumed by Studio, read [`../studio-config-option-lifecycle/SKILL.md`](../studio-config-option-lifecycle/SKILL.md) completely before wiring it. Classify the option as startup-fixed or reloadable across all Studio consumers; mixed behavior is not allowed. If any consumer requires startup-fixed behavior, pass the startup snapshot to every consumer. Add lifecycle tests that prove the classification.
+
 ## 5. Add to Config
 
 **`packages/cli/src/config/index.ts`**:

.agents/skills/studio-config-option-lifecycle/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: studio-config-option-lifecycle
+description: Classify and wire Remotion Studio config options as either startup-fixed or reloadable while preventing mixed lifecycle behavior across consumers. Use when adding, changing, or reviewing a Config setter or CLI option consumed by Studio, its preview server, compiler, HTML bootstrap, public-folder watcher, or render queue.
+---
+
+# Studio Config Option Lifecycle
+
+Make reload behavior explicit for every Studio-facing option. A config file is reset and re-executed when it changes, but a consumer only observes the new value if its code reads the option again.
+
+## Classify the whole option
+
+Inspect every Studio consumer, then assign one lifecycle to the whole option:
+
+- **Startup-fixed:** Changing the value requires recreating a server, compiler, watcher, directory mapping, or other initialized resource.
+- **Reloadable:** Every Studio consumer can safely use the new value after the browser reload or at another deliberate request boundary.
+
+If any consumer must be startup-fixed, make the option startup-fixed for all Studio consumers. Do not implement mixed lifecycle behavior.
+
+Do not infer reloadability from `Config.set*()` state being updated. Config re-execution updates module state regardless of whether an already-created consumer observes it.
+
+## Wire startup-fixed values
+
+Resolve the option once in `packages/cli/src/studio.ts` before calling `startStudio()`:
+
+```ts
+const fixedValue = option.getValue({commandLine: parsedCli}).value;
+
+await StudioServerInternals.startStudio({
+	fixedValue,
+});
+```
+
+Pass the value, not a getter, through `startStudio()`, `startServer()`, and the consumer. Keep new internal parameters required; use `T | null` when absence is valid.
+
+Capture startup-fixed render settings in `StudioRenderJobFixedConfig` at the Studio queue boundary and thread that object into the job processor. Do not call `option.getValue()` from the processor, because config state may have changed since Studio startup.
+
+Typical startup-fixed consumers include the Studio port, entry point, active compiler choice and override, polling mode, public directory and watcher, network binding, and cross-site-isolation headers.
+
+## Wire reloadable values
+
+Read reloadable options through a getter that retains CLI precedence:
+
+```ts
+const getValue = () =>
+	option.getValue({commandLine: parsedCli}).value;
+
+await StudioServerInternals.startStudio({
+	getValue,
+});
+```
+
+Pass the getter as a required internal callback and invoke it only at the boundary that should observe config changes, such as generating Studio HTML after the `config-file-changed` browser reload. Do not evaluate the getter earlier and pass its result onward.
+
+Use the existing `getStudioRuntimeConfig()` path for values already represented by `StudioRuntimeConfig`. Be careful when extending that exported type: adding a required property can be a public API break. For independent HTML bootstrap values, pass a dedicated getter through the internal Studio server layers.
+
+Only use this pattern when all Studio consumers are reloadable. Typical examples include UI behavior and HTML bootstrap defaults that do not require rebuilding initialized resources.
+
+## Resolve lifecycle conflicts
+
+Search all reads of the option and decide each one independently:
+
+```sh
+rg -n "myOption|setMyOption|my-cli-flag" packages
+```
+
+If the consumers do not all support reloading, capture the option once at Studio startup and pass that same value to every consumer. For example, if the active preview compiler cannot change bundlers, future render jobs must retain the startup bundler choice as well.
+
+Treat aliases as one option. If a deprecated setter updates multiple underlying values, make every affected Studio consumer follow the stricter startup-fixed lifecycle.
+
+## Reset and rollback
+
+Ensure config reload resets the option before executing the changed file, so deleting a setter restores the default. Options registered through `BrowserSafeApis.options` and exposed directly through `Config` are reset by `resetBrowserSafeConfigOptions()`. Add an explicit reset in `ConfigInternals.resetConfigOptions()` for custom module state.
+
+Preserve transactional reload behavior: an invalid changed config must leave the previous valid configuration active.
+
+## Test the lifecycle
+
+Add tests that prove the classification:
+
+- Reloadable: change the option after the initial read, cross the intended reload/request boundary, and assert the new value is observed.
+- Startup-fixed: capture the initial value, change config state, and assert the initialized consumer still receives the original value.
+- Cross-consumer: assert every Studio consumer receives the same startup snapshot when any one consumer requires it.
+- Reset: omit a previously set option on reload and assert its default is restored.
+- Nullable internal inputs: pass `null` explicitly in fixtures and call sites.
+
+Run focused builds and checks for the affected packages:
+
+```sh
+bunx turbo run make lint formatting --filter='@remotion/cli' --filter='@remotion/studio-server'
+bun test packages/cli/src/test/config-reload.test.ts packages/cli/src/test/config-reset.test.ts
+```

.agents/skills/studio-config-option-lifecycle/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Studio Config Option Lifecycle"
+  short_description: "Classify Studio options by reload behavior"
+  default_prompt: "Use $studio-config-option-lifecycle to wire a Studio config option with explicit reload behavior."

packages/cli/src/config/buffer-state-delay-in-milliseconds.ts

@@ -7,3 +7,7 @@ export const getBufferStateDelayInMilliseconds = () => {
 export const setBufferStateDelayInMilliseconds = (val: number | null) => {
 	value = val;
 };
+
+export const resetBufferStateDelayInMilliseconds = () => {
+	value = null;
+};

packages/cli/src/config/entry-point.ts

@@ -7,3 +7,7 @@ export const setEntryPoint = (ep: string) => {
 export const getEntryPoint = () => {
 	return entryPoint;
 };
+
+export const resetEntryPoint = () => {
+	entryPoint = null;
+};

packages/cli/src/config/ffmpeg-override.ts

@@ -1,6 +1,8 @@
 import type {FfmpegOverrideFn} from '@remotion/renderer';
 
-let ffmpegOverrideFn: FfmpegOverrideFn = ({args}) => args;
+const defaultFfmpegOverrideFn: FfmpegOverrideFn = ({args}) => args;
+
+let ffmpegOverrideFn: FfmpegOverrideFn = defaultFfmpegOverrideFn;
 
 export const setFfmpegOverrideFunction = (fn: FfmpegOverrideFn) => {
 	ffmpegOverrideFn = fn;
@@ -9,3 +11,7 @@ export const setFfmpegOverrideFunction = (fn: FfmpegOverrideFn) => {
 export const getFfmpegOverrideFunction = () => {
 	return ffmpegOverrideFn;
 };
+
+export const resetFfmpegOverrideFunction = () => {
+	ffmpegOverrideFn = defaultFfmpegOverrideFn;
+};

packages/cli/src/config/index.ts

@@ -18,33 +18,42 @@ import {Log} from '../log';
 import {getBrowser} from './browser';
 import {
 	getBufferStateDelayInMilliseconds,
+	resetBufferStateDelayInMilliseconds,
 	setBufferStateDelayInMilliseconds,
 } from './buffer-state-delay-in-milliseconds';
-import {getConcurrency} from './concurrency';
 import type {Concurrency} from './concurrency';
-import {getEntryPoint, setEntryPoint} from './entry-point';
+import {getConcurrency} from './concurrency';
+import {getEntryPoint, resetEntryPoint, setEntryPoint} from './entry-point';
 import {getDotEnvLocation} from './env-file';
 import {
 	getFfmpegOverrideFunction,
+	resetFfmpegOverrideFunction,
 	setFfmpegOverrideFunction,
 } from './ffmpeg-override';
 import {getShouldOutputImageSequence} from './image-sequence';
-import {getMetadata, setMetadata} from './metadata';
-import {getOutputLocation} from './output-location';
-import {setOutputLocation} from './output-location';
+import {getMetadata, resetMetadata, setMetadata} from './metadata';
+import {
+	getOutputLocation,
+	resetOutputLocation,
+	setOutputLocation,
+} from './output-location';
+import type {WebpackOverrideFn} from './override-webpack';
 import {
 	defaultOverrideFunction,
 	getWebpackOverrideFn,
+	overrideWebpackConfig,
+	resetWebpackOverride,
 } from './override-webpack';
-import type {WebpackOverrideFn} from './override-webpack';
-import {overrideWebpackConfig} from './override-webpack';
 import {
 	getRendererPortFromConfigFile,
 	getRendererPortFromConfigFileAndCliFlag,
 	getStudioPort,
+	resetPreviewServerPorts,
+	setPort,
+	setRendererPort,
+	setStudioPort,
 } from './preview-server';
-import {setPort, setRendererPort, setStudioPort} from './preview-server';
-import {getStillFrame, setStillFrame} from './still-frame';
+import {getStillFrame, resetStillFrame, setStillFrame} from './still-frame';
 import {getWebpackCaching} from './webpack-caching';
 import {getWebpackPolling} from './webpack-poll';
 
@@ -804,6 +813,69 @@ export const Config: FlatConfig = {
 	setPreviewSampleRate: previewSampleRateOption.setConfig,
 };
 
+type BrowserSafeConfigOption = {
+	cliFlag: string;
+	getValue: (values: {commandLine: Record<string, unknown>}) => {
+		value: unknown;
+		source: string;
+	};
+	setConfig: (value: never) => void;
+	reset?: () => void;
+};
+
+const getDefaultConfigValue = (option: BrowserSafeConfigOption) => {
+	for (const cliValue of [undefined, null]) {
+		const result = option.getValue({
+			commandLine: {[option.cliFlag]: cliValue},
+		});
+		if (result.source !== 'cli') {
+			return result.value;
+		}
+	}
+
+	throw new Error(`Could not determine the default for --${option.cliFlag}`);
+};
+
+const configSetters = new Set(
+	Object.values(Object.getOwnPropertyDescriptors(Config))
+		.map((descriptor) => descriptor.value)
+		.filter(
+			(value): value is (...args: never[]) => unknown =>
+				typeof value === 'function',
+		),
+);
+
+const browserSafeConfigOptionResets = Object.values(BrowserSafeApis.options)
+	.filter((option) => configSetters.has(option.setConfig))
+	.map((untypedOption): (() => void) => {
+		const option = untypedOption as unknown as BrowserSafeConfigOption;
+		if (option.reset) {
+			return option.reset;
+		}
+
+		const defaultValue = getDefaultConfigValue(option);
+		return () => option.setConfig(defaultValue as never);
+	});
+
+const resetBrowserSafeConfigOptions = () => {
+	for (const reset of browserSafeConfigOptionResets) {
+		reset();
+	}
+};
+
+const resetConfigOptions = () => {
+	resetBrowserSafeConfigOptions();
+	StudioServerInternals.resetMaxTimelineTracks();
+	resetBufferStateDelayInMilliseconds();
+	resetEntryPoint();
+	resetFfmpegOverrideFunction();
+	resetMetadata();
+	resetOutputLocation();
+	resetWebpackOverride();
+	resetPreviewServerPorts();
+	resetStillFrame();
+};
+
 export const ConfigInternals = {
 	getBrowser,
 	getStudioPort,
@@ -825,4 +897,5 @@ export const ConfigInternals = {
 	getWebpackPolling,
 	getBufferStateDelayInMilliseconds,
 	getOutputCodecOrUndefined: BrowserSafeApis.getOutputCodecOrUndefined,
+	resetConfigOptions,
 };

packages/cli/src/config/metadata.ts

@@ -7,3 +7,7 @@ export const setMetadata = (metadata: Record<string, string>): void => {
 export const getMetadata = (): Record<string, string> => {
 	return specifiedMetadata;
 };
+
+export const resetMetadata = (): void => {
+	specifiedMetadata = undefined as unknown as Record<string, string>;
+};

packages/cli/src/config/output-location.ts

@@ -17,3 +17,7 @@ export const setOutputLocation = (newOutputLocation: string) => {
 };
 
 export const getOutputLocation = () => currentOutputLocation;
+
+export const resetOutputLocation = () => {
+	currentOutputLocation = null;
+};

packages/cli/src/config/override-webpack.ts

@@ -15,3 +15,7 @@ export const overrideWebpackConfig = (fn: WebpackOverrideFn) => {
 	const prevOverride = overrideFn;
 	overrideFn = async (c) => fn(await prevOverride(c));
 };
+
+export const resetWebpackOverride = () => {
+	overrideFn = defaultOverrideFunction;
+};

packages/cli/src/config/preview-server.ts

@@ -60,3 +60,8 @@ export const getRendererPortFromConfigFileAndCliFlag = (): number | null => {
 		portOption.getValue({commandLine: parsedCli}).value ?? rendererPort ?? null
 	);
 };
+
+export const resetPreviewServerPorts = () => {
+	studioPort = undefined;
+	rendererPort = undefined;
+};

packages/cli/src/config/still-frame.ts

@@ -12,3 +12,7 @@ export const setStillFrame = (frame: number) => {
 };
 
 export const getStillFrame = () => stillFrame;
+
+export const resetStillFrame = () => {
+	stillFrame = 0;
+};