@invisibleloop/pulse 0.17.3 → 0.18.0

package/CLAUDE.md

@@ -68,6 +68,13 @@ export const mySpec = {
   // query param, list it here so distinct values get distinct cache entries.
   cacheVary: ['q', 'page'],
 
+  // Sitemap inclusion (when createServer has sitemap: true).
+  // Static routes are included automatically — only set this to:
+  //   false              → exclude this page
+  //   true               → include a guarded page (excluded by default)
+  //   async () => [...]  → enumerate a dynamic :param route's URLs
+  sitemap: async () => (await db.posts.list()).map(p => `/blog/${p.slug}`),
+
   // 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'],
@@ -282,6 +289,11 @@ await createServer(
     healthCheck:     '/healthz',  // built-in health endpoint path, or false to disable
     secret:       process.env.PULSE_SECRET,  // HMAC secret for CSRF tokens — set a stable value
                                   // when running multiple instances (default: random per boot)
+    sitemap:      true,           // auto-serve /sitemap.xml + robots.txt from registered routes
+                                  // also accepts { origin: 'https://mysite.com' } to pin the URL origin;
+                                  // dynamic :param routes contribute via spec.sitemap enumerators;
+                                  // a physical sitemap.xml/robots.txt in staticDir always wins
+    robots:       null,           // robots.txt when sitemap on: null = auto, false = off, string = verbatim
     csp: {                        // extra sources merged into the framework's default CSP
       'style-src': ['https://fonts.googleapis.com'],
       'font-src':  ['https://fonts.gstatic.com'],

package/docs/src/pages/meta.js

@@ -115,6 +115,33 @@ meta: {
 }`, 'js'))}
       ${callout('note', '<strong>Streaming caveat:</strong> when <code>stream: true</code> (the default), the <code>&lt;head&gt;</code> is written before server fetchers resolve, so <code>serverState</code> will be <code>null</code> for streaming responses. If your canonical depends on server data, set <code>stream: false</code> on that spec, or derive it from <code>ctx.params</code> instead.')}
 
+      ${section('sitemap', 'Sitemap & robots.txt')}
+      <p>Pulse generates <code>/sitemap.xml</code> and <code>/robots.txt</code> from the registered routes — enable it with one option:</p>
+      ${codeBlock(highlight(`await createServer(pages, {
+  sitemap: true,                          // or { origin: 'https://mysite.com' } to pin the origin
+})`, 'js'))}
+      <p>Static page routes are included automatically. Excluded by default: the <code>route: '*'</code> not-found page, raw content specs, guarded pages (set <code>sitemap: true</code> on the spec to opt one in), and any page with <code>sitemap: false</code>.</p>
+      <p>Dynamic <code>:param</code> routes can't be enumerated automatically — give them a <code>sitemap</code> enumerator or they are skipped (the server logs a startup hint listing them):</p>
+      ${codeBlock(highlight(`export default {
+  route: '/blog/:slug',
+  sitemap: async () => {
+    const posts = await db.posts.allPublished()
+    return posts.map(p => ({ path: \`/blog/\${p.slug}\`, lastmod: p.updatedAt }))
+  },
+  // entries are '/path' strings or { path, lastmod } objects
+}`, 'js'))}
+      ${table(
+        ['Where', 'Value', 'Effect'],
+        [
+          ['<code>createServer</code>', '<code>sitemap: true | { origin }</code>', 'Enables generation. Origin defaults to the request host; pin it for multi-domain setups.'],
+          ['<code>createServer</code>', '<code>robots: false | string</code>', 'Disable robots.txt, or serve a custom string verbatim. Default auto-generates allow-all + the Sitemap line.'],
+          ['spec', '<code>sitemap: false</code>', 'Exclude this page.'],
+          ['spec', '<code>sitemap: true</code>', 'Include a guarded page that would be excluded by default.'],
+          ['spec', '<code>sitemap: array | function</code>', 'Enumerate URLs — required for dynamic routes.'],
+        ]
+      )}
+      ${callout('note', 'A physical <code>sitemap.xml</code> or <code>robots.txt</code> in <code>staticDir</code> always wins over the generated one — drop a file in <code>public/</code> to take full manual control. For fully hand-built XML, see <a href="/raw-responses#sitemap">Raw Responses</a>.')}
+
       ${section('styles', 'Stylesheets')}
       <p>The <code>styles</code> array accepts any number of stylesheet URLs. They are emitted as <code>&lt;link rel="stylesheet"&gt;</code> tags in the <code>&lt;head&gt;</code> in the order declared:</p>
       ${codeBlock(highlight(`meta: {

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

@@ -66,6 +66,7 @@ export default {
 }`, 'js'))}
 
       ${section('sitemap', 'XML sitemap')}
+      ${callout('tip', 'For most sites you don\'t need a raw spec for this — set <code>sitemap: true</code> in <code>createServer</code> and Pulse generates <code>/sitemap.xml</code> and <code>robots.txt</code> from the registered routes automatically. See <a href="/meta#sitemap">Metadata &amp; SEO</a>. Write a raw sitemap spec only when you need full control over the XML.')}
       ${codeBlock(highlight(`export default {
   route: '/sitemap.xml',
   contentType: 'application/xml',

package/docs/src/pages/server-api.js

@@ -49,6 +49,8 @@ await createServer(entries, options)`, 'js'))}
           ['<code>healthCheck</code>', '<code>string | false</code>', '<code>"/healthz"</code>', 'Path for the built-in health check endpoint. Returns <code>{ status: "ok", uptime }</code>. Set to <code>false</code> to disable. The endpoint bypasses <code>onRequest</code> so load balancers always get a response.'],
           ['<code>resolveBrand</code>', '<code>async (host) => any</code>', '<code>undefined</code>', 'Multi-brand support. Called once per host (cached 60s). Result is attached to <code>ctx.brand</code> and available in <code>guard</code>, <code>server</code>, and <code>meta</code> functions.'],
           ['<code>secret</code>', '<code>string</code>', 'random per boot', 'HMAC secret for CSRF tokens (<a href="/forms">Forms</a>). Set a stable value when running multiple instances so tokens issued by one validate on another.'],
+          ['<code>sitemap</code>', '<code>boolean | { origin }</code>', '<code>false</code>', 'Auto-serve <code>/sitemap.xml</code> + <code>robots.txt</code> from the registered routes. Dynamic <code>:param</code> routes contribute via <code>spec.sitemap</code> enumerators. See <a href="/meta#sitemap">Metadata &amp; SEO</a>.'],
+          ['<code>robots</code>', '<code>string | false</code>', 'auto', 'robots.txt behaviour when sitemap is enabled — <code>false</code> disables, a string is served verbatim.'],
           ['<code>onRequest</code>', '<code>function</code>', '<code>undefined</code>', 'Called on every request before routing. Return <code>false</code> to short-circuit Pulse handling.'],
           ['<code>onError</code>', '<code>function</code>', '<code>undefined</code>', 'Called on unhandled errors. Receives <code>(err, req, res)</code>. See <a href="/error-pages">Error Pages</a>.'],
         ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.17.3",
+  "version": "0.18.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.17.3
+0.18.0

package/src/agent/guide-routing.md

@@ -147,6 +147,31 @@ export default {
 - **Every site should have one** — without it, visitors to a bad URL get the framework's unbranded default 404.
 - 500 errors are customised via `createServer`'s `onError` option, not a spec.
 
+## Sitemap & robots.txt
+
+Enable in `pulse.config.js` / `createServer` — the framework serves `/sitemap.xml` and `/robots.txt` generated from the registered routes:
+
+```js
+// pulse.config.js
+export default {
+  sitemap: true,                              // or { origin: 'https://mysite.com' } to pin the origin
+}
+```
+
+- **Static routes are included automatically.** Excluded by default: `route: '*'`, raw content specs, guarded pages (set `sitemap: true` on the spec to opt a guarded page in), and `sitemap: false` pages.
+- **Dynamic `:param` routes need an enumerator** or they are skipped (a startup hint lists them):
+
+```js
+export default {
+  route:   '/blog/:slug',
+  sitemap: async () => (await db.posts.list()).map(p => ({ path: `/blog/${p.slug}`, lastmod: p.updatedAt })),
+  // entries can be '/path' strings or { path, lastmod } objects
+}
+```
+
+- `robots: false` disables robots.txt; a string serves verbatim. A physical `sitemap.xml`/`robots.txt` in `staticDir` always wins over the generated one.
+- **Always enable this on production sites** — it is one config line and crawlers need it.
+
 ## Canonical URLs
 
 Pulse auto-derives a canonical URL from every request and emits `<link rel="canonical">` in the `<head>`. No config needed in most cases.

package/src/server/index.js

@@ -546,6 +546,11 @@ export async function createServer(entries, options = {}) {
     csp            = {},            // extra CSP sources: { 'style-src': ['https://fonts.googleapis.com'] }
     secret         = null,          // HMAC secret for CSRF tokens — set a stable value when running
                                     // multiple instances; defaults to a random per-boot secret
+    sitemap        = false,         // true | { origin } — auto-serve /sitemap.xml + robots.txt from
+                                    // the registered routes. Dynamic :param routes contribute via
+                                    // spec.sitemap = async () => ['/blog/a', ...]
+    robots         = null,          // robots.txt content when sitemap is enabled:
+                                    // null = auto-generate, false = disable, string = serve verbatim
     onError        = (err, req, res) => defaultErrorHandler(err, req, res, dev),
     onRequest,
     agentMode      = false,        // show agent-active indicator in banner
@@ -614,6 +619,20 @@ export async function createServer(entries, options = {}) {
   // tied to a cookie, so a restart only means in-flight forms re-render once.
   const csrfSecret = secret || crypto.randomBytes(32).toString('hex')
 
+  // Sitemap — track the live spec list (updated on hot reload) and surface a
+  // startup hint for dynamic routes that can't be enumerated automatically.
+  const sitemapEnabled = !!sitemap
+  const sitemapOrigin  = (typeof sitemap === 'object' && sitemap?.origin) ? String(sitemap.origin).replace(/\/$/, '') : null
+  let   allSpecs       = specs
+  if (sitemapEnabled && !quiet) {
+    const unenumerated = specs.filter(s =>
+      !s.contentType && s.route !== '*' && s.route.includes(':') && s.sitemap === undefined
+    )
+    if (unenumerated.length > 0) {
+      console.log(`  ℹ sitemap: ${unenumerated.length} dynamic route${unenumerated.length === 1 ? '' : 's'} not in the sitemap — add \`sitemap: async () => ['/path', …]\` to enumerate: ${unenumerated.map(s => s.route).join(', ')}`)
+    }
+  }
+
   // 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
@@ -658,6 +677,39 @@ export async function createServer(entries, options = {}) {
         if (served) return
       }
 
+      // Auto-generated sitemap.xml + robots.txt — after static serving so a
+      // physical file in staticDir always wins over the generated one.
+      if (sitemapEnabled && (req.method === 'GET' || req.method === 'HEAD') &&
+          (pathname === '/sitemap.xml' || (pathname === '/robots.txt' && robots !== false))) {
+        const origin = sitemapOrigin ||
+          `${req.headers['x-forwarded-proto'] || 'http'}://${req.headers['x-forwarded-host'] || req.headers.host || `localhost:${port}`}`
+
+        let body, contentType
+        if (pathname === '/robots.txt') {
+          contentType = 'text/plain; charset=utf-8'
+          body = typeof robots === 'string'
+            ? robots
+            : `User-agent: *\nAllow: /\n\nSitemap: ${origin}/sitemap.xml\n`
+        } else {
+          contentType = 'application/xml; charset=utf-8'
+          const entries = await collectSitemapEntries(allSpecs, trailingSlash)
+          body = buildSitemapXml(entries, origin)
+        }
+
+        const encoding = negotiateEncoding(req)
+        const buf      = await compressBuffer(Buffer.from(body, 'utf8'), encoding)
+        const headers  = {
+          'Content-Type':  contentType,
+          'Cache-Control': dev ? 'no-store' : 'public, max-age=3600',
+          'Vary':          'Accept-Encoding',
+          ...SECURITY_HEADERS, ...httpsHeaders(req),
+        }
+        if (encoding) headers['Content-Encoding'] = encoding
+        res.writeHead(200, headers)
+        res.end(req.method === 'HEAD' ? undefined : buf)
+        return
+      }
+
       // Trailing slash normalisation — GET/HEAD only (redirects don't apply to POST etc.)
       if ((req.method === 'GET' || req.method === 'HEAD') && pathname !== '/') {
         if (trailingSlash === 'remove' && pathname.endsWith('/')) {
@@ -948,7 +1000,8 @@ export async function createServer(entries, options = {}) {
     shutdown,
     updateSpecs(newSpecs) {
       notFoundSpec = newSpecs.find(s => s.route === '*') || null
-      router = buildRouter(newSpecs.filter(s => s.route !== '*'))
+      router       = buildRouter(newSpecs.filter(s => s.route !== '*'))
+      allSpecs     = newSpecs
     }
   }
 }
@@ -1671,6 +1724,94 @@ function escHtml(str) {
     .replace(/'/g, ''')
 }
 
+/**
+ * Collect sitemap entries from the registered specs.
+ *
+ * Inclusion rules:
+ *   - page specs with static routes are included automatically
+ *   - route '*' (not-found), raw content specs, and spec.sitemap === false are excluded
+ *   - guarded pages are excluded by default (likely auth-gated) — set spec.sitemap
+ *     to true/array/function to include them explicitly
+ *   - dynamic :param routes contribute only via spec.sitemap — an array of paths
+ *     or an async function returning one. Entries can be strings or
+ *     { path, lastmod } objects.
+ *
+ * @param {Array} specs
+ * @param {'remove'|'add'|'allow'} trailingSlash
+ * @returns {Promise<Array<{ path: string, lastmod?: string }>>}
+ */
+async function collectSitemapEntries(specs, trailingSlash) {
+  const entries = []
+
+  const normalise = (item) => {
+    const e = typeof item === 'string' ? { path: item } : { path: item?.path, lastmod: item?.lastmod }
+    if (!e.path || typeof e.path !== 'string' || !e.path.startsWith('/')) return null
+    // Apply the trailing-slash mode so sitemap URLs match the canonical form
+    if (e.path !== '/') {
+      if (trailingSlash === 'add'    && !e.path.endsWith('/')) e.path = e.path + '/'
+      if (trailingSlash !== 'add'    &&  e.path.endsWith('/')) e.path = e.path.slice(0, -1)
+    }
+    return e
+  }
+
+  for (const spec of specs) {
+    if (spec.contentType || spec.route === '*' || spec.sitemap === false) continue
+
+    const isDynamic = spec.route.includes(':')
+
+    if (typeof spec.sitemap === 'function') {
+      try {
+        const list = await spec.sitemap()
+        for (const item of (Array.isArray(list) ? list : [])) {
+          const e = normalise(item)
+          if (e) entries.push(e)
+        }
+      } catch (err) {
+        // An enumerator failure must not take down the whole sitemap
+        console.error(`[Pulse] sitemap enumerator for "${spec.route}" failed:`, err.message)
+      }
+      continue
+    }
+
+    if (Array.isArray(spec.sitemap)) {
+      for (const item of spec.sitemap) {
+        const e = normalise(item)
+        if (e) entries.push(e)
+      }
+      continue
+    }
+
+    if (isDynamic) continue                                          // no enumerator → skip
+    if (typeof spec.guard === 'function' && spec.sitemap !== true) continue  // auth-gated by default
+
+    const e = normalise(spec.route)
+    if (e) entries.push(e)
+  }
+
+  // Dedupe by path, preserving first occurrence (which may carry lastmod)
+  const seen = new Set()
+  return entries.filter(e => seen.has(e.path) ? false : (seen.add(e.path), true))
+}
+
+/** Escape a value for XML text content. */
+function escXml(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
+}
+
+/** Build the sitemap XML document from collected entries. */
+function buildSitemapXml(entries, origin) {
+  const urls = entries.map(e => {
+    const lastmod = e.lastmod ? `\n    <lastmod>${escXml(e.lastmod)}</lastmod>` : ''
+    return `  <url>\n    <loc>${escXml(origin + e.path)}</loc>${lastmod}\n  </url>`
+  }).join('\n')
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>\n`
+}
+
 /**
  * Derive the CSRF token for a cookie id: HMAC-SHA256(secret, id), base64url.
  * The token goes in the form's hidden _csrf field; the id stays in an HttpOnly

package/src/server/server.test.js

@@ -1446,6 +1446,120 @@ await test('submit pages are excluded from the in-process page cache', async ()
 
 // ---------------------------------------------------------------------------
 
+console.log('\nSitemap + robots.txt\n')
+
+const aboutSpec   = { route: '/about', view: () => '<main id="main-content">About</main>' }
+const blogSpec    = {
+  route:   '/blog/:slug',
+  sitemap: async () => ['/blog/first-post', { path: '/blog/second-post', lastmod: '2026-01-15' }],
+  server:  { post: async (ctx) => ({ slug: ctx.params.slug }) },
+  view:    (_s, server) => `<main id="main-content">${server.post.slug}</main>`,
+}
+const secretSpec  = { route: '/admin', guard: async () => {}, view: () => '<main id="main-content">admin</main>' }
+const hiddenSpec  = { route: '/internal', sitemap: false, view: () => '<main id="main-content">internal</main>' }
+
+await test('sitemap: true serves /sitemap.xml with static routes', async () => {
+  await withServer([helloSpec, aboutSpec], { stream: false, sitemap: true }, async (port) => {
+    const { status, headers, body } = await get(port, '/sitemap.xml')
+    assert(status === 200, `Expected 200, got ${status}`)
+    assert(headers['content-type'].includes('application/xml'), `Expected XML, got ${headers['content-type']}`)
+    assert(body.includes(`<loc>http://localhost:${port}/hello</loc>`), `Missing /hello: ${body}`)
+    assert(body.includes(`<loc>http://localhost:${port}/about</loc>`), `Missing /about: ${body}`)
+  })
+})
+
+await test('dynamic routes contribute via spec.sitemap enumerator (with lastmod)', async () => {
+  await withServer([blogSpec], { stream: false, sitemap: true, quiet: true }, async (port) => {
+    const { body } = await get(port, '/sitemap.xml')
+    assert(body.includes('/blog/first-post</loc>'), `Missing enumerated path: ${body}`)
+    assert(body.includes('/blog/second-post</loc>'), 'Missing second enumerated path')
+    assert(body.includes('<lastmod>2026-01-15</lastmod>'), 'Missing lastmod')
+  })
+})
+
+await test('dynamic routes without an enumerator are skipped, not broken', async () => {
+  const bare = { route: '/items/:id', server: { i: async (ctx) => ctx.params.id }, view: (_s, s) => `<main id="main-content">${s.i}</main>` }
+  await withServer([helloSpec, bare], { stream: false, sitemap: true, quiet: true }, async (port) => {
+    const { status, body } = await get(port, '/sitemap.xml')
+    assert(status === 200)
+    assert(!body.includes(':id'), `Raw :param leaked into sitemap: ${body}`)
+    assert(body.includes('/hello</loc>'), 'Static route should still be present')
+  })
+})
+
+await test('guarded pages, route "*", and sitemap:false are excluded', async () => {
+  const nf = { route: '*', view: () => '<main id="main-content">404</main>' }
+  await withServer([helloSpec, secretSpec, hiddenSpec, nf], { stream: false, sitemap: true }, async (port) => {
+    const { body } = await get(port, '/sitemap.xml')
+    assert(!body.includes('/admin'), 'Guarded page must be excluded by default')
+    assert(!body.includes('/internal'), 'sitemap:false page must be excluded')
+    assert(!body.includes('<loc>http://localhost:' + port + '/*'), 'route * must be excluded')
+    assert(body.includes('/hello</loc>'))
+  })
+})
+
+await test('a guarded page opts in with sitemap: true', async () => {
+  const publicGuarded = { route: '/landing', guard: async () => {}, sitemap: true, view: () => '<main id="main-content">x</main>' }
+  await withServer([publicGuarded], { stream: false, sitemap: true }, async (port) => {
+    const { body } = await get(port, '/sitemap.xml')
+    assert(body.includes('/landing</loc>'), `Expected opted-in guarded page: ${body}`)
+  })
+})
+
+await test('robots.txt is generated and points at the sitemap', async () => {
+  await withServer([helloSpec], { stream: false, sitemap: true }, async (port) => {
+    const { status, body } = await get(port, '/robots.txt')
+    assert(status === 200)
+    assert(body.includes('User-agent: *'), `Missing user-agent: ${body}`)
+    assert(body.includes(`Sitemap: http://localhost:${port}/sitemap.xml`), `Missing sitemap line: ${body}`)
+  })
+})
+
+await test('robots: false disables robots.txt; custom string is served verbatim', async () => {
+  await withServer([helloSpec], { stream: false, sitemap: true, robots: false }, async (port) => {
+    const { status } = await get(port, '/robots.txt')
+    assert(status === 404, `Expected 404 with robots:false, got ${status}`)
+  })
+  await withServer([helloSpec], { stream: false, sitemap: true, robots: 'User-agent: *\nDisallow: /private\n' }, async (port) => {
+    const { body } = await get(port, '/robots.txt')
+    assert(body.includes('Disallow: /private'), 'Expected custom robots content')
+  })
+})
+
+await test('sitemap origin can be pinned via { origin }', async () => {
+  await withServer([helloSpec], { stream: false, sitemap: { origin: 'https://mysite.com' } }, async (port) => {
+    const { body } = await get(port, '/sitemap.xml')
+    assert(body.includes('<loc>https://mysite.com/hello</loc>'), `Expected pinned origin: ${body}`)
+    const robotsRes = await get(port, '/robots.txt')
+    assert(robotsRes.body.includes('Sitemap: https://mysite.com/sitemap.xml'), 'robots should use pinned origin')
+  })
+})
+
+await test('trailingSlash "add" is reflected in sitemap URLs', async () => {
+  await withServer([helloSpec, aboutSpec], { stream: false, sitemap: true, trailingSlash: 'add' }, async (port) => {
+    const { body } = await get(port, '/sitemap.xml')
+    assert(body.includes('/about/</loc>'), `Expected trailing slash on URLs: ${body}`)
+  })
+})
+
+await test('sitemap disabled by default — /sitemap.xml is 404', async () => {
+  await withServer([helloSpec], { stream: false }, async (port) => {
+    const { status } = await get(port, '/sitemap.xml')
+    assert(status === 404, `Expected 404 when sitemap not enabled, got ${status}`)
+  })
+})
+
+await test('a failing enumerator does not take down the sitemap', async () => {
+  const broken = { route: '/x/:id', sitemap: async () => { throw new Error('db down') }, server: { i: async () => 1 }, view: (_s, s) => `<main id="main-content">${s.i}</main>` }
+  await withServer([helloSpec, broken], { stream: false, sitemap: true, quiet: true }, async (port) => {
+    const { status, body } = await get(port, '/sitemap.xml')
+    assert(status === 200, `Expected 200 despite enumerator failure, got ${status}`)
+    assert(body.includes('/hello</loc>'), 'Other routes should still be listed')
+  })
+})
+
+// ---------------------------------------------------------------------------
+
 console.log('\nMalformed request handling\n')
 
 await test('malformed percent-encoding in path returns 404, not 500', async () => {

package/src/spec/schema.js

@@ -153,6 +153,25 @@ export function validateSpec(spec) {
     }
   }
 
+  // sitemap — inclusion control for the auto-generated sitemap (createServer { sitemap: true })
+  //   false          → exclude this page
+  //   true           → include a guarded static page that would be excluded by default
+  //   array/function → enumerate paths (required for dynamic :param routes)
+  if (spec.sitemap !== undefined) {
+    const t = spec.sitemap
+    const ok = typeof t === 'boolean' || typeof t === 'function' || Array.isArray(t)
+    if (!ok) {
+      errors.push('spec.sitemap must be a boolean, an array of paths, or a function — e.g. sitemap: async () => [\'/blog/a\', { path: \'/blog/b\', lastmod: \'2026-01-01\' }]')
+    }
+    if (Array.isArray(t)) {
+      const bad = t.find(item => !(typeof item === 'string' && item.startsWith('/')) &&
+                                 !(item && typeof item === 'object' && typeof item.path === 'string' && item.path.startsWith('/')))
+      if (bad !== undefined) {
+        errors.push('spec.sitemap array entries must be "/path" strings or { path: \'/path\', lastmod? } objects')
+      }
+    }
+  }
+
   // csrf — opt out of CSRF protection on the submit handler (default: enforced)
   if (spec.csrf !== undefined) {
     if (typeof spec.csrf !== 'boolean') {

package/src/spec/schema.test.js

@@ -445,6 +445,22 @@ test('csrf: false with submit warns about unprotected POSTs', () => {
   assert(warnings.some(w => w.includes('CSRF')), 'Expected a warning about disabled CSRF protection')
 })
 
+// --- sitemap ------------------------------------------------------------------
+
+test('sitemap accepts boolean, array, and function', () => {
+  for (const v of [true, false, ['/a', { path: '/b', lastmod: '2026-01-01' }], async () => ['/a']]) {
+    const { valid, errors } = validateSpec({ route: '/x', view: () => '', sitemap: v })
+    assert(valid, `Expected sitemap ${typeof v} to be valid: ${errors.join('; ')}`)
+  }
+})
+
+test('sitemap rejects invalid types and malformed array entries', () => {
+  const { valid: v1 } = validateSpec({ route: '/x', view: () => '', sitemap: 'yes' })
+  assert(!v1, 'Expected string sitemap to be invalid')
+  const { valid: v2, errors } = validateSpec({ route: '/x', view: () => '', sitemap: ['no-slash'] })
+  assert(!v2 && errors.some(e => e.includes('sitemap')), 'Expected malformed array entry to be invalid')
+})
+
 // ---------------------------------------------------------------------------
 
 console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`)

package/types/schema.d.ts

@@ -75,6 +75,9 @@ export type SubmitResult =
   | { redirect: string }
   | { status?: number; [key: string]: unknown }
 
+/** A sitemap entry: a '/path' string, or { path, lastmod } for a per-URL lastmod date. */
+export type SitemapEntry = string | { path: string; lastmod?: string }
+
 export type GuardResult =
   | { redirect: string }
   | { status: number; json?: unknown; body?: string; headers?: Record<string, string> }
@@ -226,6 +229,14 @@ export interface PulseSpec<S extends object = Record<string, unknown>> {
    */
   csrf?: boolean
 
+  /**
+   * Inclusion control for the auto-generated sitemap (createServer { sitemap: true }).
+   * false → exclude this page. true → include a guarded static page that would be
+   * excluded by default. Array or function → enumerate paths — required for dynamic
+   * :param routes. Entries are '/path' strings or { path, lastmod } objects.
+   */
+  sitemap?: boolean | SitemapEntry[] | (() => Promise<SitemapEntry[]> | SitemapEntry[])
+
   /**
    * Called before server data fetchers on every request.
    * Return { redirect } to redirect, { status, json } for a custom response,

package/types/server.d.ts

@@ -79,6 +79,21 @@ export interface ServerOptions {
    */
   secret?: string | null
 
+  /**
+   * Auto-serve /sitemap.xml (and robots.txt) from the registered routes.
+   * true derives the origin from request headers; { origin } pins it.
+   * Static page routes are included automatically; dynamic :param routes
+   * contribute via spec.sitemap; guarded pages are excluded unless the spec
+   * opts in. A physical sitemap.xml in staticDir always wins.
+   */
+  sitemap?: boolean | { origin?: string }
+
+  /**
+   * robots.txt behaviour when sitemap is enabled. null/undefined auto-generates
+   * (allow all + Sitemap line); false disables; a string is served verbatim.
+   */
+  robots?: string | false | null
+
   /**
    * Extra CSP sources to merge into the framework's default Content-Security-Policy.
    * Use this to allow external stylesheets, fonts, or API origins.