create-visualbuild-app 0.1.0 → 1.0.1

package/docs/user-guide.md

@@ -0,0 +1,759 @@
+# VisualBuild v1 User Guide
+
+VisualBuild is a local visual editor for React and Tailwind applications. It
+lets you build pages with drag and drop while keeping ordinary `.jsx` and
+`.tsx` source files that can be opened in any code editor, committed to Git,
+built with Vite, and deployed without a VisualBuild runtime.
+
+This guide covers installation, the generated workspace, visual editing, page
+and component registration, the code workspace, source ownership, supported
+two-way synchronization, configuration, deployment, limits, recovery, and the
+planned direction after v1.
+
+## Contents
+
+1. [Requirements](#requirements)
+2. [Create a project](#create-a-project)
+3. [Understand the generated workspace](#understand-the-generated-workspace)
+4. [Start the app and editor](#start-the-app-and-editor)
+5. [Understand the interface](#understand-the-interface)
+6. [Build and edit a page](#build-and-edit-a-page)
+7. [Create and register pages](#create-and-register-pages)
+8. [Use built-in elements](#use-built-in-elements)
+9. [Create and register custom components](#create-and-register-custom-components)
+10. [Use the code panel and larger editor](#use-the-code-panel-and-larger-editor)
+11. [Understand source ownership and synchronization](#understand-source-ownership-and-synchronization)
+12. [Reverse-sync support and limits](#reverse-sync-support-and-limits)
+13. [Configure VisualBuild](#configure-visualbuild)
+14. [Use editor themes and responsive previews](#use-editor-themes-and-responsive-previews)
+15. [Deploy to Vercel](#deploy-to-vercel)
+16. [Generate and build without the editor](#generate-and-build-without-the-editor)
+17. [Upcoming versions](#upcoming-versions)
+18. [Recover from errors and conflicts](#recover-from-errors-and-conflicts)
+19. [Troubleshooting](#troubleshooting)
+
+## 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.
+
+## Understand the generated workspace
+
+```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.
+
+## Start the app and editor
+
+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.
+
+## 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.