@lightcone-ai/daemon 0.23.6 → 0.23.8

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

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

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

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

package/package.json

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

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

@@ -24,23 +24,18 @@ async function readScrollY(page) {
 // ── atomScrollTo ─────────────────────────────────────────────────────────────
 // Animated scroll from current position to target_y over duration_ms.
 //
-// Mode selection (the bit that took an end-to-end failure to learn):
-//   - 'programmatic' (default for distance >= 240px): runs the easing loop
-//     inside page.evaluate via root.scrollTo. Lands EXACTLY at target_y.
-//     Lacks the rubber-band/fling physics of real touch, but reliable.
-//   - 'touch' (default for short distances): humanizedScroll → CDP touch.
-//     Produces natural gesture physics (rubber-band, inertia) but for
-//     larger distances the multi-segment swipe gets broken up into rapid
-//     micro-flings that interfere with each other, and the page often
-//     ends up nowhere near the intended target_y. Safe for distances
-//     that fit in a single ~260px finger swipe.
-//   - 'auto' (default): picks 'touch' for distance < 240px (single
-//     segment, no fling interference), 'programmatic' otherwise.
-//
-// Discovered the hard way: scroll_to_dwell macro with ~18% transition
-// for 1100+ px distances dispatched 5 CDP swipes in ~1s; each touchEnd
-// kicked off a fling that the next touchStart immediately cancelled, so
-// the cumulative scroll never reached target.
+// Mode selection:
+//   - 'programmatic': RAF-driven easing loop inside page.evaluate via
+//     root.scrollTo. Every frame moves, vertical only, lands EXACTLY at
+//     target_y. This is what a smooth between-blocks transition needs.
+//   - 'touch': humanizedScroll → CDP touch. Real gesture physics (rubber-
+//     band, inertia) but splits scroll > 260px into multiple swipes with
+//     fling-cancel-fling boundaries and ±18-26px horizontal nudge — looks
+//     like a shaky multi-tap drag, not a clean slide.
+//   - 'auto' (default): resolves to 'programmatic'. Touch's gesture physics
+//     lost out to a clean slide for narration video; it stays reachable
+//     only via explicit `mode: 'touch'`. See the resolvedMode block below
+//     for the full rationale.
 //
 // Params:
 //   target_y      — absolute Y in page coordinates (required)

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

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

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

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

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

@@ -14,8 +14,9 @@
 // or unsafe coordinates throw — no silent skipping.
 
 import { ATOMS, ATOM_NAMES } from './atoms.js';
-import { findOverlappingUnsafeRegion } from '../understanding/schema.js';
+import { findBlockById, findOverlappingUnsafeRegion } from '../understanding/schema.js';
 import { getCdpSession } from '../cdp-touch.js';
+import { setSpotlight, clearSpotlight } from './spotlight.js';
 
 const V5_FIELDS_ON_SECTION = Object.freeze([
   'action',
@@ -93,7 +94,70 @@ function assertYNotInUnsafeRegion(y, { unsafeRegions, atomName, sectionId, opera
   }
 }
 
-function validateOperation(op, { sectionId, operationIndex, fullHeightPx, unsafeRegions }) {
+// Resolve a scroll_to operation's target scrollTop. Two mutually-exclusive forms:
+//
+//   { block: 'b3' } — frame a content block: the block's middle is placed at
+//     the viewport center, then the section holds STILL on it. The recorder
+//     owns this geometry so the agent never writes pixels. A block taller than
+//     the viewport just shows its centered slice held still — there is no pan,
+//     partial visibility is accepted (decided 2026-05-16: 定住，接受看不全).
+//
+//   { y: <number> } — raw scrollTop, for content-agnostic moves such as the
+//     opening lead-in drift (画面跟内容无关的漫滑).
+//
+// Result is clamped to [0, full_height_px - viewport_height].
+export function resolveScrollTargetY(op, {
+  blocks = [],
+  viewportHeight = 1920,
+  fullHeightPx = null,
+  sectionId = '?',
+  operationIndex = 0,
+} = {}) {
+  const hasBlock = typeof op?.block === 'string' && op.block.trim();
+  const hasY = Number.isFinite(Number(op?.y));
+
+  if (hasBlock && hasY) {
+    const error = new Error(
+      `operations_invalid: section "${sectionId}" operations[${operationIndex}] sets both `
+      + '`block` and `y` on a scroll_to — specify exactly one (block to frame a content block, '
+      + 'y for a raw content-agnostic move).',
+    );
+    error.code = 'OPERATIONS_INVALID';
+    throw error;
+  }
+
+  if (hasBlock) {
+    const blockId = op.block.trim();
+    const block = findBlockById(blocks, blockId);
+    if (!block) {
+      const known = blocks.map(b => b?.id).filter(Boolean).join(', ') || '(none)';
+      const error = new Error(
+        `block_not_found: section "${sectionId}" operations[${operationIndex}].block="${blockId}" `
+        + `is not a block id in page_understanding.blocks. Known ids: ${known}.`,
+      );
+      error.code = 'BLOCK_NOT_FOUND';
+      throw error;
+    }
+    // Center the block. A block taller than the viewport shows its centered
+    // slice — the section then holds still on it (no pan).
+    const target = (block.y_top + block.y_bottom) / 2 - viewportHeight / 2;
+    const maxScroll = Number.isFinite(fullHeightPx) && fullHeightPx > 0
+      ? Math.max(0, fullHeightPx - viewportHeight)
+      : Number.POSITIVE_INFINITY;
+    return Math.round(Math.min(Math.max(target, 0), maxScroll));
+  }
+
+  if (hasY) return Math.round(Number(op.y));
+
+  const error = new Error(
+    `operations_invalid: section "${sectionId}" operations[${operationIndex}] is a scroll_to with `
+    + 'neither `block` nor `y`. Set `block` (centers/frames a content block) or `y` (raw scrollTop).',
+  );
+  error.code = 'OPERATIONS_INVALID';
+  throw error;
+}
+
+function validateOperation(op, { sectionId, operationIndex, fullHeightPx, unsafeRegions, blocks, viewportHeight }) {
   if (!op || typeof op !== 'object' || Array.isArray(op)) {
     const error = new Error(
       `operations_invalid: section "${sectionId}" operations[${operationIndex}] is not an object.`,
@@ -120,9 +184,15 @@ function validateOperation(op, { sectionId, operationIndex, fullHeightPx, unsafe
     throw error;
   }
 
+  let scrollTargetY = null;
   if (atomName === 'scroll_to') {
-    assertYWithinBounds(Number(op.y), { fullHeightPx, atomName, sectionId, operationIndex });
-    assertYNotInUnsafeRegion(Number(op.y), { unsafeRegions, atomName, sectionId, operationIndex });
+    // scroll_to.y is no longer agent-authored pixels — resolveScrollTargetY
+    // turns { block, align } into a clamped scrollTop. Raw { y } is still
+    // accepted for content-agnostic moves. The resolved value is what gets
+    // bounds/unsafe-checked and handed to the atom.
+    scrollTargetY = resolveScrollTargetY(op, { blocks, viewportHeight, fullHeightPx, sectionId, operationIndex });
+    assertYWithinBounds(scrollTargetY, { fullHeightPx, atomName, sectionId, operationIndex });
+    assertYNotInUnsafeRegion(scrollTargetY, { unsafeRegions, atomName, sectionId, operationIndex });
   } else if (atomName === 'cursor_focus') {
     assertYWithinBounds(Number(op.y), { fullHeightPx, atomName, sectionId, operationIndex });
     assertYNotInUnsafeRegion(Number(op.y), { unsafeRegions, atomName, sectionId, operationIndex });
@@ -134,16 +204,19 @@ function validateOperation(op, { sectionId, operationIndex, fullHeightPx, unsafe
       throw error;
     }
   }
-  return atomName;
+  return { atomName, scrollTargetY };
 }
 
-function operationToAtomParams(op, atomName, anchorY) {
+function operationToAtomParams(op, atomName, anchorY, scrollTargetY) {
   if (atomName === 'scroll_to') {
     return {
-      target_y: Number(op.y),
+      // scrollTargetY is resolved by resolveScrollTargetY (block-framed or raw y).
+      target_y: scrollTargetY,
       duration_ms: Number(op.duration_ms),
       curve: op.curve || 'easeInOutQuad',
-      jitter_px: Number.isFinite(Number(op.jitter_px)) ? Number(op.jitter_px) : 2,
+      // Default 0 — no pixel jitter (user requirement, repeatedly stated).
+      // Only consulted by touch mode; auto/programmatic ignore it.
+      jitter_px: Number.isFinite(Number(op.jitter_px)) ? Number(op.jitter_px) : 0,
       from_y: anchorY,
       mode: op.mode || 'auto',
     };
@@ -198,22 +271,45 @@ export function normalizePlanSections(plan = {}) {
 async function runOperations(page, ctx, operations, {
   fullHeightPx,
   unsafeRegions,
+  blocks,
+  viewportHeight,
+  viewportWidth,
   sectionId,
   fallbackAnchorY,
 }) {
   let anchorY = fallbackAnchorY;
+  // Spotlight off during the transition scroll — it appears once the section's
+  // block has landed centered (set right after the scroll_to below).
+  await clearSpotlight(page);
   for (let i = 0; i < operations.length; i += 1) {
     const op = operations[i];
-    const atomName = validateOperation(op, {
+    const { atomName, scrollTargetY } = validateOperation(op, {
       sectionId,
       operationIndex: i,
       fullHeightPx,
       unsafeRegions,
+      blocks,
+      viewportHeight,
     });
-    const params = operationToAtomParams(op, atomName, anchorY);
+    const params = operationToAtomParams(op, atomName, anchorY, scrollTargetY);
     const atomFn = ATOMS[atomName];
     const result = await atomFn(page, ctx, params);
     if (result?.anchorY != null) anchorY = result.anchorY;
+    // Once a scroll_to has landed on a content block, frame it: bordered box
+    // around the block + the rest of the page dimmed. The box then stays for
+    // the section's hold.
+    if (atomName === 'scroll_to' && typeof op.block === 'string' && op.block.trim()) {
+      const blk = findBlockById(blocks, op.block.trim());
+      if (blk) {
+        await setSpotlight(page, {
+          yTop: blk.y_top,
+          yBottom: blk.y_bottom,
+          viewportTop: scrollTargetY,
+          viewportHeight,
+          viewportWidth,
+        });
+      }
+    }
   }
   return { anchorY };
 }
@@ -230,6 +326,11 @@ function createEvent({ tMs, action, sectionId, detail = {} }) {
 
 export async function executePlanPhases(page, plan, {
   pageUnderstanding = null,
+  // The actual record-browser viewport height — used to frame block-referenced
+  // scroll_to operations. Falls back to page_understanding.viewport.height,
+  // then 1920. Pass the real recorder viewport so centering is pixel-correct.
+  viewportHeight = null,
+  viewportWidth = null,
   getNowMs = () => Date.now(),
   onEvent = null,
 } = {}) {
@@ -238,6 +339,13 @@ export async function executePlanPhases(page, plan, {
   const unsafeRegions = Array.isArray(pageUnderstanding?.unsafe_regions)
     ? pageUnderstanding.unsafe_regions
     : [];
+  const blocks = Array.isArray(pageUnderstanding?.blocks) ? pageUnderstanding.blocks : [];
+  const resolvedViewportHeight = Number(viewportHeight)
+    || Number(pageUnderstanding?.viewport?.height)
+    || 1920;
+  const resolvedViewportWidth = Number(viewportWidth)
+    || Number(pageUnderstanding?.viewport?.width)
+    || 1080;
 
   const startedAt = nowMs(getNowMs);
   const eventsLog = [];
@@ -263,6 +371,9 @@ export async function executePlanPhases(page, plan, {
       const result = await runOperations(page, ctx, section.operations, {
         fullHeightPx,
         unsafeRegions,
+        blocks,
+        viewportHeight: resolvedViewportHeight,
+        viewportWidth: resolvedViewportWidth,
         sectionId,
         fallbackAnchorY: lastAnchorY,
       });