@invisibleloop/pulse 0.1.21

package/docs/src/pages/testing.js

@@ -0,0 +1,198 @@
+import { renderLayout, h1, lead, section, codeBlock, callout, table } from '../lib/layout.js'
+import { prevNext } from '../lib/nav.js'
+import { highlight } from '../lib/highlight.js'
+
+const { prev, next } = prevNext('/testing')
+
+export default {
+  route: '/testing',
+  meta: {
+    title: 'Testing — Pulse Docs',
+    description: 'Test Pulse view functions with renderSync and render — query the HTML output with CSS-like selectors, no DOM required.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/testing',
+    prev,
+    next,
+    content: `
+      ${h1('Testing')}
+      ${lead('Pulse ships a built-in testing helper at <code>@invisibleloop/pulse/testing</code>. Render a spec\'s view in tests and query the HTML output with CSS-like selectors — no DOM, no jsdom, no extra dependencies.')}
+
+      ${section('quick-start', 'Quick start')}
+      ${codeBlock(highlight(`import { renderSync, render } from '@invisibleloop/pulse/testing'
+import assert from 'node:assert/strict'
+import spec from './src/pages/counter.js'
+
+// Synchronous — calls view directly, mock state and server
+const result = renderSync(spec, { state: { count: 5 } })
+assert(result.has('button'))
+assert.equal(result.get('#count').text, '5')
+
+// Async — runs real spec.server fetchers (or pass server to mock them)
+const result = await render(productSpec, {
+  server: { product: { id: 1, name: 'Widget', price: 9.99 } }
+})
+assert.equal(result.get('h1').text, 'Widget')
+assert.equal(result.count('li'), 3)`, 'js'))}
+
+      ${section('render-sync', 'renderSync(spec, options?)')}
+      <p>Synchronous. Calls the view function directly — no server fetcher resolution. The fastest path for unit testing pure view functions.</p>
+      ${table(
+        ['Option', 'Type', 'Default', 'Description'],
+        [
+          ['<code>state</code>',  '<code>object</code>', '<code>{}</code>', 'State overrides merged with <code>spec.state</code>.'],
+          ['<code>server</code>', '<code>object</code>', '<code>{}</code>', 'Server state passed directly to the view. Fetchers are never called.'],
+        ]
+      )}
+      ${codeBlock(highlight(`import { renderSync } from '@invisibleloop/pulse/testing'
+
+const result = renderSync(formSpec, {
+  state:  { name: 'Alice', email: 'alice@example.com' },
+  server: { plans: [{ id: 'pro', label: 'Pro' }] },
+})`, 'js'))}
+
+      ${section('render-async', 'render(spec, options?)')}
+      <p>Async. Two modes — mock or integration:</p>
+      <ul>
+        <li><strong>Mock mode</strong> — pass <code>server</code> to use that data directly. Fetchers are not called. Fast and deterministic.</li>
+        <li><strong>Integration mode</strong> — omit <code>server</code> and real <code>spec.server</code> fetchers run. Pass <code>ctx</code> to set params, cookies, headers, etc.</li>
+      </ul>
+      ${table(
+        ['Option', 'Type', 'Default', 'Description'],
+        [
+          ['<code>state</code>',  '<code>object</code>', '<code>{}</code>',     'State overrides merged with <code>spec.state</code>.'],
+          ['<code>server</code>', '<code>object</code>', '<code>undefined</code>', 'Server state passed directly to the view. When set, fetchers are skipped entirely.'],
+          ['<code>ctx</code>',   '<code>object</code>', '<code>{}</code>',     'Request context passed to <code>spec.server</code> fetchers (integration mode only). Accepts <code>params</code>, <code>query</code>, <code>cookies</code>, <code>headers</code>, etc.'],
+        ]
+      )}
+      ${codeBlock(highlight(`import { render } from '@invisibleloop/pulse/testing'
+
+// Mock — skip fetchers
+const result = await render(productSpec, {
+  server: { product: { id: 42, name: 'Gadget' } }
+})
+
+// Integration — real fetchers, with ctx
+const result = await render(productSpec, {
+  ctx: { params: { id: '42' }, cookies: { session: 'abc' } }
+})`, 'js'))}
+
+      ${section('render-result', 'RenderResult')}
+      <p>Both functions return the same <code>RenderResult</code> object.</p>
+      ${table(
+        ['Property / method', 'Returns', 'Description'],
+        [
+          ['<code>.html</code>',                           '<code>string</code>',             'Raw HTML string from the view.'],
+          ['<code>.state</code>',                          '<code>object</code>',             'Client state used for rendering.'],
+          ['<code>.server</code>',                         '<code>object</code>',             'Server state used for rendering.'],
+          ['<code>.text()</code>',                         '<code>string</code>',             'All text content — tags stripped, entities decoded, whitespace collapsed.'],
+          ['<code>.has(selector)</code>',                  '<code>boolean</code>',            'True if any element matches selector.'],
+          ['<code>.find(selector)</code>',                 '<code>Element | null</code>',     'First matching element, or null.'],
+          ['<code>.get(selector)</code>',                  '<code>Element</code>',            'First matching element. Throws with a clear message if not found.'],
+          ['<code>.findAll(selector)</code>',              '<code>Element[]</code>',          'All matching elements.'],
+          ['<code>.count(selector)</code>',                '<code>number</code>',             'Number of matching elements.'],
+          ['<code>.attr(selector, name)</code>',           '<code>string | null</code>',      'Attribute value of the first matching element. Null if element or attribute absent.'],
+        ]
+      )}
+
+      ${section('element', 'Element')}
+      <p>Elements returned by <code>find()</code>, <code>get()</code>, and <code>findAll()</code> support the same query methods scoped to their own subtree.</p>
+      ${table(
+        ['Property / method', 'Returns', 'Description'],
+        [
+          ['<code>.tag</code>',            '<code>string</code>',         'Tag name (lowercase).'],
+          ['<code>.text</code>',           '<code>string</code>',         'All text content within the element, whitespace-collapsed.'],
+          ['<code>.attrs</code>',          '<code>object</code>',         'Parsed attribute map. Boolean attrs (e.g. <code>disabled</code>) have value <code>true</code>.'],
+          ['<code>.attr(name)</code>',     '<code>string | null</code>',  'Get one attribute. Returns <code>""</code> for boolean attrs, <code>null</code> if absent — mirrors <code>getAttribute()</code>.'],
+          ['<code>.find(selector)</code>', '<code>Element | null</code>',  'First matching descendant.'],
+          ['<code>.findAll(selector)</code>', '<code>Element[]</code>',   'All matching descendants.'],
+          ['<code>.has(selector)</code>',  '<code>boolean</code>',        'True if any descendant matches selector.'],
+        ]
+      )}
+
+      ${section('selectors', 'Supported selectors')}
+      <p>The selector engine supports the most common patterns. Descendant combinators (<code>div p</code>) are not supported — use <code>element.findAll()</code> to search within a matched element instead.</p>
+      ${table(
+        ['Selector', 'Example', 'Matches'],
+        [
+          ['Tag',              '<code>button</code>',                  'Any <code>&lt;button&gt;</code>'],
+          ['Class',            '<code>.ui-btn</code>',                 'Elements with that class'],
+          ['ID',               '<code>#submit</code>',                 'Element with that id'],
+          ['Attribute present','<code>[disabled]</code>',              'Elements with a <code>disabled</code> attribute'],
+          ['Attribute value',  '<code>[type="submit"]</code>',         'Elements where <code>type</code> equals <code>submit</code>'],
+          ['Compound',         '<code>button.primary[disabled]</code>', 'All conditions on the same element'],
+        ]
+      )}
+      ${codeBlock(highlight(`result.has('button')                         // any <button>
+result.has('.ui-btn--primary')               // BEM modifier class
+result.has('[data-action="submit"]')         // data attribute
+result.has('input[type="email"][required]')  // compound
+result.get('form').findAll('input')          // inputs inside form`, 'js'))}
+
+      ${section('patterns', 'Common patterns')}
+      ${codeBlock(highlight(`// Assert an element exists and check its text
+assert.equal(result.get('h1').text, 'Page Title')
+
+// Assert an element does NOT exist
+assert(!result.has('.error-message'))
+
+// Check an attribute value
+assert.equal(result.attr('input[name="email"]', 'type'), 'email')
+
+// Boolean attributes — attr() returns '' (not 'disabled')
+assert.equal(result.attr('[disabled]', 'disabled'), '')
+assert(result.get('[disabled]').attr('disabled') === '')
+
+// Count elements
+assert.equal(result.count('li'), 3)
+
+// Inspect all items
+const items = result.findAll('li')
+assert.equal(items[0].text, 'Alpha')
+assert.equal(items[1].text, 'Beta')
+
+// Scope a search to a subtree
+const form = result.get('form')
+assert(form.has('button[type="submit"]'))
+assert.equal(form.count('input'), 2)
+
+// Text content decodes entities
+// <p>&lt;b&gt;bold&lt;/b&gt;</p> → text === '<b>bold</b>'
+assert.equal(result.get('p').text, '<b>bold</b>')`, 'js'))}
+
+      ${section('test-file', 'Example test file')}
+      ${codeBlock(highlight(`/**
+ * src/pages/counter.test.js
+ * run: node src/pages/counter.test.js
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { renderSync } from '@invisibleloop/pulse/testing'
+import spec from './counter.js'
+
+test('renders the current count', () => {
+  const result = renderSync(spec, { state: { count: 7 } })
+  assert.equal(result.get('#count').text, '7')
+})
+
+test('increment mutation returns count + 1', () => {
+  const next = spec.mutations.increment({ count: 0 })
+  assert.equal(next.count, 1)
+})
+
+test('decrement mutation returns count - 1', () => {
+  const next = spec.mutations.decrement({ count: 5 })
+  assert.equal(next.count, 4)
+})
+
+test('view renders increment and decrement buttons', () => {
+  const result = renderSync(spec)
+  assert(result.has('[data-event="increment"]'))
+  assert(result.has('[data-event="decrement"]'))
+})`, 'js'))}
+      ${callout('note', 'Use <code>renderSync</code> for mutations and pure view tests — it\'s synchronous and needs no <code>await</code>. Use <code>render</code> when your spec has <code>server</code> fetchers you want to exercise for integration coverage.')}
+    `,
+  }),
+}

package/docs/src/pages/validation.js

@@ -0,0 +1,138 @@
+import { renderLayout, h1, lead, section, sub, codeBlock, callout, table } from '../lib/layout.js'
+import { prevNext } from '../lib/nav.js'
+import { highlight } from '../lib/highlight.js'
+
+const { prev, next } = prevNext('/validation')
+
+export default {
+  route: '/validation',
+  meta: {
+    title: 'Validation — Pulse Docs',
+    description: 'Declarative validation rules in Pulse — syntax, formats, dot-path notation, and error handling.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/validation',
+    prev,
+    next,
+    content: `
+      ${h1('Validation')}
+      ${lead('Validation rules are declared in the spec, co-located with the state they guard. When an action sets <code>validate: true</code>, Pulse enforces every rule before the async work runs. Invalid data cannot reach <code>run()</code>.')}
+
+      ${section('declaring', 'Declaring validation rules')}
+      <p>The <code>validation</code> field maps dot-path state keys to rule objects:</p>
+      ${codeBlock(highlight(`export default {
+  route: '/signup',
+  state: {
+    fields: { name: '', email: '', age: '', website: '' },
+  },
+  validation: {
+    'fields.name':    { required: true, minLength: 2, maxLength: 100 },
+    'fields.email':   { required: true, format: 'email' },
+    'fields.age':     { required: true, min: 18, max: 120 },
+    'fields.website': { format: 'url' },   // optional field, but must be valid URL if provided
+  },
+  // ...
+}`, 'js'))}
+
+      ${section('rules', 'Available rules')}
+      ${table(
+        ['Rule', 'Type', 'Description'],
+        [
+          ['<code>required</code>', '<code>boolean</code>', 'Field must be present and non-empty.'],
+          ['<code>minLength</code>', '<code>number</code>', 'String must be at least N characters.'],
+          ['<code>maxLength</code>', '<code>number</code>', 'String must be at most N characters.'],
+          ['<code>min</code>', '<code>number</code>', 'Numeric value must be ≥ N.'],
+          ['<code>max</code>', '<code>number</code>', 'Numeric value must be ≤ N.'],
+          ['<code>pattern</code>', '<code>RegExp | string</code>', 'Value must match the regular expression.'],
+          ['<code>format</code>', '<code>string</code>', 'Named format: <code>email</code>, <code>url</code>, or <code>numeric</code>.'],
+        ]
+      )}
+
+      ${section('formats', 'Named formats')}
+      ${table(
+        ['Format', 'What it checks'],
+        [
+          ['<code>email</code>', 'Basic email structure — must contain <code>@</code> and a domain.'],
+          ['<code>url</code>', 'Must start with <code>http://</code> or <code>https://</code>.'],
+          ['<code>numeric</code>', 'Must consist entirely of digit characters.'],
+        ]
+      )}
+
+      ${section('dot-paths', 'Dot-path notation')}
+      <p>Validation keys are dot-paths into the current <code>state</code>, allowing nested fields to be validated without any special syntax:</p>
+      ${codeBlock(highlight(`state: {
+  billing: {
+    address: { street: '', city: '', postcode: '' },
+    card:    { number: '', expiry: '' },
+  },
+}
+
+validation: {
+  'billing.address.street':   { required: true },
+  'billing.address.city':     { required: true },
+  'billing.address.postcode': { required: true, pattern: /^[A-Z]{1,2}\\d[A-Z\\d]? \\d[A-Z]{2}$/i },
+  'billing.card.number':      { required: true, format: 'numeric', minLength: 16, maxLength: 16 },
+  'billing.card.expiry':      { required: true },
+}`, 'js'))}
+
+      ${section('when-runs', 'When validation runs')}
+      <p>Validation only runs when an action declares <code>validate: true</code>. The order is enforced by the framework:</p>
+      <ol>
+        <li><code>onStart</code> captures <code>FormData</code> values into state</li>
+        <li>Validation reads those values from state using dot-paths</li>
+        <li>If any rules fail, <code>onError</code> is called immediately — <code>run</code> is skipped</li>
+      </ol>
+      ${callout('note', 'Validation reads from <strong>state</strong>, not from raw <code>FormData</code>. <code>onStart</code> must copy form values into state first — this is what makes them available to dot-path rules.')}
+
+      ${section('error-structure', 'Error structure')}
+      <p>When validation fails, the runtime throws an error object with a <code>validation</code> array:</p>
+      ${codeBlock(highlight(`{
+  message: 'Validation failed',
+  validation: [
+    { field: 'fields.email',   rule: 'format',   message: 'Must be a valid email address' },
+    { field: 'fields.name',    rule: 'required',  message: 'Required' },
+    { field: 'fields.age',     rule: 'min',       message: 'Must be at least 18' },
+  ]
+}`, 'js'))}
+      <p>In your action's <code>onError</code>, check for <code>err?.validation</code> to distinguish validation errors from other failures:</p>
+      ${codeBlock(highlight(`onError: (state, err) => ({
+  status: 'error',
+  errors: err?.validation ?? [{ message: err.message }],
+})`, 'js'))}
+
+      ${section('rendering', 'Rendering errors')}
+      <p>The errors array maps to UI in the view — a global error list, or inline errors using the <code>field</code> property to place them next to each input:</p>
+      ${codeBlock(highlight(`view: (state) => {
+  const errFor = (field) => {
+    const e = state.errors.find(e => e.field === field)
+    return e ? \`<p class="field-error">\${e.message}</p>\` : ''
+  }
+
+  return \`
+    <form data-action="submit">
+      <label>
+        Email
+        <input name="email" type="email" value="\${state.fields.email}">
+        \${errFor('fields.email')}
+      </label>
+      <label>
+        Name
+        <input name="name" type="text" value="\${state.fields.name}">
+        \${errFor('fields.name')}
+      </label>
+      <button>Submit</button>
+    </form>
+  \`
+}`, 'js'))}
+
+      ${section('optional-fields', 'Optional fields')}
+      <p>Omit <code>required: true</code> for optional fields. Other rules (format, minLength, etc.) are only enforced when the field has a value — empty optional fields always pass:</p>
+      ${codeBlock(highlight(`validation: {
+  // website is optional, but must be a valid URL if provided
+  'fields.website': { format: 'url' },
+}`, 'js'))}
+    `,
+  }),
+}

package/examples/contact.js

@@ -0,0 +1,166 @@
+/**
+ * Pulse — Contact form example
+ *
+ * Demonstrates:
+ *   - Server data (fetched before render, passed to view)
+ *   - Validation (required, email format, length limits)
+ *   - Async action with full lifecycle: onStart → validate → run → onSuccess/onError
+ *   - Loading, success, and error states
+ *
+ * Run: node examples/dev.server.js  →  http://localhost:3001/contact
+ */
+
+import { button, alert, heading, input, textarea, card, container, section, stack, grid, iconMail, iconPhone, iconMapPin, iconClock, iconCheckCircle } from '../src/ui/index.js'
+import { examplesNav } from './shared.js'
+
+function infoDetail(icon, label, value, href) {
+  const valueHtml = href
+    ? `<a href="${href}" class="u-text-default">${value}</a>`
+    : `<span>${value}</span>`
+  return `<div class="u-flex u-items-start u-gap-3">
+    <span class="u-text-muted u-shrink-0" aria-hidden="true">${icon}</span>
+    <div>
+      <p class="u-text-xs u-text-muted u-font-semibold u-mb-1">${label}</p>
+      <p class="u-text-sm">${valueHtml}</p>
+    </div>
+  </div>`
+}
+
+export default {
+  route:   '/contact',
+  hydrate: '/examples/contact.js',
+
+  meta: {
+    title:       'Contact — Pulse',
+    description: 'A contact form built with Pulse. Demonstrates server data, validation, and async action lifecycle.',
+    styles:      ['/pulse-ui.css'],
+  },
+
+  server: {
+    info: async () => ({
+      email:   'hello@example.com',
+      phone:   '+44 20 7946 0958',
+      address: '123 Shoreditch High St, London E1 6JE',
+      hours:   'Monday – Friday, 9 am – 5 pm GMT',
+    }),
+  },
+
+  state: {
+    status: 'idle',   // idle | loading | success | error
+    errors: [],
+    fields: { name: '', email: '', subject: '', message: '' },
+  },
+
+  validation: {
+    'fields.name':    { required: true, minLength: 2, maxLength: 80 },
+    'fields.email':   { required: true, format: 'email' },
+    'fields.subject': { required: true, minLength: 2, maxLength: 120 },
+    'fields.message': { required: true, minLength: 10, maxLength: 2000 },
+  },
+
+  mutations: {
+    reset: () => ({ status: 'idle', errors: [], fields: { name: '', email: '', subject: '', message: '' } }),
+  },
+
+  actions: {
+    submit: {
+      onStart: (_state, formData) => ({
+        status: 'loading',
+        errors: [],
+        fields: {
+          name:    formData.get('name')    || '',
+          email:   formData.get('email')   || '',
+          subject: formData.get('subject') || '',
+          message: formData.get('message') || '',
+        },
+      }),
+
+      validate: true,
+
+      run: async (_state, _server, formData) => {
+        // Simulate sending — replace with a real fetch() to your API
+        await new Promise(resolve => setTimeout(resolve, 900))
+        // Demo: email addresses containing "fail" trigger the error path
+        if ((formData.get('email') || '').includes('fail')) {
+          throw new Error('Unable to deliver message. Please try another address.')
+        }
+      },
+
+      onSuccess: () => ({ status: 'success', errors: [] }),
+
+      onError: (_state, err) => ({
+        status: 'error',
+        errors: err?.validation
+          ? err.validation.map(e => {
+              const field = e.path?.split('.').pop() || ''
+              const label = { name: 'Name', email: 'Email', subject: 'Subject', message: 'Message' }[field] || field
+              const msg = e.rule === 'required'  ? `${label} is required`
+                        : e.rule === 'minLength' ? `${label} is too short`
+                        : e.rule === 'maxLength' ? `${label} is too long`
+                        : e.rule === 'format'    ? `${label} must be a valid email address`
+                        : e.message
+              return { field, message: msg }
+            })
+          : [{ message: err?.message || 'Something went wrong. Please try again.' }],
+      }),
+    },
+  },
+
+  view: (state, server) => {
+    const { info } = server
+    const loading   = state.status === 'loading'
+    const isSuccess = state.status === 'success'
+
+    const fieldError = (field) => state.errors.find(e => e.field === field)?.message || ''
+
+    const infoCol = stack({ gap: 'lg', content: `
+      ${heading({ level: 2, text: 'Get in touch', size: 'xl' })}
+      <p class="u-text-sm u-text-muted">Fill in the form and we&rsquo;ll get back to you within one business day.</p>
+      ${stack({ gap: 'md', content: `
+        ${infoDetail(iconMail({ size: 18 }),   'Email',   info.email,   'mailto:' + info.email)}
+        ${infoDetail(iconPhone({ size: 18 }),  'Phone',   info.phone,   'tel:' + info.phone.replace(/\s/g, ''))}
+        ${infoDetail(iconMapPin({ size: 18 }), 'Address', info.address, null)}
+        ${infoDetail(iconClock({ size: 18 }),  'Hours',   info.hours,   null)}
+      ` })}
+    ` })
+
+    const cardContent = isSuccess
+      ? stack({ gap: 'md', align: 'center', content:
+          iconCheckCircle({ size: 48, bg: 'circle', bgColor: 'success' }) +
+          heading({ level: 2, text: 'Message sent!', size: 'xl' }) +
+          `<p class="u-text-sm u-text-muted u-text-center">Thanks for reaching out. We&rsquo;ll be in touch within one business day.</p>` +
+          button({ label: 'Send another message', variant: 'secondary', attrs: { 'data-event': 'reset' } })
+        })
+      : `<form data-action="submit" novalidate>
+          <fieldset style="border:none;padding:0;margin:0" ${loading ? 'disabled' : ''}>
+            <legend class="u-text-lg u-font-semibold u-mb-5">Send a message</legend>
+            ${stack({ gap: 'md', content: `
+              ${state.status === 'error' && state.errors.length > 0
+                ? alert({ variant: 'error', content: state.errors[0]?.message || 'Please check the fields below.' })
+                : ''}
+              ${grid({ cols: 2, gap: 'sm', content:
+                input({ name: 'name',  label: 'Name',          type: 'text',  placeholder: 'Jane Smith',       value: state.fields.name,    required: true, error: fieldError('name')    }) +
+                input({ name: 'email', label: 'Email address',  type: 'email', placeholder: 'jane@example.com', value: state.fields.email,   required: true, error: fieldError('email')   })
+              })}
+              ${input({ name: 'subject', label: 'Subject', placeholder: 'How can we help?', value: state.fields.subject, required: true, error: fieldError('subject') })}
+              ${textarea({ name: 'message', label: 'Message', placeholder: "Tell us what's on your mind…", value: state.fields.message, rows: 5, required: true, error: fieldError('message') })}
+              ${button({ label: loading ? 'Sending…' : 'Send message', type: 'submit', fullWidth: true, disabled: loading })}
+            ` })}
+          </fieldset>
+        </form>`
+
+    return `
+  ${examplesNav('<span>✉ Contact</span>', '/contact')}
+
+  <main id="main-content">
+    ${section({ eyebrow: 'Contact', title: 'We\u2019d love to hear from you', level: 1, content:
+      container({ size: 'lg', content:
+        grid({ cols: 2, gap: 'lg', content: `
+          <div>${infoCol}</div>
+          <div>${card({ content: cardContent })}</div>
+        ` })
+      })
+    })}
+  </main>`
+  },
+}

package/examples/counter.js

@@ -0,0 +1,94 @@
+/**
+ * Pulse — Counter example
+ *
+ * Demonstrates:
+ *   - State and mutations
+ *   - Constraints (min/max enforced after every mutation)
+ *   - data-event binding
+ *   - Hydration for client interactivity
+ *
+ * Run: node examples/dev.server.js  →  http://localhost:3001/counter
+ */
+
+import { button, badge, card, container, section, stack, cluster, progress, segmented } from '../src/ui/index.js'
+import { examplesNav } from './shared.js'
+
+export default {
+  route:   '/counter',
+  hydrate: '/examples/counter.js',
+
+  meta: {
+    title:       'Counter — Pulse',
+    description: 'An interactive counter built with Pulse. Demonstrates mutations, constraints, and data-event binding.',
+    styles:      ['/pulse-ui.css'],
+  },
+
+  state: {
+    count: 0,
+    step:  1,
+  },
+
+  constraints: {
+    count: { min: 0, max: 20 },
+    step:  { min: 1, max: 5  },
+  },
+
+  mutations: {
+    increment: (state) => ({ count: state.count + state.step }),
+    decrement: (state) => ({ count: state.count - state.step }),
+    reset:     ()      => ({ count: 0 }),
+    setStep:   (_state, e) => ({ step: parseInt(e.target.value, 10) || 1 }),
+  },
+
+  view: (state) => {
+    const atMin = state.count <= 0
+    const atMax = state.count >= 20
+
+
+    return `
+  ${examplesNav('<span>⚡ Counter</span>', '/counter')}
+
+  <main id="main-content">
+    ${section({ eyebrow: 'Mutations & Constraints', title: 'Counter', level: 1, align: 'center',
+      subtitle: 'Constraints are enforced after every mutation — the count can never go below 0 or above 20.',
+      content:
+      container({ size: 'sm', content: `
+
+        ${card({ content: stack({ gap: 'lg', align: 'center', content: `
+
+          <div class="u-flex u-items-end u-justify-center u-gap-3" aria-live="polite" aria-atomic="true">
+            <span class="u-text-7xl u-font-bold u-text-accent">${state.count}</span>
+            <span class="u-text-3xl u-text-muted u-mb-2">/ 20</span>
+          </div>
+
+          ${progress({ value: state.count, max: 20, label: 'Counter progress' })}
+
+          ${cluster({ justify: 'center', gap: 'sm', content:
+            button({ label: '−', variant: 'secondary', disabled: atMin, attrs: { 'data-event': 'decrement', 'aria-label': 'Decrement' } }) +
+            button({ label: 'Reset', variant: 'ghost', attrs: { 'data-event': 'reset' } }) +
+            button({ label: '+', variant: 'primary', disabled: atMax, attrs: { 'data-event': 'increment', 'aria-label': 'Increment' } })
+          })}
+
+          ${stack({ gap: 'xs', align: 'center', content: `
+            <p class="u-text-xs u-text-muted" id="step-label">Step size</p>
+            ${segmented({
+              name:    'step',
+              value:   String(state.step),
+              event:   'change:setStep',
+              options: [1, 2, 5].map(n => ({ value: n, label: String(n) })),
+              size:    'md',
+            })}
+          ` })}
+
+          ${cluster({ justify: 'center', gap: 'xs', content:
+            badge({ label: atMin ? 'At minimum' : 'Min: 0', variant: atMin ? 'warning' : 'default' }) +
+            badge({ label: atMax ? 'At maximum' : 'Max: 20', variant: atMax ? 'warning' : 'default' })
+          })}
+
+        ` }) })}
+
+      `})
+    })}
+  </main>`
+  },
+}