@lightcone-ai/daemon 0.20.0 → 0.22.0

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

@@ -272,16 +272,15 @@ server.tool(
 // tails, and re-records (Task #25/#26 trial).
 server.tool(
   'compose_video_v2',
-  'Compose a video from a list of segments using ffmpeg. Each segment has a visual source (image / scroll / '
-  + 'carousel / video / gif), optional audio, and optional subtitle text. Subtitles are burned in when '
-  + 'subtitle_text is provided AND burn_subtitles is not false. Segments are concatenated in order; outro clips are appended after.\n\n'
+  'Compose video(s) from a list of segments using ffmpeg. Each segment has a visual source (image / scroll / '
+  + 'carousel / video / gif), optional audio, and optional subtitle text. Segments are concatenated in order; '
+  + 'outro clips are appended after.\n\n'
   + 'When any segment has audio_path, MUST be preceded by plan_video_segments in the same session '
-  + '(plan_video_segments fills duration/subtitle_text/audio_path mechanically; manual alignment is rejected). '
-  + 'Returns a local mp4 path + size_bytes.\n\n'
-  + 'Dual / multi-version delivery (e.g. subtitled+voiced + clean silent): pass the variants[] array — one call '
-  + 'runs the heavy per-segment ffmpeg work ONCE and only diverges at audio mux + concat + subtitle burn per '
-  + 'variant. That is ~1.2-1.4× single-version time vs ~2× when calling this tool twice. Each variant chooses '
-  + 'its own burn_subtitles and include_audio independently.',
+  + '(plan_video_segments fills duration/subtitle_text/audio_path mechanically; manual alignment is rejected).\n\n'
+  + 'Outputs are controlled by variants[] — ALWAYS required. Single output is variants:[{output_path:"..."}]. '
+  + 'Multi-output (e.g. 字幕+配音 版 + 无声无字幕 clean 版) is variants:[{output_path:"sub.mp4"}, {output_path:"clean.mp4", burn_subtitles:false, include_audio:false}]. '
+  + 'The heavy per-segment ffmpeg work runs ONCE across all variants — only audio mux + concat + subtitle burn '
+  + 'repeat per variant. Two-variant delivery is ~1.2-1.4× single-variant time, not 2×.',
   {
     segments: z.array(z.object({
       visual_path: z.string().optional().describe('Absolute path to a single image / video / gif.'),
@@ -296,20 +295,15 @@ server.tool(
       subtitle_text: z.string().optional().describe('Narration text to burn as subtitle. Displayed for the full segment duration.'),
       transition: z.enum(['cut', 'fade', 'crossfade']).optional().describe('Transition to next segment. Default cut.'),
     })).describe('Ordered list of video segments.'),
-    outro_paths: z.array(z.string()).optional().describe('Absolute paths to outro video clips appended at end.'),
+    outro_paths: z.array(z.string()).optional().describe('Absolute paths to outro video clips appended at end (shared across all variants).'),
     resolution: z.string().optional().describe('Output resolution WxH. Default "1080x1920".'),
-    output_path: z.string().optional().describe('Absolute output path (single-output mode). Auto-generated if omitted. Ignored when variants[] is provided.'),
-    burn_subtitles: z.boolean().optional().describe('Single-output mode only: whether to burn subtitle_text. Default true. '
-      + 'For producing multiple variants in one call, use variants[] instead.'),
     variants: z.array(z.object({
       output_path: z.string().describe('Absolute output path for this variant. Each variant must use a unique path.'),
       burn_subtitles: z.boolean().optional().describe('Whether to burn subtitle_text into THIS variant. Default true.'),
       include_audio: z.boolean().optional().describe('Whether to mux segment.audio_path into THIS variant. Default true. '
-        + 'Pass false for a fully silent copy (skips audio mux entirely; segment.audio_path is ignored for this variant).'),
-    })).optional().describe('Multi-output mode: one call produces all variants. '
-      + 'Visual segment processing (the heavy work) runs once; each variant only repeats audio mux + concat + optional subtitle burn. '
-      + 'Typical use: [{output_path:"with-sub.mp4"}, {output_path:"clean.mp4", burn_subtitles:false, include_audio:false}] '
-      + 'to deliver a subtitled+voiced version and a silent clean version together.'),
+        + 'Pass false for a fully silent copy (segment.audio_path ignored for this variant).'),
+    })).min(1).describe('Required: one entry per output file. Single output = 1-element array. '
+      + 'Multi-output dual delivery example: [{output_path:"with-sub-voice.mp4"}, {output_path:"clean.mp4", burn_subtitles:false, include_audio:false}].'),
   },
   async (args) => {
     const segments = Array.isArray(args?.segments) ? args.segments : [];
@@ -348,28 +342,24 @@ server.tool(
 // audio in production runs (Tasks #20/#25/#26), forcing re-records.
 server.tool(
   'record_url_narration',
-  'Record a silent video of a URL by driving Chromium on an Xvfb display and capturing it with Playwright recordVideo, driven by a video plan; ffmpeg then transcodes the recording to mp4. Outputs a silent mp4 that can be passed to compose_video_v2 as a video-kind segment with an audio_path for narration.\n\nUse this as the canonical recording step for URL-narration videos. Falls back: if the page needs interactions outside the visual_action vocabulary (clicks, waits, OCR loops), use Monitor (Bash) with custom Playwright instead.\n\nMUST be preceded by plan_video_segments in the same session — feed plan_video_segments\'s `segments` array as `plan.sections` so dwell_ms aligns mechanically with TTS audio_duration_ms (hand-written dwell_ms has drifted and forced re-records in production).\n\nMULTI-SECTION OUTPUT (recommended for any URL with ≥2 sections): pass `output_paths` as an array with one path per plan.sections entry. The tool records the URL ONCE continuously (one browser session, one scrollTop, natural scroll flow through all sections), then slices the recording at section boundaries via ffmpeg. This avoids the per-segment scroll-back-to-top reset that happens when the agent splits N sections into N separate record_url_narration calls — that pattern reopens the browser and re-navigates for each segment, which looks visually disjointed even though the per-segment timing is correct.\n\nRuntime requirements: this tool only works on a Linux daemon machine with Xvfb + Chromium + ffmpeg installed (ffmpeg is used to transcode the recording to mp4; no x11grab device support needed). macOS / Windows daemons will fail at startup.',
+  'Record silent mp4s of a URL by driving Chromium on an Xvfb display and capturing it with Playwright recordVideo, then ffmpeg-transcoding. Each output mp4 can be passed to compose_video_v2 as a video-kind segment with an audio_path for narration.\n\nUse this as the canonical recording step for URL-narration videos. Falls back: if the page needs interactions outside the visual_action vocabulary (clicks, waits, OCR loops), use Monitor (Bash) with custom Playwright instead.\n\nMUST be preceded by plan_video_segments in the same session — feed plan_video_segments\'s `segments` array as `plan.sections` so dwell_ms aligns mechanically with TTS audio_duration_ms (hand-written dwell_ms has drifted and forced re-records in production).\n\nALWAYS pass output_paths as an array with one mp4 path per plan.sections entry (single-section recording is a 1-element array). The tool records the URL ONCE continuously (one browser session, one scrollTop, natural scroll flow through all sections), then slices the recording at section boundaries via ffmpeg. There is NO mode that records N sections in N separate calls — that pattern reopened the browser and re-scrolled-from-top for each segment, which looked visually disjointed. One URL = one call.\n\nRuntime requirements: this tool only works on a Linux daemon machine with Xvfb + Chromium + ffmpeg installed (ffmpeg is used to transcode the recording to mp4; no x11grab device support needed). macOS / Windows daemons will fail at startup.',
   {
     url: z.string().describe('Page URL to record'),
     plan: z.record(z.any()).describe(
-      'A video plan: an object with `phases` (or `sections`), each a "visual beat" with '
-      + '`action` (scroll_to_dwell / linear_scroll_during / scroll_back / hold / ...), a '
-      + 'target (`target_y` or `focus_region:[y1,y2]`) for scroll-type actions, and '
-      + '`dwell_ms` (how long to hold that beat — should match the segment\'s TTS duration).\n\n'
-      + 'Standard chain: pass plan_video_segments\'s `segments` array directly as `plan.sections` — '
-      + 'each segment\'s `dwell_ms` is already set to its `audio_duration_ms`.\n\n'
-      + 'For RECRUITMENT URLs (mp.weixin.qq.com / 校招 / 实习 / 岗位 content), each section MUST '
-      + 'also declare `target_y_content_label` — a short Chinese label describing what content '
-      + 'sits at that pixel y position on the page (e.g. "标题区" / "岗位信息卡片" / "公司介绍" / '
-      + '"届别说明"). Labels matching forbidden regions ("二维码" / "扫码" / "投递入口" / "投递方式" / '
-      + '"联系方式" / "微信号" / "QR" / "阅读原文" / "外链") will cause the tool to refuse the '
-      + 'recording — recruitment content must NOT dwell on these areas (see fragments.md '
-      + 'frag.short.recruitment_url_mode_policy). Pick a different target_y in the 标题/岗位 '
-      + 'information area and rewrite that section.'
+      'A video plan: an object with `phases` (or `sections`), each a "visual beat".\n\n'
+      + 'ACTION VOCABULARY = atoms + macros. Pick by content type:\n'
+      + '  - scroll_to_dwell (default for most sections): fast transition + dwell with subtle micro-motion at target_y. Use for titles, content cards, single focal areas.\n'
+      + '  - narrated_pan: continuous linear scroll over the full section duration. Use ONLY when the speech actually narrates a long visible list (e.g. reading every job title in order). Was called linear_scroll_during; that name still works as an alias.\n'
+      + '  - focal_arc: NO scroll; cursor moves between N visual focal points. Use for SHORT pages where consecutive sections share basically the same target_y (within ~150px) — scrolling would be invisible, the cursor carries the rhythm. Requires `points: [{x,y}, ...]` instead of target_y.\n'
+      + '  - hold: pure pause, no motion. Rare.\n\n'
+      + 'ATOMS (for power use via phase.beats[]): scroll_to / hold / micro_oscillate / cursor_focus. Any custom sequence the macros do not cover can be written as a beats array.\n\n'
+      + 'Each section needs: action (or beats[]), target (`target_y` / `focus_region:[y1,y2]` / `points`), and `dwell_ms` (= section total duration; for narrated content this should match the segment\'s TTS audio_duration_ms).\n\n'
+      + 'Standard chain: pass plan_video_segments\'s `segments` array directly as `plan.sections` — each segment\'s `dwell_ms` is already its `audio_duration_ms`.\n\n'
+      + 'For RECRUITMENT URLs (mp.weixin.qq.com / 校招 / 实习 / 岗位 content), each section MUST also declare `target_y_content_label` — a short Chinese label describing what content sits at that pixel y position on the page (e.g. "标题区" / "岗位信息卡片" / "公司介绍" / "届别说明"). Labels matching forbidden regions ("二维码" / "扫码" / "投递入口" / "投递方式" / "联系方式" / "微信号" / "QR" / "阅读原文" / "外链") will cause the tool to refuse the recording — recruitment content must NOT dwell on these areas (see fragments.md frag.short.recruitment_url_mode_policy). Pick a different target_y in the 标题/岗位 information area and rewrite that section.'
     ),
-    output_path: z.string().optional().describe('Workspace-relative output mp4 path for the CONSOLIDATED master recording. Default tmp/wx3_video/recorded-{ts}.mp4. When output_paths is also provided, this still receives the full continuous recording for verification/debugging.'),
-    output_paths: z.array(z.string()).optional().describe('Multi-section output mode. Pass an array of N workspace-relative paths matching plan.sections length. The tool records ONCE continuously then slices the result into N mp4s at section boundaries (derived from phase_start / phase_end events). RECOMMENDED whenever a URL has ≥2 sections — keeps visual flow natural between sections instead of reopening the browser per segment.'),
-    events_path: z.string().optional().describe('Workspace-relative events.json path. Default ${output_path}.events.json'),
+    output_paths: z.array(z.string()).min(1).describe('REQUIRED. Workspace-relative mp4 paths, one per plan.sections entry (single-section is a 1-element array). The tool records ONCE continuously and slices the result at section boundaries (derived from phase_start / phase_end events) — each section produces exactly one of these mp4s.'),
+    output_path: z.string().optional().describe('Optional debug-only path for the CONSOLIDATED master recording (the full continuous webm transcoded). Auto-generated under tmp/ if omitted. Agents normally do not need to set this — they consume output_paths.'),
+    events_path: z.string().optional().describe('Workspace-relative events.json path. Default ${master}.events.json'),
     viewport: z.object({
       width: z.number().optional(),
       height: z.number().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightcone-ai/daemon",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "type": "module",
   "main": "src/index.js",
   "bin": {

package/src/_vendor/video/composer-v2/index.js

@@ -249,54 +249,41 @@ async function applyFadeTransition({ clipA, clipB, tmpDir, style = 'fade' }) {
   return outPath;
 }
 
-// compose_video_v2 supports two modes:
+// compose_video_v2 — ONE shape: caller passes variants[]. Single-output is
+// just variants of length 1. Multi-output (subtitled+voiced + clean silent)
+// is the same call with more variants. There is no top-level output_path or
+// burn_subtitles shortcut — it added a second pattern, and agents
+// consistently defaulted to the simpler one even when multi-output was
+// requested, so the dual-version optimization went unused.
 //
-//   1. Legacy single-output: pass output_path (+ optional burn_subtitles).
-//      Returns { path, duration_ms, size_bytes, variants: [..1 entry..] }.
-//
-//   2. Multi-variant: pass variants=[{output_path, burn_subtitles?, include_audio?}, ...].
-//      Visual segment processing runs ONCE (the heavy part — per-segment ffmpeg
-//      transcode/scale/scroll). Each variant then diverges only at audio mux +
-//      concat + subtitle burn — typically a few seconds per extra variant.
-//      Returns { variants: [{path, duration_ms, size_bytes, burn_subtitles,
-//      include_audio}, ...] }.
-//
-// Use the multi-variant mode when shipping the same content with different
-// subtitle/audio combinations (e.g. subtitled+voiced + clean silent). Calling
-// the legacy mode twice produces correct outputs but redoes per-segment work.
+// Visual segment processing runs ONCE; each variant diverges only at audio
+// mux + concat + subtitle burn (~seconds per extra variant).
 export async function composeVideoV2({
   segments = [],
   outro_paths = [],
   resolution = '1080x1920',
-  output_path,
-  burn_subtitles = true,
   variants,
 }) {
   if (!Array.isArray(segments) || segments.length === 0) {
     throw new Error('segments must be a non-empty array');
   }
 
-  // Normalize variants. If caller did not pass an explicit variants array,
-  // synthesize a single variant from the legacy output_path + burn_subtitles.
-  // include_audio defaults to true (auto-include any segment.audio_path).
-  const normalizedVariants = (Array.isArray(variants) && variants.length > 0)
-    ? variants.map((v, idx) => {
-        if (!v || typeof v !== 'object') {
-          throw new Error(`variants[${idx}]: must be an object`);
-        }
-        const outPath = String(v.output_path ?? '').trim();
-        if (!outPath) throw new Error(`variants[${idx}]: output_path is required`);
-        return {
-          output_path: outPath,
-          burn_subtitles: v.burn_subtitles !== false,
-          include_audio: v.include_audio !== false,
-        };
-      })
-    : [{
-        output_path: output_path ?? path.join(os.tmpdir(), `lightcone-video-${Date.now()}.mp4`),
-        burn_subtitles: burn_subtitles !== false,
-        include_audio: true,
-      }];
+  if (!Array.isArray(variants) || variants.length === 0) {
+    throw new Error('variants must be a non-empty array. Single output is variants:[{output_path:"..."}].');
+  }
+
+  const normalizedVariants = variants.map((v, idx) => {
+    if (!v || typeof v !== 'object') {
+      throw new Error(`variants[${idx}]: must be an object`);
+    }
+    const outPath = String(v.output_path ?? '').trim();
+    if (!outPath) throw new Error(`variants[${idx}]: output_path is required`);
+    return {
+      output_path: outPath,
+      burn_subtitles: v.burn_subtitles !== false,
+      include_audio: v.include_audio !== false,
+    };
+  });
 
   // Disallow two variants writing to the same file — would race on disk.
   const seenOutputs = new Set();
@@ -485,15 +472,8 @@ export async function composeVideoV2({
       });
     }
 
-    // Legacy single-output callers (didn't pass variants) get the same flat
-    // shape they used to get, plus the variants array for forward-compat.
-    const first = variantOutputs[0];
-    return {
-      path: first.path,
-      duration_ms: first.duration_ms,
-      size_bytes: first.size_bytes,
-      variants: variantOutputs,
-    };
+    // Always return variants[]. Single-output callers read variants[0].
+    return { variants: variantOutputs };
   } finally {
     await rm(tmpDir, { recursive: true, force: true });
   }

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

@@ -367,21 +367,26 @@ export async function recordUrlNarration({
   const normalizedViewport = normalizeViewport(viewport);
   const normalizedFps = normalizeInteger(fps, DEFAULT_FPS);
   const resolvedOutputPaths = normalizeOutputPaths(outputPaths);
-  // When multi-section output is requested, the count must match plan.sections
-  // 1:1 — otherwise the agent will end up with audio/visual misalignment when
-  // it feeds these into plan_video_segments. Fail loud rather than silently
-  // truncating or padding.
-  if (resolvedOutputPaths && resolvedOutputPaths.length !== phases.length) {
+  // output_paths is REQUIRED. Single-section recordings just pass an array
+  // of one. Removing the optional path forces 1:1 alignment with plan.sections
+  // and eliminates the "default to single output_path master" pattern that
+  // led agents to call this tool once per section instead of once per URL.
+  if (!resolvedOutputPaths) {
+    const error = new Error(
+      'output_paths is required — one entry per plan.sections (single section is a 1-element array).',
+    );
+    error.code = 'OUTPUT_PATHS_REQUIRED';
+    throw error;
+  }
+  if (resolvedOutputPaths.length !== phases.length) {
     const error = new Error(
       `output_paths_count_mismatch:expected=${phases.length}:got=${resolvedOutputPaths.length}`,
     );
     error.code = 'OUTPUT_PATHS_COUNT_MISMATCH';
     throw error;
   }
-  if (resolvedOutputPaths) {
-    for (const p of resolvedOutputPaths) {
-      mkdirSync(path.dirname(p), { recursive: true });
-    }
+  for (const p of resolvedOutputPaths) {
+    mkdirSync(path.dirname(p), { recursive: true });
   }
 
   mkdirSync(path.dirname(resolvedOutputPath), { recursive: true });
@@ -501,43 +506,40 @@ export async function recordUrlNarration({
       ? eventsLog.reduce((max, ev) => Math.max(max, Number(ev?.t_ms) || 0), 0)
       : 0;
 
-    // Multi-section output: slice the consolidated mp4 at section boundaries
-    // (derived from phase_start / phase_end events). All slices come from the
-    // SAME continuous recording, so the visual flow between sections stays
+    // Slice the consolidated mp4 at section boundaries (derived from
+    // phase_start / phase_end events). All slices come from the SAME
+    // continuous recording, so the visual flow between sections stays
     // natural — no browser reload, no scroll-back-to-top per segment.
-    let sectionOutputs = null;
-    if (resolvedOutputPaths) {
-      const cutPoints = deriveSectionCutPoints(eventsLog, phases.length);
-      sectionOutputs = [];
-      for (let i = 0; i < cutPoints.length; i += 1) {
-        const cut = cutPoints[i];
-        const outPath = resolvedOutputPaths[i];
-        await cutFn({
-          inputPath: resolvedOutputPath,
-          outputPath: outPath,
-          startMs: cut.start_ms,
-          durationMs: cut.duration_ms,
-          fps: normalizedFps,
-        });
-        const sliceStat = await stat(outPath);
-        if (!sliceStat.isFile() || sliceStat.size <= 0) {
-          const error = new Error(`section_slice_empty:${outPath}`);
-          error.code = 'SECTION_SLICE_EMPTY';
-          throw error;
-        }
-        sectionOutputs.push({
-          phase_id: cut.phase_id,
-          video_path: outPath,
-          start_ms: cut.start_ms,
-          end_ms: cut.end_ms,
-          duration_ms: cut.duration_ms,
-          size_bytes: Number(sliceStat.size ?? 0),
-        });
+    const cutPoints = deriveSectionCutPoints(eventsLog, phases.length);
+    const sectionOutputs = [];
+    for (let i = 0; i < cutPoints.length; i += 1) {
+      const cut = cutPoints[i];
+      const outPath = resolvedOutputPaths[i];
+      await cutFn({
+        inputPath: resolvedOutputPath,
+        outputPath: outPath,
+        startMs: cut.start_ms,
+        durationMs: cut.duration_ms,
+        fps: normalizedFps,
+      });
+      const sliceStat = await stat(outPath);
+      if (!sliceStat.isFile() || sliceStat.size <= 0) {
+        const error = new Error(`section_slice_empty:${outPath}`);
+        error.code = 'SECTION_SLICE_EMPTY';
+        throw error;
       }
+      sectionOutputs.push({
+        phase_id: cut.phase_id,
+        video_path: outPath,
+        start_ms: cut.start_ms,
+        end_ms: cut.end_ms,
+        duration_ms: cut.duration_ms,
+        size_bytes: Number(sliceStat.size ?? 0),
+      });
     }
 
     return {
-      video_path: resolvedOutputPath,
+      master_video_path: resolvedOutputPath,
       events_path: resolvedEventsPath,
       events_log: eventsLog,
       duration_ms: lastTms > 0 ? lastTms : null,

package/src/_vendor/video/recorder/plan-executor.js

@@ -1,5 +1,7 @@
 import { resolveDurationMs } from './phase-duration.js';
-import { humanizedScroll } from '../humanized-scroll.js';
+import { ATOMS, ATOM_NAMES } from './atoms.js';
+import { MACROS, resolveMacroName } from './macros.js';
+import { getCdpSession } from '../cdp-touch.js';
 
 function normalizeText(value) {
   if (typeof value !== 'string') return '';
@@ -22,16 +24,31 @@ function normalizeRange(value) {
   return [low, high];
 }
 
-// The recorder executes exactly these visual actions. There is no "scroll a bit"
-// blind-scroll action: every scroll phase must say where it lands.
+// Canonical action vocabulary = atoms + macros. Macros are the day-to-day
+// names plans should use; atoms are exposed for sequencing via phase.beats[]
+// when a macro doesn't fit. The legacy V2 names (smooth_scroll, fast_scroll,
+// linear_scroll_during, scroll_back) are still accepted via ACTION_ALIASES
+// in macros.js so existing plans keep running, but new plans should pick
+// from the canonical list.
+//
+// "hold" is its own canonical action (not a macro) because it's the leaf
+// case — pure pause — and the agent shouldn't have to know whether it's
+// implemented as macro or atom.
 export const SUPPORTED_PHASE_ACTIONS = Object.freeze([
+  // macros (recommended for most sections)
+  'scroll_to_dwell',     // fast transition + dwell with micro-motion (default)
+  'narrated_pan',        // continuous linear scroll (long lists)
+  'focal_arc',           // cursor across N focal points (short pages)
+  // atoms (for power use — usually inside phase.beats[])
+  'scroll_to',
   'hold',
+  'micro_oscillate',
+  'cursor_focus',
+  // legacy V2 names — kept for backward compat
   'smooth_scroll',
   'fast_scroll',
   'linear_scroll_during',
-  'scroll_to_dwell',
   'scroll_back',
-  'cursor_focus',
 ]);
 
 // Common spellings authors reach for, mapped onto the canonical action above.
@@ -229,205 +246,173 @@ function resolveFromY(phase, fallback = null) {
   return Math.round(parsed);
 }
 
-// Delegates to humanizedScroll, which dispatches real CDP touch events so
-// the browser's gesture engine produces native scroll physics (rubber-band,
-// fling inertia, compositor-paced repaints). The old implementation drove
-// `root.scrollTo(...)` in a setTimeout loop inside page.evaluate — visually
-// smooth in isolation, but bypassed the gesture pipeline entirely, which is
-// what made scrolls feel "robotic" on recordings (see the
-// `not natural` thread in docs/scenario-content-creation discussion).
-//
-// `minSteps` is no longer needed (humanizedScroll computes segments from
-// distance + duration). `jitterPx` is forwarded as `pixel_jitter_px`, which
-// humanizedScroll converts into per-touchMove vertical offset.
-async function animateScroll(page, {
-  startY = null,
-  targetY,
-  durationMs,
-  easing = 'easeInOutQuad',
-  jitterPx = 0,
-  // minSteps is accepted but unused — kept in the signature so callers don't
-  // need updating in this refactor.
-  minSteps: _minSteps,  // eslint-disable-line no-unused-vars
-} = {}) {
-  if (!Number.isFinite(Number(targetY))) {
-    const error = new Error('phase_target_y_required');
-    error.code = 'PHASE_TARGET_Y_REQUIRED';
-    throw error;
+// ── beat dispatch ─────────────────────────────────────────────────────────
+// A "beat" is one entry in the atom sequence run during a phase. Either:
+//   { atom: 'scroll_to', params: {...} }   — leaf, dispatched directly
+//   { macro: 'scroll_to_dwell', params }   — expanded to atoms then run
+// plan-executor stays thin: turn phase into beats, then run beats.
+
+// Build the atom-sequence for a phase. Two modes:
+//   1. phase.beats[] given — used as-is (agent composing arbitrary sequences).
+//   2. phase.action given — resolved to macro (incl. legacy aliases) or
+//      single atom, phase params get passed through.
+function phaseToBeats(phase, { fallbackFromY = 0 } = {}) {
+  if (Array.isArray(phase?.beats) && phase.beats.length > 0) {
+    return { beats: phase.beats, anchorY: null };
   }
 
-  const resolvedFromY = Number.isFinite(Number(startY))
-    ? Number(startY)
-    : await page.evaluate(() => {
-        const root = document.scrollingElement || document.documentElement;
-        return Math.round(root.scrollTop);
-      });
+  const action = resolvePhaseAction(phase);
 
-  await humanizedScroll(page, {
-    from_y: resolvedFromY,
-    to_y: Number(targetY),
-    duration_ms: Math.max(0, Number(durationMs) || 0),
-    motion_curve: easing,
-    pixel_jitter_px: Math.max(0, Number(jitterPx) || 0),
-  });
-}
+  if (ATOM_NAMES.includes(action)) {
+    const params = paramsForAtom(action, phase, fallbackFromY);
+    const beat = { atom: action, params };
+    const anchorY = action === 'scroll_to' && Number.isFinite(Number(params.target_y))
+      ? Number(params.target_y)
+      : null;
+    return { beats: [beat], anchorY };
+  }
 
-async function executeHold(page, phase) {
-  const holdMs = resolveDurationMs(phase, 0);
-  if (holdMs > 0) {
-    await page.waitForTimeout(holdMs);
+  const macroName = resolveMacroName(action);
+  if (macroName) {
+    const macroFn = MACROS[macroName];
+    const params = paramsForMacro(macroName, phase, fallbackFromY);
+    const expanded = macroFn(params, { fromY: fallbackFromY });
+    return { beats: expanded.beats, anchorY: expanded.anchorY };
   }
-  return { anchorY: null };
-}
 
-async function executeSmoothScroll(page, phase) {
-  const targetY = requireTargetY(phase, 'smooth_scroll');
-  const transitionMs = resolveTransitionMs(phase, 900);
-  await animateScroll(page, {
-    targetY,
-    durationMs: transitionMs,
-    easing: 'easeInOutQuad',
-    jitterPx: 2,
-    minSteps: 18,
-  });
-  return { anchorY: targetY };
-}
+  if (action === 'hold') {
+    return {
+      beats: [{ atom: 'hold', params: { duration_ms: resolveDurationMs(phase, 0) } }],
+      anchorY: null,
+    };
+  }
 
-async function executeFastScroll(page, phase) {
-  const targetY = requireTargetY(phase, 'fast_scroll');
-  const transitionMs = resolveTransitionMs(phase, 420);
-  await animateScroll(page, {
-    targetY,
-    durationMs: transitionMs,
-    easing: 'easeOutQuad',
-    jitterPx: 3,
-    minSteps: 10,
-  });
-  return { anchorY: targetY };
+  const error = new Error(
+    `phase_action_unsupported:${action || 'empty'} — supported actions: ${SUPPORTED_PHASE_ACTIONS.join(', ')}`
+    + ' (there is no blind scroll_down/scroll_up; pick a macro or write phase.beats[] from atoms)',
+  );
+  error.code = 'PHASE_ACTION_UNSUPPORTED';
+  throw error;
 }
 
-async function executeLinearScrollDuring(page, phase, { fallbackFromY = null } = {}) {
-  const fromY = resolveFromY(phase, fallbackFromY);
-  const toY = requireTargetY(phase, 'linear_scroll_during');
+// Phase fields → atom params. Atom-specific shape; missing fields fall back
+// to the same derivations the old executors did (resolveDurationMs, etc).
+function paramsForAtom(atomName, phase, fallbackFromY) {
   const durationMs = resolveDurationMs(phase, null);
-  if (!Number.isFinite(Number(durationMs)) || Number(durationMs) <= 0) {
-    const error = new Error('linear_scroll_duration_required');
-    error.code = 'LINEAR_SCROLL_DURATION_REQUIRED';
-    throw error;
+  if (atomName === 'scroll_to') {
+    return {
+      target_y: requireTargetY(phase, 'scroll_to'),
+      duration_ms: durationMs ?? resolveTransitionMs(phase, 600),
+      curve: phase.curve || phase.motion_curve || 'easeInOutQuad',
+      jitter_px: Number.isFinite(Number(phase.jitter_px)) ? Number(phase.jitter_px) : 2,
+      from_y: resolveFromY(phase, fallbackFromY),
+    };
   }
-
-  await animateScroll(page, {
-    startY: fromY,
-    targetY: toY,
-    durationMs,
-    easing: 'linear',
-    jitterPx: 0,
-    minSteps: 12,
-  });
-
-  const dwellMs = normalizeInteger(phase?.dwell_ms, null);
-  if (Number.isFinite(dwellMs) && dwellMs > durationMs) {
-    await page.waitForTimeout(dwellMs - durationMs);
+  if (atomName === 'hold') {
+    return { duration_ms: durationMs ?? 0 };
   }
-  return { anchorY: toY };
-}
-
-async function executeScrollToDwell(page, phase) {
-  const targetY = requireTargetY(phase, 'scroll_to_dwell');
-  const transitionMs = resolveTransitionMs(phase, 820);
-  await animateScroll(page, {
-    targetY,
-    durationMs: transitionMs,
-    easing: 'easeInOutQuad',
-    jitterPx: 2,
-    minSteps: 16,
-  });
-  const dwellMs = normalizeInteger(phase?.dwell_ms, null);
-  if (Number.isFinite(dwellMs) && dwellMs > 0) {
-    await page.waitForTimeout(dwellMs);
-  } else {
-    const holdMs = resolveDurationMs(phase, 0);
-    if (holdMs > 0) {
-      await page.waitForTimeout(holdMs);
-    }
+  if (atomName === 'micro_oscillate') {
+    return {
+      amplitude_px: Number(phase.amplitude_px) || 30,
+      duration_ms: durationMs ?? 0,
+      period_ms: Number(phase.period_ms) || 1400,
+    };
   }
-  return { anchorY: targetY };
+  if (atomName === 'cursor_focus') {
+    return {
+      x: Number(phase.x ?? phase.cursor_x),
+      y: Number(phase.y ?? phase.cursor_y),
+      duration_ms: durationMs ?? 0,
+    };
+  }
+  return { ...phase };
 }
 
-async function executeScrollBack(page, phase, { fallbackTargetY = 0 } = {}) {
-  const targetY = resolveTargetY(phase, fallbackTargetY);
-  const transitionMs = resolveTransitionMs(phase, 900);
-  await animateScroll(page, {
-    targetY,
-    durationMs: transitionMs,
-    easing: 'easeOutQuad',
-    jitterPx: 1,
-    minSteps: 14,
-  });
-  const dwellMs = normalizeInteger(phase?.dwell_ms, null);
-  if (Number.isFinite(dwellMs) && dwellMs > 0) {
-    await page.waitForTimeout(dwellMs);
+// Phase fields → macro params. Macros validate their own inputs.
+function paramsForMacro(macroName, phase, fallbackFromY) {
+  const durationMs = resolveDurationMs(phase, null);
+  const targetY = resolveTargetY(phase, null);
+  const fromY = resolveFromY(phase, fallbackFromY);
+  const base = {
+    target_y: targetY,
+    duration_ms: durationMs,
+    from_y: fromY,
+    transition_ms: Number.isFinite(Number(phase.transition_ms)) ? Number(phase.transition_ms) : undefined,
+    transition_ratio: Number.isFinite(Number(phase.transition_ratio)) ? Number(phase.transition_ratio) : undefined,
+    transition_curve: phase.transition_curve,
+    amplitude_px: phase.amplitude_px,
+    oscillate_period_ms: phase.oscillate_period_ms,
+  };
+  if (macroName === 'focal_arc') {
+    return { ...base, points: Array.isArray(phase.points) ? phase.points : [] };
   }
-  return { anchorY: targetY };
+  if (macroName === 'scroll_to_dwell') {
+    // The legacy fast_scroll alias maps to scroll_to_dwell, but with a
+    // shorter default transition_ratio so the snap feels closer to the
+    // original fast_scroll behavior.
+    const isFastScrollAlias = String(phase.action || '').toLowerCase() === 'fast_scroll';
+    if (isFastScrollAlias && base.transition_ratio === undefined) {
+      base.transition_ratio = 0.1;
+    }
+  }
+  return base;
 }
 
-async function executeCursorFocus(page, phase) {
-  const targetY = requireTargetY(phase, 'cursor_focus');
-  const transitionMs = resolveTransitionMs(phase, 650);
-  await animateScroll(page, {
-    targetY,
-    durationMs: transitionMs,
-    easing: 'easeInOutQuad',
-    jitterPx: 1,
-    minSteps: 12,
-  });
-  const dwellMs = normalizeInteger(phase?.dwell_ms, null);
-  if (Number.isFinite(dwellMs) && dwellMs > 0) {
-    await page.waitForTimeout(dwellMs);
-  } else {
-    const holdMs = resolveDurationMs(phase, 360);
-    if (holdMs > 0) {
-      await page.waitForTimeout(holdMs);
+// Run an atom-sequence in order. Each beat is either:
+//   - an atom (run directly through ATOMS[name])
+//   - a macro reference (expand to atoms inline; one level of nesting only —
+//     macros calling macros breaks the "shortcut for common atom combo"
+//     mental model).
+async function executeBeats(page, ctx, beats, { fallbackFromY = 0 } = {}) {
+  let anchorY = fallbackFromY;
+  for (const beat of beats) {
+    if (!beat || typeof beat !== 'object') continue;
+    if (beat.macro) {
+      const macroFn = MACROS[beat.macro] || MACROS[resolveMacroName(beat.macro)];
+      if (!macroFn) {
+        const error = new Error(`beat_macro_unsupported:${beat.macro}`);
+        error.code = 'BEAT_MACRO_UNSUPPORTED';
+        throw error;
+      }
+      const expanded = macroFn(beat.params ?? {}, { fromY: anchorY });
+      const sub = await executeBeats(page, ctx, expanded.beats, { fallbackFromY: anchorY });
+      if (sub?.anchorY != null) anchorY = sub.anchorY;
+      else if (expanded.anchorY != null) anchorY = expanded.anchorY;
+      continue;
+    }
+    const atomName = beat.atom;
+    const atomFn = ATOMS[atomName];
+    if (!atomFn) {
+      const error = new Error(`beat_atom_unsupported:${atomName || 'missing'}`);
+      error.code = 'BEAT_ATOM_UNSUPPORTED';
+      throw error;
     }
+    const params = { ...(beat.params ?? {}) };
+    // Pre-fill scroll_to's from_y from the running anchor so sequences can
+    // chain naturally without the agent recomputing positions.
+    if (atomName === 'scroll_to' && params.from_y == null) params.from_y = anchorY;
+    const result = await atomFn(page, ctx, params);
+    if (result?.anchorY != null) anchorY = result.anchorY;
   }
-  return { anchorY: targetY };
+  return { anchorY };
 }
 
 async function executePhase(page, phase, {
   lastAnchorY = null,
   initialAnchorY = 0,
 } = {}) {
-  const action = resolvePhaseAction(phase);
   const fallbackFromY = lastAnchorY ?? initialAnchorY;
+  const { beats, anchorY: macroAnchor } = phaseToBeats(phase, { fallbackFromY });
 
-  if (action === 'hold') {
-    return executeHold(page, phase);
-  }
-  if (action === 'smooth_scroll') {
-    return executeSmoothScroll(page, phase);
-  }
-  if (action === 'fast_scroll') {
-    return executeFastScroll(page, phase);
-  }
-  if (action === 'linear_scroll_during') {
-    return executeLinearScrollDuring(page, phase, { fallbackFromY });
-  }
-  if (action === 'scroll_to_dwell') {
-    return executeScrollToDwell(page, phase);
-  }
-  if (action === 'scroll_back') {
-    return executeScrollBack(page, phase, { fallbackTargetY: 0 });
-  }
-  if (action === 'cursor_focus') {
-    return executeCursorFocus(page, phase);
-  }
+  // One CDP session per phase, threaded to atoms via ctx (cached on page by
+  // cdp-touch.js so this is cheap on repeat calls). Tests pass a mock page
+  // that throws here; we swallow and let atoms that need CDP fail on demand.
+  let cdp = null;
+  try { cdp = await getCdpSession(page); } catch { /* mock pages may not expose context() */ }
+  const ctx = { cdp, fromY: fallbackFromY };
 
-  const error = new Error(
-    `phase_action_unsupported:${action || 'empty'} — supported actions: ${SUPPORTED_PHASE_ACTIONS.join(', ')}`
-    + ' (there is no blind scroll_down/scroll_up; use scroll_to_dwell with target_y or focus_region)',
-  );
-  error.code = 'PHASE_ACTION_UNSUPPORTED';
-  throw error;
+  const { anchorY } = await executeBeats(page, ctx, beats, { fallbackFromY });
+  return { anchorY: anchorY ?? macroAnchor ?? null };
 }
 
 function createEvent({ tMs, action, phaseId, phaseAction, detail = {} }) {

package/src/tools/compose-video-v2.js

@@ -27,14 +27,31 @@ export async function runComposeVideoV2Tool({
   outro_paths,
   format,
   resolution,
+  variants,
+  // Trapping legacy params: agents that still pass these from older prompts
+  // need an explicit error so they migrate, not silent fallback.
   output_path,
   burn_subtitles,
-  variants,
   workspaceDir,
 }) {
+  if (output_path != null || burn_subtitles != null) {
+    return toolError(
+      'compose_video_v2: output_path and burn_subtitles are no longer accepted at the top level. '
+      + 'Pass variants:[{output_path, burn_subtitles?, include_audio?}] — single output is a '
+      + '1-element array. See frag.short.video_synthesis_tools.',
+    );
+  }
+
   if (!Array.isArray(segments) || segments.length === 0) {
     return toolError('segments must be a non-empty array.');
   }
+  if (!Array.isArray(variants) || variants.length === 0) {
+    return toolError(
+      'compose_video_v2: variants[] is required. Single output is variants:[{output_path:"..."}]. '
+      + 'Multi-output dual delivery (字幕版 + 无字幕版) is variants:[{output_path:"sub.mp4"}, '
+      + '{output_path:"clean.mp4", burn_subtitles:false, include_audio:false}].',
+    );
+  }
 
   const imagePaths = [];
   for (let i = 0; i < segments.length; i++) {
@@ -69,34 +86,24 @@ export async function runComposeVideoV2Tool({
     }
   }
 
-  // Normalize variants. If caller passed a variants[] array, that takes
-  // priority — multi-output mode. Otherwise build a single-element variants
-  // array from the legacy output_path + burn_subtitles params.
+  // Normalize variants. Each entry needs an output_path; flags default to
+  // burn_subtitles=true, include_audio=true.
   const outDir = workspaceDir
     ? path.join(workspaceDir, 'artifacts', 'video')
     : path.join(os.tmpdir(), 'lightcone-video');
 
-  let normalizedVariants;
-  if (Array.isArray(variants) && variants.length > 0) {
-    normalizedVariants = variants.map((v, idx) => {
-      if (!v || typeof v !== 'object') {
-        return null; // surfaced below
-      }
-      const outPath = String(v.output_path ?? '').trim()
-        || path.join(outDir, `composed-${Date.now()}-${idx}-${randomUUID().slice(0, 8)}.mp4`);
-      return {
-        output_path: outPath,
-        burn_subtitles: v.burn_subtitles !== false,
-        include_audio: v.include_audio !== false,
-      };
-    });
-    if (normalizedVariants.some(v => v === null)) {
-      return toolError('variants must be an array of objects, each with { output_path, burn_subtitles?, include_audio? }.');
-    }
-  } else {
-    const burnSubtitles = burn_subtitles !== false;
-    const outPath = output_path ?? path.join(outDir, `composed-${Date.now()}-${randomUUID().slice(0, 8)}.mp4`);
-    normalizedVariants = [{ output_path: outPath, burn_subtitles: burnSubtitles, include_audio: true }];
+  const normalizedVariants = variants.map((v, idx) => {
+    if (!v || typeof v !== 'object') return null;
+    const outPath = String(v.output_path ?? '').trim()
+      || path.join(outDir, `composed-${Date.now()}-${idx}-${randomUUID().slice(0, 8)}.mp4`);
+    return {
+      output_path: outPath,
+      burn_subtitles: v.burn_subtitles !== false,
+      include_audio: v.include_audio !== false,
+    };
+  });
+  if (normalizedVariants.some(v => v === null)) {
+    return toolError('variants must be an array of objects, each with { output_path, burn_subtitles?, include_audio? }.');
   }
 
   const warnings = [];
@@ -135,31 +142,16 @@ export async function runComposeVideoV2Tool({
       variants: normalizedVariants,
     });
 
-    const outputs = Array.isArray(result?.variants) && result.variants.length > 0
-      ? result.variants
-      : [{ path: result.path, duration_ms: result.duration_ms, size_bytes: result.size_bytes,
-           burn_subtitles: normalizedVariants[0].burn_subtitles,
-           include_audio: normalizedVariants[0].include_audio }];
-
-    const lines = ['compose_video_v2 completed.'];
-    if (outputs.length === 1) {
-      const v = outputs[0];
+    const outputs = Array.isArray(result?.variants) ? result.variants : [];
+    const lines = ['compose_video_v2 completed.', `variants=${outputs.length}`];
+    outputs.forEach((v, idx) => {
+      lines.push(`--- variant ${idx} ---`);
       lines.push(`path=${v.path}`);
       lines.push(`duration_ms=${v.duration_ms}`);
       lines.push(`size_bytes=${v.size_bytes ?? 'unknown'}`);
       lines.push(`burn_subtitles=${v.burn_subtitles}`);
       lines.push(`include_audio=${v.include_audio}`);
-    } else {
-      lines.push(`variants=${outputs.length}`);
-      outputs.forEach((v, idx) => {
-        lines.push(`--- variant ${idx} ---`);
-        lines.push(`path=${v.path}`);
-        lines.push(`duration_ms=${v.duration_ms}`);
-        lines.push(`size_bytes=${v.size_bytes ?? 'unknown'}`);
-        lines.push(`burn_subtitles=${v.burn_subtitles}`);
-        lines.push(`include_audio=${v.include_audio}`);
-      });
-    }
+    });
     lines.push(`segments=${segments.length}`);
     lines.push(`outro_clips=${(outro_paths ?? []).length}`);
     for (const w of warnings) lines.push(w);

package/src/tools/record-url-narration.js

@@ -257,40 +257,49 @@ export async function runRecordUrlNarrationTool({
   }
 
   try {
-    const { resolvedOutputPath, resolvedEventsPath } = resolveRecordUrlNarrationPaths({
-      workspaceDir,
-      outputPath: validatedInput.output_path,
-      eventsPath: validatedInput.events_path,
-      nowMs,
-    });
-
-    mkdirSync(path.dirname(resolvedOutputPath), { recursive: true });
-    mkdirSync(path.dirname(resolvedEventsPath), { recursive: true });
-
-    // Multi-section mode: caller passed output_paths. Validate it 1:1 with
-    // plan.sections so the recorder can slice the continuous recording into
-    // per-section mp4s without ambiguity.
-    let resolvedOutputPaths = null;
+    // output_paths is REQUIRED. The legacy "default output_path master file"
+    // mode is gone — agents kept defaulting to one-call-per-section because
+    // that was the lowest-friction path. Now every recording is sliced, even
+    // single-section ones (which are just a 1-element output_paths array).
+    let resolvedOutputPaths;
     try {
       resolvedOutputPaths = resolveOutputPaths(validatedInput.output_paths, { workspaceDir });
     } catch (error) {
       return toolError(`Error: ${error.message}`);
     }
-    if (resolvedOutputPaths) {
-      const planSectionCount = (planSegments(validatedInput.plan) ?? []).length;
-      if (resolvedOutputPaths.length !== planSectionCount) {
-        return toolError(
-          `Error: output_paths length (${resolvedOutputPaths.length}) must match `
-          + `plan.sections length (${planSectionCount}). Each section produces exactly one mp4 — `
-          + `don't pad or truncate.`,
-        );
-      }
+    if (!resolvedOutputPaths) {
+      return toolError(
+        'Error: output_paths is required — one workspace-relative mp4 path per plan.sections entry. '
+        + 'Single-section recording is a 1-element array. Multi-section recording records once '
+        + 'continuously (one browser session, one scrollTop) and slices the result at section '
+        + 'boundaries. See frag.short.video_synthesis_tools.',
+      );
+    }
+    const planSectionCount = (planSegments(validatedInput.plan) ?? []).length;
+    if (resolvedOutputPaths.length !== planSectionCount) {
+      return toolError(
+        `Error: output_paths length (${resolvedOutputPaths.length}) must match `
+        + `plan.sections length (${planSectionCount}). Each section produces exactly one mp4 — `
+        + `don't pad or truncate.`,
+      );
     }
 
+    // The master / events JSON paths are agent-optional debug artifacts.
+    // Default master to a tmp path next to the first output; events default
+    // to <master>.events.json. Agent can override either if they care.
+    const { resolvedOutputPath: masterPath, resolvedEventsPath } = resolveRecordUrlNarrationPaths({
+      workspaceDir,
+      outputPath: validatedInput.output_path,
+      eventsPath: validatedInput.events_path,
+      nowMs,
+    });
+    mkdirSync(path.dirname(masterPath), { recursive: true });
+    mkdirSync(path.dirname(resolvedEventsPath), { recursive: true });
+
     const recorderOutput = await recordUrlNarrationFn({
       url: validatedInput.url,
       plan: validatedInput.plan,
-      output_path: resolvedOutputPath,
+      output_path: masterPath,
       events_path: resolvedEventsPath,
       output_paths: resolvedOutputPaths,
       viewport: validatedInput.viewport,
@@ -298,24 +307,11 @@ export async function runRecordUrlNarrationTool({
       settle_ms: validatedInput.settle_ms,
     });
 
-    // Single-output mode (legacy): same one-line summary as before.
-    if (!resolvedOutputPaths) {
-      return toolText(
-        `Recorded URL narration.\n`
-        + `video_path=${resolvedOutputPath}\n`
-        + `events_path=${resolvedEventsPath}\n`
-        + `duration_ms=${deriveDurationMs(recorderOutput) ?? 'unknown'}\n`
-        + `phases=${derivePhaseCount({ plan: validatedInput.plan, recorderOutput }) ?? 'n/a'}`,
-      );
-    }
-
-    // Multi-section mode: one section block per output mp4, plus the
-    // consolidated master mp4 path for debugging / verification.
     const sections = Array.isArray(recorderOutput?.sections) ? recorderOutput.sections : [];
     const lines = [
-      'Recorded URL narration (multi-section).',
-      `master_video_path=${resolvedOutputPath}`,
+      'Recorded URL narration.',
       `events_path=${resolvedEventsPath}`,
+      `master_video_path=${masterPath}`,
       `total_duration_ms=${deriveDurationMs(recorderOutput) ?? 'unknown'}`,
       `sections=${sections.length}`,
     ];