@invisibleloop/pulse 0.17.0 → 0.17.2

package/.claude/commands/build-page.md

@@ -50,7 +50,7 @@ Check for:
 - Layout looks correct
 - No console errors via `mcp__chrome-devtools__list_console_messages`
 
-Then ask the user: "Happy with the design and layout, or would you like any changes before I run tests and Lighthouse?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — run tests and Lighthouse", "I'd like some changes first"]`; otherwise ask in plain prose.
+Then **call `pulse_await_approval`** and ask the user: "Happy with the design and layout, or would you like any changes before I run tests and Lighthouse?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — run tests and Lighthouse", "I'd like some changes first"]`; otherwise ask in plain prose. Always call the tool before asking, whichever way you ask: in some hosts (including Claude Code) even a question tool ends the turn and fires the Stop hooks; the marker is harmless if the turn doesn't end. If a `VERIFY REQUIRED` stop-hook block fires while your question is unanswered, that is not permission to continue — call `pulse_await_approval`, re-ask, and end your turn.
 
 **Do not proceed to step 7 until the user explicitly confirms.** If they want changes, make them and return to step 6.
 

package/.claude/commands/verify.md

@@ -15,8 +15,8 @@ If $ARGUMENTS is provided, use it as the file path or route. Otherwise, identify
 If this is a new page build (came through `pulse_intake` or `build-page`):
 
 1. Take a screenshot and describe what you see to the user.
-2. Ask the user: "Happy with the design and layout, or would you like any changes before I run Lighthouse?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — proceed", "I'd like some changes first"]`; otherwise ask in plain prose.
-3. **Do not proceed to step 3 until the user explicitly confirms.** If they want changes, stop here, make the changes, then restart from step 2. Lighthouse takes ~90 seconds — do not waste it on a design the user hasn't approved.
+2. **Call `pulse_await_approval` first**, then ask the user: "Happy with the design and layout, or would you like any changes before I run Lighthouse?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — proceed", "I'd like some changes first"]`; otherwise ask in plain prose. Always call the tool before asking, whichever way you ask: in some hosts (including Claude Code) even a question tool ends the turn and fires the Stop hooks. The marker is harmless if the turn doesn't end — it is consumed when the user replies.
+3. **Do not proceed to step 3 until the user explicitly confirms.** If they want changes, stop here, make the changes, then restart from step 2. Lighthouse takes ~90 seconds — do not waste it on a design the user hasn't approved. If a `VERIFY REQUIRED` stop-hook block fires while your question is unanswered, that is not permission to continue — call `pulse_await_approval`, re-ask, and end your turn.
 
 ### 3. Validate the spec
 
@@ -46,7 +46,7 @@ The browser should still be on `http://localhost:3001/` from step 6. Run `mcp__c
 
 **Same pass bar: Accessibility, Best Practices, and SEO must all be 100.** Fix any failures and restart from step 3.
 
-After both Lighthouse runs pass, call `pulse_restart_server` to return to the dev server.
+**Stay on the production server (port 3001)** — steps 8 and 9 use it too. Do not call `pulse_restart_server` yet.
 
 ### 8. Mobile layout check
 
@@ -54,7 +54,7 @@ Emulate a mobile viewport and take a screenshot to catch wrapping, overflow, and
 
 ```
 mcp__chrome-devtools__emulate  viewport: "390x844x2,mobile,touch"
-mcp__chrome-devtools__navigate_page  url: "http://localhost:3000/"
+mcp__chrome-devtools__navigate_page  url: "http://localhost:3001/"
 mcp__chrome-devtools__take_screenshot
 ```
 
@@ -72,7 +72,9 @@ mcp__chrome-devtools__emulate  viewport: "1440x900x1"
 
 ### 9. 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.).
+**Run the trace against the production server, not dev.** Navigate to `http://localhost:3001/<route>` first — if the production server is no longer running, run `pulse_build` again. Tracing the dev server (port 3000) reports misleading LCP/CLS. 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.).
+
+After the trace, call `pulse_restart_server` to return to the dev server.
 
 ### 10. Console errors
 

package/.claude/pulse-checklist.md

@@ -20,6 +20,8 @@ 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.
 
+- **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
@@ -66,8 +68,8 @@ Before finishing any spec, verify every point below. Fix anything that fails.
   ```js
   const card = ({ title, body }) => `<div class="card"><h3>${title}</h3><p>${body}</p></div>`
   ```
-- **Create a shared component in `src/ui/` when the same pattern is needed across 2 or more different specs.** Follow the existing pattern: a named export that returns an HTML string.
-- **Do not abstract a pattern that appears only once.** Duplication is cheaper than the wrong abstraction. Wait until the third use before extracting.
+- **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
 
@@ -106,6 +108,7 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 - **`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
 

package/CLAUDE.md

@@ -6,7 +6,7 @@ Pulse is a spec-first frontend framework. The spec is the source of truth. No co
 
 ```bash
 npm run dev    # start dev server at http://localhost:3000 (pulse_build serves production on 3001)
-npm test       # run all 92 unit tests
+npm test       # run the full unit test suite
 npm run build  # bundle for production → public/dist/
 ```
 
@@ -37,6 +37,8 @@ public/
 
 A spec is a plain JS object. Every property is optional except `route` and `view`. `state` defaults to `{}` — omit it on purely server-rendered pages.
 
+**One spec = one page = one file.** A site is multiple specs, one per route. A dynamic route (`route: '/blog/:slug'`) is still a single spec serving every matching URL — never one spec per item, and never several pages folded into one spec with `ctx` conditionals. Shared sections live in `src/components/` and are imported by each spec.
+
 ```js
 export const mySpec = {
   route:   '/path',           // URL pattern, supports :params
@@ -45,6 +47,8 @@ export const mySpec = {
     title:       'Page Title',
     description: 'Meta description',
     styles:      ['/pulse.css'],
+    theme:       'light',        // 'light' | 'dark' — ⚠ default is DARK when unset; decide at write time
+    vibe:        'minimal',      // optional preset: radius, weight, spacing
     ogTitle:     '...',
     ogImage:     '...',
   },
@@ -360,6 +364,8 @@ There are two CSS files and they have distinct roles — do not mix them:
 
 **`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 for a section used by more than one spec 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. Per-page stylesheets are only for styles a single page uses.
+
 ```css
 /* public/theme.css — hex values live here */
 [data-theme="light"] {
@@ -464,7 +470,7 @@ For any **new page, landing page, or branded site**, run this sequence first. Do
 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. **Always ask first whether they have design inspiration** (a site they love, a screenshot, a mood board — dropped into `public/intake/` or pasted as a URL), and check `public/intake/` for images already there. Then ask for palette, vibe, and anti-style if not mentioned.
+**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. **Always ask first whether they have design inspiration** (a site they love, a screenshot, a mood board — dropped into `public/intake/` or pasted as a URL), and check `public/intake/` for images already there. Then ask for palette, **theme (light or dark — Pulse defaults to dark when unset)**, vibe, and anti-style if not mentioned.
 
 **`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.
 

package/README.md

@@ -7,7 +7,6 @@ Write a plain JavaScript object that describes what a page does. Pulse handles r
 ```js
 export default {
   route: '/counter',
-  hydrate: '/src/pages/counter.js',
   meta: {
     title: 'Counter',
     styles: ['/app.css'],
@@ -54,7 +53,7 @@ Full documentation: **[pulseframework.dev](https://pulseframework.dev)**
 
 **The spec is the source of truth.** Every page is a single JS object — data fetching, state, mutations, async actions, and view all in one place. No separate files for routes, controllers, or templates.
 
-**Performance is built in.** Streaming SSR, immutable asset caching, and zero layout shift are automatic. Every scaffolded project targets Lighthouse 100 across all four categories.
+**Performance is built in.** Streaming SSR, immutable asset caching, and zero layout shift are automatic. Every scaffolded project targets Lighthouse 100 for Accessibility, Best Practices, and SEO — and is fast by design (streaming HTML before data resolves, CLS 0.00).
 
 **No client-side dependencies.** Pulse ships no runtime framework to the browser — only a small hydration bundle (~2 kB brotli) that binds your spec's mutations and actions to the DOM.
 
@@ -83,12 +82,13 @@ Full reference at [pulseframework.dev](https://pulseframework.dev):
 - **Guard** — authentication and authorisation before data fetches
 - **Validation & constraints** — declarative form validation and state bounds
 - **Raw responses** — RSS feeds, sitemaps, JSON APIs
+- **Markdown** — built-in parser for blog posts and docs pages, zero browser JS
 - **Performance** — how the framework hits Lighthouse 100
 - **UI components** — 50+ built-in components
 
 ## Status
 
-This is an early-access release. The core architecture is stable and production-quality, but the API may evolve before v1. Feedback and issues welcome on [GitHub](https://github.com/invisibleloop/pulse).
+This is an early-access release. The core architecture is stable and production-quality, but the API may evolve before v1. Feedback and issues welcome on [GitHub](https://github.com/invisibleloop/pulse-framework).
 
 ## License
 

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

@@ -20,6 +20,8 @@ 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.
 
+- **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
@@ -66,8 +68,8 @@ Before finishing any spec, verify every point below. Fix anything that fails.
   ```js
   const card = ({ title, body }) => `<div class="card"><h3>${title}</h3><p>${body}</p></div>`
   ```
-- **Create a shared component in `src/ui/` when the same pattern is needed across 2 or more different specs.** Follow the existing pattern: a named export that returns an HTML string.
-- **Do not abstract a pattern that appears only once.** Duplication is cheaper than the wrong abstraction. Wait until the third use before extracting.
+- **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
 
@@ -106,6 +108,7 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 - **`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
 

package/docs/public/pulse-ui.css

@@ -4031,8 +4031,14 @@ fieldset[disabled] .ui-rating-stars .ui-rating-star:hover ~ .ui-rating-star { co
 }
 
 .ui-drop-cap-letter {
-  font-weight: 700;
-  color:       var(--ui-text);
+  /* line-height ~cap height keeps the float box hugging the glyph so the cap
+     top-aligns with the first text line — a relative line-height makes serif
+     caps float below the opening line. Component sets font-size inline. */
+  float:        left;
+  font-weight:  700;
+  line-height:  0.82;
+  margin-right: 0.1em;
+  color:        var(--ui-text);
 }
 
 /* Colophon — minimal footer for editorial pages */

package/docs/src/pages/project-structure.js

@@ -82,6 +82,8 @@ export default {
       ${section('one-file-per-page', 'One file per page')}
       <p>Pulse enforces <strong>one spec per file</strong>. Every page is self-contained — state, view, mutations, actions, and validation in one place. This is not a style preference. It is how the framework eliminates the question of where things live.</p>
 
+      <p>This holds for dynamic routes too: <code>route: '/blog/:slug'</code> is <strong>one spec serving every matching URL</strong> — the <code>:param</code> does the multiplying, so a thousand blog posts are still a single file. A site is therefore a small collection of specs, one per route, sharing layouts and sections from <code>src/components/</code> rather than repeating them.</p>
+
       ${callout('tip', 'For large pages, view fragments and helpers can be imported from other modules. The spec file remains the coordination point — the structure is always clear regardless of how the implementation is organised.')}
     `,
   }),

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

@@ -20,6 +20,8 @@ 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.
 
+- **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
@@ -66,8 +68,8 @@ Before finishing any spec, verify every point below. Fix anything that fails.
   ```js
   const card = ({ title, body }) => `<div class="card"><h3>${title}</h3><p>${body}</p></div>`
   ```
-- **Create a shared component in `src/ui/` when the same pattern is needed across 2 or more different specs.** Follow the existing pattern: a named export that returns an HTML string.
-- **Do not abstract a pattern that appears only once.** Duplication is cheaper than the wrong abstraction. Wait until the third use before extracting.
+- **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
 
@@ -106,6 +108,7 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 - **`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
 

package/examples/public/pulse-ui.css

@@ -150,6 +150,20 @@ html, body {
   color:      var(--ui-text);
 }
 
+/* ghost-light — use on dark section backgrounds (e.g. navy hero, section--dark).
+   Renders with light/white text and a subtle light border so it remains legible
+   regardless of whether the surrounding theme is light or dark.               */
+.ui-btn--ghost-light {
+  background:   transparent;
+  color:        rgba(255, 255, 255, 0.9);
+  border:       1px solid rgba(255, 255, 255, 0.35);
+}
+.ui-btn--ghost-light:hover:not(.ui-btn--disabled):not([disabled]) {
+  background:   rgba(255, 255, 255, 0.1);
+  border-color: rgba(255, 255, 255, 0.65);
+  color:        #ffffff;
+}
+
 .ui-btn--danger {
   background: var(--ui-red-dim);
   color:      var(--ui-red);
@@ -682,6 +696,36 @@ html, body {
 .ui-section--alt   { background: var(--ui-surface,   var(--surface,   #111116)); }
 .ui-section--dark  { background: var(--ui-surface-2, var(--surface-2, #18181f)); }
 
+/* In light theme, --ui-surface-2 resolves to a light grey — not "dark".
+   Override so section--dark always renders a genuinely dark background that
+   contrasts with the page, regardless of the active theme.                  */
+[data-theme="light"] .ui-section--dark,
+.ui-theme-light .ui-section--dark {
+  background:  var(--ui-dark-bg,  #1a1a2e);
+  color:       var(--ui-dark-text, #e2e2ea);
+}
+/* Ensure text children inherit the light colour in the dark section */
+[data-theme="light"] .ui-section--dark .ui-section-title,
+[data-theme="light"] .ui-section--dark .ui-section-eyebrow,
+[data-theme="light"] .ui-section--dark .ui-section-subtitle,
+.ui-theme-light .ui-section--dark .ui-section-title,
+.ui-theme-light .ui-section--dark .ui-section-eyebrow,
+.ui-theme-light .ui-section--dark .ui-section-subtitle {
+  color: inherit;
+}
+/* Ghost button inside a dark section on a light-theme page */
+[data-theme="light"] .ui-section--dark .ui-btn--ghost,
+.ui-theme-light .ui-section--dark .ui-btn--ghost {
+  color:        var(--ui-dark-text, #e2e2ea);
+  border-color: rgba(226, 226, 234, 0.35);
+}
+[data-theme="light"] .ui-section--dark .ui-btn--ghost:hover:not(.ui-btn--disabled):not([disabled]),
+.ui-theme-light .ui-section--dark .ui-btn--ghost:hover:not(.ui-btn--disabled):not([disabled]) {
+  background:   rgba(226, 226, 234, 0.1);
+  border-color: rgba(226, 226, 234, 0.65);
+  color:        var(--ui-dark-text, #e2e2ea);
+}
+
 /* diagonal — tapered bottom edge; follow with a section that starts flush */
 .ui-section--diagonal {
   background: var(--ui-surface, var(--surface, #111116));
@@ -3987,8 +4031,14 @@ fieldset[disabled] .ui-rating-stars .ui-rating-star:hover ~ .ui-rating-star { co
 }
 
 .ui-drop-cap-letter {
-  font-weight: 700;
-  color:       var(--ui-text);
+  /* line-height ~cap height keeps the float box hugging the glyph so the cap
+     top-aligns with the first text line — a relative line-height makes serif
+     caps float below the opening line. Component sets font-size inline. */
+  float:        left;
+  font-weight:  700;
+  line-height:  0.82;
+  margin-right: 0.1em;
+  color:        var(--ui-text);
 }
 
 /* Colophon — minimal footer for editorial pages */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",
@@ -57,7 +57,7 @@
   "scripts": {
     "dev": "node --watch src/cli/dev.js",
     "build": "node scripts/build.js",
-    "test": "node src/spec/schema.test.js && node src/runtime/runtime.test.js && node src/runtime/navigate.test.js && node src/runtime/morph.test.js && node src/runtime/ssr.test.js && node src/runtime/image.test.js && node src/server/server.test.js && node src/cli/cli.test.js && node src/ui/ui.test.js && node src/testing/testing.test.js && node src/store/store.test.js && node src/md/md.test.js && node scripts/strip-server.test.js && node src/mcp/mcp.test.js",
+    "test": "node src/spec/schema.test.js && node src/runtime/runtime.test.js && node src/runtime/navigate.test.js && node src/runtime/morph.test.js && node src/runtime/ssr.test.js && node src/runtime/image.test.js && node src/server/server.test.js && node src/cli/cli.test.js && node src/ui/ui.test.js && node src/testing/testing.test.js && node src/store/store.test.js && node src/md/md.test.js && node scripts/strip-server.test.js && node scripts/css-purge.test.js && node src/mcp/mcp.test.js",
     "typecheck": "tsc --noEmit",
     "docs": "node --watch src/cli/dev.js --root docs --port 4000",
     "docs:start": "node docs/server.js"

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.17.0
+0.17.2

package/public/pulse-ui.css

@@ -4031,8 +4031,14 @@ fieldset[disabled] .ui-rating-stars .ui-rating-star:hover ~ .ui-rating-star { co
 }
 
 .ui-drop-cap-letter {
-  font-weight: 700;
-  color:       var(--ui-text);
+  /* line-height ~cap height keeps the float box hugging the glyph so the cap
+     top-aligns with the first text line — a relative line-height makes serif
+     caps float below the opening line. Component sets font-size inline. */
+  float:        left;
+  font-weight:  700;
+  line-height:  0.82;
+  margin-right: 0.1em;
+  color:        var(--ui-text);
 }
 
 /* Colophon — minimal footer for editorial pages */

package/scripts/build.js

@@ -20,6 +20,7 @@ import { createHash } from 'crypto'
 import { discoverPages } from '../src/cli/discover.js'
 import { renderToString } from '../src/runtime/ssr.js'
 import { c, header, table, ok, fail, info, warn, elapsed, icon } from '../src/cli/fmt.js'
+import { extractUsedClasses, purgeCss, minifyCss } from './css-purge.js'
 
 // ---------------------------------------------------------------------------
 // Server-only property stripping
@@ -783,207 +784,3 @@ async function purgeCssStep(pages, manifest, root, outDir) {
   fs.writeFileSync(path.join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2))
   return cssStats
 }
-
-// ---------------------------------------------------------------------------
-// CSS class extractor
-// ---------------------------------------------------------------------------
-
-function extractUsedClasses(htmlContents, jsContents, safelist = []) {
-  const used = new Set()
-
-  // Extract from class="..." in both rendered HTML and JS template literals
-  for (const content of [...htmlContents, ...jsContents]) {
-    const re = /class(?:Name)?=["']([^"'\n]+)["']/g
-    let m
-    while ((m = re.exec(content)) !== null) {
-      for (const cls of m[1].trim().split(/\s+/)) {
-        if (cls) used.add(cls)
-      }
-    }
-  }
-
-  // Scan JS source for quoted strings that look like CSS class names (contain hyphens)
-  // Catches conditionally-applied classes like 'ui-btn--disabled' in ternaries
-  for (const js of jsContents) {
-    const re = /['"`]((?:[a-zA-Z][a-zA-Z0-9]*-[a-zA-Z0-9-]*)(?:\s+[a-zA-Z][a-zA-Z0-9-]*)*)['"`]/g
-    let m
-    while ((m = re.exec(js)) !== null) {
-      for (const cls of m[1].trim().split(/\s+/)) {
-        if (cls && cls.includes('-')) used.add(cls)
-      }
-    }
-  }
-
-  // Apply safelist from pulse.config.js — css.safelist accepts strings or RegExp.
-  // String entries are added directly; RegExp entries are matched against all
-  // class names defined in the CSS (resolved later in purgeCss via selectorUsed
-  // because we don't have the CSS text here). To handle RegExp, we mark them as
-  // a sentinel that selectorUsed checks separately.
-  for (const entry of safelist) {
-    if (typeof entry === 'string') {
-      used.add(entry)
-    }
-    // RegExp entries are stored on the Set as a symbol property for selectorUsed to check
-  }
-  if (safelist.some(e => e instanceof RegExp)) {
-    used._safelistPatterns = safelist.filter(e => e instanceof RegExp)
-  }
-
-  return used
-}
-
-// ---------------------------------------------------------------------------
-// CSS purger — strips unused rules, preserves @media / :root / element rules
-// ---------------------------------------------------------------------------
-
-/**
- * Parse CSS text into top-level blocks using a bracket-depth counter.
- * Returns [{ type, selector?, prelude?, inner?, raw }]
- */
-function parseCssBlocks(css) {
-  const blocks = []
-  let i = 0
-  const len = css.length
-
-  while (i < len) {
-    // Skip whitespace
-    while (i < len && /\s/.test(css[i])) i++
-    if (i >= len) break
-
-    // Skip block comments
-    if (css[i] === '/' && css[i + 1] === '*') {
-      const end = css.indexOf('*/', i + 2)
-      i = end === -1 ? len : end + 2
-      continue
-    }
-
-    const start = i
-    let depth = 0
-
-    while (i < len) {
-      // Skip inline comments
-      if (css[i] === '/' && css[i + 1] === '*') {
-        const end = css.indexOf('*/', i + 2)
-        i = end === -1 ? len : end + 2
-        continue
-      }
-      if (css[i] === '{') { depth++; i++; continue }
-      if (css[i] === '}') { depth--; i++; if (depth === 0) break; continue }
-      if (css[i] === ';' && depth === 0) { i++; break }
-      i++
-    }
-
-    const raw = css.slice(start, i).trim()
-    if (!raw) continue
-
-    if (raw.startsWith('@')) {
-      const braceIdx = raw.indexOf('{')
-      if (braceIdx === -1) {
-        blocks.push({ type: 'at-simple', raw })
-      } else {
-        const prelude = raw.slice(0, braceIdx).trim()
-        const inner   = raw.slice(braceIdx + 1, raw.lastIndexOf('}')).trim()
-        blocks.push({ type: 'at-block', prelude, inner, raw })
-      }
-    } else {
-      const braceIdx = raw.indexOf('{')
-      if (braceIdx !== -1) {
-        blocks.push({ type: 'rule', selector: raw.slice(0, braceIdx).trim(), raw })
-      }
-    }
-  }
-
-  return blocks
-}
-
-/**
- * Return true if any selector in the rule should be kept.
- *
- * Matching strategy: check the *rightmost* class token in the selector (the
- * subject of the rule). A rule like `.parent .child` should survive only when
- * `.child` is used — keeping it whenever `.parent` is used would retain dead
- * rules whose actual target class was never referenced.
- *
- * Pseudo-classes/elements and attribute selectors are stripped before checking
- * so `.btn:hover` is treated as `.btn`, `.btn--active::before` as `.btn--active`.
- *
- * Element-only selectors (`a`, `*`, `:root`) and rules that contain no class
- * tokens at all are always kept.
- */
-function selectorUsed(selector, usedClasses) {
-  const selectors = selector.split(',').map(s => s.trim())
-
-  for (const sel of selectors) {
-    // Strip pseudo-classes/elements and attribute selectors to find the base
-    const base = sel
-      .replace(/::?[a-z-]+(\([^)]*\))?/gi, '')
-      .replace(/\[[^\]]*\]/g, '')
-      .trim()
-
-    // Keep element-only selectors — no class tokens present
-    if (!base.includes('.')) return true
-
-    // Extract all class tokens and check the rightmost one (the rule subject).
-    // Using the rightmost class correctly handles descendant selectors:
-    //   .nav .link  → subject is .link
-    //   .btn--active → subject is .btn--active
-    const classes = [...base.matchAll(/\.([a-zA-Z][a-zA-Z0-9_-]*)/g)].map(m => m[1])
-    if (classes.length === 0) return true
-    const subject = classes[classes.length - 1]
-    if (usedClasses.has(subject)) return true
-
-    // Check RegExp safelist patterns if any were provided
-    const patterns = usedClasses._safelistPatterns
-    if (patterns && patterns.some(re => re.test(subject))) return true
-  }
-
-  return false
-}
-
-/**
- * Purge unused CSS rules from a CSS string.
- * Recursively processes @media and @supports blocks.
- */
-function minifyCss(css) {
-  return css
-    .replace(/\/\*[\s\S]*?\*\//g, '')   // strip comments
-    .replace(/\s+/g, ' ')               // collapse whitespace
-    // Remove spaces around safe punctuation — NOT + or - (would break calc() expressions)
-    .replace(/\s*([{}:;,>~])\s*/g, '$1')
-    .replace(/;}/g, '}')                // remove trailing semicolons
-    .trim()
-}
-
-function purgeCss(cssText, usedClasses) {
-  const blocks = parseCssBlocks(cssText)
-  const kept   = []
-
-  for (const block of blocks) {
-    if (block.type === 'at-simple') {
-      kept.push(block.raw)
-    } else if (block.type === 'at-block') {
-      const p = block.prelude.toLowerCase()
-      if (/^@(?:keyframes|font-face|charset)/.test(p)) {
-        kept.push(block.raw)
-      } else if (/^@(?:media|supports)/.test(p)) {
-        const innerPurged = purgeCss(block.inner, usedClasses)
-        if (innerPurged.trim()) kept.push(`${block.prelude} {\n${innerPurged}\n}`)
-      } else if (/^@layer/.test(p)) {
-        // Always preserve empty @layer declarations — they establish cascade order
-        // and removing them silently changes specificity even when no rules remain.
-        const innerPurged = purgeCss(block.inner, usedClasses)
-        if (innerPurged.trim()) {
-          kept.push(`${block.prelude} {\n${innerPurged}\n}`)
-        } else {
-          kept.push(`${block.prelude} {}`)
-        }
-      } else {
-        kept.push(block.raw) // unknown at-blocks — keep to be safe
-      }
-    } else if (block.type === 'rule') {
-      if (selectorUsed(block.selector, usedClasses)) kept.push(block.raw)
-    }
-  }
-
-  return kept.join('\n\n')
-}