@invisibleloop/pulse 0.1.21

package/src/mcp/validate-worker.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * validate-worker.js
+ *
+ * Runs spec validation in an isolated child process so a hanging import
+ * cannot block the MCP server. Called by validateContent() in server.js.
+ *
+ * Usage: node validate-worker.js <tmpFilePath>
+ * Exits with stdout containing the validation result text.
+ */
+
+import { validateSpec } from '../spec/schema.js'
+
+const tmpFile = process.argv[2]
+if (!tmpFile) { process.stdout.write('Invalid: no file path provided'); process.exit(0) }
+
+let mod
+try {
+  mod = await import(tmpFile)
+} catch (err) {
+  process.stdout.write(`Invalid: could not parse — ${err.message}`)
+  process.exit(0)
+}
+
+const spec = mod.default
+if (!spec || typeof spec !== 'object') {
+  process.stdout.write('Invalid: file must export a default spec object')
+  process.exit(0)
+}
+
+const { valid, errors, warnings: schemaWarnings } = validateSpec(spec)
+if (!valid) {
+  process.stdout.write('Invalid:\n' + errors.map(e => `  — ${e}`).join('\n'))
+  process.exit(0)
+}
+
+// Render the view and run additional HTML checks
+const warnings = [...schemaWarnings]
+try {
+  // Pass null for every declared server key so views that check `=== null`
+  // degrade gracefully (showing error branches) rather than throwing on
+  // `undefined.someProperty` when the real fetchers haven't run.
+  const serverMock = spec.server && typeof spec.server === 'object'
+    ? Object.fromEntries(Object.keys(spec.server).map(k => [k, null]))
+    : {}
+  const html = typeof spec.view === 'function'
+    ? spec.view(spec.state || {}, serverMock)
+    : ''
+
+  // Heading hierarchy — headings must not skip levels
+  const levels = [...html.matchAll(/<h([1-6])[\s>]/gi)].map(m => parseInt(m[1], 10))
+  for (let i = 1; i < levels.length; i++) {
+    if (levels[i] > levels[i - 1] + 1) {
+      warnings.push(`Heading order: h${levels[i - 1]} → h${levels[i]} skips a level (Lighthouse will flag this)`)
+    }
+  }
+  if (levels.length > 0 && levels[0] !== 1) {
+    warnings.push(`Heading order: page starts with h${levels[0]}, expected h1`)
+  }
+
+  // Missing main landmark
+  if (!/id=["']main-content["']/.test(html)) {
+    warnings.push('Missing <main id="main-content"> — required for accessibility and Lighthouse landmark audit')
+  }
+
+  // aria-live + aria-label on the same element — aria-label suppresses live region announcements
+  const tagPattern = /<[a-z][^>]*>/gi
+  let tagMatch
+  while ((tagMatch = tagPattern.exec(html)) !== null) {
+    const tag = tagMatch[0]
+    if (/aria-live/i.test(tag) && /aria-label/i.test(tag)) {
+      warnings.push('aria-live and aria-label on the same element — aria-label suppresses live region announcements in some screen readers. Remove aria-label and let the content speak for itself')
+      break
+    }
+  }
+
+  // data-event on text inputs — causes focus loss on every keystroke
+  const inputTags = [...html.matchAll(/<input[^>]+>/gi)].map(m => m[0])
+  for (const tag of inputTags) {
+    const isText = !/type=["'](checkbox|radio|range|color|submit|button|reset|file|hidden)/i.test(tag)
+    if (isText && /data-event/i.test(tag)) {
+      warnings.push('data-event on a text input causes focus loss on every keystroke — use data-action on the wrapping <form> and read values from FormData in action.onStart instead')
+      break
+    }
+  }
+
+  // Unknown u-* utility classes — catch invented classes that have no CSS definition
+  const KNOWN_UTILS = new Set(['u-absolute','u-bg-accent','u-bg-surface','u-bg-surface2','u-block','u-border','u-border-b','u-border-t','u-flex','u-flex-1','u-flex-col','u-flex-wrap','u-font-bold','u-font-medium','u-font-normal','u-font-semibold','u-gap-1','u-gap-2','u-gap-3','u-gap-4','u-gap-5','u-gap-6','u-gap-8','u-hidden','u-inline','u-inline-block','u-items-center','u-items-end','u-items-start','u-items-stretch','u-justify-between','u-justify-center','u-justify-end','u-justify-start','u-leading-loose','u-leading-normal','u-leading-relaxed','u-leading-snug','u-leading-tight','u-max-w-lg','u-max-w-md','u-max-w-prose','u-max-w-sm','u-max-w-xl','u-max-w-xs','u-mb-0','u-mb-1','u-mb-10','u-mb-12','u-mb-16','u-mb-2','u-mb-3','u-mb-4','u-mb-5','u-mb-6','u-mb-8','u-ml-auto','u-mr-auto','u-mt-0','u-mt-1','u-mt-10','u-mt-12','u-mt-16','u-mt-2','u-mt-3','u-mt-4','u-mt-5','u-mt-6','u-mt-8','u-mx-auto','u-opacity-50','u-opacity-75','u-overflow-auto','u-overflow-hidden','u-p-0','u-p-1','u-p-2','u-p-3','u-p-4','u-p-5','u-p-6','u-p-8','u-px-0','u-px-2','u-px-3','u-px-4','u-px-5','u-px-6','u-px-8','u-py-0','u-py-2','u-py-3','u-py-4','u-py-5','u-py-6','u-py-8','u-relative','u-rounded','u-rounded-full','u-rounded-lg','u-rounded-md','u-rounded-xl','u-shrink-0','u-text-2xl','u-text-3xl','u-text-4xl','u-text-accent','u-text-balance','u-text-base','u-text-blue','u-text-center','u-text-default','u-text-green','u-text-left','u-text-lg','u-text-muted','u-text-red','u-text-right','u-text-sm','u-text-xl','u-text-xs','u-text-yellow','u-w-auto','u-w-full'])
+  const usedUtils = new Set([...html.matchAll(/\bu-([\w-]+)/g)].map(m => 'u-' + m[1]))
+  const unknownUtils = [...usedUtils].filter(c => !KNOWN_UTILS.has(c))
+  if (unknownUtils.length) {
+    warnings.push(`Unknown utility class${unknownUtils.length > 1 ? 'es' : ''}: ${unknownUtils.join(', ')} — these have no CSS definition and will have no effect. Check the guide for the available u-* classes, or use layout components (container, section, grid, stack, cluster) instead.`)
+  }
+
+  // input[type="file"] used directly — fileUpload() component should be used instead
+  if (inputTags.some(tag => /type=["']file["']/i.test(tag))) {
+    warnings.push('input[type="file"] detected — use the fileUpload() component instead. It provides the drag-and-drop zone, correct styling, and pulse-ui.js integration. import { fileUpload } from \'@invisibleloop/pulse/ui\'')
+  }
+
+  // Unescaped apostrophes in attribute values
+  if (/=\s*'[^']*'[^']*'/.test(html)) {
+    warnings.push('Possible unescaped apostrophe in an HTML attribute — use &apos; or &#39; or switch to double quotes')
+  }
+} catch { /* view may depend on server data — skip HTML checks */ }
+
+if (warnings.length > 0) {
+  process.stdout.write('Valid ✓ — but fix these issues:\n' + warnings.map(w => `  ⚠ ${w}`).join('\n'))
+} else {
+  process.stdout.write('Valid ✓')
+}

package/src/runtime/image.js

@@ -0,0 +1,74 @@
+/**
+ * Pulse — Image helpers
+ *
+ * Generates optimised image markup with correct attributes for CLS and LCP.
+ * Import in page specs or components:
+ *   import { img, picture } from '/@pulse/runtime/image.js'  (dev)
+ *   import { img, picture } from '@invisibleloop/pulse/image' (production)
+ */
+
+function esc(str) {
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/"/g, '"')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+/**
+ * Generate an optimised <img> tag.
+ *
+ * Always include width + height to prevent CLS.
+ * Use priority: true for the LCP image (above the fold hero).
+ *
+ * @param {Object} options
+ * @param {string}  options.src        - Image URL
+ * @param {string}  options.alt        - Alt text (required for accessibility)
+ * @param {number}  [options.width]    - Intrinsic width in px — prevents CLS
+ * @param {number}  [options.height]   - Intrinsic height in px — prevents CLS
+ * @param {boolean} [options.priority] - true for LCP image: eager + high fetchpriority
+ * @param {string}  [options.class]    - CSS class
+ * @returns {string}
+ */
+export function img({ src, alt, width, height, priority = false, class: cls }) {
+  const attrs = [
+    `src="${esc(src)}"`,
+    `alt="${esc(alt)}"`,
+    width  != null ? `width="${width}"`   : '',
+    height != null ? `height="${height}"` : '',
+    `loading="${priority ? 'eager' : 'lazy'}"`,
+    `decoding="async"`,
+    priority ? 'fetchpriority="high"' : '',
+    cls ? `class="${esc(cls)}"` : '',
+  ].filter(Boolean).join(' ')
+
+  return `<img ${attrs}>`
+}
+
+/**
+ * Generate a <picture> element with modern format sources + fallback <img>.
+ *
+ * Provide sources in preference order (AVIF first, then WebP, then fallback src).
+ * The fallback src on the <img> is the universal baseline (JPEG/PNG).
+ *
+ * @param {Object}   options
+ * @param {string}   options.src          - Fallback image URL (JPEG/PNG)
+ * @param {string}   options.alt          - Alt text
+ * @param {number}   [options.width]      - Intrinsic width — prevents CLS
+ * @param {number}   [options.height]     - Intrinsic height — prevents CLS
+ * @param {boolean}  [options.priority]   - true for LCP image
+ * @param {string}   [options.class]      - CSS class applied to <img>
+ * @param {Array<{src: string, type: string}>} [options.sources]
+ *   Modern format sources, e.g.:
+ *   [{ src: '/hero.avif', type: 'image/avif' }, { src: '/hero.webp', type: 'image/webp' }]
+ * @returns {string}
+ */
+export function picture({ src, alt, width, height, priority = false, class: cls, sources = [] }) {
+  const sourceEls = sources
+    .map(s => `<source srcset="${esc(s.src)}" type="${esc(s.type)}">`)
+    .join('\n  ')
+
+  const imgEl = img({ src, alt, width, height, priority, class: cls })
+
+  return `<picture>\n  ${sourceEls}\n  ${imgEl}\n</picture>`
+}

package/src/runtime/image.test.js

@@ -0,0 +1,111 @@
+/**
+ * Pulse — Image helper tests
+ * run: node src/runtime/image.test.js
+ */
+
+import { img, picture } from './image.js'
+
+let passed = 0
+let failed = 0
+
+function test(label, fn) {
+  try {
+    fn()
+    console.log(`  ✓ ${label}`)
+    passed++
+  } catch (e) {
+    console.log(`  ✗ ${label}`)
+    console.log(`    ${e.message}`)
+    failed++
+  }
+}
+
+function assert(condition, msg) {
+  if (!condition) throw new Error(msg || 'Assertion failed')
+}
+
+// ---------------------------------------------------------------------------
+
+console.log('\nimg()\n')
+
+test('renders src and alt', () => {
+  const out = img({ src: '/photo.jpg', alt: 'A photo' })
+  assert(out.includes('src="/photo.jpg"'), `Missing src: ${out}`)
+  assert(out.includes('alt="A photo"'),    `Missing alt: ${out}`)
+})
+
+test('renders width and height', () => {
+  const out = img({ src: '/x.jpg', alt: '', width: 800, height: 600 })
+  assert(out.includes('width="800"'),  `Missing width: ${out}`)
+  assert(out.includes('height="600"'), `Missing height: ${out}`)
+})
+
+test('defaults to lazy loading', () => {
+  const out = img({ src: '/x.jpg', alt: '' })
+  assert(out.includes('loading="lazy"'), `Expected lazy: ${out}`)
+  assert(!out.includes('fetchpriority="high"'), `Should not have high priority: ${out}`)
+})
+
+test('priority sets eager loading and high fetchpriority', () => {
+  const out = img({ src: '/hero.jpg', alt: 'Hero', priority: true })
+  assert(out.includes('loading="eager"'),       `Expected eager: ${out}`)
+  assert(out.includes('fetchpriority="high"'),  `Expected high fetchpriority: ${out}`)
+})
+
+test('always includes decoding="async"', () => {
+  const out = img({ src: '/x.jpg', alt: '' })
+  assert(out.includes('decoding="async"'), `Missing decoding: ${out}`)
+})
+
+test('applies class attribute', () => {
+  const out = img({ src: '/x.jpg', alt: '', class: 'card-img' })
+  assert(out.includes('class="card-img"'), `Missing class: ${out}`)
+})
+
+test('escapes alt text', () => {
+  const out = img({ src: '/x.jpg', alt: 'A "quoted" & <tagged> image' })
+  assert(!out.includes('"quoted"'),  `Should escape quotes in alt: ${out}`)
+  assert(out.includes('&amp;'),      `Should escape & in alt: ${out}`)
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\npicture()\n')
+
+test('wraps img in picture element', () => {
+  const out = picture({ src: '/x.jpg', alt: 'test', width: 100, height: 100 })
+  assert(out.includes('<picture>'),  `Missing <picture>: ${out}`)
+  assert(out.includes('</picture>'), `Missing </picture>: ${out}`)
+  assert(out.includes('<img '),      `Missing <img>: ${out}`)
+})
+
+test('includes source elements for each format', () => {
+  const out = picture({
+    src: '/x.jpg', alt: '',
+    sources: [
+      { src: '/x.avif', type: 'image/avif' },
+      { src: '/x.webp', type: 'image/webp' },
+    ]
+  })
+  assert(out.includes('image/avif'), `Missing avif source: ${out}`)
+  assert(out.includes('image/webp'), `Missing webp source: ${out}`)
+  assert(out.includes('srcset="/x.avif"'), `Missing avif srcset: ${out}`)
+})
+
+test('sources appear before fallback img', () => {
+  const out = picture({
+    src: '/x.jpg', alt: '',
+    sources: [{ src: '/x.webp', type: 'image/webp' }]
+  })
+  assert(out.indexOf('<source') < out.indexOf('<img'), `source must precede img: ${out}`)
+})
+
+test('priority propagates to inner img', () => {
+  const out = picture({ src: '/x.jpg', alt: 'Hero', priority: true, sources: [] })
+  assert(out.includes('fetchpriority="high"'), `Expected high priority in picture: ${out}`)
+})
+
+// ---------------------------------------------------------------------------
+
+console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`)
+if (failed > 0) process.exit(1)