feat: replace Playwright with agent-browser for deterministic pipeline

- Phase 0 now uses agent-browser CLI for screenshots, color extraction,
  brand/font/icon detection — fully deterministic, zero Claude API cost
- Add section catalog and page renderers for structured page generation
- Add pixel-diff module for visual verification
- Add finalizeProject() to adapter interface to fix theme toggle and
  hydration issues after template writing
- Next.js adapter patches layout.tsx with suppressHydrationWarning and
  touches globals.css to trigger Turbopack recompilation
- Remove playwright-core dependency

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: lucianfialho

.mcp.json

@@ -6,7 +6,10 @@
     },
     "reactbits": {
       "command": "npx",
-      "args": ["-y", "reactbits-mcp-server"]
+      "args": [
+        "-y",
+        "reactbits-mcp-server"
+      ]
     },
     "shadcn": {
       "type": "http",
@@ -18,11 +21,17 @@
     },
     "hugeicons": {
       "command": "npx",
-      "args": ["-y", "@hugeicons/mcp-server"]
+      "args": [
+        "-y",
+        "@hugeicons/mcp-server"
+      ]
     },
     "motion-dev": {
       "command": "npx",
-      "args": ["-y", "motion-mcp"]
+      "args": [
+        "-y",
+        "motion-mcp"
+      ]
     }
   }
 }

packages/cli/package.json

@@ -35,9 +35,9 @@
     "@clack/prompts": "^1.0.1",
     "@guataiba/isac-core": "workspace:*",
     "@guataiba/isac-nextjs": "workspace:*",
+    "agent-browser": "^0.16.1",
     "chalk": "^5.4.1",
-    "commander": "^13.1.0",
-    "playwright-core": "^1.50.0"
+    "commander": "^13.1.0"
   },
   "devDependencies": {
     "@types/node": "^22.13.0",

packages/cli/tsup.config.ts

@@ -12,5 +12,4 @@ export default defineConfig({
     js: "#!/usr/bin/env node",
   },
   noExternal: ["@guataiba/isac-core", "@guataiba/isac-nextjs"],
-  external: ["playwright-core"],
 });

packages/core/package.json

@@ -36,11 +36,15 @@
     "url": "https://github.com/guataiba/isac-cli/issues"
   },
   "dependencies": {
+    "agent-browser": "^0.16.1",
     "chalk": "^5.4.1",
-    "playwright-core": "^1.50.0"
+    "pixelmatch": "^6.0.0",
+    "pngjs": "^7.0.0",
+    "zod": "^3.24.0"
   },
   "devDependencies": {
     "@types/node": "^22.13.0",
+    "@types/pngjs": "^6.0.5",
     "tsup": "^8.4.0",
     "typescript": "^5.7.0",
     "vitest": "^4.0.18"

packages/core/src/__tests__/prompts.test.ts

@@ -4,36 +4,39 @@ import { getScreenshotPrompt } from "../prompts/screenshot-capturer.js";
 describe("Core prompt generation", () => {
   const testUrl = "https://example.com";
 
-  it("design-system mode prompt does NOT contain take_screenshot", () => {
+  it("design-system mode prompt uses agent-browser (no screenshots)", () => {
     const prompt = getScreenshotPrompt(testUrl, "design-system");
     expect(prompt).toContain(testUrl);
-    expect(prompt).toContain("navigate_page");
-    expect(prompt).toContain("1440px");
+    expect(prompt).toContain("agent-browser open");
+    expect(prompt).toContain("1440");
     // Font extraction steps
     expect(prompt).toContain("font-data.json");
-    expect(prompt).toContain("evaluate_script");
+    expect(prompt).toContain("agent-browser eval");
     expect(prompt).toContain("public/fonts");
-    // Should NOT contain screenshot instructions
-    expect(prompt).not.toContain("take_screenshot");
+    // Should NOT contain actual screenshot capture instructions (full-page.png)
     expect(prompt).not.toContain("full-page.png");
+    // Should NOT reference chrome-devtools MCP
+    expect(prompt).not.toContain("mcp__chrome-devtools");
   });
 
   it("default mode is design-system (no screenshots)", () => {
     const prompt = getScreenshotPrompt(testUrl);
-    expect(prompt).not.toContain("take_screenshot");
+    expect(prompt).not.toContain("full-page.png");
   });
 
-  it("replicate mode prompt CONTAINS take_screenshot", () => {
+  it("replicate mode prompt CONTAINS screenshot commands", () => {
     const prompt = getScreenshotPrompt(testUrl, "replicate");
     expect(prompt).toContain(testUrl);
-    expect(prompt).toContain("navigate_page");
-    expect(prompt).toContain("take_screenshot");
+    expect(prompt).toContain("agent-browser open");
+    expect(prompt).toContain("agent-browser screenshot --full");
     expect(prompt).toContain("full-page.png");
-    expect(prompt).toContain("1440px");
+    expect(prompt).toContain("1440");
     // Font extraction steps
     expect(prompt).toContain("font-data.json");
-    expect(prompt).toContain("evaluate_script");
+    expect(prompt).toContain("agent-browser eval");
     expect(prompt).toContain("public/fonts");
+    // Should NOT reference chrome-devtools MCP
+    expect(prompt).not.toContain("mcp__chrome-devtools");
   });
 
   it("color extraction is NOT in the prompt (handled by Playwright)", () => {

packages/core/src/__tests__/tools.test.ts

@@ -1,6 +1,5 @@
 import { describe, it, expect } from "vitest";
 import {
-  CHROME_DEVTOOLS_TOOLS,
   PHASE_0_TOOLS,
   PHASE_1B_TOOLS,
   PHASE_2_TOOLS,
@@ -9,26 +8,14 @@ import {
 } from "../pipeline/tools.js";
 
 describe("Tool sets", () => {
-  it("CHROME_DEVTOOLS_TOOLS has 18 tools", () => {
-    expect(CHROME_DEVTOOLS_TOOLS).toHaveLength(18);
-  });
-
-  it("all chrome-devtools tools have correct prefix", () => {
-    for (const tool of CHROME_DEVTOOLS_TOOLS) {
-      expect(tool).toMatch(/^mcp__chrome-devtools__/);
+  it("Phase 0 uses Bash for agent-browser (no MCP tools)", () => {
+    expect(PHASE_0_TOOLS).toEqual(["Read", "Write", "Bash"]);
+    for (const tool of PHASE_0_TOOLS) {
+      expect(tool).not.toMatch(/^mcp__/);
     }
   });
 
-  it("Phase 0 includes chrome-devtools tools, Read, Write, and Bash (for font extraction)", () => {
-    expect(PHASE_0_TOOLS).toContain("mcp__chrome-devtools__navigate_page");
-    expect(PHASE_0_TOOLS).toContain("mcp__chrome-devtools__take_screenshot");
-    expect(PHASE_0_TOOLS).toContain("mcp__chrome-devtools__evaluate_script");
-    expect(PHASE_0_TOOLS).toContain("Read");
-    expect(PHASE_0_TOOLS).toContain("Write");
-    expect(PHASE_0_TOOLS).toContain("Bash");
-  });
-
-  it("Phase 1b has only file tools (no chrome-devtools)", () => {
+  it("Phase 1b has only file tools", () => {
     expect(PHASE_1B_TOOLS).toEqual(["Read", "Write", "Edit", "Glob", "Bash"]);
   });
 
@@ -39,17 +26,17 @@ describe("Tool sets", () => {
     expect(PHASE_2_TOOLS).not.toContain("Bash");
   });
 
-  it("Phase 3 has full file tools but no chrome-devtools", () => {
+  it("Phase 3 has full file tools but no MCP", () => {
     expect(PHASE_3_TOOLS).toEqual(["Read", "Write", "Edit", "Glob", "Grep", "Bash"]);
     for (const tool of PHASE_3_TOOLS) {
       expect(tool).not.toMatch(/^mcp__/);
     }
   });
 
-  it("Phase 4 includes chrome-devtools tools", () => {
-    expect(PHASE_4_TOOLS).toContain("mcp__chrome-devtools__take_screenshot");
-    expect(PHASE_4_TOOLS).toContain("mcp__chrome-devtools__navigate_page");
-    expect(PHASE_4_TOOLS).toContain("Read");
-    expect(PHASE_4_TOOLS).toContain("Bash");
+  it("Phase 4 uses Bash for agent-browser (no MCP tools)", () => {
+    expect(PHASE_4_TOOLS).toEqual(["Read", "Bash"]);
+    for (const tool of PHASE_4_TOOLS) {
+      expect(tool).not.toMatch(/^mcp__/);
+    }
   });
 });

packages/core/src/__tests__/types.test.ts

@@ -31,7 +31,7 @@ const mockAdapter: FrameworkAdapter = {
   validateTokenExtraction: () => ({ valid: true }),
   postProcessTokenExtraction: () => {},
   validateDesignSystem: () => ({ valid: true }),
-  generateDesignSystemFallback: () => {},
+  generateDesignSystemData: () => {},
   validateImplementation: () => ({ valid: true }),
   collectCreatedFiles: () => [],
 };

packages/core/src/adapter.ts

@@ -1,4 +1,5 @@
 import type { PipelineMode } from "./pipeline/types.js";
+import type { PagePlan } from "./catalog/index.js";
 
 /**
  * Describes a template file that the adapter wants written to disk.
@@ -145,15 +146,39 @@ export interface FrameworkAdapter {
   validateDesignSystem(cwd: string): PhaseValidation;
 
   /**
-   * Phase 1B fallback: Generate design system data from globals.css if Claude failed.
+   * Phase 1B: Generate design system data deterministically from globals.css.
+   * This is now the primary path (no Claude needed).
    */
-  generateDesignSystemFallback(cwd: string, url: string): void;
+  generateDesignSystemData(cwd: string, url: string): void;
+
+  /**
+   * @deprecated Use generateDesignSystemData instead. Kept for backward compatibility.
+   */
+  generateDesignSystemFallback?(cwd: string, url: string): void;
+
+  /**
+   * Phase 2 (v2): Returns the prompt for structured JSON page planning.
+   * If not implemented, falls back to getPagePlannerPrompt() with Markdown output.
+   */
+  getPagePlannerPromptV2?(screenshotDir: string, catalogTypes: string[]): string;
+
+  /**
+   * Phase 3 (deterministic): Render page.tsx from a validated PagePlan.
+   * If not implemented, falls back to Claude-based Phase 3.
+   */
+  renderPageFromPlan?(cwd: string, plan: PagePlan): string;
 
   /**
    * Phase 3 validation: Check that implementation files exist.
    */
   validateImplementation(cwd: string): PhaseValidation;
 
+  /**
+   * Final cleanup after all files are written: clear build cache, patch layout, etc.
+   * Called as the very last step before the pipeline exits.
+   */
+  finalizeProject?(cwd: string): void;
+
   /**
    * Collect created files for the pipeline result summary.
    * Returns paths relative to project root.

packages/core/src/catalog/index.ts

@@ -0,0 +1,37 @@
+export {
+  SectionSchema,
+  SECTION_TYPES,
+  HeaderSection,
+  HeroSection,
+  FeatureGridSection,
+  StatsBarSection,
+  DataTableSection,
+  TestimonialsSection,
+  PricingTableSection,
+  CTASection,
+  FAQSection,
+  ContentBlockSection,
+  LogoCloudSection,
+  FooterSection,
+  CustomHTMLSection,
+} from "./sections.js";
+export type {
+  Section,
+  SectionType,
+  HeaderSectionData,
+  HeroSectionData,
+  FeatureGridSectionData,
+  StatsBarSectionData,
+  DataTableSectionData,
+  TestimonialsSectionData,
+  PricingTableSectionData,
+  CTASectionData,
+  FAQSectionData,
+  ContentBlockSectionData,
+  LogoCloudSectionData,
+  FooterSectionData,
+  CustomHTMLSectionData,
+} from "./sections.js";
+
+export { PagePlanSchema } from "./page-plan.js";
+export type { PagePlan } from "./page-plan.js";

packages/core/src/catalog/page-plan.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { SectionSchema } from "./sections.js";
+
+// ── Page Plan Schema ────────────────────────────────────────────
+
+export const PagePlanSchema = z.object({
+  metadata: z.object({
+    title: z.string(),
+    description: z.string().optional(),
+  }),
+
+  sections: z.array(SectionSchema).min(1)
+    .describe("Ordered list of page sections, top to bottom"),
+
+  reusableComponents: z.array(z.object({
+    name: z.string(),
+    note: z.string().optional().describe("e.g. 'already exists — copy from design-system/components/'"),
+  })).optional(),
+
+  externalLinks: z.array(z.object({
+    text: z.string(),
+    url: z.string(),
+  })).optional(),
+
+  dependencies: z.array(z.string()).optional()
+    .describe("npm packages needed beyond the base project"),
+});
+
+export type PagePlan = z.infer<typeof PagePlanSchema>;