@antigenic-oss/paint 0.1.0

package/src/lib/tailwindClassParser.ts

@@ -0,0 +1,248 @@
+import type { CSSVariableDefinition } from '@/types/cssVariables'
+
+export interface TailwindColorClass {
+  className: string // e.g. 'text-primary'
+  prefix: string // e.g. 'text'
+  tokenName: string // e.g. 'primary'
+  cssProperty: string // e.g. 'color'
+}
+
+/**
+ * Map of Tailwind color prefixes to their corresponding CSS properties.
+ */
+const PREFIX_TO_PROPERTY: Record<string, string> = {
+  text: 'color',
+  bg: 'backgroundColor',
+  border: 'borderColor',
+  outline: 'outlineColor',
+  ring: '--tw-ring-color',
+  decoration: 'textDecorationColor',
+  accent: 'accentColor',
+  fill: 'fill',
+  stroke: 'stroke',
+}
+
+/**
+ * Non-color suffixes that look like color classes but aren't.
+ * These follow a color prefix (e.g. text-center, bg-clip-text, border-collapse).
+ */
+const NON_COLOR_SUFFIXES = new Set([
+  // text- non-color
+  'center',
+  'left',
+  'right',
+  'justify',
+  'start',
+  'end',
+  'wrap',
+  'nowrap',
+  'balance',
+  'pretty',
+  'xs',
+  'sm',
+  'base',
+  'lg',
+  'xl',
+  '2xl',
+  '3xl',
+  '4xl',
+  '5xl',
+  '6xl',
+  '7xl',
+  '8xl',
+  '9xl',
+  'ellipsis',
+  'clip',
+  'truncate',
+  // bg- non-color
+  'repeat',
+  'no-repeat',
+  'contain',
+  'cover',
+  'auto',
+  'fixed',
+  'local',
+  'scroll',
+  'clip',
+  'origin',
+  'bottom',
+  'top',
+  'center',
+  'left',
+  'right',
+  'gradient-to-t',
+  'gradient-to-tr',
+  'gradient-to-r',
+  'gradient-to-br',
+  'gradient-to-b',
+  'gradient-to-bl',
+  'gradient-to-l',
+  'gradient-to-tl',
+  'none',
+  // border- non-color
+  'collapse',
+  'separate',
+  'solid',
+  'dashed',
+  'dotted',
+  'double',
+  'hidden',
+  '0',
+  '1',
+  '2',
+  '4',
+  '8',
+  'x',
+  'y',
+  't',
+  'r',
+  'b',
+  'l',
+  'e',
+  's',
+  'spacing',
+  // outline- non-color
+  'offset',
+  'dashed',
+  'dotted',
+  'double',
+  // fill/stroke non-color
+  'rule',
+  // ring- non-color
+  'offset',
+  'inset',
+  // General
+  'inherit',
+  'current',
+  'transparent',
+])
+
+/**
+ * Multi-word non-color suffixes where the first token alone
+ * might look like a color but the combination is not.
+ */
+const NON_COLOR_COMPOUND = new Set([
+  'clip-text',
+  'clip-border',
+  'clip-padding',
+  'clip-content',
+  'origin-border',
+  'origin-padding',
+  'origin-content',
+  'repeat-x',
+  'repeat-y',
+  'repeat-round',
+  'repeat-space',
+  'decoration-slice',
+  'decoration-clone',
+  'offset-0',
+  'offset-1',
+  'offset-2',
+  'offset-4',
+  'offset-8',
+])
+
+/**
+ * Parse a className string and extract Tailwind color class mappings.
+ * Returns one mapping per CSS property (last class wins if duplicates).
+ */
+export function parseTailwindColorClasses(
+  className: string | null,
+): TailwindColorClass[] {
+  if (!className) return []
+
+  const classes = className.trim().split(/\s+/).filter(Boolean)
+  const results: TailwindColorClass[] = []
+
+  for (const cls of classes) {
+    // Strip responsive/state prefixes: md:text-primary → text-primary
+    // Also handles chained: hover:md:text-primary → text-primary
+    const stripped = cls.replace(/^(?:[a-z0-9-]+:)+/, '')
+
+    // Skip arbitrary values: text-[#ff0000], bg-[rgb(0,0,0)]
+    if (stripped.includes('[')) continue
+
+    // Try to match each known prefix
+    for (const [prefix, cssProperty] of Object.entries(PREFIX_TO_PROPERTY)) {
+      const prefixWithDash = prefix + '-'
+      if (!stripped.startsWith(prefixWithDash)) continue
+
+      const suffix = stripped.slice(prefixWithDash.length)
+      if (!suffix) continue
+
+      // Check against non-color suffixes
+      if (NON_COLOR_SUFFIXES.has(suffix)) continue
+      if (NON_COLOR_COMPOUND.has(suffix)) continue
+
+      // Skip if suffix starts with a non-color compound prefix
+      const firstPart = suffix.split('-')[0]
+      if (NON_COLOR_SUFFIXES.has(firstPart) && suffix.includes('-')) {
+        // e.g. bg-clip-text → firstPart is 'clip' which is non-color
+        if (NON_COLOR_COMPOUND.has(suffix)) continue
+      }
+
+      // Skip pure numeric suffixes for non-border prefixes
+      // (border-2 is sizing, but text-500 could be a shade if no base)
+      if (/^\d+$/.test(suffix) && prefix !== 'border') continue
+
+      results.push({
+        className: stripped,
+        prefix,
+        tokenName: suffix,
+        cssProperty,
+      })
+      break // matched a prefix, stop checking others
+    }
+  }
+
+  return results
+}
+
+/**
+ * Resolve a Tailwind token name to a CSS variable from available definitions.
+ *
+ * Search order:
+ * 1. --{tokenName}          (e.g. --primary)
+ * 2. --color-{tokenName}    (Tailwind v4 convention)
+ * 3. --colors-{tokenName}   (common naming)
+ *
+ * Returns the matching variable name or null.
+ */
+export function resolveTokenToVariable(
+  tokenName: string,
+  definitions: Record<string, CSSVariableDefinition>,
+): string | null {
+  const candidates = [
+    `--${tokenName}`,
+    `--color-${tokenName}`,
+    `--colors-${tokenName}`,
+  ]
+
+  for (const candidate of candidates) {
+    if (candidate in definitions) return candidate
+  }
+
+  return null
+}
+
+/**
+ * Build a map of CSS property → TailwindColorClass with resolved variable,
+ * from a className string and available CSS variable definitions.
+ */
+export function buildTailwindClassMap(
+  className: string | null,
+  definitions: Record<string, CSSVariableDefinition>,
+): Record<string, TailwindColorClass & { variableName: string | null }> {
+  const parsed = parseTailwindColorClasses(className)
+  const map: Record<
+    string,
+    TailwindColorClass & { variableName: string | null }
+  > = {}
+
+  for (const entry of parsed) {
+    const variableName = resolveTokenToVariable(entry.tokenName, definitions)
+    map[entry.cssProperty] = { ...entry, variableName }
+  }
+
+  return map
+}

package/src/lib/textShadowUtils.ts

@@ -0,0 +1,106 @@
+export interface TextShadowData {
+  x: number
+  y: number
+  blur: number
+  color: string
+}
+
+/**
+ * Split a text-shadow CSS string by commas, respecting nested parentheses.
+ */
+function splitShadows(css: string): string[] {
+  const parts: string[] = []
+  let depth = 0
+  let current = ''
+  for (let i = 0; i < css.length; i++) {
+    const ch = css[i]
+    if (ch === '(') depth++
+    else if (ch === ')') depth--
+    if (ch === ',' && depth === 0) {
+      parts.push(current.trim())
+      current = ''
+    } else {
+      current += ch
+    }
+  }
+  if (current.trim()) parts.push(current.trim())
+  return parts
+}
+
+/**
+ * Parse a single text-shadow string like "2px 4px 6px rgba(0,0,0,0.3)"
+ */
+function parseSingleTextShadow(str: string): TextShadowData | null {
+  const trimmed = str.trim()
+  if (!trimmed || trimmed === 'none') return null
+
+  let working = trimmed
+  let color = 'rgba(0,0,0,0.25)'
+  let numericPart = working
+
+  // Try color at end: rgb(...), rgba(...), hsl(...), hsla(...)
+  const colorFuncEnd = working.match(/((?:rgba?|hsla?)\([^)]+\))$/)
+  if (colorFuncEnd) {
+    color = colorFuncEnd[1]
+    numericPart = working
+      .slice(0, working.length - colorFuncEnd[0].length)
+      .trim()
+  } else {
+    const hexEnd = working.match(/(#[0-9a-fA-F]{3,8})$/)
+    if (hexEnd) {
+      color = hexEnd[1]
+      numericPart = working.slice(0, working.length - hexEnd[0].length).trim()
+    } else {
+      // Try color at start
+      const colorFuncStart = working.match(/^((?:rgba?|hsla?)\([^)]+\))\s+/)
+      if (colorFuncStart) {
+        color = colorFuncStart[1]
+        numericPart = working.slice(colorFuncStart[0].length).trim()
+      } else {
+        // Try named color at the end (last token)
+        const tokens = working.split(/\s+/)
+        if (tokens.length >= 3) {
+          const lastToken = tokens[tokens.length - 1]
+          if (!/^-?\d/.test(lastToken) && !lastToken.includes('px')) {
+            color = lastToken
+            numericPart = tokens.slice(0, -1).join(' ')
+          }
+        }
+      }
+    }
+  }
+
+  // Parse numeric values: x y [blur]
+  const numTokens = numericPart.split(/\s+/).map((t) => parseFloat(t))
+  const x = numTokens[0] || 0
+  const y = numTokens[1] || 0
+  const blur = numTokens[2] || 0
+
+  return { x, y, blur, color }
+}
+
+/**
+ * Parse a text-shadow CSS string into an array of TextShadowData objects.
+ * Returns [] for "none" or unparseable.
+ */
+export function parseTextShadow(value: string): TextShadowData[] {
+  if (!value || value === 'none') return []
+  const parts = splitShadows(value)
+  const shadows: TextShadowData[] = []
+  for (const part of parts) {
+    const shadow = parseSingleTextShadow(part)
+    if (shadow) shadows.push(shadow)
+  }
+  return shadows
+}
+
+/**
+ * Serialize TextShadowData array back to a valid CSS text-shadow string.
+ * Returns "none" for empty array.
+ */
+export function serializeTextShadow(shadows: TextShadowData[]): string {
+  if (shadows.length === 0) return 'none'
+  return shadows
+    .map((s) => `${s.x}px ${s.y}px ${s.blur}px ${s.color}`)
+    .join(', ')
+}

package/src/lib/utils.ts

@@ -0,0 +1,299 @@
+import {
+  getBreakpointDeviceInfo,
+  buildInstructionsFooter,
+} from '@/lib/constants'
+
+/**
+ * Convert a camelCase CSS property name to kebab-case.
+ * Handles vendor prefixes: webkitTextStroke → -webkit-text-stroke
+ */
+export function camelToKebab(s: string): string {
+  const k = s.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase())
+  if (/^(webkit|moz|ms)-/.test(k)) return '-' + k
+  return k
+}
+
+/**
+ * Generate a CSS selector path for a DOM element.
+ */
+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(' > ')
+}
+
+/**
+ * Find an element by its CSS selector path.
+ */
+export function findElementBySelector(selectorPath: string): Element | null {
+  try {
+    return document.querySelector(selectorPath)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Parse a CSS value into number and unit parts.
+ */
+export function parseCSSValue(value: string): { number: number; unit: string } {
+  const match = value.match(/^(-?\d*\.?\d+)(px|%|em|rem|vh|vw|pt|ch|ex)?$/)
+  if (match) {
+    return { number: parseFloat(match[1]), unit: match[2] || 'px' }
+  }
+  return { number: 0, unit: 'px' }
+}
+
+/**
+ * Format a CSS value from number and unit parts.
+ */
+export function formatCSSValue(num: number, unit: string): string {
+  if (unit === 'auto') return 'auto'
+  return `${num}${unit}`
+}
+
+/**
+ * Validate that a URL is a localhost address.
+ */
+export function isLocalhostUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url)
+    return parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Normalize a target URL (ensure trailing slash, etc.)
+ */
+export function normalizeTargetUrl(url: string): string {
+  try {
+    const parsed = new URL(url)
+    return parsed.origin
+  } catch {
+    return url
+  }
+}
+
+/**
+ * Generate a unique ID.
+ */
+export function generateId(): string {
+  return crypto.randomUUID()
+}
+
+/**
+ * Clamp a number between min and max.
+ */
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max)
+}
+
+/**
+ * Strip control characters from a string (keep newlines and tabs).
+ */
+export function stripControlChars(str: string): string {
+  return str.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '')
+}
+
+/**
+ * Generate a structured changelog text from tracked changes.
+ */
+export function formatChangelog(opts: {
+  targetUrl: string
+  pagePath: string
+  breakpoint: import('@/types/changelog').Breakpoint
+  breakpointWidth: number
+  styleChanges: import('@/types/changelog').StyleChange[]
+  framework?: string | null
+  cssStrategy?: string[] | null
+}): string {
+  const { targetUrl, pagePath, breakpoint, styleChanges } = opts
+
+  const { deviceName, range } = getBreakpointDeviceInfo(breakpoint)
+
+  const lines: string[] = []
+  const timestamp = new Date().toISOString()
+
+  lines.push('=== DEV EDITOR CHANGELOG ===')
+  lines.push(`Project URL: ${targetUrl}`)
+  lines.push(`Page: ${pagePath || '/'}`)
+  lines.push(`Device Name: ${deviceName}`)
+  lines.push(`Breakpoint: ${range}`)
+  lines.push(`Generated: ${timestamp}`)
+  lines.push('')
+
+  // Separate special entries from regular style changes
+  const componentExtractions = styleChanges.filter(
+    (c) => c.property === '__component_creation__',
+  )
+  const variableDefinitions = styleChanges.filter(
+    (c) => c.elementSelector === ':root' && c.property.startsWith('--'),
+  )
+  const regularChanges = styleChanges.filter(
+    (c) =>
+      c.property !== '__component_creation__' &&
+      !(c.elementSelector === ':root' && c.property.startsWith('--')),
+  )
+
+  // Component Extractions section
+  if (componentExtractions.length > 0) {
+    lines.push('## Component Extractions')
+    lines.push('')
+
+    for (const extraction of componentExtractions) {
+      try {
+        const data = JSON.parse(extraction.newValue) as {
+          name: string
+          variants: Array<{ groupName: string; options: string[] }>
+        }
+        const kebabName = data.name
+          .replace(/([a-z])([A-Z])/g, '$1-$2')
+          .replace(/\s+/g, '-')
+          .toLowerCase()
+        lines.push(`### ${data.name} Component`)
+        lines.push(`- Selector: \`${extraction.elementSelector}\``)
+        lines.push(`- Suggested file: \`src/components/${kebabName}.tsx\``)
+        if (data.variants.length > 0) {
+          lines.push('- Suggested props:')
+          for (const v of data.variants) {
+            lines.push(
+              `  - ${v.groupName.toLowerCase()}: ${v.options.join(' | ')}`,
+            )
+          }
+        }
+        lines.push('')
+      } catch {
+        // Skip malformed extraction entries
+      }
+    }
+  }
+
+  // CSS Variable Definitions section
+  if (variableDefinitions.length > 0) {
+    lines.push('## CSS Variable Definitions')
+    lines.push('')
+    lines.push(
+      "Add these CSS custom properties to the project's root stylesheet (`:root` or `html` selector):",
+    )
+    lines.push('')
+    for (const v of variableDefinitions) {
+      // Find which element property references this variable
+      const varRef = `var(${v.property})`
+      const referencing = regularChanges.filter((c) => c.newValue === varRef)
+      lines.push(`- \`${v.property}: ${v.newValue}\``)
+      for (const ref of referencing) {
+        lines.push(
+          `  - Used by: \`${ref.elementSelector}\` → ${ref.property}: var(${v.property})`,
+        )
+      }
+    }
+    lines.push('')
+  }
+
+  // Group regular style changes by element selector
+  if (regularChanges.length > 0) {
+    lines.push('## Style Changes')
+    lines.push('')
+
+    const grouped = new Map<string, typeof regularChanges>()
+    for (const change of regularChanges) {
+      const existing = grouped.get(change.elementSelector) || []
+      existing.push(change)
+      grouped.set(change.elementSelector, existing)
+    }
+
+    for (const [selector, changes] of grouped) {
+      lines.push(`### ${selector}`)
+      for (const c of changes) {
+        lines.push(
+          `- ${c.property}: "${c.originalValue}" → "${c.newValue}" [${c.breakpoint}]`,
+        )
+      }
+      lines.push('')
+    }
+  }
+
+  // Summary + instructions footer (framework-aware)
+  const totalChanges = styleChanges.length
+  const uniqueElements = new Set(styleChanges.map((c) => c.elementSelector))
+    .size
+
+  // Temporarily override summary line in the footer with component extraction count
+  const summaryPrefix = `${totalChanges} change${totalChanges !== 1 ? 's' : ''} across ${uniqueElements} element${uniqueElements !== 1 ? 's' : ''}${componentExtractions.length > 0 ? ` (${componentExtractions.length} component extraction${componentExtractions.length !== 1 ? 's' : ''})` : ''}`
+  lines.push('---')
+  lines.push(`Summary: ${summaryPrefix}`)
+  lines.push('')
+
+  // Get the framework-aware instructions (skip the first 3 lines which are --- / Summary / blank)
+  const footer = buildInstructionsFooter(totalChanges, uniqueElements, {
+    framework: opts.framework,
+    cssStrategy: opts.cssStrategy,
+  })
+  const footerLines = footer.split('\n')
+  // Skip "---", "Summary: ...", and blank line from footer — we already wrote our own summary
+  const instructionsStart = footerLines.findIndex((l) =>
+    l.startsWith('## Instructions'),
+  )
+  if (instructionsStart >= 0) {
+    lines.push(footerLines.slice(instructionsStart).join('\n'))
+  } else {
+    // Fallback: append entire footer
+    lines.push(footer)
+  }
+
+  if (variableDefinitions.length > 0) {
+    // Insert CSS variable guidance before the closing marker
+    const closingIdx = lines.lastIndexOf('=== END CHANGELOG ===')
+    const varLines = [
+      '',
+      '### CSS Variable Guidance',
+      'When the changelog includes CSS Variable Definitions, create the custom',
+      "properties in the project's root stylesheet or theme file. Then update",
+      'the referencing elements to use var(--name) instead of hardcoded values.',
+      'If using Tailwind, consider adding the variables to the theme config.',
+    ]
+    if (closingIdx >= 0) {
+      lines.splice(closingIdx, 0, ...varLines)
+    } else {
+      lines.push(...varLines)
+      lines.push('=== END CHANGELOG ===')
+    }
+  }
+
+  const result = lines.join('\n')
+  return stripControlChars(result).slice(0, 50 * 1024)
+}

package/src/lib/validatePath.ts

@@ -0,0 +1,40 @@
+import { existsSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { homedir } from 'node:os'
+
+/**
+ * Validate that projectRoot is an absolute path, exists as a directory,
+ * and resides under the user's HOME directory.
+ *
+ * Returns an error message string if invalid, or null if valid.
+ */
+export function validateProjectRoot(projectRoot: string): string | null {
+  if (!path.isAbsolute(projectRoot)) {
+    return 'projectRoot must be an absolute path'
+  }
+
+  const resolvedHome = path.resolve(homedir())
+  const resolved = path.resolve(projectRoot)
+
+  if (
+    !resolved.startsWith(resolvedHome + path.sep) &&
+    resolved !== resolvedHome
+  ) {
+    return 'projectRoot must be under the user home directory'
+  }
+
+  if (!existsSync(resolved)) {
+    return 'projectRoot does not exist'
+  }
+
+  try {
+    const stat = statSync(resolved)
+    if (!stat.isDirectory()) {
+      return 'projectRoot is not a directory'
+    }
+  } catch {
+    return 'Unable to stat projectRoot'
+  }
+
+  return null
+}