@invisibleloop/pulse 0.1.21

package/docs/src/lib/highlight.js

@@ -0,0 +1,255 @@
+/**
+ * Pulse Docs — Server-side syntax highlighter
+ *
+ * Character-by-character tokeniser. No dependencies, no client JS.
+ * Returns an HTML string of <span> elements ready to drop inside <code>.
+ */
+
+const KEYWORDS = new Set([
+  'export', 'default', 'import', 'from', 'as',
+  'async', 'await', 'const', 'let', 'var',
+  'return', 'if', 'else', 'for', 'while', 'of', 'in',
+  'true', 'false', 'null', 'undefined',
+  'function', 'class', 'new', 'this', 'typeof', 'instanceof',
+  'try', 'catch', 'finally', 'throw',
+])
+
+function esc(s) {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+function span(cls, text) {
+  return `<span class="${cls}">${esc(text)}</span>`
+}
+
+export function highlight(code, lang = 'js') {
+  if (lang === 'bash') return highlightBash(code)
+  if (lang === 'html') return highlightHtml(code)
+  return highlightJs(code)
+}
+
+// ---------------------------------------------------------------------------
+// JavaScript tokeniser
+// ---------------------------------------------------------------------------
+
+function highlightJs(code) {
+  let out = ''
+  let i = 0
+  const n = code.length
+
+  while (i < n) {
+    const ch  = code[i]
+    const ch2 = code[i + 1]
+
+    // Single-line comment
+    if (ch === '/' && ch2 === '/') {
+      const end = code.indexOf('\n', i)
+      const tok = end === -1 ? code.slice(i) : code.slice(i, end)
+      out += span('tok-cmt', tok)
+      i += tok.length
+      continue
+    }
+
+    // Block comment
+    if (ch === '/' && ch2 === '*') {
+      const end = code.indexOf('*/', i + 2)
+      const tok = end === -1 ? code.slice(i) : code.slice(i, end + 2)
+      out += span('tok-cmt', tok)
+      i += tok.length
+      continue
+    }
+
+    // Template literal
+    if (ch === '`') {
+      let tok = '`'
+      i++
+      let depth = 0
+      while (i < n) {
+        if (code[i] === '\\') {
+          tok += code[i] + (code[i + 1] || '')
+          i += 2
+          continue
+        }
+        if (code[i] === '$' && code[i + 1] === '{') {
+          tok += '${'
+          i += 2
+          depth++
+          continue
+        }
+        if (code[i] === '}' && depth > 0) {
+          tok += '}'
+          i++
+          depth--
+          continue
+        }
+        if (code[i] === '`' && depth === 0) {
+          tok += '`'
+          i++
+          break
+        }
+        tok += code[i++]
+      }
+      out += span('tok-str', tok)
+      continue
+    }
+
+    // Single or double quoted string
+    if (ch === '"' || ch === "'") {
+      let tok = ch
+      i++
+      while (i < n && code[i] !== ch && code[i] !== '\n') {
+        if (code[i] === '\\') {
+          tok += code[i] + (code[i + 1] || '')
+          i += 2
+          continue
+        }
+        tok += code[i++]
+      }
+      if (i < n && code[i] === ch) tok += code[i++]
+      out += span('tok-str', tok)
+      continue
+    }
+
+    // Number
+    if (/\d/.test(ch) && (i === 0 || !/\w/.test(code[i - 1]))) {
+      let tok = ''
+      while (i < n && /[\d.xXa-fA-F]/.test(code[i])) tok += code[i++]
+      out += span('tok-num', tok)
+      continue
+    }
+
+    // Identifier / keyword
+    if (/[a-zA-Z_$]/.test(ch)) {
+      let tok = ''
+      while (i < n && /[\w$]/.test(code[i])) tok += code[i++]
+
+      if (KEYWORDS.has(tok)) {
+        out += span('tok-kw', tok)
+      } else {
+        // Look ahead: followed by ( → function call
+        let j = i
+        while (j < n && code[j] === ' ') j++
+        if (code[j] === '(') {
+          out += span('tok-fn', tok)
+        } else {
+          out += esc(tok)
+        }
+      }
+      continue
+    }
+
+    // Operators
+    if (/[=!<>|&?.]/.test(ch)) {
+      let tok = ch
+      // Grab two-char operators
+      if (/[=!<>|&?]/.test(ch) && /[=|&>?]/.test(ch2)) {
+        tok = code.slice(i, i + 2)
+        // Three-char: ===, !==, ...
+        if (code[i + 2] === '=') tok = code.slice(i, i + 3)
+      }
+      out += span('tok-op', tok)
+      i += tok.length
+      continue
+    }
+
+    // Punctuation
+    if (/[{}()[\],;:]/.test(ch)) {
+      out += span('tok-punct', ch)
+      i++
+      continue
+    }
+
+    // Everything else (whitespace, newlines, etc.)
+    out += esc(ch)
+    i++
+  }
+
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// Bash tokeniser (minimal)
+// ---------------------------------------------------------------------------
+
+function highlightBash(code) {
+  return code.split('\n').map(line => {
+    // Comment line
+    if (/^\s*#/.test(line)) return span('tok-cmt', line)
+
+    let out = ''
+    let i = 0
+    while (i < line.length) {
+      // Inline comment
+      if (line[i] === '#') {
+        out += span('tok-cmt', line.slice(i))
+        break
+      }
+      // String
+      if (line[i] === '"' || line[i] === "'") {
+        const q = line[i]
+        let tok = q
+        i++
+        while (i < line.length && line[i] !== q) tok += line[i++]
+        tok += line[i] === q ? line[i++] : ''
+        out += span('tok-str', tok)
+        continue
+      }
+      // Flag/option
+      if (line[i] === '-' && /\w/.test(line[i + 1] || '')) {
+        let tok = '-'
+        i++
+        while (i < line.length && /[-\w]/.test(line[i])) tok += line[i++]
+        out += span('tok-op', tok)
+        continue
+      }
+      out += esc(line[i++])
+    }
+    return out
+  }).join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// HTML tokeniser (minimal)
+// ---------------------------------------------------------------------------
+
+function highlightHtml(code) {
+  let out = ''
+  let i = 0
+  const n = code.length
+
+  while (i < n) {
+    // Comment
+    if (code.slice(i, i + 4) === '<!--') {
+      const end = code.indexOf('-->', i + 4)
+      const tok = end === -1 ? code.slice(i) : code.slice(i, end + 3)
+      out += span('tok-cmt', tok)
+      i += tok.length
+      continue
+    }
+
+    // Tag
+    if (code[i] === '<') {
+      const end = code.indexOf('>', i)
+      if (end === -1) { out += esc(code[i++]); continue }
+      const tag = code.slice(i, end + 1)
+      // Simple: highlight tag name + attributes
+      const highlighted = tag.replace(
+        /^(<\/?)([\w-]+)/,
+        (_, lt, name) => esc(lt) + span('tok-kw', name)
+      ).replace(
+        /([\w-]+)(=)/g,
+        (_, attr, eq) => span('tok-fn', attr) + esc(eq)
+      ).replace(
+        /("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*')/g,
+        (_, str) => span('tok-str', str)
+      )
+      out += highlighted
+      i = end + 1
+      continue
+    }
+
+    out += esc(code[i++])
+  }
+
+  return out
+}

package/docs/src/lib/layout.js

@@ -0,0 +1,131 @@
+/**
+ * Pulse Docs — Page layout
+ *
+ * renderLayout({ currentHref, content, prev, next }) → HTML string
+ * Used by every docs page except the home page.
+ */
+
+import { NAV } from './nav.js'
+
+function esc(s) {
+  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+}
+
+function sidebar(currentHref) {
+  const sections = NAV.map(({ section, items }) => {
+    const links = items.map(item => {
+      const active = item.href === currentHref
+      return `<a href="${esc(item.href)}" class="nav-link${active ? ' active' : ''}"${active ? ' aria-current="page"' : ''}>${esc(item.label)}</a>`
+    }).join('')
+    return `
+      <div class="nav-section">
+        <p class="nav-section-title">${esc(section)}</p>
+        ${links}
+      </div>`
+  }).join('')
+
+  return `
+    <aside class="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">
+            <path d="M13 2L4.5 13.5H11L10 22L19.5 10.5H13L13 2Z" fill="var(--accent)" stroke="var(--accent)" stroke-width="1" stroke-linejoin="round"/>
+          </svg>
+          <span class="logo-name">Pulse</span>
+        </a>
+        <span class="version-badge">v0.1</span>
+      </div>
+      <nav class="sidebar-nav">
+        ${sections}
+      </nav>
+    </aside>`
+}
+
+function prevNextBar(prev, next) {
+  if (!prev && !next) return ''
+  return `
+    <nav class="doc-prev-next" aria-label="Previous and next pages">
+      <div class="prev-next-grid">
+        ${prev ? `<a href="${esc(prev.href)}" class="prev-next-link prev-link">
+          <span class="prev-next-label">← Previous</span>
+          <span class="prev-next-title">${esc(prev.label)}</span>
+        </a>` : '<div></div>'}
+        ${next ? `<a href="${esc(next.href)}" class="prev-next-link next-link">
+          <span class="prev-next-label">Next →</span>
+          <span class="prev-next-title">${esc(next.label)}</span>
+        </a>` : '<div></div>'}
+      </div>
+    </nav>`
+}
+
+export function renderLayout({ currentHref, content, prev = null, next = null }) {
+  return `
+    <div class="sidebar-overlay" aria-hidden="true"></div>
+    ${sidebar(currentHref)}
+    <div class="docs-main">
+      <header class="docs-header">
+        <button class="mobile-menu-btn" aria-label="Toggle navigation menu" aria-expanded="false" aria-controls="docs-sidebar">
+          <svg width="20" height="20" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
+            <path fill-rule="evenodd" d="M2 4.75A.75.75 0 012.75 4h14.5a.75.75 0 010 1.5H2.75A.75.75 0 012 4.75zm0 10.5a.75.75 0 01.75-.75h14.5a.75.75 0 010 1.5H2.75a.75.75 0 01-.75-.75zM2 10a.75.75 0 01.75-.75h14.5a.75.75 0 010 1.5H2.75A.75.75 0 012 10z" clip-rule="evenodd"/>
+          </svg>
+        </button>
+        <a href="/" class="header-logo-mobile" aria-label="Pulse home">
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+            <path d="M13 2L4.5 13.5H11L10 22L19.5 10.5H13L13 2Z" fill="var(--accent)" stroke="var(--accent)" stroke-width="1" stroke-linejoin="round"/>
+          </svg>
+        </a>
+        <a href="https://github.com/invisibleloop/pulse" class="header-github" aria-label="View on GitHub" target="_blank" rel="noopener noreferrer">
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+            <path d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.027 2.747-1.027.546 1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z"/>
+          </svg>
+          GitHub
+        </a>
+      </header>
+      <main class="docs-content">
+        ${content}
+        ${prevNextBar(prev, next)}
+      </main>
+    </div>
+    <script src="/menu.js"></script>
+    <script src="/pulse-ui.js"></script>`
+}
+
+/**
+ * Convenience helpers used in every page's view function
+ */
+
+export function h1(text) {
+  return `<h1 class="doc-h1">${esc(text)}</h1>`
+}
+
+export function lead(text) {
+  return `<p class="doc-lead">${text}</p>`
+}
+
+export function section(id, title) {
+  return `<h2 class="doc-h2" id="${esc(id)}"><a href="#${esc(id)}" class="heading-anchor">${esc(title)}</a></h2>`
+}
+
+export function sub(id, title) {
+  const label = title ?? id
+  return `<h3 class="doc-h3" id="${esc(id)}"><a href="#${esc(id)}" class="heading-anchor">${esc(label)}</a></h3>`
+}
+
+export function codeBlock(highlighted, filename = '') {
+  const header = filename ? `<div class="code-filename">${esc(filename)}</div>` : ''
+  return `${header}<pre class="code-block"><code>${highlighted}</code></pre>`
+}
+
+export function table(headers, rows) {
+  const ths = headers.map(h => `<th>${h}</th>`).join('')
+  const trs = rows.map(row =>
+    `<tr>${row.map(cell => `<td>${cell}</td>`).join('')}</tr>`
+  ).join('')
+  return `<div class="table-wrap"><table><thead><tr>${ths}</tr></thead><tbody>${trs}</tbody></table></div>`
+}
+
+export function callout(type, content) {
+  // type: 'note' | 'warning' | 'tip'
+  const icons = { note: 'ℹ', warning: '⚠', tip: '✦' }
+  return `<div class="callout callout-${esc(type)}"><span class="callout-icon" aria-hidden="true">${icons[type] || 'ℹ'}</span><div class="callout-body">${content}</div></div>`
+}

package/docs/src/lib/metrics-store.js

@@ -0,0 +1,6 @@
+/**
+ * Shared metrics holder. Populated by docs/server.js at startup
+ * before createServer() is called. home.js reads from here so
+ * the spec file stays free of Node built-ins (safe to bundle for browser).
+ */
+export const metricsStore = { current: null }

package/docs/src/lib/nav.js

@@ -0,0 +1,159 @@
+/**
+ * Pulse Docs — Navigation structure
+ */
+
+export const NAV = [
+  {
+    section: 'Framework',
+    items: [
+      { label: 'Overview',          href: '/'                  },
+      { label: 'FAQ',               href: '/faq'               },
+      { label: 'Project Structure', href: '/project-structure' },
+      { label: 'Spec Reference',    href: '/spec'              },
+      { label: 'Configuration',     href: '/config'            },
+    ],
+  },
+  {
+    section: 'Developer Guide',
+    items: [
+      { label: 'Getting Started',   href: '/getting-started'   },
+      { label: 'How It Works',      href: '/how-it-works'      },
+      { label: 'Slash Commands',    href: '/slash-commands'    },
+      { label: 'Prompt Examples',   href: '/prompt-examples'   },
+      { label: 'Component Library', href: '/components'        },
+    ],
+  },
+  {
+    section: 'State & Behaviour',
+    items: [
+      { label: 'State',        href: '/state'       },
+      { label: 'Mutations',    href: '/mutations'   },
+      { label: 'Actions',      href: '/actions'     },
+      { label: 'Validation',   href: '/validation'  },
+      { label: 'Constraints',  href: '/constraints' },
+      { label: 'Persist',      href: '/persist'     },
+    ],
+  },
+  {
+    section: 'Server',
+    items: [
+      { label: 'Server Data',    href: '/server-data'   },
+      { label: 'Global Store',   href: '/store'         },
+      { label: 'Routing',        href: '/routing'       },
+      { label: 'Streaming SSR',  href: '/streaming'     },
+      { label: 'Caching',        href: '/caching'       },
+      { label: 'Guard',          href: '/guard'         },
+      { label: 'Raw Responses',  href: '/raw-responses' },
+      { label: 'Server API',     href: '/server-api'    },
+      { label: 'Extending Pulse', href: '/extending'    },
+    ],
+  },
+  {
+    section: 'Client',
+    items: [
+      { label: 'Hydration',   href: '/hydration'  },
+      { label: 'Navigation',  href: '/navigation' },
+      { label: 'Images',      href: '/images'     },
+    ],
+  },
+  {
+    section: 'Deployment',
+    items: [
+      { label: 'Deployment', href: '/deploy' },
+    ],
+  },
+  {
+    section: 'Integrations',
+    items: [
+      { label: 'Supabase',          href: '/supabase' },
+      { label: 'Auth (Auth0)',      href: '/auth'     },
+      { label: 'Payments (Stripe)', href: '/stripe'   },
+    ],
+  },
+  {
+    section: 'Reference',
+    items: [
+      { label: 'Metadata & SEO',  href: '/meta'          },
+      { label: 'Performance',     href: '/performance'   },
+      { label: 'Accessibility',   href: '/accessibility' },
+      { label: 'Testing',         href: '/testing'       },
+    ],
+  },
+  {
+    section: 'UI Components',
+    items: [
+      { label: 'Alert',       href: '/components/alert'       },
+      { label: 'Avatar',      href: '/components/avatar'      },
+      { label: 'Badge',       href: '/components/badge'       },
+      { label: 'Breadcrumbs', href: '/components/breadcrumbs' },
+      { label: 'Button',      href: '/components/button'      },
+      { label: 'Card',        href: '/components/card'        },
+      { label: 'Checkbox',    href: '/components/checkbox'    },
+      { label: 'Carousel',    href: '/components/carousel'    },
+      { label: 'Charts',      href: '/components/charts'      },
+      { label: 'Empty',       href: '/components/empty'       },
+      { label: 'Fieldset',    href: '/components/fieldset'    },
+      { label: 'File Upload', href: '/components/file-upload' },
+      { label: 'Heading',     href: '/components/heading'     },
+      { label: 'Icons',       href: '/components/icons'       },
+      { label: 'Image',       href: '/components/image'       },
+      { label: 'Input',       href: '/components/input'       },
+      { label: 'List',        href: '/components/list'        },
+      { label: 'Modal',       href: '/components/modal'       },
+      { label: 'Progress',    href: '/components/progress'    },
+      { label: 'Prose',       href: '/components/prose'       },
+      { label: 'Pullquote',   href: '/components/pullquote'   },
+      { label: 'Radio',       href: '/components/radio'       },
+      { label: 'Rating',      href: '/components/rating'      },
+      { label: 'Search',      href: '/components/search'      },
+      { label: 'Segmented',   href: '/components/segmented'   },
+      { label: 'Select',      href: '/components/select'      },
+      { label: 'Slider',      href: '/components/slider'      },
+      { label: 'Spinner',     href: '/components/spinner'     },
+      { label: 'Stat',        href: '/components/stat'        },
+      { label: 'Stepper',     href: '/components/stepper'     },
+      { label: 'Table',       href: '/components/table'       },
+      { label: 'Textarea',    href: '/components/textarea'    },
+      { label: 'Timeline',    href: '/components/timeline'    },
+      { label: 'Toggle',      href: '/components/toggle'      },
+      { label: 'Tooltip',     href: '/components/tooltip'     },
+    ],
+  },
+  {
+    section: 'Landing Components',
+    items: [
+      { label: 'Accordion',   href: '/components/accordion'   },
+      { label: 'App Badge',   href: '/components/app-badge'   },
+      { label: 'CTA',         href: '/components/cta'         },
+      { label: 'Feature',     href: '/components/feature'     },
+      { label: 'Hero',        href: '/components/hero'        },
+      { label: 'Nav',         href: '/components/nav'         },
+      { label: 'Pricing',     href: '/components/pricing'     },
+      { label: 'Testimonial', href: '/components/testimonial' },
+    ],
+  },
+  {
+    section: 'Layout Components',
+    items: [
+      { label: 'Banner',      href: '/components/banner'      },
+      { label: 'Cluster',     href: '/components/cluster'     },
+      { label: 'Code Window', href: '/components/code-window' },
+      { label: 'Container',   href: '/components/container'   },
+      { label: 'Divider',     href: '/components/divider'     },
+      { label: 'Footer',      href: '/components/footer'      },
+      { label: 'Grid',        href: '/components/grid'        },
+      { label: 'Media',       href: '/components/media'       },
+      { label: 'Section',     href: '/components/section'     },
+      { label: 'Stack',       href: '/components/stack'       },
+    ],
+  },
+]
+
+export function prevNext(currentHref) {
+  const all = NAV.flatMap(s => s.items)
+  const idx = all.findIndex(i => i.href === currentHref)
+  return {
+    prev: idx > 0             ? all[idx - 1] : null,
+    next: idx < all.length - 1 ? all[idx + 1] : null,
+  }
+}

package/docs/src/lib/stats.js

@@ -0,0 +1,81 @@
+/**
+ * Performance metrics — computed once at server start from real build output.
+ * Bundle sizes are measured by compressing the actual dist files with brotli.
+ */
+
+import fs   from 'fs'
+import path  from 'path'
+import zlib  from 'zlib'
+import { fileURLToPath } from 'url'
+
+const ROOT = path.resolve(fileURLToPath(import.meta.url), '../../../../..')
+const DIST = path.join(ROOT, 'benchmark', 'public', 'dist')
+
+function brotliKb(filepath) {
+  try {
+    const buf = fs.readFileSync(filepath)
+    return zlib.brotliCompressSync(buf).length / 1024
+  } catch {
+    return null
+  }
+}
+
+function measureBundles() {
+  if (!fs.existsSync(DIST)) return null
+  const files = fs.readdirSync(DIST).filter(f => f.endsWith('.js'))
+
+  // Main runtime = largest runtime-*.js file
+  const runtimes = files
+    .filter(f => f.startsWith('runtime-'))
+    .map(f => ({ f, kb: brotliKb(path.join(DIST, f)) }))
+    .filter(x => x.kb !== null)
+    .sort((a, b) => b.kb - a.kb)
+
+  const counterBoot = files.find(f => f.startsWith('counter.boot-'))
+  const staticBoot  = files.find(f => f.startsWith('home.boot-'))
+
+  const runtimeKb    = runtimes[0]?.kb ?? null
+  const pageBootKb   = counterBoot ? brotliKb(path.join(DIST, counterBoot)) : null
+  const staticBootKb = staticBoot  ? brotliKb(path.join(DIST, staticBoot))  : null
+
+  return { runtimeKb, pageBootKb, staticBootKb }
+}
+
+const bundles = measureBundles()
+
+function fmt(kb, fallback) {
+  return (kb != null) ? kb.toFixed(kb < 1 ? 2 : 1) : fallback
+}
+
+const runtimeKb  = fmt(bundles?.runtimeKb,  '3.1')
+const firstVisit = bundles?.runtimeKb && bundles?.pageBootKb
+  ? (bundles.runtimeKb + bundles.pageBootKb).toFixed(1)
+  : '3.5'
+const pageNavKb  = fmt(bundles?.pageBootKb,  '0.35')
+
+export const metrics = {
+  generatedAt: new Date().toLocaleString('en-GB', { dateStyle: 'medium', timeStyle: 'short' }),
+
+  lighthouse: [
+    { value: '100', label: 'Accessibility' },
+    { value: '100', label: 'Best Practices' },
+    { value: '100',  label: 'SEO' },
+  ],
+
+  bundles: [
+    { value: '0 kB',              label: 'Static page — no JS shipped' },
+    { value: `${firstVisit} kB`,  label: 'Single page app — runtime + page (brotli)' },
+    { value: `${runtimeKb} kB`,   label: 'Multi-page — shared runtime, cached (brotli)' },
+    { value: `${pageNavKb} kB`,   label: 'Multi-page — per-page JS bundle (brotli)' },
+  ],
+
+  vitals: [
+    { id: 'cls', value: '0.00', label: 'Cumulative Layout Shift' },
+  ],
+
+  architecture: [
+    { value: '0', label: 'Runtime dependencies' },
+    { value: 'None', label: 'Production build step' },
+    { value: 'Brotli', label: 'Automatic compression' },
+  ],
+}