@invisibleloop/pulse 0.3.0 → 0.5.0

package/CLAUDE.md

@@ -35,12 +35,11 @@ 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 = {
   route:   '/path',           // URL pattern, supports :params
-  hydrate: '/path/to/spec.js',// browser-importable path → enables hydration
 
   meta: {
     title:       'Page Title',
@@ -63,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
@@ -199,29 +199,41 @@ The server auto-detects the manifest from `staticDir/dist/manifest.json` when `s
 ```js
 import { createServer } from './src/server/index.js'
 
-createServer([specA, specB], {
-  port:         3000,
-  stream:       true,          // streaming SSR (default)
-  staticDir:    'public',      // serve static files + auto-load manifest
-  manifest:     null,          // explicit manifest path or object (overrides auto-detect)
-  defaultCache: 3600,          // default HTML cache TTL in seconds for all pages (prod only)
-                               // also accepts true (3600s + swr 86400s) or { public, maxAge, staleWhileRevalidate }
-                               // spec.cache overrides per-page; in-process + Cache-Control headers both set
-  fetcherTimeout:  5000,        // ms before any server fetcher times out (null = no limit)
-                                // spec.serverTimeout overrides per-page
-  shutdownTimeout: 30000,       // ms to wait for in-flight requests before force-exit on SIGTERM/SIGINT
-  healthCheck:     '/healthz',  // built-in health endpoint path, or false to disable
-  csp: {                        // extra sources merged into the framework's default CSP
-    'style-src': ['https://fonts.googleapis.com'],
-    'font-src':  ['https://fonts.gstatic.com'],
-  },
-  resolveBrand: async (host) => db.brands.findBySlug(host.split('.')[0]),
-                               // multi-brand: result cached 60s, attached to ctx.brand
-  onRequest:    (req, res) => { /* return false to short-circuit */ },
-  onError:      (err, req, res) => { /* custom error handling */ }
-})
+// Pass URL objects — hydrate is auto-derived, no need to set it in specs.
+// Specs with mutations/actions/persist are hydrated automatically.
+// Purely server-rendered specs get zero JavaScript.
+await createServer(
+  [
+    new URL('./src/pages/home.js',    import.meta.url),
+    new URL('./src/pages/contact.js', import.meta.url),
+  ],
+  {
+    port:         3000,
+    stream:       true,          // streaming SSR (default)
+    staticDir:    'public',      // serve static files + auto-load manifest
+    root:         new URL('.', import.meta.url),  // project root for deriving browser paths
+    manifest:     null,          // explicit manifest path or object (overrides auto-detect)
+    defaultCache: 3600,          // default HTML cache TTL in seconds for all pages (prod only)
+                                 // also accepts true (3600s + swr 86400s) or { public, maxAge, staleWhileRevalidate }
+                                 // spec.cache overrides per-page; in-process + Cache-Control headers both set
+    fetcherTimeout:  5000,        // ms before any server fetcher times out (null = no limit)
+                                  // spec.serverTimeout overrides per-page
+    shutdownTimeout: 30000,       // ms to wait for in-flight requests before force-exit on SIGTERM/SIGINT
+    healthCheck:     '/healthz',  // built-in health endpoint path, or false to disable
+    csp: {                        // extra sources merged into the framework's default CSP
+      'style-src': ['https://fonts.googleapis.com'],
+      'font-src':  ['https://fonts.gstatic.com'],
+    },
+    resolveBrand: async (host) => db.brands.findBySlug(host.split('.')[0]),
+                                 // multi-brand: result cached 60s, attached to ctx.brand
+    onRequest:    (req, res) => { /* return false to short-circuit */ },
+    onError:      (err, req, res) => { /* custom error handling */ }
+  }
+)
 ```
 
+`createServer` is async — always `await` it. Spec objects are still accepted alongside URL objects for backwards compatibility.
+
 All specs are validated at startup — bad specs throw before the server accepts connections.
 
 ## Multi-brand Sites

package/docs/server.js

@@ -1,8 +1,8 @@
-import fs                 from 'fs'
-import { createServer }   from '../src/server/index.js'
-import { initLayoutManifest } from './src/lib/layout.js'
-import { metrics }        from './src/lib/stats.js'
-import { metricsStore }   from './src/lib/metrics-store.js'
+import fs                      from 'fs'
+import { createServer }        from '../src/server/index.js'
+import { initLayoutManifest }  from './src/lib/layout.js'
+import { metrics }             from './src/lib/stats.js'
+import { metricsStore }        from './src/lib/metrics-store.js'
 metricsStore.current = metrics
 
 // Populate hashed asset paths in layout.js before any page renders
@@ -10,194 +10,113 @@ try {
   const raw = fs.readFileSync(new URL('./public/dist/manifest.json', import.meta.url), 'utf8')
   initLayoutManifest(JSON.parse(raw))
 } catch { /* dev: no manifest yet, layout falls back to unhashed paths */ }
-import home               from './src/pages/home.js'
-import howItWorks        from './src/pages/how-it-works.js'
-import faq               from './src/pages/faq.js'
-import config             from './src/pages/config.js'
-import gettingStarted     from './src/pages/getting-started.js'
-import slashCommands      from './src/pages/slash-commands.js'
-import promptExamples     from './src/pages/prompt-examples.js'
-import components         from './src/pages/components.js'
-import projectStructure   from './src/pages/project-structure.js'
-import spec               from './src/pages/spec.js'
-import state              from './src/pages/state.js'
-import mutations          from './src/pages/mutations.js'
-import actions            from './src/pages/actions.js'
-import validation         from './src/pages/validation.js'
-import constraints        from './src/pages/constraints.js'
-import persist            from './src/pages/persist.js'
-import serverData         from './src/pages/server-data.js'
-import routing            from './src/pages/routing.js'
-import streaming          from './src/pages/streaming.js'
-import caching            from './src/pages/caching.js'
-import guard              from './src/pages/guard.js'
-import rawResponses       from './src/pages/raw-responses.js'
-import serverApi          from './src/pages/server-api.js'
-import hydration          from './src/pages/hydration.js'
-import navigation         from './src/pages/navigation.js'
-import images             from './src/pages/images.js'
-import extending          from './src/pages/extending.js'
-import deploy             from './src/pages/deploy.js'
-import supabase           from './src/pages/supabase.js'
-import auth               from './src/pages/auth.js'
-import stripe             from './src/pages/stripe.js'
-import meta               from './src/pages/meta.js'
-import performance        from './src/pages/performance.js'
-import accessibility      from './src/pages/accessibility.js'
-import testing           from './src/pages/testing.js'
-import store             from './src/pages/store.js'
 
-// Component pages
-import compButton      from './src/pages/components/button.js'
-import compBadge       from './src/pages/components/badge.js'
-import compCard        from './src/pages/components/card.js'
-import compInput       from './src/pages/components/input.js'
-import compSelect      from './src/pages/components/select.js'
-import compTextarea    from './src/pages/components/textarea.js'
-import compAlert       from './src/pages/components/alert.js'
-import compStat        from './src/pages/components/stat.js'
-import compAvatar      from './src/pages/components/avatar.js'
-import compEmpty       from './src/pages/components/empty.js'
-import compTable       from './src/pages/components/table.js'
-import compNav         from './src/pages/components/nav.js'
-import compHero        from './src/pages/components/hero.js'
-import compAppBadge    from './src/pages/components/app-badge.js'
-import compFeature     from './src/pages/components/feature.js'
-import compTestimonial from './src/pages/components/testimonial.js'
-import compPricing     from './src/pages/components/pricing.js'
-import compAccordion   from './src/pages/components/accordion.js'
-import compContainer   from './src/pages/components/container.js'
-import compSection     from './src/pages/components/section.js'
-import compGrid        from './src/pages/components/grid.js'
-import compStack       from './src/pages/components/stack.js'
-import compCluster     from './src/pages/components/cluster.js'
-import compDivider     from './src/pages/components/divider.js'
-import compBanner      from './src/pages/components/banner.js'
-import compMedia       from './src/pages/components/media.js'
-import compTooltip     from './src/pages/components/tooltip.js'
-import compModal       from './src/pages/components/modal.js'
-import compCarousel    from './src/pages/components/carousel.js'
-import compCta         from './src/pages/components/cta.js'
-import compFooter      from './src/pages/components/footer.js'
-import compCodeWindow  from './src/pages/components/code-window.js'
-import compFieldset    from './src/pages/components/fieldset.js'
-import compToggle      from './src/pages/components/toggle.js'
-import compCheckbox    from './src/pages/components/checkbox.js'
-import compFileUpload  from './src/pages/components/fileupload.js'
-import compSlider      from './src/pages/components/slider.js'
-import compSegmented   from './src/pages/components/segmented.js'
-import compRadio       from './src/pages/components/radio.js'
-import compRating      from './src/pages/components/rating.js'
-import compSearch      from './src/pages/components/search.js'
-import compSpinner     from './src/pages/components/spinner.js'
-import compProgress    from './src/pages/components/progress.js'
-import compBreadcrumbs from './src/pages/components/breadcrumbs.js'
-import compStepper     from './src/pages/components/stepper.js'
-import compImage       from './src/pages/components/image.js'
-import compPullquote   from './src/pages/components/pullquote.js'
-import compProse       from './src/pages/components/prose.js'
-import compHeading     from './src/pages/components/heading.js'
-import compList        from './src/pages/components/list.js'
-import compTimeline    from './src/pages/components/timeline.js'
-import compCharts      from './src/pages/components/charts.js'
-import compIcons       from './src/pages/components/icons.js'
-
-createServer(
+await createServer(
   [
-    home,
-    howItWorks,
-    faq,
-    config,
-    gettingStarted,
-    slashCommands,
-    promptExamples,
-    components,
-    projectStructure,
-    spec,
-    state,
-    mutations,
-    actions,
-    validation,
-    constraints,
-    persist,
-    serverData,
-    routing,
-    streaming,
-    caching,
-    guard,
-    rawResponses,
-    serverApi,
-    hydration,
-    navigation,
-    images,
-    extending,
-    deploy,
-    supabase,
-    auth,
-    stripe,
-    meta,
-    performance,
-    accessibility,
-    testing,
-    store,
-    // Component pages
-    compButton,
-    compBadge,
-    compCard,
-    compInput,
-    compSelect,
-    compTextarea,
-    compAlert,
-    compStat,
-    compAvatar,
-    compEmpty,
-    compTable,
-    compNav,
-    compHero,
-    compAppBadge,
-    compFeature,
-    compTestimonial,
-    compPricing,
-    compAccordion,
-    compContainer,
-    compSection,
-    compGrid,
-    compStack,
-    compCluster,
-    compDivider,
-    compBanner,
-    compMedia,
-    compTooltip,
-    compModal,
-    compCarousel,
-    compCta,
-    compFooter,
-    compCodeWindow,
-    compFieldset,
-    compToggle,
-    compCheckbox,
-    compFileUpload,
-    compSlider,
-    compSegmented,
-    compRadio,
-    compRating,
-    compSearch,
-    compSpinner,
-    compProgress,
-    compBreadcrumbs,
-    compStepper,
-    compImage,
-    compPullquote,
-    compProse,
-    compHeading,
-    compList,
-    compTimeline,
-    compCharts,
-    compIcons,
+    // Framework
+    new URL('./src/pages/home.js',              import.meta.url),
+    new URL('./src/pages/how-it-works.js',      import.meta.url),
+    new URL('./src/pages/faq.js',               import.meta.url),
+    new URL('./src/pages/config.js',            import.meta.url),
+    new URL('./src/pages/getting-started.js',   import.meta.url),
+    new URL('./src/pages/slash-commands.js',    import.meta.url),
+    new URL('./src/pages/prompt-examples.js',   import.meta.url),
+    new URL('./src/pages/components.js',        import.meta.url),
+    new URL('./src/pages/project-structure.js', import.meta.url),
+    new URL('./src/pages/spec.js',              import.meta.url),
+    // State & Behaviour
+    new URL('./src/pages/state.js',             import.meta.url),
+    new URL('./src/pages/mutations.js',         import.meta.url),
+    new URL('./src/pages/actions.js',           import.meta.url),
+    new URL('./src/pages/validation.js',        import.meta.url),
+    new URL('./src/pages/constraints.js',       import.meta.url),
+    new URL('./src/pages/persist.js',           import.meta.url),
+    // Server
+    new URL('./src/pages/server-data.js',       import.meta.url),
+    new URL('./src/pages/store.js',             import.meta.url),
+    new URL('./src/pages/routing.js',           import.meta.url),
+    new URL('./src/pages/streaming.js',         import.meta.url),
+    new URL('./src/pages/caching.js',           import.meta.url),
+    new URL('./src/pages/guard.js',             import.meta.url),
+    new URL('./src/pages/raw-responses.js',     import.meta.url),
+    new URL('./src/pages/server-api.js',        import.meta.url),
+    new URL('./src/pages/extending.js',         import.meta.url),
+    // Client
+    new URL('./src/pages/hydration.js',         import.meta.url),
+    new URL('./src/pages/navigation.js',        import.meta.url),
+    new URL('./src/pages/images.js',            import.meta.url),
+    // Deployment
+    new URL('./src/pages/deploy.js',            import.meta.url),
+    // Reference
+    new URL('./src/pages/meta.js',              import.meta.url),
+    new URL('./src/pages/performance.js',       import.meta.url),
+    new URL('./src/pages/accessibility.js',     import.meta.url),
+    new URL('./src/pages/testing.js',           import.meta.url),
+    // Integrations
+    new URL('./src/pages/supabase.js',          import.meta.url),
+    new URL('./src/pages/auth.js',              import.meta.url),
+    new URL('./src/pages/stripe.js',            import.meta.url),
+    // UI Components
+    new URL('./src/pages/components/alert.js',       import.meta.url),
+    new URL('./src/pages/components/avatar.js',      import.meta.url),
+    new URL('./src/pages/components/badge.js',       import.meta.url),
+    new URL('./src/pages/components/breadcrumbs.js', import.meta.url),
+    new URL('./src/pages/components/button.js',      import.meta.url),
+    new URL('./src/pages/components/card.js',        import.meta.url),
+    new URL('./src/pages/components/checkbox.js',    import.meta.url),
+    new URL('./src/pages/components/carousel.js',    import.meta.url),
+    new URL('./src/pages/components/charts.js',      import.meta.url),
+    new URL('./src/pages/components/empty.js',       import.meta.url),
+    new URL('./src/pages/components/fieldset.js',    import.meta.url),
+    new URL('./src/pages/components/fileupload.js',  import.meta.url),
+    new URL('./src/pages/components/heading.js',     import.meta.url),
+    new URL('./src/pages/components/icons.js',       import.meta.url),
+    new URL('./src/pages/components/image.js',       import.meta.url),
+    new URL('./src/pages/components/input.js',       import.meta.url),
+    new URL('./src/pages/components/list.js',        import.meta.url),
+    new URL('./src/pages/components/modal.js',       import.meta.url),
+    new URL('./src/pages/components/progress.js',    import.meta.url),
+    new URL('./src/pages/components/prose.js',       import.meta.url),
+    new URL('./src/pages/components/pullquote.js',   import.meta.url),
+    new URL('./src/pages/components/radio.js',       import.meta.url),
+    new URL('./src/pages/components/rating.js',      import.meta.url),
+    new URL('./src/pages/components/search.js',      import.meta.url),
+    new URL('./src/pages/components/segmented.js',   import.meta.url),
+    new URL('./src/pages/components/select.js',      import.meta.url),
+    new URL('./src/pages/components/slider.js',      import.meta.url),
+    new URL('./src/pages/components/spinner.js',     import.meta.url),
+    new URL('./src/pages/components/stat.js',        import.meta.url),
+    new URL('./src/pages/components/stepper.js',     import.meta.url),
+    new URL('./src/pages/components/table.js',       import.meta.url),
+    new URL('./src/pages/components/textarea.js',    import.meta.url),
+    new URL('./src/pages/components/timeline.js',    import.meta.url),
+    new URL('./src/pages/components/toggle.js',      import.meta.url),
+    new URL('./src/pages/components/tooltip.js',     import.meta.url),
+    // Landing Components
+    new URL('./src/pages/components/accordion.js',   import.meta.url),
+    new URL('./src/pages/components/app-badge.js',   import.meta.url),
+    new URL('./src/pages/components/cta.js',         import.meta.url),
+    new URL('./src/pages/components/feature.js',     import.meta.url),
+    new URL('./src/pages/components/hero.js',        import.meta.url),
+    new URL('./src/pages/components/nav.js',         import.meta.url),
+    new URL('./src/pages/components/pricing.js',     import.meta.url),
+    new URL('./src/pages/components/testimonial.js', import.meta.url),
+    // Layout Components
+    new URL('./src/pages/components/banner.js',      import.meta.url),
+    new URL('./src/pages/components/cluster.js',     import.meta.url),
+    new URL('./src/pages/components/code-window.js', import.meta.url),
+    new URL('./src/pages/components/container.js',   import.meta.url),
+    new URL('./src/pages/components/divider.js',     import.meta.url),
+    new URL('./src/pages/components/footer.js',      import.meta.url),
+    new URL('./src/pages/components/grid.js',        import.meta.url),
+    new URL('./src/pages/components/media.js',       import.meta.url),
+    new URL('./src/pages/components/section.js',     import.meta.url),
+    new URL('./src/pages/components/stack.js',       import.meta.url),
   ],
   {
     port:         process.env.PORT ? Number(process.env.PORT) : 4000,
     staticDir:    new URL('./public', import.meta.url).pathname,
+    root:         new URL('.', import.meta.url),
     defaultCache: true,
     csp: {
       'img-src': ['https://picsum.photos', 'https://images.unsplash.com'],

package/docs/src/pages/hydration.js

@@ -8,7 +8,7 @@ export default {
   route: '/hydration',
   meta: {
     title: 'Hydration — Pulse Docs',
-    description: 'How Pulse hydrates server-rendered HTML on the client — the hydrate field, mount(), and production bundles.',
+    description: 'How Pulse hydrates server-rendered HTML on the client — automatic hydration, mount(), and production bundles.',
     styles: ['/docs.css'],
   },
   state: {},
@@ -18,13 +18,22 @@ export default {
     next,
     content: `
       ${h1('Hydration')}
-      ${lead('Hydration in Pulse is opt-in and minimal. Omit <code>hydrate</code> and zero JavaScript is sent to the browser. Add it and Pulse binds events to the server-rendered HTML without re-rendering it — the SSR-painted content is preserved exactly as the server sent it.')}
+      ${lead('Hydration in Pulse is automatic. Specs with <code>mutations</code>, <code>actions</code>, or <code>persist</code> are hydrated automatically — Pulse binds events to the server-rendered HTML without re-rendering it. Purely server-rendered specs get zero JavaScript sent to the browser.')}
 
-      ${section('enabling', 'Enabling hydration')}
-      <p>Set the <code>hydrate</code> field to a browser-importable path to your spec file. Pulse uses this to generate the bootstrap script that mounts the client runtime:</p>
-      ${codeBlock(highlight(`export default {
+      ${section('enabling', 'How hydration works')}
+      <p>Pass spec files as <code>URL</code> objects to <code>createServer</code>. Pulse detects whether each spec needs client-side interactivity and, if so, derives the browser-importable path automatically — no <code>hydrate</code> field needed in the spec:</p>
+      ${codeBlock(highlight(`// server.js
+await createServer(
+  [
+    new URL('./src/pages/counter.js', import.meta.url),  // has mutations → auto-hydrated
+    new URL('./src/pages/about.js',   import.meta.url),  // no mutations  → zero JS
+  ],
+  { port: 3000, root: new URL('.', import.meta.url) }
+)
+
+// src/pages/counter.js — no hydrate field needed
+export default {
   route: '/counter',
-  hydrate: '/src/pages/counter.js',   // browser path to this file
   state: { count: 0 },
   mutations: {
     increment: (state) => ({ count: state.count + 1 }),
@@ -40,7 +49,7 @@ export default {
 }`, 'js'))}
 
       ${section('dev-bootstrap', 'Development bootstrap')}
-      <p>In development (when <code>hydrate</code> is a source file path, not a <code>/dist/</code> bundle), Pulse emits an inline bootstrap script:</p>
+      <p>In development Pulse emits an inline bootstrap script that imports the spec and runtime source files directly — no build step required:</p>
       ${codeBlock(highlight(`<script type="module">
   import spec from '/src/pages/counter.js'
   import { mount } from '/src/runtime/index.js'
@@ -57,7 +66,7 @@ public/dist/
   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>
+      <p>When Pulse detects a manifest (via <code>staticDir</code> auto-detection or explicit <code>manifest</code> option), it resolves the auto-derived hydrate 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'))}
 
       ${section('ssr-true', 'The { ssr: true } option')}
@@ -78,14 +87,14 @@ mount(
       <p>After mount, all <code>data-event</code> and <code>data-action</code> attributes in the DOM are wired to the spec's mutations and actions. State updates trigger a full view re-render via <code>innerHTML</code> replacement.</p>
 
       ${section('no-hydrate', 'Pages without hydration')}
-      <p>Omit <code>hydrate</code> and Pulse sends zero JavaScript to the browser — no runtime overhead, no hydration cost. This is the correct default for:</p>
+      <p>Specs with no <code>mutations</code>, <code>actions</code>, or <code>persist</code> automatically get zero JavaScript — no runtime overhead, no hydration cost. This is the correct default for:</p>
       <ul>
         <li>Documentation pages</li>
         <li>Marketing/landing pages</li>
         <li>Blog posts and articles</li>
         <li>Any page with no client-side interactivity</li>
       </ul>
-      ${callout('tip', 'Start without <code>hydrate</code> and only add it when actual client interactivity is needed. Many pages that appear to need JavaScript can be handled server-side with <a href="/routing">routing</a> and <a href="/server-data">server data</a>.')}
+      ${callout('tip', 'Many pages that appear to need JavaScript can be handled server-side with <a href="/routing">routing</a> and <a href="/server-data">server data</a>. Keep specs free of mutations and actions wherever possible.')}
 
       ${section('server-state', 'Passing server state to the client')}
       <p>Server data fetched via <code>server.data()</code> is serialised into the page HTML as <code>window.__PULSE_SERVER__</code>. The client runtime reads this on mount, making server data available to the view during client re-renders without an additional network request.</p>

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

@@ -18,16 +18,16 @@ export default {
     next,
     content: `
       ${h1('Server API')}
-      ${lead('<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.')}
+      ${lead('<code>createServer(entries, 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.')}
 
-      ${section('signature', 'createServer(specs, options)')}
+      ${section('signature', 'createServer(entries, options)')}
       ${codeBlock(highlight(`import { createServer } from '@invisibleloop/pulse'
 
-createServer(specs, options)`, 'js'))}
+await createServer(entries, options)`, 'js'))}
       ${table(
         ['Parameter', 'Type', 'Description'],
         [
-          ['<code>specs</code>', '<code>Spec[]</code>', 'Array of page spec objects. Validated at startup — a bad spec throws before the server accepts connections.'],
+          ['<code>entries</code>', '<code>Array&lt;URL | Spec&gt;</code>', 'Array of <code>URL</code> objects or plain spec objects. URL entries are imported and hydration is auto-derived. Validated at startup — a bad spec throws before the server accepts connections.'],
           ['<code>options</code>', '<code>object</code>', 'Server configuration options (see below).'],
         ]
       )}
@@ -41,6 +41,7 @@ createServer(specs, options)`, 'js'))}
           ['<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> — 301 redirect <code>/about/</code> → <code>/about</code>. <code>"add"</code> — 301 redirect <code>/about</code> → <code>/about/</code>. <code>"allow"</code> — serve both, no redirect.'],
+          ['<code>root</code>', '<code>URL | string</code>', '<code>process.cwd()</code>', 'Project root used to derive browser-importable paths from URL entries. Pass <code>new URL(\'.\', import.meta.url)</code> for a CWD-independent value.'],
           ['<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.'],
@@ -55,37 +56,42 @@ createServer(specs, options)`, 'js'))}
 
       ${section('example', 'Full example')}
       ${codeBlock(highlight(`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'))}
+await createServer(
+  [
+    new URL('./src/pages/home.js',    import.meta.url),
+    new URL('./src/pages/contact.js', import.meta.url),
+  ],
+  {
+    port:      3000,
+    stream:    true,
+    staticDir: 'public',
+    root:      new URL('.', import.meta.url),
+    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'))}
 
       ${section('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> — 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>
       ${codeBlock(highlight(`// server.js
-createServer(specs, {
+await createServer(specs, {
   resolveBrand: async (host) => {
     const slug = host.split('.')[0]          // 'acme' from 'acme.myco.com'
     return db.brands.findBySlug(slug)        // { slug, name, accent, logo, ... }
@@ -126,7 +132,7 @@ createServer(specs, {
       ${section('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>
-      ${codeBlock(highlight(`createServer(specs, {
+      ${codeBlock(highlight(`await createServer(specs, {
   staticDir: 'public',   // serves public/* at /*
   // manifest auto-detected from public/dist/manifest.json
 })`, 'js'))}
@@ -217,7 +223,7 @@ Cross-Origin-Resource-Policy: same-origin`, 'bash'))}
   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 — Google Fonts, a CDN, an external API — pass a <code>csp</code> object to <code>createServer</code>. Sources are merged into the framework defaults; existing directives are not replaced:</p>
-      ${codeBlock(highlight(`createServer(specs, {
+      ${codeBlock(highlight(`await createServer(specs, {
   csp: {
     'style-src': ['https://fonts.googleapis.com'],
     'font-src':  ['https://fonts.gstatic.com'],
@@ -252,7 +258,7 @@ Cross-Origin-Resource-Policy: same-origin`, 'bash'))}
       ${codeBlock(highlight(`GET /healthz → 200 OK
 { "status": "ok", "uptime": 42.3 }`, 'json'))}
       <p>Configure the path or disable it entirely:</p>
-      ${codeBlock(highlight(`createServer(specs, {
+      ${codeBlock(highlight(`await createServer(specs, {
   healthCheck: '/ping',   // custom path
   // healthCheck: false,  // disable
 })`, 'js'))}
@@ -267,7 +273,7 @@ Cross-Origin-Resource-Policy: same-origin`, 'bash'))}
         <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>
-      ${codeBlock(highlight(`const { server, shutdown } = createServer(specs, {
+      ${codeBlock(highlight(`const { server, shutdown } = await createServer(specs, {
   port:            3000,
   shutdownTimeout: 10000,  // 10 s — override the 30 s default
 })

package/docs/src/pages/spec.js

@@ -25,10 +25,10 @@ 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>', 'No', 'Browser-importable path to this spec file. Enables client hydration.'],
+          ['<code>hydrate</code>', '<code>string</code>', 'Auto', 'Auto-derived from the URL entry in <code>createServer</code>. Do not set manually.'],
           ['<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.'],
@@ -53,7 +53,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: '' },
@@ -84,10 +84,8 @@ route: '/blog/:year/:slug'`, 'js'))}
       <p>See <a href="/meta">Metadata &amp; SEO</a> for the full reference.</p>
 
       ${section('hydrate', 'hydrate')}
-      <p>A browser-importable path to this spec file. Setting this enables client-side hydration — 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>
-      ${codeBlock(highlight(`hydrate: '/src/pages/counter.js'   // dev: source file path
-// Production: resolved automatically via manifest.json`, 'js'))}
-      ${callout('note', 'Omit <code>hydrate</code> for purely server-rendered pages with no client interactivity. Pulse sends zero JavaScript to the browser — no runtime overhead, no hydration cost.')}
+      <p>Auto-derived by the framework — do not set this in your spec. When a spec is registered via a <code>URL</code> entry in <code>createServer</code>, Pulse detects whether it needs hydration (has <code>mutations</code>, <code>actions</code>, or <code>persist</code>) and sets the browser path automatically. Purely server-rendered specs get zero JavaScript.</p>
+      ${callout('note', 'See <a href="/hydration">Hydration</a> for how this works and how to register specs via URL entries.')}
 
       ${section('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>

package/examples/contact.js

@@ -28,7 +28,6 @@ function infoDetail(icon, label, value, href) {
 
 export default {
   route:   '/contact',
-  hydrate: '/examples/contact.js',
 
   meta: {
     title:       'Contact — Pulse',

package/examples/counter.js

@@ -15,7 +15,6 @@ import { examplesNav } from './shared.js'
 
 export default {
   route:   '/counter',
-  hydrate: '/examples/counter.js',
 
   meta: {
     title:       'Counter — Pulse',

package/examples/dev.server.js

@@ -18,12 +18,6 @@ import fs   from 'fs'
 import path from 'path'
 import { createServer } from '../src/server/index.js'
 import { themeScript }  from './shared.js'
-import counter  from './counter.js'
-import todos    from './todos.js'
-import contact  from './contact.js'
-import quiz     from './quiz.js'
-import products from './products.js'
-import pricing  from './pricing.js'
 
 const ROOT = path.resolve(import.meta.dirname, '..')
 
@@ -79,12 +73,20 @@ function staticHandler(req, res) {
   return false
 }
 
-createServer(
-  [counter, todos, contact, quiz, products, pricing],
+await createServer(
+  [
+    new URL('./counter.js',  import.meta.url),
+    new URL('./todos.js',    import.meta.url),
+    new URL('./contact.js',  import.meta.url),
+    new URL('./quiz.js',     import.meta.url),
+    new URL('./products.js', import.meta.url),
+    new URL('./pricing.js',  import.meta.url),
+  ],
   {
     port:       3001,
     stream:     true,
     staticDir:  path.join(ROOT, 'public'),
+    root:       new URL('..', import.meta.url),  // pulse2/ — specs served at /examples/*
     onRequest:  staticHandler,
     extraBody:  themeScript,
   }

package/examples/pricing.js

@@ -129,7 +129,6 @@ export const FAQ = [
 
 export default {
   route:   '/pricing',
-  hydrate: '/examples/pricing.js',
 
   meta: {
     title:       'Pricing — Pulse',

package/examples/products.js

@@ -72,7 +72,6 @@ export function applyFilters(products, search, category, sort) {
 
 export default {
   route:   '/products',
-  hydrate: '/examples/products.js',
 
   meta: {
     title:       'Products — Pulse',

package/examples/quiz.js

@@ -62,7 +62,6 @@ export function scoreLabel(score, total) {
 
 export default {
   route:   '/quiz',
-  hydrate: '/examples/quiz.js',
 
   meta: {
     title:       'Quiz — Pulse',

package/examples/todos.js

@@ -33,7 +33,6 @@ export function countByStatus(todos) {
 
 export default {
   route:   '/todos',
-  hydrate: '/examples/todos.js',
 
   meta: {
     title:       'Todos — Pulse',

package/package.json

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

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.3.0
+0.5.0

package/src/agent/checklist.md

@@ -4,11 +4,7 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 ### Critical
 
-- **`hydrate` is set on every interactive page.** Without it, `data-event` / `data-action` bindings do nothing, `persist` never runs, and client-side navigation cannot re-mount the page. Every spec with `mutations`, `actions`, or `persist` must include:
-  ```js
-  hydrate: '/src/pages/my-page.js',  // browser-importable path to this file
-  ```
-  Omit `hydrate` only for purely server-rendered pages with zero client interactivity.
+- **Do not set `hydrate` in specs.** It is auto-derived by the framework from the URL entry passed to `createServer`. Specs with `mutations`, `actions`, or `persist` are hydrated automatically. Purely server-rendered specs get zero JavaScript — no configuration needed.
 
 ### Components first
 

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/server/index.js

@@ -386,14 +386,70 @@ const MIME_TYPES = {
  *                                                Return false to short-circuit routing
  */
 
+// ---------------------------------------------------------------------------
+// Spec entry resolution — URL objects are imported and get hydrate auto-set
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true if the spec needs a client-side hydration script.
+ * Specs with no mutations, actions, or persist are purely server-rendered.
+ */
+function needsHydration(spec) {
+  return !!(spec.mutations && Object.keys(spec.mutations).length) ||
+         !!(spec.actions   && Object.keys(spec.actions).length)   ||
+         !!spec.persist
+}
+
+/**
+ * Accept mixed arrays of spec objects and URL objects.
+ * URL entries are dynamically imported; hydrate is auto-derived from the file
+ * URL by stripping the project root, so developers never need to set it.
+ *
+ * root — a file: URL string or URL object for the project root directory.
+ *        Defaults to process.cwd(). Pass `new URL('.', import.meta.url)` from
+ *        your server.js for a CWD-independent alternative.
+ */
+async function resolveSpecEntries(entries, root) {
+  // Normalise root to a href string ending with /
+  let rootHref
+  if (root instanceof URL) {
+    rootHref = root.href.endsWith('/') ? root.href : root.href + '/'
+  } else if (typeof root === 'string' && root.startsWith('file://')) {
+    rootHref = root.endsWith('/') ? root : root + '/'
+  } else {
+    // Default: process.cwd() converted to a file URL
+    rootHref = 'file://' + process.cwd().replace(/\\/g, '/') + '/'
+  }
+
+  const resolved = []
+  for (const entry of entries) {
+    if (!(entry instanceof URL)) {
+      resolved.push(entry)
+      continue
+    }
+    const mod  = await import(entry.href)
+    const spec = mod.default ?? mod
+    if (!spec.hydrate && needsHydration(spec)) {
+      // Strip project root to get the browser-importable path
+      const browserPath = entry.href.startsWith(rootHref)
+        ? '/' + entry.href.slice(rootHref.length)
+        : entry.pathname  // fallback: use pathname as-is
+      resolved.push({ ...spec, hydrate: browserPath })
+    } else {
+      resolved.push(spec)
+    }
+  }
+  return resolved
+}
+
 /**
  * Create and start a Pulse HTTP server.
  *
- * @param {import('../spec/schema.js').PulseSpec[]} specs
+ * @param {Array<import('../spec/schema.js').PulseSpec|URL>} entries
  * @param {ServerOptions} [options]
- * @returns {http.Server}
+ * @returns {Promise<{server: http.Server, shutdown: Function, updateSpecs: Function}>}
  */
-export function createServer(specs, options = {}) {
+export async function createServer(entries, options = {}) {
   const {
     port          = 3000,
     stream        = true,
@@ -403,6 +459,7 @@ export function createServer(specs, options = {}) {
     extraBody     = '',            // extra HTML injected before </body> on every page
     dev           = false,         // dev mode — show detailed error pages
     store         = null,          // global store definition (pulse.store.js default export)
+    root          = null,          // URL/string — project root for deriving browser paths from file: URLs
     resolveBrand   = null,          // async (host) => brandConfig — keyed by domain
     defaultCache   = null,          // default page cache: true | seconds | { public, maxAge, swr }
     fetcherTimeout  = null,          // ms before any server fetcher times out (null = no limit)
@@ -414,6 +471,9 @@ export function createServer(specs, options = {}) {
     onRequest
   } = options
 
+  // Resolve URL entries → spec objects, auto-setting hydrate where needed
+  const specs = await resolveSpecEntries(entries, root)
+
   const healthPath = healthCheck === true ? '/healthz' : (healthCheck || null)
 
   // Validate store at startup — fail fast before the server accepts connections

package/src/server/server.test.js

@@ -134,7 +134,7 @@ let nextPort = 13337
 
 async function withServer(specs, options, fn) {
   const port = nextPort++
-  const { server } = createServer(specs, { ...options, port })
+  const { server } = await createServer(specs, { ...options, port })
   await new Promise(resolve => server.once('listening', resolve))
   try {
     await fn(port)
@@ -345,7 +345,7 @@ console.log('\nStartup validation\n')
 await test('throws on invalid spec at startup', async () => {
   let threw = false
   try {
-    createServer([{ route: '/bad' }], { port: 19999 })
+    await createServer([{ route: '/bad' }], { port: 19999 })
   } catch (e) {
     threw = true
     assert(e.message.includes('/bad'), `Expected route in error: ${e.message}`)
@@ -1250,7 +1250,7 @@ console.log('\nGraceful shutdown\n')
 
 await test('shutdown() is returned from createServer', async () => {
   const port = nextPort++
-  const result = createServer([helloSpec], { port, stream: false })
+  const result = await createServer([helloSpec], { port, stream: false })
   assert(typeof result.shutdown === 'function', 'Expected shutdown to be a function')
   result.server.closeAllConnections?.()
   await new Promise(resolve => result.server.close(resolve))
@@ -1258,7 +1258,7 @@ await test('shutdown() is returned from createServer', async () => {
 
 await test('shutdown() stops the server from accepting new connections', async () => {
   const port = nextPort++
-  const { server, shutdown } = createServer([helloSpec], { port, stream: false })
+  const { server, shutdown } = await createServer([helloSpec], { port, stream: false })
   await new Promise(resolve => server.once('listening', resolve))
 
   // Confirm server is up
@@ -1276,7 +1276,7 @@ await test('shutdown() stops the server from accepting new connections', async (
 
 await test('shutdown() is idempotent — calling twice does not throw', async () => {
   const port = nextPort++
-  const { server, shutdown } = createServer([helloSpec], { port, stream: false })
+  const { server, shutdown } = await createServer([helloSpec], { port, stream: false })
   await new Promise(resolve => server.once('listening', resolve))
   shutdown()
   shutdown() // second call is a no-op
@@ -1295,7 +1295,7 @@ await test('in-flight request completes after shutdown() is called', async () =>
     view: (_s, server) => `<p>${server.data}</p>`
   }
 
-  const { server, shutdown } = createServer([slowSpec], { port, stream: false })
+  const { server, shutdown } = await createServer([slowSpec], { port, stream: false })
   await new Promise(resolve => server.once('listening', resolve))
 
   // Start a request but don't resolve its server fetch yet

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,13 +369,6 @@ export function validateSpec(spec) {
     }
   }
 
-  // hydrate — required whenever there is any client interactivity
-  if (!spec.hydrate && !spec.contentType) {
-    if (spec.mutations || spec.actions || spec.persist) {
-      warnings.push('spec.hydrate is missing — pages with mutations, actions, or persist need hydrate set to their browser-importable path, or client interactivity will silently do nothing')
-    }
-  }
-
   // 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', () => {