create-visualbuild-app 0.1.0 → 1.0.0

package/README.md

@@ -1,123 +1,306 @@
-# 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.
-
-## Public CLI
-
-The canonical npm package is `create-visualbuild-app`.
-
-After the first public release, create a named project with either command:
-
-```bash
-npm create visualbuild-app@latest my-blog
-```
-
-```bash
-npx create-visualbuild-app@latest my-blog
-```
-
-Omitting the name creates `my-app`:
-
-```bash
-npm create visualbuild-app@latest
-```
-
-The public package has not been published yet. Maintainers can exercise the
-same CLI from this repository:
-
-```powershell
-npm.cmd run create-visualbuild-app -- my-blog
-```
-
-The previous local script remains available as a compatibility alias:
-
-```powershell
-npm.cmd run create-builder-app -- my-blog
-```
-
-## Scaffold Output
-
-VisualBuild deliberately separates the deployable application from the editor:
-
-```text
-workspace/
-  my-blog/            # developer-owned React application
-  visual-builder/     # visual editor, generator, and file watcher
-  my-blog-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-blog
-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-blog/visualbuild/pages.json` and the
-generated React source. Supported static source edits are watched and reflected
-back into the canvas.
-
-## 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.
-
-## 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 pack --dry-run
-```
-
-## Status
-
-Current version: `0.1.0`
-
-Week 3 is in progress. The stable published template, CLI identity, and
-generator diagnostics are complete. The remaining release work is publishing
-to npm and validating clean public-registry scaffolds.
-
-## License
-
-UNLICENSED
+# 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