@invisibleloop/pulse 0.12.3 → 0.14.2

package/scripts/build.js

@@ -19,6 +19,7 @@ import path         from 'path'
 import { createHash } from 'crypto'
 import { discoverPages } from '../src/cli/discover.js'
 import { renderToString } from '../src/runtime/ssr.js'
+import { c, header, table, ok, fail, info, elapsed, icon } from '../src/cli/fmt.js'
 
 // ---------------------------------------------------------------------------
 // Server-only property stripping
@@ -386,10 +387,16 @@ const TMP_DIR = path.join(ROOT, '.pulse-build')
 const pages = discoverPages(ROOT)
 
 if (pages.length === 0) {
-  console.error('No pages found in src/pages/. Nothing to build.')
+  console.error(fail('No pages found in src/pages/ — nothing to build.'))
   process.exit(1)
 }
 
+// ---------------------------------------------------------------------------
+// Timing
+// ---------------------------------------------------------------------------
+
+const BUILD_START = Date.now()
+
 // ---------------------------------------------------------------------------
 // Clean output directories
 // ---------------------------------------------------------------------------
@@ -399,7 +406,7 @@ for (const dir of [OUT_DIR, TMP_DIR]) {
   fs.mkdirSync(dir, { recursive: true })
 }
 
-console.log('⚡ Building Pulse client bundles...\n')
+console.log(header(`Building ${pages.length} page${pages.length === 1 ? '' : 's'}`))
 
 // ---------------------------------------------------------------------------
 // Generate bootstrap entry points
@@ -518,20 +525,66 @@ await purgeCssStep(pages, manifest, ROOT, OUT_DIR)
 await jsAssetsStep(ROOT, OUT_DIR, manifest)
 
 // ---------------------------------------------------------------------------
-// Report
+// Summary table
 // ---------------------------------------------------------------------------
 
-console.log('Bundles:\n')
-for (const [src, bundle] of Object.entries(manifest)) {
-  if (bundle.startsWith('/dist/')) {
+{
+  const rows = []
+
+  for (const [src, bundle] of Object.entries(manifest)) {
+    // Skip runtime chunk and static assets — only show per-page bundles + CSS
+    if (!bundle.startsWith('/dist/')) continue
     const filePath = path.join(ROOT, 'public', bundle)
-    if (fs.existsSync(filePath)) {
-      const size = fs.statSync(filePath).size
-      console.log(`  ${src.padEnd(36)} → ${bundle}  (${(size / 1024).toFixed(1)} kB)`)
+    if (!fs.existsSync(filePath)) continue
+
+    const sizeBytes = fs.statSync(filePath).size
+    const sizeKb    = (sizeBytes / 1024).toFixed(1)
+    const ext       = path.extname(bundle)
+
+    if (ext === '.js' && src.startsWith('/src/pages/')) {
+      // Per-page JS bundle — find if it's hydrated
+      const srcPath = path.join(ROOT, src.replace(/^\//, ''))
+      let route = src.replace('/src/pages', '').replace(/\.js$/, '')
+      // Try to extract route from the spec
+      try {
+        const specSrc = fs.readFileSync(srcPath, 'utf8')
+        const m = specSrc.match(/route\s*:\s*['"`]([^'"`]+)['"`]/)
+        if (m) route = m[1]
+      } catch { /* use filename-derived route */ }
+      rows.push([
+        c.cyan(route),
+        c.dim(bundle.replace('/dist/', '')),
+        `${sizeKb} kB`,
+        c.dim('js'),
+      ])
+    } else if (ext === '.css') {
+      rows.push([
+        c.dim(src),
+        c.dim(bundle.replace('/dist/', '')),
+        `${sizeKb} kB`,
+        c.dim('css'),
+      ])
     }
   }
+
+  // Sort: pages first, then CSS, then other
+  rows.sort((a, b) => {
+    const aIsPage = a[3].includes('js')
+    const bIsPage = b[3].includes('js')
+    if (aIsPage && !bIsPage) return -1
+    if (!aIsPage && bIsPage) return 1
+    return 0
+  })
+
+  console.log('\n' + table(
+    ['Route / Asset', 'Bundle', 'Size', 'Type'],
+    rows,
+    { align: ['left', 'left', 'right', 'left'] }
+  ))
+
+  const totalMs = Date.now() - BUILD_START
+  console.log(`\n${ok(`Build complete`)}  ${c.dim(elapsed(totalMs))}  ${c.dim('→')}  ${c.dim('public/dist/')}\n`)
 }
-console.log('\n✓ manifest written to public/dist/manifest.json\n')
 
 // ---------------------------------------------------------------------------
 // JS static assets implementation
@@ -544,7 +597,7 @@ async function jsAssetsStep(root, outDir, manifest) {
   const jsFiles = fs.readdirSync(publicDir).filter(f => f.endsWith('.js'))
   if (jsFiles.length === 0) return
 
-  console.log('⚡ Hashing static JS assets...\n')
+  console.log(info('Hashing static JS assets…'))
 
   for (const file of jsFiles) {
     const srcPath = path.join(publicDir, file)
@@ -559,11 +612,11 @@ async function jsAssetsStep(root, outDir, manifest) {
 
     const origKb = (Buffer.byteLength(source) / 1024).toFixed(1)
     const minKb  = (Buffer.byteLength(code)   / 1024).toFixed(1)
-    console.log(`  /${file.padEnd(24)} → /dist/${outName}  (${minKb} kB from ${origKb} kB)`)
+    // silent — summary table covers this
   }
 
   fs.writeFileSync(path.join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2))
-  console.log('\n✓ JS asset entries added to manifest\n')
+  // silent — summary table covers this
 }
 
 // ---------------------------------------------------------------------------
@@ -571,7 +624,7 @@ async function jsAssetsStep(root, outDir, manifest) {
 // ---------------------------------------------------------------------------
 
 async function purgeCssStep(pages, manifest, root, outDir) {
-  console.log('⚡ Purging CSS...\n')
+  console.log(info('Purging CSS…'))
 
   const htmlContents = []
   const jsContents   = []
@@ -633,7 +686,7 @@ async function purgeCssStep(pages, manifest, root, outDir) {
   }
 
   if (cssFiles.size === 0) {
-    console.log('  No CSS files referenced — skipping.\n')
+    console.log(info('No CSS files referenced — skipping.'))
     return
   }
 
@@ -658,14 +711,14 @@ async function purgeCssStep(pages, manifest, root, outDir) {
     const purgKb  = (Buffer.byteLength(purged)   / 1024).toFixed(1)
     const pct     = Math.round((1 - Buffer.byteLength(purged) / Buffer.byteLength(original)) * 100)
 
-    console.log(`  ${cssHref.padEnd(28)} → /dist/${outName}  (${purgKb} kB, ${pct}% removed from ${origKb} kB)`)
+    // silent — summary table covers this
 
     manifest[cssHref] = `/dist/${outName}`
   }
 
   // Re-write manifest with CSS entries added
   fs.writeFileSync(path.join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2))
-  console.log('\n✓ CSS entries added to manifest\n')
+  // silent — summary table covers this
 }
 
 // ---------------------------------------------------------------------------
@@ -798,7 +851,8 @@ function minifyCss(css) {
   return css
     .replace(/\/\*[\s\S]*?\*\//g, '')   // strip comments
     .replace(/\s+/g, ' ')               // collapse whitespace
-    .replace(/\s*([{}:;,>~+])\s*/g, '$1') // remove spaces around punctuation
+    // Remove spaces around safe punctuation — NOT + or - (would break calc() expressions)
+    .replace(/\s*([{}:;,>~])\s*/g, '$1')
     .replace(/;}/g, '}')                // remove trailing semicolons
     .trim()
 }

package/src/agent/checklist.md

@@ -22,9 +22,29 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 - **Always restart the server and reload the browser after every file edit — before checking the result.** The dev server restarts on file changes but the browser tab stays stale. The required sequence is: `pulse_restart_server` → `navigate_page`. Never attempt to debug a visual problem without doing both steps first.
 
-### Components first
+### Components first — or creative override
 
 - **Before writing any HTML by hand, check `src/ui/index.js`.** There are 50+ components. Use `button`, `card`, `alert`, `input`, `spinner`, `badge`, `modal`, `nav`, `pagination`, `table`, etc. before writing equivalent HTML from scratch.
+- **Do not reinvent component patterns.** These patterns have dedicated components — never write custom HTML for them unless a creative override applies (see below):
+  - Hero sections → `hero({ title, subtitle, actions, image, ... })`
+  - Product/service cards → `card({ title, body, image, footer, ... })`
+  - Image + text two-column layouts → `media({ image, content, reverse })`
+  - Horizontal strips/banners → `banner({ content, variant })`
+  - Feature tiles → `feature({ icon, title, description })`
+  - Testimonials → `testimonial({ quote, name, role, src })`
+  - CTAs → `cta({ title, subtitle, actions })`
+  - Navigation → `nav({ logo, links, actions })`
+  - Footers → `footer({ logo, links, columns, legal, ... })`
+
+- **Creative override — raw HTML throughout is permitted** when the design intent genuinely calls for it: a highly custom visual identity, an asymmetric or typographically-driven layout, a brutalist/editorial/retro/neon/paper vibe where components would constrain the expression, or a layout that requires features a component simply doesn't support (e.g. full-viewport height, custom gradient glows, clamp-scaled display type). This is a deliberate design decision, not a shortcut. When taking this path:
+  - **Declare it in a comment at the top of the spec** so the reviewer recognises it: `// component-free — creative override: <reason>`. This is the signal the review tool reads.
+  - Functional atoms (`button`, `input`, `badge`, `modal`) should still come from components unless there is a specific design reason not to.
+  - `/pulse-ui.css` is always required — it provides the token system your custom CSS will use.
+  - The quality gate replaces the component checklist: **100/100/100/100 Lighthouse on both desktop and mobile is the pass bar.** A component-free page that passes every audit is correct. A component-heavy page that fails accessibility is not.
+
+- **When reviewing**: before flagging a class name like `.hero` as a violation, first ask whether the `hero()` component could actually reproduce the layout. If the answer is no, it is a creative override — check Lighthouse instead of refactoring. Do not flatten a good custom layout into a generic component just to clear a pattern-match.
+
+- **The review tool auto-detects creative override** from the spec comment. When detected, component pattern checks are shown as advisory (`⚡`) not as failures, and the Lighthouse gate is the stated pass bar.
 
 - **Never write App Store or Google Play download buttons by hand.** Always use `appBadge({ store: 'apple', href })` and `appBadge({ store: 'google', href })`. Raw `<a>` tags with badge images are incorrect — `appBadge` renders the correct accessible, styled badge for each store.
 
@@ -110,7 +130,7 @@ Before finishing any spec, verify every point below. Fix anything that fails.
   assert.equal(result.get('h1').text, mockProduct.name)
   assert.equal(result.attr('img', 'src'), mockProduct.image)
   ```
-  Supported selectors: `tag`, `.class`, `#id`, `[attr]`, `[attr="value"]`, and combinations (`button.primary[disabled]`).
+  Supported selectors: `tag`, `.class`, `#id`, `[attr]`, `[attr="value"]`, combinations (`button.primary[disabled]`), and **descendant combinators** (`result.count('.parent li')`, `result.find('tbody tr')`). Descendant selectors match the rightmost token within the ancestor context — they do not return 0 if the ancestor doesn't exist, they simply find no matching descendants.
 
 ### Markdown
 

package/src/agent/commands/verify.md

@@ -16,6 +16,8 @@ Use `pulse_validate` with the spec file content. If validation fails, report eve
 
 Use `pulse_fetch_page` to confirm the server is responding for the route. If it errors, use `pulse_restart_server` and retry once.
 
+**If `pulse_fetch_page` returns unexpected HTML (e.g. a different project's page title, a Next.js 404, or any non-Pulse response):** check the `X-Pulse` response header — Pulse servers always send this. If it is absent, the wrong server is running on that port. Stop and inform the user before continuing.
+
 ### 4. Screenshot
 
 Use `mcp__chrome-devtools__navigate_page` to load the page route, then `mcp__chrome-devtools__take_screenshot` to capture the result. Describe what you see — layout, content, any obvious rendering issues.
@@ -32,6 +34,8 @@ Run `mcp__chrome-devtools__lighthouse_audit` on the same route with `{ "strategy
 
 **Same pass bar: Accessibility, Best Practices, and SEO must all be 100.** Fix any failures and restart from step 2.
 
+**If you need to visually inspect the layout at a mobile viewport width** (e.g. to debug a wrapping or overflow issue), use `mcp__chrome-devtools__emulate` with `viewport: "390x844x2,mobile,touch"` — not `resize_page`. The `emulate` tool reliably sets the viewport; `resize_page` does not reliably trigger responsive layout changes. Reset afterward with `emulate` using the desktop viewport: `"1440x900x1"`.
+
 ### 7. Performance
 
 Navigate to the page route, then run `mcp__chrome-devtools__performance_start_trace` with `reload: true` and `autoStop: true`. Report LCP and CLS. Flag any LCP insight that suggests a fixable problem (render-blocking resources, large image load delay, etc.).

package/src/agent/guide-components.md

@@ -12,6 +12,62 @@ meta: { styles: ['/pulse-ui.css', '/app.css'] }
 
 Interactive components (carousel, tooltip) also need `/pulse-ui.js` in `meta.scripts`. Modal is handled natively by the Pulse runtime — no extra script needed.
 
+### Component root CSS classes
+
+Use these when writing tests (`.get('.ui-card')`) or custom CSS overrides. The root class is the one to target — not an invented name.
+
+| Component fn | Root CSS class | Notes |
+|---|---|---|
+| `nav` | `.ui-nav` | |
+| `hero` | `.ui-hero` | |
+| `button` | `.ui-btn` | |
+| `card` | `.ui-card` | |
+| `input` / `select` / `textarea` / `search` / `slider` | `.ui-field` | Wrapper div; inner input has `.ui-input` |
+| `modal` | `.ui-modal` | |
+| `alert` | `.ui-alert` | |
+| `badge` | `.ui-badge` | |
+| `stat` | `.ui-stat` | |
+| `avatar` | `.ui-avatar` | |
+| `empty` | `.ui-empty` | |
+| `table` | `.ui-table-wrap` | Inner `<table>` has `.ui-table` |
+| `spinner` | `.ui-spinner` | |
+| `section` | `.ui-section` | |
+| `container` | `.ui-container` | |
+| `grid` | `.ui-grid` | |
+| `stack` | `.ui-stack` | |
+| `cluster` | `.ui-cluster` | |
+| `feature` | `.ui-feature` | |
+| `testimonial` | `.ui-testimonial` | |
+| `pricing` | `.ui-pricing` | |
+| `accordion` | `.ui-accordion` | |
+| `cta` | `.ui-cta` | |
+| `footer` | `.ui-footer` | |
+| `phoneFrame` | `.ui-phone` | **Not** `.ui-phone-frame` |
+| `prose` | `.ui-prose` | |
+| `progress` | `.ui-progress` | |
+| `breadcrumbs` | `.ui-breadcrumbs` | |
+| `stepper` | `.ui-stepper` | |
+| `timeline` | `.ui-timeline` | |
+| `carousel` | `.ui-carousel` | |
+| `tooltip` | `.ui-tooltip` | |
+| `appBadge` | `.ui-app-badge` | |
+| `banner` | `.ui-banner` | |
+| `uiImage` | `.ui-image` | |
+| `gallery` | `.ui-gallery` | |
+| `photoCard` | `.ui-photo-card` | |
+| `marquee` | `.ui-marquee` | |
+| `decorate` | `.ui-decorate` | Inline SVG — parent needs `position: relative` |
+| `codeWindow` | `.ui-code-window` | |
+| `segmented` | `.ui-segmented` | |
+| `rating` | `.ui-rating` | |
+| `entryList` | `.ui-entry-list` | Editorial — tabular list with metadata |
+| `displayHeading` | `.ui-display-heading` | Editorial — large typographic heading |
+| `sectionLabel` | `.ui-section-label` | Editorial — eyebrow + h2 + rule |
+| `dropCap` | `.ui-drop-cap` | Editorial — first-letter treatment |
+| `colophon` | `.ui-colophon` | Editorial — minimal footer |
+
+
+
 ### Charts
 
 Server-rendered SVG charts — no JS, no dependencies. Drop into any card, section, or grid.
@@ -92,7 +148,7 @@ To add a missing icon: copy a Lucide path (MIT) into `src/ui/icons.js` using `s(
 
 | Component | Key props |
 |-----------|-----------|
-| `button` | `label`, `variant` (primary/secondary/ghost/danger), `size` (sm/md/lg), `href`, `type`, `disabled`, `fullWidth`, `icon`, `iconAfter`, `attrs` |
+| `button` | `label`, `variant` (primary/secondary/ghost/**ghost-light**/danger), `size` (sm/md/lg), `href`, `type`, `disabled`, `fullWidth`, `icon`, `iconAfter`, `attrs` — **use `ghost-light` when the button sits on a dark background** (hero, `section--dark`, navy wrapper); `ghost` uses `--ui-muted` text which fails contrast on dark backgrounds in light theme |
 | `input` | `name`, `label`, `type`, `placeholder`, `value`, `error`, `hint`, `required`, `disabled`, `attrs` |
 | `search` | `name`, `label`, `labelHidden`, `placeholder`, `value`, `event` (e.g. `'input:setSearch'`), `debounce` (ms, default 200), `clearEvent` (shown when value non-empty), `disabled`, `attrs` — search input with icon + clear button. **Use this instead of `input({ type: 'search' })`.** |
 | `select` | `name`, `label`, `options` (strings or `{value,label}`), `value`, `error`, `required`, `event` |
@@ -110,10 +166,10 @@ To add a missing icon: copy a Lucide path (MIT) into `src/ui/icons.js` using `s(
 
 | Component | Key props |
 |-----------|-----------|
-| `card` | `title`, `level` (1–6, default 3 — heading tag for title; visual style unchanged), `content` (HTML slot), `footer` (HTML slot), `flush` (full-bleed — removes body padding) |
+| `card` | `title`, `level` (1–6, default 3), `content` (HTML slot), `footer` (HTML slot), `flush` (full-bleed), `variant` (default/elevated/bordered/flat/glass/tinted) |
 | `alert` | `variant` (info/success/warning/error), `title`, `content` |
 | `badge` | `label`, `variant` (default/success/warning/error/info) |
-| `stat` | `label`, `value`, `change`, `trend` (up/down/neutral), `center` |
+| `stat` | `label`, `value`, `change`, `trend` (up/down/neutral), `size` (sm/md/lg — lg for hero KPIs), `center` |
 | `avatar` | `src`, `alt`, `size` (sm/md/lg/xl), `initials` |
 | `empty` | `title`, `description`, `action` ({label,href,variant}) |
 | `table` | `headers`, `rows` (2D array of HTML strings), `caption` |
@@ -122,6 +178,10 @@ To add a missing icon: copy a Lucide path (MIT) into `src/ui/icons.js` using `s(
 | `breadcrumbs` | `items` ([{label,href}] — last item has no href), `separator` |
 | `stepper` | `steps` (array of label strings), `current` (0-based) |
 | `uiImage` | `src`, `alt`, `caption`, `ratio`, `rounded`, `pill`, `width`, `height`, `maxWidth` |
+| `gallery` | `images` ([{src,alt,caption?,href?}]), `layout` (grid/strip/masonry), `cols` (1–4), `gap` (sm/md/lg), `rounded`, `ratio` — responsive image grid |
+| `photoCard` | `src`, `alt`, `caption`, `tilt` (CSS rotate degrees, e.g. 2 or -1.5), `rounded`, `ratio` — polaroid-style card with optional tilt |
+| `marquee` | `items` (array of HTML strings), `speed` (seconds, default 30), `gap`, `direction` (left/right), `pause` (hover pause), `fade` — CSS-only infinite scroll strip. Ideal for logos, trust badges |
+| `decorate` | `pattern` (dots/grid/lines/zigzag/cross), `color`, `opacity`, `size` — inline SVG overlay. Parent needs `position: relative` (add class `u-relative`) |
 | `pullquote` | `quote`, `cite`, `size` (md/lg) |
 | `timeline` | `direction` (vertical/horizontal), `items` ([{dot,dotColor,label,content}]) |
 | `timelineItem` | `content`, `label`, `dot`, `dotColor` (accent/success/warning/error/muted) |
@@ -142,26 +202,104 @@ To add a missing icon: copy a Lucide path (MIT) into `src/ui/icons.js` using `s(
 
 Use `prose()` for HTML from external sources (CMS, markdown). Use `heading()`/`list()` when writing content yourself.
 
+### Editorial components
+
+Editorial/typographic primitives for non-SaaS layouts: paperback books, vintage magazines, editorial sites, portfolio pages. These complement the landing-page-focused components (hero, feature, cta) when the design needs structure that's tabular, asymmetric, or typography-led.
+
+| Component | Key props | Use for |
+|-----------|-----------|---------|
+| `entryList` | `items` ([{meta, title, description}]), `metaLabel` (accessible name for meta column — e.g. "Year") | Backlists, release notes, changelogs, project archives, talk logs |
+| `displayHeading` | `text`, `level` (1–6), `maxWidth` (ch units, default 20), `balance` (true), `tracking` ('tight'\|'normal'\|'wide') | Hero titles, chapter openings, large typographic moments |
+| `sectionLabel` | `eyebrow`, `heading`, `level` (1–6, default 2), `rule` (true — show horizontal rule), `align` ('left'\|'center') | Section dividers, chapter labels, content blocks |
+| `dropCap` | `letter` (the drop cap letter or word), `content` (rest of paragraph), `lines` (height in lines, default 3) | First-paragraph treatment, editorial openings |
+| `colophon` | `content` (HTML slot), `align` ('center'\|'left') | Paperback-style footer — minimal, tight type, no columns |
+
+#### When to use editorial components
+
+Use these when the design direction is **editorial**, **retro**, **brutalist**, or **paper** vibe, or when the content structure is naturally tabular (list of books, releases, projects). They're shaped for asymmetry and typography-first layouts, not centred hero + three-column features.
+
+**Example: Book backlist**
+```js
+entryList({
+  metaLabel: 'Year',
+  items: [
+    { meta: '2023', title: 'The Argent Ghost', description: 'A tale of time-travel and lost identity.' },
+    { meta: '2021', title: 'Signal Drift',      description: 'First contact from a dead civilization.' },
+    { meta: '2019', title: 'Cold Equations',    description: 'Survival at the edge of known space.' },
+  ],
+})
+```
+
+**Example: Editorial hero**
+```js
+${displayHeading({ text: 'In Search of Lost Code', level: 1, tracking: 'tight' })}
+${dropCap({ letter: 'T', content: 'he first computers were humans, pencil-wielding calculators in windowless rooms, computing artillery trajectories by hand...' })}
+```
+
+**Example: Section divider**
+```js
+sectionLabel({ eyebrow: 'Chapter 3', heading: 'The Rise of Symbolic Logic', rule: true })
+```
+
+**Example: Minimal footer for an editorial page**
+```js
+colophon({
+  content: `<p>© 2025 Alden Press • Set in Lyon Text and Atlas Grotesk</p>
+  <p><a href="/about">About</a> • <a href="/contact">Contact</a></p>`,
+})
+```
+
+**Composition:** Editorial components work inside `section()` + `container()` like any other Pulse component. Use `prose()` for body text, `sectionLabel()` for section breaks, `entryList()` for tabular content, `displayHeading()` for large type moments, and `colophon()` instead of `footer()` for editorial pages.
+
+#### When components feel restrictive
+
+**Symptom:** You're fighting a component's wrapper styles (padding, max-width, centering) in your CSS overrides.
+
+**Solutions:**
+1. **Use the right component for your design.** If the page is editorial/typographic, use the editorial components (`displayHeading`, `sectionLabel`, `entryList`, `colophon`) instead of trying to force `hero()`, `feature()`, `cta()` into an editorial shape.
+2. **Write custom markup for structural differences.** Components provide sensible defaults for common patterns. When your design structure diverges significantly (asymmetric grid, full-bleed sections, custom positioning), write the HTML directly — that's permitted for layouts. Use components for the UI primitives (`button`, `card`, `input`, `badge`), but write the outer structure yourself.
+3. **Override with higher specificity.** Component wrappers use single class names (`.ui-hero`, `.ui-cta`). Override with a more specific selector in your `app.css`:
+   ```css
+   .my-editorial-hero .ui-hero-inner {
+     max-width: none;
+     padding: 0;
+   }
+   ```
+
+Components are opinionated by design — they enforce accessibility, consistency, and tested patterns. When the design requires breaking those patterns, prefer custom markup over fighting the component.
+
+#### Important: Vibes affect CSS tokens, not component HTML structure
+
+The `meta.vibe` setting (`warm`, `editorial`, `playful`, `minimal`, `bold`, `brutalist`, `retro`, `corporate`, `neon`, `paper`) applies CSS variable overrides via `data-vibe` on the `<body>` element. This changes **visual styling** — border radius, font size, letter-spacing, heading weight — but does **not** change the **HTML structure** of components.
+
+For example:
+- `hero()` with `vibe: 'editorial'` still renders eyebrow + title + subtitle + actions (SaaS structure)
+- The vibe adjusts the font sizes, tracking, and spacing, but the component HTML is unchanged
+
+**If you need different HTML structure for an editorial design** — e.g., a large display title + asymmetric layout + drop cap instead of eyebrow/subtitle/actions — use the editorial components (`displayHeading`, `dropCap`, `sectionLabel`) or write custom markup. Do not expect `hero()` to become structurally editorial when `vibe: 'editorial'` is set.
+
+This is by design: vibes are a paint job, not a structural transformation. Components stay predictable and testable. When the design structure itself differs from the SaaS patterns (centred hero, three-column features, pricing cards), reach for the editorial components or custom layout instead of trying to force `hero()` / `feature()` / `cta()` into shapes they weren't designed for.
+
 ### Landing page components
 
 | Component | Key props |
 |-----------|-----------|
 | `nav` | `logo` (HTML slot), `logoHref`, `links` ([{label,href}]), `action` (HTML slot), `sticky`, `background` (any CSS value — overrides default surface colour), `color` (foreground colour — set when custom background doesn't contrast with default muted text) |
-| `hero` | `eyebrow`, `title`, `subtitle`, `actions` (HTML slot), `image` (HTML slot — activates split layout), `imageAlign` (right/left), `align` (center/left), `size` (md/sm), `gradient` (true/false or preset: 'purple'\|'blue'\|'green'\|'rose'\|'orange'), `background` (any CSS value — solid colour or custom gradient, overrides gradient preset), `eyebrowColor` (overrides eyebrow text colour — always set when using a custom background to ensure WCAG contrast) |
+| `hero` | `eyebrow`, `title`, `subtitle`, `actions` (HTML slot), `image` (HTML slot — activates image layout), `imageAlign` (right/left), `align` (center/left), `size` (md/sm), `layout` (split/asymmetric/overlap — when image provided: 'split'=50/50, 'asymmetric'=60/40 text-heavy, 'overlap'=image fills section with text overlay), `gradient` (true/false or preset: 'purple'\|'blue'\|'green'\|'rose'\|'orange'), `background` (any CSS value), `eyebrowColor` |
 | `phoneFrame` | `content` (HTML slot — rendered inside the phone screen), `animate` (boolean, default `false` — enables a gentle 3-D tilt on hover). Pure CSS phone mockup with dynamic island, side buttons, home indicator. Use as the `image` slot in `hero()` for app landing pages. Add `animate: true` whenever the phone is a prominent hero element. |
-| `feature` | `icon` (HTML slot), `title`, `level` (1–6, default 3), `description`, `center` |
+| `feature` | `image` (HTML slot — rendered above icon), `icon` (HTML slot), `title`, `level` (1–6, default 3), `description` (or `body` as alias), `center` |
 | `testimonial` | `quote`, `name`, `role`, `src`, `rating` (1–5) |
 | `pricing` | `name`, `level` (1–6, default 3), `price`, `period`, `features` ([strings]), `action` (HTML slot), `highlighted` |
 | `accordion` | `items` ([{question,answer}]) — native `<details>`, no JS |
 | `appBadge` | `store` (apple/google), `href` — **always use this for App Store / Google Play download buttons. Never write a raw `<a>` with an SVG badge image.** Designed to sit in a `hero()` `actions` slot or anywhere a download CTA is needed. |
-| `cta` | `eyebrow`, `title`, `level` (1–6, default 2), `subtitle`, `actions` (HTML slot), `align` |
+| `cta` | `eyebrow`, `title`, `level` (1–6, default 2), `subtitle` (or `body` as alias), `actions` (HTML slot), `align` (center/left) |
 
 ### Layout components
 
 | Component | Key props |
 |-----------|-----------|
 | `container` | `content`, `size` (sm/md/lg/xl) |
-| `section` | `content`, `variant` (default/alt/dark), `padding` (sm/md/lg), `id`, `eyebrow`, `title`, `level` (1–6, default 2), `subtitle`, `align` |
+| `section` | `content`, `variant` (default/alt/dark/diagonal/paper/spotlight), `padding` (sm/md/lg), `id`, `eyebrow`, `title`, `level` (1–6, default 2), `subtitle`, `align` — `diagonal`: tapered bottom edge; `paper`: dot-grid texture; `spotlight`: radial gradient focus; **`dark`: in light theme renders navy `#1a1a2e` background (not light grey) with automatic light text and ghost-button overrides; customise via `--ui-dark-bg`/`--ui-dark-text`** |
 | `grid` | `content`, `cols` (1–4), `gap` (sm/md/lg) — responsive, collapses on mobile |
 | `stack` | `content`, `gap` (xs–xl), `align` — flex column |
 | `cluster` | `content`, `gap`, `justify`, `align` — flex row with wrap |
@@ -169,7 +307,7 @@ Use `prose()` for HTML from external sources (CMS, markdown). Use `heading()`/`l
 | `banner` | `content`, `variant` |
 | `media` | `image` (HTML slot), `content` (HTML slot), `reverse` — two-column image + text |
 | `codeWindow` | `content` (highlighted code HTML), `filename`, `lang` |
-| `footer` | `logo`, `logoHref`, `links`, `legal` |
+| `footer` | `logo`, `logoHref`, `links` (flat: `[{label,href}]`), `legal`, `background`, `color` — **Rich layout:** add `columns: [{title, links:[{label,href}]}]` to switch to multi-column mode; also accepts `subscribe` (HTML slot), `wordmark` (giant display text) |
 
 ### Modal / dialog