@fragments-sdk/cli 0.2.2

package/src/viewer/vite-plugin.ts

@@ -0,0 +1,2143 @@
+/**
+ * Segments Vite Plugin
+ *
+ * This plugin runs WITHIN the project's Vite context, giving it access to:
+ * - All project dependencies (React, UI libraries, etc.)
+ * - Project's loaders (SCSS, CSS modules, etc.)
+ * - Project's path aliases (@/components, etc.)
+ * - Project's tsconfig paths
+ *
+ * It provides:
+ * - Virtual module for segment imports
+ * - Viewer UI served at /fragments/
+ * - HMR support for segment file changes
+ */
+
+import type { Plugin, ViteDevServer, ResolvedConfig } from "vite";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFile } from "node:fs/promises";
+import { transform } from "esbuild";
+import type { SegmentsConfig, CompiledSegment } from "../core/index.js";
+import { generateContext, BRAND } from "../core/index.js";
+import {
+  findStorybookDir,
+  findPreviewConfigPath,
+  generatePreviewModule,
+} from "../core/node.js";
+import svgr from "vite-plugin-svgr";
+import {
+  generateRenderScript,
+  findSegmentByName,
+  getAvailableComponents,
+  type RenderRequest,
+} from "./render-utils.js";
+import {
+  compareStyles,
+  type StyleDiffItem,
+} from "./style-utils.js";
+
+/**
+ * Request body for /fragments/compare endpoint
+ */
+interface CompareRequest {
+  /** Component name */
+  component: string;
+  /** Variant name (optional, uses first variant if not specified) */
+  variant?: string;
+  /** Props to render with */
+  props?: Record<string, unknown>;
+  /** Figma URL (optional if segment has figma link) */
+  figmaUrl?: string;
+  /** Viewport dimensions */
+  viewport?: { width: number; height: number };
+  /** Figma access token (can be passed from CLI) */
+  figmaToken?: string;
+  /** Diff threshold percentage (default: 1.0) */
+  threshold?: number;
+  /** Include style comparison from Figma design properties */
+  includeStyleDiff?: boolean;
+}
+
+/**
+ * Response from /fragments/compare endpoint
+ */
+interface CompareResponse {
+  /** Whether diff is within threshold */
+  match: boolean;
+  /** Diff percentage (0-100) */
+  diffPercentage: number;
+  /** Threshold that was used */
+  threshold: number;
+  /** Rendered component screenshot (base64 PNG) */
+  rendered: string;
+  /** Figma design image (base64 PNG) */
+  figma: string;
+  /** Diff image highlighting differences (base64 PNG) */
+  diff: string;
+  /** The Figma URL that was used */
+  figmaUrl: string;
+  /** Regions that changed */
+  changedRegions: Array<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }>;
+  /** Style comparison results (when includeStyleDiff is true) */
+  styleDiff?: {
+    /** Whether all styles match */
+    match: boolean;
+    /** Individual property comparisons */
+    properties: StyleDiffItem[];
+    /** CSS properties from Figma design */
+    figmaStyles: Record<string, string>;
+    /** Computed CSS properties from rendered component */
+    renderedStyles: Record<string, string>;
+  };
+}
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Store pending render requests (for internal render page to pick up)
+const pendingRenders = new Map<
+  string,
+  { script: string; viewport?: { width: number; height: number } }
+>();
+
+// Shared browser pool for render captures (lazy initialized)
+let sharedRenderPool: any = null;
+let browserPoolModule: any = null;
+
+/**
+ * Get or create the shared browser pool for render captures.
+ * The pool is lazily initialized on first use and reused across requests.
+ */
+async function getSharedRenderPool() {
+  if (!browserPoolModule) {
+    browserPoolModule = await import("../service/index.js");
+  }
+
+  if (!sharedRenderPool) {
+    sharedRenderPool = new browserPoolModule.BrowserPool({
+      viewport: { width: 800, height: 600 }, // Default viewport, will be overridden per page
+      poolSize: 2, // Keep 2 contexts warm for parallel requests
+      idleTimeoutMs: 60000, // Keep warm for 60 seconds
+    });
+  }
+
+  return { pool: sharedRenderPool, bufferToBase64Url: browserPoolModule.bufferToBase64Url };
+}
+
+export interface SegmentsPluginOptions {
+  /** Discovered segment files */
+  segmentFiles: Array<{
+    absolutePath: string;
+    relativePath: string;
+  }>;
+
+  /** Segments configuration */
+  config: SegmentsConfig;
+
+  /** Project root directory */
+  projectRoot: string;
+}
+
+/**
+ * Create the Segments Vite plugin.
+ * Returns an array of plugins to support SVGR and other transforms.
+ */
+export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
+  const { segmentFiles, config, projectRoot } = options;
+
+  // Virtual module IDs
+  const VIRTUAL_SEGMENTS = `virtual:${BRAND.nameLower}`;
+  const VIRTUAL_SEGMENTS_RESOLVED = `\0virtual:${BRAND.nameLower}`;
+
+  const VIRTUAL_VIEWER_ENTRY = `virtual:${BRAND.nameLower}-viewer-entry`;
+  const VIRTUAL_VIEWER_ENTRY_RESOLVED = `\0virtual:${BRAND.nameLower}-viewer-entry`;
+
+  const VIRTUAL_PREVIEW = `virtual:${BRAND.nameLower}-preview`;
+  const VIRTUAL_PREVIEW_RESOLVED = `\0virtual:${BRAND.nameLower}-preview`;
+
+  let server: ViteDevServer | null = null;
+  let resolvedConfig: ResolvedConfig | null = null;
+
+  // Detect Storybook preview config path
+  const storybookDir = findStorybookDir(projectRoot);
+  const previewConfigPath = storybookDir
+    ? findPreviewConfigPath(storybookDir)
+    : null;
+
+  // Track segment files for HMR
+  const segmentFileSet = new Set(segmentFiles.map((f) => f.absolutePath));
+
+  const mainPlugin: Plugin = {
+    name: "segments",
+
+    // Add process.env shim and esbuild config for Storybook compatibility
+    config() {
+      return {
+        define: {
+          // Shim process.env for story files that use it (e.g., process.env.STORYBOOK_*)
+          "process.env": "{}",
+        },
+        esbuild: {
+          // Handle JSX in .js files (common in Storybook preview.js files)
+          loader: "tsx",
+          include: /\.(tsx?|jsx?)$/,
+        },
+        optimizeDeps: {
+          // Force esbuild to handle .js files with JSX
+          esbuildOptions: {
+            loader: {
+              ".js": "jsx",
+            },
+          },
+        },
+      };
+    },
+
+    // Store resolved config
+    configResolved(config) {
+      resolvedConfig = config;
+    },
+
+    // Store server reference for HMR
+    configureServer(_server) {
+      server = _server;
+
+      // Serve the viewer UI at /fragments/
+      _server.middlewares.use(async (req, res, next) => {
+        // Handle /fragments/render endpoint for AI preview
+        if (req.url === "/fragments/render" && req.method === "POST") {
+          try {
+            // Parse JSON body
+            const body = await parseJsonBody(req);
+            const { component, props = {}, viewport } = body as RenderRequest;
+
+            if (!component) {
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(
+                JSON.stringify({ error: "Missing required field: component" })
+              );
+              return;
+            }
+
+            // Load segments to find the component
+            const loadedSegments = await loadSegmentsForRender(
+              segmentFiles,
+              projectRoot
+            );
+            const segmentInfo = findSegmentByName(component, loadedSegments);
+
+            if (!segmentInfo) {
+              const available = getAvailableComponents(loadedSegments);
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(
+                JSON.stringify({
+                  error: `Component '${component}' not found. Available: ${available.join(
+                    ", "
+                  )}`,
+                })
+              );
+              return;
+            }
+
+            // Find the absolute path for the segment
+            const segmentFile = segmentFiles.find(
+              (f) => f.relativePath === segmentInfo.path
+            );
+            if (!segmentFile) {
+              res.writeHead(500, { "Content-Type": "application/json" });
+              res.end(
+                JSON.stringify({ error: "Could not resolve segment file path" })
+              );
+              return;
+            }
+
+            // Generate render script
+            const renderScript = generateRenderScript(
+              segmentFile.absolutePath,
+              segmentInfo.name,
+              props
+            );
+
+            // Store the render request for the render page to pick up
+            const requestId =
+              Date.now().toString(36) + Math.random().toString(36).slice(2);
+            pendingRenders.set(requestId, { script: renderScript, viewport });
+
+            // Get server address
+            const address = _server.httpServer?.address();
+            const port =
+              typeof address === "object" && address ? address.port : 6006;
+
+            // Use Playwright to render and capture
+            const screenshot = await captureRender(
+              `http://localhost:${port}/fragments/__render__/${requestId}`,
+              viewport || { width: 800, height: 600 }
+            );
+
+            // Clean up
+            pendingRenders.delete(requestId);
+
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ screenshot }));
+          } catch (error) {
+            console.error("[Fragments] Error rendering:", error);
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(
+              JSON.stringify({
+                error: error instanceof Error ? error.message : "Render failed",
+              })
+            );
+          }
+          return;
+        }
+
+        // Serve render page for AI preview (internal use)
+        if (req.url?.startsWith("/fragments/__render__/")) {
+          const requestId = req.url
+            .split("/fragments/__render__/")[1]
+            ?.split("?")[0];
+          const renderData = pendingRenders.get(requestId || "");
+
+          if (!renderData) {
+            res.writeHead(404, { "Content-Type": "text/plain" });
+            res.end("Render request not found or expired");
+            return;
+          }
+
+          await serveRenderHTML(res, _server, renderData.script);
+          return;
+        }
+
+        // Handle /fragments/compare endpoint for Figma design verification
+        if (req.url === "/fragments/compare" && req.method === "POST") {
+          try {
+            const body = (await parseJsonBody(req)) as CompareRequest;
+            const {
+              component,
+              variant,
+              props = {},
+              figmaUrl,
+              viewport,
+              threshold = 1.0,
+              includeStyleDiff = false,
+            } = body;
+
+            if (!component) {
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(
+                JSON.stringify({ error: "Missing required field: component" })
+              );
+              return;
+            }
+
+            // Check for Figma access token (request body > env var > config)
+            const figmaToken =
+              body.figmaToken ||
+              process.env.FIGMA_ACCESS_TOKEN ||
+              config.figmaToken;
+            if (!figmaToken && !figmaUrl) {
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(
+                JSON.stringify({
+                  error: `No Figma access token configured. Figma token: ${figmaToken}`,
+                  suggestion:
+                    "Set FIGMA_ACCESS_TOKEN env var, add figmaToken to fragments.config.ts, or provide in request",
+                })
+              );
+              return;
+            }
+
+            // Debug: Log segment files
+            console.log("[Fragments] Compare request for:", component);
+            console.log("[Fragments] segmentFiles count:", segmentFiles.length);
+            console.log("[Fragments] First 3 segment files:", segmentFiles.slice(0, 3).map(f => f.relativePath));
+            console.log("[Fragments] projectRoot:", projectRoot);
+
+            // Load segments to find the component and its figma URL
+            const loadedSegments = await loadSegmentsForRender(
+              segmentFiles,
+              projectRoot
+            );
+            console.log("[Fragments] loadedSegments count:", loadedSegments.length);
+            console.log("[Fragments] First 3 loaded:", loadedSegments.slice(0, 3).map(s => s.segment.meta.name));
+            const segmentInfo = findSegmentByName(component, loadedSegments);
+
+            if (!segmentInfo) {
+              const available = getAvailableComponents(loadedSegments);
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(
+                JSON.stringify({
+                  error: `Component '${component}' not found. Available: ${available.join(
+                    ", "
+                  )}`,
+                })
+              );
+              return;
+            }
+
+            // Find full segment data to get figma URL
+            const fullSegmentData = await loadFullSegmentForCompare(
+              _server,
+              segmentFiles,
+              component,
+              variant,
+              projectRoot
+            );
+
+            // Determine which Figma URL to use (request > variant > meta)
+            const effectiveFigmaUrl = figmaUrl || fullSegmentData?.figmaUrl;
+
+            if (!effectiveFigmaUrl) {
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(
+                JSON.stringify({
+                  error: `No Figma URL for component '${component}'`,
+                  suggestion:
+                    "Add 'figma' field to segment definition or provide figmaUrl in request",
+                })
+              );
+              return;
+            }
+
+            if (!figmaToken) {
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(
+                JSON.stringify({
+                  error: "Figma access token required for comparison",
+                  suggestion:
+                    "Set FIGMA_ACCESS_TOKEN env var or add figmaToken to fragments.config.ts",
+                })
+              );
+              return;
+            }
+
+            // Find segment file for rendering
+            const segmentFile = segmentFiles.find(
+              (f) => f.relativePath === segmentInfo.path
+            );
+            if (!segmentFile) {
+              res.writeHead(500, { "Content-Type": "application/json" });
+              res.end(
+                JSON.stringify({ error: "Could not resolve segment file path" })
+              );
+              return;
+            }
+
+            // Get server port
+            const address = _server.httpServer?.address();
+            const port =
+              typeof address === "object" && address ? address.port : 6006;
+            const renderViewport = viewport || { width: 800, height: 600 };
+
+            // Import Figma service
+            const { FigmaClient, bufferToBase64Url } = await import(
+              "../service/index.js"
+            );
+            const figmaClient = new FigmaClient({
+              accessToken: figmaToken,
+            });
+
+            // Parse Figma URL to get file key and node ID for style diff
+            const { fileKey, nodeId } = figmaClient.parseUrl(effectiveFigmaUrl);
+
+            // Generate render script and request ID for component capture
+            const renderScript = generateRenderScript(
+              segmentFile.absolutePath,
+              segmentInfo.name,
+              props
+            );
+            const requestId =
+              Date.now().toString(36) + Math.random().toString(36).slice(2);
+            pendingRenders.set(requestId, {
+              script: renderScript,
+              viewport: renderViewport,
+            });
+
+            try {
+              // Execute render, Figma fetch, and optionally style fetch in parallel
+              const [captureResult, figmaImageResult, figmaDesignProps] = await Promise.all([
+                // Render and capture the component (with optional computed styles)
+                captureRenderWithStyles(
+                  `http://localhost:${port}/fragments/__render__/${requestId}`,
+                  renderViewport,
+                  includeStyleDiff
+                ),
+                // Fetch Figma image
+                figmaClient.getImageFromUrl(effectiveFigmaUrl),
+                // Fetch Figma design properties (only if includeStyleDiff is true)
+                includeStyleDiff
+                  ? figmaClient.getNodeProperties(fileKey, nodeId)
+                  : Promise.resolve(null),
+              ]);
+
+              const renderedImage = captureResult.screenshot;
+              const renderedStyles = captureResult.computedStyles;
+              const figmaImage = bufferToBase64Url(figmaImageResult.data);
+
+              // Compare the images
+              const compareResult = await compareImages(
+                renderedImage,
+                figmaImage,
+                threshold
+              );
+
+              // Build response
+              const response: CompareResponse = {
+                match: compareResult.matches,
+                diffPercentage: compareResult.diffPercentage,
+                threshold,
+                rendered: renderedImage,
+                figma: figmaImage,
+                diff: compareResult.diffImage || renderedImage,
+                figmaUrl: effectiveFigmaUrl,
+                changedRegions: compareResult.changedRegions,
+              };
+
+              // Add style diff if requested
+              if (includeStyleDiff && figmaDesignProps && renderedStyles) {
+                const figmaStyles = figmaClient.convertToCSS(figmaDesignProps);
+                // Convert CSSDesignProperties to Record<string, string | undefined>
+                const figmaStylesRecord: Record<string, string | undefined> = { ...figmaStyles };
+                const styleDiffResult = compareStyles(figmaStylesRecord, renderedStyles);
+                response.styleDiff = styleDiffResult;
+
+                // Update overall match to include style match
+                if (!styleDiffResult.match) {
+                  response.match = false;
+                }
+              }
+
+              res.setHeader("Content-Type", "application/json");
+              res.end(JSON.stringify(response));
+            } finally {
+              pendingRenders.delete(requestId);
+            }
+          } catch (error) {
+            console.error("[Fragments] Error comparing:", error);
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(
+              JSON.stringify({
+                error:
+                  error instanceof Error ? error.message : "Compare failed",
+              })
+            );
+          }
+          return;
+        }
+
+        // Handle /fragments/figma-styles endpoint for lightweight style fetching
+        // This avoids the heavy Playwright rendering just to get styles
+        if (req.url === "/fragments/figma-styles" && req.method === "POST") {
+          try {
+            const body = (await parseJsonBody(req)) as {
+              figmaUrl: string;
+            };
+
+            const { figmaUrl } = body;
+
+            if (!figmaUrl) {
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({ error: "Missing figmaUrl" }));
+              return;
+            }
+
+            // Check for Figma access token
+            const figmaToken =
+              process.env.FIGMA_ACCESS_TOKEN || config.figmaToken;
+            if (!figmaToken) {
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(
+                JSON.stringify({
+                  error: "No Figma access token configured",
+                  suggestion:
+                    "Set FIGMA_ACCESS_TOKEN env var or add figmaToken to fragments.config.ts",
+                })
+              );
+              return;
+            }
+
+            // Import Figma service
+            const { FigmaClient } = await import("../service/index.js");
+            const figmaClient = new FigmaClient({ accessToken: figmaToken });
+
+            // Parse Figma URL
+            const { fileKey, nodeId } = figmaClient.parseUrl(figmaUrl);
+
+            // Fetch design properties
+            const figmaDesignProps = await figmaClient.getNodeProperties(
+              fileKey,
+              nodeId
+            );
+            const figmaStyles = figmaClient.convertToCSS(figmaDesignProps);
+
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ styles: figmaStyles }));
+          } catch (error) {
+            console.error("[Fragments] Error fetching Figma styles:", error);
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(
+              JSON.stringify({
+                error:
+                  error instanceof Error
+                    ? error.message
+                    : "Failed to fetch Figma styles",
+              })
+            );
+          }
+          return;
+        }
+
+        // Handle /fragments/tokens endpoint for token registry
+        if (req.url?.startsWith("/fragments/tokens")) {
+          try {
+            const url = new URL(req.url, "http://localhost");
+            const format = url.searchParams.get("format") || "json";
+            const category = url.searchParams.get("category");
+            const theme = url.searchParams.get("theme");
+
+            // Check if tokens are configured
+            if (!config.tokens || !config.tokens.include || config.tokens.include.length === 0) {
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({
+                error: "No token configuration found",
+                suggestion: "Add 'tokens' config to fragments.config.ts with 'include' patterns for CSS/SCSS files",
+                example: {
+                  tokens: {
+                    include: ["src/styles/theme.scss", "src/styles/variables.css"],
+                    themeSelectors: { ":root": "default", "[data-theme='dark']": "dark" },
+                  },
+                },
+              }));
+              return;
+            }
+
+            // Import token registry
+            const { getSharedTokenRegistry } = await import("../service/index.js");
+            const registry = getSharedTokenRegistry();
+
+            // Initialize if not already
+            if (!registry.isInitialized()) {
+              await registry.initialize(config.tokens, projectRoot);
+            }
+
+            let tokens = registry.getAllTokens();
+
+            // Filter by category if specified
+            if (category) {
+              tokens = tokens.filter(t => t.category === category);
+            }
+
+            // Filter by theme if specified
+            if (theme) {
+              tokens = tokens.filter(t => t.theme === theme || t.theme === "default");
+            }
+
+            const meta = registry.getMeta();
+
+            if (format === "summary") {
+              // Return summary only
+              const summary = {
+                totalTokens: meta?.totalTokens || 0,
+                byCategory: {} as Record<string, number>,
+                byTheme: {} as Record<string, number>,
+                parseTimeMs: meta?.parseTimeMs || 0,
+                sourceFiles: meta?.sourceFiles || [],
+              };
+
+              for (const token of registry.getAllTokens()) {
+                summary.byCategory[token.category] = (summary.byCategory[token.category] || 0) + 1;
+                summary.byTheme[token.theme] = (summary.byTheme[token.theme] || 0) + 1;
+              }
+
+              res.setHeader("Content-Type", "application/json");
+              res.end(JSON.stringify(summary, null, 2));
+            } else {
+              // Return full token list
+              res.setHeader("Content-Type", "application/json");
+              res.end(JSON.stringify({
+                tokens,
+                meta,
+              }, null, 2));
+            }
+          } catch (error) {
+            console.error("[Fragments] Error fetching tokens:", error);
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+              error: error instanceof Error ? error.message : "Failed to fetch tokens",
+            }));
+          }
+          return;
+        }
+
+        // Handle /fragments/token-match endpoint for reverse token lookup
+        if (req.url === "/fragments/token-match" && req.method === "POST") {
+          try {
+            const body = (await parseJsonBody(req)) as {
+              value: string;
+              propertyType?: "color" | "spacing" | "typography" | "other";
+              theme?: string;
+            };
+
+            const { value, propertyType, theme } = body;
+
+            if (!value) {
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({ error: "Missing required field: value" }));
+              return;
+            }
+
+            // Check if tokens are configured
+            if (!config.tokens || !config.tokens.include || config.tokens.include.length === 0) {
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({
+                error: "No token configuration found",
+                suggestion: "Add 'tokens' config to fragments.config.ts",
+              }));
+              return;
+            }
+
+            // Import token registry
+            const { getSharedTokenRegistry } = await import("../service/index.js");
+            const registry = getSharedTokenRegistry();
+
+            // Initialize if not already
+            if (!registry.isInitialized()) {
+              await registry.initialize(config.tokens, projectRoot);
+            }
+
+            // Match the value
+            const result = registry.matchValue({
+              value,
+              propertyType,
+              theme,
+            });
+
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify(result));
+          } catch (error) {
+            console.error("[Fragments] Error matching token:", error);
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+              error: error instanceof Error ? error.message : "Failed to match token",
+            }));
+          }
+          return;
+        }
+
+        // Handle /fragments/compliance endpoint for token compliance checking
+        if (req.url === "/fragments/compliance" && req.method === "POST") {
+          try {
+            const body = (await parseJsonBody(req)) as {
+              component: string;
+              variant?: string;
+              theme?: string;
+            };
+
+            const { component, variant, theme = "default" } = body;
+
+            if (!component) {
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({ error: "Missing required field: component" }));
+              return;
+            }
+
+            // Check if tokens are configured
+            if (!config.tokens || !config.tokens.include || config.tokens.include.length === 0) {
+              // Return 100% compliance if no tokens configured (can't check)
+              res.setHeader("Content-Type", "application/json");
+              res.end(JSON.stringify({
+                component,
+                variant,
+                compliance: 100,
+                totalProperties: 0,
+                hardcoded: 0,
+                usingTokens: 0,
+                violations: [],
+                note: "No token configuration found - token compliance checking disabled",
+              }));
+              return;
+            }
+
+            // Load segment data
+            const loadedSegments = await loadSegmentsForRender(segmentFiles, projectRoot);
+            const segmentInfo = findSegmentByName(component, loadedSegments);
+
+            if (!segmentInfo) {
+              const available = getAvailableComponents(loadedSegments);
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({
+                error: `Component '${component}' not found. Available: ${available.join(", ")}`,
+              }));
+              return;
+            }
+
+            // Find segment file for rendering
+            const segmentFile = segmentFiles.find(
+              (f) => f.relativePath === segmentInfo.path
+            );
+            if (!segmentFile) {
+              res.writeHead(500, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({ error: "Could not resolve segment file path" }));
+              return;
+            }
+
+            // Import token registry
+            const { getSharedTokenRegistry } = await import("../service/index.js");
+            const registry = getSharedTokenRegistry();
+
+            // Initialize if not already
+            if (!registry.isInitialized()) {
+              await registry.initialize(config.tokens, projectRoot);
+            }
+
+            // Get server port
+            const address = _server.httpServer?.address();
+            const port = typeof address === "object" && address ? address.port : 6006;
+            const renderViewport = { width: 800, height: 600 };
+
+            // Generate render script and capture with styles
+            const renderScript = generateRenderScript(
+              segmentFile.absolutePath,
+              segmentInfo.name,
+              {}
+            );
+            const requestId = Date.now().toString(36) + Math.random().toString(36).slice(2);
+            pendingRenders.set(requestId, { script: renderScript, viewport: renderViewport });
+
+            try {
+              // Render the component and extract computed styles
+              const captureResult = await captureRenderWithStyles(
+                `http://localhost:${port}/fragments/__render__/${requestId}`,
+                renderViewport,
+                true // extractStyles = true
+              );
+
+              const computedStyles = captureResult.computedStyles || {};
+
+              // Convert computed styles to style diff format for calculateUsageSummary
+              const styleDiffs: Array<{
+                property: string;
+                figma: string;
+                rendered: string;
+                match: boolean;
+              }> = [];
+
+              // Check each computed style property
+              for (const [property, value] of Object.entries(computedStyles)) {
+                if (!value) continue;
+
+                // Try to find a matching token
+                const matchResult = registry.matchValue({
+                  value,
+                  propertyType: property.toLowerCase().includes("color") ? "color" :
+                               property.toLowerCase().includes("font") ? "typography" :
+                               property.toLowerCase().includes("spacing") || property.toLowerCase().includes("padding") || property.toLowerCase().includes("margin") ? "spacing" : undefined,
+                  theme,
+                });
+
+                // If we found an exact match, the value is using a token
+                const isUsingToken = matchResult.exactMatches.length > 0;
+
+                styleDiffs.push({
+                  property,
+                  figma: value, // Use the value as both figma and rendered for self-comparison
+                  rendered: value,
+                  match: isUsingToken,
+                });
+              }
+
+              // Calculate compliance using token registry
+              const usageSummary = registry.calculateUsageSummary(styleDiffs, theme);
+
+              // Build violations list from hardcoded properties
+              interface ViolationItem {
+                property: string;
+                issue: string;
+                severity: "error" | "warning";
+                suggestion?: string;
+                expected?: string;
+                actual?: string;
+              }
+
+              const violations: ViolationItem[] = usageSummary.hardcodedProperties.map(hp => {
+                const suggestion = hp.suggestedFix
+                  ? `Use ${hp.suggestedFix.tokenName} (${hp.suggestedFix.tokenValue})`
+                  : undefined;
+
+                return {
+                  property: hp.property,
+                  issue: `Hardcoded value "${hp.rendered}" should use a design token`,
+                  severity: "warning" as const,
+                  suggestion,
+                  expected: hp.figmaToken,
+                  actual: hp.rendered,
+                };
+              });
+
+              res.setHeader("Content-Type", "application/json");
+              res.end(JSON.stringify({
+                component,
+                variant,
+                compliance: usageSummary.compliancePercent,
+                totalProperties: usageSummary.totalProperties,
+                hardcoded: usageSummary.hardcoded,
+                usingTokens: usageSummary.usingTokens,
+                violations,
+              }));
+            } finally {
+              pendingRenders.delete(requestId);
+            }
+          } catch (error) {
+            console.error("[Fragments] Error checking compliance:", error);
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+              error: error instanceof Error ? error.message : "Compliance check failed",
+            }));
+          }
+          return;
+        }
+
+        // Handle /fragments/context endpoint for AI context generation
+        if (req.url?.startsWith("/fragments/context")) {
+          try {
+            const url = new URL(req.url, "http://localhost");
+            const format = (url.searchParams.get("format") || "markdown") as
+              | "markdown"
+              | "json";
+            const compact = url.searchParams.get("compact") === "true";
+
+            // Load all segments from BRAND.outFile
+            const compiledSegments = await loadSegmentsForContext(
+              _server,
+              segmentFiles,
+              config,
+              projectRoot
+            );
+
+            const { content, tokenEstimate } = generateContext(
+              compiledSegments,
+              {
+                format,
+                compact,
+                include: {
+                  code: url.searchParams.get("code") === "true",
+                  relations: url.searchParams.get("relations") === "true",
+                },
+              }
+            );
+
+            res.setHeader("X-Token-Estimate", String(tokenEstimate));
+            res.setHeader(
+              "Content-Type",
+              format === "json"
+                ? "application/json"
+                : "text/markdown; charset=utf-8"
+            );
+            res.end(content);
+          } catch (error) {
+            console.error("[Fragments] Error generating context:", error);
+            res.writeHead(500, { "Content-Type": "text/plain" });
+            res.end(
+              "Error generating context: " +
+                (error instanceof Error ? error.message : error)
+            );
+          }
+          return;
+        }
+
+        // Handle /fragments/save endpoint for saving fragment metadata
+        if (req.url === "/fragments/save" && req.method === "POST") {
+          try {
+            const body = await parseJsonBody(req);
+            const { componentName, fragment } = body as {
+              componentName: string;
+              fragment: Record<string, unknown>;
+            };
+
+            if (!componentName || !fragment) {
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(
+                JSON.stringify({
+                  error: "Missing required fields: componentName, fragment",
+                })
+              );
+              return;
+            }
+
+            // Import writeFile for saving
+            const { writeFile, mkdir } = await import("node:fs/promises");
+            const { join } = await import("node:path");
+            const { BRAND } = await import("../core/index.js");
+
+            // Ensure .fragments/components directory exists
+            const fragmentsDir = join(projectRoot, BRAND.dataDir, BRAND.componentsDir);
+            await mkdir(fragmentsDir, { recursive: true });
+
+            // Write fragment file
+            const fragmentPath = join(
+              fragmentsDir,
+              `${componentName}${BRAND.fileExtension}`
+            );
+            await writeFile(
+              fragmentPath,
+              JSON.stringify(fragment, null, 2),
+              "utf-8"
+            );
+
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ success: true, path: fragmentPath }));
+          } catch (error) {
+            console.error("[Fragments] Error saving fragment:", error);
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(
+              JSON.stringify({
+                error: error instanceof Error ? error.message : "Save failed",
+              })
+            );
+          }
+          return;
+        }
+
+        // Handle /fragments/fix endpoint for generating token fix patches
+        if (req.url === "/fragments/fix" && req.method === "POST") {
+          try {
+            const body = (await parseJsonBody(req)) as {
+              component: string;
+              variant?: string;
+              fixType?: "token" | "all";
+            };
+
+            const { component, variant, fixType = "all" } = body;
+
+            if (!component) {
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({ error: "Missing required field: component" }));
+              return;
+            }
+
+            // Check if tokens are configured
+            if (!config.tokens || !config.tokens.include || config.tokens.include.length === 0) {
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({
+                error: "No token configuration found",
+                suggestion: "Add 'tokens' config to fragments.config.ts to enable fix generation",
+              }));
+              return;
+            }
+
+            // Load segment data
+            const loadedSegments = await loadSegmentsForRender(segmentFiles, projectRoot);
+            const segmentInfo = findSegmentByName(component, loadedSegments);
+
+            if (!segmentInfo) {
+              const available = getAvailableComponents(loadedSegments);
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({
+                error: `Component '${component}' not found. Available: ${available.join(", ")}`,
+              }));
+              return;
+            }
+
+            // Import services
+            const {
+              getSharedTokenRegistry,
+              generateTokenPatches,
+            } = await import("../service/index.js");
+            const registry = getSharedTokenRegistry();
+
+            // Initialize token registry if not already
+            if (!registry.isInitialized()) {
+              await registry.initialize(config.tokens, projectRoot);
+            }
+
+            // For now, we generate patches based on style diff data
+            // In a full implementation, we would:
+            // 1. Render the component and get computed styles
+            // 2. Compare with Figma styles to find hardcoded values
+            // 3. Generate patches for each hardcoded value
+
+            // Get source file path from segment
+            const segmentFile = segmentFiles.find(
+              (f) => f.relativePath === segmentInfo.path
+            );
+            const sourceFile = segmentFile?.relativePath || `${component}.tsx`;
+
+            // For demonstration, we'll create a placeholder response
+            // In production, this would use style comparison + AST patching
+            const result = generateTokenPatches(
+              component,
+              [], // Would be populated by actual style diffs
+              registry,
+              { sourceFile }
+            );
+
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({
+              patches: result.patches,
+              summary: result.summary,
+              fixableCount: result.fixableCount,
+              unfixableCount: result.unfixableCount,
+            }));
+          } catch (error) {
+            console.error("[Fragments] Error generating fixes:", error);
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+              error: error instanceof Error ? error.message : "Fix generation failed",
+            }));
+          }
+          return;
+        }
+
+        // Handle /fragments/preview/ - isolated iframe for component previews
+        if (req.url?.startsWith("/fragments/preview")) {
+          // Redirect to trailing slash
+          if (req.url === "/fragments/preview") {
+            res.writeHead(302, { Location: "/fragments/preview/" });
+            res.end();
+            return;
+          }
+
+          // Serve the preview frame HTML
+          await servePreviewFrameHTML(res, _server);
+          return;
+        }
+
+        if (req.url === "/segments" || req.url === "/fragments/") {
+          // Redirect to /fragments/
+          if (!req.url.endsWith("/")) {
+            res.writeHead(302, { Location: "/fragments/" });
+            res.end();
+            return;
+          }
+
+          // Serve the viewer HTML
+          serveViewerHTML(res, _server);
+          return;
+        }
+
+        next();
+      });
+
+      // Log startup message
+      _server.httpServer?.once("listening", () => {
+        const address = _server.httpServer?.address();
+        const port =
+          typeof address === "object" && address ? address.port : 6006;
+        console.log(
+          `\n  📦 Fragments Viewer: http://localhost:${port}/fragments/\n`
+        );
+      });
+    },
+
+    // Resolve virtual modules
+    resolveId(id) {
+      if (id === VIRTUAL_SEGMENTS) {
+        return VIRTUAL_SEGMENTS_RESOLVED;
+      }
+      if (id === VIRTUAL_VIEWER_ENTRY) {
+        return VIRTUAL_VIEWER_ENTRY_RESOLVED;
+      }
+      if (id === VIRTUAL_PREVIEW) {
+        return VIRTUAL_PREVIEW_RESOLVED;
+      }
+      return null;
+    },
+
+    // Load virtual modules
+    load(id) {
+      if (id === VIRTUAL_SEGMENTS_RESOLVED) {
+        return generateSegmentsModule(segmentFiles, config, previewConfigPath);
+      }
+      if (id === VIRTUAL_VIEWER_ENTRY_RESOLVED) {
+        return generateViewerEntry();
+      }
+      if (id === VIRTUAL_PREVIEW_RESOLVED) {
+        return generatePreviewModule(previewConfigPath);
+      }
+      return null;
+    },
+
+    // Handle HMR for segment files
+    handleHotUpdate({ file, server }) {
+      if (segmentFileSet.has(file)) {
+        // Invalidate the virtual segments module
+        const mod = server.moduleGraph.getModuleById(VIRTUAL_SEGMENTS_RESOLVED);
+        if (mod) {
+          server.moduleGraph.invalidateModule(mod);
+        }
+
+        // Send HMR update
+        server.ws.send({
+          type: "custom",
+          event: "segments:update",
+          data: { file },
+        });
+
+        // Return empty array to prevent full reload
+        // The component HMR will handle the actual update
+        return [];
+      }
+    },
+  };
+
+  // Plugin to transform JSX in .js files (common in Storybook preview.js)
+  // Uses the `load` hook instead of `transform` because we need to intercept
+  // the file BEFORE Vite's import-analysis tries to parse it
+  const jsxTransformPlugin: Plugin = {
+    name: "segments-jsx-transform",
+    enforce: "pre",
+    async load(id) {
+      // Only handle .js files that might contain JSX (like preview.js)
+      if (!id.endsWith(".js")) return null;
+
+      // Only handle .storybook directory files (most common case for JSX in .js)
+      if (!id.includes(".storybook")) return null;
+
+      // Read the file content
+      const fs = await import("node:fs/promises");
+      let code: string;
+      try {
+        code = await fs.readFile(id, "utf-8");
+      } catch {
+        return null;
+      }
+
+      // Check if the file contains JSX syntax
+      const hasOpeningTag = code.includes("<");
+      const hasSelfClosingTag = code.includes("/>");
+      const hasClosingTag = code.includes("</");
+
+      // Skip if no JSX detected
+      if (!hasOpeningTag || (!hasSelfClosingTag && !hasClosingTag)) return null;
+
+      try {
+        const result = await transform(code, {
+          loader: "jsx",
+          jsx: "automatic",
+          sourcefile: id,
+          sourcemap: true,
+        });
+        return {
+          code: result.code,
+          map: result.map,
+        };
+      } catch (error) {
+        // Log error for debugging but don't block
+        console.warn(`[Fragments] JSX transform failed for ${id}:`, error instanceof Error ? error.message : error);
+        return null;
+      }
+    },
+  };
+
+  // Return array of plugins including SVGR for SVG imports
+  return [
+    // JSX transform for .js files (must run first)
+    jsxTransformPlugin,
+    // SVGR plugin to handle `import { ReactComponent } from "*.svg"` pattern
+    svgr({
+      svgrOptions: {
+        exportType: "named", // Export as { ReactComponent }
+      },
+      include: "**/*.svg",
+    }),
+    // Main segments plugin
+    mainPlugin,
+  ];
+}
+
+/**
+ * Check if a file path is a Storybook story file
+ */
+function isStoryFile(filePath: string): boolean {
+  return /\.stories\.(tsx?|jsx?)$/.test(filePath);
+}
+
+/**
+ * Get the base component path from a segment or story file path.
+ * e.g., "src/components/Button/Button.segment.tsx" -> "src/components/Button/Button"
+ * e.g., "src/components/Button/Button.stories.tsx" -> "src/components/Button/Button"
+ */
+function getBaseComponentPath(filePath: string): string {
+  return filePath.replace(/\.(segment|stories)\.(tsx?|jsx?)$/, "");
+}
+
+/**
+ * Generate the virtual segments module.
+ * Uses dynamic imports for lazy loading - segments are loaded on demand.
+ * Supports both native .segment.tsx files and Storybook .stories.tsx files.
+ * Integrates Storybook preview config for global decorators, parameters, etc.
+ *
+ * MERGE STRATEGY: When both .segment.tsx and .stories.tsx exist for the same component:
+ * - Use .stories.tsx for RENDERING (variants, props, etc.) - it's the source of truth
+ * - Merge METADATA from .segment.tsx (Figma URLs, AI descriptions, usage guidelines)
+ * - This gives us the best of both worlds: working renders + rich metadata
+ */
+function generateSegmentsModule(
+  segmentFiles: Array<{ absolutePath: string; relativePath: string }>,
+  config: SegmentsConfig,
+  previewConfigPath: string | null
+): string {
+  // Group files by base component path to identify pairs
+  const filesByBasePath = new Map<string, {
+    storyFile?: { absolutePath: string; relativePath: string };
+    segmentFile?: { absolutePath: string; relativePath: string };
+  }>();
+
+  for (const file of segmentFiles) {
+    const basePath = getBaseComponentPath(file.relativePath);
+    const isStory = isStoryFile(file.relativePath);
+
+    const existing = filesByBasePath.get(basePath) || {};
+
+    if (isStory) {
+      existing.storyFile = file;
+    } else {
+      existing.segmentFile = file;
+    }
+
+    filesByBasePath.set(basePath, existing);
+  }
+
+  // Generate loaders with metadata merge support
+  // Priority: stories for rendering, segment for metadata (Figma URLs, etc.)
+  const loaders = Array.from(filesByBasePath.values())
+    .map((files) => {
+      // Determine which file to use for rendering
+      const primaryFile = files.storyFile || files.segmentFile;
+      if (!primaryFile) return null;
+
+      const isStory = !!files.storyFile;
+
+      // If we have both, include the segment file path for metadata merge
+      const metadataPath = (files.storyFile && files.segmentFile)
+        ? files.segmentFile.absolutePath
+        : null;
+
+      return `  {
+    path: "${primaryFile.relativePath}",
+    isStory: ${isStory},
+    loader: () => import("${primaryFile.absolutePath}"),
+    metadataLoader: ${metadataPath ? `() => import("${metadataPath}")` : 'null'}
+  }`;
+    })
+    .filter(Boolean)
+    .join(",\n");
+
+  // Generate preview config import if available
+  const previewImport = previewConfigPath
+    ? `import * as previewConfig from "virtual:segments-preview";`
+    : "";
+  const previewSetup = previewConfigPath
+    ? `
+// Set global preview config before loading segments
+setPreviewConfig({
+  decorators: previewConfig.decorators,
+  parameters: previewConfig.parameters,
+  globalTypes: previewConfig.globalTypes,
+  args: previewConfig.args,
+  argTypes: previewConfig.argTypes,
+  loaders: previewConfig.loaders,
+});
+`
+    : "";
+
+  return `
+import { storyModuleToSegment, setPreviewConfig } from "@fragments/core";
+${previewImport}
+${previewSetup}
+// Lazy segment loaders (supports both .segment.tsx and .stories.tsx)
+const segmentLoaders = [
+${loaders}
+];
+
+// Cache for loaded segments
+const loadedSegments = new Map();
+
+/**
+ * Merge metadata from a segment file into a story-based segment.
+ * This preserves Figma URLs and other AI-agent focused data.
+ */
+function mergeMetadata(segment, metadataModule) {
+  if (!metadataModule?.default) return segment;
+
+  const metadata = metadataModule.default;
+
+  // Merge meta-level Figma URL
+  if (metadata.meta?.figma && !segment.meta.figma) {
+    segment.meta.figma = metadata.meta.figma;
+  }
+
+  // Merge description if not present
+  if (metadata.meta?.description && !segment.meta.description) {
+    segment.meta.description = metadata.meta.description;
+  }
+
+  // Merge variant-level Figma URLs
+  if (metadata.variants && segment.variants) {
+    for (const metaVariant of metadata.variants) {
+      const segmentVariant = segment.variants.find(v => v.name === metaVariant.name);
+      if (segmentVariant && metaVariant.figma && !segmentVariant.figma) {
+        segmentVariant.figma = metaVariant.figma;
+      }
+    }
+  }
+
+  return segment;
+}
+
+// Load all segments (for initial render)
+// Gracefully handles individual failures - one bad story won't break all segments
+export async function loadAllSegments() {
+  const results = await Promise.all(
+    segmentLoaders.map(async (loader) => {
+      try {
+        if (loadedSegments.has(loader.path)) {
+          const cached = loadedSegments.get(loader.path);
+          return cached ? { path: loader.path, segment: cached } : null;
+        }
+
+        const module = await loader.loader();
+
+        // Convert story modules to segments at runtime
+        let segment;
+        if (loader.isStory) {
+          segment = storyModuleToSegment(module, loader.path);
+          // storyModuleToSegment returns null for stories without a component
+          if (!segment) {
+            loadedSegments.set(loader.path, null);
+            return null;
+          }
+        } else {
+          segment = module.default;
+        }
+
+        // Merge metadata from corresponding segment file if available
+        if (loader.metadataLoader) {
+          try {
+            const metadataModule = await loader.metadataLoader();
+            segment = mergeMetadata(segment, metadataModule);
+          } catch (metaError) {
+            // Metadata loading is optional - don't fail if it errors
+            console.warn("[Fragments] Could not load metadata for " + loader.path + ":", metaError.message);
+          }
+        }
+
+        loadedSegments.set(loader.path, segment);
+        return { path: loader.path, segment };
+      } catch (error) {
+        console.warn("[Fragments] Failed to load " + loader.path + ":", error.message);
+        return null;
+      }
+    })
+  );
+  // Filter out failed loads
+  return results.filter(r => r !== null);
+}
+
+// Load a single segment by path
+export async function loadSegment(path) {
+  const loader = segmentLoaders.find(l => l.path === path);
+  if (!loader) return null;
+
+  if (loadedSegments.has(path)) {
+    return loadedSegments.get(path);
+  }
+
+  const module = await loader.loader();
+
+  // Convert story modules to segments at runtime
+  let segment;
+  if (loader.isStory) {
+    segment = storyModuleToSegment(module, path);
+  } else {
+    segment = module.default;
+  }
+
+  // Merge metadata from corresponding segment file if available
+  if (loader.metadataLoader && segment) {
+    try {
+      const metadataModule = await loader.metadataLoader();
+      segment = mergeMetadata(segment, metadataModule);
+    } catch (metaError) {
+      console.warn("[Fragments] Could not load metadata for " + path + ":", metaError.message);
+    }
+  }
+
+  loadedSegments.set(path, segment);
+  return segment;
+}
+
+// For backwards compatibility, load all segments synchronously on import
+// This is still lazy per-file but awaited at module load
+let segments = [];
+const segmentsPromise = loadAllSegments().then(s => { segments = s; return s; });
+
+export { segments, segmentsPromise };
+export const config = ${JSON.stringify(config)};
+
+// HMR support
+if (import.meta.hot) {
+  import.meta.hot.accept();
+
+  import.meta.hot.on("segments:update", (data) => {
+    console.log("[Fragments] File updated:", data.file);
+    // Clear cache for the updated file (handles both .segment and .stories)
+    for (const [path, _] of loadedSegments) {
+      const basePath = path.replace(/\\.(segment|stories)\\.tsx?$/, '');
+      if (data.file.includes(basePath)) {
+        loadedSegments.delete(path);
+      }
+    }
+    // Trigger re-render in viewer
+    window.dispatchEvent(new CustomEvent("segments:update"));
+  });
+}
+`;
+}
+
+/**
+ * Generate the viewer entry point.
+ */
+function generateViewerEntry(): string {
+  return `
+import { segments, config } from "virtual:segments";
+
+// Re-export for viewer
+export { segments, config };
+
+// Initialize viewer
+console.log("[Fragments] Loaded", segments.length, "segment(s)");
+`;
+}
+
+/**
+ * Load segments for context generation.
+ * Uses BRAND.outFile to avoid SSR module loading issues with React CJS modules.
+ */
+async function loadSegmentsForContext(
+  _server: ViteDevServer,
+  _segmentFiles: Array<{ absolutePath: string; relativePath: string }>,
+  _config: SegmentsConfig,
+  configDir?: string
+): Promise<CompiledSegment[]> {
+  const { join } = await import("node:path");
+
+  // Read from outFile (avoids SSR issues with React CJS)
+  const segmentsJsonPath = join(configDir || process.cwd(), BRAND.outFile);
+
+  try {
+    const content = await readFile(segmentsJsonPath, "utf-8");
+    const data = JSON.parse(content) as {
+      segments: Record<string, CompiledSegment>;
+    };
+
+    return Object.values(data.segments || {});
+  } catch (error) {
+    console.warn(
+      `[${BRAND.name}] Failed to load ${BRAND.outFile} for context:`,
+      error
+    );
+    console.warn(`[${BRAND.name}] Run '${BRAND.cliCommand} build' to generate ${BRAND.outFile}`);
+    return [];
+  }
+}
+
+/**
+ * Serve the viewer HTML page.
+ */
+async function serveViewerHTML(res: any, server: ViteDevServer): Promise<void> {
+  const viewerRoot = resolve(__dirname, "..");
+  const entryPath = resolve(viewerRoot, "src/entry.tsx");
+
+  try {
+    // Read the viewer HTML template
+    let html = await readFile(resolve(viewerRoot, "index.html"), "utf-8");
+
+    // Rewrite the entry.tsx path to use absolute path to viewer package
+    html = html.replace("/src/entry.tsx", entryPath);
+
+    // Transform HTML through Vite's pipeline
+    html = await server.transformIndexHtml("/fragments/", html);
+
+    res.writeHead(200, { "Content-Type": "text/html" });
+    res.end(html);
+  } catch (error) {
+    console.error("[Fragments] Error serving viewer:", error);
+    res.writeHead(500, { "Content-Type": "text/plain" });
+    res.end("Error loading Segments viewer");
+  }
+}
+
+/**
+ * Serve the isolated preview frame HTML page.
+ * This is used for iframe-based component preview with CSS isolation.
+ */
+async function servePreviewFrameHTML(res: any, server: ViteDevServer): Promise<void> {
+  const viewerRoot = resolve(__dirname, "..");
+  const entryPath = resolve(viewerRoot, "src/preview-frame-entry.tsx");
+
+  try {
+    // Read the preview frame HTML template
+    let html = await readFile(resolve(viewerRoot, "src/preview-frame.html"), "utf-8");
+
+    // Rewrite the entry path to use absolute path to viewer package
+    html = html.replace("/src/preview-frame-entry.tsx", entryPath);
+
+    // Transform HTML through Vite's pipeline
+    html = await server.transformIndexHtml("/fragments/preview/", html);
+
+    res.writeHead(200, { "Content-Type": "text/html" });
+    res.end(html);
+  } catch (error) {
+    console.error("[Fragments] Error serving preview frame:", error);
+    res.writeHead(500, { "Content-Type": "text/plain" });
+    res.end("Error loading preview frame");
+  }
+}
+
+/**
+ * Parse JSON body from an HTTP request.
+ */
+async function parseJsonBody(req: any): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    req.on("data", (chunk: Buffer) => {
+      body += chunk.toString();
+    });
+    req.on("end", () => {
+      try {
+        resolve(JSON.parse(body));
+      } catch (error) {
+        reject(new Error("Invalid JSON body"));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+/**
+ * Load segments for render from BRAND.outFile or by building on-the-fly.
+ * This avoids SSR issues with React components.
+ */
+async function loadSegmentsForRender(
+  segmentFiles: Array<{ absolutePath: string; relativePath: string }>,
+  configDir: string
+): Promise<Array<{ path: string; segment: { meta: { name: string } } }>> {
+  const { join } = await import("node:path");
+
+  // Try to read from the project directory
+  const segmentsJsonPath = join(configDir, BRAND.outFile);
+
+  try {
+    const content = await readFile(segmentsJsonPath, "utf-8");
+    const data = JSON.parse(content) as {
+      segments: Record<string, { filePath: string; meta: { name: string } }>;
+    };
+
+    // Convert to the expected format if we have entries
+    const segmentEntries = Object.values(data.segments || {});
+    if (segmentEntries.length > 0) {
+      return segmentEntries.map((segment) => ({
+        path: segment.filePath,
+        segment: { meta: { name: segment.meta.name } },
+      }));
+    }
+    // Fall through to file-based extraction if outFile is empty
+  } catch {
+    // outFile doesn't exist or is invalid - fall through to file-based extraction
+  }
+
+  // Extract component names from file paths (fallback)
+  return segmentFiles.map((f) => {
+    let name: string;
+    if (isStoryFile(f.relativePath)) {
+      // Extract name from path like "src/components/Button/Button.stories.tsx"
+      const match = f.relativePath.match(/\/([^/]+)\.stories\./);
+      name = match ? match[1] : f.relativePath;
+    } else {
+      // Extract name from path like "src/components/Button/Button.segment.tsx"
+      const match = f.relativePath.match(/\/([^/]+)\.segment\./);
+      name = match ? match[1] : f.relativePath;
+    }
+    return {
+      path: f.relativePath,
+      segment: { meta: { name } },
+    };
+  });
+}
+
+/**
+ * Serve the render HTML page for AI preview.
+ */
+async function serveRenderHTML(
+  res: any,
+  server: ViteDevServer,
+  renderScript: string
+): Promise<void> {
+  const viewerRoot = resolve(__dirname, "..");
+
+  try {
+    // Read the render template
+    let html = await readFile(
+      resolve(viewerRoot, "src/render-template.html"),
+      "utf-8"
+    );
+
+    // Inject the render script
+    html = html.replace(
+      "<!-- RENDER_SCRIPT_PLACEHOLDER -->",
+      `<script type="module">${renderScript}</script>`
+    );
+
+    // Transform HTML through Vite's pipeline to process imports
+    // Use a unique URL to prevent Vite from caching the transformed HTML
+    const uniqueUrl = `/fragments/__render__/${Date.now()}`;
+    html = await server.transformIndexHtml(uniqueUrl, html);
+
+    res.writeHead(200, { "Content-Type": "text/html" });
+    res.end(html);
+  } catch (error) {
+    console.error("[Fragments] Error serving render page:", error);
+    res.writeHead(500, { "Content-Type": "text/plain" });
+    res.end("Error loading render page");
+  }
+}
+
+/**
+ * Capture a render using the shared browser pool from @fragments/service.
+ * Uses a shared pool for efficiency - browser stays warm across requests.
+ */
+async function captureRender(
+  url: string,
+  viewport: { width: number; height: number }
+): Promise<string> {
+  const { pool, bufferToBase64Url } = await getSharedRenderPool();
+
+  const ctx = await pool.acquire();
+  const page = await ctx.newPage();
+
+  try {
+    // Set viewport for this specific render
+    await page.setViewportSize(viewport);
+
+    // Navigate to the render page
+    await page.goto(url, { waitUntil: "networkidle" });
+
+    // Wait for render to complete (indicated by ready class or timeout)
+    await page.waitForFunction(
+      () => (window as any).__RENDER_READY__ === true,
+      { timeout: 10000 }
+    );
+
+    // Check for render error
+    const error = await page.evaluate(() => (window as any).__RENDER_ERROR__);
+    if (error) {
+      throw new Error(`Render error: ${error}`);
+    }
+
+    // Screenshot the render root element
+    const element = await page.$("#render-root");
+    if (!element) {
+      throw new Error("Render root element not found");
+    }
+
+    const screenshot = await element.screenshot({ type: "png" });
+
+    return bufferToBase64Url(screenshot);
+  } finally {
+    await page.close();
+    pool.release(ctx);
+  }
+}
+
+/**
+ * Capture a render with optional computed styles extraction.
+ * Uses the shared browser pool for efficiency.
+ */
+async function captureRenderWithStyles(
+  url: string,
+  viewport: { width: number; height: number },
+  extractStyles: boolean
+): Promise<{ screenshot: string; computedStyles: Record<string, string> | null }> {
+  const { pool, bufferToBase64Url } = await getSharedRenderPool();
+
+  const ctx = await pool.acquire();
+  const page = await ctx.newPage();
+
+  try {
+    // Set viewport for this specific render
+    await page.setViewportSize(viewport);
+
+    await page.goto(url, { waitUntil: "networkidle" });
+
+      await page.waitForFunction(
+        () => (window as any).__RENDER_READY__ === true,
+        { timeout: 10000 }
+      );
+
+      const error = await page.evaluate(() => (window as any).__RENDER_ERROR__);
+      if (error) {
+        throw new Error(`Render error: ${error}`);
+      }
+
+      const element = await page.$("#render-root");
+      if (!element) {
+        throw new Error("Render root element not found");
+      }
+
+      // Extract computed styles if requested
+      let computedStyles: Record<string, string> | null = null;
+      if (extractStyles) {
+        computedStyles = await page.evaluate(() => {
+          const root = document.getElementById("render-root");
+          if (!root) return null;
+
+          // Helper function to check if a color is visible (not transparent)
+          const isVisibleColor = (color: string | undefined): boolean => {
+            if (!color) return false;
+            if (color === "transparent") return false;
+            if (color === "rgba(0, 0, 0, 0)") return false;
+            if (color.includes("rgba") && color.includes(", 0)")) return false;
+            return true;
+          };
+
+          // Helper to extract styles from an element
+          const extractStylesFromElement = (el: HTMLElement): Record<string, string> => {
+            const styles = window.getComputedStyle(el);
+            const relevantProps = [
+              "backgroundColor",
+              "borderColor",
+              "borderWidth",
+              "borderRadius",
+              "fontFamily",
+              "fontSize",
+              "fontWeight",
+              "lineHeight",
+              "letterSpacing",
+              "textAlign",
+              "boxShadow",
+              "padding",
+              "paddingTop",
+              "paddingRight",
+              "paddingBottom",
+              "paddingLeft",
+              "gap",
+              "opacity",
+              "width",
+              "height",
+            ];
+
+            const result: Record<string, string> = {};
+            for (const prop of relevantProps) {
+              const value = styles.getPropertyValue(
+                prop.replace(/([A-Z])/g, "-$1").toLowerCase()
+              );
+              if (value) {
+                result[prop] = value;
+              }
+            }
+            return result;
+          };
+
+          // Strategy: Find the element with the most visible styles
+          // Start by looking at all elements and score them based on visual presence
+          const candidates = root.querySelectorAll("*");
+          let bestElement: HTMLElement | null = null;
+          let bestScore = -1;
+
+          for (const el of candidates) {
+            const htmlEl = el as HTMLElement;
+            const styles = window.getComputedStyle(htmlEl);
+            let score = 0;
+
+            // Score based on visual properties
+            const bg = styles.backgroundColor;
+            if (isVisibleColor(bg)) {
+              score += 10; // Visible background is a strong signal
+            }
+
+            const border = styles.borderWidth;
+            if (border && border !== "0px") {
+              score += 3;
+            }
+
+            const boxShadow = styles.boxShadow;
+            if (boxShadow && boxShadow !== "none") {
+              score += 3;
+            }
+
+            // Bonus for being an interactive element
+            const tagName = htmlEl.tagName.toLowerCase();
+            if (["button", "a", "input", "select", "textarea"].includes(tagName)) {
+              score += 5;
+            }
+
+            // Bonus for having role="button"
+            if (htmlEl.getAttribute("role") === "button") {
+              score += 5;
+            }
+
+            // Penalty for being too small (likely not the main component)
+            const rect = htmlEl.getBoundingClientRect();
+            if (rect.width < 10 || rect.height < 10) {
+              score -= 10;
+            }
+
+            // Penalty for very large elements (likely containers)
+            if (rect.width > 500 || rect.height > 500) {
+              score -= 3;
+            }
+
+            if (score > bestScore) {
+              bestScore = score;
+              bestElement = htmlEl;
+            }
+          }
+
+          // If we still have no good element, fall back to first child
+          if (!bestElement) {
+            bestElement = root.firstElementChild as HTMLElement | null;
+          }
+
+          if (!bestElement) return null;
+
+          const result = extractStylesFromElement(bestElement);
+
+          // Normalize padding into shorthand if individual values exist
+          if (result.paddingTop && result.paddingRight && result.paddingBottom && result.paddingLeft) {
+            const t = result.paddingTop;
+            const r = result.paddingRight;
+            const b = result.paddingBottom;
+            const l = result.paddingLeft;
+            if (t === r && r === b && b === l) {
+              result.padding = t;
+            } else if (t === b && r === l) {
+              result.padding = `${t} ${r}`;
+            } else {
+              result.padding = `${t} ${r} ${b} ${l}`;
+            }
+          }
+
+          return result;
+        });
+      }
+
+      const screenshot = await element.screenshot({ type: "png" });
+
+      return {
+        screenshot: bufferToBase64Url(screenshot),
+        computedStyles,
+      };
+  } finally {
+    await page.close();
+    pool.release(ctx);
+  }
+}
+
+/**
+ * Load full segment data to get figma URL from segment or variant.
+ * Uses BRAND.outFile to avoid SSR module loading issues with React CJS modules.
+ */
+async function loadFullSegmentForCompare(
+  _server: ViteDevServer,
+  _segmentFiles: Array<{ absolutePath: string; relativePath: string }>,
+  componentName: string,
+  variantName?: string,
+  configDir?: string
+): Promise<{ figmaUrl?: string } | null> {
+  const { join } = await import("node:path");
+
+  // Try to read from outFile (avoids SSR issues with React CJS)
+  const segmentsJsonPath = join(configDir || process.cwd(), BRAND.outFile);
+
+  try {
+    const content = await readFile(segmentsJsonPath, "utf-8");
+    const data = JSON.parse(content) as {
+      segments: Record<
+        string,
+        {
+          meta: { name: string; figma?: string };
+          variants?: Array<{ name: string; figma?: string }>;
+        }
+      >;
+    };
+
+    const segment = data.segments[componentName];
+    if (!segment) {
+      return null;
+    }
+
+    // Priority: variant.figma > meta.figma
+    if (variantName && segment.variants) {
+      const variant = segment.variants.find((v) => v.name === variantName);
+      if (variant?.figma) {
+        return { figmaUrl: variant.figma };
+      }
+    }
+
+    // Fall back to meta.figma
+    if (segment.meta.figma) {
+      return { figmaUrl: segment.meta.figma };
+    }
+
+    return null;
+  } catch {
+    // outFile not found or invalid
+    console.warn(
+      `[${BRAND.name}] ${BRAND.outFile} not found, run '${BRAND.cliCommand} build' first`
+    );
+    return null;
+  }
+}
+
+/**
+ * Compare two base64 images and return diff result.
+ */
+async function compareImages(
+  image1Base64: string,
+  image2Base64: string,
+  threshold: number
+): Promise<{
+  matches: boolean;
+  diffPercentage: number;
+  diffImage?: string;
+  changedRegions: Array<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }>;
+}> {
+  const { DiffEngine, base64UrlToBuffer, bufferToBase64Url } = await import(
+    "../service/index.js"
+  );
+  const { PNG } = await import("pngjs");
+
+  // Convert base64 to buffers
+  const buffer1 = base64UrlToBuffer(image1Base64);
+  const buffer2 = base64UrlToBuffer(image2Base64);
+
+  // Parse PNGs to get dimensions
+  const png1 = PNG.sync.read(buffer1);
+  const png2 = PNG.sync.read(buffer2);
+
+  // If dimensions don't match, resize the smaller one to match the larger
+  let finalBuffer1 = buffer1;
+  let finalBuffer2 = buffer2;
+
+  if (png1.width !== png2.width || png1.height !== png2.height) {
+    // Resize to the larger dimensions by padding the smaller image
+    const targetWidth = Math.max(png1.width, png2.width);
+    const targetHeight = Math.max(png1.height, png2.height);
+
+    if (png1.width !== targetWidth || png1.height !== targetHeight) {
+      finalBuffer1 = await resizePng(
+        buffer1,
+        png1.width,
+        png1.height,
+        targetWidth,
+        targetHeight
+      );
+    }
+    if (png2.width !== targetWidth || png2.height !== targetHeight) {
+      finalBuffer2 = await resizePng(
+        buffer2,
+        png2.width,
+        png2.height,
+        targetWidth,
+        targetHeight
+      );
+    }
+  }
+
+  // Create Screenshot-like objects for DiffEngine
+  const screenshot1 = {
+    data: finalBuffer1,
+    hash: "",
+    viewport: { width: png1.width, height: png1.height },
+    capturedAt: new Date(),
+    metadata: {
+      component: "",
+      variant: "",
+      theme: "light" as const,
+      renderTimeMs: 0,
+      captureTimeMs: 0,
+    },
+  };
+
+  const screenshot2 = {
+    data: finalBuffer2,
+    hash: "",
+    viewport: { width: png2.width, height: png2.height },
+    capturedAt: new Date(),
+    metadata: {
+      component: "",
+      variant: "",
+      theme: "light" as const,
+      renderTimeMs: 0,
+      captureTimeMs: 0,
+    },
+  };
+
+  const diffEngine = new DiffEngine(threshold);
+  const result = diffEngine.compare(screenshot1, screenshot2, { threshold });
+
+  return {
+    matches: result.matches,
+    diffPercentage: result.diffPercentage,
+    diffImage: result.diffImage
+      ? bufferToBase64Url(result.diffImage)
+      : undefined,
+    changedRegions: result.changedRegions,
+  };
+}
+
+/**
+ * Resize a PNG by padding with transparent pixels to match target dimensions.
+ */
+async function resizePng(
+  buffer: Buffer,
+  srcWidth: number,
+  srcHeight: number,
+  targetWidth: number,
+  targetHeight: number
+): Promise<Buffer> {
+  const { PNG } = await import("pngjs");
+
+  const srcPng = PNG.sync.read(buffer);
+  const dstPng = new PNG({
+    width: targetWidth,
+    height: targetHeight,
+    fill: true,
+  });
+
+  // Fill with transparent white
+  for (let y = 0; y < targetHeight; y++) {
+    for (let x = 0; x < targetWidth; x++) {
+      const idx = (y * targetWidth + x) * 4;
+      dstPng.data[idx] = 255; // R
+      dstPng.data[idx + 1] = 255; // G
+      dstPng.data[idx + 2] = 255; // B
+      dstPng.data[idx + 3] = 255; // A (opaque white background)
+    }
+  }
+
+  // Copy source image data
+  for (let y = 0; y < srcHeight; y++) {
+    for (let x = 0; x < srcWidth; x++) {
+      const srcIdx = (y * srcWidth + x) * 4;
+      const dstIdx = (y * targetWidth + x) * 4;
+      dstPng.data[dstIdx] = srcPng.data[srcIdx];
+      dstPng.data[dstIdx + 1] = srcPng.data[srcIdx + 1];
+      dstPng.data[dstIdx + 2] = srcPng.data[srcIdx + 2];
+      dstPng.data[dstIdx + 3] = srcPng.data[srcIdx + 3];
+    }
+  }
+
+  return PNG.sync.write(dstPng);
+}