@invisibleloop/pulse 0.14.1 → 0.15.0

package/docs/public/menu.js

@@ -1,5 +1,5 @@
 /**
- * Pulse Docs — Mobile sidebar menu + demo theme toggles
+ * Pulse Docs — Mobile sidebar menu, search, and demo theme toggles
  * Loaded as an external script so it passes the CSP (no unsafe-inline needed).
  */
 (function () {
@@ -12,6 +12,225 @@
     sidebar.scrollTop = sidebar.scrollTop + (linkRect.top - navRect.top) - sidebar.clientHeight / 2 + link.clientHeight / 2
   }
 
+  // ── Sidebar nav filter ────────────────────────────────────────────────────
+
+  function initSidebarSearch(sidebar) {
+    var input    = sidebar && sidebar.querySelector('#sidebar-search')
+    var nav      = sidebar && sidebar.querySelector('#sidebar-nav')
+    var noResult = sidebar && sidebar.querySelector('.sidebar-no-results')
+    if (!input || !nav || input._searchBound) return
+    input._searchBound = true
+
+    function filter(q) {
+      var query = q.trim().toLowerCase()
+      var sections = nav.querySelectorAll('.nav-section')
+      var anyVisible = false
+
+      if (!query) {
+        sections.forEach(function (s) {
+          s.hidden = false
+          s.querySelectorAll('.nav-link').forEach(function (l) { l.hidden = false })
+        })
+        if (noResult) noResult.hidden = true
+        return
+      }
+
+      sections.forEach(function (section) {
+        var sectionLinks = section.querySelectorAll('.nav-link')
+        var sectionHasMatch = false
+        sectionLinks.forEach(function (link) {
+          var matches = link.textContent.toLowerCase().includes(query)
+          link.hidden = !matches
+          if (matches) { sectionHasMatch = true; anyVisible = true }
+        })
+        section.hidden = !sectionHasMatch
+      })
+
+      if (noResult) noResult.hidden = anyVisible
+    }
+
+    input.addEventListener('input', function () { filter(this.value) })
+
+    input.addEventListener('keydown', function (e) {
+      if (e.key === 'Escape') {
+        input.value = ''
+        filter('')
+        input.blur()
+      }
+    })
+  }
+
+  // ── Full-text search overlay ──────────────────────────────────────────────
+
+  var _searchIndex = null
+
+  function loadSearchIndex(cb) {
+    if (_searchIndex) { cb(_searchIndex); return }
+    fetch('/search-index.json')
+      .then(function (r) { return r.json() })
+      .then(function (data) { _searchIndex = data; cb(data) })
+      .catch(function () { cb([]) })
+  }
+
+  function searchIndex(query, index) {
+    var q = query.trim().toLowerCase()
+    if (!q) return []
+    return index.filter(function (item) {
+      return item.title.toLowerCase().includes(q) ||
+             item.section.toLowerCase().includes(q) ||
+             (item.body && item.body.toLowerCase().includes(q))
+    }).slice(0, 12)
+  }
+
+  function highlight(text, query) {
+    if (!query) return text
+    var re = new RegExp('(' + query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + ')', 'gi')
+    return text.replace(re, '<mark>$1</mark>')
+  }
+
+  function snippet(body, query) {
+    if (!body || !query) return ''
+    var idx = body.toLowerCase().indexOf(query.toLowerCase())
+    if (idx === -1) return ''
+    var start = Math.max(0, idx - 40)
+    var end   = Math.min(body.length, idx + query.length + 80)
+    var s = (start > 0 ? '…' : '') + body.slice(start, end) + (end < body.length ? '…' : '')
+    return highlight(s, query)
+  }
+
+  function renderResults(results, query, container, selectedIdx) {
+    while (container.firstChild) container.removeChild(container.firstChild)
+
+    if (!results.length) {
+      var empty = document.createElement('p')
+      empty.className = 'search-overlay-empty'
+      empty.textContent = 'No results for '
+      var strong = document.createElement('strong')
+      strong.textContent = query
+      empty.appendChild(strong)
+      container.appendChild(empty)
+      return
+    }
+
+    results.forEach(function (item, i) {
+      var a = document.createElement('a')
+      a.href = item.href
+      a.className = 'search-result' + (i === selectedIdx ? ' search-result--selected' : '')
+      a.setAttribute('role', 'option')
+      if (i === selectedIdx) a.setAttribute('aria-selected', 'true')
+
+      var meta = document.createElement('div')
+      meta.className = 'search-result-meta'
+      var section = document.createElement('span')
+      section.className = 'search-result-section'
+      section.textContent = item.section
+      meta.appendChild(section)
+      a.appendChild(meta)
+
+      var title = document.createElement('div')
+      title.className = 'search-result-title'
+      setHighlighted(title, item.title, query)
+      a.appendChild(title)
+
+      var snip = snippet(item.body, query)
+      if (snip) {
+        var snipEl = document.createElement('div')
+        snipEl.className = 'search-result-snip'
+        setHighlighted(snipEl, snip, null) // snip already has highlight markers stripped
+        a.appendChild(snipEl)
+      }
+
+      container.appendChild(a)
+    })
+  }
+
+  function setHighlighted(el, text, query) {
+    if (!query) { el.textContent = text; return }
+    var lower = text.toLowerCase()
+    var q = query.toLowerCase()
+    var idx = lower.indexOf(q)
+    if (idx === -1) { el.textContent = text; return }
+    var before = document.createTextNode(text.slice(0, idx))
+    var mark = document.createElement('mark')
+    mark.textContent = text.slice(idx, idx + query.length)
+    var after = document.createTextNode(text.slice(idx + query.length))
+    el.appendChild(before)
+    el.appendChild(mark)
+    el.appendChild(after)
+  }
+
+  function initSearchOverlay() {
+    var overlay   = document.getElementById('search-overlay')
+    var input     = document.getElementById('search-overlay-input')
+    var results   = document.getElementById('search-overlay-results')
+    var fullBtns  = document.querySelectorAll('.sidebar-search-full')
+    if (!overlay || !input || !results) return
+
+    var selectedIdx = -1
+    var currentResults = []
+    var currentQuery = ''
+
+    function open() {
+      overlay.hidden = false
+      document.body.style.overflow = 'hidden'
+      setTimeout(function () { input.focus() }, 50)
+      selectedIdx = -1
+    }
+
+    function close() {
+      overlay.hidden = true
+      document.body.style.overflow = ''
+      input.value = ''
+      results.innerHTML = ''
+      currentResults = []
+      currentQuery = ''
+      selectedIdx = -1
+    }
+
+    function navigate(dir) {
+      selectedIdx = Math.max(-1, Math.min(currentResults.length - 1, selectedIdx + dir))
+      renderResults(currentResults, currentQuery, results, selectedIdx)
+      var sel = results.querySelector('.search-result--selected')
+      if (sel) sel.scrollIntoView({ block: 'nearest' })
+    }
+
+    fullBtns.forEach(function (btn) { btn.addEventListener('click', open) })
+
+    overlay.querySelector('.search-overlay-backdrop').addEventListener('click', close)
+    overlay.querySelector('.search-overlay-close').addEventListener('click', close)
+
+    input.addEventListener('input', function () {
+      var q = this.value.trim()
+      currentQuery = q
+      selectedIdx = -1
+      if (!q) { results.innerHTML = ''; currentResults = []; return }
+      loadSearchIndex(function (index) {
+        currentResults = searchIndex(q, index)
+        renderResults(currentResults, q, results, selectedIdx)
+      })
+    })
+
+    input.addEventListener('keydown', function (e) {
+      if (e.key === 'Escape') { close(); return }
+      if (e.key === 'ArrowDown') { e.preventDefault(); navigate(1); return }
+      if (e.key === 'ArrowUp')   { e.preventDefault(); navigate(-1); return }
+      if (e.key === 'Enter') {
+        if (selectedIdx >= 0 && currentResults[selectedIdx]) {
+          window.location.href = currentResults[selectedIdx].href
+          close()
+        }
+      }
+    })
+
+    document.addEventListener('keydown', function (e) {
+      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+        e.preventDefault()
+        overlay.hidden ? open() : close()
+      }
+      if (e.key === 'Escape' && !overlay.hidden) close()
+    })
+  }
+
   // ── Bind sidebar, mobile menu, and centre the active link ─────────────────
   // Called on first load and after every client-side navigation, because
   // #pulse-root is replaced on navigate — all element references go stale.
@@ -49,13 +268,25 @@
     // Centre the active link
     var activeLink = sidebar && sidebar.querySelector('.nav-link.active')
     if (activeLink) centerNavLink(sidebar, activeLink)
+
+    // Sidebar filter
+    initSidebarSearch(sidebar)
+
+    // Full-text search overlay (only bind once — overlay persists across navigations)
+    if (!document.getElementById('search-overlay')?._searchBound) {
+      initSearchOverlay()
+      var o = document.getElementById('search-overlay')
+      if (o) o._searchBound = true
+    }
   }
 
-  // On initial load — wait for layout paint before scrolling
-  if (document.readyState === 'complete') {
+  // On initial load — defer slightly to ensure layout paint before scrolling.
+  // Use both paths: if load already fired (common with defer scripts), run now;
+  // otherwise wait for it.
+  if (document.readyState === 'complete' || document.readyState === 'interactive') {
     setTimeout(init, 50)
   } else {
-    window.addEventListener('load', init)
+    window.addEventListener('load', function () { setTimeout(init, 50) })
   }
 
   // After client-side navigation — re-bind everything against the fresh DOM
@@ -88,9 +319,9 @@
 
   document.addEventListener('pulse:navigate', bindDemoControls)
 
-  if (document.readyState === 'complete') {
+  if (document.readyState === 'complete' || document.readyState === 'interactive') {
     setTimeout(bindDemoControls, 50)
   } else {
-    window.addEventListener('load', bindDemoControls)
+    window.addEventListener('load', function () { setTimeout(bindDemoControls, 50) })
   }
 })()

package/docs/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/docs/public/theme.css

@@ -0,0 +1,8 @@
+/* Brut theme tokens */
+:root {
+  --brut-yellow: #f0e642;
+  --brut-ink: #0a0a0a;
+  --brut-surface: #ffffff;
+  --brut-dark: #111114;
+  --brut-darker: #111214;
+}

package/docs/server.js

@@ -3,8 +3,17 @@ import { createServer }        from '../src/server/index.js'
 import { initLayoutManifest }  from './src/lib/layout.js'
 import { metrics }             from './src/lib/stats.js'
 import { metricsStore }        from './src/lib/metrics-store.js'
+import { NAV }                 from './src/lib/nav.js'
 metricsStore.current = metrics
 
+// Build search index once at startup from nav structure
+const searchIndex = JSON.stringify(
+  NAV.flatMap(({ section, items }) =>
+    items.map(item => ({ title: item.label, href: item.href, section, body: '' }))
+  )
+)
+const searchIndexEtag = `"${Buffer.from(searchIndex).length}-search"`
+
 // Populate hashed asset paths in layout.js before any page renders
 try {
   const raw = fs.readFileSync(new URL('./public/dist/manifest.json', import.meta.url), 'utf8')
@@ -142,5 +151,20 @@ await createServer(
       'style-src': ['https://fonts.googleapis.com'],
       'font-src':  ['https://fonts.gstatic.com'],
     },
+    onRequest(req, res) {
+      if (req.url !== '/search-index.json') return
+      if (req.headers['if-none-match'] === searchIndexEtag) {
+        res.writeHead(304)
+        res.end()
+        return false
+      }
+      res.writeHead(200, {
+        'Content-Type':  'application/json; charset=utf-8',
+        'Cache-Control': 'public, max-age=3600',
+        'ETag':          searchIndexEtag,
+      })
+      res.end(searchIndex)
+      return false
+    },
   }
 )

package/docs/src/lib/layout.js

@@ -34,7 +34,7 @@ function sidebar(currentHref) {
   }).join('')
 
   return `
-    <aside class="docs-sidebar" aria-label="Documentation navigation">
+    <aside class="docs-sidebar" id="docs-sidebar" aria-label="Documentation navigation">
       <div class="sidebar-logo">
         <a href="/" class="logo-link" aria-label="Pulse home">
           <svg width="24" height="24" viewBox="0 0 24 24" fill="none" aria-hidden="true">
@@ -44,10 +44,58 @@ function sidebar(currentHref) {
         </a>
         <span class="version-badge">v${version}</span>
       </div>
-      <nav class="sidebar-nav">
+      <div class="sidebar-search-wrap">
+        <svg class="sidebar-search-icon" width="14" height="14" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
+          <path fill-rule="evenodd" d="M8 4a4 4 0 100 8 4 4 0 000-8zM2 8a6 6 0 1110.89 3.476l4.817 4.817a1 1 0 01-1.414 1.414l-4.816-4.816A6 6 0 012 8z" clip-rule="evenodd"/>
+        </svg>
+        <input
+          type="search"
+          id="sidebar-search"
+          class="sidebar-search"
+          placeholder="Filter pages…"
+          aria-label="Filter documentation pages"
+          autocomplete="off"
+          spellcheck="false"
+        >
+        <button class="sidebar-search-full" aria-label="Search all docs content" title="Search all docs">
+          <svg width="14" height="14" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
+            <path fill-rule="evenodd" d="M3 4a1 1 0 011-1h12a1 1 0 110 2H4a1 1 0 01-1-1zm0 4a1 1 0 011-1h12a1 1 0 110 2H4a1 1 0 01-1-1zm0 4a1 1 0 011-1h7a1 1 0 110 2H4a1 1 0 01-1-1z" clip-rule="evenodd"/>
+          </svg>
+        </button>
+      </div>
+      <nav class="sidebar-nav" id="sidebar-nav">
         ${sections}
+        <p class="sidebar-no-results" hidden>No pages found</p>
       </nav>
-    </aside>`
+    </aside>
+    <div class="search-overlay" id="search-overlay" role="dialog" aria-modal="true" aria-label="Search documentation" hidden>
+      <div class="search-overlay-backdrop"></div>
+      <div class="search-overlay-panel">
+        <div class="search-overlay-header">
+          <div class="search-overlay-input-wrap">
+            <svg width="18" height="18" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
+              <path fill-rule="evenodd" d="M8 4a4 4 0 100 8 4 4 0 000-8zM2 8a6 6 0 1110.89 3.476l4.817 4.817a1 1 0 01-1.414 1.414l-4.816-4.816A6 6 0 012 8z" clip-rule="evenodd"/>
+            </svg>
+            <input
+              type="search"
+              id="search-overlay-input"
+              class="search-overlay-input"
+              placeholder="Search all docs…"
+              aria-label="Search all documentation"
+              autocomplete="off"
+              spellcheck="false"
+            >
+          </div>
+          <button class="search-overlay-close" aria-label="Close search">ESC</button>
+        </div>
+        <div class="search-overlay-results" id="search-overlay-results" role="listbox" aria-label="Search results"></div>
+        <div class="search-overlay-footer">
+          <span><kbd>↑</kbd><kbd>↓</kbd> navigate</span>
+          <span><kbd>↵</kbd> open</span>
+          <span><kbd>ESC</kbd> close</span>
+        </div>
+      </div>
+    </div>`
 }
 
 function prevNextBar(prev, next) {

package/docs/src/pages/getting-started.js

@@ -22,7 +22,7 @@ export default {
       ${section('requirements', 'Requirements')}
       <ul>
         <li><strong>Node.js 22 or later</strong> — <a href="https://nodejs.org" target="_blank" rel="noopener" aria-label="nodejs.org (opens in new tab)">nodejs.org</a></li>
-        <li><strong>Google Chrome</strong> — used by the agent for screenshots and Lighthouse audits — <a href="https://www.google.com/chrome" target="_blank" rel="noopener" aria-label="Download Google Chrome (opens in new tab)">google.com/chrome</a></li>
+        <li><strong>Google Chrome</strong> — used by the agent for screenshots and Lighthouse audits — <a href="https://www.google.com/chrome" target="_blank" rel="noopener" aria-label="google.com/chrome (opens in new tab)">google.com/chrome</a></li>
         <li><strong>An AI agent</strong> — Claude Code or GitHub Copilot CLI (pick one):</li>
       </ul>
       <ul>