@invisibleloop/pulse 0.4.0 → 0.5.1

package/CLAUDE.md

@@ -35,7 +35,7 @@ public/
 
 ## The Spec
 
-A spec is a plain JS object. Every property is optional except `route`, `state`, and `view`.
+A spec is a plain JS object. Every property is optional except `route` and `view`. `state` defaults to `{}` — omit it on purely server-rendered pages.
 
 ```js
 export const mySpec = {
@@ -62,6 +62,7 @@ export const mySpec = {
   store: ['user', 'cart'],
 
   // Initial client state — deep cloned on mount, never mutated directly
+  // Optional — omit entirely on purely server-rendered pages (no mutations/actions/persist)
   state: { count: 0 },
 
   // Declarative min/max bounds — always enforced after mutations

package/docs/src/pages/accessibility.js

@@ -11,7 +11,6 @@ export default {
     description: 'Keyboard navigation, focus management, semantic HTML, and ARIA patterns in Pulse.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/accessibility',
     prev,

package/docs/src/pages/auth.js

@@ -11,7 +11,6 @@ export default {
     description: 'Integrating Auth0 OAuth authentication with Pulse using guard functions, ctx.setCookie, and raw response specs.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/auth',
     prev,
@@ -141,7 +140,6 @@ export default {
     profile: async (ctx) => fetchUserProfile(ctx.cookies.session),
   },
 
-  state: {},
   view: (state, server) => \`
     <main id="main-content">
       <h1>Welcome, \${server.profile.name}</h1>

package/docs/src/pages/caching.js

@@ -11,7 +11,6 @@ export default {
     description: 'HTTP cache headers, in-process server data caching, and asset caching in Pulse.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/caching',
     prev,

package/docs/src/pages/components/accordion.js

@@ -12,7 +12,6 @@ export default {
     description: 'Accordion component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/accordion',
     prev,

package/docs/src/pages/components/alert.js

@@ -11,7 +11,6 @@ export default {
     description: 'Alert component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/alert',
     prev,

package/docs/src/pages/components/app-badge.js

@@ -12,7 +12,6 @@ export default {
     description: 'App Badge component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/app-badge',
     prev,

package/docs/src/pages/components/avatar.js

@@ -11,7 +11,6 @@ export default {
     description: 'Avatar component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/avatar',
     prev,

package/docs/src/pages/components/badge.js

@@ -11,7 +11,6 @@ export default {
     description: 'Badge component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/badge',
     prev,

package/docs/src/pages/components/banner.js

@@ -12,7 +12,6 @@ export default {
     description: 'Banner component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/banner',
     prev,

package/docs/src/pages/components/breadcrumbs.js

@@ -12,7 +12,6 @@ export default {
     description: 'Accessible breadcrumb navigation component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/breadcrumbs',
     prev,

package/docs/src/pages/components/button.js

@@ -13,7 +13,6 @@ export default {
     description: 'Button component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/button',
     prev,

package/docs/src/pages/components/card.js

@@ -12,7 +12,6 @@ export default {
     description: 'Card component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/card',
     prev,

package/docs/src/pages/components/carousel.js

@@ -16,7 +16,6 @@ export default {
     description: 'Carousel / slider component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/carousel',
     prev,

package/docs/src/pages/components/charts.js

@@ -32,7 +32,6 @@ export default {
     description: 'Server-rendered SVG charts for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/charts',
     prev,

package/docs/src/pages/components/checkbox.js

@@ -12,7 +12,6 @@ export default {
     description: 'Custom-styled checkbox component for Pulse UI.',
     styles:      ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/checkbox',
     prev,

package/docs/src/pages/components/cluster.js

@@ -12,7 +12,6 @@ export default {
     description: 'Cluster component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/cluster',
     prev,

package/docs/src/pages/components/code-window.js

@@ -12,7 +12,6 @@ export default {
     description: 'macOS-style window chrome around a code block. Accepts pre-highlighted HTML as the content slot.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/code-window',
     prev,

package/docs/src/pages/components/container.js

@@ -12,7 +12,6 @@ export default {
     description: 'Container component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/container',
     prev,

package/docs/src/pages/components/divider.js

@@ -12,7 +12,6 @@ export default {
     description: 'Divider component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/divider',
     prev,

package/docs/src/pages/components/empty.js

@@ -11,7 +11,6 @@ export default {
     description: 'Empty state component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/empty',
     prev,

package/docs/src/pages/components/feature.js

@@ -13,7 +13,6 @@ export default {
     description: 'Feature component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/feature',
     prev,

package/docs/src/pages/components/fieldset.js

@@ -12,7 +12,6 @@ export default {
     description: 'Semantic grouping of related form fields with an accessible legend.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/fieldset',
     prev,

package/docs/src/pages/components/footer.js

@@ -12,7 +12,6 @@ export default {
     description: 'Accessible site footer with logo slot, navigation links, and legal text.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/footer',
     prev,

package/docs/src/pages/components/grid.js

@@ -16,7 +16,6 @@ export default {
     description: 'Grid component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/grid',
     prev,

package/docs/src/pages/components/heading.js

@@ -12,7 +12,6 @@ export default {
     description: 'Styled semantic heading component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/heading',
     prev,

package/docs/src/pages/components/icons.js

@@ -145,7 +145,6 @@ export default {
     description: 'Built-in icon set for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/icons',
     prev,

package/docs/src/pages/components/image.js

@@ -12,7 +12,6 @@ export default {
     description: 'Responsive image component with optional aspect-ratio crop and caption for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/image',
     prev,

package/docs/src/pages/components/input.js

@@ -12,7 +12,6 @@ export default {
     description: 'Input component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/input',
     prev,

package/docs/src/pages/components/list.js

@@ -12,7 +12,6 @@ export default {
     description: 'Styled ordered and unordered list component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/list',
     prev,

package/docs/src/pages/components/media.js

@@ -12,7 +12,6 @@ export default {
     description: 'Media component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/media',
     prev,

package/docs/src/pages/components/modal.js

@@ -12,7 +12,6 @@ export default {
     description: 'Modal dialog component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/modal',
     prev,

package/docs/src/pages/components/nav.js

@@ -12,7 +12,6 @@ export default {
     description: 'Nav component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/nav',
     prev,

package/docs/src/pages/components/pricing.js

@@ -12,7 +12,6 @@ export default {
     description: 'Pricing component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/pricing',
     prev,

package/docs/src/pages/components/progress.js

@@ -12,7 +12,6 @@ export default {
     description: 'Progress bar component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/progress',
     prev,

package/docs/src/pages/components/prose.js

@@ -25,7 +25,6 @@ export default {
     description: 'Typography wrapper for CMS output and rich text content in Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/prose',
     prev,

package/docs/src/pages/components/pullquote.js

@@ -12,7 +12,6 @@ export default {
     description: 'Styled blockquote component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/pullquote',
     prev,

package/docs/src/pages/components/radio.js

@@ -12,7 +12,6 @@ export default {
     description: 'Radio button and radio group components for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/radio',
     prev,

package/docs/src/pages/components/rating.js

@@ -12,7 +12,6 @@ export default {
     description: 'Star rating display and interactive input component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/rating',
     prev,

package/docs/src/pages/components/search.js

@@ -12,7 +12,6 @@ export default {
     description: 'Search input component with icon, debounce binding, and clear button.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/search',
     prev,

package/docs/src/pages/components/section.js

@@ -12,7 +12,6 @@ export default {
     description: 'Vertical padding wrapper with optional background. Compose with container() for full-width background with constrained content.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/section',
     prev,

package/docs/src/pages/components/segmented.js

@@ -12,7 +12,6 @@ export default {
     description: 'iOS-style segmented control component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/segmented',
     prev,

package/docs/src/pages/components/select.js

@@ -11,7 +11,6 @@ export default {
     description: 'Select component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/select',
     prev,

package/docs/src/pages/components/spinner.js

@@ -12,7 +12,6 @@ export default {
     description: 'Loading spinner component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/spinner',
     prev,

package/docs/src/pages/components/stack.js

@@ -12,7 +12,6 @@ export default {
     description: 'Stack component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/stack',
     prev,

package/docs/src/pages/components/stat.js

@@ -12,7 +12,6 @@ export default {
     description: 'Stat component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/stat',
     prev,

package/docs/src/pages/components/stepper.js

@@ -14,7 +14,6 @@ export default {
     description: 'Horizontal step progress indicator component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/stepper',
     prev,

package/docs/src/pages/components/table.js

@@ -12,7 +12,6 @@ export default {
     description: 'Table component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/table',
     prev,

package/docs/src/pages/components/testimonial.js

@@ -12,7 +12,6 @@ export default {
     description: 'Testimonial component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/testimonial',
     prev,

package/docs/src/pages/components/textarea.js

@@ -11,7 +11,6 @@ export default {
     description: 'Textarea component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/textarea',
     prev,

package/docs/src/pages/components/timeline.js

@@ -17,7 +17,6 @@ export default {
     description: 'Timeline component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/timeline',
     prev,

package/docs/src/pages/components/toggle.js

@@ -12,7 +12,6 @@ export default {
     description: 'iOS-style switch toggle component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/toggle',
     prev,

package/docs/src/pages/components/tooltip.js

@@ -12,7 +12,6 @@ export default {
     description: 'Tooltip component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/tooltip',
     prev,

package/docs/src/pages/components.js

@@ -11,7 +11,6 @@ export default {
     description: 'Server-rendered UI components for Pulse — button, card, input, alert, stat, avatar, table and more. Fully accessible, mobile-ready, zero client JS.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/components',
     prev,

package/docs/src/pages/config.js

@@ -11,7 +11,6 @@ export default {
     description: 'Full reference for pulse.config.js — port, Lighthouse thresholds, load test config, environments, and per-route overrides.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/config',
     prev,

package/docs/src/pages/deploy.js

@@ -11,7 +11,6 @@ export default {
     description: 'Deploy a Pulse app to a VPS, Docker, Fly.io, Railway, or Render.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/deploy',
     prev,

package/docs/src/pages/extending.js

@@ -11,7 +11,6 @@ export default {
     description: 'Escape hatches for features outside the Pulse spec — onRequest middleware, raw server access, WebSockets, SSE, and custom error handling.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/extending',
     prev,

package/docs/src/pages/faq.js

@@ -21,7 +21,6 @@ export default {
     description: 'Frequently asked questions about the Pulse framework.',
     styles:      ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/faq',
     prev,

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

@@ -11,7 +11,6 @@ export default {
     description: 'Install Pulse and build your first page with an AI agent in minutes.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/getting-started',
     prev,

package/docs/src/pages/guard.js

@@ -11,7 +11,6 @@ export default {
     description: 'Per-route authorization in Pulse. Guard functions run before server data fetchers and redirect unauthorized requests.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/guard',
     prev,
@@ -33,7 +32,6 @@ export default {
     user: async (ctx) => getCurrentUser(ctx.cookies.session),
   },
 
-  state: {},
   view: (state, server) => \`
     <main id="main-content">
       <h1>Welcome, \${server.user.name}</h1>
@@ -87,7 +85,6 @@ export default {
     if (ctx.cookies.session) return { redirect: '/dashboard' }
   },
 
-  state: {},
   view: () => \`<main id="main-content">...</main>\`,
 }`, 'js'))}
 

package/docs/src/pages/how-it-works.js

@@ -70,7 +70,6 @@ export default {
     description: 'How the Pulse MCP server gives an AI agent the knowledge and tools to build Pulse apps correctly.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/how-it-works',
     prev,

package/docs/src/pages/images.js

@@ -11,7 +11,6 @@ export default {
     description: 'The img() and picture() helpers for optimised, CLS-free image markup.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/images',
     prev,
@@ -95,7 +94,6 @@ import { img, picture } from '@invisibleloop/pulse/image'`, 'js'))}
 
 export default {
   route: '/blog/:slug',
-  state: {},
   server: {
     data: async (ctx) => ({ post: await db.posts.findBySlug(ctx.params.slug) }),
   },

package/docs/src/pages/meta.js

@@ -11,7 +11,6 @@ export default {
     description: 'How to configure page metadata, Open Graph tags, and structured data in Pulse.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/meta',
     prev,
@@ -28,7 +27,6 @@ export default {
     description: 'Learn about the team behind Acme Corp.',
     styles:      ['/app.css'],
   },
-  state: {},
   view: () => \`<h1>About Us</h1>\`,
 }`, 'js'))}
       <p>This generates:</p>

package/docs/src/pages/navigation.js

@@ -11,7 +11,6 @@ export default {
     description: 'Client-side navigation in Pulse — how link interception, JSON responses, and spec re-mounting work.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/navigation',
     prev,

package/docs/src/pages/performance.js

@@ -11,7 +11,6 @@ export default {
     description: 'Performance targets, techniques, and built-in optimisations in Pulse.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/performance',
     prev,
@@ -85,7 +84,6 @@ export default {
 export default {
   route: '/about',
   meta:  { title: 'About', styles: ['/app.css'] },
-  state: {},
   view:  () => \`<main><h1>About us</h1></main>\`,
 }`, 'js'))}
 

package/docs/src/pages/project-structure.js

@@ -11,7 +11,6 @@ export default {
     description: 'Recommended directory layout for a Pulse application.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/project-structure',
     prev,
@@ -77,7 +76,6 @@ import { card } from '../components/card.js'
 
 export default {
   route: '/',
-  state: {},
   view: () => card({ title: 'Hello', body: 'Welcome to Pulse' }),
 }`, 'js'), 'src/pages/home.js')}
 

package/docs/src/pages/prompt-examples.js

@@ -29,7 +29,6 @@ export default {
     description: 'Real prompts for building Pulse pages with your AI agent — from creating pages to authentication, performance audits, and integrations.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/prompt-examples',
     prev,

package/docs/src/pages/raw-responses.js

@@ -11,7 +11,6 @@ export default {
     description: 'Return non-HTML responses from Pulse specs — RSS, XML, JSON, and other content types.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/raw-responses',
     prev,
@@ -25,7 +24,6 @@ export default {
       ${codeBlock(highlight(`export default {
   route: '/feed.xml',
   contentType: 'application/rss+xml',
-  state: {},
   server: {
     data: async () => ({
       posts: await db.posts.latest(20),
@@ -53,7 +51,6 @@ export default {
       ${codeBlock(highlight(`export default {
   route: '/api/products',
   contentType: 'application/json',
-  state: {},
   server: {
     data: async (ctx) => ({
       products: await db.products.list({
@@ -73,7 +70,6 @@ export default {
   route: '/sitemap.xml',
   contentType: 'application/xml',
   serverTtl:   3600,
-  state: {},
   server: {
     data: async () => ({
       pages: await db.pages.allPublished(),

package/docs/src/pages/routing.js

@@ -11,7 +11,6 @@ export default {
     description: 'How Pulse routes requests to page specs — static and dynamic routes, params, and conventions.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/routing',
     prev,
@@ -24,7 +23,6 @@ export default {
       <p>Every spec has a <code>route</code> field. This is the URL pattern the spec handles:</p>
       ${codeBlock(highlight(`export default {
   route: '/about',
-  state: {},
   view: () => \`<h1>About</h1>\`,
 }`, 'js'))}
       <p>Pulse matches the exact path. By default, trailing slashes are removed — <code>/about/</code> redirects to <code>/about</code> with a 301. This is controlled by the <code>trailingSlash</code> option in <code>createServer</code>:</p>

package/docs/src/pages/server-api.js

@@ -11,7 +11,6 @@ export default {
     description: 'Complete reference for createServer — all options, hooks, and response behaviour.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/server-api',
     prev,
@@ -176,7 +175,6 @@ await createServer(specs, {
     }
   },
 
-  state: {},
   view: () => \`<form method="POST">...</form>\`,
 }`, 'js'))}
       ${callout('note', 'Raw response specs (<code>contentType</code> set) accept any HTTP method without <code>spec.methods</code> — they are always method-agnostic.')}

package/docs/src/pages/server-data.js

@@ -11,7 +11,6 @@ export default {
     description: 'Fetch, transform, and combine data on the server before rendering — external APIs, multiple fetchers, parallel requests.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/server-data',
     prev,

package/docs/src/pages/slash-commands.js

@@ -11,7 +11,6 @@ export default {
     description: 'The built-in slash commands available in the Pulse AI agent session.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/slash-commands',
     prev,

package/docs/src/pages/spec.js

@@ -25,7 +25,7 @@ export default {
         ['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>state</code>', '<code>object</code>', 'No', 'Initial client-side state. Deep-cloned on mount. Defaults to <code>{}</code> — omit on purely server-rendered pages.'],
           ['<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>', 'Auto', 'Auto-derived from the URL entry in <code>createServer</code>. Do not set manually.'],
@@ -35,6 +35,7 @@ export default {
           ['<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>guard</code>', '<code>function</code>', 'No', 'Async pre-render hook. Return <code>{ redirect }</code> or <code>{ status, json }</code> to short-circuit. See <a href="/guard">Guard</a>.'],
           ['<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.'],
@@ -53,7 +54,7 @@ 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>
 
       ${section('state', 'state')}
-      <p>The initial client-side state for the page. Always a plain object. Pulse deep-clones it on every mount — mutations never affect the original spec, and state cannot leak between page loads.</p>
+      <p>The initial client-side state for the page. Always a plain object. Defaults to <code>{}</code> — you can omit it entirely on purely server-rendered pages with no <code>mutations</code>, <code>actions</code>, or <code>persist</code>. Pulse deep-clones it on every mount — mutations never affect the original spec, and state cannot leak between page loads.</p>
       ${codeBlock(highlight(`state: {
   count: 0,
   user: { name: '', email: '' },

package/docs/src/pages/streaming.js

@@ -11,7 +11,6 @@ export default {
     description: 'How streaming server-side rendering works in Pulse — shell, deferred segments, and when to use it.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/streaming',
     prev,
@@ -28,7 +27,6 @@ export default {
       <p>To use streaming, the <code>view</code> is an <strong>object of named segment functions</strong> rather than a single function. The spec declares which segments are in the shell and which are deferred:</p>
       ${codeBlock(highlight(`export default {
   route: '/dashboard',
-  state: {},
   server: {
     data: async (ctx) => ({
       user:   await auth.getUser(ctx.cookies.sessionId),  // fast

package/docs/src/pages/testing.js

@@ -11,7 +11,6 @@ export default {
     description: 'Test Pulse view functions with renderSync and render — query the HTML output with CSS-like selectors, no DOM required.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/testing',
     prev,

package/docs/src/pages/validation.js

@@ -11,7 +11,6 @@ export default {
     description: 'Declarative validation rules in Pulse — syntax, formats, dot-path notation, and error handling.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/validation',
     prev,

package/package.json

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

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.4.0
+0.5.1

package/src/runtime/index.js

@@ -24,8 +24,8 @@ const showToast = (opts) => import('./toast.js').then(m => m.showToast(opts))
  * @param {Object} [serverState] - Serialised server state from SSR
  */
 export function mount(spec, el, serverState = {}, options = {}) {
-  if (!spec || spec.state === undefined || !spec.view) {
-    throw new Error('[Pulse] mount: spec must have state and view')
+  if (!spec || !spec.view) {
+    throw new Error('[Pulse] mount: spec must have a view')
   }
   // Spec is validated server-side at startup — no need to re-validate in the browser
   // Initialise the client store from SSR data (no-op after the first page mount).
@@ -60,7 +60,7 @@ export function mount(spec, el, serverState = {}, options = {}) {
   }
 
   // Deep clone initial state — never mutate the spec itself
-  let state = deepClone(spec.state)
+  let state = deepClone(spec.state ?? {})
 
   // Restore persisted keys from localStorage
   const persistKey = spec.persist?.length ? `pulse:${spec.route || location.pathname}` : null
@@ -69,7 +69,7 @@ export function mount(spec, el, serverState = {}, options = {}) {
     try {
       const saved = JSON.parse(localStorage.getItem(persistKey) || '{}')
       spec.persist.forEach(k => {
-        if (saved[k] !== undefined && saved[k] !== spec.state[k]) {
+        if (saved[k] !== undefined && saved[k] !== (spec.state ?? {})[k]) {
           state[k] = saved[k]
           restoredFromPersist = true
         }

package/src/spec/schema.js

@@ -159,9 +159,7 @@ export function validateSpec(spec) {
   }
 
   // state
-  if (spec.state === undefined) {
-    errors.push('spec.state is required — use {} if there is no client state')
-  } else if (typeof spec.state !== 'object' || Array.isArray(spec.state)) {
+  if (spec.state !== undefined && (typeof spec.state !== 'object' || Array.isArray(spec.state))) {
     errors.push('spec.state must be a plain object')
   }
 
@@ -371,6 +369,11 @@ export function validateSpec(spec) {
     }
   }
 
+  // hydrate — auto-derived by the framework, should never be set manually
+  if (spec.hydrate !== undefined) {
+    warnings.push('spec.hydrate is set manually — it is auto-derived by the framework from the URL entry passed to createServer. Remove it from the spec.')
+  }
+
   // meta quality
   if (!spec.meta) {
     warnings.push('spec.meta is missing — add at minimum title and description for SEO')

package/src/spec/schema.test.js

@@ -54,8 +54,13 @@ test('rejects route that does not start with /', () => {
   assertErrors({ route: 'contact', state: {}, view: () => '' }, 'must start with "/"')
 })
 
-test('requires state', () => {
-  assertErrors({ route: '/contact', view: () => '' }, 'spec.state is required')
+test('state is optional — omitting it is valid', () => {
+  const { valid, errors } = validateSpec({ route: '/contact', view: () => '' })
+  if (!valid) throw new Error(`Expected valid but got: ${errors.join(', ')}`)
+})
+
+test('state must be a plain object when provided', () => {
+  assertErrors({ route: '/contact', state: 'bad', view: () => '' }, 'spec.state must be a plain object')
 })
 
 test('requires view', () => {