Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
Music video: overlay text quality pass before the storyboard approval
Claudefd3b739bce20
diff --git a/client/src/components/musicVideo/OverlayTextCheck.jsx b/client/src/components/musicVideo/OverlayTextCheck.jsxnew file mode 100644index 0000000000..cba3f087ae--- /dev/null+++ b/client/src/components/musicVideo/OverlayTextCheck.jsx@@ -0,0 +1,70 @@+import { formatCount, formatTimecode } from '../../utils/formatters.js';++const buttonClass = 'min-h-[44px] rounded border border-port-border px-3 py-2 text-sm disabled:opacity-50';+const KIND_LABELS = { overlap: 'Collision', 'off-frame': 'Cut off', contrast: 'Hard to read', small: 'Too small' };+// The first few findings stay in view; the rest fold so the approval stays above the fold on a phone.+const SHOWN = 3;+const plural = (n, word) => `${formatCount(n)} ${word}${n === 1 ? '' : 's'}`;++function summaryOf(report) {+ switch (report.status) {+ case 'running': return { text: 'Checking the text in every shot…', tone: 'text-port-text-muted' };+ case 'none': return { text: 'Not checked yet.', tone: 'text-port-text-muted' };+ case 'interrupted': return { text: 'The last check was interrupted.', tone: 'text-port-warning' };+ case 'failed': return { text: `The check failed: ${report.error || 'no reason given'}`, tone: 'text-port-error' };+ default: break;+ }+ const { errors, warnings } = report.counts;+ if (!report.findings.length) return { text: `No problems in ${plural(report.textSamples ?? 0, 'frame')} with text.`, tone: 'text-port-success' };+ const parts = [errors ? plural(errors, 'problem') : null, warnings ? `${formatCount(warnings)} to improve` : null].filter(Boolean);+ return { text: `${parts.join(', ')}.`, tone: errors ? 'text-port-error' : 'text-port-warning' };+}++/**+ * The overlay text quality pass on the storyboard approval: a one-line verdict,+ * the findings (each with its time, which plays the preview there), and a+ * button to run it again. Advice like the camera notes: it never blocks approval.+ */+export default function OverlayTextCheck({ report, onCheck, busy = false, onSeek = null }) {+ if (!report) return null;+ const running = report.status === 'running';+ const stale = report.status === 'complete' && !report.current;+ const summary = summaryOf(report);+ const renderFinding = (finding) => (+ <li key={finding.id} className="min-w-0">+ <div className="flex flex-wrap items-center gap-x-2">+ <span className={`font-medium ${finding.severity === 'error' ? 'text-port-error' : 'text-port-warning'}`}>{KIND_LABELS[finding.kind] || finding.kind}</span>+ {onSeek+ ? <button type="button" onClick={() => onSeek(finding.atSec)} aria-label={`Play ${formatTimecode(finding.atSec)} in the preview`}+ className="min-h-[44px] text-port-accent underline sm:min-h-0">{formatTimecode(finding.atSec)}</button>+ : <span>{formatTimecode(finding.atSec)}</span>}+ {finding.sceneLabel && <span className="min-w-0 break-words text-xs text-port-text-muted">{finding.sceneLabel}</span>}+ {finding.count > 1 && <span className="text-xs text-port-text-muted">seen {formatCount(finding.count)} times</span>}+ </div>+ <p className="break-words text-xs text-port-text-muted">{finding.message}</p>+ </li>+ );+ const shown = report.findings.slice(0, SHOWN);+ const folded = report.findings.slice(SHOWN);+ return (+ <div role="group" aria-label="Overlay text check" className="mt-2 min-w-0 rounded border border-port-border p-2 text-sm">+ <div className="flex flex-wrap items-center gap-2">+ <p className="min-w-0 flex-1 break-words">+ <strong>Overlay text</strong> · <span role="status" className={summary.tone}>{summary.text}</span>+ {stale && <span className="text-port-text-muted"> This was the earlier version; check again.</span>}+ </p>+ <button type="button" className={buttonClass} disabled={busy || running} onClick={onCheck}>+ {running ? 'Checking…' : report.status === 'none' ? 'Check overlay text' : 'Check again'}+ </button>+ </div>+ {shown.length > 0 && <ul aria-label="Overlay text findings" className={`mt-2 space-y-2 ${stale ? 'opacity-70' : ''}`}>{shown.map(renderFinding)}</ul>}+ {folded.length > 0 && (+ <details className="mt-1">+ <summary className="flex min-h-[44px] cursor-pointer items-center text-xs text-port-accent sm:min-h-0">{formatCount(folded.length)} more</summary>+ <ul className={`mt-2 space-y-2 ${stale ? 'opacity-70' : ''}`}>{folded.map(renderFinding)}</ul>+ </details>+ )}+ <p className="mt-1 text-xs text-port-text-muted">Looks at every lyric and shot for text that collides, runs off the frame, blends into the picture or is too small on a phone. It doesn't block approval.</p>+ </div>+ );+}diff --git a/client/src/components/musicVideo/OverlayTextCheck.test.jsx b/client/src/components/musicVideo/OverlayTextCheck.test.jsxnew file mode 100644index 0000000000..a4d33ce197--- /dev/null+++ b/client/src/components/musicVideo/OverlayTextCheck.test.jsx@@ -0,0 +1,39 @@+import { describe, it, expect, vi } from 'vitest';+import { fireEvent, render, screen } from '@testing-library/react';+import OverlayTextCheck from './OverlayTextCheck.jsx';++const counts = (errors = 0, warnings = 0) => ({ errors, warnings });+const finding = (n, kind = 'overlap', severity = 'error') => ({ id: `f${n}`, kind, severity, atSec: 60 + n, times: [60 + n], count: 2,+ sceneLabel: 'Cliff', texts: ['20 MILLION YEARS', 'WHOLE SPECIES'], message: `Finding ${n}: “20 MILLION YEARS” collides with “WHOLE SPECIES”.` });++describe('OverlayTextCheck', () => {+ it('offers a first check, then shows the findings with times that play the preview, folding past three', () => {+ const onCheck = vi.fn();+ const onSeek = vi.fn();+ const { rerender } = render(<OverlayTextCheck report={{ status: 'none', current: false, findings: [], counts: counts() }} onCheck={onCheck} onSeek={onSeek} />);+ fireEvent.click(screen.getByRole('button', { name: 'Check overlay text' }));+ expect(onCheck).toHaveBeenCalledOnce();++ rerender(<OverlayTextCheck report={{ status: 'running', current: true, findings: [], counts: counts() }} onCheck={onCheck} onSeek={onSeek} />);+ expect(screen.getByRole('button', { name: 'Checking…' }).disabled).toBe(true);++ const findings = [finding(1), finding(2, 'contrast', 'warning'), finding(3, 'small', 'warning'), finding(4, 'off-frame')];+ rerender(<OverlayTextCheck report={{ status: 'complete', current: true, textSamples: 40, findings, counts: counts(2, 2) }} onCheck={onCheck} onSeek={onSeek} />);+ expect(screen.getByRole('status').textContent).toBe('2 problems, 2 to improve.');+ expect(screen.getByRole('list', { name: 'Overlay text findings' }).children).toHaveLength(3);+ expect(screen.getByText('1 more')).toBeTruthy();+ expect(screen.getByText('Hard to read')).toBeTruthy();+ fireEvent.click(screen.getByRole('button', { name: 'Play 1:01.00 in the preview' }));+ expect(onSeek).toHaveBeenCalledWith(61);+ });++ it('says when the text is clean, when the result is for an earlier version, and why a check failed', () => {+ const { rerender } = render(<OverlayTextCheck report={{ status: 'complete', current: true, textSamples: 1234, findings: [], counts: counts() }} onCheck={() => {}} />);+ expect(screen.getByRole('status').textContent).toBe('No problems in 1,234 frames with text.');+ rerender(<OverlayTextCheck report={{ status: 'complete', current: false, textSamples: 3, findings: [finding(1)], counts: counts(1) }} onCheck={() => {}} />);+ expect(screen.getByText(/earlier version/)).toBeTruthy();+ rerender(<OverlayTextCheck report={{ status: 'failed', current: false, error: 'Managed browser is unavailable', findings: [], counts: counts() }} onCheck={() => {}} />);+ expect(screen.getByRole('status').textContent).toBe('The check failed: Managed browser is unavailable');+ expect(screen.getByRole('button', { name: 'Check again' })).toBeTruthy();+ });+});diff --git a/client/src/components/musicVideo/ProductionReviewPanel.jsx b/client/src/components/musicVideo/ProductionReviewPanel.jsxindex 5ffb365451..00f40ab09f 100644--- a/client/src/components/musicVideo/ProductionReviewPanel.jsx+++ b/client/src/components/musicVideo/ProductionReviewPanel.jsx@@ -1,5 +1,6 @@import { useEffect, useState } from 'react';import ProductionReviewContext from './ProductionReviewContext.jsx';+import OverlayTextCheck from './OverlayTextCheck.jsx';import { formatTimecode } from '../../utils/formatters.js';import { summarizeStoryboardProblems } from '../../lib/musicVideoStages.js';@@ -247,6 +248,9 @@ export default function ProductionReviewPanel({ project, review, onOpenArtifact,<p>Camera notes (they don't block approval):</p><ul className="list-disc pl-5">{ready.storyboard.camera.notes.map(note => <li key={note}>{note}</li>)}</ul></div>}+ {/* The overlay text pass (document compositions): advice too, shown before the shot list. */}+ {key === 'storyboard' && ready?.storyboard.text && <OverlayTextCheck report={ready.storyboard.text} busy={review.busy}+ onCheck={() => review.checkOverlayText()} onSeek={onSeek} />}{key === 'proof' ? proofContent : <ProductionReviewContext stage={key} project={project} onOpenArtifact={onOpenArtifact} onArtReady={available => setVisibleArt(available ? artIdentity : null)} onSeek={onSeek} />}{openRequests(key).length > 0 && <div role="group" aria-label={`${label} change requests`} className="mt-2 space-y-2 rounded border border-port-warning p-2"><p className="text-sm">Resolve these change requests to approve.</p>diff --git a/client/src/hooks/useMusicVideoProductionReview.js b/client/src/hooks/useMusicVideoProductionReview.jsindex ba45d3dacd..89285ce350 100644--- a/client/src/hooks/useMusicVideoProductionReview.js+++ b/client/src/hooks/useMusicVideoProductionReview.js@@ -1,5 +1,5 @@import { useEffect, useRef, useState } from 'react';-import { reverifyMusicVideoAlignment, importMusicVideoDocumentShots, getMusicVideoProductionReview, saveMusicVideoProductionDraft, prepareMusicVideoProductionReview,+import { checkMusicVideoOverlayText, reverifyMusicVideoAlignment, importMusicVideoDocumentShots, getMusicVideoProductionReview, saveMusicVideoProductionDraft, prepareMusicVideoProductionReview,approveMusicVideoProductionReview, renderMusicVideoProductionProof, musicVideoExcerptRenderEventsUrl,cancelMusicVideoExcerptRender, importMusicVideoProductionPlanning, bindMusicVideoProductionShot, addMusicVideoProductionFeedback, resolveMusicVideoProductionFeedback, reviseMusicVideoProductionFromFeedback, revertMusicVideoProductionInput } from '../services/apiMusicVideo.js';import useSseJobSlot from './useSseJobSlot.js';@@ -68,6 +68,8 @@ export default function useMusicVideoProductionReview({ project, replaceProjectimportDocumentShots: body => call(() => importMusicVideoDocumentShots(project.id, body, { silent: true })),importPlanning: source => call(() => importMusicVideoProductionPlanning(project.id, source, { silent: true })),bindShot: shotId => call(() => bindMusicVideoProductionShot(project.id, shotId, { silent: true })),+ // Starts the overlay text check; its result arrives on the project push when it finishes.+ checkOverlayText: () => call(() => checkMusicVideoOverlayText(project.id, { silent: true })),reverifyAlignment: notes => call(() => reverifyMusicVideoAlignment(project.id, { basis: readiness?.alignment.basis, notes }, { silent: true })),save: draft => call(() => saveMusicVideoProductionDraft(project.id, draft, { silent: true })),prepare: () => call(() => prepareMusicVideoProductionReview(project.id, {}, { silent: true })),diff --git a/client/src/lib/musicVideoAutonomous.js b/client/src/lib/musicVideoAutonomous.jsindex 1fbd74885a..8557681a8b 100644--- a/client/src/lib/musicVideoAutonomous.js+++ b/client/src/lib/musicVideoAutonomous.js@@ -198,6 +198,7 @@ export const AUTONOMOUS_SONG_STEP_LABELS = Object.freeze({/** What the Produce stage is doing once production is done (the server's `stages.produce.step`). */export const AUTONOMOUS_PRODUCE_STEP_LABELS = Object.freeze({+ 'text-check': 'Checking the overlay text',rendering: 'Rendering final video','final-review': 'The orchestrator is watching the final video','final-revision': 'Revising the sections the orchestrator flagged',diff --git a/client/src/services/apiMusicVideo.js b/client/src/services/apiMusicVideo.jsindex 699f2353cf..f4ae746b5b 100644--- a/client/src/services/apiMusicVideo.js+++ b/client/src/services/apiMusicVideo.js@@ -519,6 +519,7 @@ export const applyMusicVideoAudioTiming = (id, data, options = {}) => request(`/// Human-reviewed production planning and proof. These never accept approval state in a project PATCH.export const getMusicVideoProductionReview = (id, options = {}) => request(`/music-video/${encodeURIComponent(id)}/production-review`, options);+export const checkMusicVideoOverlayText = (id, options = {}) => request(`/music-video/${encodeURIComponent(id)}/production-review/text-check`, { method: 'POST', ...options });export const reverifyMusicVideoAlignment = (id, body, options = {}) => request(`/music-video/${encodeURIComponent(id)}/production-review/alignment`, { method: 'POST', body: JSON.stringify(body), ...options });export const saveMusicVideoProductionDraft = (id, body, options = {}) => request(`/music-video/${encodeURIComponent(id)}/production-review`, { method: 'PUT', body: JSON.stringify(body), ...options });export const prepareMusicVideoProductionReview = (id, body = {}, options = {}) => request(`/music-video/${encodeURIComponent(id)}/production-review/prepare`, { method: 'POST', body: JSON.stringify(body), ...options });diff --git a/docs/features/music-video-autonomous.md b/docs/features/music-video-autonomous.mdindex 7fe784dc63..ae2a5d8b02 100644--- a/docs/features/music-video-autonomous.md+++ b/docs/features/music-video-autonomous.md@@ -104,6 +104,7 @@ Choose **Who reviews each step → Orchestrator** in the start drawer to let a m| Art direction | **Produce** | Reads the cast, environments, visual and motion guides (and the guide sheet when it is an image and the model can see), approves or rewrites fields || Lyric timing | **Produce** | Verifies the aligned timings when every line carries bounded word timings, alignment ran without error and the recognizer heard at least half of the words; otherwise leaves them for a director || Storyboard | **Produce** | Anchors shots to the lyric lines they overlap, fills blank fields, approves or files change requests that re-plan the named shots, then resolves them |+| Overlay text | before the final render | Runs the overlay text check (the same one the storyboard approval shows): samples the film at each lyric line and shot and flags text that collides with other text, runs off the frame, blends into the picture (WCAG contrast against the pixels behind it, an ink outline wide enough on a phone counts) or is too small at 390px. A generated document with errors is re-authored with the findings as timecoded change requests (`text@m:ss`) while revisions remain; an imported document only gets the findings noted (`stages.produce.step: 'text-check'`) || Final video | after the final render | Looks at 24 frames sampled across the film (when the model can see). A `revise` with timecoded issues sends those sections back while revisions remain: a code or document film is re-authored with the issues as change requests on the film; footage gets an auto-review over the scenes the issues fall in, judged by the orchestrator and limited to the generations production left (not run when a dollar budget is set, which only production can enforce). The film is rendered again and reviewed again (`stages.produce.step: 'final-revision'`, `output.finalAutoReviewId`). Stop, Cancel and Resume carry through to that auto-review; one that hands off to a director (or fails) parks the run with its reason (`FINAL_REVISION_NEEDS_HUMAN`), and Resume renders and reviews the film again once that revision is finished or cancelled (pressed earlier, the run stays parked) |Production's plate and draft reviews use the orchestrator too. Each decision lands in `run.orchestration.reviews` (`checkpoint`, `verdict` of `approve`/`revise`/`retake`/`noted`, `score`, `notes`, `changes`, `issues`, `route`), which the run panel shows as a decision log. When the revision limit is reached the latest version is accepted and the note says so. Each revision is stored with its log entry (`output.lyricsForReview`, `output.styleDraft`), so a Retry after a failed review judges the latest revision rather than the first draft. A storyboard re-plan that fails fails the stage (`ORCHESTRATOR_REVISION_FAILED`) instead of approving the unchanged shot; Retry asks the orchestrator again. A readiness problem the orchestrator cannot fix still parks the run for a human, with the problem named. The orchestrator never publishes.diff --git a/server/lib/musicVideoAutonomous.js b/server/lib/musicVideoAutonomous.jsindex d79f1ab897..d7fd92ad1d 100644--- a/server/lib/musicVideoAutonomous.js+++ b/server/lib/musicVideoAutonomous.js@@ -112,6 +112,8 @@ export const ORCHESTRATOR_CHECKPOINTS = Object.freeze([Object.freeze({ id: 'art', label: 'Art direction' }),Object.freeze({ id: 'alignment', label: 'Lyric timing' }),Object.freeze({ id: 'storyboard', label: 'Storyboard' }),+ // Measured, not judged: the overlay text check before the final render (overlayTextService.js).+ Object.freeze({ id: 'text', label: 'Overlay text' }),Object.freeze({ id: 'final', label: 'Final video' }),]);export const ORCHESTRATOR_CHECKPOINT_IDS = Object.freeze(ORCHESTRATOR_CHECKPOINTS.map((c) => c.id));diff --git a/server/routes/musicVideo.js b/server/routes/musicVideo.jsindex e1aa60dc72..d9bf9bcb96 100644--- a/server/routes/musicVideo.js+++ b/server/routes/musicVideo.js@@ -697,6 +697,14 @@ router.post('/:id/production-review/revise', asyncHandler(async (req, res) => {router.post('/:id/production-review/revert', asyncHandler(async (req, res) => {res.json(await revertProductionInput(req.params.id, validateRequest(musicVideoProductionRevertSchema, req.body)));}));+// The overlay text quality pass: render the composition document at its text+// moments and flag collisions, cut-off, low contrast and phone-size text.+router.post('/:id/production-review/text-check', asyncHandler(async (req, res) => {+ const { startOverlayTextCheck } = await import('../services/musicVideo/overlayTextService.js');+ const { project, readiness } = await startOverlayTextCheck(req.params.id);+ res.status(202).json({ project, readiness });+}));+router.get('/:id/production-review', asyncHandler(async (req, res) => {res.json(await getProductionReview(req.params.id));}));@@ -781,6 +789,14 @@ const requireProject = async (id) => {return project;};+// A new document gets its overlay text checked in the background, so the+// findings are waiting at the storyboard approval (local browser work, no provider).+const checkOverlayTextAfterImport = (projectId) => {+ import('../services/musicVideo/overlayTextService.js')+ .then(({ checkOverlayTextInBackground }) => checkOverlayTextInBackground(projectId))+ .catch((err) => console.error(`❌ Overlay text check did not start: ${err.message}`));+};+const documentZipUpload = uploadSingle('file', {limits: { fileSize: DOCUMENT_ZIP_MAX_BYTES },fileFilter: (_req, file, cb) => {@@ -797,6 +813,7 @@ router.post('/:id/composition/document/zip', documentZipUpload, asyncHandler(asyif (!req.file) throw new ServerError('No file uploaded (multipart field "file")', { status: 400, code: 'VALIDATION_ERROR' });try {res.status(201).json(await importDocumentZip(req.params.id, req.file.path, req.file.originalname));+ checkOverlayTextAfterImport(req.params.id);} finally {await unlink(req.file.path).catch(() => {});}@@ -805,6 +822,7 @@ router.post('/:id/composition/document/zip', documentZipUpload, asyncHandler(asyrouter.post('/:id/composition/document/directory', asyncHandler(async (req, res) => {const { directory } = validateRequest(musicVideoDocumentDirectoryImportSchema, req.body || {});res.status(201).json(await importDocumentDirectory(req.params.id, directory));+ checkOverlayTextAfterImport(req.params.id);}));router.post('/:id/composition/document/template', asyncHandler(async (req, res) => {@@ -840,6 +858,7 @@ router.post('/:id/composition/document/sections/:sectionId/regenerate', asyncHanrouter.post('/:id/composition/document/accept', asyncHandler(async (req, res) => {const { directory } = validateRequest(musicVideoDocumentCandidateSchema, req.body || {});res.json(await acceptMixedMediaDocument(req.params.id, directory));+ checkOverlayTextAfterImport(req.params.id);}));router.delete('/:id/composition/document/candidate', asyncHandler(async (req, res) => {diff --git a/server/routes/musicVideoRichAuthoring.browser.test.js b/server/routes/musicVideoRichAuthoring.browser.test.jsindex f1633eb671..aa24f21177 100644--- a/server/routes/musicVideoRichAuthoring.browser.test.js+++ b/server/routes/musicVideoRichAuthoring.browser.test.js@@ -21,6 +21,8 @@ import { browserSuiteCanRun } from '../lib/browserSuiteGate.js';vi.mock('../lib/paths.js', async original => makePathsProxy(await original(), { dataRoot: () => lazyTempDataRoot('mv-rich-ui-browser-') }));vi.mock('../services/instanceIdentity.js', () => ({ ensureInstanceId: async () => 'synthetic-instance' }));+// Accepting a document starts a background overlay text check (its own browser); this suite pins the authoring UI.+vi.mock('../services/musicVideo/overlayTextService.js', () => ({ checkOverlayTextInBackground: () => {}, startOverlayTextCheck: async () => { throw new Error('not in this suite'); } }));vi.mock('../services/settings.js', () => ({ getSettings: async () => ({}) }));vi.mock('../services/auth.js', () => ({ isAuthEnabled: async () => true, verifyRequestSessionIdentity: async () => ({ kind: 'session', sessionId: 'synthetic-browser', label: null }) }));let endpoint;diff --git a/server/services/htmlComposition/browser.js b/server/services/htmlComposition/browser.jsindex 629f587c84..a9289bcf61 100644--- a/server/services/htmlComposition/browser.js+++ b/server/services/htmlComposition/browser.js@@ -90,7 +90,9 @@ async function readSlice(asset, start, end) {} finally { await handle.close(); }}-export async function openComposition(directory, { signal, validateAssets, streamMedia = false, mediaMode = 'code-images-video', ownedBrowser = false } = {}) {+// `initScripts` run in every new document before its own scripts, after the+// sandbox guards (a read-only probe such as the overlay text check).+export async function openComposition(directory, { signal, validateAssets, streamMedia = false, mediaMode = 'code-images-video', ownedBrowser = false, initScripts = [] } = {}) {const assets = await snapshotAssets(directory, { streamMedia });validateAssets?.(assets);signal?.throwIfAborted();@@ -98,7 +100,7 @@ export async function openComposition(directory, { signal, validateAssets, streaconst { launchCompositionBrowser } = await import('./ownedBrowser.js');const owner = await launchCompositionBrowser({ signal });try {- const page = await connectComposition(assets, { signal, mediaMode,+ const page = await connectComposition(assets, { signal, mediaMode, initScripts,version: { webSocketDebuggerUrl: owner.webSocketDebuggerUrl, 'User-Agent': 'HeadlessChrome/' } });return { ...page, close: async options => {try { await page.close(options); } finally { await owner.close(); }@@ -111,10 +113,10 @@ export async function openComposition(directory, { signal, validateAssets, streaconst response = await cdpRequest('/json/version');if (!response.ok) throw new Error('Managed browser is unavailable');const version = await response.json();- return connectComposition(assets, { signal, mediaMode, version });+ return connectComposition(assets, { signal, mediaMode, version, initScripts });}-async function connectComposition(assets, { signal, mediaMode, version }) {+async function connectComposition(assets, { signal, mediaMode, version, initScripts = [] }) {const { webSocketDebuggerUrl } = version;if (!webSocketDebuggerUrl) throw new Error('Managed browser has no CDP endpoint');const ws = new WebSocket(webSocketDebuggerUrl, { handshakeTimeout: 10000 });@@ -326,6 +328,7 @@ async function connectComposition(assets, { signal, mediaMode, version }) {}}})();` });+ for (const source of initScripts) await send('Page.addScriptToEvaluateOnNewDocument', { source });await send('Fetch.enable', { patterns: [{ urlPattern: '*', requestStage: 'Request' }] });const navigation = await send('Page.navigate', { url: `${ORIGIN}/index.html` });if (navigation.errorText) throw new Error(`Composition navigation failed: ${navigation.errorText}`);diff --git a/server/services/musicVideo/autonomousService.js b/server/services/musicVideo/autonomousService.jsindex cbe021773c..84326b849c 100644--- a/server/services/musicVideo/autonomousService.js+++ b/server/services/musicVideo/autonomousService.js@@ -140,6 +140,8 @@ const defaults = {reviseFromFeedback: async (...args) => (await import('./productionReviewService.js')).reviseProductionFromFeedback(...args),guideImagePath: async (artifact) => (await import('./devArtifactStore.js')).resolveDevArtifactFile(artifact.file),finalReviewFrames: async (jobId) => (await import('./orchestratorReview.js')).captureFinalReviewFrames(jobId),+ // The overlay text pass before a final render: resolves the finished check.+ checkOverlayText: async (projectId) => (await import('./overlayTextService.js')).startOverlayTextCheck(projectId).then((started) => started.done),// The final-video revision of footage: a board-owned auto-review over the flagged window.startAutoReview: async (...args) => (await import('./autoReviewService.js')).startAutoReview(...args),cancelAutoReview: async (...args) => (await import('./autoReviewService.js')).cancelAutoReview(...args),@@ -259,6 +261,9 @@ const ideaOf = (run) => ({ prompt: run.brief.prompt, guidance: run.brief.guidancconst orchestratorIdentity = (run, route) => ({ kind: 'orchestrator', runId: run.id,providerId: route?.providerId || run.brief.orchestrator.providerId, model: route?.model || run.brief.orchestrator.model || null,authorizedBy: run.brief.orchestratorAuthorizedBy || null });+// Who acts on the run's own change requests: its orchestrator, else the autopilot.+const runReviewer = (run) => (isOrchestratedRun(run) ? orchestratorIdentity(run)+ : { kind: 'autopilot', runId: run.id, authorizedBy: run.brief.autoApproveAuthorizedBy || null });/*** Append one decision to the run's review log (oldest dropped past the cap).@@ -497,7 +502,7 @@ async function settleLyricTiming(projectId, run) {await record('revise', `${notes} ${held}`);return `${notes} ${held}`;}- const reviewer = orchestrated ? orchestratorIdentity(run) : { kind: 'autopilot', runId: run.id, authorizedBy: run.brief.autoApproveAuthorizedBy || null };+ const reviewer = runReviewer(run);await deps.verifyAlignment(projectId, { basis: productionAlignmentBasis(project), notes, reviewer });await record('approve', notes);}@@ -720,12 +725,12 @@ async function startFinalRevision(projectId, run, issues) {return 'wait';}-async function reauthorFinal(projectId, run, issues) {+async function reauthorFinal(projectId, run, issues, { target = 'final' } = {}) {const project = await getProject(projectId);const basis = productionReviewBasis(project).proof;const before = new Set((project.productionReview?.feedback || []).map((f) => f.id));for (const issue of issues.slice(0, 12)) {- await deps.addFeedback(projectId, { stage: 'proof', basis, target: `final@${timecode(issue.atSec)}`, text: issue.text, decision: 'request-changes' });+ await deps.addFeedback(projectId, { stage: 'proof', basis, target: `${target}@${timecode(issue.atSec)}`, text: issue.text, decision: 'request-changes' });}const authoring = !run.brief.llmStages?.authoring && run.brief.authoring ? run.brief.authoring : await llmOf(run, 'authoring');const input = { providerId: authoring.providerId, model: authoring.model || undefined, ...(authoring.effort ? { effort: authoring.effort } : {}) };@@ -736,11 +741,57 @@ async function reauthorFinal(projectId, run, issues) {})().then(() => null, (err) => err);// Requests stay open through authoring (the prompt carries them), then close either way.const created = ((await getProject(projectId)).productionReview?.feedback || []).filter((f) => !before.has(f.id) && !f.resolvedAt);- const resolution = failure ? `The re-authoring failed (${trimTo(failure.message, 200)}); kept the film.` : 'Re-authored by the orchestrator.';- for (const entry of created) await deps.closeFeedback(projectId, { feedbackId: entry.id, resolution, reviewer: orchestratorIdentity(run) });+ const resolution = failure ? `The re-authoring failed (${trimTo(failure.message, 200)}); kept the film.`+ : `Re-authored by the ${isOrchestratedRun(run) ? 'orchestrator' : 'autopilot'}.`;+ for (const entry of created) await deps.closeFeedback(projectId, { feedbackId: entry.id, resolution, reviewer: runReviewer(run) });if (failure) throw failure;}+const TEXT_CHECK_STEP = 'text-check';+const TEXT_CHECKPOINT = 'text';+const textEntry = (verdict, notes, issues = []) => ({ checkpoint: TEXT_CHECKPOINT, verdict, score: null, notes, issues, route: null, visual: false });++/**+ * The overlay text pass before the film renders (overlayTextService.js): check+ * the composition document's text where it appears; when the run's own+ * generated document collides, runs off frame, blends in or is too small,+ * send the findings back to its author and check again, bounded by the run's+ * review attempts. A hand-made document is never rewritten (its findings are+ * logged for the director), and a check that cannot run never holds the+ * render. Returns false when the run stopped meanwhile.+ */+async function settleOverlayText(projectId, run) {+ for (;;) {+ const project = await getProject(projectId);+ if (project?.composition?.mode !== 'document' || !project.composition.document?.directory) return true;+ await patchRun(projectId, (r) => stagePatch(r, 'produce', { status: 'running', step: TEXT_CHECK_STEP }));+ const check = await deps.checkOverlayText(projectId).catch((err) => ({ status: 'failed', error: err.message }));+ if ((await latestRun(projectId))?.status !== 'running') return false;+ if (check?.status !== 'complete') {+ await recordReview(projectId, textEntry('noted', `The overlay text check could not run (${trimTo(check?.error || 'it was replaced by a newer check', 200)}); rendering anyway.`));+ return true;+ }+ const findings = check.findings || [];+ if (!findings.length) {+ await recordReview(projectId, textEntry('approve', `No overlay text problems in ${check.textSamples ?? 0} frames with text.`));+ return true;+ }+ const issues = findings.slice(0, 12).map((f) => ({ atSec: f.atSec, text: trimTo(f.message, 300) }));+ const generated = project.composition.document.source?.kind === 'generated';+ if (!generated || revisionsSpent(await latestRun(projectId), TEXT_CHECKPOINT) >= reviewLimit(run)) {+ await recordReview(projectId, textEntry('noted', generated ? 'Revision limit reached; rendering the latest document.' : 'This document was made by hand, so it is left for the director to fix; rendering it as is.', issues));+ return true;+ }+ try {+ await reauthorFinal(projectId, run, issues, { target: 'text' });+ } catch (err) {+ await recordReview(projectId, textEntry('noted', `The re-authoring did not go through (${trimTo(err.message, 200)}); rendering the current document.`, issues));+ return true;+ }+ await recordReview(projectId, textEntry('revise', `Sent ${issues.length} overlay text problem${issues.length === 1 ? '' : 's'} back to the document's author.`, issues));+ }+}+// ---- stage executors -------------------------------------------------------------// Each returns `{ output }` (merged into run.output) or `{ output, wait: true }`// when the stage's completion arrives later (production).@@ -1027,6 +1078,8 @@ const STAGES = {: await deps.generateDocument(project.id, input);await deps.acceptDocument(project.id, candidate.document.directory);}+ // Stopped during the check: the advance loop sees the run is no longer running and lets it be.+ if (!await settleOverlayText(project.id, run)) throw runError(409, 'RUN_STOPPED', 'The run stopped during the overlay text check');// The animated proof is optional review evidence, so the run renders the film once the// storyboard is approved; the director can still render and approve a proof by hand.const render = await deps.renderVideo(project.id);@@ -1584,6 +1637,7 @@ async function reconcileFinalRender(projectId, { restart = false } = {}) {/** Render the film (again) and wait for the render's own event. */async function startFinalRender(projectId, run) {+ if (!await settleOverlayText(projectId, run)) return;const render = await deps.renderVideo(projectId).catch((err) => ({ error: err }));if (render.error) return failFinalRender(projectId, `The final render did not start: ${render.error.message}`, render.error.code || 'FINAL_RENDER_FAILED');await patchRun(projectId, (r) => ({ output: { renderJobId: render.jobId || null }, ...stagePatch(r, 'produce', { status: 'running', error: null, step: RENDER_STEP }), error: null, errorCode: null }));diff --git a/server/services/musicVideo/autonomousService.test.js b/server/services/musicVideo/autonomousService.test.jsindex b7c7b7c146..6fae041c2c 100644--- a/server/services/musicVideo/autonomousService.test.js+++ b/server/services/musicVideo/autonomousService.test.js@@ -107,6 +107,8 @@ beforeEach(() => {generateDocument: stub('document', async () => ({ document: { directory: 'music-video/mv-auto/composition/example' } })),acceptDocument: stub('accept-document', async (id, directory) => { store.get(id).composition.document = { directory }; return {}; }),renderVideo: stub('render', async () => ({ jobId: 'render-1' })),+ // The overlay text pass before a final render: clean unless a test says otherwise.+ checkOverlayText: stub('text-check', async () => ({ status: 'complete', samples: 12, textSamples: 8, findings: [] })),// The render job stays live until a test settles it with a `render` event.activeRenderJobId: vi.fn(async () => 'render-1'),cancelRender: vi.fn(async () => true),@@ -596,6 +598,61 @@ describe('startAutonomousVideo', () => {});});+describe('overlay text pass before the final render', () => {+ const finding = (atSec, message, severity = 'error') => ({ id: `f${atSec}`, kind: severity === 'error' ? 'overlap' : 'contrast', severity, atSec, texts: ['A'], message, count: 1 });+ const textEntries = () => (runOf()?.orchestration?.reviews || []).filter((r) => r.checkpoint === 'text');+ const start = () => service.startAutonomousVideo({ prompt: 'p', tools: ['code:render'], authoring: { providerId: 'prov', model: 'm' } });++ it('sends a generated document\'s text problems back to its author, checks again, then renders', async () => {+ doubles.acceptDocument.mockImplementation(async (id, directory) => {+ calls.push('accept-document');+ store.get(id).composition.document = { directory, source: { kind: 'generated' } };+ return {};+ });+ doubles.addFeedback = vi.fn(async (id, entry) => {+ const project = store.get(id);+ project.productionReview.feedback = [...(project.productionReview.feedback || []), { id: `fb-${entry.target}`, ...entry }];+ });+ doubles.closeFeedback = vi.fn(async (id, { feedbackId, resolution, reviewer }) => {+ const project = store.get(id);+ project.productionReview.feedback = project.productionReview.feedback.map((f) => (f.id === feedbackId ? { ...f, resolution, resolvedBy: reviewer, resolvedAt: 'now' } : f));+ });+ service.__setAutonomousDepsForTests(doubles);+ doubles.checkOverlayText+ .mockResolvedValueOnce({ status: 'complete', samples: 20, textSamples: 14, findings: [finding(3.5, '“20 MILLION YEARS” collides with “WHOLE SPECIES”.')] })+ .mockResolvedValueOnce({ status: 'complete', samples: 20, textSamples: 14, findings: [] });+ await start();+ await vi.waitFor(() => expect(runOf()?.output.renderJobId).toBe('render-1'));+ expect(doubles.checkOverlayText).toHaveBeenCalledTimes(2);+ expect(doubles.generateDocument).toHaveBeenCalledTimes(2);+ expect(doubles.renderVideo).toHaveBeenCalledOnce();+ expect(store.get('mv-auto').productionReview.feedback).toEqual([expect.objectContaining({ stage: 'proof', target: 'text@0:03',+ text: '“20 MILLION YEARS” collides with “WHOLE SPECIES”.', resolution: 'Re-authored by the autopilot.', resolvedBy: expect.objectContaining({ kind: 'autopilot', runId: runOf().id }) })]);+ expect(textEntries().map((r) => r.verdict)).toEqual(['revise', 'approve']);+ expect(textEntries()[0]).toMatchObject({ route: null, issues: [{ atSec: 3.5, text: expect.stringContaining('collides') }] });+ // Check, re-author, check again, then render.+ const order = (fn, n = 0) => fn.mock.invocationCallOrder[n];+ expect(order(doubles.generateDocument, 1)).toBeGreaterThan(order(doubles.checkOverlayText, 0));+ expect(order(doubles.checkOverlayText, 1)).toBeGreaterThan(order(doubles.acceptDocument, 1));+ expect(order(doubles.renderVideo)).toBeGreaterThan(order(doubles.checkOverlayText, 1));+ });++ it('logs a hand-made document\'s problems for the director and renders it untouched', async () => {+ doubles.checkOverlayText.mockResolvedValue({ status: 'complete', samples: 20, textSamples: 14, findings: [finding(1, 'Hard to read', 'warning')] });+ await start();+ await vi.waitFor(() => expect(runOf()?.output.renderJobId).toBe('render-1'));+ expect(doubles.generateDocument).toHaveBeenCalledOnce();+ expect(textEntries()).toEqual([expect.objectContaining({ verdict: 'noted', notes: expect.stringContaining('made by hand'), issues: [{ atSec: 1, text: 'Hard to read' }] })]);+ });++ it('never holds the render on a check that cannot run', async () => {+ doubles.checkOverlayText.mockRejectedValue(new Error('Managed browser is unavailable'));+ await start();+ await vi.waitFor(() => expect(runOf()?.output.renderJobId).toBe('render-1'));+ expect(textEntries()).toEqual([expect.objectContaining({ verdict: 'noted', notes: expect.stringContaining('Managed browser is unavailable') })]);+ });+});+describe('checkpoints', () => {it('parks after a checkpointed stage, then approves with the director’s edited lyrics', async () => {await service.startAutonomousVideo({ prompt: 'p', checkpoints: ['lyrics'] });@@ -1362,8 +1419,9 @@ describe('orchestrated mode (brief.orchestrator)', () => {resolution: 'Re-authored by the orchestrator.', resolvedAt: expect.any(String) });await service.__testing.onRenderEvent({ projectId: 'mv-auto', jobId: 'render-2', status: 'completed' });await settled('completed');- expect(reviews()).toEqual(['lyrics:approve', 'style:approve', 'song:approve', 'art:revise', 'art:approve', 'alignment:approve', 'storyboard:revise', 'storyboard:approve', 'final:revise', 'final:approve']);- expect(runOf().orchestration.reviews.at(-2)).toMatchObject({ issues: [{ atSec: 18, text: 'Static hold' }], notes: expect.stringContaining('Judged without frames') });+ // The measured overlay text pass runs before each render of the film.+ expect(reviews()).toEqual(['lyrics:approve', 'style:approve', 'song:approve', 'art:revise', 'art:approve', 'alignment:approve', 'storyboard:revise', 'storyboard:approve', 'text:approve', 'final:revise', 'text:approve', 'final:approve']);+ expect(runOf().orchestration.reviews.at(-3)).toMatchObject({ issues: [{ atSec: 18, text: 'Static hold' }], notes: expect.stringContaining('Judged without frames') });expect(doubles.finalReviewFrames.mock.calls.map(([jobId]) => jobId)).toEqual(['render-1', 'render-2']);});diff --git a/server/services/musicVideo/documentRender.js b/server/services/musicVideo/documentRender.jsindex 6d45d84679..9ee0ef7409 100644--- a/server/services/musicVideo/documentRender.js+++ b/server/services/musicVideo/documentRender.js@@ -436,6 +436,92 @@ export async function encodeDocumentComposition({}}+const PROBE_SCREENSHOT = Object.freeze({ format: 'png', optimizeForSpeed: true, fromSurface: true, captureBeyondViewport: false });+// Backdrop luminance is measured on a half-size frame (plenty for a contrast percentile).+const PROBE_BACKDROP_SCALE = 0.5;++/**+ * Open a project's composition document the way a render does (same staged+ * data and selected takes, same frame) with the overlay text probe installed+ * (overlayTextProbe.js), and visit each song time `sampleTimes(data, frame)`+ * returns. At each one `onSample({ atSec, records, backdrop })` gets the text+ * the page drew and, when there was any, the frame with that text hidden as+ * linear luminance (`{ width, height, scale, values: Float32Array }`). Resolves+ * `{ frame, scenes, samples }` (the PORTOS_MV scenes, for naming shots).+ */+export async function probeDocumentText({ project, jobId, signal, sampleTimes, onSample, onProgress }) {+ const plan = await prepareDocumentRender(project);+ const { probeVideoGeometry } = await import('../../lib/ffmpeg.js');+ const { stageMusicVideoComposition } = await import('../htmlComposition/index.js');+ const { openComposition } = await import('../htmlComposition/browser.js');+ const { loadHistory } = await import('../videoGen/history.js');+ const { OVERLAY_TEXT_PROBE_SCRIPT } = await import('./overlayTextProbe.js');+ const { SRGB_TO_LINEAR } = await import('./overlayText.js');+ const { default: sharp } = await import('sharp');+ const generated = project.composition?.document?.source?.kind === 'generated';+ const history = (project.scenes || []).some((s) => s?.videoHistoryId) ? await loadHistory() : [];+ const media = await resolveSceneMedia(project, { history, probe: probeVideoGeometry, strictLayers: generated });+ const data = buildDocumentData(project, { media, frame: plan.frame, clock: plan.clock, songDurationSec: plan.songDurationSec, generated });+ let staged;+ let page;+ try {+ staged = await stageMusicVideoComposition(plan.directory, jobId, musicVideoSongDocument(project), {+ prepare: (dir) => stageDocumentData(dir, data, media),+ });+ signal?.throwIfAborted();+ page = await openComposition(staged.directory, { signal, streamMedia: true, mediaMode: musicVideoMediaMode(project), ownedBrowser: true,+ initScripts: [OVERLAY_TEXT_PROBE_SCRIPT] });+ const metadata = await page.evaluate(`(() => {+ const c = globalThis.portosComposition;+ if (!c || typeof c.seek !== 'function') throw new Error('portosComposition.seek is required');+ if (!globalThis.__portosTextProbe) throw new Error('The overlay text probe did not load');+ return { durationSec: c.durationSec, fps: c.fps, width: c.width, height: c.height, motionBlur: c.motionBlur, formats: c.formats, layout: typeof c.layout === 'function' };+ })()`);+ const parsed = htmlCompositionContractSchemaFor(Math.max(1, plan.songDurationSec)).safeParse(metadata);+ if (!parsed.success) {+ throw new ServerError(`The composition document's contract is invalid — ${parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; ')}`, {+ status: 422, code: 'COMPOSITION_DOCUMENT_CONTRACT',+ });+ }+ const target = documentTargetFrame(parsed.data, project);+ await page.send('Emulation.setDeviceMetricsOverride', { width: target.width, height: target.height, deviceScaleFactor: 1, mobile: false });+ if (target.width !== parsed.data.width || target.height !== parsed.data.height) {+ await page.evaluate(`globalThis.portosComposition.layout({ width: ${target.width}, height: ${target.height} })`);+ }+ const frame = { width: target.width, height: target.height };+ const times = sampleTimes(data, { ...frame, fps: target.fps, durationSec: target.durationSec });+ for (const [index, atSec] of times.entries()) {+ signal?.throwIfAborted();+ page.check();+ await page.evaluate('globalThis.__portosTextProbe.begin()');+ await page.evaluate(`globalThis.portosComposition.seek(${atSec})`).catch((error) => {+ throw new Error(`Composition seek(${atSec}) failed: ${error.message}`);+ });+ const records = await page.evaluate('globalThis.__portosTextProbe.end()');+ let backdrop = null;+ if (Array.isArray(records) && records.length) {+ const { data: png } = await page.send('Page.captureScreenshot', PROBE_SCREENSHOT);+ const width = Math.max(1, Math.round(target.width * PROBE_BACKDROP_SCALE));+ const { data: rgb, info } = await sharp(Buffer.from(png, 'base64')).removeAlpha().resize({ width }).raw().toBuffer({ resolveWithObject: true });+ const values = new Float32Array(info.width * info.height);+ for (let p = 0, o = 0; p < values.length; p++, o += info.channels) {+ values[p] = 0.2126 * SRGB_TO_LINEAR[rgb[o]] + 0.7152 * SRGB_TO_LINEAR[rgb[o + 1]] + 0.0722 * SRGB_TO_LINEAR[rgb[o + 2]];+ }+ backdrop = { width: info.width, height: info.height, scale: info.width / target.width, values };+ }+ onSample({ atSec, frame, records: Array.isArray(records) ? records : [], backdrop });+ onProgress?.((index + 1) / times.length);+ }+ page.check();+ await page.close({ verify: true });+ page = null;+ return { frame, scenes: data.scenes, samples: times.length };+ } finally {+ if (page) await page.close().catch(() => {});+ if (staged?.scratchRoot) await rm(staged.scratchRoot, { recursive: true, force: true }).catch(() => {});+ }+}+/** Boot sweep: no document render survives a restart, so its scratch is stale. */export async function sweepDocumentScratch() {const { MUSIC_VIDEO_SCRATCH_DIR } = await import('../htmlComposition/index.js');diff --git a/server/services/musicVideo/documentTemplates/shared/lyricType.js b/server/services/musicVideo/documentTemplates/shared/lyricType.jsindex 86dc24c32d..777872b4e4 100644--- a/server/services/musicVideo/documentTemplates/shared/lyricType.js+++ b/server/services/musicVideo/documentTemplates/shared/lyricType.js@@ -24,7 +24,8 @@* stamp short punches, negations, spoken lines: a three-frame stamp with a* small tilt, optional strike-through.* data HUD captions, counters and tags in mono; numbers roll. At most one- * per shot.+ * per shot. Set large enough to read on a phone and ringed in ink, so a+ * corner readout needs no backing plate on a light picture.** Every frame is a pure function of song time, so a draft frame matches the full* render at that time. The file is plain ES2020 with no imports.@@ -340,7 +341,7 @@ export function createLyricType(mv = globalThis.PORTOS_MV, options = {}) {const basePx = (role, unit, portrait) => {if (role === 'hook') return (portrait ? 140 : 160) * unit;if (role === 'stamp') return 110 * unit;- if (role === 'data') return 34 * unit;+ if (role === 'data') return 48 * unit;return 68 * unit;};@@ -349,7 +350,7 @@ export function createLyricType(mv = globalThis.PORTOS_MV, options = {}) {const rect = zoneRect(line.zone, width, height);if (!rect) return null;const unit = Math.min(width, height) / 1080;- const floor = (line.role === 'data' ? 28 : T.minPx) * unit;+ const floor = (line.role === 'data' ? 40 : T.minPx) * unit;let px = basePx(line.role, unit, height > width);const items = line.words.map((w) => (line.role === 'hook' ? String(w.text).toUpperCase() : w.text));const rowsAt = (size) => wrap(items.map((text, index) => ({ text, index })), rect.w, (item) => measure(`${item.text} `, fontFor(line.role, size)));@@ -389,7 +390,7 @@ export function createLyricType(mv = globalThis.PORTOS_MV, options = {}) {const states = wordStates(line, t);const exit = lineExit(line, t);const font = fontFor(line.role, placed.px);- const outline = Math.max(2, (line.role === 'data' ? 4 : 11) * unit * (placed.px / basePx(line.role, unit, height > width)));+ const outline = Math.max(2, (line.role === 'data' ? 9 : 11) * unit * (placed.px / basePx(line.role, unit, height > width)));ctx.save();ctx.font = font; ctx.textAlign = 'left'; ctx.textBaseline = 'alphabetic';ctx.lineJoin = 'round'; ctx.miterLimit = 2; ctx.lineWidth = outline;@@ -407,6 +408,7 @@ export function createLyricType(mv = globalThis.PORTOS_MV, options = {}) {const text = line.role === 'data' ? rollNumbers(word.text, (t - s.startSec) / T.dataRollSec) : word.text;const x0 = -(word.w - measure(' ', font)) / 2;if (line.role === 'data') {+ ctx.strokeStyle = palette.ink; ctx.strokeText(text, x0, 0);ctx.fillStyle = palette.accent; ctx.fillText(text, x0, 0);} else if (line.role === 'hook' && word.index === line.accent) {ctx.lineWidth = outline * 1.6;diff --git a/server/services/musicVideo/overlayText.js b/server/services/musicVideo/overlayText.jsnew file mode 100644index 0000000000..2dfe517044--- /dev/null+++ b/server/services/musicVideo/overlayText.js@@ -0,0 +1,378 @@+/**+ * Music Video — overlay text quality pass (pure half; I/O in overlayTextService.js).+ *+ * The check renders a composition document at the moments text appears (each+ * lyric line and text cue, and every shot), records where every word lands+ * (overlayTextProbe.js) and what sits behind it, and flags what a viewer on a+ * phone would trip over:+ *+ * overlap two separate pieces of text collide (a corner readout under a lyric)+ * off-frame text runs past the edge of the frame and is cut off+ * contrast the words blend into the picture behind them: too little+ * contrast and no outline or shadow wide enough to separate them+ * small text too small to read at phone width (390px)+ *+ * Contrast follows the shared lyric type (lyricType.js): a cream fill with an+ * ink outline reads on any picture, so an outline that is visible at phone+ * size passes on its own; a dark backing plate also passes (it is part of the+ * measured backdrop), but the fix this check recommends is an outline.+ *+ * Findings repeat across samples (a readout stays up for a whole shot), so one+ * finding is kept per problem and text, with every time it was seen.+ */+import { createHash, randomUUID } from 'node:crypto';++const PHONE_WIDTH_PX = 390;+const OVERLAY_TEXT_LIMITS = Object.freeze({+ maxSamples: 180,+ maxFindings: 40,+ maxTimesPerFinding: 8,+ // Smallest em (font size) still readable at phone width, in phone pixels.+ minPhoneEmPx: 8,+ // At or above this em (phone px) text counts as large (WCAG 3:1, else 4.5:1).+ largePhoneEmPx: 18,+ contrastLarge: 3,+ contrastSmall: 4.5,+ // An outline / shadow separates the words when this wide outside the glyph at phone width…+ minHaloPhonePx: 0.6,+ // …and this different from the fill.+ minHaloContrast: 3,+ // Text more transparent than this is mid-fade: skipped for overlap and size.+ minAlpha: 0.35,+ // Contrast is judged only on settled (near-opaque) text.+ contrastAlpha: 0.85,+});+const OVERLAY_TEXT_KINDS = Object.freeze(['overlap', 'off-frame', 'contrast', 'small']);+const SEVERITY = Object.freeze({ overlap: 'error', 'off-frame': 'error', contrast: 'warning', small: 'warning' });+// The process that owns a running check; a record left `running` by another process was interrupted.+export const OVERLAY_TEXT_PROCESS_ID = randomUUID();++const finite = (n) => typeof n === 'number' && Number.isFinite(n);+const round3 = (n) => Math.round(n * 1000) / 1000;+const round1 = (n) => Math.round(n * 10) / 10;++/** `{ r, g, b, a }` (0-255, alpha 0-1) for a CSS colour a canvas or computed style reports; null otherwise. */+function parseCssColor(value) {+ const s = String(value ?? '').trim().toLowerCase();+ if (!s) return null;+ if (s === 'transparent') return { r: 0, g: 0, b: 0, a: 0 };+ let m = /^#([0-9a-f]{3,8})$/.exec(s);+ if (m) {+ const hex = m[1];+ if (hex.length === 3 || hex.length === 4) {+ const [r, g, b, a = 'f'] = hex.split('').map((c) => c + c);+ return { r: parseInt(r, 16), g: parseInt(g, 16), b: parseInt(b, 16), a: parseInt(a, 16) / 255 };+ }+ if (hex.length === 6 || hex.length === 8) {+ return { r: parseInt(hex.slice(0, 2), 16), g: parseInt(hex.slice(2, 4), 16), b: parseInt(hex.slice(4, 6), 16), a: hex.length === 8 ? parseInt(hex.slice(6, 8), 16) / 255 : 1 };+ }+ return null;+ }+ m = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:\s*[,/]\s*([\d.]+%?))?\s*\)$/.exec(s);+ if (!m) return null;+ const alpha = m[4] == null ? 1 : m[4].endsWith('%') ? parseFloat(m[4]) / 100 : parseFloat(m[4]);+ return { r: Math.min(255, +m[1]), g: Math.min(255, +m[2]), b: Math.min(255, +m[3]), a: Math.max(0, Math.min(1, alpha)) };+}++const channel = (c) => { const v = c / 255; return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4; };+/** WCAG relative luminance (0-1) of an sRGB colour. */+const relativeLuminance = ({ r, g, b }) => 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);+/** A 256-entry sRGB → linear table, for per-pixel luminance of a screenshot. */+export const SRGB_TO_LINEAR = Object.freeze(Array.from({ length: 256 }, (_, c) => channel(c)));+/** WCAG contrast ratio (1-21) between two relative luminances. */+const contrastRatio = (a, b) => (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);++/**+ * Song times (seconds, on the frame grid) to sample: each lyric line and text+ * cue once settled (0.35s after it starts), mid-way through a long one and near+ * its end; each shot just after it starts and at its middle. Times closer than+ * 0.15s collapse; more than `maxSamples` thin evenly.+ */+export function planTextSampleTimes({ lyrics = [], textCues = [], scenes = [], durationSec, fps = 24, maxSamples = OVERLAY_TEXT_LIMITS.maxSamples }) {+ if (!(durationSec > 0)) return [];+ const times = [];+ const span = (start, end) => {+ if (!finite(start)) return;+ const stop = finite(end) && end > start ? end : start + 1;+ const length = stop - start;+ times.push(start + Math.min(0.35, length / 2));+ if (length > 1.2) times.push((start + stop) / 2);+ if (length > 2.4) times.push(stop - 0.2);+ };+ for (const line of Array.isArray(lyrics) ? lyrics : []) {+ const words = Array.isArray(line?.words) ? line.words.filter((w) => finite(w?.startSec)) : [];+ const end = finite(line?.endSec) ? line.endSec : words.length ? Math.max(...words.map((w) => (finite(w.endSec) ? w.endSec : w.startSec))) : null;+ span(line?.startSec ?? words[0]?.startSec, end);+ }+ for (const cue of Array.isArray(textCues) ? textCues : []) span(cue?.startSec, cue?.endSec);+ for (const scene of Array.isArray(scenes) ? scenes : []) {+ if (!finite(scene?.startSec) || !finite(scene?.endSec) || scene.endSec <= scene.startSec) continue;+ times.push(scene.startSec + Math.min(0.25, (scene.endSec - scene.startSec) / 2));+ times.push((scene.startSec + scene.endSec) / 2);+ }+ const last = Math.max(0, Math.floor(durationSec * fps - 1e-6) / fps);+ const snapped = times+ .map((t) => Math.min(last, Math.max(0, Math.floor(t * fps + 1e-6) / fps)))+ .sort((a, b) => a - b);+ const kept = [];+ for (const t of snapped) if (!kept.length || t - kept[kept.length - 1] >= 0.15) kept.push(round3(t));+ if (kept.length <= maxSamples) return kept;+ return Array.from({ length: maxSamples }, (_, i) => kept[Math.floor(((i + 0.5) * kept.length) / maxSamples)]);+}++const widthOf = (b) => b.x1 - b.x0;+const heightOf = (b) => b.y1 - b.y0;+const emOf = (item) => (finite(item.emPx) && item.emPx > 0 ? item.emPx : heightOf(item));++/**+ * Collapse one sample's raw probe records into drawn words: the outline and the+ * fill of one word (drawn as separate calls) become one item with a face colour+ * (the fill, or the last outline for outline-only type) and halos (outlines+ * and shadows that ring the face).+ */+export function mergeTextRecords(records = []) {+ const items = [];+ for (const r of Array.isArray(records) ? records : []) {+ if (!r || typeof r.text !== 'string' || !(r.x1 > r.x0) || !(r.y1 > r.y0)) continue;+ const em = finite(r.emPx) && r.emPx > 0 ? r.emPx : r.y1 - r.y0;+ const tol = Math.max(3, em * 0.15);+ const same = items.find((it) => it.text === r.text && it.layer === r.layer+ && Math.abs(it.x0 - r.x0) <= tol && Math.abs(it.y0 - r.y0) <= tol && Math.abs(it.x1 - r.x1) <= tol && Math.abs(it.y1 - r.y1) <= tol);+ const item = same || { text: r.text, layer: r.layer, source: r.source, font: r.font || '', emPx: r.emPx ?? null,+ x0: r.x0, y0: r.y0, x1: r.x1, y1: r.y1, alpha: 0, fill: null, strokes: [], shadows: [], seq: r.seq ?? items.length };+ if (!same) items.push(item);+ item.x0 = Math.min(item.x0, r.x0); item.y0 = Math.min(item.y0, r.y0);+ item.x1 = Math.max(item.x1, r.x1); item.y1 = Math.max(item.y1, r.y1);+ item.alpha = Math.max(item.alpha, finite(r.alpha) ? r.alpha : 1);+ if (r.kind === 'stroke' && r.lineWidth > 0) item.strokes.push({ color: r.color, width: r.lineWidth });+ else if (r.kind !== 'stroke' && r.color) item.fill = r.color;+ if (r.shadow?.color && r.shadow.px > 0) item.shadows.push({ color: r.shadow.color, px: r.shadow.px });+ }+ return items.map((item) => {+ // Outline-only type: the last (top) outline is the letter face; wider ones under it ring it.+ const face = item.fill || item.strokes.at(-1)?.color || null;+ const faceWidth = item.fill ? 0 : item.strokes.at(-1)?.width || 0;+ const halos = [+ ...item.strokes.filter((s) => s.width > faceWidth && s.color !== face).map((s) => ({ color: s.color, px: (s.width - faceWidth) / 2 })),+ ...item.shadows,+ ];+ const { strokes, shadows, fill, ...rest } = item;+ return { ...rest, face, halos };+ });+}++// Union-find over items: one block per run of text set in the same face that+// touches (a line's words, a wrapped paragraph). Blocks are what may collide.+function blocksOf(items) {+ const parent = items.map((_, i) => i);+ const find = (i) => (parent[i] === i ? i : (parent[i] = find(parent[i])));+ for (let i = 0; i < items.length; i++) {+ for (let j = i + 1; j < items.length; j++) {+ const a = items[i];+ const b = items[j];+ if (a.layer !== b.layer || a.font !== b.font) continue;+ const em = Math.max(emOf(a), emOf(b));+ const dx = em * 0.6;+ const dy = em * 0.45;+ if (a.x0 - dx < b.x1 && b.x0 - dx < a.x1 && a.y0 - dy < b.y1 && b.y0 - dy < a.y1) parent[find(i)] = find(j);+ }+ }+ const groups = new Map();+ items.forEach((item, i) => {+ const root = find(i);+ if (!groups.has(root)) groups.set(root, []);+ groups.get(root).push(item);+ });+ return [...groups.values()];+}++// The block's words in reading order, as one short quote.+function blockText(block, max = 48) {+ const words = block.slice().sort((a, b) => (Math.abs(a.y0 - b.y0) > emOf(a) * 0.5 ? a.y0 - b.y0 : a.x0 - b.x0)).map((w) => w.text.trim());+ const text = words.join(' ').replace(/\s+/g, ' ').trim();+ return text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;+}++/**+ * The contrast verdict for one drawn word against its backdrop luminance+ * percentiles (`backdrop: { p15, p50, p85 }`, 0-1). Null when it cannot be+ * judged (an unknown or gradient fill, no backdrop, mid-fade).+ */+function wordContrast(item, phoneScale) {+ const L = OVERLAY_TEXT_LIMITS;+ const face = parseCssColor(item.face);+ const bg = item.backdrop;+ if (!face || face.a < 0.5 || !bg || !finite(bg.p15) || !finite(bg.p85) || (item.alpha ?? 1) < L.contrastAlpha) return null;+ const lf = relativeLuminance(face);+ const ratio = Math.min(contrastRatio(lf, bg.p15), contrastRatio(lf, bg.p85));+ const phoneEm = emOf(item) * phoneScale;+ const needed = phoneEm >= L.largePhoneEmPx ? L.contrastLarge : L.contrastSmall;+ const halo = (item.halos || []).some((h) => {+ const color = parseCssColor(h.color);+ return color && color.a >= 0.5 && h.px * phoneScale >= L.minHaloPhonePx && contrastRatio(lf, relativeLuminance(color)) >= L.minHaloContrast;+ });+ return { ratio: round1(ratio), needed, halo, ok: ratio >= needed || halo, outlined: (item.halos || []).length > 0 };+}++/**+ * Luminance percentiles `{ p15, p50, p85 }` of the backdrop under a word's box+ * (`backdrop` from probeDocumentText: linear luminance at `scale` of the frame).+ * Null when the box misses the frame.+ */+export function backdropStats(backdrop, box) {+ if (!backdrop?.values || !box) return null;+ const { width, height, scale, values } = backdrop;+ const x0 = Math.max(0, Math.floor(box.x0 * scale));+ const y0 = Math.max(0, Math.floor(box.y0 * scale));+ const x1 = Math.min(width, Math.ceil(box.x1 * scale));+ const y1 = Math.min(height, Math.ceil(box.y1 * scale));+ if (x1 <= x0 || y1 <= y0) return null;+ // At most ~20k pixels per word: a stride keeps a full-width hook cheap.+ const stride = Math.max(1, Math.floor(Math.sqrt(((x1 - x0) * (y1 - y0)) / 20000)));+ const picked = [];+ for (let y = y0; y < y1; y += stride) for (let x = x0; x < x1; x += stride) picked.push(values[y * width + x]);+ picked.sort((a, b) => a - b);+ const at = (q) => picked[Math.min(picked.length - 1, Math.floor(q * picked.length))];+ return { p15: at(0.15), p50: at(0.5), p85: at(0.85) };+}++/**+ * Problems in one sampled frame. `items` come from mergeTextRecords (with an+ * optional per-item `backdrop`); `frame` is `{ width, height }` in the same+ * pixels as the boxes. Returns `[{ kind, texts, detail }]`.+ */+export function analyzeTextFrame(items = [], frame) {+ const L = OVERLAY_TEXT_LIMITS;+ const W = frame?.width;+ const H = frame?.height;+ if (!(W > 0 && H > 0)) return [];+ const phoneScale = PHONE_WIDTH_PX / W;+ const visible = items.filter((it) => it.x1 > 0 && it.x0 < W && it.y1 > 0 && it.y0 < H && (it.alpha ?? 1) >= L.minAlpha);+ const blocks = blocksOf(visible);+ const issues = [];+ // Collisions: a word of one block crossing a word of another.+ for (let i = 0; i < blocks.length; i++) {+ for (let j = i + 1; j < blocks.length; j++) {+ const hit = blocks[i].some((a) => blocks[j].some((b) => {+ const tol = Math.max(2, Math.min(emOf(a), emOf(b)) * 0.08);+ return Math.min(a.x1, b.x1) - Math.max(a.x0, b.x0) > tol && Math.min(a.y1, b.y1) - Math.max(a.y0, b.y0) > tol;+ }));+ if (hit) issues.push({ kind: 'overlap', texts: [blockText(blocks[i]), blockText(blocks[j])], detail: null });+ }+ }+ for (const block of blocks) {+ const text = blockText(block);+ const tol = 2;+ if (block.some((w) => w.x0 < -tol || w.y0 < -tol || w.x1 > W + tol || w.y1 > H + tol)) {+ issues.push({ kind: 'off-frame', texts: [text], detail: null });+ }+ const phoneEm = Math.min(...block.map((w) => emOf(w) * phoneScale));+ if (phoneEm < L.minPhoneEmPx) issues.push({ kind: 'small', texts: [text], detail: { phoneEmPx: round1(phoneEm) } });+ const verdicts = block.map((w) => wordContrast(w, phoneScale)).filter(Boolean);+ const failing = verdicts.filter((v) => !v.ok);+ if (failing.length) {+ const worst = failing.reduce((a, b) => (b.ratio < a.ratio ? b : a));+ issues.push({ kind: 'contrast', texts: [text], detail: { ratio: worst.ratio, needed: worst.needed, outlined: worst.outlined } });+ }+ }+ return issues;+}++const quote = (text) => `“${text}”`;+/** One plain sentence for a finding (what is wrong, and the fix lyricType uses). */+function describeTextFinding({ kind, texts, detail }) {+ switch (kind) {+ case 'overlap': return `${quote(texts[0])} collides with ${quote(texts[1])}. Move one to a free corner or time them apart.`;+ case 'off-frame': return `${quote(texts[0])} runs off the edge of the frame. Keep it inside the safe margin or let it wrap.`;+ case 'small': return `${quote(texts[0])} is ${detail?.phoneEmPx ?? 'too few'}px tall at phone width. Set it larger (at least ${OVERLAY_TEXT_LIMITS.minPhoneEmPx}px on a phone).`;+ case 'contrast': return `${quote(texts[0])} blends into the picture (${detail?.ratio ?? '?'}:1). Give it an ink outline wide enough to read on a phone${detail?.outlined ? ' (its outline is too thin there)' : ''}.`;+ default: return quote(texts.join(' / '));+ }+}++// Words appear one by one, so the same line reads "whole", then "whole species+// bloom": a finding of the same kind whose text contains (or is contained in)+// another's, seen within a few seconds, is the same problem.+const SAME_TEXT_WINDOW_SEC = 8;+const contains = (a, b) => {+ const x = a.toLowerCase().replace(/…$/, '');+ const y = b.toLowerCase().replace(/…$/, '');+ // A very short fragment ("I", "a") would match any line, so only an exact match counts for it.+ return x === y || (Math.min(x.length, y.length) >= 4 && (x.includes(y) || y.includes(x)));+};+function sameProblem(finding, issue, atSec) {+ if (finding.kind !== issue.kind || finding.texts.length !== issue.texts.length || atSec - finding.lastSec > SAME_TEXT_WINDOW_SEC) return false;+ if (finding.texts.length === 1) return contains(finding.texts[0], issue.texts[0]);+ const [a, b] = finding.texts;+ const [c, d] = issue.texts;+ return (contains(a, c) && contains(b, d)) || (contains(a, d) && contains(b, c));+}++const sceneAt = (scenes, t) => (scenes || []).filter((s) => finite(s?.startSec) && s.startSec <= t + 1e-6 && (!finite(s.endSec) || t < s.endSec)).pop() || null;+const findingKey = (issue) => `${issue.kind}|${issue.texts.map((t) => t.toLowerCase()).sort().join('|')}`;++/**+ * Merge per-sample issues (`[{ atSec, issues }]`) into findings, errors first,+ * then by first time seen; each names the shot it was first seen in.+ */+export function summarizeTextFindings(samples = [], scenes = []) {+ const L = OVERLAY_TEXT_LIMITS;+ const byKey = new Map();+ for (const sample of samples.slice().sort((a, b) => a.atSec - b.atSec)) {+ for (const issue of sample.issues || []) {+ const key = findingKey(issue);+ const found = byKey.get(key) || [...byKey.values()].find((f) => sameProblem(f, issue, sample.atSec));+ if (found) {+ if (found.times.length < L.maxTimesPerFinding && !found.times.includes(round3(sample.atSec))) found.times.push(round3(sample.atSec));+ found.count += 1;+ found.lastSec = sample.atSec;+ // Keep the fullest reading of the text (the whole line, not its first word).+ if (issue.texts.join(' ').length > found.texts.join(' ').length) {+ found.texts = issue.texts;+ found.detail = issue.detail ?? found.detail;+ found.message = describeTextFinding(issue);+ }+ continue;+ }+ const scene = sceneAt(scenes, sample.atSec);+ byKey.set(key, {+ id: createHash('sha1').update(key).digest('hex').slice(0, 12),+ kind: issue.kind, severity: SEVERITY[issue.kind] || 'warning', texts: issue.texts, detail: issue.detail ?? null,+ atSec: round3(sample.atSec), lastSec: sample.atSec, times: [round3(sample.atSec)], count: 1,+ sceneId: scene?.sceneId ?? null, sceneLabel: scene?.label || null,+ message: describeTextFinding(issue),+ });+ }+ }+ return [...byKey.values()]+ .map(({ lastSec, ...finding }) => finding)+ .sort((a, b) => (a.severity === b.severity ? a.atSec - b.atSec : a.severity === 'error' ? -1 : 1))+ .slice(0, L.maxFindings);+}++/** Counts per kind and severity, for the one-line summary. */+function countTextFindings(findings = []) {+ const counts = { errors: 0, warnings: 0, ...Object.fromEntries(OVERLAY_TEXT_KINDS.map((k) => [k, 0])) };+ for (const f of findings) {+ counts[f.kind] = (counts[f.kind] || 0) + 1;+ if (f.severity === 'error') counts.errors += 1; else counts.warnings += 1;+ }+ return counts;+}++/**+ * The stored check as the storyboard reports it: null outside document mode;+ * otherwise `{ status, current, ... }`. `status` is none | running |+ * interrupted | complete | failed; `current` says it was run on the present+ * document, timing, shots and takes (`basisOf(project)`, hashed only here).+ */+export function overlayTextReport(project, basisOf) {+ if (project?.composition?.mode !== 'document' || !project.composition.document?.directory) return null;+ const check = project.productionReview?.textCheck;+ if (!check) return { status: 'none', current: false, findings: [], counts: countTextFindings([]) };+ const status = check.status === 'running' && check.processId !== OVERLAY_TEXT_PROCESS_ID ? 'interrupted' : check.status;+ const findings = Array.isArray(check.findings) ? check.findings : [];+ return { status, current: check.basis === basisOf(project), checkedAt: check.checkedAt || null, startedAt: check.startedAt || null,+ samples: check.samples ?? null, textSamples: check.textSamples ?? null, error: check.error || null,+ findings, counts: countTextFindings(findings) };+}diff --git a/server/services/musicVideo/overlayText.test.js b/server/services/musicVideo/overlayText.test.jsnew file mode 100644index 0000000000..91691859f2--- /dev/null+++ b/server/services/musicVideo/overlayText.test.js@@ -0,0 +1,106 @@+/**+ * The overlay text verdicts on synthetic probe records: which drawn words form+ * one block, when blocks collide, when an outline carries contrast, and how a+ * line revealed word by word stays one finding. The browser suite+ * (overlayTextService.browser.test.js) drives the same code from real pixels.+ */+import { describe, expect, it } from 'vitest';+import {+ OVERLAY_TEXT_PROCESS_ID, analyzeTextFrame, mergeTextRecords, overlayTextReport, planTextSampleTimes, summarizeTextFindings,+} from './overlayText.js';++const FRAME = { width: 1920, height: 1080 };+const CREAM = '#f3ead7';+const INK = '#141217';+const PALE = { p15: 0.8, p50: 0.82, p85: 0.86 };++// One word as the probe reports it: fill (and optional outline) at a box, em px from the font.+function word(text, x0, y0, { w = text.length * 40, h = 70, em = 96, font = '900 96px Archivo', fill = CREAM, outline = 0, alpha = 1, layer = 'canvas-0' } = {}) {+ const box = { text, layer, source: 'canvas', font, emPx: em, x0, y0, x1: x0 + w, y1: y0 + h, alpha, shadow: null };+ return [+ ...(outline ? [{ ...box, kind: 'stroke', color: INK, lineWidth: outline }] : []),+ { ...box, kind: 'fill', color: fill, lineWidth: 0 },+ ];+}+const frameIssues = (records, backdrop = null) => {+ const items = mergeTextRecords(records);+ if (backdrop) for (const item of items) item.backdrop = backdrop;+ return analyzeTextFrame(items, FRAME);+};++describe('analyzeTextFrame', () => {+ it('flags a readout under a lyric, but not the words of one line touching each other', () => {+ const line = [...word('WHOLE', 700, 60, { outline: 14 }), ...word('SPECIES', 950, 60, { outline: 14 })];+ const readout = word('20 MILLION YEARS', 40, 80, { font: '500 40px Plex Mono', em: 40, w: 700, h: 32 });+ expect(frameIssues(line)).toEqual([]);+ expect(frameIssues([...readout, ...line])).toEqual([{ kind: 'overlap', texts: ['20 MILLION YEARS', 'WHOLE SPECIES'], detail: null }]);+ });++ it('ignores a word mid-fade for collisions', () => {+ const fading = word('OLD LINE', 100, 900, { alpha: 0.2, w: 500 });+ const incoming = word('NEW LINE', 120, 910, { font: '700 68px Archivo', em: 68, w: 500 });+ expect(frameIssues([...fading, ...incoming])).toEqual([]);+ });++ it('flags text past the edge and text too small for a phone', () => {+ expect(frameIssues(word('OFF THE EDGE', 1700, 900, { w: 400 })).map((i) => i.kind)).toEqual(['off-frame']);+ const tag = frameIssues(word('tiny', 100, 100, { em: 30, h: 22, font: '30px sans-serif' }));+ expect(tag).toEqual([{ kind: 'small', texts: ['tiny'], detail: { phoneEmPx: 6.1 } }]);+ });++ it('passes cream type on a pale frame only when its ink outline reads at phone size', () => {+ expect(frameIssues(word('BLOOM', 100, 400, { outline: 14 }), PALE)).toEqual([]);+ // A 2px outline is a fraction of a pixel on a phone.+ expect(frameIssues(word('BLOOM', 100, 400, { outline: 2 }), PALE)).toEqual([+ { kind: 'contrast', texts: ['BLOOM'], detail: expect.objectContaining({ outlined: true }) }]);+ expect(frameIssues(word('BLOOM', 100, 400), PALE)[0]).toMatchObject({ kind: 'contrast', detail: { outlined: false } });+ // Dark ink on the same pale frame needs no outline.+ expect(frameIssues(word('BLOOM', 100, 400, { fill: INK }), PALE)).toEqual([]);+ });+});++describe('summarizeTextFindings', () => {+ it('keeps a line revealed word by word as one finding with its fullest text, errors first', () => {+ const contrast = (text) => ({ kind: 'contrast', texts: [text], detail: { ratio: 1.1, needed: 3, outlined: false } });+ const findings = summarizeTextFindings([+ { atSec: 2.5, issues: [contrast('whole')] },+ { atSec: 3.5, issues: [contrast('whole species bloom')] },+ { atSec: 6, issues: [{ kind: 'overlap', texts: ['20 MILLION', 'WHOLE'], detail: null }] },+ { atSec: 20, issues: [contrast('whole species')] },+ { atSec: 30, issues: [contrast('whole')] },+ ], [{ sceneId: 's1', label: 'Cliff', startSec: 0, endSec: 10 }, { sceneId: 's2', label: 'Space', startSec: 10, endSec: 40 }]);+ expect(findings.map((f) => [f.kind, f.texts, f.atSec, f.times, f.sceneLabel])).toEqual([+ ['overlap', ['20 MILLION', 'WHOLE'], 6, [6], 'Cliff'],+ // The exact same text again later (a repeated chorus) joins it; a partial reading only nearby.+ ['contrast', ['whole species bloom'], 2.5, [2.5, 3.5, 30], 'Cliff'],+ ['contrast', ['whole species'], 20, [20], 'Space'],+ ]);+ expect(findings[1].message).toContain('“whole species bloom”');+ });+});++describe('planTextSampleTimes', () => {+ it('samples each line settled, long lines again, and each shot, on the frame grid without near-duplicates', () => {+ const times = planTextSampleTimes({+ lyrics: [{ startSec: 1, endSec: 4, words: [] }],+ scenes: [{ startSec: 0, endSec: 8 }],+ durationSec: 8, fps: 24,+ });+ expect(times).toEqual([0.25, 1.333, 2.5, 3.792, 4]);+ expect(times.every((t) => Math.abs(t * 24 - Math.round(t * 24)) < 0.05)).toBe(true);+ const many = planTextSampleTimes({ scenes: Array.from({ length: 300 }, (_, i) => ({ startSec: i, endSec: i + 1 })), durationSec: 300, maxSamples: 50 });+ expect(many).toHaveLength(50);+ });+});++describe('overlayTextReport', () => {+ const project = (textCheck) => ({ composition: { mode: 'document', document: { directory: 'music-video/mv-1/composition/doc-1' } }, productionReview: { textCheck } });+ it('reports nothing outside document mode, and a check another process left running as interrupted', () => {+ expect(overlayTextReport({ composition: { mode: 'concat' } }, () => 'b')).toBeNull();+ expect(overlayTextReport(project(undefined), () => 'b')).toMatchObject({ status: 'none', current: false });+ expect(overlayTextReport(project({ status: 'running', basis: 'b', processId: OVERLAY_TEXT_PROCESS_ID }), () => 'b')).toMatchObject({ status: 'running', current: true });+ expect(overlayTextReport(project({ status: 'running', basis: 'b', processId: 'previous-process' }), () => 'b')).toMatchObject({ status: 'interrupted' });+ expect(overlayTextReport(project({ status: 'complete', basis: 'old', findings: [{ kind: 'overlap', severity: 'error' }] }), () => 'b'))+ .toMatchObject({ status: 'complete', current: false, counts: { errors: 1, overlap: 1 } });+ });+});diff --git a/server/services/musicVideo/overlayTextProbe.js b/server/services/musicVideo/overlayTextProbe.jsnew file mode 100644index 0000000000..fb42d3ff63--- /dev/null+++ b/server/services/musicVideo/overlayTextProbe.js@@ -0,0 +1,154 @@+/**+ * Music Video — the in-page half of the overlay text check (overlayTextService.js).+ *+ * Installed before a composition document's own scripts (openComposition+ * `initScripts`). Between `begin()` and `end()` it records every piece of text+ * the page draws: canvas `fillText` / `strokeText` (its glyph box through the+ * current transform, the font, colours, outline width, shadow and alpha) and+ * visible DOM / SVG text. While a capture is open the text is also HIDDEN —+ * canvas text calls are skipped and DOM text turns transparent — so the+ * screenshot taken after `end()` shows exactly what sits behind the words+ * (picture, plates, scrims), which is what contrast is measured against.+ *+ * Text drawn on a canvas that is not in the document (an offscreen canvas, a+ * WebGL texture) cannot be placed on the frame and is not recorded.+ *+ * The function is serialized into the page, so it must stay self-contained.+ */+function overlayTextProbe() {+ const C2D = globalThis.CanvasRenderingContext2D?.prototype;+ if (!C2D || globalThis.__portosTextProbe) return;+ const MAX_RECORDS = 400;+ // `on` records; `hidden` (from the first begin() on) keeps every later text+ // call off the canvas, so a redraw between end() and the screenshot (an+ // animation-frame loop) cannot paint the words back over the backdrop.+ const state = { on: false, hidden: false, records: [], seq: 0, style: null };+ const canvases = [];+ const fillText = C2D.fillText;+ const strokeText = C2D.strokeText;+ const layerOf = (canvas) => {+ let index = canvases.indexOf(canvas);+ if (index < 0) { canvases.push(canvas); index = canvases.length - 1; }+ return `canvas-${index}`;+ };+ const colorOf = (style) => (typeof style === 'string' ? style : null);+ const emOf = (font) => {+ const match = /(\d+(?:\.\d+)?)px/.exec(String(font || ''));+ return match ? Number(match[1]) : null;+ };+ function recordCanvas(ctx, kind, text, x, y, maxWidth) {+ if (state.records.length >= MAX_RECORDS) return;+ const canvas = ctx.canvas;+ if (!(canvas instanceof HTMLCanvasElement) || !canvas.isConnected || !canvas.width || !canvas.height) return;+ const rect = canvas.getBoundingClientRect();+ if (!rect.width || !rect.height) return;+ const str = String(text);+ if (!str.trim()) return;+ const sx = rect.width / canvas.width;+ const sy = rect.height / canvas.height;+ const m = ctx.measureText(str);+ let left = -m.actualBoundingBoxLeft;+ let right = m.actualBoundingBoxRight;+ if (maxWidth != null && Number.isFinite(maxWidth) && m.width > maxWidth && m.width > 0) {+ left *= maxWidth / m.width;+ right *= maxWidth / m.width;+ }+ const top = -m.actualBoundingBoxAscent;+ const bottom = m.actualBoundingBoxDescent;+ const T = ctx.getTransform();+ const xs = [];+ const ys = [];+ for (const [px, py] of [[x + left, y + top], [x + right, y + top], [x + left, y + bottom], [x + right, y + bottom]]) {+ xs.push(rect.left + (T.a * px + T.c * py + T.e) * sx);+ ys.push(rect.top + (T.b * px + T.d * py + T.f) * sy);+ }+ const scale = Math.sqrt(Math.abs(T.a * T.d - T.b * T.c)) * Math.sqrt(sx * sy);+ const em = emOf(ctx.font);+ const shadow = ctx.shadowBlur > 0 || ctx.shadowOffsetX || ctx.shadowOffsetY+ ? { color: colorOf(ctx.shadowColor), px: (ctx.shadowBlur / 2) * Math.sqrt(sx * sy) } : null;+ state.records.push({+ seq: state.seq++, source: 'canvas', layer: layerOf(canvas), kind, text: str.slice(0, 160),+ x0: Math.min(...xs), y0: Math.min(...ys), x1: Math.max(...xs), y1: Math.max(...ys),+ emPx: em ? em * scale : null, font: String(ctx.font || ''),+ color: kind === 'fill' ? colorOf(ctx.fillStyle) : colorOf(ctx.strokeStyle),+ lineWidth: kind === 'stroke' ? ctx.lineWidth * scale : 0,+ alpha: ctx.globalAlpha, shadow,+ });+ }+ const wrap = (original, kind) => function (text, x, y, maxWidth) {+ if (state.on) {+ try { recordCanvas(this, kind, text, x, y, maxWidth); } catch { /* a probe fault never breaks the page */ }+ }+ if (state.hidden) return undefined;+ return maxWidth === undefined ? original.call(this, text, x, y) : original.call(this, text, x, y, maxWidth);+ };+ C2D.fillText = wrap(fillText, 'fill');+ C2D.strokeText = wrap(strokeText, 'stroke');++ function opacityOf(element) {+ let alpha = 1;+ for (let el = element; el && el.nodeType === 1; el = el.parentElement) {+ const cs = getComputedStyle(el);+ if (cs.display === 'none') return 0;+ alpha *= Number(cs.opacity);+ }+ return alpha;+ }+ function domRecords() {+ const out = [];+ if (!document.body) return out;+ const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);+ for (let node = walker.nextNode(); node && out.length < MAX_RECORDS; node = walker.nextNode()) {+ const text = node.nodeValue.replace(/\s+/g, ' ').trim();+ const el = node.parentElement;+ if (!text || !el || el.closest('script, style, noscript, template, title')) continue;+ const cs = getComputedStyle(el);+ if (cs.visibility !== 'visible') continue;+ const alpha = opacityOf(el);+ if (!(alpha > 0)) continue;+ const range = document.createRange();+ range.selectNodeContents(node);+ const box = range.getBoundingClientRect();+ if (!box.width || !box.height) continue;+ const svg = el instanceof SVGElement;+ const strokeWidth = svg ? parseFloat(cs.strokeWidth) || 0 : parseFloat(cs.webkitTextStrokeWidth) || 0;+ const stroke = svg ? (cs.stroke !== 'none' ? cs.stroke : null) : cs.webkitTextStrokeColor;+ const shadow = !svg && cs.textShadow && cs.textShadow !== 'none'+ ? { color: (/rgba?\([^)]*\)/.exec(cs.textShadow) || [null])[0], px: Math.max(...(cs.textShadow.match(/(\d+(?:\.\d+)?)px/g) || ['0px']).map(parseFloat)) / 2 }+ : null;+ const font = `${cs.fontStyle} ${cs.fontWeight} ${cs.fontSize} ${cs.fontFamily}`;+ const base = { source: 'dom', layer: 'dom', text: text.slice(0, 160), x0: box.left, y0: box.top, x1: box.right, y1: box.bottom,+ emPx: parseFloat(cs.fontSize) || null, font, alpha, shadow };+ if (strokeWidth > 0 && stroke) out.push({ ...base, seq: state.seq++, kind: 'stroke', color: stroke, lineWidth: strokeWidth });+ out.push({ ...base, seq: state.seq++, kind: 'fill', color: svg ? (cs.fill !== 'none' ? cs.fill : null) : cs.color, lineWidth: 0, shadow });+ }+ return out;+ }+ const HIDE_CSS = '*, *::before, *::after { color: transparent !important; -webkit-text-stroke-color: transparent !important; text-shadow: none !important; caret-color: transparent !important; } svg text, svg tspan, svg textPath { fill: transparent !important; stroke: transparent !important; }';+ globalThis.__portosTextProbe = Object.freeze({+ /** Start recording (and hiding) text for the next seek. */+ begin() {+ state.style?.remove();+ state.style = null;+ state.records = [];+ state.seq = 0;+ state.on = true;+ state.hidden = true;+ return true;+ },+ /** Stop recording; returns every text record and hides DOM text for the backdrop screenshot. */+ end() {+ state.on = false;+ const records = state.records.concat(domRecords());+ state.records = [];+ const style = document.createElement('style');+ style.textContent = HIDE_CSS;+ (document.head || document.documentElement).appendChild(style);+ state.style = style;+ return records;+ },+ });+}++/** The script openComposition installs (an IIFE of overlayTextProbe). */+export const OVERLAY_TEXT_PROBE_SCRIPT = `(${overlayTextProbe.toString()})();`;diff --git a/server/services/musicVideo/overlayTextService.browser.test.js b/server/services/musicVideo/overlayTextService.browser.test.jsnew file mode 100644index 0000000000..72d73fa2dc--- /dev/null+++ b/server/services/musicVideo/overlayTextService.browser.test.js@@ -0,0 +1,114 @@+/**+ * The overlay text check end to end in a real headless Chrome: a document that+ * draws a corner readout under a big lyric, a pale caption on a pale frame, a+ * line past the right edge, a tiny tag and a DOM caption is staged like a+ * render, probed at its text moments, and each problem comes back once —+ * while a word ringed in a wide ink outline passes on the same pale frame. The+ * shipped layered template (lyricType.js) passes on a pale still, data readout+ * included.+ */+import { afterAll, describe, expect, it, vi } from 'vitest';+import { existsSync } from 'node:fs';+import { mkdir, writeFile } from 'node:fs/promises';+import { join } from 'node:path';+import { chromium } from 'playwright-core';+import { cleanupTempDataRoots, lazyTempDataRoot, makePathsProxy } from '../../lib/mockPathsDataRoot.js';++const chrome = [process.env.CHROME_PATH, chromium.executablePath(), '/usr/bin/google-chrome', '/usr/bin/chromium',+ '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'].find((path) => path && existsSync(path));++vi.mock('../../lib/paths.js', async (importOriginal) => makePathsProxy(await importOriginal(), { dataRoot: () => lazyTempDataRoot('mv-overlay-text-') }));+vi.mock('../settings.js', () => ({ getSettings: vi.fn(async () => ({})) }));+vi.mock('../browserService.js', () => ({ loadConfig: async () => ({ chromePath: chrome }) }));++const { PATHS } = await import('../../lib/paths.js');+const projects = await import('./projects.js');+const { importDocumentDirectory, importDocumentTemplate } = await import('./compositionDocument.js');+const { startOverlayTextCheck } = await import('./overlayTextService.js');+const { productionReadiness } = await import('./productionReview.js');++afterAll(() => cleanupTempDataRoots());++const PAGE = `<!doctype html><html><head><style>+ html, body { margin: 0; background: #f3ead7; }+ canvas { display: block; }+ #dom { position: absolute; left: 860px; top: 300px; color: #ffffff; font: 600 34px sans-serif; }+</style></head><body><canvas id="c" width="1280" height="720"></canvas><div id="dom">DOM CAPTION</div>+<script src="portos-mv.js"></script><script src="app.js"></script></body></html>`;++const APP = `+const ctx = document.getElementById('c').getContext('2d');+function draw() {+ ctx.fillStyle = '#f3ead7'; ctx.fillRect(0, 0, 1280, 720);+ // A corner readout on a plate too short for it, under a big outlined lyric.+ ctx.fillStyle = '#141217'; ctx.fillRect(40, 60, 380, 60);+ ctx.font = '500 40px monospace'; ctx.fillStyle = '#f3ead7'; ctx.fillText('20 MILLION YEARS', 56, 104);+ ctx.font = '900 96px sans-serif'; ctx.lineJoin = 'round'; ctx.lineWidth = 14; ctx.strokeStyle = '#141217';+ ctx.strokeText('WHOLE', 300, 130); ctx.fillStyle = '#f3ead7'; ctx.fillText('WHOLE', 300, 130);+ // Ringed in ink on the pale frame: readable.+ ctx.strokeText('BLOOM', 80, 330); ctx.fillText('BLOOM', 80, 330);+ // Pale on pale, no outline.+ ctx.font = '700 64px sans-serif'; ctx.fillStyle = '#fffaf0'; ctx.fillText('DISAPPEAR', 80, 480);+ // Past the right edge.+ ctx.fillStyle = '#141217'; ctx.fillText('OFF THE EDGE', 1040, 640);+ // Too small for a phone.+ ctx.font = '14px sans-serif'; ctx.fillText('tiny tag', 80, 600);+}+globalThis.portosComposition = { durationSec: 4, fps: 12, width: 1280, height: 720, async seek() { draw(); } };+`;++describe.skipIf(!chrome)('overlay text check (headless Chrome)', () => {+ it('flags each text problem once, names the shot, and passes outlined type', async () => {+ const source = join(PATHS.data, 'overlay-doc');+ await mkdir(source, { recursive: true });+ await writeFile(join(source, 'index.html'), PAGE);+ await writeFile(join(source, 'app.js'), APP);+ const created = await projects.createProject({ name: 'Overlay', composition: { mode: 'document' } });+ await projects.mutateProjectRecord(created.id, (current) => ({ project: { ...current,+ audioAnalysis: { durationSec: 4, beats: [], downbeats: [], sections: [] },+ lyricCues: [{ id: 'l1', text: 'whole species bloom', startSec: 0.5, endSec: 3, words: [] }] } }));+ await importDocumentDirectory(created.id, 'overlay-doc');++ const started = await startOverlayTextCheck(created.id);+ expect(started.readiness.storyboard.text.status).toBe('running');+ const check = await started.done;+ expect(check.status).toBe('complete');+ expect(check.textSamples).toBeGreaterThan(0);++ const kinds = (text) => check.findings.filter((f) => f.texts.some((t) => t.includes(text))).map((f) => f.kind).sort();+ expect(kinds('20 MILLION YEARS')).toContain('overlap');+ expect(check.findings.find((f) => f.kind === 'overlap').texts).toEqual(expect.arrayContaining(['20 MILLION YEARS', 'WHOLE']));+ expect(kinds('DISAPPEAR')).toEqual(['contrast']);+ expect(kinds('OFF THE EDGE')).toEqual(['off-frame']);+ expect(kinds('tiny tag')).toContain('small');+ expect(kinds('DOM CAPTION')).toEqual(['contrast']);+ expect(kinds('BLOOM')).toEqual([]);+ // One finding per problem however many frames showed it, errors first.+ expect(new Set(check.findings.map((f) => f.id)).size).toBe(check.findings.length);+ expect(check.findings[0].severity).toBe('error');++ const report = productionReadiness(await projects.getProject(created.id)).storyboard.text;+ expect(report).toMatchObject({ status: 'complete', current: true });+ expect(report.counts.errors).toBe(2);+ }, 120000);++ it('passes the shipped layered template: lyricType lines and a data readout on a pale still', async () => {+ const { default: sharp } = await import('sharp');+ await mkdir(PATHS.images, { recursive: true });+ await sharp({ create: { width: 1920, height: 1080, channels: 3, background: '#f1ece0' } }).png().toFile(join(PATHS.images, 'pale.png'));+ const created = await projects.createProject({ name: 'Layered', composition: { mode: 'document' } });+ await projects.mutateProjectRecord(created.id, (current) => ({ project: { ...current,+ audioAnalysis: { durationSec: 12, beats: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11], downbeats: [1, 5, 9], sections: [{ label: 'Verse', startSec: 0, endSec: 6 }, { label: 'Chorus', startSec: 6, endSec: 12 }] },+ scenes: [{ sceneId: 's1', order: 0, label: 'One', startSec: 0, endSec: 6, textZone: 'lower-left', referenceImageId: 'pale.png' }, { sceneId: 's2', order: 1, label: 'Two', startSec: 6, endSec: 12, textZone: 'upper-right', lyricRole: 'data', referenceImageId: 'pale.png' }],+ lyricCues: [+ { id: 'l1', text: 'whole species bloom and disappear', startSec: 0.5, endSec: 3, words: [] },+ { id: 'l2', text: 'twenty million years a second', startSec: 3.2, endSec: 5.5, words: [] },+ { id: 'l3', text: 'years since launch 764,465', startSec: 6.5, endSec: 9, words: [] },+ { id: 'l4', text: 'welcome to the club', startSec: 9.2, endSec: 11.5, words: [] }] } }));+ await importDocumentTemplate(created.id, 'layered');+ const started = await startOverlayTextCheck(created.id);+ const check = await started.done;+ expect(check).toMatchObject({ status: 'complete', findings: [] });+ expect(check.textSamples).toBeGreaterThan(4);+ }, 120000);+});diff --git a/server/services/musicVideo/overlayTextService.js b/server/services/musicVideo/overlayTextService.jsnew file mode 100644index 0000000000..4130f27ef7--- /dev/null+++ b/server/services/musicVideo/overlayTextService.js@@ -0,0 +1,124 @@+/**+ * Music Video — the overlay text quality pass (overlayText.js says what it+ * flags and why).+ *+ * A check renders the project's composition document headless at its text+ * moments (documentRender.js `probeDocumentText`) and stores the findings on+ * `productionReview.textCheck`, bound to the document, timing, shots and takes+ * it saw (`overlayTextBasis`). The storyboard approval shows them; an+ * autonomous run checks before its final render and sends text problems back+ * to the document's author (autonomousService.js).+ *+ * No provider call: a check is local browser work, started by the director (the+ * storyboard's button), by importing or accepting a new document, or by a run+ * the director started. One check per project at a time; a newer start+ * cancels the older one, whose result is then dropped.+ */+import { randomUUID } from 'node:crypto';+import { ServerError } from '../../lib/errorHandler.js';+import { getProject, mutateProjectRecord } from './projects.js';+import { musicVideoEvents } from './events.js';+import { overlayTextBasis, productionReadiness } from './productionReview.js';+import {+ OVERLAY_TEXT_PROCESS_ID, analyzeTextFrame, backdropStats, mergeTextRecords, planTextSampleTimes, summarizeTextFindings,+} from './overlayText.js';++const inflight = new Map(); // projectId → { id, controller, done }++const short = (id) => String(id).slice(0, 8);++function changed(project) {+ // The project-bearing notification the production review already pushes on.+ musicVideoEvents.emit('dev-artifact', { projectId: project.id, artifactId: null, project });+ return { project, readiness: productionReadiness(project) };+}++/** Refuses (409) unless the project renders a composition document with an analyzed song. */+function assertCheckable(project) {+ if (!project) throw new ServerError('Project not found', { status: 404, code: 'NOT_FOUND' });+ if (project.composition?.mode !== 'document' || !project.composition.document?.directory) {+ throw new ServerError('Overlay text is checked on a composition document. Import or author one first.', { status: 409, code: 'TEXT_CHECK_UNAVAILABLE' });+ }+ if (!(project.audioAnalysis?.durationSec > 0)) {+ throw new ServerError('Analyze the song before checking overlay text.', { status: 422, code: 'NO_TIMELINE' });+ }+}++/** Render the document at its text moments and return the stored check (no write). */+async function inspectOverlayText(project, { signal, onProgress } = {}) {+ const { probeDocumentText } = await import('./documentRender.js');+ const samples = [];+ let textSamples = 0;+ const result = await probeDocumentText({+ project, jobId: `text-check-${randomUUID()}`, signal, onProgress,+ sampleTimes: (data, clock) => planTextSampleTimes({ lyrics: data.lyrics, textCues: data.textCues, scenes: data.scenes, durationSec: clock.durationSec, fps: clock.fps }),+ onSample: ({ atSec, frame, records, backdrop }) => {+ const items = mergeTextRecords(records);+ if (items.length) textSamples += 1;+ for (const item of items) item.backdrop = backdropStats(backdrop, item);+ samples.push({ atSec, issues: analyzeTextFrame(items, frame) });+ },+ });+ return { samples: result.samples, textSamples, frame: result.frame, findings: summarizeTextFindings(samples, result.scenes) };+}++async function writeCheck(projectId, checkId, patch) {+ const { project } = await mutateProjectRecord(projectId, (current) => {+ // A newer check (or none) owns the record now: drop this one's result.+ if (current.productionReview?.textCheck?.id !== checkId) return { project: current };+ return { project: { ...current, productionReview: { ...current.productionReview,+ textCheck: { ...current.productionReview.textCheck, ...patch } } } };+ });+ return project;+}++async function runCheck(projectId, checkId, controller) {+ try {+ const project = await getProject(projectId);+ const outcome = await inspectOverlayText(project, { signal: controller.signal });+ const saved = await writeCheck(projectId, checkId, { status: 'complete', checkedAt: new Date().toISOString(), processId: null,+ samples: outcome.samples, textSamples: outcome.textSamples, frame: outcome.frame, findings: outcome.findings, error: null });+ const errors = outcome.findings.filter((f) => f.severity === 'error').length;+ console.log(`🔤 Overlay text check ${short(projectId)}: ${outcome.findings.length} finding${outcome.findings.length === 1 ? '' : 's'} (${errors} error${errors === 1 ? '' : 's'}) over ${outcome.samples} samples`);+ changed(saved);+ return saved.productionReview?.textCheck ?? null;+ } catch (err) {+ if (controller.signal.aborted) return null;+ console.error(`❌ Overlay text check ${short(projectId)} failed: ${err.message}`);+ const saved = await writeCheck(projectId, checkId, { status: 'failed', checkedAt: new Date().toISOString(), processId: null, error: String(err.message).slice(0, 500) })+ .catch(() => null);+ if (saved) changed(saved);+ return saved?.productionReview?.textCheck ?? null;+ } finally {+ if (inflight.get(projectId)?.id === checkId) inflight.delete(projectId);+ }+}++/**+ * Start a check on the project's current document (cancelling one already+ * running). Resolves `{ project, readiness, done }` once the running record is+ * written; `done` settles with the finished check (null when superseded).+ */+export async function startOverlayTextCheck(projectId) {+ assertCheckable(await getProject(projectId));+ inflight.get(projectId)?.controller.abort();+ const id = randomUUID();+ const controller = new AbortController();+ const { project } = await mutateProjectRecord(projectId, (current) => {+ assertCheckable(current);+ return { project: { ...current, productionReview: { ...current.productionReview,+ textCheck: { id, status: 'running', basis: overlayTextBasis(current), startedAt: new Date().toISOString(), processId: OVERLAY_TEXT_PROCESS_ID,+ findings: current.productionReview?.textCheck?.findings || [] } } } };+ });+ const entry = { id, controller, done: null };+ inflight.set(projectId, entry);+ entry.done = runCheck(projectId, id, controller);+ return { ...changed(project), done: entry.done };+}++/** Start a check after a new document lands; a project that cannot be checked is skipped quietly. */+export function checkOverlayTextInBackground(projectId) {+ startOverlayTextCheck(projectId).catch((err) => {+ if (!['TEXT_CHECK_UNAVAILABLE', 'NO_TIMELINE', 'NOT_FOUND'].includes(err.code)) console.error(`❌ Overlay text check ${short(projectId)} did not start: ${err.message}`);+ });+}diff --git a/server/services/musicVideo/productionReview.js b/server/services/musicVideo/productionReview.jsindex 17b183cc3b..553d920344 100644--- a/server/services/musicVideo/productionReview.js+++ b/server/services/musicVideo/productionReview.js@@ -7,6 +7,8 @@ import { musicVideoAllowsMedia } from '../../lib/musicVideoMediaPolicy.js';import { isNonBlankStr as text } from '../../lib/textUtils.js';import { cameraMovementFromText, getCameraMovement } from '../../lib/cameraMovements.js';import { cameraVarietyReport } from './shotCamera.js';+import { overlayTextReport } from './overlayText.js';+import { musicVideoAspect } from '../../lib/musicVideoAspect.js';const artifact = (project, id) => (project.devArtifacts || []).find(a => a.id === id && !a.deleted);const artifactBasis = a => a ? { id: a.id, version: a.version, file: a.file } : null;const source = p => {@@ -30,6 +32,18 @@ export const documentStoryboardBasis = project => hash({shots: project.productionReview?.draft?.storyboard,});+/**+ * What an overlay text check saw (overlayTextService.js): the document, the+ * frame, the song timing and lyrics, the text cues, the type style and every+ * shot's text placement and selected take. A change to any of them makes a check stale.+ */+export const overlayTextBasis = project => hash({+ document: project.composition?.document?.directory || null, aspect: musicVideoAspect(project), source: source(project),+ textCues: project.composition?.textCues ?? null, overlay: project.composition?.overlay ?? null, style: project.composition?.style ?? null,+ scenes: (project.scenes || []).map(({ sceneId, startSec, endSec, textZone, lyricRole, lyricText, cardText, referenceImageId, videoHistoryId, performanceEdit, visualLayer }) =>+ ({ sceneId, startSec, endSec, textZone, lyricRole, lyricText, cardText, referenceImageId, videoHistoryId, performanceEdit, visualLayer })),+});+// Share the evidence contract between new decisions and persisted approvals:// a legacy automatic waiver must not become production-ready after an upgrade.// Playback notes are optional: approving is the director's call, not a form to fill in.@@ -284,7 +298,8 @@ export function productionReadiness(project) {const proofApproved = !proofProblems.length && hasProofEvidence(review.approvals?.proof?.proofReview) && review.approvals?.proof?.basis === hash({ basis: basis.proof, excerptId: excerpt.id, filename: excerpt.filename });return { basis, inputs, alignment: { basis: alignmentBasis, status: draft.lyricsMode === 'instrumental' ? 'instrumental': draft.timingStatus !== 'verified' ? 'provisional' : review.alignmentBasis === alignmentBasis ? 'verified' : 'stale' }, documentShotImport: { documentDirectory: project.composition?.document?.directory || null, audioBasis: alignmentBasis }, art: { approved: artApproved, problems: [...new Set(artProblems)], stale: artApproved ? null : staleApproval(project, 'art', basis.art, inputs) },- storyboard: { approved: storyboardApproved, problems: [...new Set(boardProblems)], camera, stale: storyboardApproved ? null : staleApproval(project, 'storyboard', basis.storyboard, inputs) },+ // The overlay text check is advice on the storyboard, like camera variety; it never blocks approval.+ storyboard: { approved: storyboardApproved, problems: [...new Set(boardProblems)], camera, text: overlayTextReport(project, overlayTextBasis), stale: storyboardApproved ? null : staleApproval(project, 'storyboard', basis.storyboard, inputs) },proof: { approved: proofApproved, problems: proofProblems, excerptId: excerpt?.id || null, stale: proofApproved ? null : staleApproval(project, 'proof', basis.proof, inputs) },castAndSets: castAndSetsApproval(project),// The animated proof is optional review evidence: the approved storyboard is what the final render needs.