@invisibleloop/pulse 0.12.3 → 0.14.2

package/src/mcp/validate-worker.js

@@ -18,7 +18,23 @@ let mod
 try {
   mod = await import(tmpFile)
 } catch (err) {
-  process.stdout.write(`Invalid: could not parse — ${err.message}`)
+  // Give a targeted message for common import-resolution failures
+  const msg = err.message || ''
+  if (msg.includes('Cannot find package') || msg.includes('Cannot find module') || msg.includes('ERR_MODULE_NOT_FOUND')) {
+    const bare = msg.match(/Cannot find (?:package|module) '([^']+)'/)?.[1]
+    if (bare && !bare.startsWith('.') && !bare.startsWith('/') && !bare.startsWith('@invisibleloop/pulse')) {
+      process.stdout.write(
+        `Invalid: spec has an unresolvable import — \`${bare}\` is not a valid module specifier.\n` +
+        `  • Use relative paths for project-local files: \`'../components/nav.js'\`\n` +
+        `  • Use \`'@invisibleloop/pulse/ui'\` for Pulse components\n` +
+        `  • Bare paths like \`'src/...' \` or \`'components/...'\` are not valid — they are not packages`
+      )
+    } else {
+      process.stdout.write(`Invalid: could not import spec — ${msg.split('\n')[0]}`)
+    }
+  } else {
+    process.stdout.write(`Invalid: could not parse — ${err.message}`)
+  }
   process.exit(0)
 }
 
@@ -71,6 +87,18 @@ try {
     warnings.push(`Heading order: page starts with h${levels[0]}, expected h1`)
   }
 
+  // Duplicate h2s inside a single section — inner item headings should be h3
+  // A section with an h2 title and child items that also use h2 creates a flat
+  // outline that is semantically incorrect. Flag when a <section> contains 2+ h2s.
+  const sectionBlocks = [...html.matchAll(/<section[\s>][^]*?<\/section>/gi)]
+  for (const [sectionHtml] of sectionBlocks) {
+    const h2s = [...sectionHtml.matchAll(/<h2[\s>]/gi)]
+    if (h2s.length > 1) {
+      warnings.push(`Multiple h2 headings inside a single <section> — the first h2 should be the section title; inner item headings should use h3 (or deeper). A flat outline of h2s makes navigation harder for screen reader users.`)
+      break // one warning is enough
+    }
+  }
+
   // Missing main landmark
   if (!/id=["']main-content["']/.test(html)) {
     warnings.push('Missing <main id="main-content"> — required for accessibility and Lighthouse landmark audit')
@@ -98,7 +126,7 @@ try {
   }
 
   // Unknown u-* utility classes — catch invented classes that have no CSS definition
-  const KNOWN_UTILS = new Set(['u-absolute','u-bg-accent','u-bg-surface','u-bg-surface2','u-block','u-border','u-border-b','u-border-t','u-flex','u-flex-1','u-flex-col','u-flex-wrap','u-font-bold','u-font-medium','u-font-normal','u-font-semibold','u-gap-1','u-gap-2','u-gap-3','u-gap-4','u-gap-5','u-gap-6','u-gap-8','u-hidden','u-inline','u-inline-block','u-items-center','u-items-end','u-items-start','u-items-stretch','u-justify-between','u-justify-center','u-justify-end','u-justify-start','u-leading-loose','u-leading-normal','u-leading-relaxed','u-leading-snug','u-leading-tight','u-max-w-lg','u-max-w-md','u-max-w-prose','u-max-w-sm','u-max-w-xl','u-max-w-xs','u-mb-0','u-mb-1','u-mb-10','u-mb-12','u-mb-16','u-mb-2','u-mb-3','u-mb-4','u-mb-5','u-mb-6','u-mb-8','u-ml-auto','u-mr-auto','u-mt-0','u-mt-1','u-mt-10','u-mt-12','u-mt-16','u-mt-2','u-mt-3','u-mt-4','u-mt-5','u-mt-6','u-mt-8','u-mx-auto','u-opacity-50','u-opacity-75','u-overflow-auto','u-overflow-hidden','u-p-0','u-p-1','u-p-2','u-p-3','u-p-4','u-p-5','u-p-6','u-p-8','u-px-0','u-px-2','u-px-3','u-px-4','u-px-5','u-px-6','u-px-8','u-py-0','u-py-2','u-py-3','u-py-4','u-py-5','u-py-6','u-py-8','u-relative','u-rounded','u-rounded-full','u-rounded-lg','u-rounded-md','u-rounded-xl','u-shrink-0','u-text-2xl','u-text-3xl','u-text-4xl','u-text-accent','u-text-balance','u-text-base','u-text-blue','u-text-center','u-text-default','u-text-green','u-text-left','u-text-lg','u-text-muted','u-text-red','u-text-right','u-text-sm','u-text-xl','u-text-xs','u-text-yellow','u-w-auto','u-w-full'])
+  const KNOWN_UTILS = new Set(['u-absolute','u-bg-accent','u-bg-surface','u-bg-surface2','u-block','u-border','u-border-b','u-border-t','u-flex','u-flex-1','u-flex-col','u-flex-wrap','u-font-bold','u-font-medium','u-font-normal','u-font-semibold','u-gap-1','u-gap-2','u-gap-3','u-gap-4','u-gap-5','u-gap-6','u-gap-8','u-hidden','u-inline','u-inline-block','u-items-center','u-items-end','u-items-start','u-items-stretch','u-justify-between','u-justify-center','u-justify-end','u-justify-start','u-leading-loose','u-leading-normal','u-leading-relaxed','u-leading-snug','u-leading-tight','u-max-w-lg','u-max-w-md','u-max-w-prose','u-max-w-sm','u-max-w-xl','u-max-w-xs','u-mb-0','u-mb-1','u-mb-10','u-mb-12','u-mb-16','u-mb-2','u-mb-3','u-mb-4','u-mb-5','u-mb-6','u-mb-8','u-ml-auto','u-mr-auto','u-mt-0','u-mt-1','u-mt-10','u-mt-12','u-mt-16','u-mt-2','u-mt-3','u-mt-4','u-mt-5','u-mt-6','u-mt-8','u-mx-auto','u-opacity-50','u-opacity-75','u-overflow-auto','u-overflow-hidden','u-p-0','u-p-1','u-p-2','u-p-3','u-p-4','u-p-5','u-p-6','u-p-8','u-px-0','u-px-2','u-px-3','u-px-4','u-px-5','u-px-6','u-px-8','u-py-0','u-py-2','u-py-3','u-py-4','u-py-5','u-py-6','u-py-8','u-relative','u-rounded','u-rounded-full','u-rounded-lg','u-rounded-md','u-rounded-xl','u-shrink-0','u-tabular-nums','u-text-2xl','u-text-3xl','u-text-4xl','u-text-accent','u-text-balance','u-text-base','u-text-blue','u-text-center','u-text-default','u-text-green','u-text-left','u-text-lg','u-text-muted','u-text-red','u-text-right','u-text-sm','u-text-xl','u-text-xs','u-text-yellow','u-w-auto','u-w-full'])
   const usedUtils = new Set([...html.matchAll(/\bu-([\w-]+)/g)].map(m => 'u-' + m[1]))
   const unknownUtils = [...usedUtils].filter(c => !KNOWN_UTILS.has(c))
   if (unknownUtils.length) {
@@ -110,9 +138,25 @@ try {
     warnings.push('input[type="file"] detected — use the fileUpload() component instead. It provides the drag-and-drop zone, correct styling, and pulse-ui.js integration. import { fileUpload } from \'@invisibleloop/pulse/ui\'')
   }
 
-  // Unescaped apostrophes in attribute values
-  if (/=\s*'[^']*'[^']*'/.test(html)) {
-    warnings.push('Possible unescaped apostrophe in an HTML attribute — use &apos; or &#39; or switch to double quotes')
+  // Unescaped apostrophes — only flag inside attribute values (attr='it's wrong'),
+  // not in text content (it's fine in body text). Match: attr='...apostrophe...'
+  // Pattern: an attribute assignment with single-quote delimiter containing a second single quote
+  if (/\s[\w-]+=\s*'[^'<>]*'[^']*'/.test(html)) {
+    warnings.push('Possible unescaped apostrophe in an HTML attribute value — use &apos; or &#39; or switch to double-quoted attributes')
+  }
+
+  // Inline <style> blocks in view — blocked by Pulse CSP nonce policy
+  if (/<style[\s>]/i.test(html)) {
+    warnings.push('Inline <style> block detected in view — Pulse\'s CSP (style-src with nonces) will silently block these styles at runtime. Move styles to public/app.css instead.')
+  }
+
+  // Hardcoded hex colours in view HTML — must use var(--ui-*) tokens instead.
+  // Matches: style="...color:#hex..." or style="...background:#hex..."
+  // Allows: href="#section-id" (anchor links are not colours)
+  const hexInStyle = [...html.matchAll(/style="[^"]*#[0-9a-fA-F]{3,6}[^"]*"/g)]
+  if (hexInStyle.length) {
+    const samples = [...new Set(hexInStyle.flatMap(m => [...m[0].matchAll(/#[0-9a-fA-F]{3,6}/g)].map(h => h[0])))].slice(0, 3)
+    warnings.push(`Hardcoded hex colour${samples.length > 1 ? 's' : ''} in view HTML (${samples.join(', ')}) — use var(--ui-*) CSS tokens instead. Move the hex value to public/theme.css as a named token, then reference it via var() in public/app.css or as a CSS class on the element.`)
   }
 } catch { /* view may depend on server data — skip HTML checks */ }
 

package/src/runtime/ssr.js

@@ -314,7 +314,10 @@ export function wrapDocument({ content, spec = {}, serverState = {}, storeState
   const meta  = spec.meta  || {}
   const title = meta.title || 'Pulse'
 
-  const bodyAttr = meta.theme ? ` data-theme="${esc(meta.theme)}"` : ''
+  const bodyAttr = [
+    meta.theme ? `data-theme="${esc(meta.theme)}"` : '',
+    meta.vibe  ? `data-vibe="${esc(meta.vibe)}"` : '',
+  ].filter(Boolean).map(a => ` ${a}`).join('')
 
   const metaTags = [
     meta.description ? `<meta name="description" content="${esc(meta.description)}">` : '',

package/src/server/index.js

@@ -39,6 +39,7 @@ const SECURITY_HEADERS = {
   'Permissions-Policy':           'camera=(), microphone=(), geolocation=()',
   'Cross-Origin-Opener-Policy':   'same-origin',
   'Cross-Origin-Resource-Policy': 'same-origin',
+  'X-Pulse':                      version,
 }
 
 /**
@@ -498,7 +499,9 @@ export async function createServer(entries, options = {}) {
     healthCheck    = '/healthz',    // path for health check endpoint, or false to disable
     csp            = {},            // extra CSP sources: { 'style-src': ['https://fonts.googleapis.com'] }
     onError        = (err, req, res) => defaultErrorHandler(err, req, res, dev),
-    onRequest
+    onRequest,
+    agentMode      = false,        // show agent-active indicator in banner
+    quiet          = false,        // suppress request logging
   } = options
 
   // Resolve URL entries → spec objects, auto-setting hydrate where needed
@@ -552,6 +555,15 @@ export async function createServer(entries, options = {}) {
   let router = buildRouter(specs)
 
   const server = http.createServer(async (req, res) => {
+    const reqStart = Date.now()
+    res.on('finish', () => {
+      if (!quiet) {
+        import('../cli/logger.js').then(({ request: logRequest }) => {
+          const url = new URL(req.url, `http://localhost:${port}`)
+          logRequest({ method: req.method, pathname: url.pathname, status: res.statusCode, ms: Date.now() - reqStart })
+        }).catch(() => {})
+      }
+    })
     try {
       // Parse URL — needed before health check and routing
       const url      = new URL(req.url, `http://localhost:${port}`)
@@ -753,7 +765,7 @@ export async function createServer(entries, options = {}) {
     if (draining) return
     draining = true
 
-    console.log('⚡ Pulse shutting down gracefully…')
+    import('../cli/logger.js').then(({ shutdown: logShutdown }) => logShutdown()).catch(() => {})
 
     // Stop background cache eviction timers
     serverDataCache.stopEviction()
@@ -770,7 +782,7 @@ export async function createServer(entries, options = {}) {
 
     // Force-exit after shutdownTimeout so a stuck request can't block a deploy
     setTimeout(() => {
-      console.error(`⚡ Pulse force-exiting after ${shutdownTimeout}ms shutdown timeout`)
+      import('../cli/logger.js').then(({ shutdown: logShutdown }) => logShutdown(true)).catch(() => {})
       process.exit(1)
     }, shutdownTimeout).unref()
   }
@@ -779,7 +791,16 @@ export async function createServer(entries, options = {}) {
   process.on('SIGINT',  shutdown)
 
   server.listen(port, () => {
-    console.log(`⚡ Pulse running at http://localhost:${port}`)
+    import('../cli/logger.js').then(({ banner }) => {
+      banner({
+        url:       `http://localhost:${port}`,
+        version,
+        specs,
+        agentMode,
+      })
+    }).catch(() => {
+      console.log(`⚡ Pulse running at http://localhost:${port}`)
+    })
   })
 
   return {
@@ -981,7 +1002,10 @@ async function handleStreamResponse(spec, ctx, req, res, extraBody = '', dev = f
     meta.schema ? `  <script type="application/ld+json">${JSON.stringify(meta.schema)}</script>` : '',
   ].filter(Boolean).join('\n')
 
-  const bodyAttr = meta.theme ? ` data-theme="${escHtml(meta.theme)}"` : ''
+  const bodyAttr = [
+    meta.theme ? `data-theme="${escHtml(meta.theme)}"` : '',
+    meta.vibe  ? `data-vibe="${escHtml(meta.vibe)}"` : '',
+  ].filter(Boolean).map(a => ` ${a}`).join('')
 
   const docOpen = `<!DOCTYPE html>
 <html lang="en">

package/src/spec/schema.js

@@ -376,6 +376,22 @@ export function validateSpec(spec) {
     warnings.push('spec.hydrate is set manually — it is auto-derived by the framework from the URL entry passed to createServer. Remove it from the spec.')
   }
 
+  // meta — warn on unrecognised fields (e.g. meta.vibe is silently ignored; the correct
+  // field is top-level spec.meta.vibe which IS supported, but an agent might write
+  // meta: { vibe: 'bold' } expecting it to work when the real effect comes from
+  // the framework reading spec.meta.vibe directly — this check catches unknown keys)
+  if (spec.meta && typeof spec.meta === 'object' && !Array.isArray(spec.meta)) {
+    const KNOWN_META_KEYS = new Set([
+      'title', 'description', 'styles', 'scripts', 'theme', 'vibe',
+      'ogTitle', 'ogDescription', 'ogImage', 'canonical', 'schema',
+      'robots', 'viewport', 'charset', 'lang',
+    ])
+    const unknown = Object.keys(spec.meta).filter(k => typeof spec.meta[k] !== 'function' && !KNOWN_META_KEYS.has(k))
+    if (unknown.length) {
+      warnings.push(`spec.meta has unrecognised field${unknown.length > 1 ? 's' : ''}: ${unknown.map(k => `"${k}"`).join(', ')} — these are silently ignored by the framework. Known fields: ${[...KNOWN_META_KEYS].join(', ')}.`)
+    }
+  }
+
   // meta quality
   if (!spec.meta) {
     warnings.push('spec.meta is missing — add at minimum title and description for SEO')
@@ -389,6 +405,11 @@ export function validateSpec(spec) {
     } else if (typeof desc === 'string' && desc.trim() === 'Built with Pulse') {
       warnings.push('spec.meta.description is still the default "Built with Pulse" — replace it with a real description')
     }
+    // If meta.theme is not set (and not a function), Pulse defaults to dark — warn so agents
+    // don't accidentally ship a dark-themed page when they intended light.
+    if (typeof spec.meta.theme !== 'string' && typeof spec.meta.theme !== 'function') {
+      warnings.push('spec.meta.theme is not set — Pulse defaults to dark. Add meta.theme: \'dark\' (or \'light\') to make the intent explicit and suppress this warning.')
+    }
   }
 
   return {

package/src/spec/schema.test.js

@@ -384,6 +384,34 @@ test('validateSpec still warns when hydrate is set manually in source', () => {
   assert(warnings.some(w => w.includes('hydrate')), 'Expected hydrate warning from validateSpec')
 })
 
+// meta.theme warnings
+test('warns when meta.theme is not set', () => {
+  const { warnings } = validateSpec({
+    route: '/entry',
+    view:  () => '<main id="main-content"></main>',
+    meta:  { title: 'Entry', description: 'A page' },
+  })
+  assert(warnings.some(w => w.includes('meta.theme')), 'Expected meta.theme warning')
+})
+
+test('does not warn when meta.theme is a string', () => {
+  const { warnings } = validateSpec({
+    route: '/entry',
+    view:  () => '<main id="main-content"></main>',
+    meta:  { title: 'Entry', description: 'A page', theme: 'dark' },
+  })
+  assert(!warnings.some(w => w.includes('meta.theme')), 'Unexpected meta.theme warning when theme is set')
+})
+
+test('does not warn when meta.theme is a function', () => {
+  const { warnings } = validateSpec({
+    route: '/entry',
+    view:  () => '<main id="main-content"></main>',
+    meta:  { title: 'Entry', description: 'A page', theme: (ctx) => ctx.brand?.theme ?? 'dark' },
+  })
+  assert(!warnings.some(w => w.includes('meta.theme')), 'Unexpected meta.theme warning when theme is a function')
+})
+
 // ---------------------------------------------------------------------------
 
 console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`)

package/src/testing/html.js

@@ -3,7 +3,7 @@
  *
  * No dependencies. Handles common HTML patterns well enough for test assertions.
  * Supports: tag, .class, #id, [attr], [attr="value"] and combinations thereof.
- * Does NOT support descendant combinators (div p) — match within el.findAll() instead.
+ * Supports descendant combinators (div p, .parent span) — findFirst/findAll walk the ancestor stack.
  */
 
 // ---------------------------------------------------------------------------
@@ -152,14 +152,64 @@ export function tokenize(html) {
 // Selector parsing
 // ---------------------------------------------------------------------------
 
+/**
+ * Split a selector on whitespace that is NOT inside [...] attribute brackets.
+ * "span[aria-label="foo bar"]" → ["span[aria-label="foo bar"]"]  (single part)
+ * "div p span"                 → ["div", "p", "span"]
+ *
+ * @param {string} selector
+ * @returns {string[]}
+ */
+function splitDescendant(selector) {
+  const parts = []
+  let current = ''
+  let inBracket = false
+  let inQuote   = false
+  let quoteChar = ''
+
+  for (let i = 0; i < selector.length; i++) {
+    const c = selector[i]
+    if (inQuote) {
+      current += c
+      if (c === quoteChar) inQuote = false
+    } else if (inBracket) {
+      current += c
+      if (c === '"' || c === "'") { inQuote = true; quoteChar = c }
+      else if (c === ']') inBracket = false
+    } else if (c === '[') {
+      inBracket = true
+      current += c
+    } else if (c === ' ') {
+      if (current.trim()) parts.push(current.trim())
+      current = ''
+    } else {
+      current += c
+    }
+  }
+  if (current.trim()) parts.push(current.trim())
+  return parts
+}
+
 /**
  * Parse a simple CSS selector string.
  * Supports: tag  .class  #id  [attr]  [attr="value"]  and combinations.
+ * Also supports descendant combinators: parent child grandchild
  *
  * @param {string} selector
- * @returns {{ tag: string|null, id: string|null, classes: string[], attrs: Array<{name,value}> }}
+ * @returns {{ tag: string|null, id: string|null, classes: string[], attrs: Array<{name,value}> }} | Array of same
  */
 export function parseSelector(selector) {
+  const trimmed = selector.trim()
+  const parts   = splitDescendant(trimmed)
+
+  if (parts.length > 1) {
+    return parts.map(parseSingleSelector)
+  }
+
+  return parseSingleSelector(trimmed)
+}
+
+function parseSingleSelector(selector) {
   const result = { tag: null, id: null, classes: [], attrs: [] }
   let s = selector.trim()
 
@@ -255,29 +305,105 @@ export function extractText(tokens) {
 
 /**
  * Find the first token matching selector.
+ * Supports descendant combinators: parent child
  * @param {Array}  tokens
  * @param {string} selector
  * @returns {{ token, index } | null}
  */
 export function findFirst(tokens, selector) {
   const sel = parseSelector(selector)
+  
+  // Simple selector (no spaces)
+  if (!Array.isArray(sel)) {
+    for (let i = 0; i < tokens.length; i++) {
+      if (matchesToken(tokens[i], sel)) return { token: tokens[i], index: i }
+    }
+    return null
+  }
+  
+  // Descendant selector (array of selectors)
+  const target = sel[sel.length - 1]  // Last selector is the element we're looking for
+  const ancestors = sel.slice(0, -1)  // Earlier selectors are ancestor requirements
+  
   for (let i = 0; i < tokens.length; i++) {
-    if (matchesToken(tokens[i], sel)) return { token: tokens[i], index: i }
+    if (matchesToken(tokens[i], target)) {
+      // Check if all ancestor requirements are met
+      if (hasAncestors(tokens, i, ancestors)) {
+        return { token: tokens[i], index: i }
+      }
+    }
   }
   return null
 }
 
+/**
+ * Check if a token at index has all required ancestors.
+ * @param {Array} tokens
+ * @param {number} index - index of the target token
+ * @param {Array} ancestorSels - array of ancestor selectors to match
+ */
+function hasAncestors(tokens, index, ancestorSels) {
+  if (ancestorSels.length === 0) return true
+  
+  // Build a stack of open tags from start to index
+  const stack = []
+  for (let i = 0; i < index; i++) {
+    if (tokens[i].type === 'open') {
+      stack.push(tokens[i])
+    } else if (tokens[i].type === 'close') {
+      stack.pop()
+    }
+  }
+  
+  // Now check if the stack contains all required ancestors in order
+  // We need to find each ancestor selector somewhere in the stack, in order
+  let stackIdx = 0
+  for (const ancestorSel of ancestorSels) {
+    let found = false
+    while (stackIdx < stack.length) {
+      if (matchesToken(stack[stackIdx], ancestorSel)) {
+        found = true
+        stackIdx++  // Move past this one for the next ancestor search
+        break
+      }
+      stackIdx++
+    }
+    if (!found) return false
+  }
+  
+  return true
+}
+
 /**
  * Find all tokens matching selector.
+ * Supports descendant combinators: parent child
  * @param {Array}  tokens
  * @param {string} selector
  * @returns {Array<{ token, index }>}
  */
 export function findAll(tokens, selector) {
   const sel = parseSelector(selector)
+  
+  // Simple selector (no spaces)
+  if (!Array.isArray(sel)) {
+    const results = []
+    for (let i = 0; i < tokens.length; i++) {
+      if (matchesToken(tokens[i], sel)) results.push({ token: tokens[i], index: i })
+    }
+    return results
+  }
+  
+  // Descendant selector (array of selectors)
+  const target = sel[sel.length - 1]
+  const ancestors = sel.slice(0, -1)
+  
   const results = []
   for (let i = 0; i < tokens.length; i++) {
-    if (matchesToken(tokens[i], sel)) results.push({ token: tokens[i], index: i })
+    if (matchesToken(tokens[i], target)) {
+      if (hasAncestors(tokens, i, ancestors)) {
+        results.push({ token: tokens[i], index: i })
+      }
+    }
   }
   return results
 }

package/src/testing/testing.test.js

@@ -214,6 +214,24 @@ await test('matches attribute selector [attr="value"] (negative)', async () => {
   assert(!result.has('input[type="password"]'), 'Expected no password input')
 })
 
+await test('matches attribute selector [attr="value with spaces"]', async () => {
+  const spec = {
+    route: '/test-attr-spaces',
+    view: () => `<div><span aria-label="3 items in cart">3</span></div>`,
+  }
+  const result = renderSync(spec)
+  assert(result.has('span[aria-label="3 items in cart"]'), 'Expected span with aria-label containing spaces')
+})
+
+await test('descendant selector not confused by spaces in attr value', async () => {
+  const spec = {
+    route: '/test-desc-attr',
+    view: () => `<nav><a href="/cart" aria-label="3 items in cart">Cart</a></nav>`,
+  }
+  const result = renderSync(spec)
+  assert(result.has('nav a[aria-label="3 items in cart"]'), 'Expected descendant with spaced attr value')
+})
+
 // ---------------------------------------------------------------------------
 
 console.log('\nresult.find() and result.get()\n')
@@ -444,6 +462,46 @@ await test('renderSync returns raw html string', async () => {
   assert(typeof result.html === 'string', 'Expected html to be a string')
 })
 
+console.log('\nDescendant selectors\n')
+
+await test('descendant selector finds nested elements', async () => {
+  const spec = {
+    route: '/list',
+    state: {},
+    view:  () => `<div><ul class="items"><li>A</li><li>B</li></ul><ul class="other"><li>X</li></ul></div>`,
+  }
+  const result = renderSync(spec)
+  assertEqual(result.count('.items li'), 2)
+  assertEqual(result.count('.other li'), 1)
+  assertEqual(result.count('ul li'), 3)
+})
+
+await test('descendant selector with multiple levels', async () => {
+  const spec = {
+    route: '/table',
+    state: {},
+    view:  () => `<table><thead><tr><th>Name</th></tr></thead><tbody><tr><td>Alice</td></tr><tr><td>Bob</td></tr></tbody></table>`,
+  }
+  const result = renderSync(spec)
+  assertEqual(result.count('tbody tr'), 2)
+  assertEqual(result.count('thead tr'), 1)
+  const cells = result.findAll('tbody td')
+  assertEqual(cells.length, 2)
+  assertEqual(cells[0].text, 'Alice')
+  assertEqual(cells[1].text, 'Bob')
+})
+
+await test('descendant selector returns empty for no matches', async () => {
+  const spec = {
+    route: '/empty',
+    state: {},
+    view:  () => `<div class="container"><span>text</span></div>`,
+  }
+  const result = renderSync(spec)
+  assertEqual(result.count('.container li'), 0)
+  assertEqual(result.find('.container li'), null)
+})
+
 // ---------------------------------------------------------------------------
 
 console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`)

package/src/ui/banner.js

@@ -4,10 +4,13 @@
  * Full-width announcement bar — sits above the nav for promotions,
  * notices, or launch announcements.
  *
- * @param {object} opts
- * @param {string} opts.content                     - Raw HTML slot
- * @param {'info'|'promo'|'warning'} opts.variant   - Visual style (default: 'info')
- * @param {string} opts.class
+ * @param {object}  opts
+ * @param {string}  opts.content                     - Raw HTML slot
+ * @param {'info'|'promo'|'warning'} opts.variant    - Visual style (default: 'info')
+ * @param {'top'|'bottom'} opts.position             - 'bottom' fixes the bar to the bottom of the viewport
+ * @param {boolean} opts.dismissible                 - Show a close (×) button
+ * @param {string}  opts.dismissEvent                - Mutation name fired on close (default: 'dismissBanner')
+ * @param {string}  opts.class
  */
 
 import { escHtml as e } from '../html.js'
@@ -15,12 +18,24 @@ import { escHtml as e } from '../html.js'
 const VARIANTS = new Set(['info', 'promo', 'warning'])
 
 export function banner({
-  content    = '',
-  variant    = 'info',
-  class: cls = '',
+  content       = '',
+  variant       = 'info',
+  position      = 'top',
+  dismissible   = false,
+  dismissEvent  = 'dismissBanner',
+  class: cls    = '',
 } = {}) {
   if (!VARIANTS.has(variant)) variant = 'info'
-  const classes = ['ui-banner', `ui-banner--${variant}`, cls].filter(Boolean).join(' ')
+  const classes = [
+    'ui-banner',
+    `ui-banner--${variant}`,
+    position === 'bottom' && 'ui-banner--bottom',
+    cls,
+  ].filter(Boolean).join(' ')
 
-  return `<div class="${e(classes)}" role="banner">${content}</div>`
+  const closeBtn = dismissible
+    ? `<button class="ui-banner-close" data-event="${e(dismissEvent)}" aria-label="Close announcement">×</button>`
+    : ''
+
+  return `<div class="${e(classes)}" role="banner">${content}${closeBtn}</div>`
 }

package/src/ui/brand-statement.js

@@ -0,0 +1,58 @@
+/**
+ * Pulse UI — Brand Statement
+ *
+ * Full-width centred editorial statement — large serif or display type used
+ * for brand voice paragraphs between visual sections. This is not a pull-quote
+ * (no attribution border) — it is a first-person brand declaration.
+ *
+ * Typical use: "pieces that are both eclectic and everyday. Subtly precious,
+ * expressive, and refined…"
+ *
+ * @param {object}  opts
+ * @param {string}  opts.text         - Statement text (can include basic HTML like <em>, <br>)
+ * @param {string}  opts.attribution  - Optional small attribution or tagline below
+ * @param {'serif'|'display'|'sans'} opts.font  - Font style (default: 'serif')
+ * @param {'sm'|'md'|'lg'} opts.size  - Text size (default: 'md')
+ * @param {'left'|'center'|'right'} opts.align - Text alignment (default: 'center')
+ * @param {string}  opts.maxWidth     - CSS max-width value (default: '860px')
+ * @param {string}  opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+const FONTS  = new Set(['serif', 'display', 'sans'])
+const SIZES  = new Set(['sm', 'md', 'lg'])
+const ALIGNS = new Set(['left', 'center', 'right'])
+
+export function brandStatement({
+  text         = '',
+  attribution  = '',
+  font         = 'serif',
+  size         = 'md',
+  align        = 'center',
+  maxWidth     = '',
+  class: cls   = '',
+} = {}) {
+  if (!FONTS.has(font))   font  = 'serif'
+  if (!SIZES.has(size))   size  = 'md'
+  if (!ALIGNS.has(align)) align = 'center'
+
+  const classes = [
+    'ui-brand-statement',
+    font  !== 'serif'   && `ui-brand-statement--${font}`,
+    size  !== 'md'      && `ui-brand-statement--${size}`,
+    align !== 'center'  && `ui-brand-statement--${align}`,
+    cls,
+  ].filter(Boolean).join(' ')
+
+  const innerStyle = maxWidth
+    ? ` style="max-width:${e(typeof maxWidth === 'number' ? `${maxWidth}px` : maxWidth)}"`
+    : ''
+
+  return `<div class="${e(classes)}">
+  <div class="ui-brand-statement-inner"${innerStyle}>
+    <p class="ui-brand-statement-text">${text}</p>
+    ${attribution ? `<p class="ui-brand-statement-attr">${e(attribution)}</p>` : ''}
+  </div>
+</div>`
+}

package/src/ui/button.js

@@ -5,7 +5,7 @@
  * All visual variation goes through CSS modifier classes — never inline styles.
  *
  * @param {object} opts
- * @param {string}  opts.label     - Visible text (required)
+ * @param {string}  opts.label     - Visible text — HTML is escaped. For SVG/icon content use opts.icon or opts.iconAfter.
  * @param {'primary'|'secondary'|'ghost'|'danger'} opts.variant
  * @param {'sm'|'md'|'lg'} opts.size
  * @param {string}  opts.href      - Renders as <a> when set
@@ -20,7 +20,7 @@
 
 import { escHtml as e } from '../html.js'
 
-const VARIANTS = new Set(['primary', 'secondary', 'ghost', 'danger'])
+const VARIANTS = new Set(['primary', 'secondary', 'ghost', 'ghost-light', 'danger'])
 const SIZES    = new Set(['sm', 'md', 'lg'])
 
 export function button({
@@ -39,6 +39,16 @@ export function button({
   if (!VARIANTS.has(variant)) variant = 'primary'
   if (!SIZES.has(size))       size    = 'md'
 
+  // Warn if href passed via attrs instead of the href prop (produces invalid <button href>)
+  if (typeof window === 'undefined' && !href && attrs.href) {
+    console.warn('[Pulse button] href passed via attrs produces invalid HTML (<button href>). Use button({ href: "..." }) instead — it renders an <a> automatically.')
+  }
+
+  // Warn if label contains HTML — it will be escaped. Use icon/iconAfter for SVG content.
+  if (typeof window === 'undefined' && label && label.includes('<')) {
+    console.warn('[Pulse button] label is HTML-escaped — SVG/HTML passed as label will render as text. Use icon: svgString or iconAfter: svgString instead.')
+  }
+
   const classes = [
     'ui-btn',
     `ui-btn--${variant}`,
@@ -59,6 +69,7 @@ export function button({
   }
 
   const attrsStr = Object.entries(attrs)
+    .filter(([, v]) => v !== undefined)
     .map(([k, v]) => ` ${e(k)}="${e(String(v))}"`)
     .join('')