@invisibleloop/pulse 0.12.3 → 0.14.1

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)
 }
 
@@ -37,6 +53,12 @@ if (!valid) {
 // Render the view and run additional HTML checks
 const warnings = [...schemaWarnings]
 
+// meta.theme missing — a page without theme set will use the user's system preference,
+// which can produce unexpected dark/light rendering for spec authors who built for one mode.
+if (!spec.meta?.theme) {
+  warnings.push('meta.theme is not set — the page will follow the user\'s system colour-scheme preference. Add meta: { theme: \'light\' } or meta: { theme: \'dark\' } to lock the appearance. Most Pulse pages should set this explicitly.')
+}
+
 // Raw-response specs (contentType + render) produce non-HTML output —
 // skip all view rendering and HTML-specific checks for them.
 const isRawResponse = typeof spec.render === 'function' ||
@@ -98,7 +120,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 +132,16 @@ 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 ' or ' 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.')
   }
 } 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,
 }
 
 /**
@@ -779,7 +780,23 @@ export async function createServer(entries, options = {}) {
   process.on('SIGINT',  shutdown)
 
   server.listen(port, () => {
-    console.log(`⚡ Pulse running at http://localhost:${port}`)
+    import('../cli/fmt.js').then(({ c, table, icon }) => {
+      const url  = `http://localhost:${port}`
+      const rows = specs.map(s => {
+        const hydrated = s.hydrate ? c.green('✓') : c.dim('—')
+        const method   = s.method?.toUpperCase() || 'GET'
+        const route    = s.route || '?'
+        return [c.cyan(route), c.dim(method), hydrated]
+      })
+      console.log(`\n  ${icon.bolt()} ${c.bold('Pulse')}  ${c.dim(`→  ${url}`)}\n`)
+      if (rows.length > 0) {
+        const tbl = table(['Route', 'Method', 'Hydrated'], rows)
+        console.log(tbl.split('\n').map(l => '  ' + l).join('\n'))
+        console.log()
+      }
+    }).catch(() => {
+      console.log(`⚡ Pulse running at http://localhost:${port}`)
+    })
   })
 
   return {
@@ -981,7 +998,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

@@ -389,6 +389,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, Pulse defaults to dark — warn so agents don't accidentally
+    // ship a dark-themed page when they intended light, or forget to declare intent.
+    if (spec.meta.theme === undefined && 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/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
@@ -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('')
 

package/src/ui/card.js

@@ -11,20 +11,39 @@
  * @param {string}  opts.content - HTML string for the card body
  * @param {string}  opts.footer  - HTML string for the card footer (optional)
  * @param {boolean} opts.flush   - Remove internal padding (for full-bleed content)
+ * @param {'default'|'elevated'|'bordered'|'flat'|'glass'|'tinted'} opts.variant
+ *   Visual style:
+ *   - 'default'  — standard surface with subtle shadow (same as no variant)
+ *   - 'elevated' — stronger shadow, lifts above the page
+ *   - 'bordered' — no shadow, prominent border
+ *   - 'flat'     — no shadow, no border, background only
+ *   - 'glass'    — frosted-glass effect with backdrop blur
+ *   - 'tinted'   — accent-tinted background, no shadow
  * @param {string}  opts.class
  */
 
 import { escHtml as e } from '../html.js'
 
+const VARIANTS = new Set(['default', 'elevated', 'bordered', 'flat', 'glass', 'tinted'])
+
 export function card({
   title      = '',
   level      = 3,
   content    = '',
   footer     = '',
   flush      = false,
+  variant    = 'default',
   class: cls = '',
 } = {}) {
-  const classes = ['ui-card', flush ? 'ui-card--flush' : '', cls].filter(Boolean).join(' ')
+  if (!VARIANTS.has(variant)) variant = 'default'
+
+  const classes = [
+    'ui-card',
+    variant !== 'default' ? `ui-card--${variant}` : '',
+    flush ? 'ui-card--flush' : '',
+    cls,
+  ].filter(Boolean).join(' ')
+
   const tag = `h${Math.min(Math.max(Math.floor(level), 1), 6)}`
 
   const titleHtml  = title  ? `<div class="ui-card-header"><${tag} class="ui-card-title">${e(title)}</${tag}></div>` : ''

package/src/ui/colophon.js

@@ -0,0 +1,29 @@
+/**
+ * Pulse UI — Colophon
+ *
+ * Paperback-style end-of-page metadata block. A minimal footer
+ * variant with tight type, no columns, centered layout.
+ *
+ * @param {object} opts
+ * @param {string} opts.content - Raw HTML content slot
+ * @param {'left'|'center'} opts.align - Text alignment (default 'center')
+ * @param {string} opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+export function colophon({
+  content    = '',
+  align      = 'center',
+  class: cls = '',
+} = {}) {
+  const classes = [
+    'ui-colophon',
+    align === 'left' && 'ui-colophon--left',
+    cls,
+  ].filter(Boolean).join(' ')
+
+  return `<footer class="${e(classes)}">
+  <div class="ui-colophon-inner">${content}</div>
+</footer>`
+}

package/src/ui/contact-row.js

@@ -0,0 +1,41 @@
+/**
+ * Pulse UI — ContactRow
+ *
+ * A horizontal strip of contact items — phone, email, address, hours.
+ * Universal on local-business and trades sites. Renders as a <ul> of
+ * icon + label pairs, each optionally linked.
+ *
+ * @param {object}   opts
+ * @param {Array<{icon?: string, label: string, href?: string}>} opts.items
+ * @param {'sm'|'md'} opts.size   - Text size (default: 'md')
+ * @param {string}   opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+const SIZES = new Set(['sm', 'md'])
+
+export function contactRow({
+  items      = [],
+  size       = 'md',
+  class: cls = '',
+} = {}) {
+  if (!SIZES.has(size)) size = 'md'
+
+  const classes = [
+    'ui-contact-row',
+    size !== 'md' && `ui-contact-row--${size}`,
+    cls,
+  ].filter(Boolean).join(' ')
+
+  const itemsHtml = items.map(({ icon = '', label = '', href = '' }) => {
+    const iconHtml = icon ? `<span class="ui-contact-row-icon" aria-hidden="true">${icon}</span>` : ''
+    const inner = `${iconHtml}<span>${e(label)}</span>`
+    const content = href
+      ? `<a href="${e(href)}">${inner}</a>`
+      : inner
+    return `<li class="ui-contact-row-item">${content}</li>`
+  }).join('')
+
+  return `<ul class="${e(classes)}">${itemsHtml}</ul>`
+}