@invisibleloop/pulse 0.17.2 → 0.18.0

package/src/server/server.test.js

@@ -1246,6 +1246,320 @@ await test('health check fires before route matching — shadows a user spec at
 
 // ---------------------------------------------------------------------------
 
+console.log('\nCustom 404 page (route: "*")\n')
+
+const notFoundPageSpec = {
+  route: '*',
+  meta:  { title: 'Lost?' },
+  view:  () => '<main id="main-content"><h1>Custom not found</h1><a href="/">Home</a></main>',
+}
+
+await test('unknown route renders the "*" spec with status 404', async () => {
+  await withServer([helloSpec, notFoundPageSpec], { stream: false }, async (port) => {
+    const { status, body } = await get(port, '/nope')
+    assert(status === 404, `Expected 404, got ${status}`)
+    assert(body.includes('Custom not found'), `Expected custom 404 content, got: ${body.slice(0, 200)}`)
+    assert(body.includes('<title>Lost?</title>'), `Expected custom 404 title, got: ${body.slice(0, 300)}`)
+  })
+})
+
+await test('custom 404 renders in streaming mode too (forced string path)', async () => {
+  await withServer([helloSpec, notFoundPageSpec], { stream: true }, async (port) => {
+    const { status, body } = await get(port, '/still-nope')
+    assert(status === 404, `Expected 404, got ${status}`)
+    assert(body.includes('Custom not found'), `Expected custom 404 content`)
+  })
+})
+
+await test('known routes are unaffected by the "*" spec', async () => {
+  await withServer([helloSpec, notFoundPageSpec], { stream: false }, async (port) => {
+    const { status, body } = await get(port, '/hello')
+    assert(status === 200, `Expected 200, got ${status}`)
+    assert(body.includes('Hello world'), 'Expected normal page content')
+  })
+})
+
+await test('custom 404 responses are not cached as 200s', async () => {
+  await withServer([helloSpec, notFoundPageSpec], { stream: false, defaultCache: 3600, dev: false }, async (port) => {
+    const a = await get(port, '/missing')
+    const b = await get(port, '/missing')
+    assert(a.status === 404 && b.status === 404, `Expected both 404, got ${a.status}/${b.status}`)
+  })
+})
+
+await test('without a "*" spec the default 404 still works', async () => {
+  await withServer([helloSpec], { stream: false }, async (port) => {
+    const { status, body } = await get(port, '/nope')
+    assert(status === 404 && body.includes('404'), 'Expected default 404 page')
+  })
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nServer-side forms (spec.submit) + CSRF\n')
+
+function requestFull(port, method, path, { headers = {}, body = null } = {}) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({ method, hostname: 'localhost', port, path, headers }, (res) => {
+      let data = ''
+      res.on('data', c => { data += c })
+      res.on('end', () => resolve({ status: res.statusCode, headers: res.headers, body: data }))
+    })
+    req.on('error', reject)
+    if (body) req.write(body)
+    req.end()
+  })
+}
+
+function postForm(port, path, fields, cookie = '') {
+  const body = new URLSearchParams(fields).toString()
+  return requestFull(port, 'POST', path, {
+    headers: {
+      'Content-Type':   'application/x-www-form-urlencoded',
+      'Content-Length': Buffer.byteLength(body),
+      ...(cookie ? { Cookie: cookie } : {}),
+    },
+    body,
+  })
+}
+
+/** GET the form page and extract the CSRF cookie + token for a valid POST. */
+async function getCsrfPair(port, path) {
+  const res    = await get(port, path)
+  const setCookie = [].concat(res.headers['set-cookie'] || []).find(c => c.startsWith('pulse_csrf='))
+  const cookie = setCookie ? setCookie.split(';')[0] : ''
+  const token  = res.body.match(/name="_csrf" value="([^"]+)"/)?.[1] || ''
+  return { cookie, token, body: res.body }
+}
+
+const formSpec = {
+  route: '/signup',
+  meta:  { title: 'Sign up' },
+  submit: async (ctx) => {
+    const data = await ctx.formData()
+    if (!data?.email) return { errors: { email: 'Email is required' }, values: data ?? {} }
+    if (data.email === 'taken@example.com') return { status: 422, errors: { email: 'Already registered' }, values: data }
+    return { redirect: '/signup?done=1' }
+  },
+  view: (state, server) => `
+    <main id="main-content">
+      <h1>Sign up</h1>
+      ${server.form?.errors?.email ? `<p class="error">${server.form.errors.email}</p>` : ''}
+      <form method="POST">
+        ${server.csrf ?? ''}
+        <label for="email">Email</label>
+        <input id="email" name="email" value="${server.form?.values?.email ?? ''}">
+        <button type="submit">Go</button>
+      </form>
+    </main>`,
+}
+
+await test('GET on a submit page sets the CSRF cookie and embeds the hidden field', async () => {
+  await withServer([formSpec], { stream: false }, async (port) => {
+    const { cookie, token, body } = await getCsrfPair(port, '/signup')
+    assert(cookie.startsWith('pulse_csrf='), `Expected pulse_csrf cookie, got: ${cookie}`)
+    assert(token.length > 20, `Expected a CSRF token in the form, got: ${token}`)
+    assert(body.includes('name="_csrf"'), 'Expected hidden _csrf input in the form')
+  })
+})
+
+await test('CSRF field is present in streaming mode too', async () => {
+  await withServer([formSpec], { stream: true }, async (port) => {
+    const { token } = await getCsrfPair(port, '/signup')
+    assert(token.length > 20, 'Expected CSRF token in streamed HTML')
+  })
+})
+
+await test('POST without a CSRF token is rejected with 403', async () => {
+  await withServer([formSpec], { stream: false }, async (port) => {
+    const { status } = await postForm(port, '/signup', { email: 'a@b.com' })
+    assert(status === 403, `Expected 403, got ${status}`)
+  })
+})
+
+await test('POST with a forged token is rejected with 403', async () => {
+  await withServer([formSpec], { stream: false }, async (port) => {
+    const { cookie } = await getCsrfPair(port, '/signup')
+    const { status } = await postForm(port, '/signup', { email: 'a@b.com', _csrf: 'forged-token-value' }, cookie)
+    assert(status === 403, `Expected 403, got ${status}`)
+  })
+})
+
+await test('valid POST follows POST-redirect-GET with 303', async () => {
+  await withServer([formSpec], { stream: false }, async (port) => {
+    const { cookie, token } = await getCsrfPair(port, '/signup')
+    const { status, headers } = await postForm(port, '/signup', { email: 'a@b.com', _csrf: token }, cookie)
+    assert(status === 303, `Expected 303, got ${status}`)
+    assert(headers.location === '/signup?done=1', `Expected PRG redirect, got ${headers.location}`)
+  })
+})
+
+await test('validation failure re-renders the page with server.form (errors + values)', async () => {
+  await withServer([formSpec], { stream: false }, async (port) => {
+    const { cookie, token } = await getCsrfPair(port, '/signup')
+    const { status, body } = await postForm(port, '/signup', { email: '', _csrf: token }, cookie)
+    assert(status === 200, `Expected 200 re-render, got ${status}`)
+    assert(body.includes('Email is required'), `Expected error message in re-render, got: ${body.slice(0, 400)}`)
+  })
+})
+
+await test('submit can set a custom response status (422) and values are echoed back', async () => {
+  await withServer([formSpec], { stream: false }, async (port) => {
+    const { cookie, token } = await getCsrfPair(port, '/signup')
+    const { status, body } = await postForm(port, '/signup', { email: 'taken@example.com', _csrf: token }, cookie)
+    assert(status === 422, `Expected 422, got ${status}`)
+    assert(body.includes('Already registered'), 'Expected error in re-render')
+    assert(body.includes('value="taken@example.com"'), 'Expected submitted value echoed into the input')
+  })
+})
+
+await test('csrf: false opts a submit route out of CSRF protection', async () => {
+  const webhookish = {
+    route:  '/hook',
+    csrf:   false,
+    submit: async () => ({ redirect: '/hook?ok=1' }),
+    view:   () => '<main id="main-content">hook</main>',
+  }
+  await withServer([webhookish], { stream: false }, async (port) => {
+    const { status, headers } = await postForm(port, '/hook', { x: '1' })
+    assert(status === 303 && headers.location === '/hook?ok=1', `Expected 303 without CSRF, got ${status}`)
+  })
+})
+
+await test('POST to a page without submit is still 405', async () => {
+  await withServer([helloSpec], { stream: false }, async (port) => {
+    const { status } = await postForm(port, '/hello', { x: '1' })
+    assert(status === 405, `Expected 405, got ${status}`)
+  })
+})
+
+await test('submit pages are excluded from the in-process page cache', async () => {
+  // Two different clients must get different CSRF tokens — a cached page would
+  // serve client A's token (and cookie pairing) to client B.
+  await withServer([formSpec], { stream: false, defaultCache: 3600 }, async (port) => {
+    const a = await getCsrfPair(port, '/signup')
+    const b = await getCsrfPair(port, '/signup')
+    assert(a.token && b.token && a.token !== b.token,
+      `Expected per-visitor CSRF tokens, got identical values (page was cached)`)
+  })
+})
+
+// ---------------------------------------------------------------------------
+
+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

@@ -137,13 +137,49 @@ export function validateSpec(spec) {
     return { valid: false, errors: ['Spec must be a plain object'] }
   }
 
-  // route
+  // route — '*' is the custom not-found page, rendered with status 404 when no route matches
   if (spec.route === undefined) {
     warnings.push('spec.route is not set — the server cannot register this page without a route')
   } else if (typeof spec.route !== 'string') {
     errors.push('spec.route must be a string (e.g. "/contact")')
-  } else if (!spec.route.startsWith('/')) {
-    errors.push('spec.route must start with "/" (e.g. "/contact")')
+  } else if (!spec.route.startsWith('/') && spec.route !== '*') {
+    errors.push('spec.route must start with "/" (e.g. "/contact"), or be "*" for the custom not-found page')
+  }
+
+  // submit — server-side form handler: POST to the route is handled without client JS
+  if (spec.submit !== undefined) {
+    if (typeof spec.submit !== 'function') {
+      errors.push('spec.submit must be a function — async (ctx) => ({ redirect } | { ...form state }). It handles POST requests to this route server-side.')
+    }
+  }
+
+  // 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') {
+      errors.push('spec.csrf must be a boolean — set csrf: false only to disable CSRF protection for spec.submit (e.g. for token-authenticated endpoints)')
+    }
+    if (spec.csrf === false && typeof spec.submit === 'function') {
+      warnings.push('spec.csrf is false — POST submissions to this route are NOT CSRF-protected. Only do this for endpoints with their own auth (e.g. signed webhooks).')
+    }
   }
 
   // contentType — marks a raw content spec (RSS, sitemap, JSON API, etc.)

package/src/spec/schema.test.js

@@ -412,6 +412,55 @@ test('does not warn when meta.theme is a function', () => {
   assert(!warnings.some(w => w.includes('meta.theme')), 'Unexpected meta.theme warning when theme is a function')
 })
 
+// --- route '*', submit, csrf ------------------------------------------------
+
+test('route "*" (custom not-found page) is valid', () => {
+  const { valid, errors } = validateSpec({ route: '*', view: () => '<main id="main-content">404</main>' })
+  assert(valid, `Expected valid, got: ${errors.join('; ')}`)
+})
+
+test('non-"/" routes other than "*" are still rejected', () => {
+  const { valid } = validateSpec({ route: 'about', view: () => '' })
+  assert(!valid, 'Expected route without leading / to be invalid')
+})
+
+test('submit must be a function', () => {
+  const { valid, errors } = validateSpec({ route: '/x', view: () => '', submit: 'nope' })
+  assert(!valid && errors.some(e => e.includes('submit')), 'Expected submit type error')
+})
+
+test('a valid submit function passes', () => {
+  const { valid } = validateSpec({ route: '/x', view: () => '', submit: async () => ({ redirect: '/' }) })
+  assert(valid, 'Expected spec with submit function to be valid')
+})
+
+test('csrf must be a boolean', () => {
+  const { valid, errors } = validateSpec({ route: '/x', view: () => '', csrf: 'off' })
+  assert(!valid && errors.some(e => e.includes('csrf')), 'Expected csrf type error')
+})
+
+test('csrf: false with submit warns about unprotected POSTs', () => {
+  const { valid, warnings } = validateSpec({ route: '/x', view: () => '', submit: async () => {}, csrf: false })
+  assert(valid, 'csrf: false is valid')
+  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

@@ -65,6 +65,19 @@ export interface RequestContext {
 // Guard return value
 // ---------------------------------------------------------------------------
 
+/**
+ * Return value of spec.submit().
+ * { redirect } → 303 POST-redirect-GET. Any other object re-renders the page
+ * with the value exposed as serverState.form; an optional status field sets
+ * the HTTP response status (e.g. 422 for validation failures).
+ */
+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> }
@@ -131,7 +144,10 @@ export interface MetaConfig {
 // ---------------------------------------------------------------------------
 
 export interface PulseSpec<S extends object = Record<string, unknown>> {
-  /** URL pattern. Supports :param segments. */
+  /**
+   * URL pattern. Supports :param segments.
+   * Use '*' for the custom not-found page — rendered with status 404 when no route matches.
+   */
   route: string
 
   /**
@@ -194,9 +210,33 @@ export interface PulseSpec<S extends object = Record<string, unknown>> {
   /** Global store keys this page subscribes to. Appear in view's server arg. */
   store?: string[]
 
-  /** HTTP methods this page accepts. Default ['GET', 'HEAD']. */
+  /** HTTP methods this page accepts. Default ['GET', 'HEAD'] (plus POST when submit is set). */
   methods?: Array<'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS'>
 
+  /**
+   * Server-side form handler — POST to this route works without client JS.
+   * Return { redirect } for a 303 POST-redirect-GET; any other value re-renders
+   * the page with the value exposed to the view as serverState.form (an optional
+   * status field sets the response status, e.g. 422).
+   * CSRF protection is enforced automatically: the view must include
+   * ${server.csrf} inside the <form> or POSTs are rejected with 403.
+   */
+  submit?: (ctx: RequestContext) => Promise<SubmitResult | void> | SubmitResult | void
+
+  /**
+   * Set false to disable CSRF protection on the submit handler.
+   * Only for endpoints with their own authentication (e.g. signed webhooks).
+   */
+  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

@@ -72,6 +72,28 @@ export interface ServerOptions {
   /** Called on every request before routing. Return false to short-circuit Pulse handling. */
   onRequest?: (req: IncomingMessage, res: ServerResponse) => false | void | unknown
 
+  /**
+   * HMAC secret for CSRF tokens (spec.submit forms). Defaults to a random
+   * per-boot value — set a stable secret (e.g. from an env var) when running
+   * multiple instances so tokens issued by one instance validate on another.
+   */
+  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.