From 3570c852aa11db789f66a8e5b8db4b3cbd9c6033 Mon Sep 17 00:00:00 2001
From: Igor Samokhovets <igor@remotion.dev>
Date: Wed, 22 Jul 2026 13:07:58 +0200
Subject: [PATCH] Document site version compatibility contract

---
 packages/renderer/src/set-props-and-env.ts | 5 +++++
 packages/studio-shared/src/studio-html.ts  | 5 +++++
 2 files changed, 10 insertions(+)

diff --git a/packages/renderer/src/set-props-and-env.ts b/packages/renderer/src/set-props-and-env.ts
index b775d0db34b..e61b5bc69ca 100644
--- a/packages/renderer/src/set-props-and-env.ts
+++ b/packages/renderer/src/set-props-and-env.ts
@@ -282,6 +282,11 @@ const innerSetPropsAndEnv = async ({
 		timeoutInMilliseconds: actualTimeout,
 	});
 
+	// Increment this value when the generated bundle format or behavior changes
+	// in a backwards-incompatible way. It is not the Remotion package version and
+	// should not be bumped for every generated HTML change. Keep it synchronized
+	// with window.siteVersion in packages/studio-shared/src/studio-html.ts by
+	// incrementing both values.
 	const requiredVersion: typeof window.siteVersion = '11';
 
 	if (siteVersion !== requiredVersion) {
diff --git a/packages/studio-shared/src/studio-html.ts b/packages/studio-shared/src/studio-html.ts
index 9123d75b6d0..f21704c409c 100644
--- a/packages/studio-shared/src/studio-html.ts
+++ b/packages/studio-shared/src/studio-html.ts
@@ -153,6 +153,11 @@ export const studioHtml = ({
 		<script>window.remotion_packageManager = ${JSON.stringify(packageManager)}</script>
 		<script>window.remotion_publicFolderExists = ${JSON.stringify(publicFolderExists)};</script>
 		<script>
+				// Increment this value when the generated bundle format or behavior changes
+				// in a backwards-incompatible way. It is not the Remotion package version
+				// and should not be bumped for every generated HTML change.
+				// Keep it synchronized with requiredVersion in
+				// packages/renderer/src/set-props-and-env.ts by incrementing both values.
 				window.siteVersion = '11';
 				window.remotion_version = '${VERSION}';
 		</script>