Document-mode live preview re-runs the film look's SVG filter on every video frame #11221

Problem

filmLookRuntimeSource() (server/lib/filmLook.js) installs the project's film look as one SVG <filter> on the document root of a composition page. That is right for the render (one evaluation per captured frame) and for a still, but the composition live preview (client/src/components/musicVideo/CompositionPreviewPlayer.jsx → the preview iframe, documentPreview.js) is a playing page: a browser re-runs an SVG filter chain over every decoded video frame, so a document-mode project with video takes and a saved look plays the same way the storyboard animatic did before #11220.

Measured in headless Chromium at phone width (390×219) on a 30 fps clip, filter on the box holding the video:

Adding the stages one at a time, the cost grows with the primitive count and the picture size (the full chain: 2.6 fps at half size, 0.2 fps at double size), not with any one stage. #11220 fixed the animatic (FilmLookFrame.jsx) by switching to filmLookMotionLayers() while the song plays; the document preview still takes the exact filter.

Decision

Give the runtime a playback mode that mirrors the animatic's: while the preview page is playing (the player's play/pause messages, portos-mv:*), the runtime removes the root filter and instead applies filmLookMotionLayers() — the CSS filter functions and the weave transform on the document root, and the overlay layers (cast washes, grain and tape tiles, vignette, leak) as fixed-position, pointer-events-none elements the runtime appends after the document's own layers, re-shifted from the same frame(n) hook. On pause and on every seek the runtime goes back to the exact filter, so a paused frame matches the render. The render path (documentRenderInitScripts → openComposition({ initScripts })) never plays, so it keeps the exact filter unchanged.

filmLookMotionLayers is not self-contained today (it uses module-level helpers), and the runtime inlines by toString(): either make it self-contained like filmLookFilterMarkup (the test in server/lib/filmLook.test.js that re-evaluates the function standalone is the pattern) or inline its helpers into the runtime source string.

Files

• server/lib/filmLook.js — filmLookRuntimeSource, filmLookMotionLayers
• client/src/components/musicVideo/CompositionPreviewPlayer.jsx — tell the runtime when the preview is playing (it already posts portos-mv:film-look)
• server/services/musicVideo/documentPreview.js — where the preview page is assembled
• docs/HTML_COMPOSITIONS.md — "Music-video film look" section

Acceptance

• A document-mode project with video takes and the Neon rain look plays its live preview at the clip's frame rate in a headless-Chromium check like the one above (script pattern: a page with a looping <video>, requestVideoFrameCallback count over 3 s).
• Paused or after a seek, the preview page's root carries the exact url(#portos-film-look) filter, and a document render's captured frames are byte-identical before and after the change (the render never enters playback mode).
• The overlay elements the runtime adds never intercept pointer events and sit above every document layer, lyrics included.
• filmLook.test.js covers the mode switch; the existing runtime tests still pass.

Model medium: routine multi-file work in a known pattern. Effort high: placing overlays correctly inside an arbitrary sandboxed document (stacking contexts, the lyric layer, the seek wrapper) needs care per step.