@invisibleloop/pulse 0.12.3 → 0.14.2

package/src/agent/guide-design-gallery.md

@@ -0,0 +1,288 @@
+# Pulse Design Gallery — Templates & Component Combinations
+
+A curated catalogue of ready-to-use design patterns. Each entry names the live template (or component combination), its distinguishing visual character, which vibe preset to set, which CSS theme to load, and the key components that make it work. Use this alongside `pulse://guide/design-references` — gallery = what it looks like + how to build it; design-references = aesthetic direction + creative strategy.
+
+---
+
+## Templates
+
+### Local Business Landing Page
+**Route:** `/templates/local-business`  
+**Vibe:** `warm`  **Theme:** `light`  **CSS:** `lumio.css`
+
+Warm cream background, hand-crafted feel. Photo-forward hero with a split layout (text left, dog/product image right). Earthy greens and amber for CTAs. Services grid of 6 cards with price footers. Two-column about section with credentials checklist. Three-column testimonials. Contact section with location/hours sidebar and inline booking form. Stat strip showing social proof numbers.
+
+**Key components:** `hero({ layout:'split' })`, `section`, `container`, `grid`, `card` (with `footer`), `stat`, `testimonial`, `cta`, `badge`
+
+**Distinguishing moves:**
+- Gradient hero `linear-gradient(135deg, #fdf6ee, #fdebd0)` with `color:#3d2b1e`
+- Nav with `background: rgba(255,250,245,0.92)` and matching text colour
+- Cards with price footer: `<div class="u-flex u-items-center u-justify-between"><span>From</span><strong>£35</strong></div>`
+- Credentials list: icon + span with `iconCheckCircle`
+- Booking form inlined inside a `card`
+
+**Best for:** Dog groomer, physio, florist, bakery, personal trainer, hair salon, local café, tradesperson
+
+---
+
+### Portfolio / Creative Agency
+**Route:** `/templates/portfolio`  
+**Vibe:** `minimal`  **Theme:** `dark`  **CSS:** *(none extra — dark theme built-in)*
+
+Dark, editorial, high-contrast. Works grid with cover images (fluid fill via `flush:true`), category badge overlays, and title links. Minimal nav without action button. About section in a narrow `sm` container for essay-like reading width. Simple plain contact form. Monochromatic palette with accent for hover states.
+
+**Key components:** `hero({ layout:'centered' })`, `section`, `container({ size:'sm' })`, `grid({ cols:3 })`, `card({ flush:true })`, `badge({ variant:'soft' })`
+
+**Distinguishing moves:**
+- `card({ flush:true })` + `<img>` at top of content, padded inner div below — creates image card without a native image slot
+- `aspect-ratio:3/2` on images for consistent crop
+- `container({ size:'sm' })` for about/contact text — keeps it from stretching wide
+- No eyebrows, no badge decorations in hero — just clean large type
+
+**Best for:** Designer, photographer, illustrator, studio, agency, architect, film-maker
+
+---
+
+### Event / Conference
+**Route:** `/templates/event`  
+**Vibe:** `bold`  **Theme:** `dark`  **CSS:** *(none extra — dark theme built-in)*
+
+Dark navy with violet/purple gradient CTAs. Centred hero with countdown-style stats strip. Sponsor logo marquee. Speaker portrait grid (4 columns, `flush:true` square images). Schedule as an accordion (3 day items, each with time/stage timetable). Venue section with two-column layout (map + details). Ticket pricing highlight.
+
+**Key components:** `hero`, `section`, `container`, `grid({ cols:4 })`, `card({ flush:true })`, `accordion`, `marquee`, `badge`, `stat`, `cta`
+
+**Distinguishing moves:**
+- Speaker cards: `aspect-ratio:1/1` square portrait images + name/role/quote below
+- Accordion items: `{ question: 'Day 1 — ...', answer: '<div>...timetable rows...</div>' }`
+- Marquee for sponsor logos: `marquee({ items: [...], gap:'xl', speed:'slow' })`
+- Stats strip: `section({ variant:'alt', padding:'sm' })` + `grid({ cols:4 })`
+
+**Best for:** Conference, hackathon, festival, product launch, awards ceremony, summit
+
+---
+
+### Editorial / Magazine
+**Route:** `/templates/editorial`  
+**Vibe:** `editorial`  **Theme:** `dark`  **CSS:** *(none extra — dark theme built-in)*
+
+Dark with serif headline typography. Featured article hero with byline, read-time badge, and category tag. Pullquote section with large italic text and cite attribution. Six-card article grid with `flush:true` cards (16:9 cover images, eyebrow category, deck text, author, date, read-time). Newsletter CTA in a `spotlight` section variant.
+
+**Key components:** `hero`, `section({ variant:'spotlight' })`, `pullquote`, `container`, `grid({ cols:3 })`, `card({ flush:true })`, `badge`, `cta`
+
+**Distinguishing moves:**
+- Article cards: `card({ flush:true })` + `<img style="aspect-ratio:16/9">` + padded inner div with category badge, title link, deck, byline row
+- `pullquote({ quote:'...', cite:'Name, Publication' })` — note `cite` not `author`
+- Featured hero uses `layout:'centered'` with small eyebrow badge and read-time
+- `section({ variant:'spotlight' })` for the newsletter signup gives a glowing background effect
+
+**Best for:** Online magazine, news publication, blog, newsletter landing page, media brand
+
+---
+
+### Mobile App Landing Page
+**Route:** `/templates/mobile-app`  
+**Vibe:** `bold` or `minimal`  **Theme:** `dark`  **CSS:** *(dark theme built-in)*
+
+Hero with phone-frame mockup, feature grid, pricing section, testimonials, and App Store badges. The centrepiece is a `phoneFrame` component wrapping a screenshot or animated mockup.
+
+**Key components:** `hero`, `phoneFrame`, `feature`, `pricing`, `testimonial`, `appBadge`, `cta`
+
+**Best for:** iOS/Android app, SaaS with mobile client, consumer product launch
+
+---
+
+### Blog Post
+**Route:** `/templates/blog-post`  
+**Vibe:** `editorial` or `minimal`  **Theme:** light or dark  **CSS:** `/pulse-ui.css`
+
+Long-form article layout with `prose` component for markdown rendering, breadcrumbs, reading time, featured image, and a related-posts footer.
+
+**Key components:** `prose`, `heading`, `breadcrumbs`, `badge`, `container({ size:'sm' })`
+
+**Best for:** Article, tutorial, case study, documentation page, essay
+
+---
+
+## Component Combinations by Use Case
+
+### Image Card (Card with Cover Photo)
+Card doesn't have a native image slot — use `flush:true` and put the image inside `content`:
+
+```js
+card({
+  flush:   true,
+  content: `
+    <img src="${url}" alt="${alt}" class="u-w-full" style="aspect-ratio:3/2;object-fit:cover;">
+    <div class="u-p-5">
+      <h3 class="u-font-semibold">${title}</h3>
+      <p class="u-text-sm u-text-muted">${body}</p>
+    </div>
+  `,
+})
+```
+
+### Article Card (16:9 image + category + byline)
+```js
+card({
+  flush:   true,
+  content: `
+    <img src="${img}" alt="${title}" class="u-w-full" style="aspect-ratio:16/9;object-fit:cover;">
+    <div class="u-p-5">
+      <div class="u-mb-2">${badge({ label: category, variant:'soft', size:'sm' })}</div>
+      <h3 class="u-font-semibold u-leading-snug">
+        <a href="${href}" class="u-text-inherit">${title}</a>
+      </h3>
+      <p class="u-text-sm u-text-muted u-mt-2">${deck}</p>
+      <div class="u-flex u-gap-3 u-mt-3">
+        <span class="u-text-xs u-text-muted">${author}</span>
+        <span class="u-text-xs u-text-muted">·</span>
+        <span class="u-text-xs u-text-muted">${date}</span>
+      </div>
+    </div>
+  `,
+})
+```
+
+### Credentials List (icon + text rows)
+```js
+const items = ['City & Guilds Level 3 qualified', 'Fear-free certified', 'Insured and first-aid trained']
+items.map(item => `
+  <div class="u-flex u-items-center u-gap-2">
+    ${iconCheckCircle({ size: 18 })}
+    <span>${item}</span>
+  </div>
+`).join('')
+```
+
+### Stat Strip
+```js
+section({
+  variant:  'alt',
+  padding:  'sm',
+  content:  container({ content: grid({
+    cols: 4,
+    gap:  'lg',
+    content: [
+      stat({ value: '2,400+', label: 'Happy customers' }),
+      stat({ value: '4.9',    label: 'Star rating'     }),
+      stat({ value: '6 years', label: 'In business'   }),
+      stat({ value: 'Same day', label: 'Bookings'     }),
+    ].join(''),
+  }) }),
+})
+```
+
+### Sponsor Marquee
+```js
+marquee({
+  items: ['Acme Corp', 'Globex', 'Initech', 'Umbrella', 'Hooli'].map(
+    name => `<span class="u-font-semibold u-text-lg u-opacity-60">${name}</span>`
+  ),
+  speed: 'slow',
+  gap:   'xl',
+})
+```
+
+### Section with Header (Eyebrow + Title + Subtitle)
+```js
+section({
+  id:       'services',
+  eyebrow:  'Our Services',
+  title:    'Everything You Need',
+  subtitle: 'A supporting line with a bit more detail.',
+  align:    'center',
+  content:  `...grid or cards...`,
+})
+```
+Note: when using the built-in `eyebrow`/`title`/`subtitle` on `section`, you don't need to put them inside the `content`. They are automatically rendered above `content` as a header block.
+
+### Two-Column Section (Text + Image)
+```js
+section({
+  id:      'about',
+  variant: 'alt',
+  content: container({ content: grid({
+    cols: 2,
+    gap:  'xl',
+    content: `
+      <div>
+        <img src="${img}" alt="..." class="u-w-full u-rounded-xl" style="object-fit:cover;height:360px;">
+      </div>
+      <div class="u-flex u-flex-col u-justify-center u-gap-5">
+        ${heading({ level: 2, text: 'About Us' })}
+        <p class="u-text-muted u-leading-relaxed">...</p>
+      </div>
+    `,
+  }) }),
+})
+```
+
+### Booking / Contact Form Inside a Card
+```js
+card({
+  title:   'Book an Appointment',
+  content: `
+    <p class="u-text-muted u-text-sm u-mb-4">Fill in the form and we'll confirm within a few hours.</p>
+    <form class="u-flex u-flex-col u-gap-3" data-action="submit">
+      <div class="u-flex u-flex-col u-gap-1">
+        <label class="u-text-sm u-font-medium" for="name">Your name</label>
+        <input id="name" name="name" type="text" class="u-input" required>
+      </div>
+      ${button({ label: 'Send Enquiry', type: 'submit', variant: 'primary', fullWidth: true })}
+    </form>
+  `,
+  padding: 'lg',
+})
+```
+
+---
+
+## Prop Names — Quick Reference (Critical)
+
+The most common mistakes when writing templates. These will silently produce empty output:
+
+| Component | ❌ Wrong prop | ✅ Correct prop |
+|---|---|---|
+| `section` | `children:` | `content:` |
+| `container` | `children:` | `content:` |
+| `grid` | `children:` | `content:` |
+| `card` | `body:` | `content:` |
+| `card` | `image:` *(unsupported)* | Put `<img>` inside `content:` |
+| `card` | `href:` *(unsupported)* | Wrap title in `<a>` inside `content:` |
+| `testimonial` | `author:` | `name:` |
+| `pullquote` | `author:` | `cite:` |
+| `accordion` items | `title:` | `question:` |
+| `accordion` items | `content:` | `answer:` |
+
+---
+
+## CSS Themes Available
+
+| File | Character | Pairs with vibe |
+|---|---|---|
+| *(none — dark default)* | Deep dark, cool greys, blue-ish surface | `minimal`, `bold`, `editorial` |
+| `/themes/lumio.css` | Warm cream whites, earthy mid-tones | `warm`, `paper` |
+| `/themes/neon.css` | Electric neon on very dark surface | `neon`, `brutalist` |
+| `/themes/retro.css` | Muted vintage pastels, aged look | `retro` |
+| `/themes/corporate.css` | Clean neutral greys, professional blue | `corporate` |
+
+Load via `meta.styles: ['/pulse-ui.css', '/themes/lumio.css']`.
+
+---
+
+## Vibes (data-vibe attribute)
+
+Set via `meta: { vibe: 'warm' }`. Controls radius, font weight, letter-spacing, and some colour nudges.
+
+| Vibe | Radius | Feel |
+|---|---|---|
+| `warm` | rounded | Approachable, organic, friendly |
+| `editorial` | square | Serious, print-like, editorial |
+| `minimal` | slight | Clean, airy, Swiss-influenced |
+| `bold` | medium | Confident, high-contrast |
+| `playful` | very rounded | Fun, colourful, consumer |
+| `brutalist` | none | Raw, stark, anti-design |
+| `retro` | pill/soft | Nostalgic, 70s–90s influenced |
+| `corporate` | small | Professional, trustworthy |
+| `neon` | medium | Electric, nightlife, gaming |
+| `paper` | slight | Textured, craft, tactile |

package/src/agent/guide-design-references.md

@@ -0,0 +1,172 @@
+# Pulse Design References — Aesthetic Vocabulary
+
+Use this guide to build **distinctive** pages rather than defaulting to the standard SaaS landing page. Match the user's product to a design direction, then apply the component combinations, vibe, and token hints below.
+
+When you choose a design direction, tell the user which one you're using and why. The whole point is conscious choice.
+
+---
+
+## Design Directions
+
+### 1. Clean SaaS / Productivity
+**Feels like:** Linear, Vercel, Notion, Raycast  
+**vibe:** `minimal` or `bold`  
+**Geometry:** tight radius (2–6px), mono grids, generous whitespace  
+**Typography:** geometric sans, tight tracking on headings, strong size contrast  
+**Palette pattern:** near-black bg + single accent (indigo / blue / violet)  
+**Signature moves:** bento grid, floating nav on scroll, stat bar, code window  
+**Components to lead with:** `hero(layout:'centered')`, `grid`, `stat`, `codeWindow`, `feature`
+
+---
+
+### 2. Warm Local Business
+**Feels like:** a bakery, dog groomer, physiotherapy clinic, florist  
+**vibe:** `warm`  
+**Geometry:** large radius (14–20px), soft card shadows, rounded buttons  
+**Typography:** humanist sans (inter, nunito), comfortable line-height  
+**Palette pattern:** earthy warm — terracotta / sage / cream / warm off-white  
+**Signature moves:** real photo hero, services grid with icons, "meet the team", hours + map, handwritten accent (SVG underline via decorate)  
+**Components to lead with:** `hero(layout:'split')`, `photoCard`, `gallery`, `section(variant:'alt')`, `footer` with address
+
+---
+
+### 3. Editorial / Publication
+**Feels like:** The Verge, Substack, MIT Technology Review, a literary magazine  
+**vibe:** `editorial`  
+**Geometry:** zero radius, column rules, tight grids  
+**Typography:** serif display (Georgia / Playfair Display), strong weight contrast, generous body leading  
+**Palette pattern:** black + white + single ink colour (brick red / forest green)  
+**Signature moves:** article grid with issue number, pullquote, prose with drop cap, author byline as hero subtitle  
+**Components to lead with:** `prose`, `pullquote`, `hero(size:'sm')`, `grid`, `section` with column text
+
+> **Font note:** `vibe: 'editorial'` sets `--ui-font-display` to Georgia — this applies to hero headings and display text. Body copy and nav stay sans-serif (by design). For the full editorial look with Playfair Display or a similar web serif, load the font via `meta.styles` and set `--font-display` in your theme CSS:
+> ```css
+> [data-theme="light"] { --font-display: 'Playfair Display', Georgia, serif; }
+> ```
+> Without a loaded web font, the fallback Georgia is still visibly different from sans on hero headings.
+
+---
+
+### 4. Bold Agency / Creative Studio
+**Feels like:** Awwwards winner, design agency, film production studio  
+**vibe:** `bold`  
+**Geometry:** medium radius (6–10px), oversized type, dramatic section transitions  
+**Typography:** heavy condensed sans (Black weight), massive heading, strong contrast  
+**Palette pattern:** black bg + vivid single colour (yellow / red / lime) for accents  
+**Signature moves:** work case-study grid, client logo marquee, big number stats, diagonal section, full-bleed hero  
+**Components to lead with:** `hero(layout:'poster')`, `marquee`, `gallery(layout:'masonry')`, `section(variant:'diagonal')`, `stat`
+
+---
+
+### 5. Playful / Consumer App
+**Feels like:** Duolingo, Headspace, Loom, Figma landing page, pop-art toy brand  
+**vibe:** `playful`  
+**Geometry:** very rounded (18–24px), friendly icons, colourful  
+**Typography:** rounded or friendly sans, loose spacing, emoji-friendly  
+**Palette pattern:** bright bg (coral / mint / lavender) + dark text  
+**Signature moves (use these, not 3-col feature grids):**
+- **Full-colour section blocks** — each section has its own bg colour (yellow stats strip, cyan testimonials, hot-pink CTA). Palette is structure, not accent.
+- **Oversized hero element** — the product's key visual (a game board, an illustration, an icon) fills most of the hero viewport. `phoneFrame` is one option, not the default.
+- **Marquee strip** — giant repeated glyphs, emoji, or product icons scrolling across the page between sections (`marquee` component)
+- **Tilted `photoCard`s** — testimonial or feature cards at ±2–4° with `photoCard` or CSS `transform: rotate()`
+- **Memphis-style geometric shapes** between sections — use `decorate(pattern:'circles')` or CSS background shapes
+- **Social proof as ticker** — a `marquee` of short quotes or star ratings, not a 3-col grid
+
+**Components to lead with:** `hero`, `appBadge`, `marquee`, `photoCard`, `section` with flat-colour backgrounds, `stat`  
+**What NOT to do:** 3-column `feature()` grids, centred hero + three columns, phone mockup when the product is a game/board/visual thing
+
+---
+
+### 6. Minimal Portfolio
+**Feels like:** a photographer, architect, developer personal site, typographer  
+**vibe:** `minimal`  
+**Geometry:** ultra-low radius (0–3px), strong whitespace, grid discipline  
+**Typography:** light weight body, all-caps labels, large work titles  
+**Palette pattern:** white or near-black + single neutral accent  
+**Signature moves:** work grid (no card chrome), simple text navigation, contact via plain `<a href="mailto:...">`, no footer clutter  
+**Components to lead with:** `gallery(layout:'grid')`, `grid`, `container(size:'sm')`, `heading`, minimal `footer`
+
+---
+
+### 7. Event / Conference
+**Feels like:** a festival poster, tech conference site, concert landing page  
+**vibe:** `bold` or `neon`  
+**Geometry:** strong, decisive — either rectangular or very rounded  
+**Typography:** poster-style headline, tight date/location details  
+**Palette pattern:** dark bg + 2 vivid accent colours; optional gradient hero  
+**Signature moves:** date + venue stat bar, speaker grid, schedule accordion, countdown timer (client-only JS), ticket CTA  
+**Components to lead with:** `hero` with gradient `background`, `stat`, `grid` for speakers, `accordion` for schedule, `cta` with bold button
+
+---
+
+### 8. Retro / Craft / Nostalgia
+**Feels like:** a craft brewery, vinyl record shop, heritage brand, farmers market  
+**vibe:** `retro`  
+**Geometry:** medium radius (8px), textured backgrounds, thick borders  
+**Typography:** slab serif (Rockwell / Courier), mixed cases, stamp-style labels  
+**Palette pattern:** amber / cream / dark brown / forest green  
+**Signature moves:** `decorate(pattern:'dots')` background, thick divider lines, badge-style eyebrows, stacked text hierarchy  
+**Components to lead with:** `hero(layout:'stacked')`, `section(variant:'alt')`, `decorate`, `badge`, `card`
+
+---
+
+### 9. Corporate / B2B / Enterprise
+**Feels like:** Salesforce, Workday, a consultancy, an insurance company  
+**vibe:** `corporate`  
+**Geometry:** conservative radius (4px), structured layout, safe  
+**Typography:** system-ui or clean sans, no display serif, professional  
+**Palette pattern:** navy / corporate blue + white + grey  
+**Signature moves:** trust logos, security/compliance badges, case study cards, feature table, partner logos  
+**Components to lead with:** `hero(layout:'centered')`, `grid`, `feature`, `stat`, `testimonial` with company name
+
+---
+
+### 10. Brutalist / Art / Counter-culture
+**Feels like:** a Berlin gallery, fashion brand, experimental portfolio, zine  
+**vibe:** `brutalist`  
+**Geometry:** zero radius everywhere, raw edges, intentional "broken" look  
+**Typography:** impact / black weight / giant, sometimes rotated via CSS transform  
+**Palette pattern:** black + white + ONE violent accent (red / lime / hot pink)  
+**Signature moves:** asymmetric grid, oversized section numbers, text-only nav, full bleed images bleeding into sections, no visual fluff  
+**Components to lead with:** raw `section`, `container`, `heading`, `gallery` (no rounded), `decorate(pattern:'noise')`
+
+---
+
+### 11. Dark Tech / Gaming / Crypto
+**Feels like:** a cyberpunk game, crypto protocol, AI startup, hardware brand  
+**vibe:** `neon`  
+**Geometry:** sharp (2–4px), glowing borders, glassmorphism  
+**Typography:** monospace or geometric sans, colour gradient on headings  
+**Palette pattern:** very dark bg (#0a0a0f) + neon accent (cyan / green / magenta)  
+**Signature moves:** blurred glow backgrounds, animated grid lines (CSS), terminal code window, token/protocol stats  
+**Components to lead with:** `hero` with gradient, `codeWindow`, `stat`, `section(variant:'spotlight')`, `grid`
+
+---
+
+### 12. Warm Editorial / Journal
+**Feels like:** a personal newsletter, book club, reading list, thoughtful blog  
+**vibe:** `paper`  
+**Geometry:** organic radius (10px), soft card shadows  
+**Typography:** serif body (Georgia), comfortable 1.8 line-height, warm type colour  
+**Palette pattern:** warm off-white bg + dark sepia text + muted link colour  
+**Signature moves:** `prose` + `pullquote`, author avatar + bio card, reading time badge, related articles footer  
+**Components to lead with:** `prose`, `pullquote`, `avatar`, `card`, `container(size:'sm')`
+
+---
+
+## How to use this guide
+
+1. **At intake** — when the user describes their product, map it to one of the directions above.
+2. **State the choice** — tell the user "I'm using the Warm Local Business direction — rounded cards, earthy palette, photo-forward hero."
+3. **Apply the vibe** — set `meta.vibe` to the recommended value.
+4. **Lead with the right components** — the "Components to lead with" list is ordered: use the first one for the hero, the rest for the body sections.
+5. **Match the palette pattern** — don't apply a corporate navy palette to a playful app. If the user gave you brand colours, note whether they are warm/cool/saturated before writing CSS.
+6. **Pick a template if one exists** — design direction + template = fastest correct result. See `pulse://guide/templates`.
+
+## Cross-cutting rules
+
+- Never default to centered hero + feature grid + pricing + FAQ without checking if a different layout suits the product better.
+- The `marquee` component is great for trust logos, client names, and tech stack badges — use it on agency/corporate/SaaS directions.
+- The `photoCard` and `gallery` components are underused — deploy them whenever the product has visual appeal (food, fitness, places, products).
+- `decorate` backgrounds (dots, grid, noise, lines) add texture without images — especially useful on retro, brutalist, and paper directions.
+- `section(variant:'diagonal')` → bold / agency; `section(variant:'paper')` → warm / retro; `section(variant:'spotlight')` → dark tech / neon.