@invisibleloop/pulse 0.1.21

package/src/ui/uiimage.js

@@ -0,0 +1,65 @@
+/**
+ * Pulse UI — Image
+ *
+ * Responsive image with optional aspect-ratio crop, caption, and rounded corners.
+ * Always uses loading="lazy" and decoding="async".
+ *
+ * @param {object}  opts
+ * @param {string}  opts.src      - Image source URL
+ * @param {string}  opts.alt      - Alt text (required for accessibility)
+ * @param {string}  opts.caption  - Optional figcaption text
+ * @param {string}  opts.ratio    - CSS aspect-ratio string e.g. '16/9', '4/3', '1/1'
+ * @param {boolean} opts.rounded  - Larger corner radius (1rem) — for photos, cards, book covers
+ * @param {boolean} opts.pill     - Full pill/stadium radius (999px) — for avatars or circular crops
+ * @param {number|string} opts.width    - img width attribute (browser hint only)
+ * @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
+ */
+
+import { escHtml as e } from '../html.js'
+
+export function uiImage({
+  src        = '',
+  alt        = '',
+  caption    = '',
+  ratio      = '',
+  rounded    = false,
+  pill       = false,
+  width      = '',
+  height     = '',
+  maxWidth   = '',
+  class: cls = '',
+} = {}) {
+  // The outer figure uses display:contents so the inner crop div
+  // becomes a direct flex/block child of whatever container holds it.
+  // This is required for aspect-ratio to resolve correctly in flex contexts.
+  const figClasses = ['ui-image', rounded ? 'ui-image--rounded' : '', pill ? 'ui-image--pill' : '', cls].filter(Boolean).join(' ')
+
+  const maxWidthStyle = maxWidth
+    ? ` 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 captionHtml = caption
+    ? `<figcaption class="ui-image-caption">${e(caption)}</figcaption>`
+    : ''
+
+  if (ratio) {
+    return `<figure class="${e(figClasses)}"${maxWidthStyle}>
+  <div class="ui-image-crop">
+    <img src="${e(src)}" alt="${e(alt)}" class="ui-image-img--cover" style="aspect-ratio:${e(ratio)}"${widthAttr}${heightAttr} loading="lazy" decoding="async">
+  </div>
+  ${captionHtml}
+</figure>`
+  }
+
+  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">
+  </div>
+  ${captionHtml}
+</figure>`
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "noEmit":           true,
+    "strict":           true,
+    "moduleResolution": "node16",
+    "module":           "node16",
+    "target":           "esnext",
+    "lib":              ["esnext", "dom"],
+    "types":            ["node"],
+    "allowJs":          false
+  },
+  "include": ["types/**/*.d.ts"]
+}

package/types/html.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Pulse — HTML escaping types
+ * @invisibleloop/pulse/html
+ */
+
+/**
+ * Escape HTML special characters for safe embedding in HTML attributes or text.
+ *
+ * Always use this around values from user input, URL params, or external APIs.
+ * Omitting it is an XSS vulnerability.
+ *
+ * @example
+ * import { escHtml } from '@invisibleloop/pulse/html'
+ *
+ * view: (state) => `<p>Hello, ${escHtml(state.username)}</p>`
+ */
+export function escHtml(str: unknown): string

package/types/image.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Pulse — Image helper types
+ * @invisibleloop/pulse/image
+ */
+
+export interface ImgOptions {
+  /** Image URL */
+  src:       string
+  /** Alt text (required for accessibility) */
+  alt:       string
+  /** Intrinsic width in px — include to prevent CLS */
+  width?:    number
+  /** Intrinsic height in px — include to prevent CLS */
+  height?:   number
+  /**
+   * Set true for the LCP image (above-the-fold hero).
+   * Adds loading="eager" and fetchpriority="high".
+   */
+  priority?: boolean
+  /** CSS class applied to <img> */
+  class?:    string
+}
+
+export interface PictureSource {
+  /** URL for this format variant */
+  src:  string
+  /** MIME type, e.g. 'image/avif', 'image/webp' */
+  type: string
+}
+
+export interface PictureOptions extends ImgOptions {
+  /**
+   * Modern format sources in preference order (AVIF first, then WebP).
+   * The src on ImgOptions is the universal fallback (JPEG/PNG).
+   *
+   * @example
+   * sources: [
+   *   { src: '/hero.avif', type: 'image/avif' },
+   *   { src: '/hero.webp', type: 'image/webp' },
+   * ]
+   */
+  sources?: PictureSource[]
+}
+
+/**
+ * Generate an optimised <img> tag.
+ * Always include width + height to prevent CLS.
+ * Use priority: true for the LCP image.
+ *
+ * @example
+ * import { img } from '@invisibleloop/pulse/image'
+ * img({ src: '/hero.jpg', alt: 'Hero', width: 1200, height: 600, priority: true })
+ */
+export function img(options: ImgOptions): string
+
+/**
+ * Generate a <picture> element with modern format sources and a fallback <img>.
+ * Provide sources in preference order (AVIF first, then WebP, then the fallback src).
+ *
+ * @example
+ * import { picture } from '@invisibleloop/pulse/image'
+ * picture({
+ *   src: '/hero.jpg', alt: 'Hero', width: 1200, height: 600,
+ *   sources: [
+ *     { src: '/hero.avif', type: 'image/avif' },
+ *     { src: '/hero.webp', type: 'image/webp' },
+ *   ]
+ * })
+ */
+export function picture(options: PictureOptions): string

package/types/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Pulse — root export types
+ * @invisibleloop/pulse
+ *
+ * The root export is the server. Import sub-paths for runtime, SSR, etc.
+ */
+export * from './server.js'

package/types/navigate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Pulse — Client-side navigation types
+ * @invisibleloop/pulse/navigate
+ */
+
+import type { MountResult } from './runtime.js'
+import type { PulseSpec } from './schema.js'
+
+/**
+ * Initialise client-side navigation for a Pulse app.
+ *
+ * Intercepts same-origin <a> clicks and browser back/forward events.
+ * Fetches new pages as JSON fragments (via X-Pulse-Navigate header),
+ * swaps #pulse-root, and re-mounts the new spec without a full page reload.
+ * Falls back to location.href on any fetch or import error.
+ *
+ * Call once after the initial mount().
+ *
+ * @param root    The #pulse-root element
+ * @param mountFn The mount() function from @invisibleloop/pulse/runtime
+ *
+ * @example
+ * import { mount }          from '@invisibleloop/pulse/runtime'
+ * import { initNavigation } from '@invisibleloop/pulse/navigate'
+ *
+ * const root = document.getElementById('pulse-root')
+ * const m = mount(spec, root, window.__PULSE_SERVER__ ?? {}, { ssr: true })
+ * initNavigation(root, mount)
+ */
+export function initNavigation(
+  root:    HTMLElement,
+  mountFn: (
+    spec:        PulseSpec,
+    el:          HTMLElement,
+    serverState?: Record<string, unknown>,
+    options?:    { ssr?: boolean; store?: unknown }
+  ) => MountResult
+): void

package/types/runtime.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Pulse — Client runtime types
+ * @invisibleloop/pulse/runtime
+ */
+
+import type { PulseSpec, PulseStoreDefinition } from './server.js'
+
+export type { PulseSpec } from './schema.js'
+
+// ---------------------------------------------------------------------------
+// mount
+// ---------------------------------------------------------------------------
+
+export interface MountOptions {
+  /**
+   * Set to true when mounting after SSR — skips the initial render and only
+   * binds event listeners. Preserves the SSR-painted LCP element and avoids a
+   * re-render flash. Always true in production bundle boots.
+   */
+  ssr?: boolean
+
+  /**
+   * Store definition (default export from pulse.store.js).
+   * Pass to the first mount() call on a page that uses spec.store.
+   */
+  store?: PulseStoreDefinition
+}
+
+export interface MountResult {
+  /** Destroy this mount, remove event listeners, and unsubscribe from the store. */
+  destroy(): void
+}
+
+/**
+ * Mount a Pulse spec to a DOM element.
+ *
+ * Binds events, applies mutations, enforces constraints, and re-renders the
+ * view on every state change. Call once per page load, then call destroy()
+ * before mounting a new spec during client-side navigation.
+ *
+ * @example
+ * import spec from './src/pages/counter.js'
+ * import { mount } from '@invisibleloop/pulse/runtime'
+ *
+ * const root = document.getElementById('pulse-root')
+ * mount(spec, root, window.__PULSE_SERVER__ ?? {}, { ssr: true })
+ */
+export function mount(
+  spec:        PulseSpec,
+  el:          HTMLElement,
+  serverState?: Record<string, unknown>,
+  options?:    MountOptions
+): MountResult
+
+// ---------------------------------------------------------------------------
+// Utility exports
+// ---------------------------------------------------------------------------
+
+/** Debounce a function — returns a new function that delays invocation. */
+export function debounce<T extends (...args: unknown[]) => unknown>(fn: T, ms: number): T
+
+/** Throttle a function — returns a new function that limits invocation rate. */
+export function throttle<T extends (...args: unknown[]) => unknown>(fn: T, ms: number): T

package/types/schema.d.ts

@@ -0,0 +1,243 @@
+/// <reference types="node" />
+
+/**
+ * Pulse — Core types
+ * Shared across server, runtime, and SSR.
+ */
+
+// ---------------------------------------------------------------------------
+// Request context
+// ---------------------------------------------------------------------------
+
+export interface RequestContext {
+  /** Route params extracted from the URL pattern, e.g. { id: '42' } */
+  params:   Record<string, string>
+  /** Parsed query string, e.g. { q: 'widget' } */
+  query:    Record<string, string>
+  /** Raw request headers */
+  headers:  Record<string, string | string[] | undefined>
+  /** URL pathname */
+  pathname: string
+  /** HTTP method */
+  method:   string
+  /** CSP nonce generated per request — pass to inline <script nonce="…"> */
+  nonce:    string
+  /** Parsed cookies from the request Cookie header */
+  cookies:  Record<string, string>
+  /** Brand config resolved by resolveBrand (undefined if not configured) */
+  brand?:   unknown
+  /** Global store state for keys declared in spec.store */
+  store?:   Record<string, unknown>
+  /** Active fetcher timeout in ms (null = no limit) */
+  fetcherTimeout: number | null
+
+  /** Parse a JSON request body. Returns null for an empty body. */
+  json():     Promise<Record<string, unknown> | null>
+  /** Read the body as a plain string. */
+  text():     Promise<string>
+  /** Parse a URL-encoded body into a plain object. Returns null for empty. */
+  formData(): Promise<Record<string, string> | null>
+  /** Read the raw body as a Node.js Buffer. */
+  buffer():   Promise<Buffer>
+
+  /**
+   * Queue a Set-Cookie header on the response.
+   * Defaults: Path=/, SameSite=Lax.
+   */
+  setCookie(
+    name:  string,
+    value: string,
+    opts?: {
+      httpOnly?: boolean
+      secure?:   boolean
+      path?:     string
+      maxAge?:   number
+      sameSite?: 'Strict' | 'Lax' | 'None'
+      domain?:   string
+    }
+  ): void
+
+  /** Queue an arbitrary response header. */
+  setHeader(name: string, value: string): void
+}
+
+// ---------------------------------------------------------------------------
+// Guard return value
+// ---------------------------------------------------------------------------
+
+export type GuardResult =
+  | { redirect: string }
+  | { status: number; json?: unknown; body?: string; headers?: Record<string, string> }
+
+// ---------------------------------------------------------------------------
+// Spec sub-types
+// ---------------------------------------------------------------------------
+
+export interface ValidationRule {
+  required?:  boolean
+  minLength?: number
+  maxLength?: number
+  min?:       number
+  max?:       number
+  format?:    'email' | 'url' | 'numeric'
+  pattern?:   RegExp
+}
+
+export interface StreamConfig {
+  /** Segment keys rendered in the first flush */
+  shell:     string[]
+  /** Segment keys rendered after their async data resolves */
+  deferred?: string[]
+}
+
+export interface ActionConfig<S extends object = Record<string, unknown>> {
+  /** Run validation (spec.validation) before executing. Default false. */
+  validate?:  boolean
+  /** Called before run() — optimistic update */
+  onStart?:   (state: S, payload?: unknown) => Partial<S>
+  /** Async operation. Return value is passed to onSuccess. */
+  run:        (state: S, server?: unknown, payload?: unknown) => Promise<unknown>
+  /** Called on success. Return partial state to merge. */
+  onSuccess:  (state: S, payload: unknown) => Partial<S> & { _toast?: ToastOptions; _storeUpdate?: Record<string, unknown> }
+  /** Called on error. Return partial state to merge. */
+  onError:    (state: S, err: Error) => Partial<S> & { _toast?: ToastOptions }
+}
+
+export interface ToastOptions {
+  message:   string
+  variant?:  'success' | 'error' | 'warning' | 'info'
+  duration?: number
+}
+
+export interface CacheConfig {
+  public?:              boolean
+  maxAge?:              number
+  staleWhileRevalidate?: number
+}
+
+export interface MetaConfig {
+  title?:       string | ((ctx: RequestContext) => string)
+  description?: string | ((ctx: RequestContext) => string)
+  styles?:      string[] | ((ctx: RequestContext) => string[])
+  ogTitle?:     string | ((ctx: RequestContext) => string)
+  ogImage?:     string | ((ctx: RequestContext) => string)
+  schema?:      Record<string, unknown>
+  theme?:       'light' | 'dark'
+  [key: string]: unknown
+}
+
+// ---------------------------------------------------------------------------
+// PulseSpec
+// ---------------------------------------------------------------------------
+
+export interface PulseSpec<S extends object = Record<string, unknown>> {
+  /** URL pattern. Supports :param segments. */
+  route: string
+
+  /**
+   * Initial client-side state. Deep-cloned on mount.
+   * Required for page specs; omit only for raw content specs (contentType set).
+   */
+  state: S
+
+  /**
+   * Pure function returning an HTML string.
+   * Receives (clientState, serverState).
+   * Can also be a keyed object of segment functions for streaming SSR.
+   */
+  view:
+    | ((state: S, server?: Record<string, unknown>) => string)
+    | Record<string, (state: S, server?: Record<string, unknown>) => string>
+
+  /**
+   * Browser-importable path to this spec file.
+   * Required for any spec with mutations, actions, or persist.
+   */
+  hydrate?: string
+
+  /** Streaming SSR config — split view into shell and deferred segments. */
+  stream?: StreamConfig
+
+  /** Server-side data fetchers. Results passed as second arg to view. */
+  server?: Record<string, (ctx: RequestContext) => Promise<unknown> | unknown>
+
+  /**
+   * Raw content spec — set Content-Type and implement render() instead of view().
+   * Accepts any HTTP method. Use for RSS feeds, JSON APIs, sitemaps, webhooks.
+   */
+  contentType?: string
+
+  /**
+   * Required when contentType is set.
+   * Receives (ctx, server) and returns the raw response body string.
+   */
+  render?: (ctx: RequestContext, server?: Record<string, unknown>) => Promise<string> | string
+
+  /** Page metadata for the <head>. Fields may be functions for per-request resolution. */
+  meta?: MetaConfig
+
+  /** Synchronous state updaters. Each returns a partial state to merge. */
+  mutations?: Record<string, (state: S, event?: Event | unknown) => Partial<S>>
+
+  /** Async operations with full lifecycle hooks. */
+  actions?: Record<string, ActionConfig<S>>
+
+  /** Declarative validation rules keyed by dot-path state keys. */
+  validation?: Record<string, ValidationRule>
+
+  /** Min/max bounds clamped after every mutation. Cannot be bypassed. */
+  constraints?: Record<string, { min?: number; max?: number }>
+
+  /** State keys to persist in localStorage between visits. */
+  persist?: string[]
+
+  /** Global store keys this page subscribes to. Appear in view's server arg. */
+  store?: string[]
+
+  /** HTTP methods this page accepts. Default ['GET', 'HEAD']. */
+  methods?: Array<'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS'>
+
+  /**
+   * Called before server data fetchers on every request.
+   * Return { redirect } to redirect, { status, json } for a custom response,
+   * or nothing to allow the request to proceed.
+   */
+  guard?: (ctx: RequestContext) => Promise<GuardResult | void> | GuardResult | void
+
+  /** HTTP Cache-Control header config for the page response. */
+  cache?: CacheConfig
+
+  /** Seconds to cache server.data() result in-process. */
+  serverTtl?: number
+
+  /** Timeout in ms for all server fetchers on this page. Overrides createServer fetcherTimeout. */
+  serverTimeout?: number
+
+  /**
+   * Fallback renderer called when view() throws at runtime.
+   * Return an HTML string to display instead of the default error message.
+   * On the server, if not defined, view errors propagate to the 500 handler.
+   */
+  onViewError?: (err: Error, state: S, server?: Record<string, unknown>) => string
+}
+
+// ---------------------------------------------------------------------------
+// Validation utilities
+// ---------------------------------------------------------------------------
+
+export interface ValidationResult {
+  valid:  boolean
+  errors: string[]
+}
+
+/** Validate a spec. Returns { valid, errors }. Does not throw. */
+export function validateSpec(spec: unknown): ValidationResult
+
+/** Validate a spec. Throws with all errors if invalid. */
+export function assertValidSpec(spec: unknown): void
+
+/** Returns the segment keys defined in spec.view. ['default'] for a function view. */
+export function getViewSegments(spec: PulseSpec): string[]
+
+/** Returns { shell, deferred } stream order. All segments in shell if no stream config. */
+export function getStreamOrder(spec: PulseSpec): { shell: string[]; deferred: string[] }

package/types/server.d.ts

@@ -0,0 +1,145 @@
+/// <reference types="node" />
+
+/**
+ * Pulse — Server API types
+ * @invisibleloop/pulse  or  @invisibleloop/pulse/server
+ */
+
+import type { IncomingMessage, ServerResponse, Server } from 'http'
+import type { PulseSpec } from './schema.js'
+
+export type { PulseSpec, RequestContext, ValidationRule, StreamConfig, ActionConfig,
+             GuardResult, CacheConfig, MetaConfig, ToastOptions, ValidationResult } from './schema.js'
+
+// ---------------------------------------------------------------------------
+// createServer options
+// ---------------------------------------------------------------------------
+
+export interface ServerOptions {
+  /** Port to listen on. Default 3000. */
+  port?: number
+
+  /** Enable streaming SSR globally. Default true. */
+  stream?: boolean
+
+  /** Path to a directory of static files served at their relative path. */
+  staticDir?: string
+
+  /** Explicit manifest path or object. Overrides auto-detection from staticDir/dist/manifest.json. */
+  manifest?: string | Record<string, string> | null
+
+  /**
+   * Trailing slash behaviour. Default 'remove'.
+   * 'remove' — 301 /about/ → /about
+   * 'add'    — 301 /about  → /about/
+   * 'allow'  — serve both, no redirect
+   */
+  trailingSlash?: 'remove' | 'add' | 'allow'
+
+  /** Maximum request body size in bytes. Default 1 MB. Requests exceeding this receive a 413. */
+  maxBody?: number
+
+  /**
+   * Default HTML cache TTL for all pages in production.
+   * true = 1 h + 24 h SWR, number = max-age in seconds,
+   * object = { public, maxAge, staleWhileRevalidate }.
+   * spec.cache overrides per page.
+   */
+  defaultCache?: boolean | number | { public?: boolean; maxAge?: number; staleWhileRevalidate?: number } | null
+
+  /** Global timeout in ms for all server fetchers. null = no limit. Override per page with spec.serverTimeout. */
+  fetcherTimeout?: number | null
+
+  /**
+   * Multi-brand support. Called once per host (cached 60 s).
+   * Result is attached to ctx.brand and available in guard, server, and meta functions.
+   */
+  resolveBrand?: (host: string) => Promise<unknown> | unknown
+
+  /**
+   * Milliseconds to wait for in-flight requests to complete during graceful
+   * shutdown before force-exiting. Default 30 000 ms.
+   */
+  shutdownTimeout?: number
+
+  /**
+   * Path for the built-in health check endpoint. Default '/healthz'.
+   * Returns { status: 'ok', uptime: number } — bypasses onRequest so load
+   * balancers always get a response. Set to false to disable.
+   */
+  healthCheck?: string | false
+
+  /** Called on every request before routing. Return false to short-circuit Pulse handling. */
+  onRequest?: (req: IncomingMessage, res: ServerResponse) => false | void | unknown
+
+  /**
+   * Extra CSP sources to merge into the framework's default Content-Security-Policy.
+   * Use this to allow external stylesheets, fonts, or API origins.
+   * Each key is a CSP directive name; each value is an array of sources to append.
+   * @example
+   * // Allow Google Fonts
+   * csp: { 'style-src': ['https://fonts.googleapis.com'], 'font-src': ['https://fonts.gstatic.com'] }
+   */
+  csp?: Record<string, string[]>
+
+  /** Called on unhandled errors. Receives (err, req, res). */
+  onError?: (err: Error, req: IncomingMessage, res: ServerResponse) => void
+
+  /** Global store definition (default export from pulse.store.js). */
+  store?: PulseStoreDefinition | null
+}
+
+// ---------------------------------------------------------------------------
+// Store (used via server options)
+// ---------------------------------------------------------------------------
+
+export interface PulseStoreDefinition {
+  hydrate?:   string
+  state:      Record<string, unknown>
+  server?:    Record<string, (ctx: import('./schema.js').RequestContext) => Promise<unknown> | unknown>
+  mutations?: Record<string, (state: Record<string, unknown>, payload?: unknown) => Partial<Record<string, unknown>>>
+}
+
+// ---------------------------------------------------------------------------
+// createServer return value
+// ---------------------------------------------------------------------------
+
+export interface ServerInstance {
+  /** The underlying Node.js http.Server */
+  server: Server
+
+  /**
+   * Gracefully shut down the server.
+   * Stops accepting new connections, destroys idle keep-alive sockets, lets
+   * in-flight requests finish, then force-exits after shutdownTimeout ms.
+   * SIGTERM and SIGINT are already wired up automatically.
+   * Idempotent — safe to call multiple times.
+   */
+  shutdown(): void
+
+  /** Swap the spec list at runtime (used by the dev server for hot reload). */
+  updateSpecs(specs: PulseSpec[]): void
+}
+
+// ---------------------------------------------------------------------------
+// createServer
+// ---------------------------------------------------------------------------
+
+/**
+ * Create and start a Pulse HTTP server.
+ *
+ * All specs are validated at startup — an invalid spec throws before the
+ * server accepts any connections.
+ *
+ * @example
+ * import { createServer } from '@invisibleloop/pulse'
+ * import home    from './src/pages/home.js'
+ * import contact from './src/pages/contact.js'
+ *
+ * const { server, shutdown } = createServer([home, contact], {
+ *   port:      3000,
+ *   stream:    true,
+ *   staticDir: 'public',
+ * })
+ */
+export function createServer(specs: PulseSpec[], options?: ServerOptions): ServerInstance