create-visualbuild-app 1.0.0 → 1.0.1

package/README.md

@@ -1,306 +1,984 @@
-# VisualBuild
-
-VisualBuild is a visual development framework for building React applications
-with drag and drop while retaining normal, editable source code.
-
-The visual editor writes the project schema, the generator writes real React
-files, and supported static JSX/TSX edits can sync back into the canvas.
-
-## Complete User Guide
-
-Read the [VisualBuild v1 User Guide](docs/user-guide.md) for the complete,
-self-contained workflow. It covers installation, folder separation, the
-interface, visual editing, page and component registration, the full-screen
-code workspace, source ownership, supported two-way sync, configuration,
-themes, Vercel deployment, limits, troubleshooting, and error recovery.
-
-Every new scaffold also includes this guide as `VISUALBUILD-GUIDE.md` beside
-the generated app and editor folders, so the documentation remains available
-without returning to the framework repository.
-
-## Public CLI
-
-The canonical npm package is `create-visualbuild-app`.
-
-Create a named project with either command:
-
-```bash
-npm create visualbuild-app@latest my-app
-```
-
-```bash
-npx create-visualbuild-app@latest my-app
-```
-
-Omitting the name creates `my-app`:
-
-```bash
-npm create visualbuild-app@latest
-```
-
-Version `0.1.0` is published on npm. Maintainers can also exercise the same CLI
-from this repository:
-
-```powershell
-npm.cmd run create-visualbuild-app -- my-app
-```
-
-The previous local script remains available as a compatibility alias:
-
-```powershell
-npm.cmd run create-builder-app -- my-app
-```
-
-## Scaffold Output
-
-VisualBuild deliberately separates the deployable application from the editor:
-
-```text
-workspace/
-  my-app/             # developer-owned React application
-  visual-builder/     # visual editor, generator, and file watcher
-  my-app-README.md    # generated setup instructions
-```
-
-The React app does not install editor-only packages such as dnd-kit or Zustand.
-It can be built, deployed, or retained after deleting `visual-builder/`.
-
-## Run A Generated Project
-
-Install and start the React application:
-
-```powershell
-cd my-app
-npm install
-npm.cmd run dev
-```
-
-In another terminal, install and start the visual editor:
-
-```powershell
-cd visual-builder
-npm install
-npm.cmd run visual-builder
-```
-
-Changes saved in the editor update `my-app/visualbuild/pages.json` and the
-generated React source. Supported static source edits are watched and reflected
-back into the canvas.
-
-## Configure A Project
-
-Each generated app includes a typed `visualbuild.config.ts`. All fields are
-optional; omitted values keep the standard `src`, desktop, dark-editor, and
-generation behavior.
-
-```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',
-  },
-} satisfies VisualBuildConfig
-```
-
-Paths are normalized project-relative paths and cannot escape the app folder.
-Page, layout, and App locations must remain inside `sourceDir`. Responsive
-widths accept values from 240 through 4096 pixels; desktop also accepts
-`'fluid'`. Generator switches can retain a developer-owned App or layout and
-can disable stale managed-file cleanup. Restart the visual-builder process
-after changing project paths so its file watchers use the new locations.
-
-## Deploy To Vercel
-
-VisualBuild can publish the developer-owned app directly from the editor. The
-deployment pipeline saves and regenerates source, runs the app's production
-build locally, and uploads only the configured static output directory. It
-never uploads `visual-builder`, `visual-app-builder`, `visualbuild`,
-`node_modules`, the VisualBuild config, or the Vercel access token.
-
-Create a Vercel access token, then set it only in the terminal that starts the
-visual builder:
-
-```powershell
-$env:VERCEL_TOKEN = 'your-token'
-npm.cmd run visual-builder
-```
-
-For a team-owned project, optionally set `$env:VERCEL_TEAM_ID = 'team_...'` or
-enter the Team ID in the deployment dialog. Click **Deploy** in the top bar,
-review the Vercel project name, and choose **Deploy production**. VisualBuild
-waits for Vercel to report `READY`, then displays the production URL.
-
-Configure a non-standard Vite output directory or stable Vercel project name
-in `visualbuild.config.ts`:
-
-```ts
-deployment: {
-  provider: 'vercel',
-  outputDirectory: 'dist',
-  projectName: 'my-app',
-  teamId: 'team_abc123', // optional
-}
-```
-
-The access token is intentionally not supported in project configuration or
-browser storage. If deployment fails, the dialog shows the Vercel or local
-build error and leaves the last successful production deployment untouched.
-
-## Editor Themes
-
-Use the palette control in the VisualBuild top bar to switch between:
-
-- VisualBuild Default
-- Codex Dark
-- VS Code Light
-- VS Code Dark
-- System
-
-The selected theme is saved per project and restored after refresh or editor
-restart. `editor.theme` in `visualbuild.config.ts` supplies the initial choice
-until the user selects a theme. The legacy values `dark` and `light` remain
-supported and map to VisualBuild Default and VS Code Light.
-
-Theme styles are scoped to editor chrome. The canvas, preview, generated React
-source, and deployable application keep their own Tailwind styling and are not
-recolored by the editor theme.
-
-## Register Local Components
-
-Create a `.jsx` or `.tsx` component inside the deployable app's `src` folder,
-then register it from the editor:
-
-New `.jsx` and `.tsx` files created through the VisualBuild project explorer
-are automatically initialized with a valid default-export component named from
-the file. The starter uses a simple `<div>` root with an editable heading, so it
-is immediately ready for custom-component registration. Root attributes are
-written into that element from the Properties panel. Other file extensions
-remain empty.
-
-1. Select the source file in **Files**.
-2. Click **Register** in the Code panel.
-3. Choose **Component** from the **Register as** dropdown.
-4. Click **Register component**.
-
-VisualBuild detects the default or named component export, stores the
-registration in `visualbuild/components.json`, and immediately adds it under
-**Elements → Custom**.
-
-Registered components expose ID, Tailwind classes, and additional JSON
-attributes in the Properties panel. They also expose their managed component
-root tag and accept nested canvas elements. Static JSX authored inside the
-component is selectable on the canvas. Elements dragged inside the component
-become part of the component definition and are written into the registered
-source file on Save. Pages reference the reusable definition with a
-self-closing component tag such as `<First />`; they do not duplicate the
-component's internal JSX. Generated pages import components directly from
-their local source files, so the deployed app has no VisualBuild runtime
-dependency.
-
-Custom component root-property edits update the registered implementation, such
-as `src/components/First.tsx`, and therefore apply to every use of that
-component. Nested element edits have the same definition-wide behavior. File
-mode follows source ownership: selecting any node inside a registered custom
-component opens that component's source; selecting a page element opens the
-active managed page source; and selecting a project-tree file opens that exact
-file. Unsaved root, property, and child-tree changes immediately update the
-matching page or custom-component File buffer unless the developer has started
-typing there.
-
-## Architecture
-
-```text
-Visual Editor
-    |
-    v
-visualbuild/pages.json
-    |
-    v
-Babel AST Generator
-    |
-    v
-React Project
-```
-
-`visualbuild/pages.json` remains the safe schema boundary. Reverse sync accepts
-documented static JSX/TSX structures; unsupported dynamic React code is left
-untouched and produces an editor diagnostic.
-
-The Code panel's Page, App, Layout, and JSON tabs are generated, read-only
-previews. The File tab edits the exact selected project file. Click **Open
-editor** to use the larger full-screen code workspace with its own project
-explorer and Save file controls. Top-bar **Save** persists canvas/schema state;
-**Save file** writes the source editor buffer.
-
-Managed page source can update the canvas when its returned JSX is static.
-Registered custom component source refreshes its canvas definition. Runtime
-expressions, spread props, member-expression tags, and arbitrary React behavior
-are intentionally outside the importer boundary. See the
-[reverse-sync contract and recovery guide](docs/user-guide.md#reverse-sync-support-and-limits)
-before editing generated pages directly.
-
-## Development
-
-```powershell
-npm install
-npm.cmd run visual-builder
-```
-
-Useful checks:
-
-```powershell
-npm.cmd run lint
-npm.cmd run build
-npm.cmd run test:week3
-npm.cmd run test:custom-components
-npm.cmd run test:config
-npm.cmd run test:deployment
-npm.cmd pack --dry-run
-```
-
-## Status
-
-Current version: `0.1.0`
-
-Week 3 is complete. Version `0.1.0` is published as
-`create-visualbuild-app`, and both public CLI forms have been validated from
-clean workspaces with explicit and default project names.
-
-Week 4 covers component expansion, custom component registration, editor
-themes, configuration, deployment, and v1 release-candidate validation.
-
-## 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
+
+UNLICENSED

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-visualbuild-app",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Scaffold a React app with a separate VisualBuild drag-and-drop editor.",
   "type": "module",
   "bin": {