uniweb 0.8.2 → 0.8.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,9 +41,9 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/build": "0.8.2",
-    "@uniweb/kit": "0.7.2",
-    "@uniweb/runtime": "0.6.3",
-    "@uniweb/core": "0.5.3"
+    "@uniweb/build": "0.8.4",
+    "@uniweb/core": "0.5.4",
+    "@uniweb/runtime": "0.6.4",
+    "@uniweb/kit": "0.7.3"
   }
 }

package/partials/agents.md

@@ -100,7 +100,7 @@ content = {
   icons: [],        // { library, name, role }
   videos: [],       // Video embeds
   insets: [],       // Inline @Component references — { refId }
-  lists: [],        // Bullet/ordered lists
+  lists: [],        // [[{ paragraphs, links, lists, ... }]] — each list item is an object, not a string
   quotes: [],       // Blockquotes
   data: {},         // From tagged code blocks (```yaml:tagname)
   headings: [],     // Overflow headings after subtitle2
@@ -123,6 +123,35 @@ Lightning quick.        ← items[0].paragraphs[0]
 Enterprise-grade.       ← items[1].paragraphs[0]
 ```
 
+**Lists** contain bullet or ordered list items. Each list item is an object with the same content shape — not a plain string:
+
+```markdown
+# Features               ← title
+
+- Fast builds             ← lists[0][0].paragraphs[0]
+- **Hot** reload          ← lists[0][1].paragraphs[0]  (HTML: "<strong>Hot</strong> reload")
+```
+
+Items can contain lists:
+
+```markdown
+### Starter               ← items[0].title
+$9/month                  ← items[0].paragraphs[0]
+
+- Feature A               ← items[0].lists[0][0].paragraphs[0]
+- Feature B               ← items[0].lists[0][1].paragraphs[0]
+```
+
+Render list item text with kit components (see [kit section](#uniwebkit) below):
+
+```jsx
+import { Span } from '@uniweb/kit'
+
+content.lists[0]?.map((listItem, i) => (
+  <li key={i}><Span text={listItem.paragraphs[0]} /></li>
+))
+```
+
 ### Icons
 
 Use image syntax with library prefix: `![](lu-house)`. Supported libraries: `lu` (Lucide), `hi2` (Heroicons), `fi` (Feather), `pi` (Phosphor), `tb` (Tabler), `bs` (Bootstrap), `md` (Material), `fa6` (Font Awesome 6), and others. Browse at [react-icons.github.io/react-icons](https://react-icons.github.io/react-icons/).
@@ -270,16 +299,15 @@ nest:
 - Children are ordered by their position in the `nest:` array
 - Orphaned `@` files (no parent in `nest:`) appear at top-level with a warning
 
-Components receive children via `block.childBlocks`:
+Components receive children via `block.childBlocks`. Use `ChildBlocks` from kit to render them — the runtime handles component resolution:
 
 ```jsx
+import { ChildBlocks } from '@uniweb/kit'
+
 export default function Grid({ block, params }) {
   return (
     <div className={`grid grid-cols-${params.columns || 2} gap-6`}>
-      {block.childBlocks.map(child => {
-        const Comp = child.initComponent()
-        return Comp ? <Comp key={child.id} block={child} /> : null
-      })}
+      <ChildBlocks from={block} />
     </div>
   )
 }
@@ -520,9 +548,45 @@ All defaults belong in `meta.js`, not inline in component code.
 
 ### @uniweb/kit
 
-**Primitives** (`@uniweb/kit`): `H1`–`H6`, `P`, `Span`, `Text`, `Link`, `Image`, `Icon`, `Media`, `Asset`, `SocialIcon`, `FileLogo`, `cn()`
+Content fields (`title`, `pretitle`, `paragraphs[]`, list item text) are **HTML strings** — they contain markup like `<strong>`, `<em>`, `<a>` from the author's markdown. The kit provides components to render them correctly.
+
+**Rendering text** (`@uniweb/kit`):
+
+```jsx
+import { H2, P, Span } from '@uniweb/kit'
+
+<H2 text={content.title} className="text-heading text-3xl font-bold" />
+<P text={content.paragraphs[0]} className="text-body" />
+<P text={content.paragraphs} />   // array → each string becomes its own <p>
+<Span text={listItem.paragraphs[0]} className="text-subtle" />
+```
+
+`H1`–`H6`, `P`, `Span`, `Div` are all wrappers around `Text` with a preset tag:
+
+```jsx
+<Text text={content.title} as="h2" className="..." />  // explicit tag
+```
+
+Don't render content strings with `{content.paragraphs[0]}` in JSX — that shows HTML tags as visible text. Use `<P>`, `<H2>`, `<Span>`, etc. for content strings.
+
+**Rendering full content** (`@uniweb/kit`):
 
-**Styled** (`@uniweb/kit/styled`): `Section`, `Render`, `Visual`, `SidebarLayout`, `Code`, `Alert`, `Table`, `Details`, `Divider`, `Disclaimer`
+```jsx
+import { Section, Render } from '@uniweb/kit'
+
+<Render content={block.parsedContent} block={block} />   // ProseMirror nodes → React
+<Section block={block} width="lg" padding="md" />         // Render + prose styling + layout
+```
+
+`Render` processes ProseMirror nodes into React elements — paragraphs, headings, images, code blocks, lists, tables, alerts, and insets. `Section` wraps `Render` with prose typography and layout options. Use these when rendering a block's complete content. Use `P`, `H2`, etc. when you extract specific fields and arrange them with custom layout.
+
+**Rendering visuals** (`@uniweb/kit`):
+
+`<Visual>` renders the first non-empty candidate from the props you pass (inset, video, image). See Insets section below.
+
+**Other primitives** (`@uniweb/kit`): `Link`, `Image`, `Icon`, `Media`, `Asset`, `SafeHtml`, `SocialIcon`, `FileLogo`, `cn()`
+
+**Other styled** (`@uniweb/kit`): `SidebarLayout`, `Prose`, `Article`, `Code`, `Alert`, `Table`, `Details`, `Divider`, `Disclaimer`
 
 **Hooks:**
 - `useScrolled(threshold)` → boolean for scroll-based header styling
@@ -575,25 +639,26 @@ website.getLocaleUrl('es')
 Components access inline `@` references via `block.insets` (separate from `block.childBlocks`):
 
 ```jsx
-import { Visual } from '@uniweb/kit/styled'
+import { Visual } from '@uniweb/kit'
 
-// Visual renders the first visual: inset > video > image
-function SplitContent({ content, block, params }) {
+// Visual renders the first non-empty candidate: inset > video > image
+function SplitContent({ content, block }) {
   return (
     <div className="flex gap-12">
       <div className="flex-1">
         <h2 className="text-heading">{content.title}</h2>
       </div>
-      <Visual content={content} block={block} className="flex-1 rounded-lg" />
+      <Visual inset={block.insets[0]} video={content.videos[0]} image={content.imgs[0]} className="flex-1 rounded-lg" />
     </div>
   )
 }
 ```
 
+- `<Visual>` — renders first non-empty candidate from the props you pass (`inset`, `video`, `image`)
+- `<Render>` / `<Section>` — automatically handles `@Component` references placed in content flow
 - `block.insets` — array of Block instances from `@` references
 - `block.getInset(refId)` — lookup by refId (used by sequential renderers)
 - `content.insets` — flat array of `{ refId }` entries (parallel to `content.imgs`)
-- `<Visual>` — renders first inset > video > image from content (from `@uniweb/kit/styled`)
 
 Inset components declare `inset: true` in meta.js. Use `hidden: true` for inset-only components:
 
@@ -624,7 +689,7 @@ function SplitContent({ content, block, params }) {
         <h2 className="text-heading text-3xl font-bold">{content.title}</h2>
         <p className="text-body mt-4">{content.paragraphs[0]}</p>
       </div>
-      <Visual content={content} block={block} className="flex-1 rounded-2xl" />
+      <Visual inset={block.insets[0]} video={content.videos[0]} image={content.imgs[0]} className="flex-1 rounded-2xl" />
     </div>
   )
 }
@@ -731,7 +796,7 @@ Uniweb section types do more with less because the framework handles concerns th
 - **Dispatcher pattern** — one section type with a `variant` param replaces multiple near-duplicate components (`HeroHomepage` + `HeroPricing` → `Hero` with `variant: homepage | pricing`)
 - **Section nesting** — `@`-prefixed child files replace wrapper components that exist only to arrange children
 - **Insets** — `![](@ComponentName)` replaces prop-drilling of visual components into containers
-- **Visual component** — `<Visual>` renders image/video/inset from content, replacing manual media handling
+- **Visual component** — `<Visual>` renders the first non-empty visual from explicit candidates (inset, video, image), replacing manual media handling
 - **Semantic theming** — the runtime orchestrates context classes and token resolution, replacing per-component dark mode logic
 - **Engine backgrounds** — the runtime renders section backgrounds from frontmatter, replacing background-handling code in every section
 - **Rich params** — `meta.js` params with types, defaults, and presets replace config objects and conditional logic

package/partials/search-docs.hbs

@@ -14,7 +14,7 @@ pnpm add fuse.js
 Then use the search helpers from `@uniweb/kit`:
 
 ```jsx
-import { useSearch } from '@uniweb/kit/search'
+import { useSearch } from '@uniweb/kit'
 
 function SearchComponent({ website }) {
   const { query, results, isLoading, clear } = useSearch(website)

package/src/commands/add.js

@@ -22,8 +22,10 @@ import {
   discoverSites,
   updateRootScripts,
 } from '../utils/config.js'
+import { validatePackageName, getExistingPackageNames, resolveUniqueName } from '../utils/names.js'
 import { findWorkspaceRoot } from '../utils/workspace.js'
 import { detectPackageManager, filterCmd, installCmd } from '../utils/pm.js'
+import { isNonInteractive, getCliPrefix, stripNonInteractiveFlag, formatOptions } from '../utils/interactive.js'
 import { resolveTemplate } from '../templates/index.js'
 import { validateTemplate } from '../templates/validator.js'
 import { getVersionsForTemplates } from '../versions.js'
@@ -90,13 +92,17 @@ function parseArgs(args) {
 /**
  * Main add command handler
  */
-export async function add(args) {
+export async function add(rawArgs) {
+  const nonInteractive = isNonInteractive(rawArgs)
+  const args = stripNonInteractiveFlag(rawArgs)
+
   if (args[0] === '--help' || args[0] === '-h') {
     showAddHelp()
     return
   }
 
   const pm = detectPackageManager()
+  const prefix = getCliPrefix()
 
   // Find workspace root
   const rootDir = findWorkspaceRoot()
@@ -109,6 +115,18 @@ export async function add(args) {
   // Interactive subcommand chooser when no args given
   let parsed
   if (!args.length || (args[0] && args[0].startsWith('--'))) {
+    if (nonInteractive) {
+      error(`Missing subcommand.\n`)
+      log(formatOptions([
+        { label: 'foundation', description: 'Component library' },
+        { label: 'site', description: 'Content site' },
+        { label: 'extension', description: 'Additional component package' },
+      ]))
+      log('')
+      log(`Usage: ${prefix} add <foundation|site|extension> [name]`)
+      process.exit(1)
+    }
+
     const response = await prompts({
       type: 'select',
       name: 'subcommand',
@@ -157,9 +175,25 @@ export async function add(args) {
  */
 async function addFoundation(rootDir, projectName, opts, pm = 'pnpm') {
   let name = opts.name
+  const existingNames = await getExistingPackageNames(rootDir)
+
+  // Reject reserved names (format + reserved check only — collisions handled at package name level)
+  if (name) {
+    const valid = validatePackageName(name)
+    if (valid !== true) {
+      error(valid)
+      process.exit(1)
+    }
+  }
 
   // Interactive name prompt when name not provided and no --path
   if (!name && !opts.path) {
+    if (isNonInteractive(process.argv)) {
+      error(`Missing foundation name.\n`)
+      log(`Usage: ${getCliPrefix()} add foundation <name>`)
+      process.exit(1)
+    }
+
     const foundations = await discoverFoundations(rootDir)
     const hasDefault = foundations.length === 0 && !existsSync(join(rootDir, 'foundation'))
     const response = await prompts({
@@ -167,11 +201,7 @@ async function addFoundation(rootDir, projectName, opts, pm = 'pnpm') {
       name: 'name',
       message: 'Foundation name:',
       initial: hasDefault ? 'foundation' : undefined,
-      validate: (value) => {
-        if (!value) return 'Name is required'
-        if (!/^[a-z0-9-]+$/.test(value)) return 'Use lowercase letters, numbers, and hyphens'
-        return true
-      },
+      validate: (value) => validatePackageName(value),
     }, {
       onCancel: () => {
         log('\nCancelled.')
@@ -193,9 +223,15 @@ async function addFoundation(rootDir, projectName, opts, pm = 'pnpm') {
     process.exit(1)
   }
 
+  // Compute package name — auto-suffix if it collides with an existing package
+  let packageName = name || opts.project || 'foundation'
+  if (existingNames.has(packageName)) {
+    packageName = resolveUniqueName(packageName, '-foundation', existingNames)
+  }
+
   // Scaffold
   await scaffoldFoundation(fullPath, {
-    name: name || opts.project || 'foundation',
+    name: packageName,
     projectName,
     isExtension: false,
   }, {
@@ -215,7 +251,7 @@ async function addFoundation(rootDir, projectName, opts, pm = 'pnpm') {
   const sites = await discoverSites(rootDir)
   await updateRootScripts(rootDir, sites, pm)
 
-  success(`Created foundation '${name || 'foundation'}' at ${target}/`)
+  success(`Created foundation '${packageName}' at ${target}/`)
   log('')
   log(`Next: ${colors.cyan}${installCmd(pm)}${colors.reset}`)
 }
@@ -225,9 +261,25 @@ async function addFoundation(rootDir, projectName, opts, pm = 'pnpm') {
  */
 async function addSite(rootDir, projectName, opts, pm = 'pnpm') {
   let name = opts.name
+  const existingNames = await getExistingPackageNames(rootDir)
+
+  // Reject reserved names (format + reserved check only — collisions handled at package name level)
+  if (name) {
+    const valid = validatePackageName(name)
+    if (valid !== true) {
+      error(valid)
+      process.exit(1)
+    }
+  }
 
   // Interactive name prompt when name not provided and no --path
   if (!name && !opts.path) {
+    if (isNonInteractive(process.argv)) {
+      error(`Missing site name.\n`)
+      log(`Usage: ${getCliPrefix()} add site <name>`)
+      process.exit(1)
+    }
+
     const existingSites = await discoverSites(rootDir)
     const hasDefault = existingSites.length === 0 && !existsSync(join(rootDir, 'site'))
     const response = await prompts({
@@ -235,11 +287,7 @@ async function addSite(rootDir, projectName, opts, pm = 'pnpm') {
       name: 'name',
       message: 'Site name:',
       initial: hasDefault ? 'site' : undefined,
-      validate: (value) => {
-        if (!value) return 'Name is required'
-        if (!/^[a-z0-9-]+$/.test(value)) return 'Use lowercase letters, numbers, and hyphens'
-        return true
-      },
+      validate: (value) => validatePackageName(value),
     }, {
       onCancel: () => {
         log('\nCancelled.')
@@ -271,6 +319,11 @@ async function addSite(rootDir, projectName, opts, pm = 'pnpm') {
     siteName = name || 'site'
   }
 
+  // Auto-suffix package name if it collides with an existing package
+  if (existingNames.has(siteName)) {
+    siteName = resolveUniqueName(siteName, '-site', existingNames)
+  }
+
   if (foundation) {
     // Compute relative path from site to foundation
     const foundationPath = computeFoundationPath(target, foundation.path)
@@ -334,18 +387,30 @@ async function addSite(rootDir, projectName, opts, pm = 'pnpm') {
  */
 async function addExtension(rootDir, projectName, opts, pm = 'pnpm') {
   let name = opts.name
+  const existingNames = await getExistingPackageNames(rootDir)
+
+  // Reject reserved names (format + reserved check only — collisions handled at package name level)
+  if (name) {
+    const valid = validatePackageName(name)
+    if (valid !== true) {
+      error(valid)
+      process.exit(1)
+    }
+  }
 
   // Interactive name prompt when name not provided
   if (!name) {
+    if (isNonInteractive(process.argv)) {
+      error(`Missing extension name.\n`)
+      log(`Usage: ${getCliPrefix()} add extension <name>`)
+      process.exit(1)
+    }
+
     const response = await prompts({
       type: 'text',
       name: 'name',
       message: 'Extension name:',
-      validate: (value) => {
-        if (!value) return 'Name is required'
-        if (!/^[a-z0-9-]+$/.test(value)) return 'Use lowercase letters, numbers, and hyphens'
-        return true
-      },
+      validate: (value) => validatePackageName(value),
     }, {
       onCancel: () => {
         log('\nCancelled.')
@@ -355,6 +420,11 @@ async function addExtension(rootDir, projectName, opts, pm = 'pnpm') {
     name = response.name
   }
 
+  // Auto-suffix package name if it collides with an existing package
+  const extensionPackageName = existingNames.has(name)
+    ? resolveUniqueName(name, '-ext', existingNames)
+    : name
+
   // Determine target
   let target
   if (opts.path) {
@@ -372,7 +442,7 @@ async function addExtension(rootDir, projectName, opts, pm = 'pnpm') {
 
   // Scaffold foundation with extension flag
   await scaffoldFoundation(fullPath, {
-    name,
+    name: extensionPackageName,
     projectName,
     isExtension: true,
   }, {
@@ -494,7 +564,18 @@ async function resolveFoundation(rootDir, foundationFlag) {
     return foundations[0]
   }
 
-  // Multiple foundations — prompt
+  // Multiple foundations — prompt (or fail in non-interactive mode)
+  if (isNonInteractive(process.argv)) {
+    error(`Multiple foundations found. Specify which to use:\n`)
+    log(formatOptions(foundations.map(f => ({
+      label: f.name,
+      description: f.path,
+    }))))
+    log('')
+    log(`Usage: ${getCliPrefix()} add site <name> --foundation <name>`)
+    process.exit(1)
+  }
+
   const response = await prompts({
     type: 'select',
     name: 'foundation',

package/src/commands/docs.js

@@ -29,6 +29,7 @@ import {
   findFoundations,
   promptSelect,
 } from '../utils/workspace.js'
+import { isNonInteractive, getCliPrefix, formatOptions } from '../utils/interactive.js'
 
 // Colors for terminal output
 const colors = {
@@ -394,6 +395,12 @@ async function generateComponentDocs(args) {
     if (foundations.length === 1) {
       targetFoundation = foundations[0]
       info(`Found foundation: ${targetFoundation}`)
+    } else if (isNonInteractive(process.argv)) {
+      error(`Multiple foundations found. Specify which to target:\n`)
+      log(formatOptions(foundations.map(f => ({ label: f, description: '' }))))
+      log('')
+      log(`Usage: ${getCliPrefix()} docs --target <path>`)
+      process.exit(1)
     } else {
       log(`${colors.dim}Multiple foundations found in workspace.${colors.reset}\n`)
       targetFoundation = await promptSelect('Select foundation:', foundations)

package/src/index.js

@@ -29,6 +29,7 @@ import {
 import { validateTemplate } from './templates/validator.js'
 import { scaffoldWorkspace, scaffoldFoundation, scaffoldSite, applyContent, applyStarter, mergeTemplateDependencies } from './utils/scaffold.js'
 import { detectPackageManager, filterCmd, installCmd, runCmd } from './utils/pm.js'
+import { isNonInteractive, getCliPrefix, stripNonInteractiveFlag, formatOptions } from './utils/interactive.js'
 
 // Colors for terminal output
 const colors = {
@@ -288,7 +289,9 @@ function computeFoundationFilePath(sitePath, foundationPath) {
 }
 
 async function main() {
-  const args = process.argv.slice(2)
+  const rawArgs = process.argv.slice(2)
+  const nonInteractive = isNonInteractive(rawArgs)
+  const args = stripNonInteractiveFlag(rawArgs)
   const command = args[0]
   const pm = detectPackageManager()
 
@@ -369,6 +372,26 @@ async function main() {
     projectName = null
   }
 
+  const prefix = getCliPrefix()
+
+  // Non-interactive: fail with actionable message instead of prompting
+  if (nonInteractive && !projectName) {
+    error(`Missing project name.\n`)
+    log(`Usage: ${prefix} create <project-name> [--template <name>]`)
+    process.exit(1)
+  }
+
+  if (nonInteractive && !templateType) {
+    error(`Missing --template flag. Available templates:\n`)
+    log(formatOptions(TEMPLATE_CHOICES.map(c => ({
+      label: c.value,
+      description: c.description,
+    }))))
+    log('')
+    log(`Usage: ${prefix} create ${projectName || '<project-name>'} --template <name>`)
+    process.exit(1)
+  }
+
   // Interactive prompts
   const response = await prompts([
     {
@@ -539,6 +562,10 @@ ${colors.bright}Add Subcommands:${colors.reset}
   add site [name]         Add a site (--from, --foundation, --path, --project)
   add extension <name>    Add an extension (--from, --site, --path)
 
+${colors.bright}Global Options:${colors.reset}
+  --non-interactive    Fail with usage info instead of prompting
+                       Auto-detected when CI=true or no TTY (pipes, agents)
+
 ${colors.bright}Build Options:${colors.reset}
   --target <type>    Build target (foundation, site) - auto-detected if not specified
   --prerender        Force pre-rendering (overrides site.yml)

package/src/utils/interactive.js

@@ -0,0 +1,53 @@
+/**
+ * Non-Interactive Mode Detection
+ *
+ * Detects when the CLI is running without a TTY (AI agents, CI, piped input)
+ * and provides helpers for printing actionable error messages.
+ */
+
+/**
+ * Detect if the CLI is running in non-interactive mode.
+ * True when --non-interactive flag, CI env var, or no TTY.
+ * @param {string[]} args - Command line arguments
+ * @returns {boolean}
+ */
+export function isNonInteractive(args) {
+  if (args.includes('--non-interactive')) return true
+  if (process.env.CI) return true
+  if (!process.stdin.isTTY) return true
+  return false
+}
+
+/**
+ * Get the CLI invocation prefix to use in suggested commands.
+ * Mirrors however the user actually ran the CLI.
+ * @returns {string}
+ */
+export function getCliPrefix() {
+  const ua = process.env.npm_config_user_agent || ''
+  if (ua.startsWith('pnpm/')) return 'pnpm uniweb'
+  if (ua.startsWith('npm/')) return 'npx uniweb'
+  return 'uniweb'
+}
+
+/**
+ * Strip --non-interactive from an args array so it doesn't interfere
+ * with positional argument parsing.
+ * @param {string[]} args
+ * @returns {string[]}
+ */
+export function stripNonInteractiveFlag(args) {
+  return args.filter(a => a !== '--non-interactive')
+}
+
+/**
+ * Format a list of options with aligned descriptions for terminal output.
+ * @param {{ label: string, description: string }[]} options
+ * @returns {string}
+ */
+export function formatOptions(options) {
+  const maxLen = Math.max(...options.map(o => o.label.length))
+  return options
+    .map(o => `  ${o.label.padEnd(maxLen + 3)}${o.description}`)
+    .join('\n')
+}

package/src/utils/names.js

@@ -0,0 +1,91 @@
+/**
+ * Package Name Validation
+ *
+ * Validates package names for the `add` command — rejects reserved names
+ * and detects collisions with existing workspace packages.
+ */
+
+import { discoverFoundations, discoverSites, readWorkspaceConfig, resolveGlob } from './config.js'
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/**
+ * Names that must not be used as package names.
+ * - JS module keywords: default, undefined, null, true, false
+ * - Node/filesystem: node_modules, package
+ * - Common directory names that would cause confusion: src, dist, build
+ */
+const RESERVED_NAMES = new Set([
+  'default', 'undefined', 'null', 'true', 'false',
+  'node_modules', 'package',
+  'src', 'dist', 'build',
+])
+
+/**
+ * Validate a package name.
+ * @param {string} name
+ * @param {Set<string>} [existingNames] - Names already in the workspace
+ * @returns {string|true} true if valid, or an error message string
+ */
+export function validatePackageName(name, existingNames) {
+  if (!name) return 'Name is required'
+  if (!/^[a-z0-9-]+$/.test(name)) return 'Use lowercase letters, numbers, and hyphens'
+  if (RESERVED_NAMES.has(name)) return `"${name}" is a reserved name — choose a different one`
+  if (existingNames?.has(name)) return `"${name}" already exists in this workspace`
+  return true
+}
+
+/**
+ * Discover all package names in the workspace (foundations + sites + extensions).
+ * @param {string} rootDir - Workspace root directory
+ * @returns {Promise<Set<string>>}
+ */
+export async function getExistingPackageNames(rootDir) {
+  const names = new Set()
+
+  // Foundations and sites via existing discovery
+  const foundations = await discoverFoundations(rootDir)
+  const sites = await discoverSites(rootDir)
+
+  for (const f of foundations) names.add(f.name)
+  for (const s of sites) names.add(s.name)
+
+  // Extensions (foundations with @uniweb/runtime absent — already captured above)
+  // Also scan extensions/* if it exists
+  const extensionsDir = join(rootDir, 'extensions')
+  if (existsSync(extensionsDir)) {
+    const dirs = await resolveGlob(rootDir, 'extensions/*')
+    for (const dir of dirs) {
+      const pkgPath = join(rootDir, dir, 'package.json')
+      if (!existsSync(pkgPath)) continue
+      try {
+        const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'))
+        if (pkg.name) names.add(pkg.name)
+      } catch {
+        // skip
+      }
+    }
+  }
+
+  return names
+}
+
+/**
+ * Resolve a unique name by appending a suffix if there's a collision.
+ * @param {string} name - Proposed name
+ * @param {string} suffix - Suffix to append (e.g., '-site', '-foundation')
+ * @param {Set<string>} existingNames
+ * @returns {string} The resolved unique name
+ */
+export function resolveUniqueName(name, suffix, existingNames) {
+  if (!existingNames.has(name)) return name
+  const suffixed = `${name}${suffix}`
+  if (!existingNames.has(suffixed)) return suffixed
+  // Unlikely: both name and name-suffix taken — append number
+  for (let i = 2; i < 100; i++) {
+    const numbered = `${name}${suffix}-${i}`
+    if (!existingNames.has(numbered)) return numbered
+  }
+  return suffixed // give up
+}

package/templates/foundation/src/styles.css

@@ -2,4 +2,5 @@
 @import "@uniweb/kit/theme-tokens.css";
 
 @source "./sections/**/*.{js,jsx}";
+@source "./layouts/**/*.{js,jsx}";
 @source "../node_modules/@uniweb/kit/src/**/*.{js,jsx}";

package/templates/site/theme.yml

@@ -1 +1,99 @@
-primary: '#3b82f6'
+# Theme Configuration
+# Controls colors, typography, and visual style for the site.
+# Only set what you want to change — everything has sensible defaults.
+
+# ─── Colors ────────────────────────────────────────────────────────────────────
+# Palette colors generate shades (50–950) used by semantic tokens.
+# Values: any CSS color (hex, rgb, hsl, oklch).
+
+colors:
+  primary: '#3b82f6'        # Brand color — buttons, links, focus rings
+  # secondary: '#64748b'    # Secondary actions
+  # accent: '#8b5cf6'       # Highlights, decorative elements
+  # neutral: stone           # Gray family — stone, zinc, gray, slate, neutral
+
+# ─── Fonts ─────────────────────────────────────────────────────────────────────
+# Font families for text, headings, and code blocks.
+# Default: system-ui stack. Uncomment to use custom fonts.
+
+# fonts:
+#   heading: '"Inter", system-ui, sans-serif'
+#   body: '"Inter", system-ui, sans-serif'
+#   mono: '"JetBrains Mono", ui-monospace, monospace'
+#   import:
+#     - url: https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap
+#     - url: https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500&display=swap
+
+# ─── Page Background ──────────────────────────────────────────────────────────
+# Background applied to the page body. Any CSS background value.
+
+# background: '#fafaf9'
+# background: 'linear-gradient(to bottom, #fafaf9, white)'
+
+# ─── Appearance ────────────────────────────────────────────────────────────────
+# Color scheme support. Simple value: light, dark, or system.
+# Or use the expanded form for more control.
+
+# appearance: light
+# appearance:
+#   default: light
+#   schemes: [light, dark]
+#   allowToggle: true
+#   respectSystemPreference: true
+
+# ─── Context Overrides ─────────────────────────────────────────────────────────
+# Sections declare a context (light, medium, dark) in frontmatter.
+# Each context maps semantic tokens to palette values.
+# Override individual tokens here — unlisted tokens keep their defaults.
+#
+# Available tokens:
+#   Surfaces:  section, card, muted
+#   Text:      body, heading, subtle
+#   Border:    border, ring
+#   Links:     link, link-hover
+#   Actions:   primary, primary-foreground, primary-hover
+#              secondary, secondary-foreground, secondary-hover
+#   Status:    success, warning, error, info (+ -subtle variants)
+
+# contexts:
+#   light:
+#     section: white
+#   medium:
+#     section: 'var(--neutral-100)'
+#   dark:
+#     heading: white
+
+# ─── Inline Text Styles ───────────────────────────────────────────────────────
+# Named styles for inline text in markdown: [text]{emphasis}
+# Each name maps to CSS properties.
+# Defaults: emphasis (colored + bold), muted (subtle).
+
+# inline:
+#   emphasis:
+#     color: 'var(--link)'
+#     font-weight: '600'
+#   muted:
+#     color: 'var(--subtle)'
+
+# ─── Code Blocks ───────────────────────────────────────────────────────────────
+# Syntax highlighting colors for code blocks (uses Shiki).
+
+# code:
+#   background: '#1e1e2e'
+#   foreground: '#cdd6f4'
+#   keyword: '#cba6f7'
+#   string: '#a6e3a1'
+#   number: '#fab387'
+#   comment: '#6c7086'
+#   function: '#89b4fa'
+#   variable: '#f5e0dc'
+#   type: '#f9e2af'
+#   property: '#94e2d5'
+#   tag: '#89b4fa'
+
+# ─── Foundation Variables ──────────────────────────────────────────────────────
+# Override variables declared by the foundation (e.g., header-height, max-width).
+# Available variables depend on the foundation — check its foundation.js.
+
+# vars:
+#   header-height: 5rem