Add desktop/server MP4 export pipeline, hardening, and render tests (v1.3.0)

Desktop MP4 export renders frames from a hidden BrowserWindow via
capturePage, pipes PNGs to a bundled ffmpeg (libx264/yuv420p/+faststart),
and writes the file through an atomic temp-file swap. It shares scene
validation (shared/renderValidation.cjs) and the render.html renderer with
the standalone Puppeteer server, which is hardened in parallel.

Render worker & main (electron/):
- abortable render loop with an inactivity watchdog and cancel plumbing
- atomic temp-file + rename so a cancel/failure never truncates a
  pre-existing target (#7); stdin EPIPE / early-exit / backpressure-hang
  handled (#8)
- HiDPI frames normalized to canvas size (#10); odd dimensions padded to
  even (#13, also server); backgroundThrottling disabled (#12)
- reject canvases larger than the display (#11); single-render guard;
  isolated render session that blocks network requests (#5)

Tests:
- Electron harnesses (scripts/verify-*.cjs) for capture, export, cancel,
  timeout, assets, background, capture-fidelity, resolution, odd-dims,
  aggregated by verify-desktop-render.cjs
- server smoke + e2e and shared validation unit tests
- headless hook (src/devtools/headless.ts) to run the in-app suite under
  browser/electron hosts; pixel-diff util + capture fixtures (test/)
- dev_docs plans: integration, fixes (#7-#13), and the e2e/capture strategy

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

electron/main.cts

@@ -1,7 +1,13 @@
-import { app, BrowserWindow, Menu, shell } from 'electron'
-import type { BrowserWindow as BrowserWindowInstance, Event, MenuItemConstructorOptions } from 'electron'
+import { app, BrowserWindow, dialog, ipcMain, Menu, screen, shell } from 'electron'
+import type { BrowserWindow as BrowserWindowInstance, Event, IpcMainInvokeEvent, MenuItemConstructorOptions } from 'electron'
+import { randomUUID } from 'node:crypto'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { renderMp4Job } from './renderWorker.cjs'
+
+const { validateRenderRequest } = require('../shared/renderValidation.cjs') as {
+  validateRenderRequest(scene: unknown, options: unknown): RenderValidation
+}
 
 const isDev = !app.isPackaged
 const devServerUrl = process.env.VITE_DEV_SERVER_URL ?? 'http://localhost:5200'
@@ -11,12 +17,127 @@ const appIconPath = isDev
   : path.join(process.resourcesPath, 'build', 'icon.png')
 
 let mainWindow: BrowserWindowInstance | null = null
+const renderJobs = new Map<string, AbortController>()
+// Serialize desktop renders: one active export at a time, mirroring the
+// standalone server's MAX_ACTIVE_JOBS=1 (finding #6). The UI also guards this,
+// but IPC is directly invokable, so enforce it in main too.
+let renderActive = false
+
+interface RenderValidation {
+  ok: boolean
+  error?: string
+  scene?: Parameters<typeof renderMp4Job>[0]['scene']
+  options?: Parameters<typeof renderMp4Job>[0]['options']
+}
+
+interface RenderMp4Payload {
+  scene?: unknown
+  fps?: unknown
+  crf?: unknown
+  preset?: unknown
+  suggestedName?: unknown
+}
 
 function sendAppCommand(command: string): void {
   if (!mainWindow || mainWindow.isDestroyed()) return
   mainWindow.webContents.send('ruwio:menu-command', command)
 }
 
+function sendRenderProgress(
+  target: Electron.WebContents,
+  event: { jobId: string; progress: number; done: boolean; error?: string },
+): void {
+  if (!target.isDestroyed()) target.send('ruwio:render-progress', event)
+}
+
+function sanitizeMp4Name(value: unknown): string {
+  const raw = typeof value === 'string' && value.trim() ? value.trim() : 'animation.mp4'
+  const noPath = raw.replace(/[\\/]+/g, '-')
+  const safe = noPath.replace(/[^a-z0-9äöüß._-]+/gi, '-').replace(/^-+|-+$/g, '')
+  const named = safe || 'animation.mp4'
+  return named.toLowerCase().endsWith('.mp4') ? named : `${named}.mp4`
+}
+
+async function handleRenderMp4(event: IpcMainInvokeEvent, payload: RenderMp4Payload): Promise<{ path: string } | null> {
+  if (renderActive) {
+    throw new Error('A render is already in progress')
+  }
+  renderActive = true
+  try {
+    return await runRenderMp4(event, payload)
+  } finally {
+    renderActive = false
+  }
+}
+
+async function runRenderMp4(event: IpcMainInvokeEvent, payload: RenderMp4Payload): Promise<{ path: string } | null> {
+  const validation = validateRenderRequest(payload?.scene, {
+    fps: payload?.fps,
+    crf: payload?.crf,
+    preset: payload?.preset,
+  })
+  if (!validation.ok || !validation.scene || !validation.options) {
+    throw new Error(validation.error || 'invalid render request')
+  }
+
+  // The desktop path captures a hidden, on-screen BrowserWindow, which Chromium
+  // can't composite/capture beyond the physical display bounds — a canvas larger
+  // than the screen would silently yield truncated frames. Fail fast with a clear
+  // message instead (finding #11). The web/server path uses a headless viewport
+  // and has no such limit, so this is desktop-only.
+  const { width: canvasWidth, height: canvasHeight } = validation.scene.canvas
+  const { width: displayWidth, height: displayHeight } = screen.getPrimaryDisplay().size
+  if (canvasWidth > displayWidth || canvasHeight > displayHeight) {
+    throw new Error(
+      `Canvas ${canvasWidth}×${canvasHeight} is larger than this display ` +
+        `(${displayWidth}×${displayHeight}). Desktop export can't capture a canvas ` +
+        `bigger than the screen — reduce the canvas size and try again.`,
+    )
+  }
+
+  const window = BrowserWindow.fromWebContents(event.sender)
+  const saveOptions = {
+    title: 'Export MP4',
+    defaultPath: sanitizeMp4Name(payload?.suggestedName),
+    filters: [{ name: 'MP4 Video', extensions: ['mp4'] }],
+  }
+  const saveResult = window
+    ? await dialog.showSaveDialog(window, saveOptions)
+    : await dialog.showSaveDialog(saveOptions)
+  if (saveResult.canceled || !saveResult.filePath) return null
+
+  const jobId = randomUUID()
+  const controller = new AbortController()
+  renderJobs.set(jobId, controller)
+  sendRenderProgress(event.sender, { jobId, progress: 0, done: false })
+
+  try {
+    await renderMp4Job({
+      jobId,
+      scene: validation.scene,
+      options: validation.options,
+      outputPath: saveResult.filePath,
+      signal: controller.signal,
+      onProgress: (progress) => {
+        sendRenderProgress(event.sender, { jobId, progress, done: false })
+      },
+    })
+    sendRenderProgress(event.sender, { jobId, progress: 1, done: true })
+    return { path: saveResult.filePath }
+  } catch (err) {
+    const message = (err as Error).message || String(err)
+    sendRenderProgress(event.sender, { jobId, progress: 0, done: true, error: message })
+    throw err
+  } finally {
+    renderJobs.delete(jobId)
+  }
+}
+
+async function handleRenderCancel(_event: IpcMainInvokeEvent, jobId: unknown): Promise<void> {
+  if (typeof jobId !== 'string' || !jobId) return
+  renderJobs.get(jobId)?.abort()
+}
+
 function parseUrl(raw: string): URL | null {
   try {
     return new URL(raw)
@@ -256,6 +377,8 @@ function createMenu(): void {
 app.setName('RUWIO')
 
 app.whenReady().then(() => {
+  ipcMain.handle('ruwio:render-mp4', handleRenderMp4)
+  ipcMain.handle('ruwio:render-cancel', handleRenderCancel)
   createMenu()
   createMainWindow()