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 new generated Three.js documents (#11656)

[._.]/99963fb0be75
diff --git a/.claude/skills/portos-music-video-code/SKILL.md b/.claude/skills/portos-music-video-code/SKILL.md
index 70a46bed6b..48f0371471 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. 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.
+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 and Three.js sections finish all drawing before returning: no Promise, deferred drawing or retained ctx; the host awaits packaged fonts and any selected media. 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/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a2c0fa8613..59b083c2eb 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -707,13 +707,25 @@ jobs:
# client bundler is missing, so a skip can never pass this step.
- name: Run cross-workspace browser suites
if: needs.impact.outputs.browser_files != '[]'
+ # The independent supervisor emits progress and owns a 12m deadline;
+ # this 15m step limit is only a fallback before the 20m job boundary.
+ timeout-minutes: 15
env:
PORTOS_BROWSER_TEST_PROFILE: ${{ github.event_name == 'pull_request' && github.base_ref != 'release' && inputs.full != true && 'smoke' || 'full' }}
+ PORTOS_CI_DIAGNOSTICS_DIR: ${{ runner.temp }}/portos-ci-diagnostics
CI_TEST_MODE: files
CI_TEST_FILES: ${{ needs.impact.outputs.browser_files }}
PORTOS_REQUIRE_BROWSER_SUITES: '1'
PORTOS_TEST_QUIET: 1
- run: node scripts/run-ci-tests.js server
+ run: node scripts/watch-ci-tests.js server
+
+ - name: Preserve browser test failure diagnostics
+ if: failure() && needs.impact.outputs.browser_files != '[]'
+ continue-on-error: true
+ timeout-minutes: 1
+ env:
+ PORTOS_CI_DIAGNOSTICS_DIR: ${{ runner.temp }}/portos-ci-diagnostics
+ run: node scripts/ci-test-diagnostics.js
- name: Report the failure, then cancel sibling CI jobs
if: failure() && github.event_name == 'pull_request'
diff --git a/docs/GITHUB_ACTIONS.md b/docs/GITHUB_ACTIONS.md
index 023417513a..c056431ea4 100644
--- a/docs/GITHUB_ACTIONS.md
+++ b/docs/GITHUB_ACTIONS.md
@@ -456,7 +456,10 @@ The selected work is split across parallel jobs:
Chrome, FFmpeg and bundler prerequisites instead of silently skipping them.
Ordinary PRs run the `smoke` profile: all existing assertions except the
explicitly tagged `[fidelity]` grading/authoring cases. Scheduled, release,
- and dispatched full runs execute every case. Profiles do not change pixels,
+ and dispatched full runs also execute ordinary fidelity cases. The explicit
+ `[local-performance]` playback case runs only in local fidelity, including when
+ hosted CI selects `full`. Hosted profiles retain generated Three render/export
+ and owned cleanup coverage. Profiles do not change pixels,
render settings, tolerances, or cleanup assertions.
A PR selecting a fidelity-owning file also requires the exact-head receipt
described below; a smoke pass alone cannot admit it.
@@ -483,7 +486,7 @@ The selected work is split across parallel jobs:
After publishing a relevant PR, run `node scripts/browser-fidelity.js --pr NUMBER`
from its clean checkout using existing `gh` authentication. This command runs the
-canonical fidelity cases automatically, retains a local receipt, and publishes
+four registered fidelity cases automatically, retains a local receipt, and publishes
an exact-commit status only after complete passing assertions and unchanged-source
verification. It binds the PR head and that commit's source tree. It does not
provision a runner, install credentials, or start PortOS.
@@ -499,11 +502,14 @@ rerun that gate job on the unchanged run once its other required jobs have passe
A receipt cannot turn a cancelled or failed browser, Windows, or containment job
green. A changed PR head requires new evidence; base-only movement does not. Hosted smoke tests the merge checkout; local fidelity proves the PR head only,
not native integration of subsequent base changes. Scheduled/release full coverage
-remains the integration check for those fidelity cases. Default
+remains the integration check for the ordinary fidelity cases; hardware-sensitive
+`[local-performance]` acceptance stays local. Default
pregate is not a substitute for this command or required CI.
-Hardware playback/GPU throughput remains distinct from these deterministic visual
-assertions. Software WebGL results do not certify physical-GPU performance, and
+The local playback case preserves full-resolution transport, frame freshness,
+preview/export parity and lens-coordinate regressions. Creative quality receives
+human review; hosted acceptance does not impose this playback performance budget.
+Software WebGL results do not certify physical-GPU performance, and
Mac-local results cannot replace Windows compatibility or Linux containment.
The profile split does not explain or repair previously unidentified hosted stalls.
diff --git a/docs/HTML_COMPOSITIONS.md b/docs/HTML_COMPOSITIONS.md
index 5994399098..45f22003ce 100644
--- a/docs/HTML_COMPOSITIONS.md
+++ b/docs/HTML_COMPOSITIONS.md
@@ -580,15 +580,14 @@ 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;
+New Canvas and Three.js candidates generated by PortOS package this complete-frame
+producer automatically. The host awaits packaged fonts and any selected media,
+draws with the existing renderer into private surfaces, and commits only the
+finished frame. Three.js retains its scene, text and lens passes and exact
+subframe timing outside narrative holds. 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
@@ -651,11 +650,10 @@ baseline, native video-frame request/cancel callbacks, and trusted finite select
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
+Previously generated documents with older or customized engines are not
+automatically opted in. Their hosts may ignore section Promise returns;
+rewriting them would change historical semantics. Generate and accept a new candidate
+to use the current generation contract. Custom authors implement the API and
re-import; historical engine adoption remains an explicit version change.
Two limits stay explicit. The lyric-overlay animatic still mounts the shipped
diff --git a/scripts/browser-fidelity.test.js b/scripts/browser-fidelity.test.js
index b73e172540..40e824cecc 100644
--- a/scripts/browser-fidelity.test.js
+++ b/scripts/browser-fidelity.test.js
@@ -36,7 +36,7 @@ function fixture({ outcome = 'passed', changed = false, dirty = false, wrongTree
expect(env.CHROME_PATH).toBe('/synthetic/chrome');
const dir = join(env.PORTOS_CI_DIAGNOSTICS_DIR, 'portos-vitest-contract');
mkdirSync(dir);
- const report = { success: true, numFailedTests: 0, numFailedTestSuites: 0, numPassedTests: 3,
+ const report = { success: true, numFailedTests: 0, numFailedTestSuites: 0, numPassedTests: 4,
testResults: Object.entries(BROWSER_FIDELITY_TESTS).map(([name, titles]) => ({ name,
assertionResults: titles.map(title => ({ title, fullName: `suite ${title}`, status: 'passed' })) })) };
if (outcome === 'skipped') report.testResults[0].assertionResults[0].status = 'pending';
@@ -65,7 +65,7 @@ describe('local fidelity publication through the existing runner and status boun
const receipt = JSON.parse(readFileSync(result.receiptPath, 'utf8'));
expect(receipt.target).toMatchObject({ head, base, tree, merge });
expect(receipt.profile.files).toEqual(BROWSER_FIDELITY_FILES);
- expect(receipt.profile.executed).toBe(3);
+ expect(receipt.profile.executed).toBe(4);
expect(f.posts[1].context.length).toBeLessThanOrEqual(100);
expect(f.posts[1].description).toMatch(/^receipt sha256=[a-f0-9]{64}$/);
expect(JSON.stringify(receipt)).not.toMatch(/synthetic credential|synthetic key/);
diff --git a/scripts/browser-suite-registry.test.js b/scripts/browser-suite-registry.test.js
index 26843a7ca6..d60aab877c 100644
--- a/scripts/browser-suite-registry.test.js
+++ b/scripts/browser-suite-registry.test.js
@@ -21,7 +21,7 @@ describe('cross-workspace browser suite registry', () => {
for (const file of BROWSER_SUITES) {
const expected = BROWSER_FIDELITY_TESTS[file] ?? [];
const source = readFileSync(join(root, file), 'utf8');
- const declarations = [...source.matchAll(/\bit\((['"`])(\[fidelity\][^\n]*?)\1/g)];
+ const declarations = [...source.matchAll(/\b(?:it|threeIt)\((['"`])(\[fidelity\][^\n]*?)\1/g)];
// Catch a marker in any registered suite, including a new registration
// shape this small literal-title extractor does not understand yet.
expect(source.match(/\[fidelity\]/g)?.length ?? 0, file).toBe(declarations.length);
@@ -29,13 +29,13 @@ describe('cross-workspace browser suite registry', () => {
title.includes('${fixture}') ? ['ramps', 'generated-shots'].map(fixture => title.replace('${fixture}', fixture)) : [title]);
expect(tags, file).toEqual(expected);
if (BROWSER_FIDELITY_ONLY_FILES.includes(file)) {
- const all = [...source.matchAll(/\bit\((['"`])([^\n]*?)\1/g)].map(([, , title]) => title);
+ const all = [...source.matchAll(/\b(?:it|threeIt)\((['"`])([^\n]*?)\1/g)].map(([, , title]) => title);
expect(all, `${file} must not hide a newly added smoke case`).toEqual(expected);
}
}
const documentSource = readFileSync(join(root, 'server/services/musicVideo/documentRender.browser.test.js'), 'utf8');
const smokeNames = [
- 'authors a local Three.js world and renders the same deterministic scene through module preview and export',
+ 'generates and exports a Three.js scene with visible authored content',
'renders a generated 3-second card/still/clip document with the selected performance in-point',
'propagates a deadline through a pending seek and waits for owned Chrome cleanup',
];
diff --git a/scripts/ci-test-diagnostics.js b/scripts/ci-test-diagnostics.js
index 2083177cd7..2aac87ca30 100644
--- a/scripts/ci-test-diagnostics.js
+++ b/scripts/ci-test-diagnostics.js
@@ -74,6 +74,11 @@ export async function collectTestDiagnostics(root, {
lines.push(`Vitest progress: reason=${reason}; completed=${run.completedCount}; unhandledErrors=${run.errorCount}.`);
lines.push(`Queued/unfinished modules (up to 100): ${run.activeModules.slice(0, 100).map(diagnosticTestFile).join(', ') || 'none recorded'}`);
lines.push(`Last completed modules (up to 100): ${run.completedModules.slice(-100).map(diagnosticTestFile).join(', ') || 'none recorded'}`);
+ // Completed outcomes survive interruptions before the final JSON report.
+ if (Array.isArray(run.moduleResults)) {
+ const results = run.moduleResults.slice(-100).filter(item => item && ['queued', 'pending', 'passed', 'failed', 'skipped', 'unavailable'].includes(item.state));
+ lines.push(`Module outcomes (up to 100): ${results.map(item => `${diagnosticTestFile(item.file)}=${item.state}`).join(', ') || 'none recorded'}`);
+ }
} catch {
lines.push('Diagnostic gap: Vitest progress unavailable; active test file is unknown.');
}
diff --git a/scripts/ci-test-diagnostics.test.js b/scripts/ci-test-diagnostics.test.js
index 2c483a26ae..f2432b9462 100644
--- a/scripts/ci-test-diagnostics.test.js
+++ b/scripts/ci-test-diagnostics.test.js
@@ -5,6 +5,7 @@ import { delimiter, join } from 'node:path';
import { pathToFileURL } from 'node:url';
import { describe, expect, it, vi } from 'vitest';
import { collectTestDiagnostics } from './ci-test-diagnostics.js';
+import vitestRunDiagnostics from './vitestRunDiagnostics.js';
import { workflowJobs } from './lib/workflowJobs.js';
const launcher = new URL('./run-ci-tests.js', import.meta.url).href;
@@ -88,6 +89,33 @@ describe('independent CI test failure recovery (#11552)', () => {
expect(output).toContain('structured test report missing');
});
+ it('recovers bounded completed outcomes without final JSON or private error details', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'ci-diagnostics-outcomes-'));
+ const prior = process.env.PORTOS_CI_DIAGNOSTICS_PATH;
+ try {
+ const attempt = join(root, 'portos-vitest-fixture'); mkdirSync(attempt);
+ const path = join(attempt, 'run.json');
+ process.env.PORTOS_CI_DIAGNOSTICS_PATH = path;
+ const hooks = vitestRunDiagnostics();
+ hooks.onInit({ onClose() {} });
+ for (let i = 0; i < 105; i++) hooks.onTestModuleEnd({ moduleId: 'server/lib/synthetic.test.js', state: () => 'passed' });
+ hooks.onTestModuleEnd({ moduleId: 'server/lib/synthetic.test.js', state: () => 'failed', errors: ['private-sentinel'] });
+ hooks.onTestModuleEnd({ moduleId: 'server/lib/unknown.test.js', state: () => 'private-sentinel' });
+ const persisted = JSON.parse(readFileSync(path, 'utf8'));
+ expect(persisted.moduleResults).toHaveLength(100);
+ expect(persisted.moduleResults.at(-1).state).toBe('unavailable');
+ expect(JSON.stringify(persisted)).not.toContain('private-sentinel');
+ const lines = await collectTestDiagnostics(root, { logger: { warn() {} }, diagnose: async () => {}, writeSummary() {} });
+ expect(lines.join('\n')).toContain('server/lib/synthetic.test.js=failed');
+ expect(lines.join('\n')).toContain('structured test report missing');
+ expect(lines.join('\n')).not.toContain('private-sentinel');
+ } finally {
+ if (prior === undefined) delete process.env.PORTOS_CI_DIAGNOSTICS_PATH;
+ else process.env.PORTOS_CI_DIAGNOSTICS_PATH = prior;
+ rmSync(root, { recursive: true, force: true });
+ }
+ });
+
it('keeps unavailable and invalid reports inconclusive even when summary and native collection fail', async () => {
const root = mkdtempSync(join(tmpdir(), 'ci-diagnostics-invalid-'));
try {
@@ -108,21 +136,30 @@ describe('independent CI test failure recovery (#11552)', () => {
} finally { rmSync(root, { recursive: true, force: true }); }
});
- it('collects after failure and before sibling cancellation with bounded, non-masking failure handling', () => {
+ it.each([
+ ['windows-server', 'Run server tests on Windows', 'Preserve Windows test failure diagnostics', 'run-ci-tests.js'],
+ ['database', 'Run cross-workspace browser suites', 'Preserve browser test failure diagnostics', 'watch-ci-tests.js'],
+ ])('%s collects after failure and before sibling cancellation with bounded, non-masking failure handling', (jobId, testName, collectorName, launcherName) => {
const workflow = readFileSync(new URL('../.github/workflows/ci.yml', import.meta.url), 'utf8');
- const windows = workflowJobs(workflow)['windows-server'];
- expect(windows).toContain('PORTOS_CI_DIAGNOSTICS_DIR: ${{ runner.temp }}/portos-ci-diagnostics');
- const start = windows.indexOf(' - name: Preserve Windows test failure diagnostics');
- expect(start).toBeGreaterThan(windows.indexOf('run: node scripts/run-ci-tests.js server'));
- const end = windows.indexOf(' - name: Report the failure, then cancel sibling CI jobs');
+ const job = workflowJobs(workflow)[jobId];
+ const start = job.indexOf(` - name: ${collectorName}`);
+ expect(start).toBeGreaterThan(job.indexOf(`run: node scripts/${launcherName} server`));
+ const end = job.indexOf(' - name: Report the failure, then cancel sibling CI jobs');
expect(end).toBeGreaterThan(start);
- const step = windows.slice(start, end);
+ const step = job.slice(start, end);
expect(step).toContain('if: failure()');
expect(step).toContain('continue-on-error: true');
expect(step).toContain('timeout-minutes: 1');
expect(step).toContain('run: node scripts/ci-test-diagnostics.js');
- const testStep = windows.slice(windows.indexOf('- name: Run server tests on Windows'), start);
+ const testStep = job.slice(job.indexOf(`- name: ${testName}`), start);
+ const durable = 'PORTOS_CI_DIAGNOSTICS_DIR: ${{ runner.temp }}/portos-ci-diagnostics';
+ expect(testStep).toContain(durable);
+ expect(step).toContain(durable);
+ const testMinutes = Number(testStep.match(/timeout-minutes:\s*(\d+)/)?.[1]);
+ const jobMinutes = Number(job.match(/^ timeout-minutes:\s*(\d+)/m)?.[1]);
+ expect(testMinutes).toBeGreaterThan(0);
+ expect(testMinutes).toBeLessThan(jobMinutes - 1);
expect(testStep).not.toContain('continue-on-error');
- expect(windows.slice(end)).toContain("if: failure() && github.event_name == 'pull_request'");
+ expect(job.slice(end)).toContain("if: failure() && github.event_name == 'pull_request'");
});
});
diff --git a/scripts/lib/browserTestProfiles.js b/scripts/lib/browserTestProfiles.js
index c8ffe1a4e2..e0124369bd 100644
--- a/scripts/lib/browserTestProfiles.js
+++ b/scripts/lib/browserTestProfiles.js
@@ -1,6 +1,7 @@
/** Browser profiles select existing assertions; they never change render settings. */
export const BROWSER_FIDELITY_TESTS = {
'server/services/musicVideo/documentRender.browser.test.js': [
+ '[fidelity] [local-performance] authors a local Three.js world and renders the same deterministic scene through module preview and export',
'[fidelity] matches bounded grades across real composed/document ramps and song-time excerpts',
'[fidelity] matches bounded grades across real composed/document generated-shots and song-time excerpts',
],
@@ -14,7 +15,8 @@ export const BROWSER_FIDELITY_FILES = Object.keys(BROWSER_FIDELITY_TESTS);
export const BROWSER_FIDELITY_ONLY_FILES = ['server/routes/musicVideoRichAuthoring.browser.test.js'];
export function browserTestProfileArgs(profile = 'full') {
- if (profile === 'full') return [];
+ // Hosted full coverage includes fidelity, but hardware-sensitive playback is local.
+ if (profile === 'full') return ['--testNamePattern=^(?!.*\\[local-performance\\]).*$'];
if (profile === 'smoke') return ['--testNamePattern=^(?!.*\\[fidelity\\]).*$'];
if (profile === 'fidelity') return ['--testNamePattern=\\[fidelity\\]'];
throw new Error(`Unknown browser test profile: ${profile}`);
diff --git a/scripts/lib/browserTestProfiles.test.js b/scripts/lib/browserTestProfiles.test.js
index 27f38051e1..c0f2cd70fa 100644
--- a/scripts/lib/browserTestProfiles.test.js
+++ b/scripts/lib/browserTestProfiles.test.js
@@ -7,7 +7,7 @@ import { dirname, join } from 'node:path';
import { assertBrowserProfileExecuted, BROWSER_FIDELITY_ONLY_FILES, BROWSER_FIDELITY_TESTS, browserTestProfileArgs, browserTestProfileFiles } from './browserTestProfiles.js';
const smokeNames = [
- 'authors a local Three.js world and renders the same deterministic scene through module preview and export',
+ 'generates and exports a Three.js scene with visible authored content',
'renders a generated 3-second card/still/clip document with the selected performance in-point',
'propagates a deadline through a pending seek and waits for owned Chrome cleanup',
];
@@ -39,10 +39,10 @@ describe('browser test profiles', () => {
});
it('requires every fidelity assertion to pass exactly once in its owning file', () => {
- expect(assertBrowserProfileExecuted('fidelity', completeReport())).toBe(3);
+ expect(assertBrowserProfileExecuted('fidelity', completeReport())).toBe(4);
const windows = completeReport();
windows.testResults.forEach(suite => { suite.name = `D:\\checkout\\${suite.name.slice('/checkout/'.length).replaceAll('/', '\\')}`; });
- expect(assertBrowserProfileExecuted('fidelity', windows)).toBe(3);
+ expect(assertBrowserProfileExecuted('fidelity', windows)).toBe(4);
for (const status of ['failed', 'skipped', 'pending', 'todo']) {
const report = completeReport();
report.testResults[0].assertionResults[0].status = status;
@@ -63,7 +63,7 @@ describe('browser test profiles', () => {
// Executes only empty synthetic Node test bodies. This pins Vitest's actual
// filtering and JSON receipt semantics, without importing browser fixtures.
- it('partitions the full assertion set into nonempty smoke and fidelity runs with real Vitest', () => {
+ it('keeps local playback in required fidelity and out of every hosted profile with real Vitest', () => {
const temp = mkdtempSync(join(tmpdir(), 'browser-profile-contract-'));
const require = createRequire(new URL('../../server/package.json', import.meta.url));
const cli = join(dirname(require.resolve('vitest/package.json')), 'vitest.mjs');
@@ -100,7 +100,8 @@ globalSetup: [${JSON.stringify(new URL('../vitestTempRootSetup.js', import.meta.
}
expect(passed.smoke).toEqual([...smokeNames].sort());
expect(passed.fidelity).toEqual(Object.values(BROWSER_FIDELITY_TESTS).flat().sort());
- expect([...passed.smoke, ...passed.fidelity].sort()).toEqual(passed.full);
+ expect([...passed.smoke, ...passed.fidelity.filter(title => !title.includes('[local-performance]'))].sort()).toEqual(passed.full);
+ expect(passed.fidelity.filter(title => title.includes('[local-performance]'))).toHaveLength(1);
} finally { rmSync(temp, { recursive: true, force: true }); }
}, 70000);
});
diff --git a/scripts/run-ci-tests.js b/scripts/run-ci-tests.js
index db62014054..e75206690f 100644
--- a/scripts/run-ci-tests.js
+++ b/scripts/run-ci-tests.js
@@ -248,12 +248,15 @@ function runNpmWithReport(scope, script, extraArgs, reportPath, env, abortSignal
const { command, args: spawnArgs } = prepareCliSpawn('npm', args, env);
return new Promise((resolve) => {
// npm is a launcher, not the entire test tree. Give this invocation its
- // own POSIX group; Windows killProcessTree uses taskkill /T instead.
- const processGroup = process.platform !== 'win32';
+ // own POSIX group; Windows killProcessTree uses taskkill /T instead. The
+ // browser supervisor instead owns the inherited group, so its independent
+ // watchdog can retire npm even if this launcher's event loop is stopped.
+ const processGroup = process.platform !== 'win32' && env.PORTOS_CI_TEST_SUPERVISED_GROUP !== '1';
const childEnv = { ...env, PORTOS_CI_DIAGNOSTICS_PATH: runReportPath };
// Only the workflow launcher owns durable attempts. Nested launcher
// fixtures must not overwrite or add to the job's failure provenance.
delete childEnv.PORTOS_CI_DIAGNOSTICS_DIR;
+ delete childEnv.PORTOS_CI_TEST_SUPERVISED_GROUP;
const child = spawn(command, spawnArgs, {
env: childEnv, cwd: repoRoot, detached: processGroup,
});
diff --git a/scripts/run-ci-tests.test.js b/scripts/run-ci-tests.test.js
index e7f827a36c..8a4aaf3fd0 100644
--- a/scripts/run-ci-tests.test.js
+++ b/scripts/run-ci-tests.test.js
@@ -95,7 +95,7 @@ it('rejects empty browser coverage except explicitly deferred smoke-only inputs'
});
describe('ci.yml shard wiring', () => {
- const runners = Object.entries(workflowJobs(WORKFLOW)).filter(([, body]) => body.includes('run-ci-tests.js'));
+ const runners = Object.entries(workflowJobs(WORKFLOW)).filter(([, body]) => /(?:run|watch)-ci-tests\.js/.test(body));
it('builds every test runner matrix from the planner and hands each slice to the runner', () => {
expect(runners.map(([id]) => id).sort()).toEqual(['client', 'database', 'server', 'windows-server']);
diff --git a/scripts/vitestRunDiagnostics.js b/scripts/vitestRunDiagnostics.js
index 4150d5bee1..8f47470b5c 100644
--- a/scripts/vitestRunDiagnostics.js
+++ b/scripts/vitestRunDiagnostics.js
@@ -10,15 +10,18 @@ function errorDiagnostic(error, depth = 0) {
return lines.filter(Boolean).join('\n').slice(0, 8000);
}
+const moduleStates = new Set(['queued', 'pending', 'passed', 'failed', 'skipped']);
+
export default function vitestRunDiagnostics() {
let diagnostics = { reason: 'not-finished', errorCount: 0, errors: [], completedCount: 0 };
const activeModules = new Set();
const completedModules = [];
+ const moduleResults = [];
const persist = () => {
const path = process.env.PORTOS_CI_DIAGNOSTICS_PATH;
if (!path) return;
persistTestDiagnostic(path, { ...diagnostics, activeModules: [...activeModules].slice(0, 100),
- completedModules, exitCode: process.exitCode ?? null });
+ completedModules, moduleResults, exitCode: process.exitCode ?? null });
};
return {
onInit(vitest) {
@@ -35,6 +38,9 @@ export default function vitestRunDiagnostics() {
activeModules.delete(file);
completedModules.push(file);
if (completedModules.length > 100) completedModules.shift();
+ const state = module.state?.();
+ moduleResults.push({ file, state: moduleStates.has(state) ? state : 'unavailable' });
+ if (moduleResults.length > 100) moduleResults.shift();
diagnostics.completedCount += 1;
persist();
},
diff --git a/scripts/vitestTempRootSetup.test.js b/scripts/vitestTempRootSetup.test.js
index 7c7743f297..8d94749e08 100644
--- a/scripts/vitestTempRootSetup.test.js
+++ b/scripts/vitestTempRootSetup.test.js
@@ -1,15 +1,20 @@
-import { appendFileSync, statSync, mkdirSync, mkdtempSync, rmSync, writeFileSync, existsSync, readFileSync, symlinkSync } from 'node:fs';
+import { appendFileSync, lstatSync, statSync, mkdirSync, mkdtempSync, rmSync, writeFileSync, existsSync, readFileSync, symlinkSync } from 'node:fs';
import { spawnSync } from 'node:child_process';
import { tmpdir } from 'node:os';
import { channel } from 'node:diagnostics_channel';
import { EventEmitter } from 'node:events';
import { fileURLToPath } from 'node:url';
import { cleanupTempDataRoots, lazyTempDataRoot } from '../server/lib/mockPathsDataRoot.js';
-import { observeOwnedBrowsers } from '../server/test/ownedBrowserDiagnostics.js';
+import { describeStageFixtureRoot, observeOwnedBrowsers, readOwnedBrowserObservations } from '../server/test/ownedBrowserDiagnostics.js';
import { join } from 'node:path';
import { afterEach, describe, expect, it, vi } from 'vitest';
import { teardown } from './vitestTempRootSetup.js';
+vi.mock('node:fs', async importOriginal => {
+ const actual = await importOriginal();
+ return { ...actual, lstatSync: vi.fn(actual.lstatSync) };
+});
+
describe('vitestTempRootSetup teardown', () => {
const originalRoot = process.env.PORTOS_TEST_TEMP_ROOT;
const originalExit = process.exitCode;
@@ -175,6 +180,57 @@ describe('vitestTempRootSetup teardown', () => {
expect(reports.join('\n')).not.toContain('private content');
});
+ it('retains exact large filesystem identities through observation and rejects rounded or malformed records', async () => {
+ const actual = await vi.importActual('node:fs');
+ const root = mkdtempSync(join(tmpdir(), 'pvt-large-identity-'));
+ process.env.PORTOS_TEST_TEMP_ROOT = root;
+ const name = 'portos-code-animation-stages-Abc123';
+ const profile = join(root, name);
+ mkdirSync(profile);
+ let ino = 18014398509481984n;
+ let dev = 18446744073709551615n;
+ lstatSync.mockImplementation((path, options) => {
+ const stat = actual.lstatSync(path, options);
+ if (path === profile) {
+ expect(options).toEqual({ bigint: true });
+ stat.ino = ino;
+ stat.dev = dev;
+ }
+ return stat;
+ });
+ const dispose = observeOwnedBrowsers(() => fileURLToPath(import.meta.url));
+ try {
+ channel('portos.composition-browser.lifecycle').publish({ event: 'allocated', profile });
+ dispose();
+ const sidecar = join(root, '.leak-owners');
+ const row = readFileSync(sidecar, 'utf8').trim().split('\n').at(-1).split('\t');
+ const recorded = JSON.parse(row[2]);
+ expect(recorded).toMatchObject({ generation: 1, dev: dev.toString(), ino: ino.toString() });
+ const project = () => {
+ const { observations, state } = readOwnedBrowserObservations(root);
+ return describeStageFixtureRoot(profile, observations.get(name), state);
+ };
+ expect(project()).toContain('generation=1 rootIdentity=matches');
+ ino += 1n; // These adjacent IDs collapse to the same floating-point Number.
+ expect(Number(ino)).toBe(Number(recorded.ino));
+ expect(project()).toContain('generation=1 rootIdentity=changed');
+ const replace = identity => writeFileSync(sidecar, `${row[0]}\t${row[1]}\t${JSON.stringify({ ...recorded, ...identity })}\n`);
+ ino = 1n; dev = 2n;
+ replace({ ino: 1, dev: 2 });
+ expect(project()).toContain('generation=1 rootIdentity=matches');
+ for (const invalid of [18014398509481984, -1, '01', '-1', '1e3', '18446744073709551616', '9'.repeat(21)]) {
+ for (const field of ['ino', 'dev']) {
+ replace({ [field]: invalid });
+ expect(project()).toContain('generation=unavailable rootIdentity=unavailable');
+ }
+ }
+ } finally {
+ dispose();
+ lstatSync.mockImplementation(actual.lstatSync);
+ rmSync(root, { recursive: true, force: true });
+ }
+ });
+
it('caps records, event history and public projection without copying private child or error values', () => {
const observations = channel('portos.composition-browser.lifecycle');
const leaked = runTeardown(root => {
diff --git a/scripts/watch-ci-tests.js b/scripts/watch-ci-tests.js
new file mode 100644
index 0000000000..9d649e8dfc
--- /dev/null
+++ b/scripts/watch-ci-tests.js
@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { collectTestDiagnostics } from './ci-test-diagnostics.js';
+import { isDirectlyInvoked } from './lib/directInvocation.js';
+import { drainBrowserProcessGroup } from '../server/services/htmlComposition/browserProcessGroup.js';
+
+// A separate event loop owns this deadline: a blocked launcher/test worker must
+// not prevent evidence collection or termination. Whole-runner loss can still
+// prevent both execution and delivery of these logs; that remains inconclusive.
+export async function watchTests(scope, {
+ env = process.env, deadlineMs = 12 * 60_000, progressMs = 60_000, graceMs = 5000, settleMs = 5000,
+} = {}) {
+ if (process.platform === 'win32') throw Error('Browser test supervision requires POSIX process groups.');
+ if (!['server', 'client'].includes(scope)) throw Error('Expected a server or client test workspace.');
+ const root = env.PORTOS_CI_DIAGNOSTICS_DIR;
+ if (!root) throw Error('Browser test supervision requires durable diagnostics.');
+ const child = spawn(process.execPath, [fileURLToPath(new URL('./run-ci-tests.js', import.meta.url)), scope], {
+ detached: true, stdio: ['ignore', 'pipe', 'pipe'], env: { ...env, PORTOS_CI_TEST_SUPERVISED_GROUP: '1' },
+ });
+ child.stdout.on('data', chunk => process.stdout.write(chunk));
+ child.stderr.on('data', chunk => process.stderr.write(chunk));
+ const started = Date.now();
+ let timedOut = false, interrupted = false, stopping, spawnError, closeResult, finish, leftovers = false;
+ const completed = new Promise(resolve => { finish = resolve; });
+ child.once('error', error => { spawnError = error; });
+ child.once('close', (code, signal) => { closeResult = { code, signal }; finish({}); });
+ let collecting;
+ const collect = () => collecting ??= collectTestDiagnostics(root, {
+ // Linux browser jobs have no Windows crash query. Keep periodic output
+ // bounded and sanitized through the same durable collector as final failure.
+ diagnose: async () => {}, writeSummary: () => {},
+ }).finally(() => { collecting = undefined; });
+ const stop = () => stopping ??= (async () => {
+ console.error('CI test watchdog: collecting evidence before owned-runner shutdown.');
+ await collect().catch(() => console.error('CI test watchdog: deadline evidence unavailable.'));
+ // Let the launcher's existing interruption path settle first, then retire
+ // its entire known-owned group even if that launcher's event loop is stuck.
+ child.kill('SIGTERM');
+ await delay(graceMs);
+ try { process.kill(-child.pid, 'SIGKILL'); }
+ catch (error) { if (error.code !== 'ESRCH') throw error; }
+ console.error('CI test watchdog: owned launcher group termination requested.');
+ const until = Date.now() + settleMs;
+ while (!closeResult) {
+ if (Date.now() >= until) throw Error('Owned launcher close unverified after SIGKILL.');
+ await delay(25);
+ }
+ await drainBrowserProcessGroup(child.pid, performance.now() + settleMs, Math.min(graceMs, settleMs / 2));
+ console.error('CI test watchdog: owned launcher group stopped; independently detached browser groups remain unverified.');
+ await collect();
+ })();
+ const requestStop = () => stop().catch(error => {
+ // A refused signal or unresponsive OS cannot prove quiescence. Fail closed
+ // with evidence; the workflow's outer deadline remains the final fallback.
+ const code = ['EPERM', 'EACCES', 'EINVAL', 'ENOSYS'].includes(error.code) ? error.code : 'unavailable';
+ console.error(`CI test watchdog: owned-runner settlement unverified; code=${code}; outer step cleanup still required.`);
+ child.stdout.destroy();
+ child.stderr.destroy();
+ child.unref();
+ finish({ error });
+ });
+ const interrupt = () => { interrupted = true; requestStop(); };
+ process.on('SIGINT', interrupt);
+ process.on('SIGTERM', interrupt);
+ const progress = setInterval(() => {
+ console.log(`CI test watchdog: ${Math.floor((Date.now() - started) / 1000)}s elapsed; deadline=${deadlineMs / 1000}s.`);
+ collect().catch(() => console.error('CI test watchdog: progress unavailable.'));
+ }, progressMs);
+ const deadline = setTimeout(() => {
+ timedOut = true;
+ console.error('CI test watchdog: subordinate deadline exceeded; this step will fail.');
+ requestStop();
+ }, deadlineMs);
+ try {
+ const { error } = await completed;
+ if (error) throw error;
+ if (!stopping && child.pid) {
+ // Only a positively closed, retained group is eligible for this existing
+ // numeric/state-only observer; it also detects stdio-detached leftovers.
+ const state = { error: 'none' };
+ await drainBrowserProcessGroup(child.pid, performance.now() + settleMs, Math.min(graceMs, settleMs / 2), state);
+ if (state.term) {
+ leftovers = true;
+ console.error('CI test watchdog: launcher closed with inherited group members remaining; this step will fail.');
+ console.error('CI test watchdog: owned launcher group stopped; independently detached browser groups remain unverified.');
+ }
+ }
+ if (stopping) await stopping;
+ if (spawnError) throw spawnError;
+ return timedOut ? 124 : interrupted ? 143 : leftovers ? 1 : closeResult.code ?? 1;
+ } finally {
+ clearInterval(progress);
+ clearTimeout(deadline);
+ process.removeListener('SIGINT', interrupt);
+ process.removeListener('SIGTERM', interrupt);
+ await collecting?.catch(() => console.error('CI test watchdog: final progress unavailable.'));
+ }
+}
+
+if (isDirectlyInvoked(import.meta.url)) {
+ try { process.exitCode = await watchTests(process.argv[2]); }
+ catch { console.error('CI test watchdog failed; owned-runner settlement is unverified.'); process.exitCode = 1; }
+}
diff --git a/scripts/watch-ci-tests.test.js b/scripts/watch-ci-tests.test.js
new file mode 100644
index 0000000000..bcfb9ba4e4
--- /dev/null
+++ b/scripts/watch-ci-tests.test.js
@@ -0,0 +1,100 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { afterAll, describe, expect, it as vitestIt } from 'vitest';
+import { setTimeout as delay } from 'node:timers/promises';
+import { ownTestBodies } from '../server/lib/mockPathsDataRoot.js';
+
+const { it, drain } = ownTestBodies(vitestIt);
+afterAll(drain);
+
+const supervisor = new URL('./watch-ci-tests.js', import.meta.url).href;
+const reporter = new URL('./vitestRunDiagnostics.js', import.meta.url).href;
+
+describe.skipIf(process.platform === 'win32')('independent browser test watchdog', () => {
+ for (const [stalled, status, denied, orphan] of [[false, 0, false, false], [false, 17, false, false], [true, 17, false, false], [true, 17, true, false], [false, 0, false, true]]) {
+ it(`preserves status or interrupts a stopped launcher with prior progress (stalled=${stalled}, status=${status}, denied=${denied}, orphan=${orphan})`, async () => {
+ const root = mkdtempSync(join(tmpdir(), 'ci-watchdog-'));
+ const reports = join(root, 'reports');
+ mkdirSync(reports);
+ try {
+ const npm = join(root, 'npm.mjs');
+ writeFileSync(npm, `
+ import reporter from ${JSON.stringify(reporter)};
+ import { writeFileSync } from 'node:fs';
+ import { spawn } from 'node:child_process';
+ const hooks = reporter();
+ hooks.onInit({ onClose() {} });
+ hooks.onTestModuleQueued({ moduleId: 'server/lib/synthetic.test.js' });
+ const orphan = ${orphan} ? spawn(process.execPath, ['-e', "process.on('SIGTERM', () => {}); setInterval(() => {}, 1000); process.send('ready');"], { stdio: ['ignore', 'ignore', 'ignore', 'ipc'] }) : null;
+ writeFileSync(${JSON.stringify(join(root, 'owned.json'))}, JSON.stringify({ worker: process.pid, launcher: process.ppid, orphan: orphan?.pid }));
+ if (orphan) { await new Promise(resolve => orphan.once('message', resolve)); orphan.disconnect(); orphan.unref(); }
+ if (${stalled}) {
+ // Stop the launcher's event loop: its own signal handler cannot help.
+ // The independent supervisor must retire the inherited known group.
+ process.on('SIGTERM', () => {});
+ process.kill(process.ppid, 'SIGSTOP');
+ setInterval(() => {}, 1000);
+ } else process.exitCode = ${status};
+ `);
+ writeFileSync(join(root, 'npm'), `#!${process.execPath}\nimport(${JSON.stringify(pathToFileURL(npm).href)});`, { mode: 0o755 });
+ const result = spawnSync(process.execPath, ['--input-type=module', '-e', `
+ import { watchTests } from ${JSON.stringify(supervisor)};
+ const kill = process.kill;
+ if (${denied}) process.kill = (pid, signal) => {
+ if (pid < 0 && signal === 'SIGKILL') throw Object.assign(Error('synthetic denied signal'), { code: 'EPERM' });
+ return kill(pid, signal);
+ };
+ try { process.exitCode = await watchTests('server', { deadlineMs: 1500, progressMs: 300, graceMs: 200 }); }
+ catch (error) { console.error('Synthetic supervisor failed closed: ' + error.message); process.exitCode = 1; }
+ `], { encoding: 'utf8', timeout: 10_000, env: { ...process.env,
+ PATH: `${root}${delimiter}${process.env.PATH}`, PORTOS_CI_DIAGNOSTICS_DIR: reports,
+ GITHUB_STEP_SUMMARY: '', GITHUB_ENV: '', NODE_DISABLE_COMPILE_CACHE: '1' } });
+ expect(result.error).toBeUndefined();
+ expect(result.status, result.stderr).toBe(denied || orphan ? 1 : stalled ? 124 : status);
+ const owned = JSON.parse(readFileSync(join(root, 'owned.json'), 'utf8'));
+ if (!denied) for (const pid of [owned.worker, owned.launcher, ...(owned.orphan ? [owned.orphan] : [])]) expect(() => process.kill(pid, 0)).toThrow();
+ if (stalled) {
+ expect(result.stdout).toContain('CI test watchdog: 0s elapsed');
+ const progress = result.stderr.indexOf('server/lib/synthetic.test.js');
+ expect(progress).toBeGreaterThanOrEqual(0);
+ expect(progress).toBeLessThan(result.stderr.indexOf('subordinate deadline exceeded'));
+ if (denied) {
+ expect(result.stderr).toContain('owned-runner settlement unverified');
+ expect(result.stderr).not.toContain('owned launcher group stopped');
+ } else {
+ expect(result.stderr).toContain('owned launcher group stopped');
+ expect(result.stderr).toContain('independently detached browser groups remain unverified');
+ }
+ expect(result.stderr).not.toContain(root);
+ } else {
+ expect(result.stderr).not.toContain('subordinate deadline exceeded');
+ if (orphan) {
+ expect(result.stderr).toContain('launcher closed with inherited group members remaining');
+ expect(result.stderr).toContain('owned launcher group stopped');
+ }
+ }
+ } finally {
+ // Even an assertion or supervisor regression must retire this fixture's
+ // positively recorded group, including a launcher stopped with SIGSTOP.
+ const ownedPath = join(root, 'owned.json');
+ if (!existsSync(ownedPath)) throw Error('Synthetic watchdog ownership unavailable; scratch retained.');
+ {
+ const { launcher } = JSON.parse(readFileSync(ownedPath, 'utf8'));
+ try { process.kill(-launcher, 'SIGKILL'); }
+ catch (error) { if (error.code !== 'ESRCH') throw error; }
+ const until = Date.now() + 5000;
+ while (true) {
+ try { process.kill(-launcher, 0); }
+ catch (error) { if (error.code === 'ESRCH') break; throw error; }
+ if (Date.now() >= until) throw Error('Synthetic watchdog group settlement unverified; scratch retained.');
+ await delay(25);
+ }
+ }
+ rmSync(root, { recursive: true, force: true });
+ }
+ }, 15000);
+ }
+});
diff --git a/server/services/codeAnimation/prompt.js b/server/services/codeAnimation/prompt.js
index 78e5326153..4b3b011438 100644
--- a/server/services/codeAnimation/prompt.js
+++ b/server/services/codeAnimation/prompt.js
@@ -461,7 +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.',
+ 'Finish all drawing before render returns. Do not return a Promise, schedule deferred drawing callbacks or retain ctx. The host awaits packaged fonts and any selected media 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 74a1d7e648..d13cc74771 100644
--- a/server/services/codeAnimation/prompt.test.js
+++ b/server/services/codeAnimation/prompt.test.js
@@ -223,10 +223,10 @@ 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');
+ if (_label.startsWith('document ')) {
+ expect(prompt).toContain('Finish all 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');
+ expect(prompt).toContain('The host awaits packaged fonts and any selected media');
}
const snapshot = songSnapshot(prompt);
expect(snapshot.beats).toEqual(project.audioAnalysis.beats);
diff --git a/server/services/htmlComposition/testBrowserCleanup.test.js b/server/services/htmlComposition/testBrowserCleanup.test.js
index 49ae012daa..ed0e8c661f 100644
--- a/server/services/htmlComposition/testBrowserCleanup.test.js
+++ b/server/services/htmlComposition/testBrowserCleanup.test.js
@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { EventEmitter } from 'node:events';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ownTestBodies } from '../../lib/mockPathsDataRoot.js';
import { _cleanupTestBrowser, _createTestArtifactsRoot, _describeTestChromeStartup, _testBrowserCleanupSettled, _testChromeProcessFacts, _waitForTestChrome, _withTestCaptureDiagnostics } from './testBrowserCleanup.js';
async function waitForFile(path, timeoutMs = 2000) {
@@ -585,6 +586,48 @@ describe('owned test Chrome cleanup', () => {
expect(vi.getTimerCount()).toBe(0);
});
+ it('retires a held evaluator before draining an aborted body even when browser disconnect stalls', async () => {
+ const proc = child(), deadline = new AbortController();
+ const evaluator = Promise.withResolvers(), disconnect = Promise.withResolvers(), entered = Promise.withResolvers();
+ const pageClosed = new Error('Owned page closed');
+ let invoke, closing, bodySettled = false, drainSettled = false;
+ const owned = ownTestBodies((_name, body) => { invoke = body; });
+ owned.it('held raw page evaluation', async () => {
+ entered.resolve();
+ try { await evaluator.promise; } finally { bodySettled = true; }
+ });
+ proc.once('exit', () => { evaluator.reject(pageClosed); disconnect.resolve(); });
+ const cleanup = vi.fn();
+ const close = () => closing ??= _cleanupTestBrowser({ browser: { close: () => disconnect.promise }, proc, cleanup });
+ const abort = () => { close().catch(() => {}); };
+ deadline.signal.addEventListener('abort', abort, { once: true });
+ const running = invoke({ signal: deadline.signal }).catch(error => error);
+ await entered.promise;
+ const draining = owned.drain().catch(error => error).finally(() => { drainSettled = true; });
+ try {
+ deadline.abort(new Error('Synthetic deadline'));
+ expect(close()).toBe(closing);
+ await vi.advanceTimersByTimeAsync(5000);
+ expect(bodySettled).toBe(false);
+ expect(drainSettled).toBe(false);
+ await vi.advanceTimersByTimeAsync(3000);
+ expect(await running).toBe(pageClosed);
+ expect(await draining).toMatchObject({ errors: [pageClosed] });
+ await expect(closing).rejects.toThrow('browser disconnect exceeded 5000ms');
+ expect(bodySettled).toBe(true);
+ expect(drainSettled).toBe(true);
+ expect(proc.kill.mock.calls).toEqual([['SIGTERM'], ['SIGKILL']]);
+ expect(cleanup).toHaveBeenCalledOnce();
+ expect(vi.getTimerCount()).toBe(0);
+ } finally {
+ deadline.signal.removeEventListener('abort', abort);
+ disconnect.resolve(); evaluator.reject(pageClosed);
+ if (proc.signalCode === null) { proc.signalCode = 'SIGTERM'; proc.emit('exit', null, 'SIGTERM'); }
+ await vi.runAllTimersAsync();
+ await Promise.allSettled([running, draining, closing]);
+ }
+ });
+
it.each([
['accepted but running', true, null, 'none', 'accepted'],
['rejected with a delivery error', false, null, 'EPERM', 'rejected'],
diff --git a/server/services/musicVideo/compositionDocument.js b/server/services/musicVideo/compositionDocument.js
index 7a726bf573..99f4c3a86e 100644
--- a/server/services/musicVideo/compositionDocument.js
+++ b/server/services/musicVideo/compositionDocument.js
@@ -1,5 +1,6 @@
import { createRequire } from 'node:module';
import { generatedCanvasPlaybackEngine } from './generatedCanvasPlayback.js';
+import { generatedThreePlaybackEngine } from './generatedThreePlayback.js';
import { createHash } from 'node:crypto';
import { assertDocumentMediaPolicy } from './documentMediaPolicy.js';
/**
@@ -402,6 +403,11 @@ export async function readLyricOverlayDocumentFiles() {
export async function stageGeneratedDocument(projectId, generatedFiles, { verifyCurrent, renderer = 'canvas' } = {}) {
if (renderer === 'three') {
const { files } = await collectTree(join(TEMPLATE_ROOT, 'spatial'), { excludeTests: true });
+ const originalEngine = await readFile(join(TEMPLATE_ROOT, 'spatial', 'engine.js'));
+ const staged = files.filter(file => file.rel !== 'engine.js');
+ staged.push({ rel: 'engine.js', data: generatedThreePlaybackEngine(originalEngine) },
+ { rel: 'engine-reference.js', data: originalEngine },
+ { rel: 'preview-playback.json', data: Buffer.from(JSON.stringify({ version: 1, contract: 'portos-complete-frame-v1' })) });
const fonts = await collectTree(join(TEMPLATE_ROOT, 'layered', 'fonts'));
const require = createRequire(import.meta.url);
const packageRoot = dirname(dirname(require.resolve('three')));
@@ -410,12 +416,12 @@ export async function stageGeneratedDocument(projectId, generatedFiles, { verify
for (const name of ['build/three.module.js', 'build/three.core.js', 'LICENSE']) {
const data = await readFile(join(packageRoot, name));
const rel = `vendor/${name.split('/').pop()}`;
- files.push({ rel, data });
+ staged.push({ rel, data });
dependencies.push({ path: rel, sha256: createHash('sha256').update(data).digest('hex') });
}
- files.push(...fonts.files.map((file) => ({ ...file, rel: `fonts/${file.rel}` })), ...generatedFiles,
+ staged.push(...fonts.files.map((file) => ({ ...file, rel: `fonts/${file.rel}` })), ...generatedFiles,
{ rel: 'dependencies.json', data: Buffer.from(JSON.stringify({ packages: [{ name: 'three', version: pkg.version, files: dependencies }], network: false })) });
- return storeVersion(projectId, files, { kind: 'generated', name: 'Authored Three.js world' }, { draft: true, verifyCurrent });
+ return storeVersion(projectId, staged, { kind: 'generated', name: 'Authored Three.js world' }, { draft: true, verifyCurrent });
}
const { files } = await collectTree(join(TEMPLATE_ROOT, 'layered'), { excludeTests: true });
const index = await readFile(join(TEMPLATE_ROOT, 'layered', 'index.html'), 'utf8');
diff --git a/server/services/musicVideo/documentGeneration.test.js b/server/services/musicVideo/documentGeneration.test.js
index 10aa093784..e341c45291 100644
--- a/server/services/musicVideo/documentGeneration.test.js
+++ b/server/services/musicVideo/documentGeneration.test.js
@@ -118,7 +118,153 @@ async function candidateRuntime(document, { reference = false, fontGate = Promis
page: { evaluate: source => runInContext(source, context) }, slow: () => { slow = true; } };
}
+async function threeCandidate(source) {
+ const created = await projects.createProject({ name: 'Synthetic spatial song', mediaMode: 'code-only' });
+ await projects.mutateProjectRecord(created.id, current => ({ project: { ...current,
+ audioAnalysis: { durationSec: 1, beats: [], downbeats: [], sections: [{ id: 'world', startSec: 0, endSec: 1 }] },
+ composition: { mode: 'document', authoringRenderer: 'three' },
+ } }));
+ h.response = JSON.stringify({ sections: [{ id: 'world', source: source || `function render(ctx, env) {
+ ctx.scene.userData.t = env.t;
+ ctx.text.fillText(JSON.stringify({ t: env.t, localT: env.localT, frame: env.frame, width: env.width, height: env.height }), 1, 2);
+ }` }] });
+ return (await generateMixedMediaDocument(created.id)).document;
+}
+
+// Run the staged module's real scene/post logic; only the GPU and DOM are doubles.
+async function threeRuntime(document, { reference = false, fontGate = Promise.resolve(), titleGate = Promise.resolve(), failDrawAt = null } = {}) {
+ const THREE = await import('three');
+ const traces = [], copies = [], renders = [], finishing = [], events = [], resources = [], overlap = [];
+ let clock = 0, slow = false, rendererDisposed = false;
+ const makeCanvas = name => {
+ const context = { reset() {}, save() {}, restore() {}, strokeText() {},
+ fillText(label) { if (label.startsWith('{')) { traces.push(JSON.parse(label)); if (slow) clock += 100; } },
+ drawImage(back) { if (name !== 'back') copies.push([name, back.width, back.height]); },
+ };
+ return { width: 0, height: 0, getContext: () => context };
+ };
+ const world = makeCanvas('world'), type = makeCanvas('type');
+ function WebGLRenderer({ canvas }) {
+ let target = null;
+ return { shadowMap: {}, setPixelRatio() {},
+ setSize(w, h) { canvas.width = w; canvas.height = h; },
+ getContext: () => ({ getExtension: () => null, getParameter: () => 'software' }),
+ initRenderTarget() {}, setRenderTarget(next) { target = next; }, clear() {},
+ render(scene) {
+ overlap.push(resources.filter(item => !item.materialDisposed).length);
+ scene.traverse(object => {
+ if (!object.isMesh || !object.material || target) return;
+ const item = { materialDisposed: false, geometryDisposed: false };
+ object.material.addEventListener('dispose', () => { item.materialDisposed = true; });
+ object.geometry.addEventListener('dispose', () => { item.geometryDisposed = true; });
+ resources.push(item);
+ });
+ if (failDrawAt !== null && scene.userData.t === failDrawAt) throw new Error('Synthetic drawing failure');
+ renders.push([scene.userData.t ?? null, target ? [target.width, target.height] : null]);
+ },
+ dispose() { rendererDisposed = true; },
+ };
+ }
+ const sandbox = { THREE: { ...THREE, WebGLRenderer }, GeometryTHREE: THREE, setTimeout, clearTimeout,
+ performance: { now: () => clock }, requestAnimationFrame: () => 1, cancelAnimationFrame() {},
+ document: { getElementById: id => id === 'world' ? world : type, createElement: () => makeCanvas('back'), fonts: { load: () => fontGate } },
+ PORTOS_MV: { render: { width: 1920, height: 1080, fps: 24, durationSec: 1 }, song: {} },
+ PORTOS_MV_EVENT_STATE: (_song, t) => ({ t: t >= 0.2 && t < 0.4 ? 0.2 : Math.floor(t * 24) / 24,
+ hold: t >= 0.2 && t < 0.4, activeEvents: [], reactiveGain: 0 }),
+ __portosFilmLook: { frame: t => finishing.push(['look', t]), playback() {} },
+ __portosTitleCard: { ready: () => titleGate, draw: t => finishing.push(['title', t]) },
+ postMessage: event => events.push(event),
+ };
+ sandbox.window = sandbox;
+ const context = createContext(sandbox), root = join(PATHS.data, document.directory);
+ const kit = (await readFile(join(root, 'toonWorld.js'), 'utf8'))
+ .replace("import * as GeometryTHREE from './vendor/three.module.js';", '').replaceAll('export ', '');
+ runInContext(`${kit}\nglobalThis.toonWorld = { createInkPass, inkShader };`, context);
+ runInContext(await readFile(join(root, 'generated.js'), 'utf8'), context);
+ const source = (await readFile(join(root, reference ? 'engine-reference.js' : 'engine.js'), 'utf8'))
+ .replace("import * as toonWorld from './toonWorld.js';", '').replaceAll('export function ', 'function ');
+ runInContext(`${source}\nmount(THREE);`, context);
+ return { composition: sandbox.portosComposition, api: sandbox.portosComposition.previewPlayback, traces, copies, renders, finishing, events, resources, overlap,
+ page: { evaluate: source => runInContext(source, context) }, slow: () => { slow = true; }, disposed: () => rendererDisposed };
+}
+
describe('treatment-driven mixed-media document authoring', () => {
+ it('packages Three through the complete-frame producer without changing exact subframe or hold rendering', async () => {
+ const document = await threeCandidate(), 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/spatial/engine.js', import.meta.url)));
+ const native = await threeRuntime(document), reference = await threeRuntime(document, { reference: true });
+ try {
+ expect(await bindAuthoredPreviewPlayback(native.page)).toMatchObject({ supported: true, fps: 30 });
+ for (const t of [0.03125, 0.3, 0.5, 0.03125]) {
+ await native.composition.seek(t); await reference.composition.seek(t);
+ }
+ expect(native.traces.map(trace => trace.t)).toEqual([0.03125, 0.2, 0.5, 0.03125]);
+ expect(native.traces).toEqual(reference.traces);
+ expect(native.renders).toEqual(reference.renders);
+ native.composition.layout({ width: 1080, height: 1920 }); reference.composition.layout({ width: 1080, height: 1920 });
+ await native.composition.seek(0.51); await reference.composition.seek(0.51);
+ expect(native.traces).toEqual(reference.traces);
+ expect(native.copies.slice(-2)).toEqual([['world', 1080, 1920], ['type', 1080, 1920]]);
+ await expect(native.api.prepare({ epoch: 1, sequence: 1, t: 0.51 })).resolves.toEqual({ epoch: 1, sequence: 1, status: 'prepared', t: 0.51 });
+ const copies = native.copies.length, finishing = native.finishing.length;
+ native.slow();
+ await expect(native.api.prepare({ epoch: 2, sequence: 2, t: 0.7 })).rejects.toThrow('frame freshness');
+ expect(native.copies).toHaveLength(copies);
+ expect(native.finishing).toHaveLength(finishing);
+ } finally { await native.api.dispose(); }
+ expect(native.disposed()).toBe(true);
+ });
+
+ it('keeps shader material ownership across fresh worlds and releases it on drawing failure or disposal', async () => {
+ const document = await threeCandidate(`function render(ctx, env) {
+ ctx.scene.userData.t = env.t;
+ ctx.scene.add(new ctx.THREE.Mesh(new ctx.THREE.BoxGeometry(), new ctx.THREE.MeshBasicMaterial()));
+ }`);
+ const runtime = await threeRuntime(document, { failDrawAt: 0.5 });
+ try {
+ await runtime.composition.seek(0);
+ expect(runtime.resources).toEqual([{ materialDisposed: false, geometryDisposed: true }]);
+ await runtime.composition.seek(0.1);
+ expect(runtime.overlap).toEqual([0, 1]);
+ expect(runtime.resources).toEqual([{ materialDisposed: true, geometryDisposed: true }, { materialDisposed: false, geometryDisposed: true }]);
+ const copies = runtime.copies.length;
+ await expect(runtime.composition.seek(0.5)).rejects.toThrow('Synthetic drawing failure');
+ expect(runtime.copies).toHaveLength(copies);
+ expect(runtime.resources.every(item => item.materialDisposed && item.geometryDisposed)).toBe(true);
+ await runtime.composition.seek(0.75);
+ expect(runtime.resources.at(-1).materialDisposed).toBe(false);
+ } finally { await runtime.api.dispose(); }
+ expect(runtime.resources.every(item => item.materialDisposed && item.geometryDisposed)).toBe(true);
+ expect(runtime.disposed()).toBe(true);
+ });
+
+ it('awaits Three and title fonts without publishing a canceled exact frame', async () => {
+ const document = await threeCandidate();
+ const font = Promise.withResolvers(), title = Promise.withResolvers();
+ const runtime = await threeRuntime(document, { fontGate: font.promise, titleGate: title.promise });
+ let exact, paused;
+ try {
+ exact = runtime.composition.seek(0.03125);
+ await new Promise(resolve => setImmediate(resolve));
+ expect(runtime.copies).toEqual([]);
+ font.resolve();
+ await new Promise(resolve => setImmediate(resolve));
+ expect(runtime.copies).toEqual([]);
+ paused = runtime.api.pause({ epoch: 1, t: 0 });
+ title.resolve();
+ await Promise.all([exact, paused]);
+ expect(runtime.copies).toEqual([]);
+ expect(runtime.finishing).toEqual([]);
+ await runtime.api.prepare({ epoch: 2, sequence: 1, t: 0.51 });
+ expect(runtime.copies).toEqual([['world', 1920, 1080], ['type', 1920, 1080]]);
+ } finally {
+ font.resolve(); title.resolve();
+ await Promise.allSettled([exact, paused]);
+ await runtime.api.dispose();
+ }
+ });
+
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(); }';
@@ -684,5 +830,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' });
+ expect(JSON.parse(await readFile(join(PATHS.data, candidate.document.directory, 'preview-playback.json'), 'utf8'))).toEqual({ version: 1, contract: 'portos-complete-frame-v1' });
});
diff --git a/server/services/musicVideo/documentRender.browser.test.js b/server/services/musicVideo/documentRender.browser.test.js
index 9d5831dbcc..14dc05ba26 100644
--- a/server/services/musicVideo/documentRender.browser.test.js
+++ b/server/services/musicVideo/documentRender.browser.test.js
@@ -88,6 +88,8 @@ describe.skipIf(!canRun)('layered template with real Chrome and ffmpeg', () => {
let browser;
let artifacts;
const detachedChromeProcessGroupId = () => process.platform === 'win32' ? undefined : proc?.pid;
+ let closingFixture;
+ const closeFixture = () => closingFixture ??= _cleanupTestBrowser({ browser, proc, artifacts, cleanup: () => {}, detachedProcessGroupId: detachedChromeProcessGroupId() });
let PATHS, encodeDocumentComposition, prepareDocumentRender, documentRenderClock, importDocumentTemplate;
let generateMixedMediaDocument, regenerateMixedMediaSection, acceptMixedMediaDocument, buildDocumentPreview, PREVIEW_MEDIA_BUDGET_BYTES, projects;
beforeAll(async () => {
@@ -121,7 +123,7 @@ describe.skipIf(!canRun)('layered template with real Chrome and ffmpeg', () => {
expect(existsSync(owned.profile), `owned capture profile removed before fixture teardown; ${lifecycle.diagnostics.describe(owned)}`).toBe(false);
}
lifecycle.fixtureWritersSettled = true;
- } finally { await _cleanupTestBrowser({ browser, proc, artifacts, cleanup: () => {}, detachedProcessGroupId: detachedChromeProcessGroupId() }); }
+ } finally { await closeFixture(); }
}, 35000);
// Uniquely catches dropped effect data, missing staged modules and preview/export curve drift.
@@ -273,7 +275,55 @@ describe.skipIf(!canRun)('layered template with real Chrome and ffmpeg', () => {
// Server-only CI does not install client dependencies; the full local install
// exercises this cross-workspace package/render contract alongside the UI proof.
const threeIt = existsSync(new URL('../../../client/node_modules/three/package.json', import.meta.url)) ? it : vitestIt.skip;
- threeIt('authors a local Three.js world and renders the same deterministic scene through module preview and export', async () => {
+ // Hosted coverage exercises the generated adapter and encoded content without
+ // certifying live playback throughput or judging creative quality.
+ threeIt('generates and exports a Three.js scene with visible authored content', async () => {
+ const created = await projects.createProject({ name: 'Synthetic generated export', mediaMode: 'code-only' });
+ await projects.mutateProjectRecord(created.id, current => ({ project: { ...current,
+ audioAnalysis: { durationSec: 1, beats: [0], downbeats: [0], sections: [{ id: 'world', label: 'World', startSec: 0, endSec: 1 }] },
+ composition: { mode: 'document', authoringRenderer: 'three' },
+ } }));
+ author.response = JSON.stringify({ sections: [{ id: 'world', source: `function render(ctx, env) {
+ const { THREE, scene, camera } = ctx;
+ camera.position.set(0, 0, 5); camera.lookAt(0, 0, 0);
+ scene.add(new THREE.Mesh(new THREE.PlaneGeometry(3, 3), new THREE.MeshBasicMaterial({ color: 0xff0000 })));
+ }` }] });
+ try {
+ const candidate = await generateMixedMediaDocument(created.id, { providerId: 'stub-provider' });
+ await acceptMixedMediaDocument(created.id, candidate.document.directory);
+ } finally { author.response = null; }
+ const project = await projects.getProject(created.id);
+ await mkdir(PATHS.music, { recursive: true }); await mkdir(PATHS.videos, { recursive: true });
+ const master = join(PATHS.music, 'generated-smoke.wav');
+ execFileSync(ffmpeg, ['-v', 'error', '-y', '-f', 'lavfi', '-i', 'sine=frequency=220:duration=1', master]);
+ const outputPath = join(PATHS.videos, 'generated-smoke.mp4');
+ const result = await encodeDocumentComposition({ project, plan: await prepareDocumentRender(project),
+ jobId: 'generated-smoke', audioPath: master, outputPath, windowStart: 0, windowEnd: 2/24 });
+ expect(result).toMatchObject({ width: 1920, height: 1080, fps: 24 });
+ const rendered = execFileSync(ffmpeg, ['-v', 'error', '-i', outputPath, '-frames:v', '1', '-vf', 'scale=64:36', '-f', 'rawvideo', '-pix_fmt', 'rgb24', '-']);
+ const center = (18 * 64 + 32) * 3;
+ expect(rendered[center]).toBeGreaterThan(150);
+ expect(rendered[center + 1]).toBeLessThan(80);
+ expect(rendered[center + 2]).toBeLessThan(80);
+ }, 60000);
+
+ threeIt('[fidelity] [local-performance] authors a local Three.js world and renders the same deterministic scene through module preview and export', async ({ signal }) => {
+ let bodyError;
+ let page;
+ const abort = () => {
+ // The cached verdict is awaited below and by suite teardown. Termination
+ // must begin before drain can wait on a blocked renderer evaluation.
+ closeFixture().catch(() => {});
+ };
+ const newPage = async options => {
+ signal.throwIfAborted();
+ const page = await browser.newPage(options);
+ if (signal.aborted) { await closeFixture(); signal.throwIfAborted(); }
+ return page;
+ };
+ signal.addEventListener('abort', abort, { once: true });
+ try {
+ signal.throwIfAborted();
const created = await projects.createProject({ name: 'Synthetic authored world', mediaMode: 'code-only' });
await projects.mutateProjectRecord(created.id, (current) => ({ project: { ...current,
audioAnalysis: { durationSec: 1, beats: [0, 0.5], downbeats: [0], sections: [{ id: 'world', label: 'World', startSec: 0, endSec: 1 }] },
@@ -288,7 +338,42 @@ describe.skipIf(!canRun)('layered template with real Chrome and ffmpeg', () => {
const preview = await buildDocumentPreview(project);
expect(preview.assets).toEqual([]);
expect(preview.html).toContain("img-src 'none'");
- const page = await browser.newPage({ viewport: { width: 1920, height: 1080 } });
+ const { readDocumentFiles } = await import('./compositionDocument.js');
+ const referenceFiles = await readDocumentFiles(project);
+ referenceFiles.set('engine.js', referenceFiles.get('engine-reference.js'));
+ // Keep only one eager WebGL world alive: retain the reference pixels, then
+ // retire its page before creating the generated preview in the same browser.
+ const referenceFrames = [];
+ let portrait;
+ const reference = await newPage({ viewport: { width: 1920, height: 1080 } });
+ try {
+ await _withTestPreviewLoadDiagnostics(reference, async markReadiness => {
+ await reference.setContent((await buildDocumentPreview(project, { files: referenceFiles })).html);
+ markReadiness();
+ await reference.waitForFunction(() => typeof window.portosComposition?.seek === 'function');
+ });
+ await reference.evaluate(() => {
+ window.priorThreeEvents = window.PORTOS_MV.song.narrativeEvents;
+ window.PORTOS_MV.song.narrativeEvents = [{ kind: 'silence', startFrame: 5, endFrame: 9 }];
+ });
+ for (const t of [0, 0.03125, 0.25, 0.5, 0.03125]) {
+ const pixels = await reference.evaluate(async t => {
+ await window.portosComposition.seek(t);
+ return { world: document.getElementById('world').toDataURL(), type: document.getElementById('type').toDataURL() };
+ }, t);
+ referenceFrames.push({ t, pixels });
+ }
+ await reference.evaluate(() => window.portosComposition.layout({ width: 1080, height: 1920 }));
+ portrait = await reference.evaluate(async () => {
+ await window.portosComposition.seek(0.03125);
+ return { world: document.getElementById('world').toDataURL(), type: document.getElementById('type').toDataURL() };
+ });
+ await reference.evaluate(() => {
+ window.PORTOS_MV.song.narrativeEvents = window.priorThreeEvents;
+ window.portosComposition.layout({ width: 1920, height: 1080 });
+ });
+ } finally { await reference.close(); }
+ page = await newPage({ viewport: { width: 1920, height: 1080 } });
const errors = []; page.on('pageerror', (error) => errors.push(error.message));
const warnings = []; page.on('console', (message) => { if (message.type() === 'warning') warnings.push(message.text()); });
await page.evaluate(() => {
@@ -314,15 +399,65 @@ describe.skipIf(!canRun)('layered template with real Chrome and ffmpeg', () => {
await window.portosComposition.seek(t);
return { world: document.getElementById('world').toDataURL(), type: document.getElementById('type').toDataURL() };
}, t);
+ await page.evaluate(() => {
+ window.priorThreeEvents = window.PORTOS_MV.song.narrativeEvents;
+ window.PORTOS_MV.song.narrativeEvents = [{ kind: 'silence', startFrame: 5, endFrame: 9 }];
+ });
+ for (const { t, pixels } of referenceFrames) expect(await at(t)).toEqual(pixels);
+ await page.evaluate(() => window.portosComposition.layout({ width: 1080, height: 1920 }));
+ expect(await at(0.03125)).toEqual(portrait);
+ await page.evaluate(() => {
+ window.PORTOS_MV.song.narrativeEvents = window.priorThreeEvents;
+ window.portosComposition.layout({ width: 1920, height: 1080 });
+ });
+ const live = await page.evaluate(async () => {
+ const api = window.portosComposition.previewPlayback;
+ const times = [], failures = [];
+ const original = window.PORTOS_MV_GENERATED.sections.world;
+ const receive = ({ data }) => { if (data?.type === 'portos-mv:playback-error') failures.push(data.message); };
+ addEventListener('message', receive);
+ window.PORTOS_MV_GENERATED.sections.world = (ctx, env) => { times.push(env.t); return original(ctx, env); };
+ try {
+ const prepared = await api.prepare({ epoch: 1, sequence: 1, t: 0 });
+ const played = await api.play({ epoch: 1, sequence: 2, t: 0, workerTime: api.clock() });
+ for (let i = 0; i < 8; i++) await new Promise(resolve => requestAnimationFrame(resolve));
+ await api.pause({ epoch: 2, t: 0 });
+ return { prepared, played, times, failures };
+ } finally { window.PORTOS_MV_GENERATED.sections.world = original; removeEventListener('message', receive); }
+ });
+ expect(live.prepared.status).toBe('prepared');
+ expect(live.played.status).toBe('playing');
+ expect(live.failures).toEqual([]);
+ expect(new Set(live.times).size).toBeGreaterThan(1);
+ const beforeCancel = await at(0);
+ await page.evaluate(() => {
+ window.originalTitleReady = window.__portosTitleCard.ready;
+ window.__portosTitleCard.ready = () => new Promise(resolve => { window.releaseThreeTitle = resolve; });
+ window.pendingThreeExact = window.portosComposition.seek(0.75);
+ });
+ try {
+ await page.waitForFunction(() => typeof window.releaseThreeTitle === 'function');
+ expect(await page.evaluate(() => ({ world: document.getElementById('world').toDataURL(), type: document.getElementById('type').toDataURL() }))).toEqual(beforeCancel);
+ await page.evaluate(async () => {
+ const paused = window.portosComposition.previewPlayback.pause({ epoch: 3, t: 0 });
+ window.releaseThreeTitle();
+ await Promise.all([paused, window.pendingThreeExact]);
+ });
+ expect(await page.evaluate(() => ({ world: document.getElementById('world').toDataURL(), type: document.getElementById('type').toDataURL() }))).toEqual(beforeCancel);
+ } finally {
+ if (!signal.aborted && !page.isClosed()) await page.evaluate(async () => {
+ window.releaseThreeTitle?.();
+ await window.pendingThreeExact;
+ window.__portosTitleCard.ready = window.originalTitleReady;
+ });
+ }
const first = await at(0);
+ const pixels = await sharp(Buffer.from(first.world.split(',')[1], 'base64')).resize(64,36).removeAlpha().raw().toBuffer();
const textures = await page.evaluate(() => window.liveTextureCount());
const moved = await at(0.5);
expect(moved.world).not.toBe(first.world);
expect(await at(0)).toEqual(first);
expect(await page.evaluate(() => window.liveTextureCount())).toBe(textures);
- const pixels = await sharp(Buffer.from(first.world.split(',')[1], 'base64')).resize(64,36).removeAlpha().raw().toBuffer();
- const orange = [...Array(pixels.length / 3).keys()].filter((i) => pixels[i*3] > pixels[i*3+2] * 1.5 && pixels[i*3] > 100).length;
- expect(orange).toBeGreaterThan(15); // authored character, not a blank backdrop/overlay-only fallback
expect(errors).toEqual([]);
// ctx.lens drives the host post stack: a wide aperture focused in front of
// the character softens every edge without allocating new GPU textures.
@@ -383,6 +518,7 @@ describe.skipIf(!canRun)('layered template with real Chrome and ffmpeg', () => {
expect(warnings.filter((text) => text.includes('PCFSoftShadowMap'))).toEqual([]);
expect(errors).toEqual([]);
await page.close();
+ signal.throwIfAborted();
await mkdir(PATHS.music, { recursive: true }); await mkdir(PATHS.videos, { recursive: true });
const master = join(PATHS.music, 'world.wav');
execFileSync(ffmpeg, ['-v', 'error', '-y', '-f', 'lavfi', '-i', 'sine=frequency=220:duration=1', master]);
@@ -391,6 +527,20 @@ describe.skipIf(!canRun)('layered template with real Chrome and ffmpeg', () => {
expect(result).toMatchObject({ width: 1920, height: 1080, fps: 24 });
const rendered = execFileSync(ffmpeg, ['-v', 'error', '-i', outputPath, '-frames:v', '1', '-vf', 'scale=64:36', '-f', 'rawvideo', '-pix_fmt', 'rgb24', '-']);
expect(rendered.reduce((sum, v, i) => sum + Math.abs(v-pixels[i]), 0) / pixels.length).toBeLessThan(15);
+ } catch (error) {
+ bodyError = error;
+ throw error;
+ } finally {
+ const cleanupErrors = [];
+ try {
+ if (!signal.aborted && page && !page.isClosed()) await page.close().catch(error => cleanupErrors.push(error));
+ // Keep the listener installed while ordinary page closure is pending.
+ // If cancellation starts there, await its cached fixture verdict too.
+ if (signal.aborted) await closeFixture().catch(error => cleanupErrors.push(error));
+ if (cleanupErrors.length) throw new AggregateError([...(bodyError ? [bodyError] : []), ...cleanupErrors],
+ 'Three test or owned browser cleanup failed', { cause: bodyError ?? cleanupErrors[0] });
+ } finally { signal.removeEventListener('abort', abort); }
+ }
}, 120000);
it('revokes idle preview media past the budget, keeps what a media element still plays, and asks again on reuse', async () => {
diff --git a/server/services/musicVideo/generatedCanvasPlayback.js b/server/services/musicVideo/generatedCanvasPlayback.js
index b79de1c3b6..98ad42b989 100644
--- a/server/services/musicVideo/generatedCanvasPlayback.js
+++ b/server/services/musicVideo/generatedCanvasPlayback.js
@@ -3,7 +3,7 @@ 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) {
+export function installGeneratedPlayback(composition, bridge, installScheduler) {
let exactLease = 0, disposed = false, playing = false;
const exactWork = new Set();
const now = performance.now.bind(performance);
@@ -87,7 +87,7 @@ function installGeneratedCanvasPlayback(composition, bridge, installScheduler) {
}
const BRIDGE = `
- (${installGeneratedCanvasPlayback.toString()})(globalThis.portosComposition, {
+ (${installGeneratedPlayback.toString()})(globalThis.portosComposition, {
get ready() { return Promise.all([ready, globalThis.__portosTitleCard?.ready?.()]); },
duration: DURATION, fps: FPS,
state: eventState, scene: sceneAt, source: sourceFor,
diff --git a/server/services/musicVideo/generatedThreePlayback.js b/server/services/musicVideo/generatedThreePlayback.js
new file mode 100644
index 0000000000..e5a0330db6
--- /dev/null
+++ b/server/services/musicVideo/generatedThreePlayback.js
@@ -0,0 +1,93 @@
+/** New Three candidates keep the spatial renderer behind the shared producer. */
+import { installGeneratedPlayback } from './generatedCanvasPlayback.js';
+import { installLayeredPreviewPlayback } from './previewPlaybackRuntime.js';
+
+const BRIDGE = `
+const draw = composition.draw;
+delete composition.draw;
+const stagedWorld = document.createElement('canvas');
+const staging = stagedWorld.getContext('2d');
+globalThis.portosComposition = composition;
+(${installGeneratedPlayback.toString()})(globalThis.portosComposition, {
+ get ready() { return Promise.all([ready, globalThis.__portosTitleCard?.ready?.()]); },
+ duration: mv.render.durationSec, fps: mv.render.fps,
+ state(requested) {
+ const state = window.PORTOS_MV_EVENT_STATE({ ...mv.song, sections: mv.song.narrativeSections }, requested, mv.render.fps);
+ // Spatial authoring uses continuous time outside narrative holds, including
+ // exact shutter subframes. The event state's frame remains quantized.
+ return { ...state, t: state.hold ? state.t : requested };
+ },
+ scene: t => authored.song.sections.find(item => t >= item.startSec && t < item.endSec) || authored.song.sections.at(-1),
+ needsSource: () => false, source: () => null, videos: () => [],
+ playback: on => globalThis.__portosFilmLook?.playback(on),
+ draw(...args) {
+ draw(...args);
+ if (stagedWorld.width !== width) stagedWorld.width = width;
+ if (stagedWorld.height !== height) stagedWorld.height = height;
+ // Resolve the WebGL drawing buffer privately, so its copy cost belongs to
+ // drawing's freshness check rather than advancing visible pixels afterward.
+ staging.globalCompositeOperation = 'copy';
+ staging.drawImage(canvas, 0, 0);
+ },
+ finish(songTime) {
+ globalThis.__portosFilmLook?.frame(Math.round(songTime * mv.render.fps));
+ globalThis.__portosTitleCard?.draw(songTime);
+ },
+ commit() {
+ for (const [front, back] of [[frontWorld, stagedWorld], [frontType, overlay]]) {
+ const context = front.getContext('2d');
+ context.globalCompositeOperation = 'copy';
+ context.drawImage(back, 0, 0);
+ }
+ },
+ dispose() {
+ for (const material of previousMaterials) material.dispose();
+ previousMaterials.clear();
+ post.dispose(); renderer.dispose();
+ canvas.width = 0; canvas.height = 0; overlay.width = 0; overlay.height = 0;
+ stagedWorld.width = 0; stagedWorld.height = 0;
+ },
+}, ${installLayeredPreviewPlayback.toString()});
+`;
+
+/** Adapt only the canonical engine copied into a deliberately new candidate. */
+export function generatedThreePlaybackEngine(original) {
+ let source = original.toString();
+ for (const [from, to] of [
+ ['const post = createPost(THREE, renderer);', 'const post = createPost(THREE, renderer);\nlet previousMaterials = new Set();'],
+ [' text.reset();\n try {', ' text.reset();\n let rendered = false;\n try {'],
+ [' drawWords(t);', ' drawWords(t);\n rendered = true;'],
+ [' for (const resource of resources) resource.dispose();', ` const materials = new Set([...resources].filter(resource => resource.isMaterial));
+ // Keep one frame's materials alive until the next fresh world has drawn,
+ // so Three can reuse shader programs before their reference count hits zero.
+ // Geometry, shadows and textures retain their immediate disposal contract.
+ for (const resource of resources) if (!resource.isMaterial) resource.dispose();
+ for (const material of previousMaterials) if (!rendered || !materials.has(material)) material.dispose();
+ if (!rendered) for (const material of materials) if (!previousMaterials.has(material)) material.dispose();
+ previousMaterials = rendered ? materials : new Set();`],
+ ["const canvas = document.getElementById('world');", "const frontWorld = document.getElementById('world');\nconst canvas = document.createElement('canvas');"],
+ ["const overlay = document.getElementById('type');", "const frontType = document.getElementById('type');\nconst overlay = document.createElement('canvas');"],
+ [' overlay.width = width; overlay.height = height;', ' overlay.width = width; overlay.height = height;\n frontWorld.width = width; frontWorld.height = height; frontType.width = width; frontType.height = height;'],
+ ['globalThis.portosComposition = {', 'const composition = {'],
+ [` async seek(requested) {
+ await ready;
+ const state = window.PORTOS_MV_EVENT_STATE({ ...mv.song, sections: mv.song.narrativeSections }, requested, mv.render.fps);
+ const t = state.hold ? state.t : requested;
+ const section = authored.song.sections.find((item) => t >= item.startSec && t < item.endSec) || authored.song.sections.at(-1);`,
+ ' draw(t, section, _source, state) {'],
+ [' fn({ THREE, scene, camera, text, lens, toonWorld },', ' const drawing = fn({ THREE, scene, camera, text, lens, toonWorld },'],
+ [' events: state.activeEvents || [], reactiveGain: state.reactiveGain ?? 1 });', " events: state.activeEvents || [], reactiveGain: state.reactiveGain ?? 1 });\n if (drawing && typeof drawing.then === 'function') { Promise.resolve(drawing).catch(() => {}); throw new Error('Generated sections must draw synchronously'); }"],
+ ['\n};\n\n}\n', `\n};\n${BRIDGE}\n}\n`],
+ [' return {\n resize(width, height) {', ` return {
+ dispose() {
+ for (const target of targets) { target.depthTexture?.dispose(); target.dispose(); }
+ for (const material of [dof, bright, blur, composite, inkOnly]) material.dispose();
+ quad.geometry.dispose(); ink.dispose();
+ },
+ resize(width, height) {`],
+ ]) {
+ if (source.split(from).length !== 2) throw new Error('Generated Three playback host seam changed');
+ source = source.replace(from, () => to);
+ }
+ return Buffer.from(source);
+}
diff --git a/server/test/ownedBrowserDiagnostics.js b/server/test/ownedBrowserDiagnostics.js
index e8115dcfe2..864370478f 100644
--- a/server/test/ownedBrowserDiagnostics.js
+++ b/server/test/ownedBrowserDiagnostics.js
@@ -25,6 +25,13 @@ const ownerFor = filepath => {
const present = profile => { try { return existsSync(profile); } catch { return 'unknown'; } };
const safeSignal = signal => signal == null ? 'none' : typeof signal === 'string' && Object.hasOwn(osConstants.signals, signal) ? signal : 'other';
const safeExit = code => code == null ? 'none' : Number.isSafeInteger(code) && Math.abs(code) <= 2147483647 ? code : 'other';
+// Filesystem identities can exceed Number's exact range, notably on Windows.
+// Retain legacy safe numeric rows, but never accept an already-rounded identity.
+const fileIdentity = value => {
+ if (Number.isSafeInteger(value) && value >= 0) return String(value);
+ return typeof value === 'string' && /^(0|[1-9]\d{0,19})$/.test(value)
+ && BigInt(value) <= 18446744073709551615n ? value : null;
+};
const elapsed = started => Math.min(86400000, Math.max(0, Math.round(performance.now() - started)));
// One interpretation for both local assertion diagnostics and persisted worker
@@ -161,8 +168,8 @@ export function observeOwnedBrowsers(getOwner) {
}
owners.set(message.profile, ownerFor(getOwner()));
if (basename(message.profile).startsWith('portos-code-animation-stages-')) {
- const { dev, ino } = lstatSync(message.profile);
- roots.set(message.profile, { v: 2, generation: roots.size + 1, dev, ino });
+ const { dev, ino } = lstatSync(message.profile, { bigint: true });
+ roots.set(message.profile, { v: 2, generation: roots.size + 1, dev: dev.toString(), ino: ino.toString() });
}
owned = diagnostics.allocate(message.profile);
}
@@ -218,8 +225,8 @@ export function readOwnedBrowserObservations(root) {
try { value = JSON.parse(encoded); } catch { observations.delete(dir); continue; }
if (dir === '.composition-observer' && value?.v === 1 && value.state === 'capped') { state = 'capped'; continue; }
const stageRoot = value?.v === 2 && /^portos-code-animation-stages-[A-Za-z0-9]+$/.test(dir)
- && ['generation', 'dev', 'ino'].every(key => Number.isSafeInteger(value[key]) && value[key] >= 0)
- && value.generation >= 1 && value.generation <= 64;
+ && Number.isSafeInteger(value.generation) && value.generation >= 1 && value.generation <= 64
+ && fileIdentity(value.dev) !== null && fileIdentity(value.ino) !== null;
const valid = (value?.v === 1 || stageRoot)
&& safeExit(value.exitCode === 'none' ? null : value.exitCode) === value.exitCode
&& safeSignal(value.signalCode === 'none' ? null : value.signalCode) === value.signalCode
@@ -257,8 +264,8 @@ export function describeStageFixtureRoot(path, value, state) {
let capped = false;
let unreadable = false;
try {
- const current = lstatSync(path);
- identity = value?.v === 2 ? (current.dev === value.dev && current.ino === value.ino ? 'matches' : 'changed') : 'unavailable';
+ const current = lstatSync(path, { bigint: true });
+ identity = value?.v === 2 ? (current.dev.toString() === fileIdentity(value.dev) && current.ino.toString() === fileIdentity(value.ino) ? 'matches' : 'changed') : 'unavailable';
const walk = (directory, category, depth) => {
if (depth > 12 || visited >= 256) { capped = true; return; }
const dir = opendirSync(directory);