create-visualbuild-app 0.1.0 → 1.0.1

package/templates/default/app/README.md

@@ -1,21 +1,56 @@
-# __DISPLAY_NAME__
-
-This is the deployable React application generated by VisualBuild. It contains
-only the source and dependencies required to run the application.
-
-## Run
-
-```powershell
-npm install
-npm.cmd run dev
-```
-
-## Build
-
-```powershell
-npm.cmd run build
-```
-
-The visual schema lives in `visualbuild/pages.json`. The optional sibling
-`visual-builder` project can edit this application visually and regenerate its
-managed React files. This application remains runnable without that editor.
+# __DISPLAY_NAME__
+
+This is the deployable React application generated by VisualBuild. It contains
+only the source and dependencies required to run the application.
+
+The complete workspace guide is available at
+[`../VISUALBUILD-GUIDE.md`](../VISUALBUILD-GUIDE.md). It explains the editor,
+page and component registration, source ownership, two-way synchronization,
+configuration, deployment, limits, and recovery.
+
+## Run
+
+```powershell
+npm install
+npm.cmd run dev
+```
+
+## Build
+
+```powershell
+npm.cmd run build
+```
+
+The visual schema lives in `visualbuild/pages.json`. The optional sibling
+`visual-builder` project can edit this application visually and regenerate its
+managed React files. This application remains runnable without that editor.
+
+## VisualBuild configuration
+
+Edit `visualbuild.config.ts` to customize source, page, layout, schema,
+component-registry, and generated-manifest paths; initial editor panels and
+viewport widths; editor theme preference; and App/layout/stale-file generation.
+The `deployment` block configures the static output folder plus optional Vercel
+project and team identifiers.
+The file imports types only, so the deployable app has no VisualBuild runtime
+dependency. Restart the sibling visual builder after changing configured paths.
+
+The editor theme setting accepts `default`, `codex-dark`, `vs-light`,
+`vs-dark`, or `system`. A theme selected from the editor's top-bar palette is
+saved for this project. Editor palettes never change the styling of this
+deployable application.
+
+## Deploy from VisualBuild
+
+Set `VERCEL_TOKEN` in the terminal that starts the sibling visual builder, then
+use **Deploy** in the editor top bar:
+
+```powershell
+$env:VERCEL_TOKEN = 'your-token'
+npm.cmd run visual-builder
+```
+
+VisualBuild saves and builds this app locally and sends only the generated
+`dist` files to Vercel. The editor package, `visualbuild` metadata,
+`node_modules`, configuration source, and access token are never uploaded.
+Use `VERCEL_TEAM_ID` or the optional Team ID field for a team-owned project.

package/templates/default/app/visualbuild/components.json

@@ -0,0 +1,3 @@
+{
+  "components": []
+}

package/templates/default/app/visualbuild/config.d.ts

@@ -0,0 +1,48 @@
+export type VisualBuildTheme =
+  | 'default'
+  | 'codex-dark'
+  | 'vs-light'
+  | 'vs-dark'
+  | 'system'
+  | 'dark'
+  | 'light'
+export type VisualBuildViewport = 'mobile' | 'tablet' | 'desktop'
+
+export interface VisualBuildConfig {
+  paths?: {
+    sourceDir?: string
+    pagesDir?: string
+    layoutsDir?: string
+    appFile?: string
+    schemaFile?: string
+    componentRegistryFile?: string
+    generatedManifestFile?: string
+  }
+  editor?: {
+    theme?: VisualBuildTheme
+    defaultViewport?: VisualBuildViewport
+    responsiveWidths?: {
+      mobile?: number
+      tablet?: number
+      desktop?: number | 'fluid'
+    }
+    panels?: {
+      leftOpen?: boolean
+      leftTab?: 'files' | 'elements'
+      rightOpen?: boolean
+      rightTab?: 'code' | 'properties'
+      codeView?: 'page' | 'app' | 'layout' | 'schema' | 'file'
+    }
+  }
+  generator?: {
+    emitApp?: boolean
+    emitLayout?: boolean
+    cleanStaleFiles?: boolean
+  }
+  deployment?: {
+    provider?: 'vercel'
+    outputDirectory?: string
+    projectName?: string
+    teamId?: string
+  }
+}

package/templates/default/app/visualbuild.config.ts

@@ -0,0 +1,38 @@
+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

package/templates/default/builder/README.md

@@ -1,21 +1,37 @@
-# VisualBuild Editor
-
-This package contains the optional VisualBuild editor and generator for the
-sibling `__PROJECT_NAME__` React application.
-
-## Run
-
-```powershell
-npm install
-npm.cmd run visual-builder
-```
-
-## Generate Without Opening The Editor
-
-```powershell
-npm.cmd run vb:generate
-```
-
-The editor reads and writes `../__PROJECT_NAME__/visualbuild/pages.json` and
-manages generated files in `../__PROJECT_NAME__/src`. It is intentionally
-separate from the deployable application and does not need to be deployed.
+# VisualBuild Editor
+
+This package contains the optional VisualBuild editor and generator for the
+sibling `__PROJECT_NAME__` React application.
+
+Read [`../VISUALBUILD-GUIDE.md`](../VISUALBUILD-GUIDE.md) for the complete
+visual editing, registry, code workspace, synchronization, configuration,
+deployment, and recovery workflow.
+
+## Run
+
+```powershell
+npm install
+npm.cmd run visual-builder
+```
+
+To enable one-click Vercel deployment, set the access token in this terminal
+before starting the editor:
+
+```powershell
+$env:VERCEL_TOKEN = 'your-token'
+npm.cmd run visual-builder
+```
+
+The token remains in this local process and is never written to the app or sent
+to the browser. An optional `VERCEL_TEAM_ID` scopes deployments to a team.
+
+## Generate Without Opening The Editor
+
+```powershell
+npm.cmd run vb:generate
+```
+
+The editor reads and writes `../__PROJECT_NAME__/visualbuild/pages.json` and
+manages generated files in `../__PROJECT_NAME__/src`. It is intentionally
+separate from the deployable application and does not need to be deployed.
+The Deploy action builds the sibling app and uploads only its static output.