@antigenic-oss/paint 0.1.0

package/src/lib/claude-stream.ts

@@ -0,0 +1,158 @@
+/**
+ * Browser-side SSE consumer for streaming Claude CLI activity.
+ * Uses fetch + ReadableStream (not EventSource, which only supports GET).
+ */
+
+// ANSI escape codes
+const ANSI = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  gray: '\x1b[90m',
+} as const
+
+/**
+ * Classify a stderr line and wrap it in ANSI colors for xterm.js display.
+ */
+export function formatStderrLine(line: string): string {
+  const trimmed = line.trim()
+  if (!trimmed) return ''
+
+  // File reads
+  if (
+    /^(Reading|Read)\s/i.test(trimmed) ||
+    /\.tsx?|\.jsx?|\.css|\.html/i.test(trimmed)
+  ) {
+    return `${ANSI.magenta}  ${trimmed}${ANSI.reset}`
+  }
+  // Tool usage
+  if (/^Tool:\s/i.test(trimmed) || /^Using\s/i.test(trimmed)) {
+    return `${ANSI.cyan}  ${trimmed}${ANSI.reset}`
+  }
+  // Success
+  if (/success|complete|done|finished/i.test(trimmed)) {
+    return `${ANSI.green}  ${trimmed}${ANSI.reset}`
+  }
+  // Errors
+  if (/error|fail|exception/i.test(trimmed)) {
+    return `${ANSI.red}  ${trimmed}${ANSI.reset}`
+  }
+  // Warnings
+  if (/warn|warning|caution/i.test(trimmed)) {
+    return `${ANSI.yellow}  ${trimmed}${ANSI.reset}`
+  }
+  // Unclassified
+  return `${ANSI.gray}  ${trimmed}${ANSI.reset}`
+}
+
+export interface StreamCallbacks<T> {
+  onStderr?: (line: string) => void
+  onResult?: (data: T) => void
+  onError?: (error: { code: string; message: string }) => void
+  onDone?: () => void
+}
+
+/**
+ * Send a POST with `Accept: text/event-stream` and consume the SSE response.
+ * Returns an AbortController for cancellation.
+ */
+export function consumeClaudeStream<T>(
+  url: string,
+  body: Record<string, unknown>,
+  callbacks: StreamCallbacks<T>,
+): AbortController {
+  const controller = new AbortController()
+
+  ;(async () => {
+    try {
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Accept: 'text/event-stream',
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      })
+
+      if (!res.ok || !res.body) {
+        const data = await res.json().catch(() => ({}))
+        callbacks.onError?.({
+          code: data.code || 'HTTP_ERROR',
+          message: data.error || `Request failed with status ${res.status}`,
+        })
+        callbacks.onDone?.()
+        return
+      }
+
+      const reader = res.body.getReader()
+      const decoder = new TextDecoder()
+      let buffer = ''
+
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+
+        buffer += decoder.decode(value, { stream: true })
+
+        // Parse SSE events from buffer
+        const parts = buffer.split('\n\n')
+        // Keep the last part — it may be incomplete
+        buffer = parts.pop() || ''
+
+        for (const part of parts) {
+          const lines = part.split('\n')
+          let eventType = ''
+          let dataStr = ''
+
+          for (const line of lines) {
+            if (line.startsWith('event: ')) {
+              eventType = line.slice(7)
+            } else if (line.startsWith('data: ')) {
+              dataStr = line.slice(6)
+            }
+          }
+
+          if (!eventType || !dataStr) continue
+
+          try {
+            const payload = JSON.parse(dataStr)
+
+            switch (eventType) {
+              case 'stderr':
+                callbacks.onStderr?.(payload.line)
+                break
+              case 'result':
+                callbacks.onResult?.(payload as T)
+                break
+              case 'error':
+                callbacks.onError?.(payload)
+                break
+              case 'done':
+                // Stream ended
+                break
+            }
+          } catch {
+            // Skip malformed JSON
+          }
+        }
+      }
+    } catch (err) {
+      if ((err as Error).name !== 'AbortError') {
+        callbacks.onError?.({
+          code: 'NETWORK_ERROR',
+          message: err instanceof Error ? err.message : 'Network error',
+        })
+      }
+    } finally {
+      callbacks.onDone?.()
+    }
+  })()
+
+  return controller
+}

package/src/lib/clientProjectScanner.ts

@@ -0,0 +1,344 @@
+/**
+ * Client-side project scanner using the File System Access API.
+ * Mirrors the server-side /api/project-scan logic but runs entirely in the browser.
+ */
+
+import type { RouteEntry } from '@/types/claude'
+
+export interface ClientScanResult {
+  projectName: string
+  componentCount: number
+  componentFileMap: Record<string, string>
+  framework: string | null
+  cssStrategy: string[]
+  cssFiles: string[]
+  srcDirs: string[]
+  assetDirs: string[]
+  routes: RouteEntry[]
+}
+
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.next',
+  'dist',
+  'build',
+  '.git',
+  '__tests__',
+  '__mocks__',
+  '.turbo',
+  '.vercel',
+  'coverage',
+])
+
+const COMPONENT_EXTENSIONS = new Set(['.tsx', '.jsx'])
+const MAYBE_COMPONENT_EXTENSIONS = new Set(['.ts', '.js'])
+const CSS_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less'])
+const MAX_FILES = 5000
+
+const CONVENTION_FILES = new Set([
+  'page',
+  'layout',
+  'loading',
+  'error',
+  'not-found',
+  'template',
+  'default',
+  'route',
+  'proxy',
+  'middleware',
+  'global-error',
+  'instrumentation',
+])
+
+const ROUTE_CONVENTION_MAP: Record<string, RouteEntry['type']> = {
+  page: 'page',
+  layout: 'layout',
+  loading: 'loading',
+  error: 'error',
+  'not-found': 'not-found',
+  template: 'template',
+}
+
+const PREFERRED_SEGMENTS = new Set(['components', 'ui', 'common', 'shared'])
+
+const ASSET_DIR_NAMES = new Set([
+  'images',
+  'img',
+  'fonts',
+  'icons',
+  'media',
+  'assets',
+  'static',
+  'videos',
+  'svgs',
+  'illustrations',
+])
+
+function isPascalCase(name: string): boolean {
+  return /^[A-Z][a-zA-Z0-9]*$/.test(name)
+}
+
+function getExtension(name: string): string {
+  const i = name.lastIndexOf('.')
+  return i >= 0 ? name.slice(i) : ''
+}
+
+function getBaseName(name: string): string {
+  const ext = getExtension(name)
+  return ext ? name.slice(0, -ext.length) : name
+}
+
+function hasPreferredSegment(relativePath: string): boolean {
+  const segments = relativePath.split('/')
+  return segments.some((s) => PREFERRED_SEGMENTS.has(s))
+}
+
+function filePathToUrlPattern(relativePath: string): string {
+  const parts = relativePath.split('/')
+  const routeParts = parts.slice(1, -1)
+  const filtered = routeParts.filter((p) => !p.startsWith('('))
+  return '/' + filtered.join('/')
+}
+
+interface Collectors {
+  componentFileMap: Record<string, string>
+  cssFiles: string[]
+  routes: RouteEntry[]
+  assetDirs: Set<string>
+  hasCssModules: boolean
+}
+
+async function walkDir(
+  dirHandle: FileSystemDirectoryHandle,
+  relativePath: string,
+  collectors: Collectors,
+  counter: { count: number },
+): Promise<void> {
+  if (counter.count >= MAX_FILES) return
+
+  for await (const [name, entryHandle] of dirHandle.entries()) {
+    if (counter.count >= MAX_FILES) return
+    if (SKIP_DIRS.has(name)) continue
+
+    if (entryHandle.kind === 'directory') {
+      if (ASSET_DIR_NAMES.has(name.toLowerCase())) {
+        const relDir = relativePath ? `${relativePath}/${name}` : name
+        collectors.assetDirs.add(relDir)
+      }
+      const childPath = relativePath ? `${relativePath}/${name}` : name
+      await walkDir(
+        entryHandle as FileSystemDirectoryHandle,
+        childPath,
+        collectors,
+        counter,
+      )
+      continue
+    }
+
+    counter.count++
+    const ext = getExtension(name)
+    const baseName = getBaseName(name)
+    const filePath = relativePath ? `${relativePath}/${name}` : name
+
+    if (baseName.startsWith('.')) continue
+
+    // CSS files
+    if (CSS_EXTENSIONS.has(ext)) {
+      collectors.cssFiles.push(filePath)
+      if (name.includes('.module.')) {
+        collectors.hasCssModules = true
+      }
+      continue
+    }
+
+    // Test files
+    if (baseName.endsWith('.test') || baseName.endsWith('.spec')) continue
+
+    // Route/convention files
+    const routeType = ROUTE_CONVENTION_MAP[baseName]
+    if (
+      routeType &&
+      (COMPONENT_EXTENSIONS.has(ext) || MAYBE_COMPONENT_EXTENSIONS.has(ext))
+    ) {
+      if (filePath.startsWith('app/') || filePath.startsWith('src/app/')) {
+        const normalizedPath = filePath.startsWith('src/')
+          ? filePath.slice(4)
+          : filePath
+        collectors.routes.push({
+          urlPattern: filePathToUrlPattern(normalizedPath),
+          filePath,
+          type: routeType,
+        })
+      }
+      continue
+    }
+
+    if (baseName === 'index') continue
+    if (CONVENTION_FILES.has(baseName)) continue
+
+    // Component files
+    const isComponentExt = COMPONENT_EXTENSIONS.has(ext)
+    const isMaybeComponentExt = MAYBE_COMPONENT_EXTENSIONS.has(ext)
+    if (!isComponentExt && !isMaybeComponentExt) continue
+    if (isMaybeComponentExt && !isPascalCase(baseName)) continue
+
+    if (collectors.componentFileMap[baseName]) {
+      const existingPreferred = hasPreferredSegment(
+        collectors.componentFileMap[baseName],
+      )
+      const newPreferred = hasPreferredSegment(filePath)
+      if (newPreferred && !existingPreferred) {
+        collectors.componentFileMap[baseName] = filePath
+      }
+    } else {
+      collectors.componentFileMap[baseName] = filePath
+    }
+  }
+}
+
+function detectFramework(
+  deps: Record<string, string>,
+  devDeps: Record<string, string>,
+): string | null {
+  const all = { ...deps, ...devDeps }
+  if (all['next']) return 'Next.js'
+  if (all['@remix-run/react'] || all['remix']) return 'Remix'
+  if (all['gatsby']) return 'Gatsby'
+  if (all['astro']) return 'Astro'
+  if (all['@angular/core']) return 'Angular'
+  if (all['vue']) return 'Vue'
+  if (all['svelte']) return 'Svelte'
+  if (all['react']) return 'React'
+  return null
+}
+
+function detectCssStrategy(
+  deps: Record<string, string>,
+  devDeps: Record<string, string>,
+  hasCssModules: boolean,
+  cssFiles: string[],
+): string[] {
+  const all = { ...deps, ...devDeps }
+  const strategies: string[] = []
+  if (all['tailwindcss']) strategies.push('Tailwind')
+  if (hasCssModules) strategies.push('CSS Modules')
+  if (all['styled-components']) strategies.push('styled-components')
+  if (all['@emotion/react'] || all['@emotion/styled'])
+    strategies.push('Emotion')
+  if (all['sass'] || all['node-sass']) strategies.push('Sass')
+  if (all['less']) strategies.push('Less')
+  if (all['@vanilla-extract/css']) strategies.push('Vanilla Extract')
+  if (strategies.length === 0 && cssFiles.length > 0) strategies.push('CSS')
+  return strategies
+}
+
+/**
+ * Scan a project directory using the File System Access API.
+ * Returns the same shape as the server-side /api/project-scan endpoint.
+ */
+export async function scanProjectClient(
+  rootHandle: FileSystemDirectoryHandle,
+): Promise<ClientScanResult> {
+  // Read package.json
+  let projectName = rootHandle.name || 'unknown'
+  let deps: Record<string, string> = {}
+  let devDeps: Record<string, string> = {}
+
+  try {
+    const pkgHandle = await rootHandle.getFileHandle('package.json')
+    const pkgFile = await pkgHandle.getFile()
+    const pkgText = await pkgFile.text()
+    const pkg = JSON.parse(pkgText)
+    projectName = pkg.name || projectName
+    deps = pkg.dependencies || {}
+    devDeps = pkg.devDependencies || {}
+  } catch {
+    // No package.json or couldn't parse — continue with defaults
+  }
+
+  const collectors: Collectors = {
+    componentFileMap: {},
+    cssFiles: [],
+    routes: [],
+    assetDirs: new Set(),
+    hasCssModules: false,
+  }
+  const counter = { count: 0 }
+  const srcDirs: string[] = []
+  const candidateDirs = ['src', 'app', 'components', 'lib', 'pages', 'styles']
+  const scannedRoots: string[] = []
+
+  for (const dir of candidateDirs) {
+    const alreadyCovered = scannedRoots.some((root) =>
+      dir.startsWith(root + '/'),
+    )
+    if (alreadyCovered) continue
+
+    try {
+      const dirHandle = await rootHandle.getDirectoryHandle(dir)
+      await walkDir(dirHandle, dir, collectors, counter)
+      scannedRoots.push(dir)
+      srcDirs.push(dir)
+    } catch {
+      // Directory doesn't exist — skip
+    }
+  }
+
+  // Detect root-level config files
+  const configPatterns = [
+    'tailwind.config.js',
+    'tailwind.config.ts',
+    'tailwind.config.mjs',
+    'tailwind.config.cjs',
+    'postcss.config.js',
+    'postcss.config.ts',
+    'postcss.config.mjs',
+    'postcss.config.cjs',
+  ]
+  for (const config of configPatterns) {
+    try {
+      await rootHandle.getFileHandle(config)
+      collectors.cssFiles.push(config)
+    } catch {
+      // Not found — skip
+    }
+  }
+
+  // Detect asset dirs under public/
+  try {
+    const publicHandle = await rootHandle.getDirectoryHandle('public')
+    for await (const [name, entry] of publicHandle.entries()) {
+      if (
+        entry.kind === 'directory' &&
+        ASSET_DIR_NAMES.has(name.toLowerCase())
+      ) {
+        collectors.assetDirs.add('public/' + name)
+      }
+      if (entry.kind === 'file') {
+        collectors.assetDirs.add('public')
+      }
+    }
+  } catch {
+    // No public dir
+  }
+
+  const framework = detectFramework(deps, devDeps)
+  const cssStrategy = detectCssStrategy(
+    deps,
+    devDeps,
+    collectors.hasCssModules,
+    collectors.cssFiles,
+  )
+
+  return {
+    projectName,
+    componentCount: Object.keys(collectors.componentFileMap).length,
+    componentFileMap: collectors.componentFileMap,
+    framework,
+    cssStrategy,
+    cssFiles: collectors.cssFiles,
+    srcDirs,
+    assetDirs: Array.from(collectors.assetDirs),
+    routes: collectors.routes,
+  }
+}

package/src/lib/componentMatcher.ts

@@ -0,0 +1,156 @@
+/**
+ * Match a selected DOM element to a component file from the scanned file map.
+ *
+ * Pure function — only returns paths that exist in the provided file map.
+ * Never fabricates paths.
+ */
+
+interface ElementSignals {
+  attributes: Record<string, string>
+  id: string | null
+  className: string | null
+  selectorPath: string
+  tagName: string
+}
+
+function kebabToPascal(str: string): string {
+  return str
+    .split('-')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+}
+
+function lookup(name: string, map: Record<string, string>): string | null {
+  if (map[name]) return map[name]
+  // Try without common suffixes
+  for (const suffix of ['Component', 'View', 'Page', 'Section', 'Widget']) {
+    if (map[name + suffix]) return map[name + suffix]
+  }
+  return null
+}
+
+/**
+ * Extract potential component names from a CSS class string.
+ * Looks for PascalCase class names or kebab-case names that convert to PascalCase.
+ */
+function extractClassCandidates(className: string): string[] {
+  const candidates: string[] = []
+  const classes = className.split(/\s+/).filter(Boolean)
+
+  for (const cls of classes) {
+    // Skip Tailwind utility classes (contain brackets, colons, slashes, or start with lowercase single segment)
+    if (cls.includes('[') || cls.includes(':') || cls.includes('/')) continue
+    if (cls.startsWith('-')) continue
+
+    // Already PascalCase
+    if (/^[A-Z][a-zA-Z0-9]+$/.test(cls)) {
+      candidates.push(cls)
+      continue
+    }
+
+    // Kebab-case that looks like a component name (at least 2 segments, no numbers-only segments)
+    if (cls.includes('-') && !cls.startsWith('_')) {
+      const parts = cls.split('-')
+      if (
+        parts.length >= 2 &&
+        parts.every((p) => p.length > 0 && !/^\d+$/.test(p))
+      ) {
+        const pascal = kebabToPascal(cls)
+        if (/^[A-Z][a-zA-Z0-9]+$/.test(pascal)) {
+          candidates.push(pascal)
+        }
+      }
+    }
+  }
+
+  return candidates
+}
+
+/**
+ * Extract ancestor tag/class hints from the selectorPath.
+ * selectorPath format: "body > div.container > main > section.hero > h1"
+ */
+function extractAncestorCandidates(selectorPath: string): string[] {
+  const candidates: string[] = []
+  const segments = selectorPath.split('>').map((s) => s.trim())
+
+  // Walk from innermost to outermost (skip the element itself)
+  for (let i = segments.length - 2; i >= 0; i--) {
+    const seg = segments[i]
+
+    // Extract class names from segment like "div.ClassName" or "section.hero-section"
+    const classMatch = seg.match(/\.([a-zA-Z][\w-]*)/g)
+    if (classMatch) {
+      for (const cls of classMatch) {
+        const name = cls.slice(1) // remove leading dot
+        if (/^[A-Z][a-zA-Z0-9]+$/.test(name)) {
+          candidates.push(name)
+        } else if (name.includes('-')) {
+          const pascal = kebabToPascal(name)
+          if (/^[A-Z][a-zA-Z0-9]+$/.test(pascal)) {
+            candidates.push(pascal)
+          }
+        }
+      }
+    }
+
+    // Extract from data attributes in the segment (rare in selectorPath, but possible)
+    const dataMatch = seg.match(/\[data-component="([^"]+)"\]/)
+    if (dataMatch) {
+      candidates.push(dataMatch[1])
+    }
+  }
+
+  return candidates
+}
+
+export function matchElementToComponent(
+  signals: ElementSignals,
+  fileMap: Record<string, string>,
+): string | null {
+  // Strategy 1: data-component attribute → exact lookup
+  const dataComponent = signals.attributes['data-component']
+  if (dataComponent) {
+    const result = lookup(dataComponent, fileMap)
+    if (result) return result
+  }
+
+  // Strategy 2: data-testid → convert kebab-to-PascalCase → lookup
+  const testId = signals.attributes['data-testid']
+  if (testId) {
+    const pascal = kebabToPascal(testId)
+    const result = lookup(pascal, fileMap)
+    if (result) return result
+  }
+
+  // Strategy 3: Element id → convert to PascalCase → lookup
+  if (signals.id) {
+    const pascal = kebabToPascal(signals.id)
+    const result = lookup(pascal, fileMap)
+    if (result) return result
+
+    // Try the id as-is if it's already PascalCase
+    if (/^[A-Z]/.test(signals.id)) {
+      const result2 = lookup(signals.id, fileMap)
+      if (result2) return result2
+    }
+  }
+
+  // Strategy 4: Walk up selectorPath ancestors
+  const ancestorCandidates = extractAncestorCandidates(signals.selectorPath)
+  for (const candidate of ancestorCandidates) {
+    const result = lookup(candidate, fileMap)
+    if (result) return result
+  }
+
+  // Strategy 5: Class names that look PascalCase or convert from kebab-case
+  if (signals.className) {
+    const classCandidates = extractClassCandidates(signals.className)
+    for (const candidate of classCandidates) {
+      const result = lookup(candidate, fileMap)
+      if (result) return result
+    }
+  }
+
+  return null
+}