@elyracode/design-tools 0.9.13 → 0.9.15

package/extensions/index.ts

@@ -1,5 +1,5 @@
 import { execSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import type { ExtensionAPI } from "@elyracode/coding-agent";
@@ -157,6 +157,18 @@ export default function (elyra: ExtensionAPI): void {
 						"Use mobile viewport (375x812) (default: false)",
 				}),
 			),
+			selector: Type.Optional(
+				Type.String({
+					description:
+						"CSS selector to screenshot a specific element instead of the viewport (e.g., '#app', '.card'). Useful for focusing on the component you just changed.",
+				}),
+			),
+			full_page: Type.Optional(
+				Type.Boolean({
+					description:
+						"Capture the full scrollable page instead of just the viewport (default: false)",
+				}),
+			),
 		}),
 		execute: async (_toolCallId, params) => {
 			try {
@@ -164,61 +176,63 @@ export default function (elyra: ExtensionAPI): void {
 					mkdirSync(PREVIEW_DIR, { recursive: true });
 				}
 
-				const screenshotPath = join(
-					PREVIEW_DIR,
-					`screenshot-${Date.now()}.png`,
+				const stamp = Date.now();
+				const screenshotPath = join(PREVIEW_DIR, `screenshot-${stamp}.png`);
+				const consolePath = join(PREVIEW_DIR, `console-${stamp}.json`);
+				const configPath = join(PREVIEW_DIR, `capture-${stamp}.json`);
+				const width = params.mobile ? 375 : (params.width ?? 1280);
+				const height = params.mobile ? 812 : (params.height ?? 800);
+
+				// Pass all parameters via a JSON config file rather than string
+				// interpolation, so a hostile URL/selector can't inject into the script.
+				writeFileSync(
+					configPath,
+					JSON.stringify({
+						url: params.url,
+						width,
+						height,
+						selector: params.selector ?? null,
+						fullPage: params.full_page ?? false,
+						screenshotPath,
+						consolePath,
+					}),
+					"utf-8",
 				);
-				const width = params.mobile
-					? 375
-					: (params.width ?? 1280);
-				const height = params.mobile
-					? 812
-					: (params.height ?? 800);
-
-				// Try Puppeteer first (if installed globally or in project)
-				let captured = false;
 
+				let captured = false;
 				try {
-					// Write a small Node script that uses puppeteer
 					const scriptPath = join(PREVIEW_DIR, "capture.mjs");
 					writeFileSync(
 						scriptPath,
 						`
+import { readFileSync, writeFileSync } from 'node:fs';
 import puppeteer from 'puppeteer';
+const cfg = JSON.parse(readFileSync(process.argv[2], 'utf-8'));
 const browser = await puppeteer.launch({ headless: true, args: ['--no-sandbox'] });
 const page = await browser.newPage();
-await page.setViewport({ width: ${width}, height: ${height} });
-await page.goto('${params.url}', { waitUntil: 'networkidle2', timeout: 15000 });
-await page.screenshot({ path: '${screenshotPath}', fullPage: false });
+const logs = [];
+page.on('console', (m) => { if (m.type() === 'error' || m.type() === 'warning') logs.push(m.type() + ': ' + m.text()); });
+page.on('pageerror', (e) => logs.push('pageerror: ' + e.message));
+page.on('requestfailed', (r) => logs.push('requestfailed: ' + r.url() + ' ' + (r.failure()?.errorText ?? '')));
+await page.setViewport({ width: cfg.width, height: cfg.height });
+await page.goto(cfg.url, { waitUntil: 'networkidle2', timeout: 15000 });
+const target = cfg.selector ? await page.$(cfg.selector) : null;
+if (cfg.selector && !target) throw new Error('Selector not found: ' + cfg.selector);
+if (target) await target.screenshot({ path: cfg.screenshotPath });
+else await page.screenshot({ path: cfg.screenshotPath, fullPage: cfg.fullPage });
+writeFileSync(cfg.consolePath, JSON.stringify(logs));
 await browser.close();
 `,
 						"utf-8",
 					);
 
-					execSync(`node "${scriptPath}"`, {
+					execSync(`node "${scriptPath}" "${configPath}"`, {
 						timeout: 30000,
 						stdio: "pipe",
 					});
 					captured = existsSync(screenshotPath);
 				} catch {
-					// Puppeteer not available
-				}
-
-				// Fallback: macOS screencapture (if the URL is a local file)
-				if (
-					!captured &&
-					process.platform === "darwin" &&
-					params.url.startsWith("file://")
-				) {
-					try {
-						execSync(
-							`screencapture -x -C "${screenshotPath}"`,
-							{ timeout: 10000 },
-						);
-						captured = existsSync(screenshotPath);
-					} catch {
-						// screencapture failed
-					}
+					// Puppeteer not available or capture failed
 				}
 
 				if (!captured) {
@@ -226,14 +240,32 @@ await browser.close();
 						content: [
 							{
 								type: "text",
-								text: `Could not capture screenshot. Install Puppeteer for automated screenshots:\n\nnpm install -g puppeteer\n\nOr take a manual screenshot and paste it into the chat.`,
+								text: "Could not capture screenshot. This tool needs a headless browser: install Puppeteer (npm install -g puppeteer) and ensure the URL is reachable (start your dev server first). You can also paste a screenshot into the chat manually.",
 							},
 						],
 						details: {},
 					};
 				}
 
-				// Read the screenshot and return as image content
+				// Collect any captured browser errors/warnings.
+				let consoleNote = "";
+				try {
+					if (existsSync(consolePath)) {
+						const logs = JSON.parse(readFileSync(consolePath, "utf-8")) as string[];
+						if (logs.length > 0) {
+							consoleNote = `\n\nBrowser console (${logs.length} error/warning):\n${logs.slice(0, 20).join("\n")}`;
+						}
+					}
+				} catch {
+					// ignore console-read failures
+				}
+
+				const scope = params.selector
+					? `element "${params.selector}"`
+					: params.full_page
+						? "full page"
+						: `viewport ${width}x${height}`;
+
 				const imageData = readFileSync(screenshotPath);
 				const base64 = imageData.toString("base64");
 
@@ -246,10 +278,10 @@ await browser.close();
 						},
 						{
 							type: "text",
-							text: `Screenshot captured (${width}x${height}): ${screenshotPath}\nAnalyze the screenshot for visual issues: alignment, spacing, color contrast, responsive layout, text readability.`,
+							text: `Screenshot captured (${scope}): ${screenshotPath}\nAnalyze it for visual issues: alignment, spacing, color contrast, responsive layout, text readability. A visible bug is often a JS error — check the console output below.${consoleNote}`,
 						},
 					],
-					details: { path: screenshotPath, width, height },
+					details: { path: screenshotPath, width, height, selector: params.selector ?? null },
 				};
 			} catch (error) {
 				const msg =
@@ -267,7 +299,84 @@ await browser.close();
 		},
 	});
 
-	// ── Tool 3: design_system_check ──
+	// ── Tool 3: design_diff ──
+	// Compare two screenshots and have the model describe the visual delta.
+	elyra.registerTool({
+		name: "design_diff",
+		label: "Design Diff",
+		description:
+			"Compare two screenshots (a before and an after) and analyze the visual difference. " +
+			"Returns both images so you can describe exactly what changed and flag unintended visual " +
+			"regressions after a code change. If no paths are given, uses the two most recent screenshots " +
+			"captured by screenshot_url.",
+		parameters: Type.Object({
+			before: Type.Optional(
+				Type.String({
+					description: "Path to the 'before' screenshot (default: second-most-recent capture)",
+				}),
+			),
+			after: Type.Optional(
+				Type.String({
+					description: "Path to the 'after' screenshot (default: most-recent capture)",
+				}),
+			),
+		}),
+		execute: async (_toolCallId, params) => {
+			try {
+				let beforePath = params.before;
+				let afterPath = params.after;
+
+				// Fall back to the two most recent screenshots in the preview dir.
+				if (!beforePath || !afterPath) {
+					const shots = existsSync(PREVIEW_DIR)
+						? readdirSync(PREVIEW_DIR)
+								.filter((f) => f.startsWith("screenshot-") && f.endsWith(".png"))
+								.map((f) => join(PREVIEW_DIR, f))
+								.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)
+						: [];
+					afterPath = afterPath ?? shots[0];
+					beforePath = beforePath ?? shots[1];
+				}
+
+				if (!beforePath || !afterPath || !existsSync(beforePath) || !existsSync(afterPath)) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: "Need two screenshots to diff. Capture a 'before' with screenshot_url, make your change, capture an 'after', then call design_diff again (or pass explicit before/after paths).",
+							},
+						],
+						details: {},
+					};
+				}
+
+				const beforeB64 = readFileSync(beforePath).toString("base64");
+				const afterB64 = readFileSync(afterPath).toString("base64");
+
+				return {
+					content: [
+						{ type: "text", text: `BEFORE (${beforePath}):` },
+						{ type: "image", data: beforeB64, mimeType: "image/png" },
+						{ type: "text", text: `AFTER (${afterPath}):` },
+						{ type: "image", data: afterB64, mimeType: "image/png" },
+						{
+							type: "text",
+							text: "Compare the two images. Describe what changed visually (layout, spacing, color, typography, added/removed elements). Flag anything that looks like an unintended regression versus an intended change.",
+						},
+					],
+					details: { before: beforePath, after: afterPath },
+				};
+			} catch (error) {
+				const msg = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text", text: `Design diff failed: ${msg}` }],
+					details: {},
+				};
+			}
+		},
+	});
+
+	// ── Tool 4: design_system_check ──
 	// Analyze Tailwind classes for consistency
 	elyra.registerTool({
 		name: "design_system_check",
@@ -453,6 +562,7 @@ await browser.close();
 			const options = [
 				"Preview -- render HTML/Tailwind in the browser",
 				"Screenshot -- capture a web page for visual QA",
+				"Diff -- compare before/after screenshots",
 				"Design Check -- analyze Tailwind classes for consistency",
 			];
 
@@ -470,6 +580,10 @@ await browser.close();
 				elyra.sendUserMessage(
 					"I want to take a screenshot of a page for visual QA. What URL should I capture?",
 				);
+			} else if (selected.startsWith("Diff")) {
+				elyra.sendUserMessage(
+					"I want to compare before/after screenshots of a UI change. Capture a before, make the change, capture an after, then diff them.",
+				);
 			} else if (selected.startsWith("Design Check")) {
 				elyra.sendUserMessage(
 					"I want to check a file for Tailwind design consistency. Which file should I analyze?",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elyracode/design-tools",
-  "version": "0.9.13",
+  "version": "0.9.15",
   "description": "Elyra extension for UI design -- live browser preview, screenshot capture, and visual QA",
   "type": "module",
   "keywords": [