@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/dist/tools/captureScreenRecording.d.ts

@@ -1,12 +1,64 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { type Interaction, type Viewport } from "../capture";
+import { type CursorPoint, type Interaction, type SettleReport, type Viewport } from "@openvidstudio/capture";
 export interface CaptureScreenRecordingInput {
     projectRoot?: string;
     beatId: string;
     url: string;
     viewport?: Viewport;
+    /** Pixels recorded per CSS pixel. Defaults to 2, same reasoning as capture_screenshot. */
+    deviceScaleFactor?: number;
+    /**
+     * Settle the page before the recording starts. Defaults to true.
+     *
+     * Without it the first second of every clip is the page still assembling itself: fonts
+     * swapping, images popping in, the hero animating from nothing. That is the second a
+     * viewer decides whether the product looks finished.
+     */
+    settle?: boolean;
+    settleTimeoutMs?: number;
+    /**
+     * Navigation wait condition. Defaults to "load", same reasoning as capture_screenshot's
+     * own waitUntil: a dev server with an open websocket never reaches "networkidle", so that
+     * cannot be the default. Opt into "networkidle" only for a beat whose real content arrives
+     * from a delayed fetch after "load" already fired.
+     */
+    waitUntil?: "load" | "networkidle";
+    /**
+     * Replay rate. 2 is twice as fast, 0.5 is half speed. Defaults to 1.
+     *
+     * Real interaction is often too slow to watch and occasionally too fast to follow. A
+     * form being filled wants speeding up; a state change worth noticing wants slowing down.
+     * Applied at transcode with setpts, so the recording itself is untouched and the beat's
+     * duration in the manifest is the duration after the change.
+     */
+    speed?: number;
+    /**
+     * Piecewise alternative to `speed`: a list of non-overlapping { startMs, endMs, speed }
+     * ranges (against the RAW recording's own timeline, before retiming) so one clip can have
+     * one slow stretch and one fast stretch instead of a single flat multiplier for the whole
+     * thing. Gaps between/around the given ranges play at speed 1 automatically -- nothing
+     * outside the ranges you name is ever dropped. Mutually exclusive with `speed`: pass one
+     * or the other, never both.
+     */
+    segments?: RetimeSegment[];
     interactions?: Interaction[];
     outPath?: string;
+    /**
+     * Emulate a color scheme for the recording context. Same reasoning as capture_screenshot's
+     * colorScheme: set at context creation, before the page exists, so prefers-color-scheme CSS
+     * is correct from the first frame rather than racing a page that reads the media query once.
+     */
+    colorScheme?: "light" | "dark";
+    /** Emulate prefers-reduced-motion: reduce for the recording context. Off by default. */
+    reducedMotion?: boolean;
+    /**
+     * Freeze Date.now()/new Date() and seed Math.random() before the page ever runs, so a
+     * page whose content depends on either (a timestamp-based id, a randomly ordered list)
+     * records identically on every run. Off by default. Timers/animations still run in real
+     * time -- this does not force a CSS/JS animation to a specific phase, which stays a
+     * separate, harder problem.
+     */
+    deterministic?: boolean;
 }
 export interface CaptureScreenRecordingResult {
     outPath: string;
@@ -14,6 +66,15 @@ export interface CaptureScreenRecordingResult {
     height: number;
     zoom: number;
     durationMs?: number;
+    settle?: SettleReport;
+    /**
+     * Real click/hover/fill/select target centers measured during interaction replay, with
+     * atMs rewritten to be relative to the RECORDING's own start (navigation+settle time
+     * added back in) rather than replay-relative, so a consumer can turn a point into a video
+     * frame directly via fps. Also written to `<outPath>.cursor.json`. Empty/absent when
+     * there were no such interactions.
+     */
+    cursorPoints?: CursorPoint[];
 }
 /**
  * Pure argv builder, unit-testable without spawning ffmpeg. Remotion's
@@ -21,8 +82,47 @@ export interface CaptureScreenRecordingResult {
  * transcoded to mp4 (h264/yuv420p, +faststart) -- same spawn/argv-array
  * discipline as render_video/qc_extract_frames.
  */
-export declare function buildFfmpegTranscodeArgs(inputPath: string, outputPath: string): string[];
+export declare function buildFfmpegTranscodeArgs(inputPath: string, outputPath: string, speed?: number): string[];
 /** Pure argv builder for the best-effort ffprobe duration lookup. */
 export declare function buildFfprobeDurationArgs(filePath: string): string[];
+export interface RetimeSegment {
+    startMs: number;
+    endMs: number;
+    /** 2 is twice as fast, 0.5 is half speed, same convention as the flat `speed` field. */
+    speed: number;
+}
+/**
+ * Throws on anything that would make the ffmpeg filter graph below ambiguous or wrong:
+ * out-of-range bounds, a zero-width or backwards range, a non-positive speed, or two
+ * ranges that overlap (which would ask the same span of footage to play at two different
+ * speeds at once, with no defined answer for which one wins).
+ */
+export declare function validateRetimeSegments(segments: RetimeSegment[], totalDurationMs: number): void;
+/**
+ * Fills the gaps between/around the caller's explicit ranges with speed: 1, so retiming
+ * never silently drops the footage outside the ranges someone actually named -- a beat
+ * that only wants to speed up its middle third still needs its first and last thirds in
+ * the output. Assumes segments is already validated (validateRetimeSegments) and sorted.
+ */
+export declare function fillRetimeGaps(segments: RetimeSegment[], totalDurationMs: number): RetimeSegment[];
+/**
+ * Piecewise version of buildFfmpegTranscodeArgs's single flat setpts: trims the input into
+ * each (gap-filled, non-overlapping, ordered) segment, rebases each to its own zero
+ * (setpts=PTS-STARTPTS) then scales by that segment's own speed, and concatenates them
+ * back together in order via ffmpeg's filter_complex concat -- the documented,
+ * well-verified pattern for variable-speed video, and considerably easier to reason about
+ * and test than one conditional setpts expression trying to cover the whole timeline.
+ * `segments` must already cover [0, the real duration] with no gaps (fillRetimeGaps) --
+ * this function does not check that; a gap here would silently drop that span of footage.
+ */
+export declare function buildPiecewiseRetimeArgs(inputPath: string, outputPath: string, segments: RetimeSegment[]): string[];
+/**
+ * Maps a real, pre-retiming timestamp (a cursor point's atMs, measured against the raw
+ * recording) through the same piecewise time-warp buildPiecewiseRetimeArgs applies to the
+ * video, so a cursor overlay built from the result lands on the same moment in the FINAL
+ * retimed clip that it did in reality -- the piecewise equivalent of item 3's flat
+ * `atMs / speed` rebase. `segments` must be gap-filled (fillRetimeGaps) and sorted.
+ */
+export declare function remapAtMsThroughSegments(atMs: number, segments: RetimeSegment[]): number;
 export declare function runCaptureScreenRecording(input: CaptureScreenRecordingInput): Promise<CaptureScreenRecordingResult>;
 export declare function registerCaptureScreenRecording(server: McpServer): void;

package/dist/tools/captureScreenRecording.js

@@ -35,6 +35,10 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildFfmpegTranscodeArgs = buildFfmpegTranscodeArgs;
 exports.buildFfprobeDurationArgs = buildFfprobeDurationArgs;
+exports.validateRetimeSegments = validateRetimeSegments;
+exports.fillRetimeGaps = fillRetimeGaps;
+exports.buildPiecewiseRetimeArgs = buildPiecewiseRetimeArgs;
+exports.remapAtMsThroughSegments = remapAtMsThroughSegments;
 exports.runCaptureScreenRecording = runCaptureScreenRecording;
 exports.registerCaptureScreenRecording = registerCaptureScreenRecording;
 const fs = __importStar(require("node:fs"));
@@ -42,21 +46,143 @@ const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const zod_1 = require("zod");
 const util_1 = require("../util");
-const capture_1 = require("../capture");
+const capture_1 = require("@openvidstudio/capture");
 const mcp_1 = require("./mcp");
+const facts_1 = require("../facts");
 /**
  * Pure argv builder, unit-testable without spawning ffmpeg. Remotion's
  * OffthreadVideo needs a seekable format, so Playwright's webm output gets
  * transcoded to mp4 (h264/yuv420p, +faststart) -- same spawn/argv-array
  * discipline as render_video/qc_extract_frames.
  */
-function buildFfmpegTranscodeArgs(inputPath, outputPath) {
-    return ["-nostdin", "-i", inputPath, "-c:v", "libx264", "-pix_fmt", "yuv420p", "-movflags", "+faststart", outputPath, "-y"];
+function buildFfmpegTranscodeArgs(inputPath, outputPath, speed = 1) {
+    // Screen-tuned, not film-tuned. x264's defaults (crf 23, film psy settings) spend bitrate
+    // on grain this footage does not have and starve the hard edges it is entirely made of,
+    // which reads as ringing around text. Shared with the native backends so every capture in
+    // the pipeline is encoded identically.
+    // setpts scales presentation timestamps: 2x faster means each frame is shown at half its
+    // original time, so the multiplier is the reciprocal. Captures are silent, so there is no
+    // audio track to keep in step.
+    const retime = speed !== 1 ? ["-vf", `setpts=${(1 / speed).toFixed(6)}*PTS`] : [];
+    return [
+        "-nostdin",
+        "-i",
+        inputPath,
+        ...retime,
+        ...(0, capture_1.screenEncodeArgs)(),
+        "-pix_fmt",
+        "yuv420p",
+        "-movflags",
+        "+faststart",
+        outputPath,
+        "-y",
+    ];
 }
 /** Pure argv builder for the best-effort ffprobe duration lookup. */
 function buildFfprobeDurationArgs(filePath) {
     return ["-v", "error", "-show_entries", "format=duration", "-of", "default=noprint_wrappers=1:nokey=1", filePath];
 }
+/**
+ * Throws on anything that would make the ffmpeg filter graph below ambiguous or wrong:
+ * out-of-range bounds, a zero-width or backwards range, a non-positive speed, or two
+ * ranges that overlap (which would ask the same span of footage to play at two different
+ * speeds at once, with no defined answer for which one wins).
+ */
+function validateRetimeSegments(segments, totalDurationMs) {
+    const sorted = [...segments].sort((a, b) => a.startMs - b.startMs);
+    let prevEnd = 0;
+    for (const seg of sorted) {
+        if (!(seg.startMs >= 0) || !(seg.endMs > seg.startMs)) {
+            throw new Error(`segments: invalid range { startMs: ${seg.startMs}, endMs: ${seg.endMs} } -- endMs must be greater than startMs, both non-negative.`);
+        }
+        if (seg.endMs > totalDurationMs) {
+            throw new Error(`segments: range endMs ${seg.endMs} is past the recording's real duration (${totalDurationMs}ms).`);
+        }
+        if (!(seg.speed > 0)) {
+            throw new Error(`segments: speed ${seg.speed} must be greater than 0.`);
+        }
+        if (seg.startMs < prevEnd) {
+            throw new Error(`segments: range starting at ${seg.startMs}ms overlaps the previous one, which ends at ${prevEnd}ms -- ranges must be non-overlapping.`);
+        }
+        prevEnd = seg.endMs;
+    }
+}
+/**
+ * Fills the gaps between/around the caller's explicit ranges with speed: 1, so retiming
+ * never silently drops the footage outside the ranges someone actually named -- a beat
+ * that only wants to speed up its middle third still needs its first and last thirds in
+ * the output. Assumes segments is already validated (validateRetimeSegments) and sorted.
+ */
+function fillRetimeGaps(segments, totalDurationMs) {
+    const sorted = [...segments].sort((a, b) => a.startMs - b.startMs);
+    const filled = [];
+    let cursor = 0;
+    for (const seg of sorted) {
+        if (seg.startMs > cursor)
+            filled.push({ startMs: cursor, endMs: seg.startMs, speed: 1 });
+        filled.push(seg);
+        cursor = seg.endMs;
+    }
+    if (cursor < totalDurationMs)
+        filled.push({ startMs: cursor, endMs: totalDurationMs, speed: 1 });
+    return filled;
+}
+/**
+ * Piecewise version of buildFfmpegTranscodeArgs's single flat setpts: trims the input into
+ * each (gap-filled, non-overlapping, ordered) segment, rebases each to its own zero
+ * (setpts=PTS-STARTPTS) then scales by that segment's own speed, and concatenates them
+ * back together in order via ffmpeg's filter_complex concat -- the documented,
+ * well-verified pattern for variable-speed video, and considerably easier to reason about
+ * and test than one conditional setpts expression trying to cover the whole timeline.
+ * `segments` must already cover [0, the real duration] with no gaps (fillRetimeGaps) --
+ * this function does not check that; a gap here would silently drop that span of footage.
+ */
+function buildPiecewiseRetimeArgs(inputPath, outputPath, segments) {
+    const labels = segments.map((_, i) => `v${i}`);
+    const chains = segments.map((seg, i) => {
+        const start = (seg.startMs / 1000).toFixed(6);
+        const end = (seg.endMs / 1000).toFixed(6);
+        const factor = (1 / seg.speed).toFixed(6);
+        return `[0:v]trim=start=${start}:end=${end},setpts=PTS-STARTPTS,setpts=${factor}*PTS[${labels[i]}]`;
+    });
+    const concat = `${labels.map((l) => `[${l}]`).join("")}concat=n=${labels.length}:v=1:a=0[outv]`;
+    return [
+        "-nostdin",
+        "-i",
+        inputPath,
+        "-filter_complex",
+        `${chains.join(";")};${concat}`,
+        "-map",
+        "[outv]",
+        ...(0, capture_1.screenEncodeArgs)(),
+        "-pix_fmt",
+        "yuv420p",
+        "-movflags",
+        "+faststart",
+        outputPath,
+        "-y",
+    ];
+}
+/**
+ * Maps a real, pre-retiming timestamp (a cursor point's atMs, measured against the raw
+ * recording) through the same piecewise time-warp buildPiecewiseRetimeArgs applies to the
+ * video, so a cursor overlay built from the result lands on the same moment in the FINAL
+ * retimed clip that it did in reality -- the piecewise equivalent of item 3's flat
+ * `atMs / speed` rebase. `segments` must be gap-filled (fillRetimeGaps) and sorted.
+ */
+function remapAtMsThroughSegments(atMs, segments) {
+    let acc = 0;
+    for (const seg of segments) {
+        const spanInThisSegment = Math.min(atMs, seg.endMs) - seg.startMs;
+        if (spanInThisSegment <= 0)
+            continue;
+        if (atMs <= seg.endMs) {
+            return acc + spanInThisSegment / seg.speed;
+        }
+        acc += spanInThisSegment / seg.speed;
+    }
+    return acc;
+}
 /**
  * Best-effort duration via ffprobe. Not a new dependency (ffprobe ships
  * alongside the ffmpeg this tool already requires for the transcode); if it's
@@ -76,9 +202,37 @@ async function probeDurationMs(filePath, cwd) {
     }
 }
 async function runCaptureScreenRecording(input) {
+    const result = await captureScreenRecording(input);
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    (0, facts_1.writeFactRecord)(projectRoot, {
+        tool: "capture_screen_recording",
+        beatId: (0, util_1.sanitizeSegment)(input.beatId, "beatId"),
+        facts: {
+            kind: "real-capture",
+            outPath: (0, facts_1.relToProject)(projectRoot, result.outPath),
+            bytes: (0, facts_1.fileBytes)(result.outPath),
+            url: input.url,
+            viewport: { width: result.width, height: result.height },
+            durationMs: result.durationMs ?? null,
+            speed: input.speed ?? 1,
+            interactions: input.interactions?.length ?? 0,
+            settled: result.settle?.settled ?? null,
+            settleWaitedMs: result.settle?.waitedMs ?? null,
+        },
+    });
+    return result;
+}
+async function captureScreenRecording(input) {
     const beatId = (0, util_1.sanitizeSegment)(input.beatId, "beatId");
     const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
     const target = input.viewport ?? capture_1.DEFAULT_VIEWPORT;
+    const deviceScaleFactor = input.deviceScaleFactor ?? capture_1.DEFAULT_DEVICE_SCALE;
+    if (input.segments && input.segments.length > 0 && input.speed !== undefined) {
+        throw new Error("Pass either speed or segments, not both -- combining a flat multiplier with piecewise retiming ranges is ambiguous.");
+    }
+    const speed = input.speed ?? 1;
+    if (!(speed > 0))
+        throw new Error("speed must be greater than 0. 2 is twice as fast, 0.5 is half speed.");
     const outPathRel = input.outPath ?? path.join("public", "video", `${beatId}.mp4`);
     (0, util_1.sanitizeRelativeOutPath)(projectRoot, outPathRel, "outPath");
     const outPathAbs = path.join(projectRoot, outPathRel);
@@ -95,7 +249,7 @@ async function runCaptureScreenRecording(input) {
         try {
             const probePage = await probeContext.newPage();
             await probePage.setViewportSize(target);
-            await probePage.goto(input.url, { waitUntil: "load" });
+            await probePage.goto(input.url, { waitUntil: input.waitUntil ?? "load" });
             const compensation = await (0, capture_1.detectAndCompensateZoom)(probePage, target);
             zoom = compensation.zoom;
             compensatedViewport = compensation.viewport;
@@ -107,15 +261,52 @@ async function runCaptureScreenRecording(input) {
         // requested) viewport -- same reasoning as capture_screenshot.
         const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "ovs-capture-"));
         let webmPath;
+        let settleReport;
         try {
+            // recordVideo.size is in the same CSS-pixel units as viewport, not physical pixels --
+            // Playwright only ever scales a painted frame DOWN to fit the requested size, never up.
+            // Pre-multiplying this by deviceScaleFactor asks for a canvas larger than the page ever
+            // paints into, so the extra area is never filled and stays flat grey; deviceScaleFactor
+            // alone is what drives the actual (higher-resolution) pixels Chromium renders.
             const recordContext = await browser.newContext({
                 viewport: compensatedViewport,
-                recordVideo: { dir: tmpDir, size: compensatedViewport },
+                deviceScaleFactor,
+                ...(input.colorScheme ? { colorScheme: input.colorScheme } : {}),
+                ...(input.reducedMotion ? { reducedMotion: "reduce" } : {}),
+                recordVideo: {
+                    dir: tmpDir,
+                    size: compensatedViewport,
+                },
             });
+            let cursorPoints = [];
             try {
                 const page = await recordContext.newPage();
-                await page.goto(input.url, { waitUntil: "load" });
-                await (0, capture_1.replayInteractions)(page, input.interactions);
+                // Playwright's video starts recording as soon as this page exists, so this is the
+                // real zero point every cursor point's atMs gets rebased against below.
+                const recordingStartedAt = Date.now();
+                // Before navigation, same timing rule as colorScheme/reducedMotion: applied after
+                // the first paint, this would race a page that reads Math.random()/Date.now() once
+                // at load and caches the result.
+                if (input.deterministic)
+                    await (0, capture_1.installDeterminism)(page);
+                await page.goto(input.url, { waitUntil: input.waitUntil ?? "load" });
+                // Settle BEFORE the interactions, not after: the recording is already running, so
+                // this is what keeps the opening seconds of the clip from being the page still
+                // loading rather than the product working.
+                if (input.settle !== false) {
+                    settleReport = await (0, capture_1.settlePage)(page, { timeoutMs: input.settleTimeoutMs });
+                }
+                const preReplayAt = Date.now();
+                const rawCursorPoints = await (0, capture_1.replayInteractions)(page, input.interactions);
+                // replayInteractions' own atMs is relative to when IT started, not to the
+                // recording. Rebased onto recordingStartedAt here; the retiming-specific part
+                // (flat /speed, or the piecewise equivalent) is applied below, once it's known
+                // which one this call is actually using -- either way the result is directly
+                // convertible to a frame in the FINAL retimed mp4 via fps.
+                cursorPoints = rawCursorPoints.map((p) => ({
+                    ...p,
+                    atMs: preReplayAt - recordingStartedAt + p.atMs,
+                }));
                 const video = page.video();
                 if (!video) {
                     throw new Error("Playwright did not attach a Video to this page -- recordVideo may not be active.");
@@ -130,17 +321,58 @@ async function runCaptureScreenRecording(input) {
                 throw err;
             }
             fs.mkdirSync(path.dirname(outPathAbs), { recursive: true });
-            const transcodeResult = await (0, util_1.spawnCapture)("ffmpeg", buildFfmpegTranscodeArgs(webmPath, outPathAbs), projectRoot);
+            let transcodeArgs;
+            if (input.segments && input.segments.length > 0) {
+                // Piecewise retiming needs the RAW recording's real duration to fill the gaps
+                // around the caller's ranges (fillRetimeGaps) -- probed from the webm before any
+                // transcode has happened, not guessed from the beat's planned duration.
+                const rawDurationMs = await probeDurationMs(webmPath, projectRoot);
+                if (rawDurationMs === undefined) {
+                    throw new Error("segments requires probing the raw recording's real duration via ffprobe, which is unavailable " +
+                        "(ffprobe missing, or the webm couldn't be probed). Install ffprobe, or use the flat speed " +
+                        "parameter instead.");
+                }
+                validateRetimeSegments(input.segments, rawDurationMs);
+                const filled = fillRetimeGaps(input.segments, rawDurationMs);
+                transcodeArgs = buildPiecewiseRetimeArgs(webmPath, outPathAbs, filled);
+                cursorPoints = cursorPoints.map((p) => ({ ...p, atMs: remapAtMsThroughSegments(p.atMs, filled) }));
+            }
+            else {
+                transcodeArgs = buildFfmpegTranscodeArgs(webmPath, outPathAbs, speed);
+                cursorPoints = cursorPoints.map((p) => ({ ...p, atMs: p.atMs / speed }));
+            }
+            const transcodeResult = await (0, util_1.spawnCapture)("ffmpeg", transcodeArgs, projectRoot);
             if (transcodeResult.code !== 0) {
                 throw new Error(`ffmpeg webm->mp4 transcode failed (exit ${transcodeResult.code}): ${transcodeResult.stderr.slice(-1000)}`);
             }
             const durationMs = await probeDurationMs(outPathAbs, projectRoot);
+            // Otherwise the settle report only ever lived in this local variable: it was measured,
+            // then discarded when the function returned, with no evidence anywhere that a
+            // recording's opening seconds might have started before the page actually settled.
+            if (settleReport)
+                (0, capture_1.writeSettleSidecar)(outPathAbs, settleReport);
+            // Same reasoning: without this, scaffold_scene (a separate later tool call) has no
+            // real coordinates or timing to build a cursor overlay from.
+            (0, capture_1.writeCursorSidecar)(outPathAbs, compensatedViewport, cursorPoints);
+            // Same reasoning as capture_screenshot's own capture sidecar: docs_drift/release_diff
+            // need the CSS viewport actually requested, not the compensated size or a guess made
+            // from a reference frame's pixel dimensions.
+            (0, capture_1.writeCaptureSidecar)(outPathAbs, {
+                url: input.url,
+                viewport: target,
+                deviceScaleFactor,
+                zoom,
+                ...(input.interactions?.length ? { interactions: input.interactions } : {}),
+                capturedAt: new Date().toISOString(),
+            });
             return {
                 outPath: outPathAbs,
                 width: compensatedViewport.width,
                 height: compensatedViewport.height,
                 zoom,
                 ...(durationMs !== undefined ? { durationMs } : {}),
+                ...(settleReport ? { settle: settleReport } : {}),
+                ...(cursorPoints.length ? { cursorPoints } : {}),
             };
         }
         finally {
@@ -158,15 +390,37 @@ function registerCaptureScreenRecording(server) {
             "directly via the `playwright` package (not a separate Playwright MCP server). Runs the same " +
             "zoom-desync detection/compensation as capture_screenshot on a throwaway probe page first (Playwright's " +
             "recordVideo.size can only be set when the context is created, so the compensated size must be known " +
-            "before recording starts), then opens the real recording context at that compensated size, navigates, " +
+            "before recording starts), then opens the real recording context at that compensated size, navigates " +
+            "(waitUntil: \"load\" by default, same reasoning as capture_screenshot; pass \"networkidle\" only for " +
+            "a beat whose real content arrives from a delayed fetch after load), " +
             "and replays `interactions` in array order. v1 scope is fixed full-viewport recordings only -- no " +
             "post-hoc DOM-rect cropping of a moving recording, that's future work. Closing the context flushes " +
             "Playwright's webm to disk, which is then transcoded to mp4 via ffmpeg (spawn, argv array, same " +
             "discipline as render_video/qc_extract_frames) since Remotion's OffthreadVideo needs a seekable " +
-            "format; the intermediate webm and temp recording dir are cleaned up after. Default outPath is " +
+            "format -- retimed either by `speed` (one flat setpts multiplier for the whole clip) or, if `segments` " +
+            "is given instead, piecewise (trim each range to its own setpts, concat them back together via " +
+            "filter_complex, with any gap between/around your ranges auto-filled at speed 1 so nothing outside " +
+            "them is ever dropped); pass one or the other, never both. Cursor points (see below) are retimed the " +
+            "same way, so the overlay stays in sync either way. The intermediate webm and temp recording dir are " +
+            "cleaned up after. colorScheme " +
+            "(\"light\"/\"dark\") and reducedMotion (boolean) are opt-in, set on the recording context before the " +
+            "page exists so prefers-color-scheme/prefers-reduced-motion CSS is correct from the first frame. " +
+            "deterministic (boolean, default false) freezes Date.now()/new Date() and seeds Math.random() before " +
+            "the page's own scripts run -- timers/animations still run in real time, so this only helps a page " +
+            "whose content depends on the clock or Math.random(), not one whose only nondeterminism is animation " +
+            "phase. The settle report (when " +
+            "settle wasn't disabled) is both returned and written to `<outPath>.settle.json`, so validate_scenes " +
+            "can flag a timed-out beat without a browser. Every click/hover/fill/select interaction's real target " +
+            "center is also measured during replay and written to `<outPath>.cursor.json`, with its timing " +
+            "rebased onto the recording's own start (navigation+settle time added back in) and compressed by " +
+            "`speed`, so it lands on the right frame of the FINAL retimed mp4 -- this is what lets scaffold_scene " +
+            "sync a cursor overlay to what the video is actually doing at that moment, instead of a hand-drawn " +
+            "guess. Default outPath is " +
             "public/video/<beatId>.mp4 under projectRoot, matching scaffold_scene's real-recording convention. " +
-            "Returns { outPath, width, height, zoom, durationMs? } -- durationMs is a best-effort ffprobe lookup, " +
-            "omitted (not failed) if ffprobe isn't available. Requires Chromium to be installed for Playwright " +
+            "Returns { outPath, width, height, zoom, durationMs?, settle?, cursorPoints? } -- durationMs is a " +
+            "best-effort ffprobe lookup, " +
+            "omitted (not failed) if ffprobe isn't available; cursorPoints the same real, retimed coordinates " +
+            "written to the sidecar (omitted when there were none). Requires Chromium to be installed for Playwright " +
             "first: run \"npx playwright install chromium\" once wherever this package is installed; a missing " +
             "browser fails with a message telling you to do exactly that, not a cryptic native error.",
         inputSchema: {
@@ -174,8 +428,52 @@ function registerCaptureScreenRecording(server) {
             beatId: zod_1.z.string().min(1),
             url: zod_1.z.string().min(1),
             viewport: capture_1.viewportSchema.optional(),
+            settle: zod_1.z
+                .boolean()
+                .optional()
+                .describe("Settle the page before recording starts, so the opening second is the product working rather than the page still loading. Defaults to true."),
+            settleTimeoutMs: zod_1.z.number().int().positive().optional(),
+            waitUntil: zod_1.z
+                .enum(["load", "networkidle"])
+                .optional()
+                .describe("Navigation wait condition. Defaults to \"load\" (a dev server's open websocket would never hit " +
+                "networkidle). Pass \"networkidle\" for a beat whose real content arrives from a delayed fetch."),
+            speed: zod_1.z
+                .number()
+                .positive()
+                .optional()
+                .describe("Replay rate. 2 is twice as fast, 0.5 is half speed. Defaults to 1. Use it when real interaction is too slow to watch or too quick to follow. Mutually exclusive with segments."),
+            segments: zod_1.z
+                .array(zod_1.z.object({
+                startMs: zod_1.z.number().nonnegative(),
+                endMs: zod_1.z.number().positive(),
+                speed: zod_1.z.number().positive(),
+            }))
+                .optional()
+                .describe("Piecewise alternative to speed: non-overlapping { startMs, endMs, speed } ranges against the raw " +
+                "recording's own timeline, for one clip with one slow stretch and one fast stretch. Gaps " +
+                "between/around the ranges play at speed 1 automatically. Mutually exclusive with speed."),
+            deviceScaleFactor: zod_1.z
+                .number()
+                .positive()
+                .optional()
+                .describe("Pixels recorded per CSS pixel. Defaults to 2, which keeps the footage sharp once the camera pushes in."),
             interactions: zod_1.z.array(capture_1.interactionSchema).optional(),
             outPath: zod_1.z.string().optional(),
+            colorScheme: zod_1.z
+                .enum(["light", "dark"])
+                .optional()
+                .describe("Emulate a color scheme, set at context creation before the page exists. Omit for the page's own default."),
+            reducedMotion: zod_1.z
+                .boolean()
+                .optional()
+                .describe("Emulate prefers-reduced-motion: reduce for the recording context. Off by default."),
+            deterministic: zod_1.z
+                .boolean()
+                .optional()
+                .describe("Freeze Date.now()/new Date() and seed Math.random() before the page runs, so a page whose " +
+                "content depends on either records identically every run. Off by default. Timers/animations " +
+                "still run in real time -- pair with settle/reducedMotion for animation-phase determinism."),
         },
     }, async (input) => (0, mcp_1.runTool)("capture_screen_recording", () => runCaptureScreenRecording(input)));
 }