Skip to content

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

Enable complete-frame previews for newly generated Canvas documents (#11655)

[._.]/d2de3feb684c
diff --git a/.claude/skills/portos-music-video-code/SKILL.md b/.claude/skills/portos-music-video-code/SKILL.md
index d04ca648ca..70a46bed6b 100644
--- a/.claude/skills/portos-music-video-code/SKILL.md
+++ b/.claude/skills/portos-music-video-code/SKILL.md
@@ -5,7 +5,7 @@ description: Author and review a treatment-driven mixed-media music-video compos
# Mixed-media composition authoring
-Use the Music Video **Compose → Document → Generate mixed-media composition** action after the song is analyzed, the treatment is approved, and each footage or still scene has a timed, selected local asset. The provider and model shown beside the button write only section drawing functions. No footage or still provider runs during this step. Missing selected media is a preflight error to resolve on the scene board.
+Use the Music Video **Compose → Document → Generate mixed-media composition** action after the song is analyzed, the treatment is approved, and each footage or still scene has a timed, selected local asset. The provider and model shown beside the button write only section drawing functions. Canvas sections finish all drawing before returning: no Promise, deferred drawing or retained ctx; the host awaits selected media and packaged fonts. No footage or still provider runs during this step. Missing selected media is a preflight error to resolve on the scene board.
PortOS assembles the functions into an immutable candidate version of its layered document. The active document remains selected while the candidate is previewed. Scrub the candidate through each section boundary, selected clip in-point and out-point, repeated hooks and lyric onsets; play it with the master song to judge movement and audio alignment. Accept the reviewed version to render it, or discard it. **Regenerate section** writes a new candidate with the same shared style contract and every other section unchanged. If the treatment, song, scene timing or selected media changed, generate a fresh candidate.
diff --git a/docs/HTML_COMPOSITIONS.md b/docs/HTML_COMPOSITIONS.md
index 1be2af77b4..5994399098 100644
--- a/docs/HTML_COMPOSITIONS.md
+++ b/docs/HTML_COMPOSITIONS.md
@@ -580,6 +580,16 @@ 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.
+New mixed-media Canvas candidates generated by PortOS package this complete-frame
+producer automatically. The host awaits selected media and packaged fonts, draws
+with the existing renderer into a private persistent canvas, and commits only the
+finished frame. Section functions must finish synchronously before returning;
+Promise/deferred drawing and retaining `ctx` violate the generation contract.
+The packaged `engine-reference.js` retains the original renderer for comparison.
+Existing generated, imported and customized documents keep their existing path.
+New Three.js candidates retain exact seek playback; their cooperative producer
+remains tracked in #11221.
+
### Optional authored complete-frame playback
A custom music-video document can explicitly supply a cooperative producer
diff --git a/server/lib/musicVideoTitleCard.js b/server/lib/musicVideoTitleCard.js
index 1ce205fe67..ce4c4b80aa 100644
--- a/server/lib/musicVideoTitleCard.js
+++ b/server/lib/musicVideoTitleCard.js
@@ -367,6 +367,8 @@ export function titleCardRuntimeSource(card = null, { fonts = {} } = {}) {
drawTitleCard(ctx, card, t, { width, height });
};
const api = {
+ // Complete-frame producers await fonts without painting a visible layer.
+ ready,
apply(next) {
card = next && typeof next === 'object' ? next : null;
const wait = ready();
diff --git a/server/services/codeAnimation/prompt.js b/server/services/codeAnimation/prompt.js
index 3a805029c5..78e5326153 100644
--- a/server/services/codeAnimation/prompt.js
+++ b/server/services/codeAnimation/prompt.js
@@ -461,6 +461,7 @@ export function buildMixedMediaDocumentPrompt({ title, song, palette, treatment,
`MEDIA POLICY: ${mediaMode}. Code always authors composition, staging, characters, camera, text, motion and timing. Never generate guide images in code-only mode.`,
renderer === 'three' ? `Write complete authored Three.js worlds, one function render(ctx, env) per section. ctx = { THREE, scene, camera, text, lens, toonWorld }; THREE is the installed locally packaged library; scene is a fresh Scene on EACH seek, camera a PerspectiveCamera, text a transparent Canvas2D overlay with local MV Mono font, lens a per-frame object you set to direct the host post stack. LENS: every lens setting starts off; once any is set the host renders HDR then applies depth of field, bloom, a PBR Neutral highlight shoulder, vignette and grain. For a finished look set ctx.lens.bloom 0.3, vignette 0.3 and grain 0.02 alongside your focus. Set ctx.lens.focus (camera distance, or a THREE.Vector3 such as the subject's head) and ctx.lens.aperture (blur pixels at 1080p; 0 is sharp, 3-6 for wide shots, 10-18 for character close-ups) and animate focus from env.t for rack focus; ctx.lens.maxBlur caps it (default 16). Only colours above ctx.lens.bloomThreshold (default 1) glow, so drive emissive screens, lamps and sparks above 1 (e.g. new THREE.Color(3, 1.6, 0.8)) and raise the threshold above a bright daytime sky so daylight does not haze; exposure is also settable (default 1). Light a character with a key that casts shadows plus a soft fill near the camera so faces stay readable in night or backlit shots, and keep additive particles small and away from the lens. For toon worlds use ctx.toonWorld.toonMaterial(THREE, { lit, mid, shadow, bands: 3 }), shellLathe(profile, thickness, segments) for closed bowls/shells, solidify(geometry, thickness) for sheets, and layoutRow/layoutGrid({ count, footprint, gap, curve }) for spaced placements. These helpers are members of ctx.toonWorld. Footprint is full axis-aligned width/depth including thickness and posed excursions; curve(x, row) adds Z. Set ctx.lens.ink = true or { color, width, depthThreshold, normalThreshold } for visible-depth silhouettes/creases before grade/grain. Never use single-surface bowls or inverted-hull ink on thin/concave geometry. Build modeled characters with articulated limbs and expressive poses, environments with depth/lighting/shadows, props, narrative action and camera choreography. Position every object analytically from env.t/localT; no simulation accumulation. Add geometry/lights to ctx.scene and set ctx.camera explicitly. Use ctx.text for designed typography. Render fills the whole frame; a particle field or text overlays alone are not a scene. Do not create a renderer, DOM elements, textures loaded from files, or another clock. env provides t, localT, frame, width, height, song, section, palette, safe, events and reactiveGain. No imports, require, fetch, Math.random, Date, performance, globalThis, window, document or external assets. The host draws aligned subtitles after your text; reserve lower title-safe space. Use reusable local functions within each section for anatomy and world construction.` : `Write original Canvas 2D section functions for a mixed-media music-video document titled ${JSON.stringify(trimTo(title, 200))}. The host owns the document, song clock, selected local media and lyric pass. Return code functions only; do not request or generate image/video assets.`,
renderer === 'three' ? '' : CODE_VIDEO_RULES.replace('- Canvas 2D only. No external assets, fonts, or network.', '- Canvas 2D only. No network, remote URLs, filesystem paths or font loading. The host binds only the listed selected project assets; draw over footage/stills without obscuring them, and draw the entire authored world for card scenes, including characters, environments, camera staging, lighting and narrative actions. Local packaged fonts MV Mono, MV Cond and MV Stencil are available; authored titles are allowed, but do not duplicate host subtitles.'),
+ renderer === 'three' ? '' : 'Finish all Canvas drawing before render returns. Do not return a Promise, schedule deferred drawing callbacks or retain ctx. The host awaits selected media and packaged fonts before invoking your function.',
MUSIC_VIDEO_DIRECTION,
MUSIC_VIDEO_CHOREOGRAPHY,
renderer === 'three' ? 'The authored Three.js world receives no selected-media handles; all visual staging uses geometry and the host text overlay.' : 'env additionally has mediaKind (video, image or null) and visualLayer (footage, still, card or code — a code shot has no media and is drawn entirely by the section). The host has already drawn the selected media at its in/out time: when env.mediaKind is set, the section is an overlay: never fill, clear or paint the whole canvas (no full-frame fillRect, path fill or drawImage; the host reduces a full-frame fillRect to a faint wash) and keep the footage readable; paint full backgrounds only when env.mediaKind is null. Do not read DOM or load assets in a section function. Use seeded arithmetic from env.frame for visual motion. Keep repeated hooks related but deliberately vary their action.',
diff --git a/server/services/codeAnimation/prompt.test.js b/server/services/codeAnimation/prompt.test.js
index 0d882254d3..74a1d7e648 100644
--- a/server/services/codeAnimation/prompt.test.js
+++ b/server/services/codeAnimation/prompt.test.js
@@ -223,6 +223,11 @@ describe('music-video craft and measured choreography', () => {
expect(prompt).toContain('does not require rapid cuts or constant motion');
expect(prompt).toContain("Preserve the host's lyric pass as the authority");
expect(prompt).toContain('never invent a kick, snare, drop, word timing or missing event');
+ if (_label === 'document Canvas') {
+ expect(prompt).toContain('Finish all Canvas drawing before render returns');
+ expect(prompt).toContain('Do not return a Promise, schedule deferred drawing callbacks or retain ctx');
+ expect(prompt).toContain('The host awaits selected media and packaged fonts');
+ }
const snapshot = songSnapshot(prompt);
expect(snapshot.beats).toEqual(project.audioAnalysis.beats);
expect(snapshot.downbeats).toEqual(project.audioAnalysis.downbeats);
diff --git a/server/services/musicVideo/compositionDocument.js b/server/services/musicVideo/compositionDocument.js
index f563ebf23c..7a726bf573 100644
--- a/server/services/musicVideo/compositionDocument.js
+++ b/server/services/musicVideo/compositionDocument.js
@@ -1,4 +1,5 @@
import { createRequire } from 'node:module';
+import { generatedCanvasPlaybackEngine } from './generatedCanvasPlayback.js';
import { createHash } from 'node:crypto';
import { assertDocumentMediaPolicy } from './documentMediaPolicy.js';
/**
@@ -420,7 +421,11 @@ export async function stageGeneratedDocument(projectId, generatedFiles, { verify
const index = await readFile(join(TEMPLATE_ROOT, 'layered', 'index.html'), 'utf8');
const marker = '<script src="engine.js"></script>';
if (!index.includes(marker)) throw new Error('Layered template has no engine script');
- const staged = files.filter((file) => file.rel !== 'index.html');
+ const originalEngine = await readFile(join(TEMPLATE_ROOT, 'layered', 'engine.js'));
+ const staged = files.filter((file) => file.rel !== 'index.html' && file.rel !== 'engine.js');
+ staged.push({ rel: 'engine.js', data: generatedCanvasPlaybackEngine(originalEngine) },
+ { rel: 'engine-reference.js', data: originalEngine },
+ { rel: 'preview-playback.json', data: Buffer.from(JSON.stringify({ version: 1, contract: 'portos-complete-frame-v1' })) });
staged.push({ rel: 'index.html', data: Buffer.from(index.replace(marker, '<script src="generated.js"></script>\n' + marker)) });
staged.push(...generatedFiles);
return storeVersion(projectId, staged, { kind: 'generated', name: 'Mixed-media composition' }, { draft: true, verifyCurrent });
diff --git a/server/services/musicVideo/documentGeneration.test.js b/server/services/musicVideo/documentGeneration.test.js
index 2bdcfb60b4..10aa093784 100644
--- a/server/services/musicVideo/documentGeneration.test.js
+++ b/server/services/musicVideo/documentGeneration.test.js
@@ -3,6 +3,9 @@ vi.mock('./productionReview.js', async (load) => ({ ...await load(), assertProdu
import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';
import { mkdir, readFile, writeFile, unlink } from 'node:fs/promises';
import { join } from 'node:path';
+import { createContext, runInContext } from 'node:vm';
+import { bindAuthoredPreviewPlayback } from './authoredPreviewPlayback.js';
+import { titleCardRuntimeSource } from '../../lib/musicVideoTitleCard.js';
import { cleanupTempDataRoots, lazyTempDataRoot, makePathsProxy } from '../../lib/mockPathsDataRoot.js';
const h = vi.hoisted(() => ({ calls: 0, prompt: '', response: '', onSubmit: null, onPrepare: null, provider: { id: 'stub-provider' }, args: null }));
@@ -67,7 +70,165 @@ async function fixture() {
return created.id;
}
+// Execute the actual newly staged candidate (or its preserved raw reference)
+// without a browser. The context deliberately models persistent font/path state.
+async function candidateRuntime(document, { reference = false, fontGate = Promise.resolve(), titleFontGate = null } = {}) {
+ const traces = [], copies = [], events = [], finishing = [], overlays = [];
+ let clock = 0, slow = false;
+ const makeCanvas = () => {
+ const stack = [], path = [];
+ const ctx = { font: '10px sans-serif',
+ save() { stack.push(this.font); }, restore() { this.font = stack.pop(); },
+ beginPath() { path.length = 0; }, lineTo(...point) { path.push(point); },
+ fillText(text) { if (text === 'authored') { traces.push({ font: this.font, path: path.slice() }); if (slow) clock += 100; } },
+ stroke() {}, drawImage(...args) { copies.push(args); },
+ createImageData(w, h) { return { data: new Uint8ClampedArray(w * h * 4) }; },
+ createLinearGradient() { return { addColorStop() {} }; }, createRadialGradient() { return { addColorStop() {} }; },
+ createPattern() { return {}; }, measureText(text) { return { width: String(text).length * 10 }; },
+ };
+ const context = new Proxy(ctx, { get(target, key) { return key in target ? target[key] : () => {}; } });
+ let width = 1920, height = 1080;
+ const reset = () => { ctx.font = '10px sans-serif'; path.length = 0; stack.length = 0; };
+ return { get width() { return width; }, set width(value) { width = value; reset(); },
+ get height() { return height; }, set height(value) { height = value; reset(); },
+ dataset: {}, style: {}, setAttribute() {}, getContext: () => context };
+ };
+ const front = makeCanvas();
+ const sandbox = { setTimeout, clearTimeout, performance: { now: () => clock }, requestAnimationFrame: () => 1, cancelAnimationFrame() {},
+ innerWidth: 1920, innerHeight: 1080,
+ document: { body: { appendChild(node) { node.isConnected = true; overlays.push(node); } }, getElementById: () => front, createElement: () => makeCanvas(),
+ fonts: { load: font => titleFontGate && font.includes('MV Title') ? titleFontGate : fontGate } },
+ PORTOS_MV: { render: { width: 1920, height: 1080, fps: 24, durationSec: 30 }, song: {}, composition: {},
+ scenes: [{ sceneId: 'code', startSec: 0, endSec: 30, visualLayer: 'code' }] },
+ PORTOS_MV_EVENT_STATE: (_song, t) => ({ t, frame: Math.floor(t * 24), hold: false, activeEvents: [], reactiveGain: 0 }),
+ PORTOS_LYRIC_TYPE: { createLyricType: () => ({ ready: Promise.resolve(), draw(ctx, t) { ctx.font = `lyric-${t}`; } }) },
+ __portosFilmLook: { frame: t => finishing.push(['look', t]), playback() {} },
+ __portosTitleCard: { draw: t => finishing.push(['title', t]) }, postMessage: event => events.push(event),
+ };
+ sandbox.window = sandbox;
+ const context = createContext(sandbox);
+ const root = join(PATHS.data, document.directory);
+ if (titleFontGate) {
+ delete sandbox.__portosTitleCard;
+ runInContext(titleCardRuntimeSource({ title: 'Real delayed title', font: 'oswald', startSec: 0, endSec: 4 }), context);
+ }
+ runInContext(await readFile(join(root, 'generated.js'), 'utf8'), context);
+ runInContext(await readFile(join(root, reference ? 'engine-reference.js' : 'engine.js'), 'utf8'), context);
+ return { api: sandbox.portosComposition.previewPlayback, composition: sandbox.portosComposition, traces, copies, events, finishing, overlays,
+ page: { evaluate: source => runInContext(source, context) }, slow: () => { slow = true; } };
+}
+
describe('treatment-driven mixed-media document authoring', () => {
+ it('packages an actual complete-frame producer for new Canvas candidates and preserves raw renderer state/reference', async () => {
+ const id = await fixture();
+ const drawing = 'function render(ctx, env) { ctx.fillText("authored", 1, 2); ctx.lineTo(env.frame, 3); ctx.stroke(); }';
+ h.response = JSON.stringify({ sections: ['intro', 'still', 'clip'].map(id => ({ id, source: drawing })) });
+ const { document } = await generateMixedMediaDocument(id);
+ const root = join(PATHS.data, document.directory);
+ expect(JSON.parse(await readFile(join(root, 'preview-playback.json'), 'utf8'))).toEqual({ version: 1, contract: 'portos-complete-frame-v1' });
+ expect(await readFile(join(root, 'engine-reference.js'))).toEqual(await readFile(new URL('./documentTemplates/layered/engine.js', import.meta.url)));
+ expect(await readFile(join(root, 'generated.js'), 'utf8')).toContain(drawing);
+ const native = await candidateRuntime(document), reference = await candidateRuntime(document, { reference: true });
+ expect(await bindAuthoredPreviewPlayback(native.page)).toMatchObject({ supported: true, fps: 30 });
+ for (const t of [0.75, 1.5, 0.75, 2, 0.75]) {
+ await native.composition.seek(t); await reference.composition.seek(t);
+ }
+ expect(native.traces.length, JSON.stringify((await manifestAt(document)).song.sections)).toBeGreaterThan(0);
+ expect(native.traces).toEqual(reference.traces);
+ expect(native.traces.at(-1).font).toBe('lyric-2');
+ for (const [width, height] of [[1920, 1080], [1080, 1920], [1920, 1080]]) {
+ native.composition.layout({ width, height }); reference.composition.layout({ width, height });
+ await native.composition.seek(0.75); await reference.composition.seek(0.75);
+ expect(native.traces).toEqual(reference.traces);
+ }
+ await reference.composition.seek(0.5);
+ expect(await native.api.prepare({ epoch: 1, sequence: 7, t: 0.5 })).toEqual({ epoch: 1, sequence: 7, status: 'prepared', t: 0.5 });
+ expect(native.traces).toEqual(reference.traces);
+ const copies = native.copies.length, finishing = native.finishing.length;
+ native.slow();
+ await expect(native.api.prepare({ epoch: 2, sequence: 8, t: 0.75 })).rejects.toThrow('frame freshness');
+ expect(native.copies).toHaveLength(copies);
+ expect(native.finishing).toHaveLength(finishing);
+ expect(native.events.at(-1)).toMatchObject({ type: 'portos-mv:playback-error', epoch: 2 });
+ await native.api.dispose();
+ });
+
+ it('awaits real title readiness for first exact capture and cooperative preparation', async () => {
+ const id = await fixture();
+ const { document } = await generateMixedMediaDocument(id);
+ for (const cooperative of [false, true]) {
+ let release;
+ const titleFontGate = new Promise(resolve => { release = resolve; });
+ const runtime = await candidateRuntime(document, { titleFontGate });
+ let finished = false;
+ const capture = (cooperative ? runtime.api.prepare({ epoch: 1, sequence: 1, t: 1 }) : runtime.composition.seek(1))
+ .then(() => { finished = true; });
+ await new Promise(resolve => setImmediate(resolve));
+ expect(finished).toBe(false);
+ expect(runtime.copies).toEqual([]);
+ release();
+ await capture;
+ expect(runtime.copies.length).toBeGreaterThan(0);
+ await runtime.api.dispose();
+ }
+ });
+
+ it('cancels the real title font wait before visible exact work on pause or disposal', async () => {
+ const id = await fixture();
+ const { document } = await generateMixedMediaDocument(id);
+ for (const method of ['pause', 'dispose']) {
+ let release;
+ const titleFontGate = new Promise(resolve => { release = resolve; });
+ const runtime = await candidateRuntime(document, { titleFontGate });
+ const exact = runtime.composition.seek(1);
+ await new Promise(resolve => setImmediate(resolve));
+ const stopping = runtime.api[method]({ epoch: 2 });
+ expect(runtime.copies).toEqual([]);
+ expect(runtime.overlays).toEqual([]);
+ release();
+ await Promise.all([exact, stopping]);
+ expect(runtime.copies).toEqual([]);
+ expect(runtime.overlays).toEqual([]);
+ if (method !== 'dispose') await runtime.api.dispose();
+ }
+ });
+
+ it('waits for host readiness, retires pending preparation, and rejects explicit async drawing before publication', async () => {
+ const id = await fixture();
+ let release;
+ const fontGate = new Promise(resolve => { release = resolve; });
+ const { document } = await generateMixedMediaDocument(id);
+ const pending = await candidateRuntime(document, { fontGate });
+ const preparation = pending.api.prepare({ epoch: 1, sequence: 1, t: 0.5 }).catch(error => error);
+ await Promise.resolve();
+ expect(pending.copies).toEqual([]);
+ const pausing = pending.api.pause({ epoch: 2 });
+ release();
+ expect(await preparation).toMatchObject({ message: 'Generated preparation superseded' });
+ expect(await pausing).toEqual({ epoch: 2, status: 'paused' });
+ expect(pending.copies).toEqual([]);
+ await pending.api.dispose();
+
+ let rejectFonts;
+ const failingFonts = new Promise((_resolve, reject) => { rejectFonts = reject; });
+ const failed = await candidateRuntime(document, { fontGate: failingFonts });
+ const failedPreparation = failed.api.prepare({ epoch: 1, sequence: 1, t: 0.5 });
+ const failure = expect(failedPreparation).rejects.toThrow('Packaged fonts unavailable');
+ rejectFonts(new Error('Packaged fonts unavailable'));
+ await failure;
+ expect(failed.copies).toEqual([]);
+ expect(failed.events.at(-1)).toMatchObject({ type: 'portos-mv:playback-error', epoch: 1 });
+ await failed.api.dispose();
+
+ h.response = JSON.stringify({ sections: ['intro', 'still', 'clip'].map(id => ({ id, source: 'function render(ctx, env) { return Promise.resolve(); }' })) });
+ const asynchronous = await candidateRuntime((await generateMixedMediaDocument(id)).document);
+ await expect(asynchronous.api.prepare({ epoch: 1, sequence: 1, t: 0.5 })).rejects.toThrow('synchronously');
+ expect(asynchronous.copies).toEqual([]);
+ expect(asynchronous.finishing).toEqual([]);
+ expect(asynchronous.events.at(-1)).toMatchObject({ type: 'portos-mv:playback-error' });
+ await asynchronous.api.dispose();
+ });
+
it('runs authoring on the pinned provider with its effort, and drops effort for a provider that has none (#9545)', async () => {
const id = await fixture();
h.provider = { id: 'stub-provider', type: 'cli', command: 'claude' };
@@ -523,4 +684,5 @@ it('refuses ambient Three.js random helpers and their aliases while allowing det
}` }] });
const candidate = await generateMixedMediaDocument(created.id);
expect((await manifestAt(candidate.document)).renderer).toBe('three');
+ await expect(readFile(join(PATHS.data, candidate.document.directory, 'preview-playback.json'))).rejects.toMatchObject({ code: 'ENOENT' });
});
diff --git a/server/services/musicVideo/generatedCanvasPlayback.js b/server/services/musicVideo/generatedCanvasPlayback.js
new file mode 100644
index 0000000000..b79de1c3b6
--- /dev/null
+++ b/server/services/musicVideo/generatedCanvasPlayback.js
@@ -0,0 +1,145 @@
+/** Host-owned producer packaged only into deliberately new Canvas candidates. */
+import { installLayeredPreviewPlayback } from './previewPlaybackRuntime.js';
+
+// Serialized beside the generated candidate's existing renderer. Original author
+// functions retain the existing synchronous/deterministic section contract.
+function installGeneratedCanvasPlayback(composition, bridge, installScheduler) {
+ let exactLease = 0, disposed = false, playing = false;
+ const exactWork = new Set();
+ const now = performance.now.bind(performance);
+ const fail = message => { throw new Error(message); };
+ const publish = (songTime, t, scene, source, state, valid = () => true) => {
+ const started = now();
+ bridge.draw(t, scene, source, state);
+ // A section may block the event loop. Recheck after drawing, before title,
+ // film look or front pixels change; token checks alone cannot catch that.
+ if (disposed || !valid()) return false;
+ if (now() - started >= 100) fail('Generated drawing exceeded frame freshness');
+ if (playing && source && scene?.media?.kind === 'video') {
+ const latestSongTime = songTime + (now() - started) / 1000;
+ const latest = bridge.state(latestSongTime);
+ if (bridge.scene(latest.t) !== scene || latest.hold !== state.hold || (state.hold && latest.t !== t)) fail('Generated scene changed during drawing');
+ const clock = latest.hold ? latest.t : latestSongTime;
+ const end = Math.min(Number.isFinite(scene.media.outSec) ? scene.media.outSec : source.duration, source.duration);
+ const last = Math.max(0, end - 0.5 / (scene.media.fps || bridge.fps));
+ const target = Math.min(Math.max((scene.media.inSec || 0) + clock - scene.startSec, scene.media.inSec || 0), last);
+ if (source.readyState < 2 || source.seeking || !Number.isFinite(source.currentTime) || Math.abs(source.currentTime - target) >= 0.1) fail('Generated source changed during drawing');
+ }
+ bridge.finish(songTime);
+ bridge.commit();
+ return true;
+ };
+ const privateComposition = {};
+ installScheduler({
+ duration: bridge.duration, fps: bridge.fps, state: bridge.state, scene: bridge.scene,
+ source: bridge.source, needsSource: bridge.needsSource, videos: bridge.videos,
+ get ready() { return bridge.ready; },
+ publish,
+ playback(on) { playing = on; bridge.playback(on); },
+ dispose() { disposed = true; exactLease++; bridge.dispose(); },
+ }, privateComposition);
+ const scheduler = privateComposition.previewPlayback;
+ const retireExact = async () => { exactLease++; await Promise.allSettled([...exactWork]); };
+ const reply = async (method, input) => {
+ const result = await scheduler[method](input);
+ if (method === 'prepare') {
+ if (result.status !== 'prepared') fail('Generated preparation superseded');
+ return { epoch: result.epoch, sequence: input.sequence, status: result.status, t: result.t };
+ }
+ return { epoch: result.epoch, sequence: input.sequence, status: result.status,
+ ...(method === 'sync' && Number.isFinite(result.driftSec) ? { driftSec: result.driftSec } : {}) };
+ };
+ Object.defineProperty(composition, 'previewPlayback', { value: {
+ version: 1, fps: 30, presentation: 'atomic-canvas-v1', mediaTiming: 'staged-output-v1',
+ clock: () => scheduler.clock(),
+ async prepare(input) { await retireExact(); return reply('prepare', input); },
+ play: input => reply('play', input), sync: input => reply('sync', input),
+ async pause(input) { exactLease++; const result = await scheduler.pause(input); await retireExact(); return result; },
+ async dispose() {
+ exactLease++;
+ const disposal = scheduler.dispose(); // Stop native media before waiting on exact source work.
+ await Promise.all([disposal, retireExact()]);
+ return disposal;
+ },
+ } });
+ // Own readiness and finishing here instead of retaining the init-script seek
+ // wrappers: their font continuations would sit outside this cancellation lease.
+ composition.seek = (songTime, { reviewFootage = false } = {}) => {
+ const token = ++exactLease, previous = [...exactWork];
+ const operation = (async () => {
+ await Promise.allSettled(previous);
+ await bridge.ready;
+ if (token !== exactLease || disposed) return;
+ const state = bridge.state(songTime), t = state.t, scene = bridge.scene(t);
+ const source = scene && bridge.needsSource(scene) ? await bridge.source(scene, t) : null;
+ if (token !== exactLease || disposed) return;
+ bridge.draw(t, scene, source, state, reviewFootage);
+ if (token !== exactLease || disposed) return;
+ // Exact rendering retains its existing operation deadline, rather than a
+ // live freshness limit. Its source clock is paused at the requested frame.
+ bridge.finish(songTime);
+ bridge.commit();
+ })();
+ exactWork.add(operation);
+ operation.then(() => exactWork.delete(operation), () => exactWork.delete(operation));
+ return operation;
+ };
+}
+
+const BRIDGE = `
+ (${installGeneratedCanvasPlayback.toString()})(globalThis.portosComposition, {
+ get ready() { return Promise.all([ready, globalThis.__portosTitleCard?.ready?.()]); },
+ duration: DURATION, fps: FPS,
+ state: eventState, scene: sceneAt, source: sourceFor,
+ needsSource: scene => !cardFor(scene),
+ videos: () => [...videos.values()].map(entry => entry.el),
+ playback: on => globalThis.__portosFilmLook?.playback(on),
+ draw(t, scene, source, state, reviewFootage = false) {
+ if (!generatedBack) {
+ generatedBack = document.createElement('canvas');
+ generatedBack.width = W; generatedBack.height = H;
+ }
+ if (generatedBack.width !== W) generatedBack.width = W;
+ if (generatedBack.height !== H) generatedBack.height = H;
+ const front = canvas, frontContext = ctx;
+ // Keep the renderer's persistent state and paths, just as ordinary seek
+ // does. Resetting here would change inherited typography/path semantics.
+ try { canvas = generatedBack; ctx = generatedBack.getContext('2d'); render(t, scene, source, state, reviewFootage); }
+ finally { canvas = front; ctx = frontContext; }
+ },
+ finish(songTime) {
+ globalThis.__portosFilmLook?.frame(Math.round(songTime * FPS));
+ globalThis.__portosTitleCard?.draw(songTime);
+ },
+ commit() {
+ ctx.save();
+ try {
+ ctx.resetTransform(); ctx.globalAlpha = 1;
+ ctx.globalCompositeOperation = 'copy'; ctx.filter = 'none';
+ ctx.drawImage(generatedBack, 0, 0);
+ } finally { ctx.restore(); }
+ },
+ dispose() {
+ for (const entry of videos.values()) { entry.el.pause(); entry.el.removeAttribute('src'); entry.el.load(); }
+ videos.clear(); images.clear();
+ if (generatedBack) { generatedBack.width = 0; generatedBack.height = 0; generatedBack = null; }
+ },
+ }, ${installLayeredPreviewPlayback.toString()});
+`;
+
+/** Canonical host seams only; never called for an existing/imported document. */
+export function generatedCanvasPlaybackEngine(original) {
+ let source = original.toString();
+ for (const [from, to] of [
+ [" const canvas = document.getElementById('stage');", " let canvas = document.getElementById('stage');"],
+ [" const ctx = canvas.getContext('2d');", " let ctx = canvas.getContext('2d');\n let generatedBack = null;"],
+ [' W = width; H = height;', ' W = width; H = height;\n if (generatedBack) { generatedBack.width = 0; generatedBack.height = 0; generatedBack = null; }'],
+ [' authored.fn(source ? footageOverlayContext(ctx) : ctx, {', ' const drawing = authored.fn(source ? footageOverlayContext(ctx) : ctx, {'],
+ [' events: state.activeEvents, reactiveGain: state.reactiveGain, hold: state.hold,\n });', ' events: state.activeEvents, reactiveGain: state.reactiveGain, hold: state.hold,\n });\n if (drawing && typeof drawing.then === \'function\') { Promise.resolve(drawing).catch(() => {}); throw new Error(\'Generated sections must draw synchronously\'); }'],
+ ['\n})();\n', `${BRIDGE}\n})();\n`],
+ ]) {
+ if (source.split(from).length !== 2) throw new Error('Generated Canvas playback host seam changed');
+ source = source.replace(from, () => to);
+ }
+ return Buffer.from(source);
+}
diff --git a/server/services/musicVideo/previewPlaybackRuntime.js b/server/services/musicVideo/previewPlaybackRuntime.js
index 856ad0da9f..621708d88d 100644
--- a/server/services/musicVideo/previewPlaybackRuntime.js
+++ b/server/services/musicVideo/previewPlaybackRuntime.js
@@ -1,5 +1,5 @@
/** Serialized into an admitted layered preview's private engine closure. */
-export function installLayeredPreviewPlayback(bridge) {
+export function installLayeredPreviewPlayback(bridge, composition = globalThis.portosComposition) {
const FPS = 30;
const FRAME_FRESH_MS = 100;
let epoch = -1, lease = 0, sequence = -1, phase = 'idle', disposed = false, poisoned = false, motion = null;
@@ -357,5 +357,5 @@ export function installLayeredPreviewPlayback(bridge) {
return Promise.allSettled([...pending]).then(() => { bridge.dispose(); active = null; return { epoch, status: 'disposed' }; });
},
};
- Object.defineProperty(globalThis.portosComposition, 'previewPlayback', { value: api });
+ Object.defineProperty(composition, 'previewPlayback', { value: api });
}