@invisibleloop/pulse 0.15.0 → 0.16.0

package/.claude/commands/verify.md

@@ -32,55 +32,79 @@ Use `mcp__chrome-devtools__navigate_page` to load the page route, then `mcp__chr
 
 ### 6. Lighthouse — desktop
 
-Run `mcp__chrome-devtools__lighthouse_audit` on the route with `{ "strategy": "desktop" }`.
+**Pre-flight (required before every Lighthouse run):**
+1. Call `pulse_build` to produce a production build and start the production server on port 3001.
+2. Call `navigate_page` with `url: "http://localhost:3001/"` so the browser is on the production server.
 
-**Pass bar: Performance, Accessibility, Best Practices, and SEO must all be 100.** Report the actual scores. If any score is below 100, identify the failing audit(s), fix the issue, and restart from step 3.
+Then run `mcp__chrome-devtools__lighthouse_audit` with `{ "device": "desktop" }`.
+
+**Pass bar: Accessibility, Best Practices, and SEO must all be 100.** Performance is measured and reported but is not a hard requirement (it varies with machine load). Report the actual scores. If Accessibility, Best Practices, or SEO is below 100, identify the failing audit(s), fix the issue, and restart from step 3.
 
 ### 7. Lighthouse — mobile
 
-Run `mcp__chrome-devtools__lighthouse_audit` on the same route with `{ "strategy": "mobile" }`.
+The browser should still be on `http://localhost:3001/` from step 6. Run `mcp__chrome-devtools__lighthouse_audit` with `{ "device": "mobile" }`.
+
+**Same pass bar: Accessibility, Best Practices, and SEO must all be 100.** Fix any failures and restart from step 3.
+
+After both Lighthouse runs pass, call `pulse_restart_server` to return to the dev server.
+
+### 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
 
-**Same pass bar: all four categories must be 100.** Report the actual scores. If any score is below 100, fix and restart from step 3.
+Fix any issues, then reset to desktop before continuing:
 
-### 8. Performance
+```
+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.0",
+  "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.0
+0.16.0

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` |

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/agent/skills/verify/SKILL.md

@@ -83,11 +83,9 @@ Run `mcp__chrome-devtools__list_pages`, then `mcp__chrome-devtools__close_page`
 
 ### 12. Write verification stamp
 
-```bash
-date +%s > .pulse-verified
-```
+Call `pulse_stamp`. This writes `.pulse-verified` via the MCP server, which is more reliable than `date +%s > .pulse-verified` — the MCP write always lands after all spec edits, avoiding the mtime race that causes the stop hook to block immediately after verification.
 
-**This must be the last write before stopping.** Do not edit any spec file after writing the stamp.
+**This must be the last operation before stopping.** Do not edit any spec file after calling `pulse_stamp`.
 
 ### 13. Report
 

package/src/agent/workflow.md

@@ -298,7 +298,9 @@ Run the tests. Fix every failure.
 
 Only invoke `pulse_review` after phases 4–6 all pass. It checks the code for correctness, security, accessibility, DRY violations, and checklist adherence.
 
-> Note: `/verify` includes the review step — if you ran `/verify` and it passed, the Review Agent has already run.
+**Ordering:** `pulse_review` runs **after** Lighthouse, not before. Lighthouse catches contrast failures, missing landmarks, and Best Practices issues that `pulse_review` cannot detect statically. Fixing a Lighthouse failure may require spec edits — so the code review always comes last, against the final version of the code.
+
+> Note: `/verify` includes the review step in the correct position — Lighthouse first (steps 6–7), then `pulse_review` (step 10). If you ran `/verify` and it passed, `pulse_review` has already run against the Lighthouse-passing version of the code.
 
 ---
 

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

@@ -18,6 +18,7 @@
  *   pulse_create_page    — create a new page spec with proper template
  *   pulse_create_component — create a reusable component
  *   pulse_validate       — validate a spec against the schema
+ *   pulse_stamp          — write the .pulse-verified stamp (call as last step of /verify)
  *   pulse_check_version  — installed vs static vs npm latest
  *   pulse_update         — re-copy pulse-ui assets from package → public/
  */
@@ -1042,22 +1043,47 @@ ${(() => {
   }
   
   // Check spec source
-  // Hex colours in view — exclude anchor hrefs (#id), CSS selector strings, and comments
-  // Only flag actual colour values: # followed by exactly 3 or 6 hex chars with no trailing word chars
+  // Hex colours in view — strip anchor hrefs and id attributes before checking so
+  // href="#fixtures" / id="main-content" / href="#join" are never flagged as hex colours.
+  // Only flag actual colour values: # followed by exactly 3 or 6 hex chars.
   const viewBlock = source.slice(source.indexOf('view:'))
-  const hexInView = /(?<!href=["']?)#[0-9a-fA-F]{6}\b|(?<!href=["']?)#[0-9a-fA-F]{3}\b(?![0-9a-fA-F])/.test(viewBlock)
+  const viewBlockStripped = viewBlock
+    .replace(/href=["']#[^"']*["']/g, 'href="#"')   // href="#anchor" → href="#"
+    .replace(/id=["'][^"']*["']/g, 'id=""')          // id="foo" → id=""
+  const hexInView = /#[0-9a-fA-F]{6}\b|#[0-9a-fA-F]{3}\b(?![0-9a-fA-F])/.test(viewBlockStripped)
   if (hexInView) {
-    checks.push('⚠ **Possible hex colour in view** — use var(--ui-*) tokens only (verify: may be an anchor #id href)')
+    checks.push('⚠ **Possible hex colour in view** — use var(--ui-*) tokens only')
   } else {
     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')
 })()}
 
@@ -1141,12 +1167,39 @@ Fix every issue you find. Then confirm what was changed.
 
 **After confirming fixes: you are back in builder mode. Continue to the verification workflow — navigate to the page in the browser, take a screenshot, run Lighthouse desktop audit, run Lighthouse mobile audit. Do not stop at the review.**`)
 
-    // Write the .pulse-verified stamp from the MCP side so the stop hook
-    // is never blocked by a sub-second mtime race from a Bash touch command.
-    // This is a best-effort write — if it fails, the agent can still Bash-stamp.
+  }
+)
+
+// ---------------------------------------------------------------------------
+// pulse_stamp — write the .pulse-verified stamp
+// ---------------------------------------------------------------------------
+// Called as the final step of /verify, after all Lighthouse gates pass and
+// pulse_review is complete. Using the MCP tool avoids the mtime race that can
+// occur when `date +%s > .pulse-verified` runs in the same second as the last
+// spec write, making the stamp appear older than the spec.
+//
+// The stop hook compares spec mtimeMs against stamp mtimeMs — not the content.
+// Writing via MCP ensures the stamp is always written after all spec edits.
+
+server.registerTool(
+  'pulse_stamp',
+  {
+    description: `Write the .pulse-verified stamp to clear the stop-hook verification gate.
+
+Call this as the **last step** of /verify — after Lighthouse desktop + mobile both pass 100/100/100, pulse_review is complete, and no further spec edits will be made.
+
+The stop hook compares each changed spec's mtime against this stamp. Any spec newer than the stamp blocks the session. Do NOT call this before Lighthouse or before fixing issues found in pulse_review.`,
+    inputSchema: {},
+  },
+  () => {
+    const stampPath = path.join(ROOT, '.pulse-verified')
+    const ts = String(Math.floor(Date.now() / 1000))
     try {
-      fs.writeFileSync(path.join(ROOT, '.pulse-verified'), String(Math.floor(Date.now() / 1000)), 'utf8')
-    } catch { /* non-critical */ }
+      fs.writeFileSync(stampPath, ts, 'utf8')
+      return text(`✓ .pulse-verified written (${ts}). Stop hook cleared — session can end.`)
+    } catch (err) {
+      return text(`Error writing .pulse-verified: ${err.message}\nFallback: run \`date +%s > .pulse-verified\` in Bash.`)
+    }
   }
 )
 
@@ -2220,21 +2273,24 @@ The extracted values map directly to pulse_intake fields (palette, vibe, styleNo
   ({ source, focus = 'all' }) => {
     const lines = []
     lines.push(`# Inspiration Extraction — ${source}\n`)
-    lines.push('Use this template to systematically observe and capture design decisions from the inspiration source.')
-    lines.push('Fill in every section you can observe. Leave a field blank if it cannot be determined.\n')
+    lines.push('**You must fill in this template now** — do not return it blank to the user.')
+    lines.push('Use your browsing tool (for URLs) or vision capability (for images) to observe the source and populate every field you can determine.')
+    lines.push('Leave a cell blank only if it is genuinely unobservable. When done, call `pulse_intake` with the extracted values.\n')
     lines.push('---\n')
 
     const isUrl = /^https?:\/\//.test(source) || /\.(com|io|co|app|design|net|org|dev)\b/.test(source)
 
     if (isUrl) {
-      lines.push('## Step 1 — Visit the site')
+      lines.push('## Step 1 — Visit the site (do this now)')
       lines.push(`Navigate to: **${source}**`)
       lines.push('Observe the rendered page at desktop width (~1440px) and again at mobile (~375px).')
-      lines.push('Take note of the above-the-fold area, then scroll through the full page.\n')
+      lines.push('Take note of the above-the-fold area, then scroll through the full page.')
+      lines.push('**Fill in the sections below based on what you observe. Return a completed extraction, not an empty template.**\n')
     } else {
-      lines.push('## Step 1 — Analyse the source')
+      lines.push('## Step 1 — Analyse the source (do this now)')
       lines.push(`Source: **${source}**`)
-      lines.push('Use your vision capability or knowledge of this reference to fill in the template below.\n')
+      lines.push('Use your vision capability or knowledge of this reference to fill in the template below.')
+      lines.push('**Return a completed extraction with your observations filled in — not a blank template.**\n')
     }
 
     lines.push('---\n')
@@ -2322,7 +2378,9 @@ The extracted values map directly to pulse_intake fields (palette, vibe, styleNo
     lines.push('})')
     lines.push('```')
     lines.push('')
-    lines.push('Then call `pulse_sketch` — pass the layout direction observed above as context in your `brief`.')
+    lines.push('**Now fill in the template above with your observations, then call `pulse_sketch` — pass the layout direction observed above as context in your `brief`.**')
+    lines.push('')
+    lines.push('> Do not return this template blank. The user is waiting for a completed extraction.')
 
     return text(lines.join('\n'))
   }
@@ -2989,15 +3047,21 @@ Run this immediately after writing a theme file — before production build and
     }
 
     // Standard pairings to check — [foreground token, background token, label, isLargeText]
+    // isLargeText=true → WCAG AA large text threshold (3:1); isLargeText=false → body text (4.5:1)
+    // Muted text is checked at both thresholds: body text pairings always need 4.5:1.
+    // When a muted pairing fails 4.5:1 but passes 3:1, the warning distinguishes the two
+    // so designers know it can be used for captions/eyebrows (large) but not body copy (small).
     const PAIRINGS = [
-      ['--ui-text',         '--ui-bg',       'Body text on page background',        false],
-      ['--ui-muted',        '--ui-bg',       'Muted text on page background',        false],
-      ['--ui-accent',       '--ui-bg',       'Accent text on page background',       false],
-      ['--ui-text',         '--ui-surface',  'Body text on card/surface',            false],
-      ['--ui-muted',        '--ui-surface',  'Muted text on card/surface',           false],
-      ['--ui-accent-text',  '--ui-accent',   'Button text on accent background',     false],
-      ['--ui-accent',       '--ui-surface',  'Accent text on surface',               false],
-      ['--ui-text',         '--ui-surface-2','Text on nested surface',               false],
+      ['--ui-text',         '--ui-bg',       'Body text on page background',                                false],
+      ['--ui-muted',        '--ui-bg',       'Muted/secondary text on page background (body size)',        false],
+      ['--ui-muted',        '--ui-bg',       'Muted text on page background (large text / captions)',      true],
+      ['--ui-accent',       '--ui-bg',       'Accent text on page background',                             false],
+      ['--ui-text',         '--ui-surface',  'Body text on card/surface',                                  false],
+      ['--ui-muted',        '--ui-surface',  'Muted text on card/surface (body size)',                     false],
+      ['--ui-muted',        '--ui-surface',  'Muted text on card/surface (large text / captions)',         true],
+      ['--ui-accent-text',  '--ui-accent',   'Button text on accent background',                           false],
+      ['--ui-accent',       '--ui-surface',  'Accent text on surface',                                     false],
+      ['--ui-text',         '--ui-surface-2','Text on nested surface',                                     false],
     ]
 
     const checkSet = (vars, context) => {
@@ -3082,12 +3146,19 @@ Run this immediately after writing a theme file — before production build and
         lines.push(`**${r.label}** — ${r.context}`)
         lines.push(`  ${r.fg}  on  ${r.bg}`)
         lines.push(`  Ratio: ${r.ratio}:1  ·  Needed: ${r.threshold}:1  ·  Level: ${r.level}`)
-        
+
+        // Distinguish between body and large-text failures for --ui-muted
+        if (r.label.includes('large text') || r.label.includes('captions')) {
+          lines.push(`  Context: large text / captions (3:1 threshold) — fails even the relaxed threshold.`)
+        } else if (r.label.includes('body size') || r.threshold === 4.5) {
+          lines.push(`  Context: body text (4.5:1 threshold) — only use this colour for large text (≥18pt / ≥14pt bold) or decorative elements, not for body copy or captions.`)
+        }
+
         // Suggest a corrected hex value
         if (r.fgHex && r.bgLum !== null) {
           const suggested = suggestContrastFix(r.fgHex, r.bgLum, r.threshold)
           if (suggested) {
-            lines.push(`  💡 Suggested fix: use ${suggested} instead of ${r.fgHex}`)
+            lines.push(`  Suggested fix: use ${suggested} instead of ${r.fgHex}`)
           }
         }
         lines.push('')
@@ -3105,8 +3176,9 @@ Run this immediately after writing a theme file — before production build and
     if (failures.length > 0) {
       lines.push('---')
       lines.push('**Fix guidance:**')
+      lines.push('• **WCAG AA thresholds:** 4.5:1 for body text (≤18pt regular / ≤14pt bold); 3:1 for large text (≥18pt / ≥14pt bold), UI components, and decorative elements.')
       lines.push('• Mid-tone accents on near-white backgrounds often fail 4.5:1. Darken the accent token or use it only for large text/icons (3:1 threshold).')
-      lines.push('• For `--ui-muted` failures: muted text on `--ui-bg` needs at minimum a 4.5:1 ratio. Adjust the muted tone.')
+      lines.push('• For `--ui-muted` "body size" failures: muted text on `--ui-bg` needs 4.5:1 for body copy. If you only use this colour for eyebrows, captions, or large labels (≥18pt), the 3:1 "large text" row is the relevant gate — check whether that row passes.')
       lines.push('• Light-theme `--ui-accent` must be distinctly darker than the page background — many default accent hues are too light.')
       lines.push('• After fixing, run this tool again before `pulse_build`.')
     }
@@ -3410,6 +3482,7 @@ const PULSE_GUIDE_INDEX = `# Pulse Framework Guide
 - \`pulse_create_store\` — register a pulse.store.js you wrote with the Write tool. Write the file first, then call this.
 - \`pulse_create_action\` — generate a correctly-structured action snippet.
 - \`pulse_run_tests\` — run the project test suite (npm test). Use after writing or editing specs.
+- \`pulse_stamp\` — write the \`.pulse-verified\` stamp. Call as the **last step** of \`/verify\`, after Lighthouse and \`pulse_review\` both pass. Using this MCP tool avoids the mtime race that \`date +%s > .pulse-verified\` can cause when the stamp and the last spec write land in the same filesystem second.
 - \`pulse_fetch_page(url)\` — HTTP GET the dev server URL. Use to verify SSR output.
 - \`pulse_restart_server\` — stop and restart the dev server.
 - \`pulse_build\` — production build + starts prod server on devPort+1 for Lighthouse. Returns the URL. Call \`pulse_restart_server\` after to return to dev. **Slow — takes 30–60 s. Tell the user before calling.**

package/src/mcp/validate-worker.js

@@ -150,6 +150,30 @@ try {
     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.')
   }
 
+  // Inline <script> blocks in view — blocked by Pulse CSP nonce policy
+  // meta.scripts is the correct way to add JS: it receives the server nonce automatically.
+  if (/<script[\s>]/i.test(html)) {
+    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)