@lightcone-ai/daemon 0.22.1 → 0.23.1

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

@@ -0,0 +1,212 @@
+// Page-operation atoms. The closed primitive set plan.sections.operations[]
+// decomposes into. Adding a new atom is a code-level decision; composing new
+// behaviors is data-level (a new operations sequence in the plan).
+//
+// Each atom returns { anchorY } so plan-executor can track where the camera
+// landed (used by subsequent scroll_to's from_y if not explicitly set).
+// anchorY=null for non-scrolling atoms (hold, cursor_focus) — caller keeps
+// the previous anchor.
+//
+// Layout convention: atoms take (page, ctx, params). ctx carries shared
+// resources (CDP session) so atoms don't repeat the page.context dance.
+// plan-executor builds ctx once per section.
+
+import { humanizedScroll } from '../humanized-scroll.js';
+import { getCdpSession } from '../cdp-touch.js';
+
+async function readScrollY(page) {
+  return page.evaluate(() => {
+    const root = document.scrollingElement || document.documentElement;
+    return Math.round(root.scrollTop);
+  });
+}
+
+// ── atomScrollTo ─────────────────────────────────────────────────────────────
+// Animated scroll from current position to target_y over duration_ms.
+//
+// Mode selection (the bit that took an end-to-end failure to learn):
+//   - 'programmatic' (default for distance >= 240px): runs the easing loop
+//     inside page.evaluate via root.scrollTo. Lands EXACTLY at target_y.
+//     Lacks the rubber-band/fling physics of real touch, but reliable.
+//   - 'touch' (default for short distances): humanizedScroll → CDP touch.
+//     Produces natural gesture physics (rubber-band, inertia) but for
+//     larger distances the multi-segment swipe gets broken up into rapid
+//     micro-flings that interfere with each other, and the page often
+//     ends up nowhere near the intended target_y. Safe for distances
+//     that fit in a single ~260px finger swipe.
+//   - 'auto' (default): picks 'touch' for distance < 240px (single
+//     segment, no fling interference), 'programmatic' otherwise.
+//
+// Discovered the hard way: scroll_to_dwell macro with ~18% transition
+// for 1100+ px distances dispatched 5 CDP swipes in ~1s; each touchEnd
+// kicked off a fling that the next touchStart immediately cancelled, so
+// the cumulative scroll never reached target.
+//
+// Params:
+//   target_y      — absolute Y in page coordinates (required)
+//   duration_ms   — total animation time (required)
+//   curve         — 'easeInOutQuad' (default) | 'linear' | 'easeOutQuad'
+//   jitter_px     — per-step vertical jitter (default 2)
+//   from_y        — explicit start position; if omitted reads current scrollY
+//   mode          — 'auto' (default) | 'programmatic' | 'touch'
+export async function atomScrollTo(page, _ctx, {
+  target_y,
+  duration_ms,
+  curve = 'easeInOutQuad',
+  jitter_px = 2,
+  from_y = null,
+  mode = 'auto',
+} = {}) {
+  if (!Number.isFinite(Number(target_y))) {
+    throw new Error('atom_scroll_to: target_y is required');
+  }
+  if (!Number.isFinite(Number(duration_ms)) || Number(duration_ms) <= 0) {
+    throw new Error('atom_scroll_to: duration_ms must be positive');
+  }
+  const fromY = Number.isFinite(Number(from_y))
+    ? Number(from_y)
+    : await readScrollY(page);
+  const targetY = Number(target_y);
+  const durationMs = Number(duration_ms);
+  const distance = Math.abs(targetY - fromY);
+
+  // Auto-mode heuristic: touch works for short distances (single segment, no
+  // inter-segment fling interference) OR slow velocities (each segment has
+  // time to settle before the next starts). Fast long-distance scrolls fall
+  // back to programmatic, where the easing loop drives root.scrollTo
+  // deterministically.
+  // Thresholds chosen empirically against the v4 failure mode (~1100px in
+  // ~1000ms → ~1100 px/s, fling-interrupt-fling, page never reached target).
+  const velocity = durationMs > 0 ? (distance / durationMs) * 1000 : 0; // px/s
+  const resolvedMode = mode === 'programmatic' || mode === 'touch'
+    ? mode
+    : (distance < 240 || velocity < 500 ? 'touch' : 'programmatic');
+
+  if (resolvedMode === 'touch') {
+    await humanizedScroll(page, {
+      from_y: fromY,
+      to_y: targetY,
+      duration_ms: durationMs,
+      motion_curve: curve,
+      pixel_jitter_px: Math.max(0, Number(jitter_px) || 0),
+    });
+  } else {
+    await programmaticScroll(page, {
+      fromY,
+      targetY,
+      durationMs,
+      curve,
+      jitterPx: Math.max(0, Number(jitter_px) || 0),
+    });
+  }
+  return { anchorY: Math.round(targetY) };
+}
+
+// Programmatic scroll: hands the animation off to the browser's native
+// scroll engine via `scroll-behavior: smooth`. That way the easing runs on
+// the compositor thread at the display refresh rate, independent of how
+// busy the page's JS is. The JS-driven setTimeout approach we tried first
+// gets badly throttled on JS-heavy article pages (60Hz timers can stretch
+// to 150-200ms), turning a 1s transition into 5-8s.
+//
+// The wait is Node-side, so even if the in-page scrollend never fires we
+// still cap the section at durationMs and move on. We deliberately do NOT
+// wait for scrollend — empirically faster than dispatching the event on
+// page-heavy mobile sites.
+async function programmaticScroll(page, {
+  fromY,
+  targetY,
+  durationMs,
+} = {}) {
+  // Try every plausible scroll target — mobile article pages sometimes have
+  // a fixed-position outer body and scroll happens on an inner container.
+  // We dispatch to all candidates and let whichever one is actually the
+  // scroller win. Returns the diagnostics so we can debug when the page
+  // refuses to scroll.
+  const diag = await page.evaluate((input) => {
+    const candidates = [];
+    if (document.scrollingElement) candidates.push(document.scrollingElement);
+    if (document.documentElement) candidates.push(document.documentElement);
+    if (document.body) candidates.push(document.body);
+    candidates.push(window);
+
+    const before = candidates.map((c) => {
+      if (c === window) return { tag: 'window', y: window.scrollY };
+      return { tag: c.tagName, y: c.scrollTop };
+    });
+
+    // Hard snap to target on every candidate (instant, no animation).
+    for (const c of candidates) {
+      try {
+        if (c === window) window.scrollTo(0, input.targetY);
+        else { c.scrollTop = input.targetY; }
+      } catch { /* ignore */ }
+    }
+
+    const after = candidates.map((c) => {
+      if (c === window) return { tag: 'window', y: window.scrollY };
+      return { tag: c.tagName, y: c.scrollTop };
+    });
+
+    return {
+      requested_target: input.targetY,
+      before, after,
+      maxScroll: document.documentElement?.scrollHeight,
+      innerHeight: window.innerHeight,
+    };
+  }, { fromY, targetY });
+  void diag;
+  // Brief dwell to let the page settle the snap before next atom starts.
+  await page.waitForTimeout(Math.max(80, Math.round(durationMs * 0.3)));
+}
+
+// ── atomHold ─────────────────────────────────────────────────────────────────
+// Stay at current position for duration_ms. Pure pause — no motion, no
+// cursor update. The dominant choice for "口播 introducing what's on screen"
+// segments: scroll to anchor, then hold for the rest of the audio.
+export async function atomHold(page, _ctx, { duration_ms } = {}) {
+  const ms = Math.max(0, Math.round(Number(duration_ms) || 0));
+  if (ms > 0) await page.waitForTimeout(ms);
+  return { anchorY: null };
+}
+
+// ── atomCursorFocus ──────────────────────────────────────────────────────────
+// Move the cursor to (x, y) in viewport coordinates and hold it there.
+// Used for short pages where there's nothing to scroll to — the cursor
+// shifting between visual focal points carries the rhythm instead.
+//
+// CDP `Input.dispatchMouseEvent` type='mouseMoved' moves the cursor through
+// the real gesture pipeline so the cursor renders on the captured video.
+export async function atomCursorFocus(page, ctx, { x, y, duration_ms } = {}) {
+  if (!Number.isFinite(Number(x)) || !Number.isFinite(Number(y))) {
+    throw new Error('atom_cursor_focus: x and y are required');
+  }
+  if (!Number.isFinite(Number(duration_ms)) || Number(duration_ms) <= 0) {
+    throw new Error('atom_cursor_focus: duration_ms must be positive');
+  }
+  const cdp = ctx?.cdp ?? await getCdpSession(page);
+  await cdp.send('Input.dispatchMouseEvent', {
+    type: 'mouseMoved',
+    x: Math.round(Number(x)),
+    y: Math.round(Number(y)),
+    button: 'none',
+    modifiers: 0,
+  });
+  await page.waitForTimeout(Math.max(0, Math.round(Number(duration_ms))));
+  return { anchorY: null };
+}
+
+// Public atom registry. Plan-executor looks up operation.atom in this map.
+// V6 is closed: agent composes operations[] from these three; if a new page
+// interaction is genuinely needed, a new atom gets added — never a macro.
+//
+// micro_oscillate was deleted in V6 — anchor sections dwell cleanly via `hold`
+// when the口播 content corresponds to what's visible; "natural reader motion"
+// during dwell is the wrong design.
+export const ATOMS = Object.freeze({
+  scroll_to: atomScrollTo,
+  hold: atomHold,
+  cursor_focus: atomCursorFocus,
+});
+
+export const ATOM_NAMES = Object.freeze(Object.keys(ATOMS));

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

@@ -7,7 +7,7 @@ import path from 'node:path';
 import { launchChromiumMobile, openPageAndSettle } from './chromium-driver.js';
 import { defaultDisplayPool } from './display-pool.js';
 import { createUnexpectedExitWatcher, waitForProcessExit } from './ffmpeg-runner.js';
-import { executePlanPhases, normalizePlanPhases } from './plan-executor.js';
+import { executePlanPhases, normalizePlanSections } from './plan-executor.js';
 
 const DEFAULT_VIEWPORT = Object.freeze({ width: 1080, height: 1920 });
 const DEFAULT_FPS = 30;
@@ -152,24 +152,41 @@ async function scrollToTop(page) {
   });
 }
 
-function scalePhaseY(phase, zoom) {
-  if (!phase || typeof phase !== 'object') return phase;
-  const scale = (v) => (Number.isFinite(Number(v)) ? Math.round(Number(v) * zoom) : v);
-  const scaledVisualAction = phase.visual_action && typeof phase.visual_action === 'object'
-    ? {
-        ...phase.visual_action,
-        ...(phase.visual_action.target_y != null ? { target_y: scale(phase.visual_action.target_y) } : {}),
-        ...(phase.visual_action.to_y != null ? { to_y: scale(phase.visual_action.to_y) } : {}),
-        ...(phase.visual_action.from_y != null ? { from_y: scale(phase.visual_action.from_y) } : {}),
-      }
-    : phase.visual_action;
-  return {
-    ...phase,
-    ...(phase.target_y != null ? { target_y: scale(phase.target_y) } : {}),
-    ...(phase.to_y != null ? { to_y: scale(phase.to_y) } : {}),
-    ...(phase.from_y != null ? { from_y: scale(phase.from_y) } : {}),
-    ...(scaledVisualAction !== phase.visual_action ? { visual_action: scaledVisualAction } : {}),
-  };
+// Preheat: slow-scroll to bottom of page to trigger lazy-load (images / late
+// content), then back to top. Both analyze_page and record_url_narration run
+// this so y coordinates in page_understanding match what the record browser
+// sees — without preheat, lazy images haven't loaded, page is shorter, and
+// scroll targets land on the wrong content.
+async function preheatPage(page, { fullHeightPx } = {}) {
+  await page.evaluate(async ({ targetHeight }) => {
+    const step = 600;
+    const stepDelayMs = 180;
+    const root = document.scrollingElement || document.documentElement;
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+    const totalAtStart = Math.max(
+      root.scrollHeight,
+      document.body?.scrollHeight || 0,
+      window.innerHeight,
+    );
+    const target = Number.isFinite(targetHeight) && targetHeight > 0
+      ? Math.max(targetHeight, totalAtStart)
+      : totalAtStart;
+
+    let cursor = 0;
+    while (cursor < target) {
+      cursor = Math.min(target, cursor + step);
+      window.scrollTo(0, cursor);
+      await sleep(stepDelayMs);
+    }
+    await sleep(500);
+
+    window.scrollTo(0, 0);
+    await sleep(300);
+  }, { targetHeight: Number.isFinite(fullHeightPx) ? fullHeightPx : null });
+
+  // Wait for any newly loaded images to settle.
+  try { await page.waitForLoadState('networkidle', { timeout: 4000 }); } catch { /* ignore */ }
 }
 
 // Re-encode the page recording (webm, page content only — no browser chrome) into
@@ -326,22 +343,26 @@ function normalizeOutputPaths(rawList) {
 
 export async function recordUrlNarration({
   plan,
+  // page_understanding (V6) — required for safety-region validation and to
+  // align preheat strategy with what analyze_page used. The recorder's plan-
+  // executor checks scroll_to.y / cursor_focus.y against pageUnderstanding.unsafe_regions
+  // before execution. Without it, scroll_to.y is unbounded and unsafe.
+  page_understanding,
+  pageUnderstanding = page_understanding,
   output_path,
   outputPath = output_path,
   events_path,
   eventsPath = events_path,
-  // Multi-section output: pass an array of N paths matching plan.sections length
-  // to record once continuously and slice the result into N per-section mp4s.
-  // The browser stays open for the whole recording, so visuals flow naturally
-  // between sections (no scroll-back-to-top between each, no page reload). When
-  // omitted, behaves exactly like before — single mp4 at outputPath.
+  // Multi-section output: array of N paths matching plan.sections length.
+  // Recorder captures once continuously and slices into N per-section mp4s,
+  // so visuals flow naturally between sections (no scroll-back-to-top, no
+  // page reload).
   output_paths,
   outputPaths = output_paths,
   url,
   viewport = DEFAULT_VIEWPORT,
   fps = DEFAULT_FPS,
   settle_ms = 4000,
-  page_zoom = 1.1,
   displayPool = defaultDisplayPool,
   startupProbeMs = 1200,
   xvfbStopTimeoutMs = 5000,
@@ -353,12 +374,19 @@ export async function recordUrlNarration({
   cutFn = cutMp4Slice,
   nowMs = () => Date.now(),
 } = {}) {
-  const zoom = Number.isFinite(Number(page_zoom)) && Number(page_zoom) > 0 ? Number(page_zoom) : 1.1;
-  const rawPhases = normalizePlanPhases(plan);
-  const phases = zoom !== 1.0 ? rawPhases.map(p => scalePhaseY(p, zoom)) : rawPhases;
+  if (!pageUnderstanding || typeof pageUnderstanding !== 'object' || Array.isArray(pageUnderstanding)) {
+    const error = new Error(
+      'page_understanding_required: V6 record_url_narration requires page_understanding (from analyze_page) '
+      + 'for safe-region validation and preheat consistency. No silent default — refusing rather than running blind.',
+    );
+    error.code = 'PAGE_UNDERSTANDING_REQUIRED';
+    throw error;
+  }
+
+  const sections = normalizePlanSections(plan);
   const executablePlan = {
     ...(plan && typeof plan === 'object' ? plan : {}),
-    phases,
+    sections,
   };
 
   const resolvedOutputPath = resolveOutputPath(outputPath);
@@ -378,9 +406,9 @@ export async function recordUrlNarration({
     error.code = 'OUTPUT_PATHS_REQUIRED';
     throw error;
   }
-  if (resolvedOutputPaths.length !== phases.length) {
+  if (resolvedOutputPaths.length !== sections.length) {
     const error = new Error(
-      `output_paths_count_mismatch:expected=${phases.length}:got=${resolvedOutputPaths.length}`,
+      `output_paths_count_mismatch:expected=${sections.length}:got=${resolvedOutputPaths.length}`,
     );
     error.code = 'OUTPUT_PATHS_COUNT_MISMATCH';
     throw error;
@@ -438,11 +466,13 @@ export async function recordUrlNarration({
       settleMs: settle_ms,
     });
 
-    if (zoom !== 1.0) {
-      await browserSession.page.evaluate((z) => {
-        document.documentElement.style.zoom = String(z);
-      }, zoom);
-      await browserSession.page.waitForTimeout(300);
+    // Preheat to match analyze_page's page state — triggers lazy-loaded
+    // images so y coordinates stabilize at the same values the analyzer saw.
+    // Skipped when pageUnderstanding.preheat_strategy === 'none'.
+    if (pageUnderstanding.preheat_strategy === 'full_scroll_then_top') {
+      await preheatPage(browserSession.page, {
+        fullHeightPx: pageUnderstanding.full_height_px,
+      });
     }
 
     await scrollToTop(browserSession.page);
@@ -451,7 +481,7 @@ export async function recordUrlNarration({
     const headTrimMs = Math.max(0, nowMs() - recordStartedAt);
 
     const eventsLog = await Promise.race([
-      executePlanPhases(browserSession.page, executablePlan),
+      executePlanPhases(browserSession.page, executablePlan, { pageUnderstanding }),
       xvfbWatcher.promise,
     ]);
 
@@ -510,7 +540,7 @@ export async function recordUrlNarration({
     // 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.
-    const cutPoints = deriveSectionCutPoints(eventsLog, phases.length);
+    const cutPoints = deriveSectionCutPoints(eventsLog, sections.length);
     const sectionOutputs = [];
     for (let i = 0; i < cutPoints.length; i += 1) {
       const cut = cutPoints[i];