creavit-studio-mcp 1.1.0 → 1.2.1

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.1",
 	"description": "MCP server that lets AI coding agents (Claude Code, Codex, Cursor) drive the Creavit Studio screen recording app",
 	"keywords": [
 		"mcp",

package/src/appLauncher.mjs

@@ -0,0 +1,104 @@
+// MCP sunucusu — uygulama kapalıysa başlatma.
+//
+// Köprü yalnızca uygulama çalışırken vardır. Ajanın "önce uygulamayı sen aç"
+// diyememesi her oturumun başında elle müdahale gerektiriyordu. Burası
+// uygulamayı bulur, açar ve köprü hazır olana kadar bekler.
+
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const APP_BUNDLE_NAME = "Creavit Studio.app";
+
+const DEFAULT_APP_PATHS = [
+	path.join("/Applications", APP_BUNDLE_NAME),
+	path.join(os.homedir(), "Applications", APP_BUNDLE_NAME),
+];
+
+/** Açılışın tamamlanması için verilen süre; soğuk başlangıç yavaş olabilir. */
+export const DEFAULT_LAUNCH_TIMEOUT_MS = 45_000;
+const POLL_INTERVAL_MS = 500;
+
+export class AppLaunchError extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "AppLaunchError";
+	}
+}
+
+/** Uygulama paketinin yolu: env override > /Applications > ~/Applications */
+export function resolveAppPath() {
+	const fromEnv = process.env.CREAVIT_APP_PATH;
+	const candidates = fromEnv ? [fromEnv, ...DEFAULT_APP_PATHS] : DEFAULT_APP_PATHS;
+
+	for (const candidate of candidates) {
+		try {
+			if (candidate && fs.existsSync(candidate)) return candidate;
+		} catch (_) {}
+	}
+	return null;
+}
+
+/** Otomatik başlatma kapatılabilir olmalı (CI, kısıtlı ortam). */
+export function isAutoLaunchEnabled() {
+	return process.env.CREAVIT_MCP_AUTOLAUNCH !== "0";
+}
+
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Uygulamayı açar (beklemez). macOS'ta `open` kullanılır: zaten açıksa yeni
+ * kopya başlatmaz, kapalıysa başlatır.
+ */
+export function launchApp() {
+	if (process.platform !== "darwin") {
+		throw new AppLaunchError(
+			"Automatic launch is only supported on macOS. Start Creavit Studio manually.",
+		);
+	}
+
+	const appPath = resolveAppPath();
+	if (!appPath) {
+		throw new AppLaunchError(
+			`Could not find ${APP_BUNDLE_NAME} in /Applications or ~/Applications. ` +
+				"Set CREAVIT_APP_PATH to the bundle path, or start the app manually.",
+		);
+	}
+
+	const child = spawn("open", ["-a", appPath], {
+		detached: true,
+		stdio: "ignore",
+	});
+	child.unref();
+	return appPath;
+}
+
+/**
+ * Uygulama çalışmıyorsa başlatır ve köprü yanıt verene kadar bekler.
+ *
+ * @param {object} options
+ * @param {() => Promise<boolean>} options.isRunning Köprü sağlık kontrolü
+ * @param {number} [options.timeoutMs]
+ * @returns {Promise<{ launched: boolean, appPath: string|null }>}
+ */
+export async function ensureAppRunning({
+	isRunning,
+	timeoutMs = DEFAULT_LAUNCH_TIMEOUT_MS,
+}) {
+	if (await isRunning()) return { launched: false, appPath: null };
+
+	const appPath = launchApp();
+	const deadline = Date.now() + timeoutMs;
+
+	while (Date.now() < deadline) {
+		await delay(POLL_INTERVAL_MS);
+		if (await isRunning()) return { launched: true, appPath };
+	}
+
+	throw new AppLaunchError(
+		`Launched ${appPath} but its agent bridge did not become ready within ` +
+			`${Math.round(timeoutMs / 1000)}s. The app may still be starting, or the ` +
+			"bridge may be disabled (CREAVIT_AGENT_BRIDGE=0).",
+	);
+}

package/src/bridgeClient.mjs

@@ -7,6 +7,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { ENDPOINT_FILENAME, APP_NOT_RUNNING_HINT } from "./protocol.mjs";
+import { ensureAppRunning, isAutoLaunchEnabled } from "./appLauncher.mjs";
 
 const DEFAULT_ENDPOINT_DIRS = [
 	path.join(os.homedir(), "Library", "Application Support", "creavit-studio"),
@@ -107,12 +108,39 @@ async function request(route, { method = "GET", body, timeoutMs = 120_000 } = {}
 	return payload.result;
 }
 
+// Otomatik başlatma süreç başına EN FAZLA BİR KEZ denenir. Her başarısız
+// çağrıda yeniden denemek, uygulama gerçekten açılamıyorsa her aracı
+// dakikalarca bekletirdi.
+let autoLaunchAttempt = null;
+
+async function tryAutoLaunch() {
+	if (!isAutoLaunchEnabled()) return false;
+	if (!autoLaunchAttempt) {
+		autoLaunchAttempt = ensureAppRunning({ isRunning: isAppRunning })
+			.then(() => true)
+			.catch(() => false);
+	}
+	return autoLaunchAttempt;
+}
+
 export async function callCommand(command, params, timeoutMs) {
-	return request("/rpc", {
-		method: "POST",
-		body: { command, params: params || {}, timeoutMs },
-		timeoutMs: timeoutMs || 120_000,
-	});
+	const send = () =>
+		request("/rpc", {
+			method: "POST",
+			body: { command, params: params || {}, timeoutMs },
+			timeoutMs: timeoutMs || 120_000,
+		});
+
+	try {
+		return await send();
+	} catch (error) {
+		// Uygulama kapalıysa aç ve komutu bir kez tekrarla; ajanın "önce
+		// uygulamayı elle başlat" demek zorunda kalmaması için.
+		if (!(error instanceof BridgeUnavailableError)) throw error;
+		const launched = await tryAutoLaunch();
+		if (!launched) throw error;
+		return send();
+	}
 }
 
 export async function health() {

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,143 @@ 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",
+			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:
-				"Activates a browser and scrolls by page. Useful while recording. Requires macOS Accessibility permission for Creavit Studio.",
+				"Finds a page element by CSS selector or visible text, scrolls to it, and performs a hover/click/type action. By default it moves the REAL system mouse, which looks natural in a recording. Set useSystemCursor:false when the user asks you not to touch their cursor — the click is still delivered to the page, the pointer just never moves.",
 			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)"),
+					useSystemCursor: S.bool(
+						"Move the real system cursor (default true). false = never touch the user's pointer; clicks are sent synthetically.",
+					),
 				},
-				["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 +251,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,
-				});
 			},
 		},
 	];

package/src/tools/systemTools.mjs

@@ -1,10 +1,38 @@
 // MCP araçları — uygulama durumu, kayıt akışı, cihazlar ve olay akışı.
 
 import { bridgeTool, schema, S, textResult } from "./defineTool.mjs";
-import { callCommand } from "../bridgeClient.mjs";
+import { callCommand, isAppRunning } from "../bridgeClient.mjs";
+import {
+	ensureAppRunning,
+	resolveAppPath,
+	DEFAULT_LAUNCH_TIMEOUT_MS,
+} from "../appLauncher.mjs";
 
 export function systemTools() {
 	return [
+		{
+			name: "creavit_app_launch",
+			description:
+				"Starts Creavit Studio if it is not already running, then waits until its agent bridge is ready. Looks for the app in /Applications and ~/Applications (override with CREAVIT_APP_PATH). Other tools also auto-launch on first use, so call this only when you want to start the app explicitly or check where it was found.",
+			inputSchema: schema({
+				timeoutMs: S.number(
+					`How long to wait for the bridge after launching (default ${DEFAULT_LAUNCH_TIMEOUT_MS})`,
+				),
+			}),
+			run: async (args) => {
+				const appPath = resolveAppPath();
+				const { launched } = await ensureAppRunning({
+					isRunning: isAppRunning,
+					timeoutMs: args?.timeoutMs || DEFAULT_LAUNCH_TIMEOUT_MS,
+				});
+				return textResult({
+					launched,
+					alreadyRunning: !launched,
+					appPath,
+				});
+			},
+		},
+
 		bridgeTool({
 			name: "creavit_app_info",
 			description:
@@ -49,7 +77,7 @@ export function systemTools() {
 				"Starts a screen recording. Get source IDs from creavit_devices_list first. Monitor with creavit_recording_status, and finish with creavit_recording_stop.",
 			inputSchema: schema({
 				options: S.object(
-					"Recording options: {sourceType:'display'|'window'|'area', sourceId, cameraEnabled, micEnabled, systemAudioEnabled, delayMs, area:{x,y,width,height}}",
+					"Recording options: {sourceType:'display'|'window'|'area', sourceId, cameraEnabled, micEnabled, systemAudioEnabled, delayMs, area:{x,y,width,height}}. cameraEnabled:false also turns the camera off and hides its window, so it does not appear in a screen recording; cameraEnabled:true opens and starts it.",
 				),
 			}),
 			timeoutMs: 180_000,