npm - create-visualbuild-app - Versions diffs - 1.0.1 → 1.0.2 - Mend

create-visualbuild-app 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -1,984 +1,990 @@
-# VisualBuild
-[![npm version](https://img.shields.io/npm/v/create-visualbuild-app.svg)](https://www.npmjs.com/package/create-visualbuild-app)
-[![GitHub source](https://img.shields.io/badge/GitHub-source-181717?logo=github)](https://github.com/LORD-JINXXX/builder-app)
-VisualBuild is a local visual development framework for building React and
-Tailwind applications with drag and drop while retaining normal, editable
-source code. It combines a component library, recursive canvas, properties
-editor, responsive preview, project explorer, source editor, generator, and
-safe source-to-canvas synchronization in one workflow.
-VisualBuild is not a runtime that must be shipped with the application. The
-result is an ordinary React/Vite project: developers own its files, can edit
-them in any code editor, commit them to Git, build them without the visual
-editor, and deploy the generated application independently.
-## Why VisualBuild was created
-Visual development tools are fast for composing interfaces, but many make the
-tool's private format or runtime the permanent owner of the application.
-Traditional code-first development gives developers full ownership, but
-repetitive layout construction and styling can slow early product work.
-VisualBuild was created to bridge those two workflows:
-- use a visual canvas for the work that is naturally visual;
-- generate readable React source instead of hiding the result;
-- keep the developer-owned application separate from editor tooling;
-- make ownership explicit so the editor never silently replaces arbitrary
-  files;
-- support safe two-way synchronization for a documented static JSX/TSX subset;
-- provide direct code-editing escape hatches when visual controls are not
-  enough;
-- keep the production application free of a VisualBuild runtime dependency.
-The central idea is **visual speed without surrendering source ownership**.
-VisualBuild deliberately does not claim that every possible React program can
-be reconstructed visually. Dynamic application logic stays in normal
-developer-owned components, while the visual system manages the static
-structure it can understand safely.
-## Architecture
-VisualBuild is schema-driven, registry-powered, and code-generating. Its
-architecture separates the deployable application from the local editor and
-uses explicit boundaries for state, source ownership, synchronization, and
-deployment.
-### Workspace boundary
-```text
-workspace/
-  my-app/                 developer-owned React application
-    src/                  real application source
-    visualbuild/          schema, component registry, ownership metadata
-    visualbuild.config.ts typed project configuration
-    package.json          application dependencies only
-  visual-builder/         optional local development tool
-    visual-app-builder/   canvas and editor interface
-    scripts/              generator and launch commands
-    package.json          editor-only dependencies
-```
-The application and editor have independent dependency trees. Drag-and-drop,
-editor state, parsing, and generator dependencies belong to
-`visual-builder/`; they do not enter the application's production dependency
-graph.
-### Forward visual-to-code flow
-```text
-Elements panel + Canvas + Properties
-                 |
-                 v
-       Recursive VisualNode tree
-                 |
-                 v
-       visualbuild/pages.json
-                 |
-        Component registries
-                 |
-                 v
-        Babel AST code generator
-                 |
-                 v
-  React pages, App, layout, and imports
-                 |
-                 v
-       Standard Vite application
-```
-1. Built-in elements and presets come from registries that define their label,
-   category, editable defaults, canvas rendering contract, and generated
-   structure.
-2. Dragging or editing an element changes a recursive `VisualNode` tree in the
-   editor.
-3. Top-bar **Save** persists that tree to `visualbuild/pages.json`, the
-   canonical state for canvas-managed pages.
-4. The generator combines schema data, registered custom-component metadata,
-   and project configuration.
-5. Babel AST generation writes deterministic React source rather than
-   concatenating fragile JSX strings.
-6. The generated app runs with Vite and does not import a VisualBuild runtime.
-The canvas and generated source are two views of the same managed structure:
-the canvas is optimized for composition, while the source files remain useful
-to developers and normal tooling.
-### Component registry architecture
-VisualBuild has two related registry paths:
-- **Built-in registry:** HTML primitives and page-block presets expand into
-  editable node trees. A preset is not an opaque screenshot; its nested
-  headings, text, links, images, containers, classes, IDs, and attributes can
-  be selected and edited.
-- **Custom-component registry:** a local `.jsx` or `.tsx` file is registered
-  in `visualbuild/components.json` with its export, source path, editor label,
-  and editable props. Generated pages import that local component directly.
-Registered custom components keep their implementation in the developer's
-application. VisualBuild adds no runtime wrapper. Definition-owned static JSX
-is selectable on the canvas, and elements dropped into the definition are
-written back to the component source. Pages reuse the definition with imports
-and self-closing component instances.
-### Safe reverse synchronization
-```text
-Supported static JSX/TSX edit
-             |
-          Watcher
-             |
-             v
-        Babel parser
-             |
-   Static-contract validation
-             |
-   Stable node-ID reconciliation
-             |
-             v
-  pages.json and the visual canvas
-```
-The file watcher observes managed pages and registered custom components.
-Supported static JSX/TSX can be parsed, validated, reconciled with existing
-node IDs, and reflected back into the canvas. Equivalent formatting changes do
-not rewrite the schema.
-Hooks, runtime expressions, conditional rendering, mapped collections, spread
-props, and other arbitrary behavior are outside this importer contract. When
-source is unsupported, VisualBuild pauses reverse sync, preserves the source
-file and last valid schema, and reports a diagnostic instead of guessing or
-overwriting code.
-### Source ownership
-VisualBuild treats ownership as a safety rule:
-| Source | Owner | Visual behavior |
-| --- | --- | --- |
-| Managed page source | Canvas/schema | Top-bar Save regenerates it; supported static edits can reverse-sync |
-| Registered custom component | Component definition | Root, props, and definition children update its local source |
-| Generic project file | Developer | Editable in File mode; never regenerated merely because it exists |
-| App and layout outputs | Configuration-dependent | Generated only when their generation switches are enabled |
-| Schema and registry metadata | VisualBuild | Stores page state, registration, and ownership information |
-Generated-file metadata lets the generator update or remove only files it
-owns. Unregistered developer files are preserved.
-### Editor state and Save semantics
-The editor keeps immediate canvas state locally so drag, reorder, selection,
-and property changes feel responsive.
-- Top-bar **Save** commits canvas/schema state and regenerates managed source.
-- **Save file** writes the exact File-editor buffer.
-- External file changes refresh clean buffers.
-- If canvas or File mode contains unsaved work, VisualBuild shows an explicit
-  conflict choice instead of selecting a winner silently.
-- Generation and managed move operations use rollback behavior when a write
-  fails.
-### Preview and code workspace
-The responsive canvas renders the editable node tree at mobile, tablet, and
-desktop widths. Preview removes editor chrome without changing application
-styles. The Code panel exposes generated Page, App, Layout, and JSON views,
-while File mode and the larger code workspace edit the exact selected source
-file.
-Editor themes are scoped to the editor interface. They do not recolor the
-canvas content, generated application, or production build.
-### Production and deployment boundary
-VisualBuild's Vercel workflow saves and generates locally, runs the
-developer-owned application's production build, audits the output, and uploads
-only the configured static build directory.
-It excludes the editor source, `visual-builder/`, `visualbuild/`,
-`node_modules/`, project configuration, and credentials. The Vercel token
-stays in the local builder process and is never written to generated source or
-browser storage.
-## Public CLI
-### Requirements
-- Node.js and npm.
-- A terminal. The examples use PowerShell and `npm.cmd` on Windows. On macOS
-  or Linux, use `npm` in the same commands.
-- A modern browser.
-- A Vercel account and access token only if you want one-click deployment.
-The examples use `my-app` as the application folder. Replace it with the name
-you supplied to the create command.
-### Create a project
-Create a named project from the public package:
-```powershell
-npm create visualbuild-app@latest my-app
-```
-The equivalent `npx` command is:
-```powershell
-npx create-visualbuild-app@latest my-app
-```
-If you omit the name, VisualBuild creates `my-app`:
-```powershell
-npm create visualbuild-app@latest
-```
-Maintainers testing an unpublished local checkout can run this from an empty
-folder:
-```powershell
-npm.cmd --prefix "D:\path\to\builder-app" run create-visualbuild-app -- my-app
-```
-The command creates two sibling projects. It does not install dependencies.
-## Scaffold output
-```text
-workspace/
-  my-app/                    deployable React application
-    src/                     application source
-    visualbuild/             schema, registry, and ownership metadata
-      pages.json             visual page schema
-      components.json        registered custom components and prop metadata
-      generated-files.json   files managed by the generator
-    visualbuild.config.ts    typed project configuration
-    package.json             application dependencies only
-  visual-builder/            optional local editor and generator
-    visual-app-builder/      VisualBuild interface and local API
-    scripts/                 editor and generation commands
-    package.json             editor-only dependencies
-  my-app-README.md           workspace-specific quick start
-  VISUALBUILD-GUIDE.md       a copy of this complete guide
-```
-The separation is a production boundary, not only an organizational choice:
-| Location | Owner and purpose | Deploy it? |
-| --- | --- | --- |
-| `my-app/src` | Real React application source | Yes |
-| `my-app/visualbuild` | VisualBuild schema, registry, and generation metadata | No runtime requirement |
-| `my-app/visualbuild.config.ts` | Local editor/generator configuration | No runtime requirement |
-| `visual-builder` | Visual editor, watcher, generator, and editor-only dependencies | No |
-The app does not install drag-and-drop, editor state, or generator packages.
-It remains runnable after the sibling `visual-builder` directory is removed.
-## Run a generated project
-Open the first terminal in the workspace root, then install and run the
-application:
-```powershell
-cd my-app
-npm.cmd install
-npm.cmd run dev
-```
-Open a separate second terminal in the workspace root, then install and run
-the visual editor:
-```powershell
-cd visual-builder
-npm.cmd install
-npm.cmd run visual-builder
-```
-If the second terminal opens inside `my-app` instead of the workspace root,
-use this path to reach the sibling editor:
-```powershell
-cd ..\visual-builder
-```
-Do not run both development processes sequentially in one occupied terminal.
-Use two terminals so the app and VisualBuild can remain running together. If
-you stop the app and reuse its terminal, then `cd ..\visual-builder` is the
-correct command because that terminal is still inside `my-app`.
-The app normally uses Vite's development URL. VisualBuild opens at:
-```text
-http://127.0.0.1:7371
-```
-Keep the builder terminal open while editing. It runs the file watcher,
-generation API, reverse-sync importer, and optional deployment service.
-## Complete user guide
-The preceding sections explain the product, architecture, installation,
-workspace, and startup flow. The sections below complete the self-contained v1
-guide for using every major VisualBuild workflow.
-1. [Understand the interface](#understand-the-interface)
-2. [Build and edit a page](#build-and-edit-a-page)
-3. [Create and register pages](#create-and-register-pages)
-4. [Use built-in elements](#use-built-in-elements)
-5. [Create and register custom components](#create-and-register-custom-components)
-6. [Use the code panel and larger editor](#use-the-code-panel-and-larger-editor)
-7. [Understand source ownership and synchronization](#understand-source-ownership-and-synchronization)
-8. [Reverse-sync support and limits](#reverse-sync-support-and-limits)
-9. [Configure VisualBuild](#configure-visualbuild)
-10. [Use editor themes and responsive previews](#use-editor-themes-and-responsive-previews)
-11. [Deploy to Vercel](#deploy-to-vercel)
-12. [Generate and build without the editor](#generate-and-build-without-the-editor)
-13. [Upcoming versions](#upcoming-versions)
-14. [Recover from errors and conflicts](#recover-from-errors-and-conflicts)
-15. [Troubleshooting](#troubleshooting)
-## Understand the interface
-### Top bar
-- **Preview** hides editor panels and displays the active page as the user
-  will see it.
-- **Code** opens or closes the right Code panel.
-- The palette button changes the editor theme only.
-- **Save** writes the visual schema and regenerates managed source.
-- **Deploy** builds the developer-owned app and publishes its static output to
-  Vercel.
-### Left panel
-- **Files** is the project explorer. Create, select, rename, move, and delete
-  files or folders here.
-- **Elements** contains global elements, registered custom components,
-  reusable page blocks, and HTML primitives grouped by category.
-- Collapse the panel with its arrow when more canvas space is needed.
-### Canvas and page bar
-- Drag elements from the Elements panel onto insertion zones.
-- Click an element to add it to the selected container. If no valid container
-  is selected, drag it to the desired insertion zone.
-- Select a canvas node to show its controls and Properties.
-- Drag selected nodes to reorder or nest them in compatible containers.
-- Use **Mobile**, **Tablet**, and **Desktop** above the canvas to test the
-  configured responsive widths.
-- Use the page bar along the bottom to switch pages, add a page, or delete a
-  page when more than one exists.
-### Right panel
-- **Properties** edits the selected node's text, ID, component fields,
-  Tailwind classes, arrays, booleans, select values, and supported additional
-  attributes.
-- Selecting the page root exposes **Page root tag**, allowing `div`, `main`,
-  `section`, `article`, `header`, `footer`, `nav`, `aside`, or `form`.
-- Registered custom components expose their managed component root tag, ID,
-  Tailwind classes, additional attributes, and configured prop fields.
-- **Code** shows generated views and the editable source file associated with
-  the current selection.
-- Collapse the panel with its arrow when more canvas space is needed.
-## Build and edit a page
-1. Open **Elements**.
-2. Drag a reusable page block, such as Hero, Grid, or Pricing, onto the canvas.
-3. Select the block or one of its nested elements.
-4. Open **Properties** and edit its text, values, ID, or Tailwind classes.
-5. Drag primitives such as `h2`, `p`, `button`, `section`, or `div` into a
-   compatible insertion zone.
-6. Reorder a node with its drag handle or move it upward with the canvas
-   control.
-7. Select the page root to change its semantic root tag and root classes.
-8. Switch between Mobile, Tablet, and Desktop.
-9. Click **Preview** to inspect the page without editor chrome.
-10. Click **Save** to persist the schema and generated React source.
-Tailwind changes are stored as ordinary `className` strings. The class editor
-offers suggestions as you type; variants such as `sm:`, `hover:`, and `focus:`
-remain part of the generated source. Editor themes never modify these classes.
-## Create and register pages
-VisualBuild supports two page workflows.
-### Create a managed page from the page bar
-1. Click **+ Add page** at the bottom of the editor.
-2. Enter a unique page name.
-3. Enter a unique route such as `/about`.
-4. Click **Add**.
-VisualBuild creates a page schema entry and a generated file under the
-configured `pagesDir`, normally `src/pages`. The new page becomes active and
-is managed from the canvas.
-### Register an existing React file as a page
-1. Create or select a `.jsx` or `.tsx` file inside the configured `sourceDir`.
-2. Ensure it exports a React component whose returned JSX follows the
-   [supported static contract](#reverse-sync-support-and-limits).
-3. Select the file in **Files**. The Code panel switches to **File**.
-4. Click **Register**.
-5. Choose **Page** in **Register as**.
-6. Enter the page name and route.
-7. Click **Register page**.
-VisualBuild parses the returned static JSX into the page registry, adds the
-page to `visualbuild/pages.json`, and treats the source as a managed page from
-that point onward. Duplicate names and routes are rejected.
-### Page files in the project explorer
-- Renaming or moving a managed page file through VisualBuild updates its
-  `sourcePath`, imports, schema, and selected File view together.
-- External moves are detected and reconciled when VisualBuild can identify
-  the matching file.
-- Deleting a managed page file unregisters that page. VisualBuild restores the
-  file if it is the only registered page, because a project must retain at
-  least one page.
-## Use built-in elements
-The Elements panel contains three main levels:
-- **Global**: Navbar and Footer. These belong to the shared app layout and
-  appear across pages.
-- **Page Blocks**: Hero, Card, Button, Grid, Testimonials, Pricing, Form,
-  Image, Features, Gallery, FAQ, Contact Form, and Login Form.
-- **Primitives**: semantic, layout, text, media, form, table, and interactive
-  HTML elements used for detailed composition.
-Every built-in page block expands to an editable primitive tree. You can
-select nested elements, change their properties, add compatible children,
-reorder them, preview them, and generate normal React source.
-## Create and register custom components
-### Create the source file
-Create a `.jsx` or `.tsx` file inside the app's `src` directory. Files created
-from VisualBuild receive filename-derived component boilerplate automatically.
-For example, `src/components/First.tsx` starts as a valid default-exported
-component.
-A component can contain authored static JSX and an optional `children` slot:
-```tsx
-import type { ReactNode } from 'react'
-export default function First({ children }: { children?: ReactNode }) {
-  return (
-    <section className="w-full rounded-lg p-6">
-      <h2 className="text-2xl font-bold">First component</h2>
-      {children}
-    </section>
-  )
-}
-```
-### Register the component
-1. Select the file in **Files**.
-2. Click **Register** in the Code panel.
-3. Choose **Component** in **Register as**.
-4. Confirm the detected export.
-5. Click **Register component**.
-VisualBuild records the registration in `visualbuild/components.json`. The
-component appears immediately under **Elements > Custom**. Default and named
-exports are supported when they can be detected from the source.
-Do not add registrations to `visualbuild.config.ts`. The project registry file
-is the single registration source used by the editor.
-### Edit and use the registered component
-- Drag or click the component from **Elements > Custom** to add it to a page.
-- Select the component to edit its root tag, ID, Tailwind classes, additional
-  JSON attributes, and registered prop schema.
-- Static JSX authored in the component file appears on the canvas and is
-  selectable.
-- Elements dragged into the custom component become part of the reusable
-  component definition and are written into its source on Save.
-- Selecting the component or one of its definition-owned children opens the
-  component source in the File tab.
-VisualBuild treats these canvas edits as definition edits. If the component is
-used on multiple pages, the updated definition applies everywhere. Generated
-pages import the local source directly and render a self-closing reference such
-as `<First />`; they do not copy the component's internal JSX into every page.
-Registration supplies root tag, ID, Tailwind class, and additional-attribute
-fields. Advanced prop metadata lives in that component's `props` object in
-`visualbuild/components.json`. Supported field types are `string`, `text`,
-`number`, `boolean`, `color`, `select`, `array`, and `attributes`. A custom
-field affects runtime output only when the React component accepts and uses
-the corresponding prop.
-## Use the code panel and larger editor
-The Code panel has several views:
-| View | Purpose | Editable here? |
-| --- | --- | --- |
-| **Page** | Generated source preview for the active page | No |
-| **App** | Generated application entry/router preview | No |
-| **Layout** | Generated shared Navbar/Footer layout preview | No |
-| **JSON** | Current visual schema preview | No |
-| **File** | Exact selected project file | Yes |
-Generated views are useful for understanding and copying output. Use **File**
-when you want to change actual source.
-Selection follows source ownership:
-- Selecting a normal page node opens the active managed page file.
-- Selecting a registered custom component or its internal node opens that
-  custom component file.
-- Selecting a file from **Files** opens that exact file.
-The File tab shows `*` when it has unsaved text. Use **Save file** or
-`Ctrl+S`. The top-bar **Save** is different: it saves canvas/schema state and
-regenerates managed files.
-Click **Open editor** for the full-screen code workspace. It contains a larger
-editable File view and a live project explorer, which is more practical for
-long components and page files. Close it with the `x` button to return to the
-canvas without losing unsaved File text.
-Text files up to 2 MB are editable. Binary files, symbolic links, files outside
-the app root, and oversized files are protected from browser editing.
-## Understand source ownership and synchronization
-VisualBuild is bidirectional only across documented, safe boundaries.
-| Change | Result |
-| --- | --- |
-| Canvas/Properties change, then top-bar **Save** | Writes `pages.json`, regenerates managed pages/App/layout, and synchronizes definition-owned custom component JSX |
-| Managed page source changes in File, VS Code, or another editor | Static returned JSX is parsed into the schema and canvas |
-| Registered custom component source changes | Its static preview, root defaults, and definition tree refresh on the canvas |
-| Generic project file changes | The project explorer and File view refresh; the file is not converted into canvas nodes |
-| Managed page file is renamed or moved | Schema `sourcePath` and generated imports are updated |
-| Managed page file is deleted | The page is unregistered, except the only remaining page is restored |
-### Ownership rules
-- `visualbuild/pages.json` is the safe visual schema boundary.
-- Files listed in `visualbuild/generated-files.json` are generator-managed.
-- Managed page files can be edited visually or through the supported static
-  source importer. A later canvas Save can regenerate them.
-- Registered custom component files remain local React source, but canvas
-  edits to their managed root and definition tree intentionally update those
-  files.
-- Unregistered components and ordinary project files are developer-owned and
-  are never rewritten merely because they exist under `src`.
-- Set `generator.emitApp` or `generator.emitLayout` to `false` when you want to
-  retain developer ownership of those outputs.
-Commit application source, `visualbuild.config.ts`, and the `visualbuild`
-metadata to Git so schema and source changes can be reviewed and recovered.
-## Reverse-sync support and limits
-Reverse sync is intentionally a static JSX importer, not a JavaScript runtime
-or a full React compiler.
-### Supported
-- `.jsx` and `.tsx` managed page files inside the configured source directory.
-- Function and arrow components with a discoverable returned JSX element or
-  fragment.
-- Standard supported HTML tags and registered PascalCase custom components.
-- Recursive static element trees and fragments.
-- Static text.
-- Boolean attributes and static string, number, boolean, `null`, negative
-  number, and expression-free template literal values.
-- `className`, ID, supported component props, and supported plain attributes.
-- The special `{children}` slot used by registered custom component previews.
-### Not supported for source-to-canvas import
-- Unknown or unregistered custom component tags.
-- Member-expression or namespaced tags such as `<UI.Card>`.
-- Spread attributes such as `<div {...props}>`.
-- Runtime JSX expressions such as `{items.map(...)}`, `{condition && ...}`,
-  ternaries, function calls, state-dependent values, or fetched data.
-- Arbitrary hook behavior, event-handler logic, render props, portals, or
-  runtime component factories as visual nodes.
-- Dynamically computed attribute values.
-Unsupported source is not partially imported. VisualBuild displays **Reverse
-sync paused**, keeps the last valid schema, and leaves the edited source file
-untouched. This prevents a best-effort import from silently deleting code.
-You can still keep complex React in developer-owned files. Register only the
-static components that should participate in the visual canvas, or disable a
-generated output and own it entirely in code.
-## Configure VisualBuild
-Each app contains a typed `visualbuild.config.ts`. Every field is optional.
-Restart the builder after changing paths because its file watchers are created
-at startup.
-```ts
-import type { VisualBuildConfig } from './visualbuild/config'
-export default {
-  paths: {
-    sourceDir: 'src',
-    pagesDir: 'src/pages',
-    layoutsDir: 'src/layouts',
-    appFile: 'src/App.tsx',
-    schemaFile: 'visualbuild/pages.json',
-    componentRegistryFile: 'visualbuild/components.json',
-    generatedManifestFile: 'visualbuild/generated-files.json',
-  },
-  editor: {
-    theme: 'default',
-    defaultViewport: 'desktop',
-    responsiveWidths: {
-      mobile: 390,
-      tablet: 768,
-      desktop: 'fluid',
-    },
-    panels: {
-      leftOpen: true,
-      leftTab: 'elements',
-      rightOpen: true,
-      rightTab: 'properties',
-      codeView: 'page',
-    },
-  },
-  generator: {
-    emitApp: true,
-    emitLayout: true,
-    cleanStaleFiles: true,
-  },
-  deployment: {
-    provider: 'vercel',
-    outputDirectory: 'dist',
-    projectName: 'my-app',
-    // teamId: 'team_abc123',
-  },
-} satisfies VisualBuildConfig
-```
-### Configuration reference
-- `paths.sourceDir`: application source boundary.
-- `paths.pagesDir`: default generated page directory.
-- `paths.layoutsDir`: generated shared layout directory.
-- `paths.appFile`: generated app/router path.
-- `paths.schemaFile`: page schema path.
-- `paths.componentRegistryFile`: custom component registry path.
-- `paths.generatedManifestFile`: generated-file ownership manifest.
-- `editor.theme`: `default`, `codex-dark`, `vs-light`, `vs-dark`, or `system`.
-- `editor.defaultViewport`: `mobile`, `tablet`, or `desktop`.
-- `editor.responsiveWidths`: widths from 240 through 4096; desktop may be
-  `fluid`.
-- `editor.panels`: initial open tabs and initial Code view.
-- `generator.emitApp`: whether VisualBuild owns and emits the App file.
-- `generator.emitLayout`: whether VisualBuild owns and emits the shared layout.
-- `generator.cleanStaleFiles`: whether obsolete managed files are removed.
-- `deployment.outputDirectory`: application build output to upload.
-- `deployment.projectName`: stable lowercase Vercel project name.
-- `deployment.teamId`: optional Vercel team identifier beginning with `team_`.
-Paths must stay inside the app. Page, layout, and App paths must remain inside
-`sourceDir`. Invalid values stop builder startup with a focused configuration
-error instead of falling back silently.
-## Use editor themes and responsive previews
-The palette menu offers:
-- VisualBuild Default
-- Codex Dark
-- VS Code Light
-- VS Code Dark
-- System
-The selected theme is stored per project and restored after refresh. The
-configuration theme is the initial fallback until the user selects one.
-Editor theme variables are scoped to editor chrome; they never recolor the
-canvas, generated source, preview, or deployed application.
-Mobile, Tablet, and Desktop use `editor.responsiveWidths`. They change the
-canvas viewport, not the application's generated Tailwind classes.
-## Deploy to Vercel
-VisualBuild performs a production deployment of the developer-owned app. It
-saves and generates source, runs `npm run build` locally, creates a digest
-manifest from the configured static output directory, uploads those files,
-creates a production Vercel deployment, and waits until Vercel reports
-`READY`.
-### Configure credentials
-Create a Vercel access token. Set it only in the terminal that starts the
-builder:
-```powershell
-cd visual-builder
-$env:VERCEL_TOKEN = 'your-token'
-npm.cmd run visual-builder
-```
-For a team-owned project, optionally set:
-```powershell
-$env:VERCEL_TEAM_ID = 'team_abc123'
-```
-You can also enter the Team ID in the deployment dialog. The access token is
-never accepted in project configuration, browser storage, or the dialog.
-On macOS or Linux:
-```bash
-cd visual-builder
-VERCEL_TOKEN='your-token' npm run visual-builder
-```
-### Deploy
-1. Open VisualBuild.
-2. Click **Deploy**.
-3. Review the lowercase Vercel project name.
-4. Leave Team ID blank for a personal account, or provide the owning team ID.
-5. Click **Deploy production**.
-6. Wait for `READY` and open the returned production URL.
-Only the configured static output, normally `dist`, is uploaded. VisualBuild
-rejects builder, metadata, config, dependency, Git, symlink, and other
-builder-only paths at the deployment boundary. A virtual SPA fallback is added
-to the deployment without modifying application source.
-The following never enter the production upload:
-- `visual-builder`
-- `visual-app-builder`
-- `visualbuild`
-- `visualbuild.config.*`
-- `node_modules`
-- `.git`
-- `.vercel`
-- the Vercel access token
-## Generate and build without the editor
-Generate managed source from the schema without opening the browser:
-```powershell
-cd visual-builder
-npm.cmd run vb:generate
-```
-Build the deployable application independently:
-```powershell
-cd ..\my-app
-npm.cmd run build
-```
-This independence is the quickest way to verify the production boundary: the
-app build must succeed using only the app package and its dependencies.
-## Upcoming versions
-The features in this section are planned roadmap items, not capabilities in
-the current v1 release. Their final scope and release order may change as the
-implementation is validated.
-### v1.1: application package installation interface
-VisualBuild will add an editor interface for finding, installing, updating,
-and removing npm packages used by the developer-owned application. Package
-operations will target the application workspace and its `package.json`; they
-will not add editor-only packages to the production application.
-This is different from installing the `create-visualbuild-app` CLI itself and
-from publishing VisualBuild to npm. It is package management for the React
-application being built. This interface is a new addition to the current
-roadmap; the locked PRD's original v1.1 item was Vercel deployment, which is
-already available in the current v1 implementation.
-### v2: generated-application state management setup
-VisualBuild will offer setup flows for application state management with
-Zustand and Redux. The generated stores, providers, hooks, and configuration
-will belong to the developer's application and remain usable without a
-VisualBuild runtime.
-VisualBuild already uses Zustand internally for editor state. That internal
-implementation is separate from the planned v2 feature, which configures
-state management in the generated application. Redux support and this
-generated-application setup flow are additions to the current roadmap rather
-than features specified by the locked PRD.
-### v2: AI help
-VisualBuild will introduce contextual AI help for building and understanding
-the project. The v2 scope is assistance inside the existing visual-and-code
-workflow, such as explaining errors, suggesting edits, and helping configure
-components. AI changes must remain reviewable and must produce ordinary
-developer-owned project files.
-The PRD also describes a later, broader AI-native phase: natural-language page
-generation, AI-assisted layout generation, and generation through the project
-schema. That full generation workflow remains a later roadmap item rather
-than part of the initial v2 AI-help scope.
-### Additional PRD roadmap items
-The longer-term PRD also identifies these directions:
-- data and authentication integration, including protected routes;
-- a component marketplace and publishing developer components;
-- team collaboration through shared project state;
-- full natural-language-to-project generation and AI layout suggestions;
-- multi-framework output such as Vue, Svelte, and Solid; and
-- a VisualBuild experience integrated into VS Code.
-Some PRD milestones have already been delivered earlier than originally
-planned in this repository, including Vercel deployment, local custom component
-registration, drag and drop, editor themes, and limited reverse sync. They are
-documented as current v1 features elsewhere in this guide and are therefore
-not repeated as upcoming work.
-## Recover from errors and conflicts
-### Reverse sync paused
-The edited managed source contains unsupported or invalid JSX. The file is not
-overwritten and the last valid schema remains active.
-1. Read the notice for the unsupported tag or attribute.
-2. Fix the file so its returned JSX matches the static contract, or move the
-   dynamic behavior to a developer-owned component.
-3. Save the file again and wait for **Source synced**.
-### Source changed while the canvas has unsaved edits
-VisualBuild does not choose a winner automatically.
-- Click **Load source changes** to discard unsaved canvas state and import the
-  source version.
-- Dismiss the notice to keep working from the canvas state. A later top-bar
-  Save regenerates managed source from that canvas/schema state.
-### File changed while the File editor has unsaved text
-VisualBuild preserves the browser text and displays **Reload disk**.
-- Click **Reload disk** to discard browser edits and load the external file.
-- Keep editing and use **Save file** to make the browser version the file
-  version.
-### Generation failed during Save
-Schema writes are transactional. VisualBuild restores the previous
-`pages.json` and regenerates the last valid managed source. Read the diagnostic,
-fix the duplicate route, invalid schema, or reported source issue, and save
-again.
-### Rename or move failed
-Managed file moves update filesystem paths, schema paths, and imports as one
-operation. If persistence or generation fails, VisualBuild rolls the move back.
-Refresh the project tree, resolve the reported conflict, and retry.
-### Deployment failed
-The deployment dialog shows whether failure occurred during local generation,
-the app build, file upload, deployment creation, or Vercel processing. The
-last successful production deployment stays live.
-Check:
-1. The builder was started after `VERCEL_TOKEN` was set.
-2. App dependencies are installed.
-3. `npm run build` succeeds in the app directory.
-4. `deployment.outputDirectory` matches the build output.
-5. Project name is lowercase and valid.
-6. Team ID and token belong to the same Vercel scope.
-## Troubleshooting
-### Deploy is disabled
-Stop the builder, set `VERCEL_TOKEN` in that same terminal, and restart it.
-### A newly created test app does not contain recent local changes
-Scaffolds copy the current editor into `visual-builder`. An existing scaffold
-does not update when the framework repository changes. Create a fresh scaffold
-when validating unpublished framework changes.
-### A custom component is not in Elements
-- Confirm the file is `.jsx` or `.tsx` under `sourceDir`.
-- Confirm it has a detectable default or named React component export.
-- Select the file and use **Register > Component**.
-- Check `visualbuild/components.json` for the saved registration.
-### A custom component's source content is not visible on the canvas
-Keep the returned JSX static and supported. Runtime expressions are not
-rendered as visual nodes. An optional `{children}` position is recognized as
-the drop location for definition-owned children.
-### Page source does not update the canvas
-Confirm the file is registered as a page, then check the reverse-sync notice.
-Unregistered generic files refresh in the File editor but are not imported
-into the page schema.
-### File edits and canvas edits appear to disagree
-Check which Save action you used:
-- **Save file** writes the File editor buffer.
-- Top-bar **Save** writes canvas/schema state and regenerates managed files.
-Use the conflict notice to choose which side should become authoritative.
-## Development and release verification
-From the framework repository:
-```powershell
-npm.cmd install
-npm.cmd test
-npm.cmd run lint
-npm.cmd run build
-npm.cmd run validate:release
-npm.cmd pack --dry-run
-```
-The release validator creates an isolated workspace, scaffolds both projects,
-installs their dependencies, generates source, lints both projects, builds both
-projects, and verifies that builder-only files cannot enter the deployable
-output.
-## Package and support
-- npm: [create-visualbuild-app](https://www.npmjs.com/package/create-visualbuild-app)
-- source: [LORD-JINXXX/builder-app](https://github.com/LORD-JINXXX/builder-app)
-- issues: [GitHub Issues](https://github.com/LORD-JINXXX/builder-app/issues)
-- complete scaffold guide: [docs/user-guide.md](docs/user-guide.md)
-## License
-UNLICENSED
+# VisualBuild
+[![npm version](https://img.shields.io/npm/v/create-visualbuild-app.svg)](https://www.npmjs.com/package/create-visualbuild-app)
+[![GitHub source](https://img.shields.io/badge/GitHub-source-181717?logo=github)](https://github.com/LORD-JINXXX/builder-app)
+VisualBuild is a local visual development framework for building React and
+Tailwind applications with drag and drop while retaining normal, editable
+source code. It combines a component library, recursive canvas, properties
+editor, responsive preview, project explorer, source editor, generator, and
+safe source-to-canvas synchronization in one workflow.
+VisualBuild is not a runtime that must be shipped with the application. The
+result is an ordinary React/Vite project: developers own its files, can edit
+them in any code editor, commit them to Git, build them without the visual
+editor, and deploy the generated application independently.
+## Why VisualBuild was created
+Visual development tools are fast for composing interfaces, but many make the
+tool's private format or runtime the permanent owner of the application.
+Traditional code-first development gives developers full ownership, but
+repetitive layout construction and styling can slow early product work.
+VisualBuild was created to bridge those two workflows:
+- use a visual canvas for the work that is naturally visual;
+- generate readable React source instead of hiding the result;
+- keep the developer-owned application separate from editor tooling;
+- make ownership explicit so the editor never silently replaces arbitrary
+  files;
+- support safe two-way synchronization for a documented static JSX/TSX subset;
+- provide direct code-editing escape hatches when visual controls are not
+  enough;
+- keep the production application free of a VisualBuild runtime dependency.
+The central idea is **visual speed without surrendering source ownership**.
+VisualBuild deliberately does not claim that every possible React program can
+be reconstructed visually. Dynamic application logic stays in normal
+developer-owned components, while the visual system manages the static
+structure it can understand safely.
+## Architecture
+VisualBuild is schema-driven, registry-powered, and code-generating. Its
+architecture separates the deployable application from the local editor and
+uses explicit boundaries for state, source ownership, synchronization, and
+deployment.
+### Workspace boundary
+```text
+workspace/
+  my-app/                 developer-owned React application
+    src/                  real application source
+    visualbuild/          schema, component registry, ownership metadata
+    visualbuild.config.ts typed project configuration
+    package.json          application dependencies only
+  visual-builder/         optional local development tool
+    visual-app-builder/   canvas and editor interface
+    scripts/              generator and launch commands
+    package.json          editor-only dependencies
+```
+The application and editor have independent dependency trees. Drag-and-drop,
+editor state, parsing, and generator dependencies belong to
+`visual-builder/`; they do not enter the application's production dependency
+graph.
+### Forward visual-to-code flow
+```text
+Elements panel + Canvas + Properties
+                 |
+                 v
+       Recursive VisualNode tree
+                 |
+                 v
+       visualbuild/pages.json
+                 |
+        Component registries
+                 |
+                 v
+        Babel AST code generator
+                 |
+                 v
+  React pages, App, layout, and imports
+                 |
+                 v
+       Standard Vite application
+```
+1. Built-in elements and presets come from registries that define their label,
+   category, editable defaults, canvas rendering contract, and generated
+   structure.
+2. Dragging or editing an element changes a recursive `VisualNode` tree in the
+   editor.
+3. Top-bar **Save** persists that tree to `visualbuild/pages.json`, the
+   canonical state for canvas-managed pages.
+4. The generator combines schema data, registered custom-component metadata,
+   and project configuration.
+5. Babel AST generation writes deterministic React source rather than
+   concatenating fragile JSX strings.
+6. The generated app runs with Vite and does not import a VisualBuild runtime.
+The canvas and generated source are two views of the same managed structure:
+the canvas is optimized for composition, while the source files remain useful
+to developers and normal tooling.
+### Component registry architecture
+VisualBuild has two related registry paths:
+- **Built-in registry:** HTML primitives and page-block presets expand into
+  editable node trees. A preset is not an opaque screenshot; its nested
+  headings, text, links, images, containers, classes, IDs, and attributes can
+  be selected and edited.
+- **Custom-component registry:** a local `.jsx` or `.tsx` file is registered
+  in `visualbuild/components.json` with its export, source path, editor label,
+  and editable props. Generated pages import that local component directly.
+Registered custom components keep their implementation in the developer's
+application. VisualBuild adds no runtime wrapper. Definition-owned static JSX
+is selectable on the canvas, and elements dropped into the definition are
+written back to the component source. Pages reuse the definition with imports
+and self-closing component instances.
+### Safe reverse synchronization
+```text
+Supported static JSX/TSX edit
+             |
+          Watcher
+             |
+             v
+        Babel parser
+             |
+   Static-contract validation
+             |
+   Stable node-ID reconciliation
+             |
+             v
+  pages.json and the visual canvas
+```
+The file watcher observes managed pages and registered custom components.
+Supported static JSX/TSX can be parsed, validated, reconciled with existing
+node IDs, and reflected back into the canvas. Equivalent formatting changes do
+not rewrite the schema.
+Hooks, runtime expressions, conditional rendering, mapped collections, spread
+props, and other arbitrary behavior are outside this importer contract. When
+source is unsupported, VisualBuild pauses reverse sync, preserves the source
+file and last valid schema, and reports a diagnostic instead of guessing or
+overwriting code.
+### Source ownership
+VisualBuild treats ownership as a safety rule:
+| Source | Owner | Visual behavior |
+| --- | --- | --- |
+| Managed page source | Canvas/schema | Top-bar Save regenerates it; supported static edits can reverse-sync |
+| Registered custom component | Component definition | Root, props, and definition children update its local source |
+| Generic project file | Developer | Editable in File mode; never regenerated merely because it exists |
+| App and layout outputs | Configuration-dependent | Generated only when their generation switches are enabled |
+| Schema and registry metadata | VisualBuild | Stores page state, registration, and ownership information |
+Generated-file metadata lets the generator update or remove only files it
+owns. Unregistered developer files are preserved.
+### Editor state and Save semantics
+The editor keeps immediate canvas state locally so drag, reorder, selection,
+and property changes feel responsive.
+- Top-bar **Save** commits canvas/schema state and regenerates managed source.
+- **Save file** writes the exact File-editor buffer.
+- External file changes refresh clean buffers.
+- If canvas or File mode contains unsaved work, VisualBuild shows an explicit
+  conflict choice instead of selecting a winner silently.
+- Generation and managed move operations use rollback behavior when a write
+  fails.
+### Preview and code workspace
+The responsive canvas renders the editable node tree at mobile, tablet, and
+desktop widths. Preview removes editor chrome without changing application
+styles. The Code panel exposes generated Page, App, Layout, and JSON views,
+while File mode and the larger code workspace edit the exact selected source
+file.
+Editor themes are scoped to the editor interface. They do not recolor the
+canvas content, generated application, or production build.
+### Production and deployment boundary
+VisualBuild's Vercel workflow saves and generates locally, runs the
+developer-owned application's production build, audits the output, and uploads
+only the configured static build directory.
+It excludes the editor source, `visual-builder/`, `visualbuild/`,
+`node_modules/`, project configuration, and credentials. The Vercel token
+stays in the local builder process and is never written to generated source or
+browser storage.
+## Public CLI
+### Requirements
+- Node.js and npm.
+- A terminal. The examples use PowerShell and `npm.cmd` on Windows. On macOS
+  or Linux, use `npm` in the same commands.
+- A modern browser.
+- A Vercel account and access token only if you want one-click deployment.
+The examples use `my-app` as the application folder. Replace it with the name
+you supplied to the create command.
+### Create a project
+Create a named project from the public package:
+```powershell
+npm create visualbuild-app@latest my-app
+```
+The equivalent `npx` command is:
+```powershell
+npx create-visualbuild-app@latest my-app
+```
+If you omit the name, VisualBuild creates `my-app`:
+```powershell
+npm create visualbuild-app@latest
+```
+Maintainers testing an unpublished local checkout can run this from an empty
+folder:
+```powershell
+npm.cmd --prefix "D:\path\to\builder-app" run create-visualbuild-app -- my-app
+```
+The command creates two sibling projects. It does not install dependencies.
+## Scaffold output
+```text
+workspace/
+  my-app/                    deployable React application
+    src/                     application source
+    visualbuild/             schema, registry, and ownership metadata
+      pages.json             visual page schema
+      components.json        registered custom components and prop metadata
+      generated-files.json   files managed by the generator
+    visualbuild.config.ts    typed project configuration
+    package.json             application dependencies only
+  visual-builder/            optional local editor and generator
+    visual-app-builder/      VisualBuild interface and local API
+    scripts/                 editor and generation commands
+    package.json             editor-only dependencies
+  my-app-README.md           workspace-specific quick start
+  VISUALBUILD-GUIDE.md       a copy of this complete guide
+```
+The separation is a production boundary, not only an organizational choice:
+| Location | Owner and purpose | Deploy it? |
+| --- | --- | --- |
+| `my-app/src` | Real React application source | Yes |
+| `my-app/visualbuild` | VisualBuild schema, registry, and generation metadata | No runtime requirement |
+| `my-app/visualbuild.config.ts` | Local editor/generator configuration | No runtime requirement |
+| `visual-builder` | Visual editor, watcher, generator, and editor-only dependencies | No |
+The app does not install drag-and-drop, editor state, or generator packages.
+It remains runnable after the sibling `visual-builder` directory is removed.
+## Run a generated project
+Open the first terminal in the workspace root, then install and run the
+application:
+```powershell
+cd my-app
+npm.cmd install
+npm.cmd run dev
+```
+Open a separate second terminal in the workspace root, then install and run
+the visual editor:
+```powershell
+cd visual-builder
+npm.cmd install
+npm.cmd run visual-builder
+```
+If the second terminal opens inside `my-app` instead of the workspace root,
+use this path to reach the sibling editor:
+```powershell
+cd ..\visual-builder
+```
+Do not run both development processes sequentially in one occupied terminal.
+Use two terminals so the app and VisualBuild can remain running together. If
+you stop the app and reuse its terminal, then `cd ..\visual-builder` is the
+correct command because that terminal is still inside `my-app`.
+The app normally uses Vite's development URL. VisualBuild opens at:
+```text
+http://127.0.0.1:7371
+```
+Keep the builder terminal open while editing. It runs the file watcher,
+generation API, reverse-sync importer, and optional deployment service.
+## Complete user guide
+The preceding sections explain the product, architecture, installation,
+workspace, and startup flow. The sections below complete the self-contained v1
+guide for using every major VisualBuild workflow.
+1. [Understand the interface](#understand-the-interface)
+2. [Build and edit a page](#build-and-edit-a-page)
+3. [Create and register pages](#create-and-register-pages)
+4. [Use built-in elements](#use-built-in-elements)
+5. [Create and register custom components](#create-and-register-custom-components)
+6. [Use the code panel and larger editor](#use-the-code-panel-and-larger-editor)
+7. [Understand source ownership and synchronization](#understand-source-ownership-and-synchronization)
+8. [Reverse-sync support and limits](#reverse-sync-support-and-limits)
+9. [Configure VisualBuild](#configure-visualbuild)
+10. [Use editor themes and responsive previews](#use-editor-themes-and-responsive-previews)
+11. [Deploy to Vercel](#deploy-to-vercel)
+12. [Generate and build without the editor](#generate-and-build-without-the-editor)
+13. [Upcoming versions](#upcoming-versions)
+14. [Recover from errors and conflicts](#recover-from-errors-and-conflicts)
+15. [Troubleshooting](#troubleshooting)
+## Understand the interface
+### Top bar
+- **Preview** hides editor panels and displays the active page as the user
+  will see it.
+- **Code** opens or closes the right Code panel.
+- The palette button changes the editor theme only.
+- **Save** writes the visual schema and regenerates managed source.
+- **Deploy** builds the developer-owned app and publishes its static output to
+  Vercel.
+### Left panel
+- **Files** is the project explorer. Create, select, rename, move, and delete
+  files or folders here.
+- **Elements** contains global elements, registered custom components,
+  reusable page blocks, and HTML primitives grouped by category.
+- Collapse the panel with its arrow when more canvas space is needed.
+### Canvas and page bar
+- Drag elements from the Elements panel onto insertion zones.
+- Click an element to add it to the selected container. If no valid container
+  is selected, drag it to the desired insertion zone.
+- Select a canvas node to show its controls and Properties.
+- Drag selected nodes to reorder or nest them in compatible containers.
+- Use **Mobile**, **Tablet**, and **Desktop** above the canvas to test the
+  configured responsive widths.
+- Use the page bar along the bottom to switch pages, add a page, or delete a
+  page when more than one exists.
+### Right panel
+- **Properties** edits the selected node's text, ID, component fields,
+  Tailwind classes, arrays, booleans, select values, and supported additional
+  attributes.
+- Selecting the page root exposes **Page root tag**, allowing `div`, `main`,
+  `section`, `article`, `header`, `footer`, `nav`, `aside`, or `form`.
+- Registered custom components expose their managed component root tag, ID,
+  Tailwind classes, additional attributes, and configured prop fields.
+- **Code** shows generated views and the editable source file associated with
+  the current selection.
+- Collapse the panel with its arrow when more canvas space is needed.
+## Build and edit a page
+1. Open **Elements**.
+2. Drag a reusable page block, such as Hero, Grid, or Pricing, onto the canvas.
+3. Select the block or one of its nested elements.
+4. Open **Properties** and edit its text, values, ID, or Tailwind classes.
+5. Drag primitives such as `h2`, `p`, `button`, `section`, or `div` into a
+   compatible insertion zone.
+6. Reorder a node with its drag handle or move it upward with the canvas
+   control.
+7. Select the page root to change its semantic root tag and root classes.
+8. Switch between Mobile, Tablet, and Desktop.
+9. Click **Preview** to inspect the page without editor chrome.
+10. Click **Save** to persist the schema and generated React source.
+Tailwind changes are stored as ordinary `className` strings. The class editor
+offers suggestions as you type; variants such as `sm:`, `hover:`, and `focus:`
+remain part of the generated source. Editor themes never modify these classes.
+## Create and register pages
+VisualBuild supports two page workflows.
+### Create a managed page from the page bar
+1. Click **+ Add page** at the bottom of the editor.
+2. Enter a unique page name.
+3. Enter a unique route such as `/about`.
+4. Click **Add**.
+VisualBuild creates a page schema entry and a generated file under the
+configured `pagesDir`, normally `src/pages`. The new page becomes active and
+is managed from the canvas.
+### Register an existing React file as a page
+1. Create or select a `.jsx` or `.tsx` file inside the configured `sourceDir`.
+2. Ensure it exports a React component whose returned JSX follows the
+   [supported static contract](#reverse-sync-support-and-limits).
+3. Select the file in **Files**. The Code panel switches to **File**.
+4. Click **Register**.
+5. Choose **Page** in **Register as**.
+6. Enter the page name and route.
+7. Click **Register page**.
+VisualBuild parses the returned static JSX into the page registry, adds the
+page to `visualbuild/pages.json`, and treats the source as a managed page from
+that point onward. Duplicate names and routes are rejected.
+### Page files in the project explorer
+- Renaming or moving a managed page file through VisualBuild updates its
+  `sourcePath`, imports, schema, and selected File view together.
+- External moves are detected and reconciled when VisualBuild can identify
+  the matching file.
+- Deleting a managed page file unregisters that page. VisualBuild restores the
+  file if it is the only registered page, because a project must retain at
+  least one page.
+## Use built-in elements
+The Elements panel contains three main levels:
+- **Global**: Navbar and Footer. These belong to the shared app layout and
+  appear across pages.
+- **Page Blocks**: Hero, Card, Button, Grid, Testimonials, Pricing, Form,
+  Image, Features, Gallery, FAQ, Contact Form, and Login Form.
+- **Primitives**: semantic, layout, text, media, form, table, and interactive
+  HTML elements used for detailed composition.
+Every built-in page block expands to an editable primitive tree. You can
+select nested elements, change their properties, add compatible children,
+reorder them, preview them, and generate normal React source.
+## Create and register custom components
+### Create the source file
+Create a `.jsx` or `.tsx` file inside the app's `src` directory. Files created
+from VisualBuild receive filename-derived component boilerplate automatically.
+For example, `src/components/First.tsx` starts as a valid default-exported
+component.
+A component can contain authored static JSX and an optional `children` slot:
+```tsx
+import type { ReactNode } from 'react'
+export default function First({ children }: { children?: ReactNode }) {
+  return (
+    <section className="w-full rounded-lg p-6">
+      <h2 className="text-2xl font-bold">First component</h2>
+      {children}
+    </section>
+  )
+}
+```
+### Register the component
+1. Select the file in **Files**.
+2. Click **Register** in the Code panel.
+3. Choose **Component** in **Register as**.
+4. Confirm the detected export.
+5. Click **Register component**.
+VisualBuild records the registration in `visualbuild/components.json`. The
+component appears immediately under **Elements > Custom**. Default and named
+exports are supported when they can be detected from the source.
+Do not add registrations to `visualbuild.config.ts`. The project registry file
+is the single registration source used by the editor.
+### Edit and use the registered component
+- Drag or click the component from **Elements > Custom** to add it to a page.
+- Select the component to edit its root tag, ID, Tailwind classes, additional
+  JSON attributes, and registered prop schema.
+- Static JSX authored in the component file appears on the canvas and is
+  selectable.
+- Elements dragged into the custom component become part of the reusable
+  component definition and are written into its source on Save.
+- Selecting the component or one of its definition-owned children opens the
+  component source in the File tab.
+VisualBuild treats these canvas edits as definition edits. If the component is
+used on multiple pages, the updated definition applies everywhere. Generated
+pages import the local source directly and render a self-closing reference such
+as `<First />`; they do not copy the component's internal JSX into every page.
+Registration supplies root tag, ID, Tailwind class, and additional-attribute
+fields. Advanced prop metadata lives in that component's `props` object in
+`visualbuild/components.json`. Supported field types are `string`, `text`,
+`number`, `boolean`, `color`, `select`, `array`, and `attributes`. A custom
+field affects runtime output only when the React component accepts and uses
+the corresponding prop.
+## Use the code panel and larger editor
+The Code panel has several views:
+| View | Purpose | Editable here? |
+| --- | --- | --- |
+| **Page** | Generated source preview for the active page | No |
+| **App** | Generated application entry/router preview | No |
+| **Layout** | Generated shared Navbar/Footer layout preview | No |
+| **JSON** | Current visual schema preview | No |
+| **File** | Exact selected project file | Yes |
+Generated views are useful for understanding and copying output. Use **File**
+when you want to change actual source.
+Selection follows source ownership:
+- Selecting a normal page node opens the active managed page file.
+- Selecting a registered custom component or its internal node opens that
+  custom component file.
+- Selecting a file from **Files** opens that exact file.
+The File tab shows `*` when it has unsaved text. Use **Save file** or
+`Ctrl+S`. The top-bar **Save** is different: it saves canvas/schema state and
+regenerates managed files.
+Click **Open editor** for the full-screen code workspace. It contains a larger
+editable File view and a live project explorer, which is more practical for
+long components and page files. Close it with the `x` button to return to the
+canvas without losing unsaved File text.
+Text files up to 2 MB are editable. Binary files, symbolic links, files outside
+the app root, and oversized files are protected from browser editing.
+## Understand source ownership and synchronization
+VisualBuild is bidirectional only across documented, safe boundaries.
+| Change | Result |
+| --- | --- |
+| Canvas/Properties change, then top-bar **Save** | Writes `pages.json`, regenerates managed pages/App/layout, and synchronizes definition-owned custom component JSX |
+| Managed page source changes in File, VS Code, or another editor | Static returned JSX is parsed into the schema and canvas |
+| Registered custom component source changes | Its static preview, root defaults, and definition tree refresh on the canvas |
+| Generic project file changes | The project explorer and File view refresh; the file is not converted into canvas nodes |
+| Managed page file is renamed or moved | Schema `sourcePath` and generated imports are updated |
+| Managed page file is deleted | The page is unregistered, except the only remaining page is restored |
+### Ownership rules
+- `visualbuild/pages.json` is the safe visual schema boundary.
+- Files listed in `visualbuild/generated-files.json` are generator-managed.
+- Managed page files can be edited visually or through the supported static
+  source importer. A later canvas Save can regenerate them.
+- Registered custom component files remain local React source, but canvas
+  edits to their managed root and definition tree intentionally update those
+  files.
+- Unregistered components and ordinary project files are developer-owned and
+  are never rewritten merely because they exist under `src`.
+- Set `generator.emitApp` or `generator.emitLayout` to `false` when you want to
+  retain developer ownership of those outputs.
+Commit application source, `visualbuild.config.ts`, and the `visualbuild`
+metadata to Git so schema and source changes can be reviewed and recovered.
+## Reverse-sync support and limits
+Reverse sync is intentionally a static JSX importer, not a JavaScript runtime
+or a full React compiler.
+### Supported
+- `.jsx` and `.tsx` managed page files inside the configured source directory.
+- Function and arrow components with a discoverable returned JSX element or
+  fragment.
+- Standard supported HTML tags and registered PascalCase custom components.
+- Recursive static element trees and fragments.
+- Static text.
+- Boolean attributes and static string, number, boolean, `null`, negative
+  number, and expression-free template literal values.
+- `className`, ID, supported component props, and supported plain attributes.
+- The special `{children}` slot used by registered custom component previews.
+### Not supported for source-to-canvas import
+- Unknown or unregistered custom component tags.
+- Member-expression or namespaced tags such as `<UI.Card>`.
+- Spread attributes such as `<div {...props}>`.
+- Runtime JSX expressions such as `{items.map(...)}`, `{condition && ...}`,
+  ternaries, function calls, state-dependent values, or fetched data.
+- Arbitrary hook behavior, event-handler logic, render props, portals, or
+  runtime component factories as visual nodes.
+- Dynamically computed attribute values.
+Unsupported source is not partially imported. VisualBuild displays **Reverse
+sync paused**, keeps the last valid schema, and leaves the edited source file
+untouched. This prevents a best-effort import from silently deleting code.
+You can still keep complex React in developer-owned files. Register only the
+static components that should participate in the visual canvas, or disable a
+generated output and own it entirely in code.
+## Configure VisualBuild
+Each app contains a typed `visualbuild.config.ts`. Every field is optional.
+Restart the builder after changing paths because its file watchers are created
+at startup.
+```ts
+import type { VisualBuildConfig } from './visualbuild/config'
+export default {
+  paths: {
+    sourceDir: 'src',
+    pagesDir: 'src/pages',
+    layoutsDir: 'src/layouts',
+    appFile: 'src/App.tsx',
+    schemaFile: 'visualbuild/pages.json',
+    componentRegistryFile: 'visualbuild/components.json',
+    generatedManifestFile: 'visualbuild/generated-files.json',
+  },
+  editor: {
+    theme: 'default',
+    defaultViewport: 'desktop',
+    responsiveWidths: {
+      mobile: 390,
+      tablet: 768,
+      desktop: 'fluid',
+    },
+    panels: {
+      leftOpen: true,
+      leftTab: 'elements',
+      rightOpen: true,
+      rightTab: 'properties',
+      codeView: 'page',
+    },
+  },
+  generator: {
+    emitApp: true,
+    emitLayout: true,
+    cleanStaleFiles: true,
+  },
+  deployment: {
+    provider: 'vercel',
+    outputDirectory: 'dist',
+    projectName: 'my-app',
+    // teamId: 'team_abc123',
+  },
+} satisfies VisualBuildConfig
+```
+### Configuration reference
+- `paths.sourceDir`: application source boundary.
+- `paths.pagesDir`: default generated page directory.
+- `paths.layoutsDir`: generated shared layout directory.
+- `paths.appFile`: generated app/router path.
+- `paths.schemaFile`: page schema path.
+- `paths.componentRegistryFile`: custom component registry path.
+- `paths.generatedManifestFile`: generated-file ownership manifest.
+- `editor.theme`: `default`, `codex-dark`, `vs-light`, `vs-dark`, or `system`.
+- `editor.defaultViewport`: `mobile`, `tablet`, or `desktop`.
+- `editor.responsiveWidths`: widths from 240 through 4096; desktop may be
+  `fluid`.
+- `editor.panels`: initial open tabs and initial Code view.
+- `generator.emitApp`: whether VisualBuild owns and emits the App file.
+- `generator.emitLayout`: whether VisualBuild owns and emits the shared layout.
+- `generator.cleanStaleFiles`: whether obsolete managed files are removed.
+- `deployment.outputDirectory`: application build output to upload.
+- `deployment.projectName`: stable lowercase Vercel project name.
+- `deployment.teamId`: optional Vercel team identifier beginning with `team_`.
+Paths must stay inside the app. Page, layout, and App paths must remain inside
+`sourceDir`. Invalid values stop builder startup with a focused configuration
+error instead of falling back silently.
+## Use editor themes and responsive previews
+The palette menu offers:
+- VisualBuild Default
+- Codex Dark
+- VS Code Light
+- VS Code Dark
+- System
+The selected theme is stored per project and restored after refresh. The
+configuration theme is the initial fallback until the user selects one.
+Editor theme variables are scoped to editor chrome; they never recolor the
+canvas, generated source, preview, or deployed application.
+Mobile, Tablet, and Desktop use `editor.responsiveWidths`. They change the
+canvas viewport, not the application's generated Tailwind classes.
+## Deploy to Vercel
+VisualBuild performs a production deployment of the developer-owned app. It
+saves and generates source, runs `npm run build` locally, creates a digest
+manifest from the configured static output directory, uploads those files,
+creates a production Vercel deployment, and waits until Vercel reports
+`READY`.
+### Configure credentials
+Create a Vercel access token. Set it only in the terminal that starts the
+builder:
+```powershell
+cd visual-builder
+$env:VERCEL_TOKEN = 'your-token'
+npm.cmd run visual-builder
+```
+For a team-owned project, optionally set:
+```powershell
+$env:VERCEL_TEAM_ID = 'team_abc123'
+```
+You can also enter the Team ID in the deployment dialog. The access token is
+never accepted in project configuration, browser storage, or the dialog.
+On macOS or Linux:
+```bash
+cd visual-builder
+VERCEL_TOKEN='your-token' npm run visual-builder
+```
+### Deploy
+1. Open VisualBuild.
+2. Click **Deploy**.
+3. Review the lowercase Vercel project name.
+4. Leave Team ID blank for a personal account, or provide the owning team ID.
+5. Click **Deploy production**.
+6. Wait for `READY` and open the returned production URL.
+Only the configured static output, normally `dist`, is uploaded. VisualBuild
+rejects builder, metadata, config, dependency, Git, symlink, and other
+builder-only paths at the deployment boundary. A virtual SPA fallback is added
+to the deployment without modifying application source.
+The following never enter the production upload:
+- `visual-builder`
+- `visual-app-builder`
+- `visualbuild`
+- `visualbuild.config.*`
+- `node_modules`
+- `.git`
+- `.vercel`
+- the Vercel access token
+## Generate and build without the editor
+Generate managed source from the schema without opening the browser:
+```powershell
+cd visual-builder
+npm.cmd run vb:generate
+```
+Build the deployable application independently:
+```powershell
+cd ..\my-app
+npm.cmd run build
+```
+This independence is the quickest way to verify the production boundary: the
+app build must succeed using only the app package and its dependencies.
+## Upcoming versions
+The features in this section are planned roadmap items, not capabilities in
+the current v1 release. Their final scope and release order may change as the
+implementation is validated.
+### v1.1: application package installation interface
+VisualBuild will add an editor interface for finding, installing, updating,
+and removing npm packages used by the developer-owned application. Package
+operations will target the application workspace and its `package.json`; they
+will not add editor-only packages to the production application.
+This is different from installing the `create-visualbuild-app` CLI itself and
+from publishing VisualBuild to npm. It is package management for the React
+application being built. This interface is a new addition to the current
+roadmap; the locked PRD's original v1.1 item was Vercel deployment, which is
+already available in the current v1 implementation.
+### v2: generated-application state management setup
+VisualBuild will offer setup flows for application state management with
+Zustand and Redux. The generated stores, providers, hooks, and configuration
+will belong to the developer's application and remain usable without a
+VisualBuild runtime.
+VisualBuild already uses Zustand internally for editor state. That internal
+implementation is separate from the planned v2 feature, which configures
+state management in the generated application. Redux support and this
+generated-application setup flow are additions to the current roadmap rather
+than features specified by the locked PRD.
+### v2: AI help
+VisualBuild will introduce contextual AI help for building and understanding
+the project. The v2 scope is assistance inside the existing visual-and-code
+workflow, such as explaining errors, suggesting edits, and helping configure
+components. AI changes must remain reviewable and must produce ordinary
+developer-owned project files.
+The PRD also describes a later, broader AI-native phase: natural-language page
+generation, AI-assisted layout generation, and generation through the project
+schema. That full generation workflow remains a later roadmap item rather
+than part of the initial v2 AI-help scope.
+### Additional PRD roadmap items
+The longer-term PRD also identifies these directions:
+- data and authentication integration, including protected routes;
+- a component marketplace and publishing developer components;
+- team collaboration through shared project state;
+- full natural-language-to-project generation and AI layout suggestions;
+- multi-framework output such as Vue, Svelte, and Solid; and
+- a VisualBuild experience integrated into VS Code.
+Some PRD milestones have already been delivered earlier than originally
+planned in this repository, including Vercel deployment, local custom component
+registration, drag and drop, editor themes, and limited reverse sync. They are
+documented as current v1 features elsewhere in this guide and are therefore
+not repeated as upcoming work.
+## Recover from errors and conflicts
+### Reverse sync paused
+The edited managed source contains unsupported or invalid JSX. The file is not
+overwritten and the last valid schema remains active.
+1. Read the notice for the unsupported tag or attribute.
+2. Fix the file so its returned JSX matches the static contract, or move the
+   dynamic behavior to a developer-owned component.
+3. Save the file again and wait for **Source synced**.
+### Source changed while the canvas has unsaved edits
+VisualBuild does not choose a winner automatically.
+- Click **Load source changes** to discard unsaved canvas state and import the
+  source version.
+- Dismiss the notice to keep working from the canvas state. A later top-bar
+  Save regenerates managed source from that canvas/schema state.
+### File changed while the File editor has unsaved text
+VisualBuild preserves the browser text and displays **Reload disk**.
+- Click **Reload disk** to discard browser edits and load the external file.
+- Keep editing and use **Save file** to make the browser version the file
+  version.
+### Generation failed during Save
+Schema writes are transactional. VisualBuild restores the previous
+`pages.json` and regenerates the last valid managed source. Read the diagnostic,
+fix the duplicate route, invalid schema, or reported source issue, and save
+again.
+### Rename or move failed
+Managed file moves update filesystem paths, schema paths, and imports as one
+operation. If persistence or generation fails, VisualBuild rolls the move back.
+Refresh the project tree, resolve the reported conflict, and retry.
+### Deployment failed
+The deployment dialog shows whether failure occurred during local generation,
+the app build, file upload, deployment creation, or Vercel processing. The
+last successful production deployment stays live.
+Check:
+1. The builder was started after `VERCEL_TOKEN` was set.
+2. App dependencies are installed.
+3. `npm run build` succeeds in the app directory.
+4. `deployment.outputDirectory` matches the build output.
+5. Project name is lowercase and valid.
+6. Team ID and token belong to the same Vercel scope.
+## Troubleshooting
+### Deploy is disabled
+Stop the builder, set `VERCEL_TOKEN` in that same terminal, and restart it.
+### A newly created test app does not contain recent local changes
+Scaffolds copy the current editor into `visual-builder`. An existing scaffold
+does not update when the framework repository changes. Create a fresh scaffold
+when validating unpublished framework changes.
+### A custom component is not in Elements
+- Confirm the file is `.jsx` or `.tsx` under `sourceDir`.
+- Confirm it has a detectable default or named React component export.
+- Select the file and use **Register > Component**.
+- Check `visualbuild/components.json` for the saved registration.
+### A custom component's source content is not visible on the canvas
+Keep the returned JSX static and supported. Runtime expressions are not
+rendered as visual nodes. An optional `{children}` position is recognized as
+the drop location for definition-owned children.
+### Page source does not update the canvas
+Confirm the file is registered as a page, then check the reverse-sync notice.
+Unregistered generic files refresh in the File editor but are not imported
+into the page schema.
+### File edits and canvas edits appear to disagree
+Check which Save action you used:
+- **Save file** writes the File editor buffer.
+- Top-bar **Save** writes canvas/schema state and regenerates managed files.
+Use the conflict notice to choose which side should become authoritative.
+## Development and release verification
+From the framework repository:
+```powershell
+npm.cmd install
+npm.cmd test
+npm.cmd run lint
+npm.cmd run build
+npm.cmd run validate:release
+npm.cmd pack --dry-run
+```
+The release validator creates an isolated workspace, scaffolds both projects,
+installs their dependencies, generates source, lints both projects, builds both
+projects, and verifies that builder-only files cannot enter the deployable
+output.
+## Package and support
+- npm: [create-visualbuild-app](https://www.npmjs.com/package/create-visualbuild-app)
+- source: [LORD-JINXXX/builder-app](https://github.com/LORD-JINXXX/builder-app)
+- issues: [GitHub Issues](https://github.com/LORD-JINXXX/builder-app/issues)
+- complete scaffold guide: [docs/user-guide.md](docs/user-guide.md)
+## License
+VisualBuild is dual-licensed under **MIT OR Apache-2.0**, at your option.
+- [MIT License](LICENSE-MIT)
+- [Apache License 2.0](LICENSE-APACHE)
+Copyright 2026 Mustafa Mohammed Sajid. See [LICENSE](LICENSE) for the
+dual-license notice.