@invisibleloop/pulse 0.12.2 → 0.14.1

package/.claude/commands/verify.md

@@ -42,21 +42,25 @@ 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 spec file path. This runs a full code review AND atomically writes the `.pulse-verified` stamp server-side, eliminating any race condition with the stop hook.
 
-### 10. Close the browser
+Work through every item the review returns. Fix anything that fails before proceeding.
 
-Use `mcp__chrome-devtools__list_pages` to get all open pages, then call `mcp__chrome-devtools__close_page` for every page ID returned. This closes the entire browser, not just the tab. `pageId` must be a number, not a string.
+### 10. Close extra browser tabs
+
+Use `mcp__chrome-devtools__list_pages` to get all open pages. Close every page **except the last one** — `close_page` refuses to close the final tab. `pageId` must be a number, not a string.
+
+If there is only one page open, skip this step — there is nothing to close.
 
 ### 11. Write verification stamp
 
-Run:
+`pulse_review` writes the stamp automatically. As a belt-and-suspenders backup, also run:
 
 ```bash
 date +%s > .pulse-verified
 ```
 
-This records that verify completed successfully. The stop hook checks this stamp — do not skip this step.
+This ensures the stamp is present even if `pulse_review` was not called with a file path.
 
 ### 12. Report
 

package/.claude/pulse-checklist.md

@@ -25,6 +25,20 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 ### Components first
 
 - **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:
+  - Hero sections → `hero({ title, subtitle, actions, image, ... })`
+  - Product/service cards → `card({ title, body, image, footer, ... })`
+  - Image + text two-column layouts → `media({ image, content, reverse })`
+  - Horizontal strips/banners → `banner({ content, variant })`
+  - Feature tiles → `feature({ icon, title, description })`
+  - Testimonials → `testimonial({ quote, name, role, src })`
+  - CTAs → `cta({ title, subtitle, actions })`
+  - Navigation → `nav({ logo, links, actions })`
+  - Footers → `footer({ logo, links, columns, legal, ... })`
+  
+  If you find yourself writing `class="hero"` or `class="product-card"` or `class="testimonial"`, stop — import the component instead.
+
+- **Exception — brutalist, editorial, and playful vibes:** these vibes intentionally break from polished templates. `pulse://guide/explore` explicitly endorses zone-based raw HTML for distinctive layouts. For `brutalist`, `editorial`, `retro`, or `neon` vibes, raw structural HTML is correct — components can still be used for functional atoms (`button`, `input`, `modal`) but structural sections do not need to come from components. When reviewing a brutalist or editorial spec, do not flag raw section HTML as a violation.
 
 - **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.
 
@@ -110,7 +124,13 @@ Before finishing any spec, verify every point below. Fix anything that fails.
   assert.equal(result.get('h1').text, mockProduct.name)
   assert.equal(result.attr('img', 'src'), mockProduct.image)
   ```
-  Supported selectors: `tag`, `.class`, `#id`, `[attr]`, `[attr="value"]`, and combinations (`button.primary[disabled]`).
+  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.
 
 ### Markdown
 

package/.github/workflows/publish.yml

@@ -40,5 +40,6 @@ jobs:
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git add package.json package-lock.json public/.pulse-ui-version
           git commit -m "chore: release $VERSION [skip ci]" || true
+          git pull --rebase
           git push
           npm publish --provenance --access public

package/.pulse-verified

@@ -0,0 +1 @@
+1780010184

package/CLAUDE.md

@@ -318,23 +318,30 @@ For multi-brand setups, each brand theme file just overrides `--font` in `:root`
 
 ## Overriding Theme Colours
 
-`pulse-ui.css` defines light theme variables under `[data-theme="light"]`, which has **higher specificity than `:root`**. Overrides written only to `:root` will be silently beaten by those rules.
-
-Always target `[data-theme="light"]` when overriding colours for the light theme:
+Use **input tokens** (unprefixed: `--accent`, `--bg`, `--text`, etc.) in `theme.css`. `pulse-ui.css` maps them to output tokens via `var()` in **both** the dark (`:root`) and light (`[data-theme="light"]`) blocks:
 
 ```css
-/* WRONG — loses to [data-theme="light"] rules in pulse-ui.css */
+/* Dark theme — in :root */
 :root {
-  --color-accent: #e25;
+  --accent: #9b8dff;
 }
 
-/* CORRECT */
+/* Light theme — in [data-theme="light"] */
 [data-theme="light"] {
-  --color-accent: #e25;
+  --accent: #e25;   /* overrides the light default */
 }
 ```
 
-If a colour must apply in both themes, set it in both `:root` and `[data-theme="light"]`.
+Setting `--accent` in `[data-theme="light"]` works correctly — `pulse-ui.css` resolves `var(--accent, ...)` there just like it does in `:root`.
+
+If you need to override an output token directly (e.g. one with no input equivalent), target `[data-theme="light"]` explicitly:
+
+```css
+/* Direct output token override for light theme only */
+[data-theme="light"] {
+  --ui-nav-sticky-bg: rgba(255, 255, 255, 0.95);
+}
+```
 
 ## CSS File Responsibilities
 
@@ -342,10 +349,10 @@ There are two CSS files and they have distinct roles — do not mix them:
 
 | File | Purpose | Allowed content |
 |---|---|---|
-| `public/theme.css` | Token definitions — hex values, raw colours, font URLs | Hex values, `rgb()`, raw values, `@font-face`, `@import` |
-| `app.css` (or per-page) | Layout and component overrides | `var()` tokens **only** — no hex, no raw colour values |
+| `public/theme.css` | Token definitions — hex values, raw colours, font URLs | Hex values, `rgb()`, `rgba()`, `hsl()`, `hsla()`, raw values, `@font-face`, `@import` |
+| `app.css` (or per-page) | Layout and component overrides | `var()` tokens **only** — no hex values |
 
-**`app.css` must never contain hex values or raw colour values.** A lint hook enforces this. If you need to define or override a colour token, put it in `public/theme.css` and reference it via `var()` in `app.css`.
+**`app.css` must never contain hex values.** `rgba()` and `hsla()` are allowed for translucency — but if the same translucent colour is used more than once, extract it as a token in `theme.css` (e.g. `--brand-overlay-12: rgba(0,0,0,0.12)`). If you need to define or override a colour token, put it in `public/theme.css` and reference it via `var()` in `app.css`.
 
 ```css
 /* public/theme.css — hex values live here */
@@ -422,7 +429,8 @@ const result = await render(mySpec, { server: { product: mockProduct } })
 const result = await render(mySpec, { ctx: { params: { id: '1' } } }) // real fetchers
 ```
 
-**Supported selectors:** `button`, `.class`, `#id`, `[attr]`, `[attr="value"]`, and combinations: `button.primary[type="submit"]`.
+**Supported selectors:** `button`, `.class`, `#id`, `[attr]`, `[attr="value"]`, and combinations: `button.primary[type="submit"]`. **Descendant combinators are supported:** `result.count('.parent li')` or `result.find('tbody tr')`.
+
 `Element` also has `.find()`, `.findAll()`, `.has()`, `.attr()`, `.text`, `.tag`, `.attrs`.
 
 ## Key Decisions (Do Not Reverse)
@@ -439,6 +447,25 @@ const result = await render(mySpec, { ctx: { params: { id: '1' } } }) // real fe
 
 ## Build Workflow
 
+### New page or new site? Start with intake — always
+
+For any **new page, landing page, or branded site**, run this sequence first. Do not skip to building.
+
+```
+0. pulse_extract_inspiration(url/image)       → structured design brief  [if user shares reference]
+1. pulse_intake(name, pitch, features, ...)   → product brief + contrast check
+2. pulse_sketch(brief, vibe?, antiStyle?)     → 3 layout directions to choose from
+3. pulse_intent(description)                  → archetype + scaffold + guide list
+```
+
+**Before calling `pulse_intake`**, gather the required information by asking the user — one question at a time, in plain prose, no bullet lists. You need at minimum: the product name, what it does (pitch), and its key features. Ask for inspiration references, palette, vibe, and anti-style if the user hasn't mentioned them.
+
+**`pulse_sketch` is mandatory** for `playful`, `bold`, `brutalist`, `retro`, or `neon` vibes — those vibes fight the default centred-hero layout. Skip it only for `corporate` or `minimal` when no structural preference has been stated.
+
+For **small edits, bug fixes, or "add X to existing Y"** — skip intake/sketch and go straight to Understand below.
+
+---
+
 Every build task follows this sequence. Each phase has a pass gate — do not advance until it clears.
 
 **Before calling any slow tool (`pulse_build`, `lighthouse_audit`), output a status message to the user first** — e.g. "Building for production — ~30 s…" or "Running Lighthouse desktop audit…". Never call a slow tool silently.
@@ -449,14 +476,16 @@ Every build task follows this sequence. Each phase has a pass gate — do not ad
 | 2. Plan | Present plan to user, wait for confirmation | User confirms |
 | 3. Build | Write spec + related files | — |
 | 4. Validate | `pulse_validate` — fix all errors + warnings | Clean output |
-| 5. Browser | Screenshot + Lighthouse desktop + mobile | 100/100/100 (Accessibility, Best Practices, SEO) both strategies |
+| 5. Browser | Screenshot → `pulse_design_review` (if intake ran) → `pulse_layout_review` → `/verify` (Lighthouse desktop + mobile + `pulse_review`) | ⛔ Do not skip: all gates must pass + `.pulse-verified` stamp written |
 | 6. Tests | Write tests, run them, fix failures | All pass |
-| 7. Review Agent | Invoke review — **only after phases 4–6 all pass** | — |
+| 7. Code Review | `pulse_review` — only after phases 4–6 pass | — |
 | 8. Fix | Fix every review issue, re-run affected gates | All gates still pass |
 
 **Skip phase 2 confirmation only for trivially small, unambiguous tasks.** When in doubt, confirm.
 
-**The Review Agent is always last.** Never invoke it before validate, Lighthouse, and tests all pass.
+**Template mode exception:** when adapting a pre-built template (see `pulse://guide/templates`), replace the full plan with a single compact confirmation block — template, substitutions, files. One turn is enough; do not run the full phase 2 ceremony.
+
+**The Code Review is always last.** Never invoke `pulse_review` before validate, Lighthouse, design review, and tests all pass.
 
 The `/verify` command runs the browser check loop (phases 4–5) automatically. Use it.
 
@@ -521,6 +550,18 @@ export default {
 
 Before writing any UI HTML by hand, check `src/ui/index.js` — there are 50+ components available. Use them. Do not reinvent `button`, `card`, `alert`, `modal`, `spinner`, `badge`, `input`, etc.
 
+**Common patterns with dedicated components — never write these from scratch:**
+
+- Hero sections → `hero({ title, subtitle, actions, image, layout })`
+- Product/service cards → `card({ title, body, image, footer })`
+- Image + text layouts → `media({ image, content, reverse })`
+- Horizontal strips → `banner({ content, variant })`
+- Feature tiles → `feature({ icon, title, description })`
+- Testimonials → `testimonial({ quote, name, role, src })`
+- Call-to-action sections → `cta({ title, subtitle, actions })`
+
+If you're about to write `class="hero"` or `class="product-card"`, stop — import the component instead. You can add custom CSS on top of components for brand-specific styling, but the structure and accessibility must come from the component.
+
 @src/agent/checklist.md
 
 ## Performance Baseline

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

@@ -16,6 +16,8 @@ Use `pulse_validate` with the spec file content. If validation fails, report eve
 
 Use `pulse_fetch_page` to confirm the server is responding for the route. If it errors, use `pulse_restart_server` and retry once.
 
+**If `pulse_fetch_page` returns unexpected HTML (e.g. a different project's page title, a Next.js 404, or any non-Pulse response):** check the `X-Pulse` response header — Pulse servers always send this. If it is absent, the wrong server is running on that port. Stop and inform the user before continuing.
+
 ### 4. Screenshot
 
 Use `mcp__chrome-devtools__navigate_page` to load the page route, then `mcp__chrome-devtools__take_screenshot` to capture the result. Describe what you see — layout, content, any obvious rendering issues.
@@ -32,6 +34,8 @@ Run `mcp__chrome-devtools__lighthouse_audit` on the same route with `{ "strategy
 
 **Same pass bar: Accessibility, Best Practices, and SEO must all be 100.** Fix any failures and restart from step 2.
 
+**If you need to visually inspect the layout at a mobile viewport width** (e.g. to debug a wrapping or overflow issue), use `mcp__chrome-devtools__emulate` with `viewport: "390x844x2,mobile,touch"` — not `resize_page`. The `emulate` tool reliably sets the viewport; `resize_page` does not reliably trigger responsive layout changes. Reset afterward with `emulate` using the desktop viewport: `"1440x900x1"`.
+
 ### 7. Performance
 
 Navigate to the page route, then run `mcp__chrome-devtools__performance_start_trace` with `reload: true` and `autoStop: true`. Report LCP and CLS. Flag any LCP insight that suggests a fixable problem (render-blocking resources, large image load delay, etc.).

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

@@ -20,9 +20,43 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 - **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.
 
-### Components first
+- **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 })`
+  - Horizontal strips/banners → `banner({ content, variant })`
+  - Feature tiles → `feature({ icon, title, description })`
+  - Testimonials → `testimonial({ quote, name, role, src })`
+  - 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. This is a deliberate design decision, not a shortcut. When taking this path:
+  - State it explicitly in the build brief: *"Building component-free — raw HTML throughout for creative control."*
+  - 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: **100/100/100/100 Lighthouse on both desktop and mobile is the pass bar.** A component-free page that passes every audit is correct. A component-heavy page that fails accessibility is not.
+
+- When reviewing a spec built under creative override, do not flag raw section HTML as a violation — check the Lighthouse results instead.
+
+- **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)
 
@@ -94,7 +128,7 @@ Before finishing any spec, verify every point below. Fix anything that fails.
   assert.equal(result.get('h1').text, mockProduct.name)
   assert.equal(result.attr('img', 'src'), mockProduct.image)
   ```
-  Supported selectors: `tag`, `.class`, `#id`, `[attr]`, `[attr="value"]`, and combinations (`button.primary[disabled]`).
+  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
 

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

@@ -1 +1 @@
-0.10.2
+0.13.0

package/docs/public/andypixel.css

@@ -0,0 +1,237 @@
+/*
+ * 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;
+}