@invisibleloop/pulse 0.14.1 → 0.15.0

package/examples/public/pulse-ui.js

@@ -0,0 +1,257 @@
+/**
+ * pulse-ui.js — Vanilla JS for interactive Pulse UI components
+ *
+ * Handles:
+ *   - Slider     (.ui-slider — live fill + value output)
+ *   - File Upload (.ui-upload — drag-and-drop, click-to-open)
+ *   - Modal      (data-modal-open, <dialog>, backdrop close)
+ *   - Nav        (.ui-nav — mobile burger menu)
+ *   - Carousel   (.ui-carousel — prev/next/dots)
+ *
+ * No dependencies. No build step required.
+ * CSP-safe: no inline handlers — all behaviour via event delegation.
+ * Include once per page: <script src="/pulse-ui.js"></script>
+ */
+
+// ─── Slider ──────────────────────────────────────────────────────────────────
+// Update --slider-fill on .ui-field wrapper + optional live value output.
+
+document.addEventListener('input', (e) => {
+  const el = e.target
+  if (!el.classList.contains('ui-slider')) return
+  const field = el.closest('.ui-field')
+  if (!field) return
+  const pct = ((el.value - el.min) / (el.max - el.min) * 100).toFixed(2) + '%'
+  field.style.setProperty('--slider-fill', pct)
+  const out = field.querySelector('.ui-slider-output')
+  if (out) out.textContent = el.value
+})
+
+// ─── File Upload ─────────────────────────────────────────────────────────────
+// Prevent browser navigating to dropped file anywhere on the page.
+// Handle drag visual feedback + file assignment on drop.
+// Handle click-to-open and keyboard activation.
+
+document.addEventListener('dragover', (e) => {
+  e.preventDefault()
+  if (!(e.target instanceof Element)) return
+  const zone = e.target.closest('.ui-upload:not(.ui-upload--disabled)')
+  if (zone) zone.classList.add('ui-upload--active')
+})
+
+document.addEventListener('dragleave', (e) => {
+  if (!(e.target instanceof Element)) return
+  const zone = e.target.closest('.ui-upload')
+  if (zone && !zone.contains(e.relatedTarget)) {
+    zone.classList.remove('ui-upload--active')
+  }
+})
+
+document.addEventListener('drop', (e) => {
+  e.preventDefault()
+  if (!(e.target instanceof Element)) return
+  const zone = e.target.closest('.ui-upload:not(.ui-upload--disabled)')
+  if (!zone) return
+  zone.classList.remove('ui-upload--active')
+  const input = zone.querySelector('.ui-upload-input')
+  if (!input || !e.dataTransfer.files.length) return
+  const dt = new DataTransfer()
+  Array.from(e.dataTransfer.files).forEach(f => dt.items.add(f))
+  input.files = dt.files
+  input.dispatchEvent(new Event('change', { bubbles: true }))
+})
+
+// File Upload: show selected filename in zone after file chosen
+document.addEventListener('change', (e) => {
+  const input = e.target
+  if (!input.classList.contains('ui-upload-input')) return
+  const zone = input.closest('.ui-upload')
+  if (!zone) return
+  const textEl = zone.querySelector('.ui-upload-text')
+  if (!textEl) return
+  if (input.files && input.files.length > 0) {
+    const names = Array.from(input.files).map(f => f.name).join(', ')
+    textEl.textContent = names
+    zone.classList.add('ui-upload--selected')
+  } else {
+    textEl.innerHTML = 'Drag &amp; drop or <span class="ui-upload-browse">browse</span>'
+    zone.classList.remove('ui-upload--selected')
+  }
+})
+
+// ─── Modal ──────────────────────────────────────────────────────────────────
+
+document.addEventListener('click', (e) => {
+  // File upload: click zone → open file picker
+  // Skip synthetic clicks emitted by input.click() itself to avoid loops
+  if (!e.target.classList.contains('ui-upload-input')) {
+    const zone = e.target.closest('.ui-upload')
+    if (zone) {
+      const input = zone.querySelector('.ui-upload-input')
+      if (input && !input.disabled) { input.click(); return }
+    }
+  }
+
+  // Dialog open: data-dialog-open="dialogId" (first-class) or data-modal-open="dialogId" (compat)
+  const trigger = e.target.closest('[data-dialog-open],[data-modal-open]')
+  if (trigger) {
+    const id     = trigger.dataset.dialogOpen ?? trigger.dataset.modalOpen
+    const dialog = document.getElementById(id)
+    if (dialog && typeof dialog.showModal === 'function') {
+      dialog.showModal()
+    }
+    return
+  }
+
+  // Dialog close: data-dialog-close (closes nearest ancestor <dialog>)
+  const closeTarget = e.target.closest('[data-dialog-close]')
+  if (closeTarget) {
+    const dialog = closeTarget.closest('dialog')
+    if (dialog) dialog.close()
+    return
+  }
+
+  // Backdrop close — click lands on <dialog> element itself
+  if (e.target.tagName === 'DIALOG') {
+    e.target.close()
+  }
+})
+
+// File upload: Enter / Space on focused zone → open picker
+document.addEventListener('keydown', (e) => {
+  if (e.key !== 'Enter' && e.key !== ' ') return
+  const zone = e.target.closest('.ui-upload')
+  if (!zone) return
+  const input = zone.querySelector('.ui-upload-input')
+  if (input && !input.disabled) { e.preventDefault(); input.click() }
+})
+
+// ─── Nav (mobile burger) ────────────────────────────────────────────────────
+
+function initNav(el) {
+  if (el.dataset.pulseNavInit) return
+  el.dataset.pulseNavInit = '1'
+
+  const burger = el.querySelector('.ui-nav-burger')
+  const mobile = el.querySelector('.ui-nav-mobile')
+
+  // Mobile burger
+  if (burger && mobile) {
+    const open   = () => { el.classList.add('ui-nav--open');    burger.setAttribute('aria-expanded', 'true') }
+    const close  = () => { el.classList.remove('ui-nav--open'); burger.setAttribute('aria-expanded', 'false') }
+    const toggle = () => el.classList.contains('ui-nav--open') ? close() : open()
+
+    burger.addEventListener('click', toggle)
+    document.addEventListener('keydown', (e) => { if (e.key === 'Escape') close() })
+    document.addEventListener('click',   (e) => { if (!el.contains(e.target)) close() })
+    mobile.querySelectorAll('.ui-nav-link').forEach(a => a.addEventListener('click', close))
+  }
+
+  // Mega nav dropdowns
+  el.querySelectorAll('.ui-nav-mega-wrap').forEach(wrap => {
+    const trigger = wrap.querySelector('.ui-nav-mega-trigger')
+    const panel   = wrap.querySelector('.ui-nav-mega-panel')
+    if (!trigger || !panel) return
+
+    const openMega  = () => { panel.hidden = false; wrap.classList.add('ui-nav-mega-wrap--open');    trigger.setAttribute('aria-expanded', 'true') }
+    const closeMega = () => { panel.hidden = true;  wrap.classList.remove('ui-nav-mega-wrap--open'); trigger.setAttribute('aria-expanded', 'false') }
+    const toggleMega = () => panel.hidden ? openMega() : closeMega()
+
+    trigger.addEventListener('click', (e) => { e.stopPropagation(); toggleMega() })
+    document.addEventListener('keydown', (e) => { if (e.key === 'Escape') closeMega() })
+    document.addEventListener('click',   (e) => { if (!wrap.contains(e.target)) closeMega() })
+    panel.querySelectorAll('.ui-nav-mega-item').forEach(a => a.addEventListener('click', closeMega))
+  })
+}
+
+function runNavs() { document.querySelectorAll('.ui-nav').forEach(initNav) }
+document.readyState === 'loading'
+  ? document.addEventListener('DOMContentLoaded', runNavs)
+  : runNavs()
+document.addEventListener('pulse:navigate', runNavs)
+
+// ─── Carousel ───────────────────────────────────────────────────────────────
+
+function initCarousel(el) {
+  if (el.dataset.pulseCarouselInit) return
+  el.dataset.pulseCarouselInit = '1'
+
+  const track  = el.querySelector('.ui-carousel-track')
+  const prev   = el.querySelector('.ui-carousel-prev')
+  const next   = el.querySelector('.ui-carousel-next')
+  const dots   = Array.from(el.querySelectorAll('.ui-carousel-dot'))
+  const slides = Array.from(el.querySelectorAll('.ui-carousel-slide'))
+
+  if (!track || slides.length === 0) return
+
+  let current = 0
+
+  const updateArrows = () => {
+    if (prev) prev.hidden = current === 0
+    if (next) next.hidden = current === slides.length - 1
+  }
+
+  const goTo = (i) => {
+    current = Math.max(0, Math.min(i, slides.length - 1))
+    track.scrollTo({ left: slides[current].offsetLeft, behavior: 'smooth' })
+    dots.forEach((d, j) => {
+      const active = j === current
+      d.classList.toggle('active', active)
+      d.setAttribute('aria-selected', String(active))
+      d.setAttribute('tabindex', active ? '0' : '-1')
+    })
+    updateArrows()
+  }
+
+  prev?.addEventListener('click', () => goTo(current - 1))
+  next?.addEventListener('click', () => goTo(current + 1))
+  dots.forEach((d, i) => d.addEventListener('click', () => goTo(i)))
+
+  // Keyboard navigation — roving tabindex for tablist
+  el.addEventListener('keydown', (e) => {
+    if (!e.target.classList.contains('ui-carousel-dot')) return
+    let next = null
+    if (e.key === 'ArrowLeft' || e.key === 'ArrowUp') {
+      e.preventDefault()
+      next = current > 0 ? current - 1 : slides.length - 1
+    } else if (e.key === 'ArrowRight' || e.key === 'ArrowDown') {
+      e.preventDefault()
+      next = current < slides.length - 1 ? current + 1 : 0
+    } else if (e.key === 'Home') {
+      e.preventDefault()
+      next = 0
+    } else if (e.key === 'End') {
+      e.preventDefault()
+      next = slides.length - 1
+    }
+    if (next !== null) {
+      goTo(next)
+      dots[next]?.focus()
+    }
+  })
+
+  // Sync dot state and arrows when user swipes / scrolls
+  track.addEventListener('scroll', () => {
+    const trackLeft = track.getBoundingClientRect().left
+    const idx = slides.findIndex((s) => Math.abs(s.getBoundingClientRect().left - trackLeft) < 10)
+    if (idx !== -1 && idx !== current) {
+      current = idx
+      dots.forEach((d, j) => {
+        const active = j === current
+        d.classList.toggle('active', active)
+        d.setAttribute('aria-selected', String(active))
+        d.setAttribute('tabindex', active ? '0' : '-1')
+      })
+      updateArrows()
+    }
+  }, { passive: true })
+}
+
+// Initialise all carousels on the page
+const run = () => document.querySelectorAll('.ui-carousel').forEach(initCarousel)
+document.readyState === 'loading'
+  ? document.addEventListener('DOMContentLoaded', run)
+  : run()
+
+// Re-initialise after Pulse client-side navigation swaps the DOM
+document.addEventListener('pulse:navigate', run)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.14.1
+0.15.0

package/public/pulse-ui.css

@@ -150,6 +150,20 @@ html, body {
   color:      var(--ui-text);
 }
 
+/* ghost-light — use on dark section backgrounds (e.g. navy hero, section--dark).
+   Renders with light/white text and a subtle light border so it remains legible
+   regardless of whether the surrounding theme is light or dark.               */
+.ui-btn--ghost-light {
+  background:   transparent;
+  color:        rgba(255, 255, 255, 0.9);
+  border:       1px solid rgba(255, 255, 255, 0.35);
+}
+.ui-btn--ghost-light:hover:not(.ui-btn--disabled):not([disabled]) {
+  background:   rgba(255, 255, 255, 0.1);
+  border-color: rgba(255, 255, 255, 0.65);
+  color:        #ffffff;
+}
+
 .ui-btn--danger {
   background: var(--ui-red-dim);
   color:      var(--ui-red);
@@ -682,6 +696,36 @@ html, body {
 .ui-section--alt   { background: var(--ui-surface,   var(--surface,   #111116)); }
 .ui-section--dark  { background: var(--ui-surface-2, var(--surface-2, #18181f)); }
 
+/* In light theme, --ui-surface-2 resolves to a light grey — not "dark".
+   Override so section--dark always renders a genuinely dark background that
+   contrasts with the page, regardless of the active theme.                  */
+[data-theme="light"] .ui-section--dark,
+.ui-theme-light .ui-section--dark {
+  background:  var(--ui-dark-bg,  #1a1a2e);
+  color:       var(--ui-dark-text, #e2e2ea);
+}
+/* Ensure text children inherit the light colour in the dark section */
+[data-theme="light"] .ui-section--dark .ui-section-title,
+[data-theme="light"] .ui-section--dark .ui-section-eyebrow,
+[data-theme="light"] .ui-section--dark .ui-section-subtitle,
+.ui-theme-light .ui-section--dark .ui-section-title,
+.ui-theme-light .ui-section--dark .ui-section-eyebrow,
+.ui-theme-light .ui-section--dark .ui-section-subtitle {
+  color: inherit;
+}
+/* Ghost button inside a dark section on a light-theme page */
+[data-theme="light"] .ui-section--dark .ui-btn--ghost,
+.ui-theme-light .ui-section--dark .ui-btn--ghost {
+  color:        var(--ui-dark-text, #e2e2ea);
+  border-color: rgba(226, 226, 234, 0.35);
+}
+[data-theme="light"] .ui-section--dark .ui-btn--ghost:hover:not(.ui-btn--disabled):not([disabled]),
+.ui-theme-light .ui-section--dark .ui-btn--ghost:hover:not(.ui-btn--disabled):not([disabled]) {
+  background:   rgba(226, 226, 234, 0.1);
+  border-color: rgba(226, 226, 234, 0.65);
+  color:        var(--ui-dark-text, #e2e2ea);
+}
+
 /* diagonal — tapered bottom edge; follow with a section that starts flush */
 .ui-section--diagonal {
   background: var(--ui-surface, var(--surface, #111116));

package/scripts/build.js

@@ -19,7 +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'
+import { c, header, table, ok, fail, info, warn, elapsed, icon } from '../src/cli/fmt.js'
 
 // ---------------------------------------------------------------------------
 // Server-only property stripping
@@ -380,6 +380,23 @@ const ROOT    = rootArg !== -1
 const OUT_DIR = path.join(ROOT, 'public', 'dist')
 const TMP_DIR = path.join(ROOT, '.pulse-build')
 
+// ---------------------------------------------------------------------------
+// Load pulse.config.js (optional)
+// ---------------------------------------------------------------------------
+
+let _projectConfig = {}
+const _configPath = path.join(ROOT, 'pulse.config.js')
+if (fs.existsSync(_configPath)) {
+  try { _projectConfig = (await import(_configPath)).default ?? {} } catch { /* ignore */ }
+}
+
+// css.safelist — array of class name strings or RegExp patterns to always keep
+// even if the purger would otherwise remove them.
+// Example in pulse.config.js:
+//   export default { css: { safelist: ['my-class', /^js-/] } }
+const CSS_SAFELIST = (_projectConfig.css?.safelist ?? [])
+  .map(entry => typeof entry === 'string' ? entry : entry)
+
 // ---------------------------------------------------------------------------
 // Discover pages
 // ---------------------------------------------------------------------------
@@ -516,7 +533,7 @@ fs.rmSync(TMP_DIR, { recursive: true })
 // CSS Purge — strip unused styles, write content-hashed CSS bundles
 // ---------------------------------------------------------------------------
 
-await purgeCssStep(pages, manifest, ROOT, OUT_DIR)
+const cssPurgeStats = await purgeCssStep(pages, manifest, ROOT, OUT_DIR)
 
 // ---------------------------------------------------------------------------
 // JS static assets — minify + hash any .js files directly in public/
@@ -556,13 +573,17 @@ await jsAssetsStep(ROOT, OUT_DIR, manifest)
         c.dim(bundle.replace('/dist/', '')),
         `${sizeKb} kB`,
         c.dim('js'),
+        '',
       ])
     } else if (ext === '.css') {
+      const pct = cssPurgeStats?.[src]
+      const pctLabel = pct != null ? c.dim(`−${pct}%`) : ''
       rows.push([
         c.dim(src),
         c.dim(bundle.replace('/dist/', '')),
         `${sizeKb} kB`,
         c.dim('css'),
+        pctLabel,
       ])
     }
   }
@@ -577,9 +598,9 @@ await jsAssetsStep(ROOT, OUT_DIR, manifest)
   })
 
   console.log('\n' + table(
-    ['Route / Asset', 'Bundle', 'Size', 'Type'],
+    ['Route / Asset', 'Bundle', 'Size', 'Type', 'Purged'],
     rows,
-    { align: ['left', 'left', 'right', 'left'] }
+    { align: ['left', 'left', 'right', 'left', 'right'] }
   ))
 
   const totalMs = Date.now() - BUILD_START
@@ -599,9 +620,28 @@ async function jsAssetsStep(root, outDir, manifest) {
 
   console.log(info('Hashing static JS assets…'))
 
+  // Collect fetch/XHR origins used in static JS for CSP connect-src checking
+  const cspConnectSrc = new Set([
+    ...(_projectConfig.csp?.['connect-src'] ?? []),
+    'self',
+  ])
+
   for (const file of jsFiles) {
     const srcPath = path.join(publicDir, file)
     const source  = fs.readFileSync(srcPath, 'utf8')
+
+    // Warn if the file contains fetch/XMLHttpRequest calls to origins not in
+    // the project's CSP connect-src — these will silently fail in production.
+    const fetchUrls = [...source.matchAll(/fetch\s*\(\s*['"`](https?:\/\/[^'"`]+)['"`]/g)].map(m => m[1])
+    for (const url of fetchUrls) {
+      try {
+        const origin = new URL(url).origin
+        if (!cspConnectSrc.has(origin) && !cspConnectSrc.has('*')) {
+          console.log(warn(`${file}: fetch to ${origin} may be blocked — add to csp.connect-src in pulse.config.js`))
+        }
+      } catch { /* ignore malformed URLs */ }
+    }
+
     const { code } = await esbuild.transform(source, { minify: true, target: 'es2018' })
     const hash    = createHash('sha256').update(code).digest('hex').slice(0, 8)
     const name    = path.basename(file, '.js')
@@ -610,8 +650,6 @@ async function jsAssetsStep(root, outDir, manifest) {
     fs.writeFileSync(path.join(outDir, outName), code)
     manifest[`/${file}`] = `/dist/${outName}`
 
-    const origKb = (Buffer.byteLength(source) / 1024).toFixed(1)
-    const minKb  = (Buffer.byteLength(code)   / 1024).toFixed(1)
     // silent — summary table covers this
   }
 
@@ -629,6 +667,7 @@ async function purgeCssStep(pages, manifest, root, outDir) {
   const htmlContents = []
   const jsContents   = []
   const cssFiles     = new Set()
+  const cssStats     = {}
 
   for (const { filePath } of pages) {
     try {
@@ -667,6 +706,16 @@ async function purgeCssStep(pages, manifest, root, outDir) {
     }
   }
 
+  // Scan public/*.js static assets — these often contain classList.toggle() or
+  // classList.add() calls that reference CSS classes not present in any page spec,
+  // which would otherwise be incorrectly purged from the built CSS.
+  const publicDir = path.join(root, 'public')
+  if (fs.existsSync(publicDir)) {
+    for (const f of fs.readdirSync(publicDir).filter(f => f.endsWith('.js'))) {
+      try { jsContents.push(fs.readFileSync(path.join(publicDir, f), 'utf8')) } catch {}
+    }
+  }
+
   // Scan pulse UI package source — class names generated by UI components
   // (breadcrumbs, avatar, container, etc.) only appear in the package source,
   // not in the project's own pages, so they'd otherwise be purged.
@@ -687,10 +736,10 @@ async function purgeCssStep(pages, manifest, root, outDir) {
 
   if (cssFiles.size === 0) {
     console.log(info('No CSS files referenced — skipping.'))
-    return
+    return cssStats
   }
 
-  const usedClasses = extractUsedClasses(htmlContents, jsContents)
+  const usedClasses = extractUsedClasses(htmlContents, jsContents, CSS_SAFELIST)
 
   for (const cssHref of cssFiles) {
     // CSS path is relative to public/ (e.g. '/pulse-ui.css' → public/pulse-ui.css)
@@ -698,6 +747,21 @@ async function purgeCssStep(pages, manifest, root, outDir) {
     if (!fs.existsSync(cssPath)) continue
 
     const original = fs.readFileSync(cssPath, 'utf8')
+
+    // Warn about classes defined in this CSS file that weren't found in any
+    // scanned source — these will be purged and may indicate a missing scan source
+    // (e.g. a JS file that toggles classes via classList but wasn't picked up).
+    // Only warn for project-owned CSS files (not pulse-ui.css framework styles).
+    if (!cssHref.includes('pulse-ui')) {
+      const definedClasses = [...original.matchAll(/\.([a-zA-Z][a-zA-Z0-9_-]*)\s*[{,:\[]/g)]
+        .map(m => m[1])
+        .filter((cls, i, arr) => arr.indexOf(cls) === i) // dedupe
+      const purgedClasses = definedClasses.filter(cls => !usedClasses.has(cls))
+      if (purgedClasses.length > 0) {
+        console.log(warn(`${cssHref}: ${purgedClasses.length} class${purgedClasses.length === 1 ? '' : 'es'} purged (not found in any scanned source): ${purgedClasses.slice(0, 5).map(c => `.${c}`).join(', ')}${purgedClasses.length > 5 ? ` … +${purgedClasses.length - 5} more` : ''}`))
+      }
+    }
+
     const purged   = minifyCss(purgeCss(original, usedClasses))
 
     const hash    = createHash('sha256').update(purged).digest('hex').slice(0, 8)
@@ -707,25 +771,24 @@ async function purgeCssStep(pages, manifest, root, outDir) {
 
     fs.writeFileSync(outPath, purged)
 
-    const origKb  = (Buffer.byteLength(original) / 1024).toFixed(1)
-    const purgKb  = (Buffer.byteLength(purged)   / 1024).toFixed(1)
-    const pct     = Math.round((1 - Buffer.byteLength(purged) / Buffer.byteLength(original)) * 100)
-
-    // silent — summary table covers this
+    const origBytes = Buffer.byteLength(original)
+    const purgBytes = Buffer.byteLength(purged)
+    const pct       = Math.round((1 - purgBytes / origBytes) * 100)
+    cssStats[cssHref] = pct
 
     manifest[cssHref] = `/dist/${outName}`
   }
 
   // Re-write manifest with CSS entries added
   fs.writeFileSync(path.join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2))
-  // silent — summary table covers this
+  return cssStats
 }
 
 // ---------------------------------------------------------------------------
 // CSS class extractor
 // ---------------------------------------------------------------------------
 
-function extractUsedClasses(htmlContents, jsContents) {
+function extractUsedClasses(htmlContents, jsContents, safelist = []) {
   const used = new Set()
 
   // Extract from class="..." in both rendered HTML and JS template literals
@@ -751,6 +814,21 @@ function extractUsedClasses(htmlContents, jsContents) {
     }
   }
 
+  // Apply safelist from pulse.config.js — css.safelist accepts strings or RegExp.
+  // String entries are added directly; RegExp entries are matched against all
+  // class names defined in the CSS (resolved later in purgeCss via selectorUsed
+  // because we don't have the CSS text here). To handle RegExp, we mark them as
+  // a sentinel that selectorUsed checks separately.
+  for (const entry of safelist) {
+    if (typeof entry === 'string') {
+      used.add(entry)
+    }
+    // RegExp entries are stored on the Set as a symbol property for selectorUsed to check
+  }
+  if (safelist.some(e => e instanceof RegExp)) {
+    used._safelistPatterns = safelist.filter(e => e instanceof RegExp)
+  }
+
   return used
 }
 
@@ -820,7 +898,17 @@ function parseCssBlocks(css) {
 
 /**
  * Return true if any selector in the rule should be kept.
- * Keeps: element selectors, *, :root, and any rule where a used class appears.
+ *
+ * Matching strategy: check the *rightmost* class token in the selector (the
+ * subject of the rule). A rule like `.parent .child` should survive only when
+ * `.child` is used — keeping it whenever `.parent` is used would retain dead
+ * rules whose actual target class was never referenced.
+ *
+ * Pseudo-classes/elements and attribute selectors are stripped before checking
+ * so `.btn:hover` is treated as `.btn`, `.btn--active::before` as `.btn--active`.
+ *
+ * Element-only selectors (`a`, `*`, `:root`) and rules that contain no class
+ * tokens at all are always kept.
  */
 function selectorUsed(selector, usedClasses) {
   const selectors = selector.split(',').map(s => s.trim())
@@ -832,12 +920,21 @@ function selectorUsed(selector, usedClasses) {
       .replace(/\[[^\]]*\]/g, '')
       .trim()
 
-    // Keep element selectors, *, :root — no class tokens
+    // Keep element-only selectors — no class tokens present
     if (!base.includes('.')) return true
 
-    // Keep if any class in the selector is in the used set
-    const classes = [...sel.matchAll(/\.([a-zA-Z][a-zA-Z0-9_-]*)/g)].map(m => m[1])
-    if (classes.some(cls => usedClasses.has(cls))) return true
+    // Extract all class tokens and check the rightmost one (the rule subject).
+    // Using the rightmost class correctly handles descendant selectors:
+    //   .nav .link  → subject is .link
+    //   .btn--active → subject is .btn--active
+    const classes = [...base.matchAll(/\.([a-zA-Z][a-zA-Z0-9_-]*)/g)].map(m => m[1])
+    if (classes.length === 0) return true
+    const subject = classes[classes.length - 1]
+    if (usedClasses.has(subject)) return true
+
+    // Check RegExp safelist patterns if any were provided
+    const patterns = usedClasses._safelistPatterns
+    if (patterns && patterns.some(re => re.test(subject))) return true
   }
 
   return false
@@ -868,9 +965,18 @@ function purgeCss(cssText, usedClasses) {
       const p = block.prelude.toLowerCase()
       if (/^@(?:keyframes|font-face|charset)/.test(p)) {
         kept.push(block.raw)
-      } else if (/^@(?:media|supports|layer)/.test(p)) {
+      } else if (/^@(?:media|supports)/.test(p)) {
         const innerPurged = purgeCss(block.inner, usedClasses)
         if (innerPurged.trim()) kept.push(`${block.prelude} {\n${innerPurged}\n}`)
+      } else if (/^@layer/.test(p)) {
+        // Always preserve empty @layer declarations — they establish cascade order
+        // and removing them silently changes specificity even when no rules remain.
+        const innerPurged = purgeCss(block.inner, usedClasses)
+        if (innerPurged.trim()) {
+          kept.push(`${block.prelude} {\n${innerPurged}\n}`)
+        } else {
+          kept.push(`${block.prelude} {}`)
+        }
       } else {
         kept.push(block.raw) // unknown at-blocks — keep to be safe
       }

package/src/agent/checklist.md

@@ -36,13 +36,15 @@ Before finishing any spec, verify every point below. Fix anything that fails.
   - 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. This is a deliberate design decision, not a shortcut. When taking this path:
-  - State it explicitly in the build brief: *"Building component-free — raw HTML throughout for creative control."*
+- **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 a spec built under creative override, do not flag raw section HTML as a violation — check the Lighthouse results instead.
+- **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.
 

package/src/agent/guide-components.md

@@ -148,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` |
@@ -299,7 +299,7 @@ This is by design: vibes are a paint job, not a structural transformation. Compo
 | Component | Key props |
 |-----------|-----------|
 | `container` | `content`, `size` (sm/md/lg/xl) |
-| `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 |
+| `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 |