@antigenic-oss/paint 0.1.0

package/src/hooks/useProjectScan.ts

@@ -0,0 +1,204 @@
+import { useCallback } from 'react'
+import { useEditorStore } from '@/store'
+import { scanProjectClient } from '@/lib/clientProjectScanner'
+import { getApiBase } from '@/lib/apiBase'
+import type { RouteEntry } from '@/types/claude'
+
+export interface ScanCallbacks {
+  onSuccess?: (count: number, projectName: string) => void
+  onError?: (message: string) => void
+}
+
+export interface ScanResult {
+  success: boolean
+  count: number
+  projectName: string
+  pageCount: number
+  cssFileCount: number
+  assetDirCount: number
+  framework: string | null
+  cssStrategy: string[]
+  error?: string
+}
+
+const EMPTY_RESULT: ScanResult = {
+  success: false,
+  count: 0,
+  projectName: '',
+  pageCount: 0,
+  cssFileCount: 0,
+  assetDirCount: 0,
+  framework: null,
+  cssStrategy: [],
+}
+
+/**
+ * Shared hook that triggers a project scan and updates the store.
+ * Captures components, pages/routes, CSS files, assets, and framework info.
+ *
+ * - `triggerScan(rootPath)` — server-side scan via /api/project-scan (localhost only)
+ * - `triggerClientScan(handle)` — client-side scan via File System Access API (works on Vercel)
+ */
+export function useProjectScan() {
+  const setScanStatus = useEditorStore((s) => s.setScanStatus)
+  const setScanError = useEditorStore((s) => s.setScanError)
+  const setComponentFileMap = useEditorStore((s) => s.setComponentFileMap)
+  const setScannedProjectName = useEditorStore((s) => s.setScannedProjectName)
+  const setProjectScan = useEditorStore((s) => s.setProjectScan)
+  const pendingTargetUrl = useEditorStore((s) => s.pendingTargetUrl)
+  const targetUrl = useEditorStore((s) => s.targetUrl)
+
+  /** Populate store from scan data and return a ScanResult. */
+  const finalizeScan = useCallback(
+    (
+      data: {
+        componentFileMap: Record<string, string>
+        projectName: string
+        routes: RouteEntry[]
+        cssFiles: string[]
+        assetDirs: string[]
+        framework: string | null
+        cssStrategy: string[]
+        srcDirs: string[]
+      },
+      callbacks?: ScanCallbacks,
+    ): ScanResult => {
+      setComponentFileMap(data.componentFileMap)
+      setScannedProjectName(data.projectName)
+      setScanStatus('complete')
+
+      const count = Object.keys(data.componentFileMap || {}).length
+      const pageCount = data.routes.filter((r) => r.type === 'page').length
+
+      const url = pendingTargetUrl || targetUrl
+      if (url) {
+        setProjectScan(url, {
+          framework: data.framework,
+          cssStrategy: data.cssStrategy,
+          cssFiles: data.cssFiles,
+          srcDirs: data.srcDirs,
+          packageName: data.projectName || null,
+          assetDirs: data.assetDirs,
+          fileMap: {
+            routes: data.routes,
+            components: Object.entries(data.componentFileMap || {}).map(
+              ([name, filePath]) => ({
+                name,
+                filePath: filePath as string,
+                nameLower: name.toLowerCase(),
+                category: 'component' as const,
+              }),
+            ),
+          },
+        })
+      }
+
+      callbacks?.onSuccess?.(count, data.projectName)
+      return {
+        success: true,
+        count,
+        projectName: data.projectName,
+        pageCount,
+        cssFileCount: data.cssFiles.length,
+        assetDirCount: data.assetDirs.length,
+        framework: data.framework,
+        cssStrategy: data.cssStrategy,
+      }
+    },
+    [
+      setComponentFileMap,
+      setScannedProjectName,
+      setScanStatus,
+      setProjectScan,
+      pendingTargetUrl,
+      targetUrl,
+    ],
+  )
+
+  /** Server-side scan (localhost only). */
+  const triggerScan = useCallback(
+    async (
+      rootPath: string,
+      callbacks?: ScanCallbacks,
+    ): Promise<ScanResult> => {
+      setScanStatus('scanning')
+      setScanError(null)
+      try {
+        const res = await fetch(`${getApiBase()}/api/project-scan`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ projectRoot: rootPath }),
+        })
+        if (res.ok) {
+          const data = await res.json()
+          return finalizeScan(
+            {
+              componentFileMap: data.componentFileMap || {},
+              projectName: data.projectName || 'unknown',
+              routes: data.routes || [],
+              cssFiles: data.cssFiles || [],
+              assetDirs: data.assetDirs || [],
+              framework: data.framework || null,
+              cssStrategy: data.cssStrategy || [],
+              srcDirs: data.srcDirs || [],
+            },
+            callbacks,
+          )
+        } else {
+          const errData = await res
+            .json()
+            .catch(() => ({ error: 'Scan failed' }))
+          const message = errData.error || 'Scan failed'
+          setScanStatus('error')
+          setScanError(message)
+          callbacks?.onError?.(message)
+          return { ...EMPTY_RESULT, error: message }
+        }
+      } catch {
+        const message = 'Network error during scan'
+        setScanStatus('error')
+        setScanError(message)
+        callbacks?.onError?.(message)
+        return { ...EMPTY_RESULT, error: message }
+      }
+    },
+    [setScanStatus, setScanError, finalizeScan],
+  )
+
+  /** Client-side scan using File System Access API (works on Vercel). */
+  const triggerClientScan = useCallback(
+    async (
+      handle: FileSystemDirectoryHandle,
+      callbacks?: ScanCallbacks,
+    ): Promise<ScanResult> => {
+      setScanStatus('scanning')
+      setScanError(null)
+      try {
+        const data = await scanProjectClient(handle)
+        return finalizeScan(
+          {
+            componentFileMap: data.componentFileMap,
+            projectName: data.projectName,
+            routes: data.routes,
+            cssFiles: data.cssFiles,
+            assetDirs: data.assetDirs,
+            framework: data.framework,
+            cssStrategy: data.cssStrategy,
+            srcDirs: data.srcDirs,
+          },
+          callbacks,
+        )
+      } catch (err) {
+        const message =
+          err instanceof Error ? err.message : 'Client scan failed'
+        setScanStatus('error')
+        setScanError(message)
+        callbacks?.onError?.(message)
+        return { ...EMPTY_RESULT, error: message }
+      }
+    },
+    [setScanStatus, setScanError, finalizeScan],
+  )
+
+  return { triggerScan, triggerClientScan }
+}

package/src/hooks/useResizable.ts

@@ -0,0 +1,20 @@
+import { useCallback } from 'react'
+import { useEditorStore } from '@/store'
+
+export function useResizable(side: 'left' | 'right') {
+  const width = useEditorStore((s) =>
+    side === 'left' ? s.leftPanelWidth : s.rightPanelWidth,
+  )
+  const setWidth = useEditorStore((s) =>
+    side === 'left' ? s.setLeftPanelWidth : s.setRightPanelWidth,
+  )
+
+  const handleResize = useCallback(
+    (newWidth: number) => {
+      setWidth(newWidth)
+    },
+    [setWidth],
+  )
+
+  return { width, handleResize }
+}

package/src/hooks/useSelectedElement.ts

@@ -0,0 +1,51 @@
+'use client'
+
+import { useCallback } from 'react'
+import { useEditorStore } from '@/store'
+import { usePostMessage } from './usePostMessage'
+
+/**
+ * Hook that manages element selection with bidirectional sync.
+ * Click tree node → sends SELECT_ELEMENT to inspector.
+ * Inspector click → updates store (handled by usePostMessage).
+ */
+export function useSelectedElement() {
+  const selectorPath = useEditorStore((s) => s.selectorPath)
+  const tagName = useEditorStore((s) => s.tagName)
+  const className = useEditorStore((s) => s.className)
+  const elementId = useEditorStore((s) => s.elementId)
+  const attributes = useEditorStore((s) => s.attributes)
+  const innerText = useEditorStore((s) => s.innerText)
+  const computedStyles = useEditorStore((s) => s.computedStyles)
+  const boundingRect = useEditorStore((s) => s.boundingRect)
+  const clearSelection = useEditorStore((s) => s.clearSelection)
+  const { sendToInspector } = usePostMessage()
+
+  const selectFromTree = useCallback(
+    (selectorPath: string) => {
+      sendToInspector({
+        type: 'SELECT_ELEMENT',
+        payload: { selectorPath },
+      })
+    },
+    [sendToInspector],
+  )
+
+  const deselect = useCallback(() => {
+    clearSelection()
+  }, [clearSelection])
+
+  return {
+    selectorPath,
+    tagName,
+    className,
+    elementId,
+    attributes,
+    innerText,
+    computedStyles,
+    boundingRect,
+    selectFromTree,
+    deselect,
+    isSelected: selectorPath !== null,
+  }
+}

package/src/hooks/useTargetUrl.ts

@@ -0,0 +1,81 @@
+'use client'
+
+import { useEffect, useRef, useCallback } from 'react'
+import { useEditorStore } from '@/store'
+import { usePostMessage } from './usePostMessage'
+import {
+  HEARTBEAT_INTERVAL_MS,
+  RECONNECT_MAX_RETRIES,
+  RECONNECT_BASE_DELAY_MS,
+} from '@/lib/constants'
+
+export function useTargetUrl() {
+  const connectionStatus = useEditorStore((s) => s.connectionStatus)
+  const targetUrl = useEditorStore((s) => s.targetUrl)
+  const setConnectionStatus = useEditorStore((s) => s.setConnectionStatus)
+  const { sendHeartbeat } = usePostMessage()
+
+  const heartbeatIntervalRef = useRef<ReturnType<typeof setInterval> | null>(
+    null,
+  )
+  const retryCountRef = useRef(0)
+  const retryTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  const startHeartbeat = useCallback(() => {
+    if (heartbeatIntervalRef.current)
+      clearInterval(heartbeatIntervalRef.current)
+
+    heartbeatIntervalRef.current = setInterval(async () => {
+      const alive = await sendHeartbeat()
+      if (!alive) {
+        setConnectionStatus('disconnected')
+      }
+    }, HEARTBEAT_INTERVAL_MS)
+  }, [sendHeartbeat, setConnectionStatus])
+
+  const stopHeartbeat = useCallback(() => {
+    if (heartbeatIntervalRef.current) {
+      clearInterval(heartbeatIntervalRef.current)
+      heartbeatIntervalRef.current = null
+    }
+  }, [])
+
+  // Start heartbeat when connected
+  useEffect(() => {
+    if (connectionStatus === 'connected') {
+      retryCountRef.current = 0
+      startHeartbeat()
+    } else {
+      stopHeartbeat()
+    }
+    return stopHeartbeat
+  }, [connectionStatus, startHeartbeat, stopHeartbeat])
+
+  // Auto-reconnect on disconnect (confirming/scanning have null targetUrl so they won't trigger this)
+  useEffect(() => {
+    if (
+      connectionStatus !== 'disconnected' ||
+      !targetUrl ||
+      retryCountRef.current >= RECONNECT_MAX_RETRIES
+    )
+      return
+
+    const delay = RECONNECT_BASE_DELAY_MS * Math.pow(2, retryCountRef.current)
+    retryTimeoutRef.current = setTimeout(() => {
+      retryCountRef.current++
+      setConnectionStatus('connecting')
+    }, delay)
+
+    return () => {
+      if (retryTimeoutRef.current) {
+        clearTimeout(retryTimeoutRef.current)
+      }
+    }
+  }, [connectionStatus, targetUrl, setConnectionStatus])
+
+  return {
+    isConnected: connectionStatus === 'connected',
+    isConnecting: connectionStatus === 'connecting',
+    isDisconnected: connectionStatus === 'disconnected',
+  }
+}

package/src/inspector/DOMTraverser.ts

@@ -0,0 +1,71 @@
+/**
+ * DOM tree serialization for the inspector.
+ * Converts live DOM into TreeNode structure for the editor's left panel.
+ */
+
+import type { TreeNode } from '@/types/tree'
+
+export function generateSelectorPath(element: Element): string {
+  const parts: string[] = []
+  let current: Element | null = element
+
+  while (current && current !== document.documentElement) {
+    let selector = current.tagName.toLowerCase()
+
+    if (current.id) {
+      selector += `#${current.id}`
+      parts.unshift(selector)
+      break
+    }
+
+    if (current.className && typeof current.className === 'string') {
+      const classes = current.className.trim().split(/\s+/).filter(Boolean)
+      if (classes.length > 0) {
+        selector += '.' + classes.join('.')
+      }
+    }
+
+    const parent = current.parentElement
+    if (parent) {
+      const siblings = Array.from(parent.children).filter(
+        (child) => child.tagName === current!.tagName,
+      )
+      if (siblings.length > 1) {
+        const index = siblings.indexOf(current) + 1
+        selector += `:nth-of-type(${index})`
+      }
+    }
+
+    parts.unshift(selector)
+    current = current.parentElement
+  }
+
+  return parts.join(' > ')
+}
+
+const SKIP_TAGS = new Set(['script', 'style', 'link', 'noscript'])
+
+export function serializeTree(element: Element): TreeNode | null {
+  if (!element || element.nodeType !== 1) return null
+
+  const tagName = element.tagName.toLowerCase()
+  if (SKIP_TAGS.has(tagName)) return null
+
+  const children: TreeNode[] = []
+  for (let i = 0; i < element.children.length; i++) {
+    const child = serializeTree(element.children[i])
+    if (child) children.push(child)
+  }
+
+  return {
+    id: generateSelectorPath(element),
+    tagName,
+    className:
+      element.className && typeof element.className === 'string'
+        ? element.className
+        : null,
+    elementId: element.id || null,
+    children,
+    imgSrc: tagName === 'img' ? element.getAttribute('src') || null : null,
+  }
+}

package/src/inspector/ElementSelector.ts

@@ -0,0 +1,23 @@
+/**
+ * Click handler in capture phase for element selection.
+ * Source reference — runtime code is inlined in the proxy route.
+ */
+
+export type SelectCallback = (element: Element) => void
+
+export function createElementSelector(onSelect: SelectCallback) {
+  const handler = (e: MouseEvent) => {
+    e.preventDefault()
+    e.stopPropagation()
+    const el = document.elementFromPoint(e.clientX, e.clientY)
+    if (el) onSelect(el)
+  }
+
+  document.addEventListener('click', handler, true)
+
+  return {
+    destroy() {
+      document.removeEventListener('click', handler, true)
+    },
+  }
+}

package/src/inspector/HoverHighlighter.ts

@@ -0,0 +1,54 @@
+/**
+ * visual-editor-style hover highlight — dotted green border + element name label.
+ * Source reference — runtime code is inlined in the proxy route.
+ */
+
+export function createHoverHighlighter() {
+  const overlay = document.createElement('div')
+  overlay.style.cssText =
+    'position:fixed;pointer-events:none;z-index:999996;border:1px dashed rgba(74,222,128,0.30);display:none;transition:top 0.04s,left 0.04s,width 0.04s,height 0.04s;'
+  document.body.appendChild(overlay)
+
+  const label = document.createElement('div')
+  label.style.cssText =
+    'position:absolute;top:-18px;left:-1px;padding:1px 6px;font-size:10px;font-family:-apple-system,BlinkMacSystemFont,sans-serif;line-height:14px;color:#fff;background:rgba(74,222,128,0.70);border-radius:3px 3px 0 0;white-space:nowrap;pointer-events:none;'
+  overlay.appendChild(label)
+
+  function getElementLabel(el: Element): string {
+    const tag = el.tagName.toLowerCase()
+    if (el.id) return tag + '#' + el.id
+    const cls = el.className
+    if (cls && typeof cls === 'string') {
+      const first = cls.trim().split(/\s+/)[0]
+      if (first) return tag + '.' + first
+    }
+    return tag
+  }
+
+  return {
+    show(el: Element, rect: DOMRect) {
+      overlay.style.display = 'block'
+      overlay.style.top = rect.top + 'px'
+      overlay.style.left = rect.left + 'px'
+      overlay.style.width = rect.width + 'px'
+      overlay.style.height = rect.height + 'px'
+      label.textContent = getElementLabel(el)
+      // Flip label below if near top
+      if (rect.top < 20) {
+        label.style.top = 'auto'
+        label.style.bottom = '-18px'
+        label.style.borderRadius = '0 0 3px 3px'
+      } else {
+        label.style.top = '-18px'
+        label.style.bottom = 'auto'
+        label.style.borderRadius = '3px 3px 0 0'
+      }
+    },
+    hide() {
+      overlay.style.display = 'none'
+    },
+    destroy() {
+      overlay.remove()
+    },
+  }
+}

package/src/inspector/SelectionHighlighter.ts

@@ -0,0 +1,27 @@
+/**
+ * Persistent outline on selected element.
+ * Source reference — runtime code is inlined in the proxy route.
+ */
+
+export function createSelectionHighlighter() {
+  const overlay = document.createElement('div')
+  overlay.style.cssText =
+    'position:fixed;pointer-events:none;z-index:999997;border:2px solid #4a9eff;display:none;'
+  document.body.appendChild(overlay)
+
+  return {
+    show(rect: DOMRect) {
+      overlay.style.display = 'block'
+      overlay.style.top = rect.top + 'px'
+      overlay.style.left = rect.left + 'px'
+      overlay.style.width = rect.width + 'px'
+      overlay.style.height = rect.height + 'px'
+    },
+    hide() {
+      overlay.style.display = 'none'
+    },
+    destroy() {
+      overlay.remove()
+    },
+  }
+}

package/src/inspector/StyleExtractor.ts

@@ -0,0 +1,19 @@
+/**
+ * Extract computed styles for the design panel.
+ * Source reference — runtime code is inlined in the proxy route.
+ */
+
+import { ALL_EDITABLE_PROPERTIES } from '@/lib/constants'
+
+export function getComputedStylesForElement(
+  element: Element,
+): Record<string, string> {
+  const computed = window.getComputedStyle(element)
+  const styles: Record<string, string> = {}
+
+  for (const prop of ALL_EDITABLE_PROPERTIES) {
+    styles[prop] = computed.getPropertyValue(prop)
+  }
+
+  return styles
+}

package/src/inspector/inspector.ts

@@ -0,0 +1,17 @@
+/**
+ * Inspector entry point.
+ * This file is the source for the inspector IIFE injected into the iframe.
+ * The actual runtime code is inlined in the proxy route for simplicity.
+ * This module serves as the canonical source reference.
+ *
+ * Modules:
+ * - DOMTraverser: Serializes DOM to TreeNode
+ * - HoverHighlighter: Blue overlay on mousemove
+ * - ElementSelector: Click to select with computed styles
+ * - SelectionHighlighter: Persistent outline on selected element
+ * - StyleExtractor: getComputedStyle reader
+ * - messaging: postMessage send/receive bridge
+ */
+
+export { generateSelectorPath, serializeTree } from './DOMTraverser'
+export { getComputedStylesForElement } from './StyleExtractor'

package/src/inspector/messaging.ts

@@ -0,0 +1,30 @@
+/**
+ * Inspector messaging bridge.
+ * Handles postMessage send/receive with origin checking.
+ * Runtime code is inlined in the proxy; this is the source reference.
+ */
+
+import type {
+  InspectorToEditorMessage,
+  EditorToInspectorMessage,
+} from '@/types/messages'
+
+const parentOrigin = typeof window !== 'undefined' ? window.location.origin : ''
+
+export function sendToEditor(message: InspectorToEditorMessage): void {
+  window.parent.postMessage(message, parentOrigin)
+}
+
+export type MessageHandler = (message: EditorToInspectorMessage) => void
+
+export function listenForEditorMessages(handler: MessageHandler): () => void {
+  const listener = (event: MessageEvent) => {
+    if (event.origin !== parentOrigin) return
+    const data = event.data
+    if (!data || !data.type) return
+    handler(data as EditorToInspectorMessage)
+  }
+
+  window.addEventListener('message', listener)
+  return () => window.removeEventListener('message', listener)
+}

package/src/lib/apiBase.ts

@@ -0,0 +1,15 @@
+import { useEditorStore } from '@/store'
+
+/**
+ * Returns the base URL for API calls.
+ *
+ * - When running locally: returns '' (same-origin).
+ * - When running remotely with bridge: returns the bridge URL (e.g. 'http://localhost:4002').
+ * - When running remotely without bridge: returns '' (calls go to Vercel routes).
+ */
+export function getApiBase(): string {
+  if (typeof window === 'undefined') return ''
+  const h = window.location.hostname
+  if (h === 'localhost' || h === '127.0.0.1') return ''
+  return useEditorStore.getState().bridgeUrl || ''
+}