@writepanda/mcp 1.259.0 → 1.265.0

package/bin/apps/editPreview.mjs

@@ -0,0 +1,389 @@
+// Edit preview view (ui://pandastudio/edit-preview.html): the rendered frame
+// or a strip of frames across the edit, the timeline length and what the edit
+// contains. Shown for project_render_frame, project_render_sheet,
+// preview_show and project_edit_summary.
+
+import { viewPage } from "./viewKit.mjs";
+
+export const EDIT_PREVIEW_URI = "ui://pandastudio/edit-preview.html";
+
+const CSS = `
+.head { margin-bottom: 10px; }
+.meta { display: flex; flex-wrap: wrap; gap: 6px 12px; margin-top: 4px; font-size: 12px; color: var(--fg2); }
+.meta b { color: var(--fg); font-weight: 600; }
+.stage { position: relative; border-radius: var(--radius-lg); overflow: hidden; background: var(--bg2);
+	display: flex; align-items: center; justify-content: center; }
+.stage img { display: block; max-width: 100%; max-height: 460px; object-fit: contain; }
+.stage .missing { color: var(--fg2); }
+.stage .ph { width: 100%; aspect-ratio: var(--ar, 16 / 9); max-height: 460px; }
+.stage .tc { position: absolute; left: 8px; bottom: 8px; background: rgba(0, 0, 0, 0.62); color: #fff;
+	font-size: 12px; padding: 2px 7px; border-radius: 5px; font-variant-numeric: tabular-nums; }
+.strip { display: grid; grid-template-columns: repeat(var(--cols, 4), minmax(0, 1fr)); gap: 6px; margin-top: 8px; }
+.strip button { all: unset; cursor: pointer; position: relative; border-radius: 6px; overflow: hidden;
+	background: #000; outline: 2px solid transparent; outline-offset: -2px; }
+.strip button[aria-current="true"] { outline-color: var(--accent); }
+.strip img, .strip .ph { display: block; width: 100%; aspect-ratio: var(--ar, 16 / 9); object-fit: cover; }
+.strip .tc { position: absolute; left: 4px; bottom: 4px; background: rgba(0, 0, 0, 0.62); color: #fff;
+	font-size: 10.5px; padding: 1px 5px; border-radius: 4px; font-variant-numeric: tabular-nums; }
+.changes { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 12px; }
+.actions { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 12px; }
+.missing { font-size: 13px; text-align: center; padding: 30px 16px; }
+.warn { margin-top: 10px; font-size: 12px; color: var(--danger); }
+`;
+
+/** Runs in the view. Self-contained: serialized into the page. */
+function main(kit, ui) {
+	const { h, duration, actionButton, toast } = ui;
+	const app = document.getElementById("app");
+	const view = {
+		args: {},
+		project: null, // { id?, path? } for follow-up calls
+		frames: [], // [{ atMs, path, src? }]
+		sheetPath: null,
+		selected: 0,
+		summary: null,
+		summaryState: "idle", // idle | loading | ready | unavailable
+		framesState: "idle", // idle | loading | ready | error
+		framesError: null,
+		playheadMs: null,
+		warnings: [],
+		kind: null, // frame | sheet | show | summary
+		ratio: "16 / 9",
+	};
+
+	const ratioOf = (ar) => {
+		const m = /^(\d+(?:\.\d+)?):(\d+(?:\.\d+)?)$/.exec(ar ?? "");
+		return m ? `${m[1]} / ${m[2]}` : "16 / 9";
+	};
+	const projectArgs = () => {
+		const p = view.project ?? {};
+		if (p.id) return { id: p.id };
+		if (p.path) return { path: p.path };
+		return {};
+	};
+
+	function kindOf(data) {
+		const name = kit.toolName();
+		if (name === "project_render_frame") return "frame";
+		if (name === "project_render_sheet") return "sheet";
+		if (name === "preview_show") return "show";
+		if (name === "project_edit_summary") return "summary";
+		if (Array.isArray(data?.frames) || "sheetPath" in (data ?? {})) return "sheet";
+		if (typeof data?.path === "string" && typeof data?.timeMs === "number") return "frame";
+		if (Array.isArray(data?.highlights)) return "summary";
+		return "show";
+	}
+
+	async function loadImages() {
+		const paths = view.frames.map((f) => f.path).filter(Boolean);
+		if (view.sheetPath && !paths.length) paths.push(view.sheetPath);
+		if (!paths.length) return;
+		const images = await kit.loadImages(paths);
+		for (const f of view.frames) f.src = images.get(f.path) ?? null;
+		if (view.sheetPath && !view.frames.length) {
+			view.frames = [{ atMs: null, path: view.sheetPath, src: images.get(view.sheetPath) ?? null }];
+		}
+	}
+
+	async function renderStrip() {
+		view.framesState = "loading";
+		render();
+		try {
+			const { data } = await kit.callTool("project_render_sheet", {
+				...projectArgs(),
+				count: 8,
+				cols: 4,
+			});
+			view.frames = (data?.frames ?? []).map((f) => ({ atMs: f.atMs, path: f.path }));
+			view.sheetPath = view.frames.length ? null : (data?.sheetPath ?? null);
+			if (typeof view.playheadMs === "number" && view.frames.length) {
+				let best = 0;
+				view.frames.forEach((f, i) => {
+					if (
+						Math.abs(f.atMs - view.playheadMs) < Math.abs(view.frames[best].atMs - view.playheadMs)
+					)
+						best = i;
+				});
+				view.selected = best;
+			}
+			await loadImages();
+			view.framesState = "ready";
+		} catch (err) {
+			view.framesState = "error";
+			view.framesError = err?.message ?? String(err);
+		}
+		render();
+	}
+
+	async function rerenderFrame() {
+		const f = view.frames[view.selected];
+		view.framesState = "loading";
+		render();
+		try {
+			const { data } = await kit.callTool("project_render_frame", {
+				...projectArgs(),
+				atMs: f?.atMs ?? 0,
+				width: 1280,
+			});
+			view.frames = [{ atMs: data.timeMs, path: data.path }];
+			view.selected = 0;
+			view.warnings = data.warnings ?? [];
+			await loadImages();
+			view.framesState = "ready";
+		} catch (err) {
+			view.framesState = "error";
+			view.framesError = err?.message ?? String(err);
+		}
+		render();
+	}
+
+	async function loadSummary() {
+		view.summaryState = "loading";
+		render();
+		try {
+			const { data } = await kit.callTool("project_edit_summary", projectArgs());
+			view.summary = data;
+			if (data?.id && !view.project?.id) view.project = { ...view.project, id: data.id };
+			view.ratio = ratioOf(data?.aspectRatio);
+			view.summaryState = "ready";
+		} catch {
+			// An app older than project.edit-summary: show the frames alone.
+			view.summaryState = "unavailable";
+		}
+		render();
+	}
+
+	async function start(data) {
+		view.kind = kindOf(data);
+		view.warnings = Array.isArray(data?.warnings)
+			? data.warnings
+			: data?.warning
+				? [data.warning]
+				: [];
+		const a = view.args ?? {};
+		view.project = a.id ? { id: a.id } : a.path ? { path: a.path } : null;
+		if (view.kind === "frame") {
+			view.frames = [{ atMs: data.timeMs, path: data.path }];
+		} else if (view.kind === "sheet") {
+			view.frames = (data.frames ?? []).map((f) => ({ atMs: f.atMs, path: f.path }));
+			view.sheetPath = view.frames.length ? null : (data.sheetPath ?? null);
+		} else if (view.kind === "show") {
+			if (!view.project && data?.projectPath) view.project = { path: data.projectPath };
+			view.playheadMs = typeof data?.playheadMs === "number" ? data.playheadMs : null;
+		} else if (view.kind === "summary") {
+			view.summary = data;
+			view.summaryState = "ready";
+			view.ratio = ratioOf(data?.aspectRatio);
+			view.project = data?.id ? { id: data.id } : data?.path ? { path: data.path } : view.project;
+		}
+		render();
+		const work = [];
+		if (view.kind !== "summary") work.push(loadSummary());
+		if (view.kind === "frame" || view.kind === "sheet") {
+			view.framesState = "loading";
+			work.push(
+				loadImages().then(
+					() => {
+						view.framesState = "ready";
+						render();
+					},
+					(err) => {
+						view.framesState = "error";
+						view.framesError = err?.message ?? String(err);
+						render();
+					},
+				),
+			);
+		} else {
+			work.push(renderStrip());
+		}
+		await Promise.allSettled(work);
+	}
+
+	function stage() {
+		const f = view.frames[view.selected];
+		if (view.framesState === "loading" && !f?.src)
+			return h("div", { class: "stage" }, h("div", { class: "ph skeleton" }));
+		if (view.framesState === "error")
+			return h(
+				"div",
+				{ class: "stage" },
+				h("div", { class: "missing" }, `Couldn't render the preview: ${view.framesError}`),
+			);
+		if (!f) return null;
+		if (!f.src)
+			return h(
+				"div",
+				{ class: "stage" },
+				h(
+					"div",
+					{ class: "missing" },
+					"This frame is no longer available. Render it again to see it.",
+				),
+			);
+		return h(
+			"div",
+			{ class: "stage" },
+			h("img", { src: f.src, alt: `Frame at ${duration(f.atMs)}` }),
+			typeof f.atMs === "number" ? h("span", { class: "tc" }, duration(f.atMs)) : null,
+		);
+	}
+
+	function strip() {
+		if (view.frames.length < 2) return null;
+		const [w, hgt] = view.ratio.split(" / ").map(Number);
+		const cols = w < hgt ? 8 : w === hgt ? 6 : 4;
+		return h(
+			"div",
+			{ class: "strip", style: { "--cols": String(cols) } },
+			view.frames.map((f, i) =>
+				h(
+					"button",
+					{
+						type: "button",
+						title: `Frame at ${duration(f.atMs)}`,
+						"aria-current": i === view.selected ? "true" : "false",
+						onclick: () => {
+							view.selected = i;
+							render();
+						},
+					},
+					f.src
+						? h("img", { src: f.src, alt: "" })
+						: h("div", { class: view.framesState === "loading" ? "ph skeleton" : "ph" }),
+					typeof f.atMs === "number" ? h("span", { class: "tc" }, duration(f.atMs)) : null,
+				),
+			),
+		);
+	}
+
+	function header() {
+		const s = view.summary;
+		const fileName = view.project?.path
+			?.split(/[\\/]/)
+			.pop()
+			?.replace(/\.pandastudio$/i, "");
+		const title =
+			s?.name ?? fileName ?? (view.kind === "frame" ? "Rendered frame" : "Edit preview");
+		const meta = [];
+		if (s) {
+			meta.push(h("span", null, h("b", null, duration(s.editedDurationMs)), " long"));
+			if (s.removedMs >= 500)
+				meta.push(
+					h("span", null, `${duration(s.removedMs)} cut from ${duration(s.sourceDurationMs)}`),
+				);
+			meta.push(h("span", null, s.aspectRatio));
+			if (s.clipCount > 1) meta.push(h("span", null, `${s.clipCount} clips`));
+		} else if (view.summaryState === "loading") {
+			meta.push(h("span", { class: "faint" }, "Reading the edit…"));
+		}
+		return h(
+			"div",
+			{ class: "head" },
+			h("div", { class: "brand" }, h("i"), "PandaStudio"),
+			h("h1", null, title),
+			meta.length ? h("div", { class: "meta" }, meta) : null,
+		);
+	}
+
+	function changes() {
+		const lines = view.summary?.highlights ?? [];
+		if (!lines.length) {
+			return view.summaryState === "ready"
+				? h("div", { class: "changes" }, h("span", { class: "chip" }, "No edits yet"))
+				: null;
+		}
+		return h(
+			"div",
+			{ class: "changes" },
+			lines.map((t, i) => h("span", { class: i === 0 ? "chip strong" : "chip" }, t)),
+		);
+	}
+
+	function actions() {
+		const f = view.frames[view.selected];
+		const atMs = typeof f?.atMs === "number" ? f.atMs : (view.playheadMs ?? 0);
+		const btns = [
+			actionButton(
+				view.kind === "show" ? `Show ${duration(atMs)} in the editor` : "Open in PandaStudio",
+				async () => {
+					await kit.callTool("preview_show", { ...projectArgs(), atMs });
+					toast("Opened in PandaStudio");
+				},
+				{ primary: true, busy: "Opening…" },
+			),
+		];
+		if (view.kind === "frame") {
+			btns.push(actionButton("Render again", rerenderFrame, { busy: "Rendering…" }));
+			btns.push(actionButton("Frames across the edit", renderStrip, { busy: "Rendering…" }));
+		} else {
+			btns.push(
+				actionButton(
+					"Refresh",
+					async () => {
+						await Promise.all([renderStrip(), loadSummary()]);
+					},
+					{ busy: "Refreshing…" },
+				),
+			);
+		}
+		if (kit.canMessage() && view.summary?.name) {
+			btns.push(
+				actionButton("Ask to export", async () => {
+					await kit.sendMessage(`The preview of "${view.summary.name}" looks good. Export it.`);
+				}),
+			);
+		}
+		if (kit.canFullscreen()) {
+			const full = kit.state.hostContext.displayMode === "fullscreen";
+			btns.push(
+				actionButton(full ? "Exit full screen" : "Full screen", () =>
+					kit.requestDisplayMode(full ? "inline" : "fullscreen"),
+				),
+			);
+		}
+		return h("div", { class: "actions" }, btns);
+	}
+
+	function render() {
+		document.documentElement.style.setProperty("--ar", view.ratio);
+		app.replaceChildren(
+			...[
+				header(),
+				stage(),
+				strip(),
+				changes(),
+				view.warnings.length ? h("div", { class: "warn" }, view.warnings.join(" ")) : null,
+				actions(),
+			].filter(Boolean),
+		);
+	}
+
+	app.append(h("div", { class: "stage" }, h("div", { class: "ph skeleton" })));
+	kit.on("input", (args) => {
+		view.args = args ?? {};
+	});
+	kit.on("result", (result) => {
+		const error = kit.resultError(result);
+		if (error) {
+			app.replaceChildren(
+				h("div", { class: "brand" }, h("i"), "PandaStudio"),
+				h("p", { class: "error" }, error),
+			);
+			return;
+		}
+		start(kit.resultData(result) ?? {});
+	});
+	kit.on("context", () => {
+		if (view.kind) render();
+	});
+	kit.connect().catch((err) => {
+		app.replaceChildren(
+			h("p", { class: "error" }, `Couldn't connect to the chat: ${err?.message ?? err}`),
+		);
+	});
+}
+
+export function editPreviewHtml(version) {
+	return viewPage({ title: "PandaStudio edit preview", version, css: CSS, main });
+}

package/bin/apps/index.mjs

@@ -0,0 +1,256 @@
+// MCP Apps (interactive views in the chat) for the PandaStudio MCP server.
+//
+// Spec: SEP-1865 / io.modelcontextprotocol/ui, protocol 2026-01-26. A view
+// is a `ui://` resource (text/html;profile=mcp-app) that a host renders in a
+// sandboxed iframe next to a tool call whose `_meta.ui.resourceUri` names it.
+// The host sends the view the call's input and result; the view calls this
+// server's tools back through the host (tools/call over postMessage).
+// ChatGPT implements the same spec and still reads the older
+// `openai/outputTemplate` key, so tools carry both.
+//
+// Clients that don't render views (Cursor, Claude Code, the in-app agent)
+// see exactly what they saw before: no resources, no extra tools, no _meta.
+// Tool results never change: `content` stays the JSON text the model reads.
+//
+// Images reach a view through the app-only tool ui_read_media, which serves
+// only image files the app itself reported in a result this session (frames,
+// contact sheets, clip stills), so a view can't read arbitrary files.
+
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { CLIPS_URI, clipsHtml } from "./clips.mjs";
+import { EDIT_PREVIEW_URI, editPreviewHtml } from "./editPreview.mjs";
+import { RECORDER_URI, recorderHtml } from "./recorder.mjs";
+
+export { CLIPS_URI, EDIT_PREVIEW_URI, RECORDER_URI };
+export const UI_EXTENSION = "io.modelcontextprotocol/ui";
+export const UI_MIME = "text/html;profile=mcp-app";
+/** Deprecated flat key some hosts still read; the official helper sets both. */
+const LEGACY_URI_KEY = "ui/resourceUri";
+
+const RESOURCES = [
+	{
+		uri: EDIT_PREVIEW_URI,
+		name: "edit-preview",
+		title: "Edit preview",
+		description:
+			"The rendered frame or frames across the edit, its length and what it contains, with Open in PandaStudio.",
+		html: editPreviewHtml,
+	},
+	{
+		uri: CLIPS_URI,
+		name: "clips",
+		title: "Clips",
+		description:
+			"A clip set as cards (still, title, hook, score, length) with Open, Export and Remove.",
+		html: clipsHtml,
+	},
+	{
+		uri: RECORDER_URI,
+		name: "recorder",
+		title: "Recorder",
+		description:
+			"The script loaded into PandaStudio's teleprompter (editable, with reading time), Open the recorder again, and I've recorded it.",
+		html: recorderHtml,
+	},
+];
+
+/** Resource-level UI metadata: no network or extra origins needed (images
+ *  arrive as data: URLs, which the default CSP allows). */
+const RESOURCE_UI_META = {
+	ui: { prefersBorder: true, csp: {} },
+	"openai/widgetPrefersBorder": true,
+};
+
+/** Model-visible tools that render a view, with ChatGPT's status lines. */
+export const TOOL_VIEWS = {
+	project_render_frame: {
+		uri: EDIT_PREVIEW_URI,
+		invoking: "Rendering the frame…",
+		invoked: "Frame rendered",
+	},
+	project_render_sheet: {
+		uri: EDIT_PREVIEW_URI,
+		invoking: "Rendering frames…",
+		invoked: "Frames rendered",
+	},
+	preview_show: {
+		uri: EDIT_PREVIEW_URI,
+		invoking: "Opening the preview…",
+		invoked: "Preview ready",
+	},
+	project_edit_summary: {
+		uri: EDIT_PREVIEW_URI,
+		invoking: "Reading the edit…",
+		invoked: "Edit summary ready",
+	},
+	clips_make: { uri: CLIPS_URI, invoking: "Starting clips…", invoked: "Making clips" },
+	clips_get: { uri: CLIPS_URI, invoking: "Loading clips…", invoked: "Clips loaded" },
+	recording_open_recorder: {
+		uri: RECORDER_URI,
+		invoking: "Opening the recorder…",
+		invoked: "Recorder open",
+	},
+};
+
+/** Tools only views call (hidden from the model by UI hosts). */
+export const APP_TOOLS = [
+	{
+		name: "ui_read_media",
+		description:
+			"For PandaStudio's chat views: read images the app returned this session (frames, contact sheets, clip stills) as image content.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				paths: {
+					type: "array",
+					items: { type: "string" },
+					description: "Absolute image paths, up to 24.",
+				},
+			},
+			required: ["paths"],
+		},
+		_meta: {
+			ui: { visibility: ["app"] },
+			"openai/visibility": "private",
+			"openai/widgetAccessible": true,
+		},
+	},
+];
+
+/**
+ * Does this client render MCP Apps views? It says so in its initialize
+ * capabilities (extensions["io.modelcontextprotocol/ui"].mimeTypes). The
+ * in-app agent never does. PANDASTUDIO_MCP_UI=1 / 0 forces it either way
+ * (a host that renders views without advertising them, or to switch off).
+ */
+export function clientSupportsUi(capabilities, { inApp = false, env = process.env } = {}) {
+	const force = String(env.PANDASTUDIO_MCP_UI ?? "").toLowerCase();
+	if (["0", "false", "off", "no"].includes(force)) return false;
+	if (["1", "true", "on", "yes"].includes(force)) return true;
+	if (inApp) return false;
+	const mimeTypes = capabilities?.extensions?.[UI_EXTENSION]?.mimeTypes;
+	return Array.isArray(mimeTypes) && mimeTypes.includes(UI_MIME);
+}
+
+/** _meta for a tool's tools/list entry, or undefined when it has no view. */
+export function toolUiMeta(toolName) {
+	const view = TOOL_VIEWS[toolName];
+	if (!view) return undefined;
+	return {
+		ui: { resourceUri: view.uri },
+		[LEGACY_URI_KEY]: view.uri,
+		"openai/outputTemplate": view.uri,
+		"openai/toolInvocation/invoking": view.invoking,
+		"openai/toolInvocation/invoked": view.invoked,
+		"openai/widgetAccessible": true,
+	};
+}
+
+export function listUiResources() {
+	return RESOURCES.map(({ uri, name, title, description }) => ({
+		uri,
+		name,
+		title,
+		description,
+		mimeType: UI_MIME,
+		_meta: RESOURCE_UI_META,
+	}));
+}
+
+/** resources/read for a ui:// view, or null when the uri isn't one. */
+export function readUiResource(uri, version) {
+	const res = RESOURCES.find((r) => r.uri === uri);
+	if (!res) return null;
+	return {
+		contents: [
+			{ uri: res.uri, mimeType: UI_MIME, text: res.html(version), _meta: RESOURCE_UI_META },
+		],
+	};
+}
+
+// ── Images for views ────────────────────────────────────────────────────
+
+const IMAGE_TYPES = {
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".webp": "image/webp",
+	".gif": "image/gif",
+};
+const MAX_IMAGE_BYTES = 15 * 1024 * 1024;
+const MAX_PATHS = 24;
+const imageType = (p) => IMAGE_TYPES[path.extname(p).toLowerCase()];
+
+/**
+ * Image paths the app reported in tool results this session. Any string
+ * field whose key ends in "path" / "Path" and names an absolute image file
+ * counts (render-frame path, render-sheet sheetPath + frames[].path,
+ * clips[].thumbPath, ...).
+ */
+export class MediaRegistry {
+	constructor(limit = 5000) {
+		this.limit = limit;
+		this.paths = new Set();
+	}
+
+	note(data) {
+		const walk = (value, depth) => {
+			if (!value || typeof value !== "object" || depth > 6) return;
+			if (Array.isArray(value)) {
+				for (const v of value) walk(v, depth + 1);
+				return;
+			}
+			for (const [k, v] of Object.entries(value)) {
+				if (typeof v === "string") {
+					if (/path$/i.test(k) && path.isAbsolute(v) && imageType(v)) this.add(v);
+				} else walk(v, depth + 1);
+			}
+		};
+		walk(data, 0);
+	}
+
+	add(p) {
+		const key = path.resolve(p);
+		this.paths.delete(key);
+		this.paths.add(key);
+		if (this.paths.size > this.limit) this.paths.delete(this.paths.values().next().value);
+	}
+
+	has(p) {
+		return typeof p === "string" && this.paths.has(path.resolve(p));
+	}
+
+	/** The ui_read_media result: one image block per readable path, and
+	 *  structuredContent.items mapping each path to its block (or an error). */
+	async read(paths) {
+		if (!Array.isArray(paths) || paths.length === 0)
+			return {
+				content: [{ type: "text", text: "paths must be a non-empty array" }],
+				isError: true,
+			};
+		const content = [];
+		const items = [];
+		for (const p of paths.slice(0, MAX_PATHS)) {
+			if (typeof p !== "string" || !this.has(p)) {
+				items.push({ path: p, error: "not_available" });
+				continue;
+			}
+			try {
+				const info = await stat(p);
+				if (!info.isFile() || info.size > MAX_IMAGE_BYTES) {
+					items.push({ path: p, error: "too_large" });
+					continue;
+				}
+				const buf = await readFile(p);
+				items.push({ path: p, image: content.length });
+				content.push({ type: "image", data: buf.toString("base64"), mimeType: imageType(p) });
+			} catch {
+				items.push({ path: p, error: "missing" });
+			}
+		}
+		const loaded = items.filter((i) => typeof i.image === "number").length;
+		content.push({ type: "text", text: `${loaded} of ${items.length} images` });
+		return { content, structuredContent: { items } };
+	}
+}