@invisibleloop/pulse 0.20.10 → 0.20.19

package/docs/src/pages/components.js

@@ -1,200 +0,0 @@
-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('/components')
-
-export default {
-  route: '/components',
-  meta: {
-    theme:       'light',
-    title: 'Component Library — Pulse Docs',
-    description: 'Server-rendered UI components for Pulse — button, card, input, alert, stat, avatar, table and more. Fully accessible, mobile-ready, zero client JS.',
-    styles: ['/pulse-ui.css', '/theme.css', '/docs.css'],
-  },
-  view: () => renderLayout({
-    currentHref: '/components',
-    prev,
-    next,
-    content: `
-      ${h1('Component Library')}
-      ${lead('Server-rendered building blocks. Each component is a pure function that returns an HTML string — no client-side JS, no build step, accessible and mobile-ready by default. The output is the same every time the same props are passed.')}
-
-      ${section('setup', 'Setup')}
-      <p>Components are imported directly into the spec file alongside the stylesheet reference in <code>meta.styles</code>. No build step, no registration.</p>
-      ${codeBlock(highlight(`import { button, card, input } from '@invisibleloop/pulse/ui'
-import { escHtml }          from '@invisibleloop/pulse/html'
-
-export default {
-  route: '/example',
-  meta: {
-    title:  'Example',
-    styles: ['/pulse-ui.css', '/app.css'],
-  },
-  view: () => \`
-    <main id="main-content">
-      \${card({
-        title:   'Welcome',
-        content: button({ label: 'Get started', href: '/start' }),
-      })}
-    </main>
-  \`,
-}`, 'js'))}
-
-      ${section('theming', 'Theming')}
-      <p>All visual values flow through CSS custom properties. Override any <code>--ui-*</code> token in <code>:root</code> in your <code>app.css</code> to retheme the entire library at once.</p>
-      ${codeBlock(highlight(`/* app.css */
-:root {
-  --ui-accent:       #6366f1;
-  --ui-accent-hover: #818cf8;
-  --ui-accent-dim:   rgba(99, 102, 241, .12);
-  --ui-radius:       6px;
-  --ui-bg:           #ffffff;
-  --ui-surface:      #f9fafb;
-  --ui-text:         #111827;
-  --ui-muted:        #6b7280;
-  --ui-border:       #e5e7eb;
-}`, 'css'))}
-      <p>New variants follow the <code>ui-btn--{name}</code> CSS modifier pattern. A brand-coloured button, for example, is just a new class in <code>app.css</code> — the component itself stays untouched.</p>
-      ${codeBlock(highlight(`.ui-btn--brand {
-  background: var(--brand);
-  color:      #fff;
-  border:     none;
-}
-.ui-btn--brand:hover:not(.ui-btn--disabled) {
-  background: var(--brand-hover);
-}`, 'css'))}
-
-      ${section('components', 'Components')}
-      <p>Each component has its own page with full demos, code examples, and a props reference.</p>
-
-      <h3 class="doc-h3">UI</h3>
-      ${table(
-        ['Component', 'Description'],
-        [
-          ['<a href="/components/button">button</a>',   'Renders as <code>&lt;button&gt;</code> or <code>&lt;a&gt;</code>. Four variants, three sizes.'],
-          ['<a href="/components/badge">badge</a>',     'Inline status label. Five semantic colour variants.'],
-          ['<a href="/components/card">card</a>',       'Content surface with title, body, and optional footer.'],
-          ['<a href="/components/input">input</a>',       'Labelled text input with hint and error support.'],
-          ['<a href="/components/fieldset">fieldset</a>', 'Semantic grouping of related fields with an accessible legend.'],
-          ['<a href="/components/select">select</a>',     'Styled select with option groups and current-value support.'],
-          ['<a href="/components/textarea">textarea</a>', 'Multi-line input with label, hint, and error.'],
-          ['<a href="/components/alert">alert</a>',     'Inline feedback banner. ARIA roles wired by variant.'],
-          ['<a href="/components/stat">stat</a>',       'Numeric metric with optional trend arrow.'],
-          ['<a href="/components/avatar">avatar</a>',   'User avatar — image with fallback to initials.'],
-          ['<a href="/components/empty">empty</a>',     'Empty state with title, description, and optional CTA.'],
-          ['<a href="/components/table">table</a>',     'Accessible data table with scroll wrapper.'],
-        ]
-      )}
-
-      <h3 class="doc-h3">Landing page</h3>
-      ${table(
-        ['Component', 'Description'],
-        [
-          ['<a href="/components/nav">nav</a>',               'Site header with logo, links, and optional CTA.'],
-          ['<a href="/components/hero">hero</a>',             'Full-width hero section with eyebrow, title, and actions.'],
-          ['<a href="/components/app-badge">appBadge</a>',    'App Store / Google Play download badge.'],
-          ['<a href="/components/feature">feature</a>',       'Icon + title + description block for feature grids.'],
-          ['<a href="/components/accordion">accordion</a>',   'Collapsible FAQ items — no JS, native <code>&lt;details&gt;</code>.'],
-          ['<a href="/components/cta">cta</a>',               'Call-to-action block with eyebrow, heading, body, and actions slot.'],
-        ]
-      )}
-
-      <h3 class="doc-h3">Layout</h3>
-      ${table(
-        ['Component', 'Description'],
-        [
-          ['<a href="/components/container">container</a>', 'Max-width wrapper with horizontal padding.'],
-          ['<a href="/components/section">section</a>',     'Vertical padding block with background variant.'],
-          ['<a href="/components/grid">grid</a>',           'Responsive CSS grid. Collapses to one column on mobile.'],
-          ['<a href="/components/stack">stack</a>',         'Flex column with consistent vertical gap.'],
-          ['<a href="/components/cluster">cluster</a>',     'Flex row with wrapping — for badges, buttons, etc.'],
-          ['<a href="/components/divider">divider</a>',     'Horizontal rule, optionally with centred label.'],
-          ['<a href="/components/media">media</a>',             'Two-column image + text layout, stacks on mobile.'],
-          ['<a href="/components/footer">footer</a>',          'Site footer with logo, nav links, and legal text. Stacks on mobile.'],
-        ]
-      )}
-
-      ${section('utilities', 'Utility classes')}
-      <p><code>pulse-ui.css</code> ships a utility layer (prefix <code>u-</code>) for common spacing, typography, and layout needs. Reach for these before writing custom CSS — they use the same <code>--ui-*</code> tokens as components so theme overrides apply everywhere.</p>
-
-      <h3 class="doc-h3">Spacing</h3>
-      <p>Scale: 1=4px 2=8px 3=12px 4=16px 5=20px 6=24px 8=32px 10=40px 12=48px 16=64px</p>
-      ${table(
-        ['Class', 'Property'],
-        [
-          ['<code>u-mt-{0–16}</code>', 'margin-top'],
-          ['<code>u-mb-{0–16}</code>', 'margin-bottom'],
-          ['<code>u-mx-auto</code>', 'margin-left + right: auto'],
-          ['<code>u-p-{0–8}</code>', 'padding (all sides)'],
-          ['<code>u-px-{0–8}</code>', 'padding-left + right'],
-          ['<code>u-py-{0–8}</code>', 'padding-top + bottom'],
-        ]
-      )}
-
-      <h3 class="doc-h3">Typography</h3>
-      ${table(
-        ['Class', 'Effect'],
-        [
-          ['<code>u-text-{xs,sm,base,lg,xl,2xl,3xl,4xl}</code>', 'Font size + matching line-height'],
-          ['<code>u-font-{normal,medium,semibold,bold}</code>', 'Font weight'],
-          ['<code>u-text-{left,center,right}</code>', 'Text alignment'],
-          ['<code>u-text-{default,muted,accent,green,red,yellow,blue}</code>', 'Token colour'],
-          ['<code>u-leading-{tight,snug,normal,relaxed,loose}</code>', 'Line height'],
-        ]
-      )}
-
-      <h3 class="doc-h3">Layout</h3>
-      ${table(
-        ['Class', 'Effect'],
-        [
-          ['<code>u-flex</code> / <code>u-flex-col</code>', 'Flex row or column'],
-          ['<code>u-items-{start,center,end,stretch}</code>', 'align-items'],
-          ['<code>u-justify-{start,center,end,between}</code>', 'justify-content'],
-          ['<code>u-gap-{1–8}</code>', 'gap'],
-          ['<code>u-w-full</code>', 'width: 100%'],
-          ['<code>u-max-w-{xs,sm,md,lg,xl,prose}</code>', 'max-width (320px–1024px, 65ch)'],
-          ['<code>u-hidden</code> / <code>u-block</code> / <code>u-inline-block</code>', 'display'],
-        ]
-      )}
-
-      <h3 class="doc-h3">Visual</h3>
-      ${table(
-        ['Class', 'Effect'],
-        [
-          ['<code>u-rounded</code> / <code>u-rounded-md</code> / <code>u-rounded-lg</code> / <code>u-rounded-full</code>', 'border-radius'],
-          ['<code>u-border</code> / <code>u-border-t</code> / <code>u-border-b</code>', '1px solid --ui-border'],
-          ['<code>u-bg-surface</code> / <code>u-bg-surface2</code> / <code>u-bg-accent</code>', 'background token'],
-          ['<code>u-overflow-hidden</code> / <code>u-overflow-auto</code>', 'overflow'],
-          ['<code>u-opacity-50</code> / <code>u-opacity-75</code>', 'opacity'],
-        ]
-      )}
-
-      <p>Utilities compose naturally with components and with each other:</p>
-      ${codeBlock(highlight(`<!-- centred hero block — no custom CSS needed -->
-<div class="u-flex u-flex-col u-items-center u-text-center u-py-16 u-gap-4">
-  <h1 class="u-text-4xl u-font-bold">Hello</h1>
-  <p class="u-text-lg u-text-muted u-max-w-prose">Subtitle goes here.</p>
-  \${button({ label: 'Get started', href: '/start' })}
-</div>`, 'html'))}
-
-      ${callout('note', 'Never use inline <code>style=""</code> attributes. Reach for utility classes first, and only add to <code>app.css</code> when you need something utilities cannot provide — a unique animation, a custom grid, or a one-off component variant.')}
-
-      ${section('composing', 'Composing components')}
-      <p>Components compose naturally — pass the output of one as the <code>content</code> or <code>footer</code> of another. Here's a stat dashboard card:</p>
-      ${codeBlock(highlight(`import { card, stat, button } from '@invisibleloop/pulse/ui'
-
-card({
-  title:   'This week',
-  content: \`
-    \${stat({ label: 'Page views', value: '48,291', change: '+12%', trend: 'up' })}
-    \${stat({ label: 'New users',  value: '1,042',  change: '+4%',  trend: 'up' })}
-    \${stat({ label: 'Bounced',    value: '22%',    change: '+1%',  trend: 'down' })}
-  \`,
-  footer: button({ label: 'View full report', href: '/analytics', variant: 'ghost', size: 'sm' }),
-})`, 'js'))}
-
-      ${callout('note', 'Text props like <code>label</code>, <code>title</code>, <code>value</code>, and <code>error</code> are escaped automatically. <code>content</code>, <code>footer</code>, <code>rows</code>, <code>actions</code>, <code>icon</code>, <code>action</code>, and <code>logo</code> are raw HTML slots — they pass through as-is, so any user-supplied data going into those slots should go through <code>escHtml()</code> first.')}
-    `,
-  }),
-}

package/docs/src/pages/config.js

@@ -1,193 +0,0 @@
-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('/config')
-
-export default {
-  route: '/config',
-  meta: {
-    theme:       'light',
-    title: 'Configuration — Pulse Docs',
-    description: 'Full reference for pulse.config.js — port, Lighthouse thresholds, load test config, environments, and per-route overrides.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  view: () => renderLayout({
-    currentHref: '/config',
-    prev,
-    next,
-    content: `
-      ${h1('Configuration')}
-      ${lead('<code>pulse.config.js</code> sets the performance and load thresholds that Pulse enforces across your application. All fields are optional — the defaults match Google\'s Core Web Vitals "good" band. Configuration here is not about enabling features; it is about deciding where, if anywhere, you need to lower a guaranteed baseline.')}
-
-      ${section('schema', 'Full schema')}
-      ${codeBlock(highlight(`// pulse.config.js
-export default {
-  port: 3000,
-
-  lighthouse: {
-    // Category scores — 0 to 100. Default: 100 for all four.
-    performance:   100,
-    accessibility: 100,
-    bestPractices: 100,
-    seo:           100,
-
-    // Core Web Vitals and timing metrics.
-    // Defaults are the Google "good" thresholds.
-    lcp: 2500,   // Largest Contentful Paint (ms)
-    cls: 0.1,    // Cumulative Layout Shift
-    tbt: 200,    // Total Blocking Time (ms)
-    fcp: 1800,   // First Contentful Paint (ms)
-    si:  3400,   // Speed Index (ms)
-    inp: 200,    // Interaction to Next Paint (ms)
-  },
-
-  load: {
-    duration:    10,
-    connections: 10,
-    thresholds: {
-      rps:    undefined,  // minimum req/s (optional)
-      p99:    undefined,  // maximum p99 latency ms (optional)
-      errors: 0,
-    },
-  },
-
-  environments: {
-    // Environment names are bespoke — choose whatever suits your project.
-    local:   { url: 'http://localhost:3000', default: true },
-    staging: {
-      url:     'https://staging.myapp.com',
-      headers: { Authorization: \`Bearer \${process.env.STAGING_TOKEN}\` },
-      load:       { duration: 30, connections: 50 },
-      lighthouse: { performance: 90 },
-    },
-    production: { url: 'https://myapp.com' },
-  },
-
-  routes: {
-    // Per-route overrides — merged on top of global lighthouse/load config.
-    // Only specify what differs from the global defaults.
-    '/dashboard': {
-      lighthouse: {
-        performance: 85,
-        lcp:         4000,
-      },
-    },
-    '/embed': {
-      lighthouse: {
-        bestPractices: 85,
-      },
-    },
-  },
-}`, 'js'))}
-
-      ${section('port', 'port')}
-      ${table(
-        ['Field', 'Type', 'Default', 'Description'],
-        [
-          ['<code>port</code>', '<code>number</code>', '<code>3000</code>', 'Port the dev and production servers listen on.'],
-        ]
-      )}
-
-      ${section('lighthouse', 'lighthouse')}
-      <p>Global Lighthouse thresholds that every page must meet. <code>/pulse-report</code> enforces these after every audit — any page that falls below a threshold is reported as a failure, not a warning.</p>
-      ${table(
-        ['Field', 'Type', 'Default', 'Description'],
-        [
-          ['<code>performance</code>',   '<code>number</code>', '<code>100</code>',  'Lighthouse Performance category score (0–100).'],
-          ['<code>accessibility</code>', '<code>number</code>', '<code>100</code>',  'Lighthouse Accessibility category score (0–100).'],
-          ['<code>bestPractices</code>', '<code>number</code>', '<code>100</code>',  'Lighthouse Best Practices category score (0–100).'],
-          ['<code>seo</code>',           '<code>number</code>', '<code>100</code>',  'Lighthouse SEO category score (0–100).'],
-          ['<code>lcp</code>',           '<code>number</code>', '<code>2500</code>', 'Largest Contentful Paint budget (ms).'],
-          ['<code>cls</code>',           '<code>number</code>', '<code>0.1</code>',  'Cumulative Layout Shift budget.'],
-          ['<code>tbt</code>',           '<code>number</code>', '<code>200</code>',  'Total Blocking Time budget (ms).'],
-          ['<code>fcp</code>',           '<code>number</code>', '<code>1800</code>', 'First Contentful Paint budget (ms).'],
-          ['<code>si</code>',            '<code>number</code>', '<code>3400</code>', 'Speed Index budget (ms).'],
-          ['<code>inp</code>',           '<code>number</code>', '<code>200</code>',  'Interaction to Next Paint budget (ms).'],
-        ]
-      )}
-      ${callout('note', 'Unset fields default to the values above. Setting a field to <code>null</code> removes that check for the project — use sparingly. Raising a threshold is always preferable to disabling it.')}
-
-      ${section('routes', 'routes')}
-      <p>Route-specific overrides let you lower a threshold for a specific page without relaxing the global guarantee. Only specify the fields that differ — everything else inherits from the global config.</p>
-      ${codeBlock(highlight(`routes: {
-  // This route uses a third-party chart library — relax performance only.
-  '/dashboard': {
-    lighthouse: {
-      performance: 85,
-      lcp:         4000,
-    },
-  },
-}`, 'js'))}
-      ${callout('note', 'Route keys must exactly match the spec <code>route</code> field, including any leading slash. Dynamic segments are not supported — create a specific override for each route pattern.')}
-
-      ${section('load', 'load')}
-      <p>Load test thresholds enforced by <code>/pulse-load</code>. All fields are optional — omitting a threshold means that check is not enforced.</p>
-      ${table(
-        ['Field', 'Type', 'Default', 'Description'],
-        [
-          ['<code>duration</code>',            '<code>number</code>',    '<code>10</code>',         'Test duration in seconds.'],
-          ['<code>connections</code>',          '<code>number</code>',    '<code>10</code>',         'Number of concurrent request chains.'],
-          ['<code>thresholds.rps</code>',       '<code>number</code>',    '<code>undefined</code>',  'Minimum acceptable requests per second. Unset = no check.'],
-          ['<code>thresholds.p99</code>',       '<code>number</code>',    '<code>undefined</code>',  'Maximum acceptable p99 latency (ms). Unset = no check.'],
-          ['<code>thresholds.errors</code>',    '<code>number</code>',    '<code>0</code>',          'Maximum acceptable error count.'],
-        ]
-      )}
-      ${codeBlock(highlight(`load: {
-  duration:    30,
-  connections: 20,
-  thresholds: {
-    rps:    100,   // fail if below 100 req/s
-    p99:    500,   // fail if p99 exceeds 500ms
-    errors: 0,
-  },
-},`, 'js'))}
-      <p>Per-route overrides follow the same pattern as <code>lighthouse</code>:</p>
-      ${codeBlock(highlight(`routes: {
-  '/feed': {
-    load: { connections: 5, thresholds: { rps: 20 } },
-  },
-}`, 'js'))}
-      <p>Results are saved to <code>.pulse/load-reports/</code> and displayed in the Load Tests tab of the report dashboard, alongside the Lighthouse Performance tab for the same route.</p>
-
-      ${section('environments', 'environments')}
-      <p>Named environments let you enforce thresholds against different targets — local, staging, production — from the same config. Thresholds are applied per-environment, so staging and production can have different performance floors.</p>
-      ${table(
-        ['Field', 'Type', 'Description'],
-        [
-          ['<code>url</code>',        '<code>string</code>',  'Base URL to test against. If it contains <code>localhost</code> or <code>127.0.0.1</code>, a local production build is spun up automatically. Remote URLs are tested directly.'],
-          ['<code>default</code>',    '<code>boolean</code>', 'The environment used when none is explicitly specified by <code>pulse report</code> and <code>pulse load-test</code>.'],
-          ['<code>headers</code>',    '<code>object</code>',  'HTTP headers sent with every request to this environment. Useful for authorization tokens on protected staging deployments — read values from <code>process.env</code> rather than hardcoding them.'],
-          ['<code>load</code>',       '<code>object</code>',  'Load test config overrides for this environment. Same fields as the global <code>load</code> block. Merged on top of global config.'],
-          ['<code>lighthouse</code>', '<code>object</code>',  'Lighthouse threshold overrides for this environment. Same fields as the global <code>lighthouse</code> block. Merged on top of global config.'],
-        ]
-      )}
-      ${callout('note', 'Environment names are fully bespoke — <code>local</code>, <code>staging</code>, <code>production</code>, <code>preview</code>, <code>eu</code> — whatever maps to your project\'s infrastructure. There are no reserved names.')}
-      <p>Threshold merge order: <strong>global config → environment override → per-route override</strong>.</p>
-      ${codeBlock(highlight(`environments: {
-  local:   { url: 'http://localhost:3000', default: true },
-  staging: {
-    url:     'https://staging.myapp.com',
-    headers: { Authorization: \`Bearer \${process.env.STAGING_TOKEN}\` },
-    load:       { duration: 30, connections: 50, thresholds: { rps: 500 } },
-    lighthouse: { performance: 90 },
-  },
-  production: { url: 'https://myapp.com' },
-}`, 'js'))}
-
-      ${section('defaults', 'CWV default thresholds')}
-      <p>The default metric thresholds match the Google "good" band from the Core Web Vitals specification:</p>
-      ${table(
-        ['Metric', 'Default', 'Google "good" threshold'],
-        [
-          ['LCP', '<code>2500 ms</code>',  '≤ 2500 ms'],
-          ['CLS', '<code>0.1</code>',      '≤ 0.1'],
-          ['TBT', '<code>200 ms</code>',   '≤ 200 ms'],
-          ['FCP', '<code>1800 ms</code>',  '≤ 1800 ms'],
-          ['SI',  '<code>3400 ms</code>',  '≤ 3400 ms'],
-          ['INP', '<code>200 ms</code>',   '≤ 200 ms'],
-        ]
-      )}
-    `,
-  }),
-}

package/docs/src/pages/constraints.js

@@ -1,100 +0,0 @@
-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('/constraints')
-
-export default {
-  route: '/constraints',
-  meta: {
-    theme:       'light',
-    title: 'Constraints — Pulse Docs',
-    description: 'Automatic min/max bounds on state values, enforced after every mutation.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  state: {},
-  view: () => renderLayout({
-    currentHref: '/constraints',
-    prev,
-    next,
-    content: `
-      ${h1('Constraints')}
-      ${lead('Constraints are always-on bounds for numeric state values. After every mutation, Pulse clamps constrained values to their declared range before the view re-renders. The value can never go out of range — there is no code path where it can.')}
-
-      ${section('declaring', 'Declaring constraints')}
-      <p>The <code>constraints</code> field maps top-level state keys to bounds objects with optional <code>min</code> and <code>max</code> properties:</p>
-      ${codeBlock(highlight(`export default {
-  route: '/cart',
-  state: {
-    quantity: 1,
-    zoom:     1.0,
-    rating:   0,
-  },
-  constraints: {
-    quantity: { min: 1,   max: 99  },
-    zoom:     { min: 0.5, max: 3.0 },
-    rating:   { min: 0,   max: 5   },
-  },
-  mutations: {
-    increaseQty: (state) => ({ quantity: state.quantity + 1 }),
-    decreaseQty: (state) => ({ quantity: state.quantity - 1 }),
-    zoomIn:      (state) => ({ zoom: state.zoom + 0.1 }),
-    zoomOut:     (state) => ({ zoom: state.zoom - 0.1 }),
-  },
-}`, 'js'))}
-      <p>When <code>decreaseQty</code> runs and <code>quantity</code> is already 1, the constraint clamps it back to 1 before the view renders. The mutation does not need to check bounds — the spec declares them once and Pulse enforces them everywhere.</p>
-
-      ${section('vs-validation', 'Constraints vs Validation')}
-      ${table(
-        ['Aspect', 'Constraints', 'Validation'],
-        [
-          ['When it runs', 'After <strong>every</strong> mutation, automatically', 'Only when an action has <code>validate: true</code>'],
-          ['What it does', 'Clamps numeric values silently', 'Rejects the action and surfaces errors'],
-          ['User feedback', 'None — state is silently corrected', 'Explicit error messages shown in the view'],
-          ['Best for', 'Numeric ranges that must never be exceeded', 'Form field correctness before submission'],
-        ]
-      )}
-
-      ${callout('note', 'Constraints and validation serve different purposes. Constraints silently enforce numeric bounds at every mutation — they cannot be bypassed. Validation rejects invalid form data before an action\'s async work begins — it only runs when explicitly declared.')}
-
-      ${section('one-sided', 'One-sided bounds')}
-      <p>Either <code>min</code> or <code>max</code> can be declared alone — both are optional:</p>
-      ${codeBlock(highlight(`constraints: {
-  count:    { min: 0 },          // no upper limit
-  discount: { max: 100 },        // no lower limit
-  offset:   { min: 0, max: 999 } // both bounds
-}`, 'js'))}
-
-      ${section('how-it-works', 'How clamping works')}
-      <p>After Pulse applies a mutation's partial state update, it iterates over all declared constraints and applies <code>Math.max(min, Math.min(max, value))</code> to each constrained key. The view is then called with the clamped state.</p>
-      ${codeBlock(highlight(`// state.count = 10, constraints.count = { min: 0, max: 10 }
-mutations: {
-  increment: (state) => ({ count: state.count + 1 }),
-  // mutation returns { count: 11 }
-  // constraint clamps to 10
-  // view receives { count: 10 }
-}`, 'js'))}
-
-      ${section('top-level', 'Top-level keys only')}
-      <p>Constraints apply to top-level state keys. To constrain nested values, consider flattening your state structure or applying bounds logic in the mutation itself:</p>
-      ${codeBlock(highlight(`// Cannot do:
-constraints: {
-  'player.health': { min: 0, max: 100 }   // ✗ nested paths not supported
-}
-
-// Do instead:
-state: { playerHealth: 100 },
-constraints: { playerHealth: { min: 0, max: 100 } },
-
-// Or handle in the mutation:
-mutations: {
-  takeDamage: (state, _, amount) => ({
-    player: {
-      ...state.player,
-      health: Math.max(0, state.player.health - amount),
-    }
-  })
-}`, 'js'))}
-    `,
-  }),
-}