@invisibleloop/pulse 0.1.28 → 0.1.30

package/src/mcp/server.js

@@ -233,25 +233,27 @@ server.registerTool(
 server.registerTool(
   'pulse_create_page',
   {
-    description: `Create a new page in the Pulse project. Filename determines route: home.js → /, about.js → /about.
+    description: `Validate and register a page spec that you have already written to disk with the Write tool.
 
-IMPORTANT: Always follow these rules when writing the spec content:
+Workflow — always in this order:
+1. Write the spec file to src/pages/<name>.js using the Write tool (user sees the diff)
+2. Call pulse_create_page with just the name to validate it
+
+Do NOT pass content here — write the file first, then call this tool.
+
+Rules for the spec you write:
 - Import Pulse UI components from '@invisibleloop/pulse/ui' — never write raw HTML for nav, hero, button, card, input, etc.
 - Include '/pulse-ui.css' in meta.styles whenever using any UI component
-- Use u- utility classes for spacing/layout (u-flex, u-flex-col, u-gap-4, u-mt-8, u-text-center, etc.) — never inline styles
-- Use var(--ui-*) CSS tokens in any custom CSS — never hardcode hex colours
+- Use u- utility classes for spacing/layout — never inline styles
+- Use var(--ui-*) CSS tokens for any colour — never hardcode hex values
 - onSuccess AND onError are both required in every action
 - Do NOT use data-event on text inputs — use FormData in onStart/run instead
 - Always export default spec`,
     inputSchema: {
-      name:    z.string().describe('Filename without extension, e.g. "about" or "blog/post"'),
-      content: z.string().describe('Complete JS spec — must export default a valid Pulse spec object'),
+      name: z.string().describe('Filename without extension, matching what you wrote — e.g. "about" or "blog/post"'),
     },
   },
-  async ({ name, content }) => {
-    const validation = await validateContent(content)
-    if (validation.content[0].text.startsWith('Invalid')) return validation
-
+  async ({ name }) => {
     const segments = name.replace(/\.js$/, '').split('/')
     const fullPath = path.join(PAGES_DIR, ...segments) + '.js'
 
@@ -259,11 +261,16 @@ IMPORTANT: Always follow these rules when writing the spec content:
       return text('Error: page name must not escape src/pages/')
     }
 
-    fs.mkdirSync(path.dirname(fullPath), { recursive: true })
-    fs.writeFileSync(fullPath, content, 'utf8')
+    if (!fs.existsSync(fullPath)) {
+      return text(`Error: ${path.relative(ROOT, fullPath)} does not exist — write the file with the Write tool first, then call pulse_create_page.`)
+    }
+
+    const content = fs.readFileSync(fullPath, 'utf8')
+    const validation = await validateContent(content)
+    if (validation.content[0].text.startsWith('Invalid')) return validation
 
     const route = derivedRouteFromName(name)
-    return text(`Created ${path.relative(ROOT, fullPath)} → route "${route}"`)
+    return text(`Validated ${path.relative(ROOT, fullPath)} → route "${route}"`)
   }
 )
 
@@ -685,10 +692,19 @@ server.registerTool(
 server.registerTool(
   'pulse_update',
   {
-    description: 'Re-copy pulse-ui.css, pulse-ui.js, and the agent checklist from the installed package into public/. Run after npm update @invisibleloop/pulse, or when visual output looks wrong and you suspect stale CSS.',
+    description: 'Install the latest @invisibleloop/pulse package, then re-copy pulse-ui.css, pulse-ui.js, and the agent checklist into public/. One command does the full upgrade.',
     inputSchema: {},
   },
-  () => {
+  async () => {
+    // 1. npm install latest
+    const { execSync } = await import('child_process')
+    try {
+      execSync('npm install @invisibleloop/pulse@latest', { cwd: ROOT, stdio: 'pipe' })
+    } catch (e) {
+      return text(`npm install failed:\n${e.stderr?.toString() || e.message}`)
+    }
+
+    // 2. Copy assets from the newly installed package
     const pkgPublic  = new URL('../../public', import.meta.url).pathname
     const publicDir  = path.join(ROOT, 'public')
     const assets     = ['pulse-ui.css', 'pulse-ui.js', '.pulse-ui-version']
@@ -711,7 +727,7 @@ server.registerTool(
 
     const versionFile = path.join(publicDir, '.pulse-ui-version')
     const version     = fs.existsSync(versionFile) ? fs.readFileSync(versionFile, 'utf8').trim() : '?'
-    return text(`pulse-ui updated to v${version}\n\n${updated.map(f => `✓ ${f}`).join('\n')}`)
+    return text(`Pulse updated to v${version}\n\n${updated.map(f => `✓ ${f}`).join('\n')}`)
   }
 )
 
@@ -826,7 +842,7 @@ const PULSE_GUIDE_INDEX = `# Pulse Framework Guide
 - \`pulse_list_structure\` — list pages, components, and pulse-ui version. Call at the start of every session.
 - \`pulse_validate\` — validate spec content. Call after every write. Fix all errors AND warnings.
 - \`pulse_review\` — switch into reviewer mode and critically examine a spec you just built. Returns the source, rendered HTML, validator output, and a full review checklist. **Call this only after validate, Lighthouse (desktop + mobile), and tests all pass — it is the final phase before declaring done.**
-- \`pulse_create_page\` — create a new page spec. Validates before writing.
+- \`pulse_create_page\` — validate a page spec you already wrote to disk. **Always write the file with the Write tool first, then call this.** Never pass content to this tool.
 - \`pulse_create_component\` — create a reusable component.
 - \`pulse_create_store\` — create the pulse.store.js global store.
 - \`pulse_create_action\` — generate a correctly-structured action snippet.
@@ -834,7 +850,7 @@ const PULSE_GUIDE_INDEX = `# Pulse Framework Guide
 - \`pulse_restart_server\` — stop and restart the dev server.
 - \`pulse_build\` — production build + starts prod server on devPort+1 for Lighthouse. Returns the URL. Call \`pulse_restart_server\` after to return to dev. **Slow — takes 30–60 s. Tell the user before calling.**
 - \`pulse_check_version\` — check installed package version, static asset version, and latest on npm. Use this instead of running npm commands when the user asks about updates.
-- \`pulse_update\` — re-copy \`pulse-ui.css\`, \`pulse-ui.js\`, and the agent checklist from the installed package into \`public/\`. Run this after \`npm update @invisibleloop/pulse\`, or whenever visual output looks wrong and you suspect stale CSS.
+- \`pulse_update\` — install the latest \`@invisibleloop/pulse\` package and re-copy \`pulse-ui.css\`, \`pulse-ui.js\`, and the agent checklist into \`public/\`. One command does the full upgrade.
 
 **Chrome DevTools MCP tools** (globally available):
 - \`mcp__chrome-devtools__take_screenshot\` — visual screenshot of the page.

package/src/server/index.js

@@ -16,7 +16,11 @@ import fs     from 'fs'
 import path   from 'path'
 import zlib   from 'zlib'
 import crypto from 'crypto'
-import { promisify } from 'util'
+import { promisify }  from 'util'
+import { createRequire } from 'module'
+
+const _require = createRequire(import.meta.url)
+export const version = _require('../../package.json').version
 import { renderToString, renderToStream, wrapDocument, resolveServerState } from '../runtime/ssr.js'
 import { validateSpec } from '../spec/schema.js'
 import { validateStore, resolveStoreState } from '../store/index.js'
@@ -541,14 +545,16 @@ export function createServer(specs, options = {}) {
         }
       }
 
-      // Build canonical URL — prefer spec.meta.canonical, otherwise derive from request.
+      // Derive the canonical base URL from the request.
       // Canonical path follows the trailingSlash mode so the <link> is consistent with redirects.
+      // spec.meta.canonical (string or function) is resolved inside each handler, where serverState
+      // is available — allowing dynamic canonicals from server fetcher results.
       const proto        = req.headers['x-forwarded-proto'] || 'http'
       const host         = req.headers['x-forwarded-host'] || req.headers.host || `localhost:${port}`
       const canonicalPath = trailingSlash === 'add' && pathname !== '/'
         ? (pathname.endsWith('/') ? pathname : pathname + '/')
         : (pathname !== '/' && pathname.endsWith('/') ? pathname.slice(0, -1) : pathname)
-      const canonicalUrl = spec.meta?.canonical || `${proto}://${host}${canonicalPath}`
+      const canonicalBase = `${proto}://${host}${canonicalPath}`
 
       // Raw content spec (RSS, sitemap, JSON API, webhooks) — bypass HTML pipeline
       if (spec.contentType) {
@@ -563,9 +569,9 @@ export function createServer(specs, options = {}) {
       }
 
       if (stream) {
-        await handleStreamResponse(spec, ctx, req, res, extraBody, dev, canonicalUrl, nonce, runtimeBundle, defaultCache, store, csp)
+        await handleStreamResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, store, csp)
       } else {
-        await handleStringResponse(spec, ctx, req, res, extraBody, dev, canonicalUrl, nonce, runtimeBundle, defaultCache, store, csp)
+        await handleStringResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, store, csp)
       }
 
     } catch (err) {
@@ -676,7 +682,7 @@ async function handleNavResponse(spec, ctx, res, dev = false) {
  * Render to a complete string then send — simpler, easier to cache.
  * Checks the in-process page cache before rendering; stores result after.
  */
-async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalUrl = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}) {
+async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalBase = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}) {
   const cacheKey = spec.route + '\0' + JSON.stringify(ctx.params) + '\0' + JSON.stringify(ctx.query)
   // Pages with server data or store data embed a nonce'd __PULSE_SERVER__ script — don't cache them
   const ttl      = (!spec.server && !spec.store?.length) ? pageCacheTtl(spec, dev, defaultCache) : 0
@@ -689,6 +695,12 @@ async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = f
     fromCache  = true
   } else {
     const { html: content, serverState, timing } = await cachedRenderToString(spec, ctx, dev)
+    // Resolve canonical — supports a function receiving (ctx, serverState) so the URL can be
+    // derived from server fetcher results (e.g. a canonical slug from a database lookup).
+    const canonicalRaw = spec.meta?.canonical
+    const canonicalUrl = typeof canonicalRaw === 'function'
+      ? (canonicalRaw(ctx, serverState) || canonicalBase)
+      : (canonicalRaw || canonicalBase)
     const canonicalTag      = canonicalUrl ? `<link rel="canonical" href="${escHtml(canonicalUrl)}">` : ''
     const resolvedSpec      = { ...spec, meta: resolveMeta(spec.meta, ctx) }
     const resolvedExtraBody = typeof extraBody === 'function' ? extraBody(nonce) : extraBody
@@ -720,7 +732,7 @@ async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = f
  * Stream the response — shell first, deferred segments follow.
  * On a page-cache hit, serves the buffered HTML as a string (no streaming needed).
  */
-async function handleStreamResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalUrl = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}) {
+async function handleStreamResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalBase = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}) {
   // Serve from in-process page cache when available — skip streaming overhead.
   // Pages with spec.server or spec.store embed a nonce'd __PULSE_SERVER__ script so are never cached.
   const cacheKey = spec.route + '\0' + JSON.stringify(ctx.params) + '\0' + JSON.stringify(ctx.query)
@@ -748,6 +760,13 @@ async function handleStreamResponse(spec, ctx, req, res, extraBody = '', dev = f
   // Write the document opening immediately so the browser starts parsing
   const meta  = resolveMeta(spec.meta, ctx)
   const title = meta.title || 'Pulse'
+  // Resolve canonical — supports a string or a function receiving (ctx).
+  // Note: server fetcher results are not yet available when the <head> is written in streaming mode.
+  // If your canonical depends on server data, use stream: false on that spec, or set it as a string.
+  const canonicalRaw = spec.meta?.canonical
+  const canonicalUrl = typeof canonicalRaw === 'function'
+    ? (canonicalRaw(ctx) || canonicalBase)
+    : (canonicalRaw || canonicalBase)
 
   const stylePreloads = (meta.styles || [])
     .map(href => `  <link rel="preload" as="style" href="${escHtml(href)}">`)

package/src/server/server.test.js

@@ -685,6 +685,53 @@ await test('meta.canonical overrides auto-generated canonical URL', async () =>
   })
 })
 
+await test('meta.canonical as a function receives ctx (string path)', async () => {
+  const spec = {
+    route: '/about',
+    meta: { title: 'About', styles: [], canonical: (ctx) => `https://example.com${ctx.params.slug ?? '/about'}` },
+    state: {},
+    view: () => `<main id="main-content"><h1>About</h1></main>`,
+  }
+  await withServer([spec], { stream: false }, async (port) => {
+    const { body } = await get(port, '/about')
+    assert(body.includes(`<link rel="canonical" href="https://example.com/about">`),
+      `Expected function canonical, got: ${body.slice(0, 500)}`)
+  })
+})
+
+await test('meta.canonical as a function receives serverState (string path)', async () => {
+  const spec = {
+    route: '/product',
+    meta: {
+      title:     'Product',
+      styles:    [],
+      canonical: (ctx, serverState) => `https://example.com/products/${serverState?.data?.slug ?? 'fallback'}`,
+    },
+    state: {},
+    server: { data: async () => ({ slug: 'my-product-slug' }) },
+    view: (state, server) => `<main id="main-content"><h1>${server.data.slug}</h1></main>`,
+  }
+  await withServer([spec], { stream: false }, async (port) => {
+    const { body } = await get(port, '/product')
+    assert(body.includes(`<link rel="canonical" href="https://example.com/products/my-product-slug">`),
+      `Expected serverState-derived canonical, got: ${body.slice(0, 500)}`)
+  })
+})
+
+await test('meta.canonical as a function receives ctx in streaming mode', async () => {
+  const spec = {
+    route: '/about',
+    meta: { title: 'About', styles: [], canonical: (ctx) => `https://example.com/about` },
+    state: {},
+    view: () => `<main id="main-content"><h1>About</h1></main>`,
+  }
+  await withServer([spec], { stream: true }, async (port) => {
+    const { body } = await get(port, '/about')
+    assert(body.includes(`<link rel="canonical" href="https://example.com/about">`),
+      `Expected function canonical in stream, got: ${body.slice(0, 500)}`)
+  })
+})
+
 await test('canonical tag injected in streaming response', async () => {
   await withServer([canonicalSpec], { stream: true }, async (port) => {
     const { body } = await get(port, '/about')

package/src/ui/stat.js

@@ -39,7 +39,7 @@ export function stat({
 
   const changeHtml = change
     ? `<p class="ui-stat-change ui-stat-change--${e(trend)}">
-  <span aria-label="${e(TREND_LABELS[trend])}">${TREND_ICONS[trend]}</span>
+  <span role="img" aria-label="${e(TREND_LABELS[trend])}">${TREND_ICONS[trend]}</span>
   ${e(change)}
 </p>`
     : ''

package/src/ui/ui.test.js

@@ -346,6 +346,12 @@ test('stat: renders change with trend class', () => {
   assert.match(html, /\+5%/)
 })
 
+test('stat: trend icon span has role=img for valid aria-label', () => {
+  const html = stat({ label: 'X', value: '10', change: '+5%', trend: 'up' })
+  assert.match(html, /role="img"/)
+  assert.match(html, /aria-label="increase"/)
+})
+
 test('stat: no change rendered when change is empty', () => {
   const html = stat({ label: 'X', value: '10' })
   assert.doesNotMatch(html, /ui-stat-change/)

package/docs/public/dist/accessibility.boot-5DVTARJU.js

@@ -1,115 +0,0 @@
-import{a}from"./runtime-QFURDKA2.js";import{a as r,b as c,c as l,d,e,g as t,h as i,i as u}from"./runtime-L2HNXIHW.js";import{a as s,b as m}from"./runtime-B73WLANC.js";var{prev:p,next:g}=r("/accessibility"),n={route:"/accessibility",meta:{title:"Accessibility \u2014 Pulse Docs",description:"Keyboard navigation, focus management, semantic HTML, and ARIA patterns in Pulse.",styles:["/docs.css"]},state:{},view:()=>c({currentHref:"/accessibility",prev:p,next:g,content:`
-      ${l("Accessibility")}
-      ${d("Pulse enforces a 100 Lighthouse Accessibility score as the baseline. The foundations \u2014 skip link, focus styles, and focus management on navigation \u2014 are provided by the framework on every page. There is nothing to configure and nothing to forget.")}
-
-      ${e("built-in","What the framework provides")}
-      ${i(["Feature","How"],[["Skip link","Injected on every page as the first focusable element. Targets <code>#main-content</code>. Visible only on focus."],["Focus styles","<code>:focus-visible</code> outline applied globally \u2014 purple, 3px, offset 2px. Suppressed for mouse users via <code>:focus:not(:focus-visible)</code>."],["Navigation focus","After client-side navigation, focus moves to <code>#main-content</code>, <code>&lt;main&gt;</code>, or <code>&lt;h1&gt;</code> \u2014 whichever is found first. Screen reader users hear the new page heading without a full reload."]])}
-      ${u("note",'The skip link targets <code>#main-content</code>. Pages use <code>&lt;main id="main-content"&gt;</code> as the content wrapper so the link resolves correctly.')}
-
-      ${e("structure","Page structure")}
-      <p>Each page view is wrapped in <code>&lt;main id="main-content"&gt;</code> with a single <code>&lt;h1&gt;</code> that describes the current page. Landmark elements communicate structure to assistive technology:</p>
-      ${t(a(`view: (state) => \`
-  <main id="main-content">
-    <h1>Page title</h1>
-    <!-- page content -->
-  </main>
-\``,"js"))}
-      ${i(["Element","Purpose"],[["<code>&lt;header&gt;</code>","Site header, logo, primary nav"],["<code>&lt;nav&gt;</code>","Navigation links \u2014 <code>aria-label</code> distinguishes multiple navs"],['<code>&lt;main id="main-content"&gt;</code>',"Primary page content \u2014 one per page"],["<code>&lt;aside&gt;</code>","Supplementary content (sidebars, related links)"],["<code>&lt;footer&gt;</code>","Site footer"]])}
-
-      ${e("interactive","Interactive elements")}
-      <p>Actions are expressed as <code>&lt;button&gt;</code> elements, navigation as <code>&lt;a href&gt;</code> links. Both are keyboard-accessible by default. <code>&lt;div&gt;</code> and <code>&lt;span&gt;</code> elements with click handlers are not reachable by keyboard:</p>
-      ${t(a(`<!-- Keyboard accessible -->
-<button data-event="toggle">Open menu</button>
-<a href="/about">About</a>
-
-<!-- Not keyboard accessible \u2014 avoid -->
-<div data-event="toggle">Open menu</div>
-<span onclick="...">About</span>`,"html"))}
-      <p>Buttons that toggle state carry <code>aria-expanded</code> or <code>aria-pressed</code> to communicate the current state to screen readers:</p>
-      ${t(a(`view: (state) => \`
-  <button data-event="toggleMenu" aria-expanded="\${state.menuOpen}">
-    Menu
-  </button>
-  \${state.menuOpen ? \`<nav>...</nav>\` : ''}
-\``,"js"))}
-
-      ${e("focus","Focus management")}
-      <p>When a modal or dialog opens, focus moves inside it. When it closes, focus returns to the element that opened it. Since Pulse updates the DOM via morphing rather than a full replacement, the triggering element stays in the DOM and receives focus back naturally.</p>
-      <p>The <code>autofocus</code> attribute on the first interactive element inside newly revealed content moves focus there after the DOM update \u2014 no JavaScript required:</p>
-      ${t(a(`view: (state) => \`
-  <button data-event="openDialog">Delete item</button>
-
-  \${state.dialogOpen ? \`
-    <div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
-      <h2 id="dialog-title">Confirm deletion</h2>
-      <p>This cannot be undone.</p>
-      <button autofocus data-event="confirmDelete">Delete</button>
-      <button data-event="closeDialog">Cancel</button>
-    </div>
-  \` : ''}
-\``,"js"))}
-
-      ${e("live-regions","Dynamic content announcements")}
-      <p>State changes that produce status messages \u2014 loading indicators, confirmations, validation errors \u2014 are wrapped in live regions so screen readers announce them without a page reload:</p>
-      ${i(["Role","Politeness","Used for"],[['<code>role="status"</code>',"Polite \u2014 waits for the user to finish","Loading states, success messages, counts"],['<code>role="alert"</code>',"Assertive \u2014 interrupts immediately","Validation errors, destructive confirmations"]])}
-      ${t(a(`view: (state) => \`
-  <form data-action="submit">
-    <!-- fields -->
-    <button type="submit" \${state.status === 'loading' ? 'disabled' : ''}>
-      \${state.status === 'loading' ? 'Saving\u2026' : 'Save'}
-    </button>
-  </form>
-
-  \${state.status === 'loading' ? \`
-    <p role="status">Saving\u2026</p>
-  \` : ''}
-
-  \${state.errors.length ? \`
-    <div role="alert">
-      \${state.errors.map(e => \`<p>\${e.message}</p>\`).join('')}
-    </div>
-  \` : ''}
-\``,"js"))}
-
-      ${e("forms","Forms")}
-      <p>Form controls are paired with <code>&lt;label&gt;</code> elements. Error messages are linked to their input via <code>aria-describedby</code> so screen readers announce them when the field receives focus:</p>
-      ${t(a(`<form data-action="submit">
-  <div class="field">
-    <label for="email">Email</label>
-    <input
-      id="email"
-      name="email"
-      type="email"
-      required
-      aria-describedby="\${state.emailError ? 'email-error' : ''}"
-    >
-    \${state.emailError
-      ? \`<p id="email-error" role="alert">\${state.emailError}</p>\`
-      : ''}
-  </div>
-
-  <fieldset>
-    <legend>Notification preferences</legend>
-    <label><input type="checkbox" name="email-notifs"> Email</label>
-    <label><input type="checkbox" name="sms-notifs"> SMS</label>
-  </fieldset>
-
-  <button type="submit">Submit</button>
-</form>`,"html"))}
-
-      ${e("images","Images")}
-      <p>Decorative images carry <code>alt=""</code> so screen readers skip them. Informative images have descriptive alt text. Icon-only buttons are labelled with <code>aria-label</code>, with the icon marked <code>aria-hidden="true"</code>:</p>
-      ${t(a(`<!-- Informative image -->
-<img src="/team.jpg" alt="The Pulse team at the 2025 offsite" width="800" height="450">
-
-<!-- Decorative image -->
-<img src="/divider.svg" alt="" width="600" height="4">
-
-<!-- Icon-only button -->
-<button aria-label="Close">
-  <svg aria-hidden="true" focusable="false">...</svg>
-</button>`,"html"))}
-
-      ${e("lighthouse","Lighthouse score")}
-      <p>Every page is expected to score 100 on Lighthouse Accessibility. Run <code>/pulse-report</code> after every new page or significant change. Regressions \u2014 contrast failures, missing labels, unreachable controls \u2014 are caught before they reach users.</p>
-    `})};var o=document.getElementById("pulse-root");o&&!o.dataset.pulseMounted&&(o.dataset.pulseMounted="1",s(n,o,window.__PULSE_SERVER__||{},{ssr:!0}),m(o,s));var k=n;export{k as default};

package/docs/public/dist/actions.boot-P66HKQEM.js

@@ -1,164 +0,0 @@
-import{a as o}from"./runtime-QFURDKA2.js";import{a as i,b as d,c,d as l,e,g as t,h as u,i as a}from"./runtime-L2HNXIHW.js";import{a as s,b as m}from"./runtime-B73WLANC.js";var{prev:p,next:f}=i("/actions"),n={route:"/actions",meta:{title:"Actions \u2014 Pulse Docs",description:"Async operations in Pulse \u2014 lifecycle, FormData, error handling.",styles:["/docs.css"]},state:{},view:()=>d({currentHref:"/actions",prev:p,next:f,content:`
-      ${c("Actions")}
-      ${l("Actions handle async operations with an enforced lifecycle. The order of steps \u2014 capture inputs, validate, run, succeed or fail \u2014 is fixed. Skipping validation or running async work before showing a loading state is not possible within the action structure.")}
-
-      ${e("lifecycle","The action lifecycle")}
-      <p>When a form with <code>data-action</code> is submitted, Pulse runs the action through a fixed sequence of steps:</p>
-      ${t(o(`onStart(state, formData)
-  \u2193  (optional) validate \u2014 checks spec.validation rules
-run(state, serverState, formData)
-  \u2193  success           \u2193  error
-onSuccess(state, payload)   onError(state, err)`,"bash"))}
-      <p>Each step triggers a view re-render, so the UI always reflects the current state \u2014 loading, validated, succeeded, or failed. The sequence cannot be reordered.</p>
-
-      ${e("defining","Defining an action")}
-      ${t(o(`export default {
-  route: '/contact',
-  state: {
-    status: 'idle',   // 'idle' | 'loading' | 'success' | 'error'
-    errors: [],
-  },
-  validation: {
-    'fields.name':  { required: true, minLength: 2 },
-    'fields.email': { required: true, format: 'email' },
-    'fields.message': { required: true, minLength: 10 },
-  },
-  actions: {
-    submit: {
-      // 1. Immediately update state \u2014 show loading indicator
-      onStart: (state, formData) => ({
-        status: 'loading',
-        errors: [],
-        // Capture form values into state before validation runs
-        fields: {
-          name:    formData.get('name'),
-          email:   formData.get('email'),
-          message: formData.get('message'),
-        },
-      }),
-
-      // 2. Run spec.validation before proceeding to run()
-      validate: true,
-
-      // 3. Perform the async work
-      run: async (state, serverState, formData) => {
-        const res = await fetch('/api/contact', {
-          method:  'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body:    JSON.stringify(Object.fromEntries(formData)),
-        })
-        if (!res.ok) throw new Error('Request failed')
-        return res.json()
-      },
-
-      // 4a. Success
-      onSuccess: (state, payload) => ({
-        status: 'success',
-        errors: [],
-      }),
-
-      // 4b. Error \u2014 payload may have validation errors
-      onError: (state, err) => ({
-        status: 'error',
-        errors: err?.validation ?? [{ message: err.message }],
-      }),
-    },
-  },
-}`,"js"))}
-
-      ${e("binding","Binding actions to forms")}
-      <p>A <code>data-action</code> attribute on a <code>&lt;form&gt;</code> element binds it to an action. When the form is submitted, Pulse creates a <code>FormData</code> object from the form's inputs and passes it through the action lifecycle:</p>
-      ${t(o(`<form data-action="submit">
-  <input name="name"    type="text"  placeholder="Your name">
-  <input name="email"   type="email" placeholder="Email">
-  <textarea name="message" placeholder="Message"></textarea>
-  <button type="submit">Send</button>
-</form>`,"html"))}
-      ${a("note","Pulse intercepts and prevents the default form submission. The action lifecycle is fully in control of what happens with the data \u2014 no manual <code>event.preventDefault()</code> needed.")}
-
-      ${e("on-start","onStart")}
-      <p><code>onStart(state, formData)</code> runs synchronously as soon as the form is submitted, before any async work begins. It sets a loading state, captures form values into state so validation can check them, and clears previous errors.</p>
-      ${a("warning","<code>onStart</code> runs <strong>before</strong> validation. <code>FormData</code> values are captured into state first, because the HTML re-renders (destroying the form inputs) once validation runs. All form values are captured here so validation can read them from state via dot-paths.")}
-
-      ${e("validate","validate")}
-      <p>Set <code>validate: true</code> to run the spec's <a href="/validation">validation rules</a> after <code>onStart</code>. If validation fails, <code>onError</code> is called immediately \u2014 <code>run</code> is never reached. Async work cannot execute against invalid input.</p>
-      ${t(o(`// Validation error structure
-{
-  message:    'Validation failed',
-  validation: [
-    { field: 'fields.email', rule: 'format', message: 'Must be a valid email' },
-    { field: 'fields.name',  rule: 'required', message: 'Required' },
-  ]
-}`,"js"))}
-      <p>Access the errors in <code>onError</code>:</p>
-      ${t(o(`onError: (state, err) => ({
-  status: 'error',
-  errors: err?.validation ?? [{ message: err.message }],
-})`,"js"))}
-
-      ${e("run","run")}
-      <p><code>run(state, serverState, formData)</code> is where the async work happens. Throw or reject to trigger <code>onError</code>. The return value is passed to <code>onSuccess</code> as <code>payload</code>.</p>
-      ${t(o(`run: async (state, serverState, formData) => {
-  const res = await fetch('/api/submit', {
-    method: 'POST',
-    body:   formData,
-  })
-  if (!res.ok) {
-    const err = await res.json()
-    throw Object.assign(new Error('Server error'), err)
-  }
-  return res.json()   // \u2192 onSuccess payload
-},`,"js"))}
-
-      ${e("on-success","onSuccess")}
-      <p><code>onSuccess(state, payload)</code> receives the current state and whatever <code>run</code> returned. Return a partial state update:</p>
-      ${t(o(`onSuccess: (state, payload) => ({
-  status: 'success',
-  userId: payload.id,
-})`,"js"))}
-
-      ${e("on-error","onError")}
-      <p><code>onError(state, err)</code> receives the current state and the thrown error. Return a partial state update to surface the error in the view:</p>
-      ${t(o(`onError: (state, err) => ({
-  status: 'error',
-  errors: err?.validation ?? [{ message: err.message }],
-})`,"js"))}
-
-      ${e("toast","Toast notifications")}
-      <p>Return <code>_toast</code> from any action hook to show a notification. It is stripped from spec state automatically \u2014 it never appears in <code>getState()</code> or the view.</p>
-      ${t(o(`onSuccess: (state, payload) => ({
-  status:  'success',
-  _toast:  { message: 'Saved successfully', variant: 'success' },
-}),
-
-onError: (state, err) => ({
-  status:  'error',
-  errors:  err?.validation ?? [{ message: err.message }],
-  _toast:  { message: 'Something went wrong', variant: 'error' },
-}),`,"js"))}
-      <p><code>_toast</code> works in <code>onStart</code>, <code>onSuccess</code>, and <code>onError</code>, and also in mutations. The toast container is injected into <code>document.body</code> once and survives client-side navigations.</p>
-      ${u(["Option","Type","Default",""],[["<code>message</code>","string","\u2014","Required. The notification text."],["<code>variant</code>","<code>success | error | warning | info</code>","<code>info</code>",""],["<code>duration</code>","number (ms)","<code>4000</code>","Auto-dismiss delay. <code>0</code> = sticky until dismissed."]])}
-
-      ${e("store-update","Pushing to the global store")}
-      <p>Return <code>_storeUpdate</code> from <code>onSuccess</code> to push a partial update into the <a href="/store">global store</a>. Every mounted page that subscribes to the updated keys re-renders immediately \u2014 no navigation, no polling.</p>
-      ${t(o(`onSuccess: (state, theme) => ({
-  saved:        true,
-  _storeUpdate: { settings: { theme } },   // \u2190 merged into global store state
-}),`,"js"))}
-      <p><code>_storeUpdate</code> is stripped from the page's own state \u2014 only the rest of the return object is merged into local state as usual. See <a href="/store">Global Store</a> for the full store API.</p>
-
-      ${e("rendering-errors","Rendering errors in the view")}
-      ${t(o(`view: (state) => \`
-  <form data-action="submit">
-    \${state.errors.map(e => \`
-      <p class="error">
-        \${e.field ? \`<strong>\${e.field}:</strong> \` : ''}\${e.message}
-      </p>
-    \`).join('')}
-    <!-- ... form fields ... -->
-    <button \${state.status === 'loading' ? 'disabled' : ''}>
-      \${state.status === 'loading' ? 'Sending\u2026' : 'Send'}
-    </button>
-  </form>
-\``,"js"))}
-    `})};var r=document.getElementById("pulse-root");r&&!r.dataset.pulseMounted&&(r.dataset.pulseMounted="1",s(n,r,window.__PULSE_SERVER__||{},{ssr:!0}),m(r,s));var $=n;export{$ as default};