@invisibleloop/pulse 0.14.2 → 0.15.1

package/docs/src/pages/how-it-works.js

@@ -87,13 +87,20 @@ export default {
       <p>Together these replace the need to paste documentation into a system prompt or rely on the agent's training data to know how Pulse works.</p>
 
       ${section('resources', 'Resources: what the agent knows')}
-      <p>The MCP server exposes two resources the agent reads before doing any work:</p>
-      <ul>
-        <li><strong><code>pulse://guide</code></strong> — the complete framework reference, split into focused sections so each fits comfortably in a single read. The agent fetches whichever sections are relevant to the task at hand.</li>
-        <li><strong><code>pulse://persona</code></strong> — the quality bar the agent holds itself to: always write correct SSR, always handle errors, never skip empty states, never hardcode colours, never use <code>data-event</code> on text inputs. The persona defines what "done" means.</li>
-      </ul>
+      <p>The MCP server exposes read-only documents the agent fetches at any time. There are two top-level resources and a set of focused guide sections:</p>
+
+      <dl class="definition-list">
+        <dt><code>pulse://quickstart</code></dt>
+        <dd>Workflow phases, spec skeleton, component rules, and theming essentials combined into a single fetch. Used for targeted edits, bug fixes, or simple one-shot page builds — avoids loading the full guide for small tasks.</dd>
+
+        <dt><code>pulse://workflow</code></dt>
+        <dd>The full build workflow — every phase, pass gate, and ordering rule. The agent reads this before starting any new page or project.</dd>
+
+        <dt><code>pulse://persona</code></dt>
+        <dd>The quality bar the agent holds itself to: always write correct SSR, always handle errors, never skip empty states, never hardcode colours, never use <code>data-event</code> on text inputs. The persona defines what "done" means.</dd>
+      </dl>
 
-      <p>The guide sections are:</p>
+      <p>The guide is split into topic sections the agent fetches as needed:</p>
       <dl class="definition-list">
         <dt><code>pulse://guide/spec</code></dt>
         <dd>Spec format — state, mutations, actions, streaming SSR, validation, key rules, and form layout.</dd>
@@ -112,12 +119,51 @@ export default {
 
         <dt><code>pulse://guide/examples</code></dt>
         <dd>Complete working page examples covering common patterns.</dd>
+
+        <dt><code>pulse://guide/templates</code></dt>
+        <dd>Pre-built landing page templates, adaptation rules, and theme CSS patterns. Fetched when building a new branded site or landing page.</dd>
+
+        <dt><code>pulse://guide/design-references</code></dt>
+        <dd>Twelve design directions with vibes, component combinations, palette patterns, and signature moves. Fetched during intake to pick the right aesthetic rather than defaulting to a generic SaaS look.</dd>
+
+        <dt><code>pulse://guide/design-gallery</code></dt>
+        <dd>All templates with visual descriptions and key components. Includes critical prop-name references and component recipes for cards, stat strips, and forms. Fetched when adapting a template or combining components.</dd>
+
+        <dt><code>pulse://guide/explore</code></dt>
+        <dd>Zone-based layout thinking, seven structural gestures, raw HTML patterns without components, and an anti-pattern checklist. Fetched when a distinctive or unusual layout is needed.</dd>
       </dl>
 
       ${callout('note', 'The guide is authoritative. When there is a question about how something should be structured — where state lives, how validation is wired, how streaming works — the guide answers it. The agent does not guess.')}
 
       ${section('tools', 'Tools: what the agent can do')}
-      <p>The MCP server provides tools across four categories:</p>
+      <p>The MCP server provides tools across five categories:</p>
+
+      <h3 class="doc-h3">Design &amp; intake</h3>
+      <dl class="definition-list">
+        <dt><code>pulse_extract_inspiration</code></dt>
+        <dd>Extracts a structured design brief from a URL or image shared as inspiration. Called before <code>pulse_intake</code> when the user says "I like the look of X" — it tells the agent exactly what to observe and capture.</dd>
+
+        <dt><code>pulse_intake</code></dt>
+        <dd>Captures the product name, pitch, features, palette, vibe, and anti-style before scaffolding any new page or branded template. Returns a structured brief with copy-ready content, early contrast warnings, and component suggestions. Always runs before <code>pulse_sketch</code>.</dd>
+
+        <dt><code>pulse_sketch</code></dt>
+        <dd>Generates three structurally distinct layout directions (full-bleed, asymmetric split, editorial flow, etc.) before any code is written. Called after <code>pulse_intake</code> — prevents every project from defaulting to the same centred-hero layout.</dd>
+
+        <dt><code>pulse_intent</code></dt>
+        <dd>Intent engine — describe what you want to build and get back a matched archetype, recommended components, a ready-to-adapt spec scaffold, and which guide sections to read first. An alternative entry point to <code>pulse://workflow</code> for targeted tasks.</dd>
+
+        <dt><code>pulse_design_review</code></dt>
+        <dd>Reviews the built page's visual design against the original product brief from <code>pulse_intake</code>. Checks whether the design looks and feels appropriate for the product, audience, and vibe. Runs after screenshot, before Lighthouse.</dd>
+
+        <dt><code>pulse_layout_review</code></dt>
+        <dd>Multi-viewport layout review — checks for overflow, collapsed sections, and broken images at different screen widths. Runs after design approval but before Lighthouse, catching layout issues that Lighthouse doesn't flag.</dd>
+
+        <dt><code>pulse_tokens</code></dt>
+        <dd>Lists all available <code>--ui-*</code> CSS custom property tokens from the installed <code>pulse-ui.css</code>. Used before writing theme overrides to avoid guessing token names.</dd>
+
+        <dt><code>pulse_check_contrast</code></dt>
+        <dd>Static WCAG contrast checker. Extracts colour variable definitions from a theme file and checks common foreground/background pairings for WCAG AA compliance. Run immediately after writing a theme file to catch palette mistakes before Lighthouse.</dd>
+      </dl>
 
       <h3 class="doc-h3">Scaffolding</h3>
       <dl class="definition-list">
@@ -136,11 +182,17 @@ export default {
 
       <h3 class="doc-h3">Inspection</h3>
       <dl class="definition-list">
+        <dt><code>pulse_status</code></dt>
+        <dd>Project health snapshot — pages, routes, server status, last build. Called at the start of a session to orient quickly without reading files individually.</dd>
+
         <dt><code>pulse_list_structure</code></dt>
         <dd>Lists every page, component, and store that already exists in the project. The agent calls this before creating anything — to avoid duplication and to understand what the codebase already provides.</dd>
 
         <dt><code>pulse_fetch_page</code></dt>
         <dd>Reads the full source of an existing spec file. Used when the agent needs to understand an existing page before editing it, or when a review of the current state is needed.</dd>
+
+        <dt><code>pulse_list_icons</code></dt>
+        <dd>Lists all available Pulse UI icon names, grouped by category. Called before importing icons — the agent never guesses a name.</dd>
       </dl>
 
       <h3 class="doc-h3">Validation &amp; review</h3>
@@ -148,26 +200,29 @@ export default {
         <dt><code>pulse_validate</code></dt>
         <dd>Validates a spec against the Pulse schema. Returns errors (which block progress) and warnings (which must also be resolved). The agent calls this after writing or editing every spec file.</dd>
 
+        <dt><code>pulse_suggest</code></dt>
+        <dd>Draft-mode feedback — paste a partial or complete spec and get constructive suggestions before running the hard validator. Unlike <code>pulse_validate</code>, it is collaborative rather than a gate: it notices patterns, spots likely omissions, and offers ideas. Used mid-build for a second opinion.</dd>
+
         <dt><code>pulse_review</code></dt>
         <dd>Switches the agent into reviewer mode. Returns the spec source, the rendered HTML output, and a structured checklist covering accessibility, empty states, error handling, component usage, security, and correctness. The agent reads its own output critically and fixes every issue before continuing.</dd>
+
+        <dt><code>pulse_run_tests</code></dt>
+        <dd>Runs the project test suite (<code>npm test</code>) and returns the full output. Called after writing or editing specs to verify nothing is broken.</dd>
       </dl>
 
-      <h3 class="doc-h3">Server</h3>
+      <h3 class="doc-h3">Server &amp; maintenance</h3>
       <dl class="definition-list">
         <dt><code>pulse_restart_server</code></dt>
         <dd>Restarts the Pulse dev server. Called after structural changes — adding a new page, modifying the server entry — to reload all specs and re-register routes.</dd>
 
         <dt><code>pulse_build</code></dt>
         <dd>Builds the project for production. Bundles specs, hashes assets, and writes the manifest. Called when the agent needs to verify the production build or prepare a release.</dd>
-      </dl>
 
-      <h3 class="doc-h3">Maintenance</h3>
-      <dl class="definition-list">
         <dt><code>pulse_check_version</code></dt>
         <dd>Reports the installed Pulse version and whether an update is available.</dd>
 
         <dt><code>pulse_update</code></dt>
-        <dd>Updates the Pulse package to the latest version.</dd>
+        <dd>Updates the Pulse package to the latest version and copies the latest UI assets and agent files into the project.</dd>
       </dl>
 
       ${section('flow', 'What happens when you ask for something')}

package/package.json

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

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.14.2
+0.15.1

package/scripts/build.js

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

package/src/agent/commands/verify.md

@@ -54,13 +54,9 @@ Use `mcp__chrome-devtools__list_pages` to get all open pages, then call `mcp__ch
 
 ### 11. Write verification stamp
 
-Run:
+Call `pulse_stamp`. This writes `.pulse-verified` via the MCP server, which is more reliable than the `date +%s` shell command — the MCP write always lands after all spec edits, avoiding the mtime race condition that can cause the stop hook to block immediately after verification.
 
-```bash
-date +%s > .pulse-verified
-```
-
-**This must be the last write operation before stopping.** The stop hook compares each edited spec's modification time against this stamp — if any spec is newer than the stamp, the hook blocks. Do not edit any spec file after writing the stamp.
+**This must be the last operation before stopping.** The stop hook compares each edited spec's mtime against this stamp — if any spec is newer than the stamp, the hook blocks. Do not edit any spec file after calling `pulse_stamp`.
 
 ### 12. Report
 

package/src/agent/guide-components.md

@@ -172,7 +172,7 @@ To add a missing icon: copy a Lucide path (MIT) into `src/ui/icons.js` using `s(
 | `stat` | `label`, `value`, `change`, `trend` (up/down/neutral), `size` (sm/md/lg — lg for hero KPIs), `center` |
 | `avatar` | `src`, `alt`, `size` (sm/md/lg/xl), `initials` |
 | `empty` | `title`, `description`, `action` ({label,href,variant}) |
-| `table` | `headers`, `rows` (2D array of HTML strings), `caption` |
+| `table` | `headers`, `rows` (2D array of HTML strings), `caption` | ⚠ Each cell item must be **raw HTML content** — `table()` wraps each item in `<td>` itself. Do NOT pass `<td>...</td>` strings or you will get double-nested cells. |
 | `spinner` | `size` (sm/md/lg), `color` (accent/muted/white), `label` |
 | `progress` | `value`, `max` (100), `label`, `showLabel`, `showValue`, `variant`, `size` |
 | `breadcrumbs` | `items` ([{label,href}] — last item has no href), `separator` |