@invisibleloop/pulse 0.20.10 → 0.20.19

package/src/server/index.js

@@ -331,15 +331,36 @@ function resolveCache(value) {
  *
  * spec.cache / defaultCache:
  *   true                               → public, max-age=3600, stale-while-revalidate=86400
- *   number                             → public, max-age={n}
+ *   number                               → public, max-age={n}
  *   { public, maxAge, staleWhileRevalidate }
+ *
+ * Pages with no cache config get 'no-cache', not 'no-store' — this is a
+ * deliberate choice, not a lesser default. 'no-store' unconditionally blocks
+ * the browser's back/forward cache (confirmed against a real Lighthouse
+ * audit: "Page prevented back/forward cache restoration ... cache-control:
+ * no-store header"), which without this fix meant every Pulse page failed
+ * bfcache eligibility unless it explicitly opted into caching. 'no-cache'
+ * still forces revalidation on every direct load/refresh — it does NOT
+ * serve a stale copy without checking first — it just permits the browser
+ * to keep an in-memory snapshot for back/forward navigation, which never
+ * touches the network at all. No risk of stale dynamic content on a normal
+ * page load; this only affects the back/forward navigation path.
  */
 function buildCacheControl(spec, dev, defaultCache = null) {
   if (dev) return 'no-store'
 
   const cfg = resolveCache(spec?.cache) ?? resolveCache(defaultCache)
-  if (!cfg) return 'no-store'
+  if (!cfg) return 'no-cache'
+
+  return buildCacheControlFromConfig(cfg)
+}
 
+/**
+ * Format an already-resolved cache config (see resolveCache) into a
+ * Cache-Control header value. Split out of buildCacheControl so static-file
+ * serving can reuse the same formatting without a spec object.
+ */
+function buildCacheControlFromConfig(cfg) {
   const { public: isPublic = false, maxAge = 0, staleWhileRevalidate } = cfg
   const parts = [isPublic ? 'public' : 'private']
   if (maxAge > 0) parts.push(`max-age=${maxAge}`)
@@ -492,12 +513,24 @@ const MIME_TYPES = {
 
 /**
  * Returns true if the spec needs a client-side hydration script.
- * Specs with no mutations, actions, or persist are purely server-rendered.
+ * Specs with no mutations, actions, persist, or store are purely
+ * server-rendered.
+ *
+ * spec.store alone counts even with no local mutations/actions: mount() is
+ * what wires up data-store-event dispatch AND the live SSE store-push
+ * subscription (initLiveStore) — a store-only page with no hydration script
+ * would silently never receive pushStore() broadcasts and have a dead
+ * data-store-event button, with no error surfaced anywhere (server-rendered
+ * HTML looks correct). Mirrors the same fix in discover.js's needsHydration
+ * and build.js's needsClientBundle — this is the third, independent copy of
+ * this check (the one createServer itself uses when auto-deriving
+ * spec.hydrate for URL entries) and previously had the same gap.
  */
 function needsHydration(spec) {
   return !!(spec.mutations && Object.keys(spec.mutations).length) ||
          !!(spec.actions   && Object.keys(spec.actions).length)   ||
-         !!spec.persist
+         !!spec.persist ||
+         !!(spec.store && spec.store.length)
 }
 
 /**
@@ -562,6 +595,9 @@ export async function createServer(entries, options = {}) {
     root          = null,          // URL/string — project root for deriving browser paths from file: URLs
     resolveBrand   = null,          // async (host) => brandConfig — keyed by domain
     defaultCache   = null,          // default page cache: true | seconds | { public, maxAge, swr }
+    staticCache    = null,          // cache for static files served from staticDir (excludes /dist/,
+                                    // which is always immutable/1yr): true | seconds | { public, maxAge, swr }
+                                    // — default without this option is public, max-age=3600
     fetcherTimeout  = null,          // ms before any server fetcher times out (null = no limit)
     maxBody         = 1024 * 1024,  // max request body size in bytes (default 1 MB)
     shutdownTimeout = 30000,        // ms to wait for in-flight requests before force-exit
@@ -582,7 +618,7 @@ export async function createServer(entries, options = {}) {
                                     // clients; pages subscribed via spec.store re-render immediately.
                                     // Broadcast = SHARED data only (stock, announcements), never
                                     // per-user data. Default path: /__pulse/live
-    onError        = (err, req, res) => defaultErrorHandler(err, req, res, dev),
+    onError        = (err, req, res) => defaultErrorHandler(err, req, res, dev, errorJournalPath),
     onRequest,
     agentMode      = false,        // show agent-active indicator in banner
     quiet          = false,        // suppress request logging
@@ -593,6 +629,10 @@ export async function createServer(entries, options = {}) {
 
   const healthPath = healthCheck === true ? '/healthz' : (healthCheck || null)
 
+  // Error journal path — resolved once per createServer call from this
+  // instance's real root, not cached at module load. See writeErrorEntry.
+  const errorJournalPath = resolveErrorJournalPath(root)
+
   // Store definition — `let` so the dev server can hot-swap it via updateStore()
   // when pulse.store.js changes, the same way updateSpecs() swaps page specs.
   let storeDef = store
@@ -665,6 +705,7 @@ export async function createServer(entries, options = {}) {
   // 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 !== '*'))
+  warnOnRouteShadowing(router)
 
   // 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.
@@ -775,6 +816,25 @@ export async function createServer(entries, options = {}) {
         return
       }
 
+      // Client-side error reporting — dev only. The runtime POSTs view/action
+      // failures here so they land in the same journal as server-side errors;
+      // pulse_diagnose reads one file regardless of where the error occurred.
+      // Not registered in production — a stray POST there just 404s harmlessly,
+      // so the client runtime can call it unconditionally with no dev check.
+      if (dev && pathname === '/__pulse/error' && req.method === 'POST') {
+        let body = ''
+        req.on('data', chunk => { body += chunk })
+        req.on('end', () => {
+          try {
+            const { route, phase, message, stack } = JSON.parse(body || '{}')
+            writeErrorEntry(errorJournalPath, { route, phase: phase === 'action' ? 'action' : 'view', message, stack })
+          } catch { /* malformed payload — drop it, this is best-effort */ }
+          res.writeHead(204, SECURITY_HEADERS)
+          res.end()
+        })
+        return
+      }
+
       // Request hook — allows middleware-like behaviour
       if (onRequest) {
         const result = onRequest(req, res)
@@ -783,7 +843,7 @@ export async function createServer(entries, options = {}) {
 
       // Static file serving — GET/HEAD only
       if (staticDir && (req.method === 'GET' || req.method === 'HEAD')) {
-        const served = serveStatic(req, res, staticDir, dev)
+        const served = serveStatic(req, res, staticDir, dev, staticCache)
         if (served) return
       }
 
@@ -1322,7 +1382,7 @@ async function handleStreamResponse(spec, ctx, req, res, extraBody = '', dev = f
     try { res.writeEarlyHints({ link: earlyLinks }) } catch {}
   }
 
-  const stylePreconnects = buildStylePreconnects(meta.styles || [])
+  const stylePreconnects = buildStylePreconnects([...(meta.styles || []), ...(meta.deferredStyles || [])])
 
   const stylePreloads = (meta.styles || [])
     .map(href => `  <link rel="preload" as="style" href="${escHtml(href)}">`)
@@ -1513,6 +1573,37 @@ function buildRouter(specs) {
   })
 }
 
+/**
+ * Route matching is first-match-wins in registration order (see matchRoute) —
+ * there is no path-specificity ranking. Registration order comes from file
+ * discovery order, which is not guaranteed alphabetical across platforms. A
+ * dynamic route registered before a same-depth static route will silently
+ * swallow every request to that static route — no error, no warning, just a
+ * 404 or the wrong page rendering, discovered only by noticing a route never
+ * gets hit. This is a static, best-effort check: it tests each dynamic
+ * route's pattern against a synthetic literal built from each later static
+ * route's own path segments, so it only catches routes actually registered
+ * (nothing exhaustive about every possible URL).
+ */
+function warnOnRouteShadowing(router) {
+  for (let i = 0; i < router.length; i++) {
+    const earlier = router[i]
+    if (earlier.params.length === 0) continue // static routes can't shadow anything
+    for (let j = i + 1; j < router.length; j++) {
+      const later = router[j]
+      if (later.params.length > 0) continue // only static routes can be shadowed this way
+      if (earlier.pattern.test(later.spec.route)) {
+        console.warn(
+          `⚠ Pulse: route "${earlier.spec.route}" is registered before "${later.spec.route}" and matches it — ` +
+          `"${later.spec.route}" will never be reached. Route matching is first-match-wins with no ` +
+          `specificity ranking; rename the file backing "${earlier.spec.route}" so it sorts after ` +
+          `"${later.spec.route}", or give one of them an explicit route that no longer overlaps.`
+        )
+      }
+    }
+  }
+}
+
 /**
  * Match a pathname against the router.
  * Returns the first match with extracted params, or null.
@@ -1754,9 +1845,12 @@ function resolveSpec(spec, hydrateMap) {
  * @param {http.IncomingMessage} req
  * @param {http.ServerResponse}  res
  * @param {string} staticDir - Absolute path to the static files directory
+ * @param {boolean} dev
+ * @param {*} staticCache - true | seconds | { public, maxAge, staleWhileRevalidate };
+ *   overrides the default public, max-age=3600 for non-/dist/ static files
  * @returns {boolean}
  */
-function serveStatic(req, res, staticDir, dev = false) {
+function serveStatic(req, res, staticDir, dev = false, staticCache = null) {
   const url      = new URL(req.url, 'http://localhost')
   let pathname
   try { pathname = decodeURIComponent(url.pathname) }
@@ -1775,10 +1869,15 @@ function serveStatic(req, res, staticDir, dev = false) {
 
   // Content-hashed bundles under /dist/ can be cached indefinitely.
   // In dev, all other files get no-store so CSS/JS changes are reflected immediately.
+  // staticCache lets a project raise the default 3600s for its own unhashed
+  // static assets (e.g. /images/*) without pretending they're immutable.
   const isImmutable = pathname.startsWith('/dist/')
+  const staticCacheCfg = resolveCache(staticCache)
   const cache = isImmutable
     ? 'public, max-age=31536000, immutable'
-    : dev ? 'no-store' : 'public, max-age=3600'
+    : dev ? 'no-store'
+    : staticCacheCfg ? buildCacheControlFromConfig(staticCacheCfg)
+    : 'public, max-age=3600'
 
   // Only compress compressible text types
   const compressible = ['.js', '.css', '.html', '.json', '.svg'].includes(ext)
@@ -2003,8 +2102,62 @@ function notFoundHtml(pathname) {
 </html>`
 }
 
-function defaultErrorHandler(err, _req, res, dev = false) {
+// ---------------------------------------------------------------------------
+// Error journal — dev-only diagnostic log an agent can read via pulse_diagnose.
+// Captures the failure modes that previously dead-ended at console.error:
+// server errors, SSR view throws, sitemap enumerator failures, and (via the
+// /__pulse/error endpoint) post-hydration client view/action failures.
+// Ring-buffered at 50 entries — this is a build/iterate-time tool, not a
+// production error tracker, so it is only written when dev === true.
+// ---------------------------------------------------------------------------
+
+const ERROR_JOURNAL_LIMIT = 50
+
+// journalPath is computed per-createServer-call from the real project root
+// (see resolveErrorJournalPath below) rather than cached at module load —
+// each createServer instance (e.g. concurrent test servers) gets its own
+// correct path instead of a stale process.cwd() snapshot from import time.
+function resolveErrorJournalPath(root) {
+  const dir = root
+    ? (typeof root === 'string' ? root : root.pathname || process.cwd())
+    : process.cwd()
+  return path.join(dir, '.pulse', 'errors.json')
+}
+
+function readErrorJournal(journalPath) {
+  try {
+    return JSON.parse(fs.readFileSync(journalPath, 'utf8'))
+  } catch {
+    return []
+  }
+}
+
+function writeErrorEntry(journalPath, { route, phase, message, stack, spec = null }) {
+  try {
+    const entries = readErrorJournal(journalPath)
+    entries.push({
+      id:       crypto.randomUUID(),
+      ts:       new Date().toISOString(),
+      route:    route || null,
+      phase,    // 'view' | 'action' | 'server' | 'guard' | 'sitemap'
+      message:  String(message || '').slice(0, 2000),
+      stack:    String(stack || '').slice(0, 4000),
+      spec,
+      resolved: false,
+    })
+    // Ring buffer — keep only the most recent entries
+    const trimmed = entries.slice(-ERROR_JOURNAL_LIMIT)
+    fs.mkdirSync(path.dirname(journalPath), { recursive: true })
+    fs.writeFileSync(journalPath, JSON.stringify(trimmed, null, 2), 'utf8')
+  } catch (journalErr) {
+    // Never let journal-write failures affect the actual error response
+    console.error('[Pulse] failed to write error journal:', journalErr.message)
+  }
+}
+
+function defaultErrorHandler(err, _req, res, dev = false, journalPath = null) {
   console.error('[Pulse] Server error:', err)
+  if (dev && journalPath) writeErrorEntry(journalPath, { route: _req?.url || null, phase: 'server', message: err.message, stack: err.stack })
   if (res.headersSent) return
 
   const html = dev ? errorPage(err) : errorPage500()

package/src/server/server.test.js

@@ -4,6 +4,9 @@
  */
 
 import http from 'http'
+import fs   from 'fs'
+import os   from 'os'
+import path from 'path'
 import { createServer, TtlCache } from './index.js'
 
 // ---------------------------------------------------------------------------
@@ -543,13 +546,17 @@ const throwingSpec = {
 }
 
 await test('dev mode returns HTML error page on render error (string mode)', async () => {
-  await withServer([throwingSpec], { stream: false, dev: true }, async (port) => {
+  // dev: true writes to the error journal at <root>/.pulse/errors.json — pass an
+  // isolated tmp root so this doesn't leave a file behind in the package directory.
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'pulse-boom-'))
+  await withServer([throwingSpec], { stream: false, dev: true, root: tmpRoot }, async (port) => {
     const { status, headers, body } = await get(port, '/boom')
     assert(status === 500,                            `Expected 500, got ${status}`)
     assert(headers['content-type']?.includes('text/html'), `Expected HTML, got ${headers['content-type']}`)
     assert(body.includes('view exploded'),             `Expected error message in page: ${body.slice(0, 200)}`)
     assert(body.includes('Stack trace'),              `Expected stack trace section in page`)
   })
+  fs.rmSync(tmpRoot, { recursive: true, force: true })
 })
 
 await test('production mode returns generic error page (no stack trace)', async () => {
@@ -562,12 +569,14 @@ await test('production mode returns generic error page (no stack trace)', async
 })
 
 await test('dev mode injects error into stream when render throws (stream mode)', async () => {
-  await withServer([throwingSpec], { stream: true, dev: true }, async (port) => {
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'pulse-boom-'))
+  await withServer([throwingSpec], { stream: true, dev: true, root: tmpRoot }, async (port) => {
     const { status, body } = await get(port, '/boom')
     assert(status === 200,                       `Stream mode commits 200 before error, got ${status}`)
     assert(body.includes('view exploded'),        `Expected error message injected into stream: ${body.slice(0, 400)}`)
     assert(body.includes('pulse-root'),           `Expected pulse-root in partial document`)
   })
+  fs.rmSync(tmpRoot, { recursive: true, force: true })
 })
 
 await test('production stream mode hides error details', async () => {
@@ -986,6 +995,21 @@ await test('CSP nonce differs between requests', async () => {
   })
 })
 
+await test('csp option extends trusted-types, merging with the base pulse policy', async () => {
+  // Regression: an agent assumed trusted-types/require-trusted-types-for
+  // weren't extendable via createServer's csp option (unlike other
+  // directives like img-src/style-src) because no guide demonstrated it —
+  // buildCsp's merge loop is actually fully generic across all directive
+  // keys, this was a documentation gap, not a real framework limitation.
+  // Pin the real behavior so it can't silently regress.
+  await withServer([canonicalSpec], { stream: false, csp: { 'trusted-types': ['google'] } }, async (port) => {
+    const { headers } = await request(port, 'GET', '/about')
+    const csp = headers['content-security-policy']
+    assert(csp.includes('trusted-types pulse google'),
+      `Expected trusted-types to merge with the base 'pulse' policy, got: ${csp}`)
+  })
+})
+
 await test('CSP header present on streaming page response', async () => {
   await withServer([canonicalSpec], { stream: true }, async (port) => {
     const { headers } = await request(port, 'GET', '/about')
@@ -994,6 +1018,38 @@ await test('CSP header present on streaming page response', async () => {
   })
 })
 
+// Cache-Control
+await test('HTML with no spec.cache/defaultCache gets no-cache, not no-store', async () => {
+  // Regression: a real Lighthouse audit failed "Page prevented back/forward
+  // cache restoration" with reason "cache-control:no-store" on a page that
+  // had no cache config at all — the framework's old default was no-store,
+  // which unconditionally blocks the browser's bfcache. no-cache still
+  // forces revalidation on every direct load (no risk of serving stale
+  // content) but does not block bfcache, since bfcache restoration never
+  // touches the network.
+  await withServer([canonicalSpec], { stream: false }, async (port) => {
+    const { headers } = await request(port, 'GET', '/about')
+    assert(headers['cache-control'] === 'no-cache',
+      `Expected no-cache, got: ${headers['cache-control']}`)
+  })
+})
+
+await test('HTML respects spec.cache / defaultCache when configured', async () => {
+  await withServer([helloSpec], { stream: false, defaultCache: 60 }, async (port) => {
+    const { headers } = await request(port, 'GET', '/hello')
+    assert(headers['cache-control']?.includes('max-age=60'),
+      `Expected max-age=60, got: ${headers['cache-control']}`)
+  })
+})
+
+await test('dev mode always returns no-store regardless of cache config', async () => {
+  await withServer([canonicalSpec], { stream: false, dev: true, defaultCache: 3600 }, async (port) => {
+    const { headers } = await request(port, 'GET', '/about')
+    assert(headers['cache-control'] === 'no-store',
+      `Expected no-store in dev mode, got: ${headers['cache-control']}`)
+  })
+})
+
 // HSTS
 await test('HSTS header absent on plain HTTP', async () => {
   await withServer([canonicalSpec], { stream: false }, async (port) => {
@@ -1800,6 +1856,32 @@ await test('hydrated pages receive the __PULSE_LIVE__ flag; disabled servers do
   })
 })
 
+await test('a store-only URL-entry spec (no local mutations/actions/persist, no explicit hydrate) still auto-derives a hydrate URL — regression: mount() is what wires up data-store-event dispatch AND the live SSE store-push subscription; without this a store-only page silently ships zero JS and never receives pushStore() broadcasts', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pulse-needshydration-store-test-'))
+  const specPath = path.join(dir, 'storey.js')
+  fs.writeFileSync(
+    specPath,
+    `export default {\n  route: '/storey',\n  store: ['count'],\n  state: {},\n  view: (state, server) => \`\${server.count ?? 0}\`,\n}\n`
+  )
+  try {
+    const port = nextPort++
+    const { server } = await createServer([new URL('file://' + specPath)], { stream: false, live: true, port, root: new URL('file://' + dir + '/') })
+    await new Promise(resolve => server.once('listening', resolve))
+    try {
+      const { body } = await get(port, '/storey')
+      // A store-only page with no auto-derived hydrate would render with no
+      // module script and no __PULSE_LIVE__ flag at all — both must be present.
+      assert(body.includes('<script type="module"'), `Expected a hydration script tag, got: ${body.slice(0, 800)}`)
+      assert(body.includes('__PULSE_LIVE__'), `Expected the live-store flag (only emitted for hydrated pages), got: ${body.slice(0, 800)}`)
+    } finally {
+      server.closeAllConnections?.()
+      await new Promise(resolve => server.close(resolve))
+    }
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+})
+
 // ---------------------------------------------------------------------------
 
 console.log('\nMalformed request handling\n')
@@ -1906,6 +1988,147 @@ await test('serves brotli-compressed HTML when br is accepted', async () => {
 })
 
 // ---------------------------------------------------------------------------
+// Route shadowing warning
+// ---------------------------------------------------------------------------
+// Regression: found via dogfooding. Route matching is first-match-wins in
+// registration order with no specificity ranking (see matchRoute) — a dynamic
+// route registered before a same-depth static route silently swallows every
+// request to that static route, with no error and no warning. discoverPages'
+// file-order is not guaranteed alphabetical across platforms, so this is a
+// real, easy-to-hit trap for any project mixing a catch-all-ish :param route
+// with static pages at the same path depth.
+
+console.log('\nRoute shadowing\n')
+
+const dynamicFirstSpec   = { route: '/:code', state: {}, view: () => '' }
+const staticShadowedSpec = { route: '/settings', state: {}, view: () => '' }
+const unrelatedSpec      = { route: '/about', state: {}, view: () => '' }
+
+// The warning fires synchronously inside createServer, before it starts
+// listening — capture around the whole createServer call, then tear the
+// server down immediately (nothing needs to actually run against it).
+async function warningsFromCreateServer(specs) {
+  const original = console.warn
+  const messages = []
+  console.warn = (msg) => messages.push(msg)
+  const port = nextPort++
+  let server
+  try {
+    ;({ server } = await createServer(specs, { port, stream: false, quiet: true }))
+    await new Promise(resolve => server.once('listening', resolve))
+  } finally {
+    console.warn = original
+    if (server) {
+      server.closeAllConnections?.()
+      await new Promise(resolve => server.close(resolve))
+    }
+  }
+  return messages
+}
+
+await test('warns when a dynamic route is registered before a static route it shadows', async () => {
+  const warnings = await warningsFromCreateServer([dynamicFirstSpec, staticShadowedSpec])
+  assert(warnings.some(w => w.includes('/:code') && w.includes('/settings') && w.includes('never be reached')),
+    `Expected a shadowing warning naming both routes, got: ${JSON.stringify(warnings)}`)
+})
+
+await test('no warning when the static route is registered first (correct order)', async () => {
+  const warnings = await warningsFromCreateServer([staticShadowedSpec, dynamicFirstSpec])
+  assert(warnings.length === 0, `Expected no warnings, got: ${JSON.stringify(warnings)}`)
+})
+
+await test('no warning between two unrelated static routes', async () => {
+  const warnings = await warningsFromCreateServer([staticShadowedSpec, unrelatedSpec])
+  assert(warnings.length === 0, `Expected no warnings, got: ${JSON.stringify(warnings)}`)
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nError journal\n')
+
+function makeTmpRoot() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'pulse-error-journal-'))
+}
+
+function readJournal(root) {
+  const p = path.join(root, '.pulse', 'errors.json')
+  return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf8')) : null
+}
+
+const journalThrowingSpec = {
+  route: '/boom-journal',
+  state: {},
+  view: () => { throw new Error('deliberate view failure') },
+}
+
+await test('server error in dev mode writes an entry to the journal', async () => {
+  const root = makeTmpRoot()
+  await withServer([journalThrowingSpec], { stream: false, dev: true, root }, async (port) => {
+    await get(port, '/boom-journal')
+    const entries = readJournal(root)
+    assert(entries && entries.length === 1, `Expected 1 journal entry, got ${JSON.stringify(entries)}`)
+    assert(entries[0].phase === 'server', `Expected phase "server", got ${entries[0].phase}`)
+    assert(entries[0].message.includes('deliberate view failure'), `Message missing detail: ${entries[0].message}`)
+    assert(entries[0].resolved === false, 'New entry should be unresolved')
+  })
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+await test('server error NOT in dev mode does not write a journal entry', async () => {
+  const root = makeTmpRoot()
+  await withServer([journalThrowingSpec], { stream: false, dev: false, root }, async (port) => {
+    await get(port, '/boom-journal')
+    const entries = readJournal(root)
+    assert(entries === null, `Expected no journal file in prod mode, got ${JSON.stringify(entries)}`)
+  })
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+await test('POST /__pulse/error in dev mode writes a client-reported entry', async () => {
+  const root = makeTmpRoot()
+  await withServer([helloSpec], { stream: false, dev: true, root }, async (port) => {
+    const { status } = await requestWithBody(
+      port, 'POST', '/__pulse/error',
+      JSON.stringify({ route: '/dashboard', phase: 'action', message: 'action "save" failed: boom', stack: 'Error: boom\n  at save' }),
+      'application/json'
+    )
+    assert(status === 204, `Expected 204, got ${status}`)
+    const entries = readJournal(root)
+    assert(entries && entries.length === 1, `Expected 1 journal entry, got ${JSON.stringify(entries)}`)
+    assert(entries[0].route === '/dashboard', `Expected route /dashboard, got ${entries[0].route}`)
+    assert(entries[0].phase === 'action', `Expected phase action, got ${entries[0].phase}`)
+  })
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+await test('POST /__pulse/error in production returns 404 — no dev-only endpoint exposed', async () => {
+  const root = makeTmpRoot()
+  await withServer([helloSpec], { stream: false, dev: false, root }, async (port) => {
+    const { status } = await requestWithBody(port, 'POST', '/__pulse/error', JSON.stringify({}), 'application/json')
+    assert(status === 404, `Expected 404 in production, got ${status}`)
+    assert(readJournal(root) === null, 'No journal file should exist in production')
+  })
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+await test('error journal is capped at 50 entries (ring buffer)', async () => {
+  const root = makeTmpRoot()
+  await withServer([helloSpec], { stream: false, dev: true, root }, async (port) => {
+    for (let i = 0; i < 55; i++) {
+      await requestWithBody(
+        port, 'POST', '/__pulse/error',
+        JSON.stringify({ route: '/x', phase: 'view', message: `error ${i}`, stack: '' }),
+        'application/json'
+      )
+    }
+    const entries = readJournal(root)
+    assert(entries.length === 50, `Expected 50 entries (capped), got ${entries.length}`)
+    // Oldest entries should have been dropped — the most recent should remain
+    assert(entries[entries.length - 1].message === 'error 54', `Expected newest entry to survive, got ${entries[entries.length - 1].message}`)
+    assert(entries[0].message === 'error 5', `Expected oldest surviving entry to be "error 5", got ${entries[0].message}`)
+  })
+  fs.rmSync(root, { recursive: true, force: true })
+})
 
 console.log('\nGraceful shutdown\n')
 

package/src/spec/schema.js

@@ -428,7 +428,7 @@ export function validateSpec(spec) {
   // the framework reading spec.meta.vibe directly — this check catches unknown keys)
   if (spec.meta && typeof spec.meta === 'object' && !Array.isArray(spec.meta)) {
     const KNOWN_META_KEYS = new Set([
-      'title', 'description', 'styles', 'scripts', 'theme', 'vibe',
+      'title', 'description', 'styles', 'deferredStyles', 'scripts', 'theme', 'vibe',
       'ogTitle', 'ogDescription', 'ogImage', 'canonical', 'schema',
       'robots', 'viewport', 'charset', 'lang',
     ])

package/src/ui/index.js

@@ -22,8 +22,6 @@ export { button }      from './button.js'
 export { badge }       from './badge.js'
 export { card }        from './card.js'
 export { input }       from './input.js'
-export { search }      from './search.js'
-export { fieldset }    from './fieldset.js'
 export { select }      from './select.js'
 export { textarea }    from './textarea.js'
 export { alert }       from './alert.js'
@@ -32,7 +30,6 @@ export { avatar }      from './avatar.js'
 export { empty }       from './empty.js'
 export { table }       from './table.js'
 export { hero }        from './hero.js'
-export { phoneFrame }  from './phone-frame.js'
 export { feature }     from './feature.js'
 export { accordion }   from './accordion.js'
 export { nav }         from './nav.js'
@@ -44,7 +41,6 @@ export { stack }       from './stack.js'
 export { cluster }     from './cluster.js'
 export { divider }     from './divider.js'
 export { media }         from './media.js'
-export { tooltip }       from './tooltip.js'
 export { modal, modalTrigger } from './modal.js'
 export { cta }           from './cta.js'
 export { footer }        from './footer.js'
@@ -55,7 +51,6 @@ export { rating }                from './rating.js'
 export { spinner }               from './spinner.js'
 export { progress }              from './progress.js'
 export { slider }      from './slider.js'
-export { segmented }   from './segmented.js'
 export { fileUpload }  from './fileupload.js'
 export { breadcrumbs } from './breadcrumbs.js'
 export { stepper }     from './stepper.js'