create-visualbuild-app 0.1.0 → 1.0.0

package/visual-app-builder/vite.config.ts

@@ -1,1479 +1,1946 @@
-import { execFile } from 'node:child_process'
-import { randomUUID } from 'node:crypto'
-import fs from 'node:fs/promises'
-import type { ServerResponse } from 'node:http'
-import path from 'node:path'
-import { promisify } from 'node:util'
-import { watch as watchFiles } from 'chokidar'
-import { defineConfig } from 'vite'
-import type { Plugin } from 'vite'
-import react from '@vitejs/plugin-react'
-import tailwindcss from '@tailwindcss/vite'
-import {
-  parseReactPageSource,
-  reconcileImportedTree,
-  visualTreesEqual,
-  type ImportedPageTree,
-  type ImportedVisualNode,
-} from './server/parseReactPage'
-
-const execFileAsync = promisify(execFile)
-const builderPackageRoot = process.cwd()
-const projectRoot = path.resolve(
-  process.env.VISUALBUILD_APP_DIR || builderPackageRoot
-)
-const builderRoot = path.resolve(builderPackageRoot, 'visual-app-builder')
-const generatedSourceRoot = path.resolve(projectRoot, 'src')
-const visualbuildRoot = path.resolve(projectRoot, 'visualbuild')
-const maxEditableFileBytes = 2 * 1024 * 1024
-const hiddenProjectEntries = new Set(['.git', 'node_modules'])
-
-type ProjectEntryKind = 'file' | 'directory' | 'symlink'
-
-interface ProjectEntry {
-  name: string
-  path: string
-  kind: ProjectEntryKind
-}
-
-interface ManagedPage {
-  id: string
-  name: string
-  route: string
-  sourcePath?: string
-  root: ImportedVisualNode
-  components: ImportedVisualNode[]
-}
-
-interface ManagedProjectSchema {
-  pages: ManagedPage[]
-  [key: string]: unknown
-}
-
-interface ReverseSyncEvent {
-  type: 'reverse-sync-success' | 'reverse-sync-error'
-  path: string
-  pageId?: string
-  message: string
-}
-
-interface GeneratorDiagnostic {
-  severity: 'error'
-  phase: 'generate'
-  code: string
-  title: string
-  message: string
-  path: string
-  suggestion?: string
-}
-
-interface GeneratorDiagnosticEvent extends GeneratorDiagnostic {
-  type: 'generator-diagnostic'
-}
-
-interface FileSystemEvent {
-  type: 'filesystem-change'
-  path: string
-  action: 'add' | 'change' | 'unlink' | 'addDir' | 'unlinkDir'
-}
-
-interface ManagedPagesDeletedEvent {
-  type: 'managed-pages-deleted'
-  path: string
-  pageIds: string[]
-  message: string
-}
-
-interface ManagedPagePathChange {
-  pageId: string
-  previousPath: string
-  sourcePath: string
-}
-
-interface ManagedPagesMovedEvent {
-  type: 'managed-pages-moved'
-  path: string
-  targetPath: string
-  pages: ManagedPagePathChange[]
-  message: string
-}
-
-type VisualBuildEvent =
-  | ReverseSyncEvent
-  | GeneratorDiagnosticEvent
-  | FileSystemEvent
-  | ManagedPagesDeletedEvent
-  | ManagedPagesMovedEvent
-
-function isGeneratedProjectPath(watchedPath: string) {
-  const absolutePath = path.resolve(watchedPath)
-
-  return [generatedSourceRoot, visualbuildRoot].some(
-    (rootPath) =>
-      absolutePath === rootPath || absolutePath.startsWith(`${rootPath}${path.sep}`)
-  )
-}
-
-function sendJson(
-  res: { statusCode: number; setHeader: (name: string, value: string) => void; end: (body?: string) => void },
-  statusCode: number,
-  payload: unknown
-) {
-  res.statusCode = statusCode
-  res.setHeader('Content-Type', 'application/json')
-  res.end(JSON.stringify(payload))
-}
-
-function getProjectPath(relativePath = '') {
-  const normalizedInput = relativePath.replace(/\\/g, '/').trim()
-
-  if (
-    normalizedInput.startsWith('/') ||
-    /^[a-zA-Z]:/.test(normalizedInput) ||
-    normalizedInput.includes('\0')
-  ) {
-    throw new Error('Invalid project path')
-  }
-
-  const segments = normalizedInput
-    .split('/')
-    .filter((segment) => segment && segment !== '.')
-
-  if (segments.some((segment) => segment === '..')) {
-    throw new Error('Project path cannot leave the app root')
-  }
-
-  const absolutePath = path.resolve(projectRoot, ...segments)
-  const relativeToRoot = path.relative(projectRoot, absolutePath)
-
-  if (relativeToRoot.startsWith('..') || path.isAbsolute(relativeToRoot)) {
-    throw new Error('Project path cannot leave the app root')
-  }
-
-  return {
-    absolutePath,
-    relativePath: segments.join('/'),
-  }
-}
-
-async function assertRealPathInsideProject(absolutePath: string) {
-  const [realProjectRoot, realTarget] = await Promise.all([
-    fs.realpath(projectRoot),
-    fs.realpath(absolutePath),
-  ])
-  const relativeToRoot = path.relative(realProjectRoot, realTarget)
-
-  if (relativeToRoot.startsWith('..') || path.isAbsolute(relativeToRoot)) {
-    throw new Error('Project path cannot leave the app root')
-  }
-}
-
-function validateEntryName(name: unknown) {
-  if (
-    typeof name !== 'string' ||
-    !name.trim() ||
-    name === '.' ||
-    name === '..' ||
-    /[\\/:*?"<>|]/.test(name)
-  ) {
-    throw new Error('Enter a valid file or folder name')
-  }
-
-  return name.trim()
-}
-
-async function readJsonBody(req: NodeJS.ReadableStream) {
-  let body = ''
-
-  for await (const chunk of req) {
-    body += String(chunk)
-
-    if (body.length > maxEditableFileBytes * 2) {
-      throw new Error('Request is too large')
-    }
-  }
-
-  return body ? (JSON.parse(body) as Record<string, unknown>) : {}
-}
-
-async function listProjectDirectory(relativePath: string) {
-  const projectPath = getProjectPath(relativePath)
-  const stats = await fs.lstat(projectPath.absolutePath)
-
-  if (!stats.isDirectory() || stats.isSymbolicLink()) {
-    throw new Error('The selected path is not a directory')
-  }
-
-  await assertRealPathInsideProject(projectPath.absolutePath)
-  const directoryEntries = await fs.readdir(projectPath.absolutePath, {
-    withFileTypes: true,
-  })
-  const entries: ProjectEntry[] = directoryEntries
-    .filter((entry) => !hiddenProjectEntries.has(entry.name))
-    .map((entry) => {
-      const entryPath = projectPath.relativePath
-        ? `${projectPath.relativePath}/${entry.name}`
-        : entry.name
-      const kind: ProjectEntryKind = entry.isSymbolicLink()
-        ? 'symlink'
-        : entry.isDirectory()
-          ? 'directory'
-          : 'file'
-
-      return { name: entry.name, path: entryPath, kind }
-    })
-    .sort((first, second) => {
-      if (first.kind === 'directory' && second.kind !== 'directory') return -1
-      if (first.kind !== 'directory' && second.kind === 'directory') return 1
-      return first.name.localeCompare(second.name, undefined, {
-        numeric: true,
-        sensitivity: 'base',
-      })
-    })
-
-  return {
-    rootName: path.basename(projectRoot),
-    path: projectPath.relativePath,
-    entries,
-  }
-}
-
-async function readProjectFile(relativePath: string) {
-  const projectPath = getProjectPath(relativePath)
-  const stats = await fs.lstat(projectPath.absolutePath)
-
-  if (!stats.isFile() || stats.isSymbolicLink()) {
-    throw new Error('The selected path is not an editable file')
-  }
-
-  await assertRealPathInsideProject(projectPath.absolutePath)
-
-  if (stats.size > maxEditableFileBytes) {
-    return {
-      path: projectPath.relativePath,
-      content: '',
-      size: stats.size,
-      isBinary: false,
-      isTooLarge: true,
-    }
-  }
-
-  const buffer = await fs.readFile(projectPath.absolutePath)
-  const isBinary = buffer.subarray(0, 8000).includes(0)
-
-  return {
-    path: projectPath.relativePath,
-    content: isBinary ? '' : buffer.toString('utf8'),
-    size: stats.size,
-    isBinary,
-    isTooLarge: false,
-  }
-}
-
-async function importPageFromSource(
-  relativePath: string,
-  name: string,
-  route: string
-) {
-  const projectPath = getProjectPath(relativePath)
-
-  if (
-    !projectPath.relativePath.startsWith('src/') ||
-    !/\.(jsx|tsx)$/i.test(projectPath.relativePath)
-  ) {
-    throw new Error('Pages must use a .jsx or .tsx file inside src')
-  }
-
-  const stats = await fs.lstat(projectPath.absolutePath)
-
-  if (!stats.isFile() || stats.isSymbolicLink()) {
-    throw new Error('Select a valid React source file')
-  }
-
-  await assertRealPathInsideProject(projectPath.absolutePath)
-  const source = await fs.readFile(projectPath.absolutePath, 'utf8')
-  const pageId = randomUUID()
-  const converted = parseReactPageSource(source, projectPath.relativePath)
-
-  return {
-    id: pageId,
-    name,
-    route,
-    sourcePath: projectPath.relativePath,
-    root: {
-      ...converted.root,
-      id: `${pageId}:root`,
-      label: 'Page root',
-      children: [],
-    },
-    components: converted.components,
-  }
-}
-
-function getErrorStatus(error: unknown) {
-  const code =
-    typeof error === 'object' && error !== null && 'code' in error
-      ? String(error.code)
-      : ''
-
-  if (code === 'ENOENT') return 404
-  if (code === 'EEXIST' || code === 'ENOTEMPTY') return 409
-  return 400
-}
-
-const generatorDiagnosticMarker = 'VISUALBUILD_DIAGNOSTIC:'
-
-function getProcessOutput(error: unknown, key: 'stdout' | 'stderr') {
-  if (
-    typeof error !== 'object' ||
-    error === null ||
-    !(key in error)
-  ) {
-    return ''
-  }
-
-  return String(error[key] ?? '')
-}
-
-function parseGeneratorDiagnostic(
-  error: unknown,
-  reason: string
-): GeneratorDiagnostic {
-  const stderr = getProcessOutput(error, 'stderr')
-  const diagnosticLine = stderr
-    .split(/\r?\n/)
-    .find((line) => line.startsWith(generatorDiagnosticMarker))
-
-  if (diagnosticLine) {
-    try {
-      const diagnostic = JSON.parse(
-        diagnosticLine.slice(generatorDiagnosticMarker.length)
-      ) as Partial<GeneratorDiagnostic>
-
-      if (
-        diagnostic.severity === 'error' &&
-        diagnostic.phase === 'generate' &&
-        typeof diagnostic.code === 'string' &&
-        typeof diagnostic.title === 'string' &&
-        typeof diagnostic.message === 'string' &&
-        typeof diagnostic.path === 'string'
-      ) {
-        return {
-          severity: diagnostic.severity,
-          phase: diagnostic.phase,
-          code: diagnostic.code,
-          title: diagnostic.title,
-          message: diagnostic.message,
-          path: diagnostic.path,
-          suggestion:
-            typeof diagnostic.suggestion === 'string'
-              ? diagnostic.suggestion
-              : undefined,
-        }
-      }
-    } catch {
-      // Fall through to a stable diagnostic if the child process output is malformed.
-    }
-  }
-
-  return {
-    severity: 'error',
-    phase: 'generate',
-    code: 'GENERATION_FAILED',
-    title: 'React source generation failed',
-    message:
-      error instanceof Error
-        ? error.message
-        : `Failed to generate project files after ${reason}.`,
-    path: 'visualbuild/pages.json',
-    suggestion:
-      'Review the project schema and try again. The last valid files were kept.',
-  }
-}
-
-function getGeneratorDiagnostic(error: unknown) {
-  if (
-    typeof error !== 'object' ||
-    error === null ||
-    !('diagnostic' in error)
-  ) {
-    return null
-  }
-
-  return error.diagnostic as GeneratorDiagnostic
-}
-
-function visualbuildDevApi(): Plugin {
-  const pagesPath = path.resolve(projectRoot, 'visualbuild/pages.json')
-  const runtimeClassesPath = path.resolve(
-    builderRoot,
-    '.visualbuild-runtime-classes.html'
-  )
-  const generatorPath = path.resolve(
-    builderPackageRoot,
-    'scripts/vb-generate.mjs'
-  )
-
-  return {
-    name: 'visualbuild-dev-api',
-    async configResolved() {
-      await fs.writeFile(
-        runtimeClassesPath,
-        await fs.readFile(runtimeClassesPath, 'utf8').catch(() => '')
-      )
-    },
-    configureServer(server) {
-      let suppressWatchUntil = 0
-      let suppressReloadUntil = 0
-      let generateTimer: ReturnType<typeof setTimeout> | null = null
-      let managedDeletionQueue = Promise.resolve()
-      const reverseSyncTimers = new Map<
-        string,
-        ReturnType<typeof setTimeout>
-      >()
-      const suppressedUnlinkPaths = new Map<string, number>()
-      const eventClients = new Set<ServerResponse>()
-      const hotChannel = server.ws as unknown as {
-        send: (payload: unknown, data?: unknown) => void
-      }
-      const sendHotPayload = hotChannel.send.bind(hotChannel)
-
-      hotChannel.send = (payload, data) => {
-        if (
-          Date.now() < suppressReloadUntil &&
-          typeof payload === 'object' &&
-          payload !== null &&
-          'type' in payload &&
-          payload.type === 'full-reload'
-        ) {
-          return
-        }
-
-        sendHotPayload(payload, data)
-      }
-
-      async function generateProjectFiles(reason: string) {
-        try {
-          const { stdout, stderr } = await execFileAsync(
-            process.execPath,
-            [generatorPath],
-            { cwd: projectRoot }
-          )
-
-          if (stdout.trim()) {
-            server.config.logger.info(stdout.trim())
-          }
-
-          if (stderr.trim()) {
-            server.config.logger.warn(stderr.trim())
-          }
-        } catch (error) {
-          const diagnostic = parseGeneratorDiagnostic(error, reason)
-          server.config.logger.error(
-            `[VisualBuild] ${diagnostic.title}: ${diagnostic.message}`
-          )
-          broadcastVisualBuildEvent({
-            type: 'generator-diagnostic',
-            ...diagnostic,
-          })
-
-          const generationError = new Error(diagnostic.message)
-          Object.assign(generationError, { diagnostic })
-          throw generationError
-        }
-      }
-
-      const pagesWatcher = watchFiles(pagesPath, {
-        ignoreInitial: true,
-        usePolling: process.platform === 'win32',
-        interval: 100,
-        awaitWriteFinish: {
-          stabilityThreshold: 120,
-          pollInterval: 25,
-        },
-      }).on('change', () => {
-        if (Date.now() < suppressWatchUntil) {
-          return
-        }
-
-        if (generateTimer) {
-          clearTimeout(generateTimer)
-        }
-
-        generateTimer = setTimeout(() => {
-          generateTimer = null
-          void generateProjectFiles('pages.json change').catch(() => {})
-        }, 80)
-      })
-
-      function broadcastVisualBuildEvent(event: VisualBuildEvent) {
-        const payload = `event: visualbuild\ndata: ${JSON.stringify(event)}\n\n`
-
-        for (const client of eventClients) {
-          client.write(payload)
-        }
-      }
-
-      function normalizeManagedPath(value: unknown) {
-        return typeof value === 'string'
-          ? value.replace(/\\/g, '/').replace(/^\.\/+/, '')
-          : ''
-      }
-
-      function findManagedPagesForPath(
-        schema: ManagedProjectSchema,
-        relativePath: string,
-        isDirectory: boolean
-      ) {
-        const normalizedTarget = normalizeManagedPath(relativePath)
-
-        return schema.pages.filter((page) => {
-          const sourcePath = normalizeManagedPath(page.sourcePath)
-
-          return (
-            sourcePath === normalizedTarget ||
-            (isDirectory && sourcePath.startsWith(`${normalizedTarget}/`))
-          )
-        })
-      }
-
-      function replaceManagedPathPrefix(
-        sourcePath: string,
-        previousPath: string,
-        targetPath: string
-      ) {
-        return `${targetPath}${sourcePath.slice(previousPath.length)}`
-      }
-
-      function validateManagedPagePaths(schema: ManagedProjectSchema) {
-        const seenSourcePaths = new Set<string>()
-
-        for (const page of schema.pages) {
-          const sourcePath = normalizeManagedPath(page.sourcePath)
-
-          if (
-            !sourcePath.startsWith('src/') ||
-            !/\.(jsx|tsx)$/i.test(sourcePath) ||
-            sourcePath.includes('/../') ||
-            sourcePath.endsWith('/..')
-          ) {
-            throw new Error(
-              `Managed page "${page.name}" must remain a .jsx or .tsx file inside src`
-            )
-          }
-
-          if (
-            sourcePath === 'src/App.tsx' ||
-            sourcePath === 'src/layouts/AppLayout.tsx'
-          ) {
-            throw new Error(`Managed page path is reserved: ${sourcePath}`)
-          }
-
-          if (seenSourcePaths.has(sourcePath)) {
-            throw new Error(`Duplicate managed page path: ${sourcePath}`)
-          }
-
-          seenSourcePaths.add(sourcePath)
-        }
-      }
-
-      function suppressManagedUnlink(relativePath: string) {
-        suppressedUnlinkPaths.set(
-          normalizeManagedPath(relativePath),
-          Date.now() + 2500
-        )
-      }
-
-      function consumeSuppressedUnlink(relativePath: string) {
-        const normalizedPath = normalizeManagedPath(relativePath)
-        const expiresAt = suppressedUnlinkPaths.get(normalizedPath)
-
-        if (!expiresAt) return false
-
-        suppressedUnlinkPaths.delete(normalizedPath)
-        return expiresAt >= Date.now()
-      }
-
-      async function persistManagedPageDeletion(
-        relativePath: string,
-        isDirectory: boolean,
-        deleteTarget?: () => Promise<void>
-      ) {
-        const schema = JSON.parse(
-          await fs.readFile(pagesPath, 'utf8')
-        ) as ManagedProjectSchema
-        const removedPages = findManagedPagesForPath(
-          schema,
-          relativePath,
-          isDirectory
-        )
-
-        if (removedPages.length === 0) {
-          if (deleteTarget) await deleteTarget()
-          return []
-        }
-
-        if (removedPages.length === schema.pages.length) {
-          throw new Error(
-            'A VisualBuild project must keep at least one registered page'
-          )
-        }
-
-        const removedPageIds = new Set(removedPages.map((page) => page.id))
-        const nextSchema: ManagedProjectSchema = {
-          ...schema,
-          pages: schema.pages.filter((page) => !removedPageIds.has(page.id)),
-        }
-
-        for (const page of removedPages) {
-          const sourcePath = normalizeManagedPath(page.sourcePath)
-
-          if (sourcePath) {
-            suppressManagedUnlink(sourcePath)
-            const pendingTimer = reverseSyncTimers.get(
-              path.resolve(projectRoot, sourcePath)
-            )
-
-            if (pendingTimer) {
-              clearTimeout(pendingTimer)
-              reverseSyncTimers.delete(path.resolve(projectRoot, sourcePath))
-            }
-          }
-        }
-
-        suppressWatchUntil = Date.now() + 1500
-        await fs.writeFile(
-          pagesPath,
-          `${JSON.stringify(nextSchema, null, 2)}\n`,
-          'utf8'
-        )
-
-        try {
-          if (deleteTarget) await deleteTarget()
-        } catch (error) {
-          suppressWatchUntil = Date.now() + 1500
-          await fs.writeFile(
-            pagesPath,
-            `${JSON.stringify(schema, null, 2)}\n`,
-            'utf8'
-          )
-          throw error
-        }
-
-        await generateProjectFiles('managed page deletion')
-        broadcastVisualBuildEvent({
-          type: 'managed-pages-deleted',
-          path: normalizeManagedPath(relativePath),
-          pageIds: removedPages.map((page) => page.id),
-          message:
-            removedPages.length === 1
-              ? `Deleted ${removedPages[0].name}`
-              : `Deleted ${removedPages.length} pages`,
-        })
-
-        return removedPages
-      }
-
-      async function persistManagedPageMove(
-        relativePath: string,
-        targetRelativePath: string,
-        isDirectory: boolean,
-        moveTarget: () => Promise<void>,
-        rollbackTarget: () => Promise<void>
-      ) {
-        const normalizedSource = normalizeManagedPath(relativePath)
-        const normalizedTarget = normalizeManagedPath(targetRelativePath)
-        const schema = JSON.parse(
-          await fs.readFile(pagesPath, 'utf8')
-        ) as ManagedProjectSchema
-        const affectedPages = findManagedPagesForPath(
-          schema,
-          normalizedSource,
-          isDirectory
-        )
-
-        if (affectedPages.length === 0) {
-          await moveTarget()
-          return []
-        }
-
-        const affectedPageIds = new Set(affectedPages.map((page) => page.id))
-        const pathChanges: ManagedPagePathChange[] = affectedPages.map(
-          (page) => {
-            const previousPath = normalizeManagedPath(page.sourcePath)
-
-            return {
-              pageId: page.id,
-              previousPath,
-              sourcePath: isDirectory
-                ? replaceManagedPathPrefix(
-                    previousPath,
-                    normalizedSource,
-                    normalizedTarget
-                  )
-                : normalizedTarget,
-            }
-          }
-        )
-        const nextPaths = new Map(
-          pathChanges.map((change) => [change.pageId, change.sourcePath])
-        )
-        const nextSchema: ManagedProjectSchema = {
-          ...schema,
-          pages: schema.pages.map((page) =>
-            affectedPageIds.has(page.id)
-              ? { ...page, sourcePath: nextPaths.get(page.id) }
-              : page
-          ),
-        }
-
-        validateManagedPagePaths(nextSchema)
-
-        for (const change of pathChanges) {
-          suppressManagedUnlink(change.previousPath)
-          const previousAbsolutePath = path.resolve(
-            projectRoot,
-            change.previousPath
-          )
-          const pendingTimer = reverseSyncTimers.get(previousAbsolutePath)
-
-          if (pendingTimer) {
-            clearTimeout(pendingTimer)
-            reverseSyncTimers.delete(previousAbsolutePath)
-          }
-        }
-
-        let targetMoved = false
-        let schemaUpdated = false
-
-        try {
-          await moveTarget()
-          targetMoved = true
-          suppressWatchUntil = Date.now() + 1500
-          await fs.writeFile(
-            pagesPath,
-            `${JSON.stringify(nextSchema, null, 2)}\n`,
-            'utf8'
-          )
-          schemaUpdated = true
-          await generateProjectFiles('managed page move')
-        } catch (error) {
-          suppressWatchUntil = Date.now() + 1500
-
-          if (schemaUpdated) {
-            await fs.writeFile(
-              pagesPath,
-              `${JSON.stringify(schema, null, 2)}\n`,
-              'utf8'
-            )
-          }
-
-          if (targetMoved) {
-            await rollbackTarget()
-          }
-
-          if (schemaUpdated) {
-            await generateProjectFiles('managed page move rollback').catch(
-              () => {}
-            )
-          }
-
-          throw error
-        }
-
-        broadcastVisualBuildEvent({
-          type: 'managed-pages-moved',
-          path: normalizedSource,
-          targetPath: normalizedTarget,
-          pages: pathChanges,
-          message:
-            pathChanges.length === 1
-              ? `Moved ${affectedPages[0].name}`
-              : `Moved ${pathChanges.length} managed pages`,
-        })
-
-        return pathChanges
-      }
-
-      function unregisterExternallyDeletedPage(relativePath: string) {
-        managedDeletionQueue = managedDeletionQueue
-          .then(async () => {
-            const schema = JSON.parse(
-              await fs.readFile(pagesPath, 'utf8')
-            ) as ManagedProjectSchema
-            const removedPages = findManagedPagesForPath(
-              schema,
-              relativePath,
-              false
-            )
-
-            if (removedPages.length === 0) return
-
-            if (removedPages.length === schema.pages.length) {
-              await generateProjectFiles('restore required page')
-              broadcastVisualBuildEvent({
-                type: 'reverse-sync-error',
-                path: relativePath,
-                pageId: removedPages[0].id,
-                message:
-                  'The only registered page cannot be deleted. VisualBuild restored its source file.',
-              })
-              return
-            }
-
-            await persistManagedPageDeletion(relativePath, false)
-          })
-          .catch((error) => {
-            const message =
-              error instanceof Error
-                ? error.message
-                : 'Could not unregister the deleted page.'
-            broadcastVisualBuildEvent({
-              type: 'reverse-sync-error',
-              path: relativePath,
-              message,
-            })
-            server.config.logger.warn(
-              `[VisualBuild] Page deletion sync skipped ${relativePath}: ${message}`
-            )
-          })
-      }
-
-      async function reverseSyncSourceFile(absolutePath: string) {
-        const relativePath = path
-          .relative(projectRoot, absolutePath)
-          .split(path.sep)
-          .join('/')
-
-        try {
-          const schema = JSON.parse(
-            await fs.readFile(pagesPath, 'utf8')
-          ) as ManagedProjectSchema
-          const pageIndex = schema.pages.findIndex(
-            (page) =>
-              normalizeManagedPath(page.sourcePath) === relativePath
-          )
-
-          if (pageIndex < 0) return
-
-          const page = schema.pages[pageIndex]
-          const source = await fs.readFile(absolutePath, 'utf8')
-          const imported = parseReactPageSource(source, relativePath)
-          const current: ImportedPageTree = {
-            root: page.root,
-            components: page.components,
-          }
-          const reconciled = reconcileImportedTree(imported, current)
-
-          if (visualTreesEqual(reconciled, current)) return
-
-          schema.pages[pageIndex] = {
-            ...page,
-            root: reconciled.root,
-            components: reconciled.components,
-          }
-          suppressWatchUntil = Date.now() + 1200
-          await fs.writeFile(
-            pagesPath,
-            `${JSON.stringify(schema, null, 2)}\n`,
-            'utf8'
-          )
-          broadcastVisualBuildEvent({
-            type: 'reverse-sync-success',
-            path: relativePath,
-            pageId: page.id,
-            message: `Updated ${page.name} from ${relativePath}`,
-          })
-          server.config.logger.info(
-            `[VisualBuild] Reverse synced ${relativePath}`
-          )
-        } catch (error) {
-          const message =
-            error instanceof Error
-              ? error.message
-              : 'Reverse sync could not parse the managed page.'
-          broadcastVisualBuildEvent({
-            type: 'reverse-sync-error',
-            path: relativePath,
-            message,
-          })
-          server.config.logger.warn(
-            `[VisualBuild] Reverse sync skipped ${relativePath}: ${message}`
-          )
-        }
-      }
-
-      function scheduleReverseSync(absolutePath: string) {
-        if (!/\.(jsx|tsx)$/i.test(absolutePath)) return
-
-        const previousTimer = reverseSyncTimers.get(absolutePath)
-        if (previousTimer) clearTimeout(previousTimer)
-
-        reverseSyncTimers.set(
-          absolutePath,
-          setTimeout(() => {
-            reverseSyncTimers.delete(absolutePath)
-            void reverseSyncSourceFile(absolutePath)
-          }, 100)
-        )
-      }
-
-      function handleProjectFileChange(
-        action: FileSystemEvent['action'],
-        absolutePath: string
-      ) {
-        const relativePath = path
-          .relative(projectRoot, absolutePath)
-          .split(path.sep)
-          .join('/')
-
-        if (
-          !relativePath ||
-          relativePath === '..' ||
-          relativePath.startsWith('../')
-        ) {
-          return
-        }
-
-        broadcastVisualBuildEvent({
-          type: 'filesystem-change',
-          path: relativePath,
-          action,
-        })
-
-        const relativeToSource = path.relative(generatedSourceRoot, absolutePath)
-        const isInsideSource =
-          relativeToSource &&
-          relativeToSource !== '..' &&
-          !relativeToSource.startsWith(`..${path.sep}`) &&
-          !path.isAbsolute(relativeToSource)
-
-        if (isInsideSource && (action === 'add' || action === 'change')) {
-          scheduleReverseSync(absolutePath)
-        }
-
-        if (
-          isInsideSource &&
-          action === 'unlink' &&
-          !consumeSuppressedUnlink(relativePath)
-        ) {
-          unregisterExternallyDeletedPage(relativePath)
-        }
-      }
-
-      const projectWatcher = watchFiles(projectRoot, {
-        ignoreInitial: true,
-        usePolling: process.platform === 'win32',
-        interval: 100,
-        ignored: (watchedPath) => {
-          const relativePath = path.relative(projectRoot, path.resolve(watchedPath))
-          const segments = relativePath.split(path.sep)
-
-          return segments.some((segment) =>
-            ['.git', 'node_modules', 'dist', '.visualbuild-qa'].includes(segment)
-          )
-        },
-        awaitWriteFinish: {
-          stabilityThreshold: 140,
-          pollInterval: 25,
-        },
-      })
-        .on('add', (changedPath) => handleProjectFileChange('add', changedPath))
-        .on('change', (changedPath) =>
-          handleProjectFileChange('change', changedPath)
-        )
-        .on('unlink', (changedPath) =>
-          handleProjectFileChange('unlink', changedPath)
-        )
-        .on('addDir', (changedPath) =>
-          handleProjectFileChange('addDir', changedPath)
-        )
-        .on('unlinkDir', (changedPath) =>
-          handleProjectFileChange('unlinkDir', changedPath)
-        )
-        .on('ready', () => {
-          server.config.logger.info(
-            `[VisualBuild] Watching ${projectRoot} for project and managed source changes`
-          )
-        })
-        .on('error', (error) => {
-          server.config.logger.warn(
-            `[VisualBuild] Source watcher error: ${error.message}`
-          )
-        })
-
-      const keepAliveTimer = setInterval(() => {
-        for (const client of eventClients) {
-          client.write(': keep-alive\n\n')
-        }
-      }, 15000)
-
-      server.httpServer?.once('close', () => {
-        void pagesWatcher.close()
-        void projectWatcher.close()
-        clearInterval(keepAliveTimer)
-
-        for (const client of eventClients) {
-          client.end()
-        }
-
-        for (const timer of reverseSyncTimers.values()) {
-          clearTimeout(timer)
-        }
-
-        if (generateTimer) {
-          clearTimeout(generateTimer)
-        }
-      })
-
-      void generateProjectFiles('dev server start').catch(() => {})
-
-      server.middlewares.use('/__visualbuild/events', (req, res) => {
-        if (req.method !== 'GET') {
-          res.statusCode = 405
-          res.end()
-          return
-        }
-
-        res.statusCode = 200
-        res.setHeader('Content-Type', 'text/event-stream')
-        res.setHeader('Cache-Control', 'no-cache, no-transform')
-        res.setHeader('Connection', 'keep-alive')
-        res.write('retry: 1500\n\n')
-        eventClients.add(res)
-
-        req.once('close', () => {
-          eventClients.delete(res)
-        })
-      })
-
-      server.middlewares.use('/__visualbuild/files', async (req, res) => {
-        const requestUrl = new URL(req.url ?? '/', 'http://visualbuild.local')
-
-        try {
-          if (req.method === 'GET') {
-            const result = await listProjectDirectory(
-              requestUrl.searchParams.get('path') ?? ''
-            )
-            sendJson(res, 200, result)
-            return
-          }
-
-          if (req.method === 'POST') {
-            const payload = await readJsonBody(req)
-            const parentPath = getProjectPath(
-              typeof payload.parentPath === 'string' ? payload.parentPath : ''
-            )
-            const parentStats = await fs.lstat(parentPath.absolutePath)
-
-            if (!parentStats.isDirectory() || parentStats.isSymbolicLink()) {
-              throw new Error('Select a valid parent folder')
-            }
-
-            await assertRealPathInsideProject(parentPath.absolutePath)
-            const name = validateEntryName(payload.name)
-            const targetPath = getProjectPath(
-              parentPath.relativePath
-                ? `${parentPath.relativePath}/${name}`
-                : name
-            )
-
-            if (payload.kind === 'directory') {
-              await fs.mkdir(targetPath.absolutePath)
-            } else if (payload.kind === 'file') {
-              await fs.writeFile(targetPath.absolutePath, '', {
-                encoding: 'utf8',
-                flag: 'wx',
-              })
-            } else {
-              throw new Error('Entry type must be file or directory')
-            }
-
-            sendJson(res, 201, {
-              name,
-              path: targetPath.relativePath,
-              kind: payload.kind,
-            })
-            return
-          }
-
-          if (req.method === 'PATCH') {
-            const payload = await readJsonBody(req)
-            const sourcePath = getProjectPath(
-              typeof payload.path === 'string' ? payload.path : ''
-            )
-
-            if (!sourcePath.relativePath) {
-              throw new Error('The project root cannot be renamed')
-            }
-
-            const sourceStats = await fs.lstat(sourcePath.absolutePath)
-
-            if (!sourceStats.isSymbolicLink()) {
-              await assertRealPathInsideProject(sourcePath.absolutePath)
-            }
-
-            const name = validateEntryName(payload.name)
-            const currentParentPath = path.posix.dirname(
-              sourcePath.relativePath
-            )
-            const requestedParentPath =
-              typeof payload.parentPath === 'string'
-                ? getProjectPath(payload.parentPath)
-                : getProjectPath(
-                    currentParentPath === '.' ? '' : currentParentPath
-                  )
-            const parentStats = await fs.lstat(
-              requestedParentPath.absolutePath
-            )
-
-            if (
-              !parentStats.isDirectory() ||
-              parentStats.isSymbolicLink()
-            ) {
-              throw new Error('Select a valid destination folder')
-            }
-
-            await assertRealPathInsideProject(
-              requestedParentPath.absolutePath
-            )
-            const targetPath = getProjectPath(
-              requestedParentPath.relativePath
-                ? `${requestedParentPath.relativePath}/${name}`
-                : name
-            )
-
-            if (targetPath.relativePath === sourcePath.relativePath) {
-              sendJson(res, 200, {
-                name,
-                path: targetPath.relativePath,
-                kind: sourceStats.isSymbolicLink()
-                  ? 'symlink'
-                  : sourceStats.isDirectory()
-                    ? 'directory'
-                    : 'file',
-                managedPages: [],
-              })
-              return
-            }
-
-            if (
-              sourceStats.isDirectory() &&
-              targetPath.relativePath.startsWith(
-                `${sourcePath.relativePath}/`
-              )
-            ) {
-              throw new Error('A folder cannot be moved inside itself')
-            }
-
-            const targetExists = await fs
-              .lstat(targetPath.absolutePath)
-              .then(() => true)
-              .catch((error: NodeJS.ErrnoException) => {
-                if (error.code === 'ENOENT') return false
-                throw error
-              })
-
-            if (targetExists) {
-              throw new Error('A file or folder with that name already exists')
-            }
-
-            const managedPages = await persistManagedPageMove(
-              sourcePath.relativePath,
-              targetPath.relativePath,
-              sourceStats.isDirectory() && !sourceStats.isSymbolicLink(),
-              () =>
-                fs.rename(sourcePath.absolutePath, targetPath.absolutePath),
-              () =>
-                fs.rename(targetPath.absolutePath, sourcePath.absolutePath)
-            )
-            sendJson(res, 200, {
-              name,
-              path: targetPath.relativePath,
-              kind: sourceStats.isSymbolicLink()
-                ? 'symlink'
-                : sourceStats.isDirectory()
-                  ? 'directory'
-                  : 'file',
-              managedPages,
-            })
-            return
-          }
-
-          if (req.method === 'DELETE') {
-            const targetPath = getProjectPath(
-              requestUrl.searchParams.get('path') ?? ''
-            )
-
-            if (!targetPath.relativePath) {
-              throw new Error('The project root cannot be deleted')
-            }
-
-            const targetStats = await fs.lstat(targetPath.absolutePath)
-
-            if (!targetStats.isSymbolicLink()) {
-              await assertRealPathInsideProject(targetPath.absolutePath)
-            }
-
-            const deleteTarget = () =>
-              fs.rm(targetPath.absolutePath, {
-                recursive: targetStats.isDirectory(),
-              })
-            const removedPages = await persistManagedPageDeletion(
-              targetPath.relativePath,
-              targetStats.isDirectory(),
-              deleteTarget
-            )
-
-            sendJson(res, 200, {
-              path: targetPath.relativePath,
-              removedPageIds: removedPages.map((page) => page.id),
-            })
-            return
-          }
-
-          res.statusCode = 405
-          res.end()
-        } catch (error) {
-          sendJson(res, getErrorStatus(error), {
-            error:
-              error instanceof Error
-                ? error.message
-                : 'Project file operation failed',
-          })
-        }
-      })
-
-      server.middlewares.use('/__visualbuild/file', async (req, res) => {
-        const requestUrl = new URL(req.url ?? '/', 'http://visualbuild.local')
-
-        try {
-          if (req.method === 'GET') {
-            sendJson(
-              res,
-              200,
-              await readProjectFile(requestUrl.searchParams.get('path') ?? '')
-            )
-            return
-          }
-
-          if (req.method === 'PUT') {
-            const payload = await readJsonBody(req)
-            const targetPath = getProjectPath(
-              typeof payload.path === 'string' ? payload.path : ''
-            )
-            const stats = await fs.lstat(targetPath.absolutePath)
-
-            if (!stats.isFile() || stats.isSymbolicLink()) {
-              throw new Error('The selected path is not an editable file')
-            }
-
-            await assertRealPathInsideProject(targetPath.absolutePath)
-
-            if (typeof payload.content !== 'string') {
-              throw new Error('File content must be text')
-            }
-
-            if (Buffer.byteLength(payload.content, 'utf8') > maxEditableFileBytes) {
-              throw new Error('File content exceeds the 2 MB editor limit')
-            }
-
-            await fs.writeFile(targetPath.absolutePath, payload.content, 'utf8')
-            res.statusCode = 204
-            res.end()
-            return
-          }
-
-          res.statusCode = 405
-          res.end()
-        } catch (error) {
-          sendJson(res, getErrorStatus(error), {
-            error:
-              error instanceof Error
-                ? error.message
-                : 'Project file operation failed',
-          })
-        }
-      })
-
-      server.middlewares.use('/__visualbuild/import-page', async (req, res) => {
-        try {
-          if (req.method !== 'POST') {
-            res.statusCode = 405
-            res.end()
-            return
-          }
-
-          const payload = await readJsonBody(req)
-          const name =
-            typeof payload.name === 'string' ? payload.name.trim() : ''
-          const route =
-            typeof payload.route === 'string' ? payload.route.trim() : ''
-          const sourcePath =
-            typeof payload.path === 'string' ? payload.path : ''
-
-          if (!name) {
-            throw new Error('Page name is required')
-          }
-
-          if (!route.startsWith('/')) {
-            throw new Error('Page route must start with "/"')
-          }
-
-          sendJson(
-            res,
-            201,
-            await importPageFromSource(sourcePath, name, route)
-          )
-        } catch (error) {
-          sendJson(res, getErrorStatus(error), {
-            error:
-              error instanceof Error
-                ? error.message
-                : 'Failed to import page source',
-          })
-        }
-      })
-
-      server.middlewares.use('/__visualbuild/tailwind', (req, res) => {
-        if (req.method !== 'POST') {
-          res.statusCode = 405
-          res.end()
-          return
-        }
-
-        let body = ''
-
-        req.on('data', (chunk) => {
-          body += chunk
-        })
-
-        req.on('end', async () => {
-          try {
-            const current = await fs
-              .readFile(runtimeClassesPath, 'utf8')
-              .catch(() => '')
-
-            if (current !== body) {
-              suppressReloadUntil = Date.now() + 1500
-              await fs.writeFile(runtimeClassesPath, body)
-            }
-
-            res.statusCode = 204
-            res.end()
-          } catch (error) {
-            res.statusCode = 500
-            res.end(
-              error instanceof Error
-                ? error.message
-                : 'Failed to update Tailwind classes'
-            )
-          }
-        })
-      })
-
-      server.middlewares.use('/__visualbuild/pages', async (req, res) => {
-        if (req.method === 'GET') {
-          try {
-            const json = await fs.readFile(pagesPath, 'utf8')
-            res.setHeader('Content-Type', 'application/json')
-            res.setHeader(
-              'X-VisualBuild-Project-Id',
-              encodeURIComponent(projectRoot)
-            )
-            res.end(json)
-          } catch (error) {
-            res.statusCode = 500
-            res.end(
-              error instanceof Error
-                ? error.message
-                : 'Failed to read pages.json'
-            )
-          }
-          return
-        }
-
-        if (req.method === 'POST') {
-          let body = ''
-
-          req.on('data', (chunk) => {
-            body += chunk
-          })
-
-          req.on('end', async () => {
-            let previousSchema = ''
-            let wroteSchema = false
-
-            try {
-              await fs.mkdir(path.dirname(pagesPath), { recursive: true })
-              previousSchema = await fs
-                .readFile(pagesPath, 'utf8')
-                .catch(() => '')
-
-              if (previousSchema !== body) {
-                suppressWatchUntil = Date.now() + 1000
-                suppressReloadUntil = Date.now() + 5000
-                await fs.writeFile(pagesPath, body)
-                wroteSchema = true
-                await generateProjectFiles('pages.json write')
-                suppressReloadUntil = Date.now() + 1000
-              }
-
-              res.statusCode = 204
-              res.end()
-            } catch (error) {
-              if (wroteSchema) {
-                suppressWatchUntil = Date.now() + 1000
-
-                if (previousSchema) {
-                  await fs.writeFile(pagesPath, previousSchema)
-                  await generateProjectFiles('pages.json rollback').catch(
-                    (rollbackError) => {
-                      server.config.logger.error(
-                        `[VisualBuild] Failed to restore generated files: ${
-                          rollbackError instanceof Error
-                            ? rollbackError.message
-                            : String(rollbackError)
-                        }`
-                      )
-                    }
-                  )
-                } else {
-                  await fs.rm(pagesPath, { force: true })
-                }
-              }
-
-              const diagnostic = getGeneratorDiagnostic(error)
-              sendJson(res, 500, {
-                error:
-                  diagnostic?.message ??
-                  (error instanceof Error
-                    ? error.message
-                    : 'Failed to write pages.json'),
-                diagnostic,
-              })
-            }
-          })
-
-          return
-        }
-
-        res.statusCode = 405
-        res.end()
-      })
-    },
-  }
-}
-
-export default defineConfig({
-  root: builderRoot,
-  define: {
-    'process.env.BABEL_TYPES_8_BREAKING': 'false',
-  },
-  plugins: [react(), tailwindcss(), visualbuildDevApi()],
-  server: {
-    watch: {
-      ignored: ['**/node_modules/**', isGeneratedProjectPath],
-    },
-  },
-})
+import { execFile } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import fs from 'node:fs/promises'
+import type { ServerResponse } from 'node:http'
+import path from 'node:path'
+import { promisify } from 'node:util'
+import { parse } from '@babel/parser'
+import { watch as watchFiles } from 'chokidar'
+import { defineConfig } from 'vite'
+import type { Plugin } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+import { loadVisualBuildConfig } from './shared/visualbuildConfig.mjs'
+import { createReactComponentSource } from './shared/createReactComponentSource.mjs'
+import { resolveNpmBuildCommand } from './shared/npmBuildCommand.mjs'
+import {
+  deployStaticOutputToVercel,
+  validateVercelProjectName,
+  validateVercelTeamId,
+} from './shared/vercelDeployment.mjs'
+import {
+  parseReactComponentPreview,
+  parseReactPageSource,
+  reconcileImportedTree,
+  visualTreesEqual,
+  type ImportedPageTree,
+  type ImportedVisualNode,
+} from './server/parseReactPage'
+
+const execFileAsync = promisify(execFile)
+const builderPackageRoot = process.cwd()
+const projectRoot = path.resolve(
+  process.env.VISUALBUILD_APP_DIR || builderPackageRoot
+)
+const builderRoot = path.resolve(builderPackageRoot, 'visual-app-builder')
+const startupProjectConfig = await loadVisualBuildConfig(projectRoot)
+const resolveConfiguredPath = (relativePath: string) =>
+  path.resolve(projectRoot, ...relativePath.split('/'))
+const generatedSourceRoot = resolveConfiguredPath(
+  startupProjectConfig.paths.sourceDir
+)
+const configuredProjectRoots = [
+  generatedSourceRoot,
+  ...[
+    startupProjectConfig.paths.schemaFile,
+    startupProjectConfig.paths.componentRegistryFile,
+    startupProjectConfig.paths.generatedManifestFile,
+  ].map((filePath) => path.dirname(resolveConfiguredPath(filePath))),
+]
+const maxEditableFileBytes = 2 * 1024 * 1024
+const hiddenProjectEntries = new Set(['.git', 'node_modules'])
+
+function isPathInsideDirectory(filePath: string, directoryPath: string) {
+  return (
+    filePath === directoryPath ||
+    filePath.startsWith(`${directoryPath.replace(/\/+$/, '')}/`)
+  )
+}
+
+type ProjectEntryKind = 'file' | 'directory' | 'symlink'
+
+interface ProjectEntry {
+  name: string
+  path: string
+  kind: ProjectEntryKind
+}
+
+interface ManagedPage {
+  id: string
+  name: string
+  route: string
+  sourcePath?: string
+  root: ImportedVisualNode
+  components: ImportedVisualNode[]
+}
+
+interface ManagedProjectSchema {
+  pages: ManagedPage[]
+  [key: string]: unknown
+}
+
+interface ReverseSyncEvent {
+  type: 'reverse-sync-success' | 'reverse-sync-error'
+  path: string
+  pageId?: string
+  message: string
+}
+
+interface GeneratorDiagnostic {
+  severity: 'error'
+  phase: 'generate'
+  code: string
+  title: string
+  message: string
+  path: string
+  suggestion?: string
+}
+
+interface GeneratorDiagnosticEvent extends GeneratorDiagnostic {
+  type: 'generator-diagnostic'
+}
+
+interface FileSystemEvent {
+  type: 'filesystem-change'
+  path: string
+  action: 'add' | 'change' | 'unlink' | 'addDir' | 'unlinkDir'
+}
+
+interface ManagedPagesDeletedEvent {
+  type: 'managed-pages-deleted'
+  path: string
+  pageIds: string[]
+  message: string
+}
+
+interface ManagedPagePathChange {
+  pageId: string
+  previousPath: string
+  sourcePath: string
+}
+
+interface ManagedPagesMovedEvent {
+  type: 'managed-pages-moved'
+  path: string
+  targetPath: string
+  pages: ManagedPagePathChange[]
+  message: string
+}
+
+type VisualBuildEvent =
+  | ReverseSyncEvent
+  | GeneratorDiagnosticEvent
+  | FileSystemEvent
+  | ManagedPagesDeletedEvent
+  | ManagedPagesMovedEvent
+
+function isGeneratedProjectPath(watchedPath: string) {
+  const absolutePath = path.resolve(watchedPath)
+
+  return configuredProjectRoots.some(
+    (rootPath) =>
+      absolutePath === rootPath || absolutePath.startsWith(`${rootPath}${path.sep}`)
+  )
+}
+
+function sendJson(
+  res: { statusCode: number; setHeader: (name: string, value: string) => void; end: (body?: string) => void },
+  statusCode: number,
+  payload: unknown
+) {
+  res.statusCode = statusCode
+  res.setHeader('Content-Type', 'application/json')
+  res.end(JSON.stringify(payload))
+}
+
+function getProjectPath(relativePath = '') {
+  const normalizedInput = relativePath.replace(/\\/g, '/').trim()
+
+  if (
+    normalizedInput.startsWith('/') ||
+    /^[a-zA-Z]:/.test(normalizedInput) ||
+    normalizedInput.includes('\0')
+  ) {
+    throw new Error('Invalid project path')
+  }
+
+  const segments = normalizedInput
+    .split('/')
+    .filter((segment) => segment && segment !== '.')
+
+  if (segments.some((segment) => segment === '..')) {
+    throw new Error('Project path cannot leave the app root')
+  }
+
+  const absolutePath = path.resolve(projectRoot, ...segments)
+  const relativeToRoot = path.relative(projectRoot, absolutePath)
+
+  if (relativeToRoot.startsWith('..') || path.isAbsolute(relativeToRoot)) {
+    throw new Error('Project path cannot leave the app root')
+  }
+
+  return {
+    absolutePath,
+    relativePath: segments.join('/'),
+  }
+}
+
+async function assertRealPathInsideProject(absolutePath: string) {
+  const [realProjectRoot, realTarget] = await Promise.all([
+    fs.realpath(projectRoot),
+    fs.realpath(absolutePath),
+  ])
+  const relativeToRoot = path.relative(realProjectRoot, realTarget)
+
+  if (relativeToRoot.startsWith('..') || path.isAbsolute(relativeToRoot)) {
+    throw new Error('Project path cannot leave the app root')
+  }
+}
+
+function validateEntryName(name: unknown) {
+  if (
+    typeof name !== 'string' ||
+    !name.trim() ||
+    name === '.' ||
+    name === '..' ||
+    /[\\/:*?"<>|]/.test(name)
+  ) {
+    throw new Error('Enter a valid file or folder name')
+  }
+
+  return name.trim()
+}
+
+async function readJsonBody(req: NodeJS.ReadableStream) {
+  let body = ''
+
+  for await (const chunk of req) {
+    body += String(chunk)
+
+    if (body.length > maxEditableFileBytes * 2) {
+      throw new Error('Request is too large')
+    }
+  }
+
+  return body ? (JSON.parse(body) as Record<string, unknown>) : {}
+}
+
+async function listProjectDirectory(relativePath: string) {
+  const projectPath = getProjectPath(relativePath)
+  const stats = await fs.lstat(projectPath.absolutePath)
+
+  if (!stats.isDirectory() || stats.isSymbolicLink()) {
+    throw new Error('The selected path is not a directory')
+  }
+
+  await assertRealPathInsideProject(projectPath.absolutePath)
+  const directoryEntries = await fs.readdir(projectPath.absolutePath, {
+    withFileTypes: true,
+  })
+  const entries: ProjectEntry[] = directoryEntries
+    .filter((entry) => !hiddenProjectEntries.has(entry.name))
+    .map((entry) => {
+      const entryPath = projectPath.relativePath
+        ? `${projectPath.relativePath}/${entry.name}`
+        : entry.name
+      const kind: ProjectEntryKind = entry.isSymbolicLink()
+        ? 'symlink'
+        : entry.isDirectory()
+          ? 'directory'
+          : 'file'
+
+      return { name: entry.name, path: entryPath, kind }
+    })
+    .sort((first, second) => {
+      if (first.kind === 'directory' && second.kind !== 'directory') return -1
+      if (first.kind !== 'directory' && second.kind === 'directory') return 1
+      return first.name.localeCompare(second.name, undefined, {
+        numeric: true,
+        sensitivity: 'base',
+      })
+    })
+
+  return {
+    rootName: path.basename(projectRoot),
+    path: projectPath.relativePath,
+    entries,
+  }
+}
+
+async function readProjectFile(relativePath: string) {
+  const projectPath = getProjectPath(relativePath)
+  const stats = await fs.lstat(projectPath.absolutePath)
+
+  if (!stats.isFile() || stats.isSymbolicLink()) {
+    throw new Error('The selected path is not an editable file')
+  }
+
+  await assertRealPathInsideProject(projectPath.absolutePath)
+
+  if (stats.size > maxEditableFileBytes) {
+    return {
+      path: projectPath.relativePath,
+      content: '',
+      size: stats.size,
+      isBinary: false,
+      isTooLarge: true,
+    }
+  }
+
+  const buffer = await fs.readFile(projectPath.absolutePath)
+  const isBinary = buffer.subarray(0, 8000).includes(0)
+
+  return {
+    path: projectPath.relativePath,
+    content: isBinary ? '' : buffer.toString('utf8'),
+    size: stats.size,
+    isBinary,
+    isTooLarge: false,
+  }
+}
+
+async function importPageFromSource(
+  relativePath: string,
+  name: string,
+  route: string
+) {
+  const projectPath = getProjectPath(relativePath)
+  const config = await loadVisualBuildConfig(projectRoot)
+
+  if (
+    !isPathInsideDirectory(
+      projectPath.relativePath,
+      config.paths.sourceDir
+    ) ||
+    !/\.(jsx|tsx)$/i.test(projectPath.relativePath)
+  ) {
+    throw new Error(
+      `Pages must use a .jsx or .tsx file inside ${config.paths.sourceDir}`
+    )
+  }
+
+  const stats = await fs.lstat(projectPath.absolutePath)
+
+  if (!stats.isFile() || stats.isSymbolicLink()) {
+    throw new Error('Select a valid React source file')
+  }
+
+  await assertRealPathInsideProject(projectPath.absolutePath)
+  const source = await fs.readFile(projectPath.absolutePath, 'utf8')
+  const pageId = randomUUID()
+  const converted = parseReactPageSource(
+    source,
+    projectPath.relativePath,
+    (config.components ?? []).map((component) => component.name)
+  )
+
+  return {
+    id: pageId,
+    name,
+    route,
+    sourcePath: projectPath.relativePath,
+    root: {
+      ...converted.root,
+      id: `${pageId}:root`,
+      label: 'Page root',
+      children: [],
+    },
+    components: converted.components,
+  }
+}
+
+async function registerComponentFromSource(relativePath: string) {
+  const projectPath = getProjectPath(relativePath)
+  const currentConfig = await loadVisualBuildConfig(projectRoot)
+
+  if (
+    !isPathInsideDirectory(
+      projectPath.relativePath,
+      currentConfig.paths.sourceDir
+    ) ||
+    !/\.(jsx|tsx)$/i.test(projectPath.relativePath)
+  ) {
+    throw new Error(
+      `Components must use a .jsx or .tsx file inside ${currentConfig.paths.sourceDir}`
+    )
+  }
+
+  const stats = await fs.lstat(projectPath.absolutePath)
+  if (!stats.isFile() || stats.isSymbolicLink()) {
+    throw new Error('Select a valid React component source file')
+  }
+
+  await assertRealPathInsideProject(projectPath.absolutePath)
+  const source = await fs.readFile(projectPath.absolutePath, 'utf8')
+  const exportInfo = findReactComponentExport(
+    source,
+    projectPath.relativePath
+  )
+  const registrationsPath = resolveConfiguredPath(
+    currentConfig.paths.componentRegistryFile
+  )
+  const registrations = await fs
+    .readFile(registrationsPath, 'utf8')
+    .then((contents) => JSON.parse(contents) as { components?: unknown[] })
+    .catch((error: NodeJS.ErrnoException) => {
+      if (error.code === 'ENOENT') return { components: [] }
+      throw error
+    })
+  if (
+    (currentConfig.components ?? []).some(
+      (component) => component.name === exportInfo.name
+    )
+  ) {
+    throw new Error(`Component "${exportInfo.name}" is already registered`)
+  }
+
+  const registration = {
+    name: exportInfo.name,
+    importPath: projectPath.relativePath,
+    exportName: exportInfo.exportName,
+    label: splitComponentName(exportInfo.name),
+    category: 'Custom',
+    icon: exportInfo.name.charAt(0),
+    description: `Local ${exportInfo.name} component`,
+    acceptsChildren: true,
+    props: {
+      wrapperTag: {
+        type: 'select',
+        label: 'Component root tag',
+        default: 'div',
+        options: [
+          'div',
+          'main',
+          'section',
+          'article',
+          'header',
+          'footer',
+          'nav',
+          'aside',
+          'form',
+        ],
+      },
+      id: {
+        type: 'string',
+        label: 'ID',
+        default: '',
+      },
+      className: {
+        type: 'text',
+        label: 'Tailwind classes',
+        default: '',
+      },
+      attributes: {
+        type: 'attributes',
+        label: 'Additional attributes',
+        default: {},
+      },
+    },
+  }
+  const nextRegistrations = {
+    components: [...(registrations.components ?? []), registration],
+  }
+
+  await fs.mkdir(path.dirname(registrationsPath), { recursive: true })
+  await fs.writeFile(
+    registrationsPath,
+    `${JSON.stringify(nextRegistrations, null, 2)}\n`,
+    'utf8'
+  )
+  const preview = createComponentPreview(
+    source,
+    projectPath.relativePath,
+    [
+      ...(currentConfig.components ?? []).map(
+        (component) => component.name
+      ),
+      exportInfo.name,
+    ]
+  )
+  const previewDefaults = getPreviewRootDefaults(preview)
+  return {
+    ...registration,
+    defaultProps: {
+      wrapperTag: previewDefaults.wrapperTag ?? 'div',
+      id: previewDefaults.id ?? '',
+      className: previewDefaults.className ?? '',
+      attributes: previewDefaults.attributes ?? {},
+    },
+    propSchema: registration.props,
+    acceptsChildren: preview?.rendersChildren ?? true,
+    ...(preview ? { preview } : {}),
+  }
+}
+
+function createComponentPreview(
+  source: string,
+  sourcePath: string,
+  customComponentNames: Iterable<string>
+) {
+  try {
+    return parseReactComponentPreview(
+      source,
+      sourcePath,
+      customComponentNames
+    )
+  } catch {
+    return undefined
+  }
+}
+
+function getPreviewRootDefaults(
+  preview: ReturnType<typeof createComponentPreview>
+) {
+  if (!preview) return {}
+
+  return {
+    wrapperTag: preview.rootTag,
+    id: preview.rootProps.id ?? '',
+    className: preview.rootProps.className ?? '',
+    attributes: Object.fromEntries(
+      Object.entries(preview.rootProps).filter(
+        ([name]) => !['id', 'className', 'text'].includes(name)
+      )
+    ),
+  }
+}
+
+async function addComponentPreviews(
+  components: Awaited<
+    ReturnType<typeof loadVisualBuildConfig>
+  >['components']
+) {
+  const componentNames = components.map((component) => component.name)
+
+  return Promise.all(
+    components.map(async (component) => {
+      const source = await fs
+        .readFile(getProjectPath(component.importPath).absolutePath, 'utf8')
+        .catch(() => null)
+      const preview = source
+        ? createComponentPreview(
+            source,
+            component.importPath,
+            componentNames
+          )
+        : undefined
+      const previewDefaults = getPreviewRootDefaults(preview)
+
+      return {
+        ...component,
+        defaultProps: {
+          ...component.defaultProps,
+          ...previewDefaults,
+        },
+        acceptsChildren:
+          preview?.rendersChildren ?? component.acceptsChildren,
+        ...(preview ? { preview } : {}),
+      }
+    })
+  )
+}
+
+function findReactComponentExport(source: string, sourcePath: string) {
+  const ast = parse(source, {
+    sourceType: 'module',
+    plugins: ['jsx', 'typescript'],
+  })
+  const fallbackName = toPascalComponentName(
+    path.posix.basename(sourcePath).replace(/\.[^.]+$/, '')
+  )
+
+  for (const statement of ast.program.body) {
+    if (statement.type === 'ExportDefaultDeclaration') {
+      return {
+        name:
+          'id' in statement.declaration && statement.declaration.id?.name
+            ? statement.declaration.id.name
+            : fallbackName,
+        exportName: 'default',
+      }
+    }
+  }
+
+  for (const statement of ast.program.body) {
+    if (
+      statement.type === 'ExportNamedDeclaration' &&
+      statement.declaration &&
+      'id' in statement.declaration &&
+      statement.declaration.id?.type === 'Identifier'
+    ) {
+      return {
+        name: statement.declaration.id.name,
+        exportName: statement.declaration.id.name,
+      }
+    }
+  }
+
+  throw new Error(
+    'The selected file must export a React component as default or as a named function/class'
+  )
+}
+
+function toPascalComponentName(value: string) {
+  const name = value
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+  return /^[A-Z]/.test(name) ? name : `Component${name}`
+}
+
+function splitComponentName(value: string) {
+  return value.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+}
+
+function getErrorStatus(error: unknown) {
+  const code =
+    typeof error === 'object' && error !== null && 'code' in error
+      ? String(error.code)
+      : ''
+
+  if (code === 'ENOENT') return 404
+  if (code === 'EEXIST' || code === 'ENOTEMPTY') return 409
+  return 400
+}
+
+const generatorDiagnosticMarker = 'VISUALBUILD_DIAGNOSTIC:'
+
+function getProcessOutput(error: unknown, key: 'stdout' | 'stderr') {
+  if (
+    typeof error !== 'object' ||
+    error === null ||
+    !(key in error)
+  ) {
+    return ''
+  }
+
+  return String(error[key] ?? '')
+}
+
+function parseGeneratorDiagnostic(
+  error: unknown,
+  reason: string
+): GeneratorDiagnostic {
+  const stderr = getProcessOutput(error, 'stderr')
+  const diagnosticLine = stderr
+    .split(/\r?\n/)
+    .find((line) => line.startsWith(generatorDiagnosticMarker))
+
+  if (diagnosticLine) {
+    try {
+      const diagnostic = JSON.parse(
+        diagnosticLine.slice(generatorDiagnosticMarker.length)
+      ) as Partial<GeneratorDiagnostic>
+
+      if (
+        diagnostic.severity === 'error' &&
+        diagnostic.phase === 'generate' &&
+        typeof diagnostic.code === 'string' &&
+        typeof diagnostic.title === 'string' &&
+        typeof diagnostic.message === 'string' &&
+        typeof diagnostic.path === 'string'
+      ) {
+        return {
+          severity: diagnostic.severity,
+          phase: diagnostic.phase,
+          code: diagnostic.code,
+          title: diagnostic.title,
+          message: diagnostic.message,
+          path: diagnostic.path,
+          suggestion:
+            typeof diagnostic.suggestion === 'string'
+              ? diagnostic.suggestion
+              : undefined,
+        }
+      }
+    } catch {
+      // Fall through to a stable diagnostic if the child process output is malformed.
+    }
+  }
+
+  return {
+    severity: 'error',
+    phase: 'generate',
+    code: 'GENERATION_FAILED',
+    title: 'React source generation failed',
+    message:
+      error instanceof Error
+        ? error.message
+        : `Failed to generate project files after ${reason}.`,
+    path: startupProjectConfig.paths.schemaFile,
+    suggestion:
+      'Review the project schema and try again. The last valid files were kept.',
+  }
+}
+
+function getGeneratorDiagnostic(error: unknown) {
+  if (
+    typeof error !== 'object' ||
+    error === null ||
+    !('diagnostic' in error)
+  ) {
+    return null
+  }
+
+  return error.diagnostic as GeneratorDiagnostic
+}
+
+function visualbuildDevApi(): Plugin {
+  const pagesPath = resolveConfiguredPath(
+    startupProjectConfig.paths.schemaFile
+  )
+  const runtimeClassesPath = path.resolve(
+    builderRoot,
+    '.visualbuild-runtime-classes.html'
+  )
+  const generatorPath = path.resolve(
+    builderPackageRoot,
+    'scripts/vb-generate.mjs'
+  )
+
+  return {
+    name: 'visualbuild-dev-api',
+    async configResolved() {
+      await fs.writeFile(
+        runtimeClassesPath,
+        await fs.readFile(runtimeClassesPath, 'utf8').catch(() => '')
+      )
+    },
+    configureServer(server) {
+      let suppressWatchUntil = 0
+      let suppressReloadUntil = 0
+      let generateTimer: ReturnType<typeof setTimeout> | null = null
+      let managedDeletionQueue = Promise.resolve()
+      let deploymentInProgress = false
+      const reverseSyncTimers = new Map<
+        string,
+        ReturnType<typeof setTimeout>
+      >()
+      const suppressedUnlinkPaths = new Map<string, number>()
+      const eventClients = new Set<ServerResponse>()
+      const hotChannel = server.ws as unknown as {
+        send: (payload: unknown, data?: unknown) => void
+      }
+      const sendHotPayload = hotChannel.send.bind(hotChannel)
+
+      hotChannel.send = (payload, data) => {
+        if (
+          Date.now() < suppressReloadUntil &&
+          typeof payload === 'object' &&
+          payload !== null &&
+          'type' in payload &&
+          payload.type === 'full-reload'
+        ) {
+          return
+        }
+
+        sendHotPayload(payload, data)
+      }
+
+      async function generateProjectFiles(reason: string) {
+        try {
+          const { stdout, stderr } = await execFileAsync(
+            process.execPath,
+            [generatorPath],
+            { cwd: projectRoot }
+          )
+
+          if (stdout.trim()) {
+            server.config.logger.info(stdout.trim())
+          }
+
+          if (stderr.trim()) {
+            server.config.logger.warn(stderr.trim())
+          }
+        } catch (error) {
+          const diagnostic = parseGeneratorDiagnostic(error, reason)
+          server.config.logger.error(
+            `[VisualBuild] ${diagnostic.title}: ${diagnostic.message}`
+          )
+          broadcastVisualBuildEvent({
+            type: 'generator-diagnostic',
+            ...diagnostic,
+          })
+
+          const generationError = new Error(diagnostic.message)
+          Object.assign(generationError, { diagnostic })
+          throw generationError
+        }
+      }
+
+      const pagesWatcher = watchFiles(pagesPath, {
+        ignoreInitial: true,
+        usePolling: process.platform === 'win32',
+        interval: 100,
+        awaitWriteFinish: {
+          stabilityThreshold: 120,
+          pollInterval: 25,
+        },
+      }).on('change', () => {
+        if (Date.now() < suppressWatchUntil) {
+          return
+        }
+
+        if (generateTimer) {
+          clearTimeout(generateTimer)
+        }
+
+        generateTimer = setTimeout(() => {
+          generateTimer = null
+          void generateProjectFiles('pages.json change').catch(() => {})
+        }, 80)
+      })
+
+      function broadcastVisualBuildEvent(event: VisualBuildEvent) {
+        const payload = `event: visualbuild\ndata: ${JSON.stringify(event)}\n\n`
+
+        for (const client of eventClients) {
+          client.write(payload)
+        }
+      }
+
+      function normalizeManagedPath(value: unknown) {
+        return typeof value === 'string'
+          ? value.replace(/\\/g, '/').replace(/^\.\/+/, '')
+          : ''
+      }
+
+      function findManagedPagesForPath(
+        schema: ManagedProjectSchema,
+        relativePath: string,
+        isDirectory: boolean
+      ) {
+        const normalizedTarget = normalizeManagedPath(relativePath)
+
+        return schema.pages.filter((page) => {
+          const sourcePath = normalizeManagedPath(page.sourcePath)
+
+          return (
+            sourcePath === normalizedTarget ||
+            (isDirectory && sourcePath.startsWith(`${normalizedTarget}/`))
+          )
+        })
+      }
+
+      function replaceManagedPathPrefix(
+        sourcePath: string,
+        previousPath: string,
+        targetPath: string
+      ) {
+        return `${targetPath}${sourcePath.slice(previousPath.length)}`
+      }
+
+      function validateManagedPagePaths(schema: ManagedProjectSchema) {
+        const seenSourcePaths = new Set<string>()
+
+        for (const page of schema.pages) {
+          const sourcePath = normalizeManagedPath(page.sourcePath)
+
+          if (
+            !isPathInsideDirectory(
+              sourcePath,
+              startupProjectConfig.paths.sourceDir
+            ) ||
+            !/\.(jsx|tsx)$/i.test(sourcePath) ||
+            sourcePath.includes('/../') ||
+            sourcePath.endsWith('/..')
+          ) {
+            throw new Error(
+              `Managed page "${page.name}" must remain a .jsx or .tsx file inside ${startupProjectConfig.paths.sourceDir}`
+            )
+          }
+
+          const layoutPath =
+            `${startupProjectConfig.paths.layoutsDir}/AppLayout.tsx`
+          if (
+            sourcePath === startupProjectConfig.paths.appFile ||
+            sourcePath === layoutPath
+          ) {
+            throw new Error(`Managed page path is reserved: ${sourcePath}`)
+          }
+
+          if (seenSourcePaths.has(sourcePath)) {
+            throw new Error(`Duplicate managed page path: ${sourcePath}`)
+          }
+
+          seenSourcePaths.add(sourcePath)
+        }
+      }
+
+      function suppressManagedUnlink(relativePath: string) {
+        suppressedUnlinkPaths.set(
+          normalizeManagedPath(relativePath),
+          Date.now() + 2500
+        )
+      }
+
+      function consumeSuppressedUnlink(relativePath: string) {
+        const normalizedPath = normalizeManagedPath(relativePath)
+        const expiresAt = suppressedUnlinkPaths.get(normalizedPath)
+
+        if (!expiresAt) return false
+
+        suppressedUnlinkPaths.delete(normalizedPath)
+        return expiresAt >= Date.now()
+      }
+
+      async function persistManagedPageDeletion(
+        relativePath: string,
+        isDirectory: boolean,
+        deleteTarget?: () => Promise<void>
+      ) {
+        const schema = JSON.parse(
+          await fs.readFile(pagesPath, 'utf8')
+        ) as ManagedProjectSchema
+        const removedPages = findManagedPagesForPath(
+          schema,
+          relativePath,
+          isDirectory
+        )
+
+        if (removedPages.length === 0) {
+          if (deleteTarget) await deleteTarget()
+          return []
+        }
+
+        if (removedPages.length === schema.pages.length) {
+          throw new Error(
+            'A VisualBuild project must keep at least one registered page'
+          )
+        }
+
+        const removedPageIds = new Set(removedPages.map((page) => page.id))
+        const nextSchema: ManagedProjectSchema = {
+          ...schema,
+          pages: schema.pages.filter((page) => !removedPageIds.has(page.id)),
+        }
+
+        for (const page of removedPages) {
+          const sourcePath = normalizeManagedPath(page.sourcePath)
+
+          if (sourcePath) {
+            suppressManagedUnlink(sourcePath)
+            const pendingTimer = reverseSyncTimers.get(
+              path.resolve(projectRoot, sourcePath)
+            )
+
+            if (pendingTimer) {
+              clearTimeout(pendingTimer)
+              reverseSyncTimers.delete(path.resolve(projectRoot, sourcePath))
+            }
+          }
+        }
+
+        suppressWatchUntil = Date.now() + 1500
+        await fs.writeFile(
+          pagesPath,
+          `${JSON.stringify(nextSchema, null, 2)}\n`,
+          'utf8'
+        )
+
+        try {
+          if (deleteTarget) await deleteTarget()
+        } catch (error) {
+          suppressWatchUntil = Date.now() + 1500
+          await fs.writeFile(
+            pagesPath,
+            `${JSON.stringify(schema, null, 2)}\n`,
+            'utf8'
+          )
+          throw error
+        }
+
+        await generateProjectFiles('managed page deletion')
+        broadcastVisualBuildEvent({
+          type: 'managed-pages-deleted',
+          path: normalizeManagedPath(relativePath),
+          pageIds: removedPages.map((page) => page.id),
+          message:
+            removedPages.length === 1
+              ? `Deleted ${removedPages[0].name}`
+              : `Deleted ${removedPages.length} pages`,
+        })
+
+        return removedPages
+      }
+
+      async function persistManagedPageMove(
+        relativePath: string,
+        targetRelativePath: string,
+        isDirectory: boolean,
+        moveTarget: () => Promise<void>,
+        rollbackTarget: () => Promise<void>
+      ) {
+        const normalizedSource = normalizeManagedPath(relativePath)
+        const normalizedTarget = normalizeManagedPath(targetRelativePath)
+        const schema = JSON.parse(
+          await fs.readFile(pagesPath, 'utf8')
+        ) as ManagedProjectSchema
+        const affectedPages = findManagedPagesForPath(
+          schema,
+          normalizedSource,
+          isDirectory
+        )
+
+        if (affectedPages.length === 0) {
+          await moveTarget()
+          return []
+        }
+
+        const affectedPageIds = new Set(affectedPages.map((page) => page.id))
+        const pathChanges: ManagedPagePathChange[] = affectedPages.map(
+          (page) => {
+            const previousPath = normalizeManagedPath(page.sourcePath)
+
+            return {
+              pageId: page.id,
+              previousPath,
+              sourcePath: isDirectory
+                ? replaceManagedPathPrefix(
+                    previousPath,
+                    normalizedSource,
+                    normalizedTarget
+                  )
+                : normalizedTarget,
+            }
+          }
+        )
+        const nextPaths = new Map(
+          pathChanges.map((change) => [change.pageId, change.sourcePath])
+        )
+        const nextSchema: ManagedProjectSchema = {
+          ...schema,
+          pages: schema.pages.map((page) =>
+            affectedPageIds.has(page.id)
+              ? { ...page, sourcePath: nextPaths.get(page.id) }
+              : page
+          ),
+        }
+
+        validateManagedPagePaths(nextSchema)
+
+        for (const change of pathChanges) {
+          suppressManagedUnlink(change.previousPath)
+          const previousAbsolutePath = path.resolve(
+            projectRoot,
+            change.previousPath
+          )
+          const pendingTimer = reverseSyncTimers.get(previousAbsolutePath)
+
+          if (pendingTimer) {
+            clearTimeout(pendingTimer)
+            reverseSyncTimers.delete(previousAbsolutePath)
+          }
+        }
+
+        let targetMoved = false
+        let schemaUpdated = false
+
+        try {
+          await moveTarget()
+          targetMoved = true
+          suppressWatchUntil = Date.now() + 1500
+          await fs.writeFile(
+            pagesPath,
+            `${JSON.stringify(nextSchema, null, 2)}\n`,
+            'utf8'
+          )
+          schemaUpdated = true
+          await generateProjectFiles('managed page move')
+        } catch (error) {
+          suppressWatchUntil = Date.now() + 1500
+
+          if (schemaUpdated) {
+            await fs.writeFile(
+              pagesPath,
+              `${JSON.stringify(schema, null, 2)}\n`,
+              'utf8'
+            )
+          }
+
+          if (targetMoved) {
+            await rollbackTarget()
+          }
+
+          if (schemaUpdated) {
+            await generateProjectFiles('managed page move rollback').catch(
+              () => {}
+            )
+          }
+
+          throw error
+        }
+
+        broadcastVisualBuildEvent({
+          type: 'managed-pages-moved',
+          path: normalizedSource,
+          targetPath: normalizedTarget,
+          pages: pathChanges,
+          message:
+            pathChanges.length === 1
+              ? `Moved ${affectedPages[0].name}`
+              : `Moved ${pathChanges.length} managed pages`,
+        })
+
+        return pathChanges
+      }
+
+      function unregisterExternallyDeletedPage(relativePath: string) {
+        managedDeletionQueue = managedDeletionQueue
+          .then(async () => {
+            const schema = JSON.parse(
+              await fs.readFile(pagesPath, 'utf8')
+            ) as ManagedProjectSchema
+            const removedPages = findManagedPagesForPath(
+              schema,
+              relativePath,
+              false
+            )
+
+            if (removedPages.length === 0) return
+
+            if (removedPages.length === schema.pages.length) {
+              await generateProjectFiles('restore required page')
+              broadcastVisualBuildEvent({
+                type: 'reverse-sync-error',
+                path: relativePath,
+                pageId: removedPages[0].id,
+                message:
+                  'The only registered page cannot be deleted. VisualBuild restored its source file.',
+              })
+              return
+            }
+
+            await persistManagedPageDeletion(relativePath, false)
+          })
+          .catch((error) => {
+            const message =
+              error instanceof Error
+                ? error.message
+                : 'Could not unregister the deleted page.'
+            broadcastVisualBuildEvent({
+              type: 'reverse-sync-error',
+              path: relativePath,
+              message,
+            })
+            server.config.logger.warn(
+              `[VisualBuild] Page deletion sync skipped ${relativePath}: ${message}`
+            )
+          })
+      }
+
+      async function reverseSyncSourceFile(absolutePath: string) {
+        const relativePath = path
+          .relative(projectRoot, absolutePath)
+          .split(path.sep)
+          .join('/')
+
+        try {
+          const schema = JSON.parse(
+            await fs.readFile(pagesPath, 'utf8')
+          ) as ManagedProjectSchema
+          const pageIndex = schema.pages.findIndex(
+            (page) =>
+              normalizeManagedPath(page.sourcePath) === relativePath
+          )
+
+          if (pageIndex < 0) return
+
+          const page = schema.pages[pageIndex]
+          const source = await fs.readFile(absolutePath, 'utf8')
+          const config = await loadVisualBuildConfig(projectRoot)
+          const customComponentNames = (config.components ?? []).map(
+            (component) => component.name
+          )
+          const imported = parseReactPageSource(
+            source,
+            relativePath,
+            customComponentNames
+          )
+          const current: ImportedPageTree = {
+            root: page.root,
+            components: page.components,
+          }
+          const reconciled = reconcileImportedTree(
+            imported,
+            current,
+            customComponentNames
+          )
+
+          if (visualTreesEqual(reconciled, current)) return
+
+          schema.pages[pageIndex] = {
+            ...page,
+            root: reconciled.root,
+            components: reconciled.components,
+          }
+          suppressWatchUntil = Date.now() + 1200
+          await fs.writeFile(
+            pagesPath,
+            `${JSON.stringify(schema, null, 2)}\n`,
+            'utf8'
+          )
+          broadcastVisualBuildEvent({
+            type: 'reverse-sync-success',
+            path: relativePath,
+            pageId: page.id,
+            message: `Updated ${page.name} from ${relativePath}`,
+          })
+          server.config.logger.info(
+            `[VisualBuild] Reverse synced ${relativePath}`
+          )
+        } catch (error) {
+          const message =
+            error instanceof Error
+              ? error.message
+              : 'Reverse sync could not parse the managed page.'
+          broadcastVisualBuildEvent({
+            type: 'reverse-sync-error',
+            path: relativePath,
+            message,
+          })
+          server.config.logger.warn(
+            `[VisualBuild] Reverse sync skipped ${relativePath}: ${message}`
+          )
+        }
+      }
+
+      function scheduleReverseSync(absolutePath: string) {
+        if (!/\.(jsx|tsx)$/i.test(absolutePath)) return
+
+        const previousTimer = reverseSyncTimers.get(absolutePath)
+        if (previousTimer) clearTimeout(previousTimer)
+
+        reverseSyncTimers.set(
+          absolutePath,
+          setTimeout(() => {
+            reverseSyncTimers.delete(absolutePath)
+            void reverseSyncSourceFile(absolutePath)
+          }, 100)
+        )
+      }
+
+      function handleProjectFileChange(
+        action: FileSystemEvent['action'],
+        absolutePath: string
+      ) {
+        const relativePath = path
+          .relative(projectRoot, absolutePath)
+          .split(path.sep)
+          .join('/')
+
+        if (
+          !relativePath ||
+          relativePath === '..' ||
+          relativePath.startsWith('../')
+        ) {
+          return
+        }
+
+        broadcastVisualBuildEvent({
+          type: 'filesystem-change',
+          path: relativePath,
+          action,
+        })
+
+        const relativeToSource = path.relative(generatedSourceRoot, absolutePath)
+        const isInsideSource =
+          relativeToSource &&
+          relativeToSource !== '..' &&
+          !relativeToSource.startsWith(`..${path.sep}`) &&
+          !path.isAbsolute(relativeToSource)
+
+        if (isInsideSource && (action === 'add' || action === 'change')) {
+          scheduleReverseSync(absolutePath)
+        }
+
+        if (
+          isInsideSource &&
+          action === 'unlink' &&
+          !consumeSuppressedUnlink(relativePath)
+        ) {
+          unregisterExternallyDeletedPage(relativePath)
+        }
+      }
+
+      const projectWatcher = watchFiles(projectRoot, {
+        ignoreInitial: true,
+        usePolling: process.platform === 'win32',
+        interval: 100,
+        ignored: (watchedPath) => {
+          const relativePath = path.relative(projectRoot, path.resolve(watchedPath))
+          const segments = relativePath.split(path.sep)
+
+          return segments.some((segment) =>
+            ['.git', 'node_modules', 'dist', '.visualbuild-qa'].includes(segment)
+          )
+        },
+        awaitWriteFinish: {
+          stabilityThreshold: 140,
+          pollInterval: 25,
+        },
+      })
+        .on('add', (changedPath) => handleProjectFileChange('add', changedPath))
+        .on('change', (changedPath) =>
+          handleProjectFileChange('change', changedPath)
+        )
+        .on('unlink', (changedPath) =>
+          handleProjectFileChange('unlink', changedPath)
+        )
+        .on('addDir', (changedPath) =>
+          handleProjectFileChange('addDir', changedPath)
+        )
+        .on('unlinkDir', (changedPath) =>
+          handleProjectFileChange('unlinkDir', changedPath)
+        )
+        .on('ready', () => {
+          server.config.logger.info(
+            `[VisualBuild] Watching ${projectRoot} for project and managed source changes`
+          )
+        })
+        .on('error', (error) => {
+          server.config.logger.warn(
+            `[VisualBuild] Source watcher error: ${error.message}`
+          )
+        })
+
+      const keepAliveTimer = setInterval(() => {
+        for (const client of eventClients) {
+          client.write(': keep-alive\n\n')
+        }
+      }, 15000)
+
+      server.httpServer?.once('close', () => {
+        void pagesWatcher.close()
+        void projectWatcher.close()
+        clearInterval(keepAliveTimer)
+
+        for (const client of eventClients) {
+          client.end()
+        }
+
+        for (const timer of reverseSyncTimers.values()) {
+          clearTimeout(timer)
+        }
+
+        if (generateTimer) {
+          clearTimeout(generateTimer)
+        }
+      })
+
+      void generateProjectFiles('dev server start').catch(() => {})
+
+      server.middlewares.use('/__visualbuild/events', (req, res) => {
+        if (req.method !== 'GET') {
+          res.statusCode = 405
+          res.end()
+          return
+        }
+
+        res.statusCode = 200
+        res.setHeader('Content-Type', 'text/event-stream')
+        res.setHeader('Cache-Control', 'no-cache, no-transform')
+        res.setHeader('Connection', 'keep-alive')
+        res.write('retry: 1500\n\n')
+        eventClients.add(res)
+
+        req.once('close', () => {
+          eventClients.delete(res)
+        })
+      })
+
+      server.middlewares.use('/__visualbuild/config', async (req, res) => {
+        if (req.method !== 'GET') {
+          res.statusCode = 405
+          res.end()
+          return
+        }
+
+        try {
+          const config = await loadVisualBuildConfig(projectRoot)
+          sendJson(res, 200, {
+            paths: config.paths,
+            editor: config.editor,
+            generator: config.generator,
+            deployment: config.deployment,
+            customComponents: await addComponentPreviews(
+              config.components ?? []
+            ),
+          })
+        } catch (error) {
+          sendJson(res, 400, {
+            error:
+              error instanceof Error
+                ? error.message
+                : 'Failed to load visualbuild.config.ts',
+          })
+        }
+      })
+
+      server.middlewares.use('/__visualbuild/deploy', async (req, res) => {
+        try {
+          const config = await loadVisualBuildConfig(projectRoot)
+          const packageJson = JSON.parse(
+            await fs.readFile(path.join(projectRoot, 'package.json'), 'utf8')
+          ) as { name?: unknown }
+          const defaultProjectName = validateVercelProjectName(
+            config.deployment.projectName ?? packageJson.name ?? path.basename(projectRoot)
+          )
+          const configuredTeamId = validateVercelTeamId(
+            config.deployment.teamId ?? process.env.VERCEL_TEAM_ID
+          )
+          const token =
+            process.env.VERCEL_TOKEN ?? process.env.VERCEL_ACCESS_TOKEN ?? ''
+
+          if (req.method === 'GET') {
+            sendJson(res, 200, {
+              provider: 'vercel',
+              tokenConfigured: Boolean(token.trim()),
+              projectName: defaultProjectName,
+              teamId: configuredTeamId ?? '',
+              outputDirectory: config.deployment.outputDirectory,
+              sourcePolicy: 'static-build-output-only',
+            })
+            return
+          }
+
+          if (req.method !== 'POST') {
+            res.statusCode = 405
+            res.end()
+            return
+          }
+
+          if (!token.trim()) {
+            sendJson(res, 401, {
+              error:
+                'Set VERCEL_TOKEN in the visual-builder terminal, restart the builder, and try again.',
+            })
+            return
+          }
+
+          if (deploymentInProgress) {
+            sendJson(res, 409, {
+              error: 'A Vercel deployment is already in progress',
+            })
+            return
+          }
+
+          const payload = await readJsonBody(req)
+          const projectName = validateVercelProjectName(
+            typeof payload.projectName === 'string'
+              ? payload.projectName
+              : defaultProjectName
+          )
+          const teamId = validateVercelTeamId(
+            typeof payload.teamId === 'string'
+              ? payload.teamId
+              : configuredTeamId
+          )
+          const outputPath = getProjectPath(
+            config.deployment.outputDirectory
+          )
+
+          deploymentInProgress = true
+
+          try {
+            await generateProjectFiles('Vercel deployment')
+            const npmBuildCommand = resolveNpmBuildCommand()
+            const { stdout, stderr } = await execFileAsync(
+              npmBuildCommand.executable,
+              npmBuildCommand.args,
+              {
+                cwd: projectRoot,
+                env: {
+                  ...process.env,
+                  VISUALBUILD_DEPLOYMENT: 'vercel',
+                },
+                maxBuffer: 10 * 1024 * 1024,
+              }
+            )
+
+            if (stdout.trim()) server.config.logger.info(stdout.trim())
+            if (stderr.trim()) server.config.logger.warn(stderr.trim())
+
+            const result = await deployStaticOutputToVercel({
+              outputRoot: outputPath.absolutePath,
+              token,
+              projectName,
+              teamId,
+            })
+
+            sendJson(res, 200, result)
+          } finally {
+            deploymentInProgress = false
+          }
+        } catch (error) {
+          const message =
+            error instanceof Error ? error.message : 'Vercel deployment failed'
+          server.config.logger.error(`[VisualBuild] Deployment failed: ${message}`)
+          sendJson(res, 400, { error: message })
+        }
+      })
+
+      server.middlewares.use('/__visualbuild/files', async (req, res) => {
+        const requestUrl = new URL(req.url ?? '/', 'http://visualbuild.local')
+
+        try {
+          if (req.method === 'GET') {
+            const result = await listProjectDirectory(
+              requestUrl.searchParams.get('path') ?? ''
+            )
+            sendJson(res, 200, result)
+            return
+          }
+
+          if (req.method === 'POST') {
+            const payload = await readJsonBody(req)
+            const parentPath = getProjectPath(
+              typeof payload.parentPath === 'string' ? payload.parentPath : ''
+            )
+            const parentStats = await fs.lstat(parentPath.absolutePath)
+
+            if (!parentStats.isDirectory() || parentStats.isSymbolicLink()) {
+              throw new Error('Select a valid parent folder')
+            }
+
+            await assertRealPathInsideProject(parentPath.absolutePath)
+            const name = validateEntryName(payload.name)
+            const targetPath = getProjectPath(
+              parentPath.relativePath
+                ? `${parentPath.relativePath}/${name}`
+                : name
+            )
+
+            if (payload.kind === 'directory') {
+              await fs.mkdir(targetPath.absolutePath)
+            } else if (payload.kind === 'file') {
+              await fs.writeFile(
+                targetPath.absolutePath,
+                createReactComponentSource(name),
+                {
+                encoding: 'utf8',
+                flag: 'wx',
+                }
+              )
+            } else {
+              throw new Error('Entry type must be file or directory')
+            }
+
+            sendJson(res, 201, {
+              name,
+              path: targetPath.relativePath,
+              kind: payload.kind,
+            })
+            return
+          }
+
+          if (req.method === 'PATCH') {
+            const payload = await readJsonBody(req)
+            const sourcePath = getProjectPath(
+              typeof payload.path === 'string' ? payload.path : ''
+            )
+
+            if (!sourcePath.relativePath) {
+              throw new Error('The project root cannot be renamed')
+            }
+
+            const sourceStats = await fs.lstat(sourcePath.absolutePath)
+
+            if (!sourceStats.isSymbolicLink()) {
+              await assertRealPathInsideProject(sourcePath.absolutePath)
+            }
+
+            const name = validateEntryName(payload.name)
+            const currentParentPath = path.posix.dirname(
+              sourcePath.relativePath
+            )
+            const requestedParentPath =
+              typeof payload.parentPath === 'string'
+                ? getProjectPath(payload.parentPath)
+                : getProjectPath(
+                    currentParentPath === '.' ? '' : currentParentPath
+                  )
+            const parentStats = await fs.lstat(
+              requestedParentPath.absolutePath
+            )
+
+            if (
+              !parentStats.isDirectory() ||
+              parentStats.isSymbolicLink()
+            ) {
+              throw new Error('Select a valid destination folder')
+            }
+
+            await assertRealPathInsideProject(
+              requestedParentPath.absolutePath
+            )
+            const targetPath = getProjectPath(
+              requestedParentPath.relativePath
+                ? `${requestedParentPath.relativePath}/${name}`
+                : name
+            )
+
+            if (targetPath.relativePath === sourcePath.relativePath) {
+              sendJson(res, 200, {
+                name,
+                path: targetPath.relativePath,
+                kind: sourceStats.isSymbolicLink()
+                  ? 'symlink'
+                  : sourceStats.isDirectory()
+                    ? 'directory'
+                    : 'file',
+                managedPages: [],
+              })
+              return
+            }
+
+            if (
+              sourceStats.isDirectory() &&
+              targetPath.relativePath.startsWith(
+                `${sourcePath.relativePath}/`
+              )
+            ) {
+              throw new Error('A folder cannot be moved inside itself')
+            }
+
+            const targetExists = await fs
+              .lstat(targetPath.absolutePath)
+              .then(() => true)
+              .catch((error: NodeJS.ErrnoException) => {
+                if (error.code === 'ENOENT') return false
+                throw error
+              })
+
+            if (targetExists) {
+              throw new Error('A file or folder with that name already exists')
+            }
+
+            const managedPages = await persistManagedPageMove(
+              sourcePath.relativePath,
+              targetPath.relativePath,
+              sourceStats.isDirectory() && !sourceStats.isSymbolicLink(),
+              () =>
+                fs.rename(sourcePath.absolutePath, targetPath.absolutePath),
+              () =>
+                fs.rename(targetPath.absolutePath, sourcePath.absolutePath)
+            )
+            sendJson(res, 200, {
+              name,
+              path: targetPath.relativePath,
+              kind: sourceStats.isSymbolicLink()
+                ? 'symlink'
+                : sourceStats.isDirectory()
+                  ? 'directory'
+                  : 'file',
+              managedPages,
+            })
+            return
+          }
+
+          if (req.method === 'DELETE') {
+            const targetPath = getProjectPath(
+              requestUrl.searchParams.get('path') ?? ''
+            )
+
+            if (!targetPath.relativePath) {
+              throw new Error('The project root cannot be deleted')
+            }
+
+            const targetStats = await fs.lstat(targetPath.absolutePath)
+
+            if (!targetStats.isSymbolicLink()) {
+              await assertRealPathInsideProject(targetPath.absolutePath)
+            }
+
+            const deleteTarget = () =>
+              fs.rm(targetPath.absolutePath, {
+                recursive: targetStats.isDirectory(),
+              })
+            const removedPages = await persistManagedPageDeletion(
+              targetPath.relativePath,
+              targetStats.isDirectory(),
+              deleteTarget
+            )
+
+            sendJson(res, 200, {
+              path: targetPath.relativePath,
+              removedPageIds: removedPages.map((page) => page.id),
+            })
+            return
+          }
+
+          res.statusCode = 405
+          res.end()
+        } catch (error) {
+          sendJson(res, getErrorStatus(error), {
+            error:
+              error instanceof Error
+                ? error.message
+                : 'Project file operation failed',
+          })
+        }
+      })
+
+      server.middlewares.use('/__visualbuild/file', async (req, res) => {
+        const requestUrl = new URL(req.url ?? '/', 'http://visualbuild.local')
+
+        try {
+          if (req.method === 'GET') {
+            sendJson(
+              res,
+              200,
+              await readProjectFile(requestUrl.searchParams.get('path') ?? '')
+            )
+            return
+          }
+
+          if (req.method === 'PUT') {
+            const payload = await readJsonBody(req)
+            const targetPath = getProjectPath(
+              typeof payload.path === 'string' ? payload.path : ''
+            )
+            const stats = await fs.lstat(targetPath.absolutePath)
+
+            if (!stats.isFile() || stats.isSymbolicLink()) {
+              throw new Error('The selected path is not an editable file')
+            }
+
+            await assertRealPathInsideProject(targetPath.absolutePath)
+
+            if (typeof payload.content !== 'string') {
+              throw new Error('File content must be text')
+            }
+
+            if (Buffer.byteLength(payload.content, 'utf8') > maxEditableFileBytes) {
+              throw new Error('File content exceeds the 2 MB editor limit')
+            }
+
+            await fs.writeFile(targetPath.absolutePath, payload.content, 'utf8')
+            res.statusCode = 204
+            res.end()
+            return
+          }
+
+          res.statusCode = 405
+          res.end()
+        } catch (error) {
+          sendJson(res, getErrorStatus(error), {
+            error:
+              error instanceof Error
+                ? error.message
+                : 'Project file operation failed',
+          })
+        }
+      })
+
+      server.middlewares.use('/__visualbuild/import-page', async (req, res) => {
+        try {
+          if (req.method !== 'POST') {
+            res.statusCode = 405
+            res.end()
+            return
+          }
+
+          const payload = await readJsonBody(req)
+          const name =
+            typeof payload.name === 'string' ? payload.name.trim() : ''
+          const route =
+            typeof payload.route === 'string' ? payload.route.trim() : ''
+          const sourcePath =
+            typeof payload.path === 'string' ? payload.path : ''
+
+          if (!name) {
+            throw new Error('Page name is required')
+          }
+
+          if (!route.startsWith('/')) {
+            throw new Error('Page route must start with "/"')
+          }
+
+          sendJson(
+            res,
+            201,
+            await importPageFromSource(sourcePath, name, route)
+          )
+        } catch (error) {
+          sendJson(res, getErrorStatus(error), {
+            error:
+              error instanceof Error
+                ? error.message
+                : 'Failed to import page source',
+          })
+        }
+      })
+
+      server.middlewares.use(
+        '/__visualbuild/register-component',
+        async (req, res) => {
+          try {
+            if (req.method !== 'POST') {
+              res.statusCode = 405
+              res.end()
+              return
+            }
+
+            const payload = await readJsonBody(req)
+            const sourcePath =
+              typeof payload.path === 'string' ? payload.path : ''
+            sendJson(
+              res,
+              201,
+              await registerComponentFromSource(sourcePath)
+            )
+          } catch (error) {
+            sendJson(res, getErrorStatus(error), {
+              error:
+                error instanceof Error
+                  ? error.message
+                  : 'Failed to register component source',
+            })
+          }
+        }
+      )
+
+      server.middlewares.use('/__visualbuild/tailwind', (req, res) => {
+        if (req.method !== 'POST') {
+          res.statusCode = 405
+          res.end()
+          return
+        }
+
+        let body = ''
+
+        req.on('data', (chunk) => {
+          body += chunk
+        })
+
+        req.on('end', async () => {
+          try {
+            const current = await fs
+              .readFile(runtimeClassesPath, 'utf8')
+              .catch(() => '')
+
+            if (current !== body) {
+              suppressReloadUntil = Date.now() + 1500
+              await fs.writeFile(runtimeClassesPath, body)
+            }
+
+            res.statusCode = 204
+            res.end()
+          } catch (error) {
+            res.statusCode = 500
+            res.end(
+              error instanceof Error
+                ? error.message
+                : 'Failed to update Tailwind classes'
+            )
+          }
+        })
+      })
+
+      server.middlewares.use('/__visualbuild/pages', async (req, res) => {
+        if (req.method === 'GET') {
+          try {
+            const json = await fs.readFile(pagesPath, 'utf8')
+            res.setHeader('Content-Type', 'application/json')
+            res.setHeader(
+              'X-VisualBuild-Project-Id',
+              encodeURIComponent(projectRoot)
+            )
+            res.end(json)
+          } catch (error) {
+            res.statusCode = 500
+            res.end(
+              error instanceof Error
+                ? error.message
+                : 'Failed to read pages.json'
+            )
+          }
+          return
+        }
+
+        if (req.method === 'POST') {
+          let body = ''
+
+          req.on('data', (chunk) => {
+            body += chunk
+          })
+
+          req.on('end', async () => {
+            let previousSchema = ''
+            let wroteSchema = false
+
+            try {
+              await fs.mkdir(path.dirname(pagesPath), { recursive: true })
+              previousSchema = await fs
+                .readFile(pagesPath, 'utf8')
+                .catch(() => '')
+
+              if (previousSchema !== body) {
+                suppressWatchUntil = Date.now() + 1000
+                suppressReloadUntil = Date.now() + 5000
+                await fs.writeFile(pagesPath, body)
+                wroteSchema = true
+                await generateProjectFiles('pages.json write')
+                suppressReloadUntil = Date.now() + 1000
+              }
+
+              res.statusCode = 204
+              res.end()
+            } catch (error) {
+              if (wroteSchema) {
+                suppressWatchUntil = Date.now() + 1000
+
+                if (previousSchema) {
+                  await fs.writeFile(pagesPath, previousSchema)
+                  await generateProjectFiles('pages.json rollback').catch(
+                    (rollbackError) => {
+                      server.config.logger.error(
+                        `[VisualBuild] Failed to restore generated files: ${
+                          rollbackError instanceof Error
+                            ? rollbackError.message
+                            : String(rollbackError)
+                        }`
+                      )
+                    }
+                  )
+                } else {
+                  await fs.rm(pagesPath, { force: true })
+                }
+              }
+
+              const diagnostic = getGeneratorDiagnostic(error)
+              sendJson(res, 500, {
+                error:
+                  diagnostic?.message ??
+                  (error instanceof Error
+                    ? error.message
+                    : 'Failed to write pages.json'),
+                diagnostic,
+              })
+            }
+          })
+
+          return
+        }
+
+        res.statusCode = 405
+        res.end()
+      })
+    },
+  }
+}
+
+export default defineConfig({
+  root: builderRoot,
+  define: {
+    'process.env.BABEL_TYPES_8_BREAKING': 'false',
+  },
+  plugins: [react(), tailwindcss(), visualbuildDevApi()],
+  server: {
+    watch: {
+      ignored: ['**/node_modules/**', isGeneratedProjectPath],
+    },
+  },
+})