uniweb 0.8.7 → 0.8.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.8.7",
+  "version": "0.8.8",
   "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.6",
-    "@uniweb/runtime": "0.6.5",
-    "@uniweb/kit": "0.7.4",
-    "@uniweb/core": "0.5.5"
+    "@uniweb/build": "0.8.7",
+    "@uniweb/kit": "0.7.5",
+    "@uniweb/core": "0.5.6",
+    "@uniweb/runtime": "0.6.6"
   }
 }

package/partials/agents.md

@@ -1,5 +1,7 @@
 # AGENTS.md
 
+> A comprehensive guide to building with Uniweb — for developers and AI assistants alike.
+
 Uniweb is a Component Content Architecture (CCA). Content lives in markdown, code lives in React components, and a runtime connects them. The runtime handles section wrapping, background rendering, context theming, and token resolution — components receive pre-parsed content and render it with semantic tokens. Understanding what the runtime does (and therefore what components should *not* do) is the key to working effectively in this architecture.
 
 ## Documentation
@@ -135,9 +137,9 @@ The semantic parser extracts markdown into a flat, guaranteed structure. No null
 
 ```js
 content = {
-  title: '',        // Main heading
+  title: '',        // Main heading (string or string[] for multi-line)
   pretitle: '',     // Heading before main title (auto-detected)
-  subtitle: '',     // Heading after title
+  subtitle: '',     // Heading after title (string or string[] for multi-line)
   subtitle2: '',    // Third-level heading
   paragraphs: [],   // Text blocks
   links: [],        // { href, label, role } — standalone links become buttons
@@ -194,6 +196,55 @@ Enterprise-grade security.     │  content.items[1].paragraphs[0] = "Enterprise
 
 Headings before the main title become `pretitle`. Headings after the main title at a lower importance become `subtitle`. Headings that appear after body content (paragraphs, links, images) start the `items` array.
 
+### Multi-Line Headings
+
+Consecutive headings at the same level merge into a title array — a single heading split across visual lines:
+
+```markdown
+# Build the future              │  content.title = ["Build the future", "with confidence"]
+# with confidence               │
+```
+
+Kit's `<H1>`, `<H2>`, etc. render arrays as a single tag with line breaks. This is how you create dramatic multi-line hero headlines.
+
+**Works with accent styling:**
+
+```markdown
+# Build the future              │  content.title = [
+# [with confidence]{accent}     │    "Build the future",
+                                │    "<span accent=\"true\">with confidence</span>"
+                                │  ]
+```
+
+**Works at any heading slot** — title, subtitle, items:
+
+```markdown
+### Our Mission                 │  content.pretitle = "Our Mission"
+# Build the future              │  content.title = ["Build the future",
+# with confidence               │                   "with confidence"]
+## The platform for             │  content.subtitle = ["The platform for",
+## modern teams                 │                      "modern teams"]
+```
+
+**Rule:** Same-level continuation only applies before going deeper. Once a subtitle level is reached, same-level headings start new items instead of merging:
+
+```markdown
+# Features                      │  title = "Features"
+                                │
+We built this for you.          │  paragraph
+                                │
+### Fast                        │  items[0].title = "Fast"
+### Secure                      │  items[1].title = "Secure" ← new item, not merged
+```
+
+Use `---` to force separate items when same-level headings would otherwise merge:
+
+```markdown
+# Line one                      │  title = "Line one"
+---                             │  ← divider forces split
+# Line two                      │  items[0].title = "Line two"
+```
+
 **Lists** contain bullet or ordered list items. Each list item is an object with the same content shape — not a plain string:
 
 ```markdown
@@ -280,6 +331,49 @@ Links mixed with non-link text stay as inline `<a>` tags within `content.paragra
 Check out [this](/a) and [that](/b).   ← inline links in paragraph text, NOT in content.links[]
 ```
 
+### Inline Text Styling
+
+Style specific words or phrases using bracketed spans with boolean attributes:
+
+```markdown
+# Build [faster]{accent} with structure
+
+This is [less important]{muted} context.
+```
+
+The framework provides two defaults: `accent` (colored + bold) and `muted` (subtle). These adapt to context automatically — in dark sections, `accent` resolves to a lighter shade.
+
+**What you write → what components receive:**
+
+| Markdown | HTML in content string |
+|----------|----------------------|
+| `[text]{accent}` | `<span accent="true">text</span>` |
+| `[text]{muted}` | `<span muted="true">text</span>` |
+| `[text]{color=red}` | `<span style="color: red">text</span>` |
+
+CSS is generated from `theme.yml`'s `inline:` section using attribute selectors (`span[accent] { ... }`). Sites can define additional named styles:
+
+```yaml
+inline:
+  accent:
+    color: var(--link)
+    font-weight: '600'
+  callout:
+    color: var(--accent-600)
+    font-style: italic
+```
+
+**Common pattern — accented multi-line hero heading:**
+
+```markdown
+# Build the future
+# [with confidence]{accent}
+```
+
+This produces `content.title = ["Build the future", "<span accent=\"true\">with confidence</span>"]` — an array rendered as a single `<h1>` with visual line breaks. See [Multi-Line Headings](#multi-line-headings) for details.
+
+Components receive HTML strings with the spans already applied. Kit's `<H1>`, `<P>`, etc. render them correctly via `dangerouslySetInnerHTML`.
+
 ### Structured Data
 
 Tagged code blocks pass structured data via `content.data`:
@@ -621,7 +715,7 @@ fonts:
   body: "'Inter', system-ui, sans-serif"
 
 inline:
-  emphasis:                 # For [text]{emphasis} in markdown
+  accent:                   # For [text]{accent} in markdown
     color: var(--link)
     font-weight: '600'
 
@@ -834,7 +928,7 @@ export default {
   title: 'Feature Grid',
   description: 'Grid of feature cards with icons',
   category: 'marketing',
-  // hidden: true,          // Hide from content authors
+  // hidden: true,          // Exclude from export (internal/helper component)
   // background: 'self',    // Component renders its own background
   // inset: true,           // Available for @ComponentName references in markdown
   // visuals: 1,            // Expects 1 visual (image, video, or inset)
@@ -872,11 +966,13 @@ Content fields (`title`, `pretitle`, `paragraphs[]`, list item text) are **HTML
 **Rendering text** (`@uniweb/kit`):
 
 ```jsx
-import { H2, P, Span } from '@uniweb/kit'
+import { H1, 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>
+<H1 text={content.title} className="text-heading text-5xl font-bold" />
+  // string → single <h1>, array → single <h1> with line breaks (multi-line headings)
+<H2 text={content.subtitle} className="text-heading text-3xl font-bold" />
+<P text={content.paragraphs} className="text-body" />
+  // array → each string becomes its own <p>
 <Span text={listItem.paragraphs[0]} className="text-subtle" />
 ```
 
@@ -956,7 +1052,8 @@ Only folders with `meta.js` in `sections/` (or `components/` for older foundatio
 ### Website and Page APIs
 
 ```jsx
-const { website } = useWebsite()
+const { website } = useWebsite()  // or block.website
+const page = website.activePage   // or block.page 
 
 // Navigation
 const pages = website.getPageHierarchy({ for: 'header' })  // or 'footer'
@@ -1019,17 +1116,18 @@ function SplitContent({ content, block }) {
 
 **SSG and hooks:** Inset components that use React hooks (useState, useEffect) will trigger prerender warnings during `pnpm build`. This is expected — the SSG pipeline cannot render hooks due to dual React instances in the build. The warnings are informational; the page renders correctly client-side. If you see `"Skipped SSG for /..."` or `"Invalid hook call"`, this is the cause.
 
-Inset components declare `inset: true` in meta.js. Use `hidden: true` for inset-only components:
+Inset components declare `inset: true` in meta.js:
 
 ```js
 // sections/insets/NetworkDiagram/meta.js
 export default {
   inset: true,
-  hidden: true,
   params: { variant: { type: 'select', options: ['full', 'compact'], default: 'full' } },
 }
 ```
 
+Whether an inset appears in a section palette is a concern of the parent component (via `children` and `insets` in its meta.js), not a property of the inset itself. Don't use `hidden: true` on insets — `hidden` means "don't export this component at all" (internal helpers, not-yet-ready components).
+
 ### Dispatcher Pattern
 
 One section type with a `variant` param replaces multiple near-duplicates. Instead of `HeroLeft`, `HeroCentered`, `HeroSplit` — one `Hero` with `variant: left | centered | split`:
@@ -1208,7 +1306,7 @@ Semantic color tokens (`text-heading`, `bg-section`, `bg-primary`, etc.) come fr
 
 **"Could not load foundation"** — Check `site/package.json` has `"foundation": "file:../foundation"` (or `"default": "file:../../foundations/default"` for multi-site).
 
-**Component not appearing** — Verify `meta.js` exists and doesn't have `hidden: true`. Rebuild: `cd foundation && pnpm build`.
+**Component not appearing** — Verify `meta.js` exists. Check for `hidden: true` (means component is excluded from export — only use for internal helpers). Rebuild: `cd foundation && pnpm build`.
 
 **Styles not applying** — Verify `@source` in `styles.css` includes your component paths. Check custom colors match `@theme` definitions.
 

package/partials/ai-assistance.hbs

@@ -1,8 +1,10 @@
-## AI Assistance
+## Developer Guide
 
-This project includes an [AGENTS.md](./AGENTS.md) file with detailed instructions for AI coding assistants (Claude Code, Cursor, Copilot, etc.).
+[AGENTS.md](./AGENTS.md) is a comprehensive guide to building with Uniweb — content authoring, component development, theming, configuration, and the kit API. Despite the name, it's written for developers and AI assistants alike. Read it to get productive fast.
 
-### Example Prompts
+### AI Prompts
+
+AI coding assistants (Claude Code, Cursor, Copilot, etc.) read AGENTS.md automatically. Some prompts to try:
 
 **Converting an existing design:**
 ```

package/partials/learn-more.hbs

@@ -1,5 +1,6 @@
 ## Learn More
 
-- [Uniweb Documentation](https://github.com/uniweb/cli)
-- [@uniweb/kit Components](https://www.npmjs.com/package/@uniweb/kit)
+- [AGENTS.md](./AGENTS.md) — comprehensive guide to building with Uniweb
+- [Uniweb Documentation](https://github.com/uniweb/docs) — full reference docs
+- [Uniweb CLI](https://github.com/uniweb/cli) — project scaffolding and build tools
 - [Tailwind CSS v4](https://tailwindcss.com)

package/starter/foundation/src/sections/Section/index.jsx

@@ -1,37 +1,25 @@
-import React from 'react'
 import { H1, H2, P, Link, cn } from '@uniweb/kit'
 
 /**
  * Section Component
  *
  * A versatile content section that handles headings, text, and links.
- * This is the default component for rendering markdown content.
+ * Uses semantic tokens so it adapts to any theme context automatically.
  */
-function Section({ content, params }) {
-  // Content fields: title, pretitle, subtitle, paragraphs, links, imgs, items
+export default function Section({ content, params }) {
   const { title, pretitle, subtitle, paragraphs = [], links = [], imgs = [] } = content || {}
 
   const {
-    theme = 'light',
     align = 'center',
     width = 'default',
   } = params || {}
 
-  // Theme styles
-  const themes = {
-    light: 'bg-white text-gray-900',
-    dark: 'bg-gray-900 text-white',
-    primary: 'bg-primary text-white',
-  }
-
-  // Alignment styles
   const alignments = {
     left: 'text-left',
     center: 'text-center',
     right: 'text-right',
   }
 
-  // Width styles
   const widths = {
     narrow: 'max-w-2xl',
     default: 'max-w-4xl',
@@ -40,58 +28,47 @@ function Section({ content, params }) {
   }
 
   return (
-    <section className={cn('py-16 px-6', themes[theme])}>
-      <div className={cn('mx-auto', widths[width], alignments[align])}>
-        {/* Pretitle / Eyebrow */}
+    <div className={cn('py-16 px-6', alignments[align])}>
+      <div className={cn('mx-auto', widths[width])}>
         {pretitle && (
-          <p className="text-sm font-medium text-primary mb-4 uppercase tracking-wide">
+          <p className="text-sm font-medium text-link mb-4 uppercase tracking-wide">
             {pretitle}
           </p>
         )}
 
-        {/* Title */}
         {title && (
           <H1
             text={title}
-            className="text-3xl sm:text-4xl font-bold mb-4"
+            className="text-heading text-3xl sm:text-4xl font-bold mb-4"
           />
         )}
 
-        {/* Subtitle */}
         {subtitle && (
           <H2
             text={subtitle}
-            className={cn(
-              'text-xl mb-6',
-              theme === 'light' ? 'text-gray-600' : 'text-gray-300'
-            )}
+            className="text-body text-xl mb-6"
           />
         )}
 
-        {/* Paragraphs */}
         {paragraphs.map((para, index) => (
           <P
             key={index}
             text={para}
-            className={cn(
-              'text-lg mb-4 leading-relaxed',
-              theme === 'light' ? 'text-gray-700' : 'text-gray-300'
-            )}
+            className="text-body text-lg mb-4 leading-relaxed"
           />
         ))}
 
-        {/* Links */}
         {links.length > 0 && (
-          <div className={cn('mt-8 flex gap-4 flex-wrap', alignments[align] === 'text-center' && 'justify-center')}>
+          <div className={cn('mt-8 flex gap-4 flex-wrap', align === 'center' && 'justify-center')}>
             {links.map((link, index) => (
               <Link
                 key={index}
-                href={link.href}
+                to={link.href}
                 className={cn(
                   'inline-flex items-center px-6 py-3 font-medium rounded-lg transition-colors',
                   index === 0
-                    ? 'bg-primary-600 text-white hover:bg-primary-700'
-                    : 'border border-current hover:bg-gray-100'
+                    ? 'bg-primary text-primary-foreground hover:bg-primary-hover'
+                    : 'bg-secondary text-secondary-foreground hover:bg-secondary-hover'
                 )}
               >
                 {link.label}
@@ -100,7 +77,6 @@ function Section({ content, params }) {
           </div>
         )}
 
-        {/* Images */}
         {imgs.length > 0 && (
           <div className="mt-8">
             {imgs.map((img, index) => (
@@ -114,8 +90,6 @@ function Section({ content, params }) {
           </div>
         )}
       </div>
-    </section>
+    </div>
   )
 }
-
-export default Section

package/starter/foundation/src/sections/Section/meta.js

@@ -1,8 +1,3 @@
-/**
- * Section Component Metadata (v2)
- *
- * A versatile content section for headings, text, and links.
- */
 export default {
   title: 'Section',
   description: 'A versatile content section for headings, text, and links',
@@ -19,12 +14,6 @@ export default {
   },
 
   params: {
-    theme: {
-      type: 'select',
-      label: 'Theme',
-      options: ['light', 'dark', 'primary'],
-      default: 'light',
-    },
     align: {
       type: 'select',
       label: 'Alignment',
@@ -47,15 +36,11 @@ export default {
   presets: {
     default: {
       label: 'Centered',
-      params: { theme: 'light', align: 'center' },
-    },
-    dark: {
-      label: 'Dark Theme',
-      params: { theme: 'dark', align: 'center' },
+      params: { align: 'center' },
     },
     left: {
       label: 'Left Aligned',
-      params: { theme: 'light', align: 'left' },
+      params: { align: 'left' },
     },
   },
 }

package/starter/site/pages/home/1-welcome.md.hbs

@@ -8,7 +8,7 @@ align: center
 
 ## Your Uniweb project is ready
 
-This is a minimal starting point for your Uniweb project. Edit the content in `site/pages/` and customize the components in `foundation/src/components/`.
+This is a minimal starting point for your Uniweb project. Edit the content in `site/pages/` and build section types in `foundation/src/sections/`.
 
 [About](/about)
 [Documentation](https://github.com/uniweb)

package/templates/site/theme.yml

@@ -64,12 +64,12 @@ colors:
 #     heading: white
 
 # ─── Inline Text Styles ───────────────────────────────────────────────────────
-# Named styles for inline text in markdown: [text]{emphasis}
+# Named styles for inline text in markdown: [text]{accent}
 # Each name maps to CSS properties.
-# Defaults: emphasis (colored + bold), muted (subtle).
+# Defaults: accent (colored + bold), muted (subtle).
 
 # inline:
-#   emphasis:
+#   accent:
 #     color: 'var(--link)'
 #     font-weight: '600'
 #   muted:

package/templates/workspace/README.md.hbs

@@ -10,7 +10,7 @@ A website built with [Uniweb](https://github.com/uniweb/cli) — a component web
 {{projectName}}/
 ├── foundation/          # React component library
 │   ├── src/
-│   │   ├── components/  # Your components
+│   │   ├── sections/    # Section types (selectable by content authors)
 │   │   └── styles.css   # Tailwind CSS v4 theme
 │   └── vite.config.js   # defineFoundationConfig()
 │
@@ -22,7 +22,7 @@ A website built with [Uniweb](https://github.com/uniweb/cli) — a component web
 │   ├── site.yml         # Site configuration
 │   └── vite.config.js   # defineSiteConfig()
 │
-└── AGENTS.md            # AI assistant instructions
+└── AGENTS.md            # Developer guide (human + AI)
 ```
 
 ## Content Authoring
@@ -46,27 +46,25 @@ Your content here.
 
 ## Component Development
 
-Components live in `foundation/src/components/`:
+Section types live in `foundation/src/sections/`. Each is a folder with an `index.jsx` and a `meta.js`:
 
 ```jsx
-// foundation/src/components/Hero/index.jsx
-import { H1, P, cn } from '@uniweb/kit'
+// foundation/src/sections/Hero/index.jsx
+import { H1, P } from '@uniweb/kit'
 
-export function Hero({ content, params }) {
-  const { title } = content.main?.header || {}
-  const { theme = 'light' } = params
+export default function Hero({ content }) {
+  const { title, paragraphs = [] } = content || {}
 
   return (
-    <section className={cn('py-20', theme === 'dark' && 'bg-gray-900')}>
-      <H1 text={title} />
-    </section>
+    <div className="max-w-4xl mx-auto px-6">
+      <H1 text={title} className="text-heading text-4xl font-bold" />
+      <P text={paragraphs} className="text-body mt-4" />
+    </div>
   )
 }
-
-export default Hero
 ```
 
-Exposed components (selectable via `type:` in frontmatter) need a `meta.js` file.
+Components receive parsed content from markdown. Classes like `text-heading` and `text-body` are semantic tokens — the site controls their actual colors through theming, so the same component adapts to any context automatically.
 
 {{> components-docs}}