@invisibleloop/pulse 0.1.21

package/docs/src/pages/performance.js

@@ -0,0 +1,157 @@
+import { renderLayout, h1, lead, section, codeBlock, table, callout } from '../lib/layout.js'
+import { prevNext } from '../lib/nav.js'
+import { highlight } from '../lib/highlight.js'
+
+const { prev, next } = prevNext('/performance')
+
+export default {
+  route: '/performance',
+  meta: {
+    title: 'Performance — Pulse Docs',
+    description: 'Performance targets, techniques, and built-in optimisations in Pulse.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/performance',
+    prev,
+    next,
+    content: `
+      ${h1('Performance')}
+      ${lead('Performance in Pulse is structural, not optional. Streaming SSR, immutable asset caching, brotli compression, and zero client JS by default are the baseline — not optimisations applied after the fact. A page that uses the framework correctly cannot score poorly.')}
+
+      ${section('targets', 'Performance targets')}
+      <p>Every page served by Pulse should meet these targets on localhost with no throttling:</p>
+      ${table(
+        ['Metric', 'Target', 'How'],
+        [
+          ['LCP', 'Fast', 'Streaming SSR sends HTML before server data resolves. Actual LCP depends on server location, CDN, and network conditions.'],
+          ['CLS', '0.00', 'Always set <code>width</code> and <code>height</code> on images; framework never shifts layout'],
+          ['Lighthouse Performance', '100', 'Compression, immutable caching, no render-blocking resources'],
+          ['Lighthouse Accessibility', '100', 'Semantic HTML, proper alt text, sufficient contrast'],
+          ['Lighthouse SEO', '100', 'Meta tags, structured data, canonical links'],
+          ['Lighthouse Best Practices', '100', 'HTTPS, security headers, no deprecated APIs'],
+        ]
+      )}
+      ${callout('note', 'Run <code>mcp__chrome-devtools__lighthouse_audit</code> after every new page to verify all four scores are 100. Fix any failures before considering the task done.')}
+
+      ${section('streaming-ssr', 'Streaming SSR')}
+      <p>Pulse uses Node.js streams for SSR. The server sends the <code>&lt;head&gt;</code> and page shell immediately, before any async data resolves. Browsers start downloading CSS and fonts while the server fetches data — so the user sees a styled shell within milliseconds.</p>
+      ${codeBlock(highlight(`export default {
+  route: '/feed',
+
+  // Shell renders instantly — hero, nav, layout
+  // Deferred segments wait for data then stream in
+  stream: {
+    shell:    ['header', 'hero'],
+    deferred: ['feed', 'sidebar'],
+  },
+
+  server: {
+    feed:    async () => db.posts.getLatest(20),   // slow
+    sidebar: async () => db.tags.getPopular(),     // slow
+  },
+
+  // view is a keyed object matching stream segments
+  view: {
+    header:  (state) => \`<header>...</header>\`,
+    hero:    (state) => \`<section class="hero">...</section>\`,
+    feed:    (state, server) => server.feed.map(renderPost).join(''),
+    sidebar: (state, server) => renderSidebar(server.sidebar),
+  },
+}`, 'js'))}
+
+      ${section('compression', 'Automatic compression')}
+      <p>All responses are compressed automatically. Pulse negotiates the best available encoding from the <code>Accept-Encoding</code> header:</p>
+      ${table(
+        ['Encoding', 'Priority', 'Typical savings'],
+        [
+          ['Brotli (<code>br</code>)', 'First choice', '20–30% smaller than gzip for text content'],
+          ['gzip', 'Fallback', 'Widely supported, good compression'],
+          ['None', 'Last resort', 'No compression (rare)'],
+        ]
+      )}
+      <p>HTML, CSS, JavaScript, JSON, XML, and SVG responses are all compressed. Binary formats (images, fonts) are served as-is.</p>
+
+      ${section('asset-caching', 'Immutable asset caching')}
+      <p>Production JS bundles include a content hash in their filename (<code>/dist/counter.boot-a1b2c3d4.js</code>). The server sends <code>Cache-Control: public, max-age=31536000, immutable</code> for these files — browsers cache them forever and never re-request them unless the hash changes.</p>
+      <p>When you deploy a new version, the hash changes, and users automatically get the new file. No cache-busting tricks needed.</p>
+      ${callout('tip', 'Static assets in <code>public/</code> get <code>max-age=3600</code>. For rarely-updated images, consider versioning them by filename.')}
+
+      ${section('zero-client-js', 'Zero client JS by default')}
+      <p>Pages with no <code>mutations</code>, <code>actions</code>, or <code>persist</code> send no JavaScript at all — the HTML is entirely self-contained. The Pulse CLI detects this automatically; you never need to opt out. This is appropriate for static content pages: marketing pages, blog posts, documentation.</p>
+      ${codeBlock(highlight(`// No mutations, actions, or persist → zero JS sent to browser
+export default {
+  route: '/about',
+  meta:  { title: 'About', styles: ['/app.css'] },
+  state: {},
+  view:  () => \`<main><h1>About us</h1></main>\`,
+}`, 'js'))}
+
+      ${section('js-bundle-splitting', 'JS bundle splitting and caching')}
+      <p>When you open the network tab you will see a single <code>[page].boot-[hash].js</code> file loading. What is inside that file depends on how many pages your app has:</p>
+      ${table(
+        ['App size', 'What the boot file contains', 'Size (brotli)'],
+        [
+          ['Single page', 'Your spec + the full Pulse runtime bundled together', '~3.5 kB'],
+          ['Multiple pages', 'Your spec only — runtime is in a separate <code>runtime-[hash].js</code> chunk', '~0.35–0.5 kB'],
+        ]
+      )}
+      <p>With multiple pages, esbuild's code splitting extracts the Pulse runtime into a shared chunk because every page imports it. The browser downloads it once and caches it — subsequent page navigations only fetch the small per-page boot file.</p>
+      <p><strong>What you see in the network tab across navigations:</strong></p>
+      <ul>
+        <li><strong>First page visit</strong> — <code>runtime-[hash].js</code> (~3.1 kB) + <code>home.boot-[hash].js</code> (~0.35 kB)</li>
+        <li><strong>Navigate to another page</strong> — <code>contact.boot-[hash].js</code> (~0.47 kB) only. Runtime already cached.</li>
+        <li><strong>Return visit</strong> — nothing. Both files served from cache with <code>immutable</code> headers.</li>
+      </ul>
+      ${callout('tip', 'The runtime hash only changes when the Pulse runtime itself is updated — not when your app changes. Deploying new pages or mutations does not bust the runtime cache for returning visitors.')}
+
+      ${section('security-headers', 'Security headers')}
+      <p>Every response — including 404 and 500 errors — carries a full set of security headers automatically. There is no configuration step and no way to accidentally omit them:</p>
+      ${table(
+        ['Header', 'Value'],
+        [
+          ['<code>X-Content-Type-Options</code>', '<code>nosniff</code>'],
+          ['<code>X-Frame-Options</code>', '<code>DENY</code>'],
+          ['<code>Referrer-Policy</code>', '<code>strict-origin-when-cross-origin</code>'],
+          ['<code>Permissions-Policy</code>', '<code>camera=(), microphone=(), geolocation=()</code>'],
+          ['<code>Cross-Origin-Opener-Policy</code>', '<code>same-origin</code>'],
+          ['<code>Cross-Origin-Resource-Policy</code>', '<code>same-origin</code>'],
+        ]
+      )}
+      <p>These headers are applied automatically — no configuration needed.</p>
+
+      ${section('browser-support', 'Browser support')}
+      <p>Pulse ships modern JavaScript and CSS without transpilation or polyfills. The effective minimum is set by two features:</p>
+      ${table(
+        ['Constraint', 'Chrome', 'Firefox', 'Safari', 'Edge', 'Since'],
+        [
+          ['<code>?.</code> optional chaining (JS)', '80', '74', '13.1', '80', 'Feb – Mar 2020'],
+          ['<code>gap</code> on flexbox (CSS)', '84', '63', '14.1', '84', 'Aug 2020 – Apr 2021'],
+        ]
+      )}
+      <p>In practice, <strong>Safari 14.1 (April 2021) is the combined floor</strong> — browsers released after that date support everything Pulse uses. This covers roughly 95%+ of global traffic.</p>
+      ${callout('note', 'No explicit <code>target</code> is set in the esbuild config, so syntax ships as written. If you need to support older browsers, set <code>target</code> in <code>scripts/build.js</code> and esbuild will downcompile optional chaining and other modern syntax automatically.')}
+
+      ${section('cls', 'Preventing layout shift (CLS)')}
+      <p>Pulse targets 0.00 CLS. Layout shift is caused by elements that change size or position after the initial paint. These rules prevent it:</p>
+      <ul>
+        <li>Always set <code>width</code> and <code>height</code> on images (use the <code>img()</code> helper)</li>
+        <li>Never inject content above existing content after page load</li>
+        <li>Use <code>aspect-ratio</code> CSS for embeds (videos, iframes)</li>
+        <li>Avoid loading web fonts that cause FOUT — use <code>font-display: swap</code> or system fonts</li>
+      </ul>
+
+      ${section('lcp', 'Optimising LCP')}
+      <p>LCP (Largest Contentful Paint) is typically your hero image or largest heading. Tips:</p>
+      <ul>
+        <li>Use <code>priority: true</code> on the LCP image — sets <code>fetchpriority="high"</code> and <code>loading="eager"</code></li>
+        <li>Avoid blocking server fetches — use <code>stream</code> so the shell renders without waiting for data</li>
+        <li>Keep your hero HTML inline (SSR) — never rely on client JS to render the LCP element</li>
+        <li>Use modern image formats (AVIF, WebP) via the <code>picture()</code> helper</li>
+      </ul>
+
+      ${callout('warning', 'Never render your LCP element (hero image, main heading) client-side. If it requires a client JS import or a dynamic import, it will not paint until JS executes — pushing LCP from &lt;100ms to &gt;500ms.')}
+    `,
+  }),
+}

package/docs/src/pages/persist.js

@@ -0,0 +1,88 @@
+import { renderLayout, h1, lead, section, sub, codeBlock, callout, table } from '../lib/layout.js'
+import { prevNext } from '../lib/nav.js'
+import { highlight } from '../lib/highlight.js'
+
+const { prev, next } = prevNext('/persist')
+
+export default {
+  route: '/persist',
+  meta: {
+    title: 'Persist — Pulse Docs',
+    description: 'Persist client state across page refreshes using localStorage.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/persist',
+    prev,
+    next,
+    content: `
+      ${h1('Persist')}
+      ${lead('The <code>persist</code> field declares which state keys survive page refreshes. Everything else resets. The list is explicit — nothing is persisted unless it is named here, and sensitive data should never appear in it.')}
+
+      ${section('declaring', 'Declaring persistence')}
+      <p><code>persist</code> is an array of dot-path strings. Each path points to a key in state that should be saved:</p>
+      ${codeBlock(highlight(`export default {
+  route: '/settings',
+  state: {
+    theme:       'light',
+    fontSize:    16,
+    sidebarOpen: true,
+    user: {
+      name:        '',
+      preferences: { notifications: true, newsletter: false },
+    },
+  },
+  persist: [
+    'theme',
+    'fontSize',
+    'user.preferences',
+  ],
+  // ...
+}`, 'js'))}
+      <p>In this example, <code>theme</code>, <code>fontSize</code>, and the entire <code>user.preferences</code> sub-object are saved to <code>localStorage</code>. The <code>sidebarOpen</code> key and <code>user.name</code> are session-only — they reset on each visit.</p>
+
+      ${section('how-it-works', 'How it works')}
+      <p>On every state update, Pulse serialises the persisted keys and writes them to <code>localStorage</code> under a key derived from the page route. On the next mount, persisted values are read back and merged over the spec's initial state before the view renders.</p>
+
+      ${table(
+        ['Step', 'What happens'],
+        [
+          ['First visit', 'State initialised from <code>spec.state</code>. Nothing in storage yet.'],
+          ['User interacts', 'Mutations update state. Persisted keys are written to <code>localStorage</code>.'],
+          ['Page refresh / return visit', 'Persisted values loaded from storage and merged over initial state. View renders with restored state.'],
+        ]
+      )}
+
+      ${section('dot-paths', 'Dot-path notation')}
+      <p>Persist keys use the same dot-path notation as <a href="/validation">validation</a>. Entire top-level keys or specific nested sub-objects can be persisted:</p>
+      ${codeBlock(highlight(`persist: [
+  'theme',                    // top-level key
+  'user.preferences',         // nested sub-object (entire object is saved)
+  'cart.items',               // array of cart items
+]`, 'js'))}
+      ${callout('note', 'When persisting a nested path like <code>user.preferences</code>, the <em>entire value at that path</em> is saved and restored — not individual sub-keys within it.')}
+
+      ${section('storage-key', 'Storage key')}
+      <p>Pulse stores persisted state under <code>pulse:[route]</code> in <code>localStorage</code>. For example, a spec with <code>route: \'/settings\'</code> uses the key <code>pulse:/settings</code>. This namespacing prevents collisions between pages.</p>
+
+      ${section('ssr', 'SSR and persistence')}
+      <p>On the server, <code>localStorage</code> does not exist. The server always renders with the spec's initial state. Persisted values are applied on the client after hydration — before the first mutation, after mount.</p>
+      ${callout('warning', 'If SSR and client state diverge significantly due to persisted values, a content flash may occur. Best practice: keep persisted state to preferences and settings that do not affect the main page content.')}
+
+      ${section('clearing', 'Clearing persisted state')}
+      <p>To clear persisted state programmatically, remove the relevant key from <code>localStorage</code>:</p>
+      ${codeBlock(highlight(`localStorage.removeItem('pulse:/settings')`, 'js'))}
+      <p>Or use a mutation that resets the persisted fields to their initial values — Pulse will save the reset values on the next update.</p>
+
+      ${section('best-practices', 'Best practices')}
+      <ul>
+        <li>Persist preferences and settings (theme, language, layout choices)</li>
+        <li>Persist shopping cart contents or draft form data</li>
+        <li>Never persist sensitive data (tokens, passwords, PII) — <code>localStorage</code> is not secure storage</li>
+        <li>Never persist data that must be authoritative — use <a href="/server-data">server data</a> for anything that should be fresh from the server</li>
+        <li>Keep persisted payloads small — <code>localStorage</code> has a ~5 MB limit and blocks the main thread if abused</li>
+      </ul>
+    `,
+  }),
+}

package/docs/src/pages/project-structure.js

@@ -0,0 +1,90 @@
+import { renderLayout, h1, lead, section, sub, codeBlock, callout, table } from '../lib/layout.js'
+import { prevNext } from '../lib/nav.js'
+import { highlight } from '../lib/highlight.js'
+
+const { prev, next } = prevNext('/project-structure')
+
+export default {
+  route: '/project-structure',
+  meta: {
+    title: 'Project Structure — Pulse Docs',
+    description: 'Recommended directory layout for a Pulse application.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/project-structure',
+    prev,
+    next,
+    content: `
+      ${h1('Project Structure')}
+      ${lead('Pulse enforces a single convention: one spec per page, one directory per concern. The structure is not a recommendation — it is how the framework discovers and registers your pages. There is nothing to configure because there is nothing to decide.')}
+
+      ${section('layout', 'Layout')}
+      ${codeBlock(highlight(`my-app/
+├── package.json
+├── public/                # static assets served directly
+│   ├── app.css
+│   └── dist/              # generated bundles (pulse build)
+│       ├── manifest.json
+│       ├── runtime-[hash].js
+│       └── [name].boot-[hash].js
+└── src/
+    ├── pages/             # one file per page — auto-discovered
+    │   ├── home.js
+    │   ├── about.js
+    │   └── contact.js
+    ├── lib/               # shared helpers
+    │   └── db.js
+    └── components/        # shared view fragments (optional)
+        └── card.js`, 'bash'))}
+
+      ${section('pages', 'src/pages/')}
+      <p>Each file in <code>src/pages/</code> exports a single spec as the default export. <code>pulse dev</code> auto-discovers every file in this directory and registers it as a route. There is no route registry to maintain — the file is the registration.</p>
+
+      ${callout('note', 'Routes are derived from filenames by default (<code>about.js</code> → <code>/about</code>). For dynamic segments, <code>route</code> is set explicitly in the spec.')}
+
+      ${section('public', 'public/')}
+      <p>Static files served directly — CSS, fonts, images. Referenced via <code>meta.styles</code> in the spec. The <code>dist/</code> subdirectory is generated by <code>pulse build</code>. Its contents are content-hashed and must not be edited manually.</p>
+
+      ${table(
+        ['Path', 'Purpose'],
+        [
+          ['<code>public/app.css</code>', 'Your global stylesheet — reference it in spec <code>meta.styles</code>'],
+          ['<code>public/dist/</code>', 'Generated bundles from <code>npm run build</code> — do not edit manually'],
+          ['<code>public/dist/manifest.json</code>', 'Maps spec hydrate paths to hashed bundle filenames'],
+        ]
+      )}
+
+      ${section('lib', 'src/lib/')}
+      <p>Shared helpers used across multiple pages — database clients, API wrappers, utility functions. Imported directly into specs. Plain JavaScript modules with no framework coupling — they work identically in tests, scripts, or other contexts.</p>
+
+      ${section('components', 'src/components/ (optional)')}
+      <p>Reusable view fragments. Since views are just functions that return HTML strings, a component is simply a function:</p>
+
+      ${codeBlock(highlight(`// src/components/card.js
+export function card({ title, body }) {
+  return \`
+    <div class="card">
+      <h2>\${title}</h2>
+      <p>\${body}</p>
+    </div>
+  \`
+}`, 'js'), 'src/components/card.js')}
+
+      ${codeBlock(highlight(`// src/pages/home.js
+import { card } from '../components/card.js'
+
+export default {
+  route: '/',
+  state: {},
+  view: () => card({ title: 'Hello', body: 'Welcome to Pulse' }),
+}`, 'js'), 'src/pages/home.js')}
+
+      ${section('one-file-per-page', 'One file per page')}
+      <p>Pulse enforces <strong>one spec per file</strong>. Every page is self-contained — state, view, mutations, actions, and validation in one place. This is not a style preference. It is how the framework eliminates the question of where things live.</p>
+
+      ${callout('tip', 'For large pages, view fragments and helpers can be imported from other modules. The spec file remains the coordination point — the structure is always clear regardless of how the implementation is organised.')}
+    `,
+  }),
+}

package/docs/src/pages/prompt-examples.js

@@ -0,0 +1,186 @@
+import { renderLayout, h1, lead } from '../lib/layout.js'
+import { prevNext } from '../lib/nav.js'
+
+const { prev, next } = prevNext('/prompt-examples')
+
+function promptCard({ tag, prompt, produces }) {
+  return `
+    <div class="prompt-card">
+      <div class="prompt-tag">${tag}</div>
+      <blockquote class="prompt-text">${prompt}</blockquote>
+      <p class="prompt-produces">${produces}</p>
+    </div>`
+}
+
+function promptGroup(title, cards) {
+  return `
+    <div class="prompt-group">
+      <h3 class="prompt-group-title">${title}</h3>
+      <div class="prompt-grid">
+        ${cards.map(promptCard).join('')}
+      </div>
+    </div>`
+}
+
+export default {
+  route: '/prompt-examples',
+  meta: {
+    title: 'Prompt Examples — Pulse Docs',
+    description: 'Real prompts for building Pulse pages with your AI agent — from creating pages to authentication, performance audits, and integrations.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/prompt-examples',
+    prev,
+    next,
+    content: `
+      ${h1('Prompt Examples')}
+      ${lead('These prompts produce correct Pulse specs because the framework constrains the output. The agent works within a defined structure — there is no ambiguity about where state lives, how data is fetched, or how validation is wired.')}
+
+      ${promptGroup('Creating pages', [
+        {
+          tag: 'New page',
+          prompt: 'Create a page at /about with a heading, a short paragraph about the company, and a link back to the home page.',
+          produces: 'A static page spec with <code>route</code>, <code>meta</code>, and a <code>view</code> returning the HTML.',
+        },
+        {
+          tag: 'Dynamic route',
+          prompt: 'Create a blog post page at /posts/:slug. It should fetch the post from the database by slug and display the title, published date, and body content. If no post is found, return a 404.',
+          produces: 'A spec with a parameterised <code>route</code>, a <code>server.data</code> fetcher using <code>ctx.params.slug</code>, and a 404 raw response if the post is missing.',
+        },
+        {
+          tag: 'Listing page',
+          prompt: 'Create a paginated list of articles at /articles. Read the ?page query parameter to fetch the right slice. Show 10 articles per page with previous and next links.',
+          produces: 'A spec with <code>server.data</code> reading <code>ctx.query.page</code>, pagination state, and prev/next links rendered in the view.',
+        },
+      ])}
+
+      ${promptGroup('State & interactions', [
+        {
+          tag: 'Live filter',
+          prompt: 'Add a search input to the /products page that filters the visible product list as the user types. Keep the full product list in server data and filter it in the view.',
+          produces: 'A mutation bound to <code>data-event="input:setQuery"</code> that updates a <code>query</code> state field, with the view filtering <code>server.data.products</code> against it.',
+        },
+        {
+          tag: 'Toggle',
+          prompt: 'Add a show/hide toggle to the FAQ page. Each question should expand its answer when clicked and collapse when clicked again.',
+          produces: 'An <code>openId</code> state field and a <code>toggle</code> mutation. The view renders answers conditionally based on whether their id matches <code>openId</code>.',
+        },
+        {
+          tag: 'Tabs',
+          prompt: 'The /dashboard page has three tabs: Overview, Activity, and Settings. Clicking a tab should show its panel and hide the others without a page reload.',
+          produces: 'An <code>activeTab</code> state field, a <code>setTab</code> mutation, and tab panels rendered conditionally in the view.',
+        },
+      ])}
+
+      ${promptGroup('Forms & validation', [
+        {
+          tag: 'Contact form',
+          prompt: 'Add a contact form at /contact with name, email, and message fields. All three are required. Email must be a valid format. Show inline errors on failure. Show a success message on submission.',
+          produces: 'A spec with <code>validation</code> rules, an <code>actions.submit</code> with <code>validate: true</code>, and <code>onSuccess</code>/<code>onError</code> state transitions.',
+        },
+        {
+          tag: 'Multi-step form',
+          prompt: 'Create a multi-step signup form at /signup with three steps: account details, personal info, and confirmation. Show a step indicator at the top. Only advance when the current step is valid.',
+          produces: 'A <code>step</code> state field, step-specific validation, a <code>next</code> action that validates before advancing, and a view that renders the active step panel.',
+        },
+        {
+          tag: 'Constraints',
+          prompt: 'The quantity input on the /cart page should never go below 1 or above 99. Enforce this on the server — not just in the UI.',
+          produces: 'A <code>constraints</code> block with <code>quantity: { min: 1, max: 99 }</code> that the framework enforces after every mutation, regardless of what the client sends.',
+        },
+      ])}
+
+      ${promptGroup('Server data & actions', [
+        {
+          tag: 'Dashboard data',
+          prompt: 'The /dashboard page should show the logged-in user\'s name and their last 5 orders. Fetch both in parallel.',
+          produces: 'A <code>server.data</code> fetcher that runs two queries concurrently with <code>Promise.all</code> and passes the results to the view as <code>server.data.user</code> and <code>server.data.orders</code>.',
+        },
+        {
+          tag: 'Async action',
+          prompt: 'Add a Delete button to each row in the /users table. It should send a DELETE request to the API, remove the row on success, and show an error message on failure.',
+          produces: 'An action with <code>onStart</code> setting a loading flag, <code>run</code> making the API call, <code>onSuccess</code> removing the item from state, and <code>onError</code> setting an error message.',
+        },
+        {
+          tag: 'File upload',
+          prompt: 'Add an avatar upload form to /settings. The user picks a file, it uploads to storage, and the page shows the new avatar on success.',
+          produces: 'An action whose <code>run</code> reads the file from <code>FormData</code>, converts it to an <code>ArrayBuffer</code>, and uploads it to storage. <code>onSuccess</code> updates the avatar URL in state.',
+        },
+      ])}
+
+      ${promptGroup('Authentication', [
+        {
+          tag: 'Login page',
+          prompt: 'Create a login page at /login with email and password fields. On success, set an httpOnly session cookie and redirect to /dashboard. Show an error message if credentials are wrong.',
+          produces: 'A raw response action that verifies credentials, sets <code>Set-Cookie</code> headers with <code>httpOnly; SameSite=Strict</code>, and redirects. Failed logins return the form with an error state.',
+        },
+        {
+          tag: 'Protected route',
+          prompt: 'Protect the /dashboard page so only logged-in users can access it. Redirect anyone without a valid session to /login.',
+          produces: 'A <code>guard</code> function that reads the session cookie, verifies it, and returns a redirect response if invalid.',
+        },
+        {
+          tag: 'Logout',
+          prompt: 'Add a logout button to the nav. It should clear the session and redirect to /login.',
+          produces: 'A page spec at <code>/logout</code> using the raw response spec (<code>contentType</code> + <code>render</code>) that sets the session cookie to <code>maxAge: 0</code> and issues a 302 redirect.',
+        },
+      ])}
+
+      ${promptGroup('Streaming SSR', [
+        {
+          tag: 'Deferred content',
+          prompt: 'The /feed page is slow because it waits for the activity feed before painting anything. Make it stream — show the page chrome instantly and load the feed in the background.',
+          produces: 'A <code>stream</code> block with <code>shell: [\'header\']</code> and <code>deferred: [\'feed\']</code>. The view becomes a keyed object of named segment functions.',
+        },
+        {
+          tag: 'Multiple segments',
+          prompt: 'The /home page has a hero, a trending section, and a recommendations section. The hero should appear instantly. The other two can load as data resolves.',
+          produces: 'Three view segments — <code>hero</code> in the shell, <code>trending</code> and <code>recommendations</code> deferred. Each fetches its own data independently.',
+        },
+      ])}
+
+      ${promptGroup('Performance & tooling', [
+        {
+          tag: 'Lighthouse audit',
+          prompt: 'Run a Lighthouse audit across all pages and show me the results.',
+          produces: 'The agent runs <code>/pulse-report</code>, which audits every registered route and opens the results dashboard.',
+        },
+        {
+          tag: 'Score thresholds',
+          prompt: 'Make the audit fail if any page scores below 90 for performance or below 95 for accessibility.',
+          produces: 'A <code>lighthouse</code> block in <code>pulse.config.js</code> with <code>performance: 90</code> and <code>accessibility: 95</code>.',
+        },
+        {
+          tag: 'Load test',
+          prompt: 'Load test the /api/data endpoint with 50 concurrent connections for 30 seconds and tell me the p99 latency.',
+          produces: 'The agent runs <code>/pulse-load</code> against that route with the specified parameters and reports the results.',
+        },
+        {
+          tag: 'Environment config',
+          prompt: 'Set up a staging environment so I can run audits against https://staging.myapp.com instead of localhost.',
+          produces: 'An <code>environments.staging</code> block in <code>pulse.config.js</code> with the remote URL. The agent uses it when running <code>/pulse-report</code> or <code>/pulse-load</code>.',
+        },
+      ])}
+
+      ${promptGroup('Integrations', [
+        {
+          tag: 'Supabase query',
+          prompt: 'The /profile page should load the current user\'s row from the Supabase users table. It should only return data the logged-in user owns.',
+          produces: 'A <code>server.data</code> fetcher using the Supabase public client initialised with the user\'s access token, so Row Level Security applies automatically.',
+        },
+        {
+          tag: 'Supabase auth',
+          prompt: 'Use Supabase for authentication. The login form should call Supabase\'s signInWithPassword and store the tokens in httpOnly cookies.',
+          produces: 'A login action that calls <code>supabase.auth.signInWithPassword</code>, reads the session tokens from the response, and sets them as <code>httpOnly; SameSite=Strict</code> cookies.',
+        },
+        {
+          tag: 'Stripe checkout',
+          prompt: 'Add a checkout button to the /pricing page for the Pro plan. Clicking it should create a Stripe Checkout Session and redirect the user to the Stripe-hosted page.',
+          produces: 'An action whose <code>run</code> calls the Stripe API to create a session and returns the checkout URL. <code>onSuccess</code> triggers a redirect via state.',
+        },
+      ])}
+    `,
+  }),
+}

package/docs/src/pages/raw-responses.js

@@ -0,0 +1,124 @@
+import { renderLayout, h1, lead, section, sub, codeBlock, callout, table } from '../lib/layout.js'
+import { prevNext } from '../lib/nav.js'
+import { highlight } from '../lib/highlight.js'
+
+const { prev, next } = prevNext('/raw-responses')
+
+export default {
+  route: '/raw-responses',
+  meta: {
+    title: 'Raw Responses — Pulse Docs',
+    description: 'Return non-HTML responses from Pulse specs — RSS, XML, JSON, and other content types.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/raw-responses',
+    prev,
+    next,
+    content: `
+      ${h1('Raw Responses')}
+      ${lead('Setting <code>contentType</code> switches a spec from the HTML pipeline to a raw response mode. The view returns the response body directly — no doctype, no hydration script. Security headers and compression still apply.')}
+
+      ${section('basics', 'The basics')}
+      <p>Set <code>contentType</code> to any valid MIME type. When present, the normal HTML wrapper (doctype, head, body, hydration script) is skipped. The <code>render</code> function receives <code>(ctx, serverState)</code> and returns a string:</p>
+      ${codeBlock(highlight(`export default {
+  route: '/feed.xml',
+  contentType: 'application/rss+xml',
+  state: {},
+  server: {
+    data: async () => ({
+      posts: await db.posts.latest(20),
+    }),
+  },
+  view: (ctx, server) => \`<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0">
+  <channel>
+    <title>My Blog</title>
+    <link>https://example.com</link>
+    <description>Recent posts</description>
+    \${server.posts.map(post => \`
+    <item>
+      <title>\${esc(post.title)}</title>
+      <link>https://example.com/blog/\${post.slug}</link>
+      <pubDate>\${new Date(post.date).toUTCString()}</pubDate>
+      <description>\${esc(post.excerpt)}</description>
+    </item>
+    \`).join('')}
+  </channel>
+</rss>\`,
+}`, 'js'))}
+
+      ${section('json', 'JSON API endpoints')}
+      ${codeBlock(highlight(`export default {
+  route: '/api/products',
+  contentType: 'application/json',
+  state: {},
+  server: {
+    data: async (ctx) => ({
+      products: await db.products.list({
+        page:     parseInt(ctx.query.page ?? '1', 10),
+        category: ctx.query.category,
+      }),
+    }),
+  },
+  view: (ctx, server) => JSON.stringify({
+    products: server.products,
+    page:     parseInt(ctx.query.page ?? '1', 10),
+  }),
+}`, 'js'))}
+
+      ${section('sitemap', 'XML sitemap')}
+      ${codeBlock(highlight(`export default {
+  route: '/sitemap.xml',
+  contentType: 'application/xml',
+  serverTtl:   3600,
+  state: {},
+  server: {
+    data: async () => ({
+      pages: await db.pages.allPublished(),
+    }),
+  },
+  view: (ctx, server) => \`<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  \${server.pages.map(p => \`
+  <url>
+    <loc>https://example.com\${p.path}</loc>
+    <lastmod>\${p.updatedAt.toISOString().slice(0, 10)}</lastmod>
+  </url>
+  \`).join('')}
+</urlset>\`,
+}`, 'js'))}
+
+      ${section('view-signature', 'View function signature')}
+      <p>For raw responses, the <code>view</code> function signature is <code>(ctx, serverState)</code>, not <code>(state, serverState)</code>. The <code>ctx</code> argument is the request context object with <code>params</code>, <code>query</code>, <code>headers</code>, and <code>cookies</code>.</p>
+      ${callout('note', 'There is no client state (<code>state</code>) for raw response specs — they are purely server-side. The <code>state: {}</code> field is still required for spec validation, but is not used.')}
+
+      ${section('escaping', 'Escaping in XML and HTML')}
+      <p>Pulse does not auto-escape raw response bodies. When returning XML or HTML, escaping all user-supplied and dynamic content is required — unescaped output is an injection vulnerability:</p>
+      ${codeBlock(highlight(`// Simple escape helper for XML/HTML contexts
+function esc(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}`, 'js'))}
+      ${callout('warning', 'Never interpolate raw user data or database content into XML/HTML without escaping. This applies to raw response specs just as much as to HTML view functions.')}
+
+      ${section('caching-raw', 'Caching raw responses')}
+      <p>Raw response specs support the same <code>serverTtl</code> and <code>cache</code> options as HTML specs. For feeds and sitemaps that update infrequently, a generous TTL dramatically reduces server load:</p>
+      ${codeBlock(highlight(`export default {
+  route:       '/feed.xml',
+  contentType: 'application/rss+xml',
+  serverTtl:   300,   // cache data for 5 minutes
+  cache: {
+    public:  true,
+    maxAge:  300,
+  },
+  // ...
+}`, 'js'))}
+    `,
+  }),
+}