@invisibleloop/pulse 0.4.0 → 0.5.0

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/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.'],
@@ -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: '' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.4.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.4.0
+0.5.0

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')
   }
 

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', () => {