@invisibleloop/pulse 0.14.2 → 0.15.1

package/src/agent/guide-examples.md

@@ -1,54 +1,332 @@
-## Example page — contact form
+## Pattern: action with validation and field errors
 
-```js
-import { nav, section, input, textarea, button, alert, container } from '@invisibleloop/pulse/ui'
-import { layout } from '../components/layout.js'
+The correct wiring for a form action with per-field validation errors. `onStart` captures `FormData` before `validate` runs (uncontrolled inputs — never use `data-event` to mirror input values). `validate: true` runs the spec's `validation` rules before `run`. Field errors are surfaced via `state.errors`.
 
+```js
 export default {
-  meta: {
-    title:  'Contact',
-    styles: ['/app.css', '/pulse-ui.css'],
-  },
+  route: '/signup',
+  meta: { title: 'Sign up', styles: ['/pulse-ui.css', '/app.css'] },
   state: {
-    status: 'idle',
+    status: 'idle',   // 'idle' | 'loading' | 'success' | 'error'
     errors: [],
+    fields: { name: '', email: '' },
+  },
+  validation: {
+    'fields.name':  { required: true, minLength: 2 },
+    'fields.email': { required: true, format: 'email' },
   },
   actions: {
-    send: {
+    submit: {
       onStart: (state, formData) => ({
-        status:  'loading',
-        name:    formData.get('name'),
-        email:   formData.get('email'),
-        message: formData.get('message'),
+        status: 'loading',
+        errors: [],
+        fields: { name: formData.get('name') ?? '', email: formData.get('email') ?? '' },
       }),
+      validate: true,
       run: async (state, serverState, formData) => {
-        const res = await fetch('/api/contact', { method: 'POST', body: formData })
-        if (!res.ok) throw new Error(await res.text())
+        const res = await fetch('/api/signup', { method: 'POST', body: formData })
+        if (!res.ok) {
+          let message = `Request failed: ${res.status}`
+          try { const j = await res.json(); message = j.message || j.error || message } catch {}
+          throw new Error(message)
+        }
         return await res.json()
       },
-      onSuccess: (state, result) => ({ status: 'success' }),
-      onError:   (state, err)    => ({
+      onSuccess: (state, result) => ({
+        status: 'success',
+        _toast: { message: 'Account created!', variant: 'success' },
+      }),
+      onError: (state, err) => ({
         status: 'error',
         errors: err?.validation ?? [{ message: err.message }],
+        _toast: { message: 'Please check the form', variant: 'error' },
       }),
     },
   },
-  view: (state) => layout(`
-    ${container({ content: `
-      ${section({ title: 'Contact Us', subtitle: 'We will get back to you within 24 hours.' })}
+  view: (state) => `
+    <main id="main-content">
       ${state.status === 'success'
-        ? alert({ type: 'success', message: 'Message sent!' })
-        : `<form data-action="send" class="u-flex u-flex-col u-gap-4">
-            ${grid({ cols: 2, gap: 'md', content: `
-              ${input({ name: 'name',  label: 'Name',  placeholder: 'Your name',       required: true })}
-              ${input({ name: 'email', label: 'Email', type: 'email', placeholder: 'you@example.com', required: true })}
-            ` })}
-            ${textarea({ name: 'message', label: 'Message', rows: 5, required: true })}
-            ${state.errors.length ? alert({ type: 'error', message: state.errors[0].message }) : ''}
-            ${button({ label: state.status === 'loading' ? 'Sending…' : 'Send', type: 'submit', variant: 'primary', fullWidth: true })}
+        ? `<p>You're signed up.</p>`
+        : `<form data-action="submit" class="u-flex u-flex-col u-gap-4">
+            ${input({ name: 'name',  label: 'Name',  value: state.fields.name,
+              error: state.errors.find(e => e.field === 'fields.name')?.message })}
+            ${input({ name: 'email', label: 'Email', type: 'email', value: state.fields.email,
+              error: state.errors.find(e => e.field === 'fields.email')?.message })}
+            ${button({ label: state.status === 'loading' ? 'Saving…' : 'Sign up',
+              type: 'submit', variant: 'primary',
+              attrs: state.status === 'loading' ? 'aria-busy="true" disabled' : '' })}
           </form>`
       }
-    ` })}
-  `),
+    </main>
+  `,
+}
+```
+
+**Key points:**
+- `onStart` captures `FormData` into state so field values survive the re-render
+- `validate: true` runs before `run()` — validation errors arrive in `onError` as `err.validation`
+- Always check `err?.validation` first; fall back to `err.message`
+- `aria-busy="true"` on the submit button while loading — spinner alone is not sufficient for accessibility
+- `res.ok` checked before parsing; never use `await res.text()` as an error message
+
+---
+
+## Pattern: server data with dynamic route and missing-data fallback
+
+The correct pattern for a dynamic route that loads data from a server fetcher. Always add `onViewError` — a missing or invalid param must not produce a 500.
+
+```js
+import { md }   from '@invisibleloop/pulse/md'
+import { prose } from '@invisibleloop/pulse/ui'
+
+const post = md('content/blog/:slug.md')
+
+export default {
+  route: '/blog/:slug',
+  meta: {
+    title:       async (ctx) => (await post(ctx)).frontmatter.title ?? 'Post not found',
+    description: async (ctx) => (await post(ctx)).frontmatter.description ?? '',
+  },
+  server: { post },
+  view: (state, server) => `
+    <main id="main-content">
+      <h1>${server.post.frontmatter.title}</h1>
+      ${prose({ content: server.post.html })}
+    </main>
+  `,
+  onViewError: (err) => `
+    <main id="main-content">
+      <p>Post not found. <a href="/blog">Back to blog</a></p>
+    </main>
+  `,
+}
+```
+
+**Key points:**
+- Call the same `md()` fetcher in both `meta` and `server` — it caches on `ctx._mdCache`, file is read once
+- `onViewError` is required on any dynamic route where the view can receive null/missing data
+- For database-backed routes: validate `ctx.params.id` before use; return a 404-equivalent via `onViewError` if not found
+- Use `?.` and `??` throughout the view when server data can be null
+
+---
+
+## Pattern: streaming SSR with scoped fetchers
+
+Use streaming when a page has slow data (feeds, lists, analytics) and you want the shell to paint instantly. `scope` prevents slow fetchers from blocking the shell.
+
+```js
+export default {
+  route: '/dashboard',
+  meta: { title: 'Dashboard', styles: ['/pulse-ui.css', '/app.css'] },
+  state: {},
+  server: {
+    user:  async (ctx) => db.users.findByCookie(ctx.cookies.session),  // fast
+    feed:  async () => fetchFeed(),   // slow
+    ads:   async () => fetchAds(),    // slow
+  },
+  stream: {
+    shell:    ['header'],
+    deferred: ['feed'],
+    scope: {
+      header: ['user'],        // shell sends as soon as 'user' resolves
+      feed:   ['feed', 'ads'], // deferred sends when both resolve
+    },
+  },
+  view: {
+    header: (state, server) => `
+      <header>
+        <p>Hello, ${server.user?.name ?? 'Guest'}</p>
+      </header>
+    `,
+    feed: (state, server) => `
+      <ul>
+        ${server.feed.map(item => `<li data-key="${item.id}">${item.title}</li>`).join('')}
+      </ul>
+    `,
+  },
+}
+```
+
+**Key points:**
+- `view` must be a named object of functions — not a single function — when using `stream`
+- `scope` is optional but important: without it the shell waits for all fetchers
+- `data-key` on list items enables O(1) keyed reconciliation when the list updates client-side
+- A fetcher listed in `scope.header` but slow will delay the shell — keep shell fetchers fast
+
+---
+
+## Pattern: global store subscription and `_storeUpdate`
+
+Use the global store for data shared across pages (user session, cart, theme). Read store data via `spec.store`; push changes back with `_storeUpdate` from `onSuccess`.
+
+```js
+// Page that reads from store and updates it on save
+export default {
+  route: '/settings',
+  store: ['user', 'settings'],   // declares which store keys this page subscribes to
+  meta: { title: 'Settings', styles: ['/pulse-ui.css', '/app.css'] },
+  state: { status: 'idle' },
+  actions: {
+    save: {
+      onStart: (state, formData) => ({ status: 'loading' }),
+      run: async (state, serverState, formData) => {
+        const theme = formData.get('theme')
+        const res = await fetch('/api/settings', {
+          method: 'POST',
+          body: JSON.stringify({ theme }),
+          headers: { 'Content-Type': 'application/json' },
+        })
+        if (!res.ok) throw new Error(`Save failed: ${res.status}`)
+        return { theme }
+      },
+      onSuccess: (state, { theme }) => ({
+        status: 'idle',
+        _storeUpdate: { settings: { theme } },  // merged into store; all subscribed pages re-render
+        _toast: { message: 'Saved', variant: 'success' },
+      }),
+      onError: (state, err) => ({
+        status: 'error',
+        _toast: { message: err.message, variant: 'error' },
+      }),
+    },
+  },
+  view: (state, server) => `
+    <main id="main-content">
+      <form data-action="save" class="u-flex u-flex-col u-gap-4">
+        ${select({ name: 'theme', label: 'Theme',
+          options: [{ value: 'dark', label: 'Dark' }, { value: 'light', label: 'Light' }],
+          value: server.settings?.theme ?? 'dark' })}
+        ${button({ label: state.status === 'loading' ? 'Saving…' : 'Save', type: 'submit', variant: 'primary' })}
+      </form>
+    </main>
+  `,
+}
+```
+
+**Key points:**
+- `spec.store` declares subscriptions — store data appears in the view's `server` argument
+- `_storeUpdate` is stripped from page state and merged into the store — do not store it
+- All pages subscribed to the affected store keys re-render without a server round-trip
+- Never use a full page reload to propagate shared state changes — use `_storeUpdate`
+
+---
+
+## Pattern: guard with auth redirect
+
+Use `guard` to protect routes. It runs before server fetchers. Return `{ redirect }` to send unauthenticated users elsewhere.
+
+```js
+export default {
+  route: '/account',
+  meta: { title: 'Account', styles: ['/pulse-ui.css', '/app.css'] },
+  server: {
+    user: async (ctx) => db.users.find(ctx.cookies.session),
+  },
+  guard: async (ctx) => {
+    const user = await db.users.findByCookie(ctx.cookies.session)
+    if (!user) return { redirect: '/login?next=/account' }
+  },
+  state: {},
+  view: (state, server) => `
+    <main id="main-content">
+      <h1>Hello, ${server.user?.name}</h1>
+    </main>
+  `,
+}
+```
+
+**Key points:**
+- `guard` runs before server fetchers — returning `{ redirect }` short-circuits the entire request
+- Return nothing (or `undefined`) to allow the request through
+- For shared auth logic, extract to a helper and call it from `guard` on each protected spec
+- `ctx.cookies` is available in `guard` — check session cookies here, not in the view
+
+---
+
+## Pattern: keyed list with client mutations
+
+Use `data-key` on repeated elements whenever a list can be reordered, filtered, or have items added/removed client-side.
+
+```js
+export default {
+  route: '/todos',
+  meta: { title: 'Todos', styles: ['/pulse-ui.css', '/app.css'] },
+  state: {
+    items: [
+      { id: 1, text: 'Buy milk', done: false },
+      { id: 2, text: 'Write spec', done: false },
+    ],
+    filter: 'all',  // 'all' | 'active' | 'done'
+  },
+  mutations: {
+    toggle: (state, e) => {
+      const id = Number(e.target.closest('[data-id]').dataset.id)
+      return { items: state.items.map(i => i.id === id ? { ...i, done: !i.done } : i) }
+    },
+    setFilter: (state, e) => ({ filter: e.target.value }),
+  },
+  view: (state) => {
+    const visible = state.items.filter(i =>
+      state.filter === 'all' ? true : state.filter === 'done' ? i.done : !i.done
+    )
+    return `
+      <main id="main-content">
+        <ul>
+          ${visible.map(item => `
+            <li data-key="${item.id}" data-id="${item.id}">
+              <button data-event="toggle" aria-pressed="${item.done}">${item.text}</button>
+            </li>
+          `).join('')}
+        </ul>
+        <select data-event="change:setFilter" aria-label="Filter todos">
+          <option value="all">All</option>
+          <option value="active">Active</option>
+          <option value="done">Done</option>
+        </select>
+      </main>
+    `
+  },
+}
+```
+
+**Key points:**
+- `data-key` must be on every sibling element in the container — mixed keyed/unkeyed falls back to position matching
+- Use `e.target.closest('[data-id]')` in mutations — never assume `e.target` is the element with the attribute
+- `aria-pressed` on toggle buttons communicates state to screen readers
+- Mutations are pure — no fetch, no DOM access, return partial state only
+
+---
+
+## Pattern: persist — what belongs and what doesn't
+
+`persist` survives page reload via `localStorage`. Only serialisable, user-owned state that should survive a refresh belongs here.
+
+```js
+export default {
+  route: '/builder',
+  meta: { title: 'Builder', styles: ['/pulse-ui.css', '/app.css'] },
+  state: {
+    // ✓ persist these — user-owned, meaningful across sessions
+    items:      [],
+    activeStep: 0,
+    draft:      { name: '', description: '' },
+
+    // ✗ do NOT persist these — ephemeral UI state
+    status:     'idle',
+    errors:     [],
+    modalOpen:  false,
+  },
+  persist: ['items', 'activeStep', 'draft'],
+  mutations: {
+    nextStep: (state) => ({ activeStep: Math.min(state.activeStep + 1, 3) }),
+    prevStep: (state) => ({ activeStep: Math.max(state.activeStep - 1, 0) }),
+  },
+  view: (state) => `<main id="main-content">…</main>`,
 }
 ```
+
+**Key points:**
+- Never persist `status`, `errors`, loading flags, or modal open state — these are session-only
+- Never persist large objects or arrays that could grow unbounded — `localStorage` has a ~5MB limit
+- Restored persist values override spec defaults on mount and trigger a re-render if different
+- `persist` keys must exist in `state` — persisting a key not in state has no effect

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/cli/dev.js

@@ -140,6 +140,48 @@ process.on('SIGINT',  closeReloadClients)
 let reloadTimer = null
 let lastReload = 0
 
+/**
+ * Check rendered HTML class names against CSS files in public/ and warn about
+ * any classes that are used in templates but not defined in any stylesheet.
+ * Only checks project-owned CSS (not pulse-ui.css) to avoid noise.
+ */
+async function checkUndefinedClasses(specs) {
+  try {
+    // Collect all class names defined in project CSS files
+    const cssDir = path.join(ROOT, 'public')
+    const definedClasses = new Set()
+    if (fs.existsSync(cssDir)) {
+      for (const file of fs.readdirSync(cssDir).filter(f => f.endsWith('.css') && f !== 'pulse-ui.css')) {
+        const css = fs.readFileSync(path.join(cssDir, file), 'utf8')
+        for (const [, cls] of css.matchAll(/\.([a-zA-Z][a-zA-Z0-9_-]*)\s*[{,:\[]/g)) {
+          definedClasses.add(cls)
+        }
+      }
+    }
+    if (definedClasses.size === 0) return
+
+    // Render each spec and collect used class names from the HTML output
+    const { renderToString } = await import('../runtime/ssr.js')
+    for (const spec of specs) {
+      if (!spec.view) continue
+      try {
+        const { html } = await renderToString(spec, {})
+        const usedInSpec = new Set()
+        for (const [, classes] of html.matchAll(/class="([^"]+)"/g)) {
+          for (const cls of classes.trim().split(/\s+/)) {
+            if (cls && !cls.startsWith('ui-')) usedInSpec.add(cls)
+          }
+        }
+        const undefined_ = [...usedInSpec].filter(cls => !definedClasses.has(cls))
+        if (undefined_.length > 0) {
+          const route = spec.route ?? spec.filePath ?? '(unknown)'
+          log.warn(`${route}: class${undefined_.length === 1 ? '' : 'es'} used but not defined in any CSS: ${undefined_.slice(0, 5).map(c => `.${c}`).join(', ')}${undefined_.length > 5 ? ` … +${undefined_.length - 5} more` : ''}`)
+        }
+      } catch { /* render failures are not our concern here */ }
+    }
+  } catch { /* never crash the dev server over a lint warning */ }
+}
+
 async function triggerReload(label = 'File changed') {
   clearTimeout(reloadTimer)
   reloadTimer = setTimeout(async () => {
@@ -151,6 +193,7 @@ async function triggerReload(label = 'File changed') {
       const fresh = await loadPages(ROOT, now)
       updateSpecs(fresh)
       log.info(`${label} — specs reloaded`)
+      checkUndefinedClasses(fresh)
     } catch (err) {
       log.error(`Spec reload failed: ${err.message}`)
     }

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,12 +1043,16 @@ ${(() => {
   }
   
   // 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')
   }
@@ -1141,12 +1146,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 +2252,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 +2357,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 +3026,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 +3125,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 +3155,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 +3461,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,12 @@ 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.')
+  }
+
   // 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)