creavit-studio-mcp 1.0.0 → 1.2.0

package/README.md

@@ -50,14 +50,14 @@ npx creavit-studio-mcp --doctor
 ```
 
 ```
-creavit-studio v1.0.0
+creavit-studio v1.2.0
 
-✓ 34 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
-✓ 41 bridge commands available
+✓ 56 bridge commands available
 
 Everything looks good.
 ```
@@ -110,9 +110,21 @@ files directly and work with the app closed.
 `creavit_editor_playback`, `creavit_editor_screenshot`,
 `creavit_editor_export`, `creavit_editor_history`
 
+**Appearance** — `creavit_editor_background_get`,
+`creavit_editor_background_set`, `creavit_editor_camera_get`,
+`creavit_editor_camera_set`, `creavit_editor_audio`
+
+**Perspective** — `creavit_editor_perspectives`,
+`creavit_editor_add_perspective`, `creavit_editor_update_perspective`,
+`creavit_editor_remove_perspective`
+
 **Recording** — `creavit_devices_list`, `creavit_recording_status`,
 `creavit_recording_start`, `creavit_recording_stop`
 
+**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`
 
@@ -135,6 +147,63 @@ creavit_editor_screenshot     VERIFY the result
 creavit_project_save          persist
 ```
 
+### Background, camera, and mute
+
+Use the typed tools instead of guessing generic setting keys:
+
+```text
+creavit_editor_background_set  type=solid color=#10131a
+creavit_editor_background_set  type=gradient gradient={type, direction, colors}
+creavit_editor_camera_set      settings={visible,size,radius,shadow,mirror,...}
+creavit_editor_audio           action=mute
+creavit_project_save
+```
+
+`creavit_editor_audio action=mute` changes both preview audio and every clip's
+timeline volume, so the saved project also exports without source audio.
+
+### Record a URL walkthrough
+
+`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:
+
+```json
+{
+  "url": "https://example.com",
+  "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,
+  "perspectiveTemplate": "minimal-tilt",
+  "mute": true
+}
+```
+
+For hand-directed recordings, use `creavit_browser_open`,
+`creavit_recording_start`, and `creavit_browser_scroll` separately, then add
+zooms/perspective with the editor tools.
+
 Two things worth knowing:
 
 - **Wait for the load.** After `creavit_project_open`, poll `creavit_editor_state`
@@ -151,6 +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**.
+- 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.0.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.0.0";
+export const SERVER_VERSION = "1.2.0";
 
 export const JSONRPC_ERRORS = {
 	PARSE_ERROR: -32700,

package/src/tools/browserTools.mjs

@@ -0,0 +1,432 @@
+// MCP tools — deterministic website walkthrough recording and browser control.
+
+import { bridgeTool, schema, S, textResult } from "./defineTool.mjs";
+import { callCommand } from "../bridgeClient.mjs";
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const BROWSER_APP_NAMES = {
+	zen: "Zen Browser",
+	"zen browser": "Zen Browser",
+	safari: "Safari",
+	chrome: "Google Chrome",
+	"google chrome": "Google Chrome",
+	arc: "Arc",
+	firefox: "Firefox",
+	brave: "Brave Browser",
+	"brave browser": "Brave Browser",
+};
+
+function canonicalBrowser(value) {
+	const key = String(value || "zen").trim().toLowerCase();
+	return BROWSER_APP_NAMES[key] || value;
+}
+
+function windowList(result) {
+	if (Array.isArray(result)) return result;
+	if (Array.isArray(result?.windows)) return result.windows;
+	return [];
+}
+
+function searchableWindowText(windowInfo) {
+	return [windowInfo?.appName, windowInfo?.ownerName, windowInfo?.name, windowInfo?.title, windowInfo?.windowTitle]
+		.filter(Boolean)
+		.join(" ")
+		.toLowerCase();
+}
+
+function findBrowserWindow(windows, browserName, titleContains) {
+	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"));
+	});
+	return candidates.find((entry) => entry?.isOnScreen !== false && Number(entry?.id) > 0) ||
+		candidates.find((entry) => Number(entry?.id) > 0) ||
+		null;
+}
+
+async function waitForBrowserWindow(browserName, titleContains, timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	let lastWindows = [];
+	while (Date.now() < deadline) {
+		const devices = await callCommand("devices.list", { kinds: ["windows"] }, 60_000);
+		lastWindows = windowList(devices?.windows);
+		const found = findBrowserWindow(lastWindows, browserName, titleContains);
+		if (found) return found;
+		await sleep(500);
+	}
+	throw new Error(
+		`Could not find a recordable ${browserName} window. Opened windows: ${lastWindows
+			.map((entry) => searchableWindowText(entry)).filter(Boolean).slice(0, 12).join(" | ")}`,
+	);
+}
+
+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);
+			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 new project did not become ready within ${Math.round(timeoutMs / 1000)}s${lastError ? `: ${lastError.message}` : ""}`,
+	);
+}
+
+async function clearZooms() {
+	const result = await callCommand("editor.listZooms", {});
+	const ranges = Array.isArray(result?.zoomRanges) ? result.zoomRanges : [];
+	for (let index = ranges.length - 1; index >= 0; index -= 1) {
+		await callCommand("editor.removeZoom", { index });
+	}
+	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. 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("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_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(
+				{
+					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)"),
+				},
+				["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:
+				"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("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"),
+					perspectiveTemplate: S.string("Perspective template id (default minimal-tilt)"),
+					save: S.bool("Save the generated project after editing (default true)"),
+				},
+				["url"],
+			),
+			run: async (args) => {
+				const browser = canonicalBrowser(args.browser || "Zen Browser");
+				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 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.48,
+						selector: null,
+						text: null,
+						action: "hover",
+						value: "",
+					}));
+
+				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", {
+						options: {
+							startScreen: true,
+							cameraEnabled: false,
+							micEnabled: !muted,
+							systemAudioEnabled: !muted,
+							recordingSource: { type: "window", windowId: browserWindow.id, windowInfo: browserWindow },
+						},
+					}, 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())));
+
+					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);
+					}
+					if (durationMs) {
+						const stopAt = recordingStartedAt + durationMs + 1500;
+						if (Date.now() < stopAt) await sleep(stopAt - Date.now());
+					} else {
+						await sleep(tailMs);
+					}
+					await callCommand("recording.stop", {}, 600_000);
+					recordingStarted = false;
+
+					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 (_) {}
+					}
+				}
+			},
+		},
+	];
+}

package/src/tools/editorTools.mjs

@@ -49,6 +49,81 @@ export function editorTools() {
 				}),
 		}),
 
+		bridgeTool({
+			name: "creavit_editor_background_get",
+			command: "editor.getBackground",
+			description:
+				"Reads the complete canvas background configuration: solid color, gradient, image, blur, and dynamic pattern values.",
+			inputSchema: schema(),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_background_set",
+			command: "editor.setBackground",
+			description:
+				"Sets the canvas background. For solid use type='solid' and color. For gradient pass at least two stops as {type:'linear'|'radial', direction:'to-right', colors:[{color:'#...',position:0},...]}. Call creavit_project_save afterwards.",
+			inputSchema: schema(
+				{
+					type: S.string("Background type", {
+						enum: ["solid", "color", "gradient", "image", "dynamic"],
+					}),
+					color: S.string("CSS color for a solid background"),
+					image: S.string("Image URL or local path"),
+					blur: S.number("Image blur amount"),
+					gradient: S.object(
+						"Gradient configuration: {type, direction, colors:[{color,position}]}.",
+					),
+					dynamic: S.object("Dynamic pattern configuration"),
+				},
+				["type"],
+			),
+			mapResult: (result) =>
+				textResult({ ...result, note: "Applied. Call creavit_project_save to persist." }),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_camera_get",
+			command: "editor.getCamera",
+			description: "Reads all camera overlay settings.",
+			inputSchema: schema(),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_camera_set",
+			command: "editor.setCamera",
+			description:
+				"Partially updates camera overlay settings: visible, size, radius, shadow, position crop, cropZoom, followMouse, oscillationMovement, mirror, aspectRatio, border, background removal, mergeWithCursor, lockSizeOnZoom and sizeOnZoom. Call creavit_project_save afterwards.",
+			inputSchema: schema(
+				{ settings: S.object("Camera settings to update") },
+				["settings"],
+			),
+			mapResult: (result) =>
+				textResult({ ...result, note: "Applied. Call creavit_project_save to persist." }),
+		}),
+
+		{
+			name: "creavit_editor_audio",
+			description:
+				"Reads audio state or mutes/unmutes both preview and every timeline clip used by export. Use action='mute' to guarantee that the exported video has no source audio.",
+			inputSchema: schema(
+				{
+					action: S.string("status, mute, or unmute", {
+						enum: ["status", "mute", "unmute"],
+					}),
+				},
+				["action"],
+			),
+			run: async ({ action }) => {
+				if (action === "status") return textResult(await callCommand("editor.getAudio", {}));
+				if (action !== "mute" && action !== "unmute") {
+					throw new Error("`action` must be status, mute, or unmute");
+				}
+				return textResult(
+					await callCommand("editor.setMuted", { muted: action === "mute" }),
+				);
+			},
+		},
+
 		bridgeTool({
 			name: "creavit_editor_list_zooms",
 			command: "editor.listZooms",
@@ -99,6 +174,52 @@ export function editorTools() {
 			}),
 		}),
 
+		bridgeTool({
+			name: "creavit_editor_perspectives",
+			command: "editor.listPerspectives",
+			description: "Lists all perspective (3D animation) ranges on the timeline.",
+			inputSchema: schema(),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_add_perspective",
+			command: "editor.addPerspective",
+			description:
+				"Adds a Creavit perspective range. Set fullDuration=true to cover the complete video. Templates include slant-left, slant-right, hero, lift, corner-left, corner-right, floating, perspective-left, perspective-right, minimal-tilt and cinematic-wide.",
+			inputSchema: schema({
+				start: S.number("Start time in seconds"),
+				end: S.number("End time in seconds"),
+				fullDuration: S.bool("Cover the complete video, ignoring start/end"),
+				templateId: S.string("Perspective template id"),
+				settings: S.object("Optional overrides for the perspective range"),
+			}),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_update_perspective",
+			command: "editor.updatePerspective",
+			description: "Updates an existing perspective range by id or zero-based index.",
+			inputSchema: schema(
+				{
+					id: S.string("Perspective range ID"),
+					index: S.number("Perspective range index"),
+					patch: S.object("Fields to update"),
+				},
+				["patch"],
+			),
+		}),
+
+		bridgeTool({
+			name: "creavit_editor_remove_perspective",
+			command: "editor.removePerspective",
+			description: "Deletes a perspective range by id/index, or all perspective ranges with all=true.",
+			inputSchema: schema({
+				id: S.string("Perspective range ID"),
+				index: S.number("Perspective range index"),
+				all: S.bool("Delete every perspective range"),
+			}),
+		}),
+
 		bridgeTool({
 			name: "creavit_editor_segments",
 			command: "editor.listSegments",

package/src/tools/index.mjs

@@ -3,6 +3,7 @@
 import { projectTools } from "./projectTools.mjs";
 import { editorTools } from "./editorTools.mjs";
 import { systemTools } from "./systemTools.mjs";
+import { browserTools } from "./browserTools.mjs";
 import { escapeTools } from "./escapeTools.mjs";
 import { errorResult } from "./defineTool.mjs";
 import { BridgeUnavailableError } from "../bridgeClient.mjs";
@@ -11,7 +12,13 @@ let registry = null;
 
 function buildRegistry() {
 	if (registry) return registry;
-	const all = [...systemTools(), ...projectTools(), ...editorTools(), ...escapeTools()];
+	const all = [
+		...systemTools(),
+		...projectTools(),
+		...editorTools(),
+		...browserTools(),
+		...escapeTools(),
+	];
 
 	const byName = new Map();
 	for (const tool of all) {