@invisibleloop/pulse 0.8.0 → 0.8.1

package/CLAUDE.md

@@ -336,6 +336,39 @@ Always target `[data-theme="light"]` when overriding colours for the light theme
 
 If a colour must apply in both themes, set it in both `:root` and `[data-theme="light"]`.
 
+## CSS File Responsibilities
+
+There are two CSS files and they have distinct roles — do not mix them:
+
+| File | Purpose | Allowed content |
+|---|---|---|
+| `public/theme.css` | Token definitions — hex values, raw colours, font URLs | Hex values, `rgb()`, raw values, `@font-face`, `@import` |
+| `app.css` (or per-page) | Layout and component overrides | `var()` tokens **only** — no hex, no raw colour values |
+
+**`app.css` must never contain hex values or raw colour values.** A lint hook enforces this. If you need to define or override a colour token, put it in `public/theme.css` and reference it via `var()` in `app.css`.
+
+```css
+/* public/theme.css — hex values live here */
+[data-theme="light"] {
+  --color-accent: #e25;
+  --color-bg: #ffffff;
+}
+
+/* app.css — only var() references */
+.hero {
+  background: var(--color-bg);
+  color: var(--color-accent);
+}
+```
+
+Load both files via `meta.styles`, theme first:
+
+```js
+meta: {
+  styles: ['/pulse-ui.css', '/theme.css', '/app.css'],
+}
+```
+
 ## HTTP Response Behaviour
 
 - **Full page request** — SSR HTML with hydration bootstrap

package/package.json

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

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.8.0
+0.8.1

package/public/pulse-ui.css

@@ -40,6 +40,30 @@
 
   /* Touch target minimum per WCAG 2.5.5 */
   --ui-touch-min: 44px;
+
+  /* ── Spacing scale ── */
+  --ui-space-1:  0.25rem;   /*  4px */
+  --ui-space-2:  0.5rem;    /*  8px */
+  --ui-space-3:  0.75rem;   /* 12px */
+  --ui-space-4:  1rem;      /* 16px */
+  --ui-space-5:  1.25rem;   /* 20px */
+  --ui-space-6:  1.5rem;    /* 24px */
+  --ui-space-8:  2rem;      /* 32px */
+  --ui-space-10: 2.5rem;    /* 40px */
+  --ui-space-12: 3rem;      /* 48px */
+  --ui-space-16: 4rem;      /* 64px */
+  --ui-space-20: 5rem;      /* 80px */
+  --ui-space-24: 6rem;      /* 96px */
+
+  /* ── Type scale ── */
+  --ui-text-xs:   0.75rem;    /* 12px */
+  --ui-text-sm:   0.875rem;   /* 14px */
+  --ui-text-base: 1rem;       /* 16px */
+  --ui-text-lg:   1.125rem;   /* 18px */
+  --ui-text-xl:   1.25rem;    /* 20px */
+  --ui-text-2xl:  1.5rem;     /* 24px */
+  --ui-text-3xl:  1.875rem;   /* 30px */
+  --ui-text-4xl:  2.25rem;    /* 36px */
 }
 
 /* ─── Base reset ─────────────────────────────────────────────────────────────

package/src/agent/checklist.md

@@ -66,6 +66,11 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 - **Validate FormData fields before use.** `formData.get('email')` returns `null` if the field is missing. Check for null/empty before passing to an API or database.
 - **Do not trust URL params.** `ctx.params.id` is a raw string from the URL. Validate it before use — check it exists, is the right type, and refers to a real resource. Return a 404 or redirect if it doesn't.
 
+### CSS
+
+- **`app.css` must contain no hex values or raw colour values.** A lint hook enforces this and will block the build. Hex values belong in `public/theme.css` as token definitions; `app.css` references them via `var()` only.
+- **Load order in `meta.styles`:** `pulse-ui.css` → `theme.css` → `app.css`. Theme tokens must be defined before `app.css` references them.
+
 ### Security
 
 - Any value from user input (URL params, form fields, external APIs) interpolated into view HTML must be escaped.

package/src/agent/commands/verify.md

@@ -24,13 +24,13 @@ Use `mcp__chrome-devtools__navigate_page` to load the page route, then `mcp__chr
 
 Run `mcp__chrome-devtools__lighthouse_audit` on the route with `{ "strategy": "desktop" }`.
 
-**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 2.
+**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 2.
 
 ### 6. Lighthouse — mobile
 
 Run `mcp__chrome-devtools__lighthouse_audit` on the same route with `{ "strategy": "mobile" }`.
 
-**Same pass bar: all four categories must be 100.** Report the actual scores. If any score is below 100, fix and restart from step 2.
+**Same pass bar: Accessibility, Best Practices, and SEO must all be 100.** Fix any failures and restart from step 2.
 
 ### 7. Performance
 
@@ -42,7 +42,7 @@ Use `mcp__chrome-devtools__list_console_messages` — report any errors or unexp
 
 ### 9. Code review
 
-Check the spec against the checklist in `.claude/pulse-checklist.md`. Work through every item. Fix anything that fails before proceeding to the next step.
+Call `pulse_review` with the absolute path to the spec file. Read the source, rendered HTML, validator output, and checklist it returns. Fix every issue before proceeding. This is the structured review — do not skip it or replace it with a manual checklist read.
 
 ### 10. Close the browser
 
@@ -56,7 +56,7 @@ Run:
 date +%s > .pulse-verified
 ```
 
-This records that verify completed successfully. The stop hook checks this stamp — do not skip this step.
+**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.
 
 ### 12. Report
 
@@ -69,4 +69,12 @@ Summarise:
 - 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.
+**Pass bar — all of these must be met before the page is confirmed good:**
+- Validation: clean (no errors, no warnings)
+- Lighthouse desktop: Accessibility, Best Practices, SEO all 100
+- Lighthouse mobile: same
+- CLS: 0.00 — any layout shift is a blocker
+- LCP: report the value; flag and fix any insight that identifies a fixable cause
+- Console: no errors
+
+If any gate fails, fix the issue and run `/verify` again.

package/src/agent/guide-styles.md

@@ -61,7 +61,11 @@ meta: {
 }
 ```
 
-Token list: --ui-bg, --ui-surface, --ui-surface-2, --ui-border, --ui-text, --ui-muted, --ui-accent, --ui-accent-hover, --ui-green, --ui-red, --ui-yellow, --ui-blue, --ui-radius, --ui-radius-sm, --ui-font, --ui-mono. Never hardcode hex values — override the tokens.
+**Colour tokens:** `--ui-bg`, `--ui-surface`, `--ui-surface-2`, `--ui-border`, `--ui-text`, `--ui-muted`, `--ui-accent`, `--ui-accent-hover`, `--ui-accent-dim`, `--ui-accent-text`, `--ui-green`, `--ui-red`, `--ui-yellow`, `--ui-blue`, `--ui-radius`, `--ui-radius-sm`, `--ui-font`, `--ui-mono`. Never hardcode hex values — override the tokens.
+
+**Spacing tokens** (`--ui-space-N`): `--ui-space-1` (4px), `--ui-space-2` (8px), `--ui-space-3` (12px), `--ui-space-4` (16px), `--ui-space-5` (20px), `--ui-space-6` (24px), `--ui-space-8` (32px), `--ui-space-10` (40px), `--ui-space-12` (48px), `--ui-space-16` (64px), `--ui-space-20` (80px), `--ui-space-24` (96px). Use these for `padding`, `margin`, and `gap`.
+
+**Type-scale tokens** (`--ui-text-*`): `--ui-text-xs` (12px), `--ui-text-sm` (14px), `--ui-text-base` (16px), `--ui-text-lg` (18px), `--ui-text-xl` (20px), `--ui-text-2xl` (24px), `--ui-text-3xl` (30px), `--ui-text-4xl` (36px). Use these for `font-size`.
 
 ## Custom fonts
 

package/src/agent/workflow.md

@@ -33,7 +33,39 @@ Wait for the user to confirm or adjust the plan before writing any code.
 
 ## Phase 3 — Build
 
-Write the spec and any related files using the **Write tool** — not `pulse_create_page`. This shows the user a readable diff of the file content. After writing, call `pulse_create_page(name)` to validate the file you just wrote. After each file is written, output a one-line status: `✓ Page written — validating...`
+### 3a — Announce before writing
+
+Before writing any file, output a build brief so the user can see what is being constructed and catch misunderstandings before minutes of work are lost. Format:
+
+```
+Building: <page name> (<route>)
+State:     <fields and types, or "none">
+Mutations: <list, or "none">
+Actions:   <list with brief description, or "none">
+Server:    <fetcher names and what they fetch, or "none">
+View:      <key sections / landmarks>
+Files:     <list of files that will be written>
+```
+
+Output this before making any tool calls. Do not skip it for "simple" pages — a one-liner is fine for simple pages, but always output something.
+
+### 3b — Write
+
+Write each file using the **Write tool** — not `pulse_create_page`. This shows the user a readable diff. Before each file write, output a one-line status (present-progressive, no tick — the work hasn't happened yet):
+
+```
+Writing src/pages/my-page.js...
+```
+
+After the Write tool completes, call `pulse_create_page(name)` to register the page. Only after that call succeeds output:
+
+```
+✓ src/pages/my-page.js written and registered.
+```
+
+**Rule: never output `✓` before the tool call that confirms the result. Use present-progressive (`Writing...`, `Running...`, `Checking...`) for pre-tool announcements.**
+
+If multiple files are needed (spec + shared component, spec + test stub, etc.), announce and write them one at a time with a status line before each.
 
 ---
 
@@ -48,15 +80,21 @@ Run `pulse_validate` on the spec file.
 
 ## Phase 5 — Browser check (pass gate)
 
-1. Navigate to the page route in the browser.
-2. Take a screenshot. Check it visually — layout, content, spacing, no raw unstyled HTML.
-3. Check the browser console for errors (JS errors, failed network requests).
-4. Run Lighthouse with `strategy: 'desktop'`. All three scores must be 100: Accessibility, Best Practices, SEO. The tool does not return a Performance score — use `performance_start_trace` separately if performance profiling is needed. Tell the user before calling Lighthouse — it takes 30–60 s.
-5. Run Lighthouse with `strategy: 'mobile'`. Same pass bar.
+**Run `/verify` now — as soon as the first build is working.** Do not defer it to the end. Do not execute these steps manually.
+
+`/verify` is the canonical implementation of phases 4–7: it validates, screenshots, runs Lighthouse (desktop + mobile), runs the performance trace (LCP + CLS), checks console errors, runs `pulse_review`, and — critically — **writes the `.pulse-verified` stamp** at the end. Running the steps manually without writing the stamp will cause the stop hook to block.
+
+Pass gates (all must be met before continuing to Phase 6):
+- Screenshot: no layout or rendering issues
+- Lighthouse desktop: Accessibility, Best Practices, SEO all 100
+- Lighthouse mobile: same pass bar
+- **CLS: 0.00** — any layout shift is a blocker; fix it before proceeding
+- LCP: measured and reported; flag any fixable insight (render-blocking resources, large image delay)
+- No console errors
 
-**If any score is below 100:** fix the issue, reload, re-run Lighthouse. Repeat until both strategies pass 100/100/100. Do not continue until both pass.
+**If any gate fails:** fix the issue and run `/verify` again. Repeat until all gates pass.
 
-Output after passing: `✓ Lighthouse 100/100/100 desktop + mobile — writing tests...`
+Output after passing: `✓ Verified — writing tests...`
 
 ---
 
@@ -80,15 +118,13 @@ Output after passing: `✓ Tests passing — ready for review.`
 
 The Review Agent checks the code for correctness, security, accessibility, DRY violations, and adherence to the checklist. It returns a list of issues.
 
+> Note: `/verify` includes the review step (`pulse_review`) — if you ran `/verify` and it passed cleanly, the Review Agent has already run. You do not need to invoke it again separately.
+
 ---
 
 ## Phase 8 — Fix review issues
 
-Fix every issue raised by the Review Agent. If the fixes touch the spec or view:
-
-- Re-run `pulse_validate`
-- Re-run Lighthouse if visual or structural changes were made
-- Re-run tests
+Fix every issue raised by the Review Agent. If the fixes touch the spec or view, run `/verify` again — it re-runs validation, Lighthouse, the performance trace, console check, and review in one pass and writes a fresh stamp.
 
 Only declare the task done after phase 8 is complete and all gates still pass.
 
@@ -99,9 +135,9 @@ Only declare the task done after phase 8 is complete and all gates still pass.
 ```
 Phase 1  Understand          (no gate — always run)
 Phase 2  Plan                gate: user confirmation
-Phase 3  Build               (no gate — write the code)
+Phase 3  Build               announce brief → write files (no gate, but always narrate)
 Phase 4  Validate            gate: pulse_validate clean
-Phase 5  Browser             gate: Lighthouse 100/100/100 (Accessibility/Best Practices/SEO) desktop + mobile
+Phase 5  Browser             gate: Lighthouse 100/100/100 (A/BP/SEO) + CLS 0.00, desktop + mobile
 Phase 6  Tests               gate: all tests pass
 Phase 7  Review Agent        (only reached after phases 4–6 all pass)
 Phase 8  Fix + re-verify     gate: all gates still pass

package/src/cli/scaffold.js

@@ -57,8 +57,9 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}}
   write(targetDir, 'src/pages/home.js',      homePage(name))
   write(targetDir, 'src/pages/home.test.js', homePageTest(name))
 
-  // Minimal stylesheet
-  write(targetDir, 'public/app.css', baseCSS())
+  // Stylesheets — theme.css holds hex token definitions, app.css uses only var() references
+  write(targetDir, 'public/theme.css', themeCSS())
+  write(targetDir, 'public/app.css',   baseCSS())
 
   // Copy pulse-ui assets from the package into public/ so they're served immediately
   const pkgPublic = new URL('../../public', import.meta.url).pathname
@@ -95,9 +96,6 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}}
 
   // settings.json — hooks that enforce correct agent behaviour
   write(targetDir, '.claude/settings.json', JSON.stringify({
-    enabledPlugins: {
-      'frontend-design@claude-plugins-official': true,
-    },
     hooks: {
       SessionStart: [
         {
@@ -148,7 +146,7 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}}
             },
             {
               type: 'command',
-              command: `node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const f=(i.tool_input||{}).file_path||'';if(!f.endsWith('.css')){return;}const fs=require('fs');let c;try{c=fs.readFileSync(f,'utf8');}catch(e){return;}const m=c.match(/#[0-9a-fA-F]{6}|#[0-9a-fA-F]{3}/g);if(m&&m.length){const u=[...new Set(m)];process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:'PostToolUse',additionalContext:'HARDCODED HEX in '+f+': '+u.join(', ')+'. Use var(--ui-*) tokens instead — hardcoded colours break theming.'}}));}})"`,
+              command: `node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const f=(i.tool_input||{}).file_path||'';if(!f.endsWith('.css')){return;}if(f.endsWith('theme.css')){return;}const fs=require('fs');let c;try{c=fs.readFileSync(f,'utf8');}catch(e){return;}const m=c.match(/#[0-9a-fA-F]{6}|#[0-9a-fA-F]{3}/g);if(m&&m.length){const u=[...new Set(m)];process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:'PostToolUse',additionalContext:'HARDCODED HEX in '+f+': '+u.join(', ')+'. Hex values belong in public/theme.css as token definitions — '+f+' should use var(--token-name) references only.'}}));}})"`,
               statusMessage: 'Checking for hardcoded colours...',
             },
             {
@@ -226,7 +224,7 @@ export default {
   meta: {
     title:       '${appName}',
     description: '${appName} — built with Pulse.',
-    styles:      ['/pulse-ui.css', '/app.css'],
+    styles:      ['/pulse-ui.css', '/theme.css', '/app.css'],
   },
 
   state: {
@@ -313,6 +311,22 @@ test('decrement mutation subtracts 1', () => {
 `
 }
 
+function themeCSS() {
+  return `\
+/*
+ * theme.css — token definitions
+ * Hex values and raw colours live here. app.css references these via var().
+ * Override pulse-ui tokens by targeting [data-theme="light"] (higher specificity than :root).
+ */
+
+/* Example — uncomment and edit to set a custom accent colour:
+[data-theme="light"] {
+  --color-accent: #0066cc;
+}
+*/
+`
+}
+
 function baseCSS() {
   return `\
 *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
@@ -337,9 +351,10 @@ function claudeMd(appName) {
 ## Project
 
 \`\`\`
-src/pages/       ← one .js file per page, auto-discovered
-src/components/  ← shared view fragments (JS functions returning HTML strings)
-public/app.css   ← global stylesheet
+src/pages/        ← one .js file per page, auto-discovered
+src/components/   ← shared view fragments (JS functions returning HTML strings)
+public/theme.css  ← token definitions (hex values, colour overrides) — hex allowed here only
+public/app.css    ← layout and component overrides — var() references only, no hex
 \`\`\`
 
 ## Start of every session
@@ -349,18 +364,13 @@ public/app.css   ← global stylesheet
 
 The MCP guide is the single source of truth. Follow it for all technical decisions, component usage, and the mandatory verification workflow.
 
-## Design — do this before writing any HTML
-
-Before planning any new page or component, use the \`frontend-design\` plugin to establish the visual direction:
-
-1. Call the plugin's design tools with the page brief (what it does, who it's for, the tone)
-2. The plugin will return decisions — colour palette, typography, spacing scale, component variants, layout approach
-3. **Apply those decisions as CSS custom property overrides in \`public/app.css\`** — not as inline styles or class hacks
-4. Document the chosen tokens at the top of \`public/app.css\` so every page stays consistent
+## CSS and theming
 
-The plugin informs *what* to build visually. The Pulse component library is *how* you build it. Use both — the plugin gives direction, the components implement it.
+- Hex values and colour token definitions go in \`public/theme.css\` — that is the only file where hex is allowed. The hex lint hook will fire on any other CSS file.
+- \`public/app.css\` must not contain hex colour values. Use \`var(--ui-space-N)\` spacing tokens (\`--ui-space-1\` = 4px through \`--ui-space-24\` = 96px) for padding, margin, and gap. Use \`var(--ui-text-*)\` tokens (\`--ui-text-xs\` through \`--ui-text-4xl\`) for font sizes. Plain values like \`1rem\` are also fine when no token fits.
+- Load order in \`meta.styles\`: \`/pulse-ui.css\` → \`/theme.css\` → \`/app.css\`.
 
-**Do not default to stock component styles.** If the design plugin gives you a colour, use it. If it suggests a layout pattern, follow it. Every page should reflect deliberate design decisions, not the component library defaults.
+When the user asks for layout or spacing changes, apply them directly — do not ask for confirmation on small CSS tweaks. Only pause for confirmation before large structural changes (new pages, major layout reworks).
 
 ## Before writing any code
 
@@ -376,7 +386,7 @@ Run these steps in order — do not declare work done without them:
 2. \`pulse_review\` — switch into reviewer mode, read the source and rendered HTML critically, fix every issue before continuing
 3. Write tests for every page you created or changed, run \`npm test\` (all pass), then \`npm run test:coverage\` — fix any untested branches
 4. Navigate to the page in the browser and take a screenshot
-5. Run Lighthouse (desktop then mobile) — all four scores must be 100
+5. Run Lighthouse (desktop then mobile) — Accessibility, Best Practices, and SEO must all be 100
 
 ## Writing tests
 

package/src/mcp/server.js

@@ -281,19 +281,24 @@ Rules for the spec you write:
 server.registerTool(
   'pulse_create_component',
   {
-    description: `Create a reusable view component in src/components/. Components export named functions that return HTML strings.
+    description: `Register a component you have already written to disk with the Write tool.
 
-IMPORTANT rules for component content:
+Workflow — always in this order:
+1. Write the component file to src/components/<name>.js using the Write tool (user sees the diff)
+2. Call pulse_create_component with just the name to confirm it was created correctly
+
+Do NOT pass content here — write the file first, then call this tool.
+
+Rules for the component you write:
 - Import Pulse UI components from '@invisibleloop/pulse/ui' where applicable
 - Use u- utility classes for spacing/layout — never inline styles
 - Use var(--ui-*) CSS tokens for any colour references — never hardcode hex values
 - Export named functions only (no default export needed)`,
     inputSchema: {
-      name:    z.string().describe('Component name, e.g. "hero" or "nav"'),
-      content: z.string().describe('JS — export named functions that return HTML strings'),
+      name: z.string().describe('Component filename without extension, e.g. "hero" or "nav"'),
     },
   },
-  async ({ name, content }) => {
+  ({ name }) => {
     const safeName = name.replace(/\.js$/, '')
     const fullPath = path.join(COMPONENTS_DIR, `${safeName}.js`)
 
@@ -301,10 +306,15 @@ IMPORTANT rules for component content:
       return text('Error: component name must not escape src/components/')
     }
 
-    fs.mkdirSync(path.dirname(fullPath), { recursive: true })
-    fs.writeFileSync(fullPath, content, 'utf8')
+    if (!fs.existsSync(fullPath)) {
+      return text(`Error: ${path.relative(ROOT, fullPath)} does not exist — write the file with the Write tool first, then call pulse_create_component.`)
+    }
+
+    const content = fs.readFileSync(fullPath, 'utf8')
+    const exports = [...content.matchAll(/^export\s+(?:function|const|async function)\s+(\w+)/gm)].map(m => m[1])
+    const exportNote = exports.length > 0 ? `Exports: ${exports.join(', ')}` : 'Warning: no named exports found — check the file exports at least one function.'
 
-    return text(`Created ${path.relative(ROOT, fullPath)}`)
+    return text(`Registered ${path.relative(ROOT, fullPath)}\n${exportNote}`)
   }
 )
 
@@ -315,42 +325,59 @@ IMPORTANT rules for component content:
 server.registerTool(
   'pulse_create_store',
   {
-    description: `Create a pulse.store.js global store at the project root. The store defines server fetchers and client mutations that are shared across pages.
+    description: `Register a pulse.store.js global store that you have already written to disk with the Write tool.
+
+Workflow — always in this order:
+1. Write pulse.store.js to the project root using the Write tool (user sees the diff)
+2. Call pulse_create_store to validate the file you just wrote
+
+Do NOT pass content here — write the file first, then call this tool.
 
-IMPORTANT rules:
+Rules for the store you write:
 - server fetchers must be async functions: async (ctx) => value
 - mutations must be pure functions: (storeState, payload?) => partialState — no fetch, no side effects
 - hydrate is required if the store has mutations (enables client-side store mutation dispatch)
 - Register the store in your server file by passing it to createServer({ store })
 - Pages subscribe to store keys via spec.store: ['user', 'settings']`,
-    inputSchema: {
-      content: z.string().describe('Complete pulse.store.js content — must export default a valid store object'),
-    },
+    inputSchema: {},
   },
-  async ({ content }) => {
+  () => {
     const storePath = path.join(ROOT, 'pulse.store.js')
 
-    // Basic structure check before writing
+    if (!fs.existsSync(storePath)) {
+      return text('Error: pulse.store.js does not exist — write the file with the Write tool first, then call pulse_create_store.')
+    }
+
+    const content = fs.readFileSync(storePath, 'utf8')
+
     if (!content.includes('export default')) {
-      return text('Invalid: store must contain "export default { ... }"')
+      return text('Invalid: pulse.store.js must contain "export default { ... }"')
     }
 
-    fs.writeFileSync(storePath, content, 'utf8')
+    const hasServer    = content.includes('server:')
+    const hasMutations = content.includes('mutations:')
+    const hasHydrate   = content.includes('hydrate:')
 
-    return text(`Created pulse.store.js
+    const warnings = []
+    if (hasMutations && !hasHydrate) {
+      warnings.push('Warning: store has mutations but no hydrate — add hydrate: \'/pulse.store.js\' to enable client-side store dispatch.')
+    }
 
+    const lines = ['Validated pulse.store.js']
+    if (hasServer)    lines.push('  ✓ server fetchers defined')
+    if (hasMutations) lines.push('  ✓ mutations defined')
+    if (hasHydrate)   lines.push('  ✓ hydrate set')
+    if (warnings.length) lines.push('', ...warnings)
+    lines.push(`
 Next steps:
 1. Import and register it in your server file:
    import store from './pulse.store.js'
    createServer(specs, { store })
 
 2. Declare which keys each page uses:
-   export default { route: '/dashboard', store: ['user', 'settings'], ... }
-
-3. If you added mutations, set hydrate in pulse.store.js:
-   hydrate: '/pulse.store.js'
+   export default { route: '/dashboard', store: ['user', 'settings'], ... }`)
 
-Store data is available in the view as the second argument alongside page server data.`)
+    return text(lines.join('\n'))
   }
 )
 
@@ -447,9 +474,12 @@ server.registerTool(
     const proc = spawn(process.execPath, [devScript, '--root', ROOT], { detached: true, stdio: 'ignore' })
     proc.unref()
 
-    // Give it a moment to bind the port
-    await new Promise(r => setTimeout(r, 1500))
-    return text(`Dev server restarted on port ${port}`)
+    // Wait until the server is actually accepting requests
+    const ready = await waitForServer(port)
+    return text(ready
+      ? `Dev server restarted on port ${port}`
+      : `Dev server started on port ${port} (did not respond within 10 s — check for errors)`
+    )
   }
 )
 
@@ -491,11 +521,12 @@ server.registerTool(
     const proc = spawn(process.execPath, [startScript, '--root', ROOT, '--port', String(prodPort)], { detached: true, stdio: 'ignore' })
     proc.unref()
 
-    // Wait for it to bind
-    setTimeout(() => resolve(text(
-      `Production build complete. Server running at http://localhost:${prodPort}/\n` +
-      `Run Lighthouse against this URL, then call pulse_restart_server to return to dev.`
-    )), 2000)
+    // Wait until the prod server is actually accepting requests
+    waitForServer(prodPort, 15_000).then(ready => resolve(text(
+      ready
+        ? `Production build complete. Server running at http://localhost:${prodPort}/\nRun Lighthouse against this URL, then call pulse_restart_server to return to dev.`
+        : `Build complete but prod server on port ${prodPort} did not respond within 15 s — check for startup errors.`
+    )))
   })
 )
 
@@ -587,7 +618,7 @@ Work through every item. Fix anything that fails.
 
 ### Structure
 - [ ] \`route\` is set explicitly — not left to auto-discovery
-- [ ] \`hydrate\` is set if the page has mutations, actions, or persist
+- [ ] \`hydrate\` is NOT set manually — the framework injects it automatically. Remove it if present.
 - [ ] \`state\` shape is consistent — no fields that flip between null/string/boolean
 - [ ] \`meta.title\` is meaningful and unique to this page
 - [ ] \`meta.description\` is a real description, not "Built with Pulse"
@@ -636,6 +667,38 @@ Fix every issue you find. Then confirm what was changed.
   }
 )
 
+// ---------------------------------------------------------------------------
+// pulse_run_tests
+// ---------------------------------------------------------------------------
+
+server.registerTool(
+  'pulse_run_tests',
+  {
+    description: 'Run the project test suite (npm test). Returns the full output. Use after writing or editing specs to verify nothing is broken.',
+    inputSchema: {},
+  },
+  () => new Promise(resolve => {
+    const result = spawnSync('npm', ['test'], {
+      cwd:      ROOT,
+      encoding: 'utf8',
+      timeout:  120_000,
+    })
+
+    const output   = (result.stdout || '') + (result.stderr || '')
+    const exitCode = result.status ?? 1
+
+    if (exitCode === 0) {
+      // Surface just the per-suite summary lines — enough to confirm all passed
+      const summaryLines = output.split('\n').filter(l => /\d+ tests?:/.test(l) || /passed|failed/.test(l))
+      const summary = summaryLines.length ? summaryLines.join('\n') : output.slice(-2000)
+      resolve(text(`All tests passed.\n\n${summary}`))
+    } else {
+      // Return the tail of the output where failures are reported
+      resolve(text(`Tests failed (exit ${exitCode}):\n\n${output.slice(-4000)}`))
+    }
+  })
+)
+
 // ---------------------------------------------------------------------------
 // pulse_check_version
 // ---------------------------------------------------------------------------
@@ -735,6 +798,24 @@ server.registerTool(
 // Helpers
 // ---------------------------------------------------------------------------
 
+/** Poll until the HTTP server on the given port accepts a connection, or timeout. */
+async function waitForServer(port, maxMs = 10_000) {
+  const deadline = Date.now() + maxMs
+  while (Date.now() < deadline) {
+    const alive = await new Promise(resolve => {
+      const req = http.get(`http://localhost:${port}/`, { timeout: 500 }, res => {
+        res.resume()
+        resolve(true)
+      })
+      req.on('error',   () => resolve(false))
+      req.on('timeout', () => { req.destroy(); resolve(false) })
+    })
+    if (alive) return true
+    await new Promise(r => setTimeout(r, 300))
+  }
+  return false
+}
+
 async function validateContent(content) {
   // Write into PAGES_DIR so relative imports (e.g. '../components/nav.js') resolve correctly
   fs.mkdirSync(PAGES_DIR, { recursive: true })
@@ -843,9 +924,10 @@ const PULSE_GUIDE_INDEX = `# Pulse Framework Guide
 - \`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_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\` — create a reusable component.
-- \`pulse_create_store\` — create the pulse.store.js global store.
+- \`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.
 - \`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_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.**
@@ -863,32 +945,15 @@ const PULSE_GUIDE_INDEX = `# Pulse Framework Guide
 
 ## MANDATORY: Verify every build
 
-**RULE: NEVER run \`lighthouse_audit\` against the dev server. Dev mode serves unminified source files — scores are meaningless. Lighthouse MUST always run against the production build.**
-
-**Before calling any slow tool (\`pulse_build\`, \`lighthouse_audit\`), output a short status message to the user explaining what you are about to do and that it may take a moment.** Example: "Building for production — this takes ~30 s…" or "Running Lighthouse desktop audit — may take up to a minute…". Do not call the tool silently.
-
-After writing or editing any page, run ALL of the following steps in order before telling the user you are done:
-
-1. \`pulse_validate\` — validate the spec. Fix all errors and warnings before continuing.
-2. \`pulse_review\` — **switch into reviewer mode**. Read the source, rendered HTML, and checklist returned by the tool. Fix every issue found before moving on. This is mandatory — do not skip it.
-3. \`pulse_restart_server\` — only if you added a new page or changed imports.
-2. \`mcp__chrome-devtools__navigate_page\` — navigate to the dev server URL. After any CSS or asset change, follow immediately with \`mcp__chrome-devtools__evaluate_script\` running \`location.reload(true)\` to force a hard refresh.
-3. \`mcp__chrome-devtools__take_screenshot\` — check layout, spacing, content visibility, no overflow. Also check headings for orphans (a single short word stranded on the last line). To detect them programmatically, run \`mcp__chrome-devtools__evaluate_script\` with:
-   \`\`\`js
-   Array.from(document.querySelectorAll('h1,h2,h3,h4,h5,h6')).filter(h=>{const r=document.createRange();r.selectNodeContents(h);const rects=r.getClientRects();if(rects.length<2)return false;const last=rects[rects.length-1];return last.width/h.getBoundingClientRect().width<0.4;}).map(h=>h.tagName+': '+h.textContent.trim())
-   \`\`\`
-   Any heading returned has a last line shorter than 40% of its width — fix it with \`balance: true\` on the \`heading()\` component.
-4. \`mcp__chrome-devtools__list_console_messages\` (errors) — fix every JS error.
-5. \`mcp__chrome-devtools__list_network_requests\` (failed) — fix every 404 or failed fetch.
-6. \`pulse_fetch_page\` — pass the full URL e.g. \`{ url: "http://localhost:3000/" }\`. Confirm SSR renders expected content, no blank body.
-7. \`pulse_build\` — this builds for production AND starts a prod server on devPort+1. Wait for it to return the prod URL.
-8. \`mcp__chrome-devtools__navigate_page\` — navigate to the production URL returned by \`pulse_build\` (e.g. \`http://localhost:3001/\`).
-9. \`mcp__chrome-devtools__lighthouse_audit\` with \`{ "strategy": "desktop" }\` — run against the production URL. All four scores (Performance, Accessibility, Best Practices, SEO) must be 100. Report the actual scores and fix every failing audit before continuing.
-10. \`mcp__chrome-devtools__lighthouse_audit\` with \`{ "strategy": "mobile" }\` — run the same audit for mobile. All four scores must also be 100. Fix any failures before continuing.
-11. \`pulse_restart_server\` — shut down the prod server and return to dev.
-12. \`mcp__chrome-devtools__list_pages\` then \`mcp__chrome-devtools__close_page\` — close **every** page returned by \`list_pages\` to shut the browser down entirely. \`pageId\` must be a number: \`{ pageId: 2 }\` ✓ — NOT \`{ pageId: "2" }\` ✗ (string will fail). Loop through all page IDs and close each one.
-
-Do not declare success until all steps pass (step 12 is cleanup — always run it). If any step reveals a problem, fix it and repeat from step 2.
+**After writing or editing any page spec, you MUST run \`/verify\` before declaring done.**
+
+\`/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.
+
+**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.
+
+**RULE: NEVER run \`lighthouse_audit\` against the dev server.** Dev mode serves unminified source files — scores are meaningless. \`/verify\` handles this correctly by calling \`pulse_build\` first.
+
+**Before calling any slow tool (\`pulse_build\`, \`lighthouse_audit\`), output a short status message to the user.** Example: "Building for production — this takes ~30 s…". Do not call slow tools silently.
 
 ${CHECKLIST}`