@lightcone-ai/daemon 0.23.5 → 0.23.7

package/mcp-servers/official/media-tools/index.js

@@ -92,7 +92,19 @@ server.tool(
   + 'Takes any video produced by compose_video_v2 / record_url_narration / etc. and adds '
   + 'one or more on-screen title cards with animation presets (fade+zoom pop, per-character karaoke fill). '
   + 'The default narration subtitle burned by compose_video_v2 stays at the bottom; titles default to the top band so they do not collide. '
-  + 'Output is a new mp4; original is not modified. Skip this tool entirely when a plain video is desired — not every video needs title effects.',
+  + 'Output is a new mp4; original is not modified.\n\n'
+  + 'STANDARD opening 引导语 title (URL recruitment short videos — do this by default): the video '
+  + 'opens with a 引导语 lead-in section, and that line is rendered HERE as an eye-catching centered '
+  + 'title card — NOT as a plain bottom subtitle. Recipe:\n'
+  + '  - preset: "karaoke_punch" (per-character fill reads as a real effect; "fade_zoom" is too plain for an opener)\n'
+  + '  - position: "center"\n'
+  + '  - style: { font_size 110-120 (large), color a vivid "#FFE000"-style, outline_color "#000000" }\n'
+  + '  - start_ms: 0, end_ms: the opening section duration — the card clears exactly when the first content section begins.\n'
+  + 'Long titles auto-wrap; you may also place an explicit "\\n" for a clean 2-line break.\n'
+  + 'The opening section itself must be a FRAMELESS lead-in — its operations use raw `y` (no `block`, '
+  + 'so the recorder draws no spotlight) and it carries NO bottom subtitle (subtitle_text empty); the '
+  + '引导语 appears only as this centered card.\n\n'
+  + 'Skip this tool when a plain video with no title cards is desired.',
   {
     input_path: z.string().min(1).describe('Absolute path to the source mp4 (e.g. the output of compose_video_v2).'),
     output_path: z.string().optional().describe('Optional absolute output path. If omitted, writes to a tmp path and returns it.'),
@@ -258,7 +270,8 @@ server.tool(
       operations: z.array(z.object({
         atom: z.enum(['scroll_to', 'hold', 'cursor_focus']),
         duration_ms: z.union([z.number(), z.literal('fill')]).describe('Atom duration in ms. "fill" allowed only on the LAST hold to auto-fill remaining audio time.'),
-        y: z.number().optional(),
+        block: z.string().optional().describe('scroll_to: id of a page_understanding block to frame. The recorder centers it in the viewport. Use this for content sections — do NOT write pixel y.'),
+        y: z.number().optional().describe('scroll_to: raw scrollTop. Only for a content-agnostic opening drift — for content blocks use `block` instead.'),
         x: z.number().optional(),
         curve: z.enum(['easeInOutQuad', 'linear', 'easeOutQuad']).optional(),
         mode: z.enum(['auto', 'touch', 'programmatic']).optional(),
@@ -266,29 +279,25 @@ server.tool(
       })).optional().describe(
         'For visual_kind=video URL recording sections: ordered atom sequence. Sum of duration_ms '
         + 'must equal audio_duration_ms (±200ms); use "fill" on the last hold to auto-balance.\n\n'
-        + 'READING-FLOW MODE (REQUIRED — enforced by lint): operations must simulate a person '
-        + 'sliding a finger through the page while narrating, pausing at key spots to explain. '
-        + 'Concretely:\n'
-        + '  • Each non-opening segment MUST contain at least one scroll_to with duration_ms >= 1500.\n'
-        + '  • Any hold with duration_ms > 2000 MUST be immediately preceded by a scroll_to with duration_ms >= 1500.\n'
-        + '  • Avoid the "jump + freeze" anti-pattern: scroll_to(duration_ms < 1000) followed by hold(duration_ms > 2000). '
-        + 'It makes the recording feel like a screenshot slideshow, not a page being read.\n\n'
-        + 'GOOD example for a 9.5s segment narrating "宁波银行金融科技部主推 FinTech 暑期专项":\n'
+        + 'Every content section is exactly: scroll_to{block} → hold. scroll_to FRAMES A CONTENT '
+        + 'BLOCK — pass `block: "<id>"` (a block id from page_understanding.blocks) and the recorder '
+        + 'CENTERS that block in the viewport. Do NOT write pixel `y` for content blocks; raw `y` is '
+        + 'only for a content-agnostic opening drift.\n'
+        + '  • One section narrates ONE block — every scroll_to in a section references the SAME '
+        + 'block id (2+ distinct block ids → REJECTED: section_spans_multiple_blocks).\n'
+        + '  • scroll_to is a short TRANSITION between blocks (~500-800ms). hold is where the '
+        + 'NARRATION happens and the picture is STILL — long holds (2-5s) are the norm.\n'
+        + '  • A block taller than the viewport just shows its centered slice, HELD STILL. Do NOT '
+        + 'pan / slow-scroll through it — the picture must not move while you narrate; partial '
+        + 'visibility of a tall block is accepted.\n'
+        + '  • Every non-opening segment MUST start with a scroll_to (REJECTED otherwise: transition_required).\n\n'
+        + 'GOOD — a 5s segment narrating block b2:\n'
         + '  [\n'
-        + '    { atom: "scroll_to", y: 280,  duration_ms: 2500 },   // slow slide while saying "宁波银行金融科技部，正式开放 FinTech 暑期专项"\n'
-        + '    { atom: "hold",                duration_ms: 1200 },   // brief pause on title to let viewer read\n'
-        + '    { atom: "scroll_to", y: 980,  duration_ms: 3200 },   // continue sliding while narrating job content\n'
-        + '    { atom: "hold",                duration_ms: 1400 },   // pause on key bullet list\n'
-        + '    { atom: "scroll_to", y: 1450, duration_ms: 1500 },   // final slide to closing block\n'
-        + '    { atom: "hold",                duration_ms: "fill" }, // remaining audio time (~700ms expected)\n'
+        + '    { atom: "scroll_to", block: "b2", duration_ms: 700 },  // 0.7s transition, recorder centers b2\n'
+        + '    { atom: "hold",                   duration_ms: "fill" }, // ~4.3s: narrate b2, picture still\n'
         + '  ]\n\n'
-        + 'BAD example (will be REJECTED by reading_flow_violation):\n'
-        + '  [\n'
-        + '    { atom: "scroll_to", y: 1000, duration_ms: 600 },    // jump cut\n'
-        + '    { atom: "hold",                duration_ms: 5000 },   // 5s freeze ← rejected\n'
-        + '    { atom: "scroll_to", y: 2500, duration_ms: 800 },    // jump cut\n'
-        + '    { atom: "hold",                duration_ms: "fill" }, // ← rejected\n'
-        + '  ]',
+        + 'BAD (REJECTED): a segment starting with hold (transition_required); a segment whose '
+        + 'scroll_to ops reference two different blocks (section_spans_multiple_blocks).',
       ),
     })).describe('Segments to plan. audio_path is required for each. V5 fields (action, target_y, target_y_content_label, focus_region, transition_ms, dwell_ms, phase.beats[]) are rejected.'),
   },
@@ -370,22 +379,27 @@ server.tool(
 );
 
 // ── record_url_narration (migrated from chat-bridge) ──────────────────────
-// Records a silent mp4 of a URL via Chromium+Xvfb+Playwright recordVideo,
+// Records a silent mp4 of a URL via headless Chromium + Playwright recordVideo,
 // driven by a beat-by-beat plan. Hard-block: requires plan_video_segments to
 // have run in this session — hand-written dwell_ms has drifted from TTS
 // audio in production runs (Tasks #20/#25/#26), forcing re-records.
 server.tool(
   'record_url_narration',
-  'V6 record_url_narration. Drives Chromium on Xvfb + Playwright recordVideo to capture a silent mp4 per section, then ffmpeg-slices into output_paths. Each mp4 passes to compose_video_v2 as a video-kind segment.\n\n'
+  'V6 record_url_narration. Drives headless Chromium + Playwright recordVideo to capture a silent mp4 per section, then ffmpeg-slices into output_paths. Each mp4 passes to compose_video_v2 as a video-kind segment.\n\n'
   + 'REQUIRES page_understanding (from analyze_page) — used for safe-region check (scroll_to.y / cursor_focus.y rejected if in unsafe_regions) and preheat alignment (same full-scroll-then-top pre-roll as analyze_page).\n\n'
-  + 'plan.sections[*].operations[] is the visual beat — each operation is one of three atom calls:\n'
-  + '  - scroll_to: { y, duration_ms, curve?, mode?, jitter_px? }\n'
+  + 'plan.sections[*].operations[] is the visual beat — a content section is scroll_to{block} → hold:\n'
+  + '  - scroll_to: { block | y, duration_ms, curve?, mode? } — pass `block` (a page_understanding '
+  + 'block id) and the recorder CENTERS that block in the viewport, then the section holds STILL '
+  + 'on it. A block taller than the viewport shows its centered slice held still (no pan). Raw '
+  + '`y` is only for a content-agnostic opening drift.\n'
   + '  - hold:      { duration_ms } — duration_ms="fill" allowed on the LAST hold to auto-balance with audio_duration_ms\n'
   + '  - cursor_focus: { x, y, duration_ms }\n\n'
+  + 'The recorder automatically draws a spotlight highlight (bordered frame + dimmed surround) around '
+  + "each section's block once its scroll lands — automatic, no plan field controls it.\n\n"
   + 'V5 fields are rejected: action / target_y / target_y_content_label / focus_region / transition_ms / dwell_ms (set by plan_video_segments only) / phase.beats[].\n\n'
   + 'Standard chain: analyze_page → synthesize_tts × N → plan_video_segments → record_url_narration + compose_video_v2.\n\n'
   + 'ALWAYS pass output_paths as an array with one mp4 path per plan.sections entry (single-section is a 1-element array). The tool records the URL ONCE continuously (one browser session, natural scroll flow across all sections), then ffmpeg-slices at section boundaries. One URL = one call.\n\n'
-  + 'Runtime: Linux daemon with Xvfb + Chromium + ffmpeg. macOS / Windows fail at startup.',
+  + 'Runtime: daemon with Chromium + ffmpeg.',
   {
     url: z.string().describe('Page URL to record (must match the URL passed to analyze_page that produced page_understanding).'),
     page_understanding: z.record(z.any()).describe('Output of analyze_page for this URL. Required. Provides full_height_px / viewport / preheat_strategy / unsafe_regions[] for safety validation, and blocks[] / narrative_arc as informational metadata (the recorder itself only needs the safety bits).'),
@@ -398,12 +412,13 @@ server.tool(
         operations: z.array(z.object({
           atom: z.enum(['scroll_to', 'hold', 'cursor_focus']),
           duration_ms: z.number().describe('Atom duration in ms. (plan_video_segments may have expanded a "fill" value already.)'),
-          y: z.number().optional(),
+          block: z.string().optional().describe('scroll_to: page_understanding block id to frame. Recorder centers it and the section holds still. Use for content sections instead of pixel y.'),
+          y: z.number().optional().describe('scroll_to: raw scrollTop — only for a content-agnostic opening drift.'),
           x: z.number().optional(),
           curve: z.enum(['easeInOutQuad', 'linear', 'easeOutQuad']).optional(),
           mode: z.enum(['auto', 'touch', 'programmatic']).optional(),
           jitter_px: z.number().optional(),
-        })).min(1).describe('Ordered atom sequence executed during this section.'),
+        })).min(1).describe('Ordered atom sequence executed during this section. Pass the plan_video_segments output verbatim.'),
       })).min(1),
     }).describe('plan.sections[] — each section has text/audio_path/dwell_ms (filled by plan_video_segments) and operations[].'),
     output_paths: z.array(z.string()).min(1).describe('REQUIRED. Workspace-relative mp4 paths, one per plan.sections entry. The tool records ONCE continuously and slices at section boundaries (phase_start / phase_end events).'),

package/mcp-servers/official/media-tools/lib/render.js

@@ -83,14 +83,15 @@ function buildAssContent({ playResX, playResY, overlays }) {
     'ScriptType: v4.00+',
     `PlayResX: ${playResX}`,
     `PlayResY: ${playResY}`,
-    'WrapStyle: 2',
+    'WrapStyle: 0',
     '',
     '[V4+ Styles]',
     'Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding',
     // PrimaryColour white, SecondaryColour orange (for karaoke fill), OutlineColour black,
-    // Bold on, Outline 4px, Shadow 2px, default Alignment middle-center (5) — events
-    // override per-line via \an.
-    `Style: Title,${DEFAULT_FONT},96,&H00FFFFFF,&H000066FF,&H00000000,&H80000000,-1,0,0,0,100,100,0,0,1,4,2,5,30,30,0,1`,
+    // Bold on, Outline 6px (thick — punchy contrast over busy page backgrounds),
+    // Shadow 2px, default Alignment middle-center (5) — events override per-line via \an.
+    // WrapStyle 0 (above) auto-wraps long titles instead of clipping them.
+    `Style: Title,${DEFAULT_FONT},96,&H00FFFFFF,&H000066FF,&H00000000,&H80000000,-1,0,0,0,100,100,0,0,1,6,2,5,30,30,0,1`,
     '',
     '[Events]',
     'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@lightcone-ai/daemon",
-  "version": "0.23.5",
+  "version": "0.23.7",
   "type": "module",
   "main": "src/index.js",
   "bin": {
-    "lightcone-daemon": "src/index.js"
+    "lightcone-daemon": "src/index.js",
+    "lightcone": "src/cli.js"
   },
   "files": [
     "src",

package/src/_vendor/video/recorder/atoms.js

@@ -24,23 +24,18 @@ async function readScrollY(page) {
 // ── atomScrollTo ─────────────────────────────────────────────────────────────
 // Animated scroll from current position to target_y over duration_ms.
 //
-// Mode selection (the bit that took an end-to-end failure to learn):
-//   - 'programmatic' (default for distance >= 240px): runs the easing loop
-//     inside page.evaluate via root.scrollTo. Lands EXACTLY at target_y.
-//     Lacks the rubber-band/fling physics of real touch, but reliable.
-//   - 'touch' (default for short distances): humanizedScroll → CDP touch.
-//     Produces natural gesture physics (rubber-band, inertia) but for
-//     larger distances the multi-segment swipe gets broken up into rapid
-//     micro-flings that interfere with each other, and the page often
-//     ends up nowhere near the intended target_y. Safe for distances
-//     that fit in a single ~260px finger swipe.
-//   - 'auto' (default): picks 'touch' for distance < 240px (single
-//     segment, no fling interference), 'programmatic' otherwise.
-//
-// Discovered the hard way: scroll_to_dwell macro with ~18% transition
-// for 1100+ px distances dispatched 5 CDP swipes in ~1s; each touchEnd
-// kicked off a fling that the next touchStart immediately cancelled, so
-// the cumulative scroll never reached target.
+// Mode selection:
+//   - 'programmatic': RAF-driven easing loop inside page.evaluate via
+//     root.scrollTo. Every frame moves, vertical only, lands EXACTLY at
+//     target_y. This is what a smooth between-blocks transition needs.
+//   - 'touch': humanizedScroll → CDP touch. Real gesture physics (rubber-
+//     band, inertia) but splits scroll > 260px into multiple swipes with
+//     fling-cancel-fling boundaries and ±18-26px horizontal nudge — looks
+//     like a shaky multi-tap drag, not a clean slide.
+//   - 'auto' (default): resolves to 'programmatic'. Touch's gesture physics
+//     lost out to a clean slide for narration video; it stays reachable
+//     only via explicit `mode: 'touch'`. See the resolvedMode block below
+//     for the full rationale.
 //
 // Params:
 //   target_y      — absolute Y in page coordinates (required)
@@ -53,7 +48,7 @@ export async function atomScrollTo(page, _ctx, {
   target_y,
   duration_ms,
   curve = 'easeInOutQuad',
-  jitter_px = 2,
+  jitter_px = 0,  // 不要微动 — 用户反复明确要求
   from_y = null,
   mode = 'auto',
 } = {}) {
@@ -70,17 +65,21 @@ export async function atomScrollTo(page, _ctx, {
   const durationMs = Number(duration_ms);
   const distance = Math.abs(targetY - fromY);
 
-  // Auto-mode heuristic: touch works for short distances (single segment, no
-  // inter-segment fling interference) OR slow velocities (each segment has
-  // time to settle before the next starts). Fast long-distance scrolls fall
-  // back to programmatic, where the easing loop drives root.scrollTo
-  // deterministically.
-  // Thresholds chosen empirically against the v4 failure mode (~1100px in
-  // ~1000ms → ~1100 px/s, fling-interrupt-fling, page never reached target).
-  const velocity = durationMs > 0 ? (distance / durationMs) * 1000 : 0; // px/s
+  // Auto-mode: default to programmatic (RAF-driven smooth scroll). The touch
+  // path uses humanizedScroll which splits any scroll > 260px into multiple
+  // CDP swipes, each with ±18-26px random horizontal nudge and fling-cancel-
+  // fling boundaries — that looks like "颤抖着分多次拨", not a clean slide.
+  // User feedback is unambiguous: scroll must be a smooth transition between
+  // content blocks, not a teleport (instant snap) and not a wobble (multi-
+  // segment touch with horizontal drift). Programmatic with RAF achieves
+  // both — every frame moves, vertical only, no inter-segment pauses.
+  // Touch mode remains available via explicit `mode: 'touch'` for callers
+  // that specifically want gesture physics.
+  const velocity = durationMs > 0 ? (distance / durationMs) * 1000 : 0; // px/s (kept for diagnostics)
+  void velocity;
   const resolvedMode = mode === 'programmatic' || mode === 'touch'
     ? mode
-    : (distance < 240 || velocity < 500 ? 'touch' : 'programmatic');
+    : 'programmatic';
 
   if (resolvedMode === 'touch') {
     await humanizedScroll(page, {
@@ -96,68 +95,75 @@ export async function atomScrollTo(page, _ctx, {
       targetY,
       durationMs,
       curve,
-      jitterPx: Math.max(0, Number(jitter_px) || 0),
     });
   }
   return { anchorY: Math.round(targetY) };
 }
 
-// Programmatic scroll: hands the animation off to the browser's native
-// scroll engine via `scroll-behavior: smooth`. That way the easing runs on
-// the compositor thread at the display refresh rate, independent of how
-// busy the page's JS is. The JS-driven setTimeout approach we tried first
-// gets badly throttled on JS-heavy article pages (60Hz timers can stretch
-// to 150-200ms), turning a 1s transition into 5-8s.
+// Programmatic scroll: JS-driven RAF loop that incrementally updates the
+// scroll position frame-by-frame over `durationMs`. This produces an actual
+// smooth scroll the viewer sees in the recording — the previous version
+// did a hard instant snap and then a static wait, which looked like a
+// teleport ("跳一下然后定格"), not like a person sliding a page.
+//
+// Why not native `scroll-behavior: smooth` or `scrollTo({behavior:'smooth'})`?
+// In Playwright + a headless mobile context, native smooth-scroll often
+// gets capped to a fixed short duration (~300-500ms) regardless of distance,
+// or is throttled by the page's own scroll logic. We need a duration we
+// control end-to-end.
 //
-// The wait is Node-side, so even if the in-page scrollend never fires we
-// still cap the section at durationMs and move on. We deliberately do NOT
-// wait for scrollend — empirically faster than dispatching the event on
-// page-heavy mobile sites.
+// Frame loop runs inside page.evaluate so it stays in lockstep with the
+// page's render thread — important when recordVideo is capturing 30fps.
 async function programmaticScroll(page, {
   fromY,
   targetY,
   durationMs,
+  curve = 'easeInOutQuad',
 } = {}) {
-  // Try every plausible scroll target — mobile article pages sometimes have
-  // a fixed-position outer body and scroll happens on an inner container.
-  // We dispatch to all candidates and let whichever one is actually the
-  // scroller win. Returns the diagnostics so we can debug when the page
-  // refuses to scroll.
-  const diag = await page.evaluate((input) => {
-    const candidates = [];
-    if (document.scrollingElement) candidates.push(document.scrollingElement);
-    if (document.documentElement) candidates.push(document.documentElement);
-    if (document.body) candidates.push(document.body);
-    candidates.push(window);
-
-    const before = candidates.map((c) => {
-      if (c === window) return { tag: 'window', y: window.scrollY };
-      return { tag: c.tagName, y: c.scrollTop };
-    });
-
-    // Hard snap to target on every candidate (instant, no animation).
-    for (const c of candidates) {
-      try {
-        if (c === window) window.scrollTo(0, input.targetY);
-        else { c.scrollTop = input.targetY; }
-      } catch { /* ignore */ }
+  await page.evaluate(async (input) => {
+    function pickScroller() {
+      if (document.scrollingElement) return document.scrollingElement;
+      if (document.documentElement) return document.documentElement;
+      return document.body;
     }
+    function easeInOutQuad(t) { return t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2; }
+    function easeOutQuad(t) { return 1 - (1 - t) * (1 - t); }
+    function linear(t) { return t; }
+    const ease = input.curve === 'linear' ? linear
+      : input.curve === 'easeOutQuad' ? easeOutQuad
+      : easeInOutQuad;
 
-    const after = candidates.map((c) => {
-      if (c === window) return { tag: 'window', y: window.scrollY };
-      return { tag: c.tagName, y: c.scrollTop };
-    });
+    const scroller = pickScroller();
+    const startY = (scroller === document.scrollingElement || scroller === document.documentElement)
+      ? scroller.scrollTop : window.scrollY;
+    const delta = input.targetY - startY;
+    const start = performance.now();
 
-    return {
-      requested_target: input.targetY,
-      before, after,
-      maxScroll: document.documentElement?.scrollHeight,
-      innerHeight: window.innerHeight,
-    };
-  }, { fromY, targetY });
-  void diag;
-  // Brief dwell to let the page settle the snap before next atom starts.
-  await page.waitForTimeout(Math.max(80, Math.round(durationMs * 0.3)));
+    return new Promise((resolve) => {
+      function tick(now) {
+        const elapsed = now - start;
+        const t = Math.min(1, elapsed / input.durationMs);
+        const y = startY + delta * ease(t);
+        try {
+          if (scroller === window) window.scrollTo(0, y);
+          else { scroller.scrollTop = y; }
+        } catch { /* ignore */ }
+        if (t < 1) {
+          requestAnimationFrame(tick);
+        } else {
+          // Final snap to exact target (in case of sub-pixel drift).
+          try {
+            if (scroller === window) window.scrollTo(0, input.targetY);
+            else { scroller.scrollTop = input.targetY; }
+          } catch { /* ignore */ }
+          resolve();
+        }
+      }
+      requestAnimationFrame(tick);
+    });
+  }, { fromY, targetY, durationMs, curve });
+  // Tiny settle so the next atom sees the scroll committed.
+  await page.waitForTimeout(50);
 }
 
 // ── atomHold ─────────────────────────────────────────────────────────────────

package/src/_vendor/video/recorder/chromium-driver.js

@@ -30,7 +30,6 @@ function normalizeUrl(value) {
 }
 
 export async function launchChromiumMobile({
-  display,
   viewport = DEFAULT_VIEWPORT,
   userAgent = IOS_UA,
   deviceScaleFactor = 1,
@@ -70,10 +69,7 @@ export async function launchChromiumMobile({
     headless,
     channel,
     args: launchArgs,
-    env: {
-      ...process.env,
-      DISPLAY: normalizeText(display) || process.env.DISPLAY,
-    },
+    env: process.env,
     ...launchOptions,
   });
 

package/src/_vendor/video/recorder/index.js

@@ -5,8 +5,6 @@ import os from 'node:os';
 import path from 'node:path';
 
 import { launchChromiumMobile, openPageAndSettle } from './chromium-driver.js';
-import { defaultDisplayPool } from './display-pool.js';
-import { createUnexpectedExitWatcher, waitForProcessExit } from './ffmpeg-runner.js';
 import { executePlanPhases, normalizePlanSections } from './plan-executor.js';
 
 const DEFAULT_VIEWPORT = Object.freeze({ width: 1080, height: 1920 });
@@ -60,91 +58,6 @@ function resolveUrl({ url, plan }) {
   throw error;
 }
 
-function createXvfbExitError({ code, signal, stderr }) {
-  const error = new Error(`xvfb_exited_unexpectedly:code=${code ?? 'null'}:signal=${signal ?? 'none'}`);
-  error.code = 'XVFB_EXITED_UNEXPECTEDLY';
-  error.exitCode = code;
-  error.signal = signal;
-  error.stderr = stderr;
-  return error;
-}
-
-async function stopXvfb(runner, {
-  signal = 'SIGTERM',
-  timeoutMs = 5000,
-  killTimeoutMs = 2000,
-} = {}) {
-  const child = runner?.child;
-  if (!child || child.exitCode !== null) return child?.exitCode ?? 0;
-
-  child.kill(signal);
-  const firstExit = await waitForProcessExit(child, timeoutMs);
-  if (!firstExit.timedOut) return firstExit.code;
-
-  child.kill('SIGKILL');
-  const forceExit = await waitForProcessExit(child, killTimeoutMs);
-  return forceExit.code;
-}
-
-async function startXvfb({
-  display,
-  width,
-  height,
-  colorDepth = 24,
-  startupProbeMs = 1200,
-  xvfbBin = 'Xvfb',
-} = {}) {
-  const args = [
-    display,
-    '-screen',
-    '0',
-    `${width}x${height}x${colorDepth}`,
-    '-ac',
-    '+extension',
-    'RANDR',
-  ];
-
-  let stderr = '';
-  let spawnError = null;
-  const child = spawn(xvfbBin, args, {
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
-
-  child.stderr?.on('data', (chunk) => {
-    const next = `${stderr}${String(chunk)}`;
-    stderr = next.length > 8000 ? next.slice(next.length - 8000) : next;
-  });
-  child.once('error', (error) => {
-    spawnError = error;
-  });
-
-  await new Promise(resolve => setTimeout(resolve, Math.max(0, Number(startupProbeMs) || 0)));
-
-  if (spawnError) {
-    const error = new Error(`xvfb_spawn_failed:${spawnError.message}`);
-    error.code = 'XVFB_SPAWN_FAILED';
-    throw error;
-  }
-
-  if (child.exitCode !== null) {
-    throw createXvfbExitError({
-      code: child.exitCode,
-      signal: child.signalCode,
-      stderr,
-    });
-  }
-
-  const runner = {
-    child,
-    display,
-    args,
-    getStderr: () => stderr,
-    stop: (options) => stopXvfb(runner, options),
-  };
-
-  return runner;
-}
-
 async function scrollToTop(page) {
   await page.evaluate(() => {
     const root = document.scrollingElement || document.documentElement;
@@ -363,9 +276,6 @@ export async function recordUrlNarration({
   viewport = DEFAULT_VIEWPORT,
   fps = DEFAULT_FPS,
   settle_ms = 4000,
-  displayPool = defaultDisplayPool,
-  startupProbeMs = 1200,
-  xvfbStopTimeoutMs = 5000,
   postPlanTailMs = 600,
   recordingDir = null,
   launchChromiumFn = launchChromiumMobile,
@@ -423,33 +333,16 @@ export async function recordUrlNarration({
   const ownTempDir = !recordingDir;
   const recVideoDir = recordingDir || await mkdtemp(path.join(os.tmpdir(), 'lc-recvid-'));
 
-  let displayLease;
-  let xvfb;
-  let xvfbWatcher;
   let browserSession = null;
   let primaryError = null;
   const cleanupErrors = [];
 
   try {
-    displayLease = await displayPool.acquireDisplay();
-    const display = displayLease.display;
-
-    xvfb = await startXvfb({
-      display,
-      width: normalizedViewport.width,
-      height: normalizedViewport.height,
-      startupProbeMs,
-    });
-    xvfbWatcher = createUnexpectedExitWatcher(xvfb.child, 'xvfb');
-
     // The page recording captures the page viewport only (no browser chrome),
-    // regardless of the on-screen window. recordVideo starts when the page is
-    // created, so the webm includes goto + settle; we measure that head and trim
-    // it off in transcodeFn.
-    const recordStartedAt = nowMs();
+    // regardless of the on-screen window.
     browserSession = await launchChromiumFn({
-      display,
       viewport: normalizedViewport,
+      headless: true,
       contextOptions: {
         recordVideo: {
           dir: recVideoDir,
@@ -457,6 +350,14 @@ export async function recordUrlNarration({
         },
       },
     });
+    // recordVideo's webm timeline starts at t=0 when the page is created —
+    // which happens INSIDE launchChromiumFn. Capture the head-trim reference
+    // here, right after it returns, NOT before the launch: the webm has no
+    // frames for the browser-launch interval, so measuring from before launch
+    // would make headTrimMs overshoot by the launch duration and ffmpeg's
+    // `-ss headTrimMs` would clip the opening of the first plan section,
+    // shifting every section's visuals late against its narration audio.
+    const recordStartedAt = nowMs();
     const videoHandle = typeof browserSession.page.video === 'function'
       ? browserSession.page.video()
       : null;
@@ -480,15 +381,14 @@ export async function recordUrlNarration({
 
     const headTrimMs = Math.max(0, nowMs() - recordStartedAt);
 
-    const eventsLog = await Promise.race([
-      executePlanPhases(browserSession.page, executablePlan, { pageUnderstanding }),
-      xvfbWatcher.promise,
-    ]);
+    const eventsLog = await executePlanPhases(browserSession.page, executablePlan, {
+      pageUnderstanding,
+      viewportHeight: normalizedViewport.height,
+      viewportWidth: normalizedViewport.width,
+    });
 
     await browserSession.page.waitForTimeout(Math.max(0, Number(postPlanTailMs) || 0));
 
-    xvfbWatcher.deactivate();
-
     // Flush the recording: video is written when the context closes.
     let webmPath = null;
     try {
@@ -573,15 +473,12 @@ export async function recordUrlNarration({
       events_path: resolvedEventsPath,
       events_log: eventsLog,
       duration_ms: lastTms > 0 ? lastTms : null,
-      display,
       sections: sectionOutputs,
     };
   } catch (error) {
     primaryError = error;
     throw error;
   } finally {
-    xvfbWatcher?.deactivate();
-
     if (browserSession) {
       try {
         await browserSession.browser.close();
@@ -590,18 +487,6 @@ export async function recordUrlNarration({
       }
     }
 
-    if (xvfb) {
-      try {
-        await stopXvfb(xvfb, { timeoutMs: xvfbStopTimeoutMs });
-      } catch (stopError) {
-        cleanupErrors.push(`xvfb_stop_failed:${stopError.message}`);
-      }
-    }
-
-    if (displayLease) {
-      displayLease.release();
-    }
-
     if (ownTempDir) {
       await rm(recVideoDir, { recursive: true, force: true }).catch(() => {});
     }