@invisibleloop/pulse 0.8.2 → 0.9.1

package/docs/.claude/pulse-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/docs/public/.pulse-ui-version

@@ -1 +1 @@
-0.8.1
+0.9.0

package/docs/public/menu.js

@@ -67,20 +67,30 @@
     input.style.setProperty('--slider-fill', pct)
   }
 
-  document.querySelectorAll('.ui-slider').forEach(function (input) {
-    input.addEventListener('input', function () { updateSliderFill(this) })
-  })
-
-  // ── Demo theme toggles ────────────────────────────────────────────────────
-  document.querySelectorAll('.demo-theme-toggle').forEach(function (toggle) {
-    var preview = toggle.closest('.demo-preview')
-    if (!preview) return
-    toggle.addEventListener('click', function () {
-      var isLight = preview.classList.toggle('is-light')
-      var inner   = preview.querySelector('.demo-preview-inner')
-      if (inner) {
-        inner.classList.toggle('ui-theme-light', isLight)
-      }
+  function bindDemoControls() {
+    document.querySelectorAll('.ui-slider').forEach(function (input) {
+      input.addEventListener('input', function () { updateSliderFill(this) })
     })
-  })
+
+    // ── Demo theme toggles ──────────────────────────────────────────────────
+    document.querySelectorAll('.demo-theme-toggle').forEach(function (toggle) {
+      var preview = toggle.closest('.demo-preview')
+      if (!preview) return
+      toggle.addEventListener('click', function () {
+        var isLight = preview.classList.toggle('is-light')
+        var inner   = preview.querySelector('.demo-preview-inner')
+        if (inner) {
+          inner.classList.toggle('ui-theme-light', isLight)
+        }
+      })
+    })
+  }
+
+  document.addEventListener('pulse:navigate', bindDemoControls)
+
+  if (document.readyState === 'complete') {
+    setTimeout(bindDemoControls, 50)
+  } else {
+    window.addEventListener('load', bindDemoControls)
+  }
 })()

package/docs/src/pages/components/icons.js

@@ -238,21 +238,7 @@ function iconModals_() {
   return ICONS.flatMap(({ icons }) => icons).map(iconPreviewModal).join('')
 }
 
-export default {
-  route: '/components/icons',
-  meta: {
-    title: 'Icons — Pulse Docs',
-    description: 'Built-in icon set for Pulse UI.',
-    styles: ['/pulse-ui.css', '/docs.css'],
-  },
-  view: () => renderComponentPage({
-    currentHref: '/components/icons',
-    prev,
-    next,
-    name: 'icons',
-    description: '100 curated icons. All are pure functions returning an SVG string — no external library, no DOM dependency, tree-shakeable. Style: 24×24 viewBox, <code>stroke="currentColor"</code>, compatible with any colour token.',
-    content: `
-
+const pageContent = `
       <h2 class="doc-h2" id="usage">Usage</h2>
       <p>Import the icon functions you need alongside other components. Call each as a function — optionally pass <code>size</code> and <code>class</code>.</p>
       ${demo(
@@ -370,8 +356,6 @@ feature({ icon: iconCode({   size: 22, bg: 'square', bgColor: 'muted'   }), titl
 
       ${iconGrid_()}
 
-      ${iconModals_()}
-
       ${table(
         ['Prop', 'Type', 'Default', 'Description'],
         [
@@ -383,6 +367,33 @@ feature({ icon: iconCode({   size: 22, bg: 'square', bgColor: 'muted'   }), titl
       )}
 
       <p style="margin-top:2rem;font-size:.8rem;color:var(--muted)">SVG paths derived from <a href="https://lucide.dev" target="_blank" rel="noopener noreferrer">Lucide</a> (ISC License, Copyright © 2022 Lucide Contributors) and <a href="https://feathericons.com" target="_blank" rel="noopener noreferrer">Feather Icons</a> (MIT License, Copyright © 2013–2017 Cole Bemis). Phosphor hand-pointer icons MIT License, Copyright © 2020 Phosphor Icons.</p>
-    `,
-  }),
+    `
+
+export default {
+  route: '/components/icons',
+  meta: {
+    title: 'Icons — Pulse Docs',
+    description: 'Built-in icon set for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+
+  // Shell: all visible content (nav, examples, icon grid) — sends immediately.
+  // Modals: 100 hidden <dialog> elements — streamed after. Users never see them
+  // arrive since dialogs are display:none until opened.
+  stream: {
+    shell:    ['page'],
+    deferred: ['modals'],
+  },
+
+  view: {
+    page: () => renderComponentPage({
+      currentHref: '/components/icons',
+      prev,
+      next,
+      name: 'icons',
+      description: '100 curated icons. All are pure functions returning an SVG string — no external library, no DOM dependency, tree-shakeable. Style: 24×24 viewBox, <code>stroke="currentColor"</code>, compatible with any colour token.',
+      content: pageContent,
+    }),
+    modals: () => iconModals_(),
+  },
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "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.2
+0.9.1

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,7 +8,7 @@
  */
 
 import { initClientStore, getStoreState, subscribe, updateStore, registerStoreMutations, dispatchStoreMutation } from './store.js'
-import { trustedHTML } from './tt.js'
+import { trustedHTML, trustedScriptURL } 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))
@@ -456,7 +456,13 @@ function morphKeyed(cur, nxtEls) {
 
 function morphAttrs(cur, nxt) {
   for (const { name, value } of Array.from(nxt.attributes)) {
-    if (cur.getAttribute(name) !== value) cur.setAttribute(name, value)
+    if (cur.getAttribute(name) !== value) {
+      // Trusted Types: script[src] is a TrustedScriptURL sink
+      const safeValue = (cur.tagName === 'SCRIPT' && name === 'src')
+        ? trustedScriptURL(value)
+        : value
+      cur.setAttribute(name, safeValue)
+    }
   }
   for (const { name } of Array.from(cur.attributes)) {
     if (!nxt.hasAttribute(name)) cur.removeAttribute(name)

package/src/runtime/tt.js

@@ -8,6 +8,16 @@
 
 let _policy = null
 
+function getPolicy() {
+  if (!_policy) {
+    _policy = window.trustedTypes.createPolicy('pulse', {
+      createHTML:      s => s,
+      createScriptURL: s => s,
+    })
+  }
+  return _policy
+}
+
 /**
  * Return a TrustedHTML object (Chromium) or the raw string (all other browsers).
  * @param {string} html
@@ -15,6 +25,16 @@ let _policy = null
  */
 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)
+  return getPolicy().createHTML(html)
+}
+
+/**
+ * Return a TrustedScriptURL object (Chromium) or the raw string (all other browsers).
+ * Used when setting the `src` attribute on <script> elements during DOM morphing.
+ * @param {string} url
+ * @returns {TrustedScriptURL|string}
+ */
+export function trustedScriptURL(url) {
+  if (typeof window === 'undefined' || !window.trustedTypes) return url
+  return getPolicy().createScriptURL(url)
 }

package/src/server/index.js

@@ -317,14 +317,17 @@ function buildCacheKey(spec, ctx) {
  *
  * A page is NOT cacheable if it has any of:
  *   - spec.server  — embeds a nonce'd __PULSE_SERVER__ inline script
- *   - spec.store   — same
- *   - spec.hydrate — embeds a nonce'd __PULSE_NONCE__ inline script (for toasts)
+ *   - spec.store              — same
+ *   - spec.hydrate            — embeds a nonce'd __PULSE_NONCE__ inline script (for toasts)
+ *   - spec.stream.deferred    — deferred segments inject content via inline <script nonce="...">
+ *                               tags; caching bakes in one nonce while subsequent CSP headers
+ *                               carry a different nonce, causing a violation
  *
- * In all three cases the cached HTML would contain a nonce that doesn't match
+ * In all these cases the cached HTML would contain a nonce that doesn't match
  * the nonce-free CSP used for cached responses, causing a CSP violation.
  */
 function isCacheablePage(spec) {
-  return !spec.server && !spec.store?.length && !spec.hydrate
+  return !spec.server && !spec.store?.length && !spec.hydrate && !spec.stream?.deferred?.length
 }
 
 // ---------------------------------------------------------------------------