gesso-vite-plugin 0.6.30 → 0.8.0

package/dist/index.js

@@ -1,3 +1,4 @@
+import { a as blankLiterals, c as firstArgumentName, d as CATALOG_TOOLS, f as ComponentCatalog, i as describedModule, l as importSources, n as declaresChannel, o as findCall, p as mayDeclareComponent, r as describeCalls, s as findCalls, t as ContractReader, u as CATALOG_INSTRUCTIONS } from "./contracts-Dwn5pg-0.js";
 import { defaultClientConditions } from "vite";
 //#region src/agent.ts
 /**
@@ -19,48 +20,218 @@ import { defaultClientConditions } from "vite";
 * Several tabs may be open. The newest to announce itself answers,
 * which is the one a person most likely means, and a tab that closes
 * hands back to the one before it.
+*
+* A few tools are the server's own: the component catalog, which the
+* checker reads here and which an agent should be able to read before
+* any page is open. Those are answered here, and listed alongside the
+* page's; everything else still goes to the page.
+*
+* A page that cannot answer is said to be one, rather than let the
+* agent wait or wonder. The tools the page last listed are remembered
+* (across a restart too, given `memory`), so with no page open they are
+* still listed, and a call of one says no page is open to answer it.
+* And a page takes each request as it arrives (`received`), so one that
+* has gone quiet, a window hidden and paused by its browser, is said to
+* be in moments, not when the call would have timed out.
 */
 /** The path an agent is pointed at. */
 const AGENT_PATH = "/__gesso/mcp";
+/**
+* What the dev server prints when it starts: the endpoint, which any
+* MCP client connects to, and the line to add it in the agents most
+* used from a terminal.
+*/
+function connectLines(name, url) {
+	return [
+		`  ➜  Agents:  ${url}  (MCP, as ${name})`,
+		`             claude mcp add --transport http ${name} ${url}`,
+		`             codex mcp add ${name} --url ${url}`,
+		`             gemini mcp add --transport http ${name} ${url}`
+	].join("\n");
+}
 /** The HMR events, as `connectDevAgent` names them. */
 const EVENTS = {
 	ready: "gesso:agent:ready",
 	request: "gesso:agent:request",
+	/** The page has a request and is answering it. */
+	received: "gesso:agent:received",
 	response: "gesso:agent:response"
 };
+/** What a request sent to a page that went away is answered with, before it is said to the agent. */
+const PAGE_GONE = Symbol("page gone");
 function createAgentBridge(socket, options = {}) {
 	const timeoutMs = options.timeoutMs ?? 13e4;
+	const receiveTimeoutMs = options.receiveTimeoutMs ?? 1e4;
+	const local = options.local;
+	const localNames = new Set(local?.tools.map((tool) => tool.name) ?? []);
 	/** Pages that announced themselves, newest last. */
 	const pages = [];
 	const pending = /* @__PURE__ */ new Map();
+	/** Pages that say when they take a request: one that goes quiet is waited on only `receiveTimeoutMs`. */
+	const receiving = /* @__PURE__ */ new WeakSet();
+	/** What a page last listed, said for it while none is open. */
+	let remembered = options.memory?.read() ?? { tools: [] };
 	let next = 1;
+	/**
+	* How long each tool the page listed says it may wait, under MCP's
+	* `_meta` as `gesso/waitsUpToMs` (gesso-framework's `WAITS_UP_TO`):
+	* a call of one is given that long, and a moment more, where any other
+	* is given `timeoutMs`.
+	*/
+	const waits = /* @__PURE__ */ new Map();
 	socket.on(EVENTS.ready, (_data, client) => {
 		const at = pages.indexOf(client);
 		if (at >= 0) pages.splice(at, 1);
 		pages.push(client);
+		relay({
+			jsonrpc: "2.0",
+			id: "gesso:tools",
+			method: "tools/list",
+			params: {}
+		});
+		relay({
+			jsonrpc: "2.0",
+			id: "gesso:initialize",
+			method: "initialize",
+			params: {
+				protocolVersion: "2025-06-18",
+				capabilities: {},
+				clientInfo: {
+					name: "gesso-vite-plugin",
+					version: "0"
+				}
+			}
+		});
 	});
-	socket.on("vite:ws:disconnect", (_data, client) => {
+	const dropPage = (_data, client) => {
 		const at = pages.indexOf(client);
 		if (at >= 0) pages.splice(at, 1);
+		for (const [id, waiting] of pending) if (waiting.page === client) {
+			pending.delete(id);
+			waiting.resolve(PAGE_GONE);
+		}
+	};
+	socket.on("vite:client:disconnect", dropPage);
+	socket.on("vite:ws:disconnect", dropPage);
+	socket.on(EVENTS.received, (data, client) => {
+		receiving.add(client);
+		pending.get(data.id)?.received?.();
 	});
 	socket.on(EVENTS.response, (data) => {
-		const resolve = pending.get(data.id);
-		if (resolve !== void 0) {
+		const waiting = pending.get(data.id);
+		if (waiting !== void 0) {
 			pending.delete(data.id);
-			resolve(data.response);
+			waiting.resolve(data.response);
 		}
 	});
+	/**
+	* The answer the server gives itself, or undefined to relay. A call
+	* to one of its own tools is always answered here; with no page open,
+	* so are the handshake and the listings, so an agent connected before
+	* the page still reads the catalog, and still sees the page's tools,
+	* as it last listed them, each saying no page is open to answer it.
+	*/
+	const answerHere = (message) => {
+		const request = asRequest(message);
+		if (request === void 0) return;
+		const { id, method, params } = request;
+		if (method === "tools/call" && typeof params.name === "string" && options.gate !== void 0) {
+			const refused = options.gate(params.name, params.arguments);
+			if (refused !== void 0) return Promise.resolve(failed(id, refused));
+		}
+		if (local !== void 0 && method === "tools/call" && typeof params.name === "string" && localNames.has(params.name)) {
+			const args = params.arguments;
+			return local.call(params.name, args).then((result) => ({
+				jsonrpc: "2.0",
+				id,
+				result
+			}));
+		}
+		if (pages.length > 0) return;
+		const pageTools = remembered.tools.filter((tool) => !localNames.has(tool.name));
+		if (local === void 0 && pageTools.length === 0) return;
+		const instructions = [remembered.instructions, local?.instructions].filter((text) => text !== void 0 && text !== "");
+		switch (method) {
+			case "initialize": return Promise.resolve({
+				jsonrpc: "2.0",
+				id,
+				result: {
+					protocolVersion: typeof params.protocolVersion === "string" ? params.protocolVersion : "2025-06-18",
+					capabilities: {
+						tools: {},
+						resources: {}
+					},
+					serverInfo: {
+						name: "gesso",
+						version: "0.0.0"
+					},
+					...instructions.length === 0 ? {} : { instructions: instructions.join("\n\n") }
+				}
+			});
+			case "tools/list": return Promise.resolve({
+				jsonrpc: "2.0",
+				id,
+				result: { tools: [...local?.tools ?? [], ...pageTools] }
+			});
+			case "tools/call":
+				if (typeof params.name === "string" && pageTools.some((tool) => tool.name === params.name)) return Promise.resolve(failed(id, `No window of the app is open to answer ${params.name}: it was closed, or it is reloading (a page that lost the dev server reconnects when it comes back). Open the app from this dev server, or bring its window forward and reload it if it is blank, then call ${params.name} again.`));
+				return;
+			case "ping": return Promise.resolve({
+				jsonrpc: "2.0",
+				id,
+				result: {}
+			});
+			case "resources/list": return Promise.resolve({
+				jsonrpc: "2.0",
+				id,
+				result: { resources: [] }
+			});
+			case "resources/templates/list": return Promise.resolve({
+				jsonrpc: "2.0",
+				id,
+				result: { resourceTemplates: [] }
+			});
+			default: return;
+		}
+	};
 	const relay = (message) => {
 		const page = pages[pages.length - 1];
 		const id = next++;
+		const request = asRequest(message);
+		const tool = request?.method === "tools/call" && typeof request.params.name === "string" ? request.params.name : null;
+		const called = tool === null ? void 0 : waits.get(tool);
+		const limit = called === void 0 ? timeoutMs : Math.max(timeoutMs, called + 1e4);
 		return new Promise((resolve) => {
 			const timer = setTimeout(() => {
 				pending.delete(id);
-				resolve(rpcError(message, -32001, `The page did not answer within ${Math.round(timeoutMs / 1e3)} seconds.`));
-			}, timeoutMs);
-			pending.set(id, (response) => {
+				resolve(rpcError(message, -32001, `The page did not answer within ${Math.round(limit / 1e3)} seconds.`));
+			}, limit);
+			const quiet = receiving.has(page) ? setTimeout(() => {
+				pending.delete(id);
 				clearTimeout(timer);
-				resolve(response);
+				const text = `The app's window did not take ${tool ?? "the request"} within ${Math.round(receiveTimeoutMs / 1e3)} seconds: it is most likely hidden or minimised, and paused by its browser, or it is stuck. Bring the window forward (reload it if it is blank), then call ${tool ?? "again"}${tool === null ? "" : " again"}.`;
+				resolve(request === void 0 || tool === null ? rpcError(message, -32001, text) : failed(request.id, text));
+			}, receiveTimeoutMs) : void 0;
+			pending.set(id, {
+				page,
+				received: () => clearTimeout(quiet),
+				resolve: (response) => {
+					clearTimeout(timer);
+					clearTimeout(quiet);
+					if (response === PAGE_GONE) {
+						resolve(rpcError(message, -32001, "The page closed before it answered (it may have reloaded); call again."));
+						return;
+					}
+					if (request?.method === "tools/list") {
+						noteWaits(response);
+						remember({ tools: listed(response) });
+					}
+					if (request?.method === "initialize") {
+						const instructions = response?.result?.instructions;
+						remember({ instructions: typeof instructions === "string" ? instructions : void 0 });
+					}
+					resolve(response);
+				}
 			});
 			page.send(EVENTS.request, {
 				id,
@@ -68,6 +239,27 @@ function createAgentBridge(socket, options = {}) {
 			});
 		});
 	};
+	/** Keeps what a page said of itself, for while none is open. */
+	const remember = (part) => {
+		const instructions = "instructions" in part ? part.instructions : remembered.instructions;
+		const now = {
+			tools: part.tools ?? remembered.tools,
+			...instructions === void 0 ? {} : { instructions }
+		};
+		if (JSON.stringify(now) === JSON.stringify(remembered)) return;
+		remembered = now;
+		try {
+			options.memory?.write(now);
+		} catch {}
+	};
+	const noteWaits = (response) => {
+		const tools = response?.result?.tools;
+		if (!Array.isArray(tools)) return;
+		for (const tool of tools) {
+			const wait = tool._meta?.["gesso/waitsUpToMs"];
+			if (typeof tool.name === "string" && typeof wait === "number") waits.set(tool.name, wait);
+		}
+	};
 	return {
 		get connected() {
 			return pages.length > 0;
@@ -99,6 +291,11 @@ function createAgentBridge(socket, options = {}) {
 					return;
 				}
 				const notification = typeof message === "object" && message !== null && !("id" in message);
+				const own = answerHere(message);
+				if (own !== void 0) {
+					own.then((answer) => send(response, 200, "application/json", JSON.stringify(answer)));
+					return;
+				}
 				if (pages.length === 0) {
 					if (notification) {
 						send(response, 202);
@@ -107,7 +304,7 @@ function createAgentBridge(socket, options = {}) {
 					send(response, 200, "application/json", JSON.stringify(rpcError(message, -32e3, "No page is running the application. Open it in a browser from this dev server; the agent bridge runs in the page, because that is where the channels are.")));
 					return;
 				}
-				relay(message).then((answer) => {
+				relay(message).then((answer) => local === void 0 ? answer : mergeLocal(message, answer, local)).then((answer) => {
 					if (answer === null || answer === void 0) send(response, 202);
 					else send(response, 200, "application/json", JSON.stringify(answer));
 				});
@@ -120,6 +317,25 @@ function send(response, status, type, body) {
 	if (type !== void 0) response.setHeader("content-type", type);
 	response.end(body);
 }
+/** A tool call that could not be made, as MCP says one: a result marked as an error, which the agent reads. */
+function failed(id, text) {
+	return {
+		jsonrpc: "2.0",
+		id,
+		result: {
+			content: [{
+				type: "text",
+				text
+			}],
+			isError: true
+		}
+	};
+}
+/** The tools a page's `tools/list` answer lists, or none. */
+function listed(response) {
+	const tools = response?.result?.tools;
+	return Array.isArray(tools) ? tools.filter((tool) => typeof tool?.name === "string") : [];
+}
 function rpcError(message, code, text) {
 	const id = message?.id;
 	return {
@@ -148,713 +364,48 @@ const SHELL_BRIDGE = `function __gessoAgent(app) {
   return app;
 }
 `;
-//#endregion
-//#region src/source.ts
-const IDENTIFIER = /[A-Za-z0-9_$]/;
-/**
-* A copy of `code` in which every string, template literal, regular
-* expression body and comment is spaces, and everything else is
-* untouched.
-*
-* Same length as the input, and newlines are kept, so an index into
-* the result is an index into the original and a line number is still
-* a line number. String and template delimiters are kept as well, so a
-* specifier can be found by its quotes here and read from there.
-*/
-function blankLiterals(code) {
-	const out = code.split("");
-	let index = 0;
-	let regexAllowed = true;
-	const blank = (from, to) => {
-		for (let i = from; i < to; i++) if (out[i] !== "\n") out[i] = " ";
+/** A JSON-RPC request, with an id and params, or undefined for anything else. */
+function asRequest(message) {
+	if (typeof message !== "object" || message === null || Array.isArray(message)) return;
+	const { id, method, params } = message;
+	if (typeof id !== "string" && typeof id !== "number" || typeof method !== "string") return;
+	return {
+		id,
+		method,
+		params: typeof params === "object" && params !== null ? params : {}
 	};
-	while (index < code.length) {
-		const char = code[index];
-		if (char === "/" && code[index + 1] === "/") {
-			const end = code.indexOf("\n", index);
-			blank(index, end === -1 ? code.length : end);
-			index = end === -1 ? code.length : end;
-			continue;
-		}
-		if (char === "/" && code[index + 1] === "*") {
-			const end = code.indexOf("*/", index + 2);
-			const stop = end === -1 ? code.length : end + 2;
-			blank(index, stop);
-			index = stop;
-			continue;
-		}
-		if (char === "\"" || char === "'") {
-			const end = closingQuote(code, index, char);
-			blank(index + 1, end);
-			index = end + 1;
-			regexAllowed = false;
-			continue;
-		}
-		if (char === "`") {
-			const end = closingQuote(code, index, "`");
-			blank(index + 1, end);
-			index = end + 1;
-			regexAllowed = false;
-			continue;
-		}
-		if (char === "/" && regexAllowed) {
-			const end = closingRegex(code, index);
-			if (end !== -1) {
-				blank(index + 1, end);
-				index = end + 1;
-				regexAllowed = false;
-				continue;
-			}
-		}
-		if (!/\s/.test(char)) regexAllowed = !IDENTIFIER.test(char) && char !== ")" && char !== "]";
-		index++;
-	}
-	return out.join("");
-}
-/** The index of the quote that closes the one at `open`, or the end. */
-function closingQuote(code, open, quote) {
-	for (let i = open + 1; i < code.length; i++) {
-		if (code[i] === "\\") {
-			i++;
-			continue;
-		}
-		if (code[i] === quote) return i;
-	}
-	return code.length;
-}
-/**
-* The index of the slash closing a regular expression, or -1 when the
-* slash was division after all.
-*
-* A newline inside means it was not a regular expression, which is the
-* cheap test that keeps `a / b` and `c / d` on one line from swallowing
-* everything between them.
-*/
-function closingRegex(code, open) {
-	let inClass = false;
-	for (let i = open + 1; i < code.length; i++) {
-		const char = code[i];
-		if (char === "\\") {
-			i++;
-			continue;
-		}
-		if (char === "\n") return -1;
-		if (char === "[") {
-			inClass = true;
-			continue;
-		}
-		if (char === "]") {
-			inClass = false;
-			continue;
-		}
-		if (char === "/" && !inClass) return i;
-	}
-	return -1;
-}
-/**
-* Every call of `name` in the module, in source order.
-*
-* A bare name has to stand alone: `renderRoot(` matches, `myRenderRoot(`
-* and `thing.renderRoot(` do not, because a method of that name on some
-* other object is not the framework's function. A name written with a
-* leading dot is the opposite and matches only the method call:
-* `.useService(` is how a builder chain reads and the only way it is
-* ever written.
-*/
-function findCalls(code, name, blank = blankLiterals(code)) {
-	const member = name.startsWith(".");
-	const bare = member ? name.slice(1) : name;
-	const sites = [];
-	let from = 0;
-	for (;;) {
-		const at = blank.indexOf(bare, from);
-		if (at === -1) return sites;
-		from = at + bare.length;
-		const before = at === 0 ? "" : blank[at - 1];
-		if (member ? before !== "." : before !== "" && (IDENTIFIER.test(before) || before === ".")) continue;
-		let cursor = from;
-		while (cursor < blank.length && /\s/.test(blank[cursor])) cursor++;
-		if (blank[cursor] !== "(") continue;
-		const argsEnd = matchingBracket(blank, cursor);
-		if (argsEnd === -1) continue;
-		sites.push({
-			start: at,
-			argsStart: cursor + 1,
-			argsEnd,
-			end: argsEnd + 1
-		});
-		from = argsEnd + 1;
-	}
-}
-/** The first call of `name`, or null. */
-function findCall(code, name, blank = blankLiterals(code)) {
-	return findCalls(code, name, blank)[0] ?? null;
-}
-/** The index of the bracket closing the one at `open`, or -1. */
-function matchingBracket(blank, open) {
-	const stack = [];
-	for (let i = open; i < blank.length; i++) {
-		const char = blank[i];
-		if (char === "(" || char === "[" || char === "{") {
-			stack.push(char);
-			continue;
-		}
-		if (char === ")" || char === "]" || char === "}") {
-			stack.pop();
-			if (stack.length === 0) return i;
-		}
-	}
-	return -1;
-}
-/**
-* The identifier a call's first argument is, or null when the argument
-* is anything more complicated than a name.
-*
-* `renderRoot(SegueApp)` is the shape every entry in this repository
-* writes and the only one that can be hot-replaced, because a
-* replacement has to be looked up by name in the module that changed.
-* `renderRoot(<App x={1} />)` is legal and gets no HMR wiring, which
-* the plugin says rather than guessing.
-*/
-function firstArgumentName(code, call, blank = blankLiterals(code)) {
-	const first = (splitTopLevel(blank.slice(call.argsStart, call.argsEnd))[0] ?? "").trim();
-	return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(first) ? first : null;
-}
-/** Splits an argument list on its top-level commas. */
-function splitTopLevel(text) {
-	const parts = [];
-	let depth = 0;
-	let start = 0;
-	for (let i = 0; i < text.length; i++) {
-		const char = text[i];
-		if (char === "(" || char === "[" || char === "{") depth++;
-		else if (char === ")" || char === "]" || char === "}") depth--;
-		else if (char === "," && depth === 0) {
-			parts.push(text.slice(start, i));
-			start = i + 1;
-		}
-	}
-	parts.push(text.slice(start));
-	return parts;
-}
-/**
-* Which module each imported name came from: local name to specifier,
-* exactly as the import wrote it.
-*
-* Default and namespace imports are recorded under their local names
-* too, so `import App from './App'` and `import * as app from './App'`
-* both answer. What the map does not carry is whether the binding is a
-* type, because `import type` is stripped before this runs in every
-* configuration that matters and a type never reaches a call.
-*/
-function importSources(code, blank = blankLiterals(code)) {
-	const sources = /* @__PURE__ */ new Map();
-	const statement = /\bimport\b([\s\S]*?)\bfrom\b\s*(['"])/g;
-	for (;;) {
-		const match = statement.exec(blank);
-		if (match === null) return sources;
-		const quote = match[2];
-		const open = match.index + match[0].length;
-		const close = code.indexOf(quote, open);
-		if (close === -1) continue;
-		const specifier = code.slice(open, close);
-		for (const local of importedNames(match[1])) sources.set(local, specifier);
-		statement.lastIndex = close + 1;
-	}
-}
-/** The local names an import clause binds. */
-function importedNames(clause) {
-	const names = [];
-	const braces = clause.indexOf("{");
-	const head = (braces === -1 ? clause : clause.slice(0, braces)).replace(/\btype\b/g, "");
-	for (const part of head.split(",")) {
-		const named = /^\s*(?:\*\s*as\s*)?([A-Za-z_$][A-Za-z0-9_$]*)\s*$/.exec(part);
-		if (named !== null) names.push(named[1]);
-	}
-	if (braces !== -1) {
-		const close = clause.lastIndexOf("}");
-		const list = clause.slice(braces + 1, close === -1 ? clause.length : close);
-		for (const part of list.split(",")) {
-			const aliased = /^\s*(?:type\s+)?[A-Za-z_$][A-Za-z0-9_$]*\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*$/.exec(part);
-			const plain = /^\s*(?:type\s+)?([A-Za-z_$][A-Za-z0-9_$]*)\s*$/.exec(part);
-			const name = aliased?.[1] ?? plain?.[1];
-			if (name !== void 0) names.push(name);
-		}
-	}
-	return names;
-}
-//#endregion
-//#region src/contracts.ts
-/** The functions that declare a channel. */
-const DECLARATIONS = ["channel", "defineChannel"];
-/**
-* Whether a module declares a channel, without asking the checker.
-*
-* The checker is a process round trip per question, and every module
-* the application has passes through `transform`, so this is the gate:
-* a call to `channel` or `defineChannel` imported from
-* `gesso-framework`. A module that re-exports a token someone else
-* declared is not a contract, and the module that declared it is the
-* one described.
-*/
-function declaresChannel(code) {
-	if (!code.includes("gesso-framework")) return false;
-	const blank = blankLiterals(code);
-	const imports = importSources(code, blank);
-	return DECLARATIONS.some((name) => imports.get(name) === "gesso-framework" && (findCalls(code, name, blank).length > 0 || new RegExp(`(?<![\\w$.])${name}\\s*<`).test(blank)));
-}
-/**
-* The code appended to a contract module.
-*
-* An import at the bottom is still hoisted, and appending rather than
-* rewriting leaves every line the author wrote where they wrote it, so
-* the module's source map needs nothing.
-*/
-function describeCalls(channels) {
-	const lines = ["import { describeChannel as __gessoDescribeChannel } from 'gesso-framework';"];
-	for (const [name, schema] of channels) lines.push(`__gessoDescribeChannel(${name}, ${JSON.stringify(schema)});`);
-	return `\n${lines.join("\n")}\n`;
 }
 /**
-* A module that describes channels when it is imported, for a bundle
-* this plugin never sees.
-*
-* The plugin describes a contract by appending to it as Vite bundles
-* it. An Electrobun main process is bundled by Electrobun's own build,
-* which takes no plugins, so there the description is written ahead of
-* time instead: `gesso-channels` reads the contracts with the same
-* checker and writes this module, and the main process imports it once.
-* A token is imported from its contract, so the schema lands on the
-* same object the application serves.
-*
-* `outFile` and every `file` are absolute POSIX paths.
-*/
-function describedModule(contracts, outFile) {
-	const lines = [
-		"// Written by gesso-channels from the channel contracts it names below.",
-		"// Run it again after changing a contract rather than editing this file.",
-		"import { describeChannel } from 'gesso-framework';"
-	];
-	const from = outFile.slice(0, outFile.lastIndexOf("/"));
-	for (const contract of contracts) if (contract.channels.size > 0) {
-		const names = [...contract.channels.keys()].join(", ");
-		lines.push(`import { ${names} } from '${importPath(from, contract.file)}';`);
-	}
-	for (const contract of contracts) for (const [name, schema] of contract.channels) lines.push("", `describeChannel(${name}, ${JSON.stringify(schema, null, 2)});`);
-	return `${lines.join("\n")}\n`;
-}
-/** `./Counter` from `/app/src/shared` to `/app/src/shared/Counter.ts`, without the extension. */
-function importPath(fromDir, file) {
-	const from = fromDir.split("/").filter(Boolean);
-	const to = file.replace(/\.[cm]?[jt]sx?$/, "").split("/").filter(Boolean);
-	let shared = 0;
-	while (shared < from.length && shared < to.length - 1 && from[shared] === to[shared]) shared++;
-	const up = from.length - shared;
-	const rest = to.slice(shared).join("/");
-	return up === 0 ? `./${rest}` : `${"../".repeat(up)}${rest}`;
-}
-/**
-* The checker, held open across reads.
-*
-* Spawning it and loading a project costs about a hundred
-* milliseconds; a question after that costs well under one. So one
-* reader lives as long as the dev server or the build, is told which
-* files changed between reads, and is closed at the end, because the
-* process it holds would otherwise keep the build from exiting.
+* The page's answer with the server's own tools in it: listed after the
+* page's, and the instructions joined, so an agent sees one server.
 */
-var ContractReader = class {
-	api = null;
-	changed = /* @__PURE__ */ new Set();
-	/** Each contract's tsconfig, found once. */
-	configs = /* @__PURE__ */ new Map();
-	/**
-	* @param fs Callbacks the checker reads through before the disk, for
-	*   a spec that keeps its project in memory.
-	*/
-	ts;
-	cwd;
-	fs;
-	constructor(ts, cwd, fs) {
-		this.ts = ts;
-		this.cwd = cwd;
-		this.fs = fs;
-	}
-	/** A file changed on disk since the last read. */
-	invalidate(file) {
-		this.changed.add(file);
-	}
-	/** Every channel `file` exports, described. */
-	read(file) {
-		const api = this.api ??= new this.ts.API({
-			cwd: this.cwd,
-			...this.fs === void 0 ? {} : { fs: this.fs }
-		});
-		this.changed.add(file);
-		let snapshot = api.updateSnapshot({ fileChanges: { changed: [...this.changed] } });
-		this.changed.clear();
-		let config = this.configs.get(file);
-		if (config === void 0) {
-			config = api.updateSnapshot({ openFiles: [file] }).getDefaultProjectForFile(file)?.configFileName;
-			snapshot = api.updateSnapshot({
-				...config === void 0 ? {} : { openProjects: [config] },
-				closeFiles: [file]
-			});
-			if (config !== void 0) this.configs.set(file, config);
-		}
-		const project = config === void 0 ? void 0 : snapshot.getProject(config);
-		const source = project?.program.getSourceFile(file);
-		if (project === void 0 || source === void 0) return {
-			channels: /* @__PURE__ */ new Map(),
-			warnings: [`TypeScript has no project that includes ${file}.`]
-		};
-		const checker = project.checker;
-		const module = checker.getSymbolAtLocation(source);
-		const describer = new Describer(this.ts, checker);
-		const channels = /* @__PURE__ */ new Map();
-		for (const exported of module === void 0 ? [] : checker.getExportsOfModule(module)) {
-			const type = checker.getTypeOfSymbol(exported);
-			if (type === void 0 || type.getSymbol()?.name !== "ChannelToken") continue;
-			const [view, commands] = checker.getTypeArguments(type);
-			channels.set(exported.name, describer.channel(exported, view, commands));
-		}
+function mergeLocal(message, answer, local) {
+	const method = asRequest(message)?.method;
+	const result = answer?.result;
+	if (result === void 0 || method !== "tools/list" && method !== "initialize") return answer;
+	if (method === "tools/list" && Array.isArray(result.tools)) {
+		const taken = new Set(result.tools.map((tool) => tool.name));
+		const added = local.tools.filter((tool) => !taken.has(tool.name));
 		return {
-			channels,
-			warnings: describer.warnings
-		};
-	}
-	close() {
-		this.api?.close();
-		this.api = null;
-	}
-};
-/**
-* Library types that are objects to the checker and not plain data to
-* a channel. They compare by reference, so `provide` rejects them on
-* their first value; describing their methods as properties would be
-* describing something that never arrives.
-*/
-const NOT_PLAIN = /* @__PURE__ */ new Set([
-	"Date",
-	"Map",
-	"ReadonlyMap",
-	"Set",
-	"ReadonlySet",
-	"WeakMap",
-	"WeakSet",
-	"Promise",
-	"RegExp",
-	"Error",
-	"ArrayBuffer",
-	"SharedArrayBuffer",
-	"DataView",
-	"Blob",
-	"File",
-	"URL",
-	"Int8Array",
-	"Uint8Array",
-	"Uint8ClampedArray",
-	"Int16Array",
-	"Uint16Array",
-	"Int32Array",
-	"Uint32Array",
-	"Float32Array",
-	"Float64Array",
-	"BigInt64Array",
-	"BigUint64Array"
-]);
-/**
-* Bytes, which a command may carry and a view key may not.
-*
-* A command's argument is structured-cloned onto the owning thread, and
-* a typed array or an `ArrayBuffer` clones as itself: a file a person
-* dropped crosses as its bytes, with no encoding pass on the render
-* thread. A view key is diffed, and a differ that compares bytes by
-* reference reports a change on every emission, so there they stay
-* unplain. In a command's schema they are a base64 string, which is
-* what an agent can write, tagged with the type the command expects so
-* the agent surface can turn the string back into it.
-*/
-const BINARY = /* @__PURE__ */ new Set([
-	"ArrayBuffer",
-	"Int8Array",
-	"Uint8Array",
-	"Uint8ClampedArray",
-	"Int16Array",
-	"Uint16Array",
-	"Int32Array",
-	"Uint32Array",
-	"Float32Array",
-	"Float64Array",
-	"BigInt64Array",
-	"BigUint64Array"
-]);
-/** Turns checker types into JSON Schema for one module's channels. */
-var Describer = class {
-	warnings = [];
-	flags;
-	/** Describing a command's parameters, where bytes are allowed; see `BINARY`. */
-	inCommand = false;
-	/** Types being described right now, to notice a type that contains itself. */
-	inProgress = /* @__PURE__ */ new Set();
-	/** Types found to contain themselves, which are described once in `$defs`. */
-	recursive = /* @__PURE__ */ new Set();
-	/** `$defs` for the schema being built. Reset per root, so each schema stands alone. */
-	defs = /* @__PURE__ */ new Map();
-	defNames = /* @__PURE__ */ new Map();
-	ts;
-	checker;
-	constructor(ts, checker) {
-		this.ts = ts;
-		this.checker = checker;
-		this.flags = ts.TypeFlags;
-	}
-	channel(token, view, commands) {
-		const out = {
-			view: this.root(view, `${token.name}.view`),
-			commands: {}
-		};
-		const description = this.checker.getDocumentationCommentOfSymbol(token);
-		if (description !== "") out.description = description;
-		if (this.checker.getJsDocTagsOfSymbol(token).some((tag) => tag.name === "hidden")) out.internal = true;
-		const hidden = this.checker.getPropertiesOfType(view).filter((key) => this.checker.getJsDocTagsOfSymbol(key).some((tag) => tag.name === "hidden")).map((key) => key.name);
-		if (hidden.length > 0) out.hidden = hidden;
-		if (commands !== void 0) for (const command of this.checker.getPropertiesOfType(commands)) {
-			const described = this.command(command, `${token.name}.commands.${command.name}`);
-			if (described !== null) out.commands[command.name] = described;
-		}
-		return out;
-	}
-	/** A schema that stands alone: its own `$defs`, if anything in it recurs. */
-	root(type, path) {
-		this.defs = /* @__PURE__ */ new Map();
-		const schema = this.describe(type, path);
-		if (this.defs.size > 0) return {
-			...schema,
-			$defs: Object.fromEntries(this.defs)
-		};
-		return schema;
-	}
-	command(symbol, path) {
-		const type = this.checker.getTypeOfSymbol(symbol);
-		const signatures = type === void 0 ? [] : this.checker.getSignaturesOfType(type, this.ts.SignatureKind.Call);
-		if (signatures.length === 0) {
-			this.warnings.push(`${path} is not a function, so it is not a command an agent can send.`);
-			return null;
-		}
-		if (signatures.length > 1) this.warnings.push(`${path} is overloaded; only its first signature is described.`);
-		const signature = signatures[0];
-		const tags = this.checker.getJsDocTagsOfSymbol(symbol);
-		const parameters = signature.getParameters();
-		this.defs = /* @__PURE__ */ new Map();
-		const properties = {};
-		const required = [];
-		this.inCommand = true;
-		parameters.forEach((parameter, index) => {
-			const parameterType = this.checker.getTypeOfSymbol(parameter);
-			const optional = parameterType !== void 0 && this.includesUndefined(parameterType);
-			const schema = parameterType === void 0 ? {} : this.describe(parameterType, `${path}(${parameter.name})`);
-			const description = this.parameterDescription(parameter, tags);
-			properties[parameter.name] = description === "" ? schema : {
-				...schema,
-				description
-			};
-			const rest = signature.hasRestParameter && index === parameters.length - 1;
-			if (!optional && !rest) required.push(parameter.name);
-		});
-		this.inCommand = false;
-		const input = {
-			type: "object",
-			properties,
-			additionalProperties: false
-		};
-		if (required.length > 0) input.required = required;
-		if (this.defs.size > 0) input.$defs = Object.fromEntries(this.defs);
-		const out = {
-			parameters: parameters.map((parameter) => parameter.name),
-			input
-		};
-		const description = this.checker.getDocumentationCommentOfSymbol(symbol);
-		if (description !== "") out.description = description;
-		if (signature.hasRestParameter) out.rest = true;
-		for (const annotation of [
-			"destructive",
-			"idempotent",
-			"confirm",
-			"hidden"
-		]) if (tags.some((tag) => tag.name === annotation)) out[annotation] = true;
-		return out;
-	}
-	/**
-	* A parameter's own comment, or failing that its `@param` line.
-	*
-	* The checker attaches `@param` text to the parameter of a method
-	* signature. A command written as a property, `move: (from: number)
-	* => void`, keeps its comment on the property, so the tag is read
-	* from there instead.
-	*/
-	parameterDescription(parameter, tags) {
-		const own = this.checker.getDocumentationCommentOfSymbol(parameter);
-		if (own !== "") return own;
-		for (const tag of tags) {
-			const match = tag.name === "param" ? /^\s*(\S+)\s*(?:-\s*)?([\s\S]*)$/.exec(tag.text ?? "") : null;
-			if (match !== null && match[1] === parameter.name) return match[2].trim();
-		}
-		return "";
-	}
-	includesUndefined(type) {
-		const { Undefined, Void } = this.flags;
-		if (type.isUnionType()) return (type.getTypes() ?? []).some((member) => (member.flags & (Undefined | Void)) !== 0);
-		return (type.flags & (Undefined | Void)) !== 0;
-	}
-	describe(type, path) {
-		const f = this.flags;
-		const flags = type.flags;
-		if (flags & (f.Any | f.Unknown)) return {};
-		if (flags & f.Never) {
-			this.warnings.push(`${path} is never, which describes no value. An empty array literal is never[] unless it says what it holds: write \`[] as Row[]\`.`);
-			return { not: {} };
-		}
-		if (flags & (f.String | f.TemplateLiteral | f.StringMapping)) return { type: "string" };
-		if (flags & f.Number) return { type: "number" };
-		if (flags & f.Boolean) return { type: "boolean" };
-		if (flags & f.Null) return { type: "null" };
-		if (flags & (f.Undefined | f.Void)) return {};
-		if (flags & f.BooleanLiteral) return { const: type.intrinsicName === "true" };
-		if (flags & (f.StringLiteral | f.NumberLiteral)) return { const: type.value };
-		if (flags & (f.BigInt | f.BigIntLiteral | f.ESSymbol | f.UniqueESSymbol)) return this.unplain(path, flags & f.BigIntLike ? "a bigint" : "a symbol");
-		if (type.isUnionType()) return this.union(type, path);
-		if (flags & f.TypeParameter) return {};
-		if (flags & (f.Object | f.Intersection)) {
-			if (this.checker.isArrayType(type)) {
-				const [element] = this.checker.getTypeArguments(type);
-				return {
-					type: "array",
-					items: element === void 0 ? {} : this.describe(element, `${path}[]`)
-				};
-			}
-			if (this.checker.isTupleType(type)) return this.tuple(type, path);
-			return this.named(type, path);
-		}
-		this.warnings.push(`${path} has a type this reader does not describe, so it is left open.`);
-		return {};
-	}
-	/**
-	* A union, with `undefined` taken out (optionality is said by
-	* `required`), `true | false` folded back into `boolean`, and a union
-	* of nothing but literals written as an `enum`.
-	*/
-	union(type, path) {
-		const f = this.flags;
-		let members = (type.getTypes() ?? []).filter((member) => (member.flags & (f.Undefined | f.Void)) === 0);
-		const booleans = members.filter((member) => member.flags & f.BooleanLiteral);
-		const schemas = [];
-		if (booleans.length === 2) {
-			members = members.filter((member) => !(member.flags & f.BooleanLiteral));
-			schemas.push({ type: "boolean" });
-		}
-		if (members.length > 0 && schemas.length === 0 && members.every((member) => member.flags & (f.StringLiteral | f.NumberLiteral))) return { enum: members.map((member) => member.value) };
-		members.sort((a, b) => Number((a.flags & f.Null) !== 0) - Number((b.flags & f.Null) !== 0));
-		schemas.push(...members.map((member) => this.describe(member, path)));
-		return schemas.length === 1 ? schemas[0] : { anyOf: schemas };
-	}
-	/**
-	* An object type, described once however often it appears, and by
-	* reference when it contains itself.
-	*/
-	named(type, path) {
-		const id = type.id;
-		if (this.inProgress.has(id)) {
-			this.recursive.add(id);
-			return { $ref: `#/$defs/${this.defName(type)}` };
-		}
-		this.inProgress.add(id);
-		const schema = this.object(type, path);
-		this.inProgress.delete(id);
-		if (this.recursive.has(id)) {
-			const name = this.defName(type);
-			this.defs.set(name, schema);
-			return { $ref: `#/$defs/${name}` };
-		}
-		return schema;
-	}
-	defName(type) {
-		let name = this.defNames.get(type.id);
-		if (name === void 0) {
-			const base = (type.getAliasSymbol() ?? type.getSymbol())?.name ?? "Type";
-			name = new Set(this.defNames.values()).has(base) ? `${base}${type.id}` : base;
-			this.defNames.set(type.id, name);
-		}
-		return name;
-	}
-	object(type, path) {
-		const checker = this.checker;
-		const symbolName = type.getSymbol()?.name;
-		if (symbolName !== void 0 && this.inCommand && BINARY.has(symbolName)) return {
-			type: "string",
-			contentEncoding: "base64",
-			"x-gesso-binary": symbolName
-		};
-		if (symbolName === "SharedArrayBuffer" && !this.inCommand) return {
-			type: "string",
-			description: "Shared memory, shown as its size.",
-			"x-gesso-shared": true
-		};
-		if (symbolName !== void 0 && NOT_PLAIN.has(symbolName)) return this.unplain(path, `a ${symbolName}`);
-		if (type.objectFlags & this.ts.ObjectFlags.Class) return this.unplain(path, `an instance of ${symbolName ?? "a class"}`);
-		if (checker.getSignaturesOfType(type, this.ts.SignatureKind.Call).length > 0) return this.unplain(path, "a function");
-		const properties = {};
-		const required = [];
-		for (const property of checker.getPropertiesOfType(type)) {
-			const propertyType = checker.getTypeOfSymbol(property);
-			const at = `${path}.${property.name}`;
-			if (propertyType === void 0) {
-				properties[property.name] = {};
-				continue;
+			...answer,
+			result: {
+				...result,
+				tools: [...result.tools, ...added]
 			}
-			const schema = this.describe(propertyType, at);
-			const description = checker.getDocumentationCommentOfSymbol(property);
-			properties[property.name] = description === "" ? schema : {
-				...schema,
-				description
-			};
-			if (!((property.flags & this.ts.SymbolFlags.Optional) !== 0 || this.includesUndefined(propertyType))) required.push(property.name);
-		}
-		const schema = {
-			type: "object",
-			properties
 		};
-		if (required.length > 0) schema.required = required;
-		const index = checker.getIndexInfosOfType(type).find((info) => info.keyType.flags & this.flags.String);
-		if (index !== void 0) schema.additionalProperties = this.describe(index.valueType, `${path}[key]`);
-		return schema;
 	}
-	tuple(type, path) {
-		const elements = this.checker.getTypeArguments(type);
-		const elementFlags = type.getTarget().elementFlags ?? [];
-		const { Required, Rest } = this.ts.ElementFlags;
-		const prefixItems = [];
-		let items = false;
-		let minItems = 0;
-		elements.forEach((element, index) => {
-			const schema = this.describe(element, `${path}[${index}]`);
-			if (elementFlags[index] & Rest) items = schema;
-			else {
-				prefixItems.push(schema);
-				if (elementFlags[index] & Required) minItems = index + 1;
-			}
-		});
+	if (method === "initialize" && local.instructions !== void 0) {
+		const given = typeof result.instructions === "string" ? `${result.instructions}\n\n` : "";
 		return {
-			type: "array",
-			prefixItems,
-			items,
-			minItems
+			...answer,
+			result: {
+				...result,
+				instructions: `${given}${local.instructions}`
+			}
 		};
 	}
-	unplain(path, what) {
-		this.warnings.push(`${path} is ${what}, which is not plain data and cannot cross a channel.`);
-		return {};
-	}
-};
+	return answer;
+}
 //#endregion
 //#region src/render.ts
 const MARKER$1 = "/* gesso-vite-plugin: hot replacement */";
@@ -1164,6 +715,8 @@ function gesso(options = {}) {
 	/** The checker, started by the first contract, or null once it is known to be unavailable. */
 	let contracts;
 	let root = "";
+	/** The project's components, offered to an agent while the dev server runs. */
+	let catalog = null;
 	const readerFor = (warn) => contracts ??= import("typescript/unstable/sync").then((ts) => new ContractReader(ts, root), () => {
 		warn("Channels are not described, because TypeScript 7 is not installed. Add `typescript` (7 or later) to devDependencies, or pass `channelSchemas: false` to stop this message.");
 		return null;
@@ -1230,18 +783,35 @@ function gesso(options = {}) {
 		*/
 		configureServer(server) {
 			if (options.agent === false) return;
-			const bridge = createAgentBridge(server.ws);
+			const catalogOptions = typeof options.catalog === "object" ? options.catalog : {};
+			const catalogRoot = catalogOptions.root ?? root;
+			catalog = options.catalog === false ? null : new ComponentCatalog(() => readerFor((message) => server.config.logger.warn(message)), catalogRoot, {
+				tsconfig: absolute(catalogRoot, catalogOptions.tsconfig ?? "tsconfig.json"),
+				libraries: () => resolveLibraries(server, root, catalogOptions.libraries ?? []),
+				...catalogOptions.exclude === void 0 ? {} : { exclude: catalogOptions.exclude }
+			});
+			if (catalogRoot !== root) server.watcher.add(catalogRoot);
+			const bridge = createAgentBridge(server.ws, {
+				memory: pageMemory(root),
+				...options.agentGate === void 0 ? {} : { gate: options.agentGate },
+				...catalog === null ? {} : { local: {
+					tools: CATALOG_TOOLS,
+					call: (name, args) => catalog.call(name, args),
+					instructions: [CATALOG_INSTRUCTIONS, ...options.agentInstructions === void 0 ? [] : [options.agentInstructions]].join("\n\n")
+				} }
+			});
 			server.middlewares.use((request, response, next) => bridge.middleware(request, response, next));
 			server.httpServer?.once("listening", () => {
 				const base = server.resolvedUrls?.local[0];
 				if (base !== void 0) {
 					const url = new URL(AGENT_PATH, base).href;
-					server.config.logger.info(`  ➜  Agents:  ${url}\n             claude mcp add --transport http ${agentName(server.config.root)} ${url}`);
+					server.config.logger.info(connectLines(options.agentName ?? agentName(server.config.root), url));
 				}
 			});
 		},
-		watchChange(id) {
-			contracts?.then((reader) => reader?.invalidate(id));
+		watchChange(id, change) {
+			contracts?.then((reader) => reader?.invalidate(id, change.event));
+			catalog?.invalidate();
 		},
 		/**
 		* The checker is a child process, and a build that left it running
@@ -1356,6 +926,31 @@ function scanShell(options) {
 		}
 	};
 }
+/** A path from the root, made absolute; an absolute one is kept. */
+function absolute(root, path) {
+	return path.startsWith("/") ? path : `${root.replace(/\/+$/, "")}/${path.replace(/^\.\//, "")}`;
+}
+/**
+* Where each named library's components are declared: the module Vite
+* resolves its name to, or the declaration file beside it when that is
+* built JavaScript, which says nothing about types. A name that does
+* not resolve is reported and left out.
+*/
+async function resolveLibraries(server, root, names) {
+	const out = [];
+	for (const name of names) {
+		const resolved = await server.pluginContainer.resolveId(name, absolute(root, "index.html"));
+		if (resolved === null) {
+			server.config.logger.warn(`[gesso] The catalog library ${name} does not resolve from ${root}, so it is left out.`);
+			continue;
+		}
+		out.push({
+			name,
+			file: resolved.id.replace(/\?.*$/, "").replace(/\.([cm]?)js$/, ".d.$1ts")
+		});
+	}
+	return out;
+}
 /** A name for the MCP server: the project's directory, which is what a person calls the app. */
 function agentName(root) {
 	return (root.split("/").filter(Boolean).pop() ?? "gesso").replace(/[^A-Za-z0-9_-]/g, "-");
@@ -1419,7 +1014,19 @@ async function firstResolved(context, importer, names) {
 	for (const name of names) if (await context.resolve(name, importer) !== null) return name;
 	return null;
 }
+/**
+* What each project's page last listed, by root. Kept in the module,
+* which Node holds across Vite's own restarts (a config saved), so a
+* restarted server lists the page's tools before the page reconnects.
+*/
+const pagesListed = /* @__PURE__ */ new Map();
+function pageMemory(root) {
+	return {
+		read: () => pagesListed.get(root),
+		write: (page) => pagesListed.set(root, page)
+	};
+}
 //#endregion
-export { ContractReader, blankLiterals, gesso as default, gesso, describedModule, findCall, findCalls, findShellCall, firstArgumentName, importSources, transformRenderWorker, transformShell, transformSyncShell, workerConditions };
+export { ComponentCatalog, ContractReader, blankLiterals, gesso as default, gesso, describedModule, findCall, findCalls, findShellCall, firstArgumentName, importSources, mayDeclareComponent, transformRenderWorker, transformShell, transformSyncShell, workerConditions };
 
 //# sourceMappingURL=index.js.map