Skip to content

🎥 Make videos programmatically with React

Elements: Open elements in Browser Studio (#10612)

Jonny Burger16c8fe6a42a6
diff --git a/packages/browser-studio/e2e/app.tsx b/packages/browser-studio/e2e/app.tsx
index f184ce3fa8..5353a1e896 100644
--- a/packages/browser-studio/e2e/app.tsx
+++ b/packages/browser-studio/e2e/app.tsx
@@ -3,10 +3,14 @@ import {
createBlankTemplateProject,
type VirtualProject,
} from '@remotion/browser-studio';
+import {StudioProtocolInternals} from '@remotion/studio-protocol';
import {createRoot} from 'react-dom/client';
import {VERSION} from 'remotion/version';
const project = createBlankTemplateProject();
+const initialElementPayload = StudioProtocolInternals.parseBrowserStudioHash(
+ window.location.hash,
+);
(
window as typeof window & {
__browserStudioProject: VirtualProject;
@@ -33,6 +37,11 @@ if (!root) {
createRoot(root).render(
<BrowserStudio
iframeSrc="/frame.html"
+ initialElement={
+ initialElementPayload === null
+ ? null
+ : {payload: initialElementPayload, sourceOrigin: null}
+ }
project={project}
readOnly={false}
onProjectChange={(nextProject) => {
diff --git a/packages/browser-studio/e2e/browser-studio.test.ts b/packages/browser-studio/e2e/browser-studio.test.ts
index 61a3183f83..fc34fa1c32 100644
--- a/packages/browser-studio/e2e/browser-studio.test.ts
+++ b/packages/browser-studio/e2e/browser-studio.test.ts
@@ -1,4 +1,8 @@
import {expect, test} from '@playwright/test';
+import {
+ createElementPayload,
+ StudioProtocolInternals,
+} from '@remotion/studio-protocol';
test('loads Browser Studio and can add, delete, and duplicate', async ({
page,
@@ -272,6 +276,72 @@ export const BrowserElement = () => <Rect width={320} height={180} fill="red" />
await expect(studio.getByText('Browser Element')).toBeVisible();
});
+test('confirms and imports an Element payload from the URL fragment', async ({
+ page,
+}) => {
+ const payload = createElementPayload({
+ dependencies: [],
+ dimensions: {height: 180, width: 320},
+ displayName: 'Linked Element',
+ durationInFrames: 60,
+ installationMode: 'wrapped',
+ slug: 'linked-element',
+ sourceCode: `export const LinkedElement = () => <div>Grüezi 👋</div>;`,
+ });
+ const url = StudioProtocolInternals.makeBrowserStudioUrl({
+ endpoint: 'http://127.0.0.1:62338/',
+ payload,
+ });
+
+ await page.goto(url);
+ const studio = page.frameLocator('iframe');
+ await expect(studio.getByTitle('/project').getByText('MyComp')).toBeVisible();
+
+ await expect(
+ studio.getByText('Install Element', {exact: true}),
+ ).toBeVisible();
+ await expect(
+ studio.getByText('Unverified Browser Studio link'),
+ ).toBeVisible();
+ await expect(studio.getByText('Linked Element')).toBeVisible();
+ await expect
+ .poll(() =>
+ page.evaluate(() => {
+ const browserWindow = window as typeof window & {
+ __browserStudioProject: {files: Record<string, string>};
+ };
+ return browserWindow.__browserStudioProject.files[
+ '/project/src/linked-element.element.tsx'
+ ];
+ }),
+ )
+ .toBeUndefined();
+
+ await studio.getByRole('button', {name: /^Install/}).click();
+ await expect
+ .poll(() =>
+ page.evaluate(() => {
+ const browserWindow = window as typeof window & {
+ __browserStudioProject: {files: Record<string, string>};
+ };
+ return {
+ composition:
+ browserWindow.__browserStudioProject.files[
+ '/project/src/Composition.tsx'
+ ],
+ element:
+ browserWindow.__browserStudioProject.files[
+ '/project/src/linked-element.element.tsx'
+ ],
+ };
+ }),
+ )
+ .toEqual({
+ composition: expect.stringContaining('<LinkedElement />'),
+ element: expect.stringContaining('Grüezi 👋'),
+ });
+});
+
test('reports inline SVG imports as unsupported without changing the project', async ({
page,
}) => {
diff --git a/packages/browser-studio/src/BrowserStudio.tsx b/packages/browser-studio/src/BrowserStudio.tsx
index aa356ed342..5895cedaa9 100644
--- a/packages/browser-studio/src/BrowserStudio.tsx
+++ b/packages/browser-studio/src/BrowserStudio.tsx
@@ -134,6 +134,7 @@ const getBrowserRenderDefaults = (): RenderDefaults => {
export const BrowserStudio: React.FC<BrowserStudioProps> = ({
project,
readOnly,
+ initialElement,
iframeSrc,
dependencyResolver,
onCompileStateChange,
@@ -149,6 +150,7 @@ export const BrowserStudio: React.FC<BrowserStudioProps> = ({
const lastWrittenDocumentRef = useRef<Document | null>(null);
const lastWrittenHtmlRef = useRef<string | null>(null);
const workerRef = useRef<Worker | null>(null);
+ const initialElementRef = useRef(initialElement);
const lastSentProjectRef = useRef<BrowserStudioProps['project'] | null>(null);
const bundleUrlRef = useRef<string | null>(null);
const onCompileStateChangeRef = useRef(onCompileStateChange);
@@ -270,6 +272,7 @@ export const BrowserStudio: React.FC<BrowserStudioProps> = ({
dependencyVersions: browserStudioDependencyVersions,
getStaticFiles: publicFileManager.getStaticFiles,
getProject: () => activeProjectRef.current,
+ initialElement: initialElementRef.current,
onProjectChange: updateProject,
resolveDependencies: resolveElementDependencies,
}),
diff --git a/packages/browser-studio/src/browser-studio-operations.ts b/packages/browser-studio/src/browser-studio-operations.ts
index ef920e1f93..9ba810a043 100644
--- a/packages/browser-studio/src/browser-studio-operations.ts
+++ b/packages/browser-studio/src/browser-studio-operations.ts
@@ -23,7 +23,10 @@ import {
updateDefaultProps as updateDefaultPropsCodemod,
type FormatInline,
} from '@remotion/studio-codemods';
-import {StudioProtocolInternals} from '@remotion/studio-protocol';
+import {
+ StudioProtocolInternals,
+ type StudioElementPayload,
+} from '@remotion/studio-protocol';
import {
getRequiredPackageForInsertableElement,
type BrowserStudioOperations,
@@ -348,6 +351,7 @@ export const createBrowserStudioOperations = ({
dependencyVersions,
getStaticFiles,
getProject,
+ initialElement,
onProjectChange,
resolveDependencies,
}: {
@@ -356,9 +360,14 @@ export const createBrowserStudioOperations = ({
typeof createBrowserStudioProjectController
>[0]['getStaticFiles'];
getProject: () => VirtualProject;
+ initialElement: {
+ payload: StudioElementPayload;
+ sourceOrigin: string | null;
+ } | null;
onProjectChange: (project: VirtualProject) => void;
resolveDependencies: ResolveElementDependencies | null;
}): BrowserStudioOperationsController => {
+ let pendingInitialElement = initialElement;
const defaultPropsSubscriptions = new Map<string, Set<string>>();
const lastDefaultPropsResults = new Map<string, string>();
const sequencePropsSubscriptions = new Map<
@@ -926,6 +935,16 @@ export const createBrowserStudioOperations = ({
return {
applyCodemod,
+ consumeInitialElement: () => {
+ const value = pendingInitialElement;
+ pendingInitialElement = null;
+ return value === null
+ ? null
+ : {
+ element: value.payload.element,
+ sourceOrigin: value.sourceOrigin,
+ };
+ },
deleteJsxNode,
deleteStaticFile: controller.deleteStaticFile,
downloadProject: () =>
diff --git a/packages/browser-studio/src/dev/index.tsx b/packages/browser-studio/src/dev/index.tsx
index 3bcd2ccee2..253ceb55cc 100644
--- a/packages/browser-studio/src/dev/index.tsx
+++ b/packages/browser-studio/src/dev/index.tsx
@@ -11,6 +11,7 @@ if (!root) {
createRoot(root).render(
<BrowserStudio
iframeSrc="/frame.html"
+ initialElement={null}
project={createBlankTemplateProject()}
readOnly={false}
remotionPackageSource={{
diff --git a/packages/browser-studio/src/test/browser-studio-operations.test.ts b/packages/browser-studio/src/test/browser-studio-operations.test.ts
index f18945f974..9b9d8d5b43 100644
--- a/packages/browser-studio/src/test/browser-studio-operations.test.ts
+++ b/packages/browser-studio/src/test/browser-studio-operations.test.ts
@@ -1,4 +1,5 @@
import {expect, test} from 'bun:test';
+import {createElementPayload} from '@remotion/studio-protocol';
import type {EventSourceEvent} from '@remotion/studio-shared';
import {
createBrowserStudioOperations,
@@ -28,6 +29,33 @@ const insertSolid = (
});
};
+test('consumes an initial Element payload only once', () => {
+ const project = createBlankTemplateProject();
+ const payload = createElementPayload({
+ dependencies: [],
+ dimensions: {height: 180, width: 320},
+ displayName: 'Linked Element',
+ durationInFrames: 60,
+ installationMode: 'wrapped',
+ slug: 'linked-element',
+ sourceCode: 'export const LinkedElement = () => <div />;',
+ });
+ const operations = createBrowserStudioOperations({
+ dependencyVersions: {},
+ getProject: () => project,
+ getStaticFiles: null,
+ initialElement: {payload, sourceOrigin: 'https://elements.example.test'},
+ onProjectChange: () => undefined,
+ resolveDependencies: null,
+ });
+
+ expect(operations.consumeInitialElement()).toEqual({
+ element: payload.element,
+ sourceOrigin: 'https://elements.example.test',
+ });
+ expect(operations.consumeInitialElement()).toBe(null);
+});
+
test('adds a Solid to the blank Browser Studio project', () => {
const project = createBlankTemplateProject();
const updated = insertSolid(project);
@@ -106,6 +134,7 @@ export const MyComponent = () => <AbsoluteFill>Existing</AbsoluteFill>;
dependencyVersions: {},
getStaticFiles: null,
getProject: () => currentProject,
+ initialElement: null,
onProjectChange: (nextProject) => {
currentProject = nextProject;
},
@@ -209,6 +238,7 @@ export const Root = () => <Composition id="MyComp" component={Component} duratio
dependencyVersions: {},
getStaticFiles: null,
getProject: () => currentProject,
+ initialElement: null,
onProjectChange: (nextProject) => {
currentProject = nextProject;
},
@@ -300,6 +330,7 @@ registerRoot(Root);`,
dependencyVersions: {},
getStaticFiles: null,
getProject: () => currentProject,
+ initialElement: null,
onProjectChange: (nextProject) => {
currentProject = nextProject;
},
@@ -367,6 +398,7 @@ test('reports invalid timeline Solid input without changing the project', async
dependencyVersions: {},
getStaticFiles: null,
getProject: () => currentProject,
+ initialElement: null,
onProjectChange: (nextProject) => {
currentProject = nextProject;
},
@@ -408,6 +440,7 @@ registerRoot(Root);`,
dependencyVersions: {},
getStaticFiles: null,
getProject: () => currentProject,
+ initialElement: null,
onProjectChange: (nextProject) => {
currentProject = nextProject;
},
@@ -486,6 +519,7 @@ export const Root = () => <Composition id="MyComp" component={Component} duratio
dependencyVersions: {},
getStaticFiles: null,
getProject: () => currentProject,
+ initialElement: null,
onProjectChange: (nextProject) => {
currentProject = nextProject;
},
@@ -691,6 +725,7 @@ registerRoot(Root);`,
dependencyVersions: {},
getStaticFiles: null,
getProject: () => currentProject,
+ initialElement: null,
onProjectChange: (nextProject) => {
currentProject = nextProject;
},
@@ -779,6 +814,7 @@ const makeOperationsForProject = (project: VirtualProject) => {
dependencyVersions: {},
getStaticFiles: null,
getProject: () => currentProject,
+ initialElement: null,
onProjectChange: (nextProject) => {
currentProject = nextProject;
},
diff --git a/packages/browser-studio/src/test/browser-studio-project-operations.test.ts b/packages/browser-studio/src/test/browser-studio-project-operations.test.ts
index 9c78c50148..ee0d869186 100644
--- a/packages/browser-studio/src/test/browser-studio-project-operations.test.ts
+++ b/packages/browser-studio/src/test/browser-studio-project-operations.test.ts
@@ -25,6 +25,7 @@ test('mutates virtual files, emits events, and preserves undo and redo history',
dependencyVersions: {},
getStaticFiles: publicFileManager.getStaticFiles,
getProject: () => project,
+ initialElement: null,
onProjectChange: (nextProject) => {
project = nextProject;
},
@@ -210,6 +211,7 @@ test('previews and duplicates compositions as an undoable project mutation', asy
dependencyVersions: {},
getStaticFiles: null,
getProject: () => project,
+ initialElement: null,
onProjectChange: (nextProject) => {
project = nextProject;
},
@@ -284,6 +286,7 @@ test('imports an Element with pinned Remotion dependencies as one undoable mutat
dependencyVersions: {remotion: '4.0.999'},
getStaticFiles: null,
getProject: () => project,
+ initialElement: null,
onProjectChange: (nextProject) => {
project = nextProject;
},
@@ -381,6 +384,7 @@ test('inserts generic elements with pinned Remotion dependencies', async () => {
dependencyVersions: {remotion: '4.0.999'},
getStaticFiles: null,
getProject: () => project,
+ initialElement: null,
onProjectChange: (nextProject) => {
project = nextProject;
},
@@ -420,6 +424,7 @@ test('rejects inline SVG importing in Browser Studio', async () => {
dependencyVersions: {},
getStaticFiles: null,
getProject: () => project,
+ initialElement: null,
onProjectChange: () => {
throw new Error('SVG insertion must not mutate the project');
},
@@ -448,6 +453,7 @@ test('replays an HMR event emitted before the Studio subscribes', () => {
dependencyVersions: {},
getStaticFiles: null,
getProject: () => project,
+ initialElement: null,
onProjectChange: () => undefined,
resolveDependencies: null,
});
@@ -480,6 +486,7 @@ test('rejects unsafe public paths and conflicting renames', async () => {
dependencyVersions: {},
getStaticFiles: null,
getProject: () => project,
+ initialElement: null,
onProjectChange: (nextProject) => {
project = nextProject;
},
diff --git a/packages/browser-studio/src/test/download-project.test.ts b/packages/browser-studio/src/test/download-project.test.ts
index 8879d86c3f..86b2e209b9 100644
--- a/packages/browser-studio/src/test/download-project.test.ts
+++ b/packages/browser-studio/src/test/download-project.test.ts
@@ -22,6 +22,7 @@ test('downloads the current Browser Studio project as a runnable archive', async
dependencyVersions,
getStaticFiles: null,
getProject: () => project,
+ initialElement: null,
onProjectChange: (nextProject) => {
project = nextProject;
},
diff --git a/packages/browser-studio/src/types.ts b/packages/browser-studio/src/types.ts
index 201de37b6b..beae064b9c 100644
--- a/packages/browser-studio/src/types.ts
+++ b/packages/browser-studio/src/types.ts
@@ -1,3 +1,4 @@
+import type {StudioElementPayload} from '@remotion/studio-protocol';
import type {HotMiddlewareMessage} from '@remotion/studio-shared';
export type VirtualProject = {
@@ -52,6 +53,10 @@ export type CompileState =
export type BrowserStudioProps = {
project: VirtualProject;
readOnly: boolean;
+ initialElement: {
+ payload: StudioElementPayload;
+ sourceOrigin: string | null;
+ } | null;
iframeSrc?: string;
remotionPackageSource?: BrowserStudioRemotionPackageSource;
dependencyResolver?: BrowserStudioDependencyResolver;
diff --git a/packages/docs/src/components/Elements/ElementPage.tsx b/packages/docs/src/components/Elements/ElementPage.tsx
index 4d1175868f..441d96e247 100644
--- a/packages/docs/src/components/Elements/ElementPage.tsx
+++ b/packages/docs/src/components/Elements/ElementPage.tsx
@@ -1,14 +1,19 @@
import Head from '@docusaurus/Head';
-import {installInStudio, setStudioDragData} from '@remotion/studio-protocol';
+import {
+ installInStudio,
+ setStudioDragData,
+ StudioProtocolInternals,
+} from '@remotion/studio-protocol';
import React, {
useCallback,
+ useEffect,
useId,
useMemo,
useRef,
useState,
type ReactNode,
} from 'react';
-import {BlueButton} from '../../../components/layout/Button';
+import {BlueButton, PlainButton} from '../../../components/layout/Button';
import {Seo} from '../Seo';
import type {ElementDefinition} from './element-definitions';
import {
@@ -45,6 +50,8 @@ export const ElementPage: React.FC<ElementPageProps> = ({
type: 'idle',
});
const [isSourceVisible, setIsSourceVisible] = useState(false);
+ const [isBrowserStudioActionVisible, setIsBrowserStudioActionVisible] =
+ useState(false);
const posterRef = useRef<HTMLImageElement>(null);
const sourceId = useId();
const {height: previewHeight, width: previewWidth} =
@@ -58,6 +65,38 @@ export const ElementPage: React.FC<ElementPageProps> = ({
return createElementPayloadFromDefinition({definition, sourceCode});
}, [definition, sourceCode]);
+ useEffect(() => {
+ const onKeyDown = (event: KeyboardEvent) => {
+ if (
+ event.repeat ||
+ !event.altKey ||
+ !event.shiftKey ||
+ event.ctrlKey ||
+ event.metaKey ||
+ event.code !== 'KeyB'
+ ) {
+ return;
+ }
+
+ const {target} = event;
+ if (
+ target instanceof HTMLElement &&
+ (target.isContentEditable ||
+ target.tagName === 'INPUT' ||
+ target.tagName === 'SELECT' ||
+ target.tagName === 'TEXTAREA')
+ ) {
+ return;
+ }
+
+ event.preventDefault();
+ setIsBrowserStudioActionVisible(true);
+ };
+
+ window.addEventListener('keydown', onKeyDown);
+ return () => window.removeEventListener('keydown', onKeyDown);
+ }, []);
+
const installElement = useCallback(async () => {
if (elementPayload === null) {
return;
@@ -86,6 +125,17 @@ export const ElementPage: React.FC<ElementPageProps> = ({
}
}, [definition.slug, elementPayload]);
+ const openInBrowserStudio = useCallback(() => {
+ if (elementPayload === null) {
+ return;
+ }
+
+ StudioProtocolInternals.openInBrowserStudio({
+ endpoint: null,
+ payload: elementPayload,
+ });
+ }, [elementPayload]);
+
const PreviewComponent = useMemo(() => {
return () => <ElementPreviewComposition definition={definition} />;
}, [definition]);
@@ -165,6 +215,17 @@ export const ElementPage: React.FC<ElementPageProps> = ({
? 'Finding Studio…'
: 'Install in Studio'}
</BlueButton>
+ {isBrowserStudioActionVisible ? (
+ <PlainButton
+ fullWidth
+ loading={false}
+ onClick={openInBrowserStudio}
+ size="sm"
+ style={{padding: '7px 12px'}}
+ >
+ Open in Browser Studio
+ </PlainButton>
+ ) : null}
</div>
<div
className={styles.dragHandle}
diff --git a/packages/docs/src/pages/experimental_new/index.tsx b/packages/docs/src/pages/experimental_new/index.tsx
index b193e4f95d..fc5de1c672 100644
--- a/packages/docs/src/pages/experimental_new/index.tsx
+++ b/packages/docs/src/pages/experimental_new/index.tsx
@@ -5,7 +5,8 @@ import {
BrowserStudio,
createBlankTemplateProject,
} from '@remotion/browser-studio';
-import React from 'react';
+import {StudioProtocolInternals} from '@remotion/studio-protocol';
+import React, {useEffect, useState} from 'react';
const page: React.CSSProperties = {
backgroundColor: '#111111',
@@ -43,6 +44,85 @@ const standaloneCss = `
}
`;
+type InitialElementState =
+ | {type: 'none'}
+ | {type: 'invalid'}
+ | {
+ type: 'payload';
+ payload: NonNullable<
+ React.ComponentProps<typeof BrowserStudio>['initialElement']
+ >;
+ };
+
+const getInitialElementState = (): InitialElementState => {
+ const hasPayload = new URLSearchParams(window.location.hash.slice(1)).has(
+ 'remotion-browser-studio',
+ );
+ if (!hasPayload) {
+ return {type: 'none'};
+ }
+
+ const payload = StudioProtocolInternals.parseBrowserStudioHash(
+ window.location.hash,
+ );
+ if (payload === null) {
+ return {type: 'invalid'};
+ }
+
+ let sourceOrigin: string | null = null;
+ try {
+ sourceOrigin = document.referrer ? new URL(document.referrer).origin : null;
+ } catch {
+ sourceOrigin = null;
+ }
+
+ return {type: 'payload', payload: {payload, sourceOrigin}};
+};
+
+const BrowserStudioContent: React.FC<{
+ readonly browserStudioWorkspaceCommit: string;
+}> = ({browserStudioWorkspaceCommit}) => {
+ const [initialElementState] = useState(getInitialElementState);
+ const [project] = useState(createBlankTemplateProject);
+
+ useEffect(() => {
+ if (initialElementState.type === 'none') {
+ return;
+ }
+
+ window.history.replaceState(
+ null,
+ '',
+ `${window.location.pathname}${window.location.search}`,
+ );
+ }, [initialElementState.type]);
+
+ if (initialElementState.type === 'invalid') {
+ return <div style={fallback}>Invalid Browser Studio payload.</div>;
+ }
+
+ return (
+ <BrowserStudio
+ iframeSrc="/experimental_new/frame.html"
+ initialElement={
+ initialElementState.type === 'payload'
+ ? initialElementState.payload
+ : null
+ }
+ project={project}
+ readOnly={false}
+ remotionPackageSource={{
+ baseUrl: new URL(
+ `/__remotion_browser_studio_workspace__/commits/${browserStudioWorkspaceCommit}/`,
+ window.location.href,
+ ).href,
+ commit: browserStudioWorkspaceCommit,
+ type: 'workspace',
+ }}
+ />
+ );
+};
+
const NewRemotionProject = () => {
const {siteConfig} = useDocusaurusContext();
const browserStudioWorkspaceCommit =
@@ -60,18 +140,8 @@ const NewRemotionProject = () => {
<div style={page}>
<BrowserOnly fallback={<div style={fallback}>Loading...</div>}>
{() => (
- <BrowserStudio
- iframeSrc="/experimental_new/frame.html"
- project={createBlankTemplateProject()}
- readOnly={false}
- remotionPackageSource={{
- baseUrl: new URL(
- `/__remotion_browser_studio_workspace__/commits/${browserStudioWorkspaceCommit}/`,
- window.location.href,
- ).href,
- commit: browserStudioWorkspaceCommit,
- type: 'workspace',
- }}
+ <BrowserStudioContent
+ browserStudioWorkspaceCommit={browserStudioWorkspaceCommit}
/>
)}
</BrowserOnly>
diff --git a/packages/studio-protocol/src/browser-studio-link.ts b/packages/studio-protocol/src/browser-studio-link.ts
new file mode 100644
index 0000000000..66663d4bc1
--- /dev/null
+++ b/packages/studio-protocol/src/browser-studio-link.ts
@@ -0,0 +1,127 @@
+import type {StudioElementPayload} from './element-payload';
+import {parseStudioElementPayload} from './element-payload';
+import {isRecord} from './validation';
+
+const browserStudioHashKey = 'remotion-browser-studio';
+const defaultBrowserStudioEndpoint =
+ 'https://www.remotion.dev/experimental_new';
+const maxEncodedPayloadLength = 1_100_000;
+
+const toBase64Url = (value: string) => {
+ const bytes = new TextEncoder().encode(value);
+ let binary = '';
+ const chunkSize = 32_768;
+ for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+ binary += String.fromCharCode(
+ ...bytes.subarray(offset, offset + chunkSize),
+ );
+ }
+
+ return btoa(binary)
+ .replaceAll('+', '-')
+ .replaceAll('/', '_')
+ .replace(/=+$/, '');
+};
+
+const fromBase64Url = (value: string) => {
+ if (!/^[A-Za-z0-9_-]+$/.test(value)) {
+ return null;
+ }
+
+ try {
+ const base64 = value.replaceAll('-', '+').replaceAll('_', '/');
+ const padded = base64.padEnd(
+ base64.length + ((4 - (base64.length % 4)) % 4),
+ '=',
+ );
+ const binary = atob(padded);
+ const bytes = new Uint8Array(binary.length);
+ for (let index = 0; index < binary.length; index++) {
+ bytes[index] = binary.charCodeAt(index);
+ }
+
+ return new TextDecoder('utf-8', {fatal: true}).decode(bytes);
+ } catch {
+ return null;
+ }
+};
+
+export const makeBrowserStudioUrl = ({
+ endpoint,
+ payload,
+}: {
+ readonly endpoint: string | null;
+ readonly payload: StudioElementPayload;
+}) => {
+ if (parseStudioElementPayload(payload) === null) {
+ throw new TypeError('Invalid Element payload');
+ }
+
+ const url = new URL(endpoint ?? defaultBrowserStudioEndpoint);
+ if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+ throw new TypeError('Browser Studio endpoint must use HTTP or HTTPS');
+ }
+
+ const encoded = toBase64Url(
+ JSON.stringify({
+ payload,
+ type: 'remotion-browser-studio',
+ version: 1,
+ }),
+ );
+ if (encoded.length > maxEncodedPayloadLength) {
+ throw new TypeError('Browser Studio payload is too large');
+ }
+
+ url.hash = new URLSearchParams({[browserStudioHashKey]: encoded}).toString();
+ return url.toString();
+};
+
+export const parseBrowserStudioHash = (
+ hash: string,
+): StudioElementPayload | null => {
+ const encoded = new URLSearchParams(
+ hash.startsWith('#') ? hash.slice(1) : hash,
+ ).get(browserStudioHashKey);
+ if (
+ encoded === null ||
+ encoded.length === 0 ||
+ encoded.length > maxEncodedPayloadLength
+ ) {
+ return null;
+ }
+
+ const decoded = fromBase64Url(encoded);
+ if (decoded === null) {
+ return null;
+ }
+
+ try {
+ const envelope: unknown = JSON.parse(decoded);
+ if (
+ !isRecord(envelope) ||
+ envelope.type !== 'remotion-browser-studio' ||
+ envelope.version !== 1
+ ) {
+ return null;
+ }
+
+ return parseStudioElementPayload(envelope.payload);
+ } catch {
+ return null;
+ }
+};
+
+export const openInBrowserStudio = ({
+ endpoint,
+ payload,
+}: {
+ readonly endpoint: string | null;
+ readonly payload: StudioElementPayload;
+}) => {
+ if (typeof window === 'undefined') {
+ throw new Error('Browser Studio can only be opened in a browser');
+ }
+
+ window.open(makeBrowserStudioUrl({endpoint, payload}), '_blank', 'noopener');
+};
diff --git a/packages/studio-protocol/src/index.ts b/packages/studio-protocol/src/index.ts
index a77d671e3a..61c407c6cf 100644
--- a/packages/studio-protocol/src/index.ts
+++ b/packages/studio-protocol/src/index.ts
@@ -1,3 +1,8 @@
+import {
+ makeBrowserStudioUrl,
+ openInBrowserStudio,
+ parseBrowserStudioHash,
+} from './browser-studio-link';
import {
areComponentProps,
isComponentIdentifier,
@@ -79,8 +84,11 @@ export const StudioProtocolInternals = {
isComponentImportPath,
installInStudioWithDependencies,
isValidPublicLicenseKey,
+ makeBrowserStudioUrl,
makeDragData,
makeElementFileNameFromSlug,
+ openInBrowserStudio,
+ parseBrowserStudioHash,
parseDragData,
parseStudioElementPayload,
setLicenseKeyInStudio,
diff --git a/packages/studio-protocol/src/test/browser-studio-link.test.ts b/packages/studio-protocol/src/test/browser-studio-link.test.ts
new file mode 100644
index 0000000000..61f920f976
--- /dev/null
+++ b/packages/studio-protocol/src/test/browser-studio-link.test.ts
@@ -0,0 +1,58 @@
+import {expect, test} from 'bun:test';
+import {StudioProtocolInternals} from '..';
+import {createElementPayload} from '../element-payload';
+
+const payload = createElementPayload({
+ dependencies: [],
+ dimensions: {height: 180, width: 320},
+ displayName: 'Linked Element',
+ durationInFrames: 60,
+ installationMode: 'wrapped',
+ slug: 'linked-element',
+ sourceCode: 'export const LinkedElement = () => <div>Grüezi 👋</div>;',
+});
+
+test('round-trips a payload through the default Browser Studio URL', () => {
+ const url = StudioProtocolInternals.makeBrowserStudioUrl({
+ endpoint: null,
+ payload,
+ });
+ const parsedUrl = new URL(url);
+
+ expect(parsedUrl.origin).toBe('https://www.remotion.dev');
+ expect(parsedUrl.pathname).toBe('/experimental_new');
+ expect(url).not.toContain('Grüezi');
+ expect(
+ StudioProtocolInternals.parseBrowserStudioHash(parsedUrl.hash),
+ ).toEqual(payload);
+});
+
+test('preserves a configured Browser Studio endpoint', () => {
+ const url = StudioProtocolInternals.makeBrowserStudioUrl({
+ endpoint: 'https://studio.example.test/new?template=blank',
+ payload,
+ });
+ const parsedUrl = new URL(url);
+
+ expect(parsedUrl.origin).toBe('https://studio.example.test');
+ expect(parsedUrl.pathname).toBe('/new');
+ expect(parsedUrl.search).toBe('?template=blank');
+ expect(
+ StudioProtocolInternals.parseBrowserStudioHash(parsedUrl.hash),
+ ).toEqual(payload);
+});
+
+test('rejects malformed Browser Studio fragments and endpoints', () => {
+ expect(StudioProtocolInternals.parseBrowserStudioHash('')).toBe(null);
+ expect(
+ StudioProtocolInternals.parseBrowserStudioHash(
+ '#remotion-browser-studio=not%2Bbase64',
+ ),
+ ).toBe(null);
+ expect(() =>
+ StudioProtocolInternals.makeBrowserStudioUrl({
+ endpoint: 'file:///tmp/studio.html',
+ payload,
+ }),
+ ).toThrow('Browser Studio endpoint must use HTTP or HTTPS');
+});
diff --git a/packages/studio-shared/src/api-requests.ts b/packages/studio-shared/src/api-requests.ts
index 902a3c71b6..f6600f22db 100644
--- a/packages/studio-shared/src/api-requests.ts
+++ b/packages/studio-shared/src/api-requests.ts
@@ -1001,6 +1001,10 @@ export type ElementInstallSource =
type: 'studio-protocol';
origin: string;
}
+ | {
+ type: 'browser-studio-link';
+ origin: string | null;
+ }
| {
type: 'drag-and-drop';
};
diff --git a/packages/studio-shared/src/browser-studio-operations.ts b/packages/studio-shared/src/browser-studio-operations.ts
index 07cd6640ea..de89a7c6e7 100644
--- a/packages/studio-shared/src/browser-studio-operations.ts
+++ b/packages/studio-shared/src/browser-studio-operations.ts
@@ -1,3 +1,4 @@
+import type {ElementDragData} from '@remotion/studio-protocol';
import type {
ApplyCodemodRequest,
ApplyCodemodResponse,
@@ -62,6 +63,10 @@ export type DuplicateCompositionResponse =
};
export type BrowserStudioOperations = {
+ consumeInitialElement: () => {
+ element: ElementDragData['element'];
+ sourceOrigin: string | null;
+ } | null;
applyCodemod: (request: ApplyCodemodRequest) => Promise<ApplyCodemodResponse>;
deleteJsxNode: (
request: DeleteJsxNodeRequest,
diff --git a/packages/studio/src/components/Canvas.tsx b/packages/studio/src/components/Canvas.tsx
index 3149771a36..d169055ef8 100644
--- a/packages/studio/src/components/Canvas.tsx
+++ b/packages/studio/src/components/Canvas.tsx
@@ -62,7 +62,10 @@ import {EditorRulers} from './EditorRuler';
import {useIsRulerVisible} from './EditorRuler/use-is-ruler-visible';
import {getEffectDragData} from './effect-drag-and-drop';
import {prepareElementInstall} from './element-install-api';
-import {subscribeToElementInstallRequests} from './element-install-request';
+import {
+ enqueueElementInstallRequest,
+ subscribeToElementInstallRequests,
+} from './element-install-request';
import {ElementInstallConfirmation} from './ElementInstallConfirmation';
import {handleDrop} from './handle-drop';
import {
@@ -833,6 +836,37 @@ export const Canvas: React.FC<{
});
}, []);
+ useEffect(() => {
+ if (
+ !canInstallElements ||
+ compositionFile === null ||
+ currentCompositionId === null
+ ) {
+ return;
+ }
+
+ const initialElement =
+ getBrowserStudioOperations()?.consumeInitialElement() ?? null;
+ if (initialElement === null) {
+ return;
+ }
+
+ enqueueElementInstallRequest({
+ clientId: 'browser-studio',
+ compositionFile,
+ compositionId: currentCompositionId,
+ createdAt: Date.now(),
+ element: initialElement.element,
+ from: null,
+ id: crypto.randomUUID(),
+ position: null,
+ source: {
+ origin: initialElement.sourceOrigin,
+ type: 'browser-studio-link',
+ },
+ });
+ }, [canInstallElements, compositionFile, currentCompositionId]);
+
useEffect(() => {
if (
activeElementInstallRequest !== null ||
@@ -899,19 +933,23 @@ export const Canvas: React.FC<{
? dependency.name
: `${dependency.name}@${dependency.version}`,
);
+ const {source} = activeElementInstallRequest;
const sourceLabel =
- activeElementInstallRequest.source.type === 'studio-protocol'
- ? activeElementInstallRequest.source.origin
- : 'Unverified drag-and-drop payload';
+ source.type === 'studio-protocol'
+ ? source.origin
+ : source.type === 'browser-studio-link'
+ ? (source.origin ?? 'Unverified Browser Studio link')
+ : 'Unverified drag-and-drop payload';
+ const sourceIsUnverified =
+ source.type === 'drag-and-drop' ||
+ (source.type === 'browser-studio-link' && source.origin === null);
const accepted = await confirm({
title: 'Install Element',
message: (
<ElementInstallConfirmation
displayName={activeElementInstallRequest.element.displayName}
sourceLabel={sourceLabel}
- sourceIsUnverified={
- activeElementInstallRequest.source.type === 'drag-and-drop'
- }
+ sourceIsUnverified={sourceIsUnverified}
compositionId={activeElementInstallRequest.compositionId}
filePath={preflight.plan.filePath}
overwritesExistingFile={preflight.plan.expectedFileState.exists}
diff --git a/packages/studio/src/test/make-browser-studio-operations.ts b/packages/studio/src/test/make-browser-studio-operations.ts
index 0f36d33992..7c50862a11 100644
--- a/packages/studio/src/test/make-browser-studio-operations.ts
+++ b/packages/studio/src/test/make-browser-studio-operations.ts
@@ -9,6 +9,7 @@ export const makeBrowserStudioOperations = (
): BrowserStudioOperations => {
return {
applyCodemod: () => unusedOperation('applyCodemod'),
+ consumeInitialElement: () => null,
deleteJsxNode: () => unusedOperation('deleteJsxNode'),
deleteStaticFile: () => unusedOperation('deleteStaticFile'),
downloadProject: () => unusedOperation('downloadProject'),