@writepanda/mcp 1.180.0 → 1.191.0

package/bin/server.mjs

@@ -29,7 +29,6 @@
 
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import fs from "node:fs/promises";
 import http from "node:http";
 import os from "node:os";
 import path from "node:path";
@@ -37,78 +36,26 @@ import process from "node:process";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import {
+	appLaunchEnv,
+	cleanFileValue,
+	configDir,
+	connectInApp,
+	fileCredentials,
+	IN_APP_UNAVAILABLE,
+	isInAppCaller,
+	probeHealth,
+	waitForHealth,
+} from "./appConnection.mjs";
 
 // ── Credentials + transport ───────────────────────────────────────────
+//
+// Finding and reaching the app lives in appConnection.mjs (unit-tested).
 
-function configDir() {
-	if (process.env.PANDASTUDIO_CONFIG_DIR) return process.env.PANDASTUDIO_CONFIG_DIR;
-	if (process.platform === "win32") {
-		const appData = process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
-		return path.join(appData, "pandastudio");
-	}
-	return path.join(os.homedir(), ".config", "pandastudio");
-}
-
-const TOKEN_FILE = path.join(configDir(), "token");
-const PORT_FILE = path.join(configDir(), "port");
+const IN_APP = isInAppCaller();
 
 async function readCredentials() {
-	const port = Number((await fs.readFile(PORT_FILE, "utf-8")).trim());
-	const token = (await fs.readFile(TOKEN_FILE, "utf-8")).trim();
-	if (!Number.isInteger(port) || port <= 0) throw new Error(`invalid port in ${PORT_FILE}`);
-	if (!token) throw new Error(`empty token in ${TOKEN_FILE}`);
-	return { port, token };
-}
-
-async function probeHealth(port, timeoutMs = 1500) {
-	const ctrl = new AbortController();
-	const t = setTimeout(() => ctrl.abort(), timeoutMs);
-	try {
-		const res = await fetch(`http://127.0.0.1:${port}/v1/health`, { signal: ctrl.signal });
-		clearTimeout(t);
-		return res.ok;
-	} catch {
-		clearTimeout(t);
-		return false;
-	}
-}
-
-/**
- * One health probe: "up" (answered), "busy" (the socket is open but no answer
- * within `timeoutMs`: the app's main process is stalled, e.g. creating an
- * editor window on a loaded machine) or "down" (connection refused / reset:
- * not running).
- */
-async function probeHealthState(port, timeoutMs) {
-	const ctrl = new AbortController();
-	const t = setTimeout(() => ctrl.abort(), timeoutMs);
-	try {
-		const res = await fetch(`http://127.0.0.1:${port}/v1/health`, { signal: ctrl.signal });
-		return res.ok ? "up" : "down";
-	} catch {
-		return ctrl.signal.aborted ? "busy" : "down";
-	} finally {
-		clearTimeout(t);
-	}
-}
-
-/**
- * Is the app reachable? A busy app is waited for (up to `busyWaitMs`) rather
- * than reported as not running: a single 1.5 s probe used to fail whenever the
- * main process stalled for longer (window creation takes ~0.4 s idle and
- * several seconds under load), so agents saw "not reachable" at random.
- */
-async function appReachable(port, { probeMs = 1500, busyWaitMs = 30_000, onBusy } = {}) {
-	const deadline = Date.now() + busyWaitMs;
-	let warned = false;
-	for (;;) {
-		const s = await probeHealthState(port, probeMs);
-		if (s === "up") return true;
-		if (s === "down" || Date.now() >= deadline) return false;
-		if (!warned && onBusy) onBusy();
-		warned = true;
-		probeMs = Math.min(probeMs * 2, 5000);
-	}
+	return fileCredentials(configDir());
 }
 
 function findInstalledApp() {
@@ -116,7 +63,7 @@ function findInstalledApp() {
 	// The app records its own location (it can live anywhere on Windows,
 	// and in ~/Applications on a Mac).
 	try {
-		const recorded = readFileSync(path.join(configDir(), "app-path"), "utf-8").trim();
+		const recorded = cleanFileValue(readFileSync(path.join(configDir(), "app-path"), "utf-8"));
 		if (recorded && existsSync(recorded)) return recorded;
 	} catch {
 		/* older app, or never launched */
@@ -159,14 +106,16 @@ async function autoLaunchAndWait(timeoutSec = 60) {
 		const c = await readCredentials();
 		// Busy (stalled main process) is not "not running": wait for it
 		// instead of launching a second copy.
-		if (await appReachable(c.port)) return c;
+		if ((await waitForHealth(c.port)).state === "up") return c;
 	} catch {
 		/* not running */
 	}
 
 	const bin = findInstalledApp();
 	try {
-		const child = spawn(bin, [], { detached: true, stdio: "ignore", env: process.env });
+		// appLaunchEnv drops ELECTRON_RUN_AS_NODE: inherited, it made the
+		// "launch" start a Node REPL that exits instead of PandaStudio.
+		const child = spawn(bin, [], { detached: true, stdio: "ignore", env: appLaunchEnv() });
 		child.unref();
 	} catch (err) {
 		throw new Error(`failed to launch PandaStudio (${bin}): ${err?.message ?? err}`);
@@ -176,7 +125,7 @@ async function autoLaunchAndWait(timeoutSec = 60) {
 	while (Date.now() < deadline) {
 		try {
 			const c = await readCredentials();
-			if (await probeHealth(c.port, 2000)) return c;
+			if ((await probeHealth(c.port, 2000)).state === "up") return c;
 		} catch {
 			/* still booting */
 		}
@@ -211,18 +160,50 @@ function httpRequestLocal(port, pathSuffix, { method = "GET", headers = {}, body
 	});
 }
 
-async function callPandastudio(command, args = {}) {
-	const creds = await autoLaunchAndWait();
-	const res = await httpRequestLocal(creds.port, "/v1/call", {
+async function postCall(creds, command, args) {
+	return httpRequestLocal(creds.port, "/v1/call", {
 		method: "POST",
 		headers: {
 			"Content-Type": "application/json",
 			Authorization: `Bearer ${creds.token}`,
 			// Set by the app when it runs this server for its own chat panel.
-			...(process.env.PANDASTUDIO_CALLER === "in-app" ? { "X-PandaStudio-Caller": "in-app" } : {}),
+			...(IN_APP ? { "X-PandaStudio-Caller": "in-app" } : {}),
 		},
 		body: JSON.stringify({ command, args }),
 	});
+}
+
+async function callPandastudio(command, args = {}) {
+	// In-app: the app is running (it spawned us). Never launch it, and fail in
+	// seconds with the real reason instead of outliving the client's timeout.
+	let creds = IN_APP ? await connectInApp() : await autoLaunchAndWait();
+	let res;
+	try {
+		res = await postCall(creds, command, args);
+	} catch (err) {
+		if (!IN_APP) throw err;
+		throw new Error(
+			`${IN_APP_UNAVAILABLE}: the call to 127.0.0.1:${creds.port} failed (${err?.code ?? err?.message ?? err}).`,
+		);
+	}
+	if (IN_APP && res.status === 401) {
+		// The app restarted its automation server (new token) after it
+		// spawned us. The files hold the current one.
+		try {
+			const fresh = await fileCredentials(configDir());
+			if (fresh.token !== creds.token || fresh.port !== creds.port) {
+				creds = fresh;
+				res = await postCall(creds, command, args);
+			}
+		} catch {
+			/* reported below */
+		}
+		if (res.status === 401) {
+			throw new Error(
+				`${IN_APP_UNAVAILABLE}: PandaStudio rejected the tools' access token (its automation server restarted).`,
+			);
+		}
+	}
 	const text = res.text;
 	let body;
 	try {
@@ -565,12 +546,75 @@ const ASSETS_PROP = {
 };
 const ANCHOR_PROP = {
 	type: "number",
-	description: "SOURCE ms (a transcript word's startMs) to pin to, surviving cuts.",
+	description: "SOURCE ms of a transcript word; survives cuts.",
 };
 const ANCHOR_END_PROP = { type: "number", description: "Anchor end, SOURCE ms." };
 const KEYFRAME_TARGET_DOC =
 	"main = motion region (its target decides fields); overlay: x y scale rotation opacity backdropBlur keyStrength; annotation: x y scale rotation opacity; adjustment: effects, amount, lookIntensity; focus: x y width height roundness feathering blurAmount pixelSize maskOpacity; background-effect: amount strength; mask (regionId = overlay id): x y width height roundness feather expand.";
 
+const MOTION_ELEMENT_TYPES = [
+	"keyword",
+	"chip",
+	"stamp",
+	"count",
+	"steps",
+	"slam",
+	"behind",
+	"lowerThird",
+	"highlight",
+	"endCard",
+	"progress",
+	"iconPop",
+	"frame",
+	"sticker",
+];
+const MOTION_ELEMENT_PROPS = {
+	type: { type: "string", enum: MOTION_ELEMENT_TYPES },
+	content: {
+		type: ["object", "string", "array"],
+		description:
+			'keyword/chip/stamp/slam/behind/highlight { text } (or a bare string); count { value, to?, prefix?, suffix?, label?, decimals? } (value "20-30" = range); steps { items[], cues? (ms offsets from start) }; lowerThird { title, subtitle? }; endCard { lines: [a, b] }; progress { label?, fromMs?, toMs? }; iconPop { emoji } | { icon }; frame { look: viewfinder | selection | corners, label? }; sticker { image: transparent PNG path, label? }. Latin script only.',
+	},
+	atMs: { type: "number", description: "Start, edited ms. Or wordId." },
+	wordId: {
+		type: "string",
+		description: "Start on this transcript word; follows it through cuts.",
+	},
+	offsetMs: { type: "number", description: "Shift from atMs/wordId (may be negative)." },
+	durationMs: { type: "number", description: "Default endWordId, else the type's length." },
+	endWordId: { type: "string", description: "Run to the end of this word." },
+	cueWordIds: {
+		type: "array",
+		items: { type: "string" },
+		description: "steps: one word id per item.",
+	},
+	style: {
+		type: "object",
+		properties: {
+			family: { type: "string", enum: ["bold", "editorial", "clean", "playful", "paper"] },
+			accent: { type: "string" },
+			highlight: { type: "string" },
+			text: { type: "string" },
+			font: { type: "string" },
+			size: { type: "string", enum: ["s", "m", "l", "xl"] },
+			outline: { type: "boolean" },
+		},
+		description: "Default: the brand kit.",
+	},
+	zone: {
+		type: ["string", "object"],
+		description:
+			"auto (clear of the face) | top | upper | center | lower | bottom | { x, y, w? } (% of frame; x,y = centre).",
+	},
+	layer: { type: "string", enum: ["front", "behind"] },
+	sound: {
+		type: "string",
+		enum: ["auto", "none", "pop", "whoosh", "hit", "tick", "bell"],
+		description: "Role for project_compose_soundtrack.",
+	},
+	zIndex: { type: "number" },
+	anchor: { type: "string", enum: ["auto", "free"] },
+};
 const TOOLS = [
 	// ── system + discovery ──────────────────────────────────────────
 	{
@@ -660,7 +704,7 @@ const TOOLS = [
 	{
 		name: "system_set_transcription_language",
 		description:
-			"Set the workspace transcription language. Non-auto uses Whisper, a ~1.1 GB download: tell the user first (system.is-whisper-model-downloaded via pandastudio_call).",
+			"Set the workspace transcription language. English = auto (english/en are saved as auto). Non-auto uses Whisper, a ~1.1 GB download: tell the user first (system.is-whisper-model-downloaded via pandastudio_call).",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -668,6 +712,8 @@ const TOOLS = [
 					type: "string",
 					enum: [
 						"auto",
+						"english",
+						"en",
 						"chinese",
 						"japanese",
 						"korean",
@@ -1347,6 +1393,11 @@ const TOOLS = [
 				slots: { type: "object", description: "Templates: changed slots only." },
 				background: { type: "string", enum: ["solid", "transparent", "glass"] },
 				html: { type: "string", description: "HTML graphics: full replacement." },
+				durationMs: { type: "number", description: "text-behind length." },
+				templateId: {
+					type: "string",
+					description: "Switch template (e.g. a retired one's replacement); slots map across.",
+				},
 				expectedRevision: { type: "number" },
 			},
 			required: ["overlayId"],
@@ -1526,16 +1577,33 @@ const TOOLS = [
 	},
 	{
 		name: "project_add_transition",
-		description: "Place a transition centred on a cut (atMs = a clip boundary).",
+		description:
+			"Place a transition centred on a cut (a clip boundary or a jump cut). kind overlay (fade-black, flash, glitch, torn-paper…) draws a WebM over the cut; kind native (zoom-blur, whip-left, whip-right, whip-up, spin) moves the footage itself (captions/graphics stay put), 350 ms default. Snaps atMs to a cut within snapMs (default 500) and places the transition's default sound.",
 		inputSchema: {
 			type: "object",
 			properties: {
 				id: { type: "string" },
 				path: { type: "string" },
-				transitionId: { type: "string", description: "asset_list_transitions id." },
-				file: { type: "string", description: "Instead of transitionId." },
-				atMs: { type: "number" },
-				durationMs: { type: "number", description: "Default 1000." },
+				transitionId: {
+					type: "string",
+					description: "asset_list_transitions id (overlay or native kind).",
+				},
+				file: { type: "string", description: "Custom overlay WebM, instead of transitionId." },
+				atMs: { type: "number", description: "The cut (edited ms)." },
+				durationMs: {
+					type: "number",
+					description: "Default: the catalog's (1000 overlays, 900 torn-paper, 350 native).",
+				},
+				snapMs: {
+					type: "number",
+					description: "Snap to the nearest cut within this many ms. Default 500; 0 = exact.",
+				},
+				sound: {
+					type: "string",
+					description:
+						"Bundled sound id / path. Default: the transition's defaultSoundId. none = silent.",
+				},
+				soundVolume: { type: "number", description: "0-1." },
 				expectedRevision: { type: "number" },
 			},
 			required: ["atMs"],
@@ -1545,7 +1613,7 @@ const TOOLS = [
 	{
 		name: "project_add_lower_third",
 		description:
-			"Render an lt-* nameplate and place it at atMs in one call (designs: motion_list category lower-third). ASYNC: { jobId }; job_wait gives result.overlayId once placed.",
+			"Render a nameplate and place it at atMs in one call, laid out for the project's aspect. ASYNC: { jobId }; job_wait gives result.overlayId once placed.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1553,12 +1621,16 @@ const TOOLS = [
 				path: { type: "string" },
 				name: { type: "string" },
 				title: { type: "string", description: "Second line (role / handle)." },
-				templateId: { type: "string", description: "Default lt-vox-marker." },
+				templateId: {
+					type: "string",
+					description:
+						"lt-vox-marker (default, bold marker) | lt-glass-card | lt-minimal-line | lt-bold-bar | lt-logo-name (slots.logo) | lt-duo (slots.name2/title2).",
+				},
 				atMs: { type: "number" },
 				aspectRatio: {
 					type: "string",
 					enum: ["16:9", "9:16", "1:1"],
-					description: "Match the project.",
+					description: "Default: the project's aspect.",
 				},
 				slots: { type: "object", description: "Extra slot values (motion_list)." },
 				soundUrl: { type: "string", description: 'Default bundled:sound/mouse-click; "none".' },
@@ -1575,6 +1647,29 @@ const TOOLS = [
 		},
 		command: "project.add-lower-third",
 	},
+	{
+		name: "project_add_title_behind",
+		description:
+			"1-3 huge words at head height BEHIND the presenter. ASYNC: job_wait gives regionId, face.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				text: { type: "string" },
+				atMs: { type: "number" },
+				style: { type: "string", enum: ["3d", "bold", "serif"] },
+				durationMs: { type: "number", description: "Default 3000." },
+				accentColor: { type: "string" },
+				position: { type: "string", enum: ["auto", "top", "center"] },
+				animation: { type: "string", enum: ["in-out", "in", "none"] },
+				behind: { type: "boolean", description: "false: in front (no face)." },
+				anchorSourceMs: ANCHOR_PROP,
+			},
+			required: ["text", "atMs"],
+		},
+		command: "project.add-title-behind",
+	},
 
 	// ── compose: visual regions ─────────────────────────────────────
 	{
@@ -2062,7 +2157,7 @@ const TOOLS = [
 	{
 		name: "project_render_frame",
 		description:
-			"Render the composited frame at an edited time to a PNG (matches export). Returns { path, timeMs, maskRect (video rect in 0-1 image fractions, for mapping boxes to spotlight coords), warnings? } (tell the user warnings).",
+			"Render the composited frame at an edited time to a PNG (matches export). Returns { path, timeMs (snapped to the export's frame grid, fps), maskRect (video rect in 0-1 image fractions, for mapping boxes to spotlight coords), warnings? } (tell the user warnings).",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -2464,13 +2559,14 @@ const TOOLS = [
 	// ── compose: edit existing regions ─────────────────────────────
 	{
 		name: "project_remove_region",
-		description: "Delete a region by id (editor.*Regions or audioOverlays); linked peers go too.",
+		description:
+			"Delete a region by id (editor.*Regions, motion-element = editor.motionElements, or audioOverlays); linked peers go too.",
 		inputSchema: {
 			type: "object",
 			properties: {
 				id: { type: "string" },
 				path: { type: "string" },
-				regionType: { type: "string", enum: REGION_TYPES },
+				regionType: { type: "string", enum: [...REGION_TYPES, "motion-element"] },
 				regionId: { type: "string" },
 				expectedRevision: { type: "number" },
 			},
@@ -2500,6 +2596,7 @@ const TOOLS = [
 						"spotlight",
 						"motion",
 						"adjustment",
+						"motion-element",
 						"audio-overlay",
 					],
 				},
@@ -2649,12 +2746,14 @@ const TOOLS = [
 	},
 	{
 		name: "project_set_crop",
-		description: "Crop the main video's source frame (0-1 fractions). Default 0,0,1,1 (no crop).",
+		description:
+			"Crop the main video's source frame (0-1 fractions), e.g. to cut baked-in black bars. Without clipId it applies to the project and every clip (a clip's own crop, like auto-reframe's, wins otherwise). Default 0,0,1,1 (no crop).",
 		inputSchema: {
 			type: "object",
 			properties: {
 				id: { type: "string" },
 				path: { type: "string" },
+				clipId: { type: "string", description: "Crop only this clip." },
 				x: { type: "number" },
 				y: { type: "number" },
 				width: { type: "number" },
@@ -2792,6 +2891,10 @@ const TOOLS = [
 					type: ["boolean", "string"],
 					description: "streaming / true (-14 LUFS, default), podcast (-16), off / false.",
 				},
+				frameRate: {
+					type: ["number", "string"],
+					description: "auto (default) | 30 | 60 | source (fastest source).",
+				},
 				expectedRevision: { type: "number" },
 			},
 		},
@@ -2893,6 +2996,47 @@ const TOOLS = [
 		},
 		command: "project.add-audio",
 	},
+	{
+		name: "project_add_sound_cues",
+		description:
+			"Place many timed SFX in one write (one undo). Each cue = an audio overlay. Same group again REPLACES its cues ([] clears). Returns overlayIds + warnings.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				cues: {
+					type: "array",
+					maxItems: 500,
+					items: {
+						type: "object",
+						properties: {
+							sound: {
+								type: "string",
+								description: "Bundled id or absolute path.",
+							},
+							atMs: { type: "number", description: "Edited-timeline ms." },
+							volume: { type: "number", description: "0-2." },
+							durationMs: { type: "number" },
+							sourceStartMs: { type: "number" },
+							fadeInMs: { type: "number" },
+							fadeOutMs: { type: "number" },
+							anchorSourceMs: {
+								type: "number",
+								description: "SOURCE ms word anchor; omit for graphics.",
+							},
+						},
+						required: ["sound", "atMs"],
+					},
+				},
+				group: { type: "string", description: 'e.g. "sfx".' },
+				volume: { type: "number", description: "Cue default, 0.8." },
+				expectedRevision: { type: "number" },
+			},
+			required: ["cues"],
+		},
+		command: "project.add-sound-cues",
+	},
 	{
 		name: "project_remove_audio",
 		description:
@@ -3169,13 +3313,14 @@ const TOOLS = [
 	{
 		name: "transcript_transcribe",
 		description:
-			"Transcribe clips with word timestamps. ASYNC: { jobId }, job_wait. Tell the user about result droppedWordEdits[] (fixes that may need redoing).",
+			"Transcribe clips with word timestamps (default: only clips without words). To REDO a transcript (wrong language, bad run) fix the language first, then force: true (all clips) or clipId. Word fixes are re-applied; tell the user about result droppedWordEdits[] (fixes that may need redoing). ASYNC: { jobId }, job_wait.",
 		inputSchema: {
 			type: "object",
 			properties: {
 				id: { type: "string" },
 				path: { type: "string" },
-				clipId: { type: "string" },
+				clipId: { type: "string", description: "Only this clip, even if already transcribed." },
+				force: { type: "boolean", description: "Re-transcribe clips that already have words." },
 			},
 		},
 		command: "transcript.transcribe",
@@ -3364,7 +3509,8 @@ const TOOLS = [
 	},
 	{
 		name: "caption_set_template",
-		description: "Pick a caption template (default glowStack).",
+		description:
+			"Pick a caption template (default glowStack); clears style overrides. Emphasis templates (hormoziEmphasis, tiltedBox, serifItalic, condensedCaps, scriptKeyword) style the IMPORTANT word of each phrase, not the spoken one; emphasis is detected on apply when missing (result.emphasis).",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -3389,6 +3535,11 @@ const TOOLS = [
 						"matrixDecode",
 						"glitchRgb",
 						"blendDifference",
+						"hormoziEmphasis",
+						"tiltedBox",
+						"serifItalic",
+						"condensedCaps",
+						"scriptKeyword",
 					],
 				},
 				expectedRevision: { type: "number" },
@@ -3400,7 +3551,8 @@ const TOOLS = [
 
 	{
 		name: "caption_set_style",
-		description: "Override caption style fields (template kept); pass only what changes.",
+		description:
+			"Override caption style fields (template kept); pass only what changes. highlightMode emphasis/both detects emphasis words when missing (result.emphasis).",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -3417,11 +3569,45 @@ const TOOLS = [
 				strokeWidth: { type: "number" },
 				fontSize: { type: "string", description: "e.g. '2.6rem' (1-5rem)." },
 				uppercase: { type: "boolean" },
+				highlightMode: {
+					type: "string",
+					enum: ["spoken", "emphasis", "both"],
+					description: "spoken = word being said; emphasis = key words all group long.",
+				},
+				emphasisColor: { type: "string" },
+				emphasisBackgroundColor: { type: "string", description: "'transparent' = no box." },
+				emphasisScale: { type: "number", description: "0.5-2." },
+				emphasisItalic: { type: "boolean" },
+				emphasisFontFamily: {
+					type: "string",
+					description: "Engine font, e.g. Great Vibes, Playfair Display, Bebas Neue, Anton.",
+				},
+				boxRotation: { type: "number", description: "Box tilt degrees 0-15." },
 				expectedRevision: { type: "number" },
 			},
 		},
 		command: "caption.set-style",
 	},
+	{
+		name: "caption_mark_emphasis",
+		description:
+			"Set the key words emphasis caption styles mark. No wordIds: detect from the speech map (strong moments + numbers; hand marks kept unless reset). wordIds: mark (emphasis true) or unmark (false). Returns { emphasizedWords, words }.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				wordIds: { type: "array", items: { type: "string" }, description: "From transcript_get." },
+				emphasis: { type: "boolean", description: "With wordIds; default true." },
+				detect: { type: "boolean" },
+				reset: { type: "boolean", description: "Detection replaces hand marks too." },
+				minGapMs: { type: "number", description: "Default 1200." },
+				everyMs: { type: "number", description: "Default 2500; lower = more words." },
+				expectedRevision: { type: "number" },
+			},
+		},
+		command: "caption.mark-emphasis",
+	},
 	{
 		name: "caption_move",
 		description:
@@ -3455,14 +3641,20 @@ const TOOLS = [
 	{
 		name: "media_generate_image",
 		description:
-			"Generate one image (Replicate gpt-image-2, needs Replicate connected). Returns { imagePath }. 3:2 for 16:9, 2:3 for 9:16.",
+			"Generate one image on the user's own image connector (auto: Replicate, else Higgsfield; their credits). Returns { imagePath, provider, model, transparent }. transparent=true: trimmed PNG sticker. No connector: code NO_IMAGE_CONNECTOR, so ask the user for their own images. Each call is a paid generation.",
 		inputSchema: {
 			type: "object",
 			properties: {
 				prompt: { type: "string", description: "Keep text out of the image." },
-				aspectRatio: { type: "string", enum: ["1:1", "3:2", "2:3"] },
+				aspectRatio: {
+					type: "string",
+					enum: ["1:1", "3:2", "2:3", "4:3", "3:4", "16:9", "9:16"],
+					description: "Default 3:2. 16:9 / 9:16 for full-frame video stills.",
+				},
 				quality: { type: "string", enum: ["low", "medium", "high"] },
 				referenceImagePath: { type: "string", description: "Style reference (path or URL)." },
+				transparent: { type: "boolean", description: "Background removed (sticker PNG)." },
+				provider: { type: "string", enum: ["auto", "replicate", "higgsfield"] },
 				outputName: { type: "string" },
 			},
 			required: ["prompt"],
@@ -3613,6 +3805,350 @@ const TOOLS = [
 		},
 		command: "media.generate-presenter",
 	},
+	{
+		name: "project_inspect_footage",
+		description:
+			"Import checks before styling camera footage: flat/log (needs a grade), a flat green/blue backdrop (key it), rotation (vertical phone/camera clips). Returns per clip { flat, backdrop, rotation, contrast, blackLevel, saturation, suggestions:[{ why, verb, args }] }; run the suggested verbs.",
+		inputSchema: {
+			type: "object",
+			properties: { id: { type: "string" }, path: { type: "string" }, clipId: { type: "string" } },
+		},
+		command: "project.inspect-footage",
+	},
+	{
+		name: "project_speech_map",
+		description:
+			"The words the speaker STRESSES and where they land on the edited timeline (any language, incl. code-switched speech): measured from the audio (louder, sharp attack, pause before, drawn out) plus numbers and English key terms. Returns { durationMs, moments:[{ atMs, text, phrase, strength 1-3, emphasis, reasons, suggest }] }. Use as cues: zooms on strength 2-3, keyword graphics on the phrase, hits on strength 3. Needs a transcript.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				minGapMs: { type: "number", description: "Default 2500." },
+				everyMs: {
+					type: "number",
+					description:
+						"~one moment per this long. Default 5000; Shorts 3000-4000; long-form 8000-15000.",
+				},
+				words: { type: "boolean", description: "Also return every word's emphasis." },
+			},
+		},
+		command: "project.speech-map",
+	},
+	{
+		name: "project_compose_soundtrack",
+		description:
+			"Score this edit: music + sound design composed FROM THE PROJECT'S OWN TIMELINE (zooms, graphics, pops, cuts, speech, stressed words) and placed under the voice with ducking; takes over zoom/overlay default sounds; replaces the previous score on re-run. Call LAST, after cuts/zooms/graphics. dryRun returns the score for media_compose_soundtrack. Returns { audioPath, scorePath, events, heroMoments, acts, soundsTakenOver, replaced }.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				style: { type: "string", enum: ["talking-head", "short", "promo", "calm"] },
+				mood: { type: "string", enum: ["minor", "major"] },
+				bpm: { type: "number" },
+				sfx: { type: "boolean", description: "Default true." },
+				useSpeech: {
+					type: "boolean",
+					description: "Hero hits on the most stressed words. Default true.",
+				},
+				cues: {
+					type: "array",
+					items: {
+						type: "object",
+						properties: {
+							atMs: { type: "number" },
+							strength: { type: "number" },
+							label: { type: "string" },
+						},
+						required: ["atMs"],
+					},
+					description: "Extra moments, e.g. a graphic's own cue times.",
+				},
+				musicVolume: { type: "number", description: "0-2. Default by style." },
+				takeOverSounds: { type: "boolean", description: "Default true." },
+				dryRun: { type: "boolean" },
+				seed: { type: "number" },
+			},
+		},
+		command: "project.compose-soundtrack",
+	},
+	// ── native motion elements ──────────────────────────────────────
+	{
+		name: "project_add_motion_element",
+		description:
+			"Native motion element: an editable, word-timed graphic the engine draws (preview = export, no HTML render): keyword headline, chip, stamp, count (number/range rolls up), steps, slam (+ camera kick), behind (word behind the speaker), lowerThird, highlight, endCard, progress, iconPop, frame (viewfinder / selection box / corners around the speaker). Anchor with wordId (follows the word through cuts) or atMs. Brand kit by default. Returns { elementId, element }.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				...MOTION_ELEMENT_PROPS,
+				expectedRevision: { type: "number" },
+			},
+			required: ["type", "content"],
+		},
+		command: "project.add-motion-element",
+	},
+	{
+		name: "project_add_motion_elements",
+		description:
+			"Add many native motion elements in one edit (one revision). All or nothing: an invalid one rejects the batch with 'element <i>: <reason>'. Returns { elementIds, elements }.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				elements: {
+					type: "array",
+					items: {
+						type: "object",
+						properties: MOTION_ELEMENT_PROPS,
+						required: ["type", "content"],
+					},
+				},
+				expectedRevision: { type: "number" },
+			},
+			required: ["elements"],
+		},
+		command: "project.add-motion-elements",
+	},
+	{
+		name: "project_update_motion_element",
+		description:
+			"Change a native motion element; pass only what changes. style merges (field null = default); zone/layer/sound/zIndex null = default; atMs/wordId re-anchors and keeps the length. Editing a style-edit element makes it yours (re-runs keep it).",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				elementId: { type: "string" },
+				...MOTION_ELEMENT_PROPS,
+				expectedRevision: { type: "number" },
+			},
+			required: ["elementId"],
+		},
+		command: "project.update-motion-element",
+	},
+	{
+		name: "project_remove_motion_element",
+		description: "Remove a native motion element by id.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				elementId: { type: "string" },
+				expectedRevision: { type: "number" },
+			},
+			required: ["elementId"],
+		},
+		command: "project.remove-motion-element",
+	},
+	{
+		name: "project_list_motion_elements",
+		description:
+			"List placed native motion elements (id, type, span, content, style, zone, layer, sound, wordId, origin) with one-line summaries. catalog=true adds every type's content shape and defaults.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				type: { type: "string", enum: MOTION_ELEMENT_TYPES },
+				catalog: { type: "boolean" },
+			},
+		},
+		command: "project.list-motion-elements",
+	},
+	{
+		name: "project_style_edit",
+		description:
+			"Style a talking-head / Short in one call: inspect-footage (applyFixes applies grade/key), speech-map, native motion elements on the stressed moments (numbers → count, strength-3 English statement → slam, other heroes → keyword/stamp, code-switch key terms → chip, first moment → hook, last 4 s → end card, long-form topic turns → lower third) + silent zooms (1.5x/1.25x, 1.8x hero), then compose-soundtrack. paper-cut = the Vox paper-cut look (serif ink on torn paper strips, newsprint backdrop, speaker cut out with a white keyline in the lower half, paper foley, no zooms; look=false keeps your background/framing). Latin text only: for non-Latin speech pass texts { wordId: 'English keyword' } (else zoom only). Re-runs replace only what style-edit placed. Run after cuts. dryRun returns the plan.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				style: {
+					type: "string",
+					enum: ["bold-short", "editorial-long", "clean-tutorial", "paper-cut"],
+				},
+				format: {
+					type: "string",
+					enum: ["short", "long"],
+					description: "Density; default from aspect (9:16 = short).",
+				},
+				applyFixes: { type: "boolean", description: "Apply inspect-footage fixes. Default false." },
+				backdrop: {
+					type: "string",
+					description:
+						"Background behind a keyed-out speaker (applyFixes) and the paper-cut backdrop: wallpaper id, colour or CSS gradient. Default: the style's studio gradient when no background is set; paper-cut uses /wallpapers/paper-cream.jpg.",
+				},
+				look: {
+					type: "boolean",
+					description:
+						"paper-cut only: also set the look (paper backdrop, speaker cutout + white keyline, lower-half framing). Default true.",
+				},
+				texts: {
+					type: "object",
+					additionalProperties: { type: "string" },
+					description: "{ [wordId]: 'English keyword' } overrides.",
+				},
+				endCard: {
+					type: "array",
+					items: { type: "string" },
+					description: "[line1, line2]. Default: hook + hero line.",
+				},
+				accent: { type: "string", description: "Accent colour for every element; default brand." },
+				highlight: { type: "string", description: "Emphasis colour; default brand." },
+				zooms: { type: "boolean", description: "Default true." },
+				score: { type: "boolean", description: "Run compose-soundtrack. Default true." },
+				mood: { type: "string", enum: ["minor", "major"] },
+				dryRun: { type: "boolean" },
+				expectedRevision: { type: "number" },
+			},
+		},
+		command: "project.style-edit",
+	},
+	{
+		name: "media_compose_soundtrack",
+		description:
+			"Compose + render an original soundtrack (music, beats, SFX) from a score on the SAME timeline as the edit, so hits land on their moments. Synthesized locally: no key, no licensing, ~1 s per 15 s. Plan cues from the edit first, set bpm so cuts land on beats, then place sounds on cues. Returns { audioPath, scorePath, durationMs, lufs, truePeakDb, events, cues, warnings }; place with project_add_audio. Format + recipes: skill reference/soundtrack.md.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				score: {
+					type: "object",
+					description: "The score. Pass score or scorePath.",
+					properties: {
+						duration: { type: "number", description: "Seconds (max 600)." },
+						seed: { type: "number" },
+						cues: {
+							type: "object",
+							description: 'Named moments: { "slam": 3.0, "logo": "slam+9.95" }.',
+							additionalProperties: { type: ["number", "string"] },
+						},
+						events: {
+							type: "array",
+							items: {
+								type: "object",
+								properties: {
+									at: { type: ["number", "string"], description: 'Seconds, a cue, or "cue+0.2".' },
+									sound: {
+										type: "string",
+										enum: [
+											"kick",
+											"snare",
+											"clap",
+											"hat",
+											"openhat",
+											"tick",
+											"click",
+											"blip",
+											"pop",
+											"typing",
+											"whoosh",
+											"riser",
+											"downlifter",
+											"impact",
+											"boom",
+											"subdrop",
+											"shimmer",
+											"bass",
+											"pluck",
+											"pad",
+											"lead",
+											"bell",
+											"keys",
+										],
+									},
+									gain: { type: "number" },
+									pan: { type: "number", description: "-1 left .. 1 right" },
+									dur: { type: "number" },
+									note: { type: ["string", "number"], description: '"A3" or MIDI' },
+									notes: { type: "array", items: { type: ["string", "number"] } },
+									chord: { type: "string", description: '"Am", "Fmaj7"' },
+									from: { type: "number", description: "Sweep start Hz" },
+									to: { type: "number", description: "Sweep end Hz" },
+									bright: { type: "number", description: "0 dark .. 1 bright" },
+									reverb: { type: "number", description: "0..1 send" },
+									repeat: {
+										type: "object",
+										properties: {
+											count: { type: "number" },
+											every: { type: "number" },
+											gainStep: { type: "number" },
+											alternatePan: { type: "boolean" },
+											jitter: { type: "number" },
+										},
+									},
+								},
+								required: ["at", "sound"],
+							},
+						},
+						sections: {
+							type: "array",
+							items: {
+								type: "object",
+								properties: {
+									from: { type: ["number", "string"] },
+									to: { type: ["number", "string"] },
+									bpm: { type: "number" },
+									chords: { type: "array", items: { type: "string" } },
+									chordBeats: { type: "number", description: "Beats per chord, default 4." },
+									drums: {
+										type: "string",
+										enum: ["four-on-floor", "backbeat", "half-time", "breakbeat", "none"],
+									},
+									hats: { type: "string", enum: ["16ths", "8ths", "offbeat", "none"] },
+									bass: { type: "string", enum: ["pulse", "octave", "root", "sustain", "none"] },
+									arp: { type: "string", enum: ["up", "down", "updown", "none"] },
+									arpRate: { type: "string", enum: ["4ths", "8ths", "16ths"] },
+									pad: { type: ["boolean", "number"] },
+									whooshOnChange: { type: "boolean" },
+									melody: {
+										type: "object",
+										properties: {
+											notes: { type: "array", items: { type: ["string", "number", "null"] } },
+											rate: { type: "string", enum: ["4ths", "8ths", "16ths"] },
+											sound: { type: "string", enum: ["pluck", "lead", "bell", "keys"] },
+											gain: { type: "number" },
+											length: { type: "number" },
+											reverb: { type: "number" },
+										},
+									},
+									gain: { type: "number" },
+									mix: {
+										type: "object",
+										description: "Per-part levels 0-2: drums, hats, bass, arp, pad, melody.",
+									},
+								},
+								required: ["from", "to", "bpm"],
+							},
+						},
+						master: {
+							type: "object",
+							properties: {
+								lufs: { type: "number", description: "Default -14." },
+								ceiling: { type: "number", description: "True-peak dBFS, default -1." },
+								fadeIn: { type: "number" },
+								fadeOut: { type: "number" },
+								drive: { type: "number", description: "1 clean .. 4 heavy, default 1.3." },
+								room: { type: "number", description: "Reverb size 0..1." },
+							},
+						},
+					},
+					required: ["duration"],
+				},
+				scorePath: {
+					type: "string",
+					description: "Absolute path to a score JSON (e.g. a previous scorePath).",
+				},
+				name: { type: "string", description: "File name stem." },
+			},
+		},
+		command: "media.compose-soundtrack",
+	},
 	{
 		name: "media_generate_music",
 		description:
@@ -3654,6 +4190,28 @@ const TOOLS = [
 		},
 		command: "media.import",
 	},
+	{
+		name: "media_download_url",
+		description:
+			"Download a video or its audio from a page link (YouTube, Vimeo...). Only content the user has rights to. ASYNC: job_wait gives { path, title, durationMs }.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				url: { type: "string" },
+				format: { type: "string", enum: ["video", "audio"] },
+				maxHeight: { type: "number", description: "Default 1080." },
+				startMs: { type: "number" },
+				endMs: { type: "number" },
+				maxMinutes: { type: "number", description: "Default 120." },
+				name: { type: "string" },
+				addToProject: { type: "string", description: "Project id." },
+				as: { type: "string", enum: ["clip", "overlay", "audio"] },
+				atMs: { type: "number" },
+			},
+			required: ["url"],
+		},
+		command: "media.download-url",
+	},
 	{
 		name: "media_generate_sound_effect",
 		description:
@@ -3743,7 +4301,7 @@ const TOOLS = [
 				recipe: {
 					type: "object",
 					description:
-						"{ id?, title, description, category, footage?, aspectRatio?, fields: [{ key, label, type: text|longtext|select|color, default?, options?, required?, help? }], prompt, style?: { aspectRatio?, colorCorrection?, lut?: { preset, intensity? }, background?: { mode, image? }, cameraLayout?, captions?: { enabled, templateId? }, wallpaper? }, checklist: string[] }",
+						"{ id?, title, description, category, footage?, aspectRatio?, fields: [{ key, label, type: text|longtext|select|color|images, default?, options?, required?, help?, minCount?, maxCount?, optional? }], prompt, style?: { aspectRatio?, colorCorrection?, lut?: { preset, intensity? }, background?: { mode, image? }, cameraLayout?, captions?: { enabled, templateId? }, wallpaper? }, checklist: string[] }",
 				},
 			},
 			required: ["recipe"],
@@ -3802,8 +4360,22 @@ const TOOLS = [
 	{
 		name: "motion_list",
 		description:
-			"List motion-graphic templates (slots; render with motion_generate) and slot-less registryBlocks (edit htmlPath, render with motion_render_html).",
-		inputSchema: { type: "object", properties: {} },
+			"List motion-graphic templates (slots, family, tags; render with motion_generate) and slot-less registryBlocks (edit htmlPath, render with motion_render_html). Retired templates are hidden unless includeRetired.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				family: {
+					type: "string",
+					description:
+						"titles|text-behind|captions|callouts|lists-steps|stats-data|comparisons|product|panels|social-proof|social|intro-outro|end-cards|lower-thirds (comma-separated ok).",
+				},
+				tags: { type: "string", description: "Any of these tags, comma-separated." },
+				query: { type: "string", description: "Search, e.g. 'subscribe', 'bar chart'." },
+				aspect: { type: "string", enum: ["16:9", "9:16", "1:1"] },
+				includeRetired: { type: "boolean" },
+				includeBlocks: { type: "boolean", description: "Default true." },
+			},
+		},
 		command: "motion.list",
 	},
 	{
@@ -3935,7 +4507,11 @@ const TOOLS = [
 				aspectRatio: { type: "string", enum: ["16:9", "9:16", "1:1"] },
 				width: { type: "number" },
 				height: { type: "number" },
-				durationMs: { type: "number", description: "Default 2500." },
+				durationMs: {
+					type: "number",
+					description:
+						"Omit when the root declares data-duration (that is the length rendered; a mismatch warns). Else default 2500. Max 600000 (10 min).",
+				},
 				frameRate: { type: "number" },
 				outputName: { type: "string" },
 				audioPath: { type: "string", description: "Muxed in (not when transparent)." },
@@ -3949,16 +4525,21 @@ const TOOLS = [
 	{
 		name: "motion_screenshot",
 		description:
-			"Capture one PNG frame of an HTML composition, as motion_render_html would. Returns { outputPath, previewPath } (inspect previewPath).",
+			"Capture one PNG frame of an HTML composition (or a template with slots), as motion_render_html / motion_generate would. Returns { outputPath, previewPath } (inspect previewPath).",
 		inputSchema: {
 			type: "object",
 			properties: {
-				html: { type: "string", description: "Or htmlPath." },
+				html: { type: "string", description: "Or htmlPath, or templateId." },
 				htmlPath: { type: "string" },
+				templateId: { type: "string", description: "Template id; fill with slots." },
+				slots: { type: "object" },
 				aspectRatio: { type: "string", enum: ["16:9", "9:16", "1:1"] },
 				width: { type: "number" },
 				height: { type: "number" },
-				atMs: { type: "number", description: "Max 30000." },
+				atMs: {
+					type: "number",
+					description: "Clamped to the composition's data-duration; result atMs = time captured.",
+				},
 				transparent: { type: "boolean" },
 				assets: ASSETS_PROP,
 				outputName: { type: "string" },
@@ -4005,8 +4586,23 @@ const TOOLS = [
 	},
 	{
 		name: "asset_list_sounds",
-		description: "List bundled sound effects (id, name, category, path).",
-		inputSchema: { type: "object", properties: {} },
+		description:
+			"List bundled SFX (~190: id, category, tags, durationMs, variantGroup, path). Filter; summary=true gives categories + groups only.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				category: {
+					type: "string",
+					description:
+						"ui|notification|motion|digital|impact|typing|outcome|ambience, comma-separated.",
+				},
+				tag: { type: "string", description: 'e.g. "click,soft" (all match).' },
+				mood: { type: "string" },
+				group: { type: "string", description: "Variant group." },
+				query: { type: "string" },
+				summary: { type: "boolean" },
+			},
+		},
 		command: "asset.list-sounds",
 	},
 	{
@@ -4018,7 +4614,7 @@ const TOOLS = [
 	{
 		name: "asset_list_transitions",
 		description:
-			"List bundled transitions (id, title, category, durationSeconds) for project_add_transition.",
+			"List bundled transitions (id, title, kind overlay|native, effect, category, durationSeconds, defaultSoundId) for project_add_transition.",
 		inputSchema: { type: "object", properties: {} },
 		command: "asset.list-transitions",
 	},
@@ -4105,6 +4701,10 @@ const TOOLS = [
 					type: ["boolean", "string"],
 					description: "streaming / podcast / off; omit = project setting.",
 				},
+				frameRate: {
+					type: ["number", "string"],
+					description: "30 | 60 | source | auto; omit = project setting.",
+				},
 			},
 		},
 		command: "export.start",
@@ -4175,7 +4775,7 @@ const TOOLS = [
 	{
 		name: "export_generate_thumbnail",
 		description:
-			"Generate a YouTube thumbnail for an export (Replicate, spends credits). Pass subject + hook, or omit to derive from the transcript. Returns { imagePath }.",
+			"Generate a YouTube thumbnail for an export (user's image connector: Replicate, else Higgsfield; spends their credits). Pass subject + hook, or omit to derive from the transcript. Returns { imagePath }.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -4478,7 +5078,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 	};
 });
 
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
+server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
 	const tool = TOOLS.find((t) => t.name === request.params.name);
 	if (!tool) {
 		return {
@@ -4509,7 +5109,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 	}
 
 	try {
-		const result = await callPandastudio(command, dispatchArgs);
+		const result = await withProgressHeartbeat(request, extra, () =>
+			callPandastudio(command, dispatchArgs),
+		);
 		// Format the response for the MCP client. Default is a text
 		// block carrying the JSON result. For `motion.screenshot` and
 		// `motion.verify-frames` we ALSO inline the downscaled preview
@@ -4559,6 +5161,36 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 	}
 });
 
+/**
+ * Keep a long call alive on the client side. MCP clients time a request out
+ * after 60 s unless progress arrives (opencode, the in-app agent's runtime,
+ * sends every tool call with a progress token and resets its timer on each
+ * notification). job.wait, renders and presenter takes run for minutes, so
+ * while the app works we report progress every 15 s. Clients that sent no
+ * progress token get nothing.
+ */
+const HEARTBEAT_MS = Number(process.env.PANDASTUDIO_MCP_PROGRESS_MS) || 15_000;
+
+async function withProgressHeartbeat(request, extra, run) {
+	const progressToken = request.params?._meta?.progressToken;
+	if (progressToken === undefined || typeof extra?.sendNotification !== "function") return run();
+	let beats = 0;
+	const timer = setInterval(() => {
+		beats += 1;
+		extra
+			.sendNotification({
+				method: "notifications/progress",
+				params: { progressToken, progress: beats, message: "PandaStudio is working" },
+			})
+			.catch(() => undefined);
+	}, HEARTBEAT_MS);
+	try {
+		return await run();
+	} finally {
+		clearInterval(timer);
+	}
+}
+
 /** Decide which (if any) preview PNGs to inline as image content
  *  blocks for a given tool result. Only motion.screenshot (one
  *  preview) and motion.verify-frames (one per frame) qualify today.