@invisibleloop/pulse 0.8.1 → 0.9.0

package/docs/.claude/commands/verify.md

@@ -24,13 +24,13 @@ Use `mcp__chrome-devtools__navigate_page` to load the page route, then `mcp__chr
 
 Run `mcp__chrome-devtools__lighthouse_audit` on the route with `{ "strategy": "desktop" }`.
 
-**Pass bar: Performance, Accessibility, Best Practices, and SEO must all be 100.** Report the actual scores. If any score is below 100, identify the failing audit(s), fix the issue, and restart from step 2.
+**Pass bar: Accessibility, Best Practices, and SEO must all be 100.** Performance is measured and reported but is not a hard requirement (it varies with machine load). Report the actual scores. If Accessibility, Best Practices, or SEO is below 100, identify the failing audit(s), fix the issue, and restart from step 2.
 
 ### 6. Lighthouse — mobile
 
 Run `mcp__chrome-devtools__lighthouse_audit` on the same route with `{ "strategy": "mobile" }`.
 
-**Same pass bar: all four categories must be 100.** Report the actual scores. If any score is below 100, fix and restart from step 2.
+**Same pass bar: Accessibility, Best Practices, and SEO must all be 100.** Fix any failures and restart from step 2.
 
 ### 7. Performance
 
@@ -42,7 +42,7 @@ Use `mcp__chrome-devtools__list_console_messages` — report any errors or unexp
 
 ### 9. Code review
 
-Check the spec against the checklist in `.claude/pulse-checklist.md`. Work through every item. Fix anything that fails before proceeding to the next step.
+Call `pulse_review` with the absolute path to the spec file. Read the source, rendered HTML, validator output, and checklist it returns. Fix every issue before proceeding. This is the structured review — do not skip it or replace it with a manual checklist read.
 
 ### 10. Close the browser
 
@@ -56,7 +56,7 @@ Run:
 date +%s > .pulse-verified
 ```
 
-This records that verify completed successfully. The stop hook checks this stamp — do not skip this step.
+**This must be the last write operation before stopping.** The stop hook compares each edited spec's modification time against this stamp — if any spec is newer than the stamp, the hook blocks. Do not edit any spec file after writing the stamp.
 
 ### 12. Report
 
@@ -69,4 +69,12 @@ Summarise:
 - Console: any errors
 - Review: pass or issues found and fixed
 
-Only confirm the page is good when validation passes, both Lighthouse runs are 100/100/100/100, CLS is 0.00, and there are no console errors. Otherwise, fix and run `/verify` again.
+**Pass bar — all of these must be met before the page is confirmed good:**
+- Validation: clean (no errors, no warnings)
+- Lighthouse desktop: Accessibility, Best Practices, SEO all 100
+- Lighthouse mobile: same
+- CLS: 0.00 — any layout shift is a blocker
+- LCP: report the value; flag and fix any insight that identifies a fixable cause
+- Console: no errors
+
+If any gate fails, fix the issue and run `/verify` again.

package/docs/.claude/pulse-checklist.md

@@ -66,6 +66,11 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 - **Validate FormData fields before use.** `formData.get('email')` returns `null` if the field is missing. Check for null/empty before passing to an API or database.
 - **Do not trust URL params.** `ctx.params.id` is a raw string from the URL. Validate it before use — check it exists, is the right type, and refers to a real resource. Return a 404 or redirect if it doesn't.
 
+### CSS
+
+- **`app.css` must contain no hex values or raw colour values.** A lint hook enforces this and will block the build. Hex values belong in `public/theme.css` as token definitions; `app.css` references them via `var()` only.
+- **Load order in `meta.styles`:** `pulse-ui.css` → `theme.css` → `app.css`. Theme tokens must be defined before `app.css` references them.
+
 ### Security
 
 - Any value from user input (URL params, form fields, external APIs) interpolated into view HTML must be escaped.

package/docs/public/.pulse-ui-version

@@ -1 +1 @@
-0.7.2
+0.8.1

package/docs/public/pulse-ui.css

@@ -40,6 +40,30 @@
 
   /* Touch target minimum per WCAG 2.5.5 */
   --ui-touch-min: 44px;
+
+  /* ── Spacing scale ── */
+  --ui-space-1:  0.25rem;   /*  4px */
+  --ui-space-2:  0.5rem;    /*  8px */
+  --ui-space-3:  0.75rem;   /* 12px */
+  --ui-space-4:  1rem;      /* 16px */
+  --ui-space-5:  1.25rem;   /* 20px */
+  --ui-space-6:  1.5rem;    /* 24px */
+  --ui-space-8:  2rem;      /* 32px */
+  --ui-space-10: 2.5rem;    /* 40px */
+  --ui-space-12: 3rem;      /* 48px */
+  --ui-space-16: 4rem;      /* 64px */
+  --ui-space-20: 5rem;      /* 80px */
+  --ui-space-24: 6rem;      /* 96px */
+
+  /* ── Type scale ── */
+  --ui-text-xs:   0.75rem;    /* 12px */
+  --ui-text-sm:   0.875rem;   /* 14px */
+  --ui-text-base: 1rem;       /* 16px */
+  --ui-text-lg:   1.125rem;   /* 18px */
+  --ui-text-xl:   1.25rem;    /* 20px */
+  --ui-text-2xl:  1.5rem;     /* 24px */
+  --ui-text-3xl:  1.875rem;   /* 30px */
+  --ui-text-4xl:  2.25rem;    /* 36px */
 }
 
 /* ─── Base reset ─────────────────────────────────────────────────────────────

package/docs/src/pages/home.js

@@ -39,6 +39,18 @@ export default {
     title: 'Pulse — The spec-first web framework',
     description: 'Pulse is a server-first Node.js framework with zero runtime dependencies. One spec object per page — server data, state, mutations, and view in plain JS. Streaming SSR, security headers, and production caching are enforced by the architecture.',
     styles: ['/pulse-ui.css', '/docs.css'],
+    schema: {
+      '@context': 'https://schema.org',
+      '@type': 'SoftwareApplication',
+      name: 'Pulse',
+      applicationCategory: 'DeveloperApplication',
+      operatingSystem: 'Node.js ≥ 22',
+      offers: { '@type': 'Offer', price: '0', priceCurrency: 'USD' },
+      license: 'https://opensource.org/licenses/MIT',
+      description: 'Spec-first Node.js web framework. Zero runtime dependencies. Streaming SSR, built-in security headers, and production caching enforced by the architecture.',
+      url: 'https://pulse.invisibleloop.com',
+      codeRepository: 'https://github.com/invisibleloop/pulse-framework',
+    },
   },
   state: {},
   server: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.8.1",
+  "version": "0.9.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.8.1
+0.9.0

package/src/agent/checklist.md

@@ -130,3 +130,14 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 - Interactive elements without visible text have an `aria-label`.
 - Disabled state is reflected with the `disabled` attribute, not just CSS.
 - The page has a `<main id="main-content">` landmark.
+- **Every element with `data-event`, `data-store-event`, `data-dialog-open`, or `data-dialog-close` is natively interactive (`button`, `a`, `input`, `select`, `textarea`, `summary`) or has `tabindex="0"`.** Non-interactive tags (`div`, `span`, `li`, `td`, etc.) with these attributes are not keyboard reachable. Prefer `<button>` — it is focusable, fires on Enter/Space, and carries the correct ARIA role for free. Only use `tabindex="0"` on a non-interactive element when a `<button>` genuinely cannot be used.
+- **Every interactive element communicates its purpose and state:**
+  - Buttons have visible text or `aria-label`. Links use descriptive text — "click here", "here", "read more" are failures.
+  - Form inputs have an associated `<label for="id">` or `aria-label`. `placeholder` alone is not a label.
+  - Toggle controls (open/close, show/hide, expand/collapse) carry `aria-expanded="true|false"` or `aria-pressed="true|false"`.
+  - While an action is in flight, the trigger button has `aria-busy="true"` or its label changes (e.g. "Saving…"). A spinner alone is not enough.
+  - Active nav items have `aria-current="page"`. Selected items in a list, tab set, or option group have `aria-selected="true"`.
+- **The page has a logical tab order:**
+  - No `tabindex` value greater than 0. Positive tabindex values override the natural DOM order and create a broken tab sequence. Remove them and reorder the DOM instead.
+  - Visually hidden interactive content (off-canvas menus, collapsed panels, `opacity:0` elements) is removed from the tab order with `tabindex="-1"` or the `inert` attribute — CSS alone does not remove an element from tab order.
+  - DOM order matches the visual reading order. When flexbox `order` or CSS grid placement visually reposition elements, the tab sequence still follows the DOM — author the DOM in the order a user would read and interact with the page.

package/src/mcp/server.js

@@ -644,6 +644,17 @@ Work through every item. Fix anything that fails.
 - [ ] \`aria-live\` and \`aria-label\` are NOT on the same element
 - [ ] Heading hierarchy is correct — no skipped levels, starts at h1
 - [ ] Disabled state uses the \`disabled\` attribute, not just CSS or opacity
+- [ ] **Keyboard focusability** — every element carrying \`data-event\`, \`data-store-event\`, \`data-dialog-open\`, or \`data-dialog-close\` is either a natively interactive element (\`button\`, \`a\`, \`input\`, \`select\`, \`textarea\`, \`summary\`) or has \`tabindex="0"\`. Scan the rendered HTML above — a \`<div>\`, \`<span>\`, \`<li>\`, or any other non-interactive tag with one of these attributes is a keyboard accessibility failure. Prefer \`<button>\` over a div + tabindex.
+- [ ] **Purpose** — every interactive element has a clear accessible name. Buttons have visible text or \`aria-label\`. Links use descriptive text — flag generic labels ("click here", "here", "read more", "more"). Form inputs have an associated \`<label for="id">\` or \`aria-label\` — \`placeholder\` alone is not a label (it disappears on focus and is not read by all screen readers).
+- [ ] **State** — interactive elements communicate their current state via ARIA:
+  - Toggle controls (open/close, show/hide, expand/collapse) have \`aria-expanded="true|false"\` or \`aria-pressed="true|false"\`
+  - While an action is running, the trigger button has \`aria-busy="true"\` or its visible label changes (e.g. "Saving…") — a spinner alone is not sufficient
+  - Active navigation items have \`aria-current="page"\`
+  - Selected items in a list, tab set, or option group have \`aria-selected="true"\`
+- [ ] **Tab order** — scan the rendered HTML for these failures:
+  - No \`tabindex\` value greater than 0. \`tabindex="1"\` and above override the natural DOM order and almost always create a broken, unpredictable tab sequence. The only valid values are \`0\` (add to natural order) and \`-1\` (remove from order). If you find a positive tabindex, remove it and reorder the DOM instead.
+  - Off-screen or visually hidden interactive content is removed from the tab order. Elements that are hidden via CSS alone (e.g. \`opacity:0\`, \`visibility:hidden\` without \`display:none\`, off-canvas menus, collapsed panels) but remain in the DOM must have \`tabindex="-1"\` or \`inert\` so keyboard users cannot tab into invisible controls.
+  - DOM order matches the visual reading order. When CSS flexbox \`order\` or grid placement is used to visually reposition elements, the tab sequence follows the DOM — not the visual layout. Ensure the DOM is authored in the order a sighted user would read and interact with the page.
 
 ### Defensive coding
 - [ ] Any \`fetch\` in actions or server fetchers checks \`res.ok\` before calling \`.json()\`

package/src/runtime/index.js

@@ -8,6 +8,7 @@
  */
 
 import { initClientStore, getStoreState, subscribe, updateStore, registerStoreMutations, dispatchStoreMutation } from './store.js'
+import { trustedHTML } from './tt.js'
 
 // Toast is lazy-loaded on first use — pages that never use _toast pay zero bytes
 const showToast = (opts) => import('./toast.js').then(m => m.showToast(opts))
@@ -227,7 +228,7 @@ export function mount(spec, el, serverState = {}, options = {}) {
     refresh: render,
 
     /** Tear down — remove event listeners, unsubscribe from store, clear element */
-    destroy: () => { _unsubStore?.(); _eventAbort.abort(); el.innerHTML = '' }
+    destroy: () => { _unsubStore?.(); _eventAbort.abort(); el.innerHTML = trustedHTML('') }
   }
 }
 
@@ -363,7 +364,7 @@ function morph(el, newHtml) {
     return
   }
   const temp = document.createElement('div')
-  temp.innerHTML = newHtml
+  temp.innerHTML = trustedHTML(newHtml)
   morphNodes(el, temp)
 }
 

package/src/runtime/navigate.js

@@ -8,6 +8,8 @@
  * Falls back to full page load on any error.
  */
 
+import { trustedHTML } from './tt.js'
+
 /**
  * Initialise navigation for a Pulse app.
  * Call once after the initial mount().
@@ -61,7 +63,7 @@ export function initNavigation(root, mountFn) {
             await applyScripts(msg.scripts)
 
           } else if (msg.type === 'html') {
-            root.innerHTML = msg.html
+            root.innerHTML = trustedHTML(msg.html)
             // Index <pulse-deferred> placeholders so deferred chunks land in the right spot
             for (const id of (msg.deferred || [])) {
               const el = root.querySelector(`[id="pd-${id}"]`)
@@ -74,7 +76,7 @@ export function initNavigation(root, mountFn) {
             const slot = deferredSlots.get(msg.id)
             if (slot) {
               const tmp = document.createElement('div')
-              tmp.innerHTML = msg.html
+              tmp.innerHTML = trustedHTML(msg.html)
               slot.replaceWith(...tmp.childNodes)
               deferredSlots.delete(msg.id)
             }
@@ -124,7 +126,7 @@ export function initNavigation(root, mountFn) {
           window.__updatePulseStore__(storeState)
         }
 
-        root.innerHTML = html
+        root.innerHTML = trustedHTML(html)
         document.title = title || document.title
         applyStyles(styles)
         await applyScripts(scripts)

package/src/runtime/tt.js

@@ -0,0 +1,20 @@
+/**
+ * Trusted Types helper — routes innerHTML assignments through a declared policy
+ * in browsers that support the API (Chromium). Falls back to a plain string
+ * everywhere else — behaviour is identical, the protection is simply absent.
+ *
+ * Policy name 'pulse' must match the trusted-types CSP directive on the server.
+ */
+
+let _policy = null
+
+/**
+ * Return a TrustedHTML object (Chromium) or the raw string (all other browsers).
+ * @param {string} html
+ * @returns {TrustedHTML|string}
+ */
+export function trustedHTML(html) {
+  if (typeof window === 'undefined' || !window.trustedTypes) return html
+  if (!_policy) _policy = window.trustedTypes.createPolicy('pulse', { createHTML: s => s })
+  return _policy.createHTML(html)
+}

package/src/server/index.js

@@ -63,10 +63,12 @@ const BASE_CSP = {
   'img-src':        ["'self'", 'data:'],
   'font-src':       ["'self'"],
   'connect-src':    ["'self'"],
-  'object-src':     ["'none'"],
-  'frame-ancestors':["'none'"],
-  'base-uri':       ["'self'"],
-  'form-action':    ["'self'"],
+  'object-src':                  ["'none'"],
+  'frame-ancestors':             ["'none'"],
+  'base-uri':                    ["'self'"],
+  'form-action':                 ["'self'"],
+  'require-trusted-types-for':   ["'script'"],
+  'trusted-types':               ['pulse'],
 }
 
 function serializeCsp(directives) {
@@ -81,8 +83,8 @@ function serializeCsp(directives) {
 function buildCsp(nonce, ext = {}) {
   const d = {
     ...BASE_CSP,
-    'script-src': ["'self'", `'nonce-${nonce}'`],
-    'style-src':  ["'self'", `'nonce-${nonce}'`],  // allows toast's runtime-injected <style nonce>
+    'script-src': ["'self'", `'nonce-${nonce}'`, "'unsafe-inline'"],  // 'unsafe-inline' ignored by nonce-aware browsers; fallback for CSP1-only browsers
+    'style-src':  ["'self'", `'nonce-${nonce}'`, "'unsafe-inline'"],  // same — nonce takes precedence; allows toast's runtime-injected <style> in older browsers
   }
   for (const [k, sources] of Object.entries(ext)) {
     d[k] = [...(d[k] || []), ...sources]