openuispec 0.2.14 → 0.2.16

package/mcp-server/screenshot-shared.ts

@@ -48,10 +48,9 @@ export async function closeBrowser(): Promise<void> {
 
 // ── shared result type ──────────────────────────────────────────────
 
-export interface ScreenshotResult {
-  content: Array<{ type: "text"; text: string } | { type: "image"; data: string; mimeType: string }>;
-  isError?: true;
-}
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+
+export type ScreenshotResult = CallToolResult;
 
 // ── manifest loading ────────────────────────────────────────────────
 

package/mcp-server/screenshot.ts

@@ -8,7 +8,7 @@
 import { spawn, type ChildProcess, execSync } from "node:child_process";
 import { existsSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { createServer, type AddressInfo } from "node:net";
+import { createConnection } from "node:net";
 import YAML from "yaml";
 import { findProjectDir } from "../drift/index.js";
 import { getBrowser, closeBrowser, type ScreenshotResult } from "./screenshot-shared.js";
@@ -24,18 +24,186 @@ export interface ScreenshotOptions {
   full_page?: boolean;
   selector?: string;
   output_dir?: string;
+  init_script?: string;
 }
 
-// ── free port finder ────────────────────────────────────────────────
+// ── framework config table ───────────────────────────────────────────
+
+interface FrameworkConfig {
+  /** Typed discriminant for branching logic */
+  kind: "node" | "bun" | "deno" | "python-django" | "python-flask" | "ruby" | "php" | "go" | "rust" | "java";
+  /** Human-readable name */
+  name: string;
+  /** Files whose presence identifies this framework (checked in webDir) */
+  indicators: string[];
+  /** Default dev port when none is configured */
+  defaultPort: number;
+  /** Command + args to start the dev server; PORT placeholder replaced at runtime */
+  devCommand: string[];
+  /** Install command to run when dependencies are missing (null = skip) */
+  installCommand: string[] | null;
+  /** Package manager env var used to set the port (e.g. PORT, APP_PORT) */
+  portEnvVar: string;
+}
 
-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);
+// Ordered by detection priority (most specific first)
+const FRAMEWORKS: FrameworkConfig[] = [
+  {
+    kind: "bun",
+    name: "Bun",
+    indicators: ["bun.lockb", "bun.lock"],
+    defaultPort: 3000,
+    devCommand: ["bun", "run", "dev"],
+    installCommand: ["bun", "install"],
+    portEnvVar: "PORT",
+  },
+  {
+    kind: "deno",
+    name: "Deno",
+    indicators: ["deno.json", "deno.jsonc"],
+    defaultPort: 8000,
+    devCommand: ["deno", "task", "dev"],
+    installCommand: null,
+    portEnvVar: "PORT",
+  },
+  {
+    kind: "node",
+    name: "Node.js (npm/yarn/pnpm)",
+    indicators: ["package.json"],
+    defaultPort: 3000,
+    devCommand: ["npm", "run", "dev"],
+    installCommand: ["npm", "install"],
+    portEnvVar: "PORT",
+  },
+  {
+    kind: "python-django",
+    name: "Django",
+    indicators: ["manage.py"],
+    defaultPort: 8000,
+    devCommand: ["python", "manage.py", "runserver", "PORT"],
+    installCommand: null,
+    portEnvVar: "PORT",
+  },
+  {
+    kind: "python-flask",
+    name: "Flask / FastAPI",
+    indicators: ["requirements.txt", "Pipfile", "pyproject.toml"],
+    defaultPort: 5000,
+    devCommand: ["python", "-m", "flask", "run", "--port", "PORT"],
+    installCommand: null,
+    portEnvVar: "PORT",
+  },
+  {
+    kind: "ruby",
+    name: "Ruby on Rails",
+    indicators: ["Gemfile", "config/application.rb"],
+    defaultPort: 3000,
+    devCommand: ["bin/rails", "server", "-p", "PORT"],
+    installCommand: ["bundle", "install"],
+    portEnvVar: "PORT",
+  },
+  {
+    kind: "php",
+    name: "PHP (Laravel)",
+    indicators: ["artisan"],
+    defaultPort: 8000,
+    devCommand: ["php", "artisan", "serve", "--port=PORT"],
+    installCommand: null,
+    portEnvVar: "PORT",
+  },
+  {
+    kind: "go",
+    name: "Go",
+    indicators: ["go.mod"],
+    defaultPort: 8080,
+    devCommand: ["go", "run", "."],
+    installCommand: null,
+    portEnvVar: "PORT",
+  },
+  {
+    kind: "rust",
+    name: "Rust (Trunk)",
+    indicators: ["Trunk.toml", "Cargo.toml"],
+    defaultPort: 8080,
+    devCommand: ["trunk", "serve", "--port", "PORT"],
+    installCommand: null,
+    portEnvVar: "PORT",
+  },
+  {
+    kind: "java",
+    name: "Java / Spring Boot",
+    indicators: ["pom.xml", "build.gradle", "build.gradle.kts"],
+    defaultPort: 8080,
+    devCommand: ["./mvnw", "spring-boot:run"],
+    installCommand: null,
+    portEnvVar: "SERVER_PORT",
+  },
+];
+
+// ── framework detection ──────────────────────────────────────────────
+
+function detectFramework(webDir: string): FrameworkConfig {
+  for (const fw of FRAMEWORKS) {
+    if (fw.indicators.some((f) => existsSync(join(webDir, f)))) return fw;
+  }
+  // Fallback: generic Node
+  return FRAMEWORKS.find((f) => f.kind === "node")!;
+}
+
+// ── port resolution ──────────────────────────────────────────────────
+
+/** Parse --port / -p / --port=N from a script string. */
+function parsePortFromScript(script: string): number | null {
+  const m = script.match(/(?:--port|-p)[=\s]+(\d+)/);
+  return m ? parseInt(m[1], 10) : null;
+}
+
+/** Read PORT (or custom var) from .env.local / .env.development / .env. */
+function readEnvPort(webDir: string, varName = "PORT"): number | null {
+  for (const name of [".env.local", ".env.development", ".env"]) {
+    const envPath = join(webDir, name);
+    if (!existsSync(envPath)) continue;
+    try {
+      const re = new RegExp(`^\\s*${varName}\\s*=\\s*(\\d+)`, "m");
+      const m = readFileSync(envPath, "utf-8").match(re);
+      if (m) return parseInt(m[1], 10);
+    } catch { /* skip */ }
+  }
+  return null;
+}
+
+/** Resolve the port this project's dev server will use. */
+function resolvePort(webDir: string, fw: FrameworkConfig): number {
+  // 1. .env files
+  const envPort = readEnvPort(webDir, fw.portEnvVar);
+  if (envPort) return envPort;
+
+  // 2. package.json dev/start script (Node-like only)
+  if (existsSync(join(webDir, "package.json"))) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(webDir, "package.json"), "utf-8"));
+      const scripts: Record<string, string> = pkg.scripts ?? {};
+      for (const name of ["dev", "start", "serve", "develop"]) {
+        if (scripts[name]) {
+          const p = parsePortFromScript(scripts[name]);
+          if (p) return p;
+          break;
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  // 3. Framework default
+  return fw.defaultPort;
+}
+
+function isPortListening(port: number, host = "127.0.0.1"): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = createConnection({ port, host });
+    socket.setTimeout(500);
+    socket.on("connect", () => { socket.destroy(); resolve(true); });
+    socket.on("timeout", () => { socket.destroy(); resolve(false); });
+    socket.on("error", () => resolve(false));
   });
 }
 
@@ -47,18 +215,22 @@ export function findWebAppDir(projectCwd: string): string {
   const manifest = YAML.parse(readFileSync(manifestPath, "utf-8"));
   const projectName = manifest.project?.name ?? "app";
 
+  // Derive indicators from the FRAMEWORKS table so they stay in sync
+  const isWebDir = (d: string) =>
+    FRAMEWORKS.some((fw) => fw.indicators.some((f) => existsSync(join(d, f))));
+
   // 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;
+    if (isWebDir(resolved)) 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;
+  if (isWebDir(defaultDir)) return defaultDir;
 
   throw new Error(
     `Web app not found. Checked:\n` +
@@ -71,78 +243,114 @@ export function findWebAppDir(projectCwd: string): string {
 // ── dev server manager ──────────────────────────────────────────────
 
 interface ServerInstance {
-  process: ChildProcess;
+  process: ChildProcess | null; // null = using an externally running server
   port: number;
   url: string;
 }
 
 const servers = new Map<string, ServerInstance>();
 
-function ensureDepsInstalled(webDir: string): void {
-  if (existsSync(join(webDir, "node_modules"))) return;
+function ensureDepsInstalled(webDir: string, fw: FrameworkConfig): void {
+  if (!fw.installCommand) return;
+  // For Node.js check node_modules; for others always run
+  if (fw.kind === "node" && existsSync(join(webDir, "node_modules"))) return;
   try {
-    execSync("npm install", { cwd: webDir, stdio: "pipe", timeout: 90_000 });
+    execSync(fw.installCommand.join(" "), { cwd: webDir, stdio: "pipe", timeout: 120_000 });
   } catch (err) {
-    throw new Error(`Failed to install web app dependencies in ${webDir}: ${err instanceof Error ? err.message : err}`);
+    throw new Error(`Failed to install dependencies in ${webDir}: ${err instanceof Error ? err.message : err}`);
   }
 }
 
+const stripAnsi = (s: string) => s.replace(/\x1b\[[0-9;]*m/g, "");
+
+/** Poll until the port accepts connections, or the timeout expires. */
+async function waitForPort(port: number, timeoutMs = 60_000): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isPortListening(port)) return true;
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  return false;
+}
+
 async function startDevServer(webDir: string): Promise<ServerInstance> {
   const existing = servers.get(webDir);
   if (existing) {
-    // Verify still running
-    if (existing.process.exitCode === null) return existing;
+    const alive = existing.process === null
+      ? await isPortListening(existing.port)   // external server
+      : existing.process.exitCode === null;     // managed process
+    if (alive) return existing;
     servers.delete(webDir);
   }
 
-  ensureDepsInstalled(webDir);
-  const port = await findFreePort();
+  const fw = detectFramework(webDir);
+  const port = resolvePort(webDir, fw);
+
+  // Always prefer an already-running server on the expected port
+  if (await isPortListening(port)) {
+    const instance: ServerInstance = { process: null, port, url: `http://localhost:${port}` };
+    servers.set(webDir, instance);
+    return instance;
+  }
 
-  const child = spawn("npx", ["vite", "--port", String(port), "--strictPort"], {
+  // Start the dev server for this framework
+  ensureDepsInstalled(webDir, fw);
+
+  // Build command: replace "PORT" placeholder with actual port string
+  const [cmd, ...args] = fw.devCommand.map((part) => part === "PORT" ? String(port) : part);
+
+  // For Node.js, use the project's own dev script from package.json if available
+  let spawnCmd = cmd;
+  let spawnArgs = args;
+  if (fw.kind === "node" && existsSync(join(webDir, "package.json"))) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(webDir, "package.json"), "utf-8"));
+      const scripts: Record<string, string> = pkg.scripts ?? {};
+      const scriptName = ["dev", "start", "serve", "develop"].find((n) => n in scripts);
+      if (scriptName) {
+        spawnCmd = "npm";
+        spawnArgs = ["run", scriptName];
+      }
+    } catch { /* ignore */ }
+  }
+
+  const child = spawn(spawnCmd, spawnArgs, {
     cwd: webDir,
     stdio: ["ignore", "pipe", "pipe"],
-    env: { ...process.env, FORCE_COLOR: "0", BROWSER: "none" },
+    env: { ...process.env, FORCE_COLOR: "0", BROWSER: "none", [fw.portEnvVar]: String(port) },
   });
 
-  // 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)}`));
-      }
-    });
-  });
+  // Collect stderr from the start so we have output for error messages
+  let stderr = "";
+  child.stderr?.on("data", (d: Buffer) => { stderr += d.toString(); });
+
+  // Wait for the port to open (framework-agnostic — no stdout parsing needed)
+  const ready = await waitForPort(port, 60_000);
+
+  if (!ready) {
+    child.kill();
+    throw new Error(
+      `${fw.name} dev server did not open port ${port} within 60s.\n` +
+      (stderr ? `stderr:\n${stripAnsi(stderr).slice(-500)}` : ""),
+    );
+  }
 
-  const instance: ServerInstance = { process: child, port, url };
+  const instance: ServerInstance = { process: child, port, url: `http://localhost:${port}` };
   servers.set(webDir, instance);
   return instance;
 }
 
 // ── browser manager (imported from screenshot-shared.ts) ────────────
 
+// ── init_script URL injection ────────────────────────────────────────
+
+/** Append ?__ous_init=<base64> to a URL, respecting existing query params. */
+function appendInitParam(targetUrl: string, initScript: string): string {
+  const url = new URL(targetUrl);
+  url.searchParams.set("__ous_init", Buffer.from(initScript).toString("base64"));
+  return url.toString();
+}
+
 // ── screenshot capture ──────────────────────────────────────────────
 
 export async function takeScreenshot(
@@ -158,6 +366,7 @@ export async function takeScreenshot(
     full_page = false,
     selector,
     output_dir,
+    init_script,
   } = options;
 
   // 1. Find and start
@@ -181,7 +390,8 @@ export async function takeScreenshot(
     }
 
     const base = server.url.replace(/\/+$/, "");
-    const targetUrl = `${base}${route.startsWith("/") ? "" : "/"}${route}`;
+    let targetUrl = `${base}${route.startsWith("/") ? "" : "/"}${route}`;
+    if (init_script) targetUrl = appendInitParam(targetUrl, init_script);
     await page.goto(targetUrl, { waitUntil: "networkidle2", timeout: 30_000 });
 
     if (wait_for > 0) {
@@ -230,6 +440,7 @@ export async function takeScreenshot(
             full_page,
             selector: selector ?? null,
             path: savedPath ?? null,
+            init_script: init_script ?? null,
           }, null, 2),
         },
       ],
@@ -247,6 +458,7 @@ export interface WebBatchCapture {
   selector?: string;
   full_page?: boolean;
   wait_for?: number;
+  init_script?: string;
 }
 
 export interface WebScreenshotBatchOptions {
@@ -255,6 +467,7 @@ export interface WebScreenshotBatchOptions {
   scale?: number;
   theme?: "light" | "dark";
   output_dir?: string;
+  init_script?: string;
 }
 
 // ── batch screenshot ─────────────────────────────────────────────────
@@ -263,7 +476,7 @@ export async function takeScreenshotBatch(
   projectCwd: string,
   options: WebScreenshotBatchOptions,
 ): Promise<ScreenshotResult> {
-  const { captures, viewport = { width: 1280, height: 800 }, scale = 2, theme, output_dir } = options;
+  const { captures, viewport = { width: 1280, height: 800 }, scale = 2, theme, output_dir, init_script: sharedInitScript } = options;
 
   if (captures.length === 0) {
     return { content: [{ type: "text", text: "No web captures specified." }], isError: true };
@@ -286,10 +499,12 @@ export async function takeScreenshotBatch(
 
     const base = server.url.replace(/\/+$/, "");
     const themeLabel = theme ?? "default";
-    const snapshots: Array<{ screen: string; path: string; data: string }> = [];
+    const snapshots: Array<{ screen: string; path: string; data: string; init_script?: string }> = [];
 
     for (const capture of captures) {
-      const targetUrl = `${base}${capture.route.startsWith("/") ? "" : "/"}${capture.route}`;
+      const effectiveInitScript = capture.init_script ?? sharedInitScript;
+      let targetUrl = `${base}${capture.route.startsWith("/") ? "" : "/"}${capture.route}`;
+      if (effectiveInitScript) targetUrl = appendInitParam(targetUrl, effectiveInitScript);
       await page.goto(targetUrl, { waitUntil: "networkidle2", timeout: 30_000 });
       await new Promise((r) => setTimeout(r, capture.wait_for ?? 1000));
 
@@ -310,7 +525,7 @@ export async function takeScreenshotBatch(
         writeFileSync(savedPath, buffer);
       }
 
-      snapshots.push({ screen: capture.screen, path: savedPath, data: buffer.toString("base64") });
+      snapshots.push({ screen: capture.screen, path: savedPath, data: buffer.toString("base64"), init_script: effectiveInitScript });
     }
 
     const content: ScreenshotResult["content"] = [];
@@ -318,7 +533,7 @@ export async function takeScreenshotBatch(
       content.push({ type: "image" as const, data: s.data, mimeType: "image/png" });
       content.push({
         type: "text" as const,
-        text: JSON.stringify({ screen: s.screen, path: s.path, viewport, scale, theme: themeLabel }, null, 2),
+        text: JSON.stringify({ screen: s.screen, path: s.path, viewport, scale, theme: themeLabel, init_script: s.init_script ?? null }, null, 2),
       });
     }
     return { content };
@@ -329,20 +544,20 @@ export async function takeScreenshotBatch(
 
 // ── cleanup ─────────────────────────────────────────────────────────
 
-export async function shutdownAll() {
+function killAllServers() {
   for (const [, instance] of servers) {
-    try { instance.process.kill(); } catch { /* already dead */ }
+    if (instance.process) {
+      try { instance.process.kill(); } catch { /* already dead */ }
+    }
   }
   servers.clear();
+}
+
+export async function shutdownAll() {
+  killAllServers();
   await closeBrowser();
 }
 
-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("exit", killAllServers);
 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.2.14",
+  "version": "0.2.16",
   "license": "MIT",
   "type": "module",
   "description": "A semantic UI specification format for AI-native, platform-native app development",

package/prepare/index.ts

@@ -172,6 +172,17 @@ export interface PrepareResult {
   shared_layers?: SharedLayerInfo[];
   bootstrap?: PrepareBootstrapBundle;
   spec_contents?: SpecFileContent[];
+  anti_patterns?: {
+    universal: Record<string, string[]>;
+    contract_specific: Record<string, string[]>;
+    project_specific: string[];
+  };
+  design_context?: {
+    personality?: string;
+    complexity: 'restrained' | 'balanced' | 'elaborate';
+    audience?: string;
+    complexity_rule: string;
+  };
   next_steps: string[];
 }
 
@@ -643,9 +654,90 @@ function generationRules(target: string, outputDir: string, manifest: Record<str
     rules.push(`Target "${target}" scope: ${structure.scope}`);
   }
 
+  // Include extra_rules from manifest, filtered by target platform tag
+  const extraRules: string[] = Array.isArray(manifest.generation?.extra_rules)
+    ? manifest.generation.extra_rules.filter((rule: any): rule is string => typeof rule === "string")
+    : [];
+  for (const rule of extraRules) {
+    if (matchesTargetPlatform(rule, target)) rules.push(rule);
+  }
+
   return rules;
 }
 
+function matchesTargetPlatform(item: string, target: string): boolean {
+  const tagMatch = item.match(/^\[([a-z]+)\]/);
+  return !tagMatch || tagMatch[1] === target;
+}
+
+function complexityRule(complexity: string): string {
+  switch (complexity) {
+    case 'restrained':
+      return 'Minimal motion (required state transitions only). No decorative shadows. Clean whitespace. Precise token application. No background effects.';
+    case 'elaborate':
+      return 'Rich animations with staggered reveals. Creative elevation. Platform-specific flourishes.';
+    default:
+      return 'Apply all motion.patterns. Use elevation tokens fully. Standard state animations.';
+  }
+}
+
+function buildDesignContext(manifest: Record<string, any>): PrepareResult['design_context'] {
+  const design = manifest.design;
+  if (!design) return undefined;
+  const complexity = (design.complexity as 'restrained' | 'balanced' | 'elaborate') ?? 'balanced';
+  return {
+    ...(design.personality ? { personality: design.personality } : {}),
+    complexity,
+    ...(design.audience ? { audience: design.audience } : {}),
+    complexity_rule: complexityRule(complexity),
+  };
+}
+
+function buildAntiPatterns(
+  manifest: Record<string, any>,
+  projectDir: string,
+  target: string
+): PrepareResult['anti_patterns'] {
+  // Universal anti-patterns from generation_guidance
+  const universal: Record<string, string[]> = {};
+  const universalRaw = manifest.generation_guidance?.universal_anti_patterns ?? {};
+  for (const [domain, items] of Object.entries(universalRaw)) {
+    if (Array.isArray(items)) {
+      const filtered = (items as string[]).filter((item) => matchesTargetPlatform(item, target));
+      if (filtered.length > 0) universal[domain] = filtered;
+    }
+  }
+
+  // Contract-specific must_avoid
+  const contract_specific: Record<string, string[]> = {};
+  try {
+    const contractsDir = resolve(projectDir, manifest.includes?.contracts ?? './contracts/');
+    if (existsSync(contractsDir)) {
+      for (const file of readdirSync(contractsDir).filter((f) => f.endsWith('.yaml') && !f.startsWith('x_'))) {
+        const content = YAML.parse(readFileSync(join(contractsDir, file), 'utf-8'));
+        const contractName = Object.keys(content)[0];
+        const mustAvoid: string[] = content[contractName]?.generation?.must_avoid ?? [];
+        if (mustAvoid.length > 0) {
+          const filtered = mustAvoid.filter((item: string) => matchesTargetPlatform(item, target));
+          if (filtered.length > 0) contract_specific[contractName] = filtered;
+        }
+      }
+    }
+  } catch { /* skip on error */ }
+
+  // Project-specific avoid from design section
+  const project_specific: string[] = [];
+  const designAvoid: string[] = manifest.design?.avoid ?? [];
+  for (const item of designAvoid) {
+    if (matchesTargetPlatform(item, target)) project_specific.push(item);
+  }
+
+  const hasContent = Object.keys(universal).length > 0 || Object.keys(contract_specific).length > 0 || project_specific.length > 0;
+  if (!hasContent) return undefined;
+
+  return { universal, contract_specific, project_specific };
+}
+
 function localizationConstraints(
   target: string,
   platformConfig?: Pick<PreparePlatformConfig, "framework">
@@ -1228,6 +1320,8 @@ function buildBootstrapPrepareResult(cwd: string, target: string, includeContent
   const outputDirExists = existsSync(outputDir);
   const snapshotPath = join(outputDir, ".openuispec-state.json");
   const snapshotFileExists = existsSync(snapshotPath);
+  const antiPatterns = buildAntiPatterns(manifest, projectDir, target);
+  const designContext = buildDesignContext(manifest);
 
   return {
     mode: "bootstrap",
@@ -1259,6 +1353,8 @@ function buildBootstrapPrepareResult(cwd: string, target: string, includeContent
     items: [],
     ...(sharedLayerInfos.length > 0 ? { shared_layers: sharedLayerInfos } : {}),
     ...(includeContents ? { spec_contents: readAllSpecContents(projectDir) } : {}),
+    ...(antiPatterns ? { anti_patterns: antiPatterns } : {}),
+    ...(designContext ? { design_context: designContext } : {}),
     bootstrap: {
       output_exists: existsSync(outputDir),
       generation_ready: missingDecisions.length === 0 && backendContextReady && !pendingUserConfirmation,

package/schema/component.schema.json

@@ -107,6 +107,11 @@
             "may_handle": {
               "type": "array",
               "items": { "type": "string" }
+            },
+            "must_avoid": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Anti-patterns for AI generators. Strings may start with [web], [ios], or [android] to scope to a platform. Unmarked items apply to all platforms."
             }
           },
           "additionalProperties": false