creavit-studio-mcp 1.1.0 → 1.2.0

package/README.md

@@ -50,14 +50,14 @@ npx creavit-studio-mcp --doctor
 ```
 
 ```
-creavit-studio v1.1.0
+creavit-studio v1.2.0
 
-✓ 46 MCP tools defined
+✓ 50 MCP tools defined
 ✓ Offline project reading available (.crvt files readable without the app)
 ✓ Connected to the app (v3.0.5, pid 61068)
   Open windows: 2
   Agent-connected renderers: main, editor
-✓ 52 bridge commands available
+✓ 56 bridge commands available
 
 Everything looks good.
 ```
@@ -121,8 +121,9 @@ files directly and work with the app closed.
 **Recording** — `creavit_devices_list`, `creavit_recording_status`,
 `creavit_recording_start`, `creavit_recording_stop`
 
-**Browser walkthrough** — `creavit_browser_open`, `creavit_browser_scroll`,
-`creavit_record_url_walkthrough`
+**Browser walkthrough** — `creavit_browser_open`, `creavit_browser_inspect`,
+`creavit_browser_focus`, `creavit_browser_interact`, `creavit_browser_scroll`,
+`creavit_browser_close`, `creavit_record_url_walkthrough`
 
 **Escape hatches** — `creavit_capabilities`, `creavit_call`, `creavit_ipc`,
 `creavit_eval`, `creavit_logs`
@@ -163,13 +164,18 @@ timeline volume, so the saved project also exports without source audio.
 
 ### Record a URL walkthrough
 
-`creavit_record_url_walkthrough` is the high-level workflow. It opens the URL,
-selects that browser window, records a smooth section-by-section scroll, opens
-the generated project, adds scroll-highlight zooms, optionally covers the whole
-video with a perspective preset, mutes it, and saves it.
-
-When the calling agent has inspected the page, it can pass `sections` entries
-(`scrollPages`, `dwellMs`, `zoom`, `scale`, `x`, `y`) to dwell on and frame the
+`creavit_record_url_walkthrough` is the high-level workflow. By default it opens
+the URL in a frameless site-only capture window (`16:9`, `4:3`, `1:1`, `9:16`,
+or another requested ratio) and waits for the DOM, fonts, and images before
+recording. It then executes ordered semantic actions with the real macOS mouse,
+so the normal Creavit custom-cursor track receives authentic move/click events.
+It trims the timeline to `durationMs`, adds
+scroll-highlight zooms, optionally covers the whole video with a perspective
+preset, mutes it, and saves it.
+
+When the calling agent has inspected the page, it can pass ordered `steps`
+(`scrollPages`, `dwellMs`, `zoom`, `scale`, `x`, `y`, and optionally
+`selector`/`text` plus `action`) to dwell on, hover, click, type, and frame the
 important parts instead of using the generic evenly spaced scroll plan.
 
 Example input:
@@ -177,9 +183,15 @@ Example input:
 ```json
 {
   "url": "https://example.com",
-  "browser": "Zen Browser",
-  "scrollCount": 5,
-  "scrollIntervalMs": 1800,
+  "cleanWindow": true,
+  "aspectRatio": "4:3",
+  "durationMs": 10000,
+  "steps": [
+    { "action": "click", "text": "Features", "dwellMs": 1000 },
+    { "action": "scrollTo", "text": "Get Started", "dwellMs": 700 },
+    { "action": "click", "text": "Get Started", "dwellMs": 3000 }
+  ],
+  "controlSystemMouse": true,
   "autoZoom": true,
   "zoomScale": 1.8,
   "perspective": true,
@@ -208,8 +220,9 @@ Two things worth knowing:
 - Every request requires a bearer token, regenerated on each app launch.
 - The endpoint file is written with `0600` permissions.
 - Arbitrary code execution (`creavit_eval`) is **off by default**.
-- Browser scrolling uses macOS Accessibility. Enable Creavit Studio under
-  **System Settings → Privacy & Security → Accessibility** when macOS asks.
+- Page loading and scrolling inside a clean capture window do not require
+  Accessibility permission. Real system mouse move/click automation and
+  external-browser scrolling do require macOS Accessibility permission.
 
 ### Environment variables
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "creavit-studio-mcp",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"description": "MCP server that lets AI coding agents (Claude Code, Codex, Cursor) drive the Creavit Studio screen recording app",
 	"keywords": [
 		"mcp",

package/src/protocol.mjs

@@ -6,7 +6,7 @@ export const ENDPOINT_FILENAME = "agent-bridge.json";
 
 export const MCP_PROTOCOL_VERSION = "2024-11-05";
 export const SERVER_NAME = "creavit-studio";
-export const SERVER_VERSION = "1.1.0";
+export const SERVER_VERSION = "1.2.0";
 
 export const JSONRPC_ERRORS = {
 	PARSE_ERROR: -32700,

package/src/tools/browserTools.mjs

@@ -1,4 +1,4 @@
-// MCP araçları — tarayıcı açma/scroll ve uçtan uca URL walkthrough kaydı.
+// MCP tools — deterministic website walkthrough recording and browser control.
 
 import { bridgeTool, schema, S, textResult } from "./defineTool.mjs";
 import { callCommand } from "../bridgeClient.mjs";
@@ -29,31 +29,27 @@ function windowList(result) {
 }
 
 function searchableWindowText(windowInfo) {
-	return [
-		windowInfo?.appName,
-		windowInfo?.ownerName,
-		windowInfo?.name,
-		windowInfo?.title,
-		windowInfo?.windowTitle,
-	]
+	return [windowInfo?.appName, windowInfo?.ownerName, windowInfo?.name, windowInfo?.title, windowInfo?.windowTitle]
 		.filter(Boolean)
 		.join(" ")
 		.toLowerCase();
 }
 
 function findBrowserWindow(windows, browserName, titleContains) {
-	const browserNeedle = String(browserName || "").toLowerCase();
 	const titleNeedle = String(titleContains || "").trim().toLowerCase();
+	if (titleNeedle) {
+		const exactCapture = windows.find(
+			(entry) => Number(entry?.id) > 0 && searchableWindowText(entry).includes(titleNeedle),
+		);
+		if (exactCapture) return exactCapture;
+	}
+	const browserNeedle = String(browserName || "").toLowerCase();
 	const candidates = windows.filter((entry) => {
 		const text = searchableWindowText(entry);
 		return text.includes(browserNeedle) ||
 			(browserNeedle === "google chrome" && text.includes("chrome")) ||
 			(browserNeedle === "zen browser" && text.includes("zen"));
 	});
-	if (titleNeedle) {
-		const titled = candidates.find((entry) => searchableWindowText(entry).includes(titleNeedle));
-		if (titled) return titled;
-	}
 	return candidates.find((entry) => entry?.isOnScreen !== false && Number(entry?.id) > 0) ||
 		candidates.find((entry) => Number(entry?.id) > 0) ||
 		null;
@@ -71,29 +67,34 @@ async function waitForBrowserWindow(browserName, titleContains, timeoutMs) {
 	}
 	throw new Error(
 		`Could not find a recordable ${browserName} window. Opened windows: ${lastWindows
-			.map((entry) => searchableWindowText(entry))
-			.filter(Boolean)
-			.slice(0, 12)
-			.join(" | ")}`,
+			.map((entry) => searchableWindowText(entry)).filter(Boolean).slice(0, 12).join(" | ")}`,
 	);
 }
 
-async function waitForEditor(timeoutMs = 300_000) {
+async function readEditorState() {
+	try {
+		return await callCommand("editor.getState", {}, 15_000);
+	} catch (_) {
+		return null;
+	}
+}
+
+async function waitForEditor(previousProjectFilePath, timeoutMs = 300_000) {
 	const deadline = Date.now() + timeoutMs;
 	let lastError = null;
 	while (Date.now() < deadline) {
 		try {
 			const state = await callCommand("editor.getState", {}, 15_000);
-			if (Number(state?.duration) > 0 && state?.playerMounted) return state;
+			const isNewProject = !previousProjectFilePath ||
+				(state?.projectFilePath && state.projectFilePath !== previousProjectFilePath);
+			if (Number(state?.duration) > 0 && state?.playerMounted && isNewProject) return state;
 		} catch (error) {
 			lastError = error;
 		}
 		await sleep(1000);
 	}
 	throw new Error(
-		`Recording finished but the editor did not become ready within ${Math.round(timeoutMs / 1000)}s${
-			lastError ? `: ${lastError.message}` : ""
-		}`,
+		`Recording finished but the new project did not become ready within ${Math.round(timeoutMs / 1000)}s${lastError ? `: ${lastError.message}` : ""}`,
 	);
 }
 
@@ -106,66 +107,139 @@ async function clearZooms() {
 	return ranges.length;
 }
 
+function trimSegmentsToDuration(segments, targetDuration) {
+	return segments
+		.map((segment) => {
+			const timelineStart = Number(segment.timelineStart ?? segment.start ?? segment.startTime ?? 0);
+			const timelineEnd = Number(segment.timelineEnd ?? segment.end ?? segment.endTime ?? timelineStart);
+			if (!Number.isFinite(timelineStart) || timelineStart >= targetDuration || timelineEnd <= timelineStart) return null;
+			if (timelineEnd <= targetDuration) return segment;
+			const clippedTimelineEnd = targetDuration;
+			const timelineSpan = Math.max(0.0001, timelineEnd - timelineStart);
+			const videoStart = Number(segment.videoStart ?? segment.startTime ?? 0);
+			const videoEnd = Number(segment.videoEnd ?? segment.endTime ?? videoStart + timelineSpan);
+			const ratio = Math.max(0, videoEnd - videoStart) / timelineSpan;
+			const clippedVideoEnd = videoStart + (clippedTimelineEnd - timelineStart) * ratio;
+			return {
+				...segment,
+				timelineEnd: clippedTimelineEnd,
+				end: clippedTimelineEnd,
+				duration: clippedTimelineEnd - timelineStart,
+				videoEnd: clippedVideoEnd,
+				videoDuration: clippedVideoEnd - videoStart,
+				endTime: clippedVideoEnd,
+				sourceVideoEnd: clippedVideoEnd,
+			};
+		})
+		.filter(Boolean);
+}
+
 export function browserTools() {
 	return [
 		bridgeTool({
 			name: "creavit_browser_open",
 			command: "browser.open",
 			description:
-				"Opens an http(s) URL in Zen Browser, Safari, Chrome, Arc, Firefox, Brave, or the default browser.",
+				"Opens an http(s) URL. Set cleanWindow=true for an isolated frameless capture window; it waits for DOM, fonts, and images before returning.",
 			inputSchema: schema(
 				{
 					url: S.string("http(s) URL to open"),
-					browser: S.string("Browser name (default: system browser)"),
+					browser: S.string("External browser name when cleanWindow is false"),
+					cleanWindow: S.bool("Open an isolated site-only capture window"),
+					aspectRatio: S.string("Capture ratio such as 16:9, 4:3, 1:1, or 9:16 (default 16:9)"),
+					width: S.number("Optional capture content width; height is derived from aspectRatio"),
+					height: S.number("Optional capture content height when width is omitted"),
+					loadWaitMs: S.number("Extra settle time after DOM/fonts/images load (default 1200)"),
 				},
 				["url"],
 			),
 		}),
 
 		bridgeTool({
-			name: "creavit_browser_scroll",
-			command: "browser.scroll",
-			description:
-				"Activates a browser and scrolls by page. Useful while recording. Requires macOS Accessibility permission for Creavit Studio.",
+			name: "creavit_browser_inspect",
+			command: "browser.inspect",
+			description: "Lists headings and interactive elements in a clean capture window so an agent can choose meaningful focus/click targets.",
+			inputSchema: schema(
+				{ captureWindowId: S.number("ID returned by creavit_browser_open"), limit: S.number("Maximum elements (default 80)") },
+				["captureWindowId"],
+			),
+		}),
+
+		bridgeTool({
+			name: "creavit_browser_focus",
+			command: "browser.focusPoint",
+			description: "Smoothly moves the real macOS system mouse to a normalized page point, so Creavit records its native custom-cursor data.",
+			inputSchema: schema(
+				{ captureWindowId: S.number("Capture window ID"), x: S.number("Horizontal position, 0..1"), y: S.number("Vertical position, 0..1"), durationMs: S.number("Mouse travel duration (default 520)"), click: S.bool("Perform a real left click after moving") },
+				["captureWindowId", "x", "y"],
+			),
+		}),
+
+		bridgeTool({
+			name: "creavit_browser_interact",
+			command: "browser.interact",
+			description: "Finds a page element by CSS selector or visible text, scrolls to it, moves the real system mouse, and performs a real hover/click/type action.",
 			inputSchema: schema(
 				{
-					browser: S.string("Zen Browser, Safari, Google Chrome, Arc, Firefox, or Brave Browser"),
-					direction: S.string("Scroll direction", {
-						enum: ["down", "up", "top", "bottom"],
-					}),
-					style: S.string("page or smooth (smooth uses small animated steps)", {
-						enum: ["page", "smooth"],
-					}),
-					count: S.number("Number of page-key presses (1-50)"),
-					intervalMs: S.number("Pause after each press in milliseconds"),
+					captureWindowId: S.number("Capture window ID"),
+					action: S.string("Interaction", { enum: ["hover", "click", "type", "scrollIntoView", "scrollTo"] }),
+					selector: S.string("CSS selector"),
+					text: S.string("Visible text fallback"),
+					value: S.string("Text to enter for type"),
+					moveDurationMs: S.number("Real mouse travel duration (default 520)"),
 				},
-				["browser"],
+				["captureWindowId", "action"],
 			),
 		}),
 
+		bridgeTool({
+			name: "creavit_browser_scroll",
+			command: "browser.scroll",
+			description: "Scrolls a clean capture window directly, or activates and scrolls an external browser.",
+			inputSchema: schema({
+				captureWindowId: S.number("Clean capture window ID; preferred over browser"),
+				browser: S.string("External browser name"),
+				direction: S.string("Scroll direction", { enum: ["down", "up", "top", "bottom"] }),
+				style: S.string("page or smooth", { enum: ["page", "smooth"] }),
+				count: S.number("Number of scroll steps (1-50)"),
+				intervalMs: S.number("Time for each scroll step in milliseconds"),
+			}),
+		}),
+
+		bridgeTool({
+			name: "creavit_browser_close",
+			command: "browser.close",
+			description: "Closes an isolated clean capture window.",
+			inputSchema: schema({ captureWindowId: S.number("Capture window ID") }, ["captureWindowId"]),
+		}),
+
 		{
 			name: "creavit_record_url_walkthrough",
 			description:
-				"End-to-end website recording: opens a URL, finds that browser window, records it while scrolling, opens the result in Creavit Studio, optionally replaces zooms with automatic scroll-highlight zooms, applies a full-video perspective, and guarantees a muted export timeline. This operation can take several minutes.",
+				"Records a site in a clean configurable-ratio window after real page readiness. It can execute ordered semantic steps using the real system mouse, trims to an exact duration, adds zooms, optional perspective, and optionally mutes it.",
 			inputSchema: schema(
 				{
 					url: S.string("http(s) page to record"),
-					browser: S.string("Browser to use (default: Zen Browser)"),
-					titleContains: S.string("Optional browser window title hint"),
-					loadWaitMs: S.number("Wait for the page to load before recording (default 3000)"),
-					leadInMs: S.number("Still time at the top before scrolling (default 1500)"),
-					scrollCount: S.number("Number of Page Down scrolls (default 4, max 20)"),
-					scrollIntervalMs: S.number("Time between scrolls / section dwell (default 1800)"),
-					sections: S.array(
-						"Optional agent-planned important sections. Each item: {scrollPages,dwellMs,zoom,scale,x,y}. Replaces scrollCount when present.",
-						{ type: "object" },
-					),
-					tailMs: S.number("Still time after the last scroll (default 1500)"),
-					mute: S.bool("Disable microphone/system audio and mute all export clips (default true)"),
-					autoZoom: S.bool("Add zooms around scroll destinations (default true)"),
+					browser: S.string("External browser fallback (default Zen Browser)"),
+					cleanWindow: S.bool("Use a frameless site-only capture window (default true)"),
+					aspectRatio: S.string("Capture ratio: 16:9, 4:3, 1:1, 9:16, or another W:H value"),
+					width: S.number("Optional capture content width; height is derived from aspectRatio"),
+					height: S.number("Optional capture content height when width is omitted"),
+					titleContains: S.string("Optional native window title hint"),
+					loadWaitMs: S.number("Extra settle time after real page readiness (default 1500)"),
+					durationMs: S.number("Exact final timeline duration in milliseconds"),
+					leadInMs: S.number("Still time before scrolling (default 1000)"),
+					scrollCount: S.number("Number of smooth page scrolls (default 4, max 20)"),
+					scrollIntervalMs: S.number("Dwell after each section (default 1400)"),
+					steps: S.array("Ordered actions: {action:'click|hover|scrollTo|scroll|wait|type',selector?,text?,value?,scrollPages?,dwellMs?,zoom?,scale?,x?,y?}", { type: "object" }),
+					sections: S.array("Deprecated alias for steps", { type: "object" }),
+					tailMs: S.number("Still time after the last scroll (default 800)"),
+					controlSystemMouse: S.bool("Move/click the real macOS mouse so Creavit records native cursor data (default true)"),
+					mute: S.bool("Disable recording audio and mute export clips (default true)"),
+					autoZoom: S.bool("Add zooms around section destinations (default true)"),
 					replaceZooms: S.bool("Remove recorder-created zooms first (default true)"),
 					zoomScale: S.number("Automatic zoom scale (default 1.7)"),
-					perspective: S.bool("Apply perspective to the complete result (default false)"),
+					perspective: S.bool("Apply perspective to the complete result"),
 					perspectiveTemplate: S.string("Perspective template id (default minimal-tilt)"),
 					save: S.bool("Save the generated project after editing (default true)"),
 				},
@@ -173,163 +247,185 @@ export function browserTools() {
 			),
 			run: async (args) => {
 				const browser = canonicalBrowser(args.browser || "Zen Browser");
-				const loadWaitMs = Math.max(500, Math.min(60_000, Number(args.loadWaitMs) || 3000));
-				const leadInMs = Math.max(300, Math.min(30_000, Number(args.leadInMs) || 1500));
-				const scrollCount = Math.max(
-					0,
-					Math.min(20, Math.round(args.scrollCount === undefined ? 4 : Number(args.scrollCount))),
-				);
-				const scrollIntervalMs = Math.max(
-					400,
-					Math.min(15_000, Number(args.scrollIntervalMs) || 1800),
-				);
-				const tailMs = Math.max(300, Math.min(30_000, Number(args.tailMs) || 1500));
+				const cleanWindow = args.cleanWindow !== false;
+				const loadWaitMs = Math.max(0, Math.min(60_000, Number(args.loadWaitMs) || 1500));
+				const durationMs = args.durationMs === undefined ? null : Math.max(1000, Math.min(3_600_000, Number(args.durationMs) || 10_000));
+				const leadInMs = Math.max(200, Math.min(30_000, Number(args.leadInMs) || 1000));
+				const scrollCount = Math.max(0, Math.min(20, Math.round(args.scrollCount === undefined ? 4 : Number(args.scrollCount))));
+				const scrollIntervalMs = Math.max(300, Math.min(15_000, Number(args.scrollIntervalMs) || 1400));
+				const tailMs = Math.max(200, Math.min(30_000, Number(args.tailMs) || 800));
 				const muted = args.mute !== false;
 				const autoZoom = args.autoZoom !== false;
 				const replaceZooms = args.replaceZooms !== false;
+				const controlSystemMouse = args.controlSystemMouse !== false;
 				const zoomScale = Math.max(1, Math.min(5, Number(args.zoomScale) || 1.7));
-				const sectionPlan = Array.isArray(args.sections) && args.sections.length
-					? args.sections.slice(0, 20).map((section) => {
-							const scrollPages = Number(section?.scrollPages);
-							const focusX = Number(section?.x);
-							const focusY = Number(section?.y);
-							return {
-								scrollPages: Math.max(
-									0,
-									Math.min(
-										5,
-										Math.round(Number.isFinite(scrollPages) ? scrollPages : 1),
-									),
-								),
-								dwellMs: Math.max(
-									400,
-									Math.min(15_000, Number(section?.dwellMs) || scrollIntervalMs),
-								),
-								zoom: section?.zoom !== false,
-								scale: Math.max(
-									1,
-									Math.min(5, Number(section?.scale) || zoomScale),
-								),
-								x: Math.max(
-									0,
-									Math.min(1, Number.isFinite(focusX) ? focusX : 0.5),
-								),
-								y: Math.max(
-									0,
-									Math.min(1, Number.isFinite(focusY) ? focusY : 0.5),
-								),
-							};
-						})
+				const requestedSteps = Array.isArray(args.steps) && args.steps.length ? args.steps : args.sections;
+				const sectionPlan = Array.isArray(requestedSteps) && requestedSteps.length
+					? requestedSteps.slice(0, 30).map((section) => {
+						const action = section?.action || (section?.selector || section?.text ? "hover" : "scroll");
+						const defaultScrollPages = action === "scroll" ? 1 : 0;
+						return {
+						action,
+						scrollPages: Math.max(0, Math.min(5, Math.round(Number.isFinite(Number(section?.scrollPages)) ? Number(section.scrollPages) : defaultScrollPages))),
+						dwellMs: Math.max(300, Math.min(15_000, Number(section?.dwellMs) || scrollIntervalMs)),
+						zoom: section?.zoom !== false,
+						scale: Math.max(1, Math.min(5, Number(section?.scale) || zoomScale)),
+						x: Math.max(0.01, Math.min(0.99, Number.isFinite(Number(section?.x)) ? Number(section.x) : 0.5)),
+						y: Math.max(0.01, Math.min(0.99, Number.isFinite(Number(section?.y)) ? Number(section.y) : 0.48)),
+						selector: section?.selector || null,
+						text: section?.text || null,
+						value: section?.value || "",
+					};
+					})
 					: Array.from({ length: scrollCount }, (_, index) => ({
-							scrollPages: 1,
-							dwellMs: scrollIntervalMs,
-							zoom: true,
-							scale: zoomScale,
-							x: index % 2 === 0 ? 0.42 : 0.58,
-							y: 0.5,
-						}));
+						scrollPages: 1,
+						dwellMs: scrollIntervalMs,
+						zoom: true,
+						scale: zoomScale,
+						x: index % 2 === 0 ? 0.42 : 0.58,
+						y: 0.48,
+						selector: null,
+						text: null,
+						action: "hover",
+						value: "",
+					}));
 
-				await callCommand("browser.open", { url: args.url, browser }, 30_000);
-				await sleep(loadWaitMs);
-				await callCommand("browser.scroll", { browser, direction: "top", style: "page", count: 1, intervalMs: 100 });
-				const browserWindow = await waitForBrowserWindow(browser, args.titleContains, 20_000);
+				const previousEditor = await readEditorState();
+				let captureWindowId = null;
+				let recordingStarted = false;
+				let openResult;
+				const zoomWindows = [];
+				try {
+					openResult = await callCommand("browser.open", {
+						url: args.url,
+						browser,
+						cleanWindow,
+						aspectRatio: args.aspectRatio || "16:9",
+						width: Number.isFinite(Number(args.width)) ? Number(args.width) : undefined,
+						height: Number.isFinite(Number(args.height)) ? Number(args.height) : undefined,
+						loadWaitMs,
+					}, 90_000);
+					captureWindowId = openResult?.captureWindowId ?? null;
+					const titleHint = openResult?.windowTitle || args.titleContains;
+					if (!cleanWindow) await sleep(loadWaitMs);
+					await callCommand("browser.scroll", {
+						captureWindowId,
+						browser: captureWindowId ? undefined : browser,
+						direction: "top",
+						style: "page",
+						count: 1,
+						intervalMs: 150,
+					});
+					if (captureWindowId && controlSystemMouse) {
+						await callCommand("browser.focusPoint", { captureWindowId, x: 0.5, y: 0.46 });
+					}
+					const browserWindow = await waitForBrowserWindow(captureWindowId ? "Creavit Studio" : browser, titleHint, 20_000);
 
-				await callCommand(
-					"recording.start",
-					{
+					await callCommand("recording.start", {
 						options: {
 							startScreen: true,
 							cameraEnabled: false,
 							micEnabled: !muted,
 							systemAudioEnabled: !muted,
-							recordingSource: {
-								type: "window",
-								windowId: browserWindow.id,
-								windowInfo: browserWindow,
-							},
+							recordingSource: { type: "window", windowId: browserWindow.id, windowInfo: browserWindow },
 						},
-					},
-					180_000,
-				);
+					}, 180_000);
+					recordingStarted = true;
+					const recordingStartedAt = Date.now();
+					const contentDeadline = durationMs ? recordingStartedAt + durationMs - tailMs : Number.POSITIVE_INFINITY;
+					await sleep(Math.min(leadInMs, Math.max(0, contentDeadline - Date.now())));
 
-				const recordingStartedAt = Date.now();
-				const zoomWindows = [];
-				await sleep(leadInMs);
-				for (let index = 0; index < sectionPlan.length; index += 1) {
-					const section = sectionPlan[index];
-					if (section.scrollPages > 0) {
-						await callCommand(
-							"browser.scroll",
-							{
-								browser,
-								direction: "down",
-								style: "smooth",
-								count: section.scrollPages,
-								intervalMs: 120,
-							},
-							30_000,
-						);
+					for (const section of sectionPlan) {
+						if (Date.now() >= contentDeadline) break;
+						let focus = { x: section.x, y: section.y };
+						if (section.action === "wait") {
+							// Dwell-only step; the current page and cursor stay untouched.
+						} else if (captureWindowId && (section.selector || section.text)) {
+							const interaction = await callCommand("browser.interact", {
+								captureWindowId,
+								action: section.action === "scrollTo" ? "scrollTo" : section.action,
+								selector: section.selector,
+								text: section.text,
+								value: section.value,
+							}, 30_000);
+							if (Number.isFinite(interaction?.x)) focus = { x: interaction.x, y: interaction.y };
+						} else {
+							if (section.scrollPages > 0) {
+								await callCommand("browser.scroll", {
+									captureWindowId,
+									browser: captureWindowId ? undefined : browser,
+									direction: "down",
+									style: "smooth",
+									count: section.scrollPages,
+									intervalMs: 650,
+								}, 30_000);
+							}
+							if (captureWindowId && controlSystemMouse) {
+								await callCommand("browser.focusPoint", { captureWindowId, x: focus.x, y: focus.y });
+							}
+						}
+						const arrivedAt = (Date.now() - recordingStartedAt) / 1000;
+						const dwell = Math.min(section.dwellMs, Math.max(0, contentDeadline - Date.now()));
+						if (section.zoom && dwell >= 250) {
+							zoomWindows.push({ start: Math.max(0, arrivedAt + 0.08), end: Math.max(arrivedAt + 0.3, arrivedAt + dwell / 1000 - 0.08), scale: section.scale, x: focus.x, y: focus.y });
+						}
+						if (dwell > 0) await sleep(dwell);
 					}
-					const arrivedAt = (Date.now() - recordingStartedAt) / 1000;
-					if (section.zoom) {
-						zoomWindows.push({
-							start: Math.max(0, arrivedAt + 0.12),
-							end: Math.max(0.5, arrivedAt + section.dwellMs / 1000 - 0.12),
-							scale: section.scale,
-							x: section.x,
-							y: section.y,
-						});
+					if (durationMs) {
+						const stopAt = recordingStartedAt + durationMs + 1500;
+						if (Date.now() < stopAt) await sleep(stopAt - Date.now());
+					} else {
+						await sleep(tailMs);
 					}
-					await sleep(section.dwellMs);
-				}
-				await sleep(tailMs);
-				await callCommand("recording.stop", {}, 600_000);
+					await callCommand("recording.stop", {}, 600_000);
+					recordingStarted = false;
 
-				const editorState = await waitForEditor(600_000);
-				const applied = { muted: false, zooms: [], perspective: null, saved: false };
-
-				if (muted) {
-					await callCommand("editor.setMuted", { muted: true });
-					applied.muted = true;
-				}
-				if (autoZoom) {
-					if (replaceZooms) applied.removedZooms = await clearZooms();
-					for (let index = 0; index < zoomWindows.length; index += 1) {
-						const window = zoomWindows[index];
-						const start = Math.min(window.start, Math.max(0, editorState.duration - 0.25));
-						const end = Math.min(window.end, editorState.duration);
-						if (end - start < 0.25) continue;
-						const result = await callCommand("editor.addZoom", {
-							start,
-							end,
-							scale: window.scale,
-							x: window.x,
-							y: window.y,
-						});
-						applied.zooms.push(result?.added || result);
+					const editorState = await waitForEditor(previousEditor?.projectFilePath, 600_000);
+					const applied = { muted: false, zooms: [], perspective: null, saved: false, trimmedTo: null };
+					let finalDuration = Number(editorState.duration);
+					if (durationMs) {
+						const targetDuration = durationMs / 1000;
+						const listed = await callCommand("editor.listSegments", {});
+						const segments = Array.isArray(listed?.segments) ? listed.segments : [];
+						const trimmed = trimSegmentsToDuration(segments, targetDuration);
+						if (!trimmed.length || finalDuration + 0.02 < targetDuration) {
+							throw new Error(`Recording was too short for the requested ${targetDuration}s timeline (captured ${finalDuration}s)`);
+						}
+						await callCommand("editor.setSegments", { segments: trimmed });
+						finalDuration = targetDuration;
+						applied.trimmedTo = targetDuration;
+					}
+					if (muted) {
+						await callCommand("editor.setMuted", { muted: true });
+						applied.muted = true;
+					}
+					if (autoZoom) {
+						if (replaceZooms) applied.removedZooms = await clearZooms();
+						for (const zoomWindow of zoomWindows) {
+							const start = Math.min(zoomWindow.start, Math.max(0, finalDuration - 0.25));
+							const end = Math.min(zoomWindow.end, finalDuration);
+							if (end - start < 0.25) continue;
+							const result = await callCommand("editor.addZoom", { start, end, scale: zoomWindow.scale, x: zoomWindow.x, y: zoomWindow.y });
+							applied.zooms.push(result?.added || result);
+						}
+					}
+					if (args.perspective === true) {
+						const result = await callCommand("editor.addPerspective", { fullDuration: true, templateId: args.perspectiveTemplate || "minimal-tilt" });
+						applied.perspective = result?.added || result;
+					}
+					if (args.save !== false) {
+						await callCommand("editor.saveProject", {}, 180_000);
+						applied.saved = true;
+					}
+					return textResult({ ok: true, url: args.url, browser: cleanWindow ? "Creavit Capture" : browser, cleanWindow, page: openResult, window: browserWindow, duration: finalDuration, rawDuration: editorState.duration, projectFilePath: editorState.projectFilePath, applied });
+				} finally {
+					if (recordingStarted) {
+						try { await callCommand("recording.stop", {}, 600_000); } catch (_) {}
+					}
+					if (captureWindowId) {
+						try { await callCommand("browser.close", { captureWindowId }); } catch (_) {}
 					}
 				}
-				if (args.perspective === true) {
-					const result = await callCommand("editor.addPerspective", {
-						fullDuration: true,
-						templateId: args.perspectiveTemplate || "minimal-tilt",
-					});
-					applied.perspective = result?.added || result;
-				}
-				if (args.save !== false) {
-					await callCommand("editor.saveProject", {}, 180_000);
-					applied.saved = true;
-				}
-
-				return textResult({
-					ok: true,
-					url: args.url,
-					browser,
-					window: browserWindow,
-					duration: editorState.duration,
-					projectFilePath: editorState.projectFilePath,
-					applied,
-				});
 			},
 		},
 	];