@invisibleloop/pulse 0.20.10 → 0.20.19

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

@@ -1,189 +0,0 @@
-## Spec review checklist
-
-Before finishing any spec, verify every point below. Fix anything that fails.
-
-### Critical
-
-- **`meta` must be a plain object — never a function.** Individual fields (`title`, `description`, `styles`) can be `async (ctx) => value` functions, but `meta` itself is always `{}`.
-
-  ```js
-  // WRONG — meta is not a function factory
-  meta: async (ctx) => ({ title: '...', styles: [...] })
-
-  // CORRECT — meta is a plain object; individual fields are functions
-  meta: {
-    title:       async (ctx) => (await post(ctx)).frontmatter.title,
-    description: async (ctx) => (await post(ctx)).frontmatter.description,
-    styles:      ['/pulse-ui.css', '/app.css'],
-  }
-  ```
-
-- **Do not set `hydrate` in specs.** It is auto-derived by the framework from the URL entry passed to `createServer`. Specs with `mutations`, `actions`, or `persist` are hydrated automatically. Purely server-rendered specs get zero JavaScript — no configuration needed.
-
-- **The default theme is DARK.** When `meta.theme` is unset, the page renders with the dark palette. If the design calls for a light page, set `meta.theme: 'light'` when you **first write the spec** — do not assume light and discover dark at the screenshot, which costs an edit → restart → re-approval cycle. Declare the theme in your plan/build brief, and ask the user if the brief doesn't say.
-
-- **Always restart the server and reload the browser after every file edit — before checking the result.** The dev server restarts on file changes but the browser tab stays stale. The required sequence is: `pulse_restart_server` → `navigate_page`. Never attempt to debug a visual problem without doing both steps first.
-
-### Components first — or creative override
-
-- **Before writing any HTML by hand, check `src/ui/index.js`.** There are 50+ components. Use `button`, `card`, `alert`, `input`, `spinner`, `badge`, `modal`, `nav`, `pagination`, `table`, etc. before writing equivalent HTML from scratch.
-- **Do not reinvent component patterns.** These patterns have dedicated components — never write custom HTML for them unless a creative override applies (see below):
-  - Hero sections → `hero({ title, subtitle, actions, image, ... })`
-  - Product/service cards → `card({ title, body, image, footer, ... })`
-  - Image + text two-column layouts → `media({ image, content, reverse })`
-  - Feature tiles → `feature({ icon, title, description })`
-  - Testimonials → `card({ content, footer })` with quote + avatar/name in the content slot
-  - CTAs → `cta({ title, subtitle, actions })`
-  - Navigation → `nav({ logo, links, actions })`
-  - Footers → `footer({ logo, links, columns, legal, ... })`
-
-- **Creative override — raw HTML throughout is permitted** when the design intent genuinely calls for it: a highly custom visual identity, an asymmetric or typographically-driven layout, a brutalist/editorial/retro/neon/paper vibe where components would constrain the expression, or a layout that requires features a component simply doesn't support (e.g. full-viewport height, custom gradient glows, clamp-scaled display type). This is a deliberate design decision, not a shortcut. When taking this path:
-  - **Declare it in a comment at the top of the spec** so the reviewer recognises it: `// component-free — creative override: <reason>`. This is the signal the review tool reads.
-  - Functional atoms (`button`, `input`, `badge`, `modal`) should still come from components unless there is a specific design reason not to.
-  - `/pulse-ui.css` is always required — it provides the token system your custom CSS will use.
-  - The quality gate replaces the component checklist: **Lighthouse 100 on Accessibility, Best Practices, and SEO — desktop and mobile — plus CLS 0.00 is the pass bar.** (Performance is reported but not gated; it varies with machine load.) A component-free page that passes every audit is correct. A component-heavy page that fails accessibility is not.
-
-- **When reviewing**: before flagging a class name like `.hero` as a violation, first ask whether the `hero()` component could actually reproduce the layout. If the answer is no, it is a creative override — check Lighthouse instead of refactoring. Do not flatten a good custom layout into a generic component just to clear a pattern-match.
-
-- **The review tool auto-detects creative override** from the spec comment. When detected, component pattern checks are shown as advisory (`⚡`) not as failures, and the Lighthouse gate is the stated pass bar.
-
-- **Never write App Store or Google Play download buttons by hand.** Always use `appBadge({ store: 'apple', href })` and `appBadge({ store: 'google', href })`. Raw `<a>` tags with badge images are incorrect — `appBadge` renders the correct accessible, styled badge for each store.
-
-  ```js
-  import { appBadge } from '@invisibleloop/pulse/ui'
-
-  // In a hero() actions slot:
-  ${hero({
-    actions: `
-      ${appBadge({ store: 'apple',  href: 'https://apps.apple.com/...' })}
-      ${appBadge({ store: 'google', href: 'https://play.google.com/...' })}
-    `,
-  })}
-  ```
-
-### Reuse (DRY)
-
-- **Extract a view helper when the same HTML pattern appears 3 or more times in a single spec.** A plain JS function returning an HTML string is sufficient — no framework needed:
-  ```js
-  const card = ({ title, body }) => `<div class="card"><h3>${title}</h3><p>${body}</p></div>`
-  ```
-- **Create a shared component in `src/components/` when the same pattern is needed across 2 or more different specs.** A named export that returns an HTML string — same shape as the `layout()` pattern in the routing guide. Never paste a section's HTML into a second spec: extract it at the second use, then import it from both. (`src/ui/` is the framework's own library inside the package — project-level shared code always goes in `src/components/`.)
-- **Do not abstract a pattern that appears only once.** Duplication is cheaper than the wrong abstraction. Within a single spec, wait until the third use before extracting a helper; across specs, extract at the second use.
-
-### Correctness
-
-- Mutations return plain partial-state objects and have no side effects (no fetch, no DOM access).
-- `persist` contains only serialisable state that should survive a page reload — not ephemeral UI state like a loading flag or temporary selection.
-- `e.target` assumptions in mutations are safe if the element has child nodes — use `e.target.closest('[data-index]')` rather than assuming `e.target` is the element with the attribute.
-- State shape is consistent — avoid a single field that is sometimes `null`, sometimes a string, sometimes a boolean. Use a dedicated `status` field instead.
-- **Never use `state.modalOpen` or conditional modal rendering.** This destroys the `<dialog>` on every render, breaking focus, animation, and native ESC handling. Instead, always render the `<dialog>` in the DOM and use `data-dialog-open="id"` to open it — the runtime handles this without any spec state:
-  ```html
-  <!-- always in the view, never conditional -->
-  ${modal({ id: 'confirm', title: 'Confirm', content: '...' })}
-  <!-- anywhere on the page — opens the dialog, no mutation needed -->
-  ${modalTrigger({ target: 'confirm', label: 'Open' })}
-  <!-- or inline: -->
-  <button data-dialog-open="confirm">Open</button>
-  ```
-  Close is handled natively by `<form method="dialog">` (inside the modal), ESC key, backdrop click, or `data-dialog-close` on any element.
-
-### Defensive data handling
-
-- **Always check `res.ok` before parsing fetch responses.** Never call `res.json()` on a response that may have failed. Never use `await res.text()` as an error message — on a 404 or 500, this returns raw HTML which surfaces directly in toasts and error alerts. The correct pattern:
-  ```js
-  const res = await fetch('/api/...')
-  if (!res.ok) {
-    let message = `Request failed: ${res.status}`
-    try { const j = await res.json(); message = j.message || j.error || message } catch {}
-    throw new Error(message)
-  }
-  return await res.json()
-  ```
-- **Never assume the shape of data from external APIs or server fetchers.** Use optional chaining (`?.`) and nullish coalescing (`??`) at every access point. If a server fetcher can return `null`, the view must handle it — `server.user?.name ?? 'Guest'` not `server.user.name`.
-- **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.
-- **CSS for a shared section lives in the shared `app.css`, once.** Every spec that renders the section lists the same file in `meta.styles`. Never copy a CSS block into a second per-page stylesheet — two copies drift apart. Per-page stylesheets are for styles only one page uses.
-
-### Security
-
-- Any value from user input (URL params, form fields, external APIs) interpolated into view HTML must be escaped.
-- **Every `<form method="POST">` on a `submit` page includes `${server.csrf}`.** CSRF is enforced — a form without the hidden token field gets 403 on submit. Never set `csrf: false` to "fix" a 403; that disables the protection. `csrf: false` is only for endpoints with their own authentication (e.g. signed webhooks).
-- **`submit` returns `{ redirect }` after a successful mutation** (POST-redirect-GET). Rendering success directly from the POST means browser refresh resubmits the form.
-
-### Server-side forms & error pages
-
-- **Forms that must work without JavaScript use `spec.submit`** + `<form method="POST">` with `${server.csrf}` inside. Hydrated `data-action` on the same form is the enhancement, not the requirement.
-- On a validation re-render, show `server.form?.errors` and echo `server.form?.values` back into the inputs via `value=` — failed validation must not wipe what the user typed.
-- **Every site has a custom 404 page** — a spec with `route: '*'`, using the shared `layout()` so it carries the site's nav and footer. Without it, bad URLs show the framework's unbranded default.
-
-### Tests
-
-- Pure logic functions extracted from a spec (e.g. `checkResult`, `validate`, `formatPrice`) must have unit tests in a corresponding `.test.js` file.
-- **When fixing a bug, write a failing test first.** The test must reproduce the bug before the fix is applied, then pass after. This pins the behaviour so the bug cannot silently return. A fix without a regression test is incomplete.
-- **Use `renderSync` / `render` from `@invisibleloop/pulse/testing` to test view HTML output.** Do not test views with raw `html.includes()` — use the query helpers instead:
-  ```js
-  import { renderSync, render } from '@invisibleloop/pulse/testing'
-
-  // Sync — call view directly with mock state/server
-  const result = renderSync(mySpec, { state: { count: 5 }, server: { items: [] } })
-  assert(result.has('button'))
-  assert.equal(result.get('#count').text, '5')
-  assert.equal(result.count('li'), 0)
-
-  // Async — run real server fetchers (integration), or pass server to skip them
-  const result = await render(mySpec, { server: { product: mockProduct } })
-  assert.equal(result.get('h1').text, mockProduct.name)
-  assert.equal(result.attr('img', 'src'), mockProduct.image)
-  ```
-  Supported selectors: `tag`, `.class`, `#id`, `[attr]`, `[attr="value"]`, combinations (`button.primary[disabled]`), and **descendant combinators** (`result.count('.parent li')`, `result.find('tbody tr')`). Descendant selectors match the rightmost token within the ancestor context — they do not return 0 if the ancestor doesn't exist, they simply find no matching descendants.
-
-### Markdown
-
-- **Use `md()` from `@invisibleloop/pulse/md` for `.md` file content.** Never read and parse markdown manually. Pass the result's `html` to `prose()`.
-- **Call the same `md()` fetcher in both `meta` and `server`** — it caches on `ctx._mdCache` so the file is only read once per request. Do not create two separate fetchers for the same file.
-- **Always add `onViewError` on dynamic markdown routes** (routes with `:param` segments loading `.md` files). A missing file throws `{ status: 404 }` which must be caught gracefully.
-
-### View error handling
-
-- **Define `onViewError` on any page where the view could throw due to bad or missing data.** Without it, a runtime view error returns a 500 on the server and shows a generic inline message on the client. With it, the server returns 200 with your fallback HTML instead of a 500, and the client renders your fallback:
-  ```js
-  onViewError: (err, state, serverState) => `
-    <div class="u-p-4 u-text-center">
-      <p>Something went wrong. <a href="">Reload</a></p>
-    </div>
-  `
-  ```
-  Use this on pages that render data from external APIs or user-supplied content — any path where the view can encounter `null`, `undefined`, or unexpected shapes that would cause a crash. It is not required on simple pages with predictable data.
-
-### Store updates from actions
-
-- **Use `_storeUpdate` to push changes to the global store from an action.** Return it from `onSuccess` alongside the local state update — it is stripped from page state and forwarded to the store. All mounted pages that subscribe to the affected keys re-render immediately:
-  ```js
-  onSuccess: (state, theme) => ({
-    saved:        true,
-    _storeUpdate: { settings: { theme } },  // ← merged into store state
-  }),
-  ```
-  `_storeUpdate` only merges into the store — it does not appear in the page's own state. The rest of the return is merged into local state as normal. Use this instead of a full-page reload when a user action changes shared data (theme, cart count, user profile, etc.).
-
-### Accessibility
-
-- 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/examples/andypixel.css

@@ -1,237 +0,0 @@
-/*
- * andypixel.css — Andy Pixel blog article example
- *
- * Token definitions (hex values) + layout styles (var() only).
- * Orange accent palette — editorial light theme.
- */
-
-/* ─── Token definitions ──────────────────────────────────────── */
-
-[data-theme="light"] {
-  --accent:       #f97316;
-  --accent-hover: #ea6c0a;
-  --accent-dim:   #fff3e8;
-  --surface-2:    #f0f0f0;
-  --border:       #e5e5e5;
-  --muted-bg:     #f5f5f5;
-
-  /* Code block dark-shell tokens — defined here so app.css stays hex-free */
-  --ap-code-shell:      #1e1e1e;
-  --ap-code-text:       #d4d4d4;
-  --ap-btn-dark:        #1a1a1a;
-  --ap-btn-dark-hover:  #333333;
-}
-
-/* ─── Base ───────────────────────────────────────────────────── */
-
-*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
-
-body {
-  font-family: var(--ui-font, system-ui, sans-serif);
-  line-height: 1.6;
-  background: var(--ui-bg);
-  color: var(--ui-text);
-}
-
-/* ─── Contrast fixes ─────────────────────────────────────────── */
-
-/* Badge: muted on surface-2 fails WCAG AA at small size */
-.ui-badge--default {
-  color: var(--ui-text);
-}
-
-/* Inline code: accent on surface-2 fails WCAG AA */
-.ui-prose code {
-  color: var(--ui-text);
-}
-
-/* ─── Reading column ─────────────────────────────────────────── */
-
-.ap-reading-col {
-  max-width: 72ch;
-  margin-left: auto;
-  margin-right: auto;
-  padding-left: var(--ui-space-6);
-  padding-right: var(--ui-space-6);
-}
-
-/* ─── Article header ─────────────────────────────────────────── */
-
-.ap-article-header {
-  padding: var(--ui-space-12) 0 var(--ui-space-8);
-  border-bottom: 3px solid var(--ui-accent);
-  margin-bottom: var(--ui-space-10);
-}
-
-.ap-article-meta {
-  display: flex;
-  align-items: center;
-  gap: var(--ui-space-2);
-  flex-wrap: wrap;
-  margin-bottom: var(--ui-space-5);
-}
-
-.ap-article-title {
-  font-family: var(--ui-font-display, system-ui, serif);
-  font-size: clamp(2rem, 5vw, 3.25rem);
-  font-weight: 800;
-  line-height: 1.1;
-  letter-spacing: -0.02em;
-  color: var(--ui-text);
-  margin-bottom: var(--ui-space-4);
-}
-
-.ap-article-subtitle {
-  font-size: var(--ui-text-xl);
-  color: var(--ui-muted);
-  line-height: 1.55;
-  margin-bottom: var(--ui-space-6);
-  max-width: 56ch;
-}
-
-.ap-article-author-strip {
-  display: flex;
-  align-items: center;
-  gap: var(--ui-space-3);
-}
-
-/* ─── Article body ───────────────────────────────────────────── */
-
-.ap-article-body {
-  padding-bottom: var(--ui-space-12);
-}
-
-.ap-article-lead {
-  font-size: var(--ui-text-xl) !important;
-  line-height: 1.65 !important;
-  color: var(--ui-text) !important;
-}
-
-/* ─── Code block ─────────────────────────────────────────────── */
-
-.ap-code-block {
-  margin: var(--ui-space-6) 0;
-  border-radius: var(--ui-radius);
-  overflow: hidden;
-  border: 1px solid var(--ui-border);
-}
-
-.ap-code-block__header {
-  display: flex;
-  align-items: center;
-  gap: var(--ui-space-2);
-  padding: var(--ui-space-2) var(--ui-space-4);
-  background: var(--ui-text);
-  color: var(--ui-accent);
-  font-family: var(--ui-mono, monospace);
-  font-size: var(--ui-text-sm);
-}
-
-.ap-code-block__pre {
-  background: var(--ap-code-shell);
-  padding: var(--ui-space-5) var(--ui-space-6);
-  overflow-x: auto;
-  margin: 0;
-}
-
-.ap-code-block__code {
-  font-family: var(--ui-mono, monospace);
-  font-size: var(--ui-text-sm);
-  line-height: 1.75;
-  color: var(--ap-code-text);
-}
-
-/* ─── Pullquote ──────────────────────────────────────────────── */
-
-.ap-pullquote {
-  margin: var(--ui-space-8) 0;
-  padding: var(--ui-space-5) var(--ui-space-6);
-  border-left: 4px solid var(--ui-accent);
-  background: var(--accent-dim);
-  border-radius: 0 var(--ui-radius) var(--ui-radius) 0;
-}
-
-.ap-pullquote p {
-  font-family: var(--ui-font-display, system-ui, serif);
-  font-size: var(--ui-text-xl);
-  font-style: italic;
-  color: var(--ui-text);
-  margin: 0;
-  line-height: 1.55;
-}
-
-/* ─── Author bio ─────────────────────────────────────────────── */
-
-.ap-author-bio-wrap {
-  border-top: 1px solid var(--ui-border);
-  border-bottom: 1px solid var(--ui-border);
-  padding: var(--ui-space-8) 0;
-  margin-bottom: var(--ui-space-10);
-}
-
-.ap-author-bio {
-  display: flex;
-  gap: var(--ui-space-4);
-  align-items: flex-start;
-}
-
-.ap-author-bio__name {
-  font-weight: 700;
-  font-size: var(--ui-text-base);
-  margin-bottom: var(--ui-space-1);
-}
-
-/* ─── Newsletter ─────────────────────────────────────────────── */
-
-.ap-newsletter-section {
-  max-width: 540px;
-  margin: 0 auto;
-  text-align: center;
-  padding: var(--ui-space-12) var(--ui-space-6);
-  border-top: 3px solid var(--ui-accent);
-}
-
-.ap-newsletter-eyebrow {
-  font-family: var(--ui-mono, monospace);
-  font-size: var(--ui-text-sm);
-  text-transform: uppercase;
-  letter-spacing: 0.1em;
-  color: var(--ui-text);
-  margin-bottom: var(--ui-space-2);
-}
-
-.ap-newsletter-title {
-  font-family: var(--ui-font-display, system-ui, serif);
-  font-size: clamp(1.5rem, 4vw, 2.25rem);
-  font-weight: 800;
-  letter-spacing: -0.02em;
-  color: var(--ui-text);
-  margin-bottom: var(--ui-space-3);
-  line-height: 1.15;
-}
-
-.ap-newsletter-form {
-  display: flex;
-  gap: var(--ui-space-2);
-  margin-top: var(--ui-space-6);
-  flex-wrap: wrap;
-  justify-content: center;
-}
-
-/* Orange bg on small text fails WCAG AA — use near-black for contrast (15:1) */
-.ap-newsletter-form .ui-btn--primary {
-  background: var(--ap-btn-dark);
-}
-.ap-newsletter-form .ui-btn--primary:hover {
-  background: var(--ap-btn-dark-hover);
-}
-
-.ap-newsletter-error {
-  color: var(--ui-error, #dc2626);
-  margin-top: var(--ui-space-3);
-}
-
-.ap-newsletter-success {
-  padding: var(--ui-space-12) var(--ui-space-6);
-  text-align: center;
-}