@invisibleloop/pulse 0.1.21

package/docs/public/dist/server-api.boot-K7X3LCFB.js

@@ -0,0 +1,219 @@
+import{a as t}from"./runtime-QFURDKA2.js";import{a as n,b as i,c as l,d as p,e,g as o,h as r,i as s}from"./runtime-L2HNXIHW.js";import{a,b as u}from"./runtime-B73WLANC.js";var{prev:h,next:m}=n("/server-api"),d={route:"/server-api",meta:{title:"Server API \u2014 Pulse Docs",description:"Complete reference for createServer \u2014 all options, hooks, and response behaviour.",styles:["/docs.css"]},state:{},view:()=>i({currentHref:"/server-api",prev:h,next:m,content:`
+      ${l("Server API")}
+      ${p("<code>createServer(specs, options)</code> starts an HTTP server with all guarantees active. Specs are validated before the server accepts connections. SSR, streaming, brotli compression, immutable asset caching, security headers, CSP nonces, and HSTS are all handled automatically.")}
+
+      ${e("signature","createServer(specs, options)")}
+      ${o(t(`import { createServer } from '@invisibleloop/pulse'
+
+createServer(specs, options)`,"js"))}
+      ${r(["Parameter","Type","Description"],[["<code>specs</code>","<code>Spec[]</code>","Array of page spec objects. Validated at startup \u2014 a bad spec throws before the server accepts connections."],["<code>options</code>","<code>object</code>","Server configuration options (see below)."]])}
+
+      ${e("options","Options")}
+      ${r(["Option","Type","Default","Description"],[["<code>port</code>","<code>number</code>","<code>3000</code>","Port to listen on."],["<code>stream</code>","<code>boolean</code>","<code>true</code>","Enable streaming SSR globally. Individual specs also declare a <code>stream</code> field to opt in."],["<code>staticDir</code>","<code>string</code>","<code>undefined</code>","Path to a directory of static files to serve. Relative to the process working directory."],["<code>manifest</code>","<code>string | object</code>","<code>null</code>","Explicit manifest path or object. Overrides auto-detection from <code>staticDir/dist/manifest.json</code>."],["<code>trailingSlash</code>",'<code>"remove" | "add" | "allow"</code>','<code>"remove"</code>','<code>"remove"</code> \u2014 301 redirect <code>/about/</code> \u2192 <code>/about</code>. <code>"add"</code> \u2014 301 redirect <code>/about</code> \u2192 <code>/about/</code>. <code>"allow"</code> \u2014 serve both, no redirect.'],["<code>store</code>","<code>object</code>","<code>null</code>",'Global store definition (default export from <code>pulse.store.js</code>). See <a href="/store">Global Store</a>.'],["<code>maxBody</code>","<code>number</code>","<code>1048576</code>","Maximum request body size in bytes (default 1 MB). Requests exceeding this limit receive a 413 response."],["<code>defaultCache</code>","<code>boolean | number | object</code>","<code>null</code>","Default HTML cache TTL for all pages in production. <code>true</code> = 1 h + 24 h SWR. A number sets <code>max-age</code> in seconds. An object accepts <code>{ public, maxAge, staleWhileRevalidate }</code>. <code>spec.cache</code> overrides per-page."],["<code>fetcherTimeout</code>","<code>number</code>","<code>null</code>","Global timeout in milliseconds for all server fetchers. A fetcher that does not resolve within this limit rejects with a timeout error (\u2192 500). Override per page with <code>spec.serverTimeout</code>."],["<code>shutdownTimeout</code>","<code>number</code>","<code>30000</code>",'Milliseconds to wait for in-flight requests to finish during graceful shutdown before force-exiting. See <a href="#graceful-shutdown">Graceful shutdown</a>.'],["<code>healthCheck</code>","<code>string | false</code>",'<code>"/healthz"</code>','Path for the built-in health check endpoint. Returns <code>{ status: "ok", uptime }</code>. Set to <code>false</code> to disable. The endpoint bypasses <code>onRequest</code> so load balancers always get a response.'],["<code>resolveBrand</code>","<code>async (host) => any</code>","<code>undefined</code>","Multi-brand support. Called once per host (cached 60s). Result is attached to <code>ctx.brand</code> and available in <code>guard</code>, <code>server</code>, and <code>meta</code> functions."],["<code>onRequest</code>","<code>function</code>","<code>undefined</code>","Called on every request before routing. Return <code>false</code> to short-circuit Pulse handling."],["<code>onError</code>","<code>function</code>","<code>undefined</code>","Called on unhandled errors. Receives <code>(err, req, res)</code>."]])}
+
+      ${e("example","Full example")}
+      ${o(t(`import { createServer } from '@invisibleloop/pulse'
+import home    from './src/pages/home.js'
+import contact from './src/pages/contact.js'
+
+createServer([home, contact], {
+  port:      3000,
+  stream:    true,
+  staticDir: 'public',
+  onRequest: (req, res) => {
+    // Add custom headers
+    res.setHeader('X-My-Header', 'my-value')
+    // Return false to block a request
+    if (req.url.startsWith('/admin') && !isAuthenticated(req)) {
+      res.writeHead(401)
+      res.end('Unauthorized')
+      return false
+    }
+    // Return undefined (or nothing) to let Pulse handle it
+  },
+  onError: (err, req, res) => {
+    console.error(err)
+    if (!res.headersSent) {
+      res.writeHead(500, { 'Content-Type': 'text/html' })
+      res.end('<h1>Internal Server Error</h1>')
+    }
+  },
+})`,"js"))}
+
+      ${e("multi-brand","Multi-brand sites")}
+      <p>One Pulse server can serve multiple brands, using the request domain as the key. Pass <code>resolveBrand</code> to <code>createServer</code> \u2014 it receives the <code>host</code> header and returns a brand config object of any shape you choose. The result is cached per host for 60 seconds and attached to <code>ctx.brand</code>.</p>
+      ${o(t(`// server.js
+createServer(specs, {
+  resolveBrand: async (host) => {
+    const slug = host.split('.')[0]          // 'acme' from 'acme.myco.com'
+    return db.brands.findBySlug(slug)        // { slug, name, accent, logo, ... }
+  }
+})`,"js"))}
+      <p><code>ctx.brand</code> is available in <code>guard</code>, <code>server</code> fetchers, and any <code>meta</code> field. Meta fields can be functions that receive <code>ctx</code> \u2014 Pulse calls them per request:</p>
+      ${o(t(`export default {
+  route: '/',
+
+  meta: {
+    title:       (ctx) => \`\${ctx.brand.name} \u2014 Home\`,
+    description: (ctx) => ctx.brand.tagline,
+    styles:      (ctx) => ['/pulse-ui.css', \`/themes/\${ctx.brand.slug}.css\`],
+  },
+
+  // Expose brand config to the view via server state
+  server: {
+    brand: (ctx) => ctx.brand,
+  },
+
+  view: (state, { brand }) => \`
+    <header>
+      <img src="\${brand.logo}" alt="\${brand.name}">
+      <nav>...</nav>
+    </header>
+    <main>...</main>
+  \`,
+
+  guard: async (ctx) => {
+    if (!ctx.brand) return { redirect: '/not-found' }
+  },
+}`,"js"))}
+      ${s("tip","Keep brand theme differences in CSS custom properties. One <code>/pulse-ui.css</code> handles layout and components \u2014 each <code>/themes/brand.css</code> only overrides <code>:root</code> variables like <code>--color-accent</code> and <code>--font-heading</code>. Theme files are typically under 1 kB.")}
+
+      ${e("startup-validation","Startup validation")}
+      <p>All specs are validated against the Pulse schema at startup. An invalid spec throws before the server accepts any connections \u2014 misconfigured specs are caught immediately, not when a user first hits the route. There is no silent failure path.</p>
+
+      ${e("static-files","Static file serving")}
+      <p>When <code>staticDir</code> is set, Pulse serves all files in that directory at their relative path. For example, a file at <code>public/app.css</code> is served at <code>/app.css</code>.</p>
+      <p>If <code>staticDir/dist/manifest.json</code> exists, Pulse automatically loads it to resolve production hydration bundle paths. No additional configuration is needed.</p>
+      ${o(t(`createServer(specs, {
+  staticDir: 'public',   // serves public/* at /*
+  // manifest auto-detected from public/dist/manifest.json
+})`,"js"))}
+
+      ${e("response-behaviour","Response behaviour")}
+      ${r(["Request type","Response"],[["Full page request (GET/HEAD)","SSR HTML with doctype, head, body, and optional hydration script"],["<code>X-Pulse-Navigate: true</code> header","JSON: <code>{ html, title, hydrate, serverState }</code> for client-side navigation"],["POST/PUT/DELETE to a raw response spec","Handled by <code>spec.render</code> \u2014 used for webhooks and API endpoints"],["POST/PUT/DELETE to a page spec","405 Method Not Allowed"],["Static file","File contents with appropriate Content-Type"],["No matching route","404 response"]])}
+
+      ${e("body-parsing","Reading request bodies")}
+      <p>Body parsing is available in <code>guard</code>, <code>server.*</code> fetchers, and <code>render</code> (raw specs). All methods are lazy \u2014 the stream is consumed once and the result is memoised per request.</p>
+      ${r(["Method","Returns","Description"],[["<code>await ctx.json()</code>","<code>object | null</code>","Parse a JSON request body. Returns <code>null</code> for an empty body."],["<code>await ctx.text()</code>","<code>string</code>","Read the body as a plain string."],["<code>await ctx.formData()</code>","<code>object | null</code>","Parse a URL-encoded body into a plain object. Returns <code>null</code> for an empty body."],["<code>await ctx.buffer()</code>","<code>Buffer</code>","Read the raw body as a Node.js Buffer."]])}
+      <p>Bodies larger than <code>maxBody</code> (default 1 MB) are rejected with a <strong>413</strong> before the handler runs. Set <code>maxBody</code> in <code>createServer</code> options to adjust.</p>
+      <p>Page specs only accept <strong>GET and HEAD</strong> by default \u2014 POST returns 405. To accept other methods, declare <code>spec.methods</code>:</p>
+      ${o(t(`export default {
+  route:   '/contact',
+  methods: ['GET', 'POST'],
+
+  guard: async (ctx) => {
+    if (ctx.method === 'POST') {
+      const data = await ctx.formData()
+      if (!data.email) return { status: 422, json: { error: 'Email required' } }
+      await db.leads.create(data)
+      return { redirect: '/contact?sent=1' }
+    }
+  },
+
+  state: {},
+  view: () => \`<form method="POST">...</form>\`,
+}`,"js"))}
+      ${s("note","Raw response specs (<code>contentType</code> set) accept any HTTP method without <code>spec.methods</code> \u2014 they are always method-agnostic.")}
+
+      ${e("escaping","Escaping user data")}
+      <p>Import <code>escHtml</code> from <code>@invisibleloop/pulse/html</code> to safely embed untrusted values in HTML view strings:</p>
+      ${o(t(`import { escHtml } from '@invisibleloop/pulse/html'
+
+view: (state) => \`
+  <p>Hello, \${escHtml(state.username)}</p>
+\``,"js"))}
+      ${s("warning","Always use <code>escHtml</code> around values that originate from user input, URL params, or external APIs. Omitting it is an XSS vulnerability.")}
+      <p>To use a nonce on a view-authored inline script, pass <code>ctx.nonce</code> through a server fetcher:</p>
+      ${o(t(`server: {
+  meta: async (ctx) => ({ nonce: ctx.nonce }),
+},
+
+view: (state, server) => \`
+  <script nonce="\${server.meta.nonce}">console.log('inline ok')<\/script>
+\``,"js"))}
+      <p>Inline scripts without the matching nonce are blocked by the CSP.</p>
+
+      ${e("security-headers","Security headers")}
+      <p>Pulse sends the following headers on <strong>every</strong> response \u2014 including 404 and 500 errors. There is no configuration required and no way to accidentally omit them:</p>
+      ${o(t(`X-Content-Type-Options:       nosniff
+X-Frame-Options:              DENY
+Referrer-Policy:              strict-origin-when-cross-origin
+Permissions-Policy:           camera=(), microphone=(), geolocation=()
+Cross-Origin-Opener-Policy:   same-origin
+Cross-Origin-Resource-Policy: same-origin`,"bash"))}
+
+      ${e("csp","Content Security Policy")}
+      <p>HTML page responses include a <code>Content-Security-Policy</code> header. Scripts require a per-request cryptographic nonce; stylesheets are restricted to same-origin; everything else defaults to <code>'none'</code>:</p>
+      ${o(t(`Content-Security-Policy:
+  default-src 'none';
+  script-src 'self' 'nonce-{random}';
+  style-src 'self';
+  style-src-attr 'unsafe-inline';
+  img-src 'self' data:;
+  font-src 'self';
+  connect-src 'self';
+  frame-ancestors 'none';
+  base-uri 'self';
+  form-action 'self'`,"bash"))}
+      <p>All inline scripts injected by the framework carry a matching <code>nonce</code> attribute. The nonce is also available as <code>ctx.nonce</code> so view functions can attach it to their own inline scripts.</p>
+      <p>To load resources from external origins \u2014 Google Fonts, a CDN, an external API \u2014 pass a <code>csp</code> object to <code>createServer</code>. Sources are merged into the framework defaults; existing directives are not replaced:</p>
+      ${o(t(`createServer(specs, {
+  csp: {
+    'style-src': ['https://fonts.googleapis.com'],
+    'font-src':  ['https://fonts.gstatic.com'],
+    'connect-src': ['https://api.example.com'],
+    'img-src': ['https://images.unsplash.com'],
+  },
+})`,"js"))}
+      ${s("note",`The <code>style-src-attr 'unsafe-inline'</code> directive is required for inline <code>style="..."</code> attributes used by the UI component library to set CSS custom properties (e.g. spinner size, progress fill). It is scoped to attributes only \u2014 <code>&lt;style&gt;</code> blocks are fully nonce-controlled.`)}
+
+      ${e("hsts","HSTS")}
+      <p>When a request arrives with <code>x-forwarded-proto: https</code> (or over a TLS socket), Pulse adds:</p>
+      ${o(t("Strict-Transport-Security: max-age=31536000; includeSubDomains; preload","bash"))}
+      <p>This is automatic \u2014 no configuration required. On plain HTTP the header is omitted. The <code>preload</code> directive means you can submit the domain to <a href="https://hstspreload.org" target="_blank" rel="noopener">hstspreload.org</a> so browsers enforce HTTPS before the first connection \u2014 this is a separate manual step, not automatic.</p>
+
+      ${e("cookies","Cookie defaults")}
+      <p>Cookies set via <code>ctx.setCookie()</code> default to <code>SameSite=Lax</code>. CSRF protection is on by default \u2014 omitting a <code>sameSite</code> option does not weaken it.</p>
+
+      ${e("compression","Compression")}
+      <p>Pulse compresses all compressible responses using brotli (preferred) or gzip (fallback), based on the <code>Accept-Encoding</code> header. Streaming responses use transform streams so compression and delivery happen concurrently.</p>
+
+      ${e("nav-header","X-Pulse-Navigate header")}
+      <p>When a request includes <code>X-Pulse-Navigate: true</code>, Pulse returns a JSON response instead of full HTML. This is used by the client-side navigation system to swap page content without a full reload:</p>
+      ${o(t(`{
+  "html":        "<main>...rendered content...</main>",
+  "title":       "Page Title \u2014 Site",
+  "hydrate":     "/dist/page.boot-abc123.js",
+  "serverState": { "product": { "id": 1, "name": "..." } }
+}`,"js"))}
+
+      ${e("health-check","Health check endpoint")}
+      <p>Pulse exposes a built-in health check at <code>/healthz</code> (configurable). It responds before <code>onRequest</code>, static file serving, and route matching \u2014 so load balancers and orchestration systems always get a response even if a hook is faulty.</p>
+      ${o(t(`GET /healthz \u2192 200 OK
+{ "status": "ok", "uptime": 42.3 }`,"json"))}
+      <p>Configure the path or disable it entirely:</p>
+      ${o(t(`createServer(specs, {
+  healthCheck: '/ping',   // custom path
+  // healthCheck: false,  // disable
+})`,"js"))}
+      ${s("note","<code>HEAD /healthz</code> is also supported \u2014 returns the same status headers with no body. The endpoint sets <code>Cache-Control: no-store</code> so proxies never serve a stale health status.")}
+
+      ${e("graceful-shutdown","Graceful shutdown")}
+      <p>Pulse registers <code>SIGTERM</code> and <code>SIGINT</code> handlers automatically. When either signal arrives:</p>
+      <ol>
+        <li><code>server.close()</code> stops accepting new connections.</li>
+        <li>Idle keep-alive sockets are destroyed immediately.</li>
+        <li>In-flight requests are allowed to finish naturally.</li>
+        <li>After <code>shutdownTimeout</code> ms (default 30 000 ms), the process force-exits to prevent a stuck request from blocking a deploy indefinitely.</li>
+      </ol>
+      <p>The <code>shutdown()</code> function is also returned from <code>createServer</code> so you can trigger it programmatically:</p>
+      ${o(t(`const { server, shutdown } = createServer(specs, {
+  port:            3000,
+  shutdownTimeout: 10000,  // 10 s \u2014 override the 30 s default
+})
+
+// SIGTERM is already wired automatically.
+// Call manually when needed \u2014 idempotent, safe to call multiple times.
+shutdown()`,"js"))}
+      ${s("note","Idle keep-alive sockets are destroyed immediately on shutdown. In-flight streaming responses finish sending before the socket is closed \u2014 no partial responses are delivered to clients.")}
+    `})};var c=document.getElementById("pulse-root");c&&!c.dataset.pulseMounted&&(c.dataset.pulseMounted="1",a(d,c,window.__PULSE_SERVER__||{},{ssr:!0}),u(c,a));var T=d;export{T as default};

package/docs/public/dist/server-data.boot-Y7HQYC4R.js

@@ -0,0 +1,157 @@
+import{a as r}from"./runtime-QFURDKA2.js";import{a as c,b as d,c as i,d as l,e,g as t,h as p,i as a}from"./runtime-L2HNXIHW.js";import{a as o,b as u}from"./runtime-B73WLANC.js";var{prev:h,next:v}=c("/server-data"),n={route:"/server-data",meta:{title:"Server Data \u2014 Pulse Docs",description:"Fetch, transform, and combine data on the server before rendering \u2014 external APIs, multiple fetchers, parallel requests.",styles:["/docs.css"]},state:{},view:()=>d({currentHref:"/server-data",prev:h,next:v,content:`
+      ${i("Server Data")}
+      ${l("The <code>server</code> field fetches data before the page renders. It runs exclusively on the server \u2014 credentials, database access, and API secrets stay there. The browser never receives the fetcher code, only its serialised output.")}
+
+      ${e("basic","Basic usage")}
+      <p>Declare a <code>data</code> async function inside the <code>server</code> object. It receives a <code>ctx</code> object with request context and returns a plain object:</p>
+      ${t(r(`export default {
+  route: '/products/:id',
+  state: { quantity: 1 },
+  server: {
+    data: async (ctx) => {
+      const product = await db.products.findById(ctx.params.id)
+      const related = await db.products.findRelated(product.category)
+      return { product, related }
+    },
+  },
+  view: (state, server) => \`
+    <main>
+      <h1>\${server.product.name}</h1>
+      <p>\${server.product.description}</p>
+      <p>Price: \xA3\${server.product.price}</p>
+      <div class="quantity">
+        <button data-event="decrement">-</button>
+        <span>\${state.quantity}</span>
+        <button data-event="increment">+</button>
+      </div>
+    </main>
+  \`,
+}`,"js"))}
+
+      ${e("ctx","The ctx object")}
+      <p>The <code>ctx</code> argument passed to <code>server.data()</code> contains the full request context:</p>
+      ${p(["Property","Type","Description"],[["<code>ctx.params</code>","<code>object</code>","URL path parameters from dynamic route segments (e.g. <code>:id</code>)."],["<code>ctx.query</code>","<code>object</code>","Parsed query string parameters (e.g. <code>?page=2&sort=asc</code>)."],["<code>ctx.headers</code>","<code>object</code>","Incoming request headers (lowercase keys)."],["<code>ctx.cookies</code>","<code>object</code>","Parsed cookies from the <code>Cookie</code> header."]])}
+      ${t(r(`server: {
+  data: async (ctx) => {
+    // Dynamic route: /blog/:year/:slug
+    const { year, slug } = ctx.params
+
+    // Query string: ?page=2
+    const page = parseInt(ctx.query.page ?? '1', 10)
+
+    // Authentication via cookie
+    const session = ctx.cookies.sessionId
+      ? await sessions.find(ctx.cookies.sessionId)
+      : null
+
+    const post = await db.posts.findBySlug(year, slug)
+    return { post, page, session }
+  },
+}`,"js"))}
+
+      ${e("view-arg","Server state in the view")}
+      <p>The resolved values from all server fetchers are merged into a single object and passed to the <code>view</code> function as its second argument, conventionally named <code>server</code>. Each fetcher key becomes a property:</p>
+      ${t(r(`// server: { post: async (ctx) => ... }
+
+view: (state, server) => \`
+  <article>
+    <h1>\${server.post.title}</h1>
+    <time>\${server.post.date}</time>
+    \${server.post.body}
+  </article>
+\``,"js"))}
+      ${a("note","If no <code>server</code> fetchers are declared, the second argument to <code>view</code> is an empty object <code>{}</code>.")}
+
+      ${e("ssr-only","SSR only \u2014 not available on the client")}
+      <p>Server data is resolved before the HTML is generated and is never re-fetched in the browser. After hydration, the serialised output is available to the view as <code>window.__PULSE_SERVER__</code> for client-side re-renders \u2014 it is the same value the server computed, not a new request.</p>
+      ${a("warning","Server state is serialised into the page HTML as <code>window.__PULSE_SERVER__</code> and is visible to anyone who views source. Filter fetcher output to only what the view needs \u2014 never include credentials, internal IDs, or user data beyond what must be rendered.")}
+
+      ${e("errors","Error handling")}
+      <p>If <code>server.data()</code> throws, the server returns a 500 error response. Handle errors gracefully by catching inside the function and returning a safe fallback:</p>
+      ${t(r(`server: {
+  data: async (ctx) => {
+    try {
+      const product = await db.products.findById(ctx.params.id)
+      if (!product) return { product: null, notFound: true }
+      return { product, notFound: false }
+    } catch (err) {
+      console.error('Failed to load product', err)
+      return { product: null, notFound: true }
+    }
+  },
+},
+view: (state, server) => server.notFound
+  ? \`<p>Product not found.</p>\`
+  : \`<h1>\${server.product.name}</h1>\``,"js"))}
+
+      ${e("multiple-fetchers","Multiple named fetchers")}
+      <p>The <code>server</code> object supports any number of named async functions. Each one receives <code>ctx</code> and its return value is available on <code>server</code> in the view under the same key. Fetchers run in parallel \u2014 the page renders once all have resolved:</p>
+      ${t(r(`export default {
+  route: '/products/:id',
+  state: { quantity: 1 },
+  server: {
+    product: async (ctx) => db.products.findById(ctx.params.id),
+    reviews: async (ctx) => db.reviews.forProduct(ctx.params.id),
+    related: async (ctx) => db.products.related(ctx.params.id),
+  },
+  view: (state, server) => \`
+    <h1>\${server.product.name}</h1>
+    <p>\${server.reviews.length} reviews</p>
+    \${server.related.map(p => \`<a href="/products/\${p.id}">\${p.name}</a>\`).join('')}
+  \`,
+}`,"js"))}
+
+      ${e("external-apis","External API fetching")}
+      <p>Server fetchers run in Node.js. API keys and credentials are read from environment variables and never leave the server \u2014 only the fetcher's return value is serialised into the page:</p>
+      ${t(r(`server: {
+  weather: async (ctx) => {
+    const res = await fetch(
+      \`https://api.weather.example.com/current?city=\${ctx.query.city}\`,
+      { headers: { Authorization: \`Bearer \${process.env.WEATHER_API_KEY}\` } }
+    )
+    if (!res.ok) return null
+    return res.json()
+  },
+}`,"js"))}
+
+      ${e("transforming","Transforming API responses")}
+      <p>Fetchers are the right place to reshape external responses before they reach the view. Filter to only what the view needs \u2014 this reduces payload size and prevents internal fields from being serialised into the page HTML:</p>
+      ${t(r(`server: {
+  article: async (ctx) => {
+    const res  = await fetch(\`https://cms.example.com/articles/\${ctx.params.slug}\`)
+    const data = await res.json()
+
+    // Shape and filter before serialisation
+    return {
+      title:       data.fields.title,
+      body:        data.fields.bodyHtml,
+      publishedAt: new Date(data.sys.createdAt).toLocaleDateString('en-GB'),
+      author:      data.fields.author.name,
+      // data.sys.revision, internal IDs etc. are dropped here
+    }
+  },
+}`,"js"))}
+
+      ${e("parallel","Parallel fetches within a single fetcher")}
+      <p>When multiple independent requests are needed inside a single fetcher, <code>Promise.all</code> runs them concurrently so the total wait time is the slowest request, not the sum:</p>
+      ${t(r(`server: {
+  page: async (ctx) => {
+    const [hero, featured, nav] = await Promise.all([
+      fetch('https://cms.example.com/hero').then(r => r.json()),
+      fetch('https://cms.example.com/featured').then(r => r.json()),
+      fetch('https://cms.example.com/nav').then(r => r.json()),
+    ])
+    return { hero, featured, nav }
+  },
+}`,"js"))}
+
+      ${e("caching-link","Caching server data")}
+      <p>Use <a href="/caching"><code>serverTtl</code></a> to cache fetcher results in-process for a number of seconds. This avoids hitting external APIs or a database on every request for data that changes infrequently.</p>
+      ${t(r(`export default {
+  route: '/homepage',
+  serverTtl: 60,  // cache all server fetchers for 60 seconds
+  server: {
+    featured: async () => fetch('https://api.example.com/featured').then(r => r.json()),
+  },
+}`,"js"))}
+    `})};var s=document.getElementById("pulse-root");s&&!s.dataset.pulseMounted&&(s.dataset.pulseMounted="1",o(n,s,window.__PULSE_SERVER__||{},{ssr:!0}),u(s,o));var j=n;export{j as default};

package/docs/public/dist/slash-commands.boot-V2UV7OW2.js

@@ -0,0 +1,26 @@
+import{a as s}from"./runtime-QFURDKA2.js";import{a as n,b as i,c as d,d as l,e,g as o,h as c,i as u}from"./runtime-L2HNXIHW.js";import{a,b as h}from"./runtime-B73WLANC.js";var{prev:p,next:m}=n("/slash-commands"),r={route:"/slash-commands",meta:{title:"Slash Commands \u2014 Pulse Docs",description:"The built-in slash commands available in the Pulse AI agent session.",styles:["/docs.css"]},state:{},view:()=>i({currentHref:"/slash-commands",prev:p,next:m,content:`
+      ${d("Slash Commands")}
+      ${l("Slash commands close the development loop inside the agent session. Building, auditing, and verifying performance happen without leaving the conversation \u2014 and every audit is checked against the thresholds you have declared in config.")}
+
+      ${e("commands","Available commands")}
+      ${c(["Command","What it does"],[["<code>/pulse-dev</code>","Starts (or restarts) the development server. The server watches for file changes and reloads automatically."],["<code>/pulse-stop</code>","Stops the running development server."],["<code>/pulse-build</code>","Runs a production build. Bundles all specs via esbuild into <code>public/dist/</code> with content-hashed filenames."],["<code>/pulse-start</code>","Starts the production server against the built output. Used to verify production behaviour before deploying."],["<code>/pulse-report</code>","Runs a Lighthouse audit against a production build and opens the performance report dashboard. Captures Performance score, web vitals, bundle sizes, and request counts."]])}
+
+      ${e("usage","Using commands")}
+      <p>Commands are typed directly into the agent chat:</p>
+      ${o(s(`/pulse-dev
+/pulse-report`,"bash"))}
+      <p>The agent executes the relevant CLI steps and reports back with results, including whether any Lighthouse score or Core Web Vitals metric failed a configured threshold.</p>
+
+      ${u("note","<code>/pulse-report</code> performs a full production build before auditing. This guarantees accurate scores and correct brotli-compressed bundle sizes \u2014 development builds are unminified and serve no production metrics.")}
+
+      ${e("plain-language","Plain language prompts")}
+      <p>Slash commands cover the most common operations. For everything else, describe the goal \u2014 the agent handles the implementation within Pulse's spec structure:</p>
+      ${o(s(`"Create a blog index page that fetches posts from an API"
+"Add email validation to the contact form"
+"Build a checkout flow with a Stripe payment step"
+"Add a guard to the dashboard so unauthenticated users are redirected to /login"`,"bash"))}
+      <p>The agent produces spec files that conform to Pulse's structure \u2014 the framework enforces correctness, so there is no manual wiring to verify.</p>
+
+      ${e("report-dashboard","Performance report dashboard")}
+      <p>The report dashboard is available at <code>/_pulse/report</code> when the dev server is running. It shows a history of Lighthouse audits across all pages \u2014 Performance score, Core Web Vitals, bundle sizes, and request counts. Threshold failures are highlighted. Each audit is saved to <code>.pulse/reports/</code> as JSON.</p>
+    `})};var t=document.getElementById("pulse-root");t&&!t.dataset.pulseMounted&&(t.dataset.pulseMounted="1",a(r,t,window.__PULSE_SERVER__||{},{ssr:!0}),h(t,a));var P=r;export{P as default};

package/docs/public/dist/spec.boot-2WU7ZHCV.js

@@ -0,0 +1,159 @@
+import{a as o}from"./runtime-QFURDKA2.js";import{a as n,b as d,c as i,d as l,e,g as t,h as p,i as a}from"./runtime-L2HNXIHW.js";import{a as s,b as h}from"./runtime-B73WLANC.js";var{prev:u,next:m}=n("/spec"),c={route:"/spec",meta:{title:"Spec Reference \u2014 Pulse Docs",description:"Complete reference for every field in a Pulse page spec.",styles:["/docs.css"]},state:{},view:()=>d({currentHref:"/spec",prev:u,next:m,content:`
+      ${i("Spec Reference")}
+      ${l("The spec is a plain JavaScript object that defines a complete contract for a page. Pulse validates every spec at startup and rejects invalid ones before the server accepts connections. At runtime, it enforces state bounds, validation rules, and lifecycle order automatically.")}
+
+      ${e("quick-ref","Quick reference")}
+      ${p(["Field","Type","Required","Description"],[["<code>route</code>","<code>string</code>","Yes","URL pattern for this page. Supports <code>:param</code> segments."],["<code>state</code>","<code>object</code>","Yes","Initial client-side state. Deep-cloned on mount."],["<code>view</code>","<code>function</code>","Yes","Returns an HTML string. Receives <code>(state, serverState)</code>."],["<code>meta</code>","<code>object</code>","No","Page metadata: title, description, styles, OG tags, schema."],["<code>hydrate</code>","<code>string</code>","No","Browser-importable path to this spec file. Enables client hydration."],["<code>mutations</code>","<code>object</code>","No","Synchronous state updaters keyed by name."],["<code>actions</code>","<code>object</code>","No","Async operations with full lifecycle hooks."],["<code>validation</code>","<code>object</code>","No","Declarative validation rules keyed by dot-path state keys."],["<code>constraints</code>","<code>object</code>","No","Min/max bounds enforced after every mutation."],["<code>persist</code>","<code>string[]</code>","No","State keys to save in <code>localStorage</code>."],["<code>server</code>","<code>object</code>","No","Server-side data fetcher. Result passed to <code>view</code> as second arg."],["<code>store</code>","<code>string[]</code>","No",'Global store keys this page subscribes to. See <a href="/store">Global Store</a>.'],["<code>methods</code>","<code>string[]</code>","No","HTTP methods this page accepts. Default <code>['GET', 'HEAD']</code>. Add <code>'POST'</code> etc. to opt in."],["<code>stream</code>","<code>object</code>","No","Streaming SSR config: <code>shell</code> + <code>deferred</code> segment names."],["<code>cache</code>","<code>object</code>","No","HTTP cache control headers for the page response."],["<code>serverTtl</code>","<code>number</code>","No","Seconds to cache server data in-process."],["<code>serverTimeout</code>","<code>number</code>","No","Timeout in ms for all server fetchers on this page. Overrides the global <code>fetcherTimeout</code> option."],["<code>contentType</code>","<code>string</code>","No","Override response Content-Type. Enables raw (non-HTML) responses."],["<code>onViewError</code>","<code>function</code>","No","Fallback renderer called when <code>view()</code> throws. Return an HTML string."]])}
+
+      ${e("route","route")}
+      <p>The URL pattern this spec handles. Supports static segments and dynamic <code>:param</code> segments.</p>
+      ${t(o(`route: '/products/:id'   // matches /products/42
+route: '/blog/:year/:slug'`,"js"))}
+      <p>Dynamic segments are available in server data and actions via <code>ctx.params</code>. See <a href="/routing">Routing</a> for more.</p>
+
+      ${e("state","state")}
+      <p>The initial client-side state for the page. Always a plain object. Pulse deep-clones it on every mount \u2014 mutations never affect the original spec, and state cannot leak between page loads.</p>
+      ${t(o(`state: {
+  count: 0,
+  user: { name: '', email: '' },
+  items: [],
+}`,"js"))}
+      <p>The state object is passed as the first argument to <code>view</code>, and as the first argument to every mutation and action hook. See <a href="/state">State</a>.</p>
+
+      ${e("view","view")}
+      <p>A pure function that receives <code>(state, serverState)</code> and returns an HTML string. Side effects are not permitted \u2014 the same inputs must always produce the same output. Pulse uses this guarantee to diff and re-render efficiently after mutations.</p>
+      ${t(o("view: (state, server) => `\n  <main>\n    <h1>Hello, ${state.name}</h1>\n    ${server.items.map(item => `<p>${item.title}</p>`).join('')}\n  </main>\n`","js"))}
+      <p>For streaming SSR, <code>view</code> can be an object of named segment functions. See <a href="/streaming">Streaming SSR</a>.</p>
+
+      ${e("meta","meta")}
+      <p>Page-level metadata. All fields are optional.</p>
+      ${t(o(`meta: {
+  title:       'Page Title \u2014 Site Name',
+  description: 'Meta description for search engines.',
+  styles:      ['/app.css', '/page.css'],
+  ogTitle:     'Open Graph title',
+  ogImage:     'https://example.com/og.jpg',
+  schema:      { '@type': 'WebPage', name: 'Page Title' }, // ld+json
+}`,"js"))}
+      <p>See <a href="/meta">Metadata &amp; SEO</a> for the full reference.</p>
+
+      ${e("hydrate","hydrate")}
+      <p>A browser-importable path to this spec file. Setting this enables client-side hydration \u2014 Pulse emits a bootstrap script that imports the spec bundle and calls <code>mount()</code>. In production, the path is resolved automatically via <code>manifest.json</code>.</p>
+      ${t(o(`hydrate: '/src/pages/counter.js'   // dev: source file path
+// Production: resolved automatically via manifest.json`,"js"))}
+      ${a("note","Omit <code>hydrate</code> for purely server-rendered pages with no client interactivity. Pulse sends zero JavaScript to the browser \u2014 no runtime overhead, no hydration cost.")}
+
+      ${e("mutations","mutations")}
+      <p>Synchronous state updaters. Each mutation is a function <code>(state, event) =&gt; partialState</code>. The returned partial object is merged into state. See <a href="/mutations">Mutations</a>.</p>
+      ${t(o(`mutations: {
+  increment: (state) => ({ count: state.count + 1 }),
+  setName:   (state, event) => ({ name: event.target.value }),
+}`,"js"))}
+      <p>Mutations can return <code>_toast</code> to show a notification \u2014 it is stripped from state automatically. See <a href="/actions#toast">Toast notifications</a>.</p>
+
+      ${e("actions","actions")}
+      <p>Async operations with a full lifecycle. Each action has hooks for <code>onStart</code>, optional <code>validate</code>, <code>run</code>, <code>onSuccess</code>, and <code>onError</code>. See <a href="/actions">Actions</a>.</p>
+      ${t(o(`actions: {
+  submit: {
+    onStart:   (state, formData) => ({ status: 'loading' }),
+    validate:  true,
+    run:       async (state, serverState, formData) => {
+      const res = await fetch('/api/submit', { method: 'POST', body: formData })
+      return res.json()
+    },
+    onSuccess: (state, payload) => ({ status: 'success', data: payload }),
+    onError:   (state, err) => ({
+      status: 'error',
+      errors: err?.validation ?? [{ message: err.message }],
+    }),
+  },
+}`,"js"))}
+
+      ${e("validation","validation")}
+      <p>Declarative rules checked when an action has <code>validate: true</code>. Keys are dot-path strings into state. See <a href="/validation">Validation</a>.</p>
+      ${t(o(`validation: {
+  'fields.email': { required: true, format: 'email' },
+  'fields.name':  { required: true, minLength: 2, maxLength: 100 },
+  'fields.age':   { required: true, min: 18, max: 120 },
+}`,"js"))}
+
+      ${e("constraints","constraints")}
+      <p>Min/max bounds enforced automatically after every mutation. Constraints cannot be bypassed \u2014 the state is clamped before the view re-renders, regardless of what the mutation returns. See <a href="/constraints">Constraints</a>.</p>
+      ${t(o(`constraints: {
+  count:    { min: 0, max: 100 },
+  quantity: { min: 1, max: 99 },
+}`,"js"))}
+
+      ${e("persist","persist")}
+      <p>An array of dot-path state keys to persist in <code>localStorage</code>. Values are restored on the next visit. See <a href="/persist">Persist</a>.</p>
+      ${t(o("persist: ['theme', 'user.preferences']","js"))}
+
+      ${e("server","server")}
+      <p>Server-only data fetching. The result is passed to <code>view</code> as the second argument. Not available on the client. See <a href="/server-data">Server Data</a>.</p>
+      ${t(o(`server: {
+  data: async (ctx) => {
+    const product = await db.products.find(ctx.params.id)
+    return { product }
+  }
+}`,"js"))}
+
+      ${e("stream","stream")}
+      <p>Enables streaming SSR. Declare which named view segments are in the <code>shell</code> (rendered immediately) and which are <code>deferred</code> (streamed when ready). See <a href="/streaming">Streaming SSR</a>.</p>
+      ${t(o(`stream: {
+  shell:    ['header', 'nav'],
+  deferred: ['feed', 'sidebar'],
+}`,"js"))}
+
+      ${e("cache","cache")}
+      <p>HTTP Cache-Control header configuration for the page response. See <a href="/caching">Caching</a>.</p>
+      ${t(o(`cache: {
+  public:              true,
+  maxAge:              300,       // seconds
+  staleWhileRevalidate: 86400,
+}`,"js"))}
+
+      ${e("serverTtl","serverTtl")}
+      <p>Number of seconds to cache the result of <code>server.data()</code> in-process. Subsequent requests within the TTL skip the async data fetch and re-render the HTML with the cached data. See <a href="/caching">Caching</a>.</p>
+      ${t(o("serverTtl: 60  // cache server data for 60 seconds","js"))}
+      ${a("tip","<strong>serverTtl vs cache</strong> \u2014 <code>serverTtl</code> caches only the server data fetcher results. The HTML is re-rendered on every request (good for personalised pages where only the fetched data is stable). <code>cache</code> caches the complete rendered HTML and sets <code>Cache-Control</code> headers (good for fully public pages that are identical for all users).")}
+
+      ${e("serverTimeout","serverTimeout")}
+      <p>Timeout in milliseconds for all <code>server.*</code> fetchers on this page. If any fetcher does not resolve within this limit, it rejects with a timeout error and the request returns a 500. Use this to prevent a slow DB query or external API from hanging the response indefinitely.</p>
+      ${t(o("serverTimeout: 5000  // fail after 5 s \u2014 overrides createServer fetcherTimeout","js"))}
+      <p>A global default applies to all pages via the <code>fetcherTimeout</code> option in <code>createServer</code>. <code>spec.serverTimeout</code> overrides it per page.</p>
+
+      ${e("on-view-error","onViewError")}
+      <p>An optional function called when <code>view()</code> throws at runtime. Return an HTML string to display in place of the crashed view. Without this, the Pulse runtime renders a default inline error message and logs the error to the console.</p>
+      ${t(o(`onViewError: (err, state, serverState) => \`
+  <div class="u-p-4 u-text-center">
+    <p>Something went wrong. <a href="">Reload</a></p>
+  </div>
+\``,"js"))}
+      ${a("note","On the server, a throwing view propagates to the server's error handler (500 response) unless <code>onViewError</code> is defined \u2014 in which case the page renders with the fallback HTML and a 200 status. On the client, the runtime always catches view errors and shows a fallback, whether or not <code>onViewError</code> is defined.")}
+
+      ${e("methods","methods")}
+      <p>HTTP methods this page accepts. Defaults to <code>['GET', 'HEAD']</code> \u2014 all other methods return 405. Add <code>'POST'</code> to handle form submissions or webhooks directly on a page route without a separate API endpoint.</p>
+      ${t(o("methods: ['GET', 'POST']","js"))}
+      <p>Read the method in <code>guard</code> to branch on POST vs GET:</p>
+      ${t(o(`export default {
+  route:   '/contact',
+  methods: ['GET', 'POST'],
+
+  guard: async (ctx) => {
+    if (ctx.method === 'POST') {
+      const data = await ctx.formData()
+      if (!data?.email) return { status: 422, json: { error: 'Email required' } }
+      await db.leads.create(data)
+      return { redirect: '/contact?sent=1' }
+    }
+  },
+
+  state: {},
+  view:  (state) => \`<form method="POST">...</form>\`,
+}`,"js"))}
+      ${a("note","For raw response specs (<code>contentType</code> set), all HTTP methods are accepted by default \u2014 <code>methods</code> has no effect. Use <code>ctx.method</code> inside <code>render</code> to branch.")}
+
+      ${e("contentType","contentType")}
+      <p>Override the response <code>Content-Type</code>. When set, the view function receives <code>(ctx, serverState)</code> and returns the raw response body \u2014 the normal HTML wrapper is bypassed. See <a href="/raw-responses">Raw Responses</a>.</p>
+      ${t(o("contentType: 'application/rss+xml'","js"))}
+    `})};var r=document.getElementById("pulse-root");r&&!r.dataset.pulseMounted&&(r.dataset.pulseMounted="1",s(c,r,window.__PULSE_SERVER__||{},{ssr:!0}),h(r,s));var b=c;export{b as default};