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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
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.jsxindex 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, seekRequesmaxSec={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.jsxindex 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.jsindex 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.mdindex 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 scratchdirectory 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 shippedlyric template in an iframe because the storyboard has to show through it; thattemplate is not given private media. Final MP4 encodes still use the existingdiff --git a/docs/plans/2026-10-15-authored-preview-playback-contract.md b/docs/plans/2026-10-15-authored-preview-playback-contract.mdnew file mode 100644index 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.mdindex 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.jsindex 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.jsindex 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, emitFramlet 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, emitFramcloseSession(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, emitFramasync 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, emitFramconst 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, emitFramif (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, emitFramif (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, emitFramif (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, emitFramclosed = 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.jsindex 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.jsindex 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsindex 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, onEvlet 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, onEvplaybackAdapter = { ...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.jsindex 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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' }), '*');+ });+});