@invisibleloop/pulse 0.1.21

package/src/runtime/ssr.test.js

@@ -0,0 +1,421 @@
+/**
+ * Pulse — SSR renderer tests
+ * run: node src/runtime/ssr.test.js
+ */
+
+import { renderToString, renderToStream, wrapDocument, withTimeout } from './ssr.js'
+
+// ---------------------------------------------------------------------------
+// Test runner
+// ---------------------------------------------------------------------------
+
+let passed = 0
+let failed = 0
+
+async function test(label, fn) {
+  try {
+    await 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')
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function streamToString(stream) {
+  const reader = stream.getReader()
+  const decoder = new TextDecoder()
+  let result = ''
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    result += decoder.decode(value)
+  }
+  return result
+}
+
+// ---------------------------------------------------------------------------
+// Specs used across tests
+// ---------------------------------------------------------------------------
+
+const helloSpec = {
+  route: '/hello',
+  state: {},
+  view:  () => '<h1>Hello world</h1>'
+}
+
+const counterSpec = {
+  route: '/counter',
+  state: { count: 5 },
+  view:  (state) => `<span id="count">${state.count}</span>`
+}
+
+const serverDataSpec = {
+  route: '/products',
+  state: {},
+  server: {
+    products: async (ctx) => [
+      { id: 1, name: 'Widget' },
+      { id: 2, name: 'Gadget' }
+    ]
+  },
+  view: (state, server) =>
+    `<ul>${server.products.map(p => `<li>${p.name}</li>`).join('')}</ul>`
+}
+
+const streamSpec = {
+  route: '/stream',
+  stream: {
+    shell:    ['header', 'nav'],
+    deferred: ['feed']
+  },
+  server: {
+    feed: async () => {
+      // Simulate async data
+      await new Promise(r => setTimeout(r, 10))
+      return [{ title: 'Post 1' }, { title: 'Post 2' }]
+    }
+  },
+  state: {},
+  view: {
+    header: ()             => '<header>Pulse</header>',
+    nav:    ()             => '<nav>Home</nav>',
+    feed:   (s, server)    => `<main>${server.feed.map(p => `<h2>${p.title}</h2>`).join('')}</main>`
+  }
+}
+
+const metaSpec = {
+  route: '/about',
+  state: {},
+  view:  () => '<p>About</p>',
+  meta: {
+    title:       'About Us',
+    description: 'Learn more about us',
+    ogTitle:     'About Us — Pulse'
+  }
+}
+
+// ---------------------------------------------------------------------------
+
+console.log('\nrenderToString\n')
+
+await test('renders simple function view', async () => {
+  const { html } = await renderToString(helloSpec)
+  assert(html.includes('<h1>Hello world</h1>'), `Got: ${html}`)
+})
+
+await test('renders initial client state into view', async () => {
+  const { html } = await renderToString(counterSpec)
+  assert(html.includes('>5<'), `Expected count 5, got: ${html}`)
+})
+
+await test('resolves server data and passes to view', async () => {
+  const { html } = await renderToString(serverDataSpec)
+  assert(html.includes('<li>Widget</li>'), `Expected Widget, got: ${html}`)
+  assert(html.includes('<li>Gadget</li>'), `Expected Gadget, got: ${html}`)
+})
+
+await test('passes ctx to server data fetchers', async () => {
+  const spec = {
+    route: '/user',
+    state: {},
+    server: {
+      greeting: async (ctx) => `Hello ${ctx.user}`
+    },
+    view: (s, server) => `<p>${server.greeting}</p>`
+  }
+  const { html } = await renderToString(spec, { user: 'Andy' })
+  assert(html.includes('Hello Andy'), `Got: ${html}`)
+})
+
+await test('returns serverState from resolved fetchers', async () => {
+  const { serverState } = await renderToString(serverDataSpec)
+  assert(Array.isArray(serverState.products), 'Expected products array')
+  assert(serverState.products.length === 2, `Expected 2 products, got ${serverState.products.length}`)
+})
+
+await test('returns timing object', async () => {
+  const { timing } = await renderToString(helloSpec)
+  assert(typeof timing.data   === 'number', 'timing.data should be a number')
+  assert(typeof timing.render === 'number', 'timing.render should be a number')
+  assert(typeof timing.total  === 'number', 'timing.total should be a number')
+  assert(timing.total >= 0, 'timing.total should be non-negative')
+})
+
+await test('resolves multiple server fetchers in parallel', async () => {
+  const spec = {
+    route: '/multi',
+    state: {},
+    server: {
+      a: async () => { await new Promise(r => setTimeout(r, 20)); return 'A' },
+      b: async () => { await new Promise(r => setTimeout(r, 20)); return 'B' }
+    },
+    view: (s, server) => `${server.a}${server.b}`
+  }
+
+  const t0 = Date.now()
+  const { html } = await renderToString(spec)
+  const elapsed = Date.now() - t0
+
+  assert(html === 'AB', `Got: ${html}`)
+  // Parallel: should be ~20ms, not ~40ms
+  assert(elapsed < 35, `Expected parallel resolution ~20ms, took ${elapsed}ms`)
+})
+
+await test('renders segmented view in order', async () => {
+  const spec = {
+    route: '/seg',
+    state: {},
+    view: {
+      header: () => '<header/>',
+      body:   () => '<main/>',
+      footer: () => '<footer/>'
+    }
+  }
+  const { html } = await renderToString(spec)
+  const headerPos = html.indexOf('<header/>')
+  const bodyPos   = html.indexOf('<main/>')
+  const footerPos = html.indexOf('<footer/>')
+  assert(headerPos < bodyPos,   'header should come before body')
+  assert(bodyPos   < footerPos, 'body should come before footer')
+})
+
+await test('throws on invalid spec', async () => {
+  let threw = false
+  try { await renderToString({ route: '/bad' }) } catch { threw = true }
+  assert(threw, 'Expected renderToString to throw on invalid spec')
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nrenderToStream\n')
+
+await test('streams shell segments immediately', async () => {
+  const html = await streamToString(renderToStream(streamSpec))
+  assert(html.includes('<header>Pulse</header>'), `Shell header missing: ${html}`)
+  assert(html.includes('<nav>Home</nav>'),         `Shell nav missing: ${html}`)
+})
+
+await test('streams deferred content after shell', async () => {
+  const html = await streamToString(renderToStream(streamSpec))
+  assert(html.includes('Post 1'), `Deferred feed missing Post 1: ${html}`)
+  assert(html.includes('Post 2'), `Deferred feed missing Post 2: ${html}`)
+})
+
+await test('deferred content comes after shell in stream order', async () => {
+  const html = await streamToString(renderToStream(streamSpec))
+  const shellPos    = html.indexOf('<header>')
+  const deferredPos = html.indexOf('Post 1')
+  assert(shellPos < deferredPos, 'Shell should appear before deferred content')
+})
+
+await test('includes placeholder for deferred segment', async () => {
+  const html = await streamToString(renderToStream(streamSpec))
+  assert(html.includes('pulse-deferred'), `Expected pulse-deferred placeholder: ${html}`)
+})
+
+await test('includes replacement script for deferred segment', async () => {
+  const html = await streamToString(renderToStream(streamSpec))
+  assert(html.includes('replaceWith'), `Expected inline replacement script: ${html}`)
+})
+
+await test('streams simple function view', async () => {
+  const html = await streamToString(renderToStream(helloSpec))
+  assert(html.includes('<h1>Hello world</h1>'), `Got: ${html}`)
+})
+
+await test('stream injects __PULSE_SERVER__ when spec has server data', async () => {
+  const html = await streamToString(renderToStream(serverDataSpec))
+  assert(html.includes('__PULSE_SERVER__'), `Expected server state script: ${html}`)
+  assert(html.includes('"Widget"'), `Expected serialised server data: ${html}`)
+})
+
+await test('stream does not inject __PULSE_SERVER__ when no server data', async () => {
+  const html = await streamToString(renderToStream(helloSpec))
+  assert(!html.includes('__PULSE_SERVER__'), `Should not include empty server state: ${html}`)
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nwrapDocument\n')
+
+await test('wraps content in full HTML document', async () => {
+  const { html } = wrapDocument({ content: '<p>Hello</p>' })
+  assert(html.includes('<!DOCTYPE html>'), 'Missing DOCTYPE')
+  assert(html.includes('<p>Hello</p>'), 'Missing content')
+  assert(html.includes('</html>'), 'Missing closing tag')
+})
+
+await test('sets title from spec.meta', async () => {
+  const { html } = wrapDocument({ content: '', spec: metaSpec })
+  assert(html.includes('<title>About Us</title>'), `Got: ${html}`)
+})
+
+await test('sets description meta tag', async () => {
+  const { html } = wrapDocument({ content: '', spec: metaSpec })
+  assert(html.includes('name="description"'), `Got: ${html}`)
+  assert(html.includes('Learn more about us'), `Got: ${html}`)
+})
+
+await test('sets og:title meta tag', async () => {
+  const { html } = wrapDocument({ content: '', spec: metaSpec })
+  assert(html.includes('og:title'), `Got: ${html}`)
+})
+
+await test('serialises server state into page', async () => {
+  const { html } = wrapDocument({
+    content:     '',
+    serverState: { products: [{ id: 1 }] }
+  })
+  assert(html.includes('__PULSE_SERVER__'), `Expected server state script: ${html}`)
+  assert(html.includes('"id":1'), `Expected serialised data: ${html}`)
+})
+
+await test('omits server state script when empty', async () => {
+  const { html } = wrapDocument({ content: '' })
+  assert(!html.includes('__PULSE_SERVER__'), 'Should not include empty server state script')
+})
+
+await test('returns serverTimingValue when timing provided', async () => {
+  const { serverTimingValue } = wrapDocument({
+    content: '',
+    timing: { data: 5.2, render: 1.1, total: 6.3 }
+  })
+  assert(serverTimingValue !== null, 'Expected timing value')
+  assert(serverTimingValue.includes('total'), `Got: ${serverTimingValue}`)
+})
+
+await test('escapes special characters in title', async () => {
+  const { html } = wrapDocument({
+    content: '',
+    spec: { meta: { title: '<script>bad</script>' } }
+  })
+  assert(!html.includes('<script>bad'), `Title should be escaped: ${html}`)
+  assert(html.includes('&lt;script&gt;'), `Expected escaped title: ${html}`)
+})
+
+await test('includes hydration script when spec.hydrate is set', async () => {
+  const { html } = wrapDocument({
+    content: '',
+    spec: { hydrate: '/examples/counter.js' }
+  })
+  assert(html.includes('type="module"'),       `Expected module script: ${html}`)
+  assert(html.includes('/examples/counter.js'), `Expected spec path: ${html}`)
+  assert(html.includes('/@pulse/runtime/index.js'), `Expected runtime path: ${html}`)
+  assert(html.includes('mount('),              `Expected mount() call: ${html}`)
+})
+
+await test('uses external script tag for bundle hydrate paths', async () => {
+  const { html } = wrapDocument({
+    content: '',
+    spec: { hydrate: '/dist/counter.boot-ABC123.js' }
+  })
+  assert(html.includes('type="module" src="/dist/counter.boot-ABC123.js"'), `Expected external script: ${html}`)
+  assert(!html.includes('import spec from'), `Should not include inline import: ${html}`)
+})
+
+await test('omits hydration script when spec.hydrate is not set', async () => {
+  const { html } = wrapDocument({ content: '' })
+  assert(!html.includes("import spec from"), `Should not include import: ${html}`)
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nError boundaries (SSR)\n')
+
+await test('renderToString: rethrows when view throws and no onViewError — server handles it', async () => {
+  const spec = {
+    route: '/err',
+    state: {},
+    view: () => { throw new Error('ssr boom') }
+  }
+  let threw = false
+  try { await renderToString(spec) } catch (e) {
+    threw = true
+    assert(e.message === 'ssr boom', `Expected original error, got: ${e.message}`)
+  }
+  assert(threw, 'Expected renderToString to rethrow when no onViewError is defined')
+})
+
+await test('renderToString: calls spec.onViewError and returns fallback when view throws', async () => {
+  const spec = {
+    route: '/err',
+    state: { val: 99 },
+    view: () => { throw new Error('ssr oops') },
+    onViewError: (err, state) => `<p data-testid="fallback">${err.message}:${state.val}</p>`
+  }
+  const { html } = await renderToString(spec)
+  assert(html.includes('data-testid="fallback"'), `Expected custom fallback, got: ${html}`)
+  assert(html.includes('ssr oops:99'), `Expected err + state in fallback, got: ${html}`)
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nRequest timeouts\n')
+
+await test('withTimeout: resolves normally when promise completes in time', async () => {
+  const result = await withTimeout(Promise.resolve('ok'), 100, 'test')
+  assert(result === 'ok', `Expected "ok", got "${result}"`)
+})
+
+await test('withTimeout: rejects with timeout error when promise is too slow', async () => {
+  const slow = new Promise(r => setTimeout(r, 200))
+  let err
+  try { await withTimeout(slow, 30, 'myFetcher') } catch (e) { err = e }
+  assert(err?.message?.includes('myFetcher'), `Expected fetcher name in error: ${err?.message}`)
+  assert(err?.message?.includes('30ms'),      `Expected timeout duration in error: ${err?.message}`)
+})
+
+await test('withTimeout: no-op when ms is null', async () => {
+  const result = await withTimeout(Promise.resolve(42), null, 'test')
+  assert(result === 42, `Expected 42, got ${result}`)
+})
+
+await test('withTimeout: no-op when ms is 0', async () => {
+  const result = await withTimeout(Promise.resolve(42), 0, 'test')
+  assert(result === 42, `Expected 42, got ${result}`)
+})
+
+await test('renderToString: ctx.fetcherTimeout is applied to server fetchers', async () => {
+  const spec = {
+    route: '/slow',
+    state: {},
+    server: {
+      data: () => new Promise(r => setTimeout(() => r('done'), 200))
+    },
+    view: (state, server) => `<p>${server.data}</p>`
+  }
+  let err
+  try {
+    await renderToString(spec, { fetcherTimeout: 30 })
+  } catch (e) { err = e }
+  assert(err?.message?.includes('timed out'), `Expected timeout error, got: ${err?.message}`)
+})
+
+await test('renderToString: resolves normally when fetcher completes within timeout', async () => {
+  const spec = {
+    route: '/fast',
+    state: {},
+    server: {
+      data: () => Promise.resolve('quick')
+    },
+    view: (state, server) => `<p>${server.data}</p>`
+  }
+  const { html } = await renderToString(spec, { fetcherTimeout: 500 })
+  assert(html.includes('quick'), `Expected rendered data, got: ${html}`)
+})
+
+// ---------------------------------------------------------------------------
+
+console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`)
+if (failed > 0) process.exit(1)

package/src/runtime/store.js

@@ -0,0 +1,92 @@
+/**
+ * Pulse — Client Store Singleton
+ *
+ * A module-level singleton that holds global store state on the client.
+ * Pages that declare spec.store subscribe to this and re-render when it changes.
+ *
+ * Initialised once from window.__PULSE_STORE__ (serialised by the server).
+ * Subsequent calls to initClientStore are no-ops — the store persists across
+ * client-side navigations so store actions on one page are visible on the next.
+ *
+ * Browser-only — never imported by the SSR path.
+ */
+
+let _state = {}
+let _initialized = false
+let _mutations = {}
+let _mutationsRegistered = false
+const _subs = new Set()
+
+/**
+ * Seed the store from SSR data.
+ * No-op after the first call — navigations do not reset the store.
+ *
+ * @param {Object} initialState
+ */
+export function initClientStore(initialState) {
+  if (_initialized) return
+  _state = { ...(initialState || {}) }
+  _initialized = true
+}
+
+/**
+ * Return the current store state.
+ * @returns {Object}
+ */
+export function getStoreState() {
+  return _state
+}
+
+/**
+ * Subscribe to store changes.
+ * The callback receives the new store state on every update.
+ * Returns an unsubscribe function — call it in destroy() to prevent leaks.
+ *
+ * @param {function} fn
+ * @returns {function} unsubscribe
+ */
+export function subscribe(fn) {
+  _subs.add(fn)
+  return () => _subs.delete(fn)
+}
+
+/**
+ * Merge a partial object into the store and notify all subscribers.
+ * Called by the runtime when a page action returns { _storeUpdate: {...} }.
+ *
+ * @param {Object} partial
+ */
+export function updateStore(partial) {
+  _state = { ..._state, ...partial }
+  for (const fn of _subs) fn(_state)
+}
+
+/**
+ * Register store mutations from the store definition.
+ * No-op after the first call — navigations do not re-register mutations.
+ *
+ * @param {Object} mutations
+ */
+export function registerStoreMutations(mutations) {
+  if (_mutationsRegistered) return
+  _mutations = mutations || {}
+  _mutationsRegistered = true
+}
+
+/**
+ * Dispatch a store mutation by name.
+ * The mutation receives the current store state and an optional payload,
+ * and returns a partial store object merged via updateStore.
+ * All subscribed pages re-render automatically.
+ *
+ * @param {string} name
+ * @param {*} [payload]
+ */
+export function dispatchStoreMutation(name, payload) {
+  const fn = _mutations[name]
+  if (!fn) {
+    console.warn(`[Pulse] No store mutation found for "${name}"`)
+    return
+  }
+  updateStore(fn(_state, payload))
+}

package/src/runtime/toast.js

@@ -0,0 +1,163 @@
+/**
+ * Pulse — Toast / notification system
+ *
+ * Triggered by returning `_toast` from any action lifecycle hook or mutation.
+ * The container is injected into document.body once and survives page navigations.
+ *
+ * Usage:
+ *   onSuccess: (state, result) => ({
+ *     saved: true,
+ *     _toast: { message: 'Saved!', variant: 'success' }
+ *   })
+ *
+ * _toast options:
+ *   message  {string}                              — required
+ *   variant  {'success'|'error'|'warning'|'info'}  — default 'info'
+ *   duration {number}                              — ms before auto-dismiss, default 4000. 0 = no auto-dismiss.
+ */
+
+const CONTAINER_ID = 'pulse-toasts'
+const MAX_TOASTS   = 5
+const VARIANTS     = new Set(['success', 'error', 'warning', 'info'])
+
+// ---------------------------------------------------------------------------
+// CSS — injected once, overridable via .pulse-toast classes in app CSS
+// ---------------------------------------------------------------------------
+
+const TOAST_CSS = `
+#pulse-toasts {
+  position: fixed;
+  top: 1rem;
+  right: 1rem;
+  z-index: 9999;
+  display: flex;
+  flex-direction: column;
+  gap: .5rem;
+  pointer-events: none;
+  max-width: min(24rem, calc(100vw - 2rem));
+}
+.pulse-toast {
+  display: flex;
+  align-items: flex-start;
+  gap: .75rem;
+  padding: .75rem 1rem;
+  border-radius: .5rem;
+  box-shadow: 0 4px 16px rgba(0,0,0,.2);
+  font-size: .875rem;
+  line-height: 1.4;
+  pointer-events: all;
+  opacity: 0;
+  transform: translateX(calc(100% + 1.5rem));
+  transition: opacity .2s ease, transform .2s ease;
+  background: #1e293b;
+  color: #f8fafc;
+}
+.pulse-toast--visible {
+  opacity: 1;
+  transform: translateX(0);
+}
+.pulse-toast--success { background: #166534; }
+.pulse-toast--error   { background: #991b1b; }
+.pulse-toast--warning { background: #92400e; }
+.pulse-toast-message  { flex: 1; }
+.pulse-toast-close {
+  background: none;
+  border: none;
+  color: inherit;
+  cursor: pointer;
+  padding: 0 0 0 .25rem;
+  font-size: 1.125rem;
+  line-height: 1;
+  opacity: .7;
+  flex-shrink: 0;
+}
+.pulse-toast-close:hover { opacity: 1; }
+`
+
+let _stylesInjected = false
+
+function injectStyles() {
+  if (_stylesInjected) return
+  _stylesInjected = true
+  const style = document.createElement('style')
+  style.textContent = TOAST_CSS
+  document.head.appendChild(style)
+}
+
+// ---------------------------------------------------------------------------
+// Container
+// ---------------------------------------------------------------------------
+
+function getContainer() {
+  let container = document.getElementById(CONTAINER_ID)
+  if (!container) {
+    injectStyles()
+    container = document.createElement('div')
+    container.id = CONTAINER_ID
+    container.setAttribute('aria-live', 'polite')
+    container.setAttribute('aria-atomic', 'false')
+    document.body.appendChild(container)
+  }
+  return container
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Show a toast notification.
+ *
+ * @param {Object|string} options
+ * @param {string}  options.message
+ * @param {'success'|'error'|'warning'|'info'} [options.variant='info']
+ * @param {number}  [options.duration=4000]  ms before auto-dismiss; 0 = sticky
+ */
+export function showToast(options) {
+  if (typeof document === 'undefined') return  // no-op in SSR/test environments
+
+  const { message, variant = 'info', duration = 4000 } =
+    typeof options === 'string' ? { message: options } : options
+
+  if (!message) return
+
+  const safeVariant = VARIANTS.has(variant) ? variant : 'info'
+  const container   = getContainer()
+
+  // Evict oldest toast if at the limit
+  while (container.children.length >= MAX_TOASTS) {
+    container.firstElementChild?.remove()
+  }
+
+  // Build toast element
+  const toast   = document.createElement('div')
+  toast.className = `pulse-toast pulse-toast--${safeVariant}`
+  toast.setAttribute('role', 'status')
+
+  const msg = document.createElement('span')
+  msg.className   = 'pulse-toast-message'
+  msg.textContent = message  // safe — textContent, no innerHTML
+
+  const close = document.createElement('button')
+  close.className  = 'pulse-toast-close'
+  close.setAttribute('aria-label', 'Dismiss notification')
+  close.textContent = '×'
+  close.addEventListener('click', () => dismiss(toast))
+
+  toast.appendChild(msg)
+  toast.appendChild(close)
+  container.appendChild(toast)
+
+  // Animate in on next frame
+  requestAnimationFrame(() => toast.classList.add('pulse-toast--visible'))
+
+  // Auto-dismiss
+  if (duration > 0) {
+    setTimeout(() => dismiss(toast), duration)
+  }
+}
+
+function dismiss(toast) {
+  toast.classList.remove('pulse-toast--visible')
+  toast.addEventListener('transitionend', () => toast.remove(), { once: true })
+}