openuispec 0.1.47 → 0.2.1

package/README.md

@@ -123,6 +123,7 @@ Or run directly: `openuispec mcp`
 | `openuispec_get_contract` | Incremental edits | Get a single contract spec, optionally filtered to one variant |
 | `openuispec_get_tokens` | Incremental edits | Get tokens for a specific category (color, typography, spacing, etc.) |
 | `openuispec_get_locale` | Incremental edits | Get a single locale file, optionally filtered to specific keys |
+| `openuispec_screenshot` | Visual verification | Take a screenshot of the generated web app at a specific route (requires `puppeteer`) |
 
 The server includes **protocol-level instructions** that trigger on UI-related requests independently of CLAUDE.md rules — so even if CLAUDE.md is buried under other project rules, the MCP enforcement still works.
 
@@ -190,7 +191,8 @@ openuispec/
 │   ├── index.ts                        # Entry point
 │   └── init.ts                         # Project scaffolding + AI rules
 ├── mcp-server/                          # MCP server (openuispec-mcp)
-│   └── index.ts                        # Stdio transport, 12 tools
+│   ├── index.ts                        # Stdio transport, 13 tools
+│   └── screenshot.ts                  # Dev server + headless browser screenshot
 ├── check/                               # Composite validation command
 │   └── index.ts                        # Schema + semantic + readiness
 ├── drift/                               # Drift detection (spec change tracking)

package/cli/init.ts

@@ -282,6 +282,7 @@ When the openuispec MCP server is configured, AI assistants should use these too
 | \`openuispec_get_contract\` | Get a single contract spec, optionally filtered to one variant. |
 | \`openuispec_get_tokens\` | Get tokens for a specific category (color, typography, spacing, etc.). |
 | \`openuispec_get_locale\` | Get a single locale file, optionally filtered to specific keys. |
+| \`openuispec_screenshot\` | Take a screenshot of the generated web app at a route (requires \`puppeteer\`). |
 
 ## CLI commands
 

package/examples/social-app/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- openuispec-rules-start -->
-<!-- openuispec-rules-version: 0.1.45 -->
+<!-- openuispec-rules-version: 0.1.47 -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.

package/examples/social-app/CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- openuispec-rules-start -->
-<!-- openuispec-rules-version: 0.1.45 -->
+<!-- openuispec-rules-version: 0.1.47 -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.

package/mcp-server/index.ts

@@ -25,6 +25,7 @@ import { loadTargetDrift } from "../drift/index.js";
 import { readFileSync as fsReadFileSync, existsSync, readdirSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import YAML from "yaml";
+import { takeScreenshot } from "./screenshot.js";
 
 // ── resolve project cwd ──────────────────────────────────────────────
 
@@ -111,6 +112,11 @@ FOCUSED GETTERS (prefer these for incremental edits over read_specs):
 - openuispec_check(target, screens?, contracts?) — scoped audit for specific screens/contracts
 Use read_specs for full-project generation; use focused getters when editing one screen or contract.
 
+VISUAL VERIFICATION:
+- openuispec_screenshot(route, viewport?, theme?) — screenshot the generated web app at a route.
+  Starts the dev server automatically. Use after generation to visually verify UI matches the spec.
+  Requires puppeteer (npm install -g puppeteer).
+
 Skip these tools ONLY when the request is purely non-UI (API logic, database, infrastructure, etc.)
 or explicitly platform-specific polish that doesn't affect shared UI semantics.`,
   }
@@ -622,6 +628,40 @@ server.registerTool(
   }
 );
 
+// ── tool: openuispec_screenshot ──────────────────────────────────────
+
+server.registerTool(
+  "openuispec_screenshot",
+  {
+    description: "Take a screenshot of the generated web app at a specific route. Starts the Vite dev server automatically if needed (first call may take longer). Returns a PNG image for visual verification of generated UI. Requires puppeteer to be installed (npm install -g puppeteer).",
+    inputSchema: {
+      route: z.string().default("/").describe("Route path to navigate to, e.g. '/home', '/settings', '/posts/123'"),
+      viewport: z.object({
+        width: z.number().default(1280),
+        height: z.number().default(800),
+      }).optional().describe("Viewport dimensions. Defaults to 1280x800. Use {width: 375, height: 812} for mobile."),
+      theme: z.enum(["light", "dark"]).optional().describe("Force a color scheme via prefers-color-scheme emulation"),
+      wait_for: z.number().optional().default(1000).describe("Milliseconds to wait after page load before screenshotting (default 1000)"),
+      full_page: z.boolean().optional().default(false).describe("Capture the full scrollable page instead of just the viewport"),
+      selector: z.string().optional().describe("CSS selector to screenshot a specific element instead of the full page"),
+    },
+  },
+  async ({ route, viewport, theme, wait_for, full_page, selector }) => {
+    try {
+      return await takeScreenshot(projectCwd, {
+        route,
+        viewport,
+        theme,
+        wait_for,
+        full_page,
+        selector,
+      });
+    } catch (err) {
+      return toolError(err);
+    }
+  }
+);
+
 // ── start server ─────────────────────────────────────────────────────
 
 export async function startMcpServer() {

package/mcp-server/screenshot.ts

@@ -0,0 +1,268 @@
+/**
+ * Screenshot tool — launches dev server + headless browser, captures pages.
+ *
+ * Both the Vite dev server and the Puppeteer browser are kept alive between
+ * calls and torn down when the MCP server process exits.
+ */
+
+import { spawn, type ChildProcess, execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createServer, type AddressInfo } from "node:net";
+import YAML from "yaml";
+import { findProjectDir } from "../drift/index.js";
+
+// ── types ───────────────────────────────────────────────────────────
+
+export interface ScreenshotOptions {
+  route: string;
+  viewport?: { width: number; height: number };
+  theme?: "light" | "dark";
+  wait_for?: number;
+  full_page?: boolean;
+  selector?: string;
+}
+
+export interface ScreenshotResult {
+  content: Array<{ type: "text"; text: string } | { type: "image"; data: string; mimeType: string }>;
+  isError?: true;
+}
+
+// ── free port finder ────────────────────────────────────────────────
+
+function findFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = createServer();
+    srv.listen(0, () => {
+      const port = (srv.address() as AddressInfo).port;
+      srv.close(() => resolve(port));
+    });
+    srv.on("error", reject);
+  });
+}
+
+// ── web app directory discovery ─────────────────────────────────────
+
+export function findWebAppDir(projectCwd: string): string {
+  const projectDir = findProjectDir(projectCwd);
+  const manifestPath = join(projectDir, "openuispec.yaml");
+  const manifest = YAML.parse(readFileSync(manifestPath, "utf-8"));
+  const projectName = manifest.project?.name ?? "app";
+
+  // Check custom output_dir first
+  const customDir = manifest.generation?.output_dir?.web;
+  if (customDir) {
+    const resolved = resolve(projectDir, customDir);
+    if (existsSync(join(resolved, "package.json"))) return resolved;
+  }
+
+  // Default: generated/web/<project-name>/
+  // Try from the project root (parent of openuispec/)
+  const projectRoot = resolve(projectDir, "..");
+  const defaultDir = join(projectRoot, "generated", "web", projectName);
+  if (existsSync(join(defaultDir, "package.json"))) return defaultDir;
+
+  throw new Error(
+    `Web app not found. Checked:\n` +
+    (customDir ? `  - ${resolve(projectDir, customDir)}\n` : "") +
+    `  - ${defaultDir}\n` +
+    `Generate the web target first, then try again.`,
+  );
+}
+
+// ── dev server manager ──────────────────────────────────────────────
+
+interface ServerInstance {
+  process: ChildProcess;
+  port: number;
+  url: string;
+}
+
+const servers = new Map<string, ServerInstance>();
+
+function ensureDepsInstalled(webDir: string): void {
+  if (existsSync(join(webDir, "node_modules"))) return;
+  try {
+    execSync("npm install", { cwd: webDir, stdio: "pipe", timeout: 90_000 });
+  } catch (err) {
+    throw new Error(`Failed to install web app dependencies in ${webDir}: ${err instanceof Error ? err.message : err}`);
+  }
+}
+
+async function startDevServer(webDir: string): Promise<ServerInstance> {
+  const existing = servers.get(webDir);
+  if (existing) {
+    // Verify still running
+    if (existing.process.exitCode === null) return existing;
+    servers.delete(webDir);
+  }
+
+  ensureDepsInstalled(webDir);
+  const port = await findFreePort();
+
+  const child = spawn("npx", ["vite", "--port", String(port), "--strictPort"], {
+    cwd: webDir,
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env, FORCE_COLOR: "0", BROWSER: "none" },
+  });
+
+  // Wait for "Local:" line from Vite
+  const stripAnsi = (s: string) => s.replace(/\x1b\[[0-9;]*m/g, "");
+
+  const url = await new Promise<string>((resolveUrl, reject) => {
+    const timeout = setTimeout(() => {
+      child.kill();
+      reject(new Error("Vite dev server failed to start within 30s"));
+    }, 30_000);
+
+    let output = "";
+    const onData = (chunk: Buffer) => {
+      output += chunk.toString();
+      const clean = stripAnsi(output);
+      const match = clean.match(/Local:\s+(https?:\/\/[^\s]+)/);
+      if (match) {
+        clearTimeout(timeout);
+        child.stdout?.off("data", onData);
+        child.stderr?.off("data", onData);
+        resolveUrl(match[1]);
+      }
+    };
+    child.stdout?.on("data", onData);
+    child.stderr?.on("data", onData);
+    child.on("error", (err) => { clearTimeout(timeout); reject(err); });
+    child.on("exit", (code) => {
+      clearTimeout(timeout);
+      if (!output.includes("Local:")) {
+        reject(new Error(`Vite exited with code ${code} before ready. Output:\n${output.slice(-500)}`));
+      }
+    });
+  });
+
+  const instance: ServerInstance = { process: child, port, url };
+  servers.set(webDir, instance);
+  return instance;
+}
+
+// ── browser manager ─────────────────────────────────────────────────
+
+let browserInstance: any = null;
+
+async function getBrowser(): Promise<any> {
+  if (browserInstance?.connected) return browserInstance;
+
+  let puppeteer: any;
+  try {
+    puppeteer = await import("puppeteer");
+  } catch {
+    throw new Error(
+      "puppeteer is not installed. Run:\n  npm install -g puppeteer\n" +
+      "or add it to your project's devDependencies.",
+    );
+  }
+
+  browserInstance = await puppeteer.launch({
+    headless: true,
+    args: ["--no-sandbox", "--disable-setuid-sandbox"],
+  });
+  return browserInstance;
+}
+
+// ── screenshot capture ──────────────────────────────────────────────
+
+export async function takeScreenshot(
+  projectCwd: string,
+  options: ScreenshotOptions,
+): Promise<ScreenshotResult> {
+  const {
+    route = "/",
+    viewport = { width: 1280, height: 800 },
+    theme,
+    wait_for = 1000,
+    full_page = false,
+    selector,
+  } = options;
+
+  // 1. Find and start
+  const webDir = findWebAppDir(projectCwd);
+  const server = await startDevServer(webDir);
+  const browser = await getBrowser();
+
+  // 2. Navigate
+  const page = await browser.newPage();
+  try {
+    await page.setViewport({ width: viewport.width, height: viewport.height });
+
+    if (theme) {
+      await page.emulateMediaFeatures([
+        { name: "prefers-color-scheme", value: theme },
+      ]);
+    }
+
+    const base = server.url.replace(/\/+$/, "");
+    const targetUrl = `${base}${route.startsWith("/") ? "" : "/"}${route}`;
+    await page.goto(targetUrl, { waitUntil: "networkidle2", timeout: 30_000 });
+
+    if (wait_for > 0) {
+      await new Promise((r) => setTimeout(r, wait_for));
+    }
+
+    // 3. Screenshot
+    let buffer: Buffer;
+    if (selector) {
+      const element = await page.$(selector);
+      if (!element) {
+        return {
+          content: [{ type: "text", text: `Error: Element not found for selector: ${selector}` }],
+          isError: true,
+        };
+      }
+      buffer = await element.screenshot({ type: "png" });
+    } else {
+      buffer = await page.screenshot({ type: "png", fullPage: full_page });
+    }
+
+    const base64 = buffer.toString("base64");
+
+    return {
+      content: [
+        { type: "image" as const, data: base64, mimeType: "image/png" },
+        {
+          type: "text" as const,
+          text: JSON.stringify({
+            route,
+            url: targetUrl,
+            viewport,
+            theme: theme ?? "default",
+            full_page,
+            selector: selector ?? null,
+          }, null, 2),
+        },
+      ],
+    };
+  } finally {
+    await page.close();
+  }
+}
+
+// ── cleanup ─────────────────────────────────────────────────────────
+
+export async function shutdownAll() {
+  for (const [, instance] of servers) {
+    try { instance.process.kill(); } catch { /* already dead */ }
+  }
+  servers.clear();
+  if (browserInstance) {
+    try { await browserInstance.close(); } catch { /* ignore */ }
+    browserInstance = null;
+  }
+}
+
+process.on("exit", () => {
+  // Sync-only fallback for process exit
+  for (const [, instance] of servers) {
+    try { instance.process.kill(); } catch { /* already dead */ }
+  }
+  servers.clear();
+});
+process.on("SIGINT", () => { shutdownAll().then(() => process.exit(0)); });
+process.on("SIGTERM", () => { shutdownAll().then(() => process.exit(0)); });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openuispec",
-  "version": "0.1.47",
+  "version": "0.2.1",
   "license": "MIT",
   "type": "module",
   "description": "A semantic UI specification format for AI-native, platform-native app development",
@@ -28,7 +28,9 @@
     "openuispec-mcp": "./mcp-server/index.ts"
   },
   "scripts": {
-    "test": "node --import tsx --test tests/*.test.ts",
+    "test": "node --import tsx --test tests/check.test.ts tests/configure-target.test.ts tests/drift-prepare.test.ts tests/init.test.ts tests/mcp-tools.test.ts tests/semantic-lint.test.ts tests/status.test.ts",
+    "test:screenshot": "node --import tsx --test tests/mcp-screenshot.test.ts",
+    "test:all": "node --import tsx --test tests/*.test.ts",
     "validate": "tsx schema/validate.ts",
     "validate:manifest": "tsx schema/validate.ts manifest",
     "validate:tokens": "tsx schema/validate.ts tokens",
@@ -49,6 +51,9 @@
     "tsx": "^4.19.4",
     "yaml": "^2.7.1"
   },
+  "optionalDependencies": {
+    "puppeteer": "^24.39.1"
+  },
   "devDependencies": {
     "@types/node": "^25.5.0",
     "typescript": "^5.8.3"