@lightcone-ai/daemon 0.21.0 → 0.22.0

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

@@ -346,20 +346,16 @@ server.tool(
   {
     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_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.'),

package/package.json

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

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 = {} }) {