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

Support authored preview playback with ordered client presentation (#11600)

[._.]/36a72e0ad89b
diff --git a/client/src/components/musicVideo/CompositionPreviewPlayer.jsx b/client/src/components/musicVideo/CompositionPreviewPlayer.jsx
index ff7a6d0115..85a6c14177 100644
--- a/client/src/components/musicVideo/CompositionPreviewPlayer.jsx
+++ b/client/src/components/musicVideo/CompositionPreviewPlayer.jsx
@@ -287,7 +287,7 @@ export default function CompositionPreviewPlayer({ project, audioUrl, seekReques
<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.frameUrl ? (
- <img alt="" src={preview.frameUrl} className="h-full w-full object-contain" />
+ <img ref={preview.imageRef} onLoad={preview.onFrameLoad} alt="" src={preview.frameUrl} className="h-full w-full object-contain" />
) : (
<p className="p-3 text-xs text-port-text-muted">{failed ? '' : wanted ? 'Building the preview…' : ''}</p>
)}
@@ -311,7 +311,7 @@ export default function CompositionPreviewPlayer({ project, audioUrl, seekReques
maxSec={duration || null}
onSeek={stopPlayback}
disabled={!preview.ready || failed}
- capture={() => (preview.frameUrl ? fetch(preview.frameUrl).then((res) => res.blob()) : Promise.resolve(null))}
+ capture={preview.captureFrame}
label={[project.name, shotIndex ? `Shot ${shotIndex}` : null].filter(Boolean).join(' · ')}
keys
/>
diff --git a/client/src/components/musicVideo/CompositionPreviewPlayer.test.jsx b/client/src/components/musicVideo/CompositionPreviewPlayer.test.jsx
index dfb3d297d9..62b61a1bad 100644
--- a/client/src/components/musicVideo/CompositionPreviewPlayer.test.jsx
+++ b/client/src/components/musicVideo/CompositionPreviewPlayer.test.jsx
@@ -1,3 +1,4 @@
+import { StrictMode } from 'react';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
@@ -52,6 +53,14 @@ const project = {
lyricCues: [{ id: 'l1', text: 'first line', startSec: 1, endSec: 3 }, { id: 'l2', text: 'second line', startSec: 3, endSec: 6 }],
};
+// happy-dom does not load blob images. Drive the actual element's load/decode
+// boundary explicitly, rather than treating a src assignment as presentation.
+const loadImage = async (image, decoding = Promise.resolve()) => {
+ Object.defineProperty(image, 'naturalWidth', { configurable: true, value: 1920 });
+ image.decode = vi.fn(() => decoding);
+ await act(async () => fireEvent.load(image));
+};
+
const opens = () => socket.emit.mock.calls.filter(([event]) => event === 'generated-preview:open');
beforeEach(() => {
@@ -406,12 +415,33 @@ describe('CompositionPreviewPlayer', () => {
expect(document.querySelector('iframe')).toBeNull();
});
+ it('keeps DOM-selected URLs live through StrictMode effect replay and releases them after unmount', async () => {
+ const create = vi.spyOn(URL, 'createObjectURL');
+ const release = URL.revokeObjectURL;
+ const revoke = vi.spyOn(URL, 'revokeObjectURL').mockImplementation((url) => {
+ for (const image of document.querySelectorAll('img')) {
+ expect(image.getAttribute('src')).not.toBe(url);
+ expect(image.currentSrc).not.toBe(url);
+ }
+ release(url);
+ });
+ const { container, unmount } = render(<StrictMode><CompositionPreviewPlayer project={project} audioUrl='/song.mp3' /></StrictMode>);
+ await loadImage(container.querySelector('img'));
+ const visible = container.querySelector('img').src;
+ expect(revoke).not.toHaveBeenCalledWith(visible);
+ unmount();
+ for (const { value: url } of create.mock.results) expect(revoke.mock.calls.filter(([value]) => value === url)).toHaveLength(1);
+ create.mockRestore();
+ revoke.mockRestore();
+ });
+
it('saves the docked preview frame on screen to the gallery', async () => {
const blob = new Blob(['jpeg'], { type: 'image/jpeg' });
const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue({ blob: async () => blob });
const { container } = render(<CompositionPreviewPlayer project={{ ...project, scenes: [{ sceneId: 'a', startSec: 0 }] }} audioUrl="/song.mp3" shotNav />);
await waitFor(() => expect(container.querySelector('img')?.getAttribute('src')).toBeTruthy());
const frameSrc = container.querySelector('img').getAttribute('src');
+ await loadImage(container.querySelector('img'));
await act(async () => { screen.getByRole('button', { name: /Save frame/ }).click(); });
expect(fetchSpy).toHaveBeenCalledWith(frameSrc);
expect(uploadGalleryImage).toHaveBeenCalledWith(blob, { silent: true });
@@ -474,6 +504,254 @@ describe('native composition playback', () => {
vi.spyOn(window, 'cancelAnimationFrame').mockImplementation(() => {});
return { play, pause, raf };
};
+ const presenter = async ({ shotNav = false } = {}) => {
+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+ const native = installNative();
+ const controls = media();
+ const create = vi.spyOn(URL, 'createObjectURL');
+ const revoke = vi.spyOn(URL, 'revokeObjectURL');
+ const view = render(<CompositionPreviewPlayer project={project} audioUrl='/song.mp3' shotNav={shotNav} />);
+ const image = view.container.querySelector('img');
+ await loadImage(image);
+ const baseline = image.src;
+ await act(async () => fireEvent.click(screen.getByRole('button', { name: 'Play' })));
+ expect(playbackMessages('play')).toHaveLength(1);
+ const anchor = playbackMessages('play')[0];
+ const callbacks = new Map();
+ let nextId = 1000;
+ controls.raf.mockImplementation((callback) => { callbacks.set(++nextId, callback); return nextId; });
+ window.cancelAnimationFrame.mockImplementation((id) => callbacks.delete(id));
+ const frame = (sequence, extra = {}) => {
+ act(() => receive('frame', { ...native.session(), playbackEpoch: anchor.epoch, sequence, data: btoa(`frame-${sequence}`), ...extra }));
+ return create.mock.results.at(-1).value;
+ };
+ const task = async () => { await act(async () => vi.advanceTimersByTime(0)); };
+ const batch = () => {
+ const snapshot = [...callbacks.values()];
+ callbacks.clear();
+ act(() => { for (const callback of snapshot) callback(performance.now()); });
+ };
+ const advance = async (ms) => { native.advance(ms); await act(async () => vi.advanceTimersByTime(ms)); };
+ return { ...view, ...controls, native, image, baseline, frame, task, batch, advance, create, revoke, callbacks };
+ };
+
+ it('presents a burst FIFO and keeps its source for observers on both sides of the acknowledgement RAF', async () => {
+ const p = await presenter();
+ const first = p.frame(1);
+ const second = p.frame(2);
+ const third = p.frame(3);
+ expect(p.image.src).toBe(p.baseline);
+ await p.task();
+ expect(p.image.src).toBe(first);
+ const observed = [];
+ requestAnimationFrame(() => observed.push(p.image.src));
+ await loadImage(p.image);
+ requestAnimationFrame(() => observed.push(p.image.src));
+ p.batch();
+ expect(observed).toEqual([first, first]);
+ expect(p.image.src).toBe(first);
+ expect(p.revoke).not.toHaveBeenCalledWith(first);
+ await p.task();
+ expect(p.image.src).toBe(second);
+ await loadImage(p.image);
+ expect(p.revoke).toHaveBeenCalledWith(first);
+ p.batch();
+ expect(p.image.src).toBe(second);
+ await p.task();
+ expect(p.image.src).toBe(third);
+ await loadImage(p.image);
+ p.batch();
+ fireEvent.click(screen.getByRole('button', { name: 'Pause' }));
+ expect(p.image.src).toBe(third);
+ });
+
+ it('routes an arrival between acknowledgement and promotion through the owned task', async () => {
+ const p = await presenter();
+ const first = p.frame(1);
+ await p.task();
+ await loadImage(p.image);
+ requestAnimationFrame(() => {
+ p.frame(2);
+ expect(p.image.src).toBe(first);
+ });
+ p.batch();
+ expect(p.image.src).toBe(first);
+ await p.task();
+ expect(p.image.src).not.toBe(first);
+ fireEvent.click(screen.getByRole('button', { name: 'Pause' }));
+ expect(p.image.src).toBe(first);
+ });
+
+ it('restores the decoded picture on pause, saves it, and rejects old decode/epoch work after a newer exact frame', async () => {
+ const p = await presenter({ shotNav: true });
+ const first = p.frame(1);
+ await p.task();
+ await loadImage(p.image);
+ p.batch();
+ const second = p.frame(2);
+ await p.task();
+ expect(p.image.src).toBe(second);
+ let finishDecode;
+ await loadImage(p.image, new Promise((resolve) => { finishDecode = resolve; }));
+ const blob = new Blob(['displayed']);
+ const fetch = vi.spyOn(globalThis, 'fetch').mockResolvedValue({ blob: async () => blob });
+ const uploadsBefore = uploadGalleryImage.mock.calls.length;
+ await act(async () => fireEvent.click(screen.getByRole('button', { name: /Save frame/ })));
+ expect(fetch).not.toHaveBeenCalled();
+ expect(uploadGalleryImage).toHaveBeenCalledTimes(uploadsBefore);
+ fireEvent.click(screen.getByRole('button', { name: 'Pause' }));
+ expect(p.image.src).toBe(first);
+ await act(async () => fireEvent.click(screen.getByRole('button', { name: /Save frame/ })));
+ expect(fetch).toHaveBeenCalledWith(first);
+ expect(uploadGalleryImage).toHaveBeenCalledTimes(uploadsBefore + 1);
+ expect(uploadGalleryImage).toHaveBeenLastCalledWith(blob, { silent: true });
+ const exact = socket.emit.mock.calls.filter(([event]) => event === 'generated-preview:seek').at(-1)[1];
+ const urls = p.create.mock.calls.length;
+ p.frame(3);
+ expect(p.create).toHaveBeenCalledTimes(urls);
+ act(() => receive('frame', { ...p.native.session(), generation: exact.generation, data: btoa('exact') }));
+ const latest = p.image.src;
+ await loadImage(p.image);
+ await act(async () => finishDecode());
+ p.batch();
+ await p.task();
+ expect(p.image.src).toBe(latest);
+ expect(p.revoke).toHaveBeenCalledWith(second);
+ await act(async () => fireEvent.click(screen.getByRole('button', { name: /Save frame/ })));
+ expect(fetch).toHaveBeenLastCalledWith(latest);
+ });
+
+ it('flushes old-look frames at visual control dispatch before the server responds', async () => {
+ const p = await presenter();
+ const first = p.frame(1);
+ await p.task();
+ await loadImage(p.image);
+ p.batch();
+ const candidate = p.frame(2);
+ await p.task();
+ let finishDecode;
+ await loadImage(p.image, new Promise((resolve) => { finishDecode = resolve; }));
+ const queued = p.frame(3);
+ p.rerender(<CompositionPreviewPlayer project={{ ...project, filmLook: { version: 1, preset: 'custom', grain: 0.4 } }} audioUrl='/song.mp3' />);
+ expect(socket.emit).toHaveBeenLastCalledWith('generated-preview:command', expect.objectContaining({ action: 'film-look' }));
+ expect(p.image.src).toBe(first);
+ const count = p.create.mock.calls.length;
+ p.frame(4);
+ expect(p.create).toHaveBeenCalledTimes(count);
+ await act(async () => finishDecode());
+ await p.task();
+ expect(p.image.src).toBe(first);
+ expect(p.revoke).toHaveBeenCalledWith(candidate);
+ expect(p.revoke).toHaveBeenCalledWith(queued);
+ // The same wire epoch still admits the server's control-resync signal.
+ const anchor = playbackMessages('play')[0];
+ await act(async () => receive('playback-state', { ...p.native.session(), ...anchor, action: 'sync', status: 'resync-required', reason: 'controls' }));
+ expect(playbackMessages('prepare')).toHaveLength(2);
+ });
+
+ it('fails visibly and pauses on queue overflow rather than discarding a source frame', async () => {
+ const p = await presenter();
+ p.frame(1);
+ p.frame(2);
+ p.frame(3);
+ p.frame(4);
+ expect(screen.getByRole('alert')).toHaveTextContent('presentation queue is full');
+ expect(p.image.src).toBe(p.baseline);
+ expect(p.pause).toHaveBeenCalled();
+ expect(screen.getByRole('button', { name: 'Play' })).toBeDisabled();
+ expect(socket.emit).toHaveBeenCalledWith('generated-preview:close', expect.objectContaining({ sessionId: p.native.session().sessionId }));
+ await p.task();
+ expect(p.image.src).toBe(p.baseline);
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it('enforces the receipt-to-ack deadline even when decode finishes but RAF is held', async () => {
+ const p = await presenter();
+ const first = p.frame(1);
+ await p.task();
+ await loadImage(p.image);
+ await p.advance(99);
+ expect(screen.queryByRole('alert')).toBeNull();
+ await p.advance(1);
+ expect(screen.getByRole('alert')).toHaveTextContent('presentation fell behind');
+ expect(p.image.src).toBe(first);
+ expect(p.pause).toHaveBeenCalled();
+ expect(p.callbacks.size).toBe(0);
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it('rechecks the deadline at acknowledgement when an overdue timer has not fired', async () => {
+ const p = await presenter();
+ p.frame(1);
+ await p.task();
+ await loadImage(p.image);
+ p.native.advance(100);
+ p.batch();
+ expect(screen.getByRole('alert')).toHaveTextContent('presentation fell behind');
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it('rechecks queued frame age in the promotion task before replacing an acknowledged picture', async () => {
+ const p = await presenter();
+ const first = p.frame(1);
+ await p.task();
+ await loadImage(p.image);
+ p.batch();
+ p.frame(2);
+ p.native.advance(100);
+ await p.task();
+ expect(screen.getByRole('alert')).toHaveTextContent('presentation fell behind');
+ expect(p.image.src).toBe(first);
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it('disposes a held DOM decode and its queued successors on unmount without rearming work', async () => {
+ const p = await presenter();
+ p.frame(1);
+ await p.task();
+ let finishDecode;
+ await loadImage(p.image, new Promise((resolve) => { finishDecode = resolve; }));
+ p.frame(2);
+ const all = p.create.mock.results.map(({ value }) => value);
+ p.unmount();
+ await act(async () => finishDecode());
+ p.batch();
+ await p.task();
+ for (const url of all) expect(p.revoke.mock.calls.filter(([value]) => value === url)).toHaveLength(1);
+ expect(p.callbacks.size).toBe(0);
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it('preserves the visible picture across reopen and revokes each owned URL once on unmount', async () => {
+ const p = await presenter();
+ p.frame(1);
+ await p.task();
+ await loadImage(p.image);
+ p.batch();
+ const retained = p.image.src;
+ p.frame(2);
+ socket.emit.mockImplementation(() => {});
+ p.rerender(<CompositionPreviewPlayer project={{ ...project, composition: { ...project.composition, document: { ...DOCUMENT, updatedAt: '2026-01-02' } } }} audioUrl='/song.mp3' />);
+ expect(opens()).toHaveLength(2);
+ expect(p.image.src).toBe(retained);
+ expect(p.revoke).not.toHaveBeenCalledWith(retained);
+ const replacement = { ...p.native.session(), requestId: opens()[1][1].requestId, sessionId: '10000000-0000-4000-8000-000000000002' };
+ act(() => {
+ receive('opened', replacement);
+ receive('frame', { ...replacement, generation: 0, data: btoa('replacement baseline') });
+ });
+ expect(p.image.src).not.toBe(retained);
+ expect(p.revoke).not.toHaveBeenCalledWith(retained);
+ await loadImage(p.image);
+ expect(p.revoke).toHaveBeenCalledWith(retained);
+ const all = p.create.mock.results.map(({ value }) => value);
+ p.unmount();
+ expect(p.image.isConnected).toBe(false);
+ for (const url of all) expect(p.revoke.mock.calls.filter(([value]) => value === url)).toHaveLength(1);
+ expect(p.callbacks.size).toBe(0);
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
afterEach(() => { vi.useRealTimers(); vi.restoreAllMocks(); });
it('waits for native preparation, anchors actual audio time, and sends bounded clock updates without frame seeks', async () => {
@@ -536,6 +814,8 @@ describe('native composition playback', () => {
const frame = (extra) => receive('frame', { ...native.session(), playbackEpoch: anchor.epoch, sequence: 1, data: btoa('native'), ...extra });
act(() => frame({}));
const image = container.querySelector('img');
+ await act(async () => new Promise((resolve) => setTimeout(resolve, 0)));
+ await loadImage(image);
const accepted = image.src;
act(() => frame({ data: btoa('duplicate') }));
expect(image.src).toBe(accepted);
diff --git a/client/src/hooks/useGeneratedPreview.js b/client/src/hooks/useGeneratedPreview.js
index d3ae592904..4f4586c504 100644
--- a/client/src/hooks/useGeneratedPreview.js
+++ b/client/src/hooks/useGeneratedPreview.js
@@ -22,6 +22,9 @@ const EMPTY = {
playbackResyncReason: '',
};
+const PRESENTATION_MAX_PENDING = 2;
+const PRESENTATION_MAX_AGE_MS = 100;
+
const newRequestId = () => uuidv4();
const decode = (chunk) => {
@@ -43,6 +46,10 @@ export default function useGeneratedPreview({ active, request, controls = null }
const openRef = useRef(null);
const lastSeek = useRef(null);
const frameUrl = useRef('');
+ const imageRef = useRef(null);
+ const decodedUrl = useRef('');
+ const frameUrls = useRef(new Map());
+ const presentation = useRef({ lease: 0, current: null, queue: [], blocked: true, task: 0, raf: 0, deadline: 0 });
const recordingUrl = useRef('');
const controlsRef = useRef(controls);
controlsRef.current = controls;
@@ -50,13 +57,167 @@ export default function useGeneratedPreview({ active, request, controls = null }
const requestKey = active && request ? JSON.stringify(request) : '';
const resume = useCallback(() => openRef.current?.(true), []);
+ const retireUrls = useCallback(() => {
+ const image = imageRef.current;
+ const retained = new Set([frameUrl.current, decodedUrl.current, image?.getAttribute('src'), image?.currentSrc]);
+ for (const [url, entry] of frameUrls.current) {
+ if (entry.retired && !retained.has(url)) {
+ URL.revokeObjectURL(url);
+ frameUrls.current.delete(url);
+ }
+ }
+ }, []);
+
+ const commitFrame = useCallback((entry) => {
+ const previous = frameUrls.current.get(frameUrl.current);
+ if (previous && previous !== entry) previous.retired = true;
+ entry.retired = false;
+ frameUrl.current = entry.url;
+ setState((prev) => frameUrl.current === entry.url ? { ...prev, frameUrl: entry.url } : prev);
+ retireUrls();
+ }, [retireUrls]);
+
+ const cancelPresentation = useCallback(() => {
+ const viewer = presentation.current;
+ viewer.lease += 1;
+ viewer.blocked = true;
+ clearTimeout(viewer.task);
+ clearTimeout(viewer.deadline);
+ cancelAnimationFrame(viewer.raf);
+ viewer.task = 0;
+ viewer.raf = 0;
+ viewer.deadline = 0;
+ for (const entry of [viewer.current, ...viewer.queue]) {
+ if (entry) entry.retired = true;
+ }
+ // A desired src is not yet a known decoded picture. Cancel its browser
+ // selection too, so a late decode cannot reveal a canceled playing frame.
+ if (viewer.current?.url === frameUrl.current && frameUrl.current !== decodedUrl.current) {
+ frameUrl.current = decodedUrl.current;
+ const image = imageRef.current;
+ if (image) {
+ if (decodedUrl.current) image.src = decodedUrl.current;
+ else image.removeAttribute('src');
+ }
+ if (mounted.current) setState((prev) => ({ ...prev, frameUrl: frameUrl.current }));
+ }
+ viewer.current = null;
+ viewer.queue = [];
+ retireUrls();
+ }, [mounted, retireUrls]);
+
const cancelPlayback = useCallback((current = pending.current) => {
+ cancelPresentation();
if (!current) return;
current.epoch += 1;
current.mode = 'exact';
- current.frameSequence = -1;
+ current.receivedSequence = -1;
+ current.presentedSequence = -1;
for (const finish of current.responses.values()) finish(null);
current.responses.clear();
+ }, [cancelPresentation]);
+
+ const failPresentation = useCallback((message) => {
+ const current = pending.current;
+ if (!mounted.current || !current || current.terminalError) return;
+ current.terminalError = true;
+ current.hasError = true;
+ cancelPlayback(current);
+ setState((prev) => ({ ...prev, status: 'error', ready: false, reason: message }));
+ if (socket.connected) socket.emit('generated-preview:close', { requestId: current.requestId, sessionId: current.sessionId });
+ }, [cancelPlayback, mounted]);
+
+ const liveFrame = useCallback((entry) => {
+ const current = pending.current;
+ return mounted.current && current === entry.owner && !current.terminalError
+ && entry.requestId === current.requestId && entry.sessionId === current.sessionId
+ && entry.epoch === current.epoch && current.mode === 'playing'
+ && entry.lease === presentation.current.lease && !presentation.current.blocked;
+ }, [mounted]);
+
+ const checkFrameAge = useCallback((entry) => {
+ if (performance.now() - entry.received < PRESENTATION_MAX_AGE_MS) return true;
+ failPresentation('Preview presentation fell behind. Retry the preview.');
+ return false;
+ }, [failPresentation]);
+
+ const watchPresentation = useCallback(() => {
+ const viewer = presentation.current;
+ clearTimeout(viewer.deadline);
+ viewer.deadline = 0;
+ const oldest = viewer.current && !viewer.current.acknowledged ? viewer.current : viewer.queue[0];
+ if (!oldest || !liveFrame(oldest)) return;
+ const watch = () => {
+ if (!liveFrame(oldest)) return;
+ const remaining = PRESENTATION_MAX_AGE_MS - (performance.now() - oldest.received);
+ if (remaining <= 0) { failPresentation('Preview presentation fell behind. Retry the preview.'); return; }
+ viewer.deadline = setTimeout(watch, remaining);
+ };
+ watch();
+ }, [failPresentation, liveFrame]);
+
+ const promoteFrame = useCallback(() => {
+ const viewer = presentation.current;
+ if (viewer.task || !viewer.current || viewer.current.published && !viewer.current.acknowledged) return;
+ const lease = viewer.lease;
+ // A task runs after the ENTIRE acknowledgement RAF batch. Never clear
+ // current in the RAF: an arriving socket frame must not bypass this task.
+ viewer.task = setTimeout(() => {
+ viewer.task = 0;
+ if (lease !== viewer.lease || viewer.blocked || !mounted.current) return;
+ const previous = viewer.current;
+ const next = previous.published ? viewer.queue[0] : previous;
+ if (!next || !liveFrame(next) || !checkFrameAge(next)) return;
+ if (previous.published) {
+ const image = imageRef.current;
+ if (!previous.acknowledged || !image?.isConnected || image.src !== previous.url || (image.currentSrc && image.currentSrc !== previous.url)) return;
+ viewer.queue.shift();
+ }
+ viewer.current = next;
+ next.published = true;
+ commitFrame(next);
+ watchPresentation();
+ }, 0);
+ }, [checkFrameAge, commitFrame, liveFrame, mounted, watchPresentation]);
+
+ const onFrameLoad = useCallback((event) => {
+ const image = event.currentTarget;
+ const url = image.currentSrc || image.src;
+ const entry = frameUrls.current.get(url);
+ if (!entry || entry.decoding || entry.decoded || frameUrl.current !== url || !image.naturalWidth) return;
+ entry.decoding = true;
+ Promise.resolve().then(() => image.decode()).then(() => {
+ entry.decoding = false;
+ if (!mounted.current || imageRef.current !== image || !image.isConnected || frameUrl.current !== url || image.src !== url || (image.currentSrc && image.currentSrc !== url)
+ || entry.lease !== presentation.current.lease || pending.current !== entry.owner || entry.owner.terminalError
+ || entry.native && !liveFrame(entry)) { retireUrls(); return; }
+ if (entry.native && !checkFrameAge(entry)) return;
+ entry.decoded = true;
+ decodedUrl.current = url;
+ retireUrls();
+ if (!entry.native) return;
+ const viewer = presentation.current;
+ viewer.raf = requestAnimationFrame(() => {
+ viewer.raf = 0;
+ if (!liveFrame(entry) || viewer.current !== entry || imageRef.current !== image || !image.isConnected || image.src !== url || (image.currentSrc && image.currentSrc !== url) || !checkFrameAge(entry)) return;
+ entry.acknowledged = true;
+ entry.owner.presentedSequence = entry.sequence;
+ watchPresentation();
+ promoteFrame();
+ });
+ }).catch(() => {
+ entry.decoding = false;
+ if (entry.native && liveFrame(entry)) failPresentation('Preview image could not be decoded. Retry the preview.');
+ else retireUrls();
+ });
+ }, [checkFrameAge, failPresentation, liveFrame, mounted, promoteFrame, retireUrls, watchPresentation]);
+
+ const captureFrame = useCallback(() => {
+ const image = imageRef.current;
+ const entry = frameUrls.current.get(decodedUrl.current);
+ return image?.isConnected && image.naturalWidth && entry?.decoded
+ && image.src === entry.url && (!image.currentSrc || image.currentSrc === entry.url)
+ ? fetch(entry.url).then((response) => response.blob()) : Promise.resolve(null);
}, []);
const seek = useCallback((t, { playing = false } = {}) => {
@@ -85,6 +246,7 @@ export default function useGeneratedPreview({ active, request, controls = null }
const command = useCallback((action, extra = {}) => {
const current = pending.current;
if (!socket.connected || !current?.sessionId) return;
+ if (action === 'film-look' || action === 'title-card') cancelPresentation();
socket.emit('generated-preview:command', {
requestId: current.requestId,
sessionId: current.sessionId,
@@ -92,7 +254,7 @@ export default function useGeneratedPreview({ active, request, controls = null }
action,
...extra,
});
- }, []);
+ }, [cancelPresentation]);
const preparePlayback = useCallback(async (t) => {
const current = pending.current;
@@ -156,6 +318,7 @@ export default function useGeneratedPreview({ active, request, controls = null }
if (!socket.connected || !current?.playback || current.offset === null) return;
if (action === 'play' ? current.mode !== 'prepared' : current.mode !== 'playing') return;
current.mode = 'playing';
+ if (action === 'play') presentation.current.blocked = false;
lastSeek.current = { t, playing: false };
socket.emit('generated-preview:playback', {
requestId: current.requestId, sessionId: current.sessionId,
@@ -199,7 +362,7 @@ export default function useGeneratedPreview({ active, request, controls = null }
stoppedStatus = null;
requestId = newRequestId();
const openControls = { look: controlsRef.current?.look ?? null, card: controlsRef.current?.card ?? null };
- pending.current = { requestId, sessionId: null, generation: 0, generationFloor: 0, completedGeneration: -1, controls: openControls, epoch: 0, sequence: 0, probeId: 0, frameSequence: -1, mode: 'exact', offset: null, playback: false, responses: new Map() };
+ pending.current = { requestId, sessionId: null, generation: 0, generationFloor: 0, completedGeneration: -1, controls: openControls, epoch: 0, sequence: 0, probeId: 0, receivedSequence: -1, presentedSequence: -1, mode: 'exact', offset: null, playback: false, responses: new Map() };
if (mounted.current) setState((prev) => ({ ...prev, status: 'opening', sessionId: null, ready: false, reason: '', lastEvent: null, playback: false, playbackReason: '' }));
socket.emit('generated-preview:open', {
requestId,
@@ -249,8 +412,8 @@ export default function useGeneratedPreview({ active, request, controls = null }
const current = pending.current;
if (current.terminalError) return;
if (payload.playbackEpoch !== undefined) {
- if (current.mode !== 'playing' || payload.playbackEpoch !== current.epoch || !Number.isInteger(payload.sequence) || payload.sequence <= current.frameSequence) return;
- current.frameSequence = payload.sequence;
+ if (presentation.current.blocked || current.mode !== 'playing' || payload.playbackEpoch !== current.epoch || !Number.isInteger(payload.sequence) || payload.sequence <= current.receivedSequence) return;
+ current.receivedSequence = payload.sequence;
} else if (current.capable) {
if (current.mode === 'legacy-playing') {
// A completed frame can trail newer playing requests. Display it
@@ -265,15 +428,28 @@ export default function useGeneratedPreview({ active, request, controls = null }
} catch {
return;
}
- const previous = frameUrl.current;
- frameUrl.current = url;
- if (previous) URL.revokeObjectURL(previous);
- if (!mounted.current) return;
- // Screencasting can start before the open acknowledgement. Show its
- // frame, but commands need the session identity established by opened.
- const opened = !!pending.current.sessionId;
+ const entry = { url, owner: current, requestId: current.requestId, sessionId: current.sessionId,
+ epoch: current.epoch, lease: presentation.current.lease, sequence: payload.sequence,
+ native: payload.playbackEpoch !== undefined, received: performance.now() };
+ frameUrls.current.set(url, entry);
+ if (entry.native) {
+ const viewer = presentation.current;
+ if (!viewer.current) viewer.current = entry;
+ else if (viewer.queue.length < PRESENTATION_MAX_PENDING) viewer.queue.push(entry);
+ else {
+ entry.retired = true;
+ failPresentation('Preview presentation queue is full. Retry the preview.');
+ return;
+ }
+ promoteFrame();
+ watchPresentation();
+ return;
+ }
+ if (!mounted.current) { entry.retired = true; retireUrls(); return; }
+ const opened = !!current.sessionId;
if (opened) { stoppedStatus = null; current.hasError = false; }
- setState((prev) => ({ ...prev, frameUrl: url, ...(opened ? { status: 'ready', ready: true } : {}) }));
+ commitFrame(entry);
+ setState((prev) => ({ ...prev, ...(opened ? { status: 'ready', ready: true } : {}) }));
};
const onUnavailable = (payload) => {
if (!mine(payload) || !mounted.current) return;
@@ -388,7 +564,7 @@ export default function useGeneratedPreview({ active, request, controls = null }
};
// `request` is read for the payload; requestKey is its identity.
// eslint-disable-next-line react-hooks/exhaustive-deps
- }, [requestKey, mounted, seek, cancelPlayback]);
+ }, [requestKey, mounted, seek, cancelPlayback, commitFrame, failPresentation, promoteFrame, retireUrls, watchPresentation]);
// Reconcile against what this session actually received. Controls can change
// while its open request is in flight; readiness must not mark those edits sent.
@@ -404,9 +580,18 @@ export default function useGeneratedPreview({ active, request, controls = null }
}, [controls, state.status, command, requestKey]);
useEffect(() => () => {
- if (frameUrl.current) URL.revokeObjectURL(frameUrl.current);
+ // StrictMode replays effects with the DOM still connected. Only actual
+ // DOM retirement permits releasing its selected picture in that cleanup.
+ const image = imageRef.current;
+ const selected = new Set(image?.isConnected ? [image.getAttribute('src'), image.currentSrc] : []);
+ for (const [url, entry] of frameUrls.current) {
+ entry.retired = true;
+ if (selected.has(url)) continue;
+ URL.revokeObjectURL(url);
+ frameUrls.current.delete(url);
+ }
if (recordingUrl.current) URL.revokeObjectURL(recordingUrl.current);
}, []);
- return { ...state, seek, command, resume, preparePlayback, startPlayback, syncPlayback, pausePlayback };
+ return { ...state, seek, command, resume, preparePlayback, startPlayback, syncPlayback, pausePlayback, imageRef, onFrameLoad, captureFrame };
}
diff --git a/docs/HTML_COMPOSITIONS.md b/docs/HTML_COMPOSITIONS.md
index d721bd4012..0536e20cce 100644
--- a/docs/HTML_COMPOSITIONS.md
+++ b/docs/HTML_COMPOSITIONS.md
@@ -566,6 +566,86 @@ 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/`.
+During cooperative playback, the viewer presents valid images in arrival order
+with at most two pending images and one presenting image. Actual visible-image
+decode and one animation-frame opportunity precede the next presentation task.
+Queued images cannot replace that current image early. A 100 ms receipt-to-
+acknowledgement deadline and queue bound stop the preview clearly when the
+consumer cannot keep up; intermediate images are never silently discarded.
+This adds bounded viewer latency without changing the source/audio clock.
+Pause, scrub, visual controls and session changes retire pending work; exact
+images keep their generation rules, and Save frame uses the actual known
+decoded current image. URLs retire after their DOM references. Native cadence,
+lag and drift still require measured evidence for the particular source.
+
+### Optional authored complete-frame playback
+
+A custom music-video document can explicitly supply a cooperative producer
+without PortOS rewriting its engine. Ship `preview-playback.json` beside
+`index.html`, containing exactly:
+
+```json
+{"version":1,"contract":"portos-complete-frame-v1"}
+```
+
+Before document readiness, install an own `previewPlayback` data property on
+`portosComposition`. Its own data properties declare `version: 1`, `fps: 30`,
+`presentation: 'atomic-canvas-v1'`, and `mediaTiming: 'staged-output-v1'`, and
+provide the methods below. PortOS snapshots and binds the methods with their
+original receiver once. Replacing the public API later cannot redirect calls.
+
+| Method | Input | Successful result |
+| --- | --- | --- |
+| `clock()` | None | Synchronous, finite, nonnegative, nondecreasing `performance.now()` milliseconds |
+| `prepare(input)` | `{epoch, sequence, t}` | `{epoch, sequence, status:'prepared', t}` with the requested values |
+| `play(input)` | `{epoch, sequence, t, workerTime}` | `{epoch, sequence, status:'playing'}` |
+| `sync(input)` | `{epoch, sequence, t, workerTime}` | `{epoch, sequence, status:'accepted', driftSec?}`; optional drift is finite |
+| `pause(input)` | `{epoch}` | `{epoch, status:'paused'}` after all owned work retires |
+| `dispose()` | None | Release author-owned resources; host closure also destroys the owned page |
+
+Replies have no extra fields. `play` may instead return `resync-required`,
+`superseded` or `stale`; `sync` may return `resync-required` or `stale`, retaining
+the same correlation fields. A current operation that reports stale/superseded
+requests synchronization. The host's bounded resynchronization policy still
+applies. Operation sequence and captured-frame sequence are separate values.
+
+The producer owns atomic visible commits: finish source/font/image preparation
+and every asynchronous drawing dependency before publishing the complete frame
+in one synchronous task. Retained callbacks must not mutate the visible document
+after publication or pause. Honor the request's epoch/sequence and cancel stale
+work before it can publish. Use the staged `PORTOS_MV` media timebase, applying
+rate/lead transformations once; keep original song time separate from quantized
+or held drawing time. Advance the film-look and title finishing hooks from song
+time, preserve lyric stacking and pointer behavior, and keep exact `seek(t)`
+consistent with paused/scrubbed frames and the final renderer.
+
+The synthetic reference in `server/test/authoredPreviewFixture.js` packages its
+own scheduler and complete-frame bridge, with asynchronous source preparation
+and a deliberately limited, checked source mapping.
+
+Declaration and handshake are an author's promise of this behavior. They do not
+prove arbitrary JavaScript purity, isolate same-realm canvas/DOM effects, certify
+untracked embedded media, or establish content throughput. The host enforces
+method shape, correlation, clock checks, queue ordering and deadlines: clock,
+play and sync have 1.5 seconds; prepare and pause have 3 seconds. It gates frames
+immediately before retirement. An invoked producer that fails, exceeds its
+deadline or returns an invalid reply loses the owned page; uncertain work never
+continues into exact rendering on that page. An explicit reopen is a new session.
+
+Missing declarations preserve the existing canonical recognition/exact path.
+Present malformed, unknown or incomplete contracts retain exact fallback without
+source rewriting. Eligibility still requires the verified Chromium 155+ capture
+baseline, native video-frame request/cancel callbacks, and trusted finite selected
+video cadence above 10 fps. This does not establish 30 fps for every source or
+document, 1080p/4K decoding, GPU presentation, or audible A/V synchronization.
+
+Existing generated version-1 documents, spatial engines and older/customized
+engines are not automatically opted in. Generated hosts currently ignore section
+Promise returns; changing that would change historical semantics. Future
+generation needs a new immutable candidate under an explicit authoring contract,
+then revision-bound review and acceptance. Custom authors implement the API and
+re-import; historical engine adoption remains an explicit version change.
+
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
diff --git a/docs/plans/2026-10-15-authored-preview-playback-contract.md b/docs/plans/2026-10-15-authored-preview-playback-contract.md
new file mode 100644
index 0000000000..d5835f977b
--- /dev/null
+++ b/docs/plans/2026-10-15-authored-preview-playback-contract.md
@@ -0,0 +1,139 @@
+# Authored complete-frame preview playback
+
+## Context and authority
+
+Issue #11221 remains open after #11591. Current main is
+`0ea9b0cb2505a5f30087edfa74f84881421921e2`. The canonical starter has a narrowly
+recognized producer; generated, customized and older documents retain exact
+seek playback. The user authorized continuing the playback/capture redesign,
+independent design review and bounded implementation while preserving arbitrary
+document semantics and exact final fidelity. Deployment, restart, provider calls,
+package installation and previously held worktree deletion remain excluded.
+
+Independent design review approved the custom opt-in foundation below before
+implementation. It does not approve automatic generated-document admission,
+source-purity inference, CSP changes or broader source-resolution claims.
+
+## Compatibility boundary
+
+Keep existing document bytes and the final renderer unchanged. Existing
+`seek(t)` behavior remains authoritative for pause, scrub and export. Today's
+generated hosts ignore section-function return values; making them await
+Promises or revoking retained contexts would change existing semantics.
+
+Add an optional `preview-playback.json` declaration with exactly
+`{"version":1,"contract":"portos-complete-frame-v1"}`. Only an explicitly
+declared staged document may use the authored lane. Missing declarations leave
+the canonical recognizer and legacy exact path unchanged. Present malformed,
+unknown or unsupported declarations decline the authored lane without rewriting
+source. Do not synthesize declarations for existing generated manifests or old
+engines. The immutable document pointer and frozen staged asset snapshot provide
+revision identity; a declaration or digest does not prove JavaScript purity.
+
+Future generated adoption requires a new immutable candidate under a deliberate
+authoring contract, reviewed before selection. Customized/imported documents
+implement the API and re-import. Known historical engine adoption remains an
+explicit version change. Spatial rendering needs its own cooperative producer
+and parity evidence. Stronger isolation through workers/alternate realms is a
+separate design; the current CSP remains unchanged.
+
+## Runtime and host contract
+
+The declared page supplies `portosComposition.previewPlayback` before document
+readiness. It declares version 1, 30 fps, `atomic-canvas-v1` presentation and
+`staged-output-v1` timing, and supplies own callable `clock`, `prepare`, `play`,
+`sync`, `pause` and `dispose` methods. The handshake copies and binds method
+references and their receiver once into a host-owned immutable bridge at
+`globalThis.__portosAuthoredPreviewPlayback`. Later API replacement must not
+retarget dispatch. Unsupported plain shape is a clean exact fallback. Throwing
+or unsettled inspection closes the owned page under a host deadline.
+
+Retain the verified Chromium 155+ capture baseline, native request/cancel video
+frame callbacks and trusted finite selected-video cadence above 10 fps. These
+are eligibility checks, not proof of 30 fps authored content or arbitrary codecs.
+
+Host RPCs use method-specific deadlines and strict method/status/epoch/sequence
+responses. Clocks are finite monotonic milliseconds in the renderer's
+`performance.now()` timebase. Prepare, play and sync echo the request epoch and
+sequence; pause confirms its epoch only after all owned work has retired.
+Transport capture sequence stays independent of authored operation sequence.
+
+Gate the native stream synchronously when pause, control, cancellation or failure
+arrives. Exact seeks and controls wait for successful retirement through the
+existing queue. Once an invoked producer times out, rejects or violates the
+response contract, close the owned page before any exact reuse; a timeout race
+does not cancel authored Promises. A fresh explicit reopen is a new session.
+
+The author owns complete atomic visible publication, resource readiness,
+song/draw/source timing, holds, scene transitions, lyric/finishing order and
+stale-lease suppression. Background mutations after a commit or pause violate
+that promise. The bound bridge provides dispatch integrity and host lifecycle
+guards, not same-realm isolation or proof that arbitrary pixels are complete.
+
+## Verification and acceptance
+
+- Exercise declaration and runtime admission through the public preview-open
+ boundary: absent, malformed, unknown, incomplete, unsupported browser/cadence,
+ and correctly bound implementation. Preserve original source bytes.
+- Exercise real registered socket handlers for held prepare/play/pause, wrong
+ epoch/sequence/status, nonfinite/regressing clocks, runtime errors/deadlines,
+ immediate frame gating, control ordering and late completion after close.
+- Verify method and receiver replacement cannot redirect the bound producer.
+- Verify an undeclared asynchronous custom document retains its exact seek
+ behavior and generated version-1 documents are never automatically admitted.
+- Use a real imported opt-in custom document with asynchronous preparation and
+ atomic publication through the actual socket and React player. Measure distinct
+ intrinsic content at wire, hook, decode and one-RAF boundaries, including scene
+ transitions, cancellation, pause/resume and exact paused/final PNG parity.
+ Retain original warmup, cadence, quality and drift requirements.
+- State input dimensions/codec and output dimensions/quality for every run. The
+ earlier canonical 640×360 input result establishes no 1080p/4K decoding or
+ arbitrary-document/GPU performance guarantee.
+- Complete independent source/result review, focused checks, client build when
+ affected, pregate before every push, draft PR and required exact-head CI.
+ Keep #11221 open while generated and untouched legacy paths remain.
+
+## Presentation ordering after native evidence
+
+A bounded native attempt delivered 89 consecutive source images through wire,
+hook acceptance and actual image decode in its first three-second window, but
+only 80 remained current through the independent one-RAF observation. The nine
+missing observations were interior images followed by another image about
+12–17 ms later. Immediate source replacement and URL revocation can supersede a
+decoded image before that opportunity. The entire failed attempt and positive
+owned cleanup were retained; later passing windows do not replace this failure.
+
+Independent design review approved a native-playback FIFO with two pending
+images and one presenting image. Validate request/session/epoch/received sequence
+before enqueueing; track presented sequence separately. The actual visible
+image's load, decode and current-source check precede a lease-checked one-RAF
+acknowledgement. Keep the presentation slot occupied through acknowledgement,
+then promote its successor in an owned cancelable timer task. Every successor,
+including a new arrival after acknowledgement, follows that task. A synchronous
+or Promise-microtask promotion can precede peer RAF callbacks; an additional RAF
+would cap a 60 Hz consumer at approximately 30 frames/s with no recovery headroom.
+The [HTML rendering model](https://html.spec.whatwg.org/multipage/webappapis.html#update-the-rendering)
+and [RAF callback iteration](https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#run-the-animation-frame-callbacks)
+explain this task boundary. It provides an RAF opportunity, not hardware paint
+proof; the independent actual-player observation remains the acceptance gate.
+
+Receipt-to-acknowledgement has a 100 ms deadline. Recheck identity, source,
+lease and age at acknowledgement and promotion. Overflow or excess age closes
+visibly through the existing error/audio-stop path; never drop an intermediate
+image silently. This adds bounded presentation latency, while the original
+end-to-end lag, ahead, drift, quality and cadence criteria stay unchanged.
+
+Pause, seek, prepare, visual-control dispatch, disconnect and unmount retire
+pending work immediately. Keep or restore the last known decoded current image
+when canceling an unfinished candidate. Exact/legacy frames retain their
+existing generation rules and bypass this native FIFO. Preserve a current image
+across a reopen until replacement, revoke URLs only after the DOM retires them,
+and capture the actual known decoded image for Save frame. Old decode, RAF or
+timer continuations cannot advance another intent or redirect capture.
+
+Public rendered regressions must cover burst order, deferred decode, peer
+observers before and after acknowledgement in one RAF batch, a new arrival
+before the promotion task, pause/control/epoch races, overflow/age failures and
+exactly-once URL cleanup. Freeze the updated source and independently review a
+fresh native package before another run. No threshold, warmup, window, input or
+output-quality relaxation is authorized by this design.
diff --git a/server/lib/README.md b/server/lib/README.md
index 4c9ff27b1d..b9de0ab28e 100644
--- a/server/lib/README.md
+++ b/server/lib/README.md
@@ -35,7 +35,7 @@ The barrel `server/lib/index.js` is a machine-checkable enumeration of every pub
| `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`. |
-| `generatedPreviewPlaybackSchema.js` | Strict optional generated-preview clock, preparation, playback-anchor and pause message contracts; legacy open and seek payloads remain unchanged. |
+| `generatedPreviewPlaybackSchema.js` | Strict optional generated-preview clock, preparation, playback-anchor and pause message contracts, plus authored-producer reply contracts and private bridge constants; legacy open and seek payloads remain unchanged. |
| `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. |
diff --git a/server/lib/generatedPreviewPlaybackSchema.js b/server/lib/generatedPreviewPlaybackSchema.js
index 3458f51d7c..a821608c9a 100644
--- a/server/lib/generatedPreviewPlaybackSchema.js
+++ b/server/lib/generatedPreviewPlaybackSchema.js
@@ -1,6 +1,9 @@
/** Optional preview clock/playback messages. Legacy open and seek stay unchanged. */
import { z } from 'zod';
+export const AUTHORED_PREVIEW_PLAYBACK_TARGET = '__portosAuthoredPreviewPlayback';
+export const AUTHORED_PREVIEW_HANDSHAKE_MS = 1500;
+
const identity = {
requestId: z.string().uuid(), sessionId: z.string().uuid(),
};
@@ -16,3 +19,15 @@ export const generatedPreviewPlaybackSchema = z.discriminatedUnion('action', [
z.object({ ...identity, action: z.literal('pause'), epoch: z.number().int().nonnegative(), generation: z.number().int().nonnegative(), t: z.number().min(0).max(86400) }).strict(),
]);
+
+// Authored producers opt into strict method replies. Canonical adapters retain
+// their existing responses; these schemas are only applied after authored calls.
+const authoredEpoch = { epoch: z.number().int().nonnegative() };
+const authoredOperation = { ...authoredEpoch, sequence: z.number().int().nonnegative() };
+export const authoredPreviewPlaybackReplies = {
+ clock: z.number().finite().nonnegative(),
+ prepare: z.object({ ...authoredOperation, status: z.literal('prepared'), t: z.number().finite().min(0).max(86400) }).strict(),
+ play: z.object({ ...authoredOperation, status: z.enum(['playing', 'resync-required', 'superseded', 'stale']) }).strict(),
+ sync: z.object({ ...authoredOperation, status: z.enum(['accepted', 'resync-required', 'stale']), driftSec: z.number().finite().optional() }).strict(),
+ pause: z.object({ ...authoredEpoch, status: z.literal('paused') }).strict(),
+};
diff --git a/server/services/generatedPreview/cooperativePlayback.js b/server/services/generatedPreview/cooperativePlayback.js
index 5516ecfd48..56e30ee66c 100644
--- a/server/services/generatedPreview/cooperativePlayback.js
+++ b/server/services/generatedPreview/cooperativePlayback.js
@@ -2,16 +2,17 @@
* Optional document playback. Exact seeks and native capture lifetimes share
* one queue; only the page's cooperative producer advances playing frames.
*/
-import { generatedPreviewPlaybackSchema as playbackSchema } from '../../lib/generatedPreviewPlaybackSchema.js';
+import { AUTHORED_PREVIEW_HANDSHAKE_MS, AUTHORED_PREVIEW_PLAYBACK_TARGET, authoredPreviewPlaybackReplies, generatedPreviewPlaybackSchema as playbackSchema } from '../../lib/generatedPreviewPlaybackSchema.js';
export { playbackSchema };
+const AUTHORED_METHOD_MS = { clock: AUTHORED_PREVIEW_HANDSHAKE_MS, prepare: 3000, play: 1500, sync: 1500, pause: 3000 };
const DRAIN_MS = 1500;
const START_FENCE_MS = 750;
-const nativeCall = (page, method, args = {}) => page.evaluate(
+const canonicalCall = (page, method, args = {}) => page.evaluate(
`globalThis.portosComposition.previewPlayback.${method}(${JSON.stringify(args)})`,
);
-export function createCooperativePlayback(session, { seekPage, capture, emitFrame, fail, closeSession }) {
+export function createCooperativePlayback(session, { seekPage, capture, emitFrame, fail, closeSession, authored = false }) {
let tail = Promise.resolve();
let intent = 0;
let epoch = 0;
@@ -26,6 +27,8 @@ export function createCooperativePlayback(session, { seekPage, capture, emitFram
let controlRevision = 0;
let exactBarrier = 0;
let resyncEpoch = null;
+ let lastClock = -1;
+ const pendingCalls = new Set();
const enqueue = (operation) => {
const result = tail.catch(() => {}).then(() => closed ? undefined : operation());
@@ -47,6 +50,54 @@ export function createCooperativePlayback(session, { seekPage, capture, emitFram
closeSession(session.id, 'playback-failed').catch(() => {});
};
+ const nativeCall = async (method, args = {}) => {
+ if (!authored) return canonicalCall(session.page, method, args);
+ if (closed || session.closed) throw new Error('Preview closed');
+ const startedAt = performance.now();
+ const timeoutMs = AUTHORED_METHOD_MS[method];
+ let timer;
+ let rejectClosed;
+ const canceled = new Promise((_, reject) => { rejectClosed = reject; });
+ pendingCalls.add(rejectClosed);
+ const invocation = `globalThis.${AUTHORED_PREVIEW_PLAYBACK_TARGET}.${method}(${JSON.stringify(args)})`;
+ // CDP awaits returned Promises, so enforce the synchronous clock contract
+ // inside the renderer before the transport can assimilate a thenable.
+ const source = method === 'clock'
+ ? `(() => { const value = ${invocation}; if (value && typeof value.then === 'function') throw new Error('Authored preview clock must be synchronous'); return value; })()`
+ : invocation;
+ try {
+ const value = await Promise.race([
+ Promise.resolve().then(() => {
+ if (closed || session.closed) throw new Error('Preview closed');
+ return session.page.evaluate(source);
+ }),
+ canceled,
+ new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`Authored preview ${method} timed out`)), timeoutMs); }),
+ ]);
+ // Overdue timers can run after a CDP response microtask. Elapsed time is
+ // authoritative even when the response wins that event-loop race.
+ if (performance.now() - startedAt >= timeoutMs) throw new Error(`Authored preview ${method} timed out`);
+ const parsed = authoredPreviewPlaybackReplies[method].safeParse(value);
+ if (!parsed.success) throw new Error(`Authored preview ${method} returned an invalid response`);
+ const result = parsed.data;
+ if (method === 'clock') {
+ if (result < lastClock) throw new Error('Authored preview clock regressed');
+ lastClock = result;
+ } else if (result.epoch !== args.epoch || ('sequence' in args && result.sequence !== args.sequence) || (method === 'prepare' && result.t !== args.t)) {
+ throw new Error(`Authored preview ${method} response did not match its request`);
+ }
+ return result;
+ } catch (error) {
+ // A timed-out author Promise is still running. Close before any queued
+ // exact seek or control can reuse that uncertain page.
+ terminate(error);
+ throw error;
+ } finally {
+ clearTimeout(timer);
+ pendingCalls.delete(rejectClosed);
+ }
+ };
+
async function stopStream() {
const previous = stream;
if (!previous) return;
@@ -76,7 +127,7 @@ export function createCooperativePlayback(session, { seekPage, capture, emitFram
async function quiesce() {
gate();
if (stream) stream.draining = true;
- await nativeCall(session.page, 'pause', { epoch });
+ await nativeCall('pause', { epoch });
await stopStream();
}
@@ -168,7 +219,7 @@ export function createCooperativePlayback(session, { seekPage, capture, emitFram
const handle = (input) => {
if (input.requestId !== session.requestId) return Promise.resolve();
if (input.action === 'clock') return enqueue(async () => {
- const workerTime = await nativeCall(session.page, 'clock');
+ const workerTime = await nativeCall('clock');
reply({ action: 'clock', probeId: input.probeId, clientTime: input.clientTime, workerTime });
});
if (input.action === 'pause') {
@@ -194,7 +245,7 @@ export function createCooperativePlayback(session, { seekPage, capture, emitFram
if (current !== intent) return;
await seekPage(session, input.t, false);
if (current !== intent) return;
- const prepared = await nativeCall(session.page, 'prepare', { epoch: input.epoch, t: input.t });
+ const prepared = await nativeCall('prepare', { epoch: input.epoch, ...(authored ? { sequence: input.sequence } : {}), t: input.t });
if (current !== intent || revision !== controlRevision || prepared?.status === 'superseded') return;
const data = await capture(session.page);
if (current !== intent || revision !== controlRevision || closed) return;
@@ -214,9 +265,9 @@ export function createCooperativePlayback(session, { seekPage, capture, emitFram
if (input.action === 'play') {
if (mode !== 'prepared') return;
mode = 'starting';
- const result = await nativeCall(session.page, 'play', { epoch: input.epoch, t: input.t, workerTime: input.workerTime, sequence: input.sequence });
+ const result = await nativeCall('play', { epoch: input.epoch, t: input.t, workerTime: input.workerTime, sequence: input.sequence });
if (current !== intent || revision !== controlRevision || mode !== 'starting' || closed) return;
- if (result?.status === 'resync-required') {
+ if (result?.status === 'resync-required' || authored && ['stale', 'superseded'].includes(result.status)) {
beginClockResync('play', input.sequence);
return;
}
@@ -228,10 +279,10 @@ export function createCooperativePlayback(session, { seekPage, capture, emitFram
if (stream) stream.forward = true;
reply({ action: 'play', epoch, sequence: input.sequence, status: 'playing' });
} else if (mode === 'playing') {
- const result = await nativeCall(session.page, 'sync', { epoch: input.epoch, t: input.t, workerTime: input.workerTime, sequence: input.sequence });
+ const result = await nativeCall('sync', { epoch: input.epoch, t: input.t, workerTime: input.workerTime, sequence: input.sequence });
if (current !== intent || revision !== controlRevision || mode !== 'playing' || closed) return;
time = input.t;
- if (result?.status === 'resync-required') {
+ if (result?.status === 'resync-required' || authored && result.status === 'stale') {
beginClockResync('sync', input.sequence);
return;
}
@@ -285,6 +336,8 @@ export function createCooperativePlayback(session, { seekPage, capture, emitFram
closed = true;
intent += 1;
gate();
+ for (const reject of pendingCalls) reject(new Error('Preview closed'));
+ pendingCalls.clear();
if (stream) {
clearTimeout(stream.timer);
stream.rejectHeld?.(new Error('Preview closed'));
diff --git a/server/services/generatedPreview/sessions.js b/server/services/generatedPreview/sessions.js
index 24dabeb446..3c250191d0 100644
--- a/server/services/generatedPreview/sessions.js
+++ b/server/services/generatedPreview/sessions.js
@@ -426,7 +426,8 @@ async function startMusicVideo(session, input) {
session.page = opened.page;
session.scratchRoot = opened.scratchRoot;
if (opened.playback?.version === 1) {
- session.playback = createCooperativePlayback(session, { seekPage, capture, emitFrame, fail, closeSession });
+ session.playback = createCooperativePlayback(session, { seekPage, capture, emitFrame, fail, closeSession,
+ authored: opened.playback.producer === 'authored-v1' });
}
// The first frame is captured after this seek. Apply the live controls first
// so that frame is already graded and titled.
diff --git a/server/services/generatedPreview/sessions.test.js b/server/services/generatedPreview/sessions.test.js
index c53d1d7b47..0f13c58cfe 100644
--- a/server/services/generatedPreview/sessions.test.js
+++ b/server/services/generatedPreview/sessions.test.js
@@ -7,6 +7,7 @@ vi.mock('../musicVideo/documentRender.js', () => ({ openIsolatedDocumentPreview:
return { page: fixture.page, scratchRoot: null, width: 390, height: 219, fps: 30, durationSec: 10,
...(fixture.playback ? { playback: fixture.playback } : {}) };
} }));
+import { AUTHORED_PREVIEW_PLAYBACK_TARGET } from '../../lib/generatedPreviewPlaybackSchema.js';
import { closeSession, registerGeneratedPreviewHandlers } from './sessions.js';
const socket = { id: 'preview-test-socket', handlers: new Map(), emit: vi.fn(), on(event, fn) { this.handlers.set(event, fn); } };
@@ -62,13 +63,16 @@ describe('cooperative playback through preview sockets', () => {
const requestId = '00000000-0000-4000-8000-000000000002';
const frames = () => socket.emit.mock.calls.filter(([name]) => name === 'generated-preview:frame').map(([, payload]) => payload);
const states = () => socket.emit.mock.calls.filter(([name]) => name === 'generated-preview:playback-state').map(([, payload]) => payload);
- async function openedPage({ rejectPlay = false } = {}) {
+ async function openedPage({ rejectPlay = false, authored = false } = {}) {
let lifetime = 0;
let capturing = false;
let holdPrepare = null;
let heldSeek = null;
let heldCapture = null;
let heldPause = null;
+ let heldPlay = null;
+ const authoredResponses = new Map();
+ const authoredCalls = [];
let resyncMethod = null;
let resyncEvent = false;
let autoDrain = true;
@@ -84,7 +88,7 @@ describe('cooperative playback through preview sockets', () => {
async pause() { log.push(['pause']); frame.playing = false; if (heldPause) await heldPause; },
async prepare({ epoch, t }) { log.push(['prepare', epoch, t]); if (holdPrepare) await holdPrepare; return { status: 'prepared', epoch }; },
async play({ epoch, sequence }) {
- if (rejectPlay) throw new Error('Synthetic native play rejection'); log.push(['play', epoch]); frame.playing = true;
+ if (rejectPlay) throw new Error('Synthetic native play rejection'); log.push(['play', epoch]); if (heldPlay) await heldPlay; frame.playing = true;
if (resyncMethod === 'play' && resyncEvent) fixture.onEvent({ method: 'Portos.preview', params: { type: 'portos-mv:playback-resync', epoch, sequence } });
return { status: resyncMethod === 'play' ? 'resync-required' : 'playing', epoch };
},
@@ -96,7 +100,18 @@ describe('cooperative playback through preview sockets', () => {
},
},
};
- fixture.playback = { version: 1, fps: 30, presentation: 'atomic-canvas-v1', mediaTiming: 'staged-output-v1' };
+ if (authored) {
+ const original = globals.portosComposition.previewPlayback;
+ const response = (method, args, value) => authoredResponses.has(method) ? authoredResponses.get(method)(args) : value;
+ globals[AUTHORED_PREVIEW_PLAYBACK_TARGET] = Object.freeze({
+ clock(args) { authoredCalls.push(['clock', args]); return response('clock', args, original.clock()); },
+ async pause(args) { authoredCalls.push(['pause', args]); await original.pause(args); return response('pause', args, { epoch: args.epoch, status: 'paused' }); },
+ async prepare(args) { authoredCalls.push(['prepare', args]); await original.prepare(args); return response('prepare', args, { epoch: args.epoch, sequence: args.sequence, status: 'prepared', t: args.t }); },
+ async play(args) { authoredCalls.push(['play', args]); const value = await original.play(args); return response('play', args, { ...value, sequence: args.sequence }); },
+ async sync(args) { authoredCalls.push(['sync', args]); const value = await original.sync(args); return response('sync', args, { ...value, sequence: args.sequence, driftSec: 0 }); },
+ });
+ }
+ fixture.playback = { ...(authored ? { producer: 'authored-v1' } : {}), version: 1, fps: 30, presentation: 'atomic-canvas-v1', mediaTiming: 'staged-output-v1' };
fixture.page = {
evaluate: (source) => new Function('globalThis', 'window', 'return ' + source)(globals, { postMessage() {} }),
send: async (method) => {
@@ -113,7 +128,7 @@ describe('cooperative playback through preview sockets', () => {
await vi.waitFor(() => expect(socket.emit).toHaveBeenCalledWith('generated-preview:opened', expect.objectContaining({ playback: { ...fixture.playback } })));
const sessionId = socket.emit.mock.calls.find(([name]) => name === 'generated-preview:opened')[1].sessionId;
const send = (payload) => socket.handlers.get('generated-preview:playback')({ requestId, sessionId, ...payload });
- return { sessionId, send, nativeFrame, frame, log, hold(promise) { holdPrepare = promise; }, holdSeek(t, promise) { heldSeek = { t, promise }; }, holdCapture(promise) { heldCapture = promise; }, holdPause(promise) { heldPause = promise; }, nativeResync(method, event = false) { resyncMethod = method; resyncEvent = event; }, blockDrain() { autoDrain = false; } };
+ return { sessionId, send, nativeFrame, frame, log, authoredCalls, replacePublic() { globals.portosComposition.previewPlayback = new Proxy({}, { get() { throw new Error('Mutable public producer was dispatched'); } }); }, response(method, fn) { authoredResponses.set(method, fn); }, holdPlay(promise) { heldPlay = promise; }, hold(promise) { holdPrepare = promise; }, holdSeek(t, promise) { heldSeek = { t, promise }; }, holdCapture(promise) { heldCapture = promise; }, holdPause(promise) { heldPause = promise; }, nativeResync(method, event = false) { resyncMethod = method; resyncEvent = event; }, blockDrain() { autoDrain = false; } };
}
it.each(['event', 'play-return', 'sync-return', 'play-race', 'sync-race'])('notifies the master before owned pause retires and deduplicates native resync (%s)', async scenario => {
@@ -355,4 +370,201 @@ describe('cooperative playback through preview sockets', () => {
expect(page.log.filter(([name]) => name === 'Page.startScreencast')).toHaveLength(1);
} finally { vi.useRealTimers(); }
});
+
+ it('dispatches authored playback through the bound bridge and retires before ordered controls and exact frames', async () => {
+ const page = await openedPage({ authored: true });
+ page.replacePublic();
+ page.send({ action: 'clock', probeId: 1, clientTime: 100 });
+ await vi.waitFor(() => expect(states()).toContainEqual(expect.objectContaining({ action: 'clock', workerTime: 123 })));
+ page.send({ action: 'prepare', epoch: 1, sequence: 7, generation: 1, t: 1 });
+ await vi.waitFor(() => expect(states()).toContainEqual(expect.objectContaining({ action: 'prepare', sequence: 7, status: 'ready' })));
+ expect(page.authoredCalls).toContainEqual(['prepare', { epoch: 1, sequence: 7, t: 1 }]);
+ page.send({ action: 'play', epoch: 1, sequence: 8, t: 1, workerTime: 123 });
+ await vi.waitFor(() => expect(states()).toContainEqual(expect.objectContaining({ action: 'play', status: 'playing' })));
+ page.nativeFrame('authored-visible');
+ expect(frames().at(-1)).toMatchObject({ playbackEpoch: 1, sequence: 1, data: 'authored-visible' });
+ expect(frames().at(-1)).not.toHaveProperty('generation');
+ page.send({ action: 'sync', epoch: 1, sequence: 9, t: 1.25, workerTime: 373 });
+ await vi.waitFor(() => expect(states()).toContainEqual(expect.objectContaining({ action: 'sync', sequence: 9, status: 'accepted' })));
+ let release;
+ page.holdPause(new Promise(resolve => { release = resolve; }));
+ const emitted = frames().length;
+ const controlStart = page.log.length;
+ const pauses = page.authoredCalls.filter(([method]) => method === 'pause').length;
+ socket.handlers.get('generated-preview:command')({ requestId, sessionId: page.sessionId, action: 'film-look', look: { exposure: 0.5 } });
+ socket.handlers.get('generated-preview:command')({ requestId, sessionId: page.sessionId, action: 'title-card', card: { enabled: true } });
+ page.nativeFrame('obsolete-control-frame');
+ expect(frames()).toHaveLength(emitted);
+ await vi.waitFor(() => expect(page.authoredCalls.filter(([method]) => method === 'pause')).toHaveLength(pauses + 1));
+ expect(page.log.slice(controlStart).some(([method]) => method === 'look' || method === 'card')).toBe(false);
+ release();
+ await vi.waitFor(() => expect(page.log).toContainEqual(['card', { enabled: true }]));
+ expect(page.log.slice(controlStart).filter(([method]) => method === 'look' || method === 'card')).toEqual([
+ ['look', { exposure: 0.5 }], ['card', { enabled: true }],
+ ]);
+ await vi.waitFor(() => expect(frames().at(-1)).toMatchObject({ generation: 1 }));
+ expect(socket.emit.mock.calls.some(([event]) => event === 'generated-preview:error')).toBe(false);
+ });
+
+ it('resynchronizes an allowed authored superseded play without admitting a stale capture stream', async () => {
+ const page = await openedPage({ authored: true });
+ page.response('play', args => ({ epoch: args.epoch, sequence: args.sequence, status: 'superseded' }));
+ page.send({ action: 'prepare', epoch: 1, sequence: 1, generation: 1, t: 1 });
+ await vi.waitFor(() => expect(states()).toContainEqual(expect.objectContaining({ status: 'ready' })));
+ page.send({ action: 'play', epoch: 1, sequence: 2, t: 1, workerTime: 123 });
+ await vi.waitFor(() => expect(states()).toContainEqual(expect.objectContaining({ epoch: 1, status: 'resync-required', reason: 'clock' })));
+ expect(page.log).not.toContainEqual(['Page.startScreencast']);
+ page.send({ action: 'prepare', epoch: 2, sequence: 1, generation: 2, t: 2 });
+ await vi.waitFor(() => expect(states()).toContainEqual(expect.objectContaining({ epoch: 2, status: 'ready' })));
+ expect(socket.emit.mock.calls.some(([event]) => event === 'generated-preview:error')).toBe(false);
+ expect(page.authoredCalls.filter(([method]) => method === 'pause').length).toBeGreaterThanOrEqual(2);
+ });
+
+ it('waits for a canceled authored preparation to retire before the replacing exact seek', async () => {
+ const page = await openedPage({ authored: true });
+ let release;
+ page.hold(new Promise(resolve => { release = resolve; }));
+ page.send({ action: 'prepare', epoch: 1, sequence: 1, generation: 1, t: 1 });
+ await vi.waitFor(() => expect(page.authoredCalls).toContainEqual(['prepare', { epoch: 1, sequence: 1, t: 1 }]));
+ socket.handlers.get('generated-preview:seek')({ requestId, sessionId: page.sessionId, generation: 2, t: 2 });
+ expect(page.log).not.toContainEqual(['seek', 2]);
+ release();
+ await vi.waitFor(() => expect(frames().at(-1)).toMatchObject({ generation: 2, data: JSON.stringify({ t: 2, playing: false }) }));
+ expect(states().some(state => state.action === 'prepare' && state.epoch === 1 && state.status === 'ready')).toBe(false);
+ expect(frames().some(frame => frame.generation === 1)).toBe(false);
+ const operations = page.authoredCalls.map(([method]) => method);
+ expect(operations).toEqual(['pause', 'prepare', 'pause']);
+ });
+
+ it('closes a canceled held authored play without waiting for its late resolution or starting capture', async () => {
+ const page = await openedPage({ authored: true });
+ page.send({ action: 'prepare', epoch: 1, sequence: 1, generation: 1, t: 1 });
+ await vi.waitFor(() => expect(states()).toContainEqual(expect.objectContaining({ status: 'ready' })));
+ let release;
+ page.holdPlay(new Promise(resolve => { release = resolve; }));
+ page.send({ action: 'play', epoch: 1, sequence: 2, t: 1, workerTime: 123 });
+ await vi.waitFor(() => expect(page.log).toContainEqual(['play', 1]));
+ socket.handlers.get('generated-preview:close')({ requestId, sessionId: page.sessionId });
+ await vi.waitFor(() => expect(socket.emit).toHaveBeenCalledWith('generated-preview:closed', { sessionId: page.sessionId, reason: 'closed' }));
+ expect(fixture.page.close).toHaveBeenCalledOnce();
+ release();
+ await Promise.resolve();
+ await Promise.resolve();
+ expect(page.log).not.toContainEqual(['Page.startScreencast']);
+ expect(states().some(state => state.status === 'playing')).toBe(false);
+ expect(socket.emit.mock.calls.some(([event]) => event === 'generated-preview:error')).toBe(false);
+ });
+
+ it('closes at the authored pause deadline and never reuses its uncertain page for queued exact or control work', async () => {
+ const page = await openedPage({ authored: true });
+ page.send({ action: 'prepare', epoch: 1, sequence: 1, generation: 1, t: 1 });
+ await vi.waitFor(() => expect(states()).toContainEqual(expect.objectContaining({ status: 'ready' })));
+ page.send({ action: 'play', epoch: 1, sequence: 2, t: 1, workerTime: 123 });
+ await vi.waitFor(() => expect(states()).toContainEqual(expect.objectContaining({ status: 'playing' })));
+ let release;
+ page.holdPause(new Promise(resolve => { release = resolve; }));
+ vi.useFakeTimers();
+ try {
+ socket.handlers.get('generated-preview:seek')({ requestId, sessionId: page.sessionId, generation: 2, t: 2 });
+ socket.handlers.get('generated-preview:command')({ requestId, sessionId: page.sessionId, action: 'film-look', look: { exposure: 0.5 } });
+ const count = frames().length;
+ page.nativeFrame('late-pause-frame');
+ expect(frames()).toHaveLength(count);
+ await vi.advanceTimersByTimeAsync(2999);
+ expect(fixture.page.close).not.toHaveBeenCalled();
+ expect(page.log).not.toContainEqual(['seek', 2]);
+ await vi.advanceTimersByTimeAsync(1);
+ expect(socket.emit).toHaveBeenCalledWith('generated-preview:closed', { sessionId: page.sessionId, reason: 'playback-failed' });
+ expect(fixture.page.close).toHaveBeenCalledOnce();
+ expect(socket.emit).toHaveBeenCalledWith('generated-preview:error', expect.objectContaining({ code: 'PREVIEW_PLAYBACK_FAILED' }));
+ expect(page.log).not.toContainEqual(['seek', 2]);
+ expect(page.log).not.toContainEqual(['look', { exposure: 0.5 }]);
+ release();
+ await vi.advanceTimersByTimeAsync(0);
+ expect(page.log).not.toContainEqual(['seek', 2]);
+ expect(page.log).not.toContainEqual(['look', { exposure: 0.5 }]);
+ expect(vi.getTimerCount()).toBe(0);
+ } finally { release(); vi.useRealTimers(); }
+ });
+
+ it('rejects an overdue authored response even when its CDP microtask beats the host timer callback', async () => {
+ const page = await openedPage({ authored: true });
+ let release;
+ let now = 100;
+ page.hold(new Promise(resolve => { release = resolve; }));
+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+ const clock = vi.spyOn(performance, 'now').mockImplementation(() => now);
+ try {
+ page.send({ action: 'prepare', epoch: 1, sequence: 1, generation: 1, t: 1 });
+ await vi.advanceTimersByTimeAsync(0);
+ expect(page.authoredCalls).toContainEqual(['prepare', { epoch: 1, sequence: 1, t: 1 }]);
+ socket.handlers.get('generated-preview:seek')({ requestId, sessionId: page.sessionId, generation: 2, t: 2 });
+ now = 3101; // Advance monotonic time without allowing the timer to run.
+ release();
+ await vi.advanceTimersByTimeAsync(0);
+ expect(socket.emit).toHaveBeenCalledWith('generated-preview:closed', { sessionId: page.sessionId, reason: 'playback-failed' });
+ expect(states().some(state => state.status === 'ready')).toBe(false);
+ expect(page.log).not.toContainEqual(['seek', 2]);
+ expect(fixture.page.close).toHaveBeenCalledOnce();
+ expect(vi.getTimerCount()).toBe(0);
+ } finally { release(); clock.mockRestore(); vi.useRealTimers(); }
+ });
+
+ it.each([
+ ['prepare sequence', 'prepare', args => ({ ...args, sequence: args.sequence + 1, status: 'prepared' })],
+ ['play epoch', 'play', args => ({ epoch: args.epoch + 1, sequence: args.sequence, status: 'playing' })],
+ ['sync extra field', 'sync', args => ({ epoch: args.epoch, sequence: args.sequence, status: 'accepted', unexpected: true })],
+ ['pause status', 'pause', args => ({ epoch: args.epoch, status: 'playing' })],
+ ])('closes on an invalid authored %s response before any follow-up exact seek', async (_label, method, response) => {
+ const page = await openedPage({ authored: true });
+ page.response(method, response);
+ let release;
+ if (method === 'prepare') page.hold(new Promise(resolve => { release = resolve; }));
+ page.send({ action: 'prepare', epoch: 1, sequence: 1, generation: 1, t: 1 });
+ if (method === 'prepare') {
+ await vi.waitFor(() => expect(page.authoredCalls).toContainEqual(['prepare', { epoch: 1, sequence: 1, t: 1 }]));
+ // Even an obsolete invocation must validate before exact reuse.
+ socket.handlers.get('generated-preview:seek')({ requestId, sessionId: page.sessionId, generation: 2, t: 2 });
+ release();
+ }
+ if (method !== 'prepare' && method !== 'pause') {
+ await vi.waitFor(() => expect(states()).toContainEqual(expect.objectContaining({ status: 'ready' })));
+ page.send({ action: 'play', epoch: 1, sequence: 2, t: 1, workerTime: 123 });
+ if (method === 'sync') {
+ await vi.waitFor(() => expect(states()).toContainEqual(expect.objectContaining({ status: 'playing' })));
+ page.send({ action: 'sync', epoch: 1, sequence: 3, t: 1.25, workerTime: 373 });
+ }
+ }
+ await vi.waitFor(() => expect(socket.emit).toHaveBeenCalledWith('generated-preview:closed', { sessionId: page.sessionId, reason: 'playback-failed' }));
+ socket.handlers.get('generated-preview:seek')({ requestId, sessionId: page.sessionId, generation: 2, t: 2 });
+ await Promise.resolve();
+ expect(page.log).not.toContainEqual(['seek', 2]);
+ expect(socket.emit).toHaveBeenCalledWith('generated-preview:error', expect.objectContaining({ requestId, sessionId: page.sessionId, code: 'PREVIEW_PLAYBACK_FAILED' }));
+ expect(fixture.page.close).toHaveBeenCalledOnce();
+ });
+
+ it.each([
+ ['nonfinite', () => Number.NaN],
+ ['negative', () => -1],
+ ['asynchronous', () => Promise.resolve(123)],
+ ])('refuses an authored %s clock and closes its owned session', async (_label, response) => {
+ const page = await openedPage({ authored: true });
+ page.response('clock', response);
+ page.send({ action: 'clock', probeId: 1, clientTime: 100 });
+ await vi.waitFor(() => expect(socket.emit).toHaveBeenCalledWith('generated-preview:closed', { sessionId: page.sessionId, reason: 'playback-failed' }));
+ expect(states().some(state => state.action === 'clock')).toBe(false);
+ expect(fixture.page.close).toHaveBeenCalledOnce();
+ });
+
+ it('accepts equal authored clock observations but closes on a later regression', async () => {
+ const page = await openedPage({ authored: true });
+ page.send({ action: 'clock', probeId: 1, clientTime: 100 });
+ page.send({ action: 'clock', probeId: 2, clientTime: 100 });
+ await vi.waitFor(() => expect(states().filter(state => state.action === 'clock')).toHaveLength(2));
+ page.response('clock', () => 122);
+ page.send({ action: 'clock', probeId: 3, clientTime: 101 });
+ await vi.waitFor(() => expect(socket.emit).toHaveBeenCalledWith('generated-preview:closed', { sessionId: page.sessionId, reason: 'playback-failed' }));
+ expect(states().filter(state => state.action === 'clock')).toHaveLength(2);
+ });
+
});
diff --git a/server/services/musicVideo/authoredPreviewPlayback.js b/server/services/musicVideo/authoredPreviewPlayback.js
new file mode 100644
index 0000000000..f7fdfff6a7
--- /dev/null
+++ b/server/services/musicVideo/authoredPreviewPlayback.js
@@ -0,0 +1,87 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import {
+ AUTHORED_PREVIEW_HANDSHAKE_MS, AUTHORED_PREVIEW_PLAYBACK_TARGET,
+} from '../../lib/generatedPreviewPlaybackSchema.js';
+
+const CONTRACT = 'portos-complete-frame-v1';
+const MAX_DECLARATION_BYTES = 1024;
+const declarationShape = z.object({ version: z.number().int(), contract: z.string() }).strict();
+const supportedDeclaration = z.object({ version: z.literal(1), contract: z.literal(CONTRACT) }).strict();
+
+/** An explicit opt-in identifies an author's promise, not source purity. */
+export async function readAuthoredPreviewDeclaration(directory, { scenes = [] } = {}) {
+ const path = join(directory, 'preview-playback.json');
+ const info = await lstat(path).catch(error => {
+ if (error.code === 'ENOENT') return null;
+ throw error;
+ });
+ if (!info) return { declared: false, supported: false, reason: 'absent' };
+ const declined = reason => ({ declared: true, supported: false, reason });
+ if (!info.isFile() || info.size > MAX_DECLARATION_BYTES) return declined('invalid-declaration');
+ const text = await readFile(path, 'utf8');
+ if (Buffer.byteLength(text) > MAX_DECLARATION_BYTES) return declined('invalid-declaration');
+ let declaration;
+ try { declaration = JSON.parse(text); }
+ catch { return declined('invalid-declaration'); }
+ if (!declarationShape.safeParse(declaration).success) return declined('invalid-declaration');
+ if (!supportedDeclaration.safeParse(declaration).success) return declined('unsupported-declaration');
+ if (scenes.some(scene => scene.media?.kind === 'video'
+ && (!Number.isFinite(scene.media.fps) || scene.media.fps <= 10))) return declined('unsupported-video-fps');
+ return { declared: true, supported: true, version: 1, contract: CONTRACT };
+}
+
+// This executes in the owned page. The root read preserves PortOS's existing
+// film/title accessors; authored API field getters are never invoked.
+function inspectAndBind(target) {
+ const unsupported = reason => ({ supported: false, reason });
+ const ownValue = (object, key) => {
+ const descriptor = Object.getOwnPropertyDescriptor(object, key);
+ return descriptor && Object.hasOwn(descriptor, 'value') ? descriptor.value : undefined;
+ };
+ const composition = globalThis.portosComposition;
+ if (!composition || typeof composition !== 'object') return unsupported('unsupported-runtime');
+ const api = ownValue(composition, 'previewPlayback');
+ if (!api || typeof api !== 'object' || Array.isArray(api)) return unsupported('unsupported-runtime');
+ const metadata = { version: 1, fps: 30, presentation: 'atomic-canvas-v1', mediaTiming: 'staged-output-v1' };
+ for (const [key, value] of Object.entries(metadata)) {
+ if (ownValue(api, key) !== value) return unsupported('unsupported-runtime');
+ }
+ const methods = Object.create(null);
+ for (const name of ['clock', 'prepare', 'play', 'sync', 'pause', 'dispose']) {
+ const method = ownValue(api, name);
+ if (typeof method !== 'function') return unsupported('unsupported-runtime');
+ methods[name] = Function.prototype.bind.call(method, api);
+ }
+ if (Object.getOwnPropertyDescriptor(globalThis, target)) return unsupported('occupied-bridge');
+ const bridge = Object.freeze(Object.assign(Object.create(null), metadata, methods));
+ Object.defineProperty(globalThis, target, { value: bridge, writable: false, configurable: false });
+ return { supported: true, ...metadata, target };
+}
+
+const handshakeError = code => Object.assign(new Error(code === 'AUTHORED_PREVIEW_HANDSHAKE_TIMEOUT'
+ ? 'Authored preview inspection exceeded its deadline'
+ : 'Authored preview inspection returned an invalid receipt'), { code });
+
+/** Uncertain inspection throws: callers must close the page before exact reuse. */
+export function bindAuthoredPreviewPlayback(page) {
+ const started = performance.now();
+ const expression = `(${inspectAndBind.toString()})(${JSON.stringify(AUTHORED_PREVIEW_PLAYBACK_TARGET)})`;
+ return new Promise((resolve, reject) => {
+ const timer = setTimeout(() => reject(handshakeError('AUTHORED_PREVIEW_HANDSHAKE_TIMEOUT')), AUTHORED_PREVIEW_HANDSHAKE_MS);
+ Promise.resolve().then(() => page.evaluate(expression)).then(receipt => {
+ clearTimeout(timer);
+ if (performance.now() - started >= AUTHORED_PREVIEW_HANDSHAKE_MS) {
+ reject(handshakeError('AUTHORED_PREVIEW_HANDSHAKE_TIMEOUT'));
+ } else if (receipt?.supported === false && ['unsupported-runtime', 'occupied-bridge'].includes(receipt.reason)) {
+ resolve({ supported: false, reason: receipt.reason });
+ } else if (receipt?.supported === true && receipt.version === 1 && receipt.fps === 30
+ && receipt.presentation === 'atomic-canvas-v1' && receipt.mediaTiming === 'staged-output-v1'
+ && receipt.target === AUTHORED_PREVIEW_PLAYBACK_TARGET) {
+ resolve({ supported: true, version: 1, fps: 30, presentation: receipt.presentation,
+ mediaTiming: receipt.mediaTiming, target: receipt.target });
+ } else reject(handshakeError('AUTHORED_PREVIEW_HANDSHAKE_INVALID'));
+ }).catch(error => { clearTimeout(timer); reject(error); });
+ });
+}
diff --git a/server/services/musicVideo/authoredPreviewPlayback.test.js b/server/services/musicVideo/authoredPreviewPlayback.test.js
new file mode 100644
index 0000000000..9a550944a5
--- /dev/null
+++ b/server/services/musicVideo/authoredPreviewPlayback.test.js
@@ -0,0 +1,181 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createContext, runInContext } from 'node:vm';
+import { bindAuthoredPreviewPlayback, readAuthoredPreviewDeclaration } from './authoredPreviewPlayback.js';
+import { AUTHORED_PREVIEW_HANDSHAKE_MS, AUTHORED_PREVIEW_PLAYBACK_TARGET } from '../../lib/generatedPreviewPlaybackSchema.js';
+
+const roots = [];
+afterEach(async () => {
+ vi.useRealTimers();
+ vi.restoreAllMocks();
+ await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true })));
+});
+async function document(text) {
+ const root = await mkdtemp(join(tmpdir(), 'authored-preview-contract-'));
+ roots.push(root);
+ if (text !== undefined) await writeFile(join(root, 'preview-playback.json'), text);
+ return root;
+}
+const declared = JSON.stringify({ version: 1, contract: 'portos-complete-frame-v1' });
+const implementation = `
+ globalThis.originalApi = {
+ version: 1, fps: 30, presentation: 'atomic-canvas-v1', mediaTiming: 'staged-output-v1',
+ clock() { return this === originalApi ? 123 : -1; },
+ prepare(value) { return { status: 'prepared', epoch: value.epoch, receiver: this === originalApi }; },
+ play() {}, sync() {}, pause() {}, dispose() {},
+ };
+ globalThis.portosComposition = { previewPlayback: originalApi };
+`;
+function browser(source = implementation) {
+ const context = createContext({});
+ const evaluate = expression => runInContext(expression, context, { timeout: 50 });
+ evaluate(source);
+ return { context, evaluate, page: { evaluate: vi.fn(evaluate) } };
+}
+const target = JSON.stringify(AUTHORED_PREVIEW_PLAYBACK_TARGET);
+
+describe('explicit authored preview declaration', () => {
+ it('distinguishes absent opt-in and never manufactures a declaration', async () => {
+ const root = await document();
+ await writeFile(join(root, 'engine.js'), '/* existing arbitrary async document */');
+ expect(await readAuthoredPreviewDeclaration(root)).toEqual({ declared: false, supported: false, reason: 'absent' });
+ expect(await readFile(join(root, 'engine.js'), 'utf8')).toBe('/* existing arbitrary async document */');
+ });
+
+ it.each(['{', 'null', '[]', 'true', '{}', '{"version":1}', '{"version":"1","contract":"portos-complete-frame-v1"}', '{"version":1,"contract":"portos-complete-frame-v1","extra":true}', ' '.repeat(1025)])(
+ 'declines malformed declaration %j', async text => {
+ expect(await readAuthoredPreviewDeclaration(await document(text))).toEqual({ declared: true, supported: false, reason: 'invalid-declaration' });
+ },
+ );
+
+ it.each([{ version: 2, contract: 'portos-complete-frame-v1' }, { version: 1, contract: 'unknown' }])(
+ 'declines unsupported declaration %j without modifying it', async value => {
+ const text = JSON.stringify(value), root = await document(text);
+ expect(await readAuthoredPreviewDeclaration(root)).toMatchObject({ declared: true, supported: false, reason: 'unsupported-declaration' });
+ expect(await readFile(join(root, 'preview-playback.json'), 'utf8')).toBe(text);
+ },
+ );
+
+ it('declines symlinks without treating even a dangling link as an absent declaration', async () => {
+ const root = await document();
+ await symlink(join(root, 'absent-target.json'), join(root, 'preview-playback.json'));
+ expect(await readAuthoredPreviewDeclaration(root)).toEqual({ declared: true, supported: false, reason: 'invalid-declaration' });
+ });
+
+ it('admits only the declared contract with trusted finite staged video cadence above 10', async () => {
+ const root = await document(declared);
+ for (const fps of [undefined, null, NaN, Infinity, 0, 10]) {
+ expect(await readAuthoredPreviewDeclaration(root, { scenes: [{ media: { kind: 'video', fps } }] }))
+ .toMatchObject({ declared: true, supported: false, reason: 'unsupported-video-fps' });
+ }
+ for (const fps of [10.01, 24, 30, 60]) {
+ expect(await readAuthoredPreviewDeclaration(root, { scenes: [{ media: { kind: 'video', fps } }, { media: { kind: 'image' } }, {}] }))
+ .toEqual({ declared: true, supported: true, version: 1, contract: 'portos-complete-frame-v1' });
+ }
+ expect(await readAuthoredPreviewDeclaration(root)).toMatchObject({ supported: true });
+ expect(await readFile(join(root, 'preview-playback.json'), 'utf8')).toBe(declared);
+ });
+});
+
+describe('owned authored runtime handshake', () => {
+ it('snapshots methods and their receiver once behind an immutable bridge, preserving host root accessors', async () => {
+ const runtime = browser(`${implementation}
+ const composition = portosComposition; globalThis.rootReads = 0;
+ Object.defineProperty(globalThis, 'portosComposition', { get() { rootReads++; return composition; } });
+ `);
+ expect(await bindAuthoredPreviewPlayback(runtime.page)).toEqual({ supported: true, version: 1, fps: 30,
+ presentation: 'atomic-canvas-v1', mediaTiming: 'staged-output-v1', target: AUTHORED_PREVIEW_PLAYBACK_TARGET });
+ runtime.evaluate(`
+ originalApi.clock = () => 999;
+ originalApi.prepare = () => { throw Error('replacement must not run'); };
+ composition.previewPlayback = { clock: () => 888 };
+ globalThis.other = { clock: globalThis[${target}].clock };
+ `);
+ expect(runtime.evaluate(`globalThis[${target}].clock()`)).toBe(123);
+ expect(runtime.evaluate('other.clock()')).toBe(123);
+ expect(runtime.evaluate(`globalThis[${target}].prepare({epoch:7})`)).toMatchObject({ status: 'prepared', epoch: 7, receiver: true });
+ expect(runtime.evaluate('rootReads')).toBe(1);
+ expect(runtime.evaluate(`Object.isFrozen(globalThis[${target}])`)).toBe(true);
+ expect(runtime.evaluate(`Object.getOwnPropertyDescriptor(globalThis, ${target})`)).toMatchObject({ writable: false, configurable: false });
+ expect(runtime.evaluate(`Reflect.set(globalThis, ${target}, {})`)).toBe(false);
+ expect(runtime.evaluate(`Reflect.deleteProperty(globalThis, ${target})`)).toBe(false);
+ });
+
+ it.each([
+ 'delete globalThis.portosComposition', 'portosComposition.previewPlayback = null',
+ 'originalApi.version = 2', 'originalApi.fps = 24', 'originalApi.presentation = "partial"',
+ 'originalApi.mediaTiming = "raw"', 'delete originalApi.dispose',
+ 'Object.setPrototypeOf(originalApi, { dispose() {} }); delete originalApi.dispose',
+ 'originalApi.clock = 1',
+ ])('declines unsupported ordinary runtime shape: %s', async change => {
+ const runtime = browser(`${implementation}\n${change}`);
+ expect(await bindAuthoredPreviewPlayback(runtime.page)).toEqual({ supported: false, reason: 'unsupported-runtime' });
+ expect(runtime.evaluate(`Object.hasOwn(globalThis, ${target})`)).toBe(false);
+ });
+
+ it.each(['version', 'prepare'])('does not execute authored API getter %s', async name => {
+ const runtime = browser(`${implementation}
+ globalThis.reads = 0;
+ Object.defineProperty(originalApi, ${JSON.stringify(name)}, { get() { reads++; throw Error('getter ran'); } });
+ `);
+ expect(await bindAuthoredPreviewPlayback(runtime.page)).toMatchObject({ supported: false });
+ expect(runtime.evaluate('reads')).toBe(0);
+ });
+
+ it('does not execute an authored previewPlayback getter or overwrite an existing bridge', async () => {
+ const getter = browser(`${implementation}
+ Object.defineProperty(portosComposition, 'previewPlayback', { get() { throw Error('getter ran'); } });
+ `);
+ expect(await bindAuthoredPreviewPlayback(getter.page)).toMatchObject({ supported: false, reason: 'unsupported-runtime' });
+ const occupied = browser(`${implementation}
+ Object.defineProperty(globalThis, ${target}, { get() { throw Error('existing bridge getter ran'); } });
+ `);
+ expect(await bindAuthoredPreviewPlayback(occupied.page)).toEqual({ supported: false, reason: 'occupied-bridge' });
+ });
+
+ it('propagates root/Proxy inspection failures instead of falling back on an uncertain page', async () => {
+ for (const source of [
+ `Object.defineProperty(globalThis, 'portosComposition', { get() { throw Error('root inspection failed'); } });`,
+ `${implementation} portosComposition.previewPlayback = new Proxy(originalApi, { getOwnPropertyDescriptor() { throw Error('proxy inspection failed'); } });`,
+ ]) {
+ await expect(bindAuthoredPreviewPlayback(browser(source).page)).rejects.toThrow('inspection failed');
+ }
+ });
+
+ it('propagates actual VM interruption of stuck synchronous Proxy inspection', async () => {
+ const runtime = browser(`${implementation}
+ portosComposition.previewPlayback = new Proxy(originalApi, { getOwnPropertyDescriptor() { while (true) {} } });
+ `);
+ await expect(bindAuthoredPreviewPlayback(runtime.page)).rejects.toThrow('Script execution timed out');
+ });
+
+ it('bounds unsettled page inspection and owns late rejection without declaring fallback', async () => {
+ vi.useFakeTimers();
+ let fail;
+ const promise = bindAuthoredPreviewPlayback({ evaluate: () => new Promise((_resolve, reject) => { fail = reject; }) });
+ const verdict = expect(promise).rejects.toMatchObject({ code: 'AUTHORED_PREVIEW_HANDSHAKE_TIMEOUT' });
+ await vi.advanceTimersByTimeAsync(AUTHORED_PREVIEW_HANDSHAKE_MS);
+ await verdict;
+ fail(new Error('late owned CDP rejection'));
+ await Promise.resolve();
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it('rejects invalid CDP receipts and late resolution even when the timer has not run', async () => {
+ await expect(bindAuthoredPreviewPlayback({ evaluate: () => ({ supported: true }) }))
+ .rejects.toMatchObject({ code: 'AUTHORED_PREVIEW_HANDSHAKE_INVALID' });
+ vi.useFakeTimers();
+ const runtime = browser();
+ vi.spyOn(performance, 'now').mockReturnValueOnce(0).mockReturnValue(AUTHORED_PREVIEW_HANDSHAKE_MS);
+ const promise = bindAuthoredPreviewPlayback(runtime.page);
+ await expect(promise).rejects.toMatchObject({ code: 'AUTHORED_PREVIEW_HANDSHAKE_TIMEOUT' });
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it('owns an uncertain receipt inspection throw as well as evaluation rejection', async () => {
+ const receipt = Object.defineProperty({}, 'supported', { get() { throw Error('receipt inspection failed'); } });
+ await expect(bindAuthoredPreviewPlayback({ evaluate: () => receipt })).rejects.toThrow('receipt inspection failed');
+ });
+});
diff --git a/server/services/musicVideo/documentRender.js b/server/services/musicVideo/documentRender.js
index 85c2eb44bb..2a59d1b5d7 100644
--- a/server/services/musicVideo/documentRender.js
+++ b/server/services/musicVideo/documentRender.js
@@ -356,13 +356,20 @@ export async function openIsolatedDocumentPreview({ project, jobId, signal, onEv
let staged;
let page;
let playbackAdapter;
+ let authoredDeclaration;
try {
const { adaptStagedDocumentPreview } = await import('./documentPreviewPlayback.js');
+ const { readAuthoredPreviewDeclaration, bindAuthoredPreviewPlayback } = await import('./authoredPreviewPlayback.js');
staged = await stageMusicVideoComposition(plan.directory, jobId, musicVideoSongDocument(project), {
prepare: async (dir) => {
+ authoredDeclaration = await readAuthoredPreviewDeclaration(dir, { scenes: data.scenes });
await stageDocumentData(dir, data, media, signal);
signal?.throwIfAborted();
- playbackAdapter = await adaptStagedDocumentPreview(dir, { scenes: data.scenes });
+ // A declared producer owns its implementation. Never rewrite it through
+ // the canonical recognizer, including an unknown future declaration.
+ playbackAdapter = authoredDeclaration.declared
+ ? { adapted: false, producer: 'authored-v1', ...authoredDeclaration }
+ : await adaptStagedDocumentPreview(dir, { scenes: data.scenes });
},
});
signal?.throwIfAborted();
@@ -377,7 +384,7 @@ export async function openIsolatedDocumentPreview({ project, jobId, signal, onEv
});
signal?.throwIfAborted();
let playbackAvailable = false;
- if (playbackAdapter?.adapted) {
+ if (playbackAdapter?.adapted || authoredDeclaration.supported) {
let captureProtocolSupported = false;
try {
const version = await page.send('Browser.getVersion', {}, null);
@@ -396,6 +403,12 @@ export async function openIsolatedDocumentPreview({ project, jobId, signal, onEv
playbackAdapter = { ...playbackAdapter, runtimeSupported, captureProtocolSupported,
...(!captureProtocolSupported ? { reason: 'unsupported-capture-protocol' }
: !runtimeSupported ? { reason: 'unsupported-frame-callbacks' } : {}) };
+ if (playbackAvailable && authoredDeclaration.supported) {
+ const bound = await bindAuthoredPreviewPlayback(page);
+ signal?.throwIfAborted();
+ playbackAvailable = bound.supported;
+ playbackAdapter = { ...playbackAdapter, ...bound };
+ }
}
return {
page, scratchRoot: staged.scratchRoot, playbackAdapter,
diff --git a/server/services/musicVideo/documentRender.test.js b/server/services/musicVideo/documentRender.test.js
index 1b7a44cbf1..51e84351cc 100644
--- a/server/services/musicVideo/documentRender.test.js
+++ b/server/services/musicVideo/documentRender.test.js
@@ -10,12 +10,13 @@ import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';
import { existsSync } from 'node:fs';
import { cp, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
import { join } from 'node:path';
+import { runInNewContext } from 'node:vm';
import { cleanupTempDataRoots, lazyTempDataRoot, makePathsProxy } from '../../lib/mockPathsDataRoot.js';
vi.mock('../htmlComposition/encode.js', async (importOriginal) => ({ ...(await importOriginal()), encodeComposition: vi.fn(async () => { throw new Error('stop at encoder'); }) }));
const { encodeComposition } = await import('../htmlComposition/encode.js');
-const { browser } = vi.hoisted(() => ({ browser: { seen: null, contract: null, visibility: null, sampleTimes: [], send: null, closed: [], frameCallbacks: true, capabilityProbes: 0, version: 'Chrome/155.0.8059.41', versionCalls: [] } }));
+const { browser } = vi.hoisted(() => ({ browser: { seen: null, contract: null, visibility: null, sampleTimes: [], send: null, closed: [], frameCallbacks: true, capabilityProbes: 0, version: 'Chrome/155.0.8059.41', versionCalls: [], authoredContext: null, authoredInspections: 0 } }));
vi.mock('../../lib/paths.js', async (importOriginal) => makePathsProxy(await importOriginal(), {
dataRoot: () => lazyTempDataRoot('portos-mv-document-stage-'),
}));
@@ -44,6 +45,10 @@ vi.mock('../htmlComposition/browser.js', () => ({
browser.seen = { directory, data: window.PORTOS_MV, media, song: JSON.parse(await read(joinPath(dir, 'song.json'), 'utf8')), initScripts: options?.initScripts ?? [] };
return {
async evaluate(expression) {
+ if (expression.includes('__portosAuthoredPreviewPlayback')) {
+ browser.authoredInspections++;
+ return runInNewContext(expression, browser.authoredContext || {});
+ }
if (expression.includes('requestVideoFrameCallback')) {
browser.capabilityProbes++;
const prototype = {};
@@ -75,7 +80,7 @@ const { PATHS } = await import('../../lib/paths.js');
const { encodeDocumentComposition, documentRenderClock, openIsolatedDocumentPreview, resolveSceneMedia } = await import('./documentRender.js');
afterAll(() => cleanupTempDataRoots());
-beforeEach(() => { runFfmpegProcess.mockClear(); probeVideoGeometry.mockReset(); probeVideoGeometry.mockResolvedValue(null); browser.seen = null; browser.contract = null; browser.visibility = null; browser.sampleTimes = []; browser.send = null; browser.closed = []; browser.frameCallbacks = true; browser.capabilityProbes = 0; browser.version = 'Chrome/155.0.8059.41'; browser.versionCalls = []; });
+beforeEach(() => { runFfmpegProcess.mockClear(); probeVideoGeometry.mockReset(); probeVideoGeometry.mockResolvedValue(null); browser.seen = null; browser.contract = null; browser.visibility = null; browser.sampleTimes = []; browser.send = null; browser.closed = []; browser.frameCallbacks = true; browser.capabilityProbes = 0; browser.version = 'Chrome/155.0.8059.41'; browser.versionCalls = []; browser.authoredContext = null; browser.authoredInspections = 0; });
const performanceTake = (assetId) => ({ takeId: 'mvt-p', kind: 'video', assetId, status: 'candidate', shotInstruction: { shotMode: 'performance', edit: { inSec: 0.5, outSec: 3.5 } } });
@@ -119,6 +124,88 @@ async function canonicalPreview() {
return value;
}
+async function authoredPreview(declaration = { version: 1, contract: 'portos-complete-frame-v1' }) {
+ const value = await fixture({ shipped: { 'preview-playback.json': JSON.stringify(declaration), 'authored.js': '/* Immutable authored implementation fixture. */' } });
+ value.project.composition.document = { directory: value.plan.directory };
+ browser.authoredContext = { portosComposition: { previewPlayback: {
+ version: 1, fps: 30, presentation: 'atomic-canvas-v1', mediaTiming: 'staged-output-v1',
+ clock() { return 1; }, prepare() {}, play() {}, sync() {}, pause() {}, dispose() {},
+ } } };
+ return value;
+}
+
+describe('declared authored preview admission through document open', () => {
+ it('admits an explicit supported producer without adapting its source', async () => {
+ const { project, plan } = await authoredPreview();
+ const source = join(PATHS.data, plan.directory);
+ const original = await readFile(join(source, 'index.html'));
+ const preview = await openIsolatedDocumentPreview({ project, jobId: 'authored-admitted' });
+ try {
+ expect(preview.playback).toMatchObject({ producer: 'authored-v1', adapted: false, version: 1, fps: 30 });
+ expect(browser.authoredInspections).toBe(1);
+ expect(await readFile(join(source, 'index.html'))).toEqual(original);
+ expect(await readFile(join(PATHS.data, browser.seen.directory, 'index.html'))).toEqual(original);
+ expect(await readFile(join(PATHS.data, browser.seen.directory, 'authored.js'), 'utf8')).toBe('/* Immutable authored implementation fixture. */');
+ expect(browser.closed).toEqual([]);
+ } finally { await preview.page.close(); await rm(preview.scratchRoot, { recursive: true, force: true }); }
+ });
+
+ it('leaves a declared page exact when its runtime API is incomplete', async () => {
+ const { project } = await authoredPreview();
+ delete browser.authoredContext.portosComposition.previewPlayback.pause;
+ const preview = await openIsolatedDocumentPreview({ project, jobId: 'authored-incomplete' });
+ try {
+ expect(preview.playback).toBeUndefined();
+ expect(preview.playbackAdapter).toMatchObject({ adapted: false, reason: 'unsupported-runtime' });
+ expect(browser.authoredInspections).toBe(1);
+ expect(browser.closed).toEqual([]);
+ } finally { await preview.page.close(); await rm(preview.scratchRoot, { recursive: true, force: true }); }
+ });
+
+ it('does not reinterpret an unknown declaration through the canonical recognizer', async () => {
+ const { project, plan } = await canonicalPreview();
+ const source = join(PATHS.data, plan.directory);
+ await writeFile(join(source, 'preview-playback.json'), JSON.stringify({ version: 2, contract: 'portos-complete-frame-v2' }));
+ const original = await readFile(join(source, 'engine.js'));
+ const preview = await openIsolatedDocumentPreview({ project, jobId: 'authored-future' });
+ try {
+ expect(preview.playback).toBeUndefined();
+ expect(preview.playbackAdapter).toMatchObject({ adapted: false, reason: 'unsupported-declaration' });
+ expect(browser.authoredInspections).toBe(0);
+ expect(browser.versionCalls).toEqual([]);
+ expect(await readFile(join(PATHS.data, browser.seen.directory, 'engine.js'))).toEqual(original);
+ expect(await readFile(join(source, 'engine.js'))).toEqual(original);
+ } finally { await preview.page.close(); await rm(preview.scratchRoot, { recursive: true, force: true }); }
+ });
+
+ it('retains browser and trusted media-cadence eligibility for an authored producer', async () => {
+ const { project } = await authoredPreview();
+ await writeFile(join(PATHS.data, 'video-history.json'), JSON.stringify([{ id: 'vh-a', filename: 'clip-a.mp4', width: 1280, height: 720 }]));
+ const preview = await openIsolatedDocumentPreview({ project, jobId: 'authored-unknown-cadence' });
+ try {
+ expect(preview.playback).toBeUndefined();
+ expect(preview.playbackAdapter.reason).toBe('unsupported-video-fps');
+ expect(browser.authoredInspections).toBe(0);
+ } finally { await preview.page.close(); await rm(preview.scratchRoot, { recursive: true, force: true }); }
+ const next = await authoredPreview(); browser.version = 'Chrome/154.0.8037.57';
+ const older = await openIsolatedDocumentPreview({ project: next.project, jobId: 'authored-older-browser' });
+ try {
+ expect(older.playback).toBeUndefined();
+ expect(older.playbackAdapter.reason).toBe('unsupported-capture-protocol');
+ expect(browser.authoredInspections).toBe(0);
+ } finally { await older.page.close(); await rm(older.scratchRoot, { recursive: true, force: true }); }
+ });
+
+ it('closes a page whose inspection throws before removing its assets', async () => {
+ const { project, plan } = await authoredPreview();
+ runInNewContext("Object.defineProperty(globalThis, 'portosComposition', { get() { throw new Error('Synthetic authored root inspection failure'); } });", browser.authoredContext);
+ await expect(openIsolatedDocumentPreview({ project, jobId: 'authored-inspection-failed' })).rejects.toThrow('Synthetic authored root inspection failure');
+ expect(browser.closed).toEqual([{ directory: browser.seen.directory, assetsPresent: true }]);
+ expect(await scratchEntries()).toEqual([]);
+ expect(existsSync(join(PATHS.data, plan.directory, 'index.html'))).toBe(true);
+ });
+});
+
describe('isolated document preview ownership', () => {
it.each([
{ label: 'Chrome', product: 'Chrome/155.0.8059.41', supported: true },
diff --git a/server/test/authoredPreviewFixture.js b/server/test/authoredPreviewFixture.js
new file mode 100644
index 0000000000..c26b499b2f
--- /dev/null
+++ b/server/test/authoredPreviewFixture.js
@@ -0,0 +1,213 @@
+import { installLayeredPreviewPlayback } from '../services/musicVideo/previewPlaybackRuntime.js';
+
+/**
+ * Synthetic custom-document reference, not an admission rule or a shipped
+ * template. Video comes exclusively from the host-staged selected take.
+ * Resource preparation and full-frame publication belong to this author.
+ */
+export function authoredPreviewFixtureFiles() {
+ return {
+ 'preview-playback.json': JSON.stringify({ version: 1, contract: 'portos-complete-frame-v1' }) + '\n',
+ 'badge-a.svg': '<svg xmlns="http://www.w3.org/2000/svg" width="240" height="80"><rect width="240" height="80" fill="#39e7c2"/><path d="M20 60L60 20L100 60L140 20L180 60L220 20" fill="none" stroke="#102528" stroke-width="8"/></svg>',
+ 'badge-b.svg': '<svg xmlns="http://www.w3.org/2000/svg" width="240" height="80"><rect width="240" height="80" fill="#ffb15f"/><circle cx="120" cy="40" r="26" fill="none" stroke="#251820" stroke-width="8"/></svg>',
+ 'index.html': `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Authored complete-frame reference</title><style>html,body{margin:0;width:100%;height:100%;background:#000;overflow:hidden}#stage{display:block;width:100vw;height:100vh;object-fit:contain}</style></head><body><canvas id="stage" width="1920" height="1080"></canvas><script src="portos-mv.js"></script><!-- portos-allow-hidden-content: host render-time project data --><script src="authored-engine.js"></script><!-- portos-allow-hidden-content: author-owned complete-frame engine --></body></html>`,
+ 'authored-engine.js': `(${authoredEngine.toString()})(${installLayeredPreviewPlayback.toString()});\n`,
+ };
+}
+
+// This function is serialized into the imported document. It deliberately has
+// no module closure, filesystem access, host controls, or expected pixel IDs.
+function authoredEngine(installScheduler) {
+ const W = 1920, H = 1080, FPS = 30, TIMELINE_FPS = 24, DURATION = 30;
+ const selected = globalThis.PORTOS_MV?.scenes?.find(scene => scene.sceneId === 'numbered');
+ const media = selected?.media;
+ if (selected?.startSec !== 0 || selected?.endSec !== DURATION || media?.kind !== 'video'
+ || media.fps !== FPS || media.inSec !== 0 || media.outSec !== DURATION || media.timing
+ || media.width !== 640 || media.height !== 360 || !/^media\/[A-Za-z0-9_.-]+$/.test(media.src)) throw Error('Authored fixture requires the staged selected thirty-second source');
+ const front = document.getElementById('stage'), back = document.createElement('canvas');
+ back.width = W; back.height = H;
+ const frontContext = front.getContext('2d'), backContext = back.getContext('2d');
+ const video = document.createElement('video');
+ video.id = 'clip'; video.crossOrigin = 'anonymous'; video.muted = true; video.playsInline = true; video.preload = 'auto';
+ // Passive reference for this synthetic fixture's existing out-of-window
+ // facts read; it remains detached and receives no observer-driven calls.
+ globalThis.__authoredFixtureVideo = video;
+ const facts = { kind: 'explicit-custom-author-reference', asyncResources: 0, exactSeeks: 0,
+ completeCommits: 0, sceneTransitions: 0, sceneIds: [], lastCommit: null, disposed: false,
+ exactPresentations: [], exactPresentationOverflow: 0, exactCallbackCount: 0, exactCallbackOverflow: 0,
+ sourcePresentations: [], sourcePresentationOverflow: 0, sourceCallbackCount: 0, sourceCallbackOverflow: 0,
+ cacheInvalidations: { count: 0, seeking: 0, playing: 0, last: null },
+ stagedSource: { sceneId: selected.sceneId, src: media.src, fps: media.fps, inSec: media.inSec, outSec: media.outSec, width: media.width, height: media.height } };
+ globalThis.__authoredFixtureFacts = facts;
+ const scenes = [
+ { sceneId: 'authored-a', startSec: 0, endSec: 14, badge: 0 },
+ { sceneId: 'authored-b', startSec: 14, endSec: DURATION, badge: 1 },
+ ];
+ const sceneAt = t => scenes[t >= 14 ? 1 : 0];
+ // Visual scene boundaries do not change this continuous selected source.
+ const mediaScene = { sceneId: 'continuous-selected-source', startSec: 0, endSec: DURATION,
+ media: { kind: 'video', fps: FPS, inSec: 0, outSec: DURATION } };
+ const stateAt = t => ({ t: Math.max(0, Math.min(DURATION - 1 / FPS, t)), hold: false });
+ let disposed = false, exactLease = 0, lastScene = null, qualifiedExactTarget = null;
+ const finite = value => Number.isFinite(value) ? value : null;
+ let lastRequestedTarget = null;
+ const invalidateQualifiedTarget = cause => {
+ facts.cacheInvalidations.count++; facts.cacheInvalidations[cause]++;
+ facts.cacheInvalidations.last = { cause, at: performance.now(), target: finite(qualifiedExactTarget),
+ requestedTarget: finite(lastRequestedTarget), currentTime: finite(video.currentTime) };
+ qualifiedExactTarget = null;
+ };
+ video.addEventListener('playing', () => { invalidateQualifiedTarget('playing'); });
+ video.addEventListener('seeking', () => { invalidateQualifiedTarget('seeking'); });
+ const exactWork = new Set();
+ const loadedVideo = new Promise((resolve, reject) => {
+ video.addEventListener('loadeddata', () => { facts.asyncResources++; resolve(video); }, { once: true });
+ video.addEventListener('error', () => reject(Error('Authored video resource failed')), { once: true });
+ });
+ video.src = new URL(media.src, location.href).href;
+ const badges = ['badge-a.svg', 'badge-b.svg'].map(name => {
+ const image = new Image(); image.crossOrigin = 'anonymous'; image.src = new URL(name, location.href).href;
+ return image.decode().then(() => { facts.asyncResources++; return image; });
+ });
+ let images;
+ const ready = Promise.all([loadedVideo, ...badges, document.fonts.ready]).then(values => { images = values.slice(1, 3); });
+ // Register before assigning currentTime. A stale pre-seek presentation cannot
+ // release the barrier; only the target's actual presented media frame can.
+ const seekVideo = (t, observeExact) => {
+ const intendedFrame = Math.min(FPS * DURATION - 1, Math.floor(Math.max(0, t) * FPS + 1e-6));
+ const target = (intendedFrame + 0.5) / FPS;
+ // One shared list retains at most64 source operations and128 callback rows.
+ // The legacy exact list references the same exact records, without copies.
+ // Each active operation also keeps last8 callbacks for its private timeout,
+ // even after either global retention cap; no new media callbacks are armed.
+ const observation = { kind: observeExact ? 'exact' : 'nonexact', requestedT: finite(t), intendedFrame, target,
+ startedAt: performance.now(), currentTimeBefore: finite(video.currentTime),
+ entry: { paused: video.paused, seeking: video.seeking, readyState: video.readyState,
+ qualifiedTarget: finite(qualifiedExactTarget), currentTime: finite(video.currentTime),
+ targetDelta: finite(video.currentTime - target) }, callbacks: [], seeked: false, cacheDecision: 'miss' };
+ lastRequestedTarget = target;
+ const retained = facts.sourcePresentations.length < 64;
+ if(retained)facts.sourcePresentations.push(observation);else facts.sourcePresentationOverflow++;
+ if(observeExact){if(retained)facts.exactPresentations.push(observation);else facts.exactPresentationOverflow++;}
+ // This known zero-origin30CFR reference reuses only an actually qualified
+ // target while paused. Getter microsecond reconstruction can differ from
+ // the midpoint; its source-frame identity is only a consistency check, not
+ // presentation authority or a rule for generic/VFR authored documents.
+ if (video.paused && !video.seeking && video.readyState >= 2 && qualifiedExactTarget === target
+ && Number.isFinite(video.currentTime) && video.currentTime >= 0
+ && Math.floor(video.currentTime * FPS + 1e-6) === intendedFrame) {
+ observation.cacheDecision='hit';observation.qualifiedPausedCache=true;observation.completedAt=performance.now();
+ return Promise.resolve(video);
+ }
+ qualifiedExactTarget = null;
+ return new Promise((resolve, reject) => {
+ let handle, seeked = false, presented = false, settled = false;
+ const recentCallbacks=[];
+ const cleanup = () => { settled = true; clearTimeout(timer); video.removeEventListener('seeked', onSeeked); video.removeEventListener('error', onError); if (handle != null) video.cancelVideoFrameCallback(handle); };
+ const finish = () => { if (seeked && presented) { qualifiedExactTarget = target;observation.completedAt=performance.now();observation.currentTimeAfter=finite(video.currentTime);cleanup(); resolve(video); } };
+ const onSeeked = () => { seeked = true;observation.seeked=true;observation.seekedAt=performance.now();finish(); };
+ const onError = () => { cleanup(); reject(Error('Authored source seek failed')); };
+ const timer = setTimeout(() => {
+ observation.timedOut=true;
+ const summary={kind:observation.kind,requestedT:observation.requestedT,intendedFrame,target,
+ entry:observation.entry,cacheDecision:observation.cacheDecision,seeked,
+ currentTime:finite(video.currentTime),invalidation:facts.cacheInvalidations,
+ callbacks:recentCallbacks.slice(),callbackRowsOmitted:0};
+ let detail=JSON.stringify(summary);
+ while(detail.length>2000&&summary.callbacks.length){summary.callbacks.shift();summary.callbackRowsOmitted++;detail=JSON.stringify(summary);}
+ cleanup();reject(Error(`Authored presented-frame seek deadline ${detail}`));
+ }, 1500);
+ const arm = () => { handle = video.requestVideoFrameCallback((_at, metadata) => {
+ handle = null;
+ if (settled) return;
+ const mediaTime=metadata?.mediaTime, sourceFrame=Math.round(mediaTime*FPS), ptsError=Math.abs(mediaTime-intendedFrame/FPS);
+ // This reference requires the known zero-origin30CFR WebM source. Its
+ // millisecond PTS quantization must not be compared to a frame midpoint.
+ // Integer frame identity rejects neighboring frames even at boundaries.
+ const qualified=Number.isFinite(mediaTime)&&mediaTime>=0&&sourceFrame===intendedFrame&&ptsError<=.001+1e-9;
+ const row={at:performance.now(),mediaTime:finite(mediaTime),sourceFrame:finite(sourceFrame),ptsError:finite(ptsError),qualified,seeked};
+ if(recentCallbacks.length>=8)recentCallbacks.shift();recentCallbacks.push(row);
+ if(retained&&facts.sourceCallbackCount<128){
+ facts.sourceCallbackCount++;if(observeExact)facts.exactCallbackCount++;
+ if(observation.callbacks.length>=8)observation.callbacks.shift();observation.callbacks.push(row);
+ }else{facts.sourceCallbackOverflow++;if(observeExact)facts.exactCallbackOverflow++;}
+ if (!qualified) { arm(); return; }
+ presented = true; finish();
+ }); };
+ video.addEventListener('seeked', onSeeked); video.addEventListener('error', onError);
+ arm(); video.currentTime = target;
+ });
+ };
+ const source = async (_scene, t, observeExact = false) => {
+ await ready;
+ if (disposed) throw Error('Authored disposed');
+ return seekVideo(t, observeExact);
+ };
+ const publish = (songTime, t, _mediaScene, drawable, _state, valid) => {
+ if (disposed || !drawable || !images) throw Error('Authored resources unavailable');
+ const scene = sceneAt(songTime);
+ // All drawing is detached. No await, visible clear, or partial front draw.
+ backContext.reset();
+ backContext.fillStyle = '#000'; backContext.fillRect(0, 0, W, H);
+ const scale = 1.02, width = W * scale, height = H * scale;
+ backContext.drawImage(drawable, (W - width) / 2, (H - height) / 2, width, height);
+ backContext.drawImage(images[scene.badge], W - 288, 40, 240, 80);
+ backContext.strokeStyle = scene.badge ? '#ffb15f' : '#39e7c2'; backContext.lineWidth = 6;
+ backContext.strokeRect(12, 12, W - 24, H - 24);
+ if (!valid() || disposed) return false;
+ globalThis.__portosFilmLook?.frame(Math.round(songTime * TIMELINE_FPS));
+ globalThis.__portosTitleCard?.draw(songTime);
+ frontContext.save();
+ try { frontContext.resetTransform(); frontContext.globalAlpha = 1; frontContext.globalCompositeOperation = 'copy'; frontContext.filter = 'none'; frontContext.drawImage(back, 0, 0); }
+ finally { frontContext.restore(); }
+ facts.completeCommits++;
+ if (lastScene !== scene.sceneId) { if (lastScene !== null) facts.sceneTransitions++; lastScene = scene.sceneId; if (!facts.sceneIds.includes(lastScene)) facts.sceneIds.push(lastScene); }
+ facts.lastCommit = { songTime, drawTime: t, sceneId: scene.sceneId, sourceTime: drawable.currentTime, at: performance.now() };
+ return true;
+ };
+ // The scheduler is packaged explicitly by this custom author. Host admission
+ // must come from the declaration+API, never canonical engine recognition.
+ globalThis.portosComposition = {};
+ installScheduler({ ready, duration: DURATION, fps: FPS, state: stateAt, scene: () => mediaScene, source,
+ needsSource: () => true, videos: () => [video], publish,
+ playback: on => globalThis.__portosFilmLook?.playback(on),
+ dispose() { disposed = true; facts.disposed = true; video.pause(); video.removeAttribute('src'); video.load(); back.width = 0; back.height = 0; },
+ });
+ const scheduler = globalThis.portosComposition.previewPlayback;
+ const reply = async (method, input) => {
+ const value = await scheduler[method](input);
+ if (method === 'prepare') {
+ if (value.status !== 'prepared') throw Error('Authored preparation superseded');
+ return { epoch: value.epoch, sequence: input.sequence, status: value.status, t: value.t };
+ }
+ const output = { epoch: value.epoch, sequence: input.sequence, status: value.status };
+ if (method === 'sync' && Number.isFinite(value.driftSec)) output.driftSec = value.driftSec;
+ return output;
+ };
+ const api = { version: 1, fps: FPS, presentation: 'atomic-canvas-v1', mediaTiming: 'staged-output-v1',
+ clock: () => scheduler.clock(),
+ prepare: input => reply('prepare', input), play: input => reply('play', input), sync: input => reply('sync', input),
+ async pause(input) { exactLease++; const value = await scheduler.pause(input); await Promise.allSettled([...exactWork]); return value; },
+ async dispose() { exactLease++; await Promise.allSettled([...exactWork]); return scheduler.dispose(); },
+ };
+ globalThis.portosComposition = { fps: TIMELINE_FPS, width: W, height: H, durationSec: DURATION, previewPlayback: api,
+ seek(t) {
+ const token = ++exactLease;
+ const previous = [...exactWork];
+ const operation = (async () => {
+ await Promise.allSettled(previous); await ready;
+ if (disposed || token !== exactLease) return;
+ video.pause();
+ const time = Math.max(0, Math.min(DURATION - 1 / FPS, Number(t)));
+ if (!Number.isFinite(time)) throw Error('Authored exact seek time');
+ const drawable = await source(mediaScene, time, true);
+ if (token !== exactLease || disposed) return;
+ globalThis.__portosFilmLook?.playback(false);
+ publish(time, time, mediaScene, drawable, stateAt(time), () => token === exactLease && !disposed);
+ facts.exactSeeks++;
+ })();
+ exactWork.add(operation); operation.then(() => exactWork.delete(operation), () => exactWork.delete(operation));
+ return operation;
+ },
+ };
+}
diff --git a/server/test/authoredPreviewFixture.test.js b/server/test/authoredPreviewFixture.test.js
new file mode 100644
index 0000000000..339daf09fc
--- /dev/null
+++ b/server/test/authoredPreviewFixture.test.js
@@ -0,0 +1,231 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { runInNewContext } from 'node:vm';
+import { authoredPreviewFixtureFiles } from './authoredPreviewFixture.js';
+
+afterEach(() => vi.useRealTimers());
+
+const flush = async () => { for (let i = 0; i < 20; i++) await Promise.resolve(); };
+
+function documentFixture() {
+ const listeners = new Map(), callbacks = new Map(), frontDraws = [];
+ let clock = 100, handle = 0, currentTime = 0, reportedTime;
+ const emit = type => { for (const fn of [...(listeners.get(type) || [])]) fn(); };
+ const video = {
+ paused: true, seeking: false, readyState: 4, duration: 30,
+ get currentTime() { return reportedTime === undefined ? currentTime : reportedTime; },
+ set currentTime(value) { currentTime = value; this.seeking = true; emit('seeking'); },
+ set src(_value) { queueMicrotask(() => emit('loadeddata')); },
+ addEventListener(type, fn, options) {
+ const wrapped = options?.once ? () => { this.removeEventListener(type, wrapped); fn(); } : fn;
+ if (!listeners.has(type)) listeners.set(type, new Set());
+ listeners.get(type).add(wrapped);
+ },
+ removeEventListener(type, fn) { listeners.get(type)?.delete(fn); },
+ requestVideoFrameCallback(fn) { callbacks.set(++handle, fn); return handle; },
+ cancelVideoFrameCallback(id) { callbacks.delete(id); },
+ pause() { this.paused = true; },
+ play() { this.paused = false; emit('playing'); return Promise.resolve(); },
+ removeAttribute() {}, load() {},
+ };
+ const context = () => ({ reset() {}, fillRect() {}, drawImage() {}, strokeRect() {}, save() {}, restore() {}, resetTransform() {} });
+ const frontContext = context();
+ frontContext.drawImage = (...args) => frontDraws.push(args);
+ const front = { width: 1920, height: 1080, getContext: () => frontContext };
+ const back = { width: 1920, height: 1080, getContext: () => context() };
+ const sandbox = {
+ document: { getElementById: () => front, createElement: type => type === 'video' ? video : back, fonts: { ready: Promise.resolve() } },
+ Image: function () { this.decode = () => Promise.resolve(); },
+ location: { href: 'https://composition.invalid/index.html' }, URL,
+ performance: { now: () => ++clock }, setTimeout, clearTimeout,
+ postMessage: vi.fn(),
+ requestAnimationFrame: vi.fn(), cancelAnimationFrame: vi.fn(),
+ PORTOS_MV: { scenes: [{ sceneId: 'numbered', startSec: 0, endSec: 30,
+ media: { kind: 'video', src: 'media/scene-numbered.webm', fps: 30, width: 640, height: 360, inSec: 0, outSec: 30 } }] },
+ };
+ sandbox.window = sandbox;
+ runInNewContext(authoredPreviewFixtureFiles()['authored-engine.js'], sandbox);
+ return {
+ sandbox, video, callbacks, frontDraws,
+ reportCurrentTime(value) { reportedTime = value; },
+ seeked() { video.seeking = false; emit('seeked'); },
+ presented(mediaTime) {
+ expect(callbacks.size).toBe(1);
+ const [id, fn] = callbacks.entries().next().value;
+ callbacks.delete(id); fn(++clock, { mediaTime });
+ },
+ };
+}
+
+describe('emitted custom author exact source preparation', () => {
+ it.each(['seeked-first', 'presented-first'])('publishes frame22 at millisecond PTS.733 after BOTH barriers (%s)', async order => {
+ const fixture = documentFixture();
+ let settled = false;
+ const seek = fixture.sandbox.portosComposition.seek(.75).then(() => { settled = true; });
+ await flush();
+ expect(fixture.video.currentTime).toBe(.75);
+ expect(fixture.frontDraws).toHaveLength(0);
+ if (order === 'seeked-first') fixture.seeked();
+ else fixture.presented(.733);
+ await flush();
+ expect(settled).toBe(false);
+ expect(fixture.frontDraws).toHaveLength(0);
+ if (order === 'seeked-first') fixture.presented(.733);
+ else fixture.seeked();
+ await seek;
+ expect(settled).toBe(true);
+ expect(fixture.frontDraws).toHaveLength(1);
+ expect(fixture.sandbox.__authoredFixtureFacts.lastCommit.sourceTime).toBe(.75);
+ expect(fixture.sandbox.__authoredFixtureFacts.exactPresentations[0].callbacks).toMatchObject([{ mediaTime: .733, sourceFrame: 22, qualified: true }]);
+ expect(fixture.callbacks.size).toBe(0);
+ });
+
+ it('rejects previous, next, stale and off-grid presentations without visible commit, then accepts target22', async () => {
+ const fixture = documentFixture();
+ let settled = false;
+ const seek = fixture.sandbox.portosComposition.seek(.75).then(() => { settled = true; });
+ await flush(); fixture.seeked();
+ for (const pts of [.7, .767, .233, .74, NaN, -.001]) {
+ fixture.presented(pts); await flush();
+ expect(settled).toBe(false);
+ expect(fixture.frontDraws).toHaveLength(0);
+ expect(fixture.callbacks.size).toBe(1);
+ }
+ fixture.presented(.733); await seek;
+ expect(fixture.frontDraws).toHaveLength(1);
+ expect(fixture.sandbox.__authoredFixtureFacts.exactPresentations[0].callbacks.map(row => row.qualified))
+ .toEqual([false, false, false, false, false, false, true]);
+ });
+
+ it('retains the unchanged1500ms deadline and bounded private failed-callback facts', async () => {
+ vi.useFakeTimers();
+ const fixture = documentFixture();
+ const seek = fixture.sandbox.portosComposition.seek(.75);
+ const rejected = expect(seek).rejects.toThrow(/intendedFrame.*22.*seeked.*true.*mediaTime.*0.767/);
+ await flush(); fixture.seeked();
+ for (let i = 0; i < 12; i++) fixture.presented(.767);
+ await vi.advanceTimersByTimeAsync(1499);
+ expect(fixture.frontDraws).toHaveLength(0);
+ await vi.advanceTimersByTimeAsync(1); await rejected;
+ expect(fixture.sandbox.__authoredFixtureFacts.exactPresentations[0].callbacks).toHaveLength(8);
+ expect(fixture.sandbox.__authoredFixtureFacts.exactPresentations[0].timedOut).toBe(true);
+ expect(fixture.callbacks.size).toBe(0);
+ expect(fixture.frontDraws).toHaveLength(0);
+ });
+
+ it('reuses only an unchanged previously qualified paused target and invalidates it on playing', async () => {
+ const fixture = documentFixture();
+ const initial = fixture.sandbox.portosComposition.seek(.75);
+ await flush(); fixture.seeked(); fixture.presented(.733); await initial;
+ await fixture.sandbox.portosComposition.seek(.75);
+ expect(fixture.callbacks.size).toBe(0);
+ expect(fixture.frontDraws).toHaveLength(2);
+ await fixture.video.play(); fixture.video.pause();
+ let settled = false;
+ const next = fixture.sandbox.portosComposition.seek(.75).then(() => { settled = true; });
+ await flush();
+ expect(settled).toBe(false);
+ expect(fixture.callbacks.size).toBe(1);
+ fixture.seeked(); fixture.presented(.733); await next;
+ expect(fixture.frontDraws).toHaveLength(3);
+ });
+
+ it('prepares the same repeating midpoint2 from the actual qualified exact source without another callback', async () => {
+ const fixture = documentFixture();
+ const initial = fixture.sandbox.portosComposition.seek(2);
+ await flush(); fixture.seeked(); fixture.presented(2); await initial;
+ const facts = fixture.sandbox.__authoredFixtureFacts;
+ expect(fixture.video.currentTime).toBe(60.5 / 30);
+ expect(facts.sourcePresentations[0]).toBe(facts.exactPresentations[0]);
+ const result = await fixture.sandbox.portosComposition.previewPlayback.prepare({ epoch: 1, sequence: 1, t: 2 });
+ expect(result).toEqual({ epoch: 1, sequence: 1, status: 'prepared', t: 2 });
+ expect(fixture.callbacks.size).toBe(0);
+ expect(fixture.frontDraws).toHaveLength(2);
+ expect(facts.sourcePresentations[1]).toMatchObject({ kind: 'nonexact', requestedT: 2, intendedFrame: 60,
+ target: 60.5 / 30, cacheDecision: 'hit', qualifiedPausedCache: true,
+ entry: { paused: true, seeking: false, readyState: 4, currentTime: 60.5 / 30, qualifiedTarget: 60.5 / 30, targetDelta: 0 } });
+ });
+
+ it('reuses presented frame60 for measured getter2.016665 without another seek assignment or callback', async () => {
+ const fixture = documentFixture();
+ const initial = fixture.sandbox.portosComposition.seek(2);
+ await flush(); fixture.seeked(); fixture.presented(2); await initial;
+ const facts = fixture.sandbox.__authoredFixtureFacts;
+ const invalidations = facts.cacheInvalidations.count;
+ fixture.reportCurrentTime(2.016665);
+ expect(Math.abs(fixture.video.currentTime - 60.5 / 30)).toBeGreaterThan(1e-6);
+ const result = await fixture.sandbox.portosComposition.previewPlayback.prepare({ epoch: 1, sequence: 1, t: 2 });
+ expect(result).toEqual({ epoch: 1, sequence: 1, status: 'prepared', t: 2 });
+ expect(fixture.callbacks.size).toBe(0);
+ expect(facts.cacheInvalidations.count).toBe(invalidations);
+ expect(fixture.frontDraws).toHaveLength(2);
+ expect(facts.sourcePresentations[1]).toMatchObject({ kind: 'nonexact', intendedFrame: 60,
+ cacheDecision: 'hit', qualifiedPausedCache: true,
+ entry: { currentTime: 2.016665, qualifiedTarget: 60.5 / 30 } });
+ });
+
+ it.each([
+ ['previous-frame', 59.5 / 30], ['next-frame', 61.5 / 30],
+ ['nonfinite', NaN], ['infinite', Infinity], ['negative', -1e-12],
+ ])('requires an existing presentation barrier when qualified-target getter consistency fails (%s)', async (_label, getter) => {
+ vi.useFakeTimers();
+ const fixture = documentFixture();
+ const initial = fixture.sandbox.portosComposition.seek(2);
+ await flush(); fixture.seeked(); fixture.presented(2); await initial;
+ fixture.reportCurrentTime(getter);
+ let failure;
+ const prepare = fixture.sandbox.portosComposition.previewPlayback.prepare({ epoch: 1, sequence: 1, t: 2 })
+ .catch(error => { failure = error; });
+ await flush(); fixture.seeked();
+ const record = fixture.sandbox.__authoredFixtureFacts.sourcePresentations[1];
+ expect(record).toMatchObject({ kind: 'nonexact', cacheDecision: 'miss', entry: { qualifiedTarget: 60.5 / 30 } });
+ expect(fixture.callbacks.size).toBe(1);
+ expect(fixture.frontDraws).toHaveLength(1);
+ await vi.advanceTimersByTimeAsync(1499);
+ expect(failure).toBeUndefined();
+ await vi.advanceTimersByTimeAsync(1); await prepare;
+ expect(failure.message).toMatch(/^Authored presented-frame seek deadline /);
+ expect(record.timedOut).toBe(true);
+ expect(fixture.callbacks.size).toBe(0);
+ expect(fixture.frontDraws).toHaveLength(1);
+ });
+
+ it.each([false, true])('keeps nonexact deadline facts after invalidation even with global retention exhausted (%s)', async overflow => {
+ vi.useFakeTimers();
+ const fixture = documentFixture();
+ const initial = fixture.sandbox.portosComposition.seek(2);
+ await flush(); fixture.seeked(); fixture.presented(2); await initial;
+ const facts = fixture.sandbox.__authoredFixtureFacts;
+ if (overflow) for (let i = 0; i < 63; i++) await fixture.sandbox.portosComposition.seek(2);
+ await fixture.video.play(); fixture.video.pause();
+ expect(facts.cacheInvalidations).toMatchObject({ count: 2, seeking: 1, playing: 1,
+ last: { cause: 'playing', target: 60.5 / 30 } });
+ let failure;
+ const prepare = fixture.sandbox.portosComposition.previewPlayback.prepare({ epoch: 1, sequence: 1, t: 2 })
+ .catch(error => { failure = error; });
+ await flush(); fixture.seeked();
+ for (let i = 0; i < 140; i++) fixture.presented(2.033);
+ await vi.advanceTimersByTimeAsync(1499);
+ expect(failure).toBeUndefined();
+ expect(fixture.frontDraws).toHaveLength(overflow ? 64 : 1);
+ await vi.advanceTimersByTimeAsync(1); await prepare;
+ const prefix = 'Authored presented-frame seek deadline ';
+ expect(failure.message.startsWith(prefix)).toBe(true);
+ const detail = failure.message.slice(prefix.length);
+ expect(detail.length).toBeLessThanOrEqual(2000);
+ const summary = JSON.parse(detail);
+ expect(summary).toMatchObject({ kind: 'nonexact', requestedT: 2, intendedFrame: 60, target: 60.5 / 30,
+ entry: { currentTime: 60.5 / 30, paused: true, seeking: false, readyState: 4, qualifiedTarget: null },
+ cacheDecision: 'miss', seeked: true, invalidation: { count: 3, seeking: 2, playing: 1,
+ last: { cause: 'seeking', requestedTarget: 60.5 / 30 } } });
+ expect(summary.callbacks.length).toBeGreaterThan(0);
+ expect(summary.callbacks.length + summary.callbackRowsOmitted).toBe(8);
+ expect(summary.callbacks.every(row => row.mediaTime === 2.033 && row.sourceFrame === 61 && !row.qualified && row.seeked)).toBe(true);
+ expect(facts.sourcePresentations.length).toBeLessThanOrEqual(64);
+ expect(facts.sourceCallbackCount).toBeLessThanOrEqual(128);
+ expect(facts.sourceCallbackOverflow).toBeGreaterThan(0);
+ if (overflow) expect(facts.sourcePresentationOverflow).toBe(1);
+ else expect(facts.sourcePresentations.at(-1)).toMatchObject({ kind: 'nonexact', timedOut: true, seeked: true });
+ expect(fixture.callbacks.size).toBe(0);
+ expect(fixture.sandbox.postMessage).toHaveBeenCalledWith(expect.objectContaining({ type: 'portos-mv:playback-error' }), '*');
+ });
+});