@invisibleloop/pulse 0.2.15 → 0.4.0

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

@@ -28,7 +28,7 @@ export default {
           ['<code>state</code>', '<code>object</code>', 'Yes', 'Initial client-side state. Deep-cloned on mount.'],
           ['<code>view</code>', '<code>function</code>', 'Yes', 'Returns an HTML string. Receives <code>(state, serverState)</code>.'],
           ['<code>meta</code>', '<code>object</code>', 'No', 'Page metadata: title, description, styles, OG tags, schema.'],
-          ['<code>hydrate</code>', '<code>string</code>', 'No', 'Browser-importable path to this spec file. Enables client hydration.'],
+          ['<code>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.'],
@@ -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.2.15",
+  "version": "0.4.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.2.15
+0.4.0

package/public/pulse-ui.css

@@ -1280,6 +1280,82 @@ hr.ui-divider {
 }
 .ui-nav-mobile .ui-nav-link:last-child { border-bottom: none; }
 .ui-nav-mobile-action { padding-top: .75rem; }
+.ui-nav-mobile-section {
+  font-size:      .7rem;
+  font-weight:    600;
+  text-transform: uppercase;
+  letter-spacing: .08em;
+  color:          var(--ui-muted, var(--muted, #6b6b80));
+  margin:         .75rem 0 .25rem;
+  padding:        0;
+}
+
+/* ─── Mega nav ───────────────────────────────────────────────────────────── */
+.ui-nav-mega-wrap { position: relative; }
+
+.ui-nav-mega-trigger {
+  background: none;
+  border: none;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  gap: .3rem;
+  padding: 0;
+  font: inherit;
+  font-size: .875rem;
+}
+
+.ui-nav-mega-chevron { transition: transform .2s ease; flex-shrink: 0; }
+.ui-nav-mega-wrap--open .ui-nav-mega-chevron { transform: rotate(180deg); }
+
+.ui-nav-mega-panel {
+  position: absolute;
+  top: calc(100% + .875rem);
+  left: 50%;
+  transform: translateX(-50%);
+  background: var(--ui-bg, var(--bg, #0d0d10));
+  border: 1px solid var(--ui-border, var(--border, #232329));
+  border-radius: var(--ui-radius, 8px);
+  box-shadow: 0 8px 40px rgba(0,0,0,.35);
+  padding: 1.5rem;
+  z-index: 200;
+  min-width: 360px;
+}
+.ui-nav-mega-panel[hidden] { display: none !important; }
+
+.ui-nav-mega-inner { display: flex; gap: 2rem; }
+
+.ui-nav-mega-col { flex: 1; min-width: 140px; }
+
+.ui-nav-mega-heading {
+  font-size: .7rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: .08em;
+  color: var(--ui-muted, var(--muted, #6b6b80));
+  margin: 0 0 .5rem;
+  padding: 0 .5rem;
+}
+
+.ui-nav-mega-item {
+  display: flex;
+  flex-direction: column;
+  gap: .15rem;
+  padding: .5rem;
+  border-radius: calc(var(--ui-radius, 8px) * .65);
+  transition: background .15s;
+}
+.ui-nav-mega-item:hover { background: var(--ui-surface, var(--surface, #111116)); }
+.ui-nav-mega-item-label {
+  font-size: .875rem;
+  font-weight: 500;
+  color: var(--ui-text, var(--text, #e2e2ea));
+  text-decoration: none;
+}
+.ui-nav-mega-item-label:hover { color: var(--ui-accent, var(--accent, #9b8dff)); }
+.ui-nav-mega-item-desc  { font-size: .75rem; color: var(--ui-muted, var(--muted, #6b6b80)); }
+
+[data-theme="light"] .ui-nav-mega-panel { box-shadow: 0 8px 40px rgba(0,0,0,.12); }
 
 /* ─── App Badge ──────────────────────────────────────────────────────────── */
 .ui-app-badge {

package/public/pulse-ui.js

@@ -131,19 +131,34 @@ document.addEventListener('keydown', (e) => {
 function initNav(el) {
   const burger = el.querySelector('.ui-nav-burger')
   const mobile = el.querySelector('.ui-nav-mobile')
-  if (!burger || !mobile) return
 
-  const open  = () => { el.classList.add('ui-nav--open');    burger.setAttribute('aria-expanded', 'true') }
-  const close = () => { el.classList.remove('ui-nav--open'); burger.setAttribute('aria-expanded', 'false') }
-  const toggle = () => el.classList.contains('ui-nav--open') ? close() : open()
+  // Mobile burger
+  if (burger && mobile) {
+    const open   = () => { el.classList.add('ui-nav--open');    burger.setAttribute('aria-expanded', 'true') }
+    const close  = () => { el.classList.remove('ui-nav--open'); burger.setAttribute('aria-expanded', 'false') }
+    const toggle = () => el.classList.contains('ui-nav--open') ? close() : open()
 
-  burger.addEventListener('click', toggle)
+    burger.addEventListener('click', toggle)
+    document.addEventListener('keydown', (e) => { if (e.key === 'Escape') close() })
+    document.addEventListener('click',   (e) => { if (!el.contains(e.target)) close() })
+    mobile.querySelectorAll('.ui-nav-link').forEach(a => a.addEventListener('click', close))
+  }
+
+  // Mega nav dropdowns
+  el.querySelectorAll('.ui-nav-mega-wrap').forEach(wrap => {
+    const trigger = wrap.querySelector('.ui-nav-mega-trigger')
+    const panel   = wrap.querySelector('.ui-nav-mega-panel')
+    if (!trigger || !panel) return
 
-  document.addEventListener('keydown', (e) => { if (e.key === 'Escape') close() })
-  document.addEventListener('click',   (e) => { if (!el.contains(e.target)) close() })
+    const openMega  = () => { panel.hidden = false; wrap.classList.add('ui-nav-mega-wrap--open');    trigger.setAttribute('aria-expanded', 'true') }
+    const closeMega = () => { panel.hidden = true;  wrap.classList.remove('ui-nav-mega-wrap--open'); trigger.setAttribute('aria-expanded', 'false') }
+    const toggleMega = () => panel.hidden ? openMega() : closeMega()
 
-  // Close when a mobile link is clicked (navigating away)
-  mobile.querySelectorAll('.ui-nav-link').forEach(a => a.addEventListener('click', close))
+    trigger.addEventListener('click', (e) => { e.stopPropagation(); toggleMega() })
+    document.addEventListener('keydown', (e) => { if (e.key === 'Escape') closeMega() })
+    document.addEventListener('click',   (e) => { if (!wrap.contains(e.target)) closeMega() })
+    panel.querySelectorAll('.ui-nav-mega-item').forEach(a => a.addEventListener('click', closeMega))
+  })
 }
 
 function runNavs() { document.querySelectorAll('.ui-nav').forEach(initNav) }

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/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