@invisibleloop/pulse 0.2.0 → 0.2.2

package/CLAUDE.md

@@ -186,7 +186,7 @@ The bundle is self-executing (imports spec, calls `mount` + `initNavigation` int
 
 `npm run build` generates three things per app:
 
-- `public/dist/runtime-[hash].js` — shared runtime (mount + navigate + schema, ~2.1 kB brotli)
+- `public/dist/runtime-[hash].js` — shared runtime (mount + navigate + store, ~3.8 kB brotli)
 - `public/dist/[name].boot-[hash].js` — per-page spec bundle (~0.5–0.9 kB brotli)
 - `public/dist/manifest.json` — maps `/examples/foo.js` → `/dist/foo.boot-HASH.js`
 
@@ -395,8 +395,10 @@ Before writing any UI HTML by hand, check `src/ui/index.js` — there are 50+ co
 
 | Page | CLS | JS (brotli) |
 |---|---|---|
-| /counter | 0.00 | 3.5 kB (first visit) / 0.35 kB (cached runtime) |
-| /contact | 0.00 | 3.6 kB (first visit) / 0.47 kB (cached runtime) |
+| /counter | 0.00 | 4.2 kB (first visit) / 0.4 kB (cached runtime) |
+| /contact | 0.00 | 4.3 kB (first visit) / 0.5 kB (cached runtime) |
+
+First-visit JS = runtime chunk (~3.8 kB) + per-page boot file (~0.4–0.9 kB). On repeat visits the runtime is served from cache — only the boot file is fetched. If multiple pages share UI components, esbuild's code splitting extracts those into the runtime chunk, so the runtime chunk grows with shared code.
 
 Lighthouse: 100/100/100 (Accessibility / Best Practices / SEO) on both pages.
 

package/benchmark/public/dist/counter.boot-PO6SNSJZ.js

@@ -0,0 +1,8 @@
+import{a as n,b as u}from"./runtime-5Y7ESAIB.js";var o={route:"/counter",hydrate:"/src/pages/counter.js",meta:{title:"Counter \u2014 Pulse Benchmark",styles:["/pulse.css"]},state:{count:0},constraints:{count:{min:0,max:10}},mutations:{increment:t=>({count:t.count+1}),decrement:t=>({count:t.count-1})},view:(t,r)=>`
+    <main id="main-content">
+      <p>${r.greeting}</p>
+      <p>Count: ${t.count}</p>
+      <button data-event="decrement">\u2212</button>
+      <button data-event="increment">+</button>
+    </main>
+  `};var e=document.getElementById("pulse-root");e&&!e.dataset.pulseMounted&&(e.dataset.pulseMounted="1",n(o,e,window.__PULSE_SERVER__||{},{ssr:!0}),u(e,n));var m=o;export{m as default};

package/benchmark/public/dist/home.boot-YK6VAEQI.js

@@ -0,0 +1,6 @@
+import{a as e,b as i}from"./runtime-5Y7ESAIB.js";var o={route:"/home",meta:{title:"Home \u2014 Pulse Benchmark",styles:["/pulse.css"]},state:{},view:()=>`
+    <main id="main-content">
+      <h1>Pulse Benchmark</h1>
+      <p>Static page \u2014 no client-side interactivity.</p>
+    </main>
+  `};var t=document.getElementById("pulse-root");t&&!t.dataset.pulseMounted&&(t.dataset.pulseMounted="1",e(o,t,window.__PULSE_SERVER__||{},{ssr:!0}),i(t,e));var r=o;export{r as default};

package/benchmark/public/dist/manifest.json

@@ -0,0 +1,5 @@
+{
+  "/src/pages/counter.js": "/../benchmark/public/dist/counter.boot-PO6SNSJZ.js",
+  "/src/pages/home.js": "/../benchmark/public/dist/home.boot-YK6VAEQI.js",
+  "_runtime": "/../benchmark/public/dist/runtime-5Y7ESAIB.js"
+}

package/benchmark/public/dist/runtime-5Y7ESAIB.js

@@ -0,0 +1,2 @@
+var E={},V=!1,R={},D=!1,k=new Set;function U(t){V||(E={...t||{}},V=!0)}function q(){return E}function K(t){return k.add(t),()=>k.delete(t)}function P(t){E={...E,...t};for(let o of k)o(E)}function H(t){D||(R=t||{},D=!0)}function N(t,o){let r=R[t];if(!r){console.warn(`[Pulse] No store mutation found for "${t}"`);return}P(r(E,o))}var T=t=>import("./runtime-KO4BHUQ3.js").then(o=>o.showToast(t));function ft(t,o,r={},s={}){if(!t||t.state===void 0||!t.view)throw new Error("[Pulse] mount: spec must have state and view");typeof window<"u"&&(U(window.__PULSE_STORE__||{}),s.store?.mutations&&H(s.store.mutations));let e=new Set(t.store||[]),i={};for(let[u,c]of Object.entries(r))e.has(u)||(i[u]=c);function a(){if(!e.size)return i;let u=q(),c={};for(let w of e)u[w]!==void 0&&(c[w]=u[w]);return{...c,...i}}let n=z(t.state),h=t.persist?.length?`pulse:${t.route||location.pathname}`:null,y=!1;if(h)try{let u=JSON.parse(localStorage.getItem(h)||"{}");t.persist.forEach(c=>{u[c]!==void 0&&u[c]!==t.state[c]&&(n[c]=u[c],y=!0)})}catch{}function d(){if(h)try{let u={};t.persist.forEach(c=>{u[c]=n[c]}),localStorage.setItem(h,JSON.stringify(u))}catch{}}let m=null;function f(){let u;try{u=Z(t,n,a())}catch(c){console.error("[Pulse] View error:",c);let w=a();u=t.onViewError?t.onViewError(c,n,w):ot(c)}u!==m&&(m=u,et(o,u))}function S(u,c){if(t.mutations?.[u]){let w=t.mutations[u](n,c);w?._toast&&T(w._toast);let{_toast:C,...g}=w??{},p=n;n=x({...n,...g},t.constraints),d(),$(p,n)&&f();return}if(t.actions?.[u]){b(u,t.actions[u],n,c);return}console.warn(`[Pulse] No mutation or action found for "${u}"`)}async function b(u,c,w,C){if(c.onStart){let g=c.onStart(w,C);g?._toast&&T(g._toast);let{_toast:p,...M}=g??{},_=n;n=x({...n,...M},t.constraints),$(_,n)&&f()}if(c.validate){let g=rt(n,t.validation);if(g.length>0){console.warn(`[Pulse] Validation failed for action "${u}":`,g);let p=c.onError?.(n,{validation:g})??{};p._toast&&T(p._toast);let{_toast:M,..._}=p,L=n;n=x({...n,..._},t.constraints),$(L,n)&&f();return}}try{let g=await c.run(n,a(),C),p=c.onSuccess(n,g)??{};p._storeUpdate&&P(p._storeUpdate),p._toast&&T(p._toast);let{_storeUpdate:M,_toast:_,...L}=p,Y=n;n=x({...n,...L},t.constraints),$(Y,n)&&f()}catch(g){console.error(`[Pulse] Action "${u}" failed:`,g);let p=c.onError(n,g)??{};p._toast&&T(p._toast);let{_toast:M,..._}=p,L=n;n=x({...n,..._},t.constraints),$(L,n)&&f()}d()}let v=new AbortController;tt(o,S,v.signal);let l=e.size>0?K(()=>f()):null;return s.ssr&&!y||f(),{getState:()=>z(n),dispatch:S,refresh:f,destroy:()=>{l?.(),v.abort(),o.innerHTML=""}}}function Z(t,o,r){return typeof t.view=="function"?t.view(o,r):Object.values(t.view).map(s=>s(o,r)).join("")}function tt(t,o,r){let s=r?{signal:r}:{};t.addEventListener("click",e=>{let i=e.target?.closest?.("[data-store-event]");if(i){let[m,f]=A(i.dataset.storeEvent);m==="click"&&(e.preventDefault(),N(f,e));return}let a=e.target?.closest?.("[data-dialog-open]");if(a){let m=document.getElementById(a.dataset.dialogOpen);m?.showModal&&(e.preventDefault(),m.showModal());return}let n=e.target?.closest?.("[data-dialog-close]");if(n){let m=n.closest("dialog");m&&(e.preventDefault(),m.close());return}if(e.target?.tagName==="DIALOG"){e.target.close();return}let h=e.target?.closest?.("[data-event]");if(!h)return;let[y,d]=A(h.dataset.event);y==="click"&&(e.preventDefault(),o(d,e))},s),t.addEventListener("change",e=>{let i=e.target?.closest?.("[data-store-event]");if(i){let[y,d]=A(i.dataset.storeEvent);y==="change"&&N(d,e);return}let a=e.target?.closest?.("[data-event]");if(!a)return;let[n,h]=A(a.dataset.event);n==="change"&&I(a,h,e,o)},s),t.addEventListener("input",e=>{let i=e.target?.closest?.("[data-store-event]");if(i){let[y,d]=A(i.dataset.storeEvent);y==="input"&&N(d,e);return}let a=e.target?.closest?.("[data-event]");if(!a)return;let[n,h]=A(a.dataset.event);n==="input"&&I(a,h,e,o)},s),t.addEventListener("submit",e=>{let i=e.target?.closest?.("[data-action]");i&&(e.preventDefault(),o(i.dataset.action,new FormData(i)),i.hasAttribute("data-reset")&&i.reset())},s)}function et(t,o){if(typeof document>"u"){t.innerHTML=o;return}let r=document.createElement("div");r.innerHTML=o,O(t,r)}function O(t,o){let r=Array.from(o.childNodes),s=r.filter(i=>i.nodeType===1);if(s.length>0&&s.every(i=>i.getAttribute("data-key")!==null)){nt(t,s);return}let e=Array.from(t.childNodes);for(r.forEach((i,a)=>{let n=e[a];if(!n){t.appendChild(i.cloneNode(!0));return}if(n.nodeType!==i.nodeType||n.nodeName!==i.nodeName){t.replaceChild(i.cloneNode(!0),n);return}if(i.nodeType===3){n.nodeValue!==i.nodeValue&&(n.nodeValue=i.nodeValue);return}i.nodeType===1&&(B(n,i),O(n,i))});t.childNodes.length>r.length;)t.removeChild(t.lastChild)}function nt(t,o){let r=new Map;for(let e of t.childNodes)if(e.nodeType===1){let i=e.getAttribute("data-key");i!==null&&r.set(i,e)}let s=null;for(let e=o.length-1;e>=0;e--){let i=o[e],a=i.getAttribute("data-key"),n=r.get(a);n?(r.delete(a),B(n,i),O(n,i)):n=i.cloneNode(!0),(n.nextSibling!==s||n.parentNode!==t)&&t.insertBefore(n,s),s=n}for(let e of r.values())t.removeChild(e)}function B(t,o){for(let{name:r,value:s}of Array.from(o.attributes))t.getAttribute(r)!==s&&t.setAttribute(r,s);for(let{name:r}of Array.from(t.attributes))o.hasAttribute(r)||t.removeAttribute(r)}function A(t){let o=t.split(":");return o.length===1?["click",o[0]]:[o[0],o[1]]}function I(t,o,r,s){let e=parseInt(t.dataset.debounce,10);if(e>0){J(t,"d",o,e,a=>s(o,a))(r);return}let i=parseInt(t.dataset.throttle,10);if(i>0){J(t,"t",o,i,a=>s(o,a))(r);return}s(o,r)}function x(t,o){if(!o)return t;let s=Object.keys(o).some(e=>e.includes("."))?structuredClone(t):t;for(let[e,i]of Object.entries(o)){let{obj:a,key:n}=F(s,e);a===null||a[n]===void 0||(i.min!==void 0&&typeof a[n]=="number"&&(a[n]=Math.max(a[n],i.min)),i.max!==void 0&&typeof a[n]=="number"&&(a[n]=Math.min(a[n],i.max)))}return s}function rt(t,o){if(!o)return[];let r=[];for(let[s,e]of Object.entries(o)){let{obj:i,key:a}=F(t,s),n=i?.[a];if(e.required&&!n){r.push({path:s,rule:"required",message:`${s} is required`});continue}n==null||n===""||(e.minLength!==void 0&&String(n).length<e.minLength&&r.push({path:s,rule:"minLength",message:`${s} must be at least ${e.minLength} characters`}),e.maxLength!==void 0&&String(n).length>e.maxLength&&r.push({path:s,rule:"maxLength",message:`${s} must be no more than ${e.maxLength} characters`}),e.min!==void 0&&Number(n)<e.min&&r.push({path:s,rule:"min",message:`${s} must be at least ${e.min}`}),e.max!==void 0&&Number(n)>e.max&&r.push({path:s,rule:"max",message:`${s} must be no more than ${e.max}`}),e.format==="email"&&!st(String(n))&&r.push({path:s,rule:"format",message:`${s} must be a valid email address`}),e.format==="url"&&!ut(String(n))&&r.push({path:s,rule:"format",message:`${s} must be a valid URL`}),e.format==="numeric"&&isNaN(Number(n))&&r.push({path:s,rule:"format",message:`${s} must be numeric`}),e.pattern&&!e.pattern.test(String(n))&&r.push({path:s,rule:"pattern",message:`${s} does not match the required format`}))}return r}function F(t,o){let r=o.split("."),s=r.pop(),e=t;for(let i of r){if(e==null||typeof e!="object")return{obj:null,key:s};e=e[i]}return{obj:e,key:s}}function z(t){return structuredClone(t)}function $(t,o){if(t===o)return!1;let r=Object.keys(t);return r.length!==Object.keys(o).length?!0:r.some(s=>t[s]!==o[s])}function ot(t){return`<div style="padding:1rem;color:#b91c1c;background:#fef2f2;border:1px solid #fca5a5;border-radius:.375rem;font-family:monospace;font-size:.875rem"><strong>View error</strong>${t?.message?`: ${t.message}`:""}</div>`}function st(t){return/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(t)}var j=new WeakMap;function J(t,o,r,s,e){j.has(t)||j.set(t,{});let i=j.get(t),a=`${o}:${r}:${s}`;return i[a]||(i[a]=o==="d"?it(e,s):at(e,s)),i[a]}function it(t,o){let r;return function(...s){clearTimeout(r),r=setTimeout(()=>t(...s),o)}}function at(t,o){let r=0;return function(...s){let e=Date.now();e-r>=o&&(r=e,t(...s))}}function ut(t){try{return new URL(t),!0}catch{return!1}}function mt(t,o){history.replaceState({pulse:!0,path:location.pathname},"",location.pathname);let r=null;async function s(e,i){try{let a=await fetch(e,{headers:{"X-Pulse-Navigate":"true"}});if(!a.ok){location.href=e;return}if((a.headers.get("content-type")||"").includes("application/x-ndjson")){let h=a.body.getReader(),y=new TextDecoder,d="",m=null,f={},S=new Map,b=async v=>{if(!v.trim())return;let l=JSON.parse(v);if(l.type==="meta")m=l.hydrate,document.title=l.title||document.title,G(l.styles),await X(l.scripts);else if(l.type==="html"){t.innerHTML=l.html;for(let u of l.deferred||[]){let c=t.querySelector(`[id="pd-${u}"]`);c&&S.set(u,c)}i&&history.pushState({pulse:!0,path:e},"",e),Q(t)}else if(l.type==="deferred"){let u=S.get(l.id);if(u){let c=document.createElement("div");c.innerHTML=l.html,u.replaceWith(...c.childNodes),S.delete(l.id)}}else l.type==="done"&&(l.storeState&&window.__updatePulseStore__&&window.__updatePulseStore__(l.storeState),f=l.serverState||{})};for(;;){let{done:v,value:l}=await h.read();if(v)break;d+=y.decode(l,{stream:!0});let u=d.split(`
+`);d=u.pop();for(let c of u)await b(c)}if(d&&await b(d),W(t),document.dispatchEvent(new CustomEvent("pulse:navigate")),m&&o){r?.destroy(),t.dataset.pulseMounted="1",window.__PULSE_SERVER__=f;let{default:v}=await import(m);v&&(r=o(v,t,f))}}else{let{html:h,title:y,styles:d,scripts:m,hydrate:f,serverState:S,storeState:b}=await a.json();if(b&&window.__updatePulseStore__&&window.__updatePulseStore__(b),t.innerHTML=h,document.title=y||document.title,G(d),await X(m),W(t),i&&history.pushState({pulse:!0,path:e},"",e),f&&o){r?.destroy(),t.dataset.pulseMounted="1",window.__PULSE_SERVER__=S||{};let{default:v}=await import(f);v&&(r=o(v,t,S||{}))}document.dispatchEvent(new CustomEvent("pulse:navigate")),Q(t)}}catch{location.href=e}}return document.addEventListener("click",e=>{let i=e.target.closest("a");if(!i)return;let a=i.getAttribute("href");if(!a)return;let n;try{n=new URL(a,location.origin)}catch{return}n.origin===location.origin&&(e.ctrlKey||e.metaKey||e.shiftKey||e.altKey||i.target&&i.target!=="_self"||(e.preventDefault(),s(n.pathname+n.search,!0)))}),window.addEventListener("popstate",e=>{e.state?.pulse&&s(location.pathname+location.search,!1)}),{setMount:e=>{r=e}}}function W(t){t.querySelectorAll("script:not([src])").forEach(o=>{let r=document.createElement("script");r.textContent=o.textContent,document.head.appendChild(r),r.remove()})}function G(t){if(!Array.isArray(t))return;let o=new Set([...document.querySelectorAll('link[rel="stylesheet"]')].map(r=>r.getAttribute("href")));for(let r of t)if(!o.has(r)){let s=document.createElement("link");s.rel="stylesheet",s.href=r,document.head.appendChild(s)}}function X(t){if(!Array.isArray(t))return Promise.resolve();let o=new Set([...document.querySelectorAll("script[src]")].map(r=>r.getAttribute("src")));return Promise.all(t.filter(r=>!o.has(r)).map(r=>new Promise(s=>{let e=document.createElement("script");e.src=r,e.onload=s,e.onerror=s,document.head.appendChild(e)})))}function Q(t){window.scrollTo({top:0,behavior:"instant"});let o=t.querySelector("#main-content, main, h1")||t;o.hasAttribute("tabindex")||(o.setAttribute("tabindex","-1"),o.addEventListener("blur",()=>o.removeAttribute("tabindex"),{once:!0})),o.focus({preventScroll:!0})}export{ft as a,mt as b};

package/benchmark/public/dist/runtime-KO4BHUQ3.js

@@ -0,0 +1,49 @@
+var l="pulse-toasts";var m=new Set(["success","error","warning","info"]),p=`
+#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; }
+`,c=!1;function f(){if(c)return;c=!0;let e=document.createElement("style");e.textContent=p,document.head.appendChild(e)}function g(){let e=document.getElementById(l);return e||(f(),e=document.createElement("div"),e.id=l,e.setAttribute("aria-live","polite"),e.setAttribute("aria-atomic","false"),document.body.appendChild(e)),e}function b(e){if(typeof document>"u")return;let{message:a,variant:i="info",duration:r=4e3}=typeof e=="string"?{message:e}:e;if(!a)return;let u=m.has(i)?i:"info",n=g();for(;n.children.length>=5;)n.firstElementChild?.remove();let t=document.createElement("div");t.className=`pulse-toast pulse-toast--${u}`,t.setAttribute("role","status");let o=document.createElement("span");o.className="pulse-toast-message",o.textContent=a;let s=document.createElement("button");s.className="pulse-toast-close",s.setAttribute("aria-label","Dismiss notification"),s.textContent="\xD7",s.addEventListener("click",()=>d(t)),t.appendChild(o),t.appendChild(s),n.appendChild(t),requestAnimationFrame(()=>t.classList.add("pulse-toast--visible")),r>0&&setTimeout(()=>d(t),r)}function d(e){e.classList.remove("pulse-toast--visible"),e.addEventListener("transitionend",()=>e.remove(),{once:!0})}export{b as showToast};

package/benchmark/src/pages/counter.js

@@ -0,0 +1,37 @@
+/**
+ * Benchmark page — interactive counter with server data.
+ * Represents a typical SPA page: runtime + mutations + server fetcher.
+ */
+export default {
+  route: '/counter',
+  hydrate: '/src/pages/counter.js',
+
+  meta: {
+    title: 'Counter — Pulse Benchmark',
+    styles: ['/pulse.css'],
+  },
+
+  state: { count: 0 },
+
+  constraints: {
+    count: { min: 0, max: 10 },
+  },
+
+  server: {
+    greeting: async () => 'Hello from the server',
+  },
+
+  mutations: {
+    increment: (state) => ({ count: state.count + 1 }),
+    decrement: (state) => ({ count: state.count - 1 }),
+  },
+
+  view: (state, server) => `
+    <main id="main-content">
+      <p>${server.greeting}</p>
+      <p>Count: ${state.count}</p>
+      <button data-event="decrement">−</button>
+      <button data-event="increment">+</button>
+    </main>
+  `,
+}

package/benchmark/src/pages/home.js

@@ -0,0 +1,21 @@
+/**
+ * Benchmark page — static page, no client JS.
+ * Represents a content page with no hydration.
+ */
+export default {
+  route: '/home',
+
+  meta: {
+    title: 'Home — Pulse Benchmark',
+    styles: ['/pulse.css'],
+  },
+
+  state: {},
+
+  view: () => `
+    <main id="main-content">
+      <h1>Pulse Benchmark</h1>
+      <p>Static page — no client-side interactivity.</p>
+    </main>
+  `,
+}

package/docs/src/lib/stats.js

@@ -47,11 +47,11 @@ function fmt(kb, fallback) {
   return (kb != null) ? kb.toFixed(kb < 1 ? 2 : 1) : fallback
 }
 
-const runtimeKb  = fmt(bundles?.runtimeKb,  '3.1')
+const runtimeKb  = fmt(bundles?.runtimeKb,  '3.8')
 const firstVisit = bundles?.runtimeKb && bundles?.pageBootKb
   ? (bundles.runtimeKb + bundles.pageBootKb).toFixed(1)
-  : '3.5'
-const pageNavKb  = fmt(bundles?.pageBootKb,  '0.35')
+  : '4.2'
+const pageNavKb  = fmt(bundles?.pageBootKb,  '0.4')
 
 export const metrics = {
   generatedAt: new Date().toLocaleString('en-GB', { dateStyle: 'medium', timeStyle: 'short' }),

package/docs/src/pages/faq.js

@@ -45,7 +45,7 @@ export default {
       ${q(
         'Why no virtual DOM?',
         `<p>A virtual DOM solves the problem of efficient incremental updates to a large, complex component tree. Pulse pages are server-rendered HTML strings — the client runtime re-renders a bounded section of the page when state changes, which is fast enough for the kinds of interactions Pulse is designed for.</p>
-        <p>Eliminating the virtual DOM means eliminating the ~40–100 kB runtime that comes with it. Pulse ships ~3.5 kB brotli to the browser on first visit (shared runtime + page bundle). That is not a compression trick — there is genuinely no framework runtime on the client.</p>`
+        <p>Eliminating the virtual DOM means eliminating the ~40–100 kB runtime that comes with it. Pulse ships ~4 kB brotli to the browser on first visit (shared runtime + page bundle). That is not a compression trick — there is genuinely no framework runtime on the client.</p>`
       )}
 
       ${q(

package/docs/src/pages/getting-started.js

@@ -23,6 +23,7 @@ export default {
       ${section('requirements', 'Requirements')}
       <ul>
         <li><strong>Node.js 22 or later</strong> — <a href="https://nodejs.org" target="_blank" rel="noopener" aria-label="nodejs.org (opens in new tab)">nodejs.org</a></li>
+        <li><strong>Google Chrome</strong> — used by the agent for screenshots and Lighthouse audits — <a href="https://www.google.com/chrome" target="_blank" rel="noopener" aria-label="Download Google Chrome (opens in new tab)">google.com/chrome</a></li>
         <li><strong>Claude Code</strong> — the CLI for Claude, installed and authenticated — <a href="https://docs.anthropic.com/en/docs/claude-code/getting-started" target="_blank" rel="noopener" aria-label="Claude Code installation guide (opens in new tab)">installation guide</a></li>
       </ul>
       <p>Claude Code provides the <code>claude</code> command. Pulse launches it automatically with the Pulse MCP server wired in — so the agent has instant access to the framework reference, your project structure, and all Pulse tools without any manual configuration.</p>

package/docs/src/pages/home.js

@@ -83,7 +83,7 @@ export default {
         </div>
         <div class="home-stat-divider"></div>
         <div class="home-stat">
-          <span class="home-stat-value">3.5 kB</span>
+          <span class="home-stat-value">4 kB</span>
           <span class="home-stat-label">Runtime JS, first visit (brotli)</span>
         </div>
         <div class="home-stat-divider"></div>
@@ -200,7 +200,7 @@ export default {
               </tr>
               <tr>
                 <th scope="row">Client JS shipped</th>
-                <td class="v-yes">3.5 kB brotli (shared runtime, first visit)</td>
+                <td class="v-yes">~4 kB brotli (shared runtime, first visit)</td>
                 <td class="v-no">50-200 kB+ depending on features</td>
                 <td class="v-partial">~15 kB brotli</td>
               </tr>
@@ -251,8 +251,8 @@ export default {
               The shell renders and streams instantly. Deferred segments arrive as data resolves — no blocking, no flash.
             </li>
             <li>
-              <strong>3.5 kB of JS on first visit.</strong>
-              The shared runtime is brotli-compressed and cached across all navigations. Subsequent pages cost 0.35–0.5 kB.
+              <strong>~4 kB of JS on first visit.</strong>
+              The shared runtime is brotli-compressed and cached across all navigations. Subsequent pages cost 0.4–0.9 kB.
             </li>
             <li>
               <strong>Zero CLS.</strong>

package/docs/src/pages/hydration.js

@@ -54,8 +54,8 @@ export default {
       <p>Run <code>npm run build</code> to generate production bundles. This creates content-hashed files in <code>public/dist/</code> and a <code>manifest.json</code> mapping spec hydrate paths to bundle paths.</p>
       ${codeBlock(highlight(`# Generated by npm run build
 public/dist/
-  runtime-abc123.js          # shared runtime (~2.1 kB brotli)
-  counter.boot-def456.js     # per-page spec bundle (~0.5 kB brotli)
+  runtime-abc123.js          # shared runtime (~3.8 kB brotli)
+  counter.boot-def456.js     # per-page spec bundle (~0.4–0.9 kB brotli)
   manifest.json              # { '/src/pages/counter.js': '/dist/counter.boot-def456.js' }`, 'bash'))}
       <p>When Pulse detects a manifest (via <code>staticDir</code> auto-detection or explicit <code>manifest</code> option), it resolves the <code>hydrate</code> path to the bundle path and emits a single <code>&lt;script src&gt;</code> tag instead of the inline bootstrap:</p>
       ${codeBlock(highlight(`<script type="module" src="/dist/counter.boot-def456.js"></script>`, 'html'))}

package/docs/src/pages/performance.js

@@ -93,15 +93,15 @@ export default {
       ${table(
         ['App size', 'What the boot file contains', 'Size (brotli)'],
         [
-          ['Single page', 'Your spec + the full Pulse runtime bundled together', '~3.5 kB'],
-          ['Multiple pages', 'Your spec only — runtime is in a separate <code>runtime-[hash].js</code> chunk', '~0.35–0.5 kB'],
+          ['Single page', 'Your spec + the full Pulse runtime bundled together', '~4 kB'],
+          ['Multiple pages', 'Your spec only — runtime is in a separate <code>runtime-[hash].js</code> chunk', '~0.4–0.9 kB'],
         ]
       )}
       <p>With multiple pages, esbuild's code splitting extracts the Pulse runtime into a shared chunk because every page imports it. The browser downloads it once and caches it — subsequent page navigations only fetch the small per-page boot file.</p>
       <p><strong>What you see in the network tab across navigations:</strong></p>
       <ul>
-        <li><strong>First page visit</strong> — <code>runtime-[hash].js</code> (~3.1 kB) + <code>home.boot-[hash].js</code> (~0.35 kB)</li>
-        <li><strong>Navigate to another page</strong> — <code>contact.boot-[hash].js</code> (~0.47 kB) only. Runtime already cached.</li>
+        <li><strong>First page visit</strong> — <code>runtime-[hash].js</code> (~3.8 kB) + <code>home.boot-[hash].js</code> (~0.4 kB)</li>
+        <li><strong>Navigate to another page</strong> — <code>contact.boot-[hash].js</code> (~0.5 kB) only. Runtime already cached.</li>
         <li><strong>Return visit</strong> — nothing. Both files served from cache with <code>immutable</code> headers.</li>
       </ul>
       ${callout('tip', 'The runtime hash only changes when the Pulse runtime itself is updated — not when your app changes. Deploying new pages or mutations does not bust the runtime cache for returning visitors.')}

package/package.json

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

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.2.0
+0.2.2

package/scripts/build.js

@@ -20,6 +20,222 @@ import { createHash } from 'crypto'
 import { discoverPages } from '../src/cli/discover.js'
 import { renderToString } from '../src/runtime/ssr.js'
 
+// ---------------------------------------------------------------------------
+// Server-only property stripping
+// ---------------------------------------------------------------------------
+
+/**
+ * These spec properties are resolved and used exclusively on the server.
+ * Stripping them from the client bundle:
+ *   - reduces bundle size
+ *   - prevents server-only imports (DB clients, Node built-ins, internal APIs)
+ *     from being shipped to and evaluated in the browser
+ *   - avoids bundling errors when server imports use Node-only modules
+ */
+const SERVER_ONLY_KEYS = ['server', 'guard', 'serverTimeout', 'contentType', 'render']
+
+/**
+ * Strip all server-only property declarations from a spec source string.
+ * Matches properties at the start of a line (after optional whitespace) —
+ * the standard formatting for Pulse spec files.
+ */
+function stripServerOnlyKeys(source) {
+  for (const key of SERVER_ONLY_KEYS) {
+    source = removeObjectKey(source, key)
+  }
+  return source
+}
+
+/**
+ * Remove a single named property (key + value + optional trailing comma/newline)
+ * from a JS source string. Uses a character-level scanner to correctly handle
+ * nested structures, string literals, template literals, and function expressions.
+ */
+function removeObjectKey(source, key) {
+  const keyRe = new RegExp(`^([ \\t]*)(${key})([ \\t]*:)`, 'gm')
+  let match
+
+  while ((match = keyRe.exec(source)) !== null) {
+    const removeStart = match.index                    // start of indentation
+    const afterColon  = match.index + match[0].length // character after ':'
+
+    // Skip whitespace between ':' and value
+    let pos = afterColon
+    while (pos < source.length && (source[pos] === ' ' || source[pos] === '\t')) pos++
+
+    // Scan past the full value
+    pos = scanJsValue(source, pos)
+
+    // Consume optional trailing comma and newline
+    while (pos < source.length && (source[pos] === ' ' || source[pos] === '\t')) pos++
+    if (pos < source.length && source[pos] === ',') pos++
+    if (pos < source.length && source[pos] === '\n') pos++
+
+    source = source.slice(0, removeStart) + source.slice(pos)
+    keyRe.lastIndex = removeStart
+  }
+
+  return source
+}
+
+/**
+ * Scan a JS value starting at `pos`, returning the index just past it.
+ *
+ * Correctly handles:
+ *   - Object / array / group literals:  { }  [ ]  ( )
+ *   - Arrow functions:  (params) => expr  or  (params) => { body }
+ *   - Function expressions:  function(params) { body }  /  async function ...
+ *   - String literals:  '...'  "..."
+ *   - Template literals:  `...${expr}...`
+ *   - Line and block comments
+ *   - Simple values (numbers, booleans, identifiers, null/undefined)
+ *
+ * Stops when it finds a comma or closing delimiter at depth 0 that is NOT
+ * followed by a continuation (arrow `=>`, method call `.`, etc.).
+ */
+function scanJsValue(src, pos) {
+  let i     = pos
+  let depth = 0
+
+  while (i < src.length) {
+    const c = src[i]
+
+    // ---- Line comment -------------------------------------------------------
+    if (c === '/' && src[i + 1] === '/') {
+      while (i < src.length && src[i] !== '\n') i++
+      continue
+    }
+
+    // ---- Block comment ------------------------------------------------------
+    if (c === '/' && src[i + 1] === '*') {
+      const end = src.indexOf('*/', i + 2)
+      i = end < 0 ? src.length : end + 2
+      continue
+    }
+
+    // ---- String literals ----------------------------------------------------
+    if (c === '"' || c === "'") {
+      i++
+      while (i < src.length) {
+        if (src[i] === '\\') { i += 2; continue }
+        if (src[i] === c)    { i++; break }
+        i++
+      }
+      if (depth === 0) return i
+      continue
+    }
+
+    // ---- Template literals --------------------------------------------------
+    if (c === '`') {
+      i = scanTemplateLiteral(src, i + 1)
+      if (depth === 0) return i
+      continue
+    }
+
+    // ---- Open delimiters ----------------------------------------------------
+    if (c === '{' || c === '[' || c === '(') {
+      depth++
+      i++
+      continue
+    }
+
+    // ---- Close delimiters ---------------------------------------------------
+    if (c === '}' || c === ']' || c === ')') {
+      if (depth === 0) {
+        // Hit the parent structure's closing delimiter — stop, don't consume
+        return i
+      }
+      depth--
+      i++
+      if (depth === 0) {
+        // Just closed a top-level nested block — peek ahead to see if this is
+        // the end of the value or if the expression continues.
+        let j = i
+        while (j < src.length && (src[j] === ' ' || src[j] === '\t')) j++
+        const next = src[j]
+        // Terminator characters — value is complete
+        if (!next || next === ',' || next === '}' || next === ']' || next === ')' || next === '\n') {
+          return i
+        }
+        // Arrow function body follows:  (params) => ...
+        if (next === '=' && src[j + 1] === '>') continue
+        // Anything else (method chain, ternary, etc.) — keep scanning
+        continue
+      }
+      continue
+    }
+
+    // ---- Terminators at top level -------------------------------------------
+    if (depth === 0) {
+      if (c === ',')  return i
+      if (c === '\n') return i
+    }
+
+    i++
+  }
+
+  return i
+}
+
+/**
+ * Scan a template literal body (starting just after the opening backtick).
+ * Returns the index just past the closing backtick.
+ * Handles `${...}` expression blocks including nested strings and templates.
+ */
+function scanTemplateLiteral(src, pos) {
+  let i = pos
+  while (i < src.length) {
+    if (src[i] === '\\') { i += 2; continue }
+    if (src[i] === '`')  { return i + 1 }
+    if (src[i] === '$' && src[i + 1] === '{') {
+      i += 2
+      let depth = 1
+      while (i < src.length && depth > 0) {
+        const c = src[i]
+        if (c === '{') { depth++; i++; continue }
+        if (c === '}') { depth--; i++; continue }
+        if (c === '"' || c === "'") {
+          const q = c; i++
+          while (i < src.length) {
+            if (src[i] === '\\') { i += 2; continue }
+            if (src[i] === q)    { i++; break }
+            i++
+          }
+          continue
+        }
+        if (c === '`') { i = scanTemplateLiteral(src, i + 1); continue }
+        i++
+      }
+      continue
+    }
+    i++
+  }
+  return i
+}
+
+/**
+ * esbuild plugin — strips server-only spec properties before bundling.
+ * Only transforms files under src/pages/ to avoid touching runtime/server code.
+ *
+ * @param {string} pagesDir  Absolute path to src/pages/
+ */
+function createStripServerPlugin(pagesDir) {
+  return {
+    name: 'pulse-strip-server',
+    setup(build) {
+      build.onLoad({ filter: /\.js$/ }, (args) => {
+        if (!args.path.startsWith(pagesDir + path.sep) &&
+            args.path !== pagesDir.replace(/\/$/, '') + '.js') return undefined
+
+        const source   = fs.readFileSync(args.path, 'utf8')
+        const stripped = stripServerOnlyKeys(source)
+        return { contents: stripped, loader: 'js' }
+      })
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
 // Project root — can be overridden via --root flag for CLI usage
 const rootArg = process.argv.indexOf('--root')
 const ROOT    = rootArg !== -1
@@ -105,6 +321,7 @@ const result = await esbuild.build({
   metafile:    true,
   sourcemap:   false,
   treeShaking: true,
+  plugins:     [createStripServerPlugin(PAGES_DIR)],
   define: {
     'process.env.NODE_ENV': '"production"'
   }

package/scripts/strip-server.test.js

@@ -0,0 +1,187 @@
+/**
+ * Tests for the server-only property stripper in build.js
+ * Run: node scripts/strip-server.test.js
+ */
+
+// ---------------------------------------------------------------------------
+// Inline the scanner functions (duplicated here to keep test self-contained)
+// ---------------------------------------------------------------------------
+
+const SERVER_ONLY_KEYS = ['server', 'guard', 'serverTimeout', 'contentType', 'render']
+
+function stripServerOnlyKeys(source) {
+  for (const key of SERVER_ONLY_KEYS) source = removeObjectKey(source, key)
+  return source
+}
+
+function removeObjectKey(source, key) {
+  const keyRe = new RegExp(`^([ \\t]*)(${key})([ \\t]*:)`, 'gm')
+  let match
+  while ((match = keyRe.exec(source)) !== null) {
+    const removeStart = match.index
+    const afterColon  = match.index + match[0].length
+    let pos = afterColon
+    while (pos < source.length && (source[pos] === ' ' || source[pos] === '\t')) pos++
+    pos = scanJsValue(source, pos)
+    while (pos < source.length && (source[pos] === ' ' || source[pos] === '\t')) pos++
+    if (pos < source.length && source[pos] === ',') pos++
+    if (pos < source.length && source[pos] === '\n') pos++
+    source = source.slice(0, removeStart) + source.slice(pos)
+    keyRe.lastIndex = removeStart
+  }
+  return source
+}
+
+function scanJsValue(src, pos) {
+  let i = pos, depth = 0
+  while (i < src.length) {
+    const c = src[i]
+    if (c === '/' && src[i + 1] === '/') { while (i < src.length && src[i] !== '\n') i++; continue }
+    if (c === '/' && src[i + 1] === '*') { const e = src.indexOf('*/', i + 2); i = e < 0 ? src.length : e + 2; continue }
+    if (c === '"' || c === "'") {
+      i++
+      while (i < src.length) { if (src[i] === '\\') { i += 2; continue } if (src[i] === c) { i++; break } i++ }
+      if (depth === 0) return i
+      continue
+    }
+    if (c === '`') { i = scanTemplateLiteral(src, i + 1); if (depth === 0) return i; continue }
+    if (c === '{' || c === '[' || c === '(') { depth++; i++; continue }
+    if (c === '}' || c === ']' || c === ')') {
+      if (depth === 0) return i
+      depth--; i++
+      if (depth === 0) {
+        let j = i
+        while (j < src.length && (src[j] === ' ' || src[j] === '\t')) j++
+        const next = src[j]
+        if (!next || next === ',' || next === '}' || next === ']' || next === ')' || next === '\n') return i
+        if (next === '=' && src[j + 1] === '>') continue
+        continue
+      }
+      continue
+    }
+    if (depth === 0 && (c === ',' || c === '\n')) return i
+    i++
+  }
+  return i
+}
+
+function scanTemplateLiteral(src, pos) {
+  let i = pos
+  while (i < src.length) {
+    if (src[i] === '\\') { i += 2; continue }
+    if (src[i] === '`')  { return i + 1 }
+    if (src[i] === '$' && src[i + 1] === '{') {
+      i += 2; let depth = 1
+      while (i < src.length && depth > 0) {
+        const c = src[i]
+        if (c === '{') { depth++; i++; continue }
+        if (c === '}') { depth--; i++; continue }
+        if (c === '"' || c === "'") { const q = c; i++; while (i < src.length) { if (src[i] === '\\') { i += 2; continue } if (src[i] === q) { i++; break } i++ } continue }
+        if (c === '`') { i = scanTemplateLiteral(src, i + 1); continue }
+        i++
+      }
+      continue
+    }
+    i++
+  }
+  return i
+}
+
+// ---------------------------------------------------------------------------
+// Test runner
+// ---------------------------------------------------------------------------
+
+let pass = 0, fail = 0
+
+function test(label, input, expected) {
+  const got = stripServerOnlyKeys(input).trim()
+  const exp = expected.trim()
+  if (got === exp) {
+    console.log('  \u2713 ' + label)
+    pass++
+  } else {
+    console.log('  \u2717 ' + label)
+    console.log('    expected: ' + JSON.stringify(exp))
+    console.log('    got:      ' + JSON.stringify(got))
+    fail++
+  }
+}
+
+// ---------------------------------------------------------------------------
+
+console.log('\nServer-only key stripping\n')
+
+test('object value with trailing comma',
+  `export default {\n  route: '/',\n  server: { data: async (ctx) => 'hello' },\n  view: () => ''\n}`,
+  `export default {\n  route: '/',\n  view: () => ''\n}`
+)
+
+test('async arrow with block body',
+  `export default {\n  server: {\n    data: async (ctx) => {\n      return 'x'\n    }\n  },\n  view: () => ''\n}`,
+  `export default {\n  view: () => ''\n}`
+)
+
+test('serverTimeout simple number',
+  `export default {\n  serverTimeout: 5000,\n  view: () => ''\n}`,
+  `export default {\n  view: () => ''\n}`
+)
+
+test('guard async arrow with block body containing nested object',
+  `export default {\n  guard: async (ctx) => {\n    if (!ctx.session) return { redirect: '/login' }\n  },\n  view: () => ''\n}`,
+  `export default {\n  view: () => ''\n}`
+)
+
+test('guard inline arrow expression',
+  `export default {\n  guard: async (ctx) => { if (!ctx.session) return { redirect: '/login' } },\n  view: () => ''\n}`,
+  `export default {\n  view: () => ''\n}`
+)
+
+test('contentType and render are both stripped (raw content specs are never hydrated)',
+  `export default {\n  route: '/feed.xml',\n  contentType: 'application/rss+xml',\n  render: (ctx) => '<rss/>'\n}`,
+  `export default {\n  route: '/feed.xml',\n}`
+)
+
+test('render with template literal containing ${...}',
+  'export default {\n  render: (ctx, srv) => `<rss>${srv.items.map(i => i.title).join(\',\')}</rss>`,\n  view: () => \'\'\n}',
+  "export default {\n  view: () => ''\n}"
+)
+
+test('last property — no trailing comma',
+  `export default {\n  view: () => '',\n  server: { data: async () => [] }\n}`,
+  `export default {\n  view: () => '',\n}`
+)
+
+test('multiple fetchers in server object',
+  `export default {\n  server: {\n    user: async (ctx) => ctx.user,\n    posts: async (ctx) => []\n  },\n  view: () => ''\n}`,
+  `export default {\n  view: () => ''\n}`
+)
+
+test('does not strip non-server keys',
+  `export default {\n  route: '/',\n  state: {},\n  view: () => ''\n}`,
+  `export default {\n  route: '/',\n  state: {},\n  view: () => ''\n}`
+)
+
+test('strips all server-only keys in one pass',
+  `export default {\n  route: '/admin',\n  guard: async (ctx) => { if (!ctx.user) return { redirect: '/login' } },\n  serverTimeout: 3000,\n  server: { profile: async (ctx) => ctx.user },\n  view: () => ''\n}`,
+  `export default {\n  route: '/admin',\n  view: () => ''\n}`
+)
+
+test('does not touch "server" inside a view string',
+  `export default {\n  view: (state, server) => \`<p>\${server.name}</p>\`\n}`,
+  `export default {\n  view: (state, server) => \`<p>\${server.name}</p>\`\n}`
+)
+
+test('async function expression (not arrow)',
+  `export default {\n  server: {\n    data: async function(ctx) { return ctx.db.query() }\n  },\n  view: () => ''\n}`,
+  `export default {\n  view: () => ''\n}`
+)
+
+test('server with deeply nested template literal in view is not affected',
+  'export default {\n  server: { items: async () => [] },\n  view: (s, srv) => `<ul>${srv.items.map(i => `<li>${i}</li>`).join(\'\')}</ul>`\n}',
+  'export default {\n  view: (s, srv) => `<ul>${srv.items.map(i => `<li>${i}</li>`).join(\'\')}</ul>`\n}'
+)
+
+// ---------------------------------------------------------------------------
+
+console.log(`\n${pass + fail} tests: ${pass} passed, ${fail} failed\n`)
+if (fail > 0) process.exit(1)