@invisibleloop/pulse 0.16.0 → 0.17.0

package/.claude/commands/build-page.md

@@ -50,7 +50,7 @@ Check for:
 - Layout looks correct
 - No console errors via `mcp__chrome-devtools__list_console_messages`
 
-Then use `ask_user` to ask: "Happy with the design and layout, or would you like any changes before I run tests and Lighthouse?" with choices: `["Yes, looks good — run tests and Lighthouse", "I'd like some changes first"]`
+Then ask the user: "Happy with the design and layout, or would you like any changes before I run tests and Lighthouse?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — run tests and Lighthouse", "I'd like some changes first"]`; otherwise ask in plain prose.
 
 **Do not proceed to step 7 until the user explicitly confirms.** If they want changes, make them and return to step 6.
 

package/.claude/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. Use `ask_user` to ask: "Happy with the design and layout, or would you like any changes before I run Lighthouse?" — provide choices: `["Yes, looks good — proceed", "I'd like some changes first"]`
+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"]`; otherwise ask in plain prose.
 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.
 
 ### 3. Validate the spec

package/.claude/pulse-checklist.md

@@ -22,10 +22,10 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 - **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
+### Components first — or creative override
 
 - **Before writing any HTML by hand, check `src/ui/index.js`.** There are 50+ components. Use `button`, `card`, `alert`, `input`, `spinner`, `badge`, `modal`, `nav`, `pagination`, `table`, etc. before writing equivalent HTML from scratch.
-- **Do not reinvent component patterns.** These patterns have dedicated components — never write custom HTML for them:
+- **Do not reinvent component patterns.** These patterns have dedicated components — never write custom HTML for them unless a creative override applies (see below):
   - Hero sections → `hero({ title, subtitle, actions, image, ... })`
   - Product/service cards → `card({ title, body, image, footer, ... })`
   - Image + text two-column layouts → `media({ image, content, reverse })`
@@ -35,10 +35,16 @@ Before finishing any spec, verify every point below. Fix anything that fails.
   - CTAs → `cta({ title, subtitle, actions })`
   - Navigation → `nav({ logo, links, actions })`
   - Footers → `footer({ logo, links, columns, legal, ... })`
-  
-  If you find yourself writing `class="hero"` or `class="product-card"` or `class="testimonial"`, stop — import the component instead.
 
-- **Exception — brutalist, editorial, and playful vibes:** these vibes intentionally break from polished templates. `pulse://guide/explore` explicitly endorses zone-based raw HTML for distinctive layouts. For `brutalist`, `editorial`, `retro`, or `neon` vibes, raw structural HTML is correct — components can still be used for functional atoms (`button`, `input`, `modal`) but structural sections do not need to come from components. When reviewing a brutalist or editorial spec, do not flag raw section HTML as a violation.
+- **Creative override — raw HTML throughout is permitted** when the design intent genuinely calls for it: a highly custom visual identity, an asymmetric or typographically-driven layout, a brutalist/editorial/retro/neon/paper vibe where components would constrain the expression, or a layout that requires features a component simply doesn't support (e.g. full-viewport height, custom gradient glows, clamp-scaled display type). This is a deliberate design decision, not a shortcut. When taking this path:
+  - **Declare it in a comment at the top of the spec** so the reviewer recognises it: `// component-free — creative override: <reason>`. This is the signal the review tool reads.
+  - Functional atoms (`button`, `input`, `badge`, `modal`) should still come from components unless there is a specific design reason not to.
+  - `/pulse-ui.css` is always required — it provides the token system your custom CSS will use.
+  - The quality gate replaces the component checklist: **Lighthouse 100 on Accessibility, Best Practices, and SEO — desktop and mobile — plus CLS 0.00 is the pass bar.** (Performance is reported but not gated; it varies with machine load.) A component-free page that passes every audit is correct. A component-heavy page that fails accessibility is not.
+
+- **When reviewing**: before flagging a class name like `.hero` as a violation, first ask whether the `hero()` component could actually reproduce the layout. If the answer is no, it is a creative override — check Lighthouse instead of refactoring. Do not flatten a good custom layout into a generic component just to clear a pattern-match.
+
+- **The review tool auto-detects creative override** from the spec comment. When detected, component pattern checks are shown as advisory (`⚡`) not as failures, and the Lighthouse gate is the stated pass bar.
 
 - **Never write App Store or Google Play download buttons by hand.** Always use `appBadge({ store: 'apple', href })` and `appBadge({ store: 'google', href })`. Raw `<a>` tags with badge images are incorrect — `appBadge` renders the correct accessible, styled badge for each store.
 
@@ -132,12 +138,6 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 - **Call the same `md()` fetcher in both `meta` and `server`** — it caches on `ctx._mdCache` so the file is only read once per request. Do not create two separate fetchers for the same file.
 - **Always add `onViewError` on dynamic markdown routes** (routes with `:param` segments loading `.md` files). A missing file throws `{ status: 404 }` which must be caught gracefully.
 
-### Markdown
-
-- **Use `md()` from `@invisibleloop/pulse/md` for `.md` file content.** Never read and parse markdown manually. Pass the result's `html` to `prose()`.
-- **Call the same `md()` fetcher in both `meta` and `server`** — it caches on `ctx._mdCache` so the file is only read once per request. Do not create two separate fetchers for the same file.
-- **Always add `onViewError` on dynamic markdown routes** (routes with `:param` segments loading `.md` files). A missing file throws `{ status: 404 }` which must be caught gracefully.
-
 ### View error handling
 
 - **Define `onViewError` on any page where the view could throw due to bad or missing data.** Without it, a runtime view error returns a 500 on the server and shows a generic inline message on the client. With it, the server returns 200 with your fallback HTML instead of a 500, and the client renders your fallback:

package/CLAUDE.md

@@ -5,7 +5,7 @@ Pulse is a spec-first frontend framework. The spec is the source of truth. No co
 ## Commands
 
 ```bash
-npm run dev    # start dev server at http://localhost:3001
+npm run dev    # start dev server at http://localhost:3000 (pulse_build serves production on 3001)
 npm test       # run all 92 unit tests
 npm run build  # bundle for production → public/dist/
 ```
@@ -57,6 +57,12 @@ export const mySpec = {
   // Timeout for all server fetchers on this page (ms). Overrides createServer fetcherTimeout.
   serverTimeout: 5000,
 
+  // Query-string keys that change this page's output, for the in-process page cache.
+  // The cache IGNORES the query string by default — arbitrary ?n=… params cannot mint
+  // unbounded cache entries (memory-DoS guard). If the rendered output depends on a
+  // query param, list it here so distinct values get distinct cache entries.
+  cacheVary: ['q', 'page'],
+
   // Global store keys this page subscribes to — appears in view's server arg
   // Store mutations update all subscribed pages without a server round-trip
   store: ['user', 'cart'],
@@ -458,7 +464,7 @@ For any **new page, landing page, or branded site**, run this sequence first. Do
 3. pulse_intent(description)                  → archetype + scaffold + guide list
 ```
 
-**Before calling `pulse_intake`**, gather the required information by asking the user — one question at a time, in plain prose, no bullet lists. You need at minimum: the product name, what it does (pitch), and its key features. Ask for inspiration references, palette, vibe, and anti-style if the user hasn't mentioned them.
+**Before calling `pulse_intake`**, gather the required information by asking the user — one question at a time, in plain prose, no bullet lists. You need at minimum: the product name, what it does (pitch), and its key features. **Always ask first whether they have design inspiration** (a site they love, a screenshot, a mood board — dropped into `public/intake/` or pasted as a URL), and check `public/intake/` for images already there. Then ask for palette, vibe, and anti-style if not mentioned.
 
 **`pulse_sketch` is mandatory** for `playful`, `bold`, `brutalist`, `retro`, or `neon` vibes — those vibes fight the default centred-hero layout. Skip it only for `corporate` or `minimal` when no structural preference has been stated.
 
@@ -470,13 +476,16 @@ Every build task follows this sequence. Each phase has a pass gate — do not ad
 
 **Before calling any slow tool (`pulse_build`, `lighthouse_audit`), output a status message to the user first** — e.g. "Building for production — ~30 s…" or "Running Lighthouse desktop audit…". Never call a slow tool silently.
 
+> **Canonical workflow:** `pulse://workflow` (`src/agent/workflow.md`) is the authoritative version, including complexity tiers (not every task needs all phases). The table below is the summary — if they ever disagree, the MCP resource wins.
+
 | Phase | Action | Gate |
 |---|---|---|
 | 1. Understand | Read guides, call `pulse_list_structure` | — |
 | 2. Plan | Present plan to user, wait for confirmation | User confirms |
 | 3. Build | Write spec + related files | — |
 | 4. Validate | `pulse_validate` — fix all errors + warnings | Clean output |
-| 5. Browser | Screenshot → `pulse_design_review` (if intake ran) → `pulse_layout_review` → `/verify` (Lighthouse desktop + mobile + `pulse_review`) | ⛔ Do not skip: all gates must pass + `.pulse-verified` stamp written |
+| 5a. Design approval *(new builds only)* | Screenshot → describe → ask the user | ⛔ User approves layout before any slow checks run (skip for edits/fixes) |
+| 5b. Browser | `pulse_design_review` (if intake ran) → `pulse_layout_review` → `/verify` (Lighthouse desktop + mobile + `pulse_review`) | ⛔ Do not skip: all gates must pass + `.pulse-verified` stamp written |
 | 6. Tests | Write tests, run them, fix failures | All pass |
 | 7. Code Review | `pulse_review` — only after phases 4–6 pass | — |
 | 8. Fix | Fix every review issue, re-run affected gates | All gates still pass |
@@ -487,7 +496,7 @@ Every build task follows this sequence. Each phase has a pass gate — do not ad
 
 **The Code Review is always last.** Never invoke `pulse_review` before validate, Lighthouse, design review, and tests all pass.
 
-The `/verify` command runs the browser check loop (phases 4–5) automatically. Use it.
+The `/verify` command runs the browser check loop (phases 4–5b) automatically. Use it.
 
 ## Pulse vs React — Do Not Do These
 

package/docs/.claude/pulse-checklist.md

@@ -40,7 +40,7 @@ Before finishing any spec, verify every point below. Fix anything that fails.
   - **Declare it in a comment at the top of the spec** so the reviewer recognises it: `// component-free — creative override: <reason>`. This is the signal the review tool reads.
   - Functional atoms (`button`, `input`, `badge`, `modal`) should still come from components unless there is a specific design reason not to.
   - `/pulse-ui.css` is always required — it provides the token system your custom CSS will use.
-  - The quality gate replaces the component checklist: **100/100/100/100 Lighthouse on both desktop and mobile is the pass bar.** A component-free page that passes every audit is correct. A component-heavy page that fails accessibility is not.
+  - The quality gate replaces the component checklist: **Lighthouse 100 on Accessibility, Best Practices, and SEO — desktop and mobile — plus CLS 0.00 is the pass bar.** (Performance is reported but not gated; it varies with machine load.) A component-free page that passes every audit is correct. A component-heavy page that fails accessibility is not.
 
 - **When reviewing**: before flagging a class name like `.hero` as a violation, first ask whether the `hero()` component could actually reproduce the layout. If the answer is no, it is a creative override — check Lighthouse instead of refactoring. Do not flatten a good custom layout into a generic component just to clear a pattern-match.
 

package/examples/.claude/pulse-checklist.md

@@ -36,13 +36,15 @@ Before finishing any spec, verify every point below. Fix anything that fails.
   - Navigation → `nav({ logo, links, actions })`
   - Footers → `footer({ logo, links, columns, legal, ... })`
 
-- **Creative override — raw HTML throughout is permitted** when the design intent genuinely calls for it: a highly custom visual identity, an asymmetric or typographically-driven layout, a brutalist/editorial/retro/neon/paper vibe where components would constrain the expression. This is a deliberate design decision, not a shortcut. When taking this path:
-  - State it explicitly in the build brief: *"Building component-free — raw HTML throughout for creative control."*
+- **Creative override — raw HTML throughout is permitted** when the design intent genuinely calls for it: a highly custom visual identity, an asymmetric or typographically-driven layout, a brutalist/editorial/retro/neon/paper vibe where components would constrain the expression, or a layout that requires features a component simply doesn't support (e.g. full-viewport height, custom gradient glows, clamp-scaled display type). This is a deliberate design decision, not a shortcut. When taking this path:
+  - **Declare it in a comment at the top of the spec** so the reviewer recognises it: `// component-free — creative override: <reason>`. This is the signal the review tool reads.
   - Functional atoms (`button`, `input`, `badge`, `modal`) should still come from components unless there is a specific design reason not to.
   - `/pulse-ui.css` is always required — it provides the token system your custom CSS will use.
-  - The quality gate replaces the component checklist: **100/100/100/100 Lighthouse on both desktop and mobile is the pass bar.** A component-free page that passes every audit is correct. A component-heavy page that fails accessibility is not.
+  - The quality gate replaces the component checklist: **Lighthouse 100 on Accessibility, Best Practices, and SEO — desktop and mobile — plus CLS 0.00 is the pass bar.** (Performance is reported but not gated; it varies with machine load.) A component-free page that passes every audit is correct. A component-heavy page that fails accessibility is not.
 
-- When reviewing a spec built under creative override, do not flag raw section HTML as a violation — check the Lighthouse results instead.
+- **When reviewing**: before flagging a class name like `.hero` as a violation, first ask whether the `hero()` component could actually reproduce the layout. If the answer is no, it is a creative override — check Lighthouse instead of refactoring. Do not flatten a good custom layout into a generic component just to clear a pattern-match.
+
+- **The review tool auto-detects creative override** from the spec comment. When detected, component pattern checks are shown as advisory (`⚡`) not as failures, and the Lighthouse gate is the stated pass bar.
 
 - **Never write App Store or Google Play download buttons by hand.** Always use `appBadge({ store: 'apple', href })` and `appBadge({ store: 'google', href })`. Raw `<a>` tags with badge images are incorrect — `appBadge` renders the correct accessible, styled badge for each store.
 

package/package.json

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

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.16.0
+0.17.0

package/src/agent/checklist.md

@@ -40,7 +40,7 @@ Before finishing any spec, verify every point below. Fix anything that fails.
   - **Declare it in a comment at the top of the spec** so the reviewer recognises it: `// component-free — creative override: <reason>`. This is the signal the review tool reads.
   - Functional atoms (`button`, `input`, `badge`, `modal`) should still come from components unless there is a specific design reason not to.
   - `/pulse-ui.css` is always required — it provides the token system your custom CSS will use.
-  - The quality gate replaces the component checklist: **100/100/100/100 Lighthouse on both desktop and mobile is the pass bar.** A component-free page that passes every audit is correct. A component-heavy page that fails accessibility is not.
+  - The quality gate replaces the component checklist: **Lighthouse 100 on Accessibility, Best Practices, and SEO — desktop and mobile — plus CLS 0.00 is the pass bar.** (Performance is reported but not gated; it varies with machine load.) A component-free page that passes every audit is correct. A component-heavy page that fails accessibility is not.
 
 - **When reviewing**: before flagging a class name like `.hero` as a violation, first ask whether the `hero()` component could actually reproduce the layout. If the answer is no, it is a creative override — check Lighthouse instead of refactoring. Do not flatten a good custom layout into a generic component just to clear a pattern-match.
 

package/src/agent/commands/verify.md

@@ -8,73 +8,103 @@ Run the full verification loop on the current page or the page specified in $ARG
 
 If $ARGUMENTS is provided, use it as the file path or route. Otherwise, identify the most recently edited spec file from context.
 
-### 2. Validate the spec
+### 2. Design approval (new builds only)
+
+**Skip this step for edits, bug fixes, or "add X to existing Y" tasks.**
+
+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"]`; otherwise ask in plain prose.
+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.
+
+### 3. Validate the spec
 
 Use `pulse_validate` with the spec file content. If validation fails, report every error clearly and stop — do not proceed to screenshot until the spec is valid.
 
-### 3. Check the dev server
+### 4. Check the dev server
 
 Use `pulse_fetch_page` to confirm the server is responding for the route. If it errors, use `pulse_restart_server` and retry once.
 
-**If `pulse_fetch_page` returns unexpected HTML (e.g. a different project's page title, a Next.js 404, or any non-Pulse response):** check the `X-Pulse` response header — Pulse servers always send this. If it is absent, the wrong server is running on that port. Stop and inform the user before continuing.
-
-### 4. Screenshot
+### 5. Screenshot
 
 Use `mcp__chrome-devtools__navigate_page` to load the page route, then `mcp__chrome-devtools__take_screenshot` to capture the result. Describe what you see — layout, content, any obvious rendering issues.
 
-### 5. Lighthouse — desktop
+### 6. Lighthouse — desktop
+
+**Pre-flight (required before every Lighthouse run):**
+1. Call `pulse_build` to produce a production build and start the production server on port 3001.
+2. Call `navigate_page` with `url: "http://localhost:3001/"` so the browser is on the production server.
+
+Then run `mcp__chrome-devtools__lighthouse_audit` with `{ "device": "desktop" }`.
+
+**Pass bar: Accessibility, Best Practices, and SEO must all be 100.** Performance is measured and reported but is not a hard requirement (it varies with machine load). Report the actual scores. If Accessibility, Best Practices, or SEO is below 100, identify the failing audit(s), fix the issue, and restart from step 3.
 
-Run `mcp__chrome-devtools__lighthouse_audit` on the route with `{ "strategy": "desktop" }`.
+### 7. Lighthouse — mobile
 
-**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.
+The browser should still be on `http://localhost:3001/` from step 6. Run `mcp__chrome-devtools__lighthouse_audit` with `{ "device": "mobile" }`.
 
-### 6. Lighthouse — mobile
+**Same pass bar: Accessibility, Best Practices, and SEO must all be 100.** Fix any failures and restart from step 3.
 
-Run `mcp__chrome-devtools__lighthouse_audit` on the same route with `{ "strategy": "mobile" }`.
+After both Lighthouse runs pass, call `pulse_restart_server` to return to the dev server.
 
-**Same pass bar: Accessibility, Best Practices, and SEO must all be 100.** Fix any failures and restart from step 2.
+### 8. Mobile layout check
 
-**If you need to visually inspect the layout at a mobile viewport width** (e.g. to debug a wrapping or overflow issue), use `mcp__chrome-devtools__emulate` with `viewport: "390x844x2,mobile,touch"` — not `resize_page`. The `emulate` tool reliably sets the viewport; `resize_page` does not reliably trigger responsive layout changes. Reset afterward with `emulate` using the desktop viewport: `"1440x900x1"`.
+Emulate a mobile viewport and take a screenshot to catch wrapping, overflow, and layout issues before they become Lighthouse failures.
 
-### 7. Performance
+```
+mcp__chrome-devtools__emulate  viewport: "390x844x2,mobile,touch"
+mcp__chrome-devtools__navigate_page  url: "http://localhost:3000/"
+mcp__chrome-devtools__take_screenshot
+```
+
+Describe what you see. Look specifically for:
+- Text or buttons overflowing the viewport
+- Content too small to read or tap
+- Navigation that overlaps content
+- Images that break the layout
+
+Fix any issues, then reset to desktop before continuing:
+
+```
+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.).
 
-### 8. Console errors
+### 10. Console errors
 
 Use `mcp__chrome-devtools__list_console_messages` — report any errors or unexpected warnings.
 
-### 9. Code review
+### 11. Code review
 
-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.
+Call `pulse_review` with the spec file path. This runs a full code review AND atomically writes the `.pulse-verified` stamp server-side, eliminating any race condition with the stop hook.
 
-### 10. Close the browser
+Work through every item the review returns. Fix anything that fails before proceeding.
 
-Use `mcp__chrome-devtools__list_pages` to get all open pages, then call `mcp__chrome-devtools__close_page` for every page ID returned. This closes the entire browser, not just the tab. `pageId` must be a number, not a string.
+### 12. Close extra browser tabs
 
-### 11. Write verification stamp
+Use `mcp__chrome-devtools__list_pages` to get all open pages. Close every page **except the last one** — `close_page` refuses to close the final tab. `pageId` must be a number, not a string.
+
+If there is only one page open, skip this step — there is nothing to close.
+
+### 13. Write verification stamp
 
 Call `pulse_stamp`. This writes `.pulse-verified` via the MCP server, which is more reliable than the `date +%s` shell command — the MCP write always lands after all spec edits, avoiding the mtime race condition that can cause the stop hook to block immediately after verification.
 
 **This must be the last operation before stopping.** The stop hook compares each edited spec's mtime against this stamp — if any spec is newer than the stamp, the hook blocks. Do not edit any spec file after calling `pulse_stamp`.
 
-### 12. Report
+### 14. Report
 
 Summarise:
 - Validation: pass or fail (with errors if any)
-- Visual: what was visible in the screenshot
-- Lighthouse desktop: scores for all four categories
-- Lighthouse mobile: scores for all four categories
+- Visual: desktop screenshot and mobile layout check — any issues found and fixed
+- Lighthouse desktop: scores for Accessibility, Best Practices, SEO
+- Lighthouse mobile: scores for Accessibility, Best Practices, SEO
 - Performance: LCP and CLS values, any flagged insights
 - Console: any errors
 - Review: pass or issues found and fixed
 
-**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.
+Only confirm the page is good when validation passes, both Lighthouse runs are 100/100/100, CLS is 0.00, and there are no console errors. Otherwise, fix and run `/verify` again.

package/src/agent/guide-design-gallery.md

@@ -15,7 +15,7 @@ Warm cream background, hand-crafted feel. Photo-forward hero with a split layout
 **Key components:** `hero({ layout:'split' })`, `section`, `container`, `grid`, `card` (with `footer`), `stat`, `testimonial`, `cta`, `badge`
 
 **Distinguishing moves:**
-- Gradient hero `linear-gradient(135deg, #fdf6ee, #fdebd0)` with `color:#3d2b1e`
+- Gradient hero `linear-gradient(135deg, #fdf6ee, #fdebd0)` with `color:#3d2b1e` — define these hex values as tokens in `public/theme.css` and reference them via `var()`; the lint hook blocks raw hex in any other stylesheet
 - Nav with `background: rgba(255,250,245,0.92)` and matching text colour
 - Cards with price footer: `<div class="u-flex u-items-center u-justify-between"><span>From</span><strong>£35</strong></div>`
 - Credentials list: icon + span with `iconCheckCircle`
@@ -105,6 +105,8 @@ Long-form article layout with `prose` component for markdown rendering, breadcru
 
 ## Component Combinations by Use Case
 
+> Inline `style=""` in these snippets is limited to structural image properties (`aspect-ratio`, `object-fit`, fixed heights) that have no utility-class equivalent — this is the permitted exception to the no-inline-style rule. Colours and theming still belong in tokens.
+
 ### Image Card (Card with Cover Photo)
 Card doesn't have a native image slot — use `flush:true` and put the image inside `content`:
 
@@ -218,16 +220,16 @@ section({
 ```
 
 ### Booking / Contact Form Inside a Card
+Use the `input()` component for fields — it renders the label, id wiring, and required marker accessibly. Do not write raw `<input>`/`<label>` HTML:
+
 ```js
 card({
   title:   'Book an Appointment',
   content: `
     <p class="u-text-muted u-text-sm u-mb-4">Fill in the form and we'll confirm within a few hours.</p>
     <form class="u-flex u-flex-col u-gap-3" data-action="submit">
-      <div class="u-flex u-flex-col u-gap-1">
-        <label class="u-text-sm u-font-medium" for="name">Your name</label>
-        <input id="name" name="name" type="text" class="u-input" required>
-      </div>
+      ${input({ label: 'Your name', name: 'name', required: true })}
+      ${input({ label: 'Email', name: 'email', type: 'email', required: true })}
       ${button({ label: 'Send Enquiry', type: 'submit', variant: 'primary', fullWidth: true })}
     </form>
   `,

package/src/agent/guide-design-references.md

@@ -62,12 +62,12 @@ When you choose a design direction, tell the user which one you're using and why
 **Feels like:** Duolingo, Headspace, Loom, Figma landing page, pop-art toy brand  
 **vibe:** `playful`  
 **Geometry:** very rounded (18–24px), friendly icons, colourful  
-**Typography:** rounded or friendly sans, loose spacing, emoji-friendly  
+**Typography:** rounded or friendly sans, loose spacing, friendly icon accents (icon library, never emoji)  
 **Palette pattern:** bright bg (coral / mint / lavender) + dark text  
 **Signature moves (use these, not 3-col feature grids):**
 - **Full-colour section blocks** — each section has its own bg colour (yellow stats strip, cyan testimonials, hot-pink CTA). Palette is structure, not accent.
 - **Oversized hero element** — the product's key visual (a game board, an illustration, an icon) fills most of the hero viewport. `phoneFrame` is one option, not the default.
-- **Marquee strip** — giant repeated glyphs, emoji, or product icons scrolling across the page between sections (`marquee` component)
+- **Marquee strip** — giant repeated icon-library glyphs, brand marks, or product icons scrolling across the page between sections (`marquee` component). Use icons from `src/ui/icons.js`, not emoji — emoji are banned in UI output (not accessible, not theme-aware).
 - **Tilted `photoCard`s** — testimonial or feature cards at ±2–4° with `photoCard` or CSS `transform: rotate()`
 - **Memphis-style geometric shapes** between sections — use `decorate(pattern:'circles')` or CSS background shapes
 - **Social proof as ticker** — a `marquee` of short quotes or star ratings, not a 3-col grid

package/src/agent/identity.md

@@ -14,7 +14,7 @@ Every page you ship must meet all of the following. These are not aspirational
 
 **Lighthouse 100 on Accessibility, Best Practices, and SEO.** The \`lighthouse_audit\` tool returns these three scores — all must be 100. If any cannot hit 100, something is wrong with the spec. (Performance is not part of the audit tool and is not required.) The audit is slow — ~30–60 s per run. Always tell the user before calling it.
 
-**Polished and considered.** Use the component library — `button`, `card`, `input`, `alert`, `stat`, `empty`, `table`, and the rest. Use the spacing scale (`u-mt-*`, `u-gap-*`, `u-py-*`). Use the type scale (`u-text-xl`, `u-font-semibold`). Use the colour tokens (`var(--ui-accent)`, `var(--ui-muted)`). Do not leave raw unstyled HTML. Do not invent a layout from scratch when the grid, stack, cluster, container, and section components already solve it.
+**Polished and considered.** Use the component library — `button`, `card`, `input`, `alert`, `stat`, `empty`, `table`, and the rest. Use the spacing scale (`u-mt-*`, `u-gap-*`, `u-py-*`). Use the type scale (`u-text-xl`, `u-font-semibold`). Use the colour tokens (`var(--ui-accent)`, `var(--ui-muted)`). Do not leave raw unstyled HTML. Do not invent a layout from scratch when the grid, stack, cluster, container, and section components already solve it — *unless you have declared a creative override (see "Design Freedom" below), in which case a custom layout is the deliberate, correct choice.*
 
 **Works correctly on first load.** SSR is always on. The page must be readable and navigable before any JavaScript executes. Do not build pages that require client JS to render content.
 
@@ -22,15 +22,30 @@ Every page you ship must meet all of the following. These are not aspirational
 
 **Accessible form labels.** Every `input`, `select`, and `textarea` has a label. Every form has a submit button. Required fields are marked required. Error messages are associated with the field that caused them.
 
+# Design Freedom — The Rule
+
+There are two valid build modes. Knowing which one you are in tells you exactly which rules apply.
+
+**Mode A — components first (the default).** All standard UI patterns come from the component library. The component rules in "What You Will Not Do" below apply in full. This is the right mode for most pages.
+
+**Mode B — creative override.** When the design intent genuinely calls for it — a highly custom visual identity, an asymmetric or typographically-driven layout, a brutalist/editorial/retro/neon/paper vibe that components would constrain, or a layout a component simply cannot reproduce — you may build with raw HTML throughout. This is a deliberate design decision available to you, not a rule violation and not a shortcut. To use it:
+
+1. **Declare it in a comment at the top of the spec:** `// component-free — creative override: <reason>`. The review tool reads this comment from the source file — announcing the mode in chat is not enough.
+2. Functional atoms (`button`, `input`, `badge`, `modal`) still come from components unless there is a specific design reason not to.
+3. `/pulse-ui.css` stays in `meta.styles` — your custom CSS builds on its token system.
+4. The pass bar changes: instead of the component checklist, **Lighthouse 100 on Accessibility, Best Practices, and SEO, desktop and mobile**, plus CLS 0.00. A component-free page that passes every audit is correct. A component-heavy page that fails accessibility is not.
+
+The component rules marked *(Mode A)* below are suspended under a declared creative override. Everything else — accessibility, security, testing, escaping, error handling — applies in both modes, always.
+
 # What You Will Not Do
 
 - Install client-side JS dependencies. No React, Vue, Alpine, htmx, Tailwind, Lodash, Axios, or any other package that runs in the browser. Pulse handles rendering, state, actions, navigation, and SSR. If you need a utility, write it.
 - Use emoji characters in UI output. Use icons from the icon library instead — `iconCheck`, `iconStar`, `iconZap`, etc. If the right icon does not exist, create it in `src/ui/icons.js` following the existing pattern (see the guide for how). Emoji are not accessible, are not theme-aware, and render inconsistently across platforms.
-- Hardcode hex colours in CSS. Use `var(--ui-*)` tokens. They cascade through every component automatically and make theming possible.
-- Use inline `style=""` attributes. Use utility classes or `var(--ui-*)` tokens in a stylesheet.
-- Write raw `<button>`, `<input>`, `<select>`, or `<textarea>` HTML when the component library already provides accessible, styled versions.
-- Write raw `<h1>`–`<h6>` without styling. Use `heading({ level, text })` instead.
-- Write raw `<ul>` or `<ol>` without styling. Use `list({ items })` instead.
+- Hardcode hex colours in CSS. Use `var(--ui-*)` tokens — they cascade through every component automatically and make theming possible. The one place hex values belong is `public/theme.css`, as token *definitions*; every other stylesheet references them via `var()`. A lint hook enforces this.
+- Use inline `style=""` attributes. Use utility classes or `var(--ui-*)` tokens in a stylesheet. *Exception:* structural image styles with no utility-class equivalent (`aspect-ratio`, `object-fit`) are permitted inline — these are layout facts, not theming, and the design gallery uses them this way.
+- Write raw `<button>`, `<input>`, `<select>`, or `<textarea>` HTML when the component library already provides accessible, styled versions. *(Mode A — under a creative override, functional atoms should still come from components unless there is a specific design reason.)*
+- Write raw `<h1>`–`<h6>` without styling. Use `heading({ level, text })` instead. *(Mode A)*
+- Write raw `<ul>` or `<ol>` without styling. Use `list({ items })` instead. *(Mode A)*
 - Output CMS or database HTML without a `prose()` wrapper. Raw HTML from external sources has no styling — always wrap it in `prose({ content: html })`.
 - Use `data-event` on text inputs. Re-rendering on every keystroke destroys focus. Use uncontrolled inputs and read values from `FormData` in `action.onStart` or `action.run`.
 - Skip `onError` in an action. It is required. Always handle failure.

package/src/agent/workflow.md

@@ -73,7 +73,7 @@ Decide the complexity tier (see below) and confirm with the user if the task is
 
 **Skip confirmation for trivially small tasks** (add a button, fix a label, swap a component). When in doubt, confirm.
 
-**When asking the user questions:** ask one question at a time. If you present choices, use at most 4 options — the `ask_user` tool enforces this limit and will error if exceeded. For open-ended questions (names, copy, features, hex colours), ask as plain prose with no choices at all.
+**When asking the user questions:** ask one question at a time. If you present choices, use at most 4 options — question tools in agent hosts (e.g. Claude Code's AskUserQuestion) cap the number of choices and will error if exceeded. For open-ended questions (names, copy, features, hex colours), ask as plain prose with no choices at all.
 
 ---
 
@@ -161,11 +161,12 @@ If you're about to type `class="hero"` or `class="product-card"` in Mode A, stop
 When the design intent calls for a more expressive, unconventional, or typographically-driven layout that components would constrain, you may build with raw HTML throughout. This is a deliberate design decision, not a shortcut.
 
 Rules for Mode B:
+- **Declare it in a comment at the top of the spec file:** `// component-free — creative override: <reason>`. The review tool detects creative override by reading this comment from the source — without it, `pulse_review` will flag every component pattern as a violation even though you chose Mode B deliberately. Announcing the mode in chat is not enough; the comment must be in the file.
 - Load `/pulse-ui.css` in `meta.styles` — the token system is still required
 - Functional atoms (`button`, `input`, `badge`, `modal`) should still come from components unless there is a specific design reason
-- The quality gate is 100/100/100/100 Lighthouse on both desktop and mobile — this replaces the component checklist as the pass bar
+- The quality gate is Lighthouse 100 on Accessibility, Best Practices, and SEO (desktop and mobile) plus CLS 0.00 — this replaces the component checklist as the pass bar. Performance is reported but not gated.
 
-Announce Mode B explicitly in the build brief: *"Mode B — component-free, raw HTML for creative control."*
+Announce Mode B explicitly in the build brief (*"Mode B — component-free, raw HTML for creative control"*) **and** write the override comment into the spec.
 
 ### 3b — Announce before writing
 

package/src/html.js

@@ -21,4 +21,5 @@ export function escHtml(str) {
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;')
     .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
 }

package/src/mcp/mcp.test.js

@@ -102,6 +102,117 @@ test('no orphaned guide.md (monolithic legacy file should not exist)', () => {
   )
 })
 
+// ── Duplicated doc sync ──────────────────────────────────────────────────────
+// Several agent docs exist in two places (a canonical source plus a copy that is
+// scaffolded into consumer projects or kept in this repo's own .claude/). These
+// pairs must stay byte-identical or the two audiences receive drifting rules.
+
+console.log('\nDuplicated doc sync\n')
+
+const SYNC_PAIRS = [
+  ['src/agent/checklist.md',        '.claude/pulse-checklist.md'],
+  ['src/agent/checklist.md',        'docs/.claude/pulse-checklist.md'],
+  ['src/agent/checklist.md',        'examples/.claude/pulse-checklist.md'],
+  ['src/agent/commands/verify.md',  '.claude/commands/verify.md'],
+]
+
+for (const [a, b] of SYNC_PAIRS) {
+  test(`${a} is in sync with ${b}`, () => {
+    const fa = path.join(ROOT, a)
+    const fb = path.join(ROOT, b)
+    assert(fs.existsSync(fa), `${a} does not exist`)
+    assert(fs.existsSync(fb), `${b} does not exist`)
+    assert(
+      fs.readFileSync(fa, 'utf8') === fs.readFileSync(fb, 'utf8'),
+      `${a} and ${b} have drifted apart. Edit the canonical file and copy it over the other ` +
+      `(cp ${a} ${b} or vice versa) so both audiences get the same rules.`
+    )
+  })
+}
+
+// ── Agent doc consistency guards ─────────────────────────────────────────────
+// Contradictions between agent docs leave the agent unable to know what it can
+// and cannot do. These guards pin the resolved decisions:
+//   - The Lighthouse pass bar is THREE gated scores (Accessibility, Best
+//     Practices, SEO) — Performance is reported, never gated. "100/100/100/100"
+//     reintroduces a four-score bar the audit tooling cannot verify.
+//   - "ask_user" is not a real tool in any host — docs must not name it.
+//   - Emoji are banned in UI output — design guides must not suggest them.
+
+console.log('\nAgent doc consistency\n')
+
+const agentDocs = [
+  ...fs.readdirSync(agentDir).filter(f => f.endsWith('.md')).map(f => path.join('src/agent', f)),
+  ...fs.readdirSync(path.join(agentDir, 'commands')).filter(f => f.endsWith('.md')).map(f => path.join('src/agent/commands', f)),
+  ...fs.readdirSync(path.join(agentDir, 'skills')).flatMap(d => {
+    const p = path.join(agentDir, 'skills', d, 'SKILL.md')
+    return fs.existsSync(p) ? [path.join('src/agent/skills', d, 'SKILL.md')] : []
+  }),
+  '.claude/commands/build-page.md',
+  '.claude/commands/verify.md',
+  '.claude/commands/new-doc-page.md',
+  'CLAUDE.md',
+]
+
+test('no agent doc states a four-score Lighthouse bar (100/100/100/100)', () => {
+  const offenders = agentDocs.filter(f =>
+    fs.existsSync(path.join(ROOT, f)) &&
+    fs.readFileSync(path.join(ROOT, f), 'utf8').includes('100/100/100/100')
+  )
+  if (serverSrc.includes('100/100/100/100')) offenders.push('src/mcp/server.js')
+  assert(
+    offenders.length === 0,
+    `Four-score Lighthouse bar found in: ${offenders.join(', ')}. ` +
+    `The gated scores are Accessibility, Best Practices, and SEO (three) — Performance is reported, not gated.`
+  )
+})
+
+test('no agent doc references a literal ask_user tool', () => {
+  const offenders = agentDocs.filter(f =>
+    fs.existsSync(path.join(ROOT, f)) &&
+    /\bask_user\b/.test(fs.readFileSync(path.join(ROOT, f), 'utf8'))
+  )
+  assert(
+    offenders.length === 0,
+    `"ask_user" referenced in: ${offenders.join(', ')}. ` +
+    `No host exposes a tool by that name — phrase host-agnostically (e.g. "your host's question tool").`
+  )
+})
+
+test('design guides do not suggest emoji in UI output', () => {
+  const designGuides = ['src/agent/guide-design-references.md', 'src/agent/guide-design-gallery.md']
+  const offenders = designGuides.filter(f => {
+    const src = fs.readFileSync(path.join(ROOT, f), 'utf8')
+    // Allow lines that mention emoji only to ban them; flag lines that suggest using them
+    return src.split('\n').some(line =>
+      /emoji/i.test(line) && !/never|not |banned|instead of emoji/i.test(line)
+    )
+  })
+  assert(
+    offenders.length === 0,
+    `Emoji suggested (without a ban qualifier) in: ${offenders.join(', ')}. ` +
+    `Emoji are banned in UI output (identity.md) — suggest icon-library glyphs instead.`
+  )
+})
+
+test('workflow.md Mode B instructs writing the creative-override spec comment', () => {
+  const workflow = fs.readFileSync(path.join(agentDir, 'workflow.md'), 'utf8')
+  assert(
+    /component.free — creative override/.test(workflow),
+    'workflow.md Mode B must instruct writing the `// component-free — creative override: <reason>` ' +
+    'comment into the spec — pulse_review detects creative override by reading the source file.'
+  )
+})
+
+test('identity.md declares the creative override (Design Freedom) carve-out', () => {
+  const identity = fs.readFileSync(path.join(agentDir, 'identity.md'), 'utf8')
+  assert(
+    /creative override/i.test(identity),
+    'identity.md must include the creative-override carve-out — without it the persona ' +
+    'unconditionally bans raw HTML that workflow.md Mode B explicitly permits.'
+  )
+})
+
 // ── Result ───────────────────────────────────────────────────────────────────
 
 console.log(`\n${passed} passed, ${failed} failed\n`)

package/src/mcp/server.js

@@ -1081,7 +1081,7 @@ ${(() => {
   // Creative override detection — check if spec declares component-free mode
   const creativeOverride = /component.free|creative\s+override|raw\s+HTML\s+throughout/i.test(source)
   checks.push(creativeOverride
-    ? '⚡ **Creative override declared** — component pattern checks are advisory only. Lighthouse 100/100/100/100 is the pass bar.'
+    ? '⚡ **Creative override declared** — component pattern checks are advisory only. Lighthouse 100 on Accessibility, Best Practices, and SEO (desktop + mobile) plus CLS 0.00 is the pass bar.'
     : '○ No creative override declared — component checks apply')
 
   return checks.join('\n')
@@ -1122,7 +1122,7 @@ Work through every item. Fix anything that fails. Refer to the spec source at ${
 
   If no creative override is declared and a component *could* reproduce the design, refactor to use it. Custom utility classes on top of components are fine (\`hero({ ... })\` + override CSS) — but do not write the entire structure from scratch when the component supports the layout.
 
-- [ ] **Creative override** (fill in if applicable): *State the override reason here — e.g. "full-viewport gradient hero not achievable with hero() component"*. Confirm Lighthouse 100/100/100/100 desktop and mobile passes before closing the review.
+- [ ] **Creative override** (fill in if applicable): *State the override reason here — e.g. "full-viewport gradient hero not achievable with hero() component"*. Confirm Lighthouse 100 on Accessibility, Best Practices, and SEO (desktop and mobile) plus CLS 0.00 before closing the review.
 - [ ] No \`data-event\` on text inputs — this destroys focus on every keystroke
 - [ ] No \`className\`, \`htmlFor\`, \`onClick=\`, or other React patterns
 - [ ] No hardcoded hex colours in view — only \`var(--ui-*)\` tokens (anchor \`href="#id"\` values are fine — those are not colours)

package/src/md/index.js

@@ -25,6 +25,33 @@ function esc(s) {
     .replace(/"/g, '"')
 }
 
+/**
+ * Sanitise a markdown link/image URL.
+ *
+ * Allows http(s), mailto, tel, relative paths, fragment/query refs, and
+ * image data: URIs. Any other scheme — notably javascript:, vbscript:, and
+ * non-image data: URIs — is neutralised to '#', preventing XSS when markdown
+ * comes from an untrusted source (database, user submission, external API).
+ *
+ * The value has already passed through esc(), so it is safe to embed in an
+ * attribute; this guard only blocks dangerous URL schemes.
+ *
+ * @param {string} url
+ * @param {boolean} [isImage=false] - permit image data: URIs when true
+ * @returns {string}
+ */
+function safeUrl(url, isImage = false) {
+  // Strip leading control chars/whitespace that browsers ignore when parsing
+  // the scheme (e.g. "java\tscript:"), then test for a scheme prefix.
+  const stripped = url.replace(/[\x00-\x20]+/g, '')
+  const scheme   = stripped.match(/^([a-zA-Z][a-zA-Z0-9+.\-]*):/)
+  if (!scheme) return url  // no scheme → relative / fragment / query, safe
+  const proto = scheme[1].toLowerCase()
+  if (proto === 'http' || proto === 'https' || proto === 'mailto' || proto === 'tel') return url
+  if (isImage && /^data:image\/(png|jpe?g|gif|webp|avif|svg\+xml);/i.test(stripped)) return url
+  return '#'
+}
+
 // ---------------------------------------------------------------------------
 // Frontmatter — --- key: value --- block at top of file
 // ---------------------------------------------------------------------------
@@ -69,12 +96,12 @@ function renderInline(raw) {
   // 3. Images (before links — same syntax with leading !)
   s = s.replace(/!\[([^\]]*)\]\(([^)\s"]+)(?:\s+"([^"]*)")?\)/g,
     (_, alt, src, title) =>
-      `<img src="${src}" alt="${alt}"${title ? ` title="${title}"` : ''}>`)
+      `<img src="${safeUrl(src, true)}" alt="${alt}"${title ? ` title="${title}"` : ''}>`)
 
   // 4. Links
   s = s.replace(/\[([^\]]+)\]\(([^)\s"]+)(?:\s+"([^"]*)")?\)/g,
     (_, label, href, title) =>
-      `<a href="${href}"${title ? ` title="${title}"` : ''}>${label}</a>`)
+      `<a href="${safeUrl(href)}"${title ? ` title="${title}"` : ''}>${label}</a>`)
 
   // 5. Bold + italic (order: *** before ** before *)
   s = s.replace(/\*{3}([^*\n]+)\*{3}/g, (_, t) => `<strong><em>${t}</em></strong>`)

package/src/md/md.test.js

@@ -175,6 +175,42 @@ test('HTML is escaped in inline text', () => {
   assert(html.includes('<script>'), `Got: ${html}`)
 })
 
+// --- URL scheme sanitisation (XSS) -----------------------------------------
+
+test('link with javascript: scheme is neutralised to #', () => {
+  const { html } = parseMd('[x](javascript:alert(1))')
+  assert(!html.toLowerCase().includes('javascript:'), `Got: ${html}`)
+  assert(html.includes('href="#"'), `Got: ${html}`)
+})
+
+test('javascript: scheme neutralised regardless of case', () => {
+  const { html } = parseMd('[x](JaVaScRiPt:alert(1))')
+  assert(!html.toLowerCase().includes('javascript:'), `Got: ${html}`)
+})
+
+test('image with javascript: scheme is neutralised', () => {
+  const { html } = parseMd('![i](javascript:alert(1))')
+  assert(!html.toLowerCase().includes('javascript:'), `Got: ${html}`)
+  assert(html.includes('src="#"'), `Got: ${html}`)
+})
+
+test('non-image data: URI in image is neutralised', () => {
+  const { html } = parseMd('![i](data:text/html,<script>alert(1)</script>)')
+  assert(html.includes('src="#"'), `Got: ${html}`)
+})
+
+test('image data: URI is allowed', () => {
+  const { html } = parseMd('![i](data:image/png;base64,iVBOR)')
+  assert(html.includes('src="data:image/png;base64,iVBOR"'), `Got: ${html}`)
+})
+
+test('safe schemes and relative/fragment URLs are preserved', () => {
+  for (const url of ['https://ok.com', 'http://ok.com', '/relative', '#frag', 'mailto:a@b.com', 'tel:+15551234']) {
+    const { html } = parseMd(`[x](${url})`)
+    assert(html.includes(`href="${url}"`), `Expected ${url} preserved, got: ${html}`)
+  }
+})
+
 // ---------------------------------------------------------------------------
 
 console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`)

package/src/runtime/ssr.js

@@ -621,4 +621,5 @@ function esc(str) {
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;')
     .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
 }

package/src/runtime/tt.js

@@ -4,6 +4,14 @@
  * everywhere else — behaviour is identical, the protection is simply absent.
  *
  * Policy name 'pulse' must match the trusted-types CSP directive on the server.
+ *
+ * SECURITY NOTE: createHTML/createScriptURL are intentional pass-throughs. The
+ * framework owns the HTML it renders, so this policy does NOT sanitise — it
+ * exists to satisfy `require-trusted-types-for 'script'` and to confine HTML
+ * sinks to a single audited policy (preventing *other* code on the page from
+ * creating its own policy). It is NOT a defence against unescaped user data in
+ * a view: view authors remain responsible for escaping untrusted values with
+ * escHtml() before interpolating them into markup.
  */
 
 let _policy = null

package/src/server/index.js

@@ -119,16 +119,25 @@ function negotiateEncoding(req) {
   return null
 }
 
+// Brotli quality for on-the-fly (per-request) compression. The library default
+// is 11 — the maximum, intended for build-time compression of static assets.
+// At q11 each dynamic response costs ~10x the CPU of q5 for a marginal size gain
+// on HTML, inflating TTFB and limiting throughput. q5 matches what CDNs/nginx use
+// for dynamic content. Pre-built /dist/* bundles should be compressed at build time.
+const BROTLI_DYNAMIC = {
+  params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 5 },
+}
+
 /** Compress a Buffer using the given encoding. Returns the original if none. */
 async function compressBuffer(buf, encoding) {
-  if (encoding === 'br')   return brotliAsync(buf)
+  if (encoding === 'br')   return brotliAsync(buf, BROTLI_DYNAMIC)
   if (encoding === 'gzip') return gzipAsync(buf)
   return buf
 }
 
 /** Create a transform stream for the given encoding, or null. */
 function createCompressor(encoding) {
-  if (encoding === 'br')   return zlib.createBrotliCompress()
+  if (encoding === 'br')   return zlib.createBrotliCompress(BROTLI_DYNAMIC)
   if (encoding === 'gzip') return zlib.createGzip()
   return null
 }
@@ -211,21 +220,38 @@ function parseMultipart(buf, boundary) {
 // In-process TTL cache — server data memoization
 // ---------------------------------------------------------------------------
 
-class TtlCache {
-  constructor() {
-    this._store    = new Map()
-    this._interval = null
+export class TtlCache {
+  /**
+   * @param {number} [maxEntries=1000] - hard cap on stored entries. When exceeded,
+   *   the least-recently-used entry is evicted. Bounds memory so cache keys derived
+   *   from attacker-controlled input (query strings, Host header) cannot grow the
+   *   cache without limit.
+   */
+  constructor(maxEntries = 1000) {
+    this._store      = new Map()  // Map preserves insertion order → used for LRU
+    this._interval   = null
+    this._maxEntries = maxEntries
   }
 
   get(key) {
     const entry = this._store.get(key)
     if (!entry) return undefined
     if (Date.now() > entry.expiresAt) { this._store.delete(key); return undefined }
+    // Mark as most-recently-used: re-insert to move to the end of the Map.
+    this._store.delete(key)
+    this._store.set(key, entry)
     return entry.value
   }
 
   set(key, value, ttlSeconds) {
+    // Refresh position if it already exists so LRU ordering stays correct.
+    this._store.delete(key)
     this._store.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1000 })
+    // Evict the least-recently-used entry (first in insertion order) when over cap.
+    if (this._store.size > this._maxEntries) {
+      const oldest = this._store.keys().next().value
+      this._store.delete(oldest)
+    }
   }
 
   /** Remove all entries whose TTL has elapsed. */
@@ -308,9 +334,27 @@ function pageCacheTtl(spec, dev, defaultCache) {
   return cfg?.maxAge || 0
 }
 
-/** Build the in-process page cache key scoped to route + request parameters. */
+/**
+ * Build the in-process page cache key.
+ *
+ * The key is scoped to the route + path params + only the query keys the spec
+ * explicitly opts into via `spec.cacheVary`. The full query string is NOT part
+ * of the key by default: an unauthenticated client can append arbitrary query
+ * params (?n=1, ?n=2, …) that don't change a cacheable page's output, and
+ * including them would let that client mint unbounded distinct cache entries
+ * (memory-exhaustion DoS). Pages whose output genuinely depends on a query
+ * param declare it in `cacheVary: ['q']`.
+ */
 function buildCacheKey(spec, ctx) {
-  return spec.route + '\0' + JSON.stringify(ctx.params) + '\0' + JSON.stringify(ctx.query)
+  let varied = ''
+  if (Array.isArray(spec.cacheVary) && spec.cacheVary.length) {
+    const picked = {}
+    for (const k of spec.cacheVary) {
+      if (ctx.query[k] !== undefined) picked[k] = ctx.query[k]
+    }
+    varied = JSON.stringify(picked)
+  }
+  return spec.route + '\0' + JSON.stringify(ctx.params) + '\0' + varied
 }
 
 /**
@@ -517,8 +561,10 @@ export async function createServer(entries, options = {}) {
     }
   }
 
-  // Per-host brand cache — avoids hitting the data store on every request
-  const brandCache = new TtlCache()
+  // Per-host brand cache — avoids hitting the data store on every request.
+  // Capped (Host header is attacker-controlled, so unbounded distinct keys
+  // would otherwise be a memory-exhaustion vector).
+  const brandCache = new TtlCache(500)
   brandCache.startEviction(30_000)  // brand TTL is 60s, scan every 30s
 
   // Load manifest — maps source hydrate paths to production bundle paths
@@ -554,14 +600,19 @@ export async function createServer(entries, options = {}) {
   // Build route table — let so it can be swapped on hot reload
   let router = buildRouter(specs)
 
+  // Resolve the logger module once at startup rather than dynamically importing
+  // it on every request's `finish` event. `logRequest` stays null until loaded.
+  let logRequest = null
+  if (!quiet) {
+    import('../cli/logger.js').then(m => { logRequest = m.request }).catch(() => {})
+  }
+
   const server = http.createServer(async (req, res) => {
     const reqStart = Date.now()
     res.on('finish', () => {
-      if (!quiet) {
-        import('../cli/logger.js').then(({ request: logRequest }) => {
-          const url = new URL(req.url, `http://localhost:${port}`)
-          logRequest({ method: req.method, pathname: url.pathname, status: res.statusCode, ms: Date.now() - reqStart })
-        }).catch(() => {})
+      if (logRequest) {
+        const url = new URL(req.url, `http://localhost:${port}`)
+        logRequest({ method: req.method, pathname: url.pathname, status: res.statusCode, ms: Date.now() - reqStart })
       }
     })
     try {
@@ -691,6 +742,13 @@ export async function createServer(entries, options = {}) {
       // Canonical path follows the trailingSlash mode so the <link> is consistent with redirects.
       // spec.meta.canonical (string or function) is resolved inside each handler, where serverState
       // is available — allowing dynamic canonicals from server fetcher results.
+      //
+      // SECURITY: proto/host come from client-controllable headers (x-forwarded-*,
+      // Host). They are HTML-escaped before being emitted into <link rel=canonical>
+      // and og:* tags, so this is not an XSS vector — but if your edge/proxy does
+      // not pin or validate these headers, an attacker can influence the canonical
+      // URL (SEO/canonical poisoning). Trust x-forwarded-* only behind a proxy you
+      // control; set spec.meta.canonical to a fixed string to opt out entirely.
       const proto        = req.headers['x-forwarded-proto'] || 'http'
       const host         = req.headers['x-forwarded-host'] || req.headers.host || `localhost:${port}`
       const canonicalPath = trailingSlash === 'add' && pathname !== '/'
@@ -1112,7 +1170,7 @@ async function handleRawResponse(spec, ctx, req, res, dev) {
   let content
 
   if (!dev && spec.serverTtl) {
-    const key = 'raw:' + spec.route + '\0' + JSON.stringify(ctx.params) + '\0' + JSON.stringify(ctx.query)
+    const key = 'raw:' + buildCacheKey(spec, ctx)
     content = serverDataCache.get(key)
     if (!content) {
       const serverState = await resolveServerState(spec, ctx)
@@ -1181,9 +1239,15 @@ function matchRoute(router, pathname) {
     if (!match) continue
 
     const params = {}
-    route.params.forEach((name, i) => {
-      params[name] = decodeURIComponent(match[i + 1])
-    })
+    try {
+      route.params.forEach((name, i) => {
+        params[name] = decodeURIComponent(match[i + 1])
+      })
+    } catch {
+      // Malformed percent-encoding (e.g. /%ZZ) — treat as no match (404)
+      // rather than letting decodeURIComponent throw a 500.
+      continue
+    }
 
     return { spec: route.spec, params }
   }
@@ -1433,7 +1497,9 @@ function resolveSpec(spec, hydrateMap) {
  */
 function serveStatic(req, res, staticDir, dev = false) {
   const url      = new URL(req.url, 'http://localhost')
-  const pathname = decodeURIComponent(url.pathname)
+  let pathname
+  try { pathname = decodeURIComponent(url.pathname) }
+  catch { return false }  // malformed percent-encoding → not a static file
 
   // Prevent directory traversal
   const filePath = path.join(staticDir, pathname)
@@ -1516,6 +1582,7 @@ function escHtml(str) {
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;')
     .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
 }
 
 function notFoundHtml(pathname) {

package/src/server/server.test.js

@@ -4,7 +4,7 @@
  */
 
 import http from 'http'
-import { createServer } from './index.js'
+import { createServer, TtlCache } from './index.js'
 
 // ---------------------------------------------------------------------------
 // Test runner
@@ -1246,6 +1246,111 @@ await test('health check fires before route matching — shadows a user spec at
 
 // ---------------------------------------------------------------------------
 
+console.log('\nMalformed request handling\n')
+
+await test('malformed percent-encoding in path returns 404, not 500', async () => {
+  await withServer([helloSpec], { stream: false }, async (port) => {
+    const { status } = await get(port, '/%ZZ')
+    assert(status === 404, `Expected 404 for malformed encoding, got ${status}`)
+  })
+})
+
+await test('malformed percent-encoding in param route returns 404', async () => {
+  await withServer([productSpec], { stream: false }, async (port) => {
+    const { status } = await get(port, '/products/%E0%A4%A')
+    assert(status === 404, `Expected 404 for malformed param, got ${status}`)
+  })
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nPage cache — query-string DoS guard\n')
+
+await test('query string is NOT part of the cache key by default', async () => {
+  // A cacheable page should serve identical cached HTML regardless of arbitrary
+  // query params — they must not mint new cache entries.
+  let renders = 0
+  const spec = {
+    route: '/cached',
+    cache: { public: true, maxAge: 60 },
+    view:  () => `<h1>render-${++renders}</h1>`,
+  }
+  await withServer([spec], { stream: false }, async (port) => {
+    const a = await get(port, '/cached?n=1')
+    const b = await get(port, '/cached?n=2')
+    const c = await get(port, '/cached?n=3')
+    assert(a.body === b.body && b.body === c.body, 'Cached body should be identical across query strings')
+    assert(a.body.includes('render-1'), `Expected first render cached, got: ${a.body}`)
+  })
+})
+
+await test('cacheVary keys DO produce distinct cache entries', async () => {
+  let renders = 0
+  const spec = {
+    route:     '/varied',
+    cache:     { public: true, maxAge: 60 },
+    cacheVary: ['q'],
+    server:    { n: async () => ++renders },
+    view:      (_s, server) => `<h1>v-${server.n}</h1>`,
+  }
+  // server fetcher makes this non-cacheable for HTML, so vary only affects
+  // the in-process key; assert distinct outputs per q value.
+  await withServer([spec], { stream: false }, async (port) => {
+    const a = await get(port, '/varied?q=apple')
+    const b = await get(port, '/varied?q=banana')
+    assert(a.body !== b.body, `Expected distinct outputs per cacheVary value, got identical: ${a.body}`)
+  })
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nTtlCache — bounded LRU\n')
+
+await test('evicts least-recently-used entry when over capacity', () => {
+  const c = new TtlCache(2)
+  c.set('a', 1, 60)
+  c.set('b', 2, 60)
+  c.set('c', 3, 60)  // exceeds cap → evicts 'a' (LRU)
+  assert(c.get('a') === undefined, 'Expected a to be evicted')
+  assert(c.get('b') === 2, 'Expected b to remain')
+  assert(c.get('c') === 3, 'Expected c to remain')
+})
+
+await test('get() refreshes recency so the touched entry survives eviction', () => {
+  const c = new TtlCache(2)
+  c.set('a', 1, 60)
+  c.set('b', 2, 60)
+  c.get('a')         // 'a' now most-recently-used
+  c.set('c', 3, 60)  // evicts 'b', not 'a'
+  assert(c.get('a') === 1, 'Expected a to survive (recently used)')
+  assert(c.get('b') === undefined, 'Expected b to be evicted')
+})
+
+await test('many distinct keys never exceed the cap', () => {
+  const c = new TtlCache(100)
+  for (let i = 0; i < 10_000; i++) c.set(`k${i}`, i, 60)
+  assert(c._store.size === 100, `Expected size capped at 100, got ${c._store.size}`)
+})
+
+await test('expired entries are not returned', () => {
+  const c = new TtlCache(10)
+  c.set('x', 1, -1)  // already expired
+  assert(c.get('x') === undefined, 'Expected expired entry to be absent')
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nCompression\n')
+
+await test('serves brotli-compressed HTML when br is accepted', async () => {
+  await withServer([helloSpec], { stream: false }, async (port) => {
+    const { headers } = await request(port, 'GET', '/hello', { 'Accept-Encoding': 'br' })
+    assert(headers['content-encoding'] === 'br', `Expected br encoding, got ${headers['content-encoding']}`)
+  })
+})
+
+// ---------------------------------------------------------------------------
+
 console.log('\nGraceful shutdown\n')
 
 await test('shutdown() is returned from createServer', async () => {

package/src/spec/schema.js

@@ -371,6 +371,16 @@ export function validateSpec(spec) {
     }
   }
 
+  // cacheVary — query-string keys that affect the cached HTML for this page.
+  // By default the in-process page cache ignores the query string entirely (so a
+  // client cannot mint unbounded cache entries with arbitrary ?n=… params). Pages
+  // whose output depends on a query param must list it here, e.g. cacheVary: ['q'].
+  if (spec.cacheVary !== undefined) {
+    if (!Array.isArray(spec.cacheVary) || !spec.cacheVary.every(k => typeof k === 'string')) {
+      errors.push('spec.cacheVary must be an array of query-parameter name strings, e.g. [\'q\', \'page\']')
+    }
+  }
+
   // hydrate — auto-derived by the framework, should never be set manually
   if (spec.hydrate !== undefined) {
     warnings.push('spec.hydrate is set manually — it is auto-derived by the framework from the URL entry passed to createServer. Remove it from the spec.')