@invisibleloop/pulse 0.20.1 → 0.20.3

package/src/mcp/server.js

@@ -5,11 +5,12 @@
  * Provides tools and resources for an AI agent working inside a Pulse project.
  *
  * Resources:
+ *   pulse://start   — context-aware entry point (new project / edit / bug fix)
  *   pulse://guide   — complete guide: spec format, UI components, CSS rules, patterns
  *
  * Tools:
  *   pulse_intent         — intent engine: describe what to build, get archetype + scaffold
- *   pulse_suggest        — draft-mode contextual feedback on partial specs
+ *   pulse_suggest        — draft-mode contextual feedback on partial specs (use after first draft)
  *   pulse_intake         — product intake: capture app details before scaffolding
  *   pulse_sketch         — generate 3 structural layout directions before writing code
  *   pulse_list_icons     — list all available icon names, grouped by category
@@ -17,7 +18,9 @@
  *   pulse_list_structure — list all pages and components
  *   pulse_create_page    — create a new page spec with proper template
  *   pulse_create_component — create a reusable component
+ *   pulse_create_tests   — generate starter test file with XSS, null data, and landmark stubs
  *   pulse_validate       — validate a spec against the schema
+ *   pulse_review         — full code review (pass quick:true for lightweight mid-build check)
  *   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/
@@ -188,6 +191,99 @@ for (const { name, uri, title, description, content } of GUIDE_RESOURCES) {
   )
 }
 
+// pulse://start — context-aware single entry point.
+// Detects whether this is a new project, new page, or targeted edit, and returns
+// exactly what the agent needs — no upfront decision tree, no wasted fetches.
+server.registerResource(
+  'start',
+  'pulse://start',
+  {
+    title:       'Pulse Start — Context-Aware Entry Point',
+    description: 'Single entry point that returns the right resources for your situation: new project, new page, targeted edit, or bug fix. Fetch this first instead of deciding between pulse://workflow and pulse://quickstart.',
+    mimeType:    'text/plain',
+  },
+  async () => {
+    // Detect project state to tailor the response
+    let pageCount = 0
+    try {
+      const specs = await loadPages(ROOT)
+      pageCount = specs.length
+    } catch { /* fresh project */ }
+
+    const isNewProject = pageCount === 0
+
+    return ({
+      contents: [{
+        uri:      'pulse://start',
+        mimeType: 'text/plain',
+        text: `# Pulse — Start Here
+
+${isNewProject
+  ? `> **New project detected** — no pages found in src/pages/ yet.`
+  : `> **Existing project** — ${pageCount} page${pageCount !== 1 ? 's' : ''} found.`}
+
+---
+
+## What are you doing?
+
+### A — New page or new site from scratch
+Fetch \`pulse://workflow\` for the full phase/gate sequence, then follow the intake → sketch → intent pipeline.
+
+Quick checklist before your first line of code:
+1. Ask the user for design inspiration first (a site, screenshot, or mood board)
+2. Ask: **light or dark?** Pulse renders dark when \`meta.theme\` is unset — decide before writing a single line
+3. Run \`pulse_intake\` → \`pulse_sketch\` → \`pulse_intent\`
+4. Fetch \`pulse://guide/templates\` + \`pulse://guide/design-references\` for aesthetic direction
+
+### B — Editing an existing page, adding a section, or fixing a bug
+Fetch \`pulse://quickstart\` — workflow phases, spec skeleton, components, and theming in one fetch.
+
+Quick checklist:
+1. Read the file you're changing
+2. Make the edit
+3. \`pulse_validate\` → \`/verify --quick\` (mid-iteration) or \`/verify\` (final check)
+
+### C — Targeted one-liner (label change, prop swap, CSS tweak)
+No resource fetch needed. Read the file, make the change, run \`/verify --quick\` to check it looks right, then \`/verify\` when the user is happy.
+
+### D — Stuck mid-build
+- Wrong component props? → \`pulse://guide/components\`
+- Server data / store / auth? → \`pulse://guide/server\`
+- CSS / theming? → \`pulse://guide/styles\`
+- Routing or layout? → \`pulse://guide/routing\`
+- Lighthouse < 100? → Fix the failing audit, re-run \`/verify\`
+- Something looks wrong visually? → \`pulse_restart_server\` (hot-reloads specs instantly) then navigate the browser
+
+---
+
+## Essential rules — memorise these
+
+- **\`meta.theme\` defaults to dark.** If the design is light, set \`theme: 'light'\` in the plan — not at screenshot time.
+- **Never set \`hydrate\`** — the framework sets it automatically from the URL entry.
+- **\`meta\` is always a plain object** — individual fields (\`title\`, \`description\`) can be async functions, but \`meta\` itself is \`{}\`.
+- **After every file edit:** \`pulse_restart_server\` → navigate browser → check result. (Hot-reloads specs in ~200 ms — no process restart needed.)
+- **\`/verify\` is always last** — it writes the \`.pulse-verified\` stamp. Without it, the stop hook blocks.
+
+---
+
+## Tools you'll use most
+
+| Tool | When |
+|---|---|
+| \`pulse_intake\` | New project — capture name, pitch, palette, theme, vibe |
+| \`pulse_sketch\` | New project — 3 layout directions before writing code |
+| \`pulse_intent\` | Map a description to archetype + scaffold |
+| \`pulse_suggest\` | **After first draft** — mid-build health check before hard validation |
+| \`pulse_validate\` | After every write |
+| \`pulse_review\` | Final gate after Lighthouse passes |
+| \`pulse_restart_server\` | After every file edit |
+| \`pulse_status\` | Session start — pages, server status, last build |
+`,
+      }]
+    })
+  }
+)
+
 // pulse://quickstart — combined essentials for simple/targeted tasks.
 // Reduces cold-start fetch round-trips from 4 (workflow + spec + components + styles)
 // to 1 for edits, bug fixes, and one-shot page builds that don't need the full guides.
@@ -222,9 +318,15 @@ server.registerResource(
 
 \`\`\`
 New page:   pulse_intake → pulse_sketch → pulse_intent → build → validate → screenshot → design approval → /verify
-Edit/fix:   read file → change → validate → /verify
+Edit/fix:   read file → change → validate → /verify --quick → (iterate) → /verify
 \`\`\`
 
+**\`/verify\` has two modes:**
+- \`/verify --quick\` — validate + screenshot + console + code review. No Lighthouse, no build. Use this during active iteration, between design rounds, or any time you're not yet at the "ready to ship" point. Fast (~10 s).
+- \`/verify\` — full loop: Lighthouse desktop + mobile + perf trace + all of the above. Use once the user has approved the design and you're done building. Slow (~90 s).
+
+**Rule: default to \`/verify --quick\` while building. Only run \`/verify\` (full) when the user signals they're done or happy with the result.**
+
 Tier 1 (static/read-only): phases 3 → 4 → 5a (design approval) → 5b (/verify)
 Tier 2 (interactive):       phases 3 → 4 → 5a → 5b → 6 (tests) → 7 (review)
 
@@ -276,6 +378,43 @@ export default {
 
 ---
 
+## Event binding — input patterns
+
+**The right pattern for each input type:**
+
+| Input type | Pattern | Why |
+|---|---|---|
+| Button click | \`<button data-event="increment">\` | click fires mutation |
+| Select / radio / checkbox | \`<select data-event="change:setFilter">\` | \`change\` fires on blur-with-changed-value — the correct commit semantic |
+| Color picker | \`<input type="color" data-event="change:setColor">\` | same as select |
+| Range slider | \`<input type="range" data-event="input:setVolume">\` | \`input\` fires on every drag step |
+| Text / email / password / search | **No \`data-event\`** — read via FormData | \`data-event\` on text inputs re-renders on every keystroke, destroying cursor position and focus |
+
+**Text input pattern (uncontrolled):**
+\`\`\`js
+// view — no data-event on the input
+view: (state) => \`
+  <form data-action="submit">
+    <input type="text" name="email" placeholder="Email">
+    <button type="submit">Save</button>
+  </form>
+\`,
+// action — read FormData in onStart (before validation)
+actions: {
+  submit: {
+    onStart:   (state, formData) => ({ status: 'loading', email: formData.get('email') }),
+    validate:  true,
+    run:       async (state) => { /* use state.email */ },
+    onSuccess: (state) => ({ status: 'success' }),
+    onError:   (state, err) => ({ status: 'error', error: err.message }),
+  }
+}
+\`\`\`
+
+**\`change:\` is the blur/commit event** — it fires when a non-text input loses focus with a changed value. This is correct for selects, color pickers, checkboxes, and radios. It does NOT fire on every keystroke (use \`input:\` for live-updating sliders or search fields where re-render on every character is intentional and the element is not a free-text input).
+
+---
+
 ## Key components (quick reference)
 
 Import from \`@invisibleloop/pulse/ui\`. Always include \`/pulse-ui.css\` in \`meta.styles\`.
@@ -586,8 +725,11 @@ server.registerTool(
         return text(`File not found: ${file}`)
       }
       content = fs.readFileSync(file, 'utf8')
+      // Validate from the file's own directory so relative imports resolve
+      // correctly for pages in subdirectories
+      return validateContent(content, path.dirname(file))
     }
-    
+
     return validateContent(content)
   }
 )
@@ -632,7 +774,9 @@ Rules for the spec you write:
     }
 
     const content = fs.readFileSync(fullPath, 'utf8')
-    const validation = await validateContent(content)
+    // Validate from the file's own directory so relative imports resolve
+    // correctly for pages in subdirectories (src/pages/news/index.js)
+    const validation = await validateContent(content, path.dirname(fullPath))
     if (validation.content[0].text.startsWith('Invalid')) return validation
 
     const route = derivedRouteFromName(name)
@@ -788,6 +932,178 @@ ${onStart}${validate ? '\n      validate: true,' : ''}
   }
 )
 
+// ---------------------------------------------------------------------------
+// pulse_create_tests
+// ---------------------------------------------------------------------------
+
+server.registerTool(
+  'pulse_create_tests',
+  {
+    description: `Generate a starter test file for a Pulse page spec. Stubs out the formulaic test cases — null data, empty arrays, XSS injection, view landmarks, mutation logic, and onViewError — so you start with coverage scaffolding rather than a blank file.
+
+Workflow:
+1. Call this with the spec file path after writing the spec
+2. Review the generated stub file — add real assertions where marked TODO
+3. Run the tests with pulse_run_tests
+4. Fill in any missing assertions until 100% branch coverage passes
+
+The generated file uses @invisibleloop/pulse/testing (renderSync / render). Do NOT use raw html.includes() in tests.`,
+    inputSchema: {
+      file: z.string().describe('Absolute path to the spec file, e.g. /Users/me/project/src/pages/about.js'),
+    },
+  },
+  async ({ file }) => {
+    if (!fs.existsSync(file)) {
+      return text(`File not found: ${file}`)
+    }
+
+    const source  = fs.readFileSync(file, 'utf8')
+    const relPath = path.relative(ROOT, file)
+    const testFile = file.replace(/\.js$/, '.test.js')
+
+    if (fs.existsSync(testFile)) {
+      return text(`Test file already exists: ${path.relative(ROOT, testFile)}\nDelete it first if you want to regenerate.`)
+    }
+
+    // Extract spec details to inform the scaffolding
+    const hasMutations  = source.includes('mutations:')
+    const hasActions    = source.includes('actions:')
+    const hasServer     = source.includes('server:')
+    const hasOnViewError = source.includes('onViewError')
+    const hasValidation = source.includes('validation:')
+
+    const mutationNames = [...source.matchAll(/^\s{4}(\w+)\s*:\s*\(state/gm)].map(m => m[1])
+    const actionNames   = hasActions
+      ? [...source.matchAll(/^\s{4}(\w+)\s*:\s*\{/gm)].map(m => m[1]).filter(n => n !== 'meta' && n !== 'server' && n !== 'mutations' && n !== 'actions' && n !== 'state' && n !== 'validation' && n !== 'constraints')
+      : []
+
+    const specName = path.basename(file, '.js')
+    const importPath = path.relative(path.dirname(testFile), file).replace(/\.js$/, '.js')
+
+    const lines = []
+    lines.push(`import { describe, it } from 'node:test'`)
+    lines.push(`import assert from 'node:assert/strict'`)
+    lines.push(`import { renderSync${hasServer ? ', render' : ''} } from '@invisibleloop/pulse/testing'`)
+    lines.push(`import spec from './${importPath.replace(/^\.\//, '')}'`)
+    lines.push(``)
+    lines.push(`// ${relPath}`)
+    lines.push(``)
+
+    lines.push(`describe('${specName} — view', () => {`)
+    lines.push(`  it('renders main landmark', () => {`)
+    lines.push(`    const r = renderSync(spec${hasServer ? `, { server: {} }` : ''})`)
+    lines.push(`    assert(r.has('main#main-content'), 'missing <main id="main-content">')`)
+    lines.push(`  })`)
+    lines.push(``)
+
+    if (hasServer) {
+      lines.push(`  it('handles null/empty server data without crashing', () => {`)
+      lines.push(`    // Replace null with realistic empty values for each server fetcher`)
+      lines.push(`    const r = renderSync(spec, { server: { /* TODO: add fetcher keys with null/[] values */ } })`)
+      lines.push(`    assert(r.has('main'))`)
+      lines.push(`  })`)
+      lines.push(``)
+
+      lines.push(`  it('handles empty array server data', () => {`)
+      lines.push(`    // Verify empty-state rendering (empty() component or fallback message)`)
+      lines.push(`    const r = renderSync(spec, { server: { /* TODO: fetchers with [] values */ } })`)
+      lines.push(`    assert(r.has('main'))`)
+      lines.push(`  })`)
+      lines.push(``)
+    }
+
+    lines.push(`  it('does not render user input unescaped (XSS)', () => {`)
+    lines.push(`    // Replace one user-controlled field with a script tag`)
+    lines.push(`    const xss = '<script>alert(1)</script>'`)
+    if (hasServer) {
+      lines.push(`    const r = renderSync(spec, { server: { /* TODO: pass xss as a string field */ } })`)
+    } else {
+      lines.push(`    const r = renderSync(spec, { state: { /* TODO: pass xss as a string state field */ } })`)
+    }
+    lines.push(`    assert(!r.text().includes('<script>'), 'XSS string rendered unescaped')`)
+    lines.push(`  })`)
+    lines.push(``)
+
+    if (hasOnViewError) {
+      lines.push(`  it('onViewError returns fallback HTML when view throws', () => {`)
+      lines.push(`    assert(typeof spec.onViewError, 'function')`)
+      lines.push(`    const fallback = spec.onViewError(new Error('test'), spec.state ?? {}, {})`)
+      lines.push(`    assert(typeof fallback === 'string' && fallback.length > 0, 'onViewError must return non-empty HTML string')`)
+      lines.push(`  })`)
+      lines.push(``)
+    }
+
+    lines.push(`})`)
+    lines.push(``)
+
+    if (hasMutations && mutationNames.length > 0) {
+      lines.push(`describe('${specName} — mutations', () => {`)
+      for (const name of mutationNames.slice(0, 6)) {
+        lines.push(`  it('${name} returns partial state', () => {`)
+        lines.push(`    assert(typeof spec.mutations.${name}, 'function')`)
+        lines.push(`    // TODO: call spec.mutations.${name}(spec.state, mockEvent) and assert the returned shape`)
+        lines.push(`    // e.g. const next = spec.mutations.${name}({ ...spec.state }, { target: { value: 'test' } })`)
+        lines.push(`    //      assert.equal(typeof next, 'object')`)
+        lines.push(`  })`)
+        lines.push(``)
+      }
+      lines.push(`})`)
+      lines.push(``)
+    }
+
+    if (hasActions && actionNames.length > 0) {
+      lines.push(`describe('${specName} — actions', () => {`)
+      for (const name of actionNames.slice(0, 4)) {
+        lines.push(`  it('${name}.onStart returns loading state', () => {`)
+        lines.push(`    if (!spec.actions?.${name}?.onStart) return`)
+        lines.push(`    const next = spec.actions.${name}.onStart(spec.state ?? {}, new FormData())`)
+        lines.push(`    assert(next.status === 'loading' || typeof next === 'object', 'onStart must return partial state')`)
+        lines.push(`  })`)
+        lines.push(``)
+        lines.push(`  it('${name}.onError returns error state', () => {`)
+        lines.push(`    if (!spec.actions?.${name}?.onError) return`)
+        lines.push(`    const next = spec.actions.${name}.onError(spec.state ?? {}, new Error('test'))`)
+        lines.push(`    assert(typeof next === 'object', 'onError must return partial state')`)
+        lines.push(`  })`)
+        lines.push(``)
+      }
+      lines.push(`})`)
+      lines.push(``)
+    }
+
+    if (hasValidation) {
+      lines.push(`describe('${specName} — validation', () => {`)
+      lines.push(`  it('spec has validation rules', () => {`)
+      lines.push(`    assert(typeof spec.validation === 'object' && spec.validation !== null)`)
+      lines.push(`    assert(Object.keys(spec.validation).length > 0, 'validation object is empty')`)
+      lines.push(`  })`)
+      lines.push(`})`)
+      lines.push(``)
+    }
+
+    const testContent = lines.join('\n')
+    fs.writeFileSync(testFile, testContent, 'utf8')
+
+    const summary = [
+      `Generated ${path.relative(ROOT, testFile)}`,
+      ``,
+      `Stubs created:`,
+      `  ✓ View landmark test`,
+      hasServer   ? `  ✓ Null/empty server data tests` : null,
+      `  ✓ XSS injection test`,
+      hasOnViewError ? `  ✓ onViewError fallback test` : null,
+      hasMutations && mutationNames.length > 0 ? `  ✓ Mutation tests (${mutationNames.slice(0, 6).join(', ')})` : null,
+      hasActions   && actionNames.length > 0   ? `  ✓ Action onStart/onError tests (${actionNames.slice(0, 4).join(', ')})` : null,
+      hasValidation ? `  ✓ Validation structure test` : null,
+      ``,
+      `Next: search for "TODO" in the file — each TODO needs a real assertion.`,
+      `Run: pulse_run_tests`,
+    ].filter(Boolean).join('\n')
+
+    return text(summary)
+  }
+)
+
 // ---------------------------------------------------------------------------
 // pulse_fetch_page
 // ---------------------------------------------------------------------------
@@ -820,7 +1136,7 @@ server.registerTool(
 server.registerTool(
   'pulse_restart_server',
   {
-    description: 'Stop and restart the Pulse dev server. Use after adding new pages or making changes that require a restart.',
+    description: 'Reload specs in the running dev server. Tries a fast hot-reload first (no process restart); falls back to full kill/restart only if the server is not running.',
     inputSchema: {},
   },
   async () => {
@@ -833,15 +1149,32 @@ server.registerTool(
       } catch { /* use default */ }
     }
 
-    // Kill any process on the port
+    // Fast path — POST to the running dev server's hot-reload endpoint.
+    // This reloads specs in-process and sends an SSE reload event to the browser
+    // without killing the server process (~200 ms vs ~3 s for a full restart).
+    const hotReloaded = await new Promise(resolve => {
+      try {
+        const req = http.request(
+          { hostname: '127.0.0.1', port, path: '/_pulse/trigger-reload', method: 'POST', timeout: 2000 },
+          res => resolve(res.statusCode === 204)
+        )
+        req.on('error', () => resolve(false))
+        req.on('timeout', () => { req.destroy(); resolve(false) })
+        req.end()
+      } catch { resolve(false) }
+    })
+
+    if (hotReloaded) {
+      return text(`Dev server specs reloaded (hot) on port ${port}`)
+    }
+
+    // Slow path — server not running or unresponsive, do a full kill/restart
     try { execFileSync('sh', ['-c', `lsof -ti:${port} | xargs kill -9 2>/dev/null; true`]) } catch { /* nothing running */ }
 
-    // Start fresh dev server detached so it outlives the MCP tool call
     const devScript = new URL('../cli/dev.js', import.meta.url).pathname
     const proc = spawn(process.execPath, [devScript, '--root', ROOT], { detached: true, stdio: 'ignore' })
     proc.unref()
 
-    // Wait until the server is actually accepting requests
     const ready = await waitForServer(port)
     return text(ready
       ? `Dev server restarted on port ${port}`
@@ -908,13 +1241,18 @@ server.registerTool(
 Reads the spec source, renders the view with initial state, runs all validation checks,
 and returns a structured review brief. You must read everything carefully, find every
 issue, and fix them all before reporting back to the user. Use this after completing
-any feature build.`,
+any feature build.
+
+**Two modes:**
+- Default (full review): runs after Lighthouse passes — the canonical final gate. Returns full checklist + rendered HTML + validator output.
+- \`quick: true\`: lightweight mid-build check. Runs structural checks (main landmark, data-event on inputs, missing onError, hex in view, component patterns) without Lighthouse or the full checklist. Use after first draft, before the expensive verification pass. Not a substitute for the full review.`,
     inputSchema: {
-      file: z.string().optional().describe('Absolute path to the spec file to review'),
+      file:    z.string().optional().describe('Absolute path to the spec file to review'),
       content: z.string().optional().describe('JavaScript spec content to review (alternative to file)'),
+      quick:   z.boolean().optional().describe('Run a lightweight mid-build check instead of the full review gate. Catches obvious structural issues without running Lighthouse. Use after first draft, before /verify.'),
     },
   },
-  async ({ file, content }) => {
+  async ({ file, content, quick = false }) => {
     if (!file && !content) {
       return text('Error: must provide either file or content')
     }
@@ -924,10 +1262,119 @@ any feature build.`,
 
     let source = content
     if (file) {
+      if (!path.isAbsolute(file)) file = path.resolve(process.cwd(), file)
       if (!fs.existsSync(file)) return text(`File not found: ${file}`)
       source = fs.readFileSync(file, 'utf8')
     }
 
+    // Quick mode — lightweight structural checks only, no full checklist or Lighthouse gate
+    if (quick) {
+      const issues = []
+      const warnings = []
+
+      // Try to render the view
+      let renderedHtml = ''
+      if (file) {
+        try {
+          const mod  = await import(`${file}?quick=${Date.now()}`)
+          const spec = mod.default
+          if (spec && typeof spec.view === 'function') {
+            renderedHtml = spec.view(spec.state || {}, {})
+          }
+        } catch { /* ignore — server data dependency */ }
+      }
+
+      if (renderedHtml) {
+        if (!/<main[^>]*id=["']?main-content/.test(renderedHtml))
+          issues.push('✗ Missing `<main id="main-content">` landmark')
+        if (/<input[^>]*data-event/.test(renderedHtml))
+          issues.push('✗ `data-event` on `<input>` — destroys focus on every keystroke, use FormData in onStart instead')
+        if (/(className|htmlFor|onClick)=/.test(renderedHtml))
+          issues.push('✗ React patterns found (className / htmlFor / onClick) — use class, for, data-event')
+        if (/tabindex=["']?([1-9]\d*)/.test(renderedHtml))
+          issues.push('✗ Positive tabindex found — remove, reorder DOM instead')
+        const rawNavInSource = (source.match(/<nav[\s>]/gi) || []).length
+        if (rawNavInSource > 0)
+          issues.push(`✗ Raw <nav> tag in spec source — nav() renders <nav> internally; wrapping it in another <nav> creates duplicate landmarks that fail Lighthouse accessibility. Remove the outer <nav>.`)
+        const viewBlockStripped = renderedHtml
+          .replace(/href=["']#[^"']*["']/g, 'href="#"')
+          .replace(/id=["'][^"']*["']/g, 'id=""')
+          // Strip CSS custom property assignments from style attrs (--foo:#hex is a runtime
+          // data binding, not an authored colour — e.g. style="--swatch-bg:#E8524A").
+          // Standard property assignments like color:#000 are left intact and still flagged.
+          .replace(/style="([^"]*)"/g, (_, v) => `style="${v.replace(/--[a-zA-Z][^:]*:[^;"]*/g, '')}"`)
+        if (/#[0-9a-fA-F]{6}\b|#[0-9a-fA-F]{3}\b(?![0-9a-fA-F])/.test(viewBlockStripped))
+          warnings.push('⚠ Possible hex colour in rendered HTML — use var(--ui-*) tokens')
+
+        // Component pattern checks (unless creative override declared)
+        if (!/component.free|creative\s+override/i.test(source)) {
+          if (/<[^>]+class="[^"]*\bhero\b/.test(renderedHtml) && !source.includes('hero('))
+            warnings.push('⚠ `.hero` class in HTML but no `hero()` component — use the component or declare creative override')
+          if (/<[^>]+class="[^"]*\bcard\b/.test(renderedHtml) && !source.includes('card('))
+            warnings.push('⚠ `.card` class in HTML but no `card()` component — use the component or declare creative override')
+        }
+      }
+
+      // Source-level checks (don't need rendered HTML).
+      // Use line-anchored regex for actions: to avoid false positives from component
+      // prop strings like hero({ actions: '...' }) or card({ actions: '...' }).
+      const hasActionsBlock = /^\s{0,4}actions\s*:/m.test(source)
+      if (hasActionsBlock && !source.includes('onError:'))
+        issues.push('✗ Action missing `onError` — required, will throw at runtime')
+      if (hasActionsBlock && !source.includes('onSuccess:'))
+        issues.push('✗ Action missing `onSuccess` — required')
+      if (source.includes('hydrate:'))
+        issues.push('✗ `hydrate` is set manually — remove it, the framework sets it automatically')
+      if (/meta\s*:\s*async/.test(source))
+        issues.push('✗ `meta` is an async function — `meta` must be a plain object; make individual fields async instead')
+
+      // Structural confirmations — always shown regardless of issues, so the agent
+      // gets positive signal on what's correct, not just a list of failures.
+      const confirms = []
+      if (renderedHtml) {
+        confirms.push(/<main[^>]*id=["']?main-content/.test(renderedHtml) ? '✓ `<main id="main-content">` landmark present' : null)
+        const rawNavInSource = (source.match(/<nav[\s>]/gi) || []).length
+        if (rawNavInSource === 0) confirms.push('✓ No raw <nav> in spec source — nav() component handles landmarks correctly')
+        const headings = [...renderedHtml.matchAll(/<h([1-6])[^>]*>/g)].map(m => parseInt(m[1]))
+        if (headings.length > 0) {
+          const orderOk = headings.every((h, i) => i === 0 || h <= headings[i - 1] + 1)
+          confirms.push(orderOk ? `✓ Heading order correct (${headings.map(h => `h${h}`).join(' → ')})` : `⚠ Heading order may be skipping levels (${headings.map(h => `h${h}`).join(' → ')})`)
+        }
+        const interactiveWithoutLabel = [...renderedHtml.matchAll(/<button(?![^>]*aria-label)[^>]*>\s*<\/button>/g)]
+        confirms.push(interactiveWithoutLabel.length === 0 ? '✓ No empty buttons without aria-label detected' : `⚠ ${interactiveWithoutLabel.length} button(s) appear empty — check aria-label`)
+        const dataEvents = [...renderedHtml.matchAll(/data-event=/g)].length
+        if (dataEvents > 0) confirms.push(`✓ ${dataEvents} data-event binding(s) found`)
+        const creativeOverride = /component.free|creative\s+override/i.test(source)
+        if (creativeOverride) confirms.push('✓ Creative override declared — component pattern checks are advisory')
+      }
+
+      const lines = ['## Quick review\n']
+
+      if (confirms.filter(Boolean).length > 0) {
+        lines.push('### Structural checks\n')
+        for (const c of confirms.filter(Boolean)) lines.push(c)
+        lines.push('')
+      }
+
+      if (issues.length === 0 && warnings.length === 0) {
+        lines.push('✓ No issues found. Run `pulse_validate` next, then `/verify`.')
+      } else {
+        if (issues.length) {
+          lines.push('### Fix before proceeding\n')
+          for (const i of issues) lines.push(i)
+          lines.push('')
+        }
+        if (warnings.length) {
+          lines.push('### Warnings (check these)\n')
+          for (const w of warnings) lines.push(w)
+          lines.push('')
+        }
+        lines.push('---\nFix issues, then run `pulse_validate` → `/verify --quick`.')
+      }
+
+      return text(lines.join('\n'))
+    }
+
     // Run the validator in a child process (same as pulse_validate)
     let validationResult = '(could not run validator)'
     if (file) {
@@ -1043,13 +1490,14 @@ ${(() => {
   }
   
   // Check spec source
-  // 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.
+  // Hex colours in view — strip anchor hrefs, id attributes, template literal expressions,
+  // and style attributes before checking so runtime-generated values (e.g. style="--swatch-bg:${hex}")
+  // are never flagged. Only flag literal hex values authored directly in the view string.
   const viewBlock = source.slice(source.indexOf('view:'))
   const viewBlockStripped = viewBlock
     .replace(/href=["']#[^"']*["']/g, 'href="#"')   // href="#anchor" → href="#"
     .replace(/id=["'][^"']*["']/g, 'id=""')          // id="foo" → id=""
+    .replace(/\$\{[^}]*\}/g, '${…}')                 // ${expr} — runtime values, not authored hex
   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')
@@ -1210,13 +1658,16 @@ The stop hook compares each changed spec's mtime against this stamp. Any spec ne
 server.registerTool(
   'pulse_await_approval',
   {
-    description: `Pause the workflow to wait for the user's answer — call this immediately BEFORE asking a blocking question (e.g. the design-approval gate: "Happy with the layout and direction…?").
+    description: `Pause the workflow gates for one turn-end — call this immediately BEFORE ending a turn that legitimately waits on the user. That covers:
 
-It writes a .pulse-awaiting-approval marker that tells the Stop hooks (missing tests, coverage, verify stamp) to let the turn end without demanding /verify first. The marker is deleted automatically when the user sends their next message — the gates return in full force for your following turn.
+- **Blocking questions** — the design-approval gate ("Happy with the layout and direction…?"), or any decision only the user can make.
+- **Mid-flow progress pauses** — reporting between long verification steps (e.g. between Lighthouse runs while verifying many pages) when the work is not yet stamped.
 
-**Always call this before the approval question, regardless of how you ask.** In some hosts (including Claude Code) even a dedicated question tool like AskUserQuestion ends the turn, which fires the Stop hooks. The marker is harmless if the turn does not end — it is simply consumed when the user replies. Calling it first works in every host; relying on the question tool to keep the turn open does not.
+It writes a .pulse-awaiting-approval marker that tells the Stop hooks (missing tests, coverage, verify stamp) to let the turn end without demanding /verify first. The marker is deleted automatically when the user sends their next message — the gates return in full force for your following turn, so re-call it before each pause in a long multi-page flow.
 
-Do NOT use this to skip verification — it buys exactly one turn-end, paired with a question the user must answer. Calling it without asking anything just delays the gates by one message.`,
+**Always call this before an approval question, regardless of how you ask.** In some hosts (including Claude Code) even a dedicated question tool like AskUserQuestion ends the turn, which fires the Stop hooks. The marker is harmless if the turn does not end — it is simply consumed when the user replies.
+
+Do NOT use this to skip verification — it buys exactly one turn-end, paired with something the user genuinely needs to see or answer. Calling it to dodge the gates just delays them by one message.`,
     inputSchema: {},
   },
   () => {
@@ -1793,6 +2244,15 @@ If your page genuinely doesn't fit a pattern, start from pulse://guide/spec and
     lines.push(`State:  ${arch.stateHint}`)
     lines.push(`Server: ${arch.serverHint}`)
 
+    lines.push(``)
+    lines.push(`## ⚠ Before writing any code — ask these two questions`)
+    lines.push(``)
+    lines.push(`1. **Light or dark?** Pulse renders **dark** by default when \`meta.theme\` is unset. If the user hasn't stated a preference, ask now — discovering the wrong theme at the screenshot costs a full edit → restart → re-approval cycle.`)
+    lines.push(`   Add \`theme: 'light'\` to your plan or brief if confirmed light.`)
+    lines.push(``)
+    lines.push(`2. **Design inspiration?** Ask: "Do you have any design inspiration — a site you love, a screenshot, or a mood board image? Drop it into \`public/intake/\` or paste a URL." If yes, call \`pulse_extract_inspiration\` before proceeding.`)
+    lines.push(`   (Skip if this came from pulse_intake — it already asked.)`)
+
     lines.push(``)
     lines.push(`## Guide sections to read`)
     lines.push(``)
@@ -2313,7 +2773,9 @@ The extracted values map directly to pulse_intake fields (palette, vibe, styleNo
       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.')
-      lines.push('**Fill in the sections below based on what you observe. Return a completed extraction, not an empty template.**\n')
+      lines.push('**Fill in the sections below based on what you observe. Return a completed extraction, not an empty template.**')
+      lines.push('')
+      lines.push('> **If the URL is blocked or unreachable:** do not return a blank template. Instead, use your training knowledge of the site/brand to populate as many fields as you can, mark each cell with "(from knowledge, not live)" and note at the top that the URL was unreachable. A knowledge-based extraction is more useful than an empty template.\n')
     } else {
       lines.push('## Step 1 — Analyse the source (do this now)')
       lines.push(`Source: **${source}**`)
@@ -3380,7 +3842,7 @@ const PROP_ALIASES = [
   { component: 'input()',  wrong: 'pattern',     correct: 'attrs: { pattern }',       note: 'HTML attributes go inside `attrs`: input({ attrs: { pattern: "[0-9]+" } }).' },
 ]
 
-async function validateContent(content) {
+async function validateContent(content, tmpDir = PAGES_DIR) {
   // Source-level checks — run before the worker so errors are caught without importing
   const sourceWarnings = []
 
@@ -3388,9 +3850,17 @@ async function validateContent(content) {
   for (const { component, wrong, correct, note } of PROP_ALIASES) {
     // Match: nav({ ...wrong: or footer({ ...wrong: (within the call args)
     const fnName = component.replace('()', '')
-    const re = new RegExp(`${fnName}\\s*\\(\\s*\\{[^}]*\\b${wrong}\\s*:`, 'g')
-    if (re.test(content)) {
+    const re = new RegExp(`${fnName}\\s*\\(\\s*\\{([^}]*)\\b${wrong}\\s*:`, 'g')
+    let m
+    while ((m = re.exec(content)) !== null) {
+      // Inside attrs: { … } is the CORRECT placement for these HTML attributes —
+      // when the text between the call's opening brace and the prop ends inside
+      // an open attrs object, this is the recommended pattern, not a mistake.
+      // (The naive match crossed into attrs blocks and flagged exactly what the
+      // fix-it note tells people to write.)
+      if (/attrs\s*:\s*\{[^}]*$/.test(m[1])) continue
       sourceWarnings.push(`"${wrong}" is not a recognised prop for ${component} — did you mean "${correct}"? ${note}`)
+      break
     }
   }
 
@@ -3399,24 +3869,28 @@ async function validateContent(content) {
   const externalImgHosts = [
     {
       pattern: /https?:\/\/images\.unsplash\.com/,
+      host:    'images.unsplash.com',
       entry:   'https://images.unsplash.com',
       cookieWarning: true,
       name: 'Unsplash',
     },
     {
       pattern: /https?:\/\/(?:fastly\.)?picsum\.photos/,
+      host:    'picsum.photos',
       entry:   'https://picsum.photos https://fastly.picsum.photos',
       cookieWarning: false,
       name: 'picsum',
     },
     {
       pattern: /https?:\/\/res\.cloudinary\.com/,
+      host:    'res.cloudinary.com',
       entry:   'https://res.cloudinary.com',
       cookieWarning: true,
       name: 'Cloudinary',
     },
     {
       pattern: /https?:\/\/cdn\.shopify\.com/,
+      host:    'cdn.shopify.com',
       entry:   'https://cdn.shopify.com',
       cookieWarning: false,
       name: 'Shopify CDN',
@@ -3427,8 +3901,11 @@ async function validateContent(content) {
   if (fs.existsSync(configPath)) {
     try { configImgSrc = fs.readFileSync(configPath, 'utf8') } catch { /* ignore */ }
   }
-  for (const { pattern, entry, cookieWarning, name } of externalImgHosts) {
-    if (pattern.test(content) && !pattern.test(configImgSrc)) {
+  for (const { pattern, host, entry, cookieWarning, name } of externalImgHosts) {
+    // Config match is by HOST, not full URL — CSP sources are valid without a
+    // scheme ('images.unsplash.com'), so requiring https?:// in the config
+    // produced false positives for correctly configured projects.
+    if (pattern.test(content) && !configImgSrc.includes(host)) {
       const cookieNote = cookieWarning
         ? `\n  ⚠ ${name} sets tracking cookies that fail Lighthouse Best Practices regardless of CSP. For production, download images to public/images/ instead of linking to ${name} directly.`
         : ''
@@ -3440,9 +3917,12 @@ async function validateContent(content) {
     }
   }
 
-  // Write into PAGES_DIR so relative imports (e.g. '../components/nav.js') resolve correctly
-  fs.mkdirSync(PAGES_DIR, { recursive: true })
-  const tmpFile = path.join(PAGES_DIR, `.pulse-validate-${Date.now()}.mjs`)
+  // Write the temp file into the directory the spec actually lives in (passed by
+  // callers that know it) so relative imports resolve from the true location.
+  // A page at src/pages/news/index.js importing '../../components/layout.js'
+  // resolved wrongly when the temp file was always dropped in src/pages/ root.
+  fs.mkdirSync(tmpDir, { recursive: true })
+  const tmpFile = path.join(tmpDir, `.pulse-validate-${Date.now()}.mjs`)
   try {
     fs.writeFileSync(tmpFile, content, 'utf8')
 
@@ -3547,12 +4027,17 @@ const PULSE_GUIDE_INDEX = `# Pulse Framework Guide
 
 ## Start here
 
-**Fetch \`pulse://workflow\` before anything else.** It defines the exact sequence of phases and pass gates for every build task. Do not fetch guide sections or start writing code until you have read it. Skipping it means you will run steps in the wrong order.
+**Fetch \`pulse://start\` first.** It detects your context (new project, new page, edit, or bug fix) and returns exactly what you need — no upfront decision tree.
+
+If you know your context already:
+- New page / new site → \`pulse://workflow\`
+- Edit, fix, or one-shot build → \`pulse://quickstart\`
 
 ## Guide resources
 
 | Resource | When to fetch |
 |---|---|
+| \`pulse://start\` | **Always fetch first** — context-aware entry point that routes you to the right resources |
 | \`pulse://quickstart\` | **Editing, bug-fixing, or a simple one-shot build** — workflow + spec skeleton + components + theming in one fetch. Skip the 4-resource cold-start for targeted tasks. |
 | \`pulse://workflow\` | **New project or new page** — full phase/gate sequence before writing any code. |
 | \`pulse://guide/spec\` | Building a spec — state, mutations, actions, streaming SSR, key rules, form layout |
@@ -3573,14 +4058,15 @@ const PULSE_GUIDE_INDEX = `# Pulse Framework Guide
 - \`pulse_intake(name, pitch, features, targetUser?, palette?, font?, theme?, vibe?, styleNotes?, antiStyle?, inspiration?)\` — **Capture product details before scaffolding.** Run this first for any new project or branded template — before pulse_sketch or pulse_intent. **Gather answers by asking the user one free-form question at a time — never use multi-choice lists for open-ended intake questions.** The final intake question must always be: "Do you have any design inspiration — a site you love, a screenshot, or a mood board? Drop images into \`public/intake/\` or share a URL." If the user provides references, call \`pulse_extract_inspiration\` before proceeding. After intake, call pulse_sketch to explore structural directions before writing code.
 - \`pulse_sketch(brief, vibe?, antiStyle?, pageType?)\` — **Generate 3 structurally distinct layout directions before writing any code.** Call after pulse_intake. Returns three named directions (full-bleed, asymmetric split, typography-only, editorial flow, dense grid, story scroll, content-first) with wireframes, key decisions, and component strategies. Prevents defaulting to "centred hero + three columns" on every project. After choosing a direction, fetch \`pulse://guide/explore\` for raw HTML patterns.
 - \`pulse_intent(description)\` — Describe what you want to build in plain language and get back a matched archetype, component recommendations, a ready-to-adapt spec scaffold, and which guides to read. Use after pulse_intake and pulse_sketch, before fetching guides.
-- \`pulse_suggest(content)\` — **Draft-mode feedback.** Paste a partial or complete spec and get constructive, non-blocking suggestions: missing pieces, likely omissions, component upgrades, empty-state reminders. A collaborator, not a gate. Use mid-build before running the hard validator.
+- \`pulse_suggest(content)\` — **Draft-mode feedback.** Paste a partial or complete spec and get constructive, non-blocking suggestions: missing pieces, likely omissions, component upgrades, empty-state reminders. A collaborator, not a gate. **Use after first draft** (after writing, before hard validation) — not just when something feels wrong.
+- \`pulse_create_tests(file)\` — **Generate a starter test file** for a spec. Stubs out the formulaic cases: null data, empty arrays, XSS injection, view landmarks, mutations, action onStart/onError, and onViewError. Search for "TODO" in the output and fill in real assertions. Covers 100% branch coverage requirements without hand-writing the boilerplate.
 - \`pulse_list_icons(filter?)\` — **List all available icon names grouped by category.** Always call this before importing icons — never guess a name or grep source files. Optional filter keyword narrows results (e.g. filter: "arrow").
 - \`pulse_check_contrast(css?, file?, theme?)\` — **Static WCAG contrast check.** Provide theme CSS content or a file path; it checks all token color pairings against WCAG AA thresholds (4.5:1 normal text, 3:1 large text/UI). Run immediately after writing a theme file — before pulse_build and Lighthouse. Catches palette mistakes in milliseconds.
 - \`pulse_tokens\` — **List all --ui-* CSS tokens** from the installed pulse-ui.css, grouped by category (colour, spacing, type-size, typography, shape). Call before writing theme overrides to avoid guessing names. Reminder: set \`--accent\` (no prefix) in theme.css — pulse-ui maps it to \`--ui-accent\` automatically.
 - \`pulse_status\` — **Project health snapshot.** Returns page count, routes, dev server status, last build age, and pulse-ui version check. Call at the start of a session to orient quickly without reading files.
 - \`pulse_list_structure\` — list pages, components, and pulse-ui version. Call at the start of every session.
 - \`pulse_validate\` — validate spec content. Call after every write. Fix all errors AND warnings.
-- \`pulse_review\` — switch into reviewer mode and critically examine a spec you just built. Returns the source, rendered HTML, validator output, and a full review checklist. **Call this only after validate, Lighthouse (desktop + mobile), and tests all pass — it is the final phase before declaring done.**
+- \`pulse_review(file, { quick? })\` — **Two modes.** Default: full review gate (call after Lighthouse + tests pass). Pass \`quick: true\` for a lightweight mid-build structural check — no Lighthouse, just catches obvious issues (missing main landmark, data-event on inputs, missing onError, hex colours, component pattern violations). Use quick mid-build after \`pulse_suggest\`. **Full mode only after validate, Lighthouse (desktop + mobile), and tests all pass.**
 - \`pulse_create_page\` — validate a page spec you already wrote to disk. **Always write the file with the Write tool first, then call this.** Never pass content to this tool.
 - \`pulse_create_component\` — register a component you wrote with the Write tool. Write the file first, then call this.
 - \`pulse_create_store\` — register a pulse.store.js you wrote with the Write tool. Write the file first, then call this.
@@ -3588,7 +4074,7 @@ const PULSE_GUIDE_INDEX = `# Pulse Framework Guide
 - \`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_restart_server\` — hot-reload specs in the running dev server (~200 ms). Falls back to full kill/restart if the server is not running.
 - \`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.**
 - \`pulse_check_version\` — check installed package version, static asset version, and latest on npm. Use this instead of running npm commands when the user asks about updates.
 - \`pulse_update\` — install the latest \`@invisibleloop/pulse\` package and re-copy \`pulse-ui.css\`, \`pulse-ui.js\`, and the agent checklist into \`public/\`. One command does the full upgrade.
@@ -3604,9 +4090,13 @@ const PULSE_GUIDE_INDEX = `# Pulse Framework Guide
 
 ## MANDATORY: Verify every build
 
-**After writing or editing any page spec, you MUST run \`/verify\` before declaring done.**
+**After writing or editing any page spec, you MUST run \`/verify\` or \`/verify --quick\` before declaring done.**
+
+**Choose the right mode:**
+- \`/verify --quick\` — use during active building and iteration. Runs: validate → screenshot → console check → code review → stamp. No Lighthouse, no production build. Fast (~10 s). Use this between every round of changes.
+- \`/verify\` (full) — use when the user signals they're done or happy with the result. Runs everything: validate → screenshot → production build → Lighthouse desktop → Lighthouse mobile → performance trace → console check → code review → stamp. Slow (~90 s). Run this once at the end.
 
-\`/verify\` is the single canonical verification workflow. It runs: validate → screenshot → console check → network check → SSR check → production build → Lighthouse desktop → Lighthouse mobile → performance trace → code review → writes the \`.pulse-verified\` stamp. The stop hook checks this stamp — if it is missing or older than the last spec edit, the hook will block and make you run verification again.
+The stop hook checks the \`.pulse-verified\` stamp — \`/verify --quick\` writes the stamp too, so it satisfies the hook for mid-build turns. The full \`/verify\` is required before the final commit.
 
 **Do not replicate \`/verify\` steps manually.** Running the individual tools yourself does not write the stamp. The agent will be blocked at the end regardless.