@invisibleloop/pulse 0.15.1 → 0.16.0

package/.claude/commands/verify.md

@@ -48,45 +48,63 @@ The browser should still be on `http://localhost:3001/` from step 6. Run `mcp__c
 
 After both Lighthouse runs pass, call `pulse_restart_server` to return to the dev server.
 
-### 8. Performance
+### 8. Mobile layout check
+
+Emulate a mobile viewport and take a screenshot to catch wrapping, overflow, and layout issues before they become Lighthouse failures.
+
+```
+mcp__chrome-devtools__emulate  viewport: "390x844x2,mobile,touch"
+mcp__chrome-devtools__navigate_page  url: "http://localhost:3000/"
+mcp__chrome-devtools__take_screenshot
+```
+
+Describe what you see. Look specifically for:
+- Text or buttons overflowing the viewport
+- Content too small to read or tap
+- Navigation that overlaps content
+- Images that break the layout
+
+Fix any issues, then reset to desktop before continuing:
+
+```
+mcp__chrome-devtools__emulate  viewport: "1440x900x1"
+```
+
+### 9. Performance
 
 Navigate to the page route, then run `mcp__chrome-devtools__performance_start_trace` with `reload: true` and `autoStop: true`. Report LCP and CLS. Flag any LCP insight that suggests a fixable problem (render-blocking resources, large image load delay, etc.).
 
-### 9. Console errors
+### 10. Console errors
 
 Use `mcp__chrome-devtools__list_console_messages` — report any errors or unexpected warnings.
 
-### 10. Code review
+### 11. Code review
 
 Call `pulse_review` with the spec file path. This runs a full code review AND atomically writes the `.pulse-verified` stamp server-side, eliminating any race condition with the stop hook.
 
 Work through every item the review returns. Fix anything that fails before proceeding.
 
-### 11. Close extra browser tabs
+### 12. Close extra browser tabs
 
 Use `mcp__chrome-devtools__list_pages` to get all open pages. Close every page **except the last one** — `close_page` refuses to close the final tab. `pageId` must be a number, not a string.
 
 If there is only one page open, skip this step — there is nothing to close.
 
-### 12. Write verification stamp
-
-`pulse_review` writes the stamp automatically. As a belt-and-suspenders backup, also run:
+### 13. Write verification stamp
 
-```bash
-date +%s > .pulse-verified
-```
+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.
 
-This ensures the stamp is present even if `pulse_review` was not called with a file path.
+**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`.
 
-### 13. Report
+### 14. Report
 
 Summarise:
 - Validation: pass or fail (with errors if any)
-- Visual: what was visible in the screenshot
-- Lighthouse desktop: scores for all four categories
-- Lighthouse mobile: scores for all four categories
+- Visual: desktop screenshot and mobile layout check — any issues found and fixed
+- Lighthouse desktop: scores for Accessibility, Best Practices, SEO
+- Lighthouse mobile: scores for Accessibility, Best Practices, SEO
 - Performance: LCP and CLS values, any flagged insights
 - Console: any errors
 - Review: pass or issues found and fixed
 
-Only confirm the page is good when validation passes, both Lighthouse runs are 100/100/100/100, CLS is 0.00, and there are no console errors. Otherwise, fix and run `/verify` again.
+Only confirm the page is good when validation passes, both Lighthouse runs are 100/100/100, CLS is 0.00, and there are no console errors. Otherwise, fix and run `/verify` again.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",
@@ -57,7 +57,7 @@
   "scripts": {
     "dev": "node --watch src/cli/dev.js",
     "build": "node scripts/build.js",
-    "test": "node src/spec/schema.test.js && node src/runtime/runtime.test.js && node src/runtime/navigate.test.js && node src/runtime/morph.test.js && node src/runtime/ssr.test.js && node src/runtime/image.test.js && node src/server/server.test.js && node src/cli/cli.test.js && node src/ui/ui.test.js && node src/testing/testing.test.js && node src/store/store.test.js && node src/md/md.test.js && node scripts/strip-server.test.js",
+    "test": "node src/spec/schema.test.js && node src/runtime/runtime.test.js && node src/runtime/navigate.test.js && node src/runtime/morph.test.js && node src/runtime/ssr.test.js && node src/runtime/image.test.js && node src/server/server.test.js && node src/cli/cli.test.js && node src/ui/ui.test.js && node src/testing/testing.test.js && node src/store/store.test.js && node src/md/md.test.js && node scripts/strip-server.test.js && node src/mcp/mcp.test.js",
     "typecheck": "tsc --noEmit",
     "docs": "node --watch src/cli/dev.js --root docs --port 4000",
     "docs:start": "node docs/server.js"

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.15.1
+0.16.0

package/src/agent/guide-routing.md

@@ -1,3 +1,94 @@
+## Multi-page sites — the right patterns
+
+### Shared layout component
+
+When a project has more than one page, **never repeat the nav and footer in every spec**. Extract them into a shared component:
+
+```js
+// src/components/layout.js
+import { nav, footer, button } from '@invisibleloop/pulse/ui'
+
+export const NAV_LINKS = [
+  { label: 'Home',    href: '/' },
+  { label: 'About',  href: '/about' },
+  { label: 'Blog',   href: '/blog' },
+]
+
+export const layout = ({ content, activePath = '' }) => `
+  ${nav({
+    logo: 'My Site',
+    logoHref: '/',
+    links: NAV_LINKS.map(l => ({
+      ...l,
+      attrs: activePath === l.href ? 'aria-current="page"' : '',
+    })),
+    action: button({ label: 'Sign up', href: '/signup', variant: 'primary', size: 'sm' }),
+  })}
+  <main id="main-content">
+    ${content}
+  </main>
+  ${footer({
+    logo: 'My Site',
+    links: NAV_LINKS,
+    legal: '© 2026 My Site',
+  })}
+`
+```
+
+Each page spec uses it:
+```js
+import { layout } from '../components/layout.js'
+
+export default {
+  route: '/about',
+  view: () => layout({
+    activePath: '/about',
+    content: `<h1>About us</h1>`,
+  }),
+}
+```
+
+**Rules:**
+- Add new nav links in `src/components/layout.js` only — never hardcode nav links in individual page specs.
+- Pass `activePath` so the active nav item gets `aria-current="page"` — this is required for Lighthouse accessibility.
+- The `layout()` component must include `<main id="main-content">` — do not add it again inside `content`.
+
+### Skip link
+
+Add a skip link before the nav for keyboard users. It must be the first focusable element on every page:
+
+```js
+// src/components/layout.js
+export const SKIP_LINK = `<a href="#main-content" class="skip-link">Skip to main content</a>`
+
+// public/app.css
+.skip-link {
+  position: absolute;
+  left: -9999px;
+  top: var(--ui-space-2);
+  z-index: 9999;
+  padding: var(--ui-space-2) var(--ui-space-4);
+  background: var(--ui-accent);
+  color: var(--ui-bg);
+  font-weight: 600;
+}
+.skip-link:focus { left: var(--ui-space-2); }
+```
+
+Include it at the top of every layout: `${SKIP_LINK}${nav({...})}`.
+
+### Active nav state
+
+The active page link must have `aria-current="page"`. Without it Lighthouse accessibility fails.
+
+The pattern above uses `attrs` — alternatively, use CSS with `:not` and a body class, or check `ctx` in the server fetcher and pass a flag to the view. Any approach is fine; the output must be `aria-current="page"` on the matching link.
+
+### Shared state across pages
+
+Use the global store (`pulse.store.js`) for state that needs to be consistent across pages — user session, cart count, theme preference. Do not duplicate server fetchers across specs for the same data.
+
+See `pulse://guide/server` for the full store API.
+
 ## Site navigation
 
 Projects define navigation in src/components/layout.js via a NAV_LINKS array.

package/src/mcp/mcp.test.js

@@ -0,0 +1,108 @@
+/**
+ * MCP integrity tests — run with: node src/mcp/mcp.test.js
+ *
+ * Guards against guide file drift: every guide-*.md file under src/agent/
+ * must be registered as a named MCP resource in server.js, and every
+ * readFileSync call in server.js that references a guide-*.md must point
+ * to a file that actually exists.
+ */
+
+import fs   from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const ROOT      = path.resolve(__dirname, '../..')
+
+let passed = 0
+let failed = 0
+
+function test(label, fn) {
+  try {
+    fn()
+    console.log(`  ✓ ${label}`)
+    passed++
+  } catch (e) {
+    console.log(`  ✗ ${label}`)
+    console.log(`    ${e.message}`)
+    failed++
+  }
+}
+
+function assert(condition, msg) {
+  if (!condition) throw new Error(msg || 'Assertion failed')
+}
+
+// ── Read source files ────────────────────────────────────────────────────────
+
+const serverSrc = fs.readFileSync(path.join(__dirname, 'server.js'), 'utf8')
+const agentDir  = path.join(ROOT, 'src/agent')
+
+// All guide-*.md files that exist on disk
+const guideFiles = fs.readdirSync(agentDir)
+  .filter(f => f.startsWith('guide-') && f.endsWith('.md'))
+  .sort()
+
+// All guide-*.md files referenced via readFileSync in server.js
+// Pattern: new URL('../agent/guide-*.md', import.meta.url)
+const referencedFiles = [...serverSrc.matchAll(/new URL\(['"`][^'"`]*?(guide-[^'"`/]+\.md)['"`]/g)]
+  .map(m => m[1])
+
+// All guide-*.md filenames registered as MCP resource URIs
+const registeredUris = [...serverSrc.matchAll(/uri:\s*['"`](pulse:\/\/guide\/[^'"`]+)['"`]/g)]
+  .map(m => m[1])
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+console.log('\nGuide file coverage\n')
+
+test('guide-routing.md exists on disk', () => {
+  assert(fs.existsSync(path.join(agentDir, 'guide-routing.md')), 'guide-routing.md not found')
+})
+
+test('guide-components.md exists on disk', () => {
+  assert(fs.existsSync(path.join(agentDir, 'guide-components.md')), 'guide-components.md not found')
+})
+
+for (const file of guideFiles) {
+  test(`${file} is referenced by readFileSync in server.js`, () => {
+    assert(
+      referencedFiles.includes(file),
+      `${file} exists in src/agent/ but is not loaded by server.js via readFileSync. ` +
+      `Either register it as a guide resource or delete it.`
+    )
+  })
+}
+
+for (const file of referencedFiles) {
+  test(`${file} (referenced in server.js) exists on disk`, () => {
+    assert(
+      fs.existsSync(path.join(agentDir, file)),
+      `server.js references ${file} via readFileSync but the file does not exist in src/agent/`
+    )
+  })
+}
+
+test('every guide-*.md on disk has a corresponding pulse://guide/* MCP resource', () => {
+  // Map file names to expected URI slugs: guide-design-references.md → pulse://guide/design-references
+  const fileToUri = (f) => 'pulse://guide/' + f.replace(/^guide-/, '').replace(/\.md$/, '')
+  const missing = guideFiles.filter(f => !registeredUris.includes(fileToUri(f)))
+  assert(
+    missing.length === 0,
+    `These guide files have no registered MCP resource URI:\n    ${missing.join('\n    ')}\n` +
+    `Add them to GUIDE_RESOURCES in server.js or delete them.`
+  )
+})
+
+test('no orphaned guide.md (monolithic legacy file should not exist)', () => {
+  assert(
+    !fs.existsSync(path.join(agentDir, 'guide.md')),
+    'guide.md exists in src/agent/ — this is the old monolithic guide and should be deleted. ' +
+    'Content should live in the split guide-*.md files.'
+  )
+})
+
+// ── Result ───────────────────────────────────────────────────────────────────
+
+console.log(`\n${passed} passed, ${failed} failed\n`)
+if (failed > 0) process.exit(1)

package/src/mcp/server.js

@@ -1057,12 +1057,33 @@ ${(() => {
     checks.push('✓ No obvious hex colours in view')
   }
   
+  // XSS test coverage — check whether the test file includes a <script>alert assertion
+  // for each user-controlled string interpolated into the view.
+  // Heuristic: if the view interpolates any exported string variable (escape(), or direct
+  // string props), the test file should contain a '<script>' XSS assertion.
+  if (file) {
+    const testFile = file.replace(/\.js$/, '.test.js')
+    let xssNote = ''
+    if (fs.existsSync(testFile)) {
+      const testSrc = fs.readFileSync(testFile, 'utf8')
+      const hasXssAssertion = testSrc.includes('<script>') || testSrc.includes('xss') || testSrc.includes('script>alert')
+      if (!hasXssAssertion) {
+        xssNote = '⚠ **No XSS test found** — test file exists but has no `<script>alert` assertion. Add at least one test that passes a `\'<script>alert(1)</script>\'` string as a user-controlled input and asserts it does not appear unescaped in the output.'
+      } else {
+        xssNote = '✓ XSS test assertion present'
+      }
+    } else {
+      xssNote = '○ No test file found — create one at ' + path.basename(testFile)
+    }
+    checks.push(xssNote)
+  }
+
   // Creative override detection — check if spec declares component-free mode
   const creativeOverride = /component.free|creative\s+override|raw\s+HTML\s+throughout/i.test(source)
   checks.push(creativeOverride
     ? '⚡ **Creative override declared** — component pattern checks are advisory only. Lighthouse 100/100/100/100 is the pass bar.'
     : '○ No creative override declared — component checks apply')
-  
+
   return checks.join('\n')
 })()}
 

package/src/mcp/validate-worker.js

@@ -156,6 +156,24 @@ try {
     warnings.push('Inline <script> block detected in view — Pulse\'s CSP (script-src with nonces) will block these scripts at runtime. Move JavaScript to a file in public/ and reference it via meta.scripts: [\'/my-script.js\'] in the spec instead.')
   }
 
+  // External image URLs in src attributes — will be blocked by Pulse's default CSP (img-src 'self')
+  // unless the domain is explicitly listed in pulse.config.js under csp['img-src'].
+  // Flag any http/https src that isn't a data URI or relative path.
+  const externalImgSrcs = [...html.matchAll(/\bsrc=["'](https?:\/\/[^"']+)["']/gi)]
+    .map(m => m[1])
+  if (externalImgSrcs.length) {
+    const domains = [...new Set(externalImgSrcs.map(u => {
+      try { return new URL(u).origin } catch { return u }
+    }))].slice(0, 3)
+    warnings.push(
+      `External image URL${externalImgSrcs.length > 1 ? 's' : ''} in view (${domains.join(', ')}) — ` +
+      `Pulse's default CSP blocks cross-origin images. ` +
+      `Either download the images to public/ and use a relative path (/images/foo.jpg), ` +
+      `or allow the domain in pulse.config.js:\n` +
+      `  export default { csp: { 'img-src': ['${domains[0]}'] } }`
+    )
+  }
+
   // Hardcoded hex colours in view HTML — must use var(--ui-*) tokens instead.
   // Matches: style="...color:#hex..." or style="...background:#hex..."
   // Allows: href="#section-id" (anchor links are not colours)