@invisibleloop/pulse 0.2.6 → 0.2.8

package/CLAUDE.md

@@ -228,12 +228,15 @@ All specs are validated at startup — bad specs throw before the server accepts
 
 Pass `resolveBrand: async (host) => brandConfig` to `createServer`. The result is cached per host for 60 seconds and attached to `ctx.brand`. It is available in `guard`, `server` fetchers, and any `meta` field that is a function.
 
-Any `meta` field can be a function `(ctx) => value` — called per request, not at startup:
+Any `meta` field can be a function `(ctx) => value` — called per request, not at startup. Meta functions can also be **async**, so you can fetch data for `title`, `description`, `ogImage` etc.:
 
 ```js
 export default {
   meta: {
-    title:  (ctx) => `${ctx.brand.name} — Home`,
+    title:  async (ctx) => {
+      const product = await fetchProduct(ctx.params.id)
+      return product ? `${product.name} — Store` : 'Store'
+    },
     styles: (ctx) => ['/pulse-ui.css', `/themes/${ctx.brand.slug}.css`],
   },
   server: {
@@ -246,6 +249,34 @@ export default {
 }
 ```
 
+If `meta` and `server` both need the same API data, use a **request-scoped cache** on `ctx` to avoid fetching twice. `ctx` is created fresh per request, so `ctx._cache` never leaks between requests:
+
+```js
+// shared-fetchers.js
+export async function getProduct(ctx) {
+  ctx._cache        ??= {}
+  ctx._cache.product ??= await db.products.find(ctx.params.id)
+  return ctx._cache.product
+}
+```
+
+```js
+// spec
+import { getProduct } from './shared-fetchers.js'
+
+export default {
+  meta: {
+    title: async (ctx) => {
+      const p = await getProduct(ctx)   // fetches once, cached on ctx
+      return p ? `${p.name} — Store` : 'Store'
+    },
+  },
+  server: {
+    product: (ctx) => getProduct(ctx),  // hits the same cache, no second fetch
+  },
+}
+```
+
 Keep brand differences in CSS custom properties — one `/pulse-ui.css` for components, one small `/themes/slug.css` per brand that overrides `:root` variables only.
 
 ## Custom Fonts

package/docs/public/.pulse-ui-version

@@ -1 +1 @@
-0.2.2
+0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.2.6
+0.2.8

package/scripts/build.js

@@ -468,6 +468,20 @@ async function purgeCssStep(pages, manifest, root, outDir) {
     }
   }
 
+  // Scan pulse UI package source — class names generated by UI components
+  // (breadcrumbs, avatar, container, etc.) only appear in the package source,
+  // not in the project's own pages, so they'd otherwise be purged.
+  const scanUiDirs = [
+    path.join(root, 'src', 'ui'),  // pulse2 own source
+    path.join(root, 'node_modules', '@invisibleloop', 'pulse', 'src', 'ui'),  // installed package
+  ]
+  for (const dir of scanUiDirs) {
+    if (!fs.existsSync(dir)) continue
+    for (const f of fs.readdirSync(dir).filter(f => f.endsWith('.js'))) {
+      try { jsContents.push(fs.readFileSync(path.join(dir, f), 'utf8')) } catch {}
+    }
+  }
+
   if (cssFiles.size === 0) {
     console.log('  No CSS files referenced — skipping.\n')
     return

package/src/cli/dev.js

@@ -25,16 +25,15 @@ const ROOT = rootArg !== -1
   ? path.resolve(args[rootArg + 1])
   : process.cwd()
 
+let _config = {}
+const configPath = path.join(ROOT, 'pulse.config.js')
+if (fs.existsSync(configPath)) {
+  try { _config = (await import(configPath)).default ?? {} } catch { /* ignore */ }
+}
+
 async function resolvePort() {
   if (portArg !== -1) return parseInt(args[portArg + 1], 10)
-  const configPath = path.join(ROOT, 'pulse.config.js')
-  if (fs.existsSync(configPath)) {
-    try {
-      const mod = await import(configPath)
-      if (mod.default?.port) return mod.default.port
-    } catch { /* fall through */ }
-  }
-  return 3000
+  return _config.port || 3000
 }
 
 const PORT = await resolvePort()
@@ -148,6 +147,7 @@ const { updateSpecs } = createServer(specs, {
   manifest:  {},        // never use a build manifest in dev — always serve source files
   extraBody: reloadScript,
   dev:       true,
+  ...(_config.csp ? { csp: _config.csp } : {}),
 
   onRequest(req, res) {
     const url = req.url.split('?')[0]

package/src/cli/start.js

@@ -42,6 +42,7 @@ if (!fs.existsSync(manifestPath)) {
 
 let port         = portArg !== -1 ? parseInt(args[portArg + 1], 10) : null
 let defaultCache = null
+let csp          = null
 
 const configPath = path.join(ROOT, 'pulse.config.js')
 if (fs.existsSync(configPath)) {
@@ -49,6 +50,7 @@ if (fs.existsSync(configPath)) {
     const mod    = await import(configPath)
     port         = port || mod.default?.port || null
     defaultCache = mod.default?.defaultCache ?? null
+    csp          = mod.default?.csp ?? null
   } catch { /* ignore */ }
 }
 
@@ -71,4 +73,5 @@ createServer(specs, {
   stream:       true,
   staticDir:    PUBLIC_DIR,
   defaultCache,
+  ...(csp ? { csp } : {}),
 })

package/src/server/index.js

@@ -708,7 +708,7 @@ export function createServer(specs, options = {}) {
  */
 async function handleNavResponse(spec, ctx, res, dev = false) {
   const { html, serverState } = await cachedRenderToString(spec, ctx, dev)
-  const meta = resolveMeta(spec.meta, ctx)
+  const meta = await resolveMeta(spec.meta, ctx)
 
   const payload = JSON.stringify({
     html,
@@ -735,7 +735,7 @@ async function handleNavResponse(spec, ctx, res, dev = false) {
  * showing shell content without waiting for slower deferred fetchers.
  */
 async function handleNavStreamResponse(spec, ctx, req, res) {
-  const meta = resolveMeta(spec.meta, ctx)
+  const meta = await resolveMeta(spec.meta, ctx)
 
   res.writeHead(200, {
     'Content-Type':      'application/x-ndjson',
@@ -791,7 +791,7 @@ async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = f
       ? (canonicalRaw(ctx, serverState) || canonicalBase)
       : (canonicalRaw || canonicalBase)
     const canonicalTag      = canonicalUrl ? `<link rel="canonical" href="${escHtml(canonicalUrl)}">` : ''
-    const resolvedSpec      = { ...spec, meta: resolveMeta(spec.meta, ctx) }
+    const resolvedSpec      = { ...spec, meta: await resolveMeta(spec.meta, ctx) }
     const resolvedExtraBody = typeof extraBody === 'function' ? extraBody(nonce) : extraBody
     const wrapped           = wrapDocument({ content, spec: resolvedSpec, serverState, storeState: ctx.store || null, storeDef: store || null, timing, extraBody: resolvedExtraBody, extraHead: (dev ? devImportMap(nonce) + '\n  ' : '') + canonicalTag, nonce, runtimeBundle, faviconHref: faviconPath || '' })
     html              = wrapped.html
@@ -847,7 +847,7 @@ async function handleStreamResponse(spec, ctx, req, res, extraBody = '', dev = f
   const t0 = performance.now()
 
   // Write the document opening immediately so the browser starts parsing
-  const meta  = resolveMeta(spec.meta, ctx)
+  const meta  = await resolveMeta(spec.meta, ctx)
   const title = meta.title || 'Pulse'
   // Resolve canonical — supports a string or a function receiving (ctx).
   // Note: server fetcher results are not yet available when the <head> is written in streaming mode.
@@ -1389,12 +1389,14 @@ function serveStatic(req, res, staticDir, dev = false) {
  * @param {Object} ctx
  * @returns {Object}
  */
-function resolveMeta(meta, ctx) {
+async function resolveMeta(meta, ctx) {
   if (!meta) return {}
   const resolved = {}
-  for (const [key, val] of Object.entries(meta)) {
-    resolved[key] = typeof val === 'function' ? val(ctx) : val
-  }
+  await Promise.all(
+    Object.entries(meta).map(async ([key, val]) => {
+      resolved[key] = typeof val === 'function' ? await val(ctx) : val
+    })
+  )
   return resolved
 }
 

package/src/server/server.test.js

@@ -225,6 +225,32 @@ await test('sets title from spec.meta', async () => {
   })
 })
 
+await test('resolves async meta.title function (string mode)', async () => {
+  const spec = {
+    route: '/async-meta',
+    state: {},
+    view:  () => '<p>content</p>',
+    meta:  { title: async () => 'Async Title' },
+  }
+  await withServer([spec], { stream: false }, async (port) => {
+    const { body } = await get(port, '/async-meta')
+    assert(body.includes('<title>Async Title</title>'), `Expected async title: ${body}`)
+  })
+})
+
+await test('resolves async meta.title function (streaming mode)', async () => {
+  const spec = {
+    route: '/async-meta-stream',
+    state: {},
+    view:  () => '<p>content</p>',
+    meta:  { title: async () => 'Stream Async Title' },
+  }
+  await withServer([spec], { stream: true }, async (port) => {
+    const { body } = await get(port, '/async-meta-stream')
+    assert(body.includes('<title>Stream Async Title</title>'), `Expected async title in stream: ${body}`)
+  })
+})
+
 await test('injects JSON-LD script when meta.schema is set (string mode)', async () => {
   const spec = {
     route: '/article',
@@ -428,49 +454,56 @@ const deferredNavSpec = {
 
 console.log('\nClient-side navigation — streaming (stream: true)\n')
 
-await test('X-Pulse-Navigate with stream:true returns application/x-ndjson', async () => {
-  await withServer([streamNavSpec], {}, async (port) => {
-    const { status, headers } = await request(port, 'GET', '/stream-nav', { 'X-Pulse-Navigate': 'true' })
+await test('X-Pulse-Navigate with stream:true returns application/x-ndjson for deferred specs', async () => {
+  await withServer([deferredNavSpec], { stream: true }, async (port) => {
+    const { status, headers } = await request(port, 'GET', '/deferred-nav', { 'X-Pulse-Navigate': 'true' })
     assert(status === 200, `Expected 200, got ${status}`)
     assert(headers['content-type']?.includes('application/x-ndjson'), `Expected NDJSON: ${headers['content-type']}`)
   })
 })
 
+await test('X-Pulse-Navigate with stream:true returns application/json for non-deferred specs', async () => {
+  await withServer([streamNavSpec], { stream: true }, async (port) => {
+    const { status, headers } = await request(port, 'GET', '/stream-nav', { 'X-Pulse-Navigate': 'true' })
+    assert(status === 200, `Expected 200, got ${status}`)
+    assert(headers['content-type']?.includes('application/json'), `Expected JSON: ${headers['content-type']}`)
+  })
+})
+
 await test('streaming nav: first NDJSON line is a meta message with title and hydrate', async () => {
-  await withServer([streamNavSpec], {}, async (port) => {
-    const { body } = await request(port, 'GET', '/stream-nav', { 'X-Pulse-Navigate': 'true' })
+  await withServer([deferredNavSpec], { stream: true }, async (port) => {
+    const { body } = await request(port, 'GET', '/deferred-nav', { 'X-Pulse-Navigate': 'true' })
     const lines    = body.trim().split('\n').filter(Boolean)
     const meta     = JSON.parse(lines[0])
-    assert(meta.type === 'meta',                      `First line should be meta, got ${meta.type}`)
-    assert(meta.title === 'Stream Nav',               `Expected title 'Stream Nav', got ${meta.title}`)
-    assert(meta.hydrate === '/examples/stream-nav.js', `Expected hydrate, got ${meta.hydrate}`)
-    assert(meta.styles[0] === '/app.css',             `Expected styles, got ${JSON.stringify(meta.styles)}`)
+    assert(meta.type === 'meta',                            `First line should be meta, got ${meta.type}`)
+    assert(meta.title === 'Deferred Nav',                   `Expected title 'Deferred Nav', got ${meta.title}`)
+    assert(meta.hydrate === '/examples/deferred-nav.js',    `Expected hydrate, got ${meta.hydrate}`)
   })
 })
 
 await test('streaming nav: html message contains rendered server data', async () => {
-  await withServer([streamNavSpec], {}, async (port) => {
-    const { body }  = await request(port, 'GET', '/stream-nav', { 'X-Pulse-Navigate': 'true' })
+  await withServer([deferredNavSpec], { stream: true }, async (port) => {
+    const { body }  = await request(port, 'GET', '/deferred-nav', { 'X-Pulse-Navigate': 'true' })
     const messages  = body.trim().split('\n').filter(Boolean).map(l => JSON.parse(l))
     const htmlMsg   = messages.find(m => m.type === 'html')
     assert(htmlMsg,                                    'should have html message')
-    assert(htmlMsg.html.includes('streamed hello'),    `Expected server data in html: ${htmlMsg.html}`)
+    assert(htmlMsg.html.includes('shell-data'),        `Expected shell server data in html: ${htmlMsg.html}`)
     assert(!htmlMsg.html.includes('<!DOCTYPE'),        'html should not be a full document')
   })
 })
 
 await test('streaming nav: done message contains serverState', async () => {
-  await withServer([streamNavSpec], {}, async (port) => {
-    const { body }   = await request(port, 'GET', '/stream-nav', { 'X-Pulse-Navigate': 'true' })
+  await withServer([deferredNavSpec], { stream: true }, async (port) => {
+    const { body }   = await request(port, 'GET', '/deferred-nav', { 'X-Pulse-Navigate': 'true' })
     const messages   = body.trim().split('\n').filter(Boolean).map(l => JSON.parse(l))
     const done       = messages.find(m => m.type === 'done')
-    assert(done,                                          'should have done message')
-    assert(done.serverState?.msg === 'streamed hello',    `Expected serverState.msg, got ${JSON.stringify(done.serverState)}`)
+    assert(done,                                              'should have done message')
+    assert(done.serverState?.fast === 'shell-data',           `Expected serverState.fast, got ${JSON.stringify(done.serverState)}`)
   })
 })
 
 await test('streaming nav: deferred spec sends shell then deferred then done', async () => {
-  await withServer([deferredNavSpec], {}, async (port) => {
+  await withServer([deferredNavSpec], { stream: true }, async (port) => {
     const { body }   = await request(port, 'GET', '/deferred-nav', { 'X-Pulse-Navigate': 'true' })
     const messages   = body.trim().split('\n').filter(Boolean).map(l => JSON.parse(l))
     const types      = messages.map(m => m.type)
@@ -491,7 +524,7 @@ await test('streaming nav: deferred spec sends shell then deferred then done', a
 })
 
 await test('streaming nav: html includes <pulse-deferred> placeholder for deferred segments', async () => {
-  await withServer([deferredNavSpec], {}, async (port) => {
+  await withServer([deferredNavSpec], { stream: true }, async (port) => {
     const { body }  = await request(port, 'GET', '/deferred-nav', { 'X-Pulse-Navigate': 'true' })
     const messages  = body.trim().split('\n').filter(Boolean).map(l => JSON.parse(l))
     const html      = messages.find(m => m.type === 'html')

package/src/ui/ui.test.js

@@ -40,6 +40,7 @@ import { radio, radioGroup } from './radio.js'
 import { segmented }  from './segmented.js'
 import { fileUpload } from './fileupload.js'
 import { modal, modalTrigger } from './modal.js'
+import { uiImage }             from './uiimage.js'
 
 // ─── button ─────────────────────────────────────────────────────────────────
 
@@ -1244,4 +1245,43 @@ test('modalTrigger: escapes target id to prevent XSS', () => {
   assert.doesNotMatch(html, /<script>/)
 })
 
+// ─── uiImage ────────────────────────────────────────────────────────────────
+
+test('uiImage: renders img with src and alt', () => {
+  const html = uiImage({ src: '/photo.jpg', alt: 'A photo' })
+  assert.match(html, /src="\/photo\.jpg"/)
+  assert.match(html, /alt="A photo"/)
+})
+
+test('uiImage: defaults to loading="lazy"', () => {
+  const html = uiImage({ src: '/photo.jpg', alt: '' })
+  assert.match(html, /loading="lazy"/)
+})
+
+test('uiImage: accepts loading="eager"', () => {
+  const html = uiImage({ src: '/photo.jpg', alt: '', loading: 'eager' })
+  assert.match(html, /loading="eager"/)
+})
+
+test('uiImage: omits fetchpriority when not set', () => {
+  const html = uiImage({ src: '/photo.jpg', alt: '' })
+  assert.doesNotMatch(html, /fetchpriority/)
+})
+
+test('uiImage: renders fetchpriority="high" when set', () => {
+  const html = uiImage({ src: '/photo.jpg', alt: '', fetchpriority: 'high' })
+  assert.match(html, /fetchpriority="high"/)
+})
+
+test('uiImage: wraps in aspect-ratio crop when ratio given', () => {
+  const html = uiImage({ src: '/photo.jpg', alt: '', ratio: '16/9' })
+  assert.match(html, /aspect-ratio:16\/9/)
+  assert.match(html, /ui-image-img--cover/)
+})
+
+test('uiImage: escapes src to prevent XSS', () => {
+  const html = uiImage({ src: '"><script>alert(1)</script>', alt: '' })
+  assert.doesNotMatch(html, /<script>/)
+})
+
 console.log('✓ All UI component tests passed')

package/src/ui/uiimage.js

@@ -15,21 +15,25 @@
  * @param {number|string} opts.height   - img height attribute
  * @param {number|string} opts.maxWidth - CSS max-width on the figure (px value or CSS string). Use this to constrain portrait/narrow images inside wide columns.
  * @param {string}  opts.class
+ * @param {string}  opts.loading      - 'lazy' (default) or 'eager' — use 'eager' for above-the-fold / LCP images
+ * @param {string}  opts.fetchpriority - 'high' | 'low' | 'auto' — set 'high' on the LCP image
  */
 
 import { escHtml as e } from '../html.js'
 
 export function uiImage({
-  src        = '',
-  alt        = '',
-  caption    = '',
-  ratio      = '',
-  rounded    = false,
-  pill       = false,
-  width      = '',
-  height     = '',
-  maxWidth   = '',
-  class: cls = '',
+  src           = '',
+  alt           = '',
+  caption       = '',
+  ratio         = '',
+  rounded       = false,
+  pill          = false,
+  width         = '',
+  height        = '',
+  maxWidth      = '',
+  loading       = 'lazy',
+  fetchpriority = '',
+  class: cls    = '',
 } = {}) {
   // The outer figure uses display:contents so the inner crop div
   // becomes a direct flex/block child of whatever container holds it.
@@ -40,8 +44,9 @@ export function uiImage({
     ? ` style="max-width:${e(typeof maxWidth === 'number' ? `${maxWidth}px` : maxWidth)};margin-left:auto;margin-right:auto"`
     : ''
 
-  const widthAttr  = width  ? ` width="${e(String(width))}"` : ''
-  const heightAttr = height ? ` height="${e(String(height))}"` : ''
+  const widthAttr         = width         ? ` width="${e(String(width))}"` : ''
+  const heightAttr        = height        ? ` height="${e(String(height))}"` : ''
+  const fetchpriorityAttr = fetchpriority ? ` fetchpriority="${e(fetchpriority)}"` : ''
 
   const captionHtml = caption
     ? `<figcaption class="ui-image-caption">${e(caption)}</figcaption>`
@@ -50,7 +55,7 @@ export function uiImage({
   if (ratio) {
     return `<figure class="${e(figClasses)}"${maxWidthStyle}>
   <div class="ui-image-crop" style="aspect-ratio:${e(ratio)}">
-    <img src="${e(src)}" alt="${e(alt)}" class="ui-image-img--cover"${widthAttr}${heightAttr} loading="lazy" decoding="async">
+    <img src="${e(src)}" alt="${e(alt)}" class="ui-image-img--cover"${widthAttr}${heightAttr} loading="${e(loading)}" decoding="async"${fetchpriorityAttr}>
   </div>
   ${captionHtml}
 </figure>`
@@ -58,7 +63,7 @@ export function uiImage({
 
   return `<figure class="${e(figClasses)}"${maxWidthStyle}>
   <div class="ui-image-wrap">
-    <img src="${e(src)}" alt="${e(alt)}" class="ui-image-img"${widthAttr}${heightAttr} loading="lazy" decoding="async">
+    <img src="${e(src)}" alt="${e(alt)}" class="ui-image-img"${widthAttr}${heightAttr} loading="${e(loading)}" decoding="async"${fetchpriorityAttr}>
   </div>
   ${captionHtml}
 </figure>`