uniweb 0.8.14 → 0.8.16

package/README.md

@@ -36,10 +36,10 @@ Edit files in `site/pages/` and `foundation/src/sections/` to see changes instan
 | **Store** | E-commerce with product grid |
 | **Extensions** | Multi-foundation with visual effects extension |
 
-Use `--blank` for an empty workspace (no packages) — grow with `uniweb add`.
-
 **See them live:** [View all template demos](https://uniweb.github.io/templates/)
 
+Use `--blank` for an empty workspace (no packages) — grow with `uniweb add`.
+
 Or skip the interactive prompt:
 
 ```bash
@@ -164,13 +164,43 @@ export default function Hero({ content, params }) {
 
 Standard React. Standard Tailwind. The `{ content, params }` interface is only for _section types_ — components that content creators select in markdown frontmatter. Everything else uses regular React props.
 
+### Composition
+
+Sections aren't limited to flat content. Content authors can embed interactive React components using markdown image syntax:
+
+```markdown
+---
+type: SplitContent
+---
+
+# See it in action
+
+The architecture handles the hard parts so you can focus on what matters.
+
+![Live metrics](@PerformanceChart){period=30d}
+```
+
+`@PerformanceChart` is a full React component — a ThreeJS animation, an interactive diagram, a live data visualization — placed by the content author, rendered in the component's visual slot via `<Visual>`. It looks like an image reference, but it can be anything.
+
+Authors can also compose layouts from reusable section types using child sections:
+
+```
+pages/home/
+├── highlights.md            # type: Grid, columns: 3
+├── @stats.md                # type: StatCard
+├── @testimonial.md          # type: Testimonial
+└── @demo.md                 # type: SplitContent (with an embedded @LiveDemo inset)
+```
+
+Three different section types, arranged in a grid, one with an interactive component inside it — all authored in markdown. The developer builds reusable pieces; the content author composes them. See the [Component Patterns guide](https://github.com/uniweb/docs/blob/main/development/component-patterns.md) for the full composition model.
+
 ## Next Steps
 
 After creating your project:
 
 1. **Explore the structure** — Browse `site/pages/` to see how content is organized. Each page folder contains `page.yml` (metadata) and `.md` files (sections).
 
-2. **Generate component docs** — Run `npx uniweb docs` to create `COMPONENTS.md` with all available components, their parameters, and presets.
+2. **Generate component docs** — Run `uniweb docs` to create `COMPONENTS.md` with all available components, their parameters, and presets.
 
 3. **Learn the configuration** — Run `uniweb docs site` or `uniweb docs page` for quick reference on configuration options.
 
@@ -237,31 +267,31 @@ Start simple. Add what you need, when you need it:
 cd my-site
 
 # Add a co-located foundation + site pair
-npx uniweb add project blog
+uniweb add project blog
 
 # Add a second foundation at root
-npx uniweb add foundation ui
+uniweb add foundation ui
 
 # Add a site wired to a specific foundation
-npx uniweb add site docs --foundation ui
+uniweb add site docs --foundation ui
 
 # Add an extension (auto-wired to the only site)
-npx uniweb add extension effects
+uniweb add extension effects
 
 # Scaffold + apply content from an official template
-npx uniweb add project marketing --from marketing
+uniweb add project marketing --from marketing
 ```
 
 The workspace grows organically. `add` handles placement, wires dependencies, updates workspace globs, and generates root scripts. The name you provide becomes both the directory name and the package name. Use `--path` to override default placement, or `--project` for explicit co-located layouts.
 
-> `npx uniweb` works before and after install. Once dependencies are installed, you can also use `pnpm uniweb` directly since `uniweb` is a project dependency.
+> **Install the CLI globally** with `npm i -g uniweb` for the best experience. You can also use `npx uniweb` or `pnpm uniweb` without a global install.
 
 **Or start blank and build up:**
 
 ```bash
 pnpm create uniweb acme --blank
 cd acme
-npx uniweb add project main
+uniweb add project main
 pnpm install
 pnpm dev
 ```
@@ -386,7 +416,7 @@ packages:
 
 **How is this different from MDX?**
 
-MDX blends markdown and JSX—content authors write code. Uniweb keeps them separate: content stays in markdown, components stay in React. Content authors can't break components, and component updates don't require content changes.
+MDX blends markdown and JSX—content authors write code. Uniweb keeps them separate: content stays in markdown, components stay in React. Authors can still embed interactive components (via `![](@Component)` syntax), but they never see JSX. Component updates don't require content changes, and content changes can't break components.
 
 **How is this different from Astro?**
 
@@ -420,4 +450,4 @@ Yes — documentation is a natural fit. Content stays in markdown (easy to versi
 
 ## License
 
-Apache 2.0
+Apache 2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.8.14",
+  "version": "0.8.16",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,11 +41,24 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/build": "0.8.13",
-    "@uniweb/content-reader": "1.1.4",
-    "@uniweb/kit": "0.7.10",
-    "@uniweb/runtime": "0.6.10",
+    "@uniweb/runtime": "0.6.11",
     "@uniweb/core": "0.5.10",
-    "@uniweb/semantic-parser": "1.1.6"
+    "@uniweb/kit": "0.7.11"
+  },
+  "peerDependencies": {
+    "@uniweb/build": "0.8.15",
+    "@uniweb/semantic-parser": "1.1.6",
+    "@uniweb/content-reader": "1.1.4"
+  },
+  "peerDependenciesMeta": {
+    "@uniweb/build": {
+      "optional": true
+    },
+    "@uniweb/content-reader": {
+      "optional": true
+    },
+    "@uniweb/semantic-parser": {
+      "optional": true
+    }
   }
 }

package/partials/agents.md

@@ -83,7 +83,7 @@ Use `--template <n>` for an official template (`none`, `starter`, `marketing`, `
 ### Adding a co-located project
 
 ```bash
-pnpm uniweb add project docs
+uniweb add project docs
 pnpm install
 ```
 
@@ -92,10 +92,10 @@ This creates `docs/foundation/` + `docs/site/` with package names `docs-foundati
 ### Adding individual packages
 
 ```bash
-pnpm uniweb add foundation           # First foundation → ./foundation/
-pnpm uniweb add foundation ui        # Named → ./ui/
-pnpm uniweb add site                 # First site → ./site/
-pnpm uniweb add site blog            # Named → ./blog/
+uniweb add foundation           # First foundation → ./foundation/
+uniweb add foundation ui        # Named → ./ui/
+uniweb add site                 # First site → ./site/
+uniweb add site blog            # Named → ./blog/
 ```
 
 The name is both the directory name and the package name. Use `--project <n>` to co-locate under a project directory (e.g., `--project docs` → `docs/foundation/`).
@@ -103,8 +103,8 @@ The name is both the directory name and the package name. Use `--project <n>` to
 ### Adding section types
 
 ```bash
-pnpm uniweb add section Hero
-pnpm uniweb add section Hero --foundation ui   # When multiple foundations exist
+uniweb add section Hero
+uniweb add section Hero --foundation ui   # When multiple foundations exist
 ```
 
 Creates `src/sections/Hero/index.jsx` and `meta.js` with a minimal CCA-proper starter. The dev server picks it up automatically — no build or install needed.
@@ -340,9 +340,9 @@ Check out [this](/a) link.     ← inline → stays in paragraphs as <a> tag
 This is [less important]{muted} context.
 ```
 
-`accent` (colored + bold) and `muted` (subtle) adapt to context automatically. Components receive HTML strings with spans applied: `<span accent="true">faster</span>`.
+`accent` (link-colored + bold), `callout` (accent-colored + bold), and `muted` (subtle) are built-in defaults that adapt to context automatically. Components receive HTML strings with spans applied: `<span accent="true">faster</span>`.
 
-Sites can define additional named styles in `theme.yml`'s `inline:` section.
+Sites can override these or define additional named styles in `theme.yml`'s `inline:` section.
 
 ### Fenced Code in Content
 
@@ -676,6 +676,9 @@ inline:
   accent:
     color: var(--link)
     font-weight: '600'
+  callout:
+    color: var(--accent)
+    font-weight: '600'
 
 vars:
   header-height: 5rem
@@ -1282,9 +1285,9 @@ Semantic tokens come from `theme-tokens.css` (populated from `theme.yml`). Use `
 
 **Content not appearing as expected?**
 ```bash
-pnpm uniweb inspect pages/home/hero.md         # Single section
-pnpm uniweb inspect pages/home/                 # Whole page
-pnpm uniweb inspect pages/home/hero.md --raw    # ProseMirror AST
+uniweb inspect pages/home/hero.md         # Single section
+uniweb inspect pages/home/                 # Whole page
+uniweb inspect pages/home/hero.md --raw    # ProseMirror AST
 ```
 
 ## Learning from Official Templates
@@ -1292,7 +1295,7 @@ pnpm uniweb inspect pages/home/hero.md --raw    # ProseMirror AST
 When you're unsure how to implement a pattern — data fetching, i18n, layouts, insets, theming — install an official template as a reference project in your workspace:
 
 ```bash
-pnpm uniweb add project marketing --from marketing
+uniweb add project marketing --from marketing
 pnpm install
 ```
 

package/partials/components-docs.hbs

@@ -4,10 +4,10 @@ Generate up-to-date documentation for all foundation components:
 
 ```bash
 # From foundation directory
-pnpm uniweb docs
+uniweb docs
 
 # Or from site directory (auto-detects linked foundation)
-cd site && pnpm uniweb docs
+cd site && uniweb docs
 ```
 
 This creates `COMPONENTS.md` with details on each component's parameters, presets, and content elements. The documentation is generated from component `meta.js` files, so it's always current.

package/partials/config-reference.hbs

@@ -64,4 +64,4 @@ seo:
   priority: 0.8
 ```
 
-Run `pnpm uniweb docs site` or `pnpm uniweb docs page` for complete reference.
+Run `uniweb docs site` or `uniweb docs page` for complete reference.

package/src/commands/add.js

@@ -121,7 +121,7 @@ export async function add(rawArgs) {
       error(`Missing subcommand.\n`)
       log(formatOptions([
         { label: 'project', description: 'Co-located foundation + site pair' },
-        { label: 'foundation', description: 'Component library' },
+        { label: 'foundation', description: 'Component system for content authors' },
         { label: 'site', description: 'Content site' },
         { label: 'extension', description: 'Additional component package' },
         { label: 'section', description: 'Section type in a foundation' },
@@ -137,7 +137,7 @@ export async function add(rawArgs) {
       message: 'What would you like to add?',
       choices: [
         { title: 'Project', value: 'project', description: 'Co-located foundation + site pair' },
-        { title: 'Foundation', value: 'foundation', description: 'Component library' },
+        { title: 'Foundation', value: 'foundation', description: 'Component system for content authors' },
         { title: 'Site', value: 'site', description: 'Content site' },
         { title: 'Extension', value: 'extension', description: 'Additional component package' },
         { title: 'Section', value: 'section', description: 'Section type in a foundation' },
@@ -352,7 +352,7 @@ async function addSite(rootDir, projectName, opts, pm = 'pnpm') {
     }, {
       onProgress: (msg) => info(`  ${msg}`),
     })
-    log(`  ${colors.yellow}⚠ No foundation wired. Add one later with: npx uniweb add foundation${colors.reset}`)
+    log(`  ${colors.yellow}⚠ No foundation wired. Add one later with: uniweb add foundation${colors.reset}`)
   }
 
   // Apply template content if --from specified
@@ -594,7 +594,8 @@ async function addProject(rootDir, projectName, opts, pm = 'pnpm') {
  * - --project: {project}/foundation (co-located)
  * - Existing co-located glob: follow pattern
  * - Existing segregated glob: follow pattern
- * - First foundation: dir name is the name (default: 'foundation')
+ * - Named (e.g., "marketing"): segregated at foundations/{name}
+ * - Unnamed: root-level 'foundation'
  * - Already have one: error in non-interactive, ask in interactive
  */
 async function resolveFoundationTarget(rootDir, name, opts) {
@@ -619,8 +620,13 @@ async function resolveFoundationTarget(rootDir, name, opts) {
     return `foundations/${name || 'foundation'}`
   }
 
-  // dir name = name or 'foundation'
-  const dirName = name || 'foundation'
+  // Named foundation → segregated layout (foundations/{name})
+  if (name) {
+    return `foundations/${name}`
+  }
+
+  // Unnamed → root-level 'foundation'
+  const dirName = 'foundation'
 
   // Check if target already exists
   if (!existsSync(join(rootDir, dirName))) {
@@ -667,8 +673,13 @@ async function resolveSiteTarget(rootDir, name, opts) {
     return `sites/${name || 'site'}`
   }
 
-  // dir name = name or 'site'
-  const dirName = name || 'site'
+  // Named site → segregated layout (sites/{name})
+  if (name) {
+    return `sites/${name}`
+  }
+
+  // Unnamed → root-level 'site'
+  const dirName = 'site'
 
   // Check if target already exists
   if (!existsSync(join(rootDir, dirName))) {
@@ -1050,9 +1061,9 @@ ${colors.bright}Examples:${colors.reset}
   uniweb add project docs                              # Create docs/foundation/ + docs/site/
   uniweb add project docs --from academic              # Co-located pair + academic content
   uniweb add foundation                                # Create ./foundation/ at root
-  uniweb add foundation ui                             # Create ./ui/ at root
+  uniweb add foundation ui                             # Create ./foundations/ui/
   uniweb add site                                      # Create ./site/ at root
-  uniweb add site blog --foundation marketing          # Create ./blog/ wired to marketing
+  uniweb add site blog --foundation marketing          # Create ./sites/blog/ wired to marketing
   uniweb add extension effects --site site             # Create ./extensions/effects/
   uniweb add section Hero                              # Create Hero section type
   uniweb add section Hero --foundation ui              # Target specific foundation

package/src/commands/build.js

@@ -18,9 +18,7 @@ import { writeFile, mkdir } from 'node:fs/promises'
 // Import build utilities from @uniweb/build
 import {
   generateEntryPoint,
-  buildSchema,
   discoverComponents,
-  processAllPreviews,
 } from '@uniweb/build'
 import { readSiteConfig } from '@uniweb/build/site'
 import { readWorkspaceConfig, resolveGlob } from '../utils/config.js'
@@ -130,7 +128,6 @@ function runCommand(command, args, cwd) {
  */
 async function buildFoundation(projectDir, options = {}) {
   const srcDir = join(projectDir, 'src')
-  const distDir = join(projectDir, 'dist')
 
   info('Building foundation...')
 
@@ -163,50 +160,19 @@ async function buildFoundation(projectDir, options = {}) {
   // For now, just run the standard vite build
   await runCommand('npx', ['vite', 'build'], projectDir)
 
-  success('Vite build complete')
-
-  // 4. Generate schema.json
-  log('')
-  info('Generating schema.json...')
-  let schema = await buildSchema(srcDir)
-
-  await mkdir(distDir, { recursive: true })
+  // Vite's foundation plugin generates dist/meta/schema.json
+  // and processes preview images during the build.
 
-  // 5. Process preview images
-  log('')
-  info('Processing preview images...')
-  const isProduction = process.env.NODE_ENV === 'production' || !process.env.NODE_ENV
-  const { schema: updatedSchema, totalImages } = await processAllPreviews(
-    srcDir,
-    distDir,
-    schema,
-    isProduction
-  )
-  schema = updatedSchema
-
-  if (totalImages > 0) {
-    success(`Processed ${totalImages} preview image${totalImages > 1 ? 's' : ''} (converted to webp)`)
-  } else {
-    log(`  ${colors.dim}No preview images found${colors.reset}`)
-  }
-
-  // 6. Write schema.json
-  const schemaPath = join(distDir, 'schema.json')
-  await writeFile(schemaPath, JSON.stringify(schema, null, 2), 'utf-8')
-
-  success(`Generated schema.json with ${componentNames.length} components`)
+  success('Vite build complete')
 
   // Summary
   log('')
   log(`${colors.green}${colors.bright}Build complete!${colors.reset}`)
+
   log('')
-  log(`Output:`)
-  log(`  ${colors.dim}dist/foundation.js${colors.reset}    - Bundled components`)
-  log(`  ${colors.dim}dist/assets/style.css${colors.reset} - Compiled CSS`)
-  log(`  ${colors.dim}dist/schema.json${colors.reset}      - Component schemas`)
-  if (totalImages > 0) {
-    log(`  ${colors.dim}dist/assets/[component]/${colors.reset} - Preview images`)
-  }
+  log(`${colors.bright}Share with clients:${colors.reset}`)
+  log(`  ${colors.bright}uniweb publish${colors.reset}              Register your foundation (one-time setup)`)
+  log(`  ${colors.bright}uniweb handoff <email>${colors.reset}      Hand off a site to a client`)
 }
 
 /**
@@ -489,6 +455,8 @@ async function buildSite(projectDir, options = {}) {
       process.exit(1)
     }
   }
+
+  showNextSteps(false, true)
 }
 
 /**
@@ -625,6 +593,26 @@ async function buildWorkspace(workspaceDir, options = {}) {
   log(`${colors.green}${colors.bright}Workspace build complete!${colors.reset}`)
   log('')
   log(`Built ${parts.join(', ')}`)
+
+  showNextSteps(foundations.length > 0, sites.length > 0)
+}
+
+/**
+ * Show next-step hints after workspace build
+ */
+function showNextSteps(hasFoundations, hasSites) {
+  if (hasFoundations) {
+    log('')
+    log(`${colors.bright}Share with clients:${colors.reset}`)
+    log(`  ${colors.bright}uniweb publish${colors.reset}              Register your foundation (one-time setup)`)
+    log(`  ${colors.bright}uniweb handoff <email>${colors.reset}      Hand off a site to a client`)
+  }
+  if (hasSites) {
+    log('')
+    log(`${colors.bright}Deploy:${colors.reset}`)
+    log(`  ${colors.bright}uniweb deploy${colors.reset}     Uniweb hosting`)
+    log(`  Or upload ${colors.cyan}dist/${colors.reset} to any static host`)
+  }
 }
 
 /**