@invisibleloop/pulse 0.17.1 → 0.17.3

package/src/agent/checklist.md

@@ -20,6 +20,8 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 - **Do not set `hydrate` in specs.** It is auto-derived by the framework from the URL entry passed to `createServer`. Specs with `mutations`, `actions`, or `persist` are hydrated automatically. Purely server-rendered specs get zero JavaScript — no configuration needed.
 
+- **The default theme is DARK.** When `meta.theme` is unset, the page renders with the dark palette. If the design calls for a light page, set `meta.theme: 'light'` when you **first write the spec** — do not assume light and discover dark at the screenshot, which costs an edit → restart → re-approval cycle. Declare the theme in your plan/build brief, and ask the user if the brief doesn't say.
+
 - **Always restart the server and reload the browser after every file edit — before checking the result.** The dev server restarts on file changes but the browser tab stays stale. The required sequence is: `pulse_restart_server` → `navigate_page`. Never attempt to debug a visual problem without doing both steps first.
 
 ### Components first — or creative override
@@ -111,6 +113,14 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 ### Security
 
 - Any value from user input (URL params, form fields, external APIs) interpolated into view HTML must be escaped.
+- **Every `<form method="POST">` on a `submit` page includes `${server.csrf}`.** CSRF is enforced — a form without the hidden token field gets 403 on submit. Never set `csrf: false` to "fix" a 403; that disables the protection. `csrf: false` is only for endpoints with their own authentication (e.g. signed webhooks).
+- **`submit` returns `{ redirect }` after a successful mutation** (POST-redirect-GET). Rendering success directly from the POST means browser refresh resubmits the form.
+
+### Server-side forms & error pages
+
+- **Forms that must work without JavaScript use `spec.submit`** + `<form method="POST">` with `${server.csrf}` inside. Hydrated `data-action` on the same form is the enhancement, not the requirement.
+- On a validation re-render, show `server.form?.errors` and echo `server.form?.values` back into the inputs via `value=` — failed validation must not wipe what the user typed.
+- **Every site has a custom 404 page** — a spec with `route: '*'`, using the shared `layout()` so it carries the site's nav and footer. Without it, bad URLs show the framework's unbranded default.
 
 ### Tests
 

package/src/agent/commands/verify.md

@@ -15,7 +15,7 @@ If $ARGUMENTS is provided, use it as the file path or route. Otherwise, identify
 If this is a new page build (came through `pulse_intake` or `build-page`):
 
 1. Take a screenshot and describe what you see to the user.
-2. Ask the user: "Happy with the design and layout, or would you like any changes before I run Lighthouse?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — proceed", "I'd like some changes first"]`; it waits for the answer without ending the turn. If you must ask in plain prose and end your turn, call `pulse_await_approval` first so the Stop hooks let the turn end.
+2. **Call `pulse_await_approval` first**, then ask the user: "Happy with the design and layout, or would you like any changes before I run Lighthouse?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — proceed", "I'd like some changes first"]`; otherwise ask in plain prose. Always call the tool before asking, whichever way you ask: in some hosts (including Claude Code) even a question tool ends the turn and fires the Stop hooks. The marker is harmless if the turn doesn't end — it is consumed when the user replies.
 3. **Do not proceed to step 3 until the user explicitly confirms.** If they want changes, stop here, make the changes, then restart from step 2. Lighthouse takes ~90 seconds — do not waste it on a design the user hasn't approved. If a `VERIFY REQUIRED` stop-hook block fires while your question is unanswered, that is not permission to continue — call `pulse_await_approval`, re-ask, and end your turn.
 
 ### 3. Validate the spec
@@ -46,7 +46,7 @@ The browser should still be on `http://localhost:3001/` from step 6. Run `mcp__c
 
 **Same pass bar: Accessibility, Best Practices, and SEO must all be 100.** Fix any failures and restart from step 3.
 
-After both Lighthouse runs pass, call `pulse_restart_server` to return to the dev server.
+**Stay on the production server (port 3001)** — steps 8 and 9 use it too. Do not call `pulse_restart_server` yet.
 
 ### 8. Mobile layout check
 
@@ -54,7 +54,7 @@ Emulate a mobile viewport and take a screenshot to catch wrapping, overflow, and
 
 ```
 mcp__chrome-devtools__emulate  viewport: "390x844x2,mobile,touch"
-mcp__chrome-devtools__navigate_page  url: "http://localhost:3000/"
+mcp__chrome-devtools__navigate_page  url: "http://localhost:3001/"
 mcp__chrome-devtools__take_screenshot
 ```
 
@@ -72,7 +72,9 @@ mcp__chrome-devtools__emulate  viewport: "1440x900x1"
 
 ### 9. Performance
 
-Navigate to the page route, then run `mcp__chrome-devtools__performance_start_trace` with `reload: true` and `autoStop: true`. Report LCP and CLS. Flag any LCP insight that suggests a fixable problem (render-blocking resources, large image load delay, etc.).
+**Run the trace against the production server, not dev.** Navigate to `http://localhost:3001/<route>` first — if the production server is no longer running, run `pulse_build` again. Tracing the dev server (port 3000) reports misleading LCP/CLS. Then run `mcp__chrome-devtools__performance_start_trace` with `reload: true` and `autoStop: true`. Report LCP and CLS. Flag any LCP insight that suggests a fixable problem (render-blocking resources, large image load delay, etc.).
+
+After the trace, call `pulse_restart_server` to return to the dev server.
 
 ### 10. Console errors
 

package/src/agent/guide-routing.md

@@ -126,6 +126,27 @@ Convention: name dynamic-route files [param].js inside a subfolder:
 
 This is purely a human readability convention. Pulse does not process [ ] in filenames.
 
+## Custom 404 page
+
+Create a spec with `route: '*'` — it renders through the normal pipeline (layout, styles, hydration) with status 404 whenever no route matches:
+
+```js
+// src/pages/not-found.js
+import { layout } from '../components/layout.js'
+
+export default {
+  route: '*',
+  meta:  { title: 'Page not found', styles: ['/pulse-ui.css', '/theme.css', '/app.css'] },
+  view:  () => layout({
+    content: `<h1>Page not found</h1><p>That page doesn't exist. <a href="/">Back home</a></p>`,
+  }),
+}
+```
+
+- Use the shared `layout()` so the 404 carries the site's nav and footer.
+- **Every site should have one** — without it, visitors to a bad URL get the framework's unbranded default 404.
+- 500 errors are customised via `createServer`'s `onError` option, not a spec.
+
 ## Canonical URLs
 
 Pulse auto-derives a canonical URL from every request and emits `<link rel="canonical">` in the `<head>`. No config needed in most cases.

package/src/agent/guide-server.md

@@ -102,6 +102,40 @@ actions: {
 ```
 `_storeUpdate` is stripped from local page state — it is only forwarded to the store. The rest of `onSuccess` merges into the page's own state as normal.
 
+## Server-side forms — `spec.submit` (works without client JS)
+
+A spec with a `submit` handler accepts POST on its own route. The form works with JavaScript disabled — hydrated `actions` become an enhancement, not a requirement.
+
+```js
+export default {
+  route: '/contact',
+  submit: async (ctx) => {
+    const data = await ctx.formData()
+    if (!data?.email)        return { errors: { email: 'Email is required' }, values: data ?? {} }
+    if (!isValid(data.email)) return { status: 422, errors: { email: 'Invalid email' }, values: data }
+    await sendMessage(data)
+    return { redirect: '/contact?sent=1' }   // 303 POST-redirect-GET
+  },
+  view: (state, server) => `
+    <main id="main-content">
+      ${server.form?.errors?.email ? `<p class="error">${escHtml(server.form.errors.email)}</p>` : ''}
+      <form method="POST">
+        ${server.csrf}
+        ${input({ label: 'Email', name: 'email', type: 'email', required: true, value: server.form?.values?.email ?? '' })}
+        ${button({ label: 'Send', type: 'submit' })}
+      </form>
+    </main>`,
+}
+```
+
+**Rules:**
+- `${server.csrf}` **must be inside every POST form** — CSRF protection is automatic and POSTs without a valid token are rejected with 403. Opt out with `csrf: false` only for endpoints with their own authentication (e.g. signed webhooks).
+- `{ redirect }` → 303 See Other. Always redirect after a successful mutation — rendering success directly from the POST means refresh resubmits the form.
+- Any other return value re-renders the page with it exposed as `server.form` — put `errors` and the submitted `values` there, and echo values back into inputs so failed validation doesn't wipe what the user typed. An optional `status` field sets the response status (e.g. 422).
+- Escape user-submitted values before interpolating them into HTML (`escHtml`).
+- **Progressive enhancement:** add `data-action="send"` to the same form — hydrated visitors get the async action with no page reload; no-JS visitors fall back to the POST.
+- Multi-instance deployments: pass a stable `secret` to `createServer` (e.g. from an env var) so CSRF tokens issued by one instance validate on another.
+
 ## Server context — redirects, cookies, POST bodies
 
 The `ctx` object is available in `guard`, `server.*` fetchers, and `meta` functions.

package/src/agent/guide-spec.md

@@ -16,6 +16,10 @@ export default {
     title:       'Page Title',             // string or async (ctx) => string
     description: 'Meta description',       // string or async (ctx) => string
     styles:      ['/app.css'],             // string[] or (ctx) => string[]
+    theme:       'light',                  // 'light' | 'dark' — ⚠ DEFAULT IS DARK when unset.
+                                           // Decide at write time: a light design needs
+                                           // meta.theme: 'light' or the page renders dark.
+    vibe:        'minimal',                // optional — radius/weight/spacing preset
     ogTitle:     'Social title',           // optional — falls back to title
     ogImage:     'https://…/og.jpg',       // optional — 1200×630 recommended
     canonical:   'https://mysite.com/…',  // optional — string or (ctx) => string
@@ -42,10 +46,31 @@ export default {
     // Resolved server-side before render. Passed to view() as second arg.
     posts: async () => fetchPostsFromDb(),
   },
+  // Server-side form handling — POST works with JavaScript disabled.
+  // { redirect } → 303 PRG; anything else → re-render with the value as server.form.
+  // CSRF enforced automatically: the view MUST include ${server.csrf} inside the <form>.
+  submit: async (ctx) => {
+    const data = await ctx.formData()
+    if (!data?.email) return { errors: { email: 'Required' }, values: data ?? {} }
+    await save(data)
+    return { redirect: '/thanks' }
+  },
   view: (state, serverState) => `<h1>${state.title}</h1>`,
 }
 ```
 
+## Server-side forms (`submit`)
+
+- A spec with `submit` accepts POST on its own route — plain `<form method="POST">`, no client JS needed.
+- **Always put `${server.csrf}` inside the form** — it renders the hidden CSRF input. POSTs without a valid token are rejected with 403. (`csrf: false` opts out — only for endpoints with their own auth.)
+- `server.form` holds the return value of `submit()` on a re-render: show `server.form?.errors`, echo `server.form?.values` back into inputs via `value=` so failed validation doesn't wipe the form.
+- After a successful mutation always `return { redirect: '/path' }` (POST-redirect-GET) — never render success from the POST itself. An optional `status` field on a re-render return sets the response status (e.g. 422).
+- Progressive enhancement: the same form can also have `data-action="name"` — hydrated visitors get the async action, no-JS visitors use the POST.
+
+## Custom not-found page
+
+A spec with `route: '*'` renders with **status 404** whenever no route matches — same pipeline as any page (layout, styles, hydration, validation). Every site should have one; the default framework 404 is unbranded.
+
 ## Streaming SSR — shell + deferred segments
 
 Use streaming when a page has slow data and you want the shell to paint instantly while slower content streams in.

package/src/agent/guide-styles.md

@@ -199,6 +199,8 @@ The default CSP does **not** restrict `img-src` — it inherits `default-src 'se
 
 **Do this at build time, before writing any image tags.** If you know you'll use external images, add the CSP entry to `pulse.config.js` first — discovering the block at Lighthouse time costs an extra round-trip.
 
+**Use `pulse_check_csp` to get the origin list right first time.** Many hosts redirect to a CDN origin (picsum.photos → fastly.picsum.photos), and allowing only the URL you wrote still blocks the actual bytes. Pass it the URLs you plan to use and it follows each redirect chain and returns ready-to-paste CSP config with every origin included.
+
 ```js
 // pulse.config.js
 export default {
@@ -213,7 +215,7 @@ Or via `createServer`:
 ```js
 createServer(specs, {
   csp: {
-    'img-src': ['https://images.unsplash.com', 'https://picsum.photos'],
+    'img-src': ['https://images.unsplash.com', 'https://picsum.photos', 'https://fastly.picsum.photos'],
   },
 })
 ```

package/src/agent/skills/build-page/SKILL.md

@@ -53,7 +53,7 @@ Check for:
 - Layout looks correct
 - No console errors via list_console_messages
 
-Then ask the user: *"Happy with the design and layout, or would you like any changes before I run tests and Lighthouse?"* — use your host's question tool if it has one (e.g. AskUserQuestion); it waits for the answer without ending the turn. If you must ask in plain prose and end your turn, call `pulse_await_approval` first so the Stop hooks let the turn end. **Do not proceed until the user explicitly approves.** If a `VERIFY REQUIRED` stop-hook block fires while your question is unanswered, that is not permission to continue — call `pulse_await_approval`, re-ask, and end your turn.
+Then **call `pulse_await_approval`** and ask the user: *"Happy with the design and layout, or would you like any changes before I run tests and Lighthouse?"* Always call the tool before asking, even when using a question tool like AskUserQuestion — in some hosts (including Claude Code) the question still ends the turn and fires the Stop hooks; the marker is harmless if the turn doesn't end. **Do not proceed until the user explicitly approves.** If a `VERIFY REQUIRED` stop-hook block fires while your question is unanswered, that is not permission to continue — call `pulse_await_approval`, re-ask, and end your turn.
 
 ### 7. Lighthouse
 

package/src/agent/skills/verify/SKILL.md

@@ -34,7 +34,7 @@ Navigate to the page route with `mcp__chrome-devtools__navigate_page`, then take
 **If `pulse_intake` ran earlier in this session** (i.e. this is a new page or site, not an edit or bug fix):
 
 1. Show the screenshot to the user.
-2. Ask: *"Happy with the layout and direction, or any changes before I run Lighthouse?"* — use your host's question tool if it has one (e.g. AskUserQuestion); it waits for the answer without ending the turn. If you must ask in plain prose and end your turn, call `pulse_await_approval` first so the Stop hooks let the turn end.
+2. **Call `pulse_await_approval` first, then ask:** *"Happy with the layout and direction, or any changes before I run Lighthouse?"* Always call the tool before asking, even when using a question tool like AskUserQuestion — in some hosts (including Claude Code) the question still ends the turn and fires the Stop hooks. The marker is harmless if the turn doesn't end; it is consumed when the user replies.
 3. **Stop and wait for their response.** Do not proceed to step 4b or Lighthouse until the user explicitly approves. If a `VERIFY REQUIRED` stop-hook block fires while your question is unanswered, that is not permission to continue — call `pulse_await_approval`, re-ask, and end your turn.
 
 If the user requests changes: make edits, restart the server, take a new screenshot, describe what changed, ask again. Repeat until approved. No Lighthouse between design rounds.
@@ -67,7 +67,7 @@ Run `mcp__chrome-devtools__lighthouse_audit` with `device: "mobile"` against the
 
 ### 8. Performance
 
-Navigate to the page route, then run `mcp__chrome-devtools__performance_start_trace` with `reload: true` and `autoStop: true`. Report LCP and CLS as a single line, e.g. `LCP 73ms · CLS 0.00`. Flag any insight that identifies a fixable cause (render-blocking resources, large image delay). CLS must be 0.00.
+**Stay on the production server (port 3001) for the trace** — navigate to `http://localhost:3001/<route>` first; tracing the dev server (port 3000) reports misleading LCP/CLS. Then run `mcp__chrome-devtools__performance_start_trace` with `reload: true` and `autoStop: true`. Report LCP and CLS as a single line, e.g. `LCP 73ms · CLS 0.00`. Flag any insight that identifies a fixable cause (render-blocking resources, large image delay). CLS must be 0.00.
 
 ### 9. Console errors
 

package/src/agent/workflow.md

@@ -32,7 +32,7 @@ For any **new page, landing page, or branded site**, run the intake sequence fir
 
 - **Step 0 — Ask for inspiration first (mandatory):** Before calling any tool or presenting any plan, ask the user: *"Do you have any design inspiration — a site you love, a screenshot, or a mood board image? Drop images into `public/intake/` or paste a URL and I'll extract the design intent before we start."* Wait for the answer. Do not skip this question, even if the user's brief already seems detailed. Check `public/intake/` for any images already dropped there.
 - **`pulse_extract_inspiration`** — call this after step 0 if the user supplies a URL, site name, or image they like. Also call it for any images already present in `public/intake/`. Gives you a structured extraction template: visit the URL or analyse the image with your vision tools, extract colours, layout, typography, and feel, then feed those findings into pulse_intake. If the user explicitly says they have no reference, skip this step.
-- **`pulse_intake`** — captures the real content (name, pitch, features, palette, vibe, what it should NOT look like). Returns a brief with copy-ready content and early contrast warnings. Always ask the user one question at a time — never multi-choice for open-ended questions.
+- **`pulse_intake`** — captures the real content (name, pitch, features, palette, theme, vibe, what it should NOT look like). Returns a brief with copy-ready content and early contrast warnings. Always ask the user one question at a time — never multi-choice for open-ended questions. **Always ask light or dark** — Pulse renders dark when `meta.theme` is unset, so an unstated light design ships dark.
 - **`pulse_sketch`** — generates 3 structurally distinct layout directions (full-bleed, asymmetric split, typography-only, editorial, dense grid, story scroll, content-first). **Call this before writing any code.** Prevents defaulting to centred hero + three-column features every time.
 - **Skip `pulse_sketch` only** when the vibe is `corporate` or `minimal` AND the user hasn't expressed any structural preference. For `playful`, `bold`, `brutalist`, `retro`, or `neon` vibes, `pulse_sketch` is mandatory — templates have default section orders that actively fight these vibes.
 - **`pulse_intent`** — maps the chosen direction to a spec scaffold and tells you which guides to read.
@@ -70,6 +70,7 @@ Do not fetch every guide section for every task. Fetch what you need.
 Decide the complexity tier (see below) and confirm with the user if the task is non-trivial. Output a concise plan:
 
 - Route, state shape, mutations/actions, server fetchers
+- **Theme: light or dark** — Pulse defaults to **dark** when `meta.theme` is unset. Decide now (ask the user if the brief doesn't say) — discovering a wrong theme at the screenshot costs a full edit → restart → re-approval cycle.
 - Which UI components you will use
 - Files you will create or modify
 
@@ -179,6 +180,7 @@ Before writing any file, output a build brief:
 ```
 Building:   <page name> (<route>)
 Mode:       A — components first | B — creative override (raw HTML, reason: ...)
+Theme:      light | dark (+ vibe, if any) — default is DARK when meta.theme is unset
 State:      <fields and types, or "none">
 Mutations:  <list, or "none">
 Actions:    <list with brief description, or "none">
@@ -242,8 +244,8 @@ Do this before every screenshot, console check, or visual inspection. Never debu
 
 **How to wait without tripping the Stop hooks.** The project's Stop hooks (missing tests, coverage, verify stamp) block any turn that ends with unverified spec edits — they cannot tell "abandoning the work" from "pausing for the user's answer". So:
 
-- **Preferred:** ask the question with your host's question tool (e.g. AskUserQuestion in Claude Code). A question tool waits for the answer *without ending the turn*, so the Stop hooks never fire.
-- **Otherwise:** call `pulse_await_approval` immediately before asking in plain prose and ending your turn. It writes a one-turn marker the Stop hooks respect; the marker is consumed when the user replies.
+- **Always call `pulse_await_approval` immediately before asking** — regardless of whether you ask via a question tool or in plain prose. In some hosts (including Claude Code) even AskUserQuestion ends the turn and fires the Stop hooks. The marker is harmless if the turn doesn't end: it is simply consumed when the user replies.
+- Then ask the question (question tool with choices where available, plain prose otherwise) and end your turn.
 - **Never** respond to a `VERIFY REQUIRED` block by running `/verify` while your approval question is unanswered. The block does not override the approval gate — an unanswered question means the design is not approved, and Lighthouse on an unapproved design wastes ~90 seconds and pre-empts the user's changes.
 
 **If the user requests changes:**
@@ -274,6 +276,16 @@ Do this before every screenshot, console check, or visual inspection. Never debu
 2. `pulse_layout_review <url>` — 390/768/1280px overflow, broken images, collapsed sections
 3. `/verify` — Lighthouse desktop + mobile (100/100/100) + CLS 0.00 + `pulse_review`
 
+**Two different reviews — don't confuse them.** `pulse_design_review` is the *visual* review (7 signals) and runs **before** Lighthouse. `pulse_review` is the *code* review and runs **after** Lighthouse, always last. The canonical end-to-end order is:
+
+```
+pulse_validate → design approval → pulse_design_review → pulse_layout_review
+  → pulse_build → Lighthouse desktop + mobile → performance trace
+  → pulse_review → pulse_stamp
+```
+
+If a step's fixes touch the spec, re-run from `pulse_validate` — never re-run `pulse_review` on code that hasn't re-passed Lighthouse.
+
 **Do not report the page as done until `/verify` writes the `.pulse-verified` stamp.** Skipping Lighthouse means broken contrast, missing landmarks, and Best Practices failures ship to the user.
 
 Pass gates:

package/src/mcp/mcp.test.js

@@ -261,7 +261,61 @@ test('approval pause mechanism is wired end to end', () => {
 
   // 5. The workflow must teach the mechanism at the design-approval gate
   assert(workflow.includes('pulse_await_approval'),
-    'workflow.md Phase 5a must explain how to pause: host question tool preferred, pulse_await_approval otherwise')
+    'workflow.md Phase 5a must explain how to pause: always pulse_await_approval before asking')
+
+  // 6. No doc may claim a host question tool avoids ending the turn — field
+  //    testing showed AskUserQuestion in Claude Code still ends the turn and
+  //    fires the Stop hooks. The safe instruction is: always write the marker
+  //    first, regardless of how the question is asked.
+  const claimDocs = agentDocs.filter(f =>
+    fs.existsSync(path.join(ROOT, f)) &&
+    /without ending the turn/i.test(fs.readFileSync(path.join(ROOT, f), 'utf8'))
+  )
+  if (/without ending the turn.*Stop hooks never fire/is.test(serverSrc)) claimDocs.push('src/mcp/server.js')
+  assert(claimDocs.length === 0,
+    `These docs claim a question tool avoids ending the turn (empirically false in Claude Code): ${claimDocs.join(', ')}. ` +
+    `Instruct: always call pulse_await_approval before asking, whichever way the question is asked.`)
+})
+
+test('pulse_check_contrast extracts variables from [data-theme="light"] blocks', () => {
+  // Regression: the light-theme block pattern was an ungrouped alternation
+  // (a|b) + '\\s*\\{([^}]+)\\}' — the body matcher bound only to the second
+  // alternative, so [data-theme="light"] blocks matched with no body capture
+  // and the checker silently reported nothing for the light theme.
+  // Recreate extractVars with the exact pattern strings from server.js source.
+  const patterns = [...serverSrc.matchAll(/extractVars\(source,\s*'((?:[^'\\]|\\.)*)'\)/g)].map(m =>
+    m[1].replace(/\\\\/g, '\\').replace(/\\'/g, "'")
+  )
+  assert(patterns.length === 2, `Expected 2 extractVars call patterns in server.js, found ${patterns.length}`)
+  const lightPattern = patterns.find(p => p.includes('data-theme'))
+  assert(lightPattern, 'No data-theme pattern found in extractVars calls')
+
+  const sampleCss = `:root { --accent: #112233; }\n[data-theme="light"] { --accent: #445566; --bg: #ffffff; }`
+  const blockRegex = new RegExp(lightPattern + '\\s*\\{([^}]+)\\}', 'gi')
+  const m = blockRegex.exec(sampleCss)
+  assert(m && m[1] && m[1].includes('--accent'),
+    `The light-theme block pattern in pulse_check_contrast fails to capture the block body. ` +
+    `Pattern: ${lightPattern} — alternations must be wrapped in (?:...).`)
+})
+
+test('dark theme default is declared at every spec-writing entry point', () => {
+  // Agents repeatedly assumed the default theme is light, built the page, then
+  // discovered dark at the screenshot — costing an edit → restart → re-approval
+  // cycle. The dark default must be stated wherever a spec is first written:
+  // the spec skeleton, the plan/build brief, and the checklist.
+  const guideSpec = fs.readFileSync(path.join(agentDir, 'guide-spec.md'), 'utf8')
+  const workflow  = fs.readFileSync(path.join(agentDir, 'workflow.md'), 'utf8')
+  const checklist = fs.readFileSync(path.join(agentDir, 'checklist.md'), 'utf8')
+  const claudeMd  = fs.readFileSync(path.join(ROOT, 'CLAUDE.md'), 'utf8')
+
+  assert(/theme:/.test(guideSpec) && /DEFAULT IS DARK/i.test(guideSpec),
+    'guide-spec.md meta skeleton must include the theme field with the dark-default warning')
+  assert(/Theme:\s+light \| dark/.test(workflow),
+    'workflow.md build brief template must include a Theme line')
+  assert(/default theme is DARK/i.test(checklist),
+    'checklist.md Critical section must state the dark default')
+  assert(/theme:\s+'light'/.test(claudeMd) && /default is DARK/i.test(claudeMd),
+    'CLAUDE.md spec meta block must show theme with the dark-default warning')
 })
 
 test('identity.md declares the creative override (Design Freedom) carve-out', () => {

package/src/mcp/server.js

@@ -1210,11 +1210,11 @@ 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 ending your turn with a blocking question (e.g. the design-approval gate: "Happy with the layout and direction…?").
+    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…?").
 
-It writes a .pulse-awaiting-approval marker that tells the Stop hooks (missing tests, coverage, verify stamp) to let this one 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.
+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.
 
-**Prefer your host's question tool if it has one** (e.g. AskUserQuestion in Claude Code): a question tool waits for the answer *without ending the turn*, so the Stop hooks never fire and this marker is unnecessary. Use pulse_await_approval only when you must ask in plain prose and end the turn.
+**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.
 
 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.`,
     inputSchema: {},
@@ -2099,6 +2099,7 @@ Returns observations grouped by category: completeness, data flow, components, s
       if (!content.includes('title:'))       quickWins.push('`meta.title` is missing — every page needs a unique title.')
       if (!content.includes('description:')) quickWins.push('`meta.description` is missing — used for SEO and social previews.')
       if (!content.includes('styles:'))      quickWins.push('`meta.styles` not set — add `[\'/pulse-ui.css\']` if you are using any UI components.')
+      if (!content.includes('theme:'))       quickWins.push('`meta.theme` not set — Pulse renders DARK by default. If this design is light, add `theme: \'light\'` now rather than discovering a dark page at the screenshot.')
     }
 
     // --- Export ---
@@ -2432,7 +2433,7 @@ Accepts antiStyle ("what should this NOT look like?") and inspiration (a site or
       targetUser: z.string().optional().describe('Who this is for — shapes copy tone. E.g. "busy professionals", "indie developers", "home cooks"'),
       palette:    z.string().optional().describe('Brand colours as hex values, comma-separated. E.g. "#6366f1, #f8fafc, #1e1b4b". Used for early contrast check.'),
       font:       z.string().optional().describe('Brand font name, or omit for system-ui'),
-      theme:      z.enum(['light', 'dark']).optional().describe('Colour theme preference'),
+      theme:      z.enum(['light', 'dark']).optional().describe('Colour theme — ALWAYS ask the user for this; Pulse renders DARK when meta.theme is unset, so an unstated light design ships dark and costs a rework cycle. Pass the answer through to meta.theme in the spec.'),
       vibe:       z.enum(['warm', 'editorial', 'playful', 'minimal', 'bold', 'brutalist', 'retro', 'corporate', 'neon', 'paper']).optional().describe('Visual personality — see pulse://guide/design-references for full descriptions. warm (rounded, inviting), editorial (serif, sharp), playful (very rounded), minimal (clean), bold (impact headings), brutalist (zero radius, raw), retro (slab serif, nostalgic), corporate (conservative), neon (monospace, futuristic), paper (organic, serif, journal)'),
       styleNotes: z.string().optional().describe('Free-form style direction — e.g. "like a print poster", "market stall chalkboard feel", "clinical and professional"'),
       antiStyle:  z.string().optional().describe('"What should this NOT look like?" — negative aesthetic constraint. E.g. "not corporate SaaS", "not another Vercel dark card page", "not a startup landing page". Used to steer component and layout choices away from over-used patterns.'),
@@ -2997,6 +2998,78 @@ Returns tokens grouped by category.`,
   }
 )
 
+server.registerTool(
+  'pulse_check_csp',
+  {
+    description: `Resolve the redirect chains of external asset URLs (images, fonts, stylesheets) and return the complete set of origins your CSP must allow — as ready-to-paste config.
+
+Many asset hosts redirect to a CDN origin (picsum.photos → fastly.picsum.photos): allowing only the URL you wrote still blocks the actual bytes, and the browser error names the CDN origin, which is confusing to debug. This tool follows each redirect chain (up to 5 hops) and reports every origin involved.
+
+Call it with the external URLs you plan to use, before your first Lighthouse run. Suggested directive: img-src for images, font-src for font files, style-src for stylesheets.`,
+    inputSchema: {
+      urls:      z.array(z.string()).describe('External asset URLs to check, e.g. ["https://picsum.photos/id/10/1200/600"]'),
+      directive: z.string().optional().describe("CSP directive these assets belong to (default: 'img-src')"),
+    },
+  },
+  async ({ urls, directive = 'img-src' }) => {
+    const MAX_HOPS = 5
+    const origins  = new Set()
+    const lines    = []
+
+    for (const rawUrl of urls.slice(0, 10)) {
+      let url
+      try { url = new URL(rawUrl) } catch { lines.push(`✗ ${rawUrl} — not a valid URL`); continue }
+
+      const chain = [url.origin]
+      let blocked = null
+      try {
+        for (let hop = 0; hop < MAX_HOPS; hop++) {
+          const res = await fetch(url, { method: 'HEAD', redirect: 'manual', signal: AbortSignal.timeout(5000) })
+          if (res.status >= 300 && res.status < 400 && res.headers.get('location')) {
+            url = new URL(res.headers.get('location'), url)
+            chain.push(url.origin)
+            continue
+          }
+          if (res.status === 405) {
+            // Host rejects HEAD — confirm with a ranged GET so we still see redirects
+            const get = await fetch(url, { method: 'GET', redirect: 'manual', headers: { Range: 'bytes=0-0' }, signal: AbortSignal.timeout(5000) })
+            if (get.status >= 300 && get.status < 400 && get.headers.get('location')) {
+              url = new URL(get.headers.get('location'), url)
+              chain.push(url.origin)
+              continue
+            }
+          }
+          break
+        }
+      } catch (err) {
+        blocked = err?.name === 'TimeoutError' ? 'timed out' : (err?.message || 'request failed')
+      }
+
+      const uniqueChain = [...new Set(chain)]
+      for (const o of uniqueChain) origins.add(o)
+      lines.push(
+        blocked
+          ? `⚠ ${rawUrl} — ${blocked}; allowing origin from the URL only: ${uniqueChain.join(' → ')}`
+          : uniqueChain.length > 1
+            ? `↪ ${rawUrl} — redirects: ${uniqueChain.join(' → ')} (allow ALL of these)`
+            : `✓ ${rawUrl} — no redirect, origin: ${uniqueChain[0]}`
+      )
+    }
+
+    const config = [...origins].map(o => `'${o}'`).join(', ')
+    lines.push('')
+    lines.push('Ready to paste:')
+    lines.push('```js')
+    lines.push(`csp: {`)
+    lines.push(`  '${directive}': [${[...origins].map(o => `'${o}'`).join(', ')}],`)
+    lines.push(`}`)
+    lines.push('```')
+    if (config.includes('http://')) lines.push('⚠ An origin resolved to plain http: — use https URLs in production.')
+
+    return text(lines.join('\n'))
+  }
+)
+
 server.registerTool(
   'pulse_check_contrast',
   {
@@ -3036,8 +3109,12 @@ Run this immediately after writing a theme file — before production build and
       return vars
     }
 
+    // NOTE: alternations must be wrapped in a non-capturing group. An ungrouped
+    // pattern (a|b) followed by '\\s*\\{...' binds the body matcher to the second
+    // alternative only — [data-theme="light"] blocks then match the selector
+    // alone with no body capture, silently returning zero variables.
     const rootVars  = extractVars(source, ':root')
-    const lightVars = extractVars(source, '\\[data-theme=["\']light["\']\\]|[.]ui-theme-light')
+    const lightVars = extractVars(source, '(?:\\[data-theme=["\']light["\']\\]|[.]ui-theme-light)')
 
     // pulse-ui.css maps --NAME → --ui-NAME (e.g. --accent → --ui-accent).
     // Theme files written per the guide define bare --* tokens. Synthesize the

package/src/runtime/ssr.js

@@ -36,7 +36,7 @@ export async function renderToString(spec, ctx = {}, pageState = {}) {
   const serverState = await resolveServerState(spec, ctx)
 
   // Merge declared store keys into server state — store keys lose to page-level keys
-  const mergedServerState = mergeStoreKeys(spec, serverState, ctx.store)
+  const mergedServerState = applyCtxExtras(mergeStoreKeys(spec, serverState, ctx.store), ctx)
 
   const tData = performance.now()
 
@@ -105,7 +105,7 @@ export function renderToStream(spec, ctx = {}, nonce = '') {
 
       // Await only the fetchers the shell segments need
       const shellServerState = await awaitFetchersForSegments(spec, shell, fetcherCache)
-      const mergedShellState = mergeStoreKeys(spec, shellServerState, ctx.store)
+      const mergedShellState = applyCtxExtras(mergeStoreKeys(spec, shellServerState, ctx.store), ctx)
 
       // Write shell immediately — deferred fetchers may still be in-flight
       const shellHtml = renderNamedSegments(spec, shell, clientState, mergedShellState)
@@ -122,7 +122,7 @@ export function renderToStream(spec, ctx = {}, nonce = '') {
         // Promise.all runs them concurrently — the fastest segment wins.
         await Promise.all(deferred.map(async (key) => {
           const segServerState = await awaitFetchersForSegments(spec, [key], fetcherCache)
-          const mergedSegState = mergeStoreKeys(spec, segServerState, ctx.store)
+          const mergedSegState = applyCtxExtras(mergeStoreKeys(spec, segServerState, ctx.store), ctx)
           const segHtml        = renderNamedSegments(spec, [key], clientState, mergedSegState)
 
           // Inline script replaces the placeholder with the rendered content
@@ -145,7 +145,7 @@ export function renderToStream(spec, ctx = {}, nonce = '') {
       const allServerState = fetcherCache.size > 0
         ? Object.fromEntries(await Promise.all([...fetcherCache.entries()].map(async ([k, p]) => [k, await p])))
         : {}
-      const mergedAllState = mergeStoreKeys(spec, allServerState, ctx.store)
+      const mergedAllState = applyCtxExtras(mergeStoreKeys(spec, allServerState, ctx.store), ctx)
       if (spec.hydrate && Object.keys(mergedAllState).length > 0) {
         controller.enqueue(encode(
           `<script nonce="${nonce}">window.__PULSE_SERVER__ = ${JSON.stringify(mergedAllState)};</script>`
@@ -218,7 +218,7 @@ export function renderToNavStream(spec, ctx = {}, resolvedMeta = {}) {
 
       // 2. Await shell fetchers then send shell HTML
       const shellServerState = await awaitFetchersForSegments(spec, shell, fetcherCache)
-      const mergedShellState = mergeStoreKeys(spec, shellServerState, ctx.store)
+      const mergedShellState = applyCtxExtras(mergeStoreKeys(spec, shellServerState, ctx.store), ctx)
       let shellHtml = renderNamedSegments(spec, shell, clientState, mergedShellState)
 
       // Append <pulse-deferred> placeholders so the client knows where to inject deferred content
@@ -231,7 +231,7 @@ export function renderToNavStream(spec, ctx = {}, resolvedMeta = {}) {
       // 3. Stream each deferred segment as soon as its own fetchers resolve
       await Promise.all(deferred.map(async (key) => {
         const segServerState = await awaitFetchersForSegments(spec, [key], fetcherCache)
-        const mergedSegState = mergeStoreKeys(spec, segServerState, ctx.store)
+        const mergedSegState = applyCtxExtras(mergeStoreKeys(spec, segServerState, ctx.store), ctx)
         const segHtml        = renderNamedSegments(spec, [key], clientState, mergedSegState)
         writeLine({ type: 'deferred', id: key, html: segHtml })
       }))
@@ -240,7 +240,7 @@ export function renderToNavStream(spec, ctx = {}, resolvedMeta = {}) {
       const allServerState = fetcherCache.size > 0
         ? Object.fromEntries(await Promise.all([...fetcherCache.entries()].map(async ([k, p]) => [k, await p])))
         : {}
-      const mergedAll = mergeStoreKeys(spec, allServerState, ctx.store)
+      const mergedAll = applyCtxExtras(mergeStoreKeys(spec, allServerState, ctx.store), ctx)
 
       writeLine({
         type:        'done',
@@ -426,6 +426,29 @@ function mergeStoreKeys(spec, serverState, storeState) {
   return { ...slice, ...serverState }
 }
 
+/**
+ * Merge per-request extras set by the server into the view's server state:
+ *
+ *   ctx._form      → serverState.form  — the return value of spec.submit() on a
+ *                    POST re-render (validation errors, submitted values, etc.)
+ *   ctx._csrfField → serverState.csrf  — ready-to-embed hidden <input> for CSRF;
+ *                    views include it inside <form method="POST"> as ${server.csrf}
+ *
+ * Only set by the server for specs that declare `submit` — other pages see
+ * neither key. Explicit server fetcher keys with the same names win.
+ *
+ * @param {Object} serverState
+ * @param {Object} ctx
+ * @returns {Object}
+ */
+function applyCtxExtras(serverState, ctx) {
+  if (ctx?._form === undefined && ctx?._csrfField === undefined) return serverState
+  const extras = {}
+  if (ctx._form      !== undefined) extras.form = ctx._form
+  if (ctx._csrfField !== undefined) extras.csrf = ctx._csrfField
+  return { ...extras, ...serverState }
+}
+
 // ---------------------------------------------------------------------------
 // Internal — server state resolution
 // ---------------------------------------------------------------------------