# @proyecta-ai/vite

Vite plugin suite for [Proyecta](https://proyecta.dev) applications. Provides component tagging, visual editing, route collection, error handling, and dynamic component creation for the Proyecta builder platform.

## Installation

```bash
npm install @proyecta-ai/vite
```

Peer dependencies:

```bash
npm install vite oxc-parser
```

## Usage

```ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import proyecta from '@proyecta-ai/vite';

export default defineConfig({
    plugins: [...proyecta(), react()],
});
```

With options:

```ts
export default defineConfig({
    plugins: [
        ...proyecta({
            debug: true,
            handleViteErrors: true,
            componentTagger: { enabled: true },
            visualEditor: { enabled: true },
            dynamicComponentCreator: { enabled: true },
        }),
        react(),
    ],
});
```

## Options

The `proyecta()` function accepts a `ProyectaPluginOptions` object:

| Option                    | Type      | Default                         | Description                                                                                                |
| ------------------------- | --------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `debug`                   | `boolean` | `false`                         | Enable debug logging                                                                                       |
| `message`                 | `string`  | `'Proyecta plugin is running!'` | Custom message to log during build                                                                         |
| `handleViteErrors`        | `boolean` | `true`                          | Enable Vite error handling and console log forwarding                                                      |
| `componentTagger`         | `object`  | `{ enabled: true }`             | Component tagger options (see below)                                                                       |
| `visualEditor`            | `object`  | `{ enabled: true }`             | Visual editor options (see below)                                                                          |
| `dynamicComponentCreator` | `object`  | `{ enabled: true }`             | Dynamic component creator options. Only active when `PROYECTA_DEV_MACHINE` env var is set or `force: true` |

## Features

### Component Tagger

Injects `data-ve-file`, `data-ve-line`, `data-ve-col`, and `data-ve-component` attributes onto JSX elements during development. These attributes enable the Proyecta visual editor to map rendered DOM elements back to their source file locations.

- Parses JSX/TSX files using `oxc-parser`
- Skips `node_modules`, React fragments, and Three.js/R3F elements
- Dev-mode only (`apply: 'serve'`)

### Visual Editor

Provides an in-browser visual editing experience when the app runs inside the Proyecta builder iframe. Features include:

- Element hover highlighting and selection
- Inline text editing with contentEditable
- Element analysis, updates, and deletion via AST transformation
- Parent frame communication via `postMessage` protocol

### Route Collector

Scans source files for React Router route definitions and exposes them via a `/__proyecta_routes` endpoint. Supports both JSX `<Route>` patterns and `createBrowserRouter`/`createHashRouter` config objects. Route changes are detected on HMR updates and forwarded to the parent frame.

### Error Handling

Intercepts Vite build errors, HMR errors, runtime exceptions, and unhandled promise rejections. Suppresses the Vite error overlay and forwards structured error data to the parent Proyecta builder frame via `postMessage`.

### Dynamic Component Creator

Automatically creates stub React component files when imported `.tsx` files don't exist yet. Only active when the `PROYECTA_DEV_MACHINE` environment variable is set (or `force: true`). Supports both relative imports and `@/` alias imports.

### Navigation Tracker

Monitors `history.pushState`, `history.replaceState`, and `popstate` events to notify the parent frame of in-app route changes.

### Health Check

Exposes a `/proyecta-status` endpoint that returns the plugin status as JSON.