@lightcone-ai/daemon 0.22.1 → 0.23.1

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

@@ -255,8 +255,16 @@ server.tool(
       presentation: z.object({
         style: z.enum(['static', 'scroll']).optional(),
       }).optional().describe('Optional presentation hints (style only). duration/per_card_duration are computed.'),
-      dwell_ms: z.number().optional().describe('Optional override for record_url_narration phase duration. Default = audio_duration_ms.'),
-    })).describe('Segments to plan. audio_path is required for each.'),
+      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. "fill" allowed only on the LAST hold to auto-fill remaining audio time.'),
+        y: z.number().optional(),
+        x: z.number().optional(),
+        curve: z.enum(['easeInOutQuad', 'linear', 'easeOutQuad']).optional(),
+        mode: z.enum(['auto', 'touch', 'programmatic']).optional(),
+        jitter_px: z.number().optional(),
+      })).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.'),
+    })).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.'),
   },
   async ({ segments }) => {
     const result = await runPlanVideoSegmentsTool({ segments });
@@ -342,28 +350,43 @@ server.tool(
 // audio in production runs (Tasks #20/#25/#26), forcing re-records.
 server.tool(
   'record_url_narration',
-  '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.',
+  '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'
+  + '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'
+  + '  - 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'
+  + '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.',
   {
-    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".\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.'),
+    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).'),
+    plan: z.object({
+      sections: z.array(z.object({
+        id: z.string().optional(),
+        text: z.string().optional(),
+        audio_path: z.string().optional(),
+        dwell_ms: z.number().optional(),
+        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(),
+          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('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).'),
+    output_path: z.string().optional().describe('Debug-only path for the consolidated master recording. Auto-generated under tmp/ if omitted.'),
     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(),
-    }).optional().describe('Default 1080x1920 (mobile portrait). Override only if the plan requires a different shape.'),
+    }).optional().describe('Default 1080x1920 (mobile portrait). Must match page_understanding.viewport.'),
     fps: z.number().optional().describe('Default 30. Do not change unless needed.'),
     settle_ms: z.number().optional().describe('Default 4000. Settle wait after navigation before recording starts.'),
   },

package/mcp-servers/official/page-understanding/index.js

@@ -5,14 +5,13 @@ import { z } from 'zod';
 import { startThinProxy } from '../../_thin-proxy/forward.js';
 
 const AnalyzePageOptionsSchema = z.object({
-  settleMs: z.number().int().min(500).max(30000).optional(),
-  timeoutMs: z.number().int().min(5000).max(240000).optional(),
   viewportWidth: z.number().int().min(360).max(2160).optional(),
   viewportHeight: z.number().int().min(480).max(3840).optional(),
-  minTextBins: z.number().int().min(3).max(40).optional(),
-  minBinChars: z.number().int().min(12).max(200).optional(),
-  allowVisionFallback: z.boolean().optional(),
-  useLlm: z.boolean().optional(),
+  settleMs: z.number().int().min(500).max(30000).optional(),
+  timeoutMs: z.number().int().min(5000).max(240000).optional(),
+  preheatStrategy: z.enum(['none', 'full_scroll_then_top']).optional(),
+  chunkHeight: z.number().int().min(1200).max(6000).optional(),
+  maxChunks: z.number().int().min(1).max(8).optional(),
   fixture_mode: z.boolean().optional(),
 }).passthrough();
 
@@ -22,7 +21,7 @@ await startThinProxy({
   tools: [
     {
       name: 'analyze_page',
-      description: 'Analyze webpage structure for short-video narration planning. Returns page_understanding schema.',
+      description: 'Analyze a webpage for short-video planning. Returns V6 page_understanding: blocks[] (id/y_top/y_bottom/visual_kind/text/summary/keywords/density/visual_weight/contains_image/reading_priority/pacing_hint/narration_hint) + unsafe_regions[] (y_top/y_bottom/reason) + narrative_arc (structure/suggested_flow) + url/page_type/primary_topic/viewport/preheat_strategy/full_height_px. Required for any URL-narration video.',
       inputSchema: {
         url: z.string().url(),
         persona: z.string().optional(),

package/package.json

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

package/src/_vendor/video/cdp-touch.js

@@ -0,0 +1,184 @@
+// CDP-level touch dispatch. Sends real Input.dispatchTouchEvent through a
+// Chrome DevTools Protocol session, so the browser's gesture engine treats
+// the input as a real finger swipe — getting rubber-band overscroll, fling
+// inertia, and paint-synced scroll updates for free. The previous approach
+// (page.evaluate synthesizing TouchEvents + calling scrollBy) bypassed the
+// gesture pipeline entirely, so scrolls looked smooth in isolation but felt
+// "robotic" because none of the physics-driven feedback ran.
+//
+// We pace touchMove dispatches at ~16ms from the Node side. The actual scroll
+// rendering is then driven by Chrome's compositor thread at the display's
+// native refresh rate — the Node-side cadence only determines the velocity
+// vector that Chrome sees, not the visible frame rate. That means
+// requestAnimationFrame-style smoothness comes free as long as touchMoves
+// land at roughly 60Hz; we don't need a JS-side rAF loop anymore.
+
+const DEFAULT_TOUCH_ID = 0;
+const DEFAULT_FORCE = 0.5;
+const DEFAULT_RADIUS = 2;
+const DEFAULT_FRAME_INTERVAL_MS = 16;
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, Math.max(0, Math.round(ms))));
+}
+
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+
+function easeInOutQuad(t) {
+  if (t < 0.5) return 2 * t * t;
+  return 1 - (Math.pow(-2 * t + 2, 2) / 2);
+}
+
+function easeOutQuad(t) {
+  return 1 - ((1 - t) * (1 - t));
+}
+
+function linear(t) {
+  return t;
+}
+
+function resolveCurveFn(name) {
+  if (name === 'linear') return linear;
+  if (name === 'easeOutQuad') return easeOutQuad;
+  return easeInOutQuad;
+}
+
+function randomIntInclusive(min, max, randomFn = Math.random) {
+  return Math.floor(randomFn() * (max - min + 1)) + min;
+}
+
+function buildTouchPoint(x, y, { id = DEFAULT_TOUCH_ID, force = DEFAULT_FORCE } = {}) {
+  return {
+    x: Math.round(x),
+    y: Math.round(y),
+    radiusX: DEFAULT_RADIUS,
+    radiusY: DEFAULT_RADIUS,
+    rotationAngle: 0,
+    force,
+    id,
+  };
+}
+
+// Dispatches a single touch-press / drag / release through CDP. The browser
+// sees this as a real finger gesture, so it produces native fling/momentum
+// behaviour when the release velocity is non-zero (e.g. ease-out releases
+// at speed) and rubber-band when the gesture overruns scroll bounds.
+//
+// Coordinates are viewport pixels (not page pixels). The caller is responsible
+// for translating "I want to scroll the page down by N px" into finger
+// trajectory (finger drags UP to scroll DOWN).
+export async function dispatchSwipe(cdp, {
+  startX,
+  startY,
+  endX,
+  endY,
+  durationMs,
+  curve = 'easeInOutQuad',
+  pixelJitterMin = 0,
+  pixelJitterMax = 0,
+  timingJitterMin = 0,
+  timingJitterMax = 0,
+  frameIntervalMs = DEFAULT_FRAME_INTERVAL_MS,
+  touchId = DEFAULT_TOUCH_ID,
+  randomFn = Math.random,
+} = {}) {
+  if (!cdp || typeof cdp.send !== 'function') {
+    throw new Error('dispatchSwipe requires a CDP session with .send()');
+  }
+  if (![startX, startY, endX, endY, durationMs].every(Number.isFinite)) {
+    throw new Error('dispatchSwipe requires finite startX, startY, endX, endY, durationMs');
+  }
+  const totalMs = Math.max(50, Math.round(durationMs));
+  const interval = Math.max(8, Math.round(frameIntervalMs));
+  const steps = Math.max(2, Math.round(totalMs / interval));
+  const curveFn = resolveCurveFn(curve);
+
+  // touchStart at (startX, startY)
+  await cdp.send('Input.dispatchTouchEvent', {
+    type: 'touchStart',
+    touchPoints: [buildTouchPoint(startX, startY, { id: touchId })],
+  });
+
+  // touchMove sequence: eased interpolation between start and end with optional
+  // small per-step jitter. Chrome computes release velocity from the last few
+  // moves, so the curve shape directly determines whether the gesture has
+  // post-release inertia (ease-in / linear release at speed → fling) or stops
+  // dead (ease-in-out → release at v≈0).
+  let lastDispatchAt = Date.now();
+  for (let i = 1; i < steps; i += 1) {
+    const t = i / steps;
+    const eased = curveFn(t);
+    const baseX = startX + (endX - startX) * eased;
+    const baseY = startY + (endY - startY) * eased;
+    const jitterMag = pixelJitterMin === 0 && pixelJitterMax === 0
+      ? 0
+      : randomIntInclusive(pixelJitterMin, pixelJitterMax, randomFn);
+    const jitterDir = randomFn() < 0.5 ? -1 : 1;
+    const x = baseX;
+    const y = baseY + (jitterMag * jitterDir);
+
+    await cdp.send('Input.dispatchTouchEvent', {
+      type: 'touchMove',
+      touchPoints: [buildTouchPoint(x, y, { id: touchId })],
+    });
+
+    const baseDelay = totalMs / steps;
+    const timingJitter = timingJitterMin === 0 && timingJitterMax === 0
+      ? 0
+      : randomIntInclusive(timingJitterMin, timingJitterMax, randomFn);
+    const timingDir = randomFn() < 0.5 ? -1 : 1;
+    const targetDelay = Math.max(4, Math.round(baseDelay + (timingJitter * timingDir)));
+
+    // Compensate for the time already spent in the CDP send. CDP round-trips
+    // are typically 1-3ms over the local pipe, but if a frame stalls we don't
+    // want to oversleep.
+    const elapsed = Date.now() - lastDispatchAt;
+    const wait = Math.max(0, targetDelay - elapsed);
+    if (wait > 0) await sleep(wait);
+    lastDispatchAt = Date.now();
+  }
+
+  // Final touchMove at exact end coordinates (no jitter) — Chrome reads this
+  // as the release point.
+  await cdp.send('Input.dispatchTouchEvent', {
+    type: 'touchMove',
+    touchPoints: [buildTouchPoint(endX, endY, { id: touchId })],
+  });
+
+  // touchEnd with empty touchPoints array (the touch is released).
+  await cdp.send('Input.dispatchTouchEvent', {
+    type: 'touchEnd',
+    touchPoints: [],
+  });
+}
+
+// Lazy CDP session cache keyed by page. Creating a CDP session per call would
+// add ~1 round-trip of overhead per scroll segment. We attach the session to
+// the page via WeakMap so callers don't have to thread it through.
+const SESSION_CACHE = new WeakMap();
+
+export async function getCdpSession(page) {
+  if (!page || typeof page.context !== 'function') {
+    throw new Error('getCdpSession requires a Playwright page');
+  }
+  const cached = SESSION_CACHE.get(page);
+  if (cached) return cached;
+  const session = await page.context().newCDPSession(page);
+  SESSION_CACHE.set(page, session);
+  return session;
+}
+
+// Test seam: lets unit tests inject a fake CDP session for a fake page object.
+export function __setCdpSessionForTest(page, session) {
+  if (page) SESSION_CACHE.set(page, session);
+}
+
+export const __internals = {
+  easeInOutQuad,
+  easeOutQuad,
+  linear,
+  resolveCurveFn,
+  clamp,
+};

package/src/_vendor/video/humanized-scroll.js

@@ -0,0 +1,251 @@
+import { dispatchSwipe, getCdpSession } from './cdp-touch.js';
+
+const MIN_SEGMENT_DISTANCE_PX = 260;
+const TARGET_SEGMENT_DURATION_MS = 650;
+const MAX_SEGMENTS = 36;
+
+const JITTER_PRESETS = {
+  low: {
+    pixelMin: 2,
+    pixelMax: 3,
+    timingMin: 8,
+    timingMax: 11,
+  },
+  medium: {
+    pixelMin: 2,
+    pixelMax: 4,
+    timingMin: 8,
+    timingMax: 15,
+  },
+  high: {
+    pixelMin: 3,
+    pixelMax: 4,
+    timingMin: 11,
+    timingMax: 15,
+  },
+};
+
+function clampNumber(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+
+function easeInOutQuad(t) {
+  if (t < 0.5) return 2 * t * t;
+  return 1 - (Math.pow(-2 * t + 2, 2) / 2);
+}
+
+function easeOutQuad(t) {
+  return 1 - ((1 - t) * (1 - t));
+}
+
+function linear(t) {
+  return t;
+}
+
+function curveValue(name, t) {
+  if (name === 'linear') return linear(t);
+  if (name === 'easeOutQuad') return easeOutQuad(t);
+  return easeInOutQuad(t);
+}
+
+function randomInt(min, max, randomFn) {
+  return Math.floor(randomFn() * (max - min + 1)) + min;
+}
+
+function resolveJitterPreset(jitterLevel) {
+  if (typeof jitterLevel === 'string' && JITTER_PRESETS[jitterLevel]) {
+    return JITTER_PRESETS[jitterLevel];
+  }
+  return JITTER_PRESETS.medium;
+}
+
+function resolveJitterConfig({ pixelJitterPx, jitterLevel }) {
+  // Direct numeric override wins — used by plan-executor which has historical
+  // per-call jitter budgets (e.g. 1px for cursor_focus, 3px for fast_scroll).
+  // Setting pixel_jitter_px=0 explicitly disables jitter entirely (clean swipe).
+  if (Number.isFinite(pixelJitterPx)) {
+    const px = Math.max(0, Math.floor(pixelJitterPx));
+    if (px === 0) {
+      return { pixelMin: 0, pixelMax: 0, timingMin: 0, timingMax: 0 };
+    }
+    return {
+      pixelMin: Math.max(1, Math.floor(px / 2)),
+      pixelMax: px,
+      timingMin: 6,
+      timingMax: 12,
+    };
+  }
+  return resolveJitterPreset(jitterLevel);
+}
+
+function resolveCurveName(name) {
+  if (name === 'linear') return 'linear';
+  if (name === 'easeOutQuad') return 'easeOutQuad';
+  return 'easeInOutQuad';
+}
+
+function assertFinite(name, value) {
+  if (!Number.isFinite(value)) {
+    throw new Error(`${name} must be a finite number`);
+  }
+}
+
+async function applyMouseVisibility(page, mouseVisible) {
+  if (typeof mouseVisible !== 'boolean') return;
+  await page.evaluate((visible) => {
+    const root = document.documentElement;
+    const body = document.body;
+    const cursorValue = visible ? 'auto' : 'none';
+    if (root) root.style.cursor = cursorValue;
+    if (body) body.style.cursor = cursorValue;
+  }, mouseVisible);
+}
+
+function buildSegments({ fromY, toY, durationMs }) {
+  const distance = Math.abs(toY - fromY);
+  if (distance < 1 || durationMs < 1) return [];
+  const countByDistance = Math.ceil(distance / MIN_SEGMENT_DISTANCE_PX);
+  const countByDuration = Math.ceil(durationMs / TARGET_SEGMENT_DURATION_MS);
+  const segmentCount = clampNumber(Math.max(countByDistance, countByDuration), 1, MAX_SEGMENTS);
+
+  const segments = [];
+  for (let i = 0; i < segmentCount; i += 1) {
+    const startT = i / segmentCount;
+    const endT = (i + 1) / segmentCount;
+    segments.push({
+      index: i,
+      startProgress: startT,
+      endProgress: endT,
+      fromY: Math.round(fromY + ((toY - fromY) * startT)),
+      toY: Math.round(fromY + ((toY - fromY) * endT)),
+    });
+  }
+  return segments;
+}
+
+// Resolve viewport once per call. Falls back to a typical mobile portrait
+// viewport so unit tests can mock minimally.
+function getViewportSize(page) {
+  if (typeof page.viewportSize === 'function') {
+    const size = page.viewportSize();
+    if (size && Number.isFinite(size.width) && Number.isFinite(size.height)) return size;
+  }
+  return { width: 1080, height: 1920 };
+}
+
+// Translate a scroll-by-deltaY request into a finger trajectory and dispatch
+// it through CDP. 1:1 mapping: the finger physically traverses the same
+// number of pixels the page should scroll. Drag UP to scroll DOWN, and vice
+// versa. The browser's gesture engine handles the actual scrollTop update,
+// inertia, and rubber-band — we just supply realistic input events.
+async function runSwipeSegment(page, cdp, {
+  fromY,
+  toY,
+  durationMs,
+  curveName,
+  jitterPreset,
+  randomFn,
+}) {
+  const viewport = getViewportSize(page);
+  const distance = toY - fromY;
+  if (Math.abs(distance) < 1) return;
+  const direction = distance >= 0 ? 1 : -1;
+
+  // Finger starts roughly 78% down the viewport (thumb-friendly zone) and
+  // travels in the opposite direction of the desired page scroll. Travel
+  // length equals scroll distance (1:1).
+  const fingerStartY = clampNumber(Math.round(viewport.height * 0.78), Math.round(viewport.height * 0.5), viewport.height - 100);
+  const requestedTravel = Math.abs(distance);
+  // Hard cap by viewport (a real finger can't go past the screen). Segments
+  // longer than this are split upstream by buildSegments; if one ever slips
+  // through, we clamp here and the caller's scroll will undershoot — that's
+  // fine, the next segment picks up the rest.
+  const maxTravel = fingerStartY - 80;
+  const fingerTravel = Math.min(requestedTravel, maxTravel);
+  const fingerEndY = clampNumber(fingerStartY - (direction * fingerTravel), 60, viewport.height - 60);
+  const horizontalNudge = randomInt(-18, 18, randomFn);
+  const horizontalDrift = randomInt(-26, 26, randomFn);
+  const fingerStartX = clampNumber(Math.round((viewport.width * 0.52) + horizontalNudge), 48, viewport.width - 48);
+  const fingerEndX = clampNumber(fingerStartX + horizontalDrift, 48, viewport.width - 48);
+
+  await dispatchSwipe(cdp, {
+    startX: fingerStartX,
+    startY: fingerStartY,
+    endX: fingerEndX,
+    endY: fingerEndY,
+    durationMs,
+    curve: curveName,
+    pixelJitterMin: jitterPreset.pixelMin,
+    pixelJitterMax: jitterPreset.pixelMax,
+    timingJitterMin: jitterPreset.timingMin,
+    timingJitterMax: jitterPreset.timingMax,
+    randomFn,
+  });
+}
+
+function buildConfig(options = {}) {
+  const randomFn = typeof options.random_fn === 'function' ? options.random_fn : Math.random;
+  const fromY = Number(options.from_y);
+  const toY = Number(options.to_y);
+  const durationMs = Number(options.duration_ms);
+  assertFinite('from_y', fromY);
+  assertFinite('to_y', toY);
+  assertFinite('duration_ms', durationMs);
+  return {
+    fromY: Math.max(0, fromY),
+    toY: Math.max(0, toY),
+    durationMs: Math.max(80, Math.round(durationMs)),
+    jitterPreset: resolveJitterConfig({
+      pixelJitterPx: options.pixel_jitter_px,
+      jitterLevel: options.jitter_level,
+    }),
+    mouseVisible: options.mouseVisible,
+    curveName: resolveCurveName(options.motion_curve),
+    randomFn,
+  };
+}
+
+export async function humanizedScroll(page, options = {}) {
+  if (!page || typeof page.evaluate !== 'function' || typeof page.waitForTimeout !== 'function') {
+    throw new Error('humanizedScroll requires a Playwright page-like object');
+  }
+  const config = buildConfig(options);
+  if (Math.abs(config.toY - config.fromY) < 1) return;
+
+  await applyMouseVisibility(page, config.mouseVisible);
+  const segments = buildSegments(config);
+  if (segments.length === 0) return;
+
+  // Resolve CDP session once per scroll call (cached on page via WeakMap).
+  // Tests can pre-seed the cache with a fake session via __setCdpSessionForTest.
+  const cdp = await getCdpSession(page);
+
+  let segmentsUntilPause = randomInt(3, 5, config.randomFn);
+  for (const segment of segments) {
+    const easedStart = curveValue(config.curveName, segment.startProgress);
+    const easedEnd = curveValue(config.curveName, segment.endProgress);
+    const segmentDuration = Math.max(90, Math.round(config.durationMs * (easedEnd - easedStart)));
+
+    await runSwipeSegment(page, cdp, {
+      fromY: segment.fromY,
+      toY: segment.toY,
+      durationMs: segmentDuration,
+      curveName: config.curveName,
+      jitterPreset: config.jitterPreset,
+      randomFn: config.randomFn,
+    });
+
+    if (segment.index >= segments.length - 1) continue;
+    segmentsUntilPause -= 1;
+    if (segmentsUntilPause <= 0) {
+      const pauseMs = randomInt(100, 300, config.randomFn);
+      await page.waitForTimeout(pauseMs);
+      segmentsUntilPause = randomInt(3, 5, config.randomFn);
+    }
+  }
+}
+
+// V5 convenience wrappers (scrollToDwell / linearScrollDuring / fastScroll)
+// and the snake_case re-exports are removed in V6 — atoms.js calls
+// humanizedScroll directly with explicit params, and there's no longer a
+// separate "fast/slow/dwell" vocabulary at this layer.