@invisibleloop/pulse 0.17.1 → 0.17.3

package/src/server/index.js

@@ -367,12 +367,14 @@ function buildCacheKey(spec, ctx) {
  *   - spec.stream.deferred    — deferred segments inject content via inline <script nonce="...">
  *                               tags; caching bakes in one nonce while subsequent CSP headers
  *                               carry a different nonce, causing a violation
+ *   - spec.submit             — form pages embed a per-visitor CSRF token; caching
+ *                               would serve one visitor's token to everyone
  *
  * In all these cases the cached HTML would contain a nonce that doesn't match
  * the nonce-free CSP used for cached responses, causing a CSP violation.
  */
 function isCacheablePage(spec) {
-  return !spec.server && !spec.store?.length && !spec.hydrate && !spec.stream?.deferred?.length
+  return !spec.server && !spec.store?.length && !spec.hydrate && !spec.stream?.deferred?.length && !spec.submit
 }
 
 // ---------------------------------------------------------------------------
@@ -542,6 +544,8 @@ export async function createServer(entries, options = {}) {
     shutdownTimeout = 30000,        // ms to wait for in-flight requests before force-exit
     healthCheck    = '/healthz',    // path for health check endpoint, or false to disable
     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
     onError        = (err, req, res) => defaultErrorHandler(err, req, res, dev),
     onRequest,
     agentMode      = false,        // show agent-active indicator in banner
@@ -585,8 +589,8 @@ export async function createServer(entries, options = {}) {
     const routeErrors = []
     if (!spec.route || typeof spec.route !== 'string') {
       routeErrors.push('spec.route is required and must be a string (e.g. "/contact")')
-    } else if (!spec.route.startsWith('/')) {
-      routeErrors.push('spec.route must start with "/" (e.g. "/contact")')
+    } else if (!spec.route.startsWith('/') && spec.route !== '*') {
+      routeErrors.push('spec.route must start with "/" (e.g. "/contact"), or be "*" for the custom not-found page')
     }
     const allErrors = [...errors, ...routeErrors]
     if (!valid || routeErrors.length > 0) {
@@ -597,8 +601,18 @@ export async function createServer(entries, options = {}) {
     }
   }
 
-  // Build route table — let so it can be swapped on hot reload
-  let router = buildRouter(specs)
+  // Custom not-found page — a spec with route '*' renders (with status 404)
+  // whenever no route matches. It goes through the normal render pipeline, so
+  // it gets the site's layout, styles, hydration, and validation like any page.
+  let notFoundSpec = specs.find(s => s.route === '*') || null
+
+  // Build route table — let so it can be swapped on hot reload.
+  // The '*' spec is excluded: it is not a route, it is the fallback.
+  let router = buildRouter(specs.filter(s => s.route !== '*'))
+
+  // CSRF secret — per-boot random unless pinned via options.secret. Tokens are
+  // tied to a cookie, so a restart only means in-flight forms re-render once.
+  const csrfSecret = secret || crypto.randomBytes(32).toString('hex')
 
   // Resolve the logger module once at startup rather than dynamically importing
   // it on every request's `finish` event. `logRequest` stays null until loaded.
@@ -662,20 +676,32 @@ export async function createServer(entries, options = {}) {
       }
 
       // Match route
-      const match = matchRoute(router, pathname)
+      let match          = matchRoute(router, pathname)
+      let responseStatus = 200
 
       if (!match) {
-        res.writeHead(404, { 'Content-Type': 'text/html', ...SECURITY_HEADERS, ...httpsHeaders(req) })
-        res.end(notFoundHtml(pathname))
-        return
+        // Custom not-found page — a '*' spec renders through the normal pipeline
+        // with status 404, so the site's branded 404 gets layout, styles, and
+        // hydration like any other page. Client-side navigation requests still
+        // get the plain 404 (navigate.js falls back to a full page load, which
+        // then renders the custom page).
+        if (notFoundSpec && (req.method === 'GET' || req.method === 'HEAD') && req.headers['x-pulse-navigate'] !== 'true') {
+          match          = { spec: notFoundSpec, params: {} }
+          responseStatus = 404
+        } else {
+          res.writeHead(404, { 'Content-Type': 'text/html', ...SECURITY_HEADERS, ...httpsHeaders(req) })
+          res.end(notFoundHtml(pathname))
+          return
+        }
       }
 
       // Method gating — raw response specs accept any HTTP method.
-      // Page specs default to GET/HEAD only; opt in to other methods via spec.methods.
+      // Page specs default to GET/HEAD only; spec.submit adds POST automatically;
+      // opt in to other methods via spec.methods.
       if (!match.spec.contentType) {
         const allowed = match.spec.methods
           ? match.spec.methods.map(m => m.toUpperCase())
-          : ['GET', 'HEAD']
+          : (typeof match.spec.submit === 'function' ? ['GET', 'HEAD', 'POST'] : ['GET', 'HEAD'])
         if (!allowed.includes(req.method)) {
           res.writeHead(405, {
             'Content-Type': 'text/plain',
@@ -738,6 +764,57 @@ export async function createServer(entries, options = {}) {
         }
       }
 
+      // -----------------------------------------------------------------------
+      // CSRF — specs with a `submit` handler get token protection automatically
+      // (opt out per spec with csrf: false, e.g. for token-authenticated routes).
+      // Double-submit pattern: an HttpOnly cookie holds a random id; the form
+      // carries HMAC(secret, id) in a hidden _csrf field; POST verifies the pair.
+      // Views embed the field inside <form method="POST"> as ${server.csrf}.
+      // -----------------------------------------------------------------------
+      if (typeof spec.submit === 'function' && spec.csrf !== false) {
+        let csrfId = ctx.cookies.pulse_csrf
+        if (!csrfId) {
+          csrfId = crypto.randomBytes(16).toString('base64url')
+          ctx.setCookie('pulse_csrf', csrfId, { httpOnly: true, sameSite: 'Lax', path: '/' })
+        }
+        ctx._csrfField = `<input type="hidden" name="_csrf" value="${csrfToken(csrfSecret, csrfId)}">`
+
+        if (req.method === 'POST') {
+          const form      = await ctx.formData()
+          const submitted = typeof form?._csrf === 'string' ? form._csrf : ''
+          const cookieId  = ctx.cookies.pulse_csrf
+          if (!cookieId || !safeEqual(submitted, csrfToken(csrfSecret, cookieId))) {
+            res.writeHead(403, mergeCtxHeaders(ctx, {
+              'Content-Type': 'text/plain',
+              ...SECURITY_HEADERS, ...httpsHeaders(req),
+            }))
+            res.end('Invalid or missing CSRF token. Reload the page and resubmit the form.')
+            return
+          }
+        }
+      }
+
+      // -----------------------------------------------------------------------
+      // Server-side form handling — spec.submit handles POST without client JS.
+      //   { redirect: '/path' }  → 303 See Other (POST-redirect-GET)
+      //   anything else          → re-render the page; the return value appears
+      //                            in the view as serverState.form (errors,
+      //                            submitted values, etc.). Optional status field
+      //                            sets the response status (e.g. 422).
+      // -----------------------------------------------------------------------
+      if (req.method === 'POST' && typeof spec.submit === 'function') {
+        const result = await spec.submit(ctx)
+        if (result?.redirect) {
+          res.writeHead(303, mergeCtxHeaders(ctx, { Location: result.redirect, ...SECURITY_HEADERS, ...httpsHeaders(req) }))
+          res.end()
+          return
+        }
+        ctx._form = result ?? {}
+        if (typeof result?.status === 'number') responseStatus = result.status
+        // POST re-renders always use the buffered path — the request body is
+        // consumed and streaming a form response has no benefit.
+      }
+
       // Derive the canonical base URL from the request.
       // 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
@@ -776,7 +853,12 @@ export async function createServer(entries, options = {}) {
         return
       }
 
-      if (stream) {
+      // Non-200 renders (custom 404) and POST re-renders always use the buffered
+      // string path — they are small, must carry an explicit status, and POST
+      // bodies are already consumed.
+      if (responseStatus !== 200 || req.method === 'POST') {
+        await handleStringResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, store, csp, faviconPath, responseStatus)
+      } else if (stream) {
         await handleStreamResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, store, csp, faviconPath)
       } else {
         await handleStringResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, store, csp, faviconPath)
@@ -865,7 +947,8 @@ export async function createServer(entries, options = {}) {
     server,
     shutdown,
     updateSpecs(newSpecs) {
-      router = buildRouter(newSpecs)
+      notFoundSpec = newSpecs.find(s => s.route === '*') || null
+      router = buildRouter(newSpecs.filter(s => s.route !== '*'))
     }
   }
 }
@@ -943,9 +1026,12 @@ async function handleNavStreamResponse(spec, ctx, req, res) {
  * Render to a complete string then send — simpler, easier to cache.
  * Checks the in-process page cache before rendering; stores result after.
  */
-async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalBase = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}, faviconPath = null) {
+async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalBase = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}, faviconPath = null, status = 200) {
   const cacheKey = buildCacheKey(spec, ctx)
-  const ttl      = isCacheablePage(spec) ? pageCacheTtl(spec, dev, defaultCache) : 0
+  // Never cache POST re-renders or non-200 responses (custom 404s) — POST output
+  // varies per submission and a cached 404 body would be served with a 200 later.
+  const cacheable = status === 200 && ctx.method !== 'POST' && isCacheablePage(spec)
+  const ttl       = cacheable ? pageCacheTtl(spec, dev, defaultCache) : 0
 
   let html, serverTimingValue, fromCache = false
 
@@ -984,7 +1070,7 @@ async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = f
   if (encoding)          headers['Content-Encoding'] = encoding
   if (serverTimingValue) headers['Server-Timing']    = serverTimingValue
 
-  res.writeHead(200, headers)
+  res.writeHead(status, headers)
   res.end(buf)
 }
 
@@ -1585,6 +1671,23 @@ function escHtml(str) {
     .replace(/'/g, '&#39;')
 }
 
+/**
+ * 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
+ * cookie. An attacker on another origin can trigger the cookie being sent but
+ * cannot read it or compute the HMAC, so they cannot forge the pair.
+ */
+function csrfToken(secret, id) {
+  return crypto.createHmac('sha256', secret).update(String(id)).digest('base64url')
+}
+
+/** Constant-time string comparison — length mismatch returns false without throwing. */
+function safeEqual(a, b) {
+  const ba = Buffer.from(String(a))
+  const bb = Buffer.from(String(b))
+  return ba.length === bb.length && crypto.timingSafeEqual(ba, bb)
+}
+
 function notFoundHtml(pathname) {
   return `<!DOCTYPE html>
 <html lang="en">

package/src/server/server.test.js

@@ -1246,6 +1246,206 @@ 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('\nMalformed request handling\n')
 
 await test('malformed percent-encoding in path returns 404, not 500', async () => {

package/src/spec/schema.js

@@ -137,13 +137,30 @@ 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.')
+    }
+  }
+
+  // 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,39 @@ 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')
+})
+
 // ---------------------------------------------------------------------------
 
 console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`)

package/src/ui/drop-cap.js

@@ -24,6 +24,6 @@ export function dropCap({
   const classes = ['ui-drop-cap', cls].filter(Boolean).join(' ')
   
   return `<p class="${e(classes)}">
-  <span class="ui-drop-cap-letter" style="float:left;font-size:${lines * 1.2}em;line-height:${lines * 0.8};margin-right:0.1em" aria-hidden="true">${e(letter)}</span>${e(content)}
+  <span class="ui-drop-cap-letter" style="font-size:${+(lines * 1.2).toFixed(2)}em" aria-hidden="true">${e(letter)}</span>${e(content)}
 </p>`
 }

package/src/ui/gallery.js

@@ -11,6 +11,9 @@
  * @param {'sm'|'md'|'lg'} opts.gap - Gap between images (default: 'md')
  * @param {boolean} opts.rounded  - Rounded corners on images
  * @param {string}  opts.ratio    - CSS aspect-ratio for grid/strip cells e.g. '4/3', '1/1', '16/9'
+ * @param {boolean} opts.lazy     - loading="lazy" on images (default: true). Set false for
+ *                                  above-the-fold galleries or when full-page screenshots
+ *                                  during development need every image rendered eagerly.
  * @param {string}  opts.class
  */
 
@@ -26,6 +29,7 @@ export function gallery({
   gap     = 'md',
   rounded = false,
   ratio   = '4/3',
+  lazy    = true,
   class: cls = '',
 } = {}) {
   if (!LAYOUTS.has(layout)) layout = 'grid'
@@ -42,7 +46,7 @@ export function gallery({
   ].filter(Boolean).join(' ')
 
   const items = images.map(img => {
-    const imgTag = `<img src="${e(img.src)}" alt="${e(img.alt || '')}" class="ui-gallery-img" loading="lazy" decoding="async">`
+    const imgTag = `<img src="${e(img.src)}" alt="${e(img.alt || '')}" class="ui-gallery-img"${lazy ? ' loading="lazy"' : ''} decoding="async">`
     const cap    = img.caption ? `<figcaption class="ui-gallery-caption">${e(img.caption)}</figcaption>` : ''
     const inner  = img.href
       ? `<a href="${e(img.href)}" class="ui-gallery-link">${imgTag}</a>`

package/src/ui/ui.test.js

@@ -25,6 +25,8 @@ import { pricing }     from './pricing.js'
 import { accordion }   from './accordion.js'
 import { nav }         from './nav.js'
 import { appBadge }    from './app-badge.js'
+import { dropCap }     from './drop-cap.js'
+import { gallery }     from './gallery.js'
 import { container }   from './container.js'
 import { section }     from './section.js'
 import { grid }        from './grid.js'
@@ -1319,4 +1321,36 @@ test('uiImage: escapes src to prevent XSS', () => {
   assert.doesNotMatch(html, /<script>/)
 })
 
+test('dropCap: inline style carries only the dynamic font-size — alignment lives in CSS', () => {
+  // Regression: a relative inline line-height (lines * 0.8 → 2.4 for 3 lines)
+  // made the float box ~3x the glyph height, so serif caps floated below the
+  // opening line instead of top-aligning. line-height/float/margin now live in
+  // .ui-drop-cap-letter (pulse-ui.css) with a fixed ~cap-height value.
+  const html = dropCap({ letter: 'O', content: 'nce upon a time.' })
+  assert.match(html, /class="ui-drop-cap-letter"/)
+  assert.match(html, /style="font-size:3\.6em"/)
+  assert.doesNotMatch(html, /line-height/)
+  assert.doesNotMatch(html, /float:left/)
+})
+
+test('dropCap: lines option scales the font-size', () => {
+  const html = dropCap({ letter: 'O', content: 'nce.', lines: 5 })
+  assert.match(html, /style="font-size:6em"/)
+})
+
+test('gallery: images are lazy by default', () => {
+  const html = gallery({ images: [{ src: '/a.jpg', alt: 'A' }] })
+  assert.match(html, /loading="lazy"/)
+})
+
+test('gallery: lazy:false renders eager images', () => {
+  const html = gallery({ images: [{ src: '/a.jpg', alt: 'A' }], lazy: false })
+  assert.doesNotMatch(html, /loading="lazy"/)
+})
+
+test('dropCap: escapes letter and content', () => {
+  const html = dropCap({ letter: '<', content: '<script>alert(1)</script>' })
+  assert.doesNotMatch(html, /<script>/)
+})
+
 console.log('✓ All UI component tests passed')

package/types/schema.d.ts

@@ -65,6 +65,16 @@ 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 }
+
 export type GuardResult =
   | { redirect: string }
   | { status: number; json?: unknown; body?: string; headers?: Record<string, string> }
@@ -131,7 +141,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 +207,25 @@ 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
+
   /**
    * 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,13 @@ 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
+
   /**
    * Extra CSP sources to merge into the framework's default Content-Security-Policy.
    * Use this to allow external stylesheets, fonts, or API origins.